Delivery semantics for messages sent to a busy agent session: queue instead of cancel-and-replace

[risutrex]

The problem

Sending anything to an agent session that is currently in a turn is the sharpest edge in the agent-to-agent path. ACP has no standard way to steer a running turn, so the behaviour is decided by a fallback chain, and the current fallback is "cancel the running turn and send the message as a replacement prompt":

• packages/server/src/server/agent/agent-manager.ts:3016 steerAgentRun() returns { status: "unavailable" } when the session exposes no steerActiveTurn.
• packages/server/src/server/agent/agent-manager.ts:3044 steerOrReplaceActiveTurn() then calls replaceAdmittedForegroundTurn() (:3084).
• packages/server/src/server/agent/agent-manager.ts:3141 replaceAdmittedForegroundTurn() cancels the active turn (cancelAgentRunBefore(..., "replace")) and immediately starts a replacement prompt.
• packages/server/src/server/agent/providers/acp-agent.ts:2546 interrupt() sends ACP session/cancel. That resolves when the provider acknowledges the cancel — not when the provider's turn has actually ended.

Two consequences, both visible to users:

1. A background message can cancel real work. The finish notification for a subagent is enqueued to the caller with activeTurnBehavior: "steer" (packages/server/src/server/agent/finish-subscriptions/index.ts:185). With no steering available it takes the replace path, so the parent's running turn is dropped and replaced by the notification.

2. The replacement prompt can fail. If the provider has not released the session yet, the new prompt is rejected. With MiniMax Code 0.7.1 the parent chat shows:

   [System Error] Internal error: MiniMax Code Runtime failed: Session already has an active Turn. Use queue send to deliver the message after it.
   code: -32603
   

   I filed the reproduction with the raw daemon log here: bug: the subagent finish notification cancels the busy parent's turn and then fails with -32603 (ACP provider) #8300

"prompt.steer" currently occurs in packages/server/src only in packages/server/src/server/agent/plugin-provider.ts:1236, so it is a plugin-provider capability today and no ACP provider can steer. Every message to a busy ACP session takes the cancel-and-replace path.

What providers actually offer

The providers differ, and the ACP surface does not describe this:

Provider	Steer into a running turn	Queue for later
Codex (codex-app-server-agent.ts)	yes	n/a
OpenCode (opencode-agent.ts)	yes	n/a
Claude Code	no	no (background work instead)
Generic ACP providers	no	no

Some ACP providers implement both natively, but only as vendor extensions. MiniMax Code 0.7.1 advertises them in initialize:

"_meta": { "minimax-code/extensions": { "methods": [
  "mcode/session/steer",
  "mcode/session/queue/list", "mcode/session/queue/enqueue",
  "mcode/session/queue/update", "mcode/session/queue/delete", "mcode/session/queue/steer"
] } }

Neither "mcode/session" nor "queue/enqueue" occurs anywhere in packages/server/src, so Paseo never calls them. The provider's own error message ("Use queue send to deliver the message after it") points at a capability the client is not using.

Options

A. Wait for the session to be released. After session/cancel, wait (bounded) until the provider actually reports the turn as ended, then send the replacement prompt. Fixes the race, keeps today's replace semantics. Downside: it still cancels work, and the wait has to be bounded carefully — on timeout the prompt must not be sent blindly.

B. Queue inside Paseo. When the provider cannot steer, hold the message in a Paseo-side pending queue and deliver it when the target's turn ends. No turn is cancelled, nothing is lost, and it works for every provider without provider-specific code. Downside: the notification is delayed until the target's current turn finishes, which for a long turn can be a long time — so the UI needs to show that a message is pending rather than silently dropping it.

C. Use the provider's queue extension. When initialize advertises a queue method in _meta, call it instead of session/prompt. Best fidelity for the provider, but provider-specific, adds a second source of queue state, and does nothing for the other ACP providers.

What I would propose as a first step

Keep the change narrow and provider-agnostic:

• Automatically generated messages (finish notifications, wakeups) never cancel the parent's turn. They are queued and delivered when the parent's turn ends. A background report should not change the course of the work in progress.
• User-facing semantics stay as they are. A user who sends a message to a busy agent still gets the current behaviour (steer when the provider supports it, otherwise the existing fallback), and an explicit interrupt still cancels the turn — that is what the user asked for.
• The difference between "the user asked to interrupt" and "a background message arrived" is the intent of the sender, not a provider capability. Today that intent is not represented anywhere in the delivery path: the finish notification is enqueued with the same activeTurnBehavior: "steer" a user's message would use.

If the provider turns out to expose a queue (option C), that can be used as the delivery mechanism instead of the Paseo-side queue, but it should not be required for the narrow fix.

A regression test for the narrow fix would need to assert that delivering a finish notification to a busy parent does not cancel the parent's turn and does not start a second prompt, and that the notification is delivered exactly once after the parent's turn ends. On the current code that test fails on the cancel / second prompt.

Questions

• Is a narrow fix limited to automatically generated notifications acceptable, or should the pending-message queue be a general delivery mode that users can choose explicitly?
• Where should the pending-message state live — in the agent-manager next to the existing run state, or in the message delivery layer?
• Should Paseo read provider extensions from initialize._meta at all, or is that better handled by provider-specific adapters (e.g. a minimax-code provider that maps mcode/session/queue/* onto a shared queue interface)?

Workarounds available today

For anyone hitting this while it is being worked on:

• create_agent / send_agent_prompt with notifyOnFinish: false — no parent callback is registered, so nothing is delivered into the parent's session.
• paseo agent detach <id> — makes the child independent (ParentAgentId becomes null), so it has no parent to notify.
• Sending from outside an agent context (a plain terminal, paseo send <id>) has no parent callback either.

[risutrex]

One more data point, since it removes an obvious objection: the ACP protocol itself has no standard way to advertise steering or queueing. In the ACP schema bundled with the app (@agentclientprotocol/sdk), promptCapabilities only carries image, audio and embeddedContext — there is no steer or queue field anywhere in the schema, and no occurrence of steer in the SDK.

So an ACP agent cannot tell a generic client "I can steer a running turn", and a generic client cannot discover it. That is why prompt.steer is currently a plugin-provider capability only (packages/server/src/server/agent/plugin-provider.ts:1236) and why every ACP provider falls into the cancel-and-replace path.

The practical consequence: the only interoperable behaviours left for an ACP provider are (a) queue the message inside the agent, or (b) reject it with an error that names the callable provider extension. For reference, MiniMax Code does exactly (b) today — it advertises mcode/session/steer and mcode/session/queue/enqueue in initialize._meta, but its error message says only "Use queue send to deliver the message after it" without naming the method, and the ACP schema gives a client no standard place to learn about it. I filed that side as a feature request: MiniMax-AI/minimax-code#567

This also suggests a provider-agnostic option for Paseo: instead of reading vendor _meta blocks directly, map a provider extension queue onto a shared queue interface per provider, the way codex-app-server-agent.ts and opencode-agent.ts already implement steerActiveTurn natively.

[risutrex]

Correction to one sentence in my original post, and one additional finding.

Correction. I wrote: "session/cancel. That resolves when the provider acknowledges the cancel — not when the provider's turn has actually ended." The first half of that is wrong: per the ACP specification, session/cancel is a notification and carries no acknowledgement, so await this.connection.cancel(...) resolves as soon as the notification is written. The only signal that the turn really ended is the response to the original session/prompt (stop reason cancelled), and the spec explicitly allows the caller to wait for it: https://agentclientprotocol.com/protocol/v1/cancellation.md

The rest of the analysis stands, and this makes it sharper: docs/agent-lifecycle.md:104 says provider interruption "resolves when the prior foreground turn can no longer run … It rejects only when the provider may still own the turn." The generic ACP adapter resolves the interruption while the provider may still own the turn, so the replacement prompt is sent into a session that is still busy — which is the -32603. A conformant adapter would either wait for the cancelled response to the original prompt or reject the interruption and let the caller queue the message.

Additional finding. An agent created as a detached root agent (relationship: { "kind": "detached" }) has ParentAgentId: null and no parent label, but it is still a finish subscriber of its creator: the ownership-based suppression in packages/server/src/server/agent/finish-subscriptions/index.ts:149 only applies when requireParentOwnership is true, and creation-time detachment sets it to false (packages/server/src/server/agent/create-agent/create.ts:188). The completion report is therefore still delivered into the creator's session and hits the same busy-parent failure. Only notifyOnFinish: false avoids it, because no subscription is registered in the first place.

This also means the "detach" escape hatch in my original post is not sufficient on its own for an agent created as detached — detaching an existing subagent does stop the reports, but creating one detached does not.

[risutrex]

Correction to one sentence in my earlier comment, because it changes which options are technically available.

Correction. I wrote that there is "no occurrence of steer in the SDK", and used that to argue that a generic ACP client cannot call a provider extension. The first half is right — the ACP schema has no standard steer/queue capability field, and promptCapabilities still carries only image, audio and embeddedContext. The second half is wrong, and I did not check the client side of the SDK before writing it.

@agentclientprotocol/sdk 0.17.1 does expose a client → agent channel for extension methods:

// node_modules/@agentclientprotocol/sdk/dist/acp.d.ts
export declare class ClientSideConnection implements Agent {   // line 212
  /**
   * Extension method
   *
   * Allows the Agent to send an arbitrary request that is not part of the ACP spec.
   */
  extMethod(method: string, params: Record<string, unknown>): Promise<Record<string, unknown>>;      // line 409
  extNotification(method: string, params: Record<string, unknown>): Promise<void>;                     // line 415
}

So a generic client can call mcode/session/steer on an agent that advertises it. The missing piece is not the SDK — it is Paseo's generic ACP adapter, which never calls it and implements no steerActiveTurn, so every ACP provider falls into the cancel-and-replace path.

What still holds from my earlier comment:

• discovery still depends on the agent's vendor initialize._meta block, because the ACP schema has no standard place for it;
• session/cancel is a notification without a response, and MiniMax Code answers the cancelled prompt while it still holds the session for ~100 ms (measured, raw logs in bug: ACP provider: no steerActiveTurn implementation, so mid-turn input fails with the agent's busy error #3964);
• the delivery semantics of a message that arrives while an agent is busy are still the open question here.

Consequence for the options in this discussion: implementing steer for agents that advertise it, via connection.extMethod("mcode/session/steer", …), is an adapter change rather than an SDK limitation. It still needs a maintainer decision, and it needs the vendor method name and payload shape to be discovered from the agent's _meta rather than hard-coded per provider.