@modelprofile.com/flexharness 10.15.1 → 10.17.0

package/ts/classes.flexharness.ts

@@ -29,15 +29,19 @@ import {
   FLEX_REVERSION_WORKSPACE_ID_MAX_BYTES,
   FLEX_REVERSION_WORKSPACE_LABEL_MAX_BYTES,
   FLEX_CODE_MODE_TOOL_NAME,
+  FLEX_RESULT_LIMITS,
+  FLEX_RESULT_METHOD,
   FLEX_SESSION_IMPORT_MAX_DEPTH,
   FLEX_TOOL_CATALOG_TOOL_NAMES,
+  type IFlexResultHandle,
 } from './interfaces.js';
+import { describeShape, resultPage, selectPath, summarizeResult } from './utils.results.js';
 import {
   FlexToolCatalog,
   assertNoCatalogCollisions,
   catalogToolInputSchema,
 } from './classes.toolcatalog.js';
-import { FlexCodeSandbox, type IFlexCodeHost } from './classes.codesandbox.js';
+import { FlexCodeSandbox, type IFlexCodeHost, type TFlexCodeCallOutcome } from './classes.codesandbox.js';
 import type {
   IFlexAgentContextCompactionOptions,
   IFlexAgentContextInvocation,
@@ -159,6 +163,7 @@ import type {
 import { InMemoryFlexHarnessStores } from './classes.stores.js';
 import {
   assertJsonSerializable,
+  canonicalJson,
   cloneSerializable,
   deepFreeze,
   normalizeJsonValue,
@@ -225,7 +230,7 @@ import {
   validateSessionImportHandle,
   type INormalizedSessionImportOptions,
 } from './utils.sessionimport.js';
-import { settleToolOutput, wrapToolSet } from './utils.tooloutput.js';
+import { isAsyncIterable, settleToolOutput, wrapToolSet } from './utils.tooloutput.js';
 import {
   validateCompactSessionOptions,
   validateCreateProjectTaskInput,
@@ -435,6 +440,18 @@ interface IActiveRun {
   reasoningPartIds: Map<string, string>;
   toolPartIds: Map<string, string>;
   trustedToolExecutionErrors: Map<string, Error>;
+  /**
+   * The confirmations of read-only calls started while the model still streamed, by tool call ID:
+   * their permission requests wait for them.
+   */
+  unconfirmedToolCalls: Map<string, Promise<void>>;
+  /**
+   * The read-only calls of the turn by real name and canonical params, with the call that answers
+   * them. A call that is not read-only clears them when it runs.
+   */
+  readCalls: Map<string, IRunReadCall>;
+  /** Calls an identical earlier read answered: the call's ID to the earlier call's. */
+  deduplicatedToolCalls: Map<string, string>;
   subagentCallCount: number;
   subagentSessionIds: Set<string>;
   backgroundSubagents: Set<Promise<void>>;
@@ -450,6 +467,8 @@ interface IActiveRun {
   toolCatalog?: FlexToolCatalog<unknown>;
   /** The sandbox `run_code` programs run in, loaded when the catalog has code mode. */
   codeSandbox?: FlexCodeSandbox;
+  /** The tool handle's classifier of read-only calls. */
+  isReadOnlyHostCall?: IFlexToolHandle['isReadOnlyToolCall'];
   subagents: ReadonlyMap<string, Readonly<IFlexSubagentDefinition>>;
   allowedTools?: readonly string[];
   agentAllowedTools?: readonly string[];
@@ -462,6 +481,38 @@ interface IActiveRun {
   stop: AbortController;
 }
 
+/** The validated params of a `results.get` call. */
+interface IResultRead {
+  handle: string;
+  page?: number;
+  path?: string;
+}
+
+/** A read-only call of a turn and its output, which identical reads after it share. */
+interface IRunReadCall {
+  readonly toolCallId: string;
+  /** The call's output; `notShared` when it streams its output, which only its own call reads. */
+  readonly output: Promise<unknown>;
+}
+
+const notShared = Symbol('not shared');
+
+/** Runs `operation` after the operations queued before it under `key`, whatever their outcome. */
+function queueOperation<TResult>(
+  queues: Map<string, Promise<void>>,
+  key: string,
+  operation: () => Promise<TResult>,
+): Promise<TResult> {
+  const previous = queues.get(key) ?? Promise.resolve();
+  const result = previous.then(operation);
+  const barrier = result.then(() => undefined, () => undefined);
+  queues.set(key, barrier);
+  void barrier.then(() => {
+    if (queues.get(key) === barrier) queues.delete(key);
+  });
+  return result;
+}
+
 /** The steers of a run: the input its generation takes in, and the prompts it accepted for it. */
 interface IRunSteering {
   readonly input: plugins.AgentPendingInputQueue;
@@ -893,6 +944,8 @@ export class FlexHarness<TScope = unknown> {
   private readonly orphanedTombstoneOwners = new Map<string, IOrphanedTombstoneOwner<TScope>>();
   private readonly pendingPromptAdmissionOwners = new Set<IPendingPromptAdmission>();
   private readonly projectManagementQueues = new Map<string, Promise<void>>();
+  /** A session's result writes, one at a time: they share the session's index of results. */
+  private readonly resultQueues = new Map<string, Promise<void>>();
   private readonly activeSlashCommandExecutions = new Map<string, IActiveSlashCommandExecution>();
   private readonly activeSlashCommandListings = new Set<IActiveSlashCommandListing>();
   private readonly stagedSessionImports = new Map<string, IStagedSessionImport>();
@@ -4447,6 +4500,9 @@ export class FlexHarness<TScope = unknown> {
       reasoningPartIds: new Map(),
       toolPartIds: new Map(),
       trustedToolExecutionErrors: new Map(),
+      unconfirmedToolCalls: new Map(),
+      readCalls: new Map(),
+      deduplicatedToolCalls: new Map(),
       subagentCallCount: 0,
       subagentSessionIds: new Set(),
       backgroundSubagents: new Set(),
@@ -5280,17 +5336,7 @@ export class FlexHarness<TScope = unknown> {
     sessionId: string,
     operation: () => Promise<TResult>,
   ): Promise<TResult> {
-    const key = this.projectManagementKey(storageKey, sessionId);
-    const previous = this.projectManagementQueues.get(key) ?? Promise.resolve();
-    const result = previous.then(operation);
-    const barrier = result.then(() => undefined, () => undefined);
-    this.projectManagementQueues.set(key, barrier);
-    void barrier.then(() => {
-      if (this.projectManagementQueues.get(key) === barrier) {
-        this.projectManagementQueues.delete(key);
-      }
-    });
-    return result;
+    return queueOperation(this.projectManagementQueues, this.projectManagementKey(storageKey, sessionId), operation);
   }
 
   private async awaitProjectManagementOperations(
@@ -5781,8 +5827,14 @@ export class FlexHarness<TScope = unknown> {
       runId: run.runId,
       ...resolverRelationship,
       signal,
-      requestPermission: (request: IFlexPermissionRequestInput) =>
-        this.requestPermission(run.state, run, request),
+      requestPermission: async (request: IFlexPermissionRequestInput) => {
+        // A call that started early asks once the model's response confirmed it.
+        const confirmed = request.toolCallId === undefined
+          ? undefined
+          : run.unconfirmedToolCalls.get(request.toolCallId);
+        if (confirmed) await confirmed;
+        return this.requestPermission(run.state, run, request);
+      },
     });
     const toolOutcome = Promise.resolve()
       .then(() => this.provideRunToolHandle(run, toolProviderContext))
@@ -5851,10 +5903,13 @@ export class FlexHarness<TScope = unknown> {
       signal.throwIfAborted();
       run.modelResolution = model!;
       run.toolProviderContext = toolProviderContext as Readonly<IFlexToolProviderContext<unknown>>;
+      run.isReadOnlyHostCall = toolHandle?.isReadOnlyToolCall;
       let catalog: FlexToolCatalog<unknown> | undefined;
       if (toolHandle?.catalog) {
         try {
-          catalog = await FlexToolCatalog.create(toolHandle.catalog, this.toolCatalogOptions);
+          catalog = await FlexToolCatalog.create(toolHandle.catalog, this.toolCatalogOptions, {
+            results: this.stores.results !== undefined,
+          });
           if (catalog.codeMode) run.codeSandbox = await FlexCodeSandbox.load();
         } catch (error) {
           throw this.projectExternalError(run, error, 'toolProvider');
@@ -5877,17 +5932,18 @@ export class FlexHarness<TScope = unknown> {
           : Object.fromEntries(Object.entries(combinedTools).filter(([name]) => admitted(name)));
         const admittedCatalog = catalog && (globalNames === undefined && agentNames === undefined
           ? catalog
-          : catalog.restrict(catalog.methods.filter(admitted)));
+          : catalog.restrict(catalog.methods.filter((name) => name === FLEX_RESULT_METHOD || admitted(name))));
         if (admittedCatalog && admittedCatalog.methods.length > 0) {
           run.toolCatalog = admittedCatalog;
           Object.assign(admittedTools, this.createCatalogTools(run, admittedCatalog));
         }
         tools = Object.keys(admittedTools).length > 0
-          ? wrapToolSet(
+          ? this.trackToolCalls(run, wrapToolSet(
               admittedTools as TFlexAgentToolSet,
               this.toolOutputLimits,
               (toolError) => this.projectExternalError(run, toolError, 'toolExecution'),
-            )
+              (output) => this.budgetOutput(run, output),
+            ))
           : undefined;
       } catch (error) {
         throw this.projectExternalError(run, error, 'toolProvider');
@@ -5915,7 +5971,11 @@ export class FlexHarness<TScope = unknown> {
       return {
         model: model!.model,
         ...(options.system ?? model!.system ? { system: options.system ?? model!.system } : {}),
-        ...(tools ? { tools } : {}),
+        ...(tools ? {
+          tools,
+          isReadOnlyToolCall: ({ toolName, input }: { toolName: string; input: unknown }) =>
+            this.isReadOnlyToolCall(run, toolName, input),
+        } : {}),
         ...(model!.providerOptions ? { providerOptions: model!.providerOptions } : {}),
         ...(model!.cache === undefined ? {} : { cache: model!.cache }),
         ...(options.maxSteps ?? model!.maxSteps ? { maxSteps: options.maxSteps ?? model!.maxSteps } : {}),
@@ -5935,6 +5995,213 @@ export class FlexHarness<TScope = unknown> {
     }
   }
 
+  /**
+   * The output the model gets: the output itself within the output budget, or, in a run with a
+   * catalog whose stores keep results, a handle to the stored output with a summary of it.
+   */
+  private async budgetOutput(run: IActiveRun, output: unknown): Promise<TJsonValue> {
+    const results = this.stores.results;
+    const maxBytes = this.toolOutputLimits.maxBytes;
+    if (!results || !run.toolCatalog) return normalizeJsonValue(output, this.toolOutputLimits);
+    const stored = normalizeJsonValue(output, {
+      ...this.toolOutputLimits,
+      maxBytes: Math.max(maxBytes, FLEX_RESULT_LIMITS.maxStoredBytes),
+    });
+    const bytes = jsonBytes(stored);
+    if (bytes <= maxBytes) return stored;
+    const handle = `res_${plugins.crypto.randomBytes(8).toString('hex')}`;
+    const read = `Too large to return whole: read it page by page with execute({ method: "${FLEX_RESULT_METHOD}", `
+      + `params: { handle: "${handle}", page: 1 } })${run.toolCatalog.codeMode
+        ? `, or in run_code with await api.results.get("${handle}", { page: 1 })`
+        : ''}; a dotted \`path\` reads a part of it.`;
+    const result: IFlexResultHandle = {
+      $flexType: 'result',
+      handle,
+      bytes,
+      pages: resultPage(stored, '', 1, this.resultPageBytes())!.pages,
+      summary: summarizeResult(stored, Math.min(FLEX_RESULT_LIMITS.summaryBytes, Math.floor(maxBytes / 4))),
+      read,
+    };
+    // A budget too small for even the handle keeps the truncated output.
+    if (jsonBytes(result) > maxBytes) return normalizeJsonValue(output, this.toolOutputLimits);
+    const { storageKey } = run.state;
+    await queueOperation(this.resultQueues, this.resultQueueKey(storageKey, run.sessionId), async () => {
+      await results.save(storageKey, run.sessionId, handle, stored);
+      // The session keeps its latest results; older ones are deleted.
+      const handles = await results.list(storageKey, run.sessionId);
+      for (const old of handles.slice(0, Math.max(0, handles.length - FLEX_RESULT_LIMITS.maxResultsPerSession))) {
+        await results.delete(storageKey, run.sessionId, old);
+      }
+    });
+    return result as unknown as TJsonValue;
+  }
+
+  private resultQueueKey(storageKey: string, sessionId: string): string {
+    return JSON.stringify([storageKey, sessionId]);
+  }
+
+  /** The JSON bytes of one `results.get` page: the output budget, less room for the page's fields. */
+  private resultPageBytes(): number {
+    return Math.max(64, this.toolOutputLimits.maxBytes - 512);
+  }
+
+  /** One page of a stored result of the run's session, or the error `results.get` reports. */
+  private async readResult(
+    run: IActiveRun,
+    params: IResultRead,
+  ): Promise<{ ok: true; value: TJsonValue } | { ok: false; error: TJsonValue }> {
+    const method = FLEX_RESULT_METHOD;
+    const stored = await this.stores.results!.load(run.state.storageKey, run.sessionId, params.handle);
+    if (stored === undefined) {
+      return { ok: false, error: { error: 'unknown_handle', method, handle: params.handle, hint: `A handle reads one of the latest ${FLEX_RESULT_LIMITS.maxResultsPerSession} results this session stored.` } };
+    }
+    const path = params.path ?? '';
+    const value = selectPath(stored, path);
+    if (value === undefined) {
+      return { ok: false, error: { error: 'unknown_path', method, path, hint: `The result is ${describeShape(stored)}.` } };
+    }
+    const page = params.page ?? 1;
+    const content = resultPage(value, path, page, this.resultPageBytes());
+    if (!content) {
+      const pages = resultPage(value, path, 1, this.resultPageBytes())!.pages;
+      return { ok: false, error: { error: 'unknown_page', method, page, pages } };
+    }
+    return {
+      ok: true,
+      value: { handle: params.handle, path, page, pages: content.pages, ...content.range, value: content.value },
+    };
+  }
+
+  /**
+   * Whether a call of the run's tools only reads: search_tools and describe_tools, an `execute` of
+   * a method declared read-only, or a call the tool handle classifies as read-only by its real name.
+   */
+  private isReadOnlyToolCall(run: IActiveRun, toolName: string, input: unknown): boolean {
+    const names = FLEX_TOOL_CATALOG_TOOL_NAMES;
+    const catalog = run.toolCatalog;
+    if (catalog) {
+      if (toolName === names.search || toolName === names.describe) return true;
+      if (toolName === names.execute) {
+        const target = catalog.callTarget(input);
+        return target !== undefined && this.isReadOnlyCatalogCall(run, catalog, target.method, target.params);
+      }
+      if (toolName === FLEX_CODE_MODE_TOOL_NAME) return false;
+    }
+    if (this.enabledBuiltInToolNames(run).has(toolName)) return false;
+    return this.classifyHostToolCall(run, toolName, input);
+  }
+
+  /** The method's path when the prepared call only reads, for the turn's reads. */
+  private readOnlyMethod(
+    run: IActiveRun,
+    catalog: FlexToolCatalog<unknown>,
+    call: { method: string; params: unknown },
+  ): string | undefined {
+    return this.isReadOnlyCatalogCall(run, catalog, call.method, call.params) ? call.method : undefined;
+  }
+
+  /** A method whose `onCall` decides its calls is gated: its calls run in order, whatever they read. */
+  private isReadOnlyCatalogCall(
+    run: IActiveRun,
+    catalog: FlexToolCatalog<unknown>,
+    method: string,
+    params: unknown,
+  ): boolean {
+    return !catalog.decides(method)
+      && (catalog.isReadOnly(method) || this.classifyHostToolCall(run, method, params));
+  }
+
+  private classifyHostToolCall(run: IActiveRun, toolName: string, input: unknown): boolean {
+    try {
+      return run.isReadOnlyHostCall?.({ toolName, input }) === true;
+    } catch (error) {
+      throw this.projectExternalError(run, error, 'toolProvider');
+    }
+  }
+
+  /**
+   * Runs the run's tools through the turn's reads: a read-only call identical to an earlier read of
+   * the turn shares its output, and any other call clears them. Records the confirmation of each
+   * call that started while the model still streamed, which the permission requests naming the
+   * call wait for. The catalog's tools read and run their methods by real name themselves.
+   */
+  private trackToolCalls(run: IActiveRun, tools: TFlexAgentToolSet): TFlexAgentToolSet {
+    const catalogTools = new Set<string>(run.toolCatalog
+      ? [...Object.values(FLEX_TOOL_CATALOG_TOOL_NAMES), FLEX_CODE_MODE_TOOL_NAME]
+      : []);
+    const tracked: Record<string, unknown> = {};
+    for (const [name, tool] of Object.entries(tools)) {
+      const execute = (tool as { execute?: (input: unknown, options: unknown) => unknown }).execute;
+      if (typeof execute !== 'function') {
+        tracked[name] = tool;
+        continue;
+      }
+      tracked[name] = {
+        ...tool,
+        execute: (input: unknown, options: plugins.IAgentToolExecutionOptions & { toolCallId?: string }) => {
+          const confirmed = options?.confirmed;
+          const toolCallId = options?.toolCallId ?? '';
+          if (confirmed && toolCallId) {
+            run.unconfirmedToolCalls.set(toolCallId, confirmed);
+            const forget = () => run.unconfirmedToolCalls.delete(toolCallId);
+            confirmed.then(forget, forget);
+          }
+          const executeTool = () => execute.call(tool, input, options);
+          if (catalogTools.has(name)) return executeTool();
+          const readName = this.isReadOnlyToolCall(run, name, input) ? name : undefined;
+          return this.readOnce(run, toolCallId, readName, input, confirmed, executeTool);
+        },
+      };
+    }
+    return tracked as TFlexAgentToolSet;
+  }
+
+  /**
+   * Answers a read-only call (`name` set) from an identical read earlier in the turn, sharing the
+   * output of one still running, or runs it and keeps its output for the reads after it. A failed
+   * read, and a read whose response was discarded, are not kept. Any other call clears the turn's
+   * reads before it runs.
+   */
+  private readOnce(
+    run: IActiveRun,
+    toolCallId: string,
+    name: string | undefined,
+    params: unknown,
+    confirmed: Promise<void> | undefined,
+    execute: () => unknown,
+  ): unknown {
+    if (name === undefined) {
+      run.readCalls.clear();
+      return execute();
+    }
+    const canonicalParams = canonicalJson(params);
+    if (canonicalParams === undefined) return execute();
+    const key = `${name}\n${canonicalParams}`;
+    const earlier = run.readCalls.get(key);
+    if (earlier) {
+      return earlier.output.then((output) => {
+        if (output === notShared) return execute();
+        run.deduplicatedToolCalls.set(toolCallId, earlier.toolCallId);
+        return output;
+      }, (error: unknown) => {
+        run.deduplicatedToolCalls.set(toolCallId, earlier.toolCallId);
+        throw error;
+      });
+    }
+    const result = execute();
+    const entry: IRunReadCall = {
+      toolCallId,
+      output: Promise.resolve(result).then((output) => isAsyncIterable(output) ? notShared : output),
+    };
+    run.readCalls.set(key, entry);
+    const forget = () => {
+      if (run.readCalls.get(key) === entry) run.readCalls.delete(key);
+    };
+    entry.output.catch(forget);
+    confirmed?.catch(forget);
+    return result;
+  }
+
   private enabledBuiltInToolNames(run: IActiveRun): Set<string> {
     const names = new Set<string>();
     if (run.subagents.size > 0 && (run.stored.session.depth ?? 0) < this.maxSubagentDepth) {
@@ -5995,15 +6262,35 @@ export class FlexHarness<TScope = unknown> {
         ),
         execute: async (
           input: { method: string; params?: Record<string, unknown> },
-          options?: { toolCallId?: string; abortSignal?: AbortSignal },
+          options?: { toolCallId?: string; abortSignal?: AbortSignal } & plugins.IAgentToolExecutionOptions,
         ) => {
           const toolCallId = options?.toolCallId ?? '';
           const abortSignal = options?.abortSignal ?? run.controller.signal;
+          const confirmed = options?.confirmed;
           const call = await catalog.prepareCall(input.method, input.params);
           if (!call.success) throw this.catalogCallError(run, toolCallId, call.error);
-          const context = { method: call.method, toolCallId, abortSignal, provider: run.toolProviderContext! };
+          if (call.method === FLEX_RESULT_METHOD) {
+            const read = await this.readResult(run, call.params as IResultRead);
+            if (!read.ok) throw this.catalogCallError(run, toolCallId, read.error);
+            return read.value;
+          }
+          // A call that started early asks for permission once the response confirmed it.
+          const base = run.toolProviderContext!;
+          const provider = confirmed
+            ? Object.freeze({
+                ...base,
+                requestPermission: async (request: IFlexPermissionRequestInput) => {
+                  await confirmed;
+                  return base.requestPermission(request);
+                },
+              })
+            : base;
+          const context = { method: call.method, toolCallId, abortSignal, provider };
           const decision = await call.decide(context);
-          if (decision === 'run') return call.run(context);
+          if (decision === 'run') {
+            return this.readOnce(run, toolCallId, this.readOnlyMethod(run, catalog, call), call.params, confirmed,
+              () => call.run(context));
+          }
           if (decision === 'propose') {
             return catalog.propose(
               [{ id: toolCallId, method: call.method, params: call.params }],
@@ -6075,51 +6362,97 @@ export class FlexHarness<TScope = unknown> {
     });
     const stopped = (method: string) => ({ ok: false as const, error: { error: 'aborted', method } });
     let callNumber = 0;
+    // Read-only calls run concurrently; any other call runs after every call the program made before it.
+    const order = new plugins.AgentToolCallScheduler(abortSignal);
     const finish = (id: string, method: string, input: unknown, outcome: { output: unknown } | { error: Error }) => {
       if ('error' in outcome) run.trustedToolExecutionErrors.set(id, outcome.error);
       this.onToolFinish(run.state, run.sessionId, 'error' in outcome
         ? { toolCallId: id, toolName: method, input, success: false, error: outcome.error.message }
         : { toolCallId: id, toolName: method, input, success: true, output: outcome.output });
     };
+    const callInTurn = async (
+      id: string,
+      method: string,
+      params: unknown,
+      signal: AbortSignal,
+      classification: { readOnly: boolean } | { error: Error },
+    ): Promise<TFlexCodeCallOutcome> => {
+      const call = await catalog.prepareCall(method, params);
+      if (!call.success) {
+        if (catalog.has(method)) {
+          this.onToolStart(run.state, run.sessionId, { toolCallId: id, toolName: method, input: params ?? {}, parentToolCallId: toolCallId });
+          finish(id, method, params, { error: this.catalogCallError(run, id, call.error) });
+        }
+        return { ok: false, error: call.error as unknown as TJsonValue };
+      }
+      try {
+        await order.waitForTurn(id, signal);
+      } catch {
+        return stopped(call.method);
+      }
+      if (signal.aborted) return stopped(call.method);
+      this.onToolStart(run.state, run.sessionId, {
+        toolCallId: id, toolName: call.method, input: call.params, parentToolCallId: toolCallId,
+      });
+      if ('error' in classification) {
+        finish(id, call.method, call.params, { error: classification.error });
+        return { ok: false, error: { error: 'failed', method: call.method, message: classification.error.message } };
+      }
+      if (call.method === FLEX_RESULT_METHOD) {
+        const read = await this.readResult(run, call.params as IResultRead);
+        finish(id, call.method, call.params, read.ok
+          ? { output: read.value }
+          : { error: this.catalogCallError(run, id, read.error) });
+        return read;
+      }
+      const readOnly = classification.readOnly;
+      const context = { method: call.method, toolCallId: id, abortSignal: signal, provider: providerFor(signal) };
+      try {
+        const decision = await call.decide(context);
+        signal.throwIfAborted();
+        if (decision === 'propose') {
+          proposals.push({ id, method: call.method, params: call.params });
+          const value = { proposed: true, id };
+          finish(id, call.method, call.params, { output: value });
+          return { ok: true, value };
+        }
+        if (decision !== 'run') {
+          const payload = { error: 'denied' as const, method: call.method, reason: decision.deny };
+          finish(id, call.method, call.params, { error: this.catalogCallError(run, id, payload) });
+          return { ok: false, error: payload };
+        }
+        const output = this.readOnce(run, id, readOnly ? call.method : undefined, call.params, undefined,
+          () => call.run(context));
+        const value = await this.budgetOutput(run, await settleToolOutput(output));
+        finish(id, call.method, call.params, { output: value });
+        return { ok: true, value };
+      } catch (error) {
+        const projected = this.projectExternalError(run, error, 'toolExecution');
+        finish(id, call.method, call.params, { error: projected });
+        return { ok: false, error: { error: 'failed', method: call.method, message: projected.message } };
+      }
+    };
     const host: IFlexCodeHost = {
       waitedMs: () => waitedMs + (waiting > 0 ? performance.now() - waitingSince : 0),
       call: async (method, params, signal) => {
         if (signal.aborted) return stopped(method);
         const id = `${toolCallId}.${++callNumber}`;
-        const call = await catalog.prepareCall(method, params);
-        if (!call.success) {
-          if (catalog.has(method)) {
-            this.onToolStart(run.state, run.sessionId, { toolCallId: id, toolName: method, input: params ?? {}, parentToolCallId: toolCallId });
-            finish(id, method, params, { error: this.catalogCallError(run, id, call.error) });
-          }
-          return { ok: false, error: call.error as unknown as TJsonValue };
-        }
-        if (signal.aborted) return stopped(call.method);
-        this.onToolStart(run.state, run.sessionId, {
-          toolCallId: id, toolName: call.method, input: call.params, parentToolCallId: toolCallId,
-        });
-        const context = { method: call.method, toolCallId: id, abortSignal: signal, provider: providerFor(signal) };
+        // The call takes its place in the program's order now, before anything is awaited.
+        let classification: { readOnly: boolean } | { error: Error };
         try {
-          const decision = await call.decide(context);
-          signal.throwIfAborted();
-          if (decision === 'propose') {
-            proposals.push({ id, method: call.method, params: call.params });
-            const value = { proposed: true, id };
-            finish(id, call.method, call.params, { output: value });
-            return { ok: true, value };
-          }
-          if (decision !== 'run') {
-            const payload = { error: 'denied' as const, method: call.method, reason: decision.deny };
-            finish(id, call.method, call.params, { error: this.catalogCallError(run, id, payload) });
-            return { ok: false, error: payload };
-          }
-          const value = normalizeJsonValue(await settleToolOutput(call.run(context)), this.toolOutputLimits);
-          finish(id, call.method, call.params, { output: value });
-          return { ok: true, value };
+          classification = {
+            readOnly: catalog.has(method) && this.isReadOnlyCatalogCall(run, catalog, method, params ?? {}),
+          };
         } catch (error) {
-          const projected = this.projectExternalError(run, error, 'toolExecution');
-          finish(id, call.method, call.params, { error: projected });
-          return { ok: false, error: { error: 'failed', method: call.method, message: projected.message } };
+          classification = {
+            error: error instanceof Error ? error : this.projectExternalError(run, error, 'toolProvider'),
+          };
+        }
+        order.begin(id, 'readOnly' in classification && classification.readOnly);
+        try {
+          return await callInTurn(id, method, params, signal, classification);
+        } finally {
+          order.settle(id);
         }
       },
     };
@@ -8698,6 +9031,10 @@ export class FlexHarness<TScope = unknown> {
         delete part.output;
         part.error = projectedError!.message;
       }
+      const original = run.deduplicatedToolCalls.get(event.toolCallId);
+      if (original !== undefined) {
+        part.deduplicatedFrom = this.boundedIdentifier(original, 'deduplicatedFrom');
+      }
       part.completedAt = new Date().toISOString();
       this.emitPartEvent(run, 'part.completed', part);
     } catch (error) {
@@ -9362,10 +9699,17 @@ export class FlexHarness<TScope = unknown> {
       if (catalog !== undefined && (typeof catalog !== 'object' || catalog === null)) {
         throw new FlexHarnessValidationError('Tool handle catalog must be an object.');
       }
+      const isReadOnlyToolCall = handle.isReadOnlyToolCall;
+      if (isReadOnlyToolCall !== undefined && typeof isReadOnlyToolCall !== 'function') {
+        throw new FlexHarnessValidationError('Tool handle isReadOnlyToolCall must be a function.');
+      }
       const closeHandle = close;
       return {
         tools,
         ...(catalog === undefined ? {} : { catalog }),
+        ...(isReadOnlyToolCall === undefined ? {} : {
+          isReadOnlyToolCall: (call: { toolName: string; input: unknown }) => isReadOnlyToolCall.call(handle, call),
+        }),
         ...(closeHandle ? { close: () => closeHandle.call(handle) } : {}),
       };
     } catch (error) {
@@ -9394,6 +9738,8 @@ export class FlexHarness<TScope = unknown> {
     const descriptors = this.normalizeResourceToolProviderDescriptors(resolved);
     const owned: Array<{ handle: IFlexToolHandle; closed: boolean }> = [];
     const tools: Record<string, unknown> = Object.create(null) as Record<string, unknown>;
+    /** The handle and own name of each exposed resource tool, for the handle's classifier. */
+    const resourceTools = new Map<string, { handle: IFlexToolHandle; toolName: string }>();
     const closeOwned = async (): Promise<void> => {
       const errors: unknown[] = [];
       for (const entry of [...owned].reverse()) {
@@ -9461,12 +9807,23 @@ export class FlexHarness<TScope = unknown> {
             throw new FlexHarnessValidationError(`Duplicate exposed tool "${exposedName}".`);
           }
           tools[exposedName] = tool;
+          resourceTools.set(exposedName, { handle, toolName });
         }
       }
       if (owned.length === 0 && Object.keys(tools).length === 0) return undefined;
+      const classifies = applicationHandle?.isReadOnlyToolCall !== undefined
+        || [...resourceTools.values()].some((entry) => entry.handle.isReadOnlyToolCall !== undefined);
       return {
         tools: tools as TFlexAgentToolSet,
         ...(applicationHandle?.catalog === undefined ? {} : { catalog: applicationHandle.catalog }),
+        ...(classifies ? {
+          isReadOnlyToolCall: ({ toolName, input }: { toolName: string; input: unknown }) => {
+            const resource = resourceTools.get(toolName);
+            return resource
+              ? resource.handle.isReadOnlyToolCall?.({ toolName: resource.toolName, input }) === true
+              : applicationHandle?.isReadOnlyToolCall?.({ toolName, input }) === true;
+          },
+        } : {}),
         ...(owned.some((entry) => entry.handle.close) ? { close: closeOwned } : {}),
       };
     } catch (error) {
@@ -10906,11 +11263,18 @@ export class FlexHarness<TScope = unknown> {
         tombstone,
       );
     };
+    const resultStore = this.stores.results;
+    const resultCleanup = async (): Promise<void> => {
+      // A result being saved for the session is written before its results are deleted.
+      await this.resultQueues.get(this.resultQueueKey(storageKey, sessionId));
+      await resultStore!.deleteSession(storageKey, sessionId);
+    };
     const results = await Promise.allSettled([
       this.stores.agentEvents.deleteSession(storageKey, sessionId),
       this.stores.jobs.deleteSession(storageKey, sessionId),
       this.stores.projections.deleteSession(storageKey, sessionId),
       this.stores.permissions.deleteSession(storageKey, sessionId),
+      ...(resultStore ? [resultCleanup()] : []),
       // An imported session refuses every project-management write, so it has no state to fence.
       ...(tombstone.imported ? [] : [projectManagementCleanup()]),
     ]);