Agent Core
Overview
Path-routing coverage: this doc owns packages/agent/**. Route changes under that glob here, including src/, package entrypoints, examples, README/changelog, and tests that define or lock agent-core behavior.
packages/agent publishes @earendil-works/pi-agent-core, a reusable agent runtime layered on @earendil-works/pi-ai. The package entrypoint packages/…/index.ts re-exports the stateful Agent, low-level loop APIs, proxy streaming, the default stream-function setter, and public types. packages/…/package.json exposes only dist/index.js and dist/index.d.ts plus ./package.json; source files are internal to the built package.
The stateful surface is packages/…/agent.ts. Agent wraps the low-level loop with mutable transcript state, tool loadout state, lifecycle subscriptions, abort handling, and steering/follow-up queues. Construction seeds a leading system message from initialState.systemPrompt and initialState.tools unless initialState.messages already starts with a system message. agent.state.systemPrompt is replayed from transcript system messages; state.tools is the executable tool set; state.messages is the transcript plus any app-specific AgentMessage values. Assigning state.tools or state.messages copies the top-level array, while mutating the returned array mutates live state.
The LLM/tool orchestration lives in packages/…/agent-loop.ts. runAgentLoop() appends new prompt messages, emits agent_start/turn_start and message lifecycle events for them, then enters a loop of provider request, assistant streaming, tool execution, turn finalization, and queue polling. runAgentLoopContinue() starts from existing context and requires a non-empty transcript whose last message is not an assistant message. The observable stream APIs agentLoop() and agentLoopContinue() wrap those functions in a pi-ai EventStream; they preserve event order but do not make consumer event handling a barrier. The Agent class does await subscribers in processEvents(), so message_end listeners settle before tool preflight and agent_end listeners settle before prompt()/waitForIdle() resolve.
Provider calls are funneled through the StreamFn contract in packages/…/types.ts: (model, TranscriptContext, SimpleStreamOptions) => AssistantMessageEventStream. Immediately before a provider request, agent-loop.ts optionally applies transformContext to AgentMessage[], then convertToLlm to standard pi-ai Message[], then normalizeContext({ messages }). System prompt and tool declarations are carried in transcript system messages, not as top-level context fields. getApiKey is resolved per provider request and request identity is merged over DEFAULT_AGENT_IDENTITY ({ attribution: PI_ATTRIBUTION }) before calling the stream function. packages/…/stream-fn.ts holds a process-local fallback stream function for legacy callers; current callers should pass streamFn, or getDefaultStreamFn() throws.
Tool state is split between executable tools and transcript declarations. Before pending messages reach the model, declareToolChanges() in packages/…/agent-loop.ts diffs the current transcript declarations against context.tools using pi-ai helpers. It inserts or rewrites a system message with toolsAdded/toolsRemoved, so replay of transcript system messages declares exactly the executable set. This behavior is locked by packages/…/agent.test.ts, including replacing stale pending tool declarations and preserving the replayed baseline on Agent.reset().
Tools use AgentTool from packages/…/types.ts. The runtime prepares raw tool-call arguments with an optional prepareArguments, validates them with pi-ai validateToolArguments, then runs beforeToolCall, execute, and afterToolCall. A tool may stream partial updates through the onUpdate callback; executePreparedToolCall() ignores updates after the tool promise settles. The default batch mode is parallel: calls are prepared sequentially, allowed tools execute concurrently, tool_execution_end events fire in completion order, and persisted toolResult messages are emitted in assistant source order. A global toolExecution: "sequential" or any called tool with executionMode: "sequential" forces sequential execution for the whole assistant batch. A length stop reason causes all tool calls in that assistant message to be converted to error tool results instead of executed, because streamed argument salvage may be truncated.
Turn scheduling has three extension points. prepareRequest runs immediately before every provider request after pending input has already been emitted, and can replace context, model, or thinking level for that and later requests. finishTurn runs after assistant/tool-result messages are appended and before turn_end; { action: "end" } stops before queue polling, while { action: "continue" } ensures one more provider request unless tool results, steering, or follow-up already cause one. prepareNextTurn runs after a completed turn when the loop will continue and can append messages or replace context/model/thinking for the next turn; steering queued while it runs is picked up before the next request if no earlier steering batch is already pending.
Agent adds user-facing queue semantics in packages/…/agent.ts. steer() queues messages to inject after the current assistant turn and its tools finish; followUp() queues messages only after the agent would otherwise stop. Queue modes are "one-at-a-time" or "all", and peekQueuedMessages() previews the next selected batch without consuming it, preferring steering over follow-up. continue() from a user/tool-result tail retries from existing context and polls steering at startup; follow-up waits until that response naturally stops. continue() from an assistant tail cannot call the provider directly, so it drains one steering batch first, then one follow-up batch, or throws.
Attachments are supported through normal pi-ai content blocks. Agent.prompt(input: string, images?: ImageContent[]) in packages/…/agent.ts converts text plus optional images into a single user message with [{ type: "text" }, ...images]. Tool results and partial updates also carry (TextContent | ImageContent)[] content through AgentToolResult in packages/…/types.ts; packages/…/tools.ts preserves MCP image/text blocks via toLlmContent() and codemode result.output.
packages/…/proxy.ts provides streamProxy() for browser or thin-client apps that route provider requests through a backend. It posts { model, context, options } to ${proxyUrl}/api/stream with bearer auth, forwards only serializable stream options, and reconstructs a full AssistantMessageEventStream from server-sent data: lines whose events omit partial to reduce bandwidth. The proxy reconstructs text, thinking, and tool-call partials locally; it keeps incremental tool-call argument state in ToolCallArgumentsStream by content index and merges final tool-call metadata from toolcall_end. Clean EOF without a terminal done/error event is surfaced as an error assistant message instead of hanging.
The example flow in packages/agent/examples/mcp-codemode shows extension boundaries. main.ts creates a normal Agent, connects @earendil-works/pi-mcp, converts each MCP tool to an AgentTool, and adds a codemode tool. tools.ts maps MCP input schemas to provider-safe object schemas, forwards MCP progress as tool updates, maps MCP structured output to structuredContent, and implements nested tool calls through exported runToolCall() so beforeToolCall/afterToolCall policies still apply inside codemode scripts.
Tests under packages/agent/test are behavior documentation for this module. agent.test.ts covers the stateful wrapper, event barriers, queues, reset, identity/session forwarding, default stream fallback, and thrown provider failure normalization. agent-loop.test.ts covers low-level scheduling, tool execution modes, aborted batches, finish/prepare hooks, type conversions, and tool-result ordering. proxy.test.ts covers proxy stream reconstruction and hang prevention. e2e.test.ts exercises Agent against pi-ai faux providers, including thinking blocks and continuation. agent-tool-typebox.test.ts verifies that AgentTool parameter typing remains compatible with TypeBox-shaped schemas via pi-schema types.
Coupling
- If
AgentEventin packages/…/types.ts changes, update reducers and sequencing in packages/…/agent.ts and packages/…/agent-loop.ts together.Agent.processEvents()owns state reduction and listener barriers;runLoop()owns the emitted order, and tests in packages/…/agent.test.ts and packages/…/agent-loop.test.ts assert both. - If provider stream events or
AssistantMessagecontent blocks change in@earendil-works/pi-ai, update bothstreamAssistantResponse()in packages/…/agent-loop.ts and proxy reconstruction in packages/…/proxy.ts. They both translate assistant stream events into partial/final assistant messages but one receives full provider events and the other rebuilds partials from stripped proxy events. - If transcript system-message semantics or tool declaration shapes change in
@earendil-works/pi-ai, verifycreateMutableAgentState()in packages/…/agent.ts anddeclareToolChanges()in packages/…/agent-loop.ts. Initial prompt/tool seeding,Agent.reset(), and provider context construction all assume system messages are the canonical prompt/tool carrier. - If the
StreamFnoptions surface in packages/…/types.ts gains serializable request fields, also updatebuildProxyRequestOptions()in packages/…/proxy.ts; otherwise direct provider calls may receive an option that proxy-backed agents silently drop. - If tool execution hooks or result fields change in packages/…/types.ts, update
prepareToolCall(),finalizeExecutedToolCall(),createToolResultMessage(), and exportedrunToolCall()in packages/…/agent-loop.ts together. The MCP/codemode example in packages/…/tools.ts depends onrunToolCall()applying the same validation and hooks as model-issued calls. - If queue timing changes in packages/…/agent-loop.ts, verify
Agent.continue()fallback logic in packages/…/agent.ts. Statefulcontinue()has extra behavior for assistant-tail transcripts and must preserve steering-before-follow-up priority and queue-mode drain semantics.
Risks
- packages/…/proxy.ts is fragile around streaming termination and tool-call argument reconstruction. Regression tests in packages/…/proxy.test.ts reference issues
#8996and#9265: missing newline-terminated terminal events previously lost final metadata, and reparsing accumulated tool arguments on every delta could become quadratic. If proxy line buffering orToolCallArgumentsStreamusage changes, proxy-backed agents can hang, lose tool metadata, or become unusably slow on large tool arguments. - Aborted multi-tool batches in packages/…/agent-loop.ts must emit a result for every tool call. Tests in packages/…/agent-loop.test.ts reference
#9986; without the early abort checks inprepareToolCall()and the sequential/parallel batch handling, providers can see assistant tool calls with missing tool-result messages, breaking transcript validity. - Length-truncated assistant messages in packages/…/agent-loop.ts deliberately bypass tool execution. The comments and tests in packages/…/agent-loop.test.ts describe the failure mode: salvaged JSON arguments can parse and validate while silently incomplete. If
failToolCallsFromTruncatedMessage()is weakened, tools may execute with corrupted arguments after a token-limit stop. - Listener barriers in packages/…/agent.ts are easy to break by replacing awaited
processEvents()calls with fire-and-forget emission. packages/…/agent.test.ts asserts thatprompt()andwaitForIdle()wait for async subscribers and thatbeforeToolCallobserves state after the assistantmessage_end; violating this can race persistence/UI listeners with tool execution.