@xzzpig/pi-subagents 0.1.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 +1621 -0
- package/LICENSE +21 -0
- package/README.md +118 -0
- package/agents/delegate.md +14 -0
- package/agents/oracle.md +74 -0
- package/agents/researcher.md +52 -0
- package/agents/reviewer.md +79 -0
- package/agents/scout.md +50 -0
- package/agents/worker.md +58 -0
- package/index.ts +1 -0
- package/inspector-runner.mjs +11 -0
- package/install.mjs +93 -0
- package/package.json +105 -0
- package/prompts/gather-context-and-clarify.md +13 -0
- package/prompts/parallel-cleanup.md +59 -0
- package/prompts/parallel-research.md +50 -0
- package/prompts/parallel-review.md +54 -0
- package/prompts/review-loop.md +43 -0
- package/skills/pi-subagents/SKILL.md +41 -0
- package/skills/pi-subagents/references/constraints-and-recipes.md +251 -0
- package/skills/pi-subagents/references/execution-controls.md +428 -0
- package/skills/pi-subagents/references/management-authoring-rpc.md +161 -0
- package/skills/pi-subagents/references/prompting-and-roles.md +242 -0
- package/src/agents/agent-management.ts +1256 -0
- package/src/agents/agent-memory.ts +254 -0
- package/src/agents/agent-refinements.ts +624 -0
- package/src/agents/agent-scope.ts +6 -0
- package/src/agents/agent-selection.ts +25 -0
- package/src/agents/agent-serializer.ts +163 -0
- package/src/agents/agents.ts +1889 -0
- package/src/agents/chain-serializer.ts +280 -0
- package/src/agents/frontmatter.ts +149 -0
- package/src/agents/identity.ts +30 -0
- package/src/agents/proactive-skills.ts +194 -0
- package/src/agents/skills.ts +761 -0
- package/src/api/background-work.ts +197 -0
- package/src/api/capability-ceiling.ts +17 -0
- package/src/api/control-channel.ts +4 -0
- package/src/api/delegation.ts +119 -0
- package/src/api/external-runs.ts +129 -0
- package/src/api/intercom-bridge.ts +3 -0
- package/src/api/pi-args.ts +5 -0
- package/src/api/preflight.ts +403 -0
- package/src/api/shared-types.ts +19 -0
- package/src/extension/config.ts +76 -0
- package/src/extension/control-notices.ts +58 -0
- package/src/extension/doctor.ts +230 -0
- package/src/extension/fanout-child.ts +201 -0
- package/src/extension/index.ts +805 -0
- package/src/extension/public-execution.ts +71 -0
- package/src/extension/rpc.ts +653 -0
- package/src/extension/schemas.ts +375 -0
- package/src/extension/steering-notices.ts +35 -0
- package/src/extension/tool-description.ts +164 -0
- package/src/inspectors/herdr/actions.ts +229 -0
- package/src/inspectors/herdr/client.ts +130 -0
- package/src/inspectors/herdr/inspector-runner.ts +141 -0
- package/src/inspectors/herdr/project-panes.ts +154 -0
- package/src/integrations/herdr-status.ts +330 -0
- package/src/intercom/intercom-bridge.ts +187 -0
- package/src/intercom/native-supervisor-channel.ts +715 -0
- package/src/intercom/result-intercom.ts +421 -0
- package/src/missions/actions.ts +410 -0
- package/src/missions/goal-driver.ts +162 -0
- package/src/missions/lifecycle.ts +346 -0
- package/src/missions/store.ts +507 -0
- package/src/missions/types.ts +157 -0
- package/src/missions/workflow-state.ts +250 -0
- package/src/policy/authority.ts +46 -0
- package/src/profiles/profiles.ts +661 -0
- package/src/runs/background/async-execution.ts +1574 -0
- package/src/runs/background/async-job-tracker.ts +511 -0
- package/src/runs/background/async-resume.ts +539 -0
- package/src/runs/background/async-status.ts +542 -0
- package/src/runs/background/auto-drain.ts +67 -0
- package/src/runs/background/chain-append.ts +328 -0
- package/src/runs/background/chain-root-attachment.ts +199 -0
- package/src/runs/background/completion-batcher.ts +168 -0
- package/src/runs/background/completion-dedupe.ts +54 -0
- package/src/runs/background/control-channel.ts +692 -0
- package/src/runs/background/fleet-view.ts +540 -0
- package/src/runs/background/notify.ts +332 -0
- package/src/runs/background/parallel-groups.ts +45 -0
- package/src/runs/background/process-terminal.ts +280 -0
- package/src/runs/background/result-watcher.ts +414 -0
- package/src/runs/background/retained-children.ts +68 -0
- package/src/runs/background/run-id-resolver.ts +167 -0
- package/src/runs/background/run-status.ts +504 -0
- package/src/runs/background/scheduled-runs.ts +753 -0
- package/src/runs/background/stale-run-reconciler.ts +396 -0
- package/src/runs/background/steering.ts +239 -0
- package/src/runs/background/subagent-runner.ts +4718 -0
- package/src/runs/background/subagent-wait.ts +661 -0
- package/src/runs/background/top-level-async.ts +14 -0
- package/src/runs/background/wait-completions.ts +112 -0
- package/src/runs/background/wait-config.ts +36 -0
- package/src/runs/background/wait-subscriptions.ts +253 -0
- package/src/runs/background/wait-tool.ts +34 -0
- package/src/runs/foreground/async-steering-action.ts +256 -0
- package/src/runs/foreground/async-stop-action.ts +65 -0
- package/src/runs/foreground/chain-clarify.ts +1354 -0
- package/src/runs/foreground/chain-execution.ts +1527 -0
- package/src/runs/foreground/execution.ts +1868 -0
- package/src/runs/foreground/foreground-control.ts +132 -0
- package/src/runs/foreground/subagent-executor.ts +5532 -0
- package/src/runs/shared/acceptance.ts +1365 -0
- package/src/runs/shared/agent-contract.ts +38 -0
- package/src/runs/shared/capability-ceiling.ts +209 -0
- package/src/runs/shared/chain-outputs.ts +118 -0
- package/src/runs/shared/child-protocol.ts +401 -0
- package/src/runs/shared/completion-guard.ts +95 -0
- package/src/runs/shared/context-mode.ts +44 -0
- package/src/runs/shared/dynamic-fanout.ts +297 -0
- package/src/runs/shared/external-cli-runner.ts +130 -0
- package/src/runs/shared/long-running-guard.ts +220 -0
- package/src/runs/shared/mcp-direct-tool-allowlist.ts +406 -0
- package/src/runs/shared/model-fallback.ts +336 -0
- package/src/runs/shared/model-scope.ts +128 -0
- package/src/runs/shared/nested-events.ts +1076 -0
- package/src/runs/shared/nested-path.ts +52 -0
- package/src/runs/shared/nested-render.ts +123 -0
- package/src/runs/shared/parallel-handoff.ts +238 -0
- package/src/runs/shared/parallel-utils.ts +256 -0
- package/src/runs/shared/permissions.ts +95 -0
- package/src/runs/shared/pi-args.ts +808 -0
- package/src/runs/shared/pi-spawn.ts +163 -0
- package/src/runs/shared/process-signal.ts +19 -0
- package/src/runs/shared/run-history.ts +181 -0
- package/src/runs/shared/runtime-acknowledged-extensions.ts +71 -0
- package/src/runs/shared/session-lease.ts +299 -0
- package/src/runs/shared/single-output.ts +235 -0
- package/src/runs/shared/spawn-budget.ts +128 -0
- package/src/runs/shared/structured-output.ts +182 -0
- package/src/runs/shared/subagent-control.ts +231 -0
- package/src/runs/shared/subagent-prompt-runtime.ts +588 -0
- package/src/runs/shared/subagent-startup-retry.ts +104 -0
- package/src/runs/shared/task-intent.ts +181 -0
- package/src/runs/shared/tool-availability.ts +83 -0
- package/src/runs/shared/tool-budget.ts +80 -0
- package/src/runs/shared/turn-budget.ts +98 -0
- package/src/runs/shared/usage-budget.ts +65 -0
- package/src/runs/shared/workflow-graph.ts +231 -0
- package/src/runs/shared/worktree.ts +759 -0
- package/src/shared/accessible-dir.ts +47 -0
- package/src/shared/artifacts.ts +285 -0
- package/src/shared/atomic-json.ts +61 -0
- package/src/shared/child-transcript.ts +264 -0
- package/src/shared/file-coalescer.ts +40 -0
- package/src/shared/file-system-retry.ts +47 -0
- package/src/shared/fork-context.ts +213 -0
- package/src/shared/formatters.ts +133 -0
- package/src/shared/jsonl-writer.ts +81 -0
- package/src/shared/launch-contract.ts +124 -0
- package/src/shared/model-info.ts +81 -0
- package/src/shared/post-exit-stdio-guard.ts +85 -0
- package/src/shared/session-identity.ts +10 -0
- package/src/shared/session-tokens.ts +44 -0
- package/src/shared/settings.ts +501 -0
- package/src/shared/status-format.ts +55 -0
- package/src/shared/types.ts +2069 -0
- package/src/shared/utils.ts +613 -0
- package/src/slash/delegation-adapters.ts +434 -0
- package/src/slash/delegation-json.ts +108 -0
- package/src/slash/delegation-request.ts +166 -0
- package/src/slash/prompt-template-bridge.ts +383 -0
- package/src/slash/prompt-workflows.ts +300 -0
- package/src/slash/selector.ts +147 -0
- package/src/slash/slash-bridge.ts +192 -0
- package/src/slash/slash-commands.ts +994 -0
- package/src/slash/slash-live-state.ts +296 -0
- package/src/slash/subagents-admin.ts +432 -0
- package/src/tui/fleet-status.ts +564 -0
- package/src/tui/fleet-transcript.ts +577 -0
- package/src/tui/fleet.ts +879 -0
- package/src/tui/render-helpers.ts +80 -0
- package/src/tui/render.ts +2029 -0
- package/src/types/pi-runtime-compat.d.ts +8 -0
- package/src/watchdog/change-signature.ts +220 -0
- package/src/watchdog/child-status.ts +205 -0
- package/src/watchdog/emission-guard.ts +123 -0
- package/src/watchdog/lsp-diagnostics.ts +537 -0
- package/src/watchdog/model-selection.ts +167 -0
- package/src/watchdog/permission-arbiter.ts +145 -0
- package/src/watchdog/register-child.ts +117 -0
- package/src/watchdog/register-main.ts +440 -0
- package/src/watchdog/render.ts +54 -0
- package/src/watchdog/review.ts +302 -0
- package/src/watchdog/runtime.ts +868 -0
- package/src/watchdog/scope.ts +62 -0
- package/src/watchdog/settings.ts +568 -0
- package/src/watchdog/tool-actions.ts +155 -0
- package/src/watchdog/turn-delta.ts +161 -0
- package/src/watchdog/types.ts +198 -0
- package/src/watchdog/warning-format.ts +73 -0
- package/src/workflows/chat-progress.ts +140 -0
- package/src/workflows/scripted-workflow.ts +506 -0
|
@@ -0,0 +1,375 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* TypeBox schemas for subagent tool parameters
|
|
3
|
+
*/
|
|
4
|
+
|
|
5
|
+
import { Type } from "typebox";
|
|
6
|
+
|
|
7
|
+
function keepTopLevelParameterDescriptions<T>(schema: T): T {
|
|
8
|
+
return pruneNestedDescriptions(schema, []) as T;
|
|
9
|
+
}
|
|
10
|
+
|
|
11
|
+
function pruneNestedDescriptions(value: unknown, path: string[]): unknown {
|
|
12
|
+
if (!value || typeof value !== "object") return value;
|
|
13
|
+
|
|
14
|
+
const result = Array.isArray(value) ? [] : Object.create(Object.getPrototypeOf(value));
|
|
15
|
+
for (const key of Reflect.ownKeys(value)) {
|
|
16
|
+
const descriptor = Object.getOwnPropertyDescriptor(value, key);
|
|
17
|
+
if (!descriptor) continue;
|
|
18
|
+
if (key === "description" && !isTopLevelParameterDescription(path)) continue;
|
|
19
|
+
if ("value" in descriptor) {
|
|
20
|
+
const nextPath = typeof key === "string" ? [...path, key] : path;
|
|
21
|
+
descriptor.value = pruneNestedDescriptions(descriptor.value, nextPath);
|
|
22
|
+
}
|
|
23
|
+
Object.defineProperty(result, key, descriptor);
|
|
24
|
+
}
|
|
25
|
+
return result;
|
|
26
|
+
}
|
|
27
|
+
|
|
28
|
+
function isTopLevelParameterDescription(path: string[]): boolean {
|
|
29
|
+
return path.length === 2 && path[0] === "properties";
|
|
30
|
+
}
|
|
31
|
+
|
|
32
|
+
const SkillOverride = Type.Unsafe({
|
|
33
|
+
anyOf: [
|
|
34
|
+
{ type: "array", items: { type: "string" } },
|
|
35
|
+
{ type: "boolean" },
|
|
36
|
+
{ type: "string" },
|
|
37
|
+
],
|
|
38
|
+
description: "Skill name(s) to make available (comma-separated), array of strings, or boolean (false disables, true uses default)",
|
|
39
|
+
});
|
|
40
|
+
|
|
41
|
+
const OutputOverride = Type.Unsafe({
|
|
42
|
+
anyOf: [
|
|
43
|
+
{ type: "string" },
|
|
44
|
+
{ type: "boolean" },
|
|
45
|
+
],
|
|
46
|
+
description: "Output filename/path (string), or false to disable file output",
|
|
47
|
+
});
|
|
48
|
+
|
|
49
|
+
const OutputModeOverride = Type.String({
|
|
50
|
+
enum: ["inline", "file-only"],
|
|
51
|
+
description: "Return saved output inline (default) or only a concise file reference. file-only requires output to be a path.",
|
|
52
|
+
});
|
|
53
|
+
|
|
54
|
+
const ReadsOverride = Type.Unsafe({
|
|
55
|
+
anyOf: [
|
|
56
|
+
{ type: "array", items: { type: "string" } },
|
|
57
|
+
{ type: "boolean" },
|
|
58
|
+
],
|
|
59
|
+
description: "Files to read before running (array of filenames), or false to disable",
|
|
60
|
+
});
|
|
61
|
+
|
|
62
|
+
const JsonSchemaObject = Type.Unsafe({
|
|
63
|
+
type: "object",
|
|
64
|
+
additionalProperties: true,
|
|
65
|
+
description: "JSON Schema object for strict structured output. Non-object roots are rejected.",
|
|
66
|
+
});
|
|
67
|
+
|
|
68
|
+
const AcceptanceEvidenceKinds = [
|
|
69
|
+
"changed-files",
|
|
70
|
+
"tests-added",
|
|
71
|
+
"commands-run",
|
|
72
|
+
"validation-output",
|
|
73
|
+
"residual-risks",
|
|
74
|
+
"no-staged-files",
|
|
75
|
+
"diff-summary",
|
|
76
|
+
"review-findings",
|
|
77
|
+
"manual-notes",
|
|
78
|
+
];
|
|
79
|
+
|
|
80
|
+
const AcceptanceOverride = Type.Unsafe({
|
|
81
|
+
anyOf: [
|
|
82
|
+
{ type: "string", enum: ["auto", "attested", "checked"] },
|
|
83
|
+
{
|
|
84
|
+
type: "string",
|
|
85
|
+
enum: ["reviewed"],
|
|
86
|
+
deprecated: true,
|
|
87
|
+
description: "Invalid as an explicit policy. Recognized only so preflight can explain that reviewed is an achieved status.",
|
|
88
|
+
},
|
|
89
|
+
{ type: "boolean", enum: [false] },
|
|
90
|
+
{ type: "object", additionalProperties: true },
|
|
91
|
+
],
|
|
92
|
+
description: `Optional acceptance policy. For reviewer/read-only calls, omit acceptance. Example: { level: "checked", evidence: ["commands-run", "changed-files"] }. Supported evidence kinds: ${AcceptanceEvidenceKinds.join(", ")}. Evidence levels end at verified; use acceptance.review.required for review. Omitted means auto-inferred unless agentContract compatibility behavior is enabled.`,
|
|
93
|
+
});
|
|
94
|
+
|
|
95
|
+
const AgentContractOverride = Type.Object({
|
|
96
|
+
version: Type.Integer({ enum: [1], description: "Enable compatibility behavior for this run/child." }),
|
|
97
|
+
}, { additionalProperties: false, description: "Compatibility behavior. Omit for the default behavior." });
|
|
98
|
+
|
|
99
|
+
const ChainGateOverride = Type.String({
|
|
100
|
+
enum: ["execution", "acceptance"],
|
|
101
|
+
description: "For chain steps with agentContract, choose whether the chain advances on execution success or acceptance success. Defaults to execution.",
|
|
102
|
+
});
|
|
103
|
+
|
|
104
|
+
const TurnBudgetOverride = Type.Object({
|
|
105
|
+
maxTurns: Type.Integer({ minimum: 1 }),
|
|
106
|
+
graceTurns: Type.Optional(Type.Integer({ minimum: 0 })),
|
|
107
|
+
}, { additionalProperties: false, description: "Optional assistant-turn budget. At maxTurns the child is asked to wrap up; after graceTurns additional assistant turns it is aborted and partial output is returned." });
|
|
108
|
+
|
|
109
|
+
const ToolBudgetBlock = Type.Unsafe({
|
|
110
|
+
anyOf: [
|
|
111
|
+
{ type: "array", minItems: 1, items: { type: "string", minLength: 1 } },
|
|
112
|
+
{ type: "string", enum: ["*"] },
|
|
113
|
+
],
|
|
114
|
+
});
|
|
115
|
+
|
|
116
|
+
const ToolBudgetOverride = Type.Object({
|
|
117
|
+
soft: Type.Optional(Type.Integer({ minimum: 1 })),
|
|
118
|
+
hard: Type.Integer({ minimum: 1 }),
|
|
119
|
+
block: Type.Optional(ToolBudgetBlock),
|
|
120
|
+
}, { additionalProperties: false, description: "Optional child tool-call budget. soft nudges the child; after hard, block tools (default read/grep/find/ls, or '*' for all tools) are blocked so the child can finalize." });
|
|
121
|
+
|
|
122
|
+
const UsageBudgetLimitOverride = Type.Object({
|
|
123
|
+
soft: Type.Optional(Type.Number({ exclusiveMinimum: 0 })),
|
|
124
|
+
hard: Type.Number({ exclusiveMinimum: 0 }),
|
|
125
|
+
}, { additionalProperties: false });
|
|
126
|
+
|
|
127
|
+
const UsageBudgetOverride = Type.Object({
|
|
128
|
+
tokens: Type.Optional(UsageBudgetLimitOverride),
|
|
129
|
+
costUsd: Type.Optional(UsageBudgetLimitOverride),
|
|
130
|
+
}, { additionalProperties: false, description: "Optional root-only reported-usage budget. Hard limits prevent future child launches; running children are not stopped." });
|
|
131
|
+
|
|
132
|
+
// Parallel task item (within a parallel step)
|
|
133
|
+
export const ParallelTaskSchema = Type.Object({
|
|
134
|
+
agent: Type.String(),
|
|
135
|
+
task: Type.Optional(Type.String({ description: "Task template with {task}, {previous}, {chain_dir} variables. Defaults to {previous}." })),
|
|
136
|
+
phase: Type.Optional(Type.String({ description: "Optional phase/group label for status and graph rendering." })),
|
|
137
|
+
label: Type.Optional(Type.String({ description: "Optional user-facing label for this parallel task." })),
|
|
138
|
+
as: Type.Optional(Type.String({ description: "Optional safe identifier used as {outputs.name} in later chain steps." })),
|
|
139
|
+
outputSchema: Type.Optional(JsonSchemaObject),
|
|
140
|
+
cwd: Type.Optional(Type.String()),
|
|
141
|
+
count: Type.Optional(Type.Integer({ minimum: 1, description: "Repeat this parallel task N times with the same settings." })),
|
|
142
|
+
output: Type.Optional(OutputOverride),
|
|
143
|
+
outputMode: Type.Optional(OutputModeOverride),
|
|
144
|
+
reads: Type.Optional(ReadsOverride),
|
|
145
|
+
progress: Type.Optional(Type.Boolean({ description: "Enable progress.md tracking in {chain_dir}" })),
|
|
146
|
+
skill: Type.Optional(SkillOverride),
|
|
147
|
+
model: Type.Optional(Type.String({ description: "Override model for this task" })),
|
|
148
|
+
toolBudget: Type.Optional(ToolBudgetOverride),
|
|
149
|
+
acceptance: Type.Optional(AcceptanceOverride),
|
|
150
|
+
agentContract: Type.Optional(AgentContractOverride),
|
|
151
|
+
gateOn: Type.Optional(ChainGateOverride),
|
|
152
|
+
});
|
|
153
|
+
|
|
154
|
+
export const DynamicExpandSchema = Type.Object({
|
|
155
|
+
from: Type.Object({
|
|
156
|
+
output: Type.String({ description: "Prior named structured output to expand from." }),
|
|
157
|
+
path: Type.String({ description: "JSON Pointer into the structured output, e.g. /items." }),
|
|
158
|
+
}, { additionalProperties: false }),
|
|
159
|
+
item: Type.Optional(Type.String({ description: "Template variable name for each item. Defaults to item." })),
|
|
160
|
+
key: Type.Optional(Type.String({ description: "JSON Pointer relative to each item for stable child ids." })),
|
|
161
|
+
maxItems: Type.Optional(Type.Integer({ minimum: 0, description: "Required fanout bound unless configured globally." })),
|
|
162
|
+
onEmpty: Type.Optional(Type.String({ enum: ["skip", "fail"], description: "Empty input behavior. Defaults to skip." })),
|
|
163
|
+
}, { additionalProperties: false });
|
|
164
|
+
|
|
165
|
+
export const DynamicParallelTemplateSchema = Type.Object({
|
|
166
|
+
agent: Type.String(),
|
|
167
|
+
task: Type.Optional(Type.String({ description: "Task template with {item}, {item.path}, {task}, {previous}, {chain_dir}, and {outputs.name} variables." })),
|
|
168
|
+
phase: Type.Optional(Type.String({ description: "Optional phase/group label for status and graph rendering." })),
|
|
169
|
+
label: Type.Optional(Type.String({ description: "Optional user-facing label; item templates are supported." })),
|
|
170
|
+
outputSchema: Type.Optional(JsonSchemaObject),
|
|
171
|
+
cwd: Type.Optional(Type.String()),
|
|
172
|
+
output: Type.Optional(OutputOverride),
|
|
173
|
+
outputMode: Type.Optional(OutputModeOverride),
|
|
174
|
+
reads: Type.Optional(ReadsOverride),
|
|
175
|
+
progress: Type.Optional(Type.Boolean({ description: "Enable progress.md tracking in {chain_dir}" })),
|
|
176
|
+
skill: Type.Optional(SkillOverride),
|
|
177
|
+
model: Type.Optional(Type.String({ description: "Override model for this task" })),
|
|
178
|
+
toolBudget: Type.Optional(ToolBudgetOverride),
|
|
179
|
+
acceptance: Type.Optional(AcceptanceOverride),
|
|
180
|
+
agentContract: Type.Optional(AgentContractOverride),
|
|
181
|
+
gateOn: Type.Optional(ChainGateOverride),
|
|
182
|
+
}, { additionalProperties: false });
|
|
183
|
+
|
|
184
|
+
export const DynamicCollectSchema = Type.Object({
|
|
185
|
+
as: Type.String({ description: "Safe output name for the ordered collected result array." }),
|
|
186
|
+
outputSchema: Type.Optional(JsonSchemaObject),
|
|
187
|
+
}, { additionalProperties: false });
|
|
188
|
+
|
|
189
|
+
// Flattened so chain steps do not need an object-shape anyOf/oneOf union.
|
|
190
|
+
export const ChainItem = Type.Object({
|
|
191
|
+
checkpoint: Type.Optional(Type.String({ description: "Approval checkpoint name. Pauses the chain without launching a child until approve-checkpoint or reject-checkpoint is called." })),
|
|
192
|
+
message: Type.Optional(Type.String({ description: "Optional approval message shown while the checkpoint is paused." })),
|
|
193
|
+
agent: Type.Optional(Type.String({ description: "Sequential step agent name" })),
|
|
194
|
+
task: Type.Optional(Type.String({
|
|
195
|
+
description: "Task template with variables: {task}=original request, {previous}=prior step's text response, {chain_dir}=shared folder, {outputs.name}=prior named output. Required for first step, defaults to '{previous}' for subsequent steps."
|
|
196
|
+
})),
|
|
197
|
+
phase: Type.Optional(Type.String({ description: "Optional phase/group label for status and graph rendering." })),
|
|
198
|
+
label: Type.Optional(Type.String({ description: "Optional user-facing label for this chain step." })),
|
|
199
|
+
as: Type.Optional(Type.String({ description: "Optional safe identifier used as {outputs.name} in later chain steps." })),
|
|
200
|
+
outputSchema: Type.Optional(JsonSchemaObject),
|
|
201
|
+
cwd: Type.Optional(Type.String()),
|
|
202
|
+
output: Type.Optional(OutputOverride),
|
|
203
|
+
outputMode: Type.Optional(OutputModeOverride),
|
|
204
|
+
reads: Type.Optional(ReadsOverride),
|
|
205
|
+
progress: Type.Optional(Type.Boolean({ description: "Enable progress.md tracking in {chain_dir}" })),
|
|
206
|
+
skill: Type.Optional(SkillOverride),
|
|
207
|
+
model: Type.Optional(Type.String({ description: "Override model for this step" })),
|
|
208
|
+
toolBudget: Type.Optional(ToolBudgetOverride),
|
|
209
|
+
acceptance: Type.Optional(AcceptanceOverride),
|
|
210
|
+
agentContract: Type.Optional(AgentContractOverride),
|
|
211
|
+
gateOn: Type.Optional(ChainGateOverride),
|
|
212
|
+
parallel: Type.Optional(Type.Unsafe({
|
|
213
|
+
anyOf: [
|
|
214
|
+
Type.Array(ParallelTaskSchema, { minItems: 1, description: "Tasks to run in parallel" }),
|
|
215
|
+
DynamicParallelTemplateSchema,
|
|
216
|
+
],
|
|
217
|
+
description: "Static parallel tasks array, or a single dynamic fanout child template when expand/collect are present.",
|
|
218
|
+
})),
|
|
219
|
+
expand: Type.Optional(DynamicExpandSchema),
|
|
220
|
+
collect: Type.Optional(DynamicCollectSchema),
|
|
221
|
+
concurrency: Type.Optional(Type.Number({ description: "Max concurrent tasks (default: 4)" })),
|
|
222
|
+
failFast: Type.Optional(Type.Boolean({ description: "Stop on first failure (default: false)" })),
|
|
223
|
+
worktree: Type.Optional(Type.Boolean({
|
|
224
|
+
description: "Create isolated git worktrees for each parallel task."
|
|
225
|
+
})),
|
|
226
|
+
}, {
|
|
227
|
+
description: "Chain step: use {agent, task?, ...} for sequential, {parallel: [...]} for static concurrent execution, {expand, parallel: {...}, collect} for dynamic fanout, or {checkpoint: name, message?} for an approval pause.",
|
|
228
|
+
additionalProperties: false,
|
|
229
|
+
});
|
|
230
|
+
|
|
231
|
+
// Runtime mission handlers validate these untrusted nested objects loudly. Keeping
|
|
232
|
+
// their provider schema shallow avoids repeating a full durable-record schema in
|
|
233
|
+
// every tool request.
|
|
234
|
+
const MissionLaunchOverride = Type.Unsafe({
|
|
235
|
+
anyOf: [
|
|
236
|
+
{ type: "object", additionalProperties: true },
|
|
237
|
+
{ type: "boolean", enum: [false] },
|
|
238
|
+
],
|
|
239
|
+
});
|
|
240
|
+
const MissionUpdateOverride = Type.Unsafe({ type: "object", additionalProperties: true });
|
|
241
|
+
|
|
242
|
+
const ControlOverrides = Type.Object({
|
|
243
|
+
enabled: Type.Optional(Type.Boolean({ description: "Enable/disable subagent control attention tracking for this run" })),
|
|
244
|
+
needsAttentionAfterMs: Type.Optional(Type.Integer({ minimum: 1, description: "No-observed-activity window before a run needs attention" })),
|
|
245
|
+
activeNoticeAfterMs: Type.Optional(Type.Integer({ minimum: 1, description: "Active-long-running notice threshold by elapsed ms (default: 240000)" })),
|
|
246
|
+
activeNoticeAfterTurns: Type.Optional(Type.Integer({ minimum: 1, description: "Optional active-long-running notice threshold by assistant turns (disabled by default)" })),
|
|
247
|
+
activeNoticeAfterTokens: Type.Optional(Type.Integer({ minimum: 1, description: "Optional active-long-running notice threshold by total tokens (disabled by default)" })),
|
|
248
|
+
failedToolAttemptsBeforeAttention: Type.Optional(Type.Integer({ minimum: 1, description: "Consecutive mutating-tool failures before escalating to needs_attention (default: 3)" })),
|
|
249
|
+
notifyOn: Type.Optional(Type.Array(Type.String({ enum: ["active_long_running", "needs_attention"] }), {
|
|
250
|
+
description: "Control event types that should notify the parent/orchestrator. Defaults to active_long_running and needs_attention.",
|
|
251
|
+
})),
|
|
252
|
+
notifyChannels: Type.Optional(Type.Array(Type.String({ enum: ["event", "async", "intercom"] }), {
|
|
253
|
+
description: "Notification channels to use when available. Defaults to event, async, and intercom.",
|
|
254
|
+
})),
|
|
255
|
+
});
|
|
256
|
+
|
|
257
|
+
const SubagentParamsSchema = Type.Object({
|
|
258
|
+
agent: Type.Optional(Type.String({ description: "Agent target for management actions such as get, update, delete, and models." })),
|
|
259
|
+
resume: Type.Optional(Type.String({ description: "Retained child run id for a workflowScript runs.run/runs.all item. Mutually exclusive with agent; task supplies the follow-up." })),
|
|
260
|
+
// Management action (when present, tool operates in management mode)
|
|
261
|
+
action: Type.Optional(Type.String({ minLength: 1,
|
|
262
|
+
description: "Optional management/control action. Omit this field for workflowScript execution; use it only for management/control actions."
|
|
263
|
+
})),
|
|
264
|
+
name: Type.Optional(Type.String({ description: "Human-readable name for action='schedule.create'." })),
|
|
265
|
+
id: Type.Optional(Type.String({
|
|
266
|
+
description: "Run id or prefix for status, interrupt, stop, resume, steer, append-step, approve-checkpoint, reject-checkpoint, or mission.attach-run."
|
|
267
|
+
})),
|
|
268
|
+
runId: Type.Optional(Type.String({
|
|
269
|
+
description: "Target run ID for interrupt, stop, resume, steer, append-step, approve-checkpoint, reject-checkpoint, or mission.attach-run. Prefer id for new calls."
|
|
270
|
+
})),
|
|
271
|
+
dir: Type.Optional(Type.String({
|
|
272
|
+
description: "Async run directory for action='status', action='stop', action='resume', or action='steer'."
|
|
273
|
+
})),
|
|
274
|
+
handoffPath: Type.Optional(Type.String({ description: "worktree.discard manifest." })),
|
|
275
|
+
index: Type.Optional(Type.Integer({ minimum: 0, description: "Zero-based child index for actions that target a specific child or transcript." })),
|
|
276
|
+
view: Type.Optional(Type.String({
|
|
277
|
+
enum: ["fleet", "transcript"],
|
|
278
|
+
description: "Optional status view. Use view='fleet' for a read-only active foreground/async fleet surface, or view='transcript' with id/dir (and optional index) to tail a run transcript.",
|
|
279
|
+
})),
|
|
280
|
+
lines: Type.Optional(Type.Integer({ minimum: 1, maximum: 500, description: "Maximum transcript lines for action='status', view='transcript'. Defaults to 80." })),
|
|
281
|
+
message: Type.Optional(Type.String({ description: "Follow-up message for resume, live guidance for steer, or optional startup prompt for project.open." })),
|
|
282
|
+
mode: Type.Optional(Type.String({ enum: ["steer", "follow_up", "auto"], description: "Delivery mode for action='steer'. steer interrupts at the next safe point (default), follow_up waits for the next turn boundary, and auto follows up mid-turn but delivers immediately between turns." })),
|
|
283
|
+
steeringRecovery: Type.Optional(Type.Boolean({ description: "For action='steer', allow pause-and-revive recovery after a missed acknowledgment. Defaults true for direct tool calls in steer mode; extension RPC steering forces false so callers retain exact child ownership." })),
|
|
284
|
+
additional: Type.Optional(Type.Integer({ minimum: 1, description: "Positive launches to add with action='grant-spawn-budget'. Root interactive parent with native user confirmation only; total grants cannot exceed the original configured cap." })),
|
|
285
|
+
scope: Type.Optional(Type.String({ enum: ["session", "user", "project"], description: "Scope for action='watchdog.configure'. Defaults to session to avoid persistent settings writes unless user/project is explicit." })),
|
|
286
|
+
target: Type.Optional(Type.String({ enum: ["main", "children", "child"], description: "Target for watchdog actions." })),
|
|
287
|
+
focus: Type.Optional(Type.Boolean({ description: "Focus the new Herdr pane for inspector.open or project.open." })),
|
|
288
|
+
thinking: Type.Optional(Type.Unsafe({ anyOf: [{ type: "string" }, { type: "boolean", enum: [false] }], description: "Thinking level for action='watchdog.configure' (off/minimal/low/medium/high/xhigh/max, inherit, or false for off)." })),
|
|
289
|
+
schedule: Type.Optional(Type.String({ deprecated: true, description: "Removed one-shot schedule field. Use action='schedule.create' with at." })),
|
|
290
|
+
scheduleName: Type.Optional(Type.String({ deprecated: true, description: "Removed schedule display field. Use name." })),
|
|
291
|
+
at: Type.Optional(Type.String({ description: "One-shot trigger for action='schedule.create': a relative delay such as '+10m' or an ISO timestamp with timezone." })),
|
|
292
|
+
every: Type.Optional(Type.String({ description: "Fixed recurring interval for action='schedule.create', such as '30m', '6h', '2d', or '2w'." })),
|
|
293
|
+
on: Type.Optional(Type.Unsafe({ anyOf: [{ type: "string" }, { type: "integer" }], description: "Calendar selector reserved for a later schedule slice." })),
|
|
294
|
+
timezone: Type.Optional(Type.String({ description: "IANA timezone reserved for a later calendar schedule slice." })),
|
|
295
|
+
overlap: Type.Optional(Type.String({ enum: ["skip"], description: "Overlap policy. This slice supports skip only." })),
|
|
296
|
+
catchUp: Type.Optional(Type.String({ enum: ["none", "latest"], description: "Missed occurrence policy for recurring schedules. Defaults to latest." })),
|
|
297
|
+
missionId: Type.Optional(Type.String({ description: "Mission id." })),
|
|
298
|
+
mission: Type.Optional(Type.Unsafe({ ...MissionLaunchOverride, description: "Mission object, or false for no mission. Use objective for intent; goal:true with budget.tokens enables turn-end continuation notices." })),
|
|
299
|
+
missionUpdate: Type.Optional(Type.Unsafe({ ...MissionUpdateOverride, description: "Mission update: objective, goal false or {paused:boolean}, budget, summary, labels, decisions, artifacts, or delivery receipts." })),
|
|
300
|
+
missionStatus: Type.Optional(Type.String({ description: "Mission status." })),
|
|
301
|
+
missionScope: Type.Optional(Type.String({ description: "Mission list scope: project (default) or global pointer index." })),
|
|
302
|
+
runMode: Type.Optional(Type.String({ description: "Attached run mode." })),
|
|
303
|
+
runStatus: Type.Optional(Type.String({ description: "Attached run status." })),
|
|
304
|
+
summary: Type.Optional(Type.String({ description: "Mission close summary." })),
|
|
305
|
+
// Chain identifier for management (can't reuse 'chain' — that's the execution array)
|
|
306
|
+
chainName: Type.Optional(Type.String({
|
|
307
|
+
description: "Chain name for get/update/delete management actions"
|
|
308
|
+
})),
|
|
309
|
+
// Agent/chain configuration for create/update (nested to avoid conflicts with execution fields)
|
|
310
|
+
config: Type.Optional(Type.Unsafe({
|
|
311
|
+
anyOf: [
|
|
312
|
+
{ type: "object", additionalProperties: true },
|
|
313
|
+
{ type: "string" },
|
|
314
|
+
],
|
|
315
|
+
description: "Agent/chain config for create/update. Object or JSON string; presence of steps creates a chain."
|
|
316
|
+
})),
|
|
317
|
+
workflowScript: Type.Optional(Type.String({ minLength: 1, description: "Trusted inline JavaScript statement body. Starts async by default; pass async:false for a small foreground run. Use explicit return for output. Use await runs.run(key, {agent, task, worktree?, gate?}) or runs.run(key, {resume, task}), runs.all([...]), runs.status(id), runs.ref(s), emit(value), console, and return. Mission workflows also have async state.get(key) and state.set(key, JSONValue). Use ordinary JavaScript loops, branches, awaits, and arrays to mix sequential and parallel phases dynamically. Set worktree:true at workflow or child level for a separate managed worktree; child fields override workflow defaults. gate is one host-run command and cannot be combined with acceptance. runs.run accepts one child only. No filesystem, shell, Pi tools, or host globals." })),
|
|
318
|
+
chatProgress: Type.Optional(Type.String({ enum: ["auto", "off", "live-card"], description: "WorkflowScript chat progress projection. auto shows a live in-chat card only for watched foreground workflows in the same Git repository; it is off otherwise." })),
|
|
319
|
+
worktree: Type.Optional(Type.Boolean({ description: "Managed child isolation. true gives each workflow child a separate git worktree; an individual runs.run/runs.all item can override a workflow default with worktree:false." })),
|
|
320
|
+
step: Type.Optional(Type.Unsafe({ ...ChainItem, description: "One chain step for action='append-step' only. Not an execution mode." })),
|
|
321
|
+
context: Type.Optional(Type.String({
|
|
322
|
+
enum: ["fresh", "fork"],
|
|
323
|
+
description: "'fresh' or 'fork' to branch from parent session. Explicit context overrides every child in the invocation. If omitted, each requested agent uses its own defaultContext; agents without defaultContext: 'fork' run fresh.",
|
|
324
|
+
})),
|
|
325
|
+
async: Type.Optional(Type.Boolean({ description: "Run in background (default: false, or per config)" })),
|
|
326
|
+
timeoutMs: Type.Optional(Type.Integer({ minimum: 1, description: "Optional timeout for foreground and async/background runs. Foreground workflows default to 30m; async workflows have no default timeout. Alias maxRuntimeMs." })),
|
|
327
|
+
maxRuntimeMs: Type.Optional(Type.Integer({ minimum: 1, description: "Alias timeoutMs for foreground and async/background runs. Foreground workflows default to 30m; async workflows have no default timeout." })),
|
|
328
|
+
turnBudget: Type.Optional(TurnBudgetOverride),
|
|
329
|
+
toolBudget: Type.Optional(ToolBudgetOverride),
|
|
330
|
+
usageBudget: Type.Optional(UsageBudgetOverride),
|
|
331
|
+
agentScope: Type.Optional(Type.String({ description: "Agent discovery scope: 'user', 'project', or 'both' (default: 'both'; project wins on name collisions)" })),
|
|
332
|
+
cwd: Type.Optional(Type.String({ description: "Execution cwd, or target project directory for project.open/status/close." })),
|
|
333
|
+
artifacts: Type.Optional(Type.Boolean({ description: "Write debug artifacts (default: true)" })),
|
|
334
|
+
includeProgress: Type.Optional(Type.Boolean({ description: "Include full progress in result (default: false)" })),
|
|
335
|
+
share: Type.Optional(Type.Boolean({ description: "Upload session to GitHub Gist for sharing (default: false)" })),
|
|
336
|
+
sessionDir: Type.Optional(
|
|
337
|
+
Type.String({ description: "Directory to store session logs (default: temp; enables sessions even if share=false)" }),
|
|
338
|
+
),
|
|
339
|
+
control: Type.Optional(ControlOverrides),
|
|
340
|
+
// Workflow defaults forwarded to each runs.run/runs.all child unless overridden there.
|
|
341
|
+
output: Type.Optional(Type.Unsafe({
|
|
342
|
+
anyOf: [
|
|
343
|
+
{ type: "string" },
|
|
344
|
+
{ type: "boolean" },
|
|
345
|
+
],
|
|
346
|
+
description: "Default child output file (string), or false to disable. Relative paths resolve against cwd.",
|
|
347
|
+
})),
|
|
348
|
+
outputMode: Type.Optional(OutputModeOverride),
|
|
349
|
+
skill: Type.Optional(SkillOverride),
|
|
350
|
+
model: Type.Optional(Type.String({ description: "Default child model override (e.g. 'anthropic/claude-sonnet-4')" })),
|
|
351
|
+
outputSchema: Type.Optional(JsonSchemaObject),
|
|
352
|
+
agentContract: Type.Optional(AgentContractOverride),
|
|
353
|
+
acceptance: Type.Optional(AcceptanceOverride),
|
|
354
|
+
gate: Type.Optional(Type.String({ minLength: 1, description: "Host gate command. Cannot be combined with acceptance." })),
|
|
355
|
+
});
|
|
356
|
+
|
|
357
|
+
export const SubagentParams = keepTopLevelParameterDescriptions(SubagentParamsSchema);
|
|
358
|
+
|
|
359
|
+
const SubagentWaitParamsSchema = Type.Object({
|
|
360
|
+
id: Type.Optional(Type.String({
|
|
361
|
+
description: "Async run or remembered detached foreground run id/prefix to wait for one specific run. Omit to wait across every active async run started in this session.",
|
|
362
|
+
})),
|
|
363
|
+
nonBlocking: Type.Optional(Type.Boolean({
|
|
364
|
+
description: "When true, resolve id to one exact run, persist a wake subscription, and return immediately. The originating session is woken on completion, failure, attention, reconciliation failure, or timeout. Requires id and cannot be combined with all.",
|
|
365
|
+
})),
|
|
366
|
+
all: Type.Optional(Type.Boolean({
|
|
367
|
+
description: "Wait for ALL active runs to finish. Default false: return as soon as the first run finishes, so a fleet manager can spawn a replacement and wait again. Ignored when id targets a single run.",
|
|
368
|
+
})),
|
|
369
|
+
timeoutMs: Type.Optional(Type.Integer({
|
|
370
|
+
minimum: 1,
|
|
371
|
+
description: "Give up waiting after this many milliseconds (the runs keep going regardless). Defaults to 1800000 (30 minutes).",
|
|
372
|
+
})),
|
|
373
|
+
});
|
|
374
|
+
|
|
375
|
+
export const SubagentWaitParams = keepTopLevelParameterDescriptions(SubagentWaitParamsSchema);
|
|
@@ -0,0 +1,35 @@
|
|
|
1
|
+
import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
|
|
2
|
+
import type { SteeringNotice, SubagentState } from "../shared/types.ts";
|
|
3
|
+
|
|
4
|
+
export const SUBAGENT_STEERING_MESSAGE_TYPE = "subagent_steering_notice";
|
|
5
|
+
|
|
6
|
+
export interface SubagentSteeringMessageDetails extends SteeringNotice {
|
|
7
|
+
source?: "async";
|
|
8
|
+
asyncDir?: string;
|
|
9
|
+
noticeText?: string;
|
|
10
|
+
}
|
|
11
|
+
|
|
12
|
+
export function formatSteeringNotice(details: Pick<SubagentSteeringMessageDetails, "runId" | "requestId" | "state" | "message">): string {
|
|
13
|
+
return [
|
|
14
|
+
`Subagent steering ${details.state}: ${details.runId}`,
|
|
15
|
+
`Request: ${details.requestId}`,
|
|
16
|
+
details.message,
|
|
17
|
+
"Inspect the run status before sending another correction.",
|
|
18
|
+
].join("\n");
|
|
19
|
+
}
|
|
20
|
+
|
|
21
|
+
export function handleSubagentSteeringNotice(input: {
|
|
22
|
+
pi: Pick<ExtensionAPI, "sendMessage">;
|
|
23
|
+
state: SubagentState;
|
|
24
|
+
details: SubagentSteeringMessageDetails;
|
|
25
|
+
}): void {
|
|
26
|
+
if (!input.details || (input.details.state !== "failed" && input.details.state !== "partial" && input.details.state !== "recovered")) return;
|
|
27
|
+
if (!input.state.currentSessionId || input.details.currentSessionId !== input.state.currentSessionId) return;
|
|
28
|
+
const noticeText = input.details.noticeText ?? formatSteeringNotice(input.details);
|
|
29
|
+
input.pi.sendMessage({
|
|
30
|
+
customType: SUBAGENT_STEERING_MESSAGE_TYPE,
|
|
31
|
+
content: noticeText,
|
|
32
|
+
display: true,
|
|
33
|
+
details: { ...input.details, noticeText },
|
|
34
|
+
}, { triggerTurn: true });
|
|
35
|
+
}
|
|
@@ -0,0 +1,164 @@
|
|
|
1
|
+
import * as fs from "node:fs";
|
|
2
|
+
import * as path from "node:path";
|
|
3
|
+
import type { ExtensionConfig, ToolDescriptionMode } from "../shared/types.ts";
|
|
4
|
+
import { getAgentDir, getProjectConfigDir } from "../shared/utils.ts";
|
|
5
|
+
|
|
6
|
+
const CUSTOM_TOOL_DESCRIPTION_FILE = "subagent-tool-description.md";
|
|
7
|
+
const CUSTOM_TOOL_DESCRIPTION_MAX_BYTES = 50 * 1024;
|
|
8
|
+
|
|
9
|
+
export const SUBAGENT_SAFETY_GUIDANCE = `SAFETY-CRITICAL SUBAGENT GUIDANCE:
|
|
10
|
+
• Use { action: "list" } before execution and only run executable/non-disabled agents.
|
|
11
|
+
• Keep execution and management separate: omit action for workflowScript execution; use action only for management/control.
|
|
12
|
+
• Async/background runs are the default. Use async:false only when a blocking foreground result is needed. Do not sleep or poll status just to wait; use subagent_wait only when the current request must finish in this turn.
|
|
13
|
+
• Ordinary child subagents are not orchestrators. Only explicitly configured fanout children may use the child-safe subagent tool, still bounded by depth/session limits.
|
|
14
|
+
• Keep one writer for the same cwd/worktree. Use fresh-context read-only reviewers for independent review, then have the parent synthesize and apply fixes.
|
|
15
|
+
• Async runs expose asyncId/asyncDir with status.json, events.jsonl, output logs, and status via { action: "status", id }. Include output paths and residual risks when reporting results.`;
|
|
16
|
+
|
|
17
|
+
export const FULL_SUBAGENT_TOOL_DESCRIPTION = `Run subagents only through { workflowScript }; omit action. Use action only for management/control actions.
|
|
18
|
+
|
|
19
|
+
EXECUTION:
|
|
20
|
+
• Before executing, use { action: "list" } and run only executable/non-disabled configured agents.
|
|
21
|
+
• WORKFLOW SCRIPT: { workflowScript: "return runs.run('main', {agent:'worker', task:'...'})" }. Every execution is a workflow. Use stable-key runs.run for one child and runs.all for parallel children; ordinary JavaScript provides sequence, branching, filtering, retries, and aggregation. workflowScript is an ordinary JavaScript statement body, so use an explicit return for a useful result. Scripts start asynchronously by default; pass async:false only for a small foreground run. Same-repo foreground workflows default to a live in-chat card; set chatProgress to auto, off, or live-card to control that projection. Workflow-level child controls default onto each runs.run launch, and explicit child fields override them. Use {action:"children.list"} to list up to 10 completed retained children from this parent session, then continue one with runs.run(key, {resume:"run-id", task:"follow-up"}); resume and agent are mutually exclusive, and resume keeps the stored agent/model/tool contract. For repository mutation lanes, set worktree:true on the workflow or individual runs.run/runs.all item for managed isolation; each parallel child gets a separate worktree and handoff artifact. A workflow usageBudget is enforced once across the workflow. Available globals are runs.run, runs.all, runs.status, runs.ref/refs, emit, console, and standard JavaScript only. Workflows get async state.get(key) and state.set(key, JSONValue) through their automatic or explicit mission; mission:false workflows do not have a state global. Scripts cannot access filesystem, shell, arbitrary Pi tools, or host globals.
|
|
22
|
+
• Sequential example: { workflowScript: "const a = await runs.run('analyze', {agent:'agent-a', task:'Analyze the request'}); return (await runs.run('plan', {agent:'agent-b', task:'Plan from: '+a.output})).output" }
|
|
23
|
+
• Parallel example: { workflowScript: "const [a,b] = await runs.all([{key:'correctness',agent:'agent-a',task:'Review correctness'},{key:'tests',agent:'agent-b',task:'Review tests'}]); return {correctness:a.output,tests:b.output}" }
|
|
24
|
+
• Optional context is "fresh" or "fork". timeoutMs/maxRuntimeMs apply to foreground and async workflows; foreground workflows default to 30 minutes and async workflows have no default timeout. Omit acceptance for reviewer/read-only calls; evidence levels end at verified, and acceptance.review.required requests independent writer review.
|
|
25
|
+
• Durable mission attachment is automatic by default. Use missionId to attach an existing mission, mission:{...} to override auto-create, or mission:false for ephemeral work.
|
|
26
|
+
|
|
27
|
+
MANAGEMENT / CONTROL (use action; omit execution fields):
|
|
28
|
+
• list, get, models, children.list, create, update, delete, eject, disable, enable, reset, doctor, grant-spawn-budget, worktree.discard, refine/refine.show/refine.rollback, mission.create/list/show/update/attach-run/close, inspector.open/status/close, project.open/status/close, and watchdog actions remain available.
|
|
29
|
+
• status, interrupt, stop, resume, and steer manage live or persisted runs. Use status view:"fleet" for an overview or view:"transcript" with id and optional index to tail output.
|
|
30
|
+
• { action: "append-step", id: "...", step: {agent:"agent-c", task:"Use {previous}"} } appends one step to an already-running durable legacy chain. step is control-only, not an execution mode.
|
|
31
|
+
• approve-checkpoint and reject-checkpoint decide a paused durable legacy chain checkpoint.
|
|
32
|
+
• Create durable project schedules with { action:"schedule.create", id?, name?, at:"+10m" | ISO, workflowScript:"return runs.run('main', {agent:'worker', task:'...'})" } or { every:"6h", workflowScript:"..." }. Manage them with schedule.list/show/history/pause/resume/run/run-due/delete. This first slice supports fixed intervals; calendar schedules and schedule mission attachment are deferred.
|
|
33
|
+
|
|
34
|
+
${SUBAGENT_SAFETY_GUIDANCE}`;
|
|
35
|
+
|
|
36
|
+
export const COMPACT_SUBAGENT_TOOL_DESCRIPTION = `Run subagents only through { workflowScript }; omit action. Use action only for management/control actions.
|
|
37
|
+
|
|
38
|
+
EXECUTE:
|
|
39
|
+
• Call { action:"list" } first and use only executable/non-disabled agents.
|
|
40
|
+
• SCRIPT {workflowScript:"return runs.run('main', {agent:'worker', task:'...'})"}. Use stable-key runs.run for one child and runs.all for parallel work. Use {action:"children.list"} for the last 10 retained children in this parent session, then runs.run(key,{resume:"run-id",task:"follow-up"}) to continue one with its stored contract. Workflows get async state.get/state.set through their automatic or explicit mission; mission:false does not. Scripts are ordinary JavaScript statement bodies; use explicit return for a useful result. Use JavaScript for sequence, branching, retries, and aggregation. For repository mutation lanes, use worktree:true on the workflow or runs.run/runs.all item for managed isolation. Scripts start async by default; async:false is the foreground escape hatch and auto-enables a same-repo live chat card unless chatProgress is off.
|
|
41
|
+
• Example: {workflowScript:"const [a,b]=await runs.all([{key:'a',agent:'agent-a',task:'Implement A',worktree:true},{key:'b',agent:'agent-b',task:'Implement B',worktree:true}]); return [a.output,b.output]"}
|
|
42
|
+
• context can be fresh or fork. timeoutMs/maxRuntimeMs apply to foreground and async workflows; foreground workflows default to 30 minutes and async workflows have no default timeout. Omit acceptance for reviewer/read-only calls.
|
|
43
|
+
|
|
44
|
+
MANAGE / CONTROL:
|
|
45
|
+
• Use action without execution fields for list/get/models/authoring, refine/refine.show/refine.rollback, mission, watchdog, status, interrupt, stop, resume, steer, script-only scheduling, diagnostics, and other management actions.
|
|
46
|
+
• append-step uses step:{...} only for an already-running durable legacy chain; step is not an execution mode.
|
|
47
|
+
|
|
48
|
+
ASYNC / SAFETY:
|
|
49
|
+
• Omitted async detaches background work. Do not sleep or poll merely to wait; use subagent_wait only when this turn must receive results.
|
|
50
|
+
• Ordinary children are not orchestrators. Keep one writer per cwd/worktree and use fresh read-only reviewers for independent checks.
|
|
51
|
+
• Status and artifacts live under asyncId/asyncDir with status.json, events.jsonl, output logs, and {action:"status",id:"..."}.`;
|
|
52
|
+
|
|
53
|
+
|
|
54
|
+
function isToolDescriptionMode(value: unknown): value is ToolDescriptionMode {
|
|
55
|
+
return value === "full" || value === "compact" || value === "custom";
|
|
56
|
+
}
|
|
57
|
+
|
|
58
|
+
function warn(options: ToolDescriptionOptions | undefined, message: string): void {
|
|
59
|
+
(options?.warn ?? console.warn)(`[pi-subagents] ${message}`);
|
|
60
|
+
}
|
|
61
|
+
|
|
62
|
+
export interface ToolDescriptionOptions {
|
|
63
|
+
cwd?: string;
|
|
64
|
+
agentDir?: string;
|
|
65
|
+
warn?: (message: string) => void;
|
|
66
|
+
}
|
|
67
|
+
|
|
68
|
+
export function resolveToolDescriptionMode(config: Pick<ExtensionConfig, "toolDescriptionMode">, options?: ToolDescriptionOptions): ToolDescriptionMode {
|
|
69
|
+
const mode = config.toolDescriptionMode;
|
|
70
|
+
if (mode === undefined) return "full";
|
|
71
|
+
if (isToolDescriptionMode(mode)) return mode;
|
|
72
|
+
warn(options, `Ignoring invalid toolDescriptionMode ${JSON.stringify(mode)}; expected "full", "compact", or "custom".`);
|
|
73
|
+
return "full";
|
|
74
|
+
}
|
|
75
|
+
|
|
76
|
+
function customDescriptionPaths(options?: ToolDescriptionOptions): string[] {
|
|
77
|
+
const cwd = options?.cwd ?? process.cwd();
|
|
78
|
+
const agentDir = options?.agentDir ?? getAgentDir();
|
|
79
|
+
return [
|
|
80
|
+
path.join(getProjectConfigDir(cwd), CUSTOM_TOOL_DESCRIPTION_FILE),
|
|
81
|
+
path.join(agentDir, CUSTOM_TOOL_DESCRIPTION_FILE),
|
|
82
|
+
];
|
|
83
|
+
}
|
|
84
|
+
|
|
85
|
+
function renderCustomTemplate(template: string, options?: ToolDescriptionOptions): string {
|
|
86
|
+
const cwd = options?.cwd ?? process.cwd();
|
|
87
|
+
const agentDir = options?.agentDir ?? getAgentDir();
|
|
88
|
+
const projectConfigDir = getProjectConfigDir(cwd);
|
|
89
|
+
const variables: Record<string, () => string> = {
|
|
90
|
+
fullDescription: () => FULL_SUBAGENT_TOOL_DESCRIPTION,
|
|
91
|
+
full: () => FULL_SUBAGENT_TOOL_DESCRIPTION,
|
|
92
|
+
compactDescription: () => COMPACT_SUBAGENT_TOOL_DESCRIPTION,
|
|
93
|
+
compact: () => COMPACT_SUBAGENT_TOOL_DESCRIPTION,
|
|
94
|
+
safetyGuidance: () => SUBAGENT_SAFETY_GUIDANCE,
|
|
95
|
+
safety: () => SUBAGENT_SAFETY_GUIDANCE,
|
|
96
|
+
agentDir: () => agentDir,
|
|
97
|
+
projectConfigDir: () => projectConfigDir,
|
|
98
|
+
};
|
|
99
|
+
return template.replace(/\{\{(\w+)\}\}/g, (raw, name: string) => {
|
|
100
|
+
const replacement = variables[name];
|
|
101
|
+
if (replacement) return replacement();
|
|
102
|
+
warn(options, `${CUSTOM_TOOL_DESCRIPTION_FILE}: unknown placeholder ${raw} left unchanged.`);
|
|
103
|
+
return raw;
|
|
104
|
+
});
|
|
105
|
+
}
|
|
106
|
+
|
|
107
|
+
function loadCustomToolDescription(options?: ToolDescriptionOptions): string | undefined {
|
|
108
|
+
for (const filePath of customDescriptionPaths(options)) {
|
|
109
|
+
let stat: fs.Stats;
|
|
110
|
+
try {
|
|
111
|
+
stat = fs.statSync(filePath);
|
|
112
|
+
} catch (error) {
|
|
113
|
+
if (typeof error === "object" && error !== null && "code" in error && (error as NodeJS.ErrnoException).code === "ENOENT") continue;
|
|
114
|
+
warn(options, `Failed to inspect custom tool description '${filePath}': ${error instanceof Error ? error.message : String(error)}`);
|
|
115
|
+
continue;
|
|
116
|
+
}
|
|
117
|
+
if (!stat.isFile()) {
|
|
118
|
+
warn(options, `Ignoring custom tool description '${filePath}' because it is not a file.`);
|
|
119
|
+
continue;
|
|
120
|
+
}
|
|
121
|
+
if (stat.size > CUSTOM_TOOL_DESCRIPTION_MAX_BYTES) {
|
|
122
|
+
warn(options, `Ignoring custom tool description '${filePath}' because it is larger than ${CUSTOM_TOOL_DESCRIPTION_MAX_BYTES} bytes.`);
|
|
123
|
+
continue;
|
|
124
|
+
}
|
|
125
|
+
try {
|
|
126
|
+
const template = fs.readFileSync(filePath, "utf-8").trim();
|
|
127
|
+
if (!template) {
|
|
128
|
+
warn(options, `Ignoring empty custom tool description '${filePath}'.`);
|
|
129
|
+
continue;
|
|
130
|
+
}
|
|
131
|
+
const rendered = renderCustomTemplate(template, options).trim();
|
|
132
|
+
if (!rendered) {
|
|
133
|
+
warn(options, `Ignoring custom tool description '${filePath}' because it rendered empty.`);
|
|
134
|
+
continue;
|
|
135
|
+
}
|
|
136
|
+
return rendered;
|
|
137
|
+
} catch (error) {
|
|
138
|
+
warn(options, `Failed to read custom tool description '${filePath}': ${error instanceof Error ? error.message : String(error)}`);
|
|
139
|
+
}
|
|
140
|
+
}
|
|
141
|
+
return undefined;
|
|
142
|
+
}
|
|
143
|
+
|
|
144
|
+
function withMandatorySafetyGuidance(description: string): string {
|
|
145
|
+
const customDescription = description
|
|
146
|
+
.split(SUBAGENT_SAFETY_GUIDANCE)
|
|
147
|
+
.map((part) => part.trim())
|
|
148
|
+
.filter(Boolean)
|
|
149
|
+
.join("\n\n");
|
|
150
|
+
return customDescription
|
|
151
|
+
? `${customDescription}\n\n${SUBAGENT_SAFETY_GUIDANCE}`
|
|
152
|
+
: SUBAGENT_SAFETY_GUIDANCE;
|
|
153
|
+
}
|
|
154
|
+
|
|
155
|
+
export function buildSubagentToolDescription(config: Pick<ExtensionConfig, "toolDescriptionMode"> = {}, options?: ToolDescriptionOptions): string {
|
|
156
|
+
const mode = resolveToolDescriptionMode(config, options);
|
|
157
|
+
if (mode === "compact") return COMPACT_SUBAGENT_TOOL_DESCRIPTION;
|
|
158
|
+
if (mode === "custom") {
|
|
159
|
+
const custom = loadCustomToolDescription(options);
|
|
160
|
+
if (custom) return withMandatorySafetyGuidance(custom);
|
|
161
|
+
warn(options, `${CUSTOM_TOOL_DESCRIPTION_FILE} was not found or valid for toolDescriptionMode "custom"; using full description.`);
|
|
162
|
+
}
|
|
163
|
+
return FULL_SUBAGENT_TOOL_DESCRIPTION;
|
|
164
|
+
}
|