@modelprofile.com/flexharness 17.0.1 → 18.1.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (51) hide show
  1. package/dist_ts/00_commitinfo_data.js +1 -1
  2. package/dist_ts/classes.flexharness.callbacks.d.ts +25 -3
  3. package/dist_ts/classes.flexharness.callbacks.js +115 -18
  4. package/dist_ts/classes.flexharness.core.d.ts +58 -2
  5. package/dist_ts/classes.flexharness.core.js +392 -177
  6. package/dist_ts/classes.flexharness.d.ts +6 -1
  7. package/dist_ts/classes.flexharness.js +8 -1
  8. package/dist_ts/classes.flexharness.runs.js +10 -3
  9. package/dist_ts/classes.flexharness.sessions.d.ts +8 -1
  10. package/dist_ts/classes.flexharness.sessions.js +27 -1
  11. package/dist_ts/classes.timeslicer.d.ts +21 -0
  12. package/dist_ts/classes.timeslicer.js +31 -0
  13. package/dist_ts/classes.toolcatalog.d.ts +1 -1
  14. package/dist_ts/classes.toolcatalog.js +34 -29
  15. package/dist_ts/interfaces.d.ts +44 -3
  16. package/dist_ts/interfaces.flexharness.d.ts +30 -2
  17. package/dist_ts/interfaces.js +1 -1
  18. package/dist_ts/plugins.d.ts +2 -2
  19. package/dist_ts/plugins.js +3 -3
  20. package/dist_ts/utils.flexharness.d.ts +2 -0
  21. package/dist_ts/utils.flexharness.js +3 -1
  22. package/dist_ts/utils.json.d.ts +6 -0
  23. package/dist_ts/utils.json.js +92 -35
  24. package/dist_ts/utils.scopesnapshot.d.ts +14 -0
  25. package/dist_ts/utils.scopesnapshot.js +58 -0
  26. package/dist_ts/utils.text.d.ts +6 -0
  27. package/dist_ts/utils.text.js +10 -0
  28. package/dist_ts_chat_harness/functions.mapping.js +11 -4
  29. package/dist_ts_tools_node/classes.workspacereversion.d.ts +3 -2
  30. package/dist_ts_tools_node/classes.workspacereversion.js +17 -3
  31. package/package.json +3 -3
  32. package/readme.md +12 -1
  33. package/ts/00_commitinfo_data.ts +1 -1
  34. package/ts/classes.flexharness.callbacks.ts +110 -16
  35. package/ts/classes.flexharness.core.ts +452 -207
  36. package/ts/classes.flexharness.runs.ts +9 -1
  37. package/ts/classes.flexharness.sessions.ts +30 -0
  38. package/ts/classes.flexharness.ts +9 -0
  39. package/ts/classes.timeslicer.ts +32 -0
  40. package/ts/classes.toolcatalog.ts +34 -28
  41. package/ts/interfaces.flexharness.ts +32 -1
  42. package/ts/interfaces.ts +48 -3
  43. package/ts/plugins.ts +2 -0
  44. package/ts/readme.md +12 -1
  45. package/ts/utils.flexharness.ts +3 -0
  46. package/ts/utils.json.ts +88 -38
  47. package/ts/utils.scopesnapshot.ts +75 -0
  48. package/ts/utils.text.ts +9 -0
  49. package/ts_chat_harness/functions.mapping.ts +10 -3
  50. package/ts_tools_node/classes.workspacereversion.ts +19 -4
  51. package/ts_tools_node/readme.md +1 -1
package/ts/utils.json.ts CHANGED
@@ -22,6 +22,8 @@ import type {
22
22
  TFlexAgentModelMessage,
23
23
  TJsonValue,
24
24
  } from './interfaces.js';
25
+ import { sliceUtf16 } from './utils.text.js';
26
+ import type { FlexTimeSlicer } from './classes.timeslicer.js';
25
27
  import { isValidSessionConfigurationRef } from './utils.validation.js';
26
28
 
27
29
  const DEFAULT_MAX_DEPTH = 12;
@@ -79,7 +81,7 @@ export function normalizeJsonValue(value: unknown, limits: IFlexJsonLimits = {})
79
81
  bytes: Buffer.byteLength(JSON.stringify(entry)),
80
82
  });
81
83
  const shortString = (entry: string, maximumCharacters = 160): string =>
82
- entry.length > maximumCharacters ? `${entry.slice(0, maximumCharacters)}...` : entry;
84
+ entry.length > maximumCharacters ? `${sliceUtf16(entry, maximumCharacters)}...` : entry;
83
85
  const description = (
84
86
  type: string,
85
87
  values: Record<string, TJsonValue>,
@@ -92,7 +94,7 @@ export function normalizeJsonValue(value: unknown, limits: IFlexJsonLimits = {})
92
94
  return measure('[truncated]');
93
95
  };
94
96
  const nextPath = (path: string, suffix: string): string =>
95
- `${path.slice(0, 80)}${suffix.slice(0, 48)}`;
97
+ `${sliceUtf16(path, 80)}${sliceUtf16(suffix, 48)}`;
96
98
 
97
99
  const visit = (
98
100
  current: unknown,
@@ -252,32 +254,29 @@ export function normalizeJsonValue(value: unknown, limits: IFlexJsonLimits = {})
252
254
  while (Object.prototype.hasOwnProperty.call(current, truncationKey)) {
253
255
  truncationKey += '_';
254
256
  }
257
+ // The truncation property after `count` properties: a separator unless it is the first, its key and its marker.
258
+ const truncationPropertyBytes = (count: number): number =>
259
+ (count > 0 ? 1 : 0) +
260
+ Buffer.byteLength(JSON.stringify(truncationKey)) +
261
+ 1 +
262
+ description('truncated', { reason: 'bytes', visitedProperties: count }, allowance).bytes;
255
263
  for (const key in current) {
256
264
  if (!Object.prototype.hasOwnProperty.call(current, key)) continue;
257
265
  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
266
  const rawKeyBytes = Buffer.byteLength(key);
269
- if (rawKeyBytes + 2 >= allowance - encodedBytes - truncationPropertyBytes) {
267
+ if (rawKeyBytes + 2 >= allowance - encodedBytes - truncationPropertyBytes(visitedProperties)) {
270
268
  truncated = true;
271
269
  break;
272
270
  }
273
271
  const encodedKeyBytes = Buffer.byteLength(JSON.stringify(key));
272
+ // Room for the truncation property that would follow this one.
274
273
  const childAllowance =
275
274
  allowance -
276
275
  encodedBytes -
277
276
  separatorBytes -
278
277
  encodedKeyBytes -
279
278
  1 -
280
- truncationPropertyBytes;
279
+ truncationPropertyBytes(visitedProperties + 1);
281
280
  if (childAllowance < 48) {
282
281
  truncated = true;
283
282
  break;
@@ -301,18 +300,18 @@ export function normalizeJsonValue(value: unknown, limits: IFlexJsonLimits = {})
301
300
  visitedProperties++;
302
301
  }
303
302
  if (truncated) {
303
+ // Before the first property there is no room reserved: an object too small for its
304
+ // truncation property is a marker itself.
305
+ if (encodedBytes + truncationPropertyBytes(visitedProperties) > allowance) {
306
+ return description('truncated', { reason: 'bytes' }, allowance);
307
+ }
304
308
  const truncation = description(
305
309
  'truncated',
306
310
  { reason: 'bytes', visitedProperties },
307
311
  allowance,
308
312
  );
309
- const separatorBytes = visitedProperties > 0 ? 1 : 0;
310
313
  normalized[truncationKey] = truncation.value;
311
- encodedBytes +=
312
- separatorBytes +
313
- Buffer.byteLength(JSON.stringify(truncationKey)) +
314
- 1 +
315
- truncation.bytes;
314
+ encodedBytes += truncationPropertyBytes(visitedProperties);
316
315
  }
317
316
  return { value: normalized, bytes: encodedBytes };
318
317
  };
@@ -348,22 +347,8 @@ function failJsonWalk(walk: IJsonWalk, message: string): never {
348
347
  throw new FlexHarnessStoreFormatError(`${path} ${message}`);
349
348
  }
350
349
 
351
- /**
352
- * Rejects anything a JSON round trip would not preserve. With `walk.copy` it also returns the copy
353
- * `JSON.parse(JSON.stringify(value))` would return, built in the same pass.
354
- */
355
- function walkJsonValue(walk: IJsonWalk, value: unknown): unknown {
356
- if (value === null || typeof value === 'string' || typeof value === 'boolean') {
357
- return value;
358
- }
359
- if (typeof value === 'number') {
360
- if (!Number.isFinite(value)) failJsonWalk(walk, 'contains a non-finite number.');
361
- // JSON writes -0 as 0.
362
- return value === 0 ? 0 : value;
363
- }
364
- if (typeof value !== 'object') {
365
- failJsonWalk(walk, `contains ${typeof value}, which is not JSON-safe.`);
366
- }
350
+ /** Rejects an object or array that is not a JSON container where the walk stands. */
351
+ function assertJsonContainer(walk: IJsonWalk, value: object): void {
367
352
  if (walk.ancestors.includes(value)) {
368
353
  failJsonWalk(walk, 'contains a circular reference.');
369
354
  }
@@ -373,8 +358,6 @@ function walkJsonValue(walk: IJsonWalk, value: unknown): unknown {
373
358
  if (Object.getOwnPropertySymbols(value).length > 0) {
374
359
  failJsonWalk(walk, 'contains a symbol-keyed property.');
375
360
  }
376
- walk.ancestors.push(value);
377
- let copy: unknown;
378
361
  if (Array.isArray(value)) {
379
362
  const length = value.length;
380
363
  // Own names list array indices in ascending order, then `length`, then any other keys, so a
@@ -394,6 +377,30 @@ function walkJsonValue(walk: IJsonWalk, value: unknown): unknown {
394
377
  failJsonWalk(walk, 'is not JSON-visible.');
395
378
  }
396
379
  }
380
+ }
381
+ }
382
+
383
+ /**
384
+ * Rejects anything a JSON round trip would not preserve. With `walk.copy` it also returns the copy
385
+ * `JSON.parse(JSON.stringify(value))` would return, built in the same pass.
386
+ */
387
+ function walkJsonValue(walk: IJsonWalk, value: unknown): unknown {
388
+ if (value === null || typeof value === 'string' || typeof value === 'boolean') {
389
+ return value;
390
+ }
391
+ if (typeof value === 'number') {
392
+ if (!Number.isFinite(value)) failJsonWalk(walk, 'contains a non-finite number.');
393
+ // JSON writes -0 as 0.
394
+ return value === 0 ? 0 : value;
395
+ }
396
+ if (typeof value !== 'object') {
397
+ failJsonWalk(walk, `contains ${typeof value}, which is not JSON-safe.`);
398
+ }
399
+ assertJsonContainer(walk, value);
400
+ walk.ancestors.push(value);
401
+ let copy: unknown;
402
+ if (Array.isArray(value)) {
403
+ const length = value.length;
397
404
  const items: unknown[] | undefined = walk.copy ? [] : undefined;
398
405
  const known = walk.knownEntries?.get(value) ?? 0;
399
406
  for (let index = 0; index < length; index++) {
@@ -2294,6 +2301,49 @@ export function cloneSerializable<T>(value: T): T {
2294
2301
  return walkJsonValue({ root: '$', segments: [], ancestors: [], copy: true }, value) as T;
2295
2302
  }
2296
2303
 
2304
+ /**
2305
+ * `cloneSerializable(value)` in slices: the same copy and the same error for a value that is not
2306
+ * JSON, pausing through `slicer` between the entries of `value`. Each entry is copied whole.
2307
+ */
2308
+ export async function cloneSerializableSliced<T>(value: T, slicer: FlexTimeSlicer): Promise<T> {
2309
+ const walk: IJsonWalk = { root: '$', segments: [], ancestors: [], copy: true };
2310
+ if (value === null || typeof value !== 'object') return walkJsonValue(walk, value) as T;
2311
+ assertJsonContainer(walk, value);
2312
+ walk.ancestors.push(value);
2313
+ let copy: unknown;
2314
+ if (Array.isArray(value)) {
2315
+ const items: unknown[] = [];
2316
+ for (let index = 0; index < value.length; index++) {
2317
+ walk.segments.push(index);
2318
+ if (!(index in value)) failJsonWalk(walk, 'is a sparse array entry.');
2319
+ items.push(walkJsonValue(walk, value[index]));
2320
+ walk.segments.pop();
2321
+ if (slicer.due) await slicer.pause();
2322
+ }
2323
+ copy = items;
2324
+ } else {
2325
+ const fields: Record<string, unknown> = {};
2326
+ for (const key of Object.getOwnPropertyNames(value)) {
2327
+ const descriptor = Object.getOwnPropertyDescriptor(value, key)!;
2328
+ walk.segments.push(key);
2329
+ if (!descriptor.enumerable || !('value' in descriptor)) {
2330
+ failJsonWalk(walk, 'is not a plain JSON property.');
2331
+ }
2332
+ const field = walkJsonValue(walk, descriptor.value);
2333
+ if (key in fields) {
2334
+ Object.defineProperty(fields, key, { value: field, enumerable: true, writable: true, configurable: true });
2335
+ } else {
2336
+ fields[key] = field;
2337
+ }
2338
+ walk.segments.pop();
2339
+ if (slicer.due) await slicer.pause();
2340
+ }
2341
+ copy = fields;
2342
+ }
2343
+ walk.ancestors.pop();
2344
+ return copy as T;
2345
+ }
2346
+
2297
2347
  export function deepFreeze<T>(value: T): T {
2298
2348
  if (!value || typeof value !== 'object' || Object.isFrozen(value)) {
2299
2349
  return value;
@@ -0,0 +1,75 @@
1
+ import * as plugins from './plugins.js';
2
+ import type { IFlexScopeSnapshot, IFlexSession, IFlexSessionIdentity } from './interfaces.js';
3
+ import { cloneSerializable } from './utils.json.js';
4
+ import { requireSessionGeneration } from './utils.flexharness.js';
5
+
6
+ function deriveLegacySessionGenerationId(
7
+ storageKey: string,
8
+ sessionId: string,
9
+ createdAt: string,
10
+ ): string {
11
+ const digest = plugins.crypto.createHash('sha256').update(JSON.stringify([
12
+ 'flexharness-legacy-session-generation-v1',
13
+ storageKey,
14
+ sessionId,
15
+ createdAt,
16
+ ])).digest('hex');
17
+ return `legacy_${digest}`;
18
+ }
19
+
20
+ /**
21
+ * The scope a store holds as the harness works with it: a copy of `stored`, or the empty scope,
22
+ * whose sessions and tombstones stored before session generations existed carry the generation
23
+ * derived for them. `changed` says whether any did; the scope load then saves the copy.
24
+ */
25
+ export function normalizeScopeSnapshot(
26
+ storageKey: string,
27
+ stored: IFlexScopeSnapshot | undefined,
28
+ ): { snapshot: IFlexScopeSnapshot; changed: boolean } {
29
+ const snapshot = cloneSerializable(stored ?? {
30
+ schemaVersion: 1,
31
+ revision: 0,
32
+ sessions: [],
33
+ tombstones: [],
34
+ } satisfies IFlexScopeSnapshot);
35
+ let changed = false;
36
+ const repairedGenerationSequence = snapshot.revision + 1;
37
+ for (const session of snapshot.sessions) {
38
+ if (session.sessionGenerationId !== undefined) continue;
39
+ session.sessionGenerationId = deriveLegacySessionGenerationId(
40
+ storageKey,
41
+ session.sessionId,
42
+ session.createdAt,
43
+ );
44
+ session.sessionGenerationSequence = repairedGenerationSequence;
45
+ changed = true;
46
+ }
47
+ for (const tombstone of snapshot.tombstones) {
48
+ if (tombstone.sessionGenerationId !== undefined) continue;
49
+ tombstone.sessionGenerationId = deriveLegacySessionGenerationId(
50
+ storageKey,
51
+ tombstone.sessionId,
52
+ tombstone.deletedAt,
53
+ );
54
+ tombstone.sessionGenerationSequence = repairedGenerationSequence;
55
+ changed = true;
56
+ }
57
+ return { snapshot, changed };
58
+ }
59
+
60
+ /** The sessions of a scope snapshot that no tombstone deletes, in snapshot order. */
61
+ export function liveScopeSessions(snapshot: IFlexScopeSnapshot): IFlexSession[] {
62
+ const tombstoned = new Set(snapshot.tombstones.map((tombstone) => tombstone.sessionId));
63
+ return snapshot.sessions.filter((session) => !tombstoned.has(session.sessionId));
64
+ }
65
+
66
+ /** The identities of `sessions`, sorted by session id as scope snapshots are. */
67
+ export function sessionIdentities(sessions: Iterable<IFlexSession>): IFlexSessionIdentity[] {
68
+ return [...sessions]
69
+ .map((session): IFlexSessionIdentity => ({
70
+ sessionId: session.sessionId,
71
+ ...requireSessionGeneration(session),
72
+ ...(session.parentSessionId === undefined ? {} : { parentSessionId: session.parentSessionId }),
73
+ }))
74
+ .sort((left, right) => left.sessionId.localeCompare(right.sessionId));
75
+ }
@@ -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