@modelprofile.com/flexharness 4.1.1 → 5.0.0

package/dist_ts/interfaces.d.ts

@@ -817,8 +817,7 @@ export interface IFlexMessageChangedEvent extends IFlexEventBase {
     readonly messageId: string;
     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. */
@@ -826,9 +825,19 @@ 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;
@@ -864,6 +873,6 @@ export interface IFlexErrorInfo {
     message: string;
     code?: string;
 }
-export type TFlexHarnessEvent = IFlexSessionCreatedEvent | IFlexSessionUpdatedEvent | IFlexSessionDeletedEvent | IFlexRunStartedEvent | IFlexMessageChangedEvent | IFlexPartChangedEvent | IFlexPermissionRequestedEvent | IFlexPermissionResolvedEvent | IFlexRunFinishedEvent | IFlexPromptQueueEvent | IFlexSessionHistoryChangedEvent;
+export type TFlexHarnessEvent = IFlexSessionCreatedEvent | IFlexSessionUpdatedEvent | IFlexSessionDeletedEvent | IFlexRunStartedEvent | IFlexMessageChangedEvent | TFlexPartEvent | IFlexPermissionRequestedEvent | IFlexPermissionResolvedEvent | IFlexRunFinishedEvent | IFlexPromptQueueEvent | IFlexSessionHistoryChangedEvent;
 export type TFlexHarnessEventListener = (event: TFlexHarnessEvent) => void;
 export {};

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@modelprofile.com/flexharness",
-  "version": "4.1.1",
+  "version": "5.0.0",
   "private": false,
   "description": "Provider-neutral model-session runtime with durable history, permissions, typed events, and pluggable local or remote tool execution.",
   "main": "dist_ts/index.js",
@@ -22,7 +22,7 @@
     "node": ">=24"
   },
   "dependencies": {
-    "@push.rocks/smartagent": "^5.0.0",
+    "@push.rocks/smartagent": "^5.0.1",
     "@types/json-schema": "7.0.15"
   },
   "devDependencies": {

package/readme.hints.md

@@ -12,6 +12,7 @@ Implementation findings for flexharness.
 ## SmartAgent boundary
 
 - SmartAgent is the canonical private conversation and execution runtime. FlexHarness creates one transactional `AgentSession` per public session and derives its public model, prompt, provider-option, tool-set, and result aliases from SmartAgent exports.
+- Non-empty SmartAgent text and reasoning callback deltas cross the public event boundary immediately and exactly once. Delta events never carry a cumulative part and are not subject to snapshot text truncation.
 - Public prompts remain JSON-safe. URL strings are converted to `URL` instances only at the private SmartAgent invocation boundary.
 - Prompt attachment payloads exist only in canonical private Agent events. Public messages, prompt results, projection snapshots, and events expose only `attachmentType`, source kind, optional media/name, and decoded size when determinable.
 - Resolver calls start in promise continuations so synchronous throws are observed. The first failure aborts the shared internal signal without awaiting an ignoring sibling; detached tool-provider settlement is observed and late handles are closed.
@@ -45,9 +46,9 @@ Implementation findings for flexharness.
 ## Tool output boundary
 
 - Every tool `execute` result and every async-iterable yield is converted to bounded JSON before SmartAgent observes it. Thrown errors and iterator failures are not converted or swallowed.
-- SmartAgent preliminary tool outputs mutate only the run-local running tool part and emit cumulative `part.updated` snapshots. Terminal success replaces them with the authoritative final output; failure, cancellation, and callback overflow remove them before persistence.
+- Every distinct SmartAgent streamed tool output mutates only the run-local running tool part and immediately emits a cumulative `part.updated` snapshot, including the final yielded value. Terminal success replaces it with the authoritative final output; failure, cancellation, and callback overflow remove transient output before persistence.
 - JSON byte limits are propagated through traversal. Large strings never enter normalized output, and array/object traversal stops once the remaining allowance is reserved for deterministic truncation metadata.
-- Model callbacks use bounded synchronous run-local parts. Adjacent text/reasoning deltas coalesce; no per-delta snapshot is written. Callback event, byte, or part overflow aborts internally and is classified as failure, not owner cancellation.
+- Model callbacks use bounded synchronous run-local parts. Source text/reasoning deltas accumulate there without per-delta persistence, while public `part.delta` events retain each exact source delta. Per-part UTF-8 counters are updated incrementally, including correction when a source boundary splits a surrogate pair; cumulative text is never rescanned per token. Callback event, byte, or part overflow aborts internally and is classified as failure, not owner cancellation.
 
 ## Prompt queue boundary
 

package/readme.md

@@ -632,7 +632,7 @@ FlexHarness wraps every provided tool `execute` method before SmartAgent receive
 
 `toolOutputLimits` in the complete setup above bounds traversal depth and encoded bytes. The normalizer enforces its byte allowance incrementally: oversized strings are replaced before entering output, and arrays/objects stop reading entries once only truncation metadata fits.
 
-Streaming callbacks use run-local synchronous state rather than one persistence promise per delta. Adjacent text and reasoning deltas coalesce. Preliminary async-iterable tool outputs appear as bounded cumulative `part.updated` snapshots while the tool remains `running`; only the authoritative `part.completed` output enters the terminal projection, and failed or interrupted tools discard their preliminary output. `callbackLimits` bounds callback events, accumulated output bytes, and part count; overflow aborts internally with `FlexHarnessCallbackOverflowError` and the turn is recorded as failed. Reservation and terminal finalization are the normal persistence checkpoints, with permission state changes as explicit additional checkpoints.
+Streaming callbacks use run-local synchronous state rather than one persistence promise per source delta. Text and reasoning accumulate only in the run-local terminal projection while each source delta remains an immediate exact public event. Every distinct async-iterable tool output appears immediately as a bounded cumulative `part.updated` snapshot while the tool remains `running`, including the final yielded value before completion. Only the authoritative `part.completed` output enters the terminal projection, and failed or interrupted tools discard their transient output. `callbackLimits` bounds callback events, accumulated output bytes, and part count; overflow aborts internally with `FlexHarnessCallbackOverflowError` and the turn is recorded as failed. Reservation and terminal finalization are the normal persistence checkpoints, with permission state changes as explicit additional checkpoints.
 
 Model resolver, tool provider, AgentSession, tool execution, tool callback, tool cleanup, and run-persistence failures cross an untrusted error boundary. By default they become a fixed immutable `FlexHarnessExternalError` before completion rejection, persistence, events, or detached-cleanup reporting. Raw external messages and aggregate members are not retained. A failed `onToolCallFinish` callback stores and accounts for only the bounded projected message; it does not otherwise reject completion, although exceeding the configured callback limits still fails the run. Scope resolution and the initial store load happen before a run exists and remain outside this boundary.
 
@@ -656,7 +656,15 @@ Transactional tool calls persist an execution intent before the tool side effect
 const unsubscribe = harness.subscribe((event) => {
   switch (event.type) {
     case 'part.delta':
-      renderDelta(event.sessionId, event.messageIndex, event.partIndex, event.delta);
+      applyExactDelta(
+        event.sessionId,
+        event.messageIndex,
+        event.partIndex,
+        event.partType,
+        event.delta,
+        event.baseTextUtf8Bytes,
+        event.textUtf8Bytes,
+      );
       break;
     case 'permission.requested':
       showPermission(event.request);
@@ -685,7 +693,15 @@ const unsubscribe = harness.subscribe((event) => {
 unsubscribe();
 ```
 
-Events are discriminated, sequenced, deeply immutable snapshots. Listener exceptions are isolated from runs and other listeners. Every accepted queue entry emits `prompt.queued` and exactly one `prompt.finished`. Durable promotion additionally emits `prompt.started`, and actual model preparation emits `prompt.running`; cancellation or failure can omit either intermediate event. Existing durable run/message terminal events precede `prompt.finished`. Every callback-backed streamed text part emits exactly one `part.completed` event before the corresponding `run.finished` event. Every `part.started`, `part.delta`, `part.updated`, and `part.completed` event carries zero-based `messageIndex` and `partIndex` coordinates from the session's authoritative message and part sequences. `part.updated` is a cumulative replacement snapshot for running tool output or metadata, not a text delta. `session.history.changed` carries `direction: 'undo' | 'redo' | 'branch'`; `runId` is present for undo and redo. Events contain public IDs and snapshots only; they do not expose prompt payloads, the resolved scope object, storage key, model object, provider options, or raw storage key.
+Events are discriminated, deeply immutable values with one global sequence within each `FlexHarness` instance. Listener exceptions are isolated from runs and other listeners. Every accepted queue entry emits `prompt.queued` and exactly one `prompt.finished`. Durable promotion additionally emits `prompt.started`, and actual model preparation emits `prompt.running`; cancellation or failure can omit either intermediate event. Existing durable run/message terminal events precede `prompt.finished`. Every callback-backed streamed text part emits exactly one `part.completed` event before the corresponding `run.finished` event. Every `part.started`, `part.delta`, `part.updated`, and `part.completed` event carries zero-based `messageIndex` and `partIndex` coordinates from the session's authoritative message and part sequences.
+
+`part.started`, `part.updated`, and `part.completed` are snapshot events with a complete immutable `part`. A newly streamed text part emits `part.started` with empty text before its first delta; reasoning parts also start empty. `part.delta` is a separate delta-only event: it has no cumulative `part`, and carries `partType`, the required exact source `delta`, and `baseTextUtf8Bytes`/`textUtf8Bytes` for the cumulative text before and after that delta. The counters remain correct when a UTF-16 surrogate pair is split across callbacks. Exact deltas are never truncated, including a single delta above the 96 KiB message-transfer text limit. `part.updated` remains a cumulative replacement snapshot for running tool output or metadata, not a text delta. `session.history.changed` carries `direction: 'undo' | 'redo' | 'branch'`; `runId` is present for undo and redo. Events contain public IDs, exact delta payloads, and public snapshots only; they do not expose prompt payloads, the resolved scope object, storage key, model object, provider options, or raw storage key.
+
+Part events narrow through the exported `TFlexPartEvent` union. `IFlexPartEventBase` contains their shared coordinates, `IFlexPartSnapshotEvent` owns snapshot events and their complete `part`, and `IFlexPartDeltaEvent` owns exact delta-only events and their UTF-8 counters.
+
+### Migrating Part Events to 5.x
+
+Version `5.x` replaces cumulative `part.delta` payloads with the exact delta-only contract above. Consumers must stop reading `event.part` from `part.delta`; use `event.partType`, `event.delta`, `event.baseTextUtf8Bytes`, and `event.textUtf8Bytes`, then hydrate or settle from the complete `part` carried by snapshot events. `IFlexPartChangedEvent` has been removed; use `TFlexPartEvent`, `IFlexPartSnapshotEvent`, or `IFlexPartDeltaEvent` according to the required narrowing. New streamed text and reasoning parts start with empty text, so consumers must apply subsequent deltas in sequence within that harness instance.
 
 ## Stores
 

package/ts/00_commitinfo_data.ts

@@ -3,6 +3,6 @@
  */
 export const commitinfo = {
   name: '@modelprofile.com/flexharness',
-  version: '4.1.1',
+  version: '5.0.0',
   description: 'Provider-neutral model-session runtime with durable history, permissions, typed events, and pluggable local or remote tool execution.'
 }

package/ts/classes.flexharness.ts

@@ -42,7 +42,7 @@ import type {
   IFlexMessagePage,
   IFlexMessagePageOptions,
   IFlexModelIdentity,
-  IFlexPartChangedEvent,
+  IFlexPartSnapshotEvent,
   IFlexPermissionRequest,
   IFlexPermissionRequestInput,
   IFlexPermissionSnapshot,
@@ -321,6 +321,7 @@ interface IActiveRun {
   callbackEventCount: number;
   callbackOutputBytes: number;
   callbackParts: TFlexMessagePart[];
+  partTextUtf8Bytes: Map<string, number>;
   callbacksClosed: boolean;
   reasoningPartIds: Map<string, string>;
   toolPartIds: Map<string, string>;
@@ -3110,6 +3111,7 @@ export class FlexHarness<TScope = unknown> {
       callbackEventCount: 0,
       callbackOutputBytes: 0,
       callbackParts: [],
+      partTextUtf8Bytes: new Map(),
       callbacksClosed: false,
       reasoningPartIds: new Map(),
       toolPartIds: new Map(),
@@ -6062,14 +6064,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 +6097,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 +6108,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 +6129,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 +6265,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
     ) {
@@ -9329,20 +9386,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 +9398,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

@@ -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