@ai-sdk/harness 0.0.0-6b196531-20260710185421

package/dist/agent/index.d.ts

@@ -0,0 +1,1631 @@
+import * as _ai_sdk_provider_utils from '@ai-sdk/provider-utils';
+import { Experimental_SandboxSession, UserModelMessage, ToolSet, FlexibleSchema, Tool, ToolApprovalResponse, ModelMessage, Context } from '@ai-sdk/provider-utils';
+import { 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';
+
+/** Severity of a diagnostic. */
+type HarnessDebugLevel = 'error' | 'warn' | 'info' | 'debug' | 'trace';
+/**
+ * Consumer-facing diagnostics configuration. Set on `HarnessAgentSettings` to
+ * enable bridge log forwarding and the `HARNESS_DEBUG` stderr default in code.
+ * `HARNESS_DEBUG` / `HARNESS_DEBUG_LEVEL` / `HARNESS_DEBUG_SUBSYSTEMS` env vars
+ * fill any unset field — a convenience default, never the only path.
+ */
+type HarnessDebugConfig = {
+    /** Master switch. Nothing is captured or forwarded when false/unset. */
+    readonly enabled?: boolean;
+    /** Threshold; events at or above this severity are emitted. Default `debug`. */
+    readonly level?: HarnessDebugLevel;
+    /** Dotted-prefix subsystem filter for structured events. */
+    readonly subsystems?: ReadonlyArray<string>;
+};
+/**
+ * A forwarded bridge diagnostic, normalized for host consumers.
+ *
+ * The bridge emits two raw frame kinds — captured console lines (`sandbox-log`)
+ * and structured events (`debug-event`). The framework normalizes both into
+ * this single shape before handing them to a consumer's `onLog` callback, the
+ * `HARNESS_DEBUG` stderr default, and observability reporters. Diagnostics are
+ * kept first-class and per-line — they are never folded into telemetry spans.
+ */
+type HarnessDiagnostic = {
+    /**
+     * Severity. Structured events carry their own level; captured console lines
+     * map `stderr` → `'warn'` and `stdout` → `'info'`.
+     */
+    readonly level: HarnessDebugLevel;
+    /** Human-readable line (console capture) or message (structured event). */
+    readonly message: string;
+    /**
+     * Dotted subsystem. For captured console output this is
+     * `sandbox.log.<source>`; for structured events it is the adapter-supplied
+     * subsystem (e.g. `bridge.turn`).
+     */
+    readonly subsystem: string;
+    /** `'log'` = captured console line; `'event'` = structured `bridgeLog`. */
+    readonly kind: 'log' | 'event';
+    /** Originating sandbox source label (console capture). */
+    readonly source?: string;
+    /** Which standard stream the line came from (console capture). */
+    readonly stream?: 'stdout' | 'stderr';
+    /** Structured attributes (structured events only). */
+    readonly attrs?: Record<string, unknown>;
+    /** Error payload (structured events only). */
+    readonly error?: {
+        name?: string;
+        message: string;
+        stack?: string;
+    };
+    /** The harness session this diagnostic originated from. */
+    readonly sessionId?: string;
+    /** Host receipt time (epoch ms). */
+    readonly timestamp: number;
+};
+/**
+ * A telemetry integration that also wants the per-line diagnostics stream. The
+ * framework calls `ingestDiagnostic` for every forwarded bridge diagnostic in
+ * addition to driving the standard `Telemetry` span lifecycle, so a single
+ * reporter object (e.g. `createFileReporter`) registered in
+ * `telemetry.integrations` receives both spans and logs.
+ */
+interface HarnessDiagnosticConsumer {
+    ingestDiagnostic?(diagnostic: HarnessDiagnostic): void;
+}
+
+/**
+ * One file to write into the sandbox as part of an adapter's bootstrap recipe.
+ * Paths should live under {@link HarnessV1Bootstrap.bootstrapDir}.
+ */
+interface HarnessV1BootstrapFile {
+    readonly path: string;
+    readonly content: string;
+}
+/**
+ * One command to run in the sandbox as part of an adapter's bootstrap recipe.
+ * Commands run sequentially after all files have been written; a non-zero exit
+ * aborts the bootstrap.
+ */
+interface HarnessV1BootstrapCommand {
+    readonly command: string;
+    readonly workingDirectory?: string;
+}
+/**
+ * Adapter-owned bootstrap recipe. The adapter declares the files and commands
+ * needed to set up its bridge inside any sandbox. The harness framework hashes
+ * the recipe into an identity used by sandbox providers for snapshot-based
+ * reuse, and applies the recipe idempotently before the bridge spawns.
+ */
+interface HarnessV1Bootstrap {
+    /**
+     * Stable id of the adapter that owns this recipe. Conventionally matches
+     * {@link HarnessV1.harnessId}. Contributes to the recipe hash.
+     */
+    readonly harnessId: string;
+    /**
+     * Absolute path inside the sandbox where this recipe writes its state.
+     * The marker file lives directly under it. Files declared in {@link files}
+     * should also use this prefix so an adapter upgrade can sweep stale state
+     * by clearing the directory.
+     */
+    readonly bootstrapDir: string;
+    /** Files to write into the sandbox before any command runs. */
+    readonly files: ReadonlyArray<HarnessV1BootstrapFile>;
+    /** Commands to run after files are written, in order. */
+    readonly commands: ReadonlyArray<HarnessV1BootstrapCommand>;
+}
+
+/**
+ * Network sandbox session returned by `HarnessV1SandboxProvider.createSession()`. The
+ * harness keeps this for the lifetime of a session. It is itself a
+ * {@link SandboxSession} (file I/O, exec, spawn) and adds the infra surface on
+ * top: port resolution, lifecycle, and network-policy mutation.
+ *
+ * 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.
+ */
+interface HarnessV1NetworkSandboxSession extends Experimental_SandboxSession {
+    /**
+     * Stable identifier for the underlying sandbox resource. Used by the
+     * harness session manager as the durable lookup key for cross-process
+     * resume — the framework persists this on lifecycle state so a future
+     * process can call `HarnessV1SandboxProvider.resume?({ sessionId })` and
+     * reach the same resource. Providers populate it from their native
+     * identifier (Vercel: the sandbox name; just-bash: a UUID minted at
+     * create time).
+     */
+    readonly id: string;
+    /**
+     * The sandbox's default working directory — the absolute path that
+     * `run`/`spawn` resolve relative commands against when no `workingDirectory`
+     * is given. Read from the live sandbox (it is provider-specific and
+     * configurable at create time: Vercel defaults to `/vercel/sandbox`,
+     * just-bash to `/home/user`), never hardcoded.
+     *
+     * The framework composes each session's working directory underneath this
+     * path (`<defaultWorkingDirectory>/<harnessId>-<sessionId>`) so adapters do
+     * not bake a provider-specific base into their own paths.
+     */
+    readonly defaultWorkingDirectory: string;
+    /** Ports the sandbox exposes; resolvable to public URLs via `getPortUrl`. */
+    readonly ports: ReadonlyArray<number>;
+    /**
+     * Resolve a publicly-reachable URL for a sandbox-exposed port. Bridge-backed
+     * adapters call this to open their WebSocket to the in-sandbox bridge.
+     */
+    readonly getPortUrl: (options: {
+        port: number;
+        protocol?: 'http' | 'https' | 'ws';
+    }) => PromiseLike<string>;
+    /** Stop the sandbox. Idempotent. */
+    readonly stop: () => PromiseLike<void>;
+    /**
+     * Destroy/delete the sandbox resource when supported. Optional because some
+     * providers only have a stop/dispose concept. Implementations must handle
+     * both a still-running sandbox and a previously stopped sandbox.
+     */
+    readonly destroy?: () => PromiseLike<void>;
+    /**
+     * Update the sandbox's outbound network policy. Optional — implementations
+     * without a local enforcement primitive (e.g. just-bash) omit this. Callers
+     * use optional-call (`sandboxSession.setNetworkPolicy?.(policy)`); a
+     * missing implementation is a no-op.
+     */
+    readonly setNetworkPolicy?: (policy: HarnessV1NetworkPolicy) => PromiseLike<void>;
+    /**
+     * Replace the set of ports exposed by the sandbox. Full-replacement
+     * semantics: ports omitted from the array are deregistered. Optional —
+     * implementations that cannot expose ports (e.g. just-bash) omit this.
+     */
+    readonly setPorts?: (ports: ReadonlyArray<number>, options?: {
+        abortSignal?: AbortSignal;
+    }) => PromiseLike<void>;
+    /**
+     * Reduced view of this session, typed as the bare {@link SandboxSession}
+     * (file I/O, exec, spawn) — nothing that could stop the sandbox or change
+     * its network policy. Pass this to user-tool `execute()` calls and other
+     * code that must not reach the infra surface.
+     *
+     * 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.
+     */
+    readonly restricted: () => Experimental_SandboxSession;
+}
+/**
+ * Outbound network policy applied by the sandbox runtime.
+ *
+ * `'allow-all'` and `'deny-all'` are convenience presets. `'custom'` is an
+ * allow-list with an optional CIDR deny-list that takes precedence:
+ *
+ * - Reachable hosts are the union of `allowedHosts` and `allowedCIDRs`.
+ * - `deniedCIDRs` wins over both, useful for blocking cloud-metadata IPs while
+ *   otherwise allowing broad access.
+ *
+ * The two `'custom'` branches share the same discriminator but each requires
+ * a different allow field. Specifying `'custom'` with only `deniedCIDRs`
+ * (deny-only) is rejected at compile time — functionally it would be
+ * equivalent to `'deny-all'`.
+ */
+type HarnessV1NetworkPolicy = {
+    mode: 'allow-all';
+} | {
+    mode: 'deny-all';
+} | {
+    mode: 'custom';
+    allowedHosts: ReadonlyArray<string>;
+    allowedCIDRs?: ReadonlyArray<string>;
+    deniedCIDRs?: ReadonlyArray<string>;
+} | {
+    mode: 'custom';
+    allowedHosts?: ReadonlyArray<string>;
+    allowedCIDRs: ReadonlyArray<string>;
+    deniedCIDRs?: ReadonlyArray<string>;
+};
+
+/** Severity of a diagnostic, ordered most → least severe. */
+declare const harnessV1DebugLevelSchema: z.ZodEnum<{
+    error: "error";
+    warn: "warn";
+    info: "info";
+    debug: "debug";
+    trace: "trace";
+}>;
+type HarnessV1DebugLevel = z.infer<typeof harnessV1DebugLevelSchema>;
+/**
+ * Per-session diagnostics configuration the framework hands an adapter (and the
+ * host sends on `start.debug`). When absent or `enabled` is false the adapter
+ * captures and emits nothing. `subsystems` filters structured events by dotted
+ * prefix; console capture is independent of the subsystem filter.
+ */
+declare const harnessV1DebugConfigSchema: z.ZodObject<{
+    enabled: z.ZodOptional<z.ZodBoolean>;
+    level: z.ZodOptional<z.ZodEnum<{
+        error: "error";
+        warn: "warn";
+        info: "info";
+        debug: "debug";
+        trace: "trace";
+    }>>;
+    subsystems: z.ZodOptional<z.ZodArray<z.ZodString>>;
+}, z.core.$strip>;
+type HarnessV1DebugConfig = z.infer<typeof harnessV1DebugConfigSchema>;
+/**
+ * A diagnostic as emitted by a harness adapter. Structurally identical to the
+ * host-facing `HarnessDiagnostic` today, but kept separate: this is the spec's
+ * emission shape, that is the external consumption shape.
+ */
+type HarnessV1Diagnostic = {
+    /** Severity. */
+    readonly level: HarnessV1DebugLevel;
+    /** Human-readable line (console capture) or message (structured event). */
+    readonly message: string;
+    /** Dotted subsystem (`sandbox.log.<source>` for console capture). */
+    readonly subsystem: string;
+    /** `'log'` = captured console line; `'event'` = structured emission. */
+    readonly kind: 'log' | 'event';
+    /** Originating source label (console capture). */
+    readonly source?: string;
+    /** Which standard stream the line came from (console capture). */
+    readonly stream?: 'stdout' | 'stderr';
+    /** Structured attributes (structured events only). */
+    readonly attrs?: Record<string, unknown>;
+    /** Error payload (structured events only). */
+    readonly error?: {
+        name?: string;
+        message: string;
+        stack?: string;
+    };
+    /** The harness session this diagnostic originated from. */
+    readonly sessionId?: string;
+    /** Emission time (epoch ms). */
+    readonly timestamp: number;
+};
+
+/**
+ * Diagnostics wiring the framework hands to an adapter's `doStart`. `report` is
+ * the general emission sink: a bridge adapter normalizes each wire frame into a
+ * `HarnessV1Diagnostic` (via `harnessV1DiagnosticFromBridgeFrame`) and calls it;
+ * a non-bridge adapter constructs a `HarnessV1Diagnostic` from its host-side
+ * logs/errors and calls it directly. `debug` gates what the adapter emits.
+ * Absent when the consumer has not enabled diagnostics.
+ */
+type HarnessV1Observability = {
+    /** Per-session debug config gating what the adapter captures/emits. */
+    readonly debug?: HarnessV1DebugConfig;
+    /** General emission sink — any adapter reports a `HarnessV1Diagnostic` here. */
+    readonly report?: (diagnostic: HarnessV1Diagnostic) => void;
+};
+
+/**
+ * Baseline permission mode for adapter-native built-in tools.
+ *
+ * Custom host-executed tools are not controlled by this setting. They use
+ * `HarnessAgentSettings.toolApproval`, similar to AI SDK's per-tool approval
+ * status map.
+ */
+type HarnessV1PermissionMode = 'allow-reads' | 'allow-edits' | 'allow-all';
+
+/**
+ * Prompt shape passed to `HarnessV1Session.doPromptTurn`.
+ *
+ * A harness session represents an ongoing third-party agent runtime that
+ * owns its own conversation history. Each prompt turn carries only the
+ * fresh user input for that turn, either as a plain string or as a single
+ * `UserModelMessage`.
+ */
+type HarnessV1Prompt = string | UserModelMessage;
+
+/**
+ * Bidirectional control surface returned by `doPromptTurn`.
+ *
+ * The host uses these methods to feed asynchronous responses back to the
+ * adapter while a turn is running. All methods are optional except those
+ * the adapter actively supports (host-executed tools require
+ * `submitToolResult`; approvals require `submitToolApproval`; mid-turn
+ * messages require `submitUserMessage`).
+ */
+type HarnessV1PromptControl = {
+    /**
+     * Provide a result for a `tool-call` the adapter emitted. The adapter
+     * forwards the result to the underlying runtime so the model can continue.
+     */
+    submitToolResult(input: {
+        toolCallId: string;
+        output: unknown;
+        isError?: boolean;
+    }): PromiseLike<void>;
+    /**
+     * Respond to a `tool-approval-request` the adapter emitted.
+     */
+    submitToolApproval?(input: {
+        approvalId: string;
+        approved: boolean;
+        reason?: string;
+    }): PromiseLike<void>;
+    /**
+     * Inject a fresh user message into a turn that is still in flight.
+     * Supported only by runtimes that accept interactive input.
+     */
+    submitUserMessage?(text: string): PromiseLike<void>;
+    /**
+     * Resolves when the adapter has finished the turn (success or failure).
+     * Rejects with the underlying error when the turn fails.
+     */
+    readonly done: PromiseLike<void>;
+};
+
+type HarnessV1PendingToolApproval = {
+    readonly approvalId: string;
+    readonly toolCallId: string;
+    readonly toolName: string;
+    readonly input: string;
+    readonly kind: 'builtin' | 'custom';
+    readonly providerExecuted?: boolean;
+    readonly nativeName?: string;
+};
+type HarnessV1LifecycleStateBase = {
+    /**
+     * Identifier of the harness that produced this state. Used by adapters to
+     * refuse mismatched payloads.
+     */
+    readonly harnessId: string;
+    /**
+     * Spec version of the harness that produced this state.
+     */
+    readonly specificationVersion: 'harness-v1';
+    /**
+     * Adapter-defined payload. May be persisted as JSON; the adapter is
+     * responsible for any necessary encoding.
+     */
+    readonly data: JSONValue;
+};
+/**
+ * Opaque payload returned by between-turn session lifecycle methods and
+ * accepted by a future `HarnessV1.doStart({ resumeFrom })` to resume the same
+ * underlying session before starting a new turn.
+ */
+type HarnessV1ResumeSessionState = HarnessV1LifecycleStateBase & {
+    readonly type: 'resume-session';
+    /**
+     * Optional unfinished-turn state. When present, the session must be resumed
+     * before the turn is continued.
+     */
+    readonly continueFrom?: HarnessV1ContinueTurnState;
+};
+/**
+ * Opaque payload returned by `doSuspendTurn` and accepted by a future
+ * `HarnessV1.doStart({ continueFrom })` to reconnect to the same session before
+ * continuing the interrupted turn.
+ */
+type HarnessV1ContinueTurnState = HarnessV1LifecycleStateBase & {
+    readonly type: 'continue-turn';
+    /**
+     * Framework-owned pending approval records. These are intentionally outside
+     * adapter-defined `data` so callers can persist the entire lifecycle payload
+     * without the harness framework owning storage.
+     */
+    readonly pendingToolApprovals?: readonly HarnessV1PendingToolApproval[];
+};
+type HarnessV1LifecycleState = HarnessV1ResumeSessionState | HarnessV1ContinueTurnState;
+
+/**
+ * A self-contained instruction bundle the underlying runtime can load into
+ * its context. Adapters decide how to surface skills to the runtime.
+ */
+type HarnessV1Skill = {
+    /** Stable identifier for the skill (kebab-case slug). */
+    readonly name: string;
+    /**
+     * Short, model-facing description. This is what the runtime sees to
+     * decide whether the skill is relevant.
+     */
+    readonly description: string;
+    /** Full skill content the model loads when the skill is active. */
+    readonly content: string;
+    /**
+     * Additional files that belong to this skill. Adapters with native skill
+     * directories materialize these next to `SKILL.md`; adapters without native
+     * skill files include them with the skill content.
+     */
+    readonly files?: ReadonlyArray<HarnessV1SkillFile>;
+};
+type HarnessV1SkillFile = {
+    /**
+     * Skill-relative POSIX path, for example `reference.md` or
+     * `references/codes.md`. Absolute paths and `..` segments are rejected by
+     * adapters before writing.
+     */
+    readonly path: string;
+    /** UTF-8 text content for the file. */
+    readonly content: string;
+};
+
+/**
+ * Warning emitted by a harness adapter during a call.
+ *
+ * Surfaces non-fatal issues such as unsupported options or quirks of the
+ * underlying agent runtime. Mirrors the shape of `SharedV4Warning` but lives
+ * in the harness namespace.
+ */
+type HarnessV1CallWarning = {
+    type: 'unsupported-setting';
+    setting: string;
+    details?: string;
+} | {
+    type: 'unsupported-tool';
+    tool: string;
+    details?: string;
+} | {
+    type: 'other';
+    message: string;
+};
+
+/**
+ * Adapter-namespaced opaque data attached to harness events.
+ *
+ * Mirrors the `providerMetadata` pattern from `@ai-sdk/provider`, but lives
+ * in the harness namespace because a harness is a peer concept to a
+ * provider, not a kind of provider.
+ *
+ * Keys are harness ids (e.g. `'claude-code'`). Inner values are arbitrary
+ * JSON-serializable data the adapter chooses to surface to callers.
+ */
+type HarnessV1Metadata = Record<string, Record<string, JSONValue>>;
+
+/**
+ * One event emitted by a harness adapter during a prompt turn.
+ *
+ * Mirrors `LanguageModelV4StreamPart` on the variants it shares so a
+ * `HarnessAgent` can pipe events through to AI SDK consumers with minimal
+ * translation. Primitive types from the V4 spec (`LanguageModelV4ToolCall`,
+ * `LanguageModelV4ToolResult`, `LanguageModelV4ToolApprovalRequest`,
+ * `LanguageModelV4Usage`, `LanguageModelV4FinishReason`) are reused
+ * verbatim — type-compat tests assert this stays the case.
+ *
+ * The metadata field is named `harnessMetadata` (not `providerMetadata`)
+ * because a harness is a peer to a provider, not a kind of provider. The
+ * agent rebinds it when forwarding to AI SDK consumers.
+ */
+type HarnessV1StreamPart = {
+    type: 'stream-start';
+    warnings?: ReadonlyArray<HarnessV1CallWarning>;
+    /**
+     * The model the runtime actually resolved to for this turn, when the
+     * adapter learns it at stream start (e.g. Claude Code's `init` message
+     * reports the resolved/default model). Surfaced into telemetry as
+     * `gen_ai.request.model`. Omitted when the adapter doesn't know it here.
+     */
+    modelId?: string;
+} | {
+    type: 'text-start';
+    id: string;
+    harnessMetadata?: HarnessV1Metadata;
+} | {
+    type: 'text-delta';
+    id: string;
+    delta: string;
+    harnessMetadata?: HarnessV1Metadata;
+} | {
+    type: 'text-end';
+    id: string;
+    harnessMetadata?: HarnessV1Metadata;
+} | {
+    type: 'reasoning-start';
+    id: string;
+    harnessMetadata?: HarnessV1Metadata;
+} | {
+    type: 'reasoning-delta';
+    id: string;
+    delta: string;
+    harnessMetadata?: HarnessV1Metadata;
+} | {
+    type: 'reasoning-end';
+    id: string;
+    harnessMetadata?: HarnessV1Metadata;
+} | (LanguageModelV4ToolCall & {
+    nativeName?: string;
+}) | LanguageModelV4ToolApprovalRequest | LanguageModelV4ToolResult | {
+    type: 'finish-step';
+    finishReason: LanguageModelV4FinishReason;
+    usage: LanguageModelV4Usage;
+    harnessMetadata?: HarnessV1Metadata;
+} | {
+    type: 'finish';
+    finishReason: LanguageModelV4FinishReason;
+    totalUsage: LanguageModelV4Usage;
+    harnessMetadata?: HarnessV1Metadata;
+} | {
+    type: 'file-change';
+    event: 'create' | 'modify' | 'delete';
+    path: string;
+    harnessMetadata?: HarnessV1Metadata;
+} | {
+    type: 'compaction';
+    trigger: 'manual' | 'auto';
+    summary: string;
+    tokensBefore?: number;
+    tokensAfter?: number;
+    harnessMetadata?: HarnessV1Metadata;
+} | {
+    type: 'error';
+    error: unknown;
+} | {
+    type: 'raw';
+    rawValue: unknown;
+};
+
+/**
+ * Description of a host-defined tool that the harness should make available
+ * to the underlying agent runtime.
+ *
+ * Adapters translate this into whatever shape their runtime expects (e.g.
+ * Claude Code's tool definitions, Codex CLI's tool config, an MCP server
+ * exposed to the runtime, …). The adapter does not execute the tool; when
+ * the runtime calls it, the adapter emits a `tool-call` event and waits for
+ * `submitToolResult` from the caller.
+ */
+type HarnessV1ToolSpec = {
+    /**
+     * Tool name the agent runtime sees. Must match the name on incoming
+     * `tool-call` events.
+     */
+    readonly name: string;
+    /**
+     * Human-readable description handed to the runtime, used to help the model
+     * decide when to call the tool.
+     */
+    readonly description?: string;
+    /**
+     * JSON Schema describing the expected input for the tool. Optional because
+     * some runtimes accept tools without schemas (free-form arguments).
+     */
+    readonly inputSchema?: JSONSchema7;
+};
+
+type HarnessV1BuiltinToolFiltering = {
+    mode: 'allow';
+    toolNames: string[];
+} | {
+    mode: 'deny';
+    toolNames: string[];
+};
+
+/**
+ * Options passed to `HarnessV1.doStart`.
+ *
+ * `sandboxSession` and `sessionWorkDir` are coupled and always present. The
+ * framework creates the sandbox and per-session working directory before
+ * calling the adapter, so adapters never need to derive provider-specific paths.
+ */
+type HarnessV1StartOptions = {
+    /**
+     * Stable identifier for this harness session. Used as the underlying
+     * resource name where the adapter has a notion of a named session
+     * (sandbox name, native session id, …).
+     */
+    readonly sessionId: string;
+    /**
+     * Skills made available to the underlying runtime for the lifetime of
+     * the session. Adapters decide how to surface them.
+     */
+    readonly skills?: ReadonlyArray<HarnessV1Skill>;
+    /**
+     * Optional resume payload returned by a prior session lifecycle method. When
+     * provided, the adapter should resume the existing session before accepting a
+     * new prompt or continuing a nested unfinished turn.
+     */
+    readonly resumeFrom?: HarnessV1ResumeSessionState;
+    /**
+     * Optional continuation payload returned by `doSuspendTurn`, or nested in
+     * `resumeFrom`. When provided, the adapter should resume the existing session
+     * in a shape ready for `doContinueTurn` rather than for a fresh prompt.
+     */
+    readonly continueFrom?: HarnessV1ContinueTurnState;
+    /**
+     * Approval policy for built-in adapter-native tool use. Custom host-executed
+     * tools are approved by the framework before results are submitted back to
+     * the adapter.
+     */
+    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.
+     */
+    readonly abortSignal?: AbortSignal;
+    /**
+     * Diagnostics wiring. The framework populates this; the adapter only
+     * forwards `observability.onDiagnostic` into its `SandboxChannel` and
+     * `observability.debug` into the bridge `start` message. Absent when the
+     * consumer has not enabled diagnostics.
+     */
+    readonly observability?: HarnessV1Observability;
+    /**
+     * 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.
+     */
+    readonly sandboxSession: HarnessV1NetworkSandboxSession;
+    /**
+     * Absolute path the adapter runs the agent in for this session. Composed by
+     * the framework as `<sandboxSession.defaultWorkingDirectory>/<harnessId>-<sessionId>`
+     * and created before `doStart`, so the adapter uses it directly instead of
+     * deriving its own provider-specific path.
+     */
+    readonly sessionWorkDir: string;
+};
+/**
+ * Options passed to `HarnessV1Session.doPromptTurn`.
+ */
+type HarnessV1PromptTurnOptions = {
+    /**
+     * Fresh input for this turn — either a plain string or a single
+     * `ModelMessage`. The harness session owns its own conversation history,
+     * so prior turns are never replayed across the contract.
+     */
+    readonly prompt: HarnessV1Prompt;
+    /**
+     * Host-defined tools to make available to the underlying runtime for this
+     * turn. The harness emits `tool-call` events when the runtime calls one
+     * and waits for `submitToolResult`.
+     */
+    readonly tools?: ReadonlyArray<HarnessV1ToolSpec>;
+    /**
+     * Free-form instructions for the session. The framework supplies the same
+     * value on every turn; the adapter is responsible for applying it once, by
+     * prepending it to the first user message of a fresh (non-resumed) session.
+     * On a resumed session the adapter must not re-apply it — the original first
+     * message already carried it and lives in the runtime's persisted history.
+     */
+    readonly instructions?: string;
+    /**
+     * Signal that aborts the in-flight turn. The adapter must cancel any
+     * underlying work and resolve `done` (with an error if appropriate).
+     */
+    readonly abortSignal?: AbortSignal;
+    /**
+     * Callback invoked once for each event the adapter produces during the
+     * turn. The adapter is responsible for the ordering and completeness of
+     * events. `done` resolves once the adapter has emitted all events for the
+     * turn (success or failure).
+     */
+    readonly emit: (event: HarnessV1StreamPart) => void;
+};
+/**
+ * Options passed to `HarnessV1Session.doContinueTurn`.
+ *
+ * Unlike `doPromptTurn`, there is no `prompt`: `doContinueTurn` continues the
+ * in-flight turn rather than starting a new one. It is used to continue a turn
+ * that was previously suspended temporarily, e.g. by the workflow slice loop.
+ */
+type HarnessV1ContinueTurnOptions = {
+    /**
+     * 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
+     * may ignore them; an adapter that re-drives the turn (rerun) needs them.
+     */
+    readonly tools?: ReadonlyArray<HarnessV1ToolSpec>;
+    /**
+     * Signal that aborts the continued turn. The adapter must cancel any
+     * underlying work and resolve `done` (with an error if appropriate).
+     */
+    readonly abortSignal?: AbortSignal;
+    /**
+     * Callback invoked once for each event the adapter produces while the
+     * continued turn runs. Same contract as `doPromptTurn`'s `emit`.
+     */
+    readonly emit: (event: HarnessV1StreamPart) => void;
+};
+/**
+ * Active harness session, returned by `HarnessV1.doStart`.
+ *
+ * A session is the unit of state continuity across multiple prompts (one
+ * sandbox, one conversation history, one running agent runtime). The host
+ * holds onto the session across `doPromptTurn` calls and ends the local
+ * instance via `doDetach`, `doStop`, or `doDestroy`.
+ */
+type HarnessV1Session = {
+    /**
+     * Stable identifier for this session. Same value the host passed in via
+     * `HarnessV1StartOptions.sessionId`.
+     */
+    readonly sessionId: string;
+    /**
+     * Whether this session was created from `resumeFrom` or `continueFrom`. Fresh
+     * sessions report `false`; resumed sessions report `true`.
+     */
+    readonly isResume: boolean;
+    /**
+     * The model id the underlying runtime is configured to use, if the adapter
+     * knows it (e.g. from its settings). Surfaced into telemetry as
+     * `gen_ai.request.model` and the trace span labels. Omitted when the adapter
+     * defers to the runtime's own default and has no concrete id.
+     */
+    readonly modelId?: string;
+    /**
+     * Run one prompt turn. Returns a control handle the host uses to feed
+     * tool results, approvals, and user messages back into the turn while it
+     * is in flight. The handle's `done` promise resolves when the turn ends.
+     */
+    doPromptTurn(options: HarnessV1PromptTurnOptions): PromiseLike<HarnessV1PromptControl>;
+    /**
+     * Request that the underlying runtime compact its context. The runtime owns
+     * the compaction — the harness neither implements nor schedules it; this is
+     * only the trigger. When compaction completes, the adapter surfaces a
+     * `compaction` stream part on the next/active turn.
+     *
+     * Required, but not every runtime can honour it: adapters whose transport
+     * exposes no manual compaction (e.g. Codex over `codex exec`, which still
+     * auto-compacts on its own) throw `HarnessCapabilityUnsupportedError`.
+     * `customInstructions`, when supported, steer the compaction summary.
+     */
+    doCompact(customInstructions?: string): PromiseLike<void>;
+    /**
+     * Continue the in-flight turn **without a new user prompt**, returning the
+     * same control surface as `doPromptTurn`. Used to keep consuming a turn that
+     * was interrupted at a process boundary (the workflow slice loop), after the
+     * session itself has been resumed via `doStart({ continueFrom })`:
+     *
+     *  - When the runtime's turn is still live and reachable (bridge `attach` /
+     *    `replay`), the adapter subscribes to its events and resolves `done` on
+     *    the turn's `finish` — **without** re-driving it. Lossless.
+     *  - When the live turn is gone (bridge respawned `rerun`, or a host-resident
+     *    runtime like Pi whose turn cannot survive its process), the adapter
+     *    re-drives the runtime's own thread from its persisted state. Lossy: work
+     *    in flight at the interruption is recomputed.
+     *
+     * Required on every adapter. The behaviour an adapter can guarantee follows
+     * from its architecture; the contract is uniform.
+     */
+    doContinueTurn(options: HarnessV1ContinueTurnOptions): PromiseLike<HarnessV1PromptControl>;
+    /**
+     * Gracefully freeze the active turn **at a precise cursor while keeping the
+     * runtime alive**, returning the continuation payload.
+     *
+     * This is the slice-boundary primitive. The adapter stops host-side
+     * consumption of the in-flight turn without telling the runtime to stop:
+     * for a bridge adapter it closes the host socket (the bridge keeps the turn
+     * running and accumulates events for replay) and resolves the active
+     * `doPromptTurn`/`doContinueTurn` `done` **cleanly** (not as an error) once buffered
+     * events have drained, so the cursor in the returned state equals the last
+     * event delivered to the host — guaranteeing the next slice's attach replays
+     * with no gap and no duplicate. A host-resident adapter (Pi) cannot keep its
+     * turn alive, so it persists what it can and the in-flight tail is recomputed
+     * on continue.
+     *
+     * Like `doDetach`, the sandbox/runtime is left running. Unlike `doDetach`,
+     * this is for an active turn at a slice boundary rather than a between-turn
+     * session handoff. Required on every adapter.
+     */
+    doSuspendTurn(): PromiseLike<HarnessV1ContinueTurnState>;
+    /**
+     * Detach from the underlying runtime without tearing it down, returning a
+     * payload the host can later pass to
+     * `HarnessV1.doStart({ resumeFrom })` to reconnect before a new turn. After
+     * `doDetach`, no further methods on this session instance may be called.
+     *
+     * Required. Adapters that cannot keep a live runtime parked still return the
+     * best resume session state they can while leaving the sandbox running.
+     */
+    doDetach(): PromiseLike<HarnessV1ResumeSessionState>;
+    /**
+     * Persist enough state to resume later, then stop the underlying runtime.
+     * After `doStop`, no further methods on this session instance may be called.
+     */
+    doStop(): PromiseLike<HarnessV1ResumeSessionState>;
+    /**
+     * Stop the underlying runtime without returning lifecycle state. After
+     * `doDestroy`, no further methods on this session instance may be called.
+     */
+    doDestroy(): PromiseLike<void>;
+};
+
+/**
+ * Versioned specification for a harness adapter — the integration point for
+ * one third-party coding-agent runtime (Claude Code, Codex, …).
+ *
+ * Modelled after `LanguageModelV4`: a tagged spec version, a small set of
+ * descriptive fields, and one entry-point method (`doStart`) that yields a
+ * session. There is intentionally no static "capabilities" object —
+ * optional features are signalled by the presence or absence of optional
+ * methods on the prompt-control handle. Adapters that cannot satisfy a request
+ * (manual compaction not supported, required port exposure unavailable, …)
+ * throw `HarnessCapabilityUnsupportedError` from the method that needs the
+ * capability.
+ */
+type HarnessV1<TBuiltinTools extends ToolSet = ToolSet> = {
+    /**
+     * Spec version this adapter implements. Always the literal `'harness-v1'`.
+     */
+    readonly specificationVersion: 'harness-v1';
+    /**
+     * Stable identifier for this harness, used as the key inside
+     * `HarnessV1Metadata` objects. Conventionally a kebab-case slug matching
+     * the package name (`'claude-code'`, `'codex'`).
+     */
+    readonly harnessId: string;
+    /**
+     * Tools the adapter's underlying runtime exposes natively, as a `ToolSet`
+     * keyed by what the bridge emits on `tool-call` events
+     * (`commonName ?? nativeName`). Each entry is a `HarnessV1BuiltinTool`
+     * (a `Tool` plus harness-specific `nativeName` / `commonName` metadata).
+     *
+     * The agent merges this with consumer-supplied user tools when validating
+     * inbound tool calls and when typing the consumer-facing stream.
+     */
+    readonly builtinTools: TBuiltinTools;
+    /**
+     * Whether the adapter can emit approval requests for built-in tools when
+     * `permissionMode` is not `'allow-all'`.
+     *
+     * Custom host-executed tool approvals are handled by `HarnessAgent`, so this
+     * only describes adapter-native tool approval support.
+     */
+    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
+     * validated by this schema can be re-imported in a future
+     * `doStart({ resumeFrom })` or `doStart({ continueFrom })` call.
+     */
+    readonly lifecycleStateSchema?: FlexibleSchema<unknown>;
+    /**
+     * Optional bootstrap recipe. When defined, the harness session manager
+     * computes a stable identity from the recipe, passes it (along with a
+     * one-time recipe-application hook) to the sandbox provider, and applies
+     * the recipe idempotently after the provider returns the handle.
+     *
+     * Adapters with no bootstrap needs omit this. Adapters that need to install
+     * deps or ship bridge files into the sandbox declare them here so the
+     * provider can cache the result across sessions via snapshots when
+     * supported.
+     */
+    readonly getBootstrap?: (options?: {
+        abortSignal?: AbortSignal;
+    }) => PromiseLike<HarnessV1Bootstrap>;
+    /**
+     * Start a fresh session, resume a parked session via `resumeFrom`, or resume
+     * an interrupted turn via `continueFrom`. The host then issues prompts against
+     * the returned session, ending with `doDetach`, `doStop`, or `doDestroy`.
+     */
+    doStart(options: HarnessV1StartOptions): PromiseLike<HarnessV1Session>;
+};
+
+/**
+ * Cross-harness vocabulary of common built-in tool names with their baseline
+ * input schemas. Adapters that declare a built-in with one of these
+ * `commonName`s must accept (at least) every input the baseline schema
+ * accepts. Extra optional fields are encouraged.
+ *
+ * Used both as runtime values (spread into `ToolSet`s for inspection) and as
+ * a vocabulary source — `HarnessV1BuiltinToolName` is derived from its keys.
+ */
+declare const HARNESS_V1_BUILTIN_TOOLS: {
+    readonly read: Tool<{
+        file_path: string;
+    }, unknown, _ai_sdk_provider_utils.Context>;
+    readonly write: Tool<{
+        file_path: string;
+        content: string;
+    }, unknown, _ai_sdk_provider_utils.Context>;
+    readonly edit: Tool<{
+        file_path: string;
+        old_string: string;
+        new_string: string;
+    }, unknown, _ai_sdk_provider_utils.Context>;
+    readonly bash: Tool<{
+        command: string;
+    }, unknown, _ai_sdk_provider_utils.Context>;
+    readonly grep: Tool<{
+        pattern: string;
+    }, unknown, _ai_sdk_provider_utils.Context>;
+    readonly glob: Tool<{
+        pattern: string;
+    }, unknown, _ai_sdk_provider_utils.Context>;
+    readonly webSearch: Tool<{
+        query: string;
+    }, unknown, _ai_sdk_provider_utils.Context>;
+};
+type HarnessV1BuiltinToolName = keyof typeof HARNESS_V1_BUILTIN_TOOLS;
+type HarnessV1BuiltinToolUseKind = 'readonly' | 'edit' | 'bash';
+/**
+ * A tool that the adapter's underlying runtime exposes natively. Extends the
+ * AI SDK `Tool` shape with two optional harness-specific fields:
+ *
+ *  - `nativeName`: the name as the underlying runtime knows it. Required
+ *    only when the tool's key in the harness's `builtinTools` is not the
+ *    native name — i.e. when the tool maps to a `commonName` (e.g. key
+ *    `'bash'` for Claude Code's native `'Bash'`). Tools without a common
+ *    equivalent are keyed by their native name directly, so `nativeName`
+ *    is redundant and omitted.
+ *  - `commonName`: cross-harness label drawn from
+ *    `HARNESS_V1_BUILTIN_TOOL_NAMES`. Set when the tool maps to a familiar
+ *    capability; consumers use it to recognize, e.g., that Claude Code's
+ *    `Bash` and Codex's `shell` are the same kind of tool.
+ *
+ * Always set both fields together via the `commonTool` helper, or neither
+ * (declare the tool with the AI SDK's `tool()` directly).
+ */
+type HarnessV1BuiltinTool<INPUT = unknown, OUTPUT = unknown> = Tool<INPUT, OUTPUT, any> & {
+    readonly nativeName?: string;
+    readonly commonName?: HarnessV1BuiltinToolName;
+    readonly toolUseKind?: HarnessV1BuiltinToolUseKind;
+};
+
+/**
+ * Provider that produces network sandbox sessions for harness sessions. Lives at
+ * module scope as a stable, synchronous object — analogous to
+ * `LanguageModelV4` providers, no I/O performed at construction. The actual
+ * sandbox is created (or wrapped) when `HarnessAgent` calls `createSession()`.
+ */
+interface HarnessV1SandboxProvider {
+    readonly specificationVersion: 'harness-sandbox-v1';
+    readonly providerId: string;
+    /**
+     * Pool of ports the consumer reserved on a caller-provided sandbox for
+     * concurrent harness sessions. The session manager leases one port per
+     * session and releases on stop or destroy.
+     *
+     * Only meaningful when the provider wraps a caller-provided sandbox
+     * (the caller pre-declared the ports). In create-new modes the provider
+     * mints a fresh sandbox per session, so no leasing is needed; providers
+     * leave this undefined.
+     */
+    readonly bridgePorts?: ReadonlyArray<number>;
+    readonly createSession: (options?: {
+        /**
+         * Stable per-session identifier. When supplied, the provider names the
+         * underlying resource deterministically so a future call to `resume`
+         * (potentially from a different process) can find the same sandbox.
+         * Omitted from prewarm and other paths that don't need a resumable
+         * resource — in that case the provider falls back to its native
+         * auto-naming.
+         */
+        sessionId?: string;
+        abortSignal?: AbortSignal;
+        /**
+         * Stable identity for snapshot-based reuse. Providers that support
+         * persistence/snapshots use this as part of the persistent sandbox
+         * name; subsequent calls with the same identity resume from snapshot.
+         *
+         * Ignored when the provider is wrapping a caller-provided sandbox.
+         */
+        identity?: string;
+        /**
+         * Called exactly once per identity, on fresh creation. Snapshot-capable
+         * providers wire this into the platform's one-time-setup hook so the
+         * side effects are baked into the snapshot. Providers without snapshot
+         * support run it immediately after fresh create.
+         *
+         * Not called when the provider is wrapping a caller-provided sandbox
+         * (the caller owns the sandbox; the framework applies its own
+         * idempotent bootstrap post-create instead).
+         */
+        onFirstCreate?: (session: Experimental_SandboxSession, opts: {
+            abortSignal?: AbortSignal;
+        }) => Promise<void>;
+    }) => PromiseLike<HarnessV1NetworkSandboxSession>;
+    /**
+     * Reattach to an existing sandbox previously created with the same
+     * `sessionId`. Optional — providers that cannot rehydrate by id (e.g.
+     * just-bash) omit this; the harness throws
+     * `HarnessCapabilityUnsupportedError` when resume is attempted against
+     * them.
+     *
+     * The provider derives the sandbox identifier from `sessionId` using the
+     * same deterministic naming scheme it used in `createSession`. Returns a
+     * network sandbox session bound to the existing resource.
+     */
+    readonly resumeSession?: (options: {
+        sessionId: string;
+        abortSignal?: AbortSignal;
+    }) => PromiseLike<HarnessV1NetworkSandboxSession>;
+}
+
+type HarnessAgentAdapter<TBuiltinTools extends ToolSet = ToolSet> = HarnessV1<TBuiltinTools>;
+type HarnessAgentBuiltinTool<INPUT = unknown, OUTPUT = unknown> = HarnessV1BuiltinTool<INPUT, OUTPUT>;
+type HarnessAgentBuiltinToolName = HarnessV1BuiltinToolName;
+type HarnessAgentBuiltinToolUseKind = HarnessV1BuiltinToolUseKind;
+type HarnessAgentBuiltinTools = typeof HARNESS_V1_BUILTIN_TOOLS;
+type HarnessAgentStartOptions = HarnessV1StartOptions;
+type HarnessAgentAdapterSession = HarnessV1Session;
+type HarnessAgentPrompt = HarnessV1Prompt;
+type HarnessAgentPromptControl = HarnessV1PromptControl;
+type HarnessAgentPromptTurnOptions = HarnessV1PromptTurnOptions;
+type HarnessAgentContinueTurnOptions = HarnessV1ContinueTurnOptions;
+type HarnessAgentStreamPart = HarnessV1StreamPart;
+type HarnessAgentToolSpec = HarnessV1ToolSpec;
+type HarnessAgentLifecycleState = HarnessV1LifecycleState;
+type HarnessAgentResumeSessionState = HarnessV1ResumeSessionState;
+type HarnessAgentContinueTurnState = HarnessV1ContinueTurnState;
+type HarnessAgentPendingToolApproval = HarnessV1PendingToolApproval;
+type HarnessAgentSkill = HarnessV1Skill;
+type HarnessAgentPermissionMode = HarnessV1PermissionMode;
+
+/** Extract the builtin tool set type from a harness adapter parameter. */
+type HarnessBuiltinToolsOf<H> = H extends HarnessAgentAdapter<infer T> ? T : never;
+/**
+ * Type-level merge of a harness's builtin tools with user-defined tools.
+ * User tools override builtins on key collision.
+ */
+type HarnessAllTools<THarness extends HarnessAgentAdapter<any>, TUserTools extends ToolSet> = Omit<HarnessBuiltinToolsOf<THarness>, keyof TUserTools> & TUserTools;
+
+type HarnessAgentToolApprovalConfiguration = Readonly<Record<string, ToolApprovalStatus>>;
+type HarnessAgentSandboxConfig = {
+    /**
+     * Optional fixed working directory for all sessions, relative to the
+     * sandbox's default working directory. When omitted, sessions keep the
+     * existing `<harnessId>-<sessionId>` work directory.
+     */
+    readonly workDir?: string;
+    /**
+     * Caller-controlled identity for `onBootstrap`. Change this whenever the
+     * bootstrap side effects should invalidate the reusable sandbox snapshot.
+     */
+    readonly bootstrapHash?: string;
+    /**
+     * Called during sandbox template creation after the harness adapter's own
+     * bootstrap has run and before snapshot-capable providers publish a snapshot.
+     *
+     * `bootstrapHash` must be provided with this callback.
+     */
+    readonly onBootstrap?: (opts: {
+        readonly session: Experimental_SandboxSession;
+        readonly workDir: string;
+        readonly abortSignal?: AbortSignal;
+    }) => Promise<void>;
+    /**
+     * Called after each sandbox session is acquired and the session work
+     * directory exists, before the harness adapter starts. Runs for fresh and
+     * resumed sessions.
+     *
+     * Use this to write per-session config, install lightweight tools, activate
+     * licenses, or prepare files in `sessionWorkDir`. Keep it idempotent if the
+     * agent may resume sessions.
+     */
+    readonly onSession?: (opts: {
+        readonly session: Experimental_SandboxSession;
+        readonly sessionWorkDir: string;
+        readonly abortSignal?: AbortSignal;
+    }) => Promise<void>;
+};
+type HarnessTools<TOOLS extends ToolSet> = ActiveTools<NoInfer<TOOLS>>;
+/**
+ * Construction-time settings for a `HarnessAgent`.
+ *
+ * Per-call settings (prompt, abortSignal, callbacks) belong on the
+ * `AgentCallParameters` / `AgentStreamParameters` passed to `generate` /
+ * `stream` and are not duplicated here.
+ */
+type HarnessAgentToolFilteringSettings<TOOLS extends ToolSet> = {
+    /**
+     * Limits the tools that are available for the harness to call without
+     * changing the tool call and result types in the result.
+     */
+    readonly activeTools?: HarnessTools<TOOLS>;
+    readonly inactiveTools?: never;
+} | {
+    readonly activeTools?: never;
+    /**
+     * Excludes tools from the set that is available for the harness to call
+     * without changing the tool call and result types in the result.
+     */
+    readonly inactiveTools?: HarnessTools<TOOLS>;
+};
+type HarnessAgentSettings<THarness extends HarnessAgentAdapter<any> = HarnessAgentAdapter, TUserTools extends ToolSet = {}> = {
+    /**
+     * The harness adapter driving the underlying agent runtime. Its
+     * `builtinTools` are merged with the user-defined `tools` and exposed to
+     * AI SDK consumers in the typed `tool-call` stream.
+     */
+    readonly harness: THarness;
+    /**
+     * Stable identifier for this agent instance. Exposed via `agent.id`.
+     * If omitted, `agent.id` is `undefined`.
+     */
+    readonly id?: string;
+    /**
+     * Tools available to the underlying runtime in addition to the harness's
+     * own builtins. The agent forwards each tool to the harness as a
+     * `HarnessAgentToolSpec`; when the runtime calls one, the agent executes
+     * `tool.execute()` on the host and submits the result back to the harness.
+     *
+     * User tools take precedence over harness builtins on key collision —
+     * declare a tool with the same name as a builtin to override.
+     */
+    readonly tools?: TUserTools;
+    /**
+     * Skills made available to the underlying runtime for the lifetime of
+     * the session. Each adapter decides how to surface skills (file in the
+     * working tree, prompt prefix, …).
+     */
+    readonly skills?: ReadonlyArray<HarnessAgentSkill>;
+    /**
+     * Instructions for the underlying agent runtime. Adapters prepend this to
+     * the first user message of a fresh session, once — it is not re-applied on
+     * later turns or when resuming a previously ended session.
+     */
+    readonly instructions?: string;
+    /**
+     * Built-in tool permission mode. Defaults to `'allow-all'`, preserving the
+     * existing bypass-permissions behavior unless users opt in.
+     */
+    readonly permissionMode?: HarnessAgentPermissionMode;
+    /**
+     * Per custom-tool approval statuses. This mirrors AI SDK `toolApproval`
+     * object configuration for host-executed tools, without callback support.
+     *
+     * `not-applicable` and `approved` run the tool, `user-approval` pauses the
+     * turn for a user decision, and `denied` immediately submits an
+     * `execution-denied` result.
+     */
+    readonly toolApproval?: HarnessAgentToolApprovalConfiguration;
+    /**
+     * Sandbox provider whose `create()` produces the network sandbox session the
+     * harness runs against. Its `restricted()` view is also propagated to user
+     * tool `execute()` calls (as the `experimental_sandbox` field), typed as
+     * `Experimental_SandboxSession` so tools cannot reach the infra surface.
+     */
+    readonly sandbox: HarnessV1SandboxProvider;
+    /**
+     * Sandbox working-directory and lifecycle hook configuration.
+     */
+    readonly sandboxConfig?: HarnessAgentSandboxConfig;
+    /** @deprecated Use `sandboxConfig.onSession` instead. */
+    readonly onSandboxSession?: HarnessAgentSandboxConfig['onSession'];
+    /**
+     * Telemetry configuration. The harness drives AI SDK's pluggable
+     * `Telemetry` integration contract from the turn lifecycle, so a harness turn
+     * appears in a consumer's traces with the same span shape as `streamText`.
+     * Register an integration here (e.g. `@ai-sdk/otel`) or globally via
+     * `registerTelemetry`. The harness itself stays OpenTelemetry-agnostic.
+     */
+    readonly telemetry?: TelemetryOptions;
+    /**
+     * Diagnostics configuration. Enables bridge log forwarding (sandbox
+     * console + structured `debug-event`s) and the `HARNESS_DEBUG` stderr default.
+     * Set `{ enabled: true }` to turn it on in code; env vars fill unset fields.
+     */
+    readonly debug?: HarnessDebugConfig;
+    /**
+     * Programmatic sink for forwarded bridge diagnostics. Receives every
+     * captured console line and structured event, normalized. Independent of the
+     * stderr default — wire this to capture diagnostics in code.
+     */
+    readonly onLog?: (event: HarnessDiagnostic) => void;
+} & HarnessAgentToolFilteringSettings<HarnessAllTools<THarness, TUserTools>>;
+
+type HarnessAgentToolApprovalContinuation = {
+    readonly approvalResponse: ToolApprovalResponse;
+    readonly toolCall: {
+        readonly type: 'tool-call';
+        readonly toolCallId: string;
+        readonly toolName: string;
+        readonly input: unknown;
+        readonly providerExecuted?: boolean;
+    };
+};
+/**
+ * Extract approval decisions that should continue a suspended harness turn.
+ *
+ * AI SDK clients send approval decisions as a trailing `role: "tool"` message
+ * containing `tool-approval-response` parts. The response only carries the
+ * approval id, so the harness has to recover the matching approval request
+ * locally to find the original tool call before it can resume the paused turn.
+ * Responses that already have a tool result are ignored, because those
+ * approvals were already consumed by a prior continuation.
+ */
+declare function collectHarnessAgentToolApprovalContinuations(input: {
+    messages: readonly ModelMessage[];
+}): readonly HarnessAgentToolApprovalContinuation[];
+
+type HarnessAgentTurnResult<TOOLS extends ToolSet, RUNTIME_CONTEXT extends Context> = {
+    result: StreamTextResult<TOOLS, RUNTIME_CONTEXT, never>;
+    done: Promise<void>;
+};
+type HarnessAgentTurnState = 'idle' | 'running' | 'awaiting-approval' | 'suspended';
+/**
+ * Live harness session held by the caller.
+ *
+ * Created by {@link import('./harness-agent').HarnessAgent.createSession}.
+ * Owns the underlying adapter session, the network sandbox session, and the
+ * bridge-port lease (when the provider wraps a caller-provided sandbox with a
+ * port pool).
+ *
+ * Pass the instance back to `agent.generate` / `agent.stream` on every
+ * call; end the local handle with `detach()`, `stop()`, or `destroy()`.
+ *
+ * After any lifecycle method has resolved, the session is unusable — any
+ * subsequent `generate`/`stream` call against it throws.
+ */
+declare class HarnessAgentSession {
+    /**
+     * Stable identifier the harness adapter saw in `doStart`. The same
+     * string callers persist when they intend to resume the session in a
+     * future process.
+     */
+    readonly sessionId: string;
+    private readonly harness;
+    private readonly sandboxProvider;
+    private readonly sessionWorkDir;
+    private underlyingSession;
+    private sandboxSession;
+    private leasedBridgePort;
+    private readonly toolApproval;
+    private readonly pendingToolApprovals;
+    private sessionState;
+    private turnState;
+    private turnSequence;
+    private activeTurnSequence;
+    /**
+     * Whether this session was created from `resumeFrom` or `continueFrom`.
+     * Captured at construction so it survives lifecycle cleanup.
+     */
+    readonly isResume: boolean;
+    constructor(options: {
+        sessionId: string;
+        harness: HarnessAgentAdapter;
+        underlyingSession: HarnessAgentAdapterSession;
+        sandboxSession: HarnessV1NetworkSandboxSession;
+        sandboxProvider: HarnessV1SandboxProvider;
+        leasedBridgePort?: number;
+        sessionWorkDir: string;
+        toolApproval: HarnessAgentToolApprovalConfiguration | undefined;
+        pendingToolApprovals?: readonly HarnessAgentPendingToolApproval[];
+        turnState?: HarnessAgentTurnState;
+    });
+    promptTurn<TOOLS extends ToolSet, RUNTIME_CONTEXT extends Context>(options: {
+        prompt: HarnessAgentPrompt;
+        instructions: string | undefined;
+        tools: TOOLS;
+        activeTools: ToolSet;
+        toolSpecs: HarnessAgentToolSpec[];
+        builtinToolFiltering: HarnessV1BuiltinToolFiltering | undefined;
+        runtimeContext: RUNTIME_CONTEXT;
+        abortSignal: AbortSignal | undefined;
+        telemetry: TelemetryOptions | undefined;
+    }): HarnessAgentTurnResult<TOOLS, RUNTIME_CONTEXT>;
+    continueTurn<TOOLS extends ToolSet, RUNTIME_CONTEXT extends Context>(options: {
+        instructions: string | undefined;
+        tools: TOOLS;
+        activeTools: ToolSet;
+        toolSpecs: HarnessAgentToolSpec[];
+        builtinToolFiltering: HarnessV1BuiltinToolFiltering | undefined;
+        runtimeContext: RUNTIME_CONTEXT;
+        abortSignal: AbortSignal | undefined;
+        telemetry: TelemetryOptions | undefined;
+        toolApprovalContinuations?: readonly HarnessAgentToolApprovalContinuation[] | undefined;
+    }): HarnessAgentTurnResult<TOOLS, RUNTIME_CONTEXT>;
+    /**
+     * Ask the underlying runtime to compact its context. The runtime performs
+     * the compaction itself; when it completes, a `compaction` part appears on
+     * the active (or next) turn's stream. Safe to call between turns for
+     * runtimes whose compaction is session-scoped (e.g. Pi).
+     *
+     * Throws `HarnessCapabilityUnsupportedError` for harnesses that cannot
+     * trigger compaction manually (e.g. Codex, which still auto-compacts under
+     * the hood). Throws if the session has ended.
+     */
+    compact(customInstructions?: string): Promise<void>;
+    /**
+     * Park the session, returning a payload the caller can persist and later
+     * pass to `agent.createSession({ sessionId, resumeFrom })` to reconnect.
+     * The runtime and sandbox keep running; this local session handle becomes
+     * unusable.
+     */
+    detach(): Promise<HarnessAgentResumeSessionState>;
+    /**
+     * Persist enough state to resume later, then stop the runtime and sandbox.
+     * Returns the resume state for a future
+     * `agent.createSession({ sessionId, resumeFrom })` call.
+     */
+    stop(): Promise<HarnessAgentResumeSessionState>;
+    /**
+     * Stop the runtime and discard resumability. The sandbox is destroyed when
+     * the provider supports destruction; otherwise it is stopped.
+     */
+    destroy(): Promise<void>;
+    /**
+     * Gracefully freeze the active turn at the slice boundary and return the
+     * continuation payload, **leaving the sandbox/runtime running** so the next
+     * process can continue. Resolves once the in-flight `stream()` /
+     * `continueStream()` has cleanly wound down at a precise cursor (see
+     * `doSuspendTurn`).
+     *
+     * After this call the session is detached. This in-process handle no
+     * longer drives turns; a future slice creates a fresh session from the
+     * returned state. The sandbox is **not** stopped and no port lease is
+     * released, because bridge-backed adapters may still have a live bridge on
+     * that port.
+     */
+    suspendTurn(): Promise<HarnessAgentContinueTurnState>;
+    private getPendingToolApprovals;
+    private addPendingToolApprovals;
+    private suspendCurrentTurn;
+    private toResumeStateWithContinuation;
+    private requirePromptableTurn;
+    private requireContinuableTurn;
+    private markAwaitingApprovalIfActive;
+    private startTrackedTurn;
+    private trackTurnCompletion;
+    private finishTrackedTurn;
+    private endLocalHandle;
+    private releasePortLease;
+    private requireReusableSession;
+}
+
+/**
+ * Required `session` extension on every `HarnessAgent.generate` /
+ * `HarnessAgent.stream` call. The agent operates exclusively on the
+ * `HarnessAgentSession` the caller passes in — it owns no session
+ * state of its own.
+ */
+interface HarnessAgentCallExtensions {
+    /**
+     * Active session returned by `agent.createSession(...)`. Drives the
+     * underlying harness adapter for this turn.
+     */
+    session: HarnessAgentSession;
+}
+/**
+ * AI SDK `Agent` implementation that drives a third-party agent runtime
+ * through a harness adapter (Claude Code, Codex, …).
+ *
+ * Behaviour summary:
+ *  - **Stateless definition.** Construct once at module scope. The agent
+ *    holds the harness adapter, the merged tool surface, the sandbox
+ *    provider and other config — never a live session. Per-call data
+ *    (prompt, abort signal, the `HarnessAgentSession`) lives on
+ *    `generate()` / `stream()`.
+ *  - **Explicit sessions.** Callers spawn sessions with
+ *    `agent.createSession(...)`, pass the returned
+ *    `HarnessAgentSession` on every `generate` / `stream`, and end it via
+ *    `session.detach()`, `session.stop()`, or `session.destroy()`.
+ *  - **Cross-process resume.** `createSession({ sessionId, resumeFrom })`
+ *    resumes from state previously returned by `session.detach()` or
+ *    `session.stop()`. The framework validates `resumeFrom` against the
+ *    harness's `lifecycleStateSchema` before handing it to the adapter.
+ *    `createSession({ sessionId, continueFrom })` resumes from state returned
+ *    by `session.suspendTurn()` before `continueStream()` /
+ *    `continueGenerate()`.
+ *  - **Host tool execution.** User tools passed in `settings.tools` are
+ *    executed on the host whenever the underlying runtime calls them;
+ *    the result is fed back to the harness via `submitToolResult`.
+ *    Adapter builtin tools (e.g. Claude Code's `Bash`) pass through
+ *    untouched.
+ *  - **Sandbox propagation.** `settings.sandbox` is a sandbox provider.
+ *    On `createSession`, the agent calls `provider.createSession()` (or
+ *    `resumeSession()`) and passes the resulting network sandbox session into
+ *    `doStart`. Its `restricted()` view (a tool-safe
+ *    `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> {
+    readonly version: "agent-v1";
+    readonly id: string | undefined;
+    /**
+     * Merged tool set exposed to AI SDK consumers: harness builtins +
+     * user-defined tools, with user tools overriding builtins on key
+     * collision. Built once at construction time so the typed surface is
+     * stable across calls.
+     */
+    readonly tools: HarnessAllTools<THarness, TUserTools>;
+    private readonly settings;
+    private readonly sandboxConfig;
+    private readonly activeUserTools;
+    private readonly builtinToolFiltering;
+    private readonly permissionMode;
+    constructor(settings: HarnessAgentSettings<THarness, TUserTools>);
+    /** Identifier of the harness backing this agent. */
+    get harnessId(): string;
+    /**
+     * Start a fresh session, or resume from state previously returned by
+     * `session.detach()` or `session.stop()`. The returned
+     * `HarnessAgentSession` must be passed to subsequent `generate` / `stream`
+     * calls; end it with `session.detach()`, `session.stop()`, or
+     * `session.destroy()`.
+     */
+    createSession(options?: {
+        /**
+         * Optional stable identifier for the underlying sandbox/session.
+         * When omitted the agent generates one. Supply the original
+         * `session.sessionId` together with `resumeFrom` to reattach a
+         * previously ended session across processes.
+         */
+        sessionId?: string;
+        /**
+         * Resume payload returned by a prior `session.detach()` or
+         * `session.stop()`. Must be accompanied by the original `sessionId`; the
+         * framework validates it against `harness.lifecycleStateSchema` before
+         * handing it to the adapter.
+         */
+        resumeFrom?: HarnessAgentResumeSessionState;
+        /**
+         * Continuation payload returned by a prior `session.suspendTurn()`. Must be
+         * accompanied by the original `sessionId`; the framework validates it before
+         * handing it to the adapter.
+         */
+        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>>;
+    /**
+     * Continue the in-flight turn **without a new prompt**, draining it like
+     * {@link generate}. Used after `createSession({ continueFrom })` to finish
+     * consuming a turn that crossed a process boundary.
+     */
+    continueGenerate(options: {
+        session: HarnessAgentSession;
+        toolApprovalContinuations?: readonly HarnessAgentToolApprovalContinuation[];
+        abortSignal?: AbortSignal;
+    }): Promise<GenerateTextResult<HarnessAllTools<THarness, TUserTools>, RUNTIME_CONTEXT, never>>;
+    /**
+     * 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
+     * (or finished) in the runtime after a process boundary — the workflow slice
+     * loop calls this on every slice after the first. Routes through the adapter's
+     * `doContinueTurn`; what it can guarantee (lossless attach vs. lossy rerun)
+     * follows from how the adapter resumed the session.
+     */
+    continueStream(options: {
+        session: HarnessAgentSession;
+        toolApprovalContinuations?: readonly HarnessAgentToolApprovalContinuation[];
+        abortSignal?: AbortSignal;
+    }): Promise<StreamTextResult<HarnessAllTools<THarness, TUserTools>, RUNTIME_CONTEXT, never>>;
+    private _startTurn;
+    private _acquireSandbox;
+    private _resolveTurnInput;
+    private _toToolSpecs;
+    private _toGenerateResult;
+}
+
+type SandboxBootstrapSettings = Omit<HarnessAgentSandboxConfig, 'onSession'>;
+/**
+ * Prepare a harness's sandbox template without running an agent. Idempotent: if
+ * the template already exists (snapshot present, or marker on a non-snapshot
+ * provider), this resolves quickly.
+ *
+ * Use from a CI/deploy script to amortize the first-session cost so production
+ * sessions always resume from snapshot. For adapters without a bootstrap
+ * recipe (no `getBootstrap`) this is a no-op.
+ *
+ * The temporary network sandbox session created during preparation is stopped
+ * before the function resolves; the snapshot/template state persists in the
+ * provider's native storage (for Vercel: as the `currentSnapshotId` of the
+ * named template sandbox).
+ */
+declare function prepareHarnessSandboxTemplate(options: {
+    readonly harness: HarnessAgentAdapter;
+    readonly sandboxProvider: HarnessV1SandboxProvider;
+    readonly sandboxConfig?: SandboxBootstrapSettings;
+    readonly abortSignal?: AbortSignal;
+}): Promise<void>;
+/** @deprecated Use `prepareHarnessSandboxTemplate` instead. */
+declare const prewarmHarness: typeof prepareHarnessSandboxTemplate;
+
+type PrepareSandboxForHarnessResult = {
+    readonly identity?: string;
+    readonly recipeIdentities: Record<string, string>;
+    readonly skippedHarnessIds: ReadonlyArray<string>;
+};
+/**
+ * Apply one or more harness bootstrap recipes to an existing sandbox session.
+ *
+ * Use this when a sandbox provider or caller wants to prepare a reusable
+ * sandbox template, image, or snapshot before creating live harness sessions.
+ *
+ * The function writes each adapter's bridge/bootstrap files, runs its install
+ * commands, and then returns a deterministic identity derived from the applied
+ * recipes and optional sandbox bootstrap configuration. Providers can use that
+ * identity as the cache key for the prepared artifact.
+ *
+ * This function only mutates the supplied sandbox; the caller is responsible for
+ * committing, snapshotting, or otherwise persisting that modified filesystem.
+ * 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.
+ */
+declare function prepareSandboxForHarness(options: {
+    readonly session: Experimental_SandboxSession;
+    readonly harnesses: ReadonlyArray<HarnessAgentAdapter>;
+    readonly sandboxConfig?: HarnessAgentSandboxConfig;
+    readonly abortSignal?: AbortSignal;
+}): Promise<PrepareSandboxForHarnessResult>;
+
+declare const symbol$1: unique symbol;
+/**
+ * Base error type for failures originating in or signalled by a harness
+ * adapter. Specific failure modes (e.g. unsupported capability) extend this
+ * class.
+ */
+declare class HarnessError extends AISDKError {
+    private readonly [symbol$1];
+    constructor({ message, cause }: {
+        message: string;
+        cause?: unknown;
+    });
+    static isInstance(error: unknown): error is HarnessError;
+}
+
+declare const symbol: 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.
+ *
+ * The caller supplies the full human-readable message. Optional `harnessId`
+ * is recorded as structured context for tooling.
+ */
+declare class HarnessCapabilityUnsupportedError extends HarnessError {
+    private readonly [symbol];
+    readonly harnessId?: string;
+    constructor({ message, harnessId, cause, }: {
+        message: string;
+        harnessId?: string;
+        cause?: unknown;
+    });
+    static isInstance(error: unknown): error is HarnessCapabilityUnsupportedError;
+}
+
+/**
+ * A harness observability reporter that writes a unified, non-lossy
+ * `events.jsonl` containing **both** the telemetry span lifecycle (turn / step
+ * / tool) **and** the forwarded bridge diagnostics (console lines + structured
+ * events). It is a single object registered in `telemetry.integrations`: the
+ * framework drives its `Telemetry` methods for spans and calls
+ * `ingestDiagnostic` for diagnostics.
+ *
+ * No external collector or OTel setup required — this is the AI-SDK-idiomatic
+ * replacement for the original SDK's host-side artifact files.
+ */
+interface FileReporterOptions {
+    /** Directory for `events.jsonl` (created if absent). */
+    dir: string;
+    /**
+     * Buffer a turn's records in memory and write them only if the turn produced
+     * an error (an `error`-level diagnostic, a failed tool, or an error finish).
+     * Default false (write everything).
+     */
+    failOnly?: boolean;
+    /** File name within `dir`. Default `events.jsonl`. */
+    fileName?: string;
+}
+type FileReporter = Telemetry & HarnessDiagnosticConsumer;
+declare function createFileReporter(options: FileReporterOptions): FileReporter;
+
+/**
+ * A harness observability reporter that renders an ASCII trace tree of a
+ * turn's span lifecycle (turn → steps → tools) to a stream at turn end. It is a
+ * `Telemetry` integration — register it in `telemetry.integrations`. Useful for
+ * zero-setup local debugging when no OTel collector is wired up; a real OTel
+ * backend (via `@ai-sdk/otel`) is a strict superset.
+ */
+interface TraceTreeReporterOptions {
+    /** Where to write the rendered tree. Default `process.stderr.write`. */
+    write?: (chunk: string) => void;
+}
+declare function createTraceTreeReporter(options?: TraceTreeReporterOptions): Telemetry;
+
+export { type FileReporter, type FileReporterOptions, HarnessAgent, type HarnessAgentAdapter, type HarnessAgentAdapterSession, type HarnessAgentBuiltinTool, type HarnessAgentBuiltinToolName, type HarnessAgentBuiltinToolUseKind, type HarnessAgentBuiltinTools, type HarnessAgentContinueTurnOptions, type HarnessAgentContinueTurnState, type HarnessAgentLifecycleState, type HarnessAgentPendingToolApproval, type HarnessAgentPermissionMode, type HarnessAgentPrompt, type HarnessAgentPromptControl, type HarnessAgentPromptTurnOptions, type HarnessAgentResumeSessionState, type HarnessAgentSandboxConfig, HarnessAgentSession, type HarnessAgentSettings, type HarnessAgentSkill, type HarnessAgentStartOptions, type HarnessAgentStreamPart, type HarnessAgentToolApprovalConfiguration, type HarnessAgentToolApprovalContinuation, type HarnessAgentToolSpec, type HarnessAllTools, HarnessCapabilityUnsupportedError, type HarnessDebugConfig, type HarnessDebugLevel, type HarnessDiagnostic, type HarnessDiagnosticConsumer, HarnessError, type PrepareSandboxForHarnessResult, type TraceTreeReporterOptions, collectHarnessAgentToolApprovalContinuations, createFileReporter, createTraceTreeReporter, prepareHarnessSandboxTemplate, prepareSandboxForHarness, prewarmHarness };