@modelprofile.com/flexharness 10.11.0 → 10.13.0

package/ts/classes.flexharness.ts

@@ -14,6 +14,7 @@ import {
   FlexHarnessSlashCommandReentryError,
   FlexHarnessSlashCommandUnavailableError,
   FlexHarnessSteerRejectedError,
+  FlexHarnessStepLimitError,
   FlexHarnessStoreConflictError,
   FlexHarnessStoreCommitUncertainError,
   FlexHarnessValidationError,
@@ -28,7 +29,13 @@ import {
   FLEX_REVERSION_WORKSPACE_ID_MAX_BYTES,
   FLEX_REVERSION_WORKSPACE_LABEL_MAX_BYTES,
   FLEX_SESSION_IMPORT_MAX_DEPTH,
+  FLEX_TOOL_CATALOG_TOOL_NAMES,
 } from './interfaces.js';
+import {
+  FlexToolCatalog,
+  assertNoCatalogCollisions,
+  catalogToolInputSchema,
+} from './classes.toolcatalog.js';
 import type {
   IFlexAgentContextCompactionOptions,
   IFlexAgentContextInvocation,
@@ -95,6 +102,8 @@ import type {
   IFlexSessionPermissionPolicyContext,
   IFlexSessionActivity,
   IFlexSessionGeneration,
+  IFlexSessionMetrics,
+  IFlexSessionMetricsState,
   IFlexSessionGenerationCohortEntry,
   IFlexSessionImportHandle,
   IFlexSessionImportLimits,
@@ -109,6 +118,9 @@ import type {
   IFlexSubagentDefinition,
   IFlexSubagentProvenance,
   IFlexTerminalProjection,
+  IFlexCatalogDescribeInput,
+  IFlexCatalogSearchInput,
+  IFlexToolCatalogOptions,
   IFlexToolHandle,
   IFlexToolMessagePart,
   IFlexToolProviderContext,
@@ -165,6 +177,7 @@ import {
   normalizeAgentSessionPolicy,
   normalizeBuiltInTools,
   normalizeSlashCommands,
+  normalizeToolCatalogOptions,
   normalizeSubagents,
   requireHarnessStores,
   resolveBoundedPositiveInteger,
@@ -226,6 +239,15 @@ import {
   validateUtf8String,
 } from './utils.validation.js';
 
+import {
+  createSessionMetricsOperation,
+  createSessionMetricsState,
+  observeSessionMetricsCall,
+  sessionMetricsView,
+  settleSessionMetricsOperation,
+  type ISessionMetricsOperation,
+} from './utils.sessionmetrics.js';
+
 type TCanonicalOutcome = 'accepted' | 'rejected' | 'interrupted';
 type TRunPhase =
   | 'admitting'
@@ -256,6 +278,10 @@ interface IStoredSessionState {
   projectionReconciliationRequired: boolean;
   projectionRevision: number;
   projectionQueue: Promise<void>;
+  metrics: IFlexSessionMetricsState;
+  metricsCompaction?: ISessionMetricsOperation;
+  /** Retained independently of the error-neutral projectionQueue. */
+  metricsFailure?: unknown;
   rememberedPermissionKeys: Set<string>;
   permissionRevision: number;
   permissionQueue: Promise<void>;
@@ -402,17 +428,23 @@ interface IActiveRun {
   finishedEventEmitted: boolean;
   /** The usage the provider reported for the run's model calls so far. */
   usage: IFlexUsage;
+  metricsOperation?: ISessionMetricsOperation;
   reasoningPartIds: Map<string, string>;
   toolPartIds: Map<string, string>;
   trustedToolExecutionErrors: Map<string, Error>;
   subagentCallCount: number;
   subagentSessionIds: Set<string>;
   backgroundSubagents: Set<Promise<void>>;
+  cacheDispatch?: plugins.ISmartAiCacheDispatch;
   pendingPermissionIds: Set<string>;
   phase: TRunPhase;
   reservedUserMessage?: IFlexMessage;
   reservedAssistantMessage?: IFlexMessage;
   modelResolution?: IFlexResolvedModel;
+  /** The tool-provider context of the run, passed to catalog methods. */
+  toolProviderContext?: Readonly<IFlexToolProviderContext<unknown>>;
+  /** The catalog methods the run offers through search_tools, describe_tools and execute. */
+  toolCatalog?: FlexToolCatalog<unknown>;
   subagents: ReadonlyMap<string, Readonly<IFlexSubagentDefinition>>;
   allowedTools?: readonly string[];
   agentAllowedTools?: readonly string[];
@@ -466,6 +498,7 @@ interface IDelegatedRunAdmissionSeed {
   readonly parentQueueId: string;
   readonly parentRunId: string;
   readonly parentToolCallId: string;
+  readonly configurationRef?: string;
   readonly agent: string;
   readonly depth: number;
 }
@@ -672,7 +705,7 @@ const maxSubagentPromptBytes = 64 * 1024;
 const maxSubagentTaskIdBytes = 512;
 const maxSubagentPermissionMetadataBytes = 16 * 1024;
 const maxSubagentResultTextBytes = 64 * 1024;
-const defaultMaxSubagentDepth = 1;
+const defaultMaxSubagentDepth = 6;
 const maximumMaxSubagentDepth = 8;
 const defaultMaxSubagentCallsPerRun = 32;
 const maximumMaxSubagentCallsPerRun = 128;
@@ -832,6 +865,7 @@ export class FlexHarness<TScope = unknown> {
   private readonly externalErrorProjector?: TFlexExternalErrorProjector;
   private readonly subagents: ReadonlyMap<string, Readonly<IFlexSubagentDefinition>>;
   private readonly builtInTools: INormalizedBuiltInTools;
+  private readonly toolCatalogOptions: Readonly<Required<IFlexToolCatalogOptions>>;
   private readonly slashCommands: ReadonlyMap<string, TRegisteredSlashCommand<TScope>>;
   private readonly maxSubagentDepth: number;
   private readonly maxSubagentCallsPerRun: number;
@@ -918,6 +952,7 @@ export class FlexHarness<TScope = unknown> {
     this.externalErrorProjector = options.externalErrorProjector;
     this.subagents = normalizeSubagents(options.subagents);
     this.builtInTools = normalizeBuiltInTools(options.builtInTools);
+    this.toolCatalogOptions = normalizeToolCatalogOptions(options.toolCatalog);
     this.slashCommands = normalizeSlashCommands(options.slashCommands);
     this.maxSubagentDepth = resolveBoundedPositiveInteger(
       options.maxSubagentDepth,
@@ -1029,6 +1064,7 @@ export class FlexHarness<TScope = unknown> {
         scopeId,
         resolved.scope.scope,
         placeholder.compactorLifecycleController,
+        true,
       );
       const loaded = await initialization;
       if (resolved.state.sessions.get(sessionId) !== placeholder) {
@@ -1314,6 +1350,7 @@ export class FlexHarness<TScope = unknown> {
       await this.stores.projections.save(state.storageKey, sessionId, {
         schemaVersion: 3,
         revision: 1,
+        metrics: createSessionMetricsState(false),
         messages: staged.runs.flatMap((run) => [run.user, run.assistant]),
         stagedTerminals: [],
         reversionSegments: [],
@@ -1390,6 +1427,16 @@ export class FlexHarness<TScope = unknown> {
     return publicSnapshot(this.requireSession(state, sessionId).session);
   }
 
+  /** Bounded projection-state read: no message, event, archive or child-history scan. */
+  public async getSessionMetrics(scopeId: string, sessionId: string): Promise<IFlexSessionMetrics> {
+    const { state } = await this.resolveState(scopeId);
+    const stored = this.requireSession(state, sessionId);
+    await stored.projectionQueue;
+    this.assertStateAcceptingWork(state);
+    if (stored.metricsFailure !== undefined) throw stored.metricsFailure;
+    return publicSnapshot(sessionMetricsView(stored.metrics));
+  }
+
   public async getSessionReversionInfo(
     scopeId: string,
     sessionId: string,
@@ -3014,13 +3061,53 @@ export class FlexHarness<TScope = unknown> {
       }
       throw new FlexHarnessNotFoundError('Prompt queue entry', queueId);
     }
+    return this.admitRunSteer(run, steer, prompt, byteSize);
+  }
+
+  /** Sends follow-up input only to an exact running direct child owned by this parent run. */
+  public async sendSubagentInput(
+    scopeId: string,
+    parentSessionId: string,
+    parentRunId: string,
+    taskId: string,
+    steer: IFlexSteerInput,
+  ): Promise<IFlexSteerAdmission> {
+    validateIdentifier(parentSessionId, 'parentSessionId');
+    requireTransferIdentifier(parentSessionId, 'parentSessionId');
+    validateIdentifier(parentRunId, 'parentRunId');
+    requireTransferIdentifier(parentRunId, 'parentRunId');
+    this.assertOpen();
+    const { state } = await this.resolveState(scopeId);
+    const parent = state.activeRuns.get(parentSessionId);
+    if (!parent || parent.runId !== parentRunId) {
+      throw new FlexHarnessValidationError('The exact parent run is not active.');
+    }
+    return this.sendSubagentInputInRun(parent, taskId, steer);
+  }
+
+  /** The shared synchronous admission point; neither entrypoint starts or resumes a run. */
+  private admitRunSteer(
+    run: IActiveRun,
+    steer: IFlexSteerInput,
+    prompt: INormalizedFlexPrompt,
+    byteSize: number,
+  ): IFlexSteerAdmission {
+    if (
+      run.phase === 'closing'
+      || run.phase === 'finalizing'
+      || run.phase === 'promoting'
+      || run.callbacksClosed
+      || run.controller.signal.aborted
+      || run.stop.signal.aborted
+      || run.state.activeRuns.get(run.sessionId) !== run
+    ) throw new FlexHarnessSteerRejectedError('not-running', steer.steerId);
     const steering = run.steering;
     if (!steering.input.closed && !steering.accepted.has(steer.steerId)) {
       if (
         steering.accepted.size - steering.applied.size
         >= this.promptQueueLimits.maxOutstandingPromptsPerSession
       ) {
-        throw new FlexHarnessQueueFullError(`Session "${sessionId}" has reached its pending steer limit.`);
+        throw new FlexHarnessQueueFullError(`Session "${run.sessionId}" has reached its pending steer limit.`);
       }
       // Pending steers hold outstanding prompt bytes of the session until they are taken in.
       if (
@@ -3028,7 +3115,7 @@ export class FlexHarness<TScope = unknown> {
         > this.promptQueueLimits.maxOutstandingBytesPerSession
       ) {
         throw new FlexHarnessQueueFullError(
-          `Session "${sessionId}" has reached its outstanding prompt byte limit.`,
+          `Session "${run.sessionId}" has reached its outstanding prompt byte limit.`,
         );
       }
     }
@@ -3052,11 +3139,130 @@ export class FlexHarness<TScope = unknown> {
     steering.stored.outstandingPromptBytes += byteSize;
     this.emitEvent(run.scopeId, run.stored.session, {
       type: 'prompt.steer.accepted',
-      queueId,
+      queueId: run.queueId,
       runId: run.runId,
       steerId: steer.steerId,
     });
-    return { steerId: steer.steerId, queueId, runId: run.runId };
+    return { steerId: steer.steerId, queueId: run.queueId, runId: run.runId };
+  }
+
+  private sendSubagentInputInRun(
+    parent: IActiveRun,
+    taskId: string,
+    steer: IFlexSteerInput,
+  ): IFlexSteerAdmission {
+    this.assertOpen();
+    validateUtf8String(taskId, 'taskId', maxSubagentTaskIdBytes, true);
+    validateIdentifier(steer.steerId, 'steerId');
+    requireTransferIdentifier(steer.steerId, 'steerId');
+    const prompt = normalizeFlexPrompt(steer.prompt);
+    const byteSize = this.promptAdmissionByteSize(steer.prompt, {});
+    this.assertStateAcceptingWork(parent.state);
+    const child = parent.state.activeRuns.get(taskId);
+    if (!child) throw new FlexHarnessSteerRejectedError('not-running', steer.steerId);
+    this.assertLiveSubagentOwnership(child, parent);
+    return this.admitRunSteer(child, steer, prompt, byteSize);
+  }
+
+  /** Fences live ownership by exact runtime pointers and admission seeds all the way to root. */
+  private assertLiveSubagentOwnership(child: IActiveRun, parent: IActiveRun): void {
+    const state = parent.state;
+    const visited = new Set<IActiveRun>();
+    let current = child;
+    let expectedParent: IActiveRun | undefined = parent;
+    while (true) {
+      const stored = current.stored;
+      const session = stored.session;
+      const queued = stored.outstandingPromptsById.get(current.queueId);
+      if (
+        visited.has(current)
+        || current.state !== state
+        || state.activeRuns.get(current.sessionId) !== current
+        || state.sessions.get(current.sessionId) !== stored
+        || session.sessionId !== current.sessionId
+        || state.tombstones.has(current.sessionId)
+        || state.initializingSessions.has(current.sessionId)
+        || current.phase !== 'running'
+        || current.callbacksClosed
+        || current.controller.signal.aborted
+        || current.stop.signal.aborted
+        || current.steering.input.closed
+        || !queued
+        || queued.state !== state
+        || queued.stored !== stored
+        || queued.sessionId !== current.sessionId
+        || queued.queueId !== current.queueId
+        || queued.runId !== current.runId
+        || queued.steering !== current.steering
+      ) throw new FlexHarnessValidationError('The subagent or ancestor run is no longer live and owned.');
+      this.assertSessionWritable(stored);
+      visited.add(current);
+      if (session.parentSessionId === undefined) {
+        if (expectedParent !== undefined || queued.delegationSeed !== undefined) {
+          throw new FlexHarnessValidationError('The task is not a direct child of this parent run.');
+        }
+        return;
+      }
+      const seed = queued.delegationSeed;
+      if (!seed) throw new FlexHarnessValidationError('The child has no live delegated admission owner.');
+      const owner = current.delegatedRunAdmissionOwner;
+      const owningParent = seed.parentRun;
+      const parentSession = owningParent.stored.session;
+      if (
+        (expectedParent !== undefined && owningParent !== expectedParent)
+        || seed.state !== state
+        || seed.storageKey !== state.storageKey
+        || seed.childStored !== stored
+        || stored.storageKey !== seed.storageKey
+        || seed.sessionId !== current.sessionId
+        || session.sessionId !== seed.sessionId
+        || session.sessionGenerationId !== seed.sessionGenerationId
+        || session.sessionGenerationSequence !== seed.sessionGenerationSequence
+        || session.parentSessionId !== seed.parentSessionId
+        || session.parentRunId !== seed.originParentRunId
+        || session.parentToolCallId !== seed.originParentToolCallId
+        || session.agent !== seed.agent
+        || session.depth !== seed.depth
+        || session.configurationRef !== seed.configurationRef
+        || parentSession.configurationRef !== seed.configurationRef
+        || seed.depth !== (parentSession.depth ?? 0) + 1
+        || !owningParent.subagents.has(seed.agent)
+        || seed.parentStored !== owningParent.stored
+        || seed.parentStored.storageKey !== seed.storageKey
+        || owningParent.sessionId !== seed.parentSessionId
+        || owningParent.runId !== seed.parentRunId
+        || owningParent.queueId !== seed.parentQueueId
+        || parentSession.sessionGenerationId !== seed.parentSessionGenerationId
+        || parentSession.sessionGenerationSequence !== seed.parentSessionGenerationSequence
+        || current.scopeId !== seed.scopeId
+        || current.scope !== seed.scope
+        || owningParent.scopeId !== seed.scopeId
+        || owningParent.scope !== seed.scope
+        || (this.delegatedRunAdmissionProvider !== undefined && owner === undefined)
+        || (owner !== undefined && (
+          owner.storageState !== state || owner.run !== current
+          || !state.delegatedRunAdmissionOwners.has(owner)
+          || owner.status !== 'acquired' || !owner.acquisitionSettled || owner.acquisitionDetached
+          || owner.context.runId !== current.runId || owner.context.queueId !== current.queueId
+          || owner.context.parentRunId !== owningParent.runId
+          || owner.context.parentQueueId !== owningParent.queueId
+          || owner.context.scopeId !== seed.scopeId || owner.context.scope !== seed.scope
+          || owner.context.storageKey !== seed.storageKey
+          || owner.context.sessionId !== seed.sessionId
+          || owner.context.parentSessionId !== seed.parentSessionId
+          || owner.context.parentToolCallId !== seed.parentToolCallId
+          || owner.context.originParentRunId !== seed.originParentRunId
+          || owner.context.originParentToolCallId !== seed.originParentToolCallId
+          || owner.context.agent !== seed.agent || owner.context.depth !== seed.depth
+          || owner.context.sessionGenerationId !== seed.sessionGenerationId
+          || owner.context.sessionGenerationSequence !== seed.sessionGenerationSequence
+          || owner.context.parentSessionGenerationId !== seed.parentSessionGenerationId
+          || owner.context.parentSessionGenerationSequence !== seed.parentSessionGenerationSequence
+        ))
+      ) throw new FlexHarnessValidationError('The task is not owned by this exact parent run and configuration.');
+      current = owningParent;
+      expectedParent = undefined;
+    }
   }
 
   public async abort(scopeId: string, sessionId: string): Promise<boolean> {
@@ -4532,7 +4738,12 @@ export class FlexHarness<TScope = unknown> {
         this.assertPromptPromotion(queued, run);
         const reservation = this.createReservation(run, prompt);
         closeReservationPublication = this.openPublication(run.state, run.sessionId);
+        run.metricsOperation = createSessionMetricsOperation(run.runId, 'generation');
         await this.mutateProjection(run.state, run.stored, () => {
+          if (run.stored.metrics.pendingGenerationId !== undefined) {
+            throw new Error('Session metrics already owns a generation.');
+          }
+          run.stored.metrics.pendingGenerationId = run.runId;
           run.stored.messages.push(reservation.userMessage, reservation.assistantMessage);
           if (run.stored.session.agent === undefined) {
             this.pruneReversionState(run.stored, true);
@@ -4650,6 +4861,8 @@ export class FlexHarness<TScope = unknown> {
       prepare: (context: { generationId: string; abortSignal: AbortSignal }) =>
         this.prepareGeneration(run, options, context.abortSignal),
       pendingInput: run.steering.input,
+      activateOnBackgroundJobs: true,
+      onCacheDispatch: (dispatch: plugins.ISmartAiCacheDispatch) => { run.cacheDispatch = dispatch; },
       onInputApplied: (input: plugins.IAgentAppliedInput) => this.applyRunSteer(run, input),
       beforeFinish: (context: { abortSignal: AbortSignal }) =>
         this.awaitNextBackgroundSubagent(run, context.abortSignal),
@@ -4803,7 +5016,8 @@ export class FlexHarness<TScope = unknown> {
   /**
    * Holds the end of a run's generation until one more of its background subagents settles. The
    * subagent commits its result to the generation before it settles, so the model takes the result
-   * in with another step instead of the run ending without it. Returns at once when none runs.
+   * in with another step instead of the run ending without it. The engine bounds the scoped
+   * wait from its observed dispatch and commits timer check-ins. Returns at once when none runs.
    */
   private async awaitNextBackgroundSubagent(run: IActiveRun, signal: AbortSignal): Promise<void> {
     if (run.backgroundSubagents.size === 0) return;
@@ -4828,8 +5042,16 @@ export class FlexHarness<TScope = unknown> {
     try {
       // The transactional generation settles only after its model calls are reported, so
       // `run.usage` is complete once it settles, also for a cancelled run.
-      const rawResult = await generation;
-      generated = true;
+      let rawResult: plugins.IAgentGenerateResult;
+      try {
+        rawResult = await generation;
+        generated = true;
+      } finally {
+        await this.settleMetricsOperation(run.state, run.stored, run.metricsOperation!);
+      }
+      if (rawResult.terminationReason === 'step-limit') {
+        throw this.trustInternalError(new FlexHarnessStepLimitError(rawResult.steps));
+      }
       // Background tools do not block inference, but the owning turn joins its admitted children
       // before releasing its authority or committing its terminal projection.
       await Promise.all([...run.backgroundSubagents]);
@@ -5617,18 +5839,37 @@ export class FlexHarness<TScope = unknown> {
       }
       signal.throwIfAborted();
       run.modelResolution = model!;
+      run.toolProviderContext = toolProviderContext as Readonly<IFlexToolProviderContext<unknown>>;
+      let catalog: FlexToolCatalog<unknown> | undefined;
+      if (toolHandle?.catalog) {
+        try {
+          catalog = await FlexToolCatalog.create(toolHandle.catalog, this.toolCatalogOptions);
+        } catch (error) {
+          throw this.projectExternalError(run, error, 'toolProvider');
+        }
+        signal.throwIfAborted();
+      }
       let tools: TFlexAgentToolSet | undefined;
       try {
         const providedTools = toolHandle?.tools;
         const combinedTools: Record<string, unknown> = { ...(providedTools ?? {}) };
         Object.assign(combinedTools, this.createBuiltInTools(run));
+        if (catalog) assertNoCatalogCollisions(catalog, combinedTools);
         const globalNames = run.allowedTools === undefined ? undefined : new Set(run.allowedTools);
         const agentNames = run.agentAllowedTools === undefined ? undefined : new Set(run.agentAllowedTools);
+        const admitted = (name: string): boolean =>
+          (globalNames === undefined || globalNames.has(name))
+          && (agentNames === undefined || agentNames.has(name));
         const admittedTools = globalNames === undefined && agentNames === undefined
           ? combinedTools
-          : Object.fromEntries(Object.entries(combinedTools).filter(([name]) =>
-              (globalNames === undefined || globalNames.has(name))
-              && (agentNames === undefined || agentNames.has(name))));
+          : Object.fromEntries(Object.entries(combinedTools).filter(([name]) => admitted(name)));
+        const admittedCatalog = catalog && (globalNames === undefined && agentNames === undefined
+          ? catalog
+          : catalog.restrict(catalog.methods.filter(admitted)));
+        if (admittedCatalog && admittedCatalog.methods.length > 0) {
+          run.toolCatalog = admittedCatalog;
+          Object.assign(admittedTools, this.createCatalogTools(run, admittedCatalog));
+        }
         tools = Object.keys(admittedTools).length > 0
           ? wrapToolSet(
               admittedTools as TFlexAgentToolSet,
@@ -5644,6 +5885,9 @@ export class FlexHarness<TScope = unknown> {
       const close = toolHandle?.close
         ? async () => {
             if (closed) return;
+            // Inference has ended before its tool lease closes. Fence follow-up admission
+            // synchronously, even when external cleanup has not settled yet.
+            run.steering.input.close();
             closePromise ??= Promise.resolve()
               .then(() => toolHandle!.close!())
               .then(() => {
@@ -5684,6 +5928,7 @@ export class FlexHarness<TScope = unknown> {
     if (run.subagents.size > 0 && (run.stored.session.depth ?? 0) < this.maxSubagentDepth) {
       names.add('delegate');
       names.add('delegate_result');
+      names.add('delegate_send');
     }
     if (this.builtInTools.renameSession) names.add('rename_session');
     const projectManagement = this.builtInTools.projectManagement;
@@ -5703,11 +5948,65 @@ export class FlexHarness<TScope = unknown> {
     }
   }
 
+  /**
+   * search_tools, describe_tools and execute. `execute` validates the call and runs the method
+   * inside this tool call, so the tool wrapper bounds its output and projects its errors, and the
+   * call's part, events and permission requests carry the method's path.
+   */
+  private createCatalogTools(run: IActiveRun, catalog: FlexToolCatalog<unknown>): Record<string, unknown> {
+    const names = FLEX_TOOL_CATALOG_TOOL_NAMES;
+    const definitions = catalog.toolDefinitions();
+    const describeBytes = Math.max(1024, this.toolOutputLimits.maxBytes - 1024);
+    return {
+      [names.search]: plugins.tool({
+        description: definitions[names.search].description,
+        strict: false,
+        inputSchema: catalogToolInputSchema<IFlexCatalogSearchInput>(definitions[names.search]),
+        execute: async (input: IFlexCatalogSearchInput) => catalog.search(input),
+      }),
+      [names.describe]: plugins.tool({
+        description: definitions[names.describe].description,
+        strict: false,
+        inputSchema: catalogToolInputSchema<IFlexCatalogDescribeInput>(definitions[names.describe]),
+        execute: async (input: IFlexCatalogDescribeInput, options?: { messages?: plugins.ModelMessage[] }) =>
+          catalog.describe(input, {
+            declaredTypes: catalog.declaredTypesIn(options?.messages),
+            maxBytes: describeBytes,
+          }).output,
+      }),
+      [names.execute]: plugins.tool({
+        description: definitions[names.execute].description,
+        strict: false,
+        inputSchema: catalogToolInputSchema<{ method: string; params?: Record<string, unknown> }>(
+          definitions[names.execute],
+        ),
+        execute: async (
+          input: { method: string; params?: Record<string, unknown> },
+          options?: { toolCallId?: string; abortSignal?: AbortSignal },
+        ) => {
+          const call = await catalog.prepareCall(input.method, input.params);
+          if (!call.success) {
+            const error = this.trustInternalError(new FlexHarnessValidationError(JSON.stringify(call.error)));
+            if (options?.toolCallId) run.trustedToolExecutionErrors.set(options.toolCallId, error);
+            throw error;
+          }
+          return call.run({
+            method: call.method,
+            toolCallId: options?.toolCallId ?? '',
+            abortSignal: options?.abortSignal ?? run.controller.signal,
+            provider: run.toolProviderContext!,
+          });
+        },
+      }),
+    };
+  }
+
   private createBuiltInTools(run: IActiveRun): Record<string, unknown> {
     const tools: Record<string, unknown> = {};
     if (run.subagents.size > 0 && (run.stored.session.depth ?? 0) < this.maxSubagentDepth) {
       tools.delegate = this.createSubagentTool(run);
       tools.delegate_result = this.createSubagentResultTool(run);
+      tools.delegate_send = this.createSubagentSendTool(run);
     }
     if (this.builtInTools.renameSession) tools.rename_session = this.createRenameSessionTool(run);
     const projectManagement = this.builtInTools.projectManagement;
@@ -6253,9 +6552,33 @@ export class FlexHarness<TScope = unknown> {
     }
   }
 
+  private createSubagentSendTool(run: IActiveRun): unknown {
+    return plugins.tool({
+      description: 'Send follow-up instructions to a RUNNING direct child owned by this exact parent turn. The child takes the message at its next inference boundary; running tools and permission waits are not interrupted. Never starts or resumes a settled child. Use delegate_result for progress and results.',
+      inputSchema: plugins.z.object({
+        taskId: plugins.z.string().min(1).max(maxSubagentTaskIdBytes),
+        prompt: plugins.z.string().min(1).max(maxSubagentPromptBytes),
+      }).strict(),
+      execute: async (
+        { taskId, prompt }: { taskId: string; prompt: string },
+        options?: { toolCallId?: string },
+      ) => {
+        validateUtf8String(prompt, 'delegate_send prompt', maxSubagentPromptBytes, true);
+        const toolCallId = options?.toolCallId;
+        validateUtf8String(toolCallId, 'delegate_send toolCallId', maxTransferIdentifierBytes, true);
+        return this.sendSubagentInputInRun(run, taskId, {
+          steerId: `steer_${sha256Hex(JSON.stringify([
+            'flexharness-subagent-input-v1', run.state.storageKey, run.sessionId, run.runId, toolCallId,
+          ]))}`,
+          prompt,
+        });
+      },
+    });
+  }
+
   private createSubagentResultTool(run: IActiveRun): unknown {
     return plugins.tool({
-      description: 'Read a subagent owned by this parent. Returns live status and the final text when settled. waitMs optionally waits for completion, bounded to 240 seconds; omit it to continue immediately.',
+      description: 'Read a subagent owned by this parent. Returns live status and the final text when settled. waitMs optionally waits for completion, bounded to 240 seconds and the remaining configured cache idle budget; omit it to continue immediately.',
       inputSchema: plugins.z.object({
         taskId: plugins.z.string().min(1).max(maxSubagentTaskIdBytes),
         waitMs: plugins.z.number().int().min(0).max(240_000).optional(),
@@ -6274,7 +6597,7 @@ export class FlexHarness<TScope = unknown> {
             await Promise.race([
               active.completion.catch(() => undefined),
               new Promise<void>((resolve, reject) => {
-                timer = setTimeout(resolve, waitMs);
+                timer = setTimeout(resolve, plugins.getSmartAiCacheWaitMs(waitMs, run.cacheDispatch));
                 onAbort = () => reject(run.controller.signal.reason);
                 run.controller.signal.addEventListener('abort', onAbort, { once: true });
                 if (run.controller.signal.aborted) onAbort();
@@ -6328,6 +6651,9 @@ export class FlexHarness<TScope = unknown> {
       parentQueueId: run.queueId,
       parentRunId: run.runId,
       parentToolCallId: toolCallId,
+      ...(run.stored.session.configurationRef === undefined
+        ? {}
+        : { configurationRef: run.stored.session.configurationRef }),
       agent: definition.name,
       depth: (run.stored.session.depth ?? 0) + 1,
     });
@@ -6467,6 +6793,7 @@ export class FlexHarness<TScope = unknown> {
         run.scopeId,
         run.scope as TScope,
         placeholder!.compactorLifecycleController,
+        true,
       );
       const parentLostOwnership = run.controller.signal.aborted
         || state.sessions.get(run.sessionId) !== run.stored
@@ -8183,13 +8510,17 @@ export class FlexHarness<TScope = unknown> {
     const run = this.callbackRun(state, sessionId);
     if (!run || run.toolPartIds.has(event.toolCallId)) return;
     try {
-      const input = normalizeJsonValue(event.input, this.toolOutputLimits);
+      // An execute call is the call of the catalog method it names.
+      const target = event.toolName === FLEX_TOOL_CATALOG_TOOL_NAMES.execute
+        ? run.toolCatalog?.callTarget(event.input)
+        : undefined;
+      const input = normalizeJsonValue(target ? target.params : event.input, this.toolOutputLimits);
       if (!this.reserveCallbackCapacity(run, 1, jsonBytes(input), 1)) return;
       const part: IFlexToolMessagePart = {
         partId: plugins.crypto.randomUUID(),
         type: 'tool',
         toolCallId: this.boundedIdentifier(event.toolCallId, 'toolCallId'),
-        toolName: this.boundedIdentifier(event.toolName, 'toolName'),
+        toolName: this.boundedIdentifier(target ? target.method : event.toolName, 'toolName'),
         status: 'running',
         input,
         startedAt: new Date().toISOString(),
@@ -8289,34 +8620,59 @@ export class FlexHarness<TScope = unknown> {
     stored: IStoredSessionState,
     event: plugins.TAgentModelCallUsageEvent,
   ): void {
-    const { source, generationId, ...call } = event;
-    const sessionId = stored.session.sessionId;
-    const activeRun = state.activeRuns.get(sessionId);
-    const run = generationId !== undefined && activeRun?.runId === generationId ? activeRun : undefined;
-    let scopeId = run?.scopeId;
-    if (scopeId === undefined) {
-      const ambientContext = this.compactorInvocationContext.getStore();
-      const invocationContext = ambientContext
-        ? this.deferredCompactorContexts.get(ambientContext) ?? ambientContext
-        : undefined;
-      if (
-        !invocationContext
-        || invocationContext.storageKey !== state.storageKey
-        || invocationContext.sessionId !== sessionId
-      ) {
-        throw new Error('Model call usage is missing its exact FlexHarness invocation context.');
+    try {
+      const { source, generationId, ...call } = event;
+      const sessionId = stored.session.sessionId;
+      const activeRun = state.activeRuns.get(sessionId);
+      const run = generationId !== undefined && activeRun?.runId === generationId ? activeRun : undefined;
+      const operation = source === 'compaction' ? stored.metricsCompaction : run?.metricsOperation;
+      if (!operation) throw new Error('Model call usage has no owning metrics operation.');
+      observeSessionMetricsCall(operation, call);
+      let scopeId = run?.scopeId;
+      if (scopeId === undefined) {
+        const ambientContext = this.compactorInvocationContext.getStore();
+        const invocationContext = ambientContext
+          ? this.deferredCompactorContexts.get(ambientContext) ?? ambientContext
+          : undefined;
+        if (
+          !invocationContext
+          || invocationContext.storageKey !== state.storageKey
+          || invocationContext.sessionId !== sessionId
+        ) {
+          throw new Error('Model call usage is missing its exact FlexHarness invocation context.');
+        }
+        scopeId = invocationContext.scopeId;
+      }
+      if (run && call.status === 'reported') {
+        for (const key of Object.keys(run.usage) as (keyof IFlexUsage)[]) run.usage[key] += call.usage[key];
       }
-      scopeId = invocationContext.scopeId;
+      this.emitEvent(scopeId, stored.session, {
+        type: 'model.usage',
+        ...(generationId === undefined ? {} : { runId: generationId }),
+        source,
+        ...call,
+      });
+    } catch (error) {
+      // AgentSession isolates the entire callback, including event/context failures. Join it later.
+      stored.metricsFailure ??= error;
+      throw error;
     }
-    if (run && call.status === 'reported') {
-      for (const key of Object.keys(run.usage) as (keyof IFlexUsage)[]) run.usage[key] += call.usage[key];
+  }
+
+  private async settleMetricsOperation(
+    state: IStorageState,
+    stored: IStoredSessionState,
+    operation: ISessionMetricsOperation,
+  ): Promise<void> {
+    try {
+      if (stored.metricsFailure !== undefined) throw stored.metricsFailure;
+      await this.mutateProjection(state, stored, () => settleSessionMetricsOperation(stored.metrics, operation), true);
+    } catch (error) {
+      stored.metricsFailure ??= error;
+      // Never allow a later operation to overwrite a marker whose spend was not durably joined.
+      state.lifecycle = 'fenced';
+      throw error;
     }
-    this.emitEvent(scopeId, stored.session, {
-      type: 'model.usage',
-      ...(generationId === undefined ? {} : { runId: generationId }),
-      source,
-      ...call,
-    });
   }
 
   private callbackRun(state: IStorageState, sessionId: string): IActiveRun | undefined {
@@ -8820,9 +9176,12 @@ export class FlexHarness<TScope = unknown> {
         errors.push(this.projectExternalError(run, error, 'persistence'));
       }
     }
-    if (projectionReserved) {
+    if (projectionReserved || run.stored.metrics.pendingGenerationId === run.runId) {
       try {
         await this.mutateProjection(run.state, run.stored, () => {
+          if (run.stored.metrics.pendingGenerationId === run.runId) {
+            delete run.stored.metrics.pendingGenerationId;
+          }
           run.stored.messages = run.stored.messages.filter((message) => message.runId !== run.runId);
           run.stored.stagedTerminals = run.stored.stagedTerminals.filter((entry) => entry.runId !== run.runId);
           run.stored.reversionSegments = run.stored.reversionSegments.filter(
@@ -8862,9 +9221,14 @@ export class FlexHarness<TScope = unknown> {
       }
       const tools = handle.tools;
       this.assertNoBuiltInToolCollisions(run, tools);
+      const catalog = handle.catalog;
+      if (catalog !== undefined && (typeof catalog !== 'object' || catalog === null)) {
+        throw new FlexHarnessValidationError('Tool handle catalog must be an object.');
+      }
       const closeHandle = close;
       return {
         tools,
+        ...(catalog === undefined ? {} : { catalog }),
         ...(closeHandle ? { close: () => closeHandle.call(handle) } : {}),
       };
     } catch (error) {
@@ -8951,6 +9315,9 @@ export class FlexHarness<TScope = unknown> {
         );
         if (!handle) continue;
         owned.push({ handle, closed: false });
+        if (handle.catalog !== undefined) {
+          throw new FlexHarnessValidationError('Resource tool providers cannot supply a tool catalog.');
+        }
         for (const [toolName, tool] of Object.entries(handle.tools)) {
           const exposedName = createFlexResourceToolName(namespace, toolName);
           if (Object.prototype.hasOwnProperty.call(tools, exposedName)) {
@@ -8962,6 +9329,7 @@ export class FlexHarness<TScope = unknown> {
       if (owned.length === 0 && Object.keys(tools).length === 0) return undefined;
       return {
         tools: tools as TFlexAgentToolSet,
+        ...(applicationHandle?.catalog === undefined ? {} : { catalog: applicationHandle.catalog }),
         ...(owned.some((entry) => entry.handle.close) ? { close: closeOwned } : {}),
       };
     } catch (error) {
@@ -9403,6 +9771,7 @@ export class FlexHarness<TScope = unknown> {
       projectionReconciliationRequired: false,
       projectionRevision: 0,
       projectionQueue: Promise.resolve(),
+      metrics: createSessionMetricsState(false),
       rememberedPermissionKeys: new Set(),
       permissionRevision: 0,
       permissionQueue: Promise.resolve(),
@@ -9427,6 +9796,7 @@ export class FlexHarness<TScope = unknown> {
     scopeId: string,
     scope: TScope,
     compactorLifecycleController = new AbortController(),
+    newSession = false,
   ): Promise<IStoredSessionState> {
     const sessionId = metadata.sessionId;
     const compactorContext = this.createCompactorContext(
@@ -9530,11 +9900,12 @@ export class FlexHarness<TScope = unknown> {
         pendingReversionReleases,
         projectionSchemaVersion: projection?.schemaVersion ?? 3,
         projectionReconciliationRequired: false,
-        ...(projection && projection.schemaVersion !== 3
+        ...(projection
           ? { projectionBaseline: cloneSerializable(projection) }
           : {}),
         projectionRevision: projection?.revision ?? 0,
         projectionQueue: Promise.resolve(),
+        metrics: cloneSerializable(currentProjection?.metrics ?? createSessionMetricsState(newSession)),
         rememberedPermissionKeys: new Set(permission?.rememberedPermissionKeys ?? []),
         permissionRevision: permission?.revision ?? 0,
         permissionQueue: Promise.resolve(),
@@ -9553,6 +9924,19 @@ export class FlexHarness<TScope = unknown> {
         terminalPromptQueueEntries: new Map(),
         outstandingPromptBytes: 0,
       };
+      if (currentProjection?.metrics === undefined
+        || stored.metrics.pendingGenerationId !== undefined
+        || stored.metrics.pendingCompactionId !== undefined
+        || (metadata.origin !== undefined && stored.metrics.lifetimeUsageComplete)) {
+        await this.mutateProjection(state, stored, () => {
+          if (stored.metrics.pendingGenerationId !== undefined || stored.metrics.pendingCompactionId !== undefined
+            || metadata.origin !== undefined) {
+            stored.metrics.lifetimeUsageComplete = false;
+          }
+          delete stored.metrics.pendingGenerationId;
+          delete stored.metrics.pendingCompactionId;
+        });
+      }
       const {
         contextCompactor,
         ...agentSessionPolicy
@@ -9609,22 +9993,55 @@ export class FlexHarness<TScope = unknown> {
                     events: filteredEvents,
                   }),
                 );
-                return contextCompactor(filteredMessages, filteredEvents, {
-                  ...options,
-                  ...invocation,
-                  scope: invocation.scope as TScope,
-                  ...this.compactionModel(state, sessionId, ambientContext, options.reason, modelHint),
-                  abortSignal: options.abortSignal
-                    ? AbortSignal.any([
-                        options.abortSignal,
-                        state.compactorLifecycleController.signal,
-                        stored.compactorLifecycleController.signal,
-                      ])
-                    : AbortSignal.any([
-                        state.compactorLifecycleController.signal,
-                        stored.compactorLifecycleController.signal,
-                      ]),
-                });
+                const operation = createSessionMetricsOperation(plugins.crypto.randomUUID(), 'compaction');
+                try {
+                  await this.mutateProjection(state, stored, () => {
+                    if (stored.metrics.pendingCompactionId !== undefined || stored.metricsFailure !== undefined) {
+                      throw new Error('Session metrics compaction ownership is unresolved.');
+                    }
+                    stored.metrics.pendingCompactionId = operation.id;
+                  });
+                } catch (error) {
+                  // No compactor ran. Reconcile a known committed reservation without inventing spend.
+                  // Unknown outcomes remain fenced and are repaired conservatively on namespace reload.
+                  if (state.lifecycle !== 'fenced' && stored.metrics.pendingCompactionId === operation.id) {
+                    try {
+                      await this.mutateProjection(state, stored, () => {
+                        delete stored.metrics.pendingCompactionId;
+                      }, true);
+                    } catch (cleanupError) {
+                      stored.metricsFailure ??= cleanupError;
+                      state.lifecycle = 'fenced';
+                      throw combineErrors([error, cleanupError]);
+                    }
+                  }
+                  throw error;
+                }
+                stored.metricsCompaction = operation;
+                try {
+                  return await contextCompactor(filteredMessages, filteredEvents, {
+                    ...options,
+                    ...invocation,
+                    scope: invocation.scope as TScope,
+                    ...this.compactionModel(state, sessionId, ambientContext, options.reason, modelHint),
+                    abortSignal: options.abortSignal
+                      ? AbortSignal.any([
+                          options.abortSignal,
+                          state.compactorLifecycleController.signal,
+                          stored.compactorLifecycleController.signal,
+                        ])
+                      : AbortSignal.any([
+                          state.compactorLifecycleController.signal,
+                          stored.compactorLifecycleController.signal,
+                        ]),
+                  });
+                } finally {
+                  try {
+                    await this.settleMetricsOperation(state, stored, operation);
+                  } finally {
+                    delete stored.metricsCompaction;
+                  }
+                }
               },
             }
           : {}),
@@ -10044,6 +10461,7 @@ export class FlexHarness<TScope = unknown> {
       const beforeBaseline = stored.projectionBaseline === undefined
         ? undefined
         : cloneSerializable(stored.projectionBaseline);
+      const beforeMetrics = cloneSerializable(stored.metrics);
       const beforeMessages = cloneSerializable(stored.messages);
       const beforeStages = cloneSerializable(stored.stagedTerminals);
       const beforeSegments = cloneSerializable(stored.reversionSegments);
@@ -10056,6 +10474,7 @@ export class FlexHarness<TScope = unknown> {
       const beforeSnapshot: TFlexProjectionSnapshot = beforeBaseline ?? {
         schemaVersion: 3,
         revision: beforeRevision,
+        metrics: cloneSerializable(beforeMetrics),
         messages: cloneSerializable(beforeMessages),
         stagedTerminals: cloneSerializable(beforeStages),
         reversionSegments: cloneSerializable(beforeSegments),
@@ -10072,6 +10491,7 @@ export class FlexHarness<TScope = unknown> {
         if (beforeBaseline === undefined) delete stored.projectionBaseline;
         else stored.projectionBaseline = beforeBaseline;
         stored.projectionRevision = beforeRevision;
+        stored.metrics = beforeMetrics;
         stored.messages = beforeMessages;
         stored.stagedTerminals = beforeStages;
         stored.reversionSegments = beforeSegments;
@@ -10251,6 +10671,7 @@ export class FlexHarness<TScope = unknown> {
     return {
       schemaVersion: 3,
       revision,
+      metrics: cloneSerializable(stored.metrics),
       messages: cloneSerializable(stored.messages),
       stagedTerminals: cloneSerializable(stored.stagedTerminals),
       reversionSegments: cloneSerializable(stored.reversionSegments),
@@ -10962,6 +11383,11 @@ export class FlexHarness<TScope = unknown> {
         errors.push(error);
       }
     }
+    if (stored.metricsFailure !== undefined) {
+      errors.push(stored.metricsFailure);
+      // Runtime ownership has settled; the fenced namespace will be reloaded from its durable WAL.
+      if (stored.agentSessionCloseCompleted) delete stored.metricsFailure;
+    }
     if (errors.length > 0) throw combineErrors(errors);
   }