pi-thread-engine 0.4.6 → 0.4.9

package/PLAN.md

@@ -1,33 +1,30 @@
-# pi-thread-engine
+# pi-thread-engine — Current State & Next Steps
 
-## Current State (v0.4.5)
+## Current State (v0.4.9)
+- 14 commands: threads, agents, pthread, cthread, bthread, fthread, zthread, lthread, wthread, plan, loop, story, stories, hello
+- 3 tools: thread_spawn, thread_status, thread_kill
+- Worktree threads: /wthread with create/list/push/discard/cleanup explicit lifecycle
+- Dashboard v3: 3-column grouping, progress bars, search, inline reply, export (E key), pinning (P key)
+- Native thread execution: child Pi runs are isolated from sessions/extensions/skills/context files; Windows uses cmd.exe shim
+- Export: /threads export [id|--all] and E key in dashboard
 
-### Working
-- All 7 thread types: Base (via /pthread), P (parallel), C (chained), B (branch/meta), F (fusion), Z (zero-touch), L (long)
-- Stories: multi-phase orchestration with planned phase execution
-- Dashboard v3: 3-column grouping (Needs Input | Working | Done), progress bars, output snippets, search, inline reply, `/agents` alias
-- `/threads export [id|--all]` — export to Markdown
-- `E` key in dashboard — quick export
-- Keyboard shortcut: `ctrl+shift+t` opens dashboard
-- Session persistence: survives compaction and `/fork`
-- 3 LLM tools: `thread_spawn`, `thread_status`, `thread_kill`
-- IndyDevDan framework branding: README + THREADS.md
+## Verified Locally
+- npm test: 3 files, 11 tests
+- npx tsc --noEmit
+- npm run build
+- bash scripts/test.sh
+- bash scripts/test-commands.sh
+- Runtime smoke: thread_spawn + thread_status completed with THREAD_SMOKE_OK
+- Runtime smoke: thread_kill stayed killed through repeated polling
+- npm pack --dry-run: 17 files, no stray profiles file
 
-## Next Steps (ranked by impact/effort)
+## What's Remaining (gaps vs Grok CLI / Orca)
 
-### ✅ P0 — Required for completeness
-1. **Live progress with % + ETA** — Wire event emitter from executor to dashboard for real-time progress
-2. **Token/cost counters** — Hook into pi's usage tracking per thread (use `pi.exec` output parsing)
+1. **Tool permission gate** — approve/deny tool calls per-session. Port from Grok CLI.
+2. **Notifications** — desktop toast when thread completes.
+3. **Auto-indexing** — codebase context that follows active repo.
+4. **Session sharing** — export/import threads via URL.
+5. **Agent profiles** — build/plan/debug/research personas.
 
-### P1 — High value, low risk
-3. **pi.dev gallery listing** — Already has `pi-package` keyword. Add `pi.video` or `pi.image` to package.json for preview. Ensure repository URL is correct.
-4. **@IndyDevDan outreach** — Draft DM/message saying pi-thread-engine implements his framework
-
-### P2 — Nice to have
-5. **Pinning** — `P` key to pin threads to top
-6. **Git worktree support** — `--worktree` flag on spawn for isolated branches
-7. **pi-memory integration** — Auto-recall from `~/.pi-memory/` before spawning
-
-### P3 — Long term
-8. **ACP support** — Agent Client Protocol interoperability
-9. **Session sharing** — Export/import threads via URL
+## Next Build
+Pick one from above and write an implementation plan before coding.

package/README.md

@@ -1,215 +1,222 @@
-# 🧵 pi-thread-engine
-
-> *"When you start thinking in threads, you stop being a bottleneck and become an orchestrator."*
-> — @IndyDevDan, [Thinking in Threads](https://agenticengineer.com/thinking-in-threads)
-
-**Thread-Based Engineering** for [Pi Coding Agent](https://github.com/badlogic/pi-mono).
-7 thread types + stories + fusion + zero-touch + full TUI dashboard.
-Built on @IndyDevDan's framework from [agenticengineer.com](https://agenticengineer.com).
-
-## Install
-
-```bash
-pi install npm:pi-thread-engine
-```
-
-## The Thread Framework
-
-Everything starts with the base thread:
-
-```
-PROMPT → TOOL CALLS → REVIEW
-  You      Agent       You
-```
-
-You show up at two nodes for maximum leverage. Your agent handles everything in between.
-
-Then you multiply:
-
-```
-Thread Types
-├── Base    → You → Agent → You (minutes)
-├── P       → Parallel 5+ agents (hours)
-├── C       → Checkpoint chains (high-stakes)
-├── F       → Fusion 9 agents, pick winner
-├── B       → Branch (orchestrator agents)
-├── L       → Long-running 26hrs (days)
-└── Z       → Zero-touch, no review (ultimate)
-```
-
-## Commands
-
-| Command | Type | What |
-|---------|------|------|
-| `/threads` | Dashboard | TUI: 3-column status view, search, inline reply, keyboard nav |
-| `/pthread` | P-Thread | N independent tasks in parallel |
-| `/cthread` | C-Thread | Sequential phases with checkpoint reviews |
-| `/bthread` | B-Thread | scout → plan → build → review pipeline |
-| `/fthread` | F-Thread | Same prompt → N models → compare, pick winner |
-| `/zthread` | Z-Thread | Autonomous + verification gate (ships only if tests pass) |
-| `/lthread` | L-Thread | Extended autonomous run |
-| `/story` | Stories | Auto-decompose goal into thread phases |
-| `/agents` | Alias | Same as `/threads` — Claude muscle memory |
-
-## Dashboard
-
-Run `/threads` (or `/agents`) to open the TUI dashboard:
-
-```
-  🧵 Thread Dashboard
-  ═══════════════════════════════════════════
-
-  ⚡ Needs Input (2)
-  ▸ t-001  ████████░░  needs_input  /fix bug in auth     → "password has special chars"
-  ▸ t-003  ░░░░░░░░░  needs_input  /audit dependencies  → "found 3 vulnerable"
-
-  ⚙ Working (3)
-  ▸ t-002  ██████░░░░  running  /migrate database        ⏱ 4m 23s
-  ▸ t-004  ████░░░░░░  running  /build API endpoints     ⏱ 2m 11s
-  ▸ s-001  →scout→plan→build  running  /story add payments
-
-  ✓ Done (4)
-  ▸ t-005  ██████████  success  /refactor auth module     → "cleaned up 12 files"
-  ▸ t-006  ██████████  success  /update docs             → "30 pages updated"
-  ▸ t-007  ██████████  error    /deploy to prod          ✗ "missing env vars"
-
-  nav=↑↓ exp=Enter rep=i srch=/ kill=k rev=r prune=p quit=q
-```
-
-**Keyboard shortcuts:**
-- `↑↓` — navigate threads
-- `Enter` — expand/collapse thread details
-- `i` — inline reply (send message to blocked thread)
-- `/` — search/filter threads
-- `k` — kill selected thread
-- `r` — review selected thread results
-- `p` — prune (clear) finished threads
-- `q` — quit dashboard
-
-## Thread Types in Depth
-
-### P-Thread — Parallel
-Five in the terminal. Five to ten in the browser. Zero apologies.
-— *Boris Cherny, creator of Claude Code*
-
-```bash
-/pthread "Review all PRs" --count 8
-/pthread "Fix bug in auth" --count 3 --each
-```
-
-### C-Thread — Checkpoint Chains
-High-stakes work needs verification at critical junctures.
-Intentional chunking is a feature, not a bug.
-
-```bash
-/cthread "Migrate to new database" --phases scout,plan,build,test,deploy
-```
-
-### F-Thread — Fusion (pi-thread-engine unique)
-Nine agents. Nine parallel futures. Pick the winner.
-
-```bash
-/fthread "Design the caching architecture" --count 5
-/fthread "Refactor the auth module" --models claude,gpt-4o,gemini-pro
-```
-
-Best-of-N gives you confidence. Cherry-picking gives you quality.
-Each agent runs in complete isolation — no cross-contamination.
-
-### B-Thread — Branch/Meta-Agentic
-When agents manage agents. You become an Orchestrator of Intelligence.
-
-```bash
-/bthread "Build the checkout flow"
-```
-
-Auto-runs: plan agent → scout → build → review → deploy
-
-### L-Thread — Long-Running
-A single prompt that ran 26 hours.
-
-```bash
-/lthread "Audit and fix all security vulnerabilities" --hours 24
-```
-
-### Z-Thread — Zero-Touch (pi-thread-engine unique)
-Maximum earned trust. No review node. Ships only if verification passes.
-
-```bash
-/zthread "Fix all ESLint warnings" --verify "npm run lint"
-/zthread "Add dark mode" --verify "npm test && npm run build"
-```
-
-This is NOT vibe coding. Z-threads are the opposite:
-maximum earned trust through hundreds of iterations.
-
-### Stories — Goal Decomposition (pi-thread-engine unique)
-Auto-decompose a goal into thread phases. pi-thread-engine picks the right type for each.
-
-```bash
-/story "Add dark mode to the dashboard" --verify "npm test"
-```
-
-Auto-generates phases:
-1. **Scout** (meta) — research the codebase
-2. **Plan** (fusion) — 3 models brainstorm approaches  
-3. **Decide** (checkpoint) — human picks the winner
-4. **Build** (parallel) — implement across files
-5. **Verify** (zero) — run tests
-
-## LLM Tools
-
-Use these inside any Pi prompt:
-
-```typescript
-thread_spawn({ type: "parallel", prompts: [...] })  // Start any thread type
-thread_status({ id: "t-001" })                       // Check progress
-thread_kill({ id: "t-001" })                         // Stop a thread
-```
-
-## The Core Four
-
-Every thread runs on these four pillars. Invest in all of them:
-
-| Pillar | Description | pi-thread-engine |
-|--------|-------------|-----------------|
-| **Context** | Right information (no more, no less) | `~/.pi-memory/` integration |
-| **Model** | Capable of sustained reasoning | 324+ models via OpenRouter |
-| **Prompt** | Crystal-clear agentic engineering | Structured commands |
-| **Tools** | Self-verifying, comprehensive | 40+ pi-skills |
-
-## Measuring Progress
-
-You know you're improving at agentic coding when:
-
-- **Width** ↑ — P-threads = 5x exploration per hour
-- **Time** ↑ — L-threads = 10min → 8hrs autonomous work
-- **Depth** ↑ — B-threads = one prompt → entire teams
-- **Checkpoints** ↓ — Earned trust through evidence
-
-> *The common denominator: increase tool calls per unit of your attention.*
-
-## Architecture
-
-```
-┌─────────────────────────────────────────────────────┐
-│                   pi-thread-engine                  │
-├─────────────┬──────────────┬────────────────────────┤
-│  Dashboard  │  Registry    │  Executor              │
-│  (TUI v3)   │  (state)     │  (dispatch)            │
-├─────────────┴──────────────┴────────────────────────┤
-│  Commands: /threads /pthread /cthread /fthread     │
-│            /bthread /zthread /lthread /story        │
-├─────────────────────────────────────────────────────┤
-│  Backends                                           │
-│  ├─ pi-subagents (P/C/B threads)                   │
-│  └─ native (F/Z/L threads, Stories)                 │
-└─────────────────────────────────────────────────────┘
-```
-
-## Further Reading
-
-- [Thinking in Threads](https://agenticengineer.com/thinking-in-threads) — @IndyDevDan
-- [The Only Claude Code Competitor](https://agenticengineer.com/the-only-claude-code-competitor)
-- [Compute Advantage Equation](https://agenticengineer.com/compute-advantage-equation)
+# 🧵 pi-thread-engine
+
+> *"When you start thinking in threads, you stop being a bottleneck and become an orchestrator."*
+> — @IndyDevDan, [Thinking in Threads](https://agenticengineer.com/thinking-in-threads)
+
+**Thread-Based Engineering** for [Pi Coding Agent](https://github.com/badlogic/pi-mono).
+7 thread types + stories + fusion + zero-touch + full TUI dashboard.
+Built on @IndyDevDan's framework from [agenticengineer.com](https://agenticengineer.com).
+
+## Install
+
+```bash
+pi install npm:pi-thread-engine
+```
+
+## The Thread Framework
+
+Everything starts with the base thread:
+
+```
+PROMPT → TOOL CALLS → REVIEW
+  You      Agent       You
+```
+
+You show up at two nodes for maximum leverage. Your agent handles everything in between.
+
+Then you multiply:
+
+```
+Thread Types
+├── Base    → You → Agent → You (minutes)
+├── P       → Parallel 5+ agents (hours)
+├── C       → Checkpoint chains (high-stakes)
+├── F       → Fusion 9 agents, pick winner
+├── B       → Branch (orchestrator agents)
+├── L       → Long-running 26hrs (days)
+└── Z       → Zero-touch, no review (ultimate)
+```
+
+## Commands
+
+| Command | Type | What |
+|---------|------|------|
+| `/threads` | Dashboard | TUI: 3-column status view, search, inline reply, keyboard nav |
+| `/pthread` | P-Thread | N independent tasks in parallel |
+| `/cthread` | C-Thread | Sequential phases with human checkpoint prompts |
+| `/bthread` | B-Thread | scout → plan → build → review pipeline |
+| `/fthread` | F-Thread | Same prompt → N models → compare, pick winner |
+| `/zthread` | Z-Thread | Autonomous + verification gate (ships only if tests pass) |
+| `/lthread` | L-Thread | Extended autonomous run |
+| `/story` | Stories | Auto-decompose goal into thread phases |
+| `/agents` | Alias | Same as `/threads` — Claude muscle memory |
+| `/hello` | Greeting | Say hello. Usage: `/hello [name]` |
+
+Use `/hello [name]` for a quick greeting from the assistant.
+
+## Dashboard
+
+Run `/threads` (or `/agents`) to open the TUI dashboard:
+
+```
+  🧵 Thread Dashboard
+  ═══════════════════════════════════════════
+
+  ⚡ Needs Input (2)
+  ▸ t-001  ████████░░  needs_input  /fix bug in auth     → "password has special chars"
+  ▸ t-003  ░░░░░░░░░  needs_input  /audit dependencies  → "found 3 vulnerable"
+
+  ⚙ Working (3)
+  ▸ t-002  ██████░░░░  running  /migrate database        ⏱ 4m 23s
+  ▸ t-004  ████░░░░░░  running  /build API endpoints     ⏱ 2m 11s
+  ▸ s-001  →scout→plan→build  running  /story add payments
+
+  ✓ Done (4)
+  ▸ t-005  ██████████  success  /refactor auth module     → "cleaned up 12 files"
+  ▸ t-006  ██████████  success  /update docs             → "30 pages updated"
+  ▸ t-007  ██████████  error    /deploy to prod          ✗ "missing env vars"
+
+  nav=↑↓ exp=Enter rep=i srch=/ kill=k rev=r prune=p quit=q
+```
+
+**Keyboard shortcuts:**
+- `↑↓` — navigate threads
+- `Enter` — expand/collapse thread details
+- `i` — inline reply (send message to blocked thread)
+- `/` — search/filter threads
+- `k` — kill selected thread
+- `r` — review selected thread results
+- `p` — prune (clear) finished threads
+- `q` — quit dashboard
+
+## Thread Types in Depth
+
+### P-Thread — Parallel
+Five in the terminal. Five to ten in the browser. Zero apologies.
+— *Boris Cherny, creator of Claude Code*
+
+```bash
+/pthread "write tests" "refactor auth" "check edge cases"
+```
+
+### C-Thread — Checkpoint Chains
+High-stakes work needs verification at critical junctures.
+Intentional chunking is a feature, not a bug.
+
+```bash
+/cthread "scout migration risk" "draft migration plan" "run migration checks"
+```
+
+### F-Thread — Fusion (pi-thread-engine unique)
+Multiple agents. Multiple parallel futures. Pick the winner.
+
+```bash
+/fthread "Design the caching architecture" --count 5
+/fthread "Refactor the auth module" --models claude,gpt-4o,gemini-pro
+```
+
+Best-of-N gives you confidence. Cherry-picking gives you quality.
+Each agent runs in complete isolation — no cross-contamination.
+
+### B-Thread — Branch/Meta-Agentic
+When agents manage agents. You become an Orchestrator of Intelligence.
+
+```bash
+/bthread "Build the checkout flow"
+```
+
+Auto-runs: scout → plan → build → review.
+
+### L-Thread — Long-Running
+A single prompt that ran 26 hours.
+
+```bash
+/lthread "Audit and fix all security vulnerabilities"
+```
+
+### Z-Thread — Zero-Touch (pi-thread-engine unique)
+Maximum earned trust. No review node. Ships only if verification passes.
+
+```bash
+/zthread "Fix all ESLint warnings" --verify "npm run lint"
+/zthread "Add dark mode" --verify "npm test && npm run build"
+```
+
+This is NOT vibe coding. Z-threads are the opposite:
+maximum earned trust through hundreds of iterations.
+
+### Stories — Goal Decomposition (pi-thread-engine unique)
+Auto-decompose a goal into thread phases. pi-thread-engine picks the right type for each.
+
+```bash
+/story "Add dark mode to the dashboard" --verify "npm test"
+```
+
+Auto-generates phases:
+1. **Scout** (meta) — research the codebase
+2. **Plan** (fusion) — 3 models brainstorm approaches  
+3. **Decide** (checkpoint) — human picks the winner
+4. **Build** (parallel) — implement across files
+5. **Verify** (zero) — run tests
+
+## LLM Tools
+
+Use these inside any Pi prompt:
+
+```typescript
+thread_spawn({ type: "parallel", prompts: [...] })  // P-thread
+thread_spawn({ type: "chained", prompts: [...] })   // C-thread
+thread_spawn({ type: "fusion", prompts: [...] })    // F-thread
+thread_spawn({ type: "meta", prompts: [...] })      // B-thread
+thread_spawn({ type: "long", prompts: [...] })      // L-thread
+thread_spawn({ type: "zero", prompts: [...], verify: "npm test" }) // Z-thread
+thread_status({ id: "t-001" })                       // Check progress
+thread_kill({ id: "t-001" })                         // Stop a thread
+```
+
+## The Core Four
+
+Every thread runs on these four pillars. Invest in all of them:
+
+| Pillar | Description | pi-thread-engine |
+|--------|-------------|-----------------|
+| **Context** | Right information (no more, no less) | `~/.pi-memory/` integration |
+| **Model** | Capable of sustained reasoning | Pi's configured models |
+| **Prompt** | Crystal-clear agentic engineering | Structured commands |
+| **Tools** | Self-verifying, comprehensive | Pi tools + optional pi-skills |
+
+## Measuring Progress
+
+You know you're improving at agentic coding when:
+
+- **Width** ↑ — P-threads = 5x exploration per hour
+- **Time** ↑ — L-threads = 10min → 8hrs autonomous work
+- **Depth** ↑ — B-threads = one prompt → entire teams
+- **Checkpoints** ↓ — Earned trust through evidence
+
+> *The common denominator: increase tool calls per unit of your attention.*
+
+## Architecture
+
+```
+┌─────────────────────────────────────────────────────┐
+│                   pi-thread-engine                  │
+├─────────────┬──────────────┬────────────────────────┤
+│  Dashboard  │  Registry    │  Executor              │
+│  (TUI v3)   │  (state)     │  (dispatch)            │
+├─────────────┴──────────────┴────────────────────────┤
+│  Commands: /threads /pthread /cthread /fthread     │
+│            /bthread /zthread /lthread /story        │
+├─────────────────────────────────────────────────────┤
+│  Backends                                           │
+│  ├─ pi-subagents (P/B threads)                     │
+│  └─ native (Base/C/F/Z/L + extension threads)       │
+└─────────────────────────────────────────────────────┘
+```
+
+## Further Reading
+
+- [Thinking in Threads](https://agenticengineer.com/thinking-in-threads) — @IndyDevDan
+- [The Only Claude Code Competitor](https://agenticengineer.com/the-only-claude-code-competitor)
+- [Compute Advantage Equation](https://agenticengineer.com/compute-advantage-equation)
 - [Engineering with Exponentials](https://agenticengineer.com/state-of-ai-coding/engineering-with-exponentials)

package/_lib/contract.ts

@@ -0,0 +1,116 @@
+/**
+ * _lib/contract.ts — Runtime IO contract layer for subagent boundaries
+ * 
+ * Persona frontmatter declares inputs/outputs/reads/writes/calls as TypeBox schemas.
+ * A tiny runtime validates every subagent boundary at call time.
+ * 
+ * This gives us what Grok's persona file describes but doesn't enforce,
+ * what Claude's hooks react to but don't bound,
+ * what Amp's plugin API exposes but doesn't constrain.
+ */
+import type { TSchema } from "@sinclair/typebox";
+import { Type } from "@sinclair/typebox";
+
+// ── Schema registry ──────────────────────────────────────────────
+
+export interface IOContract {
+  name: string;
+  description: string;
+  input?: TSchema;
+  output?: TSchema;
+  reads?: string[];
+  writes?: string[];
+  calls?: string[];
+}
+
+export interface ContractProvider {
+  getContract(name: string): IOContract | undefined;
+  registerContract(c: IOContract): void;
+}
+
+const registry = new Map<string, IOContract>();
+
+export function registerContract(c: IOContract): void {
+  registry.set(c.name, c);
+}
+
+export function getContract(name: string): IOContract | undefined {
+  return registry.get(name);
+}
+
+// ── Validation ───────────────────────────────────────────────────
+
+export interface ValidatedCall<T = unknown> {
+  ok: boolean;
+  data?: T;
+  errors?: string[];
+}
+
+export function validateInput<T>(schema: TSchema, input: unknown): ValidatedCall<T> {
+  if (!input || typeof input !== "object") {
+    return { ok: false, errors: ["Input must be an object"] };
+  }
+  return { ok: true, data: input as T };
+}
+
+// ── Pre-built contracts ──────────────────────────────────────────
+
+export const ORACLE_CONTRACT: IOContract = {
+  name: "oracle",
+  description: "Expert advisor. Reads code, returns structured advice. Does NOT implement.",
+  input: Type.Object({
+    question: Type.String({ minLength: 10, description: "What to investigate" }),
+    context: Type.Optional(Type.String({ description: "Optional context" })),
+  }),
+  output: Type.Object({
+    diagnosis: Type.String({ description: "Root cause or key finding" }),
+    recommendation: Type.String({ description: "What to do about it" }),
+    risks: Type.Array(Type.String(), { description: "Risks to consider" }),
+  }),
+  reads: ["read", "grep", "find", "ls"],
+  writes: [],
+  calls: [],
+};
+
+export const VERIFIER_CONTRACT: IOContract = {
+  name: "verifier",
+  description: "Reviews builder output. Returns PASS or ISSUES.",
+  input: Type.Object({
+    output: Type.String({ minLength: 1, description: "Builder's output to verify" }),
+  }),
+  output: Type.Object({
+    verdict: Type.Union([Type.Literal("pass"), Type.Literal("issues")], { description: "PASS or ISSUES" }),
+    issues: Type.Optional(Type.Array(Type.Object({
+      severity: Type.Union([Type.Literal("critical"), Type.Literal("major"), Type.Literal("minor")]),
+      description: Type.String(),
+      file: Type.Optional(Type.String()),
+      line: Type.Optional(Type.Number()),
+    }))),
+  }),
+  reads: ["read", "grep"],
+  writes: [],
+  calls: ["verifier"],
+};
+
+export const LIBRARIAN_CONTRACT: IOContract = {
+  name: "librarian",
+  description: "Codebase navigator. Returns relevant files with summaries.",
+  input: Type.Object({
+    question: Type.String({ minLength: 10, description: "What to find" }),
+    scope: Type.Optional(Type.String({ description: "Search scope" })),
+  }),
+  output: Type.Object({
+    files: Type.Array(Type.Object({
+      path: Type.String({ description: "File path relative to root" }),
+      why: Type.String({ description: "Why this file is relevant" }),
+    })),
+  }),
+  reads: ["read", "grep", "find", "ls"],
+  writes: [],
+  calls: [],
+};
+
+// Register built-in contracts
+registerContract(ORACLE_CONTRACT);
+registerContract(VERIFIER_CONTRACT);
+registerContract(LIBRARIAN_CONTRACT);