Sub-agent message queue: no way to inspect, delete, or reorder pending messages - stale messages still get delivered

[wsdc520-tl]

Sub-agent message queue: no way to inspect, delete, or reorder pending messages

Environment: @deepseek-ai/dsh 0.1.1-rc.2, Windows 11, installed via npx.

Description

Messages sent with send_message to a busy sub-agent are parked in its inbound queue and delivered one by one as the agent finishes turns. Currently there is no way to:

1. Inspect the pending queue of a sub-agent (list queued messages with id + preview);
2. Delete / cancel a single queued message that has become stale;
3. Reorder the queue, e.g. move the most urgent intervention to the front.

Why this matters

In practice, while a sub-agent is working you often send follow-up corrections. If several of them pile up, earlier ones can become stale or contradictory — but they will still be delivered in the original order. Consequences:

• The sub-agent burns turns acting on outdated context;
• The actually urgent message can only sit at the tail of the queue, losing its timeliness;
• Stale "paired" messages linger forever because they cannot be removed individually.

The only escape hatch today is interrupt_agent, which is too coarse: it stops the current turn but leaves the queue untouched, and it cannot express something like "drop the two older messages, deliver this one next".

Expected behavior

Any subset of the following would fix the pain:

1. A way to list pending queued messages per sub-agent (id + short preview);
2. Delete/cancel a queued message by id;
3. Reorder the queue — at minimum a "move to front";
4. (Nice-to-have) send_message options such as priority: urgent and/or replace_pending: true, so "cancel the old ones + insert this one" is a single step.

Happy to provide more reproduction details if useful. Thanks!

[Jstn-1g]

Thanks for the precise queue-control report, @schwarztim. I implemented and tested a reference for the bounded list + cancel subset against current master (b150a551b8d):

• exact commit: Jstn-1g@913172e
• reference branch: https://github.com/Jstn-1g/deepseek-harness/tree/reference/discussion-4631-pending-message-control

The root control plugin adds:

• list_pending_messages(subagent_id, offset?, limit?): a bounded FIFO snapshot of the exact live direct parent's still-unclaimed send_message follow-ups, with stable message ids, 160-code-point previews, default page size 20, and maximum 100.
• cancel_pending_message(subagent_id, message_id): removes one eligible follow-up through the existing Agent inbox cancellation path, recording the durable agent/inbox/spliced event with outcome: "canceled" and leaving the active turn untouched.

Authority and races are intentionally narrow. Initial input, active work, child-local/plugin context, internal notices, and coordinator relays attributed to another sender are neither listed nor cancellable. A stale/wrong parent, ancestor, host-user address, or non-resident/closing child cannot use this control, and inspection never cold-resumes a child. Cancel-first removes the id before any later claim; claim-first returns cancelled: false and never calls Agent.cancel().

Verification includes 302 passing package/catalog tests plus an assembled keyless ACP replay that holds a real child, queues two messages, pages the list, cancels the first runtime-minted id, admits only the survivor, and verifies the child's durable log contains the canceled splice but no canceled user/message. Host build, contract typecheck, full lint, generated catalogs/API surfaces, and all documentation/translation gates also pass.

I deliberately left reorder, move-to-front, priority, replace, and non-resident/cross-process mailbox control out of this patch; those need separate ordering, identity, lease, and claim semantics. This is a reference implementation for review, not an upstream merge or adoption claim.

[weijiafu14]

@Jstn-1g's list + cancel reference covers your asks 1 and 2. I want to flag a constraint on asks 3 and 4 that I do not think has been stated, because it decides whether they can be built at all in the current shape.

The pending send_message queue is not a dedicated queue. It is the Agent inbox — and the inbox carries more than your messages.

packages/subagent/subagent/src/continuation.ts states it plainly: "The Agent inbox is the only turn queue", and that same manager owns settlement delivery — when a grandchild settles, its notice is delivered into that inbox as a waking message. The file also tracks "accepted waking message ids this manager has not yet seen leave the inbox."

So the queue you want to reorder contains at least two kinds of item:

1. your send_message follow-ups, and
2. settlement notices from that sub-agent's own children.

Why this matters for each of your asks:

• Ask 3 (reorder / move-to-front) cannot be a general queue reorder. Moving your urgent message ahead of a settlement notice is probably fine; moving a settlement notice behind later work, or reordering two notices relative to each other, changes what the child believes about its own children's state. The operation needs to be defined as "reorder among my follow-ups", not "reorder the inbox".
• Ask 4 (replace_pending: true) has the sharper version of the same problem. A naive "clear the queue and insert this one" would drop settlement notices, and a dropped notice produces exactly the failure in Sub-agent completion polling fails with "unknown job" during multi-agent task, halting generation mid-task #4696: a parent that ended its turn to wait for a promised notice, and was never woken. That thread's report is a task that stalled silently after most of its work had succeeded — the same cost, one level up.

None of this argues against your asks. It argues that the API should be scoped to follow-ups by construction — cancel_pending_message(subagent_id, message_id) already is, since it takes an id from a list of your messages, which is probably why the bounded subset was the easy one to implement. A replace_pending that means "cancel my other pending follow-ups to this child, then send" is safe by the same reasoning; one that means "clear the queue" is not.

Worth adding to the report: the distinction above is invisible from the outside — from a user's seat the queue looks like a list of messages you sent. If the eventual list_pending_messages shows only your follow-ups (which is the right default), it is worth saying so in the tool description, or the first person to see "queue is empty" while a child is demonstrably waiting on something will file a second bug.

Interest disclosure: I maintain a third-party DSH plugin and ship subagent functionality through it, so I am not neutral here — which is why I am pointing only at DSH's own source and at another user's thread, and proposing nothing of mine. The native subagent runtime and its inbox are DSH's; we do not touch them and could not implement any of this.

[Jstn-1g]

Thank you for tracing this to the actual inbox and to #4696. That is exactly the boundary the reference enforces: list_pending_messages filters only coordinator relay entries attributed to the exact live direct parent, and the cancel path repeats the same eligibility check before using the inbox's existing removal path. Initial input, child-local messages, settlement/internal notices, other senders, and already-claimed work never enter the controllable set.

The current tool description and README also call out that an empty list means “none of your pending follow-ups,” not “the child inbox is empty.” I agree that any future replace/reorder operation would need to be defined over that eligible subsequence and preserve every ineligible entry and its relative order; a raw inbox clear or reorder would be unsafe. That extra atomicity/order contract is why this reference deliberately stops at bounded list + cancel.