@modelprofile.com/flexharness 18.5.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.
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
 
@@ -193,6 +193,11 @@ class NoSqlProjectionStore implements IFlexProjectionStore {
193
193
  return this.records.readLog({ domain: 'projection', storageKey, sessionId }, this.log(sessionId));
194
194
  }
195
195
 
196
+ public loadHead(storageKey: string, sessionId: string) {
197
+ providerKey(storageKey, sessionId);
198
+ return this.records.readLogHead({ domain: 'projection', storageKey, sessionId });
199
+ }
200
+
196
201
  public async save(
197
202
  storageKey: string,
198
203
  sessionId: string,
@@ -344,6 +349,13 @@ class NoSqlAgentEventStore implements plugins.IAgentEventStore {
344
349
  );
345
350
  }
346
351
 
352
+ public loadHead(sessionId: string) {
353
+ this.assertSession(sessionId);
354
+ return this.records.readLogHead({
355
+ domain: 'agentEvents', storageKey: this.storageKey, sessionId,
356
+ });
357
+ }
358
+
347
359
  public async save(
348
360
  sessionId: string,
349
361
  change: plugins.IAgentEventChange,
@@ -128,6 +128,11 @@ export class FlexRecordDocument extends plugins.SmartDataDbDoc<FlexRecordDocumen
128
128
  public blobId!: string | null;
129
129
  public chunkCount!: number;
130
130
  public payloadSha256!: string | null;
131
+ /** Hash of the log base and every committed change, updated with the head CAS. */
132
+ public contentRoot?: string | null;
133
+ /** The exact head revision and token whose content the root commits. */
134
+ public contentRootRevision?: number;
135
+ public contentRootWriteToken?: string;
131
136
  /** Set before the first chunk of this record is written; the record's writes then sweep. */
132
137
  public chunked!: boolean;
133
138
  public sweepCount!: number;
@@ -222,6 +227,9 @@ export function bindFlexRecordModels(db: plugins.SmartdataDb): IFlexRecordModels
222
227
  'blobId',
223
228
  'chunkCount',
224
229
  'payloadSha256',
230
+ 'contentRoot',
231
+ 'contentRootRevision',
232
+ 'contentRootWriteToken',
225
233
  'chunked',
226
234
  'sweepCount',
227
235
  'logId',
@@ -232,7 +240,7 @@ export function bindFlexRecordModels(db: plugins.SmartdataDb): IFlexRecordModels
232
240
  'baseLength',
233
241
  'retiredLogId',
234
242
  ],
235
- numericFields: ['revision', 'chunkCount', 'sweepCount', 'changeCount', 'changeLength', 'baseLength'],
243
+ numericFields: ['revision', 'contentRootRevision', 'chunkCount', 'sweepCount', 'changeCount', 'changeLength', 'baseLength'],
236
244
  identityFields: ['recordId'],
237
245
  indexes: [
238
246
  { name: 'flexharness_record_id', key: { recordId: 1 }, options: { unique: true } },
@@ -314,6 +322,12 @@ interface IStoredLog<TSnapshot> {
314
322
  value?: TSnapshot;
315
323
  }
316
324
 
325
+ /** A content commitment read from one bounded log head, without its base or change pages. */
326
+ export interface IFlexRecordLogHead {
327
+ revision: number;
328
+ contentRoot: string;
329
+ }
330
+
317
331
  type TDeletionSelector =
318
332
  | { recordId: string; domain: TFlexRecordDomain }
319
333
  | { ownerKey: string; domain: TFlexRecordDomain }
@@ -326,6 +340,31 @@ const deletionBatchSize = 4;
326
340
  const digest = (value: string): string =>
327
341
  plugins.crypto.createHash('sha256').update(value, 'utf8').digest('hex');
328
342
 
343
+ const logBaseRoot = (text: string): string => digest(JSON.stringify(['flex-record-log-v1', 'base', digest(text)]));
344
+ const logChangeRoot = (root: string, text: string): string =>
345
+ digest(JSON.stringify(['flex-record-log-v1', 'change', root, digest(text)]));
346
+
347
+ /** An older writer may advance a head without knowing these fields; then the root is unqualified. */
348
+ function committedLogRoot(head: FlexRecordDocument, resolved: IResolvedAddress): string | undefined {
349
+ const root = head.contentRoot;
350
+ const revision = head.contentRootRevision;
351
+ const token = head.contentRootWriteToken;
352
+ if (root === undefined || root === null) {
353
+ if (revision !== undefined || token !== undefined) {
354
+ throw new FlexHarnessStoreFormatError(`Incomplete log content commitment at ${resolved.path}.`);
355
+ }
356
+ return undefined;
357
+ }
358
+ if (typeof root !== 'string' || !/^[a-f0-9]{64}$/.test(root)
359
+ || !Number.isSafeInteger(revision) || Number(revision) < 1
360
+ || typeof token !== 'string' || token.length === 0
361
+ || !Number.isSafeInteger(head.revision) || head.revision < 1
362
+ || typeof head.writeToken !== 'string' || head.writeToken.length === 0) {
363
+ throw new FlexHarnessStoreFormatError(`Invalid log content commitment at ${resolved.path}.`);
364
+ }
365
+ return revision === head.revision && token === head.writeToken ? root : undefined;
366
+ }
367
+
329
368
  function splitPayload(text: string): string[] {
330
369
  const chunks: string[] = [];
331
370
  let start = 0;
@@ -511,6 +550,33 @@ export class FlexRecordStore {
511
550
  return this.readVisible(resolved, async () => (await this.loadLog(resolved, log)).value);
512
551
  }
513
552
 
553
+ /** A missing or legacy commitment requires the caller to take the complete log path. */
554
+ public async readLogHead(address: IFlexRecordAddress): Promise<IFlexRecordLogHead | undefined> {
555
+ await this.prepare();
556
+ const resolved = this.resolve(address);
557
+ return this.readVisible(resolved, async () => {
558
+ const head = await this.findHead(resolved);
559
+ if (!head) return undefined;
560
+ const root = committedLogRoot(head, resolved);
561
+ if (head.contentRoot === undefined || head.contentRoot === null) return undefined;
562
+ if (!Number.isSafeInteger(head.revision) || head.revision < 1
563
+ || typeof head.logId !== 'string' || !head.logId
564
+ || typeof head.payloadSha256 !== 'string' || !/^[a-f0-9]{64}$/.test(head.payloadSha256)
565
+ || typeof head.blobId !== 'string' || !head.blobId
566
+ || head.payload !== null || head.chunked !== true
567
+ || !Number.isSafeInteger(head.chunkCount) || head.chunkCount < 1
568
+ || !Number.isSafeInteger(head.changeCount) || head.changeCount < 0
569
+ || !Array.isArray(head.recentChanges)
570
+ || head.recentChanges.some((change) => typeof change !== 'string')
571
+ || head.changeCount < head.recentChanges.length
572
+ || head.recentChanges.reduce((length, change) => length + change.length, 0)
573
+ > FLEX_RECORD_INLINE_CHANGE_CODE_UNITS) {
574
+ throw new FlexHarnessStoreFormatError(`Invalid content commitment at ${resolved.path}.`);
575
+ }
576
+ return root === undefined ? undefined : { revision: head.revision, contentRoot: root };
577
+ });
578
+ }
579
+
514
580
  /**
515
581
  * Saves a change to a log record while its head holds the expected revision. Only the head is
516
582
  * read when the record takes the change; a compaction loads the record and checks the result in
@@ -532,8 +598,9 @@ export class FlexRecordStore {
532
598
  const head = await this.findHead(resolved);
533
599
  actualRevision = head?.revision ?? 0;
534
600
  if (actualRevision !== change.expectedRevision) throw change.conflict(actualRevision);
535
- if (head && this.takesChange(head, text)) {
536
- if (await this.commitChange(resolved, head, revision, text)) return;
601
+ const root = head ? committedLogRoot(head, resolved) : undefined;
602
+ if (head && root && this.takesChange(head, text)) {
603
+ if (await this.commitChange(resolved, head, revision, text, root)) return;
537
604
  continue;
538
605
  }
539
606
  const stored = await this.loadLog(resolved, log);
@@ -881,10 +948,29 @@ export class FlexRecordStore {
881
948
  for (let attempt = 0; attempt < chunkReadAttempts; attempt++) {
882
949
  const head = await this.readHead(resolved);
883
950
  const document = head.document;
884
- if (!document || head.text === undefined) return { document };
885
- if (!document.logId) return { document, value: this.parse(resolved, head.text, log.validate) };
951
+ if (!document) return {};
952
+ const root = committedLogRoot(document, resolved);
953
+ if (head.text === undefined) {
954
+ if (document.contentRoot !== undefined && document.contentRoot !== null) {
955
+ throw new FlexHarnessStoreFormatError(`${resolved.path} has a log commitment without a base.`);
956
+ }
957
+ return { document };
958
+ }
959
+ if (!document.logId) {
960
+ if (document.contentRoot !== undefined && document.contentRoot !== null) {
961
+ throw new FlexHarnessStoreFormatError(`${resolved.path} has a log commitment without a log.`);
962
+ }
963
+ return { document, value: this.parse(resolved, head.text, log.validate) };
964
+ }
886
965
  const changes = await this.readChanges(document);
887
966
  if (changes) {
967
+ if (root !== undefined) {
968
+ let actualRoot = logBaseRoot(head.text);
969
+ for (const change of changes) actualRoot = logChangeRoot(actualRoot, change);
970
+ if (actualRoot !== root) {
971
+ throw new FlexHarnessStoreFormatError(`${resolved.path} has a mismatched log content commitment.`);
972
+ }
973
+ }
888
974
  return { document, value: this.fold(resolved, document, head.text, changes, log) };
889
975
  }
890
976
  const latest = await this.findHead(resolved);
@@ -1007,6 +1093,8 @@ export class FlexRecordStore {
1007
1093
  blobId,
1008
1094
  chunkCount: chunked ? splitPayload(text).length : 0,
1009
1095
  payloadSha256: chunked ? digest(text) : null,
1096
+ ...(log ? { contentRoot: logBaseRoot(text) } : {}),
1097
+ ...(log ? { contentRootRevision: write.revision, contentRootWriteToken: writeToken } : {}),
1010
1098
  logId: log ? writeToken : null,
1011
1099
  changeCount: 0,
1012
1100
  recentChanges: [],
@@ -1015,6 +1103,7 @@ export class FlexRecordStore {
1015
1103
  baseLength: log ? text.length : 0,
1016
1104
  retiredLogId: current.logId ?? null,
1017
1105
  },
1106
+ ...(log ? {} : { $unset: { contentRoot: '', contentRootRevision: '', contentRootWriteToken: '' } }),
1018
1107
  },
1019
1108
  { session: transaction },
1020
1109
  ));
@@ -1046,6 +1135,7 @@ export class FlexRecordStore {
1046
1135
  head: FlexRecordDocument,
1047
1136
  revision: number,
1048
1137
  text: string,
1138
+ root: string,
1049
1139
  ): Promise<boolean> {
1050
1140
  const recentLength = head.recentChanges.reduce((length, data) => length + data.length, 0);
1051
1141
  const page = recentLength + text.length > FLEX_RECORD_INLINE_CHANGE_CODE_UNITS
@@ -1067,8 +1157,8 @@ export class FlexRecordStore {
1067
1157
  const updated = await this.records.atomicUpdate(
1068
1158
  { recordId: resolved.recordId, writeToken: head.writeToken },
1069
1159
  page
1070
- ? { $set: { revision, writeToken, recentChanges: [], lastPageId: page.pageId }, $inc: counts }
1071
- : { $set: { revision, writeToken }, $inc: counts, $push: { recentChanges: text } },
1160
+ ? { $set: { revision, writeToken, contentRoot: logChangeRoot(root, text), contentRootRevision: revision, contentRootWriteToken: writeToken, recentChanges: [], lastPageId: page.pageId }, $inc: counts }
1161
+ : { $set: { revision, writeToken, contentRoot: logChangeRoot(root, text), contentRootRevision: revision, contentRootWriteToken: writeToken }, $inc: counts, $push: { recentChanges: text } },
1072
1162
  { session: transaction },
1073
1163
  );
1074
1164
  if (updated.matchedCount === 1 && page) await this.changes.insert(page, { session: transaction });
@@ -1119,6 +1209,9 @@ export class FlexRecordStore {
1119
1209
  head.blobId = chunk.blobId;
1120
1210
  head.chunkCount = 1;
1121
1211
  head.payloadSha256 = digest(text);
1212
+ head.contentRoot = logBaseRoot(text);
1213
+ head.contentRootRevision = revision;
1214
+ head.contentRootWriteToken = head.writeToken;
1122
1215
  head.logId = head.writeToken;
1123
1216
  head.baseLength = text.length;
1124
1217
  } else {
@@ -56,6 +56,8 @@ All writes in one namespace now contend on its namespace document, not only crea
56
56
 
57
57
  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
58
 
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.
60
+
59
61
  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.
60
62
 
61
63
  A projection or Agent event record that an earlier version wrote whole is read whole, and its next save rewrites it as a base. Versions before 12.0.0 cannot read a base: they fail closed on such a record with `FlexHarnessStoreFormatError` instead of reading the session without its changes, so rolling back to them is unsupported for every session 12.x has saved, as is running them beside 12.x on one database, and they leave the `flexharness_changes` documents in place.