@modelprofile.com/flexharness 4.1.2 → 5.1.0

package/ts/classes.flexharness.ts

@@ -42,7 +42,7 @@ import type {
   IFlexMessagePage,
   IFlexMessagePageOptions,
   IFlexModelIdentity,
-  IFlexPartChangedEvent,
+  IFlexPartSnapshotEvent,
   IFlexPermissionRequest,
   IFlexPermissionRequestInput,
   IFlexPermissionSnapshot,
@@ -74,6 +74,7 @@ import type {
   IFlexSchedulePromptOptions,
   IFlexScopeSnapshot,
   IFlexSession,
+  IFlexSessionGeneration,
   IFlexSessionReversionGroup,
   IFlexSessionReversionInfo,
   IFlexSessionTombstone,
@@ -321,6 +322,7 @@ interface IActiveRun {
   callbackEventCount: number;
   callbackOutputBytes: number;
   callbackParts: TFlexMessagePart[];
+  partTextUtf8Bytes: Map<string, number>;
   callbacksClosed: boolean;
   reasoningPartIds: Map<string, string>;
   toolPartIds: Map<string, string>;
@@ -518,7 +520,7 @@ function requireSessionGeneration(
     IFlexSession | IFlexSessionTombstone,
     'sessionGenerationId' | 'sessionGenerationSequence'
   >,
-): { sessionGenerationId: string; sessionGenerationSequence: number } {
+): IFlexSessionGeneration {
   if (
     !session.sessionGenerationId
     || !Number.isSafeInteger(session.sessionGenerationSequence)
@@ -1848,6 +1850,7 @@ export class FlexHarness<TScope = unknown> {
           scope,
           storageKey: state.storageKey,
           sessionId: stored.session.sessionId,
+          ...requireSessionGeneration(stored.session),
           rawArguments,
           arguments: arguments_,
           signal,
@@ -2511,6 +2514,7 @@ export class FlexHarness<TScope = unknown> {
   ): Promise<void> {
     const pending = stored.pendingReversion;
     if (pending?.kind !== 'apply') return;
+    const sessionGeneration = requireSessionGeneration(stored.session);
     const segmentMap = new Map(stored.reversionSegments.map((segment) => [segment.runId, segment]));
     if (
       pending.segmentRunIds.some((runId) =>
@@ -2551,6 +2555,7 @@ export class FlexHarness<TScope = unknown> {
           scope,
           storageKey: state.storageKey,
           sessionId: stored.session.sessionId,
+          ...sessionGeneration,
           runId,
           captureId,
           reference: cloneSerializable(reference),
@@ -2684,6 +2689,7 @@ export class FlexHarness<TScope = unknown> {
       scopeId,
       scope,
       stored.session.sessionId,
+      requireSessionGeneration(stored.session),
       pending.runId,
       pending.captureId,
       pending.state === 'prepared' ? 'finalizing' : pending.state,
@@ -3110,6 +3116,7 @@ export class FlexHarness<TScope = unknown> {
       callbackEventCount: 0,
       callbackOutputBytes: 0,
       callbackParts: [],
+      partTextUtf8Bytes: new Map(),
       callbacksClosed: false,
       reasoningPartIds: new Map(),
       toolPartIds: new Map(),
@@ -3997,6 +4004,7 @@ export class FlexHarness<TScope = unknown> {
       scopeId: run.scopeId,
       scope: run.scope as TScope,
       sessionId: run.sessionId,
+      ...requireSessionGeneration(run.stored.session),
       runId: run.runId,
       ...resolverRelationship,
       signal,
@@ -4965,6 +4973,7 @@ export class FlexHarness<TScope = unknown> {
       scope: run.scope as TScope,
       storageKey: run.state.storageKey,
       sessionId: run.sessionId,
+      ...requireSessionGeneration(run.stored.session),
       runId: run.runId,
       captureId,
       signal,
@@ -4999,6 +5008,7 @@ export class FlexHarness<TScope = unknown> {
     scope: TScope,
     storageKey: string,
     sessionId: string,
+    sessionGeneration: Readonly<IFlexSessionGeneration>,
     runId: string,
     captureId: string,
   ): Promise<TNormalizedCaptureInspection> {
@@ -5009,6 +5019,7 @@ export class FlexHarness<TScope = unknown> {
         scope,
         storageKey,
         sessionId,
+        ...sessionGeneration,
         runId,
         captureId,
         signal,
@@ -5042,6 +5053,7 @@ export class FlexHarness<TScope = unknown> {
     scope: TScope,
     storageKey: string,
     sessionId: string,
+    sessionGeneration: Readonly<IFlexSessionGeneration>,
     runId: string,
     captureId: string,
   ): Promise<TFlexTurnReversionFinalizedOutcome> {
@@ -5051,6 +5063,7 @@ export class FlexHarness<TScope = unknown> {
         scope,
         storageKey,
         sessionId,
+        ...sessionGeneration,
         runId,
         captureId,
         signal,
@@ -5070,6 +5083,7 @@ export class FlexHarness<TScope = unknown> {
     scopeId: string,
     scope: TScope,
     sessionId: string,
+    sessionGeneration: Readonly<IFlexSessionGeneration>,
     runId: string,
     captureId: string,
     durableState: 'preparing' | 'prepared' | 'finalizing',
@@ -5081,6 +5095,7 @@ export class FlexHarness<TScope = unknown> {
         scope,
         state.storageKey,
         sessionId,
+        sessionGeneration,
         runId,
         captureId,
       );
@@ -5105,6 +5120,7 @@ export class FlexHarness<TScope = unknown> {
           scope,
           state.storageKey,
           sessionId,
+          sessionGeneration,
           runId,
           captureId,
         );
@@ -5114,6 +5130,7 @@ export class FlexHarness<TScope = unknown> {
           scope,
           state.storageKey,
           sessionId,
+          sessionGeneration,
           runId,
           captureId,
         );
@@ -5266,6 +5283,7 @@ export class FlexHarness<TScope = unknown> {
           run.scope as TScope,
           run.state.storageKey,
           run.sessionId,
+          requireSessionGeneration(run.stored.session),
           run.runId,
           captureId,
         );
@@ -5347,6 +5365,7 @@ export class FlexHarness<TScope = unknown> {
       run.scopeId,
       run.scope as TScope,
       run.sessionId,
+      requireSessionGeneration(run.stored.session),
       run.runId,
       captureId,
       pending.state === 'prepared' ? 'finalizing' : pending.state,
@@ -5596,6 +5615,7 @@ export class FlexHarness<TScope = unknown> {
       }
       return;
     }
+    const sessionGeneration = requireSessionGeneration(stored.session);
     while (stored.pendingReversionReleases.length > 0) {
       const release = stored.pendingReversionReleases[0];
       if (this.reversionProviderProtocolVersion() !== release.protocolVersion) {
@@ -5610,6 +5630,7 @@ export class FlexHarness<TScope = unknown> {
             scope,
             storageKey: state.storageKey,
             sessionId: stored.session.sessionId,
+            ...sessionGeneration,
             runId: release.runId,
             captureId: release.captureId,
             reference: cloneSerializable(release.reference),
@@ -5647,11 +5668,13 @@ export class FlexHarness<TScope = unknown> {
   private async releaseDeletedSessionReversions(
     state: IStorageState,
     storageKey: string,
-    sessionId: string,
+    tombstone: IFlexSessionTombstone,
     scopeId: string,
     scope: TScope,
     stored?: IStoredSessionState,
   ): Promise<void> {
+    const sessionId = tombstone.sessionId;
+    const sessionGeneration = requireSessionGeneration(stored?.session ?? tombstone);
     if (stored) await stored.projectionQueue;
     let durableProjection = await this.stores.projections.load(storageKey, sessionId);
     if (!durableProjection) return;
@@ -5710,6 +5733,7 @@ export class FlexHarness<TScope = unknown> {
               scope,
               storageKey,
               sessionId,
+              ...sessionGeneration,
               runId,
               captureId,
               reference: cloneSerializable(reference),
@@ -5823,6 +5847,7 @@ export class FlexHarness<TScope = unknown> {
           scope,
           storageKey,
           sessionId,
+          sessionGeneration,
           capture.runId,
           capture.captureId,
         );
@@ -5852,6 +5877,7 @@ export class FlexHarness<TScope = unknown> {
             scope,
             storageKey,
             sessionId,
+            sessionGeneration,
             capture.runId,
             capture.captureId,
           );
@@ -5861,6 +5887,7 @@ export class FlexHarness<TScope = unknown> {
             scope,
             storageKey,
             sessionId,
+            sessionGeneration,
             capture.runId,
             capture.captureId,
           );
@@ -5926,6 +5953,7 @@ export class FlexHarness<TScope = unknown> {
               scope,
               storageKey,
               sessionId,
+              ...sessionGeneration,
               runId: release.runId,
               captureId: release.captureId,
               reference: cloneSerializable(release.reference),
@@ -6062,14 +6090,25 @@ export class FlexHarness<TScope = unknown> {
     if (!run || !delta) return;
     const lastPart = run.callbackParts.at(-1);
     const created = lastPart?.type !== 'text';
-    if (!this.reserveCallbackCapacity(run, created ? 2 : 1, Buffer.byteLength(delta), created ? 1 : 0)) return;
     const part = lastPart?.type === 'text'
       ? lastPart
       : { partId: plugins.crypto.randomUUID(), type: 'text' as const, text: '' };
-    if (created) run.callbackParts.push(part);
+    const accounting = this.textAppendAccounting(run, part, delta, created);
+    if (!accounting) return;
+    if (!this.reserveCallbackCapacity(
+      run,
+      created ? 2 : 1,
+      accounting.textUtf8Bytes - accounting.baseTextUtf8Bytes,
+      created ? 1 : 0,
+    )) return;
+    if (created) {
+      run.callbackParts.push(part);
+      run.partTextUtf8Bytes.set(part.partId, 0);
+      this.emitPartEvent(run, 'part.started', part);
+    }
     part.text += delta;
-    if (created) this.emitPartEvent(run, 'part.started', part);
-    this.emitPartEvent(run, 'part.delta', part, delta);
+    run.partTextUtf8Bytes.set(part.partId, accounting.textUtf8Bytes);
+    this.emitPartDeltaEvent(run, part, delta, accounting);
   }
 
   private onReasoningStart(state: IStorageState, sessionId: string, id: string): void {
@@ -6084,6 +6123,7 @@ export class FlexHarness<TScope = unknown> {
     };
     run.reasoningPartIds.set(id, part.partId);
     run.callbackParts.push(part);
+    run.partTextUtf8Bytes.set(part.partId, 0);
     this.emitPartEvent(run, 'part.started', part);
   }
 
@@ -6094,9 +6134,17 @@ export class FlexHarness<TScope = unknown> {
     const partId = run.reasoningPartIds.get(id);
     const part = run.callbackParts.find((entry) => entry.partId === partId && entry.type === 'reasoning');
     if (!part || part.type !== 'reasoning' || part.status !== 'running') return;
-    if (!this.reserveCallbackCapacity(run, 1, Buffer.byteLength(delta), 0)) return;
+    const accounting = this.textAppendAccounting(run, part, delta);
+    if (!accounting) return;
+    if (!this.reserveCallbackCapacity(
+      run,
+      1,
+      accounting.textUtf8Bytes - accounting.baseTextUtf8Bytes,
+      0,
+    )) return;
     part.text += delta;
-    this.emitPartEvent(run, 'part.delta', part, delta);
+    run.partTextUtf8Bytes.set(part.partId, accounting.textUtf8Bytes);
+    this.emitPartDeltaEvent(run, part, delta, accounting);
   }
 
   private onReasoningEnd(state: IStorageState, sessionId: string, id: string, text: string): void {
@@ -6107,12 +6155,44 @@ export class FlexHarness<TScope = unknown> {
     const part = run.callbackParts.find((entry) => entry.partId === partId && entry.type === 'reasoning');
     if (!part || part.type !== 'reasoning' || part.status !== 'running') return;
     const missingText = part.text ? '' : text;
-    if (!this.reserveCallbackCapacity(run, 1, Buffer.byteLength(missingText), 0)) return;
-    if (missingText) part.text = missingText;
+    const missingTextUtf8Bytes = Buffer.byteLength(missingText, 'utf8');
+    if (!this.reserveCallbackCapacity(run, 1, missingTextUtf8Bytes, 0)) return;
+    if (missingText) {
+      part.text = missingText;
+      run.partTextUtf8Bytes.set(part.partId, missingTextUtf8Bytes);
+    }
     part.status = 'completed';
     this.emitPartEvent(run, 'part.completed', part);
   }
 
+  private textAppendAccounting(
+    run: IActiveRun,
+    part: Extract<TFlexMessagePart, { type: 'text' | 'reasoning' }>,
+    delta: string,
+    created = false,
+  ): { baseTextUtf8Bytes: number; textUtf8Bytes: number } | undefined {
+    const baseTextUtf8Bytes = created ? 0 : run.partTextUtf8Bytes.get(part.partId);
+    if (baseTextUtf8Bytes === undefined) {
+      throw new Error('Flex part text byte accounting is unavailable.');
+    }
+    const trailingCodeUnit = part.text.charCodeAt(part.text.length - 1);
+    const leadingCodeUnit = delta.charCodeAt(0);
+    const joinsSurrogatePair = trailingCodeUnit >= 0xD800
+      && trailingCodeUnit <= 0xDBFF
+      && leadingCodeUnit >= 0xDC00
+      && leadingCodeUnit <= 0xDFFF;
+    const textUtf8Bytes = baseTextUtf8Bytes
+      + Buffer.byteLength(delta, 'utf8')
+      - (joinsSurrogatePair ? 2 : 0);
+    if (!Number.isSafeInteger(textUtf8Bytes)) {
+      this.failCallback(run, this.trustInternalError(new FlexHarnessCallbackOverflowError(
+        'Callback text byte accounting exceeded the safe integer range.',
+      )));
+      return undefined;
+    }
+    return { baseTextUtf8Bytes, textUtf8Bytes };
+  }
+
   private onToolStart(
     state: IStorageState,
     sessionId: string,
@@ -6211,7 +6291,10 @@ export class FlexHarness<TScope = unknown> {
     const nextOutputBytes = run.callbackOutputBytes + outputBytes;
     const nextParts = run.callbackParts.length + partCount;
     if (
-      nextEvents > this.callbackLimits.maxEvents
+      !Number.isSafeInteger(nextEvents)
+      || !Number.isSafeInteger(nextOutputBytes)
+      || !Number.isSafeInteger(nextParts)
+      || nextEvents > this.callbackLimits.maxEvents
       || nextOutputBytes > this.callbackLimits.maxOutputBytes
       || nextParts > this.callbackLimits.maxParts
     ) {
@@ -6650,6 +6733,7 @@ export class FlexHarness<TScope = unknown> {
       scopeId: context.scopeId,
       scope: context.scope,
       sessionId: context.sessionId,
+      ...requireSessionGeneration(run.stored.session),
       runId: context.runId,
       ...(context.parentSessionId === undefined ? {} : { parentSessionId: context.parentSessionId }),
       ...(context.agent === undefined ? {} : { agent: context.agent }),
@@ -7059,7 +7143,7 @@ export class FlexHarness<TScope = unknown> {
             await this.releaseDeletedSessionReversions(
               state,
               storageKey,
-              tombstone.sessionId,
+              tombstone,
               scopeId,
               scope,
             );
@@ -8305,7 +8389,7 @@ export class FlexHarness<TScope = unknown> {
         await this.releaseDeletedSessionReversions(
           state,
           state.storageKey,
-          sessionId,
+          tombstone,
           releaseContext.scopeId,
           releaseContext.scope,
           retained?.stored,
@@ -9329,20 +9413,10 @@ export class FlexHarness<TScope = unknown> {
 
   private emitPartEvent(
     run: IActiveRun,
-    type: IFlexPartChangedEvent['type'],
+    type: IFlexPartSnapshotEvent['type'],
     part: TFlexMessagePart,
-    delta?: string,
   ): void {
-    const messageIndex = run.stored.messages.findIndex(
-      (message) => message.messageId === run.assistantMessageId,
-    );
-    const partIndex = run.callbackParts.findIndex((entry) => entry.partId === part.partId);
-    if (
-      messageIndex < 0
-      || run.stored.messages[messageIndex]?.messageId !== run.assistantMessageId
-      || partIndex < 0
-      || run.callbackParts[partIndex]?.partId !== part.partId
-    ) throw new Error('Flex part event source coordinates are unavailable.');
+    const { messageIndex, partIndex } = this.partEventCoordinates(run, part.partId);
     this.emitEvent(run.scopeId, run.sessionId, {
       type,
       runId: run.runId,
@@ -9351,10 +9425,46 @@ export class FlexHarness<TScope = unknown> {
       partId: part.partId,
       partIndex,
       part: publicSnapshot(part),
-      ...(delta === undefined ? {} : { delta: truncateUtf8(delta, maxTransferTextBytes) }),
     });
   }
 
+  private emitPartDeltaEvent(
+    run: IActiveRun,
+    part: Extract<TFlexMessagePart, { type: 'text' | 'reasoning' }>,
+    delta: string,
+    accounting: { baseTextUtf8Bytes: number; textUtf8Bytes: number },
+  ): void {
+    const { messageIndex, partIndex } = this.partEventCoordinates(run, part.partId);
+    this.emitEvent(run.scopeId, run.sessionId, {
+      type: 'part.delta',
+      runId: run.runId,
+      messageId: run.assistantMessageId,
+      messageIndex,
+      partId: part.partId,
+      partIndex,
+      partType: part.type,
+      delta,
+      ...accounting,
+    });
+  }
+
+  private partEventCoordinates(
+    run: IActiveRun,
+    partId: string,
+  ): { messageIndex: number; partIndex: number } {
+    const messageIndex = run.stored.messages.findIndex(
+      (message) => message.messageId === run.assistantMessageId,
+    );
+    const partIndex = run.callbackParts.findIndex((entry) => entry.partId === partId);
+    if (
+      messageIndex < 0
+      || run.stored.messages[messageIndex]?.messageId !== run.assistantMessageId
+      || partIndex < 0
+      || run.callbackParts[partIndex]?.partId !== partId
+    ) throw new Error('Flex part event source coordinates are unavailable.');
+    return { messageIndex, partIndex };
+  }
+
   private emitEvent(scopeId: string, sessionId: string, details: TEventDetails): void {
     const event = deepFreeze(cloneSerializable({
       eventId: plugins.crypto.randomUUID(),

package/ts/interfaces.ts

@@ -207,7 +207,7 @@ export interface IFlexSlashCommandDescriptor {
   workspaceReversion: TFlexSlashCommandWorkspaceReversion;
 }
 
-export interface IFlexSlashCommandHandlerContext<TScope> {
+export interface IFlexSlashCommandHandlerContext<TScope> extends IFlexSessionGeneration {
   readonly scopeId: string;
   readonly scope: TScope;
   readonly storageKey: string;
@@ -386,7 +386,7 @@ export interface IFlexPermissionRequest extends IFlexPermissionRequestInput {
 
 export type TFlexPermissionDecision = 'once' | 'always' | 'reject';
 
-export interface IFlexToolProviderContext<TScope> {
+export interface IFlexToolProviderContext<TScope> extends IFlexSessionGeneration {
   scopeId: string;
   scope: TScope;
   sessionId: string;
@@ -408,7 +408,7 @@ export interface IFlexToolProvider<TScope> {
   ): Promise<IFlexToolHandle | undefined> | IFlexToolHandle | undefined;
 }
 
-export interface IFlexResourceToolProviderResolverContext<TScope> {
+export interface IFlexResourceToolProviderResolverContext<TScope> extends IFlexSessionGeneration {
   scopeId: string;
   scope: TScope;
   sessionId: string;
@@ -793,7 +793,7 @@ export const FLEX_REVERSION_WORKSPACE_ID_MAX_BYTES = 512;
 export const FLEX_REVERSION_WORKSPACE_LABEL_MAX_BYTES = 2048;
 export const FLEX_REVERSION_REASON_CODE_MAX_BYTES = 128;
 
-export interface IFlexTurnReversionBaseContext<TScope> {
+export interface IFlexTurnReversionBaseContext<TScope> extends IFlexSessionGeneration {
   readonly scopeId: string;
   readonly scope: TScope;
   readonly storageKey: string;
@@ -1107,8 +1107,7 @@ export interface IFlexMessageChangedEvent extends IFlexEventBase {
   readonly message: IFlexMessage;
 }
 
-export interface IFlexPartChangedEvent extends IFlexEventBase {
-  readonly type: 'part.started' | 'part.delta' | 'part.updated' | 'part.completed';
+export interface IFlexPartEventBase extends IFlexEventBase {
   readonly runId: string;
   readonly messageId: string;
   /** Zero-based position in the session's authoritative message sequence. */
@@ -1116,10 +1115,23 @@ export interface IFlexPartChangedEvent extends IFlexEventBase {
   readonly partId: string;
   /** Zero-based position in the message's authoritative part sequence. */
   readonly partIndex: number;
+}
+
+export interface IFlexPartSnapshotEvent extends IFlexPartEventBase {
+  readonly type: 'part.started' | 'part.updated' | 'part.completed';
   readonly part: TFlexMessagePart;
-  readonly delta?: string;
 }
 
+export interface IFlexPartDeltaEvent extends IFlexPartEventBase {
+  readonly type: 'part.delta';
+  readonly partType: 'text' | 'reasoning';
+  readonly delta: string;
+  readonly baseTextUtf8Bytes: number;
+  readonly textUtf8Bytes: number;
+}
+
+export type TFlexPartEvent = IFlexPartSnapshotEvent | IFlexPartDeltaEvent;
+
 export interface IFlexPermissionRequestedEvent extends IFlexEventBase {
   readonly type: 'permission.requested';
   readonly runId: string;
@@ -1167,7 +1179,7 @@ export type TFlexHarnessEvent =
   | IFlexSessionDeletedEvent
   | IFlexRunStartedEvent
   | IFlexMessageChangedEvent
-  | IFlexPartChangedEvent
+  | TFlexPartEvent
   | IFlexPermissionRequestedEvent
   | IFlexPermissionResolvedEvent
   | IFlexRunFinishedEvent