agl 43.0.4 → 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 (30) hide show
  1. package/changelog.md +7 -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.flexservice.d.ts +6 -7
  6. package/dist_ts/classes.flexservice.js +12 -45
  7. package/dist_ts/classes.flexsupervisor.d.ts +37 -3
  8. package/dist_ts/classes.flexsupervisor.js +164 -37
  9. package/dist_ts/flexharness.child.js +9 -4
  10. package/dist_ts/functions.flexchildshutdown.d.ts +7 -0
  11. package/dist_ts/functions.flexchildshutdown.js +18 -1
  12. package/dist_ts_migration/index.d.ts +0 -2
  13. package/dist_ts_migration/index.js +1 -3
  14. package/dist_ts_migration/v43_flexpostharnessmigrationmarkers.d.ts +6 -17
  15. package/dist_ts_migration/v43_flexpostharnessmigrationmarkers.js +6 -36
  16. package/package.json +1 -1
  17. package/ts/00_commitinfo_data.ts +1 -1
  18. package/ts/classes.flexservice.ts +10 -66
  19. package/ts/classes.flexsupervisor.ts +214 -37
  20. package/ts/flexharness.child.ts +8 -3
  21. package/ts/functions.flexchildshutdown.ts +22 -0
  22. package/ts_migration/index.ts +0 -2
  23. package/ts_migration/v43_flexpostharnessmigrationmarkers.ts +6 -49
  24. package/ts_web/00_commitinfo_data.ts +1 -1
  25. package/dist_ts_migration/classes.flexpostharnessmigrationrunner.d.ts +0 -19
  26. package/dist_ts_migration/classes.flexpostharnessmigrationrunner.js +0 -34
  27. package/dist_ts_migration/v19_flexprojectmanagement.d.ts +0 -14
  28. package/dist_ts_migration/v19_flexprojectmanagement.js +0 -23
  29. package/ts_migration/classes.flexpostharnessmigrationrunner.ts +0 -54
  30. package/ts_migration/v19_flexprojectmanagement.ts +0 -32
@@ -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,
@@ -73,11 +73,19 @@ export interface IFlexSupervisorLogEntry {
73
73
  /** An error of a child's log pipe, or of a started child process, the supervisor recorded and ignored. */
74
74
  export interface IFlexSupervisorIgnoredError {
75
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;
76
78
  code?: string;
77
79
  timestamp: number;
78
80
  }
79
81
 
80
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;
81
89
  onChildExitObserved?: (exitArg: IFlexSupervisorExit) => void;
82
90
  onChildExit?: (exitArg: IFlexSupervisorExit) => void;
83
91
  cancellationGraceTimeoutMs?: number;
@@ -156,6 +164,19 @@ interface ILogAccumulator {
156
164
  decoder: TextDecoder;
157
165
  partial: string;
158
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;
159
180
  }
160
181
 
161
182
  const supervisorLogEntries = 200;
@@ -165,6 +186,17 @@ const supervisorTermTimeoutMs = 5_000;
165
186
  const supervisorKillTimeoutMs = 2_000;
166
187
  const logSuffix = '... [truncated]';
167
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;
168
200
 
169
201
  export class FlexBrowserChannelNotificationUnavailableError extends Error {
170
202
  constructor() {
@@ -326,12 +358,9 @@ export class FlexSupervisor {
326
358
  private readonly eventListeners = new Set<(eventArg: TFlexChildEvent) => void>();
327
359
  private readonly logs: IFlexSupervisorLogEntry[] = [];
328
360
  private readonly ignoredChildErrors: IFlexSupervisorIgnoredError[] = [];
329
- private readonly stdoutAccumulator: ILogAccumulator = {
330
- decoder: new TextDecoder(), partial: '', dropping: false,
331
- };
332
- private readonly stderrAccumulator: ILogAccumulator = {
333
- decoder: new TextDecoder(), partial: '', dropping: false,
334
- };
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;
335
364
  private readonly cancellationGraceTimeoutMs: number;
336
365
  private readonly childTaskDrainTimeoutMs: number;
337
366
  /** The writer identity of the current child generation, until its exit is confirmed. */
@@ -340,6 +369,7 @@ export class FlexSupervisor {
340
369
  private readonly retiredWriterIds: string[] = [];
341
370
 
342
371
  constructor(private readonly options: IFlexSupervisorOptions = {}) {
372
+ this.writeControllerLog = options.writeControllerLog ?? ((lineArg) => console.error(lineArg));
343
373
  this.cancellationGraceTimeoutMs = this.normalizeDeadline(
344
374
  options.cancellationGraceTimeoutMs,
345
375
  flexIpcCancellationGraceTimeoutMs,
@@ -1379,19 +1409,40 @@ export class FlexSupervisor {
1379
1409
  }
1380
1410
 
1381
1411
  private observeChild(childArg: plugins.childProcess.ChildProcess): Promise<IFlexChildLifecycle> {
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
+ };
1382
1422
  // The log pipes and the process keep their error listeners for as long as they exist: an error
1383
- // event without a listener throws, and the child's lifecycle never depends on its log pipes.
1384
- childArg.stdout?.on('data', (chunk) => this.consumeLog('stdout', chunk, this.stdoutAccumulator));
1385
- childArg.stdout?.on('error', (errorArg) => this.recordIgnoredChildError('stdout', errorArg));
1386
- childArg.stderr?.on('data', (chunk) => this.consumeLog('stderr', chunk, this.stderrAccumulator));
1387
- childArg.stderr?.on('error', (errorArg) => this.recordIgnoredChildError('stderr', errorArg));
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
+ }
1388
1440
  return new Promise((resolve) => {
1389
1441
  let settled = false;
1390
1442
  const finish = (outcomeArg: IFlexChildLifecycle): void => {
1391
1443
  if (settled) return;
1392
1444
  settled = true;
1393
- this.flushLog('stdout', this.stdoutAccumulator);
1394
- this.flushLog('stderr', this.stderrAccumulator);
1445
+ this.logAbnormalExit(logGeneration, outcomeArg, this.status.state === 'stopping');
1395
1446
  this.status = { state: this.status.state === 'stopping' ? 'stopped' : 'failed', ready: false };
1396
1447
  this.browserPeerId = '';
1397
1448
  this.browserChannelGenerations.clear();
@@ -1437,14 +1488,59 @@ export class FlexSupervisor {
1437
1488
  // A child without a process ID never started, and its error is its outcome; a started
1438
1489
  // child's error (a failed signal) leaves its lifecycle to its exit.
1439
1490
  if (!childArg.pid) finish({ type: 'error', error });
1440
- else this.recordIgnoredChildError('process', error);
1491
+ else this.recordIgnoredChildError('process', logGeneration.generation, error);
1441
1492
  });
1442
1493
  });
1443
1494
  }
1444
1495
 
1445
- private recordIgnoredChildError(sourceArg: IFlexSupervisorIgnoredError['source'], errorArg: Error): void {
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 {
1446
1537
  const code = 'code' in errorArg && typeof errorArg.code === 'string' ? errorArg.code : undefined;
1447
- this.ignoredChildErrors.push({ source: sourceArg, ...(code ? { code } : {}), timestamp: Date.now() });
1538
+ this.ignoredChildErrors.push({
1539
+ source: sourceArg,
1540
+ generation: generationArg,
1541
+ ...(code ? { code } : {}),
1542
+ timestamp: Date.now(),
1543
+ });
1448
1544
  if (this.ignoredChildErrors.length > supervisorIgnoredErrorEntries) this.ignoredChildErrors.shift();
1449
1545
  }
1450
1546
 
@@ -1628,9 +1724,9 @@ export class FlexSupervisor {
1628
1724
  }
1629
1725
 
1630
1726
  private consumeLog(
1727
+ logGenerationArg: IFlexChildLogGeneration,
1631
1728
  streamArg: IFlexSupervisorLogEntry['stream'],
1632
1729
  chunkArg: unknown,
1633
- accumulatorArg: ILogAccumulator,
1634
1730
  ): void {
1635
1731
  const bytes = typeof chunkArg === 'string'
1636
1732
  ? Buffer.from(chunkArg, 'utf8')
@@ -1638,49 +1734,64 @@ export class FlexSupervisor {
1638
1734
  ? chunkArg
1639
1735
  : undefined;
1640
1736
  if (!bytes) return;
1641
- 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;
1642
1748
  while (text.length > 0) {
1643
- if (accumulatorArg.dropping) {
1749
+ if (accumulator.dropping) {
1644
1750
  const newline = text.indexOf('\n');
1645
1751
  if (newline < 0) return;
1646
- accumulatorArg.dropping = false;
1752
+ accumulator.dropping = false;
1647
1753
  text = text.slice(newline + 1);
1648
1754
  continue;
1649
1755
  }
1650
1756
  const newline = text.indexOf('\n');
1651
1757
  if (newline >= 0) {
1652
- const complete = `${accumulatorArg.partial}${text.slice(0, newline)}`.replace(/\r$/u, '');
1653
- accumulatorArg.partial = '';
1654
- 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);
1655
1761
  text = text.slice(newline + 1);
1656
1762
  continue;
1657
1763
  }
1658
- const complete = `${accumulatorArg.partial}${text}`;
1764
+ const complete = `${accumulator.partial}${text}`;
1659
1765
  if (Buffer.byteLength(complete, 'utf8') > supervisorLogLineBytes) {
1660
- this.addLog(streamArg, complete);
1661
- accumulatorArg.partial = '';
1662
- accumulatorArg.dropping = true;
1766
+ this.addLog(logGenerationArg, streamArg, complete);
1767
+ accumulator.partial = '';
1768
+ accumulator.dropping = true;
1663
1769
  } else {
1664
- accumulatorArg.partial = complete;
1770
+ accumulator.partial = complete;
1665
1771
  }
1666
1772
  return;
1667
1773
  }
1668
1774
  }
1669
1775
 
1670
1776
  private flushLog(
1777
+ logGenerationArg: IFlexChildLogGeneration,
1671
1778
  streamArg: IFlexSupervisorLogEntry['stream'],
1672
- accumulatorArg: ILogAccumulator,
1673
1779
  ): void {
1674
- const final = accumulatorArg.decoder.decode();
1675
- if (final) this.consumeLog(streamArg, final, accumulatorArg);
1676
- if (accumulatorArg.partial && !accumulatorArg.dropping) {
1677
- 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);
1678
1785
  }
1679
- accumulatorArg.partial = '';
1680
- accumulatorArg.dropping = false;
1786
+ accumulator.partial = '';
1787
+ accumulator.dropping = false;
1681
1788
  }
1682
1789
 
1683
- private addLog(streamArg: IFlexSupervisorLogEntry['stream'], lineArg: string): void {
1790
+ private addLog(
1791
+ logGenerationArg: IFlexChildLogGeneration,
1792
+ streamArg: IFlexSupervisorLogEntry['stream'],
1793
+ lineArg: string,
1794
+ ): void {
1684
1795
  const bounded = truncateLog(lineArg);
1685
1796
  this.logs.push({
1686
1797
  timestamp: Date.now(),
@@ -1691,5 +1802,71 @@ export class FlexSupervisor {
1691
1802
  if (this.logs.length > supervisorLogEntries) {
1692
1803
  this.logs.splice(0, this.logs.length - supervisorLogEntries);
1693
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
+ }
1694
1871
  }
1695
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';
@@ -1,6 +1,6 @@
1
1
  import * as plugins from './plugins.js';
2
2
 
3
- /** The Flex migrations that run through FlexHarness once the harness is up, by name. */
3
+ /** The one migration AGL 43.0.4 recorded markers for: its per-session project-management walk. */
4
4
  export type TFlexPostHarnessMigrationId = 'v19_flexprojectmanagement';
5
5
 
6
6
  /** One post-harness migration that completed for one storage key (a Flex project). */
@@ -35,9 +35,11 @@ export const flexPostHarnessMigrationMarkerId = (
35
35
  .digest('hex')}`;
36
36
 
37
37
  /**
38
- * One record per post-harness migration and storage key, written once the migration walked every
39
- * session of that key: a key with a marker is never walked again, by any later Flex child. A walk
40
- * that failed or was aborted records nothing, so the next registration walks the key again.
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.
41
43
  */
42
44
  @plugins.nosqldb.managed({ collectionName: 'flex_post_harness_migrations' })
43
45
  @plugins.nosqldb.exactPersistence({ assertDocument: (input: unknown) => { markerSchema.parse(input); } })
@@ -62,48 +64,3 @@ export const registerFlexPostHarnessMigrationMarkerModel = (
62
64
  export const initFlexPostHarnessMigrationMarkerModel = async (): Promise<void> => {
63
65
  await FlexPostHarnessMigrationMarkerModel.exact.prepare();
64
66
  };
65
-
66
- /** Which post-harness migrations completed for a storage key; see `FlexPostHarnessMigrationRunner`. */
67
- export interface IFlexPostHarnessMigrationMarkers {
68
- completed(storageKeyArg: string, migrationArg: TFlexPostHarnessMigrationId): Promise<boolean>;
69
- /** Records the completion; recording one that is already recorded changes nothing. */
70
- record(storageKeyArg: string, migrationArg: TFlexPostHarnessMigrationId): Promise<void>;
71
- }
72
-
73
- /** The markers of one controller, in its Flex database's `flex_post_harness_migrations`. */
74
- export class FlexPostHarnessMigrationMarkers implements IFlexPostHarnessMigrationMarkers {
75
- constructor(private readonly controllerId: string) {}
76
-
77
- public async completed(
78
- storageKeyArg: string,
79
- migrationArg: TFlexPostHarnessMigrationId,
80
- ): Promise<boolean> {
81
- const id = flexPostHarnessMigrationMarkerId(this.controllerId, storageKeyArg, migrationArg);
82
- const stored = await FlexPostHarnessMigrationMarkerModel.exact.findStoredOne({ id });
83
- if (!stored) return false;
84
- const marker = FlexPostHarnessMigrationMarkerModel.exact.toPersisted(stored);
85
- if (
86
- marker.controllerId !== this.controllerId
87
- || marker.storageKey !== storageKeyArg
88
- || marker.migration !== migrationArg
89
- ) throw new Error('The Flex post-harness migration marker names another migration.');
90
- return true;
91
- }
92
-
93
- public async record(
94
- storageKeyArg: string,
95
- migrationArg: TFlexPostHarnessMigrationId,
96
- ): Promise<void> {
97
- const inserted = await FlexPostHarnessMigrationMarkerModel.exact.insert({
98
- id: flexPostHarnessMigrationMarkerId(this.controllerId, storageKeyArg, migrationArg),
99
- controllerId: this.controllerId,
100
- storageKey: storageKeyArg,
101
- migration: migrationArg,
102
- completedAt: new Date().toISOString(),
103
- });
104
- // A conflict is a marker with the same id recorded earlier, with its own completion time.
105
- if (inserted.status === 'conflict' && !await this.completed(storageKeyArg, migrationArg)) {
106
- throw new Error('The Flex post-harness migration marker could not be recorded.');
107
- }
108
- }
109
- }
@@ -3,6 +3,6 @@
3
3
  */
4
4
  export const commitinfo = {
5
5
  name: 'agl',
6
- version: '43.0.4',
6
+ version: '43.0.5',
7
7
  description: 'Agent Gateway Layer for OpenCode, FlexHarness, and Codex sessions'
8
8
  }
@@ -1,19 +0,0 @@
1
- import * as plugins from './plugins.js';
2
- import type { IFlexPostHarnessMigrationMarkers } from './v43_flexpostharnessmigrationmarkers.js';
3
- export interface IFlexPostHarnessMigrationRunnerOptions<TScope> {
4
- harness: plugins.flexharness.FlexHarness<TScope>;
5
- /** The storage keys each migration already completed for, which it never walks again. */
6
- markers: IFlexPostHarnessMigrationMarkers;
7
- scopeIds: Iterable<string>;
8
- }
9
- /**
10
- * Runs each post-harness migration for every storage key it has not completed for, and records
11
- * the completion only once the key's walk finished: a failed or aborted walk records nothing.
12
- */
13
- export declare class FlexPostHarnessMigrationRunner<TScope> {
14
- private readonly markers;
15
- private readonly scopeIds;
16
- private readonly migrations;
17
- constructor(optionsArg: IFlexPostHarnessMigrationRunnerOptions<TScope>);
18
- run(signalArg?: AbortSignal): Promise<void>;
19
- }
@@ -1,34 +0,0 @@
1
- import * as plugins from './plugins.js';
2
- import { FlexProjectManagementMigration, flexProjectManagementMigrationId, } from './v19_flexprojectmanagement.js';
3
- /**
4
- * Runs each post-harness migration for every storage key it has not completed for, and records
5
- * the completion only once the key's walk finished: a failed or aborted walk records nothing.
6
- */
7
- export class FlexPostHarnessMigrationRunner {
8
- markers;
9
- scopeIds;
10
- migrations;
11
- constructor(optionsArg) {
12
- this.markers = optionsArg.markers;
13
- this.scopeIds = [...new Set(optionsArg.scopeIds)].sort();
14
- this.migrations = [{
15
- id: flexProjectManagementMigrationId,
16
- run: (scopeIdArg, signalArg) => new FlexProjectManagementMigration({
17
- harness: optionsArg.harness,
18
- scopeIds: [scopeIdArg],
19
- }).run(signalArg),
20
- }];
21
- }
22
- async run(signalArg) {
23
- for (const migration of this.migrations) {
24
- for (const scopeId of this.scopeIds) {
25
- signalArg?.throwIfAborted();
26
- if (await this.markers.completed(scopeId, migration.id))
27
- continue;
28
- await migration.run(scopeId, signalArg);
29
- await this.markers.record(scopeId, migration.id);
30
- }
31
- }
32
- }
33
- }
34
- //# sourceMappingURL=data:application/json;base64,eyJ2ZXJzaW9uIjozLCJmaWxlIjoiY2xhc3Nlcy5mbGV4cG9zdGhhcm5lc3NtaWdyYXRpb25ydW5uZXIuanMiLCJzb3VyY2VSb290IjoiIiwic291cmNlcyI6WyIuLi8uLi90c19taWdyYXRpb24vY2xhc3Nlcy5mbGV4cG9zdGhhcm5lc3NtaWdyYXRpb25ydW5uZXIudHMiXSwibmFtZXMiOltdLCJtYXBwaW5ncyI6IkFBQUEsT0FBTyxLQUFLLE9BQU8sTUFBTSxjQUFjLENBQUM7QUFDeEMsT0FBTyxFQUNMLDhCQUE4QixFQUM5QixnQ0FBZ0MsR0FDakMsTUFBTSxnQ0FBZ0MsQ0FBQztBQWtCeEM7OztHQUdHO0FBQ0gsTUFBTSxPQUFPLDhCQUE4QjtJQUN4QixPQUFPLENBQW1DO0lBQzFDLFFBQVEsQ0FBVztJQUNuQixVQUFVLENBQThCO0lBRXpELFlBQVksVUFBMEQ7UUFDcEUsSUFBSSxDQUFDLE9BQU8sR0FBRyxVQUFVLENBQUMsT0FBTyxDQUFDO1FBQ2xDLElBQUksQ0FBQyxRQUFRLEdBQUcsQ0FBQyxHQUFHLElBQUksR0FBRyxDQUFDLFVBQVUsQ0FBQyxRQUFRLENBQUMsQ0FBQyxDQUFDLElBQUksRUFBRSxDQUFDO1FBQ3pELElBQUksQ0FBQyxVQUFVLEdBQUcsQ0FBQztnQkFDakIsRUFBRSxFQUFFLGdDQUFnQztnQkFDcEMsR0FBRyxFQUFFLENBQUMsVUFBVSxFQUFFLFNBQVMsRUFBRSxFQUFFLENBQUMsSUFBSSw4QkFBOEIsQ0FBQztvQkFDakUsT0FBTyxFQUFFLFVBQVUsQ0FBQyxPQUFPO29CQUMzQixRQUFRLEVBQUUsQ0FBQyxVQUFVLENBQUM7aUJBQ3ZCLENBQUMsQ0FBQyxHQUFHLENBQUMsU0FBUyxDQUFDO2FBQ2xCLENBQUMsQ0FBQztJQUNMLENBQUM7SUFFTSxLQUFLLENBQUMsR0FBRyxDQUFDLFNBQXVCO1FBQ3RDLEtBQUssTUFBTSxTQUFTLElBQUksSUFBSSxDQUFDLFVBQVUsRUFBRSxDQUFDO1lBQ3hDLEtBQUssTUFBTSxPQUFPLElBQUksSUFBSSxDQUFDLFFBQVEsRUFBRSxDQUFDO2dCQUNwQyxTQUFTLEVBQUUsY0FBYyxFQUFFLENBQUM7Z0JBQzVCLElBQUksTUFBTSxJQUFJLENBQUMsT0FBTyxDQUFDLFNBQVMsQ0FBQyxPQUFPLEVBQUUsU0FBUyxDQUFDLEVBQUUsQ0FBQztvQkFBRSxTQUFTO2dCQUNsRSxNQUFNLFNBQVMsQ0FBQyxHQUFHLENBQUMsT0FBTyxFQUFFLFNBQVMsQ0FBQyxDQUFDO2dCQUN4QyxNQUFNLElBQUksQ0FBQyxPQUFPLENBQUMsTUFBTSxDQUFDLE9BQU8sRUFBRSxTQUFTLENBQUMsRUFBRSxDQUFDLENBQUM7WUFDbkQsQ0FBQztRQUNILENBQUM7SUFDSCxDQUFDO0NBQ0YifQ==
@@ -1,14 +0,0 @@
1
- import * as plugins from './plugins.js';
2
- import type { TFlexPostHarnessMigrationId } from './v43_flexpostharnessmigrationmarkers.js';
3
- /** The name its completion is recorded under (`FlexPostHarnessMigrationMarkers`). */
4
- export declare const flexProjectManagementMigrationId: TFlexPostHarnessMigrationId;
5
- export interface IFlexProjectManagementMigrationOptions<TScope> {
6
- harness: plugins.flexharness.FlexHarness<TScope>;
7
- scopeIds: Iterable<string>;
8
- }
9
- export declare class FlexProjectManagementMigration<TScope> {
10
- private readonly harness;
11
- private readonly scopeIds;
12
- constructor(optionsArg: IFlexProjectManagementMigrationOptions<TScope>);
13
- run(signalArg?: AbortSignal): Promise<void>;
14
- }
@@ -1,23 +0,0 @@
1
- import * as plugins from './plugins.js';
2
- /** The name its completion is recorded under (`FlexPostHarnessMigrationMarkers`). */
3
- export const flexProjectManagementMigrationId = 'v19_flexprojectmanagement';
4
- export class FlexProjectManagementMigration {
5
- harness;
6
- scopeIds;
7
- constructor(optionsArg) {
8
- this.harness = optionsArg.harness;
9
- this.scopeIds = [...new Set(optionsArg.scopeIds)].sort();
10
- }
11
- async run(signalArg) {
12
- for (const scopeId of this.scopeIds) {
13
- signalArg?.throwIfAborted();
14
- // listSessions durably repairs legacy session generations before PM state is loaded.
15
- const sessions = await this.harness.listSessions(scopeId);
16
- for (const session of sessions) {
17
- signalArg?.throwIfAborted();
18
- await this.harness.getProjectState(scopeId, session.sessionId);
19
- }
20
- }
21
- }
22
- }
23
- //# sourceMappingURL=data:application/json;base64,eyJ2ZXJzaW9uIjozLCJmaWxlIjoidjE5X2ZsZXhwcm9qZWN0bWFuYWdlbWVudC5qcyIsInNvdXJjZVJvb3QiOiIiLCJzb3VyY2VzIjpbIi4uLy4uL3RzX21pZ3JhdGlvbi92MTlfZmxleHByb2plY3RtYW5hZ2VtZW50LnRzIl0sIm5hbWVzIjpbXSwibWFwcGluZ3MiOiJBQUFBLE9BQU8sS0FBSyxPQUFPLE1BQU0sY0FBYyxDQUFDO0FBR3hDLHFGQUFxRjtBQUNyRixNQUFNLENBQUMsTUFBTSxnQ0FBZ0MsR0FBZ0MsMkJBQTJCLENBQUM7QUFPekcsTUFBTSxPQUFPLDhCQUE4QjtJQUN4QixPQUFPLENBQTBDO0lBQ2pELFFBQVEsQ0FBVztJQUVwQyxZQUFZLFVBQTBEO1FBQ3BFLElBQUksQ0FBQyxPQUFPLEdBQUcsVUFBVSxDQUFDLE9BQU8sQ0FBQztRQUNsQyxJQUFJLENBQUMsUUFBUSxHQUFHLENBQUMsR0FBRyxJQUFJLEdBQUcsQ0FBQyxVQUFVLENBQUMsUUFBUSxDQUFDLENBQUMsQ0FBQyxJQUFJLEVBQUUsQ0FBQztJQUMzRCxDQUFDO0lBRU0sS0FBSyxDQUFDLEdBQUcsQ0FBQyxTQUF1QjtRQUN0QyxLQUFLLE1BQU0sT0FBTyxJQUFJLElBQUksQ0FBQyxRQUFRLEVBQUUsQ0FBQztZQUNwQyxTQUFTLEVBQUUsY0FBYyxFQUFFLENBQUM7WUFDNUIscUZBQXFGO1lBQ3JGLE1BQU0sUUFBUSxHQUFHLE1BQU0sSUFBSSxDQUFDLE9BQU8sQ0FBQyxZQUFZLENBQUMsT0FBTyxDQUFDLENBQUM7WUFDMUQsS0FBSyxNQUFNLE9BQU8sSUFBSSxRQUFRLEVBQUUsQ0FBQztnQkFDL0IsU0FBUyxFQUFFLGNBQWMsRUFBRSxDQUFDO2dCQUM1QixNQUFNLElBQUksQ0FBQyxPQUFPLENBQUMsZUFBZSxDQUFDLE9BQU8sRUFBRSxPQUFPLENBQUMsU0FBUyxDQUFDLENBQUM7WUFDakUsQ0FBQztRQUNILENBQUM7SUFDSCxDQUFDO0NBQ0YifQ==