@modelprofile.com/flexharness 18.6.0 → 18.8.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/ts/interfaces.ts CHANGED
@@ -1726,6 +1726,45 @@ export interface IFlexScopeRecoverySnapshot {
1726
1726
  recoverySessionIds: string[];
1727
1727
  }
1728
1728
 
1729
+ /** An unresolved session. A clean publication must replace this state through an exact CAS. */
1730
+ export interface IFlexSessionRecoveryDirtyState {
1731
+ sessionId: string;
1732
+ state: 'dirty';
1733
+ }
1734
+
1735
+ /** A bounded commitment to one incarnation of a persistent session log. */
1736
+ export interface IFlexSessionRecoveryHead {
1737
+ incarnationId: string;
1738
+ revision: number;
1739
+ contentRoot: string;
1740
+ }
1741
+
1742
+ /** The exact producer identity and authenticated histories certified by a clean publication. */
1743
+ export interface IFlexSessionRecoveryCleanState {
1744
+ sessionId: string;
1745
+ state: 'clean';
1746
+ sessionGenerationId: string;
1747
+ sessionGenerationSequence: number;
1748
+ sessionDigest: string;
1749
+ projection: IFlexSessionRecoveryHead;
1750
+ agentEvents: IFlexSessionRecoveryHead;
1751
+ }
1752
+
1753
+ export type TFlexSessionRecoveryState =
1754
+ | IFlexSessionRecoveryDirtyState
1755
+ | IFlexSessionRecoveryCleanState;
1756
+
1757
+ /** Additive sidecar schema; strict schema-1 scope snapshots remain unchanged. */
1758
+ export interface IFlexScopeRecoverySnapshotV2 {
1759
+ schemaVersion: 2;
1760
+ revision: number;
1761
+ catalogueRevision: number;
1762
+ catalogueDigest: string;
1763
+ sessionStates: TFlexSessionRecoveryState[];
1764
+ }
1765
+
1766
+ export type TFlexScopeRecoverySnapshot = IFlexScopeRecoverySnapshot | IFlexScopeRecoverySnapshotV2;
1767
+
1729
1768
  /**
1730
1769
  * Additive sidecar persistence for `RecoverableFlexScopeStore`: the recovery proof and the
1731
1770
  * namespace's write provenance. A scope snapshot cannot show that nothing needs recovery: a writer
@@ -1775,6 +1814,13 @@ export interface IFlexScopeRecoveryStore {
1775
1814
  save(storageKey: string, snapshot: IFlexScopeRecoverySnapshot, expectedRevision: number): Promise<void>;
1776
1815
  }
1777
1816
 
1817
+ /** Explicit schema-2 storage capability; schema-1 recovery stores retain their original contract. */
1818
+ export interface IFlexScopeRecoveryStoreV2 extends Omit<IFlexScopeRecoveryStore, 'load' | 'save'> {
1819
+ readonly recoverySchemaVersion: 2;
1820
+ load(storageKey: string): Promise<TFlexScopeRecoverySnapshot | undefined>;
1821
+ save(storageKey: string, snapshot: TFlexScopeRecoverySnapshot, expectedRevision: number): Promise<void>;
1822
+ }
1823
+
1778
1824
  /** Requires exclusive namespace ownership, like the harness itself. */
1779
1825
  export interface IFlexSessionLocalScopeStore {
1780
1826
  /** Releases local writer activation only, not a distributed namespace lock. */
@@ -1829,6 +1875,8 @@ export interface IFlexProjectionStore {
1829
1875
  }
1830
1876
 
1831
1877
  export interface IFlexProjectionHead {
1878
+ /** Present on stores that can prove the log was not deleted and recreated at this revision. */
1879
+ incarnationId?: string;
1832
1880
  revision: number;
1833
1881
  contentRoot: string;
1834
1882
  }
@@ -2396,6 +2444,20 @@ export interface IFlexUncertainToolExecution {
2396
2444
  timestamp: string;
2397
2445
  }
2398
2446
 
2447
+ /** Bounded inspection metadata; the tool input never crosses this API. */
2448
+ export type TFlexUncertainToolExecutionMetadata = Omit<IFlexUncertainToolExecution, 'input'>;
2449
+
2450
+ export interface IFlexUncertainToolExecutionPageOptions extends IFlexSessionGeneration {
2451
+ afterIntentId?: string;
2452
+ /** Defaults to 128 and may not exceed 128. */
2453
+ limit?: number;
2454
+ }
2455
+
2456
+ export interface IFlexUncertainToolExecutionPage {
2457
+ tools: TFlexUncertainToolExecutionMetadata[];
2458
+ nextAfterIntentId?: string;
2459
+ }
2460
+
2399
2461
  export type TFlexToolExecutionReconciliation =
2400
2462
  | {
2401
2463
  resolution: 'executed';
package/ts/plugins.ts CHANGED
@@ -163,6 +163,8 @@ export type {
163
163
  IAgentRetryEvent,
164
164
  IAgentRunResult,
165
165
  IAgentSession,
166
+ IAgentUncertainToolExecutionMetadata,
167
+ IAgentUncertainToolInspectionSession,
166
168
  IAgentContinuationSession,
167
169
  IAgentSessionOptions,
168
170
  IAgentToolCallUpdateEvent,
package/ts/readme.md CHANGED
@@ -688,6 +688,11 @@ await harness.listPendingPermissions(scopeId, sessionId);
688
688
  await harness.respondToPermission(scopeId, sessionId, permissionId, 'once');
689
689
  await harness.pushRuntimeEvent(scopeId, sessionId, { type: 'workspace.changed', path: 'src/' });
690
690
  await harness.listUncertainToolExecutions(scopeId, sessionId);
691
+ const { sessionGenerationId, sessionGenerationSequence } = await harness.getSession(scopeId, sessionId);
692
+ if (!sessionGenerationId || !sessionGenerationSequence) throw new Error('Session generation is unavailable.');
693
+ const inspection = { sessionGenerationId, sessionGenerationSequence };
694
+ const firstUncertainPage = await harness.pageUncertainToolExecutions(scopeId, sessionId, inspection);
695
+ await harness.getUncertainToolExecution(scopeId, sessionId, intentId, inspection);
691
696
  await harness.reconcileToolExecution(scopeId, sessionId, intentId, {
692
697
  resolution: 'executed',
693
698
  output: { committed: true },
@@ -773,7 +778,9 @@ When the older releases of a host change no such witness, the host cannot detect
773
778
 
774
779
  In-memory and NoSQL stores implement the additive capability. Existing custom stores and `JsonFileFlexHarnessStores` keep their eager behavior; the JSON store creates no new recovery files and cannot opt into session-local loading without a separate capable backend.
775
780
 
776
- The NoSQL projection store's optional `loadHead(storageKey, sessionId)` and Agent event store's optional `loadHead(sessionId)` return `{ revision, contentRoot }` from the record head without reading the base, change pages or event bodies. The SHA-256 root commits to the serialized log base and each ordered change; its stored revision and write-token binding advance in the same compare-and-swap as the head. A missing record, legacy unrooted log or head whose revision or write token an older writer advanced without renewing the root returns `undefined`; its next save validates and rewrites the complete log before it can supply a root. Malformed commitment fields fail closed. A full load verifies a current root against the stored base and changes. These heads are content commitments for a future recovery frontier; by themselves they do not make a catalogue session safe for a cold `getSession()` read. Other stores do not advertise bounded heads.
781
+ The NoSQL projection store's optional `loadHead(storageKey, sessionId)` and Agent event store's optional `loadHead(sessionId)` return `{ incarnationId, revision, contentRoot }` from the record head without reading the base, change pages or event bodies. The SHA-256 root commits to the serialized log base and each ordered change; its stored revision and write-token binding advance in the same compare-and-swap as the head. A missing record, legacy unrooted log or head whose revision or write token an older writer advanced without renewing the root returns `undefined`; its next save validates and rewrites the complete log before it can supply a root. Malformed commitment fields fail closed. A full load verifies a current root against the stored base and changes. These heads are content commitments for a future recovery frontier; by themselves they do not make a catalogue session safe for a cold `getSession()` read. Other stores do not advertise bounded heads.
782
+
783
+ The existing `IFlexScopeRecoveryStore` contract remains schema 1. A store that can read schema-2 sidecars explicitly implements `IFlexScopeRecoveryStoreV2`; the built-in NoSQL store does. `RecoverableFlexScopeStore` accepts either contract. New sidecars start at schema 1, and no production path promotes them to schema 2. On a session-local open, this compatibility version durably turns every inherited schema-2 clean state dirty before returning the catalogue; a failed sidecar write refuses the open. The sidecar stays schema 2, and cold loading performs normal recovery.
777
784
 
778
785
  ### Continuing Without New Input
779
786
 
@@ -1217,6 +1224,8 @@ Model resolver, tool provider, delegated run admission provider, AgentSession, t
1217
1224
 
1218
1225
  Transactional tool calls persist an execution intent before the tool side effect starts. After an interrupted process, `listUncertainToolExecutions()` exposes intents whose outcome cannot be proven. While any such intent remains, new prompts, continuations, scheduled and cache-warm turns, and delegated child turns are refused with `FlexHarnessUnresolvedToolExecutionsError` (`FLEX_UNRESOLVED_TOOL_EXECUTIONS`). A prompt queued while the current run's tool was still executing receives one failed queue outcome if that effect remains unresolved at promotion; the caller must explicitly resend it after reconciliation. A steer may join its own running generation while that generation's tool executes, but cannot enter a run with unresolved effects from another generation. A controller must inspect the external system and call `reconcileToolExecution()` with `executed`, `not-executed`, or `abandoned-unknown` before allowing dependent work to continue. Reconciliation output is normalized using the same tool-output limits. After reconciliation, the model sees its authoritative result once, even if an earlier unknown-effect result closed the call in the failed run; both events remain in the audit log. Neither reconciliation nor reopening admission retries a tool or resends input automatically.
1219
1226
 
1227
+ For a bounded inspection view, call `pageUncertainToolExecutions(scopeId, sessionId, { sessionGenerationId, sessionGenerationSequence, afterIntentId?, limit? }, signal?)` or `getUncertainToolExecution(scopeId, sessionId, intentId, { sessionGenerationId, sessionGenerationSequence }, signal?)`. Take the session generation from `getSession()` and keep it fixed across pages. Pages contain only `intentId`, `generationId`, `toolCallId`, `toolName`, and ISO `timestamp`; no tool input or output is read or returned. The default and maximum page size is 128, and `nextAfterIntentId` is present only when another page exists. A changed session generation throws `FlexHarnessUncertainToolInspectionStaleError` (`FLEX_UNCERTAIN_TOOL_INSPECTION_STALE`); an `afterIntentId` that was resolved or removed throws `FlexHarnessUncertainToolCursorStaleError` (`FLEX_UNCERTAIN_TOOL_CURSOR_STALE`), so start again from the first page. Exact lookup returns `null` for an absent or resolved intent. An optional abort signal cancels only that caller's wait. The existing `listUncertainToolExecutions()` still includes tool inputs for controllers that need them.
1228
+
1220
1229
  `agentSessionPolicy` forwards bounded AgentSession session controls for context building, compaction, event retention, change-listener pressure, lease cleanup, archived transaction tombstones, and context-overflow retries. A configured `contextCompactor` receives the projected model messages, only the filtered model-visible covered events, AgentSession's existing `reason` and `abortSignal`, and the exact resolved `scopeId`, `scope`, `storageKey`, and `sessionId` for the invocation causing compaction. The invocation context remains isolated when aliases share one storage key, so integrations can resolve the correct model without global mutable state. If no events are eligible for compaction, `compactSession()` returns without calling the compactor or writing a compaction event; otherwise it writes the canonical event. `archiveSessionEvents()` moves events covered by that compaction into the configured Agent event archive store and returns public archive metadata.
1221
1230
 
1222
1231
  `executionContextProvider` can construct a AgentSession execution context for each session. FlexHarness supplies the resolved scope, storage key, and the session's private job store. The public background APIs expose only execution ID, type, state, exit code, and timestamps; command payloads, stdout, and stderr remain private. The provider's optional `close()` is owned by session deletion, scope retirement, and harness disposal.
@@ -1,6 +1,6 @@
1
1
  import * as plugins from './plugins.js';
2
2
  import {
3
- assertFlexScopeRecoverySnapshot,
3
+ assertFlexScopeRecoverySnapshotVersioned,
4
4
  RecoverableFlexScopeStore,
5
5
  validateFlexScopeRecoverySave,
6
6
  } from '../ts/classes.scoperecovery.js';
@@ -17,8 +17,8 @@ import type {
17
17
  IFlexProjectionChange,
18
18
  IFlexProjectionStore,
19
19
  IFlexResultStore,
20
- IFlexScopeRecoverySnapshot,
21
- IFlexScopeRecoveryStore,
20
+ TFlexScopeRecoverySnapshot,
21
+ IFlexScopeRecoveryStoreV2,
22
22
  IFlexScopeSnapshot,
23
23
  IFlexScopeStore,
24
24
  IFlexToolJobStoreProvider,
@@ -129,7 +129,8 @@ class NoSqlScopeStore implements IFlexScopeStore {
129
129
  }
130
130
  }
131
131
 
132
- class NoSqlScopeRecoveryStore implements IFlexScopeRecoveryStore {
132
+ class NoSqlScopeRecoveryStore implements IFlexScopeRecoveryStoreV2 {
133
+ public readonly recoverySchemaVersion = 2;
133
134
  constructor(private readonly records: FlexRecordStore) {}
134
135
 
135
136
  public deactivateWriteProvenance(storageKey: string): void {
@@ -146,17 +147,17 @@ class NoSqlScopeRecoveryStore implements IFlexScopeRecoveryStore {
146
147
  return this.records.qualifyWriteProvenance(storageKey);
147
148
  }
148
149
 
149
- public load(storageKey: string): Promise<IFlexScopeRecoverySnapshot | undefined> {
150
+ public load(storageKey: string): Promise<TFlexScopeRecoverySnapshot | undefined> {
150
151
  validateIdentifier(storageKey, 'storageKey');
151
152
  return this.records.read({ domain: 'scopeRecovery', storageKey }, (value) => {
152
- assertFlexScopeRecoverySnapshot(value);
153
+ assertFlexScopeRecoverySnapshotVersioned(value);
153
154
  return value;
154
155
  });
155
156
  }
156
157
 
157
158
  public async save(
158
159
  storageKey: string,
159
- snapshot: IFlexScopeRecoverySnapshot,
160
+ snapshot: TFlexScopeRecoverySnapshot,
160
161
  expectedRevision: number,
161
162
  ): Promise<void> {
162
163
  validateIdentifier(storageKey, 'storageKey');
@@ -324,6 +324,7 @@ interface IStoredLog<TSnapshot> {
324
324
 
325
325
  /** A content commitment read from one bounded log head, without its base or change pages. */
326
326
  export interface IFlexRecordLogHead {
327
+ incarnationId: string;
327
328
  revision: number;
328
329
  contentRoot: string;
329
330
  }
@@ -573,7 +574,11 @@ export class FlexRecordStore {
573
574
  > FLEX_RECORD_INLINE_CHANGE_CODE_UNITS) {
574
575
  throw new FlexHarnessStoreFormatError(`Invalid content commitment at ${resolved.path}.`);
575
576
  }
576
- return root === undefined ? undefined : { revision: head.revision, contentRoot: root };
577
+ return root === undefined ? undefined : {
578
+ incarnationId: head.logId,
579
+ revision: head.revision,
580
+ contentRoot: root,
581
+ };
577
582
  });
578
583
  }
579
584
 
@@ -27,6 +27,8 @@ Scope snapshots retain exactly schema 1's `{ schemaVersion, revision, sessions,
27
27
 
28
28
  Qualification publishes its proof while inactive, then explicitly qualifies the namespace witness. A failure between those steps remains unqualified. Disposal, retirement and eager activation release local known-writer activation, including when a bundle is reused. Neither those hooks nor cross-process CAS replace the host's exclusive namespace lifecycle ownership. All namespace header access uses the public document-model APIs of `@lossless.org/client/nosqldb`.
29
29
 
30
+ On a session-local open, the compatibility harness converts every inherited schema-2 clean state to dirty in one sidecar CAS before it can hydrate a session or admit work. A failed CAS refuses the open. The schema-2 format and session IDs remain intact, so a later version must recover those sessions even if this version wrote only a projection or Agent event after the open.
31
+
30
32
  Engine qualification follows the store's client, `@lossless.org/client` ^1.17.0, which qualifies NoSQLDB 8.0.2 and 10.7.2; the store's tests run on NoSQLDB 10.x (10.11.0). NoSQLDB 11 is not qualified: on 11.1.2, two connections that create the same new collection at the same time can fail `prepare()` with `Created collection is not observable.` (one connection is told the collection exists while another still lists it as absent), and a fenced purge racing record creations can leave a record behind.
31
33
 
32
34
  The database is the application's. The stores never close it, and they need NoSQLDB or a MongoDB deployment with transactions. `prepare()` creates or verifies the `flexharness_records`, `flexharness_chunks`, `flexharness_changes` and `flexharness_namespaces` collections and their indexes; every store operation awaits the same preparation, so calling it at startup only moves that work and its failure forward. `operationTimeoutMs` (1 to 120000, default 30000) bounds every database call and transaction.
@@ -56,7 +58,7 @@ All writes in one namespace now contend on its namespace document, not only crea
56
58
 
57
59
  A projection and an Agent event history are each stored as a base plus the changes saved since. FlexHarness saves a projection as an `IFlexProjectionChange` and an Agent event history as an `IAgentEventChange`, which carry only the entries that changed, and the store appends the change to the record's head in the compare-and-swap that commits it, so a save reads and writes the head alone and costs the change rather than the whole session. The head holds the latest changes up to 16 Ki characters of JSON; the save that would exceed that first writes them, with its own change, as one page in `flexharness_changes`, and empties them in its swap. The base lives in chunks whatever its length, so the head each change swaps holds no payload; a session's first save creates the record together with a base of up to one chunk in one transaction. The changes are kept while together they stay no longer than the base, or than 64 Ki characters of JSON while the base is shorter, and no single change is longer than one chunk. The save that would exceed that compacts the record instead: it reads the record, applies the change, checks the resulting snapshot in full and writes it as the new base. The earlier base and its pages are removed like unreferenced chunks, by the record's next compaction, which finds those pages by their log instead of scanning the current one. A record therefore holds its base and changes no longer than it or that minimum, plus the earlier base and its pages until the next compaction. A session whose history shrank, after an undo branch for example, keeps its larger base until its changes outgrow it. A read applies every change to the base and checks the result in full, so it costs the base and every change since, and a record whose pages are incomplete fails with `FlexHarnessStoreFormatError`. A page a crashed writer left behind without swapping the head onto it is removed with the rest of its log, or by the record's deletion.
58
60
 
59
- The projection store and each Agent event store also expose `loadHead`, an optional bounded read of `{ revision, contentRoot }`. A rooted log's head commits to its serialized base and ordered changes; each append advances that SHA-256 root and binds it to the new revision and write token in the head CAS. A full read verifies a current root. Missing and older unrooted logs return no head. An older writer that advances a rooted head but preserves fields it does not know leaves a well-formed stale binding: `loadHead` returns no root, and the next save validates and rewrites the whole log. Malformed commitment fields fail closed. This commitment does not certify a repaired session or replace recovery evidence.
61
+ The projection store and each Agent event store also expose `loadHead`, an optional bounded read of `{ incarnationId, revision, contentRoot }`. `incarnationId` identifies the log record so a deleted and recreated log cannot match an earlier head at the same revision. A rooted log's head commits to its serialized base and ordered changes; each append advances that SHA-256 root and binds it to the new revision and write token in the head CAS. A full read verifies a current root. Missing and older unrooted logs return no head. An older writer that advances a rooted head but preserves fields it does not know leaves a well-formed stale binding: `loadHead` returns no root, and the next save validates and rewrites the whole log. Malformed commitment fields fail closed. This commitment does not certify a repaired session or replace recovery evidence.
60
62
 
61
63
  A save of a scope, permission or job snapshot checks its expected revision against the record's head alone: it never reads the stored snapshot or its chunks, which it replaces whole. A projection or Agent event change checks it against the head in the same way and checks only its own form; the store reads the record only when it compacts. A record swap that loses to a concurrent writer is decided again against the newer record, up to eight times, with a bounded exponential backoff between attempts; a writer that still loses gets the domain's conflict error.
62
64