@ai-sdk/harness-acp 1.0.10 → 1.0.12

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ai-sdk/harness-acp",
-  "version": "1.0.10",
+  "version": "1.0.12",
   "type": "module",
   "license": "Apache-2.0",
   "sideEffects": false,
@@ -27,7 +27,7 @@
   },
   "dependencies": {
     "ws": "^8.21.0",
-    "@ai-sdk/harness": "1.0.72",
+    "@ai-sdk/harness": "1.0.74",
     "@ai-sdk/provider-utils": "5.0.27"
   },
   "peerDependencies": {

package/src/acp-harness.ts

@@ -40,6 +40,7 @@ export type ACPHarnessSettings<TBuiltinTools extends ToolSet = {}> = {
   readonly providerAuthentication?: ACPV1Settings['providerAuthentication'];
   readonly modelId?: ACPV1Settings['modelId'];
   readonly instructionMapping?: ACPV1Settings['instructionMapping'];
+  readonly outputSchemaMapping?: ACPV1Settings['outputSchemaMapping'];
   readonly permissionModeMapping?: ACPV1Settings['permissionModeMapping'];
   readonly session?: ACPV1Settings['session'];
   readonly mintBridgeToken?: ACPV1Settings['mintBridgeToken'];

package/src/index.ts

@@ -25,6 +25,7 @@ export type {
   ACPInstructionMapping,
   ACPNpmLockedSource,
   ACPNpmSimpleSource,
+  ACPOutputSchemaMapping,
   ACPPermissionModeMapping,
   ACPPermissionModeTarget,
   ACPProfileValue,

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

@@ -100,6 +100,17 @@ const instructionMappingSchema: z.ZodType<ACPInstructionMapping> =
     }),
   ]);
 
+type ACPSerializableOutputSchemaMapping = {
+  readonly type: 'session-prompt-meta';
+  readonly path: string[];
+};
+
+const outputSchemaMappingSchema: z.ZodType<ACPSerializableOutputSchemaMapping> =
+  z.object({
+    type: z.literal('session-prompt-meta'),
+    path: z.array(z.string().min(1)).min(1),
+  });
+
 export type ACPTurnStartConfig = {
   readonly version: 1;
   readonly configurationFingerprint: string;
@@ -109,6 +120,10 @@ export type ACPTurnStartConfig = {
   readonly permissionMode: HarnessV1PermissionMode;
   readonly permissionModeMapping?: ACPPermissionModeMapping;
   readonly debug?: HarnessV1DebugConfig;
+  readonly responseFormat?: z.infer<
+    typeof harnessV1BridgeStartBaseSchema
+  >['responseFormat'];
+  readonly outputSchemaMapping?: ACPSerializableOutputSchemaMapping;
 };
 
 export const acpTurnStartConfigSchema = z.object({
@@ -120,6 +135,9 @@ export const acpTurnStartConfigSchema = z.object({
   permissionMode: harnessV1BridgeStartBaseSchema.shape.permissionMode.unwrap(),
   permissionModeMapping: permissionModeMappingSchema.optional(),
   debug: harnessV1BridgeStartBaseSchema.shape.debug.optional(),
+  responseFormat:
+    harnessV1BridgeStartBaseSchema.shape.responseFormat.optional(),
+  outputSchemaMapping: outputSchemaMappingSchema.optional(),
 }) satisfies z.ZodType<ACPTurnStartConfig>;
 
 export type ACPColdSessionState = Omit<
@@ -166,6 +184,7 @@ export const startMessageSchema = harnessV1BridgeStartBaseSchema.extend({
   prompt: z.array(acpTextContentBlockSchema),
   instructions: z.string().optional(),
   instructionMapping: instructionMappingSchema.optional(),
+  outputSchemaMapping: outputSchemaMappingSchema.optional(),
   mcpServers: z.record(z.string(), z.unknown()).optional(),
   tools: z.array(acpSerializableToolSpecSchema).optional(),
   builtinTools: z.array(builtinToolSchema).readonly().default([]),

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

@@ -76,6 +76,7 @@ import {
 } from './acp-v1-prompt';
 import type {
   ACPInstructionMapping,
+  ACPOutputSchemaMapping,
   ACPPermissionModeMapping,
   ACPPermissionModeTarget,
   ACPSerializableValue,
@@ -388,6 +389,7 @@ export function createACPV1<TBuiltinTools extends ToolSet = {}>({
               modelId: settings.modelId,
               sessionMeta: settings.session?.meta,
               instructionMapping: settings.instructionMapping,
+              outputSchemaMapping: settings.outputSchemaMapping,
               debug: startOptions.observability?.debug,
               implementationIdentity,
               authenticationProfile,
@@ -446,6 +448,7 @@ export function createACPV1<TBuiltinTools extends ToolSet = {}>({
                   authenticationProfile,
                   sessionMeta: settings.session?.meta,
                   instructionMapping: settings.instructionMapping,
+                  outputSchemaMapping: settings.outputSchemaMapping,
                   builtinTools: builtinToolCatalog,
                   permissionModeMapping,
                   mcpServers: settings.mcpServers,
@@ -477,6 +480,7 @@ export function createACPV1<TBuiltinTools extends ToolSet = {}>({
             authenticationProfile,
             sessionMeta: settings.session?.meta,
             instructionMapping: settings.instructionMapping,
+            outputSchemaMapping: settings.outputSchemaMapping,
             builtinTools: builtinToolCatalog,
             permissionModeMapping,
             mcpServers: settings.mcpServers,
@@ -638,6 +642,7 @@ export function createACPV1<TBuiltinTools extends ToolSet = {}>({
         modelId: settings.modelId,
         sessionMeta: settings.session?.meta,
         instructionMapping: settings.instructionMapping,
+        outputSchemaMapping: settings.outputSchemaMapping,
         debug: startOptions.observability?.debug,
         implementationIdentity,
         authenticationProfile,
@@ -879,6 +884,7 @@ function createSession({
   modelId,
   sessionMeta,
   instructionMapping,
+  outputSchemaMapping,
   debug,
   implementationIdentity,
   authenticationProfile,
@@ -910,6 +916,7 @@ function createSession({
   modelId: string | undefined;
   sessionMeta: Readonly<Record<string, ACPSerializableValue>> | undefined;
   instructionMapping: ACPInstructionMapping | undefined;
+  outputSchemaMapping: ACPOutputSchemaMapping | undefined;
   debug: HarnessV1DebugConfig | undefined;
   implementationIdentity: string;
   authenticationProfile: ACPAuthenticationProfileIdentity;
@@ -1211,6 +1218,20 @@ function createSession({
     isResume,
     ...(modelId == null ? {} : { modelId }),
     doPromptTurn: async options => {
+      if (options.responseFormat?.type === 'json') {
+        if (options.responseFormat.schema == null) {
+          throw unsupported({
+            harnessId,
+            message: `${harnessId} requires a JSON schema for structured output.`,
+          });
+        }
+        if (outputSchemaMapping == null) {
+          throw unsupported({
+            harnessId,
+            message: `${harnessId} does not support structured output through ACP.`,
+          });
+        }
+      }
       if (replayOnly) {
         throw new Error(
           `${harnessId} recovered this turn through disk replay only and has no restored ACP process for a subsequent prompt.`,
@@ -1237,6 +1258,8 @@ function createSession({
         authenticationProfile,
         sessionMeta,
         instructionMapping,
+        responseFormat: options.responseFormat,
+        outputSchemaMapping,
       });
       const control = wireTurn({
         emit: options.emit,
@@ -1272,6 +1295,12 @@ function createSession({
             builtinTools,
             permissionMode,
             permissionModeMapping,
+            ...(options.responseFormat == null
+              ? {}
+              : { responseFormat: options.responseFormat }),
+            ...(turnStartConfig.outputSchemaMapping == null
+              ? {}
+              : { outputSchemaMapping: turnStartConfig.outputSchemaMapping }),
             ...(mcpServers == null ? {} : { mcpServers }),
             tools: options.tools == null ? undefined : turnStartConfig.tools,
             turnStartConfig,
@@ -1283,6 +1312,20 @@ function createSession({
       return control;
     },
     doContinueTurn: async options => {
+      if (options.responseFormat?.type === 'json') {
+        if (options.responseFormat.schema == null) {
+          throw unsupported({
+            harnessId,
+            message: `${harnessId} requires a JSON schema for structured output.`,
+          });
+        }
+        if (outputSchemaMapping == null) {
+          throw unsupported({
+            harnessId,
+            message: `${harnessId} does not support structured output through ACP.`,
+          });
+        }
+      }
       if (!turnInFlight) {
         throw new Error(`${harnessId} has no in-flight ACP turn to continue.`);
       }
@@ -1310,6 +1353,12 @@ function createSession({
             builtinTools: turnStartConfig.builtinTools,
             permissionMode: turnStartConfig.permissionMode,
             permissionModeMapping: turnStartConfig.permissionModeMapping,
+            ...(turnStartConfig.responseFormat == null
+              ? {}
+              : { responseFormat: turnStartConfig.responseFormat }),
+            ...(turnStartConfig.outputSchemaMapping == null
+              ? {}
+              : { outputSchemaMapping: turnStartConfig.outputSchemaMapping }),
             ...(instructionMapping == null
               ? {}
               : {
@@ -1482,6 +1531,7 @@ function validateACPTurnStartConfig({
   authenticationProfile,
   sessionMeta,
   instructionMapping,
+  outputSchemaMapping,
   builtinTools,
   permissionModeMapping,
   mcpServers,
@@ -1490,6 +1540,7 @@ function validateACPTurnStartConfig({
   authenticationProfile: ACPAuthenticationProfileIdentity;
   sessionMeta: Readonly<Record<string, ACPSerializableValue>> | undefined;
   instructionMapping: ACPInstructionMapping | undefined;
+  outputSchemaMapping: ACPOutputSchemaMapping | undefined;
   builtinTools: ReadonlyArray<ACPBuiltinToolMapping>;
   permissionModeMapping: ACPPermissionModeMapping | undefined;
   mcpServers: Record<string, unknown> | undefined;
@@ -1505,6 +1556,8 @@ function validateACPTurnStartConfig({
     authenticationProfile,
     sessionMeta,
     instructionMapping,
+    responseFormat: turnStartConfig.responseFormat,
+    outputSchemaMapping,
   });
   if (
     current.configurationFingerprint !==
@@ -1523,6 +1576,7 @@ function validateACPColdSessionConfiguration({
   authenticationProfile,
   sessionMeta,
   instructionMapping,
+  outputSchemaMapping,
   builtinTools,
   permissionModeMapping,
   mcpServers,
@@ -1534,6 +1588,7 @@ function validateACPColdSessionConfiguration({
   authenticationProfile: ACPAuthenticationProfileIdentity;
   sessionMeta: Readonly<Record<string, ACPSerializableValue>> | undefined;
   instructionMapping: ACPInstructionMapping | undefined;
+  outputSchemaMapping: ACPOutputSchemaMapping | undefined;
   builtinTools: ReadonlyArray<ACPBuiltinToolMapping>;
   permissionModeMapping: ACPPermissionModeMapping | undefined;
   mcpServers: Record<string, unknown> | undefined;
@@ -1550,6 +1605,8 @@ function validateACPColdSessionConfiguration({
     authenticationProfile,
     sessionMeta,
     instructionMapping,
+    responseFormat: coldSession.responseFormat,
+    outputSchemaMapping,
   });
   if (
     current.configurationFingerprint !== coldSession.configurationFingerprint ||

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

@@ -100,6 +100,11 @@ export type ACPInstructionMapping =
       readonly path: ReadonlyArray<string>;
     };
 
+export type ACPOutputSchemaMapping = {
+  readonly type: 'session-prompt-meta';
+  readonly path: ReadonlyArray<string>;
+};
+
 export type ACPV1Settings = {
   readonly version?: 'v1';
   readonly harnessId: string;
@@ -125,6 +130,11 @@ export type ACPV1Settings = {
    * prompt. When omitted, instructions are prepended to the first user prompt.
    */
   readonly instructionMapping?: ACPInstructionMapping;
+  /**
+   * Maps structured output JSON Schema to an implementation-specific path
+   * below the ACP session prompt's `_meta` field.
+   */
+  readonly outputSchemaMapping?: ACPOutputSchemaMapping;
   readonly permissionModeMapping?: ACPPermissionModeMapping;
   readonly session?: {
     readonly meta?: Readonly<Record<string, ACPSerializableValue>>;

package/src/v1/acp-v1-turn-start-config.ts

@@ -11,6 +11,7 @@ import {
 import type { ACPTextContentBlock } from './acp-v1-prompt';
 import type {
   ACPInstructionMapping,
+  ACPOutputSchemaMapping,
   ACPPermissionModeMapping,
   ACPSerializableValue,
 } from './acp-v1-settings';
@@ -26,6 +27,8 @@ export function createACPTurnStartConfig({
   authenticationProfile,
   sessionMeta,
   instructionMapping,
+  responseFormat,
+  outputSchemaMapping,
 }: {
   prompt: ReadonlyArray<ACPTextContentBlock>;
   tools: ReadonlyArray<HarnessV1ToolSpec>;
@@ -37,6 +40,8 @@ export function createACPTurnStartConfig({
   authenticationProfile: ACPAuthenticationProfileIdentity;
   sessionMeta: Readonly<Record<string, ACPSerializableValue>> | undefined;
   instructionMapping: ACPInstructionMapping | undefined;
+  responseFormat: StartMessage['responseFormat'];
+  outputSchemaMapping: ACPOutputSchemaMapping | undefined;
 }): ACPTurnStartConfig {
   return {
     version: 1,
@@ -46,6 +51,7 @@ export function createACPTurnStartConfig({
           authenticationProfile,
           sessionMeta: sessionMeta ?? null,
           ...(instructionMapping == null ? {} : { instructionMapping }),
+          ...(outputSchemaMapping == null ? {} : { outputSchemaMapping }),
           builtinTools,
           permissionModeMapping: permissionModeMapping ?? null,
           mcpServers: mcpServers ?? null,
@@ -56,6 +62,15 @@ export function createACPTurnStartConfig({
     tools: tools.map(tool => acpSerializableToolSpecSchema.parse(tool)),
     builtinTools: [...builtinTools],
     permissionMode,
+    ...(responseFormat == null ? {} : { responseFormat }),
+    ...(outputSchemaMapping == null
+      ? {}
+      : {
+          outputSchemaMapping: {
+            type: outputSchemaMapping.type,
+            path: [...outputSchemaMapping.path],
+          },
+        }),
     ...(permissionModeMapping == null ? {} : { permissionModeMapping }),
     ...(debug == null ? {} : { debug }),
   };
@@ -74,6 +89,12 @@ export function createACPColdSessionState({
     tools: turnStartConfig.tools,
     builtinTools: turnStartConfig.builtinTools,
     permissionMode: turnStartConfig.permissionMode,
+    ...(turnStartConfig.responseFormat == null
+      ? {}
+      : { responseFormat: turnStartConfig.responseFormat }),
+    ...(turnStartConfig.outputSchemaMapping == null
+      ? {}
+      : { outputSchemaMapping: turnStartConfig.outputSchemaMapping }),
     ...(turnStartConfig.permissionModeMapping == null
       ? {}
       : { permissionModeMapping: turnStartConfig.permissionModeMapping }),

package/src/v1/bridge/index.ts

@@ -261,7 +261,13 @@ async function runTurn(start: StartMessage, turn: BridgeTurn): Promise<void> {
   };
   hostToolRelay?.bindTurn({ turn: relayTurn });
   try {
-    void activeSession.prompt(start.prompt);
+    const promptMeta = createOutputSchemaPromptMeta({ start });
+    void promptActiveSession({
+      session: activeSession,
+      agent: connection!.agent,
+      prompt: start.prompt,
+      meta: promptMeta,
+    });
     if (turn.abortSignal.aborted) {
       await cancel();
     } else {
@@ -706,6 +712,81 @@ function isRecord(value: unknown): value is Readonly<Record<string, unknown>> {
   return value != null && typeof value === 'object' && !Array.isArray(value);
 }
 
+function createOutputSchemaPromptMeta({
+  start,
+}: {
+  start: StartMessage;
+}): Record<string, unknown> | undefined {
+  if (
+    start.responseFormat?.type !== 'json' ||
+    start.responseFormat.schema == null ||
+    start.outputSchemaMapping?.type !== 'session-prompt-meta'
+  ) {
+    return undefined;
+  }
+  const root: Record<string, unknown> = {};
+  let target = root;
+  const path = start.outputSchemaMapping.path;
+  for (let index = 0; index < path.length - 1; index++) {
+    const child: Record<string, unknown> = {};
+    target[path[index]!] = child;
+    target = child;
+  }
+  target[path[path.length - 1]!] = start.responseFormat.schema;
+  return root;
+}
+
+function promptActiveSession({
+  session,
+  agent,
+  prompt,
+  meta,
+}: {
+  session: ACPActiveSession;
+  agent: acp.ClientContext;
+  prompt: Array<acp.ContentBlock>;
+  meta: Record<string, unknown> | undefined;
+}): Promise<acp.PromptResponse> {
+  if (meta == null) return session.prompt(prompt);
+  if (session.promptWithMeta != null) {
+    return session.promptWithMeta({ prompt, meta });
+  }
+  const updates = (
+    session as unknown as {
+      updates?: {
+        clearErrors(): void;
+        enqueue(value: acp.ActiveSessionMessage): void;
+        reject(error: unknown): void;
+      };
+    }
+  ).updates;
+  if (updates == null) {
+    throw new Error(
+      'The installed ACP SDK cannot send session prompt metadata while preserving streamed updates.',
+    );
+  }
+  updates.clearErrors();
+  const response = agent.request<acp.PromptResponse, acp.PromptRequest>(
+    acp.methods.agent.session.prompt,
+    {
+      sessionId: session.sessionId,
+      prompt,
+      _meta: meta,
+    },
+  );
+  void response.then(
+    value => {
+      updates.enqueue({
+        kind: 'stop',
+        response: value,
+        stopReason: value.stopReason,
+      });
+    },
+    error => updates.reject(error),
+  );
+  return response;
+}
+
 async function readImplementationDescriptor({
   path,
 }: {

package/src/v1/bridge/recovered-session.ts

@@ -6,6 +6,10 @@ export type ACPActiveSession = {
   readonly sessionId: string;
   readonly newSessionResponse: acp.NewSessionResponse;
   prompt(prompt: Array<acp.ContentBlock>): Promise<acp.PromptResponse>;
+  promptWithMeta?(options: {
+    prompt: Array<acp.ContentBlock>;
+    meta: Record<string, unknown>;
+  }): Promise<acp.PromptResponse>;
   nextUpdate(): Promise<acp.ActiveSessionMessage>;
   dispose(): void;
 };
@@ -70,6 +74,27 @@ export function createACPRecoveredSession({
       );
       return response;
     },
+    promptWithMeta: async ({ prompt, meta }) => {
+      if (disposed) {
+        throw new Error('Recovered ACP session is disposed.');
+      }
+      updates.clearErrors();
+      const response = agent.request<acp.PromptResponse, acp.PromptRequest>(
+        acp.methods.agent.session.prompt,
+        { sessionId, prompt, _meta: meta },
+      );
+      void response.then(
+        value => {
+          updates.enqueue({
+            kind: 'stop',
+            response: value,
+            stopReason: value.stopReason,
+          });
+        },
+        error => updates.reject(error),
+      );
+      return response;
+    },
     nextUpdate: () => updates.next(),
     dispose: () => {
       if (disposed) return;

package/src/v1/index.ts

@@ -5,6 +5,7 @@ export type {
   ACPInstructionMapping,
   ACPNpmLockedSource,
   ACPNpmSimpleSource,
+  ACPOutputSchemaMapping,
   ACPPermissionModeMapping,
   ACPPermissionModeTarget,
   ACPProfileValue,