Pi RPC and SDK integration
Grounding
pi-mono/packages/coding-agent/docs/rpc.md— Framing section (LF-only record delimiter;readlineincompatibility with U+2028/U+2029).pi-mono/packages/coding-agent/docs/sdk.md— programmatic session patterns pluscreateAgentSession,AgentSession,createAgentSessionRuntime,ModelRegistry.create(),AuthStorage.create(), andSessionManager.inMemory().pi-mono/packages/coding-agent/docs/json.md—--mode jsonevent stream: session header,agent_*/turn_*/message_*/tool_execution_*events,jqfiltering examples.pi-mono/packages/coding-agent/src/modes/rpc/rpc-client.ts— reference TypeScript client mentioned fromrpc.mdintro when applicable.pi-mono/packages/coding-agent/src/core/agent-session.ts— API surface for in-process embedding (perrpc.mdnote to TypeScript users).
Invariants
- Framing rules are normative text in
pi-mono/packages/coding-agent/docs/rpc.md; quote or paraphrase strictly from that file when advising client implementers. - Skill commands and prompt templates are expanded for RPC prompts per
rpc.mdInput expansion bullet underpromptcommand. --mode jsonis read-only observation (stdout events);--mode rpcis bidirectional control (stdin commands + stdout responses). Different use cases, same framing caveats for U+2028/U+2029.- For TypeScript/Node embedding,
createAgentSession()is the primary factory; it requiressessionManager,authStorage, andmodelRegistry. For advanced multi-session hosting, usecreateAgentSessionRuntime()which returnsAgentSessionRuntimewith lower-level access toagent,sessionManager,settingsManager,modelRegistry,extensions,bashExecutor,resourceLoader—pi-mono/packages/coding-agent/docs/sdk.md.
Workflows
- Choose integration: If user is on Node/TS, point to
rpc.mdrecommendation to preferAgentSessionvs subprocess; cite the file’s opening Note for Node.js/TypeScript users. - Debug framing: Re-read Framing section; do not suggest generic line readers as compliant.
- JSON event stream: For read-only observation of agent activity, point to
json.md(--mode json); for bidirectional control, point torpc.md(--mode rpc). - In-process embedding: For TypeScript/Node users who don't need subprocess isolation, prefer
createAgentSession()over--mode rpc. Import from@mariozechner/pi-coding-agent. Seepi-mono/packages/coding-agent/docs/sdk.mdandpi-mono/packages/coding-agent/examples/sdk/.
Anti-patterns
- Do not describe delimiter behavior contradicting
rpc.md(only\nas record delimiter; optional\rstrip on input).