pi-crew 0.9.51 → 0.9.53

package/docs/actions-reference.md

@@ -8,24 +8,37 @@ The `team` tool is the primary tool that pi-crew registers with Pi. All operatio
 |--------|---------|-------------|
 | `recommend` | Suggest a suitable team/workflow | Starting point when unsure what to pick |
 | `run` | Create a run and execute a workflow | Main operation |
+| `parallel` | Fan out independent tasks as concurrent runs | When you need N truly concurrent agents |
 | `plan` | Preview a workflow without running tasks | Dry-run planning |
 | `orchestrate` | Execute from a plan document | Automate a plan |
 | `schedule` | Schedule recurring runs | Periodic automation |
 | `scheduled` | List scheduled jobs | View schedules |
+| `anchor` | Cross-run session anchoring | Persist context across runs |
+| `auto-summarize` | Control auto-summarization of long runs | Manage context summarization |
+| `auto_boomerang` | Toggle auto-summarize (shorthand) | Quick on/off |
 | `status` | Read run status | Track progress |
 | `summary` | Read/write run summary artifact | Summarize |
 | `cancel` | Cancel queued/running work | Stop a run |
 | `resume` | Re-queue failed/cancelled tasks | Resume a run |
+| `retry` | Retry specific failed/cancelled task(s) | Retry a task without full resume |
+| `wait` | Block until a run finishes (with timeout) | Synchronous wait |
+| `steer` | Queue an interrupting message to an active task | Redirect in-flight work |
+| `respond` | Reply to a waiting task and re-queue it | Interactive task Q&A |
 | `list` | List teams, agents, workflows, runs | Explore resources |
 | `get` | Inspect agent/team/workflow | View details |
+| `onboard` | Show team onboarding guide | Learn a team's roles/flow |
 | `search` | BM25-ranked agent/team discovery | Smart search |
 | `events` | Read the event log | Debug/audit |
 | `artifacts` | List run artifacts | View outputs |
 | `worktrees` | List run worktree metadata | Inspect worktrees |
 | `graph` | Load/save/list run graphs | Visualization |
+| `explain` | Explain a run or task structure | Understand a run |
+| `cache` | Run/skill cache stats or cached-run lookup | Inspect caches |
+| `checkpoint` | Read a task's saved checkpoint | Inspect task progress |
 | `cleanup` | Delete run worktrees | Cleanup |
 | `forget` | Delete run state/artifacts | Remove entirely (requires `confirm`) |
 | `prune` | Delete multiple old finished runs | Bulk cleanup |
+| `invalidate` | Drop a run's snapshot cache | Force fresh reads |
 | `export` | Export a portable run bundle | Share/backup |
 | `import` | Import a run bundle | Receive a run from elsewhere |
 | `imports` | List imported bundles | View imports |
@@ -34,7 +47,9 @@ The `team` tool is the primary tool that pi-crew registers with Pi. All operatio
 | `delete` | Delete an agent/team/workflow | Remove resources (requires `confirm`) |
 | `validate` | Validate resources | Health check |
 | `doctor` | Check readiness | Diagnose environment |
-| `config` | Show/update config | Configuration |
+| `health` | Watchdog health monitor across all runs | Diagnose stuck/zombie runs |
+| `config` | Show/update config (raw JSON) | Configuration |
+| `settings` | View/set config via dotted-path keys | Human-readable settings |
 | `init` | Initialize project layout | Initial setup |
 | `autonomy` | Manage delegation settings | Adjust automation |
 | `api` | Safe interop for state operations | Advanced integration |
@@ -686,3 +701,418 @@ Copy builtins:
 ```
 
 Profiles: `manual`, `suggested`, `assisted`, `aggressive`.
+
+---
+
+## Additional Actions (Run domain)
+
+### `parallel` — Fan out independent tasks
+
+Spawns an array of independent tasks as concurrent background agents. Use this when you need N truly concurrent workers in a single call (e.g. parallel research or review). Max concurrency is 8.
+
+```json
+{
+  "action": "parallel",
+  "config": {
+    "tasks": [
+      { "goal": "Audit auth module for CVEs", "agent": "explorer" },
+      { "goal": "Audit payment module for CVEs", "agent": "explorer" }
+    ],
+    "concurrency": 4,
+    "team": "fast-fix"
+  }
+}
+```
+
+Params:
+
+| Param | Type | Default | Notes |
+|-------|------|---------|-------|
+| `config.tasks` | `Array<{ goal, agent? }>` | — | **Required.** Each entry becomes a concurrent run. |
+| `config.concurrency` | `number` | `4` | Clamped to `1..8`. |
+| `config.team` | `string` | `fast-fix` | Team whose workflow is used for each task. |
+
+Each task launches its own run; the host agent does not need to emit one
+`Agent()` call per turn.
+
+---
+
+### `retry` — Retry specific failed task(s)
+
+Re-queues `failed` / `cancelled` tasks so the scheduler picks them up again.
+Unlike `resume` (which re-queues *all* non-terminal tasks), `retry` can target a
+single task via `taskId`. Runs the `before_retry` hook before mutating state.
+
+```json
+{
+  "action": "retry",
+  "runId": "team_..."
+}
+```
+
+Retry a single task:
+
+```json
+{
+  "action": "retry",
+  "runId": "team_...",
+  "taskId": "03_execute"
+}
+```
+
+Params:
+
+| Param | Type | Default | Notes |
+|-------|------|---------|-------|
+| `runId` | `string` | — | **Required.** |
+| `taskId` | `string` | — | Retry only this task; omit to retry all failed/cancelled. |
+| `force` | `boolean` | `false` | Override cross-session ownership check. |
+
+---
+
+### `wait` — Block until a run finishes
+
+Synchronously waits (polling) until the run reaches a terminal status, then
+returns the result. Useful when a foreground caller must block on an async run.
+
+```json
+{
+  "action": "wait",
+  "runId": "team_...",
+  "config": { "timeoutMs": 300000, "pollIntervalMs": 2000 }
+}
+```
+
+Params:
+
+| Param | Type | Default | Notes |
+|-------|------|---------|-------|
+| `runId` | `string` | — | **Required.** |
+| `config.timeoutMs` | `number` | `300000` | Clamped to `1000..3_600_000` (1 s – 1 h). |
+| `config.pollIntervalMs` | `number` | `2000` | Clamped to `500..60_000`. |
+
+Returns `status: "error"` when the run finished as `failed`.
+
+---
+
+### `steer` — Interrupt an active task
+
+> ⚠️ **Internal / experimental.** Queues a steering message that is delivered to
+> a task's worker session on its next turn. The message is appended to
+> `pendingSteers` and also written to a live steering file for immediate delivery.
+
+```json
+{
+  "action": "steer",
+  "runId": "team_...",
+  "taskId": "01_explore",
+  "message": "Focus only on src/ — ignore docs/"
+}
+```
+
+Params:
+
+| Param | Type | Default | Notes |
+|-------|------|---------|-------|
+| `runId` | `string` | — | **Required.** |
+| `taskId` | `string` | — | **Required.** Must be a non-terminal task. |
+| `message` | `string` | — | **Required.** The steering instruction. |
+
+The pending-steers queue is capped at 100 entries (oldest dropped with an
+audit event). Terminal tasks cannot be steered.
+
+---
+
+## Additional Actions (Control domain)
+
+### `respond` — Reply to a waiting task
+
+Sends a message to a task in `waiting` status and re-queues it for the durable
+scheduler. Used for interactive task Q&A (e.g. a worker that paused to ask a
+clarifying question).
+
+```json
+{
+  "action": "respond",
+  "runId": "team_...",
+  "taskId": "05_verify",
+  "message": "Yes, use the Postgres dialect."
+}
+```
+
+Params:
+
+| Param | Type | Default | Notes |
+|-------|------|---------|-------|
+| `runId` | `string` | — | **Required.** |
+| `taskId` | `string` | — | Target a specific waiting task; omit to respond to all waiting. |
+| `message` | `string` | — | The reply body. |
+| `force` | `boolean` | `false` | Override cross-session ownership check. |
+
+If no tasks are `waiting`, the response hints at `api operation=follow-up-agent`
+(continuation) or `api operation=steer-agent` (interrupt).
+
+---
+
+### `invalidate` — Drop a run's snapshot cache
+
+> ⚠️ **Internal / experimental.** Discards the cached run snapshot for a run so
+> subsequent reads rebuild it from disk. Use after external state mutations that
+> bypass the normal write path.
+
+```json
+{
+  "action": "invalidate",
+  "runId": "team_..."
+}
+```
+
+Params:
+
+| Param | Type | Default | Notes |
+|-------|------|---------|-------|
+| `runId` | `string` | — | **Required.** |
+
+Requires the in-process snapshot cache (only available within a live Pi
+session that has the cache wired up).
+
+---
+
+## Additional Actions (Status domain)
+
+### `onboard` — Team onboarding guide
+
+Prints a human-readable guide describing a team's roles, workflow, and expected
+flow — helpful when adopting a new team.
+
+```json
+{ "action": "onboard", "team": "implementation" }
+```
+
+Params:
+
+| Param | Type | Default | Notes |
+|-------|------|---------|-------|
+| `team` | `string` | `default` | The team to onboard. |
+
+---
+
+### `explain` — Explain a run or task
+
+Produces a structured explanation of a run (status, duration, task table) or,
+when `taskId` is given, a single-task breakdown (role, layer, why it exists,
+files touched, connected tasks, complexity).
+
+```json
+{ "action": "explain", "runId": "team_..." }
+```
+
+Explain one task:
+
+```json
+{ "action": "explain", "runId": "team_...", "taskId": "02_plan" }
+```
+
+Params:
+
+| Param | Type | Default | Notes |
+|-------|------|---------|-------|
+| `runId` | `string` | — | **Required.** |
+| `taskId` | `string` | — | Omit to explain the whole run. |
+
+---
+
+### `cache` — Cache stats or cached-run lookup
+
+> ⚠️ **Internal / experimental.** With a `goal`, looks up a previously cached run
+> by goal/team/workflow hash. Without a `goal`, reports run-cache and skill-cache
+> statistics (entries, size, hit rate, evictions).
+
+```json
+{ "action": "cache" }
+```
+
+Lookup a cached run:
+
+```json
+{
+  "action": "cache",
+  "goal": "Investigate failing tests",
+  "team": "default",
+  "workflow": "default"
+}
+```
+
+Params:
+
+| Param | Type | Default | Notes |
+|-------|------|---------|-------|
+| `goal` | `string` | — | Omit to show cache stats; provide to look up a cached run. |
+| `team` | `string` | `default` | Used in the cache key when `goal` is set. |
+| `workflow` | `string` | `default` | Used in the cache key when `goal` is set. |
+
+---
+
+### `checkpoint` — Read a task's saved checkpoint
+
+Loads a previously saved checkpoint for a task (step, progress, saved-at
+timestamp). Checkpoints are written during long-running tasks for resume
+support.
+
+```json
+{
+  "action": "checkpoint",
+  "runId": "team_...",
+  "taskId": "07_build"
+}
+```
+
+Params:
+
+| Param | Type | Default | Notes |
+|-------|------|---------|-------|
+| `runId` | `string` | — | **Required.** |
+| `taskId` | `string` | — | **Required.** |
+
+---
+
+### `health` — Watchdog health monitor
+
+> ⚠️ **Internal / experimental.** Scans all known runs and classifies them by
+> status, surfacing stuck tasks (heartbeat stale > 5 min), zombie workspaces,
+> ghost processes, orphaned temp dirs, and corrupted state. Returns a counts
+> summary (`total`, `running`, `completed`, `failed`, `blocked`, `queued`,
+> `planning`, `waiting`, `stuck`, `zombie`, `ghost`, `orphaned`, `corrupted`).
+
+```json
+{ "action": "health" }
+```
+
+No parameters. This is an auto-monitored watchdog diagnostic — prefer `doctor`
+for environment readiness checks.
+
+---
+
+## Additional Actions (Manage domain)
+
+### `settings` — View/set config via dotted-path keys
+
+A richer, human-readable interface to configuration. Unlike `config` (which
+returns the raw merged JSON), `settings` supports dotted-path `get`/`set`/`unset`,
+a flattened effective-settings listing, a schema reference, config-path
+display, and live Pi-UI theme switching.
+
+```json
+{ "action": "settings", "config": { "args": "list" } }
+```
+
+Set a value:
+
+```json
+{
+  "action": "settings",
+  "config": { "args": "set runtime.mode scaffold", "scope": "project" }
+}
+```
+
+Commands (passed via `config.args`):
+
+| Command | Description |
+|---------|-------------|
+| `list` | Show all effective config values (default). |
+| `json` | Dump full effective config as JSON. |
+| `schema` | List all known config keys (✓ = currently set). |
+| `paths` | Show user + project config file paths. |
+| `get <key>` | Get a specific dotted-path value. |
+| `set <key> <value>` | Set a value (JSON-parsed; scope via `config.scope`). |
+| `unset <key>` | Remove a value. |
+| `scope [user\|project]` | Show/change the write scope for `set`/`unset`. |
+| `themes` | Browse the Pi UI theme gallery. |
+| `theme <name>` | Switch the Pi UI theme (applied live). |
+
+> **`settings` vs `config`:** `config` returns/updates the merged JSON object
+> directly. `settings` is the dotted-path UI with schema hints, theme
+> management, and fuzzy key suggestions — use it for interactive exploration.
+
+---
+
+## Additional Actions (Automate domain)
+
+### `anchor` — Cross-run session anchoring
+
+Persists a named context anchor for the current session so it survives across
+runs and compactions. Sub-actions are selected via `config.subAction`.
+
+```json
+{ "action": "anchor", "config": { "subAction": "status" } }
+```
+
+Set an anchor:
+
+```json
+{
+  "action": "anchor",
+  "config": { "subAction": "set", "context": { "refactor": "auth-split" } }
+}
+```
+
+Sub-actions:
+
+| `subAction` | Description |
+|-------------|-------------|
+| `status` (default) | Show current anchors for the session. |
+| `set` | Create an anchor (accepts `config.context` object or `config.key`). |
+| `clear` | Remove an anchor (by `config.anchorId`, or all if omitted). |
+| `accumulate` | Append to an existing anchor's context. |
+
+---
+
+### `auto-summarize` — Auto-summarization control
+
+Controls automatic context summarization for long-running sessions. When
+enabled, the worker's context is summarized once the token count or tool-use
+count crosses a threshold. Sub-actions via `config.subAction`.
+
+```json
+{ "action": "auto-summarize", "config": { "subAction": "status" } }
+```
+
+Enable and configure:
+
+```json
+{
+  "action": "auto-summarize",
+  "config": {
+    "subAction": "on",
+    "threshold": 8000,
+    "minToolsUsed": 10,
+    "collapseContext": true
+  }
+}
+```
+
+Sub-actions:
+
+| `subAction` | Description |
+|-------------|-------------|
+| `status` (default) | Show current config + trigger thresholds. |
+| `on` | Enable summarization. |
+| `off` | Disable summarization. |
+| `config` | Update thresholds (`threshold`, `minToolsUsed`, `collapseContext`). |
+| `toggle` | Flip enabled state. |
+
+Defaults: `threshold` 5000 tokens, `minToolsUsed` 5, `collapseContext` true.
+
+---
+
+### `auto_boomerang` — Toggle auto-summarize (shorthand)
+
+Shares the same handler as `auto-summarize`; defaults `subAction` to `toggle`
+when omitted, providing a quick on/off switch.
+
+```json
+{ "action": "auto_boomerang" }
+```
+
+Accepts the same `config.subAction` values as `auto-summarize`
+(`on`, `off`, `config`, `toggle`, `status`).

package/index.ts

@@ -47,18 +47,29 @@
  *     avoid recursion), the bundle flip risk is acceptable.
  */
 import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
-import { registerPiTeams as registerPiTeamsFromSrc } from "./src/extension/register.ts";
-import { waitForRun as waitForRunFromSrc } from "./src/runtime/run-tracker.ts";
 import { accessSync } from "node:fs";
 import { fileURLToPath } from "node:url";
 import { dirname, resolve } from "node:path";
 
-// Minimal bundle shape — we only use a few named exports. Keep this loose
-// because dist/index.mjs has no .d.ts (it's a build artifact, not source).
+// IMPORTANT: src/ imports here MUST be dynamic (lazy `import()`), never
+// top-level static imports. Published npm packages ship only dist/index.mjs
+// in the tarball (src/ is excluded by the package.json "files" field — keeps
+// the package ~5MB instead of ~16MB). A top-level static
+// `import { x } from "./src/..."` is resolved by the module loader BEFORE
+// this file's code runs, so it would break every fresh `npm install`
+// (Cannot find module './src/...'). Dynamic import() defers src/ resolution
+// to the fallback path below, which only executes when the bundle is
+// unavailable — i.e. dev clones that still have src/. Published installs
+// always ship + load the bundle, so src/ is never touched there.
+
+// Minimal bundle shape — loose types because dist/index.mjs has no .d.ts
+// (it's a build artifact, not source). The src fallback types use
+// `typeof import(...)` type queries, which are type-only constructs erased
+// at runtime (no module load) — they stay in sync with the real modules.
 type BundleModule = {
 	default?: (pi: ExtensionAPI) => void;
-	waitForRun?: typeof waitForRunFromSrc;
-	registerPiTeams?: (pi: ExtensionAPI) => void;
+	waitForRun?: typeof import("./src/runtime/run-tracker.ts").waitForRun;
+	registerPiTeams?: typeof import("./src/extension/register.ts").registerPiTeams;
 };
 
 const OPT_OUT = new Set(["0", "false", "no", "off"]);
@@ -91,8 +102,26 @@ if (!envForceOff) {
 	}
 }
 
-export const waitForRun = bundleModule?.waitForRun ?? waitForRunFromSrc;
-export const registerPiTeams: (pi: ExtensionAPI) => void =
-	bundleModule?.registerPiTeams ?? registerPiTeamsFromSrc;
+// Lazy src/ fallback — only resolved when the bundle is unavailable
+// (dev clones without a built dist/). NEVER imported in published
+// installs, where the bundle always ships + loads above. This dynamic
+// import() is what lets us exclude src/ from the npm tarball.
+let srcRegister:
+	| typeof import("./src/extension/register.ts").registerPiTeams
+	| undefined;
+let srcWaitForRun:
+	| typeof import("./src/runtime/run-tracker.ts").waitForRun
+	| undefined;
+if (!bundleModule) {
+	({ registerPiTeams: srcRegister } = await import(
+		"./src/extension/register.ts",
+	));
+	({ waitForRun: srcWaitForRun } = await import(
+		"./src/runtime/run-tracker.ts",
+	));
+}
 
-export default bundleModule?.default ?? ((pi: ExtensionAPI) => registerPiTeamsFromSrc(pi));
+export const waitForRun = bundleModule?.waitForRun ?? srcWaitForRun!;
+export const registerPiTeams: (pi: ExtensionAPI) => void =
+	bundleModule?.registerPiTeams ?? srcRegister!;
+export default bundleModule?.default ?? ((pi: ExtensionAPI) => srcRegister!(pi));

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "pi-crew",
-  "version": "0.9.51",
+  "version": "0.9.53",
   "description": "Pi extension for coordinated AI teams, workflows, worktrees, and async task orchestration",
   "author": "baphuongna",
   "license": "MIT",
@@ -31,8 +31,8 @@
   "files": [
     "*.ts",
     "*.mjs",
-    "src/**/*.ts",
-    "dist/",
+    "dist/index.mjs",
+    "dist/build-meta.json",
     "agents/",
     "teams/",
     "workflows/",
@@ -45,7 +45,16 @@
     "scripts/pty_probe.py",
     "README.md",
     "AGENTS.md",
-    "docs/",
+    "docs/actions-reference.md",
+    "docs/commands-reference.md",
+    "docs/troubleshooting.md",
+    "docs/usage.md",
+    "docs/architecture.md",
+    "docs/dynamic-workflows.md",
+    "docs/runtime-flow.md",
+    "docs/resource-formats.md",
+    "docs/publishing.md",
+    "docs/migration-v0.4-v0.5.md",
     "tsconfig.json",
     "schema.json",
     "types/",
@@ -55,9 +64,10 @@
   ],
   "scripts": {
     "check": "npm run ci",
-    "ci": "npm run typecheck && npm run lint && npm run format:check && npm run check:conflict-markers && npm run check:lazy-imports && npm run check:bundle-staleness && npm run build:bundle && 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: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",
     "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 --diagnostic-level=error .",
@@ -116,10 +126,10 @@
   },
   "devDependencies": {
     "@biomejs/biome": "^2.5.3",
-    "@earendil-works/pi-agent-core": "^0.77.0",
-    "@earendil-works/pi-ai": "^0.77.0",
-    "@earendil-works/pi-coding-agent": "^0.77.0",
-    "@earendil-works/pi-tui": "^0.77.0",
+    "@earendil-works/pi-agent-core": "^0.82.0",
+    "@earendil-works/pi-ai": "^0.82.0",
+    "@earendil-works/pi-coding-agent": "^0.82.0",
+    "@earendil-works/pi-tui": "^0.82.0",
     "@types/node": "^25.9.5",
     "esbuild": "^0.28.1",
     "tsx": "^4.23.0",

package/schema.json

@@ -22,6 +22,12 @@
       "type": "boolean",
       "description": "Require a clean leader git repository before provisioning worktrees."
     },
+    "ignoreMethod": {
+      "type": "string",
+      "enum": ["gitignore", "exclude"],
+      "default": "gitignore",
+      "description": "Method for ignoring pi-crew generated directories from VCS: 'gitignore' appends to .gitignore, 'exclude' writes to .git/info/exclude."
+    },
     "autonomous": {
       "type": "object",
       "additionalProperties": false,
@@ -94,6 +100,30 @@
         "linkNodeModules": { "type": "boolean" }
       }
     },
+    "goalWrap": {
+      "type": "object",
+      "description": "Per-workflow goal-wrap configuration. Maps workflow name to goal-wrap settings (worker -> judge -> feedback -> redo until achieved / maxTurns / budget). Only applies to builtin workflows with a clear done condition.",
+      "additionalProperties": {
+        "type": "object",
+        "additionalProperties": false,
+        "properties": {
+          "enabled": { "type": "boolean" },
+          "maxTurns": { "type": "integer", "minimum": 1, "maximum": 50 },
+          "evaluatorModel": { "type": "string", "minLength": 1 },
+          "verification": {
+            "type": "object",
+            "additionalProperties": false,
+            "properties": {
+              "commands": { "type": "array", "items": { "type": "string", "minLength": 1 } },
+              "mode": { "type": "string", "enum": ["text-only"] }
+            },
+            "required": ["commands"]
+          },
+          "budgetTotal": { "type": "integer", "minimum": 1000 },
+          "budgetUnlimited": { "type": "boolean" }
+        }
+      }
+    },
     "agents": {
       "type": "object",
       "additionalProperties": false,
@@ -217,6 +247,17 @@
         "headers": { "type": "object", "additionalProperties": { "type": "string" } },
         "intervalMs": { "type": "integer", "minimum": 5000, "default": 60000 }
       }
+    },
+    "broker": {
+      "type": "object",
+      "additionalProperties": false,
+      "description": "Phase 0 inter-pi broker config for cross-process communication.",
+      "properties": {
+        "enabled": { "type": "boolean" },
+        "pathHashLen": { "type": "integer", "minimum": 4, "maximum": 32 },
+        "maxFrameBytes": { "type": "integer", "minimum": 1024, "maximum": 1048576 },
+        "outboundQueueCap": { "type": "integer", "minimum": 32, "maximum": 4096 }
+      }
     }
   }
 }