AgentSession 类，而不是起一个子进程走 RPC。| 路径 | 形态 | 适合 |
|---|---|---|
-p "prompt" | 一次性执行，纯文本输出 | 脚本、CI |
--mode json | 事件流，JSON Lines 到 stdout | 接进其它工具、自定义 UI |
--mode rpc | stdin/stdout 上的 JSON 协议，双向 | 非 Node 语言、IDE 插件 |
SDK（AgentSession） | 直接当库用，同进程 | Node/TS 应用（首选） |
另外还有一个 packages/protocol + packages/server 的二进制协议，标着 experimental——那是给「会话服务端」用的，与上面四条不是一回事。
RPC mode enables headless operation of the coding agent via a JSON protocol over
stdin/stdout. This is useful for embedding the agent in other applications, IDEs, or custom UIs.
**Note for Node.js/TypeScript users**: If you're building a Node.js application, consider
using `AgentSession` directly from `@earendil-works/pi-coding-agent` instead of spawning
a subprocess.pi --mode json "prompt" 把全部会话事件按 JSON Lines 输出。json.md:7 事件种类与 第 03 章的循环事件同源——agent_start / turn_start / message_update / tool_execution_*。
换句话说，无头模式暴露的是循环的内部结构，而不是一个封装好的「答案」。要拿最终文本，你得自己从事件流里挑。
Protocol version `1` uses binary messages with this wire layout:
1. A four-byte unsigned big-endian payload length.
2. One definite-length CBOR item containing the message.
… Session and server snapshots are authoritative. Progress events are transient UI
hints and must not be reduced into authoritative state.这条规则与 第 08 章harness-v2 的 UI 模型是同一条：客户端拿一次原子快照，然后接实时事件流；事件不重放，重连就是拿新快照。两处独立表述了同一个约束，说明它是这套架构里想清楚了的部分。
看似冗余，实际对应四种不同的调用方约束：
-p：调用方是 shell，只要 stdout；--mode json：调用方要看过程，但不需要回话（单向）；--mode rpc：调用方要双向交互（steering、审批），且不是 Node；关键在最后一条：如果 SDK 可用，RPC 就是纯粹的开销。文档把这件事说破，而不是让每个 Node 用户自己踩一遍。
一个流式 agent 的客户端有两个信息来源：初始快照和实时事件。允许客户端把事件归约进状态，就等于要求事件流无丢失、无重复、严格有序——那是分布式系统里最贵的保证之一。
pi 的做法是拒绝支付这个成本：事件只用来更新界面，权威状态永远来自快照；断线了就重新拿快照。代价是重连成本高（要传整个快照），收益是事件通道可以不可靠。
对一个「事件是 token 级、每秒几十条」的系统，这个取舍显然正确。
packages/server 与 packages/protocol 标着 experimental，README 第一行就说可能变更或移除。基于它们做集成是在赌路线图。AgentSession 来自 coding-agent 包——那是产品层（第 02 章），不像 pi-ai / pi-agent-core 那样以库的姿态维护。-p、--mode json、--mode rpc 都不弹 project trust 询问，默认忽略需信任的项目资源（第 15 章）。集成时要显式决定用 --approve 还是保持默认。result 事件把答案单独给你。-p 这样的纯文本路径。场景pi --mode json 跑完了一个任务。「最终答案」在输出的哪里？
B。无头模式暴露的是循环的事件结构（agent_start / message_update / tool_execution_*），「什么算完成」由调用方定义。简单场景请用 -p。
ac4ac9e（2026-08-07 快照）。