@xzzpig/pi-subagents 0.16.0 → 0.19.0
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/CHANGELOG.md +233 -1
- package/README.md +5 -3
- package/agents/claude-code-writer.md +1 -0
- package/agents/codex-exec-writer.md +1 -0
- package/agents/cursor-agent-writer.md +1 -0
- package/agents/reviewer.md +3 -2
- package/agents/worker.md +3 -2
- package/docs/agents.md +34 -21
- package/docs/configuration.md +82 -7
- package/docs/extension-api.md +75 -8
- package/docs/missions.md +13 -13
- package/docs/models.md +7 -5
- package/docs/observability.md +23 -13
- package/docs/standalone-background.md +5 -5
- package/docs/tool-reference.md +98 -100
- package/docs/watchdog.md +2 -0
- package/docs/workflows.md +214 -162
- package/inspector-runner.mjs +1 -1
- package/node_modules/@xzzpig/pi-components/package.json +4 -4
- package/package.json +15 -9
- package/prompts/council.md +6 -3
- package/prompts/review-loop.md +1 -1
- package/runner-peer-loader.mjs +4 -7
- package/runner-peer-preload.mjs +5 -7
- package/skills/council-mode/SKILL.md +1 -1
- package/skills/pi-subagents/SKILL.md +13 -5
- package/skills/pi-subagents/references/constraints-and-recipes.md +8 -5
- package/skills/pi-subagents/references/execution-controls.md +72 -69
- package/skills/pi-subagents/references/management-authoring-rpc.md +4 -4
- package/skills/pi-subagents/references/multi-lane-orchestration.md +9 -1
- package/skills/pi-subagents/references/prompting-and-roles.md +52 -54
- package/src/agents/advertised-agent-prompt.ts +21 -41
- package/src/agents/agent-eject.ts +3 -3
- package/src/agents/agent-management.ts +63 -54
- package/src/agents/agent-memory.ts +90 -3
- package/src/agents/agent-serializer.ts +4 -4
- package/src/agents/agents.ts +132 -51
- package/src/agents/global-npm-root.ts +58 -0
- package/src/agents/proactive-skills.ts +4 -1
- package/src/agents/runtime-agent-registry.ts +14 -11
- package/src/agents/skills.ts +42 -9
- package/src/api/delegation.ts +15 -0
- package/src/api/inspectors.ts +27 -0
- package/src/api/preflight.ts +7 -2
- package/src/extension/config.ts +12 -4
- package/src/extension/control-notices.ts +3 -0
- package/src/extension/doctor.ts +10 -4
- package/src/extension/fanout-child.ts +20 -3
- package/src/extension/herdr-pi-bridge.ts +2 -0
- package/src/extension/index.ts +168 -206
- package/src/extension/public-execution.ts +69 -35
- package/src/extension/reply-workflow-script.ts +58 -0
- package/src/extension/rpc.ts +39 -11
- package/src/extension/schemas.ts +47 -138
- package/src/extension/subagent-guide.ts +12 -4
- package/src/extension/tool-activation.ts +146 -0
- package/src/extension/tool-description.ts +62 -27
- package/src/extension/upgrade-notice.ts +40 -0
- package/src/inspectors/ghostty/plugin.ts +13 -1
- package/src/inspectors/plugins.ts +70 -3
- package/src/integrations/herdr-status.ts +19 -3
- package/src/intercom/intercom-bridge.ts +2 -0
- package/src/intercom/native-supervisor-channel.ts +26 -16
- package/src/intercom/result-intercom.ts +4 -0
- package/src/runs/background/active-async-capacity.ts +3 -25
- package/src/runs/background/async-execution.ts +60 -95
- package/src/runs/background/async-job-tracker.ts +91 -56
- package/src/runs/background/async-resume.ts +16 -8
- package/src/runs/background/async-retention.ts +46 -16
- package/src/runs/background/async-status.ts +2 -0
- package/src/runs/background/await-async-run.ts +76 -0
- package/src/runs/background/binary-bootstrap.ts +34 -6
- package/src/runs/background/chain-root-attachment.ts +4 -4
- package/src/runs/background/control-channel.ts +18 -2
- package/src/runs/background/fleet-view.ts +51 -7
- package/src/runs/background/notify.ts +98 -7
- package/src/runs/background/pid-namespace.ts +18 -0
- package/src/runs/background/process-terminal-candidate.ts +98 -0
- package/src/runs/background/process-terminal.ts +17 -96
- package/src/runs/background/result-watcher.ts +1 -1
- package/src/runs/background/retained-children.ts +3 -2
- package/src/runs/background/run-child-session.ts +20 -6
- package/src/runs/background/run-id-resolver.ts +10 -5
- package/src/runs/background/run-status.ts +16 -4
- package/src/runs/background/runner-aliases.ts +54 -16
- package/src/runs/background/runner-child-launch.ts +4 -2
- package/src/runs/background/runner-startup-failure.ts +56 -0
- package/src/runs/background/scheduled-runs.ts +5 -5
- package/src/runs/background/stale-run-reconciler.ts +19 -3
- package/src/runs/background/subagent-runner-bootstrap.ts +276 -0
- package/src/runs/background/subagent-runner.ts +111 -288
- package/src/runs/background/wait-tool.ts +2 -0
- package/src/runs/background/workflow-terminal-proof.ts +68 -0
- package/src/runs/foreground/async-stop-action.ts +17 -3
- package/src/runs/foreground/execution.ts +111 -139
- package/src/runs/foreground/prompt-audit.ts +3 -9
- package/src/runs/foreground/subagent-executor.ts +715 -258
- package/src/runs/shared/acceptance.ts +167 -68
- package/src/runs/shared/async-status-projection.ts +5 -0
- package/src/runs/shared/capability-ceiling.ts +4 -1
- package/src/runs/shared/child-hooks.ts +1 -16
- package/src/runs/shared/child-launch.ts +37 -16
- package/src/runs/shared/child-runtime-config.ts +3 -0
- package/src/runs/shared/child-session.ts +144 -8
- package/src/runs/shared/child-tool-plan.ts +38 -116
- package/src/runs/shared/dynamic-fanout.ts +1 -1
- package/src/runs/shared/external-cli-runner.ts +3 -1
- package/src/runs/shared/external-job-bridge.ts +54 -0
- package/src/runs/shared/git-environment.ts +29 -0
- package/src/runs/shared/mcp-config-sources.ts +5 -1
- package/src/runs/shared/mcp-direct-tool-allowlist.ts +104 -12
- package/src/runs/shared/mcp-direct-tool-grant.ts +22 -6
- package/src/runs/shared/model-resolution.ts +35 -10
- package/src/runs/shared/model-scope.ts +28 -9
- package/src/runs/shared/nested-events.ts +12 -0
- package/src/runs/shared/orca-progress-tabs.ts +3 -2
- package/src/runs/shared/parallel-utils.ts +4 -1
- package/src/runs/shared/pi-spawn.ts +1 -3
- package/src/runs/shared/single-output.ts +11 -2
- package/src/runs/shared/structured-output.ts +227 -7
- package/src/runs/shared/subagent-control.ts +2 -16
- package/src/runs/shared/subagent-prompt-runtime.ts +29 -5
- package/src/runs/shared/tool-availability.ts +2 -2
- package/src/runs/shared/tool-budget.ts +21 -0
- package/src/runs/shared/usage-reconciliation.ts +73 -0
- package/src/runs/shared/worktree.ts +36 -9
- package/src/shared/child-session-name.ts +4 -2
- package/src/shared/disabled-features.ts +123 -0
- package/src/shared/extension-context.ts +13 -0
- package/src/shared/fork-context.ts +11 -4
- package/src/shared/launch-contract.ts +1 -1
- package/src/shared/model-info.ts +9 -0
- package/src/shared/pruned-fork.ts +69 -56
- package/src/shared/settings.ts +1 -1
- package/src/shared/types.ts +73 -16
- package/src/slash/delegation-adapters.ts +25 -1
- package/src/slash/prompt-template-bridge.ts +18 -3
- package/src/slash/prompt-workflows.ts +12 -1
- package/src/slash/slash-commands.ts +17 -246
- package/src/slash/subagent-cost.ts +313 -0
- package/src/slash/subagents-admin.ts +4 -5
- package/src/tui/fleet-status.ts +38 -8
- package/src/tui/fleet.ts +21 -6
- package/src/tui/render.ts +166 -71
- package/src/tui/running-tone.ts +28 -0
- package/src/watchdog/diff-tool.ts +47 -12
- package/src/watchdog/permission-arbiter.ts +13 -15
- package/src/watchdog/register-child.ts +13 -5
- package/src/watchdog/register-main.ts +3 -3
- package/src/watchdog/review.ts +16 -16
- package/src/watchdog/runtime.ts +2 -1
- package/src/watchdog/turn-delta.ts +12 -6
- package/src/workflows/chat-progress.ts +2 -2
- package/src/workflows/scripted-workflow.ts +225 -59
- package/src/workflows/structured-workflow-scripts.ts +177 -0
- package/src/workflows/workflow-checklist.ts +6 -0
- package/src/workflows/workflow-child-summary.ts +4 -2
- package/src/workflows/workflow-receipt.ts +8 -2
- package/src/workflows/workflow-resources.ts +37 -12
- package/src/workflows/workflow-reuse.ts +120 -0
- package/src/workflows/workflow-revival.ts +123 -0
- package/src/workflows/workflow-settlement.ts +4 -1
- package/src/runs/shared/completion-evidence.ts +0 -89
- package/src/runs/shared/completion-guard.ts +0 -255
- package/src/runs/shared/llm-intent-arbiter.ts +0 -321
- package/src/runs/shared/task-intent.ts +0 -244
package/package.json
CHANGED
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "@xzzpig/pi-subagents",
|
|
3
|
-
"version": "0.
|
|
3
|
+
"version": "0.19.0",
|
|
4
4
|
"description": "Pi extension for single-agent delegation and scripted multi-agent workflows",
|
|
5
5
|
"author": "Nico Bailon",
|
|
6
6
|
"license": "MIT",
|
|
@@ -11,6 +11,7 @@
|
|
|
11
11
|
"./external-job-provider": "./src/api/external-job-provider.ts",
|
|
12
12
|
"./external-runs": "./src/api/external-runs.ts",
|
|
13
13
|
"./agents": "./src/api/agents.ts",
|
|
14
|
+
"./inspectors": "./src/api/inspectors.ts",
|
|
14
15
|
"./delegation": "./src/api/delegation.ts",
|
|
15
16
|
"./capability-ceiling": "./src/api/capability-ceiling.ts",
|
|
16
17
|
"./workflow-resources": "./src/api/workflow-resources.ts",
|
|
@@ -67,9 +68,10 @@
|
|
|
67
68
|
},
|
|
68
69
|
"peerDependencies": {
|
|
69
70
|
"@earendil-works/pi-agent-core": "*",
|
|
70
|
-
"@earendil-works/pi-ai": ">=0.
|
|
71
|
+
"@earendil-works/pi-ai": ">=1.0.0 <2",
|
|
71
72
|
"@earendil-works/pi-coding-agent": "*",
|
|
72
|
-
"@earendil-works/pi-tui": "*"
|
|
73
|
+
"@earendil-works/pi-tui": "*",
|
|
74
|
+
"typebox": "*"
|
|
73
75
|
},
|
|
74
76
|
"peerDependenciesMeta": {
|
|
75
77
|
"@earendil-works/pi-agent-core": {
|
|
@@ -83,25 +85,28 @@
|
|
|
83
85
|
},
|
|
84
86
|
"@earendil-works/pi-tui": {
|
|
85
87
|
"optional": true
|
|
88
|
+
},
|
|
89
|
+
"typebox": {
|
|
90
|
+
"optional": true
|
|
86
91
|
}
|
|
87
92
|
},
|
|
88
93
|
"dependencies": {
|
|
89
94
|
"@xzzpig/pi-components": "0.4.0",
|
|
90
95
|
"acorn": "8.18.0",
|
|
91
96
|
"jiti": "2.7.0",
|
|
92
|
-
"
|
|
93
|
-
"undici": "8.10.0",
|
|
97
|
+
"undici": "8.10.2",
|
|
94
98
|
"yaml": "2.8.3"
|
|
95
99
|
},
|
|
96
100
|
"devDependencies": {
|
|
97
|
-
"@earendil-works/pi-agent-core": "0.
|
|
98
|
-
"@earendil-works/pi-ai": "0.
|
|
99
|
-
"@earendil-works/pi-tui": "0.
|
|
101
|
+
"@earendil-works/pi-agent-core": "1.0.0",
|
|
102
|
+
"@earendil-works/pi-ai": "1.0.0",
|
|
103
|
+
"@earendil-works/pi-tui": "1.0.0",
|
|
100
104
|
"@oxlint/plugins": "1.80.0",
|
|
101
105
|
"@types/node": "24.13.3",
|
|
102
106
|
"oxlint": "1.80.0",
|
|
103
107
|
"typescript": "5.9.3",
|
|
104
|
-
"@earendil-works/pi-coding-agent": "file:./test/fixtures/pi-coding-agent-shim"
|
|
108
|
+
"@earendil-works/pi-coding-agent": "file:./test/fixtures/pi-coding-agent-shim",
|
|
109
|
+
"typebox": "1.3.27"
|
|
105
110
|
},
|
|
106
111
|
"publishConfig": {
|
|
107
112
|
"access": "public"
|
|
@@ -116,6 +121,7 @@
|
|
|
116
121
|
"test": "npm run test:unit",
|
|
117
122
|
"test:unit": "env -u PI_SUBAGENT_PARENT_SESSION -u PI_SESSION_ID -u PI_SESSION_FILE -u PI_CODING_AGENT -u PI_PROVIDER -u PI_MODEL -u PI_REASONING_LEVEL -u PI_SUBAGENT_EXTRA_AGENT_DIRS node --experimental-strip-types --import ./test/support/isolated-temp-root.mjs --test test/unit/*.test.ts",
|
|
118
123
|
"test:integration": "env -u PI_SUBAGENT_PARENT_SESSION -u PI_SESSION_ID -u PI_SESSION_FILE -u PI_CODING_AGENT -u PI_PROVIDER -u PI_MODEL -u PI_REASONING_LEVEL -u PI_SUBAGENT_EXTRA_AGENT_DIRS node --experimental-strip-types --import ./test/support/register-loader.mjs --test test/integration/*.test.ts",
|
|
124
|
+
"test:smoke:tool-activation": "env -u PI_SUBAGENT_PARENT_SESSION -u PI_SESSION_ID -u PI_SESSION_FILE -u PI_CODING_AGENT -u PI_PROVIDER -u PI_MODEL -u PI_REASONING_LEVEL -u PI_SUBAGENT_EXTRA_AGENT_DIRS node --experimental-strip-types --test test/smoke/tool-activation.test.ts",
|
|
119
125
|
"test:all": "npm run test:unit && npm run test:integration"
|
|
120
126
|
}
|
|
121
127
|
}
|
package/prompts/council.md
CHANGED
|
@@ -8,8 +8,11 @@ session, are the supervisor. You select the roster, curate cross-advisor packets
|
|
|
8
8
|
decide which feedback is valid, and write the final memo. Advisors do not talk
|
|
9
9
|
directly or see peer transcripts by default. This is not free-form agent chat.
|
|
10
10
|
|
|
11
|
-
Before you orchestrate,
|
|
12
|
-
`
|
|
11
|
+
Before you orchestrate, load the council protocol with
|
|
12
|
+
`subagent({ action: "guide", topic: "council" })`. If only `subagents_enable`
|
|
13
|
+
is available, call it first; `subagent` is available on the next request. The
|
|
14
|
+
guide returns the packaged council-mode skill and the references it asks you to
|
|
15
|
+
read, so it also works when Pi runs with `--no-skills`.
|
|
13
16
|
|
|
14
17
|
Parse the invocation yourself. The flags below are conventions, not runtime
|
|
15
18
|
options. Record a brief with the question, scope, non-goals, evidence targets,
|
|
@@ -48,7 +51,7 @@ path if the run is not resumable.
|
|
|
48
51
|
## Run the protocol
|
|
49
52
|
|
|
50
53
|
Use the canonical workflow, structured advisor contracts, aggregate pass receipts,
|
|
51
|
-
and memo requirements
|
|
54
|
+
and memo requirements from the council guide. Keep the parent as the
|
|
52
55
|
only synthesizer and decision maker. Do not introduce a chair advisor, peer chat,
|
|
53
56
|
or transcript sharing.
|
|
54
57
|
|
package/prompts/review-loop.md
CHANGED
|
@@ -8,7 +8,7 @@ Use the `subagent` tool. Keep the parent session as the loop controller and fina
|
|
|
8
8
|
|
|
9
9
|
Default to a maximum of 3 review rounds unless I specify a different cap. Count a review round each time fresh-context reviewers inspect the current diff after a worker pass. Stop early when reviewers find no P0 findings, no P1 fixes worth doing now, and no approved P2 notes that should be handled in this loop.
|
|
10
10
|
|
|
11
|
-
If the invocation includes an implementation request, first launch one async `worker` to implement the approved scope. If the current diff is already the target, start with review. The sequence can be launched up front
|
|
11
|
+
If the invocation includes an implementation request, first launch one async `worker` to implement the approved scope. If the current diff is already the target, start with review. The sequence can be launched up front as a workflow script (a ```` ```js workflow ```` block plus `subagent({ workflow: true })`) when it is already clear, or continued as follow-up single-agent runs after each async completion. For an initial workflow script, 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.
|
|
12
12
|
|
|
13
13
|
As a conservative orchestration policy, do not set a hard `toolBudget` or tight `usageBudget` on implementation or fix workers. 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.
|
|
14
14
|
|
package/runner-peer-loader.mjs
CHANGED
|
@@ -2,8 +2,6 @@ import { pathToFileURL } from "node:url";
|
|
|
2
2
|
|
|
3
3
|
let aliases = {};
|
|
4
4
|
let nativeRunner = false;
|
|
5
|
-
let compiledRunner = false;
|
|
6
|
-
let packageRootUrl;
|
|
7
5
|
const redirected = new Set([
|
|
8
6
|
"@earendil-works/pi-tui",
|
|
9
7
|
]);
|
|
@@ -11,14 +9,13 @@ const redirected = new Set([
|
|
|
11
9
|
export function initialize(data) {
|
|
12
10
|
aliases = data?.aliases ?? {};
|
|
13
11
|
nativeRunner = data?.nativeRunner === true;
|
|
14
|
-
compiledRunner = data?.compiledRunner === true;
|
|
15
|
-
packageRootUrl = data?.packageRootUrl;
|
|
16
12
|
}
|
|
17
13
|
|
|
18
14
|
export function resolve(specifier, context, nextResolve) {
|
|
19
|
-
const
|
|
20
|
-
if (
|
|
21
|
-
|
|
15
|
+
const alias = nativeRunner ? aliases[specifier] : redirected.has(specifier) && aliases[specifier];
|
|
16
|
+
if (alias) {
|
|
17
|
+
const target = pathToFileURL(alias).href;
|
|
18
|
+
return nativeRunner ? { url: target, shortCircuit: true } : nextResolve(target, context);
|
|
22
19
|
}
|
|
23
20
|
return nextResolve(specifier, context);
|
|
24
21
|
}
|
package/runner-peer-preload.mjs
CHANGED
|
@@ -5,9 +5,6 @@ import { pathToFileURL } from "node:url";
|
|
|
5
5
|
// pi-lens-ignore: unchecked-throwing-call-js
|
|
6
6
|
const aliases = JSON.parse(process.env.JITI_ALIAS ?? "{}");
|
|
7
7
|
const nativeRunner = process.env.PI_ASYNC_NATIVE_RUNNER === "1";
|
|
8
|
-
const compiledRunner = process.env.PI_ASYNC_COMPILED_RUNNER === "1";
|
|
9
|
-
// Pi's jiti loader owns aliases for external extensions; these hooks only supply peers to our compiled package.
|
|
10
|
-
const packageRootUrl = new URL("./", import.meta.url).href;
|
|
11
8
|
const redirected = new Set([
|
|
12
9
|
"@earendil-works/pi-tui",
|
|
13
10
|
]);
|
|
@@ -17,9 +14,10 @@ const redirected = new Set([
|
|
|
17
14
|
if (typeof nodeModule.registerHooks === "function") {
|
|
18
15
|
nodeModule.registerHooks({
|
|
19
16
|
resolve(specifier, context, nextResolve) {
|
|
20
|
-
const
|
|
21
|
-
if (
|
|
22
|
-
|
|
17
|
+
const alias = nativeRunner ? aliases[specifier] : redirected.has(specifier) && aliases[specifier];
|
|
18
|
+
if (alias) {
|
|
19
|
+
const target = pathToFileURL(alias).href;
|
|
20
|
+
return nativeRunner ? { url: target, shortCircuit: true } : nextResolve(target, context);
|
|
23
21
|
}
|
|
24
22
|
try {
|
|
25
23
|
return nextResolve(specifier, context);
|
|
@@ -31,6 +29,6 @@ if (typeof nodeModule.registerHooks === "function") {
|
|
|
31
29
|
});
|
|
32
30
|
} else {
|
|
33
31
|
nodeModule.register(new URL("./runner-peer-loader.mjs", import.meta.url), {
|
|
34
|
-
data: { aliases, nativeRunner
|
|
32
|
+
data: { aliases, nativeRunner },
|
|
35
33
|
});
|
|
36
34
|
}
|
|
@@ -32,7 +32,7 @@ Pass 1 is independent reports. Pass 2 is one cross-exam. Run Pass 3 only when `-
|
|
|
32
32
|
|
|
33
33
|
1. Write the council brief: question, scope, non-goals, evidence targets, roster, known advisor context modes, and pass cap.
|
|
34
34
|
2. Tell the user the roster, context modes, and pass cap.
|
|
35
|
-
3. Launch one async `
|
|
35
|
+
3. Launch one async workflow script (a ```` ```js workflow ```` block plus `subagent({ workflow: true, async: true })`) with `runs.all` for Pass 1. Use stable keys, `phase: "Council pass 1"`, concise labels, and `output: false` unless separate artifacts are useful. Set `context` only when the profile context is known or a fallback rule requires it.
|
|
36
36
|
4. Return one aggregate Pass 1 receipt. On completion, tell the user completion count, agreement count, dispute count, and whether Pass 2 is needed.
|
|
37
37
|
5. Synthesize the claim matrix in the parent: agreements, disputed claims, missing proof, owner decisions, and at most five material relay claims per advisor.
|
|
38
38
|
6. For Pass 2, tell the user which claims are relayed and why they matter. Resume each advisor with a curated challenge packet. A resume needs a retained run id and task; it excludes `agent` and rejects `gate`. Record each new run id; Pass 3 resumes those latest ids with new stable keys.
|
|
@@ -29,19 +29,26 @@ and their resolved `tools` allow `subagent`.
|
|
|
29
29
|
| Need | Use |
|
|
30
30
|
| --- | --- |
|
|
31
31
|
| One bounded task for one child | direct `{ agent, task }` |
|
|
32
|
-
| JavaScript control flow or data-dependent branching; sequence, fanout, retry, rolling fanout, or aggregation |
|
|
33
|
-
| A broad plan split into visible narrow stages per lane |
|
|
32
|
+
| JavaScript control flow or data-dependent branching; sequence, fanout, retry, rolling fanout, or aggregation | a workflow script with `runs.run(...)` / `runs.all(...)` |
|
|
33
|
+
| A broad plan split into visible narrow stages per lane | a workflow script with `runs.lanes([{ key, stages: [...] }])` |
|
|
34
34
|
| Independent worktree or repository lanes | `references/multi-lane-orchestration.md` |
|
|
35
35
|
| Council of advisors | `../council-mode/SKILL.md` |
|
|
36
36
|
| Management, status, steering, authoring, or inspection | `action` |
|
|
37
37
|
|
|
38
|
-
|
|
38
|
+
To launch a workflow script, write it as one ```` ```js workflow ```` fenced
|
|
39
|
+
block in your reply, then call `subagent({ workflow: true, ... })` in the same
|
|
40
|
+
reply. Use `workflow: "./path/to/script.js"` for a script file and
|
|
41
|
+
`workflow: "<name>"` for a named resource.
|
|
42
|
+
|
|
43
|
+
A workflow script is code-driven: `runs.run(...)` for keyed steps,
|
|
39
44
|
`runs.all([...])` for fanout, plain JavaScript for branching and aggregation.
|
|
40
45
|
Keep scripts portable: use top-level `await`, plain helpers, or explicit Promise
|
|
41
46
|
chains, not nested async helpers. Legacy top-level `chain` / `tasks` inputs and
|
|
42
|
-
durable `.chain.md` execution are inspection or migration material only
|
|
47
|
+
durable `.chain.md` execution are inspection or migration material only, except
|
|
48
|
+
that `disabledFeatures: ["workflow-scripts"]` replaces scripts with top-level
|
|
49
|
+
`chain` and `tasks` (see [configuration](../../docs/configuration.md#chain-and-tasks-without-workflow-scripts)).
|
|
43
50
|
|
|
44
|
-
Use `runs.lanes(...)` only inside a
|
|
51
|
+
Use `runs.lanes(...)` only inside a workflow script, not as a top-level mode,
|
|
45
52
|
when a broad, predeclared plan benefits from visible per-lane stages; otherwise
|
|
46
53
|
use ordinary `runs.run(...)` / `runs.all(...)`. See the [canonical staged-lane
|
|
47
54
|
example](../../docs/workflows.md#parallel-sequential-lanes). Keep assignments
|
|
@@ -101,6 +108,7 @@ For an authorized complex delegated workflow, read `prompting-and-roles.md` and
|
|
|
101
108
|
- Keep the parent on the ordinary strong default model. Route workers/scouts to a fast capable tier, serious reviews to a strong tier, and top reasoning to bounded read-only critique.
|
|
102
109
|
- Exact model names are deployment policy. Put them in user/project settings or profiles, not package guidance.
|
|
103
110
|
- Give every child a compact meta-prompt checklist: objective; repo/cwd/ref; authority/edit boundary; relevant files/contracts and constraints; success/acceptance criteria; validation; expected output/report; and stop/ask conditions. See `references/prompting-and-roles.md`.
|
|
111
|
+
- Before launching a writer for substantial mutation work, classify it as single-seam or multi-seam and partition multi-seam work across exclusive component owners, gates, and durable handoffs before an integration-only owner. See `references/multi-lane-orchestration.md`.
|
|
104
112
|
- For mutation work, use an isolated lane/worktree when isolation, overlap, or concurrent juggling matters; keep one writer per cwd/worktree. See `references/multi-lane-orchestration.md` for lane mechanics.
|
|
105
113
|
- Keep long/high-output validation out of chat: prefer `interactive_shell` dispatch/background monitors, bounded logs, or subagent-owned reports; return a concise summary plus report path unless same-turn output is required. Do not use `interactive_shell` as an implicit fallback for a failed `subagent` lane; see `references/execution-controls.md`.
|
|
106
114
|
- Treat subagent workflow, child launch, prompt runtime, extension load, and child tooling setup failures as lane infrastructure blockers. Stop, report the exact failure and run/worktree state, verify a clean worktree or capture a partial diff, and use only a clear same-protocol retry or an owner-approved execution-mode fallback.
|
|
@@ -6,10 +6,13 @@ This file is a detailed reference loaded from `skills/pi-subagents/SKILL.md`.
|
|
|
6
6
|
|
|
7
7
|
- **Explicit forking requires a persisted parent session.** If the current session
|
|
8
8
|
does not have a persisted session file or current leaf, explicit `context: "fork"`
|
|
9
|
-
fails. An agent-level `defaultContext: fork` is a preference: packaged `
|
|
10
|
-
|
|
9
|
+
fails. An agent-level `defaultContext: fork` is a preference: packaged `oracle`
|
|
10
|
+
and `advisor` fall back to `fresh` when those fork preconditions are not
|
|
11
11
|
met yet. Use `context: "fresh"` when you do not want a fork even after the parent
|
|
12
12
|
session exists.
|
|
13
|
+
- **Packaged workers start fresh.** `worker` defaults to fresh context so its brief,
|
|
14
|
+
not the parent's unfinished agenda, controls the implementation. Pass explicit
|
|
15
|
+
`context: "fork"` when inherited conversation history is required.
|
|
13
16
|
- **Forked runs inherit parent history.** They are branched threads, not fresh
|
|
14
17
|
filtered contexts. Use fresh context for adversarial reviewers unless the user explicitly asks for forked context.
|
|
15
18
|
- **Default subagent nesting depth is 2.** Deeper recursive delegation is blocked
|
|
@@ -31,8 +34,8 @@ For durable evidence, copy only the final summary to session memory, a PR body/c
|
|
|
31
34
|
|
|
32
35
|
## Best Practices
|
|
33
36
|
|
|
34
|
-
- Run subagents asynchronously by default; direct one-child execution is enough for one bounded task, while `
|
|
35
|
-
- For a predeclared broad plan split into visible narrow stages, use `runs.lanes([...])` inside
|
|
37
|
+
- Run subagents asynchronously by default; direct one-child execution is enough for one bounded task, while a workflow script (a ```` ```js workflow ```` block plus `subagent({ workflow: true })`) is the composition surface for JavaScript control flow and data-dependent branching. Use `async: false` only when the parent must block. See `references/execution-controls.md` → Async/background for wait semantics.
|
|
38
|
+
- For a predeclared broad plan split into visible narrow stages, use `runs.lanes([...])` inside a workflow script; use raw `runs.run(...)`/`runs.all(...)` for conditional or rolling flows. See [`execution-controls.md`](execution-controls.md#parallel-sequential-lanes).
|
|
36
39
|
- Keep one writer per cwd/worktree. Parallelize reading, review, and validation; concurrent writers need isolated worktrees. Give every child a cold-start packet with its goal, target/ref, authority, context, success criteria, validation, output, and stop rules.
|
|
37
40
|
- Keep tasks narrow and standalone; do not rely on issue numbers, broad globs, or supervisor round-trips to supply missing context.
|
|
38
41
|
- Keep authority with the parent. Escalate unapproved product, scope, architecture, merge, credential, or release decisions; checks, receipts, and review bots are evidence, not authority.
|
|
@@ -61,7 +64,7 @@ its overhead. Recipes select a shape; they do not authorize delegation:
|
|
|
61
64
|
|
|
62
65
|
## Error Handling
|
|
63
66
|
|
|
64
|
-
- **Unknown agent:** run `subagent({ action: "list" })`; check scope/precedence and author new orchestration
|
|
67
|
+
- **Unknown agent:** run `subagent({ action: "list" })`; check scope/precedence and author new orchestration as a workflow script, not legacy chains.
|
|
65
68
|
- **Setup, discovery, or intercom confusion:** run `subagent({ action: "doctor" })`.
|
|
66
69
|
- **Max subagent depth exceeded:** flatten the workflow or raise `maxSubagentDepth` in config.
|
|
67
70
|
- **Missing session file for a fork:** persist the parent session before using `context: "fork"`.
|
|
@@ -9,7 +9,7 @@ Agent files can live in:
|
|
|
9
9
|
- `.pi/agents/**/*.md` — canonical project scope
|
|
10
10
|
- legacy `.agents/**/*.md` — still read for compatibility, but `.pi/agents/` wins on conflicts
|
|
11
11
|
|
|
12
|
-
Saved chain files may still be discovered for management and existing durable run state, but they are not a public execution surface. Author new orchestration
|
|
12
|
+
Saved chain files may still be discovered for management and existing durable run state, but they are not a public execution surface. Author new orchestration as a workflow script.
|
|
13
13
|
|
|
14
14
|
Precedence is by parsed runtime name:
|
|
15
15
|
1. project scope
|
|
@@ -24,7 +24,7 @@ Project settings resolve from the nearest parent directory containing `.pi` or `
|
|
|
24
24
|
|
|
25
25
|
An agent may set `runner.type: external-cli` with a non-empty `command`, optional string `args`, and `promptDelivery: stdin` (the default). The command runs with `shell: false`, inherits the resolved cwd and environment, and receives the combined agent instructions and task through stdin. It must already be installed; pi-subagents adds no CLI dependency.
|
|
26
26
|
|
|
27
|
-
External CLI profiles are async-only and one-shot. They support lifecycle artifacts, stdout/stderr logs, timeout, and stop. Full stdout and stderr are retained in their log files, while the final stdout response and stderr error kept in memory are each limited to their last 64 KiB. They do not support native Pi child options such as model override, structured output, acceptance/agent contract, tool budgets, fast mode, fork context, skills, or native Pi tools unless the runner explicitly implements them. Foreground/clarify, steer/resume/interrupt-as-pause, nested subagents, and sessions are also unsupported.
|
|
27
|
+
A command-runner agent with a plain `command` (no adapter) is also how a classifier or scoring script becomes a typed workflow step: the prompt arrives on stdin, stdout is the child's `output`, and the script parses it. Keep `inheritProjectContext`, `inheritGlobalContext`, and `inheritSkills` off unless the command wants that text. External CLI profiles are async-only and one-shot. They support lifecycle artifacts, stdout/stderr logs, timeout, and stop. Full stdout and stderr are retained in their log files, while the final stdout response and stderr error kept in memory are each limited to their last 64 KiB. They do not support native Pi child options such as model override, structured output, acceptance/agent contract, tool budgets, fast mode, fork context, skills, or native Pi tools unless the runner explicitly implements them. Foreground/clarify, steer/resume/interrupt-as-pause, nested subagents, and sessions are also unsupported.
|
|
28
28
|
|
|
29
29
|
### External job profiles
|
|
30
30
|
|
|
@@ -32,7 +32,7 @@ An agent may set `runner.type: external-job` with a non-empty `provider` and opt
|
|
|
32
32
|
|
|
33
33
|
External job profiles are async-only. The provider owns the remote job and Pi owns the async run record. Status persists provider name, provider job id, prompt digest, provider options, handle/conversation URLs when supplied, result artifact path, last known state, and provider failure code/message. Recovery uses existing provider job metadata to call `reattach` and `result`; it refuses to redispatch a prompt when the persisted provider job does not match the prompt digest.
|
|
34
34
|
|
|
35
|
-
External job profiles do not support foreground/clarify, steer
|
|
35
|
+
External job profiles do not support foreground/clarify, live steer or native session resume, Pi models/tools/extensions/skills, tool budgets, structured output, native child permissions, or Pi child sessions. Completed external-job runs can use `action: "resume"` for provider follow-up when the registered provider exposes `followUp(input)`; running jobs must finish first, and providers without follow-up support fail closed with an update/reload message. Capacity conflicts fail closed and include the blocking provider job id when the provider supplies it.
|
|
36
36
|
|
|
37
37
|
### Single agent
|
|
38
38
|
|
|
@@ -45,16 +45,16 @@ subagent({
|
|
|
45
45
|
|
|
46
46
|
Use direct single-agent execution for one bounded task when no stable key,
|
|
47
47
|
branching, retained-child lookup, or aggregate workflow result is needed. Use a
|
|
48
|
-
|
|
48
|
+
workflow script when the parent needs JavaScript control flow or data-dependent
|
|
49
49
|
branching, or when the run is part of a larger coordinated wave or a later step
|
|
50
50
|
must resume it by key.
|
|
51
51
|
|
|
52
52
|
### Forked context
|
|
53
53
|
|
|
54
|
-
|
|
55
|
-
|
|
56
|
-
|
|
57
|
-
})
|
|
54
|
+
Write this block in the reply, then call `subagent({ workflow: true })` (see [Scripted workflows](#scripted-workflows)):
|
|
55
|
+
|
|
56
|
+
```js workflow
|
|
57
|
+
return runs.run("oracle-check", { agent: "oracle", task: "Review my current direction and challenge assumptions.", context: "fork" });
|
|
58
58
|
```
|
|
59
59
|
|
|
60
60
|
`context: "fork"` creates a branched child session from the current persisted
|
|
@@ -68,7 +68,7 @@ its resolved launch context as `[fresh]` or `[fork]`. Aggregate headers show
|
|
|
68
68
|
|
|
69
69
|
### Scripted workflows
|
|
70
70
|
|
|
71
|
-
|
|
71
|
+
A workflow script is the public composition surface when the parent needs
|
|
72
72
|
JavaScript control flow or data-dependent branching. Use
|
|
73
73
|
`runs.run(key, { agent, task, ... })` for keyed children, `runs.all([...])` for
|
|
74
74
|
parallel children, and ordinary JavaScript for sequence, filtering, retries,
|
|
@@ -80,17 +80,25 @@ workflow whenever the parent is starting a coordinated wave, such as multiple
|
|
|
80
80
|
reviews, review plus gate monitor, worker then monitor setup, cross-repo prep
|
|
81
81
|
lanes, or a fanout that the parent will consume together.
|
|
82
82
|
|
|
83
|
+
Write the script as one ```` ```js workflow ```` fenced block in the reply, then
|
|
84
|
+
call `subagent({ workflow: true, ... })` in the same reply. The block is plain
|
|
85
|
+
text, so it needs no JSON string escaping; a line containing only ```` ``` ````
|
|
86
|
+
(three or more backticks) ends it. A reply carries one block and one
|
|
87
|
+
`workflow: true` call. Use `workflow: "./path/to/script.js"` for a script file.
|
|
88
|
+
Later examples that show only a ```` ```js workflow ```` block run with
|
|
89
|
+
`subagent({ workflow: true })`.
|
|
90
|
+
|
|
91
|
+
```js workflow
|
|
92
|
+
const scan = await runs.run("scan", { label: "Map target behavior", agent: "scout", task: "Map the target" });
|
|
93
|
+
const reviews = await runs.all([
|
|
94
|
+
{ key: "correctness", label: "Review target correctness", agent: "reviewer", task: "Review correctness: " + scan.output },
|
|
95
|
+
{ key: "tests", label: "Review target test coverage", agent: "reviewer", task: "Review tests: " + scan.output }
|
|
96
|
+
]);
|
|
97
|
+
return reviews.map(result => result.output);
|
|
98
|
+
```
|
|
99
|
+
|
|
83
100
|
```js
|
|
84
|
-
subagent({
|
|
85
|
-
workflowScript: `
|
|
86
|
-
const scan = await runs.run("scan", { label: "Map target behavior", agent: "scout", task: "Map the target" });
|
|
87
|
-
const reviews = await runs.all([
|
|
88
|
-
{ key: "correctness", label: "Review target correctness", agent: "reviewer", task: "Review correctness: " + scan.output },
|
|
89
|
-
{ key: "tests", label: "Review target test coverage", agent: "reviewer", task: "Review tests: " + scan.output }
|
|
90
|
-
]);
|
|
91
|
-
return reviews.map(result => result.output);
|
|
92
|
-
`
|
|
93
|
-
})
|
|
101
|
+
subagent({ workflow: true, async: true })
|
|
94
102
|
```
|
|
95
103
|
|
|
96
104
|
Scripts run in a timed worker with only `runs.run`, `runs.all`, `runs.status`, `runs.ref/refs`, `emit`, captured `console`, and standard JavaScript. Pass explicit task text to `runs.run`. Mission-attached workflows also get `await state.get(key)` and `await state.set(key, value)` for durable JSON state shared across workflows on the same mission; `mission: false` workflows have no `state` global. Stable keys are required. Child launches follow ordinary single-agent execution controls. Give each child a distinct decision and output path when reports must outlive the workflow, then consume the aggregate workflow result before opening individual reports. Do not ask children to write `reports/...` or other repo-root scratch paths in task text.
|
|
@@ -99,9 +107,11 @@ If `runs.all` is missing in a running session, reload or update `pi-subagents` b
|
|
|
99
107
|
|
|
100
108
|
For one host-run verification command, pass `gate: "npm test"` on a `runs.run`/`runs.all` item (or at the top level as a workflow default). It is shorthand for verified acceptance with that single command: the runtime executes it on the host, records the result as evidence, and memoizes it per tracked workspace state and effective environment. `gate` cannot be combined with `acceptance`; use explicit `acceptance.verify` for multiple commands or custom criteria.
|
|
101
109
|
|
|
110
|
+
For a typed post-run check, pass the object form `gate: { command, output: "json", schema?, timeoutMs? }`. A passing command must print one JSON document (under 12,000 characters); the parsed value, validated against `schema` when given, becomes the child's `structuredOutput`, so a script can branch on `result.structuredOutput` and `runs.lanes` blocks on `verdict === "blocked"` without the parent reading the child's output. Pair it with `output` + `outputMode: "file-only"` so the command reads the saved file. Empty, non-JSON, or schema-invalid stdout fails the gate and rejects the run. Typed gates are never memoized. A typed gate cannot be combined with an `outputSchema` from the launch or the agent; the launch is rejected before any child starts. See the `tool-reference` guide, "Typed gates".
|
|
111
|
+
|
|
102
112
|
If omitted, acceptance is inferred from role, mode, and risk. Use `level: "checked"` for ordinary writer evidence and `level: "verified"` when the runtime should run explicit validation commands. Independent review is orthogonal: use `review: { required: true, agent: "reviewer" }`; reviewer/read-only calls omit `acceptance`. `review-required` means evidence passed but review is pending; `reviewed` means an independent review found no blockers. Never request `level: "reviewed"`; it is recognized only so preflight can return an actionable correction. Disable gates with `{ level: "none", reason: "..." }`; bare `"none"` is rejected and `false` is only a deprecated shorthand. Child-reported command success is evidence, not runtime verification.
|
|
103
113
|
|
|
104
|
-
Completed workflow children from this parent session stay addressable as retained children. `subagent({ action: "children.list" })` lists up to the last 10 with run ids and reports each row as `resumable` or `not resumable` with a reason. Resume only rows reported `resumable`. For a retained-child challenge, use `resume` instead of `steer` when the child is complete.
|
|
114
|
+
Completed workflow children from this parent session stay addressable as retained children. `subagent({ action: "children.list" })` lists up to the last 10 with run ids and reports each row as `resumable` or `not resumable` with a reason. This workflow-only roster is not an exhaustive list of direct native children. Resume only rows reported `resumable`. When the exact run id of an intended direct child is known, inspect it with `subagent({ action: "status", id: "<run-id>" })`; if status identifies the candidate, attempt `subagent({ action: "resume", id: "<run-id>", message: "..." })`. Resume performs the authoritative eligibility check and may reject the attempt. For a retained-child challenge, use `resume` instead of `steer` when the child is complete. Launch a same-role fallback challenge, labeled as fallback, only when no known candidate exists or resume rejects eligibility. A later workflow continues a resumable child with `runs.run(key, { resume: "<run-id>", task: "follow-up" })`. Inside a workflow script, awaiting that call waits for the revived child to finish and returns its completed output and new `runId`; top-level `{ action: "resume" }` remains detached. Pass explicit follow-up task text. Assign each returned child result back to the loop variable because every resume can return a new retained `runId`; always resume the latest returned id. `resume` and `agent` are mutually exclusive, the revived child keeps its stored agent/model/tool contract, and `gate` is rejected on retained resume items.
|
|
105
115
|
|
|
106
116
|
Each workflow key identifies one result lane: use a new stable workflow key for every distinct retained resume pass; same-key calls are reused only when launch parameters are identical, and incompatible parameters are rejected.
|
|
107
117
|
|
|
@@ -120,7 +130,7 @@ Keyed resume reads that one exact receipt and revalidates the retained run at la
|
|
|
120
130
|
### Parallel sequential lanes
|
|
121
131
|
|
|
122
132
|
For a broad plan with a known set of narrow, visible stages per lane, use
|
|
123
|
-
`runs.lanes(...)` inside a
|
|
133
|
+
`runs.lanes(...)` inside a workflow script; it is a nested helper, not a
|
|
124
134
|
top-level `subagent` mode. Give each lane and stage a stable key; give stage
|
|
125
135
|
items a short verb + behavior `label`, preserving explicit user labels. The first
|
|
126
136
|
stage from every lane is launched together, then later stages sequence per lane.
|
|
@@ -182,25 +192,26 @@ fleet. If `PI_SUBAGENT_WAIT_TOOL_ENABLED` disables blocking, direct waits return
|
|
|
182
192
|
immediately, but headless `agent_end` auto-drain still surfaces provider,
|
|
183
193
|
reconciliation, or timeout failures.
|
|
184
194
|
|
|
195
|
+
```js workflow
|
|
196
|
+
return runs.run("main", { agent: "worker", task: "Run the full test suite" });
|
|
197
|
+
```
|
|
198
|
+
|
|
185
199
|
```typescript
|
|
186
|
-
subagent({
|
|
187
|
-
workflowScript: `return runs.run("main", { agent: "worker", task: "Run the full test suite" })`,
|
|
188
|
-
async: true
|
|
189
|
-
})
|
|
200
|
+
subagent({ workflow: true, async: true })
|
|
190
201
|
```
|
|
191
202
|
|
|
192
|
-
File-only output mode works for
|
|
203
|
+
File-only output mode works for workflow script child launches. Use relative child output paths for scratch reports so the runtime stores them under the run artifact directory and age-based cleanup can remove them. Use absolute paths only for user-approved durable destinations, such as session memory, a docs folder outside the repo, or a known handoff path. For cross-codebase waves, include the repo slug or lane key in each output path so reports from different repositories cannot collide.
|
|
193
204
|
|
|
194
205
|
The `output` field is the API binding; a filename mentioned in task text is only instruction and does not override runtime routing. When a later workflow step or parent needs a durable file, set `output` on `runs.run`/`runs.all` and return the child’s `outputReference`, `outputPathMapping`, or `artifactPaths`; arbitrary literal strings returned by workflow JavaScript are not rewritten. Omitted child output may use a managed aggregate-derived sibling path.
|
|
195
206
|
|
|
196
207
|
For review fanout where the parent continues a local audit:
|
|
197
208
|
|
|
209
|
+
```js workflow
|
|
210
|
+
return runs.run("correctness", { agent: "reviewer", task: "Review the current diff for correctness issues. Do not edit files." });
|
|
211
|
+
```
|
|
212
|
+
|
|
198
213
|
```typescript
|
|
199
|
-
const run = subagent({
|
|
200
|
-
workflowScript: `return runs.run("correctness", { agent: "reviewer", task: "Review the current diff for correctness issues. Do not edit files." })`,
|
|
201
|
-
async: true,
|
|
202
|
-
context: "fresh"
|
|
203
|
-
})
|
|
214
|
+
const run = subagent({ workflow: true, async: true, context: "fresh" })
|
|
204
215
|
// Continue local inspection, then later call status with the returned id.
|
|
205
216
|
```
|
|
206
217
|
|
|
@@ -263,11 +274,11 @@ A cooperating terminal runtime can register read-only external records through `
|
|
|
263
274
|
Schedules are durable project records under `.pi/subagents/schedules/`. They are enabled by default; set `{ "scheduledRuns": { "enabled": false } }` in `~/.pi/agent/extensions/subagent/config.json` to disable them. Only schedule explicit work the user asked for. To keep schedules outside the project repository, set `{ "scheduledRuns": { "storeRoot": "~/.pi/subagent-schedules" } }` in the same config: `storeRoot` accepts an absolute path or a `~/`-prefixed path, and records land under `<storeRoot>/<sha256(path.resolve(cwd)) first 20 hex>/<scheduleId>/`.
|
|
264
275
|
|
|
265
276
|
```typescript
|
|
266
|
-
// One-shot reviewer
|
|
267
|
-
subagent({ action: "schedule.create", id: "evening-review", name: "Evening review", at: "+30m",
|
|
277
|
+
// One-shot reviewer, after a ```js workflow block with the script
|
|
278
|
+
subagent({ action: "schedule.create", id: "evening-review", name: "Evening review", at: "+30m", workflow: true })
|
|
268
279
|
|
|
269
|
-
// Fixed recurring workflow
|
|
270
|
-
subagent({ action: "schedule.create", id: "backlog", every: "6h", catchUp: "latest",
|
|
280
|
+
// Fixed recurring workflow from a script file
|
|
281
|
+
subagent({ action: "schedule.create", id: "backlog", every: "6h", catchUp: "latest", workflow: "./.pi/workflows/backlog.js" })
|
|
271
282
|
|
|
272
283
|
subagent({ action: "schedule.list" })
|
|
273
284
|
subagent({ action: "schedule.show", id: "backlog" })
|
|
@@ -279,7 +290,7 @@ subagent({ action: "schedule.run-due" })
|
|
|
279
290
|
subagent({ action: "schedule.delete", id: "backlog" })
|
|
280
291
|
```
|
|
281
292
|
|
|
282
|
-
`schedule.create` accepts exactly one target, `
|
|
293
|
+
`schedule.create` accepts exactly one target, a workflow script (`workflow: true` or a script path; the script text is stored at creation), and exactly one trigger (`at`, or a fixed `every` interval using `m`, `h`, `d`, or `w`). Runs always launch async with fresh context and no automatic mission; mission attachment is deferred from this first slice. `overlap` is currently `skip`; `catchUp` supports `latest` and `none`. `schedule.run-due` is the headless external-launcher seam. Calendar recurrence, cron, and the schedule inspector are deferred from this first safe slice. Definitions, bounded history, append-only events, and per-run receipts remain project-scoped across Pi sessions.
|
|
283
294
|
|
|
284
295
|
Humans can use `/subagents-doctor` for the same read-only report. It checks runtime paths, discovery counts, async support, current session context, and intercom bridge state.
|
|
285
296
|
|
|
@@ -306,17 +317,15 @@ A soft interrupt cancels the current child turn and leaves the run paused. It do
|
|
|
306
317
|
|
|
307
318
|
Per-run control thresholds can be overridden when a task legitimately runs without observable output for longer than usual:
|
|
308
319
|
|
|
309
|
-
```
|
|
310
|
-
|
|
311
|
-
|
|
312
|
-
|
|
313
|
-
|
|
314
|
-
|
|
315
|
-
|
|
316
|
-
|
|
317
|
-
|
|
318
|
-
})`
|
|
319
|
-
})
|
|
320
|
+
```js workflow
|
|
321
|
+
return runs.run("slow-tests", {
|
|
322
|
+
agent: "worker",
|
|
323
|
+
task: "Run the slow migration test suite",
|
|
324
|
+
control: {
|
|
325
|
+
needsAttentionAfterMs: 300000,
|
|
326
|
+
notifyOn: ["needs_attention"]
|
|
327
|
+
}
|
|
328
|
+
});
|
|
320
329
|
```
|
|
321
330
|
|
|
322
331
|
If the run already has an active intercom bridge target, needs-attention notifications can also prepare a compact intercom ping for the orchestrator. When a child route is available, the ping tells the orchestrator which agent needs attention and includes the exact `intercom({ action: "send", to: "..." })` target for a nudge. Do not invent a target or ask the child to self-report when no bridge exists.
|
|
@@ -398,7 +407,7 @@ Use `mission.update` while work runs to record decisions, artifacts, labels, sum
|
|
|
398
407
|
|
|
399
408
|
### Mission use policy
|
|
400
409
|
|
|
401
|
-
- **Keep the default.** Every ordinary
|
|
410
|
+
- **Keep the default.** Every ordinary workflow script launch with a task creates one enclosing mission automatically. All workflow children share it and never get their own. Do not add `mission: {...}` boilerplate. Pass it only to set the title, objective, labels, or to enable `goal` with `budget`.
|
|
402
411
|
- **Use `mission: false` for noise.** Use it for trivial one-shot lookups, scouts, disposable probes, and quick validation where a recovery record is noise. It removes the mission and the `state` global for the whole workflow, so do not use it for monitors or multi-workflow loops that coordinate through `state`. Scheduled runs already launch without automatic missions.
|
|
403
412
|
- **Use `missionId` for follow-up work.** Attach later work to an existing objective with `missionId`; attachment re-marks the mission active. `missionId` and `mission` are mutually exclusive. Explicit attachment fails before launch if the mission is missing, while automatic missions degrade to `details.missionWarning` without blocking the run.
|
|
404
413
|
- **Keep `state` small.** Mission `state` is JSON coordination across workflows on the same mission. Keys use the same format as run keys, values must be JSON, and the whole state file is capped at 256 KiB. Each `set` merges one key under a file lock. Put large content in artifact files and store paths in state. In goal missions, write `state.set("nextReadyAction", "...")` so the next idle-turn notice names the exact ready step.
|
|
@@ -411,15 +420,15 @@ After compaction, restart, or confusing history, recover from durable state firs
|
|
|
411
420
|
Routing rule:
|
|
412
421
|
- Same project: ordinary mission-backed subagents.
|
|
413
422
|
- Different project, small/bounded task: ordinary async subagent with explicit `cwd`, an authority boundary, and durable output.
|
|
414
|
-
- Several projects with independent work: one async
|
|
423
|
+
- Several projects with independent work: one async workflow script whose child keys include repo slugs and whose child calls set explicit `cwd`; keep publication and merge decisions serial per repo.
|
|
415
424
|
- Different project, substantial or long-running work: open a project-owned Herdr pane rooted there when a separate visible project session is useful, then give that project Pi session a narrow mission/result contract. Do not model it as ordinary child nesting, and do not expect existing headless runs to move into the pane.
|
|
416
425
|
|
|
417
426
|
Project panes run a separate Pi session from the target directory. Subagents launched inside that pane use that project's config, agents, skills, files, git state, and mission records. The pane binding lives under `<projectRoot>/.pi/subagents/project-panes/herdr.json`. When Pi runs inside Herdr, the owning pane reports compact active-work status and title suffixes, and the parent inline status counts opened project panes. Use Herdr itself or `project.status` / `project.close` for pane-level follow-up. For ordinary headless delegation to another repo, prefer explicit `cwd` first; reserve project panes for visible or persistent project ownership.
|
|
418
427
|
|
|
419
428
|
```typescript
|
|
420
429
|
subagent({ action: "mission.create", mission: { title: "Ship auth refresh", objective: "Implement and validate refresh handling" } })
|
|
421
|
-
subagent({
|
|
422
|
-
subagent({
|
|
430
|
+
subagent({ workflow: true, missionId: "<mission-id>" }) // after a ```js workflow block
|
|
431
|
+
subagent({ workflow: true, mission: false }) // after a ```js workflow block
|
|
423
432
|
subagent({ action: "mission.list", missionScope: "global" })
|
|
424
433
|
subagent({ action: "mission.resolve-decision", missionId: "<mission-id>", id: "<decision-id>", summary: "Settled: ship the v2 API; no schema freeze needed." })
|
|
425
434
|
subagent({ action: "project.open", cwd: "/path/to/other-repo", message: "Own this mission for the project and report back with receipts." })
|
|
@@ -433,16 +442,12 @@ subagent({ action: "mission.close", missionId: "<mission-id>", missionStatus: "c
|
|
|
433
442
|
When multiple agents might write concurrently, use worktrees instead of letting
|
|
434
443
|
them share one filesystem view.
|
|
435
444
|
|
|
436
|
-
```
|
|
437
|
-
|
|
438
|
-
|
|
439
|
-
|
|
440
|
-
|
|
441
|
-
|
|
442
|
-
]);
|
|
443
|
-
return results.map(({ key, artifactPaths }) => ({ key, artifactPaths }));
|
|
444
|
-
`
|
|
445
|
-
})
|
|
445
|
+
```js workflow
|
|
446
|
+
const results = await runs.all([
|
|
447
|
+
{ key: "feature-a", agent: "worker", task: "Implement feature A", worktree: true },
|
|
448
|
+
{ key: "feature-b", agent: "worker", task: "Implement feature B", worktree: true }
|
|
449
|
+
]);
|
|
450
|
+
return results.map(({ key, artifactPaths }) => ({ key, artifactPaths }));
|
|
446
451
|
```
|
|
447
452
|
|
|
448
453
|
`worktree: true` on a `runs.run` / `runs.all` item gives that child its own git
|
|
@@ -485,16 +490,14 @@ The intended oracle loop is:
|
|
|
485
490
|
4. the main agent decides what direction to approve
|
|
486
491
|
5. only then should `worker` implement
|
|
487
492
|
|
|
488
|
-
```
|
|
493
|
+
```js workflow
|
|
489
494
|
// Advisory review in a branched thread. Oracle defaults to forked context.
|
|
490
|
-
|
|
491
|
-
|
|
492
|
-
})
|
|
495
|
+
return runs.run("oracle-check", { agent: "oracle", task: "Review my current direction, challenge assumptions, and propose the best next move." });
|
|
496
|
+
```
|
|
493
497
|
|
|
494
|
-
|
|
495
|
-
|
|
496
|
-
|
|
497
|
-
})
|
|
498
|
+
```js workflow
|
|
499
|
+
// Implementation only after explicit approval, in a later reply. Worker defaults to fresh context.
|
|
500
|
+
return runs.run("implementation", { agent: "worker", task: "Implement the approved approach: ..." });
|
|
498
501
|
```
|
|
499
502
|
|
|
500
503
|
`oracle` is not a fresh-context reviewer in the Cognition article sense. It is
|
|
@@ -18,7 +18,7 @@ subagent({ action: "list" })
|
|
|
18
18
|
subagent({ action: "children.list" })
|
|
19
19
|
```
|
|
20
20
|
|
|
21
|
-
Lists up to the last 10 retained workflow children from this parent session with explicit `resumable` or `not resumable` rows. Resume only rows reported `resumable`.
|
|
21
|
+
Lists up to the last 10 retained workflow children from this parent session with explicit `resumable` or `not resumable` rows. This workflow-only roster is not an exhaustive list of direct native children. Resume only rows reported `resumable`. When the exact run id of an intended direct child is known, inspect it with `subagent({ action: "status", id: "<run-id>" })`; if status identifies the candidate, attempt `subagent({ action: "resume", id: "<run-id>", message: "..." })`. Resume performs the authoritative eligibility check and may reject the attempt. Continue one inside a workflow with `runs.run(key, { resume: "<run-id>", task: "follow-up" })`; each workflow key identifies one result lane, so use a new stable workflow key for every distinct retained resume pass. Same-key calls are reused only when launch parameters are identical, and incompatible parameters are rejected. The revived child keeps its stored agent, model, and tool contract. Start a same-role fallback challenge, labeled as fallback, only when no known candidate exists or resume rejects eligibility. `steer` with `mode: "follow_up"` only queues text for the next `resume` when the child has already completed.
|
|
22
22
|
|
|
23
23
|
### Refinement overlays
|
|
24
24
|
|
|
@@ -85,7 +85,7 @@ subagent({ action: "reset", agent: "reviewer" })
|
|
|
85
85
|
Use management actions when the system needs to create or edit subagents on
|
|
86
86
|
demand without dropping into raw file editing.
|
|
87
87
|
|
|
88
|
-
Management actions create or update user/project agent files. `config.name` is the local frontmatter name; optional `config.package` registers and looks up the runtime name as `{package}.{name}`. Use the dotted runtime name for `get`, `update`, `delete`, slash commands, and scripted workflow steps. For small agent changes such as a model swap, prefer `subagents.agentOverrides` in settings. Durable `.chain.md` definitions are legacy records, not a current authoring target; use `
|
|
88
|
+
Management actions create or update user/project agent files. `config.name` is the local frontmatter name; optional `config.package` registers and looks up the runtime name as `{package}.{name}`. Use the dotted runtime name for `get`, `update`, `delete`, slash commands, and scripted workflow steps. For small agent changes such as a model swap, prefer `subagents.agentOverrides` in settings. Durable `.chain.md` definitions are legacy records, not a current authoring target; use a workflow script file (`workflow: "./path.js"`) or `/prompt-workflow` for repeatable orchestration.
|
|
89
89
|
|
|
90
90
|
## Creating and Editing Agents by File
|
|
91
91
|
|
|
@@ -131,7 +131,7 @@ That is only a starting point. Omit `package` for the traditional unqualified ru
|
|
|
131
131
|
|
|
132
132
|
`acceptance` is a single-agent launch default. Use a scalar level such as `checked` or an inline/block YAML map such as `{ level: "none", reason: "lightweight lookup" }`. An explicit tool-call value wins; scripted workflow child acceptance remains configured on the `runs.run` or `runs.all` item. Management create/update accepts the same policy object, and `acceptance: ""` clears the frontmatter default (`false` remains the deprecated disabled-policy shorthand).
|
|
133
133
|
|
|
134
|
-
`acceptanceRole` is `read-only` or `writer` and controls automatic acceptance inference only.
|
|
134
|
+
`acceptanceRole` is `read-only` or `writer` and controls automatic acceptance inference only. The structured role is authoritative; task wording and agent names do not escalate acceptance. Omission uses lightweight attestation. The field does not grant or revoke tools. Management accepts `false` or an empty string to clear it.
|
|
135
135
|
|
|
136
136
|
`tools` is a strict child allowlist, not an extension loader. For a named extension tool, keep its registered name in `tools` and load its provider through normal Pi discovery, `extensions`, a path-like `tools` entry, or `subagentOnlyExtensions`. For example, pair `tools: read, fixture_search` with `subagentOnlyExtensions: ./tools/fixture-search.ts` when the provider should exist only in that agent's child sessions. The child now fails with the unavailable names and provider-loading guidance instead of silently continuing when a requested tool is absent; internal `structured_output` is allowed automatically when an output schema requires it.
|
|
137
137
|
|
|
@@ -158,4 +158,4 @@ Additional user prompt templates can delegate into `pi-subagents` through the na
|
|
|
158
158
|
|
|
159
159
|
Other Pi extensions can call `pi-subagents` through the in-process event bus. The RPC channels are `subagents:rpc:v1:ready`, `subagents:rpc:v1:request`, and per-request replies at `subagents:rpc:v1:reply:<requestId>`. Envelopes use `{ version: 1, requestId, method, params }`, and replies use `{ version: 1, requestId, success, data | error }`. `ping` advertises the exact process-local async completion event as `events.asyncComplete` for RPC-spawn consumers.
|
|
160
160
|
|
|
161
|
-
Methods: `ping`, `status`, `spawn`, `steer`, `interrupt`, `resume`, and `
|
|
161
|
+
Methods: `ping`, `status`, `manage`, `spawn`, `steer`, `interrupt`, `resume`, `stop`, and `cost`. `ping` capability metadata advertises optional projections: `capabilities.fleetStatus: { version: 1 }` adds bounded current-session `data.fleet` records (opaque reconciliation `key`, resolved `agent`, optional `role`, `model`, `effort`, caller-facing `goal`, `startedAt`, split `{ input, output, total }` tokens, plus `totalActive`/`omitted` overflow counts) to successful `status` replies; `capabilities.launchResolvedExtensions` advertises parent-resolved opaque launch-extension identifiers in status details; `capabilities.runtimeAcknowledgedExtensions` advertises the best-effort child-runtime acknowledgement projection fed by cooperating extensions emitting `subagent:acknowledge-extension`; `capabilities.cost: { version: 1 }` advertises parent-plus-child accounting as data. Foreground `details.results[]` rows carry a stable numeric `index`; correlate children by `(runId, index)` rather than row position. Consumers should read status/result artifacts and RPC projections instead of scraping terminal output and must ignore unknown fields. `spawn` accepts either `{ agent, task? }`, inline script text as `script`, or `workflow` with a script path (containing `/`) or a named workflow resource; `workflow: true` is rejected because RPC has no assistant reply to read. It is async-only and rejects management actions, `async: false`, or `clarify: true`. It reuses the normal executor, so discovery, validation, session attribution, configured spawn caps, child-safety depth, artifacts, and async status are shared with the `subagent` tool. `manage` accepts only the schedule actions advertised by `ping.capabilities.managementActions`. `status`, acknowledged async `steer`, and `interrupt` map to the normal control actions. RPC steer disables pause-and-revive recovery and advertises `capabilities.nonRecoveringSteer`, preserving the caller's authority over the exact spawned child. `resume` requires a target plus non-empty message and delegates to the package-owned revival path; it may set a caller-owned `file-only` output path but cannot override the persisted child model, tools, budgets, session ownership, or exclusive session lease. For retained-child workflows, resume only roster rows reported `resumable`; because that workflow-only roster is not exhaustive, inspect the exact status of a known direct-run candidate and attempt the authoritative resume when status identifies it. Start a labeled same-role fallback only when there is no known candidate or resume rejects eligibility. `stop` targets running async runs through the existing timeout control channel. `pi.events` is process-local, so separate Pi processes and child subagents need lifecycle artifact files or `pi-intercom` instead.
|