@modelprofile.com/flexharness 5.2.0 → 5.3.0

package/dist_ts/interfaces.d.ts

@@ -691,7 +691,7 @@ export interface IFlexUndoSessionResult {
 export interface IFlexRedoSessionResult {
     restoredRunId: string;
 }
-export type TFlexExternalErrorSource = 'modelResolver' | 'toolProvider' | 'toolExecution' | 'toolCallback' | 'toolCleanup' | 'agentSession' | 'persistence' | 'slashCommand' | 'turnReversion';
+export type TFlexExternalErrorSource = 'modelResolver' | 'toolProvider' | 'delegatedRunAdmissionProvider' | 'toolExecution' | 'toolCallback' | 'toolCleanup' | 'agentSession' | 'persistence' | 'slashCommand' | 'turnReversion';
 export interface IFlexExternalErrorContext {
     source: TFlexExternalErrorSource;
     scopeId: string;
@@ -699,6 +699,32 @@ export interface IFlexExternalErrorContext {
     runId: string;
 }
 export type TFlexExternalErrorProjector = (error: unknown, context: IFlexExternalErrorContext) => IFlexErrorInfo;
+export interface IFlexDelegatedRunAdmissionContext<TScope> extends IFlexSessionGeneration {
+    readonly scopeId: string;
+    readonly scope: TScope;
+    readonly storageKey: string;
+    readonly sessionId: string;
+    readonly sessionGenerationId: string;
+    readonly sessionGenerationSequence: number;
+    readonly queueId: string;
+    readonly runId: string;
+    readonly parentSessionId: string;
+    readonly parentSessionGenerationId: string;
+    readonly parentSessionGenerationSequence: number;
+    readonly parentQueueId: string;
+    readonly parentRunId: string;
+    readonly parentToolCallId: string;
+    readonly agent: string;
+    readonly depth: number;
+    readonly signal: AbortSignal;
+}
+export interface IFlexDelegatedRunAdmissionLease {
+    /** Must be idempotent and safe to retry after a rejected close attempt. */
+    close(): Promise<void> | void;
+}
+export interface IFlexDelegatedRunAdmissionProvider<TScope> {
+    acquireDelegatedRunAdmission(context: IFlexDelegatedRunAdmissionContext<TScope>): Promise<IFlexDelegatedRunAdmissionLease> | IFlexDelegatedRunAdmissionLease;
+}
 export interface IFlexExecutionContextProviderContext<TScope> {
     scopeId: string;
     scope: TScope;
@@ -754,6 +780,7 @@ export interface IFlexHarnessOptions<TScope> {
     toolProvider?: IFlexToolProvider<TScope>;
     resourceToolProviderResolver?: IFlexResourceToolProviderResolver<TScope>;
     executionContextProvider?: IFlexExecutionContextProvider<TScope>;
+    delegatedRunAdmissionProvider?: IFlexDelegatedRunAdmissionProvider<TScope>;
     stores?: IFlexHarnessStores;
     agentSessionPolicy?: IFlexAgentSessionPolicy<TScope>;
     toolOutputLimits?: IFlexJsonLimits;

package/package.json

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

@@ -290,9 +290,43 @@ The parent tool part receives `childSessionId` in a cumulative `part.updated` ev
 }
 ```
 
-Omitting `taskId` creates a deterministic child for the parent session, run, and tool call. Repeating that same invocation does not create another child. If the deterministic child already has messages, FlexHarness reports an uncertain prior execution and never silently reruns it. This preserves SmartAgent's durable parent tool intent as crash authority; controllers use `listUncertainToolExecutions()` and `reconcileToolExecution()` for uncertain parent calls.
+Omitting `taskId` creates a deterministic child for the parent session, run, and tool call. The model-visible tool description and `taskId` schema state this creation rule directly. Repeating that same invocation does not create another child. If the deterministic child already has messages, FlexHarness reports an uncertain prior execution and never silently reruns it. This preserves SmartAgent's durable parent tool intent as crash authority; controllers use `listUncertainToolExecutions()` and `reconcileToolExecution()` for uncertain parent calls.
 
-Supplying `taskId` deliberately resumes an idle, live child from a later run of the same immutable parent session and the same configured agent. It starts a new child prompt while retaining the child's original parent run and tool-call origin. A child owned by another parent or agent, a deleted child, an active child, a same-run resume, or a second acquisition of the same child within one later parent run is rejected. Parent cancellation propagates only to the exact child run started by that delegate call.
+Supplying `taskId` deliberately resumes an idle, live child from a later run of the same immutable parent session and the same configured agent. The caller must use the exact ID returned by an earlier completed delegate call; an unknown ID fails with safe corrective guidance and never creates a child under the supplied label. Resume starts a new child prompt while retaining the child's original parent run and tool-call origin. A child owned by another parent or agent, a deleted child, an active child, a same-run resume, or a second acquisition of the same child within one later parent run is rejected. Parent cancellation propagates only to the exact child run started by that delegate call.
+
+`delegatedRunAdmissionProvider` optionally adds an application-owned admission lease around each internally delegated child run. The public contracts are `IFlexDelegatedRunAdmissionProvider<TScope>`, `IFlexDelegatedRunAdmissionContext<TScope>`, and `IFlexDelegatedRunAdmissionLease`. The provider is never called for root prompts or direct public prompt APIs. It receives a frozen context containing the resolved `scopeId`, exact captured `scope`, and `storageKey`; the exact child `sessionId`, session generation, queue, and run; the exact current parent session generation, queue, run, and delegate `toolCallId`; the child agent and depth; and the child run `AbortSignal`. For `taskId` resume, `parentQueueId`, `parentRunId`, and `parentToolCallId` identify the current delegate invocation, while the durable child session retains its original `parentRunId` and `parentToolCallId` creation metadata.
+
+```typescript
+delegatedRunAdmissionProvider: {
+  async acquireDelegatedRunAdmission(context) {
+    const admission = await controller.acquireDelegatedRun({
+      child: {
+        sessionId: context.sessionId,
+        sessionGenerationId: context.sessionGenerationId,
+        sessionGenerationSequence: context.sessionGenerationSequence,
+        queueId: context.queueId,
+        runId: context.runId,
+      },
+      parent: {
+        sessionId: context.parentSessionId,
+        sessionGenerationId: context.parentSessionGenerationId,
+        sessionGenerationSequence: context.parentSessionGenerationSequence,
+        queueId: context.parentQueueId,
+        runId: context.parentRunId,
+        toolCallId: context.parentToolCallId,
+      },
+      signal: context.signal,
+    });
+    return {
+      close: () => admission.close(),
+    };
+  },
+},
+```
+
+Acquisition completes before generation-side branch reversion, context compaction, model resolution, application or resource tool-provider callbacks, and model execution. Child session store and runtime initialization may already have occurred before acquisition. Providers must honor the supplied `AbortSignal`; an abort can settle the active child and parent without waiting for an acquisition that ignores cancellation, while FlexHarness retains ownership and closes any lease returned later.
+
+For a normally acquired lease, FlexHarness gives `close()` an awaited attempt after SmartAgent generation and before canonical accepted, rejected, or interrupted finalization and the terminal `prompt.finished` event. If an abort detaches an acquisition that ignores its signal, the run may settle before acquisition returns; FlexHarness retains that owner and closes any late lease. `close()` must be idempotent and safe to retry after rejection. A close failure prevents successful child acceptance and remains owned by the exact child session generation for retry by later exact-session deletion, scope retirement, or disposal. Retirement and disposal truthfully wait for late acquisition and lease cleanup.
 
 Limits are validated and frozen at construction: at most 32 unique definitions; names are non-empty and at most 128 UTF-8 bytes; descriptions 2048 bytes; optional model hints 512 bytes; optional system prompts 64 KiB; and optional `maxSteps` a positive safe integer. `maxSubagentDepth` defaults to 1 and must be a positive safe integer at most 8. `maxSubagentCallsPerRun` defaults to 32 and must be a positive safe integer at most 128. A call slot is consumed synchronously at the start of every schema-valid delegate execution, before semantic bounds, subagent type/depth validation, permission, or child work. Inputs rejected by the tool schema never start delegate execution and do not consume a slot. After successful semantic validation, the child ID is reserved for the rest of the parent run, including after permission rejection or later failure. Permission rejection creates no child session. Omitting `taskId` reserves a deterministic new child ID; supplying `taskId` reserves and resumes that existing child after permission. Delegate descriptions are non-empty and at most 256 UTF-8 bytes, prompts non-empty and at most 64 KiB, subagent types at most 128 bytes, and task IDs at most 512 bytes.
 
@@ -661,9 +695,9 @@ FlexHarness wraps every provided tool `execute` method before SmartAgent receive
 
 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.
+Model resolver, tool provider, delegated run admission 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.
 
-`externalErrorProjector` receives one of `modelResolver`, `toolProvider`, `agentSession`, `toolExecution`, `toolCallback`, `toolCleanup`, `persistence`, `slashCommand`, or `turnReversion` as its source. It may synchronously return an application-approved plain data object `{ name, message, code? }`, limited to a 128-byte name, 2048-byte message, and optional 128-byte code. Accessors, extra keys, throwing projectors, and malformed or oversized results fall back to the fixed error. Even exported FlexHarness error subclasses thrown by external integrations are reprojected. Internally created cancellation, callback-overflow, and permission errors retain their typed behavior.
+`externalErrorProjector` receives one of `modelResolver`, `toolProvider`, `delegatedRunAdmissionProvider`, `agentSession`, `toolExecution`, `toolCallback`, `toolCleanup`, `persistence`, `slashCommand`, or `turnReversion` as its source. It may synchronously return an application-approved plain data object `{ name, message, code? }`, limited to a 128-byte name, 2048-byte message, and optional 128-byte code. Accessors, extra keys, throwing projectors, and malformed or oversized results fall back to the fixed error. Even exported FlexHarness error subclasses thrown by external integrations are reprojected. Internally created cancellation, callback-overflow, and permission errors retain their typed behavior.
 
 `normalizeJsonValue()` is also exported for integrations that need the same conversion independently.
 

package/ts/00_commitinfo_data.ts

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