pi-ca-leash 0.10.0

package/DEVELOPMENT.md

@@ -0,0 +1,197 @@
+# Development
+
+This repository is a local runtime-first MVP. Keep development workflows honest:
+
+- automated smoke covers the runtime-backed tool surface only
+- manual smoke covers slash commands, dashboard, widget, and operator UX
+- failing smoke runs are debug artifacts, not release notes
+
+## Prerequisites
+
+You need:
+
+- a real `pi` installation
+- working auth/provider setup for whichever runtime driver you use
+- `npm install`
+
+## Main commands
+
+### Default driver
+
+```bash
+npm test
+npm run build
+npm run smoke:dev
+npm run smoke:last
+npm run smoke:manual
+npm run smoke:clean
+```
+
+### Codex driver
+
+```bash
+npm run smoke:dev:codex
+npm run smoke:manual:codex
+```
+
+### Lower-level commands
+
+```bash
+npm run smoke:pi:auto
+npm run smoke:pi:auto:codex
+npm run smoke:pi
+npm run smoke:pi:codex
+```
+
+## Recommended loops
+
+### Normal development loop
+
+```bash
+npm run smoke:dev
+npm run smoke:last
+```
+
+Use this after meaningful runtime/tool changes.
+
+### Manual slash-command follow-up
+
+```bash
+npm run smoke:manual
+```
+
+Use this when you changed:
+
+- `/peer` command behavior
+- dashboard/widget rendering
+- attention UX
+- startup/operator guidance
+- anything where live interactive feel matters
+
+### Codex-specific loop
+
+```bash
+npm run smoke:dev:codex
+npm run smoke:manual:codex
+```
+
+Use this when changing driver threading or Codex-specific behavior.
+
+## What the automated smoke actually tests
+
+`npm run smoke:pi:auto` starts `pi` in JSON mode from this checkout with:
+
+- `--no-extensions -e <repo-root>`
+- no builtin tools
+- no context files, skills, prompts, or themes
+
+The prompt is fixed and runtime-only. It exercises:
+
+- `peer_start`
+- `peer_list`
+- `peer_ask`
+- `peer_history`
+- `peer_stop`
+- `subagent_run`
+- `subagent_list`
+- `subagent_status`
+- `team_spawn`
+- `team_list`
+- `team_task`
+- `team_message`
+- `team_stop`
+
+It does **not** try to validate:
+
+- dashboard or widget rendering
+- slash-command UX quality
+- manual operator ergonomics
+- broader TUI behavior
+
+## Automated smoke artifacts
+
+Each automated run writes artifacts under:
+
+```text
+.pi-ca-leash/smoke/auto/<timestamp-id>/
+  prompt.md
+  report.md
+  events.jsonl
+  stderr.log
+```
+
+And also refreshes:
+
+```text
+.pi-ca-leash/smoke/auto/latest.md
+```
+
+### How to read them
+
+- `report.md` — human summary and pass/fail result
+- `events.jsonl` — exact event timeline from pi JSON mode
+- `stderr.log` — runtime/host stderr
+- `prompt.md` — exact prompt used for that run
+
+## Debugging with smoke artifacts
+
+When `smoke:dev` or `smoke:pi:auto` fails:
+
+1. read `npm run smoke:last`
+2. inspect the matching run directory
+3. check which tool step failed
+4. inspect `events.jsonl` for sequencing or tool-result details
+5. inspect `stderr.log` for host/runtime issues
+6. fix the bug
+7. rerun the smoke
+8. add or adjust a focused test when the bug deserves permanent coverage
+
+Good use of saved runs:
+
+- keep interesting failing runs while debugging
+- compare runs before/after behavior changes
+- keep maybe one passing run during a release pass
+
+Bad use:
+
+- committing raw smoke artifacts
+- treating broad smoke logs as a replacement for tests
+
+## Cleanup
+
+Remove saved automated smoke artifacts with:
+
+```bash
+npm run smoke:clean
+```
+
+The whole `.pi-ca-leash/` tree is already git-ignored.
+
+## Manual smoke checklist
+
+Use this before claiming the repo is ready to share:
+
+1. `npm test`
+2. `npm run build`
+3. `npm run smoke:dev`
+4. `npm run smoke:manual`
+5. in pi, run `/peer`, `/peer start`, `/peer ask`, `/peer list`, `/peer stop`
+6. run `/peer dashboard advanced`
+7. confirm retained backend diagnostics are believable
+8. when explicitly testing installed-package behavior rather than local `-e` loading, restart pi and confirm persisted peers/backends restore honestly
+
+## Notes on persistence during development
+
+Repository-local runtime state lives under:
+
+```text
+.pi-ca-leash/
+  runtime/
+  bridge/
+  subagents/
+  teams/
+  extension/
+  smoke/
+```
+
+Delete or move `.pi-ca-leash/` when you need a truly clean local state.

package/KNOWN_LIMITS.md

@@ -0,0 +1,80 @@
+# Known Limits
+
+This file is intentionally blunt.
+
+## Product/integration limits
+
+1. **No real upstream `pi-subagents` integration is proven here.**
+   - This repo contains local backend logic and extension wiring.
+   - It should not be described as shipped upstream integration unless that is separately verified.
+
+2. **No external `pi-teams` integration exists here.**
+   - Teams backend is local to this repository.
+   - Do not imply compatibility with a package/product that is not actually present.
+
+3. **Claude fork semantics are not supported.**
+   - `runner=claude-code-agent` rejects real `fork`.
+   - Better an explicit error than a fake branch illusion.
+
+4. **Codex support is partial and still not parity-complete.**
+   - Runtime has an experimental `codex-cli` driver.
+   - Bridge peers can carry driver identity, including `driver: "codex-cli"`.
+   - Extension startup can select Codex as the default driver for new peers via `PI_CLAUDE_RUNTIME_DRIVER=codex-cli`.
+   - Per-peer driver override exists on the LLM-callable `peer_start` tool.
+   - Public `/peer start` slash-command docs can thread driver and model selection, but treat Codex selection as experimental.
+   - Subagents and teams backend APIs, demo CLIs, and LLM-callable tools can thread driver selection, but public slash-command UX still does not expose subagent/team driver selection.
+   - The bundled model catalog is advisory and generated from Lanista snapshots; it does not prove that the local CLI or account can use every listed model.
+   - Workspace tests do not require a real `codex` binary, but local smoke validation can use a real one.
+   - Context-window percentage is currently Claude SDK-derived only; Codex-backed peers show no `ctx` value unless a trustworthy context window can be derived later.
+   - Codex effective default model can be shown from the bundled catalog, but the runtime still trusts the Codex CLI for actual model resolution.
+
+## Runtime/host limits
+
+5. **Full extension-host smoke coverage is still environment-dependent.**
+   - Workspace/package tests pass.
+   - Extension helper/state logic is tested directly.
+   - Real pi-host loading still depends on an actual pi installation and host runtime.
+
+6. **Live intercom broker transport is optional.**
+   - If the broker is unreachable, local runtime-backed peers still work.
+   - Live presence/messaging through the broker is unavailable until reconnect.
+   - The extension now waits until `/peer init`, another actionable `/peer` command, or an LLM-callable runtime tool before starting background broker checks.
+
+7. **Cross-process resurrection is partial, not magical.**
+   - Persisted state survives.
+   - In-flight control of an already-running host-local process does not fully survive arbitrary host loss.
+
+## UX/coordination limits
+
+8. **Attention ack/snooze is local extension state.**
+   - It is persisted across pi restarts in this repo.
+   - It is not a shared multi-host or cross-session control protocol.
+
+9. **Teams workflow is intentionally simple.**
+   - Task classification is heuristic (`DONE:` / `BLOCKED:` style replies).
+   - There is no rich board UI, inbox app, or broader collaboration product layer.
+
+10. **Busy handling is strict.**
+   - A busy peer can reject concurrent inbound work instead of queueing it.
+   - There is no sophisticated queueing/scheduling layer yet.
+
+11. **Peer auto-naming is heuristic.**
+    - Default `/peer start <prompt>` derives a short readable name from prompt text.
+    - Use `/peer start <name> | <prompt>` when you need an exact stable name.
+
+12. **Peer working directory is fixed at start time.**
+    - Peer tools can choose `cwd` when starting a peer.
+    - Changing `cwd` later requires starting a new peer session.
+
+13. **Default peer UX is intentionally compressed.**
+    - The main window does not stream live peer transcript output.
+    - Peer completion is relayed back as one wrapped follow-up turn instead of live transcript spam.
+    - Detailed retained backend diagnostics live in `/peer dashboard advanced`.
+    - Legacy `/claude-*` slash commands stay hidden unless you start pi with `PI_CA_LEASH_ENABLE_LEGACY_COMMANDS=1`.
+    - Old internal diagnostic slash commands also require `PI_CLAUDE_ENABLE_ADVANCED_COMMANDS=1`.
+
+## Documentation limits
+
+14. **This repo is documented as a local MVP, not a final product.**
+    - If the implementation grows, docs must stay equally honest.
+    - Remove stale claims rather than letting optimistic historical docs linger.

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 durandom
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,288 @@
+# pi-ca-leash
+
+Harness-aware Claude Code and Codex CLI extension for pi.
+
+Claude Code and Codex CLI are more than model endpoints. They are coding harnesses with their own tool loops, session semantics, and increasingly harness-optimized models. `pi-ca-leash` treats them that way.
+
+Pi stays in the brain seat — like a human coordinating multiple coding agents. It can start long-lived workers, hand them scoped tasks, wait for results, inspect what they did, and decide what happens next.
+
+Claude is the default and most complete path today. Codex works too, but is still experimental and not parity-complete.
+
+## What it adds
+
+After installation, pi gets:
+- named long-lived peers with `/peer start`, `/peer ask`, `/peer send`, `/peer history`, and `/peer stop`
+- a peer dashboard plus local attention state
+- LLM-callable peer tools such as `peer_start`, `peer_ask`, `peer_send`, `peer_history`, and `runtime_models`
+- optional local subagent-style runs and local persistent teammates behind advanced commands/tools
+- optional live intercom transport when the broker is reachable
+
+What this package does **not** claim:
+- no real upstream `pi-subagents` integration
+- no external `pi-teams` integration
+- no real Claude fork/session-tree semantics
+- no host-independent full pi extension smoke test
+
+## Example session
+
+Fictional but representative flow:
+
+```text
+You: /peer dashboard
+
+You: Start a planner peer to understand the auth flow and propose the safest implementation plan.
+
+You: Start an implementer peer too, but keep it waiting for my approved plan before editing anything.
+
+Pi/main agent:
+- uses peer tools to start both workers
+- keeps control of the conversation
+- receives planner output automatically when it is ready
+- decides what plan to approve
+
+Sample peer state:
+- planner      idle      summarized auth flow and proposed scoped plan
+- implementer  waiting   ready for approved implementation handoff
+
+You: Send the approved plan to the implementer. Keep changes scoped. Report files changed, commands run, tests, and residual risk.
+
+Pi/main agent:
+- inspects the implementer result
+- asks follow-up questions if needed
+- gives the final answer to the user
+```
+
+That is core idea: pi is not replaced by child agents. Pi orchestrates them.
+
+Once peer mode is active, you can often ask for this in natural language instead of manually driving every peer command.
+
+## Install
+
+For most users, if pi already works on your machine and `pi install` works, you do not need to think about Node directly. `pi install npm:pi-ca-leash` is usually enough.
+
+Requirements for normal use:
+- a working pi installation
+- at least one configured runtime:
+  - Claude Code configured for Claude-backed execution, or
+  - `codex` on `PATH` for experimental Codex-backed runtime checks
+
+Requirements for local development or source installs:
+- Node.js 18 or newer
+- npm
+
+Install from npm:
+
+```bash
+pi install npm:pi-ca-leash
+```
+
+Pin an explicit version when needed:
+
+```bash
+pi install npm:pi-ca-leash@0.10.0
+```
+
+Install from a pinned git release:
+
+```bash
+pi install git:github.com/durandom/pi-ca-leash@v0.10.0
+```
+
+Try this checkout locally:
+
+```bash
+npm install
+npm test
+npm run build
+pi install /absolute/path/to/pi-ca-leash
+```
+
+`npm install` runs the workspace build through `prepare`, so local development and git-based installs have package `dist/` files available.
+
+Use Codex as the default runtime driver for newly started peers:
+
+```bash
+PI_CLAUDE_RUNTIME_DRIVER=codex-cli pi
+```
+
+Persisted peers keep their recorded driver.
+
+## Try this first
+
+Inside pi:
+
+```text
+/peer about
+/peer init
+/peer start reviewer | Review this repo briefly and report one concrete risk.
+# keep working or wait; completion relays automatically
+/peer ask reviewer | Reply with exactly: peer-ok
+/peer dashboard advanced
+```
+
+If you want Codex-backed peers, inspect the bundled Codex catalog first:
+
+```text
+/peer models codex-cli
+```
+
+## How it works
+
+After peer mode is active, the main agent can use the peer tools directly, and you can usually steer it in plain language.
+
+Mental model:
+- the main agent stays in charge; peers are delegated workers, not replacements for the orchestrator
+- peers are long-lived sessions, so follow-up messages continue the same worker instead of starting from scratch
+- most peers work in the same repository checkout; prefer short prompts plus file-based handoffs over pasting large context
+- start bounded peer jobs, keep working in the main turn, and wait for the automatic completion/block/failure relay
+- use `ask` when you need a reply now, `send` for fire-and-forget follow-up work, and `history` only when you need to scroll back for evidence
+- do not babysit peers with repeated status polling
+
+Primary slash-command surface:
+
+```text
+/peer
+/peer help
+/peer about
+/peer init
+/peer dashboard
+/peer dashboard advanced
+/peer start <prompt>
+/peer start <prompt> | <driver> | <model>
+/peer start <name> | <prompt>
+/peer start <name> | <prompt> | <driver> | <model>
+/peer ask <name> | <message>
+/peer send <name> | <message>
+/peer list
+/peer models [claude-sdk|codex-cli] [all|advanced|verbose]
+/peer history <name> [cursor] [limit]
+/peer interrupt <name>
+/peer stop <name>
+/peer stop --all --confirm
+```
+
+LLM-callable tools:
+
+```text
+runtime_models(driver?, verbose?)
+extension_log(category?, severity?, summary, observed?, expected?, reproduction?, suggestedFix?, relatedCommand?, relatedTool?, files?)
+peer_start(prompt, name?, driver?, model?, cwd?)
+peer_list()
+peer_history(name, cursor?, limit?)
+peer_ask(name, message, model?)
+peer_send(name, message, model?)
+peer_interrupt(name)
+peer_stop(name?, all?, confirmAll?)
+```
+
+Advanced LLM-callable backend tools are hidden by default while their integration model is still being refined. Enable them only for development with `PI_CLAUDE_ENABLE_ADVANCED_COMMANDS=1`:
+
+```text
+subagent_run(task, name?, prompt?, driver?, model?, cwd?, async?)
+subagent_list()
+subagent_status(runId)
+team_spawn(name, prompt, driver?, model?, cwd?)
+team_task(name, title, details)
+team_message(name, message)
+team_list()
+team_stop(name)
+```
+
+Legacy `/claude-*` commands are hidden by default. Re-enable old peer commands only for compatibility:
+
+```bash
+PI_CA_LEASH_ENABLE_LEGACY_COMMANDS=1 pi
+```
+
+Re-enable old internal diagnostics for development:
+
+```bash
+PI_CA_LEASH_ENABLE_LEGACY_COMMANDS=1 PI_CLAUDE_ENABLE_ADVANCED_COMMANDS=1 pi
+```
+
+## Behavior
+
+The extension is lazy. Loading it registers commands and tools, but it does not start the Peers widget, background monitor, or intercom transport checks immediately. `/peer` with no args opens the dashboard and activates peer mode. `/peer init` also activates the peer workflow, adds the one-time orchestration guide to the main agent context, and shows the user a compact command cheat sheet as a user-only UI notification. The first actionable `/peer` command, such as `/peer models`, `/peer dashboard`, `/peer list`, or `/peer start`, also activates it and adds that agent guide once. `/peer help` and `/peer about` stay passive and show user-only UI notifications. `/peer about` reports the installed package version, package root, state root, default driver, and session mode.
+
+Peers are asynchronous workers. The main agent should start a peer, continue useful work, and wait for the automatic peer completion, blocked, or failure relay. It should not poll `peer_list`, `peer_history`, or repeated `peer_ask` just to see whether the peer is done. When a peer returns, the main agent still owns verification, synthesis, and the final answer.
+
+The extension keeps peer output quiet by default:
+- peer work does not stream child transcript spam into the main window
+- peer command acknowledgments and reports are user-only UI notifications, not main-agent context
+- peer completion is relayed back as one wrapped follow-up turn with the latest visible peer message
+- detailed backend diagnostics live in `/peer dashboard advanced`
+
+Runtime driver notes:
+- `claude-sdk` is the default and most complete path
+- `codex-cli` is supported, but still experimental and not parity-complete
+- `PI_CLAUDE_RUNTIME_DRIVER=codex-cli` changes the default for newly started peers
+- `/peer models` and LLM-callable `runtime_models` show a short recommended model list by default, including advisory use cases
+- `/peer models ... all` and `runtime_models(verbose: true)` expose the full bundled Lanista-derived model catalog
+- LLM-callable `peer_start`, `peer_ask`, and `peer_send` can pass explicit model ids
+- `/peer start` can pass driver and model in pipe syntax
+- common catalog aliases such as `sonnet`, `opus`, `haiku`, `mini`, and `spark` are resolved to exact model ids before runtime launch
+- catalog validation is advisory; unknown model ids are still passed through to the runtime because provider and CLI availability is environment-dependent
+
+## Repository Layout
+
+```text
+packages/
+  runtime/            Claude/Codex runtime abstraction
+  intercom-bridge/    named runtime-backed peers
+  subagents-backend/  local subagent-style run backend
+  teams-backend/      local persistent teammate backend
+extensions/
+  index.ts            pi extension wiring and command/tool surface
+  prompts/            editable operator, tool, peer, and agent guidance text
+```
+
+Useful docs that should remain current:
+- `ARCHITECTURE.md`
+- `KNOWN_LIMITS.md`
+- `CHANGELOG.md`
+- `DEVELOPMENT.md`
+- `AGENTS.md`
+
+## Development
+
+Start here:
+
+```bash
+npm test
+npm run build
+npm run smoke:dev
+npm run smoke:last
+npm run smoke:manual
+```
+
+For the full developer workflow, smoke-command reference, artifact/debugging guide, and manual release checklist, see [`DEVELOPMENT.md`](./DEVELOPMENT.md).
+
+## Persistence
+
+Repository-local runtime state is written under:
+
+```text
+.pi-ca-leash/
+  runtime/
+  bridge/
+  subagents/
+  teams/
+  extension/
+  log.md
+```
+
+These paths are ignored by git. `log.md` is an append-only local feedback log for extension UX rough edges, confusing guidance, poor defaults, and repeated interaction problems. Remove `.pi-ca-leash/` when you need a clean local manual-test session.
+
+Older local development state may also exist under ignored paths such as `.pi-claude-code-agent/`, `.claude-runtime/`, or `undefined/`. Those are not part of the package.
+
+## Limits
+
+The short version:
+- full extension-host smoke testing still needs a real pi installation
+- live intercom broker transport is optional
+- Codex support is partial
+- `runner=claude-code-agent` rejects real `fork`
+- teams backend is local-only
+- attention ack/snooze is local extension state
+
+See `KNOWN_LIMITS.md` for the detailed version.

package/extensions/backend-tool-actions.test.ts

@@ -0,0 +1,59 @@
+import test from "node:test";
+import assert from "node:assert/strict";
+import { buildSubagentRunRequest, buildTeamSpawnRequest } from "./backend-tool-actions.ts";
+
+test("buildSubagentRunRequest threads driver, model, async, and cwd", () => {
+  assert.deepEqual(buildSubagentRunRequest({
+    task: "do work",
+    name: "worker",
+    prompt: "be brief",
+    driver: "claude-sdk",
+    model: "o4-mini",
+    cwd: "/tmp/run",
+    async: true,
+  }, "/base"), {
+    agent: {
+      name: "worker",
+      runner: "claude-code-agent",
+      prompt: "be brief",
+      cwd: "/tmp/run",
+      model: "o4-mini",
+    },
+    task: "do work",
+    driver: "claude-sdk",
+    cwd: "/tmp/run",
+    model: "o4-mini",
+    async: true,
+  });
+});
+
+test("buildSubagentRunRequest falls back to base cwd", () => {
+  const request = buildSubagentRunRequest({
+    task: "do work",
+    name: "worker",
+    prompt: "be brief",
+    driver: "codex-cli",
+    model: undefined,
+    cwd: undefined,
+    async: false,
+  }, "/base");
+  assert.equal(request.driver, "codex-cli");
+  assert.equal(request.cwd, "/base");
+  assert.equal(request.agent.cwd, "/base");
+});
+
+test("buildTeamSpawnRequest threads driver and falls back to base cwd", () => {
+  assert.deepEqual(buildTeamSpawnRequest({
+    name: "teammate",
+    prompt: "hello",
+    driver: "codex-cli",
+    model: "o4-mini",
+    cwd: undefined,
+  }, "/base"), {
+    name: "teammate",
+    prompt: "hello",
+    driver: "codex-cli",
+    model: "o4-mini",
+    cwd: "/base",
+  });
+});

package/extensions/backend-tool-actions.ts

@@ -0,0 +1,31 @@
+import type { StartRunInput } from "@pi-claude-code-agent/subagents-backend";
+import type { SpawnTeammateInput } from "@pi-claude-code-agent/teams-backend";
+import type { ParsedSubagentRunToolInput, ParsedTeamSpawnToolInput } from "./tool-inputs.js";
+
+export function buildSubagentRunRequest(input: ParsedSubagentRunToolInput, baseCwd: string): StartRunInput {
+  const cwd = input.cwd ?? baseCwd;
+  return {
+    agent: {
+      name: input.name,
+      runner: "claude-code-agent",
+      prompt: input.prompt,
+      cwd,
+      model: input.model,
+    },
+    task: input.task,
+    driver: input.driver,
+    cwd,
+    model: input.model,
+    async: input.async,
+  };
+}
+
+export function buildTeamSpawnRequest(input: ParsedTeamSpawnToolInput, baseCwd: string): SpawnTeammateInput {
+  return {
+    name: input.name,
+    prompt: input.prompt,
+    driver: input.driver,
+    model: input.model,
+    cwd: input.cwd ?? baseCwd,
+  };
+}