@sema-agent/core 7.63.0 → 7.65.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 (239) hide show
  1. package/CHANGELOG.md +725 -0
  2. package/dist/agents/cc-peer-directory.js +1 -0
  3. package/dist/agents/cc-peer-wire.d.ts +4 -0
  4. package/dist/agents/cc-peer-wire.js +1 -0
  5. package/dist/agents/cc-uds-peer-channel.js +5 -0
  6. package/dist/agents/cross-session-judge.d.ts +3 -1
  7. package/dist/agents/cross-session-judge.js +4 -1
  8. package/dist/agents/peer-directory.d.ts +8 -0
  9. package/dist/agents/peer-directory.js +4 -0
  10. package/dist/agents/peer-held-queue.d.ts +9 -3
  11. package/dist/agents/peer-held-queue.js +12 -9
  12. package/dist/agents/peer-idle.d.ts +20 -1
  13. package/dist/agents/peer-idle.js +23 -12
  14. package/dist/agents/peer-notice-route.d.ts +16 -5
  15. package/dist/agents/peer-notice-route.js +11 -9
  16. package/dist/agents/peer-notices.d.ts +25 -8
  17. package/dist/agents/peer-notices.js +6 -1
  18. package/dist/agents/peer-session-drain.d.ts +32 -6
  19. package/dist/agents/peer-session-drain.js +100 -26
  20. package/dist/agents/send-message-tool.d.ts +7 -0
  21. package/dist/agents/send-message-tool.js +18 -6
  22. package/dist/agents/subagent.js +25 -5
  23. package/dist/core/allow-entry.d.ts +4 -0
  24. package/dist/core/ask-origin.d.ts +1 -1
  25. package/dist/core/ask-origin.js +2 -2
  26. package/dist/core/ask-unresolvable-notice.d.ts +13 -4
  27. package/dist/core/ask-unresolvable-notice.js +10 -3
  28. package/dist/core/auto-compaction.d.ts +7 -5
  29. package/dist/core/auto-promote.d.ts +3 -2
  30. package/dist/core/background-agent-store.d.ts +14 -0
  31. package/dist/core/background-agent-store.js +3 -0
  32. package/dist/core/checkpoint-queries.d.ts +9 -6
  33. package/dist/core/checkpoint-queries.js +8 -3
  34. package/dist/core/checkpoint-store.d.ts +7 -4
  35. package/dist/core/context-settings.d.ts +39 -9
  36. package/dist/core/context-settings.js +32 -10
  37. package/dist/core/engine-attestation.d.ts +26 -6
  38. package/dist/core/engine-attestation.js +5 -1
  39. package/dist/core/engine-notice.d.ts +37 -2
  40. package/dist/core/engine-notice.js +3 -1
  41. package/dist/core/extension-requester.d.ts +9 -0
  42. package/dist/core/extension-requester.js +7 -0
  43. package/dist/core/file-history-store.d.ts +30 -2
  44. package/dist/core/file-history-store.js +48 -9
  45. package/dist/core/fs-write-gate-policy.js +1 -1
  46. package/dist/core/gate-fold.js +5 -1
  47. package/dist/core/gate-lanes.js +2 -0
  48. package/dist/core/gate-outcome.d.ts +39 -2
  49. package/dist/core/gate-outcome.js +20 -1
  50. package/dist/core/governance-codes.d.ts +8 -4
  51. package/dist/core/governance-codes.js +8 -3
  52. package/dist/core/leg-identity.d.ts +35 -1
  53. package/dist/core/leg-identity.js +10 -0
  54. package/dist/core/mailbox-store.d.ts +39 -4
  55. package/dist/core/mailbox-store.js +14 -2
  56. package/dist/core/memory-engine/consolidation.d.ts +13 -6
  57. package/dist/core/memory-engine/consolidation.js +26 -0
  58. package/dist/core/memory-engine/control-objects.d.ts +58 -0
  59. package/dist/core/memory-engine/control-objects.js +273 -0
  60. package/dist/core/memory-engine/control-plane-adoption.d.ts +51 -0
  61. package/dist/core/memory-engine/control-plane-adoption.js +161 -0
  62. package/dist/core/memory-engine/delegation-settlement.d.ts +73 -40
  63. package/dist/core/memory-engine/delegation-settlement.js +271 -107
  64. package/dist/core/memory-engine/dual-root.d.ts +3 -2
  65. package/dist/core/memory-engine/dual-root.js +7 -3
  66. package/dist/core/memory-engine/engine.d.ts +54 -33
  67. package/dist/core/memory-engine/engine.js +150 -157
  68. package/dist/core/memory-engine/file-backend.d.ts +58 -76
  69. package/dist/core/memory-engine/file-backend.js +111 -268
  70. package/dist/core/memory-engine/index.d.ts +3 -2
  71. package/dist/core/memory-engine/index.js +2 -1
  72. package/dist/core/memory-engine/layout.d.ts +135 -50
  73. package/dist/core/memory-engine/layout.js +214 -89
  74. package/dist/core/memory-engine/memory-age.d.ts +12 -0
  75. package/dist/core/memory-engine/memory-age.js +17 -0
  76. package/dist/core/memory-engine/memory-backend-contract.d.ts +10 -3
  77. package/dist/core/memory-engine/memory-backend-contract.js +159 -2
  78. package/dist/core/memory-engine/memory-deployment.d.ts +12 -4
  79. package/dist/core/memory-engine/memory-deployment.js +31 -6
  80. package/dist/core/memory-engine/origin-clearance.d.ts +12 -3
  81. package/dist/core/memory-engine/origin-clearance.js +64 -9
  82. package/dist/core/memory-engine/session-write-home.d.ts +34 -1
  83. package/dist/core/memory-engine/session-write-home.js +37 -10
  84. package/dist/core/memory-engine/tools.d.ts +2 -2
  85. package/dist/core/memory-engine/tools.js +7 -7
  86. package/dist/core/memory-engine/types.d.ts +55 -12
  87. package/dist/core/memory-engine/types.js +2 -1
  88. package/dist/core/memory-vector.d.ts +6 -14
  89. package/dist/core/memory.d.ts +0 -462
  90. package/dist/core/memory.js +0 -333
  91. package/dist/core/mode-policy.js +3 -3
  92. package/dist/core/mods/agent-stations.d.ts +18 -0
  93. package/dist/core/mods/agent-stations.js +8 -6
  94. package/dist/core/mods/extension-call.d.ts +4 -0
  95. package/dist/core/mods/extension-call.js +8 -0
  96. package/dist/core/mods/tool-call.js +3 -4
  97. package/dist/core/parent-spec-seat.d.ts +2 -2
  98. package/dist/core/peer-channel.d.ts +5 -0
  99. package/dist/core/permission-rule-consent.d.ts +64 -22
  100. package/dist/core/permission-rule-consent.js +106 -58
  101. package/dist/core/permission-rule-store.d.ts +56 -21
  102. package/dist/core/permission-rule-store.js +2 -0
  103. package/dist/core/refusal-echo.d.ts +20 -0
  104. package/dist/core/refusal-echo.js +33 -0
  105. package/dist/core/retention.d.ts +175 -10
  106. package/dist/core/retention.js +44 -0
  107. package/dist/core/retired-keys.d.ts +5 -0
  108. package/dist/core/retired-keys.js +3 -0
  109. package/dist/core/rule-offer-read.d.ts +0 -4
  110. package/dist/core/rule-offer-read.js +2 -18
  111. package/dist/core/runner/classifier-ladder.d.ts +10 -2
  112. package/dist/core/runner/classifier-ladder.js +4 -2
  113. package/dist/core/runner/compact-session.js +10 -7
  114. package/dist/core/runner/compaction-call-options.d.ts +7 -7
  115. package/dist/core/runner/compaction-call-options.js +3 -2
  116. package/dist/core/runner/contracts.d.ts +28 -9
  117. package/dist/core/runner/delegation-owner.d.ts +2 -3
  118. package/dist/core/runner/delegation-owner.js +2 -1
  119. package/dist/core/runner/gate-exit.d.ts +6 -0
  120. package/dist/core/runner/gate-exit.js +11 -2
  121. package/dist/core/runner/memory-consolidation-driver.d.ts +4 -2
  122. package/dist/core/runner/memory-consolidation-driver.js +8 -5
  123. package/dist/core/runner/prepare-ask-lane.js +3 -3
  124. package/dist/core/runner/prepare-caps-and-workflow.d.ts +3 -1
  125. package/dist/core/runner/prepare-caps-and-workflow.js +2 -2
  126. package/dist/core/runner/prepare-config-doors.js +4 -0
  127. package/dist/core/runner/prepare-delegation-surface.d.ts +3 -0
  128. package/dist/core/runner/prepare-delegation-surface.js +2 -2
  129. package/dist/core/runner/prepare-gate-stations.d.ts +8 -0
  130. package/dist/core/runner/prepare-gate-stations.js +15 -7
  131. package/dist/core/runner/prepare-hands-readface.js +1 -1
  132. package/dist/core/runner/prepare-inherited-gate.d.ts +3 -1
  133. package/dist/core/runner/prepare-inherited-gate.js +4 -2
  134. package/dist/core/runner/prepare-memory-engine-session.js +1 -1
  135. package/dist/core/runner/prepare-memory.d.ts +4 -0
  136. package/dist/core/runner/prepare-memory.js +22 -28
  137. package/dist/core/runner/prepare-policy-chain.js +18 -10
  138. package/dist/core/runner/prepare-prompt-inputs.js +1 -1
  139. package/dist/core/runner/prepare-task.d.ts +5 -1
  140. package/dist/core/runner/prepare-task.js +16 -11
  141. package/dist/core/runner/prepare-wiring-manifest.d.ts +3 -1
  142. package/dist/core/runner/prepare-wiring-manifest.js +3 -2
  143. package/dist/core/runner/resume-admission.d.ts +2 -2
  144. package/dist/core/runner/resume-admission.js +2 -23
  145. package/dist/core/runner/role-resolution-table.d.ts +98 -0
  146. package/dist/core/runner/role-resolution-table.js +62 -0
  147. package/dist/core/runner/run-compaction-machinery.js +2 -2
  148. package/dist/core/runner/run-identity-wiring.js +12 -9
  149. package/dist/core/runner/run-leg.js +8 -4
  150. package/dist/core/runner/run-notification-lane.js +23 -23
  151. package/dist/core/runner/run-recovery-lanes.js +3 -3
  152. package/dist/core/runner/run-terminal-adoption.js +1 -1
  153. package/dist/core/runner/run-turn-boundary.js +14 -15
  154. package/dist/core/runner/runtask.js +1 -1
  155. package/dist/core/runner/sub-agent-deny-lists.d.ts +19 -0
  156. package/dist/core/runner/sub-agent-deny-lists.js +25 -0
  157. package/dist/core/runner/tool-occurrence.d.ts +4 -2
  158. package/dist/core/runner/tool-occurrence.js +2 -2
  159. package/dist/core/runner-deps.d.ts +1 -1
  160. package/dist/core/secret-env.d.ts +2 -2
  161. package/dist/core/secret-env.js +6 -20
  162. package/dist/core/session-checkout.d.ts +63 -3
  163. package/dist/core/session-checkout.js +152 -58
  164. package/dist/core/session-store.d.ts +6 -6
  165. package/dist/core/session-store.js +3 -3
  166. package/dist/core/shell-read-silence.js +8 -0
  167. package/dist/core/store-contracts/background-agent-store-contract.js +13 -0
  168. package/dist/core/store-contracts/peer-directory-contract.js +8 -1
  169. package/dist/core/task-event.d.ts +9 -5
  170. package/dist/core/task-notification.d.ts +137 -31
  171. package/dist/core/task-notification.js +198 -100
  172. package/dist/core/task-registry-agent.d.ts +11 -0
  173. package/dist/core/task-registry-agent.js +12 -3
  174. package/dist/core/task-registry-shared.d.ts +11 -0
  175. package/dist/core/task-registry.d.ts +18 -0
  176. package/dist/core/task-registry.js +27 -8
  177. package/dist/core/task-spec.d.ts +7 -2
  178. package/dist/core/tool-errors.d.ts +17 -9
  179. package/dist/core/tool-errors.js +1 -1
  180. package/dist/core/tool-policy.d.ts +18 -1
  181. package/dist/core/tool-policy.js +16 -7
  182. package/dist/core/tool-result-store.d.ts +20 -0
  183. package/dist/core/tool-spec.d.ts +10 -6
  184. package/dist/core/trace.d.ts +3 -2
  185. package/dist/core/workflow-journal-store.d.ts +11 -0
  186. package/dist/core/workflow-journal-store.js +7 -0
  187. package/dist/core/workflow-run-store.d.ts +9 -0
  188. package/dist/core/workflow-run-store.js +6 -0
  189. package/dist/core/write-protect.d.ts +16 -0
  190. package/dist/core/write-protect.js +10 -0
  191. package/dist/engine/compaction/compaction.d.ts +2 -1
  192. package/dist/engine/harness/types.d.ts +1 -0
  193. package/dist/engine/session/repo-utils.d.ts +14 -4
  194. package/dist/engine/session/repo-utils.js +5 -4
  195. package/dist/engine/session/session.d.ts +7 -1
  196. package/dist/engine/session/session.js +5 -2
  197. package/dist/index.d.ts +13 -11
  198. package/dist/index.js +13 -11
  199. package/dist/orchestration/run-workflow-tool.d.ts +4 -0
  200. package/dist/orchestration/run-workflow-tool.js +7 -0
  201. package/dist/orchestration/workflow-types.d.ts +2 -1
  202. package/dist/orchestration/workflow.d.ts +3 -0
  203. package/dist/orchestration/workflow.js +2 -1
  204. package/dist/prompts/default.d.ts +1 -2
  205. package/dist/scenarios/full-body.d.ts +1 -1
  206. package/dist/stores/file/adoption/adopt.d.ts +1 -1
  207. package/dist/stores/file/checkpoint-store.d.ts +6 -0
  208. package/dist/stores/file/checkpoint-store.js +4 -1
  209. package/dist/stores/file/file-history-store.d.ts +13 -0
  210. package/dist/stores/file/file-history-store.js +75 -13
  211. package/dist/stores/file/index.d.ts +12 -16
  212. package/dist/stores/file/index.js +7 -25
  213. package/dist/stores/file/permission-rule-store.d.ts +34 -0
  214. package/dist/stores/file/permission-rule-store.js +104 -9
  215. package/dist/stores/file/session-store.js +1 -1
  216. package/dist/stores/file/tool-result-store.d.ts +14 -0
  217. package/dist/stores/file/tool-result-store.js +39 -2
  218. package/dist/stores/file/workflow-journal-store.d.ts +4 -0
  219. package/dist/stores/file/workflow-journal-store.js +17 -0
  220. package/dist/stores/file/workflow-run-store.d.ts +3 -0
  221. package/dist/stores/file/workflow-run-store.js +15 -0
  222. package/dist/tools/fs/read-deny.d.ts +15 -2
  223. package/dist/tools/fs/read-deny.js +10 -2
  224. package/dist/tools/fs/shell-read-check.d.ts +8 -2
  225. package/dist/tools/fs/shell-read-check.js +7 -7
  226. package/package.json +2 -2
  227. package/test/export-surface.snapshot.json +71 -73
  228. package/wire-changes/core-stores-sql@7.64.0.json +30 -0
  229. package/wire-changes/core-stores-sql@7.65.0.json +30 -0
  230. package/wire-changes/core@7.64.0.json +2653 -0
  231. package/wire-changes/core@7.65.0.json +1650 -0
  232. package/wire-changes/mods-kernel@7.64.0.json +30 -0
  233. package/wire-changes/mods-kernel@7.65.0.json +30 -0
  234. package/wire-changes/primitives@7.64.0.json +30 -0
  235. package/wire-changes/primitives@7.65.0.json +337 -0
  236. package/dist/core/memory-recall.d.ts +0 -208
  237. package/dist/core/memory-recall.js +0 -136
  238. package/dist/stores/file/memory-store.d.ts +0 -124
  239. package/dist/stores/file/memory-store.js +0 -353
@@ -4,6 +4,8 @@ import { egressText } from "./untrusted-egress.js";
4
4
  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
+ import { deliverEngineNotice } from "./engine-notice.js";
8
+ import { sameOccupant } from "../engine/session/repo-utils.js";
7
9
  export const TASK_NOTIFICATION_TERMINAL_STATUSES = Object.freeze(["completed", "failed", "killed", "cancelled"]);
8
10
  export const NOTIFICATION_INJECTION_OUTCOMES = Object.freeze(["queued", "parked", "parked_durably", "dropped_duplicate", "refused"]);
9
11
  export function isNotificationInjectionOutcome(value) {
@@ -163,6 +165,27 @@ export const MAX_PENDING_EVENTS_PER_TASK = 50;
163
165
  export const MAX_PENDING_EVENTS_PER_SESSION = 200;
164
166
  export const MAX_PENDING_SESSIONS = 100;
165
167
  export const MAX_SESSION_BOX_BINDINGS = 4096;
168
+ export function sessionAddressOf(leg) {
169
+ return { sessionId: leg.sessionId, occupant: leg.sessionIncarnation, ...(leg.sessionIncarnationUnread === true ? { unread: true } : {}) };
170
+ }
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) {
176
+ return {
177
+ code: "delegation.delivery_discarded",
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`,
179
+ detail: {
180
+ taskId: delivery.taskId,
181
+ taskType: delivery.taskType,
182
+ sessionId: address.sessionId,
183
+ path,
184
+ addressed: sameOccupant(address.occupant, undefined) ? "unknown" : "known",
185
+ current: sameOccupant(current, undefined) ? "unknown" : "known",
186
+ },
187
+ };
188
+ }
166
189
  export const HANDBACK_STATES = Object.freeze(["send", "flagged", "withheld"]);
167
190
  export function handbackStateOf(facts) {
168
191
  if (facts.warning !== undefined)
@@ -285,12 +308,12 @@ function malformedFacet(f) {
285
308
  }
286
309
  return undefined;
287
310
  }
288
- export function engineFrameRecordOf(payload, priority, box) {
311
+ export function engineFrameRecordOf(payload, priority, to) {
289
312
  return {
290
313
  id: taskNotificationDedupKey(payload),
291
314
  content: encodeEngineFrame(payload, priority),
292
315
  sentAt: Date.now(),
293
- peerMeta: { fromRoot: box.sessionId, kind: "engine_frame" },
316
+ peerMeta: { fromRoot: to.sessionId, kind: "engine_frame", ...(to.occupant !== undefined ? { occupant: to.occupant } : {}) },
294
317
  };
295
318
  }
296
319
  const MAX_TOMBSTONES = 5_000;
@@ -426,62 +449,148 @@ export function createLiveNotificationLane(seat) {
426
449
  }
427
450
  export class SessionLiveNotificationLanes {
428
451
  lanes = new Map();
429
- register(sessionId, lane) {
430
- const existing = this.lanes.get(sessionId);
452
+ register(address, lane) {
453
+ if (address.unread === true)
454
+ return;
455
+ const existing = this.lanes.get(address.sessionId);
456
+ const seat = { occupant: address.occupant, lane };
431
457
  if (existing === undefined)
432
- this.lanes.set(sessionId, [lane]);
433
- else if (!existing.includes(lane))
434
- existing.push(lane);
458
+ this.lanes.set(address.sessionId, [seat]);
459
+ else if (!existing.some((s) => s.lane === lane))
460
+ existing.push(seat);
435
461
  }
436
- unregister(sessionId, lane) {
437
- const existing = this.lanes.get(sessionId);
462
+ unregister(address, lane) {
463
+ const existing = this.lanes.get(address.sessionId);
438
464
  if (existing === undefined)
439
465
  return;
440
- const at = existing.indexOf(lane);
466
+ const at = existing.findIndex((s) => s.lane === lane);
441
467
  if (at !== -1)
442
468
  existing.splice(at, 1);
443
469
  if (existing.length === 0)
444
- this.lanes.delete(sessionId);
470
+ this.lanes.delete(address.sessionId);
445
471
  }
446
- deliver(sessionId, payload, priority, opts) {
447
- const existing = this.lanes.get(sessionId);
472
+ deliver(address, payload, priority, opts) {
473
+ const existing = this.lanes.get(address.sessionId);
448
474
  if (existing === undefined)
449
475
  return "unavailable";
450
476
  for (let i = existing.length - 1; i >= 0; i -= 1) {
451
- const outcome = existing[i](payload, priority, opts?.onDisposition);
477
+ const seat = existing[i];
478
+ if (!sameOccupant(seat.occupant, address.occupant))
479
+ continue;
480
+ const outcome = seat.lane(payload, priority, opts?.onDisposition);
452
481
  if (outcome !== "unavailable")
453
482
  return outcome;
454
483
  }
455
484
  return "unavailable";
456
485
  }
486
+ holds(address) {
487
+ return this.lanes.get(address.sessionId)?.some((s) => sameOccupant(s.occupant, address.occupant)) === true;
488
+ }
457
489
  get size() {
458
490
  return this.lanes.size;
459
491
  }
460
492
  }
493
+ function parksDurably(payload, box) {
494
+ return payload.agentMessage !== undefined || (box.engineFrames === true && isEngineFrameParkable(payload));
495
+ }
496
+ function keysOf(held, address) {
497
+ const entry = held.get(address.sessionId);
498
+ return entry !== undefined && sameOccupant(entry.occupant, address.occupant) ? entry.keys : undefined;
499
+ }
500
+ function addOccupantKey(held, address, dedupKey) {
501
+ let mine = keysOf(held, address);
502
+ if (mine === undefined) {
503
+ held.delete(address.sessionId);
504
+ if (held.size >= MAX_PENDING_SESSIONS) {
505
+ const oldest = held.keys().next().value;
506
+ if (oldest !== undefined)
507
+ held.delete(oldest);
508
+ }
509
+ mine = new Set();
510
+ held.set(address.sessionId, { occupant: address.occupant, keys: mine });
511
+ }
512
+ mine.add(dedupKey);
513
+ if (mine.size > MAX_PENDING_EVENTS_PER_SESSION) {
514
+ for (const k of mine) {
515
+ mine.delete(k);
516
+ if (mine.size <= MAX_PENDING_EVENTS_PER_SESSION)
517
+ break;
518
+ }
519
+ }
520
+ }
461
521
  export class PendingSessionNotifications {
462
522
  sessions = new Map();
523
+ noticeSeat;
524
+ constructor(seats) {
525
+ this.noticeSeat = seats?.onNotice ?? (() => undefined);
526
+ }
463
527
  liveLanes = new SessionLiveNotificationLanes();
464
528
  droppedSessions = 0;
465
529
  evictedSessions = new Map();
466
530
  unattributedDrops = 0;
467
- sessionBoxes = new Map();
468
- bindSessionBox(sessionId, box) {
469
- this.sessionBoxes.delete(sessionId);
470
- if (box === undefined)
531
+ seats = new Map();
532
+ admit(address, box) {
533
+ if (address.unread === true)
471
534
  return;
472
- this.sessionBoxes.set(sessionId, box);
473
- while (this.sessionBoxes.size > MAX_SESSION_BOX_BINDINGS) {
474
- const oldest = this.sessionBoxes.keys().next().value;
475
- if (oldest === undefined)
535
+ this.seats.delete(address.sessionId);
536
+ this.seats.set(address.sessionId, { occupant: address.occupant, ...(box !== undefined ? { box } : {}) });
537
+ for (const id of this.seats.keys()) {
538
+ if (this.seats.size <= MAX_SESSION_BOX_BINDINGS)
476
539
  break;
477
- this.sessionBoxes.delete(oldest);
540
+ if (!this.sessions.has(id))
541
+ this.seats.delete(id);
478
542
  }
543
+ const parked = this.sessions.get(address.sessionId);
544
+ if (parked !== undefined && !sameOccupant(parked.occupant, address.occupant))
545
+ this.discardRecord(address.sessionId, parked, address.occupant);
546
+ for (const held of [this.evictedSessions, this.routed, this.durable]) {
547
+ const entry = held.get(address.sessionId);
548
+ if (entry !== undefined && !sameOccupant(entry.occupant, address.occupant))
549
+ held.delete(address.sessionId);
550
+ }
551
+ }
552
+ sessionBoxFor(address) {
553
+ const seat = this.seats.get(address.sessionId);
554
+ return seat !== undefined && sameOccupant(seat.occupant, address.occupant) ? seat.box : undefined;
555
+ }
556
+ discardsStale(address, payload) {
557
+ const stale = this.staleAgainst(address);
558
+ if (stale === undefined)
559
+ return false;
560
+ const { seat } = stale;
561
+ const current = { sessionId: address.sessionId, occupant: seat?.occupant };
562
+ const path = seat !== undefined && this.liveLanes.holds(current) ? "live" : seat?.box !== undefined && parksDurably(payload, seat.box) ? "box" : "drain";
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");
571
+ return true;
479
572
  }
480
- sessionBoxFor(sessionId) {
481
- return this.sessionBoxes.get(sessionId);
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 };
482
578
  }
483
- settleBoxDebts(sessionId, signal) {
484
- const owed = this.sessions.get(sessionId)?.boxDebts;
579
+ announceDiscard(address, current, delivery, path) {
580
+ deliverEngineNotice(this.noticeSeat(), deliveryDiscardedNotice(address, current, delivery, path));
581
+ }
582
+ discardRecord(sessionId, record, current) {
583
+ if (this.sessions.get(sessionId) === record)
584
+ this.sessions.delete(sessionId);
585
+ for (const n of record.items)
586
+ this.announceDiscard({ sessionId, occupant: record.occupant }, current, frameDelivery(n), "drain");
587
+ }
588
+ recordOf(address) {
589
+ const s = this.sessions.get(address.sessionId);
590
+ return s !== undefined && sameOccupant(s.occupant, address.occupant) ? s : undefined;
591
+ }
592
+ settleBoxDebts(address, signal) {
593
+ const owed = this.recordOf(address)?.boxDebts;
485
594
  if (owed === undefined || owed.size === 0)
486
595
  return undefined;
487
596
  const debts = [...owed];
@@ -489,7 +598,7 @@ export class PendingSessionNotifications {
489
598
  for (const [copy, debt] of debts) {
490
599
  if (signal?.aborted === true)
491
600
  return;
492
- await this.settleBoxDebt(sessionId, copy, debt);
601
+ await this.settleBoxDebt(address, copy, debt);
493
602
  }
494
603
  })();
495
604
  }
@@ -504,11 +613,12 @@ export class PendingSessionNotifications {
504
613
  if (p !== undefined)
505
614
  tiers.set(n, p);
506
615
  }
507
- this.sessions.set(sessionId, { items: owing, dropped: new Map(), keys: new Set(owing.map((n) => taskNotificationDedupKey(n))), priorities: tiers, boxDebts: debts });
616
+ this.sessions.set(sessionId, { occupant: s.occupant, items: owing, dropped: new Map(), keys: new Set(owing.map((n) => taskNotificationDedupKey(n))), priorities: tiers, boxDebts: debts });
508
617
  const rest = s.items.filter((n) => !debts.has(n));
509
618
  return rest.length === 0 && s.dropped.size === 0 ? undefined : { ...s, items: rest };
510
619
  }
511
- async settleBoxDebt(sessionId, copy, debt) {
620
+ async settleBoxDebt(address, copy, debt) {
621
+ const sessionId = address.sessionId;
512
622
  let answered = false;
513
623
  try {
514
624
  await debt.box.mailbox.append(debt.box.scope, debt.box.handle, debt.record);
@@ -521,7 +631,7 @@ export class PendingSessionNotifications {
521
631
  catch {
522
632
  }
523
633
  }
524
- const s = this.sessions.get(sessionId);
634
+ const s = this.recordOf(address);
525
635
  if (s?.boxDebts?.get(copy) !== debt)
526
636
  return;
527
637
  s.boxDebts.delete(copy);
@@ -532,12 +642,19 @@ export class PendingSessionNotifications {
532
642
  const key = taskNotificationDedupKey(copy);
533
643
  s.keys.delete(key);
534
644
  s.priorities?.delete(copy);
535
- this.noteDurablePark(sessionId, key);
645
+ this.noteDurablePark(address, key);
536
646
  if (s.items.length === 0 && s.dropped.size === 0)
537
647
  this.sessions.delete(sessionId);
538
648
  }
539
- pend(sessionId, n, priority, debt) {
649
+ pend(address, n, priority, debt) {
650
+ if (this.discardsStale(address, n))
651
+ return false;
652
+ const sessionId = address.sessionId;
540
653
  let s = this.sessions.get(sessionId);
654
+ if (s !== undefined && !sameOccupant(s.occupant, address.occupant)) {
655
+ this.discardRecord(sessionId, s, address.occupant);
656
+ s = undefined;
657
+ }
541
658
  if (s === undefined) {
542
659
  if (this.sessions.size >= MAX_PENDING_SESSIONS) {
543
660
  const oldest = this.sessions.keys().next().value;
@@ -550,20 +667,22 @@ export class PendingSessionNotifications {
550
667
  if (!this.evictedSessions.has(oldest) && this.evictedSessions.size >= MAX_TOMBSTONES) {
551
668
  const oldestTomb = this.evictedSessions.keys().next().value;
552
669
  if (oldestTomb !== undefined) {
553
- this.unattributedDrops += this.evictedSessions.get(oldestTomb) ?? 0;
670
+ this.unattributedDrops += this.evictedSessions.get(oldestTomb)?.count ?? 0;
554
671
  this.evictedSessions.delete(oldestTomb);
555
672
  }
556
673
  }
557
- this.evictedSessions.set(oldest, (this.evictedSessions.get(oldest) ?? 0) + lost);
674
+ const tomb = this.evictedSessions.get(oldest);
675
+ const occupant = victim?.occupant;
676
+ this.evictedSessions.set(oldest, { occupant, count: (tomb !== undefined && sameOccupant(tomb.occupant, occupant) ? tomb.count : 0) + lost });
558
677
  }
559
678
  }
560
679
  }
561
- s = { items: [], dropped: new Map(), keys: new Set(), priorities: new Map() };
680
+ s = { occupant: address.occupant, items: [], dropped: new Map(), keys: new Set(), priorities: new Map() };
562
681
  this.sessions.set(sessionId, s);
563
682
  }
564
683
  const key = taskNotificationDedupKey(n);
565
684
  if (s.keys.has(key))
566
- return;
685
+ return true;
567
686
  s.keys.add(key);
568
687
  s.items.push(n);
569
688
  if (priority !== undefined)
@@ -579,10 +698,17 @@ export class PendingSessionNotifications {
579
698
  evictOldest(s, (i) => taskNotificationLaneKey(i) === lane);
580
699
  if (s.items.length > MAX_PENDING_EVENTS_PER_SESSION)
581
700
  evictOldest(s, () => true);
701
+ return true;
582
702
  }
583
- drain(sessionId) {
703
+ drain(address) {
704
+ if (address.unread === true)
705
+ return undefined;
706
+ const sessionId = address.sessionId;
584
707
  this.routed.delete(sessionId);
585
- const parked = this.sessions.get(sessionId);
708
+ const held = this.sessions.get(sessionId);
709
+ if (held !== undefined && !sameOccupant(held.occupant, address.occupant))
710
+ this.discardRecord(sessionId, held, address.occupant);
711
+ const parked = this.recordOf(address);
586
712
  if (parked !== undefined)
587
713
  this.sessions.delete(sessionId);
588
714
  const s = parked !== undefined ? this.keepBackOwing(sessionId, parked) : undefined;
@@ -593,10 +719,12 @@ export class PendingSessionNotifications {
593
719
  };
594
720
  s.items = [...s.items].sort((a, b) => rank(a) - rank(b));
595
721
  }
596
- const tomb = this.evictedSessions.get(sessionId);
722
+ const tombstone = this.evictedSessions.get(sessionId);
723
+ const tomb = tombstone !== undefined && sameOccupant(tombstone.occupant, address.occupant) ? tombstone.count : undefined;
724
+ if (tombstone !== undefined)
725
+ this.evictedSessions.delete(sessionId);
597
726
  if (tomb === undefined && this.unattributedDrops === 0)
598
727
  return s;
599
- this.evictedSessions.delete(sessionId);
600
728
  const carried = this.unattributedDrops;
601
729
  this.unattributedDrops = 0;
602
730
  const out = s ?? { items: [], dropped: new Map() };
@@ -604,57 +732,23 @@ export class PendingSessionNotifications {
604
732
  return out;
605
733
  }
606
734
  routed = new Map();
607
- holdsKey(sessionId, dedupKey) {
608
- return this.sessions.get(sessionId)?.keys.has(dedupKey) === true || this.routed.get(sessionId)?.has(dedupKey) === true || this.durable.get(sessionId)?.has(dedupKey) === true;
735
+ holdsKey(address, dedupKey) {
736
+ return this.recordOf(address)?.keys.has(dedupKey) === true || keysOf(this.routed, address)?.has(dedupKey) === true || keysOf(this.durable, address)?.has(dedupKey) === true;
609
737
  }
610
738
  durable = new Map();
611
- noteDurablePark(sessionId, dedupKey) {
612
- let mine = this.durable.get(sessionId);
613
- if (mine === undefined) {
614
- if (this.durable.size >= MAX_PENDING_SESSIONS) {
615
- const oldest = this.durable.keys().next().value;
616
- if (oldest !== undefined)
617
- this.durable.delete(oldest);
618
- }
619
- mine = new Set();
620
- this.durable.set(sessionId, mine);
621
- }
622
- mine.add(dedupKey);
623
- if (mine.size > MAX_PENDING_EVENTS_PER_SESSION) {
624
- for (const k of mine) {
625
- mine.delete(k);
626
- if (mine.size <= MAX_PENDING_EVENTS_PER_SESSION)
627
- break;
628
- }
629
- }
739
+ noteDurablePark(address, dedupKey) {
740
+ addOccupantKey(this.durable, address, dedupKey);
630
741
  }
631
- forgetDurablePark(sessionId, dedupKey) {
632
- const mine = this.durable.get(sessionId);
742
+ forgetDurablePark(address, dedupKey) {
743
+ const mine = keysOf(this.durable, address);
633
744
  if (mine === undefined)
634
745
  return;
635
746
  mine.delete(dedupKey);
636
747
  if (mine.size === 0)
637
- this.durable.delete(sessionId);
638
- }
639
- markDelivered(sessionId, dedupKey) {
640
- let mine = this.routed.get(sessionId);
641
- if (mine === undefined) {
642
- if (this.routed.size >= MAX_PENDING_SESSIONS) {
643
- const oldest = this.routed.keys().next().value;
644
- if (oldest !== undefined)
645
- this.routed.delete(oldest);
646
- }
647
- mine = new Set();
648
- this.routed.set(sessionId, mine);
649
- }
650
- mine.add(dedupKey);
651
- if (mine.size > MAX_PENDING_EVENTS_PER_SESSION) {
652
- for (const k of mine) {
653
- mine.delete(k);
654
- if (mine.size <= MAX_PENDING_EVENTS_PER_SESSION)
655
- break;
656
- }
657
- }
748
+ this.durable.delete(address.sessionId);
749
+ }
750
+ markDelivered(address, dedupKey) {
751
+ addOccupantKey(this.routed, address, dedupKey);
658
752
  }
659
753
  get size() {
660
754
  return this.sessions.size;
@@ -678,20 +772,23 @@ export class DurableAppendObligations {
678
772
  await Promise.allSettled([...this.inFlight]);
679
773
  }
680
774
  }
681
- export function routeOrParkNotification(store, sessionId, payload, priority, onDisposition) {
775
+ export function routeOrParkNotification(store, address, payload, priority, onDisposition) {
776
+ if (store.discardsStale(address, payload)) {
777
+ onDisposition?.("refused");
778
+ return;
779
+ }
682
780
  const dedupKey = taskNotificationDedupKey(payload);
683
- if (store.holdsKey(sessionId, dedupKey)) {
781
+ if (store.holdsKey(address, dedupKey)) {
684
782
  onDisposition?.("parked");
685
783
  return;
686
784
  }
687
- const routed = store.liveLanes.deliver(sessionId, payload, priority, { ...(onDisposition !== undefined ? { onDisposition } : {}) });
785
+ const routed = store.liveLanes.deliver(address, payload, priority, { ...(onDisposition !== undefined ? { onDisposition } : {}) });
688
786
  if (routed === "unavailable") {
689
- const box = store.sessionBoxFor(sessionId);
787
+ const box = store.sessionBoxFor(address);
690
788
  const carrier = payload.agentMessage;
691
- const durable = box !== undefined && (carrier !== undefined || (box.engineFrames === true && isEngineFrameParkable(payload)));
692
- if (box !== undefined && durable) {
693
- store.noteDurablePark(sessionId, dedupKey);
694
- const record = carrier !== undefined ? sessionBoxRecordOf({ ...payload, agentMessage: carrier }, box) : engineFrameRecordOf(payload, priority, box);
789
+ if (box !== undefined && parksDurably(payload, box)) {
790
+ store.noteDurablePark(address, dedupKey);
791
+ const record = carrier !== undefined ? sessionBoxRecordOf({ ...payload, agentMessage: carrier }, address) : engineFrameRecordOf(payload, priority, address);
695
792
  const ask = () => {
696
793
  try {
697
794
  return Promise.resolve(box.mailbox.append(box.scope, box.handle, record));
@@ -709,21 +806,21 @@ export function routeOrParkNotification(store, sessionId, payload, priority, onD
709
806
  return ask();
710
807
  });
711
808
  const settled = appended.then(() => onDisposition?.("parked_durably"), () => {
712
- store.forgetDurablePark(sessionId, dedupKey);
713
- store.pend(sessionId, payload, priority, { box, record });
714
- onDisposition?.("parked");
809
+ store.forgetDurablePark(address, dedupKey);
810
+ const parked = store.pend(address, payload, priority, { box, record });
811
+ onDisposition?.(parked ? "parked" : "refused");
715
812
  });
716
813
  DurableAppendObligations.current()?.track(settled);
717
814
  return;
718
815
  }
719
- store.pend(sessionId, payload, priority);
720
- onDisposition?.("parked");
816
+ const parked = store.pend(address, payload, priority);
817
+ onDisposition?.(parked ? "parked" : "refused");
721
818
  }
722
819
  else if (routed !== "taken") {
723
820
  onDisposition?.("queued");
724
821
  }
725
822
  }
726
- export function sessionBoxRecordOf(payload, box) {
823
+ export function sessionBoxRecordOf(payload, to) {
727
824
  const peer = payload.peer;
728
825
  return {
729
826
  id: taskNotificationDedupKey(payload),
@@ -734,8 +831,9 @@ export function sessionBoxRecordOf(payload, box) {
734
831
  peerMeta: {
735
832
  ...(peer?.fromSession !== undefined ? { fromSession: peer.fromSession } : {}),
736
833
  ...(peer?.senderKey !== undefined ? { senderKey: peer.senderKey } : {}),
737
- fromRoot: box.sessionId,
834
+ fromRoot: to.sessionId,
738
835
  kind: "peer_message",
836
+ ...(to.occupant !== undefined ? { occupant: to.occupant } : {}),
739
837
  },
740
838
  };
741
839
  }
@@ -1,5 +1,6 @@
1
1
  import { type BackgroundAgentRecord, type BackgroundAgentStore } from "./background-agent-store.js";
2
2
  import { type StopSource, type TaskAccess, type TaskRetrievalStatus, type UnifiedTaskOutput, type UnifiedTaskResult, type BackgroundAgentTaskHandle, type ChildSessionStore, type RegisteredTaskHandle, type DurableAgentCore, type ParkedClaimTicket, type RegisterBackgroundAgentInput, type LandedAgentTerminal } from "./task-registry-shared.js";
3
+ import type { ExtensionRequester } from "./task-event.js";
3
4
  import { type AgentState } from "./agent-state.js";
4
5
  import type { CheckpointSeat } from "./checkpoint-seat.js";
5
6
  /**
@@ -19,6 +20,8 @@ export declare function activeDelegationHandlesLane(core: DurableAgentCore, scop
19
20
  export interface DelegationOccupant {
20
21
  readonly id: string;
21
22
  readonly name: string;
23
+ /** The extension that started the row, when one did (the row's `requestedBy`); absent for every other row. */
24
+ readonly requestedBy?: ExtensionRequester;
22
25
  readonly reachable: boolean;
23
26
  }
24
27
  /** The rows {@link activeDelegationHandlesLane} counts, with the name each is addressed by — the one selection, read in the same
@@ -545,6 +548,14 @@ export interface AgentPollDetailsInput {
545
548
  * `agentState` when given; the poll arms always give it, a serving layer may omit it. */
546
549
  agentState?: AgentState;
547
550
  }
551
+ /**
552
+ * The ONE reading of a delegation outcome's tool-result error bit: a delegation whose child FAILED produced no usable result,
553
+ * so the tool result that reports it is an error (`isError: true`) — on the synchronous card, the fork card, the live poll
554
+ * and the durable poll alike, so a hook or a host reading the bit never sees `false` beside `status: failed`. Every other
555
+ * outcome word answers `false` here: a completed, killed or still-running delegation is data, and the refusals that never
556
+ * start a child (a refused call, a held park, an unavailable isolation) are their own constructors, not outcomes.
557
+ */
558
+ export declare function agentOutcomeIsError(status: string): boolean;
548
559
  /** PUBLIC (see the doc above): a serving layer that renders its own protocol projection of a row
549
560
  * builds the structured facts HERE, so the status gates and the untrusted-text fencing apply to it
550
561
  * too — a third literal is exactly the drift this builder exists to prevent. Input only; it reads no
@@ -7,6 +7,7 @@ import { delimitUntrusted } from "./untrusted-text.js";
7
7
  import { boundedRedactedSummary } from "./untrusted-egress.js";
8
8
  import { mintCompletionId, commitCompletionIdIfEmpty, clipTaskOutput, assertOwnership, sleepPollStep, alreadyTerminalStopNote, canAccess, normalizeAgentName, engineAgentName, chosenAgentName, DURABLE_AGENT_HEARTBEAT_MS, DURABLE_AGENT_HANDLE_RE, BG_AGENT_REAP_STOP_ERROR, } from "./task-registry-shared.js";
9
9
  import { thrownLabel } from "./thrown-value.js";
10
+ import { readExtensionRequester } from "./extension-requester.js";
10
11
  import { closestName } from "./closest-name.js";
11
12
  import { agentStateSourceOfHandle, agentStateSummary, readAgentState } from "./agent-state.js";
12
13
  export function activeDelegationHandlesLane(core, scope, rootSessionId) {
@@ -25,7 +26,8 @@ export function activeDelegationOccupantsLane(core, scope, rootSessionId, caller
25
26
  const root = bh.rootSessionId ?? bh.parentSessionId ?? (bh.sessionScoped ? bh.owner : undefined);
26
27
  if (root !== rootSessionId)
27
28
  continue;
28
- out.push({ id: h.id, name: bh.name, reachable: caller !== undefined && canAccess(h, { ...caller, scope }) });
29
+ const requestedBy = readExtensionRequester(bh.requestedBy);
30
+ out.push({ id: h.id, name: bh.name, ...(requestedBy !== undefined ? { requestedBy } : {}), reachable: caller !== undefined && canAccess(h, { ...caller, scope }) });
29
31
  }
30
32
  return out;
31
33
  }
@@ -395,6 +397,7 @@ export function registerBackgroundAgentLane(core, input) {
395
397
  throw new Error(`TaskRegistry: background-agent name must be a non-empty string (got ${JSON.stringify(input.name)}); omit it to take the derived one`);
396
398
  }
397
399
  const name = input.name ?? engineAgentName(id);
400
+ const requestedBy = readExtensionRequester(input.requestedBy);
398
401
  core.handles.set(id, {
399
402
  id,
400
403
  type: "background_agent",
@@ -406,6 +409,7 @@ export function registerBackgroundAgentLane(core, input) {
406
409
  ...(input.description !== undefined ? { description: input.description } : {}),
407
410
  name,
408
411
  ...(input.agentType !== undefined ? { agentType: input.agentType } : {}),
412
+ ...(requestedBy !== undefined ? { requestedBy } : {}),
409
413
  ...(input.parentTaskId !== undefined ? { parentTaskId: input.parentTaskId } : {}),
410
414
  ...(input.parentSessionId !== undefined ? { parentSessionId: input.parentSessionId } : {}),
411
415
  ...(input.rootSessionId !== undefined ? { rootSessionId: input.rootSessionId } : {}),
@@ -446,9 +450,11 @@ export function registerBackgroundAgentLane(core, input) {
446
450
  sessionScoped: input.sessionScoped === true,
447
451
  ...(input.parentSessionId !== undefined ? { parentSessionId: input.parentSessionId } : {}),
448
452
  ...(input.rootSessionId !== undefined ? { rootSessionId: input.rootSessionId } : {}),
453
+ ...(input.rootSessionId !== undefined && input.rootSessionIncarnation !== undefined ? { rootSessionIncarnation: input.rootSessionIncarnation } : {}),
449
454
  ...(input.parentTaskId !== undefined ? { parentTaskId: input.parentTaskId } : {}),
450
455
  name,
451
456
  ...(input.agentType !== undefined ? { agentType: input.agentType } : {}),
457
+ ...(requestedBy !== undefined ? { requestedBy } : {}),
452
458
  ...(input.description !== undefined ? { description: input.description } : {}),
453
459
  ...(input.model !== undefined ? { model: input.model } : {}),
454
460
  ...(input.policyFloor !== undefined ? { policyFloor: input.policyFloor } : {}),
@@ -1331,6 +1337,9 @@ export function notFoundRunningAgentsTail(footer) {
1331
1337
  return ((footer.named.length > 0 ? `. Running named agents: ${footer.named.join(", ")}` : "") +
1332
1338
  (footer.background.length > 0 ? `. Running background agents: ${footer.background.join(", ")}` : ""));
1333
1339
  }
1340
+ export function agentOutcomeIsError(status) {
1341
+ return status === "failed";
1342
+ }
1334
1343
  export function buildAgentPollDetails(input) {
1335
1344
  const failed = input.status === "failed";
1336
1345
  return {
@@ -1387,7 +1396,7 @@ ${clipTaskOutput(row.finalOutputFull ?? row.finalOutput)}` : "(no result text)"}
1387
1396
  ...(row.completionId !== undefined ? { completionId: row.completionId } : {}),
1388
1397
  ...(agentState !== undefined ? { agentState } : {}),
1389
1398
  }),
1390
- ...(row.status === "failed" ? { isError: true } : {}),
1399
+ ...(agentOutcomeIsError(row.status) ? { isError: true } : {}),
1391
1400
  };
1392
1401
  }
1393
1402
  export async function pollBackgroundAgentLane(handle, deadline, signal, checkpointSeat) {
@@ -1458,7 +1467,7 @@ ${resultText}` : "(no result text)"}`;
1458
1467
  ...(snap.completionId !== undefined ? { completionId: snap.completionId } : {}),
1459
1468
  agentState,
1460
1469
  }),
1461
- ...(snap.status === "failed" ? { isError: true } : {}),
1470
+ ...(agentOutcomeIsError(snap.status) ? { isError: true } : {}),
1462
1471
  };
1463
1472
  }
1464
1473
  export async function stopBackgroundAgentLane(core, handle) {
@@ -4,6 +4,7 @@ import { type WorkflowRunStore } from "./workflow-run-store.js";
4
4
  import type { BackgroundAgentRecord, BackgroundAgentStore } from "./background-agent-store.js";
5
5
  import type { WorkflowHandle, WorkflowRun } from "../orchestration/workflow.js";
6
6
  import type { TaskNotificationPayload } from "./task-notification.js";
7
+ import type { ExtensionRequester } from "./task-event.js";
7
8
  import type { TaskArtifactSeat } from "./tool-result-store.js";
8
9
  import type { AssertAllKeysHandled } from "./ask-origin.js";
9
10
  export type SemaTaskType = "background_bash" | "workflow" | "background_agent" | "monitor";
@@ -271,6 +272,8 @@ export interface BackgroundAgentTaskHandle extends SemaTaskHandle {
271
272
  parentTaskId?: string;
272
273
  parentSessionId?: string;
273
274
  rootSessionId?: string;
275
+ /** Who started the agent when an extension did ({@link RegisterBackgroundAgentInput.requestedBy}); absent otherwise. */
276
+ requestedBy?: ExtensionRequester;
274
277
  /** design/151 S1a — the child's store session id (transcript/resume anchor), bound once the child
275
278
  * session is minted ({@link TaskRegistry.bindBackgroundAgentSession}) and removed — together with the
276
279
  * durable record's copy — by the successful release of that session
@@ -932,6 +935,10 @@ export interface RegisterBackgroundAgentInput extends TaskAccess {
932
935
  /** the RESOLVED subagent type ("general-purpose"/"fork"/a roster name), persisted
933
936
  * so a REVIVE cycle's observer frames can reproduce the row's TYPE column (never the description). */
934
937
  agentType?: string;
938
+ /** Who started this agent when an extension did: the extension, by its registration name (`$.agent.spawn`) — persisted on the row,
939
+ * so a revival keeps the row's origin. ABSENT = not an extension's spawn (the model's own, the host's): the one reading, with no
940
+ * word for either of those. A display and audit fact only — it decides nothing. */
941
+ requestedBy?: ExtensionRequester;
935
942
  /** the spawn frame's parent linkage, persisted so a REVIVE cycle's spawn frame nests the
936
943
  * revived row exactly like the first spawn did. The caller passes the SAME values it emitted on the
937
944
  * original frame (parentTaskId already-clamped there; parentSessionId always-on). */
@@ -941,6 +948,10 @@ export interface RegisterBackgroundAgentInput extends TaskAccess {
941
948
  * internals chain; equals parentSessionId at depth 1). Persisted on the handle, the durable row
942
949
  * and the roster so recovery faces enumerate the whole tree under the root without alias walks. */
943
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;
944
955
  /** design/151 S3b — the revival lookup key (CC meta-sidecar shape): the model RECORD KEY,
945
956
  * persisted on the durable row so a tier-3 revival rebuilds the spec the way a fresh
946
957
  * named-teammate spawn would. A lookup key only, never a serialized spec. `model` is NOT the