@modelprofile.com/flexharness 4.1.2 → 5.1.0

package/dist_ts/interfaces.d.ts

@@ -160,7 +160,7 @@ export interface IFlexSlashCommandDescriptor {
     unavailableReason?: string;
     workspaceReversion: TFlexSlashCommandWorkspaceReversion;
 }
-export interface IFlexSlashCommandHandlerContext<TScope> {
+export interface IFlexSlashCommandHandlerContext<TScope> extends IFlexSessionGeneration {
     readonly scopeId: string;
     readonly scope: TScope;
     readonly storageKey: string;
@@ -292,7 +292,7 @@ export interface IFlexPermissionRequest extends IFlexPermissionRequestInput {
     createdAt: string;
 }
 export type TFlexPermissionDecision = 'once' | 'always' | 'reject';
-export interface IFlexToolProviderContext<TScope> {
+export interface IFlexToolProviderContext<TScope> extends IFlexSessionGeneration {
     scopeId: string;
     scope: TScope;
     sessionId: string;
@@ -309,7 +309,7 @@ export interface IFlexToolHandle {
 export interface IFlexToolProvider<TScope> {
     provideTools(context: IFlexToolProviderContext<TScope>): Promise<IFlexToolHandle | undefined> | IFlexToolHandle | undefined;
 }
-export interface IFlexResourceToolProviderResolverContext<TScope> {
+export interface IFlexResourceToolProviderResolverContext<TScope> extends IFlexSessionGeneration {
     scopeId: string;
     scope: TScope;
     sessionId: string;
@@ -594,7 +594,7 @@ export declare const FLEX_REVERSION_MAX_AFFECTED_WORKSPACES = 64;
 export declare const FLEX_REVERSION_WORKSPACE_ID_MAX_BYTES = 512;
 export declare const FLEX_REVERSION_WORKSPACE_LABEL_MAX_BYTES = 2048;
 export declare 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;
@@ -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.2",
+  "version": "5.1.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",

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.
@@ -47,7 +48,7 @@ Implementation findings for flexharness.
 - 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.
 - 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

@@ -122,7 +122,7 @@ const harness = new FlexHarness<IProjectScope>({
 });
 ```
 
-`modelRegistry`, `projectRegistry`, `createProjectTools`, and `closeProjectTools` in this example are application-owned integrations. FlexHarness passes the same run `AbortSignal` to the model resolver and tool provider.
+`modelRegistry`, `projectRegistry`, `createProjectTools`, and `closeProjectTools` in this example are application-owned integrations. FlexHarness passes the same run `AbortSignal` to the model resolver and tool provider. Every application and resource tool-provider context also carries the required canonical `sessionGenerationId` and `sessionGenerationSequence`, allowing host operations to authorize the exact session generation rather than a reusable session ID alone.
 
 ## Resource Tool Providers
 
@@ -130,10 +130,19 @@ const harness = new FlexHarness<IProjectScope>({
 
 ```typescript
 resourceToolProviderResolver: {
-  async resolveResourceToolProviders({ scope, sessionId, runId, signal }) {
+  async resolveResourceToolProviders({
+    scope,
+    sessionId,
+    sessionGenerationId,
+    sessionGenerationSequence,
+    runId,
+    signal,
+  }) {
     const attachments = await resourceRegistry.listAttached({
       scope,
       sessionId,
+      sessionGenerationId,
+      sessionGenerationSequence,
       runId,
       signal,
     });
@@ -146,7 +155,7 @@ resourceToolProviderResolver: {
 },
 ```
 
-Each descriptor uses the existing `IFlexToolProvider<TScope>` contract. Its provider receives the normal run context and must return a fresh run-scoped handle. The original `toolProvider` remains optional and its tool names remain unchanged. Resource tool names are deterministic and bounded:
+Each descriptor uses the existing `IFlexToolProvider<TScope>` contract. Its provider receives the normal run context and must return a fresh run-scoped handle. The resource resolver context carries the same required canonical session generation as the tool-provider contexts. The original `toolProvider` remains optional and its tool names remain unchanged. Resource tool names are deterministic and bounded:
 
 1. `resourceIdentity` is the lowercase hexadecimal SHA-256 of `JSON.stringify([resourceId, attachmentRevision])`.
 2. The namespace is `resource_` plus the first 16 digest characters.
@@ -438,12 +447,24 @@ const harness = new FlexHarness({
     {
       name: 'refresh-index',
       description: 'Refresh the application-owned workspace index.',
-      async handler({ scopeId, scope, storageKey, sessionId, rawArguments, arguments, signal }) {
+      async handler({
+        scopeId,
+        scope,
+        storageKey,
+        sessionId,
+        sessionGenerationId,
+        sessionGenerationSequence,
+        rawArguments,
+        arguments,
+        signal,
+      }) {
         return indexer.refresh({
           scopeId,
           scope,
           storageKey,
           sessionId,
+          sessionGenerationId,
+          sessionGenerationSequence,
           rawArguments,
           arguments,
           signal,
@@ -470,7 +491,7 @@ Session metadata archival through `updateSession(..., { archived: true })` only
 
 Templates replace every `$ARGUMENTS` with untouched raw argument text. `$1` through the highest referenced positional placeholder use tokenized arguments, with the highest position receiving all remaining tokens joined by spaces. Missing positions become empty. A template with no placeholders appends non-empty raw arguments after a blank line. `/init` uses the OpenCode 1.18.15 `AGENTS.md` initialization prompt with provider-neutral active-workspace wording.
 
-Handler context is frozen and contains only the resolved scope identity, session identity, raw and tokenized arguments, and an `AbortSignal`. Handler results are converted with the configured `toolOutputLimits`; `void` becomes JSON `null`. Handler failures use `externalErrorProjector` with source `slashCommand`. Same-session command overlap is rejected, including reentry from a handler. Scope retirement and disposal abort and await active handlers; prompt-admission commands transfer immediately to the normal prompt lifecycle.
+Handler context is frozen and contains only the resolved scope identity, session identity, required canonical `sessionGenerationId` and `sessionGenerationSequence`, raw and tokenized arguments, and an `AbortSignal`. Handler results are converted with the configured `toolOutputLimits`; `void` becomes JSON `null`. Handler failures use `externalErrorProjector` with source `slashCommand`. Same-session command overlap is rejected, including reentry from a handler. Scope retirement and disposal abort and await active handlers; prompt-admission commands transfer immediately to the normal prompt lifecycle.
 
 ### Workspace Reversion Provider
 
@@ -557,7 +578,7 @@ for (const group of info.groups) {
 
 The immutable result exposes `undoAvailable`, `redoAvailable`, and groups classified as `candidate`, `barrier`, or `no-change`. Group metadata contains at most 64 unique affected workspaces; `affectedWorkspacesTruncated` is `true` when additional unique descriptors were omitted. It never includes capture IDs or provider references.
 
-`workspaceSnapshots` is application-owned. Every context contains `scopeId`, `scope`, `storageKey`, `sessionId`, `runId`, deterministic `captureId`, and an `AbortSignal`. Apply contexts additionally contain the normalized `reference`, deterministic per-segment `operationId`, and `direction`; release contexts contain the reference.
+`workspaceSnapshots` is application-owned. Every context contains `scopeId`, `scope`, `storageKey`, `sessionId`, the required canonical `sessionGenerationId` and `sessionGenerationSequence`, `runId`, deterministic `captureId`, and an `AbortSignal`. Apply contexts additionally contain the normalized `reference`, deterministic per-segment `operationId`, and `direction`; release contexts contain the reference. Deleted-session recovery retains the same generation from the durable tombstone, so providers can reject callbacks from an older same-ID generation.
 
 The protocol is durable and inspectable:
 
@@ -632,7 +653,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. 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.
+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 +677,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 +714,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.2',
+  version: '5.1.0',
   description: 'Provider-neutral model-session runtime with durable history, permissions, typed events, and pluggable local or remote tool execution.'
 }