@modelprofile.com/flexharness 17.0.1 → 18.1.0

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 (51) hide show
  1. package/dist_ts/00_commitinfo_data.js +1 -1
  2. package/dist_ts/classes.flexharness.callbacks.d.ts +25 -3
  3. package/dist_ts/classes.flexharness.callbacks.js +115 -18
  4. package/dist_ts/classes.flexharness.core.d.ts +58 -2
  5. package/dist_ts/classes.flexharness.core.js +392 -177
  6. package/dist_ts/classes.flexharness.d.ts +6 -1
  7. package/dist_ts/classes.flexharness.js +8 -1
  8. package/dist_ts/classes.flexharness.runs.js +10 -3
  9. package/dist_ts/classes.flexharness.sessions.d.ts +8 -1
  10. package/dist_ts/classes.flexharness.sessions.js +27 -1
  11. package/dist_ts/classes.timeslicer.d.ts +21 -0
  12. package/dist_ts/classes.timeslicer.js +31 -0
  13. package/dist_ts/classes.toolcatalog.d.ts +1 -1
  14. package/dist_ts/classes.toolcatalog.js +34 -29
  15. package/dist_ts/interfaces.d.ts +44 -3
  16. package/dist_ts/interfaces.flexharness.d.ts +30 -2
  17. package/dist_ts/interfaces.js +1 -1
  18. package/dist_ts/plugins.d.ts +2 -2
  19. package/dist_ts/plugins.js +3 -3
  20. package/dist_ts/utils.flexharness.d.ts +2 -0
  21. package/dist_ts/utils.flexharness.js +3 -1
  22. package/dist_ts/utils.json.d.ts +6 -0
  23. package/dist_ts/utils.json.js +92 -35
  24. package/dist_ts/utils.scopesnapshot.d.ts +14 -0
  25. package/dist_ts/utils.scopesnapshot.js +58 -0
  26. package/dist_ts/utils.text.d.ts +6 -0
  27. package/dist_ts/utils.text.js +10 -0
  28. package/dist_ts_chat_harness/functions.mapping.js +11 -4
  29. package/dist_ts_tools_node/classes.workspacereversion.d.ts +3 -2
  30. package/dist_ts_tools_node/classes.workspacereversion.js +17 -3
  31. package/package.json +3 -3
  32. package/readme.md +12 -1
  33. package/ts/00_commitinfo_data.ts +1 -1
  34. package/ts/classes.flexharness.callbacks.ts +110 -16
  35. package/ts/classes.flexharness.core.ts +452 -207
  36. package/ts/classes.flexharness.runs.ts +9 -1
  37. package/ts/classes.flexharness.sessions.ts +30 -0
  38. package/ts/classes.flexharness.ts +9 -0
  39. package/ts/classes.timeslicer.ts +32 -0
  40. package/ts/classes.toolcatalog.ts +34 -28
  41. package/ts/interfaces.flexharness.ts +32 -1
  42. package/ts/interfaces.ts +48 -3
  43. package/ts/plugins.ts +2 -0
  44. package/ts/readme.md +12 -1
  45. package/ts/utils.flexharness.ts +3 -0
  46. package/ts/utils.json.ts +88 -38
  47. package/ts/utils.scopesnapshot.ts +75 -0
  48. package/ts/utils.text.ts +9 -0
  49. package/ts_chat_harness/functions.mapping.ts +10 -3
  50. package/ts_tools_node/classes.workspacereversion.ts +19 -4
  51. package/ts_tools_node/readme.md +1 -1
@@ -59,6 +59,7 @@ import {
59
59
  combineErrors,
60
60
  delegatedCancellation,
61
61
  terminalActivityError,
62
+ toolCallNotStartedMessage,
62
63
  } from './utils.flexharness.js';
63
64
  import type { FlexHarnessCore } from './classes.flexharness.core.js';
64
65
 
@@ -144,6 +145,9 @@ export class FlexHarnessRuns<TScope> {
144
145
  },
145
146
  reasoningPartIds: new Map(),
146
147
  stepPartIds: new Set(),
148
+ stepStreamedCalls: new Map(),
149
+ stepInvalidCalls: new Map(),
150
+ textPartClosed: false,
147
151
  toolPartIds: new Map(),
148
152
  trustedToolExecutionErrors: new Map(),
149
153
  unconfirmedToolCalls: new Map(),
@@ -877,6 +881,8 @@ export class FlexHarnessRuns<TScope> {
877
881
  run.callbackParts = [];
878
882
  run.reasoningPartIds.clear();
879
883
  run.stepPartIds.clear();
884
+ run.stepStreamedCalls.clear();
885
+ run.stepInvalidCalls.clear();
880
886
  this.core.emitEvent(run.scopeId, run.stored.session, {
881
887
  type: 'message.updated',
882
888
  runId: run.runId,
@@ -954,7 +960,9 @@ export class FlexHarnessRuns<TScope> {
954
960
  delete part.output;
955
961
  part.error = status === 'cancelled'
956
962
  ? 'Tool execution was cancelled.'
957
- : 'Tool execution ended without a terminal event.';
963
+ : part.startedAt === undefined
964
+ ? toolCallNotStartedMessage
965
+ : 'Tool execution ended without a terminal event.';
958
966
  part.completedAt = timestamp;
959
967
  }
960
968
  }
@@ -14,6 +14,7 @@ import {
14
14
  type IFlexMessagePageOptions,
15
15
  type IFlexMessageReadOptions,
16
16
  type IFlexSession,
17
+ type IFlexSessionIdentity,
17
18
  type IFlexSessionView,
18
19
  type IFlexSessionMetrics,
19
20
  type IFlexSessionTombstone,
@@ -48,6 +49,7 @@ import {
48
49
  combineErrors,
49
50
  } from './utils.flexharness.js';
50
51
  import type { FlexHarnessCore } from './classes.flexharness.core.js';
52
+ import { liveScopeSessions, normalizeScopeSnapshot, sessionIdentities } from './utils.scopesnapshot.js';
51
53
 
52
54
  /**
53
55
  * Consecutive waits a session view makes for queued writes and open sections to settle. Each wait
@@ -84,6 +86,34 @@ export class FlexHarnessSessions<TScope> {
84
86
  .sort((left, right) => right.updatedAt.localeCompare(left.updatedAt)));
85
87
  }
86
88
 
89
+ /**
90
+ * The identities of a scope's live sessions, sorted by session id. Until the scope's load has
91
+ * settled they are read from its stored scope snapshot, normalized as the load normalizes it:
92
+ * they neither wait for the load nor read a session's projection, events or jobs, and nothing
93
+ * changes a scope before its load settles. Once it has, they are its loaded sessions'.
94
+ */
95
+ public async listSessionIdentities(scopeId: string): Promise<IFlexSessionIdentity[]> {
96
+ return this.core.withScopeAdmission(scopeId, async (scope, admitted) => {
97
+ const stateLoad = this.core.stateLoads.get(scope.storageKey);
98
+ if (stateLoad && this.core.isStateLoaded(stateLoad)) {
99
+ const state = await this.core.admittedState(scopeId, scope, stateLoad, admitted);
100
+ await state.scopeQueue;
101
+ this.core.assertOpen();
102
+ this.core.assertStateAcceptingWork(state);
103
+ return sessionIdentities([...state.sessions.values()]
104
+ .filter((stored) => !state.initializingSessions.has(stored.session.sessionId))
105
+ .map((stored) => stored.session));
106
+ }
107
+ const { snapshot } = normalizeScopeSnapshot(
108
+ scope.storageKey,
109
+ await this.core.stores.scopes.load(scope.storageKey),
110
+ );
111
+ this.core.assertOpen();
112
+ if (!admitted()) throw this.core.createScopeRetirementError();
113
+ return sessionIdentities(liveScopeSessions(snapshot));
114
+ });
115
+ }
116
+
87
117
  public async createSession(
88
118
  scopeId: string,
89
119
  options: IFlexCreateSessionOptions = {},
@@ -35,6 +35,7 @@ import type {
35
35
  IFlexScheduledPromptAdmission,
36
36
  IFlexSchedulePromptOptions,
37
37
  IFlexSession,
38
+ IFlexSessionIdentity,
38
39
  IFlexSessionView,
39
40
  IFlexSessionMetrics,
40
41
  IFlexSessionImportHandle,
@@ -73,6 +74,14 @@ export class FlexHarness<TScope = unknown> {
73
74
  return this.core.sessions.listSessions(scopeId);
74
75
  }
75
76
 
77
+ /**
78
+ * The identities of a scope's live sessions, sorted by session id. Before the scope is loaded
79
+ * they come from its stored scope metadata alone, without loading any session.
80
+ */
81
+ public listSessionIdentities(scopeId: string): Promise<IFlexSessionIdentity[]> {
82
+ return this.core.sessions.listSessionIdentities(scopeId);
83
+ }
84
+
76
85
  public createSession(
77
86
  scopeId: string,
78
87
  options?: IFlexCreateSessionOptions,
@@ -0,0 +1,32 @@
1
+ /**
2
+ * The longest stretch of scope-load work between two turns of the event loop. Timers, I/O and a
3
+ * caller's cancellation wait at most this long behind the load; at about 0.1 ms per turn the
4
+ * pauses cost well under 1% of the load's time.
5
+ */
6
+ export const scopeLoadSliceMs = 25;
7
+
8
+ /**
9
+ * Cuts long synchronous work into slices of elapsed time. Work checks `due` between steps and
10
+ * awaits `pause()` when it is: the event loop runs whatever waits behind the work, and the work
11
+ * stops with the signal's reason once the signal is aborted.
12
+ */
13
+ export class FlexTimeSlicer {
14
+ private sliceStartedAt = performance.now();
15
+
16
+ constructor(
17
+ private readonly signal: AbortSignal,
18
+ private readonly sliceMs = scopeLoadSliceMs,
19
+ ) {}
20
+
21
+ /** Whether the current slice has used its time. */
22
+ public get due(): boolean {
23
+ return performance.now() - this.sliceStartedAt >= this.sliceMs;
24
+ }
25
+
26
+ /** Lets the event loop run, then fails with the signal's reason if it was aborted. */
27
+ public async pause(): Promise<void> {
28
+ await new Promise<void>((resolve) => setImmediate(resolve));
29
+ this.signal.throwIfAborted();
30
+ this.sliceStartedAt = performance.now();
31
+ }
32
+ }
@@ -32,6 +32,7 @@ import {
32
32
  type TJsonSchemaNode,
33
33
  } from './utils.schemadeclarations.js';
34
34
  import { normalizeToolCatalogOptions } from './utils.harnessoptions.js';
35
+ import { sliceUtf16 } from './utils.text.js';
35
36
  import { validateUtf8String } from './utils.validation.js';
36
37
 
37
38
  type TValidationResult = { success: true; value: unknown } | { success: false; error: Error };
@@ -198,12 +199,13 @@ const isPlainObject = (value: unknown): value is Record<string, unknown> =>
198
199
  && !Array.isArray(value)
199
200
  && [Object.prototype, null].includes(Object.getPrototypeOf(value));
200
201
 
201
- const compareCodePoints = (left: string, right: string): number => left < right ? -1 : left > right ? 1 : 0;
202
+ /** JavaScript's string order: by UTF-16 code units, which puts an astral character before U+E000–U+FFFF. */
203
+ const compareUtf16 = (left: string, right: string): number => left < right ? -1 : left > right ? 1 : 0;
202
204
 
203
205
  const stableStringify = (value: unknown): string => {
204
206
  if (Array.isArray(value)) return `[${value.map(stableStringify).join(',')}]`;
205
207
  if (isSchemaRecord(value)) {
206
- return `{${Object.keys(value).sort(compareCodePoints)
208
+ return `{${Object.keys(value).sort(compareUtf16)
207
209
  .map((key) => `${JSON.stringify(key)}:${stableStringify(value[key])}`).join(',')}}`;
208
210
  }
209
211
  return JSON.stringify(value) ?? 'null';
@@ -323,7 +325,7 @@ const closeMatches = (wanted: string, candidates: Iterable<string>, count = 3):
323
325
  if (distance <= limit) scored.push({ name: candidate, distance });
324
326
  }
325
327
  return scored
326
- .sort((left, right) => left.distance - right.distance || compareCodePoints(left.name, right.name))
328
+ .sort((left, right) => left.distance - right.distance || compareUtf16(left.name, right.name))
327
329
  .slice(0, count)
328
330
  .map((entry) => entry.name);
329
331
  };
@@ -336,7 +338,7 @@ const preview = (value: unknown): string => {
336
338
  } catch {
337
339
  text = String(value);
338
340
  }
339
- return text.length > 80 ? `${text.slice(0, 77)}...` : text;
341
+ return text.length > 80 ? `${sliceUtf16(text, 77)}...` : text;
340
342
  };
341
343
 
342
344
  const paramsPath = (tokens: readonly (string | number)[]): string => tokens.reduce<string>((path, token) => {
@@ -356,7 +358,7 @@ const valueAt = (value: unknown, tokens: readonly (string | number)[]): unknown
356
358
 
357
359
  const compactType = (text: string): string => {
358
360
  const compact = text.replace(/\/\*\*[\s\S]*?\*\//g, '').replace(/\s+/g, ' ').trim();
359
- return compact.length > 200 ? `${compact.slice(0, 197)}...` : compact;
361
+ return compact.length > 200 ? `${sliceUtf16(compact, 197)}...` : compact;
360
362
  };
361
363
 
362
364
  const textOf = (
@@ -398,13 +400,13 @@ const typeIdentifierOf = (name: string): string => {
398
400
 
399
401
  /**
400
402
  * The identifier each of a catalog's type names is declared under. A name that is an identifier
401
- * keeps it; the others are mapped in code-point order, so a catalog always declares the same
403
+ * keeps it; the others are mapped in UTF-16 order, so a catalog always declares the same
402
404
  * identifiers.
403
405
  */
404
406
  const typeIdentifiersOf = (typeNames: Iterable<string>): Map<string, string> => {
405
407
  const typeIdentifiers = new Map<string, string>();
406
408
  const taken = new Set<string>();
407
- const names = [...new Set(typeNames)].sort(compareCodePoints);
409
+ const names = [...new Set(typeNames)].sort(compareUtf16);
408
410
  for (const name of names) {
409
411
  if (typeIdentifierOf(name) !== name) continue;
410
412
  typeIdentifiers.set(name, name);
@@ -574,7 +576,7 @@ class CatalogSearchIndex {
574
576
  return { entry, score: (named ? score * nameCoverageFactor : score) + bonus, named };
575
577
  })
576
578
  .filter(({ entry }) => accept(entry))
577
- .sort((left, right) => right.score - left.score || compareCodePoints(left.entry.path, right.entry.path));
579
+ .sort((left, right) => right.score - left.score || compareUtf16(left.entry.path, right.entry.path));
578
580
  }
579
581
  }
580
582
 
@@ -643,7 +645,7 @@ class FlexToolCatalogCore {
643
645
  for (const [index, method] of (catalog.methods as unknown[]).entries()) {
644
646
  methodInputs.push(await FlexToolCatalogCore.normalizeMethod(method, `Tool catalog method ${index}`));
645
647
  }
646
- methodInputs.sort((left, right) => compareCodePoints(left.path, right.path));
648
+ methodInputs.sort((left, right) => compareUtf16(left.path, right.path));
647
649
  const paths = new Set<string>();
648
650
  for (const method of methodInputs) {
649
651
  if (paths.has(method.path)) throw new FlexHarnessValidationError(`Tool catalog method "${method.path}" is defined twice.`);
@@ -667,7 +669,7 @@ class FlexToolCatalogCore {
667
669
  for (const container of ['$defs', 'definitions']) {
668
670
  const definitions = root[container];
669
671
  if (!isSchemaRecord(definitions)) continue;
670
- for (const key of Object.keys(definitions).sort(compareCodePoints)) {
672
+ for (const key of Object.keys(definitions).sort(compareUtf16)) {
671
673
  if (!typeNamePattern.test(key) || reservedWords.has(key) || key.length > limits.maxIdentifierCharacters) continue;
672
674
  const definition = definitions[key] as TJsonSchemaNode;
673
675
  const canonical = stableStringify(definition);
@@ -704,7 +706,7 @@ class FlexToolCatalogCore {
704
706
  : {}),
705
707
  });
706
708
  }
707
- const types = new Map([...registry.entries()].sort(([left], [right]) => compareCodePoints(left, right)));
709
+ const types = new Map([...registry.entries()].sort(([left], [right]) => compareUtf16(left, right)));
708
710
  return new FlexToolCatalogCore(
709
711
  mode,
710
712
  methods,
@@ -921,7 +923,7 @@ class FlexToolCatalogCore {
921
923
  const parts = signatureParts(entry.declaration, entry.name);
922
924
  const input = this.scanTypes(parts?.params ?? entry.declaration);
923
925
  const output = parts ? this.scanTypes(parts.result) : [];
924
- rendered = { text: entry.declaration.trim(), types: [...new Set([...input, ...output])].sort(compareCodePoints) };
926
+ rendered = { text: entry.declaration.trim(), types: [...new Set([...input, ...output])].sort(compareUtf16) };
925
927
  this.methodTypeSets.set(entry.path, { input, output });
926
928
  } else {
927
929
  const inputWriter = new SchemaDeclarationWriter(this.scopeContext(entry.inputScope));
@@ -945,11 +947,11 @@ class FlexToolCatalogCore {
945
947
  const signature = `function ${entry.name}(params${optional}: ${paramsType}): Promise<${resultType}>;`;
946
948
  rendered = {
947
949
  text: `${docBlock(lines.join('\n'), '')}${signature}`,
948
- types: [...new Set([...inputWriter.usedTypes, ...(outputWriter?.usedTypes ?? [])])].sort(compareCodePoints),
950
+ types: [...new Set([...inputWriter.usedTypes, ...(outputWriter?.usedTypes ?? [])])].sort(compareUtf16),
949
951
  };
950
952
  this.methodTypeSets.set(entry.path, {
951
- input: [...new Set(inputWriter.usedTypes)].sort(compareCodePoints),
952
- output: [...new Set(outputWriter?.usedTypes ?? [])].sort(compareCodePoints),
953
+ input: [...new Set(inputWriter.usedTypes)].sort(compareUtf16),
954
+ output: [...new Set(outputWriter?.usedTypes ?? [])].sort(compareUtf16),
953
955
  });
954
956
  }
955
957
  this.renderedMethods.set(entry.path, rendered);
@@ -980,7 +982,7 @@ class FlexToolCatalogCore {
980
982
  }
981
983
  level = next;
982
984
  }
983
- return [...result].sort(compareCodePoints);
985
+ return [...result].sort(compareUtf16);
984
986
  }
985
987
 
986
988
  /** `names` and every type they use, transitively, sorted. */
@@ -993,7 +995,7 @@ class FlexToolCatalogCore {
993
995
  result.add(name);
994
996
  pending.push(...this.renderType(name).types);
995
997
  }
996
- return [...result].sort(compareCodePoints);
998
+ return [...result].sort(compareUtf16);
997
999
  }
998
1000
 
999
1001
  /**
@@ -1112,7 +1114,7 @@ export class FlexToolCatalog<TScope = unknown> {
1112
1114
 
1113
1115
  /**
1114
1116
  * The identifier each type name of a catalog of exactly these types is declared under: a name that
1115
- * is an identifier keeps it, and each other takes `identifierOf()`'s, in code-point order with
1117
+ * is an identifier keeps it, and each other takes `identifierOf()`'s, in UTF-16 order with
1116
1118
  * `_2`, `_3` … appended where that is taken (`a_b` and `a-b` are declared as `a_b` and `a_b_2`).
1117
1119
  * As a name's identifier depends on the other names, a host that hands a catalog only some of its
1118
1120
  * types keeps the ones that took the lower identifiers along.
@@ -1369,16 +1371,16 @@ export class FlexToolCatalog<TScope = unknown> {
1369
1371
  );
1370
1372
  }
1371
1373
  const maxBytes = Math.min(options.maxBytes ?? limits.maxDescribeBytes, limits.maxDescribeBytes);
1372
- const entries = requestedMethods.filter((path) => this.has(path)).sort(compareCodePoints)
1374
+ const entries = requestedMethods.filter((path) => this.has(path)).sort(compareUtf16)
1373
1375
  .map((path) => this.core.methods.get(path)!);
1374
- const unknownMethods = requestedMethods.filter((path) => !this.has(path)).sort(compareCodePoints);
1376
+ const unknownMethods = requestedMethods.filter((path) => !this.has(path)).sort(compareUtf16);
1375
1377
  // A type is asked for by its identifier or by the name its schema gives it.
1376
1378
  const identifierOf = (name: string): string | undefined => {
1377
1379
  const identifier = this.core.types.has(name) ? name : this.core.typeIdentifiers.get(name);
1378
1380
  return identifier !== undefined && this.hasType(identifier) ? identifier : undefined;
1379
1381
  };
1380
- const knownTypes = [...new Set(requestedTypes.flatMap((name) => identifierOf(name) ?? []))].sort(compareCodePoints);
1381
- const unknownTypes = requestedTypes.filter((name) => identifierOf(name) === undefined).sort(compareCodePoints);
1382
+ const knownTypes = [...new Set(requestedTypes.flatMap((name) => identifierOf(name) ?? []))].sort(compareUtf16);
1383
+ const unknownTypes = requestedTypes.filter((name) => identifierOf(name) === undefined).sort(compareUtf16);
1382
1384
  const notes = [
1383
1385
  ...unknownMethods.map((path) => {
1384
1386
  const suggestions = closeMatches(path, this.listedMethods());
@@ -1445,6 +1447,10 @@ export class FlexToolCatalog<TScope = unknown> {
1445
1447
  else issues.push(...this.foreignIssues(result.error, value));
1446
1448
  }
1447
1449
  if (issues.length > 0) {
1450
+ // A fixed order, whatever order the validator found them in: by path, then expected, in
1451
+ // UTF-16 order. The structural issues are distinct in that pair, so the order is total.
1452
+ issues.sort((left, right) =>
1453
+ compareUtf16(left.path, right.path) || compareUtf16(left.expected, right.expected));
1448
1454
  const listed = issues.slice(0, limits.maxParamIssues);
1449
1455
  return {
1450
1456
  success: false,
@@ -1470,7 +1476,7 @@ export class FlexToolCatalog<TScope = unknown> {
1470
1476
  && typeof decision.deny === 'string'
1471
1477
  && decision.deny.trim()
1472
1478
  ) {
1473
- return { deny: decision.deny.slice(0, 2000) };
1479
+ return { deny: sliceUtf16(decision.deny, 2000) };
1474
1480
  }
1475
1481
  throw new FlexHarnessValidationError(`Tool catalog method "${path}" onCall returned an invalid decision.`);
1476
1482
  },
@@ -1534,7 +1540,7 @@ export class FlexToolCatalog<TScope = unknown> {
1534
1540
  }
1535
1541
  }
1536
1542
  for (const entry of tree.values()) {
1537
- entry.children = new Map([...entry.children.entries()].sort(([left], [right]) => compareCodePoints(left, right)));
1543
+ entry.children = new Map([...entry.children.entries()].sort(([left], [right]) => compareUtf16(left, right)));
1538
1544
  }
1539
1545
  this.namespaceTree = tree;
1540
1546
  return tree;
@@ -1579,7 +1585,7 @@ export class FlexToolCatalog<TScope = unknown> {
1579
1585
  return [...new Set([
1580
1586
  ...this.core.typeClosure(inputs, alreadyDeclared),
1581
1587
  ...this.core.typeLevels(outputs, this.outputTypeDepth, alreadyDeclared),
1582
- ])].sort(compareCodePoints);
1588
+ ])].sort(compareUtf16);
1583
1589
  };
1584
1590
  let types = typesFor([]);
1585
1591
  const assemble = (methods: IMethodEntry[], typeNames: string[], skipped: string[]): string => {
@@ -1588,8 +1594,8 @@ export class FlexToolCatalog<TScope = unknown> {
1588
1594
  ...methods.flatMap((entry) => this.core.renderMethod(entry).types),
1589
1595
  ...typeNames.flatMap((name) => this.core.renderType(name).types),
1590
1596
  ]);
1591
- const earlier = [...named].filter((name) => declared.has(name) && !shown.has(name)).sort(compareCodePoints);
1592
- const undeclared = [...named].filter((name) => !declared.has(name) && !shown.has(name)).sort(compareCodePoints);
1597
+ const earlier = [...named].filter((name) => declared.has(name) && !shown.has(name)).sort(compareUtf16);
1598
+ const undeclared = [...named].filter((name) => !declared.has(name) && !shown.has(name)).sort(compareUtf16);
1593
1599
  const blocks: string[] = [];
1594
1600
  if (typeNames.length) blocks.push(`${declaredTypesHeader}${typeNames.join(', ')}`);
1595
1601
  for (const name of typeNames) blocks.push(this.core.renderType(name).text);
@@ -1919,7 +1925,7 @@ const codeOf = (text: string): string => {
1919
1925
 
1920
1926
  /** The identifiers a declaration's code names, sorted; its comments and string literals name none. */
1921
1927
  const identifiersIn = (text: string): string[] =>
1922
- [...new Set(codeOf(text).match(identifierScanPattern))].sort(compareCodePoints);
1928
+ [...new Set(codeOf(text).match(identifierScanPattern))].sort(compareUtf16);
1923
1929
 
1924
1930
  /** The index of the bracket that closes the one at `open`, or -1. */
1925
1931
  const closingBracket = (code: string, open: number): number => {
@@ -2,6 +2,7 @@ import type * as plugins from './plugins.js';
2
2
  import type { FlexHarnessAbortError } from './errors.js';
3
3
  import type { FlexToolCatalog } from './classes.toolcatalog.js';
4
4
  import type { FlexCodeSandbox } from './classes.codesandbox.js';
5
+ import type { FlexTimeSlicer } from './classes.timeslicer.js';
5
6
  import type { IFlexProjectionLists } from './utils.projectionchange.js';
6
7
  import type {
7
8
  IFlexAgentContextInvocation,
@@ -20,6 +21,7 @@ import type {
20
21
  IFlexPendingReversionRelease,
21
22
  IFlexResolvedModel,
22
23
  IFlexResolvedSessionConfiguration,
24
+ IFlexScopeLoadMetrics,
23
25
  IFlexSession,
24
26
  IFlexSessionMetricsState,
25
27
  IFlexSessionTombstone,
@@ -53,6 +55,26 @@ export type TRunPhase =
53
55
  | 'finalizing'
54
56
  | 'promoting';
55
57
 
58
+ /** One scope load: the slicer that cuts its work, and what it took so far. */
59
+ export interface IScopeLoadPass {
60
+ readonly slicer: FlexTimeSlicer;
61
+ readonly metrics: Omit<IFlexScopeLoadMetrics, 'totalMs' | 'outcome'>;
62
+ }
63
+
64
+ /**
65
+ * A session's projection content as a repair found it: the message and reversion segment lists
66
+ * with their frozen entries, the other fields encoded.
67
+ */
68
+ export interface IProjectionContent {
69
+ readonly messages: readonly IFlexMessage[];
70
+ readonly reversionSegments: readonly IFlexReversionSegment[];
71
+ readonly stagedTerminals: string;
72
+ readonly revertCursor: number;
73
+ readonly excludedRunIds: string;
74
+ readonly pendingReversion: string | undefined;
75
+ readonly pendingReversionReleases: string;
76
+ }
77
+
56
78
  /** The invocation a compaction runs under; a manual compaction also carries its requested model hint. */
57
79
  export interface ICompactorInvocation<TScope> extends IFlexAgentContextInvocation<TScope> {
58
80
  readonly modelHint?: string;
@@ -263,9 +285,18 @@ export interface IActiveRun {
263
285
  /**
264
286
  * The text and reasoning parts the model step in progress streamed. When the step commits, its
265
287
  * text parts complete and text that follows starts a new part; when its model call is retried,
266
- * they are removed.
288
+ * those the call streamed after its last tool call that ran are removed and the others complete.
267
289
  */
268
290
  stepPartIds: Set<string>;
291
+ /**
292
+ * The step's streamed tool calls, each with the step's parts that came before it: a retry that
293
+ * keeps the call's output up to a call keeps exactly those. Text streamed after a call starts a
294
+ * new part (`textPartClosed`).
295
+ */
296
+ stepStreamedCalls: Map<string, ReadonlySet<string>>;
297
+ /** The step's streamed calls the SDK could not parse or repair, with its error: they never start. */
298
+ stepInvalidCalls: Map<string, string>;
299
+ textPartClosed: boolean;
269
300
  toolPartIds: Map<string, string>;
270
301
  trustedToolExecutionErrors: Map<string, Error>;
271
302
  /**
package/ts/interfaces.ts CHANGED
@@ -218,7 +218,10 @@ export interface IFlexToolMessagePart {
218
218
  /** For a failed call whose permission was rejected: the rejected request's `permissionId`. */
219
219
  rejectedPermissionId?: string;
220
220
  model?: IFlexModelIdentity;
221
- /** ISO time the tool call began. Absent on parts recorded before part times existed. */
221
+ /**
222
+ * ISO time the tool call began. Absent while a call the model streamed has not started yet, and
223
+ * on parts recorded before part times existed.
224
+ */
222
225
  startedAt?: string;
223
226
  /** ISO time the tool call reached its terminal status; absent while it runs. */
224
227
  completedAt?: string;
@@ -1507,6 +1510,12 @@ export interface IFlexSessionGeneration {
1507
1510
  sessionGenerationSequence: number;
1508
1511
  }
1509
1512
 
1513
+ /** A live session of a scope as `listSessionIdentities()` names it. */
1514
+ export interface IFlexSessionIdentity extends IFlexSessionGeneration {
1515
+ sessionId: string;
1516
+ parentSessionId?: string;
1517
+ }
1518
+
1510
1519
  export const FLEX_SESSION_CONFIGURATION_REF_MAX_BYTES = 1024;
1511
1520
 
1512
1521
  export interface IFlexSessionConfigurationResolverContext<TScope> extends IFlexSessionGeneration {
@@ -2213,8 +2222,42 @@ export interface IFlexHarnessOptions<TScope> {
2213
2222
  maxSubagentCallsPerRun?: number;
2214
2223
  /** Bounds and the clock of the cache keeper; see `keepCacheWarm()`. */
2215
2224
  cacheWarm?: IFlexCacheWarmOptions;
2225
+ /**
2226
+ * Called once each scope load ends, with what it took. An exception it throws, or a promise it
2227
+ * rejects, is ignored.
2228
+ */
2229
+ scopeLoadObserver?: TFlexScopeLoadObserver;
2230
+ }
2231
+
2232
+ /** How a scope load ended: loaded, failed, or stopped by disposal or the scope's retirement. */
2233
+ export type TFlexScopeLoadOutcome = 'loaded' | 'failed' | 'aborted';
2234
+
2235
+ /**
2236
+ * What one scope load took. A load reads the scope's sessions, their projections, permissions,
2237
+ * event logs and job stores, and repairs what a stopped process left behind; the first request of
2238
+ * a scope waits for it. Times are wall-clock milliseconds, which include the turns the load gives
2239
+ * the event loop.
2240
+ */
2241
+ export interface IFlexScopeLoadMetrics {
2242
+ scopeId: string;
2243
+ storageKey: string;
2244
+ /** The live sessions the load read, up to where it ended. */
2245
+ sessions: number;
2246
+ /**
2247
+ * The time spent waiting for the stores: the scope snapshot, and each session's projection,
2248
+ * permissions, agent event store and job store. The event log itself is read in `agentSessionMs`.
2249
+ */
2250
+ storeReadMs: number;
2251
+ /** The time spent creating the sessions' agent sessions: each reads and checks its event log. */
2252
+ agentSessionMs: number;
2253
+ /** The time spent repairing the sessions, their saves included. */
2254
+ repairMs: number;
2255
+ totalMs: number;
2256
+ outcome: TFlexScopeLoadOutcome;
2216
2257
  }
2217
2258
 
2259
+ export type TFlexScopeLoadObserver = (metricsArg: IFlexScopeLoadMetrics) => void;
2260
+
2218
2261
  export interface IFlexUncertainToolExecution {
2219
2262
  intentId: string;
2220
2263
  generationId: string;
@@ -2314,8 +2357,10 @@ export interface IFlexPartDeltaEvent extends IFlexPartEventBase {
2314
2357
  }
2315
2358
 
2316
2359
  /**
2317
- * A part left its message. `partIndex` is its position before it left; the parts after it
2318
- * move up by one. Failed-inference observations are retained, not removed for a retry.
2360
+ * A streamed part left its message: the model call that streamed it failed and is retried, the
2361
+ * part came after the call's last tool call that ran or is a tool call the model streamed that
2362
+ * never started, and the retry streams its own parts. `partIndex` is the part's position before
2363
+ * it left; the parts after it move up by one.
2319
2364
  */
2320
2365
  export interface IFlexPartRemovedEvent extends IFlexPartEventBase {
2321
2366
  readonly type: 'part.removed';
package/ts/plugins.ts CHANGED
@@ -108,6 +108,7 @@ import {
108
108
  createAgentEvent,
109
109
  filterModelVisibleAgentEvents,
110
110
  getAgentGenerationTransactions,
111
+ getGenerationsInModelContext,
111
112
  isGenerationInModelContext,
112
113
  modelMessagesToAgentEvents,
113
114
  resolveAgentContextCompactionPoint,
@@ -134,6 +135,7 @@ export {
134
135
  createAgentEvent,
135
136
  filterModelVisibleAgentEvents,
136
137
  getAgentGenerationTransactions,
138
+ getGenerationsInModelContext,
137
139
  isGenerationInModelContext,
138
140
  modelMessagesToAgentEvents,
139
141
  resolveAgentContextCompactionPoint,
package/ts/readme.md CHANGED
@@ -162,6 +162,12 @@ ChatGPT authentication, pass
162
162
  `connection: createOpenAiChatGptModelConnection(credentials)` from `/auth` to the
163
163
  OpenAI model options. API-key inference needs no authentication setup.
164
164
 
165
+ The Anthropic, OpenAI and Ollama adapters end a streamed answer at its stream's terminal event
166
+ (Anthropic's `message_stop`, the Responses API's `response.completed`, Chat Completions'
167
+ `data: [DONE]`, Ollama's `done` object), never at the end of the connection: nothing after it is
168
+ read, and a stream that ends before it fails its model call with `ModelStreamIncompleteError`
169
+ from `flexharness-models`, which a run does not retry (AGL-1130).
170
+
165
171
  ## Migration
166
172
 
167
173
  Replace the withdrawn 6.x component imports with the subpaths above. Provider
@@ -633,6 +639,7 @@ The main session methods are:
633
639
 
634
640
  ```typescript
635
641
  await harness.listSessions(scopeId);
642
+ await harness.listSessionIdentities(scopeId);
636
643
  await harness.createSession(scopeId, { sessionId, sessionGenerationId, title });
637
644
  await harness.getSession(scopeId, sessionId);
638
645
  await harness.getMessages(scopeId, sessionId);
@@ -702,6 +709,10 @@ await harness.dispose();
702
709
 
703
710
  `getSession()` returns the session as saved after every queued write that may change it; it does not wait for queued writes of the scope's other sessions, so a slow save of one session never holds a read of another. `listSessions()` waits for every queued write.
704
711
 
712
+ `listSessionIdentities(scopeId)` lists a scope's live sessions as `IFlexSessionIdentity` (`sessionId`, `sessionGenerationId`, `sessionGenerationSequence`, `parentSessionId` when set), sorted by session id. The first request of a scope loads it: every session's projection, permissions, event log and job store, and the repair of what a stopped process left behind. `listSessions()` waits for that load; `listSessionIdentities()` does not. Until the load has settled it reads the stored scope snapshot alone, normalized as the load normalizes it (a session stored before session generations existed gets the generation the load derives for it, a deleted session is left out), and never reads a projection, an event log or a job store; nothing can change a scope before its load settles. Once the load has settled it answers from the loaded sessions. It gives the same answer before and after the load.
713
+
714
+ The load gives the event loop a turn about every 25 ms of work, so timers, I/O and a caller's cancellation keep running beside it, and its repair takes time linear in a session's size. A request that stops waiting for the load leaves it running, and the next request of the scope joins it; `dispose()` and `retireScope()` stop it at its next turn, and the requests waiting for it fail with `FlexHarnessAbortError`. The `scopeLoadObserver` option is called once each load ends, with `IFlexScopeLoadMetrics`: `scopeId`, `storageKey`, the live `sessions` it read, `storeReadMs` (waiting for the scope snapshot and each session's projection, permissions, agent event store and job store), `agentSessionMs` (creating the sessions' agent sessions, each of which reads and checks its event log), `repairMs`, `totalMs`, all wall-clock milliseconds, and `outcome` (`'loaded'`, `'failed'`, or `'aborted'` by disposal or retirement). An exception the observer throws, or a promise it rejects, is ignored.
715
+
705
716
  Only one run may be active in a session. Additional prompts enter a bounded FIFO owned by FlexHarness, while different sessions can run concurrently. `enqueuePrompt()` resolves with `{ queueId, generation, completion }` after the immutable prompt and options have been accepted into that runtime queue and `prompt.queued` has been emitted. `startPrompt()` keeps its durable-admission behavior: it waits for its FIFO turn and resolves with `{ queueId, generation, runId, completion }` only after the canonical generation claim, run ID, and initial public audit messages have been durably reserved and the corresponding start events have been emitted. `prompt()` preserves the simpler behavior by awaiting completion internally.
706
717
 
707
718
  Every admission names the session generation that admitted it: `generation` (`IFlexPromptAdmissionGeneration`) holds `sessionGenerationId`, `sessionGenerationSequence`, `depth` (0 for a root session, also a legacy root that stored none) and `configurationRef` when the session has one, as `getSession()` reports them. None of them changes while the generation lives, and the prompt only ever runs on that generation. The harness reads it from the session in memory, so a caller that needs it for the run it started does not call `getSession()`: that read waits for the session's queued writes, which queue behind every other session's write queued before them in the scope's one write FIFO.
@@ -1264,7 +1275,7 @@ const unsubscribe = harness.subscribe((event) => {
1264
1275
  unsubscribe();
1265
1276
  ```
1266
1277
 
1267
- Events are discriminated, deeply immutable values with one global sequence within each `FlexHarness` instance. Every `IFlexEventBase` carries the exact source `sessionGenerationId` and `sessionGenerationSequence`; `session.deleted` retains the deleted generation after live metadata is removed. Listener exceptions are isolated from runs and other listeners. Every accepted queue entry emits `prompt.queued` and exactly one `prompt.finished`. Every accepted steer emits `prompt.steer.accepted` (a steer admitted with its prompt when the run starts, and not at all when the prompt is cancelled or fails before), and `prompt.steer.applied`, after the `message.*` events of its user message, once the run took it in; `run.finished` lists it in `unappliedSteerIds` unless it is in the model context of later turns. Durable promotion additionally emits `prompt.started`, and actual model preparation emits `prompt.running`; cancellation or failure can omit either intermediate event. Existing durable run/message terminal events precede `prompt.finished`. Every callback-backed streamed text part that stays in its message emits exactly one `part.completed` event before the corresponding `run.finished` event: once the model step that streamed it is committed, so its text is final and saved, or with the run's terminal projection when that step did not commit. Text a later model step streams starts a new part. When a model call fails and is retried, the text and reasoning parts it streamed are not in the session: `part.removed` takes each of them out of its message, last part first, and the retry streams its own parts. Its `partIndex` is the part's position before it left; the parts after it move up by one. A removed part has no further events, and `part.removed` does not count against `callbackLimits`. The tool parts of calls the failed model call executed stay. Every `part.started`, `part.delta`, `part.updated`, `part.completed`, and `part.removed` event carries zero-based `messageIndex` and `partIndex` coordinates from the session's authoritative message and part sequences.
1278
+ Events are discriminated, deeply immutable values with one global sequence within each `FlexHarness` instance. Every `IFlexEventBase` carries the exact source `sessionGenerationId` and `sessionGenerationSequence`; `session.deleted` retains the deleted generation after live metadata is removed. Listener exceptions are isolated from runs and other listeners. Every accepted queue entry emits `prompt.queued` and exactly one `prompt.finished`. Every accepted steer emits `prompt.steer.accepted` (a steer admitted with its prompt when the run starts, and not at all when the prompt is cancelled or fails before), and `prompt.steer.applied`, after the `message.*` events of its user message, once the run took it in; `run.finished` lists it in `unappliedSteerIds` unless it is in the model context of later turns. Durable promotion additionally emits `prompt.started`, and actual model preparation emits `prompt.running`; cancellation or failure can omit either intermediate event. Existing durable run/message terminal events precede `prompt.finished`. Every callback-backed streamed text part that stays in its message emits exactly one `part.completed` event before the corresponding `run.finished` event: once the model step that streamed it is committed, so its text is final and saved, or with the run's terminal projection when that step did not commit. Text a later model step streams starts a new part, and so does text a response streams after a tool call. When a model call fails and is retried, the text and reasoning parts it streamed after its last tool call that ran (all of them, when none ran) are not in the session: `part.removed` takes each of them out of its message, last part first, and the retry streams its own parts. The parts before that call stay, and their text completes. Its `partIndex` is the part's position before it left; the parts after it move up by one. A removed part has no further events, and `part.removed` does not count against `callbackLimits`. The tool parts of calls the failed model call executed stay. Every `part.started`, `part.delta`, `part.updated`, `part.completed`, and `part.removed` event carries zero-based `messageIndex` and `partIndex` coordinates from the session's authoritative message and part sequences.
1268
1279
 
1269
1280
  `getSessionView(scopeId, sessionId)` reads a session's metadata, visible messages and pending permission requests in one step, together with the instance's event `sequence` they include. The messages include what a running turn has streamed so far, so a consumer that applies every event of the instance with a greater `sequence` follows the session exactly from the view on; events up to `sequence` are already in it. The read waits while a queued write or a change that emits events for the session is in progress; a session that keeps changing through 64 consecutive waits is refused with `FlexHarnessSessionBusyError`, and the read can be repeated. Session metadata is current: status changes such as `waiting_permission` emit no event. A permission request its run leaves unanswered leaves `pendingPermissions` without an event of its own; the run's `run.finished` follows.
1270
1281
 
@@ -37,6 +37,9 @@ export const resourceToolStemLength = 16;
37
37
  export const scopeRetirementMessage = 'The scope is being retired.';
38
38
  export const slashCommandSessionUnavailableReason = 'Session must be idle with no queued prompts.';
39
39
 
40
+ /** The error of a tool part whose call the model streamed but that never started. */
41
+ export const toolCallNotStartedMessage = 'The tool call did not start.';
42
+
40
43
  export const externalErrorFallback: IFlexErrorInfo = Object.freeze({
41
44
  name: 'FlexHarnessExternalError',
42
45
  message: 'The model operation failed.',