@ai-sdk/harness-acp 0.0.0 → 1.0.0

package/src/acp-auth.ts

@@ -0,0 +1,254 @@
+import { createHash } from 'node:crypto';
+import { getAiGatewayAuthFromEnv } from '@ai-sdk/harness/utils';
+import type {
+  ACPAuthentication,
+  ACPProviderAuthentication,
+  ACPProviderAuthenticationMode,
+} from './v1';
+import type { ACPResolvedProviderAuthentication } from './v1/bridge/acp-v1-bridge-environment';
+
+const DEFAULT_AI_GATEWAY_BASE_URL = 'https://ai-gateway.vercel.sh';
+
+export type ACPAuthOptions = ACPProviderAuthenticationMode;
+
+export type ACPClientApp = {
+  readonly name: string;
+  readonly version: string;
+};
+
+type ACPAuthResolutionOptions = {
+  readonly mode?: ACPAuthOptions;
+  readonly providerAuthentication: ACPProviderAuthentication | undefined;
+  readonly clientApp: ACPClientApp;
+};
+
+type ACPGatewayCredentialSource = 'AI_GATEWAY_API_KEY' | 'VERCEL_OIDC_TOKEN';
+
+export type ACPProviderAuthenticationCompatibility =
+  | {
+      readonly type: 'direct';
+      readonly mode: 'auto' | 'direct';
+    }
+  | {
+      readonly type: 'ai-gateway';
+      readonly mode: 'auto' | 'ai-gateway';
+      readonly env: ACPProviderAuthentication['gateway']['env'];
+      readonly credentialSource: ACPGatewayCredentialSource | null;
+      readonly baseUrl: string;
+    };
+
+export type ACPAuthenticationProfileIdentity = {
+  readonly digest: string;
+  readonly acpMethodId?: string;
+  readonly providerKind: 'direct' | 'ai-gateway';
+  readonly providerMode?: 'auto' | 'direct' | 'ai-gateway';
+  readonly gatewayCredentialSource?:
+    | 'AI_GATEWAY_API_KEY'
+    | 'VERCEL_OIDC_TOKEN'
+    | null;
+};
+
+export function createACPAuthenticationProfileIdentity({
+  authentication,
+  providerAuthenticationCompatibility,
+}: {
+  authentication: ACPAuthentication | undefined;
+  providerAuthenticationCompatibility:
+    | ACPProviderAuthenticationCompatibility
+    | undefined;
+}): ACPAuthenticationProfileIdentity {
+  const providerKind = providerAuthenticationCompatibility?.type ?? 'direct';
+  const digest = createHash('sha256')
+    .update(
+      stableStringify({
+        value: {
+          authentication: authentication ?? null,
+          providerAuthentication: providerAuthenticationCompatibility ?? null,
+        },
+      }),
+    )
+    .digest('hex');
+  return {
+    digest,
+    ...(authentication == null ? {} : { acpMethodId: authentication.methodId }),
+    providerKind,
+    ...(providerAuthenticationCompatibility == null
+      ? {}
+      : { providerMode: providerAuthenticationCompatibility.mode }),
+    ...(providerAuthenticationCompatibility?.type === 'ai-gateway'
+      ? {
+          gatewayCredentialSource:
+            providerAuthenticationCompatibility.credentialSource,
+        }
+      : {}),
+  };
+}
+
+export function resolveACPProviderAuthentication({
+  auth,
+  env,
+  compatibility,
+}: {
+  auth: ACPAuthResolutionOptions;
+  env: Record<string, string | undefined>;
+  compatibility?: ACPProviderAuthenticationCompatibility;
+}): {
+  readonly providerAuthentication:
+    | ACPResolvedProviderAuthentication
+    | undefined;
+  readonly env: Record<string, string>;
+} {
+  const clientAppEnv = {
+    AI_SDK_ACP_CLIENT_APP_NAME: auth.clientApp.name,
+    AI_SDK_ACP_CLIENT_APP_VERSION: auth.clientApp.version,
+  };
+  const providerAuthentication = auth.providerAuthentication;
+  if (providerAuthentication == null) {
+    return { providerAuthentication: undefined, env: clientAppEnv };
+  }
+
+  if (compatibility?.type === 'direct') {
+    return {
+      providerAuthentication: { type: 'direct' },
+      env: clientAppEnv,
+    };
+  }
+
+  const mode = auth.mode ?? 'auto';
+  if (mode === 'direct') {
+    return {
+      providerAuthentication: { type: 'direct' },
+      env: clientAppEnv,
+    };
+  }
+
+  const gateway =
+    compatibility?.type === 'ai-gateway'
+      ? {
+          apiKey: resolveGatewayCredential({
+            env,
+            credentialSource: compatibility.credentialSource,
+          }),
+          baseUrl: compatibility.baseUrl,
+        }
+      : getAiGatewayAuthFromEnv({ env });
+  const apiKey = gateway.apiKey;
+  if (compatibility == null && mode === 'auto' && apiKey == null) {
+    return {
+      providerAuthentication: { type: 'direct' },
+      env: clientAppEnv,
+    };
+  }
+  if (apiKey == null) {
+    throw new Error(
+      'AI Gateway authentication was selected, but neither AI_GATEWAY_API_KEY nor VERCEL_OIDC_TOKEN is set.',
+    );
+  }
+
+  return {
+    providerAuthentication: {
+      type: 'ai-gateway',
+      env:
+        compatibility?.type === 'ai-gateway'
+          ? compatibility.env
+          : providerAuthentication.gateway.env,
+    },
+    env: {
+      AI_SDK_ACP_GATEWAY_API_KEY: apiKey,
+      AI_SDK_ACP_GATEWAY_BASE_URL: gateway.baseUrl,
+      ...clientAppEnv,
+    },
+  };
+}
+
+export function resolveACPProviderAuthenticationCompatibility({
+  auth = 'auto',
+  providerAuthentication,
+  env,
+}: {
+  auth?: ACPProviderAuthenticationMode;
+  providerAuthentication: ACPProviderAuthentication | undefined;
+  env: Record<string, string | undefined>;
+}): ACPProviderAuthenticationCompatibility | undefined {
+  if (providerAuthentication == null) return undefined;
+
+  const mode = auth;
+  if (mode === 'direct') {
+    return { type: 'direct', mode };
+  }
+
+  const credentialSource = resolveGatewayCredentialSource({
+    env,
+  });
+  if (mode === 'auto' && credentialSource == null) {
+    return { type: 'direct', mode };
+  }
+
+  return {
+    type: 'ai-gateway',
+    mode,
+    env: providerAuthentication.gateway.env,
+    credentialSource,
+    baseUrl: env.AI_GATEWAY_BASE_URL ?? DEFAULT_AI_GATEWAY_BASE_URL,
+  };
+}
+
+export function resolveACPEnv({
+  auth,
+  env,
+}: {
+  auth: ACPAuthResolutionOptions;
+  env: Record<string, string | undefined>;
+}): Record<string, string> {
+  return resolveACPProviderAuthentication({ auth, env }).env;
+}
+
+function resolveGatewayCredentialSource({
+  env,
+}: {
+  env: Record<string, string | undefined>;
+}): ACPGatewayCredentialSource | null {
+  return env.AI_GATEWAY_API_KEY
+    ? 'AI_GATEWAY_API_KEY'
+    : env.VERCEL_OIDC_TOKEN
+      ? 'VERCEL_OIDC_TOKEN'
+      : null;
+}
+
+function resolveGatewayCredential({
+  env,
+  credentialSource,
+}: {
+  env: Record<string, string | undefined>;
+  credentialSource: ACPGatewayCredentialSource | null;
+}): string | undefined {
+  const gatewayFromEnv = getAiGatewayAuthFromEnv({ env });
+  switch (credentialSource) {
+    case 'AI_GATEWAY_API_KEY':
+      return env.AI_GATEWAY_API_KEY == null ? undefined : gatewayFromEnv.apiKey;
+    case 'VERCEL_OIDC_TOKEN':
+      return getAiGatewayAuthFromEnv({
+        env: { VERCEL_OIDC_TOKEN: env.VERCEL_OIDC_TOKEN },
+      }).apiKey;
+    case null:
+      return undefined;
+  }
+}
+
+function stableStringify({ value }: { value: unknown }): string {
+  return JSON.stringify(sortIdentityValue({ value }));
+}
+
+function sortIdentityValue({ value }: { value: unknown }): unknown {
+  if (Array.isArray(value)) {
+    return value.map(item => sortIdentityValue({ value: item }));
+  }
+  if (value != null && typeof value === 'object') {
+    return Object.fromEntries(
+      Object.entries(value)
+        .sort(([left], [right]) => (left < right ? -1 : left > right ? 1 : 0))
+        .map(([key, entry]) => [key, sortIdentityValue({ value: entry })]),
+    );
+  }
+  return value;
+}

package/src/acp-bridge-protocol.ts

@@ -0,0 +1,13 @@
+import * as acpV1BridgeProtocol from './v1/acp-v1-bridge-protocol';
+
+export const outboundMessageSchema = acpV1BridgeProtocol.outboundMessageSchema;
+export type OutboundMessage = acpV1BridgeProtocol.OutboundMessage;
+
+export const startMessageSchema = acpV1BridgeProtocol.startMessageSchema;
+export type StartMessage = acpV1BridgeProtocol.StartMessage;
+
+export const inboundMessageSchema = acpV1BridgeProtocol.inboundMessageSchema;
+export type InboundMessage = acpV1BridgeProtocol.InboundMessage;
+
+export const bridgeReadySchema = acpV1BridgeProtocol.bridgeReadySchema;
+export type BridgeReady = acpV1BridgeProtocol.BridgeReady;

package/src/acp-harness.ts

@@ -0,0 +1,160 @@
+import type { HarnessV1 } from '@ai-sdk/harness';
+import type { ToolSet } from '@ai-sdk/provider-utils';
+import { z } from 'zod/v4';
+import {
+  createACPAuthenticationProfileIdentity,
+  resolveACPProviderAuthenticationCompatibility,
+  type ACPAuthenticationProfileIdentity,
+  type ACPClientApp,
+} from './acp-auth';
+import { createACPV1, type ACPV1Settings } from './v1';
+import { createImplementationIdentity } from './v1/implementation';
+import {
+  acpColdSessionStateSchema,
+  acpTurnStartConfigSchema,
+  type ACPColdSessionState,
+  type ACPTurnStartConfig,
+} from './v1/acp-v1-bridge-protocol';
+import { VERSION } from './version';
+
+const ACP_CLIENT_APP = {
+  name: 'ai-sdk/harness-acp',
+  version: VERSION,
+} as const satisfies ACPClientApp;
+
+export type ACPHarnessSettings<TBuiltinTools extends ToolSet = {}> = {
+  readonly builtinTools?: TBuiltinTools;
+  readonly port?: number;
+  readonly startupTimeoutMs?: number;
+  readonly clientApp?: ACPClientApp;
+  readonly version?: ACPV1Settings['version'];
+  readonly harnessId: ACPV1Settings['harnessId'];
+  readonly auth?: ACPV1Settings['auth'];
+  readonly implementation: ACPV1Settings['implementation'];
+  readonly authentication?: ACPV1Settings['authentication'];
+  readonly providerAuthentication?: ACPV1Settings['providerAuthentication'];
+  readonly modelId?: ACPV1Settings['modelId'];
+  readonly permissionModeMapping?: ACPV1Settings['permissionModeMapping'];
+  readonly session?: ACPV1Settings['session'];
+};
+
+const ACP_BUILTIN_TOOLS = {} as const satisfies ToolSet;
+
+const acpBridgeCoordsSchema = z.object({
+  port: z.number(),
+  token: z.string(),
+  lastSeenEventId: z.number(),
+  sandboxId: z.string().optional(),
+  stateDir: z.string().optional(),
+});
+
+const acpResumeStateSchema = z.object({
+  implementationIdentity: z.string(),
+  authenticationProfile: z
+    .object({
+      digest: z.string(),
+      acpMethodId: z.string().optional(),
+      providerKind: z
+        .enum(['implementation-default', 'direct', 'ai-gateway'])
+        .transform(value =>
+          value === 'implementation-default' ? 'direct' : value,
+        ),
+      providerMode: z.enum(['auto', 'direct', 'ai-gateway']).optional(),
+      gatewayCredentialSource: z
+        .enum(['AI_GATEWAY_API_KEY', 'VERCEL_OIDC_TOKEN'])
+        .nullable()
+        .optional(),
+    })
+    .optional(),
+  acpSessionId: z.string().optional(),
+  bridge: acpBridgeCoordsSchema.optional(),
+  coldSession: acpColdSessionStateSchema.optional(),
+  turnStartConfig: acpTurnStartConfigSchema.optional(),
+  recovery: z
+    .object({
+      mode: z.enum(['disk-replay', 'lossy-rerun']),
+      reason: z.string(),
+    })
+    .optional(),
+  restoration: z
+    .object({
+      method: z.enum(['resume', 'load']),
+    })
+    .optional(),
+  initialGuidanceApplied: z.boolean().optional(),
+  skillsMaterialized: z.boolean().optional(),
+  skillsFingerprint: z.string().optional(),
+});
+
+type ACPBridgeCoords = z.infer<typeof acpBridgeCoordsSchema>;
+
+export function createACP<TBuiltinTools extends ToolSet = {}>(
+  settings: ACPHarnessSettings<TBuiltinTools>,
+): HarnessV1<TBuiltinTools> {
+  const version = (settings as { readonly version?: string }).version ?? 'v1';
+  switch (version) {
+    case 'v1': {
+      const clientApp = settings.clientApp ?? ACP_CLIENT_APP;
+      const providerAuthenticationCompatibility =
+        resolveACPProviderAuthenticationCompatibility({
+          auth: settings.auth,
+          providerAuthentication: settings.providerAuthentication,
+          env: process.env,
+        });
+      const implementationIdentity = createImplementationIdentity({
+        harnessId: settings.harnessId,
+        acpVersion: version,
+        implementation: settings.implementation,
+        clientApp,
+        providerAuthentication: providerAuthenticationCompatibility,
+        permissionModeMapping: settings.permissionModeMapping,
+      });
+      const authenticationProfile = createACPAuthenticationProfileIdentity({
+        authentication: settings.authentication,
+        providerAuthenticationCompatibility,
+      });
+      const lifecycleStateSchema: z.ZodType<{
+        readonly implementationIdentity: string;
+        readonly authenticationProfile?: ACPAuthenticationProfileIdentity;
+        readonly acpSessionId?: string;
+        readonly bridge?: ACPBridgeCoords;
+        readonly coldSession?: ACPColdSessionState;
+        readonly turnStartConfig?: ACPTurnStartConfig;
+        readonly recovery?: {
+          readonly mode: 'disk-replay' | 'lossy-rerun';
+          readonly reason: string;
+        };
+        readonly restoration?: {
+          readonly method: 'resume' | 'load';
+        };
+        readonly initialGuidanceApplied?: boolean;
+        readonly skillsMaterialized?: boolean;
+        readonly skillsFingerprint?: string;
+      }> = acpResumeStateSchema.extend({
+        implementationIdentity: z.literal(implementationIdentity),
+        authenticationProfile: acpResumeStateSchema.shape.authenticationProfile
+          .unwrap()
+          .extend({
+            digest: z.literal(authenticationProfile.digest),
+          })
+          .optional(),
+      });
+      return createACPV1({
+        settings,
+        builtinTools:
+          settings.builtinTools ?? (ACP_BUILTIN_TOOLS as TBuiltinTools),
+        port: settings.port,
+        startupTimeoutMs: settings.startupTimeoutMs,
+        clientApp,
+        implementationIdentity,
+        authenticationProfile,
+        providerAuthenticationCompatibility,
+        lifecycleStateSchema,
+      });
+    }
+    default:
+      throw new Error(
+        `Unsupported ACP protocol version ${JSON.stringify(version)}. Supported versions: "v1".`,
+      );
+  }
+}

package/src/index.ts

@@ -0,0 +1,19 @@
+export { createACP } from './acp-harness';
+export type { ACPAuthOptions, ACPClientApp } from './acp-auth';
+export type { ACPHarnessSettings } from './acp-harness';
+export type {
+  ACPAuthentication,
+  ACPLockedNpmImplementation,
+  ACPNpmImplementation,
+  ACPPermissionModeMapping,
+  ACPPermissionModeTarget,
+  ACPProfileValue,
+  ACPProviderAuthentication,
+  ACPProviderAuthenticationMode,
+  ACPSerializablePrimitive,
+  ACPSerializableValue,
+  ACPSimpleNpmImplementation,
+  ACPV1Settings,
+  ACPValueSource,
+} from './v1';
+export { VERSION } from './version';

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

@@ -0,0 +1,151 @@
+import {
+  harnessV1BridgeInboundCommandSchemas,
+  harnessV1BridgeOutboundMessageSchema,
+  harnessV1BridgeReadySchema,
+  harnessV1BridgeStartBaseSchema,
+  harnessV1BridgeToolWireSchema,
+  type HarnessV1BuiltinTool,
+  type HarnessV1DebugConfig,
+  type HarnessV1LifecycleState,
+  type HarnessV1PermissionMode,
+  type HarnessV1ToolSpec,
+} from '@ai-sdk/harness';
+import { z } from 'zod/v4';
+import type { ACPPermissionModeMapping } from './acp-v1-settings';
+import { acpTextContentBlockSchema } from './acp-v1-prompt';
+
+export type ACPBuiltinToolMapping = {
+  /**
+   * Key of the tool in `HarnessV1.builtinTools`, which is also emitted as the
+   * Harness V1 `toolName`. It is the common tool name when the tool has a
+   * standardized Harness V1 equivalent; otherwise it is the native tool name.
+   */
+  readonly toolName: string;
+
+  /**
+   * Name used by the underlying agent runtime. It is present when `toolName`
+   * is a Harness V1 common tool name that differs from the runtime's name.
+   */
+  readonly nativeName?: HarnessV1BuiltinTool['nativeName'];
+
+  /**
+   * JSON Schema used to identify tool calls when an ACP implementation does
+   * not provide a programmatic tool name. It is optional because built-in
+   * definitions are allowed to omit their input schema.
+   */
+  readonly inputSchema?: HarnessV1LifecycleState['data'];
+};
+
+const builtinToolSchema: z.ZodType<ACPBuiltinToolMapping> = z.object({
+  toolName: z.string(),
+  nativeName: z.string().optional(),
+  inputSchema: z.json().optional(),
+});
+
+type ACPSerializableToolSpec = Omit<HarnessV1ToolSpec, 'inputSchema'> & {
+  readonly inputSchema?: NonNullable<HarnessV1ToolSpec['inputSchema']> &
+    HarnessV1LifecycleState['data'];
+};
+
+const jsonValueSchema = z.json();
+
+export const acpSerializableToolSpecSchema: z.ZodType<ACPSerializableToolSpec> =
+  harnessV1BridgeToolWireSchema.extend({
+    inputSchema: z
+      .custom<NonNullable<ACPSerializableToolSpec['inputSchema']>>(
+        value =>
+          value != null &&
+          typeof value === 'object' &&
+          !Array.isArray(value) &&
+          jsonValueSchema.safeParse(value).success,
+      )
+      .optional(),
+  });
+
+const permissionModeTargetSchema = z.discriminatedUnion('type', [
+  z.object({
+    type: z.literal('session-mode'),
+    modeId: z.string(),
+  }),
+  z.object({
+    type: z.literal('session-config-option'),
+    configId: z.string(),
+    value: z.union([z.string(), z.boolean()]),
+  }),
+]);
+
+const permissionModeMappingSchema: z.ZodType<ACPPermissionModeMapping> =
+  z.object({
+    'allow-reads': permissionModeTargetSchema.nullable(),
+    'allow-edits': permissionModeTargetSchema.nullable(),
+    'allow-all': permissionModeTargetSchema.nullable(),
+  });
+
+export type ACPTurnStartConfig = {
+  readonly version: 1;
+  readonly configurationFingerprint: string;
+  readonly prompt: Array<z.infer<typeof acpTextContentBlockSchema>>;
+  readonly tools: Array<ACPSerializableToolSpec>;
+  readonly builtinTools: Array<ACPBuiltinToolMapping>;
+  readonly permissionMode: HarnessV1PermissionMode;
+  readonly permissionModeMapping?: ACPPermissionModeMapping;
+  readonly debug?: HarnessV1DebugConfig;
+};
+
+export const acpTurnStartConfigSchema = z.object({
+  version: z.literal(1),
+  configurationFingerprint: z.string(),
+  prompt: z.array(acpTextContentBlockSchema),
+  tools: z.array(acpSerializableToolSpecSchema).default([]),
+  builtinTools: z.array(builtinToolSchema).default([]),
+  permissionMode: harnessV1BridgeStartBaseSchema.shape.permissionMode.unwrap(),
+  permissionModeMapping: permissionModeMappingSchema.optional(),
+  debug: harnessV1BridgeStartBaseSchema.shape.debug.optional(),
+}) satisfies z.ZodType<ACPTurnStartConfig>;
+
+export type ACPColdSessionState = Omit<
+  ACPTurnStartConfig,
+  'prompt' | 'debug'
+> & {
+  readonly modelId?: string;
+};
+
+export const acpColdSessionStateSchema: z.ZodType<ACPColdSessionState> =
+  acpTurnStartConfigSchema.omit({ prompt: true, debug: true }).extend({
+    modelId: z.string().optional(),
+  });
+
+const lossyRecoverySchema = z.object({
+  type: z.literal('lossy-rerun'),
+  acpSessionId: z.string(),
+  reason: z.string(),
+});
+
+const coldRestoreSchema = z.object({
+  type: z.literal('cold-restore'),
+  acpSessionId: z.string(),
+});
+
+export const outboundMessageSchema = harnessV1BridgeOutboundMessageSchema;
+export type OutboundMessage = z.infer<typeof outboundMessageSchema>;
+
+export const startMessageSchema = harnessV1BridgeStartBaseSchema.extend({
+  prompt: z.array(acpTextContentBlockSchema),
+  tools: z.array(acpSerializableToolSpecSchema).optional(),
+  builtinTools: z.array(builtinToolSchema).readonly().default([]),
+  permissionModeMapping: permissionModeMappingSchema.optional(),
+  turnStartConfig: acpTurnStartConfigSchema,
+  recoveryMode: z
+    .discriminatedUnion('type', [lossyRecoverySchema, coldRestoreSchema])
+    .optional(),
+});
+export type StartMessage = z.infer<typeof startMessageSchema>;
+
+export const inboundMessageSchema = z.discriminatedUnion('type', [
+  startMessageSchema,
+  ...harnessV1BridgeInboundCommandSchemas,
+]);
+export type InboundMessage = z.infer<typeof inboundMessageSchema>;
+
+export const bridgeReadySchema = harnessV1BridgeReadySchema;
+export type BridgeReady = z.infer<typeof bridgeReadySchema>;