evolcore 0.0.43-test.7 → 0.0.45

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 (127) hide show
  1. package/CHANGELOG.md +47 -0
  2. package/bin/ecmsg.js +22 -9
  3. package/dist/agent-template/jobs.js +62 -0
  4. package/dist/agent-template/runtime.js +214 -0
  5. package/dist/agent-template/service.js +465 -0
  6. package/dist/agent-template/tool-runner.js +45 -0
  7. package/dist/agent-template/types.js +5 -0
  8. package/dist/agents/claude-runner.js +1 -1
  9. package/dist/aun/aid/agentmd.js +56 -1
  10. package/dist/aun/aid/client.js +3 -1
  11. package/dist/aun/menu/client.js +3 -2
  12. package/dist/aun/msg/p2p.js +1 -1
  13. package/dist/channels/aun.js +47 -32
  14. package/dist/cli/agent-command.js +5 -0
  15. package/dist/cli/agent-create.js +5 -1
  16. package/dist/cli/agent-template.js +124 -0
  17. package/dist/cli/aun-commands.js +2 -2
  18. package/dist/cli/ctl-command.js +2 -1
  19. package/dist/cli/daemon-commands.js +5 -0
  20. package/dist/cli/ecmsg-gateway.js +2 -2
  21. package/dist/cli/events-command.js +45 -9
  22. package/dist/cli/index.js +29 -0
  23. package/dist/cli/net-check.js +1 -1
  24. package/dist/cli/restart-monitor.js +115 -36
  25. package/dist/cli/services-command.js +29 -3
  26. package/dist/cli/thread-command.js +97 -11
  27. package/dist/config/boot-log.js +8 -8
  28. package/dist/config/schema-migration.js +41 -16
  29. package/dist/core/agent-ipc-registration.js +25 -4
  30. package/dist/core/agent-runtime.js +2 -0
  31. package/dist/core/auth/operation-authorizer.js +2 -0
  32. package/dist/core/auth/operation-catalog.js +11 -2
  33. package/dist/core/channel-runtime.js +16 -9
  34. package/dist/core/command/agent-control.js +11 -1
  35. package/dist/core/command/agent-template-menu.js +147 -0
  36. package/dist/core/command/command-handler.js +27 -6
  37. package/dist/core/command/eventcenter-menu.js +158 -28
  38. package/dist/core/command/menu-catalog.js +8 -1
  39. package/dist/core/command/menu-handler.js +18 -6
  40. package/dist/core/command/menu-protocol.js +11 -2
  41. package/dist/core/daemon-control.js +14 -0
  42. package/dist/core/daemon-lifecycle.js +262 -189
  43. package/dist/core/handoff/runtime.js +42 -10
  44. package/dist/core/ipc-registration.js +5 -1
  45. package/dist/core/legacy-rename.js +41 -0
  46. package/dist/core/message/aun-ipc-sender.js +118 -13
  47. package/dist/core/message/im-renderer.js +88 -1
  48. package/dist/core/message/message-queue.js +66 -15
  49. package/dist/core/message/pending-hints.js +29 -5
  50. package/dist/core/message/response-engine.js +37 -7
  51. package/dist/core/message/send-routing.js +13 -6
  52. package/dist/core/pack-auth.js +94 -0
  53. package/dist/core/pack-install.js +194 -0
  54. package/dist/core/permission/ec-command-parser.js +49 -16
  55. package/dist/core/rate-window.js +48 -0
  56. package/dist/core/relation/peer-identity.js +28 -0
  57. package/dist/core/session/session-fs-store.js +66 -26
  58. package/dist/core/session/session-idle-monitor.js +59 -19
  59. package/dist/core/session/session-manager.js +13 -4
  60. package/dist/core/thread/thread-route.js +2 -2
  61. package/dist/core/thread/thread-service.js +52 -3
  62. package/dist/eck/kit-renderer.js +1 -1
  63. package/dist/eck/message-renderer.js +2 -0
  64. package/dist/event-center/admission-materializer.js +22 -12
  65. package/dist/event-center/bus-gate.js +20 -2
  66. package/dist/event-center/bus-host.js +46 -29
  67. package/dist/event-center/bus-resolver.js +1 -1
  68. package/dist/event-center/center-config.js +41 -14
  69. package/dist/event-center/daemon.js +1 -2
  70. package/dist/event-center/directory-source.js +3 -1
  71. package/dist/event-center/index-generator.js +12 -2
  72. package/dist/event-center/ipc-operation.js +140 -25
  73. package/dist/event-center/pack-loader.js +61 -56
  74. package/dist/event-center/pack-manager.js +2 -2
  75. package/dist/event-center/registry.js +242 -17
  76. package/dist/event-center/runtime.js +271 -75
  77. package/dist/event-center/types.js +20 -4
  78. package/dist/event-center/validation.js +34 -12
  79. package/dist/index.js +147 -44
  80. package/dist/ipc.js +44 -4
  81. package/dist/paths.js +2 -2
  82. package/dist/response-system/engines/v1/proactive-flow.js +4 -2
  83. package/dist/services/index.js +3 -3
  84. package/dist/services/ipc-operation.js +99 -7
  85. package/dist/services/pack-manager.js +17 -6
  86. package/dist/services/router.js +8 -5
  87. package/dist/services/validation.js +5 -5
  88. package/dist/trigger/scheduler.js +38 -0
  89. package/dist/trigger/script-sandbox.js +52 -2
  90. package/dist/utils/npm-ops.js +2 -1
  91. package/dist/utils/package-version-info.js +6 -3
  92. package/kits/docs/aun/ABILITY_CALLING.md +4 -3
  93. package/kits/docs/context-assembly.md +1 -1
  94. package/kits/docs/evolcore/INDEX.md +3 -3
  95. package/kits/docs/evolcore/agent.md +22 -1
  96. package/kits/docs/evolcore/event-center.md +30 -10
  97. package/kits/docs/evolcore/fs.md +4 -3
  98. package/kits/docs/evolcore/menu-protocol.md +7 -1
  99. package/kits/docs/evolcore/msg.md +8 -8
  100. package/kits/docs/evolcore/response.md +2 -2
  101. package/kits/docs/evolcore/services.md +27 -10
  102. package/kits/docs/evolcore/thread-chain.md +15 -3
  103. package/kits/rules/06-channel.md +1 -0
  104. package/kits/skills/ability/references/calling.md +2 -2
  105. package/kits/skills/ec-group/SKILL.md +5 -8
  106. package/kits/skills/ec-group-collaboration/SKILL.md +7 -7
  107. package/kits/skills/ec-trigger/SKILL.md +4 -4
  108. package/kits/skills/thread-ops/SKILL.md +10 -10
  109. package/kits/templates/message-fragments/item.md +1 -1
  110. package/kits/templates/system-fragments/channel.md +1 -1
  111. package/kits/templates/system-fragments/commands.md +1 -1
  112. package/kits/templates/system-fragments/reply.md +1 -0
  113. package/kits/templates/system-fragments/thread.md +3 -2
  114. package/package.json +4 -3
  115. package/scripts/agent-template/index.mjs +40 -0
  116. package/scripts/agent-template/inspect.mjs +240 -0
  117. package/scripts/agent-template/overlay.mjs +71 -0
  118. package/scripts/agent-template/pack.mjs +169 -0
  119. package/scripts/agent-template/shared/common.mjs +235 -0
  120. package/scripts/agent-template/shared/evolcore.mjs +75 -0
  121. package/scripts/agent-template/shared/plan.mjs +129 -0
  122. package/scripts/agent-template/shared/team-schema.json +70 -0
  123. package/scripts/agent-template/shared/template-contract.mjs +154 -0
  124. package/scripts/agent-template/shared/template-package.mjs +265 -0
  125. package/scripts/agent-template/shared/template-runtime.mjs +80 -0
  126. package/scripts/agent-template/shared/template.mjs +142 -0
  127. package/dist/event-center/client-factory.js +0 -50
@@ -7,11 +7,12 @@ import { disposeAgentInstances } from './runner-reload-transaction.js';
7
7
  import { sessionTopicThreadId } from './thread/topic-id.js';
8
8
  import { StartupTracer } from '../utils/startup-trace.js';
9
9
  import { OFFLINE_TOTAL_BUDGET_MS } from './lifecycle-notice.js';
10
- import { monitorEventLoopDelay, performance } from 'node:perf_hooks';
11
10
  import { setImmediate as yieldToIo } from 'node:timers/promises';
11
+ import { performance, monitorEventLoopDelay } from 'node:perf_hooks';
12
12
  import path from 'node:path';
13
13
  import { agentTriggersDir } from '../paths.js';
14
14
  import { readLastJsonlLineAsync, scanAgentChatDirsAsync } from './session/session-fs-store.js';
15
+ import { pendingHintDirectoryVersion } from './message/pending-hints.js';
15
16
  import { fileToSession } from './session/session-mapper.js';
16
17
  import { HandoffStore } from './handoff/store.js';
17
18
  export class StartupGate {
@@ -60,17 +61,36 @@ async function json(file) {
60
61
  throw error;
61
62
  }
62
63
  }
64
+ /** Reuse freed scan capacity, and settle in-flight readers before publishing classification. */
65
+ async function scanStartupItems(items, concurrency, visit) {
66
+ let next = 0;
67
+ const results = await Promise.allSettled(Array.from({ length: Math.min(concurrency, items.length) }, async () => {
68
+ while (next < items.length)
69
+ await visit(items[next++]);
70
+ }));
71
+ for (const result of results)
72
+ if (result.status === 'rejected')
73
+ throw result.reason;
74
+ }
63
75
  export async function discoverStartupWork(options) {
64
76
  const plan = {
65
77
  priorityAids: new Set(), triggerAids: new Set(), requiredChannelKeys: new Set(),
66
78
  requiredExternalAids: new Set(), pendingSessions: [], staleSessions: [], sessionScanFailed: false,
67
- handoffSnapshots: new Map(),
79
+ hintDirectories: new Map(),
68
80
  };
69
81
  const known = new Set(options.agentAids);
82
+ const prioritized = new Set();
83
+ const prioritize = (aid, reason) => {
84
+ plan.priorityAids.add(aid);
85
+ if (!known.has(aid) || prioritized.has(aid))
86
+ return;
87
+ prioritized.add(aid);
88
+ options.onAgentPrioritized?.(aid, reason);
89
+ };
70
90
  const uncertain = (aid, error) => {
71
91
  if (known.has(aid)) {
72
- plan.priorityAids.add(aid);
73
92
  plan.requiredExternalAids.add(aid);
93
+ prioritize(aid, 'uncertain');
74
94
  }
75
95
  logger.warn(`[startup] Work classification uncertain for ${aid}; prioritizing recovery: ${error}`);
76
96
  };
@@ -82,7 +102,7 @@ export async function discoverStartupWork(options) {
82
102
  uncertain(candidate, 'unresolved persisted input owner');
83
103
  return;
84
104
  }
85
- plan.priorityAids.add(aid);
105
+ prioritize(aid, 'queue');
86
106
  if (message?.channel)
87
107
  plan.requiredChannelKeys.add(message.channel);
88
108
  else
@@ -120,7 +140,6 @@ export async function discoverStartupWork(options) {
120
140
  }
121
141
  const now = Date.now();
122
142
  const triggerDir = options.triggerDir ?? agentTriggersDir;
123
- const handoffStore = options.handoffStore ?? new HandoffStore();
124
143
  const scanTriggers = async (aid) => {
125
144
  const started = Date.now();
126
145
  let files = 0;
@@ -157,7 +176,7 @@ export async function discoverStartupWork(options) {
157
176
  if (plan.triggerAids.has(aid)) {
158
177
  const owner = aid === options.daemonTriggerAid ? options.primaryAid : aid;
159
178
  if (owner)
160
- plan.priorityAids.add(owner);
179
+ prioritize(owner, 'triggers');
161
180
  }
162
181
  options.onScan?.({ phase: 'triggers', aid, durationMs: Date.now() - started, files });
163
182
  };
@@ -166,99 +185,136 @@ export async function discoverStartupWork(options) {
166
185
  const daemonTriggerScan = scanTriggers(options.daemonTriggerAid);
167
186
  const aids = [...known];
168
187
  let next = 0;
169
- await Promise.all([daemonTriggerScan, ...Array.from({ length: Math.min(4, aids.length) }, async () => {
170
- while (next < aids.length) {
171
- const aid = aids[next++];
172
- let started = Date.now();
173
- let files = 0;
174
- try {
175
- const snapshots = await handoffStore.listAsync(aid);
176
- files = snapshots.length;
177
- plan.handoffSnapshots.set(aid, snapshots);
178
- if (snapshots.some(needsHandoffRecovery))
179
- plan.priorityAids.add(aid);
180
- }
181
- catch (error) {
182
- uncertain(aid, error);
183
- }
184
- options.onScan?.({ phase: 'handoff', aid, durationMs: Date.now() - started, files });
185
- started = Date.now();
186
- files = 0;
187
- let chats = 0;
188
- try {
189
- for (const chat of await scanAgentChatDirsAsync(options.sessionsRoot, aid, undefined, { includeEntries: true })) {
190
- chats++;
191
- const dirs = [{ dirPath: chat.dirPath, names: chat.entries.map(entry => entry.name) }];
192
- if (chat.entries.some(entry => entry.name === '_threads')) {
193
- const dirPath = path.join(chat.dirPath, '_threads');
194
- try {
195
- dirs.push({ dirPath, names: await fs.promises.readdir(dirPath) });
196
- }
197
- catch (error) {
198
- if (error.code !== 'ENOENT')
199
- throw error;
200
- }
188
+ const loopDelay = monitorEventLoopDelay({ resolution: 20 });
189
+ const loopStart = performance.eventLoopUtilization();
190
+ loopDelay.enable();
191
+ try {
192
+ await Promise.all([daemonTriggerScan, ...Array.from({ length: Math.min(4, aids.length) }, async () => {
193
+ while (next < aids.length) {
194
+ const aid = aids[next++];
195
+ const started = Date.now();
196
+ let files = 0;
197
+ let chats = 0;
198
+ let directoryMs = 0;
199
+ let threadDirectoryMs = 0;
200
+ let metadataMs = 0;
201
+ let readMaxMs = 0;
202
+ const io = { openMs: 0, statMs: 0, readMs: 0, parseMs: 0, closeMs: 0, bytes: 0 };
203
+ try {
204
+ const hintVersion = pendingHintDirectoryVersion();
205
+ let phaseStarted = performance.now();
206
+ let chatDirs;
207
+ try {
208
+ chatDirs = await scanAgentChatDirsAsync(options.sessionsRoot, aid, undefined, { includeEntries: true });
201
209
  }
202
- for (const dir of dirs) {
203
- const names = dir.names.filter(name => /^meta_.*\.jsonl$/.test(name));
204
- files += names.length;
205
- for (let offset = 0; offset < names.length; offset += 8) {
206
- const records = await Promise.allSettled(names.slice(offset, offset + 8).map(name => readLastJsonlLineAsync(path.join(dir.dirPath, name), path.basename(dir.dirPath) === '_threads')));
207
- // Do not release classification while another read in a failed
208
- // batch is still able to mutate the work plan.
209
- for (const record of records) {
210
- if (record.status === 'rejected')
211
- throw record.reason;
212
- if (!record.value)
213
- continue;
214
- const session = fileToSession(record.value);
215
- if (!session.processingState)
216
- continue;
217
- const startedAt = Number.parseInt(session.processingState.split(':', 1)[0], 10);
218
- if (Number.isFinite(startedAt) && now - startedAt < 3_600_000) {
219
- plan.pendingSessions.push(session);
220
- plan.priorityAids.add(aid);
221
- plan.requiredChannelKeys.add(session.channel);
222
- }
223
- else
224
- plan.staleSessions.push(session);
210
+ finally {
211
+ directoryMs = Math.round(performance.now() - phaseStarted);
212
+ }
213
+ chats = chatDirs.length;
214
+ // Keep paths only; retries read current hint events. A new hint chat
215
+ // invalidates this inventory even when created while discovery runs.
216
+ if (hintVersion === pendingHintDirectoryVersion())
217
+ plan.hintDirectories.set(aid, {
218
+ sessionsDir: options.sessionsRoot, selfAID: aid, version: hintVersion,
219
+ chats: chatDirs.map(({ entries: _entries, ...chat }) => chat),
220
+ });
221
+ const metadata = [];
222
+ const collect = (dir, names, strict) => {
223
+ for (const name of names)
224
+ if (/^meta_.*\.jsonl$/.test(name)) {
225
+ metadata.push({ file: path.join(dir, name), strict });
226
+ files++;
227
+ }
228
+ };
229
+ for (const chat of chatDirs)
230
+ collect(chat.dirPath, chat.entries.map(entry => entry.name), false);
231
+ phaseStarted = performance.now();
232
+ try {
233
+ await scanStartupItems(chatDirs.filter(chat => chat.entries.some(entry => entry.name === '_threads')), 8, async (chat) => {
234
+ const dir = path.join(chat.dirPath, '_threads');
235
+ try {
236
+ collect(dir, await fs.promises.readdir(dir), true);
225
237
  }
226
- }
238
+ catch (error) {
239
+ if (error.code !== 'ENOENT')
240
+ throw error;
241
+ }
242
+ });
243
+ }
244
+ finally {
245
+ threadDirectoryMs = Math.round(performance.now() - phaseStarted);
246
+ }
247
+ // The eight-reader budget spans all chats of this Agent. A slow file
248
+ // must not serialize the next chat or a complete batch of eight files.
249
+ phaseStarted = performance.now();
250
+ try {
251
+ await scanStartupItems(metadata, 8, async ({ file, strict }) => {
252
+ const readStarted = performance.now();
253
+ let record;
254
+ try {
255
+ record = await readLastJsonlLineAsync(file, strict, io);
256
+ }
257
+ finally {
258
+ readMaxMs = Math.max(readMaxMs, Math.round(performance.now() - readStarted));
259
+ }
260
+ if (!record)
261
+ return;
262
+ const session = fileToSession(record);
263
+ if (!session.processingState)
264
+ return;
265
+ const startedAt = Number.parseInt(session.processingState.split(':', 1)[0], 10);
266
+ if (Number.isFinite(startedAt) && now - startedAt < 3_600_000) {
267
+ plan.pendingSessions.push(session);
268
+ prioritize(aid, 'sessions');
269
+ plan.requiredChannelKeys.add(session.channel);
270
+ }
271
+ else
272
+ plan.staleSessions.push(session);
273
+ });
274
+ }
275
+ finally {
276
+ metadataMs = Math.round(performance.now() - phaseStarted);
227
277
  }
228
278
  }
279
+ catch (error) {
280
+ plan.hintDirectories.delete(aid);
281
+ plan.sessionScanFailed = true;
282
+ uncertain(aid, error);
283
+ }
284
+ for (const key of Object.keys(io))
285
+ io[key] = Math.round(io[key]);
286
+ options.onScan?.({ phase: 'sessions', aid, durationMs: Date.now() - started, files, directories: chats,
287
+ directoryMs, threadDirectoryMs, metadataMs, readMaxMs, io });
288
+ if (aid === options.daemonTriggerAid)
289
+ await daemonTriggerScan;
290
+ else
291
+ await scanTriggers(aid);
292
+ if (aid === options.primaryAid)
293
+ await daemonTriggerScan;
294
+ options.onAgentDiscovered?.(aid, plan);
229
295
  }
230
- catch (error) {
231
- plan.sessionScanFailed = true;
232
- uncertain(aid, error);
233
- }
234
- options.onScan?.({ phase: 'sessions', aid, durationMs: Date.now() - started, files, directories: chats });
235
- if (aid === options.daemonTriggerAid)
236
- await daemonTriggerScan;
237
- else
238
- await scanTriggers(aid);
239
- if (aid === options.primaryAid)
240
- await daemonTriggerScan;
241
- options.onAgentDiscovered?.(aid, plan);
242
- }
243
- })]);
296
+ })]);
297
+ }
298
+ finally {
299
+ loopDelay.disable();
300
+ const loop = performance.eventLoopUtilization(loopStart);
301
+ options.onDiagnostics?.({ loopMaxMs: Math.round(loopDelay.max / 1e6),
302
+ loopActiveMs: Math.round(loop.active), loopIdleMs: Math.round(loop.idle) });
303
+ }
244
304
  return plan;
245
305
  }
246
306
  /** Bounded admission for startup side effects. Dependency waits belong outside this queue. */
247
307
  export class StartupTaskQueue {
248
308
  concurrency;
249
309
  intervalMs;
250
- backgroundConcurrency;
251
310
  pending = [];
252
311
  active = 0;
253
- activeBackground = 0;
254
312
  stopped = false;
255
313
  timer;
256
- constructor(concurrency = 2, intervalMs = 50, backgroundConcurrency = concurrency) {
314
+ constructor(concurrency = 2, intervalMs = 50) {
257
315
  this.concurrency = concurrency;
258
316
  this.intervalMs = intervalMs;
259
- this.backgroundConcurrency = backgroundConcurrency;
260
- if (!Number.isInteger(concurrency) || concurrency < 1 || !Number.isFinite(intervalMs) || intervalMs < 0
261
- || !Number.isInteger(backgroundConcurrency) || backgroundConcurrency < 1 || backgroundConcurrency > concurrency) {
317
+ if (!Number.isInteger(concurrency) || concurrency < 1 || !Number.isFinite(intervalMs) || intervalMs < 0) {
262
318
  throw new Error('Invalid startup task queue limits');
263
319
  }
264
320
  }
@@ -271,11 +327,6 @@ export class StartupTaskQueue {
271
327
  this.schedule();
272
328
  return result;
273
329
  }
274
- /** Once priority work is ready (or degraded), background work may use all slots. */
275
- releaseBackground() {
276
- this.backgroundConcurrency = this.concurrency;
277
- this.schedule();
278
- }
279
330
  stop() {
280
331
  this.stopped = true;
281
332
  if (this.timer)
@@ -287,23 +338,19 @@ export class StartupTaskQueue {
287
338
  schedule() {
288
339
  if (this.stopped || this.timer || this.active >= this.concurrency || !this.pending.length)
289
340
  return;
290
- if (this.activeBackground >= this.backgroundConcurrency
291
- && !this.pending.some(task => task.priority === 'foreground'))
292
- return;
293
341
  // Yield between admissions even when tasks finish synchronously.
294
342
  this.timer = setTimeout(() => {
295
343
  this.timer = undefined;
296
344
  // Choose at admission time, so newly classified priority work can pass
297
- // queued idle channels without interrupting an existing connection.
345
+ // queued idle channels. Never hold a free slot for unclassified work;
346
+ // already-running connections finish within the existing concurrency cap.
298
347
  let index = this.pending.findIndex(task => task.priority === 'foreground');
299
- if (index < 0 && this.activeBackground < this.backgroundConcurrency)
348
+ if (index < 0)
300
349
  index = 0;
301
- const task = index < 0 ? undefined : this.pending.splice(index, 1)[0];
350
+ const task = this.pending.splice(index, 1)[0];
302
351
  if (!task)
303
352
  return;
304
353
  this.active++;
305
- if (task.priority === 'background')
306
- this.activeBackground++;
307
354
  void Promise.resolve().then(async () => {
308
355
  if (this.stopped || !task.valid())
309
356
  return false;
@@ -311,8 +358,6 @@ export class StartupTaskQueue {
311
358
  return true;
312
359
  }).then(task.resolve, task.reject).finally(() => {
313
360
  this.active--;
314
- if (task.priority === 'background')
315
- this.activeBackground--;
316
361
  this.schedule();
317
362
  });
318
363
  this.schedule();
@@ -361,118 +406,146 @@ export function daemonConversationTotalExecutionMs(settings) {
361
406
  ? seconds * 1000
362
407
  : undefined;
363
408
  }
364
- export async function recoverStartupHandoffs({ channelInstances, recoveryAids, agentRegistry, queuePendingObserverHints, startupObserverRecoveries, handoffRuntime, cleanupAgentHandoffs, trace, setStartupRecoveryPending, onStartupHintsRecovered, onAgentHintsRecovered, beforeAgentRecovery, waitForNormalReady, isCancelled, }) {
365
- const terminalAudits = new Map();
366
- const loopDelay = monitorEventLoopDelay({ resolution: 20 });
367
- const utilizationStart = performance.eventLoopUtilization();
368
- loopDelay.enable();
369
- try {
370
- // Registration is local and scoped to each Agent. Never wait for all transports.
371
- await Promise.all(startupObserverRecoveries);
372
- const outcomes = await Promise.allSettled(recoveryAids.map(async (aid) => {
373
- // Cleanup only gates this Agent; another Agent's history must not hold
374
- // its restored input behind a global cleanup barrier.
375
- await beforeAgentRecovery?.(aid);
376
- if (isCancelled?.())
409
+ /** Observer hints are foreground registration; Handoff history is independent. */
410
+ export async function recoverStartupObserverHints(options) {
411
+ await Promise.all(options.startupObserverRecoveries);
412
+ await Promise.all(options.recoveryAids.map(async (aid) => {
413
+ await options.beforeAgentRecovery?.(aid);
414
+ while (!options.isCancelled()) {
415
+ const started = Date.now();
416
+ try {
417
+ const results = await Promise.allSettled(options.channelInstances
418
+ .filter(inst => inst.channelType === 'aun'
419
+ && options.agentRegistry.resolveByChannel(inst.adapter.channelKey)?.aid === aid)
420
+ .map(inst => options.queuePendingObserverHints(aid, inst.adapter.channelKey)));
421
+ const failure = results.find(result => result.status === 'rejected');
422
+ if (failure?.status === 'rejected')
423
+ throw failure.reason;
424
+ if (options.isCancelled())
425
+ return;
426
+ options.trace?.addSpan('daemon.observerHints', started, Date.now(), aid, 'ok');
427
+ options.onAgentHintsRecovered(aid);
377
428
  return;
378
- while (!isCancelled?.()) {
379
- const agentStarted = Date.now();
429
+ }
430
+ catch (error) {
431
+ options.trace?.addSpan('daemon.observerHints', started, Date.now(), `${aid}; retry pending`);
432
+ logger.warn(`[startup] observer hint registration waits for ${aid}: ${error}`);
433
+ await recoveryRetryDelay();
434
+ }
435
+ }
436
+ }));
437
+ if (options.isCancelled())
438
+ return;
439
+ options.setStartupRecoveryPending(false);
440
+ options.startupObserverRecoveries.length = 0;
441
+ }
442
+ function recoveryRetryDelay() {
443
+ return new Promise(resolve => { const timer = setTimeout(resolve, 1_000); timer.unref?.(); });
444
+ }
445
+ /**
446
+ * Background recovery never gates Ready. Until an Agent's scan completes its
447
+ * inputs stay queued; afterwards only sessions referenced by unfinished
448
+ * Handoffs wait for durable local recovery. No Runner is loaded by scanning.
449
+ */
450
+ export class StartupHandoffRecovery {
451
+ options;
452
+ states = new Map();
453
+ running;
454
+ constructor(options) {
455
+ this.options = options;
456
+ for (const aid of options.aids)
457
+ this.states.set(aid, { phase: 'waiting' });
458
+ }
459
+ blockedReason(aid, sessionId) {
460
+ const state = this.states.get(aid);
461
+ if (!state || state.phase === 'ready')
462
+ return;
463
+ if (!state.sessions)
464
+ return 'startup Handoff scan';
465
+ if (state.sessions.has(sessionId))
466
+ return 'session Handoff recovery';
467
+ }
468
+ status() {
469
+ const states = [...this.states.values()];
470
+ return { completed: states.filter(state => state.phase === 'ready').length,
471
+ total: states.length, retrying: states.filter(state => state.phase === 'retrying').length };
472
+ }
473
+ run(waitForReady) {
474
+ return this.running ??= this.recover(waitForReady);
475
+ }
476
+ async recover(waitForReady) {
477
+ if (!await waitForReady() || this.options.isCancelled())
478
+ return;
479
+ const { runtime, trace, isCancelled, onProgress } = this.options;
480
+ const store = this.options.store ?? new HandoffStore();
481
+ const audits = new Map();
482
+ await Promise.all([...this.states].map(async ([aid, state]) => {
483
+ while (!isCancelled()) {
484
+ const started = Date.now();
380
485
  try {
381
- const options = {
382
- isCancelled,
383
- onPhase: (phase, start, end, detail, status) => trace?.addSpan(`daemon.handoffRecovery.${phase}`, start, end, detail ? `${aid}; ${detail}` : aid, status),
384
- };
385
- const snapshots = await cleanupAgentHandoffs?.(aid, options);
386
- if (isCancelled?.())
486
+ state.phase = 'recovering';
487
+ let scanDetail = '';
488
+ const snapshots = await store.listAsync(aid, stats => {
489
+ scanDetail = Object.entries(stats).map(([key, value]) => `${key}=${Math.round(value)}`).join('; ');
490
+ });
491
+ if (isCancelled())
387
492
  return;
388
- const hintsStarted = Date.now();
389
- const hints = channelInstances
390
- .filter(inst => inst.channelType === 'aun'
391
- && agentRegistry.resolveByChannel(inst.adapter.channelKey)?.aid === aid)
392
- .map(inst => queuePendingObserverHints(aid, inst.adapter.channelKey));
393
- const results = await Promise.allSettled(hints);
394
- const failure = results.find(result => result.status === 'rejected');
395
- trace?.addSpan('daemon.handoffRecovery.hints', hintsStarted, Date.now(), failure ? `${aid}; retry pending` : aid, failure ? undefined : 'ok');
396
- if (failure?.status === 'rejected')
397
- throw failure.reason;
398
- if (isCancelled?.())
493
+ trace?.addSpan('daemon.handoffRecovery.scan', started, Date.now(), `${aid}; files=${snapshots.length}${scanDetail ? '; ' + scanDetail : ''}`, 'ok');
494
+ const pending = snapshots.filter(needsHandoffRecovery);
495
+ state.sessions = new Set(pending.flatMap(item => [item.origin_session_id, item.target_session_id]));
496
+ onProgress(); // Unrelated sessions need not wait for journal reconciliation.
497
+ const options = { snapshots, isCancelled,
498
+ prioritizeOrigin: true,
499
+ onPhase: (phase, from, to, detail, status) => trace?.addSpan(`daemon.handoffRecovery.${phase}`, from, to, detail ? `${aid}; ${detail}` : aid, status) };
500
+ await runtime.prepareRecovery(aid, options);
501
+ if (isCancelled())
399
502
  return;
400
- // recover persists local origin inputs; remote sends use the dispatcher.
401
- await handoffRuntime.recover([aid], { ...options, discardExpired: false,
402
- ...(snapshots ? { snapshots: snapshots.filter(needsHandoffRecovery) } : {}) });
403
- trace?.addSpan('daemon.handoffRecovery.agent', agentStarted, Date.now(), aid, isCancelled?.() ? 'cancelled' : 'ok');
404
- if (!isCancelled?.()) {
405
- const terminal = snapshots?.filter(snapshot => !needsHandoffRecovery(snapshot));
406
- if (terminal?.length)
407
- terminalAudits.set(aid, terminal);
408
- onAgentHintsRecovered?.(aid);
409
- }
503
+ await runtime.recover([aid], { ...options, snapshots: pending, discardExpired: false });
504
+ if (isCancelled())
505
+ return;
506
+ const terminal = snapshots.filter(item => !needsHandoffRecovery(item));
507
+ if (terminal.length)
508
+ audits.set(aid, terminal);
509
+ state.phase = 'ready';
510
+ state.sessions.clear();
511
+ trace?.addSpan('daemon.handoffRecovery.agent', started, Date.now(), aid, 'ok');
512
+ onProgress();
410
513
  return;
411
514
  }
412
515
  catch (error) {
413
- // This attempt will be retried. A failed span would permanently
414
- // mark the whole startup failed even after a successful recovery.
415
- trace?.addSpan('daemon.handoffRecovery.agent', agentStarted, Date.now(), `${aid}; retry pending`);
416
- logger.warn(`[Handoff] startup registration waits for ${aid}: ${error}`);
417
- await new Promise(resolve => { const timer = setTimeout(resolve, 1_000); timer.unref?.(); });
516
+ state.phase = 'retrying';
517
+ trace?.addSpan('daemon.handoffRecovery.agent', started, Date.now(), `${aid}; retry pending`);
518
+ logger.warn(`[Handoff] background recovery waits for ${aid}: ${error}`);
519
+ await recoveryRetryDelay();
418
520
  }
419
521
  }
420
522
  }));
421
- outcomes.forEach((outcome, index) => {
422
- if (outcome.status === 'rejected') {
423
- logger.error(`[Handoff] startup recovery failed for ${recoveryAids[index]}:`, outcome.reason);
424
- }
425
- });
426
- }
427
- finally {
428
- loopDelay.disable();
429
- const utilization = performance.eventLoopUtilization(utilizationStart);
430
- const diagnostics = { loopMaxMs: Math.round(loopDelay.max / 1e6),
431
- loopP99Ms: Math.round(loopDelay.percentile(99) / 1e6),
432
- loopActiveMs: Math.round(utilization.active), loopIdleMs: Math.round(utilization.idle) };
433
- for (const [key, value] of Object.entries(diagnostics))
434
- trace?.setMeta?.(`handoffRecovery.${key}`, String(value));
435
- logger.info(`[Handoff] startup scheduling: ${Object.entries(diagnostics).map(([key, value]) => `${key}=${value}`).join(' ')}`);
436
- // Individual failed Agents remain blocked; completion does not manufacture readiness.
437
- setStartupRecoveryPending(false);
438
- onStartupHintsRecovered?.();
439
- startupObserverRecoveries.length = 0;
440
- }
441
- // Start only after every Agent's foreground registration has settled. Audit
442
- // failures retry independently and never hold restored input or normal Ready.
443
- if (!terminalAudits.size || isCancelled?.())
444
- return;
445
- const finishAudit = trace?.startTask?.('daemon.handoffTerminalAuditComplete');
446
- let auditSkipped = false;
447
- void (async () => {
448
- if (waitForNormalReady && !await waitForNormalReady()) {
449
- auditSkipped = true;
450
- return;
451
- }
452
- if (isCancelled?.())
523
+ if (!audits.size || isCancelled())
453
524
  return;
454
- await yieldToIo();
455
- while (terminalAudits.size && !isCancelled?.()) {
456
- for (const [aid, snapshots] of terminalAudits) {
457
- if (isCancelled?.())
525
+ const finish = trace?.startTask?.('daemon.handoffTerminalAuditComplete');
526
+ while (audits.size && !isCancelled()) {
527
+ for (const [aid, snapshots] of audits) {
528
+ if (isCancelled())
529
+ break;
530
+ await yieldToIo();
531
+ if (isCancelled())
458
532
  break;
459
533
  const started = Date.now();
460
534
  try {
461
- await handoffRuntime.recover([aid], { snapshots, discardExpired: false, isCancelled,
462
- onPhase: (phase, start, end, detail, status) => trace?.addSpan(`daemon.handoffTerminalAudit.${phase}`, start, end, detail ? `${aid}; ${detail}` : aid, status) });
463
- trace?.addSpan('daemon.handoffTerminalAudit.agent', started, Date.now(), aid, isCancelled?.() ? 'cancelled' : 'ok');
464
- terminalAudits.delete(aid);
535
+ await runtime.recover([aid], { snapshots, discardExpired: false, isCancelled,
536
+ onPhase: (phase, from, to, detail, status) => trace?.addSpan(`daemon.handoffTerminalAudit.${phase}`, from, to, detail ? `${aid}; ${detail}` : aid, status) });
537
+ trace?.addSpan('daemon.handoffTerminalAudit.agent', started, Date.now(), aid, isCancelled() ? 'cancelled' : 'ok');
538
+ audits.delete(aid);
465
539
  }
466
540
  catch (error) {
467
541
  logger.warn(`[Handoff] terminal audit retry pending for ${aid}: ${error}`);
468
542
  }
469
543
  }
470
- if (terminalAudits.size && !isCancelled?.()) {
471
- await new Promise(resolve => { const timer = setTimeout(resolve, 1_000); timer.unref?.(); });
472
- }
544
+ if (audits.size && !isCancelled())
545
+ await recoveryRetryDelay();
473
546
  }
474
- })().catch(error => logger.warn(`[Handoff] terminal audit failed: ${error}`))
475
- .finally(() => finishAudit?.(isCancelled?.() ? 'cancelled' : auditSkipped ? 'skipped' : 'ok'));
547
+ finish?.(isCancelled() ? 'cancelled' : 'ok');
548
+ }
476
549
  }
477
550
  export function resumePendingSessions({ sessionManager, messageQueue, droppedTriggerSessionIds, agentRegistry, agentMap, pendingSessions = sessionManager.getPendingProcessingSessions(), }) {
478
551
  if (pendingSessions.length === 0)