pi-crew 0.9.65 → 0.9.67

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "pi-crew",
-  "version": "0.9.65",
+  "version": "0.9.67",
   "description": "Pi extension for coordinated AI teams, workflows, worktrees, and async task orchestration",
   "author": "baphuongna",
   "license": "MIT",
@@ -67,22 +67,25 @@
   ],
   "scripts": {
     "check": "npm run ci",
-    "ci": "npm run typecheck && npm run lint && npm run format:check && npm run check:conflict-markers && npm run check:decision-drift && npm run check:lazy-imports && npm run check:bundle-staleness && npm run build:bundle && npm run check:bundle-size && npm run test:bundle && npm test && npm pack --dry-run",
+    "ci": "npm run typecheck && npm run lint && npm run format:check && npm run check:conflict-markers && npm run check:decision-drift && npm run check:event-types && npm run check:lazy-imports && npm run check:bundle-staleness && npm run build:bundle && npm run check:bundle-size && npm run test:bundle && npm test && npm pack --dry-run",
     "check:lazy-imports": "node scripts/check-lazy-imports.mjs",
     "check:bundle-staleness": "node scripts/check-bundle-staleness.mjs",
     "check:bundle-size": "node scripts/check-bundle-size.mjs",
     "check:conflict-markers": "node scripts/check-conflict-markers.mjs",
     "check:decision-drift": "node scripts/check-decision-drift.mjs",
+    "check:event-types": "node scripts/check-event-types-registry.mjs",
     "typecheck": "tsc --noEmit && node --experimental-strip-types -e \"await import('./index.ts'); console.log('strip-types import ok')\"",
     "lint": "biome check --linter-enabled=true --formatter-enabled=false --max-diagnostics=50 .",
     "format:check": "biome format .",
     "test": "npm run test:unit && npm run test:integration",
     "test:unit": "node scripts/test-runner.mjs --test-concurrency=4 --test-timeout=180000 --test-force-exit 'test/unit/**/*.test.ts'",
     "test:critical": "node scripts/test-runner.mjs --test-concurrency=4 --test-timeout=30000 --test-force-exit test/unit/runtime/broker/crew-broker-handshake.test.ts test/unit/runtime/broker/crew-broker-stale-socket.test.ts test/unit/runtime/broker/crew-broker-feature-flag.test.ts test/unit/runtime/broker/crew-broker-server-gate.test.ts test/unit/runtime/broker/crew-broker-client-fallback.test.ts test/unit/runtime/broker/crew-broker-mailbox-observer.test.ts test/unit/runtime/broker/crew-broker-close-during-reconnect.test.ts test/unit/runtime/broker/crew-broker-steer-dedup.test.ts test/unit/runtime/broker/crew-broker-symlink-steering.test.ts test/unit/ui/keybinding-map.parity.test.ts test/unit/ui/pi-tui-dispatch-probe.test.ts test/unit/utils/session-utils-extract.test.ts test/unit/config/config-schema-sync.test.ts test/unit/runtime/child-pi/child-pi-env-spread.test.ts",
-    "test:watch": "tsx --watch --test --test-concurrency=4 --test-timeout=30000 --test-force-exit 'test/unit/**/*.test.ts'",
+    "test:watch": "node scripts/test-runner.mjs --watch --test-concurrency=4 --test-timeout=30000 'test/unit/**/*.test.ts'",
     "test:integration": "node scripts/test-runner.mjs --test-concurrency=1 --test-timeout=300000 test/integration/*.test.ts",
     "test:smoke": "node scripts/test-runner.mjs --test-concurrency=1 --test-timeout=180000 test/smoke/*.smoke.ts",
     "test:spike": "node scripts/test-runner.mjs --test-concurrency=2 --test-timeout=120000 --test-force-exit test/runtime/scratchpad/*.test.ts",
+    "test:functional": "node scripts/test-runner.mjs --test-concurrency=1 --test-timeout=120000 test/functional/pi-crew-functional.test.ts",
+    "test:platform": "node scripts/test-runner.mjs --test-concurrency=1 --test-timeout=60000 test/platform/*.test.ts",
     "build:bundle": "node scripts/build-bundle.mjs",
     "test:bundle": "node --experimental-strip-types --test --test-force-exit test/unit/bundle-load.test.ts",
     "watch:bundle": "node scripts/watch-bundle.mjs",
@@ -93,7 +96,7 @@
     "build:crew-font": "python scripts/build-crew-vibes-font.py",
     "bench": "node scripts/run-bench.mjs",
     "bench:check": "node scripts/bench-check.mjs",
-    "test:new": "tsx --test --test-concurrency=4 --test-timeout=30000 --test-force-exit 'test/unit/**/*.test.ts'",
+    "test:new": "node scripts/test-runner.mjs --test-concurrency=4 --test-timeout=30000 'test/unit/**/*.test.ts'",
     "test:changed": "node scripts/test-changed.mjs",
     "bench:capture": "node scripts/run-bench.mjs && node -e \"require('node:fs').copyFileSync('test/bench/results.json','test/bench/baseline.json')\"",
     "profile:startup": "node scripts/profile-startup.mjs",

package/skills/real-test-pi-crew/SKILL.md

@@ -110,7 +110,7 @@ To add Tier 1 to CI as a fast-feedback gate (under 30s):
 
 ---
 
-## Tier 1 — Critical unit tests (~21s, 97 tests, the only suite you need for broker/UI changes)
+## Tier 1 — Critical unit tests (~25s, 101 tests, the only suite you need for broker/UI changes)
 
 **What**: run the curated 14-file fast subset.
 
@@ -122,7 +122,7 @@ To add Tier 1 to CI as a fast-feedback gate (under 30s):
 time npm run test:critical
 ```
 
-Expected output: `# tests 97 # pass 97 # fail 0 # duration_ms ~21000`.
+Expected output: `# tests 101 # pass 101 # fail 0 # duration_ms ~26000`. (Count was 97 at v0.9.46; 101 since the model-routing merge — verify with the actual run; the skill's hard-coded numbers drift between releases.)
 
 **References**:
 
@@ -162,7 +162,7 @@ PI_CREW_BROKER=0 npm run test:critical
 PI_CREW_BROKER=1 npm run test:critical
 ```
 
-All three must show `# pass 97 # fail 0`. Measured times in this session: ~20s for default and `PI_CREW_BROKER=0`, ~21s for `PI_CREW_BROKER=1` (varies ±1s run-to-run).
+All three must show `# pass 101 # fail 0`. Measured times in this session (2026-08-11): ~26s for default, ~26s for `PI_CREW_BROKER=0`, ~26s for `PI_CREW_BROKER=1` (varies ±1-2s run-to-run).
 
 **References**:
 
@@ -202,7 +202,7 @@ Compare the printed md5 against what the user's Pi session loaded. If they diffe
 | Bundle builder | `scripts/build-bundle.mjs` (esbuild-based, bundles `index.bundle.ts` → `dist/index.mjs`) |
 | Bundle resolution rule | `index.ts:5-22` (entrypoint docstring); also `scripts/build-bundle.mjs:14-20` (entrypoint preference); **symlink is live for source files but the bundled `dist/index.mjs` is loaded** |
 | Postinstall hook | `scripts/postinstall.mjs:43` — best-effort bundle rebuild; falls back to strip-types if esbuild missing |
-| Bundle md5 after Phase-4 commit | `1cc4d55e18add7b9a036c569143320b6` (~2.78 MB at the time; bundle size drifts ±5% between releases, check current `ls -la dist/index.mjs`) |
+| Bundle md5 after Phase-4 commit | `1cc4d55e18add7b9a036c569143320b6` (~2.78 MB at the time; **check current**: `md5sum dist/index.mjs`. As of v0.9.66 I-batch 2026-08-11: `16e29d053bd370e24f40df147dadcb79` ~2.81 MB) |
 
 ---
 
@@ -454,7 +454,7 @@ If the two md5s match → session is on the latest code. If not → user must `/
 
 **Real measured outcome** (this session, after the v0.9.57 schema fix): 9a (15 team actions) + 9b (4 subagent tools / 3 run paths) exercised; all green; the two silent-failure modes that motivated this tier (`Unknown type` from `Type.Unsafe` without Kind, and `Validation failed for tool team` from empty-string-strict schema) were caught ONLY by this battery — Tier 1-8 all passed while the team tool was broken live. The session also surfaced the unauthorized-agent-edit anti-pattern (a chain-run agent edited `chain-runner.ts` mid-smoke) — see Anti-patterns.
 
-**Not covered by the cheap battery above** — the actions below need extra setup, cost, or user confirmation. Run them only when the change touches their code path, and prefer a throwaway cwd / config so you don't mutate the user's real state. Organised by cost/safety:
+**Not covered by the cheap battery above** — the actions below need extra setup, cost, or user confirmation. Run them only when the change touches their code path, and prefer a throwaway cwd / config so you don't mutate the user's real state. Organised by cost/safety. **As of 2026-08-11 (extended battery, run report `real-test-2026-08-11-scratchpad-I-batch.md`), 9c/9e/9f have been exercised live once each — they are no longer unproven, but still require explicit scope+confirmation to re-run.**
 
 **9c. Lifecycle / recovery** (needs a *running* run — start an async run, then exercise these against its runId):
 - `team action='wait' runId='...'` — block until completion
@@ -508,9 +508,10 @@ If the two md5s match → session is on the latest code. If not → user must `/
 | `makeFakeCtx({ flagOn: false })` without `brokerEnv: "0"` | `makeFakeCtx` deletes `PI_CREW_BROKER` env if `brokerEnv` is undefined | `612e18b` (test fix) | `test/unit/crew-broker-server-gate.test.ts:78` — pass `brokerEnv: "0"` to preserve env |
 | Trust green CI on one OS | macOS/Windows regressions slip through | n/a (permanent) | `.crew/knowledge.md` — "CI runs 3 OSes ... A flake on one OS IS a real bug" |
 | Trusting a team-run agent not to edit the repo under test | Agents spawned by `team`/`Agent`/`crew_agent` inherit the session cwd and have `edit`/`write` tools — a proactive LLM (observed with deepseek) will make **unauthorized source edits** to pi-crew during a trivial smoke run (e.g. "improving" `chain-runner.ts` while parsing a chain string). The edit can be correct + green-tested yet still be unintended scope creep that silently lands in your commit. | n/a (permanent) | After EVERY team/subagent run: `git status` and verify each changed file was authored by you. Diff + review any surprise change before staging. Consider `workspaceMode: 'worktree'` for parallel/risky runs to isolate mutations. |
+| **Armed-role tool-surface bug (found live 2026-08-11)**: an opt-in tool (e.g. `scratchpad`) is armed via `ROLE_TOOL_CONFIGS[role].scratchpad=true` AND env `PI_CREW_SCRATCHPAD=1`, but NEVER appears in the worker surface. Root cause: `resolveToolPolicy` (`src/agents/agent-config.ts:165`) falls back `roleConfig.tools ?? agent.tools` when the role has no `tools` allowlist, and the builtin `agents/{executor,verifier,test-engineer}.md` frontmatter `tools:` did not list `scratchpad` → pi got `--tools read,grep,find,ls,bash,edit,write` and **hard-filtered** scratchpad. Env was correct; the tool was silently dropped by the `--tools` allowlist. Reproduce: `pi -p --tools read,grep,find,ls,bash,edit,write "list tools"` → no scratchpad; with scratchpad added → present. | `f753be30` | **Fix**: keep armed-role `agents/*.md` frontmatter `tools:` lists in sync with `ROLE_TOOL_CONFIGS` (QW17 pins the pinned roles; add the new tool to BOTH frontmatter AND role config for pinned roles, frontmatter-only for vacuous roles). A smoke run that claims the tool is "not available" in the worker is a REAL signal — verify the worker's actual `--tools` allowlist, not just env vars. |
 | `Type.Unsafe({ anyOf/type })` schema field **without** `[TypeBox.Kind]` symbol | `Value.Check` throws `Unknown type` the first time a model emits that field (e.g. `skill`, `config`) — every team action returns `isError:true` text `"Unknown type"`. Tier 1-8 stay green because unit tests never send the offending field. | v0.9.57 | `src/schema/team-tool-schema.ts` — `SkillOverride`/`FreeformConfig` switched from `Type.Unsafe` to TypeBox-native `Type.Union`/`Type.Record`. See Tier 9. |
 | Schema too strict for model-emitted empty strings (`runId:""`, `workspaceMode:""`, `budgetTotal:0`) | pi-ai `validateToolArguments` runs BEFORE the pi-crew handler and rejects `""` against Literal unions / patterns → `Validation failed for tool team` → model loops. | v0.9.57 | `src/schema/team-tool-schema.ts` — added `Literal("")` to unions, `^$|` pattern for runId, `""` to action enum, `0`/Boolean allowances. Handler-side `normalizeTeamParams` drops the empties. |
-| Claiming "all 9 tiers pass" while 9c–9f were never run | Overclaim — once reported "9 tiers pass" when only 9a (8/10) + 9b (4/5) had actually run; 9c–9f were skipped. Past runs then become unverifiable ("did it really pass 9 tiers?"). | n/a (process) | Fill `REPORT-TEMPLATE.md` per-tier DURING the run. "Tier 9 pass" = 9a AND 9b AND the applicable 9c–9f, each with evidence. Round-up-to-pass is the anti-pattern this row exists to prevent. |
+| Claiming "all 9 tiers pass" while 9c–9f were never run | Overclaim — once reported "9 tiers pass" when only 9a (8/10) + 9b (4/5) had actually run; 9c–9f were skipped. Past runs then become unverifiable ("did it really pass 9 tiers?"). **2026-08-11 repeat**: an initial report said "9c–9f skipped" yet the summary read as full coverage until the gap was called out. | n/a (process) | Fill `REPORT-TEMPLATE.md` per-tier DURING the run. "Tier 9 pass" = 9a AND 9b AND the applicable 9c–9f, each with evidence. Round-up-to-pass is the anti-pattern this row exists to prevent. If 9c–9f are skipped, SAY SO in the verdict and do not phrase it as "all pass". |
 | chain run with `workflow:"chain"` forwarded to steps | Every chain step fails in ~58ms with an EMPTY error string — looks like a parse failure but isn't. `chain-dispatch` forwards `params.workflow` ("chain") into executor overrides; each step then runs the "chain" workflow via the normal `executeTeamRun` path and fails fast + silently. | Open (issue #44) | Omit `workflow` when invoking `action:'run' chain=...` — chain then runs 2/2 success (~308s). See `docs/bugs/chain-workflow-forward-quirk.md`. |
 
 ---
@@ -648,7 +649,7 @@ The skill does NOT need to be updated for every commit — only when the cited l
 ## Quick reference — exact commands
 
 ```bash
-# Tier 1 (critical unit, ~21s, 97 tests)
+# Tier 1 (critical unit, ~25s, 101 tests)
 npm run test:critical
 # Tier 2 (3-path proof, broker changes only)
 PI_CREW_BROKER=0 npm run test:critical
@@ -687,14 +688,14 @@ md5sum "$(npm root -g)"/pi-crew/dist/index.mjs 2>/dev/null \
 
 Before claiming "tested":
 
-- [ ] Tier 1: `test:critical` fresh-run, all pass (<25s). Count varies by release — was 97 at v0.9.46, 101 after the model-routing merge; record the actual count in the report.
+- [ ] Tier 1: `test:critical` fresh-run, all pass (<25s). Count varies by release — was 97 at v0.9.46, **101 since the model-routing merge (v0.9.66)**; record the actual count in the report.
 - [ ] Tier 2: 3-path proof all pass — **required if you touched `src/config/defaults.ts` or `src/extension/registration/lifecycle-handlers.ts`**
 - [ ] Tier 3: `npm run typecheck` exit 0, `npm run build:bundle` exit 0
 - [ ] Tier 4: bundle md5 matches what the session loaded (or user has `/quit`-ed + reopened)
 - [ ] Tier 5/6: live TUI smoke for any `src/ui/` change — keystroke reached `handleInput`
 - [ ] Tier 7: smoke team run for any `src/runtime/plan-templates.ts` or `workflows/*.workflow.md` change — completed, no hang, verifier output under 60s
 - [ ] Tier 8: final md5 sync check passed
-- [ ] Tier 9: feature battery — **required if you touched `src/schema/team-tool-schema.ts`, `src/extension/registration/team-tool.ts`, or any `Type.Unsafe({...})` schema**. 9a read-only batch all return clean; one probe per 9b spawn path (sync / async / chain / `Agent` / `crew_agent`+`get_subagent_result`) completes with `consistency=1`. Run 9c–9f only when the change touches their code path; 9d (destructive) requires explicit user confirmation. **After every run: `git status` to catch unauthorized agent edits.**
+- [ ] Tier 9: feature battery — **required if you touched `src/schema/team-tool-schema.ts`, `src/extension/registration/team-tool.ts`, any `Type.Unsafe({...})` schema, or any armed-role tool list (`agents/*.md` / `src/config/role-tools.ts`)**. 9a read-only batch all return clean; one probe per 9b spawn path (sync / async / chain / `Agent` / `crew_agent`+`get_subagent_result`) completes with `consistency=1`. Run 9c–9f only when the change touches their code path; **at least one full 9c/9e/9f sweep per release is recommended so the battery stays proven** (see `real-test-2026-08-11-scratchpad-I-batch.md`); 9d (destructive) requires explicit user confirmation. **After every run: `git status` to catch unauthorized agent edits.**
 - [ ] **Output report**: save `docs/real-test/reports/real-test-<YYYY-MM-DD>-<slug>.md` from `skills/real-test-pi-crew/REPORT-TEMPLATE.md`, filled DURING the run with per-tier evidence (counts/md5/runId) — not reconstructed from memory afterward. This is what makes past runs verifiable instead of trust-the-summary.
 
 **"All 9 tiers pass" is a claim that needs per-row evidence.** Tier 9 means 9a **and** 9b **and** whichever of 9c–9f applies to the change — not "9a passed, therefore 9 passed". If any required item above is unchecked or lacks concrete evidence (a number, an md5, a runId), the answer to "is it tested?" is **no** — say so explicitly instead of rounding up to "pass".

package/src/config/config.ts

@@ -1249,12 +1249,20 @@ export function updateConfig(patch: PiTeamsConfig, options: UpdateConfigOptions
 			for (const unset of options.unsetPaths) unsetPath(raw, unset);
 			merged = parseConfig(raw);
 		}
+		// Skip-if-unchanged: an empty/identical patch must not rewrite the file
+		// (e.g. `team action='config'` with an empty patch — read-only path).
+		// Both sides are parseConfig-normalized, so JSON.stringify key order is
+		// deterministic (same construction path); no key sorting needed.
+		const normalizedCurrent = parseConfig(current);
+		if (JSON.stringify(merged) === JSON.stringify(normalizedCurrent)) {
+			return { path: filePath, config: merged, written: false }; // unchanged — skip write
+		}
 		fs.mkdirSync(path.dirname(filePath), { recursive: true });
 		atomicWriteFile(filePath, `${JSON.stringify(merged, null, 2)}\n`);
 		// (F16) Invalidate the loadConfig cache after a write — the next
 		// caller must see the new value, not a 0-2s stale snapshot.
 		invalidateConfigCache();
-		return { path: filePath, config: merged };
+		return { path: filePath, config: merged, written: true };
 	});
 }
 
@@ -1273,10 +1281,18 @@ export function updateAutonomousConfig(patch: PiTeamsAutonomousConfig): SavedPiT
 			current.autonomous && typeof current.autonomous === "object" && !Array.isArray(current.autonomous)
 				? (current.autonomous as Record<string, unknown>)
 				: {};
-		current.autonomous = { ...currentAutonomous, ...patch };
+		// Skip-if-unchanged (raw shape): a no-op autonomous patch must not
+		// rewrite the file. NOTE: compare the RAW on-disk record, NOT the
+		// parseConfig-normalized shape — normalizing would add default keys and
+		// false-positive the equality check.
+		const next = { ...current, autonomous: { ...currentAutonomous, ...patch } };
+		if (JSON.stringify(next) === JSON.stringify(current)) {
+			return { path: filePath, config: parseConfig(current), written: false }; // unchanged — skip write
+		}
+		current.autonomous = next.autonomous;
 		atomicWriteFile(filePath, `${JSON.stringify(current, null, 2)}\n`);
 		// (F16) Invalidate the loadConfig cache after a write — see updateConfig.
 		invalidateConfigCache();
-		return { path: filePath, config: parseConfig(current) };
+		return { path: filePath, config: parseConfig(current), written: true };
 	});
 }

package/src/config/role-tools.ts

@@ -84,7 +84,7 @@ export const ROLE_TOOL_CONFIGS: Record<string, RoleToolConfig> = {
 	// agents/verifier.md). Tool-set keeps bash but excludes edit/write so source
 	// integrity is preserved during verification. Mirrors cold-verifier behavior.
 	verifier: {
-		tools: ["read", "grep", "find", "ls", "bash"],
+		tools: ["read", "grep", "find", "ls", "bash", "scratchpad"],
 		excludeTools: ["edit", "write", "web"],
 		// Phase 1 scratchpad: multi-cell test/verify flows reuse parsed state.
 		scratchpad: true,
@@ -92,7 +92,7 @@ export const ROLE_TOOL_CONFIGS: Record<string, RoleToolConfig> = {
 
 	// Test Engineer - Can write tests (F1: hyphenated key)
 	"test-engineer": {
-		tools: ["read", "edit", "write", "bash", "ls"],
+		tools: ["read", "edit", "write", "bash", "ls", "scratchpad"],
 		excludeTools: ["web"],
 		// Phase 1 scratchpad: build/run test suites with state across cells.
 		scratchpad: true,

package/src/config/types.ts

@@ -312,6 +312,8 @@ export interface ConfigValidationResult {
 export interface SavedPiTeamsConfig {
 	config: PiTeamsConfig;
 	path: string;
+	/** Whether the file was actually rewritten. `false` when a no-op patch hit the skip-write guard. */
+	written: boolean;
 }
 
 export interface UpdateConfigOptions {

package/src/extension/knowledge-injection.ts

@@ -301,6 +301,7 @@ export function readKnowledge(cwd: string, query?: KnowledgeQuery): string {
 				content = `${content.slice(0, MAX_KNOWLEDGE_HEAD_BYTES)}\n\n<!-- knowledge.md truncated at ${MAX_KNOWLEDGE_HEAD_BYTES} bytes (head shown). Full file: ${p} — use the \`read\` tool if you need sections beyond the head. -->`;
 			}
 			knowledgeCache.set(p, { key: cacheKey, content });
+			enforceKnowledgeCacheCap(knowledgeCache);
 			return content;
 		}
 
@@ -325,6 +326,7 @@ export function readKnowledge(cwd: string, query?: KnowledgeQuery): string {
 				conventions: parsed.conventions,
 				sessionLog: parsed.sessionLog,
 			});
+			enforceKnowledgeCacheCap(sectionCache);
 		}
 
 		const queryText = [query.goal, query.taskText].filter(Boolean).join(" \n ");
@@ -382,6 +384,21 @@ interface CachedSections {
 }
 const sectionCache = new Map<string, CachedSections>();
 
+// H6 (2026-08-10): FIFO cap — mirrors the discover-* caches
+// (TEAM_DISCOVERY_MAX_ENTRIES = 32, WORKFLOW_DISCOVERY_MAX_ENTRIES = 32).
+// Without this, the caches grow with every distinct project root seen by the
+// process; each entry can be KB-scale (full knowledge.md content + parsed
+// sections). Eviction is safe: a cache miss falls through to a fresh
+// readFileSync + parse, same as the first call for that path.
+const KNOWLEDGE_CACHE_MAX_ENTRIES = 64;
+
+function enforceKnowledgeCacheCap(cache: Map<string, unknown>): void {
+	if (cache.size > KNOWLEDGE_CACHE_MAX_ENTRIES) {
+		const oldest = cache.keys().next().value;
+		if (oldest !== undefined) cache.delete(oldest);
+	}
+}
+
 /** Head cap for the no-query (legacy / main-session) path. */
 const MAX_KNOWLEDGE_HEAD_BYTES = 2_000;
 

package/src/extension/pi-api.ts

@@ -38,19 +38,3 @@ export type {
 } from "@earendil-works/pi-coding-agent";
 
 export { createBashTool, defineTool } from "@earendil-works/pi-coding-agent";
-
-/**
- * @deprecated Drift detector removed in Phase 5 follow-up to H1.
- *
- * History: this constant was meant to surface version-drift between
- * dev-time type-check and runtime peer-dep version. pi-crew declares
- * peer deps as `*` so the runtime version is set by whatever host pi
- * install the user has — pinning this constant to a specific devDep
- * range was a false invariant that did not reflect how extensions
- * actually consume peer packages.
- *
- * Kept exported (now `"0.0.0-unset"`) only for any downstream consumers
- * that may import it via re-exports. No diagnostic uses it anymore.
- * Will be removed in a future major version.
- */
-export const BUILT_AGAINST_PI_VERSION = "0.0.0-unset";

package/src/extension/team-tool/api/agent-control.ts

@@ -0,0 +1,358 @@
+/**
+ * Extracted `api` operation handlers — live-agent control group (H3 phase 2).
+ *
+ * Extracted from `src/extension/team-tool/api.ts` on 2026-08-10. Behaviour is
+ * byte-identical to the inline `if` blocks they replace.
+ */
+
+import { readCrewAgents } from "../../../runtime/crew-agent-records.ts";
+import { appendLiveAgentControlRequest } from "../../../runtime/live-session/live-agent-control.ts";
+import {
+	followUpLiveAgent,
+	getLiveAgent,
+	listActiveLiveAgents,
+	resumeLiveAgent,
+	steerLiveAgent,
+	stopLiveAgent,
+} from "../../../runtime/live-session/live-agent-manager.ts";
+import { liveControlRealtimeMessage, publishLiveControlRealtime } from "../../../runtime/live-session/live-control-realtime.ts";
+import {
+	appendFollowUpMessage,
+	appendFollowUpMessageAsync,
+	appendSteeringMessage,
+	appendSteeringMessageAsync,
+} from "../../../state/coordination/mailbox.ts";
+import { appendEvent } from "../../../state/event-log/event-log.ts";
+import type { ApiOperationHandler } from "./handler-context.ts";
+
+export const handleNudgeAgent: ApiOperationHandler = (hctx) => {
+	const { cfg, loaded, result, paramRequired, ctx } = hctx;
+	const agentId = typeof cfg.agentId === "string" ? cfg.agentId : undefined;
+	const agent = readCrewAgents(loaded.manifest).find((item) => item.id === agentId || item.taskId === agentId);
+	if (!agent)
+		return result(
+			paramRequired(
+				"API nudge-agent",
+				"config.agentId matching an agent id or task id",
+				"{ action: 'api', runId: 'team_...', config: { operation: 'nudge-agent', agentId: 'agent-1' } }",
+			),
+			{
+				action: "api",
+				status: "error",
+				runId: loaded.manifest.runId,
+			},
+			true,
+		);
+	const messageText =
+		typeof cfg.message === "string" && cfg.message.trim()
+			? cfg.message.trim()
+			: "Please report your current status, blocker, or smallest next step.";
+	const message = appendSteeringMessage(loaded.manifest, {
+		taskId: agent.taskId,
+		to: agent.taskId,
+		body: messageText,
+		priority: "normal",
+		data: { source: "nudge-agent" },
+	});
+	appendEvent(loaded.manifest.eventsPath, {
+		type: "agent.nudged",
+		runId: loaded.manifest.runId,
+		taskId: agent.taskId,
+		message: messageText,
+		data: { agentId: agent.id, mailboxMessageId: message.id },
+	});
+	ctx.events?.emit?.("crew.mailbox.message", {
+		runId: loaded.manifest.runId,
+		id: message.id,
+		direction: message.direction,
+		from: message.from,
+		to: message.to,
+		taskId: message.taskId,
+		source: "nudge-agent",
+	});
+	return result(JSON.stringify({ agentId: agent.id, mailboxMessage: message }, null, 2), {
+		action: "api",
+		status: "ok",
+		runId: loaded.manifest.runId,
+		artifactsRoot: loaded.manifest.artifactsRoot,
+	});
+};
+
+export const handleListLiveAgents: ApiOperationHandler = (hctx) => {
+	const { loaded, result } = hctx;
+	return result(
+		JSON.stringify(
+			listActiveLiveAgents().filter((agent) => agent.runId === loaded.manifest.runId),
+			null,
+			2,
+		),
+		{
+			action: "api",
+			status: "ok",
+			runId: loaded.manifest.runId,
+			artifactsRoot: loaded.manifest.artifactsRoot,
+		},
+	);
+};
+
+/**
+ * Handles steer-agent / follow-up-agent / stop-agent / resume-agent /
+ * interrupt-agent — the live-agent control cluster (shared body in the
+ * original handleApi; interrupt falls through to stop).
+ */
+export const handleLiveAgentControl: ApiOperationHandler = async (hctx) => {
+	const { cfg, loaded, result, paramRequired, ctx } = hctx;
+	const operation = typeof cfg.operation === "string" ? cfg.operation : "";
+	const agentId = typeof cfg.agentId === "string" ? cfg.agentId : undefined;
+	if (!agentId)
+		return result(
+			paramRequired(
+				`API ${operation}`,
+				"config.agentId",
+				`{ action: 'api', runId: 'team_...', config: { operation: '${operation}', agentId: 'agent-1' } }`,
+			),
+			{
+				action: "api",
+				status: "error",
+				runId: loaded.manifest.runId,
+			},
+			true,
+		);
+	const message = typeof cfg.message === "string" && cfg.message.trim() ? cfg.message.trim() : undefined;
+	const prompt = typeof cfg.prompt === "string" && cfg.prompt.trim() ? cfg.prompt.trim() : message;
+	try {
+		const live = getLiveAgent(agentId);
+		if (live && live.runId !== loaded.manifest.runId)
+			return result(
+				`Live agent '${agentId}' does not belong to run ${loaded.manifest.runId}.`,
+				{
+					action: "api",
+					status: "error",
+					runId: loaded.manifest.runId,
+				},
+				true,
+			);
+		if (live && live.workspaceId !== loaded.manifest.cwd)
+			return result(
+				`Live agent '${agentId}' does not belong to workspace ${loaded.manifest.cwd}.`,
+				{
+					action: "api",
+					status: "error",
+					runId: loaded.manifest.runId,
+				},
+				true,
+			);
+		if (!live && (operation === "steer-agent" || operation === "follow-up-agent"))
+			throw new Error(`Live agent '${agentId}' not found.`);
+		const liveTaskId = live?.taskId;
+		if ((operation === "steer-agent" || operation === "follow-up-agent") && !liveTaskId)
+			throw new Error(`Live agent '${agentId}' not found.`);
+		const targetTaskId = liveTaskId ?? agentId;
+		if (operation === "steer-agent") {
+			const text = message ?? "Please report current status and wrap up if possible.";
+			const realtime = await steerLiveAgent(agentId, text);
+			const mailboxMessage = await appendSteeringMessageAsync(loaded.manifest, {
+				taskId: targetTaskId,
+				body: text,
+				status: "delivered",
+				data: { source: "steer-agent", realtime: true },
+			});
+			return result(JSON.stringify({ realtime, mailboxMessage }, null, 2), {
+				action: "api",
+				status: "ok",
+				runId: loaded.manifest.runId,
+				artifactsRoot: loaded.manifest.artifactsRoot,
+			});
+		}
+		if (operation === "follow-up-agent") {
+			if (!prompt)
+				return result(
+					paramRequired(
+						"API follow-up-agent",
+						"config.prompt or config.message",
+						"{ action: 'api', runId: 'team_...', config: { operation: 'follow-up-agent', agentId: 'agent-1', prompt: '<next step>' } }",
+					),
+					{
+						action: "api",
+						status: "error",
+						runId: loaded.manifest.runId,
+					},
+					true,
+				);
+			const realtime = await followUpLiveAgent(agentId, prompt);
+			const mailboxMessage = await appendFollowUpMessageAsync(loaded.manifest, {
+				taskId: targetTaskId,
+				body: prompt,
+				status: "delivered",
+				data: { source: "follow-up-agent", realtime: true },
+			});
+			return result(JSON.stringify({ realtime, mailboxMessage }, null, 2), {
+				action: "api",
+				status: "ok",
+				runId: loaded.manifest.runId,
+				artifactsRoot: loaded.manifest.artifactsRoot,
+			});
+		}
+		if (operation === "resume-agent") {
+			if (!prompt)
+				return result(
+					paramRequired(
+						"API resume-agent",
+						"config.prompt or config.message",
+						"{ action: 'api', runId: 'team_...', config: { operation: 'resume-agent', agentId: 'agent-1', prompt: '<resume instruction>' } }",
+					),
+					{
+						action: "api",
+						status: "error",
+						runId: loaded.manifest.runId,
+					},
+					true,
+				);
+			return result(JSON.stringify(await resumeLiveAgent(agentId, prompt), null, 2), {
+				action: "api",
+				status: "ok",
+				runId: loaded.manifest.runId,
+				artifactsRoot: loaded.manifest.artifactsRoot,
+			});
+		}
+		return result(JSON.stringify(await stopLiveAgent(agentId), null, 2), {
+			action: "api",
+			status: "ok",
+			runId: loaded.manifest.runId,
+			artifactsRoot: loaded.manifest.artifactsRoot,
+		});
+	} catch (error) {
+		const agent = readCrewAgents(loaded.manifest).find((item) => item.id === agentId || item.taskId === agentId);
+		if (!agent) {
+			const err = error instanceof Error ? error.message : String(error);
+			return result(
+				err,
+				{
+					action: "api",
+					status: "error",
+					runId: loaded.manifest.runId,
+				},
+				true,
+			);
+		}
+		const task = loaded.tasks.find((item) => item.id === agent.taskId);
+		if (!task)
+			return result(
+				`API ${operation} agent '${agentId}' does not match a run task.`,
+				{
+					action: "api",
+					status: "error",
+					runId: loaded.manifest.runId,
+				},
+				true,
+			);
+		if (operation === "resume-agent" && !prompt)
+			return result(
+				paramRequired(
+					"API resume-agent",
+					"config.prompt or config.message",
+					"{ action: 'api', runId: 'team_...', config: { operation: 'resume-agent', agentId: 'agent-1', prompt: '<resume instruction>' } }",
+				),
+				{
+					action: "api",
+					status: "error",
+					runId: loaded.manifest.runId,
+				},
+				true,
+			);
+		if (operation === "follow-up-agent" && !prompt)
+			return result(
+				paramRequired(
+					"API follow-up-agent",
+					"config.prompt or config.message",
+					"{ action: 'api', runId: 'team_...', config: { operation: 'follow-up-agent', agentId: 'agent-1', prompt: '<next step>' } }",
+				),
+				{
+					action: "api",
+					status: "error",
+					runId: loaded.manifest.runId,
+				},
+				true,
+			);
+		try {
+			const request = appendLiveAgentControlRequest(loaded.manifest, {
+				taskId: task.id,
+				agentId: agent.id,
+				operation:
+					operation === "resume-agent"
+						? "resume"
+						: operation === "follow-up-agent"
+							? "follow-up"
+							: operation === "steer-agent"
+								? "steer"
+								: "stop",
+				message: operation === "resume-agent" || operation === "follow-up-agent" ? prompt : message,
+			});
+			const mailboxMessage =
+				operation === "steer-agent"
+					? appendSteeringMessage(loaded.manifest, {
+							taskId: task.id,
+							to: agent.id,
+							body: message ?? "Please report current status and wrap up if possible.",
+							status: "delivered",
+							data: {
+								source: "steer-agent",
+								liveControlRequestId: request.id,
+							},
+						})
+					: operation === "follow-up-agent" && prompt
+						? appendFollowUpMessage(loaded.manifest, {
+								taskId: task.id,
+								to: agent.id,
+								body: prompt,
+								status: "delivered",
+								data: {
+									source: "follow-up-agent",
+									liveControlRequestId: request.id,
+								},
+							})
+						: undefined;
+			publishLiveControlRealtime(request);
+			ctx.events?.emit?.("pi-crew:live-control", liveControlRealtimeMessage(request));
+			appendEvent(loaded.manifest.eventsPath, {
+				type: "agent.control.queued",
+				runId: loaded.manifest.runId,
+				taskId: agent.taskId,
+				message: `Queued ${request.operation} control request for live agent.`,
+				data: {
+					request,
+					mailboxMessageId: mailboxMessage?.id,
+					realtime: true,
+				},
+			});
+			return result(JSON.stringify({ queued: true, request, mailboxMessage }, null, 2), {
+				action: "api",
+				status: "ok",
+				runId: loaded.manifest.runId,
+				artifactsRoot: loaded.manifest.artifactsRoot,
+			});
+		} catch (queueError) {
+			const message = queueError instanceof Error ? queueError.message : String(queueError);
+			return result(
+				message,
+				{
+					action: "api",
+					status: "error",
+					runId: loaded.manifest.runId,
+				},
+				true,
+			);
+		}
+	}
+};
+
+/** Dispatcher map for the live-agent control group. Consumed by handleApi. */
+export const AGENT_CONTROL_OPERATIONS: Record<string, ApiOperationHandler> = {
+	"nudge-agent": handleNudgeAgent,
+	"list-live-agents": handleListLiveAgents,
+	"steer-agent": handleLiveAgentControl,
+	"follow-up-agent": handleLiveAgentControl,
+	"stop-agent": handleLiveAgentControl,
+	"resume-agent": handleLiveAgentControl,
+	"interrupt-agent": handleLiveAgentControl,
+};