@ai-sdk/harness 0.0.0-6b196531-20260710185421

package/src/agent/internal/sandbox-bootstrap.ts

@@ -0,0 +1,266 @@
+import { posix } from 'node:path';
+import type { Experimental_SandboxSession as SandboxSession } from '@ai-sdk/provider-utils';
+import type { HarnessV1Bootstrap } from '../../v1';
+import type { HarnessAgentSandboxConfig } from '../harness-agent-settings';
+import { applyBootstrapRecipe, hashHarnessBootstrap } from './bootstrap-recipe';
+
+const SANDBOX_BOOTSTRAP_IDENTITY_VERSION = 1;
+
+type SandboxBootstrapSettings = Omit<HarnessAgentSandboxConfig, 'onSession'>;
+
+export type SandboxBootstrapPlan = {
+  readonly recipe?: HarnessV1Bootstrap;
+  readonly recipeIdentity?: string;
+  readonly identity?: string;
+  readonly workDir?: string;
+  readonly onFirstCreate?: (
+    session: SandboxSession,
+    opts: { abortSignal?: AbortSignal },
+  ) => Promise<void>;
+};
+
+export function validateSandboxBootstrapSettings(
+  settings: SandboxBootstrapSettings,
+): void {
+  if ((settings.onBootstrap == null) !== (settings.bootstrapHash == null)) {
+    throw new Error(
+      'HarnessAgent: `sandboxConfig.onBootstrap` and `sandboxConfig.bootstrapHash` must be provided together.',
+    );
+  }
+
+  if (settings.workDir != null) {
+    normalizeSandboxWorkDir(settings.workDir);
+  }
+}
+
+export function normalizeSandboxWorkDir(workDir: string): string {
+  if (workDir.length === 0) {
+    throw new Error('HarnessAgent: `sandboxConfig.workDir` must not be empty.');
+  }
+  if (workDir.includes('\0')) {
+    throw new Error(
+      'HarnessAgent: `sandboxConfig.workDir` must not contain NUL.',
+    );
+  }
+  if (workDir.includes('\\')) {
+    throw new Error(
+      'HarnessAgent: `sandboxConfig.workDir` must use POSIX path separators.',
+    );
+  }
+  if (posix.isAbsolute(workDir)) {
+    throw new Error('HarnessAgent: `sandboxConfig.workDir` must be relative.');
+  }
+
+  const normalized = posix.normalize(workDir);
+  if (
+    normalized === '.' ||
+    normalized === '..' ||
+    normalized.startsWith('../')
+  ) {
+    throw new Error(
+      'HarnessAgent: `sandboxConfig.workDir` must stay inside the sandbox default working directory.',
+    );
+  }
+  return normalized;
+}
+
+export function resolveSessionWorkDir({
+  defaultWorkingDirectory,
+  harnessId,
+  sessionId,
+  workDir,
+}: {
+  readonly defaultWorkingDirectory: string;
+  readonly harnessId: string;
+  readonly sessionId: string;
+  readonly workDir?: string;
+}): string {
+  return joinSandboxPath({
+    base: defaultWorkingDirectory,
+    path: workDir ?? `${harnessId}-${sessionId}`,
+  });
+}
+
+export async function createSandboxBootstrapPlan({
+  recipe,
+  settings,
+}: {
+  readonly recipe?: HarnessV1Bootstrap;
+  readonly settings: SandboxBootstrapSettings;
+}): Promise<SandboxBootstrapPlan> {
+  const workDir =
+    settings.workDir == null
+      ? undefined
+      : normalizeSandboxWorkDir(settings.workDir);
+  const recipeIdentity =
+    recipe == null ? undefined : await hashHarnessBootstrap(recipe);
+  const hasCallerBootstrap = settings.onBootstrap != null;
+  const needsCombinedIdentity =
+    hasCallerBootstrap || (recipeIdentity != null && workDir != null);
+  const identity =
+    needsCombinedIdentity && (recipeIdentity != null || hasCallerBootstrap)
+      ? await hashSandboxBootstrapIdentity({
+          recipeIdentity,
+          bootstrapHash: settings.bootstrapHash,
+          workDir,
+        })
+      : recipeIdentity;
+
+  return {
+    ...(recipe != null ? { recipe } : {}),
+    ...(recipeIdentity != null ? { recipeIdentity } : {}),
+    ...(identity != null ? { identity } : {}),
+    ...(workDir != null ? { workDir } : {}),
+    ...(recipe != null || settings.onBootstrap != null
+      ? {
+          onFirstCreate: (session, opts) =>
+            runSandboxBootstrap({
+              session,
+              recipe,
+              recipeIdentity,
+              workDir,
+              onBootstrap: settings.onBootstrap,
+              abortSignal: opts.abortSignal,
+            }),
+        }
+      : {}),
+  };
+}
+
+export async function runSandboxBootstrap({
+  session,
+  recipe,
+  recipeIdentity,
+  workDir,
+  onBootstrap,
+  abortSignal,
+}: {
+  readonly session: SandboxSession;
+  readonly recipe?: HarnessV1Bootstrap;
+  readonly recipeIdentity?: string;
+  readonly workDir?: string;
+  readonly onBootstrap?: SandboxBootstrapSettings['onBootstrap'];
+  readonly abortSignal?: AbortSignal;
+}): Promise<void> {
+  if (recipe != null && recipeIdentity != null) {
+    await applyBootstrapRecipe(session, recipe, recipeIdentity, {
+      abortSignal,
+    });
+  }
+
+  if (onBootstrap == null) return;
+
+  const defaultWorkingDirectory = await resolveDefaultWorkingDirectory({
+    session,
+    abortSignal,
+  });
+  const bootstrapWorkDir =
+    workDir == null
+      ? defaultWorkingDirectory
+      : joinSandboxPath({
+          base: defaultWorkingDirectory,
+          path: workDir,
+        });
+
+  await ensureSandboxDirectory({
+    session,
+    workDir: bootstrapWorkDir,
+    abortSignal,
+  });
+  await onBootstrap({ session, workDir: bootstrapWorkDir, abortSignal });
+}
+
+export async function resolveDefaultWorkingDirectory({
+  session,
+  abortSignal,
+}: {
+  readonly session: SandboxSession;
+  readonly abortSignal?: AbortSignal;
+}): Promise<string> {
+  const result = await session.run({
+    command: 'pwd',
+    abortSignal,
+  });
+  if (result.exitCode !== 0) {
+    throw new Error(
+      `Failed to resolve sandbox default working directory (exit ${result.exitCode}): ${result.stderr || result.stdout}`,
+    );
+  }
+
+  const cwd = result.stdout.trim();
+  if (!posix.isAbsolute(cwd)) {
+    throw new Error(
+      `Failed to resolve sandbox default working directory: expected an absolute path, got ${JSON.stringify(cwd)}.`,
+    );
+  }
+  return cwd === '/' ? cwd : cwd.replace(/\/+$/, '');
+}
+
+export async function ensureSandboxDirectory({
+  session,
+  workDir,
+  abortSignal,
+}: {
+  readonly session: SandboxSession;
+  readonly workDir: string;
+  readonly abortSignal?: AbortSignal;
+}): Promise<void> {
+  const result = await session.run({
+    command: 'mkdir -p "$WORK_DIR"',
+    env: { WORK_DIR: workDir },
+    abortSignal,
+  });
+  if (result.exitCode !== 0) {
+    throw new Error(
+      `Failed to create sandbox work directory ${workDir} (exit ${result.exitCode}): ${result.stderr || result.stdout}`,
+    );
+  }
+}
+
+async function hashSandboxBootstrapIdentity({
+  recipeIdentity,
+  bootstrapHash,
+  workDir,
+}: {
+  readonly recipeIdentity?: string;
+  readonly bootstrapHash?: string;
+  readonly workDir?: string;
+}): Promise<string> {
+  const encoder = new TextEncoder();
+  const chunks: Uint8Array[] = [];
+  const pushString = (value: string) => {
+    chunks.push(encoder.encode(value));
+    chunks.push(encoder.encode('\0'));
+  };
+
+  pushString(String(SANDBOX_BOOTSTRAP_IDENTITY_VERSION));
+  pushString(recipeIdentity ?? '');
+  pushString(bootstrapHash ?? '');
+  pushString(workDir ?? '');
+
+  const totalLength = chunks.reduce((sum, chunk) => sum + chunk.length, 0);
+  const buffer = new Uint8Array(totalLength);
+  let offset = 0;
+  for (const chunk of chunks) {
+    buffer.set(chunk, offset);
+    offset += chunk.length;
+  }
+
+  const digest = await crypto.subtle.digest('SHA-256', buffer);
+  const bytes = new Uint8Array(digest);
+  let hex = '';
+  for (let i = 0; i < 8; i++) {
+    hex += bytes[i].toString(16).padStart(2, '0');
+  }
+  return hex;
+}
+
+function joinSandboxPath({
+  base,
+  path,
+}: {
+  readonly base: string;
+  readonly path: string;
+}): string {
+  return posix.join(base, path);
+}

package/src/agent/internal/strip-work-dir.ts

@@ -0,0 +1,68 @@
+import type { HarnessV1StreamPart } from '../../v1';
+
+/**
+ * Remove the session working-directory prefix from path-bearing fields of a
+ * stream event, returning a new event for display to consumers.
+ *
+ * Harness adapters run the agent in a per-session working directory that is a
+ * subdirectory of the sandbox root, and the agent's tools use absolute paths so
+ * they resolve against the root regardless of where the runtime process
+ * operates. The absolute paths are correct but noisy in a UI, so this strips
+ * the prefix for the consumer-facing projection only.
+ *
+ * Blanket prefix replacement (rather than rewriting known path fields) is used
+ * deliberately: `tool-result` results are free-form text — command stdout, grep
+ * output — where paths can appear anywhere and field-aware rewriting is
+ * impossible. The prefix is long and contains the session id, so it is unique
+ * enough that replacing every occurrence is safe.
+ */
+export function stripWorkDir(
+  part: HarnessV1StreamPart,
+  sessionWorkDir: string,
+): HarnessV1StreamPart {
+  if (sessionWorkDir.length === 0) return part;
+
+  switch (part.type) {
+    case 'tool-call':
+      return { ...part, input: stripString(part.input, sessionWorkDir) };
+    case 'tool-result':
+      return {
+        ...part,
+        result: stripDeep(part.result, sessionWorkDir) as Extract<
+          HarnessV1StreamPart,
+          { type: 'tool-result' }
+        >['result'],
+      };
+    case 'file-change':
+      return { ...part, path: stripString(part.path, sessionWorkDir) };
+    default:
+      return part;
+  }
+}
+
+/**
+ * Replace occurrences of the working directory in a string. A reference to the
+ * directory followed by a separator becomes workspace-relative
+ * (`/work/dir/src/a.ts` → `src/a.ts`); a bare reference to the directory itself
+ * becomes `.`.
+ */
+function stripString(value: string, workDir: string): string {
+  return value.split(`${workDir}/`).join('').split(workDir).join('.');
+}
+
+/**
+ * Recursively strip the working directory from every string nested in an
+ * arbitrary JSON-like value. Non-string leaves are returned unchanged.
+ */
+function stripDeep(value: unknown, workDir: string): unknown {
+  if (typeof value === 'string') return stripString(value, workDir);
+  if (Array.isArray(value)) return value.map(item => stripDeep(item, workDir));
+  if (value !== null && typeof value === 'object') {
+    const out: Record<string, unknown> = {};
+    for (const [key, val] of Object.entries(value)) {
+      out[key] = stripDeep(val, workDir);
+    }
+    return out;
+  }
+  return value;
+}

package/src/agent/internal/to-harness-stream.ts

@@ -0,0 +1,75 @@
+import type { HarnessV1PromptControl } from '../../v1/harness-v1-prompt-control';
+import type { HarnessV1StreamPart } from '../../v1/harness-v1-stream-part';
+
+/**
+ * Bridge an adapter's emit-based event surface into a pull-based
+ * `ReadableStream<HarnessV1StreamPart>`.
+ *
+ * Adapters implement `doPromptTurn` / `doContinueTurn` against an `emit` callback
+ * because that is the natural shape when wrapping an SDK that itself produces
+ * events. Consumers (notably `HarnessAgent`) prefer a stream because that is
+ * the idiomatic AI SDK shape. This helper converts the former into the latter
+ * and is agnostic to which turn entry point produced the control surface — the
+ * caller supplies an `invoke` thunk that wires `emit` into either method.
+ *
+ * Lifetime:
+ *   1. Calls `invoke(emit)` immediately (which runs `doPromptTurn`/`doContinueTurn`).
+ *   2. Every `emit(part)` becomes a stream chunk.
+ *   3. When `control.done` resolves, the stream closes — this includes a
+ *      graceful `doSuspendTurn`, which resolves `done` cleanly after draining.
+ *   4. When `control.done` rejects, an `{ type: 'error', error }` part is
+ *      enqueued and the stream is then closed normally. The rejection is
+ *      surfaced to consumers as a discriminated-union event rather than as
+ *      a stream error so iteration code does not need a separate try/catch
+ *      around the consumer loop.
+ *   5. The supplied `abortSignal` (if any) aborts the underlying turn and
+ *      closes the stream.
+ *
+ * The returned `control` is the same object the adapter produced and is
+ * intended for use by the consumer to submit tool results / approvals /
+ * user messages back into the in-flight turn.
+ */
+export async function toHarnessStream(options: {
+  invoke: (
+    emit: (event: HarnessV1StreamPart) => void,
+  ) => PromiseLike<HarnessV1PromptControl>;
+}): Promise<{
+  stream: ReadableStream<HarnessV1StreamPart>;
+  control: HarnessV1PromptControl;
+}> {
+  let controller!: ReadableStreamDefaultController<HarnessV1StreamPart>;
+  let closed = false;
+
+  const stream = new ReadableStream<HarnessV1StreamPart>({
+    start(c) {
+      controller = c;
+    },
+  });
+
+  const safeEnqueue = (part: HarnessV1StreamPart) => {
+    if (closed) return;
+    controller.enqueue(part);
+  };
+
+  const safeClose = () => {
+    if (closed) return;
+    closed = true;
+    controller.close();
+  };
+
+  const control = await options.invoke(safeEnqueue);
+
+  Promise.resolve(control.done)
+    .then(
+      () => safeClose(),
+      (err: unknown) => {
+        safeEnqueue({ type: 'error', error: err });
+        safeClose();
+      },
+    )
+    // Belt-and-suspenders: any throw inside the handlers themselves should
+    // not become an unhandled rejection.
+    .catch(() => {});
+
+  return { stream, control };
+}

package/src/agent/internal/tool-filtering.ts

@@ -0,0 +1,114 @@
+import { HarnessCapabilityUnsupportedError } from '../../errors/harness-capability-unsupported-error';
+import type { HarnessV1, HarnessV1BuiltinToolFiltering } from '../../v1';
+import { NoSuchToolError, type ActiveTools } from 'ai';
+import type { ToolSet } from '@ai-sdk/provider-utils';
+
+export type ResolvedHarnessAgentToolFiltering<TUserTools extends ToolSet> = {
+  readonly activeUserTools: TUserTools;
+  readonly builtinToolFiltering?: HarnessV1BuiltinToolFiltering;
+};
+
+export function resolveHarnessAgentToolFiltering<
+  TAllTools extends ToolSet,
+  TUserTools extends ToolSet,
+>(input: {
+  harness: HarnessV1;
+  userTools: TUserTools;
+  allTools: TAllTools;
+  activeTools: ActiveTools<TAllTools>;
+  inactiveTools: ActiveTools<TAllTools>;
+}): ResolvedHarnessAgentToolFiltering<TUserTools> {
+  if (input.activeTools !== undefined && input.inactiveTools !== undefined) {
+    throw new Error(
+      'HarnessAgent: pass either `activeTools` or `inactiveTools`, not both.',
+    );
+  }
+
+  const allToolNames = Object.keys(input.allTools);
+  const activeTools = dedupeToolNames({ toolNames: input.activeTools });
+  const inactiveTools = dedupeToolNames({ toolNames: input.inactiveTools });
+  validateToolNames({
+    requestedToolNames: activeTools ?? inactiveTools,
+    availableToolNames: allToolNames,
+  });
+
+  const userToolNames = Object.keys(input.userTools);
+  const activeUserToolNames =
+    activeTools != null
+      ? userToolNames.filter(name => activeTools.includes(name))
+      : inactiveTools != null
+        ? userToolNames.filter(name => !inactiveTools.includes(name))
+        : userToolNames;
+
+  const builtinToolNames = Object.keys(input.harness.builtinTools);
+  const disabledBuiltinToolNames =
+    activeTools != null
+      ? builtinToolNames.filter(name => !activeTools.includes(name))
+      : inactiveTools != null
+        ? builtinToolNames.filter(name => inactiveTools.includes(name))
+        : [];
+
+  const builtinToolFiltering =
+    disabledBuiltinToolNames.length > 0
+      ? activeTools != null
+        ? {
+            mode: 'allow' as const,
+            toolNames: builtinToolNames.filter(name =>
+              activeTools.includes(name),
+            ),
+          }
+        : { mode: 'deny' as const, toolNames: disabledBuiltinToolNames }
+      : undefined;
+
+  if (
+    builtinToolFiltering != null &&
+    input.harness.supportsBuiltinToolFiltering !== true &&
+    input.harness.supportsBuiltinToolApprovals !== true
+  ) {
+    throw new HarnessCapabilityUnsupportedError({
+      message: `Harness '${input.harness.harnessId}' does not support built-in tool filtering controls.`,
+      harnessId: input.harness.harnessId,
+    });
+  }
+
+  return {
+    activeUserTools: filterToolSet({
+      tools: input.userTools,
+      toolNames: activeUserToolNames,
+    }),
+    ...(builtinToolFiltering != null ? { builtinToolFiltering } : {}),
+  };
+}
+
+function dedupeToolNames(input: {
+  toolNames: ReadonlyArray<string> | undefined;
+}): ReadonlyArray<string> | undefined {
+  return input.toolNames == null
+    ? undefined
+    : Array.from(new Set(input.toolNames));
+}
+
+function validateToolNames(input: {
+  requestedToolNames: ReadonlyArray<string> | undefined;
+  availableToolNames: ReadonlyArray<string>;
+}): void {
+  if (input.requestedToolNames == null) return;
+  for (const toolName of input.requestedToolNames) {
+    if (!input.availableToolNames.includes(toolName)) {
+      throw new NoSuchToolError({
+        toolName,
+        availableTools: [...input.availableToolNames],
+      });
+    }
+  }
+}
+
+function filterToolSet<TUserTools extends ToolSet>(input: {
+  tools: TUserTools;
+  toolNames: ReadonlyArray<string>;
+}): TUserTools {
+  const allowed = new Set(input.toolNames);
+  return Object.fromEntries(
+    Object.entries(input.tools).filter(([name]) => allowed.has(name)),
+  ) as TUserTools;
+}