@henryqw/pi-subagent 3.0.2 → 3.1.0

package/CONTEXT.md

@@ -2,27 +2,31 @@
 
 ## Purpose
 
-Provide validated user Roles, shared task-model Pi launch policy, generic managed Herdr Subagent hosting, and a `delegate_task` extension that runs one bounded task in one isolated child process.
+Provide validated user Roles, shared task-model Pi launch policy, generic managed Herdr Subagent hosting, and a `delegate_task` extension that runs one selected bounded workflow in one or more ephemeral child processes.
 
 ## Domain glossary
 
 - **Main**: Pi session delegating work.
 - **Subagent**: isolated Pi child process handling one task.
-- **Role**: user-owned Markdown profile defining name, description, system instructions, optional exact tool allowlist, extensions, and Skill names.
+- **Role**: user-owned Markdown definition of a reusable responsibility, with a name, description, system instructions, optional base tool allowlist, extensions, and Skill names.
 - **Model Class**: `fast`, `balanced`, `frontier`, or `fav`, assigned in shared task-model settings or overridden by Main from task complexity.
 - **Route**: configured model and thinking-level pair selected from a shared Model Class profile; the primary route precedes its optional fallback.
 - **Delegated Task**: one bounded work request sent from Main to one Role.
+- **Workflow**: orchestration of one or more Delegated Tasks; `delegate_task` owns its selected mode, while library callers compose executor runs in JavaScript.
+- **Workflow Mode**: `delegate_task` tool policy selected per call for `single`, `parallel`, or `chain` execution; not a Role property or executor API.
+- **Resource Policy**: Role ownership of base tools, extensions, and Skill names, plus explicit caller additions of tools, extensions, and environment through `createRoleLaunch`.
 - **Pi Launch**: reusable `{env,args}` policy for one Role, resolved model route, explicit caller resources, and project trust.
+- **Ephemeral Executor**: mechanism that receives a prepared Pi Launch, runs one bounded Delegated Task in one no-session child process, and returns its result without discovering resources or composing a Workflow.
 - **Managed Subagent**: Pi agent hosted in a reconciled Herdr tab or pane; lifecycle orchestration remains with the caller.
 
 ## Invariants
 
 - One Delegated Task creates one ephemeral child process and no saved session. Timeout behavior: `deadline = min(last recognized Pi JSON event + idle timeout, child start + maximum runtime)` (recognized Pi events renew; raw bytes do not; max always terminates). Configurable via the `timeout` object in `~/.pi/agent/config/pi-subagent/pi-subagent.json` (`idleMinutes`, `maxMinutes`; defaults 10/30).
 - Up to five active ephemeral `delegate_task` children run per Main by default, configurable via `maxSubagents` in `~/.pi/agent/config/pi-subagent/pi-subagent.json` or the `PI_SUBAGENT_MAX_SUBAGENTS` environment variable; excess calls wait FIFO. Queued calls do not start a child or consume child timeout. Managed Herdr workers are unaffected.
-- Ambient child extensions and Skills stay disabled; Role explicitly selects extension sources and named Skills. Pi loads Skills supplied by those extension packages or their resource discovery. Omitted Role tools use Pi's effective `defaultTools`; an explicit list sets base tools while loaded extension tools activate automatically.
+- Ambient child extensions and Skills stay disabled; Role explicitly selects extension sources and named Skills. Pi loads Skills supplied by those extension packages or their resource discovery. With Role and caller tools omitted, no allowlist is installed and Pi uses its defaults. Caller tools with omitted Role tools snapshot Main's effective active built-ins into the installed policy; explicit Role tools set the base. Loaded extension tools activate automatically in every case.
 - Role Skill names resolve through Main's effective Pi Skill registry; unavailable names warn and skip without blocking delegation.
 - Main selects Role and may override Model Class and thinking level per task; omitted class uses shared `pi-subagent/delegateTask` assignment, initially `balanced`. Library callers select Role plus their own shared task ID.
 - The selected profile resolves primary then fallback only before launch when a route, model, or thinking level is unavailable. If neither route is usable, launch rejects with `Run /task-models`; a started child is never retried by this package.
-- Role and Subagent JSON config live only in the user `config/pi-subagent` directory; model routes live in shared `config/pi-task-models.json`; repository roles do not execute.
+- Role Markdown files and Subagent JSON config live only in the user `config/pi-subagent` directory; model routes live in shared `config/pi-task-models.json`; repository roles do not execute.
 - Numbered Codex routes prefer Main's active account slot and explicitly load the multi-Codex child extension.
 - Generic Herdr host functions validate workspace ownership and provisioning identity while callers retain domain state, prompts, and lifecycle decisions.

package/README.md

@@ -1,11 +1,11 @@
 # `@henryqw/pi-subagent`
 
-Delegate one bounded task to one isolated Pi process, or reuse validated Role launch and managed Herdr hosting for durable workers. Main chooses Role and may override shared task-model effort per call.
+Delegate bounded work to isolated Pi child processes. The `delegate_task` tool has one flat contract with exactly one selected mode: single, parallel, or chain. Package authors can reuse the same Role launch policy and active-Pi executor from JavaScript.
 
 ## Why
 
-- **Created for**: Delegating bounded tasks to isolated child Pi processes while Main retains integration decisions.
-- **Advantage**: Validated Roles, capped concurrency, timeouts, and managed Herdr hosting make delegation predictable.
+- **Created for**: Pi users who need to delegate bounded work to isolated child Pi processes without losing Main's context.
+- **Advantage**: One flat `delegate_task` tool contract with single, parallel, and chain modes, plus reusable Role launch policies for package authors.
 
 ## Install
 
@@ -19,86 +19,78 @@ pi install npm:@henryqw/pi-subagent
 
 | Package | Why |
 | --- | --- |
-| `@henryqw/pi-task-models` | Required. Shared `fast` / `balanced` / `frontier` / `fav` routes. |
-| `@henryqw/pi-multi-codex` | Required. Child uses Main's active Codex slot. |
+| `@henryqw/pi-task-models` | Required shared `fast` / `balanced` / `frontier` / `fav` routes. |
+| `@henryqw/pi-multi-codex` | Required so children can use Main's active Codex slot. |
 
 ## Use
 
 | Surface | Type | Purpose |
 | --- | --- | --- |
-| `delegate_task` | tool | Start one isolated child for `role`, `task`, and optional `model`, `modelClass`, or `thinking`. |
+| `delegate_task` | tool | Delegate bounded work to one or more isolated Pi child processes. |
 
-An explicit `model` (`provider/modelId`) overrides `modelClass` and resolves against the currently available text models; an unknown reference rejects with the list of available models. Thinking level defaults to `medium` when supported, otherwise the highest supported level; a designated model with no usable level rejects before launch. An explicit `thinking` level participates in route resolution itself: routes that cannot honor it are skipped so fallback routes get considered, and delegation rejects when no route supports the level.
+### `delegate_task`
 
-`modelClass` is `fast`, `balanced`, `frontier`, or `fav`. Omitted class uses the shared `pi-subagent/delegateTask` assignment, which defaults to `balanced`. Primary route is resolved against current scoped text models; fallback is tried only before launch. If no route is usable, delegation rejects with `Run /task-models`. A started child is never retried.
+Select exactly one shape:
 
-Main splits broad work into independent bounded tasks and keeps integration and cross-cutting decisions. Each `task` states its objective, exact scope and exclusions, relevant context and constraints, expected deliverable, and validation. Each call uses the least capable `modelClass` that can reliably complete its task. Independent sibling calls can run concurrently; concurrent edit tasks must own non-overlapping files. Up to five active ephemeral `delegate_task` subagents run per Main; excess calls wait FIFO. Configure the cap with `"maxSubagents"` (positive integer) in `~/.pi/agent/config/pi-subagent/pi-subagent.json`, or override per session with the `PI_SUBAGENT_MAX_SUBAGENTS` environment variable. Child timeouts are configurable with a `"timeout"` object: `{ "idleMinutes": 10, "maxMinutes": 30 }` (all keys optional; defaults 10/30; the effective maximum must exceed the idle timeout). Invalid config values fall back to the default with a warning; an invalid environment variable fails fast. Queued calls do not start a child or consume child timeout. Managed Herdr workers are unaffected.
+```text
+// Single
+{ role, task, model?, modelClass?, thinking?, background? }
 
-Each call starts one isolated child (`pi --mode json -p --no-session`). Ambient extensions and Skills are off. Role/caller extensions load; those packages' tools and Skills auto-load, plus any extra `skills` names. Child uses the delegated working directory and Main's project approval. Abort kills the child process group. Child timeout behavior uses `deadline = min(last recognized Pi JSON event + idle timeout, child start + maximum runtime)`: recognized Pi events renew; raw bytes do not; max always terminates. Streaming output is capped at 50 KiB. Unused JSON event types are discarded before payload buffering; consumed or unclassifiable events above 1 MiB fail delegation.
+// Parallel: 1–8 independent delegations
+{ tasks: [{ role, task, model?, modelClass?, thinking? }], background? }
 
-TUI shows one row per Subagent with role, route, task, tokens, and elapsed time. Terminal rows drop after one second.
+// Chain: 1–8 dependent delegations
+{ chain: [{ role, task, model?, modelClass?, thinking? }], background? }
+```
+
+`model` is `provider/modelId` and overrides `modelClass`. `modelClass` is `fast`, `balanced`, `frontier`, or `fav`; omission uses the shared `pi-subagent/delegateTask` assignment. `background` applies to the entire selected mode and is never a per-delegation field.
+
+Parallel mode starts entries concurrently, waits for every entry, and reports them in input order. Chain mode is sequential and fail-fast; every literal `{previous}` receives only the immediately preceding successful assistant output. Foreground failures throw after retaining bounded sibling and recovery evidence. One tool call has one aggregate 50 KiB Main-visible transport cap, not 50 KiB per child.
+
+Background workflows are session-scoped. Session shutdown or reload aborts them and may deliver only recoverable-work evidence or no follow-up message.
+
+Each delegation resolves its own user Role, resources, route, and optional worktree request. When available, `isolation: worktree` gives each entry a deterministic separate worktree; non-Git or unborn-`HEAD` contexts may use Main's cwd. Siblings and chain steps never implicitly share one created worktree.
+
+See [Orchestration, isolation, and the public API](./docs/orchestration.md) for the complete contract and JavaScript composition examples.
 
 ## Config
 
-Role files and `pi-subagent.json` live in `~/.pi/agent/config/pi-subagent/`. Model routes live in `~/.pi/agent/config/pi-task-models.json`.
-
-```markdown
----
-name: reviewer
-description: Reviews changes for correctness and security
-tools: [read, grep, find, ls, bash]
-extensions:
-  - ~/.pi/agent/extensions/review-tools.ts
-skills:
-  - code-review
-  - security
----
-
-Review only requested change. Return ranked findings with file and line evidence.
-Do not edit files.
+`~/.pi/agent/config/pi-subagent/pi-subagent.json` controls the ephemeral child pool and timeouts:
+
+```json
+{
+  "maxSubagents": 5,
+  "timeout": { "idleMinutes": 10, "maxMinutes": 30 }
+}
 ```
 
-| Field | Required | Meaning |
-| --- | --- | --- |
-| `name` | yes | Role selected by Main |
-| `description` | yes | Tells Main when to use the role |
-| `tools` | no | Omit for Pi defaults; when present, base tools are listed and every loaded Role/caller extension tool is added automatically. `[]` leaves extension tools only. |
-| `extensions` | no | Absolute/`~/` paths or package sources. Package-declared Skills and Pi `resources_discover` Skill paths load automatically. Repository-relative paths are rejected. |
-| `skills` | no | Additional effective Pi Skill names, resolved from Main's registry |
-| `isolation` | no | Set to `worktree` to give each delegated child its own git worktree branched from Main's current `HEAD` |
-| Markdown body | yes | Role system instructions |
+Excess children wait FIFO without consuming child timeout. `PI_SUBAGENT_MAX_SUBAGENTS` overrides the configured concurrency for the session.
 
-Missing skills warn and skip; they do not block delegation. No repo-controlled `.pi/agents` roles. No package-local model picker.
+## Roles
 
-With `isolation: worktree`, each child runs in `<primary-workspace>/.worktrees/subagent-<hash>` on branch `pi-subagent/subagent-<hash>`, using a fixed hash of the child ID so parallel children never clobber each other's files. This stable root keeps children outside removable linked checkouts. Git submodules reject worktree isolation because parent cleanup can remove their Git metadata. Non-git directories and repositories with no commits silently share Main's working directory; worktree setup failures in a real git repository reject the delegation instead of silently losing isolation. The directory is excluded from git status through the repository-local exclude file. The child is told to work only inside its worktree and commit to its branch; after each run the parent sees a worktree report (path, branch, commits, dirty, pruned) appended to the result — including failures and preserved background work during session shutdown, so kept work is always locatable. Worktrees are discarded only when the dedicated branch has no commits, `HEAD` still names that branch, and the full tree including ignored files and submodules is clean; anything holding work stays for the parent to review and merge — children never merge.
+Roles are user-owned Markdown files in `~/.pi/agent/config/pi-subagent/`. This repository includes inert samples:
 
-## Library API
+- [`scout`](./examples/roles/scout.md): read-only discovery
+- [`implementer`](./examples/roles/implementer.md): focused edits requesting worktree isolation
+- [`reviewer`](./examples/roles/reviewer.md): read-only correctness review
+- [`synthesizer`](./examples/roles/synthesizer.md): reconcile supplied reports
+
+Copy them manually from the repository root:
 
-Package root exports shared `Role` loading, Skill resolution, task-routed Pi launch, and generic managed Herdr lifecycle:
-
-```ts
-import {
-  loadRoles,
-  resolveRoleLaunch,
-  managedSubagentWorkspaceId,
-  reconcileManagedSubagentTab,
-  startManagedSubagent,
-} from "@henryqw/pi-subagent";
-
-const role = loadRoles().find(({ name }) => name === "reviewer")!;
-const launch = resolveRoleLaunch(pi, ctx, {
-  role,
-  taskId: "your-package/review",
-  extensions: [adapterExtensionPath],
-  tools: ["submit_review"],
-});
-const workspaceId = await managedSubagentWorkspaceId(ctx.cwd, mainPane, { execute });
-const host = { cwd: ctx.cwd, workspaceId };
-const tab = await reconcileManagedSubagentTab(host, { cwd: worktree, launch, label }, { execute });
-await startManagedSubagent(host, agentName, tab.paneId, launch, { execute });
+```bash
+mkdir -p ~/.pi/agent/config/pi-subagent
+cp packages/pi-subagent/examples/roles/*.md ~/.pi/agent/config/pi-subagent/
 ```
 
-`resolveRoleLaunch` uses shared task assignment and effective Pi registries. Caller tools extend Role base tools; Role and caller extension tools activate automatically. Omitted Role `tools` preserves Pi defaults. Generic host APIs contain no workflow prompts or durable state.
+The package never installs or writes Role configuration. Sample names are not built-ins; after copying, edit or replace them as your own Roles.
+
+A Role owns its base tools, extensions, named Skills, instructions, and optional `isolation: worktree`. Ambient extension and Skill discovery is disabled in children. With neither Role tools nor caller tools, Pi defaults remain; caller tools with omitted Role tools snapshot Main's effective active built-ins and install the child policy. Loaded Role/caller extension tools still activate, parent-only tools stay excluded, and unavailable named Skills warn and skip.
+
+## Library API
+
+The package root exports Role loading and launch resolution, `createEphemeralSubagentExecutor`, worktree helpers, and generic managed Herdr lifecycle helpers. The ephemeral executor is for code already running inside active Pi; it does not provide standalone Node.js Pi discovery or launch support.
+
+Use [`docs/orchestration.md`](./docs/orchestration.md#public-role-and-executor-api) for exact API behavior and a post-permit `prepare` example using `resolveRoleLaunch` against the latest Pi context.
 
 ## Remove
 

package/dist/ephemeral.d.ts

@@ -0,0 +1,50 @@
+import type { Usage } from "@earendil-works/pi-ai";
+import type { PiLaunch } from "./index.ts";
+export interface EphemeralSubagentTimeout {
+    idleMs: number;
+    maxMs: number;
+}
+export interface EphemeralSubagentExecutorOptions {
+    maxConcurrency: number;
+    timeout: EphemeralSubagentTimeout;
+}
+export interface EphemeralSubagentRunInput {
+    signal?: AbortSignal;
+    onUpdate?: (text: string) => void;
+    onTokens?: (tokens: number) => void;
+    prepare: () => Promise<{
+        launch: PiLaunch;
+        task: string;
+        cwd: string;
+    }>;
+}
+interface EphemeralSubagentResultBase {
+    exitCode: number;
+    output: string;
+    stderr: string;
+    stopReason?: string;
+    errorMessage?: string;
+    usage?: Usage;
+}
+export type EphemeralSubagentResult = (EphemeralSubagentResultBase & {
+    outcome: "success";
+}) | (EphemeralSubagentResultBase & {
+    outcome: "failure";
+});
+export type EphemeralSubagentErrorCode = "aborted" | "timeout" | "spawn" | "protocol" | "prepare" | "callback";
+export declare class EphemeralSubagentError extends Error {
+    name: string;
+    readonly code: EphemeralSubagentErrorCode;
+    readonly usage?: Usage;
+    constructor(code: EphemeralSubagentErrorCode, message: string, cause?: unknown, usage?: Usage);
+}
+export interface EphemeralSubagentExecutor {
+    run(input: EphemeralSubagentRunInput): Promise<EphemeralSubagentResult>;
+}
+/**
+ * Creates a bounded ephemeral executor for callers already running inside Pi.
+ * It reuses the active Pi process invocation; it does not resolve a standalone Pi installation.
+ */
+export declare function createEphemeralSubagentExecutor(options: EphemeralSubagentExecutorOptions): EphemeralSubagentExecutor;
+export declare function capEphemeralSubagentOutput(text: string): string;
+export {};