agl 43.3.0 → 43.3.2

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 (80) hide show
  1. package/changelog.md +19 -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 +38 -10
  10. package/dist_ts/classes.controller.js +160 -91
  11. package/dist_ts/classes.flexservice.d.ts +12 -1
  12. package/dist_ts/classes.flexservice.js +44 -13
  13. package/dist_ts/classes.flexstore.d.ts +20 -0
  14. package/dist_ts/classes.flexstore.js +30 -1
  15. package/dist_ts/classes.mcpcontrollerhost.js +4 -1
  16. package/dist_ts/classes.mcptools.js +6 -1
  17. package/dist_ts/classes.nativesessions.d.ts +12 -0
  18. package/dist_ts/classes.nativesessions.js +1 -1
  19. package/dist_ts/classes.workercallers.js +4 -2
  20. package/dist_ts/driver/classes.directreports.js +19 -19
  21. package/dist_ts/driver/classes.directreportstore.d.ts +8 -1
  22. package/dist_ts/driver/classes.directreportstore.js +20 -10
  23. package/dist_ts/fleet/classes.workers.d.ts +16 -0
  24. package/dist_ts/fleet/classes.workers.js +73 -39
  25. package/dist_ts/fleet/classes.workerstore.js +14 -8
  26. package/dist_ts/fleet/functions.workervalidation.js +10 -3
  27. package/dist_ts/fleet/interfaces.workers.d.ts +6 -2
  28. package/dist_ts/fleet/interfaces.workers.js +8 -4
  29. package/dist_ts/functions.deviceapi.d.ts +50 -3
  30. package/dist_ts/functions.deviceapi.js +174 -7
  31. package/dist_ts/functions.exactpersistence.d.ts +3 -0
  32. package/dist_ts/functions.exactpersistence.js +4 -0
  33. package/dist_ts/functions.mcpfleetworkertools.js +2 -2
  34. package/dist_ts/functions.ticketactor.d.ts +17 -1
  35. package/dist_ts/functions.ticketactor.js +55 -15
  36. package/dist_ts/interfaces.flexipc.d.ts +17 -9
  37. package/dist_ts/interfaces.flexipc.js +19 -20
  38. package/dist_ts_interfaces/devices.d.ts +17 -4
  39. package/dist_ts_interfaces/devices.js +1 -1
  40. package/dist_ts_interfaces/fleetworkers.d.ts +32 -7
  41. package/dist_ts_interfaces/fleetworkers.js +19 -8
  42. package/dist_ts_interfaces/workercallers.d.ts +2 -0
  43. package/dist_ts_migration/classes.documentmigrationrunner.d.ts +14 -0
  44. package/dist_ts_migration/classes.documentmigrationrunner.js +20 -1
  45. package/dist_ts_migration/index.d.ts +1 -0
  46. package/dist_ts_migration/index.js +2 -1
  47. package/dist_ts_migration/v43_ticketactornames.d.ts +32 -0
  48. package/dist_ts_migration/v43_ticketactornames.js +236 -0
  49. package/package.json +5 -5
  50. package/readme.md +35 -4
  51. package/ts/00_commitinfo_data.ts +1 -1
  52. package/ts/classes.authstore.ts +10 -0
  53. package/ts/classes.claudeharness.ts +18 -4
  54. package/ts/classes.controller.ts +169 -96
  55. package/ts/classes.flexservice.ts +57 -14
  56. package/ts/classes.flexstore.ts +40 -0
  57. package/ts/classes.mcpcontrollerhost.ts +3 -0
  58. package/ts/classes.mcptools.ts +5 -0
  59. package/ts/classes.nativesessions.ts +13 -0
  60. package/ts/classes.workercallers.ts +3 -1
  61. package/ts/driver/classes.directreports.ts +18 -18
  62. package/ts/driver/classes.directreportstore.ts +20 -9
  63. package/ts/fleet/classes.workers.ts +66 -39
  64. package/ts/fleet/classes.workerstore.ts +11 -7
  65. package/ts/fleet/functions.workervalidation.ts +7 -2
  66. package/ts/fleet/interfaces.workers.ts +6 -2
  67. package/ts/functions.deviceapi.ts +227 -6
  68. package/ts/functions.exactpersistence.ts +5 -0
  69. package/ts/functions.mcpfleetworkertools.ts +1 -1
  70. package/ts/functions.ticketactor.ts +58 -14
  71. package/ts/interfaces.flexipc.ts +43 -27
  72. package/ts_interfaces/devices.schema.json +5 -2
  73. package/ts_interfaces/devices.ts +20 -4
  74. package/ts_interfaces/fleetworkers.ts +33 -7
  75. package/ts_interfaces/workercallers.ts +2 -0
  76. package/ts_migration/classes.documentmigrationrunner.ts +21 -0
  77. package/ts_migration/index.ts +1 -0
  78. package/ts_migration/v43_ticketactornames.ts +225 -0
  79. package/ts_web/00_commitinfo_data.ts +1 -1
  80. package/ts_web/elements.fleetworker.ts +4 -2
@@ -104,6 +104,16 @@ export interface IFlexTranscriptMigrationPage {
104
104
  nextCursor?: TFlexObjectId;
105
105
  }
106
106
 
107
+ /** What the store read for one FlexHarness load of a storage key (AGL-1713). */
108
+ export interface IFlexScopeLoadReads {
109
+ /** Private snapshots read from the database; a cached one costs no read and is not counted. */
110
+ snapshots: number;
111
+ /** Their JSON bytes. */
112
+ bytes: number;
113
+ /** Decoding them: base64, chunk and snapshot SHA-256, concatenation, UTF-8 and `JSON.parse`. */
114
+ decodeMs: number;
115
+ }
116
+
107
117
  export interface IFlexStoreOptions {
108
118
  database: plugins.nosqldb.SmartdataDb;
109
119
  controllerId: string;
@@ -1268,6 +1278,12 @@ export class FlexStore implements plugins.flexharness.IFlexHarnessStores {
1268
1278
  /** Transcripts by id; they are addressed by their content, so a cached one never goes stale. */
1269
1279
  private readonly transcriptCache = new Map<string, IFlexCachedTranscript>();
1270
1280
  private transcriptCacheBytes = 0;
1281
+ /**
1282
+ * What FlexHarness's load of each storage key has read so far: opened by the load's first read,
1283
+ * its scope snapshot, and ended by the load's report (`takeScopeLoadReads`), a purge or the
1284
+ * close. At most one entry per storage key, numbers only.
1285
+ */
1286
+ private readonly scopeLoadReads = new Map<string, IFlexScopeLoadReads>();
1271
1287
 
1272
1288
  constructor(optionsArg: IFlexStoreOptions) {
1273
1289
  assertIdentifier(optionsArg.controllerId, 'controllerId');
@@ -1638,6 +1654,7 @@ export class FlexStore implements plugins.flexharness.IFlexHarnessStores {
1638
1654
  await this.runStorage(storageKeyArg, async (lease) => {
1639
1655
  this.evictProviderScope(storageKeyArg);
1640
1656
  this.forgetCachedSnapshots(storageKeyArg);
1657
+ this.scopeLoadReads.delete(storageKeyArg);
1641
1658
  let lastDomainHeadId: TFlexObjectId | undefined;
1642
1659
  while (true) {
1643
1660
  const domainHeads = await this.readDomainHeadPage({
@@ -1756,6 +1773,16 @@ export class FlexStore implements plugins.flexharness.IFlexHarnessStores {
1756
1773
  }
1757
1774
  }
1758
1775
 
1776
+ /**
1777
+ * The reads of FlexHarness's load of a storage key since it began, which end here: FlexHarness
1778
+ * reports each load once it ended, whatever its outcome.
1779
+ */
1780
+ public takeScopeLoadReads(storageKeyArg: string): IFlexScopeLoadReads {
1781
+ const reads = this.scopeLoadReads.get(storageKeyArg) ?? { snapshots: 0, bytes: 0, decodeMs: 0 };
1782
+ this.scopeLoadReads.delete(storageKeyArg);
1783
+ return reads;
1784
+ }
1785
+
1759
1786
  public async close(): Promise<void> {
1760
1787
  if (this.closeComplete) return;
1761
1788
  if (this.closePromise) return this.closePromise;
@@ -1801,6 +1828,7 @@ export class FlexStore implements plugins.flexharness.IFlexHarnessStores {
1801
1828
  }
1802
1829
  this.agentEventStores.clear();
1803
1830
  this.jobStores.clear();
1831
+ this.scopeLoadReads.clear();
1804
1832
  const releaseResults = await Promise.allSettled(
1805
1833
  [...this.heldLeases.values()].map((lease) => this.releaseHeldLease(
1806
1834
  lease,
@@ -1822,6 +1850,11 @@ export class FlexStore implements plugins.flexharness.IFlexHarnessStores {
1822
1850
  }
1823
1851
 
1824
1852
  private async loadScope(storageKeyArg: string): Promise<TFlexScopeSnapshot | undefined> {
1853
+ // FlexHarness loads a scope's sessions after its scope snapshot, so its reads count from here on
1854
+ // until the load reports. A load already counting keeps what it read.
1855
+ if (!this.scopeLoadReads.has(storageKeyArg)) {
1856
+ this.scopeLoadReads.set(storageKeyArg, { snapshots: 0, bytes: 0, decodeMs: 0 });
1857
+ }
1825
1858
  return this.runStorage(storageKeyArg, async () => {
1826
1859
  const loaded = await this.loadDomainDirect<TFlexScopeSnapshot>(
1827
1860
  { storageKey: storageKeyArg, domain: 'scope' },
@@ -2877,6 +2910,7 @@ export class FlexStore implements plugins.flexharness.IFlexHarnessStores {
2877
2910
  scopeId: storageKeyArg,
2878
2911
  }),
2879
2912
  );
2913
+ const decodeStartedAt = performance.now();
2880
2914
  const chunks: Buffer[] = [];
2881
2915
  for (const chunkManifest of manifestArg.chunks) {
2882
2916
  abortSignalArg?.throwIfAborted();
@@ -2923,6 +2957,12 @@ export class FlexStore implements plugins.flexharness.IFlexHarnessStores {
2923
2957
  { cause: errorArg },
2924
2958
  );
2925
2959
  }
2960
+ const scopeLoadReads = this.scopeLoadReads.get(storageKeyArg);
2961
+ if (scopeLoadReads) {
2962
+ scopeLoadReads.snapshots += 1;
2963
+ scopeLoadReads.bytes += manifestArg.bytes;
2964
+ scopeLoadReads.decodeMs += performance.now() - decodeStartedAt;
2965
+ }
2926
2966
  abortSignalArg?.throwIfAborted();
2927
2967
  try {
2928
2968
  return await validateArg(parsed);
@@ -316,6 +316,9 @@ const safeTypedResponseError = (
316
316
  project_not_found: 'The requested project is unavailable.',
317
317
  session_not_found: 'The requested session is unavailable.',
318
318
  session_read_only: 'The session takes no message now; session_read names why.',
319
+ // "Nothing was sent" holds because a `native_session_failed` reaching MCP says `outcome: 'refused'`: the MCP send
320
+ // path (`deliverNativeAgentMessage`) turns every other outcome into `outcome_unknown` first, and an operation
321
+ // that sends the session nothing is always `refused` (`serveNativeSession`).
319
322
  native_session_failed: 'The Claude Code session could not be reached, and nothing was sent; read the session before acting again.',
320
323
  ambiguous_session: 'The native ID exists on multiple connections; select its qualified AGL ID.',
321
324
  model_not_found: 'The selected model is unavailable.',
@@ -304,6 +304,11 @@ const safeClientMessages: Record<ControllerMcpClientError['code'], string> = {
304
304
  LIST_CURSOR_MISMATCH: 'The cursor pages another filter (archived, ticketKey, state, harness); repeat that filter or list again without cursor.',
305
305
  LIST_CURSOR_STALE: 'The cursor continues after a worker this owner no longer holds as it was; list again without cursor.',
306
306
  LIST_CURSOR_INVALID: 'The cursor is not the nextCursor of a fleet_worker_list summary page; list again without cursor.',
307
+ FLEET_UNAVAILABLE: 'The fleet admits no worker job now: it is closing, holds its most jobs, or cannot prove its own process. Try again later.',
308
+ WORKER_FENCED: 'The worker\'s dispatch fence stands in the way (an unresolved, running or lost dispatch, or a reconfirmation without its ticket comment). Read the worker with fleet_worker_get before acting again.',
309
+ WORKER_ARCHIVED: 'The worker is archived and takes no dispatch.',
310
+ TICKET_MISMATCH: 'The worker is bound to another ticket; name its ticket, or adopt its binding explicitly.',
311
+ WORKER_CONFLICT: 'The request does not fit what the fleet holds: the name is taken, the session is bound already, or the harness, profile or directory cannot serve it. Change the request.',
307
312
  REQUEST_FAILED: 'The private AGL controller request failed.',
308
313
  TURN_ENDED: 'The turn the message was to steer has ended; nothing was sent. Read the task before sending again.',
309
314
  AGENT_MESSAGES_DISABLED: 'The owner does not accept agent messages for this project.',
@@ -7,6 +7,7 @@ import type {
7
7
  TControllerNativeSessionReadOnlyReason,
8
8
  } from '../ts_interfaces/index.js';
9
9
  import type { IFleetNativeAgent, IFleetNativeSession, IFleetNativeThread } from './fleet/interfaces.workers.js';
10
+ import type { TClaudeDispatchRefusal } from './classes.claudeharness.js';
10
11
 
11
12
  /** Where the resolver finds native sessions: exactly the sources the session feed lists, never a path a caller names. */
12
13
  export interface INativeSessionSources {
@@ -27,6 +28,18 @@ export interface INativeSessionSources {
27
28
  directoryExists(path: string): Promise<boolean>;
28
29
  }
29
30
 
31
+ /**
32
+ * The data of a failed native session operation (`native_session_failed`), which says what it did: `refused`, nothing
33
+ * reached the session (an operation that sends it nothing, such as a read, or a send or answer refused before it went
34
+ * out, with `refusal` when a busy conversation or host refused it); `unknown`, the send or answer went out, or may have,
35
+ * and its effect is unknown.
36
+ */
37
+ export interface INativeSessionFailedErrorData {
38
+ code: 'native_session_failed';
39
+ outcome: 'refused' | 'unknown';
40
+ refusal?: TClaudeDispatchRefusal;
41
+ }
42
+
30
43
  /** A native session as the resolver found it in one of its sources. */
31
44
  export interface IResolvedNativeSession {
32
45
  session: IControllerNativeSession;
@@ -629,7 +629,9 @@ export class ControllerWorkerCallers implements IFleetWorkerCallerHooks {
629
629
  controllerGeneration: this.options.controllerGeneration, bindingRevision: revision,
630
630
  projectId: recordArg.launch.projectId, harnessId: recordArg.launch.harnessId,
631
631
  nativeSessionId: recordArg.binding.nativeSessionId, ticketSessionId: recordArg.ticketSessionId!,
632
- sessionIdentityId: plugins.crypto.createHash('sha256').update(recordArg.ticketSessionId!).digest('base64url') });
632
+ sessionIdentityId: plugins.crypto.createHash('sha256').update(recordArg.ticketSessionId!).digest('base64url'),
633
+ // A worker id is `${projectId}:${name}`: prepared and kept launches are refused otherwise.
634
+ workerName: recordArg.launch.workerId.slice(recordArg.launch.projectId.length + 1) });
633
635
  recordArg.credentials.set(bridgePidArg, { credential, bridge, bindingRevision: revision });
634
636
  return { ...this.getWorkerCallerStatus(recordArg.launch.launchId), credential };
635
637
  });
@@ -7,7 +7,7 @@ import * as plugins from '../plugins.js';
7
7
  import type { IFleetSessionBindingFailure, IFleetSessionBindings } from '../fleet/classes.workers.js';
8
8
  import type { IFleetNativeAgent, IFleetNativeThread } from '../fleet/interfaces.workers.js';
9
9
  import type { IResolvedNativeSession } from '../classes.nativesessions.js';
10
- import { DirectReportConflictError, DirectReportStore, type IDirectReportStore } from './classes.directreportstore.js';
10
+ import { DirectReportConflictError, DirectReportError, DirectReportStore, type IDirectReportStore } from './classes.directreportstore.js';
11
11
 
12
12
  /** What direct reports read from the fleet, the native inventories and the ticket board; the controller supplies it. */
13
13
  export interface IDirectReportsHost {
@@ -54,7 +54,7 @@ export const directReportReachable = (report: IDirectReport): boolean => report.
54
54
  /** The native session a report is (`IDirectReport.sessionId`, `harness:nativeId`) as a runtime id. */
55
55
  export const directReportRuntimeId = (report: IDirectReport): { harnessId: TFleetWorkerHarness; nativeId: string } => {
56
56
  const separator = report.sessionId.indexOf(':'), harnessId = report.sessionId.slice(0, separator), nativeId = report.sessionId.slice(separator + 1);
57
- if (separator < 0 || (harnessId !== 'claude' && harnessId !== 'codex') || !nativeId) throw new Error(`Direct report ${report.name} names no Claude Code or Codex session.`);
57
+ if (separator < 0 || (harnessId !== 'claude' && harnessId !== 'codex') || !nativeId) throw new DirectReportError(`Direct report ${report.name} names no Claude Code or Codex session.`);
58
58
  return { harnessId, nativeId };
59
59
  };
60
60
 
@@ -153,9 +153,9 @@ export class DirectReports implements IFleetSessionBindings {
153
153
  /** Appoints the fleet worker `workerName`, bound to a native session and a ticket, as the report `name`. */
154
154
  public async appoint(owner: string, request: IReq_ControllerDirectReportAppoint['request'], signal?: AbortSignal): Promise<IDirectReportView> {
155
155
  const workers = await this.host.workers(owner), worker = workers.find((view) => view.worker.name === request.workerName)?.worker;
156
- if (!worker) throw new Error('The fleet worker is unavailable.');
157
- if (!worker.nativeId) throw new Error('The fleet worker has no native session yet.');
158
- if (!worker.ticketKey) throw new Error('The fleet worker is bound to no ticket; a direct report is steered through its ticket.');
156
+ if (!worker) throw new DirectReportError('The fleet worker is unavailable.');
157
+ if (!worker.nativeId) throw new DirectReportError('The fleet worker has no native session yet.');
158
+ if (!worker.ticketKey) throw new DirectReportError('The fleet worker is bound to no ticket; a direct report is steered through its ticket.');
159
159
  const projects = request.projects ?? [await this.host.ticketProject(worker.ticketKey, signal)];
160
160
  const report = await this.store.create(owner, this.report(owner, request.name, { kind: 'fleet-worker', workerName: worker.name },
161
161
  `${worker.harness}:${worker.nativeId}`, projects, worker.ticketKey));
@@ -208,15 +208,15 @@ export class DirectReports implements IFleetSessionBindings {
208
208
  public async adopt(owner: string, request: IReq_ControllerDirectReportAdopt['request'], signal?: AbortSignal, actor?: ITicketActor): Promise<IDirectReportView> {
209
209
  const { harness, nativeId, relaunch } = request;
210
210
  if (harness === 'claude' && !relaunch) {
211
- throw new Error('A Claude Code session is adopted with a relaunch: the fleet resumes it under its own control, which gives it a verified identity.');
211
+ throw new DirectReportError('A Claude Code session is adopted with a relaunch: the fleet resumes it under its own control, which gives it a verified identity.');
212
212
  }
213
- if (harness === 'codex' && relaunch) throw new Error('A Codex thread is adopted by reference; only a Claude Code session is relaunched.');
213
+ if (harness === 'codex' && relaunch) throw new DirectReportError('A Codex thread is adopted by reference; only a Claude Code session is relaunched.');
214
214
  if ((await this.host.workers(owner)).some((view) => view.worker.harness === harness && view.worker.nativeId === nativeId)) {
215
- throw new Error('A fleet worker is bound to this session; appoint the worker instead.');
215
+ throw new DirectReportError('A fleet worker is bound to this session; appoint the worker instead.');
216
216
  }
217
217
  const observations: IDirectReportObservations = harness === 'claude' ? { claude: await this.host.claudeSessions() } : { codex: await this.host.codexThreads() };
218
218
  const session = (observations.claude ?? observations.codex ?? []).find((item) => item.sessionId === nativeId);
219
- if (!session) throw new Error(`The ${harness === 'claude' ? 'Claude Code session' : 'Codex thread'} is not on this host.`);
219
+ if (!session) throw new DirectReportError(`The ${harness === 'claude' ? 'Claude Code session' : 'Codex thread'} is not on this host.`);
220
220
  const project = await this.host.ticketProject(request.driverTicketKey, signal);
221
221
  if (!relaunch) {
222
222
  const report = await this.store.create(owner, this.report(owner, request.name, { kind: 'session', harness, nativeId },
@@ -225,14 +225,14 @@ export class DirectReports implements IFleetSessionBindings {
225
225
  }
226
226
  // Refused before the relaunch: a session that ran as a report keeps that report, and a name stays taken once used.
227
227
  const reports = await this.store.list(owner);
228
- if (reports.some((report) => report.name === request.name)) throw new Error('A direct report of that name exists.');
229
- if (reports.some((report) => report.state === 'active' && report.sessionId === `claude:${nativeId}`)) throw new Error('Another active direct report already holds this session.');
228
+ if (reports.some((report) => report.name === request.name)) throw new DirectReportError('A direct report of that name exists.');
229
+ if (reports.some((report) => report.state === 'active' && report.sessionId === `claude:${nativeId}`)) throw new DirectReportError('Another active direct report already holds this session.');
230
230
  // Only the host's own Claude Code home holds project conversations; a session its profile's home does not list is
231
231
  // refused by the relaunch itself.
232
232
  if ((await this.host.claudeProfiles()).some((profile) => profile.id === relaunch.profile && profile.home === undefined)) {
233
233
  const listed = await this.host.nativeSession({ harness: 'claude', nativeId }).catch((error: unknown) => { if (notListed(error)) return undefined; throw error; });
234
234
  if (listed?.session.readOnly?.reason === 'projectConversation') {
235
- throw new Error('An AGL project conversation records this Claude Code session, so it stays that project\'s: a relaunch would give the conversation a second writer.');
235
+ throw new DirectReportError('An AGL project conversation records this Claude Code session, so it stays that project\'s: a relaunch would give the conversation a second writer.');
236
236
  }
237
237
  }
238
238
  const worker = await this.host.relaunch(owner, { name: relaunch.workerName ?? request.name, profile: relaunch.profile, cwd: relaunch.cwd ?? session.cwd,
@@ -242,7 +242,7 @@ export class DirectReports implements IFleetSessionBindings {
242
242
  report = await this.store.create(owner, this.report(owner, request.name, { kind: 'fleet-worker', workerName: worker.name },
243
243
  `${worker.harness}:${worker.nativeId}`, request.projects ?? [project], request.driverTicketKey));
244
244
  } catch (error) {
245
- throw new Error(`The session was relaunched as fleet worker ${worker.name}, but its direct report was not recorded: ${error instanceof Error ? error.message : String(error)} Appoint the worker as the report.`.slice(0, 4096));
245
+ throw new DirectReportError(`The session was relaunched as fleet worker ${worker.name}, but its direct report was not recorded. Appoint the worker as the report.`, { cause: error });
246
246
  }
247
247
  return this.view(report, { workers: await this.host.workers(owner) }, await this.host.openQuestions(signal));
248
248
  }
@@ -250,7 +250,7 @@ export class DirectReports implements IFleetSessionBindings {
250
250
  /** Retires the report; its session is left as it is. */
251
251
  public async retire(owner: string, name: string): Promise<IDirectReport> {
252
252
  return await this.serialized(owner, name, () => this.store.update(owner, name, (report) => {
253
- if (report.state === 'retired') throw new Error('The direct report is retired.');
253
+ if (report.state === 'retired') throw new DirectReportError('The direct report is retired.');
254
254
  report.state = 'retired';
255
255
  }));
256
256
  }
@@ -264,14 +264,14 @@ export class DirectReports implements IFleetSessionBindings {
264
264
  */
265
265
  public async channelOf(owner: string, name: string): Promise<TDirectReportChannel> {
266
266
  const report = await this.store.get(owner, name);
267
- if (!report || report.state !== 'active') throw new Error(`Direct report ${name} is not an active direct report.`);
267
+ if (!report || report.state !== 'active') throw new DirectReportError(`Direct report ${name} is not an active direct report.`);
268
268
  const session = report.session;
269
269
  if (session.kind === 'fleet-worker') return { kind: 'fleet-worker', report, workerName: session.workerName };
270
270
  if (!directReportReachable(report)) {
271
- throw new Error(`Direct report ${name} is a Claude Code session the fleet does not run, so it cannot be read or messaged: AGL reaches a Claude Code session only by resuming it in a process of its own, a second writer beside the one that runs it. Adopt the session with a relaunch (directreport_adopt) once it has settled.`);
271
+ throw new DirectReportError(`Direct report ${name} is a Claude Code session the fleet does not run, so it cannot be read or messaged: AGL reaches a Claude Code session only by resuming it in a process of its own, a second writer beside the one that runs it. Adopt the session with a relaunch (directreport_adopt) once it has settled.`);
272
272
  }
273
273
  const thread = (await this.host.codexThreads()).find((item) => item.sessionId === session.nativeId);
274
- if (!thread) throw new Error(`Direct report ${name}'s Codex thread ${session.nativeId} is not among the threads of this host's Codex server.`);
274
+ if (!thread) throw new DirectReportError(`Direct report ${name}'s Codex thread ${session.nativeId} is not among the threads of this host's Codex server.`);
275
275
  return { kind: 'session', report, nativeId: session.nativeId, cwd: thread.cwd };
276
276
  }
277
277
 
@@ -345,7 +345,7 @@ export class DirectReports implements IFleetSessionBindings {
345
345
  const current = await this.store.get(owner, name), move = current && directReportMove(current, workers);
346
346
  if (!current || !move) return;
347
347
  const ticketKey = move.to.ticketKey;
348
- if (current.session.kind === 'session' && !ticketKey) throw new Error(`Fleet worker ${move.to.name} is bound to no ticket.`);
348
+ if (current.session.kind === 'session' && !ticketKey) throw new DirectReportError(`Fleet worker ${move.to.name} is bound to no ticket.`);
349
349
  try {
350
350
  await this.store.update(owner, name, (next) => {
351
351
  if (!plugins.util.isDeepStrictEqual(next, current)) throw new DirectReportConflictError();
@@ -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
  }