@modelprofile.com/flexharness 17.0.1 → 18.0.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 (34) 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.js +2 -1
  5. package/dist_ts/classes.flexharness.runs.js +10 -3
  6. package/dist_ts/classes.toolcatalog.d.ts +1 -1
  7. package/dist_ts/classes.toolcatalog.js +34 -29
  8. package/dist_ts/interfaces.d.ts +8 -3
  9. package/dist_ts/interfaces.flexharness.d.ts +10 -1
  10. package/dist_ts/interfaces.js +1 -1
  11. package/dist_ts/utils.flexharness.d.ts +2 -0
  12. package/dist_ts/utils.flexharness.js +3 -1
  13. package/dist_ts/utils.json.js +18 -16
  14. package/dist_ts/utils.text.d.ts +6 -0
  15. package/dist_ts/utils.text.js +10 -0
  16. package/dist_ts_chat_harness/functions.mapping.js +11 -4
  17. package/dist_ts_tools_node/classes.workspacereversion.d.ts +3 -2
  18. package/dist_ts_tools_node/classes.workspacereversion.js +17 -3
  19. package/package.json +3 -3
  20. package/readme.md +7 -1
  21. package/ts/00_commitinfo_data.ts +1 -1
  22. package/ts/classes.flexharness.callbacks.ts +110 -16
  23. package/ts/classes.flexharness.core.ts +1 -0
  24. package/ts/classes.flexharness.runs.ts +9 -1
  25. package/ts/classes.toolcatalog.ts +34 -28
  26. package/ts/interfaces.flexharness.ts +10 -1
  27. package/ts/interfaces.ts +8 -3
  28. package/ts/readme.md +7 -1
  29. package/ts/utils.flexharness.ts +3 -0
  30. package/ts/utils.json.ts +18 -20
  31. package/ts/utils.text.ts +9 -0
  32. package/ts_chat_harness/functions.mapping.ts +10 -3
  33. package/ts_tools_node/classes.workspacereversion.ts +19 -4
  34. package/ts_tools_node/readme.md +1 -1
@@ -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 => {
@@ -263,9 +263,18 @@ export interface IActiveRun {
263
263
  /**
264
264
  * The text and reasoning parts the model step in progress streamed. When the step commits, its
265
265
  * text parts complete and text that follows starts a new part; when its model call is retried,
266
- * they are removed.
266
+ * those the call streamed after its last tool call that ran are removed and the others complete.
267
267
  */
268
268
  stepPartIds: Set<string>;
269
+ /**
270
+ * The step's streamed tool calls, each with the step's parts that came before it: a retry that
271
+ * keeps the call's output up to a call keeps exactly those. Text streamed after a call starts a
272
+ * new part (`textPartClosed`).
273
+ */
274
+ stepStreamedCalls: Map<string, ReadonlySet<string>>;
275
+ /** The step's streamed calls the SDK could not parse or repair, with its error: they never start. */
276
+ stepInvalidCalls: Map<string, string>;
277
+ textPartClosed: boolean;
269
278
  toolPartIds: Map<string, string>;
270
279
  trustedToolExecutionErrors: Map<string, Error>;
271
280
  /**
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;
@@ -2314,8 +2317,10 @@ export interface IFlexPartDeltaEvent extends IFlexPartEventBase {
2314
2317
  }
2315
2318
 
2316
2319
  /**
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.
2320
+ * A streamed part left its message: the model call that streamed it failed and is retried, the
2321
+ * part came after the call's last tool call that ran or is a tool call the model streamed that
2322
+ * never started, and the retry streams its own parts. `partIndex` is the part's position before
2323
+ * it left; the parts after it move up by one.
2319
2324
  */
2320
2325
  export interface IFlexPartRemovedEvent extends IFlexPartEventBase {
2321
2326
  readonly type: 'part.removed';
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
@@ -1264,7 +1270,7 @@ const unsubscribe = harness.subscribe((event) => {
1264
1270
  unsubscribe();
1265
1271
  ```
1266
1272
 
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.
1273
+ 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
1274
 
1269
1275
  `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
1276
 
@@ -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.',
package/ts/utils.json.ts CHANGED
@@ -22,6 +22,7 @@ import type {
22
22
  TFlexAgentModelMessage,
23
23
  TJsonValue,
24
24
  } from './interfaces.js';
25
+ import { sliceUtf16 } from './utils.text.js';
25
26
  import { isValidSessionConfigurationRef } from './utils.validation.js';
26
27
 
27
28
  const DEFAULT_MAX_DEPTH = 12;
@@ -79,7 +80,7 @@ export function normalizeJsonValue(value: unknown, limits: IFlexJsonLimits = {})
79
80
  bytes: Buffer.byteLength(JSON.stringify(entry)),
80
81
  });
81
82
  const shortString = (entry: string, maximumCharacters = 160): string =>
82
- entry.length > maximumCharacters ? `${entry.slice(0, maximumCharacters)}...` : entry;
83
+ entry.length > maximumCharacters ? `${sliceUtf16(entry, maximumCharacters)}...` : entry;
83
84
  const description = (
84
85
  type: string,
85
86
  values: Record<string, TJsonValue>,
@@ -92,7 +93,7 @@ export function normalizeJsonValue(value: unknown, limits: IFlexJsonLimits = {})
92
93
  return measure('[truncated]');
93
94
  };
94
95
  const nextPath = (path: string, suffix: string): string =>
95
- `${path.slice(0, 80)}${suffix.slice(0, 48)}`;
96
+ `${sliceUtf16(path, 80)}${sliceUtf16(suffix, 48)}`;
96
97
 
97
98
  const visit = (
98
99
  current: unknown,
@@ -252,32 +253,29 @@ export function normalizeJsonValue(value: unknown, limits: IFlexJsonLimits = {})
252
253
  while (Object.prototype.hasOwnProperty.call(current, truncationKey)) {
253
254
  truncationKey += '_';
254
255
  }
256
+ // The truncation property after `count` properties: a separator unless it is the first, its key and its marker.
257
+ const truncationPropertyBytes = (count: number): number =>
258
+ (count > 0 ? 1 : 0) +
259
+ Buffer.byteLength(JSON.stringify(truncationKey)) +
260
+ 1 +
261
+ description('truncated', { reason: 'bytes', visitedProperties: count }, allowance).bytes;
255
262
  for (const key in current) {
256
263
  if (!Object.prototype.hasOwnProperty.call(current, key)) continue;
257
264
  const separatorBytes = visitedProperties > 0 ? 1 : 0;
258
- const truncation = description(
259
- 'truncated',
260
- { reason: 'bytes', visitedProperties },
261
- allowance,
262
- );
263
- const truncationPropertyBytes =
264
- (visitedProperties > 0 ? 1 : 0) +
265
- Buffer.byteLength(JSON.stringify(truncationKey)) +
266
- 1 +
267
- truncation.bytes;
268
265
  const rawKeyBytes = Buffer.byteLength(key);
269
- if (rawKeyBytes + 2 >= allowance - encodedBytes - truncationPropertyBytes) {
266
+ if (rawKeyBytes + 2 >= allowance - encodedBytes - truncationPropertyBytes(visitedProperties)) {
270
267
  truncated = true;
271
268
  break;
272
269
  }
273
270
  const encodedKeyBytes = Buffer.byteLength(JSON.stringify(key));
271
+ // Room for the truncation property that would follow this one.
274
272
  const childAllowance =
275
273
  allowance -
276
274
  encodedBytes -
277
275
  separatorBytes -
278
276
  encodedKeyBytes -
279
277
  1 -
280
- truncationPropertyBytes;
278
+ truncationPropertyBytes(visitedProperties + 1);
281
279
  if (childAllowance < 48) {
282
280
  truncated = true;
283
281
  break;
@@ -301,18 +299,18 @@ export function normalizeJsonValue(value: unknown, limits: IFlexJsonLimits = {})
301
299
  visitedProperties++;
302
300
  }
303
301
  if (truncated) {
302
+ // Before the first property there is no room reserved: an object too small for its
303
+ // truncation property is a marker itself.
304
+ if (encodedBytes + truncationPropertyBytes(visitedProperties) > allowance) {
305
+ return description('truncated', { reason: 'bytes' }, allowance);
306
+ }
304
307
  const truncation = description(
305
308
  'truncated',
306
309
  { reason: 'bytes', visitedProperties },
307
310
  allowance,
308
311
  );
309
- const separatorBytes = visitedProperties > 0 ? 1 : 0;
310
312
  normalized[truncationKey] = truncation.value;
311
- encodedBytes +=
312
- separatorBytes +
313
- Buffer.byteLength(JSON.stringify(truncationKey)) +
314
- 1 +
315
- truncation.bytes;
313
+ encodedBytes += truncationPropertyBytes(visitedProperties);
316
314
  }
317
315
  return { value: normalized, bytes: encodedBytes };
318
316
  };
@@ -0,0 +1,9 @@
1
+ /**
2
+ * The first `end` UTF-16 code units of `text`, one fewer where the last of them is the first half of
3
+ * a surrogate pair: a cut never keeps half of a character, which JSON would write as an escape such
4
+ * as `\ud83d`.
5
+ */
6
+ export function sliceUtf16(text: string, end: number): string {
7
+ const last = text.charCodeAt(end - 1);
8
+ return text.slice(0, end > 0 && end < text.length && last >= 0xd800 && last <= 0xdbff ? end - 1 : end);
9
+ }
@@ -51,18 +51,25 @@ export function flexToolPartToHarness(
51
51
  part: IFlexToolMessagePart,
52
52
  timing?: IFlexPartTiming,
53
53
  ): plugins.IHarnessToolCall {
54
+ // A call the model streamed waits until it starts: it is pending, and its clock starts with it.
55
+ // One that ended without starting has `completedAt` but no `startedAt`, and no clock at all.
56
+ // Parts recorded before part times existed have neither, so the events' times stand in.
57
+ const pending = part.status === 'running' && part.startedAt === undefined;
58
+ const neverStarted = part.startedAt === undefined && (pending || part.completedAt !== undefined);
59
+ const startedAt = neverStarted ? undefined : epoch(part.startedAt) ?? timing?.startedAt;
60
+ const finishedAt = neverStarted ? undefined : epoch(part.completedAt) ?? timing?.endedAt;
54
61
  return {
55
62
  id: part.toolCallId,
56
63
  name: part.toolName,
57
- status: toolStatuses[part.status],
64
+ status: pending ? 'pending' : toolStatuses[part.status],
58
65
  input: part.input,
59
66
  ...(part.output === undefined ? {} : { output: part.output }),
60
67
  ...(part.status === 'failed' ? { isError: true } : {}),
61
68
  ...(part.error === undefined ? {} : { errorText: part.error }),
62
69
  ...(part.childSessionId === undefined ? {} : { childSessionId: part.childSessionId }),
63
70
  ...(part.model === undefined ? {} : { model: flexModelLabel(part.model) }),
64
- ...(timing?.startedAt === undefined ? {} : { startedAt: timing.startedAt }),
65
- ...(timing?.endedAt === undefined ? {} : { finishedAt: timing.endedAt }),
71
+ ...(startedAt === undefined ? {} : { startedAt }),
72
+ ...(finishedAt === undefined ? {} : { finishedAt }),
66
73
  };
67
74
  }
68
75
 
@@ -14,8 +14,9 @@ export interface IInMemoryWorkspaceReversionOptions {
14
14
  /** The workspace a revertible turn names in the session's reversion info. */
15
15
  workspace: plugins.IFlexAffectedWorkspace;
16
16
  /**
17
- * The bytes of file images one turn may hold. A turn that changes more is recorded as
18
- * nonrevertible (`capture-too-large`) and its images are dropped. Default: 64 MiB.
17
+ * The bytes of file images one turn may hold: what each file it changed held before the turn and
18
+ * after it. A turn that changes more is recorded as nonrevertible (`capture-too-large`) and its
19
+ * images are dropped. Default: 64 MiB.
19
20
  */
20
21
  maxCaptureBytes?: number;
21
22
  }
@@ -125,10 +126,24 @@ export class InMemoryWorkspaceReversion<TScope = unknown> implements plugins.IFl
125
126
  if (capture.outcome) return capture.outcome;
126
127
  const reference: ICaptureReference = { captureId: capture.captureId };
127
128
  if (!capture.nonrevertibleReason) {
129
+ // The cap counts what the capture keeps: the before and after images of each file the turn
130
+ // changed. A file the turn left as it was is dropped uncounted, so the sum only grows and the
131
+ // outcome does not depend on the order of the files.
132
+ let keptBytes = 0;
128
133
  for (const [filePath, record] of capture.files) {
129
- record.after = await readFileImage(filePath);
130
- if (fileImagesEqual(record.before, record.after)) capture.files.delete(filePath);
134
+ const after = await readFileImage(filePath);
135
+ if (fileImagesEqual(record.before, after)) {
136
+ capture.files.delete(filePath);
137
+ continue;
138
+ }
139
+ keptBytes += fileImageBytes(record.before) + fileImageBytes(after);
140
+ if (keptBytes > this.maxCaptureBytes) {
141
+ this.markNonrevertible(capture, 'capture-too-large');
142
+ break;
143
+ }
144
+ record.after = after;
131
145
  }
146
+ if (!capture.nonrevertibleReason) capture.bytes = keptBytes;
132
147
  }
133
148
  capture.state = 'finalized';
134
149
  if (capture.nonrevertibleReason) {
@@ -36,7 +36,7 @@ const harness = new FlexHarness({
36
36
  });
37
37
  ```
38
38
 
39
- The `fileChangeObserver` of `createLocalToolExecutionContext` sees every write and delete by its canonical path (a write follows a symbolic link to its target, a delete removes the link itself) after the root checks and before the change, and every shell command before it starts; a rejection refuses the operation. The first change of a file in a turn records its bytes, mode or link target, and the directories a new file's write creates. Undo puts the before images back and removes those directories while empty; redo puts the after images back. Either direction applies only while every file still holds what the other direction left, so a later edit is never overwritten: the undo fails without a change and can be retried. A turn that ran a shell command is nonrevertible (`shell-command`), as is one whose images exceed `maxCaptureBytes` (64 MiB by default; `capture-too-large`). Only root-session runs are captured: a change of a run without a capture is refused. Captures do not survive a restart; FlexHarness then finds them `missing`.
39
+ The `fileChangeObserver` of `createLocalToolExecutionContext` sees every write and delete by its canonical path (a write follows a symbolic link to its target, a delete removes the link itself) after the root checks and before the change, and every shell command before it starts; a rejection refuses the operation. The first change of a file in a turn records its bytes, mode or link target, and the directories a new file's write creates. Undo puts the before images back and removes those directories while empty; redo puts the after images back. Either direction applies only while every file still holds what the other direction left, so a later edit is never overwritten: the undo fails without a change and can be retried. A turn that ran a shell command is nonrevertible (`shell-command`), as is one whose images exceed `maxCaptureBytes` (64 MiB by default; `capture-too-large`): what each file it changed held before the turn and after it, together. A file the turn left as it was does not count. Only root-session runs are captured: a change of a run without a capture is refused. Captures do not survive a restart; FlexHarness then finds them `missing`.
40
40
 
41
41
  ## Issue Reporting and Security
42
42