@ai-sdk/harness-acp 1.0.1 → 1.0.3

package/dist/index.d.ts

@@ -1,6 +1,104 @@
 import { HarnessV1PermissionMode, HarnessV1 } from '@ai-sdk/harness';
 import { ToolSet } from '@ai-sdk/provider-utils';
 
+type ACPMetadata = Record<string, unknown>;
+type ACPRole = 'assistant' | 'user';
+type ACPAnnotations = {
+    audience?: Array<ACPRole> | null;
+    lastModified?: string | null;
+    priority?: number | null;
+    _meta?: ACPMetadata | null;
+};
+type ACPTextContent = {
+    annotations?: ACPAnnotations | null;
+    text: string;
+    _meta?: ACPMetadata | null;
+};
+type ACPImageContent = {
+    annotations?: ACPAnnotations | null;
+    data: string;
+    mimeType: string;
+    uri?: string | null;
+    _meta?: ACPMetadata | null;
+};
+type ACPAudioContent = {
+    annotations?: ACPAnnotations | null;
+    data: string;
+    mimeType: string;
+    _meta?: ACPMetadata | null;
+};
+type ACPResourceLink = {
+    annotations?: ACPAnnotations | null;
+    description?: string | null;
+    mimeType?: string | null;
+    name: string;
+    size?: number | null;
+    title?: string | null;
+    uri: string;
+    _meta?: ACPMetadata | null;
+};
+type ACPTextResourceContents = {
+    mimeType?: string | null;
+    text: string;
+    uri: string;
+    _meta?: ACPMetadata | null;
+};
+type ACPBlobResourceContents = {
+    blob: string;
+    mimeType?: string | null;
+    uri: string;
+    _meta?: ACPMetadata | null;
+};
+type ACPEmbeddedResource = {
+    annotations?: ACPAnnotations | null;
+    resource: ACPTextResourceContents | ACPBlobResourceContents;
+    _meta?: ACPMetadata | null;
+};
+type ACPContentBlock = (ACPTextContent & {
+    type: 'text';
+}) | (ACPImageContent & {
+    type: 'image';
+}) | (ACPAudioContent & {
+    type: 'audio';
+}) | (ACPResourceLink & {
+    type: 'resource_link';
+}) | (ACPEmbeddedResource & {
+    type: 'resource';
+});
+type ACPToolCallContent = {
+    type: 'content';
+    content: ACPContentBlock;
+    _meta?: ACPMetadata | null;
+} | {
+    type: 'diff';
+    path: string;
+    oldText?: string | null;
+    newText: string;
+    _meta?: ACPMetadata | null;
+} | {
+    type: 'terminal';
+    terminalId: string;
+    _meta?: ACPMetadata | null;
+};
+type ACPToolKind = 'read' | 'edit' | 'delete' | 'move' | 'search' | 'execute' | 'think' | 'fetch' | 'switch_mode' | 'other';
+type ACPToolCallStatus = 'pending' | 'in_progress' | 'completed' | 'failed';
+type ACPToolCallLocation = {
+    path: string;
+    line?: number | null;
+    _meta?: ACPMetadata | null;
+};
+type ACPToolCall = {
+    toolCallId: string;
+    title: string;
+    kind?: ACPToolKind;
+    status?: ACPToolCallStatus;
+    content?: Array<ACPToolCallContent>;
+    locations?: Array<ACPToolCallLocation>;
+    rawInput?: unknown;
+    rawOutput?: unknown;
+    _meta?: ACPMetadata | null;
+};
+
 type ACPSerializablePrimitive = string | number | boolean | null;
 type ACPSerializableValue = ACPSerializablePrimitive | ReadonlyArray<ACPSerializableValue> | {
     readonly [key: string]: ACPSerializableValue;
@@ -50,9 +148,24 @@ type ACPPermissionModeTarget = {
     readonly value: string | boolean;
 };
 type ACPPermissionModeMapping = Readonly<Record<HarnessV1PermissionMode, ACPPermissionModeTarget | null>>;
+/**
+ * Describes where an ACP implementation accepts native session instructions.
+ * Session metadata paths are relative to `_meta`; launch environment paths are
+ * relative to the parsed JSON object stored in `variable`.
+ */
+type ACPInstructionMapping = {
+    readonly type: 'session-meta';
+    readonly path: ReadonlyArray<string>;
+} | {
+    readonly type: 'launch-env-json';
+    readonly variable: string;
+    readonly path: ReadonlyArray<string>;
+};
 type ACPV1Settings = {
     readonly version?: 'v1';
     readonly harnessId: string;
+    readonly mcpServers?: Record<string, unknown>;
+    readonly isMcpToolCall?: (toolCall: ACPToolCall) => boolean;
     readonly auth?: ACPProviderAuthenticationMode;
     readonly source: ACPSource;
     readonly executable: string;
@@ -66,10 +179,20 @@ type ACPV1Settings = {
     readonly authentication?: ACPAuthentication;
     readonly providerAuthentication?: ACPProviderAuthentication;
     readonly modelId?: string;
+    /**
+     * Routes HarnessAgent instructions to a runtime-native system or developer
+     * prompt. When omitted, instructions are prepended to the first user prompt.
+     */
+    readonly instructionMapping?: ACPInstructionMapping;
     readonly permissionModeMapping?: ACPPermissionModeMapping;
     readonly session?: {
         readonly meta?: Readonly<Record<string, ACPSerializableValue>>;
     };
+    /**
+     * Creates the authentication token used by the sandbox bridge. Defaults to
+     * a random 32-byte hexadecimal token.
+     */
+    readonly mintBridgeToken?: (sandboxId: string) => string;
 };
 
 type ACPAuthOptions = ACPProviderAuthenticationMode;
@@ -80,6 +203,12 @@ type ACPClientApp = {
 
 type ACPHarnessSettings<TBuiltinTools extends ToolSet = {}> = {
     readonly builtinTools?: TBuiltinTools;
+    /**
+     * MCP server definitions keyed by server name. Each definition uses the
+     * underlying runtime's native MCP server configuration format.
+     */
+    readonly mcpServers?: Record<string, unknown>;
+    readonly isMcpToolCall?: (toolCall: ACPToolCall) => boolean;
     readonly port?: number;
     readonly startupTimeoutMs?: number;
     readonly clientApp?: ACPClientApp;
@@ -94,11 +223,13 @@ type ACPHarnessSettings<TBuiltinTools extends ToolSet = {}> = {
     readonly authentication?: ACPV1Settings['authentication'];
     readonly providerAuthentication?: ACPV1Settings['providerAuthentication'];
     readonly modelId?: ACPV1Settings['modelId'];
+    readonly instructionMapping?: ACPV1Settings['instructionMapping'];
     readonly permissionModeMapping?: ACPV1Settings['permissionModeMapping'];
     readonly session?: ACPV1Settings['session'];
+    readonly mintBridgeToken?: ACPV1Settings['mintBridgeToken'];
 };
 declare function createACP<TBuiltinTools extends ToolSet = {}>(settings: ACPHarnessSettings<TBuiltinTools>): HarnessV1<TBuiltinTools>;
 
 declare const VERSION: string;
 
-export { type ACPAuthOptions, type ACPAuthentication, type ACPClientApp, type ACPHarnessSettings, type ACPNpmLockedSource, type ACPNpmSimpleSource, type ACPPermissionModeMapping, type ACPPermissionModeTarget, type ACPProfileValue, type ACPProviderAuthentication, type ACPProviderAuthenticationMode, type ACPSerializablePrimitive, type ACPSerializableValue, type ACPSource, type ACPV1Settings, type ACPValueSource, VERSION, createACP };
+export { type ACPAnnotations, type ACPAudioContent, type ACPAuthOptions, type ACPAuthentication, type ACPBlobResourceContents, type ACPClientApp, type ACPContentBlock, type ACPEmbeddedResource, type ACPHarnessSettings, type ACPImageContent, type ACPInstructionMapping, type ACPMetadata, type ACPNpmLockedSource, type ACPNpmSimpleSource, type ACPPermissionModeMapping, type ACPPermissionModeTarget, type ACPProfileValue, type ACPProviderAuthentication, type ACPProviderAuthenticationMode, 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

@@ -518,6 +518,18 @@ var permissionModeMappingSchema = z2.object({
   "allow-edits": permissionModeTargetSchema.nullable(),
   "allow-all": permissionModeTargetSchema.nullable()
 });
+var instructionMappingPathSchema = z2.array(z2.string().min(1)).min(1);
+var instructionMappingSchema = z2.discriminatedUnion("type", [
+  z2.object({
+    type: z2.literal("session-meta"),
+    path: instructionMappingPathSchema
+  }),
+  z2.object({
+    type: z2.literal("launch-env-json"),
+    variable: z2.string().min(1),
+    path: instructionMappingPathSchema
+  })
+]);
 var acpTurnStartConfigSchema = z2.object({
   version: z2.literal(1),
   configurationFingerprint: z2.string(),
@@ -540,9 +552,21 @@ var coldRestoreSchema = z2.object({
   type: z2.literal("cold-restore"),
   acpSessionId: z2.string()
 });
-var outboundMessageSchema = harnessV1BridgeOutboundMessageSchema;
+var acpToolCallCandidateSchema = z2.object({
+  type: z2.literal("acp-tool-call-candidate"),
+  toolCall: z2.custom(
+    (value) => value != null && typeof value === "object" && typeof value.toolCallId === "string" && typeof value.title === "string"
+  )
+});
+var outboundMessageSchema = z2.union([
+  harnessV1BridgeOutboundMessageSchema,
+  acpToolCallCandidateSchema
+]);
 var startMessageSchema = harnessV1BridgeStartBaseSchema.extend({
   prompt: z2.array(acpTextContentBlockSchema),
+  instructions: z2.string().optional(),
+  instructionMapping: instructionMappingSchema.optional(),
+  mcpServers: z2.record(z2.string(), z2.unknown()).optional(),
   tools: z2.array(acpSerializableToolSpecSchema).optional(),
   builtinTools: z2.array(builtinToolSchema).readonly().default([]),
   permissionModeMapping: permissionModeMappingSchema.optional(),
@@ -622,9 +646,11 @@ function createACPTurnStartConfig({
   builtinTools,
   permissionMode,
   permissionModeMapping,
+  mcpServers,
   debug,
   authenticationProfile,
-  sessionMeta
+  sessionMeta,
+  instructionMapping
 }) {
   return {
     version: 1,
@@ -632,8 +658,10 @@ function createACPTurnStartConfig({
       stableStringify3({
         authenticationProfile,
         sessionMeta: sessionMeta ?? null,
+        ...instructionMapping == null ? {} : { instructionMapping },
         builtinTools,
-        permissionModeMapping: permissionModeMapping ?? null
+        permissionModeMapping: permissionModeMapping ?? null,
+        mcpServers: mcpServers ?? null
       })
     ).digest("hex"),
     prompt: [...prompt],
@@ -897,6 +925,14 @@ function createACPV1({
   clientApp,
   lifecycleStateSchema
 }) {
+  if (settings.mcpServers != null && Object.prototype.hasOwnProperty.call(
+    settings.mcpServers,
+    "ai-sdk-harness-tools"
+  )) {
+    throw new Error(
+      'ACP MCP server name "ai-sdk-harness-tools" is reserved for HarnessAgent tools.'
+    );
+  }
   if (!HARNESS_ID_REGEXP.test(settings.harnessId)) {
     throw new Error(
       `ACP harnessId must be a stable kebab-case identifier; received ${JSON.stringify(settings.harnessId)}.`
@@ -1112,12 +1148,15 @@ function createACPV1({
               proc: void 0,
               modelId: settings.modelId,
               sessionMeta: settings.session?.meta,
+              instructionMapping: settings.instructionMapping,
               debug: startOptions.observability?.debug,
               implementationIdentity,
               authenticationProfile,
               builtinTools: builtinToolCatalog,
               permissionMode,
               permissionModeMapping,
+              mcpServers: settings.mcpServers,
+              isMcpToolCall: settings.isMcpToolCall,
               initialGuidanceApplied: resolveACPInitialGuidanceApplied({
                 isResume: true,
                 lifecycleState: lifecycleData
@@ -1166,8 +1205,10 @@ function createACPV1({
                   turnStartConfig,
                   authenticationProfile,
                   sessionMeta: settings.session?.meta,
+                  instructionMapping: settings.instructionMapping,
                   builtinTools: builtinToolCatalog,
-                  permissionModeMapping
+                  permissionModeMapping,
+                  mcpServers: settings.mcpServers
                 });
                 respawnStrategy = {
                   mode: "lossy-rerun",
@@ -1194,8 +1235,10 @@ function createACPV1({
             permissionMode,
             authenticationProfile,
             sessionMeta: settings.session?.meta,
+            instructionMapping: settings.instructionMapping,
             builtinTools: builtinToolCatalog,
             permissionModeMapping,
+            mcpServers: settings.mcpServers,
             debug: startOptions.observability?.debug
           });
           respawnStrategy = {
@@ -1210,7 +1253,7 @@ function createACPV1({
         override: portOverride,
         harnessId: settings.harnessId
       });
-      const token = randomBytes(32).toString("hex");
+      const token = settings.mintBridgeToken == null ? randomBytes(32).toString("hex") : settings.mintBridgeToken(sandboxSession.id);
       await sandbox.run({
         command: `mkdir -p ${shellQuote(workDir)} ${shellQuote(bridgeStateDir)}`,
         abortSignal: startOptions.abortSignal
@@ -1300,6 +1343,8 @@ function createACPV1({
               builtinTools: builtinToolCatalog,
               permissionMode,
               permissionModeMapping,
+              ...settings.instructionMapping == null ? {} : { instructionMapping: settings.instructionMapping },
+              ...settings.mcpServers == null ? {} : { mcpServers: settings.mcpServers },
               tools: respawnStrategy.turnStartConfig.tools,
               turnStartConfig: respawnStrategy.turnStartConfig,
               recoveryMode: {
@@ -1331,12 +1376,15 @@ function createACPV1({
         proc,
         modelId: settings.modelId,
         sessionMeta: settings.session?.meta,
+        instructionMapping: settings.instructionMapping,
         debug: startOptions.observability?.debug,
         implementationIdentity,
         authenticationProfile,
         builtinTools: builtinToolCatalog,
         permissionMode,
         permissionModeMapping,
+        mcpServers: settings.mcpServers,
+        isMcpToolCall: settings.isMcpToolCall,
         initialGuidanceApplied: resolveACPInitialGuidanceApplied({
           isResume,
           lifecycleState: lifecycleData
@@ -1490,12 +1538,15 @@ function createSession({
   proc,
   modelId,
   sessionMeta,
+  instructionMapping,
   debug,
   implementationIdentity,
   authenticationProfile,
   builtinTools,
   permissionMode,
   permissionModeMapping,
+  mcpServers,
+  isMcpToolCall,
   initialGuidanceApplied: initialGuidanceAppliedAtStart,
   skillCatalog,
   skillsFingerprint,
@@ -1542,6 +1593,8 @@ function createSession({
     let abortError;
     let abortListenerAttached = false;
     let openBlock;
+    const dynamicToolCalls = /* @__PURE__ */ new Map();
+    const toolCallClassificationErrors = /* @__PURE__ */ new Map();
     const subscriptions = [];
     const forward = (event) => {
       if (event.type === "text-start" || event.type === "reasoning-start") {
@@ -1574,9 +1627,7 @@ function createSession({
       "reasoning-start",
       "reasoning-delta",
       "reasoning-end",
-      "tool-call",
       "tool-approval-request",
-      "tool-result",
       "file-change",
       "finish-step",
       "raw"
@@ -1604,6 +1655,44 @@ function createSession({
         settle({ error: abortError });
       }
     };
+    subscriptions.push(
+      channel.on("acp-tool-call-candidate", (event) => {
+        try {
+          dynamicToolCalls.set(
+            event.toolCall.toolCallId,
+            isMcpToolCall?.(event.toolCall) === true
+          );
+        } catch (error) {
+          toolCallClassificationErrors.set(event.toolCall.toolCallId, error);
+        }
+      })
+    );
+    subscriptions.push(
+      channel.on("tool-call", (event) => {
+        if (toolCallClassificationErrors.has(event.toolCallId)) {
+          const error = toolCallClassificationErrors.get(event.toolCallId);
+          closeForwardedBlock();
+          forward({ type: "error", error });
+          try {
+            channel.send({ type: "abort" });
+          } catch {
+          }
+          settle({ error });
+          return;
+        }
+        forward(
+          dynamicToolCalls.get(event.toolCallId) === true ? { ...event, dynamic: true } : event
+        );
+      })
+    );
+    subscriptions.push(
+      channel.on("tool-result", (event) => {
+        const dynamic = dynamicToolCalls.get(event.toolCallId) === true;
+        dynamicToolCalls.delete(event.toolCallId);
+        toolCallClassificationErrors.delete(event.toolCallId);
+        forward(dynamic ? { ...event, dynamic: true } : event);
+      })
+    );
     for (const type of eventTypes) {
       subscriptions.push(channel.on(type, (event) => forward(event)));
     }
@@ -1744,9 +1833,11 @@ function createSession({
         builtinTools,
         permissionMode,
         permissionModeMapping,
+        mcpServers,
         debug,
         authenticationProfile,
-        sessionMeta
+        sessionMeta,
+        instructionMapping
       });
       const control = wireTurn({
         emit: options.emit,
@@ -1762,13 +1853,18 @@ function createSession({
             type: "start",
             prompt: initialGuidanceApplied ? prompt : prependACPInitialGuidance({
               prompt,
-              instructions: options.instructions,
+              instructions: instructionMapping == null ? options.instructions : void 0,
               skills: skillCatalog
             }),
+            ...instructionMapping == null ? {} : {
+              instructionMapping,
+              ...options.instructions == null ? {} : { instructions: options.instructions }
+            },
             debug,
             builtinTools,
             permissionMode,
             permissionModeMapping,
+            ...mcpServers == null ? {} : { mcpServers },
             tools: options.tools == null ? void 0 : turnStartConfig.tools,
             turnStartConfig
           });
@@ -1806,6 +1902,11 @@ function createSession({
             builtinTools: turnStartConfig.builtinTools,
             permissionMode: turnStartConfig.permissionMode,
             permissionModeMapping: turnStartConfig.permissionModeMapping,
+            ...instructionMapping == null ? {} : {
+              instructionMapping,
+              ...options.instructions == null ? {} : { instructions: options.instructions }
+            },
+            ...mcpServers == null ? {} : { mcpServers },
             tools: turnStartConfig.tools,
             turnStartConfig,
             recoveryMode: {
@@ -1937,8 +2038,10 @@ function validateACPTurnStartConfig({
   turnStartConfig,
   authenticationProfile,
   sessionMeta,
+  instructionMapping,
   builtinTools,
-  permissionModeMapping
+  permissionModeMapping,
+  mcpServers
 }) {
   const current = createACPTurnStartConfig({
     prompt: turnStartConfig.prompt,
@@ -1946,9 +2049,11 @@ function validateACPTurnStartConfig({
     builtinTools,
     permissionMode: turnStartConfig.permissionMode,
     permissionModeMapping,
+    mcpServers,
     debug: turnStartConfig.debug,
     authenticationProfile,
-    sessionMeta
+    sessionMeta,
+    instructionMapping
   });
   if (current.configurationFingerprint !== turnStartConfig.configurationFingerprint) {
     throw new Error(
@@ -1962,8 +2067,10 @@ function validateACPColdSessionConfiguration({
   permissionMode,
   authenticationProfile,
   sessionMeta,
+  instructionMapping,
   builtinTools,
   permissionModeMapping,
+  mcpServers,
   debug
 }) {
   const current = createACPTurnStartConfig({
@@ -1972,9 +2079,11 @@ function validateACPColdSessionConfiguration({
     builtinTools,
     permissionMode,
     permissionModeMapping,
+    mcpServers,
     debug,
     authenticationProfile,
-    sessionMeta
+    sessionMeta,
+    instructionMapping
   });
   if (current.configurationFingerprint !== coldSession.configurationFingerprint || coldSession.permissionMode !== permissionMode || coldSession.modelId !== modelId) {
     throw new Error(
@@ -2021,7 +2130,7 @@ function deserializeBridgeError({
 }
 
 // src/version.ts
-var VERSION = true ? "1.0.1" : "0.0.0-test";
+var VERSION = true ? "1.0.3" : "0.0.0-test";
 
 // src/acp-harness.ts
 var ACP_CLIENT_APP = {
@@ -2063,6 +2172,14 @@ var acpResumeStateSchema = z4.object({
   skillsFingerprint: z4.string().optional()
 });
 function createACP(settings) {
+  if (settings.mcpServers != null && Object.prototype.hasOwnProperty.call(
+    settings.mcpServers,
+    "ai-sdk-harness-tools"
+  )) {
+    throw new Error(
+      'ACP MCP server name "ai-sdk-harness-tools" is reserved for HarnessAgent tools.'
+    );
+  }
   const version = settings.version ?? "v1";
   switch (version) {
     case "v1": {