@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
@@ -1,18 +1,23 @@
1
1
  import type { PausedCause, TaskResult, TerminalCause } from "../core/types.js";
2
2
  /**
3
- * design/45 §11 Q6 — the **durable-suspend hard boundary** (v1). A `paused` terminal is only safe to
4
- * handle at the **top-level `runTask`** boundary: the orchestrators (cascade / verify / repair-loop)
5
- * run their work as *nested* `runTask`s, and none of them can drive a resume from the inside. If a nested
6
- * task pauses on a durable gate, the orchestrator must **fail fast** — not silently treat it as an
7
- * ordinary failure (which would escalate/re-run side effects) and not release its pinned session (which
8
- * would orphan the checkpoint). It maps `paused → failed` with the code `"unexpected.suspended"` (an
9
- * approval / resource pause) or `"unexpected.needs_review"` (a review pause) and **carries the pause's own
10
- * cause on the failed terminal's `nestedPause` seat** so the top-level caller can still resume.
3
+ * The **nested durable-pause boundary** — the one place that says which orchestrators map a pause they meet and how a host
4
+ * continues it; the other places that mention it point here.
11
5
  *
12
- * The structural prevention is upstream — an orchestrator should run nested tasks under a **non-durable**
13
- * approval policy (e.g. the verifier already forces `handsReadOnly` + headless auto-deny, DESIGN#5) so a
14
- * suspension can't arise. This mapping is the defense-in-depth the council made a must-fix: "write it as
15
- * a hard boundary, or a deployment wires durable-suspend into verify and produces silent errors."
6
+ * An orchestrator that runs its work as *nested* `runTask`s cannot answer a durable gate (an approval, a resource slice, a platform
7
+ * park, a dry-run or plan review) from the inside. The cascade (`runCascade` / `resumeCascade`) and the verification gate
8
+ * (`runWithVerification` / `resumeWithVerification`) therefore **stop** at such a pause — no escalation or re-run (side effects), and
9
+ * no release of the pinned session (the checkpoint still references it) — and hand it back through {@link mapNestedSuspend}: a
10
+ * `failed` terminal with the code `"unexpected.suspended"` (an approval / resource / platform pause) or `"unexpected.needs_review"`
11
+ * (a review pause), **the pause's own cause on the failed terminal's `nestedPause` seat**, and a sentence that names the entry that
12
+ * continues it. That entry is the orchestrator's own: `resumeCascade` for a cascade, `resumeWithVerification` for a verification
13
+ * gate. Once the pause is decided, the host calls it with `nestedPause.token` and the decision.
14
+ *
15
+ * The other orchestrators do not map: the repair loop hands the paused terminal back as is, a workflow parks the run, and a
16
+ * subagent reports `suspended.awaiting_approval`.
17
+ *
18
+ * The structural prevention is upstream — an orchestrator should run nested tasks under a **non-durable** approval policy (e.g. the
19
+ * verifier already forces `handsReadOnly` + headless auto-deny) so a suspension cannot arise. This mapping is the defense-in-depth:
20
+ * a deployment that wires durable suspend into a nested orchestrator gets a surfaced pause, not silent errors.
16
21
  */
17
22
  export declare const UNEXPECTED_SUSPENDED = "unexpected.suspended";
18
23
  /** design/80 D-B: the review durable-pause family (dry-run `needs_review` AND `plan_review`) hits the SAME
@@ -22,9 +27,9 @@ export declare const UNEXPECTED_NEEDS_REVIEW = "unexpected.needs_review";
22
27
  /**
23
28
  * design/80 D-B: the durable-pause hard boundary covers EVERY `paused` cause — an approval gate, a resource
24
29
  * slice, a dry-run review, a `plan_review` plan-gate. All of them persist a checkpoint + PIN their session,
25
- * and a nested orchestrator can't drive their resume — so it must surface the pause and NOT release the
26
- * pinned session (releasing it orphans the checkpoint). A type guard, so the caller reads the token/gate
27
- * off the narrowed cause.
30
+ * and the decision that resumes them comes from outside the orchestrator — so it must surface the pause and
31
+ * NOT release the pinned session (releasing it orphans the checkpoint). A type guard, so the caller reads the
32
+ * token/gate off the narrowed cause.
28
33
  */
29
34
  export declare function isDurablePause(terminal: TerminalCause): terminal is PausedCause;
30
35
  /** A result whose terminal is known to be a pause — what {@link isDurablePause} narrows a result's
@@ -43,13 +48,30 @@ export declare function resumeNeverStarted(result: TaskResult): boolean;
43
48
  * status word is projected from; read here by the orchestrators that name the family in their own faces.
44
49
  */
45
50
  export declare function pauseFamily(t: PausedCause): "suspended" | "needs_review";
51
+ /**
52
+ * The entry that continues what {@link mapNestedSuspend} hands back, as the orchestrator that calls it names it. The entry is the
53
+ * caller's to give — the mint does not look at who is calling — and a union, so a new mapper has to name its own to compile.
54
+ */
55
+ export interface NestedResumeEntry {
56
+ /** The orchestrator's resume entry, by its exported name. */
57
+ readonly door: "resumeCascade" | "resumeWithVerification";
58
+ /**
59
+ * Only for an entry that takes the parked leg: where the host gets it. `"card"` — the parked card records it
60
+ * (`CheckpointState.compositionLeg`); `"caller"` — the leg was dispatched with none (the task spec named no session and no leg was
61
+ * handed in), so the card records none and the host supplies the leg itself. Absent — the entry takes no leg.
62
+ */
63
+ readonly legFrom?: "card" | "caller";
64
+ }
46
65
  /**
47
66
  * If `result` durably paused, return it mapped to a `failed` result whose terminal carries the pause on
48
67
  * `nestedPause`; otherwise return it unchanged. The orchestrator should also **stop** (not escalate/re-run)
49
68
  * and **not release** the session when this maps a pause — the checkpoint still references that session.
50
69
  *
70
+ * `resume` names the entry that continues the pause; the sentence of the failed terminal is one template with that entry (and, for
71
+ * an entry that takes the parked leg, where the host gets the leg) as its slots.
72
+ *
51
73
  * The mapped result keeps the parked leg's `sessionId` — the parked row's own `Checkpoint.sessionId`. A composition's legs do
52
74
  * not run in the caller's session, so a host links the row to its run by the row's `CheckpointState.compositionLeg`, never by
53
75
  * assuming the row sits in the session it submitted.
54
76
  */
55
- export declare function mapNestedSuspend(result: TaskResult): TaskResult;
77
+ export declare function mapNestedSuspend(result: TaskResult, resume: NestedResumeEntry): TaskResult;
@@ -11,16 +11,21 @@ export function resumeNeverStarted(result) {
11
11
  export function pauseFamily(t) {
12
12
  return PAUSE_REGISTRY[t.gate.kind].taskStatus;
13
13
  }
14
- export function mapNestedSuspend(result) {
14
+ const LEG_CLAUSE = {
15
+ card: ", and the leg its parked card records (CheckpointState.compositionLeg)",
16
+ caller: ", and the parked leg — this run's card records none because the task spec named no session, so you supply it yourself",
17
+ };
18
+ export function mapNestedSuspend(result, resume) {
15
19
  const t = result.terminal;
16
20
  if (!isDurablePause(t)) {
17
21
  return result;
18
22
  }
19
23
  const word = pauseFamily(t);
20
24
  const code = word === "needs_review" ? UNEXPECTED_NEEDS_REVIEW : UNEXPECTED_SUSPENDED;
21
- const message = `a nested task durably paused ("${word}") on a HITL gate; durable suspend/resume and plan/` +
22
- "dry-run review are only supported at the top-level runTask (design/45 v1 / design/80). Resume it via " +
23
- "the pause's token, or run the orchestrated task under a non-durable policy so it auto-adjudicates instead of pausing.";
25
+ const legClause = resume.legFrom === undefined ? "" : LEG_CLAUSE[resume.legFrom];
26
+ const message = `a nested task durably paused ("${word}") on a HITL gate and the orchestrator stopped there, keeping the parked leg's session: ` +
27
+ `once the pause is decided, continue it with ${resume.door}, handing it this pause's token (nestedPause.token) and the decision${legClause}; ` +
28
+ "or run the orchestrated task under a non-durable policy so it auto-adjudicates instead of pausing.";
24
29
  return {
25
30
  ...result,
26
31
  terminal: { kind: "failed", code, message, nestedPause: t },
@@ -91,6 +91,7 @@ function withLegIdentity(internals, leg, caller) {
91
91
  return { ...internals, onWiringManifest: (manifest) => (caller ?? internals).onWiringManifest?.(manifest, identity) };
92
92
  }
93
93
  const IMPL_LEG = { kind: "impl", round: 0 };
94
+ const GATE_RESUME_ENTRY = { door: "resumeWithVerification" };
94
95
  function fixObjective(findings) {
95
96
  const list = findings.length
96
97
  ? findings.map((f) => `- ${sanitizeUntrustedText(f)}`).join("\n")
@@ -279,7 +280,7 @@ async function verifyCompletedPlaced(runner, result, specBase, objective, config
279
280
  spend += (current.stats.costMicroUsd ?? 0) + (current.stats.nested?.costMicroUsd ?? 0);
280
281
  implAccount.add(current.stats);
281
282
  if (isDurablePause(current.terminal)) {
282
- return { ...mapNestedSuspend(carryFrozenPosture(withImplAccount(current))), verification: outcome };
283
+ return { ...mapNestedSuspend(carryFrozenPosture(withImplAccount(current)), GATE_RESUME_ENTRY), verification: outcome };
283
284
  }
284
285
  if (current.terminal.kind !== "completed")
285
286
  break;
@@ -291,7 +292,7 @@ export async function runWithVerification(runner, implSpec, config = {}, interna
291
292
  const placement = compositionPlacement(internals);
292
293
  const result = await runner.runTask(implSpec, withLegIdentity(placement.firstLeg, IMPL_LEG, internals));
293
294
  if (isDurablePause(result.terminal)) {
294
- return { ...mapNestedSuspend(result), verification: { verdict: "unverified", unverifiedReason: pauseFamily(result.terminal), rounds: 0, findings: [] } };
295
+ return { ...mapNestedSuspend(result, GATE_RESUME_ENTRY), verification: { verdict: "unverified", unverifiedReason: pauseFamily(result.terminal), rounds: 0, findings: [] } };
295
296
  }
296
297
  refuseUnhonorableInternals(internals, "before_leg");
297
298
  return verifyCompletedPlaced(runner, result, implSpec, implSpec.objective, config, internals, placement);
@@ -301,7 +302,7 @@ export async function resumeWithVerification(runner, token, outcome, taskConfig,
301
302
  const placement = compositionPlacement(internals);
302
303
  const result = await runner.resume(token, outcome, taskConfig, withLegIdentity(placement.firstLeg, IMPL_LEG, internals));
303
304
  if (isDurablePause(result.terminal)) {
304
- return { ...mapNestedSuspend(result), verification: { verdict: "unverified", unverifiedReason: pauseFamily(result.terminal), rounds: 0, findings: [] } };
305
+ return { ...mapNestedSuspend(result, GATE_RESUME_ENTRY), verification: { verdict: "unverified", unverifiedReason: pauseFamily(result.terminal), rounds: 0, findings: [] } };
305
306
  }
306
307
  refuseUnhonorableInternals(internals, "before_leg");
307
308
  return verifyCompletedPlaced(runner, result, taskConfig, objective, config, internals, placement);