pi-better-subagents 0.34.0 → 0.35.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 (46) hide show
  1. package/assignment-outcomes.ts +44 -6
  2. package/capacity.mjs +13 -0
  3. package/continuation-authority.ts +29 -0
  4. package/continuation.ts +21 -0
  5. package/failures.ts +7 -1
  6. package/health.ts +0 -1
  7. package/index.ts +273 -109
  8. package/managed-background-capability.ts +9 -0
  9. package/managed-failure-worker.mjs +27 -0
  10. package/managed-launch-bootstrap.mjs +35 -0
  11. package/managed-launch-client.ts +56 -0
  12. package/managed-launch-host.ts +351 -0
  13. package/managed-launch-journal.mjs +18 -0
  14. package/managed-launch-ownership.ts +22 -0
  15. package/managed-launch-port.ts +21 -0
  16. package/managed-launch-recovery.ts +45 -0
  17. package/managed-worker-bridge.ts +48 -0
  18. package/managed-worker.mjs +11 -0
  19. package/package.json +1 -1
  20. package/permission-policy.ts +12 -0
  21. package/registry.ts +2 -0
  22. package/runtime-client/artifacts/darwin-arm64.gz +0 -0
  23. package/runtime-client/artifacts/darwin-arm64.json +1 -1
  24. package/runtime-client/artifacts/darwin-x64.gz +0 -0
  25. package/runtime-client/artifacts/darwin-x64.json +1 -1
  26. package/runtime-client/artifacts/linux-arm64.gz +0 -0
  27. package/runtime-client/artifacts/linux-arm64.json +1 -1
  28. package/runtime-client/artifacts/linux-x64.gz +0 -0
  29. package/runtime-client/artifacts/linux-x64.json +1 -1
  30. package/shared-callback-batcher.ts +4 -1
  31. package/shared-failure-observations.ts +3 -0
  32. package/shared-navigator.ts +23 -5
  33. package/shared-operation-coordinator/assignment-observation.mjs +30 -0
  34. package/shared-operation-coordinator/index.ts +2 -0
  35. package/shared-operation-coordinator/src/background-parent-callbacks.ts +68 -0
  36. package/shared-operation-coordinator/src/background-requests.ts +79 -0
  37. package/shared-operation-coordinator/src/schema.ts +31 -0
  38. package/shared-operation-coordinator/src/store.ts +18 -0
  39. package/shared-operation-coordinator/src/subagent-launch.ts +119 -0
  40. package/shared-operation-coordinator/src/upgrade.ts +22 -0
  41. package/task-runtime.mjs +1 -0
  42. package/timing-notifications.ts +37 -0
  43. package/timing.ts +1 -0
  44. package/tools.ts +10 -3
  45. package/work-observation.ts +18 -2
  46. package/worker-waits.ts +46 -14
@@ -0,0 +1,48 @@
1
+ import { createHash } from "node:crypto";
2
+ import { lstatSync, mkdirSync, readdirSync, readFileSync, writeFileSync, renameSync, unlinkSync } from "node:fs";
3
+ import { join } from "node:path";
4
+ import { readMeta, processStartToken } from "./registry.ts";
5
+ import { processExists } from "./spawn.ts";
6
+ import { readConversationLease } from "./continuation.ts";
7
+ import type { WorkerOperationRegistration } from "./worker-waits.ts";
8
+
9
+ /** Bearer capabilities are private runtime records, never metadata or transcript fields. */
10
+ export function managedWorkerBridge(root: string) {
11
+ const directory = join(root, "worker-bridge-admission");
12
+ const socketDirectory = `/tmp/pi-wb-${process.getuid?.() ?? "user"}-${createHash("sha256").update(root).digest("hex").slice(0, 20)}`;
13
+ const check = (path: string, directory: boolean) => {
14
+ const stat = lstatSync(path);
15
+ if (stat.isSymbolicLink() || stat.uid !== process.getuid?.() || (stat.mode & 0o077) || (directory ? !stat.isDirectory() : !stat.isFile())) throw new Error("Worker bridge admission storage is not private");
16
+ return stat;
17
+ };
18
+ for (const path of [directory, socketDirectory]) { mkdirSync(path, { recursive: true, mode: 0o700 }); check(path, true); }
19
+ const pathFor = (id: string) => {
20
+ if (!/^sa_[a-zA-Z0-9_-]+$/.test(id)) throw new Error("Invalid bridge attempt identity");
21
+ return join(directory, `${id}.json`);
22
+ };
23
+ return {
24
+ socketPath: join(socketDirectory, "operations.sock"),
25
+ save(registration: WorkerOperationRegistration, token: string) {
26
+ const path = pathFor(registration.runId), pending = `${path}.${process.pid}.tmp`;
27
+ writeFileSync(pending, JSON.stringify({ registration, token }), { mode: 0o600, flag: "wx" });
28
+ renameSync(pending, path);
29
+ },
30
+ remove(id: string) { try { unlinkSync(pathFor(id)); } catch (error) { if ((error as NodeJS.ErrnoException).code !== "ENOENT") throw error; } },
31
+ restore(): Array<WorkerOperationRegistration & { token: string }> {
32
+ const records = [];
33
+ for (const name of readdirSync(directory)) {
34
+ if (!name.endsWith(".json")) continue;
35
+ const path = join(directory, name);
36
+ if (check(path, false).size > 1024 * 1024) throw new Error("Worker bridge admission record is too large");
37
+ const { registration, token } = JSON.parse(readFileSync(path, "utf8"));
38
+ const meta = readMeta(registration.runId);
39
+ if (!meta || meta.management?.root !== root || !["running", "orphaned"].includes(meta.status) || !processExists(meta.pid)) continue;
40
+ if (!meta.pidStartTime || processStartToken(meta.pid) !== meta.pidStartTime) throw new Error("Worker bridge writer identity is unverified");
41
+ const lease = readConversationLease(meta.sessionId);
42
+ if (!lease || lease.token !== registration.writerLeaseId || lease.attemptId !== meta.id || registration.conversationId !== meta.sessionId) throw new Error("Worker bridge writer lease changed");
43
+ records.push({ ...registration, token });
44
+ }
45
+ return records;
46
+ },
47
+ };
48
+ }
@@ -0,0 +1,11 @@
1
+ /** Fixed SDK bootstrap for server-owned workers; never executes a PATH-selected launcher. */
2
+ import "./managed-launch-bootstrap.mjs";
3
+ import preflight from "./child-preflight.mjs";
4
+ import { dirname, join } from "node:path";
5
+ import { fileURLToPath, pathToFileURL } from "node:url";
6
+
7
+ if (Number(process.versions.node.split(".")[0]) < 24) throw new Error("Managed subagents require Node 24 or newer");
8
+ if (!process.env.PI_MANAGED_SUBAGENT) throw new Error("Managed worker has no admitted launch intent");
9
+ const sdk = fileURLToPath(import.meta.resolve("@earendil-works/pi-coding-agent"));
10
+ const { main } = await import(pathToFileURL(join(dirname(sdk), "main.js")).href);
11
+ await main(process.argv.slice(2), { extensionFactories: [{ name: "managed-subagent-preflight", factory: preflight }] });
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "pi-better-subagents",
3
- "version": "0.34.0",
3
+ "version": "0.35.0",
4
4
  "description": "Pi extension for detached, sandboxed subagent runs that keep the foreground session free.",
5
5
  "license": "MIT",
6
6
  "type": "module",
@@ -57,6 +57,7 @@ export function resolveCommandSettings(
57
57
  export type PermissionSnapshot = Readonly<{
58
58
  permissions?: PermissionProfile;
59
59
  subagentPermissions?: PermissionProfile;
60
+ backgroundPolicy?: Readonly<{state:string;permissions?:PermissionProfile;writableRoot?:string;denyWrite?:readonly string[];reason?:string}>;
60
61
  subagentTools?: SubagentToolSettings;
61
62
  }>;
62
63
 
@@ -95,11 +96,22 @@ function profile(value: unknown): PermissionProfile {
95
96
  });
96
97
  }
97
98
 
99
+ function backgroundPolicy(value:unknown): NonNullable<PermissionSnapshot['backgroundPolicy']> {
100
+ if(!value||typeof value!=='object')throw new Error('Invalid Background policy snapshot');
101
+ const p=value as Record<string,unknown>;
102
+ if(!['inactive','enabled','disabled','unavailable','failed'].includes(String(p.state)))throw new Error('Invalid Background policy state');
103
+ return Object.freeze({state:String(p.state),...(p.permissions?{permissions:profile(p.permissions)}:{}),
104
+ ...(typeof p.writableRoot==='string'?{writableRoot:p.writableRoot}:{}),
105
+ ...(Array.isArray(p.denyWrite)&&p.denyWrite.every(item=>typeof item==='string')?{denyWrite:[...p.denyWrite] as string[]}:{}),
106
+ ...(typeof p.reason==='string'?{reason:p.reason}:{})});
107
+ }
108
+
98
109
  function readPolicy(data: unknown): PermissionSnapshot | undefined {
99
110
  if (!data || typeof data !== "object") return undefined;
100
111
  const p = data as Record<string, unknown>;
101
112
  if (!["inactive", "enabled", "disabled", "unavailable", "failed"].includes(String(p.state))) return undefined;
102
113
  return Object.freeze({
114
+ ...(p.background === undefined ? {} : {backgroundPolicy: backgroundPolicy(p.background)}),
103
115
  ...(p.permissions === undefined ? {} : { permissions: profile(p.permissions) }),
104
116
  ...(p.subagentPermissions === undefined ? {} : { subagentPermissions: profile(p.subagentPermissions) }),
105
117
  ...(p.subagentTools === undefined ? {} : { subagentTools: parseSubagentTools(p.subagentTools) }),
package/registry.ts CHANGED
@@ -233,6 +233,8 @@ export interface RunMeta {
233
233
  resumedFrom?: string;
234
234
  /** Effective launch recipe, frozen at launch for continuation. */
235
235
  recipe?: LaunchRecipe;
236
+ /** Mechanical manager, separate from the original spawnPid capacity domain. */
237
+ management?: { root: string; instance: string; epoch: number };
236
238
  /** Foreground session that is allowed to receive unsolicited callbacks. */
237
239
  callbackOrigin?: RunCallbackOrigin;
238
240
  /** Durable ordinary-completion callback recovery and successful-handoff markers. */
@@ -1 +1 @@
1
- {"build":{"format":1,"sourceDigest":"f1a415e52552342511151e078257a3d81660989f30a684a263fb8f6252ac9e63","piSdkVersion":"1.4.0","nodeVersion":"24.14.1","platform":"darwin-arm64","dependencyLockDigest":"c63ff3a60c411a06ad881d6ae81fbe88402cc1ff3a3447bf54765b090b2c77bb","protocolVersion":1,"serverVersion":"0.4.0","contentId":"d8babdaa88ccdf11463b69738823e4175a88cb25e1f6b51bd1cde1dc5ebbd6b3"},"sha256":"40cbb55c9f6bcba62ac2fde5d00521d44c627177baede403fdfa9ee53ccec6ce"}
1
+ {"build":{"format":1,"sourceDigest":"e89627fd959da4e828f709c00fa6b2178ffac42197f95bd118ba7d4625f97a25","piSdkVersion":"1.4.0","nodeVersion":"24.14.1","platform":"darwin-arm64","dependencyLockDigest":"a104a72371ffce16cf6acd48e6ccbbf36023e4eb0fbe571677bdaeaa4fb84c27","protocolVersion":1,"serverVersion":"0.5.0","contentId":"ff6f0431d44ca8784bb3075ecd23f3f819435df221fa8635def2c05d826a23af"},"sha256":"74642cefa6adb1f02c54e759bd3f9f81ab21c18c27ca05ba09302f5ef12a61f1"}
@@ -1 +1 @@
1
- {"build":{"format":1,"sourceDigest":"f1a415e52552342511151e078257a3d81660989f30a684a263fb8f6252ac9e63","piSdkVersion":"1.4.0","nodeVersion":"24.14.1","platform":"darwin-x64","dependencyLockDigest":"c63ff3a60c411a06ad881d6ae81fbe88402cc1ff3a3447bf54765b090b2c77bb","protocolVersion":1,"serverVersion":"0.4.0","contentId":"0c892582dfd3e78b9f5fc25821dfd6b7c233f7f8b6d31677196dc3aaeda0a909"},"sha256":"61e469f213ae5ef7e379897f03f069b4a8c668a3a338f7fee7cafffeb7c648f3"}
1
+ {"build":{"format":1,"sourceDigest":"e89627fd959da4e828f709c00fa6b2178ffac42197f95bd118ba7d4625f97a25","piSdkVersion":"1.4.0","nodeVersion":"24.14.1","platform":"darwin-x64","dependencyLockDigest":"a104a72371ffce16cf6acd48e6ccbbf36023e4eb0fbe571677bdaeaa4fb84c27","protocolVersion":1,"serverVersion":"0.5.0","contentId":"9e4de6d9e748e598ebed703c087df5b5bc76f01cd02ecf482c75b7f95ac881d7"},"sha256":"1e9387e6da69c4ba18cdbbc0f70fe01e4700c73e69ea507e4a30db761478b0be"}
@@ -1 +1 @@
1
- {"build":{"format":1,"sourceDigest":"f1a415e52552342511151e078257a3d81660989f30a684a263fb8f6252ac9e63","piSdkVersion":"1.4.0","nodeVersion":"24.14.1","platform":"linux-arm64","dependencyLockDigest":"c63ff3a60c411a06ad881d6ae81fbe88402cc1ff3a3447bf54765b090b2c77bb","protocolVersion":1,"serverVersion":"0.4.0","contentId":"d71fc0b69c23b6808726d5a971c3ddd1da00985dfb655c79190b83c3997fcb1f"},"sha256":"057130e7109c592068e375f31a5f39297163326bb88f6461d59ae4e7742d7a80"}
1
+ {"build":{"format":1,"sourceDigest":"e89627fd959da4e828f709c00fa6b2178ffac42197f95bd118ba7d4625f97a25","piSdkVersion":"1.4.0","nodeVersion":"24.14.1","platform":"linux-arm64","dependencyLockDigest":"a104a72371ffce16cf6acd48e6ccbbf36023e4eb0fbe571677bdaeaa4fb84c27","protocolVersion":1,"serverVersion":"0.5.0","contentId":"f440118e90639f06127f3f2082a117e8d4aaa137ecde155870192539fc200eaa"},"sha256":"e740abc2b40d3069701ce3540f2881fd836406eb6a66e856c834c967ee8e9e90"}
@@ -1 +1 @@
1
- {"build":{"format":1,"sourceDigest":"f1a415e52552342511151e078257a3d81660989f30a684a263fb8f6252ac9e63","piSdkVersion":"1.4.0","nodeVersion":"24.14.1","platform":"linux-x64","dependencyLockDigest":"c63ff3a60c411a06ad881d6ae81fbe88402cc1ff3a3447bf54765b090b2c77bb","protocolVersion":1,"serverVersion":"0.4.0","contentId":"5e132e98f011fb0eee44a2184ef8d17787a7ac0f1b792b676b08582d248ba19f"},"sha256":"a007cde2962d0b0eb4fe378a3e9d08fd2f20ada6fce2c96b76f849cb6dd62c96"}
1
+ {"build":{"format":1,"sourceDigest":"e89627fd959da4e828f709c00fa6b2178ffac42197f95bd118ba7d4625f97a25","piSdkVersion":"1.4.0","nodeVersion":"24.14.1","platform":"linux-x64","dependencyLockDigest":"a104a72371ffce16cf6acd48e6ccbbf36023e4eb0fbe571677bdaeaa4fb84c27","protocolVersion":1,"serverVersion":"0.5.0","contentId":"d750352fca4145db9e04031a9a8c384ec19c9bd3277dd5139e881d8f0f79fe04"},"sha256":"923e3a45528bd8cb1354ccffe53ca7c8a613d458b2b1914f8e94698146499cc8"}
@@ -158,6 +158,8 @@ export interface CallbackBatchEvent {
158
158
  }
159
159
 
160
160
  export interface UrgentCallbackEvent {
161
+ /** Durable recipient transcript identity for handoff/receipt crash recovery. */
162
+ receiptId?: string;
161
163
  source: CallbackSource;
162
164
  /** Notification identity (dedupe/receipts). */
163
165
  id: string;
@@ -743,7 +745,8 @@ export function createCallbackBatcher(
743
745
  urgentInFlight.add(key);
744
746
  try {
745
747
  const handoff = host.sendMessage(
746
- { customType: event.customType, content: formatUrgentCallback(event, { maxBytes }), display: true },
748
+ { customType: event.customType, content: formatUrgentCallback(event, { maxBytes }), display: true,
749
+ ...(event.receiptId ? { details: { urgentEventId: event.receiptId } } : {}) },
747
750
  { deliverAs: "followUp", triggerTurn: true },
748
751
  );
749
752
  if (isPromiseLike(handoff)) {
@@ -1072,6 +1072,9 @@ export function readFailureState(path: string): FailureState {
1072
1072
  for (const record of remaining ?? []) state = reduceFailure(state, record.event, record.observedAt);
1073
1073
  return remaining?.length ? storageProblem(state, "Failure evidence could not be persisted") : state;
1074
1074
  }
1075
+ /** Read-only projection: never retries or appends process-local pending writes. */
1076
+ export function readFailureStateReadOnly(path: string): FailureState { return readStoredState(path); }
1077
+
1075
1078
  function readStoredState(path: string): FailureState {
1076
1079
  let source: string;
1077
1080
  try { source = readFileSync(path, "utf8"); }
@@ -64,6 +64,7 @@ export type BackgroundWorkProvider = {
64
64
  showSection?(rows: BackgroundWorkRow[], now: number): boolean;
65
65
  parentRow?(now: number): BackgroundWorkRow | null;
66
66
  listRows(now: number): BackgroundWorkRow[];
67
+ prepareDetail?(id: string, options?: {logTailLines?: number}): void;
67
68
  detail(id: string, now: number, options?: { logTailLines?: number }): BackgroundWorkDetail | null;
68
69
  armCloseLabel(row: BackgroundWorkRow): string;
69
70
  close(id: string): BackgroundWorkCloseOutcome;
@@ -728,6 +729,11 @@ function singleLine(value: unknown): string {
728
729
  return String(value ?? "").replace(/[\r\n\t]+/g, " ").replace(/ {2,}/g, " ").trim();
729
730
  }
730
731
 
732
+ function prepareDetail(navigatorId: string, options?: {logTailLines?: number}): void {
733
+ const {providerId,id}=splitRowKey(navigatorId);
734
+ try {state().providers.get(providerId)?.prepareDetail?.(id,options);}catch {/* observation failure retains cached detail */}
735
+ }
736
+
731
737
  function detailFor(navigatorId: string, now = Date.now(), options?: { logTailLines?: number }): BackgroundWorkDetail | null {
732
738
  const { providerId, id } = splitRowKey(navigatorId);
733
739
  const provider = state().providers.get(providerId);
@@ -989,10 +995,12 @@ function createOverlayComponent(
989
995
  const overlayState: OverlayState = { rows: initialRows, selected: 0 };
990
996
  let logTailRows: number = DEFAULT_LOG_TAIL_ROWS;
991
997
  const expandedSections = new Set<string>();
998
+ const initializedSections = new Set<string>();
992
999
  let detailId: string = initialDetailId;
993
1000
  const initialRow = initialRows.find((row) => row.navigatorId === detailId);
1001
+ prepareDetail(detailId,{logTailLines:logTailRows});
994
1002
  let detail: BackgroundWorkDetail | null = detailFor(detailId, Date.now(), { logTailLines: logTailRows }) ?? (initialRow ? fallbackDetail(initialRow) : null);
995
- applyDefaultExpandedSections(detail, expandedSections);
1003
+ applyDefaultExpandedSections(detail, expandedSections, initializedSections);
996
1004
  {
997
1005
  const idx = overlayState.rows.findIndex((row) => row.navigatorId === detailId);
998
1006
  if (idx >= 0) overlayState.selected = idx;
@@ -1028,6 +1036,7 @@ function createOverlayComponent(
1028
1036
  const detailScheduler = createRenderScheduler(() => {
1029
1037
  if (closed) return;
1030
1038
  detail = detailFor(detailId, Date.now(), { logTailLines: logTailRows }) ?? detail;
1039
+ applyDefaultExpandedSections(detail, expandedSections, initializedSections);
1031
1040
  requestRender();
1032
1041
  startDetailTimer();
1033
1042
  });
@@ -1079,8 +1088,10 @@ function createOverlayComponent(
1079
1088
  clearCloseArm();
1080
1089
  detailId = row.navigatorId;
1081
1090
  expandedSections.clear();
1091
+ initializedSections.clear();
1092
+ prepareDetail(detailId,{logTailLines:logTailRows});
1082
1093
  detail = detailFor(row.navigatorId, Date.now(), { logTailLines: logTailRows }) ?? fallbackDetail(row);
1083
- applyDefaultExpandedSections(detail, expandedSections);
1094
+ applyDefaultExpandedSections(detail, expandedSections, initializedSections);
1084
1095
  startDetailTimer();
1085
1096
  requestRender();
1086
1097
  }
@@ -1251,12 +1262,15 @@ function createOverlayComponent(
1251
1262
  const key = data === "m" || data === "M" ? "m" : "ctrl+s";
1252
1263
  if (!row || !provider?.handleDetailInput?.(row.id, key)) return;
1253
1264
  detail = detailFor(detailId, Date.now(), { logTailLines: logTailRows }) ?? detail;
1265
+ applyDefaultExpandedSections(detail, expandedSections, initializedSections);
1254
1266
  refreshMainListWidget();
1255
1267
  requestRender();
1256
1268
  }
1257
1269
  else if (data === "l" || data === "L") {
1258
1270
  logTailRows = cycleLogTailRows(logTailRows);
1271
+ prepareDetail(detailId,{logTailLines:logTailRows});
1259
1272
  if (detailId) detail = detailFor(detailId, Date.now(), { logTailLines: logTailRows }) ?? detail;
1273
+ applyDefaultExpandedSections(detail, expandedSections, initializedSections);
1260
1274
  requestRender();
1261
1275
  }
1262
1276
  else if (deps.matchKey(data, "escape")) {
@@ -1266,9 +1280,9 @@ function createOverlayComponent(
1266
1280
  /** Observation arrival updates this row without resetting selection or folded sections. */
1267
1281
  refreshDetail() {
1268
1282
  if (closed) return;
1269
- const wasLoading = detail?.status === "rebuilding";
1283
+ prepareDetail(detailId,{logTailLines:logTailRows});
1270
1284
  detail = detailFor(detailId, Date.now(), { logTailLines: logTailRows }) ?? detail;
1271
- if (wasLoading) applyDefaultExpandedSections(detail, expandedSections);
1285
+ applyDefaultExpandedSections(detail, expandedSections, initializedSections);
1272
1286
  startDetailTimer();
1273
1287
  requestRender();
1274
1288
  },
@@ -1502,8 +1516,12 @@ function firstToggleableSectionId(detail: BackgroundWorkDetail | null | undefine
1502
1516
  return detail && isFoldableEvidence(detail) ? EVIDENCE_SECTION_ID : undefined;
1503
1517
  }
1504
1518
 
1505
- function applyDefaultExpandedSections(detail: BackgroundWorkDetail | null, expandedSections: Set<string>): void {
1519
+ function applyDefaultExpandedSections(detail: BackgroundWorkDetail | null, expandedSections: Set<string>, initializedSections: Set<string>): void {
1506
1520
  for (const section of detail?.foldedSections ?? []) {
1521
+ if (initializedSections.has(section.id)) continue;
1522
+ // Details can arrive after a running row's fallback. Initialize each section
1523
+ // on first arrival, then preserve the user's choice across observations.
1524
+ initializedSections.add(section.id);
1507
1525
  if (section.expandedByDefault) expandedSections.add(section.id);
1508
1526
  }
1509
1527
  }
@@ -65,6 +65,8 @@ export function createAssignmentReader(path) {
65
65
  db ??= new DatabaseSync(path, { readOnly: true });
66
66
  return `${identity}:${db.prepare("PRAGMA data_version").get().data_version}`;
67
67
  },
68
+ connection(refresh = true) { if (refresh) this.revision(); return db; },
69
+
68
70
  beginSnapshot() {
69
71
  this.revision();
70
72
  if (snapshot) throw new Error("Coordinator snapshot already open");
@@ -80,6 +82,7 @@ export function createAssignmentReader(path) {
80
82
  return { revision: this.revision(), release };
81
83
  } catch (error) { release(); throw error; }
82
84
  },
85
+
83
86
  read(owner) {
84
87
  try {
85
88
  this.revision();
@@ -115,6 +118,33 @@ export function createAssignmentReader(path) {
115
118
  return new Map([...hashes].map(([key, hash]) => [key, hash.digest("hex")]));
116
119
  } catch { return undefined; }
117
120
  },
121
+ upgradeObligations() {
122
+ try { this.revision(); } catch (error) {
123
+ if (error.code === "ENOENT") return [];
124
+ throw error;
125
+ }
126
+ const version = db.prepare("SELECT value FROM schema_meta WHERE key='schema_version'").get()?.value;
127
+ if (!["1", "2", "3", "4"].includes(version)) throw new Error("Unsupported coordinator schema during upgrade");
128
+ const obligations = db.prepare("SELECT operation_id, task_id, observer_kind FROM operations WHERE phase='running' AND terminal_revision=0").all()
129
+ .map(row => ({ kind: "unsettled-operation", id: row.task_id, operationId: row.operation_id, observer: row.observer_kind }));
130
+ const reasons = db.prepare("SELECT claim_id AS id, state FROM resume_claims WHERE state IN ('claimed', 'published')").all()
131
+ .map(row => ({ kind: "resume-claim", id: row.id, state: row.state }));
132
+ for (const row of db.prepare("SELECT wait_id, generation, phase FROM waits WHERE owner_kind='worker-conversation' AND phase NOT IN ('consumed', 'cancelled') AND dispatch_disarmed=0").all()) {
133
+ reasons.push({ kind: "worker-wait", id: row.wait_id, generation: row.generation, phase: row.phase });
134
+ }
135
+ if (db.prepare("SELECT 1 FROM sqlite_master WHERE type='table' AND name='subagent_launch_intents'").get()) {
136
+ for (const row of db.prepare("SELECT owner, request_key, attempts FROM subagent_launch_intents WHERE state='accepted'").all()) {
137
+ reasons.push({ kind: "launch-intent", id: row.request_key, owner: row.owner, attempts: JSON.parse(row.attempts).map(attempt => attempt.id) });
138
+ }
139
+ }
140
+ for (const row of db.prepare("SELECT value FROM coordinator_state WHERE key LIKE 'background-request-v1:%'").all()) {
141
+ const request = JSON.parse(row.value);
142
+ if (request.state !== 'returned') reasons.push({kind:'background-request', id:request.key, owner:request.owner});
143
+ }
144
+ return [...obligations, ...reasons];
145
+ },
146
+
118
147
  close() { if (snapshot) { db.exec("ROLLBACK"); snapshot = false; } db?.close(); db = undefined; statements.clear(); identity = undefined; },
148
+
119
149
  };
120
150
  }
@@ -118,3 +118,5 @@ export { StoreError, isStoreError } from "./src/errors.ts";
118
118
  export type { StoreErrorCode } from "./src/errors.ts";
119
119
  export { openStore, ownerDiff } from "./src/store.ts";
120
120
  export type { Store } from "./src/store.ts";
121
+
122
+ export type { ParentCallbackScope, ParentCallbackPage, RecentBackgroundTerminalPage } from './src/background-parent-callbacks.ts';
@@ -0,0 +1,68 @@
1
+ // Generated from packages/operation-coordinator/src/background-parent-callbacks.ts. Do not edit directly.
2
+ /** Pending parent notifications are obligations, independent of UI retention. */
3
+ import { bumpChangeRevision } from './discovery.ts';
4
+ import { mapOperation } from './rows.ts';
5
+ import { getRow, getRows, run, type StoreContext } from './sqlite.ts';
6
+ import { requireBoolean, requireCounter, requireId, requirePath } from './validate.ts';
7
+ import type { OperationRecord } from './types.ts';
8
+
9
+ export interface ParentCallbackScope { sessionId: string; workspace: string }
10
+ export interface ParentCallbackPage { after?: string; limit?: number }
11
+ export interface RecentBackgroundTerminalPage {
12
+ since: number;
13
+ after?: { terminalAt: number; operationId: string };
14
+ limit?: number;
15
+ owner?: ParentCallbackScope;
16
+ }
17
+ const pageSize = (limit = 256) => Math.max(1, Math.min(256, requireCounter('limit', limit)));
18
+ const scopeValues = (scope: ParentCallbackScope) => [requirePath('workspace', scope.workspace), requireId('sessionId', scope.sessionId)] as const;
19
+
20
+ export function setParentCallbackPending(ctx: StoreContext, taskId: string, pending: boolean): boolean {
21
+ taskId = requireId('taskId', taskId);
22
+ pending = requireBoolean('pending', pending);
23
+ return ctx.transaction(() => {
24
+ const operation = getRow(ctx, "SELECT operation_id, owner_workspace, owner_session_id FROM operations WHERE task_id=? AND owner_kind='parent-session' AND observer_kind='local-supervisor'", taskId);
25
+ if (!operation) return false;
26
+ const changed = pending
27
+ ? run(ctx, `INSERT OR IGNORE INTO background_parent_callbacks(operation_id,owner_kind,owner_workspace,owner_session_id)
28
+ VALUES (?,'parent-session',?,?)`, String(operation.operation_id), String(operation.owner_workspace), String(operation.owner_session_id))
29
+ : run(ctx, 'DELETE FROM background_parent_callbacks WHERE operation_id=?', String(operation.operation_id));
30
+ if (changed > 0) bumpChangeRevision(ctx);
31
+ return changed > 0;
32
+ });
33
+ }
34
+
35
+ export function listPendingParentCallbacks(ctx: StoreContext, scope: ParentCallbackScope, options: ParentCallbackPage = {}): OperationRecord[] {
36
+ return getRows(ctx, `SELECT o.* FROM background_parent_callbacks p JOIN operations o ON o.operation_id=p.operation_id
37
+ WHERE p.owner_kind='parent-session' AND p.owner_workspace=? AND p.owner_session_id=? AND p.operation_id>? AND o.terminal_revision>0
38
+ ORDER BY p.operation_id LIMIT ?`, ...scopeValues(scope), options.after === undefined ? '' : requireId('after', options.after), pageSize(options.limit)).map(mapOperation);
39
+ }
40
+
41
+ export function listRecentBackgroundTerminals(ctx: StoreContext, options: RecentBackgroundTerminalPage): OperationRecord[] {
42
+ const params: Array<string|number> = [requireCounter('since', options.since)];
43
+ let where = "observer_kind='local-supervisor' AND terminal_revision>0 AND terminal_at>=?";
44
+ if (options.owner) { where += " AND owner_kind='parent-session' AND owner_workspace=? AND owner_session_id=?"; params.push(...scopeValues(options.owner)); }
45
+ if (options.after) { where += ' AND (terminal_at,operation_id)>(?,?)'; params.push(requireCounter('after.terminalAt', options.after.terminalAt), requireId('after.operationId', options.after.operationId)); }
46
+ params.push(pageSize(options.limit));
47
+ return getRows(ctx, `SELECT * FROM operations WHERE ${where} ORDER BY terminal_at,operation_id LIMIT ?`, ...params).map(mapOperation);
48
+ }
49
+
50
+ /** Call from the canonical manager in bounded batches, yielding between pages. */
51
+ export function seedPendingParentCallbacks(ctx: StoreContext, options: { limit?: number } = {}): { done: boolean; seeded: number } {
52
+ return ctx.transaction(() => {
53
+ const migration = getRow(ctx, 'SELECT * FROM background_parent_callback_migration WHERE singleton=1')!;
54
+ if (Number(migration.done)) return { done: true, seeded: 0 };
55
+ const limit = pageSize(options.limit);
56
+ const rows = getRows(ctx, `SELECT operation_id,owner_workspace,owner_session_id FROM operations
57
+ WHERE owner_kind='parent-session' AND observer_kind='local-supervisor' AND operation_id>? AND operation_id<=?
58
+ ORDER BY operation_id LIMIT ?`, String(migration.after_operation_id), String(migration.through_operation_id), limit);
59
+ let seeded = 0;
60
+ for (const row of rows) seeded += Number(run(ctx, `INSERT OR IGNORE INTO background_parent_callbacks(operation_id,owner_kind,owner_workspace,owner_session_id)
61
+ VALUES (?,'parent-session',?,?)`, String(row.operation_id), String(row.owner_workspace), String(row.owner_session_id)));
62
+ const after = rows.length ? String(rows.at(-1)!.operation_id) : String(migration.after_operation_id);
63
+ const done = rows.length < limit || after === migration.through_operation_id;
64
+ run(ctx, 'UPDATE background_parent_callback_migration SET after_operation_id=?,done=? WHERE singleton=1', after, done ? 1 : 0);
65
+ if (seeded) bumpChangeRevision(ctx);
66
+ return { done, seeded };
67
+ });
68
+ }
@@ -0,0 +1,79 @@
1
+ // Generated from packages/operation-coordinator/src/background-requests.ts. Do not edit directly.
2
+ import { createHash } from 'node:crypto';
3
+ import type { StoreContext } from './sqlite.ts';
4
+ export interface BackgroundRequest {
5
+ owner: string;
6
+ key: string;
7
+ digest: string;
8
+ state: 'accepted' | 'dispatching' | 'returned';
9
+ operations: Array<{
10
+ operationId: string;
11
+ taskId: string;
12
+ token: string;
13
+ }>;
14
+ result?: unknown;
15
+ }
16
+ const prefix = 'background-request-v1:';
17
+ // A partial index excludes returned history. CASE protects other coordinator
18
+ // records and makes corrupt request rows visible to recovery rather than hiding them.
19
+ const pendingPredicate = "key GLOB 'background-request-v1:*' AND CASE WHEN json_valid(value) THEN COALESCE(json_extract(value, '$.state'), '') != 'returned' ELSE 1 END";
20
+ export const BACKGROUND_PENDING_QUERY = `SELECT value FROM coordinator_state INDEXED BY background_requests_pending WHERE ${pendingPredicate} ORDER BY key LIMIT ?`;
21
+ function storageKey(owner: string, key: string) { return prefix + createHash('sha256').update(JSON.stringify([owner, key])).digest('hex'); }
22
+ export class BackgroundRequests {
23
+ private context: StoreContext;
24
+ private alive: () => void;
25
+ constructor(context: StoreContext, alive: () => void) {
26
+ this.context = context;
27
+ this.alive = alive;
28
+ alive();
29
+ context.db.exec(`CREATE INDEX IF NOT EXISTS background_requests_pending ON coordinator_state(key) WHERE ${pendingPredicate}`);
30
+ }
31
+ read(owner: string, key: string): BackgroundRequest | undefined {
32
+ this.alive();
33
+ const row = this.context.db.prepare('SELECT value FROM coordinator_state WHERE key=?').get(storageKey(owner, key));
34
+ return row ? JSON.parse(String(row.value)) : undefined;
35
+ }
36
+ private write(value: BackgroundRequest) {
37
+ this.context.db.prepare('INSERT OR REPLACE INTO coordinator_state (key,value) VALUES (?,?)').run(storageKey(value.owner, value.key), JSON.stringify(value));
38
+ }
39
+ accept(owner: string, key: string, digest: string) {
40
+ this.alive();
41
+ return this.context.transaction(() => {
42
+ const prior = this.read(owner, key);
43
+ if (prior) {
44
+ if (prior.digest !== digest)
45
+ throw new Error('request-conflict: Background request key changed content');
46
+ return { prior: true, record: prior };
47
+ }
48
+ const record: BackgroundRequest = { owner, key, digest, state: 'accepted', operations: [] };
49
+ this.write(record);
50
+ return { prior: false, record };
51
+ });
52
+ }
53
+ dispatch(owner: string, key: string) { this.update(owner, key, value => { if (value.state !== 'accepted')
54
+ throw new Error('Background request already dispatched'); value.state = 'dispatching'; }); }
55
+ operation(owner: string, key: string, operation: BackgroundRequest['operations'][number]) {
56
+ this.update(owner, key, value => {
57
+ if (value.state !== 'dispatching')
58
+ throw new Error('Background request is not dispatching');
59
+ if (value.operations.some(prior => prior.operationId === operation.operationId))
60
+ throw new Error('Background operation already prepared');
61
+ value.operations.push(operation);
62
+ });
63
+ }
64
+ finish(owner: string, key: string, result: unknown) { this.update(owner, key, value => { value.result = result; value.state = 'returned'; }); }
65
+ private update(owner: string, key: string, change: (value: BackgroundRequest) => void) {
66
+ this.alive();
67
+ this.context.transaction(() => { const value = this.read(owner, key); if (!value)
68
+ throw new Error('Background request not admitted'); change(value); this.write(value); });
69
+ }
70
+ hasPending(): boolean {
71
+ this.alive();
72
+ return Boolean(this.context.db.prepare(`SELECT 1 FROM coordinator_state INDEXED BY background_requests_pending WHERE ${pendingPredicate} LIMIT 1`).get());
73
+ }
74
+ pending(limit = 128): BackgroundRequest[] {
75
+ this.alive();
76
+ if (!Number.isSafeInteger(limit) || limit < 1 || limit > 128) throw new Error('Background recovery batch limit must be 1..128');
77
+ return this.context.db.prepare(BACKGROUND_PENDING_QUERY).all(limit).map(row => JSON.parse(String(row.value)));
78
+ }
79
+ }
@@ -30,6 +30,33 @@ const RESULT_ADMISSION_FENCE = `CREATE TRIGGER IF NOT EXISTS result_scope_admiss
30
30
  OR key = 'result-scope-v1:' || json_extract(NEW.supervision_json, '$.resultScope')))
31
31
  BEGIN SELECT RAISE(ABORT, 'permission-unavailable: legacy launch into managed result scope'); END`;
32
32
 
33
+ const BACKGROUND_CALLBACK_DDL = [
34
+ `CREATE TABLE IF NOT EXISTS background_parent_callbacks (
35
+ operation_id TEXT PRIMARY KEY REFERENCES operations(operation_id),
36
+ owner_kind TEXT NOT NULL CHECK(owner_kind='parent-session'),
37
+ owner_workspace TEXT NOT NULL,
38
+ owner_session_id TEXT NOT NULL
39
+ )`,
40
+ `CREATE TRIGGER IF NOT EXISTS background_parent_callback_registration
41
+ AFTER INSERT ON operations
42
+ WHEN NEW.owner_kind='parent-session' AND NEW.observer_kind='local-supervisor'
43
+ BEGIN INSERT OR IGNORE INTO background_parent_callbacks(operation_id,owner_kind,owner_workspace,owner_session_id)
44
+ VALUES(NEW.operation_id,NEW.owner_kind,NEW.owner_workspace,NEW.owner_session_id); END`,
45
+ `CREATE INDEX IF NOT EXISTS background_parent_callbacks_owner ON background_parent_callbacks(owner_kind,owner_workspace,owner_session_id,operation_id)`,
46
+ `CREATE INDEX IF NOT EXISTS operations_background_recent ON operations(terminal_at,operation_id) WHERE observer_kind='local-supervisor' AND terminal_revision>0`,
47
+ `CREATE INDEX IF NOT EXISTS operations_background_owner_recent ON operations(owner_kind,owner_workspace,owner_session_id,terminal_at,operation_id) WHERE observer_kind='local-supervisor' AND terminal_revision>0`,
48
+ `CREATE INDEX IF NOT EXISTS operations_background_parent_seed ON operations(operation_id) WHERE owner_kind='parent-session' AND observer_kind='local-supervisor'`,
49
+ `CREATE TABLE IF NOT EXISTS background_parent_callback_migration (
50
+ singleton INTEGER PRIMARY KEY CHECK(singleton=1),
51
+ after_operation_id TEXT NOT NULL,
52
+ through_operation_id TEXT NOT NULL,
53
+ done INTEGER NOT NULL CHECK(done IN (0,1))
54
+ )`,
55
+ `INSERT OR IGNORE INTO background_parent_callback_migration(singleton,after_operation_id,through_operation_id,done)
56
+ SELECT 1,'',COALESCE(MAX(operation_id),''),CASE WHEN MAX(operation_id) IS NULL THEN 1 ELSE 0 END
57
+ FROM operations WHERE owner_kind='parent-session' AND observer_kind='local-supervisor'`,
58
+ ];
59
+
33
60
  const DDL: readonly string[] = [
34
61
  `CREATE TABLE task_cancellation_authorities (
35
62
  credential_hash TEXT PRIMARY KEY,
@@ -84,6 +111,7 @@ const DDL: readonly string[] = [
84
111
  updated_at INTEGER NOT NULL,
85
112
  terminal_at INTEGER
86
113
  )`,
114
+ ...BACKGROUND_CALLBACK_DDL,
87
115
  `CREATE INDEX operations_owner ON operations (owner_kind, owner_session_id)`,
88
116
  `CREATE INDEX operations_phase ON operations (phase)`,
89
117
  `CREATE INDEX operations_running_supervisor ON operations (phase, supervision_host_id)`,
@@ -341,6 +369,9 @@ export function ensureSchema(ctx: StoreContext): void {
341
369
  * records during a rolling upgrade. Missing additions are created once on open.
342
370
  */
343
371
  function ensureAdditiveSchema(ctx: StoreContext): void {
372
+ // Schema/index creation is atomic; legacy obligation seeding is performed
373
+ // separately in bounded batches by the canonical manager.
374
+ ctx.transaction(() => { for (const statement of BACKGROUND_CALLBACK_DDL) ctx.db.exec(statement); });
344
375
  const hasColumn = (): boolean =>
345
376
  getRows(ctx, "PRAGMA table_info(operations)").some((row) => columnText(row, "name") === "supervision_host_id");
346
377
  const hasIndex = (): boolean =>
@@ -7,7 +7,11 @@
7
7
  * synchronous and transactional; a refusal throws `StoreError` with a typed code
8
8
  * and leaves no partial record.
9
9
  */
10
+ import { setUpgradeFence } from "./upgrade.ts";
11
+ import { setParentCallbackPending, listPendingParentCallbacks, listRecentBackgroundTerminals, seedPendingParentCallbacks, type ParentCallbackScope, type ParentCallbackPage, type RecentBackgroundTerminalPage } from './background-parent-callbacks.ts';
12
+ import { BackgroundRequests } from "./background-requests.ts";
10
13
  import { StoreError } from "./errors.ts";
14
+ import { SubagentLaunchJournal } from "./subagent-launch.ts";
11
15
  import { resultSupervision, resultSupervisions, resultScopeManaged, handoffResultScope, handoffResultSupervision, handoffResultSupervisions, recoverResultSupervision, publishSupervisedResult } from "./result-supervision.ts";
12
16
  import { acceptTaskCancellation, getTaskCancellation, recordTaskStopRequested, admitTaskCancellation, authorizedTaskCancellation, finishTaskCancellation, cancellationRuntimeEpoch, acceptAuthorizedTaskCancellation, taskCancellationManaged, pendingTaskCancellations, finishTaskCancellationIntent, unknownTaskCancellation } from "./task-cancellation.ts";
13
17
  import type { TaskCancellationIntent, TaskCancellationRequest } from "./task-cancellation.ts";
@@ -120,6 +124,7 @@ import {
120
124
  } from "./types.ts";
121
125
 
122
126
  export interface Store {
127
+ subagentLaunchJournal(): SubagentLaunchJournal;
123
128
  resultScopeManaged(scope: string): boolean;
124
129
  handoffResultScope(input: Parameters<typeof handoffResultScope>[1]): ReturnType<typeof handoffResultScope>;
125
130
  resultSupervision(operationId: string): ReturnType<typeof resultSupervision>;
@@ -161,6 +166,12 @@ export interface Store {
161
166
  * returns `created: false`, and any difference is refused with
162
167
  * `operation-conflict` or `task-ownership`.
163
168
  */
169
+ backgroundRequests(): BackgroundRequests;
170
+ setParentCallbackPending(taskId: string, pending: boolean): boolean;
171
+ listPendingParentCallbacks(scope: ParentCallbackScope, options?: ParentCallbackPage): OperationRecord[];
172
+ listRecentBackgroundTerminals(options: RecentBackgroundTerminalPage): OperationRecord[];
173
+ seedPendingParentCallbacks(options?: { limit?: number }): { done: boolean; seeded: number };
174
+ setUpgradeFence(epoch: string | null): void;
164
175
  registerOperation(input: RegisterOperationInput): RegisterOperationResult;
165
176
  /**
166
177
  * Replace supervision identity and/or report observer health
@@ -336,6 +347,7 @@ export function openStore(options: StoreOptions): Store {
336
347
  };
337
348
 
338
349
  const store: Store = {
350
+ subagentLaunchJournal() { alive(); return new SubagentLaunchJournal(ctx, alive); },
339
351
  resultScopeManaged(scope) { alive(); return resultScopeManaged(ctx, scope); },
340
352
  handoffResultScope(input) { alive(); return handoffResultScope(ctx, input); },
341
353
  resultSupervision(id) { alive(); return resultSupervision(ctx, id); },
@@ -366,6 +378,12 @@ export function openStore(options: StoreOptions): Store {
366
378
  closed = true;
367
379
  db.close();
368
380
  },
381
+ setParentCallbackPending(taskId, pending) { alive(); return setParentCallbackPending(ctx, taskId, pending); },
382
+ listPendingParentCallbacks(scope, options) { alive(); return listPendingParentCallbacks(ctx, scope, options); },
383
+ listRecentBackgroundTerminals(options) { alive(); return listRecentBackgroundTerminals(ctx, options); },
384
+ seedPendingParentCallbacks(options) { alive(); return seedPendingParentCallbacks(ctx, options); },
385
+ backgroundRequests() { alive(); return new BackgroundRequests(ctx, alive); },
386
+ setUpgradeFence(epoch) { alive(); setUpgradeFence(ctx, epoch); },
369
387
  registerOperation(input) {
370
388
  alive();
371
389
  return writeOperation(ctx, input);