@modelprofile.com/flexharness 11.0.1 → 11.1.0

package/ts/classes.codesandbox.worker.ts

@@ -0,0 +1,345 @@
+/**
+ * The QuickJS side of a `run_code` program. `FlexCodeSandbox` runs every program in a worker thread of
+ * its own with this module, and ends it by terminating the worker, which frees its WebAssembly instance
+ * too: a native operation that never reaches QuickJS's interrupt handler cannot outlast its limits, and
+ * a program never blocks the host's event loop.
+ *
+ * Written in erasable TypeScript that imports nothing of the package at run time, so the module loads
+ * uncompiled as well.
+ */
+import { parentPort } from 'node:worker_threads';
+import type * as plugins from './plugins.js';
+
+/** Evaluating the prelude, the program's text, or running the program. */
+export type TCodeWorkerPhase = 'prelude' | 'parse' | 'program';
+
+/** The limits of a program that its worker enforces itself. */
+export interface ICodeWorkerLimits {
+  cpuMs: number;
+  memoryBytes: number;
+  stackBytes: number;
+  maxLogBytes: number;
+}
+
+/** What the host sends a program's worker. */
+export type TCodeWorkerRequest =
+  | { kind: 'start'; program: string; limits: ICodeWorkerLimits }
+  | { kind: 'answer'; id: number; text: string };
+
+/**
+ * What a program's worker reports. `ready` comes once QuickJS is loaded; every `start` and `answer`
+ * ends in `idle`, with the milliseconds computed so far, unless the program stopped. `done` counts the
+ * calls the program had no answer to when it returned.
+ */
+export type TCodeWorkerReport =
+  | { kind: 'ready' }
+  | { kind: 'call'; id: number; method: string; params: string }
+  | { kind: 'log'; text: string }
+  | { kind: 'idle'; cpuMs: number }
+  | { kind: 'done'; text: string; unawaited: number }
+  | { kind: 'failed'; phase: TCodeWorkerPhase; name?: string; message?: string; stack?: string; dumped?: string }
+  | { kind: 'stopped'; limit: 'cpu' | 'stack' };
+
+/** The file name the program's text is evaluated as: the host reads a failure's line in it from the stack. */
+const programFile = 'program.ts';
+
+/**
+ * Runs in the context before the program: it takes the host functions off the global object and
+ * defines `api`, `ApiError` and `console`. Only strings cross the boundary.
+ */
+const prelude = `'use strict';
+(() => {
+  const call = globalThis.__flexCall;
+  const log = globalThis.__flexLog;
+  const done = globalThis.__flexDone;
+  delete globalThis.__flexCall;
+  delete globalThis.__flexLog;
+  delete globalThis.__flexDone;
+  class ApiError extends Error {
+    constructor(details) {
+      const message = details && typeof details.message === 'string' ? details.message : JSON.stringify(details);
+      super(message);
+      this.name = 'ApiError';
+      this.details = details;
+    }
+  }
+  const invoke = (path, args) => {
+    if (!path) return Promise.reject(new TypeError('Call a method as api.<namespace>.<method>(params).'));
+    let params;
+    try {
+      // api.results.get(handle, { page, path }) reads a stored result.
+      const argument = path === 'results.get' && typeof args[0] === 'string'
+        ? Object.assign({}, args[1], { handle: args[0] })
+        : args[0];
+      params = JSON.stringify(args.length === 0 || argument === undefined ? {} : argument);
+    } catch (error) {
+      return Promise.reject(new TypeError('The params of ' + path + ' are not JSON: ' + error.message));
+    }
+    return call(path, params === undefined ? 'null' : params).then((text) => {
+      const outcome = JSON.parse(text);
+      if (outcome.ok) return outcome.value;
+      throw new ApiError(outcome.error);
+    });
+  };
+  const target = (path) => new Proxy(function () {}, {
+    get: (_target, key) => typeof key === 'string' && key !== 'then' ? target(path ? path + '.' + key : key) : undefined,
+    apply: (_target, _this, args) => invoke(path, args),
+    set: () => false,
+    defineProperty: () => false,
+    deleteProperty: () => false,
+  });
+  const format = (value) => {
+    if (typeof value === 'string') return value;
+    try {
+      const text = JSON.stringify(value);
+      return text === undefined ? String(value) : text;
+    } catch {
+      return String(value);
+    }
+  };
+  const writer = (level) => (...values) => { log(level, values.map(format).join(' ')); };
+  const fixed = (value) => ({ value, enumerable: false, writable: false, configurable: false });
+  Object.defineProperty(globalThis, 'api', fixed(target('')));
+  Object.defineProperty(globalThis, 'ApiError', fixed(ApiError));
+  Object.defineProperty(globalThis, 'console', fixed(Object.freeze({
+    log: writer('log'), info: writer('info'), warn: writer('warn'), error: writer('error'), debug: writer('debug'),
+  })));
+  const settle = (value) => {
+    try {
+      const text = JSON.stringify({ ok: true, value: value === undefined ? null : value });
+      return text === undefined ? JSON.stringify({ ok: true, value: null }) : text;
+    } catch (error) {
+      return JSON.stringify({ ok: false, name: 'TypeError', message: 'The return value is not JSON: ' + error.message });
+    }
+  };
+  const fail = (error) => JSON.stringify({
+    ok: false,
+    name: error && typeof error.name === 'string' ? error.name : 'Error',
+    message: error && typeof error.message === 'string' ? error.message : String(error),
+    stack: error && typeof error.stack === 'string' ? error.stack : '',
+    ...(error instanceof ApiError ? { details: error.details } : {}),
+  });
+  Object.defineProperty(globalThis, '__flexStart', {
+    configurable: true,
+    value: () => {
+      const main = globalThis.__flexMain;
+      delete globalThis.__flexStart;
+      delete globalThis.__flexMain;
+      main().then(settle, fail).then(done);
+    },
+  });
+})();
+`;
+
+/**
+ * One program in its QuickJS runtime. It enforces the limits QuickJS can see: memory, stack, console
+ * output, and computing time at every interrupt point. The host enforces the rest, and ends the worker
+ * when the program computes past its time between two interrupt points.
+ */
+class CodeWorkerRun {
+  private readonly report: (report: TCodeWorkerReport) => void;
+  private readonly limits: ICodeWorkerLimits;
+  private readonly runtime: plugins.IQuickJsRuntime;
+  private readonly vm: plugins.IQuickJsContext;
+  private readonly deferreds = new Map<number, plugins.IQuickJsDeferredPromise>();
+  private nextCallId = 0;
+  private cpuMs = 0;
+  private enteredAt?: number;
+  private stopped?: 'cpu' | 'stack';
+  private ended = false;
+  private logBytes = 0;
+  private logsCut = false;
+
+  constructor(module: plugins.IQuickJsModule, limits: ICodeWorkerLimits, report: (report: TCodeWorkerReport) => void) {
+    this.limits = limits;
+    this.report = report;
+    this.runtime = module.newRuntime();
+    this.runtime.setMemoryLimit(limits.memoryBytes);
+    this.runtime.setMaxStackSize(limits.stackBytes);
+    this.runtime.setInterruptHandler(() => this.interrupted());
+    this.vm = this.runtime.newContext();
+    this.define('__flexCall', (pathHandle, paramsHandle) => this.call(this.vm.getString(pathHandle), this.vm.getString(paramsHandle)));
+    this.define('__flexLog', (levelHandle, textHandle) => {
+      this.log(this.vm.getString(levelHandle), this.vm.getString(textHandle));
+    });
+    this.define('__flexDone', (textHandle) => {
+      this.ended = true;
+      this.report({ kind: 'done', text: this.vm.getString(textHandle), unawaited: this.deferreds.size });
+    });
+  }
+
+  public start(program: string): void {
+    if (this.evaluate(prelude, 'prelude.js', 'prelude')
+      && this.evaluate(program, programFile, 'parse')
+      && this.evaluate('__flexStart();', 'start.js', 'program')) {
+      this.pump();
+    }
+    this.idle();
+  }
+
+  /** Settles a call of the program with the host's outcome, and runs what it unblocked. */
+  public answer(id: number, text: string): void {
+    const deferred = this.deferreds.get(id);
+    if (!deferred || this.ended) return;
+    this.deferreds.delete(id);
+    const value = this.vm.newString(text);
+    deferred.resolve(value);
+    value.dispose();
+    this.pump();
+    this.idle();
+  }
+
+  private define(name: string, implementation: (...args: plugins.IQuickJsHandle[]) => plugins.IQuickJsHandle | void): void {
+    const handle = this.vm.newFunction(name, implementation);
+    this.vm.setProp(this.vm.global, name, handle);
+    handle.dispose();
+  }
+
+  private call(method: string, params: string): plugins.IQuickJsHandle {
+    const deferred = this.vm.newPromise();
+    const id = this.nextCallId++;
+    this.deferreds.set(id, deferred);
+    this.report({ kind: 'call', id, method, params });
+    return deferred.handle;
+  }
+
+  private log(level: string, text: string): void {
+    if (this.logsCut) return;
+    const line = `${level === 'log' ? '' : `[${level}] `}${text}\n`;
+    const bytes = Buffer.byteLength(line, 'utf8');
+    if (this.logBytes + bytes > this.limits.maxLogBytes) {
+      this.logsCut = true;
+      this.report({ kind: 'log', text: '[console output cut off]\n' });
+      return;
+    }
+    this.logBytes += bytes;
+    this.report({ kind: 'log', text: line });
+  }
+
+  private evaluate(code: string, file: string, phase: TCodeWorkerPhase): boolean {
+    if (this.over()) return false;
+    let result: plugins.TQuickJsResult;
+    this.enter();
+    try {
+      result = this.vm.evalCode(code, file);
+    } catch (error) {
+      this.hostThrow(error);
+      return false;
+    } finally {
+      this.leave();
+    }
+    if (result.error) {
+      this.failWith(result.error, phase);
+      return false;
+    }
+    result.value.dispose();
+    return true;
+  }
+
+  /** Runs the program's pending jobs after a call settled or the program started. */
+  private pump(): void {
+    if (this.over()) return;
+    let result: { error?: plugins.IQuickJsHandle };
+    this.enter();
+    try {
+      result = this.runtime.executePendingJobs();
+    } catch (error) {
+      this.hostThrow(error);
+      return;
+    } finally {
+      this.leave();
+    }
+    if (result.error) this.failWith(result.error, 'program');
+  }
+
+  /** The worker's own stack ran out under deep recursion; anything else is a failure of the worker. */
+  private hostThrow(error: unknown): void {
+    if (!(error instanceof RangeError)) throw error;
+    this.stop('stack');
+  }
+
+  private failWith(handle: plugins.IQuickJsHandle, phase: TCodeWorkerPhase): void {
+    let dumped: unknown;
+    // Reading the thrown value can run program code, such as a toJSON: it counts as computing.
+    this.enter();
+    try {
+      dumped = this.vm.dump(handle);
+    } catch {
+      dumped = undefined;
+    } finally {
+      this.leave();
+    }
+    if (this.stopped) {
+      this.stop(this.stopped);
+      return;
+    }
+    this.ended = true;
+    const error = (dumped && typeof dumped === 'object' ? dumped : { message: String(dumped) }) as {
+      name?: unknown; message?: unknown; stack?: unknown;
+    };
+    this.report({
+      kind: 'failed',
+      phase,
+      ...(typeof error.name === 'string' ? { name: error.name } : {}),
+      ...(typeof error.message === 'string' ? { message: error.message } : {}),
+      ...(typeof error.stack === 'string' ? { stack: error.stack } : {}),
+      ...(phase === 'prelude' ? { dumped: JSON.stringify(dumped) } : {}),
+    });
+  }
+
+  private stop(limit: 'cpu' | 'stack'): void {
+    this.stopped = limit;
+    if (this.ended) return;
+    this.ended = true;
+    this.report({ kind: 'stopped', limit });
+  }
+
+  private over(): boolean {
+    return this.ended || this.stopped !== undefined;
+  }
+
+  private idle(): void {
+    if (!this.over()) this.report({ kind: 'idle', cpuMs: this.cpuMs });
+  }
+
+  private enter(): void {
+    this.enteredAt = performance.now();
+  }
+
+  private leave(): void {
+    if (this.enteredAt === undefined) return;
+    this.cpuMs += performance.now() - this.enteredAt;
+    this.enteredAt = undefined;
+  }
+
+  private interrupted(): boolean {
+    if (this.stopped) return true;
+    if (this.enteredAt !== undefined && this.cpuMs + performance.now() - this.enteredAt > this.limits.cpuMs) {
+      this.stopped = 'cpu';
+      return true;
+    }
+    return false;
+  }
+}
+
+const port = parentPort;
+if (port) {
+  // The variant's typings resolve as CommonJS; at run time the default export is the variant.
+  const [core, variant] = await Promise.all([
+    import('quickjs-emscripten-core'),
+    import('@jitl/quickjs-ng-wasmfile-release-sync'),
+  ]);
+  const quickjsVariant = (variant as { default: unknown }).default as Parameters<typeof core.newQuickJSWASMModuleFromVariant>[0];
+  const module = await core.newQuickJSWASMModuleFromVariant(quickjsVariant) as unknown as plugins.IQuickJsModule;
+  const report = (message: TCodeWorkerReport): void => port.postMessage(message);
+  let run: CodeWorkerRun | undefined;
+  port.on('message', (request: TCodeWorkerRequest) => {
+    if (request.kind === 'start') {
+      run = new CodeWorkerRun(module, request.limits, report);
+      run.start(request.program);
+    } else {
+      run?.answer(request.id, request.text);
+    }
+  });
+  report({ kind: 'ready' });
+}

package/ts/classes.flexharness.callbacks.ts

@@ -8,17 +8,29 @@ import {
   type TFlexAgentToolCallUpdateEvent,
   type TFlexAgentToolCallFinishEvent,
   type TFlexMessagePart,
+  type TJsonValue,
 } from './interfaces.js';
-import { normalizeJsonValue } from './utils.json.js';
-import { jsonBytes } from './utils.transfer.js';
+import { MIN_MAX_BYTES, normalizeJsonValue } from './utils.json.js';
+import { jsonBytes, truncateUtf8 } from './utils.transfer.js';
 import {
   observeSessionMetricsCall,
   settleSessionMetricsOperation,
   type ISessionMetricsOperation,
 } from './utils.sessionmetrics.js';
-import type { IStoredSessionState, IStorageState, IActiveRun } from './interfaces.flexharness.js';
+import type {
+  IStoredSessionState,
+  IStorageState,
+  IActiveRun,
+  IProgramCallbackShare,
+} from './interfaces.flexharness.js';
 import type { FlexHarnessCore } from './classes.flexharness.core.js';
 
+/** How a tool call ended, as its part records it. */
+type TToolPartOutcome = { output: TJsonValue } | { error: string };
+
+const outcomeBytes = (outcome: TToolPartOutcome): number =>
+  'output' in outcome ? jsonBytes(outcome.output) : Buffer.byteLength(outcome.error);
+
 /** The model stream callbacks of a run: text, reasoning, tool, retry and usage events. */
 export class FlexHarnessRunCallbacks<TScope> {
   constructor(private readonly core: FlexHarnessCore<TScope>) {}
@@ -27,10 +39,11 @@ export class FlexHarnessRunCallbacks<TScope> {
     const run = this.callbackRun(state, sessionId);
     if (!run || !delta) return;
     const lastPart = run.callbackParts.at(-1);
-    const created = lastPart?.type !== 'text';
-    const part = lastPart?.type === 'text'
+    const openPart = lastPart?.type === 'text' && !run.completedTextPartIds.has(lastPart.partId)
       ? lastPart
-      : { partId: plugins.crypto.randomUUID(), type: 'text' as const, text: '' };
+      : undefined;
+    const created = !openPart;
+    const part = openPart ?? { partId: plugins.crypto.randomUUID(), type: 'text' as const, text: '' };
     const accounting = this.textAppendAccounting(run, part, delta, created);
     if (!accounting) return;
     if (!this.reserveCallbackCapacity(
@@ -105,6 +118,22 @@ export class FlexHarnessRunCallbacks<TScope> {
     this.core.emitPartEvent(run, 'part.completed', part);
   }
 
+  /**
+   * Completes the text parts of a committed model step: their text is final and saved. A text part
+   * completes once, so the terminal projection completes only the text parts of a step that did
+   * not commit. Like the terminal's completions, these events are outside the callback limits:
+   * their number is bounded by the run's parts.
+   */
+  public onStepCommitted(state: IStorageState, sessionId: string): void {
+    const run = this.callbackRun(state, sessionId);
+    if (!run) return;
+    for (const part of run.callbackParts) {
+      if (part.type !== 'text' || run.completedTextPartIds.has(part.partId)) continue;
+      run.completedTextPartIds.add(part.partId);
+      this.core.emitPartEvent(run, 'part.completed', part);
+    }
+  }
+
   private textAppendAccounting(
     run: IActiveRun,
     part: Extract<TFlexMessagePart, { type: 'text' | 'reasoning' }>,
@@ -147,21 +176,7 @@ export class FlexHarnessRunCallbacks<TScope> {
         : undefined;
       const input = normalizeJsonValue(target ? target.params : event.input, this.core.toolOutputLimits);
       if (!this.reserveCallbackCapacity(run, 1, jsonBytes(input), 1)) return;
-      const part: IFlexToolMessagePart = {
-        partId: plugins.crypto.randomUUID(),
-        type: 'tool',
-        toolCallId: this.core.boundedIdentifier(event.toolCallId, 'toolCallId'),
-        toolName: this.core.boundedIdentifier(target ? target.method : event.toolName, 'toolName'),
-        status: 'running',
-        input,
-        ...(event.parentToolCallId === undefined
-          ? {}
-          : { parentToolCallId: this.core.boundedIdentifier(event.parentToolCallId, 'parentToolCallId') }),
-        startedAt: new Date().toISOString(),
-      };
-      run.toolPartIds.set(event.toolCallId, part.partId);
-      run.callbackParts.push(part);
-      this.core.emitPartEvent(run, 'part.started', part);
+      this.startToolPart(run, { ...event, toolName: target ? target.method : event.toolName }, input);
     } catch (error) {
       this.failCallback(run, this.core.projectExternalError(run, error, 'toolCallback'));
     }
@@ -175,37 +190,164 @@ export class FlexHarnessRunCallbacks<TScope> {
     const run = this.callbackRun(state, sessionId);
     if (!run) return;
     if (!run.toolPartIds.has(event.toolCallId)) this.onToolStart(state, sessionId, event);
-    const partId = run.toolPartIds.get(event.toolCallId);
-    const part = run.callbackParts.find((entry) => entry.partId === partId && entry.type === 'tool');
-    if (!part || part.type !== 'tool' || part.status !== 'running') return;
+    const part = this.runningToolPart(run, event.toolCallId);
+    if (!part) return;
     try {
-      const trustedExecutionError = run.trustedToolExecutionErrors.get(event.toolCallId);
-      run.trustedToolExecutionErrors.delete(event.toolCallId);
-      const output = event.success ? normalizeJsonValue(event.output, this.core.toolOutputLimits) : undefined;
-      const projectedError = event.success
-        ? undefined
-        : this.core.projectExternalError(run, trustedExecutionError ?? event.error, 'toolCallback');
-      const bytes = event.success ? jsonBytes(output) : Buffer.byteLength(projectedError!.message);
-      if (!this.reserveCallbackCapacity(run, 1, bytes - (part.output === undefined ? 0 : jsonBytes(part.output)), 0)) return;
-      if (event.success) {
-        part.status = 'completed';
-        part.output = output!;
-      } else {
-        part.status = 'failed';
-        delete part.output;
-        part.error = projectedError!.message;
-      }
-      const original = run.deduplicatedToolCalls.get(event.toolCallId);
-      if (original !== undefined) {
-        part.deduplicatedFrom = this.core.boundedIdentifier(original, 'deduplicatedFrom');
-      }
-      part.completedAt = new Date().toISOString();
-      this.core.emitPartEvent(run, 'part.completed', part);
+      const outcome = this.toolOutcome(run, event, this.core.toolOutputLimits.maxBytes);
+      if (!this.reserveCallbackCapacity(
+        run,
+        1,
+        outcomeBytes(outcome) - (part.output === undefined ? 0 : jsonBytes(part.output)),
+        0,
+      )) return;
+      this.completeToolPart(run, part, event.toolCallId, outcome);
+    } catch (error) {
+      this.failCallback(run, this.core.projectExternalError(run, error, 'toolCallback'));
+    }
+  }
+
+  /**
+   * The room a `run_code` program's calls get in the run's callback limits: half of what the run
+   * has left once its program's answer is set aside. The rest stays for the model's next steps.
+   */
+  public programCallbackShare(state: IStorageState, sessionId: string): IProgramCallbackShare {
+    const run = this.callbackRun(state, sessionId);
+    if (!run) return { events: 0, outputBytes: 0, parts: 0 };
+    const limits = this.core.callbackLimits;
+    const half = (room: number): number => Math.max(0, Math.floor(room / 2));
+    return {
+      events: half(limits.maxEvents - run.callbackEventCount - 1),
+      outputBytes: half(limits.maxOutputBytes - run.callbackOutputBytes - this.core.toolOutputLimits.maxBytes),
+      parts: half(limits.maxParts - run.callbackParts.length),
+    };
+  }
+
+  /**
+   * Records the start of a call a program made, in the program's share. The call takes the room of
+   * its input, its two events and at least a truncated output now. A call the share or the run
+   * cannot hold is not recorded, and the answer is false: the program stops, the run goes on.
+   */
+  public onProgramCallStart(
+    state: IStorageState,
+    sessionId: string,
+    share: IProgramCallbackShare,
+    event: { toolCallId: string; toolName: string; input: unknown; parentToolCallId: string },
+  ): boolean {
+    const run = this.callbackRun(state, sessionId);
+    if (!run) return false;
+    try {
+      const input = normalizeJsonValue(event.input, this.core.toolOutputLimits);
+      const bytes = jsonBytes(input) + MIN_MAX_BYTES;
+      if (
+        share.events < 2
+        || share.outputBytes < bytes
+        || share.parts < 1
+        || !this.tryReserveCallbackCapacity(run, 2, bytes, 1)
+      ) return false;
+      share.events -= 2;
+      share.outputBytes -= bytes;
+      share.parts -= 1;
+      this.startToolPart(run, event, input);
+      return true;
     } catch (error) {
       this.failCallback(run, this.core.projectExternalError(run, error, 'toolCallback'));
+      return false;
     }
   }
 
+  /**
+   * Records how a call `onProgramCallStart` recorded ended. Its output or error is recorded in what
+   * is left of the share, cut to fit: the program gets the call's answer whole all the same.
+   */
+  public onProgramCallFinish(
+    state: IStorageState,
+    sessionId: string,
+    share: IProgramCallbackShare,
+    event: TFlexAgentToolCallFinishEvent,
+  ): void {
+    const run = this.callbackRun(state, sessionId);
+    if (!run) return;
+    const part = this.runningToolPart(run, event.toolCallId);
+    if (!part) return;
+    try {
+      const room = Math.min(share.outputBytes, this.core.callbackLimits.maxOutputBytes - run.callbackOutputBytes);
+      const allowance = MIN_MAX_BYTES + Math.max(0, room);
+      const finished = this.toolOutcome(run, event, Math.min(this.core.toolOutputLimits.maxBytes, allowance));
+      const outcome = 'error' in finished ? { error: truncateUtf8(finished.error, allowance) } : finished;
+      // The start reserved the call's events and its least output.
+      const bytes = outcomeBytes(outcome) - MIN_MAX_BYTES;
+      if (!this.reserveCallbackCapacity(run, 0, bytes, 0)) return;
+      share.outputBytes -= bytes;
+      this.completeToolPart(run, part, event.toolCallId, outcome);
+    } catch (error) {
+      this.failCallback(run, this.core.projectExternalError(run, error, 'toolCallback'));
+    }
+  }
+
+  private startToolPart(
+    run: IActiveRun,
+    event: { toolCallId: string; toolName: string; parentToolCallId?: string },
+    input: IFlexToolMessagePart['input'],
+  ): void {
+    const part: IFlexToolMessagePart = {
+      partId: plugins.crypto.randomUUID(),
+      type: 'tool',
+      toolCallId: this.core.boundedIdentifier(event.toolCallId, 'toolCallId'),
+      toolName: this.core.boundedIdentifier(event.toolName, 'toolName'),
+      status: 'running',
+      input,
+      ...(event.parentToolCallId === undefined
+        ? {}
+        : { parentToolCallId: this.core.boundedIdentifier(event.parentToolCallId, 'parentToolCallId') }),
+      startedAt: new Date().toISOString(),
+    };
+    run.toolPartIds.set(event.toolCallId, part.partId);
+    run.callbackParts.push(part);
+    this.core.emitPartEvent(run, 'part.started', part);
+  }
+
+  private runningToolPart(run: IActiveRun, toolCallId: string): IFlexToolMessagePart | undefined {
+    const partId = run.toolPartIds.get(toolCallId);
+    const part = run.callbackParts.find((entry) => entry.partId === partId && entry.type === 'tool');
+    return part?.type === 'tool' && part.status === 'running' ? part : undefined;
+  }
+
+  /** A finished call's output in at most `maxOutputBytes`, or its projected error. */
+  private toolOutcome(
+    run: IActiveRun,
+    event: TFlexAgentToolCallFinishEvent,
+    maxOutputBytes: number,
+  ): TToolPartOutcome {
+    const trustedExecutionError = run.trustedToolExecutionErrors.get(event.toolCallId);
+    run.trustedToolExecutionErrors.delete(event.toolCallId);
+    if (event.success) {
+      return { output: normalizeJsonValue(event.output, { ...this.core.toolOutputLimits, maxBytes: maxOutputBytes }) };
+    }
+    return { error: this.core.projectExternalError(run, trustedExecutionError ?? event.error, 'toolCallback').message };
+  }
+
+  private completeToolPart(
+    run: IActiveRun,
+    part: IFlexToolMessagePart,
+    toolCallId: string,
+    outcome: TToolPartOutcome,
+  ): void {
+    if ('output' in outcome) {
+      part.status = 'completed';
+      part.output = outcome.output;
+    } else {
+      part.status = 'failed';
+      delete part.output;
+      part.error = outcome.error;
+    }
+    const original = run.deduplicatedToolCalls.get(toolCallId);
+    if (original !== undefined) {
+      part.deduplicatedFrom = this.core.boundedIdentifier(original, 'deduplicatedFrom');
+    }
+    part.completedAt = new Date().toISOString();
+    this.core.emitPartEvent(run, 'part.completed', part);
+  }
+
   public onToolUpdate(
     state: IStorageState,
     sessionId: string,
@@ -218,9 +360,8 @@ export class FlexHarnessRunCallbacks<TScope> {
       run = this.callbackRun(state, sessionId);
       if (!run) return;
     }
-    const partId = run.toolPartIds.get(event.toolCallId);
-    const part = run.callbackParts.find((entry) => entry.partId === partId && entry.type === 'tool');
-    if (!part || part.type !== 'tool' || part.status !== 'running') return;
+    const part = this.runningToolPart(run, event.toolCallId);
+    if (!part) return;
     try {
       const output = normalizeJsonValue(event.output, this.core.toolOutputLimits);
       if (!this.reserveCallbackCapacity(run, 1, jsonBytes(output) - (part.output === undefined ? 0 : jsonBytes(part.output)), 0)) return;
@@ -318,11 +459,27 @@ export class FlexHarnessRunCallbacks<TScope> {
     return !run || run.callbacksClosed || run.callbackError ? undefined : run;
   }
 
+  /** Reserves room in the run's callback limits; a reservation past them fails the run. */
   public reserveCallbackCapacity(
     run: IActiveRun,
     eventCount: number,
     outputBytes: number,
     partCount: number,
+  ): boolean {
+    if (this.tryReserveCallbackCapacity(run, eventCount, outputBytes, partCount)) return true;
+    this.failCallback(run, this.core.trustInternalError(new FlexHarnessCallbackOverflowError(
+      `Callback buffer exceeded its limit (${run.callbackEventCount + eventCount} events, `
+        + `${run.callbackOutputBytes + outputBytes} bytes, ${run.callbackParts.length + partCount} parts).`,
+    )));
+    return false;
+  }
+
+  /** Reserves room in the run's callback limits; false, reserving nothing, when it does not fit. */
+  private tryReserveCallbackCapacity(
+    run: IActiveRun,
+    eventCount: number,
+    outputBytes: number,
+    partCount: number,
   ): boolean {
     const nextEvents = run.callbackEventCount + eventCount;
     const nextOutputBytes = run.callbackOutputBytes + outputBytes;
@@ -334,12 +491,7 @@ export class FlexHarnessRunCallbacks<TScope> {
       || nextEvents > this.core.callbackLimits.maxEvents
       || nextOutputBytes > this.core.callbackLimits.maxOutputBytes
       || nextParts > this.core.callbackLimits.maxParts
-    ) {
-      this.failCallback(run, this.core.trustInternalError(new FlexHarnessCallbackOverflowError(
-        `Callback buffer exceeded its limit (${nextEvents} events, ${nextOutputBytes} bytes, ${nextParts} parts).`,
-      )));
-      return false;
-    }
+    ) return false;
     run.callbackEventCount = nextEvents;
     run.callbackOutputBytes = nextOutputBytes;
     return true;