@ai-sdk/harness-acp 1.0.38 → 1.0.40

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
@@ -26,7 +29,9 @@ import {
   shellQuote,
   warnCredentialBrokeringUnavailable,
   waitForBridgeReady,
-  withBridgeToken
+  withBridgeToken,
+  writeInstructions,
+  writeSkills
 } from "@ai-sdk/harness/utils";
 import {
   asSchema
@@ -706,6 +711,10 @@ var instructionMappingSchema = z2.discriminatedUnion("type", [
     type: z2.literal("launch-env-json"),
     variable: z2.string().min(1),
     path: instructionMappingPathSchema
+  }),
+  z2.object({
+    type: z2.literal("filesystem"),
+    path: z2.string().min(1)
   })
 ]);
 var outputSchemaMappingSchema = z2.object({
@@ -756,13 +765,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),
@@ -809,6 +831,10 @@ var profileValueSchema = z3.lazy(
     z3.record(z3.string(), profileValueSchema)
   ])
 );
+var hostToolMcpTransportSchema = z3.enum([
+  "stdio",
+  "http"
+]);
 var serializableRecordSchema = z3.record(z3.string(), serializableValueSchema);
 var profileRecordSchema = z3.record(z3.string(), profileValueSchema);
 var authenticationSchema = z3.object({
@@ -828,14 +854,18 @@ 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(),
+  hostToolMcpTransport: hostToolMcpTransportSchema.optional()
 });
 function createACPBridgeEnvironment({
   authentication,
   providerAuthentication,
   providerEnvironment,
   sessionMeta,
-  clientCapabilities
+  clientCapabilities,
+  askUserQuestionsRequestMethod,
+  hostToolMcpTransport
 }) {
   return {
     [ACP_BRIDGE_CONFIGURATION_ENV]: JSON.stringify({
@@ -843,7 +873,9 @@ function createACPBridgeEnvironment({
       ...providerAuthentication == null ? {} : { providerAuthentication },
       ...providerEnvironment == null ? {} : { providerEnvironment },
       ...sessionMeta == null ? {} : { sessionMeta },
-      ...clientCapabilities == null ? {} : { clientCapabilities }
+      ...clientCapabilities == null ? {} : { clientCapabilities },
+      ...askUserQuestionsRequestMethod == null ? {} : { askUserQuestionsRequestMethod },
+      ...hostToolMcpTransport == null ? {} : { hostToolMcpTransport }
     })
   };
 }
@@ -1066,51 +1098,25 @@ function validateACPLifecycleCompatibility({
 // src/v1/acp-v1-skills.ts
 import { createHash as createHash4 } from "crypto";
 import path from "path";
-import { writeSkills } from "@ai-sdk/harness/utils";
 var ACP_SKILL_NAME_PATTERN = /^[a-z0-9]+(?:-[a-z0-9]+)*$/;
 var DEFAULT_ACP_SKILLS_DIRECTORY = ".agents/skills";
 function resolveACPPrivateSessionDirectory({
   sandboxHomeDir,
-  sessionWorkDir,
   harnessId,
   sessionId
 }) {
   const sessionKey = createHash4("sha256").update(sessionId).digest("hex");
-  const rootDir = path.posix.join(
+  return path.posix.join(
     sandboxHomeDir,
     ".ai-sdk",
     "harness-acp",
     harnessId,
     sessionKey
   );
-  assertOutsideSessionWorkDir({ rootDir, sessionWorkDir });
-  return rootDir;
-}
-async function materializeACPSkills({
-  sandbox,
-  rootDir,
-  sessionWorkDir,
-  skills,
-  abortSignal
-}) {
-  validateACPSkills({ skills });
-  assertOutsideSessionWorkDir({ rootDir, sessionWorkDir });
-  return writeSkills({
-    sandbox,
-    rootDir,
-    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.`
-  });
 }
 function resolveACPSkillsDirectory({
   implementationHomeDir,
-  skillsDirectory = DEFAULT_ACP_SKILLS_DIRECTORY,
-  sessionWorkDir
+  skillsDirectory = DEFAULT_ACP_SKILLS_DIRECTORY
 }) {
   const containsTraversal = skillsDirectory.split(/[\\/]/).some((segment) => segment === "..");
   const normalizedDirectory = path.posix.normalize(skillsDirectory);
@@ -1119,9 +1125,7 @@ function resolveACPSkillsDirectory({
       `ACP skillsDirectory ${JSON.stringify(skillsDirectory)} must be a relative POSIX path without traversal.`
     );
   }
-  const rootDir = path.posix.join(implementationHomeDir, normalizedDirectory);
-  assertOutsideSessionWorkDir({ rootDir, sessionWorkDir });
-  return rootDir;
+  return path.posix.join(implementationHomeDir, normalizedDirectory);
 }
 function validateACPSkills({
   skills
@@ -1179,20 +1183,6 @@ function validateACPAttachedFilePath({
   }
   return normalizedPath;
 }
-function assertOutsideSessionWorkDir({
-  rootDir,
-  sessionWorkDir
-}) {
-  const relative = path.posix.relative(sessionWorkDir, rootDir);
-  const isInside = relative === "" || !relative.startsWith("../") && !path.posix.isAbsolute(relative);
-  if (isInside) {
-    throw new Error(
-      `ACP skill directory ${JSON.stringify(rootDir)} must be outside sessionWorkDir ${JSON.stringify(
-        sessionWorkDir
-      )}.`
-    );
-  }
-}
 
 // src/v1/acp-v1-harness.ts
 var HARNESS_ID_REGEXP = /^[a-z0-9]+(?:-[a-z0-9]+)*$/;
@@ -1359,7 +1349,8 @@ function createACPV1({
         };
         const requestTransformations = settings.credentialBrokering({
           env: brokeringEnvironment,
-          sandboxEnv: sandboxImplementationEnvironment
+          sandboxEnv: sandboxImplementationEnvironment,
+          ...startOptions.headers == null ? {} : { headers: startOptions.headers }
         });
         if (requestTransformations.length > 0) {
           await sandboxSession.addRequestTransformations(
@@ -1397,14 +1388,14 @@ function createACPV1({
       });
       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,
-        skillsDirectory: settings.skillsDirectory,
-        sessionWorkDir: workDir
+        implementationHomeDir,
+        skillsDirectory: settings.skillsDirectory
       });
       const bridgeStateDir = `${privateSessionDir}/bridge`;
       const report = startOptions.observability?.report;
@@ -1461,6 +1452,7 @@ function createACPV1({
               sessionMeta: settings.session?.meta,
               instructionMapping: settings.instructionMapping,
               outputSchemaMapping: settings.outputSchemaMapping,
+              askUserQuestions: settings.askUserQuestions,
               debug: startOptions.observability?.debug,
               implementationIdentity,
               authenticationProfile,
@@ -1475,7 +1467,8 @@ function createACPV1({
               }),
               instructionsFingerprint: lifecycleData.instructionsFingerprint,
               sandbox: toolSafeSandboxSession,
-              sessionWorkDir: workDir,
+              homePath: implementationHomeDir,
+              skillsDir,
               skillsDirectory,
               acpSessionId: lifecycleData.acpSessionId,
               bridgePort: coords.port,
@@ -1612,7 +1605,9 @@ function createACPV1({
             providerAuthentication: resolvedProviderAuthentication.providerAuthentication,
             providerEnvironment: sandboxProviderEnvironment == null ? void 0 : {},
             sessionMeta: settings.session?.meta,
-            clientCapabilities: settings.clientCapabilities
+            clientCapabilities: settings.clientCapabilities,
+            askUserQuestionsRequestMethod: settings.askUserQuestions?.requestMethod,
+            hostToolMcpTransport: settings.hostToolMcpTransport
           }),
           ...sandboxProviderAuthenticationEnvironment,
           BRIDGE_CHANNEL_TOKEN: token,
@@ -1720,6 +1715,7 @@ function createACPV1({
         sessionMeta: settings.session?.meta,
         instructionMapping: settings.instructionMapping,
         outputSchemaMapping: settings.outputSchemaMapping,
+        askUserQuestions: settings.askUserQuestions,
         debug: startOptions.observability?.debug,
         implementationIdentity,
         authenticationProfile,
@@ -1734,7 +1730,8 @@ function createACPV1({
         }),
         instructionsFingerprint: lifecycleData?.instructionsFingerprint,
         sandbox: toolSafeSandboxSession,
-        sessionWorkDir: workDir,
+        homePath: implementationHomeDir,
+        skillsDir,
         skillsDirectory,
         acpSessionId: lifecycleData?.acpSessionId,
         bridgePort: boundPort,
@@ -1957,6 +1954,7 @@ function createSession({
   sessionMeta,
   instructionMapping,
   outputSchemaMapping,
+  askUserQuestions,
   debug,
   implementationIdentity,
   authenticationProfile,
@@ -1968,7 +1966,8 @@ function createSession({
   initialGuidanceApplied: initialGuidanceAppliedAtStart,
   instructionsFingerprint: instructionsFingerprintAtStart,
   sandbox,
-  sessionWorkDir,
+  homePath,
+  skillsDir,
   skillsDirectory,
   acpSessionId: acpSessionIdAtStart,
   bridgePort,
@@ -1990,6 +1989,7 @@ function createSession({
   let instructionsFingerprint = instructionsFingerprintAtStart;
   let latestACPSessionId = acpSessionIdAtStart;
   let latestTurnStartConfig = turnStartConfigAtStart;
+  const bufferedQuestionResults = /* @__PURE__ */ new Map();
   const markTurnFinished = () => {
     turnInFlight = false;
   };
@@ -2019,6 +2019,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") {
@@ -2082,12 +2084,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);
         }
       })
     );
@@ -2173,11 +2278,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
@@ -2241,14 +2383,34 @@ function createSession({
     skills,
     abortSignal
   }) => {
-    await materializeACPSkills({
+    validateACPSkills({ skills });
+    await writeSkills({
       sandbox,
-      rootDir: skillsDirectory,
-      sessionWorkDir,
+      homePath,
+      skillsDir,
       skills,
-      abortSignal
+      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
+  }) => {
+    if (instructionMapping?.type === "filesystem") {
+      await writeInstructions({
+        sandbox,
+        homePath,
+        instructionsFile: instructionMapping.path,
+        instructions,
+        abortSignal
+      });
+    }
+  };
   return {
     sessionId,
     isResume,
@@ -2257,6 +2419,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({
@@ -2315,7 +2481,7 @@ function createSession({
           turnInFlight = true;
           channel.send({
             type: "start",
-            prompt: instructionsFingerprint !== nextInstructionsFingerprint && (instructionMapping == null || initialGuidanceApplied) ? prependACPInstructionGuidance({
+            prompt: instructionMapping?.type !== "filesystem" && instructionsFingerprint !== nextInstructionsFingerprint && (instructionMapping == null || initialGuidanceApplied) ? prependACPInstructionGuidance({
               prompt,
               instructions: options.instructions
             }) : prompt,
@@ -2346,6 +2512,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({
@@ -2421,11 +2591,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 {
@@ -2491,6 +2656,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
 }) {
@@ -2636,7 +2840,7 @@ function deserializeBridgeError({
 }
 
 // src/version.ts
-var VERSION = true ? "1.0.38" : "0.0.0-test";
+var VERSION = true ? "1.0.40" : "0.0.0-test";
 
 // src/acp-harness.ts
 var ACP_CLIENT_APP = {
@@ -2696,9 +2900,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,