agl 43.3.0 → 43.3.1

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 (71) hide show
  1. package/changelog.md +9 -0
  2. package/dist_serve/bundle.js +2 -2
  3. package/dist_serve/bundle.js.map +2 -2
  4. package/dist_ts/00_commitinfo_data.js +1 -1
  5. package/dist_ts/classes.authstore.d.ts +7 -0
  6. package/dist_ts/classes.authstore.js +9 -1
  7. package/dist_ts/classes.claudeharness.d.ts +13 -2
  8. package/dist_ts/classes.claudeharness.js +12 -5
  9. package/dist_ts/classes.controller.d.ts +27 -6
  10. package/dist_ts/classes.controller.js +136 -39
  11. package/dist_ts/classes.mcpcontrollerhost.js +4 -1
  12. package/dist_ts/classes.mcptools.js +6 -1
  13. package/dist_ts/classes.nativesessions.d.ts +12 -0
  14. package/dist_ts/classes.nativesessions.js +1 -1
  15. package/dist_ts/classes.workercallers.js +4 -2
  16. package/dist_ts/driver/classes.directreports.js +19 -19
  17. package/dist_ts/driver/classes.directreportstore.d.ts +8 -1
  18. package/dist_ts/driver/classes.directreportstore.js +20 -10
  19. package/dist_ts/fleet/classes.workers.d.ts +16 -0
  20. package/dist_ts/fleet/classes.workers.js +73 -39
  21. package/dist_ts/fleet/classes.workerstore.js +14 -8
  22. package/dist_ts/fleet/functions.workervalidation.js +10 -3
  23. package/dist_ts/fleet/interfaces.workers.d.ts +6 -2
  24. package/dist_ts/fleet/interfaces.workers.js +8 -4
  25. package/dist_ts/functions.deviceapi.d.ts +50 -3
  26. package/dist_ts/functions.deviceapi.js +174 -7
  27. package/dist_ts/functions.exactpersistence.d.ts +3 -0
  28. package/dist_ts/functions.exactpersistence.js +4 -0
  29. package/dist_ts/functions.mcpfleetworkertools.js +2 -2
  30. package/dist_ts/functions.ticketactor.d.ts +17 -1
  31. package/dist_ts/functions.ticketactor.js +55 -15
  32. package/dist_ts_interfaces/devices.d.ts +17 -4
  33. package/dist_ts_interfaces/devices.js +1 -1
  34. package/dist_ts_interfaces/fleetworkers.d.ts +32 -7
  35. package/dist_ts_interfaces/fleetworkers.js +19 -8
  36. package/dist_ts_interfaces/workercallers.d.ts +2 -0
  37. package/dist_ts_migration/classes.documentmigrationrunner.d.ts +14 -0
  38. package/dist_ts_migration/classes.documentmigrationrunner.js +20 -1
  39. package/dist_ts_migration/index.d.ts +1 -0
  40. package/dist_ts_migration/index.js +2 -1
  41. package/dist_ts_migration/v43_ticketactornames.d.ts +32 -0
  42. package/dist_ts_migration/v43_ticketactornames.js +236 -0
  43. package/package.json +1 -1
  44. package/readme.md +34 -3
  45. package/ts/00_commitinfo_data.ts +1 -1
  46. package/ts/classes.authstore.ts +10 -0
  47. package/ts/classes.claudeharness.ts +18 -4
  48. package/ts/classes.controller.ts +142 -40
  49. package/ts/classes.mcpcontrollerhost.ts +3 -0
  50. package/ts/classes.mcptools.ts +5 -0
  51. package/ts/classes.nativesessions.ts +13 -0
  52. package/ts/classes.workercallers.ts +3 -1
  53. package/ts/driver/classes.directreports.ts +18 -18
  54. package/ts/driver/classes.directreportstore.ts +20 -9
  55. package/ts/fleet/classes.workers.ts +66 -39
  56. package/ts/fleet/classes.workerstore.ts +11 -7
  57. package/ts/fleet/functions.workervalidation.ts +7 -2
  58. package/ts/fleet/interfaces.workers.ts +6 -2
  59. package/ts/functions.deviceapi.ts +227 -6
  60. package/ts/functions.exactpersistence.ts +5 -0
  61. package/ts/functions.mcpfleetworkertools.ts +1 -1
  62. package/ts/functions.ticketactor.ts +58 -14
  63. package/ts_interfaces/devices.schema.json +5 -2
  64. package/ts_interfaces/devices.ts +20 -4
  65. package/ts_interfaces/fleetworkers.ts +33 -7
  66. package/ts_interfaces/workercallers.ts +2 -0
  67. package/ts_migration/classes.documentmigrationrunner.ts +21 -0
  68. package/ts_migration/index.ts +1 -0
  69. package/ts_migration/v43_ticketactornames.ts +225 -0
  70. package/ts_web/00_commitinfo_data.ts +1 -1
  71. package/ts_web/elements.fleetworker.ts +4 -2
@@ -1,4 +1,5 @@
1
1
  import * as plugins from '../plugins.js';
2
+ import { exactError } from '../functions.exactpersistence.js';
2
3
  import type { IDirectReport } from '../../ts_interfaces/directreports.js';
3
4
 
4
5
  /**
@@ -62,12 +63,22 @@ export interface IDirectReportStore {
62
63
  update(owner: string, name: string, change: (report: IDirectReport) => void): Promise<IDirectReport>;
63
64
  }
64
65
 
66
+ /**
67
+ * A refusal or failure of the direct reports whose message AGL writes itself, never a dependency's text: the Driver view
68
+ * and a device show it as it is. A dependency's error it stands for is its `cause`, which the controller journals.
69
+ */
70
+ export class DirectReportError extends Error {
71
+ constructor(messageArg: string, optionsArg?: ErrorOptions) {
72
+ super(messageArg, optionsArg);
73
+ this.name = 'DirectReportError';
74
+ }
75
+ }
76
+
65
77
  /** Another write changed the report between its read and this write. */
66
- export class DirectReportConflictError extends Error {
67
- constructor() { super('The direct report changed concurrently.'); }
78
+ export class DirectReportConflictError extends DirectReportError {
79
+ constructor() { super('The direct report changed concurrently.'); this.name = 'DirectReportConflictError'; }
68
80
  }
69
81
 
70
- const exactError = (error: unknown, code: string): boolean => error instanceof plugins.nosqldb.SmartdataExactPersistenceError && error.code === code;
71
82
  type TStoredReport = plugins.nosqldb.TStoredDocument<IDirectReportDocument>;
72
83
  const persisted = (record: TStoredReport): IDirectReport => structuredClone(DirectReportModel.exact.toPersisted(record).report);
73
84
  const sessionTaken = 'Another active direct report already holds this session.';
@@ -76,7 +87,7 @@ const sessionTaken = 'Another active direct report already holds this session.';
76
87
  export class DirectReportStore implements IDirectReportStore {
77
88
  public async list(owner: string): Promise<IDirectReport[]> {
78
89
  const records = await DirectReportModel.exact.findStored({ filter: { owner }, sort: { id: 1 }, limit: 257 });
79
- if (records.length > 256) throw new Error('Direct report capacity exceeded.');
90
+ if (records.length > 256) throw new DirectReportError('Direct report capacity exceeded.');
80
91
  return records.map(persisted);
81
92
  }
82
93
 
@@ -90,10 +101,10 @@ export class DirectReportStore implements IDirectReportStore {
90
101
  ...(report.state === 'active' ? { activeSessionKey: report.sessionId } : {}) };
91
102
  try {
92
103
  const result = await DirectReportModel.exact.insert(candidate);
93
- if (result.status === 'conflict') throw new Error('A direct report of that name exists.');
104
+ if (result.status === 'conflict') throw new DirectReportError('A direct report of that name exists.');
94
105
  return persisted(result.document);
95
106
  } catch (error) {
96
- if (exactError(error, 'unique_conflict')) throw new Error(sessionTaken, { cause: error });
107
+ if (exactError(error, 'unique_conflict')) throw new DirectReportError(sessionTaken, { cause: error });
97
108
  if (!exactError(error, 'ambiguous_write')) throw error;
98
109
  return this.confirm(candidate, error);
99
110
  }
@@ -101,7 +112,7 @@ export class DirectReportStore implements IDirectReportStore {
101
112
 
102
113
  public async update(owner: string, name: string, change: (report: IDirectReport) => void): Promise<IDirectReport> {
103
114
  const current = await DirectReportModel.exact.findStoredOne({ id: `${owner}:${name}`, owner });
104
- if (!current) throw new Error('The direct report is unavailable.');
115
+ if (!current) throw new DirectReportError('The direct report is unavailable.');
105
116
  const next = structuredClone(DirectReportModel.exact.toPersisted(current));
106
117
  change(next.report); next.report.updatedAt = new Date().toISOString(); next.updateId = plugins.crypto.randomUUID();
107
118
  const activeSessionKey = next.report.state === 'active' ? next.report.sessionId : undefined;
@@ -113,7 +124,7 @@ export class DirectReportStore implements IDirectReportStore {
113
124
  if (result.status !== 'transitioned') throw new DirectReportConflictError();
114
125
  return persisted(result.document);
115
126
  } catch (error) {
116
- if (exactError(error, 'unique_conflict')) throw new Error(sessionTaken, { cause: error });
127
+ if (exactError(error, 'unique_conflict')) throw new DirectReportError(sessionTaken, { cause: error });
117
128
  if (!exactError(error, 'ambiguous_write')) throw error;
118
129
  return this.confirm(next, error);
119
130
  }
@@ -122,6 +133,6 @@ export class DirectReportStore implements IDirectReportStore {
122
133
  private async confirm(expected: IDirectReportDocument, error: unknown): Promise<IDirectReport> {
123
134
  const record = await DirectReportModel.exact.findStoredOne({ id: expected.id });
124
135
  if (record?.updateId === expected.updateId) return persisted(record);
125
- throw new Error('The direct report write outcome is unknown; read the direct reports before retrying.', { cause: error });
136
+ throw new DirectReportError('The direct report write outcome is unknown; read the direct reports before retrying.', { cause: error });
126
137
  }
127
138
  }
@@ -88,6 +88,8 @@ export class FleetWorkers {
88
88
  private readonly backends: { claude: IFleetWorkerBackend; codex: IFleetWorkerBackend };
89
89
  private readonly jobs = new Map<string, IOwnedWorkerJob>();
90
90
  private readonly queues = new Map<string, Promise<unknown>>();
91
+ /** The jobs whose dispatch may have reached a native session; see `dispatch`. */
92
+ private readonly dispatchedJobs = new WeakSet<IFleetWorkerJob>();
91
93
  /** Each owner's running repair of what follows its native sessions; see `repairBindings`. */
92
94
  private readonly bindingRepairs = new Map<string, Promise<IBindingRepair>>();
93
95
  private bindingRevision = 0;
@@ -245,9 +247,8 @@ export class FleetWorkers {
245
247
  // Like every fleet refusal, a session the send may not wake fails the job with its reason.
246
248
  const snapshot: IFleetWorkerJob = { id: plugins.crypto.randomUUID(), action: 'native-message', state: 'running' };
247
249
  const job: IOwnedWorkerJob = { owner, snapshot, completion: Promise.resolve() }; this.jobs.set(snapshot.id, job);
248
- job.completion = nativeMessages.send(owner, input as TFleetWorkerRequest<'native-message'>, actor)
249
- .then((receipt) => { snapshot.nativeMessage = receipt; snapshot.state = 'succeeded'; },
250
- (error: unknown) => { snapshot.state = 'failed'; snapshot.error = this.error(error); });
250
+ job.completion = this.dispatch(snapshot, () => nativeMessages.send(owner, input as TFleetWorkerRequest<'native-message'>, actor))
251
+ .then((receipt) => { snapshot.nativeMessage = receipt; snapshot.state = 'succeeded'; }, (error: unknown) => this.failJob(snapshot, error));
251
252
  return { job: this.publicJob(snapshot) } as TFleetWorkerResponseTo<T, R>;
252
253
  }
253
254
  const profiles = validateFleetWorkerProfiles(configuration.workerProfiles ?? []);
@@ -267,8 +268,8 @@ export class FleetWorkers {
267
268
  // Adoptions of one native session run one at a time, whatever their names and owners: a relaunch of a session
268
269
  // another adoption is binding would start a second process on it.
269
270
  const adopted = action === 'adopt' ? (input as TFleetWorkerRequest<'adopt'>).nativeId : undefined;
270
- job.completion = (recoveringActiveJob ? Promise.reject(new Error('Worker job is still running; inspect it before recovery.'))
271
- : this.exclusive(owner, names, async () => adopted === undefined ? await run() : await this.exclusive('', [`native:${adopted}`], run))).catch((error: unknown) => { snapshot.state = 'failed'; snapshot.error = this.error(error); });
271
+ job.completion = (recoveringActiveJob ? Promise.reject(new FleetWorkerError('worker_fenced', 'Worker job is still running; inspect it before recovery.'))
272
+ : this.exclusive(owner, names, async () => adopted === undefined ? await run() : await this.exclusive('', [`native:${adopted}`], run))).catch((error: unknown) => this.failJob(snapshot, error));
272
273
  return { job: this.publicJob(snapshot) } as TFleetWorkerResponseTo<T, R>;
273
274
  }
274
275
  /**
@@ -290,7 +291,7 @@ export class FleetWorkers {
290
291
  this.abort.signal.throwIfAborted(); signal?.throwIfAborted();
291
292
  const { worker } = await this.store.get(owner, name), backend = this.backends[worker.harness];
292
293
  if (worker.lostDispatch) return { ...this.view(worker), bundles: [], earlier: false };
293
- if (!worker.nativeId) throw new Error('Worker has no native identity yet.');
294
+ if (!worker.nativeId) throw new FleetWorkerError('worker_fenced', 'Worker has no native identity yet.');
294
295
  const page = await backend.history(worker, worker.profile, limit, before);
295
296
  signal?.throwIfAborted();
296
297
  return { ...this.view(worker), ...page };
@@ -307,7 +308,7 @@ export class FleetWorkers {
307
308
  private nativeBackend<K extends 'nativeHistory' | 'nativeSend' | 'nativeTurn' | 'nativeAttention' | 'nativeReply'>(harness: IFleetWorker['harness'], method: K): NonNullable<IFleetWorkerBackend[K]> {
308
309
  this.abort.signal.throwIfAborted();
309
310
  const backend = this.backends[harness], operation = backend[method];
310
- if (!operation) throw new Error(`The ${harness} backend does not serve native sessions.`);
311
+ if (!operation) throw new FleetWorkerError('worker_conflict', `The ${harness} backend does not serve native sessions.`);
311
312
  return operation.bind(backend) as NonNullable<IFleetWorkerBackend[K]>;
312
313
  }
313
314
  /** A listed native session's transcript page, read-only, through the reader its harness's workers use. */
@@ -329,7 +330,7 @@ export class FleetWorkers {
329
330
  public async relaunchBlocker(configuration: IFleetConfiguration, profileId: string, nativeId: string, cwd: string): Promise<IFleetRelaunchBlocker | undefined> {
330
331
  this.abort.signal.throwIfAborted();
331
332
  const profile = this.profile(validateFleetWorkerProfiles(configuration.workerProfiles ?? []), profileId), backend = this.backends[profile.harness];
332
- if (!backend.relaunchBlocker) throw new Error('Only a Claude Code session is relaunched.');
333
+ if (!backend.relaunchBlocker) throw new FleetWorkerError('worker_conflict', 'Only a Claude Code session is relaunched.');
333
334
  return await backend.relaunchBlocker(cwd, profile, nativeId);
334
335
  }
335
336
  /** Every native session of `harness` with requests its backend holds for AGL, without reading anything. */
@@ -460,10 +461,10 @@ export class FleetWorkers {
460
461
  return await this.backends.codex.threads?.(plugins.os.homedir(), maxAgeMs) ?? [];
461
462
  }
462
463
  private admitJob(): void {
463
- if (this.admissionClosed || this.abort.signal.aborted) throw new Error('The fleet is closing and admits no new worker job.');
464
+ if (this.admissionClosed || this.abort.signal.aborted) throw new FleetWorkerError('fleet_unavailable', 'The fleet is closing and admits no new worker job.');
464
465
  if (this.jobs.size < 512) return;
465
466
  for (const [id, job] of this.jobs) if (['succeeded', 'failed'].includes(job.snapshot.state)) { this.jobs.delete(id); break; }
466
- if (this.jobs.size >= 512) throw new Error('Fleet worker job capacity reached.');
467
+ if (this.jobs.size >= 512) throw new FleetWorkerError('fleet_unavailable', 'Fleet worker job capacity reached.');
467
468
  }
468
469
  /**
469
470
  * Steers the worker bound to the native session `sessionId` (`harness:nativeId`) with a ticket notice, through the
@@ -482,12 +483,12 @@ export class FleetWorkers {
482
483
  const running = this.exclusive(owner, [worker.name], async () => {
483
484
  snapshot.state = 'running'; this.abort.signal.throwIfAborted();
484
485
  const claimed = await this.claim(owner, worker.name, snapshot, false, fleetMessageDigest(text));
485
- try { await this.backends[claimed.harness].send([{ worker: claimed, profile: claimed.profile, text }]); }
486
+ try { await this.dispatch(snapshot, () => this.backends[claimed.harness].send([{ worker: claimed, profile: claimed.profile, text }])); }
486
487
  catch (error) { await this.finish(owner, claimed, snapshot, error instanceof FleetDispatchError && error.dispatched ? 'unknown' : claimed.state, this.error(error)); throw error; }
487
488
  snapshot.workers = [await this.finish(owner, claimed, snapshot, 'live')];
488
489
  return snapshot.workers[0]!;
489
490
  });
490
- job.completion = running.then(() => { snapshot.state = 'succeeded'; }, (error: unknown) => { snapshot.state = 'failed'; snapshot.error = this.error(error); });
491
+ job.completion = running.then(() => { snapshot.state = 'succeeded'; }, (error: unknown) => this.failJob(snapshot, error));
491
492
  return this.publicWorker(await running);
492
493
  }
493
494
  private publicWorker(worker: IFleetWorker): IFleetWorker {
@@ -582,11 +583,37 @@ export class FleetWorkers {
582
583
  const { stayed, revision } = await this.rebindSessions(owner, { names: [worker.name], own: worker.name,
583
584
  stayed: (failures) => failures.find((failure) => failure.workerName === worker.name) ?? failures.find((failure) => failure.nextName === worker.name) });
584
585
  await this.recordBinding(owner, worker.name, revision, stayed, (current) => {
585
- if (current.pending || current.state !== 'live') throw new Error('Worker recovery fence changed.');
586
+ if (current.pending || current.state !== 'live') throw new FleetWorkerError('worker_fenced', 'Worker recovery fence changed.');
586
587
  });
587
588
  if (stayed) throw new Error(stayed.error);
588
589
  }
589
590
  private error(error: unknown): string { return (error instanceof Error ? error.message : 'Fleet worker operation failed.').slice(0, 4096); }
591
+ /**
592
+ * Fails `job` with `error`, the one place a job failure is recorded: its message, its code exactly when the fleet
593
+ * refused it itself (`FleetWorkerError`), so a reader tells AGL's own text from a dependency's output by the code, and
594
+ * its outcome. The outcome is `refused` only where nothing can have reached a native session: the job never dispatched
595
+ * (`dispatch`) and the error is a refusal, the fleet's own or a dispatch's that sent nothing. Any other failure, a
596
+ * refusal after a dispatch (a fence the settling found changed) and every untyped error included, is `unknown`.
597
+ */
598
+ private failJob(job: IFleetWorkerJob, error: unknown): void {
599
+ job.state = 'failed'; job.error = this.error(error);
600
+ if (error instanceof FleetWorkerError) job.errorCode = error.code;
601
+ const refusal = error instanceof FleetWorkerError || error instanceof FleetDispatchError && !error.dispatched;
602
+ job.errorOutcome = refusal && !this.dispatchedJobs.has(job) ? 'refused' : 'unknown';
603
+ }
604
+ /**
605
+ * Runs `effect`, a dispatch of `job` to a native session (a start, relaunch, send, stop or archive, a native message):
606
+ * from its call on the job may have reached the session, unless it is the job's first dispatch and failed with a
607
+ * `FleetDispatchError` that sent nothing. Every native effect of a job goes through it, so `failJob` knows the outcome.
608
+ */
609
+ private async dispatch<T>(job: IFleetWorkerJob, effect: () => Promise<T>): Promise<T> {
610
+ const earlier = this.dispatchedJobs.has(job);
611
+ this.dispatchedJobs.add(job);
612
+ try { return await effect(); } catch (error) {
613
+ if (!earlier && error instanceof FleetDispatchError && !error.dispatched) this.dispatchedJobs.delete(job);
614
+ throw error;
615
+ }
616
+ }
590
617
  private async exclusive<T>(owner: string, names: string[], action: () => Promise<T>): Promise<T> {
591
618
  const keys = [...new Set(names)].sort().map((name) => `${owner}:${name}`);
592
619
  const before = keys.map((key) => this.queues.get(key) ?? Promise.resolve());
@@ -595,16 +622,16 @@ export class FleetWorkers {
595
622
  try { return await running; } finally { for (const key of keys) if (this.queues.get(key) === running) this.queues.delete(key); }
596
623
  }
597
624
  private profile(profiles: IFleetWorkerProfile[], id: string): IFleetWorkerProfile {
598
- const profile = profiles.find((item) => item.id === id); if (!profile) throw new Error('Worker profile is not configured in the AGL Configuration master.'); return structuredClone(profile);
625
+ const profile = profiles.find((item) => item.id === id); if (!profile) throw new FleetWorkerError('worker_conflict', 'Worker profile is not configured in the AGL Configuration master.'); return structuredClone(profile);
599
626
  }
600
627
  private changed(owner: string, worker: IFleetWorker): void { this.events.publish({ kind: 'worker.changed', workerId: worker.id, workerName: worker.name, ...(worker.ticketKey ? { ticketKey: worker.ticketKey } : {}), status: worker.state, ...(worker.error ? { error: worker.error } : {}) }, owner); }
601
628
  private assertTicket(worker: IFleetWorker, ticketKey: string | undefined): void {
602
- if (!ticketKey || worker.ticketKey !== ticketKey) throw new Error('Worker is not associated with this ticket; inspect or explicitly adopt its binding.');
629
+ if (!ticketKey || worker.ticketKey !== ticketKey) throw new FleetWorkerError('ticket_mismatch', 'Worker is not associated with this ticket; inspect or explicitly adopt its binding.');
603
630
  }
604
631
  private async dispatchHolder(): Promise<IFleetWorkerDispatchHolder> {
605
632
  this.holder ??= (async () => {
606
633
  const identity = await readControllerProcessIdentity(process.pid);
607
- if (!identity) throw new Error('Fleet controller process identity cannot be proven.');
634
+ if (!identity) throw new FleetWorkerError('fleet_unavailable', 'Fleet controller process identity cannot be proven.');
608
635
  return { controllerId: this.controllerId, host: plugins.os.hostname(), pid: identity.pid, fingerprint: identity.fingerprint };
609
636
  })();
610
637
  return await this.holder;
@@ -612,12 +639,12 @@ export class FleetWorkers {
612
639
  private async assertRecoverable(worker: IFleetWorker): Promise<void> {
613
640
  if (!worker.pending) return;
614
641
  const holder = worker.pending.holder;
615
- if (holder.host !== plugins.os.hostname()) throw new Error('Worker dispatch belongs to another host; reconcile it on that host.');
642
+ if (holder.host !== plugins.os.hostname()) throw new FleetWorkerError('worker_fenced', 'Worker dispatch belongs to another host; reconcile it on that host.');
616
643
  if (holder.controllerId === this.controllerId) {
617
644
  const active = this.jobs.get(worker.pending.id)?.snapshot;
618
- if (active?.state === 'running' || active?.state === 'queued') throw new Error('Worker dispatch job is still running.');
645
+ if (active?.state === 'running' || active?.state === 'queued') throw new FleetWorkerError('worker_fenced', 'Worker dispatch job is still running.');
619
646
  } else if (await controllerProcessIdentityIsLive(holder.pid, holder.fingerprint)) {
620
- throw new Error('Worker dispatch controller is still running; reconcile it through that controller.');
647
+ throw new FleetWorkerError('worker_fenced', 'Worker dispatch controller is still running; reconcile it through that controller.');
621
648
  }
622
649
  }
623
650
  /**
@@ -625,7 +652,7 @@ export class FleetWorkers {
625
652
  * session never started (stopped, unbound and settled) is taken over instead: a refused relaunch keeps its name.
626
653
  */
627
654
  private async reserve(owner: string, name: string, cwd: string, profile: IFleetWorkerProfile, job: IFleetWorkerJob, predecessor?: string, actor?: ITicketActor, reportsTo?: string, unstarted?: IFleetWorker): Promise<IFleetWorker> {
628
- await plugins.fs.promises.access(cwd); if (!(await plugins.fs.promises.stat(cwd)).isDirectory()) throw new Error('Worker cwd is not a directory.');
655
+ await plugins.fs.promises.access(cwd); if (!(await plugins.fs.promises.stat(cwd)).isDirectory()) throw new FleetWorkerError('worker_conflict', 'Worker cwd is not a directory.');
629
656
  const now = new Date().toISOString();
630
657
  const worker: IFleetWorker = { id: `${owner}:${name}`, name, harness: profile.harness, profileId: profile.id, profile, cwd,
631
658
  ...(job.ticketKey ? { ticketKey: job.ticketKey } : {}),
@@ -635,7 +662,7 @@ export class FleetWorkers {
635
662
  else {
636
663
  await this.store.update(owner, name, (current) => {
637
664
  if (current.state !== 'stopped' || current.nativeId || current.pending || current.lostDispatch || current.predecessor || current.successor
638
- || current.ticketKey !== job.ticketKey) throw new Error('Native binding fence changed.');
665
+ || current.ticketKey !== job.ticketKey) throw new FleetWorkerError('worker_fenced', 'Native binding fence changed.');
639
666
  for (const key of Object.keys(current) as Array<keyof IFleetWorker>) delete current[key];
640
667
  Object.assign(current, structuredClone(worker));
641
668
  });
@@ -651,12 +678,12 @@ export class FleetWorkers {
651
678
  const commented = !reconfirmed || !this.options.ticketEffects || !!await this.options.ticketEffects.saved(`fleet:reconfirmed:${reconfirmed.id}`);
652
679
  const doc = await this.store.update(owner, name, (worker) => {
653
680
  if (ticketBound) this.assertTicket(worker, job.ticketKey);
654
- if (worker.pending || worker.state === 'unknown' || worker.state === 'starting') throw new Error('Worker has an unresolved dispatch; inspect its native identity before proceeding.');
655
- if (worker.state === 'archived') throw new Error('Worker is archived.');
656
- if (worker.lostDispatch && job.action !== 'stop' && job.action !== 'archive') throw new Error('Worker dispatch was resolved as lost; only stop/archive are allowed.');
681
+ if (worker.pending || worker.state === 'unknown' || worker.state === 'starting') throw new FleetWorkerError('worker_fenced', 'Worker has an unresolved dispatch; inspect its native identity before proceeding.');
682
+ if (worker.state === 'archived') throw new FleetWorkerError('worker_archived', 'Worker is archived.');
683
+ if (worker.lostDispatch && job.action !== 'stop' && job.action !== 'archive') throw new FleetWorkerError('worker_fenced', 'Worker dispatch was resolved as lost; only stop/archive are allowed.');
657
684
  const keep = worker.reconfirmedDispatch && (worker.reconfirmedDispatch.id !== reconfirmed?.id || !commented);
658
685
  if (keep && job.action !== 'stop' && job.action !== 'archive') {
659
- throw new Error(`Worker reconfirmation ${worker.reconfirmedDispatch!.id} has no saved ticket comment; reconfirm the worker again before dispatching to it.`);
686
+ throw new FleetWorkerError('worker_fenced', `Worker reconfirmation ${worker.reconfirmedDispatch!.id} has no saved ticket comment; reconfirm the worker again before dispatching to it.`);
660
687
  }
661
688
  worker.pending = { id: job.id, action: job.action, startedAt: new Date().toISOString(), holder, ...(digest ? { digest } : {}) };
662
689
  // A reconfirmation stays only while it is the worker's latest dispatch outcome; its ticket comment keeps it.
@@ -666,7 +693,7 @@ export class FleetWorkers {
666
693
  /** Settles `job` on `worker` with `error`, which is a binding that stayed on it when `binding` is set. */
667
694
  private async finish(owner: string, worker: IFleetWorker, job: IFleetWorkerJob, state: IFleetWorker['state'], error?: string, binding = false): Promise<IFleetWorker> {
668
695
  const doc = await this.store.update(owner, worker.name, (current) => {
669
- if (current.pending?.id !== job.id) throw new Error('Worker dispatch fence changed.');
696
+ if (current.pending?.id !== job.id) throw new FleetWorkerError('worker_fenced', 'Worker dispatch fence changed.');
670
697
  current.state = state; if (state !== 'unknown') delete current.pending;
671
698
  if (error) current.error = error; else delete current.error;
672
699
  if (error && binding) current.errorSource = 'binding'; else delete current.errorSource;
@@ -676,11 +703,11 @@ export class FleetWorkers {
676
703
  private async startNative(owner: string, worker: IFleetWorker, job: IFleetWorkerJob, start: string | ((bind: (nativeId: string) => Promise<void>) => Promise<void>)): Promise<IFleetWorker> {
677
704
  const launch = typeof start === 'string' ? (bind: (nativeId: string) => Promise<void>) => this.backends[worker.harness].start(worker, worker.profile, start, bind) : start;
678
705
  try {
679
- await launch(async (nativeId) => {
706
+ await this.dispatch(job, () => launch(async (nativeId) => {
680
707
  const doc = await this.store.update(owner, worker.name, (current) => {
681
- if (current.pending?.id !== job.id || current.nativeId && current.nativeId !== nativeId) throw new Error('Native binding fence changed.'); current.nativeId = nativeId;
708
+ if (current.pending?.id !== job.id || current.nativeId && current.nativeId !== nativeId) throw new FleetWorkerError('worker_fenced', 'Native binding fence changed.'); current.nativeId = nativeId;
682
709
  }); worker.nativeId = doc.worker.nativeId;
683
- });
710
+ }));
684
711
  return await this.finish(owner, worker, job, 'live');
685
712
  } catch (error) { await this.finish(owner, worker, job, error instanceof FleetDispatchError && !error.dispatched ? 'stopped' : 'unknown', this.error(error)); throw error; }
686
713
  }
@@ -801,15 +828,15 @@ export class FleetWorkers {
801
828
  }
802
829
  if (job.action === 'adopt' && (input as TFleetWorkerRequest<'adopt'>).relaunch !== undefined) {
803
830
  const args = input as TFleetWorkerRequest<'adopt'>, profile = this.profile(profiles, args.profile), backend = this.backends[profile.harness];
804
- if (!backend.relaunch) throw new Error('Only a Claude Code session is relaunched; a Codex worker gains its identity at its next steer, so adopt it without relaunch.');
831
+ if (!backend.relaunch) throw new FleetWorkerError('worker_conflict', 'Only a Claude Code session is relaunched; a Codex worker gains its identity at its next steer, so adopt it without relaunch.');
805
832
  // The native binding is unique across owners, so the bound check reads every owner's workers.
806
833
  const documents = await this.store.list(), named = documents.find((doc) => doc.owner === owner && doc.worker.name === args.name)?.worker;
807
834
  // Only a worker of the same ticket whose own start or relaunch was refused before its session started gives its
808
835
  // name to a relaunch; a dispatch resolved as lost keeps its record.
809
- if (named && (named.state !== 'stopped' || named.nativeId || named.pending || named.lostDispatch || named.predecessor || named.successor)) throw new Error('A relaunch adopts its session as a new worker; this worker name is taken.');
836
+ if (named && (named.state !== 'stopped' || named.nativeId || named.pending || named.lostDispatch || named.predecessor || named.successor)) throw new FleetWorkerError('worker_conflict', 'A relaunch adopts its session as a new worker; this worker name is taken.');
810
837
  if (named) this.assertTicket(named, args.ticketKey);
811
838
  if (documents.some((doc) => doc.worker.harness === profile.harness && doc.worker.nativeId === args.nativeId && doc.worker.state !== 'archived')) {
812
- throw new Error('A fleet worker is bound to this session already.');
839
+ throw new FleetWorkerError('worker_conflict', 'A fleet worker is bound to this session already.');
813
840
  }
814
841
  const worker = await this.reserve(owner, args.name, args.cwd, profile, job, undefined, actor, reportsTo, named);
815
842
  job.workers = [await this.startNative(owner, worker, job, (bind) => backend.relaunch!(worker, profile, args.nativeId,
@@ -834,15 +861,15 @@ export class FleetWorkers {
834
861
  || existing.ticketKey !== undefined && existing.ticketKey !== args.ticketKey || existing.cwd !== args.cwd
835
862
  || existing.harness !== profile.harness || existing.nativeId && existing.nativeId !== args.nativeId
836
863
  || !plugins.util.isDeepStrictEqual(existing.profile, profile)) {
837
- throw new Error(`Existing worker cannot be adopted as this native identity.${existing.nativeId && existing.nativeId !== args.nativeId ? ' To move it onto a successor session of its lane, re-bind it with a reason.' : ''}`);
864
+ throw new FleetWorkerError('worker_conflict', `Existing worker cannot be adopted as this native identity.${existing.nativeId && existing.nativeId !== args.nativeId ? ' To move it onto a successor session of its lane, re-bind it with a reason.' : ''}`);
838
865
  }
839
866
  await this.assertRecoverable(existing);
840
867
  }
841
- if ((await this.backends[candidate.harness].observe(candidate, profile)).status === 'gone') throw new Error('Native worker identity cannot be observed for adoption.');
868
+ if ((await this.backends[candidate.harness].observe(candidate, profile)).status === 'gone') throw new FleetWorkerError('worker_conflict', 'Native worker identity cannot be observed for adoption.');
842
869
  // Adoption never starts/resumes a turn. Native bindings are unique across owners.
843
870
  if (existing) {
844
871
  const doc = await this.store.update(owner, args.name, (current) => {
845
- if (!plugins.util.isDeepStrictEqual(current, existing)) throw new Error('Worker recovery fence changed.');
872
+ if (!plugins.util.isDeepStrictEqual(current, existing)) throw new FleetWorkerError('worker_fenced', 'Worker recovery fence changed.');
846
873
  current.nativeId = args.nativeId; current.ticketKey = args.ticketKey; current.state = 'live'; delete current.pending; delete current.error; delete current.errorSource;
847
874
  if (actor && !current.ticketActor) current.ticketActor = actor;
848
875
  if (reportsTo && !current.reportsTo) current.reportsTo = reportsTo;
@@ -901,8 +928,8 @@ export class FleetWorkers {
901
928
  catch (error) { stayed = this.error(error); }
902
929
  if (stayed) { await this.finish(owner, claimed, job, old.state, stayed, binding); throw new Error(stayed); }
903
930
  try {
904
- await this.backends[old.harness].stop(old, old.profile);
905
- await this.backends[old.harness].archive(old, old.profile);
931
+ await this.dispatch(job, () => this.backends[old.harness].stop(old, old.profile));
932
+ await this.dispatch(job, () => this.backends[old.harness].archive(old, old.profile));
906
933
  job.workers = [await this.finish(owner, claimed, job, 'archived'), next];
907
934
  } catch (error) { await this.finish(owner, claimed, job, 'unknown', this.error(error)); throw error; }
908
935
  return;
@@ -921,14 +948,14 @@ export class FleetWorkers {
921
948
  for (const harness of ['claude', 'codex'] as const) {
922
949
  const group = workers.filter((worker) => worker.harness === harness).map((worker) => ({ worker, profile: worker.profile, text: messages.find((message) => message.name === worker.name)!.text }));
923
950
  if (!group.length) continue;
924
- await this.backends[harness].send(group); admitted = true;
951
+ await this.dispatch(job, () => this.backends[harness].send(group)); admitted = true;
925
952
  }
926
953
  } catch (error) { throw new FleetDispatchError(this.error(error), admitted || error instanceof FleetDispatchError && error.dispatched, { cause: error }); }
927
954
  } else for (const worker of workers) {
928
955
  if (worker.lostDispatch) continue;
929
956
  // A worker whose start the harness refused has no native session to settle.
930
957
  if (job.action === 'archive' && !worker.nativeId) continue;
931
- await this.backends[worker.harness][job.action as 'stop' | 'archive'](worker, worker.profile);
958
+ await this.dispatch(job, () => this.backends[worker.harness][job.action as 'stop' | 'archive'](worker, worker.profile));
932
959
  }
933
960
  job.workers = [];
934
961
  for (const worker of workers) job.workers.push(await this.finish(owner, worker, job, job.action === 'archive' ? 'archived' : job.action === 'stop' ? 'stopped' : 'live'));
@@ -1,6 +1,8 @@
1
1
  import * as plugins from '../plugins.js';
2
+ import { exactError } from '../functions.exactpersistence.js';
2
3
  import type { IFleetWorker } from '../../ts_interfaces/fleetworkers.js';
3
4
  import { fleetWorkerSchema } from './functions.workervalidation.js';
5
+ import { FleetWorkerError } from './interfaces.workers.js';
4
6
 
5
7
  export interface IFleetWorkerDocument { id: string; owner: string; updateId: string; worker: IFleetWorker; nativeKey?: string }
6
8
  const documentSchema = plugins.z.object({ id: plugins.z.string().min(1), owner: plugins.z.string().min(1),
@@ -28,7 +30,7 @@ export interface IFleetWorkerStore {
28
30
  create(owner: string, worker: IFleetWorker): Promise<IFleetWorkerDocument>;
29
31
  update(owner: string, name: string, change: (worker: IFleetWorker) => void): Promise<IFleetWorkerDocument>;
30
32
  }
31
- const ambiguous = (error: unknown): boolean => error instanceof plugins.nosqldb.SmartdataExactPersistenceError && error.code === 'ambiguous_write';
33
+ const nativeBindingTaken = 'Another fleet worker already holds this native session.';
32
34
  /** The auth store owns the model manager and database; this adapter owns no connection. */
33
35
  export class FleetWorkerStore implements IFleetWorkerStore {
34
36
  public async list(owner?: string): Promise<IFleetWorkerDocument[]> {
@@ -38,7 +40,7 @@ export class FleetWorkerStore implements IFleetWorkerStore {
38
40
  }
39
41
  public async get(owner: string, name: string): Promise<IFleetWorkerDocument> {
40
42
  const record = await FleetWorkerModel.exact.findStoredOne({ id: `${owner}:${name}`, owner });
41
- if (!record) throw new Error('Fleet worker is unavailable for this owner.');
43
+ if (!record) throw new FleetWorkerError('worker_not_found', 'Fleet worker is unavailable for this owner.');
42
44
  return structuredClone(FleetWorkerModel.exact.toPersisted(record));
43
45
  }
44
46
  public async create(owner: string, worker: IFleetWorker): Promise<IFleetWorkerDocument> {
@@ -46,10 +48,11 @@ export class FleetWorkerStore implements IFleetWorkerStore {
46
48
  ...(worker.nativeId ? { nativeKey: `${worker.harness}:${worker.nativeId}` } : {}) };
47
49
  try {
48
50
  const result = await FleetWorkerModel.exact.insert(candidate);
49
- if (result.status === 'conflict') throw new Error('The fleet worker name or native binding already exists.');
51
+ if (result.status === 'conflict') throw new FleetWorkerError('worker_conflict', 'The fleet worker name already exists.');
50
52
  return structuredClone(FleetWorkerModel.exact.toPersisted(result.document));
51
53
  } catch (error) {
52
- if (!ambiguous(error)) throw error;
54
+ if (exactError(error, 'unique_conflict')) throw new FleetWorkerError('worker_conflict', nativeBindingTaken, { cause: error });
55
+ if (!exactError(error, 'ambiguous_write')) throw error;
53
56
  const record = await FleetWorkerModel.exact.findStoredOne({ id: candidate.id });
54
57
  if (record?.updateId === candidate.updateId) return structuredClone(FleetWorkerModel.exact.toPersisted(record));
55
58
  throw new Error('Fleet worker reservation outcome is unknown; inspect the registry before retrying.', { cause: error });
@@ -57,16 +60,17 @@ export class FleetWorkerStore implements IFleetWorkerStore {
57
60
  }
58
61
  public async update(owner: string, name: string, change: (worker: IFleetWorker) => void): Promise<IFleetWorkerDocument> {
59
62
  const current = await FleetWorkerModel.exact.findStoredOne({ id: `${owner}:${name}`, owner });
60
- if (!current) throw new Error('Fleet worker is unavailable for this owner.');
63
+ if (!current) throw new FleetWorkerError('worker_not_found', 'Fleet worker is unavailable for this owner.');
61
64
  const next = structuredClone(FleetWorkerModel.exact.toPersisted(current));
62
65
  change(next.worker); next.worker.updatedAt = new Date().toISOString(); next.updateId = plugins.crypto.randomUUID();
63
66
  if (next.worker.nativeId) next.nativeKey = `${next.worker.harness}:${next.worker.nativeId}`;
64
67
  try {
65
68
  const result = await FleetWorkerModel.exact.transition({ current, change: (model) => { Object.assign(model, next); } });
66
- if (result.status !== 'transitioned') throw new Error('Fleet worker changed concurrently.');
69
+ if (result.status !== 'transitioned') throw new FleetWorkerError('worker_fenced', 'Fleet worker changed concurrently.');
67
70
  return structuredClone(FleetWorkerModel.exact.toPersisted(result.document));
68
71
  } catch (error) {
69
- if (!ambiguous(error)) throw error;
72
+ if (exactError(error, 'unique_conflict')) throw new FleetWorkerError('worker_conflict', nativeBindingTaken, { cause: error });
73
+ if (!exactError(error, 'ambiguous_write')) throw error;
70
74
  const record = await FleetWorkerModel.exact.findStoredOne({ id: next.id });
71
75
  if (record?.updateId === next.updateId) return structuredClone(FleetWorkerModel.exact.toPersisted(record));
72
76
  throw new Error('Fleet worker transition outcome is unknown; inspect the registry before retrying.', { cause: error });
@@ -1,5 +1,5 @@
1
1
  import * as plugins from '../plugins.js';
2
- import { fleetWorkerJobWaitMaximumMs, type IFleetWorkerProfile, type TFleetWorkerAction, type TFleetWorkerRequest, type TFleetWorkerResponse } from '../../ts_interfaces/fleetworkers.js';
2
+ import { fleetWorkerErrorCodes, fleetWorkerErrorOutcomes, fleetWorkerJobWaitMaximumMs, type IFleetWorkerProfile, type TFleetWorkerAction, type TFleetWorkerRequest, type TFleetWorkerResponse } from '../../ts_interfaces/fleetworkers.js';
3
3
  import { fleetTicketKeySchema as ticketKey, fleetTicketSyncSchema as ticketSync } from './functions.ticketcontext.js';
4
4
  import { ticketActorSchema } from '../functions.ticketvalidation.js';
5
5
  import { controllerAgentMessageMaxTextBytes, controllerNativeWaitReasons, controllerSessionFeedLimits, isControllerAgentMessageSender } from '../../ts_interfaces/index.js';
@@ -125,11 +125,16 @@ const job = plugins.z.object({ id: text, action: plugins.z.enum(['start', 'adopt
125
125
  ticketKey: ticketKey.optional(),
126
126
  ticketSync: ticketSync.optional(),
127
127
  state: plugins.z.enum(['queued', 'running', 'succeeded', 'failed']), workers: plugins.z.array(fleetWorkerSchema).max(64).optional(),
128
- report: report.optional(), nativeMessage: nativeMessage.optional(), error: plugins.z.string().max(4096).optional() }).strict().superRefine((value, context) => {
128
+ report: report.optional(), nativeMessage: nativeMessage.optional(), error: plugins.z.string().max(4096).optional(),
129
+ errorCode: plugins.z.enum(fleetWorkerErrorCodes).optional(), errorOutcome: plugins.z.enum(fleetWorkerErrorOutcomes).optional() }).strict().superRefine((value, context) => {
129
130
  if (value.state === 'failed' && !value.error || value.state === 'succeeded' && (value.action === 'report' ? !value.report
130
131
  : value.action === 'native-message' ? !value.nativeMessage : !value.workers)) {
131
132
  context.addIssue({ code: 'custom', message: 'Incomplete fleet worker job outcome.' });
132
133
  }
134
+ // A code names the fleet's own refusal of a failed job.
135
+ if (value.errorCode !== undefined && value.state !== 'failed') context.addIssue({ code: 'custom', message: 'Only a failed fleet worker job has an error code.' });
136
+ // So does the outcome of what it dispatched.
137
+ if (value.errorOutcome !== undefined && value.state !== 'failed') context.addIssue({ code: 'custom', message: 'Only a failed fleet worker job has an error outcome.' });
133
138
  });
134
139
  const event = plugins.z.object({ id: plugins.z.number().int().positive(),
135
140
  kind: plugins.z.enum(['worker.changed', 'worker.turn.ended', 'worker.report.mid_turn', 'worker.reaped', 'worker.credential.failed', 'worker.observation.failed', 'release.finished', 'release.failed', 'ticket.applied', 'ticket.failed', 'ticket.unknown',
@@ -8,9 +8,13 @@ export type TFleetNativeReply = { permission: TControllerPermissionReply } | { a
8
8
  export class FleetDispatchError extends Error {
9
9
  constructor(message: string, public readonly dispatched: boolean, options?: ErrorOptions) { super(message, options); this.name = 'FleetDispatchError'; }
10
10
  }
11
- /** A fleet worker read's refusal; see `fleetWorkerErrorCodes`. Its message names only what the caller asked for. */
11
+ /**
12
+ * A refusal of the fleet whose text AGL writes itself, never a dependency's, so its message names only AGL's own values
13
+ * (a worker, a ticket, a profile, a harness); see `fleetWorkerErrorCodes`. A job it fails records its code
14
+ * (`IFleetWorkerJob.errorCode`).
15
+ */
12
16
  export class FleetWorkerError extends Error {
13
- constructor(public readonly code: TFleetWorkerErrorCode, message: string) { super(message); this.name = 'FleetWorkerError'; }
17
+ constructor(public readonly code: TFleetWorkerErrorCode, message: string, options?: ErrorOptions) { super(message, options); this.name = 'FleetWorkerError'; }
14
18
  }
15
19
  /**
16
20
  * A native send refused before anything reached the session: its running turn is not the one the sender read