privateer-agent 0.1.1 → 0.3.0

package/bin/privateer-tui

@@ -0,0 +1,86 @@
+#!/usr/bin/env bash
+# Launch Pi's full interactive TUI with the Privateer moat + tool packs. The moat is
+# installed as re-export SHIMS in the agent dir's extensions/, so BOTH this TUI and
+# any subagents it spawns (which run as child `pi` processes reading the agent dir)
+# load the identical set — including our permission gate. So subagent tool calls are
+# gated too (the gate runs bypass-within-restricted-tools headlessly; danger.ts still
+# blocks destructive shell). One source of truth via discovery — no -e (which would
+# double-load vs discovery).
+#
+# Runs in the current directory. Model via PRIVATEER_MODEL=provider/id.
+set -euo pipefail
+# Resolve through symlinks so REPO points at the real repo, not the symlink dir.
+SOURCE="${BASH_SOURCE[0]}"
+while [ -h "$SOURCE" ]; do
+  DIR="$(cd -P "$(dirname "$SOURCE")" && pwd)"
+  SOURCE="$(readlink "$SOURCE")"
+  [ "${SOURCE#/}" = "$SOURCE" ] && SOURCE="$DIR/$SOURCE"
+done
+REPO="$(cd -P "$(dirname "$SOURCE")/.." && pwd)"
+
+pick_node() {
+  if command -v node >/dev/null 2>&1 \
+     && node -e 'process.exit((+process.versions.node.split(".")[0]) >= 22 ? 0 : 1)' 2>/dev/null; then
+    command -v node; return
+  fi
+  for c in "$HOME"/.nvm/versions/node/v22*/bin/node; do
+    [ -x "$c" ] && { echo "$c"; return; }
+  done
+  echo "node"
+}
+
+AGENT_DIR="${PRIVATEER_HOME:-$HOME/.privateer}/agent"
+EXT_DIR="$AGENT_DIR/extensions"
+mkdir -p "$EXT_DIR"
+
+# Install/refresh the moat + tool-pack shims. Each shim re-exports its target by
+# ABSOLUTE path so the target's own relative imports resolve from the repo (a plain
+# symlink would resolve them relative to the shim's location and break). We remove
+# any shim we previously managed first, so a dropped package can't linger and reload.
+MANAGED="privateer-brand privateer-gate privateer-account privateer-posture privateer-tools privateer-privacy pi-privacy pi-web-access rpiv-web-tools pi-mcp-adapter pi-hypa pi-subagents"
+for name in $MANAGED; do rm -f "$EXT_DIR/$name.ts"; done
+shim() { printf 'export { default } from "%s";\n' "$2" > "$EXT_DIR/$1.ts"; }
+# Branding + the account sign-in surface (banner, ⚓ badge, /signin /signout).
+shim privateer-brand   "$REPO/extensions/privateer-brand.ts"
+shim privateer-gate    "$REPO/extensions/privateer-gate.ts"
+shim privateer-account "$REPO/extensions/privateer-account.ts"
+shim privateer-posture "$REPO/extensions/privateer-posture.ts"
+shim privateer-tools   "$REPO/extensions/privateer-tools.ts"
+# pi-privacy wrapped with the account-channel tier resolver (privateer/near… = TEE),
+# so it replaces loading pi-privacy's default entry.
+shim privateer-privacy "$REPO/extensions/privateer-privacy.ts"
+# Privacy-aligned web tools: pluggable backends (SearXNG self-hosted = private; no
+# WebView). Pick the backend with /web-tools, or set SEARXNG_URL. Replaces
+# pi-web-access (opened a WebView + defaulted to Exa, a 3rd-party search).
+shim rpiv-web-tools    "$REPO/node_modules/@juicesharp/rpiv-web-tools/index.ts"
+shim pi-mcp-adapter    "$REPO/node_modules/pi-mcp-adapter/index.ts"
+shim pi-hypa           "$REPO/node_modules/@hypabolic/pi-hypa/extensions/index.ts"
+shim pi-subagents      "$REPO/node_modules/pi-subagents/src/extension/index.ts"
+
+CLI="$REPO/node_modules/@earendil-works/pi-coding-agent/dist/cli.js"
+export PI_CODING_AGENT_DIR="$AGENT_DIR"
+NODE_BIN="$(pick_node)"
+
+# Quiet Pi's built-in startup resource listing ([Extensions]/[Context]/[Skills]/…) by
+# default — our banner is the intended startup surface, and the extension list is noise.
+# Only set it when unset, so a later `--verbose` or a user's own settings toggle sticks.
+"$NODE_BIN" -e '
+const fs = require("fs"), p = process.argv[1];
+let s = {}; try { s = JSON.parse(fs.readFileSync(p, "utf8")); } catch {}
+if (s.quietStartup === undefined) { s.quietStartup = true; fs.writeFileSync(p, JSON.stringify(s, null, 2) + "\n"); }
+' "$AGENT_DIR/settings.json" 2>/dev/null || true
+
+# Default model: when signed in to a Privateer account, default to GLM 5.1 on the
+# account's NEAR confidential-compute (TEE) channel — attestable, strongest privacy
+# tier. Otherwise (BYO key, no account) fall back to a cheap OpenRouter model. An
+# explicit PRIVATEER_MODEL always wins.
+CRED="${PRIVATEER_HOME:-$HOME/.privateer}/credentials.json"
+if [ -n "${PRIVATEER_MODEL:-}" ]; then
+  MODEL="$PRIVATEER_MODEL"
+elif [ -f "$CRED" ]; then
+  MODEL="privateer/near/zai-org/GLM-5.1-FP8"
+else
+  MODEL="openrouter/openai/gpt-4o-mini"
+fi
+
+exec "$NODE_BIN" --env-file="$REPO/.env" "$CLI" --model "$MODEL" "$@"

package/bin/privateer.mjs

@@ -1,11 +1,22 @@
 #!/usr/bin/env node
-// Privateer launcher. Registers tsx's ESM loader so the TypeScript/JSX
-// entrypoint runs with no build step. (Phase 6 can add a compiled binary path.)
+// Launcher for the privateer 0.3 agent REPL. It runs in the DIRECTORY YOU INVOKE
+// IT FROM (process.cwd() — that's the agent's working dir), while resolving the
+// code and dev keys from the repo. Prefer the `bin/pv` wrapper, which also picks a
+// Node >= 22 (the Pi stack's floor).
+import { register } from "tsx/esm/api";
 import { fileURLToPath } from "node:url";
 import { dirname, resolve } from "node:path";
-import { register } from "tsx/esm/api";
 
-const __dirname = dirname(fileURLToPath(import.meta.url));
+const here = dirname(fileURLToPath(import.meta.url));
+const repo = resolve(here, "..");
+
+// Dev convenience: load provider keys from the repo's .env if present, WITHOUT
+// changing cwd. (A real install would rely on env vars / ~/.privateer instead.)
+try {
+  process.loadEnvFile(resolve(repo, ".env"));
+} catch {
+  /* no .env — fall back to the ambient environment */
+}
 
-register();
-await import(resolve(__dirname, "../src/main.tsx"));
+register(); // resolves the repo's tsx regardless of the invocation cwd
+await import(resolve(repo, "src/cli/chat.ts"));

package/bin/pv

@@ -0,0 +1,28 @@
+#!/usr/bin/env bash
+# Launch the privateer 0.3 dev agent in the CURRENT directory. Picks a Node >= 22
+# (the Pi stack's floor): the active node if new enough, else an nvm-installed v22.
+# Symlink this onto your PATH under whatever name you like (it does NOT have to be
+# `pv`), e.g.:  ln -s "$PWD/bin/pv" /usr/local/bin/pv
+set -euo pipefail
+# Resolve through symlinks so REPO points at the real repo, not the symlink dir.
+SOURCE="${BASH_SOURCE[0]}"
+while [ -h "$SOURCE" ]; do
+  DIR="$(cd -P "$(dirname "$SOURCE")" && pwd)"
+  SOURCE="$(readlink "$SOURCE")"
+  [ "${SOURCE#/}" = "$SOURCE" ] && SOURCE="$DIR/$SOURCE"
+done
+REPO="$(cd -P "$(dirname "$SOURCE")/.." && pwd)"
+
+pick_node() {
+  if command -v node >/dev/null 2>&1 \
+     && node -e 'process.exit((+process.versions.node.split(".")[0]) >= 22 ? 0 : 1)' 2>/dev/null; then
+    command -v node
+    return
+  fi
+  for c in "$HOME"/.nvm/versions/node/v22*/bin/node; do
+    [ -x "$c" ] && { echo "$c"; return; }
+  done
+  echo "node" # last resort — errors clearly if it's too old
+}
+
+exec "$(pick_node)" "$REPO/bin/privateer.mjs" "$@"

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "privateer-agent",
-  "version": "0.1.1",
-  "description": "Privateer — a provider-agnostic terminal coding agent. Bring your own model (OpenRouter, Anthropic, OpenAI, Ollama, NEAR AI).",
+  "version": "0.3.0",
+  "description": "Privateer — a provider-agnostic, safe-by-default terminal coding agent with TEE/Tinfoil attestation, rebuilt on the Pi toolkit. Bring your own model across 20 providers.",
   "type": "module",
   "license": "MIT",
   "author": "Patrick (zahnno)",
@@ -15,15 +15,17 @@
     "cli",
     "tui",
     "terminal",
+    "pi",
+    "tee",
+    "confidential-computing",
+    "attestation",
+    "tinfoil",
     "openrouter",
     "anthropic",
     "openai",
     "ollama",
     "nearai",
-    "tee",
-    "confidential-computing",
-    "ai-sdk",
-    "ink"
+    "venice"
   ],
   "bin": {
     "privateer": "./bin/privateer.mjs"
@@ -38,37 +40,38 @@
     "LICENSE"
   ],
   "scripts": {
-    "start": "tsx src/main.tsx",
-    "dev": "tsx watch src/main.tsx",
+    "start": "tsx src/main.ts",
+    "chat": "node --env-file=.env --import tsx src/cli/chat.ts",
+    "dev": "tsx watch src/main.ts",
     "typecheck": "tsc --noEmit",
     "test": "for f in tests/*.test.ts; do node --import tsx --test \"$f\" || exit 1; done"
   },
   "engines": {
-    "node": ">=20"
+    "node": ">=22.19.0"
   },
   "dependencies": {
-    "@ai-sdk/anthropic": "^2.0.0",
-    "@ai-sdk/openai": "^2.0.0",
-    "@modelcontextprotocol/sdk": "^1.29.0",
-    "@openrouter/ai-sdk-provider": "^1.0.0",
-    "@types/picomatch": "^4.0.3",
-    "ai": "^5.0.0",
-    "commander": "^12.0.0",
-    "ink": "^5.0.0",
-    "ink-spinner": "^5.0.0",
-    "ink-text-input": "^6.0.0",
-    "ollama-ai-provider-v2": "^1.2.0",
+    "@earendil-works/pi-ai": "^0.80.3",
+    "@earendil-works/pi-coding-agent": "^0.80.3",
+    "@earendil-works/pi-tui": "^0.80.3",
+    "@hypabolic/pi-hypa": "^0.1.6",
+    "@juicesharp/rpiv-web-tools": "^1.20.0",
+    "@noble/ciphers": "^2.1.1",
+    "@noble/curves": "^1.9.7",
+    "@noble/hashes": "^1.7.1",
+    "pi-mcp-adapter": "^2.11.0",
+    "pi-privacy": "^0.2.0",
+    "pi-subagents": "^0.34.0",
     "picomatch": "^4.0.4",
-    "react": "^18.3.1",
     "tsx": "^4.16.0",
+    "typebox": "^1.3.4",
+    "undici": "^7.28.0",
     "ws": "^8.21.0",
     "zod": "^4.0.16"
   },
   "devDependencies": {
     "@types/node": "^20.14.0",
-    "@types/react": "^18.3.3",
+    "@types/picomatch": "^4.0.3",
     "@types/ws": "^8.18.1",
-    "ink-testing-library": "^4.0.0",
     "typescript": "^5.5.0"
   }
 }

package/src/auth/privateer.ts

@@ -145,6 +145,32 @@ function tryChmod(path: string, mode: number): void {
   }
 }
 
+// ── Session-expiry notification ──────────────────────────────────────────────
+// Fired when the machine login is invalidated server-side: the parent refresh
+// token's TTL lapsed (14 days for email logins, 60 for wallet — each session
+// spawn slides it forward, so this means the machine sat unused that long), or
+// it was revoked (from the app's Linked Devices, or by reuse detection).
+// Without a listener the credentials are wiped silently and Privateer just
+// stops working; the UI subscribes to announce the sign-out prominently.
+
+type SessionExpiredListener = () => void;
+const _expiredListeners = new Set<SessionExpiredListener>();
+
+export function onSessionExpired(listener: SessionExpiredListener): () => void {
+  _expiredListeners.add(listener);
+  return () => _expiredListeners.delete(listener);
+}
+
+function notifySessionExpired(): void {
+  for (const listener of _expiredListeners) {
+    try {
+      listener();
+    } catch {
+      /* a failing listener must not break the auth path */
+    }
+  }
+}
+
 // ── Device authorization flow ────────────────────────────────────────────────
 
 export interface DeviceCode {
@@ -271,7 +297,10 @@ async function spawnChildSession(): Promise<ChildSession> {
   });
   if (!res.ok) {
     // Parent refresh token invalid/expired → the machine login is gone.
-    if (res.status === 401) clearCredentials();
+    if (res.status === 401) {
+      clearCredentials();
+      notifySessionExpired();
+    }
     throw new Error("Your Privateer session expired. Run /login to sign in again.");
   }
   const { accessToken, refreshToken } = (await res.json()) as ChildSession;
@@ -279,6 +308,22 @@ async function spawnChildSession(): Promise<ChildSession> {
   return _child;
 }
 
+/**
+ * Eagerly spawn this terminal's child session at startup so an expired machine
+ * login is announced (via onSessionExpired) at launch rather than surfacing as
+ * an inference error on the first prompt of the day. Best effort: transient
+ * network failures stay silent here — the first real request retries the spawn
+ * and reports through the normal error path.
+ */
+export async function warmSession(): Promise<void> {
+  if (!hasCredentials()) return;
+  try {
+    await ensureChildSession();
+  } catch {
+    /* expiry is announced via onSessionExpired; other failures retry on use */
+  }
+}
+
 // Ensure a child session exists, de-duping concurrent spawns within this process.
 function ensureChildSession(): Promise<ChildSession> {
   if (_child) return Promise.resolve(_child);
@@ -363,6 +408,31 @@ export async function apiRequest(path: string, init: RequestInit = {}): Promise<
   return authedFetch(`${base}${path}`, init);
 }
 
+/**
+ * Best-effort revoke of THIS terminal's child session on exit, so the terminal
+ * disappears from the app's Linked Devices list immediately instead of
+ * lingering until its access-token rows expire (24h server-side).
+ *
+ * Deliberately NOT authedFetch: that would spawn/refresh a session just to kill
+ * it. If no child was ever spawned (e.g. BYO-key run), there's nothing to do.
+ * Bounded by a short timeout — exit must never hang on a slow network — and all
+ * failures are swallowed; the server's TTL remains the fallback.
+ */
+export async function revokeChildSession(timeoutMs = 1500): Promise<void> {
+  const child = _child;
+  if (!child) return;
+  _child = null; // never reuse a session we've asked the server to revoke
+  try {
+    await fetch(`${serverBaseUrl()}/auth/session/current`, {
+      method: "DELETE",
+      headers: { Authorization: `Bearer ${child.accessToken}` },
+      signal: AbortSignal.timeout(timeoutMs),
+    });
+  } catch {
+    /* best effort — the session expires server-side regardless */
+  }
+}
+
 // ── Logout ───────────────────────────────────────────────────────────────────
 
 /**
@@ -378,6 +448,63 @@ export async function logout(): Promise<void> {
   clearCredentials();
 }
 
+// ── Account provider (Pi OAuth) credential helpers ───────────────────────────
+// The `privateer` account inference provider registers with Pi via the OAuth path
+// (ProviderConfigInput.oauth). Pi treats a credential as { access, refresh, expires }
+// and refreshes when Date.now() >= expires. We map a per-terminal CHILD session onto
+// that shape: `access` = child access JWT, `refresh` = child refresh token, `expires`
+// = the JWT's exp (so Pi refreshes just before the server would reject it). These are
+// independent of authedFetch's in-memory _child (Pi owns this credential's lifecycle).
+
+interface AccountCredential {
+  access: string;
+  refresh: string;
+  expires: number; // ms epoch
+}
+
+// Decode a JWT's `exp` (seconds) → ms epoch minus a safety skew, or a short fallback
+// so an undecodable token still gets refreshed frequently rather than never.
+function jwtExpMs(token: string, fallbackMs = 5 * 60_000): number {
+  try {
+    const seg = token.split(".")[1];
+    const payload = JSON.parse(Buffer.from(seg, "base64").toString("utf8")) as { exp?: unknown };
+    if (typeof payload.exp === "number") return payload.exp * 1000 - 30_000; // 30s skew
+  } catch {
+    /* not a decodable JWT */
+  }
+  return Date.now() + fallbackMs;
+}
+
+// Spawn a fresh child session (from the parent machine login) as an account credential.
+export async function spawnAccountCredentials(): Promise<AccountCredential> {
+  const parent = loadCredentials();
+  if (!parent) throw new Error("Not logged in to Privateer. Run /login.");
+  const res = await postJson(
+    serverBaseUrl(),
+    "/auth/session/spawn",
+    { refreshToken: parent.refreshToken, deviceLabel: defaultDeviceLabel() },
+    { headers: { Authorization: `Bearer ${parent.accessToken}` } },
+  );
+  if (!res.ok) {
+    if (res.status === 401) {
+      clearCredentials();
+      notifySessionExpired();
+    }
+    throw new Error("Your Privateer session expired. Run /login to sign in again.");
+  }
+  const { accessToken, refreshToken } = (await res.json()) as { accessToken: string; refreshToken: string };
+  return { access: accessToken, refresh: refreshToken, expires: jwtExpMs(accessToken) };
+}
+
+// Rotate this account credential's own refresh token; caller falls back to a fresh
+// spawn if this throws (expired/reused child token).
+export async function refreshAccountCredentials(refresh: string): Promise<AccountCredential> {
+  const res = await postJson(serverBaseUrl(), "/auth/refresh", { refreshToken: refresh });
+  if (!res.ok) throw new Error(`account refresh failed (${res.status})`);
+  const { accessToken, refreshToken } = (await res.json()) as { accessToken: string; refreshToken: string };
+  return { access: accessToken, refresh: refreshToken, expires: jwtExpMs(accessToken) };
+}
+
 function sleep(ms: number, signal?: AbortSignal): Promise<void> {
   return new Promise((resolve, reject) => {
     const t = setTimeout(resolve, ms);

package/src/boot.ts

@@ -0,0 +1,43 @@
+// BOOT — the first module loaded, before any Pi module exists in the graph.
+//
+// Two load-bearing side effects, both of which MUST happen before Pi is
+// imported/evaluated (see docs/pi-migration-plan.md §0 and §Appendix A.3):
+//
+//   1. Pin PI_CODING_AGENT_DIR to $PRIVATEER_HOME/agent. Many Pi internals
+//      (settings-manager, auth-storage, model-registry, migrations, sdk) call
+//      getAgentDir() directly at import/eval time and IGNORE the agentDir option,
+//      so the env var — not the option — is the real lever. Set it here, once.
+//
+//   2. Install the process-wide undici attestation dispatcher, so Pi's provider
+//      TLS handshakes flow through a connector we can inspect (the TEE/Tinfoil
+//      SPKI capture). Pi's extension hooks can't reach the TLS layer; this can.
+//
+// ORDERING CONTRACT: this module imports ONLY node builtins + our own paths and
+// dispatcher modules. It must NEVER import anything from @earendil-works/pi-*.
+// Entrypoints do `import "./boot.ts";` and then DYNAMICALLY import all
+// Pi-touching code, so these side effects are guaranteed to run first regardless
+// of ESM hoisting. Keep this file dependency-light and import-order-safe.
+
+import { agentDir } from "./config/paths.ts";
+// The attestation dispatcher now lives in the pi-privacy package (the publishable
+// moat). boot still installs it pre-Pi as belt-and-suspenders; the package's
+// extension would also install it at extension-init (idempotent — same module
+// instance, so the captured-cert map is shared).
+import { installAttestationDispatcher } from "pi-privacy/attest";
+
+// (1) Pin Pi's agent dir under the privateer home. `??=` so an explicit
+// PI_CODING_AGENT_DIR from the environment still wins (tests, power users).
+//
+// NOTE: confirm the literal env var name against the installed Pi constant —
+// ENV_AGENT_DIR = `${APP_NAME.toUpperCase()}_CODING_AGENT_DIR`, which is
+// "PI_CODING_AGENT_DIR" for APP_NAME="pi". Pinned here as a constant so a Pi
+// rename surfaces as one edit, not a silent config-home split.
+export const PI_AGENT_DIR_ENV = "PI_CODING_AGENT_DIR";
+process.env[PI_AGENT_DIR_ENV] ??= agentDir();
+
+// (2) Install the attestation dispatcher (idempotent).
+installAttestationDispatcher();
+
+// Marker other modules can assert on to catch an accidental "imported Pi before
+// boot" regression during development.
+export const BOOTED = true;

package/src/bridge/engineAdapter.ts

@@ -0,0 +1,182 @@
+// The load-bearing bridge: translate Pi's session.subscribe() events into the
+// privateer `EngineEvent` vocabulary that RelayClient.sendEvent() already speaks.
+// This is the ENTIRE coupling between Pi and the preserved connection layer — the
+// relay/app see EngineEvents and never learn the loop underneath changed.
+//
+// Promoted from ../../ pi-spike/adapter.mjs (spike-B proven) and HARDENED per
+// Phase 1 of docs/pi-migration-plan.md:
+//   - stateful so `usage` carries BOTH the cumulative session total and this
+//     turn's delta (the real EngineEvent shape, unlike the stateless spike),
+//   - `finish` carries usage + finishReason,
+//   - compaction / auto-retry / agent-end-error mapped through.
+//
+// Field names for the compaction/retry/error events are best-effort against Pi
+// 0.80 and marked TODO(verify) — Phase 1's test (`tests/engine.test.ts`, ported
+// from tree-cli) asserts the mapping against a real event stream and pins them.
+
+import {
+  addUsage,
+  emptyUsage,
+  type EngineEvent,
+  type UsageTotals,
+} from "../engine/events.ts";
+
+// Minimal structural view of the Pi session events we read. Kept loose (not the
+// full Pi union) so this module type-checks without pinning to Pi's internals;
+// the runtime shape is what the spike observed.
+export interface PiSessionEvent {
+  type: string;
+  [k: string]: unknown;
+}
+
+interface PiUsage {
+  input?: number;
+  output?: number;
+  cacheRead?: number;
+  totalTokens?: number;
+  cost?: { total?: number };
+}
+
+function normUsage(u: PiUsage | undefined): UsageTotals {
+  const input = u?.input ?? 0;
+  const output = u?.output ?? 0;
+  return {
+    inputTokens: input,
+    outputTokens: output,
+    cachedInputTokens: u?.cacheRead ?? 0,
+    totalTokens: u?.totalTokens ?? input + output,
+  };
+}
+
+function textOf(result: unknown): string {
+  if (typeof result === "string") return result;
+  const parts = (result as any)?.content;
+  if (Array.isArray(parts)) return parts.map((p: any) => p.text ?? `[${p.type}]`).join("");
+  try {
+    return JSON.stringify(result);
+  } catch {
+    return String(result);
+  }
+}
+
+function num(v: unknown, fallback = 0): number {
+  return typeof v === "number" && Number.isFinite(v) ? v : fallback;
+}
+
+// Create a stateful adapter. One instance per session (it accumulates the
+// running usage total). `toEngineEvents` returns zero-or-more EngineEvents for
+// each Pi event; feed each through in `session.subscribe`.
+export function createEngineEventAdapter() {
+  let sessionTotal: UsageTotals = emptyUsage();
+
+  function toEngineEvents(ev: PiSessionEvent): EngineEvent[] {
+    switch (ev.type) {
+      case "message_update": {
+        const a = ev.assistantMessageEvent as any;
+        if (a?.type === "text_delta") return [{ type: "text", text: a.delta }];
+        if (a?.type === "thinking_delta") return [{ type: "reasoning", text: a.delta }];
+        return [];
+      }
+
+      case "tool_execution_start":
+        return [
+          {
+            type: "tool-call",
+            id: ev.toolCallId as string,
+            name: ev.toolName as string,
+            input: ev.args,
+          },
+        ];
+
+      case "tool_execution_end":
+        return ev.isError
+          ? [
+              {
+                type: "tool-error",
+                id: ev.toolCallId as string,
+                name: ev.toolName as string,
+                error: textOf(ev.result),
+              },
+            ]
+          : [
+              {
+                type: "tool-result",
+                id: ev.toolCallId as string,
+                name: ev.toolName as string,
+                output: textOf(ev.result),
+              },
+            ];
+
+      case "turn_end": {
+        const turn = normUsage((ev.message as any)?.usage);
+        sessionTotal = addUsage(sessionTotal, turn);
+        const finishReason =
+          (ev.finishReason as string) ??
+          ((ev.message as any)?.stopReason as string) ??
+          "stop";
+        return [
+          { type: "usage", usage: sessionTotal, turn },
+          { type: "finish", usage: sessionTotal, finishReason },
+        ];
+      }
+
+      // Compaction: Pi collapses history to free context. TODO(verify) field
+      // names for before/after token counts against a real compaction event.
+      case "compaction_start":
+      case "compaction_end":
+        return [
+          {
+            type: "compacted",
+            before: num(ev.beforeTokens ?? (ev as any).before),
+            after: num(ev.afterTokens ?? (ev as any).after),
+          },
+        ];
+
+      // Automatic transient-failure retry before any output streamed.
+      // TODO(verify) Pi's auto-retry event name + fields.
+      case "auto_retry":
+      case "auto_retry_start":
+        return [
+          {
+            type: "retrying",
+            attempt: num(ev.attempt, 1),
+            max: num(ev.max ?? (ev as any).maxAttempts, 1),
+            delayMs: num(ev.delayMs ?? (ev as any).delay, 0),
+            reason: String(ev.reason ?? (ev as any).error ?? "transient failure"),
+          },
+        ];
+
+      // Terminal error surfaced at the end of an agent run. TODO(verify) shape;
+      // Phase 1 re-points errors/errors.ts (describeError) here.
+      case "agent_end": {
+        const err = (ev as any).error;
+        if (!err) return [];
+        return [
+          {
+            type: "error",
+            error: typeof err === "string" ? err : (err.message ?? String(err)),
+            retryable: Boolean((ev as any).retryable),
+          },
+        ];
+      }
+
+      case "abort":
+      case "aborted":
+        return [{ type: "aborted" }];
+
+      default:
+        return [];
+    }
+  }
+
+  return {
+    toEngineEvents,
+    // Current running total, for callers that want to snapshot session usage
+    // outside the event stream.
+    get sessionUsage(): UsageTotals {
+      return sessionTotal;
+    },
+  };
+}
+
+export type EngineEventAdapter = ReturnType<typeof createEngineEventAdapter>;