@ai-sdk/harness-claude-code 1.0.0-canary.2 → 1.0.0-canary.4

package/src/claude-code-harness.ts

@@ -1,5 +1,6 @@
 import { randomBytes } from 'node:crypto';
 import { readFile } from 'node:fs/promises';
+import path from 'node:path';
 import { fileURLToPath } from 'node:url';
 import {
   commonTool,
@@ -19,9 +20,13 @@ import {
   type HarnessV1Skill,
   type HarnessV1StreamPart,
 } from '@ai-sdk/harness';
-import { classifyDiskLog, SandboxChannel } from '@ai-sdk/harness/utils';
 import {
-  safeParseJSON,
+  classifyDiskLog,
+  markBridgeStarting,
+  SandboxChannel,
+  waitForBridgeReady,
+} from '@ai-sdk/harness/utils';
+import {
   tool,
   type Experimental_SandboxSession,
   type Experimental_SandboxProcess,
@@ -33,7 +38,6 @@ import {
   type ClaudeCodeAuthOptions,
 } from './claude-code-auth';
 import {
-  bridgeReadySchema,
   outboundMessageSchema,
   type InboundMessage,
   type OutboundMessage,
@@ -506,6 +510,7 @@ export function createClaudeCode(
             sandboxId,
             debug: startOpts.observability?.debug,
             permissionMode: startOpts.permissionMode,
+            skills: startOpts.skills ?? [],
           });
         } catch {
           // Bridge no longer reachable — recover by respawning below.
@@ -536,12 +541,20 @@ export function createClaudeCode(
         }
       }
 
+      const sandboxHomeDir =
+        startOpts.skills && startOpts.skills.length > 0
+          ? await resolveSandboxHomeDir({
+              sandbox: session,
+              abortSignal: startOpts.abortSignal,
+            })
+          : undefined;
       const port = resolveBridgePort(sandboxSession, settings.port);
       const token = randomBytes(32).toString('hex');
       const env = {
         ...resolveClaudeCodeEnv(settings.auth),
         BRIDGE_CHANNEL_TOKEN: token,
         BRIDGE_WS_PORT: String(port),
+        ...(sandboxHomeDir ? { HOME: sandboxHomeDir } : {}),
         ...(respawnStrategy === 'replay'
           ? { BRIDGE_REPLAY_FROM_DISK: '1' }
           : {}),
@@ -560,15 +573,25 @@ export function createClaudeCode(
         });
 
         if (startOpts.skills && startOpts.skills.length > 0) {
+          if (!sandboxHomeDir) {
+            throw new Error('Unable to resolve sandbox HOME directory.');
+          }
           await writeSkills({
             sandbox: session,
-            workdir: workDir,
+            homeDir: sandboxHomeDir,
             skills: startOpts.skills,
             abortSignal: startOpts.abortSignal,
           });
         }
       }
 
+      await markBridgeStarting({
+        sandbox: session,
+        bridgeStateDir,
+        bridgeType: 'claude-code',
+        abortSignal: startOpts.abortSignal,
+      });
+
       const proc = await session.spawn({
         command: `node ${BOOTSTRAP_DIR}/bridge.mjs --workdir ${workDir} --bridge-state-dir ${bridgeStateDir}`,
         env,
@@ -589,10 +612,27 @@ export function createClaudeCode(
       void bridgeStartupStderrDone;
       const { port: boundPort } = await waitForBridgeReady({
         proc,
+        sandbox: session,
+        bridgeStateDir,
+        bridgeType: 'claude-code',
         timeoutMs,
         abortSignal: startOpts.abortSignal,
-        stderrTail: bridgeStartupStderr,
-        stderrDone: bridgeStartupStderrDone,
+        createTimeoutError: ({ proc, stdoutTail }) =>
+          createBridgeStartupError({
+            message: 'claude-code bridge did not become ready in time.',
+            proc,
+            stdoutTail,
+            stderrTail: bridgeStartupStderr,
+            stderrDone: bridgeStartupStderrDone,
+          }),
+        createExitError: ({ proc, stdoutTail }) =>
+          createBridgeStartupError({
+            message: 'claude-code bridge exited before becoming ready.',
+            proc,
+            stdoutTail,
+            stderrTail: bridgeStartupStderr,
+            stderrDone: bridgeStartupStderrDone,
+          }),
       });
       void drainRest(proc.stdout);
 
@@ -632,6 +672,7 @@ export function createClaudeCode(
         sandboxId,
         debug: startOpts.observability?.debug,
         permissionMode: startOpts.permissionMode,
+        skills: startOpts.skills ?? [],
       });
     },
   };
@@ -652,31 +693,106 @@ function resolveBridgePort(
 }
 
 /**
- * Materialise skill files into `${workdir}/.claude/skills/<name>.md`. The
- * `claude` CLI auto-discovers skills from that directory on startup, so the
- * files have to be in place before the bridge is spawned. Each file uses
- * the YAML-frontmatter shape the CLI expects.
+ * Materialise skill files into
+ * `$HOME/.claude/skills/<name>/SKILL.md`. The `claude` CLI
+ * auto-discovers skills from that directory on startup, so the files have to
+ * be in place before the bridge is spawned without mutating the session
+ * workdir. Each file uses the YAML-frontmatter shape the CLI expects.
  */
 async function writeSkills({
   sandbox,
-  workdir,
+  homeDir,
   skills,
   abortSignal,
 }: {
   sandbox: Experimental_SandboxSession;
-  workdir: string;
+  homeDir: string;
   skills: ReadonlyArray<HarnessV1Skill>;
   abortSignal?: AbortSignal;
 }): Promise<void> {
+  for (const skill of skills) {
+    safeClaudeSkillName(skill.name);
+    for (const file of skill.files ?? []) {
+      safeClaudeSkillFilePath({
+        skillName: skill.name,
+        filePath: file.path,
+      });
+    }
+  }
+
   await sandbox.run({
-    command: `mkdir -p ${workdir}/.claude/skills`,
+    command: `mkdir -p ${shellQuote(homeDir)}/.claude/skills`,
     abortSignal,
   });
   for (const skill of skills) {
-    const path = `${workdir}/.claude/skills/${skill.name}.md`;
+    const name = safeClaudeSkillName(skill.name);
+    const skillDir = `${homeDir}/.claude/skills/${name}`;
+    const path = `${skillDir}/SKILL.md`;
     const content = `---\nname: ${skill.name}\ndescription: ${skill.description}\n---\n\n${skill.content}\n`;
     await sandbox.writeTextFile({ path, content, abortSignal });
+    for (const file of skill.files ?? []) {
+      const filePath = safeClaudeSkillFilePath({
+        skillName: skill.name,
+        filePath: file.path,
+      });
+      await sandbox.writeTextFile({
+        path: `${skillDir}/${filePath}`,
+        content: file.content,
+        abortSignal,
+      });
+    }
+  }
+}
+
+async function resolveSandboxHomeDir({
+  sandbox,
+  abortSignal,
+}: {
+  sandbox: Experimental_SandboxSession;
+  abortSignal?: AbortSignal;
+}): Promise<string> {
+  const result = await sandbox.run({
+    command: 'printf "%s" "$HOME"',
+    abortSignal,
+  });
+  const homeDir = result.stdout.trim();
+  if (result.exitCode !== 0 || !homeDir || !path.posix.isAbsolute(homeDir)) {
+    throw new Error(
+      `Unable to resolve sandbox HOME directory: ${result.stderr || result.stdout}`,
+    );
+  }
+  return homeDir;
+}
+
+function safeClaudeSkillName(name: string): string {
+  if (!/^[A-Za-z0-9._-]+$/.test(name) || name === '.' || name === '..') {
+    throw new Error(`Invalid Claude Code skill name: ${name}`);
   }
+  return name;
+}
+
+function safeClaudeSkillFilePath({
+  skillName,
+  filePath,
+}: {
+  skillName: string;
+  filePath: string;
+}): string {
+  const normalized = path.posix.normalize(filePath);
+  if (
+    normalized === '.' ||
+    normalized.startsWith('../') ||
+    path.posix.isAbsolute(normalized)
+  ) {
+    throw new Error(
+      `Invalid Claude Code skill file path for ${skillName}: ${filePath}`,
+    );
+  }
+  return normalized;
+}
+
+function shellQuote(value: string): string {
+  return `'${value.replace(/'/g, `'\\''`)}'`;
 }
 
 async function readBridgeAsset(name: string): Promise<string> {
@@ -697,80 +813,6 @@ async function readBridgeAsset(name: string): Promise<string> {
   throw lastErr ?? new Error(`bridge asset not found: ${name}`);
 }
 
-async function waitForBridgeReady({
-  proc,
-  timeoutMs,
-  abortSignal,
-  stderrTail,
-  stderrDone,
-}: {
-  proc: Experimental_SandboxProcess;
-  timeoutMs: number;
-  abortSignal: AbortSignal | undefined;
-  stderrTail: string[];
-  stderrDone: Promise<void>;
-}): Promise<{ port: number }> {
-  const reader = proc.stdout.pipeThrough(new TextDecoderStream()).getReader();
-
-  const decoder = lineDecoder();
-  const stdoutTail: string[] = [];
-
-  const deadline = Date.now() + timeoutMs;
-  try {
-    while (true) {
-      if (abortSignal?.aborted) {
-        await proc.kill();
-        throw abortSignal.reason ?? new DOMException('Aborted', 'AbortError');
-      }
-      const remaining = deadline - Date.now();
-      if (remaining <= 0) {
-        await proc.kill();
-        throw await createBridgeStartupError({
-          message: 'claude-code bridge did not become ready in time.',
-          proc,
-          stdoutTail,
-          stderrTail,
-          stderrDone,
-        });
-      }
-      const { value, done } = (await Promise.race([
-        reader.read(),
-        new Promise(resolve =>
-          setTimeout(
-            () => resolve({ value: undefined, done: false }),
-            remaining,
-          ),
-        ),
-      ])) as ReadableStreamReadResult<string>;
-      if (done) {
-        for (const line of decoder.flush()) {
-          stdoutTail.push(line);
-          if (stdoutTail.length > 20) stdoutTail.shift();
-        }
-        throw await createBridgeStartupError({
-          message: 'claude-code bridge exited before becoming ready.',
-          proc,
-          stdoutTail,
-          stderrTail,
-          stderrDone,
-        });
-      }
-      if (value === undefined) continue;
-      for (const line of decoder.push(value)) {
-        stdoutTail.push(line);
-        if (stdoutTail.length > 20) stdoutTail.shift();
-        const parsed = await safeParseJSON({
-          text: line,
-          schema: bridgeReadySchema,
-        });
-        if (parsed.success) return { port: parsed.value.port };
-      }
-    }
-  } finally {
-    reader.releaseLock();
-  }
-}
-
 async function createBridgeStartupError({
   message,
   proc,
@@ -1063,6 +1105,7 @@ function createSession({
   sandboxId,
   debug,
   permissionMode,
+  skills,
 }: {
   sessionId: string;
   channel: ClaudeCodeChannel;
@@ -1079,6 +1122,7 @@ function createSession({
   sandboxId: string;
   debug: HarnessV1DebugConfig | undefined;
   permissionMode: HarnessV1PermissionMode | undefined;
+  skills: ReadonlyArray<HarnessV1Skill>;
 }): HarnessV1Session {
   let stopped = false;
   let stopPromise: Promise<void> | undefined;
@@ -1259,6 +1303,9 @@ function createSession({
         model,
         maxTurns,
         thinking,
+        ...(skills.length > 0
+          ? { skills: skills.map(skill => skill.name) }
+          : {}),
         ...(permissionMode ? { permissionMode } : {}),
         ...(debug ? { debug } : {}),
         ...(pendingResumeFlag ? { continue: true } : {}),
@@ -1307,6 +1354,9 @@ function createSession({
           model,
           maxTurns,
           thinking,
+          ...(skills.length > 0
+            ? { skills: skills.map(skill => skill.name) }
+            : {}),
           ...(permissionMode ? { permissionMode } : {}),
           ...(debug ? { debug } : {}),
           continue: true,