@xzzpig/pi-subagents 0.2.0 → 0.4.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 +96 -0
- package/README.md +2 -0
- package/agents/oracle.md +7 -5
- package/agents/researcher.md +1 -1
- package/agents/reviewer.md +2 -2
- package/agents/scout.md +1 -1
- package/agents/worker.md +1 -1
- package/docs/agents.md +3 -0
- package/docs/configuration.md +121 -10
- package/docs/extension-api.md +36 -0
- package/docs/missions.md +5 -3
- package/docs/observability.md +43 -3
- package/docs/tool-reference.md +20 -3
- package/docs/workflows.md +2 -2
- package/package.json +4 -4
- package/skills/pi-subagents/references/constraints-and-recipes.md +3 -2
- package/skills/pi-subagents/references/execution-controls.md +5 -4
- package/skills/pi-subagents/references/management-authoring-rpc.md +2 -2
- package/skills/pi-subagents/references/prompting-and-roles.md +31 -15
- package/src/agents/agent-serializer.ts +2 -0
- package/src/agents/agents.ts +46 -15
- package/src/api/external-runs.ts +174 -84
- package/src/api/preflight.ts +13 -7
- package/src/extension/config.ts +59 -0
- package/src/extension/doctor.ts +40 -0
- package/src/extension/index.ts +83 -9
- package/src/extension/public-execution.ts +37 -4
- package/src/extension/rpc.ts +8 -10
- package/src/extension/schemas.ts +12 -10
- package/src/extension/tool-description.ts +13 -9
- package/src/inspectors/herdr/actions.ts +13 -8
- package/src/inspectors/herdr/inspector-runner.ts +16 -3
- package/src/inspectors/herdr/project-panes.ts +2 -6
- package/src/inspectors/herdr/shell-command.ts +16 -0
- package/src/intercom/intercom-bridge.ts +9 -5
- package/src/intercom/native-supervisor-channel.ts +19 -42
- package/src/missions/goal-driver.ts +3 -1
- package/src/missions/lifecycle.ts +4 -7
- package/src/missions/store.ts +12 -7
- package/src/missions/workflow-state.ts +6 -2
- package/src/runs/background/active-async-capacity.ts +431 -0
- package/src/runs/background/active-run-index.ts +77 -3
- package/src/runs/background/async-execution.ts +190 -72
- package/src/runs/background/async-job-tracker.ts +5 -0
- package/src/runs/background/async-resume.ts +21 -7
- package/src/runs/background/async-status-snapshot.ts +277 -0
- package/src/runs/background/async-status.ts +17 -6
- package/src/runs/background/chain-append.ts +33 -15
- package/src/runs/background/chain-root-attachment.ts +2 -2
- package/src/runs/background/completion-replay.ts +11 -1
- package/src/runs/background/fleet-view.ts +21 -6
- package/src/runs/background/owned-process-tree.ts +104 -0
- package/src/runs/background/process-terminal.ts +17 -3
- package/src/runs/background/result-files.ts +437 -0
- package/src/runs/background/result-watcher.ts +188 -41
- package/src/runs/background/resume-guidance.ts +27 -7
- package/src/runs/background/retained-children.ts +75 -18
- package/src/runs/background/run-id-resolver.ts +30 -24
- package/src/runs/background/run-status.ts +106 -5
- package/src/runs/background/scheduled-runs.ts +54 -28
- package/src/runs/background/stale-run-reconciler.ts +30 -16
- package/src/runs/background/subagent-runner.ts +352 -62
- package/src/runs/background/subagent-wait.ts +2 -0
- package/src/runs/background/wait-completions.ts +5 -2
- package/src/runs/foreground/async-dismiss-action.ts +2 -1
- package/src/runs/foreground/chain-execution.ts +53 -2
- package/src/runs/foreground/execution.ts +309 -34
- package/src/runs/foreground/foreground-control.ts +12 -0
- package/src/runs/foreground/prompt-audit.ts +172 -0
- package/src/runs/foreground/subagent-executor.ts +936 -224
- package/src/runs/shared/acceptance.ts +13 -4
- package/src/runs/shared/completion-guard.ts +107 -1
- package/src/runs/shared/external-cli-runner.ts +4 -0
- package/src/runs/shared/llm-intent-arbiter.ts +302 -0
- package/src/runs/shared/model-fallback.ts +16 -2
- package/src/runs/shared/nested-events.ts +66 -62
- package/src/runs/shared/orca-progress-tabs.ts +375 -0
- package/src/runs/shared/parallel-utils.ts +4 -0
- package/src/runs/shared/pi-args.ts +44 -1
- package/src/runs/shared/run-fanout-budget.ts +280 -0
- package/src/runs/shared/single-output.ts +4 -2
- package/src/runs/shared/subagent-control.ts +15 -0
- package/src/runs/shared/subagent-prompt-runtime.ts +1 -9
- package/src/runs/shared/subagent-startup-retry.ts +12 -0
- package/src/runs/shared/task-intent.ts +19 -3
- package/src/runs/shared/tool-timeout.ts +93 -0
- package/src/runs/shared/worktree.ts +17 -5
- package/src/shared/agent-stream-options.ts +5 -0
- package/src/shared/artifacts.ts +2 -6
- package/src/shared/display-text.ts +50 -0
- package/src/shared/node-executable.ts +21 -0
- package/src/shared/types.ts +143 -5
- package/src/shared/utils.ts +3 -1
- package/src/slash/slash-commands.ts +34 -25
- package/src/slash/slash-live-state.ts +3 -0
- package/src/tui/fleet-status.ts +164 -47
- package/src/tui/fleet-transcript.ts +1 -48
- package/src/tui/fleet.ts +352 -27
- package/src/tui/render.ts +122 -44
- package/src/watchdog/permission-arbiter.ts +2 -1
- package/src/watchdog/review.ts +4 -3
- package/src/workflows/chat-progress.ts +10 -2
- package/src/workflows/scripted-workflow.ts +292 -79
|
@@ -23,7 +23,7 @@ import type {
|
|
|
23
23
|
SubagentRunMode,
|
|
24
24
|
} from "../../shared/types.ts";
|
|
25
25
|
import { isAgentContractV1 } from "./agent-contract.ts";
|
|
26
|
-
import { classifyTaskMutationIntent, taskMayMutate } from "./task-intent.ts";
|
|
26
|
+
import { classifyTaskMutationIntent, stripSeverityCompounds, taskMayMutate } from "./task-intent.ts";
|
|
27
27
|
|
|
28
28
|
const LEVEL_RANK: Record<Exclude<AcceptanceLevel, "auto">, number> = {
|
|
29
29
|
none: 0,
|
|
@@ -93,7 +93,7 @@ function inferLevel(input: {
|
|
|
93
93
|
const rolePatchTask = input.acceptanceRole !== undefined
|
|
94
94
|
&& intent.kind !== "read-only"
|
|
95
95
|
&& !/\b(?:do not|don't|must not)\s+patch\b/.test(task)
|
|
96
|
-
&& /\bpatch\s+(?:(?:\.{0,2}[\\/])?(?:[\w.-]+[\\/])+[\w.-]+|[\w.-]+\.[a-z0-9]+\b|(?:the\s+)?parser\b)/.test(task);
|
|
96
|
+
&& /\bpatch\s+(?:(?:\.{0,2}[\\/])?(?:[\w.-]+[\\/])+[\w.-]+|[\w.-]+\.[a-z0-9]+\b|(?:the\s+)?parser\b)/.test(stripSeverityCompounds(task));
|
|
97
97
|
const taskMayWrite = readOnlyTask ? false : taskMayMutate(input.task ?? "") || intent.kind === "implementation" || rolePatchTask;
|
|
98
98
|
const readOnlyAgent = input.acceptanceRole === "read-only"
|
|
99
99
|
|| (input.acceptanceRole === undefined && /\b(?:reviewer|oracle|scout|researcher|analyst)\b/.test(agent));
|
|
@@ -433,6 +433,7 @@ export function formatAcceptancePrompt(acceptance: ResolvedAcceptanceConfig, opt
|
|
|
433
433
|
"",
|
|
434
434
|
"Finish with a fenced JSON block tagged `acceptance-report` in this shape:",
|
|
435
435
|
"Use empty arrays when no items apply; array fields contain strings unless object entries are shown.",
|
|
436
|
+
"Empty-string entries (`[\"\"]`) are ignored; use `[]` when nothing applies.",
|
|
436
437
|
"`criteriaSatisfied[].status` must be exactly one of: satisfied, not-satisfied, not-applicable.",
|
|
437
438
|
"`commandsRun[].result` must be exactly one of: passed, failed, not-run.",
|
|
438
439
|
"`manualNotes` and `notes` are optional strings; an empty string means no note and does not satisfy `manual-notes` evidence.",
|
|
@@ -612,9 +613,17 @@ function normalizeAcceptanceReportValue(value: unknown, pathLabel = ""): { value
|
|
|
612
613
|
case "testsAddedOrUpdated":
|
|
613
614
|
case "validationOutput":
|
|
614
615
|
case "residualRisks":
|
|
615
|
-
case "reviewFindings":
|
|
616
|
-
|
|
616
|
+
case "reviewFindings": {
|
|
617
|
+
// Tolerate empty-string entries ("[\"\"]"): models write them for "no items"
|
|
618
|
+
// and a single empty entry must not reject the whole report. Drop them at
|
|
619
|
+
// parse time; non-string entries are kept so validateStringArrayField still
|
|
620
|
+
// flags structural garbage.
|
|
621
|
+
const items = typeof fieldValue === "string" ? [fieldValue] : fieldValue;
|
|
622
|
+
normalized[canonical] = Array.isArray(items)
|
|
623
|
+
? items.filter((item) => typeof item !== "string" || item.trim().length > 0)
|
|
624
|
+
: items;
|
|
617
625
|
break;
|
|
626
|
+
}
|
|
618
627
|
case "noStagedFiles": {
|
|
619
628
|
const token = typeof fieldValue === "string" ? fieldValue.trim().toLowerCase() : undefined;
|
|
620
629
|
normalized[canonical] = token === "true" ? true : token === "false" ? false : fieldValue;
|
|
@@ -22,6 +22,23 @@ const READ_ONLY_BUILTIN_TOOLS = new Set([
|
|
|
22
22
|
const CURSOR_FILE_MUTATION_THINKING =
|
|
23
23
|
/(?:^|\n)\s*Cursor (?:edit|write)\s*:/i;
|
|
24
24
|
|
|
25
|
+
const REVIVED_TASK_PREFIX = /^You are reviving a previous subagent conversation\.\n\nOriginal run: .+\nOriginal agent: .+(?:\nOriginal session file: .+)?\n\nUse the stored session context as background\. Answer the orchestrator's follow-up below\. Do not assume the original child process is still alive\.\n\nFollow-up:\n/;
|
|
26
|
+
const IMPLEMENTATION_CHALLENGE_FOLLOW_UP_PATTERN = /^(?:Run )?implementation challenge pass (?:one|two|\d+)(?:\s+and implement any better current[- ]scope change\.?|\s+for the accepted candidate\.\s+Reconsider it and implement any better current[- ]scope change\.?)?$/i;
|
|
27
|
+
const NO_BETTER_CHANGE_NEEDED_PATTERN = /^\s*no (?:better|further|additional) (?:current[- ]scope )?(?:code |source |file )?(?:change|changes|edit|edits|patch|patches) (?:is|are) needed\b/i;
|
|
28
|
+
const KEPT_CURRENT_IMPLEMENTATION_PATTERN = /\b(?:kept (?:the )?current (?:implementation|candidate|shape)|(?:the )?current (?:implementation|candidate|shape) was kept)\b/i;
|
|
29
|
+
const NO_CHANGE_MADE_PATTERN = /\bno (?:new )?(?:(?:code|source|file|test)(?:\s*(?:,\s*or|,|\/|or)\s*(?:code|source|file|test))* changes?|changes?) (?:were|was) made\b/i;
|
|
30
|
+
const NO_BETTER_CHANGE_QUALIFIER_PATTERN = /\b(?:do\s+not|don't|dont|not|never|cannot|can't|cant|unable|uncertain|unsure|unclear|disagree|wrong|false|reject|rejected|rejecting|maybe|might|may|\w+n['’]t)\b/i;
|
|
31
|
+
const REPORT_SENTENCE_PATTERN = /[^.!?]+(?:[.!?]+(?=(?:["”'’]?\s)|["”'’]?$)|$)/g;
|
|
32
|
+
const QUOTED_CLAIM_PATTERN = /["“]([^"”]+)["”]([.!?]?\s*[^.!?]*)/g;
|
|
33
|
+
const QUOTED_CLAIM_REFERENCE_PATTERN = /\b(?:that|this|it|claim|report|message|disagree)\b/i;
|
|
34
|
+
const CLAIM_CONTRADICTION_PATTERN = /\bbut\b[^.!?]*\b(?:uncertain|unsure|unclear|disagree|wrong|false|reject|rejected|rejecting)\b/i;
|
|
35
|
+
const IMPLEMENTATION_RETRACTION_PATTERN = /\b(?:found|identified)\s+(?:(?:a|an|the)\s+)?(?:required|necessary|additional|better)?\s*(?:(?:code|source|file|test)\s+)?(?:changes?|edits?|patches?)\b|\b(?:(?:implementation|code|source|file|test)\s+)?work\s+(?:remains?|is\s+(?:needed|required))\b|\b(?:(?:a|an|the)\s+)?(?:(?:code|source|file|test)\s+)?(?:changes?|edits?|patches?)\s+(?:are|is)\s+(?:needed|required)\b|\b(?:required|necessary|additional|better)\s+(?:(?:code|source|file|test)\s+)?(?:changes?|edits?|patches?)\b|\b(?:I|we)?\s*need\s+(?:(?:code|source|file|test)\s+)?(?:changes?|edits?|patches?)\b|\b(?:need|needs|require|requires)\s+(?:to\s+)?(?:implement|make|apply)\b/i;
|
|
36
|
+
const IMPLEMENTATION_RETRACTION_GLOBAL_PATTERN = new RegExp(IMPLEMENTATION_RETRACTION_PATTERN.source, "gi");
|
|
37
|
+
const DIRECT_CLAIM_RETRACTION_PATTERN = /^\s*(?:I\s+)?(?:disagree|reject|retract)\b|\b(?:disagree|retract|retracted|retracting|reject|rejected|rejecting)\b[^.!?]*\b(?:that|this|it|claim|report|message)\b|\b(?:that|this|it|claim|report|message)\b[^.!?]*\b(?:is|was)\s+(?:rejected|retracted)\b/i;
|
|
38
|
+
const NEGATED_RETRACTION_PREFIX_PATTERN = /\b(?:no|not|\w+n['’]t)\b(?:\s+\w+){0,2}\s*$/i;
|
|
39
|
+
const REPORTED_CLAIM_PREFIX_PATTERN = /["“]|\b(?:prior|previous)\s+(?:message|report)\b|\b(?:said|stated|reported)\b/i;
|
|
40
|
+
const POST_CLAIM_SEPARATOR_PATTERN = /^[\s,;:.—–'"“‘’-]+/;
|
|
41
|
+
|
|
25
42
|
interface CompletionMutationGuardInput {
|
|
26
43
|
agent: string;
|
|
27
44
|
task: string;
|
|
@@ -36,6 +53,11 @@ interface CompletionMutationGuardResult {
|
|
|
36
53
|
triggered: boolean;
|
|
37
54
|
}
|
|
38
55
|
|
|
56
|
+
interface ReportSentence {
|
|
57
|
+
text: string;
|
|
58
|
+
offset: number;
|
|
59
|
+
}
|
|
60
|
+
|
|
39
61
|
export function hasMutationToolCapability(tools: string[] | undefined, mcpDirectTools: string[] | undefined): boolean {
|
|
40
62
|
if ((mcpDirectTools?.length ?? 0) > 0) return true;
|
|
41
63
|
if (tools === undefined) return true;
|
|
@@ -82,14 +104,98 @@ export function hasMutationToolCall(messages: Message[]): boolean {
|
|
|
82
104
|
return false;
|
|
83
105
|
}
|
|
84
106
|
|
|
107
|
+
function hasImplementationRetraction(text: string): boolean {
|
|
108
|
+
return Array.from(text.matchAll(IMPLEMENTATION_RETRACTION_GLOBAL_PATTERN)).some((retraction) =>
|
|
109
|
+
!NEGATED_RETRACTION_PREFIX_PATTERN.test(text.slice(0, retraction.index!)));
|
|
110
|
+
}
|
|
111
|
+
|
|
112
|
+
function hasDirectClaimRetraction(text: string): boolean {
|
|
113
|
+
return DIRECT_CLAIM_RETRACTION_PATTERN.test(text.replace(POST_CLAIM_SEPARATOR_PATTERN, ""));
|
|
114
|
+
}
|
|
115
|
+
|
|
116
|
+
function isInsideQuotedText(report: string, index: number): boolean {
|
|
117
|
+
let quote: "double" | "single" | undefined;
|
|
118
|
+
for (const char of report.slice(0, index)) {
|
|
119
|
+
if (quote === "double") {
|
|
120
|
+
if (char === "\"" || char === "”") quote = undefined;
|
|
121
|
+
} else if (quote === "single") {
|
|
122
|
+
if (char === "’") quote = undefined;
|
|
123
|
+
} else if (char === "\"" || char === "“") {
|
|
124
|
+
quote = "double";
|
|
125
|
+
} else if (char === "‘") {
|
|
126
|
+
quote = "single";
|
|
127
|
+
}
|
|
128
|
+
}
|
|
129
|
+
return quote !== undefined;
|
|
130
|
+
}
|
|
131
|
+
|
|
132
|
+
function unqualifiedClaimIndex(report: string, sentences: ReportSentence[], pattern: RegExp): number {
|
|
133
|
+
return sentences.findIndex((sentence) => {
|
|
134
|
+
const claim = sentence.text.match(pattern);
|
|
135
|
+
if (claim === null) return false;
|
|
136
|
+
const before = sentence.text.slice(0, claim.index!);
|
|
137
|
+
const after = sentence.text.slice(claim.index! + claim[0].length);
|
|
138
|
+
const previous = before.trimEnd().at(-1);
|
|
139
|
+
return previous !== "'"
|
|
140
|
+
&& previous !== "‘"
|
|
141
|
+
&& !isInsideQuotedText(report, sentence.offset + claim.index!)
|
|
142
|
+
&& !REPORTED_CLAIM_PREFIX_PATTERN.test(before)
|
|
143
|
+
&& !NO_BETTER_CHANGE_QUALIFIER_PATTERN.test(before)
|
|
144
|
+
&& !CLAIM_CONTRADICTION_PATTERN.test(after)
|
|
145
|
+
&& !hasImplementationRetraction(after)
|
|
146
|
+
&& !hasDirectClaimRetraction(after);
|
|
147
|
+
});
|
|
148
|
+
}
|
|
149
|
+
|
|
150
|
+
function hasLaterClaimRetraction(sentences: ReportSentence[], claimIndex: number): boolean {
|
|
151
|
+
return sentences.slice(claimIndex + 1).some((sentence) => hasImplementationRetraction(sentence.text)
|
|
152
|
+
|| hasDirectClaimRetraction(sentence.text));
|
|
153
|
+
}
|
|
154
|
+
|
|
155
|
+
function explicitlyRejectsQuotedClaim(report: string): boolean {
|
|
156
|
+
for (const [, claim, response] of report.matchAll(QUOTED_CLAIM_PATTERN)) {
|
|
157
|
+
if ((KEPT_CURRENT_IMPLEMENTATION_PATTERN.test(claim!) || NO_CHANGE_MADE_PATTERN.test(claim!))
|
|
158
|
+
&& NO_BETTER_CHANGE_QUALIFIER_PATTERN.test(response!)
|
|
159
|
+
&& QUOTED_CLAIM_REFERENCE_PATTERN.test(response!)) return true;
|
|
160
|
+
}
|
|
161
|
+
return false;
|
|
162
|
+
}
|
|
163
|
+
|
|
164
|
+
function isImplementationChallengeTask(task: string): boolean {
|
|
165
|
+
const followUp = task.replace(REVIVED_TASK_PREFIX, "");
|
|
166
|
+
return followUp !== task && IMPLEMENTATION_CHALLENGE_FOLLOW_UP_PATTERN.test(followUp.trim());
|
|
167
|
+
}
|
|
168
|
+
|
|
169
|
+
function reportsNoBetterChallengeChange(messages: Message[]): boolean {
|
|
170
|
+
const report = messages
|
|
171
|
+
.filter((message) => message.role === "assistant")
|
|
172
|
+
.flatMap((message) => message.content)
|
|
173
|
+
.flatMap((part) => part.type === "text" ? [part.text] : [])
|
|
174
|
+
.join("\n");
|
|
175
|
+
if (explicitlyRejectsQuotedClaim(report)) return false;
|
|
176
|
+
const sentences = Array.from(report.matchAll(REPORT_SENTENCE_PATTERN), (match) => ({
|
|
177
|
+
text: match[0],
|
|
178
|
+
offset: match.index!,
|
|
179
|
+
}));
|
|
180
|
+
const noBetterIndex = unqualifiedClaimIndex(report, sentences, NO_BETTER_CHANGE_NEEDED_PATTERN);
|
|
181
|
+
if (noBetterIndex >= 0) return !hasLaterClaimRetraction(sentences, noBetterIndex);
|
|
182
|
+
const keptIndex = unqualifiedClaimIndex(report, sentences, KEPT_CURRENT_IMPLEMENTATION_PATTERN);
|
|
183
|
+
const noChangeIndex = unqualifiedClaimIndex(report, sentences, NO_CHANGE_MADE_PATTERN);
|
|
184
|
+
return keptIndex >= 0
|
|
185
|
+
&& noChangeIndex >= 0
|
|
186
|
+
&& !hasLaterClaimRetraction(sentences, Math.min(keptIndex, noChangeIndex));
|
|
187
|
+
}
|
|
188
|
+
|
|
85
189
|
export function evaluateCompletionMutationGuard(input: CompletionMutationGuardInput): CompletionMutationGuardResult {
|
|
86
190
|
const expectedMutation = hasMutationToolCapability(input.tools, input.mcpDirectTools)
|
|
87
191
|
? expectsImplementationMutation(input.agent, input.task)
|
|
88
192
|
: false;
|
|
89
193
|
const attemptedMutation = hasMutationToolCall(input.messages);
|
|
194
|
+
const noEditChallengeComplete = isImplementationChallengeTask(input.task)
|
|
195
|
+
&& reportsNoBetterChallengeChange(input.messages);
|
|
90
196
|
return {
|
|
91
197
|
expectedMutation,
|
|
92
198
|
attemptedMutation,
|
|
93
|
-
triggered: expectedMutation && !attemptedMutation,
|
|
199
|
+
triggered: expectedMutation && !attemptedMutation && !noEditChallengeComplete,
|
|
94
200
|
};
|
|
95
201
|
}
|
|
@@ -35,6 +35,8 @@ export function runExternalCli(input: {
|
|
|
35
35
|
timeoutMessage?: string;
|
|
36
36
|
stopMessage?: string;
|
|
37
37
|
onProcess?: (process: ExternalProcessStatus) => void;
|
|
38
|
+
onStdout?: (chunk: Buffer) => void;
|
|
39
|
+
onStderr?: (chunk: Buffer) => void;
|
|
38
40
|
}): Promise<ExternalCliRunResult> {
|
|
39
41
|
return new Promise((resolve, reject) => {
|
|
40
42
|
const startedAt = Date.now();
|
|
@@ -65,11 +67,13 @@ export function runExternalCli(input: {
|
|
|
65
67
|
input.onProcess?.(initialProcess);
|
|
66
68
|
child.stdout.on("data", (chunk: Buffer) => {
|
|
67
69
|
stdoutStream.write(chunk);
|
|
70
|
+
input.onStdout?.(chunk);
|
|
68
71
|
stdoutTail = Buffer.concat([stdoutTail, chunk]);
|
|
69
72
|
if (stdoutTail.length > MAX_OUTPUT_TAIL_BYTES) stdoutTail = stdoutTail.subarray(stdoutTail.length - MAX_OUTPUT_TAIL_BYTES);
|
|
70
73
|
});
|
|
71
74
|
child.stderr.on("data", (chunk: Buffer) => {
|
|
72
75
|
stderrStream.write(chunk);
|
|
76
|
+
input.onStderr?.(chunk);
|
|
73
77
|
stderrTail = Buffer.concat([stderrTail, chunk]);
|
|
74
78
|
if (stderrTail.length > MAX_ERROR_TAIL_BYTES) stderrTail = stderrTail.subarray(stderrTail.length - MAX_ERROR_TAIL_BYTES);
|
|
75
79
|
});
|
|
@@ -0,0 +1,302 @@
|
|
|
1
|
+
import { createHash } from "node:crypto";
|
|
2
|
+
import { Agent, type AgentTool, type StreamFn } from "@earendil-works/pi-agent-core";
|
|
3
|
+
import { convertToLlm, type ExtensionContext } from "@earendil-works/pi-coding-agent";
|
|
4
|
+
import { streamSimple } from "@earendil-works/pi-ai/compat";
|
|
5
|
+
import type { ProviderHeaders } from "@earendil-works/pi-ai";
|
|
6
|
+
import { Type, type Static } from "typebox";
|
|
7
|
+
import { agentStreamOptions } from "../../shared/agent-stream-options.ts";
|
|
8
|
+
|
|
9
|
+
/**
|
|
10
|
+
* LLM intent arbiter for the completion mutation guard.
|
|
11
|
+
*
|
|
12
|
+
* The regex classifier (task-intent.ts) is deliberately narrow, so exotic
|
|
13
|
+
* review wording can still look like an implementation task ("to fix this,
|
|
14
|
+
* compare the outputs", verbs inside URLs or quoted text). When the guard is
|
|
15
|
+
* about to hard-fail a run that made no edits, this arbiter asks a model
|
|
16
|
+
* whether the task actually instructed file changes. It can only downgrade a
|
|
17
|
+
* failure to a pass; every error, timeout, or non-read-only verdict keeps the
|
|
18
|
+
* guard's original behavior.
|
|
19
|
+
*
|
|
20
|
+
* Enabled by default; set PI_SUBAGENTS_LLM_INTENT_ARBITER=0 to disable.
|
|
21
|
+
*/
|
|
22
|
+
|
|
23
|
+
const COMPLETION_GUARD_ERROR_PREFIX =
|
|
24
|
+
"Subagent completed without making edits for an implementation task.";
|
|
25
|
+
|
|
26
|
+
export type TaskMutationVerdict = "read-only" | "implementation" | "unavailable";
|
|
27
|
+
|
|
28
|
+
export type TaskMutationArbiter = (task: string) => Promise<TaskMutationVerdict>;
|
|
29
|
+
|
|
30
|
+
const DecisionParams = Type.Object(
|
|
31
|
+
{
|
|
32
|
+
classification: Type.String({ enum: ["read_only", "implementation"] }),
|
|
33
|
+
confidence: Type.String({
|
|
34
|
+
enum: ["low", "medium", "high"],
|
|
35
|
+
description: "Confidence in the classification. Only read_only with high confidence rescues a failed run.",
|
|
36
|
+
}),
|
|
37
|
+
reason: Type.String({ description: "One concise reason for this classification." }),
|
|
38
|
+
},
|
|
39
|
+
{ additionalProperties: false },
|
|
40
|
+
);
|
|
41
|
+
|
|
42
|
+
type DecisionParams = Static<typeof DecisionParams>;
|
|
43
|
+
|
|
44
|
+
/** Map a model decision to a verdict. Only a high-confidence read_only rescues. */
|
|
45
|
+
export function mapArbiterDecision(
|
|
46
|
+
decision: { classification?: string; confidence?: string } | undefined,
|
|
47
|
+
): TaskMutationVerdict {
|
|
48
|
+
if (!decision) return "unavailable";
|
|
49
|
+
if (decision.classification === "read_only" && decision.confidence === "high") return "read-only";
|
|
50
|
+
return "implementation";
|
|
51
|
+
}
|
|
52
|
+
|
|
53
|
+
interface ArbiterRuntime {
|
|
54
|
+
model: NonNullable<RegistryModel>;
|
|
55
|
+
baseStreamFn: StreamFn;
|
|
56
|
+
timeoutMs: number;
|
|
57
|
+
}
|
|
58
|
+
|
|
59
|
+
interface ArbiterAuth {
|
|
60
|
+
apiKey?: string;
|
|
61
|
+
headers?: ProviderHeaders;
|
|
62
|
+
env?: Record<string, string>;
|
|
63
|
+
}
|
|
64
|
+
|
|
65
|
+
export interface TaskMutationArbiterOptions {
|
|
66
|
+
/** Explicit "provider/id" model override (tests, config). */
|
|
67
|
+
model?: string;
|
|
68
|
+
/** Injectable stream function (tests). */
|
|
69
|
+
streamFn?: StreamFn;
|
|
70
|
+
timeoutMs?: number;
|
|
71
|
+
}
|
|
72
|
+
|
|
73
|
+
const DEFAULT_ARBITER_TIMEOUT_MS = 10_000;
|
|
74
|
+
|
|
75
|
+
type RegistryModel = ReturnType<NonNullable<ExtensionContext["modelRegistry"]["find"]>>;
|
|
76
|
+
|
|
77
|
+
function resolveArbiterModel(
|
|
78
|
+
ctx: ExtensionContext,
|
|
79
|
+
options?: TaskMutationArbiterOptions,
|
|
80
|
+
): NonNullable<RegistryModel> | null {
|
|
81
|
+
const registry = ctx.modelRegistry as {
|
|
82
|
+
find?: (provider: string, modelId: string) => RegistryModel | undefined;
|
|
83
|
+
getAvailable?: () => Array<{ provider?: string; id?: string }>;
|
|
84
|
+
};
|
|
85
|
+
const explicit = options?.model?.trim();
|
|
86
|
+
if (explicit) {
|
|
87
|
+
const [provider, id] = explicit.split("/");
|
|
88
|
+
if (provider && id) return registry.find?.(provider, id) ?? null;
|
|
89
|
+
return null;
|
|
90
|
+
}
|
|
91
|
+
if (ctx.model) return ctx.model as NonNullable<RegistryModel>;
|
|
92
|
+
const first = registry.getAvailable?.()[0];
|
|
93
|
+
if (first?.provider && first.id) return registry.find?.(first.provider, first.id) ?? null;
|
|
94
|
+
return null;
|
|
95
|
+
}
|
|
96
|
+
|
|
97
|
+
function resolveArbiterRuntime(
|
|
98
|
+
ctx: ExtensionContext,
|
|
99
|
+
options?: TaskMutationArbiterOptions,
|
|
100
|
+
): ArbiterRuntime | null {
|
|
101
|
+
const model = resolveArbiterModel(ctx, options);
|
|
102
|
+
if (!model?.provider || !model.id) return null;
|
|
103
|
+
const registry = ctx.modelRegistry as {
|
|
104
|
+
getRegisteredProviderConfig?: (provider: string) => { api?: string; streamSimple?: StreamFn } | undefined;
|
|
105
|
+
};
|
|
106
|
+
const modelApi = (model as { api?: string }).api;
|
|
107
|
+
const registered = registry.getRegisteredProviderConfig?.(model.provider);
|
|
108
|
+
const baseStreamFn = options?.streamFn
|
|
109
|
+
?? (registered?.streamSimple && registered.api === modelApi
|
|
110
|
+
? registered.streamSimple
|
|
111
|
+
: streamSimple);
|
|
112
|
+
return {
|
|
113
|
+
model,
|
|
114
|
+
baseStreamFn,
|
|
115
|
+
timeoutMs: options?.timeoutMs ?? DEFAULT_ARBITER_TIMEOUT_MS,
|
|
116
|
+
};
|
|
117
|
+
}
|
|
118
|
+
|
|
119
|
+
async function resolveArbiterAuth(
|
|
120
|
+
ctx: ExtensionContext,
|
|
121
|
+
model: RegistryModel,
|
|
122
|
+
): Promise<ArbiterAuth> {
|
|
123
|
+
const registry = ctx.modelRegistry as {
|
|
124
|
+
getApiKeyAndHeaders?: (m: RegistryModel) => Promise<{
|
|
125
|
+
ok: boolean;
|
|
126
|
+
apiKey?: string;
|
|
127
|
+
headers?: ProviderHeaders;
|
|
128
|
+
env?: Record<string, string>;
|
|
129
|
+
error?: string;
|
|
130
|
+
}>;
|
|
131
|
+
};
|
|
132
|
+
// Call as a METHOD on the registry: the host ModelRegistry implementation
|
|
133
|
+
// is a class whose method reads instance state (this.runtime), so a
|
|
134
|
+
// detached call silently fails auth. Same shape as the watchdog.
|
|
135
|
+
if (!registry.getApiKeyAndHeaders) return {};
|
|
136
|
+
try {
|
|
137
|
+
const auth = await registry.getApiKeyAndHeaders(model);
|
|
138
|
+
if (auth.ok === false) return {};
|
|
139
|
+
return {
|
|
140
|
+
...(auth.apiKey ? { apiKey: auth.apiKey } : {}),
|
|
141
|
+
...(auth.headers ? { headers: auth.headers } : {}),
|
|
142
|
+
...(auth.env ? { env: auth.env } : {}),
|
|
143
|
+
};
|
|
144
|
+
} catch {
|
|
145
|
+
return {};
|
|
146
|
+
}
|
|
147
|
+
}
|
|
148
|
+
|
|
149
|
+
/** Build the effective stream function with resolved credentials wrapped in (watchdog pattern). */
|
|
150
|
+
function authWrappedStreamFn(
|
|
151
|
+
base: StreamFn,
|
|
152
|
+
auth: ArbiterAuth,
|
|
153
|
+
): StreamFn {
|
|
154
|
+
return (model, context, streamOptions) => base(model, context, {
|
|
155
|
+
...(streamOptions ?? {}),
|
|
156
|
+
...(auth.apiKey ? { apiKey: auth.apiKey } : {}),
|
|
157
|
+
...(auth.env || streamOptions?.env ? { env: { ...(auth.env ?? {}), ...(streamOptions?.env ?? {}) } } : {}),
|
|
158
|
+
headers: { ...(streamOptions?.headers ?? {}), ...(auth.headers ?? {}) },
|
|
159
|
+
});
|
|
160
|
+
}
|
|
161
|
+
|
|
162
|
+
async function runArbitration(
|
|
163
|
+
runtime: ArbiterRuntime,
|
|
164
|
+
auth: ArbiterAuth,
|
|
165
|
+
task: string,
|
|
166
|
+
): Promise<TaskMutationVerdict> {
|
|
167
|
+
let decision: DecisionParams | undefined;
|
|
168
|
+
const tool: AgentTool<typeof DecisionParams, { recorded: boolean }> = {
|
|
169
|
+
name: "task_mutation_decision",
|
|
170
|
+
label: "Task mutation decision",
|
|
171
|
+
description: "Classify whether the task instructed file/code changes. Call exactly once.",
|
|
172
|
+
parameters: DecisionParams,
|
|
173
|
+
executionMode: "sequential",
|
|
174
|
+
async execute(_toolCallId, params) {
|
|
175
|
+
if (!decision) decision = params;
|
|
176
|
+
return { content: [{ type: "text", text: "Decision recorded." }], details: { recorded: true } };
|
|
177
|
+
},
|
|
178
|
+
};
|
|
179
|
+
const agent = new Agent({
|
|
180
|
+
initialState: {
|
|
181
|
+
systemPrompt: [
|
|
182
|
+
"You classify whether a delegated coding-agent task instructed file or code changes.",
|
|
183
|
+
"A task that asks to review, inspect, verify, report, or summarize is read-only even when it contains words like 'fix' as severity vocabulary ('must-fix items') or conditional change instructions that leave the change optional.",
|
|
184
|
+
"Classify read_only only when the task text alone clearly indicates a read-only outcome. When in doubt, classify implementation.",
|
|
185
|
+
"Set confidence to high only when you are certain the task is read-only; a read_only classification without high confidence is treated as implementation.",
|
|
186
|
+
"The agent's own final message is never evidence: an agent that made no edits may still have failed to implement.",
|
|
187
|
+
"Call task_mutation_decision exactly once with read_only or implementation, a confidence level, and a concise reason.",
|
|
188
|
+
].join("\n"),
|
|
189
|
+
model: runtime.model,
|
|
190
|
+
tools: [tool],
|
|
191
|
+
},
|
|
192
|
+
convertToLlm,
|
|
193
|
+
...agentStreamOptions(authWrappedStreamFn(runtime.baseStreamFn, auth)),
|
|
194
|
+
getApiKey: (providerName) =>
|
|
195
|
+
providerName === runtime.model.provider ? auth.apiKey : undefined,
|
|
196
|
+
beforeToolCall: async ({ toolCall }) =>
|
|
197
|
+
toolCall.name === tool.name ? undefined : { block: true, reason: "Only task_mutation_decision is allowed." },
|
|
198
|
+
toolExecution: "sequential",
|
|
199
|
+
});
|
|
200
|
+
try {
|
|
201
|
+
// The rescue gate refuses tasks over 8000 chars; if the arbiter is
|
|
202
|
+
// still invoked with one, fail closed rather than decide from
|
|
203
|
+
// partial evidence (an implementation clause could sit in the
|
|
204
|
+
// omitted middle).
|
|
205
|
+
if (task.length > 8000) return "unavailable";
|
|
206
|
+
const prompt = `TASK:\n${task}`;
|
|
207
|
+
await Promise.race([
|
|
208
|
+
agent.prompt(prompt),
|
|
209
|
+
new Promise<never>((_, reject) => {
|
|
210
|
+
const timeout = setTimeout(() => {
|
|
211
|
+
agent.abort();
|
|
212
|
+
reject(new Error("Task mutation arbiter timed out."));
|
|
213
|
+
}, runtime.timeoutMs);
|
|
214
|
+
timeout.unref?.();
|
|
215
|
+
}),
|
|
216
|
+
]);
|
|
217
|
+
if (!decision) return "unavailable";
|
|
218
|
+
return mapArbiterDecision(decision);
|
|
219
|
+
} catch {
|
|
220
|
+
return "unavailable";
|
|
221
|
+
}
|
|
222
|
+
}
|
|
223
|
+
|
|
224
|
+
/** Create a memoized arbiter bound to the parent session's model, or undefined when disabled/unavailable. */
|
|
225
|
+
export function createTaskMutationArbiter(
|
|
226
|
+
ctx: ExtensionContext,
|
|
227
|
+
options?: TaskMutationArbiterOptions,
|
|
228
|
+
): TaskMutationArbiter | undefined {
|
|
229
|
+
if (process.env.PI_SUBAGENTS_LLM_INTENT_ARBITER === "0") return undefined;
|
|
230
|
+
const runtime = resolveArbiterRuntime(ctx, options);
|
|
231
|
+
if (!runtime) return undefined;
|
|
232
|
+
const cache = new Map<string, TaskMutationVerdict>();
|
|
233
|
+
return async (task) => {
|
|
234
|
+
const key = createHash("sha256").update(task).digest("base64url");
|
|
235
|
+
const cached = cache.get(key);
|
|
236
|
+
if (cached) return cached;
|
|
237
|
+
const auth = await resolveArbiterAuth(ctx, runtime.model);
|
|
238
|
+
const verdict = await runArbitration(runtime, auth, task);
|
|
239
|
+
if (cache.size > 200) cache.clear();
|
|
240
|
+
cache.set(key, verdict);
|
|
241
|
+
return verdict;
|
|
242
|
+
};
|
|
243
|
+
}
|
|
244
|
+
|
|
245
|
+
export function isCompletionGuardFailure(result: { error?: string }): boolean {
|
|
246
|
+
return result.error?.startsWith(COMPLETION_GUARD_ERROR_PREFIX) === true;
|
|
247
|
+
}
|
|
248
|
+
|
|
249
|
+
export async function arbitrateCompletionGuardRescue(input: {
|
|
250
|
+
guardTriggered: boolean;
|
|
251
|
+
task: string;
|
|
252
|
+
arbiter?: TaskMutationArbiter;
|
|
253
|
+
}): Promise<{ triggered: boolean; rescued: boolean }> {
|
|
254
|
+
if (!input.guardTriggered || !input.arbiter) {
|
|
255
|
+
return { triggered: input.guardTriggered, rescued: false };
|
|
256
|
+
}
|
|
257
|
+
// Never decide from partial evidence: refuse tasks over 8000 chars before
|
|
258
|
+
// even consulting the model.
|
|
259
|
+
if (input.task.length > 8000) {
|
|
260
|
+
return { triggered: true, rescued: false };
|
|
261
|
+
}
|
|
262
|
+
try {
|
|
263
|
+
const verdict = await input.arbiter(input.task);
|
|
264
|
+
if (verdict === "read-only") return { triggered: false, rescued: true };
|
|
265
|
+
return { triggered: true, rescued: false };
|
|
266
|
+
} catch {
|
|
267
|
+
return { triggered: true, rescued: false };
|
|
268
|
+
}
|
|
269
|
+
}
|
|
270
|
+
|
|
271
|
+
/**
|
|
272
|
+
* When the completion guard hard-failed a run and the arbiter classifies the
|
|
273
|
+
* task as read-only, clear the failure. Returns true when rescued. All other
|
|
274
|
+
* verdicts and every failure mode keep the original guard behavior.
|
|
275
|
+
*
|
|
276
|
+
* Classification uses the task text only: the agent's own final message is
|
|
277
|
+
* never evidence, so a child that failed to implement cannot talk its way
|
|
278
|
+
* out of the guard by claiming the work was read-only.
|
|
279
|
+
*/
|
|
280
|
+
export async function maybeRescueCompletionGuardFailure(
|
|
281
|
+
result: { exitCode?: number; error?: string },
|
|
282
|
+
task: string,
|
|
283
|
+
arbiter: TaskMutationArbiter | undefined,
|
|
284
|
+
): Promise<boolean> {
|
|
285
|
+
if (!arbiter || !isCompletionGuardFailure(result)) return false;
|
|
286
|
+
const verdict = await arbitrateWithGuard(arbiter, task);
|
|
287
|
+
if (verdict !== "read-only") return false;
|
|
288
|
+
result.exitCode = 0;
|
|
289
|
+
delete result.error;
|
|
290
|
+
return true;
|
|
291
|
+
}
|
|
292
|
+
|
|
293
|
+
async function arbitrateWithGuard(
|
|
294
|
+
arbiter: TaskMutationArbiter,
|
|
295
|
+
task: string,
|
|
296
|
+
): Promise<TaskMutationVerdict> {
|
|
297
|
+
try {
|
|
298
|
+
return await arbiter(task);
|
|
299
|
+
} catch {
|
|
300
|
+
return "unavailable";
|
|
301
|
+
}
|
|
302
|
+
}
|
|
@@ -163,6 +163,20 @@ export function resolveModelCandidate(
|
|
|
163
163
|
return model;
|
|
164
164
|
}
|
|
165
165
|
|
|
166
|
+
function resolveRequiredSubagentModelCandidate(
|
|
167
|
+
model: string,
|
|
168
|
+
availableModels: AvailableModelInfo[] | undefined,
|
|
169
|
+
preferredProvider?: string,
|
|
170
|
+
): string {
|
|
171
|
+
if (!availableModels || availableModels.length === 0) return model;
|
|
172
|
+
const resolvedWhole = resolveBaseModelCandidate(model, availableModels, preferredProvider);
|
|
173
|
+
if (resolvedWhole) return resolvedWhole;
|
|
174
|
+
const { baseModel, thinkingSuffix } = splitThinkingSuffix(model);
|
|
175
|
+
const resolvedBase = thinkingSuffix ? resolveBaseModelCandidate(baseModel, availableModels, preferredProvider) : undefined;
|
|
176
|
+
if (resolvedBase) return `${resolvedBase}${thinkingSuffix}`;
|
|
177
|
+
throw new Error(`Unknown subagent model '${model}' in the active Pi model registry.`);
|
|
178
|
+
}
|
|
179
|
+
|
|
166
180
|
export interface ResolveSubagentModelOverrideOptions {
|
|
167
181
|
/** When set with `enforce: true`, out-of-scope models are rejected. */
|
|
168
182
|
scope?: ModelScopeConfig;
|
|
@@ -207,7 +221,7 @@ export function resolveSubagentModelOverride(
|
|
|
207
221
|
if (explicit === undefined) {
|
|
208
222
|
resolved = parentModel ? `${parentModel.provider}/${parentModel.id}` : undefined;
|
|
209
223
|
} else {
|
|
210
|
-
resolved =
|
|
224
|
+
resolved = resolveRequiredSubagentModelCandidate(explicit, availableModels, preferredProvider);
|
|
211
225
|
}
|
|
212
226
|
if (resolved && options?.scope?.enforce) {
|
|
213
227
|
const source: ModelSource = explicit === undefined ? "inherited" : (options.source ?? "inherited");
|
|
@@ -264,7 +278,7 @@ export function buildModelCandidates(
|
|
|
264
278
|
for (let index = 0; index < rawCandidates.length; index++) {
|
|
265
279
|
const raw = rawCandidates[index];
|
|
266
280
|
if (!raw) continue;
|
|
267
|
-
const normalized =
|
|
281
|
+
const normalized = resolveRequiredSubagentModelCandidate(raw.trim(), availableModels, preferredProvider);
|
|
268
282
|
if (!normalized || seen.has(normalized)) continue;
|
|
269
283
|
if ((index > 0 || options?.scope?.strict === true) && options?.scope?.enforce) {
|
|
270
284
|
const violation = checkModelScope(normalized, options.scope, "inherited");
|