From 8a8e2a8049fba194d999cf7f3ec4b247910657ee Mon Sep 17 00:00:00 2001 From: Mario Zechner Date: Wed, 18 Mar 2026 03:49:16 +0100 Subject: [PATCH] docs(agent): update steering docs for deferred tool execution closes #2330 --- packages/agent/README.md | 6 +++--- packages/agent/src/agent.ts | 5 +++-- packages/agent/src/types.ts | 6 +++--- packages/coding-agent/README.md | 2 +- packages/coding-agent/docs/extensions.md | 4 ++-- packages/coding-agent/docs/rpc.md | 8 ++++---- packages/coding-agent/docs/sdk.md | 4 ++-- packages/coding-agent/src/core/agent-session.ts | 5 +++-- 8 files changed, 21 insertions(+), 19 deletions(-) diff --git a/packages/agent/README.md b/packages/agent/README.md index 55679c5a..6461422c 100644 --- a/packages/agent/README.md +++ b/packages/agent/README.md @@ -310,10 +310,10 @@ agent.clearAllQueues(); Use clearSteeringQueue, clearFollowUpQueue, or clearAllQueues to drop queued messages. -When steering messages are detected after a tool completes: -1. Remaining tools are skipped with error results +When steering messages are detected after a turn completes: +1. All tool calls from the current assistant message have already finished 2. Steering messages are injected -3. LLM responds to the interruption +3. The LLM responds on the next turn Follow-up messages are checked only when there are no more tool calls and no steering messages. If any are queued, they are injected and another turn runs. diff --git a/packages/agent/src/agent.ts b/packages/agent/src/agent.ts index 068b834f..012adeae 100644 --- a/packages/agent/src/agent.ts +++ b/packages/agent/src/agent.ts @@ -304,8 +304,9 @@ export class Agent { } /** - * Queue a steering message to interrupt the agent mid-run. - * Delivered after current tool execution, skips remaining tools. + * Queue a steering message while the agent is running. + * Delivered after the current assistant turn finishes executing its tool calls, + * before the next LLM call. */ steer(m: AgentMessage) { this.steeringQueue.push(m); diff --git a/packages/agent/src/types.ts b/packages/agent/src/types.ts index d542748a..2e7b53a3 100644 --- a/packages/agent/src/types.ts +++ b/packages/agent/src/types.ts @@ -159,9 +159,9 @@ export interface AgentLoopConfig extends SimpleStreamOptions { /** * Returns steering messages to inject into the conversation mid-run. * - * Called after each tool execution to check for user interruptions. - * If messages are returned, remaining tool calls are skipped and - * these messages are added to the context before the next LLM call. + * Called after the current assistant turn finishes executing its tool calls. + * If messages are returned, they are added to the context before the next LLM call. + * Tool calls from the current assistant message are not skipped. * * Use this for "steering" the agent while it's working. * diff --git a/packages/coding-agent/README.md b/packages/coding-agent/README.md index 44b12507..24763912 100644 --- a/packages/coding-agent/README.md +++ b/packages/coding-agent/README.md @@ -181,7 +181,7 @@ See `/hotkeys` for the full list. Customize via `~/.pi/agent/keybindings.json`. Submit messages while the agent is working: -- **Enter** queues a *steering* message, delivered after current tool execution (interrupts remaining tools) +- **Enter** queues a *steering* message, delivered after the current assistant turn finishes executing its tool calls - **Alt+Enter** queues a *follow-up* message, delivered only after the agent finishes all work - **Escape** aborts and restores queued messages to editor - **Alt+Up** retrieves queued messages back to editor diff --git a/packages/coding-agent/docs/extensions.md b/packages/coding-agent/docs/extensions.md index 69ec4fdd..d09ed387 100644 --- a/packages/coding-agent/docs/extensions.md +++ b/packages/coding-agent/docs/extensions.md @@ -999,7 +999,7 @@ pi.sendMessage({ **Options:** - `deliverAs` - Delivery mode: - - `"steer"` (default) - Interrupts streaming. Delivered after current tool finishes, remaining tools skipped. + - `"steer"` (default) - Queues the message while streaming. Delivered after the current assistant turn finishes executing its tool calls, before the next LLM call. - `"followUp"` - Waits for agent to finish. Delivered only when agent has no more tool calls. - `"nextTurn"` - Queued for next user prompt. Does not interrupt or trigger anything. - `triggerTurn: true` - If agent is idle, trigger an LLM response immediately. Only applies to `"steer"` and `"followUp"` modes (ignored for `"nextTurn"`). @@ -1025,7 +1025,7 @@ pi.sendUserMessage("And then summarize", { deliverAs: "followUp" }); **Options:** - `deliverAs` - Required when agent is streaming: - - `"steer"` - Interrupts after current tool, remaining tools skipped + - `"steer"` - Queues the message for delivery after the current assistant turn finishes executing its tool calls - `"followUp"` - Waits for agent to finish all tools When not streaming, the message is sent immediately and triggers a new turn. When streaming without `deliverAs`, throws an error. diff --git a/packages/coding-agent/docs/rpc.md b/packages/coding-agent/docs/rpc.md index a037c04e..53350cdd 100644 --- a/packages/coding-agent/docs/rpc.md +++ b/packages/coding-agent/docs/rpc.md @@ -58,7 +58,7 @@ With images: {"type": "prompt", "message": "New instruction", "streamingBehavior": "steer"} ``` -- `"steer"`: Interrupt the agent mid-run. Message is delivered after current tool execution, remaining tools are skipped. +- `"steer"`: Queue the message while the agent is running. It is delivered after the current assistant turn finishes executing its tool calls, before the next LLM call. - `"followUp"`: Wait until the agent finishes. Message is delivered only when agent stops. If the agent is streaming and no `streamingBehavior` is specified, the command returns an error. @@ -76,7 +76,7 @@ The `images` field is optional. Each image uses `ImageContent` format: `{"type": #### steer -Queue a steering message to interrupt the agent mid-run. Delivered after current tool execution, remaining tools are skipped. Skill commands and prompt templates are expanded. Extension commands are not allowed (use `prompt` instead). +Queue a steering message while the agent is running. It is delivered after the current assistant turn finishes executing its tool calls, before the next LLM call. Skill commands and prompt templates are expanded. Extension commands are not allowed (use `prompt` instead). ```json {"type": "steer", "message": "Stop and do this instead"} @@ -321,8 +321,8 @@ Control how steering messages (from `steer`) are delivered. ``` Modes: -- `"all"`: Deliver all steering messages at the next interruption point -- `"one-at-a-time"`: Deliver one steering message per interruption (default) +- `"all"`: Deliver all steering messages after the current assistant turn finishes executing its tool calls +- `"one-at-a-time"`: Deliver one steering message per completed assistant turn (default) Response: ```json diff --git a/packages/coding-agent/docs/sdk.md b/packages/coding-agent/docs/sdk.md index 52514201..dc5f93ca 100644 --- a/packages/coding-agent/docs/sdk.md +++ b/packages/coding-agent/docs/sdk.md @@ -78,7 +78,7 @@ interface AgentSession { prompt(text: string, options?: PromptOptions): Promise; // Queue messages during streaming - steer(text: string): Promise; // Interrupt: delivered after current tool, skips remaining + steer(text: string): Promise; // Queue for delivery after the current assistant turn finishes its tool calls followUp(text: string): Promise; // Wait: delivered only when agent finishes // Subscribe to events (returns unsubscribe function) @@ -150,7 +150,7 @@ await session.prompt("After you're done, also check X", { streamingBehavior: "fo For explicit queueing during streaming: ```typescript -// Interrupt the agent (delivered after current tool, skips remaining tools) +// Queue a steering message for delivery after the current assistant turn finishes its tool calls await session.steer("New instruction"); // Wait for agent to finish (delivered only when agent stops) diff --git a/packages/coding-agent/src/core/agent-session.ts b/packages/coding-agent/src/core/agent-session.ts index 4517dc31..713ebd45 100644 --- a/packages/coding-agent/src/core/agent-session.ts +++ b/packages/coding-agent/src/core/agent-session.ts @@ -1066,8 +1066,9 @@ export class AgentSession { } /** - * Queue a steering message to interrupt the agent mid-run. - * Delivered after current tool execution, skips remaining tools. + * Queue a steering message while the agent is running. + * Delivered after the current assistant turn finishes executing its tool calls, + * before the next LLM call. * Expands skill commands and prompt templates. Errors on extension commands. * @param images Optional image attachments to include with the message * @throws Error if text is an extension command