@ai-sdk/harness 1.0.100 → 1.0.102

package/src/bridge/index.ts

@@ -11,6 +11,7 @@ import { appendFile, mkdir, writeFile } from 'node:fs/promises';
 import { existsSync, readFileSync } from 'node:fs';
 import { randomUUID } from 'node:crypto';
 import { env as procEnv, pid, stdout } from 'node:process';
+import type { ToolResultPart } from '@ai-sdk/provider-utils';
 import { WebSocketServer, type WebSocket } from 'ws';
 
 export { HarnessBridgeCapabilityUnsupportedError } from './harness-bridge-capability-unsupported-error';
@@ -244,8 +245,21 @@ export interface BridgeTurn {
    * itself (via {@link emit}) using the same `toolCallId`.
    */
   requestToolResult(
-    toolCallId: string,
-  ): Promise<{ output: unknown; isError?: boolean }>;
+    input:
+      | string
+      | {
+          toolCallId: string;
+          matches?: (result: {
+            output: unknown;
+            isError?: boolean;
+            toolResult?: ToolResultPart;
+          }) => boolean;
+        },
+  ): Promise<{
+    output: unknown;
+    isError?: boolean;
+    toolResult?: ToolResultPart;
+  }>;
 
   /**
    * Register interest in a host approval decision and resolve when the matching
@@ -342,6 +356,7 @@ type InboundControl =
       toolCallId: string;
       output: unknown;
       isError?: boolean;
+      toolResult?: ToolResultPart;
     }
   | {
       type: 'tool-approval-response';
@@ -506,8 +521,27 @@ export async function runBridge<TStart extends { type: 'start' }>(
 
   const pendingToolResults = new Map<
     string,
-    (output: { output: unknown; isError?: boolean }) => void
+    {
+      resolve: (output: {
+        output: unknown;
+        isError?: boolean;
+        toolResult?: ToolResultPart;
+      }) => void;
+      matches?: (output: {
+        output: unknown;
+        isError?: boolean;
+        toolResult?: ToolResultPart;
+      }) => boolean;
+    }
   >();
+  const bufferedToolResults: Array<{
+    toolCallId: string;
+    result: {
+      output: unknown;
+      isError?: boolean;
+      toolResult?: ToolResultPart;
+    };
+  }> = [];
   const pendingToolApprovals = new Map<
     string,
     (response: { approved: boolean; reason?: string }) => void
@@ -749,10 +783,28 @@ export async function runBridge<TStart extends { type: 'start' }>(
         const userMessages = createBridgeUserMessageQueue({ respond: emit });
         const turn: BridgeTurn = {
           emit,
-          requestToolResult: toolCallId =>
-            new Promise(resolve => {
-              pendingToolResults.set(toolCallId, resolve);
-            }),
+          requestToolResult: requestInput => {
+            const request =
+              typeof requestInput === 'string'
+                ? { toolCallId: requestInput }
+                : requestInput;
+            const bufferedIndex = bufferedToolResults.findIndex(
+              buffered =>
+                buffered.toolCallId === request.toolCallId ||
+                request.matches?.(buffered.result) === true,
+            );
+            if (bufferedIndex >= 0) {
+              return Promise.resolve(
+                bufferedToolResults.splice(bufferedIndex, 1)[0].result,
+              );
+            }
+            return new Promise(resolve => {
+              pendingToolResults.set(request.toolCallId, {
+                resolve,
+                matches: request.matches,
+              });
+            });
+          },
           requestToolApproval: approvalId =>
             new Promise(resolve => {
               pendingToolApprovals.set(approvalId, resolve);
@@ -800,10 +852,29 @@ export async function runBridge<TStart extends { type: 'start' }>(
         return;
       }
       case 'tool-result': {
-        const resolver = pendingToolResults.get(msg.toolCallId);
-        if (resolver) {
-          pendingToolResults.delete(msg.toolCallId);
-          resolver({ output: msg.output, isError: msg.isError });
+        const result = {
+          output: msg.output,
+          isError: msg.isError,
+          toolResult: msg.toolResult,
+        };
+        const exactPending = pendingToolResults.get(msg.toolCallId);
+        const matchingPending =
+          exactPending == null
+            ? Array.from(pendingToolResults.entries()).find(
+                ([, pending]) => pending.matches?.(result) === true,
+              )
+            : undefined;
+        const pending = exactPending ?? matchingPending?.[1];
+        const pendingId =
+          exactPending != null ? msg.toolCallId : matchingPending?.[0];
+        if (pending != null && pendingId != null) {
+          pendingToolResults.delete(pendingId);
+          pending.resolve(result);
+        } else {
+          bufferedToolResults.push({
+            toolCallId: msg.toolCallId,
+            result,
+          });
         }
         return;
       }

package/src/utils/index.ts

@@ -26,6 +26,11 @@ export {
 } from './sandbox-credential-brokering';
 export { resolveSandboxHomeDir } from './sandbox-home-dir';
 export { shellQuote } from './shell-quote';
+export {
+  writeInstructions,
+  type WriteInstructionsOptions,
+  type WriteInstructionsResult,
+} from './write-instructions';
 export {
   writeSkills,
   type SkillFilePathMode,

package/src/utils/write-instructions.ts

@@ -0,0 +1,373 @@
+import path from 'node:path';
+import {
+  safeParseJSON,
+  type Experimental_SandboxSession,
+} from '@ai-sdk/provider-utils';
+import { shellQuote } from './shell-quote';
+
+const INSTRUCTIONS_METADATA_VERSION = 1;
+
+export type WriteInstructionsOptions = {
+  sandbox: Experimental_SandboxSession;
+  homePath: string;
+  instructionsFile: string;
+  instructions?: string;
+  abortSignal?: AbortSignal;
+};
+
+export type WriteInstructionsResult = {
+  changed: boolean;
+  filePath: string;
+};
+
+type InstructionsMetadata = {
+  readonly version: typeof INSTRUCTIONS_METADATA_VERSION;
+  readonly originalContent: string | null;
+  readonly instructions: string;
+  readonly appliedContent: string;
+};
+
+export async function writeInstructions({
+  sandbox,
+  homePath,
+  instructionsFile,
+  instructions,
+  abortSignal,
+}: WriteInstructionsOptions): Promise<WriteInstructionsResult> {
+  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+$/, '')}\n\n${trimmedInstructions}\n`
+        : `${trimmedInstructions}\n`;
+
+    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+$/, '')}\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,
+}: {
+  currentDiskContent: string | null;
+  existingMetadata: InstructionsMetadata | undefined;
+}): string | null {
+  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 = `\n\n${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 existingMetadata.originalContent ?? currentDiskContent;
+}
+
+function deriveRestoredContent({
+  currentDiskContent,
+  existingMetadata,
+}: {
+  currentDiskContent: string | null;
+  existingMetadata: InstructionsMetadata;
+}): string | null {
+  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 = `\n\n${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,
+}: {
+  homePath: string;
+  instructionsFile: string;
+}): { targetPath: string; metadataPath: string } {
+  if (typeof homePath !== 'string' || homePath.trim().length === 0) {
+    throw new Error('Invalid homePath: expected a non-empty string.');
+  }
+  if (!path.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 = path.posix.normalize(
+    instructionsFile.trim(),
+  );
+  const normalizedNoTrailingSlash = normalizedInstructionsFile.replace(
+    /\/+$/,
+    '',
+  );
+  if (
+    instructionsFile.includes('\\') ||
+    path.posix.isAbsolute(instructionsFile) ||
+    path.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 = path.posix.join(homePath, normalizedNoTrailingSlash);
+  const relative = path.posix.relative(homePath, targetPath);
+  if (
+    relative === '' ||
+    relative.startsWith('..') ||
+    path.posix.isAbsolute(relative)
+  ) {
+    throw new Error(
+      `Invalid instructionsFile ${JSON.stringify(instructionsFile)}: must be a subpath within homePath ${JSON.stringify(homePath)}.`,
+    );
+  }
+
+  const dir = path.posix.dirname(targetPath);
+  const base = path.posix.basename(targetPath);
+  const metadataPath = path.posix.join(
+    dir,
+    `.${base}.ai-sdk-harness-instructions.json`,
+  );
+
+  return { targetPath, metadataPath };
+}
+
+async function readInstructionsMetadata({
+  sandbox,
+  metadataPath,
+  abortSignal,
+}: {
+  sandbox: Experimental_SandboxSession;
+  metadataPath: string;
+  abortSignal?: AbortSignal;
+}): Promise<InstructionsMetadata | undefined> {
+  const content = await sandbox.readTextFile({
+    path: metadataPath,
+    abortSignal,
+  });
+  if (content == null) return undefined;
+  const parsed = await safeParseJSON({ text: content });
+  if (!parsed.success || !isInstructionsMetadata(parsed.value)) {
+    throw new Error(
+      `Invalid AI SDK harness instructions metadata: ${metadataPath}`,
+    );
+  }
+  return parsed.value;
+}
+
+function isInstructionsMetadata(value: unknown): value is InstructionsMetadata {
+  if (value == null || typeof value !== 'object' || Array.isArray(value)) {
+    return false;
+  }
+  const candidate = value as Record<string, unknown>;
+  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,
+}: {
+  sandbox: Experimental_SandboxSession;
+  metadataPath: string;
+  metadata: InstructionsMetadata;
+  abortSignal?: AbortSignal;
+}): Promise<void> {
+  const temporaryPath = `${metadataPath}.tmp`;
+  await sandbox.writeTextFile({
+    path: temporaryPath,
+    content: `${JSON.stringify(metadata, null, 2)}\n`,
+    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,
+}: {
+  sandbox: Experimental_SandboxSession;
+  metadataPath: string;
+  abortSignal?: AbortSignal;
+}): Promise<void> {
+  await runSandboxCommand({
+    sandbox,
+    command: `rm -f -- ${shellQuote(metadataPath)}`,
+    abortSignal,
+    errorMessage: `Failed to remove instructions metadata: ${metadataPath}`,
+  });
+}
+
+async function removeTargetFile({
+  sandbox,
+  targetPath,
+  abortSignal,
+}: {
+  sandbox: Experimental_SandboxSession;
+  targetPath: string;
+  abortSignal?: AbortSignal;
+}): Promise<void> {
+  await runSandboxCommand({
+    sandbox,
+    command: `rm -f -- ${shellQuote(targetPath)}`,
+    abortSignal,
+    errorMessage: `Failed to remove instructions file: ${targetPath}`,
+  });
+}
+
+async function runSandboxCommand({
+  sandbox,
+  command,
+  abortSignal,
+  errorMessage,
+}: {
+  sandbox: Experimental_SandboxSession;
+  command: string;
+  abortSignal?: AbortSignal;
+  errorMessage: string;
+}): Promise<void> {
+  const result = await sandbox.run({ command, abortSignal });
+  if (result.exitCode !== 0) {
+    throw new Error(
+      `${errorMessage} (exit ${result.exitCode})${result.stderr ? `: ${result.stderr}` : ''}`,
+    );
+  }
+}

package/src/utils/write-skills.ts

@@ -15,7 +15,8 @@ export type SkillFilePathMode = 'relative' | 'strip-leading-slashes';
 
 export type WriteSkillsOptions = {
   sandbox: Experimental_SandboxSession;
-  rootDir: string;
+  homePath: string;
+  skillsDir: string;
   skills: ReadonlyArray<HarnessV1Skill>;
   abortSignal?: AbortSignal;
   skillNamePattern?: RegExp;
@@ -57,7 +58,8 @@ type SkillsManifest = {
 
 export async function writeSkills({
   sandbox,
-  rootDir,
+  homePath,
+  skillsDir,
   skills,
   abortSignal,
   skillNamePattern = /^[A-Za-z0-9._-]+$/,
@@ -67,6 +69,7 @@ export async function writeSkills({
     `Invalid skill file path for ${skillName}: ${filePath}`,
   trailingNewline = false,
 }: WriteSkillsOptions): Promise<WriteSkillsResult> {
+  const rootDir = resolveSkillsRootDir({ homePath, skillsDir });
   const projectedSkills = skills
     .map(skill =>
       projectSkill({
@@ -526,3 +529,57 @@ function renderSkillFile({
   const content = `---\nname: ${skill.name}\ndescription: ${skill.description}\n---\n\n${skill.content}`;
   return trailingNewline ? `${content}\n` : content;
 }
+
+function resolveSkillsRootDir({
+  homePath,
+  skillsDir,
+}: {
+  homePath: string;
+  skillsDir: string;
+}): string {
+  if (typeof homePath !== 'string' || homePath.trim().length === 0) {
+    throw new Error('Invalid homePath: expected a non-empty string.');
+  }
+  if (!path.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 = path.posix.normalize(skillsDir.trim());
+  const normalizedNoTrailingSlash = normalizedSkillsDir.replace(/\/+$/, '');
+  if (
+    skillsDir.includes('\\') ||
+    path.posix.isAbsolute(skillsDir) ||
+    path.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 = path.posix.join(homePath, normalizedNoTrailingSlash);
+  const relative = path.posix.relative(homePath, rootDir);
+  if (
+    relative === '' ||
+    relative.startsWith('..') ||
+    path.posix.isAbsolute(relative)
+  ) {
+    throw new Error(
+      `Invalid skillsDir ${JSON.stringify(skillsDir)}: must be a subpath within homePath ${JSON.stringify(homePath)}.`,
+    );
+  }
+  return rootDir;
+}

package/src/v1/harness-v1-bridge-protocol.ts

@@ -295,6 +295,7 @@ export const harnessV1BridgeToolResultInboundSchema = z.object({
   toolCallId: z.string(),
   output: z.unknown(),
   isError: z.boolean().optional(),
+  toolResult: z.unknown().optional(),
 });
 
 export const harnessV1BridgeToolApprovalResponseInboundSchema = z.object({

package/src/v1/harness-v1-builtin-tool.ts

@@ -1,5 +1,6 @@
 import { tool, type FlexibleSchema, type Tool } from '@ai-sdk/provider-utils';
 import { z } from 'zod/v4';
+import { harnessV1QuestionsTool } from './harness-v1-questions-tool';
 
 /**
  * Cross-harness vocabulary of common built-in tool names with their baseline
@@ -50,6 +51,7 @@ export const HARNESS_V1_BUILTIN_TOOLS = {
     inputSchema: z.object({ query: z.string() }),
     outputSchema: z.unknown(),
   }),
+  askUserQuestions: harnessV1QuestionsTool,
 } as const;
 
 export type HarnessV1BuiltinToolName = keyof typeof HARNESS_V1_BUILTIN_TOOLS;

package/src/v1/harness-v1-lifecycle-state.ts

@@ -1,4 +1,5 @@
 import type { JSONValue } from '@ai-sdk/provider';
+import type { ProviderOptions } from '@ai-sdk/provider-utils';
 import type { HarnessV1Skill } from './harness-v1-skill';
 import type { HarnessV1ToolSpec } from './harness-v1-tool-spec';
 
@@ -16,6 +17,7 @@ export type HarnessV1PendingToolResult = {
   readonly toolCallId: string;
   readonly toolName: string;
   readonly input: string;
+  readonly providerOptions?: ProviderOptions;
 };
 
 /**

package/src/v1/harness-v1-prompt-control.ts

@@ -1,3 +1,5 @@
+import type { ToolResultPart } from '@ai-sdk/provider-utils';
+
 /**
  * Bidirectional control surface returned by `doPromptTurn`.
  *
@@ -16,6 +18,7 @@ export type HarnessV1PromptControl = {
     toolCallId: string;
     output: unknown;
     isError?: boolean;
+    toolResult?: ToolResultPart;
   }): PromiseLike<void>;
 
   /**