agent-tempo 1.3.1 → 1.4.0

package/CLAUDE.md

@@ -28,6 +28,7 @@ src/
 │   ├── dev-banner.ts  # [DEV MODE] banner formatter (ADR 0014 §5.4) — gate 4 production-safety line
 │   ├── dev-mode-bootstrap.ts # pre-import side-effect: promotes top-level `--dev` flag to `CLAUDE_TEMPO_DEV_MODE=1` before any other module loads
 │   ├── dev-verbs.ts   # dev-mode scriptable CLI verbs (#432) — shell-scriptable wrappers over MCP tools for E2E validation; stripped from production surface
+│   ├── global-wrapper.ts # global wrapper auto-provisioning — writes `~/.agent-tempo/bin/agent-tempo` shell/cmd scripts; entrypoint pointer refreshed on every CLI boot; emits one-time PATH hint when bin dir is off PATH (#620)
 │   ├── help-text.ts   # help output — crash-proof, no Temporal deps
 │   ├── legacy-migration.ts # one-shot idempotent copy `~/.claude-tempo/` → `~/.agent-tempo/` on first v1.0 boot (PR-2 of rebrand)
 │   ├── mcp.ts         # MCP server registration helpers (init, global vs project)
@@ -47,6 +48,7 @@ src/
 │   ├── copilot/       # CopilotSdkAttachment — Copilot bridge adapter
 │   ├── claude-api/    # ClaudeApiAttachment — headless adapter via Anthropic Messages API (#131)
 │   ├── opencode/      # OpenCodeAttachment — headless multi-provider adapter via SST OpenCode subprocess (#449)
+│   ├── pi/            # Headless Pi adapter — descriptor + spawn entry (Phase 3a). No BaseAttachment; the Pi extension singleton owns lifecycle (claim/heartbeat/tools/cue pump). `adapter.ts` is the process entry; `index.ts` is the registry descriptor.
 │   ├── mock/          # MockAttachment — dev-mode-only SDK adapter (ADR 0014 PR-2). prepack strips dist/adapters/mock from npm tarball.
 │   └── sdk/           # SDK-style adapter base (used by Copilot bridge and opencode)
 ├── client/
@@ -77,7 +79,14 @@ src/
 │   ├── ring-buffer.ts # Fixed-size event ring buffer (256 events) for Last-Event-ID replay
 │   ├── snapshot.ts    # On-demand ensemble state snapshot (prelude + poll)
 │   ├── aggregate.ts   # AggregateRunner — wires bus + snapshot + HTTP server startup
-│   ├── auth.ts / cors.ts / responses.ts / event-id.ts / port-file.ts / index.ts
+│   ├── inner-loop.ts  # InnerLoopRegistry + InnerSubscription — daemon-local fine-tail sink (3c MD-F); drop-oldest bounded queue (256) + `compacted{dropped,sinceTs}` marker; NOT on Temporal/bus, ephemeral no-replay
+│   ├── ingest-registry.ts # IngestTokenRegistry — per-player ingest token (mint-on-pi-spawn / revoke-on-destroy / revokeAll-on-shutdown); timing-safe validation; cross-player-spoof guard
+│   ├── inner-loop-routes.ts # 3 inner-loop HTTP routes: POST /inner/ingest + GET /inner/presence (INGRESS, loopback + X-Ingest-Token, uniform 403); GET /inner (EGRESS operator SSE, requireTier(3))
+│   ├── gate-registry.ts   # GateRegistry (3d MD-G) — per-player armed-gate + pending-request store; 45s lazy auto-allow (R3 locked); arm/disarm/decide/getResolution; injected auditSink + publishToInner callback
+│   ├── gate-routes.ts     # Gate HTTP routes: POST /gate-arm + /gate-disarm + /gate/:requestId (OPERATOR, Tier 3); GET /gate/:requestId/resolution (SOURCE, loopback + X-Ingest-Token); uniform 403 no-leak
+│   ├── gate-audit.ts      # createGateAuditSink — append-only JSONL at ~/.agent-tempo/gate-audit/<ensemble>/<workflowId>.jsonl; sync write (R5 durable-before-return); whitelisted path segments; swallows I/O errors
+│   ├── auth.ts        # 3e MD-E RBAC: two-token model (readToken T1 / adminToken T1+T2+T3 env-var-only); loadRbacTokens; requireTier(tier, input) → TierGuardResult; tierForToken; loadReadToken (env>config>legacy httpToken>auto-gen); loadAdminToken (env-only); TLS/legacy startup warnings in startHttpServer
+│   ├── cors.ts / responses.ts / event-id.ts / port-file.ts / index.ts
 ├── reconcile/
 │   └── orphans.ts     # Shared orphan-query helper (daemon reconcile-on-boot + CLI restore)
 ├── ensemble/
@@ -91,11 +100,33 @@ src/
 │   ├── worktree.ts / stage.ts / stages.ts / cancel-stage.ts
 │   ├── load-lineup.ts / save-lineup.ts / agent-types.ts / resolve.ts
 │   ├── set-name.ts / set-part.ts / who-am-i.ts / release.ts
-│   ├── pause.ts / play.ts / shutdown.ts / restore.ts
+│   ├── pause.ts / play.ts / shutdown.ts / restore.ts / reset.ts
 │   ├── hosts.ts / set-ensemble-description.ts
 │   ├── save-state.ts / fetch-state.ts / clear-state.ts
 │   ├── coat-check-put.ts / coat-check-get.ts / coat-check-list.ts / coat-check-evict.ts
-│   └── helpers.ts     # Zod/MCP tool registration wrapper
+│   └── descriptor.ts  # Transport-neutral tool descriptor (TempoToolDescriptor) + renderToMcp; per-tool `build*Tool` factories live in each tool file (MD-B, Phase 1)
+├── pi/                # Pi-native integration — a Pi session as a first-class player over the Temporal core
+│   ├── extension.ts   # `export default function(pi)` — interactive runtime entry. Holds the MODULE-SCOPE singleton `Map<workflowId, PiPlayerRuntime>` that survives Pi's per-switch instance rebuild (rebind, not re-claim); full tool surface via renderToPi; Option-C reason-discriminated teardown
+│   ├── phase-driver.ts / workflow-client.ts / cue-pump.ts   # Pi-event→attachment-phase machine, thin client-side WorkflowClient (lease/heartbeat 90/30, handle getter), cue pump (D10 steer/followUp)
+│   ├── lazy-proxy.ts  # D11 createLazyProxy — Client/WorkflowHandle proxy resolving the live module-scope target per call (survives instance rebuild)
+│   ├── headless.ts    # Headless Pi runtime (Phase 3a) — boots Pi's createAgentSession with inline extension; `noExtensions: true` closes S2 exec-tool bypass; SIGTERM/SIGINT shutdown → reliable detach + dispose
+│   ├── render-tools.ts # renderToPi — registers the shared tool descriptors on Pi's ExtensionAPI (TypeBox params via the converter)
+│   ├── zod-to-typebox.ts # zod→TypeBox tool-schema converter (fail-loud on unsupported constructs; Phase 1 / D1)
+│   ├── inner-loop-publisher.ts # InnerLoopPublisher (3c MD-F) — single Pi-source observer; Tier-1 coarse via heartbeat piggyback (currentTool + context pressure), Tier-2 fine presence-gated; source coalescing (100ms/2KB) + 2KB truncation
+│   ├── inner-loop-client.ts # InnerLoopHttpClient — production InnerLoopRegistry impl: thin loopback-HTTP calls (publish→POST ingest, subscriberCount→cached presence GET); no-ops without AGENT_TEMPO_INGEST_TOKEN; 3d: also caches gateArmed from presence response
+│   ├── gate-client.ts     # GateClient (3d MD-G) — Pi-subprocess poll client for operator gate resolution; awaitDecision(requestId) polls GET /gate/:id/resolution until resolved or timeout; fail-open (allow on timeout/error/auto-allow)
+│   ├── reset-pump.ts      # ResetPump (3d D14) — polls pendingReset query every 1s; on result calls session.newSession() (clean-wipe); sends system notice; acks via ackReset signal
+│   ├── tool-capability.ts # classify(toolName) → ToolCapability ('exec' | 'high-blast' | 'low-risk'); EXEC_TOOLS denylist (F1 locked: bash/shell/exec/sh/powershell/pwsh/cmd/…); unknown → 'high-blast' (fail-safe)
+│   ├── mission-control/   # 3f — observer-only Pi extension that turns one interactive Pi TUI into an ensemble mission-control board + operator controller. HTTP-driven (NOT MCP tools). Never claims attachment or registers as a player.
+│   │   ├── extension.ts   # Controller (testable command handlers) + Pi extension lifecycle: session_start opens coarse SSE + ~200ms render tick + registers /players /tail /cue /pause /play /restart /destroy /reset /arm /gate; session_shutdown tears down SSE + widget
+│   │   ├── board.ts       # Pure BoardModel + reducers: applyTempoEvent (coarse /events SSE) + applyInnerFrame (selected-player inner tail); revision counter drives render throttle
+│   │   ├── render.ts      # Pure BoardModel → string[] renderer; phase glyphs, part, currentTool, context%, selected-player tail (12 lines), inner.gate_pending/gate_resolved frames
+│   │   ├── actions.ts     # Daemon HTTP write-surface client (T2 + T3 bearer): cue/pause/play/restart/destroy + gate arm/disarm/decide; reads AGENT_TEMPO_HTTP_ADMIN_TOKEN
+│   │   ├── inner-tail.ts  # Operator-egress /inner SSE consumer (T3 bearer): pure parseInnerSse + injectable stream pump; cross-host note: baseUrl is the preferredHost seam
+│   │   ├── pi-ui.ts       # Local structural slice of Pi's ctx.ui / registerCommand / registerShortcut API (self-contained; tsc green without optional Pi dep)
+│   │   └── index.ts       # Barrel — re-exports Controller, BoardModel, renderBoard, MissionControlActions, and public types
+│   ├── probe.ts / pi-types.ts / index.ts   # optional-dep preflight, hand-written ExtensionAPI decls, barrel
+│   └── README.md      # Pi integration findings (abrupt-death/MD-A, D12a, Phase 2 singleton/teardown) + carry-items
 ├── tui/
 │   ├── App.tsx / store.ts / commands.ts   # TUI root, state, slash commands
 │   ├── sse-handler.ts # SSE event → TUI store dispatch mapping (PR-4a of #94/#95)
@@ -105,13 +136,14 @@ src/
 │   ├── validation.ts / worktree.ts / safe-path.ts / duration.ts / search-attributes.ts
 │   ├── attachment-format.ts / recall-format.ts   # Shared display formatters (attachment-info, recall)
 │   ├── hosts.ts / format-hosts.ts                # Host enumeration + shared hosts display formatter (#274)
-│   ├── sdk-probe.ts   # Filesystem-walk probe for installed optional npm deps (used by opencode adapter + recruit preflight, #449)
+│   ├── sdk-probe.ts   # Filesystem-walk probe for installed optional npm deps + version floor check (used by opencode adapter + recruit preflight + Pi/Copilot-via-Pi preflight, #449)
 │   ├── ensemble-ops.ts   # Shared pause/unpause/fan-out helpers for ensemble-scope verbs (pause, play, shutdown, restore, destroy)
 │   ├── query-timeout.ts   # Bounded WorkflowHandle.query() wrapper with in-flight deduplication; prevents hung queries from wedging snapshot endpoint (#433)
 │   ├── visibility-deadline.ts   # Iterator-level deadlines for Temporal workflow.list() scans; prevents memory growth from stalled visibility page streams (#336, #529)
 │   ├── default-part.ts   # Derives human-readable "X session" part string from a player's type name (e.g. tempo-conductor → "Conductor session")
 │   ├── restore-format.ts   # Pure formatter for restore --all-hosts cluster-view listing; no Temporal/I/O deps (#151)
-│   └── parent-death-watchdog.ts   # Self-exit watchdog (stdin EOF + PPID poll) so MCP server children don't outlive their parent host (#604)
+│   ├── parent-death-watchdog.ts   # Self-exit watchdog (stdin EOF + PPID poll) so MCP server children don't outlive their parent host (#604)
+│   └── grpc-shutdown-guard.ts   # Process-level `uncaughtException` guard that swallows benign post-shutdown "Channel has been shut down" gRPC errors at the three JS-client entrypoints (cli.ts, daemon.ts, server.ts); re-throws everything else (#624)
 ├── types.ts           # Shared type definitions
 ├── git-info.ts        # Git repository detection helper
 └── config.ts          # Env var handling
@@ -178,6 +210,8 @@ daemon worker notes, `npx ts-node` dev runner).
 - **Claude API adapter** (`agent: 'claude-api'`, #131): Headless adapter that drives sessions via the Anthropic Messages API (`@anthropic-ai/sdk`) — no terminal, no Claude Code CLI. Requires `ANTHROPIC_API_KEY` env var and the `@anthropic-ai/sdk` optional dependency. Default model `claude-opus-4-7` (overridable via `model` recruit arg or `CLAUDE_TEMPO_API_MODEL` env). Claude-API players have access to agent-tempo MCP tools (cue, report, recall, ensemble, …) but not file-edit/shell/web tools. See `src/adapters/claude-api/`.
 - **OpenCode adapter** (`agent: 'opencode'`, #449): Headless multi-provider adapter that drives sessions via [SST OpenCode](https://opencode.ai) as a managed subprocess — supports Anthropic, OpenAI, Bedrock, Vertex, Ollama, and ~70 other providers via OpenCode's `provider/model` selector. Requires OpenCode CLI (`npm install -g opencode-ai`) and the `@opencode-ai/sdk` optional dependency. Recruit with `model: 'provider/name'` (e.g. `'anthropic/claude-opus-4-7'`). Tool bridging is MCP-native — OpenCode spawns `dist/server.js` as its own stdio MCP child. Session state is persisted server-side by OpenCode; the adapter stashes the session id on workflow metadata for reconnect across `opencode serve` restarts. See `src/adapters/opencode/`.
 - **Claude Code headless adapter** (`agent: 'claude-code-headless'`, #520): Headless adapter that drives sessions via the official `claude` CLI as a per-turn `claude -p --output-format stream-json` subprocess. The whole point: turns bill against the host's existing Claude Code subscription extra-usage credits (Pro / Max plans) rather than a Console workspace API key — the only ToS-clean way for a third-party tool to tap that pool. Requires the `claude` binary on PATH AND a logged-in Claude Code session (`claude auth login`); recruit pre-flight rejects with an actionable error otherwise. Tool surface is the union of full Claude Code built-ins (Bash / Read / Write / Edit / Glob / Grep / WebSearch / WebFetch) and the agent-tempo MCP surface — registered via inline `--mcp-config` so `claude` spawns `dist/server.js` as its own MCP child (no in-process bridge). Recruit knobs: `permissionMode` (default `'acceptEdits'`) or `dangerouslySkipPermissions: true` (mutually exclusive). Sessions resume across restart via the existing `sessionId` metadata field — the same UUID is shared with the interactive `claude-code` adapter (per-cwd JSONL is per-cwd, not per-adapter). See `src/adapters/claude-code-headless/` and `examples/ensembles/tempo-headless-jam.yaml`.
+- **Pi adapter** (`agent: 'pi'`, #632 Phase 3a): Headless adapter that runs a Pi AI session as a first-class agent-tempo player — no terminal, no BaseAttachment. Recruit injects the Phase 2 `src/pi` extension into Pi's `createAgentSession`; the module-scope singleton owns claim/heartbeat/tools/cue pump (MD-D). Requires the `pi-ai` optional dependency (`npm install -g pi-ai`) on Node 22.19+. Optional `model: 'provider/model'` selector (e.g. `'anthropic/claude-opus-4-7'`, `'github-copilot/gpt-4o'`); absent → Pi's own default. MD-C tool-access policy: `toolAccess: 'restricted'` (default — Bash/shell/exec HARD-BLOCKED) | `'standard'` (scoped Bash) | `'full'` (unsandboxed; requires `force: true`). `noExtensions: true` closes the S2 exec-tool-bypass gap (no disk/package extensions load alongside the agent-tempo extension). See `src/adapters/pi/` and `src/pi/headless.ts`.
+- **Mission-control Pi extension** (3f): An observer-only Pi extension that turns one interactive Pi TUI into a live ensemble board + operator controller. HTTP-drives the daemon — coarse ensemble view via `/v1/events/:ensemble` SSE + fine per-player tail via `/inner` (T3); operator controls (cue/pause/play/restart/destroy + gate arm/disarm/decide) POST to the daemon write surface using `AGENT_TEMPO_HTTP_ADMIN_TOKEN`. **Never claims attachment or registers as a player** — invisible to the ensemble. ~200ms render throttle from an in-memory `BoardModel`. Requires an interactive Pi session with `ctx.hasUI`. See `src/pi/mission-control/`.
 - **Mock adapter** (`agent: 'mock'`, dev mode only): Four modes: `echo` (echoes input), `scripted` (replays YAML scenario rules), `silent` (drains messages without replying — heartbeat-stale validation), `chaos` (probabilistic fail/crash injection via seeded PRNG). Only registered when `isDevMode()` is true; stripped from the npm tarball by `prepack`. See `src/adapters/mock/`.
 - **Saveable state** (#334, ADR 0011): Per-player curated state slots — the player itself decides what context survives a restart. Three MCP tools: `save_state` (owner-only write, max 4 slots × 32 KiB), `fetch_state` (read self or peer; audit identity recorded on each entry's `savedBy`), `clear_state` (owner-only). `restart` accepts `loadFromState: true | 'someKey'` to seed the new session from a saved-state slot instead of (or, with `transcript: 'replay'`, alongside) transcript replay. Saved-state delivery uses `from: 'self-restart'` as a stable system identity. Empty-slot fallback: graceful — falls through to transcript replay with a log line. See [docs/design/334-player-saveable-state.md](docs/design/334-player-saveable-state.md).
 - **Coat-check** (#318, ADR 0008): Per-ensemble transient content store on Maestro state. Solves the 100 KB cue body cap — stash a large artifact with `coat_check_put` (returns a ticket id) and attach the ticket to a `cue` via `attachmentTicket`; the recipient calls `coat_check_get` to pull the full body. Four MCP tools: `coat_check_put` (any player; max 32 KiB per entry, 20 slots per ensemble, TTL 7d default), `coat_check_get` (any player; bumps fetch-audit counters), `coat_check_list` (read-only survey; headers only, content omitted), `coat_check_evict` (owner or conductor). Saturation rejects with `CoatCheckSlotsFull` (no LRU eviction). See `src/tools/coat-check-*.ts` and [docs/adr/0008-coat-check-pattern.md](docs/adr/0008-coat-check-pattern.md).

package/README.md

@@ -37,16 +37,20 @@ Each session registers as a **player** in Temporal. Players discover each other
 | 🖥️ **Terminal UI** | Chat-focused TUI with slash commands, overlays, and interactive wizards |
 | 🌐 **Cross-machine** | Any session that can reach your Temporal server can join the ensemble |
 | ⏸️ **Hold / Pause / Resume** | Pre-warm a full team before delivering tasks; pause and resume mid-session |
-| 🤖 **Headless adapters** | Copilot bridge, Claude API, OpenCode, and Claude Code headless (`claude -p` subprocess — bills against your Claude Code subscription, no Console API key needed) — mix providers and headless agents in the same ensemble |
+| 🤖 **Headless adapters** | Copilot bridge, Claude API, OpenCode, Claude Code headless (`claude -p` — bills against your Claude Code subscription), and Pi AI — mix providers and headless agents in the same ensemble |
 
 ## Installation
 
 ```bash
 npm install -g agent-tempo
+# or without a global install:
+npx agent-tempo
 ```
 
 **Prerequisites**: [Node.js](https://nodejs.org/) 20 LTS, 22 LTS, or 24 LTS, [Temporal CLI](https://docs.temporal.io/cli), [Claude Code](https://claude.ai/code)
 
+> **No-global-install path**: On first run, `agent-tempo` auto-provisions `~/.agent-tempo/bin/agent-tempo` so subsequent invocations don't need `npx`. If that directory isn't on your PATH, a one-time hint is printed to stderr with the exact export line to add to your shell profile.
+
 ## Quick Start
 
 One command handles everything:
@@ -202,7 +206,7 @@ players:
     type: tempo-soloist
 ```
 
-Eight types ship out of the box: `tempo-conductor`, `tempo-composer`, `tempo-soloist`, `tempo-tuner`, `tempo-critic`, `tempo-roadie`, `tempo-improv`, `tempo-liner`. Five lineup presets are included: `tempo-big-band`, `tempo-dev-team`, `tempo-review-squad`, `tempo-jam-session`, `tempo-mock-jam`.
+Eight types ship out of the box: `tempo-conductor`, `tempo-composer`, `tempo-soloist`, `tempo-tuner`, `tempo-critic`, `tempo-roadie`, `tempo-improv`, `tempo-liner`. Six lineup presets are included: `tempo-big-band`, `tempo-dev-team`, `tempo-review-squad`, `tempo-jam-session`, `tempo-mock-jam`, `tempo-headless-jam`.
 
 ```bash
 agent-tempo agent-types list   # discover available types