@sema-agent/core 7.61.0 → 7.62.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 (176) hide show
  1. package/CHANGELOG.md +312 -0
  2. package/dist/agents/cascade.d.ts +11 -3
  3. package/dist/agents/cascade.js +1 -1
  4. package/dist/agents/peer-held-queue.d.ts +27 -4
  5. package/dist/agents/peer-held-queue.js +81 -36
  6. package/dist/agents/peer-session-drain.js +13 -3
  7. package/dist/agents/subagent.d.ts +6 -1
  8. package/dist/agents/subagent.js +66 -12
  9. package/dist/agents/suspend-guard.d.ts +38 -16
  10. package/dist/agents/suspend-guard.js +9 -4
  11. package/dist/agents/verify.js +4 -3
  12. package/dist/core/checkpoint-features.d.ts +722 -0
  13. package/dist/core/checkpoint-features.js +98 -0
  14. package/dist/core/checkpoint-requirements.d.ts +9 -2
  15. package/dist/core/checkpoint-requirements.js +9 -4
  16. package/dist/core/checkpoint-row-verdict.d.ts +99 -0
  17. package/dist/core/checkpoint-row-verdict.js +225 -0
  18. package/dist/core/checkpoint-store.d.ts +55 -745
  19. package/dist/core/checkpoint-store.js +39 -141
  20. package/dist/core/engine-notice.d.ts +19 -3
  21. package/dist/core/engine-notice.js +9 -2
  22. package/dist/core/gate-fold.js +2 -2
  23. package/dist/core/governance-codes.d.ts +3 -1
  24. package/dist/core/governance-codes.js +3 -0
  25. package/dist/core/hooks.d.ts +13 -0
  26. package/dist/core/human-input-projection.d.ts +1 -0
  27. package/dist/core/human-input-projection.js +3 -0
  28. package/dist/core/image-admission.d.ts +1 -1
  29. package/dist/core/locked-config.d.ts +2 -2
  30. package/dist/core/mcp-host-seat.js +6 -1
  31. package/dist/core/memory-engine/consolidation-driver.d.ts +1 -1
  32. package/dist/core/memory-vector.d.ts +1 -1
  33. package/dist/core/memory.d.ts +10 -10
  34. package/dist/core/mode-policy.js +1 -1
  35. package/dist/core/mods/classic-events.d.ts +9 -1
  36. package/dist/core/mods/dollar.d.ts +32 -1
  37. package/dist/core/mods/dollar.js +13 -1
  38. package/dist/core/mods/kernel/events.d.ts +11 -3
  39. package/dist/core/mods/kernel/events.js +13 -10
  40. package/dist/core/mods/lifecycle-stations.d.ts +36 -4
  41. package/dist/core/mods/lifecycle-stations.js +44 -9
  42. package/dist/core/mods/session-append.d.ts +4 -1
  43. package/dist/core/mods/session-append.js +7 -0
  44. package/dist/core/mods/session-receive.js +12 -15
  45. package/dist/core/mods/stations.d.ts +51 -6
  46. package/dist/core/mods/stations.js +124 -0
  47. package/dist/core/own-property-receipt.d.ts +7 -0
  48. package/dist/core/own-property-receipt.js +3 -0
  49. package/dist/core/read-root-candidate.js +1 -1
  50. package/dist/core/resume-startup-cause.d.ts +5 -4
  51. package/dist/core/runner/compact-session.js +5 -2
  52. package/dist/core/runner/contracts.d.ts +18 -8
  53. package/dist/core/runner/delegation-owner.d.ts +43 -0
  54. package/dist/core/runner/delegation-owner.js +59 -0
  55. package/dist/core/runner/lineage-reroot-view.d.ts +56 -0
  56. package/dist/core/runner/lineage-reroot-view.js +108 -0
  57. package/dist/core/runner/permission-rule-lanes.d.ts +2 -1
  58. package/dist/core/runner/permission-rule-lanes.js +2 -2
  59. package/dist/core/runner/person-path-rows.d.ts +15 -0
  60. package/dist/core/runner/person-path-rows.js +26 -3
  61. package/dist/core/runner/prepare-acquire-reconcile.d.ts +4 -1
  62. package/dist/core/runner/prepare-acquire-reconcile.js +7 -2
  63. package/dist/core/runner/prepare-caps-and-workflow.d.ts +1 -0
  64. package/dist/core/runner/prepare-caps-and-workflow.js +1 -1
  65. package/dist/core/runner/prepare-config-doors.d.ts +6 -6
  66. package/dist/core/runner/prepare-config-doors.js +3 -4
  67. package/dist/core/runner/prepare-hands-readface.d.ts +1 -1
  68. package/dist/core/runner/prepare-hands-readface.js +28 -7
  69. package/dist/core/runner/prepare-inherited-gate.d.ts +2 -0
  70. package/dist/core/runner/prepare-inherited-gate.js +7 -3
  71. package/dist/core/runner/prepare-task.js +10 -7
  72. package/dist/core/runner/resume-admission.d.ts +3 -3
  73. package/dist/core/runner/resume-admission.js +6 -3
  74. package/dist/core/runner/resume-apply.d.ts +4 -0
  75. package/dist/core/runner/resume-apply.js +11 -4
  76. package/dist/core/runner/resume-checkpoint-screen.d.ts +9 -0
  77. package/dist/core/runner/resume-checkpoint-screen.js +4 -84
  78. package/dist/core/runner/run-git-lane.d.ts +2 -0
  79. package/dist/core/runner/run-git-lane.js +4 -1
  80. package/dist/core/runner/run-harness-handlers.d.ts +2 -0
  81. package/dist/core/runner/run-harness-handlers.js +3 -2
  82. package/dist/core/runner/run-leg.js +24 -7
  83. package/dist/core/runner/run-settle-and-teardown.js +3 -2
  84. package/dist/core/runner/run-stop-and-final-verify.js +2 -1
  85. package/dist/core/runner/run-turn-boundary.js +7 -4
  86. package/dist/core/runner/runtask.js +6 -6
  87. package/dist/core/runner/steering-preview.d.ts +9 -0
  88. package/dist/core/runner/steering-preview.js +5 -0
  89. package/dist/core/runner/stream-steer-verb.js +8 -0
  90. package/dist/core/runner/tool-face-overlay.js +2 -0
  91. package/dist/core/runner/turn-attachments.d.ts +5 -0
  92. package/dist/core/runner/turn-attachments.js +1 -1
  93. package/dist/core/runner-deps.d.ts +2 -2
  94. package/dist/core/secret-env.d.ts +8 -5
  95. package/dist/core/secret-env.js +37 -18
  96. package/dist/core/session-store.d.ts +1 -1
  97. package/dist/core/session-store.js +5 -1
  98. package/dist/core/session.d.ts +14 -4
  99. package/dist/core/store-contracts/checkpoint-store-contract.d.ts +6 -0
  100. package/dist/core/store-contracts/checkpoint-store-contract.js +68 -0
  101. package/dist/core/store-contracts/session-store-contract.js +22 -8
  102. package/dist/core/task-event.d.ts +7 -1
  103. package/dist/core/task-notification.js +2 -1
  104. package/dist/core/task-registry-agent.d.ts +27 -7
  105. package/dist/core/task-registry-agent.js +12 -5
  106. package/dist/core/task-registry-shared.d.ts +7 -0
  107. package/dist/core/task-registry-workflow.js +4 -3
  108. package/dist/core/task-registry.d.ts +13 -2
  109. package/dist/core/task-registry.js +11 -4
  110. package/dist/core/task-result.d.ts +5 -5
  111. package/dist/core/task-spec.d.ts +1 -1
  112. package/dist/core/terminal-cause.d.ts +6 -6
  113. package/dist/core/tool-face.d.ts +6 -2
  114. package/dist/core/tool-face.js +1 -1
  115. package/dist/core/tool-policy.d.ts +2 -1
  116. package/dist/core/tool-roster.d.ts +4 -4
  117. package/dist/core/tool-spec.d.ts +4 -0
  118. package/dist/core/types.d.ts +1 -1
  119. package/dist/core/types.js +1 -1
  120. package/dist/engine/execution-env/node-execution-env.d.ts +3 -0
  121. package/dist/engine/execution-env/node-execution-env.js +12 -5
  122. package/dist/engine/harness/types.d.ts +11 -0
  123. package/dist/engine/session/parent-chain-guard.d.ts +3 -3
  124. package/dist/engine/session/parent-chain-guard.js +1 -1
  125. package/dist/engine/session/path-to-root.d.ts +18 -3
  126. package/dist/engine/session/path-to-root.js +15 -1
  127. package/dist/engine/session/repo-utils.d.ts +12 -1
  128. package/dist/engine/session/repo-utils.js +41 -0
  129. package/dist/engine/session/session.js +1 -1
  130. package/dist/engine/session/storage-base.d.ts +20 -0
  131. package/dist/engine/session/storage-base.js +28 -9
  132. package/dist/index.d.ts +9 -8
  133. package/dist/index.js +4 -4
  134. package/dist/internal/harness.d.ts +4 -3
  135. package/dist/internal/harness.js +3 -2
  136. package/dist/orchestration/run-workflow-tool.d.ts +3 -0
  137. package/dist/orchestration/run-workflow-tool.js +27 -11
  138. package/dist/orchestration/workflow-governance.d.ts +1 -1
  139. package/dist/orchestration/workflow.d.ts +3 -0
  140. package/dist/orchestration/workflow.js +2 -7
  141. package/dist/stores/file/checkpoint-store.d.ts +2 -0
  142. package/dist/stores/file/checkpoint-store.js +7 -6
  143. package/dist/stores/file/fs-atomic.d.ts +0 -22
  144. package/dist/stores/file/fs-atomic.js +0 -17
  145. package/dist/stores/file/index.d.ts +2 -9
  146. package/dist/stores/file/index.js +2 -4
  147. package/dist/stores/file/session-store.d.ts +13 -7
  148. package/dist/stores/file/session-store.js +40 -17
  149. package/dist/tools/fs/bash-program-position.d.ts +3 -2
  150. package/dist/tools/fs/bash-program-position.js +7 -7
  151. package/dist/tools/fs/removal-targets.js +2 -2
  152. package/dist/tools/fs/shell-read-argv.d.ts +4 -2
  153. package/dist/tools/fs/shell-read-argv.js +14 -3
  154. package/dist/tools/fs/shell-read-bindings.d.ts +18 -2
  155. package/dist/tools/fs/shell-read-bindings.js +148 -68
  156. package/dist/tools/fs/shell-read-check.js +20 -4
  157. package/dist/tools/fs/shell-read-establish.js +22 -8
  158. package/dist/tools/fs/shell-read-functions.js +2 -2
  159. package/dist/tools/fs/shell-read-object-path.d.ts +59 -0
  160. package/dist/tools/fs/shell-read-object-path.js +119 -0
  161. package/dist/tools/fs/shell-read-plan.d.ts +8 -0
  162. package/dist/tools/fs/shell-read-plan.js +47 -30
  163. package/dist/tools/fs/shell-read-start.d.ts +66 -13
  164. package/dist/tools/fs/shell-read-start.js +89 -17
  165. package/dist/tools/fs/shell-read-workdir.d.ts +29 -8
  166. package/dist/tools/fs/shell-read-workdir.js +31 -8
  167. package/package.json +2 -2
  168. package/test/export-surface.snapshot.json +21 -33
  169. package/wire-changes/core-stores-sql@7.62.0.json +30 -0
  170. package/wire-changes/core@7.62.0.json +2181 -0
  171. package/wire-changes/mods-kernel@7.62.0.json +42 -0
  172. package/wire-changes/primitives@7.62.0.json +30 -0
  173. package/dist/core/consolidate-scope.d.ts +0 -93
  174. package/dist/core/consolidate-scope.js +0 -98
  175. package/dist/core/runner/memory-consolidation.d.ts +0 -109
  176. package/dist/core/runner/memory-consolidation.js +0 -251
@@ -928,7 +928,8 @@ export type TaskEvent = ({
928
928
  * or the design/130 P2 graceful-finalize instruction) into the model's next turn. Previously these
929
929
  * went through `harness.steer()` with no stream echo — a consumer literally could not tell whether
930
930
  * the finalize fired (the refute-130 attribution blind spot). Echo only; the model-facing message
931
- * is unchanged. `preview` is the injected text clipped to a display bound.
931
+ * is unchanged. `preview` is the injected text clipped to a display bound (220 characters; the post-compaction
932
+ * `background_tasks` table, a list its renderer already bounds, is echoed whole up to the per-boundary attachment cap).
932
933
  *
933
934
  * design/133 (LOW-11/F11): the turn-boundary attachment producers ride the same echo — sources
934
935
  * `todo_reminder` / `task_reminder` / `changed_files` and the G1/续批 members
@@ -1053,6 +1054,11 @@ export type TaskEvent = ({
1053
1054
  * render it as the scheduler's, not as someone typing): the objective's `TaskSpec.runOrigin`, a parked or waking
1054
1055
  * message's `runOrigin`. Absent ⇒ the host said nothing (never "a person sent it"). Attribution only. */
1055
1056
  runOrigin?: import("./run-origin.js").RunOrigin;
1057
+ /** Present when the leg's prompt screen (`prompt.submit`) rewrote THIS input's text before it was delivered: the extensions
1058
+ * that changed it, in the order they did. The model saw the rewritten text (the caller's own words are not delivered);
1059
+ * rides the account the screening entrance mints — the `"applied"` frame of an objective, a parked steer or a wake's
1060
+ * message, the `"queued"` frame of a live steer. Absent ⇒ the text went as it came. */
1061
+ rewrittenBy?: readonly string[];
1056
1062
  } & TaskEventIdentity) | ({
1057
1063
  /**
1058
1064
  * design/99 §E3/§E10 — a live BRAIN-LAYER status the brain would otherwise absorb
@@ -1,6 +1,7 @@
1
1
  import { AsyncLocalStorage } from "node:async_hooks";
2
2
  import { escapeEnvelopeTag, inlineUntrusted, sanitizeUntrustedText } from "./untrusted-text.js";
3
3
  import { egressText } from "./untrusted-egress.js";
4
+ import { redactThenCut } from "../agents/subagent-steps.js";
4
5
  import { PEER_MESSAGE_NOTICE } from "../agents/peer-admission.js";
5
6
  import { buildCrossSessionEnvelope, CROSS_PRINCIPAL_MESSAGE_NOTICE, CROSS_SESSION_MESSAGE_NOTICE, neutralizePeerBody } from "../agents/cross-session-envelope.js";
6
7
  export const TASK_NOTIFICATION_TERMINAL_STATUSES = Object.freeze(["completed", "failed", "killed", "cancelled"]);
@@ -820,7 +821,7 @@ export function renderBackgroundTaskTable(tasks) {
820
821
  : t.status === "parked"
821
822
  ? "parked awaiting an out-of-band approval — do NOT re-issue the gated call"
822
823
  : t.status;
823
- return `- [${t.id}] Task "${(t.description ?? "background task").slice(0, BACKGROUND_TASK_TABLE_DESCRIPTION_MAX)}" ${phrase}${t.read !== undefined ? ` — ${t.read}` : ""}`;
824
+ return `- [${t.id}] Task "${redactThenCut(t.description ?? "background task", BACKGROUND_TASK_TABLE_DESCRIPTION_MAX)}" ${phrase}${t.read !== undefined ? ` — ${t.read}` : ""}`;
824
825
  });
825
826
  return lines.join("\n") + (unlisted > 0 ? `\n(+${unlisted} more background tasks, not listed here)` : "");
826
827
  }
@@ -1,5 +1,5 @@
1
1
  import { type BackgroundAgentRecord, type BackgroundAgentStore } from "./background-agent-store.js";
2
- import { type StopSource, type TaskAccess, type TaskRetrievalStatus, type UnifiedTaskOutput, type UnifiedTaskResult, type BackgroundAgentTaskHandle, type RegisteredTaskHandle, type DurableAgentCore, type ParkedClaimTicket, type RegisterBackgroundAgentInput } from "./task-registry-shared.js";
2
+ import { type StopSource, type TaskAccess, type TaskRetrievalStatus, type UnifiedTaskOutput, type UnifiedTaskResult, type BackgroundAgentTaskHandle, type ChildSessionStore, type RegisteredTaskHandle, type DurableAgentCore, type ParkedClaimTicket, type RegisterBackgroundAgentInput } from "./task-registry-shared.js";
3
3
  import { type AgentState } from "./agent-state.js";
4
4
  import type { CheckpointSeat } from "./checkpoint-seat.js";
5
5
  /**
@@ -13,6 +13,17 @@ import type { CheckpointSeat } from "./checkpoint-seat.js";
13
13
  * segment, which is what makes the reservation race-free in-process.
14
14
  */
15
15
  export declare function activeDelegationHandlesLane(core: DurableAgentCore, scope: string, rootSessionId: string): string[];
16
+ /** One running or pending row of a delegation tree, as its occupant is told of it: the task id every addressing tool takes, the row's
17
+ * addressing name, and whether the caller asked for can address it (the registry's access predicate — a nested agent does not reach
18
+ * its siblings' rows, so their ids and names are not its to be told). */
19
+ export interface DelegationOccupant {
20
+ readonly id: string;
21
+ readonly name: string;
22
+ readonly reachable: boolean;
23
+ }
24
+ /** The rows {@link activeDelegationHandlesLane} counts, with the name each is addressed by — the one selection, read in the same
25
+ * synchronous segment. `caller` is the access the asking leg's own tools hold (`scope` is the pool's); without one no row is reachable. */
26
+ export declare function activeDelegationOccupantsLane(core: DurableAgentCore, scope: string, rootSessionId: string, caller?: TaskAccess): DelegationOccupant[];
16
27
  export declare function ensureDurableHeartbeatLane(core: DurableAgentCore): void;
17
28
  /** design/151 S1a — enqueue one durable-row write (see {@link DurableAgentLane} for the lane
18
29
  * contract). `patch` is captured at CALL time (the settle-site values), applied in chain order.
@@ -116,11 +127,18 @@ export declare function reapDurableAgentsLane(core: DurableAgentCore, scope: str
116
127
  skippedNoSessions: number;
117
128
  orphanPlacedReleased: number;
118
129
  }>;
130
+ /** A background-agent row's child session: its id and the store the child's run holds it through (`undefined` when a
131
+ * caller outside the bind's types bound the id without one). */
132
+ export interface ChildSessionAnchor {
133
+ readonly sessionId: string;
134
+ readonly store: ChildSessionStore | undefined;
135
+ }
119
136
  /** The child session a background-agent row is anchored to right now — the session its child runs on
120
- * or keeps (transcript / resume anchor) — or `undefined` before the bind, after the anchor's release,
121
- * and on every other task type. The ONE reading of the anchor: the list row's `sessionId` and the
122
- * release match below both read it here. */
123
- export declare function childSessionAnchorOf(handle: RegisteredTaskHandle): string | undefined;
137
+ * or keeps (transcript / resume anchor), with the store that holds it — or `undefined` before the bind,
138
+ * after the anchor's release, and on every other task type. The ONE reading of the anchor: the list
139
+ * row's `sessionId`, the transcript read ({@link TaskRegistry.anchoredSession}) and the release and bind
140
+ * matches below all read it here. */
141
+ export declare function childSessionAnchorOf(handle: RegisteredTaskHandle): ChildSessionAnchor | undefined;
124
142
  /** A successful release of the child session `sessionId` ends the row's claim on it: both copies of
125
143
  * the anchor go — the handle's (the list row reads it) and the durable record's (the heartbeat's F-1
126
144
  * arm keeps re-driving a flush-failed lane, so a later successful flush would otherwise persist a row
@@ -133,8 +151,10 @@ export declare function releaseDurableTranscriptAnchorLane(core: DurableAgentCor
133
151
  * A row already anchored to that session is left as it is (one fact, no second durable write). A row anchored to ANOTHER session
134
152
  * is refused: an anchor changes only by its release ({@link releaseDurableTranscriptAnchorLane}) and a fresh bind, never by being
135
153
  * written over, so the earlier session is never silently left unowned. An id that is no non-empty string is no anchor and is
136
- * refused whatever the row holds. */
137
- export declare function bindBackgroundAgentSessionLane(core: DurableAgentCore, id: string, sessionId: string): void;
154
+ * refused whatever the row holds. `store` is the store the child's run holds that session through, bound with the id (the
155
+ * store is process-local; the durable record keeps the id alone). The store is judged where it is read: the transcript read
156
+ * (`$.session.messages`) refuses, naming why, one it cannot read through. */
157
+ export declare function bindBackgroundAgentSessionLane(core: DurableAgentCore, id: string, sessionId: string, store: ChildSessionStore): void;
138
158
  /**
139
159
  * #22 — record the org-memory admission verdict THIS leg adjudicated onto the durable row, so the
140
160
  * next CROSS-PROCESS revival (which rebuilds the spec from the reviving caller's mount and cannot
@@ -10,6 +10,9 @@ import { thrownLabel } from "./thrown-value.js";
10
10
  import { closestName } from "./closest-name.js";
11
11
  import { agentStateSourceOfHandle, agentStateSummary, readAgentState } from "./agent-state.js";
12
12
  export function activeDelegationHandlesLane(core, scope, rootSessionId) {
13
+ return activeDelegationOccupantsLane(core, scope, rootSessionId).map((o) => o.id);
14
+ }
15
+ export function activeDelegationOccupantsLane(core, scope, rootSessionId, caller) {
13
16
  const out = [];
14
17
  for (const h of core.handles.values()) {
15
18
  if (h.type !== "background_agent")
@@ -22,7 +25,7 @@ export function activeDelegationHandlesLane(core, scope, rootSessionId) {
22
25
  const root = bh.rootSessionId ?? bh.parentSessionId ?? (bh.sessionScoped ? bh.owner : undefined);
23
26
  if (root !== rootSessionId)
24
27
  continue;
25
- out.push(h.id);
28
+ out.push({ id: h.id, name: bh.name, reachable: caller !== undefined && canAccess(h, { ...caller, scope }) });
26
29
  }
27
30
  return out;
28
31
  }
@@ -312,29 +315,33 @@ export async function reapDurableAgentsLane(core, scope, deps, policy) {
312
315
  return { rowsReaped, sessionsReleased, skippedNoSessions, orphanPlacedReleased };
313
316
  }
314
317
  export function childSessionAnchorOf(handle) {
315
- return handle.type === "background_agent" ? handle.sessionId : undefined;
318
+ if (handle.type !== "background_agent" || handle.sessionId === undefined)
319
+ return undefined;
320
+ return { sessionId: handle.sessionId, store: handle.sessionStore };
316
321
  }
317
322
  export function releaseDurableTranscriptAnchorLane(core, id, sessionId) {
318
323
  const handle = core.handles.get(id);
319
324
  if (!handle || handle.type !== "background_agent")
320
325
  return;
321
- if (childSessionAnchorOf(handle) !== sessionId)
326
+ if (childSessionAnchorOf(handle)?.sessionId !== sessionId)
322
327
  return;
323
328
  delete handle.sessionId;
329
+ delete handle.sessionStore;
324
330
  durableAgentWriteLane(handle, {}, ["sessionId"]);
325
331
  }
326
- export function bindBackgroundAgentSessionLane(core, id, sessionId) {
332
+ export function bindBackgroundAgentSessionLane(core, id, sessionId, store) {
327
333
  if (typeof sessionId !== "string" || sessionId === "")
328
334
  throw new Error(`TaskRegistry: a background-agent session anchor must be a non-empty session id (got ${typeof sessionId === "string" ? "an empty string" : `a ${sessionId === null ? "null" : typeof sessionId}`})`);
329
335
  const handle = core.handles.get(id);
330
336
  if (!handle || handle.type !== "background_agent")
331
337
  return;
332
- const anchored = childSessionAnchorOf(handle);
338
+ const anchored = childSessionAnchorOf(handle)?.sessionId;
333
339
  if (anchored === sessionId)
334
340
  return;
335
341
  if (anchored !== undefined)
336
342
  throw new Error(`TaskRegistry: background-agent row ${id} is anchored to a session already — release that anchor before binding another (the row keeps its anchor)`);
337
343
  handle.sessionId = sessionId;
344
+ handle.sessionStore = store;
338
345
  durableAgentWriteLane(handle, { sessionId });
339
346
  }
340
347
  export function recordBackgroundAgentOrgAdmissionLane(core, id, verdict) {
@@ -255,6 +255,9 @@ export interface DurableAgentLane {
255
255
  * flush success); past the ceiling the lane is abandoned loudly instead of retrying forever. */
256
256
  redrives?: number;
257
257
  }
258
+ /** What a background agent's row keeps of the store its child session lives in: that store's `acquire` (structural, so any
259
+ * session store fits — the type-only import is erased, the one-way import rule at the top is untouched). */
260
+ export type ChildSessionStore = Pick<import("./session.js").SessionStore, "acquire">;
258
261
  export interface BackgroundAgentTaskHandle extends SemaTaskHandle {
259
262
  type: "background_agent";
260
263
  /** The spawning tree's cross-boundary token ({@link RegisterBackgroundAgentInput.crossBoundaryTree}), compared by identity. */
@@ -273,6 +276,10 @@ export interface BackgroundAgentTaskHandle extends SemaTaskHandle {
273
276
  * durable record's copy — by the successful release of that session
274
277
  * ({@link TaskRegistry.releaseDurableTranscriptAnchor}). Read through `childSessionAnchorOf` only. */
275
278
  sessionId?: string;
279
+ /** The store the child's run holds that session through, written by the same bind and removed by the same release as
280
+ * `sessionId` — a reader of the child's transcript travels with its row, never with the runner that happens to read it.
281
+ * Process-local: the durable record keeps the id alone, and a revival's own bind brings its own runner's store. */
282
+ sessionStore?: ChildSessionStore;
276
283
  /** design/151 S1a — the durable write lane (present iff the registration wired a store). */
277
284
  durable?: DurableAgentLane;
278
285
  /** design/147 S2a — the RUNNING child run's notification injector (attached once its lane is
@@ -38,10 +38,11 @@ export function registerWorkflowLane(core, input) {
38
38
  }, (err) => {
39
39
  if (handle.status !== "cancelled")
40
40
  handle.status = "failed";
41
- handle.error = boundedRedactedSummary(thrownText(err), 500);
42
41
  const settledRun = settledRunOf(input.handle.done);
43
- if (settledRun?.completionId !== undefined)
44
- handle.completionId = settledRun.completionId;
42
+ const settleId = settledRun?.completionId;
43
+ handle.error = boundedRedactedSummary(thrownText(err), 500);
44
+ if (settleId !== undefined)
45
+ handle.completionId = settleId;
45
46
  handle.updatedAt = Date.now();
46
47
  });
47
48
  return id;
@@ -9,7 +9,9 @@ import { type TaskArtifactSeat } from "./tool-result-store.js";
9
9
  import { type SemaTaskType, type StopSource, type SemaTaskStatus, type TaskRetrievalStatus, type UnifiedTaskOutput, type UnifiedTaskResult, type SemaTaskHandle, type TaskAccess, type BackgroundAgentTaskHandle, type MonitorTimers, type RegisterMonitorInput, type RegisterWorkflowInput, canAccessWorkflowRun, clipTaskOutput, MONITOR_BATCH_WINDOW_MS, MONITOR_DEFAULT_TIMEOUT_MS, MONITOR_MAX_TIMEOUT_MS, MONITOR_MAX_BATCHES_PER_MINUTE } from "./task-registry-shared.js";
10
10
  export { normalizeAgentName, DURABLE_AGENT_HEARTBEAT_MS, DURABLE_AGENT_HANDLE_RE, BG_AGENT_REAP_STOP_ERROR, engineAgentName, chosenAgentName } from "./task-registry-shared.js";
11
11
  export type { ParkedClaimTicket, RegisterBackgroundAgentInput } from "./task-registry-shared.js";
12
- import type { RegisterBackgroundAgentInput, ParkedClaimTicket } from "./task-registry-shared.js";
12
+ import type { RegisterBackgroundAgentInput, ParkedClaimTicket, ChildSessionStore } from "./task-registry-shared.js";
13
+ import type { ChildSessionAnchor } from "./task-registry-agent.js";
14
+ import { type DelegationOccupant } from "./task-registry-agent.js";
13
15
  import { type AgentStateSource } from "./agent-state.js";
14
16
  import type { CheckpointSeat } from "./checkpoint-seat.js";
15
17
  export type { SemaTaskType, StopSource, SemaTaskStatus, TaskRetrievalStatus, UnifiedTaskOutput, SemaTaskHandle, TaskAccess, MonitorTimers, RegisterMonitorInput, RegisterWorkflowInput, };
@@ -218,7 +220,9 @@ export declare class TaskRegistry {
218
220
  /** The successful release of child session `sessionId` ends row `id`'s anchor on it — handle and durable
219
221
  * record together, and only while the row still names that session (see {@link releaseDurableTranscriptAnchorLane}). */
220
222
  releaseDurableTranscriptAnchor(id: string, sessionId: string): void;
221
- bindBackgroundAgentSession(id: string, sessionId: string): void;
223
+ /** Anchor row `id` to its child session `sessionId`, held through `store` — the store the child's run creates or resumes that
224
+ * session in (see {@link bindBackgroundAgentSessionLane}). */
225
+ bindBackgroundAgentSession(id: string, sessionId: string, store: ChildSessionStore): void;
222
226
  registerBackgroundAgent(input: RegisterBackgroundAgentInput): string;
223
227
  /** #22 — persist this leg's org-memory admission verdict on the durable row (the cross-process
224
228
  * revival's only carrier). See {@link recordBackgroundAgentOrgAdmissionLane}. */
@@ -312,6 +316,9 @@ export declare class TaskRegistry {
312
316
  * contract (the caps check and the registration form one atomic segment). See
313
317
  * {@link activeDelegationHandlesLane}. */
314
318
  activeDelegationHandles(scope: string, rootSessionId: string): string[];
319
+ /** The same rows as {@link activeDelegationHandles}, each with its addressing name and whether `caller` reaches it — what a refusal
320
+ * of one more child may tell its caller about who holds the tree's slots. See {@link activeDelegationOccupantsLane}. */
321
+ activeDelegationOccupants(scope: string, rootSessionId: string, caller?: TaskAccess): DelegationOccupant[];
315
322
  /** ASYNC (revive arbitration) — the durable half is a guarded ownership claim on the row (awaited before the
316
323
  * in-memory flip), so this leg and a cross-process claim arbitrate in one domain instead of both
317
324
  * believing they own the cycle. See {@link reviveBackgroundAgentLane}. */
@@ -659,6 +666,10 @@ export declare class TaskRegistry {
659
666
  * cap ({@link list}'s): the one reading of a leg's live background tasks (its end's {@link owedDeliveries}, the post-compaction
660
667
  * listing and the resume's orphan diff, the suspend's snapshot), each consumer projecting its own columns from it. */
661
668
  liveTasks(access: TaskAccess): TaskListRow[];
669
+ /** The child session task `taskId`'s row is anchored to — its id and the store the child's run holds it through — when
670
+ * `access` reaches the row (the reach {@link list} reads with): `undefined` for an unknown or out-of-reach id, `null` for a
671
+ * reached row with no anchor (no background agent's row, not bound yet, or released). */
672
+ anchoredSession(taskId: string, access: TaskAccess): ChildSessionAnchor | null | undefined;
662
673
  /** Every row `access` reaches, newest first, in {@link list}'s projection — the one walk both readings take. */
663
674
  private rowsUnder;
664
675
  /** Throttled {@link gc} for hot-path callers (design/115 review B5): prepare-task runs once per task,
@@ -12,7 +12,7 @@ import { registerWorkflowLane, pollWorkflowLane, stopWorkflowLane } from "./task
12
12
  import { mintCompletionId, taskReadHandleText, canAccessWorkflowRun, formatWorkflowRun, clipTaskOutput, assertOwnership, sleepPollStep, statusFromBackground, rollSpoolText, accountDroppedBytes, renderSpoolBody, stdoutHeadingOf, REPLAY_FACE, SPOOL_REPLAY, INCREMENT_REPLAY, spoolDropNote, droppedGapNote, alreadyTerminalStopNote, terminalTaskSummary, TASK_OUTPUT_MAX_CHARS, MONITOR_BATCH_WINDOW_MS, MONITOR_DEFAULT_TIMEOUT_MS, MONITOR_MAX_TIMEOUT_MS, MONITOR_MAX_BATCHES_PER_MINUTE, canAccess, DURABLE_AGENT_HANDLE_RE, } from "./task-registry-shared.js";
13
13
  export { normalizeAgentName, DURABLE_AGENT_HEARTBEAT_MS, DURABLE_AGENT_HANDLE_RE, BG_AGENT_REAP_STOP_ERROR, engineAgentName, chosenAgentName } from "./task-registry-shared.js";
14
14
  import { TASK_STOP_TOOL_NAME, TASK_STOP_MISSING_ID_MESSAGE, TASK_STOP_PARAMS, TASK_STOP_DESCRIPTION, resolveTaskIdArg } from "./task-tool-shape.js";
15
- import { durableAgentArmedLane, durableAgentRowProbeLane, beginDurableClaimLane, endDurableClaimLane, reapDurableAgentsLane, noteBackgroundAgentActivityLane, reapStaleSessionBackgroundAgentsLane, releaseDurableTranscriptAnchorLane, bindBackgroundAgentSessionLane, childSessionAnchorOf, registerBackgroundAgentLane, recordBackgroundAgentOrgAdmissionLane, parkBackgroundAgentLane, reconcileParkedAgentsLane, claimParkedAgentLane, rollbackParkedClaimLane, consumeParkedFlipLane, finalizeParkedResumeLane, settleBackgroundAgentLane, abortBackgroundAgentsForOwnerLane, serveDurableAgentRowLane, resolveBackgroundAgentByNameLane, backgroundAgentCycleSeqLane, activeDelegationHandlesLane, markRetainedContinuationLane, reviveBackgroundAgentLane, settleRevivedAgentLane, unmarkRetainedContinuationLane, attachAgentNotifyLane, deliverToRunningAgentLane, runningBackgroundAgentLabelsLane, runningAgentFooterLane, notFoundRunningAgentsTail, pollBackgroundAgentLane, stopBackgroundAgentLane, } from "./task-registry-agent.js";
15
+ import { durableAgentArmedLane, durableAgentRowProbeLane, beginDurableClaimLane, endDurableClaimLane, reapDurableAgentsLane, noteBackgroundAgentActivityLane, reapStaleSessionBackgroundAgentsLane, releaseDurableTranscriptAnchorLane, bindBackgroundAgentSessionLane, childSessionAnchorOf, registerBackgroundAgentLane, recordBackgroundAgentOrgAdmissionLane, parkBackgroundAgentLane, reconcileParkedAgentsLane, claimParkedAgentLane, rollbackParkedClaimLane, consumeParkedFlipLane, finalizeParkedResumeLane, settleBackgroundAgentLane, abortBackgroundAgentsForOwnerLane, serveDurableAgentRowLane, resolveBackgroundAgentByNameLane, backgroundAgentCycleSeqLane, activeDelegationHandlesLane, activeDelegationOccupantsLane, markRetainedContinuationLane, reviveBackgroundAgentLane, settleRevivedAgentLane, unmarkRetainedContinuationLane, attachAgentNotifyLane, deliverToRunningAgentLane, runningBackgroundAgentLabelsLane, runningAgentFooterLane, notFoundRunningAgentsTail, pollBackgroundAgentLane, stopBackgroundAgentLane, } from "./task-registry-agent.js";
16
16
  import { mountRuleFace, toolFace } from "./tool-catalog-entries.js";
17
17
  import { thrownText } from "./thrown-value.js";
18
18
  import { agentStateSourceOfHandle, agentStateSourceOfRecord, agentStateSummary, readAgentState } from "./agent-state.js";
@@ -168,8 +168,8 @@ export class TaskRegistry {
168
168
  releaseDurableTranscriptAnchor(id, sessionId) {
169
169
  return releaseDurableTranscriptAnchorLane(this.core, id, sessionId);
170
170
  }
171
- bindBackgroundAgentSession(id, sessionId) {
172
- return bindBackgroundAgentSessionLane(this.core, id, sessionId);
171
+ bindBackgroundAgentSession(id, sessionId, store) {
172
+ return bindBackgroundAgentSessionLane(this.core, id, sessionId, store);
173
173
  }
174
174
  registerBackgroundAgent(input) {
175
175
  return registerBackgroundAgentLane(this.core, input);
@@ -231,6 +231,9 @@ export class TaskRegistry {
231
231
  activeDelegationHandles(scope, rootSessionId) {
232
232
  return activeDelegationHandlesLane(this.core, scope, rootSessionId);
233
233
  }
234
+ activeDelegationOccupants(scope, rootSessionId, caller) {
235
+ return activeDelegationOccupantsLane(this.core, scope, rootSessionId, caller);
236
+ }
234
237
  reviveBackgroundAgent(id, access, abort) {
235
238
  return reviveBackgroundAgentLane(this.core, id, access, abort);
236
239
  }
@@ -1033,6 +1036,10 @@ The durable record is still marked running (last update ${new Date(row.updatedAt
1033
1036
  liveTasks(access) {
1034
1037
  return this.rowsUnder(access).filter((t) => t.status === "pending" || t.status === "running" || t.status === "parked");
1035
1038
  }
1039
+ anchoredSession(taskId, access) {
1040
+ const h = this.handles.get(taskId);
1041
+ return h !== undefined && canAccess(h, access) ? (childSessionAnchorOf(h) ?? null) : undefined;
1042
+ }
1036
1043
  rowsUnder(access) {
1037
1044
  const out = [];
1038
1045
  for (const h of this.handles.values()) {
@@ -1047,7 +1054,7 @@ The durable record is still marked running (last update ${new Date(row.updatedAt
1047
1054
  ...((h.type === "background_bash" || h.type === "monitor") && shellRowRetained(h) ? { retained: true } : {}),
1048
1055
  ...(h.description !== undefined ? { description: h.description } : {}),
1049
1056
  ...(h.toolUseId !== undefined ? { toolUseId: h.toolUseId } : {}),
1050
- ...(childSession !== undefined ? { sessionId: childSession } : {}),
1057
+ ...(childSession !== undefined ? { sessionId: childSession.sessionId } : {}),
1051
1058
  createdAt: h.createdAt,
1052
1059
  updatedAt: h.updatedAt,
1053
1060
  });
@@ -10,9 +10,9 @@ import type { NestedUsage } from "./tool-spec.js";
10
10
  /**
11
11
  * `"suspended"` (design/45) is a **non-terminal** outcome: the task hit a durable tool-policy gate
12
12
  * (`ask` with a `CheckpointStore` wired) and persisted a checkpoint instead of finishing — resume it
13
- * with `runner.resume(checkpointToken, outcome)`. v1 contract: it is only safe at the **top-level
14
- * `runTask` boundary**; the orchestrators (cascade/verify/repair-loop) map an unexpected `suspended`
15
- * to `failed` + `errorCode:"unexpected.suspended"` and pass the token up (§11 Q6, hard boundary).
13
+ * with `runner.resume(checkpointToken, outcome)`. A nested orchestrator's boundary turns the pause into a
14
+ * `failed` terminal that carries it (`mapNestedSuspend` in `src/agents/suspend-guard.ts` states which
15
+ * orchestrators do, and the entry that continues the pause).
16
16
  *
17
17
  * `"needs_review"` (design/76 §2.5, dry-run / shadow; design/80 D-B, plan-gate) is also a **non-terminal,
18
18
  * resumable** outcome, but a DISTINCT one: it is the REVIEW-PAUSE terminal a human/judge must clear. Two
@@ -22,8 +22,8 @@ import type { NestedUsage } from "./tool-spec.js";
22
22
  * profile's plan-gate produced a proposed PLAN a human must approve/edit/reject BEFORE any step runs, resumed
23
23
  * with a `plan_review` outcome. Both are DISJOINT from `"suspended"`: that is a PRE-ACTION approval of a TOOL
24
24
  * CALL (resumed with `policy_ask`); these are human REVIEWS (the distinct gate.kind picks the resume outcome).
25
- * Orchestrators that map an unexpected `suspended` should map an unexpected `needs_review` the same
26
- * hard-boundary way (it is, like `suspended`, only safe at the top-level `runTask` boundary).
25
+ * A `needs_review` pause meets the same nested boundary as a `suspended` one (`mapNestedSuspend`: code
26
+ * `unexpected.needs_review`).
27
27
  */
28
28
  /**
29
29
  * Terminal vs waiting. Three words are TERMINAL — the leg is over and nobody is expected to act: `completed`,
@@ -700,7 +700,7 @@ export interface TaskSpec {
700
700
  * (same turn, no checkpoint) — this option is the durable FALLBACK for when no live approver can answer,
701
701
  * not an "always park" mandate. It is the cross-process / long / headless version of the `onAsk` gate.
702
702
  * **opt-in, default-off**: unset → the synchronous `onAsk`-only path (a headless ask then auto-denies).
703
- * Only safe at the top-level `runTask` (orchestrators fail-fast, §11 Q6).
703
+ * A nested orchestrator stops at such a pause and hands it back (`mapNestedSuspend` in `src/agents/suspend-guard.ts` states how it continues).
704
704
  *
705
705
  * **Precedence vs a live `onAsk`:** "live approver" means a FUNCTION-valued `spec.onAsk ?? deps.onAsk`.
706
706
  * With one wired, BOTH plain and SAFETY asks (egress/irreversibility tightens) resolve through it
@@ -79,8 +79,8 @@ export type TerminalCause = {
79
79
  * and the retry budget is spent (nothing ran for them).
80
80
  * - `"model.truncated_output_exhausted"` — the model's answer kept ending on the output cap and the
81
81
  * continue budget is spent (`result` holds the text it reached).
82
- * A NESTED orchestrator that met a durable pause it cannot drive stamps `"unexpected.suspended"` /
83
- * `"unexpected.needs_review"` and carries the pause on {@link nestedPause}.
82
+ * `"unexpected.suspended"` / `"unexpected.needs_review"` — a nested orchestrator stopped at a durable pause and
83
+ * carries it on {@link nestedPause} (`mapNestedSuspend` states which orchestrators, and how the pause continues).
84
84
  */
85
85
  code?: string;
86
86
  /** Human-readable failure text. */
@@ -100,10 +100,10 @@ export type TerminalCause = {
100
100
  detail?: TerminalFailureDetail;
101
101
  /**
102
102
  * The durable pause this failure STANDS IN FOR — set only by the nested hard boundary
103
- * (`mapNestedSuspend`): an orchestrator's nested leg paused on a durable gate, the orchestrator cannot
104
- * drive a resume from the inside, so at ITS boundary the pause is a failure — but the pause's own
105
- * cause travels here verbatim so the top-level caller keeps the recovery capability
106
- * (`nestedPause.token` → `runner.resume`). Absent on every failure the engine itself assembles.
103
+ * (`mapNestedSuspend`, which states which orchestrators map and the entry that continues the pause): an
104
+ * orchestrator's nested leg paused on a durable gate, so at ITS boundary the pause is a failure — but the
105
+ * pause's own cause travels here verbatim so the host keeps the recovery capability (`nestedPause.token`).
106
+ * Absent on every failure the engine itself assembles.
107
107
  */
108
108
  nestedPause?: PausedCause;
109
109
  /**
@@ -38,8 +38,12 @@ export type ToolMountTag = (typeof TOOL_MOUNT_TAGS)[number];
38
38
  import type { AssertAllKeysHandled } from "./ask-origin.js";
39
39
  /** The closed set of specialised approval cards a shell may pre-select from a render hint. The hint is a
40
40
  * PRE-FILTER: the shell owns each card's input schema and validates the call's full args before
41
- * mounting the card (design/388 §2.5 boundary ①). */
42
- export declare const TOOL_APPROVAL_CARDS: readonly ["file-edit", "file-write", "notebook-edit", "shell", "fetch", "skill", "workflow", "plan", "question", "generic"];
41
+ * mounting the card (design/388 §2.5 boundary ①).
42
+ *
43
+ * `computer-access` (the call carries `apps`, the list asked for) and `computer-control` (the call carries nothing the
44
+ * card needs) are the two consent cards of a tool that hands the model the user's screen; a caller or an MCP overlay may
45
+ * declare either. What each grants is per connection: `docs/sdk/04-tools-and-mcp.md` states the lifetime. */
46
+ export declare const TOOL_APPROVAL_CARDS: readonly ["file-edit", "file-write", "notebook-edit", "shell", "fetch", "skill", "workflow", "plan", "question", "generic", "computer-access", "computer-control"];
43
47
  export type ToolApprovalCard = (typeof TOOL_APPROVAL_CARDS)[number];
44
48
  /** Membership in the closed set — the one screen a stored or declared card word passes before it is read. */
45
49
  export declare function isToolApprovalCard(word: unknown): word is ToolApprovalCard;
@@ -1,6 +1,6 @@
1
1
  export const TOOL_FAMILIES = Object.freeze(["shell", "file-read", "file-write", "search", "web", "delegate", "plan", "scaffold", "memory", "protocol", "other"]);
2
2
  export const TOOL_MOUNT_TAGS = Object.freeze(["hands", "backgroundTasks", "workflow", "delegation", "hostInternals", "peerLane", "scheduler", "memory", "scenario", "always", "optional"]);
3
- export const TOOL_APPROVAL_CARDS = Object.freeze(["file-edit", "file-write", "notebook-edit", "shell", "fetch", "skill", "workflow", "plan", "question", "generic"]);
3
+ export const TOOL_APPROVAL_CARDS = Object.freeze(["file-edit", "file-write", "notebook-edit", "shell", "fetch", "skill", "workflow", "plan", "question", "generic", "computer-access", "computer-control"]);
4
4
  export function isToolApprovalCard(word) {
5
5
  return typeof word === "string" && TOOL_APPROVAL_CARDS.includes(word);
6
6
  }
@@ -665,7 +665,8 @@ export type ToolIdentity = Pick<ToolCallRequest, "toolName" | "face">;
665
665
  export type WholeToolRefusal = (tool: ToolIdentity) => boolean;
666
666
  /** The judge of a policy with no whole-tool deny rule. */
667
667
  export declare const REFUSES_NO_WHOLE_TOOL: WholeToolRefusal;
668
- /** The id a whole-tool judge's read carries — no call of the leg, so every rule reader takes a read of its own for it. */
668
+ /** The id a whole-tool judge's read of the session rules carries — no call of the leg, so that reader takes a read of its own
669
+ * for it (the person's rules are read for a request through `PersonPathRows.forRequest`). */
669
670
  export declare const TOOL_TABLE_VIEW_READ = "tool-table-view";
670
671
  /**
671
672
  * The members a policy carries beside `check` — one table for every seat that carries them: {@link wrapToolPolicy} reads
@@ -9,7 +9,7 @@ export declare const ToolRosterRenderHints: Type.TObject<{
9
9
  activity: Type.TOptional<Type.TString>;
10
10
  summaryParams: Type.TOptional<Type.TArray<Type.TString>>;
11
11
  resultCards: Type.TOptional<Type.TArray<Type.TString>>;
12
- approvalCard: Type.TOptional<Type.TUnion<[Type.TLiteral<"file-edit">, Type.TLiteral<"file-write">, Type.TLiteral<"notebook-edit">, Type.TLiteral<"shell">, Type.TLiteral<"fetch">, Type.TLiteral<"skill">, Type.TLiteral<"workflow">, Type.TLiteral<"plan">, Type.TLiteral<"question">, Type.TLiteral<"generic">]>>;
12
+ approvalCard: Type.TOptional<Type.TUnion<[Type.TLiteral<"file-edit">, Type.TLiteral<"file-write">, Type.TLiteral<"notebook-edit">, Type.TLiteral<"shell">, Type.TLiteral<"fetch">, Type.TLiteral<"skill">, Type.TLiteral<"workflow">, Type.TLiteral<"plan">, Type.TLiteral<"question">, Type.TLiteral<"generic">, Type.TLiteral<"computer-access">, Type.TLiteral<"computer-control">]>>;
13
13
  }>;
14
14
  export declare const ToolRosterEntry: Type.TObject<{
15
15
  name: Type.TString;
@@ -85,7 +85,7 @@ export declare const ToolRosterEntry: Type.TObject<{
85
85
  activity: Type.TOptional<Type.TString>;
86
86
  summaryParams: Type.TOptional<Type.TArray<Type.TString>>;
87
87
  resultCards: Type.TOptional<Type.TArray<Type.TString>>;
88
- approvalCard: Type.TOptional<Type.TUnion<[Type.TLiteral<"file-edit">, Type.TLiteral<"file-write">, Type.TLiteral<"notebook-edit">, Type.TLiteral<"shell">, Type.TLiteral<"fetch">, Type.TLiteral<"skill">, Type.TLiteral<"workflow">, Type.TLiteral<"plan">, Type.TLiteral<"question">, Type.TLiteral<"generic">]>>;
88
+ approvalCard: Type.TOptional<Type.TUnion<[Type.TLiteral<"file-edit">, Type.TLiteral<"file-write">, Type.TLiteral<"notebook-edit">, Type.TLiteral<"shell">, Type.TLiteral<"fetch">, Type.TLiteral<"skill">, Type.TLiteral<"workflow">, Type.TLiteral<"plan">, Type.TLiteral<"question">, Type.TLiteral<"generic">, Type.TLiteral<"computer-access">, Type.TLiteral<"computer-control">]>>;
89
89
  }>>;
90
90
  /** The ONE mount condition that fired for this instance. */
91
91
  mountedBy: Type.TUnion<[Type.TLiteral<"hands">, Type.TLiteral<"backgroundTasks">, Type.TLiteral<"workflow">, Type.TLiteral<"delegation">, Type.TLiteral<"hostInternals">, Type.TLiteral<"peerLane">, Type.TLiteral<"scheduler">, Type.TLiteral<"memory">, Type.TLiteral<"scenario">, Type.TLiteral<"always">, Type.TLiteral<"optional">]>;
@@ -170,7 +170,7 @@ export declare const ToolRoster: Type.TObject<{
170
170
  activity: Type.TOptional<Type.TString>;
171
171
  summaryParams: Type.TOptional<Type.TArray<Type.TString>>;
172
172
  resultCards: Type.TOptional<Type.TArray<Type.TString>>;
173
- approvalCard: Type.TOptional<Type.TUnion<[Type.TLiteral<"file-edit">, Type.TLiteral<"file-write">, Type.TLiteral<"notebook-edit">, Type.TLiteral<"shell">, Type.TLiteral<"fetch">, Type.TLiteral<"skill">, Type.TLiteral<"workflow">, Type.TLiteral<"plan">, Type.TLiteral<"question">, Type.TLiteral<"generic">]>>;
173
+ approvalCard: Type.TOptional<Type.TUnion<[Type.TLiteral<"file-edit">, Type.TLiteral<"file-write">, Type.TLiteral<"notebook-edit">, Type.TLiteral<"shell">, Type.TLiteral<"fetch">, Type.TLiteral<"skill">, Type.TLiteral<"workflow">, Type.TLiteral<"plan">, Type.TLiteral<"question">, Type.TLiteral<"generic">, Type.TLiteral<"computer-access">, Type.TLiteral<"computer-control">]>>;
174
174
  }>>;
175
175
  /** The ONE mount condition that fired for this instance. */
176
176
  mountedBy: Type.TUnion<[Type.TLiteral<"hands">, Type.TLiteral<"backgroundTasks">, Type.TLiteral<"workflow">, Type.TLiteral<"delegation">, Type.TLiteral<"hostInternals">, Type.TLiteral<"peerLane">, Type.TLiteral<"scheduler">, Type.TLiteral<"memory">, Type.TLiteral<"scenario">, Type.TLiteral<"always">, Type.TLiteral<"optional">]>;
@@ -263,7 +263,7 @@ export declare const ToolRosterDelta: Type.TObject<{
263
263
  activity: Type.TOptional<Type.TString>;
264
264
  summaryParams: Type.TOptional<Type.TArray<Type.TString>>;
265
265
  resultCards: Type.TOptional<Type.TArray<Type.TString>>;
266
- approvalCard: Type.TOptional<Type.TUnion<[Type.TLiteral<"file-edit">, Type.TLiteral<"file-write">, Type.TLiteral<"notebook-edit">, Type.TLiteral<"shell">, Type.TLiteral<"fetch">, Type.TLiteral<"skill">, Type.TLiteral<"workflow">, Type.TLiteral<"plan">, Type.TLiteral<"question">, Type.TLiteral<"generic">]>>;
266
+ approvalCard: Type.TOptional<Type.TUnion<[Type.TLiteral<"file-edit">, Type.TLiteral<"file-write">, Type.TLiteral<"notebook-edit">, Type.TLiteral<"shell">, Type.TLiteral<"fetch">, Type.TLiteral<"skill">, Type.TLiteral<"workflow">, Type.TLiteral<"plan">, Type.TLiteral<"question">, Type.TLiteral<"generic">, Type.TLiteral<"computer-access">, Type.TLiteral<"computer-control">]>>;
267
267
  }>>;
268
268
  /** The ONE mount condition that fired for this instance. */
269
269
  mountedBy: Type.TUnion<[Type.TLiteral<"hands">, Type.TLiteral<"backgroundTasks">, Type.TLiteral<"workflow">, Type.TLiteral<"delegation">, Type.TLiteral<"hostInternals">, Type.TLiteral<"peerLane">, Type.TLiteral<"scheduler">, Type.TLiteral<"memory">, Type.TLiteral<"scenario">, Type.TLiteral<"always">, Type.TLiteral<"optional">]>;
@@ -700,6 +700,10 @@ export interface ToolExecuteContext {
700
700
  * fixed point `ctx.rootSessionId ?? ctx.sessionId` at every spawn). Absent for a top-level run
701
701
  * (its OWN sessionId is the root). */
702
702
  rootSessionId?: string;
703
+ /** The run's delegation tree owner seat (`RunInternals.delegationOwner`, Runner-filled): a delegation tool reads the tree's owner
704
+ * through it for the rows it creates for a child (a placed transcript, a fork, a park's durable row) and threads it into a spawned
705
+ * child's internals by reference — never into a revival's. */
706
+ delegationOwner?: import("./runner/delegation-owner.js").DelegationOwnerSeat;
703
707
  /** design/380 O1② (C12) — the spawning run's EXPLICIT placement fixed point
704
708
  * (`RunInternals.placementRoot`), present only when its internals carried one (cascade rungs /
705
709
  * verification legs after the first, or a caller-declared root). A delegation tool threads it
@@ -31,5 +31,5 @@ export type { BackgroundChildEvent, BackgroundChildRow, DelegationLifecycleEvent
31
31
  export { __resetMalformedDelegationSeatAnnouncement, backgroundChildTerminal, deliverDelegationLifecycle, emitsChildRowFrames, taskStartedFrame } from "./delegation-frames.js";
32
32
  export type { ProjectMemoryLoad, ResumePreflightInfo, ResumePreflightVerdict, RunnerDeps } from "./runner-deps.js";
33
33
  export type { ApprovalCarryRefusal, EngineNotice, HeldUserInputs, OwedInputIds, OwedUserInputAccount, UserInputUndrainedCause } from "./engine-notice.js";
34
- export { __resetMalformedNoticeSeatAnnouncement, deliverEngineNotice, owedUserInputCounts, owedUserInputIds, parentLegIds, parkedInputIdsOf, settleOwedUserInput, undrainedUserInputNotices, USER_INPUT_UNDRAINED_CAUSES, USER_INPUT_UNDRAINED_FAMILIES } from "./engine-notice.js";
34
+ export { __resetMalformedNoticeSeatAnnouncement, deliverEngineNotice, owedUserInputCounts, owedUserInputIds, parentLegIds, parkedInputIdsOf, setDefaultEngineNoticeSeat, settleOwedUserInput, undrainedUserInputNotices, USER_INPUT_UNDRAINED_CAUSES, USER_INPUT_UNDRAINED_FAMILIES } from "./engine-notice.js";
35
35
  export type { AgentTool, Model, StreamFn, ThinkingLevel, ToolInputValidationContext, ToolInputVerdict };
@@ -2,4 +2,4 @@ export { MODEL_ROLES } from "./model-seat.js";
2
2
  export { DECLARATION_ENTRY_WORDS, DECLARATION_PATH_RULES, MCP_TRANSPORT_KINDS, NO_DECLARATION_PATH_RULES, TOOL_AXIS_WORDS, callerText, dataKind, declarationFaultOf, declarationPath, declarerWord, perToolEmptyName, perToolEntryRefusal, readMcpToolAxes, readToolAxes, receiveDeclaration, receivePerToolDeclaration, toolAxesRefusal, transportKindOf } from "./mcp-server-spec.js";
3
3
  export { AUTO_MODE_DENY_SOURCES, isAutoModeDenySource } from "./runtime-caps.js";
4
4
  export { __resetMalformedDelegationSeatAnnouncement, backgroundChildTerminal, deliverDelegationLifecycle, emitsChildRowFrames, taskStartedFrame } from "./delegation-frames.js";
5
- export { __resetMalformedNoticeSeatAnnouncement, deliverEngineNotice, owedUserInputCounts, owedUserInputIds, parentLegIds, parkedInputIdsOf, settleOwedUserInput, undrainedUserInputNotices, USER_INPUT_UNDRAINED_CAUSES, USER_INPUT_UNDRAINED_FAMILIES } from "./engine-notice.js";
5
+ export { __resetMalformedNoticeSeatAnnouncement, deliverEngineNotice, owedUserInputCounts, owedUserInputIds, parentLegIds, parkedInputIdsOf, setDefaultEngineNoticeSeat, settleOwedUserInput, undrainedUserInputNotices, USER_INPUT_UNDRAINED_CAUSES, USER_INPUT_UNDRAINED_FAMILIES } from "./engine-notice.js";
@@ -96,6 +96,9 @@ export declare class NodeExecutionEnv implements ExecutionEnv, BackgroundShellCa
96
96
  /** `ExecutionEnv.cdPath` = the `CDPATH` the shell child receives, read LIVE off the same merge each exec gets (never the
97
97
  * engine process's own environment): its entries, `[]` when the child gets none. Residual: a per-exec `env.CDPATH`. */
98
98
  get cdPath(): readonly string[];
99
+ /** `ExecutionEnv.receivedEnvNames` = the names of the same merge each exec gets, read LIVE; `[]` when no child would be spawned
100
+ * at all. Residual: a per-exec `env` adding one. */
101
+ get receivedEnvNames(): readonly string[];
99
102
  /** `ExecutionEnv.withheldEnv` = what the same merge withholds from the shell child (an entry `shellEnv` re-supplies is
100
103
  * no loss), read LIVE; `[]` when no child would be spawned at all. Residual: a per-exec `env` re-supplying one. */
101
104
  get withheldEnv(): readonly SecretEnvFinding[];
@@ -1,5 +1,5 @@
1
1
  import { spawn, spawnSync } from "node:child_process";
2
- import { randomUUID } from "node:crypto";
2
+ import { createHash, randomUUID } from "node:crypto";
3
3
  import { closeSync, constants, createReadStream, mkdtempSync, openSync, readSync, rmSync, statSync, truncateSync, unlinkSync } from "node:fs";
4
4
  import { access, appendFile, lstat, mkdir, mkdtemp, open, readdir, readFile, readlink, rename, rm, stat, unlink, writeFile, } from "node:fs/promises";
5
5
  import { tmpdir } from "node:os";
@@ -196,25 +196,29 @@ function isFsSupportError(error) {
196
196
  }
197
197
  const RENAME_FALLBACK_CODES = new Set(["EXDEV", "EPERM", "EEXIST", "EBUSY"]);
198
198
  const NAME_MAX_BYTES = 255;
199
+ const STAGING_NAME_DIGEST_HEX = 12;
200
+ const STAGING_CUT_AT_BYTES = NAME_MAX_BYTES - 3;
199
201
  const STAGING_SUFFIX = /\.tmp\.(\d+)\.[0-9a-f]{12}$/;
200
202
  function stagingSuffix(pid) {
201
203
  return `.tmp.${pid}.${randomUUID().replace(/-/g, "").slice(0, 12)}`;
202
204
  }
203
205
  function stagingNameOf(name, suffix) {
204
206
  const nameBytes = Buffer.byteLength(name, "utf8");
205
- const room = NAME_MAX_BYTES - Buffer.byteLength(suffix, "utf8");
206
- if (nameBytes <= room || nameBytes > NAME_MAX_BYTES)
207
+ const suffixBytes = Buffer.byteLength(suffix, "utf8");
208
+ if (nameBytes + suffixBytes < STAGING_CUT_AT_BYTES || nameBytes > NAME_MAX_BYTES)
207
209
  return `${name}${suffix}`;
210
+ const mark = `~${createHash("sha256").update(name, "utf8").digest("hex").slice(0, STAGING_NAME_DIGEST_HEX)}`;
211
+ const keep = NAME_MAX_BYTES - suffixBytes - Buffer.byteLength(mark, "utf8");
208
212
  let kept = "";
209
213
  let used = 0;
210
214
  for (const char of name) {
211
215
  const bytes = Buffer.byteLength(char, "utf8");
212
- if (used + bytes > room)
216
+ if (used + bytes > keep)
213
217
  break;
214
218
  kept += char;
215
219
  used += bytes;
216
220
  }
217
- return `${kept}${suffix}`;
221
+ return `${kept}${mark}${suffix}`;
218
222
  }
219
223
  function stagingSiblingOf(target) {
220
224
  const suffix = stagingSuffix(process.pid);
@@ -473,6 +477,9 @@ export class NodeExecutionEnv {
473
477
  const value = this.childEnvForRead()?.CDPATH;
474
478
  return value === undefined || value === "" ? [] : value.split(":");
475
479
  }
480
+ get receivedEnvNames() {
481
+ return Object.entries(this.childEnvForRead() ?? {}).flatMap(([name, value]) => (value === undefined ? [] : [name]));
482
+ }
476
483
  get withheldEnv() {
477
484
  let withheld = [];
478
485
  this.childEnvForRead((f) => (withheld = f));
@@ -667,6 +667,8 @@ export interface ExecutionEnv extends FileSystem, Shell {
667
667
  * re-supply — names and rules, never a value. `[]` = none withheld, or none inherited (a shell environment built
668
668
  * rather than inherited from this process); `"unknown"` = the adapter cannot say. A read: it announces nothing. */
669
669
  readonly withheldEnv: readonly SecretEnvFinding[] | "unknown";
670
+ /** #1726 — the NAMES (never a value) of the environment the shell child receives; omitted ⇒ the adapter cannot say, every name may be there. */
671
+ readonly receivedEnvNames?: readonly string[];
670
672
  }
671
673
  /** Base fields shared by append-only session tree entries. */
672
674
  export interface SessionTreeEntryBase {
@@ -1096,6 +1098,11 @@ export interface SessionWriteOptions {
1096
1098
  */
1097
1099
  expectedLeafId?: string | null;
1098
1100
  }
1101
+ /** What the replay that loaded a stored log dropped: `dropped` of its `total` records could not be read and are not in the log. */
1102
+ export interface ReplayLoss {
1103
+ readonly dropped: number;
1104
+ readonly total: number;
1105
+ }
1099
1106
  export interface SessionStorage<TMetadata extends SessionMetadata = SessionMetadata> {
1100
1107
  getMetadata(): Promise<TMetadata>;
1101
1108
  getLeafId(): Promise<string | null>;
@@ -1127,6 +1134,10 @@ export interface SessionStorage<TMetadata extends SessionMetadata = SessionMetad
1127
1134
  * from a CORRUPT log (a head whose parent is simply missing); the two look identical byte-wise and
1128
1135
  * must not be treated alike. `BaseSessionStorage` implements it for the bundled backends. */
1129
1136
  getFloorId?(): string | null;
1137
+ /** What the replay that loaded this log dropped, or `undefined` when it dropped nothing (or the backend has no replay to lose from). A run
1138
+ * that continues the session tells the person when it is there. Fixed at the load: a later write does not change it.
1139
+ * `BaseSessionStorage` implements it for the bundled backends. */
1140
+ getReplayLoss?(): ReplayLoss | undefined;
1130
1141
  getEpochAnchor?(): Promise<unknown>;
1131
1142
  }
1132
1143
  /**
@@ -1,11 +1,11 @@
1
1
  /**
2
2
  * The memory of one walk up a session log's parent chain, shared by `getPathToRoot`, the resume-at ancestry scan and the fork-point judge `settledForkOptions` (the import validator still keeps its own loop — #2253). An entry the
3
- * walk stands on twice means the parent links loop, which no ancestry can contain: the walk is refused
4
- * `invalid_session` naming that entry instead of being followed again, and saying what a person can do (start a new session, or fork from an entry the
3
+ * walk stands on twice means the parent links loop, which no ancestry can contain: the stored log does not hold together, so the walk is refused
4
+ * `corrupt_session` naming that entry instead of being followed again, and saying what a person can do (start a new session, or fork from an entry the
5
5
  * loop does not touch). One guard per walk.
6
6
  */
7
7
  export declare class ParentChainGuard {
8
8
  private readonly stepped;
9
- /** Records that the walk now stands on `id`; throws `invalid_session` when it already stood there. */
9
+ /** Records that the walk now stands on `id`; throws `corrupt_session` when it already stood there. */
10
10
  stepOnto(id: string): void;
11
11
  }
@@ -3,7 +3,7 @@ export class ParentChainGuard {
3
3
  stepped = new Set();
4
4
  stepOnto(id) {
5
5
  if (this.stepped.has(id)) {
6
- throw new SessionError("invalid_session", `Entry ${id} is its own ancestor (parent chain cycles at ${id}) — start a new session, or fork from an entry above the loop`);
6
+ throw new SessionError("corrupt_session", `Entry ${id} is its own ancestor (parent chain cycles at ${id}) — start a new session, or fork from an entry above the loop`);
7
7
  }
8
8
  this.stepped.add(id);
9
9
  }