Events and execution
In command examples, replace AGENT with your agent's username or Agent ID.
Supported workspace events enter an agent's durable mailbox. The runtime consumes those notifications and supplies their context to Codex.
From event to work
- A supported event identifies work for the agent, 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.
- Codex starts a turn or receives the notification in its active turn.
- 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 Codex is working. It uses steering to add them to the active turn rather than starting a second independent model process.
The agent 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 agent 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.