@ai-sdk/harness-cline 0.0.0 → 1.0.0

package/src/cline-mcp.ts

@@ -0,0 +1,153 @@
+import type { AgentTool } from '@cline/agents';
+import type {
+  CreateMcpToolsOptions,
+  McpManager,
+  McpManagerOptions,
+  McpServerClientFactory,
+  McpServerRegistration,
+  McpServerTransportConfig,
+} from '@cline/core';
+
+const CLINE_CORE_PACKAGE: string = '@cline/core';
+
+type ClineCoreMcpModule = {
+  createDefaultMcpServerClientFactory(): McpServerClientFactory;
+  createMcpTools(options: CreateMcpToolsOptions): Promise<AgentTool[]>;
+  InMemoryMcpManager: new (options: McpManagerOptions) => McpManager;
+};
+
+export interface ClineMcpRuntime {
+  readonly tools: ReadonlyArray<AgentTool>;
+  readonly toolNames: ReadonlySet<string>;
+  dispose(): Promise<void>;
+}
+
+function isRecord(value: unknown): value is Record<string, unknown> {
+  return value != null && typeof value === 'object' && !Array.isArray(value);
+}
+
+function optionalStringArray(value: unknown): string[] | undefined {
+  return Array.isArray(value) && value.every(item => typeof item === 'string')
+    ? value
+    : undefined;
+}
+
+function optionalStringRecord(
+  value: unknown,
+): Record<string, string> | undefined {
+  return isRecord(value) &&
+    Object.values(value).every(item => typeof item === 'string')
+    ? (value as Record<string, string>)
+    : undefined;
+}
+
+function resolveTransport(input: {
+  serverName: string;
+  config: Record<string, unknown>;
+}): McpServerTransportConfig {
+  if (isRecord(input.config.transport)) {
+    return input.config.transport as unknown as McpServerTransportConfig;
+  }
+
+  if (typeof input.config.command === 'string') {
+    const args = optionalStringArray(input.config.args);
+    const env = optionalStringRecord(input.config.env);
+    return {
+      type: 'stdio',
+      command: input.config.command,
+      ...(args ? { args } : {}),
+      ...(typeof input.config.cwd === 'string'
+        ? { cwd: input.config.cwd }
+        : {}),
+      ...(env ? { env } : {}),
+    };
+  }
+
+  if (typeof input.config.url === 'string') {
+    const configuredType = input.config.type ?? input.config.transportType;
+    const headers = optionalStringRecord(input.config.headers);
+    return {
+      type:
+        configuredType === 'http' || configuredType === 'streamableHttp'
+          ? 'streamableHttp'
+          : 'sse',
+      url: input.config.url,
+      ...(headers ? { headers } : {}),
+    };
+  }
+
+  throw new Error(
+    `Cline MCP server ${JSON.stringify(input.serverName)} must define a transport, command, or URL.`,
+  );
+}
+
+function resolveRegistration(input: {
+  serverName: string;
+  config: unknown;
+}): McpServerRegistration {
+  if (!isRecord(input.config)) {
+    throw new Error(
+      `Cline MCP server ${JSON.stringify(input.serverName)} must be configured with an object value.`,
+    );
+  }
+
+  return {
+    name: input.serverName,
+    transport: resolveTransport({
+      serverName: input.serverName,
+      config: input.config,
+    }),
+    ...(typeof input.config.disabled === 'boolean'
+      ? { disabled: input.config.disabled }
+      : {}),
+    ...(isRecord(input.config.metadata)
+      ? { metadata: input.config.metadata }
+      : {}),
+    ...(isRecord(input.config.oauth) ? { oauth: input.config.oauth } : {}),
+  };
+}
+
+export async function createClineMcpRuntime(input: {
+  mcpServers: Record<string, unknown> | undefined;
+}): Promise<ClineMcpRuntime> {
+  if (input.mcpServers == null || Object.keys(input.mcpServers).length === 0) {
+    return {
+      tools: [],
+      toolNames: new Set(),
+      dispose: async () => {},
+    };
+  }
+
+  const {
+    createDefaultMcpServerClientFactory,
+    createMcpTools,
+    InMemoryMcpManager,
+  } = (await import(CLINE_CORE_PACKAGE)) as ClineCoreMcpModule;
+  const manager = new InMemoryMcpManager({
+    clientFactory: createDefaultMcpServerClientFactory(),
+  });
+  const tools: AgentTool[] = [];
+
+  try {
+    for (const [serverName, config] of Object.entries(input.mcpServers)) {
+      const registration = resolveRegistration({ serverName, config });
+      await manager.registerServer(registration);
+      if (registration.disabled) continue;
+      tools.push(
+        ...(await createMcpTools({
+          serverName,
+          provider: manager,
+        })),
+      );
+    }
+  } catch (error) {
+    await manager.dispose().catch(() => {});
+    throw error;
+  }
+
+  return {
+    tools,
+    toolNames: new Set(tools.map(tool => tool.name)),
+    dispose: async () => manager.dispose(),
+  };
+}

package/src/cline-remote-ops.ts

@@ -0,0 +1,243 @@
+import path from 'node:path';
+import { shellQuote } from '@ai-sdk/harness/utils';
+import type { Experimental_SandboxSession } from '@ai-sdk/provider-utils';
+
+/**
+ * Sandbox-backed implementations of the Cline harness's built-in tools.
+ *
+ * The Cline runtime executes on the host, but the workspace the model reasons
+ * about lives in the sandbox — every file/shell operation goes through the
+ * restricted `SandboxSession` surface. Relative paths resolve against the
+ * per-session working directory the framework created.
+ */
+export interface ClineRemoteOpsOptions {
+  readonly sandbox: Experimental_SandboxSession;
+  /** Absolute sandbox path of the session's working directory. */
+  readonly workDir: string;
+}
+
+export interface ClineRemoteOps {
+  resolvePath(inputPath: string): string;
+  readFile(inputPath: string): Promise<string>;
+  writeFile(inputPath: string, content: string): Promise<void>;
+  editFile(inputPath: string, oldText: string, newText: string): Promise<void>;
+  bash(
+    command: string,
+    input?: {
+      /** Timeout in seconds (the `bash` tool contract). */
+      timeout?: number;
+      signal?: AbortSignal;
+    },
+  ): Promise<{ output: string; exitCode: number }>;
+  grep(
+    pattern: string,
+    input?: {
+      path?: string;
+      glob?: string;
+      ignoreCase?: boolean;
+      literal?: boolean;
+      context?: number;
+      limit?: number;
+    },
+  ): Promise<string>;
+  glob(pattern: string, inputPath?: string, limit?: number): Promise<string[]>;
+  ls(inputPath?: string, limit?: number): Promise<string[]>;
+}
+
+export function createClineRemoteOps(
+  options: ClineRemoteOpsOptions,
+): ClineRemoteOps {
+  const { sandbox, workDir } = options;
+
+  const resolvePath = (inputPath: string): string => {
+    const normalized = path.posix.isAbsolute(inputPath)
+      ? path.posix.normalize(inputPath)
+      : path.posix.normalize(path.posix.join(workDir, inputPath));
+    return normalized;
+  };
+
+  const runShell = async (
+    command: string,
+    input?: { signal?: AbortSignal },
+  ): Promise<{ exitCode: number; output: string }> => {
+    // `sandbox.run({ command })` already wraps in a shell; interpolated
+    // paths/values inside `command` are quoted with `shellQuote` by callers.
+    const result = await sandbox.run({
+      command,
+      workingDirectory: workDir,
+      ...(input?.signal ? { abortSignal: input.signal } : {}),
+    });
+    return {
+      exitCode: result.exitCode,
+      output: `${result.stdout}${result.stderr}`,
+    };
+  };
+
+  const readFile = async (inputPath: string): Promise<string> => {
+    const resolved = resolvePath(inputPath);
+    const content = await sandbox.readTextFile({ path: resolved });
+    if (content == null) {
+      throw new Error(`File not found: ${inputPath}`);
+    }
+    return content;
+  };
+
+  const writeFile = async (
+    inputPath: string,
+    content: string,
+  ): Promise<void> => {
+    const resolved = resolvePath(inputPath);
+    // `writeTextFile` creates parent directories recursively per the
+    // SandboxSession contract, so no explicit mkdir is needed.
+    await sandbox.writeTextFile({ path: resolved, content });
+  };
+
+  const editFile = async (
+    inputPath: string,
+    oldText: string,
+    newText: string,
+  ): Promise<void> => {
+    const current = await readFile(inputPath);
+    const index = current.indexOf(oldText);
+    if (index === -1) {
+      throw new Error(`Text to replace was not found in ${inputPath}`);
+    }
+    const updated = `${current.slice(0, index)}${newText}${current.slice(
+      index + oldText.length,
+    )}`;
+    await writeFile(inputPath, updated);
+  };
+
+  return {
+    resolvePath,
+    readFile,
+    writeFile,
+    editFile,
+
+    async bash(command, input) {
+      const controller = new AbortController();
+      // `input.timeout` is expressed in seconds (the `bash` tool contract),
+      // so convert to milliseconds for `setTimeout`.
+      const timeoutId =
+        typeof input?.timeout === 'number' && input.timeout > 0
+          ? setTimeout(() => controller.abort(), input.timeout * 1000)
+          : undefined;
+
+      const forwardedSignal = input?.signal;
+      const onAbort = () => controller.abort();
+      forwardedSignal?.addEventListener('abort', onAbort, { once: true });
+
+      try {
+        const result = await runShell(command, { signal: controller.signal });
+        return { output: result.output, exitCode: result.exitCode };
+      } finally {
+        forwardedSignal?.removeEventListener('abort', onAbort);
+        if (timeoutId) {
+          clearTimeout(timeoutId);
+        }
+      }
+    },
+
+    async grep(pattern, input = {}) {
+      const target = resolvePath(input.path ?? '.');
+      const flags = [
+        '-R',
+        '-n',
+        '--binary-files=without-match',
+        ...(input.ignoreCase ? ['-i'] : []),
+        ...(input.literal ? ['-F'] : []),
+        ...(typeof input.context === 'number' && input.context > 0
+          ? ['-C', String(input.context)]
+          : []),
+        ...(input.glob ? ['--include', input.glob] : []),
+      ];
+      const limit = Math.max(1, input.limit ?? 100);
+      const result = await runShell(
+        [
+          `if [ ! -e ${shellQuote(
+            target,
+          )} ]; then echo "__CLINE_GREP_NOT_FOUND__"; exit 2; fi`,
+          `grep ${flags.map(shellQuote).join(' ')} -- ${shellQuote(
+            pattern,
+          )} ${shellQuote(target)} 2>/dev/null | head -n ${limit}`,
+        ].join('; '),
+      );
+
+      const output = result.output.trim();
+      if (output.includes('__CLINE_GREP_NOT_FOUND__')) {
+        throw new Error(`Path not found: ${input.path ?? '.'}`);
+      }
+      return output || 'No matches found';
+    },
+
+    async glob(pattern, inputPath = '.', limit = 1_000) {
+      const target = resolvePath(inputPath);
+      const result = await runShell(
+        [
+          `if [ ! -e ${shellQuote(
+            target,
+          )} ]; then echo "__CLINE_FIND_NOT_FOUND__"; exit 2; fi`,
+          `if [ -d ${shellQuote(target)} ]; then find ${shellQuote(
+            target,
+          )} -type f -print; else printf '%s\\n' ${shellQuote(target)}; fi`,
+        ].join('; '),
+      );
+
+      const output = result.output.trim();
+      if (output.includes('__CLINE_FIND_NOT_FOUND__')) {
+        throw new Error(`Path not found: ${inputPath}`);
+      }
+
+      return output
+        .split('\n')
+        .filter(Boolean)
+        .map(absolutePath => {
+          if (absolutePath === target) {
+            return path.posix.basename(absolutePath);
+          }
+          return path.posix.relative(target, absolutePath);
+        })
+        .filter(
+          candidate =>
+            candidate.length > 0 && path.matchesGlob(candidate, pattern),
+        )
+        .sort((left, right) =>
+          left.toLowerCase().localeCompare(right.toLowerCase()),
+        )
+        .slice(0, limit);
+    },
+
+    async ls(inputPath = '.', limit = 500) {
+      const target = resolvePath(inputPath);
+      const result = await runShell(
+        [
+          `if [ ! -e ${shellQuote(
+            target,
+          )} ]; then echo "__CLINE_LS_NOT_FOUND__"; exit 2; fi`,
+          `if [ ! -d ${shellQuote(
+            target,
+          )} ]; then echo "__CLINE_LS_NOT_DIR__"; exit 3; fi`,
+          `cd ${shellQuote(target)}`,
+          'ls -1Ap',
+        ].join('; '),
+      );
+
+      const output = result.output.trim();
+      if (output.includes('__CLINE_LS_NOT_FOUND__')) {
+        throw new Error(`Path not found: ${inputPath}`);
+      }
+      if (output.includes('__CLINE_LS_NOT_DIR__')) {
+        throw new Error(`Not a directory: ${inputPath}`);
+      }
+
+      return output
+        .split('\n')
+        .filter(Boolean)
+        .map(line => line.replace(/[*=@|]$/, ''))
+        .sort((left, right) =>
+          left.toLowerCase().localeCompare(right.toLowerCase()),
+        )
+        .slice(0, limit);
+    },
+  };
+}

package/src/cline-resume-state.ts

@@ -0,0 +1,139 @@
+import { createHash } from 'node:crypto';
+import path from 'node:path';
+import {
+  safeParseJSON,
+  type Experimental_SandboxSession,
+} from '@ai-sdk/provider-utils';
+import type { AgentMessage } from '@cline/agents';
+import { z } from 'zod/v4';
+
+const CLINE_HISTORY_FILE_NAME_PATTERN = /^[A-Za-z0-9][A-Za-z0-9._-]*\.json$/;
+
+export function safeClineHistoryFileName(historyFileName: string): string {
+  if (!CLINE_HISTORY_FILE_NAME_PATTERN.test(historyFileName)) {
+    throw new Error(`Invalid Cline history file name: ${historyFileName}`);
+  }
+  return historyFileName;
+}
+
+const clineHistoryFileNameSchema = z
+  .string()
+  .refine(
+    historyFileName => CLINE_HISTORY_FILE_NAME_PATTERN.test(historyFileName),
+    'Cline historyFileName must be a safe .json basename.',
+  );
+
+/**
+ * Schema for the adapter-specific portion of lifecycle state `data` produced
+ * by the Cline harness's resumable lifecycle methods. Carries the basename of
+ * the serialized conversation history. The actual history bytes live in a
+ * private, session-scoped directory under sandbox HOME so they survive
+ * cross-process resume without appearing in the agent workspace.
+ */
+export const clineResumeStateSchema = z.looseObject({
+  historyFileName: clineHistoryFileNameSchema.optional(),
+});
+
+export type ClineResumeStateData = z.infer<typeof clineResumeStateSchema>;
+
+export const CLINE_DEFAULT_HISTORY_FILE_NAME = 'history.json';
+
+export function resolveClinePrivateSessionDirectory(input: {
+  readonly sandboxHomeDir: string;
+  readonly sessionWorkDir: string;
+  readonly sessionId: string;
+}): string {
+  const sessionKey = createHash('sha256').update(input.sessionId).digest('hex');
+  const privateSessionDir = path.posix.join(
+    input.sandboxHomeDir,
+    '.ai-sdk',
+    'harness-cline',
+    sessionKey,
+  );
+  const relativePath = path.posix.relative(
+    input.sessionWorkDir,
+    privateSessionDir,
+  );
+  if (
+    relativePath === '' ||
+    (!relativePath.startsWith('../') && !path.posix.isAbsolute(relativePath))
+  ) {
+    throw new Error(
+      `Cline private session directory ${JSON.stringify(privateSessionDir)} must be outside sessionWorkDir ${JSON.stringify(input.sessionWorkDir)}.`,
+    );
+  }
+  return privateSessionDir;
+}
+
+function resolveContainedSandboxPath(input: {
+  readonly privateSessionDir: string;
+  readonly historyFileName: string;
+}): string {
+  const historyDir = path.posix.resolve(input.privateSessionDir);
+  const filePath = path.posix.resolve(
+    historyDir,
+    safeClineHistoryFileName(input.historyFileName),
+  );
+  const relativePath = path.posix.relative(historyDir, filePath);
+  if (
+    relativePath === '' ||
+    relativePath.startsWith('..') ||
+    path.posix.isAbsolute(relativePath)
+  ) {
+    throw new Error(
+      `Invalid Cline history file name: ${input.historyFileName}`,
+    );
+  }
+  return filePath;
+}
+
+/**
+ * Persist the runtime's conversation history into private sandbox state so a
+ * future process can resume the session after
+ * `HarnessV1SandboxProvider.resume?.({ sessionId })` reattaches the sandbox.
+ */
+export async function persistHistoryToSandbox(args: {
+  readonly sandbox: Experimental_SandboxSession;
+  readonly privateSessionDir: string;
+  readonly historyFileName: string;
+  readonly messages: readonly AgentMessage[];
+  readonly abortSignal?: AbortSignal;
+}): Promise<void> {
+  const remotePath = resolveContainedSandboxPath({
+    privateSessionDir: args.privateSessionDir,
+    historyFileName: args.historyFileName,
+  });
+  // `writeTextFile` creates parent directories recursively per the
+  // SandboxSession contract.
+  await args.sandbox.writeTextFile({
+    path: remotePath,
+    content: JSON.stringify(args.messages),
+    ...(args.abortSignal ? { abortSignal: args.abortSignal } : {}),
+  });
+}
+
+/**
+ * Pull a previously persisted conversation history from the sandbox. Returns
+ * `undefined` when the file is missing or unparsable — resume then falls back
+ * to a fresh conversation rather than failing `doStart`.
+ */
+export async function pullHistoryFromSandbox(args: {
+  readonly sandbox: Experimental_SandboxSession;
+  readonly privateSessionDir: string;
+  readonly historyFileName: string;
+  readonly abortSignal?: AbortSignal;
+}): Promise<AgentMessage[] | undefined> {
+  const remotePath = resolveContainedSandboxPath({
+    privateSessionDir: args.privateSessionDir,
+    historyFileName: args.historyFileName,
+  });
+  const content = await args.sandbox.readTextFile({
+    path: remotePath,
+    ...(args.abortSignal ? { abortSignal: args.abortSignal } : {}),
+  });
+  if (content == null) return undefined;
+  const parsed = await safeParseJSON({ text: content });
+  return parsed.success && Array.isArray(parsed.value)
+    ? (parsed.value as unknown as AgentMessage[])
+    : undefined;
+}