agent-core@earendil-works/pi-agent-core

要点Key points

• index.ts 只有 5 行：export * 四个模块，再单独导出 setDefaultStreamFn（getDefaultStreamFn 不导出）。index.ts is five lines: export * from four modules plus setDefaultStreamFn alone (getDefaultStreamFn stays internal).
• 循环本身不持有状态：agentLoop() 返回 EventStream<AgentEvent, AgentMessage[]>，runAgentLoop() 接受一个 emit 回调——Agent 用的是后者。The loop holds no state: agentLoop() returns an EventStream<AgentEvent, AgentMessage[]>, runAgentLoop() takes an emit callback — Agent uses the latter.
• 对 pi-ai 的依赖集中在四处：transcript 工具（工具声明 / system 基线）、validateToolArguments、EventStream 与类型。The pi-ai dependency is concentrated in four places: transcript helpers (tool declarations, system baseline), validateToolArguments, EventStream, and types.

工作原理How it works

1. 宿主构造 new Agent({ initialState, streamFn, convertToLlm, … })。The host constructs new Agent({ initialState, streamFn, convertToLlm, … }).
2. prompt() / continue() 把当前状态拍成 AgentContext 快照，连同由选项组装的 AgentLoopConfig 交给 runAgentLoop()。prompt() / continue() snapshot state into an AgentContext and pass it, with an AgentLoopConfig assembled from the options, to runAgentLoop().
3. 循环通过 emit 发出 AgentEvent；Agent.processEvents() 先更新自身状态，再依次 await 订阅者。The loop emits AgentEvents via emit; Agent.processEvents() updates its own state first, then awaits subscribers in order.

要点Key points

• prompt() 在运行中调用会抛错，提示改用 steer() 或 followUp()——这是唯一的并发入口约束。prompt() throws while a run is active, pointing at steer() or followUp() — the single concurrency rule at the entry.
• isStreaming 在 agent_end 监听器全部完成后才变回 false，所以 waitForIdle() 返回时 UI 一定已经处理完最后的事件。isStreaming turns false only after all agent_end listeners settle, so when waitForIdle() resolves the UI has handled the final events.
• handleRunFailure() 依次发出 message_start/end（error 消息）、turn_end、agent_end，订阅者看到的事件序列与正常结束同构。handleRunFailure() emits message_start/end (the error message), turn_end and agent_end, so subscribers see the same event shape as a normal ending.
• reset() 运行中抛错；空闲时清空消息与队列，但保留 system 基线消息。reset() throws while running; when idle it clears messages and queues but keeps the system baseline message.

工作原理How it works

1. prompt(input) 把字符串 / 图像规范化成 user 消息，调用 runPromptMessages()。prompt(input) normalizes string / images into user messages and calls runPromptMessages().
2. runWithLifecycle(executor) 创建 AbortController，置 isStreaming = true，执行 executor(signal)。runWithLifecycle(executor) creates an AbortController, sets isStreaming = true, runs executor(signal).
3. 异常 → handleRunFailure(error, aborted)；stopReason 取 aborted 或 error。On exception → handleRunFailure(error, aborted); stopReason becomes aborted or error.
4. finally → finishRun()：isStreaming = false、清 streamingMessage / pendingToolCalls、resolve 空闲等待者。finally → finishRun(): isStreaming = false, clear streamingMessage / pendingToolCalls, resolve idle waiters.

要点Key points

• Steering：Agent 运行中用户插入的消息，在当前轮的工具执行完成后、下一次 LLM 请求之前注入。Steering messages typed while the agent runs are injected after the current turn's tools finish, before the next LLM request.
• Follow-up：只在 Agent 本该停止时才投递，触发外层循环。Follow-up messages are delivered only when the agent would otherwise stop, and drive the outer loop.
• stopReason 为 length 时，该消息中所有工具调用直接判为失败，因为参数可能被截断。On stopReason: "length" every tool call in that message fails, because its arguments may be truncated.
• finishTurn 可返回 end（立即结束）或 continue（在无新消息时追加一次仅含上下文的轮次）。finishTurn can return end (stop now) or continue (run one more context-only turn when nothing else is queued).

工作原理How it works

1. 开始时先轮询一次 getSteeringMessages()，因为用户可能在等待时已经输入。It first polls getSteeringMessages(), since the user may have typed while waiting.
2. 从第二轮起调用 prepareNextTurn()；coding agent 在这里做阈值压缩并刷新工具清单。From the second turn it calls prepareNextTurn(); the coding agent compacts at threshold and refreshes the tool loadout here.
3. prepareRequest() 可覆盖 model 与 thinking level，然后 streamAssistantResponse() 依次执行 transformContext → convertToLlm → getApiKey → streamFn。prepareRequest() may override model and thinking level; then streamAssistantResponse() runs transformContext → convertToLlm → getApiKey → streamFn.
4. 若所有工具结果都带 terminate: true，内层循环在本轮后停止。If every tool result carries terminate: true, the inner loop stops after this turn.

要点Key points

• transformContext 作用于 AgentMessage[]（可含自定义消息），convertToLlm 再把它们转成 pi-ai 的 Message[]——压缩、裁剪放前者，格式转换放后者。transformContext works on AgentMessage[] (custom messages included); convertToLlm then turns them into pi-ai Message[] — pruning belongs in the former, format conversion in the latter.
• getApiKey 每次请求都调用，让短期 OAuth token 在长时间工具执行期间也能刷新。getApiKey is called on every request, so short-lived OAuth tokens can refresh during long tool runs.
• finishTurn 返回 { action: "end" } 可以在本轮后直接结束（跳过 steering 轮询）；prepareNextTurn 可以替换模型、工具、上下文。finishTurn returning { action: "end" } stops after this turn (skipping the steering poll); prepareNextTurn can swap model, tools or context.
• 工具集合变化时，declareToolChanges 在发送前插入带 toolsAdded/Removed 的 system 消息，保证 transcript 自描述。When the tool set changes, declareToolChanges inserts a system message with toolsAdded/Removed before sending, keeping the transcript self-describing.

工作原理How it works

1. 开始：发 agent_start、turn_start，把提示消息作为 message_start/end 发出。Start: emit agent_start, turn_start, then the prompt messages as message_start/end.
2. 请求：streamAssistantResponse() 依次调用请求侧钩子，把 pi-ai 事件映射为 message_*。Request: streamAssistantResponse() runs the request-side hooks and maps pi-ai events onto message_*.
3. 工具：每个 toolCall 经 prepareToolCall() → executePreparedToolCall() → finalizeExecutedToolCall()。Tools: each toolCall goes through prepareToolCall() → executePreparedToolCall() → finalizeExecutedToolCall().
4. 轮末：turn_end，轮询 steering；有消息或有工具结果就进入下一轮，否则检查 follow-up，最后 agent_end。Turn end: turn_end, poll steering; continue if there are messages or tool results, else check follow-ups, then agent_end.

要点Key points

• 参数用工具的 TypeBox schema 通过 validateToolArguments() 校验。Arguments are validated against the tool's TypeBox schema via validateToolArguments().
• coding agent 把 beforeToolCall / afterToolCall 映射为扩展事件 tool_call（可阻止）和 tool_result（可改写结果）。The coding agent maps beforeToolCall / afterToolCall to the extension events tool_call (can block) and tool_result (can rewrite).
• 模式为 ToolExecutionMode = "sequential" | "parallel"；只要批次中有一个工具声明 executionMode: "sequential"，整批就串行。ToolExecutionMode = "sequential" | "parallel"; if any tool in the batch declares executionMode: "sequential", the whole batch runs sequentially.
• runToolCall() 对外导出，供调用其他工具的工具复用同一套钩子（例如权限检查）。runToolCall() is exported so tools that call other tools reuse the same hooks (e.g. permission checks).

工作原理How it works

1. 并行模式下，准备阶段（含 beforeToolCall）按源顺序逐个进行，执行阶段并发。In parallel mode, preparation (including beforeToolCall) runs one by one in source order; execution runs concurrently.
2. tool_execution_end 在每个工具完成时发出；ToolResultMessage 则按原始顺序统一发出。tool_execution_end fires as each tool finishes; ToolResultMessages are emitted afterwards in the original order.
3. 执行中的 onUpdate 回调被转成 tool_execution_update 事件，用于流式显示 bash 输出等。onUpdate during execution becomes tool_execution_update events, used to stream bash output and similar.

要点Key points

• 立即结果（未知工具、参数校验失败、被 beforeToolCall 阻止）不进入执行，直接得到 error 结果。Immediate outcomes (unknown tool, failed validation, blocked by beforeToolCall) skip execution and get an error result directly.
• 1.1.0 新增：每个结果带 durationMs（performance.now() 计时），出现在 AgentToolCallOutcome 与 tool_execution_end 上。New in 1.1.0: every result carries durationMs (timed with performance.now()), on AgentToolCallOutcome and tool_execution_end.
• 只有批内每个最终结果都 terminate: true 时，循环才会在本批后停止——一个工具不能单方面结束对话。The loop stops after a batch only if every finalized result has terminate: true — a single tool can't end the conversation on its own.
• 输出被截断（stopReason: "length"）时，不执行任何工具调用，而是为每个调用写入失败结果。When output was truncated (stopReason: "length"), no tool call runs; each gets a failure result instead.

工作原理How it works

1. executeToolCalls() 根据 config.toolExecution 与各工具的 executionMode 选择顺序或并行。executeToolCalls() picks sequential or parallel from config.toolExecution and each tool's executionMode.
2. 并行：逐个 prepareToolCall()，把可执行的放入 Promise.all。Parallel: prepareToolCall() one by one, putting runnable calls into Promise.all.
3. 每个完成后 finalizeExecutedToolCall() 并立即发 tool_execution_end。Each completion is finalized and immediately emits tool_execution_end.
4. 全部完成后按原顺序 createToolResultMessage() 并发出消息事件。After all settle, createToolResultMessage() in source order and emit the message events.

要点Key points

• message_update 同时携带 assistantMessageEvent（原始 pi-ai 事件），UI 可以按 delta 精细渲染。message_update also carries assistantMessageEvent (the raw pi-ai event), so a UI can render per delta.
• 并行工具模式下 tool_execution_end 按完成顺序发出，但 toolResult 消息按调用的原始顺序发出。In parallel tool mode tool_execution_end fires in completion order, but toolResult messages are emitted in source order.
• Agent 的归约器在调用订阅者之前更新状态，所以监听器里读 agent.state 总是最新的。Agent's reducer updates state before calling subscribers, so agent.state read inside a listener is always current.

工作原理How it works

1. 流开始（start）：把 partial 推入上下文并发 message_start。Stream start (start): push the partial into context and emit message_start.
2. 每个 delta：用新的 partial 替换上下文末尾，发 message_update。Each delta: replace the context tail with the new partial and emit message_update.
3. done / error：取 result()，盖上 thinkingLevel，发 message_end。done / error: take result(), stamp thinkingLevel, emit message_end.

要点Key points

• 解析顺序：AgentOptions.streamFn → setDefaultStreamFn() 安装的全局默认 → 都没有则抛出 “No default stream function configured”。Resolution: AgentOptions.streamFn → the global default from setDefaultStreamFn() → otherwise throw “No default stream function configured”.
• 1.1.0 破坏性变更：streamProxy 与所有 StreamFn 必须返回 AssistantMessageEventStream（以便统一计时 durationMs）。Breaking in 1.1.0: streamProxy and every StreamFn must return AssistantMessageEventStream (so durationMs is timed uniformly).
• 代理只序列化 11 个可序列化选项；服务端发的事件不含 partial，以节省带宽。The proxy serializes only 11 serializable options; server events omit the partial to save bandwidth.

工作原理How it works

1. streamProxy(model, ctx, { proxyUrl, authToken }) 向 {proxyUrl}/api/stream 发 POST。streamProxy(model, ctx, { proxyUrl, authToken }) POSTs to {proxyUrl}/api/stream.
2. 读取 SSE data: 行，processProxyEvent() 把每个事件应用到本地 partial 上并推入流。Read SSE data: lines; processProxyEvent() applies each event to the local partial and pushes it.
3. HTTP 错误、EOF 无终止事件、abort 都被编码成 error 事件，不会抛出。HTTP errors, EOF without a terminal event, and aborts are all encoded as error events — never thrown.

要点Key points

• AgentState 的 tools 与 messages 赋值时复制数组；pendingToolCalls 每次替换为新的 Set，方便 UI 做引用比较。AgentState.tools and messages copy on assignment; pendingToolCalls is replaced with a new Set each time so UIs can compare by reference.
• AgentTool 继承 pi-ai Tool，增加 label、execute()、可选 prepareArguments() 与 executionMode。AgentTool extends pi-ai Tool with label, execute(), optional prepareArguments() and executionMode.
• AfterToolCallResult 按字段合并：替换 content 但不给 structuredContent 时，旧的 structuredContent 会被丢弃，避免两者不一致。AfterToolCallResult merges field by field: replacing content without structuredContent drops the old structuredContent, so the two never disagree.

工作原理How it works

1. 扩展消息类型：declare module "@earendil-works/pi-agent-core" { interface CustomAgentMessages { … } }。Extend messages: declare module "@earendil-works/pi-agent-core" { interface CustomAgentMessages { … } }.
2. 工具返回 AgentToolResult<T>：content 给模型，details 给 UI / 日志。Tools return AgentToolResult<T>: content for the model, details for UI / logs.