@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.
- package/dist_ts/00_commitinfo_data.js +1 -1
- package/dist_ts/classes.flexharness.callbacks.d.ts +25 -3
- package/dist_ts/classes.flexharness.callbacks.js +115 -18
- package/dist_ts/classes.flexharness.core.js +2 -1
- package/dist_ts/classes.flexharness.runs.js +10 -3
- package/dist_ts/classes.toolcatalog.d.ts +1 -1
- package/dist_ts/classes.toolcatalog.js +34 -29
- package/dist_ts/interfaces.d.ts +8 -3
- package/dist_ts/interfaces.flexharness.d.ts +10 -1
- package/dist_ts/interfaces.js +1 -1
- package/dist_ts/utils.flexharness.d.ts +2 -0
- package/dist_ts/utils.flexharness.js +3 -1
- package/dist_ts/utils.json.js +18 -16
- package/dist_ts/utils.text.d.ts +6 -0
- package/dist_ts/utils.text.js +10 -0
- package/dist_ts_chat_harness/functions.mapping.js +11 -4
- package/dist_ts_tools_node/classes.workspacereversion.d.ts +3 -2
- package/dist_ts_tools_node/classes.workspacereversion.js +17 -3
- package/package.json +3 -3
- package/readme.md +7 -1
- package/ts/00_commitinfo_data.ts +1 -1
- package/ts/classes.flexharness.callbacks.ts +110 -16
- package/ts/classes.flexharness.core.ts +1 -0
- package/ts/classes.flexharness.runs.ts +9 -1
- package/ts/classes.toolcatalog.ts +34 -28
- package/ts/interfaces.flexharness.ts +10 -1
- package/ts/interfaces.ts +8 -3
- package/ts/readme.md +7 -1
- package/ts/utils.flexharness.ts +3 -0
- package/ts/utils.json.ts +18 -20
- package/ts/utils.text.ts +9 -0
- package/ts_chat_harness/functions.mapping.ts +10 -3
- package/ts_tools_node/classes.workspacereversion.ts +19 -4
- 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
|
-
|
|
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(
|
|
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 ||
|
|
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
|
|
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
|
|
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
|
|
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(
|
|
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 ||
|
|
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) =>
|
|
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(
|
|
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]) =>
|
|
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(
|
|
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(
|
|
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(
|
|
952
|
-
output: [...new Set(outputWriter?.usedTypes ?? [])].sort(
|
|
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(
|
|
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(
|
|
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
|
|
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(
|
|
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(
|
|
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(
|
|
1381
|
-
const unknownTypes = requestedTypes.filter((name) => identifierOf(name) === undefined).sort(
|
|
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
|
|
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]) =>
|
|
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(
|
|
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(
|
|
1592
|
-
const undeclared = [...named].filter((name) => !declared.has(name) && !shown.has(name)).sort(
|
|
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(
|
|
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
|
-
*
|
|
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
|
-
/**
|
|
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
|
|
2318
|
-
*
|
|
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
|
|
package/ts/utils.flexharness.ts
CHANGED
|
@@ -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
|
|
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
|
|
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
|
};
|
package/ts/utils.text.ts
ADDED
|
@@ -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
|
-
...(
|
|
65
|
-
...(
|
|
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
|
|
18
|
-
* nonrevertible (`capture-too-large`) and its
|
|
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
|
-
|
|
130
|
-
if (fileImagesEqual(record.before,
|
|
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) {
|
package/ts_tools_node/readme.md
CHANGED
|
@@ -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
|
|