@xzzpig/pi-subagents 0.7.0 → 0.8.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.
Files changed (86) hide show
  1. package/CHANGELOG.md +13 -4
  2. package/README.md +1 -1
  3. package/agents/reviewer.md +12 -2
  4. package/docs/agents.md +4 -4
  5. package/docs/configuration.md +6 -6
  6. package/docs/extension-api.md +14 -4
  7. package/docs/models.md +47 -6
  8. package/docs/observability.md +14 -3
  9. package/docs/tool-reference.md +21 -6
  10. package/docs/workflows.md +7 -1
  11. package/index.ts +10 -1
  12. package/package.json +3 -3
  13. package/prompts/council.md +19 -7
  14. package/prompts/parallel-review.md +5 -1
  15. package/prompts/review-loop.md +9 -5
  16. package/skills/council-mode/SKILL.md +50 -26
  17. package/skills/pi-subagents/SKILL.md +5 -1
  18. package/skills/pi-subagents/references/constraints-and-recipes.md +16 -1
  19. package/skills/pi-subagents/references/execution-controls.md +13 -4
  20. package/skills/pi-subagents/references/multi-lane-orchestration.md +3 -3
  21. package/skills/pi-subagents/references/prompting-and-roles.md +14 -7
  22. package/src/agents/agent-management.ts +115 -14
  23. package/src/agents/agent-serializer.ts +4 -2
  24. package/src/agents/agents.ts +226 -48
  25. package/src/api/external-job-provider.ts +10 -1
  26. package/src/api/preflight.ts +52 -19
  27. package/src/api/project-panes.ts +2 -0
  28. package/src/extension/doctor.ts +10 -0
  29. package/src/extension/fanout-child.ts +3 -2
  30. package/src/extension/index.ts +24 -4
  31. package/src/extension/public-execution.ts +12 -9
  32. package/src/extension/rpc.ts +77 -3
  33. package/src/extension/schemas.ts +7 -1
  34. package/src/extension/tool-description.ts +9 -6
  35. package/src/extension/tool-result.ts +19 -0
  36. package/src/inspectors/herdr/client.ts +3 -3
  37. package/src/inspectors/herdr/focus.ts +55 -0
  38. package/src/inspectors/herdr/project-panes.ts +228 -44
  39. package/src/integrations/herdr-status.ts +26 -4
  40. package/src/runs/background/async-execution.ts +146 -17
  41. package/src/runs/background/async-job-tracker.ts +33 -14
  42. package/src/runs/background/async-resume.ts +23 -2
  43. package/src/runs/background/async-retention.ts +1 -1
  44. package/src/runs/background/async-status.ts +10 -0
  45. package/src/runs/background/chain-root-attachment.ts +5 -0
  46. package/src/runs/background/control-channel.ts +98 -10
  47. package/src/runs/background/notify.ts +62 -1
  48. package/src/runs/background/result-watcher.ts +4 -3
  49. package/src/runs/background/run-status.ts +15 -1
  50. package/src/runs/background/stale-run-reconciler.ts +3 -0
  51. package/src/runs/background/subagent-runner.ts +333 -48
  52. package/src/runs/background/wait-completions.ts +2 -0
  53. package/src/runs/background/wait-tool.ts +4 -3
  54. package/src/runs/foreground/async-stop-action.ts +23 -2
  55. package/src/runs/foreground/execution.ts +148 -13
  56. package/src/runs/foreground/foreground-history.ts +3 -2
  57. package/src/runs/foreground/subagent-executor.ts +417 -50
  58. package/src/runs/foreground/workflow-detach-reconcile.ts +18 -6
  59. package/src/runs/shared/acceptance.ts +11 -5
  60. package/src/runs/shared/agent-contract.ts +1 -1
  61. package/src/runs/shared/child-identity.ts +36 -0
  62. package/src/runs/shared/completion-guard.ts +52 -2
  63. package/src/runs/shared/dynamic-fanout.ts +1 -1
  64. package/src/runs/shared/extension-bindings.ts +78 -0
  65. package/src/runs/shared/external-cli-runner.ts +2 -0
  66. package/src/runs/shared/external-job-bridge.ts +53 -37
  67. package/src/runs/shared/external-job-runner.ts +126 -23
  68. package/src/runs/shared/fast-mode-extension.ts +10 -0
  69. package/src/runs/shared/model-exclusions.ts +2 -1
  70. package/src/runs/shared/model-fallback.ts +48 -22
  71. package/src/runs/shared/model-scope.ts +106 -39
  72. package/src/runs/shared/mutation-evidence.ts +145 -0
  73. package/src/runs/shared/orca-progress-tabs.ts +71 -9
  74. package/src/runs/shared/parallel-utils.ts +15 -0
  75. package/src/runs/shared/pi-args.ts +78 -1
  76. package/src/runs/shared/structured-output.ts +18 -4
  77. package/src/runs/shared/subagent-prompt-runtime.ts +48 -15
  78. package/src/runs/shared/tool-availability.ts +1 -3
  79. package/src/shared/launch-contract.ts +12 -5
  80. package/src/shared/settings.ts +6 -1
  81. package/src/shared/thinking-ceiling.ts +52 -0
  82. package/src/shared/types.ts +120 -5
  83. package/src/tui/fleet-status.ts +66 -13
  84. package/src/tui/render.ts +5 -4
  85. package/src/watchdog/permission-arbiter.ts +59 -52
  86. package/src/workflows/scripted-workflow.ts +156 -12
@@ -8,9 +8,10 @@ import { decodePermissionRules, permissionDecision, PERMISSION_AUDIT_PATH_ENV, P
8
8
  import { consumeSteerRequestsFromDir, MAX_STEER_QUEUE_SIZE, steerAckPathFromDir, writeSteerAckAt, writeSteerCapabilityAt, writeSteerRequestToDir, type SteerDeliveryStatus, type SteerRequest } from "../background/control-channel.ts";
9
9
  import { SUBAGENT_CHILD_AGENT_ENV, SUBAGENT_CHILD_INDEX_ENV, SUBAGENT_FANOUT_CHILD_ENV, SUBAGENT_STEER_ACK_DIR_ENV, SUBAGENT_STEER_CAPABILITY_ENV, SUBAGENT_STEER_INBOX_ENV } from "./pi-args.ts";
10
10
  import { RUNTIME_EXTENSION_ACK_EVENT, RUNTIME_EXTENSION_ACK_PATH_ENV, isRuntimeAcknowledgedExtensionId, writeRuntimeAcknowledgedExtensions } from "./runtime-acknowledged-extensions.ts";
11
- import { createStructuredOutputToolParameters, STRUCTURED_OUTPUT_CAPTURE_ENV, STRUCTURED_OUTPUT_SCHEMA_ENV, validateStructuredOutputValue } from "./structured-output.ts";
11
+ import { createStructuredOutputToolParameters, STRUCTURED_OUTPUT_ACCEPTANCE_CAPTURE_ENV, STRUCTURED_OUTPUT_CAPTURE_ENV, STRUCTURED_OUTPUT_SCHEMA_ENV, validateStructuredOutputValue } from "./structured-output.ts";
12
12
  import {
13
13
  CHILD_TOOL_DIAGNOSTIC_PATH_ENV,
14
+ formatChildToolDiagnostic,
14
15
  MCP_DIRECT_CHILD_TOOLS_ENV,
15
16
  REQUIRED_CHILD_TOOLS_ENV,
16
17
  writeChildToolDiagnostic,
@@ -21,7 +22,7 @@ import type { JsonSchemaObject, ResolvedToolBudget, SubagentState } from "../../
21
22
  import { resolveCurrentSessionId } from "../../shared/session-identity.ts";
22
23
  import { resolveWatchPath } from "../../shared/utils.ts";
23
24
  import { registerChildWatchdog } from "../../watchdog/register-child.ts";
24
- import { CHILD_WATCHDOG_CONFIG_ENV } from "../../watchdog/child-status.ts";
25
+ import { CHILD_WATCHDOG_CONFIG_ENV, decodeChildWatchdogConfig } from "../../watchdog/child-status.ts";
25
26
  import { requestWatchdogPermission, type WatchdogPermissionRequest, type WatchdogPermissionResult } from "../../watchdog/permission-arbiter.ts";
26
27
  import { SUBAGENT_WATCHDOG_WARNING_TYPE } from "../../watchdog/types.ts";
27
28
  import { resolveWaitToolConfig } from "../background/wait-config.ts";
@@ -296,14 +297,41 @@ export function registerPermissionGate(
296
297
  const decision = permissionDecision(rules, toolName);
297
298
  if (decision === "allow") return undefined;
298
299
  if (decision === "deny") return { block: true, reason: `Blocked by pi-subagents permission rule: '${toolName}' is denied.` };
299
- const result = await requestPermission({
300
- ctx,
301
- toolName,
302
- args: event.input ?? {},
303
- rawWatchdogConfig: process.env[CHILD_WATCHDOG_CONFIG_ENV],
304
- auditPath: process.env[PERMISSION_AUDIT_PATH_ENV],
305
- ...(ctx.signal ? { signal: ctx.signal } : {}),
306
- });
300
+ const rawWatchdogConfig = process.env[CHILD_WATCHDOG_CONFIG_ENV];
301
+ let timeoutMs = 30_000;
302
+ try {
303
+ timeoutMs = decodeChildWatchdogConfig(rawWatchdogConfig)?.agentEndTimeoutMs ?? timeoutMs;
304
+ } catch {
305
+ // The arbiter reports invalid configuration with the concrete decode error.
306
+ }
307
+ if (ctx.signal?.aborted) return { block: true, reason: "Blocked by pi-subagents permission rule: Watchdog permission decision was cancelled." };
308
+ let timeout: ReturnType<typeof setTimeout> | undefined;
309
+ let abort: (() => void) | undefined;
310
+ let result: WatchdogPermissionResult;
311
+ try {
312
+ result = await Promise.race([
313
+ requestPermission({
314
+ ctx,
315
+ toolName,
316
+ args: event.input ?? {},
317
+ rawWatchdogConfig,
318
+ auditPath: process.env[PERMISSION_AUDIT_PATH_ENV],
319
+ ...(ctx.signal ? { signal: ctx.signal } : {}),
320
+ }),
321
+ new Promise<WatchdogPermissionResult>((resolve) => {
322
+ if (!ctx.signal) return;
323
+ abort = () => resolve({ approved: false, reason: "Watchdog permission decision was cancelled.", source: "watchdog" });
324
+ ctx.signal.addEventListener("abort", abort, { once: true });
325
+ }),
326
+ new Promise<never>((_, reject) => { timeout = setTimeout(() => reject(new Error(`Watchdog permission decision timed out after ${timeoutMs}ms.`)), timeoutMs); }),
327
+ ]);
328
+ } catch (error) {
329
+ const reason = error instanceof Error ? error.message : String(error);
330
+ return { block: true, reason: `Blocked by pi-subagents permission rule: Watchdog permission arbiter failed closed: ${reason}` };
331
+ } finally {
332
+ if (timeout) clearTimeout(timeout);
333
+ if (abort) ctx.signal?.removeEventListener("abort", abort);
334
+ }
307
335
  if (result.approved) return undefined;
308
336
  return { block: true, reason: `Blocked by pi-subagents permission rule: ${result.reason}` };
309
337
  });
@@ -598,36 +626,41 @@ export default function registerSubagentPromptRuntime(pi: ExtensionAPI): void {
598
626
  registerNativeSupervisorClientOnce();
599
627
  });
600
628
  onRuntimeEvent("agent_start", () => {
601
- refreshChildToolDiagnostic(pi);
629
+ const diagnostic = refreshChildToolDiagnostic(pi);
630
+ if (diagnostic) throw new Error(formatChildToolDiagnostic(diagnostic));
602
631
  });
603
632
  onRuntimeEvent("agent_end", async (_event: unknown, ctx: unknown) => {
604
633
  if ((ctx as { hasUI?: boolean } | undefined)?.hasUI === true) return;
605
634
  await drainOutstandingWork({ state: waitState, events: pi.events });
606
635
  });
607
636
  const structuredOutputPath = process.env[STRUCTURED_OUTPUT_CAPTURE_ENV];
637
+ const structuredAcceptanceReportPath = process.env[STRUCTURED_OUTPUT_ACCEPTANCE_CAPTURE_ENV];
608
638
  const structuredSchemaPath = process.env[STRUCTURED_OUTPUT_SCHEMA_ENV];
609
639
  if (structuredOutputPath && structuredSchemaPath) {
610
640
  const schema = JSON.parse(fs.readFileSync(structuredSchemaPath, "utf-8")) as JsonSchemaObject;
611
- const parameters = createStructuredOutputToolParameters(schema);
641
+ const parameters = createStructuredOutputToolParameters(schema, { acceptanceReport: Boolean(structuredAcceptanceReportPath) });
612
642
  const registerTool = pi.registerTool as unknown as (tool: {
613
643
  name: string;
614
644
  label: string;
615
645
  description: string;
616
646
  parameters: unknown;
617
- execute: (_id: string, params: { value: unknown }) => Promise<unknown>;
647
+ execute: (_id: string, params: { value: unknown; acceptanceReport?: unknown }) => Promise<unknown>;
618
648
  }) => void;
619
649
  registerTool({
620
650
  name: "structured_output",
621
651
  label: "Structured Output",
622
652
  description: "Submit the required final structured output for this subagent step. This terminates the step.",
623
- parameters: parameters as never,
624
- async execute(_id: string, params: { value: unknown }) {
653
+ parameters,
654
+ async execute(_id: string, params: { value: unknown; acceptanceReport?: unknown }) {
625
655
  const validation = await validateStructuredOutputValue(schema, params.value);
626
656
  if (validation.status === "invalid") {
627
657
  throw new Error(`Structured output validation failed: ${validation.message}`);
628
658
  }
629
659
  fs.mkdirSync(path.dirname(structuredOutputPath), { recursive: true });
630
660
  fs.writeFileSync(structuredOutputPath, JSON.stringify(params.value), { mode: 0o600 });
661
+ if (structuredAcceptanceReportPath && params.acceptanceReport !== undefined) {
662
+ fs.writeFileSync(structuredAcceptanceReportPath, JSON.stringify(params.acceptanceReport), { mode: 0o600 });
663
+ }
631
664
  return {
632
665
  content: [{ type: "text", text: "Structured output captured." }],
633
666
  details: { path: structuredOutputPath },
@@ -13,8 +13,6 @@ export interface ChildToolDiagnostic {
13
13
  missingMcpDirectTools?: string[];
14
14
  }
15
15
 
16
- const PI_CORE_CHILD_TOOLS = new Set(["bash", "edit", "find", "grep", "ls", "read", "write"]);
17
-
18
16
  export function writeChildToolDiagnostic(
19
17
  filePath: string,
20
18
  required: string[],
@@ -22,7 +20,7 @@ export function writeChildToolDiagnostic(
22
20
  agent?: string,
23
21
  mcpDirectTools?: string[],
24
22
  ): ChildToolDiagnostic | undefined {
25
- const availableNames = new Set([...available, ...PI_CORE_CHILD_TOOLS]);
23
+ const availableNames = new Set(available);
26
24
  const missing = required.filter((name) => !availableNames.has(name));
27
25
  if (missing.length === 0) {
28
26
  fs.rmSync(filePath, { force: true });
@@ -1,6 +1,7 @@
1
1
  import { createHash } from "node:crypto";
2
2
  import * as fs from "node:fs";
3
3
  import type { AgentConfig } from "../agents/agents.ts";
4
+ import type { ExtensionBindings } from "../runs/shared/extension-bindings.ts";
4
5
 
5
6
  export const AGENT_DEFINITION_PROJECTION_VERSION = 1 as const;
6
7
  export const LAUNCH_BINDING_PROJECTION_VERSION = 1 as const;
@@ -17,7 +18,7 @@ function stableJson(value: unknown): string {
17
18
  return JSON.stringify(value);
18
19
  }
19
20
 
20
- function sha256(value: unknown): string {
21
+ export function stableJsonDigest(value: unknown): string {
21
22
  return createHash("sha256").update(stableJson(value)).digest("hex");
22
23
  }
23
24
 
@@ -44,7 +45,9 @@ export function projectAgentDefinition(agent: AgentConfig): Record<string, unkno
44
45
  inheritProjectContext: agent.inheritProjectContext,
45
46
  inheritSkills: agent.inheritSkills,
46
47
  model: agent.model,
48
+ modelProvider: agent.modelProvider,
47
49
  fallbackModels: agent.fallbackModels,
50
+ fast: agent.fast,
48
51
  thinking: agent.thinking,
49
52
  tools: agent.tools,
50
53
  mcpDirectTools: agent.mcpDirectTools,
@@ -70,7 +73,7 @@ export function projectAgentDefinition(agent: AgentConfig): Record<string, unkno
70
73
  }
71
74
 
72
75
  export function agentDefinitionDigest(agent: AgentConfig): string {
73
- return sha256(projectAgentDefinition(agent));
76
+ return stableJsonDigest(projectAgentDefinition(agent));
74
77
  }
75
78
 
76
79
  export interface LaunchBindingInput {
@@ -79,6 +82,7 @@ export interface LaunchBindingInput {
79
82
  task?: string;
80
83
  model?: string;
81
84
  modelCandidates?: string[];
85
+ fast?: boolean;
82
86
  thinking?: string;
83
87
  systemPrompt?: string | null;
84
88
  systemPromptMode?: AgentConfig["systemPromptMode"];
@@ -92,6 +96,7 @@ export interface LaunchBindingInput {
92
96
  outputPath?: string;
93
97
  outputMode?: string;
94
98
  structuredOutputSchema?: unknown;
99
+ extensionBindings?: ExtensionBindings;
95
100
  }
96
101
 
97
102
  /** Canonical projection of the resolved inputs handed to the child. */
@@ -99,12 +104,13 @@ export function projectLaunchBinding(input: LaunchBindingInput): Record<string,
99
104
  return {
100
105
  version: LAUNCH_BINDING_PROJECTION_VERSION,
101
106
  definitionDigest: input.definitionDigest,
102
- taskDigest: input.task === undefined ? undefined : sha256(input.task),
107
+ taskDigest: input.task === undefined ? undefined : stableJsonDigest(input.task),
103
108
  // The ordered candidate set already contains each attempted model; keeping only
104
109
  // this set makes retries correlate to the same preflight binding.
105
110
  modelCandidates: input.modelCandidates,
111
+ fast: input.fast,
106
112
  thinking: input.thinking,
107
- systemPromptDigest: input.systemPrompt === undefined || input.systemPrompt === null ? undefined : sha256(input.systemPrompt),
113
+ systemPromptDigest: input.systemPrompt === undefined || input.systemPrompt === null ? undefined : stableJsonDigest(input.systemPrompt),
108
114
  systemPromptMode: input.systemPromptMode,
109
115
  inheritProjectContext: input.inheritProjectContext,
110
116
  inheritSkills: input.inheritSkills,
@@ -116,9 +122,10 @@ export function projectLaunchBinding(input: LaunchBindingInput): Record<string,
116
122
  outputPath: input.outputPath,
117
123
  outputMode: input.outputMode,
118
124
  structuredOutputSchema: input.structuredOutputSchema,
125
+ extensionBindings: input.extensionBindings,
119
126
  };
120
127
  }
121
128
 
122
129
  export function launchBindingDigest(input: LaunchBindingInput): string {
123
- return sha256(projectLaunchBinding(input));
130
+ return stableJsonDigest(projectLaunchBinding(input));
124
131
  }
@@ -22,6 +22,7 @@ export interface ResolvedStepBehavior {
22
22
  progress: boolean;
23
23
  skills: string[] | false;
24
24
  model?: string;
25
+ fast?: boolean;
25
26
  }
26
27
 
27
28
  export type OutputOverrideInput = string | boolean;
@@ -33,6 +34,7 @@ export interface StepOverrides {
33
34
  progress?: boolean;
34
35
  skills?: string[] | false;
35
36
  model?: string;
37
+ fast?: boolean;
36
38
  }
37
39
 
38
40
  function normalizeOutputOverride(output: unknown): string | false | undefined {
@@ -60,6 +62,7 @@ export interface SequentialStep {
60
62
  progress?: boolean;
61
63
  skill?: string | string[] | false;
62
64
  model?: string;
65
+ fast?: boolean;
63
66
  toolBudget?: ToolBudgetConfig;
64
67
  acceptance?: AcceptanceInput;
65
68
  agentContract?: AgentContract;
@@ -84,6 +87,7 @@ export interface ParallelTaskItem {
84
87
  progress?: boolean;
85
88
  skill?: string | string[] | false;
86
89
  model?: string;
90
+ fast?: boolean;
87
91
  toolBudget?: ToolBudgetConfig;
88
92
  acceptance?: AcceptanceInput;
89
93
  agentContract?: AgentContract;
@@ -284,7 +288,8 @@ export function resolveStepBehavior(
284
288
 
285
289
  const outputMode = stepOverrides.outputMode ?? agentConfig.outputMode ?? "inline";
286
290
  const model = stepOverrides.model ?? agentConfig.model;
287
- return { output, outputMode, reads, progress, skills, model };
291
+ const fast = stepOverrides.fast ?? agentConfig.fast;
292
+ return { output, outputMode, reads, progress, skills, model, fast };
288
293
  }
289
294
 
290
295
  export function resolveTaskTextForFileUpdatePolicy(task: string | undefined, originalTask?: string): string | undefined {
@@ -0,0 +1,52 @@
1
+ import { resolveEffectiveThinking, THINKING_LEVELS, type ThinkingLevel } from "./model-info.ts";
2
+ export type { ThinkingLevel } from "./model-info.ts";
3
+
4
+ export const SUBAGENT_THINKING_CEILING_ENV = "PI_SUBAGENT_THINKING_CEILING";
5
+
6
+ const thinkingLevelRanks = new Map<ThinkingLevel, number>(THINKING_LEVELS.map((level, index) => [level, index]));
7
+
8
+ export function parseThinkingLevel(value: unknown, field = "thinking level"): ThinkingLevel {
9
+ if (typeof value === "string") {
10
+ const trimmed = value.trim();
11
+ if (thinkingLevelRanks.has(trimmed as ThinkingLevel)) return trimmed as ThinkingLevel;
12
+ }
13
+ throw new Error(`Invalid ${field}; expected one of ${THINKING_LEVELS.join(", ")}.`);
14
+ }
15
+
16
+ export function compareThinkingLevels(left: ThinkingLevel, right: ThinkingLevel): number {
17
+ const leftRank = thinkingLevelRanks.get(left);
18
+ const rightRank = thinkingLevelRanks.get(right);
19
+ if (leftRank === undefined || rightRank === undefined) throw new Error(`Invalid thinking level comparison; expected one of ${THINKING_LEVELS.join(", ")}.`);
20
+ return leftRank - rightRank;
21
+ }
22
+
23
+ export function intersectThinkingCeilings(...ceilings: Array<ThinkingLevel | undefined>): ThinkingLevel | undefined {
24
+ const active = ceilings.filter((ceiling): ceiling is ThinkingLevel => ceiling !== undefined);
25
+ if (active.length === 0) return undefined;
26
+ return active.reduce((lowest, ceiling) => compareThinkingLevels(ceiling, lowest) < 0 ? ceiling : lowest);
27
+ }
28
+
29
+ export function decodeThinkingCeiling(value: string | undefined): ThinkingLevel | undefined {
30
+ if (value === undefined || value === "") return undefined;
31
+ return parseThinkingLevel(value, "inherited thinking ceiling");
32
+ }
33
+
34
+ export interface ThinkingCeilingCheck {
35
+ model?: string;
36
+ configThinking?: string | false;
37
+ ceiling?: ThinkingLevel;
38
+ agent?: string;
39
+ runId?: string;
40
+ }
41
+
42
+ export function assertThinkingWithinCeiling(input: ThinkingCeilingCheck): void {
43
+ if (!input.ceiling) return;
44
+ const requested = resolveEffectiveThinking(input.model, input.configThinking);
45
+ if (!requested) return;
46
+ const requestedLevel = parseThinkingLevel(requested, "requested thinking level");
47
+ if (compareThinkingLevels(requestedLevel, input.ceiling) <= 0) return;
48
+ const subject = [input.agent ? `agent '${input.agent}'` : undefined, input.runId ? `run '${input.runId}'` : undefined]
49
+ .filter((value): value is string => Boolean(value))
50
+ .join(" ");
51
+ throw new Error(`Thinking level '${requestedLevel}' exceeds configured maximum '${input.ceiling}'${subject ? ` for ${subject}` : ""}.`);
52
+ }
@@ -8,10 +8,12 @@ import type { Message } from "@earendil-works/pi-ai";
8
8
  import type { AgentConfig } from "../agents/agents.ts";
9
9
  import type { FSWatcher } from "node:fs";
10
10
  import type { ExtensionContext } from "@earendil-works/pi-coding-agent";
11
- import type { ModelScopeConfig } from "../runs/shared/model-scope.ts";
11
+ import type { ModelScopeRule } from "../runs/shared/model-scope.ts";
12
12
  import type { ResolvedSubagentCapabilityCeiling, SubagentCapabilityAudit } from "../runs/shared/capability-ceiling.ts";
13
13
  import type { AuthorityPolicyConfig } from "../policy/authority.ts";
14
+ import type { ThinkingLevel } from "./model-info.ts";
14
15
  import type { GlobalMissionIndexRecord, MissionRecord, MissionStoreConfig } from "../missions/types.ts";
16
+ import type { ExtensionBindings } from "../runs/shared/extension-bindings.ts";
15
17
 
16
18
  // ============================================================================
17
19
  // Basic Types
@@ -342,17 +344,54 @@ export interface ReviewProjection {
342
344
  }
343
345
 
344
346
  export interface FileMutationEffect {
345
- status: "not-requested" | "not-applicable" | "observed" | "missing";
347
+ status: "not-requested" | "not-applicable" | "observed" | "missing" | "blocked";
346
348
  expected: boolean;
347
349
  attempted: boolean;
348
350
  message?: string;
349
351
  resolvedBy?: "llm-intent-arbiter";
352
+ evidence?: TrackedMutationEvidence;
350
353
  }
351
354
 
352
355
  export interface EffectsProjection {
353
356
  fileMutation?: FileMutationEffect;
354
357
  }
355
358
 
359
+ export interface TrackedMutationSnapshot {
360
+ source: "tracked-files";
361
+ trackedOnly: true;
362
+ cwd: string;
363
+ gitRoot?: string;
364
+ dirtyFiles: string[];
365
+ fingerprints: Record<string, TrackedMutationFingerprint>;
366
+ truncated?: boolean;
367
+ unavailable?: string;
368
+ }
369
+
370
+ export type TrackedMutationFingerprint = { kind: "diff"; digest: string };
371
+
372
+ export interface TrackedMutationEvidence {
373
+ source: "tracked-files";
374
+ trackedOnly: true;
375
+ changedFiles: string[];
376
+ attemptedMutation: boolean;
377
+ truncated?: boolean;
378
+ unavailable?: string;
379
+ }
380
+
381
+ export interface TimeoutRecoverySummary {
382
+ termination: "timed-out" | "stopped";
383
+ changedFiles: string[];
384
+ truncated?: boolean;
385
+ currentTool?: string;
386
+ currentToolArgs?: string;
387
+ currentPath?: string;
388
+ sessionFile?: string;
389
+ transcriptPath?: string;
390
+ artifactPaths?: ArtifactPaths;
391
+ warning: string;
392
+ message: string;
393
+ }
394
+
356
395
  export const SUBAGENT_LIFECYCLE_ARTIFACT_VERSION = 3;
357
396
  export type SubagentLifecycleArtifactVersion = typeof SUBAGENT_LIFECYCLE_ARTIFACT_VERSION;
358
397
 
@@ -525,6 +564,7 @@ export interface RunFanoutRejection extends RunFanoutBudgetSnapshot {
525
564
  export interface SteeringRecoveryDescriptor {
526
565
  version: 1;
527
566
  launchContractDigest?: string;
567
+ extensionBindings?: ExtensionBindings;
528
568
  runFanoutBudget: RunFanoutBudgetDescriptor;
529
569
  sourceRunId: string;
530
570
  agentContract?: AgentContract;
@@ -532,9 +572,12 @@ export interface SteeringRecoveryDescriptor {
532
572
  sessionFile?: string;
533
573
  cwd: string;
534
574
  model?: string;
575
+ modelProvider?: string;
535
576
  modelOverrideFromParent?: boolean;
536
577
  fallbackModels?: string[];
578
+ fast?: boolean;
537
579
  thinking?: string;
580
+ thinkingCeiling?: ThinkingLevel;
538
581
  tools?: string[];
539
582
  extensions?: string[];
540
583
  subagentOnlyExtensions?: string[];
@@ -938,6 +981,7 @@ export interface SingleResult {
938
981
  context?: "fresh" | "fork";
939
982
  exitCode: number;
940
983
  processSignal?: string | null;
984
+ timeoutRecovery?: TimeoutRecoverySummary;
941
985
  detached?: boolean;
942
986
  detachedReason?: string;
943
987
  interrupted?: boolean;
@@ -957,6 +1001,13 @@ export interface SingleResult {
957
1001
  modelAttempts?: ModelAttempt[];
958
1002
  controlEvents?: ControlEvent[];
959
1003
  error?: string;
1004
+ /**
1005
+ * True when the dispatch failed because the input exceeded the model's
1006
+ * context window. The model fallback loop stops immediately (retrying the
1007
+ * same input on another model cannot succeed). Callers should treat this as
1008
+ * a signal to reduce input size or re-decompose the task.
1009
+ */
1010
+ contextOverflow?: boolean;
960
1011
  protocolError?: ProtocolOutputLimit;
961
1012
  sessionFile?: string;
962
1013
  skills?: string[];
@@ -1022,6 +1073,7 @@ export interface WaitCompletionChild {
1022
1073
  outputState?: SubagentOutputState;
1023
1074
  error?: string;
1024
1075
  model?: string;
1076
+ contextOverflow?: boolean;
1025
1077
  artifactPaths?: Partial<ArtifactPaths>;
1026
1078
  }
1027
1079
 
@@ -1364,6 +1416,12 @@ export interface ExternalJobStatus {
1364
1416
  provider: string;
1365
1417
  providerJobId?: string;
1366
1418
  promptDigest: string;
1419
+ operation?: "start" | "follow-up";
1420
+ sourceRunId?: string;
1421
+ sourceStepIndex?: number;
1422
+ parentProviderJobId?: string;
1423
+ requestId?: string;
1424
+ requestDigest?: string;
1367
1425
  options: Record<string, unknown>;
1368
1426
  handleUrl?: string;
1369
1427
  conversationUrl?: string;
@@ -1446,6 +1504,8 @@ export interface AsyncStatus {
1446
1504
  /** Set when a durable schedule launched this run, so completions can name their origin. */
1447
1505
  scheduleOrigin?: ScheduleOrigin;
1448
1506
  steps?: Array<{
1507
+ /** Stable caller-facing child identity for inspect/status/stop. */
1508
+ childId?: string;
1449
1509
  agent: string;
1450
1510
  runner?: ExternalCliRunnerStatus | ExternalJobRunnerStatus;
1451
1511
  externalProcess?: ExternalProcessStatus;
@@ -1465,6 +1525,8 @@ export interface AsyncStatus {
1465
1525
  outputName?: string;
1466
1526
  structured?: boolean;
1467
1527
  status: "pending" | "running" | "complete" | "completed" | "failed" | "paused" | "stopped" | "rejected";
1528
+ stopRequested?: boolean;
1529
+ stopRequestedAt?: number;
1468
1530
  children?: NestedRunSummary[];
1469
1531
  sessionFile?: string;
1470
1532
  transcriptPath?: string;
@@ -1484,6 +1546,7 @@ export interface AsyncStatus {
1484
1546
  durationMs?: number;
1485
1547
  exitCode?: number | null;
1486
1548
  timedOut?: boolean;
1549
+ timeoutRecovery?: TimeoutRecoverySummary;
1487
1550
  stopped?: boolean;
1488
1551
  turnBudget?: TurnBudgetState;
1489
1552
  turnBudgetExceeded?: boolean;
@@ -1494,8 +1557,11 @@ export interface AsyncStatus {
1494
1557
  skills?: string[];
1495
1558
  model?: string;
1496
1559
  thinking?: string;
1560
+ thinkingCeiling?: ThinkingLevel;
1497
1561
  attemptedModels?: string[];
1498
1562
  modelAttempts?: ModelAttempt[];
1563
+ /** True when the child input exceeded the model context window. */
1564
+ contextOverflow?: boolean;
1499
1565
  totalCost?: CostSummary;
1500
1566
  steering?: SteeringStatus;
1501
1567
  error?: string;
@@ -1620,6 +1686,8 @@ export interface ForegroundResumeChild {
1620
1686
  acceptance?: AcceptanceLedger;
1621
1687
  agentContract?: AgentContract;
1622
1688
  launchContractDigest?: string;
1689
+ /** Private retained launch authority. Never project into status or result output. */
1690
+ extensionBindings?: ExtensionBindings;
1623
1691
  launchResolvedExtensions?: LaunchResolvedChildExtensionsV1;
1624
1692
  runtimeAcknowledgedExtensions?: RuntimeAcknowledgedChildExtensionsV1;
1625
1693
  execution?: ExecutionProjection;
@@ -1754,6 +1822,8 @@ export interface SubagentState {
1754
1822
  };
1755
1823
  /** Current-session top-level async capacity projection. */
1756
1824
  activeAsyncCapacity?: ActiveAsyncCapacitySnapshot;
1825
+ /** Herdr project panes opened by this Pi session, keyed by project root. */
1826
+ herdrProjectPanes?: Map<string, HerdrProjectPaneSnapshot>;
1757
1827
  asyncJobs: Map<string, AsyncJobState>;
1758
1828
  /** Current-session active and recent async runs for the native fleet inspector. */
1759
1829
  fleetJobs?: Map<string, AsyncJobState>;
@@ -1780,12 +1850,32 @@ export interface SubagentState {
1780
1850
  waitSubscriptions?: Map<string, WaitSubscriptionRecord>;
1781
1851
  /** Live in-process workflow controllers. Durable status remains on disk after settlement. */
1782
1852
  workflowControllers?: Map<string, AbortController>;
1853
+ /** Live in-process workflow child stoppers keyed by parent workflow run id. */
1854
+ workflowChildStops?: Map<string, (childId: string, message?: string) => boolean>;
1783
1855
  /** Session-snapshot `<available_subagents>` block appended to the parent system prompt; empty when nothing is advertised. */
1784
1856
  contextInjectionBlock?: string;
1785
1857
  /** `subagents.injectAgents` entries that matched no discovered agent at snapshot time. */
1786
1858
  contextInjectionUnknownNames?: string[];
1787
1859
  }
1788
1860
 
1861
+ export interface HerdrProjectPaneSnapshot {
1862
+ projectRoot: string;
1863
+ bindingPath: string;
1864
+ paneId: string;
1865
+ openedAt: string;
1866
+ lastFocusedAt?: string;
1867
+ state: "open" | "stale";
1868
+ agentStatus: string;
1869
+ ownership: "verified" | "unknown" | "mismatch";
1870
+ safeToClose: boolean;
1871
+ refreshedAt: number;
1872
+ summary?: string;
1873
+ tabId?: string;
1874
+ workspaceId?: string;
1875
+ terminalTitle?: string;
1876
+ staleReason?: string;
1877
+ }
1878
+
1789
1879
  // ============================================================================
1790
1880
  // Display
1791
1881
  // ============================================================================
@@ -1819,9 +1909,28 @@ export const SUBAGENT_FOREGROUND_COMPLETE_EVENT = "subagent:foreground-complete"
1819
1909
  export const SUBAGENT_CONTROL_EVENT = "subagent:control-event";
1820
1910
  export const SUBAGENT_CONTROL_INTERCOM_EVENT = "subagent:control-intercom";
1821
1911
  export const SUBAGENT_STEERING_NOTICE_EVENT = "subagent:steering-notice";
1912
+ export const SUBAGENT_CHILD_STATUS_EVENT = "subagent:child-status";
1822
1913
  export const SUBAGENT_RESULT_INTERCOM_EVENT = "subagent:result-intercom";
1823
1914
  export const SUBAGENT_RESULT_INTERCOM_DELIVERY_EVENT = "subagent:result-intercom-delivery";
1824
1915
 
1916
+ export interface SubagentChildStatusEvent {
1917
+ type: "subagent.child-status";
1918
+ version: 1;
1919
+ runId: string;
1920
+ childId: string;
1921
+ status: "stopping" | "stopped";
1922
+ ts: number;
1923
+ reason?: string;
1924
+ source?: "rpc" | "async";
1925
+ asyncDir?: string;
1926
+ stepIndex?: number;
1927
+ agent?: string;
1928
+ childRunId?: string;
1929
+ workflowKey?: string;
1930
+ phase?: string;
1931
+ label?: string;
1932
+ }
1933
+
1825
1934
  // ============================================================================
1826
1935
  // Execution Options
1827
1936
  // ============================================================================
@@ -1883,24 +1992,29 @@ export interface RunSyncOptions {
1883
1992
  nestedRoute?: NestedRouteInfo;
1884
1993
  /** Override the agent's default model (format: "provider/id" or just "id") */
1885
1994
  modelOverride?: string;
1995
+ /** Opt into priority service tier for supported native OpenAI-Codex launches. */
1996
+ fast?: boolean;
1886
1997
  /** The override came from the running parent session, not configuration. */
1887
1998
  modelOverrideFromParent?: boolean;
1888
1999
  /** LLM intent arbiter for the completion mutation guard (rescues read-only review runs). */
1889
2000
  llmIntentArbiter?: import("../runs/shared/llm-intent-arbiter.ts").TaskMutationArbiter;
1890
2001
  /** Override the agent's default thinking level for this run */
1891
2002
  thinkingOverride?: AgentConfig["thinking"];
2003
+ thinkingCeiling?: ThinkingLevel;
2004
+ extensionBindings?: ExtensionBindings;
1892
2005
  /** Registry models available for heuristic bare-model resolution */
1893
2006
  availableModels?: Array<{ provider: string; id: string; fullId: string }>;
1894
2007
  /** Current parent-session provider to prefer for ambiguous bare model ids */
1895
2008
  preferredModelProvider?: string;
1896
2009
  /** Optional subagent model-scope enforcement for fallback candidates */
1897
- modelScope?: ModelScopeConfig;
2010
+ modelScope?: ModelScopeRule | ModelScopeRule[];
1898
2011
  /** Skills to make available (overrides agent default if provided) */
1899
2012
  skills?: string[];
1900
2013
  structuredOutput?: {
1901
2014
  schema: JsonSchemaObject;
1902
2015
  schemaPath: string;
1903
2016
  outputPath: string;
2017
+ acceptanceReportPath?: string;
1904
2018
  };
1905
2019
  agentContract?: AgentContract;
1906
2020
  acceptance?: AcceptanceInput;
@@ -1977,7 +2091,7 @@ export type FleetKeybindingAction = typeof FLEET_KEYBINDING_ACTIONS[number];
1977
2091
  export type FleetKeybindingsConfig = Partial<Record<FleetKeybindingAction, string[]>>;
1978
2092
 
1979
2093
  export interface OrcaProgressTabsConfig {
1980
- /** Create one Orca terminal tab per running subagent. Experimental and opt-in. */
2094
+ /** Create one Orca observer tab per top-level subagent call. Experimental and opt-in. */
1981
2095
  enabled?: boolean;
1982
2096
  }
1983
2097
 
@@ -2059,7 +2173,7 @@ export interface ExtensionConfig {
2059
2173
  /** Artifact cleanup retention. Set cleanupDays to 0 to disable cleanup. */
2060
2174
  artifactConfig?: Pick<ArtifactConfig, "cleanupDays">;
2061
2175
  intercomBridge?: IntercomBridgeConfig;
2062
- /** Control how slow result-index scans are logged. Defaults to \"all\".
2176
+ /** Control how slow result-index scans are logged. Defaults to \"activity\".
2063
2177
  * - \"all\": log every slow scan, including scans that find nothing.
2064
2178
  * - \"activity\": log only slow scans that found or scheduled work. Silences
2065
2179
  * the periodic healthy rescan that inspects zero files while no async runs
@@ -2173,6 +2287,7 @@ export const SLASH_SUBAGENT_RESPONSE_EVENT = "subagent:slash:response";
2173
2287
  export const SLASH_SUBAGENT_UPDATE_EVENT = "subagent:slash:update";
2174
2288
  export const SLASH_SUBAGENT_CANCEL_EVENT = "subagent:slash:cancel";
2175
2289
  export const POLL_INTERVAL_MS = 250;
2290
+ export const WIDGET_ANIMATION_INTERVAL_MS = 1000;
2176
2291
  export const MAX_WIDGET_JOBS = 4;
2177
2292
  export const DEFAULT_SUBAGENT_MAX_DEPTH = 2;
2178
2293
  export const SUBAGENT_ACTIONS = ["list", "get", "models", "children.list", "guide", "create", "update", "delete", "eject", "disable", "enable", "reset", "mission.create", "mission.list", "mission.show", "mission.update", "mission.resolve-decision", "mission.attach-run", "mission.close", "worktree.discard", "refine", "refine.show", "refine.rollback", "inspector.open", "inspector.status", "inspector.close", "project.open", "project.status", "project.close", "status", "debug.run", "grant-spawn-budget", "interrupt", "resume", "steer", "stop", "dismiss", "doctor", "watchdog.status", "watchdog.check", "watchdog.configure", "watchdog.recommend-model", "schedule.create", "schedule.list", "schedule.show", "schedule.history", "schedule.pause", "schedule.resume", "schedule.run", "schedule.run-due", "schedule.delete"] as const;