@modelprofile.com/flexharness 18.4.0 → 18.6.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 (37) hide show
  1. package/dist_ts/00_commitinfo_data.js +1 -1
  2. package/dist_ts/classes.flexharness.core.js +5 -2
  3. package/dist_ts/classes.flexharness.prompts.d.ts +2 -0
  4. package/dist_ts/classes.flexharness.prompts.js +11 -2
  5. package/dist_ts/errors.d.ts +5 -0
  6. package/dist_ts/errors.js +10 -1
  7. package/dist_ts/index.d.ts +1 -0
  8. package/dist_ts/index.js +2 -1
  9. package/dist_ts/interfaces.d.ts +6 -0
  10. package/dist_ts/interfaces.js +1 -1
  11. package/dist_ts/plugins.d.ts +2 -2
  12. package/dist_ts/plugins.js +3 -3
  13. package/dist_ts/utils.json.d.ts +34 -1
  14. package/dist_ts/utils.json.js +47 -35
  15. package/dist_ts/utils.projectionindex.d.ts +58 -0
  16. package/dist_ts/utils.projectionindex.js +534 -0
  17. package/dist_ts/utils.projectionindextree.d.ts +63 -0
  18. package/dist_ts/utils.projectionindextree.js +314 -0
  19. package/dist_ts_stores_nosqldb/classes.nosqldbstores.js +11 -1
  20. package/dist_ts_stores_nosqldb/classes.recordstore.d.ts +12 -0
  21. package/dist_ts_stores_nosqldb/classes.recordstore.js +93 -9
  22. package/package.json +3 -3
  23. package/readme.md +5 -1
  24. package/ts/00_commitinfo_data.ts +1 -1
  25. package/ts/classes.flexharness.core.ts +4 -0
  26. package/ts/classes.flexharness.prompts.ts +17 -0
  27. package/ts/errors.ts +14 -0
  28. package/ts/index.ts +13 -0
  29. package/ts/interfaces.ts +7 -0
  30. package/ts/plugins.ts +2 -0
  31. package/ts/readme.md +5 -1
  32. package/ts/utils.json.ts +65 -43
  33. package/ts/utils.projectionindex.ts +693 -0
  34. package/ts/utils.projectionindextree.ts +328 -0
  35. package/ts_stores_nosqldb/classes.nosqldbstores.ts +12 -0
  36. package/ts_stores_nosqldb/classes.recordstore.ts +100 -7
  37. package/ts_stores_nosqldb/readme.md +2 -0
package/ts/interfaces.ts CHANGED
@@ -1813,6 +1813,8 @@ export interface IFlexScopeStore {
1813
1813
 
1814
1814
  export interface IFlexProjectionStore {
1815
1815
  load(storageKey: string, sessionId: string): Promise<TFlexProjectionSnapshot | undefined>;
1816
+ /** Optional bounded content commitment; undefined requires a full load. */
1817
+ loadHead?(storageKey: string, sessionId: string): Promise<IFlexProjectionHead | undefined>;
1816
1818
  /**
1817
1819
  * Applies `change` to the stored projection while its revision is `expectedRevision`; the
1818
1820
  * change's revision is the next one.
@@ -1826,6 +1828,11 @@ export interface IFlexProjectionStore {
1826
1828
  deleteSession(storageKey: string, sessionId: string): Promise<void>;
1827
1829
  }
1828
1830
 
1831
+ export interface IFlexProjectionHead {
1832
+ revision: number;
1833
+ contentRoot: string;
1834
+ }
1835
+
1829
1836
  export interface IFlexPermissionStore {
1830
1837
  load(storageKey: string, sessionId: string): Promise<IFlexPermissionSnapshot | undefined>;
1831
1838
  save(
package/ts/plugins.ts CHANGED
@@ -100,6 +100,7 @@ import {
100
100
  assertAttachmentResolver,
101
101
  AgentPendingInputRejectedError,
102
102
  AgentSession,
103
+ AgentUnresolvedToolExecutionsError,
103
104
  AgentToolCallScheduler,
104
105
  assertAgentContextCompactionSetting,
105
106
  buildModelMessages,
@@ -127,6 +128,7 @@ export {
127
128
  assertAttachmentResolver,
128
129
  AgentPendingInputRejectedError,
129
130
  AgentSession,
131
+ AgentUnresolvedToolExecutionsError,
130
132
  AgentToolCallScheduler,
131
133
  assertAgentContextCompactionSetting,
132
134
  buildModelMessages,
package/ts/readme.md CHANGED
@@ -773,6 +773,8 @@ When the older releases of a host change no such witness, the host cannot detect
773
773
 
774
774
  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
775
 
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.
777
+
776
778
  ### Continuing Without New Input
777
779
 
778
780
  Use `continuePrompt()` after a failed or stopped run whose input remains in context
@@ -1213,7 +1215,7 @@ Model resolver, tool provider, delegated run admission provider, AgentSession, t
1213
1215
 
1214
1216
  `pushRuntimeEvent()` appends a validated JSON event through the canonical AgentSession event store. It is intended for controller-owned context such as workspace changes or external notifications; invalid or non-JSON values fail before persistence.
1215
1217
 
1216
- 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. 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.
1218
+ 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.
1217
1219
 
1218
1220
  `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.
1219
1221
 
@@ -1342,6 +1344,8 @@ A custom store validates what it loads and saves with the validators the built-i
1342
1344
 
1343
1345
  Projections and Agent event histories are saved as changes, so a save costs what changed rather than the whole session. `IFlexProjectionStore.save(storageKey, sessionId, change, expectedRevision)` receives an `IFlexProjectionChange`: the schema-3 projection with `messages` and `reversionSegments` given as `IFlexListChange`s `{ start, end, items }`, each of which keeps the stored entries from `start` up to `end` and appends `items`. A list change with `start` and `end` at 0 replaces the list whole; FlexHarness sends whole lists when it cannot know which entries the store holds: for a projection it loaded in an older schema and after a save with an uncertain outcome. The Agent event store of each session receives an `IAgentEventChange` of removed, replaced and appended events, as the `@modelprofile.com/flexharness-agent` readme describes. A store that keeps snapshots checks a change's form with `assertFlexProjectionChange()` or `assertAgentEventChange()`, applies it with `applyFlexProjectionChange()` or `applyAgentEventChange()`, and validates the result as above; `createWholeProjectionChange(snapshot)` makes the change that stores a projection whole. `createChangedProjectionSnapshot(stored, change, sessionId)` applies a projection change and validates the result in one step that costs what the change carries rather than the whole session: it validates the change's own entries and other fields in full and reads the stored entries the change keeps only for their identities (message, run, event and capture IDs, roles and statuses), which relate every entry to the others. For a `stored` that `assertFlexProjectionSnapshot(stored, sessionId)` accepted or the function returned, it throws exactly when `assertFlexProjectionSnapshot(applyFlexProjectionChange(stored, change), sessionId)` throws and otherwise returns that snapshot, provided the stored entries were not modified after their validation. The in-memory and JSON-file stores save through it. FlexHarness freezes every message and reversion segment it saved and replaces an entry instead of editing it, which is how it tells the entries the store already holds. `/stores/testing` exports `createFlexStoreContractTests(backend)`, the cases every built-in store passes, for a custom store to run with any test runner; its readme shows how.
1344
1346
 
1347
+ `createProjectionValidationIndex(snapshot, sessionId)` validates a stored projection in full once and returns `{ rootHash, writes }`, where each write is an immutable `{ hash, node }` addressed by the SHA-256 of canonical JSON. It stores only message and reversion identities, ordered positions, and relation facts; no message body is retained in the index. An absent or older-schema projection produces an empty current-schema index and requires whole-list changes. A content-addressed store checks each `hashFlexProjectionIndexNode(node) === hash`, persists the returned nodes and binds `rootHash` to the same projection candidate, session, revision, and incarnation in its committed head. For later saves, `validateProjectionChangeWithIndex(rootHash, reader, change, expectedRevision, sessionId)` reads authenticated nodes through `reader.readNode(hash)` and returns a cloned validated `change` plus the next root and node writes. A normal append reads and writes tree paths proportional to the change and logarithmic in retained history; dropping a range also visits the entries it removes. The store must stage both the projection content and these index writes, then publish both roots in one revision compare-and-swap. A missing node, wrong digest, session, or revision fails the validation. After an uncertain commit, reload the authoritative head before retrying.
1348
+
1345
1349
  Custom Agent event and job providers may implement `releaseSession(storageKey, sessionId)` to release session-bound wrappers, handles, or caches without deleting durable data. FlexHarness calls these hooks only after the corresponding AgentSession or execution context has released runtime ownership. A failed release remains owned for a later retirement or disposal retry. `deleteSession()` and `deleteSessionGenerationCohort()` are the separate destructive operations for durable session data.
1346
1350
 
1347
1351
  `JsonFileFlexHarnessStores` stores the domains in separate `scopes`, `projections`, `permissions`, `projectManagement`, `events`, `archives`, and `jobs` directories. Storage and session identifiers are SHA-256 hashed for filenames. Passing the store bundle supplies lifecycle persistence but does not enable any built-in tool. It provides:
package/ts/utils.json.ts CHANGED
@@ -771,7 +771,7 @@ function validateUsage(value: unknown, path: string): void {
771
771
  requireNonNegativeNumber(usage.cacheWriteTokens, `${path}.cacheWriteTokens`);
772
772
  }
773
773
 
774
- interface IValidatedMessageIdentity {
774
+ export interface IValidatedMessageIdentity {
775
775
  messageId: string;
776
776
  sessionId: string;
777
777
  runId: string;
@@ -792,7 +792,7 @@ interface IValidatedSessionIdentity {
792
792
  depth?: number;
793
793
  }
794
794
 
795
- function validateMessage(value: unknown, path: string): IValidatedMessageIdentity {
795
+ export function validateMessage(value: unknown, path: string): IValidatedMessageIdentity {
796
796
  const message = requireRecord(value, path);
797
797
  requireOnlyKeys(
798
798
  message,
@@ -1246,7 +1246,7 @@ interface IValidatedProjectionBody {
1246
1246
  stagedMessages: IValidatedMessageIdentity[];
1247
1247
  }
1248
1248
 
1249
- interface IValidatedStagedTerminal {
1249
+ export interface IValidatedStagedTerminal {
1250
1250
  runId: string;
1251
1251
  user?: IValidatedMessageIdentity;
1252
1252
  assistant: IValidatedMessageIdentity;
@@ -1264,7 +1264,7 @@ const stagedTerminalKeys = [
1264
1264
  ];
1265
1265
 
1266
1266
  /** One staged terminal by itself: its fields, and messages that belong to its run and status. */
1267
- function validateStagedTerminal(value: unknown, path: string): IValidatedStagedTerminal {
1267
+ export function validateStagedTerminal(value: unknown, path: string): IValidatedStagedTerminal {
1268
1268
  const terminal = requireRecord(value, path);
1269
1269
  requireOnlyKeys(terminal, stagedTerminalKeys, path);
1270
1270
  const runId = requireString(terminal.runId, `${path}.runId`);
@@ -1648,7 +1648,7 @@ function validateAffectedWorkspaces(value: unknown, path: string): void {
1648
1648
  }
1649
1649
  }
1650
1650
 
1651
- function assertSessionMetrics(value: unknown): void {
1651
+ export function assertSessionMetrics(value: unknown): void {
1652
1652
  const path = '$snapshot.metrics';
1653
1653
  const metrics = requireRecord(value, path);
1654
1654
  requireOnlyKeys(metrics, [
@@ -1740,7 +1740,7 @@ const reversionSegmentKeys = [
1740
1740
  * One schema-3 reversion segment by itself: its fields and the workspace ownership its
1741
1741
  * provenance, status and disposition allow.
1742
1742
  */
1743
- function validateReversionSegment(value: unknown, path: string): void {
1743
+ export function validateReversionSegment(value: unknown, path: string): void {
1744
1744
  const segment = requireRecord(value, path);
1745
1745
  requireOnlyKeys(segment, reversionSegmentKeys, path);
1746
1746
  requireString(segment.runId, `${path}.runId`);
@@ -1954,6 +1954,30 @@ interface IReversionSegmentFacts {
1954
1954
  capturingRunIds: string[];
1955
1955
  }
1956
1956
 
1957
+ /** Relates one segment to its visible and staged turn facts, independent of their storage layout. */
1958
+ export function assertProjectionSegmentTurnRelation(
1959
+ segment: Pick<IFlexReversionSegment, 'userMessageId'>,
1960
+ facts: {
1961
+ readonly visiblePrompt: boolean;
1962
+ readonly stagedPrompt: boolean;
1963
+ readonly assistant: boolean;
1964
+ readonly matchingVisibleUser: boolean;
1965
+ readonly matchingStagedUser: boolean;
1966
+ },
1967
+ path: string,
1968
+ ): void {
1969
+ if (segment.userMessageId === undefined) {
1970
+ if (facts.visiblePrompt || facts.stagedPrompt) {
1971
+ throw new FlexHarnessStoreFormatError(`${path} omits its projected prompt identity.`);
1972
+ }
1973
+ if (!facts.assistant) {
1974
+ throw new FlexHarnessStoreFormatError(`${path} does not match its projected turn messages.`);
1975
+ }
1976
+ } else if (!facts.matchingVisibleUser && !facts.matchingStagedUser) {
1977
+ throw new FlexHarnessStoreFormatError(`${path} does not match its projected turn messages.`);
1978
+ }
1979
+ }
1980
+
1957
1981
  /**
1958
1982
  * Validates the segments after the `kept` first in full, then reads every segment's identity
1959
1983
  * once: run, event and capture IDs are unique, and each segment matches its run's messages.
@@ -2000,35 +2024,44 @@ function relateReversionSegments(
2000
2024
  if (segment.status === 'capturing') facts.capturingRunIds.push(runId);
2001
2025
  }
2002
2026
  if (segment.status === 'completed') facts.completed.push(index);
2003
- if (userMessageId === undefined) {
2004
- // An assistant-only continuation: its run has no prompt and an assistant message.
2005
- if (messages.visiblePromptRunIds.has(runId) || messages.stagedPromptRunIds.has(runId)) {
2006
- throw new FlexHarnessStoreFormatError(
2007
- `$snapshot.reversionSegments[${index}] omits its projected prompt identity.`,
2008
- );
2009
- }
2010
- if (!messages.assistantRunIds.has(runId)) {
2011
- throw new FlexHarnessStoreFormatError(
2012
- `$snapshot.reversionSegments[${index}] does not match its projected turn messages.`,
2013
- );
2014
- }
2015
- } else {
2016
- const visible = messages.visible.get(userMessageId);
2017
- const staged = messages.staged.get(userMessageId);
2018
- if (
2019
- !(visible?.runId === runId && visible.role === 'user')
2020
- && !(staged?.runId === runId && staged.role === 'user')
2021
- ) {
2022
- throw new FlexHarnessStoreFormatError(
2023
- `$snapshot.reversionSegments[${index}] does not match its projected turn messages.`,
2024
- );
2025
- }
2026
- }
2027
+ const visible = userMessageId === undefined ? undefined : messages.visible.get(userMessageId);
2028
+ const staged = userMessageId === undefined ? undefined : messages.staged.get(userMessageId);
2029
+ assertProjectionSegmentTurnRelation(segment, {
2030
+ visiblePrompt: messages.visiblePromptRunIds.has(runId),
2031
+ stagedPrompt: messages.stagedPromptRunIds.has(runId),
2032
+ assistant: messages.assistantRunIds.has(runId),
2033
+ matchingVisibleUser: visible?.runId === runId && visible.role === 'user',
2034
+ matchingStagedUser: staged?.runId === runId && staged.role === 'user',
2035
+ }, `$snapshot.reversionSegments[${index}]`);
2027
2036
  }
2028
2037
  return facts;
2029
2038
  }
2030
2039
 
2031
2040
  /** Checks a pending apply against the segments: it moves the cursor by one unit, applied in order. */
2041
+ export function assertPendingApplyRunIds(pendingRuns: readonly string[], appliedRuns: readonly string[]): void {
2042
+ if (new Set(pendingRuns).size !== pendingRuns.length || new Set(appliedRuns).size !== appliedRuns.length) {
2043
+ throw new FlexHarnessStoreFormatError('Snapshot pending apply run IDs are invalid.');
2044
+ }
2045
+ if (appliedRuns.some((runId) => !pendingRuns.includes(runId))) {
2046
+ throw new FlexHarnessStoreFormatError('Snapshot pending apply progress is invalid.');
2047
+ }
2048
+ }
2049
+
2050
+ export function assertPendingApplyRunUnit(
2051
+ pendingRuns: readonly string[],
2052
+ appliedRuns: readonly string[],
2053
+ exactRuns: readonly string[],
2054
+ direction: 'undo' | 'redo',
2055
+ ): void {
2056
+ if (pendingRuns.length !== exactRuns.length || pendingRuns.some((runId, index) => runId !== exactRuns[index])) {
2057
+ throw new FlexHarnessStoreFormatError('Snapshot pending apply segment unit is invalid.');
2058
+ }
2059
+ const applyOrder = direction === 'undo' ? [...exactRuns].reverse() : exactRuns;
2060
+ if (appliedRuns.some((runId, index) => runId !== applyOrder[index])) {
2061
+ throw new FlexHarnessStoreFormatError('Snapshot pending apply progress is out of order.');
2062
+ }
2063
+ }
2064
+
2032
2065
  function validatePendingApply(
2033
2066
  pending: Record<string, unknown>,
2034
2067
  revertCursor: number,
@@ -2054,12 +2087,7 @@ function validatePendingApply(
2054
2087
  requireNonNegativeInteger(pending.toCursor, '$snapshot.pendingReversion.toCursor');
2055
2088
  const pendingRuns = requireStringArray(pending.segmentRunIds, '$snapshot.pendingReversion.segmentRunIds');
2056
2089
  const appliedRuns = requireStringArray(pending.appliedRunIds, '$snapshot.pendingReversion.appliedRunIds');
2057
- if (new Set(pendingRuns).size !== pendingRuns.length || new Set(appliedRuns).size !== appliedRuns.length) {
2058
- throw new FlexHarnessStoreFormatError('Snapshot pending apply run IDs are invalid.');
2059
- }
2060
- if (appliedRuns.some((runId) => !pendingRuns.includes(runId))) {
2061
- throw new FlexHarnessStoreFormatError('Snapshot pending apply progress is invalid.');
2062
- }
2090
+ assertPendingApplyRunIds(pendingRuns, appliedRuns);
2063
2091
  const fromCursor = Number(pending.fromCursor);
2064
2092
  const toCursor = Number(pending.toCursor);
2065
2093
  const direction = pending.direction as 'undo' | 'redo';
@@ -2081,13 +2109,7 @@ function validatePendingApply(
2081
2109
  const start = rangeStart === 0 ? 0 : first;
2082
2110
  const end = facts.completed[rangeEnd] ?? segments.length;
2083
2111
  const exactRuns = segments.slice(start, end).map((segment) => segment.runId);
2084
- if (pendingRuns.length !== exactRuns.length || pendingRuns.some((runId, index) => runId !== exactRuns[index])) {
2085
- throw new FlexHarnessStoreFormatError('Snapshot pending apply segment unit is invalid.');
2086
- }
2087
- const applyOrder = direction === 'undo' ? [...exactRuns].reverse() : exactRuns;
2088
- if (appliedRuns.some((runId, index) => runId !== applyOrder[index])) {
2089
- throw new FlexHarnessStoreFormatError('Snapshot pending apply progress is out of order.');
2090
- }
2112
+ assertPendingApplyRunUnit(pendingRuns, appliedRuns, exactRuns, direction);
2091
2113
  }
2092
2114
 
2093
2115
  /**