@ai-sdk/harness 1.0.71 → 1.0.73

package/CHANGELOG.md

@@ -1,5 +1,23 @@
 # @ai-sdk/harness
 
+## 1.0.73
+
+### Patch Changes
+
+- 62a9c2a: feat(harness): add support for structured output to `HarnessAgent` via `output` property
+- d25cae2: fix(harness): claim the bridge event stream on start/resume instead of on connect
+
+## 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/README.md

@@ -81,6 +81,23 @@ try {
 }
 ```
 
+Set `output` on `HarnessAgent` to require the same typed, schema-backed output
+on every turn. `generate()` exposes the validated value as `result.output`, and
+`stream()` additionally exposes `partialOutputStream`; the JSON also remains on
+the normal text and stream surfaces.
+
+```ts
+import { Output } from 'ai';
+
+const agent = new HarnessAgent({
+  harness: claudeCode,
+  sandbox,
+  output: Output.object({
+    schema: z.object({ answer: z.string() }),
+  }),
+});
+```
+
 Use `session.detach()` to park a bridge-backed session for later attach, `session.stop()` to save state and stop the sandbox, or `session.destroy()` to clean up without keeping resume state. Bridge-backed adapters such as Claude Code, Codex, OpenCode, and DeepAgents require a sandbox provider that exposes ports — `@ai-sdk/sandbox-vercel` is the supported choice today. `@ai-sdk/sandbox-just-bash` is suitable only for host-runtime or otherwise non-bridge flows, such as Pi.
 
 `sandbox` is a required `HarnessV1SandboxProvider` — the agent calls `provider.createSession()` when a session starts. Use `sandboxConfig` for agent specific sandbox configuration that works independently from the sandbox provider that is used:
@@ -111,6 +128,12 @@ See the [harness adapters documentation](https://ai-sdk.dev/v7/docs/ai-sdk-harne
 
 Implement the `HarnessV1` factory and a `HarnessV1Session` whose `doPromptTurn` emits events; the agent surface, streaming, tool execution, and multi-turn state are handled for you. Read `startOpts.sandboxSession` for the network sandbox session the agent created and will stop on cleanup. Call `sandboxSession.restricted()` for the tool-safe file-IO/exec/spawn surface.
 
+Each prompt and continuation receives an optional `responseFormat`. JSON
+formats carry a caller-provided JSON Schema plus optional name and description;
+the adapter must enforce the schema and emit the resulting JSON through normal
+text parts. If the runtime cannot honor the format, throw
+`HarnessCapabilityUnsupportedError` before starting the turn.
+
 Bootstrap recipe paths may be absolute or relative. Relative `bootstrapDir` and
 file paths are resolved against `sandboxSession.defaultWorkingDirectory`.
 The framework creates `bootstrapDir` before writing files, and bootstrap

package/dist/agent/index.d.ts

@@ -1,6 +1,6 @@
 import * as _ai_sdk_provider_utils from '@ai-sdk/provider-utils';
 import { Experimental_SandboxSession, UserModelMessage, ToolSet, FlexibleSchema, Tool, Context, Arrayable, ToolApprovalResponse, ModelMessage } from '@ai-sdk/provider-utils';
-import { StopCondition, ToolApprovalStatus, TelemetryOptions, ActiveTools, StreamTextResult, Agent, AgentCallParameters, GenerateTextResult, AgentStreamParameters, Telemetry } from 'ai';
+import { OutputInterface, StopCondition, ToolApprovalStatus, TelemetryOptions, ActiveTools, StreamTextResult, Agent, AgentCallParameters, GenerateTextResult, AgentStreamParameters, Telemetry } from 'ai';
 import { z } from 'zod/v4';
 import { JSONValue, LanguageModelV4ToolCall, LanguageModelV4ToolApprovalRequest, LanguageModelV4ToolResult, LanguageModelV4FinishReason, LanguageModelV4Usage, JSONSchema7, AISDKError } from '@ai-sdk/provider';
 
@@ -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<{
@@ -359,6 +435,30 @@ type HarnessV1PromptControl = {
     readonly done: PromiseLike<void>;
 };
 
+type HarnessV1JSONValue = null | boolean | number | string | HarnessV1JSONArray | HarnessV1JSONObject;
+interface HarnessV1JSONArray extends Array<HarnessV1JSONValue> {
+}
+interface HarnessV1JSONObject {
+    [key: string]: HarnessV1JSONValue | undefined;
+}
+type HarnessV1JSONSchema = HarnessV1JSONObject;
+/**
+ * Requested response format for one harness turn.
+ *
+ * This intentionally mirrors the AI SDK provider response-format shape
+ * without depending on `@ai-sdk/provider`. Harness implementations receive
+ * JSON Schema rather than the caller's original Zod or Standard Schema so the
+ * contract can cross process and package boundaries.
+ */
+type HarnessV1ResponseFormat = {
+    readonly type: 'text';
+} | {
+    readonly type: 'json';
+    readonly schema?: HarnessV1JSONSchema;
+    readonly name?: string;
+    readonly description?: string;
+};
+
 type HarnessV1PendingToolApproval = {
     readonly approvalId: string;
     readonly toolCallId: string;
@@ -664,8 +764,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;
     /**
@@ -686,6 +788,11 @@ type HarnessV1PromptTurnOptions = {
      * so prior turns are never replayed across the contract.
      */
     readonly prompt: HarnessV1Prompt;
+    /**
+     * Response format requested for this turn. Adapters that cannot honor a
+     * JSON response format must throw `HarnessCapabilityUnsupportedError`.
+     */
+    readonly responseFormat?: HarnessV1ResponseFormat;
     /**
      * Host-defined tools to make available to the underlying runtime for this
      * turn. The harness emits `tool-call` events when the runtime calls one
@@ -721,6 +828,11 @@ type HarnessV1PromptTurnOptions = {
  * that was previously suspended temporarily, e.g. by the workflow slice loop.
  */
 type HarnessV1ContinueTurnOptions = {
+    /**
+     * Response format of the in-flight turn. Rerun-based adapters use this when
+     * reconstructing the turn; attach-based adapters may ignore it.
+     */
+    readonly responseFormat?: HarnessV1ResponseFormat;
     /**
      * Host-defined tools to make available for the continued turn. Same shape
      * as `doPromptTurn`'s `tools`. An adapter that purely attaches to a live turn
@@ -1157,7 +1269,7 @@ type HarnessAgentToolFilteringSettings<TOOLS extends ToolSet> = {
      */
     readonly inactiveTools?: HarnessTools<TOOLS>;
 };
-type HarnessAgentSettings<THarness extends HarnessAgentAdapter<any> = HarnessAgentAdapter, TUserTools extends ToolSet = {}, RUNTIME_CONTEXT extends Context = Context> = {
+type HarnessAgentSettings<THarness extends HarnessAgentAdapter<any> = HarnessAgentAdapter, TUserTools extends ToolSet = {}, RUNTIME_CONTEXT extends Context = Context, OUTPUT extends OutputInterface = never> = {
     /**
      * The harness adapter driving the underlying agent runtime. Its
      * `builtinTools` are merged with the user-defined `tools` and exposed to
@@ -1191,6 +1303,11 @@ type HarnessAgentSettings<THarness extends HarnessAgentAdapter<any> = HarnessAge
      * it to the first user message of a fresh session.
      */
     readonly instructions?: string;
+    /**
+     * Optional specification for generating typed output. The same output
+     * requirement is active for every turn run by this agent.
+     */
+    readonly output?: OUTPUT;
     /**
      * Conditions that stop the current result after a completed harness tool
      * step that can continue into another model step. The underlying turn remains
@@ -1288,8 +1405,8 @@ declare function collectHarnessAgentToolResultContinuations(input: {
     messages: readonly ModelMessage[];
 }): readonly HarnessAgentToolResultContinuation[];
 
-type HarnessAgentTurnResult<TOOLS extends ToolSet, RUNTIME_CONTEXT extends Context> = {
-    result: StreamTextResult<TOOLS, RUNTIME_CONTEXT, never>;
+type HarnessAgentTurnResult<TOOLS extends ToolSet, RUNTIME_CONTEXT extends Context, OUTPUT extends OutputInterface> = {
+    result: StreamTextResult<TOOLS, RUNTIME_CONTEXT, OUTPUT>;
     done: Promise<void>;
 };
 type HarnessAgentTurnState = 'idle' | 'running' | 'awaiting-approval' | 'awaiting-tool-result' | 'suspended';
@@ -1347,7 +1464,7 @@ declare class HarnessAgentSession {
         turnState?: HarnessAgentTurnState;
     });
     hasUnfinishedTurn(): boolean;
-    promptTurn<TOOLS extends ToolSet, RUNTIME_CONTEXT extends Context>(options: {
+    promptTurn<TOOLS extends ToolSet, RUNTIME_CONTEXT extends Context, OUTPUT extends OutputInterface>(options: {
         prompt: HarnessAgentPrompt;
         instructions: string | undefined;
         tools: TOOLS;
@@ -1356,10 +1473,12 @@ declare class HarnessAgentSession {
         builtinToolFiltering: HarnessV1BuiltinToolFiltering | undefined;
         runtimeContext: RUNTIME_CONTEXT;
         abortSignal: AbortSignal | undefined;
+        responseFormat: HarnessV1ResponseFormat | undefined;
+        output: OUTPUT | undefined;
         telemetry: TelemetryOptions | undefined;
         stopConditions: ReadonlyArray<StopCondition<TOOLS, RUNTIME_CONTEXT>>;
-    }): HarnessAgentTurnResult<TOOLS, RUNTIME_CONTEXT>;
-    continueTurn<TOOLS extends ToolSet, RUNTIME_CONTEXT extends Context>(options: {
+    }): HarnessAgentTurnResult<TOOLS, RUNTIME_CONTEXT, OUTPUT>;
+    continueTurn<TOOLS extends ToolSet, RUNTIME_CONTEXT extends Context, OUTPUT extends OutputInterface>(options: {
         instructions: string | undefined;
         tools: TOOLS;
         activeTools: ToolSet;
@@ -1367,11 +1486,13 @@ declare class HarnessAgentSession {
         builtinToolFiltering: HarnessV1BuiltinToolFiltering | undefined;
         runtimeContext: RUNTIME_CONTEXT;
         abortSignal: AbortSignal | undefined;
+        responseFormat: HarnessV1ResponseFormat | undefined;
+        output: OUTPUT | undefined;
         telemetry: TelemetryOptions | undefined;
         stopConditions: ReadonlyArray<StopCondition<TOOLS, RUNTIME_CONTEXT>>;
         toolApprovalContinuations?: readonly HarnessAgentToolApprovalContinuation[] | undefined;
         toolResultContinuations?: readonly HarnessAgentToolResultContinuation[] | undefined;
-    }): HarnessAgentTurnResult<TOOLS, RUNTIME_CONTEXT>;
+    }): HarnessAgentTurnResult<TOOLS, RUNTIME_CONTEXT, OUTPUT>;
     /**
      * Ask the underlying runtime to compact its context. The runtime performs
      * the compaction itself; when it completes, a `compaction` part appears on
@@ -1478,7 +1599,7 @@ interface HarnessAgentCallExtensions {
  *    `Experimental_SandboxSession`) is handed to user-tool `execute()` calls
  *    via `experimental_sandbox`.
  */
-declare class HarnessAgent<THarness extends HarnessAgentAdapter<any> = HarnessAgentAdapter, TUserTools extends ToolSet = {}, RUNTIME_CONTEXT extends Context = Context> implements Agent<never, HarnessAllTools<THarness, TUserTools>, RUNTIME_CONTEXT, never> {
+declare class HarnessAgent<THarness extends HarnessAgentAdapter<any> = HarnessAgentAdapter, TUserTools extends ToolSet = {}, RUNTIME_CONTEXT extends Context = Context, OUTPUT extends OutputInterface = never> implements Agent<never, HarnessAllTools<THarness, TUserTools>, RUNTIME_CONTEXT, OUTPUT> {
     readonly version: "agent-v1";
     readonly id: string | undefined;
     /**
@@ -1494,7 +1615,7 @@ declare class HarnessAgent<THarness extends HarnessAgentAdapter<any> = HarnessAg
     private readonly activeUserTools;
     private readonly builtinToolFiltering;
     private readonly permissionMode;
-    constructor(settings: HarnessAgentSettings<THarness, TUserTools, RUNTIME_CONTEXT>);
+    constructor(settings: HarnessAgentSettings<THarness, TUserTools, RUNTIME_CONTEXT, OUTPUT>);
     /** Identifier of the harness backing this agent. */
     get harnessId(): string;
     /**
@@ -1527,8 +1648,8 @@ declare class HarnessAgent<THarness extends HarnessAgentAdapter<any> = HarnessAg
         continueFrom?: HarnessAgentContinueTurnState;
         abortSignal?: AbortSignal;
     }): Promise<HarnessAgentSession>;
-    generate(options: AgentCallParameters<never, HarnessAllTools<THarness, TUserTools>, RUNTIME_CONTEXT> & HarnessAgentCallExtensions): Promise<GenerateTextResult<HarnessAllTools<THarness, TUserTools>, RUNTIME_CONTEXT, never>>;
-    stream(options: AgentStreamParameters<never, HarnessAllTools<THarness, TUserTools>, RUNTIME_CONTEXT> & HarnessAgentCallExtensions): Promise<StreamTextResult<HarnessAllTools<THarness, TUserTools>, RUNTIME_CONTEXT, never>>;
+    generate(options: AgentCallParameters<never, HarnessAllTools<THarness, TUserTools>, RUNTIME_CONTEXT> & HarnessAgentCallExtensions): Promise<GenerateTextResult<HarnessAllTools<THarness, TUserTools>, RUNTIME_CONTEXT, OUTPUT>>;
+    stream(options: AgentStreamParameters<never, HarnessAllTools<THarness, TUserTools>, RUNTIME_CONTEXT> & HarnessAgentCallExtensions): Promise<StreamTextResult<HarnessAllTools<THarness, TUserTools>, RUNTIME_CONTEXT, OUTPUT>>;
     /**
      * Continue the in-flight turn **without a new prompt**, draining it like
      * {@link generate}. Used after `createSession({ continueFrom })` to finish
@@ -1539,7 +1660,7 @@ declare class HarnessAgent<THarness extends HarnessAgentAdapter<any> = HarnessAg
         toolApprovalContinuations?: readonly HarnessAgentToolApprovalContinuation[];
         toolResultContinuations?: readonly HarnessAgentToolResultContinuation[];
         abortSignal?: AbortSignal;
-    }): Promise<GenerateTextResult<HarnessAllTools<THarness, TUserTools>, RUNTIME_CONTEXT, never>>;
+    }): Promise<GenerateTextResult<HarnessAllTools<THarness, TUserTools>, RUNTIME_CONTEXT, OUTPUT>>;
     /**
      * Continue the in-flight turn **without a new prompt**, streaming its events
      * like {@link stream}. Used to keep consuming a turn that is still running
@@ -1553,12 +1674,13 @@ declare class HarnessAgent<THarness extends HarnessAgentAdapter<any> = HarnessAg
         toolApprovalContinuations?: readonly HarnessAgentToolApprovalContinuation[];
         toolResultContinuations?: readonly HarnessAgentToolResultContinuation[];
         abortSignal?: AbortSignal;
-    }): Promise<StreamTextResult<HarnessAllTools<THarness, TUserTools>, RUNTIME_CONTEXT, never>>;
+    }): Promise<StreamTextResult<HarnessAllTools<THarness, TUserTools>, RUNTIME_CONTEXT, OUTPUT>>;
     private _startTurn;
     private _acquireSandbox;
     private _resolveTurnInput;
     private _toToolSpecs;
     private _toGenerateResult;
+    private _resolveResponseFormat;
 }
 
 type SandboxBootstrapSettings = Omit<HarnessAgentSandboxConfig, 'onSession'>;
@@ -1606,6 +1728,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 +1758,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.