agl 43.0.3 → 43.0.5

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 (35) hide show
  1. package/changelog.md +18 -0
  2. package/dist_serve/bundle.js +1 -1
  3. package/dist_serve/bundle.js.map +1 -1
  4. package/dist_ts/00_commitinfo_data.js +1 -1
  5. package/dist_ts/classes.flexframedtransport.d.ts +16 -0
  6. package/dist_ts/classes.flexframedtransport.js +35 -20
  7. package/dist_ts/classes.flexservice.d.ts +7 -2
  8. package/dist_ts/classes.flexservice.js +11 -40
  9. package/dist_ts/classes.flexstore.js +4 -1
  10. package/dist_ts/classes.flexsupervisor.d.ts +47 -3
  11. package/dist_ts/classes.flexsupervisor.js +179 -32
  12. package/dist_ts/flexharness.child.js +9 -4
  13. package/dist_ts/functions.flexchildshutdown.d.ts +7 -0
  14. package/dist_ts/functions.flexchildshutdown.js +18 -1
  15. package/dist_ts_migration/index.d.ts +1 -2
  16. package/dist_ts_migration/index.js +2 -3
  17. package/dist_ts_migration/v43_flexpostharnessmigrationmarkers.d.ts +33 -0
  18. package/dist_ts_migration/v43_flexpostharnessmigrationmarkers.js +116 -0
  19. package/package.json +1 -1
  20. package/ts/00_commitinfo_data.ts +1 -1
  21. package/ts/classes.flexframedtransport.ts +42 -17
  22. package/ts/classes.flexservice.ts +9 -56
  23. package/ts/classes.flexstore.ts +6 -0
  24. package/ts/classes.flexsupervisor.ts +236 -32
  25. package/ts/flexharness.child.ts +8 -3
  26. package/ts/functions.flexchildshutdown.ts +22 -0
  27. package/ts_migration/index.ts +1 -2
  28. package/ts_migration/v43_flexpostharnessmigrationmarkers.ts +66 -0
  29. package/ts_web/00_commitinfo_data.ts +1 -1
  30. package/dist_ts_migration/classes.flexpostharnessmigrationrunner.d.ts +0 -10
  31. package/dist_ts_migration/classes.flexpostharnessmigrationrunner.js +0 -15
  32. package/dist_ts_migration/v19_flexprojectmanagement.d.ts +0 -11
  33. package/dist_ts_migration/v19_flexprojectmanagement.js +0 -21
  34. package/ts_migration/classes.flexpostharnessmigrationrunner.ts +0 -22
  35. package/ts_migration/v19_flexprojectmanagement.ts +0 -28
@@ -6,7 +6,7 @@ import {
6
6
  GitReversionDirtyWorktreeError,
7
7
  GitReversionFencedError,
8
8
  } from './classes.gitreversion.js';
9
- import type { IFailureDescription } from './functions.failuredescription.js';
9
+ import { sanitizeFailureText, type IFailureDescription } from './functions.failuredescription.js';
10
10
  import { createSanitizedRuntimeEnvironment } from './functions.runtimeenvironment.js';
11
11
  import {
12
12
  FlexServiceError,
@@ -70,7 +70,22 @@ export interface IFlexSupervisorLogEntry {
70
70
  truncated: boolean;
71
71
  }
72
72
 
73
+ /** An error of a child's log pipe, or of a started child process, the supervisor recorded and ignored. */
74
+ export interface IFlexSupervisorIgnoredError {
75
+ source: 'stdout' | 'stderr' | 'process';
76
+ /** The child generation, counted from 1 per supervisor, whose pipe or process the error came from. */
77
+ generation: number;
78
+ code?: string;
79
+ timestamp: number;
80
+ }
81
+
73
82
  export interface IFlexSupervisorOptions {
83
+ /**
84
+ * Writes one record to the controller log; the controller's stderr (`console.error`) unless a test
85
+ * captures it. Each child stdout and stderr line arrives here as it is read, tagged with its child
86
+ * generation, credential-redacted and bounded, and so does every abnormal child exit.
87
+ */
88
+ writeControllerLog?: (lineArg: string) => void;
74
89
  onChildExitObserved?: (exitArg: IFlexSupervisorExit) => void;
75
90
  onChildExit?: (exitArg: IFlexSupervisorExit) => void;
76
91
  cancellationGraceTimeoutMs?: number;
@@ -149,14 +164,39 @@ interface ILogAccumulator {
149
164
  decoder: TextDecoder;
150
165
  partial: string;
151
166
  dropping: boolean;
167
+ /** The stream's last suppressed lines of the current rate window, as buffered (at most 8 KiB each). */
168
+ suppressedTail: string[];
169
+ }
170
+
171
+ /** One child generation's log state: its pipes' partial lines and its controller-log rate window. */
172
+ interface IFlexChildLogGeneration {
173
+ generation: number;
174
+ pid?: number;
175
+ stdout: ILogAccumulator;
176
+ stderr: ILogAccumulator;
177
+ windowStartedAt: number;
178
+ windowLines: number;
179
+ suppressedLines: number;
152
180
  }
153
181
 
154
182
  const supervisorLogEntries = 200;
183
+ const supervisorIgnoredErrorEntries = 16;
155
184
  const supervisorLogLineBytes = 8 * 1024;
156
185
  const supervisorTermTimeoutMs = 5_000;
157
186
  const supervisorKillTimeoutMs = 2_000;
158
187
  const logSuffix = '... [truncated]';
159
188
  const supervisorExitMessageBytes = 1024;
189
+ /** A child line in the controller log keeps at most this many bytes, after its credentials are hidden. */
190
+ const supervisorControllerLogLineBytes = 2048;
191
+ /** A child generation writes at most this many lines to the controller log per window; the rest are counted. */
192
+ const supervisorControllerLogLinesPerWindow = 200;
193
+ const supervisorControllerLogWindowMs = 60_000;
194
+ /**
195
+ * The suppression record is followed by each stream's last this many suppressed lines, so a child that
196
+ * floods and then fails still leaves its fault: the crash line, the stack's header and its frames
197
+ * (`Error.stackTraceLimit`, 10 in the Flex child).
198
+ */
199
+ const supervisorControllerLogSuppressedTailLines = 20;
160
200
 
161
201
  export class FlexBrowserChannelNotificationUnavailableError extends Error {
162
202
  constructor() {
@@ -317,12 +357,10 @@ export class FlexSupervisor {
317
357
  private readonly settledHostRequestIds = new Set<string>();
318
358
  private readonly eventListeners = new Set<(eventArg: TFlexChildEvent) => void>();
319
359
  private readonly logs: IFlexSupervisorLogEntry[] = [];
320
- private readonly stdoutAccumulator: ILogAccumulator = {
321
- decoder: new TextDecoder(), partial: '', dropping: false,
322
- };
323
- private readonly stderrAccumulator: ILogAccumulator = {
324
- decoder: new TextDecoder(), partial: '', dropping: false,
325
- };
360
+ private readonly ignoredChildErrors: IFlexSupervisorIgnoredError[] = [];
361
+ /** Child generations observed so far; the controller log names each child by its number. */
362
+ private childGenerations = 0;
363
+ private readonly writeControllerLog: (lineArg: string) => void;
326
364
  private readonly cancellationGraceTimeoutMs: number;
327
365
  private readonly childTaskDrainTimeoutMs: number;
328
366
  /** The writer identity of the current child generation, until its exit is confirmed. */
@@ -331,6 +369,7 @@ export class FlexSupervisor {
331
369
  private readonly retiredWriterIds: string[] = [];
332
370
 
333
371
  constructor(private readonly options: IFlexSupervisorOptions = {}) {
372
+ this.writeControllerLog = options.writeControllerLog ?? ((lineArg) => console.error(lineArg));
334
373
  this.cancellationGraceTimeoutMs = this.normalizeDeadline(
335
374
  options.cancellationGraceTimeoutMs,
336
375
  flexIpcCancellationGraceTimeoutMs,
@@ -355,6 +394,11 @@ export class FlexSupervisor {
355
394
  return this.logs.map((entry) => ({ ...entry }));
356
395
  }
357
396
 
397
+ /** The child log-pipe and started-process errors the supervisor ignored, oldest first, the last 16. */
398
+ public getIgnoredChildErrors(): IFlexSupervisorIgnoredError[] {
399
+ return this.ignoredChildErrors.map((entry) => ({ ...entry }));
400
+ }
401
+
358
402
  public ownsChildPeer(peerIdArg: string): boolean {
359
403
  return this.browserPeerId !== ''
360
404
  && this.browserPeerId === peerIdArg
@@ -1365,15 +1409,40 @@ export class FlexSupervisor {
1365
1409
  }
1366
1410
 
1367
1411
  private observeChild(childArg: plugins.childProcess.ChildProcess): Promise<IFlexChildLifecycle> {
1368
- childArg.stdout?.on('data', (chunk) => this.consumeLog('stdout', chunk, this.stdoutAccumulator));
1369
- childArg.stderr?.on('data', (chunk) => this.consumeLog('stderr', chunk, this.stderrAccumulator));
1412
+ this.childGenerations += 1;
1413
+ const logGeneration: IFlexChildLogGeneration = {
1414
+ generation: this.childGenerations,
1415
+ ...(childArg.pid ? { pid: childArg.pid } : {}),
1416
+ stdout: { decoder: new TextDecoder(), partial: '', dropping: false, suppressedTail: [] },
1417
+ stderr: { decoder: new TextDecoder(), partial: '', dropping: false, suppressedTail: [] },
1418
+ windowStartedAt: Date.now(),
1419
+ windowLines: 0,
1420
+ suppressedLines: 0,
1421
+ };
1422
+ // The log pipes and the process keep their error listeners for as long as they exist: an error
1423
+ // event without a listener throws, and the child's lifecycle never depends on its log pipes. A
1424
+ // pipe's last partial line is written when the pipe closes, which can be after the child's exit,
1425
+ // and the generation's suppressed-line count and tails once both have closed.
1426
+ let openLogPipes = 0;
1427
+ const closeLogPipe = (streamArg: IFlexSupervisorLogEntry['stream']): void => {
1428
+ this.flushLog(logGeneration, streamArg);
1429
+ openLogPipes -= 1;
1430
+ if (openLogPipes === 0) this.reportSuppressedLines(logGeneration);
1431
+ };
1432
+ for (const stream of ['stdout', 'stderr'] as const) {
1433
+ const pipe = childArg[stream];
1434
+ if (!pipe) continue;
1435
+ openLogPipes += 1;
1436
+ pipe.on('data', (chunk) => this.consumeLog(logGeneration, stream, chunk));
1437
+ pipe.on('error', (errorArg) => this.recordIgnoredChildError(stream, logGeneration.generation, errorArg));
1438
+ pipe.once('close', () => closeLogPipe(stream));
1439
+ }
1370
1440
  return new Promise((resolve) => {
1371
1441
  let settled = false;
1372
1442
  const finish = (outcomeArg: IFlexChildLifecycle): void => {
1373
1443
  if (settled) return;
1374
1444
  settled = true;
1375
- this.flushLog('stdout', this.stdoutAccumulator);
1376
- this.flushLog('stderr', this.stderrAccumulator);
1445
+ this.logAbnormalExit(logGeneration, outcomeArg, this.status.state === 'stopping');
1377
1446
  this.status = { state: this.status.state === 'stopping' ? 'stopped' : 'failed', ready: false };
1378
1447
  this.browserPeerId = '';
1379
1448
  this.browserChannelGenerations.clear();
@@ -1415,12 +1484,66 @@ export class FlexSupervisor {
1415
1484
  resolve(outcomeArg);
1416
1485
  };
1417
1486
  childArg.once('exit', (code, signal) => finish({ type: 'exit', code, signal }));
1418
- childArg.once('error', (error) => {
1487
+ childArg.on('error', (error) => {
1488
+ // A child without a process ID never started, and its error is its outcome; a started
1489
+ // child's error (a failed signal) leaves its lifecycle to its exit.
1419
1490
  if (!childArg.pid) finish({ type: 'error', error });
1491
+ else this.recordIgnoredChildError('process', logGeneration.generation, error);
1420
1492
  });
1421
1493
  });
1422
1494
  }
1423
1495
 
1496
+ /**
1497
+ * Writes an exit the supervisor did not ask for, or one with a failure code or a signal, to the
1498
+ * controller log: the generation, its exit code and signal or why it never started, and the pipe
1499
+ * and process errors of that generation the supervisor ignored so far.
1500
+ */
1501
+ private logAbnormalExit(
1502
+ logGenerationArg: IFlexChildLogGeneration,
1503
+ outcomeArg: IFlexChildLifecycle,
1504
+ requestedArg: boolean,
1505
+ ): void {
1506
+ const child = this.describeChildGeneration(logGenerationArg);
1507
+ if (outcomeArg.type === 'error') {
1508
+ const reason = outcomeArg.error ? sanitizeFailureText(outcomeArg.error.message) : '';
1509
+ this.writeControllerLog(
1510
+ `${child} did not start: ${sanitizeExitMessage(reason) || 'the process reported no reason'}.`,
1511
+ );
1512
+ return;
1513
+ }
1514
+ const code = outcomeArg.code ?? null;
1515
+ const signal = outcomeArg.signal ?? null;
1516
+ if (requestedArg && code === 0 && signal === null) return;
1517
+ const ignored = this.ignoredChildErrors
1518
+ .filter((entryArg) => entryArg.generation === logGenerationArg.generation)
1519
+ .map((entryArg) => `${entryArg.source} ${entryArg.code ?? 'without code'}`);
1520
+ this.writeControllerLog(
1521
+ `${child} exited ${requestedArg ? 'while stopping' : 'unexpectedly'}: `
1522
+ + `code ${code === null ? 'none' : String(code)}, signal ${signal ?? 'none'}`
1523
+ + `${ignored.length > 0 ? `; ignored errors: ${ignored.join(', ')}` : ''}.`,
1524
+ );
1525
+ }
1526
+
1527
+ private describeChildGeneration(logGenerationArg: IFlexChildLogGeneration): string {
1528
+ return `Flex child generation ${logGenerationArg.generation}`
1529
+ + `${logGenerationArg.pid === undefined ? '' : ` (PID ${logGenerationArg.pid})`}`;
1530
+ }
1531
+
1532
+ private recordIgnoredChildError(
1533
+ sourceArg: IFlexSupervisorIgnoredError['source'],
1534
+ generationArg: number,
1535
+ errorArg: Error,
1536
+ ): void {
1537
+ const code = 'code' in errorArg && typeof errorArg.code === 'string' ? errorArg.code : undefined;
1538
+ this.ignoredChildErrors.push({
1539
+ source: sourceArg,
1540
+ generation: generationArg,
1541
+ ...(code ? { code } : {}),
1542
+ timestamp: Date.now(),
1543
+ });
1544
+ if (this.ignoredChildErrors.length > supervisorIgnoredErrorEntries) this.ignoredChildErrors.shift();
1545
+ }
1546
+
1424
1547
  private async reapOrphanedGroup(processGroupIdArg: number): Promise<void> {
1425
1548
  if (!isProcessGroupAlive(processGroupIdArg)) return;
1426
1549
  signalProcessGroup(processGroupIdArg, 'SIGTERM');
@@ -1601,9 +1724,9 @@ export class FlexSupervisor {
1601
1724
  }
1602
1725
 
1603
1726
  private consumeLog(
1727
+ logGenerationArg: IFlexChildLogGeneration,
1604
1728
  streamArg: IFlexSupervisorLogEntry['stream'],
1605
1729
  chunkArg: unknown,
1606
- accumulatorArg: ILogAccumulator,
1607
1730
  ): void {
1608
1731
  const bytes = typeof chunkArg === 'string'
1609
1732
  ? Buffer.from(chunkArg, 'utf8')
@@ -1611,49 +1734,64 @@ export class FlexSupervisor {
1611
1734
  ? chunkArg
1612
1735
  : undefined;
1613
1736
  if (!bytes) return;
1614
- let text = accumulatorArg.decoder.decode(bytes, { stream: true });
1737
+ const accumulator = logGenerationArg[streamArg];
1738
+ this.consumeLogText(logGenerationArg, streamArg, accumulator.decoder.decode(bytes, { stream: true }));
1739
+ }
1740
+
1741
+ private consumeLogText(
1742
+ logGenerationArg: IFlexChildLogGeneration,
1743
+ streamArg: IFlexSupervisorLogEntry['stream'],
1744
+ textArg: string,
1745
+ ): void {
1746
+ const accumulator = logGenerationArg[streamArg];
1747
+ let text = textArg;
1615
1748
  while (text.length > 0) {
1616
- if (accumulatorArg.dropping) {
1749
+ if (accumulator.dropping) {
1617
1750
  const newline = text.indexOf('\n');
1618
1751
  if (newline < 0) return;
1619
- accumulatorArg.dropping = false;
1752
+ accumulator.dropping = false;
1620
1753
  text = text.slice(newline + 1);
1621
1754
  continue;
1622
1755
  }
1623
1756
  const newline = text.indexOf('\n');
1624
1757
  if (newline >= 0) {
1625
- const complete = `${accumulatorArg.partial}${text.slice(0, newline)}`.replace(/\r$/u, '');
1626
- accumulatorArg.partial = '';
1627
- this.addLog(streamArg, complete);
1758
+ const complete = `${accumulator.partial}${text.slice(0, newline)}`.replace(/\r$/u, '');
1759
+ accumulator.partial = '';
1760
+ this.addLog(logGenerationArg, streamArg, complete);
1628
1761
  text = text.slice(newline + 1);
1629
1762
  continue;
1630
1763
  }
1631
- const complete = `${accumulatorArg.partial}${text}`;
1764
+ const complete = `${accumulator.partial}${text}`;
1632
1765
  if (Buffer.byteLength(complete, 'utf8') > supervisorLogLineBytes) {
1633
- this.addLog(streamArg, complete);
1634
- accumulatorArg.partial = '';
1635
- accumulatorArg.dropping = true;
1766
+ this.addLog(logGenerationArg, streamArg, complete);
1767
+ accumulator.partial = '';
1768
+ accumulator.dropping = true;
1636
1769
  } else {
1637
- accumulatorArg.partial = complete;
1770
+ accumulator.partial = complete;
1638
1771
  }
1639
1772
  return;
1640
1773
  }
1641
1774
  }
1642
1775
 
1643
1776
  private flushLog(
1777
+ logGenerationArg: IFlexChildLogGeneration,
1644
1778
  streamArg: IFlexSupervisorLogEntry['stream'],
1645
- accumulatorArg: ILogAccumulator,
1646
1779
  ): void {
1647
- const final = accumulatorArg.decoder.decode();
1648
- if (final) this.consumeLog(streamArg, final, accumulatorArg);
1649
- if (accumulatorArg.partial && !accumulatorArg.dropping) {
1650
- this.addLog(streamArg, accumulatorArg.partial);
1780
+ const accumulator = logGenerationArg[streamArg];
1781
+ const final = accumulator.decoder.decode();
1782
+ if (final) this.consumeLogText(logGenerationArg, streamArg, final);
1783
+ if (accumulator.partial && !accumulator.dropping) {
1784
+ this.addLog(logGenerationArg, streamArg, accumulator.partial);
1651
1785
  }
1652
- accumulatorArg.partial = '';
1653
- accumulatorArg.dropping = false;
1786
+ accumulator.partial = '';
1787
+ accumulator.dropping = false;
1654
1788
  }
1655
1789
 
1656
- private addLog(streamArg: IFlexSupervisorLogEntry['stream'], lineArg: string): void {
1790
+ private addLog(
1791
+ logGenerationArg: IFlexChildLogGeneration,
1792
+ streamArg: IFlexSupervisorLogEntry['stream'],
1793
+ lineArg: string,
1794
+ ): void {
1657
1795
  const bounded = truncateLog(lineArg);
1658
1796
  this.logs.push({
1659
1797
  timestamp: Date.now(),
@@ -1664,5 +1802,71 @@ export class FlexSupervisor {
1664
1802
  if (this.logs.length > supervisorLogEntries) {
1665
1803
  this.logs.splice(0, this.logs.length - supervisorLogEntries);
1666
1804
  }
1805
+ this.writeChildLine(logGenerationArg, streamArg, bounded.line);
1806
+ }
1807
+
1808
+ /**
1809
+ * Writes a child line to the controller log as it arrives, within the generation's rate window.
1810
+ * Lines over the window's budget are counted and the last `supervisorControllerLogSuppressedTailLines`
1811
+ * of each stream kept as buffered, not redacted; they are reported when the next window opens or
1812
+ * the generation's pipes closed.
1813
+ */
1814
+ private writeChildLine(
1815
+ logGenerationArg: IFlexChildLogGeneration,
1816
+ streamArg: IFlexSupervisorLogEntry['stream'],
1817
+ lineArg: string,
1818
+ ): void {
1819
+ const now = Date.now();
1820
+ if (now - logGenerationArg.windowStartedAt >= supervisorControllerLogWindowMs) {
1821
+ this.reportSuppressedLines(logGenerationArg);
1822
+ logGenerationArg.windowStartedAt = now;
1823
+ logGenerationArg.windowLines = 0;
1824
+ }
1825
+ if (logGenerationArg.windowLines >= supervisorControllerLogLinesPerWindow) {
1826
+ logGenerationArg.suppressedLines += 1;
1827
+ const tail = logGenerationArg[streamArg].suppressedTail;
1828
+ tail.push(lineArg);
1829
+ if (tail.length > supervisorControllerLogSuppressedTailLines) tail.shift();
1830
+ return;
1831
+ }
1832
+ logGenerationArg.windowLines += 1;
1833
+ this.emitChildLine(logGenerationArg, streamArg, lineArg);
1834
+ }
1835
+
1836
+ /**
1837
+ * Writes one child line to the controller log, live or from a suppression tail: at most
1838
+ * `supervisorControllerLogLineBytes`, control characters spaced out and every credential hidden
1839
+ * before the cut (`sanitizeFailureText`, then `redactAndBound`), so the cut never keeps part of a
1840
+ * credential. The input is the buffered line, at most 8 KiB, whose unread rest lies far beyond the
1841
+ * kept head.
1842
+ */
1843
+ private emitChildLine(
1844
+ logGenerationArg: IFlexChildLogGeneration,
1845
+ streamArg: IFlexSupervisorLogEntry['stream'],
1846
+ lineArg: string,
1847
+ ): void {
1848
+ const line = plugins.smartstring.redact.redactAndBound(sanitizeFailureText(lineArg), {
1849
+ maxBytes: supervisorControllerLogLineBytes,
1850
+ keep: 'head',
1851
+ marker: logSuffix,
1852
+ }).text;
1853
+ this.writeControllerLog(`${this.describeChildGeneration(logGenerationArg)} ${streamArg}: ${line}`);
1854
+ }
1855
+
1856
+ /** Writes the rate window's suppression record, then its stdout tail and its stderr tail, and empties them. */
1857
+ private reportSuppressedLines(logGenerationArg: IFlexChildLogGeneration): void {
1858
+ if (logGenerationArg.suppressedLines === 0) return;
1859
+ const suppressed = logGenerationArg.suppressedLines;
1860
+ logGenerationArg.suppressedLines = 0;
1861
+ this.writeControllerLog(
1862
+ `${this.describeChildGeneration(logGenerationArg)}: ${suppressed} lines suppressed `
1863
+ + `(more than ${supervisorControllerLogLinesPerWindow} lines in ${supervisorControllerLogWindowMs / 1000} s); `
1864
+ + `the last ${supervisorControllerLogSuppressedTailLines} of each stream follow.`,
1865
+ );
1866
+ for (const stream of ['stdout', 'stderr'] as const) {
1867
+ const tail = logGenerationArg[stream].suppressedTail;
1868
+ logGenerationArg[stream].suppressedTail = [];
1869
+ for (const line of tail) this.emitChildLine(logGenerationArg, stream, line);
1870
+ }
1667
1871
  }
1668
1872
  }
@@ -1,7 +1,7 @@
1
1
  import * as plugins from './plugins.js';
2
2
  import { FlexFramedTransport } from './classes.flexframedtransport.js';
3
3
  import { FlexService } from './classes.flexservice.js';
4
- import { createFlexChildShutdown } from './functions.flexchildshutdown.js';
4
+ import { createFlexChildShutdown, formatFlexChildFault } from './functions.flexchildshutdown.js';
5
5
  import {
6
6
  type TFlexChildMessage,
7
7
  type TFlexParentMessage,
@@ -38,8 +38,13 @@ service = new FlexService({
38
38
 
39
39
  process.once('SIGTERM', () => shutdown(false));
40
40
  process.once('SIGINT', () => shutdown(false));
41
- process.once('uncaughtException', () => shutdown(true));
42
- process.once('unhandledRejection', () => shutdown(true));
41
+ // A fault nothing else handled is written to stderr, which the supervisor logs, before the shutdown.
42
+ const handleFault = (kindArg: Parameters<typeof formatFlexChildFault>[0]) => (errorArg: unknown): void => {
43
+ process.stderr.write(formatFlexChildFault(kindArg, errorArg));
44
+ shutdown(true);
45
+ };
46
+ process.once('uncaughtException', handleFault('uncaught exception'));
47
+ process.once('unhandledRejection', handleFault('unhandled rejection'));
43
48
 
44
49
  try {
45
50
  await service.start();
@@ -1,3 +1,6 @@
1
+ import * as plugins from './plugins.js';
2
+ import { describeFailure } from './functions.failuredescription.js';
3
+
1
4
  export interface IFlexChildShutdownOptions {
2
5
  dispose: () => Promise<void>;
3
6
  closeDescriptors: () => void;
@@ -48,3 +51,22 @@ export const createFlexChildShutdown = (
48
51
  });
49
52
  };
50
53
  };
54
+
55
+ /**
56
+ * What the Flex child writes to its stderr for a fault nothing else handled, before it shuts down
57
+ * with exit code 1: the error's name and message, its causes included, then its stack, one line
58
+ * each. The supervisor writes every stderr line to the controller log with credentials hidden. A
59
+ * thrown value that is not an Error is named by its type and inspected shallowly.
60
+ */
61
+ export const formatFlexChildFault = (
62
+ kindArg: 'uncaught exception' | 'unhandled rejection',
63
+ errorArg: unknown,
64
+ ): string => {
65
+ if (!(errorArg instanceof Error)) {
66
+ const value = plugins.util.inspect(errorArg, { depth: 1, breakLength: Infinity });
67
+ return `Flex child ${kindArg}: a thrown ${typeof errorArg} that is not an Error: ${value}\n`;
68
+ }
69
+ const failure = describeFailure(errorArg);
70
+ const stack = typeof errorArg.stack === 'string' ? errorArg.stack : '';
71
+ return `Flex child ${kindArg}: ${failure.name}: ${failure.message}\n${stack ? `${stack}\n` : ''}`;
72
+ };
@@ -3,8 +3,6 @@ export * from './v10_flexharnessv3migration.js';
3
3
  export * from './v16_flexprovidercredentials.js';
4
4
  export * from './v18_resourcelayout.js';
5
5
  export * from './v18_resourcelayoutmigration.js';
6
- export * from './classes.flexpostharnessmigrationrunner.js';
7
- export * from './v19_flexprojectmanagement.js';
8
6
  export * from './v22_projectfilesystemidentitymigration.js';
9
7
  export * from './v23_runtimeconfig.js';
10
8
  export * from './v24_legacyterminallayout.js';
@@ -30,3 +28,4 @@ export * from './v39_flexpublicheadpointers.js';
30
28
  export * from './v41_ticketmigrationmarkers.js';
31
29
  export * from './v41_ticketclosedcolumn.js';
32
30
  export * from './v41_ticketlinkrepos.js';
31
+ export * from './v43_flexpostharnessmigrationmarkers.js';
@@ -0,0 +1,66 @@
1
+ import * as plugins from './plugins.js';
2
+
3
+ /** The one migration AGL 43.0.4 recorded markers for: its per-session project-management walk. */
4
+ export type TFlexPostHarnessMigrationId = 'v19_flexprojectmanagement';
5
+
6
+ /** One post-harness migration that completed for one storage key (a Flex project). */
7
+ export interface IFlexPostHarnessMigrationMarkerDocument {
8
+ /** `flexPostHarnessMigrationMarkerId(controllerId, storageKey, migration)`. */
9
+ id: string;
10
+ controllerId: string;
11
+ storageKey: string;
12
+ /** The migration's name, such as `v19_flexprojectmanagement`. */
13
+ migration: string;
14
+ completedAt: string;
15
+ }
16
+
17
+ const markerSchema = plugins.z.object({
18
+ id: plugins.z.string().regex(/^flex-post-harness-migration:[0-9a-f]{64}$/u),
19
+ controllerId: plugins.z.string().min(1).max(512),
20
+ storageKey: plugins.z.string().min(1).max(512),
21
+ migration: plugins.z.string().regex(/^v[0-9]+_[a-z0-9]+$/u),
22
+ completedAt: plugins.z.iso.datetime(),
23
+ }).strict();
24
+
25
+ export const flexPostHarnessMigrationMarkerId = (
26
+ controllerIdArg: string,
27
+ storageKeyArg: string,
28
+ migrationArg: TFlexPostHarnessMigrationId,
29
+ ): string => `flex-post-harness-migration:${plugins.crypto.createHash('sha256')
30
+ .update(controllerIdArg, 'utf8')
31
+ .update('\0', 'utf8')
32
+ .update(storageKeyArg, 'utf8')
33
+ .update('\0', 'utf8')
34
+ .update(migrationArg, 'utf8')
35
+ .digest('hex')}`;
36
+
37
+ /**
38
+ * One record per storage key whose v19 project-management walk AGL 43.0.4 completed. Nothing
39
+ * reads or writes them since registration stopped walking sessions: each session's state is
40
+ * read, and a legacy scratchpad copied into it, when it is first loaded. The model stays
41
+ * registered and prepared, so the Flex store prepares what 43.0.4 prepared, and the documents
42
+ * stay where 43.0.4 reads them.
43
+ */
44
+ @plugins.nosqldb.managed({ collectionName: 'flex_post_harness_migrations' })
45
+ @plugins.nosqldb.exactPersistence({ assertDocument: (input: unknown) => { markerSchema.parse(input); } })
46
+ export class FlexPostHarnessMigrationMarkerModel extends plugins.nosqldb.SmartDataDbDoc<
47
+ FlexPostHarnessMigrationMarkerModel,
48
+ IFlexPostHarnessMigrationMarkerDocument
49
+ > {
50
+ declare static exact: plugins.nosqldb.TExact<FlexPostHarnessMigrationMarkerModel>;
51
+ @plugins.nosqldb.unI() public id!: string;
52
+ @plugins.nosqldb.svDb() public controllerId!: string;
53
+ @plugins.nosqldb.svDb() public storageKey!: string;
54
+ @plugins.nosqldb.svDb() public migration!: string;
55
+ @plugins.nosqldb.svDb() public completedAt!: string;
56
+ }
57
+
58
+ export const registerFlexPostHarnessMigrationMarkerModel = (
59
+ managerArg: { db: plugins.nosqldb.SmartdataDb },
60
+ ): void => {
61
+ plugins.nosqldb.setDefaultManagerForDoc(managerArg, FlexPostHarnessMigrationMarkerModel);
62
+ };
63
+
64
+ export const initFlexPostHarnessMigrationMarkerModel = async (): Promise<void> => {
65
+ await FlexPostHarnessMigrationMarkerModel.exact.prepare();
66
+ };
@@ -3,6 +3,6 @@
3
3
  */
4
4
  export const commitinfo = {
5
5
  name: 'agl',
6
- version: '43.0.3',
6
+ version: '43.0.5',
7
7
  description: 'Agent Gateway Layer for OpenCode, FlexHarness, and Codex sessions'
8
8
  }
@@ -1,10 +0,0 @@
1
- import * as plugins from './plugins.js';
2
- export interface IFlexPostHarnessMigrationRunnerOptions<TScope> {
3
- harness: plugins.flexharness.FlexHarness<TScope>;
4
- scopeIds: Iterable<string>;
5
- }
6
- export declare class FlexPostHarnessMigrationRunner<TScope> {
7
- private readonly migrations;
8
- constructor(optionsArg: IFlexPostHarnessMigrationRunnerOptions<TScope>);
9
- run(signalArg?: AbortSignal): Promise<void>;
10
- }
@@ -1,15 +0,0 @@
1
- import * as plugins from './plugins.js';
2
- import { FlexProjectManagementMigration } from './v19_flexprojectmanagement.js';
3
- export class FlexPostHarnessMigrationRunner {
4
- migrations;
5
- constructor(optionsArg) {
6
- this.migrations = [new FlexProjectManagementMigration(optionsArg)];
7
- }
8
- async run(signalArg) {
9
- for (const migration of this.migrations) {
10
- signalArg?.throwIfAborted();
11
- await migration.run(signalArg);
12
- }
13
- }
14
- }
15
- //# sourceMappingURL=data:application/json;base64,eyJ2ZXJzaW9uIjozLCJmaWxlIjoiY2xhc3Nlcy5mbGV4cG9zdGhhcm5lc3NtaWdyYXRpb25ydW5uZXIuanMiLCJzb3VyY2VSb290IjoiIiwic291cmNlcyI6WyIuLi8uLi90c19taWdyYXRpb24vY2xhc3Nlcy5mbGV4cG9zdGhhcm5lc3NtaWdyYXRpb25ydW5uZXIudHMiXSwibmFtZXMiOltdLCJtYXBwaW5ncyI6IkFBQUEsT0FBTyxLQUFLLE9BQU8sTUFBTSxjQUFjLENBQUM7QUFDeEMsT0FBTyxFQUFFLDhCQUE4QixFQUFFLE1BQU0sZ0NBQWdDLENBQUM7QUFPaEYsTUFBTSxPQUFPLDhCQUE4QjtJQUN4QixVQUFVLENBQXlEO0lBRXBGLFlBQVksVUFBMEQ7UUFDcEUsSUFBSSxDQUFDLFVBQVUsR0FBRyxDQUFDLElBQUksOEJBQThCLENBQUMsVUFBVSxDQUFDLENBQUMsQ0FBQztJQUNyRSxDQUFDO0lBRU0sS0FBSyxDQUFDLEdBQUcsQ0FBQyxTQUF1QjtRQUN0QyxLQUFLLE1BQU0sU0FBUyxJQUFJLElBQUksQ0FBQyxVQUFVLEVBQUUsQ0FBQztZQUN4QyxTQUFTLEVBQUUsY0FBYyxFQUFFLENBQUM7WUFDNUIsTUFBTSxTQUFTLENBQUMsR0FBRyxDQUFDLFNBQVMsQ0FBQyxDQUFDO1FBQ2pDLENBQUM7SUFDSCxDQUFDO0NBQ0YifQ==
@@ -1,11 +0,0 @@
1
- import * as plugins from './plugins.js';
2
- export interface IFlexProjectManagementMigrationOptions<TScope> {
3
- harness: plugins.flexharness.FlexHarness<TScope>;
4
- scopeIds: Iterable<string>;
5
- }
6
- export declare class FlexProjectManagementMigration<TScope> {
7
- private readonly harness;
8
- private readonly scopeIds;
9
- constructor(optionsArg: IFlexProjectManagementMigrationOptions<TScope>);
10
- run(signalArg?: AbortSignal): Promise<void>;
11
- }
@@ -1,21 +0,0 @@
1
- import * as plugins from './plugins.js';
2
- export class FlexProjectManagementMigration {
3
- harness;
4
- scopeIds;
5
- constructor(optionsArg) {
6
- this.harness = optionsArg.harness;
7
- this.scopeIds = [...new Set(optionsArg.scopeIds)].sort();
8
- }
9
- async run(signalArg) {
10
- for (const scopeId of this.scopeIds) {
11
- signalArg?.throwIfAborted();
12
- // listSessions durably repairs legacy session generations before PM state is loaded.
13
- const sessions = await this.harness.listSessions(scopeId);
14
- for (const session of sessions) {
15
- signalArg?.throwIfAborted();
16
- await this.harness.getProjectState(scopeId, session.sessionId);
17
- }
18
- }
19
- }
20
- }
21
- //# sourceMappingURL=data:application/json;base64,eyJ2ZXJzaW9uIjozLCJmaWxlIjoidjE5X2ZsZXhwcm9qZWN0bWFuYWdlbWVudC5qcyIsInNvdXJjZVJvb3QiOiIiLCJzb3VyY2VzIjpbIi4uLy4uL3RzX21pZ3JhdGlvbi92MTlfZmxleHByb2plY3RtYW5hZ2VtZW50LnRzIl0sIm5hbWVzIjpbXSwibWFwcGluZ3MiOiJBQUFBLE9BQU8sS0FBSyxPQUFPLE1BQU0sY0FBYyxDQUFDO0FBT3hDLE1BQU0sT0FBTyw4QkFBOEI7SUFDeEIsT0FBTyxDQUEwQztJQUNqRCxRQUFRLENBQVc7SUFFcEMsWUFBWSxVQUEwRDtRQUNwRSxJQUFJLENBQUMsT0FBTyxHQUFHLFVBQVUsQ0FBQyxPQUFPLENBQUM7UUFDbEMsSUFBSSxDQUFDLFFBQVEsR0FBRyxDQUFDLEdBQUcsSUFBSSxHQUFHLENBQUMsVUFBVSxDQUFDLFFBQVEsQ0FBQyxDQUFDLENBQUMsSUFBSSxFQUFFLENBQUM7SUFDM0QsQ0FBQztJQUVNLEtBQUssQ0FBQyxHQUFHLENBQUMsU0FBdUI7UUFDdEMsS0FBSyxNQUFNLE9BQU8sSUFBSSxJQUFJLENBQUMsUUFBUSxFQUFFLENBQUM7WUFDcEMsU0FBUyxFQUFFLGNBQWMsRUFBRSxDQUFDO1lBQzVCLHFGQUFxRjtZQUNyRixNQUFNLFFBQVEsR0FBRyxNQUFNLElBQUksQ0FBQyxPQUFPLENBQUMsWUFBWSxDQUFDLE9BQU8sQ0FBQyxDQUFDO1lBQzFELEtBQUssTUFBTSxPQUFPLElBQUksUUFBUSxFQUFFLENBQUM7Z0JBQy9CLFNBQVMsRUFBRSxjQUFjLEVBQUUsQ0FBQztnQkFDNUIsTUFBTSxJQUFJLENBQUMsT0FBTyxDQUFDLGVBQWUsQ0FBQyxPQUFPLEVBQUUsT0FBTyxDQUFDLFNBQVMsQ0FBQyxDQUFDO1lBQ2pFLENBQUM7UUFDSCxDQUFDO0lBQ0gsQ0FBQztDQUNGIn0=
@@ -1,22 +0,0 @@
1
- import * as plugins from './plugins.js';
2
- import { FlexProjectManagementMigration } from './v19_flexprojectmanagement.js';
3
-
4
- export interface IFlexPostHarnessMigrationRunnerOptions<TScope> {
5
- harness: plugins.flexharness.FlexHarness<TScope>;
6
- scopeIds: Iterable<string>;
7
- }
8
-
9
- export class FlexPostHarnessMigrationRunner<TScope> {
10
- private readonly migrations: Array<{ run(signalArg?: AbortSignal): Promise<void> }>;
11
-
12
- constructor(optionsArg: IFlexPostHarnessMigrationRunnerOptions<TScope>) {
13
- this.migrations = [new FlexProjectManagementMigration(optionsArg)];
14
- }
15
-
16
- public async run(signalArg?: AbortSignal): Promise<void> {
17
- for (const migration of this.migrations) {
18
- signalArg?.throwIfAborted();
19
- await migration.run(signalArg);
20
- }
21
- }
22
- }
@@ -1,28 +0,0 @@
1
- import * as plugins from './plugins.js';
2
-
3
- export interface IFlexProjectManagementMigrationOptions<TScope> {
4
- harness: plugins.flexharness.FlexHarness<TScope>;
5
- scopeIds: Iterable<string>;
6
- }
7
-
8
- export class FlexProjectManagementMigration<TScope> {
9
- private readonly harness: plugins.flexharness.FlexHarness<TScope>;
10
- private readonly scopeIds: string[];
11
-
12
- constructor(optionsArg: IFlexProjectManagementMigrationOptions<TScope>) {
13
- this.harness = optionsArg.harness;
14
- this.scopeIds = [...new Set(optionsArg.scopeIds)].sort();
15
- }
16
-
17
- public async run(signalArg?: AbortSignal): Promise<void> {
18
- for (const scopeId of this.scopeIds) {
19
- signalArg?.throwIfAborted();
20
- // listSessions durably repairs legacy session generations before PM state is loaded.
21
- const sessions = await this.harness.listSessions(scopeId);
22
- for (const session of sessions) {
23
- signalArg?.throwIfAborted();
24
- await this.harness.getProjectState(scopeId, session.sessionId);
25
- }
26
- }
27
- }
28
- }