pi-better-subagents 0.35.0 → 0.36.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 (78) hide show
  1. package/README.md +1 -1
  2. package/assignment-outcomes.ts +11 -5
  3. package/assignment-report.ts +83 -19
  4. package/catalog-host-admission.ts +19 -3
  5. package/catalog-preferences.ts +1 -1
  6. package/catalog-resolver.ts +35 -1
  7. package/catalog-store.ts +27 -20
  8. package/child-apply-patch.ts +13 -0
  9. package/child-dependencies.mjs +25 -12
  10. package/child-operations.ts +80 -1
  11. package/child-preflight.mjs +8 -2
  12. package/child-process-list.ts +8 -0
  13. package/config.ts +46 -2
  14. package/continuation-authority.ts +3 -1
  15. package/continuation-runtime.ts +88 -0
  16. package/docs/usage.md +53 -28
  17. package/extensions.mjs +11 -13
  18. package/finalization.ts +15 -0
  19. package/goal-provider.ts +44 -2
  20. package/health-observation.ts +43 -48
  21. package/index.ts +257 -98
  22. package/launch-context.ts +23 -0
  23. package/launch-digest.mjs +6 -0
  24. package/log-cursor.ts +91 -15
  25. package/managed-launch-bootstrap.mjs +2 -2
  26. package/managed-launch-client.ts +6 -3
  27. package/managed-launch-host.ts +168 -15
  28. package/managed-launch-journal.mjs +1 -5
  29. package/managed-launch-port.ts +4 -0
  30. package/operation-bridge-types.ts +27 -2
  31. package/owned-exit.ts +12 -0
  32. package/package.json +1 -1
  33. package/parse.ts +48 -6
  34. package/permission-policy.ts +41 -8
  35. package/process-identity.d.mts +1 -0
  36. package/process-identity.mjs +29 -0
  37. package/registry.ts +54 -33
  38. package/runtime-client/artifacts/darwin-arm64.gz +0 -0
  39. package/runtime-client/artifacts/darwin-arm64.json +1 -1
  40. package/runtime-client/artifacts/darwin-x64.gz +0 -0
  41. package/runtime-client/artifacts/darwin-x64.json +1 -1
  42. package/runtime-client/artifacts/linux-arm64.gz +0 -0
  43. package/runtime-client/artifacts/linux-arm64.json +1 -1
  44. package/runtime-client/artifacts/linux-x64.gz +0 -0
  45. package/runtime-client/artifacts/linux-x64.json +1 -1
  46. package/runtime-client/src/runtime/client.mjs +30 -3
  47. package/runtime-client/src/runtime/work-client.mjs +150 -7
  48. package/shared-callback-batcher.ts +11 -2
  49. package/shared-catalog.ts +6 -14
  50. package/shared-navigator-panels.ts +26 -4
  51. package/shared-navigator.ts +197 -14
  52. package/shared-operation-coordinator/assignment-inbox.mjs +118 -0
  53. package/shared-operation-coordinator/assignment-observation.mjs +43 -35
  54. package/shared-operation-coordinator/src/assignment-changes.ts +73 -0
  55. package/shared-operation-coordinator/src/assignment-outcomes.ts +2 -0
  56. package/shared-operation-coordinator/src/background-requests.ts +14 -3
  57. package/shared-operation-coordinator/src/discovery.ts +5 -3
  58. package/shared-operation-coordinator/src/operations.ts +50 -2
  59. package/shared-operation-coordinator/src/result-supervision.ts +12 -0
  60. package/shared-operation-coordinator/src/rows.ts +2 -0
  61. package/shared-operation-coordinator/src/schema.ts +40 -24
  62. package/shared-operation-coordinator/src/store.ts +34 -8
  63. package/shared-operation-coordinator/src/subagent-launch.ts +24 -1
  64. package/shared-operation-coordinator/src/types.ts +5 -1
  65. package/shared-sandbox-core.ts +1 -1
  66. package/shared-task-exec.ts +12 -1
  67. package/shared-task-process-identity.ts +126 -0
  68. package/shared-task-process-list.ts +8 -2
  69. package/shared-task-sandbox.ts +5 -3
  70. package/shared-task-tools.ts +8 -5
  71. package/shared-work-client.d.mts +10 -0
  72. package/shared-work-client.mjs +150 -7
  73. package/subagent-tools.ts +28 -34
  74. package/task-policy.ts +3 -1
  75. package/timing.ts +10 -1
  76. package/work-observation.ts +71 -16
  77. package/worker-operations-host.ts +12 -4
  78. package/worker-waits.ts +93 -34
@@ -20,6 +20,7 @@ import { connect, type Socket } from "node:net";
20
20
  import * as piSdk from "@earendil-works/pi-coding-agent";
21
21
  import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
22
22
  import { captureParkCheckpoint, type ParkCheckpoint } from "./park-checkpoint.ts";
23
+ import { supportsPromptSections } from "./shared-execution-policy.ts";
23
24
  import {
24
25
  ACKNOWLEDGE_OPERATION_TOOL,
25
26
  OPERATION_BRIDGE_ENV_KEYS,
@@ -28,12 +29,14 @@ import {
28
29
  OPERATIONS_ATTEMPT_ID_ENV,
29
30
  OPERATIONS_CHILD_ID_ENV,
30
31
  OPERATIONS_CONVERSATION_ID_ENV,
32
+ OPERATIONS_DEADLINE_AT_ENV,
31
33
  OPERATIONS_ENABLED_ENV,
32
34
  OPERATIONS_ENDPOINT_ENV,
33
35
  OPERATIONS_RUN_ID_ENV,
34
36
  OPERATIONS_TOKEN_ENV,
35
37
  OPERATIONS_WRITER_LEASE_ID_ENV,
36
38
  WAIT_OPERATIONS_TOOL,
39
+ assertWaitToolDependencies,
37
40
  OperationBridgeError,
38
41
  OperationToolError,
39
42
  type JsonRecord,
@@ -54,6 +57,7 @@ import {
54
57
  requiresParkCheckpoint,
55
58
  parseBridgeEndpoint,
56
59
  validateJsonSchemaSupport,
60
+ validateJsonSchema,
57
61
  redactSecret,
58
62
  } from "./operation-bridge-types.ts";
59
63
 
@@ -67,6 +71,7 @@ export interface ChildOperationBridgeConfig {
67
71
  attemptId?: string;
68
72
  writerLeaseId?: string;
69
73
  childId?: string;
74
+ deadlineAt?: number | null;
70
75
  requestTimeoutMs?: number;
71
76
  }
72
77
 
@@ -120,6 +125,10 @@ export function readChildOperationBridgeConfig(env: NodeJS.ProcessEnv = process.
120
125
  const token = env[OPERATIONS_TOKEN_ENV]!;
121
126
  const runId = env[OPERATIONS_RUN_ID_ENV]!;
122
127
  const conversationId = env[OPERATIONS_CONVERSATION_ID_ENV]!;
128
+ const deadline = env[OPERATIONS_DEADLINE_AT_ENV];
129
+ if (deadline !== undefined && (!/^\d+$/.test(deadline) || !Number.isSafeInteger(Number(deadline)))) {
130
+ return { status: "invalid", reason: "operation bridge assignment deadline is invalid" };
131
+ }
123
132
  try {
124
133
  parseBridgeEndpoint(endpoint);
125
134
  } catch {
@@ -138,6 +147,7 @@ export function readChildOperationBridgeConfig(env: NodeJS.ProcessEnv = process.
138
147
  token,
139
148
  runId,
140
149
  conversationId,
150
+ ...(deadline !== undefined ? { deadlineAt: Number(deadline) || null } : {}),
141
151
  ...(env[OPERATIONS_ATTEMPT_ID_ENV] ? { attemptId: env[OPERATIONS_ATTEMPT_ID_ENV]! } : {}),
142
152
  ...(env[OPERATIONS_WRITER_LEASE_ID_ENV] ? { writerLeaseId: env[OPERATIONS_WRITER_LEASE_ID_ENV]! } : {}),
143
153
  ...(env[OPERATIONS_CHILD_ID_ENV] ? { childId: env[OPERATIONS_CHILD_ID_ENV]! } : {}),
@@ -488,6 +498,7 @@ export function verifyDescriptor(value: unknown, config: Pick<ChildOperationBrid
488
498
  }));
489
499
  }
490
500
  const capabilities = validateCapabilities(record.capabilities);
501
+ assertWaitToolDependencies(capabilities, [...seen]);
491
502
  if (seen.has(WAIT_OPERATIONS_TOOL) && !(capabilities.wait && capabilities.parking)) {
492
503
  throw new OperationBridgeError("invalid-request", "parent exposed wait_for_operations without a parking capability");
493
504
  }
@@ -809,7 +820,19 @@ export function installChildOperationBridge(
809
820
  let installed = false;
810
821
  let starting: Promise<void> | undefined;
811
822
  let completingPark = false;
823
+ let completion = { correctionUsed: false, reported: false };
824
+ let reportError: string | undefined;
825
+ let bridgeConfig: ChildOperationBridgeConfig | undefined;
812
826
  const env = options.env ?? process.env;
827
+ const completionEntryType = "pi-subagent-completion";
828
+
829
+ const canCorrectCompletion = (signal?: AbortSignal): boolean => state.status === "ready"
830
+ && !completion.correctionUsed && !completion.reported && !signal?.aborted
831
+ && (bridgeConfig?.deadlineAt == null || Date.now() < bridgeConfig.deadlineAt);
832
+
833
+ function saveCompletion(): void {
834
+ pi.appendEntry(completionEntryType, { attemptId: bridgeConfig?.attemptId ?? bridgeConfig?.runId, ...completion });
835
+ }
813
836
 
814
837
  const handle: ChildOperationBridgeHandle = {
815
838
  getState: () => ({ ...state, ...(state.descriptor ? { descriptor: state.descriptor } : {}) }),
@@ -843,7 +866,7 @@ export function installChildOperationBridge(
843
866
  if (activeToolExecutions === 0) restoreBridgeEnvironment();
844
867
  });
845
868
 
846
- pi.on("session_start", async (_event, _ctx) => {
869
+ pi.on("session_start", async (_event, ctx) => {
847
870
  if (installed || starting) return starting;
848
871
  starting = (async () => {
849
872
  const read = options.config
@@ -856,6 +879,7 @@ export function installChildOperationBridge(
856
879
  return;
857
880
  }
858
881
  state.status = "connecting";
882
+ bridgeConfig = read.config;
859
883
  options.onDiagnostic?.({ event: "connecting" });
860
884
  const active = (options.clientFactory ?? ((config) => createOperationBridgeClient(config, {
861
885
  requestTimeoutMs: options.requestTimeoutMs,
@@ -872,6 +896,17 @@ export function installChildOperationBridge(
872
896
  }
873
897
  client = active;
874
898
  state.descriptor = descriptor;
899
+ if (descriptor.capabilities.reportAssignment) {
900
+ const entries = ctx.sessionManager.getEntries();
901
+ for (let index = entries.length - 1; index >= 0; index--) {
902
+ const entry = entries[index]!;
903
+ if (entry.type !== "custom" || entry.customType !== completionEntryType) continue;
904
+ const data = entry.data as { attemptId?: string; correctionUsed?: boolean; reported?: boolean } | undefined;
905
+ if (data?.attemptId !== (read.config.attemptId ?? read.config.runId)) continue;
906
+ completion = { correctionUsed: data.correctionUsed === true, reported: data.reported === true };
907
+ break;
908
+ }
909
+ }
875
910
  try {
876
911
  registerTools(descriptor, state.parkingSupported === true);
877
912
  } catch (error) {
@@ -889,6 +924,31 @@ export function installChildOperationBridge(
889
924
  return starting;
890
925
  });
891
926
 
927
+ pi.on("before_agent_start", (event, ctx) => {
928
+ if (!state.descriptor?.capabilities.reportAssignment) return;
929
+ const instruction = `Assignment completion: call report_assignment_result before returning. Evidence sources must resolve inside this assigned workspace: ${JSON.stringify(ctx.cwd)}. A sibling output directory is outside that boundary; use an existing workspace file or place the reportable artifact inside the workspace. Use offset and max_bytes for evidence larger than 65536 bytes. Continue remaining local work within the existing deadline, or report a concrete blocker; do not infer a tool-call budget from the number of calls you have made.`;
930
+ if (!supportsPromptSections(event.systemPromptOptions)) return { systemPrompt: `${event.systemPrompt}\n\n${instruction}` };
931
+ const prompt = event.systemPromptOptions as { sections?: Record<string, string> };
932
+ (prompt.sections ??= {}).assignment_completion = instruction;
933
+ });
934
+
935
+ pi.on("agent_end", (event, ctx) => {
936
+ if (!state.descriptor?.capabilities.reportAssignment || !canCorrectCompletion(ctx.signal)) return;
937
+ let last;
938
+ for (let index = event.messages.length - 1; index >= 0; index--) {
939
+ const message = event.messages[index]!;
940
+ if (message.role !== "assistant") continue;
941
+ last = message;
942
+ break;
943
+ }
944
+ if (last?.stopReason !== "stop") return;
945
+ completion.correctionUsed = true;
946
+ saveCompletion();
947
+ pi.sendMessage({ customType: "assignment-completion-correction", display: false,
948
+ content: `The assignment has no accepted report. ${reportError ? `The latest report was refused: ${reportError}. ` : ""}This is the one completion correction for this execution attempt, within its original authority and deadline. Finish available remaining work, inspect and acknowledge any outstanding operation evidence, then call report_assignment_result with workspace evidence. If progress is blocked or work remains, report incomplete with remaining_work and the concrete blocker. Do not claim completion from process exit or final prose.` },
949
+ { deliverAs: "followUp", triggerTurn: true });
950
+ });
951
+
892
952
  pi.on("message_end", (event) => {
893
953
  const message = event.message as { role?: string; content?: unknown };
894
954
  if (message.role !== "assistant" || !Array.isArray(message.content)) return;
@@ -963,6 +1023,7 @@ export function installChildOperationBridge(
963
1023
  try {
964
1024
  return await invokeTool(tool, toolCallId, params, signal);
965
1025
  } catch (error) {
1026
+ if (tool.name === "report_assignment_result") reportError = redactSecret(error instanceof Error ? error.message : String(error)).slice(0, 2048);
966
1027
  return toolErrorResult(error);
967
1028
  }
968
1029
  },
@@ -981,6 +1042,13 @@ export function installChildOperationBridge(
981
1042
  throw new OperationToolError("tool parameters must be an object");
982
1043
  }
983
1044
  const params = rawParams as JsonRecord;
1045
+ if (tool.name === "report_assignment_result" && params.status === "incomplete" && !params.blocker
1046
+ && Array.isArray(params.remaining_work) && params.remaining_work.length > 0
1047
+ && validateJsonSchema(tool.parameters, params).ok && canCorrectCompletion(signal)) {
1048
+ completion.correctionUsed = true;
1049
+ saveCompletion();
1050
+ throw new OperationToolError("The incomplete report has not been accepted. Use the one completion correction to continue the listed remaining local work within the original authority and deadline, then report the result. If blocked or still incomplete, report that explicitly; no further automatic correction will be requested.");
1051
+ }
984
1052
  if (isLaunchTool(tool.name, params)) {
985
1053
  const bridgeEnvironmentField = findBridgeEnvironmentKey(params);
986
1054
  if (bridgeEnvironmentField) {
@@ -991,6 +1059,17 @@ export function installChildOperationBridge(
991
1059
  }
992
1060
  }
993
1061
  const raw = await client.request(tool.name, params, { signal });
1062
+ if (tool.name === "report_assignment_result" && raw && typeof raw === "object"
1063
+ && ["complete", "incomplete"].includes(String((raw as JsonRecord).status))) {
1064
+ completion.reported = true;
1065
+ reportError = undefined;
1066
+ saveCompletion();
1067
+ }
1068
+ if (tool.name === ACKNOWLEDGE_OPERATION_TOOL && params.disposition === "assignment-complete"
1069
+ && raw && typeof raw === "object" && (raw as JsonRecord).phase === "consumed") {
1070
+ completion.reported = true;
1071
+ saveCompletion();
1072
+ }
994
1073
  if (tool.name === WAIT_OPERATIONS_TOOL) {
995
1074
  return waitToolResult(toolCallId, raw);
996
1075
  }
@@ -9,12 +9,18 @@ export default function childPreflight(pi) {
9
9
  };
10
10
  let plan;
11
11
  try { plan = JSON.parse(readFileSync(process.env[PREFLIGHT_ENV], 'utf8')); } catch (error) { fail(error); }
12
+ const reported = new Set();
12
13
  // The task guard activates its adapters on session_start. Check after every
13
14
  // startup handler has finished, before the first request (and subsequent runs).
14
15
  const check = async (ctx, tools) => {
15
16
  try {
16
- await checkChildPreflight({ ...plan, tools }, { registry: ctx.modelRegistry,
17
- tools: pi.getActiveTools(), model: ctx.model });
17
+ const inactive = await checkChildPreflight({ ...plan, tools }, { registry: ctx.modelRegistry,
18
+ tools: pi.getActiveTools(), registeredTools: pi.getAllTools?.().map(tool => tool.name), model: ctx.model });
19
+ const newlyInactive = inactive.filter(tool => !reported.has(tool));
20
+ if (newlyInactive.length) {
21
+ for (const tool of newlyInactive) reported.add(tool);
22
+ process.stderr.write(`Subagent child preflight: inherited trusted tools are inactive in this child: ${newlyInactive.join(', ')}. Continuing without them.\n`);
23
+ }
18
24
  } catch (error) { fail(error); }
19
25
  };
20
26
  pi.on('session_start', async (_event, ctx) => check(ctx, []));
@@ -0,0 +1,8 @@
1
+ import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
2
+ import { createProcessListToolDefinition } from "./shared-task-process-list.ts";
3
+
4
+ /** Keep the fixed, bounded inventory contract when no task sandbox is active. */
5
+ export default function childProcessList(pi: ExtensionAPI): void {
6
+ const tool = createProcessListToolDefinition(process.cwd(), { requireLaunchPlan: () => ({ confined: false }) }, () => "read");
7
+ pi.registerTool(tool as Parameters<ExtensionAPI["registerTool"]>[0]);
8
+ }
package/config.ts CHANGED
@@ -9,12 +9,14 @@
9
9
  * `defaultSkills` absent → the child discovers the user-level skills catalog.
10
10
  */
11
11
 
12
- import { existsSync, readFileSync, statSync } from "node:fs";
12
+ import { existsSync, readFileSync, realpathSync, statSync } from "node:fs";
13
13
  import { fileURLToPath } from "node:url";
14
14
  import { dirname, isAbsolute, join } from "node:path";
15
15
  import { homedir } from "node:os";
16
+ import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
17
+ import { toolPackage, supportsChildProvider } from "./shared-task-tools.ts";
16
18
  import { SELF_SPEC } from "./extensions.ts";
17
- import { installedPackage } from "./child-dependencies.mjs";
19
+ import { installedPackage, packageRoot } from "./child-dependencies.mjs";
18
20
  import { isDelegationMode, type DelegationMode } from "./delegation.ts";
19
21
  import { normalizeSkillExposure } from "./skills.ts";
20
22
  import { validatedTimingMinutes, type TimingSettings } from "./timing.ts";
@@ -251,6 +253,48 @@ export function normalizeTools(list: string): string {
251
253
  return list.split(",").map((t) => t.trim()).filter(Boolean).join(",");
252
254
  }
253
255
 
256
+ export const ORDINARY_TOOL_PROVIDERS: Readonly<Record<string, string>> = {
257
+ apply_patch: join(selfDir(), "child-apply-patch.ts"),
258
+ process_list: join(selfDir(), "child-process-list.ts"),
259
+ };
260
+
261
+ /** Check the owning package even when a mapping points directly to one of its files. */
262
+ export function supportedChildEntrypoint(name: string, pkg: string, path: string): boolean {
263
+ return supportsChildProvider(name, pkg, packageRoot(path) ?? path);
264
+ }
265
+
266
+ /** Capture exact user-installed entrypoints already active in the foreground. */
267
+ export function activeChildProviders(pi: Pick<ExtensionAPI, "getActiveTools" | "getAllTools">): Record<string, string> {
268
+ const active = new Set(pi.getActiveTools?.() ?? []);
269
+ const paths = new Map<string, string>();
270
+ const seen = new Set<string>();
271
+ for (const tool of pi.getAllTools?.() ?? []) {
272
+ if (!active.has(tool.name)) continue;
273
+ // The SDK reports active names. Conflicting registrations have no unique owner.
274
+ if (seen.has(tool.name)) { paths.delete(tool.name); continue; }
275
+ seen.add(tool.name);
276
+ if (tool.sourceInfo?.scope !== "user") continue;
277
+ const owner = toolPackage(tool);
278
+ if (!owner || !supportsChildProvider(tool.name, owner.package, owner.root)) continue;
279
+ try {
280
+ const path = realpathSync(tool.sourceInfo.path);
281
+ if (!statSync(path).isFile() || !supportedChildEntrypoint(tool.name, owner.package, path)) continue;
282
+ paths.set(tool.name, path);
283
+ } catch { /* An unavailable entrypoint cannot supply a new worker. */ }
284
+ }
285
+ return Object.fromEntries(paths);
286
+ }
287
+
288
+ export function ordinaryChildConfig(config: SubagentConfig, activeProviders: Record<string, string> = {}): SubagentConfig {
289
+ const packaged = config.toolExtensions === null ? undefined : bundledConfig().toolExtensions;
290
+ return { ...config, toolExtensions: { ...activeProviders, ...ORDINARY_TOOL_PROVIDERS, ...packaged, ...config.toolExtensions } };
291
+ }
292
+
293
+ export function addEditablePatch(names: string[], excluded: ReadonlySet<string>): void {
294
+ const editable = names.some(name => (name === "edit" || name === "write") && !excluded.has(name));
295
+ if (editable && !excluded.has("apply_patch") && !names.includes("apply_patch")) names.push("apply_patch");
296
+ }
297
+
254
298
  /** This package's own root — the extension dir, which is also `self`. */
255
299
  export function selfDir(): string {
256
300
  return dirname(fileURLToPath(import.meta.url));
@@ -10,8 +10,10 @@ export function intersectContinuationPermissions(captured: any, current: any): a
10
10
  .sort((a, b) => a.name.localeCompare(b.name) || a.package.localeCompare(b.package)) };
11
11
  const intersect = (old: any, fresh: any) => {
12
12
  if (!old || !fresh) throw new Error("Continuation permission profile unavailable");
13
+ if (!fresh.enabled) return old.enabled ? { ...old } : { ...fresh };
14
+ if (!old.enabled) return { ...fresh };
13
15
  const access = ["off", "read", "write", "read-write"];
14
- const value = { ...fresh, enabled: old.enabled || fresh.enabled };
16
+ const value = { ...fresh };
15
17
  for (const key of ["projectFiles", "outsideProject", "storedCredentials"]) {
16
18
  if (!access.includes(old[key]) || !access.includes(fresh[key])) throw new Error("Invalid continuation permission profile");
17
19
  value[key] = access[Math.min(access.indexOf(old[key]), access.indexOf(fresh[key]))];
@@ -0,0 +1,88 @@
1
+ /** Select a saved, installed worker closure without changing the server owner. */
2
+ import { readFileSync, realpathSync, statSync } from "node:fs";
3
+ import { basename, dirname, join, normalize, sep } from "node:path";
4
+
5
+ const DOMAIN = join("src", "runtime", "domain", "subagents");
6
+ type Recipe = { runtimeRoot?: string; baseExtensionArgs?: readonly string[]; extensionArgs?: readonly string[] };
7
+ type Command = { file: string; fileArgs: string[] };
8
+
9
+ export function managedRuntimeRoot(domain: string): string | undefined {
10
+ if (!domain.endsWith(`${sep}${DOMAIN}`)) return undefined;
11
+ const root = domain.slice(0, -(DOMAIN.length + 1));
12
+ return basename(dirname(root)) === "releases" && /^[a-f0-9]{64}$/.test(basename(root)) ? root : undefined;
13
+ }
14
+
15
+ export interface ContinuationRuntime {
16
+ root: string;
17
+ mapPath(path: string): string;
18
+ mapArgs(args: readonly string[]): string[];
19
+ command(command: Command): Command;
20
+ }
21
+
22
+ /**
23
+ * Only sibling, published releases are eligible. User extensions retain their
24
+ * original identity check. Permission policy is still generated by the current
25
+ * server; a saved runtime does not grandfather its previous permission grants.
26
+ * Published releases are retained by the installer (it removes staging only).
27
+ * Any future release GC must treat LaunchRecipe.runtimeRoot as a reference.
28
+ */
29
+ export function selectContinuationRuntime(options: { currentDir: string; recipe?: Recipe }): ContinuationRuntime | undefined {
30
+ const current = managedRuntimeRoot(options.currentDir);
31
+ if (!current || !options.recipe) return undefined;
32
+ const recipe = options.recipe;
33
+ // Upgrade recipes written before runtimeRoot existed using the mandatory
34
+ // harness control, never a user-selected/custom extension path.
35
+ const args = recipe.baseExtensionArgs ?? recipe.extensionArgs ?? [];
36
+ const steer = args.find((value, index) => args[index - 1] === "--extension" && value.endsWith(`${sep}${DOMAIN}${sep}child-steer.ts`));
37
+ const saved = recipe.runtimeRoot ?? (steer ? managedRuntimeRoot(dirname(steer)) : undefined);
38
+ if (!saved || saved === current) return undefined;
39
+ const unavailable = (detail: string): never => {
40
+ throw new Error(`Cannot resume: saved runtime ${basename(saved)} unavailable (${detail}). Restore that release or explicitly launch a replacement conversation; no worker was started.`);
41
+ };
42
+ if (normalize(saved) !== saved || dirname(saved) !== dirname(current) || !/^[a-f0-9]{64}$/.test(basename(saved))) {
43
+ return unavailable("not a sibling managed release");
44
+ }
45
+ function manifest(root: string) {
46
+ let value;
47
+ try {
48
+ if (realpathSync(root) !== root) return unavailable("release path is not canonical");
49
+ value = JSON.parse(readFileSync(join(root, "runtime.json"), "utf8"));
50
+ } catch { return unavailable("missing or unreadable release manifest"); }
51
+ if (value.format !== 1 || value.root !== root || value.build?.contentId !== basename(root)
52
+ || value.node !== join(root, "node/bin/node") || value.installRoot !== dirname(dirname(root))) {
53
+ return unavailable("invalid release manifest");
54
+ }
55
+ return value;
56
+ }
57
+ const before = manifest(saved), now = manifest(current);
58
+ // These releases share the existing v1 worker admission/policy/bridge wire
59
+ // formats. Refuse SDK, Node, platform or protocol transitions rather than
60
+ // assuming that a new server can host any historic worker.
61
+ if (before.build.protocolVersion !== 1 || now.build.protocolVersion !== 1
62
+ || ["piSdkVersion", "nodeVersion", "platform"].some(key => !before.build[key] || before.build[key] !== now.build[key])) {
63
+ throw new Error(`Cannot resume: saved runtime ${basename(saved)} is incompatible with the current worker protocol, SDK or platform. Explicit replacement is required; no worker was started.`);
64
+ }
65
+ function required(path: string, directory = false): string {
66
+ try {
67
+ const stat = statSync(path);
68
+ if (realpathSync(path) !== path || !(stat.isFile() || directory && stat.isDirectory())) return unavailable("worker file is missing or redirected");
69
+ } catch { return unavailable("worker file is missing or unreadable"); }
70
+ return path;
71
+ }
72
+ const node = required(before.node);
73
+ const mapPath = (path: string): string => path.startsWith(`${current}${sep}`)
74
+ ? required(join(saved, path.slice(current.length + 1)), true) : path;
75
+ return {
76
+ root: saved,
77
+ mapPath,
78
+ mapArgs: values => values.map((value, index) => values[index - 1] === "--extension" ? mapPath(value) : value),
79
+ command: command => {
80
+ // Only executable slots are rewritten. A prompt or arbitrary CLI
81
+ // value that happens to contain a runtime path must stay untouched.
82
+ const fileArgs = [...command.fileArgs];
83
+ fileArgs[0] = mapPath(fileArgs[0]!);
84
+ if (basename(fileArgs[0]!) === "task-runtime.mjs") fileArgs[1] = mapPath(fileArgs[1]!);
85
+ return { file: node, fileArgs };
86
+ },
87
+ };
88
+ }
package/docs/usage.md CHANGED
@@ -206,6 +206,12 @@ supervised local commands. The bridge retains the worker's captured permissions
206
206
  and applies the current Background Tasks policy as well. Explicit tool exclusions
207
207
  and clean loadouts can withhold the bridge.
208
208
 
209
+ An explicit tool list containing `wait_for_operations` must also contain
210
+ `acknowledge_operation_result` and either `bg_task_status` or `bg_task_log`.
211
+ The launcher checks this after permission filtering and refuses an incomplete
212
+ combination. A default loadout with no authorized evidence reader withholds
213
+ waiting instead of adding permissions.
214
+
209
215
  A worker starts a long validation command, continues independent work, then calls
210
216
  `wait_for_operations` with its owned task ids. Call this tool directly as the only
211
217
  tool call in its assistant message. A nested codemode call cannot deliver the
@@ -230,6 +236,23 @@ checked again. Full capacity leaves the wait ready. Missing or conflicting
230
236
  recovery evidence leaves it held with a reason. The runner survives worker and Pi
231
237
  exit, but v1 does not run an unattended model after Pi shuts down.
232
238
 
239
+ ## Reporting completion
240
+
241
+ Bound assignments use `report_assignment_result` with evidence from inside the
242
+ assigned workspace. A sibling results directory is outside that boundary. An
243
+ existing workspace source file can be evidence; read-only workers need not write
244
+ a new artifact. Use `offset` and `max_bytes` to retain an excerpt from a file
245
+ larger than 65,536 bytes.
246
+
247
+ Before accepting an unblocked incomplete report with concrete `remaining_work`,
248
+ the child allows one chance to continue that work. A normal model stop without
249
+ an accepted report can use the same correction allowance to submit or correct
250
+ the report. The allowance belongs to the current attempt, survives reload, and
251
+ keeps the original deadline and permissions. Concrete blockers, aborted/error
252
+ stops, parked work and expired deadlines do not trigger correction. Accepted
253
+ reports remain immutable; exhausted correction retains the incomplete or
254
+ unverified result for the coordinator.
255
+
233
256
  ## Codemode batch launches
234
257
 
235
258
  On Pi 0.99.1 or newer, enable native codemode alongside the existing direct
@@ -452,8 +475,7 @@ an enabled human profile. Saved enabled profiles and session choices stay enable
452
475
  cache directories when Outside is Read or Read/write. Credential and control
453
476
  denials retain precedence. See the permission details below.
454
477
  - **Tool allowlist.** Confined children admit only verified read/write/edit/bash
455
- implementations, guarded `run_application`, the guarded `apply_patch`, and the trusted tools ticked in
456
- `/sandbox`. The fixed `process_list` adapter is available with Process access
478
+ implementations, guarded `run_application`, the guarded `apply_patch`, and the selected extension tools with verified providers. The fixed `process_list` adapter is available with Process access
457
479
  set to Read. Other requested tools are reported as unavailable, with the reason.
458
480
  - **No runaway recursion.** Confined children cannot spawn nested agents.
459
481
  `allow_nested:true` loads nested-agent support only for unconfined children.
@@ -497,7 +519,14 @@ does not start an emulator or allocate test resources. The setting governs
497
519
  the fixed adapter only, not every OS process operation available through bash
498
520
  or trusted tools. New launches capture changes; running children retain their
499
521
  launch-time setting. Raw macOS `/bin/ps` remains subject to setuid execution
500
- restrictions. See [ADR 0011](../../../docs/adr/0011-fixed-read-only-process-inventory.md).
522
+ restrictions. With Process Read and Commands On, the task PATH includes a
523
+ protected non-setuid compatibility entry for exactly
524
+ `ps -p PID -o lstart= -o comm=`. It returns the current-user process's start time
525
+ and executable path, without exposing arguments or environment. The harness
526
+ requires Xcode Command Line Tools to build this fixed helper; failure refuses
527
+ identity queries without disabling other commands. This does not alter absolute
528
+ `/bin/ps` or callers that replace PATH. See [ADR 0024](../../../docs/adr/0024-sandbox-process-identity-compatibility.md)
529
+ and [ADR 0011](../../../docs/adr/0011-fixed-read-only-process-inventory.md).
501
530
  Network Off blocks task network access while Pi's provider transport remains
502
531
  available. The confined file worker has an 8 MiB file limit and rejects larger
503
532
  files explicitly; use confined commands for larger files when commands are On.
@@ -522,9 +551,8 @@ limit to 10 min in `/sandbox`, then press Ctrl+S. New launches capture the polic
522
551
  running children keep theirs. An incompatible older consumer is rejected rather
523
552
  than silently dropping these restrictions.
524
553
 
525
- Extension tools are
526
- chosen in `/sandbox` → Subagents · Tools
527
- ([ADR 0009](../../../docs/adr/0009-guarded-and-trusted-subagent-tools.md)):
554
+ Select tools in the role, worker defaults or spawn request. Loading a tool grants access to call it. Use `/sandbox` to edit the resource rules.
555
+ [Sandbox tool loading and permission to use tools](../../../docs/adr/0027-sandbox-tools-and-permissions.md) defines the contract.
528
556
 
529
557
  - **Guarded:** `apply_patch`, a harness adapter with the Codex tool's name,
530
558
  schema and patch format. Every add, update, move and delete goes through the
@@ -534,17 +562,14 @@ chosen in `/sandbox` → Subagents · Tools
534
562
  checked first; no file is left half-patched, and a failure part-way reports
535
563
  what was and wasn't applied. It is added for a child that may `edit` or
536
564
  `write`, or asks for it.
537
- - **Trusted:** third-party tools you tick (default `web_fetch` and `web_search`).
538
- Their package is loaded into the child and they run in the child Pi process,
539
- **outside the file rules**. The child admits one only when both its name and
540
- its package match the ticked entry, so another package registering the same
541
- name is refused. A single extension file with no package manifest is loaded
542
- and admitted by itself, never its directory. Known network tool names
543
- (`web_fetch`, `web_search`, `firecrawl_scrape`, `firecrawl_extract`, `mcp`, `mcpScript`, `remote_bash`, and any `mcp__*` name) are refused while Network access is Off; this is a name list, not a
544
- network sandbox. A ticked tool whose package can't be found is left out of a
545
- default loadout and reported with its reason in the launch output; an explicit
546
- `tools` request for a tool the task boundary cannot provide refuses the launch.
547
- Ticked tools join the default tool list; an explicit `tools` list still decides.
565
+ - **Extension tools:** the child loads the selected provider and checks its
566
+ canonical source at dispatch. A single user-installed extension entrypoint is
567
+ loaded by itself. Known network tools require Network access On. The extension
568
+ runs in the trusted Pi process, outside guarded file operations.
569
+ If a trusted tool is inherited from the defaults, registers in the child, and
570
+ is then inactive (for example, because the extension requires a different
571
+ model), the child logs the omission once and continues without it. Missing
572
+ registrations and unavailable explicitly requested tools still fail preflight.
548
573
 
549
574
  Other tools are disabled in confined children. One that only joined the default
550
575
  loadout is omitted from the child and listed in launch output with the reason;
@@ -713,12 +738,10 @@ The effective config also sets:
713
738
 
714
739
  ## The allowlist also decides what LOADS
715
740
 
716
- For confined children, the requested list is first restricted to tools with
717
- verified task adapters and the trusted tools ticked in `/sandbox`; only the
718
- ticked tools' packages load. `toolExtensions` still chooses which package to
719
- load for a tool (an override), but the child admits it only if that is the
720
- ticked package. Provider extensions can still load as trusted runtime
721
- dependencies. Nested spawning and
741
+ For confined children, the requested list selects verified task adapters and
742
+ extension providers. A worker mapping takes precedence over an active
743
+ user-installed entrypoint. Previously saved trusted-package records can
744
+ identify a provider for a selected tool. Nested spawning and
722
745
  inherited extension discovery are currently unavailable under confinement.
723
746
 
724
747
  The mapping behavior below applies to unconfined children and to admitted
@@ -731,9 +754,10 @@ which extension *code* is loaded into it. A child launches as
731
754
  pi -p --mode json --no-extensions -e <package backing a requested tool> ...
732
755
  ```
733
756
 
734
- so a package that backs no requested tool never loads. With the default
735
- allowlist (`read, bash, edit, write, web_search, web_fetch`) exactly one package
736
- loads — the web-tools one — and `web_fetch` works normally.
757
+ The default editable worker gets the Harness `apply_patch` adapter. An explicit
758
+ `process_list` request loads the bounded current-user inventory adapter. Each
759
+ can use an ordinary provider override. The default web tools load their
760
+ configured package. Both execution modes use the selected tools without an additional permission checkbox.
737
761
 
738
762
  Two maps in `config.json` drive it, with a built-in default for provider auth:
739
763
 
@@ -748,8 +772,9 @@ same provider replaces the built-in one, and an empty list disables it. A mapped
748
772
  package that is not installed still fails the launch with the explicit
749
773
  missing-extension error rather than starting without provider auth.
750
774
 
751
- Ask for a tool with no mapping and the spawn still succeeds, but says so at
752
- launch — the tool simply will not exist in the child.
775
+ A required tool with no possible provider fails admission. If an extension
776
+ could supply the name, the worker checks the active registration during
777
+ startup. Both failures identify the missing tool.
753
778
 
754
779
  `clean:true` is the narrowest case of the same mechanism: no extensions at all.
755
780
  For unconfined children, `allow_nested:true` loads this package into the child;
package/extensions.mjs CHANGED
@@ -34,7 +34,7 @@
34
34
  * A builtin needs no extension, so it never counts as unmapped.
35
35
  */
36
36
  // codemode is supplied by the harness child adapter, not a discovered package.
37
- export const BUILTIN_TOOLS = ["read", "bash", "edit", "write", "codemode"];
37
+ export const BUILTIN_TOOLS = ["read", "bash", "edit", "write", "grep", "find", "ls", "codemode"];
38
38
 
39
39
  /** Marker spec meaning "this extension's own package" (for allow_nested). */
40
40
  export const SELF_SPEC = "self";
@@ -88,11 +88,11 @@ export function toolList(tools) {
88
88
  * @returns {{mode: "isolated"|"clean"|"inherit", specs: string[], unmapped: string[], reasons: Record<string,string[]>}}
89
89
  * mode — "isolated" passes --no-extensions + explicit -e (the default);
90
90
  * "clean" passes --no-extensions with no -e;
91
- * "inherit" passes neither (operator opt-out, NOT model-selectable).
91
+ * "inherit" keeps discovery and adds explicitly selected mappings.
92
92
  * specs — extension specs to load, deduped, in a stable order.
93
93
  * unmapped — requested tools that are neither builtin nor mapped to an
94
- * extension. They simply will not exist in the child; surfaced so
95
- * the human sees it instead of the child silently lacking a tool.
94
+ * extension. Admission rejects a known missing required provider.
95
+ * Preflight verifies registrations supplied by loaded extensions.
96
96
  * reasons — spec -> what pulled it in, for the spawn diagnostic.
97
97
  */
98
98
  export function resolveExtensions(a = {}) {
@@ -107,13 +107,10 @@ export function resolveExtensions(a = {}) {
107
107
 
108
108
  // allow_nested is honored in every mode: it is an explicit caller request,
109
109
  // and without our own package loaded the child has no subagent tools at all.
110
- if (a.allowNested) add(SELF_SPEC, "allow_nested");
111
-
112
- if (cfg.inheritExtensions === true) {
113
- return { mode: "inherit", specs: [], unmapped: [], reasons: {} };
114
- }
110
+ const inherit = cfg.inheritExtensions === true;
111
+ if (a.allowNested && !inherit) add(SELF_SPEC, "allow_nested");
115
112
  if (a.clean === true) {
116
- return { mode: "clean", specs, unmapped: [], reasons };
113
+ return { mode: inherit ? "inherit" : "clean", specs, unmapped: [], reasons };
117
114
  }
118
115
 
119
116
  const toolMap = cfg.toolExtensions ?? {};
@@ -122,12 +119,14 @@ export function resolveExtensions(a = {}) {
122
119
  if (BUILTIN_TOOLS.includes(tool)) continue;
123
120
  const mapped = toSpecList(toolMap[tool]);
124
121
  if (mapped.length === 0) {
125
- if (!unmapped.includes(tool)) unmapped.push(tool);
122
+ if (!inherit && !unmapped.includes(tool)) unmapped.push(tool);
126
123
  continue;
127
124
  }
128
125
  for (const spec of mapped) add(spec, `tool:${tool}`);
129
126
  }
130
127
 
128
+ if (inherit) return { mode: "inherit", specs, unmapped, reasons };
129
+
131
130
  // Model auth is not tool-shaped: xai/grok needs pi-xai-oauth loaded or the
132
131
  // child cannot authenticate at all, whatever tools it was granted. A user
133
132
  // entry for a provider wins over the built-in one, including an empty list
@@ -151,8 +150,7 @@ export function resolveExtensions(a = {}) {
151
150
  * @returns {{args: string[], missing: string[]}}
152
151
  */
153
152
  export function extensionArgs(resolution, resolvePath) {
154
- if (resolution.mode === "inherit") return { args: [], missing: [] };
155
- const args = ["--no-extensions"];
153
+ const args = resolution.mode === "inherit" ? [] : ["--no-extensions"];
156
154
  const missing = [];
157
155
  for (const spec of resolution.specs) {
158
156
  const path = resolvePath(spec);
package/finalization.ts CHANGED
@@ -26,6 +26,7 @@ import {
26
26
  } from "./registry.ts";
27
27
  import { fmtElapsed, fmtSpend } from "./widget.ts";
28
28
  import { evaluateParkDisposition, type ParkDisposition } from "./worker-waits.ts";
29
+ import { reconcileRun, type ProcessProbe, type ReconcileResult } from "./health.ts";
29
30
 
30
31
  export interface FinalizeHooks {
31
32
  renderWidget?: () => void;
@@ -45,6 +46,20 @@ export interface FinalizeResult {
45
46
  park?: ParkDisposition;
46
47
  }
47
48
 
49
+ /** The current management owner calls this only for an interrupted, unobserved writer. */
50
+ export function reconcileInterruptedRun(meta: RunMeta, probe: ProcessProbe, now: number, hooks: FinalizeHooks = {}): {
51
+ reconciliation: ReconcileResult; finalization?: FinalizeResult;
52
+ } {
53
+ const reconciliation = reconcileRun(meta, probe, now);
54
+ if ((meta.status === "running" || meta.status === "orphaned") && meta.supervisionInterruptedAt !== undefined && reconciliation.status === "lost") {
55
+ const run = parseRunForLifecycle(meta.id);
56
+ if (run.sawEnd && run.unmatchedToolCalls.length === 0) {
57
+ return { reconciliation, finalization: finalizeRun(meta.id, null, hooks) };
58
+ }
59
+ }
60
+ return { reconciliation };
61
+ }
62
+
48
63
  /**
49
64
  * Finalize a run once its child exits. Idempotent: a run already marked
50
65
  * terminal is left alone. Persists lifecycle classification + failureReason