@ai-sdk/harness 1.0.70 → 1.0.72

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

@@ -248,6 +248,25 @@ export function runPrompt<
       | Extract<HarnessV1StreamPart, { type: 'finish' }>
       | undefined;
     const completedSteps: Array<StepResult<TOOLS, RUNTIME_CONTEXT>> = [];
+    const outstandingHostToolExecutions: Promise<void>[] = [];
+    const startHostToolExecution = (execution: Promise<void>): void => {
+      outstandingHostToolExecutions.push(execution);
+      // The execution is joined at the next step boundary. Attach a rejection
+      // handler immediately so failures cannot become unhandled in the
+      // meantime; awaiting the original promise still propagates the failure.
+      void execution.catch(() => {});
+    };
+    const waitForOutstandingHostToolExecutions = async (): Promise<void> => {
+      if (outstandingHostToolExecutions.length === 0) return;
+      const executions = outstandingHostToolExecutions.splice(0);
+      const results = await Promise.allSettled(executions);
+      const failedExecution = results.find(
+        result => result.status === 'rejected',
+      );
+      if (failedExecution != null) {
+        throw failedExecution.reason;
+      }
+    };
     const releasePendingStopBoundary = (): void => {
       pendingStopBoundary?.releaseCheckpoint?.();
       pendingStopBoundary = undefined;
@@ -311,6 +330,7 @@ export function runPrompt<
     const finishForHostInputPause = async (options: {
       completeCurrentStep: boolean;
     }): Promise<void> => {
+      await waitForOutstandingHostToolExecutions();
       if (options.completeCurrentStep) {
         await completeStep({
           finishReason: toolCallsFinishReason,
@@ -665,6 +685,7 @@ export function runPrompt<
          * or a second `error` part from `fail`).
          */
         if (value.type === 'error' && displayValue.type === 'error') {
+          await waitForOutstandingHostToolExecutions();
           // Telemetry and stderr diagnostics keep the raw error (absolute
           // paths help debugging); the consumer-facing settle uses the
           // workDir-stripped one, like every other forwarded part.
@@ -784,6 +805,7 @@ export function runPrompt<
 
         // Drive step boundaries.
         if (value.type === 'finish-step') {
+          await waitForOutstandingHostToolExecutions();
           await completeStep({
             finishReason: value.finishReason,
             usage: value.usage,
@@ -799,6 +821,7 @@ export function runPrompt<
         }
 
         if (value.type === 'finish') {
+          await waitForOutstandingHostToolExecutions();
           finalFinish = value;
           await telemetry.end({
             finishReason: value.finishReason,
@@ -910,52 +933,62 @@ export function runPrompt<
             await finishForHostInputPause({ completeCurrentStep: true });
             return;
           }
-          const execution = await maybeExecuteHostTool({
-            event: toolCall,
-            tools: activeTools,
-            wrappedExecuteTool: telemetry.executeTool,
-            sandboxSession: input.sandboxSession,
-            abortSignal: input.abortSignal,
-            control,
-            onPreliminaryResult: preliminaryOutput => {
-              /*
-               * Project a `yield`ed value as a preliminary AI SDK
-               * `tool-result` part. Unlike the final result — which is
-               * submitted to the runtime, echoed back as a `tool-result`
-               * event, and stripped on its way through the loop above —
-               * preliminary values never reach the runtime, so strip the
-               * working directory here to match the final result's projection.
-               */
-              const stripped = stripWorkDir(
-                {
-                  type: 'tool-result',
-                  toolCallId: toolCall.toolCallId,
-                  toolName: toolCall.toolName,
-                  result: preliminaryOutput as Extract<
-                    HarnessV1StreamPart,
-                    { type: 'tool-result' }
-                  >['result'],
-                },
-                input.sessionWorkDir,
-              ) as Extract<HarnessV1StreamPart, { type: 'tool-result' }>;
-              result.enqueue({
-                type: 'tool-result',
-                toolCallId: toolCall.toolCallId,
-                toolName: toolCall.toolName,
-                input: undefined,
-                output: stripped.result,
-                preliminary: true,
-              } as TextStreamPart<TOOLS>);
-            },
-          });
-          if (!execution.executed) {
+          if (!isExecutableTool(activeTools[toolCall.toolName])) {
             recordPendingToolResult({ toolCall });
             await finishForHostInputPause({ completeCurrentStep: true });
             return;
           }
-          await telemetry.toolEnd(toolCall.toolCallId, execution.outcome);
+          startHostToolExecution(
+            (async () => {
+              const execution = await maybeExecuteHostTool({
+                event: toolCall,
+                tools: activeTools,
+                wrappedExecuteTool: telemetry.executeTool,
+                sandboxSession: input.sandboxSession,
+                abortSignal: input.abortSignal,
+                control,
+                onPreliminaryResult: preliminaryOutput => {
+                  /*
+                   * Project a `yield`ed value as a preliminary AI SDK
+                   * `tool-result` part. Unlike the final result — which is
+                   * submitted to the runtime, echoed back as a `tool-result`
+                   * event, and stripped on its way through the loop above —
+                   * preliminary values never reach the runtime, so strip the
+                   * working directory here to match the final result's projection.
+                   */
+                  const stripped = stripWorkDir(
+                    {
+                      type: 'tool-result',
+                      toolCallId: toolCall.toolCallId,
+                      toolName: toolCall.toolName,
+                      result: preliminaryOutput as Extract<
+                        HarnessV1StreamPart,
+                        { type: 'tool-result' }
+                      >['result'],
+                    },
+                    input.sessionWorkDir,
+                  ) as Extract<HarnessV1StreamPart, { type: 'tool-result' }>;
+                  result.enqueue({
+                    type: 'tool-result',
+                    toolCallId: toolCall.toolCallId,
+                    toolName: toolCall.toolName,
+                    input: undefined,
+                    output: stripped.result,
+                    preliminary: true,
+                  } as TextStreamPart<TOOLS>);
+                },
+              });
+              if (!execution.executed) {
+                throw new Error(
+                  `Harness '${input.harness.harnessId}' could not execute host tool '${toolCall.toolName}'.`,
+                );
+              }
+              await telemetry.toolEnd(toolCall.toolCallId, execution.outcome);
+            })(),
+          );
         }
       }
+      await waitForOutstandingHostToolExecutions();
       const isTurnSuspending = input.isTurnSuspending?.() === true;
       if (isTurnSuspending) {
         if (finalFinish == null) {
@@ -982,6 +1015,11 @@ export function runPrompt<
           : undefined,
       );
     } catch (err) {
+      try {
+        await waitForOutstandingHostToolExecutions();
+      } catch {
+        // Preserve the error that stopped the reader loop.
+      }
       await telemetry.error(err);
       logBridgeError({
         harnessId: input.harness.harnessId,

package/src/agent/prepare-sandbox-for-harness.ts

@@ -36,6 +36,9 @@ export type PrepareSandboxForHarnessResult = {
  * When a later `HarnessAgent` session uses a sandbox created from the persisted
  * artifact, the adapter recomputes the same recipe identity and the existing
  * bootstrap marker makes the bootstrap logic a no-op.
+ *
+ * Repeated harness IDs are prepared once. When multiple adapters use the same
+ * ID, the last adapter in `harnesses` is used.
  */
 export async function prepareSandboxForHarness(options: {
   readonly session: SandboxSession;
@@ -52,10 +55,11 @@ export async function prepareSandboxForHarness(options: {
     );
   }
 
-  const harnesses = [...options.harnesses].sort((a, b) =>
-    a.harnessId.localeCompare(b.harnessId),
-  );
-  assertUniqueHarnessIds(harnesses);
+  const harnesses = [
+    ...new Map(
+      options.harnesses.map(harness => [harness.harnessId, harness]),
+    ).values(),
+  ].sort((a, b) => a.harnessId.localeCompare(b.harnessId));
 
   const workDir =
     sandboxConfig.workDir == null
@@ -112,20 +116,6 @@ export async function prepareSandboxForHarness(options: {
   };
 }
 
-function assertUniqueHarnessIds(
-  harnesses: ReadonlyArray<HarnessAgentAdapter>,
-): void {
-  const seen = new Set<string>();
-  for (const harness of harnesses) {
-    if (seen.has(harness.harnessId)) {
-      throw new Error(
-        `prepareSandboxForHarness: duplicate harness id "${harness.harnessId}".`,
-      );
-    }
-    seen.add(harness.harnessId);
-  }
-}
-
 async function resolvePreparedSandboxIdentity({
   recipeIdentities,
   bootstrapHash,

package/src/errors/harness-capability-unsupported-error.ts

@@ -8,8 +8,8 @@ const symbol = Symbol.for(marker);
 /**
  * Thrown when a caller asks the harness to do something the adapter (or the
  * supplied sandbox) does not support, e.g. requesting manual compaction from
- * an adapter that only auto-compacts, or invoking `getPortUrl` on a sandbox
- * that does not expose one.
+ * an adapter that only auto-compacts, or invoking `getPortEndpoint` on a
+ * sandbox that does not expose one.
  *
  * The caller supplies the full human-readable message. Optional `harnessId`
  * is recorded as structured context for tooling.

package/src/utils/index.ts

@@ -6,6 +6,11 @@ export {
 } from './sandbox-channel';
 export { classifyDiskLog, type DiskLogRecoveryMode } from './classify-disk-log';
 export { getAiGatewayAuthFromEnv } from './ai-gateway-auth';
+export {
+  createCredentialRequestTransformation,
+  maskSandboxCredentials,
+  warnCredentialBrokeringUnavailable,
+} from './sandbox-credential-brokering';
 export { resolveSandboxHomeDir } from './sandbox-home-dir';
 export { shellQuote } from './shell-quote';
 export {

package/src/utils/sandbox-credential-brokering.ts

@@ -0,0 +1,41 @@
+import type { HarnessV1RequestTransformation } from '../v1';
+
+export function warnCredentialBrokeringUnavailable(): void {
+  console.warn(
+    'The sandbox implementation does not support configuring request transformations, so credential brokering does not work. Falling back to less secure credential forwarding.',
+  );
+}
+
+export function maskSandboxCredentials({
+  environment,
+  credentialEnvironmentVariables,
+}: {
+  environment: Readonly<Record<string, string>>;
+  credentialEnvironmentVariables: ReadonlyArray<string>;
+}): Record<string, string> {
+  const maskedEnvironment = { ...environment };
+  for (const name of credentialEnvironmentVariables) {
+    if (maskedEnvironment[name] != null) {
+      maskedEnvironment[name] = name;
+    }
+  }
+  return maskedEnvironment;
+}
+
+export function createCredentialRequestTransformation({
+  baseUrl,
+  headers,
+}: {
+  baseUrl: string;
+  headers: Readonly<Record<string, string>>;
+}): HarnessV1RequestTransformation {
+  const url = new URL(baseUrl);
+  const pathname = url.pathname.replace(/\/+$/, '');
+  return {
+    match: {
+      host: url.hostname,
+      ...(pathname.length === 0 ? {} : { path: { startsWith: pathname } }),
+    },
+    transform: { headers },
+  };
+}

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

@@ -1,5 +1,14 @@
 import type { Experimental_SandboxSession as SandboxSession } from '@ai-sdk/provider-utils';
 
+/**
+ * Connection details for a sandbox-exposed port. Headers are scoped to the
+ * returned URL and must be included when opening the connection.
+ */
+export type HarnessV1PortEndpoint = {
+  readonly url: string;
+  readonly headers?: Readonly<Record<string, string>>;
+};
+
 /**
  * Network sandbox session returned by `HarnessV1SandboxProvider.createSession()`. The
  * harness keeps this for the lifetime of a session. It is itself a
@@ -8,8 +17,8 @@ import type { Experimental_SandboxSession as SandboxSession } from '@ai-sdk/prov
  *
  * Code that should only touch the filesystem and spawn processes receives the
  * reduced view from {@link HarnessV1NetworkSandboxSession.restricted}, never the
- * network sandbox session itself — so it cannot stop the sandbox or change its
- * network policy.
+ * network sandbox session itself — so it cannot stop the sandbox, change
+ * network access, or transform requests.
  */
 export interface HarnessV1NetworkSandboxSession extends SandboxSession {
   /**
@@ -36,13 +45,23 @@ export interface HarnessV1NetworkSandboxSession extends SandboxSession {
    */
   readonly defaultWorkingDirectory: string;
 
-  /** Ports the sandbox exposes; resolvable to public URLs via `getPortUrl`. */
+  /** Ports the sandbox exposes; resolvable via `getPortEndpoint`. */
   readonly ports: ReadonlyArray<number>;
 
   /**
-   * Resolve a publicly-reachable URL for a sandbox-exposed port. Bridge-backed
+   * Resolve the connection details for a sandbox-exposed port. Bridge-backed
    * adapters call this to open their WebSocket to the in-sandbox bridge.
    */
+  readonly getPortEndpoint: (options: {
+    port: number;
+    protocol?: 'http' | 'https' | 'ws';
+  }) => PromiseLike<HarnessV1PortEndpoint>;
+
+  /**
+   * Resolve a publicly-reachable URL for a sandbox-exposed port.
+   *
+   * @deprecated Use `getPortEndpoint` instead.
+   */
   readonly getPortUrl: (options: {
     port: number;
     protocol?: 'http' | 'https' | 'ws';
@@ -68,6 +87,29 @@ export interface HarnessV1NetworkSandboxSession extends SandboxSession {
     policy: HarnessV1NetworkPolicy,
   ) => PromiseLike<void>;
 
+  /**
+   * Replace the sandbox's outbound request-transformation rules. Optional —
+   * implementations expose this only when credentials can be injected outside
+   * the sandbox security boundary. Calling this method assumes authority over
+   * the complete transformation set; harness adapters should normally use
+   * `addRequestTransformations` instead. Adapters may preserve legacy
+   * credential-forwarding behavior when additive request transformations are
+   * unavailable.
+   */
+  readonly setRequestTransformations?: (
+    transformations: ReadonlyArray<HarnessV1RequestTransformation>,
+  ) => PromiseLike<void>;
+
+  /**
+   * Add outbound request-transformation rules without replacing rules already
+   * managed by the sandbox session. Optional for the same reason as
+   * `setRequestTransformations`. Harness adapters should use this additive
+   * capability unless they explicitly own the complete transformation set.
+   */
+  readonly addRequestTransformations?: (
+    transformations: ReadonlyArray<HarnessV1RequestTransformation>,
+  ) => PromiseLike<void>;
+
   /**
    * Replace the set of ports exposed by the sandbox. Full-replacement
    * semantics: ports omitted from the array are deregistered. Optional —
@@ -86,7 +128,8 @@ export interface HarnessV1NetworkSandboxSession extends SandboxSession {
    *
    * The returned object points at exactly the same underlying sandbox
    * resource as the network sandbox session it was produced from; it is only a
-   * narrower surface over the same resource, not a separate sandbox.
+   * narrower surface over the same resource, not a separate sandbox. In
+   * particular, it cannot mutate network access or request transformations.
    */
   readonly restricted: () => SandboxSession;
 }
@@ -121,3 +164,42 @@ export type HarnessV1NetworkPolicy =
       allowedCIDRs: ReadonlyArray<string>;
       deniedCIDRs?: ReadonlyArray<string>;
     };
+
+type HarnessV1RequestTransformationPathMatcher =
+  | { exact: string }
+  | { startsWith: string }
+  | { regex: string };
+
+type HarnessV1RequestTransformationKeyValuePartMatcher =
+  | { exact: string }
+  | { startsWith: string }
+  | { regex: string };
+
+type HarnessV1RequestTransformationKeyValueMatcher = {
+  readonly key?: HarnessV1RequestTransformationKeyValuePartMatcher;
+  readonly value?: HarnessV1RequestTransformationKeyValuePartMatcher;
+};
+
+/**
+ * Outbound HTTPS request transformation applied outside the sandbox security
+ * boundary. The host is part of the match so each rule is self-contained and
+ * several rules, including several for the same host, can be installed at
+ * once.
+ *
+ * Credential values belong in `transform.headers`, while the sandbox process
+ * receives only a non-secret placeholder. Implementations must overwrite
+ * matching request headers after the request leaves the sandbox rather than
+ * making transformed values available inside it.
+ */
+export type HarnessV1RequestTransformation = {
+  readonly match: {
+    readonly host: string;
+    readonly path?: HarnessV1RequestTransformationPathMatcher;
+    readonly method?: ReadonlyArray<string>;
+    readonly queryString?: ReadonlyArray<HarnessV1RequestTransformationKeyValueMatcher>;
+    readonly headers?: ReadonlyArray<HarnessV1RequestTransformationKeyValueMatcher>;
+  };
+  readonly transform: {
+    readonly headers: Readonly<Record<string, string>>;
+  };
+};

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

@@ -78,8 +78,10 @@ export type HarnessV1StartOptions = {
    * Network sandbox session the adapter operates against. It is owned and
    * lifecycled by `HarnessAgent`. Adapters call `restricted()` for the
    * tool-safe filesystem/exec/spawn surface, and use the infra methods
-   * (`getPortUrl`, `ports`, `setNetworkPolicy`) for bridge wiring. Adapters
-   * must not call `stop()` themselves; the agent does that during cleanup.
+   * (`getPortEndpoint`, `ports`, `setNetworkPolicy`,
+   * `setRequestTransformations`, `addRequestTransformations`) for bridge
+   * wiring. Adapters must not call `stop()` themselves; the agent does that
+   * during cleanup.
    */
   readonly sandboxSession: HarnessV1NetworkSandboxSession;
 

package/src/v1/index.ts

@@ -36,6 +36,8 @@ export type {
 export type {
   HarnessV1NetworkPolicy,
   HarnessV1NetworkSandboxSession,
+  HarnessV1PortEndpoint,
+  HarnessV1RequestTransformation,
 } from './harness-v1-network-sandbox-session';
 export type { HarnessV1Skill } from './harness-v1-skill';
 export type { HarnessV1StreamPart } from './harness-v1-stream-part';