pi-crew 0.11.1 → 0.11.4

package/docs/runtime-flow.md

@@ -1,148 +0,0 @@
-# pi-crew Runtime Flow
-
-This document is a compact map of the runtime paths used by `pi-crew`.
-
-## Main sequence
-
-```text
-User / model
-  │ calls team({ action: "run", ... }) or /team-run
-  ▼
-handleTeamTool()
-  │ validates schema and routes action
-  ▼
-handleRun()
-  ├─ discoverTeams/discoverWorkflows/discoverAgents
-  ├─ validateWorkflowForTeam
-  ├─ expandParallelResearchWorkflow when applicable
-  ├─ createRunManifest + tasks.json + goal artifact
-  ├─ if async=true ─────────────────────────────────────────────┐
-  │   spawnBackgroundTeamRun()                                  │
-  │     ├─ resolve jiti-register.mjs                            │
-  │     ├─ fail-fast if jiti missing                            │
-  │     ├─ node --import jiti-register.mjs background-runner.ts  │
-  │     └─ parent schedules early-exit guard                    │
-  │                                                            ▼
-  │   background-runner.ts
-  │     ├─ append async.started
-  │     ├─ write async.pid startup marker
-  │     ├─ rediscover team/workflow/agents
-  │     └─ executeTeamRun()
-  │
-  └─ if foreground/default
-      ├─ startForegroundRun schedules session-bound run, or
-      └─ executeTeamRun inline for scaffold/non-scheduled paths
-
-executeTeamRun()
-  ├─ write run.running
-  ├─ materialize queued/running agent records lazily
-  ├─ build task graph index
-  ├─ while queued tasks exist
-  │   ├─ taskGraphSnapshot
-  │   ├─ resolveBatchConcurrency
-  │   ├─ getReadyTasks
-  │   ├─ append task.progress batch event
-  │   ├─ mapConcurrent ready batch
-  │   │   └─ runTeamTask()
-  │   │       ├─ prepare workspace/worktree
-  │   │       ├─ build task packet
-  │   │       ├─ render prompt + dependency context
-  │   │       ├─ choose model candidates from Pi config
-  │   │       ├─ spawn child Pi process
-  │   │       ├─ ChildPiLineObserver parses stdout/stderr
-  │   │       ├─ append per-agent events/output
-  │   │       ├─ update agent progress/task state
-  │   │       ├─ parse final JSONL/session usage
-  │   │       └─ write result/log/transcript/metadata artifacts
-  │   ├─ merge task updates monotonically
-  │   ├─ optional adaptive plan injection
-  │   ├─ save tasks/agents/progress
-  │   └─ write batch artifact
-  ├─ policy closeout
-  └─ run.completed / run.failed / run.blocked / run.cancelled
-```
-
-## Action router
-
-| Action | Handler | Purpose |
-|---|---|---|
-| `run` | `team-tool/run.ts` | Create and execute a run, foreground or async. |
-| `status` | `team-tool.ts` | Show manifest/tasks/agents/events and mark stale async runs failed. |
-| `summary` | `session-summary.ts`/summary handler | Write/read run summary artifact. |
-| `events` | `team-tool.ts` | Tail durable run events. |
-| `artifacts` | `team-tool.ts` | List run artifacts. |
-| `resume` | `team-tool.ts` | Requeue failed/cancelled/skipped/running tasks. |
-| `cancel` | `team-tool.ts` | Mark queued/running tasks cancelled and request foreground interrupt. |
-| `forget` | `run-maintenance.ts` | Delete run state/artifacts with confirmation. |
-| `prune` | `run-maintenance.ts` | Remove old finished runs with confirmation. |
-| `export` | `run-export.ts` | Create portable run bundle. |
-| `import` / `imports` | `run-import.ts` / `import-index.ts` | Store/list imported bundles. |
-| `config` | `config.ts` + config action | Show/update user/project config. |
-| `doctor` | `team-tool/doctor.ts` | Platform/resource/runtime diagnostics. |
-| `validate` | `validate-resources.ts` | Validate agents/teams/workflows. |
-| `recommend` | `team-recommendation.ts` | Suggest team/workflow/action for a goal. |
-| management | `management.ts` | Create/update/delete/rename teams, agents, workflows. |
-| API | `team-tool/api.ts` | File-backed observability/control/mailbox API. |
-
-## Worker modes
-
-| Mode | Behavior |
-|---|---|
-| `child-process` | Default. Launches real child `pi` processes per task. |
-| `scaffold` | Explicit dry-run. No child Pi worker execution. |
-| `live-session` | Experimental/gated in-process/live agent path. |
-| `auto` | Resolves to child-process unless config/env requests otherwise. |
-
-## Important files
-
-```text
-src/extension/register.ts              Pi extension entry/wiring
-src/extension/team-tool/run.ts         run creation and foreground/async split
-src/runtime/background-runner.ts       detached async entrypoint
-src/runtime/async-runner.ts            background spawn command/options
-src/runtime/team-runner.ts             workflow/task graph scheduler
-src/runtime/task-runner.ts             single task execution
-src/runtime/child-pi.ts                child Pi process and output observer
-src/runtime/model-fallback.ts          configured model candidates/routing
-src/runtime/concurrency.ts             batch concurrency decisions
-src/runtime/process-status.ts          pid/liveness/stale detection
-src/state/state-store.ts               manifest/tasks persistence
-src/state/event-log.ts                 JSONL run events
-src/runtime/crew-agent-records.ts      aggregate + per-agent status files
-```
-
-## Environment variables
-
-| Env | Effect |
-|---|---|
-| `PI_CREW_EXECUTE_WORKERS=0` | Disable real workers, use scaffold behavior. |
-| `PI_TEAMS_EXECUTE_WORKERS=0` | Legacy alias for worker disable. |
-| `PI_CREW_ENABLE_EXPERIMENTAL_LIVE_SESSION=1` | Allow experimental live-session runtime. |
-| `PI_CREW_MOCK_LIVE_SESSION=success` | Test hook for live-session mock. |
-| `PI_TEAMS_MOCK_CHILD_PI` | Test hook for mocked child Pi execution. |
-| `PI_CREW_DEPTH`, `PI_CREW_MAX_DEPTH` | Canonical subagent recursion guard. |
-| `PI_TEAMS_DEPTH`, `PI_TEAMS_MAX_DEPTH` | Legacy recursion guard aliases. |
-| `PI_TEAMS_HOME` | Override user config/state home in tests. |
-| `PI_TEAMS_PI_BIN` | Override child `pi` executable. |
-| `PI_CODING_AGENT_DIR` | Override Pi settings/models directory for model discovery. |
-| `PI_CREW_ASYNC_EARLY_EXIT_GUARD=0` | Disable 3s background early-exit guard. |
-
-## State transition summary
-
-```text
-queued/planning/running  ── completed
-                         ├─ failed
-                         ├─ blocked
-                         └─ cancelled
-```
-
-Task states follow the same durable contract plus `skipped`. Terminal states are monotonic during parallel merge.
-
-## Observability tips
-
-- Use `/team-dashboard` for a UI overview.
-- Use `team status runId=...` for canonical state and stale async detection.
-- Read `background.log` for early import/spawn errors.
-- Read `events.jsonl` for event chronology.
-- Read `agents/{taskId}/status.json` for per-agent model/progress/tool status.
-- Read `artifacts/{runId}/transcripts/{taskId}.jsonl` for raw child Pi transcript.

package/src/ui/card-colors.ts

@@ -1,168 +0,0 @@
-/**
- * Color utilities for pi-crew UI — background tinting and ANSI parsing.
- *
- * Ported from pi-diff's mixBg() / autoDeriveBgFromTheme() technique:
- * derive subtle status-tinted backgrounds from the theme's foreground colors
- * so crew cards stay readable across light/dark themes without hardcoding RGB.
- *
- * mixBg(base, accent, intensity) does a LINEAR interpolation:
- *   result = base + (accent - base) * intensity
- *
- * Intensity tiers (per pi-diff research):
- *   10-12% — subtle gutter/hint
- *   15-18% — line background (visible but not loud)
- *   30-35% — word-level emphasis (prominent)
- */
-
-import { visibleWidth as visualWidth } from "../utils/visual.ts";
-import type { CrewTheme } from "./theme-adapter.ts";
-
-// ── ANSI parsing ────────────────────────────────────────────────────────
-
-interface Rgb {
-	r: number;
-	g: number;
-	b: number;
-}
-
-const ANSI_RGB_FG_RE = /^\x1b?\[?38;2;(\d+);(\d+);(\d+)m?$/;
-const ANSI_RGB_BG_RE = /^\x1b?\[?48;2;(\d+);(\d+);(\d+)m?$/;
-
-/** Parse a truecolor ANSI SGR sequence (e.g. "\x1b[38;2;255;100;50m") to RGB. */
-export function parseAnsiRgb(ansi: string | undefined | null): Rgb | null {
-	if (!ansi) return null;
-	const stripped = ansi.replace(/^\x1b?\[?/, "").replace(/m?$/, "");
-	const fgMatch = stripped.match(/^38;2;(\d+);(\d+);(\d+)$/);
-	const bgMatch = stripped.match(/^48;2;(\d+);(\d+);(\d+)$/);
-	const m = fgMatch ?? bgMatch;
-	if (!m) return null;
-	const r = Number(m[1]);
-	const g = Number(m[2]);
-	const b = Number(m[3]);
-	if (![r, g, b].every(Number.isFinite)) return null;
-	return { r, g, b };
-}
-
-// ── Color mixing ────────────────────────────────────────────────────────
-
-/** Linear-interpolate two RGB colors and emit a 48;2 (truecolor bg) SGR code. */
-export function mixBg(base: Rgb, accent: Rgb, intensity: number): string {
-	const r = Math.round(base.r + (accent.r - base.r) * intensity);
-	const g = Math.round(base.g + (accent.g - base.g) * intensity);
-	const b = Math.round(base.b + (accent.b - base.b) * intensity);
-	return `\x1b[48;2;${r};${g};${b}m`;
-}
-
-const BLACK: Rgb = { r: 0, g: 0, b: 0 };
-
-/**
- * The background slots Pi's Theme actually exposes (`ThemeBg` in
- * node_modules/@earendil-works/pi-coding-agent/dist/modes/interactive/theme/theme.d.ts).
- *
- * P1-6 (2026-09-15): this probe used to pass "background", which is NOT a
- * ThemeBg member. Pi's `getBgAnsi` throws `Unknown theme background color:
- * background` for it, the surrounding catch swallowed the throw, and `base`
- * stayed BLACK on every theme — so crew card tints were derived from the wrong
- * base (visibly wrong on light themes). Never pass a slot outside this union.
- * `selectedBg` is the slot whose value is the surrounding card/selection
- * background; it is the one both Pi's `ThemeBg` and pi-crew's `CrewThemeBg`
- * (theme-adapter.ts) define. Enforced by
- * test/unit/round23-ui-unicode.test.ts (a fake theme records every slot).
- */
-type ThemeBgSlot =
-	| "selectedBg"
-	| "scrollbarThumb"
-	| "userMessageBg"
-	| "customMessageBg"
-	| "toolPendingBg"
-	| "toolSuccessBg"
-	| "toolErrorBg";
-
-/** Duck-typed view of Pi's Theme methods (CrewTheme does not declare them). */
-type ThemeProbe = {
-	getBgAnsi?: (slot: ThemeBgSlot) => string | undefined;
-	getFgAnsi?: (slot: string) => string | undefined;
-};
-
-// ── Theme → background derivation ───────────────────────────────────────
-
-/**
- * Resolve a subtle status-tinted background for a crew card interior.
- *
- * Reads the theme's fg color for the given status slot (success/error/border),
- * mixes it into a dark base at low intensity (default 8%), and returns a bg SGR
- * sequence. Returns "" if the theme exposes no fg ANSI (graceful — caller
- * renders without background).
- *
- * @param theme       pi-crew theme adapter
- * @param statusSlot  which status color to tint with ("success" | "error" | "borderAccent" | "border")
- * @param intensity   0-1, how strong the tint is (default 0.08 = very subtle)
- */
-export function deriveCardBackground(
-	theme: CrewTheme,
-	statusSlot: "success" | "error" | "borderAccent" | "border",
-	intensity = 0.08,
-): string {
-	// Prefer the theme's bg color as base (matches the card's surroundings).
-	let base = BLACK;
-	const themeAny = theme as unknown as ThemeProbe;
-	if (themeAny.getBgAnsi) {
-		try {
-			// "selectedBg" is a valid ThemeBg slot (P1-6). The catch only guards
-			// third-party theme shims that throw on the probe; it can no longer
-			// hide a permanently-invalid slot, because the slot type and the
-			// regression test both pin it to the ThemeBg union.
-			const parsed = parseAnsiRgb(themeAny.getBgAnsi("selectedBg"));
-			if (parsed) base = parsed;
-		} catch {
-			/* shim threw — fall back to black */
-		}
-	}
-
-	// Get the accent from the theme's fg for the requested slot.
-	let accentRgb: Rgb | null = null;
-	if (themeAny.getFgAnsi) {
-		try {
-			accentRgb = parseAnsiRgb(themeAny.getFgAnsi(statusSlot));
-		} catch {
-			/* accent stays null */
-		}
-	}
-	if (!accentRgb) return ""; // can't derive — render without bg tint
-
-	return mixBg(base, accentRgb, intensity);
-}
-
-// ── Helpers for padding lines with a background ─────────────────────────
-
-const RESET = "\x1b[0m";
-
-/** Strip ANSI SGR codes then compute the VISUAL width (Unicode-aware).
- * Round 23 (BUG 2): previously this used `.length` (UTF-16 code units), which
- * under-counts CJK/emoji → wrong padding → broken frame borders in crew cards.
- * Delegate to the canonical Unicode-aware visualWidth from utils/visual.ts
- * used by every other renderer. */
-export function visibleWidth(text: string): number {
-	return visualWidth(text);
-}
-
-/**
- * Pad a line to `targetWidth` and apply `bgAnsi` as the background for the
- * full visible width (including any trailing padding spaces).
- *
- * `bgAnsi` should be a 48;2 (truecolor bg) SGR sequence from mixBg().
- * The function inserts the bg code after any existing leading SGR, fills the
- * content, pads to width, then resets. This ensures the entire row's background
- * is tinted — not just the characters.
- */
-export function padWithBackground(line: string, targetWidth: number, bgAnsi: string): string {
-	if (!bgAnsi) {
-		// No background — just space-pad (preserving any existing styling).
-		const width = visibleWidth(line);
-		return width >= targetWidth ? line : line + " ".repeat(targetWidth - width);
-	}
-	const width = visibleWidth(line);
-	const pad = width >= targetWidth ? "" : " ".repeat(targetWidth - width);
-	// Re-apply bg after a leading reset if present, otherwise prepend.
-	return `${bgAnsi}${line}${pad}${RESET}`;
-}

package/src/utils/completion-dedupe.ts

@@ -1,63 +0,0 @@
-interface CompletionDataLike {
-	id?: unknown;
-	agent?: unknown;
-	timestamp?: unknown;
-	sessionId?: unknown;
-	taskIndex?: unknown;
-	totalTasks?: unknown;
-	success?: unknown;
-}
-
-function asNonEmptyString(value: unknown): string | undefined {
-	if (typeof value !== "string") return undefined;
-	const trimmed = value.trim();
-	return trimmed.length > 0 ? trimmed : undefined;
-}
-
-function asFiniteNumber(value: unknown): number | undefined {
-	if (typeof value !== "number") return undefined;
-	return Number.isFinite(value) ? value : undefined;
-}
-
-export function buildCompletionKey(data: CompletionDataLike, fallback: string): string {
-	const id = asNonEmptyString(data.id);
-	if (id) return `id:${id}`;
-	const sessionId = asNonEmptyString(data.sessionId) ?? "no-session";
-	const agent = asNonEmptyString(data.agent) ?? "unknown";
-	const timestamp = asFiniteNumber(data.timestamp);
-	const taskIndex = asFiniteNumber(data.taskIndex);
-	const totalTasks = asFiniteNumber(data.totalTasks);
-	const success = typeof data.success === "boolean" ? (data.success ? "1" : "0") : "?";
-	return [
-		"meta",
-		sessionId,
-		agent,
-		timestamp !== undefined ? String(timestamp) : "no-ts",
-		taskIndex !== undefined ? String(taskIndex) : "-",
-		totalTasks !== undefined ? String(totalTasks) : "-",
-		success,
-		fallback,
-	].join(":");
-}
-
-export function pruneSeenMap(seen: Map<string, number>, now: number, ttlMs: number): void {
-	for (const [key, ts] of seen.entries()) {
-		if (now - ts > ttlMs) seen.delete(key);
-	}
-}
-
-export function markSeenWithTtl(seen: Map<string, number>, key: string, now: number, ttlMs: number): boolean {
-	pruneSeenMap(seen, now, ttlMs);
-	if (seen.has(key)) return true;
-	seen.set(key, now);
-	return false;
-}
-
-export function getGlobalSeenMap(storeKey: string): Map<string, number> {
-	const globalStore = globalThis as Record<string, unknown>;
-	const existing = globalStore[storeKey];
-	if (existing instanceof Map) return existing as Map<string, number>;
-	const map = new Map<string, number>();
-	globalStore[storeKey] = map;
-	return map;
-}

package/src/utils/resolve-shell.ts

@@ -1,36 +0,0 @@
-import * as fs from "node:fs";
-
-/**
- * Resolve the bash executable path, with Windows fallbacks for Git Bash.
- */
-export function resolveBashCmd(): string {
-	if (process.platform !== "win32") return "bash";
-	const candidates = [process.env.SHELL, "C:\\Program Files\\Git\\bin\\bash.exe", "C:\\Program Files (x86)\\Git\\bin\\bash.exe"];
-	for (const cand of candidates) {
-		if (cand && fs.existsSync(cand)) return cand;
-	}
-	return "bash";
-}
-
-/**
- * Choose the right shell command and arguments for a script path.
- * On Windows, powershell (.ps1) and batch (.cmd/.bat) run natively.
- */
-export function resolveShellForScript(scriptPath: string): {
-	command: string;
-	args: string[];
-} {
-	if (process.platform === "win32") {
-		if (scriptPath.endsWith(".ps1")) {
-			return { command: "powershell", args: ["-File", scriptPath] };
-		}
-		if (scriptPath.endsWith(".cmd") || scriptPath.endsWith(".bat")) {
-			// Node >= 20 blocks direct spawn of .bat/.cmd without shell (CVE-2024-27980)
-			return {
-				command: process.env.ComSpec ?? "cmd.exe",
-				args: ["/d", "/s", "/c", scriptPath],
-			};
-		}
-	}
-	return { command: resolveBashCmd(), args: [scriptPath] };
-}