pi-ca-leash 0.10.0

package/AGENTS.md

@@ -0,0 +1,77 @@
+# AGENTS.md
+
+Agent guidance for working in `pi-ca-leash`.
+
+## Mission
+
+Keep this repo honest.
+
+This project is a **runtime-first local MVP** for Claude Code integration with pi. Do not rewrite it into a fake stateless provider integration and do not pretend upstream product integrations exist when they do not.
+
+## Current scope
+
+In scope:
+- `packages/runtime` — Claude Code runtime abstraction
+- `packages/intercom-bridge` — named peer bridge and optional live intercom transport
+- `packages/subagents-backend` — local subagent backend package
+- `packages/teams-backend` — local persistent teammate backend package
+- `extensions/index.ts` — pi extension wiring, dashboard, transport monitoring, attention UX
+
+Out of scope unless explicitly requested and proven possible:
+- fake `pi-teams` integration
+- claims of real upstream `pi-subagents` integration
+- fake Claude fork/session-tree semantics
+- broad architecture rewrites without tests
+
+## Non-negotiable truths
+
+- Claude Code is treated here as a **long-lived runtime**, not a normal stateless model provider.
+- `runner=claude-code-agent` does **not** support real `fork`.
+- Teams backend is **local-only** in this repo.
+- Intercom broker transport is optional; local runtime-backed peers still work without it.
+- If something is environment-dependent, say so plainly.
+
+## Working style
+
+- Prefer small, maintainable changes.
+- Add or update tests before behavior changes when practical.
+- Keep docs synchronized with reality.
+- Remove stale docs instead of letting multiple contradictory docs survive.
+- Do not add dependencies for imaginary integrations.
+
+## Good commands
+
+```bash
+npm test
+npm run build
+npm run smoke -- "Reply with exactly: smoke-ok"
+npm run demo:intercom -- "You are demo worker. Reply briefly."
+npm run demo:subagent -- "Reply with exactly: subagent-ok"
+npm run demo:teams -- "You are persistent teammate. Reply briefly."
+```
+
+## Files worth reading first
+
+- `README.md`
+- `ARCHITECTURE.md`
+- `KNOWN_LIMITS.md`
+- `CHANGELOG.md`
+
+## Documentation policy
+
+Keep documentation in English.
+
+If you change behavior, update whichever of these are affected:
+- `README.md` — public repo entrypoint
+- `ARCHITECTURE.md` — how pieces fit together
+- `KNOWN_LIMITS.md` — honest constraints
+- `CHANGELOG.md` — notable user-visible changes
+
+## Shareability standard
+
+Before claiming the repo is ready to share:
+- `npm test` must pass
+- `npm run build` must pass
+- README must match reality
+- known limits must still be true
+- no stale plan/session docs should remain

package/ARCHITECTURE.md

@@ -0,0 +1,290 @@
+# Architecture
+
+## Overview
+
+`pi-ca-leash` is built around one idea:
+
+> Claude Code should be integrated as a **stateful runtime** first, then adapted into pi-style workflows.
+
+That leads to a layered design.
+
+```text
+Claude SDK driver (default)    Codex CLI driver (experimental)
+             ↓                          ↓
+                   packages/runtime
+                          ↓
+               packages/intercom-bridge
+                          ↓
+     packages/subagents-backend    packages/teams-backend
+                          ↓                     ↓
+                       extensions/index.ts
+```
+
+## Layers
+
+### 1. Runtime layer
+
+Path:
+- `packages/runtime`
+
+Responsibility:
+- start driver-backed sessions
+- resume/send messages into existing sessions
+- normalize runtime events
+- persist session state and transcript
+- expose status, listing, event streaming, interrupt, and stop
+
+This package is the source of truth for runtime session lifecycle.
+
+Current drivers:
+- `claude-sdk` is the default and most complete path.
+- `codex-cli` exists as an experimental runtime driver with a narrower supported option set.
+
+Important consequence:
+- higher layers should not reinvent runtime session persistence or control semantics
+
+### 2. Intercom bridge layer
+
+Path:
+- `packages/intercom-bridge`
+
+Responsibility:
+- give runtime sessions stable peer names
+- map `send` / `ask` / `reply` style messages into runtime sends
+- wait for the next idle cycle to determine replies
+- persist peer registry for restart restore
+- optionally bind peers to live `pi-intercom` transport when broker is reachable
+- preserve per-peer runtime driver identity
+
+Important consequence:
+- intercom transport is optional
+- the bridge still works locally without live broker presence
+- peers may now be runtime-backed by different drivers
+- extension startup can choose the default peer driver via `PI_CLAUDE_RUNTIME_DRIVER`
+- public peer examples stay driver-agnostic; experimental Codex selection is primarily via startup default or LLM-callable tools
+
+### 3. Subagent backend layer
+
+Path:
+- `packages/subagents-backend`
+
+Responsibility:
+- run bounded delegated jobs through the Claude runtime
+- persist run artifacts in subagent-style layout
+- map runtime states into run states
+- support sync/async runs
+- emit attention events for stale background runs
+
+Truth:
+- this is local backend logic in this repo
+- backend API can thread runtime driver selection into runs
+- it is not proof of real upstream `pi-subagents` product integration
+- `context: fork` is rejected explicitly
+
+### 4. Teams backend layer
+
+Path:
+- `packages/teams-backend`
+
+Responsibility:
+- keep persistent Claude-backed teammates alive across multiple messages/tasks
+- assign tasks
+- exchange direct messages
+- persist teammate/task state
+- restore teammate records after restart
+
+Truth:
+- this is a local teams backend only
+- backend API can thread runtime driver selection into teammate spawn
+- no external `pi-teams` integration is assumed here
+
+### 5. Extension layer
+
+Path:
+- `extensions/index.ts`
+- `extensions/model-catalog.ts`
+- `extensions/prompts/`
+
+Responsibility:
+- wire runtime + bridge + backends into a pi extension
+- expose operator commands
+- render peer-first widget/dashboard surfaces
+- stay lazy until `/peer init`, another actionable `/peer` command, or an LLM-callable runtime tool activates the workflow
+- keep retained backend diagnostics behind explicit advanced views
+- monitor live broker transport connectivity
+- surface attention notifications
+- persist local attention ack/snooze state
+- expose a bundled, advisory model catalog for runtime model selection
+- keep editable prompt/guidance text out of the main extension implementation
+
+The extension is where operator UX lives.
+
+Activation model:
+- extension load registers slash commands, tools, and renderers only
+- `session_start` does not create the widget, start the background monitor, or run live intercom checks while inactive
+- `/peer init` activates the workflow, adds the one-time orchestration guide to the main agent context, and shows compact user help as a user-only UI notification
+- the first actionable `/peer` command also activates the workflow and adds the agent guide once
+- `/peer help` stays passive and shows user-only UI help
+- after activation, the background monitor handles broker connectivity, attention notifications, peer relays, and visible dashboard refreshes
+
+Context boundary:
+- command acknowledgments, dashboards, model lists, history pages, and diagnostics are operator-facing UI notifications
+- the main agent context receives only intentional agent-facing prompts, such as the one-time orchestration guide, and automated peer relays
+- peer relays are wrapped follow-up turns containing the latest visible peer message so the orchestrator can decide whether to inspect more history
+
+Prompt files:
+- `extensions/prompts/peer-init.md` is the one-time main-agent orchestration guide added when peer mode is first activated
+- `extensions/prompts/peer-init-user-help.md` is the compact user-facing command cheat sheet shown as a user-only UI notification with peer-mode activation
+- `extensions/prompts/peer-no-babysitting.md` is included in peer start acknowledgments
+- `extensions/prompts/*-tool.md` files provide LLM-callable tool snippets/guidelines
+- `extensions/prompts/peer-bridge-system.md` is appended to runtime-backed peer sessions
+
+### Model catalog layer
+
+Path:
+- `extensions/model-catalog.ts`
+
+Responsibility:
+- map runtime drivers to model-provider catalogs
+- expose known model ids, labels, context windows, token limits, modality flags, and rough per-million-token costs
+- expose a small deterministic alias map for common shorthand names, resolved before launching a runtime call
+- expose a short advisory recommendation list for common use cases such as architecture, coding, quick checks, and cheap worker tasks
+- provide advisory model-selection notes for `/peer`, `runtime_models`, and LLM-callable runtime tools
+
+Current mapping:
+- `claude-sdk` uses the Lanista `anthropic` catalog and passes models to the Claude SDK / Claude Code runtime.
+- `codex-cli` uses the Lanista `openai-codex` catalog and passes models as `codex -m` / `codex --model` compatible ids.
+
+Important consequence:
+- the catalog is not an entitlement authority
+- recommendation use cases are local product guidance, not upstream provider guarantees
+- aliases only normalize shorthand into exact ids from the bundled catalog; they do not guarantee local provider access
+- unknown model ids are passed through to the runtime instead of being hard-rejected
+- actual availability can still differ by installed CLI version, account, region, and provider rollout state
+
+## Updating the Model Catalog with Lanista
+
+The bundled catalog is a static snapshot so `pi-ca-leash` does not need `lanista` at runtime.
+
+To refresh it from Lanista:
+
+```bash
+cd /Users/mhild/src/durandom/b4arena/lanista
+.venv/bin/lanista fetch
+.venv/bin/lanista --json agents anthropic
+.venv/bin/lanista --json agents codex
+```
+
+Then copy the relevant provider records into `extensions/model-catalog.ts`:
+- Lanista `anthropic` -> `RUNTIME_MODEL_CATALOGS["claude-sdk"]`
+- Lanista `openai-codex` -> `RUNTIME_MODEL_CATALOGS["codex-cli"]`
+
+Keep these fields when updating entries:
+- model id
+- display name
+- context window
+- max output tokens
+- reasoning flag
+- input modalities
+- input and output cost per million tokens
+
+After updating the snapshot:
+
+```bash
+npm test
+npm run build
+```
+
+Do not add a runtime dependency from this repo to Lanista unless the extension needs live model refresh. The default should stay deterministic and offline-friendly.
+
+## Runtime-first design rationale
+
+Why this shape exists:
+- Claude Code is session-based and tool-using
+- it has lifecycle concerns that do not fit a pure model-provider abstraction well
+- intercom/subagents/teams all need long-lived session identity and persistence
+
+So this repo chooses:
+- one runtime core
+- multiple adapters on top
+- minimal duplication across higher layers
+
+## Persistence model
+
+Repository-local state is written under:
+
+```text
+.pi-ca-leash/
+```
+
+Typical layout:
+
+```text
+.pi-ca-leash/
+  runtime/      # runtime sessions and transcripts
+  bridge/       # bridge peer registry
+  subagents/    # subagent run artifacts
+  teams/        # teammate and task records
+  extension/    # extension-local state such as attention ledger
+  log.md        # append-only local feedback log for extension smoothing
+```
+
+## Interaction model
+
+### Named peer flow
+
+```text
+user command
+  → extension
+  → immediate acknowledgment in main window
+  → intercom bridge
+  → runtime session send
+  → wait for idle cycle
+  → reply extraction
+  → peer-first dashboard/widget update
+  → final command result
+```
+
+### Subagent flow
+
+```text
+user command
+  → extension
+  → subagents backend
+  → runtime start/send
+  → persisted run status/events/result
+  → attention monitoring if stale
+```
+
+### Teammate flow
+
+```text
+user command
+  → extension
+  → teams backend
+  → bridge-backed persistent peer
+  → task/message exchange over time
+```
+
+## What is intentionally not abstracted further
+
+This repo currently avoids extra abstraction layers unless they solve a real problem.
+
+Examples:
+- no fake generic team product adapter
+- no fake upstream `pi-teams` compatibility layer
+- no pseudo-fork illusion for Claude sessions
+
+## Testing strategy
+
+Current coverage:
+- package-level tests for runtime, intercom bridge, subagent backend, and teams backend
+- extension helper/state tests in `extensions/*.test.ts`
+
+Current gap:
+- no full end-to-end extension-host smoke test inside a real pi host runtime
+
+See also:
+- `README.md`
+- `KNOWN_LIMITS.md`
+- `CHANGELOG.md`

package/CHANGELOG.md

@@ -0,0 +1,158 @@
+# Changelog
+
+All notable changes to this repository should be recorded here.
+
+## 0.10.0 - 2026-05-03
+
+### Changed
+- Root package is now publishable as a single npm package that bundles the internal runtime, bridge, subagents, and teams workspaces while keeping their build output inside the shipped tarball.
+- Root install/build hooks now use `prepare` plus `prepack` instead of consumer-side `postinstall` rebuilds.
+- README and package metadata now describe the package as a harness-aware Claude Code and Codex CLI extension, while still calling out Codex support as experimental.
+
+### Fixed
+- `peer_interrupt` now reports whether an interrupt signal was delivered, the runtime reason, resulting peer state, and whether follow-up input can be sent immediately.
+- Peer list/dashboard waiting state now only flags explicit unresolved asks, avoiding false `waiting / needs input` rows for normal completion reports.
+- Newly started peers now relay their first real `waiting`, `idle`, or `error` transition into the main context instead of suppressing the initial `needs input` signal.
+
+## 0.9.0 - 2026-05-03
+
+### Changed
+- The compact peer-mode user help now uses a persistent user-only notification instead of the lower widget area, avoiding widget truncation without adding help text to the main agent context.
+
+## 0.8.0 - 2026-05-03
+
+### Changed
+- Peer slash-command guidance, reports, dashboards, model lists, and history pages now use user-only UI notifications instead of custom chat messages, keeping them out of the main agent context.
+- Agent-facing peer messages remain explicit: the one-time orchestration guide is added to the main agent context, and peer completion/block/failure relays still arrive as wrapped follow-up turns with the latest visible peer message.
+
+## 0.7.0 - 2026-05-03
+
+### Changed
+- `/peer init` now carries the one-time main-agent orchestration guide plus a compact user-facing command cheat sheet, while repeated peer tool prompts stay narrowly tool-specific.
+- Runtime model selection now resolves common shorthand aliases such as `sonnet`, `opus`, `haiku`, `mini`, and `spark` to concrete catalog model ids before launching peers, subagents, or teammates.
+- `/peer models` and `runtime_models` now show a shorter recommended model list by default, with advisory use cases and clearer `context window` / `max output` column labels; pass `all`, `advanced`, `verbose`, or `verbose: true` for the full catalog.
+- Added `extension_log`, an LLM-callable local feedback tool that appends structured extension UX and interaction roughness notes to `.pi-ca-leash/log.md`.
+- Peer/subagent/team launch surfaces now include prompt-size warnings for large delegated prompts, nudging agents toward smaller slices and file-based context.
+- `runtime_models` reports bundled model aliases alongside exact model ids.
+- Compact Peers widget rendering now uses a small adaptive table layout helper, including a wide-mode driver column and narrow-mode fallback.
+- `/peer help` now includes versioned concept guidance, and `/peer about` reports installed version and runtime environment details without activating peer mode.
+- Subagent and team LLM-callable tools are now hidden by default and only registered when `PI_CLAUDE_ENABLE_ADVANCED_COMMANDS=1`.
+
+### Fixed
+- Runtime driver errors now add actionable hints for missing Claude Code/Codex executables, Bedrock credential routing, missing API keys, and prompt/context-length failures.
+- Extension version reporting now reads the package version instead of a hardcoded constant.
+
+## 0.3.0 - 2026-05-03
+
+### Changed
+- Added `DEVELOPMENT.md` and linked it from `README.md` as the dedicated developer workflow and smoke-debugging guide.
+- Added developer-oriented smoke helpers: `npm run smoke:dev`, `smoke:dev:codex`, `smoke:manual`, `smoke:manual:codex`, `smoke:last`, and `smoke:clean`.
+- Added `npm run smoke:pi:auto` and `npm run smoke:pi:auto:codex` helpers that start pi against this checkout in JSON mode with an isolated runtime-only prompt, then write Markdown and raw event/stderr smoke artifacts under `.pi-ca-leash/smoke/auto/`.
+- Added `npm run smoke:pi` and `npm run smoke:pi:codex` helpers that start pi against this checkout with `--no-extensions -e <repo-root>` for isolated pre-release hands-on smoke testing.
+- Automated pi smoke runs now stop the `pi --no-session` child after an explicit `SMOKE_OK`/`SMOKE_FAIL` final marker instead of waiting for the idle CLI process to exit by itself.
+- Extension startup is now lazy: loading registers commands/tools only, while `/peer init` or the first actionable `/peer` command starts the widget/background workflow and shows the operator guide.
+- Moved core extension prompt/guidance text into editable files under `extensions/prompts/`.
+- Added a bundled Lanista-derived runtime model catalog for `claude-sdk` and `codex-cli`, exposed through `runtime_models` and `/peer models`.
+- `/peer start` can now include explicit driver and model fields in pipe syntax.
+- Runtime tool guidance now points agents to `runtime_models` before choosing non-default model ids.
+- Polished README setup, persistence, and runtime-driver wording around the current local MVP.
+- Polished the compact Peers widget with peer counts, column labels, priority ordering, clearer context usage, and explicit local-mode broker warning text.
+- Aligned workspace package versions with the root `0.3.0` package version.
+- Reworked README into the single practical entrypoint, with the useful manual smoke and peer no-polling guidance folded in.
+
+### Fixed
+- `subagent_status` now accepts the same short run id prefixes shown by `subagent_run` and `subagent_list`, while still rejecting unknown or ambiguous prefixes.
+- `--no-session` smoke runs no longer start dashboard/background peer polling or emit stale peer follow-up turns after cleanup.
+
+### Removed
+- Removed the redundant direct runtime dependency on `@anthropic-ai/sdk`; the runtime imports `@anthropic-ai/claude-agent-sdk`, and the root override remains as a guard for SDK resolution through that dependency tree.
+- Removed unused internal TypeScript declarations found by `noUnusedLocals` / `noUnusedParameters` checks.
+- Removed leftover standalone manual/stress-test Markdown files from the public repo root.
+
+## 0.2.0 - 2026-05-03
+
+### Changed
+- Public slash-command UX now centers on `/peer` (`dashboard`, `start`, `ask`, `send`, `list`, `history`, `interrupt`, `stop`).
+- Old `/claude-*` slash commands are hidden by default and only restored with `PI_CA_LEASH_ENABLE_LEGACY_COMMANDS=1`; old internal diagnostics additionally require `PI_CLAUDE_ENABLE_ADVANCED_COMMANDS=1`.
+- Command result renderer, widget key/title, hints, and peer guidance now use `peer`/`pi-ca-leash` branding instead of `cca` or old extension labels.
+- README install instructions now pin the public release as `git:github.com/durandom/pi-ca-leash@v0.2.0`.
+- Pi host peer dependencies are marked optional so clean git installs do not download pi core packages unnecessarily.
+- Root package overrides now guard `@anthropic-ai/sdk` resolution through the current Claude agent SDK dependency tree.
+
+### Removed
+- Scratch/planning markdown files that should not ship in the public package.
+
+## 0.1.1 - 2026-05-03
+
+### Fixed
+- Git pi package installs now build workspace packages during install so extension imports can resolve package `dist/index.js` files.
+- README install instructions now use the renamed `durandom/pi-ca-leash` repository URL.
+
+## 0.1.0 - 2026-05-03
+
+### Changed
+- Renamed the pi package/extension surface to `pi-ca-leash` while keeping the internal runtime package names and honest `claude-code-agent` runner identity unchanged.
+- Runtime now includes an optional experimental `codex-cli` driver, bridge peers now persist selected runtime driver identity, extension startup can select the default driver for new peers via `PI_CLAUDE_RUNTIME_DRIVER`, LLM-callable `peer_start` can override the driver per peer, subagent/team backend APIs can thread runtime driver selection, the runtime/subagent/team demo CLIs now honor `PI_CLAUDE_RUNTIME_DRIVER` for Codex-backed smoke checks, and the extension now exposes LLM-callable subagent/team tools.
+- Extension default UX is now peer-first.
+- Primary footer status line was removed from the main UX.
+- Compact widget now shows one live row per peer with short activity summaries derived from runtime events.
+- `/claude-dashboard` now defaults to a peer-first view, with retained backend diagnostics moved to `/claude-dashboard advanced`.
+- `/claude-peer-start` and `/claude-peer-ask` now emit immediate acknowledgment messages before final completion.
+- LLM-callable `peer_start` now returns and displays no-babysitting guidance, and `peer_ask` now returns and displays the outgoing prompt sent to the peer.
+- Runtime Peers widget rows now include each peer's last update time.
+- Claude SDK result usage now preserves last-known context-window metrics, and peer rows show `ctx <percent>%` when available.
+- LLM-callable `peer_ask` now shows the outgoing prompt once as direct `[cca] Sent to peer` user feedback while keeping the tool result compact.
+- Stopped peers are hidden from the compact Runtime Peers widget but remain visible in `/claude-dashboard`.
+- Codex usage parsing now preserves cached/reasoning token counts internally, but compact peer rows only show `ctx <percent>%` when a trustworthy context-window percentage is available.
+- Added fire-and-forget peer messaging via `peer_send` and `/claude-peer-send`, plus graceful peer interruption via `peer_interrupt` and `/claude-peer-interrupt`.
+- `peer_ask` timeouts after successful delivery now return `delivered_and_running` instead of reporting a confusing delivery failure.
+- `/claude-peer-start <prompt>` now auto-generates a short peer name, while `/claude-peer-start <name> | <prompt>` remains available as an explicit override.
+- Internal slash commands (`/claude-dev-ping`, `/claude-runtime-list`, `/claude-subagent-*`, `/claude-attention-*`, `/claude-team-*`) are now hidden from the default UX and only reappear when pi starts with `PI_CLAUDE_ENABLE_ADVANCED_COMMANDS=1`.
+- Peer completions now inject one wrapped follow-up turn into the main agent by default, carrying the peer's latest message when the peer finishes, needs input, or errors.
+- Peer tool output and wrapped peer relays now fence latest visible peer messages as raw text blocks for cleaner multiline boundaries and safer relay inspection.
+- LLM-callable peer tools now support explicit start-time `model` and `cwd`, and `peer_ask` can persistently switch the peer model for later turns.
+- Main-agent peer transcript scrolling is now available through `peer_history(name, cursor?, limit?)`, including cursor-based paging through visible peer messages and tool activity.
+- `peer_stop` can now bulk-stop all retained peers when explicitly confirmed with `all=true` and `confirmAll=true`.
+- `peer_history` paging now counts visible history entries instead of raw transcript events, which makes scrolling behave more like a human reading backscroll.
+- Runtime now preserves an explicitly requested model switch across resumed-session init events that report a stale prior model.
+- Primary peer operations are now also exposed as LLM-callable tools: `peer_start`, `peer_list`, `peer_history`, `peer_ask`, and `peer_stop`.
+- README, architecture notes, and known limits were updated to match peer-first MVP behavior.
+
+### Notes
+- Codex support is still partial: extension startup can choose a default peer driver, per-peer driver override exists on the LLM-callable `peer_start` tool, slash-command peer UX still has no per-peer driver selection, subagent/team driver threading is available through backend APIs and LLM-callable tools but not through slash-command/visual UX, and these surfaces are not being described as Codex-parity products.
+- Historical session-plan docs were removed in favor of a single current documentation set.
+
+## 2026-04-29
+
+### Added
+- Persisted intercom peer registry with restart restore.
+- Optional live `pi-intercom` transport adapter.
+- Late transport binding and retry logic for broker availability.
+- Subagent backend rehydration from persisted runtime state.
+- Attention events for stale background runs.
+- Dashboard surfacing for intercom state and attention state.
+- Intercom disconnect/reconnect notices in the extension.
+- Attention list / ack / snooze extension commands.
+- Persisted local attention ledger for ack/snooze state.
+- Extension helper/state tests.
+- Extension persistence tests.
+
+### Changed
+- Teams backend scope is now documented and enforced as **local-only**.
+- README was rewritten around current reality instead of session-plan history.
+- Package metadata was cleaned up to stop implying `pi-teams` integration.
+
+### Removed
+- Historical `docs/IMPLEMENTATION_PLAN.md`.
+- Historical `docs/sessions/*` handoff/session documents.
+- Remaining `pi-teams` roadmap narrative.
+
+## 2026-04-25
+
+### Added
+- Initial monorepo structure.
+- Claude runtime package.
+- Intercom bridge package.
+- Subagents backend package.
+- Teams backend package.
+- Initial tests and demo/smoke scripts.