@sema-agent/core 7.64.0 → 7.66.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 (192) hide show
  1. package/CHANGELOG.md +571 -0
  2. package/dist/agents/delegation-registry-seat.d.ts +15 -0
  3. package/dist/agents/delegation-registry-seat.js +13 -0
  4. package/dist/agents/org-delivery-gate.d.ts +8 -1
  5. package/dist/agents/org-delivery-gate.js +9 -3
  6. package/dist/agents/peer-held-queue.js +1 -1
  7. package/dist/agents/peer-idle.js +1 -1
  8. package/dist/agents/peer-session-drain.d.ts +51 -12
  9. package/dist/agents/peer-session-drain.js +47 -34
  10. package/dist/agents/read-inbox-tool.d.ts +6 -2
  11. package/dist/agents/read-inbox-tool.js +18 -5
  12. package/dist/agents/subagent.d.ts +3 -1
  13. package/dist/agents/subagent.js +84 -77
  14. package/dist/brain/reasoning.d.ts +2 -0
  15. package/dist/brain/reasoning.js +1 -0
  16. package/dist/core/allow-entry.d.ts +9 -0
  17. package/dist/core/allow-entry.js +7 -1
  18. package/dist/core/ask-origin.d.ts +23 -3
  19. package/dist/core/ask-origin.js +11 -1
  20. package/dist/core/auto-promote.d.ts +3 -2
  21. package/dist/core/background-agent-store.d.ts +7 -0
  22. package/dist/core/checkpoint-store.d.ts +2 -3
  23. package/dist/core/context-settings.d.ts +1 -2
  24. package/dist/core/context-settings.js +1 -1
  25. package/dist/core/engine-attestation.d.ts +2 -2
  26. package/dist/core/engine-notice.d.ts +13 -1
  27. package/dist/core/engine-notice.js +3 -1
  28. package/dist/core/file-history-store.d.ts +2 -2
  29. package/dist/core/file-history-store.js +0 -4
  30. package/dist/core/gate-fold.js +3 -1
  31. package/dist/core/governance-codes.d.ts +6 -4
  32. package/dist/core/governance-codes.js +5 -3
  33. package/dist/core/human-input-projection.d.ts +9 -0
  34. package/dist/core/human-input-projection.js +13 -0
  35. package/dist/core/input-author.d.ts +66 -6
  36. package/dist/core/input-author.js +21 -3
  37. package/dist/core/leg-identity.d.ts +18 -2
  38. package/dist/core/leg-identity.js +5 -7
  39. package/dist/core/mailbox-store.d.ts +1 -1
  40. package/dist/core/memory-engine/consolidation.d.ts +30 -10
  41. package/dist/core/memory-engine/consolidation.js +41 -6
  42. package/dist/core/memory-engine/control-objects.d.ts +36 -3
  43. package/dist/core/memory-engine/control-objects.js +134 -12
  44. package/dist/core/memory-engine/control-plane-adoption.d.ts +13 -9
  45. package/dist/core/memory-engine/control-plane-adoption.js +58 -31
  46. package/dist/core/memory-engine/delegation-settlement.d.ts +75 -52
  47. package/dist/core/memory-engine/delegation-settlement.js +211 -228
  48. package/dist/core/memory-engine/dual-root.d.ts +3 -2
  49. package/dist/core/memory-engine/dual-root.js +5 -1
  50. package/dist/core/memory-engine/engine.d.ts +33 -16
  51. package/dist/core/memory-engine/engine.js +213 -177
  52. package/dist/core/memory-engine/file-backend.d.ts +21 -12
  53. package/dist/core/memory-engine/file-backend.js +58 -104
  54. package/dist/core/memory-engine/index.d.ts +2 -2
  55. package/dist/core/memory-engine/index.js +2 -2
  56. package/dist/core/memory-engine/layout.d.ts +184 -83
  57. package/dist/core/memory-engine/layout.js +267 -172
  58. package/dist/core/memory-engine/memory-age.d.ts +12 -0
  59. package/dist/core/memory-engine/memory-age.js +17 -0
  60. package/dist/core/memory-engine/memory-backend-contract.js +12 -11
  61. package/dist/core/memory-engine/memory-deployment.d.ts +4 -3
  62. package/dist/core/memory-engine/memory-deployment.js +6 -3
  63. package/dist/core/memory-engine/origin-clearance.d.ts +43 -15
  64. package/dist/core/memory-engine/origin-clearance.js +142 -58
  65. package/dist/core/memory-engine/tools.d.ts +2 -2
  66. package/dist/core/memory-engine/tools.js +7 -7
  67. package/dist/core/memory-engine/types.d.ts +16 -10
  68. package/dist/core/memory-vector.d.ts +6 -14
  69. package/dist/core/memory.d.ts +0 -462
  70. package/dist/core/memory.js +0 -333
  71. package/dist/core/model-receipt.d.ts +2 -1
  72. package/dist/core/model-receipt.js +5 -0
  73. package/dist/core/mods/dollar.d.ts +12 -0
  74. package/dist/core/mods/kernel/dispatch.d.ts +3 -1
  75. package/dist/core/mods/kernel/dispatch.js +5 -2
  76. package/dist/core/mods/kernel/events.d.ts +3 -1
  77. package/dist/core/mods/kernel/events.js +2 -2
  78. package/dist/core/mods/prompt-submit.d.ts +4 -0
  79. package/dist/core/mods/prompt-submit.js +24 -0
  80. package/dist/core/mods/stations.d.ts +23 -4
  81. package/dist/core/mods/stations.js +14 -7
  82. package/dist/core/permission-rule-consent.d.ts +49 -18
  83. package/dist/core/permission-rule-consent.js +59 -38
  84. package/dist/core/permission-rule-store.d.ts +24 -14
  85. package/dist/core/retention.d.ts +2 -7
  86. package/dist/core/retention.js +0 -1
  87. package/dist/core/retired-host-table-account.d.ts +19 -0
  88. package/dist/core/retired-host-table-account.js +28 -0
  89. package/dist/core/retired-tool-name-account.d.ts +60 -0
  90. package/dist/core/retired-tool-name-account.js +32 -0
  91. package/dist/core/roles.d.ts +3 -1
  92. package/dist/core/roles.js +5 -2
  93. package/dist/core/runner/classifier-ladder.d.ts +3 -1
  94. package/dist/core/runner/classifier-ladder.js +2 -2
  95. package/dist/core/runner/compact-session.js +2 -1
  96. package/dist/core/runner/contracts.d.ts +9 -9
  97. package/dist/core/runner/delegation-owner.d.ts +0 -8
  98. package/dist/core/runner/delegation-owner.js +1 -3
  99. package/dist/core/runner/gate-exit.js +9 -2
  100. package/dist/core/runner/memory-consolidation-driver.js +2 -2
  101. package/dist/core/runner/prepare-config-doors.js +1 -1
  102. package/dist/core/runner/prepare-delegation-surface.d.ts +1 -1
  103. package/dist/core/runner/prepare-delegation-surface.js +5 -3
  104. package/dist/core/runner/prepare-gate-stations.d.ts +8 -5
  105. package/dist/core/runner/prepare-gate-stations.js +13 -5
  106. package/dist/core/runner/prepare-inherited-gate.js +2 -0
  107. package/dist/core/runner/prepare-memory-engine-session.js +1 -1
  108. package/dist/core/runner/prepare-memory.js +35 -14
  109. package/dist/core/runner/prepare-policy-chain.js +12 -3
  110. package/dist/core/runner/prepare-project-context.js +2 -2
  111. package/dist/core/runner/prepare-task.d.ts +9 -1
  112. package/dist/core/runner/prepare-task.js +6 -5
  113. package/dist/core/runner/prepare-wiring-manifest.js +5 -4
  114. package/dist/core/runner/prompt-suggestions.js +1 -1
  115. package/dist/core/runner/run-identity-wiring.js +2 -2
  116. package/dist/core/runner/run-leg.js +3 -3
  117. package/dist/core/runner/run-notification-lane.d.ts +3 -0
  118. package/dist/core/runner/run-notification-lane.js +2 -2
  119. package/dist/core/runner/runtask.js +6 -3
  120. package/dist/core/runner/steer-admission.d.ts +11 -2
  121. package/dist/core/runner/stream-steer-verb.d.ts +5 -2
  122. package/dist/core/runner/stream-steer-verb.js +67 -14
  123. package/dist/core/runner/sub-agent-deny-lists.d.ts +8 -8
  124. package/dist/core/runner/sub-agent-deny-lists.js +22 -8
  125. package/dist/core/runner-deps.d.ts +4 -4
  126. package/dist/core/secret-env.d.ts +2 -2
  127. package/dist/core/secret-env.js +6 -20
  128. package/dist/core/session-store.d.ts +6 -6
  129. package/dist/core/session-store.js +3 -3
  130. package/dist/core/shell-run-candidates.js +3 -3
  131. package/dist/core/side-query.js +1 -1
  132. package/dist/core/skill-grant.d.ts +7 -0
  133. package/dist/core/skill-grant.js +14 -5
  134. package/dist/core/store-contracts/background-agent-store-contract.js +13 -0
  135. package/dist/core/task-event.d.ts +14 -0
  136. package/dist/core/task-notification.d.ts +35 -8
  137. package/dist/core/task-notification.js +31 -13
  138. package/dist/core/task-registry-agent.js +1 -0
  139. package/dist/core/task-registry-shared.d.ts +4 -0
  140. package/dist/core/tool-errors.d.ts +3 -3
  141. package/dist/core/tool-policy.js +2 -3
  142. package/dist/core/tool-spec.d.ts +20 -10
  143. package/dist/core/user-attachment.d.ts +5 -1
  144. package/dist/core/user-attachment.js +11 -5
  145. package/dist/core/write-protect.d.ts +16 -0
  146. package/dist/core/write-protect.js +10 -0
  147. package/dist/engine/harness/agent-harness.d.ts +19 -11
  148. package/dist/engine/harness/agent-harness.js +7 -4
  149. package/dist/engine/llm/types.d.ts +22 -10
  150. package/dist/engine/session/repo-utils.d.ts +14 -4
  151. package/dist/engine/session/repo-utils.js +5 -4
  152. package/dist/index.d.ts +10 -8
  153. package/dist/index.js +9 -7
  154. package/dist/prompts/default.d.ts +1 -2
  155. package/dist/scenarios/full-body.d.ts +1 -1
  156. package/dist/shell/lex.d.ts +50 -15
  157. package/dist/shell/lex.js +43 -9
  158. package/dist/stores/file/adoption/adopt.d.ts +1 -1
  159. package/dist/stores/file/index.d.ts +1 -15
  160. package/dist/stores/file/index.js +1 -15
  161. package/dist/stores/file/permission-rule-store.d.ts +12 -1
  162. package/dist/stores/file/permission-rule-store.js +31 -4
  163. package/dist/stores/file/session-store.js +1 -1
  164. package/dist/tools/fs/fs-bash.js +3 -3
  165. package/dist/tools/fs/removal-targets.d.ts +8 -2
  166. package/dist/tools/fs/removal-targets.js +31 -4
  167. package/dist/tools/fs/shell-read-argv.js +7 -1
  168. package/dist/tools/fs/shell-read-bindings.d.ts +21 -5
  169. package/dist/tools/fs/shell-read-bindings.js +130 -44
  170. package/dist/tools/fs/shell-read-plan.js +95 -29
  171. package/dist/tools/fs/shell-read-sourced.d.ts +25 -0
  172. package/dist/tools/fs/shell-read-sourced.js +119 -0
  173. package/dist/tools/fs/shell-read-word.d.ts +2 -2
  174. package/dist/tools/fs/shell-read-word.js +4 -5
  175. package/dist/tools/fs/shell-read-workdir.d.ts +19 -3
  176. package/dist/tools/fs/shell-read-workdir.js +60 -15
  177. package/dist/tools/fs/shell-reentry-text.d.ts +10 -2
  178. package/dist/tools/fs/shell-reentry-text.js +11 -4
  179. package/package.json +2 -2
  180. package/test/export-surface.snapshot.json +21 -79
  181. package/wire-changes/core-stores-sql@7.65.0.json +30 -0
  182. package/wire-changes/core-stores-sql@7.66.0.json +30 -0
  183. package/wire-changes/core@7.65.0.json +1650 -0
  184. package/wire-changes/core@7.66.0.json +1218 -0
  185. package/wire-changes/mods-kernel@7.65.0.json +30 -0
  186. package/wire-changes/mods-kernel@7.66.0.json +65 -0
  187. package/wire-changes/primitives@7.65.0.json +337 -0
  188. package/wire-changes/primitives@7.66.0.json +30 -0
  189. package/dist/core/memory-recall.d.ts +0 -208
  190. package/dist/core/memory-recall.js +0 -136
  191. package/dist/stores/file/memory-store.d.ts +0 -124
  192. package/dist/stores/file/memory-store.js +0 -353
@@ -523,15 +523,31 @@ export declare function sessionAddressOf(leg: {
523
523
  readonly sessionIncarnation?: string;
524
524
  readonly sessionIncarnationUnread?: true;
525
525
  }): SessionAddress;
526
- /** Which seat a frame addressed to an earlier occupant of a session would have reached under the occupant the session
527
- * holds now: that occupant's live run, its durable box, or its next run's turn-open drain. */
528
- export type DiscardedDeliveryPath = "live" | "box" | "drain";
526
+ /** The words {@link DiscardedDeliveryPath} is made of, as a value (#3505): the closed set a host reads off
527
+ * `delegation.delivery_discarded`'s `detail.path` against, so it does not copy the four words by hand. Root-exported. */
528
+ export declare const DISCARDED_DELIVERY_PATHS: readonly ["live", "box", "drain", "notice"];
529
+ /** Which seat a delivery addressed to an earlier occupant of a session would have reached under the occupant the session
530
+ * holds now: for a frame, that occupant's live run, its durable box, or its next run's turn-open drain; for a delegated leg's
531
+ * user-face notice addressed to its tree's root, the notice sink that routes it to the root session (`notice`). Derived from
532
+ * {@link DISCARDED_DELIVERY_PATHS}, so the type and the value are one set. */
533
+ export type DiscardedDeliveryPath = (typeof DISCARDED_DELIVERY_PATHS)[number];
534
+ /** What a discarded delivery was, by name only: a frame's task (its id and type), or a delegated leg's user-face notice (the
535
+ * leg it came from — its agent id, else its session — and the notice's code). */
536
+ export interface DiscardedDelivery {
537
+ readonly taskId: string;
538
+ readonly taskType: string;
539
+ }
540
+ /** The Runner's judge of a delegated leg's notice destination ({@link PendingSessionNotifications.discardsStaleNotice}): `true`
541
+ * = the notice is addressed to an occupant the root no longer holds, and was discarded and announced. */
542
+ export type NoticeDestinationJudge = (destination: SessionAddress, delivery: DiscardedDelivery) => boolean;
543
+ /** A frame's name as a discarded delivery: its task id and type, nothing of its text. */
544
+ export declare function frameDelivery(payload: TaskNotificationPayload): DiscardedDelivery;
529
545
  /**
530
- * The account of a frame discarded because its address names an occupant the session no longer holds — the one mint of
531
- * `delegation.delivery_discarded`. Counts and words only: the frame's text (a child's summary, a peer's words) never
532
- * rides it, nor either occupant token (only whether each side had one).
546
+ * The account of a delivery discarded because its address names an occupant the session no longer holds — the one mint of
547
+ * `delegation.delivery_discarded`. Counts and words only: the delivery's text (a child's summary, a peer's words, a notice's
548
+ * sentence) never rides it, nor either occupant token (only whether each side had one).
533
549
  */
534
- export declare function deliveryDiscardedNotice(address: Pick<SessionAddress, "sessionId" | "occupant">, current: string | undefined, payload: TaskNotificationPayload, path: DiscardedDeliveryPath): EngineNotice;
550
+ export declare function deliveryDiscardedNotice(address: Pick<SessionAddress, "sessionId" | "occupant">, current: string | undefined, delivery: DiscardedDelivery, path: DiscardedDeliveryPath): EngineNotice;
535
551
  /**
536
552
  * A session's DURABLE box, bound to the park seat by the leg that mounts its session-box drain — one
537
553
  * mint (the drain mount judgment), two readers (the drain and {@link routeOrParkNotification}), so
@@ -933,7 +949,18 @@ export declare class PendingSessionNotifications {
933
949
  * address (a leg that could not read its occupant) is nobody's: its frames are discarded the same way, whatever the seat.
934
950
  */
935
951
  discardsStale(address: SessionAddress, payload: TaskNotificationPayload): boolean;
936
- /** The one place a discarded frame is announced. */
952
+ /**
953
+ * The same question for a delegated leg's user-face notice, addressed to its tree's root: is `destination` (the root's id
954
+ * and the occupant the tree was born under) an earlier occupant of a session whose current occupant is another? Then the
955
+ * notice is discarded — announced with path `notice` — and the answer is `true`: the leg delivers nothing. `false` for the
956
+ * current occupant, and for a root no leg of which this process admitted. A notice cannot wait for the root's next leg
957
+ * the way a frame parks, so a root that was created again but not yet admitted here is not known to be another occupant.
958
+ */
959
+ discardsStaleNotice(destination: SessionAddress, delivery: DiscardedDelivery): boolean;
960
+ /** The one judgement both discards read: `undefined` when `address` is the session's current occupant, or the session has
961
+ * none on record; else the seat it was judged against (absent for an unread address on a session with no seat). */
962
+ private staleAgainst;
963
+ /** The one place a discarded delivery is announced. */
937
964
  private announceDiscard;
938
965
  /** Discard a record parked for an occupant the session no longer holds: every frame in it is announced; the record's own
939
966
  * bookkeeping (its eviction counts, its box debts) belongs to that occupant and goes with it. */
@@ -5,7 +5,7 @@ import { redactThenCut } from "../agents/subagent-steps.js";
5
5
  import { PEER_MESSAGE_NOTICE } from "../agents/peer-admission.js";
6
6
  import { buildCrossSessionEnvelope, CROSS_PRINCIPAL_MESSAGE_NOTICE, CROSS_SESSION_MESSAGE_NOTICE, neutralizePeerBody } from "../agents/cross-session-envelope.js";
7
7
  import { deliverEngineNotice } from "./engine-notice.js";
8
- import { sameOccupant } from "./runner/delegation-owner.js";
8
+ import { sameOccupant } from "../engine/session/repo-utils.js";
9
9
  export const TASK_NOTIFICATION_TERMINAL_STATUSES = Object.freeze(["completed", "failed", "killed", "cancelled"]);
10
10
  export const NOTIFICATION_INJECTION_OUTCOMES = Object.freeze(["queued", "parked", "parked_durably", "dropped_duplicate", "refused"]);
11
11
  export function isNotificationInjectionOutcome(value) {
@@ -168,17 +168,21 @@ export const MAX_SESSION_BOX_BINDINGS = 4096;
168
168
  export function sessionAddressOf(leg) {
169
169
  return { sessionId: leg.sessionId, occupant: leg.sessionIncarnation, ...(leg.sessionIncarnationUnread === true ? { unread: true } : {}) };
170
170
  }
171
- export function deliveryDiscardedNotice(address, current, payload, path) {
171
+ export const DISCARDED_DELIVERY_PATHS = Object.freeze(["live", "box", "drain", "notice"]);
172
+ export function frameDelivery(payload) {
173
+ return { taskId: payload.task_id, taskType: payload.task_type };
174
+ }
175
+ export function deliveryDiscardedNotice(address, current, delivery, path) {
172
176
  return {
173
177
  code: "delegation.delivery_discarded",
174
- message: `a ${inlineUntrusted(String(payload.task_type), 40)} frame of task ${inlineUntrusted(String(payload.task_id), 120)} was addressed to session ${inlineUntrusted(address.sessionId, 120)} under an occupant the session does not hold now (the id was deleted and created again, or the address carried no occupant), so it was discarded, not delivered`,
178
+ message: `a ${inlineUntrusted(String(delivery.taskType), 40)} ${path === "notice" ? "notice" : "frame"} of task ${inlineUntrusted(String(delivery.taskId), 120)} was addressed to session ${inlineUntrusted(address.sessionId, 120)} under an occupant the session does not hold now (the id was deleted and created again, or the address carried no occupant), so it was discarded, not delivered`,
175
179
  detail: {
176
- taskId: payload.task_id,
177
- taskType: payload.task_type,
180
+ taskId: delivery.taskId,
181
+ taskType: delivery.taskType,
178
182
  sessionId: address.sessionId,
179
183
  path,
180
- addressed: address.occupant !== undefined ? "known" : "unknown",
181
- current: current !== undefined ? "known" : "unknown",
184
+ addressed: sameOccupant(address.occupant, undefined) ? "unknown" : "known",
185
+ current: sameOccupant(current, undefined) ? "unknown" : "known",
182
186
  },
183
187
  };
184
188
  }
@@ -550,22 +554,36 @@ export class PendingSessionNotifications {
550
554
  return seat !== undefined && sameOccupant(seat.occupant, address.occupant) ? seat.box : undefined;
551
555
  }
552
556
  discardsStale(address, payload) {
553
- const seat = this.seats.get(address.sessionId);
554
- if (address.unread !== true && (seat === undefined || sameOccupant(address.occupant, seat.occupant)))
557
+ const stale = this.staleAgainst(address);
558
+ if (stale === undefined)
555
559
  return false;
560
+ const { seat } = stale;
556
561
  const current = { sessionId: address.sessionId, occupant: seat?.occupant };
557
562
  const path = seat !== undefined && this.liveLanes.holds(current) ? "live" : seat?.box !== undefined && parksDurably(payload, seat.box) ? "box" : "drain";
558
- this.announceDiscard(address, seat?.occupant, payload, path);
563
+ this.announceDiscard(address, seat?.occupant, frameDelivery(payload), path);
564
+ return true;
565
+ }
566
+ discardsStaleNotice(destination, delivery) {
567
+ const stale = this.staleAgainst(destination);
568
+ if (stale === undefined)
569
+ return false;
570
+ this.announceDiscard(destination, stale.seat?.occupant, delivery, "notice");
559
571
  return true;
560
572
  }
561
- announceDiscard(address, current, payload, path) {
562
- deliverEngineNotice(this.noticeSeat(), deliveryDiscardedNotice(address, current, payload, path));
573
+ staleAgainst(address) {
574
+ const seat = this.seats.get(address.sessionId);
575
+ if (address.unread !== true && (seat === undefined || sameOccupant(address.occupant, seat.occupant)))
576
+ return undefined;
577
+ return { seat };
578
+ }
579
+ announceDiscard(address, current, delivery, path) {
580
+ deliverEngineNotice(this.noticeSeat(), deliveryDiscardedNotice(address, current, delivery, path));
563
581
  }
564
582
  discardRecord(sessionId, record, current) {
565
583
  if (this.sessions.get(sessionId) === record)
566
584
  this.sessions.delete(sessionId);
567
585
  for (const n of record.items)
568
- this.announceDiscard({ sessionId, occupant: record.occupant }, current, n, "drain");
586
+ this.announceDiscard({ sessionId, occupant: record.occupant }, current, frameDelivery(n), "drain");
569
587
  }
570
588
  recordOf(address) {
571
589
  const s = this.sessions.get(address.sessionId);
@@ -450,6 +450,7 @@ export function registerBackgroundAgentLane(core, input) {
450
450
  sessionScoped: input.sessionScoped === true,
451
451
  ...(input.parentSessionId !== undefined ? { parentSessionId: input.parentSessionId } : {}),
452
452
  ...(input.rootSessionId !== undefined ? { rootSessionId: input.rootSessionId } : {}),
453
+ ...(input.rootSessionId !== undefined && input.rootSessionIncarnation !== undefined ? { rootSessionIncarnation: input.rootSessionIncarnation } : {}),
453
454
  ...(input.parentTaskId !== undefined ? { parentTaskId: input.parentTaskId } : {}),
454
455
  name,
455
456
  ...(input.agentType !== undefined ? { agentType: input.agentType } : {}),
@@ -948,6 +948,10 @@ export interface RegisterBackgroundAgentInput extends TaskAccess {
948
948
  * internals chain; equals parentSessionId at depth 1). Persisted on the handle, the durable row
949
949
  * and the roster so recovery faces enumerate the whole tree under the root without alias walks. */
950
950
  rootSessionId?: string;
951
+ /** The occupant of {@link rootSessionId}'s row as the spawning tree holds it (the spawner's `ctx.rootSessionIncarnation`):
952
+ * persisted on the durable row beside the anchor (`BackgroundAgentRecord.rootSessionIncarnation`), so a revival addresses
953
+ * its subtree's escalations to the occupant the tree was born under. Written only together with {@link rootSessionId}. */
954
+ rootSessionIncarnation?: string;
951
955
  /** design/151 S3b — the revival lookup key (CC meta-sidecar shape): the model RECORD KEY,
952
956
  * persisted on the durable row so a tier-3 revival rebuilds the spec the way a fresh
953
957
  * named-teammate spawn would. A lookup key only, never a serialized spec. `model` is NOT the
@@ -103,9 +103,9 @@ export declare function formatToolError(error: unknown): string;
103
103
  * `memory.admission_required`/`_denied` are EXACT codes, not a broad `memory.` prefix —
104
104
  * falsification review (A-005.3 follow-up) caught an
105
105
  * earlier draft folding EVERY `memory.*` code here, which misclassified the
106
- * memory-engine's non-governance incident codes (`memory.secret_detected` et al.,
107
- * explicitly listed as NON-governance in `NON_GOVERNANCE_MEMORY_CODES` — a content-safety
108
- * tool-call refusal, not a task-spec rejection) as configuration failures. `usage.*` STAYS
106
+ * memory-engine's non-governance incident codes (`memory.announce_failed` et al.,
107
+ * explicitly listed as NON-governance in `NON_GOVERNANCE_MEMORY_CODES` — engine incidents,
108
+ * not task-spec rejections) as configuration failures. `usage.*` STAYS
109
109
  * a broad prefix: governance-codes.ts's own `governanceRetryClass` already treats every
110
110
  * `usage.*` code (registered or not) as governance by prefix — a deliberate legacy-family
111
111
  * rule this folder mirrors rather than re-deciding (questioned whether that
@@ -3,7 +3,7 @@ import { homedir } from "node:os";
3
3
  import { argsReadFrom, carryArgsReadFrom, withArgsReading } from "./effective-path-target.js";
4
4
  import { editRewrittenSentence, readRejudge, rewriteChasedSentence } from "./rewrite-rejudge.js";
5
5
  import { brandPolicyAskClass } from "./ask-class.js";
6
- import { decisionAskClassesOf, headlessDenialMessage, joinAskReasons } from "./ask-origin.js";
6
+ import { decisionAskClassesOf, headlessDenialMessage, joinAskReasons, unresolvedAskDenialMessage } from "./ask-origin.js";
7
7
  import { attest, attestationOf, engineSentenceOf, isEngineAttestation, mergeAttestation, mintAttestation, withAttestation } from "./engine-attestation.js";
8
8
  import { ownReadRootCandidate, readRootGrantSeat } from "./read-root-grant-screen.js";
9
9
  import { DECIDED_VIA, decidersNote, isDecidedVia, policyDeciderOf, settledByDecider } from "./gate-outcome.js";
@@ -1341,8 +1341,7 @@ async function resolveAskArms(req, onAsk, signal, onLateSettlement) {
1341
1341
  if (ok === "unavailable") {
1342
1342
  return {
1343
1343
  action: "deny",
1344
- message: `approval required for "${req.toolName}" but the approver reported unavailable (no reachable ` +
1345
- `operator for this ask) and no durable approval gate is armed — denied fail-closed: ${req.message}`,
1344
+ message: unresolvedAskDenialMessage("approver_unavailable", req.toolName, req.message, false),
1346
1345
  decisionReason: "mode",
1347
1346
  settlement: settledByNobody("approver_unavailable"),
1348
1347
  approverUnavailable: true,
@@ -16,7 +16,7 @@ import type { TaskSpec } from "./task-spec.js";
16
16
  import type { BackgroundChildEvent } from "./delegation-frames.js";
17
17
  import type { ModelRef } from "./model-seat.js";
18
18
  import type { ToolFamily, ToolHostTarget, ToolPathTarget, ToolRenderHints, ToolRuleFace } from "./tool-face.js";
19
- import type { MemoryGovernanceDocs } from "./memory-engine/types.js";
19
+ import type { MemoryGovernanceStore } from "./memory-engine/types.js";
20
20
  /**
21
21
  * Side-effect class of a tool. Used by wake/resume reconciliation: when a call was interrupted
22
22
  * before its result was recorded, the outcome is unknown, so core must decide whether re-doing it
@@ -673,12 +673,11 @@ export interface NestedUsageAccum {
673
673
  * carry knownness alongside the number it qualifies. */
674
674
  anyUnpriced: boolean;
675
675
  }
676
- /** {@link ToolExecuteContext.delegationSettlement}'s answer: where a delegation's settlement rows are kept (the WRITE
677
- * plane's governance store), that plane's control-plane directory (the pollution marker and the hold custody files a
678
- * settled delegation's effects reach), and the session whose rows they are. */
676
+ /** {@link ToolExecuteContext.delegationSettlement}'s answer: the WRITE plane's governance store — where a delegation's
677
+ * settlement rows are kept and where the effects a settled delegation reaches land (the session's pollution marker) —
678
+ * and the session whose rows they are. */
679
679
  export interface DelegationSettlementSeat {
680
- readonly governance: MemoryGovernanceDocs;
681
- readonly controlDir: string;
680
+ readonly governance: MemoryGovernanceStore;
682
681
  readonly sessionId: string;
683
682
  }
684
683
  export interface ToolExecuteContext {
@@ -711,7 +710,8 @@ export interface ToolExecuteContext {
711
710
  rootSessionId?: string;
712
711
  /** The occupant (`SessionMetadata.incarnation`) of the session the fixed point above names (`rootSessionId ?? sessionId`)
713
712
  * as this tree holds it — Runner-filled, trusted. A spawn hands it down beside the root anchor
714
- * (`RunInternals.rootSessionIncarnation`); absent = unknown (a row minted before occupants, a revival's tree). */
713
+ * (`RunInternals.rootSessionIncarnation`) and a background spawn persists it on its row, where a revival reads it back;
714
+ * absent = unknown (a row minted before occupants, a revival of a row that recorded none). */
715
715
  rootSessionIncarnation?: string;
716
716
  /** The run's delegation tree owner seat (`RunInternals.delegationOwner`, Runner-filled): a delegation tool reads the tree's owner
717
717
  * 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
@@ -1160,9 +1160,10 @@ export interface ToolExecuteContext {
1160
1160
  * a floor no selection loosens (the `memoryPersistenceCapable:false` floor's exact law, on the
1161
1161
  * privacy axis). Trusted Runner-filled seat, never a model/tool argument.
1162
1162
  *
1163
- * DUAL FORM (#511 件2): on a deployment whose capture record store is synchronous (the default
1164
- * file trio) this is a plain boolean, byte-identical to before; a Promise-form
1165
- * {@link RunnerDeps.memoryCaptureRecordStore} makes the live read answer a `Promise<boolean>`.
1163
+ * DUAL FORM (#511 件2): on a deployment whose capture record store answers synchronously (a host
1164
+ * store) this is a plain boolean; the default carrier (the governance store's `capture` objects,
1165
+ * #3484) and a Promise-form {@link RunnerDeps.memoryCaptureRecordStore} make the live read answer a
1166
+ * `Promise<boolean>`.
1166
1167
  * Consumers must `await` (identity on the boolean arm) — a bare `=== true` on the Promise arm
1167
1168
  * would coin `false`, the exact un-floored escape this seat closes.
1168
1169
  */
@@ -1315,6 +1316,15 @@ export interface ToolExecuteContext {
1315
1316
  * park in its subtree). Same discipline as `principal`: inherit verbatim off the trusted seat.
1316
1317
  */
1317
1318
  checkpointStoreForChildren?: import("./checkpoint-store.js").CheckpointStore | "disabled";
1319
+ /**
1320
+ * The registry the host run's background tasks live in — the one its leg end (the owed-delivery reading), TaskStop, ListAgents
1321
+ * and its teardown read. Runner-filled, read-only, NEVER a model/tool argument; ABSENT when the tool runs outside a Runner task.
1322
+ * A delegation tool registers its background children here (C-R1143, #2280): its `background.registry` option is the
1323
+ * out-of-task fallback only, and inside a task an option naming a different registry is refused at spawn
1324
+ * (`config.invalid_task_registry`) — the same reading the bag's `checkpointStore` member has against
1325
+ * {@link checkpointStoreForChildren}.
1326
+ */
1327
+ taskRegistry?: import("./task-registry.js").TaskRegistry;
1318
1328
  /**
1319
1329
  * The host run's checkpoint SCOPE, for its children — the scope this run's own parked rows land in (the one
1320
1330
  * value its prepare derived; a delegated host's is the scope ITS parent handed it, so a whole tree answers
@@ -23,7 +23,7 @@
23
23
  * message's text blocks with no separator.
24
24
  */
25
25
  import type { ImageContent, TextContent, UserAttachmentSupply, UserMessageAttachment } from "../internal/llm.js";
26
- import type { HumanInputAttachment } from "./task-event.js";
26
+ import type { ExtensionRequester, HumanInputAttachment } from "./task-event.js";
27
27
  import { type ModelFileReader } from "../tools/fs/fs-read.js";
28
28
  import { type ImageDownsampler } from "./image-downsample.js";
29
29
  import type { SyntheticReadJudge } from "./synthetic-read-verdict.js";
@@ -135,6 +135,10 @@ export interface MintedAttachmentFrame {
135
135
  readonly attachment: UserMessageAttachment;
136
136
  };
137
137
  readonly commit?: () => void;
138
+ /** The extension a `prompt.mention` outcome names as this attachment's refuser ({@link HumanInputAttachment.declinedBy}, which
139
+ * {@link humanInputAttachmentsOf} projects it into). Not part of the transcript record: the `human_input` frame is built from the
140
+ * frames this run just minted. */
141
+ readonly declinedBy?: ExtensionRequester;
138
142
  }
139
143
  export interface ReadUserAttachmentsInput {
140
144
  screened: readonly ScreenedUserAttachment[];
@@ -1,4 +1,5 @@
1
1
  import { quoteDataLabel, userAttachmentOf } from "../internal/llm.js";
2
+ import { readExtensionRequester } from "./extension-requester.js";
2
3
  import { READ_OUTCOMES } from "../tools/fs/fs-read.js";
3
4
  import { renderDirectoryListing } from "../tools/fs/dir-entries.js";
4
5
  import { MAX_READ_OUTPUT_CHARS } from "../tools/fs/fs-shared.js";
@@ -12,6 +13,7 @@ import { DEFAULT_CHARS_PER_TOKEN, estimateTokens, uuidv7 } from "../internal/har
12
13
  import { thrownText } from "./thrown-value.js";
13
14
  import { optionKeys, receiveMembers } from "./own-property-receipt.js";
14
15
  import { guardBudget } from "./context-guard.js";
16
+ import { namedRegistration } from "./mods/kernel/registration.js";
15
17
  import { failedHandlerClause } from "./mods/stations.js";
16
18
  import { agentIdOf } from "./leg-identity.js";
17
19
  import { extensionWords } from "./untrusted-egress.js";
@@ -319,7 +321,7 @@ const declineOf = (x) => isPlainObject(x) && Object.keys(x).length === 1 && ((ty
319
321
  : undefined;
320
322
  async function readMentioned(a, ordinal, input, mentions) {
321
323
  const label = a.supply === "path" ? a.path : a.name;
322
- const declined = (text) => ({ supply: a.supply, label, outcome: "not_attached", shape: "file", data: [{ type: "text", text }], notes: [{ kind: "extension_declined" }], unscanned: [label, text], truncated: false });
324
+ const declined = (text, by) => ({ supply: a.supply, label, outcome: "not_attached", shape: "file", data: [{ type: "text", text }], notes: [{ kind: "extension_declined" }], unscanned: [label, text], truncated: false, ...(by !== undefined ? { declinedBy: by } : {}) });
323
325
  const window = a.supply === "path" && a.lines !== undefined ? { offset: a.lines.start, ...(a.lines.end !== undefined ? { limit: a.lines.end - a.lines.start + 1 } : {}) } : {};
324
326
  const e = { mention: declarationOf(a, ordinal), ...(mentions.agentId !== undefined ? { agentId: mentions.agentId } : {}), ...(a.supply === "path" ? { path: a.path, ...window } : {}) };
325
327
  const reads = new Map();
@@ -345,12 +347,16 @@ async function readMentioned(a, ordinal, input, mentions) {
345
347
  if (outcome.kind === "aborted")
346
348
  return declined("Not attached: the run was cancelled while an extension was judging it.");
347
349
  if (outcome.kind === "failed")
348
- return declined(`Not attached: a prompt.mention extension ${failedHandlerClause(outcome)}.`);
350
+ return declined(`Not attached: a prompt.mention extension ${failedHandlerClause(outcome)}.`, refuserOf(outcome));
349
351
  const read = typeof outcome.answer === "object" && outcome.answer !== null ? reads.get(outcome.answer) : undefined;
350
352
  if (read !== undefined)
351
353
  return read;
352
354
  const reason = declineOf(outcome.answer)?.reason;
353
- return declined(`Not attached: extension "${extensionWords(outcome.answeredBy ?? "engine", 80)}" declined it${reason !== undefined ? `: ${extensionWords(reason, 300)}` : ""}.`);
355
+ return declined(`Not attached: extension "${extensionWords(outcome.answeredBy ?? "engine", 80)}" declined it${reason !== undefined ? `: ${extensionWords(reason, 300)}` : ""}.`, refuserOf(outcome));
356
+ }
357
+ function refuserOf(outcome) {
358
+ const named = namedRegistration(outcome.kind === "failed" ? outcome.registration : outcome.answeredBy);
359
+ return named === undefined ? undefined : readExtensionRequester({ kind: "extension", name: named });
354
360
  }
355
361
  function respelled(a, handed) {
356
362
  if (a.supply !== "path") {
@@ -480,7 +486,7 @@ function mintFrame(r, at, seat) {
480
486
  const result = r.result;
481
487
  const extra = scan.effects.counts.length > 0 || scan.effects.windows.length > 0 ? [scan.effects] : [];
482
488
  const commit = result !== undefined || extra.length > 0 ? () => seat.commit(result, extra, attachmentTransmissionId(at)) : undefined;
483
- return { seed: { content, attachment }, ...(commit !== undefined ? { commit } : {}) };
489
+ return { seed: { content, attachment }, ...(commit !== undefined ? { commit } : {}), ...(r.declinedBy !== undefined ? { declinedBy: r.declinedBy } : {}) };
484
490
  }
485
491
  function refuseFramesOverWindow(frames, model, window) {
486
492
  const budget = guardBudget(model, window.overlay());
@@ -585,7 +591,7 @@ export function lastAttachmentFrameOf(entries, id) {
585
591
  }
586
592
  }
587
593
  export function humanInputAttachmentsOf(frames) {
588
- return frames.map(({ seed: { attachment: a } }) => ({ ordinal: a.ordinal, ...(a.kind !== undefined ? { kind: a.kind } : {}), outcome: a.outcome, label: a.label }));
594
+ return frames.map(({ seed: { attachment: a }, declinedBy }) => ({ ordinal: a.ordinal, ...(a.kind !== undefined ? { kind: a.kind } : {}), outcome: a.outcome, label: a.label, ...(declinedBy !== undefined ? { declinedBy } : {}) }));
589
595
  }
590
596
  export function createAttachmentDelivery() {
591
597
  const pending = new Map();
@@ -295,6 +295,22 @@ export declare function compileLegWriteJudgment(entries: readonly WriteProtected
295
295
  * · `clear` ⇒ `undefined`: the surviving decision stands.
296
296
  */
297
297
  export declare function writeProtectionTightenDecision(toolName: string, verdict: WriteProtectionVerdict): PermissionResult | undefined;
298
+ /**
299
+ * The question a surviving ASK is said with when the table also meets its target: the standing ask — its action, provenance
300
+ * and disclosures — with {@link writeProtectionTightenDecision}'s own sentence after its message in parentheses (the form the
301
+ * persisted-rule tightening appends its account in), once; a standing ask without a message takes the sentence alone. One
302
+ * sentence is minted (beside the verdict); this only places it. A standing ask whose message IS the engine's own sentence
303
+ * (`engineSentenceOf`) keeps the account of it over the result: both halves are the engine's words, the literals the account
304
+ * lists are still quoted by the longer text, and this station composed the longer text — the account's only writer — so it
305
+ * restates the account for it (`generic` and `echoed` ride along, `text` is the result's message). Any other standing ask
306
+ * (a hook's, a deployment's) keeps its words and no account.
307
+ */
308
+ export declare function askWithTableSentence<T extends {
309
+ readonly message?: string;
310
+ }>(standing: T, tightenSentence: string, call: {
311
+ toolCallId: string;
312
+ toolName: string;
313
+ }): T;
298
314
  /**
299
315
  * @contract write_protection.verdict_is_the_mandate — a MATCHED row is the one fact of the judge's verdict a standing
300
316
  * allow rule may not retire (a live decider may still clear it), and `clear` is not it; this predicate is the one reading
@@ -7,6 +7,7 @@ import { chainHopsOrNone, symlinkChainHops } from "./path-identity.js";
7
7
  import { readDenyPatternRun } from "../tools/fs/read-deny.js";
8
8
  import { agentConfigDirSegments, agentConfigDirTail } from "./agent-config-dir.js";
9
9
  import { thrownText } from "./thrown-value.js";
10
+ import { attest, engineSentenceOf } from "./engine-attestation.js";
10
11
  import { fromSource, gateWaitFailureOf } from "./gate-bounded-await.js";
11
12
  const freezeTable = (rows) => Object.freeze(rows.map((r) => Object.freeze(r)));
12
13
  export const WRITE_PROTECTED_DEFAULT_TABLE = freezeTable([
@@ -463,6 +464,15 @@ export function writeProtectionTightenDecision(toolName, verdict) {
463
464
  decisionReason: "safety",
464
465
  };
465
466
  }
467
+ export function askWithTableSentence(standing, tightenSentence, call) {
468
+ if (standing.message === undefined)
469
+ return { ...standing, message: tightenSentence };
470
+ if (standing.message.includes(tightenSentence))
471
+ return standing;
472
+ const merged = { ...standing, message: `${standing.message} (${tightenSentence})` };
473
+ const account = engineSentenceOf(standing, call);
474
+ return account === undefined ? merged : attest(merged, call, { sentence: { ...account, text: merged.message } });
475
+ }
466
476
  export function writeProtectionMandated(verdict) {
467
477
  return verdict.kind === "hit";
468
478
  }
@@ -73,12 +73,12 @@ export interface UserMessageProvenance {
73
73
  * task notifications, steering, recall) but never under user authority — see UserMessage.provenance. */
74
74
  provenance?: "engine-note";
75
75
  /** Who wrote the input this frame's CONTENT is ({@link InputAuthor}) — an input relayed by the engine (a TaskStream steer, the
76
- * observer's report), not engine-authored guidance. Rides only WITH `provenance:"engine-note"` (the projection semantics are
77
- * identical — visible, never `[user]` authority); what it changes is the run-control judgment: the human-halt hold below
78
- * treats an authored frame as input (always passes) while an engine-authored one is held, and only a frame whose author
79
- * counts as the operator's (`countsAsOperator`) is the person's input — parkable across a pause, on the undelivered-input
80
- * account. Minter-stated at the single relay seam that mints such frames — never inferred from text. Metadata only; not
81
- * persisted on the message. */
76
+ * observer's report, an extension's prompt), not engine-authored guidance. Rides only WITH `provenance:"engine-note"` (the
77
+ * projection semantics are identical — visible, never `[user]` authority); what it changes is the run-control judgment: only
78
+ * a frame whose author counts as the operator's (`countsAsOperator`) is the person's input — it passes the human-halt hold
79
+ * below, is parkable across a pause and is on the undelivered-input account; another author's is held by the hold like an
80
+ * engine-authored one. Minter-stated at the single relay seam that mints such frames — never inferred from text. Metadata
81
+ * only; not persisted on the message. */
82
82
  author?: InputAuthor;
83
83
  /** #1036 — the frame's injection-queue dedup key, persisted on the message it becomes
84
84
  * ({@link UserMessage.engineNoteKey}) so a reader of the TRANSCRIPT alone can join an entry back
@@ -183,6 +183,10 @@ export declare class AgentHarness<TSkill extends Skill = Skill, TPromptTemplate
183
183
  * the phase reads `"turn"` through all of that. Nothing awaits between this read and the injection
184
184
  * it gates, so a `true` cannot go stale under its caller. */
185
185
  get acceptsInjections(): boolean;
186
+ /** Is a prompt in flight — the harness takes an injection (`steer` / `followUp` refuse `invalid_state` while it is not)? The one
187
+ * reading of that fact: the injection verbs refuse on it, {@link acceptsInjections} conjoins it, and a producer that must know
188
+ * before it waits whether a loop has begun taking input (the steer relay's input window) reads it. */
189
+ get takingInput(): boolean;
186
190
  /** design/74 R3-A: the one-way clean-stop latch — SET iff this set is non-empty. When set, the boundary consults
187
191
  * answer true so the loop exits CLEANLY (emit `agent_end` + return) WITHOUT an abort/interrupt — the path a
188
192
  * resource-slice suspend needs (an abort would trip the orphan-[INTERRUPTED] reconcile = corrupt resume). It is
@@ -299,7 +303,9 @@ export declare class AgentHarness<TSkill extends Skill = Skill, TPromptTemplate
299
303
  * legitimately continues the run, otherwise handed to the terminal sweep (payload frames park
300
304
  * losslessly; payload-less boundary advisories end with the run, the same best-effort fate
301
305
  * their mint sites already accept for a final turn).
302
- * Caller/user-provenance input always passes — it is the awaited direction. One predicate here
306
+ * The operator's input always passes — it is the awaited direction; an input another author wrote (an extension's prompt, an
307
+ * observer's report) is held at the drain like an engine-authored frame, and the steer relay that carries it refuses it at
308
+ * entry (it reads this hold before its screen). One predicate here
303
309
  * instead of a per-lane check at every injection site: a future engine lane that never heard of
304
310
  * the halt is held by construction rather than by remembering. `nextTurn` is deliberately NOT
305
311
  * gated: its splice opens a NEW run (idle-park redelivery), and a halt belongs to the run that
@@ -408,10 +414,12 @@ export declare class AgentHarness<TSkill extends Skill = Skill, TPromptTemplate
408
414
  private createContext;
409
415
  private createStreamFn;
410
416
  /** May a drain take this frame now? The one predicate of the drain, the immediate re-check and {@link pendingInjectionCount}.
411
- * A person's or caller's frame always may. An engine-authored frame is held — a drained steer makes a request — under
412
- * the human-halt hold ({@link engineInjectionsHeld}), and an ADVISORY is held where the loop's own work owes no request
413
- * (`continuing` false): it rides a request, never makes one; a notification's payload is an event and may continue a
414
- * run. Held frames stay queued: later input drains past them, an owed drain takes them, else they end with the run. */
417
+ * The operator's frame always may ({@link isOperatorInput}). Any other frame — engine-authored, or an input another author
418
+ * wrote (an extension's prompt, an observer's report) — is held under the human-halt hold ({@link engineInjectionsHeld}): a
419
+ * drained frame makes a request, and only the person restarts a run they stopped. An ADVISORY is held as well where the
420
+ * loop's own work owes no request (`continuing` false): it rides a request, never makes one; a notification's payload is an
421
+ * event and may continue a run. Held frames stay queued: later input drains past them, an owed drain takes them, else they
422
+ * end with the run. */
415
423
  private isDrainable;
416
424
  private drainQueuedMessages;
417
425
  /** #389 — drop these frames from the in-flight account (they went back on a queue, or they landed). */
@@ -207,7 +207,10 @@ export class AgentHarness {
207
207
  session;
208
208
  phase = "idle";
209
209
  get acceptsInjections() {
210
- return this.phase !== "idle" && !this.aborting && !this.stopRequested;
210
+ return this.takingInput && !this.aborting && !this.stopRequested;
211
+ }
212
+ get takingInput() {
213
+ return this.phase !== "idle";
211
214
  }
212
215
  stopRequestSources = new Set();
213
216
  get stopRequested() {
@@ -610,7 +613,7 @@ export class AgentHarness {
610
613
  };
611
614
  }
612
615
  isDrainable(m, continuing) {
613
- if (!engineAuthoredInjections.has(m))
616
+ if (isOperatorInput(m))
614
617
  return true;
615
618
  if (this.engineInjectionsHeld?.() === true)
616
619
  return false;
@@ -1191,14 +1194,14 @@ export class AgentHarness {
1191
1194
  }
1192
1195
  }
1193
1196
  async steer(text, options) {
1194
- if (this.phase === "idle") {
1197
+ if (!this.takingInput) {
1195
1198
  throw new AgentHarnessError("invalid_state", "Cannot steer while idle");
1196
1199
  }
1197
1200
  this.refuseHeldEngineInjection(options);
1198
1201
  return await this.enqueueInjection(this.steerQueue, text, options);
1199
1202
  }
1200
1203
  async followUp(text, options) {
1201
- if (this.phase === "idle") {
1204
+ if (!this.takingInput) {
1202
1205
  throw new AgentHarnessError("invalid_state", "Cannot follow up while idle");
1203
1206
  }
1204
1207
  this.refuseHeldEngineInjection(options);
@@ -16,8 +16,9 @@ export type ImagesProvider = string;
16
16
  /**
17
17
  * Effort/intensity TIERS (no "off" — this is the value a provider effort field takes). ⚠ Name clash
18
18
  * by history with the loop-layer `ThinkingLevel` (engine/loop/types.ts), which is the SEVEN-value
19
- * on/off+tier knob ("off" | these six). Rule of thumb: harness/task config uses the loop's 7-tier
20
- * type; provider compat fields (`reasoningEffortLevels`/`effortLevels`) use this 6-tier one.
19
+ * on/off+tier knob ("off" | these six). Rule of thumb: harness/task config and the model entry's
20
+ * requested default (`Model.defaultThinking`, typed {@link ModelThinkingLevel}) use the 7-tier set; the
21
+ * effort ladders a provider compat declares (`reasoningEffortLevels`/`effortLevels`) use this 6-tier one.
21
22
  */
22
23
  export type ThinkingLevel = "minimal" | "low" | "medium" | "high" | "xhigh" | "max";
23
24
  export type ModelThinkingLevel = "off" | ThinkingLevel;
@@ -980,15 +981,26 @@ export interface Model<TApi extends Api = Api> {
980
981
  * (`brain/model-capability.ts`), which also says what an undeclared capability means. */
981
982
  reasoning?: boolean;
982
983
  /**
983
- * design/111 — this model's DEFAULT thinking level (per-model preset). The thinking-resolution chain is
984
- * `spec.thinking ?? role.thinking ?? model.defaultThinking` (prepare-task) — a caller/role still overrides, but
985
- * a model that should "think by default" (e.g. an Anthropic reasoning model defaulting to `medium`) declares it
986
- * here instead of every task/role re-specifying. Absent ⇒ no model-level default (chain falls to `undefined` =
987
- * thinking off unless a caller/role asks). It is the REQUESTED tier; the per-endpoint clamp (`resolveReasoning`/
988
- * `reasoningEffortLevels`) still bounds it — a stock-OpenAI endpoint clamps `max`→`high`, while an
989
- * `anthropic-messages` budget endpoint honors the full range up to `max` unclamped.
984
+ * design/111 — this model's DEFAULT thinking level: the tier a request to this model takes when neither the
985
+ * caller nor its role names one. The chain `spec.thinking ?? role.thinking ?? model.defaultThinking` is read in
986
+ * ONE place, `resolveTaskModel` (`ResolvedRole.thinking`), and every engine lane that resolves a model through it
987
+ * (the run, a side query, a compaction pass, the next-prompt suggestions) takes that one answer.
988
+ *
989
+ * `"off"` is a tier like the others: the request then carries the explicit off — the wire's disable key where it
990
+ * spells one (`thinkingOffSpelled`) — which is what a default-on gateway (a Qwen chat template) needs to stop
991
+ * thinking on a request that asked for nothing. It is NOT "no default": ABSENT is no default, and a request that
992
+ * names no tier then writes no thinking key at all, so the provider's default governs (a default-on gateway thinks).
993
+ *
994
+ * The two types stay apart: this member takes the seven tiers (`ModelThinkingLevel`), while the effort ladder a model
995
+ * declares (`compat.reasoningEffortLevels`, `compat.effortLevels`) stays the six enabled tiers ({@link ThinkingLevel}) —
996
+ * off is a tier a request asks for, spelled by the off arm of the wire, never a rung the clamp compares against.
997
+ *
998
+ * It is the REQUESTED tier, read exactly as a request's own: the per-endpoint clamp (`resolveReasoning` /
999
+ * `reasoningEffortLevels`) still bounds it — a stock-OpenAI endpoint clamps `max`→`high` — and a model that does
1000
+ * not hold `reasoning` carries none of it. A value that is not one of the seven tiers is refused where the model
1001
+ * is received (the model door, `config.unknown_role` / `not_a_model_ref`), never read as absence.
990
1002
  */
991
- defaultThinking?: ThinkingLevel;
1003
+ defaultThinking?: ModelThinkingLevel;
992
1004
  /**
993
1005
  * Maps OpenClaw thinking levels to provider/model-specific values.
994
1006
  * Missing keys use provider defaults. null marks a level as unsupported.
@@ -11,9 +11,19 @@ export declare function incarnationCell(existing: Pick<SessionMetadata, "incarna
11
11
  * is told once with the cell's shape (never its value). The cell never makes this throw; a throw from `disclose` propagates. */
12
12
  export declare function readIncarnationCell(raw: unknown, disclose: (detail: string) => void): string | undefined;
13
13
  /**
14
- * Whether two heads of one session id name the same occupant (each side a {@link SessionHead}, or a row's {@link SessionMetadata}).
15
- * `"unknown"` whenever either side has no row or no occupant token — unknown is never `"same"`, so a caller that may only proceed on the
16
- * same occupant refuses on it.
14
+ * THE reading of "do two readings of one session id's occupant cell (`SessionMetadata.incarnation`) name one occupant": each side is
15
+ * decoded as {@link readIncarnationCell} decodes a stored cell — a non-empty string is the token, anything else (absent, `""`, a
16
+ * non-string) is no token — and the two are one occupant when they hold the same token, or no token on either side (a row written before
17
+ * occupants were minted, taken as it reads: every write that creates a row mints a token, so a row created again under the id never reads
18
+ * as the one before it). A token on one side only is another occupant. Every occupant question in the engine asks this one predicate:
19
+ * a run's own seats (the tree owner, the session address a frame or a notice is delivered to, a box record's addressee) directly, and a
20
+ * comparison of two heads through {@link compareOccupants}.
21
+ */
22
+ export declare function sameOccupant(held: string | undefined, current: string | undefined): boolean;
23
+ /**
24
+ * Whether two heads of one session id name the same occupant (each side a {@link SessionHead}, or a row's {@link SessionMetadata}):
25
+ * `"unknown"` when either side has no row, otherwise {@link sameOccupant} of their occupant cells — `"same"` or `"different"`. Unknown
26
+ * is never `"same"`, so a caller that may only proceed on the same occupant refuses on it.
17
27
  */
18
28
  export declare function compareOccupants(before: {
19
29
  readonly incarnation?: SessionHead["incarnation"];
@@ -26,7 +36,7 @@ export declare function compareOccupants(before: {
26
36
  * log binds: no expectation ⇒ no precondition; `row: null` ⇒ the row must be absent; otherwise the row must be there with the same owner
27
37
  * and the same occupant cell and — when `log` is given — a log of the same mark ({@link sessionLogMarkOf}). The occupant cell is compared
28
38
  * as written, an absent token equal to an absent one: this asks whether any write changed the row since the read the expectation came
29
- * from, not whether two parties name one occupant ({@link compareOccupants}, where unknown is never the same) — and since every write
39
+ * from, not whether two parties name one occupant ({@link sameOccupant}, where an empty or non-string cell names nobody) — and since every write
30
40
  * that creates a row mints a token, a row without one cannot be created again, so an absent cell is one generation. An expectation that
31
41
  * is not of this shape is refused (a `TypeError` naming the member), never read as no precondition.
32
42
  */
@@ -26,12 +26,13 @@ function isOccupantToken(raw) {
26
26
  function nonStringShape(raw) {
27
27
  return Array.isArray(raw) ? "a non-string value (array)" : `a non-string value (${typeof raw})`;
28
28
  }
29
+ export function sameOccupant(held, current) {
30
+ return (isOccupantToken(held) ? held : undefined) === (isOccupantToken(current) ? current : undefined);
31
+ }
29
32
  export function compareOccupants(before, after) {
30
- const a = before?.incarnation;
31
- const b = after?.incarnation;
32
- if (!isOccupantToken(a) || !isOccupantToken(b))
33
+ if (before === undefined || after === undefined)
33
34
  return "unknown";
34
- return a === b ? "same" : "different";
35
+ return sameOccupant(before.incarnation, after.incarnation) ? "same" : "different";
35
36
  }
36
37
  export function sessionRowMatches(expect, row, logNow) {
37
38
  if (expect === undefined)