Session Orchestration
Wait for session state and coordinate governed child sessions through CLI, HTTP, UDS, and native tools.
10 min read16 pages in Sessions
CompozyOS exposes session orchestration through the CLI, matching HTTP/UDS routes, and scoped native tools. Use these surfaces to wait on state, spawn bounded children, resolve their interactions, cancel one prompt, or stop a session without polling the catalog.
Wait for state
compozy session wait returns when a session reaches any requested state:
compozy session wait sess_1234 \
--until waiting-for-input,waiting-for-auth,stopped,failed \
--timeout 2m \
-o jsonWhen --until is omitted, the target set is waiting-for-input, waiting-for-auth, idle,
stopped, and failed. done satisfies idle. Explicit targets may also include done, running,
hung, unhealthy, and needs-attention. Include needs-attention when an unverified stop should wake the caller for a retry.
The default timeout is 5 minutes. --unbounded keeps the CLI waiting through gapless, bounded server
requests; the daemon never holds an unbounded HTTP/UDS request. Structured outcomes are
state-reached, timeout, session-gone, canceled, and overflow.
| Outcome or error | CLI exit |
|---|---|
| State reached | 0 |
| Invalid target | 65 |
| Session unavailable | 69 |
| Timeout | 75 |
HTTP and UDS use
POST /api/workspaces/{workspace_id}/sessions/{session_id}/wait with required timeout_ms from 1
through 1,800,000. A timeout is a normal result; a deleted or replaced session returns 410.
Cancel an active prompt
Cancel the prompt without stopping the session:
compozy session prompt-cancel sess_1234 -o jsonThe result is canceled with its turn_id, or nothing-in-flight. Repeating the command is safe and
uses the same cancellation path as
POST /api/workspaces/{workspace_id}/sessions/{session_id}/prompt/cancel and the native tool. The CLI
exits 0 after a cancel and 66 when there was nothing to cancel.
Messages between sessions
Agents use compozy__session_prompt to address another session. Supply session_id, message_id,
idempotency_key, and the message or attachments. Choose mode: "queue", "steer", or
"interrupt" when the target is busy; without mode, session.busy_input.default_mode applies
(steer by default). Retry with the same message and idempotency IDs. Every message costs the
receiver a full turn, so send at milestones instead of streaming status updates.
For a long-running receiver, prefer steer for anything it must see soon; queue only waits for the end
of its current turn, which can be long. Set supersede: true on a status update so only your latest one
stays queued; a superseding steer also cancels your older queued messages.
CompozyOS stamps an immutable origin from the calling agent session. Queue and event responses
include kind: "session", session_id, workspace_id, hop, and optional agent_name,
title_at_send, notify_on_complete, reply_watch_id, and in_reply_to. The origin survives all
delivery modes and daemon restarts. It cannot be supplied through a request body. HTTP prompts
without daemon-validated agent identity headers remain unattributed operator input.
compozy session prompt sends operator input unless you opt in. Pass --from-session auto inside a
managed session to send with the daemon-issued COMPOZY_SESSION_ID and COMPOZY_AGENT identity, so
the message carries that session's origin exactly like the native tool: the receiver sees who sent it
and can reply. Pass --from-session <id> to name a session explicitly. Without the flag, a prompt run
inside a managed session stays operator input and prints a one-line hint on stderr; sending as the
session becomes the default in a later release. The daemon validates the named session like any agent
identity, but the identity is a local, trusted session-ID header: it does not protect against a local
operator who names another session. An origin-stamped CLI prompt follows the same self-target, hop,
rate, and workspace rules as the native tool, and loses operator-only behavior (interrupt, slash
commands, operator priority). --steer keeps sending operator input. --in-reply-to and
--supersede require a sending session: without --from-session the CLI refuses them, and HTTP and
the native tool return invalid_request for a caller without an agent session.
The receiving provider sees a one-line sender header followed by the message. The header does not
become stored message text. Without a reply watch, it tells the recipient to answer by calling
compozy__session_prompt with the sender's session ID. Set notify_on_complete: true to request the
reply-watch flow from an agent session. Without it, nobody is woken when the receiver finishes.
Changing that flag on a retry conflicts, as does retrying another sender's message identity. A sender
rename preserves the original admission.
To answer a specific message, pass its message ID as in_reply_to (--in-reply-to on the CLI). It is
carried in the origin, so the receiver's card can link the answer to the original. An explicit answer
never releases the original sender's reply watch: an early "ack, starting" must not cancel the
completion wake, so a sender that asked for notify_on_complete still gets the final answer when your
turn ends. An unanswered watch expires after session.messaging.reply_watch_ttl (24 hours by
default) with the expired outcome and stops keeping the sender awake; set it to "0s" to let a watch
wait for as long as the target works.
An operator can cancel an agent-authored queued message or promote it to steer (Steer on its queue
row in the Web UI), but cannot replace its text: that returns HTTP 409 input_agent_authored.
When the receiver is busy, the order is operator input, then messages from other sessions, then reply
and subagent wakes, and enqueue time within each group. The queue cap counts operator and agent entries
separately, so agents cannot fill the operator's slots, and queue_position is the real dispatch rank.
An agent's steer never interrupts the receiver: if the provider cannot take an injection, or operator
input is waiting, it waits in the queue behind that input. Steer replacement is per sender, so an agent
cannot cancel another sender's or the operator's steer.
The hop counts forwarding depth. A message forwarded to a session that is not driving your current
turn takes the turn's highest accepted hop plus one; steer also raises that value before provider
delivery. A message answering the session that started or joined your current turn (its message or
its reply wake), or one sent with an in_reply_to that names a message that session sent you, keeps
the turn's hop. A reply wake carries the hop you had when you sent the message, so an orchestrator
that dispatches the next child after each completion stays at hop 1 however many stages it runs. A
plain conversation between two sessions therefore stays at hop 1. A ninth forwarding
hop returns message_hop_limit: ask the operator to continue in a fresh turn.
Each sender→target pair has a rate budget, session.messaging.rate_limit_messages per
session.messaging.rate_limit_window (30 per 10 minutes by default), counted from durable admissions.
A send past it returns message_rate_limited (HTTP 429) with limit, window, and
retry_after_seconds details. Only that send is refused; neither session stops. Batch updates into
fewer messages rather than retrying immediately. Set rate_limit_messages = -1 to disable the budget.
Messages from other sessions never cancel the receiver's work. An agent's mode: "interrupt" is
delivered as steer, including attachments, and the result reports the mode used. If the runtime
cannot inject it into the live turn, it waits until the turn ends.
Consecutive queued messages from other sessions and reply wakes run as one turn (up to 8), each kept as
its own message in the transcript with its own reply watch; operator input is never merged and always
goes first. Send supersede: true to replace your own older message still queued for the same target.
When the target has been in one turn longer than session.messaging.queue_promote_after (default 2
minutes) and its provider supports steering, waiting agent messages and coalesced monitor wakes are
injected into the live turn instead of waiting for it to end.
Native self-targeting returns invalid_request. To continue work in the same session, end the turn;
to schedule work, use a subagent or send compozy__session_prompt to another session. This approved
compatibility exception applies immediately. Existing v4 admission receipts still replay without
origin or a new reply watch; their boundary compatibility shim is scheduled for removal in v0.5.0.
The message tool's existing cross-workspace reach is unchanged. Origin includes the sender's workspace so readers can resolve that session correctly.
Governed child feedback
compozy spawn creates a child with a required TTL, lineage, capacity limits, and permissions that
cannot exceed its parent. By default, CompozyOS queues a sanitized synthetic turn on the parent when
the child completes a turn, stops, fails, or enters a needs-you state. A canceled child turn sends no
completed wake. The wake never interrupts an active parent prompt.
To hand one task to another agent, provider, or model from inside a turn and get the answer back without managing a child yourself, use subagents instead.
compozy spawn --agent researcher --ttl-seconds 3600
compozy spawn --agent researcher --ttl-seconds 3600 --no-notify-creator
compozy spawn --agent researcher --ttl-seconds 3600 \
--provider codex --model gpt-5.6-sol --reasoning-effort high --speed fastnotify_creator defaults to true on HTTP, UDS, and compozy__session_spawn. Set it explicitly to
false to opt out for one child. This default has no config.toml key.
Provider, model, reasoning effort, and speed are optional child-runtime overrides on the CLI, HTTP/UDS request, and native tool. Omit them to use the named agent and workspace defaults.
Native orchestration tools
Resolve each live descriptor with compozy__tool_info before calling it. All targets are restricted
to the caller's workspace, and a session cannot target itself.
| Tool | Purpose |
|---|---|
compozy__session_wait | Wait up to 30 minutes for a badge or lifecycle state. |
compozy__session_spawn | Create a governed child with a required TTL and narrowed permissions. |
compozy__session_stop | Stop another session; destructive approval policy applies. |
compozy__session_approve | Resolve another session's pending permission request. |
compozy__session_clarify_answer | Answer another session's pending clarification by choice or text. |
compozy__session_prompt_cancel | Cancel another session's active prompt without stopping the session. |
Approval and clarification resolution survive daemon restart. A successful orphaned resolution
returns resolved-after-restart; a race may return already-resolved, and a full durable input queue
returns queue-full without consuming the pending interaction.
Related pages
- Safe Spawn covers child constraints and cleanup.
- Delegate to subagents covers one-call delegation with a wake on completion.
- Session Lifecycle covers durable session and runtime state.
- Session Wait CLI lists the generated flags.
- Prompt Cancel CLI lists the generated command contract.
Ask another session for a reply
An agent can call compozy__session_prompt with notify_on_complete: true to receive a reply from an
existing session. The tool returns reply_watch: { id, state }, using its current persisted state
(armed, fired, delivered, or abandoned). Retrying the same message and idempotency key after a
pre-dispatch failure re-arms the same watch. The sender can then finish its turn;
CompozyOS delivers one synthetic reply wake after the turn that consumed the message settles.
Queued messages retain their watches across a target stop. A busy sender receives the wake after its
current turn.
Waiting is long-running work, not silence. While the asked session is live, the sender's open watch
counts as an awaiting_reply work signal, so inactivity supervision does not stop an orchestrator
that is waiting for an answer until the watch expires (reply_watch_ttl, 24 hours by default). A
sender with no turn in flight is never stopped for inactivity; if the target stopped with the message
queued, the idle sender stays active (its runtime may be released) and the later reply wakes it once.
If the sender was stopped anyway (a daemon restart or an agent crash), the reply resumes the sender
and delivers the wake once. A sender you stopped yourself stays stopped and receives the wake when you
resume it.
compozy__session_status with result_view: "full", the session status HTTP response, and compozy session status <id> -o json
include reply_watches while they are armed or fired. Each item identifies the watch, target
session, message, state, and creation time. The human CLI shows a Waiting for replies section.
Delivered and abandoned watches disappear from this list.
Replies contain the last non-empty assistant message of the consuming turn, bounded to 12000 Unicode
characters. Truncated replies include a pointer to compozy__session_history; empty replies use
(no reply text). Outcomes are completed, failed (with an error summary), canceled, dropped
(removed before execution), expired (no reply arrived within reply_watch_ttl), or unknown
(delivery was uncertain; inspect the target session).
Archiving or deleting the sender abandons its outstanding watches. Canceling or clearing a reply wake
from the sender's queue does not send it again. notify_on_complete belongs to the agent-facing native
tool; HTTP operator prompts have no equivalent option. Operator-scoped native calls with this
option return invalid_request: notify_on_complete requires an agent session. Archiving or deleting
an unconsumed target settles its outstanding watches as unknown without waiting for a restart.
What the Web UI shows
A received message shows an In reply chip when it answers an earlier message; click it to jump to the
original. Several consecutive messages from the same sender collapse into one group labeled
"{title} · N messages", showing the latest and expanding to all. An expired reply watch appears as
No reply on the sender's card. In the session list, a session marked Needs attention says why,
for example "Stop not confirmed" or "Loop run went stale", with every cause in the hover text.
Steering with a screenshot
Operators can send an image or file while a session is working:
compozy session prompt <session-id> "Use this screenshot." --steer --attachment ./screen.pngRepeat --attachment for more files. HTTP/UDS clients can use attachments on the normal prompt
request with mode: "steer", or on the fenced /steer request. Use the metadata returned by the
session attachment upload endpoint. Attachment-only prompts are supported with an empty message.
When the runtime accepts live steering and the attachment's content type, the image/file joins the current turn. Otherwise operator steering interrupts and sends a replacement prompt with the same attachments. An agent message never interrupts another session: unavailable injection waits until that turn ends. Queue-to-steer promotion retains the queued attachment snapshot. Image/PDF capability refusals identify an input type the selected runtime cannot accept through an ordinary prompt either.