@modelprofile.com/flexharness 5.0.0 → 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;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@modelprofile.com/flexharness",
-  "version": "5.0.0",
+  "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.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:
 

package/ts/00_commitinfo_data.ts

@@ -3,6 +3,6 @@
  */
 export const commitinfo = {
   name: '@modelprofile.com/flexharness',
-  version: '5.0.0',
+  version: '5.1.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

@@ -74,6 +74,7 @@ import type {
   IFlexSchedulePromptOptions,
   IFlexScopeSnapshot,
   IFlexSession,
+  IFlexSessionGeneration,
   IFlexSessionReversionGroup,
   IFlexSessionReversionInfo,
   IFlexSessionTombstone,
@@ -519,7 +520,7 @@ function requireSessionGeneration(
     IFlexSession | IFlexSessionTombstone,
     'sessionGenerationId' | 'sessionGenerationSequence'
   >,
-): { sessionGenerationId: string; sessionGenerationSequence: number } {
+): IFlexSessionGeneration {
   if (
     !session.sessionGenerationId
     || !Number.isSafeInteger(session.sessionGenerationSequence)
@@ -1849,6 +1850,7 @@ export class FlexHarness<TScope = unknown> {
           scope,
           storageKey: state.storageKey,
           sessionId: stored.session.sessionId,
+          ...requireSessionGeneration(stored.session),
           rawArguments,
           arguments: arguments_,
           signal,
@@ -2512,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) =>
@@ -2552,6 +2555,7 @@ export class FlexHarness<TScope = unknown> {
           scope,
           storageKey: state.storageKey,
           sessionId: stored.session.sessionId,
+          ...sessionGeneration,
           runId,
           captureId,
           reference: cloneSerializable(reference),
@@ -2685,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,
@@ -3999,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,
@@ -4967,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,
@@ -5001,6 +5008,7 @@ export class FlexHarness<TScope = unknown> {
     scope: TScope,
     storageKey: string,
     sessionId: string,
+    sessionGeneration: Readonly<IFlexSessionGeneration>,
     runId: string,
     captureId: string,
   ): Promise<TNormalizedCaptureInspection> {
@@ -5011,6 +5019,7 @@ export class FlexHarness<TScope = unknown> {
         scope,
         storageKey,
         sessionId,
+        ...sessionGeneration,
         runId,
         captureId,
         signal,
@@ -5044,6 +5053,7 @@ export class FlexHarness<TScope = unknown> {
     scope: TScope,
     storageKey: string,
     sessionId: string,
+    sessionGeneration: Readonly<IFlexSessionGeneration>,
     runId: string,
     captureId: string,
   ): Promise<TFlexTurnReversionFinalizedOutcome> {
@@ -5053,6 +5063,7 @@ export class FlexHarness<TScope = unknown> {
         scope,
         storageKey,
         sessionId,
+        ...sessionGeneration,
         runId,
         captureId,
         signal,
@@ -5072,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',
@@ -5083,6 +5095,7 @@ export class FlexHarness<TScope = unknown> {
         scope,
         state.storageKey,
         sessionId,
+        sessionGeneration,
         runId,
         captureId,
       );
@@ -5107,6 +5120,7 @@ export class FlexHarness<TScope = unknown> {
           scope,
           state.storageKey,
           sessionId,
+          sessionGeneration,
           runId,
           captureId,
         );
@@ -5116,6 +5130,7 @@ export class FlexHarness<TScope = unknown> {
           scope,
           state.storageKey,
           sessionId,
+          sessionGeneration,
           runId,
           captureId,
         );
@@ -5268,6 +5283,7 @@ export class FlexHarness<TScope = unknown> {
           run.scope as TScope,
           run.state.storageKey,
           run.sessionId,
+          requireSessionGeneration(run.stored.session),
           run.runId,
           captureId,
         );
@@ -5349,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,
@@ -5598,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) {
@@ -5612,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),
@@ -5649,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;
@@ -5712,6 +5733,7 @@ export class FlexHarness<TScope = unknown> {
               scope,
               storageKey,
               sessionId,
+              ...sessionGeneration,
               runId,
               captureId,
               reference: cloneSerializable(reference),
@@ -5825,6 +5847,7 @@ export class FlexHarness<TScope = unknown> {
           scope,
           storageKey,
           sessionId,
+          sessionGeneration,
           capture.runId,
           capture.captureId,
         );
@@ -5854,6 +5877,7 @@ export class FlexHarness<TScope = unknown> {
             scope,
             storageKey,
             sessionId,
+            sessionGeneration,
             capture.runId,
             capture.captureId,
           );
@@ -5863,6 +5887,7 @@ export class FlexHarness<TScope = unknown> {
             scope,
             storageKey,
             sessionId,
+            sessionGeneration,
             capture.runId,
             capture.captureId,
           );
@@ -5928,6 +5953,7 @@ export class FlexHarness<TScope = unknown> {
               scope,
               storageKey,
               sessionId,
+              ...sessionGeneration,
               runId: release.runId,
               captureId: release.captureId,
               reference: cloneSerializable(release.reference),
@@ -6707,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 }),
@@ -7116,7 +7143,7 @@ export class FlexHarness<TScope = unknown> {
             await this.releaseDeletedSessionReversions(
               state,
               storageKey,
-              tombstone.sessionId,
+              tombstone,
               scopeId,
               scope,
             );
@@ -8362,7 +8389,7 @@ export class FlexHarness<TScope = unknown> {
         await this.releaseDeletedSessionReversions(
           state,
           state.storageKey,
-          sessionId,
+          tombstone,
           releaseContext.scopeId,
           releaseContext.scope,
           retained?.stored,

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;