@ai-sdk/harness 1.0.70 → 1.0.72

package/CHANGELOG.md

@@ -1,5 +1,26 @@
 # @ai-sdk/harness
 
+## 1.0.72
+
+### Patch Changes
+
+- 69bb613: feat(harness): support request transformations in network sandbox abstraction and use it to apply credential brokering when available
+- 52bc889: feat(harness): add `getPortEndpoint()` as more comprehensive replacement to `getPortUrl()` (now deprecated) in `HarnessV1NetworkSandboxSession`
+- 4cd4989: chore(harness): decouple bridge based harness bootstrap recipe logic from dynamic params and enforce unique harnesses in `prepareSandboxForHarness()` helper
+- Updated dependencies [0782259]
+- Updated dependencies [2fd1214]
+  - ai@7.0.66
+
+## 1.0.71
+
+### Patch Changes
+
+- 8d717b3: Execute independent host tool calls concurrently within a harness step.
+- Updated dependencies [dc8caae]
+- Updated dependencies [72ec74f]
+- Updated dependencies [c5b0515]
+  - ai@7.0.65
+
 ## 1.0.70
 
 ### Patch Changes

package/dist/agent/index.d.ts

@@ -117,6 +117,14 @@ interface HarnessV1Bootstrap {
     readonly commands: ReadonlyArray<HarnessV1BootstrapCommand>;
 }
 
+/**
+ * Connection details for a sandbox-exposed port. Headers are scoped to the
+ * returned URL and must be included when opening the connection.
+ */
+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
@@ -125,8 +133,8 @@ interface HarnessV1Bootstrap {
  *
  * 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.
  */
 interface HarnessV1NetworkSandboxSession extends Experimental_SandboxSession {
     /**
@@ -151,12 +159,21 @@ interface HarnessV1NetworkSandboxSession extends Experimental_SandboxSession {
      * not bake a provider-specific base into their own paths.
      */
     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';
@@ -176,6 +193,23 @@ interface HarnessV1NetworkSandboxSession extends Experimental_SandboxSession {
      * missing implementation is a no-op.
      */
     readonly setNetworkPolicy?: (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 —
@@ -192,7 +226,8 @@ interface HarnessV1NetworkSandboxSession extends Experimental_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: () => Experimental_SandboxSession;
 }
@@ -226,6 +261,47 @@ 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.
+ */
+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>>;
+    };
+};
 
 /** Severity of a diagnostic, ordered most → least severe. */
 declare const harnessV1DebugLevelSchema: z.ZodEnum<{
@@ -664,8 +740,10 @@ 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;
     /**
@@ -1606,6 +1684,9 @@ 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.
  */
 declare function prepareSandboxForHarness(options: {
     readonly session: Experimental_SandboxSession;
@@ -1633,8 +1714,8 @@ declare const symbol$1: unique symbol;
 /**
  * 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/dist/agent/index.js

@@ -1476,6 +1476,23 @@ function runPrompt(input) {
     let pendingStopBoundary;
     let finalFinish;
     const completedSteps = [];
+    const outstandingHostToolExecutions = [];
+    const startHostToolExecution = (execution) => {
+      outstandingHostToolExecutions.push(execution);
+      void execution.catch(() => {
+      });
+    };
+    const waitForOutstandingHostToolExecutions = async () => {
+      if (outstandingHostToolExecutions.length === 0) return;
+      const executions = outstandingHostToolExecutions.splice(0);
+      const results = await Promise.allSettled(executions);
+      const failedExecution = results.find(
+        (result2) => result2.status === "rejected"
+      );
+      if (failedExecution != null) {
+        throw failedExecution.reason;
+      }
+    };
     const releasePendingStopBoundary = () => {
       var _a6;
       (_a6 = pendingStopBoundary == null ? void 0 : pendingStopBoundary.releaseCheckpoint) == null ? void 0 : _a6.call(pendingStopBoundary);
@@ -1531,6 +1548,7 @@ function runPrompt(input) {
       return step;
     };
     const finishForHostInputPause = async (options) => {
+      await waitForOutstandingHostToolExecutions();
       if (options.completeCurrentStep) {
         await completeStep({
           finishReason: toolCallsFinishReason,
@@ -1799,6 +1817,7 @@ function runPrompt(input) {
           }
         }
         if (value.type === "error" && displayValue.type === "error") {
+          await waitForOutstandingHostToolExecutions();
           await telemetry.error(value.error);
           logBridgeError({
             harnessId: input.harness.harnessId,
@@ -1892,6 +1911,7 @@ function runPrompt(input) {
           return;
         }
         if (value.type === "finish-step") {
+          await waitForOutstandingHostToolExecutions();
           await completeStep({
             finishReason: value.finishReason,
             usage: value.usage,
@@ -1906,6 +1926,7 @@ function runPrompt(input) {
           }
         }
         if (value.type === "finish") {
+          await waitForOutstandingHostToolExecutions();
           finalFinish = value;
           await telemetry.end({
             finishReason: value.finishReason,
@@ -2009,41 +2030,51 @@ function runPrompt(input) {
             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) => {
-              const stripped = stripWorkDir(
-                {
-                  type: "tool-result",
-                  toolCallId: toolCall.toolCallId,
-                  toolName: toolCall.toolName,
-                  result: preliminaryOutput
-                },
-                input.sessionWorkDir
-              );
-              result.enqueue({
-                type: "tool-result",
-                toolCallId: toolCall.toolCallId,
-                toolName: toolCall.toolName,
-                input: void 0,
-                output: stripped.result,
-                preliminary: true
-              });
-            }
-          });
-          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) => {
+                  const stripped = stripWorkDir(
+                    {
+                      type: "tool-result",
+                      toolCallId: toolCall.toolCallId,
+                      toolName: toolCall.toolName,
+                      result: preliminaryOutput
+                    },
+                    input.sessionWorkDir
+                  );
+                  result.enqueue({
+                    type: "tool-result",
+                    toolCallId: toolCall.toolCallId,
+                    toolName: toolCall.toolName,
+                    input: void 0,
+                    output: stripped.result,
+                    preliminary: true
+                  });
+                }
+              });
+              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 = ((_j = input.isTurnSuspending) == null ? void 0 : _j.call(input)) === true;
       if (isTurnSuspending) {
         if (finalFinish == null) {
@@ -2062,6 +2093,10 @@ function runPrompt(input) {
         } : void 0
       );
     } catch (err) {
+      try {
+        await waitForOutstandingHostToolExecutions();
+      } catch (e) {
+      }
       await telemetry.error(err);
       logBridgeError({
         harnessId: input.harness.harnessId,
@@ -3656,10 +3691,11 @@ async function prepareSandboxForHarness(options) {
       "prepareSandboxForHarness: at least one harness must be provided."
     );
   }
-  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 ? void 0 : normalizeSandboxWorkDir(sandboxConfig.workDir);
   const recipeIdentities = {};
   const skippedHarnessIds = [];
@@ -3706,17 +3742,6 @@ async function prepareSandboxForHarness(options) {
     skippedHarnessIds
   };
 }
-function assertUniqueHarnessIds(harnesses) {
-  const seen = /* @__PURE__ */ new Set();
-  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,