@ai-sdk/harness-acp 1.0.38 → 1.0.40

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ai-sdk/harness-acp",
-  "version": "1.0.38",
+  "version": "1.0.40",
   "type": "module",
   "license": "Apache-2.0",
   "sideEffects": false,
@@ -26,7 +26,7 @@
     }
   },
   "dependencies": {
-    "@ai-sdk/harness": "1.0.100",
+    "@ai-sdk/harness": "1.0.102",
     "@ai-sdk/provider-utils": "5.0.36",
     "ws": "^8.21.0"
   },

package/src/acp-harness.ts

@@ -1,9 +1,17 @@
-import type { HarnessV1, HarnessV1PortEndpoint } from '@ai-sdk/harness';
+import {
+  HARNESS_V1_BUILTIN_TOOLS,
+  type HarnessV1,
+  type HarnessV1PortEndpoint,
+} from '@ai-sdk/harness';
 import type { ToolSet } from '@ai-sdk/provider-utils';
 import { z } from 'zod/v4';
 import type { ACPClientApp } from './acp-auth';
 import type { ACPToolCall } from './acp-tool-call';
-import { createACPV1, type ACPV1Settings } from './v1';
+import {
+  createACPV1,
+  type ACPAskUserQuestionsSettings,
+  type ACPV1Settings,
+} from './v1';
 import {
   acpColdSessionStateSchema,
   acpTurnStartConfigSchema,
@@ -15,7 +23,12 @@ const ACP_CLIENT_APP = {
   version: VERSION,
 } as const satisfies ACPClientApp;
 
-export type ACPHarnessSettings<TBuiltinTools extends ToolSet = {}> = {
+export type ACPHarnessSettings<
+  TBuiltinTools extends ToolSet = {},
+  TAskUserQuestions extends ACPAskUserQuestionsSettings | undefined =
+    | ACPAskUserQuestionsSettings
+    | undefined,
+> = {
   readonly builtinTools?: TBuiltinTools;
   /**
    * MCP server definitions keyed by server name. Each definition uses the
@@ -61,6 +74,15 @@ export type ACPHarnessSettings<TBuiltinTools extends ToolSet = {}> = {
   readonly skillsDirectory?: ACPV1Settings['skillsDirectory'];
   readonly instructionMapping?: ACPV1Settings['instructionMapping'];
   readonly outputSchemaMapping?: ACPV1Settings['outputSchemaMapping'];
+  /**
+   * Transport used for the harness-owned MCP server that exposes host tools to
+   * the ACP implementation. Defaults to `stdio`. Set this to `http` for
+   * implementations that only accept HTTP or SSE MCP servers from the client,
+   * which requires the implementation to advertise
+   * `agentCapabilities.mcpCapabilities.http`.
+   */
+  readonly hostToolMcpTransport?: ACPV1Settings['hostToolMcpTransport'];
+  readonly askUserQuestions?: TAskUserQuestions;
   readonly permissionModeMapping?: ACPV1Settings['permissionModeMapping'];
   readonly session?: ACPV1Settings['session'];
   readonly mintBridgeToken?: ACPV1Settings['mintBridgeToken'];
@@ -117,9 +139,22 @@ const acpResumeStateSchema = z.object({
 
 type ACPBridgeCoords = z.infer<typeof acpBridgeCoordsSchema>;
 
-export function createACP<TBuiltinTools extends ToolSet = {}>(
-  settings: ACPHarnessSettings<TBuiltinTools>,
-): HarnessV1<TBuiltinTools> {
+type ACPHarnessTools<
+  TBuiltinTools extends ToolSet,
+  TAskUserQuestions,
+> = TBuiltinTools &
+  ([TAskUserQuestions] extends [undefined]
+    ? {}
+    : {
+        askUserQuestions: typeof HARNESS_V1_BUILTIN_TOOLS.askUserQuestions;
+      });
+
+export function createACP<
+  TBuiltinTools extends ToolSet = {},
+  TAskUserQuestions extends ACPAskUserQuestionsSettings | undefined = undefined,
+>(
+  settings: ACPHarnessSettings<TBuiltinTools, TAskUserQuestions>,
+): HarnessV1<ACPHarnessTools<TBuiltinTools, TAskUserQuestions>> {
   if (
     (settings.credentialEnv == null) !==
     (settings.credentialBrokering == null)
@@ -143,10 +178,17 @@ export function createACP<TBuiltinTools extends ToolSet = {}>(
   switch (version) {
     case 'v1': {
       const clientApp = settings.clientApp ?? ACP_CLIENT_APP;
+      const builtinTools =
+        settings.askUserQuestions == null
+          ? (settings.builtinTools ?? (ACP_BUILTIN_TOOLS as TBuiltinTools))
+          : {
+              ...(settings.builtinTools ??
+                (ACP_BUILTIN_TOOLS as TBuiltinTools)),
+              askUserQuestions: HARNESS_V1_BUILTIN_TOOLS.askUserQuestions,
+            };
       return createACPV1({
         settings,
-        builtinTools:
-          settings.builtinTools ?? (ACP_BUILTIN_TOOLS as TBuiltinTools),
+        builtinTools,
         port: settings.port,
         portEndpoint: settings.portEndpoint,
         startupTimeoutMs: settings.startupTimeoutMs,
@@ -154,7 +196,7 @@ export function createACP<TBuiltinTools extends ToolSet = {}>(
         lifecycleStateSchema: acpResumeStateSchema satisfies z.ZodType<{
           bridge?: ACPBridgeCoords;
         }>,
-      });
+      }) as HarnessV1<ACPHarnessTools<TBuiltinTools, TAskUserQuestions>>;
     }
     default:
       throw new Error(

package/src/index.ts

@@ -20,8 +20,10 @@ export type {
   ACPToolKind,
 } from './acp-tool-call';
 export type {
+  ACPAskUserQuestionsSettings,
   ACPCredentialBrokering,
   ACPAuthentication,
+  ACPHostToolMCPTransport,
   ACPInstallCommandSource,
   ACPInstructionMapping,
   ACPModelMapping,

package/src/v1/acp-v1-bridge-protocol.ts

@@ -113,6 +113,10 @@ const instructionMappingSchema: z.ZodType<ACPInstructionMapping> =
       variable: z.string().min(1),
       path: instructionMappingPathSchema,
     }),
+    z.object({
+      type: z.literal('filesystem'),
+      path: z.string().min(1),
+    }),
   ]);
 
 type ACPSerializableOutputSchemaMapping = {
@@ -199,6 +203,7 @@ const coldRestoreSchema = z.object({
 
 const acpToolCallCandidateSchema = z.object({
   type: z.literal('acp-tool-call-candidate'),
+  requestId: z.string(),
   toolCall: z.custom<ACPToolCall>(
     value =>
       value != null &&
@@ -208,9 +213,23 @@ const acpToolCallCandidateSchema = z.object({
   ),
 });
 
+const acpQuestionRequestSchema = z.object({
+  type: z.literal('acp-question-request'),
+  requestId: z.string(),
+  nativeRequest: z.unknown(),
+  nativeToolCall: acpToolCallCandidateSchema.shape.toolCall.optional(),
+});
+
+const acpQuestionResolvedSchema = z.object({
+  type: z.literal('acp-question-resolved'),
+  requestId: z.string(),
+});
+
 export const outboundMessageSchema = z.union([
   harnessV1BridgeOutboundMessageSchema,
   acpToolCallCandidateSchema,
+  acpQuestionRequestSchema,
+  acpQuestionResolvedSchema,
 ]);
 export type OutboundMessage = z.infer<typeof outboundMessageSchema>;
 

package/src/v1/acp-v1-harness.ts

@@ -32,11 +32,14 @@ import {
   warnCredentialBrokeringUnavailable,
   waitForBridgeReady,
   withBridgeToken,
+  writeInstructions,
+  writeSkills,
 } from '@ai-sdk/harness/utils';
 import {
   asSchema,
   type Experimental_SandboxProcess,
   type Experimental_SandboxSession as SandboxSession,
+  type ToolResultPart,
   type ToolSet,
 } from '@ai-sdk/provider-utils';
 import { WebSocket } from 'ws';
@@ -81,6 +84,7 @@ import {
   prependACPInstructionGuidance,
 } from './acp-v1-prompt';
 import type {
+  ACPAskUserQuestionsSettings,
   ACPInstructionMapping,
   ACPModelMapping,
   ACPOutputSchemaMapping,
@@ -91,9 +95,11 @@ import type {
   ACPV1Settings,
 } from './acp-v1-settings';
 import {
-  materializeACPSkills,
+  ACP_SKILL_NAME_PATTERN,
+  DEFAULT_ACP_SKILLS_DIRECTORY,
   resolveACPPrivateSessionDirectory,
   resolveACPSkillsDirectory,
+  validateACPSkills,
 } from './acp-v1-skills';
 
 const HARNESS_ID_REGEXP = /^[a-z0-9]+(?:-[a-z0-9]+)*$/;
@@ -322,6 +328,9 @@ export function createACPV1<TBuiltinTools extends ToolSet = {}>({
         const requestTransformations = settings.credentialBrokering({
           env: brokeringEnvironment,
           sandboxEnv: sandboxImplementationEnvironment,
+          ...(startOptions.headers == null
+            ? {}
+            : { headers: startOptions.headers }),
         });
         if (requestTransformations.length > 0) {
           await sandboxSession.addRequestTransformations(
@@ -370,17 +379,18 @@ export function createACPV1<TBuiltinTools extends ToolSet = {}>({
       });
       const privateSessionDir = resolveACPPrivateSessionDirectory({
         sandboxHomeDir,
-        sessionWorkDir: workDir,
         harnessId: settings.harnessId,
         sessionId: startOptions.sessionId,
       });
+      const implementationHomeDir =
+        implementation.source.type === 'install-command'
+          ? `${resolvedImplementationDir}/home`
+          : sandboxHomeDir;
+      const skillsDir =
+        settings.skillsDirectory ?? DEFAULT_ACP_SKILLS_DIRECTORY;
       const skillsDirectory = resolveACPSkillsDirectory({
-        implementationHomeDir:
-          implementation.source.type === 'install-command'
-            ? `${resolvedImplementationDir}/home`
-            : sandboxHomeDir,
+        implementationHomeDir,
         skillsDirectory: settings.skillsDirectory,
-        sessionWorkDir: workDir,
       });
       const bridgeStateDir = `${privateSessionDir}/bridge`;
       const report = startOptions.observability?.report;
@@ -442,6 +452,7 @@ export function createACPV1<TBuiltinTools extends ToolSet = {}>({
               sessionMeta: settings.session?.meta,
               instructionMapping: settings.instructionMapping,
               outputSchemaMapping: settings.outputSchemaMapping,
+              askUserQuestions: settings.askUserQuestions,
               debug: startOptions.observability?.debug,
               implementationIdentity,
               authenticationProfile,
@@ -456,7 +467,8 @@ export function createACPV1<TBuiltinTools extends ToolSet = {}>({
               }),
               instructionsFingerprint: lifecycleData.instructionsFingerprint,
               sandbox: toolSafeSandboxSession,
-              sessionWorkDir: workDir,
+              homePath: implementationHomeDir,
+              skillsDir,
               skillsDirectory,
               acpSessionId: lifecycleData.acpSessionId,
               bridgePort: coords.port,
@@ -615,6 +627,9 @@ export function createACPV1<TBuiltinTools extends ToolSet = {}>({
               sandboxProviderEnvironment == null ? undefined : {},
             sessionMeta: settings.session?.meta,
             clientCapabilities: settings.clientCapabilities,
+            askUserQuestionsRequestMethod:
+              settings.askUserQuestions?.requestMethod,
+            hostToolMcpTransport: settings.hostToolMcpTransport,
           }),
           ...sandboxProviderAuthenticationEnvironment,
           BRIDGE_CHANNEL_TOKEN: token,
@@ -732,6 +747,7 @@ export function createACPV1<TBuiltinTools extends ToolSet = {}>({
         sessionMeta: settings.session?.meta,
         instructionMapping: settings.instructionMapping,
         outputSchemaMapping: settings.outputSchemaMapping,
+        askUserQuestions: settings.askUserQuestions,
         debug: startOptions.observability?.debug,
         implementationIdentity,
         authenticationProfile,
@@ -746,7 +762,8 @@ export function createACPV1<TBuiltinTools extends ToolSet = {}>({
         }),
         instructionsFingerprint: lifecycleData?.instructionsFingerprint,
         sandbox: toolSafeSandboxSession,
-        sessionWorkDir: workDir,
+        homePath: implementationHomeDir,
+        skillsDir,
         skillsDirectory,
         acpSessionId: lifecycleData?.acpSessionId,
         bridgePort: boundPort,
@@ -1045,6 +1062,7 @@ function createSession({
   sessionMeta,
   instructionMapping,
   outputSchemaMapping,
+  askUserQuestions,
   debug,
   implementationIdentity,
   authenticationProfile,
@@ -1056,7 +1074,8 @@ function createSession({
   initialGuidanceApplied: initialGuidanceAppliedAtStart,
   instructionsFingerprint: instructionsFingerprintAtStart,
   sandbox,
-  sessionWorkDir,
+  homePath,
+  skillsDir,
   skillsDirectory,
   acpSessionId: acpSessionIdAtStart,
   bridgePort,
@@ -1081,6 +1100,7 @@ function createSession({
   sessionMeta: Readonly<Record<string, ACPSerializableValue>> | undefined;
   instructionMapping: ACPInstructionMapping | undefined;
   outputSchemaMapping: ACPOutputSchemaMapping | undefined;
+  askUserQuestions: ACPAskUserQuestionsSettings | undefined;
   debug: HarnessV1DebugConfig | undefined;
   implementationIdentity: string;
   authenticationProfile: ACPAuthenticationProfileIdentity;
@@ -1092,7 +1112,8 @@ function createSession({
   initialGuidanceApplied: boolean;
   instructionsFingerprint: string | undefined;
   sandbox: SandboxSession;
-  sessionWorkDir: string;
+  homePath: string;
+  skillsDir: string;
   skillsDirectory: string;
   acpSessionId: string | undefined;
   bridgePort: number;
@@ -1114,6 +1135,14 @@ function createSession({
   let instructionsFingerprint = instructionsFingerprintAtStart;
   let latestACPSessionId = acpSessionIdAtStart;
   let latestTurnStartConfig = turnStartConfigAtStart;
+  const bufferedQuestionResults = new Map<
+    string,
+    {
+      readonly output: unknown;
+      readonly isError?: boolean;
+      readonly toolResult: ToolResultPart;
+    }
+  >();
 
   const markTurnFinished = () => {
     turnInFlight = false;
@@ -1154,6 +1183,14 @@ function createSession({
       | undefined;
     const dynamicToolCalls = new Map<string, boolean>();
     const toolCallClassificationErrors = new Map<string, unknown>();
+    const activeQuestionRequests = new Map<
+      string,
+      {
+        readonly requestId: string;
+        readonly nativeRequest: unknown;
+      }
+    >();
+    const questionToolCallIdsByRequestId = new Map<string, string>();
     const subscriptions: Array<() => void> = [];
     const forward = (event: HarnessV1StreamPart) => {
       if (event.type === 'text-start' || event.type === 'reasoning-start') {
@@ -1220,12 +1257,120 @@ function createSession({
     subscriptions.push(
       channel.on('acp-tool-call-candidate', event => {
         try {
+          const suppress =
+            askUserQuestions?.isNativeToolCall?.({
+              nativeToolCall: event.toolCall,
+            }) === true;
           dynamicToolCalls.set(
             event.toolCall.toolCallId,
             isMcpToolCall?.(event.toolCall) === true,
           );
+          channel.send({
+            type: 'tool-result',
+            toolCallId: event.requestId,
+            output: { suppress },
+          });
         } catch (error) {
           toolCallClassificationErrors.set(event.toolCall.toolCallId, error);
+          channel.send({
+            type: 'tool-result',
+            toolCallId: event.requestId,
+            output: { suppress: false },
+          });
+        }
+      }),
+    );
+    subscriptions.push(
+      channel.on('acp-question-request', event => {
+        if (askUserQuestions == null) {
+          channel.send({
+            type: 'tool-result',
+            toolCallId: event.requestId,
+            output: { type: 'unhandled' },
+          });
+          return;
+        }
+        try {
+          const nativeToolCall = askUserQuestions.fromNativeRequest({
+            nativeRequest: event.nativeRequest,
+            nativeToolCall: event.nativeToolCall,
+          });
+          if (nativeToolCall == null) {
+            channel.send({
+              type: 'tool-result',
+              toolCallId: event.requestId,
+              output: { type: 'unhandled' },
+            });
+            return;
+          }
+          if (
+            nativeToolCall.toolName !== 'askUserQuestions' ||
+            nativeToolCall.providerExecuted !== false
+          ) {
+            throw new Error(
+              `${harnessId} ACP askUserQuestions.fromNativeRequest must return a client-executed askUserQuestions tool call.`,
+            );
+          }
+
+          const toolCall = withNativeQuestionRequest({
+            harnessId,
+            nativeRequest: event.nativeRequest,
+            toolCall: nativeToolCall,
+          });
+          const bufferedResult = takeBufferedQuestionResult({
+            bufferedQuestionResults,
+            toolCallId: toolCall.toolCallId,
+            nativeRequest: event.nativeRequest,
+            matchesNativeRequest: askUserQuestions.matchesNativeRequest,
+            harnessId,
+          });
+          activeQuestionRequests.set(toolCall.toolCallId, {
+            requestId: event.requestId,
+            nativeRequest: event.nativeRequest,
+          });
+          questionToolCallIdsByRequestId.set(
+            event.requestId,
+            toolCall.toolCallId,
+          );
+          channel.send({
+            type: 'tool-result',
+            toolCallId: event.requestId,
+            output: {
+              type: 'handled',
+              toolCallId: toolCall.toolCallId,
+            },
+          });
+
+          if (bufferedResult == null) {
+            forward(toolCall);
+            return;
+          }
+          channel.send({
+            type: 'tool-result',
+            toolCallId: toolCall.toolCallId,
+            output: askUserQuestions.toNativeResponse({
+              nativeRequest: event.nativeRequest,
+              toolResult: bufferedResult.toolResult,
+            }),
+            isError: bufferedResult.isError,
+            toolResult: bufferedResult.toolResult,
+          });
+        } catch (error) {
+          closeForwardedBlock();
+          forward({ type: 'error', error });
+          try {
+            channel.send({ type: 'abort' });
+          } catch {}
+          settle({ error });
+        }
+      }),
+    );
+    subscriptions.push(
+      channel.on('acp-question-resolved', event => {
+        const toolCallId = questionToolCallIdsByRequestId.get(event.requestId);
+        if (toolCallId != null) {
+          activeQuestionRequests.delete(toolCallId);
+          questionToolCallIdsByRequestId.delete(event.requestId);
         }
       }),
     );
@@ -1315,11 +1460,52 @@ function createSession({
         });
       },
       submitToolResult: async input => {
+        if (
+          askUserQuestions != null &&
+          input.toolResult?.toolName === 'askUserQuestions'
+        ) {
+          const activeRequest = activeQuestionRequests.get(input.toolCallId);
+          if (activeRequest == null) {
+            const previousNativeRequest =
+              input.toolResult.providerOptions?.[harnessId]?.nativeRequest;
+            if (!lossyRerun && previousNativeRequest !== undefined) {
+              channel.send({
+                type: 'tool-result',
+                toolCallId: input.toolCallId,
+                output: askUserQuestions.toNativeResponse({
+                  nativeRequest: previousNativeRequest,
+                  toolResult: input.toolResult,
+                }),
+                isError: input.isError,
+                toolResult: input.toolResult,
+              });
+              return;
+            }
+            bufferedQuestionResults.set(input.toolCallId, {
+              output: input.output,
+              ...(input.isError == null ? {} : { isError: input.isError }),
+              toolResult: input.toolResult,
+            });
+            return;
+          }
+          channel.send({
+            type: 'tool-result',
+            toolCallId: input.toolCallId,
+            output: askUserQuestions.toNativeResponse({
+              nativeRequest: activeRequest.nativeRequest,
+              toolResult: input.toolResult,
+            }),
+            isError: input.isError,
+            toolResult: input.toolResult,
+          });
+          return;
+        }
         channel.send({
           type: 'tool-result',
           toolCallId: input.toolCallId,
           output: input.output,
           isError: input.isError,
+          toolResult: input.toolResult,
         });
       },
       done,
@@ -1398,15 +1584,41 @@ function createSession({
     skills: ReadonlyArray<HarnessV1Skill>;
     abortSignal?: AbortSignal;
   }): Promise<void> => {
-    await materializeACPSkills({
+    validateACPSkills({ skills });
+    await writeSkills({
       sandbox,
-      rootDir: skillsDirectory,
-      sessionWorkDir,
+      homePath,
+      skillsDir,
       skills,
       abortSignal,
+      skillNamePattern: ACP_SKILL_NAME_PATTERN,
+      invalidSkillNameMessage: ({ name }) =>
+        `Invalid ACP skill name ${JSON.stringify(name)}: expected a kebab-case slug.`,
+      invalidSkillFilePathMessage: ({ skillName, filePath }) =>
+        `Invalid ACP skill file path ${JSON.stringify(filePath)} for skill ${JSON.stringify(
+          skillName,
+        )}: expected a relative POSIX path without traversal.`,
     });
   };
 
+  const synchronizeInstructions = async ({
+    instructions,
+    abortSignal,
+  }: {
+    instructions: string | undefined;
+    abortSignal?: AbortSignal;
+  }): Promise<void> => {
+    if (instructionMapping?.type === 'filesystem') {
+      await writeInstructions({
+        sandbox,
+        homePath,
+        instructionsFile: instructionMapping.path,
+        instructions,
+        abortSignal,
+      });
+    }
+  };
+
   return {
     sessionId,
     isResume,
@@ -1415,6 +1627,10 @@ function createSession({
         skills: options.skills,
         abortSignal: options.abortSignal,
       });
+      await synchronizeInstructions({
+        instructions: options.instructions,
+        abortSignal: options.abortSignal,
+      });
       if (options.responseFormat?.type === 'json') {
         if (options.responseFormat.schema == null) {
           throw unsupported({
@@ -1477,6 +1693,7 @@ function createSession({
           channel.send({
             type: 'start',
             prompt:
+              instructionMapping?.type !== 'filesystem' &&
               instructionsFingerprint !== nextInstructionsFingerprint &&
               (instructionMapping == null || initialGuidanceApplied)
                 ? prependACPInstructionGuidance({
@@ -1519,6 +1736,10 @@ function createSession({
         skills: options.skills,
         abortSignal: options.abortSignal,
       });
+      await synchronizeInstructions({
+        instructions: options.instructions,
+        abortSignal: options.abortSignal,
+      });
       if (options.responseFormat?.type === 'json') {
         if (options.responseFormat.schema == null) {
           throw unsupported({
@@ -1604,11 +1825,6 @@ function createSession({
           `${harnessId} ACP session ${sessionId} is stopped; cannot suspend.`,
         );
       }
-      if (!turnInFlight) {
-        throw new Error(
-          `${harnessId} ACP session ${sessionId} has no in-flight turn to suspend.`,
-        );
-      }
       stopped = true;
       const lastSeenEventId = await channel.suspend();
       return {
@@ -1682,6 +1898,78 @@ function isCompletePermissionModeMapping({
   );
 }
 
+function withNativeQuestionRequest({
+  harnessId,
+  nativeRequest,
+  toolCall,
+}: {
+  harnessId: string;
+  nativeRequest: unknown;
+  toolCall: Extract<HarnessV1StreamPart, { type: 'tool-call' }>;
+}): Extract<HarnessV1StreamPart, { type: 'tool-call' }> {
+  const harnessMetadata = toolCall.providerMetadata?.[harnessId];
+  return {
+    ...toolCall,
+    providerMetadata: {
+      ...toolCall.providerMetadata,
+      [harnessId]: {
+        ...(harnessMetadata ?? {}),
+        nativeRequest,
+      } as NonNullable<
+        Extract<HarnessV1StreamPart, { type: 'tool-call' }>['providerMetadata']
+      >[string],
+    },
+  };
+}
+
+function takeBufferedQuestionResult({
+  bufferedQuestionResults,
+  toolCallId,
+  nativeRequest,
+  matchesNativeRequest,
+  harnessId,
+}: {
+  bufferedQuestionResults: Map<
+    string,
+    {
+      readonly output: unknown;
+      readonly isError?: boolean;
+      readonly toolResult: ToolResultPart;
+    }
+  >;
+  toolCallId: string;
+  nativeRequest: unknown;
+  matchesNativeRequest:
+    | ACPAskUserQuestionsSettings['matchesNativeRequest']
+    | undefined;
+  harnessId: string;
+}):
+  | {
+      readonly output: unknown;
+      readonly isError?: boolean;
+      readonly toolResult: ToolResultPart;
+    }
+  | undefined {
+  const exact = bufferedQuestionResults.get(toolCallId);
+  if (exact != null) {
+    bufferedQuestionResults.delete(toolCallId);
+    return exact;
+  }
+  if (matchesNativeRequest == null) return undefined;
+  for (const [bufferedToolCallId, buffered] of bufferedQuestionResults) {
+    const previousNativeRequest =
+      buffered.toolResult.providerOptions?.[harnessId]?.nativeRequest;
+    if (
+      previousNativeRequest !== undefined &&
+      matchesNativeRequest({ previousNativeRequest, nativeRequest })
+    ) {
+      bufferedQuestionResults.delete(bufferedToolCallId);
+      return buffered;
+    }
+  }
+  return undefined;
+}
+
 function isPermissionModeMappingValue({
   value,
 }: {