@ai-sdk/harness-cline 1.0.18 → 1.0.20

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ai-sdk/harness-cline",
-  "version": "1.0.18",
+  "version": "1.0.20",
   "type": "module",
   "license": "Apache-2.0",
   "sideEffects": false,
@@ -26,11 +26,11 @@
     }
   },
   "dependencies": {
-    "@ai-sdk/harness": "1.0.91",
+    "@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-auth.ts

@@ -1,31 +1,45 @@
-import { getAiGatewayAuthFromEnv } from '@ai-sdk/harness/utils';
+import type { HarnessV1Authentication } from '@ai-sdk/harness';
+import {
+  getAiGatewayAuthFromEnv,
+  isHarnessAuthenticationEnvironment,
+} from '@ai-sdk/harness/utils';
 
-export type ClineAuthenticationMode = 'auto' | 'direct' | 'ai-gateway';
-
-export type ClineAuthOptions = ClineAuthenticationMode;
+export type ClineAuthenticationMode = HarnessV1Authentication;
 
 export function resolveClineEnv({
   auth = 'auto',
   env = process.env,
 }: {
-  auth?: ClineAuthOptions;
+  auth?: ClineAuthenticationMode;
   env?: Record<string, string | undefined>;
 }): Record<string, string> {
+  if (isHarnessAuthenticationEnvironment(auth)) {
+    const gatewayAuth = getAiGatewayAuthFromEnv({ env: auth });
+    return gatewayAuth.apiKey
+      ? toGatewayClineEnv(gatewayAuth)
+      : pickDirectClineEnv({ env: auth });
+  }
   if (auth === 'direct') {
     return pickDirectClineEnv({ env });
   }
 
   const gatewayAuth = getAiGatewayAuthFromEnv({ env });
   if (auth === 'ai-gateway' || gatewayAuth.apiKey) {
-    return {
-      ...(gatewayAuth.apiKey ? { AI_GATEWAY_API_KEY: gatewayAuth.apiKey } : {}),
-      AI_GATEWAY_BASE_URL: gatewayAuth.baseUrl,
-    };
+    return toGatewayClineEnv(gatewayAuth);
   }
 
   return pickDirectClineEnv({ env });
 }
 
+function toGatewayClineEnv(
+  gatewayAuth: ReturnType<typeof getAiGatewayAuthFromEnv>,
+): Record<string, string> {
+  return {
+    ...(gatewayAuth.apiKey ? { AI_GATEWAY_API_KEY: gatewayAuth.apiKey } : {}),
+    AI_GATEWAY_BASE_URL: gatewayAuth.baseUrl,
+  };
+}
+
 function pickDirectClineEnv({
   env,
 }: {

package/src/cline-harness.ts

@@ -3,9 +3,10 @@ import {
   type HarnessV1,
   type HarnessV1BuiltinTool,
 } from '@ai-sdk/harness';
+import { isHarnessAuthenticationEnvironment } from '@ai-sdk/harness/utils';
 import { tool } from '@ai-sdk/provider-utils';
 import { z } from 'zod/v4';
-import { resolveClineEnv, type ClineAuthOptions } from './cline-auth';
+import { resolveClineEnv, type ClineAuthenticationMode } from './cline-auth';
 import { clineResumeStateSchema } from './cline-resume-state';
 import { createClineSession, type ClineReasoningEffort } from './cline-session';
 import { VERSION } from './version';
@@ -22,7 +23,7 @@ const CLINE_CLIENT_APP = `ai-sdk/harness-cline/${VERSION}`;
  */
 export type ClineHarnessSettings = {
   /** Where Cline sources direct or AI Gateway credentials from. */
-  readonly auth?: ClineAuthOptions;
+  readonly auth?: ClineAuthenticationMode;
   /**
    * MCP server definitions keyed by server name. Each definition uses the
    * underlying runtime's native MCP server configuration format.
@@ -36,11 +37,14 @@ 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;
   /**
    * Provider API key. When omitted, the Cline gateway falls back to the
    * provider's environment variable (e.g. `ANTHROPIC_API_KEY`).
+   * A record-shaped authentication override disables that fallback.
    */
   readonly apiKey?: string;
   /** Custom provider endpoint. */
@@ -138,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(
@@ -151,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
@@ -161,12 +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,
@@ -82,6 +85,7 @@ const parkedClineSessions = new Map<string, HarnessV1Session>();
 
 export interface ClineSessionSettings {
   readonly authEnv: Record<string, string>;
+  readonly isAuthenticationEnvironmentOverride: boolean;
   readonly mcpServers?: Record<string, unknown>;
   readonly providerId?: string;
   readonly modelId?: string;
@@ -96,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;
@@ -153,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 {
@@ -209,7 +207,9 @@ function createClineAgentModel({
         ...(apiKey ? { apiKey } : {}),
         ...(baseUrl ? { baseUrl } : {}),
         ...(headers ? { headers } : {}),
-        ...(isAiGateway ? { apiKeyEnv: [] } : {}),
+        ...(isAiGateway || settings.isAuthenticationEnvironmentOverride
+          ? { apiKeyEnv: [] }
+          : {}),
       },
     ],
   });
@@ -268,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
@@ -321,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;
   /*
@@ -401,6 +378,7 @@ export async function createClineSession(
 
   function rebuildAgent(rebuildInput: {
     userTools: ReadonlyArray<HarnessV1ToolSpec>;
+    skillsRuntime: ClineSkillsRuntime;
     instructions?: string;
     responseFormat?: HarnessV1PromptTurnOptions['responseFormat'];
   }): void {
@@ -417,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
@@ -427,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,
@@ -569,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
@@ -604,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,
@@ -806,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 }
@@ -840,6 +839,7 @@ export async function createClineSession(
        */
       return runTurn({
         text: undefined,
+        skills: continueOpts.skills,
         tools: continueOpts.tools ?? [],
         ...(continueOpts.instructions
           ? { instructions: continueOpts.instructions }