@ai-sdk/harness 1.0.11 → 1.0.13

package/src/agent/internal/run-prompt.ts

@@ -1,11 +1,14 @@
-import type {
-  HarnessV1,
-  HarnessV1PendingToolApproval,
-  HarnessV1Prompt,
-  HarnessV1PromptControl,
-  HarnessV1Session,
-  HarnessV1StreamPart,
-  HarnessV1ToolSpec,
+import {
+  getHarnessV1BuiltinToolFilteringDenialReason,
+  isHarnessV1BuiltinToolIncluded,
+  type HarnessV1,
+  type HarnessV1BuiltinToolFiltering,
+  type HarnessV1PendingToolApproval,
+  type HarnessV1Prompt,
+  type HarnessV1PromptControl,
+  type HarnessV1Session,
+  type HarnessV1StreamPart,
+  type HarnessV1ToolSpec,
 } from '../../v1';
 import { toHarnessStream } from './to-harness-stream';
 import {
@@ -60,7 +63,9 @@ export function runPrompt<
   prompt?: HarnessV1Prompt;
   instructions: string | undefined;
   tools: TOOLS;
+  activeTools?: ToolSet;
   toolSpecs: HarnessV1ToolSpec[];
+  builtinToolFiltering?: HarnessV1BuiltinToolFiltering | undefined;
   sandboxSession: SandboxSession;
   sessionWorkDir: string;
   runtimeContext: RUNTIME_CONTEXT;
@@ -89,6 +94,7 @@ export function runPrompt<
   const pendingToolApprovals = input.pendingToolApprovals ?? [];
   const onPendingToolApproval = input.onPendingToolApproval ?? (() => {});
   const onToolApprovalSettled = input.onToolApprovalSettled ?? (() => {});
+  const activeTools = input.activeTools ?? input.tools;
 
   const telemetry = createTurnTelemetry({
     telemetry: input.telemetry,
@@ -304,7 +310,7 @@ export function runPrompt<
 
       const outcome = await maybeExecuteHostTool({
         event: rawToolCall,
-        tools: input.tools,
+        tools: activeTools,
         sandboxSession: input.sandboxSession,
         abortSignal: input.abortSignal,
         control,
@@ -379,6 +385,39 @@ export function runPrompt<
           continue;
         }
 
+        if (displayValue.type === 'tool-approval-request') {
+          const toolCall = toolCallsByToolCallId.get(displayValue.toolCallId);
+          if (toolCall == null) {
+            throw new Error(
+              `Harness '${input.harness.harnessId}' emitted approval request '${displayValue.approvalId}' for unknown tool call '${displayValue.toolCallId}'.`,
+            );
+          }
+          const rawToolCall = rawToolCallsByToolCallId.get(
+            displayValue.toolCallId,
+          );
+          const toolName = rawToolCall?.toolName ?? toolCall.toolName;
+          if (
+            !isHarnessV1BuiltinToolIncluded({
+              toolName,
+              toolFiltering: input.builtinToolFiltering,
+            })
+          ) {
+            if (control.submitToolApproval == null) {
+              throw new Error(
+                `Harness '${input.harness.harnessId}' emitted a built-in tool approval request but does not support approval responses.`,
+              );
+            }
+            await control.submitToolApproval({
+              approvalId: displayValue.approvalId,
+              approved: false,
+              reason: getHarnessV1BuiltinToolFilteringDenialReason({
+                toolName,
+              }),
+            });
+            continue;
+          }
+        }
+
         // Forward to consumer as soon as possible.
         for (const part of translateStreamPart<TOOLS>(displayValue)) {
           result.enqueue(part);
@@ -514,6 +553,20 @@ export function runPrompt<
               `Harness '${input.harness.harnessId}' could not find parsed tool call '${toolCall.toolCallId}' for custom tool approval.`,
             );
           }
+          if (!hasTool({ tools: activeTools, toolName: toolCall.toolName })) {
+            const output = {
+              type: 'execution-denied',
+              reason: getHarnessV1BuiltinToolFilteringDenialReason({
+                toolName: toolCall.toolName,
+              }),
+            };
+            await control.submitToolResult({
+              toolCallId: toolCall.toolCallId,
+              output,
+            });
+            telemetry.toolEnd(toolCall.toolCallId, { ok: true, output });
+            continue;
+          }
           const customToolApprovalDecision = resolveCustomToolApproval({
             toolName: toolCall.toolName,
             toolApproval: input.toolApproval,
@@ -595,7 +648,7 @@ export function runPrompt<
           }
           const outcome = await maybeExecuteHostTool({
             event: toolCall,
-            tools: input.tools,
+            tools: activeTools,
             sandboxSession: input.sandboxSession,
             abortSignal: input.abortSignal,
             control,
@@ -694,6 +747,10 @@ type ToolCallTextStreamPart = {
   readonly title?: string;
 };
 
+function hasTool(input: { tools: ToolSet; toolName: string }): boolean {
+  return Object.prototype.hasOwnProperty.call(input.tools, input.toolName);
+}
+
 async function maybeExecuteHostTool<TOOLS extends ToolSet>(input: {
   event: { toolCallId: string; toolName: string; input: string };
   tools: TOOLS;

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;
+}

package/src/utils/index.ts

@@ -6,6 +6,13 @@ export {
 } from './sandbox-channel';
 export { classifyDiskLog, type DiskLogRecoveryMode } from './classify-disk-log';
 export { getAiGatewayAuthFromEnv } from './ai-gateway-auth';
+export { resolveSandboxHomeDir } from './sandbox-home-dir';
+export { shellQuote } from './shell-quote';
+export {
+  writeSkills,
+  type SkillFilePathMode,
+  type WriteSkillsOptions,
+} from './write-skills';
 export {
   markBridgeStarting,
   waitForBridgeReady,

package/src/utils/sandbox-home-dir.ts

@@ -0,0 +1,22 @@
+import path from 'node:path';
+import type { Experimental_SandboxSession } from '@ai-sdk/provider-utils';
+
+export 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;
+}

package/src/utils/shell-quote.ts

@@ -0,0 +1,3 @@
+export function shellQuote(value: string): string {
+  return `'${value.replace(/'/g, `'\\''`)}'`;
+}

package/src/utils/write-skills.ts

@@ -0,0 +1,141 @@
+import path from 'node:path';
+import type { Experimental_SandboxSession } from '@ai-sdk/provider-utils';
+import type { HarnessV1Skill } from '../v1';
+import { shellQuote } from './shell-quote';
+
+export type SkillFilePathMode = 'relative' | 'strip-leading-slashes';
+
+export type WriteSkillsOptions = {
+  sandbox: Experimental_SandboxSession;
+  rootDir: string;
+  skills: ReadonlyArray<HarnessV1Skill>;
+  abortSignal?: AbortSignal;
+  skillNamePattern?: RegExp;
+  invalidSkillNameMessage?: (input: { name: string }) => string;
+  filePathMode?: SkillFilePathMode;
+  invalidSkillFilePathMessage?: (input: {
+    skillName: string;
+    filePath: string;
+  }) => string;
+  trailingNewline?: boolean;
+};
+
+export async function writeSkills({
+  sandbox,
+  rootDir,
+  skills,
+  abortSignal,
+  skillNamePattern = /^[A-Za-z0-9._-]+$/,
+  invalidSkillNameMessage = ({ name }) => `Invalid skill name: ${name}`,
+  filePathMode = 'relative',
+  invalidSkillFilePathMessage = ({ skillName, filePath }) =>
+    `Invalid skill file path for ${skillName}: ${filePath}`,
+  trailingNewline = false,
+}: WriteSkillsOptions): Promise<void> {
+  for (const skill of skills) {
+    validateSkillName({
+      name: skill.name,
+      pattern: skillNamePattern,
+      message: invalidSkillNameMessage,
+    });
+    for (const file of skill.files ?? []) {
+      normalizeSkillFilePath({
+        skillName: skill.name,
+        filePath: file.path,
+        mode: filePathMode,
+        message: invalidSkillFilePathMessage,
+      });
+    }
+  }
+
+  await sandbox.run({
+    command: `mkdir -p ${shellQuote(rootDir)}`,
+    abortSignal,
+  });
+
+  for (const skill of skills) {
+    const name = validateSkillName({
+      name: skill.name,
+      pattern: skillNamePattern,
+      message: invalidSkillNameMessage,
+    });
+    const skillDir = path.posix.join(rootDir, name);
+    await sandbox.writeTextFile({
+      path: path.posix.join(skillDir, 'SKILL.md'),
+      content: renderSkillFile({ skill, trailingNewline }),
+      abortSignal,
+    });
+
+    for (const file of skill.files ?? []) {
+      const filePath = normalizeSkillFilePath({
+        skillName: skill.name,
+        filePath: file.path,
+        mode: filePathMode,
+        message: invalidSkillFilePathMessage,
+      });
+      await sandbox.writeTextFile({
+        path: path.posix.join(skillDir, filePath),
+        content: file.content,
+        abortSignal,
+      });
+    }
+  }
+}
+
+function validateSkillName({
+  name,
+  pattern,
+  message,
+}: {
+  name: string;
+  pattern: RegExp;
+  message?: (input: { name: string }) => string;
+}): string {
+  if (!pattern.test(name) || name === '.' || name === '..') {
+    throw new Error(message?.({ name }) ?? `Invalid skill name: ${name}`);
+  }
+  return name;
+}
+
+function normalizeSkillFilePath({
+  skillName,
+  filePath,
+  mode,
+  message,
+}: {
+  skillName?: string;
+  filePath: string;
+  mode: SkillFilePathMode;
+  message?: (input: { skillName: string; filePath: string }) => string;
+}): string {
+  const normalized =
+    mode === 'strip-leading-slashes'
+      ? filePath.replace(/^\/+/, '')
+      : path.posix.normalize(filePath);
+  const invalid =
+    normalized === '' ||
+    (mode === 'relative' && normalized === '.') ||
+    normalized.startsWith('../') ||
+    normalized.includes('/../') ||
+    normalized.endsWith('/..') ||
+    (mode === 'relative' && path.posix.isAbsolute(normalized));
+
+  if (invalid) {
+    throw new Error(
+      message?.({ skillName: skillName ?? '', filePath }) ??
+        `Invalid skill file path for ${skillName}: ${filePath}`,
+    );
+  }
+  return normalized;
+}
+
+function renderSkillFile({
+  skill,
+  trailingNewline,
+}: {
+  skill: HarnessV1Skill;
+  trailingNewline: boolean;
+}): string {
+  const content = `---\nname: ${skill.name}\ndescription: ${skill.description}\n---\n\n${skill.content}`;
+  return trailingNewline ? `${content}\n` : content;
+}

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

@@ -73,6 +73,20 @@ export const harnessV1BridgePermissionModeSchema = z.enum([
   'allow-all',
 ]);
 
+export const harnessV1BridgeBuiltinToolFilteringSchema = z.discriminatedUnion(
+  'mode',
+  [
+    z.object({
+      mode: z.literal('allow'),
+      toolNames: z.array(z.string()),
+    }),
+    z.object({
+      mode: z.literal('deny'),
+      toolNames: z.array(z.string()),
+    }),
+  ],
+);
+
 /**
  * Common fields of the inbound `start` message. Each adapter extends this with
  * its runtime-specific configuration (e.g. `thinking`/`continue` for Claude
@@ -90,6 +104,7 @@ export const harnessV1BridgeStartBaseSchema = z.object({
   model: z.string().optional(),
   debug: harnessV1DebugConfigSchema.optional(),
   permissionMode: harnessV1BridgePermissionModeSchema.optional(),
+  builtinToolFiltering: harnessV1BridgeBuiltinToolFilteringSchema.optional(),
 });
 
 // --- Transport / control frames (outbound, not consumer events) ---

package/src/v1/harness-v1-session.ts

@@ -10,6 +10,7 @@ import type {
 import type { HarnessV1Skill } from './harness-v1-skill';
 import type { HarnessV1StreamPart } from './harness-v1-stream-part';
 import type { HarnessV1ToolSpec } from './harness-v1-tool-spec';
+import type { HarnessV1BuiltinToolFiltering } from './harness-v1-tool-filtering';
 
 /**
  * Options passed to `HarnessV1.doStart`.
@@ -53,6 +54,13 @@ export type HarnessV1StartOptions = {
    */
   readonly permissionMode?: HarnessV1PermissionMode;
 
+  /**
+   * Adapter-native built-in tools that should be available for this session.
+   * Custom host-executed tools are filtered by the framework before they reach
+   * the adapter.
+   */
+  readonly builtinToolFiltering?: HarnessV1BuiltinToolFiltering;
+
   /**
    * Signal that aborts startup. The adapter must propagate cancellation to
    * any spawned processes or network calls.

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

@@ -0,0 +1,25 @@
+export type HarnessV1BuiltinToolFiltering =
+  | {
+      mode: 'allow';
+      toolNames: string[];
+    }
+  | {
+      mode: 'deny';
+      toolNames: string[];
+    };
+
+export function isHarnessV1BuiltinToolIncluded(input: {
+  toolName: string;
+  toolFiltering: HarnessV1BuiltinToolFiltering | undefined;
+}): boolean {
+  if (input.toolFiltering == null) return true;
+  return input.toolFiltering.mode === 'allow'
+    ? input.toolFiltering.toolNames.includes(input.toolName)
+    : !input.toolFiltering.toolNames.includes(input.toolName);
+}
+
+export function getHarnessV1BuiltinToolFilteringDenialReason(input: {
+  toolName: string;
+}): string {
+  return `Tool '${input.toolName}' is inactive due to the HarnessAgent tool filtering policy.`;
+}

package/src/v1/harness-v1.ts

@@ -51,6 +51,17 @@ export type HarnessV1<TBuiltinTools extends ToolSet = ToolSet> = {
    */
   readonly supportsBuiltinToolApprovals?: boolean;
 
+  /**
+   * Whether the adapter can prevent its underlying runtime from seeing or
+   * calling inactive built-in tools for every tool in `builtinTools`.
+   *
+   * Adapters without native filtering can still support `activeTools` and
+   * `inactiveTools` for built-ins when `supportsBuiltinToolApprovals` is
+   * `true`: the framework routes inactive built-in tool calls through the
+   * approval path and auto-denies them before they execute.
+   */
+  readonly supportsBuiltinToolFiltering?: boolean;
+
   /**
    * Optional schema for the adapter-defined `data` payload returned by session
    * lifecycle methods. When present, the adapter promises that exported state

package/src/v1/index.ts

@@ -58,6 +58,7 @@ export {
 } from './harness-v1-stream-part';
 export {
   harnessV1BridgeAbortInboundSchema,
+  harnessV1BridgeBuiltinToolFilteringSchema,
   harnessV1BridgeDebugEventSchema,
   harnessV1BridgeDetachInboundSchema,
   harnessV1BridgeDetachSchema,
@@ -91,3 +92,8 @@ export {
 } from './harness-v1-diagnostic';
 export type { HarnessV1ToolSpec } from './harness-v1-tool-spec';
 export type { HarnessV1PermissionMode } from './harness-v1-permission-mode';
+export type { HarnessV1BuiltinToolFiltering } from './harness-v1-tool-filtering';
+export {
+  getHarnessV1BuiltinToolFilteringDenialReason,
+  isHarnessV1BuiltinToolIncluded,
+} from './harness-v1-tool-filtering';