@modelprofile.com/flexharness 18.0.0 → 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.
@@ -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
+ }
@@ -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;
package/ts/interfaces.ts CHANGED
@@ -1510,6 +1510,12 @@ export interface IFlexSessionGeneration {
1510
1510
  sessionGenerationSequence: number;
1511
1511
  }
1512
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
+
1513
1519
  export const FLEX_SESSION_CONFIGURATION_REF_MAX_BYTES = 1024;
1514
1520
 
1515
1521
  export interface IFlexSessionConfigurationResolverContext<TScope> extends IFlexSessionGeneration {
@@ -2216,8 +2222,42 @@ export interface IFlexHarnessOptions<TScope> {
2216
2222
  maxSubagentCallsPerRun?: number;
2217
2223
  /** Bounds and the clock of the cache keeper; see `keepCacheWarm()`. */
2218
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;
2219
2257
  }
2220
2258
 
2259
+ export type TFlexScopeLoadObserver = (metricsArg: IFlexScopeLoadMetrics) => void;
2260
+
2221
2261
  export interface IFlexUncertainToolExecution {
2222
2262
  intentId: string;
2223
2263
  generationId: string;
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
@@ -639,6 +639,7 @@ The main session methods are:
639
639
 
640
640
  ```typescript
641
641
  await harness.listSessions(scopeId);
642
+ await harness.listSessionIdentities(scopeId);
642
643
  await harness.createSession(scopeId, { sessionId, sessionGenerationId, title });
643
644
  await harness.getSession(scopeId, sessionId);
644
645
  await harness.getMessages(scopeId, sessionId);
@@ -708,6 +709,10 @@ await harness.dispose();
708
709
 
709
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.
710
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
+
711
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.
712
717
 
713
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.
package/ts/utils.json.ts CHANGED
@@ -23,6 +23,7 @@ import type {
23
23
  TJsonValue,
24
24
  } from './interfaces.js';
25
25
  import { sliceUtf16 } from './utils.text.js';
26
+ import type { FlexTimeSlicer } from './classes.timeslicer.js';
26
27
  import { isValidSessionConfigurationRef } from './utils.validation.js';
27
28
 
28
29
  const DEFAULT_MAX_DEPTH = 12;
@@ -346,22 +347,8 @@ function failJsonWalk(walk: IJsonWalk, message: string): never {
346
347
  throw new FlexHarnessStoreFormatError(`${path} ${message}`);
347
348
  }
348
349
 
349
- /**
350
- * Rejects anything a JSON round trip would not preserve. With `walk.copy` it also returns the copy
351
- * `JSON.parse(JSON.stringify(value))` would return, built in the same pass.
352
- */
353
- function walkJsonValue(walk: IJsonWalk, value: unknown): unknown {
354
- if (value === null || typeof value === 'string' || typeof value === 'boolean') {
355
- return value;
356
- }
357
- if (typeof value === 'number') {
358
- if (!Number.isFinite(value)) failJsonWalk(walk, 'contains a non-finite number.');
359
- // JSON writes -0 as 0.
360
- return value === 0 ? 0 : value;
361
- }
362
- if (typeof value !== 'object') {
363
- failJsonWalk(walk, `contains ${typeof value}, which is not JSON-safe.`);
364
- }
350
+ /** Rejects an object or array that is not a JSON container where the walk stands. */
351
+ function assertJsonContainer(walk: IJsonWalk, value: object): void {
365
352
  if (walk.ancestors.includes(value)) {
366
353
  failJsonWalk(walk, 'contains a circular reference.');
367
354
  }
@@ -371,8 +358,6 @@ function walkJsonValue(walk: IJsonWalk, value: unknown): unknown {
371
358
  if (Object.getOwnPropertySymbols(value).length > 0) {
372
359
  failJsonWalk(walk, 'contains a symbol-keyed property.');
373
360
  }
374
- walk.ancestors.push(value);
375
- let copy: unknown;
376
361
  if (Array.isArray(value)) {
377
362
  const length = value.length;
378
363
  // Own names list array indices in ascending order, then `length`, then any other keys, so a
@@ -392,6 +377,30 @@ function walkJsonValue(walk: IJsonWalk, value: unknown): unknown {
392
377
  failJsonWalk(walk, 'is not JSON-visible.');
393
378
  }
394
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;
395
404
  const items: unknown[] | undefined = walk.copy ? [] : undefined;
396
405
  const known = walk.knownEntries?.get(value) ?? 0;
397
406
  for (let index = 0; index < length; index++) {
@@ -2292,6 +2301,49 @@ export function cloneSerializable<T>(value: T): T {
2292
2301
  return walkJsonValue({ root: '$', segments: [], ancestors: [], copy: true }, value) as T;
2293
2302
  }
2294
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
+
2295
2347
  export function deepFreeze<T>(value: T): T {
2296
2348
  if (!value || typeof value !== 'object' || Object.isFrozen(value)) {
2297
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
+ }