@agentproto/adapter-pi 0.2.0

package/README.md

@@ -0,0 +1,87 @@
+# @agentproto/adapter-pi
+
+AIP-45 AGENT-CLI adapter for **[earendil-works/pi](https://github.com/earendil-works/pi)**
+(`@earendil-works/pi-coding-agent`) — an MIT, headless TypeScript coding
+agent. This adapter drives pi over its **persistent JSON-over-stdio RPC mode**
+(`pi --mode rpc`), spawned as a real child process.
+
+```ts
+import { pi, piRuntime } from "@agentproto/adapter-pi"
+
+const session = await piRuntime().start()
+for await (const evt of session.send({ role: "user", content: "list the files" })) {
+  console.log(evt.kind)
+}
+await session.close()
+```
+
+## MCP support — bridged into pi tools
+
+Pi ships **no native MCP client** — but this adapter closes that gap. When the
+host injects `mcpServers` into `connect()` (the daemon's orchestration gateway,
+or any scoped toolset), the adapter **bridges** them into pi by exploiting pi's
+own TypeScript **extension** system:
+
+1. At `connect()`, it enumerates each server's tools (`tools/list`), writes a
+   per-session config JSON, and spawns pi with `-e <mcp-bridge-extension.mjs>`
+   plus `PI_MCP_BRIDGE_CONFIG`.
+2. The bundled extension registers **one pi tool per MCP tool** (namespaced
+   `mcp__<server>__<tool>`); each tool's `execute` proxies the call to the MCP
+   server over `@modelcontextprotocol/sdk`.
+
+Net result: pi gains agentproto's full injected toolset, **including
+`agent_start`** when the daemon injects its gateway (`--orchestrator` flag),
+enabling sub-agent orchestration (`capabilities.sub_agents: true`). When no
+MCP servers are injected, behavior is unchanged (pi runs only its own
+built-in file/shell tools). Full mechanism, limitations, and caveats
+(image/binary-content, cancellation): [`MCP-BRIDGE.md`](./MCP-BRIDGE.md).
+
+## What it is
+
+Because pi has no native ACP/MCP protocol surface, this is a
+`protocol: "proprietary"` manifest:
+`createAgentCliRuntime` skips the built-in ACP/print subprocess plumbing and
+instead dynamic-imports this package's `createAgentCliClient(definition)`
+factory (see `createProprietaryProtocolArm` in `@agentproto/driver-agent-cli`).
+Unlike `@agentproto/adapter-mastracode-inprocess` (the in-process proprietary
+arm), **this arm spawns a real child** (`pi --mode rpc`) and translates pi's
+RPC event stream into the canonical `StreamEvent` taxonomy.
+
+- **Multi-provider** — Anthropic, OpenAI, Google (Gemini). One provider key
+  minimum. See [`SECRETS.md`](./SECRETS.md).
+- **Streaming** — text + thinking deltas, tool-call/result lifecycle.
+- **Live duplex** — pi's RPC mode supports `steer` / `follow_up` / `abort`
+  mid-turn (`capabilities.bidirectional: true`).
+- **Resumable** — pi persists sessions; the client captures pi's session id
+  from `get_state` and reattaches via `--session <id>`
+  (`continuation.default: "native-resume"`).
+
+## Configuration
+
+| Option   | Type   | Notes |
+| -------- | ------ | ----- |
+| `model`  | string | Passed to pi's `--model` (accepts `provider/id`, e.g. `anthropic/claude-sonnet-4-5`). |
+| `effort` | enum   | Thinking level, mapped 1:1 to pi's `set_thinking_level`: `off \| minimal \| low \| medium \| high \| xhigh`. |
+
+The pi binary is resolved from `definition.bin` (`pi`), overridable via the
+`AGENTPROTO_PI_BIN` env var (used by the gated smoke test to point at a local
+install without a global `pi` on PATH).
+
+## Safety
+
+Pi has **no built-in permission system** — file, process, network and
+credential access run with the launching user's permissions, and non-interactive
+modes (including `--mode rpc`) show no trust prompt. Treat a pi session as
+arbitrary code execution. See [`SANDBOX.md`](./SANDBOX.md).
+
+## Docs in this package
+
+- [`PI.md`](./PI.md) — AIP-45 manifest overview.
+- [`PI-RPC.md`](./PI-RPC.md) — the reverse-engineered RPC wire profile + the
+  pi-event → `StreamEvent` mapping table.
+- [`SECRETS.md`](./SECRETS.md) — provider env slots.
+- [`SANDBOX.md`](./SANDBOX.md) — no built-in permissions; containerization.
+
+Built against pi **0.80.3**. The event/command wire profile was
+reverse-engineered from pi source (`packages/coding-agent/src/modes/rpc/*` +
+`core/agent-session.ts`); see `PI-RPC.md`.

package/SANDBOX.md

@@ -0,0 +1,63 @@
+# Pi — sandbox & safety profile
+
+## Pi has NO built-in permission system
+
+This is not an opinion — it is pi's own documented position. From pi's
+README (`## Permissions & Containerization`):
+
+> Pi does not include a built-in permission system for restricting filesystem,
+> process, network, or credential access. By default, it runs with the
+> permissions of the user and process that launched it.
+
+And, critically for this adapter, from pi's coding-agent README:
+
+> Non-interactive modes (`-p`, `--mode json`, and `--mode rpc`) do not show a
+> trust prompt.
+
+> **No permission popups.** Run in a container, or build your own confirmation
+> flow with extensions inline with your environment and security requirements.
+
+> **Security:** Pi packages run with full system access. Extensions execute
+> arbitrary code, and skills can instruct the model to perform any action
+> including running executables.
+
+Because this adapter drives pi via `--mode rpc` — a **non-interactive** mode —
+there is **no trust prompt and no approval gate**. Every `bash`, `write`,
+`edit` the model decides to run executes immediately with the launching
+process's full OS permissions.
+
+**Treat a pi session as arbitrary code execution on the host.**
+
+## Recommendation: containerize
+
+Pi's own guidance is to sandbox the whole process. Do not run this adapter
+against untrusted repos or prompts on a host you care about. Pi documents three
+patterns in `packages/coding-agent/docs/containerization.md`:
+
+- run pi inside a Docker/OCI container scoped to the target workspace;
+- restrict network egress at the container/VM boundary;
+- **OpenShell** — run the whole `pi` process in a policy-controlled sandbox.
+
+Prefer running the agentproto daemon (and therefore the spawned `pi --mode rpc`
+child) inside such a boundary, with only the target working directory mounted
+and only the provider API egress it needs.
+
+## MCP substrate is unavailable (defense-in-depth note)
+
+Pi has no MCP, so the daemon **cannot** narrow pi's tool surface by mounting a
+curated MCP toolset — pi always exposes its own built-in file/shell tools, and
+`connect({ mcpServers })` is ignored (with a one-time warning). There is no
+"allowed tools" lever at the protocol layer here: the only enforcement boundary
+is the OS/container sandbox you place pi in. This is a meaningful difference
+from the ACP adapters, where the host chooses the mounted toolset.
+
+## What the adapter does / doesn't isolate
+
+- **Working directory** — the runner spawns `pi --mode rpc` with the
+  host-chosen `cwd`; pi's file tools operate relative to it. This is scoping,
+  not a security boundary.
+- **Env / secrets** — only the runner-injected env (provider keys + host env)
+  reaches the child. Keys are never logged.
+- **Process** — the adapter owns the child and kills it (`SIGTERM`, after
+  `stdin.end()`) on `close()` / abort. It does **not** confine what the child
+  does while alive. That is the sandbox's job.

package/SECRETS.md

@@ -0,0 +1,48 @@
+---
+name: pi-secrets
+id: pi-secrets
+description: Secret slots pi reads at boot. At minimum ONE model-provider key MUST be present — pi routes each turn to whichever provider the selected model belongs to (Anthropic / OpenAI / Google).
+version: 0.1.0
+slots:
+  - name: ANTHROPIC_API_KEY
+    description: Anthropic API key — enables `anthropic/claude-*` models (adapter default provider).
+    required: false
+    sensitivity: high
+  - name: OPENAI_API_KEY
+    description: OpenAI API key — enables `openai/gpt-*` models.
+    required: false
+    sensitivity: high
+  - name: GOOGLE_GENERATIVE_AI_API_KEY
+    description: Google Generative AI (Gemini) key — enables `google/gemini-*` models.
+    required: false
+    sensitivity: high
+constraints:
+  - kind: at-least-one-of
+    of:
+      - ANTHROPIC_API_KEY
+      - OPENAI_API_KEY
+      - GOOGLE_GENERATIVE_AI_API_KEY
+tags: [pi, secrets, model-providers]
+---
+
+# Pi — secrets inventory
+
+Pi routes each turn to the provider that owns the selected model. The adapter
+declares the three provider key slots pi's supported providers read from the
+process environment:
+
+| Env var | Provider | Unlocks |
+| ------- | -------- | ------- |
+| `ANTHROPIC_API_KEY` | Anthropic | `anthropic/claude-*` (adapter default) |
+| `OPENAI_API_KEY` | OpenAI | `openai/gpt-*` |
+| `GOOGLE_GENERATIVE_AI_API_KEY` | Google | `google/gemini-*` |
+
+**At least one** must be present, and it must match the provider of the model
+you route to (`models.default` is `anthropic/claude-sonnet-4-5`, so
+`ANTHROPIC_API_KEY` is the natural minimum). Keys are injected into the spawned
+`pi --mode rpc` child's environment by the runner (from the workspace secrets
+store) and are never logged.
+
+Pi also accepts a per-invocation `--api-key`, but this adapter relies on the
+env slots above so key material flows through the runner's secrets pipeline
+rather than argv.

package/dist/index.d.ts

@@ -0,0 +1,209 @@
+import { AgentCliHandle, AgentCliClient, StreamEvent, AgentCliRuntime } from '@agentproto/driver-agent-cli';
+export { AgentCliHandle, AgentCliRuntime } from '@agentproto/driver-agent-cli';
+
+/**
+ * `AgentCliClient` for pi (`@earendil-works/pi-coding-agent`), driven over
+ * its persistent JSON-over-stdio RPC mode.
+ *
+ * Unlike `@agentproto/adapter-mastracode-inprocess` (the other
+ * `protocol: "proprietary"` arm, which runs in-process), this arm spawns a
+ * real child: `pi --mode rpc`. It writes RPC commands (LF-delimited JSON) to
+ * the child's stdin and reads pi's response + `AgentSessionEvent` stream from
+ * stdout, translating the events into agentproto `StreamEvent`s.
+ *
+ * ## MCP support — bridged via a generated pi extension
+ *
+ * Pi ships neither ACP nor MCP. The proprietary arm's `connect()` receives
+ * `mcpServers` (the host may inject the daemon's own orchestration gateway or
+ * any scoped toolset). Pi cannot mount MCP natively, so this arm bridges them:
+ * it enumerates each server's tools up-front, writes a per-session config JSON,
+ * and spawns pi with `-e <mcp-bridge-extension.mjs>` + `PI_MCP_BRIDGE_CONFIG`.
+ * The extension registers one pi tool per MCP tool and proxies calls over
+ * `@modelcontextprotocol/sdk`. See ../MCP-BRIDGE.md. When no MCP servers are
+ * injected, behavior is unchanged (pi runs only its own file/shell tools).
+ */
+
+declare function createAgentCliClient(definition: AgentCliHandle): AgentCliClient;
+
+/**
+ * Pi RPC wire types + the pure pi-event → {@link StreamEvent} mapper.
+ *
+ * Pi (`@earendil-works/pi-coding-agent`) exposes a persistent
+ * JSON-over-stdio RPC mode (`pi --mode rpc`). Its stdout carries two
+ * kinds of LF-delimited JSON records:
+ *
+ *   1. **Responses** — `{ type: "response", command, success, id?, data?, error? }`,
+ *      correlated to a command by the `id` echoed back. Handled by the
+ *      client's request/response layer.
+ *   2. **Session events** — the `AgentSessionEvent` union emitted by pi's
+ *      `session.subscribe(...)` (assistant text/thinking deltas, tool
+ *      execution lifecycle, turn/agent lifecycle). These are what this
+ *      module narrows and maps onto agentproto's canonical taxonomy.
+ *
+ * Everything here is pure and synchronous so it can be unit-tested
+ * against hand-built pi records without spawning a real `pi`.
+ *
+ * Wire profile documented in ../PI-RPC.md.
+ */
+
+/** Pi `StopReason` (packages/ai/src/types.ts). */
+type PiStopReason = "stop" | "length" | "toolUse" | "error" | "aborted";
+/** Pi `Usage` (packages/ai/src/types.ts) — token + cost accounting on an
+ *  assistant message. Only the fields this adapter surfaces are modelled. */
+interface PiUsage {
+    input: number;
+    output: number;
+    totalTokens: number;
+    cost: {
+        total: number;
+    };
+}
+/** Minimal shape of an assistant `AgentMessage` carried on `turn_end`. */
+interface PiTurnMessage {
+    role: string;
+    stopReason?: PiStopReason;
+    usage?: PiUsage;
+    errorMessage?: string;
+}
+/** Assistant-message-event types this adapter does NOT translate but must
+ *  still discriminate cleanly (keeps `PiAssistantMessageEvent` exhaustive). */
+type PiIgnoredAssistantEventType = "start" | "text_start" | "text_end" | "thinking_start" | "thinking_end" | "toolcall_start" | "toolcall_delta" | "toolcall_end";
+/** Pi `AssistantMessageEvent` (packages/ai/src/types.ts), narrowed to the
+ *  fields this adapter reads. Streaming deltas + the terminal done/error. */
+type PiAssistantMessageEvent = {
+    type: "text_delta";
+    delta: string;
+} | {
+    type: "thinking_delta";
+    delta: string;
+} | {
+    type: "done";
+    reason: "stop" | "length" | "toolUse";
+} | {
+    type: "error";
+    reason: "error" | "aborted";
+    errorMessage?: string;
+} | {
+    type: PiIgnoredAssistantEventType;
+};
+/** Pi `AgentSessionEvent` (packages/coding-agent/src/core/agent-session.ts +
+ *  packages/agent/src/types.ts `AgentEvent`), narrowed to the events this
+ *  adapter acts on. Any other pi event is dropped before it reaches here. */
+type PiSessionEvent = {
+    type: "agent_start";
+} | {
+    type: "agent_end";
+    willRetry?: boolean;
+} | {
+    type: "turn_start";
+} | {
+    type: "turn_end";
+    message?: PiTurnMessage;
+} | {
+    type: "message_update";
+    assistantMessageEvent: PiAssistantMessageEvent;
+} | {
+    type: "tool_execution_start";
+    toolCallId: string;
+    toolName: string;
+    args: unknown;
+} | {
+    type: "tool_execution_end";
+    toolCallId: string;
+    toolName: string;
+    result: unknown;
+    isError: boolean;
+} | {
+    type: "agent_settled";
+};
+/** A pi RPC response line (`type: "response"`). */
+interface PiResponse {
+    type: "response";
+    id?: string;
+    command: string;
+    success: boolean;
+    error?: string;
+    data?: unknown;
+}
+/** Classified pi stdout line. `other` covers extension-UI requests, the
+ *  json-mode session header, and anything this adapter ignores. */
+type PiOutbound = {
+    kind: "response";
+    response: PiResponse;
+} | {
+    kind: "event";
+    event: PiSessionEvent;
+} | {
+    kind: "other";
+};
+/**
+ * Parse + classify one pi stdout JSON line. Returns `{ kind: "other" }` for
+ * malformed lines and any record this adapter does not act on, so the caller
+ * can uniformly ignore them.
+ */
+declare function classifyPiLine(line: string): PiOutbound;
+/** Carried across a turn's events — pi reports the stop reason mid-stream
+ *  (`message_update` done/error, `turn_end.message.stopReason`) but the
+ *  turn only truly closes on `agent_settled`, so it must be remembered. */
+interface PiMapperState {
+    lastStopReason: PiStopReason | undefined;
+}
+declare function createPiMapperState(): PiMapperState;
+/** Reset for a fresh turn (call in the client's `send`). */
+declare function resetPiMapperState(state: PiMapperState): void;
+/** Map a pi `StopReason` onto the canonical `turn-end` reason.
+ *  `length` (token/context cap) has no exact equivalent; `max_turns` is the
+ *  closest "hit a budget limit" reason. `toolUse` is never the settled
+ *  reason (the loop keeps going) but falls back to `completed` defensively. */
+declare function mapStopReason(reason: PiStopReason | undefined): "completed" | "cancelled" | "max_turns" | "error";
+/**
+ * Translate one pi session event into zero or more {@link StreamEvent}s,
+ * updating `state` in place. Pure aside from the state mutation.
+ *
+ * `agent_end` (with `willRetry` false) is the turn terminator: it flushes a
+ * `turn-end` whose reason reflects the stop reason accumulated over the turn.
+ * An `agent_end` with `willRetry: true` (auto-retry) does NOT close the turn —
+ * pi will run again and emit a final `agent_end`. NOTE: pi's `agent_settled`
+ * event is emitted to in-process extension listeners but is NOT written to the
+ * RPC stdout stream (verified empirically against pi 0.80.3), so it cannot be
+ * relied on as the terminator — see PI-RPC.md.
+ */
+declare function mapPiEvent(event: PiSessionEvent, sessionId: string, state: PiMapperState): StreamEvent[];
+
+/**
+ * @agentproto/adapter-pi — AIP-45 adapter for **earendil-works/pi**
+ * (`@earendil-works/pi-coding-agent`), an MIT TypeScript headless coding
+ * agent.
+ *
+ * Pi ships **no ACP and no MCP** — but it does ship a persistent
+ * JSON-over-stdio RPC mode (`pi --mode rpc`). So this is a
+ * `protocol: "proprietary"` manifest: `createAgentCliRuntime` skips the
+ * built-in ACP/print subprocess plumbing and instead dynamic-imports this
+ * package's `createAgentCliClient(definition)` factory (see
+ * `createProprietaryProtocolArm` in `@agentproto/driver-agent-cli`). Unlike
+ * the in-process mastracode arm, THIS arm spawns a real child (`pi --mode
+ * rpc`) and translates pi's RPC event stream — see `./client.ts`.
+ *
+ *   import { pi, piRuntime } from "@agentproto/adapter-pi"
+ *   const session = await piRuntime().start()
+ *   for await (const evt of session.send({ role: "user", content: "..." })) {
+ *     console.log(evt)
+ *   }
+ *   await session.close()
+ *
+ * ## MCP support — bridged via a generated pi extension
+ *
+ * Pi has no native MCP client, but the proprietary arm's `connect()` receives
+ * `mcpServers` and now bridges them: it enumerates each server's tools, writes a
+ * per-session config, and spawns pi with `-e <mcp-bridge-extension.mjs>` so the
+ * extension registers one pi tool per MCP tool (proxying calls over
+ * `@modelcontextprotocol/sdk`). Injected toolsets — including the daemon's
+ * `agent_start` orchestration gateway — become callable from pi. When no MCP
+ * servers are injected, pi runs only its own built-in file/shell tools. See
+ * MCP-BRIDGE.md, README.md, and SANDBOX.md.
+ */
+
+declare const pi: AgentCliHandle;
+declare function piRuntime(): AgentCliRuntime;
+
+export { type PiAssistantMessageEvent, type PiMapperState, type PiOutbound, type PiResponse, type PiSessionEvent, type PiStopReason, type PiTurnMessage, type PiUsage, classifyPiLine, createAgentCliClient, createPiMapperState, mapPiEvent, mapStopReason, pi, piRuntime, resetPiMapperState };