@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.
@@ -0,0 +1,14 @@
1
+ import type { IFlexScopeSnapshot, IFlexSession, IFlexSessionIdentity } from './interfaces.js';
2
+ /**
3
+ * The scope a store holds as the harness works with it: a copy of `stored`, or the empty scope,
4
+ * whose sessions and tombstones stored before session generations existed carry the generation
5
+ * derived for them. `changed` says whether any did; the scope load then saves the copy.
6
+ */
7
+ export declare function normalizeScopeSnapshot(storageKey: string, stored: IFlexScopeSnapshot | undefined): {
8
+ snapshot: IFlexScopeSnapshot;
9
+ changed: boolean;
10
+ };
11
+ /** The sessions of a scope snapshot that no tombstone deletes, in snapshot order. */
12
+ export declare function liveScopeSessions(snapshot: IFlexScopeSnapshot): IFlexSession[];
13
+ /** The identities of `sessions`, sorted by session id as scope snapshots are. */
14
+ export declare function sessionIdentities(sessions: Iterable<IFlexSession>): IFlexSessionIdentity[];
@@ -0,0 +1,58 @@
1
+ import * as plugins from './plugins.js';
2
+ import { cloneSerializable } from './utils.json.js';
3
+ import { requireSessionGeneration } from './utils.flexharness.js';
4
+ function deriveLegacySessionGenerationId(storageKey, sessionId, createdAt) {
5
+ const digest = plugins.crypto.createHash('sha256').update(JSON.stringify([
6
+ 'flexharness-legacy-session-generation-v1',
7
+ storageKey,
8
+ sessionId,
9
+ createdAt,
10
+ ])).digest('hex');
11
+ return `legacy_${digest}`;
12
+ }
13
+ /**
14
+ * The scope a store holds as the harness works with it: a copy of `stored`, or the empty scope,
15
+ * whose sessions and tombstones stored before session generations existed carry the generation
16
+ * derived for them. `changed` says whether any did; the scope load then saves the copy.
17
+ */
18
+ export function normalizeScopeSnapshot(storageKey, stored) {
19
+ const snapshot = cloneSerializable(stored ?? {
20
+ schemaVersion: 1,
21
+ revision: 0,
22
+ sessions: [],
23
+ tombstones: [],
24
+ });
25
+ let changed = false;
26
+ const repairedGenerationSequence = snapshot.revision + 1;
27
+ for (const session of snapshot.sessions) {
28
+ if (session.sessionGenerationId !== undefined)
29
+ continue;
30
+ session.sessionGenerationId = deriveLegacySessionGenerationId(storageKey, session.sessionId, session.createdAt);
31
+ session.sessionGenerationSequence = repairedGenerationSequence;
32
+ changed = true;
33
+ }
34
+ for (const tombstone of snapshot.tombstones) {
35
+ if (tombstone.sessionGenerationId !== undefined)
36
+ continue;
37
+ tombstone.sessionGenerationId = deriveLegacySessionGenerationId(storageKey, tombstone.sessionId, tombstone.deletedAt);
38
+ tombstone.sessionGenerationSequence = repairedGenerationSequence;
39
+ changed = true;
40
+ }
41
+ return { snapshot, changed };
42
+ }
43
+ /** The sessions of a scope snapshot that no tombstone deletes, in snapshot order. */
44
+ export function liveScopeSessions(snapshot) {
45
+ const tombstoned = new Set(snapshot.tombstones.map((tombstone) => tombstone.sessionId));
46
+ return snapshot.sessions.filter((session) => !tombstoned.has(session.sessionId));
47
+ }
48
+ /** The identities of `sessions`, sorted by session id as scope snapshots are. */
49
+ export function sessionIdentities(sessions) {
50
+ return [...sessions]
51
+ .map((session) => ({
52
+ sessionId: session.sessionId,
53
+ ...requireSessionGeneration(session),
54
+ ...(session.parentSessionId === undefined ? {} : { parentSessionId: session.parentSessionId }),
55
+ }))
56
+ .sort((left, right) => left.sessionId.localeCompare(right.sessionId));
57
+ }
58
+ //# sourceMappingURL=data:application/json;base64,eyJ2ZXJzaW9uIjozLCJmaWxlIjoidXRpbHMuc2NvcGVzbmFwc2hvdC5qcyIsInNvdXJjZVJvb3QiOiIiLCJzb3VyY2VzIjpbIi4uL3RzL3V0aWxzLnNjb3Blc25hcHNob3QudHMiXSwibmFtZXMiOltdLCJtYXBwaW5ncyI6IkFBQUEsT0FBTyxLQUFLLE9BQU8sTUFBTSxjQUFjLENBQUM7QUFFeEMsT0FBTyxFQUFFLGlCQUFpQixFQUFFLE1BQU0saUJBQWlCLENBQUM7QUFDcEQsT0FBTyxFQUFFLHdCQUF3QixFQUFFLE1BQU0sd0JBQXdCLENBQUM7QUFFbEUsU0FBUywrQkFBK0IsQ0FDdEMsVUFBa0IsRUFDbEIsU0FBaUIsRUFDakIsU0FBaUI7SUFFakIsTUFBTSxNQUFNLEdBQUcsT0FBTyxDQUFDLE1BQU0sQ0FBQyxVQUFVLENBQUMsUUFBUSxDQUFDLENBQUMsTUFBTSxDQUFDLElBQUksQ0FBQyxTQUFTLENBQUM7UUFDdkUsMENBQTBDO1FBQzFDLFVBQVU7UUFDVixTQUFTO1FBQ1QsU0FBUztLQUNWLENBQUMsQ0FBQyxDQUFDLE1BQU0sQ0FBQyxLQUFLLENBQUMsQ0FBQztJQUNsQixPQUFPLFVBQVUsTUFBTSxFQUFFLENBQUM7QUFDNUIsQ0FBQztBQUVEOzs7O0dBSUc7QUFDSCxNQUFNLFVBQVUsc0JBQXNCLENBQ3BDLFVBQWtCLEVBQ2xCLE1BQXNDO0lBRXRDLE1BQU0sUUFBUSxHQUFHLGlCQUFpQixDQUFDLE1BQU0sSUFBSTtRQUMzQyxhQUFhLEVBQUUsQ0FBQztRQUNoQixRQUFRLEVBQUUsQ0FBQztRQUNYLFFBQVEsRUFBRSxFQUFFO1FBQ1osVUFBVSxFQUFFLEVBQUU7S0FDYyxDQUFDLENBQUM7SUFDaEMsSUFBSSxPQUFPLEdBQUcsS0FBSyxDQUFDO0lBQ3BCLE1BQU0sMEJBQTBCLEdBQUcsUUFBUSxDQUFDLFFBQVEsR0FBRyxDQUFDLENBQUM7SUFDekQsS0FBSyxNQUFNLE9BQU8sSUFBSSxRQUFRLENBQUMsUUFBUSxFQUFFLENBQUM7UUFDeEMsSUFBSSxPQUFPLENBQUMsbUJBQW1CLEtBQUssU0FBUztZQUFFLFNBQVM7UUFDeEQsT0FBTyxDQUFDLG1CQUFtQixHQUFHLCtCQUErQixDQUMzRCxVQUFVLEVBQ1YsT0FBTyxDQUFDLFNBQVMsRUFDakIsT0FBTyxDQUFDLFNBQVMsQ0FDbEIsQ0FBQztRQUNGLE9BQU8sQ0FBQyx5QkFBeUIsR0FBRywwQkFBMEIsQ0FBQztRQUMvRCxPQUFPLEdBQUcsSUFBSSxDQUFDO0lBQ2pCLENBQUM7SUFDRCxLQUFLLE1BQU0sU0FBUyxJQUFJLFFBQVEsQ0FBQyxVQUFVLEVBQUUsQ0FBQztRQUM1QyxJQUFJLFNBQVMsQ0FBQyxtQkFBbUIsS0FBSyxTQUFTO1lBQUUsU0FBUztRQUMxRCxTQUFTLENBQUMsbUJBQW1CLEdBQUcsK0JBQStCLENBQzdELFVBQVUsRUFDVixTQUFTLENBQUMsU0FBUyxFQUNuQixTQUFTLENBQUMsU0FBUyxDQUNwQixDQUFDO1FBQ0YsU0FBUyxDQUFDLHlCQUF5QixHQUFHLDBCQUEwQixDQUFDO1FBQ2pFLE9BQU8sR0FBRyxJQUFJLENBQUM7SUFDakIsQ0FBQztJQUNELE9BQU8sRUFBRSxRQUFRLEVBQUUsT0FBTyxFQUFFLENBQUM7QUFDL0IsQ0FBQztBQUVELHFGQUFxRjtBQUNyRixNQUFNLFVBQVUsaUJBQWlCLENBQUMsUUFBNEI7SUFDNUQsTUFBTSxVQUFVLEdBQUcsSUFBSSxHQUFHLENBQUMsUUFBUSxDQUFDLFVBQVUsQ0FBQyxHQUFHLENBQUMsQ0FBQyxTQUFTLEVBQUUsRUFBRSxDQUFDLFNBQVMsQ0FBQyxTQUFTLENBQUMsQ0FBQyxDQUFDO0lBQ3hGLE9BQU8sUUFBUSxDQUFDLFFBQVEsQ0FBQyxNQUFNLENBQUMsQ0FBQyxPQUFPLEVBQUUsRUFBRSxDQUFDLENBQUMsVUFBVSxDQUFDLEdBQUcsQ0FBQyxPQUFPLENBQUMsU0FBUyxDQUFDLENBQUMsQ0FBQztBQUNuRixDQUFDO0FBRUQsaUZBQWlGO0FBQ2pGLE1BQU0sVUFBVSxpQkFBaUIsQ0FBQyxRQUFnQztJQUNoRSxPQUFPLENBQUMsR0FBRyxRQUFRLENBQUM7U0FDakIsR0FBRyxDQUFDLENBQUMsT0FBTyxFQUF3QixFQUFFLENBQUMsQ0FBQztRQUN2QyxTQUFTLEVBQUUsT0FBTyxDQUFDLFNBQVM7UUFDNUIsR0FBRyx3QkFBd0IsQ0FBQyxPQUFPLENBQUM7UUFDcEMsR0FBRyxDQUFDLE9BQU8sQ0FBQyxlQUFlLEtBQUssU0FBUyxDQUFDLENBQUMsQ0FBQyxFQUFFLENBQUMsQ0FBQyxDQUFDLEVBQUUsZUFBZSxFQUFFLE9BQU8sQ0FBQyxlQUFlLEVBQUUsQ0FBQztLQUMvRixDQUFDLENBQUM7U0FDRixJQUFJLENBQUMsQ0FBQyxJQUFJLEVBQUUsS0FBSyxFQUFFLEVBQUUsQ0FBQyxJQUFJLENBQUMsU0FBUyxDQUFDLGFBQWEsQ0FBQyxLQUFLLENBQUMsU0FBUyxDQUFDLENBQUMsQ0FBQztBQUMxRSxDQUFDIn0=
package/package.json CHANGED
@@ -2,7 +2,7 @@
2
2
  "author": "Task Venture Capital GmbH",
3
3
  "license": "MIT",
4
4
  "name": "@modelprofile.com/flexharness",
5
- "version": "18.0.0",
5
+ "version": "18.1.0",
6
6
  "type": "module",
7
7
  "description": "Managed agent sessions with tools, MCP, chat, OCR, documents and browser control through focused subpath imports.",
8
8
  "main": "./dist_ts/index.js",
@@ -91,8 +91,8 @@
91
91
  },
92
92
  "dependencies": {
93
93
  "@cfworker/json-schema": "^4.1.1",
94
- "@modelprofile.com/flexharness-agent": "18.0.0",
95
- "@modelprofile.com/flexharness-models": "18.0.0",
94
+ "@modelprofile.com/flexharness-agent": "18.1.0",
95
+ "@modelprofile.com/flexharness-models": "18.1.0",
96
96
  "@push.rocks/smartrequest": "^5.5.1",
97
97
  "ai": "^7.0.111",
98
98
  "zod": "^4.6.5"
package/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.
@@ -3,6 +3,6 @@
3
3
  */
4
4
  export const commitinfo = {
5
5
  name: '@modelprofile.com/flexharness',
6
- version: '18.0.0',
6
+ version: '18.1.0',
7
7
  description: 'The FlexHarness toolbox source repository and shared dependency catalog.'
8
8
  }