@ai-sdk/harness-acp 0.0.0 → 1.0.1

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

@@ -0,0 +1,115 @@
+import type { ACPAuthenticationProfileIdentity } from '../acp-auth';
+import type {
+  ACPColdSessionState,
+  ACPTurnStartConfig,
+} from './acp-v1-bridge-protocol';
+
+export type ACPPromptGuidanceLifecycleState = {
+  readonly initialGuidanceApplied?: boolean;
+  readonly skillsMaterialized?: boolean;
+  readonly skillsFingerprint?: string;
+};
+
+export type ACPBridgeCoordinates = {
+  readonly port: number;
+  readonly token: string;
+  readonly lastSeenEventId: number;
+  readonly sandboxId?: string;
+  readonly stateDir?: string;
+};
+
+export type ACPLifecycleData = ACPPromptGuidanceLifecycleState & {
+  readonly implementationIdentity: string;
+  readonly authenticationProfile?: ACPAuthenticationProfileIdentity;
+  readonly acpSessionId?: string;
+  readonly bridge?: ACPBridgeCoordinates;
+  readonly coldSession?: ACPColdSessionState;
+  readonly turnStartConfig?: ACPTurnStartConfig;
+  readonly recovery?: {
+    readonly mode: 'disk-replay' | 'lossy-rerun';
+    readonly reason: string;
+  };
+  readonly restoration?: {
+    readonly method: 'resume' | 'load';
+  };
+};
+
+export function resolveACPInitialGuidanceApplied({
+  isResume,
+  lifecycleState,
+}: {
+  isResume: boolean;
+  lifecycleState: ACPPromptGuidanceLifecycleState | undefined;
+}): boolean {
+  if (!isResume) return false;
+  return lifecycleState?.initialGuidanceApplied ?? true;
+}
+
+export function shouldMaterializeACPSkills({
+  isResume,
+  lifecycleState,
+  skillsFingerprint,
+}: {
+  isResume: boolean;
+  lifecycleState: ACPPromptGuidanceLifecycleState | undefined;
+  skillsFingerprint: string;
+}): boolean {
+  if (
+    isResume &&
+    lifecycleState?.skillsFingerprint != null &&
+    lifecycleState.skillsFingerprint !== skillsFingerprint
+  ) {
+    throw new Error(
+      'ACP lifecycle state was created with a different set of skills.',
+    );
+  }
+  return !isResume || lifecycleState?.skillsMaterialized !== true;
+}
+
+export function validateACPLifecycleCompatibility({
+  harnessId,
+  lifecycleHarnessId,
+  implementationIdentity,
+  authenticationProfile,
+  lifecycleData,
+  sandboxId,
+}: {
+  harnessId: string;
+  lifecycleHarnessId: string;
+  implementationIdentity: string;
+  authenticationProfile: ACPAuthenticationProfileIdentity;
+  lifecycleData: ACPLifecycleData;
+  sandboxId: string | undefined;
+}): void {
+  if (lifecycleHarnessId !== harnessId) {
+    throw new Error(
+      `ACP lifecycle state was produced by harness ${JSON.stringify(
+        lifecycleHarnessId,
+      )}, but this harness is ${JSON.stringify(harnessId)}.`,
+    );
+  }
+  if (lifecycleData.implementationIdentity !== implementationIdentity) {
+    throw new Error(
+      'ACP lifecycle state is incompatible with the configured implementation.',
+    );
+  }
+  if (
+    lifecycleData.authenticationProfile?.digest !== authenticationProfile.digest
+  ) {
+    throw new Error(
+      'ACP lifecycle state is incompatible with the configured authentication profile.',
+    );
+  }
+  const expectedSandboxId = lifecycleData.bridge?.sandboxId;
+  if (
+    expectedSandboxId != null &&
+    sandboxId != null &&
+    expectedSandboxId !== sandboxId
+  ) {
+    throw new Error(
+      `ACP lifecycle state belongs to sandbox ${JSON.stringify(
+        expectedSandboxId,
+      )}, not ${JSON.stringify(sandboxId)}.`,
+    );
+  }
+}

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

@@ -0,0 +1,122 @@
+import {
+  HarnessCapabilityUnsupportedError,
+  type HarnessV1Prompt,
+} from '@ai-sdk/harness';
+import { z } from 'zod/v4';
+
+export const acpTextContentBlockSchema = z.object({
+  type: z.literal('text'),
+  text: z.string(),
+});
+
+export type ACPTextContentBlock = z.infer<typeof acpTextContentBlockSchema>;
+
+export type ACPSkillCatalogEntry = {
+  readonly name: string;
+  readonly description: string;
+  readonly path: string;
+};
+
+export function convertHarnessPromptToACPTextBlocks({
+  prompt,
+  harnessId,
+}: {
+  prompt: HarnessV1Prompt;
+  harnessId: string;
+}): ACPTextContentBlock[] {
+  if (typeof prompt === 'string') {
+    return [{ type: 'text', text: prompt }];
+  }
+  if (typeof prompt.content === 'string') {
+    return [{ type: 'text', text: prompt.content }];
+  }
+
+  const content: ACPTextContentBlock[] = [];
+  for (const part of prompt.content) {
+    if (part.type === 'text') {
+      content.push({ type: 'text', text: part.text });
+      continue;
+    }
+    if (part.type === 'image') {
+      throw unsupportedPromptContent({
+        harnessId,
+        category: 'image content',
+      });
+    }
+    if (part.type === 'file') {
+      const mediaCategory = part.mediaType.toLowerCase().split('/', 1)[0];
+      if (mediaCategory === 'image') {
+        throw unsupportedPromptContent({
+          harnessId,
+          category: 'image content',
+        });
+      }
+      if (mediaCategory === 'audio') {
+        throw unsupportedPromptContent({
+          harnessId,
+          category: 'audio content',
+        });
+      }
+      throw unsupportedPromptContent({
+        harnessId,
+        category: `embedded resource content with media type ${JSON.stringify(part.mediaType)}`,
+      });
+    }
+    throw unsupportedPromptContent({
+      harnessId,
+      category: `content parts of type ${JSON.stringify(
+        (part as { readonly type?: unknown }).type,
+      )}`,
+    });
+  }
+  return content;
+}
+
+export function prependACPInitialGuidance({
+  prompt,
+  instructions,
+  skills,
+}: {
+  prompt: ReadonlyArray<ACPTextContentBlock>;
+  instructions: string | undefined;
+  skills: ReadonlyArray<ACPSkillCatalogEntry>;
+}): ACPTextContentBlock[] {
+  const hasInstructions = instructions != null && instructions.length > 0;
+  if (!hasInstructions && skills.length === 0) return [...prompt];
+
+  const lines = [
+    '<session-guidance>',
+    'This block is operating guidance from the harness, not user-authored content.',
+  ];
+  if (hasInstructions) {
+    lines.push('<instructions>', instructions, '</instructions>');
+  }
+  if (skills.length > 0) {
+    lines.push(
+      '<available-skills>',
+      'Load a skill only when relevant by reading its SKILL.md file at the listed absolute path.',
+    );
+    for (const skill of skills) {
+      lines.push(`- ${skill.name}: ${skill.description} (${skill.path})`);
+    }
+    lines.push('</available-skills>');
+  }
+  lines.push('</session-guidance>');
+
+  return [{ type: 'text', text: lines.join('\n') }, ...prompt];
+}
+
+function unsupportedPromptContent({
+  harnessId,
+  category,
+}: {
+  harnessId: string;
+  category: string;
+}): HarnessCapabilityUnsupportedError {
+  return new HarnessCapabilityUnsupportedError({
+    harnessId,
+    message:
+      `The ${harnessId} ACP harness supports only portable text prompts and does not support ${category}. ` +
+      'Pass a string or a user message whose content contains only text parts.',
+  });
+}

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

@@ -0,0 +1,97 @@
+import type { HarnessV1PermissionMode } from '@ai-sdk/harness';
+
+export type ACPSerializablePrimitive = string | number | boolean | null;
+
+export type ACPSerializableValue =
+  | ACPSerializablePrimitive
+  | ReadonlyArray<ACPSerializableValue>
+  | { readonly [key: string]: ACPSerializableValue };
+
+export type ACPValueSource = {
+  readonly $source:
+    | 'gateway-api-key'
+    | 'gateway-base-url'
+    | 'gateway-authorization'
+    | 'client-app'
+    | 'client-app-name'
+    | 'client-app-version';
+  readonly prefix?: string;
+  readonly suffix?: string;
+  readonly ensureSuffix?: string;
+};
+
+export type ACPProfileValue =
+  | ACPSerializablePrimitive
+  | ACPValueSource
+  | ReadonlyArray<ACPProfileValue>
+  | { readonly [key: string]: ACPProfileValue };
+
+export type ACPNpmSimpleSource = {
+  readonly type: 'npm-simple';
+  readonly packageName: string;
+  /**
+   * Exact version to install. When omitted, the package's `latest` dist-tag is
+   * installed and no version takes part in the implementation identity, so a
+   * new upstream release does not invalidate existing lifecycle state.
+   */
+  readonly packageVersion?: string;
+};
+
+export type ACPNpmLockedSource = {
+  readonly type: 'npm-locked';
+  readonly packageJson: string;
+  readonly pnpmLockYaml: string;
+};
+
+export type ACPSource = ACPNpmSimpleSource | ACPNpmLockedSource;
+
+export type ACPAuthentication = {
+  readonly methodId: string;
+  readonly meta?: Readonly<Record<string, ACPSerializableValue>>;
+  readonly clientCapabilities?: Readonly<Record<string, ACPSerializableValue>>;
+};
+
+export type ACPProviderAuthenticationMode = 'auto' | 'direct' | 'ai-gateway';
+
+export type ACPProviderAuthentication = {
+  readonly gateway: {
+    readonly env: Readonly<Record<string, ACPProfileValue>>;
+  };
+};
+
+export type ACPPermissionModeTarget =
+  | {
+      readonly type: 'session-mode';
+      readonly modeId: string;
+    }
+  | {
+      readonly type: 'session-config-option';
+      readonly configId: string;
+      readonly value: string | boolean;
+    };
+
+export type ACPPermissionModeMapping = Readonly<
+  Record<HarnessV1PermissionMode, ACPPermissionModeTarget | null>
+>;
+
+export type ACPV1Settings = {
+  readonly version?: 'v1';
+  readonly harnessId: string;
+  readonly auth?: ACPProviderAuthenticationMode;
+  readonly source: ACPSource;
+  readonly executable: string;
+  readonly args?: ReadonlyArray<string>;
+  readonly forwardEnv?: ReadonlyArray<string>;
+  /**
+   * Runtime environment values that are safe to persist in bootstrap and
+   * lifecycle compatibility identity.
+   */
+  readonly env?: Readonly<Record<string, string>>;
+  readonly authentication?: ACPAuthentication;
+  readonly providerAuthentication?: ACPProviderAuthentication;
+  readonly modelId?: string;
+  readonly permissionModeMapping?: ACPPermissionModeMapping;
+  readonly session?: {
+    readonly meta?: Readonly<Record<string, ACPSerializableValue>>;
+  };
+};

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

@@ -0,0 +1,228 @@
+import { createHash } from 'node:crypto';
+import path from 'node:path';
+import type { HarnessV1Skill } from '@ai-sdk/harness';
+import { writeSkills } from '@ai-sdk/harness/utils';
+import type { Experimental_SandboxSession } from '@ai-sdk/provider-utils';
+import type { ACPSkillCatalogEntry } from './acp-v1-prompt';
+
+const ACP_SKILL_NAME_PATTERN = /^[a-z0-9]+(?:-[a-z0-9]+)*$/;
+
+export function createACPSkillsFingerprint({
+  skills,
+}: {
+  skills: ReadonlyArray<HarnessV1Skill>;
+}): string {
+  const canonicalSkills = skills
+    .map(skill => ({
+      name: skill.name,
+      description: skill.description,
+      content: skill.content,
+      files: [...(skill.files ?? [])]
+        .map(file => ({
+          path: path.posix.normalize(file.path),
+          content: file.content,
+        }))
+        .sort((left, right) =>
+          compareCanonicalStrings({ left: left.path, right: right.path }),
+        ),
+    }))
+    .sort((left, right) =>
+      compareCanonicalStrings({ left: left.name, right: right.name }),
+    );
+  return createHash('sha256')
+    .update(JSON.stringify(canonicalSkills))
+    .digest('hex');
+}
+
+export function resolveACPPrivateSessionDirectory({
+  sandboxHomeDir,
+  sessionWorkDir,
+  harnessId,
+  sessionId,
+}: {
+  sandboxHomeDir: string;
+  sessionWorkDir: string;
+  harnessId: string;
+  sessionId: string;
+}): string {
+  const sessionKey = createHash('sha256').update(sessionId).digest('hex');
+  const rootDir = path.posix.join(
+    sandboxHomeDir,
+    '.ai-sdk',
+    'harness-acp',
+    harnessId,
+    sessionKey,
+  );
+  assertOutsideSessionWorkDir({ rootDir, sessionWorkDir });
+  return rootDir;
+}
+
+export async function materializeACPSkills({
+  sandbox,
+  sandboxHomeDir,
+  sessionWorkDir,
+  harnessId,
+  sessionId,
+  skills,
+  shouldMaterialize,
+  abortSignal,
+}: {
+  sandbox: Experimental_SandboxSession;
+  sandboxHomeDir: string;
+  sessionWorkDir: string;
+  harnessId: string;
+  sessionId: string;
+  skills: ReadonlyArray<HarnessV1Skill>;
+  shouldMaterialize: boolean;
+  abortSignal?: AbortSignal;
+}): Promise<{
+  readonly catalog: ReadonlyArray<ACPSkillCatalogEntry>;
+  readonly rootDir: string;
+}> {
+  validateACPSkills({ skills });
+
+  const rootDir = path.posix.join(
+    resolveACPPrivateSessionDirectory({
+      sandboxHomeDir,
+      sessionWorkDir,
+      harnessId,
+      sessionId,
+    }),
+    'skills',
+  );
+
+  if (shouldMaterialize) {
+    await 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.`,
+    });
+  }
+
+  return {
+    rootDir,
+    catalog: skills.map(skill => ({
+      name: skill.name,
+      description: skill.description,
+      path: path.posix.join(rootDir, skill.name, 'SKILL.md'),
+    })),
+  };
+}
+
+function validateACPSkills({
+  skills,
+}: {
+  skills: ReadonlyArray<HarnessV1Skill>;
+}): void {
+  const skillNames = new Set<string>();
+  for (const skill of skills) {
+    if (
+      !ACP_SKILL_NAME_PATTERN.test(skill.name) ||
+      skill.name === '.' ||
+      skill.name === '..'
+    ) {
+      throw new Error(
+        `Invalid ACP skill name ${JSON.stringify(skill.name)}: expected a kebab-case slug.`,
+      );
+    }
+    if (skillNames.has(skill.name)) {
+      throw new Error(
+        `Duplicate ACP skill name ${JSON.stringify(skill.name)}.`,
+      );
+    }
+    skillNames.add(skill.name);
+
+    const filePaths = new Set<string>();
+    for (const file of skill.files ?? []) {
+      const normalizedPath = validateACPAttachedFilePath({
+        skillName: skill.name,
+        filePath: file.path,
+      });
+      if (normalizedPath === 'SKILL.md') {
+        throw new Error(
+          `Invalid ACP skill file path ${JSON.stringify(file.path)} for skill ${JSON.stringify(
+            skill.name,
+          )}: SKILL.md is reserved for the skill definition.`,
+        );
+      }
+      if (filePaths.has(normalizedPath)) {
+        throw new Error(
+          `Duplicate ACP skill file path ${JSON.stringify(file.path)} for skill ${JSON.stringify(
+            skill.name,
+          )}.`,
+        );
+      }
+      filePaths.add(normalizedPath);
+    }
+  }
+}
+
+function validateACPAttachedFilePath({
+  skillName,
+  filePath,
+}: {
+  skillName: string;
+  filePath: string;
+}): string {
+  const containsTraversal = filePath
+    .split(/[\\/]/)
+    .some(segment => segment === '..');
+  const normalizedPath = path.posix.normalize(filePath);
+  const invalid =
+    filePath.length === 0 ||
+    filePath.endsWith('/') ||
+    filePath.includes('\\') ||
+    path.posix.isAbsolute(filePath) ||
+    path.win32.isAbsolute(filePath) ||
+    containsTraversal ||
+    normalizedPath === '.' ||
+    normalizedPath.startsWith('../') ||
+    normalizedPath.includes('/../') ||
+    normalizedPath.endsWith('/..');
+  if (invalid) {
+    throw new Error(
+      `Invalid ACP skill file path ${JSON.stringify(filePath)} for skill ${JSON.stringify(
+        skillName,
+      )}: expected a relative POSIX path without traversal.`,
+    );
+  }
+  return normalizedPath;
+}
+
+function assertOutsideSessionWorkDir({
+  rootDir,
+  sessionWorkDir,
+}: {
+  rootDir: string;
+  sessionWorkDir: string;
+}): void {
+  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,
+      )}.`,
+    );
+  }
+}
+
+function compareCanonicalStrings({
+  left,
+  right,
+}: {
+  left: string;
+  right: string;
+}): number {
+  return left < right ? -1 : left > right ? 1 : 0;
+}

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

@@ -0,0 +1,93 @@
+import { createHash } from 'node:crypto';
+import type { HarnessV1DebugConfig, HarnessV1ToolSpec } from '@ai-sdk/harness';
+import type { ACPAuthenticationProfileIdentity } from '../acp-auth';
+import {
+  acpSerializableToolSpecSchema,
+  type ACPBuiltinToolMapping,
+  type ACPColdSessionState,
+  type ACPTurnStartConfig,
+  type StartMessage,
+} from './acp-v1-bridge-protocol';
+import type { ACPTextContentBlock } from './acp-v1-prompt';
+import type {
+  ACPPermissionModeMapping,
+  ACPSerializableValue,
+} from './acp-v1-settings';
+
+export function createACPTurnStartConfig({
+  prompt,
+  tools,
+  builtinTools,
+  permissionMode,
+  permissionModeMapping,
+  debug,
+  authenticationProfile,
+  sessionMeta,
+}: {
+  prompt: ReadonlyArray<ACPTextContentBlock>;
+  tools: ReadonlyArray<HarnessV1ToolSpec>;
+  builtinTools: ReadonlyArray<ACPBuiltinToolMapping>;
+  permissionMode: NonNullable<StartMessage['permissionMode']>;
+  permissionModeMapping: ACPPermissionModeMapping | undefined;
+  debug: HarnessV1DebugConfig | undefined;
+  authenticationProfile: ACPAuthenticationProfileIdentity;
+  sessionMeta: Readonly<Record<string, ACPSerializableValue>> | undefined;
+}): ACPTurnStartConfig {
+  return {
+    version: 1,
+    configurationFingerprint: createHash('sha256')
+      .update(
+        stableStringify({
+          authenticationProfile,
+          sessionMeta: sessionMeta ?? null,
+          builtinTools,
+          permissionModeMapping: permissionModeMapping ?? null,
+        }),
+      )
+      .digest('hex'),
+    prompt: [...prompt],
+    tools: tools.map(tool => acpSerializableToolSpecSchema.parse(tool)),
+    builtinTools: [...builtinTools],
+    permissionMode,
+    ...(permissionModeMapping == null ? {} : { permissionModeMapping }),
+    ...(debug == null ? {} : { debug }),
+  };
+}
+
+export function createACPColdSessionState({
+  turnStartConfig,
+  modelId,
+}: {
+  turnStartConfig: ACPTurnStartConfig;
+  modelId: string | undefined;
+}): ACPColdSessionState {
+  return {
+    version: turnStartConfig.version,
+    configurationFingerprint: turnStartConfig.configurationFingerprint,
+    tools: turnStartConfig.tools,
+    builtinTools: turnStartConfig.builtinTools,
+    permissionMode: turnStartConfig.permissionMode,
+    ...(turnStartConfig.permissionModeMapping == null
+      ? {}
+      : { permissionModeMapping: turnStartConfig.permissionModeMapping }),
+    ...(modelId == null ? {} : { modelId }),
+  };
+}
+
+function stableStringify(value: unknown): string {
+  return JSON.stringify(sortValue(value));
+}
+
+function sortValue(value: unknown): unknown {
+  if (Array.isArray(value)) {
+    return value.map(item => sortValue(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, sortValue(entry)]),
+    );
+  }
+  return value;
+}