pi-crew 0.9.51 → 0.9.53

package/docs/archive/pi-mono-review.md

@@ -1,291 +0,0 @@
-# pi-mono Review: Full May 2026 Analysis
-
-**Date:** 2026-05-28  
-**Reviewed:** Direct source reading of `packages/agent/`, `packages/ai/`, `packages/coding-agent/`  
-**Source:** `origin/main` (up to date)
-
-> **Focused coding-agent analysis:** See [`docs/coding-agent-optimization.md`](./coding-agent-optimization.md) for actionable optimization opportunities for pi-crew.
-
----
-
-## Executive Summary
-
-**No breaking changes found.** The entire May refactor is additive or internal. Both `Agent` (legacy harness) and `AgentHarness` (new harness) coexist. pi-crew's usage of the `Agent` class via `child-pi.ts` spawning is **fully compatible**.
-
----
-
-## 1. Architecture: Two Harnesses Coexist
-
-### Legacy Harness: `Agent` class (`packages/agent/src/agent.ts`)
-
-```typescript
-// Still the primary harness used by coding-agent
-export class Agent {
-  async prompt(input: string | AgentMessage | AgentMessage[], images?: ImageContent[]): Promise<void>
-  async abort(): void
-  subscribe(listener: (event: AgentEvent, signal: AbortSignal) => void): () => void
-  // ... existing API unchanged
-}
-```
-
-This is what pi-crew's `child-pi.ts` spawns — **no breaking changes**.
-
-### New Harness: `AgentHarness` class (`packages/agent/src/harness/agent-harness.ts`)
-
-```typescript
-// New harness, built on top of runAgentLoop, with richer APIs
-export class AgentHarness {
-  async prompt(text: string, options?: AgentHarnessPromptOptions): Promise<AssistantMessage>
-  async steer(text: string): Promise<void>
-  async setModel(model: Model<any>): Promise<void>
-  async setThinkingLevel(level: ThinkingLevel): Promise<void>
-  async setResources(resources: AgentHarnessResources): Promise<void>
-  async navigateTree(options: NavigateTreeOptions): Promise<NavigateTreeResult>
-  async abort(): Promise<AbortResult>
-}
-```
-
-**Both use the same `runAgentLoop`** internally. `AgentHarness` wraps it with richer state management, resource loading, and session persistence.
-
-### Session System (`packages/agent/src/harness/session/`)
-
-New formal session infrastructure (1,008 lines across 7 files):
-
-```typescript
-// Session storage with JSONL backend
-SessionStorage<TMetadata> {
-  getMetadata(), setLeafId(), createEntryId(), appendEntry(),
-  getEntry(), findEntries(), getLabel(), getPathToRoot(), getEntries()
-}
-
-// Session repo with fork/list/delete
-SessionRepo<TMetadata, TCreateOptions, TListOptions> {
-  create(), open(), list(), delete(), fork()
-}
-```
-
-**pi-crew's event log** (`src/state/event-log.ts`) uses its own JSONL format — no conflict.
-
----
-
-## 2. New Hooks (AgentHarness)
-
-### `context` hook
-
-Fires before each LLM call to allow context transformation:
-
-```typescript
-// agent-harness.ts line ~413
-const result = await this.emitHook({ type: "context", messages: [...messages] });
-```
-
-**pi-crew relevance:** Currently pi-crew uses `before_agent_start` only. The `context` hook would allow per-turn context injection (e.g., pruning, external context injection).
-
-### `resources_update` hook
-
-Fires when resources (skills/prompt templates) change mid-run:
-
-```typescript
-type: "resources_update";
-resources: AgentHarnessResources;
-previousResources: AgentHarnessResources;
-```
-
-**pi-crew relevance:** Useful for dynamic skill loading during task execution.
-
-### `model_select` / `thinking_level_select` hooks
-
-Fire when the model or thinking level changes mid-run.
-
-**pi-crew relevance:** Supports the `prepareNextTurn` dynamic model switching pattern.
-
----
-
-## 3. New `prepareNextTurn` API
-
-```typescript
-// packages/agent/src/types.ts
-prepareNextTurn?: (
-  context: PrepareNextTurnContext,
-) => AgentLoopTurnUpdate | undefined | Promise<AgentLoopTurnUpdate | undefined>;
-
-interface AgentLoopTurnUpdate {
-  context?: AgentContext;      // replacement context
-  model?: Model<any>;          // new model for next turn
-  thinkingLevel?: ThinkingLevel; // new thinking level
-}
-```
-
-Called after each `turn_end` and before deciding whether to start another LLM call. Enables **dynamic model routing** mid-run without restarting.
-
-**pi-crew relevance:** Process-per-task model means each task is already isolated. No use for `prepareNextTurn`. However, this could enable a future single-process execution mode.
-
----
-
-## 4. New `shouldStopAfterTurn` API
-
-```typescript
-shouldStopAfterTurn?: (context: ShouldStopAfterTurnContext) => boolean | Promise<boolean>;
-```
-
-Called after each turn completes. Return `true` to gracefully stop after the current turn (without starting another LLM call).
-
-**pi-crew relevance:** Could be used to implement turn-count-based task completion (instead of relying on `maxTurns` in child-pi).
-
----
-
-## 5. New `transformContext` API
-
-```typescript
-transformContext?: (messages: AgentMessage[], signal?: AbortSignal) => Promise<AgentMessage[]>;
-```
-
-Applied to context before `convertToLlm` at each turn. For context window management or external context injection.
-
-**pi-crew relevance:** Could replace the current approach of rewriting prompts in `before_agent_start` — instead, transform the full context between turns.
-
----
-
-## 6. Result Type System
-
-```typescript
-// packages/agent/src/harness/types.ts
-export type Result<TValue, TError> = 
-  | { ok: true; value: TValue } 
-  | { ok: false; error: TError };
-
-export function ok<TValue, TError>(value: TValue): Result<TValue, TError>
-export function err<TValue, TError>(error: TError): Result<TValue, TError>
-export function getOrThrow<TValue, TError>(result: Result<TValue, TError>): TValue
-```
-
-Formal result type for all harness filesystem and execution operations. Prevents thrown exceptions for expected failures.
-
-**pi-crew relevance:** No current use. If pi-crew ever uses `AgentHarness` directly, this would be the expected error-handling pattern.
-
----
-
-## 7. Image Generation API (`@earendil-works/pi-ai`)
-
-```typescript
-// packages/ai/src/images.ts
-export async function generateImages<TApi extends ImagesApi>(
-  model: ImagesModel<TApi>,
-  context: ImagesGenerationContext,
-  options?: ImagesGenerationOptions
-): Promise<ImageResult[]>
-```
-
-New image generation capability. Providers: OpenRouter images, Flux, DALL-E, etc.
-
-**pi-crew relevance:** Tasks can now use image generation. No API change needed — pi handles it.
-
----
-
-## 8. Explicit Session ID Naming
-
-```typescript
-// packages/coding-agent/src/core/session-manager.ts
-this.sessionId = options?.id ?? createSessionId();
-```
-
-Users can now specify a custom session ID on startup.
-
-**pi-crew relevance:** Could enhance `inheritContext` feature — pass a named session instead of raw JSON.
-
----
-
-## 9. Stream Options Patch System
-
-```typescript
-// AgentHarnessStreamOptionsPatch — returned by before_provider_request hooks
-export interface AgentHarnessStreamOptionsPatch {
-  transport?: Transport;
-  timeoutMs?: number;
-  maxRetries?: number;
-  headers?: Record<string, string | undefined>; // undefined = delete
-  metadata?: Record<string, unknown | undefined>;
-}
-```
-
-Hooks can now **modify stream options** before each LLM call (per-turn patching).
-
-**pi-crew relevance:** Could enable per-task timeout/retries via hooks instead of process-level limits.
-
----
-
-## 10. Bug Fixes Affecting pi-crew
-
-### Tool Preflight Abort (`b9448276`)
-
-**Before:** When a run was aborted, sibling tool calls kept preparing in parallel.
-
-**After:** `signal?.aborted` check breaks the tool execution loop immediately.
-
-```typescript
-// agent-loop.ts
-if (signal?.aborted) {
-  break; // Stop preparing sibling tool calls
-}
-```
-
-**pi-crew relevance:** When pi-crew calls `cancel` on a running task, pi now correctly stops tool preflight immediately. Previously, pending tool calls could continue executing even after cancellation.
-
-### RPC Child Process Exit (`e007fcd0`)
-
-RPC now rejects pending requests when child process exits. Affects `child-pi.ts` communication.
-
----
-
-## 11. AgentHarness Key Source Files
-
-| File | Lines | Purpose |
-|------|-------|---------|
-| `harness/agent-harness.ts` | ~950 | Main orchestrator |
-| `harness/types.ts` | ~817 | All types, hooks, error codes |
-| `harness/session/session.ts` | 252 | Session abstraction |
-| `harness/session/jsonl-storage.ts` | 293 | JSONL persistence |
-| `harness/session/session-repo.ts` | 231 | Session CRUD |
-| `harness/skills.ts` | 375 | Skill loading + formatting |
-| `harness/prompt-templates.ts` | 267 | Prompt template processing |
-| `harness/compaction/compaction.ts` | 842 | Transcript compaction |
-| `harness/compaction/branch-summarization.ts` | 355 | Branch summarization |
-| `harness/env/nodejs.ts` | 370+ | Node.js execution environment |
-| `harness/execution-env.ts` | Abstract | FS + shell abstraction |
-
----
-
-## 12. Opportunities for pi-crew Enhancement
-
-> **Full plans:** [`docs/pi-mono-opportunities.md`](./pi-mono-opportunities.md)
-
-### High Priority
-
-**BM25 Semantic Reranking** — Fix `recommendTeam()` keyword failures by integrating existing BM25 search.
-
-### Medium Priority
-
-**Extended Hook Phases** — `before_turn`/`after_turn` hooks using existing `turn_end` tracking in `child-pi.ts`.
-
-**Hook Lifecycle Tests** — Cover untested hooks: `task_result`, `before_retry`, `before_publish`, `session_before_switch`, `run_recovery`.
-
-### Future (6+ months)
-
-**AgentHarness Migration** — When `AgentHarness` stabilizes (removes `Agent` dependency), pi-crew could replace `child-pi.ts` spawning with harness-based in-process execution. **Not a current concern.**
-
----
-
-## 13. Summary
-
-| Check | Result |
-|-------|--------|
-| Breaking API changes | **None** |
-| `Agent` class API | **Unchanged** — pi-crew compatible |
-| `AgentHarness` class | **New** — additive, not used by pi-crew |
-| New hooks | `context`, `resources_update`, `model_select`, `thinking_level_select` |
-| New lifecycle APIs | `prepareNextTurn`, `shouldStopAfterTurn`, `transformContext` |
-| New providers/features | Together AI, Xiaomi MiMo, Image generation, Codex websocket |
-| Bug fixes affecting pi-crew | Tool preflight abort, RPC child exit |
-| Migration path | AgentHarness (6+ months out, not urgent) |
-
-**Conclusion:** pi-crew is fully compatible with the latest pi source. The `AgentHarness` refactor is substantial but additive — it coexists with the legacy `Agent` class that pi-crew uses. Focus on pi-crew-specific enhancements. Monitor `AgentHarness` stabilization for future migration.

package/docs/archive/pi-subagent4-comparison.md

@@ -1,261 +0,0 @@
-# pi-subagent4 vs pi-crew: Comparative Analysis
-
-## Overview
-
-| Aspect | pi-subagent4 | pi-crew |
-|--------|--------------|---------|
-| **Size** | ~560 lines (single file) | ~50+ files, 10K+ lines |
-| **Architecture** | Single `subagent` tool | Full team orchestration system |
-| **Agent Model** | 3 built-in (scout, researcher, worker) | Configurable, extensible |
-| **Concurrency** | Semaphore (default 4) | DAG scheduler with phases |
-| **Context** | No inheritance (must be in task) | Full context preservation |
-
----
-
-## 1. Extension & Registration
-
-### pi-subagent4
-```typescript
-// Dynamic agent registration via globalThis bridge
-(globalThis as any).__pi_subagents = { registerAgent, unregisterAgent };
-
-export function registerAgent(config: AgentConfig): void {
-  agents.push(config);
-}
-```
-- **File-based**: Loads agents from `.md` files at startup
-- **Global bridge**: Uses `globalThis.__pi_subagents` for cross-module registration
-- **Frontmatter config**: YAML frontmatter in `.md` files define agents
-
-### pi-crew
-- **Manifest-based**: Teams/workflows defined in `.team.md`/`.workflow.md` files
-- **Skills system**: Extensible skill system for agents
-- **No dynamic registration API**: Static configuration
-
----
-
-## 2. Child Process Spawning
-
-### pi-subagent4
-```typescript
-const args = [
-  ...piBin.baseArgs,
-  "--mode", "json",
-  "-p",
-  "--no-session",
-  "--no-skills",
-  "--no-extensions",
-  "--tools", allowlist.join(","),
-  // ... custom tools, model, thinking level
-];
-
-const child = spawn(command, spawnArgs, { stdio: ["ignore", "pipe", "pipe"] });
-```
-- **JSON mode**: `--mode json` for structured output
-- **Heavy isolation**: `--no-session --no-skills --no-extensions`
-- **Tool allowlist**: `--tools` for fine-grained control
-- **PI_SUBAGENT_ALLOWED**: Env var restricts nested subagents
-
-### pi-crew
-```typescript
-const child = spawn(spawnSpec.command, spawnSpec.args, buildChildPiSpawnOptions(...));
-```
-- **Similar isolation**: Filters env vars, preserves essentials
-- **More complex args**: Based on task config
-- **No direct env restriction**: Uses runtime mode instead
-
----
-
-## 3. Concurrency Control
-
-### pi-subagent4
-```typescript
-class Semaphore {
-  constructor(private readonly max: number) {}
-
-  async run<T>(fn: () => Promise<T>): Promise<T> {
-    // Simple acquire/release pattern
-  }
-}
-
-const semaphore = new Semaphore(config.maxConcurrency ?? 4);
-```
-- **Per-parent semaphore**: Default 4, configurable via `config.json`
-- **Promise.all fan-out**: Parallel subagent calls in one turn
-
-### pi-crew
-```typescript
-// DAG scheduler with phase-based concurrency
-resolveBatchConcurrency({
-  workflowMaxConcurrency,
-  teamMaxConcurrency,
-  maxConcurrentWorkers,
-  workspaceMode,
-});
-
-// Tasks in same phase run concurrently
-```
-- **Phase-based**: Tasks grouped by workflow phase
-- **DAG dependency**: Respects task dependencies
-- **Configurable limits**: Per-workflow and per-team
-
----
-
-## 4. Input Handling
-
-### pi-subagent4
-```typescript
-// Long tasks written to temp file
-if (task.length > 8000) {
-  const tempFile = createTempFile(task);
-  args.push("@" + tempFile);
-} else {
-  args.push("--task", task);
-}
-```
-- **8K char threshold**: Uses temp file for large tasks
-- **Single task format**: `--task <text>` or `@<file>`
-
-### pi-crew
-```typescript
-// Prompt builder with system prompt, context, task
-const built = await buildPrompt({ task, role, goal, cwd, ... });
-// Args built from task configuration
-```
-- **Prompt builder**: Constructs full prompt with context
-- **File-based context**: Can read from workspace files
-
----
-
-## 5. Output Handling
-
-### pi-subagent4
-```typescript
-// JSON event stream on stdout
-child.stdout.on("data", (data) => {
-  const lines = data.toString().split("\n");
-  for (const line of lines) {
-    if (line.startsWith("{")) {
-      const event = JSON.parse(line);
-      // tool_execution_start/end, message_end
-    }
-  }
-});
-```
-- **JSON event stream**: Structured events from child process
-- **Event types**: `tool_execution_start`, `tool_execution_end`, `message_end`
-- **Streaming**: Real-time event processing
-
-### pi-crew
-```typescript
-// JSON output mode + structured response
-const output = await runChildPi({
-  onLifecycleEvent: (event) => { ... },
-  // ...
-});
-```
-- **Lifecycle events**: spawn, spawn_error, response_timeout, etc.
-- **Structured result**: `{ content, details, usage }`
-
----
-
-## 6. Safety Features
-
-### pi-subagent4
-```typescript
-// tools/safe-bash.ts
-const DANGEROUS_PATTERNS = [
-  /\brm\s+(-[a-zA-Z]*f[a-zA-Z]*\s+)?(-[a-zA-Z]*r[a-zA-Z]*\s+)?(\/|~\/?\s|~\/?\b)/,
-  /\bsudo\b/,
-  /\bmkfs\b/,
-  // ... 15+ patterns
-];
-```
-- **Regex blocklist**: 15+ dangerous command patterns
-- **Safe bash wrapper**: Wraps built-in bash tool
-
-### pi-crew
-- **Env var filtering**: Strips secrets before spawning
-- **No built-in safe bash**: Trust-based (user config required)
-- **Sandbox modes**: scaffold, child-process, live-session
-
----
-
-## 7. UI/Rendering
-
-### pi-subagent4
-```typescript
-// Throttled live rendering
-const updateThrottle = 150; // ms
-// Context window meter for depth >= 1 subagents
-// Tool preview extraction
-```
-- **150ms throttle**: Prevents UI thrashing
-- **Context gauge**: Shows token usage
-- **Tool preview**: Single-line argument preview
-
-### pi-crew
-- **Rich UI widget**: Live status, progress, model/token display
-- **Dashboard**: Full run dashboard
-- **Event bus**: Real-time updates
-
----
-
-## 8. Agent Hierarchy
-
-### pi-subagent4
-```
-worker (depth 2)
-  ├─ scout (depth 1)
-  └─ researcher (depth 1)
-```
-- **Depth-2 cap**: Worker can spawn scout/researcher
-- **PI_SUBAGENT_ALLOWED**: Enforces restriction
-
-### pi-crew
-- **No nested subagent**: Each task is independent
-- **Team roles**: explorer, planner, executor, etc.
-- **Phase-based**: Sequential phases with parallel within
-
----
-
-## Key Insights
-
-### What pi-subagent4 does better:
-1. **Simpler API**: Single tool, minimal config
-2. **Dynamic registration**: `registerAgent()` for runtime changes
-3. **JSON event stream**: Real-time structured events
-4. **Safe bash**: Built-in dangerous command blocking
-5. **Context gauge**: Token monitoring per turn
-
-### What pi-crew does better:
-1. **Complex workflows**: DAG scheduler, phases, dependencies
-2. **Durable state**: Manifest, events, artifacts persisted
-3. **Worktree isolation**: Safe parallel edits
-4. **Async runs**: Background execution with notifications
-5. **Rich UI**: Full dashboard and widget system
-6. **Multiple teams**: Built-in teams for different use cases
-
----
-
-## Potential Improvements for pi-crew
-
-1. **Dynamic agent registration API**
-   - Add `registerAgent(config)` similar to subagent4
-   - Allow runtime agent creation
-
-2. **Safe bash tool**
-   - Port dangerous pattern blocklist from subagent4
-   - Configurable via project config
-
-3. **JSON event stream parsing**
-   - Extract real-time tool events from child process
-   - Display tool progress in UI
-
-4. **Context window monitoring**
-   - Show token usage per task
-   - Alert when approaching limits
-
-5. **Simpler single-agent mode**
-   - Maybe a `subagent` tool for simple delegation?
-   - Current API is team/workflow based, could be heavy for simple cases