[Feature Request] Expose an independent Agent.wake(target) operation for pending input

[Yangeyu]

Motivation

Related: discussion #4832 describes the interrupt-and-send UX and proposes removing and resubmitting queued messages. This proposal focuses on the underlying composable API capability, so clients can implement that UX while preserving the existing inbox.

An Agent can enqueue input without waking execution (send(message, target, false)) and cancel execution while retaining its inbox (cancel(cause, { keepInbox: true })), but callers cannot explicitly start that retained input without submitting another message.

A concrete use case is an interactive client: while a turn is running, the user submits steering and then interrupts the current execution. The client wants to interrupt first and then process the already queued steering immediately. Today, the retained input can remain pending until another waking message arrives.

Removing and resubmitting pending messages in the client would move inbox scheduling responsibilities into the UI and complicate preservation of message identity, order, and interleaved plugin context. A combined interrupt-and-steer operation would instead couple the core API to one client workflow.

Behavior

Expose a separate primitive, tentatively Agent.wake(target: InboxTarget): void, that requests execution of existing input without inserting or rewriting messages. Callers could compose it with cancellation:

agent.cancel({ kind: 'user' }, { keepInbox: true })
agent.wake('next-step')

Proposed semantics for discussion:

• next-step starts with all pending step input; next-turn starts with pending step input plus one ordinary queued message. Subsequent turns use the existing queue-draining behavior.
• An empty target does not create a turn. An already running driver continues processing normally.
• During cancellation settlement or maintenance, retain the wake request and recheck the inbox when execution can restart. If both boundaries were requested and step input remains, process the step boundary first.
• Preserve existing message IDs, order, plugin context, cancellation behavior, and durable session format. Clearing cancellation removes pending wake requests; disposal must not restart execution.
• Expose the same operation through SessionController for attached, ordinary live Agents, with an acknowledgement rather than a completion promise.

A candidate implementation is available in this fork comparison, commit c5e34d4fa8d0121af0e636b14fe5b4d73d4e807b. The API name and deferred-wake semantics are proposals for upstream review.

Local validation passed 442 Agent-loop/controller tests, TypeScript SDK session replay, Python SDK snapshots through the built JavaScript CLI with a local mock model service, build, lint, and typechecks. No live-provider or packaged-executable validation is claimed.

[1207627875]

always.                   ——Snape Severus