@ai-sdk/harness-cline 1.0.19 → 1.0.20

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ai-sdk/harness-cline",
-  "version": "1.0.19",
+  "version": "1.0.20",
   "type": "module",
   "license": "Apache-2.0",
   "sideEffects": false,
@@ -26,11 +26,11 @@
     }
   },
   "dependencies": {
-    "@ai-sdk/harness": "1.0.92",
+    "@ai-sdk/harness": "1.0.93",
     "@ai-sdk/provider": "4.0.8",
-    "@ai-sdk/provider-utils": "5.0.32",
-    "@cline/agents": "^0.0.72",
-    "@cline/core": "^0.0.72"
+    "@ai-sdk/provider-utils": "5.0.33",
+    "@cline/agents": "^0.0.79",
+    "@cline/core": "^0.0.79"
   },
   "peerDependencies": {
     "zod": "^3.25.76 || ^4.1.8"

package/src/cline-harness.ts

@@ -37,6 +37,8 @@ export type ClineHarnessSettings = {
   /**
    * Model id for the configured provider. When omitted, Cline selects the
    * provider's default model.
+   *
+   * @deprecated Use `model` on `HarnessAgent` instead.
    */
   readonly modelId?: string;
   /**
@@ -140,6 +142,18 @@ const CLINE_BUILTIN_TOOLS = {
     nativeName: 'ls',
     toolUseKind: 'readonly',
   } as HarnessV1BuiltinTool,
+  skills: {
+    ...tool({
+      description: 'Execute a configured skill by name.',
+      inputSchema: z.object({
+        skill: z.string(),
+        args: z.string().optional(),
+      }),
+      outputSchema: z.string(),
+    }),
+    nativeName: 'skills',
+    toolUseKind: 'readonly',
+  } as HarnessV1BuiltinTool,
 } as const satisfies Record<string, HarnessV1BuiltinTool<any, any>>;
 
 export function createCline(
@@ -153,6 +167,7 @@ export function createCline(
     supportsBuiltinToolFiltering: true,
     lifecycleStateSchema: clineResumeStateSchema,
     doStart: async startOpts => {
+      const modelId = startOpts.model ?? settings.modelId;
       const authEnv = resolveClineEnv({ auth: settings.auth });
       const lifecycleState = startOpts.continueFrom ?? startOpts.resumeFrom;
       const resumeData = lifecycleState?.data as
@@ -163,14 +178,13 @@ export function createCline(
         sessionId: startOpts.sessionId,
         sandboxSession: startOpts.sandboxSession,
         sessionWorkDir: startOpts.sessionWorkDir,
-        skills: startOpts.skills ?? [],
         settings: {
           authEnv,
           isAuthenticationEnvironmentOverride:
             isHarnessAuthenticationEnvironment(settings.auth),
           ...(settings.mcpServers ? { mcpServers: settings.mcpServers } : {}),
           ...(settings.providerId ? { providerId: settings.providerId } : {}),
-          ...(settings.modelId ? { modelId: settings.modelId } : {}),
+          ...(modelId == null ? {} : { modelId }),
           ...(settings.apiKey ? { apiKey: settings.apiKey } : {}),
           ...(settings.baseUrl ? { baseUrl: settings.baseUrl } : {}),
           ...(settings.headers ? { headers: settings.headers } : {}),

package/src/cline-remote-ops.ts

@@ -14,7 +14,6 @@ export interface ClineRemoteOpsOptions {
   readonly sandbox: Experimental_SandboxSession;
   /** Absolute sandbox path of the session's working directory. */
   readonly workDir: string;
-  readonly readableRoots?: ReadonlyArray<{ readonly sandboxDir: string }>;
 }
 
 export interface ClineRemoteOps {
@@ -50,9 +49,6 @@ export function createClineRemoteOps(
 ): ClineRemoteOps {
   const { sandbox, workDir } = options;
   const normalizedWorkDir = path.posix.normalize(workDir);
-  const readableRoots =
-    options.readableRoots?.map(root => path.posix.normalize(root.sandboxDir)) ??
-    [];
 
   const isInsidePath = ({
     parent,
@@ -78,19 +74,6 @@ export function createClineRemoteOps(
     return normalized;
   };
 
-  const assertReadablePath = (inputPath: string): string => {
-    const normalized = path.posix.normalize(inputPath);
-    if (
-      !isInsidePath({ parent: normalizedWorkDir, candidate: normalized }) &&
-      !readableRoots.some(parent =>
-        isInsidePath({ parent, candidate: normalized }),
-      )
-    ) {
-      throw new Error(`Cline path escapes the readable roots: ${inputPath}`);
-    }
-    return normalized;
-  };
-
   const resolvePath = (inputPath: string): string => {
     const resolved = path.posix.isAbsolute(inputPath)
       ? path.posix.normalize(inputPath)
@@ -98,13 +81,6 @@ export function createClineRemoteOps(
     return assertWorkspacePath(resolved);
   };
 
-  const resolveReadablePath = (inputPath: string): string => {
-    if (!path.posix.isAbsolute(inputPath)) {
-      return resolvePath(inputPath);
-    }
-    return assertReadablePath(inputPath);
-  };
-
   const runShell = async ({
     command,
     signal,
@@ -172,7 +148,7 @@ export function createClineRemoteOps(
     inputPath: string;
     missingMessage?: string;
   }): Promise<string> =>
-    assertReadablePath(
+    assertWorkspacePath(
       await resolveExistingSandboxPath({
         remotePath,
         inputPath,
@@ -216,7 +192,7 @@ export function createClineRemoteOps(
   };
 
   const readFile = async (inputPath: string): Promise<string> => {
-    const remotePath = resolveReadablePath(inputPath);
+    const remotePath = resolvePath(inputPath);
     const resolved = await resolveReadableSandboxPath({
       remotePath,
       inputPath,
@@ -305,7 +281,7 @@ export function createClineRemoteOps(
 
     async grep(pattern, input = {}) {
       const inputPath = input.path ?? '.';
-      const remotePath = resolveReadablePath(inputPath);
+      const remotePath = resolvePath(inputPath);
       const target = await resolveReadableSandboxPath({
         remotePath,
         inputPath,
@@ -341,7 +317,7 @@ export function createClineRemoteOps(
     },
 
     async glob(pattern, inputPath = '.', limit = 1_000) {
-      const remotePath = resolveReadablePath(inputPath);
+      const remotePath = resolvePath(inputPath);
       const target = await resolveReadableSandboxPath({
         remotePath,
         inputPath,
@@ -382,7 +358,7 @@ export function createClineRemoteOps(
     },
 
     async ls(inputPath = '.', limit = 500) {
-      const remotePath = resolveReadablePath(inputPath);
+      const remotePath = resolvePath(inputPath);
       const target = await resolveReadableSandboxPath({
         remotePath,
         inputPath,

package/src/cline-session.ts

@@ -35,7 +35,10 @@ import {
   resolveClinePrivateSessionDirectory,
   safeClineHistoryFileName,
 } from './cline-resume-state';
-import { renderSkillsPromptSection, writeClineSkills } from './cline-skills';
+import {
+  createClineSkillsRuntime,
+  type ClineSkillsRuntime,
+} from './cline-skills';
 import {
   buildBuiltinAgentTools,
   buildUserAgentTools,
@@ -97,7 +100,6 @@ export interface CreateClineSessionInput {
   readonly sessionId: string;
   readonly sandboxSession: HarnessV1NetworkSandboxSession | SandboxSession;
   readonly sessionWorkDir: string;
-  readonly skills: ReadonlyArray<HarnessV1Skill>;
   readonly settings: ClineSessionSettings;
   readonly clientApp: string;
   readonly isResume: boolean;
@@ -154,17 +156,12 @@ function clineBuiltinToolRequiresApproval(input: {
 function buildSystemPrompt(input: {
   sessionWorkDir: string;
   sandboxDescription: string;
-  skillsSection?: string;
 }): string {
-  const sections = [
+  return [
     'You are Cline, an autonomous coding agent operating inside a sandboxed workspace.',
     `## Workspace\n\nThe workspace root is \`${input.sessionWorkDir}\`. All relative file paths and shell commands resolve against it. Use the provided tools (read, write, edit, bash, grep, glob, ls) to inspect and modify the workspace.`,
     `## Sandbox\n\n${input.sandboxDescription}`,
-  ];
-  if (input.skillsSection) {
-    sections.push(input.skillsSection);
-  }
-  return sections.join('\n\n');
+  ].join('\n\n');
 }
 
 function toClineBackendProviderBaseUrl(baseUrl: string): string {
@@ -271,32 +268,9 @@ export async function createClineSession(
     input.builtinToolFiltering,
   );
 
-  // Materialize harness-provided skills into sandbox HOME (not the workspace)
-  // and advertise them via a system prompt section.
-  let skillsSection: string | undefined;
-  let skillRootDir: string | undefined;
-  if (input.skills.length > 0) {
-    skillRootDir = await writeClineSkills({
-      sandbox: toolSafeSandboxSession,
-      sandboxHomeDir,
-      skills: input.skills,
-      ...(input.abortSignal ? { abortSignal: input.abortSignal } : {}),
-    });
-    if (skillRootDir) {
-      skillsSection = renderSkillsPromptSection(input.skills, skillRootDir);
-    }
-  }
-
   const ops = createClineRemoteOps({
     sandbox: toolSafeSandboxSession,
     workDir: input.sessionWorkDir,
-    ...(skillRootDir ? { readableRoots: [{ sandboxDir: skillRootDir }] } : {}),
-  });
-
-  const baseSystemPrompt = buildSystemPrompt({
-    sessionWorkDir: input.sessionWorkDir,
-    sandboxDescription: toolSafeSandboxSession.description,
-    ...(skillsSection ? { skillsSection } : {}),
   });
 
   // On resume: pull the persisted conversation history from the sandbox so
@@ -324,7 +298,7 @@ export async function createClineSession(
   // Per-session mutable state we hold across prompts.
   let agent: Agent | undefined;
   let unsubscribe: (() => void) | undefined;
-  let lastToolsSignature: string | undefined;
+  let lastAgentConfigurationSignature: string | undefined;
   let agentHasRun = false;
   let stopped = false;
   /*
@@ -404,6 +378,7 @@ export async function createClineSession(
 
   function rebuildAgent(rebuildInput: {
     userTools: ReadonlyArray<HarnessV1ToolSpec>;
+    skillsRuntime: ClineSkillsRuntime;
     instructions?: string;
     responseFormat?: HarnessV1PromptTurnOptions['responseFormat'];
   }): void {
@@ -420,9 +395,15 @@ export async function createClineSession(
           }
         : {}),
       sessionId: input.sessionId,
-      systemPrompt: rebuildInput.instructions
-        ? `${baseSystemPrompt}\n\n${rebuildInput.instructions}`
-        : baseSystemPrompt,
+      systemPrompt: (() => {
+        const baseSystemPrompt = buildSystemPrompt({
+          sessionWorkDir: input.sessionWorkDir,
+          sandboxDescription: toolSafeSandboxSession.description,
+        });
+        return rebuildInput.instructions
+          ? `${baseSystemPrompt}\n\n${rebuildInput.instructions}`
+          : baseSystemPrompt;
+      })(),
       initialMessages: currentMessages,
       toolExecution: 'parallel',
       ...(input.settings.maxIterations !== undefined
@@ -430,6 +411,10 @@ export async function createClineSession(
         : {}),
       tools: [
         ...buildBuiltinAgentTools({ ops, activeNames: activeBuiltinNames }),
+        ...(rebuildInput.skillsRuntime.tool &&
+        activeBuiltinNames.includes('skills')
+          ? [rebuildInput.skillsRuntime.tool]
+          : []),
         ...mcpRuntime.tools,
         ...buildUserAgentTools({
           specs: rebuildInput.userTools,
@@ -572,19 +557,23 @@ export async function createClineSession(
    * Shared by `doPromptTurn` (a fresh user prompt) and `doContinueTurn`
    * (no prompt — the runtime continues its own thread after a rerun resume).
    */
-  function runTurn(turnOpts: {
+  async function runTurn(turnOpts: {
     text: string | undefined;
+    skills: ReadonlyArray<HarnessV1Skill>;
     tools: ReadonlyArray<HarnessV1ToolSpec>;
     instructions?: string;
     emit: (part: HarnessV1StreamPart) => void;
     abortSignal?: AbortSignal;
     responseFormat?: HarnessV1PromptTurnOptions['responseFormat'];
-  }): HarnessV1PromptControl {
+  }): Promise<HarnessV1PromptControl> {
     if (stopped) {
       throw new Error('Cline session has been stopped.');
     }
 
     const userTools = turnOpts.tools;
+    const skillsRuntime = createClineSkillsRuntime({
+      skills: turnOpts.skills,
+    });
     if (
       turnOpts.responseFormat?.type === 'json' &&
       turnOpts.responseFormat.schema == null
@@ -607,25 +596,31 @@ export async function createClineSession(
     }
 
     const signature = JSON.stringify({
-      tools: userTools.map(t => t.name).sort(),
+      tools: userTools,
       responseFormat: turnOpts.responseFormat,
+      instructions: turnOpts.instructions,
+      skills: skillsRuntime.signature,
     });
-    if (agent == null || signature !== lastToolsSignature) {
+    if (agent == null || signature !== lastAgentConfigurationSignature) {
       currentMessages = agent?.snapshot().messages ?? currentMessages;
       rebuildAgent({
         userTools,
+        skillsRuntime,
         responseFormat: turnOpts.responseFormat,
         ...(turnOpts.instructions
           ? { instructions: turnOpts.instructions }
           : {}),
       });
-      lastToolsSignature = signature;
+      lastAgentConfigurationSignature = signature;
     }
 
     currentEmit = turnOpts.emit;
+    const userToolNames = new Set(userTools.map(tool => tool.name));
     translatorState = createClineTranslatorState({
-      builtinToolNames: activeBuiltinNames,
-      hostToolNames: userTools.map(tool => tool.name),
+      builtinToolNames: activeBuiltinNames.filter(
+        name => !userToolNames.has(name),
+      ),
+      hostToolNames: userToolNames,
       ignoredToolNames:
         turnOpts.responseFormat?.type === 'json' ? ['structured_output'] : [],
       mcpToolNames: mcpRuntime.toolNames,
@@ -809,6 +804,7 @@ export async function createClineSession(
     ): Promise<HarnessV1PromptControl> => {
       return runTurn({
         text: extractUserText(promptOpts.prompt),
+        skills: promptOpts.skills,
         tools: promptOpts.tools ?? [],
         ...(promptOpts.instructions
           ? { instructions: promptOpts.instructions }
@@ -843,6 +839,7 @@ export async function createClineSession(
        */
       return runTurn({
         text: undefined,
+        skills: continueOpts.skills,
         tools: continueOpts.tools ?? [],
         ...(continueOpts.instructions
           ? { instructions: continueOpts.instructions }

package/src/cline-skills.ts

@@ -1,59 +1,184 @@
 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 { AgentTool } from '@cline/agents';
+import { createDefaultTools, type ToolExecutors } from '@cline/core';
+
+const CLINE_SKILL_NAME_PATTERN = /^[A-Za-z0-9._-]+$/;
+
+type ProjectedClineSkill = {
+  readonly id: string;
+  readonly name: string;
+  readonly description: string;
+  readonly content: string;
+  readonly files: ReadonlyArray<{
+    readonly path: string;
+    readonly content: string;
+  }>;
+};
+
+export type ClineSkillsRuntime = {
+  readonly signature: string;
+  readonly tool?: AgentTool;
+};
 
 /**
- * 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.
+ * Build Cline's native skills tool around an immutable in-host projection of
+ * the harness skills. The low-level Agent does not discover skills itself, so
+ * the adapter provides the same tool contract that Cline's core orchestration
+ * layer uses without involving the sandbox filesystem.
  */
-export async function writeClineSkills({
-  sandbox,
-  sandboxHomeDir,
+export function createClineSkillsRuntime({
   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;
+}): ClineSkillsRuntime {
+  const projectedSkills = projectClineSkills({ skills });
+  const signature = JSON.stringify(projectedSkills);
+  if (projectedSkills.length === 0) {
+    return { signature };
+  }
+
+  const executor: NonNullable<ToolExecutors['skills']> = async (
+    ...executorArguments
+  ) => {
+    const [requestedSkill, args] = executorArguments;
+    const skill = projectedSkills.find(
+      candidate => candidate.id === normalizeSkillToken(requestedSkill),
+    );
+    if (skill == null) {
+      const availableSkills = projectedSkills.map(skill => skill.name);
+      return availableSkills.length > 0
+        ? `Skill "${requestedSkill}" not found. Available skills: ${availableSkills.join(', ')}`
+        : 'No skills are currently available.';
+    }
+    return renderSkillInstructions({ skill, args });
+  };
+  executor.configuredSkills = projectedSkills.map(skill => ({
+    id: skill.id,
+    name: skill.name,
+    description: skill.description,
+    disabled: false,
+  }));
+
+  const tool = createDefaultTools({
+    executors: { skills: executor },
+    enableReadFiles: false,
+    enableSearch: false,
+    enableBash: false,
+    enableWebFetch: false,
+    enableApplyPatch: false,
+    enableEditor: false,
+    enableSkills: true,
+    enableAskQuestion: false,
+    enableSubmitAndExit: false,
+  }).find(tool => tool.name === 'skills');
+  if (tool == null) {
+    throw new Error('Cline did not create its native skills tool.');
+  }
+
+  return { signature, tool };
 }
 
-/**
- * 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
-  );
+function projectClineSkills({
+  skills,
+}: {
+  skills: ReadonlyArray<HarnessV1Skill>;
+}): ReadonlyArray<ProjectedClineSkill> {
+  const names = new Set<string>();
+  const ids = new Set<string>();
+  return skills
+    .map(skill => {
+      if (
+        !CLINE_SKILL_NAME_PATTERN.test(skill.name) ||
+        skill.name === '.' ||
+        skill.name === '..'
+      ) {
+        throw new Error(`Invalid Cline skill name: ${skill.name}`);
+      }
+      if (names.has(skill.name)) {
+        throw new Error(`Duplicate Cline skill name: ${skill.name}`);
+      }
+      names.add(skill.name);
+
+      const id = normalizeSkillToken(skill.name);
+      if (ids.has(id)) {
+        throw new Error(`Duplicate Cline skill identifier: ${id}`);
+      }
+      ids.add(id);
+
+      return {
+        id,
+        name: skill.name,
+        description: skill.description,
+        content: skill.content,
+        files: (skill.files ?? [])
+          .map(file => ({
+            path: normalizeSkillFilePath({
+              skillName: skill.name,
+              filePath: file.path,
+            }),
+            content: file.content,
+          }))
+          .sort(
+            (left, right) =>
+              left.path.localeCompare(right.path) ||
+              left.content.localeCompare(right.content),
+          ),
+      };
+    })
+    .sort((left, right) => left.name.localeCompare(right.name));
+}
+
+function normalizeSkillToken(skill: string): string {
+  return skill.trim().replace(/^\/+/, '').toLowerCase();
+}
+
+function normalizeSkillFilePath({
+  skillName,
+  filePath,
+}: {
+  skillName: string;
+  filePath: string;
+}): string {
+  const normalized = path.posix.normalize(filePath);
+  if (
+    normalized === '' ||
+    normalized === '.' ||
+    normalized.startsWith('../') ||
+    normalized.includes('/../') ||
+    normalized.endsWith('/..') ||
+    path.posix.isAbsolute(normalized)
+  ) {
+    throw new Error(
+      `Invalid Cline skill file path for ${skillName}: ${filePath}`,
+    );
+  }
+  return normalized;
+}
+
+function renderSkillInstructions({
+  skill,
+  args,
+}: {
+  skill: ProjectedClineSkill;
+  args: string | undefined;
+}): string {
+  const trimmedArgs = args?.trim();
+  const argsTag = trimmedArgs
+    ? `\n<command-args>${trimmedArgs}</command-args>`
+    : '';
+  const description = skill.description.trim()
+    ? `Description: ${skill.description.trim()}\n\n`
+    : '';
+  const files =
+    skill.files.length === 0
+      ? ''
+      : `\n\n<skill-files>\n${skill.files
+          .map(
+            file =>
+              `<skill-file path=${JSON.stringify(file.path)}>\n${file.content}\n</skill-file>`,
+          )
+          .join('\n')}\n</skill-files>`;
+
+  return `<command-name>${skill.name}</command-name>${argsTag}\n<command-instructions>\n${description}${skill.content}${files}\n</command-instructions>`;
 }

package/src/cline-tools.ts

@@ -24,6 +24,7 @@ export const CLINE_NATIVE_BUILTIN_NAMES = [
   'grep',
   'glob',
   'ls',
+  'skills',
 ] as const;
 
 export type ClineNativeBuiltinName =
@@ -39,6 +40,7 @@ export const CLINE_NATIVE_TOOL_KINDS: Readonly<
   grep: 'readonly',
   glob: 'readonly',
   ls: 'readonly',
+  skills: 'readonly',
 };
 
 export function isClineBuiltinToolName(
@@ -127,9 +129,9 @@ async function guarded<T>(run: () => Promise<T>): Promise<ClineToolResult> {
 }
 
 /**
- * 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.
+ * Build the sandbox-backed coding tools handed to the Cline runtime. These
+ * schemas mirror their declarations in `CLINE_BUILTIN_TOOLS`
+ * (cline-harness.ts). The in-host skills tool is built separately.
  */
 export function buildBuiltinAgentTools({
   ops,