@ai-sdk/harness-cline 0.0.0 → 1.0.0

package/src/cline-skills.ts

@@ -0,0 +1,59 @@
+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';
+
+/**
+ * Materialize harness-provided skills into the sandbox HOME
+ * (`~/.agents/skills/<name>/SKILL.md` plus any auxiliary files) and return
+ * the root directory they were written to. The Cline runtime has no native
+ * skill loader, so the session surfaces them to the model through a system
+ * prompt section (see `renderSkillsPromptSection`) that points at these files.
+ */
+export async function writeClineSkills({
+  sandbox,
+  sandboxHomeDir,
+  skills,
+  abortSignal,
+}: {
+  sandbox: Experimental_SandboxSession;
+  sandboxHomeDir: string;
+  skills: ReadonlyArray<HarnessV1Skill>;
+  abortSignal?: AbortSignal;
+}): Promise<string | undefined> {
+  if (skills.length === 0) return undefined;
+  const skillRootDir = path.posix.join(sandboxHomeDir, '.agents', 'skills');
+  await writeSkills({
+    sandbox,
+    rootDir: skillRootDir,
+    skills,
+    ...(abortSignal ? { abortSignal } : {}),
+  });
+  return skillRootDir;
+}
+
+/**
+ * Render the system-prompt section that advertises available skills. Only the
+ * name + description sit in context; the model loads the full skill via the
+ * `read` tool when the task calls for it (progressive disclosure).
+ */
+export function renderSkillsPromptSection(
+  skills: ReadonlyArray<HarnessV1Skill>,
+  skillRootDir: string,
+): string {
+  const entries = skills
+    .map(
+      skill =>
+        `- ${skill.name}: ${skill.description}\n  SKILL.md: ${path.posix.join(
+          skillRootDir,
+          skill.name,
+          'SKILL.md',
+        )}`,
+    )
+    .join('\n');
+  return (
+    '## Skills\n\n' +
+    'The following skills are available. When a task matches a skill, read its SKILL.md with the `read` tool and follow its instructions.\n\n' +
+    entries
+  );
+}

package/src/cline-tools.ts

@@ -0,0 +1,381 @@
+import type {
+  HarnessV1BuiltinToolFiltering,
+  HarnessV1ToolSpec,
+} from '@ai-sdk/harness';
+import {
+  createTool,
+  type AgentTool,
+  type AgentToolResult,
+} from '@cline/agents';
+import type { ClineRemoteOps } from './cline-remote-ops';
+import { getErrorText } from './cline-utils';
+
+/**
+ * Native names of the Cline harness's built-in tools. The Cline runtime
+ * requires snake_case tool names, and every one of these already matches its
+ * cross-harness common name, so the public (wire) names and native names are
+ * identical.
+ */
+export const CLINE_NATIVE_BUILTIN_NAMES = [
+  'read',
+  'write',
+  'edit',
+  'bash',
+  'grep',
+  'glob',
+  'ls',
+] as const;
+
+export type ClineNativeBuiltinName =
+  (typeof CLINE_NATIVE_BUILTIN_NAMES)[number];
+
+export const CLINE_NATIVE_TOOL_KINDS: Readonly<
+  Record<ClineNativeBuiltinName, 'readonly' | 'edit' | 'bash'>
+> = {
+  read: 'readonly',
+  write: 'edit',
+  edit: 'edit',
+  bash: 'bash',
+  grep: 'readonly',
+  glob: 'readonly',
+  ls: 'readonly',
+};
+
+export function isClineBuiltinToolName(
+  name: string,
+): name is ClineNativeBuiltinName {
+  return (CLINE_NATIVE_BUILTIN_NAMES as readonly string[]).includes(name);
+}
+
+/**
+ * Resolve which built-in tools stay active for a session under the framework's
+ * `builtinToolFiltering`. Names map 1:1 (native === common), so filtering is a
+ * plain include/exclude.
+ */
+export function resolveActiveClineBuiltinNames(
+  toolFiltering: HarnessV1BuiltinToolFiltering | undefined,
+): ReadonlyArray<ClineNativeBuiltinName> {
+  if (toolFiltering == null) return CLINE_NATIVE_BUILTIN_NAMES;
+  if (toolFiltering.mode === 'allow') {
+    return CLINE_NATIVE_BUILTIN_NAMES.filter(name =>
+      toolFiltering.toolNames.includes(name),
+    );
+  }
+  return CLINE_NATIVE_BUILTIN_NAMES.filter(
+    name => !toolFiltering.toolNames.includes(name),
+  );
+}
+
+export interface PendingToolResult {
+  resolve: (value: unknown) => void;
+}
+
+const clineToolResultMarker = Symbol('cline-tool-result');
+
+interface ClineToolResult {
+  readonly [clineToolResultMarker]: true;
+  readonly output: unknown;
+  readonly isError?: boolean;
+}
+
+export function createClineToolResult({
+  output,
+  isError,
+}: {
+  output: unknown;
+  isError?: boolean;
+}): ClineToolResult {
+  return {
+    [clineToolResultMarker]: true,
+    output,
+    ...(isError ? { isError: true } : {}),
+  };
+}
+
+export function unwrapClineToolResult(
+  value: unknown,
+): AgentToolResult | undefined {
+  if (
+    value == null ||
+    typeof value !== 'object' ||
+    (value as ClineToolResult)[clineToolResultMarker] !== true
+  ) {
+    return undefined;
+  }
+
+  const result = value as ClineToolResult;
+  return {
+    output: result.output,
+    ...(result.isError ? { isError: true } : {}),
+  };
+}
+
+/*
+ * The Cline runtime treats a thrown tool error as a "mistake" against the
+ * agent's mistake limit, so built-ins catch and return errors as structured
+ * data — the model reads the error and adjusts.
+ */
+async function guarded<T>(run: () => Promise<T>): Promise<ClineToolResult> {
+  try {
+    return createClineToolResult({ output: await run() });
+  } catch (error) {
+    return createClineToolResult({
+      output: { error: getErrorText(error) },
+      isError: true,
+    });
+  }
+}
+
+/**
+ * Build the sandbox-backed built-in `AgentTool`s handed to the Cline runtime.
+ * These schemas mirror the zod declarations in `CLINE_BUILTIN_TOOLS`
+ * (cline-harness.ts) — keep the two in sync.
+ */
+export function buildBuiltinAgentTools({
+  ops,
+  activeNames,
+}: {
+  ops: ClineRemoteOps;
+  activeNames: ReadonlyArray<ClineNativeBuiltinName>;
+}): AgentTool<any, any>[] {
+  // biome/eslint: `any` matches the runtime's own `tools?: readonly AgentTool<any, any>[]`.
+  const tools: Partial<Record<ClineNativeBuiltinName, AgentTool<any, any>>> = {
+    read: createTool({
+      name: 'read',
+      description: 'Read file contents.',
+      inputSchema: {
+        type: 'object',
+        properties: {
+          file_path: {
+            type: 'string',
+            description: 'Path of the file to read.',
+          },
+        },
+        required: ['file_path'],
+      },
+      execute: async (input: { file_path: string }) =>
+        guarded(() => ops.readFile(input.file_path)),
+    }),
+    write: createTool({
+      name: 'write',
+      description: 'Overwrite or create a file.',
+      inputSchema: {
+        type: 'object',
+        properties: {
+          file_path: {
+            type: 'string',
+            description: 'Path of the file to write.',
+          },
+          content: {
+            type: 'string',
+            description: 'Full file content to write.',
+          },
+        },
+        required: ['file_path', 'content'],
+      },
+      execute: async (input: { file_path: string; content: string }) =>
+        guarded(async () => {
+          await ops.writeFile(input.file_path, input.content);
+          return `Wrote ${input.file_path}`;
+        }),
+    }),
+    edit: createTool({
+      name: 'edit',
+      description: 'Edit a file by exact string replacement.',
+      inputSchema: {
+        type: 'object',
+        properties: {
+          file_path: {
+            type: 'string',
+            description: 'Path of the file to edit.',
+          },
+          old_string: { type: 'string', description: 'Exact text to replace.' },
+          new_string: { type: 'string', description: 'Replacement text.' },
+        },
+        required: ['file_path', 'old_string', 'new_string'],
+      },
+      execute: async (input: {
+        file_path: string;
+        old_string: string;
+        new_string: string;
+      }) =>
+        guarded(async () => {
+          await ops.editFile(
+            input.file_path,
+            input.old_string,
+            input.new_string,
+          );
+          return `Edited ${input.file_path}`;
+        }),
+    }),
+    bash: createTool({
+      name: 'bash',
+      description:
+        'Execute a shell command in the sandbox workspace. Returns combined stdout/stderr and the exit code.',
+      inputSchema: {
+        type: 'object',
+        properties: {
+          command: { type: 'string', description: 'Shell command to execute.' },
+          timeout: {
+            type: 'number',
+            description: 'Optional timeout in seconds.',
+          },
+        },
+        required: ['command'],
+      },
+      execute: async (input: { command: string; timeout?: number }, context) =>
+        guarded(async () => {
+          const result = await ops.bash(input.command, {
+            ...(typeof input.timeout === 'number'
+              ? { timeout: input.timeout }
+              : {}),
+            ...(context.signal ? { signal: context.signal } : {}),
+          });
+          return `${result.output}${
+            result.exitCode != null ? `\n\n(exit ${result.exitCode})` : ''
+          }`.trim();
+        }),
+    }),
+    grep: createTool({
+      name: 'grep',
+      description: 'Search file contents with regex.',
+      inputSchema: {
+        type: 'object',
+        properties: {
+          pattern: {
+            type: 'string',
+            description: 'Regex pattern to search for.',
+          },
+          path: { type: 'string', description: 'File or directory to search.' },
+          glob: { type: 'string', description: 'Glob filter for file names.' },
+          ignoreCase: { type: 'boolean' },
+          literal: {
+            type: 'boolean',
+            description: 'Treat pattern as a literal string.',
+          },
+          context: {
+            type: 'number',
+            description: 'Lines of context around matches.',
+          },
+          limit: {
+            type: 'number',
+            description: 'Maximum matching lines to return.',
+          },
+        },
+        required: ['pattern'],
+      },
+      execute: async (input: {
+        pattern: string;
+        path?: string;
+        glob?: string;
+        ignoreCase?: boolean;
+        literal?: boolean;
+        context?: number;
+        limit?: number;
+      }) => guarded(() => ops.grep(input.pattern, input)),
+    }),
+    glob: createTool({
+      name: 'glob',
+      description: 'Find files matching a glob pattern.',
+      inputSchema: {
+        type: 'object',
+        properties: {
+          pattern: { type: 'string', description: 'Glob pattern to match.' },
+          path: { type: 'string', description: 'Directory to search from.' },
+          limit: { type: 'number', description: 'Maximum paths to return.' },
+        },
+        required: ['pattern'],
+      },
+      execute: async (input: {
+        pattern: string;
+        path?: string;
+        limit?: number;
+      }) =>
+        guarded(async () => {
+          const matches = await ops.glob(
+            input.pattern,
+            input.path ?? '.',
+            input.limit ?? 1_000,
+          );
+          return matches.length > 0 ? matches.join('\n') : 'No files found';
+        }),
+    }),
+    ls: createTool({
+      name: 'ls',
+      description: 'List directory entries.',
+      inputSchema: {
+        type: 'object',
+        properties: {
+          path: { type: 'string', description: 'Directory to list.' },
+          limit: { type: 'number', description: 'Maximum entries to return.' },
+        },
+      },
+      execute: async (input: { path?: string; limit?: number }) =>
+        guarded(async () => {
+          const entries = await ops.ls(input.path ?? '.', input.limit ?? 500);
+          return entries.join('\n');
+        }),
+    }),
+  };
+
+  return activeNames
+    .map(name => tools[name])
+    .filter((tool): tool is AgentTool<any, any> => tool != null);
+}
+
+/**
+ * Build host-executed user tools. When the model calls one, the tool parks a
+ * promise keyed by the runtime's `toolCallId`; the harness caller supplies the
+ * output via `submitToolResult`, which resolves the promise and lets the loop
+ * continue. The adapter never executes these itself.
+ */
+export function buildUserAgentTools({
+  specs,
+  pendingToolResults,
+}: {
+  specs: ReadonlyArray<HarnessV1ToolSpec>;
+  pendingToolResults: Map<string, PendingToolResult>;
+}): AgentTool<any, any>[] {
+  return specs.map(spec =>
+    createTool({
+      name: spec.name,
+      description: spec.description ?? `User-registered tool ${spec.name}`,
+      inputSchema: (spec.inputSchema as Record<string, unknown>) ?? {
+        type: 'object',
+        properties: {},
+        additionalProperties: true,
+      },
+      execute: async (_input: unknown, context) => {
+        const toolCallId = context.toolCallId;
+        if (!toolCallId) {
+          return createClineToolResult({
+            output: { error: 'Tool call is missing a toolCallId.' },
+            isError: true,
+          });
+        }
+        return new Promise<unknown>(resolve => {
+          pendingToolResults.set(toolCallId, { resolve });
+          // If the turn is aborted while waiting for the host, settle so the
+          // runtime's tool execution does not dangle forever.
+          context.signal?.addEventListener(
+            'abort',
+            () => {
+              if (pendingToolResults.delete(toolCallId)) {
+                resolve(
+                  createClineToolResult({
+                    output: {
+                      error:
+                        'Turn was aborted before a tool result was submitted.',
+                    },
+                    isError: true,
+                  }),
+                );
+              }
+            },
+            { once: true },
+          );
+        });
+      },
+    }),
+  );
+}

package/src/cline-translate.ts

@@ -0,0 +1,255 @@
+import type { HarnessV1StreamPart } from '@ai-sdk/harness';
+import type { AgentRuntimeEvent, AgentToolResult } from '@cline/agents';
+import {
+  mapModelFinishReason,
+  toToolResultValue,
+  usageFromMessageMetrics,
+} from './cline-utils';
+
+type FinishStepPart = Extract<
+  HarnessV1StreamPart,
+  { readonly type: 'finish-step' }
+>;
+
+/**
+ * Per-turn translator state. Tracks open text/reasoning blocks (the Cline
+ * runtime streams flat deltas; the harness contract wants explicit
+ * start/delta/end block framing) and which tool calls have already been
+ * surfaced — an approval request can emit a `tool-call` part before the
+ * runtime's own `tool-started` event fires for it. Cline emits the assistant
+ * message before executing that iteration's tools, so the step boundary is
+ * buffered until `turn-finished` confirms that those tools have settled.
+ */
+export interface ClineTranslatorState {
+  readonly builtinToolNames: ReadonlySet<string>;
+  readonly dynamicToolCallIds: Set<string>;
+  readonly hostToolNames: ReadonlySet<string>;
+  readonly mcpToolNames: ReadonlySet<string>;
+  openTextBlockId?: string;
+  openReasoningBlockId?: string;
+  emittedToolCalls: Set<string>;
+  pendingFinishStep?: FinishStepPart;
+  blockCounter: number;
+}
+
+export function createClineTranslatorState({
+  builtinToolNames,
+  hostToolNames = [],
+  mcpToolNames = [],
+}: {
+  builtinToolNames: Iterable<string>;
+  hostToolNames?: Iterable<string>;
+  mcpToolNames?: Iterable<string>;
+}): ClineTranslatorState {
+  return {
+    builtinToolNames: new Set(builtinToolNames),
+    dynamicToolCallIds: new Set(),
+    hostToolNames: new Set(hostToolNames),
+    mcpToolNames: new Set(mcpToolNames),
+    emittedToolCalls: new Set(),
+    blockCounter: 0,
+  };
+}
+
+function closeOpenBlocks(state: ClineTranslatorState): HarnessV1StreamPart[] {
+  const parts: HarnessV1StreamPart[] = [];
+  if (state.openReasoningBlockId) {
+    parts.push({ type: 'reasoning-end', id: state.openReasoningBlockId });
+    state.openReasoningBlockId = undefined;
+  }
+  if (state.openTextBlockId) {
+    parts.push({ type: 'text-end', id: state.openTextBlockId });
+    state.openTextBlockId = undefined;
+  }
+  return parts;
+}
+
+function toolCallPart(
+  state: ClineTranslatorState,
+  toolCall: { toolCallId: string; toolName: string; input: unknown },
+): HarnessV1StreamPart {
+  const isMcpTool =
+    state.mcpToolNames.has(toolCall.toolName) &&
+    !state.hostToolNames.has(toolCall.toolName);
+  if (isMcpTool) {
+    state.dynamicToolCallIds.add(toolCall.toolCallId);
+  }
+  return {
+    type: 'tool-call',
+    toolCallId: toolCall.toolCallId,
+    toolName: toolCall.toolName,
+    input: JSON.stringify(toolCall.input ?? {}),
+    /*
+     * Built-ins and external MCP tools are executed by the Cline runtime.
+     * Typed host tools wait for dispatch through `submitToolResult`, including
+     * when a host tool has the same name as a configured MCP tool.
+     */
+    ...(state.builtinToolNames.has(toolCall.toolName) || isMcpTool
+      ? { providerExecuted: true }
+      : {}),
+    ...(isMcpTool ? { dynamic: true } : {}),
+  };
+}
+
+/**
+ * Emit the `tool-call` + `tool-approval-request` pair for a built-in tool
+ * that requires approval. The Cline runtime asks for approval *before* its
+ * `tool-started` event fires, so the `tool-call` part is emitted here and
+ * deduplicated when `tool-started` arrives.
+ */
+export function toolApprovalParts(
+  state: ClineTranslatorState,
+  toolCall: { toolCallId: string; toolName: string; input: unknown },
+): HarnessV1StreamPart[] {
+  const parts: HarnessV1StreamPart[] = [];
+  if (!state.emittedToolCalls.has(toolCall.toolCallId)) {
+    state.emittedToolCalls.add(toolCall.toolCallId);
+    parts.push(toolCallPart(state, toolCall));
+  }
+  parts.push({
+    type: 'tool-approval-request',
+    approvalId: toolCall.toolCallId,
+    toolCallId: toolCall.toolCallId,
+  });
+  return parts;
+}
+
+/**
+ * Translate one Cline runtime event into zero or more harness stream parts.
+ * Terminal events (`run-finished`, `run-failed`) are intentionally not
+ * translated here — the session driver emits `finish`/`error` after the
+ * runtime's promise settles, so a suspend can close the stream cleanly.
+ */
+export function translateClineEvent(
+  event: AgentRuntimeEvent,
+  state: ClineTranslatorState,
+): HarnessV1StreamPart[] {
+  switch (event.type) {
+    case 'assistant-reasoning-delta': {
+      const parts: HarnessV1StreamPart[] = [];
+      if (state.openTextBlockId) {
+        parts.push({ type: 'text-end', id: state.openTextBlockId });
+        state.openTextBlockId = undefined;
+      }
+      if (!state.openReasoningBlockId) {
+        state.openReasoningBlockId = `reasoning-${++state.blockCounter}`;
+        parts.push({ type: 'reasoning-start', id: state.openReasoningBlockId });
+      }
+      parts.push({
+        type: 'reasoning-delta',
+        id: state.openReasoningBlockId,
+        delta: event.text,
+      });
+      return parts;
+    }
+
+    case 'assistant-text-delta': {
+      const parts: HarnessV1StreamPart[] = [];
+      if (state.openReasoningBlockId) {
+        parts.push({ type: 'reasoning-end', id: state.openReasoningBlockId });
+        state.openReasoningBlockId = undefined;
+      }
+      if (!state.openTextBlockId) {
+        state.openTextBlockId = `text-${++state.blockCounter}`;
+        parts.push({ type: 'text-start', id: state.openTextBlockId });
+      }
+      parts.push({
+        type: 'text-delta',
+        id: state.openTextBlockId,
+        delta: event.text,
+      });
+      return parts;
+    }
+
+    case 'assistant-message': {
+      const parts = closeOpenBlocks(state);
+      state.pendingFinishStep = {
+        type: 'finish-step',
+        finishReason: mapModelFinishReason(event.finishReason),
+        usage: usageFromMessageMetrics(event.message.metrics),
+      };
+      return parts;
+    }
+
+    case 'turn-finished': {
+      const pendingFinishStep = state.pendingFinishStep;
+      if (!pendingFinishStep) {
+        return [];
+      }
+      state.pendingFinishStep = undefined;
+      return [pendingFinishStep];
+    }
+
+    case 'tool-started': {
+      if (state.emittedToolCalls.has(event.toolCall.toolCallId)) {
+        return [];
+      }
+      state.emittedToolCalls.add(event.toolCall.toolCallId);
+      return [toolCallPart(state, event.toolCall)];
+    }
+
+    case 'tool-finished': {
+      // The tool message carries the runtime's recorded result for this call.
+      const resultPart = event.message.content.find(
+        (part): part is Extract<typeof part, { type: 'tool-result' }> =>
+          part.type === 'tool-result' &&
+          part.toolCallId === event.toolCall.toolCallId,
+      );
+      const output = resultPart?.output as AgentToolResult['output'] | unknown;
+      const dynamic = state.dynamicToolCallIds.delete(
+        event.toolCall.toolCallId,
+      );
+      return [
+        {
+          type: 'tool-result',
+          toolCallId: event.toolCall.toolCallId,
+          toolName: event.toolCall.toolName,
+          result: toToolResultValue(output),
+          ...(resultPart?.isError ? { isError: true } : {}),
+          ...(dynamic ? { dynamic: true } : {}),
+        },
+      ];
+    }
+
+    case 'tool-updated':
+      return [
+        {
+          type: 'raw',
+          rawValue: {
+            type: 'tool-updated',
+            toolCallId: event.toolCall.toolCallId,
+            toolName: event.toolCall.toolName,
+            update: event.update,
+          },
+        },
+      ];
+
+    case 'status-notice':
+      return [
+        {
+          type: 'raw',
+          rawValue: {
+            type: 'status-notice',
+            message: event.message,
+            ...(event.metadata ? { metadata: event.metadata } : {}),
+          },
+        },
+      ];
+
+    default:
+      return [];
+  }
+}
+
+/**
+ * Close any blocks still open when the turn ends (e.g. an aborted turn whose
+ * `assistant-message` never arrived). A buffered step that never reached
+ * Cline's `turn-finished` boundary is incomplete and must not be emitted.
+ */
+export function finishClineTranslation(
+  state: ClineTranslatorState,
+): HarnessV1StreamPart[] {
+  const parts = closeOpenBlocks(state);
+  state.pendingFinishStep = undefined;
+  return parts;
+}