@ixo/oracle-runtime-workers 0.13.0 → 0.16.0

package/src/core/middlewares/page-context.ts

@@ -22,8 +22,36 @@ export interface PageContextMiddlewareOptions {
   logger?: Logger;
 }
 
+/** Longest page title rendered (characters); longer ones are cut. */
+export const PAGE_TITLE_MAX_CHARS = 120;
+/** Longest room id rendered; a real Matrix room id is far shorter. */
+const ROOM_ID_MAX_CHARS = 255;
+
+/**
+ * Text set by other people (a page title any room member can change, a room
+ * id from the request) as inert single-line text: line breaks, control and
+ * format characters become spaces, runs of whitespace one space, the
+ * markdown and markup characters that open code, emphasis, headings,
+ * quotes, tables, links or tags (`` ` * # > < [ ] | ``) are dropped, the
+ * length is capped. What remains cannot open a section, a list or a tag in
+ * the system prompt.
+ */
+export function inertInline(text: string, maxChars: number): string {
+  const flat = text
+    .replace(/[\p{Cc}\p{Cf}\p{Zl}\p{Zp}]/gu, ' ')
+    .replace(/[`*#><|[\]]/g, '')
+    .replace(/\s+/g, ' ')
+    .trim();
+  return flat.length <= maxChars
+    ? flat
+    : `${flat.slice(0, maxChars).trimEnd()}…`;
+}
+
 function formatLabel(title: string | undefined, roomId: string): string {
-  return title ? `"${title}" (${roomId})` : roomId;
+  const id = inertInline(roomId, ROOM_ID_MAX_CHARS);
+  const name = title ? inertInline(title, PAGE_TITLE_MAX_CHARS) : '';
+  // Quoted as a value (JSON string rules): a quote in the title cannot end it.
+  return name ? `${JSON.stringify(name)} (${id})` : id;
 }
 
 /**
@@ -31,12 +59,28 @@ function formatLabel(title: string | undefined, roomId: string): string {
  * the agent is editing a page (`state.editorRoomId` is set). When the user
  * switches pages mid-conversation the block flags it explicitly so the
  * agent re-reads the current page before editing.
+ *
+ * A page's title is looked up once per room for the life of the middleware
+ * (one turn: the main agent is built per turn), not on every model step.
  */
 export const createPageContextMiddleware = (
   options: PageContextMiddlewareOptions,
 ): AgentMiddleware => {
   const logger = options.logger ?? NOOP_LOGGER;
-  const { getRoomTitle } = options;
+  const titles = new Map<string, Promise<string | undefined>>();
+  const getRoomTitle = (roomId: string): Promise<string | undefined> => {
+    let title = titles.get(roomId);
+    if (!title) {
+      title = options.getRoomTitle(roomId).catch((error: unknown) => {
+        logger.warn(
+          `[PageContextMiddleware] title lookup failed for ${roomId}: ${error instanceof Error ? error.message : String(error)}`,
+        );
+        return undefined;
+      });
+      titles.set(roomId, title);
+    }
+    return title;
+  };
 
   return createMiddleware({
     name: 'PageContextMiddleware',

package/src/core/middlewares/return-direct-first.ts

@@ -0,0 +1,47 @@
+/**
+ * LangChain's agent loop exits when the LAST tool result of a step comes
+ * from a return-direct tool. A model that calls one alongside other tools
+ * would then never see those other results. This middleware moves the
+ * return-direct call to the front of such a step, so the loop continues and
+ * the model answers with every result in view.
+ */
+import { AIMessage, isAIMessage } from '@langchain/core/messages';
+import { type AgentMiddleware, createMiddleware } from 'langchain';
+
+export function createReturnDirectFirstMiddleware(
+  toolNames: ReadonlySet<string>,
+): AgentMiddleware {
+  return createMiddleware({
+    name: 'ReturnDirectFirstMiddleware',
+    afterModel: (state) => {
+      const last = state.messages.at(-1);
+      if (!last || !isAIMessage(last)) return undefined;
+      const calls = last.tool_calls ?? [];
+      const lastCall = calls.at(-1);
+      // Only a return-direct call in last place ends the loop early, and
+      // only when some other tool's result would go unanswered.
+      if (!lastCall || !toolNames.has(lastCall.name)) return undefined;
+      if (calls.every((c) => toolNames.has(c.name))) return undefined;
+      const direct = calls.filter((c) => toolNames.has(c.name));
+      return {
+        messages: [
+          new AIMessage({
+            id: last.id,
+            name: last.name,
+            content: last.content,
+            additional_kwargs: last.additional_kwargs,
+            response_metadata: last.response_metadata,
+            ...(last.usage_metadata
+              ? { usage_metadata: last.usage_metadata }
+              : {}),
+            invalid_tool_calls: last.invalid_tool_calls ?? [],
+            tool_calls: [
+              ...direct,
+              ...calls.filter((c) => !toolNames.has(c.name)),
+            ],
+          }),
+        ],
+      };
+    },
+  });
+}

package/src/core/middlewares/summarization.ts

@@ -1,7 +1,20 @@
 import type { BaseChatModel } from '@langchain/core/language_models/chat_models';
-import type { BaseMessage } from '@langchain/core/messages';
+import {
+  AIMessage,
+  HumanMessage,
+  ToolMessage,
+  type BaseMessage,
+} from '@langchain/core/messages';
 import { type AgentMiddleware, summarizationMiddleware } from 'langchain';
 import type { Logger } from '../../plugin-api/types';
+import type { TurnBudget } from '../turn-budget';
+import {
+  carriedCallsOfTurn,
+  isSummarizationMessage,
+  SUMMARY_PREFIX,
+  turnCarryKwargs,
+  turnStart,
+} from './turn-boundary';
 
 /**
  * IXO-flavoured prompt instructing the summarizer to preserve identifiers
@@ -48,7 +61,7 @@ Messages to summarize:
 {messages}
 </messages>`;
 
-export const SUMMARY_PREFIX = 'Here is a summary of the conversation to date:';
+export { isSummarizationMessage, SUMMARY_PREFIX };
 
 const DEFAULT_TRIGGER_MESSAGES = 20;
 const DEFAULT_TRIGGER_TOKENS = 40_000;
@@ -73,6 +86,12 @@ export interface SummarizationMiddlewareOptions {
   keepMessages?: number;
   /** What the summarizer itself may read (tokens); default LangChain's. */
   summaryInputTokens?: number;
+  /**
+   * The turn's budget: a summary is not started after the deadline or the
+   * abort, and its model call is charged like any other (the metered
+   * adapter does that; the check here is the cheap early exit).
+   */
+  budget?: TurnBudget;
   logger?: Pick<Logger, 'warn' | 'log'>;
 }
 
@@ -94,21 +113,101 @@ export function isFailedSummary(message: BaseMessage): boolean {
   return FAILED_SUMMARY.test(body);
 }
 
+interface ApproximateChars {
+  content: unknown;
+  toolCalls: unknown;
+  toolCallId: unknown;
+  chars: number;
+}
+
+const approximateChars = new WeakMap<BaseMessage, ApproximateChars>();
+
 /**
- * `true` for the condensed-history message the summarization middleware
- * writes into graph state. List endpoints use this to keep it out of the
- * user-visible transcript.
+ * The characters LangChain's `countTokensApproximately` counts for one
+ * message (its text, an AI message's tool calls as JSON, a tool message's
+ * call id), memoised per message while those values are unchanged.
  */
-export function isSummarizationMessage(message: BaseMessage): boolean {
-  if (message.additional_kwargs?.lc_source === 'summarization') return true;
+function charsOf(message: BaseMessage): number {
+  const toolCalls = AIMessage.isInstance(message)
+    ? message.tool_calls
+    : undefined;
+  const toolCallId = ToolMessage.isInstance(message)
+    ? message.tool_call_id
+    : undefined;
+  const cached = approximateChars.get(message);
+  if (
+    cached &&
+    cached.content === message.content &&
+    cached.toolCalls === toolCalls &&
+    cached.toolCallId === toolCallId
+  )
+    return cached.chars;
   const { content } = message;
-  return typeof content === 'string' && content.startsWith(SUMMARY_PREFIX);
+  let text: string;
+  if (typeof content === 'string') text = content;
+  else if (Array.isArray(content))
+    text = content
+      .map((item: unknown) => {
+        if (typeof item === 'string') return item;
+        if (
+          item &&
+          typeof item === 'object' &&
+          'type' in item &&
+          item.type === 'text' &&
+          'text' in item
+        )
+          return item.text;
+        return '';
+      })
+      .join('');
+  else text = '';
+  if (Array.isArray(toolCalls) && toolCalls.length > 0)
+    text += JSON.stringify(toolCalls);
+  if (ToolMessage.isInstance(message)) text += toolCallId ?? '';
+  approximateChars.set(message, {
+    content,
+    toolCalls,
+    toolCallId,
+    chars: text.length,
+  });
+  return text.length;
+}
+
+/**
+ * LangChain's `countTokensApproximately` over messages (chars/4 of the
+ * total, rounded up) with the per-message work memoised: the summarizer
+ * counts the whole history before every model step, and again while it
+ * trims what it reads.
+ */
+export function countMessageTokensApproximately(
+  messages: readonly BaseMessage[],
+): number {
+  let chars = 0;
+  for (const message of messages) chars += charsOf(message);
+  return Math.ceil(chars / 4);
+}
+
+/** The turn-opening message of `messages`, by id and by reference. */
+function openingOf(messages: readonly BaseMessage[]): {
+  id?: string;
+  message?: BaseMessage;
+} {
+  const message = messages[turnStart(messages)];
+  return { id: message?.id, message };
 }
 
 /**
  * Wraps LangChain's built-in `summarizationMiddleware` with the IXO-specific
  * summary prompt + prefix. Pass any compatible chat model — typically the
  * cheap "routing" role.
+ *
+ * A summary that fails is not attempted again before the next turn: the
+ * history it could not condense is the same one on every later step, and
+ * each attempt would send all of it again.
+ *
+ * A summary written in the middle of a turn — the turn's opening message is
+ * among what it condenses — carries the turn's earlier tool calls
+ * (turn-boundary.ts), so the repetition guard still sees them.
  */
 export const createSummarizationMiddleware = (
   options: SummarizationMiddlewareOptions,
@@ -129,6 +228,7 @@ export const createSummarizationMiddleware = (
       { tokens: options.triggerTokens ?? DEFAULT_TRIGGER_TOKENS },
     ],
     keep: { messages: options.keepMessages ?? DEFAULT_KEEP_MESSAGES },
+    tokenCounter: countMessageTokensApproximately,
     ...(options.summaryInputTokens !== undefined
       ? { trimTokensToSummarize: options.summaryInputTokens }
       : {}),
@@ -138,9 +238,21 @@ export const createSummarizationMiddleware = (
   // The hook is either a bare handler or `{ hook, canJumpTo }`; keep the shape.
   const handler =
     typeof beforeModel === 'function' ? beforeModel : beforeModel.hook;
+  // The opening message of the turn whose summary failed.
+  let failedTurn: { id?: string; message?: BaseMessage } | undefined;
+  const sameTurn = (messages: readonly BaseMessage[]): boolean => {
+    if (!failedTurn) return false;
+    const now = openingOf(messages);
+    return (
+      (now.message !== undefined && now.message === failedTurn.message) ||
+      (now.id !== undefined && now.id === failedTurn.id)
+    );
+  };
   // A summary that failed keeps the history exactly as it was: the turn
   // runs on the full context and the next turn tries again.
   const guarded: typeof handler = async (state, runtime) => {
+    options.budget?.check(runtime.signal);
+    if (sameTurn(state.messages)) return undefined;
     const update = await handler(state, runtime);
     const messages =
       update && typeof update === 'object' && 'messages' in update
@@ -150,15 +262,18 @@ export const createSummarizationMiddleware = (
       ? messages.find((m) => isBaseMessageLike(m) && isFailedSummary(m))
       : undefined;
     if (failed) {
+      failedTurn = openingOf(state.messages);
       options.logger?.warn(
-        `[summarization] summary failed; keeping the full history this turn: ${String(failed.content).slice(0, 300)}`,
+        `[summarization] summary failed; keeping the full history for the rest of this turn: ${String(failed.content).slice(0, 300)}`,
       );
       return undefined;
     }
-    if (Array.isArray(messages) && messages.length > 0)
+    if (Array.isArray(messages) && messages.length > 0) {
+      carryTurnCalls(state.messages, messages);
       options.logger?.log(
         `[summarization] condensed the history: ${state.messages.length} messages → a summary + ${messages.length - 2} kept`,
       );
+    }
     return update;
   };
   return {
@@ -170,6 +285,33 @@ export const createSummarizationMiddleware = (
   };
 };
 
+/**
+ * When the summary in `update` removes the current turn's opening message,
+ * record on it the turn's tool calls it condensed (turn-boundary.ts).
+ */
+function carryTurnCalls(
+  before: readonly BaseMessage[],
+  update: readonly unknown[],
+): void {
+  const summary = update.find(
+    (m): m is BaseMessage =>
+      isBaseMessageLike(m) &&
+      HumanMessage.isInstance(m) &&
+      isSummarizationMessage(m),
+  );
+  if (!summary) return;
+  const keptIds = new Set<string>();
+  for (const m of update)
+    if (isBaseMessageLike(m) && m !== summary && typeof m.id === 'string')
+      keptIds.add(m.id);
+  const carried = carriedCallsOfTurn(before, keptIds);
+  if (carried === undefined) return;
+  summary.additional_kwargs = {
+    ...summary.additional_kwargs,
+    ...turnCarryKwargs(carried),
+  };
+}
+
 function isBaseMessageLike(value: unknown): value is BaseMessage {
   return (
     typeof value === 'object' &&

package/src/core/middlewares/tool-execution.ts

@@ -0,0 +1,323 @@
+/**
+ * How a tool call is executed once the resume policy (tool-marks.ts) let it
+ * run: charged to the turn's budget, scheduled in its lane, and — for a
+ * write — claimed in the run ledger for as long as its outcome is unknown.
+ *
+ * The claim is a fingerprint of the tool name and its canonical arguments,
+ * recorded before the write starts. A returned result (success or a
+ * reported failure) releases it; a failure that says nothing about whether
+ * the write happened — abort, deadline, a dropped connection, a 5xx —
+ * leaves it in place, whether the tool threw it or caught it and returned
+ * it as an error result (many plugin tools and adapters never throw to the
+ * agent: `{ ok: false, error }`, an error-status ToolMessage, `Error: …`).
+ * An identical write attempted while a claim stands is
+ * not executed: the model is told the earlier outcome is unknown and asked
+ * to verify with a read (a `warned` claim). A later turn that asks for the
+ * same write again, after that warning, runs it — the user was informed and
+ * asked again — and the ledger drops claims with the run retention.
+ *
+ * Placed innermost around the tool (`MainAgentHooks.toolExecution`): it
+ * must see the tool's own thrown error, which the retry middlewares would
+ * otherwise have turned into an error ToolMessage, and each retry attempt
+ * is charged and scheduled again. Applied to every sub-agent's inner graph
+ * too, so a sub-agent's own writes are claimed. Sub-agent dispatches are
+ * counted as tool attempts and scheduled in their own lane, never
+ * fingerprinted.
+ */
+import { reportsUnknownOutcome } from '@ixo/common/ai/frontend-bridge';
+import { ToolMessage } from '@langchain/core/messages';
+import { type AgentMiddleware, createMiddleware } from 'langchain';
+import type { Logger } from '../../plugin-api/types';
+import type { ToolLane, ToolScheduler } from '../tool-scheduler';
+import { isHarnessLimitError, type TurnBudget } from '../turn-budget';
+import { NOOP_LOGGER } from '../utils';
+
+export type WriteClaim =
+  | { status: 'claimed' }
+  | { status: 'blocked'; toolName: string; since: string };
+
+/** The claim slice of the run ledger (see `RunStore`). */
+export interface WriteClaimStore {
+  claimWrite(input: {
+    fingerprint: string;
+    toolName: string;
+    runId: string;
+    sessionId: string;
+  }): Promise<WriteClaim>;
+  releaseWrite(fingerprint: string, runId: string): Promise<void>;
+}
+
+export interface ToolExecutionOptions {
+  budget: TurnBudget;
+  scheduler: ToolScheduler;
+  /** Lane of a tool by name (`read`, `write`, or `subagent` for a dispatch). */
+  laneOf: (toolName: string) => ToolLane;
+  runId: string;
+  sessionId: string;
+  /** Omitted → writes are scheduled and charged but not claimed (stateless builds, tests). */
+  claims?: WriteClaimStore;
+  /** The turn's abort signal: waiting for a slot ends with it. */
+  signal?: AbortSignal;
+  logger?: Logger;
+}
+
+/** Stable text for a value: object keys sorted, arrays in order. */
+export function canonicalArguments(value: unknown): string {
+  if (Array.isArray(value))
+    return `[${value.map(canonicalArguments).join(',')}]`;
+  if (value && typeof value === 'object')
+    return `{${Object.entries(value)
+      .filter(([, item]) => item !== undefined)
+      .sort(([a], [b]) => (a < b ? -1 : a > b ? 1 : 0))
+      .map(
+        ([key, item]) => `${JSON.stringify(key)}:${canonicalArguments(item)}`,
+      )
+      .join(',')}}`;
+  return JSON.stringify(value) ?? 'null';
+}
+
+/** SHA-256 of `name:args`, hex — the write's fingerprint in the ledger. */
+export async function operationKey(
+  name: string,
+  args: unknown,
+): Promise<string> {
+  const bytes = new TextEncoder().encode(`${name}:${canonicalArguments(args)}`);
+  const digest = await crypto.subtle.digest('SHA-256', bytes);
+  return Array.from(new Uint8Array(digest), (b) =>
+    b.toString(16).padStart(2, '0'),
+  ).join('');
+}
+
+/** The result handed to the model for a write it must not repeat yet. */
+export function uncertainWriteToolResult(toolName: string): string {
+  return `An identical ${toolName} call was started earlier and its outcome is unknown (it was interrupted or its connection dropped), so it was NOT run again: running it twice could repeat its effect. Verify with a read-only call whether it already happened and tell the user; only repeat it if they confirm.`;
+}
+
+/**
+ * Transport error codes (Node / undici `code`s; workerd only has them in the
+ * message) and the editor's undelivered write (`write_not_saved`: the
+ * homeserver kept failing, and a send that failed with a server error may
+ * still have landed). Any of them can follow a request that reached the
+ * service, so none proves the effect did not happen.
+ */
+const UNCERTAIN_CODES =
+  'ECONNRESET|ECONNREFUSED|ECONNABORTED|ETIMEDOUT|EPIPE|UND_ERR_(?:SOCKET|CLOSED|CONNECT_TIMEOUT|HEADERS_TIMEOUT|BODY_TIMEOUT)|write_not_saved';
+const UNCERTAIN_CODE = new RegExp(`^(?:${UNCERTAIN_CODES})$`, 'i');
+
+/**
+ * Failure text that says nothing about whether the side effect happened,
+ * anchored to how such a failure is reported — never a bare word a definite
+ * refusal can contain ("network 'base' not supported", "invalid timeout",
+ * "payment aborted by the user"):
+ *  - an error code above, as a whole word;
+ *  - a transport failure's own message: undici's `fetch failed`, `socket
+ *    hang up`, workerd's `Network connection lost`, `network error`;
+ *  - a deadline: `timed out`, `timeout exceeded` / `timeout of <n>`, the
+ *    `TimeoutError` / `AbortError` names, DOMException's "operation was
+ *    aborted";
+ *  - a 5xx: its status (`HTTP 503`, `status 502`, `status code: 500`) or
+ *    its reason phrase.
+ */
+const UNCERTAIN_TEXT = new RegExp(
+  [
+    `\\b(?:${UNCERTAIN_CODES})\\b`,
+    '\\bfetch failed\\b',
+    '\\bsocket hang up\\b',
+    '\\bnetwork (?:error|connection (?:was )?lost)\\b',
+    '\\btimed out\\b',
+    '\\btimeout (?:exceeded|of \\d)',
+    '\\b(?:TimeoutError|AbortError)\\b',
+    '\\boperation was aborted\\b',
+    '\\b(?:HTTP|status(?: code)?):? ?5\\d\\d\\b',
+    '\\b(?:internal server error|bad gateway|service unavailable|gateway time-?out)\\b',
+  ].join('|'),
+  'i',
+);
+
+const isServerStatus = (status: unknown): boolean =>
+  typeof status === 'number' && status >= 500 && status <= 599;
+
+/**
+ * `true` when a thrown error says nothing about whether the tool's side
+ * effect happened: the turn was aborted or hit its deadline, the transport
+ * failed, or the service answered with a server error.
+ */
+export function isUncertainOutcome(
+  error: unknown,
+  signal?: AbortSignal,
+): boolean {
+  if (signal?.aborted) return true;
+  if (isHarnessLimitError(error)) return true;
+  if (!(error instanceof Error)) return false;
+  if (error.name === 'AbortError' || error.name === 'TimeoutError') return true;
+  if (
+    'code' in error &&
+    typeof error.code === 'string' &&
+    UNCERTAIN_CODE.test(error.code)
+  )
+    return true;
+  const status =
+    'status' in error && typeof error.status === 'number'
+      ? error.status
+      : undefined;
+  if (status !== undefined) return isServerStatus(status);
+  return UNCERTAIN_TEXT.test(error.message);
+}
+
+function isRecord(value: unknown): value is Record<string, unknown> {
+  return typeof value === 'object' && value !== null && !Array.isArray(value);
+}
+
+function toolMessageText(message: ToolMessage): string {
+  const { content } = message;
+  if (typeof content === 'string') return content;
+  return content
+    .map((block) =>
+      typeof block === 'string'
+        ? block
+        : 'text' in block && typeof block.text === 'string'
+          ? block.text
+          : '',
+    )
+    .join('\n');
+}
+
+/**
+ * The failure a JSON tool result reports, when it is one: `ok`, `success` or
+ * `successful` false, `isError` true, or an `error` field. The text joins
+ * whatever describes it (error, message, reason, code, detail) and a server
+ * status (`status` / `statusCode`) is carried apart.
+ */
+function reportedFailure(
+  body: Record<string, unknown>,
+): { text: string; serverStatus: boolean } | null {
+  const failed =
+    body.ok === false ||
+    body.success === false ||
+    body.successful === false ||
+    body.isError === true ||
+    (body.error !== undefined && body.error !== null && body.error !== false);
+  if (!failed) return null;
+  const parts: string[] = [];
+  let serverStatus =
+    isServerStatus(body.status) || isServerStatus(body.statusCode);
+  const collect = (value: unknown): void => {
+    if (typeof value === 'string') parts.push(value);
+    else if (isRecord(value)) {
+      if (isServerStatus(value.status) || isServerStatus(value.statusCode))
+        serverStatus = true;
+      for (const key of ['message', 'code', 'name', 'reason', 'detail'])
+        collect(value[key]);
+    }
+  };
+  for (const key of ['error', 'message', 'reason', 'code', 'name', 'detail'])
+    collect(body[key]);
+  return { text: parts.join(' '), serverStatus };
+}
+
+/**
+ * Why a RETURNED tool result leaves a write's outcome unknown, or null when
+ * it does not. A JSON result whose `outcome` is `'unknown'` says so itself.
+ * Otherwise only an error-shaped result counts — an error-status
+ * ToolMessage, a JSON failure (`reportedFailure`), or text that opens with
+ * `Error` / `Failed` — and only when what it reports is the uncertain kind
+ * `isUncertainOutcome` recognises in a thrown error (a timeout, a transport
+ * failure, a 5xx). A failure the service did report (validation, 404, 403)
+ * is a known outcome, and a success mentioning a timeout is not a failure.
+ */
+export function uncertainResultReason(output: unknown): string | null {
+  if (!ToolMessage.isInstance(output)) return null;
+  const text = toolMessageText(output).trim();
+  let failure: { text: string; serverStatus: boolean } | null = null;
+  try {
+    const parsed: unknown = JSON.parse(text);
+    // A result that says so itself (the frontend bridge's
+    // FRONTEND_OUTCOME_UNKNOWN, or a client reporting the same).
+    if (reportsUnknownOutcome(parsed)) return 'outcome unknown';
+    if (isRecord(parsed)) failure = reportedFailure(parsed);
+  } catch {
+    // Not JSON: plain text, judged below.
+  }
+  if (
+    !failure &&
+    (output.status === 'error' || /^(error|failed)\b/i.test(text))
+  )
+    failure = { text, serverStatus: false };
+  if (!failure) return null;
+  if (failure.serverStatus) return 'server error';
+  const match = UNCERTAIN_TEXT.exec(failure.text);
+  return match ? match[0] : null;
+}
+
+export function createToolExecutionMiddleware(
+  options: ToolExecutionOptions,
+): AgentMiddleware {
+  const logger = options.logger ?? NOOP_LOGGER;
+  const { budget, scheduler, claims } = options;
+  // Executions per tool call id: a second one is a retry (the log is the
+  // operator's only view of a read that failed and then succeeded).
+  const attempts = new Map<string, number>();
+  return createMiddleware({
+    name: 'ToolExecutionMiddleware',
+    wrapToolCall: async (request, handler) => {
+      const { toolCall } = request;
+      const toolName = toolCall.name;
+      const lane = options.laneOf(toolName);
+      const callId = toolCall.id ?? '';
+      const attempt = (attempts.get(callId) ?? 0) + 1;
+      attempts.set(callId, attempt);
+      if (attempt > 1)
+        logger.log(
+          `[tool-execution] ${toolName} (${callId}): attempt ${attempt}`,
+        );
+      // Refused before waiting for a slot: a turn over its limit takes no
+      // more slots. The slot wait itself ends with the abort signal.
+      budget.check(options.signal);
+      return scheduler.run(lane, options.signal, async () => {
+        budget.reserveTool(options.signal);
+        if (lane !== 'write' || !claims) return handler(request);
+        const fingerprint = await operationKey(toolName, toolCall.args);
+        const claim = await claims.claimWrite({
+          fingerprint,
+          toolName,
+          runId: options.runId,
+          sessionId: options.sessionId,
+        });
+        if (claim.status === 'blocked') {
+          logger.warn(
+            `[tool-execution] ${toolName}: an identical write since ${claim.since} has no known outcome; not run again`,
+          );
+          return new ToolMessage({
+            tool_call_id: toolCall.id ?? '',
+            name: toolName,
+            content: uncertainWriteToolResult(toolName),
+            status: 'error',
+          });
+        }
+        try {
+          const output = await handler(request);
+          const uncertain = uncertainResultReason(output);
+          if (uncertain !== null) {
+            logger.warn(
+              `[tool-execution] ${toolName}: returned a failure that leaves its outcome unknown (${uncertain}); its claim stays in the ledger`,
+            );
+          } else {
+            await claims.releaseWrite(fingerprint, options.runId);
+          }
+          return output;
+        } catch (error) {
+          if (isUncertainOutcome(error, options.signal)) {
+            logger.warn(
+              `[tool-execution] ${toolName}: outcome unknown (${error instanceof Error ? error.message.split('\n')[0] : String(error)}); its claim stays in the ledger`,
+            );
+          } else {
+            await claims
+              .releaseWrite(fingerprint, options.runId)
+              .catch(() => undefined);
+          }
+          throw error;
+        }
+      });
+    },
+  });
+}