maka-agent 0.2.0-dev.23.20260906 → 0.2.0-dev.25.20260908

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 (215) hide show
  1. package/README.md +38 -19
  2. package/README.zh-CN.md +34 -19
  3. package/dist/acp/maka-acp-agent.js +2 -1
  4. package/dist/acp/session-configuration.js +143 -0
  5. package/dist/acp/session-registry.js +90 -4
  6. package/dist/cli-core.js +2 -0
  7. package/dist/pi-transcript-tools.js +6 -0
  8. package/dist/pi-transcript.js +5 -12
  9. package/dist/pi-tui-layout.js +56 -10
  10. package/dist/pi-tui-pickers.js +102 -1
  11. package/dist/pi-tui-runner.js +230 -46
  12. package/dist/pi-tui-todo.js +221 -0
  13. package/dist/pi-tui-transcript-viewer.js +134 -7
  14. package/dist/runtime-host-cli-context.js +224 -78
  15. package/dist/runtime-host-cli-installation.js +8 -2
  16. package/dist/runtime-host-cli.js +31 -1
  17. package/dist/runtime-host-handoff-surface.js +106 -0
  18. package/dist/runtime-host-installed-update-bootstrap.js +13 -0
  19. package/dist/runtime-host-installed-update-coordinator.js +33 -0
  20. package/dist/runtime-host-lifecycle-transaction.js +9 -1
  21. package/dist/runtime-host-local-handoff.js +48 -5
  22. package/dist/runtime-host-local-managed-activation.js +84 -0
  23. package/dist/runtime-host-local-source-retirement.js +18 -2
  24. package/dist/runtime-host-managed-lifecycle-manager.js +1 -0
  25. package/dist/runtime-host-operator-retirement.js +50 -0
  26. package/dist/runtime-host-service-manager.js +3 -3
  27. package/dist/runtime-host-session-channel.js +13 -0
  28. package/dist/runtime-host-session-driver.js +46 -26
  29. package/dist/runtime-host-session-update.js +62 -0
  30. package/dist/runtime-host-tui-command.js +38 -73
  31. package/dist/runtime-host-tui-context.js +1 -0
  32. package/dist/runtime-host-tui-owner.js +226 -0
  33. package/dist/tui-copy-catalog.js +219 -6
  34. package/dist/tui-host-owner-copy.js +24 -0
  35. package/native/runtime-host-windows-task-launcher/prebuilds/win32-x64/maka-runtime-host-task-launcher.exe +0 -0
  36. package/node_modules/@maka/core/dist/agent-run.js +1 -0
  37. package/node_modules/@maka/core/dist/attachments.js +3 -0
  38. package/node_modules/@maka/core/dist/canonical-json.js +27 -0
  39. package/node_modules/@maka/core/dist/canonical-runtime-event.js +3 -1
  40. package/node_modules/@maka/core/dist/capabilities.js +35 -0
  41. package/node_modules/@maka/core/dist/computer-use.js +0 -1
  42. package/node_modules/@maka/core/dist/display-redaction.js +18 -0
  43. package/node_modules/@maka/core/dist/llm-connections.js +13 -0
  44. package/node_modules/@maka/core/dist/model-call-attempt.js +2 -0
  45. package/node_modules/@maka/core/dist/model-failure.js +40 -0
  46. package/node_modules/@maka/core/dist/model-metadata.generated.js +4 -4
  47. package/node_modules/@maka/core/dist/model-metadata.js +7 -3
  48. package/node_modules/@maka/core/dist/model-web-search.js +5 -4
  49. package/node_modules/@maka/core/dist/provider-registry.js +45 -4
  50. package/node_modules/@maka/core/dist/record-schema.js +9 -2
  51. package/node_modules/@maka/core/dist/redaction.js +35 -0
  52. package/node_modules/@maka/core/dist/run-composition.js +77 -2
  53. package/node_modules/@maka/core/dist/runtime-boundary.js +31 -11
  54. package/node_modules/@maka/core/dist/runtime-event.js +37 -6
  55. package/node_modules/@maka/core/dist/runtime-handoff.js +98 -0
  56. package/node_modules/@maka/core/dist/runtime-invocation.js +1 -1
  57. package/node_modules/@maka/core/dist/runtime-logical-execution.js +112 -0
  58. package/node_modules/@maka/core/dist/session.js +84 -56
  59. package/node_modules/@maka/core/dist/slash-command-catalog.js +3 -0
  60. package/node_modules/@maka/core/dist/tool-result-archive-evidence.js +20 -0
  61. package/node_modules/@maka/core/dist/tool-result-record-schema.js +2 -1
  62. package/node_modules/@maka/core/dist/usage-record-schema.js +26 -35
  63. package/node_modules/@maka/core/package.json +5 -0
  64. package/node_modules/@maka/eval/dist/experiment-directory.js +4 -13
  65. package/node_modules/@maka/mcp/dist/index.js +131 -1
  66. package/node_modules/@maka/runtime/dist/agent-run-inspect.js +0 -13
  67. package/node_modules/@maka/runtime/dist/agent-run.js +351 -105
  68. package/node_modules/@maka/runtime/dist/ai-sdk-backend.js +29 -13
  69. package/node_modules/@maka/runtime/dist/ai-sdk-compaction.js +109 -34
  70. package/node_modules/@maka/runtime/dist/ai-sdk-turn.js +184 -183
  71. package/node_modules/@maka/runtime/dist/archive-read-tool.js +2 -2
  72. package/node_modules/@maka/runtime/dist/context-budget-helpers.js +0 -16
  73. package/node_modules/@maka/runtime/dist/context-budget.js +14 -9
  74. package/node_modules/@maka/runtime/dist/conversation-copy.js +158 -15
  75. package/node_modules/@maka/runtime/dist/github-copilot-oauth-enrollment.js +3 -3
  76. package/node_modules/@maka/runtime/dist/goal-continuation.js +36 -4
  77. package/node_modules/@maka/runtime/dist/history-compact-checkpoint.js +18 -9
  78. package/node_modules/@maka/runtime/dist/history-compact-summarizer.js +30 -22
  79. package/node_modules/@maka/runtime/dist/history-compaction.js +29 -4
  80. package/node_modules/@maka/runtime/dist/ledger-tool-result-archive-reader.js +174 -0
  81. package/node_modules/@maka/runtime/dist/mcp-tools.js +7 -2
  82. package/node_modules/@maka/runtime/dist/message-authority.js +9 -0
  83. package/node_modules/@maka/runtime/dist/model-adapter.js +19 -98
  84. package/node_modules/@maka/runtime/dist/model-factory.js +19 -81
  85. package/node_modules/@maka/runtime/dist/model-fetcher.js +49 -2
  86. package/node_modules/@maka/runtime/dist/model-history.js +0 -112
  87. package/node_modules/@maka/runtime/dist/model-runtime.js +85 -111
  88. package/node_modules/@maka/runtime/dist/native-web-search-tool.js +2 -1
  89. package/node_modules/@maka/runtime/dist/openai-codex-history-compactor.js +2 -2
  90. package/node_modules/@maka/runtime/dist/opencode-session-header.js +4 -2
  91. package/node_modules/@maka/runtime/dist/plugin-runtime.js +20 -10
  92. package/node_modules/@maka/runtime/dist/plugin-tool-service.js +205 -0
  93. package/node_modules/@maka/runtime/dist/provider-error-classification.js +84 -123
  94. package/node_modules/@maka/runtime/dist/provider-request-telemetry.js +76 -109
  95. package/node_modules/@maka/runtime/dist/request-shape.js +23 -0
  96. package/node_modules/@maka/runtime/dist/run-handoff-gate.js +97 -0
  97. package/node_modules/@maka/runtime/dist/runtime-event-backfill.js +83 -55
  98. package/node_modules/@maka/runtime/dist/runtime-event-read-model.js +121 -159
  99. package/node_modules/@maka/runtime/dist/runtime-kernel.js +157 -112
  100. package/node_modules/@maka/runtime/dist/runtime-ledger-repair.js +160 -79
  101. package/node_modules/@maka/runtime/dist/runtime-read-model.js +30 -89
  102. package/node_modules/@maka/runtime/dist/runtime-resume.js +80 -4
  103. package/node_modules/@maka/runtime/dist/session-event-runtime-mapper.js +5 -0
  104. package/node_modules/@maka/runtime/dist/session-manager.js +171 -288
  105. package/node_modules/@maka/runtime/dist/session-projection-helpers.js +0 -27
  106. package/node_modules/@maka/runtime/dist/stream-graph-coordinator.js +21 -0
  107. package/node_modules/@maka/runtime/dist/stream-graph-supervisor-tools.js +0 -5
  108. package/node_modules/@maka/runtime/dist/subscription-model-fetch.js +3 -4
  109. package/node_modules/@maka/runtime/dist/test-connection.js +16 -17
  110. package/node_modules/@maka/runtime/dist/tool-activation-identity.js +41 -0
  111. package/node_modules/@maka/runtime/dist/tool-availability.js +11 -1
  112. package/node_modules/@maka/runtime/dist/tool-result-archive-encoding.js +38 -0
  113. package/node_modules/@maka/runtime/dist/tool-result-archive-resource.js +63 -1
  114. package/node_modules/@maka/runtime/dist/tool-result-archive-transition.js +42 -12
  115. package/node_modules/@maka/runtime/dist/tool-result-archive.js +27 -4
  116. package/node_modules/@maka/runtime/dist/tool-runtime.js +3 -61
  117. package/node_modules/@maka/runtime/package.json +2 -0
  118. package/node_modules/@maka/runtime-host/dist/adapter/session-projector.js +35 -0
  119. package/node_modules/@maka/runtime-host/dist/client/connect-or-spawn.js +9 -1
  120. package/node_modules/@maka/runtime-host/dist/client/connection.js +3 -0
  121. package/node_modules/@maka/runtime-host/dist/client/host-handoff-copy.js +179 -0
  122. package/node_modules/@maka/runtime-host/dist/client/host-handoff.js +275 -0
  123. package/node_modules/@maka/runtime-host/dist/client/host-retirement.js +26 -5
  124. package/node_modules/@maka/runtime-host/dist/client/index.js +2 -0
  125. package/node_modules/@maka/runtime-host/dist/client/launcher.js +3 -0
  126. package/node_modules/@maka/runtime-host/dist/client/remote-compatibility-error.js +2 -0
  127. package/node_modules/@maka/runtime-host/dist/client/session-subscription.js +46 -5
  128. package/node_modules/@maka/runtime-host/dist/control/endpoint.js +1 -3
  129. package/node_modules/@maka/runtime-host/dist/node-error.js +22 -0
  130. package/node_modules/@maka/runtime-host/dist/operator/index.js +2 -1
  131. package/node_modules/@maka/runtime-host/dist/operator/managed-deployment.js +1 -3
  132. package/node_modules/@maka/runtime-host/dist/operator/retirement-cancellation.js +20 -0
  133. package/node_modules/@maka/runtime-host/dist/peer-mesh/limits.js +0 -1
  134. package/node_modules/@maka/runtime-host/dist/peer-mesh/model.js +1 -1
  135. package/node_modules/@maka/runtime-host/dist/peer-reachability/publisher.js +1 -3
  136. package/node_modules/@maka/runtime-host/dist/protocol/host-status.js +21 -12
  137. package/node_modules/@maka/runtime-host/dist/protocol/index.js +29 -1
  138. package/node_modules/@maka/runtime-host/dist/protocol/operations.js +1 -0
  139. package/node_modules/@maka/runtime-host/dist/protocol/plan.js +1 -0
  140. package/node_modules/@maka/runtime-host/dist/protocol/plugin-platform.js +27 -5
  141. package/node_modules/@maka/runtime-host/dist/protocol/project-catalog.js +2 -2
  142. package/node_modules/@maka/runtime-host/dist/protocol/session-continuity.js +40 -20
  143. package/node_modules/@maka/runtime-host/dist/protocol/session-transcript.js +0 -5
  144. package/node_modules/@maka/runtime-host/dist/protocol/session-turns.js +29 -58
  145. package/node_modules/@maka/runtime-host/dist/protocol/turn.js +11 -1
  146. package/node_modules/@maka/runtime-host/dist/protocol/workhub-coordination.js +31 -2
  147. package/node_modules/@maka/runtime-host/dist/server/access-credential-store.js +1 -0
  148. package/node_modules/@maka/runtime-host/dist/server/agent-graph-coordinator.js +0 -3
  149. package/node_modules/@maka/runtime-host/dist/server/canonical-turn-snapshot.js +19 -4
  150. package/node_modules/@maka/runtime-host/dist/server/connection-session.js +7 -6
  151. package/node_modules/@maka/runtime-host/dist/server/execution-artifacts.js +32 -32
  152. package/node_modules/@maka/runtime-host/dist/server/execution-composition.js +144 -33
  153. package/node_modules/@maka/runtime-host/dist/server/execution-model-authority.js +5 -5
  154. package/node_modules/@maka/runtime-host/dist/server/execution-model-composition.js +45 -16
  155. package/node_modules/@maka/runtime-host/dist/server/goal-coordinator.js +40 -1
  156. package/node_modules/@maka/runtime-host/dist/server/host-kernel.js +96 -17
  157. package/node_modules/@maka/runtime-host/dist/server/host-residency-registry.js +13 -7
  158. package/node_modules/@maka/runtime-host/dist/server/hosted-execution-admission-registry.js +3 -1
  159. package/node_modules/@maka/runtime-host/dist/server/hosted-execution-recovery.js +124 -62
  160. package/node_modules/@maka/runtime-host/dist/server/interactive-run-composer.js +47 -22
  161. package/node_modules/@maka/runtime-host/dist/server/message-coordinator.js +76 -6
  162. package/node_modules/@maka/runtime-host/dist/server/plugin-platform-coordinator.js +6 -0
  163. package/node_modules/@maka/runtime-host/dist/server/plugin-platform.js +6 -0
  164. package/node_modules/@maka/runtime-host/dist/server/root-turn-coordinator.js +325 -73
  165. package/node_modules/@maka/runtime-host/dist/server/scheduled-task-coordinator.js +37 -2
  166. package/node_modules/@maka/runtime-host/dist/server/serial-outbound-writer.js +45 -3
  167. package/node_modules/@maka/runtime-host/dist/server/session-catalog-coordinator.js +50 -7
  168. package/node_modules/@maka/runtime-host/dist/server/session-continuity-coordinator.js +87 -25
  169. package/node_modules/@maka/runtime-host/dist/server/session-retirement-coordinator.js +5 -2
  170. package/node_modules/@maka/runtime-host/dist/server/session-revision-coordinator.js +12 -55
  171. package/node_modules/@maka/runtime-host/dist/server/session-sidecar-purge.js +1 -16
  172. package/node_modules/@maka/runtime-host/dist/server/session-transcript-pager.js +0 -1
  173. package/node_modules/@maka/runtime-host/dist/server/session-transcript-reader.js +460 -70
  174. package/node_modules/@maka/runtime-host/dist/server/shared-session-transcript.js +1 -1
  175. package/node_modules/@maka/runtime-host/dist/server/storage-maintenance.js +109 -0
  176. package/node_modules/@maka/runtime-host/dist/server/workhub-coordination-action-gate.js +20 -2
  177. package/node_modules/@maka/runtime-host/dist/server/workhub-coordination-coordinator.js +13 -4
  178. package/node_modules/@maka/runtime-host/dist/server/workhub-message-attachments.js +46 -0
  179. package/node_modules/@maka/storage/dist/artifact-store.js +21 -10
  180. package/node_modules/@maka/storage/dist/artifact-stores.js +1 -1
  181. package/node_modules/@maka/storage/dist/claude-code-session-adapter.js +0 -5
  182. package/node_modules/@maka/storage/dist/codex-session-adapter.js +284 -198
  183. package/node_modules/@maka/storage/dist/context-offload-snapshot.js +325 -0
  184. package/node_modules/@maka/storage/dist/execution-stores.js +9 -7
  185. package/node_modules/@maka/storage/dist/file-session-repository.js +1012 -0
  186. package/node_modules/@maka/storage/dist/git-exec.js +61 -0
  187. package/node_modules/@maka/storage/dist/git-worktree-child-executor.js +8 -35
  188. package/node_modules/@maka/storage/dist/goal-authority.js +2 -2
  189. package/node_modules/@maka/storage/dist/interaction-store.js +2 -2
  190. package/node_modules/@maka/storage/dist/opencode-session-adapter.js +0 -4
  191. package/node_modules/@maka/storage/dist/operational-state-backup.js +9 -5
  192. package/node_modules/@maka/storage/dist/project-catalog.js +2 -23
  193. package/node_modules/@maka/storage/dist/runtime-event-invariants.js +2 -2
  194. package/node_modules/@maka/storage/dist/runtime-event-persistence.js +1 -0
  195. package/node_modules/@maka/storage/dist/runtime-policy/connection-catalog-document.js +8 -3
  196. package/node_modules/@maka/storage/dist/runtime-transcript-query.js +308 -0
  197. package/node_modules/@maka/storage/dist/scheduled-task-store.js +249 -283
  198. package/node_modules/@maka/storage/dist/session-bundle-manifest.js +5 -17
  199. package/node_modules/@maka/storage/dist/session-bundle-policy.js +26 -5
  200. package/node_modules/@maka/storage/dist/session-copy-cleanup.js +2 -1
  201. package/node_modules/@maka/storage/dist/session-message-projection.js +15 -0
  202. package/node_modules/@maka/storage/dist/session-repository.js +767 -0
  203. package/node_modules/@maka/storage/dist/session-store.js +25 -99
  204. package/node_modules/@maka/storage/dist/sqlite-artifact-metadata.js +10 -3
  205. package/node_modules/@maka/storage/dist/sqlite-context-offload-store.js +24 -8
  206. package/node_modules/@maka/storage/dist/sqlite-core-execution-schema.js +7 -1
  207. package/node_modules/@maka/storage/dist/sqlite-runtime-schema.js +44 -1
  208. package/node_modules/@maka/storage/dist/sqlite-runtime-store.js +130 -27
  209. package/node_modules/@maka/storage/dist/sqlite-session-metadata-store.js +109 -892
  210. package/node_modules/@maka/storage/dist/storage-id.js +28 -0
  211. package/node_modules/@maka/storage/dist/tool-result-archive-evidence.js +138 -0
  212. package/node_modules/@maka/storage/dist/workspace-identity.js +2 -15
  213. package/node_modules/@maka/storage/dist/workspace-version-authority-internal.js +1 -8
  214. package/node_modules/@maka/storage/package.json +2 -0
  215. package/package.json +1 -1
@@ -85,7 +85,7 @@ export class HostGoalCoordinator {
85
85
  goalManager: this.manager,
86
86
  evaluator: options.evaluator,
87
87
  getRecentContext: async (sessionId) => {
88
- const messages = await this.#stores.sessionStore.readMessagesSnapshot(sessionId);
88
+ const messages = await options.readSessionMessages(sessionId);
89
89
  tokenCache.set(sessionId, tokenCount(messages));
90
90
  return recentContext(messages);
91
91
  },
@@ -229,6 +229,45 @@ export class HostGoalCoordinator {
229
229
  this.continuation.unarchiveSession(sessionId);
230
230
  }
231
231
  }
232
+ holdForHandoff() {
233
+ if (this.#draining)
234
+ return undefined;
235
+ const hold = this.continuation.holdForHandoff();
236
+ if (!hold)
237
+ return undefined;
238
+ const settled = async () => {
239
+ await hold.settled();
240
+ await this.#flushGoalState();
241
+ };
242
+ return {
243
+ settled,
244
+ release: hold.release,
245
+ residencies: async (executions) => {
246
+ await settled();
247
+ if (this.#draining)
248
+ return undefined;
249
+ for (const [sessionId] of this.#residencies) {
250
+ const authority = this.#authorityBySession.get(sessionId);
251
+ if (!authority)
252
+ return undefined;
253
+ const current = authority.record.currentExecution;
254
+ const paused = executions.find((execution) => execution.sessionId === sessionId);
255
+ // An observed external turn is not a durable Goal execution. Its
256
+ // in-memory completion registration cannot be silently discarded.
257
+ if (paused &&
258
+ (!current ||
259
+ current.execution.turnId !== paused.turnId ||
260
+ current.execution.runId !== paused.runId))
261
+ return undefined;
262
+ if (current && !paused)
263
+ return undefined;
264
+ if (current && !this.matchesActive(sessionId, current.checkpoint, current.controlLease))
265
+ return undefined;
266
+ }
267
+ return [...this.#residencies.values()];
268
+ },
269
+ };
270
+ }
232
271
  beginDrain() {
233
272
  if (this.#draining)
234
273
  return;
@@ -70,6 +70,7 @@ export class RuntimeHostKernel {
70
70
  #hasAcceptedConnection = false;
71
71
  #activeOperations = 0;
72
72
  #activeCommandOperations = 0;
73
+ #handoff;
73
74
  #retainedUntilProcessExit = false;
74
75
  #composition;
75
76
  #compositionDrainBegun = false;
@@ -231,6 +232,8 @@ export class RuntimeHostKernel {
231
232
  }
232
233
  this.#state = 'ready';
233
234
  await this.#publishRegistration();
235
+ if (!this.#shutdownRequested)
236
+ this.#composition?.startMaintenance?.();
234
237
  this.#scheduleIdleIfNeeded();
235
238
  }
236
239
  #accept(connection) {
@@ -306,7 +309,7 @@ export class RuntimeHostKernel {
306
309
  }
307
310
  async #admitHandshake(hello, transport, authority) {
308
311
  const admittedState = await this.#readAdmissionState();
309
- if (!admittedState) {
312
+ if (!admittedState || this.#handoff) {
310
313
  return {
311
314
  kind: 'draining',
312
315
  hostEpoch: this.hostEpoch,
@@ -337,7 +340,13 @@ export class RuntimeHostKernel {
337
340
  hello.generation !== undefined &&
338
341
  hello.generation !== this.#options.generation;
339
342
  if (generationMismatch && hello.takeover?.expectedHostEpoch === this.hostEpoch) {
340
- if (authority.principalKind === 'local_owner' && this.#isTrueIdle(transport)) {
343
+ const residencyCount = hello.activitySnapshotVersion === 2
344
+ ? this.#residencies.drainCount
345
+ : this.#residencies.activeCount;
346
+ if (authority.principalKind === 'local_owner' &&
347
+ residencyCount === 0 &&
348
+ this.#hasNoObservedWork(transport)) {
349
+ this.#shutdownReason = 'retirement';
341
350
  this.#requestDrain();
342
351
  return {
343
352
  kind: 'draining',
@@ -364,8 +373,9 @@ export class RuntimeHostKernel {
364
373
  replacement: this.#lifecycle.kind === 'ephemeral' && this.#isSettledForReplacementAdvice()
365
374
  ? 'wait_for_idle_exit'
366
375
  : 'blocked_by_residency',
367
- ...(generationMismatch && authority.principalKind === 'local_owner'
368
- ? { activity: this.#activitySnapshot() }
376
+ ...(authority.principalKind === 'local_owner' &&
377
+ (generationMismatch || hello.activitySnapshotVersion === 2)
378
+ ? { activity: this.#activitySnapshot(hello.activitySnapshotVersion) }
369
379
  : {}),
370
380
  };
371
381
  }
@@ -376,6 +386,9 @@ export class RuntimeHostKernel {
376
386
  this.#cancelIdle();
377
387
  return {
378
388
  kind: 'accepted',
389
+ ...(hello.activitySnapshotVersion === 2 && this.#composition?.prepareHandoff
390
+ ? { cooperativeHandoff: true }
391
+ : {}),
379
392
  rootId: this.#options.owner.capability.rootId,
380
393
  hostEpoch: this.hostEpoch,
381
394
  connectionId: randomUUID(),
@@ -401,6 +414,10 @@ export class RuntimeHostKernel {
401
414
  async #beginOperation(frame) {
402
415
  if (!(await this.#readAdmissionState()))
403
416
  return 'host_draining';
417
+ if (this.#handoff &&
418
+ HOST_OPERATION_SPECS[frame.operation].mode === 'command' &&
419
+ (this.#handoff.commandsClosed || frame.operation !== 'turn.stop'))
420
+ return 'host_draining';
404
421
  if (HOST_OPERATION_SPECS[frame.operation].availability !== 'bootstrap' &&
405
422
  this.#state !== 'ready') {
406
423
  return 'host_not_ready';
@@ -475,14 +492,9 @@ export class RuntimeHostKernel {
475
492
  this.#settleLifecycleAfterWork();
476
493
  }
477
494
  #acquireResidency(label) {
478
- const residency = this.#residencies.acquire(label);
495
+ const residency = this.#residencies.acquire(label, 'drain', () => this.#settleLifecycleAfterWork());
479
496
  this.#cancelIdle();
480
- return {
481
- release: () => {
482
- residency.release();
483
- this.#settleLifecycleAfterWork();
484
- },
485
- };
497
+ return residency;
486
498
  }
487
499
  #retainUntilProcessExit() {
488
500
  if (this.#retainedUntilProcessExit)
@@ -523,7 +535,7 @@ export class RuntimeHostKernel {
523
535
  ok: true,
524
536
  result: await this.#resourceCollector.snapshot(this.hostEpoch),
525
537
  }),
526
- 'host.upgrade.prepare': async (input) => {
538
+ 'host.upgrade.prepare': async (input, context) => {
527
539
  if (input.expectedHostEpoch !== this.hostEpoch) {
528
540
  return {
529
541
  ok: false,
@@ -534,7 +546,10 @@ export class RuntimeHostKernel {
534
546
  };
535
547
  }
536
548
  if (!input.allowInterruptActiveTasks && this.#hasUpgradeBlockingActivity(1)) {
537
- return { ok: true, result: { kind: 'active_tasks' } };
549
+ if (!input.allowCooperativeHandoff ||
550
+ !(await this.#prepareCooperativeHandoff(context.inputClosedSignal))) {
551
+ return { ok: true, result: { kind: 'active_tasks' } };
552
+ }
538
553
  }
539
554
  this.#shutdownReason = 'retirement';
540
555
  this.#requestDrain();
@@ -600,12 +615,18 @@ export class RuntimeHostKernel {
600
615
  : {}),
601
616
  };
602
617
  }
603
- #activitySnapshot() {
618
+ #activitySnapshot(version) {
604
619
  return {
605
620
  connections: this.#acceptedTransports.size,
606
621
  activeOperations: this.#activeOperations,
607
622
  processUptimeSeconds: Math.max(0, Math.floor(process.uptime())),
608
623
  residencies: this.#residencies.snapshot(),
624
+ ...(version === 2
625
+ ? {
626
+ drainResidencies: this.#residencies.drainCount,
627
+ ...(this.#composition?.prepareHandoff ? { cooperativeHandoff: true } : {}),
628
+ }
629
+ : {}),
609
630
  };
610
631
  }
611
632
  #hasUpgradeBlockingActivity(selfCommands) {
@@ -621,6 +642,62 @@ export class RuntimeHostKernel {
621
642
  return true;
622
643
  return this.#residencies.drainCount > 0;
623
644
  }
645
+ async #prepareCooperativeHandoff(inputClosedSignal) {
646
+ if (!inputClosedSignal ||
647
+ inputClosedSignal.aborted ||
648
+ !this.#composition?.prepareHandoff ||
649
+ this.#handoff ||
650
+ this.#acceptedTransports.size > 1 ||
651
+ this.#activeCommandOperations > 1)
652
+ return false;
653
+ const handoff = { abort: new AbortController(), commandsClosed: false, committing: false };
654
+ this.#handoff = handoff;
655
+ const cancelOnDisconnect = () => {
656
+ if (!handoff.committing)
657
+ handoff.abort.abort();
658
+ };
659
+ inputClosedSignal.addEventListener('abort', cancelOnDisconnect, { once: true });
660
+ const timer = setTimeout(() => handoff.abort.abort(), 10_000);
661
+ let prepared;
662
+ try {
663
+ prepared = await this.#composition.prepareHandoff(this.hostEpoch, handoff.abort.signal);
664
+ if (!prepared || handoff.abort.signal.aborted || this.#activeCommandOperations !== 1)
665
+ return false;
666
+ handoff.commandsClosed = true;
667
+ if (!(await prepared.seal()))
668
+ return false;
669
+ const residencies = await prepared.residencies();
670
+ if (!residencies ||
671
+ handoff.abort.signal.aborted ||
672
+ !(await this.#hasLiveOwnerOrDrain()) ||
673
+ handoff.abort.signal.aborted ||
674
+ this.#handoff !== handoff ||
675
+ this.#acceptedTransports.size !== 1 ||
676
+ this.#activeCommandOperations !== 1 ||
677
+ this.#residencies.hasDrainResidenciesExcept(residencies))
678
+ return false;
679
+ // No await between the final exact-handle proof and closing all command
680
+ // admission. After this cut cancellation must not restart the old runs.
681
+ handoff.committing = true;
682
+ clearTimeout(timer);
683
+ await prepared.detach();
684
+ return true;
685
+ }
686
+ finally {
687
+ clearTimeout(timer);
688
+ inputClosedSignal.removeEventListener('abort', cancelOnDisconnect);
689
+ if (handoff.committing) {
690
+ this.#shutdownReason = 'retirement';
691
+ this.#requestDrain();
692
+ }
693
+ else {
694
+ handoff.abort.abort();
695
+ prepared?.cancel();
696
+ }
697
+ if (this.#handoff === handoff)
698
+ this.#handoff = undefined;
699
+ }
700
+ }
624
701
  #beginCompositionDrain() {
625
702
  if (!this.#composition || this.#compositionDrainBegun)
626
703
  return;
@@ -659,7 +736,10 @@ export class RuntimeHostKernel {
659
736
  void this.#commitShutdown().catch(() => undefined);
660
737
  }, this.#lifecycle.idleGraceMs);
661
738
  }
662
- #isTrueIdle(exceptHandshaking) {
739
+ #isTrueIdle() {
740
+ return this.#residencies.activeCount === 0 && this.#hasNoObservedWork();
741
+ }
742
+ #hasNoObservedWork(exceptHandshaking) {
663
743
  // A transport mid-handshake keeps the Host busy, except the one whose
664
744
  // admission is being decided right now: counting it would make every
665
745
  // true-idle takeover observe itself as activity.
@@ -669,8 +749,7 @@ export class RuntimeHostKernel {
669
749
  return (this.#state === 'ready' &&
670
750
  this.#acceptedTransports.size === 0 &&
671
751
  handshaking === 0 &&
672
- this.#activeOperations === 0 &&
673
- this.#residencies.activeCount === 0);
752
+ this.#activeOperations === 0);
674
753
  }
675
754
  // The replacement advice in a rejection is what a stale Client acts on.
676
755
  // In-flight handshakes resolve within milliseconds and must not flip that
@@ -21,34 +21,41 @@ export class HostResidencyRegistry {
21
21
  #counts = new Map();
22
22
  #drainWaiters = new Set();
23
23
  #activeCount = 0;
24
- #drainCount = 0;
24
+ #drainHandles = new Set();
25
25
  /** Residencies of either kind keep the process alive against idle exit. */
26
26
  get activeCount() {
27
27
  return this.#activeCount;
28
28
  }
29
29
  /** Only drain-kind residencies block maintenance probes and graceful close. */
30
30
  get drainCount() {
31
- return this.#drainCount;
31
+ return this.#drainHandles.size;
32
32
  }
33
- acquire(label, kind = 'drain') {
33
+ hasDrainResidenciesExcept(allowed) {
34
+ const proven = new Set(allowed);
35
+ return [...this.#drainHandles].some((handle) => !proven.has(handle));
36
+ }
37
+ acquire(label, kind = 'drain', onRelease) {
34
38
  requireResidencyLabel(label);
35
39
  this.#activeCount += 1;
36
- if (kind === 'drain')
37
- this.#drainCount += 1;
38
40
  const counts = this.#counts.get(label) ?? { total: 0, drain: 0 };
39
41
  counts.total += 1;
40
42
  if (kind === 'drain')
41
43
  counts.drain += 1;
42
44
  this.#counts.set(label, counts);
43
45
  let active = true;
44
- return {
46
+ const handle = {
45
47
  release: () => {
46
48
  if (!active)
47
49
  return;
48
50
  active = false;
51
+ this.#drainHandles.delete(handle);
49
52
  this.#release(label, kind);
53
+ onRelease?.();
50
54
  },
51
55
  };
56
+ if (kind === 'drain')
57
+ this.#drainHandles.add(handle);
58
+ return handle;
52
59
  }
53
60
  snapshot() {
54
61
  return [...this.#counts]
@@ -70,7 +77,6 @@ export class HostResidencyRegistry {
70
77
  counts.total -= 1;
71
78
  if (kind === 'drain') {
72
79
  counts.drain -= 1;
73
- this.#drainCount -= 1;
74
80
  }
75
81
  this.#activeCount -= 1;
76
82
  if (counts.total === 0)
@@ -131,7 +131,9 @@ export class HostedExecutionAdmissionRegistry {
131
131
  }
132
132
  }
133
133
  waitForSettledAdmissions() {
134
- return Promise.all([...this.#bySession.values()].map((value) => value.admissionSettled.promise)).then(() => undefined);
134
+ return Promise.all([...this.#bySession.values()]
135
+ .filter((value) => value.kind === 'pending')
136
+ .map((value) => value.admissionSettled.promise)).then(() => undefined);
135
137
  }
136
138
  }
137
139
  export function hostedExecutionDeferred() {
@@ -17,39 +17,52 @@
17
17
  * under the License.
18
18
  */
19
19
  import { isDeepStrictEqual } from 'node:util';
20
+ import { readLogicalRuntimeExecution } from '@maka/core/runtime-logical-execution';
20
21
  import { runtimeInvocationOutcome, } from '@maka/core/runtime-invocation';
21
22
  import { messageContentsEqual, normalizeMessageContent, } from '@maka/core/events';
22
- import { RuntimeMessageAuthorityInvariantError } from '@maka/runtime/message-authority';
23
+ import { projectRuntimeEventUserMessage } from '@maka/runtime/runtime-event-read-model';
24
+ import { admittedPromptEventId, RuntimeMessageAuthorityInvariantError, } from '@maka/runtime/message-authority';
23
25
  /** Validates and repairs durable admission/message relationships before execution replay. */
24
26
  export async function prepareHostedExecutionRecovery(input) {
25
27
  // listHeaders() avoids listForRecovery()'s discarded per-Session message
26
- // pre-read; the per-Session readMessagesForRecovery below remains the single
27
- // decode that validates durable messages before replay.
28
+ // pre-read. The messages an admission is checked against are the Session's
29
+ // own RuntimeEvents: the ledger is where a Turn's user message is committed,
30
+ // so it is also the only place a missing one can be detected.
28
31
  const sessions = await input.stores.sessionStore.listHeaders();
29
32
  const prepared = [];
30
33
  for (const session of sessions) {
31
34
  const admissions = await input.rootAdmissions.recoverSession(session.id);
32
- const messages = await input.stores.sessionStore.readMessagesForRecovery(session.id);
33
35
  const runs = await input.stores.runtimeEventStore.listSessionInvocations(session.id);
34
36
  const runsById = new Map(runs.map((run) => [run.runId, run]));
35
37
  for (const run of runs) {
36
38
  await input.stores.agentRunStore.readEventsForRecovery(session.id, run.runId);
37
39
  await input.stores.runtimeEventStore.readRuntimeEvents(session.id, run.runId);
38
40
  }
39
- const messageIndex = indexRecoveryMessages(messages);
41
+ const messageIndex = indexRecoveryMessages(recoveryUserMessagesFromLedger(await input.stores.runtimeEventStore.readSessionRuntimeEvents(session.id)));
40
42
  const replayAdmissions = [];
41
43
  const rootReplayAdmissions = [];
42
- const missingMessages = [];
43
44
  const pendingRecoveryClosures = [];
44
45
  for (const admission of admissions) {
45
46
  const run = runsById.get(admission.runId);
46
- const rootUserMessages = (messageIndex.userMessagesByTurnId.get(admission.turnId) ?? []).filter((message) => message.id === admission.userMessageId);
47
- const messageIdOwners = admission.userMessageId
48
- ? (messageIndex.messagesById.get(admission.userMessageId) ?? [])
49
- : [];
47
+ const logical = run && (await readLogicalRuntimeExecution(input.stores.runtimeEventStore, admission, run));
48
+ if (logical?.pendingHandoff) {
49
+ replayAdmissions.push(admission);
50
+ rootReplayAdmissions.push(admission);
51
+ }
52
+ const admittedMessageId = admittedPromptEventId(admission.runId, admission.userMessageId);
53
+ // Whether the prompt is on the ledger is a question about the Turn, not
54
+ // about the id it landed under: a Run written by an older build derived
55
+ // that id differently, and matching on the id would read its prompt as
56
+ // missing and record a second one.
57
+ const rootUserMessages = messageIndex.userMessagesByTurnId.get(admission.turnId) ?? [];
58
+ const messageIdOwners = messageIndex.messagesById.get(admittedMessageId) ?? [];
59
+ if (messageIdOwners.length > 1) {
60
+ throw new Error(`Admitted Turn ${admission.turnId} has a duplicated UserMessage identity`);
61
+ }
62
+ const messageIdOwner = messageIdOwners[0];
50
63
  const executionContract = recoveryExecutionContract(admission.execution);
51
64
  if (admission.execution.kind === 'scheduled_task' &&
52
- (!run || runtimeInvocationOutcome(run) === undefined)) {
65
+ (!logical || runtimeInvocationOutcome(logical.tip) === undefined)) {
53
66
  if (!input.assertScheduledTaskAdmission) {
54
67
  throw new RuntimeMessageAuthorityInvariantError('ScheduledTask recovery admission has no canonical authority validator');
55
68
  }
@@ -67,12 +80,9 @@ export async function prepareHostedExecutionRecovery(input) {
67
80
  if (admission.sourceMessages.length > 0) {
68
81
  await verifyQueueSourceMessages(admission, messageIndex, input.stores.agentRunStore);
69
82
  }
70
- if (rootUserMessages.length > 0) {
71
- throw new Error(`Admitted Turn ${admission.turnId} must not record a UserMessage`);
72
- }
73
83
  if (!run) {
74
84
  if (executionContract.pendingWithoutRun === 'host_recovery_closure') {
75
- pendingRecoveryClosures.push(admission);
85
+ pendingRecoveryClosures.push({ admission });
76
86
  }
77
87
  else {
78
88
  replayAdmissions.push(admission);
@@ -88,35 +98,35 @@ export async function prepareHostedExecutionRecovery(input) {
88
98
  else {
89
99
  await input.projection.assertRunIdentityAndContinuation(run, admission.turnId, admission.execution);
90
100
  }
101
+ if (executionContract.requiresUserMessage) {
102
+ const recorded = verifyUserMessage(admission, rootUserMessages, messageIdOwner);
103
+ await recordAdmittedUserMessage(input.stores, admission, run, recorded);
104
+ }
91
105
  continue;
92
106
  }
93
- if (messageIdOwners.length > 1) {
94
- throw new Error(`Admitted Turn ${admission.turnId} has a duplicated UserMessage identity`);
95
- }
96
- const messageIdOwner = messageIdOwners[0];
97
107
  if (!run && executionContract.pendingWithoutRun === 'host_recovery_closure') {
98
- verifyOrRecoverUserMessage(admission, rootUserMessages, messageIdOwner, missingMessages, messageIndex);
99
- pendingRecoveryClosures.push(admission);
100
- continue;
101
- }
102
- if (!run && executionContract.pendingWithoutRun === 'domain_replay') {
103
- verifyOrRecoverUserMessage(admission, rootUserMessages, messageIdOwner, missingMessages, messageIndex);
104
- replayAdmissions.push(admission);
108
+ // The closure below opens this Turn's invocation, so it is also what
109
+ // writes the message the crashed admission never got to record.
110
+ const recorded = verifyUserMessage(admission, rootUserMessages, messageIdOwner);
111
+ pendingRecoveryClosures.push({
112
+ admission,
113
+ ...(recorded ? {} : { writesUserMessage: true }),
114
+ });
105
115
  continue;
106
116
  }
107
117
  if (!run) {
108
- if (executionContract.pendingWithoutRun === 'root_replay') {
109
- verifyOrRecoverUserMessage(admission, rootUserMessages, messageIdOwner, missingMessages, messageIndex, false);
110
- }
111
- else if (rootUserMessages.length > 0 || messageIdOwner) {
112
- throw new Error(`Admitted Turn ${admission.turnId} has a UserMessage but no Run`);
113
- }
118
+ // Every remaining path replays the admission, and a replay opens the
119
+ // Turn with the admission's own message id — writing the message here
120
+ // would only race the Run that owns it.
121
+ verifyUserMessage(admission, rootUserMessages, messageIdOwner);
114
122
  replayAdmissions.push(admission);
115
- rootReplayAdmissions.push(admission);
123
+ if (executionContract.pendingWithoutRun !== 'domain_replay') {
124
+ rootReplayAdmissions.push(admission);
125
+ }
116
126
  continue;
117
127
  }
118
128
  await input.projection.assertRunIdentityAndContinuation(run, admission.turnId, admission.execution);
119
- verifyOrRecoverUserMessage(admission, rootUserMessages, messageIdOwner, missingMessages, messageIndex);
129
+ await recordAdmittedUserMessage(input.stores, admission, run, verifyUserMessage(admission, rootUserMessages, messageIdOwner));
120
130
  }
121
131
  if (replayAdmissions.length > 1) {
122
132
  throw new Error(`Session ${session.id} has multiple admitted Turns without Runs`);
@@ -128,24 +138,30 @@ export async function prepareHostedExecutionRecovery(input) {
128
138
  sessionId: session.id,
129
139
  admissions,
130
140
  ...(rootReplayAdmissions[0] ? { rootReplayAdmission: rootReplayAdmissions[0] } : {}),
131
- missingMessages,
132
141
  pendingRecoveryClosures,
133
142
  });
134
143
  }
135
144
  for (const plan of prepared) {
136
- for (const message of plan.missingMessages) {
137
- await input.stores.sessionStore.appendMessage(plan.sessionId, message);
138
- }
139
- for (const admission of plan.pendingRecoveryClosures) {
145
+ for (const { admission, writesUserMessage } of plan.pendingRecoveryClosures) {
140
146
  if (!usesHostRecoveryClosure(admission.execution)) {
141
147
  throw new Error('Execution domain cannot use Host recovery closure');
142
148
  }
149
+ const origin = hostedExecutionMessageOrigin(admission.execution);
143
150
  await input.runtime.closePendingHostedAdmission({
144
151
  sessionId: admission.sessionId,
145
152
  turnId: admission.turnId,
146
153
  runId: admission.runId,
147
154
  admittedAt: admission.admittedAt,
148
155
  execution: admission.execution,
156
+ ...(writesUserMessage && admission.userMessageId
157
+ ? {
158
+ userMessage: {
159
+ id: admission.userMessageId,
160
+ content: requireHostedExecutionMessageContent(admission),
161
+ ...(origin ? { origin } : {}),
162
+ },
163
+ }
164
+ : {}),
149
165
  });
150
166
  }
151
167
  }
@@ -155,6 +171,48 @@ export async function prepareHostedExecutionRecovery(input) {
155
171
  ...(rootReplayAdmission ? { rootReplayAdmission } : {}),
156
172
  }));
157
173
  }
174
+ /**
175
+ * The message a crashed Turn was admitted with, written into the Run that had
176
+ * already opened for it.
177
+ *
178
+ * A Run records its own user message right after its opening fact, so a Run
179
+ * that exists without one crashed between those two writes. Nothing else will
180
+ * write it now: the terminal fact recovery is about to append would seal the
181
+ * Turn without ever saying what the user asked for.
182
+ *
183
+ * The admission's normalized input is what goes in, not its queue sources: a
184
+ * Root folded from several Messages ran as one prompt, and that is the prompt
185
+ * the Turn was executed with.
186
+ */
187
+ async function recordAdmittedUserMessage(stores, admission, run, ledgerHasMessage) {
188
+ if (run.terminalEvent)
189
+ return;
190
+ const content = requireHostedExecutionMessageContent(admission);
191
+ const origin = hostedExecutionMessageOrigin(admission.execution);
192
+ const event = {
193
+ id: admittedPromptEventId(admission.runId, admission.userMessageId),
194
+ sessionId: admission.sessionId,
195
+ invocationId: run.invocationId,
196
+ runId: run.runId,
197
+ turnId: admission.turnId,
198
+ ts: admission.admittedAt,
199
+ partial: false,
200
+ role: 'user',
201
+ author: origin ? 'host' : 'user',
202
+ content: { kind: 'text', ...content, ...(origin ? { origin } : {}) },
203
+ };
204
+ if (!ledgerHasMessage) {
205
+ await stores.runtimeEventStore.appendRuntimeEvent(admission.sessionId, run.runId, event);
206
+ }
207
+ // The Turn never reached the commit that carries these, and no later path
208
+ // recomputes them: the connection lock is one-way and the preview is a write.
209
+ // Committed even when the ledger already holds the message, because the two
210
+ // are separate writes and a crash between them leaves exactly that state.
211
+ const message = projectRuntimeEventUserMessage(event, event.id);
212
+ if (message) {
213
+ await stores.sessionStore.commitMessageCatalogProjection(admission.sessionId, message);
214
+ }
215
+ }
158
216
  export function requireHostedExecutionMessageContent(admission) {
159
217
  if (admission.normalizedInput === null) {
160
218
  throw new RuntimeMessageAuthorityInvariantError(`Admitted Turn ${admission.turnId} has no message input`);
@@ -186,28 +244,46 @@ export function hostedExecutionMessageOrigin(execution) {
186
244
  return undefined;
187
245
  }
188
246
  }
189
- function verifyOrRecoverUserMessage(admission, rootUserMessages, messageIdOwner, missingMessages, index, materializeMissing = true) {
247
+ /**
248
+ * Whether the ledger already carries this admission's message, throwing when
249
+ * what it carries contradicts the admission.
250
+ */
251
+ function verifyUserMessage(admission, rootUserMessages, messageIdOwner) {
190
252
  if (rootUserMessages.length > 1) {
191
253
  throw new Error(`Admitted Turn ${admission.turnId} has multiple UserMessages`);
192
254
  }
193
255
  const userMessage = rootUserMessages[0];
194
256
  if (userMessage) {
195
- if (messageIdOwner !== userMessage ||
196
- userMessage.id !== admission.userMessageId ||
257
+ if ((messageIdOwner !== undefined && messageIdOwner !== userMessage) ||
197
258
  !recoveryUserMessageOriginMatches(userMessage, admission.execution) ||
198
259
  !messageContentsEqual(normalizeMessageContent(userMessage), requireHostedExecutionMessageContent(admission))) {
199
260
  throw new Error(`Admitted Turn ${admission.turnId} does not match its UserMessage`);
200
261
  }
201
- return;
262
+ return true;
202
263
  }
203
264
  if (messageIdOwner) {
204
265
  throw new Error(`Admitted Turn ${admission.turnId} reuses another message identity`);
205
266
  }
206
- if (!materializeMissing)
207
- return;
208
- const recoveredMessage = recoveryUserMessage(admission);
209
- missingMessages.push(recoveredMessage);
210
- indexRecoveryMessage(index, recoveredMessage);
267
+ return false;
268
+ }
269
+ /**
270
+ * The prompts a Session's ledger holds, as the transcript presents them.
271
+ *
272
+ * Recovery reads the raw events rather than the read model: a Session it is
273
+ * about to repair may be exactly the one whose projection is still incomplete.
274
+ * Steering is excluded — it is typed as a user message but is something said
275
+ * into a Turn that was already admitted, so it is never the Turn's own prompt.
276
+ */
277
+ function recoveryUserMessagesFromLedger(events) {
278
+ const messages = [];
279
+ for (const event of events) {
280
+ if (event.role !== 'user' || event.content?.kind !== 'text' || event.partial)
281
+ continue;
282
+ const projected = projectRuntimeEventUserMessage(event, event.id);
283
+ if (projected && projected.steeringEventId === undefined)
284
+ messages.push(projected);
285
+ }
286
+ return messages;
211
287
  }
212
288
  async function verifyQueueSourceMessages(admission, index, proofReader) {
213
289
  for (const source of admission.sourceMessages) {
@@ -232,20 +308,6 @@ async function verifyQueueSourceMessages(admission, index, proofReader) {
232
308
  }
233
309
  }
234
310
  }
235
- function recoveryUserMessage(admission) {
236
- if (!admission.userMessageId || !admission.normalizedInput) {
237
- throw new Error(`Admitted Turn ${admission.turnId} does not own a UserMessage`);
238
- }
239
- const origin = hostedExecutionMessageOrigin(admission.execution);
240
- return {
241
- type: 'user',
242
- id: admission.userMessageId,
243
- turnId: admission.turnId,
244
- ts: admission.admittedAt,
245
- ...normalizeMessageContent(admission.normalizedInput),
246
- ...(origin ? { origin } : {}),
247
- };
248
- }
249
311
  function recoveryUserMessageOriginMatches(message, execution) {
250
312
  const expected = hostedExecutionMessageOrigin(execution);
251
313
  return expected === undefined || isDeepStrictEqual(message.origin, expected);