@selesai/code 0.6.2 → 0.7.0

package/dist/extensions/pi-subagents/package.json

@@ -1,16 +1,21 @@
 {
   "name": "pi-subagents",
-  "version": "0.40.0",
-  "description": "Selesai extension for delegating tasks to subagents with chains, parallel execution, and TUI clarification",
+  "version": "0.41.0",
+  "description": "Selesai extension for single-agent delegation and scripted multi-agent workflows",
   "author": "Nico Bailon",
   "license": "MIT",
   "type": "module",
   "exports": {
     ".": "./index.ts",
     "./background-work": "./src/api/background-work.ts",
+    "./external-runs": "./src/api/external-runs.ts",
     "./delegation": "./src/api/delegation.ts",
     "./capability-ceiling": "./src/api/capability-ceiling.ts",
-    "./preflight": "./src/api/preflight.ts"
+    "./preflight": "./src/api/preflight.ts",
+    "./control-channel": "./src/api/control-channel.ts",
+    "./intercom-bridge": "./src/api/intercom-bridge.ts",
+    "./pi-args": "./src/api/pi-args.ts",
+    "./shared-types": "./src/api/shared-types.ts"
   },
   "repository": {
     "type": "git",
@@ -43,6 +48,7 @@
     "CHANGELOG.md"
   ],
   "scripts": {
+    "typecheck": "tsc --noEmit",
     "test": "npm run test:unit",
     "test:unit": "node --experimental-strip-types --test test/unit/*.test.ts",
     "test:integration": "node --experimental-strip-types --import ./test/support/register-loader.mjs --test test/integration/*.test.ts",
@@ -91,7 +97,9 @@
   "devDependencies": {
     "@earendil-works/pi-agent-core": "0.81.0",
     "@earendil-works/pi-ai": "0.81.0",
-    "@selesai/code": "0.81.0",
-    "@earendil-works/pi-tui": "0.81.0"
+    "@selesai/code": "0.7.0",
+    "@earendil-works/pi-tui": "0.81.0",
+    "@types/node": "24.13.3",
+    "typescript": "5.9.3"
   }
 }

package/dist/extensions/pi-subagents/prompts/parallel-context-build.md

@@ -4,7 +4,7 @@ description: Parallel context builders for planning handoff
 
 Launch fresh-context `explorer` subagents in parallel to build grounded handoff context for planning or implementation.
 
-Use the `subagent` tool in chain mode with a single parallel step, not top-level parallel tasks, so relative output files live under the temporary chain directory. Use `context: "fresh"` unless I explicitly ask for forked context. Give every parallel task a distinct `output` path, `label`, and `as` name, for example:
+Use the `subagent` tool with `workflowScript` and `runs.all(...)`; assign each child a distinct absolute or durable output path. Use `context: "fresh"` unless I explicitly ask for forked context. Give every parallel task a distinct `output` path, `label`, and `as` name, for example:
 
 - `context-build/request-and-scope.md`
 - `context-build/codebase-and-patterns.md`

package/dist/extensions/pi-subagents/prompts/parallel-handoff-plan.md

@@ -10,7 +10,7 @@ $@
 
 Use `context: "fresh"` unless I explicitly ask for forked context. First read or fetch any URLs, issue links, PRs, screenshots, plans, docs, or local files mentioned in the request. Treat them as primary scope, not optional context.
 
-Use the `subagent` tool in chain mode:
+Use the `subagent` tool with `workflowScript`:
 
 1. First step: a parallel group.
    - `researcher`, when the request includes external references, APIs, libraries, docs, current best practices, or prompt-guidance research.

package/dist/extensions/pi-subagents/prompts/review-loop.md

@@ -8,7 +8,7 @@ Use the `subagent` tool. Keep the parent session as the loop controller and fina
 
 Default to a maximum of 3 review rounds unless I specify a different cap. Count a review round each time fresh-context commentators inspect the current diff after a builder pass. Stop early when commentators find no blockers or fixes worth doing now.
 
-If the invocation includes an implementation request, first launch one async `builder` to implement the approved scope. If the current diff is already the target, start with review. The sequence can be launched up front as an async/background chain when the workflow is already clear, or continued as follow-up subagent runs after each async completion. For an initial chain, pass `async: true` so the main chat is unblocked; do not set `clarify: true` unless I explicitly want the foreground clarify UI. Use only one writer against the active worktree at a time unless I explicitly ask for isolated worktrees.
+If the invocation includes an implementation request, first launch one async `builder` to implement the approved scope. If the current diff is already the target, start with review. The sequence can be launched up front with `workflowScript` when it is already clear, or continued as follow-up single-agent runs after each async completion. For an initial workflowScript, pass `async: true` so the main chat is unblocked; do not set `clarify: true` unless I explicitly want the foreground clarify UI. Use only one writer against the active worktree at a time unless I explicitly ask for isolated worktrees.
 
 As a conservative orchestration policy, do not set `turnBudget`, a hard `toolBudget`, or a tight `usageBudget` on implementation or fix builders. A default tool budget blocks read/search tools rather than mutation tools, and reported usage has no reservation model, so count or usage limits still do not measure delivery safety. Give each writer a narrow delivery slice and an outer elapsed deadline with enough margin. Before that deadline, request a checkpoint after the current tool returns with changed files, build/test state, remaining work, and commit or PR state. An elapsed timeout is not a mutation-safe boundary and must not be the checkpoint trigger.
 

package/dist/extensions/pi-subagents/skills/pi-subagents/SKILL.md

@@ -1,18 +1,18 @@
 ---
 name: pi-subagents
 description: |
-  Delegate work to builtin or custom subagents with single-agent, chain,
-  parallel, async, forked-context, and intercom-coordinated workflows. Use
-  for advisory review, implementation handoffs, and multi-step tasks where a
+  Delegate work to builtin or custom subagents with single-agent, scripted,
+  compatibility-chain, async, forked-context, and intercom-coordinated workflows. Use
+  for commentatory review, implementation handoffs, and multi-step tasks where a
   single agent should stay in control while other agents contribute context,
   planning, or execution.
 ---
 
 # Pi Subagents
 
-This skill is for the main parent orchestrator only. Do not inject or follow it inside spawned child subagents. The parent session owns delegation, orchestration, review fanout, and final fix-builder launches. Ordinary children should not run their own subagent workflows; the explicit exception is a delegated fanout child whose resolved builtin `tools` includes `subagent`, and that child may use `subagent` only for the fanout work the parent assigned.
+This skill is for the main parent orchestrator only. Do not inject or follow it inside spawned child subagents. The parent session owns delegation, orchestration, review fanout, and final fix-builder launches. Ordinary children should not run their own subagent workflows; the explicit exception is a explorerd fanout child whose resolved builtin `tools` includes `subagent`, and that child may use `subagent` only for the fanout work the parent assigned.
 
-Use this skill when the parent orchestrator needs to launch a specialized subagent, compose multiple agents into a workflow, or create/edit agents and chains on demand.
+Use this skill when the parent orchestrator needs one specialized child or composed orchestration. Use `{ agent, task }` for one isolated child with no sibling lane, monitor, dependency, or aggregation. Use `workflowScript` proactively for coordinated waves: sequence, parallelism, branching, retries, gate monitors, and aggregation. Scripted workflows start asynchronously by default; pass `async:false` only for a small foreground run. `workflowScript` is the only public multi-agent orchestration surface.
 
 ## How to use this router
 
@@ -20,14 +20,14 @@ Read the matching reference file before acting. Paths are relative to this `SKIL
 
 | Task | Read |
 | --- | --- |
-| Decide whether to delegate, choose agents, compare tool versus slash commands, apply prompt techniques, or understand builtin roles | `references/prompting-and-roles.md` |
-| Run single, parallel, chain, async, scheduled, forked, worktree, watchdog, clarify, commentator, or intercom-coordinated workflows | `references/execution-controls.md` |
+| Decide whether to explorer, choose agents, compare tool versus slash commands, apply prompt techniques, or understand builtin roles | `references/prompting-and-roles.md` |
+| Run single, scripted, async, scheduled, mission-backed, forked, worktree, watchdog, clarify, commentator, or intercom-coordinated workflows | `references/execution-controls.md` |
 | List/create/update/delete/eject/disable agents or chains, edit agent files, use prompt-template integration, or expose extension RPC | `references/management-authoring-rpc.md` |
 | Check safety constraints, best practices, standard workflows, or error handling | `references/constraints-and-recipes.md` |
 
 Selesai default: use Fable-style parent orchestration for complex work (multiple moving parts, unclear acceptance, cross-cutting code, meaningful user impact, expensive validation, or broad review surface). Lightweight one-off delegation stays lightweight.
 
-Routing rule: keep tiny targeted reads and simple answers with the parent. For broad local investigation, external research, or mutation work, call `{ action: "list" }`, choose an executable entry from its runtime metadata, then delegate. Treat list output—not hardcoded role names—as the agent-selection authority.
+Routing rule: keep tiny targeted reads and simple answers with the parent. For broad local investigation, external research, or mutation work, call `{ action: "list" }`, choose an executable entry from its runtime metadata, then explorer. Treat list output—not hardcoded role names—as the agent-selection authority.
 
 For broad or uncertain requests, read more than one reference. For complex work, start with `references/prompting-and-roles.md` and `references/execution-controls.md`, then consult `references/constraints-and-recipes.md` before launching or reviewing child work.
 
@@ -35,9 +35,9 @@ For broad or uncertain requests, read more than one reference. For complex work,
 
 - Keep the parent as orchestrator and final decision-maker.
 - Use one writer per cwd/worktree unless isolated worktrees are intentional.
-- For parallel fanout, compare child prompts before launch. Do not send clone prompts with only issue numbers, titles, or broad file globs swapped; each child needs a lane-specific task, source seam, prior evidence, and decision that remains distinct without the item number.
+- For parallel fanout, compare child prompts before launch. Do not send clone prompts with only issue numbers, titles, or broad file globs swapped; each child needs a lane-specific task, source seam, prior evidence, and decision that remains distinct without the item number. Launch that fanout as one `workflowScript` with stable keys and aggregate output unless there is truly only one child.
 - Prefer fresh-context review/validation fanout, then synthesize and apply fixes in the parent.
-- Use async/background only when work can proceed independently; do not poll just to wait. For planned human gates in chains, use `{ checkpoint: "name", message?: "..." }` and approve or reject paused async checkpoints with `approve-checkpoint` / `reject-checkpoint`.
+- Use async/background only when work can proceed independently; do not poll just to wait. For adaptive gates, branch in `workflowScript`. Approval controls remain available only for already-running durable legacy chains.
 - Preserve capability ceilings, including child tool restrictions and session-scoped allowed-agent restrictions.
 - Escalate unresolved product, architecture, or safety decisions upward instead of letting a child decide silently.
 - As a conservative orchestration policy, do not pass `turnBudget`, a hard `toolBudget`, or a tight `usageBudget` to mutation-capable builders. The default tool budget blocks read/search tools rather than mutation tools, and reported usage has no reservation model. If a builder is interrupted after a tool call starts, checkpoint after the current tool returns with changed files, build/test state, and commit or PR state.

package/dist/extensions/pi-subagents/skills/pi-subagents/references/constraints-and-recipes.md

@@ -18,14 +18,15 @@ This file is a detailed reference loaded from `skills/pi-subagents/SKILL.md`.
   ask wait state at a time.
 - **Keep conversational authority clear.** Advisory subagents should not silently
   become second decision-makers.
+- **Respect the fixed authority policy.** `authorityPolicy` is a small `auto` / `confirm` / `forbid` map for supported operational actions. Worktree discard, destructive cleanup, and spawn-budget grants default to confirmation; stop, steer, and schedule creation remain automatic. Use `worktree.discard` with the durable `handoffPath`; confirm-required actions refuse safely without an interactive UI and retained paths include manual Git recovery commands.
 
-Runtime config can change orchestration behavior. `intercomBridge.resultDelivery: false` disables only external acknowledged grouped-result delivery when native parent notifications own completion; supervisor asks/progress stay active, and enabled transport failures are still reported. `asyncByDefault` and `forceTopLevelAsync` affect whether launches detach; `waitTool` can make direct `subagent_wait()` calls return immediately while headless auto-drain remains active, and its effective value is propagated to child runtimes; `globalConcurrencyLimit` bounds concurrent fanout, while a positive `maxSubagentSpawnsPerSession` optionally caps cumulative launches (`0` or unset is unlimited). Status and doctor report the budget; static work preflights declared capacity; only the settled root interactive parent can use `grant-spawn-budget` after native confirmation, with total grants bounded by the original cap. Compaction does not reset usage or grants; `singleRunOutputBaseDir` and `worktreeBaseDir` route outputs and worktrees; `completionBatch` groups async notifications. `artifactDir` is `project` (default), `session`, or `temp` and chooses where subagent artifacts are stored. Set `asyncWidget: false` to hide the above-editor background-run widget when a companion footer or dashboard owns that space (fleet inspector remains available). Artifact capture is off by default; set per-run `artifacts: true` when debug files are needed. Async status and result artifacts are versioned with fields such as `lifecycleArtifactVersion`, `workflowGraph`, `steps`, `results`, `totalTokens`, `totalCost`, `turnCount`, `toolCount`, and nested `children`. Child protocol failures expose a structured `protocolError`; `protocol_output_limit` means a child emitted a JSONL line above the 4 MiB live-parser cap. Prefer these artifacts and `status` views over scraping terminal output.
+Runtime config can change orchestration behavior. `intercomBridge.resultDelivery: false` disables only external acknowledged grouped-result delivery when native parent notifications own completion; supervisor asks/progress stay active, and enabled transport failures are still reported. `asyncByDefault` and `forceTopLevelAsync` affect whether launches detach; `waitTool` can make direct `subagent_wait()` calls return immediately while headless auto-drain remains active, and its effective value is propagated to child runtimes; `globalConcurrencyLimit` bounds concurrent fanout, while a positive `maxSubagentSpawnsPerSession` optionally caps cumulative launches (`0` or unset is unlimited). Status and doctor report the budget; static work preflights declared capacity; only the settled root interactive parent can use `grant-spawn-budget` after native confirmation, with total grants bounded by the original cap. Compaction does not reset usage or grants; `singleRunOutputBaseDir` and `worktreeBaseDir` route outputs and worktrees; `completionBatch` groups async notifications. `artifactDir` is `project` (default), `session`, or `temp` and chooses where subagent artifacts are stored. Set `asyncWidget: false` to hide the above-editor background-run widget when a companion footer or dashboard owns that space (fleet inspector remains available). Artifact capture is off by default; set per-run `artifacts: true` when debug files are needed, and per-run `artifacts: false` disables capture for that launch. Authority policy (`authorityPolicy`) is enforced at the settled root parent before confirm-required actions such as worktree discard, destructive cleanup, and spawn-budget grants. Async status and result artifacts are versioned with fields such as `lifecycleArtifactVersion`, `workflowGraph`, `steps`, `results`, `totalTokens`, `totalCost`, `turnCount`, `toolCount`, and nested `children`. Child protocol failures expose a structured `protocolError`; `protocol_output_limit` means a child emitted a JSONL line above the 4 MiB live-parser cap. Prefer these artifacts and `status` views over scraping terminal output.
 
 ## Best Practices
 
 ### Prefer async orchestration
 
-Launch every subagent asynchronously by default. Use `async: true` for explorers, researchers, builders, commentators, validators, commentator checks, one-off builders, chains, and parallel groups unless you intentionally need a foreground/blocking run. The parent should keep moving: inspect code while explorers run, prepare validation while a builder implements, do a local diff pass while commentators review, and synthesize or verify while a fix builder applies accepted feedback. Async is the default orchestration posture; foreground runs are the explicit opt-out.
+Launch every subagent asynchronously by default. Use `async: true` for explorers, researchers, builders, commentators, validators, commentator checks, one-off builders, and scripted workflows unless you intentionally need a foreground/blocking run. When two or more child lanes, monitors, or dependent steps should move together, launch them as one `workflowScript` with stable keys instead of separate tool calls; use direct single-child launches only for truly isolated work. The parent should keep moving: inspect code while explorers run, prepare validation while a builder implements, do a local diff pass while commentators review, and synthesize or verify while a fix builder applies accepted feedback. Async is the default orchestration posture; foreground runs are the explicit opt-out.
 
 ### Use subagent_wait() to block until async runs finish
 
@@ -40,13 +41,13 @@ Providers are discovered through the versioned `pi-subagents/background-work` re
 
 For non-interactive fleet orchestration, `subagent_wait()` can keep N builders in flight: launch N, wait for the next completion, react to the result, launch a replacement if needed, then wait again. Use `subagent_wait({ all: true })` only when you intentionally want to drain the fleet to zero. If the turn ends first, headless `agent_end` auto-drain still waits for exact current-session work. In an interactive session, return to the user instead of holding the turn open just to await completion.
 
-If config or `PI_SUBAGENT_WAIT_TOOL_ENABLED` disables blocking behavior, direct `subagent_wait` calls return immediately. Headless `agent_end` auto-drain remains active as a lifecycle safeguard and surfaces provider, reconciliation, or timeout failures.
+If config or `SELESAI_SUBAGENT_WAIT_TOOL_ENABLED` disables blocking behavior, direct `subagent_wait` calls return immediately. Headless `agent_end` auto-drain remains active as a lifecycle safeguard and surfaces provider, reconciliation, or timeout failures.
 
 ### Keep writes single-threaded by default
 
-A strong pattern is one main decision-maker plus advisory/research/review/validation subagents around it. Use `commentator` for advice and `builder` for the actual write path. Parallelize reading, review, validation, and synthesis support, not normal writes, unless you deliberately isolate writers with worktrees. A child that writes should report what changed, what was left undone, commands run with exit codes, validation evidence, surprises, and any decisions that need parent approval.
+A strong pattern is one main decision-maker plus commentatory/research/review/validation subagents around it. Use `commentator` for advice and `builder` for the actual write path. Parallelize reading, review, validation, and synthesis support, not normal writes, unless you deliberately isolate writers with worktrees. A child that writes should report what changed, what was left undone, commands run with exit codes, validation evidence, surprises, and any decisions that need parent approval.
 
-### Use fork for branched advisory or execution threads
+### Use fork for branched commentatory or execution threads
 
 Forked runs are useful when the child should reason in a separate thread while
 still inheriting the parent’s accumulated context. They are especially useful for
@@ -66,7 +67,7 @@ it should use `contact_supervisor` and wait for the reply instead of deciding al
 
 ### Intervene only on clear control signals
 
-Use subagent control proactively when a delegated run emits `needs_attention`, or when a human asks you to regain control. Do not interrupt just because a child has briefly produced no output. Silence can be normal during long tool calls, test runs, or model reasoning.
+Use subagent control proactively when a explorerd run emits `needs_attention`, or when a human asks you to regain control. Do not interrupt just because a child has briefly produced no output. Silence can be normal during long tool calls, test runs, or model reasoning.
 
 ### Name sessions meaningfully
 
@@ -76,14 +77,12 @@ Use `/name` so intercom targeting stays stable.
 
 ### Recon → Plan → Implement
 
-```typescript
-subagent({
-  chain: [
-    { agent: "explorer", task: "Map the auth flow and summarize relevant files" },
-    { agent: "architect", task: "Plan the migration from {previous}" },
-    { agent: "builder", task: "Implement the approved plan from {previous}" }
-  ]
-})
+```js
+subagent({ workflowScript: `
+  const recon = await runs.run("recon", { agent: "explorer", task: "Map the auth flow and summarize relevant files" });
+  const plan = await runs.run("plan", { agent: "architect", task: "Plan the migration from: " + recon.output });
+  return (await runs.run("implement", { agent: "builder", task: "Implement the approved plan from: " + plan.output })).output;
+` })
 ```
 
 ### Fable mode for complex work
@@ -112,7 +111,7 @@ When the user approves launching a subagent to carry out a plan or workflow, tre
 - `/parallel-review` maps to: launch fresh-context `commentator` agents with distinct review angles; synthesize the feedback before applying anything.
 - `/review-loop` maps to: keep the parent in charge of builder → fresh commentators → synthesized fix builder cycles until no fixes worth doing now remain, an unapproved decision appears, or the review-round cap is reached.
 - `/parallel-research` maps to: combine local `explorer` context with external `researcher` evidence when current docs, ecosystem behavior, or API details matter.
-- `/parallel-context-build` maps to: run a chain-mode parallel group of `explorer` agents with distinct temp output paths, then synthesize their context and meta-prompt sections.
+- `/parallel-context-build` maps to: use `workflowScript` with `runs.all` for distinct `explorer` lanes, then synthesize their context and meta-prompt sections.
 - `/parallel-handoff-plan` maps to: run external `researcher` plus local/strategy `explorer` passes, then a synthesis `explorer` that writes an implementation handoff plan and implementation-ready meta-prompt.
 - `/parallel-cleanup` maps to: use review-only cleanup passes after implementation, especially for simplicity, verbosity, and redundant tests.
 
@@ -162,17 +161,15 @@ subagent({
 
 Example review pass after implementation:
 
-```typescript
-subagent({
-  tasks: [
-    { agent: "commentator", task: "Review the current diff for correctness and regressions. Inspect changed files directly; do not rely on the builder's reasoning.", output: false },
-    { agent: "commentator", task: "Review the current diff for tests and validation quality against the validation contract. Inspect changed files directly.", output: false },
-    { agent: "commentator", task: "Review the current diff for simplicity and maintainability. Inspect changed files directly.", output: false }
-  ],
-  concurrency: 3,
-  context: "fresh",
-  async: true
-})
+```js
+subagent({ workflowScript: `
+  const reviews = await runs.all([
+    { key: "correctness", agent: "commentator", task: "Review the current diff for correctness and regressions. Inspect changed files directly; do not rely on the builder's reasoning.", output: false },
+    { key: "tests", agent: "commentator", task: "Review the current diff for tests and validation quality against the validation contract. Inspect changed files directly.", output: false },
+    { key: "simplicity", agent: "commentator", task: "Review the current diff for simplicity and maintainability. Inspect changed files directly.", output: false }
+  ]);
+  return { correctness: reviews.correctness.output, tests: reviews.tests.output, simplicity: reviews.simplicity.output };
+` })
 ```
 
 Example fix builder after parallel reviews:
@@ -195,23 +192,15 @@ For explicit review-loop requests, repeat builder → fresh-commentator → synt
 
 ### Parallel non-conflicting analysis
 
-```typescript
-subagent({
-  tasks: [
-    { agent: "explorer", task: "Audit frontend auth flow" },
-    { agent: "researcher", task: "Research current retry/backoff best practices" }
-  ]
-})
+```js
+subagent({ workflowScript: `
+  return await runs.all([
+    { key: "frontend", agent: "explorer", task: "Audit frontend auth flow" },
+    { key: "research", agent: "researcher", task: "Research current retry/backoff best practices" }
+  ]);
+` })
 ```
 
-### Saved chain
-
-```text
-/run-chain review-chain -- review this branch
-```
-
-Use saved `.chain.md` or `.chain.json` workflows when the user wants a repeatable multi-agent flow without rewriting the chain each time. Prefer `.chain.json` for dynamic fanout or inline `outputSchema` objects; `.chain.md` remains the simple sequential/static authoring format.
-
 ## Error Handling
 
 **"Unknown agent"**
@@ -241,9 +230,9 @@ subagent({ action: "doctor" })
 // Resolve the current outbound ask before starting another one.
 ```
 
-**Parallel output-path conflict**
+**Workflow lane output-path conflict**
 ```typescript
-// Give each parallel task a distinct output path, or disable output for tasks that do not need it.
+// Give each runs.all lane a distinct key and prompt, or use output: false for lanes that do not need it.
 ```
 
 **Worktree launch fails**