@ai-sdk/harness 1.0.101 → 1.0.103

package/dist/index.d.ts

@@ -916,6 +916,10 @@ declare function getHarnessV1BuiltinToolFilteringDenialReason(input: {
  * calling the adapter, so adapters never need to derive provider-specific paths.
  */
 type HarnessV1StartOptions = {
+    /**
+     * Additional normalized HTTP headers to send with model requests.
+     */
+    readonly headers?: Readonly<Record<string, string>>;
     /**
      * Stable identifier for this harness session. Used as the underlying
      * resource name where the adapter has a notion of a named session

package/dist/utils/index.d.ts

@@ -522,10 +522,24 @@ declare function resolveSandboxHomeDir({ sandbox, abortSignal, }: {
 
 declare function shellQuote(value: string): string;
 
+type WriteInstructionsOptions = {
+    sandbox: Experimental_SandboxSession;
+    homePath: string;
+    instructionsFile: string;
+    instructions?: string;
+    abortSignal?: AbortSignal;
+};
+type WriteInstructionsResult = {
+    changed: boolean;
+    filePath: string;
+};
+declare function writeInstructions({ sandbox, homePath, instructionsFile, instructions, abortSignal, }: WriteInstructionsOptions): Promise<WriteInstructionsResult>;
+
 type SkillFilePathMode = 'relative' | 'strip-leading-slashes';
 type WriteSkillsOptions = {
     sandbox: Experimental_SandboxSession;
-    rootDir: string;
+    homePath: string;
+    skillsDir: string;
     skills: ReadonlyArray<HarnessV1Skill>;
     abortSignal?: AbortSignal;
     skillNamePattern?: RegExp;
@@ -545,7 +559,7 @@ type WriteSkillsResult = {
     removed: string[];
     unchanged: string[];
 };
-declare function writeSkills({ sandbox, rootDir, skills, abortSignal, skillNamePattern, invalidSkillNameMessage, filePathMode, invalidSkillFilePathMessage, trailingNewline, }: WriteSkillsOptions): Promise<WriteSkillsResult>;
+declare function writeSkills({ sandbox, homePath, skillsDir, skills, abortSignal, skillNamePattern, invalidSkillNameMessage, filePathMode, invalidSkillFilePathMessage, trailingNewline, }: WriteSkillsOptions): Promise<WriteSkillsResult>;
 
 type BridgeReadySource = 'stdout' | 'metadata';
 type BridgeReadyErrorContext = {
@@ -625,4 +639,4 @@ declare function resolveSandboxDefaultWorkingDirectory({ sandboxSession, abortSi
 
 declare function getRestrictedSandboxSession(sandboxSession: HarnessV1NetworkSandboxSession | Experimental_SandboxSession): Experimental_SandboxSession;
 
-export { type BridgeReadyErrorContext, type BridgeReadySource, type DiskLogRecoveryMode, type Experimental_BridgeUserMessageRequest, type Experimental_BridgeUserMessageResponse, type Experimental_BridgeUserMessageSubmitter, SandboxChannel, type SandboxChannelDebugEvent, type SandboxChannelOptions, type SandboxChannelReconnectOptions, type SkillFilePathMode, type WaitForBridgeReadyOptions, type WaitForBridgeReadyResult, type WriteSkillsOptions, type WriteSkillsResult, applyCredentialForwarding, classifyDiskLog, createBridgeErrorHandler, createBridgeStartupError, createBridgeToken, createCredentialRequestTransformation, createReadBridgeAsset, createSandboxCredentialEnvironment, drainBridgeProcessStream, experimental_createBridgeUserMessageSubmitter, formatBridgeError, forwardBridgeProcessStream, generateSandboxCredentialPlaceholder, getAiGatewayAuthFromEnv, getRestrictedSandboxSession, isHarnessAuthenticationEnvironment, isSandboxCredentialPlaceholder, logBridgeError, markBridgeStarting, maskSandboxCredentials, resolveSandboxDefaultWorkingDirectory, resolveSandboxHomeDir, shellQuote, waitForBridgeReady, warnCredentialBrokeringUnavailable, withBridgeToken, writeSkills };
+export { type BridgeReadyErrorContext, type BridgeReadySource, type DiskLogRecoveryMode, type Experimental_BridgeUserMessageRequest, type Experimental_BridgeUserMessageResponse, type Experimental_BridgeUserMessageSubmitter, SandboxChannel, type SandboxChannelDebugEvent, type SandboxChannelOptions, type SandboxChannelReconnectOptions, type SkillFilePathMode, type WaitForBridgeReadyOptions, type WaitForBridgeReadyResult, type WriteInstructionsOptions, type WriteInstructionsResult, type WriteSkillsOptions, type WriteSkillsResult, applyCredentialForwarding, classifyDiskLog, createBridgeErrorHandler, createBridgeStartupError, createBridgeToken, createCredentialRequestTransformation, createReadBridgeAsset, createSandboxCredentialEnvironment, drainBridgeProcessStream, experimental_createBridgeUserMessageSubmitter, formatBridgeError, forwardBridgeProcessStream, generateSandboxCredentialPlaceholder, getAiGatewayAuthFromEnv, getRestrictedSandboxSession, isHarnessAuthenticationEnvironment, isSandboxCredentialPlaceholder, logBridgeError, markBridgeStarting, maskSandboxCredentials, resolveSandboxDefaultWorkingDirectory, resolveSandboxHomeDir, shellQuote, waitForBridgeReady, warnCredentialBrokeringUnavailable, withBridgeToken, writeInstructions, writeSkills };

package/dist/utils/index.js

@@ -573,18 +573,285 @@ function shellQuote(value) {
   return `'${value.replace(/'/g, `'\\''`)}'`;
 }
 
-// src/utils/write-skills.ts
-import { createHash } from "crypto";
+// src/utils/write-instructions.ts
 import path2 from "path";
 import {
   safeParseJSON as safeParseJSON3
 } from "@ai-sdk/provider-utils";
+var INSTRUCTIONS_METADATA_VERSION = 1;
+async function writeInstructions({
+  sandbox,
+  homePath,
+  instructionsFile,
+  instructions,
+  abortSignal
+}) {
+  const { targetPath, metadataPath } = resolveInstructionsFilePath({
+    homePath,
+    instructionsFile
+  });
+  const hasInstructions = typeof instructions === "string" && instructions.trim().length > 0;
+  const trimmedInstructions = hasInstructions ? instructions.trim() : "";
+  const currentDiskContent = await sandbox.readTextFile({
+    path: targetPath,
+    abortSignal
+  });
+  const existingMetadata = await readInstructionsMetadata({
+    sandbox,
+    metadataPath,
+    abortSignal
+  });
+  if (hasInstructions) {
+    const originalContent = deriveOriginalContent({
+      currentDiskContent,
+      existingMetadata
+    });
+    const targetContent = originalContent != null && originalContent.trim().length > 0 ? `${originalContent.replace(/\n+$/, "")}
+
+${trimmedInstructions}
+` : `${trimmedInstructions}
+`;
+    if (currentDiskContent === targetContent && existingMetadata != null && existingMetadata.instructions === trimmedInstructions && existingMetadata.originalContent === originalContent) {
+      return { changed: false, filePath: targetPath };
+    }
+    await sandbox.writeTextFile({
+      path: targetPath,
+      content: targetContent,
+      abortSignal
+    });
+    await writeInstructionsMetadata({
+      sandbox,
+      metadataPath,
+      metadata: {
+        version: INSTRUCTIONS_METADATA_VERSION,
+        originalContent,
+        instructions: trimmedInstructions,
+        appliedContent: targetContent
+      },
+      abortSignal
+    });
+    return { changed: true, filePath: targetPath };
+  }
+  if (existingMetadata == null) {
+    return { changed: false, filePath: targetPath };
+  }
+  const restoredContent = deriveRestoredContent({
+    currentDiskContent,
+    existingMetadata
+  });
+  if (restoredContent != null) {
+    const contentToWrite = `${restoredContent.replace(/\n+$/, "")}
+`;
+    await sandbox.writeTextFile({
+      path: targetPath,
+      content: contentToWrite,
+      abortSignal
+    });
+  } else {
+    await removeTargetFile({
+      sandbox,
+      targetPath,
+      abortSignal
+    });
+  }
+  await removeMetadataFile({
+    sandbox,
+    metadataPath,
+    abortSignal
+  });
+  return { changed: true, filePath: targetPath };
+}
+function deriveOriginalContent({
+  currentDiskContent,
+  existingMetadata
+}) {
+  var _a;
+  if (existingMetadata == null) {
+    return currentDiskContent;
+  }
+  if (currentDiskContent == null) {
+    return existingMetadata.originalContent;
+  }
+  if (currentDiskContent === existingMetadata.appliedContent) {
+    return existingMetadata.originalContent;
+  }
+  const trimmedDisk = currentDiskContent.replace(/\n+$/, "");
+  const expectedSuffix = `
+
+${existingMetadata.instructions}`;
+  if (trimmedDisk.endsWith(expectedSuffix)) {
+    const userBase = trimmedDisk.slice(0, -expectedSuffix.length);
+    return userBase.length > 0 ? userBase : null;
+  }
+  if (trimmedDisk === existingMetadata.instructions) {
+    return null;
+  }
+  return (_a = existingMetadata.originalContent) != null ? _a : currentDiskContent;
+}
+function deriveRestoredContent({
+  currentDiskContent,
+  existingMetadata
+}) {
+  if (currentDiskContent == null) {
+    return null;
+  }
+  if (currentDiskContent === existingMetadata.appliedContent) {
+    return existingMetadata.originalContent != null && existingMetadata.originalContent.trim().length > 0 ? existingMetadata.originalContent : null;
+  }
+  const trimmedDisk = currentDiskContent.replace(/\n+$/, "");
+  const expectedSuffix = `
+
+${existingMetadata.instructions}`;
+  if (trimmedDisk.endsWith(expectedSuffix)) {
+    const userBase = trimmedDisk.slice(0, -expectedSuffix.length);
+    return userBase.length > 0 ? userBase : null;
+  }
+  if (trimmedDisk === existingMetadata.instructions) {
+    return null;
+  }
+  return currentDiskContent;
+}
+function resolveInstructionsFilePath({
+  homePath,
+  instructionsFile
+}) {
+  if (typeof homePath !== "string" || homePath.trim().length === 0) {
+    throw new Error("Invalid homePath: expected a non-empty string.");
+  }
+  if (!path2.posix.isAbsolute(homePath)) {
+    throw new Error(
+      `Invalid homePath ${JSON.stringify(homePath)}: expected an absolute POSIX path.`
+    );
+  }
+  if (typeof instructionsFile !== "string" || instructionsFile.trim().length === 0) {
+    throw new Error(
+      `Invalid instructionsFile ${JSON.stringify(instructionsFile)}: expected a relative POSIX path without traversal.`
+    );
+  }
+  const containsTraversal = instructionsFile.split(/[\\\/]/).some((segment) => segment === "..");
+  const normalizedInstructionsFile = path2.posix.normalize(
+    instructionsFile.trim()
+  );
+  const normalizedNoTrailingSlash = normalizedInstructionsFile.replace(
+    /\/+$/,
+    ""
+  );
+  if (instructionsFile.includes("\\") || path2.posix.isAbsolute(instructionsFile) || path2.win32.isAbsolute(instructionsFile) || containsTraversal || instructionsFile.endsWith("/") || instructionsFile.endsWith("\\") || instructionsFile.endsWith("/.") || instructionsFile.endsWith("/..") || normalizedNoTrailingSlash === "" || normalizedNoTrailingSlash === "." || normalizedInstructionsFile.startsWith("../") || normalizedInstructionsFile.includes("/../") || normalizedInstructionsFile.endsWith("/..")) {
+    throw new Error(
+      `Invalid instructionsFile ${JSON.stringify(instructionsFile)}: expected a relative POSIX path without traversal.`
+    );
+  }
+  const targetPath = path2.posix.join(homePath, normalizedNoTrailingSlash);
+  const relative = path2.posix.relative(homePath, targetPath);
+  if (relative === "" || relative.startsWith("..") || path2.posix.isAbsolute(relative)) {
+    throw new Error(
+      `Invalid instructionsFile ${JSON.stringify(instructionsFile)}: must be a subpath within homePath ${JSON.stringify(homePath)}.`
+    );
+  }
+  const dir = path2.posix.dirname(targetPath);
+  const base = path2.posix.basename(targetPath);
+  const metadataPath = path2.posix.join(
+    dir,
+    `.${base}.ai-sdk-harness-instructions.json`
+  );
+  return { targetPath, metadataPath };
+}
+async function readInstructionsMetadata({
+  sandbox,
+  metadataPath,
+  abortSignal
+}) {
+  const content = await sandbox.readTextFile({
+    path: metadataPath,
+    abortSignal
+  });
+  if (content == null) return void 0;
+  const parsed = await safeParseJSON3({ text: content });
+  if (!parsed.success || !isInstructionsMetadata(parsed.value)) {
+    throw new Error(
+      `Invalid AI SDK harness instructions metadata: ${metadataPath}`
+    );
+  }
+  return parsed.value;
+}
+function isInstructionsMetadata(value) {
+  if (value == null || typeof value !== "object" || Array.isArray(value)) {
+    return false;
+  }
+  const candidate = value;
+  return candidate.version === INSTRUCTIONS_METADATA_VERSION && (candidate.originalContent === null || typeof candidate.originalContent === "string") && typeof candidate.instructions === "string" && typeof candidate.appliedContent === "string";
+}
+async function writeInstructionsMetadata({
+  sandbox,
+  metadataPath,
+  metadata,
+  abortSignal
+}) {
+  const temporaryPath = `${metadataPath}.tmp`;
+  await sandbox.writeTextFile({
+    path: temporaryPath,
+    content: `${JSON.stringify(metadata, null, 2)}
+`,
+    abortSignal
+  });
+  await runSandboxCommand({
+    sandbox,
+    command: `mv -f ${shellQuote(temporaryPath)} ${shellQuote(metadataPath)}`,
+    abortSignal,
+    errorMessage: `Failed to update instructions metadata: ${metadataPath}`
+  });
+}
+async function removeMetadataFile({
+  sandbox,
+  metadataPath,
+  abortSignal
+}) {
+  await runSandboxCommand({
+    sandbox,
+    command: `rm -f -- ${shellQuote(metadataPath)}`,
+    abortSignal,
+    errorMessage: `Failed to remove instructions metadata: ${metadataPath}`
+  });
+}
+async function removeTargetFile({
+  sandbox,
+  targetPath,
+  abortSignal
+}) {
+  await runSandboxCommand({
+    sandbox,
+    command: `rm -f -- ${shellQuote(targetPath)}`,
+    abortSignal,
+    errorMessage: `Failed to remove instructions file: ${targetPath}`
+  });
+}
+async function runSandboxCommand({
+  sandbox,
+  command,
+  abortSignal,
+  errorMessage
+}) {
+  const result = await sandbox.run({ command, abortSignal });
+  if (result.exitCode !== 0) {
+    throw new Error(
+      `${errorMessage} (exit ${result.exitCode})${result.stderr ? `: ${result.stderr}` : ""}`
+    );
+  }
+}
+
+// src/utils/write-skills.ts
+import { createHash } from "crypto";
+import path3 from "path";
+import {
+  safeParseJSON as safeParseJSON4
+} from "@ai-sdk/provider-utils";
 var SKILLS_MANIFEST_FILENAME = ".ai-sdk-harness-skills.json";
 var SKILLS_MANIFEST_VERSION = 1;
 var SAFE_MANIFEST_SKILL_NAME = /^[A-Za-z0-9._-]+$/;
 async function writeSkills({
   sandbox,
-  rootDir,
+  homePath,
+  skillsDir,
   skills,
   abortSignal,
   skillNamePattern = /^[A-Za-z0-9._-]+$/,
@@ -594,6 +861,7 @@ async function writeSkills({
   trailingNewline = false
 }) {
   var _a;
+  const rootDir = resolveSkillsRootDir({ homePath, skillsDir });
   const projectedSkills = skills.map(
     (skill) => projectSkill({
       skill,
@@ -605,7 +873,7 @@ async function writeSkills({
     })
   ).sort((a, b) => a.name.localeCompare(b.name));
   assertUniqueSkillNames(projectedSkills);
-  const manifestPath = path2.posix.join(rootDir, SKILLS_MANIFEST_FILENAME);
+  const manifestPath = path3.posix.join(rootDir, SKILLS_MANIFEST_FILENAME);
   const existingManifest = await readSkillsManifest({
     sandbox,
     manifestPath,
@@ -729,7 +997,7 @@ async function ensureSkillsDirectory({
   rootDir,
   abortSignal
 }) {
-  await runSandboxCommand({
+  await runSandboxCommand2({
     sandbox,
     command: `mkdir -p ${shellQuote(rootDir)}`,
     abortSignal,
@@ -788,7 +1056,7 @@ async function readSkillsManifest({
     abortSignal
   });
   if (content == null) return void 0;
-  const parsed = await safeParseJSON3({ text: content });
+  const parsed = await safeParseJSON4({ text: content });
   if (!parsed.success || !isSkillsManifest(parsed.value)) {
     throw new Error(`Invalid AI SDK harness skills manifest: ${manifestPath}`);
   }
@@ -828,7 +1096,7 @@ async function writeSkillsManifest({
 `,
     abortSignal
   });
-  await runSandboxCommand({
+  await runSandboxCommand2({
     sandbox,
     command: `mv -f ${shellQuote(temporaryPath)} ${shellQuote(manifestPath)}`,
     abortSignal,
@@ -841,7 +1109,7 @@ async function assertSkillDirectoryAvailable({
   skillName,
   abortSignal
 }) {
-  const skillDir = path2.posix.join(rootDir, skillName);
+  const skillDir = path3.posix.join(rootDir, skillName);
   const result = await sandbox.run({
     command: `test ! -e ${shellQuote(skillDir)}`,
     abortSignal
@@ -859,8 +1127,8 @@ async function removeSkillDirectories({
   abortSignal
 }) {
   if (skillNames.length === 0) return;
-  const directories = Array.from(new Set(skillNames)).sort((a, b) => a.localeCompare(b)).map((name) => shellQuote(path2.posix.join(rootDir, name))).join(" ");
-  await runSandboxCommand({
+  const directories = Array.from(new Set(skillNames)).sort((a, b) => a.localeCompare(b)).map((name) => shellQuote(path3.posix.join(rootDir, name))).join(" ");
+  await runSandboxCommand2({
     sandbox,
     command: `rm -rf -- ${directories}`,
     abortSignal,
@@ -874,17 +1142,17 @@ async function writeProjectedSkills({
   abortSignal
 }) {
   for (const skill of skills) {
-    const skillDir = path2.posix.join(rootDir, skill.name);
+    const skillDir = path3.posix.join(rootDir, skill.name);
     for (const file of skill.files) {
       await sandbox.writeTextFile({
-        path: path2.posix.join(skillDir, file.path),
+        path: path3.posix.join(skillDir, file.path),
         content: file.content,
         abortSignal
       });
     }
   }
 }
-async function runSandboxCommand({
+async function runSandboxCommand2({
   sandbox,
   command,
   abortSignal,
@@ -931,8 +1199,8 @@ function normalizeSkillFilePath({
   message
 }) {
   var _a;
-  const normalized = mode === "strip-leading-slashes" ? filePath.replace(/^\/+/, "") : path2.posix.normalize(filePath);
-  const invalid = normalized === "" || mode === "relative" && normalized === "." || normalized.startsWith("../") || normalized.includes("/../") || normalized.endsWith("/..") || mode === "relative" && path2.posix.isAbsolute(normalized);
+  const normalized = mode === "strip-leading-slashes" ? filePath.replace(/^\/+/, "") : path3.posix.normalize(filePath);
+  const invalid = normalized === "" || mode === "relative" && normalized === "." || normalized.startsWith("../") || normalized.includes("/../") || normalized.endsWith("/..") || mode === "relative" && path3.posix.isAbsolute(normalized);
   if (invalid) {
     throw new Error(
       (_a = message == null ? void 0 : message({ skillName: skillName != null ? skillName : "", filePath })) != null ? _a : `Invalid skill file path for ${skillName}: ${filePath}`
@@ -953,10 +1221,44 @@ ${skill.content}`;
   return trailingNewline ? `${content}
 ` : content;
 }
+function resolveSkillsRootDir({
+  homePath,
+  skillsDir
+}) {
+  if (typeof homePath !== "string" || homePath.trim().length === 0) {
+    throw new Error("Invalid homePath: expected a non-empty string.");
+  }
+  if (!path3.posix.isAbsolute(homePath)) {
+    throw new Error(
+      `Invalid homePath ${JSON.stringify(homePath)}: expected an absolute POSIX path.`
+    );
+  }
+  if (typeof skillsDir !== "string" || skillsDir.trim().length === 0) {
+    throw new Error(
+      `Invalid skillsDir ${JSON.stringify(skillsDir)}: expected a relative POSIX path without traversal.`
+    );
+  }
+  const containsTraversal = skillsDir.split(/[\\\/]/).some((segment) => segment === "..");
+  const normalizedSkillsDir = path3.posix.normalize(skillsDir.trim());
+  const normalizedNoTrailingSlash = normalizedSkillsDir.replace(/\/+$/, "");
+  if (skillsDir.includes("\\") || path3.posix.isAbsolute(skillsDir) || path3.win32.isAbsolute(skillsDir) || containsTraversal || normalizedNoTrailingSlash === "" || normalizedNoTrailingSlash === "." || normalizedSkillsDir.startsWith("../") || normalizedSkillsDir.includes("/../") || normalizedSkillsDir.endsWith("/..")) {
+    throw new Error(
+      `Invalid skillsDir ${JSON.stringify(skillsDir)}: expected a relative POSIX path without traversal.`
+    );
+  }
+  const rootDir = path3.posix.join(homePath, normalizedNoTrailingSlash);
+  const relative = path3.posix.relative(homePath, rootDir);
+  if (relative === "" || relative.startsWith("..") || path3.posix.isAbsolute(relative)) {
+    throw new Error(
+      `Invalid skillsDir ${JSON.stringify(skillsDir)}: must be a subpath within homePath ${JSON.stringify(homePath)}.`
+    );
+  }
+  return rootDir;
+}
 
 // src/utils/bridge-ready.ts
 import {
-  safeParseJSON as safeParseJSON4
+  safeParseJSON as safeParseJSON5
 } from "@ai-sdk/provider-utils";
 import { z as z4 } from "zod/v4";
 
@@ -1448,7 +1750,7 @@ async function waitForBridgeReady({
       if (value === void 0) continue;
       for (const line of decoder.push(value)) {
         pushTail({ lines: stdoutTail, line });
-        const parsed = await safeParseJSON4({
+        const parsed = await safeParseJSON5({
           text: line,
           schema: harnessV1BridgeReadySchema
         });
@@ -1485,7 +1787,7 @@ async function readBridgeMetaReady({
     })
   ).catch(() => null);
   if (raw == null) return void 0;
-  const parsed = await safeParseJSON4({ text: raw, schema: bridgeMetaSchema });
+  const parsed = await safeParseJSON5({ text: raw, schema: bridgeMetaSchema });
   if (!parsed.success) return void 0;
   if (parsed.value.type !== bridgeType) return void 0;
   if (parsed.value.state !== "waiting") return void 0;
@@ -1782,6 +2084,7 @@ export {
   waitForBridgeReady,
   warnCredentialBrokeringUnavailable,
   withBridgeToken,
+  writeInstructions,
   writeSkills
 };
 //# sourceMappingURL=index.js.map