@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,197 @@
|
|
|
1
|
+
export const BACKGROUND_WORK_PROTOCOL_VERSION = 1;
|
|
2
|
+
export const BACKGROUND_WORK_REGISTRY_KEY = "pi-subagents.background-work.v1";
|
|
3
|
+
|
|
4
|
+
const MAX_PROVIDER_NAME_LENGTH = 128;
|
|
5
|
+
const MAX_PROVIDERS = 100;
|
|
6
|
+
const MAX_ITEM_ID_LENGTH = 256;
|
|
7
|
+
const MAX_SESSION_ID_LENGTH = 256;
|
|
8
|
+
const MAX_WAKE_CHANNEL_LENGTH = 256;
|
|
9
|
+
const MAX_ITEMS_PER_PROVIDER = 10_000;
|
|
10
|
+
|
|
11
|
+
export interface BackgroundWorkItem {
|
|
12
|
+
id: string;
|
|
13
|
+
sessionId: string;
|
|
14
|
+
}
|
|
15
|
+
|
|
16
|
+
export interface BackgroundWorkReconcileContext {
|
|
17
|
+
sessionId: string;
|
|
18
|
+
nowMs: number;
|
|
19
|
+
}
|
|
20
|
+
|
|
21
|
+
export interface BackgroundWorkProvider {
|
|
22
|
+
name: string;
|
|
23
|
+
listActiveWork(): readonly BackgroundWorkItem[];
|
|
24
|
+
wakeChannels?: readonly string[];
|
|
25
|
+
reconcile?(context: BackgroundWorkReconcileContext): void;
|
|
26
|
+
}
|
|
27
|
+
|
|
28
|
+
export interface RegisteredBackgroundWorkItem extends BackgroundWorkItem {
|
|
29
|
+
provider: string;
|
|
30
|
+
}
|
|
31
|
+
|
|
32
|
+
export interface BackgroundWorkSnapshot {
|
|
33
|
+
providers: readonly string[];
|
|
34
|
+
items: readonly RegisteredBackgroundWorkItem[];
|
|
35
|
+
}
|
|
36
|
+
|
|
37
|
+
interface BackgroundWorkRegistry {
|
|
38
|
+
version: typeof BACKGROUND_WORK_PROTOCOL_VERSION;
|
|
39
|
+
providers: Map<string, BackgroundWorkProvider>;
|
|
40
|
+
}
|
|
41
|
+
|
|
42
|
+
function registry(): BackgroundWorkRegistry {
|
|
43
|
+
const key = Symbol.for(BACKGROUND_WORK_REGISTRY_KEY);
|
|
44
|
+
const globalObject = globalThis as Record<PropertyKey, unknown>;
|
|
45
|
+
const existing = globalObject[key];
|
|
46
|
+
if (existing === undefined) {
|
|
47
|
+
const created: BackgroundWorkRegistry = {
|
|
48
|
+
version: BACKGROUND_WORK_PROTOCOL_VERSION,
|
|
49
|
+
providers: new Map(),
|
|
50
|
+
};
|
|
51
|
+
globalObject[key] = created;
|
|
52
|
+
return created;
|
|
53
|
+
}
|
|
54
|
+
if (!existing || typeof existing !== "object" || Array.isArray(existing)) {
|
|
55
|
+
throw new Error(`Malformed background-work registry at Symbol.for("${BACKGROUND_WORK_REGISTRY_KEY}").`);
|
|
56
|
+
}
|
|
57
|
+
const candidate = existing as Partial<BackgroundWorkRegistry>;
|
|
58
|
+
if (candidate.version !== BACKGROUND_WORK_PROTOCOL_VERSION || !(candidate.providers instanceof Map)) {
|
|
59
|
+
throw new Error(`Unsupported background-work registry at Symbol.for("${BACKGROUND_WORK_REGISTRY_KEY}").`);
|
|
60
|
+
}
|
|
61
|
+
return candidate as BackgroundWorkRegistry;
|
|
62
|
+
}
|
|
63
|
+
|
|
64
|
+
function validateString(value: unknown, field: string, maxLength: number): string {
|
|
65
|
+
if (typeof value !== "string" || value.length === 0 || value.trim() !== value) {
|
|
66
|
+
throw new Error(`${field} must be a non-empty string without leading or trailing whitespace.`);
|
|
67
|
+
}
|
|
68
|
+
if (value.length > maxLength) throw new Error(`${field} must be at most ${maxLength} characters.`);
|
|
69
|
+
if (value.includes("\0")) throw new Error(`${field} must not contain NUL characters.`);
|
|
70
|
+
return value;
|
|
71
|
+
}
|
|
72
|
+
|
|
73
|
+
function validateProvider(value: unknown): BackgroundWorkProvider {
|
|
74
|
+
if (!value || typeof value !== "object" || Array.isArray(value)) {
|
|
75
|
+
throw new Error("Background-work provider must be an object.");
|
|
76
|
+
}
|
|
77
|
+
const provider = value as Record<string, unknown>;
|
|
78
|
+
const unknownFields = Object.keys(provider).filter((key) => !["name", "listActiveWork", "wakeChannels", "reconcile"].includes(key));
|
|
79
|
+
if (unknownFields.length > 0) throw new Error(`Background-work provider has unknown fields: ${unknownFields.join(", ")}.`);
|
|
80
|
+
const name = validateString(provider.name, "Background-work provider name", MAX_PROVIDER_NAME_LENGTH);
|
|
81
|
+
if (typeof provider.listActiveWork !== "function") {
|
|
82
|
+
throw new Error(`Background-work provider '${name}' must expose listActiveWork().`);
|
|
83
|
+
}
|
|
84
|
+
if (provider.reconcile !== undefined && typeof provider.reconcile !== "function") {
|
|
85
|
+
throw new Error(`Background-work provider '${name}' reconcile must be a function when provided.`);
|
|
86
|
+
}
|
|
87
|
+
if (provider.wakeChannels !== undefined) {
|
|
88
|
+
if (!Array.isArray(provider.wakeChannels)) {
|
|
89
|
+
throw new Error(`Background-work provider '${name}' wakeChannels must be an array when provided.`);
|
|
90
|
+
}
|
|
91
|
+
const channels = provider.wakeChannels.map((channel, index) =>
|
|
92
|
+
validateString(channel, `Background-work provider '${name}' wakeChannels[${index}]`, MAX_WAKE_CHANNEL_LENGTH));
|
|
93
|
+
if (new Set(channels).size !== channels.length) {
|
|
94
|
+
throw new Error(`Background-work provider '${name}' wakeChannels must not contain duplicates.`);
|
|
95
|
+
}
|
|
96
|
+
}
|
|
97
|
+
return value as BackgroundWorkProvider;
|
|
98
|
+
}
|
|
99
|
+
|
|
100
|
+
function validateItem(provider: string, value: unknown, index: number): BackgroundWorkItem {
|
|
101
|
+
if (!value || typeof value !== "object" || Array.isArray(value)) {
|
|
102
|
+
throw new Error(`Background-work provider '${provider}' item ${index} must be an object.`);
|
|
103
|
+
}
|
|
104
|
+
const item = value as Record<string, unknown>;
|
|
105
|
+
const unknownFields = Object.keys(item).filter((key) => key !== "id" && key !== "sessionId");
|
|
106
|
+
if (unknownFields.length > 0) {
|
|
107
|
+
throw new Error(`Background-work provider '${provider}' item ${index} has unknown fields: ${unknownFields.join(", ")}.`);
|
|
108
|
+
}
|
|
109
|
+
return {
|
|
110
|
+
id: validateString(item.id, `Background-work provider '${provider}' item ${index} id`, MAX_ITEM_ID_LENGTH),
|
|
111
|
+
sessionId: validateString(item.sessionId, `Background-work provider '${provider}' item ${index} sessionId`, MAX_SESSION_ID_LENGTH),
|
|
112
|
+
};
|
|
113
|
+
}
|
|
114
|
+
|
|
115
|
+
/**
|
|
116
|
+
* Register or replace one process-local background-work provider. The returned
|
|
117
|
+
* disposer only removes this exact registration, so an old extension reload
|
|
118
|
+
* cannot unregister its replacement.
|
|
119
|
+
*/
|
|
120
|
+
export function registerBackgroundWorkProvider(provider: BackgroundWorkProvider): () => void {
|
|
121
|
+
const validated = validateProvider(provider);
|
|
122
|
+
const current = registry();
|
|
123
|
+
if (!current.providers.has(validated.name) && current.providers.size >= MAX_PROVIDERS) {
|
|
124
|
+
throw new Error(`Background-work registry supports at most ${MAX_PROVIDERS} providers.`);
|
|
125
|
+
}
|
|
126
|
+
current.providers.set(validated.name, validated);
|
|
127
|
+
return () => {
|
|
128
|
+
if (current.providers.get(validated.name) === validated) current.providers.delete(validated.name);
|
|
129
|
+
};
|
|
130
|
+
}
|
|
131
|
+
|
|
132
|
+
export function listBackgroundWorkProviders(): readonly BackgroundWorkProvider[] {
|
|
133
|
+
const current = registry();
|
|
134
|
+
if (current.providers.size > MAX_PROVIDERS) throw new Error(`Background-work registry contains more than ${MAX_PROVIDERS} providers.`);
|
|
135
|
+
const providers: BackgroundWorkProvider[] = [];
|
|
136
|
+
for (const [key, value] of current.providers) {
|
|
137
|
+
const provider = validateProvider(value);
|
|
138
|
+
if (key !== provider.name) throw new Error(`Background-work registry key '${key}' does not match provider name '${provider.name}'.`);
|
|
139
|
+
providers.push(provider);
|
|
140
|
+
}
|
|
141
|
+
return providers;
|
|
142
|
+
}
|
|
143
|
+
|
|
144
|
+
/** Read validated provider wake channels without reconciling or listing work. */
|
|
145
|
+
export function listBackgroundWorkWakeChannels(): readonly string[] {
|
|
146
|
+
const channels = new Set<string>();
|
|
147
|
+
for (const provider of listBackgroundWorkProviders()) {
|
|
148
|
+
for (const channel of provider.wakeChannels ?? []) channels.add(channel);
|
|
149
|
+
}
|
|
150
|
+
return [...channels];
|
|
151
|
+
}
|
|
152
|
+
|
|
153
|
+
/** Reconcile and snapshot active provider work owned by one exact Pi session. */
|
|
154
|
+
export function snapshotBackgroundWork(sessionId: string, nowMs = Date.now()): BackgroundWorkSnapshot {
|
|
155
|
+
validateString(sessionId, "Background-work snapshot sessionId", MAX_SESSION_ID_LENGTH);
|
|
156
|
+
const providers = listBackgroundWorkProviders();
|
|
157
|
+
const items: RegisteredBackgroundWorkItem[] = [];
|
|
158
|
+
const identities = new Set<string>();
|
|
159
|
+
for (const provider of providers) {
|
|
160
|
+
try {
|
|
161
|
+
provider.reconcile?.({ sessionId, nowMs });
|
|
162
|
+
} catch (error) {
|
|
163
|
+
throw new Error(
|
|
164
|
+
`Background-work provider '${provider.name}' reconcile failed: ${error instanceof Error ? error.message : String(error)}`,
|
|
165
|
+
{ cause: error },
|
|
166
|
+
);
|
|
167
|
+
}
|
|
168
|
+
let active: readonly BackgroundWorkItem[];
|
|
169
|
+
try {
|
|
170
|
+
active = provider.listActiveWork();
|
|
171
|
+
} catch (error) {
|
|
172
|
+
throw new Error(
|
|
173
|
+
`Background-work provider '${provider.name}' listActiveWork failed: ${error instanceof Error ? error.message : String(error)}`,
|
|
174
|
+
{ cause: error },
|
|
175
|
+
);
|
|
176
|
+
}
|
|
177
|
+
if (!Array.isArray(active)) {
|
|
178
|
+
throw new Error(`Background-work provider '${provider.name}' listActiveWork() must return an array.`);
|
|
179
|
+
}
|
|
180
|
+
if (active.length > MAX_ITEMS_PER_PROVIDER) {
|
|
181
|
+
throw new Error(`Background-work provider '${provider.name}' returned ${active.length} items; maximum is ${MAX_ITEMS_PER_PROVIDER}.`);
|
|
182
|
+
}
|
|
183
|
+
active.forEach((value, index) => {
|
|
184
|
+
const item = validateItem(provider.name, value, index);
|
|
185
|
+
const identity = `${provider.name}\0${item.sessionId}\0${item.id}`;
|
|
186
|
+
if (identities.has(identity)) {
|
|
187
|
+
throw new Error(`Background-work provider '${provider.name}' returned duplicate item '${item.id}' for session '${item.sessionId}'.`);
|
|
188
|
+
}
|
|
189
|
+
identities.add(identity);
|
|
190
|
+
if (item.sessionId === sessionId) items.push({ provider: provider.name, ...item });
|
|
191
|
+
});
|
|
192
|
+
}
|
|
193
|
+
return {
|
|
194
|
+
providers: providers.map((provider) => provider.name),
|
|
195
|
+
items,
|
|
196
|
+
};
|
|
197
|
+
}
|
|
@@ -0,0 +1,17 @@
|
|
|
1
|
+
export {
|
|
2
|
+
SUBAGENT_CAPABILITY_CEILING_ENV,
|
|
3
|
+
SUBAGENT_CAPABILITY_CEILING_REGISTRY_KEY,
|
|
4
|
+
SUBAGENT_CAPABILITY_CEILING_VERSION,
|
|
5
|
+
decodeSubagentCapabilityCeiling,
|
|
6
|
+
encodeSubagentCapabilityCeiling,
|
|
7
|
+
intersectSubagentCapabilityCeilings,
|
|
8
|
+
parseSubagentCapabilityCeiling,
|
|
9
|
+
registerSubagentCapabilityCeiling,
|
|
10
|
+
resolveCurrentSubagentCapabilityCeiling,
|
|
11
|
+
resolveSubagentCapabilityCeiling,
|
|
12
|
+
type RegisterSubagentCapabilityCeilingOptions,
|
|
13
|
+
type ResolvedSubagentCapabilityCeiling,
|
|
14
|
+
type SubagentCapabilityCeiling,
|
|
15
|
+
type SubagentCapabilityCeilingHandle,
|
|
16
|
+
type SubagentCapabilityAudit,
|
|
17
|
+
} from "../runs/shared/capability-ceiling.ts";
|
|
@@ -0,0 +1,119 @@
|
|
|
1
|
+
// This is the established extension-to-extension transport. The structured
|
|
2
|
+
// delegation API intentionally reuses it instead of adding a second event
|
|
3
|
+
// protocol. Unstructured legacy direct payloads are rejected.
|
|
4
|
+
export const SUBAGENT_DELEGATION_REQUEST_EVENT = "prompt-template:subagent:request";
|
|
5
|
+
export const SUBAGENT_DELEGATION_STARTED_EVENT = "prompt-template:subagent:started";
|
|
6
|
+
export const SUBAGENT_DELEGATION_UPDATE_EVENT = "prompt-template:subagent:update";
|
|
7
|
+
export const SUBAGENT_DELEGATION_RESPONSE_EVENT = "prompt-template:subagent:response";
|
|
8
|
+
export const SUBAGENT_DELEGATION_CANCEL_EVENT = "prompt-template:subagent:cancel";
|
|
9
|
+
|
|
10
|
+
export interface SubagentDelegationTurnBudget {
|
|
11
|
+
maxTurns: number;
|
|
12
|
+
graceTurns?: number;
|
|
13
|
+
}
|
|
14
|
+
|
|
15
|
+
export interface SubagentDelegationToolBudget {
|
|
16
|
+
soft?: number;
|
|
17
|
+
hard: number;
|
|
18
|
+
block?: string[] | "*";
|
|
19
|
+
}
|
|
20
|
+
|
|
21
|
+
export type SubagentDelegationJsonSchemaObject = Record<string, unknown>;
|
|
22
|
+
|
|
23
|
+
export type SubagentDelegationThinking = "off" | "minimal" | "low" | "medium" | "high" | "xhigh" | "max";
|
|
24
|
+
|
|
25
|
+
export type SubagentDelegationResultRequest =
|
|
26
|
+
| { kind: "text" }
|
|
27
|
+
| { kind: "structured"; schema: SubagentDelegationJsonSchemaObject };
|
|
28
|
+
|
|
29
|
+
export interface SubagentDelegationRequest {
|
|
30
|
+
requestId: string;
|
|
31
|
+
ownerRunId: string;
|
|
32
|
+
nodeId: string;
|
|
33
|
+
agent: string;
|
|
34
|
+
task: string;
|
|
35
|
+
context: "fresh" | "fork";
|
|
36
|
+
cwd: string;
|
|
37
|
+
model?: string;
|
|
38
|
+
thinking?: SubagentDelegationThinking;
|
|
39
|
+
timeoutMs?: number;
|
|
40
|
+
turnBudget?: SubagentDelegationTurnBudget;
|
|
41
|
+
toolBudget?: SubagentDelegationToolBudget;
|
|
42
|
+
skill?: string | string[] | boolean;
|
|
43
|
+
artifacts?: boolean;
|
|
44
|
+
result: SubagentDelegationResultRequest;
|
|
45
|
+
}
|
|
46
|
+
|
|
47
|
+
export interface SubagentDelegationStarted {
|
|
48
|
+
requestId: string;
|
|
49
|
+
ownerRunId: string;
|
|
50
|
+
nodeId: string;
|
|
51
|
+
}
|
|
52
|
+
|
|
53
|
+
export interface SubagentDelegationUpdate extends SubagentDelegationStarted {
|
|
54
|
+
runId?: string;
|
|
55
|
+
currentTool?: string;
|
|
56
|
+
currentToolArgs?: string;
|
|
57
|
+
recentOutput?: string;
|
|
58
|
+
recentOutputLines?: string[];
|
|
59
|
+
recentTools?: Array<{ tool: string; args: string }>;
|
|
60
|
+
model?: string;
|
|
61
|
+
toolCount?: number;
|
|
62
|
+
durationMs?: number;
|
|
63
|
+
tokens?: number;
|
|
64
|
+
}
|
|
65
|
+
|
|
66
|
+
export type SubagentDelegationStatus =
|
|
67
|
+
| "completed"
|
|
68
|
+
| "failed"
|
|
69
|
+
| "timed_out"
|
|
70
|
+
| "cancelled"
|
|
71
|
+
| "interrupted"
|
|
72
|
+
| "turn_budget_exhausted"
|
|
73
|
+
| "tool_budget_exhausted"
|
|
74
|
+
| "structured_output_failed"
|
|
75
|
+
| "acceptance_failed"
|
|
76
|
+
| "invalid_request"
|
|
77
|
+
| "unavailable_context"
|
|
78
|
+
| "duplicate_node";
|
|
79
|
+
|
|
80
|
+
export type SubagentDelegationValue =
|
|
81
|
+
| { kind: "text"; text: string }
|
|
82
|
+
| { kind: "structured"; value: unknown };
|
|
83
|
+
|
|
84
|
+
export interface SubagentDelegationUsage {
|
|
85
|
+
input: number;
|
|
86
|
+
output: number;
|
|
87
|
+
cacheRead: number;
|
|
88
|
+
cacheWrite: number;
|
|
89
|
+
cost: number;
|
|
90
|
+
turns: number;
|
|
91
|
+
toolCalls: number;
|
|
92
|
+
durationMs: number;
|
|
93
|
+
}
|
|
94
|
+
|
|
95
|
+
export interface SubagentDelegationTerminalResponse extends SubagentDelegationStarted {
|
|
96
|
+
status: Exclude<SubagentDelegationStatus, "invalid_request">;
|
|
97
|
+
error?: string;
|
|
98
|
+
runId?: string;
|
|
99
|
+
agent?: string;
|
|
100
|
+
model?: string;
|
|
101
|
+
thinking?: string;
|
|
102
|
+
exitCode?: number;
|
|
103
|
+
launchContractDigest?: string;
|
|
104
|
+
result?: SubagentDelegationValue;
|
|
105
|
+
usage?: SubagentDelegationUsage;
|
|
106
|
+
}
|
|
107
|
+
|
|
108
|
+
/** A malformed structured request can only be correlated by the valid identity fields it supplied. */
|
|
109
|
+
export interface SubagentDelegationInvalidResponse {
|
|
110
|
+
requestId: string;
|
|
111
|
+
ownerRunId?: string;
|
|
112
|
+
nodeId?: string;
|
|
113
|
+
status: "invalid_request";
|
|
114
|
+
error?: string;
|
|
115
|
+
}
|
|
116
|
+
|
|
117
|
+
export type SubagentDelegationResponse = SubagentDelegationTerminalResponse | SubagentDelegationInvalidResponse;
|
|
118
|
+
|
|
119
|
+
export interface SubagentDelegationCancel extends SubagentDelegationStarted {}
|
|
@@ -0,0 +1,129 @@
|
|
|
1
|
+
export const EXTERNAL_RUN_REGISTRY_VERSION = 1;
|
|
2
|
+
export const EXTERNAL_RUN_REGISTRY_KEY = "pi-subagents.external-runs.v1";
|
|
3
|
+
|
|
4
|
+
const MAX_PROVIDERS = 100;
|
|
5
|
+
const MAX_RUNS_PER_PROVIDER = 10_000;
|
|
6
|
+
const MAX_TEXT_LENGTH = 4_096;
|
|
7
|
+
|
|
8
|
+
export type ExternalRunState = "running" | "completed" | "failed" | "stopped";
|
|
9
|
+
export type ExternalRunCompletionReason = "exit" | "timeout" | "user-kill" | "auto-close-quiet" | "crash" | "unknown";
|
|
10
|
+
|
|
11
|
+
/** An observational record for work owned by another runtime. */
|
|
12
|
+
export interface ExternalRun {
|
|
13
|
+
id: string;
|
|
14
|
+
sessionId: string;
|
|
15
|
+
source: string;
|
|
16
|
+
state: ExternalRunState;
|
|
17
|
+
command?: string;
|
|
18
|
+
cwd?: string;
|
|
19
|
+
isolationPath?: string;
|
|
20
|
+
owner?: string;
|
|
21
|
+
completionReason?: ExternalRunCompletionReason;
|
|
22
|
+
reportPath?: string;
|
|
23
|
+
startedAt?: number;
|
|
24
|
+
completedAt?: number;
|
|
25
|
+
exitCode?: number | null;
|
|
26
|
+
residualRisks?: string[];
|
|
27
|
+
}
|
|
28
|
+
|
|
29
|
+
export interface ExternalRunProvider {
|
|
30
|
+
name: string;
|
|
31
|
+
listExternalRuns(): readonly ExternalRun[];
|
|
32
|
+
}
|
|
33
|
+
|
|
34
|
+
export interface RegisteredExternalRun extends ExternalRun {
|
|
35
|
+
provider: string;
|
|
36
|
+
}
|
|
37
|
+
|
|
38
|
+
interface ExternalRunRegistry {
|
|
39
|
+
version: typeof EXTERNAL_RUN_REGISTRY_VERSION;
|
|
40
|
+
providers: Map<string, ExternalRunProvider>;
|
|
41
|
+
}
|
|
42
|
+
|
|
43
|
+
function registry(): ExternalRunRegistry {
|
|
44
|
+
const key = Symbol.for(EXTERNAL_RUN_REGISTRY_KEY);
|
|
45
|
+
const target = globalThis as Record<PropertyKey, unknown>;
|
|
46
|
+
const existing = target[key];
|
|
47
|
+
if (existing === undefined) {
|
|
48
|
+
const created: ExternalRunRegistry = { version: EXTERNAL_RUN_REGISTRY_VERSION, providers: new Map() };
|
|
49
|
+
target[key] = created;
|
|
50
|
+
return created;
|
|
51
|
+
}
|
|
52
|
+
if (!existing || typeof existing !== "object" || Array.isArray(existing)) throw new Error(`Malformed external-run registry at Symbol.for("${EXTERNAL_RUN_REGISTRY_KEY}").`);
|
|
53
|
+
const candidate = existing as Partial<ExternalRunRegistry>;
|
|
54
|
+
if (candidate.version !== EXTERNAL_RUN_REGISTRY_VERSION || !(candidate.providers instanceof Map)) throw new Error(`Unsupported external-run registry at Symbol.for("${EXTERNAL_RUN_REGISTRY_KEY}").`);
|
|
55
|
+
return candidate as ExternalRunRegistry;
|
|
56
|
+
}
|
|
57
|
+
|
|
58
|
+
function text(value: unknown, field: string, required = false): string | undefined {
|
|
59
|
+
if (value === undefined && !required) return undefined;
|
|
60
|
+
if (typeof value !== "string" || value.length === 0 || value.trim() !== value || value.includes("\0")) throw new Error(`${field} must be a non-empty trimmed string without NUL characters.`);
|
|
61
|
+
if (value.length > MAX_TEXT_LENGTH) throw new Error(`${field} must be at most ${MAX_TEXT_LENGTH} characters.`);
|
|
62
|
+
return value;
|
|
63
|
+
}
|
|
64
|
+
|
|
65
|
+
function timestamp(value: unknown, field: string): number | undefined {
|
|
66
|
+
if (value === undefined) return undefined;
|
|
67
|
+
if (typeof value !== "number" || !Number.isFinite(value) || value < 0) throw new Error(`${field} must be a non-negative finite number.`);
|
|
68
|
+
return value;
|
|
69
|
+
}
|
|
70
|
+
|
|
71
|
+
function validateRun(value: unknown, provider: string, index: number): ExternalRun {
|
|
72
|
+
if (!value || typeof value !== "object" || Array.isArray(value)) throw new Error(`External-run provider '${provider}' item ${index} must be an object.`);
|
|
73
|
+
const run = value as Record<string, unknown>;
|
|
74
|
+
const fields = new Set(["id", "sessionId", "source", "state", "command", "cwd", "isolationPath", "owner", "completionReason", "reportPath", "startedAt", "completedAt", "exitCode", "residualRisks"]);
|
|
75
|
+
const unknown = Object.keys(run).filter((key) => !fields.has(key));
|
|
76
|
+
if (unknown.length) throw new Error(`External-run provider '${provider}' item ${index} has unknown fields: ${unknown.join(", ")}.`);
|
|
77
|
+
if (!["running", "completed", "failed", "stopped"].includes(run.state as string)) throw new Error(`External-run provider '${provider}' item ${index} state is invalid.`);
|
|
78
|
+
if (run.completionReason !== undefined && !["exit", "timeout", "user-kill", "auto-close-quiet", "crash", "unknown"].includes(run.completionReason as string)) throw new Error(`External-run provider '${provider}' item ${index} completionReason is invalid.`);
|
|
79
|
+
if (run.exitCode !== undefined && run.exitCode !== null && (!Number.isInteger(run.exitCode) || !Number.isFinite(run.exitCode))) throw new Error(`External-run provider '${provider}' item ${index} exitCode must be an integer or null.`);
|
|
80
|
+
if (run.residualRisks !== undefined && (!Array.isArray(run.residualRisks) || run.residualRisks.some((risk, riskIndex) => text(risk, `External-run provider '${provider}' item ${index} residualRisks[${riskIndex}]`, true) === undefined))) throw new Error(`External-run provider '${provider}' item ${index} residualRisks must be an array of strings.`);
|
|
81
|
+
return {
|
|
82
|
+
id: text(run.id, `External-run provider '${provider}' item ${index} id`, true)!,
|
|
83
|
+
sessionId: text(run.sessionId, `External-run provider '${provider}' item ${index} sessionId`, true)!,
|
|
84
|
+
source: text(run.source, `External-run provider '${provider}' item ${index} source`, true)!,
|
|
85
|
+
state: run.state as ExternalRunState,
|
|
86
|
+
...(text(run.command, `External-run provider '${provider}' item ${index} command`) !== undefined ? { command: text(run.command, `External-run provider '${provider}' item ${index} command`) } : {}),
|
|
87
|
+
...(text(run.cwd, `External-run provider '${provider}' item ${index} cwd`) !== undefined ? { cwd: text(run.cwd, `External-run provider '${provider}' item ${index} cwd`) } : {}),
|
|
88
|
+
...(text(run.isolationPath, `External-run provider '${provider}' item ${index} isolationPath`) !== undefined ? { isolationPath: text(run.isolationPath, `External-run provider '${provider}' item ${index} isolationPath`) } : {}),
|
|
89
|
+
...(text(run.owner, `External-run provider '${provider}' item ${index} owner`) !== undefined ? { owner: text(run.owner, `External-run provider '${provider}' item ${index} owner`) } : {}),
|
|
90
|
+
...(run.completionReason !== undefined ? { completionReason: run.completionReason as ExternalRunCompletionReason } : {}),
|
|
91
|
+
...(text(run.reportPath, `External-run provider '${provider}' item ${index} reportPath`) !== undefined ? { reportPath: text(run.reportPath, `External-run provider '${provider}' item ${index} reportPath`) } : {}),
|
|
92
|
+
...(timestamp(run.startedAt, `External-run provider '${provider}' item ${index} startedAt`) !== undefined ? { startedAt: timestamp(run.startedAt, `External-run provider '${provider}' item ${index} startedAt`) } : {}),
|
|
93
|
+
...(timestamp(run.completedAt, `External-run provider '${provider}' item ${index} completedAt`) !== undefined ? { completedAt: timestamp(run.completedAt, `External-run provider '${provider}' item ${index} completedAt`) } : {}),
|
|
94
|
+
...(run.exitCode !== undefined ? { exitCode: run.exitCode as number | null } : {}),
|
|
95
|
+
...(run.residualRisks !== undefined ? { residualRisks: [...run.residualRisks] as string[] } : {}),
|
|
96
|
+
};
|
|
97
|
+
}
|
|
98
|
+
|
|
99
|
+
/** Register an observational provider. pi-subagents never starts, stops, or steers these processes. */
|
|
100
|
+
export function registerExternalRunProvider(provider: ExternalRunProvider): () => void {
|
|
101
|
+
if (!provider || typeof provider !== "object" || Array.isArray(provider) || Object.keys(provider).some((key) => key !== "name" && key !== "listExternalRuns")) throw new Error("External-run provider must contain only name and listExternalRuns.");
|
|
102
|
+
const name = text(provider.name, "External-run provider name", true)!;
|
|
103
|
+
if (typeof provider.listExternalRuns !== "function") throw new Error(`External-run provider '${name}' must expose listExternalRuns().`);
|
|
104
|
+
const current = registry();
|
|
105
|
+
if (!current.providers.has(name) && current.providers.size >= MAX_PROVIDERS) throw new Error(`External-run registry supports at most ${MAX_PROVIDERS} providers.`);
|
|
106
|
+
current.providers.set(name, provider);
|
|
107
|
+
return () => { if (current.providers.get(name) === provider) current.providers.delete(name); };
|
|
108
|
+
}
|
|
109
|
+
|
|
110
|
+
/** Snapshot records for one Pi session. Records are read-only observations of foreign process ownership. */
|
|
111
|
+
export function snapshotExternalRuns(sessionId: string): readonly RegisteredExternalRun[] {
|
|
112
|
+
text(sessionId, "External-run snapshot sessionId", true);
|
|
113
|
+
const records: RegisteredExternalRun[] = [];
|
|
114
|
+
const identities = new Set<string>();
|
|
115
|
+
for (const [name, provider] of registry().providers) {
|
|
116
|
+
if (provider.name !== name) throw new Error(`External-run registry key '${name}' does not match provider name '${provider.name}'.`);
|
|
117
|
+
const runs = provider.listExternalRuns();
|
|
118
|
+
if (!Array.isArray(runs)) throw new Error(`External-run provider '${name}' listExternalRuns() must return an array.`);
|
|
119
|
+
if (runs.length > MAX_RUNS_PER_PROVIDER) throw new Error(`External-run provider '${name}' returned more than ${MAX_RUNS_PER_PROVIDER} runs.`);
|
|
120
|
+
runs.forEach((value, index) => {
|
|
121
|
+
const run = validateRun(value, name, index);
|
|
122
|
+
const identity = `${name}\0${run.sessionId}\0${run.id}`;
|
|
123
|
+
if (identities.has(identity)) throw new Error(`External-run provider '${name}' returned duplicate run '${run.id}' for session '${run.sessionId}'.`);
|
|
124
|
+
identities.add(identity);
|
|
125
|
+
if (run.sessionId === sessionId) records.push({ provider: name, ...run });
|
|
126
|
+
});
|
|
127
|
+
}
|
|
128
|
+
return records;
|
|
129
|
+
}
|