@ai-sdk/harness 1.0.71 → 1.0.72

package/CHANGELOG.md

@@ -1,5 +1,16 @@
 # @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

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

@@ -3691,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 = [];
@@ -3741,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,