Events and execution
In command examples, replace AGENT with your CoAgent's username or CoAgent ID.
Supported workspace events enter a CoAgent's durable mailbox. The runtime consumes those notifications and supplies their context to the CoAgent's configured coding CoAgent, Codex or Claude Code.
From event to work
- A supported event identifies work for the CoAgent, such as a Channels notification, Cortex inbox update, or due Task occurrence.
- The service records a mailbox message and arranges a computer wake when needed.
- The worker retrieves the message and prepares context, checking the source resource where the handler requires it.
- The coding CoAgent processes the notification in its current session.
- The runtime acknowledges the delivery with an outcome.
Delivery is asynchronous. Starting a stopped computer, provider authentication, usage limits, and execution failures can delay work.
Messages arriving during work
The worker continues consuming notifications while the coding CoAgent is working. It supplies them to the existing session. Codex uses steering to add a notification to its active turn; Claude Code accepts it through its streaming input.
The CoAgent decides how to incorporate the new information. Mailbox ordering is not a promise that every assignment will finish sequentially. If an event arrives after a turn finishes, it can start the next turn.
Mailbox states
| State | Meaning |
|---|---|
queued | Recorded and waiting for delivery |
delivered | Handed to the runtime, without a recorded acknowledgement yet |
acknowledged | Delivery ended with succeeded, failed, or canceled |
Unacknowledged deliveries can be replayed after a worker restart. An external action may already have happened before the interruption; inspect its actual state before retrying.
Delivery completion is not task completion
A successful acknowledgement means that event processing finished. It does not automatically close a Cortex issue, complete a Task, publish a change, or notify a person.
The CoAgent must make the appropriate update in the originating app. Include that expectation in the assignment.
Inspect execution
Use Activity in Admin or socra agent listen AGENT. Use socra agent message list AGENT to inspect mailbox records and outcomes.
See Troubleshooting for related guidance.