@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.
- 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.d.ts +58 -2
- package/dist_ts/classes.flexharness.core.js +392 -177
- package/dist_ts/classes.flexharness.d.ts +6 -1
- package/dist_ts/classes.flexharness.js +8 -1
- package/dist_ts/classes.flexharness.runs.js +10 -3
- package/dist_ts/classes.flexharness.sessions.d.ts +8 -1
- package/dist_ts/classes.flexharness.sessions.js +27 -1
- package/dist_ts/classes.timeslicer.d.ts +21 -0
- package/dist_ts/classes.timeslicer.js +31 -0
- package/dist_ts/classes.toolcatalog.d.ts +1 -1
- package/dist_ts/classes.toolcatalog.js +34 -29
- package/dist_ts/interfaces.d.ts +44 -3
- package/dist_ts/interfaces.flexharness.d.ts +30 -2
- package/dist_ts/interfaces.js +1 -1
- package/dist_ts/plugins.d.ts +2 -2
- package/dist_ts/plugins.js +3 -3
- package/dist_ts/utils.flexharness.d.ts +2 -0
- package/dist_ts/utils.flexharness.js +3 -1
- package/dist_ts/utils.json.d.ts +6 -0
- package/dist_ts/utils.json.js +92 -35
- package/dist_ts/utils.scopesnapshot.d.ts +14 -0
- package/dist_ts/utils.scopesnapshot.js +58 -0
- 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 +12 -1
- package/ts/00_commitinfo_data.ts +1 -1
- package/ts/classes.flexharness.callbacks.ts +110 -16
- package/ts/classes.flexharness.core.ts +452 -207
- package/ts/classes.flexharness.runs.ts +9 -1
- package/ts/classes.flexharness.sessions.ts +30 -0
- package/ts/classes.flexharness.ts +9 -0
- package/ts/classes.timeslicer.ts +32 -0
- package/ts/classes.toolcatalog.ts +34 -28
- package/ts/interfaces.flexharness.ts +32 -1
- package/ts/interfaces.ts +48 -3
- package/ts/plugins.ts +2 -0
- package/ts/readme.md +12 -1
- package/ts/utils.flexharness.ts +3 -0
- package/ts/utils.json.ts +88 -38
- package/ts/utils.scopesnapshot.ts +75 -0
- 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
|
@@ -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
|
-
:
|
|
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
|
-
|
|
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 => {
|
|
@@ -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
|
-
*
|
|
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
|
-
/**
|
|
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
|
|
2318
|
-
*
|
|
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
|
|
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.',
|