Updated agent README with steering enhancements
Public
Updated agent README with steering enhancements
Agent
Pi
Model
GPT-5.2 Codex
Started
Jan 18, 6:13 PM
Messages76
Downloads0
Updated README with new agent options and examples.
EditExpanded steering section with new methods.
EditTriggered tests via commit hook.
VerifyCommitted and pushed documentation changes.
Cleanup
@packages/agent/README.md needs an update. thing i noticed is that steering is now more powerful iirc? please have a look at the actual implementation and update
Planning initial code exploration
I'm preparing to locate the steering implementation by searching and reading the README and related files to understand the current setup before making any edits.
>lsAGENTS.md
biome.json
CONTRIBUTING.md
LICENSE
node_modules
package-lock.json
package.json
packages
pi-mono.code-workspace
pi-test.sh
README.md
scripts
test.sh
tsconfig.base.json
tsconfig.jsonPlanning to locate steering logic
I'm preparing to search the codebase using ripgrep or grep to find where the agent's steering functionality is implemented.
>rg -n "steering" packages/agentpackages/agent/CHANGELOG.md:111: - `followUp(msg)`: Waits until the agent finishes. Delivered only when there are no more tool calls or steering messages.
packages/agent/CHANGELOG.md:112:- **Queue mode renamed**: `queueMode` option renamed to `steeringMode`. Added new `followUpMode` option. Both control whether messages are delivered one-at-a-time or all at once.
packages/agent/src/agent.ts:50: * Steering mode: "all" = send all steering messages at once, "one-at-a-time" = one per turn
packages/agent/src/agent.ts:52: steeringMode?: "all" | "one-at-a-time";
packages/agent/src/agent.ts:99: private steeringQueue: AgentMessage[] = [];
packages/agent/src/agent.ts:101: private steeringMode: "all" | "one-at-a-time";
packages/agent/src/agent.ts:114: this.steeringMode = opts.steeringMode || "one-at-a-time";
packages/agent/src/agent.ts:174: this.steeringMode = mode;
packages/agent/src/agent.ts:178: return this.steeringMode;
packages/agent/src/agent.ts:202: * Queue a steering message to interrupt the agent mid-run.
packages/agent/src/agent.ts:206: this.steeringQueue.push(m);
packages/agent/src/agent.ts:211: * Delivered only when agent has no more tool calls or steering messages.
packages/agent/src/agent.ts:218: this.steeringQueue = [];
packages/agent/src/agent.ts:226: this.steeringQueue = [];
packages/agent/src/agent.ts:248: this.steeringQueue = [];
packages/agent/src/agent.ts:340: if (this.steeringMode === "one-at-a-time") {
packages/agent/src/agent.ts:341: if (this.steeringQueue.length > 0) {
packages/agent/src/agent.ts:342: const first = this.steeringQueue[0];
packages/agent/src/agent.ts:343: this.steeringQueue = this.steeringQueue.slice(1);
packages/agent/src/agent.ts:348: const steering = this.steeringQueue.slice();
packages/agent/src/agent.ts:349: this.steeringQueue = [];
packages/agent/src/agent.ts:350: return steering;
packages/agent/src/types.ts:78: * Returns steering messages to inject into the conversation mid-run.
packages/agent/src/types.ts:84: * Use this for "steering" the agent while it's working.
packages/agent/src/types.ts:91: * Called when the agent has no more tool calls and no steering messages.
packages/agent/src/agent-loop.ts:113: // Check for steering messages at start (user may have typed while waiting)
packages/agent/src/agent-loop.ts:119: let steeringAfterTools: AgentMessage[] | null = null;
packages/agent/src/agent-loop.ts:121: // Inner loop: process tool calls and steering messages
packages/agent/src/agent-loop.ts:165: steeringAfterTools = toolExecution.steeringMessages ?? null;
packages/agent/src/agent-loop.ts:175: // Get steering messages after turn completes
packages/agent/src/agent-loop.ts:176: if (steeringAfterTools && steeringAfterTools.length > 0) {
packages/agent/src/agent-loop.ts:177: pendingMessages = steeringAfterTools;
packages/agent/src/agent-loop.ts:178: steeringAfterTools = null;
packages/agent/src/agent-loop.ts:300:): Promise<{ toolResults: ToolResultMessage[]; steeringMessages?: AgentMessage[] }> {
packages/agent/src/agent-loop.ts:303: let steeringMessages: AgentMessage[] | undefined;
packages/agent/src/agent-loop.ts:363: // Check for steering messages - skip remaining tools if user interrupted
packages/agent/src/agent-loop.ts:365: const steering = await getSteeringMessages();
packages/agent/src/agent-loop.ts:366: if (steering.length > 0) {
packages/agent/src/agent-loop.ts:367: steeringMessages = steering;
packages/agent/src/agent-loop.ts:377: return { toolResults: results, steeringMessages };
packages/agent/test/agent-loop.test.ts:344: // Return steering message after first tool executes
packages/agent/test/agent.test.ts:130: it("should support steering message queue", async () => {Planning README review
I'm preparing to fully read the README at packages/agent and relevant implementation files like agent.ts and agent-loop.ts to understand the agent's structure before editing or steering improvements.
Planning README update based on code rename
The README still mentions queueMode, but the code renamed it to steeringMode and followUpMode; I'll review agent.ts and relevant types fully before editing the README.
Planning steering update
I see the README and types still reference queueMode and queueMessage; I'll update them to use steer/followUp, and verify if getSteeringMessages and followUp are properly typed and documented.
Planning README update
I identified new steering features like steer, followUp, steeringMode, and followUpMode that should replace outdated queueMode references in the README; next, I'll examine the agent-loop implementation to understand followUp message behavior for accurate documentation.
Planning README update for steering
I'm preparing to revise the README to reflect that steering now supports both interrupt (steer) and follow-up messages with distinct modes, processed at multiple points including start, after tools, and after turns; this requires updating Agent Options, Message Queue sections, and adding a new Steering and Follow-up section without changing code.
Preparing detailed README edits for steering and follow-up
I'm outlining precise textual changes to fully replace queueMode with steeringMode and followUpMode in Agent Options and to rename Message Queue to Steering and Follow-up, adding clear explanations of steer() and followUp() methods, how steering interrupts tool execution, and follow-up triggers after agent completion. I'll also ensure examples and comments align with new APIs and avoid prohibited hyphen spacing in sentences.
>rg -n "queueMode|queueMessage|queue" packages/agent/README.md147: // How to handle queued messages: "one-at-a-time" (default) or "all"
148: queueMode: "one-at-a-time",
233:agent.queueMessage({
240:When queued messages are detected after a tool completes:Starting options section update
Updating message queue section
I'm planning to rewrite the "Message Queue" section to introduce and explain the new steer and followUp modes, showing how steering messages interrupt immediately after tools finish while follow-up messages run later only if no steering occurs. I'll provide code examples and update the bullet points to clarify their behaviors.
Preparing precise replacement for message queue section
I'm focusing on crafting a clear, concise replacement without em dashes, using commas and sentences for clarity, and ensuring an exact match to the old section for smooth editing.
Replacing message queue with steering and follow-up
I'm preparing new text explaining steering messages for interrupting running tools and follow-up messages for queuing work after the agent stops, emphasizing the sequencing rules and providing example code.
Verifying removal of legacy queueMode
I'm confirming that all mentions of the old "queueMode" are fully removed, including in Agent Options comments, to keep the codebase consistent.
>rg -n "queueMode|queueMessage|setQueueMode" packages/agent/README.md(no output)
Command exited with code 1Finalizing README updates
The README was updated to mention steer/follow-up as part of Control methods, ensuring terminology aligns with style rules and covers user expectations. No tests or npm checks were run since only documentation changed.
Summarizing documentation updates
Summary: Updated packages/agent/README.md to document steering and follow-up modes and updated example and options.
Tests: Not run (docs only).
Summary: Updated packages/agent/README.md to document steering and follow-up modes, and revised the example and behavior description to match the current API. Tests: Not run (documentation changes only).
anything else that's outdated?
Reviewing README for outdated info
I'm analyzing the README to identify sections that no longer match the current API and implementation, focusing on options like queueMode, setThinkingLevel, followUp, steer, and changes around message streaming and prompt parameters to highlight any inconsistencies or deprecated features.
Confirming missing options and methods in README
The README omits newer AgentOptions fields like sessionId and thinkingBudgets and lacks mentions of newer methods such as setSteeringMode and followUpMode; these are not necessarily outdated but represent missing documentation worth noting.
Reviewing docs for outdated references
I'm checking if event flow examples and convertToLlm message filtering have outdated details, noting comments mismatch actual code on attachment handling. I see some README still mentions old terms like queueMode instead of steering and lacks coverage of new features like sessionId and thinkingBudgets.
Identifying missing README details
The README lacks documentation for sessionId and thinkingBudgets options, plus the steering and follow-up methods for managing queues (like setSteeringMode, clearSteeringQueue). The rename from queueMode is fully updated with no other outstanding renames.
A few gaps remain in packages/agent/README.md:
sessionId and thinkingBudgets.setSteeringMode, setFollowUpMode, clearSteeringQueue, clearFollowUpQueue, or clearAllQueues.Want me to update those too?
well, yes, that's the whole point
Preparing full README reread before edits
I'll reread the entire README without offset to comply with the requirement before updating it to include sessionId, thinkingBudgets, queue-related methods, and options details.
Refining agent options docs
I'm updating agent options to include sessionId and thinkingBudgets with clear comments, maintaining the declared order and avoiding inline hyphens. I’ll also enhance the state management section with steering mode methods and queue controls for clarity without redundancy.
Planning doc updates for methods and properties
I'm planning to add setter usage for sessionId and thinkingBudgets properties in a new "Session and thinking budgets" subsection, update State Management with queue clearing and getter methods for modes, and clarify Agent Options with comments and examples, while ensuring proper hyphen usage and doc consistency. Next, I'll verify ThinkingBudgets type for accurate placeholder details.
>rg -n "interface ThinkingBudgets|type ThinkingBudgets" packages/ai/srcpackages/ai/src/types.ts:70:export interface ThinkingBudgets {Clarifying thinkingBudgets and sessionId usage
I'm noting ThinkingBudgets only includes minimal to high levels, so documentation should avoid mentioning xhigh except at agent level for specific providers. I'll add examples showing thinkingBudgets and sessionId as runtime properties for token-based providers, plus snippets for queue clearing methods extending the Steering section.
Adding sessionId and thinkingBudgets docs with code snippets
I'll create a new "Session and thinking budgets" subsection after State Management showing how to set sessionId and thinkingBudgets with clear usage examples, plus expand Steering section with queue-clearing method snippets and brief guidance on dropping queued messages. I'll update the Agent Options snippet by inserting sessionId and thinkingBudgets properly between streamFn and getApiKey.
Adding session and thinking budgets section
I'm inserting a new "Session and Thinking Budgets" subsection after State Management with a code snippet showing how to set sessionId and thinkingBudgets properties on the agent, without mentioning clearing them.
Adding clear queue methods to docs
I'm inserting the example snippet with get modes and clearing methods after the existing steering example, plus adding a sentence explaining to use clearSteeringQueue, clearFollowUpQueue, or clearAllQueues to drop queued messages without hyphen interruptions.
Confirming code comments and property mentions
Verified that comments accurately describe "thinkingBudgets" as an option property for token-based providers, "sessionId" is mentioned in Agent Options but not in Agent State, and no improper hyphen usage appears in new text; all references align correctly with the current code structure.
Summary: Updated packages/agent/README.md to document sessionId and thinkingBudgets in Agent options, added a Session and Thinking Budgets methods example, and expanded the steering section with getters and queue clearing methods. Tests: Not run (documentation changes only).
commit and push
Preparing commit with git status check
>git status --shortM packages/agent/README.md>git add packages/agent/README.md(no output)>git commit -m "docs(agent): update steering and options"Running formatting, linting, and type checking...
> pi-monorepo@0.0.3 check
> biome check --write . && tsgo --noEmit && npm run check -w @mariozechner/pi-web-ui
Checked 407 files in 247ms. No fixes applied.
> @mariozechner/pi-web-ui@0.49.0 check
> biome check --write . && tsc --noEmit && cd example && biome check --write . && tsc --noEmit
Checked 73 files in 36ms. No fixes applied.
Checked 3 files in 8ms. No fixes applied.
✅ All pre-commit checks passed!
[main c63f33d8] docs(agent): update steering and options
1 file changed, 54 insertions(+), 8 deletions(-)>git pushTo https://github.com/badlogic/pi-mono.git
ad337e30..c63f33d8 main -> mainSummary: Committed and pushed packages/agent/README.md updates. Tests: npm run check (triggered by commit hook).