@ai-sdk/harness-acp 1.0.37 → 1.0.39

package/dist/index.d.ts

@@ -1,5 +1,5 @@
-import { HarnessV1Authentication, HarnessV1RequestTransformation, HarnessV1CredentialForwarding, HarnessV1PermissionMode, HarnessV1PortEndpoint, HarnessV1 } from '@ai-sdk/harness';
-import { ToolSet } from '@ai-sdk/provider-utils';
+import { HarnessV1StreamPart, HarnessV1Authentication, HarnessV1RequestTransformation, HarnessV1CredentialForwarding, HarnessV1PermissionMode, HarnessV1PortEndpoint, HarnessV1, HARNESS_V1_BUILTIN_TOOLS } from '@ai-sdk/harness';
+import { ToolResultPart, ToolSet } from '@ai-sdk/provider-utils';
 
 type ACPMetadata = Record<string, unknown>;
 type ACPRole = 'assistant' | 'user';
@@ -182,6 +182,26 @@ type ACPOutputSchemaMapping = {
     readonly type: 'session-prompt-meta';
     readonly path: ReadonlyArray<string>;
 };
+type ACPAskUserQuestionsSettings = {
+    readonly requestMethod: string;
+    readonly isNativeToolCall?: (options: {
+        nativeToolCall: ACPToolCall;
+    }) => boolean;
+    readonly fromNativeRequest: (options: {
+        nativeRequest: unknown;
+        nativeToolCall?: ACPToolCall;
+    }) => Extract<HarnessV1StreamPart, {
+        type: 'tool-call';
+    }> | null;
+    readonly toNativeResponse: (options: {
+        nativeRequest: unknown;
+        toolResult: ToolResultPart;
+    }) => unknown;
+    readonly matchesNativeRequest?: (options: {
+        previousNativeRequest: unknown;
+        nativeRequest: unknown;
+    }) => boolean;
+};
 type ACPV1Settings = {
     readonly version?: 'v1';
     readonly harnessId: string;
@@ -232,6 +252,7 @@ type ACPV1Settings = {
      * below the ACP session prompt's `_meta` field.
      */
     readonly outputSchemaMapping?: ACPOutputSchemaMapping;
+    readonly askUserQuestions?: ACPAskUserQuestionsSettings;
     readonly permissionModeMapping?: ACPPermissionModeMapping;
     readonly session?: {
         readonly meta?: Readonly<Record<string, ACPSerializableValue>>;
@@ -249,7 +270,7 @@ type ACPClientApp = {
     readonly version: string;
 };
 
-type ACPHarnessSettings<TBuiltinTools extends ToolSet = {}> = {
+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
@@ -295,12 +316,16 @@ type ACPHarnessSettings<TBuiltinTools extends ToolSet = {}> = {
     readonly skillsDirectory?: ACPV1Settings['skillsDirectory'];
     readonly instructionMapping?: ACPV1Settings['instructionMapping'];
     readonly outputSchemaMapping?: ACPV1Settings['outputSchemaMapping'];
+    readonly askUserQuestions?: TAskUserQuestions;
     readonly permissionModeMapping?: ACPV1Settings['permissionModeMapping'];
     readonly session?: ACPV1Settings['session'];
     readonly mintBridgeToken?: ACPV1Settings['mintBridgeToken'];
 };
-declare 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;
+});
+declare function createACP<TBuiltinTools extends ToolSet = {}, TAskUserQuestions extends ACPAskUserQuestionsSettings | undefined = undefined>(settings: ACPHarnessSettings<TBuiltinTools, TAskUserQuestions>): HarnessV1<ACPHarnessTools<TBuiltinTools, TAskUserQuestions>>;
 
 declare const VERSION: string;
 
-export { type ACPAnnotations, type ACPAudioContent, type ACPAuthentication, type ACPAuthenticationMode, type ACPBlobResourceContents, type ACPClientApp, type ACPContentBlock, type ACPCredentialBrokering, type ACPEmbeddedResource, type ACPHarnessSettings, type ACPImageContent, type ACPInstallCommandSource, type ACPInstructionMapping, type ACPMetadata, type ACPModelMapping, type ACPNpmLockedSource, type ACPNpmSimpleSource, type ACPOutputSchemaMapping, type ACPPermissionModeMapping, type ACPPermissionModeTarget, type ACPProfileValue, type ACPProviderAuthentication, type ACPResourceLink, type ACPRole, type ACPSerializablePrimitive, type ACPSerializableValue, type ACPSource, type ACPTextContent, type ACPTextResourceContents, type ACPToolCall, type ACPToolCallContent, type ACPToolCallLocation, type ACPToolCallStatus, type ACPToolKind, type ACPV1Settings, type ACPValueSource, VERSION, createACP };
+export { type ACPAnnotations, type ACPAskUserQuestionsSettings, type ACPAudioContent, type ACPAuthentication, type ACPAuthenticationMode, type ACPBlobResourceContents, type ACPClientApp, type ACPContentBlock, type ACPCredentialBrokering, type ACPEmbeddedResource, type ACPHarnessSettings, type ACPImageContent, type ACPInstallCommandSource, type ACPInstructionMapping, type ACPMetadata, type ACPModelMapping, type ACPNpmLockedSource, type ACPNpmSimpleSource, type ACPOutputSchemaMapping, type ACPPermissionModeMapping, type ACPPermissionModeTarget, type ACPProfileValue, type ACPProviderAuthentication, type ACPResourceLink, type ACPRole, type ACPSerializablePrimitive, type ACPSerializableValue, type ACPSource, type ACPTextContent, type ACPTextResourceContents, type ACPToolCall, type ACPToolCallContent, type ACPToolCallLocation, type ACPToolCallStatus, type ACPToolKind, type ACPV1Settings, type ACPValueSource, VERSION, createACP };

package/dist/index.js

@@ -1,4 +1,7 @@
 // src/acp-harness.ts
+import {
+  HARNESS_V1_BUILTIN_TOOLS
+} from "@ai-sdk/harness";
 import { z as z4 } from "zod/v4";
 
 // src/v1/acp-v1-harness.ts
@@ -756,13 +759,26 @@ var coldRestoreSchema = z2.object({
 });
 var acpToolCallCandidateSchema = z2.object({
   type: z2.literal("acp-tool-call-candidate"),
+  requestId: z2.string(),
   toolCall: z2.custom(
     (value) => value != null && typeof value === "object" && typeof value.toolCallId === "string" && typeof value.title === "string"
   )
 });
+var acpQuestionRequestSchema = z2.object({
+  type: z2.literal("acp-question-request"),
+  requestId: z2.string(),
+  nativeRequest: z2.unknown(),
+  nativeToolCall: acpToolCallCandidateSchema.shape.toolCall.optional()
+});
+var acpQuestionResolvedSchema = z2.object({
+  type: z2.literal("acp-question-resolved"),
+  requestId: z2.string()
+});
 var outboundMessageSchema = z2.union([
   harnessV1BridgeOutboundMessageSchema,
-  acpToolCallCandidateSchema
+  acpToolCallCandidateSchema,
+  acpQuestionRequestSchema,
+  acpQuestionResolvedSchema
 ]);
 var startMessageSchema = harnessV1BridgeStartBaseSchema.extend({
   prompt: z2.array(acpTextContentBlockSchema),
@@ -828,14 +844,16 @@ var bridgeConfigurationSchema = z3.object({
   providerAuthentication: providerAuthenticationSchema.optional(),
   providerEnvironment: z3.record(z3.string(), z3.string()).optional(),
   sessionMeta: serializableRecordSchema.optional(),
-  clientCapabilities: serializableRecordSchema.optional()
+  clientCapabilities: serializableRecordSchema.optional(),
+  askUserQuestionsRequestMethod: z3.string().optional()
 });
 function createACPBridgeEnvironment({
   authentication,
   providerAuthentication,
   providerEnvironment,
   sessionMeta,
-  clientCapabilities
+  clientCapabilities,
+  askUserQuestionsRequestMethod
 }) {
   return {
     [ACP_BRIDGE_CONFIGURATION_ENV]: JSON.stringify({
@@ -843,7 +861,8 @@ function createACPBridgeEnvironment({
       ...providerAuthentication == null ? {} : { providerAuthentication },
       ...providerEnvironment == null ? {} : { providerEnvironment },
       ...sessionMeta == null ? {} : { sessionMeta },
-      ...clientCapabilities == null ? {} : { clientCapabilities }
+      ...clientCapabilities == null ? {} : { clientCapabilities },
+      ...askUserQuestionsRequestMethod == null ? {} : { askUserQuestionsRequestMethod }
     })
   };
 }
@@ -1367,8 +1386,6 @@ function createACPV1({
           );
         }
         sandboxProviderEnvironment = resolvedProviderAuthentication.providerAuthentication?.type === "ai-gateway" ? {} : void 0;
-      } else if (settings.credentialBrokering != null) {
-        warnCredentialBrokeringUnavailable();
       }
       if (settings.credentialForwarding != null && sandboxProviderEnvironment == null && resolvedProviderAuthentication.providerAuthentication?.type === "ai-gateway") {
         sandboxProviderEnvironment = resolveProviderEnvironment({
@@ -1463,6 +1480,7 @@ function createACPV1({
               sessionMeta: settings.session?.meta,
               instructionMapping: settings.instructionMapping,
               outputSchemaMapping: settings.outputSchemaMapping,
+              askUserQuestions: settings.askUserQuestions,
               debug: startOptions.observability?.debug,
               implementationIdentity,
               authenticationProfile,
@@ -1573,6 +1591,22 @@ function createACPV1({
         credentialEnvironmentVariables: credentialForwardingEnvironmentVariables,
         credentialForwarding: settings.credentialForwarding
       }) : sandboxImplementationEnvironment;
+      if (settings.credentialBrokering != null && sandboxCredentialEnvironment == null) {
+        warnCredentialBrokeringUnavailable({
+          environment: {
+            ...sandboxImplementationEnvironment,
+            ...resolvedProviderAuthentication.env
+          },
+          forwardedEnvironment: {
+            ...forwardedImplementationEnvironment,
+            ...sandboxProviderAuthenticationEnvironment
+          },
+          credentialEnvironmentVariables: [
+            ...credentialForwardingEnvironmentVariables,
+            "AI_SDK_ACP_GATEWAY_API_KEY"
+          ]
+        });
+      }
       const port = resolveBridgePort({
         sandboxSession,
         override: portOverride,
@@ -1598,7 +1632,8 @@ function createACPV1({
             providerAuthentication: resolvedProviderAuthentication.providerAuthentication,
             providerEnvironment: sandboxProviderEnvironment == null ? void 0 : {},
             sessionMeta: settings.session?.meta,
-            clientCapabilities: settings.clientCapabilities
+            clientCapabilities: settings.clientCapabilities,
+            askUserQuestionsRequestMethod: settings.askUserQuestions?.requestMethod
           }),
           ...sandboxProviderAuthenticationEnvironment,
           BRIDGE_CHANNEL_TOKEN: token,
@@ -1706,6 +1741,7 @@ function createACPV1({
         sessionMeta: settings.session?.meta,
         instructionMapping: settings.instructionMapping,
         outputSchemaMapping: settings.outputSchemaMapping,
+        askUserQuestions: settings.askUserQuestions,
         debug: startOptions.observability?.debug,
         implementationIdentity,
         authenticationProfile,
@@ -1943,6 +1979,7 @@ function createSession({
   sessionMeta,
   instructionMapping,
   outputSchemaMapping,
+  askUserQuestions,
   debug,
   implementationIdentity,
   authenticationProfile,
@@ -1976,15 +2013,18 @@ function createSession({
   let instructionsFingerprint = instructionsFingerprintAtStart;
   let latestACPSessionId = acpSessionIdAtStart;
   let latestTurnStartConfig = turnStartConfigAtStart;
+  const bufferedQuestionResults = /* @__PURE__ */ new Map();
   const markTurnFinished = () => {
     turnInFlight = false;
   };
   channel.on("bridge-thread", (event) => {
     latestACPSessionId = event.threadId;
   });
-  channel.on("finish", markTurnFinished);
-  channel.on("error", markTurnFinished);
-  channel.onClose(markTurnFinished);
+  if (!turnInFlightAtStart) {
+    channel.on("finish", markTurnFinished);
+    channel.on("error", markTurnFinished);
+    channel.onClose(markTurnFinished);
+  }
   const wireTurn = ({
     emit,
     abortSignal,
@@ -2003,6 +2043,8 @@ function createSession({
     let openBlock;
     const dynamicToolCalls = /* @__PURE__ */ new Map();
     const toolCallClassificationErrors = /* @__PURE__ */ new Map();
+    const activeQuestionRequests = /* @__PURE__ */ new Map();
+    const questionToolCallIdsByRequestId = /* @__PURE__ */ new Map();
     const subscriptions = [];
     const forward = (event) => {
       if (event.type === "text-start" || event.type === "reasoning-start") {
@@ -2066,12 +2108,115 @@ 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);
         }
       })
     );
@@ -2106,6 +2251,7 @@ function createSession({
     }
     subscriptions.push(
       channel.on("finish", (event) => {
+        markTurnFinished();
         closeForwardedBlock();
         forward(event);
         settle(abortRequested ? { error: abortError } : {});
@@ -2113,6 +2259,7 @@ function createSession({
     );
     subscriptions.push(
       channel.on("error", (event) => {
+        markTurnFinished();
         closeForwardedBlock();
         const error = deserializeBridgeError({
           error: event.error,
@@ -2123,6 +2270,7 @@ function createSession({
       })
     );
     channel.onClose((_code, reason) => {
+      markTurnFinished();
       if (reason === "suspended") {
         settle({});
         return;
@@ -2154,11 +2302,48 @@ 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 !== void 0) {
+              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
+          isError: input.isError,
+          toolResult: input.toolResult
         });
       },
       done
@@ -2472,6 +2657,45 @@ function isCompletePermissionModeMapping({
 }) {
   return isPermissionModeMappingValue({ value: value?.["allow-reads"] }) && isPermissionModeMappingValue({ value: value?.["allow-edits"] }) && isPermissionModeMappingValue({ value: value?.["allow-all"] });
 }
+function withNativeQuestionRequest({
+  harnessId,
+  nativeRequest,
+  toolCall
+}) {
+  const harnessMetadata = toolCall.providerMetadata?.[harnessId];
+  return {
+    ...toolCall,
+    providerMetadata: {
+      ...toolCall.providerMetadata,
+      [harnessId]: {
+        ...harnessMetadata ?? {},
+        nativeRequest
+      }
+    }
+  };
+}
+function takeBufferedQuestionResult({
+  bufferedQuestionResults,
+  toolCallId,
+  nativeRequest,
+  matchesNativeRequest,
+  harnessId
+}) {
+  const exact = bufferedQuestionResults.get(toolCallId);
+  if (exact != null) {
+    bufferedQuestionResults.delete(toolCallId);
+    return exact;
+  }
+  if (matchesNativeRequest == null) return void 0;
+  for (const [bufferedToolCallId, buffered] of bufferedQuestionResults) {
+    const previousNativeRequest = buffered.toolResult.providerOptions?.[harnessId]?.nativeRequest;
+    if (previousNativeRequest !== void 0 && matchesNativeRequest({ previousNativeRequest, nativeRequest })) {
+      bufferedQuestionResults.delete(bufferedToolCallId);
+      return buffered;
+    }
+  }
+  return void 0;
+}
 function isPermissionModeMappingValue({
   value
 }) {
@@ -2617,7 +2841,7 @@ function deserializeBridgeError({
 }
 
 // src/version.ts
-var VERSION = true ? "1.0.37" : "0.0.0-test";
+var VERSION = true ? "1.0.39" : "0.0.0-test";
 
 // src/acp-harness.ts
 var ACP_CLIENT_APP = {
@@ -2677,9 +2901,13 @@ function createACP(settings) {
   switch (version) {
     case "v1": {
       const clientApp = settings.clientApp ?? ACP_CLIENT_APP;
+      const builtinTools = settings.askUserQuestions == null ? settings.builtinTools ?? ACP_BUILTIN_TOOLS : {
+        ...settings.builtinTools ?? ACP_BUILTIN_TOOLS,
+        askUserQuestions: HARNESS_V1_BUILTIN_TOOLS.askUserQuestions
+      };
       return createACPV1({
         settings,
-        builtinTools: settings.builtinTools ?? ACP_BUILTIN_TOOLS,
+        builtinTools,
         port: settings.port,
         portEndpoint: settings.portEndpoint,
         startupTimeoutMs: settings.startupTimeoutMs,