@ai-sdk/harness 0.0.0 → 1.0.0-canary.3

package/dist/agent/index.d.ts

@@ -0,0 +1,1480 @@
+import { Experimental_SandboxSession, UserModelMessage, ToolSet, FlexibleSchema, ToolApprovalResponse, ModelMessage, Context, AssistantModelMessage, ToolModelMessage } from '@ai-sdk/provider-utils';
+import { z } from 'zod/v4';
+import * as _ai_sdk_provider from '@ai-sdk/provider';
+import { JSONValue, LanguageModelV4ToolCall, LanguageModelV4ToolApprovalRequest, LanguageModelV4ToolResult, LanguageModelV4FinishReason, LanguageModelV4Usage, JSONSchema7 } from '@ai-sdk/provider';
+import * as ai from 'ai';
+import { ToolApprovalStatus, TelemetryOptions, StreamTextResult, TextStreamPart, ProviderMetadata, CallWarning, ContentPart, FinishReason, LanguageModelUsage, StepResult, UIMessage, UIMessageStreamOptions, InferUIMessageChunk, Agent, AgentCallParameters, GenerateTextResult, AgentStreamParameters } from 'ai';
+
+/**
+ * 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 the resume payload 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;
+};
+/**
+ * Opaque payload returned by resumable session lifecycle methods and accepted
+ * by a future `HarnessV1.doStart({ resumeFrom })` to resume the same
+ * underlying session.
+ *
+ * The contents are entirely adapter-defined. Consumers (including
+ * `HarnessAgent`) treat the value as opaque; adapters describe and validate
+ * their own schemas via `HarnessV1.resumeStateSchema`.
+ */
+type HarnessV1ResumeState = {
+    /**
+     * Identifier of the harness that produced this state. Used by adapters to
+     * refuse mismatched resume 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;
+    /**
+     * Framework-owned pending approval records. These are intentionally outside
+     * adapter-defined `data` so callers can persist the entire resume payload
+     * without the harness framework owning storage.
+     */
+    readonly pendingToolApprovals?: readonly HarnessV1PendingToolApproval[];
+};
+
+/**
+ * A self-contained instruction bundle the underlying runtime can load into
+ * its context. Adapters decide how to surface skills to the runtime — the
+ * `claude` CLI auto-discovers skills materialised as Markdown files in
+ * `.claude/skills`, while the `codex` CLI has no skill mechanism and the
+ * adapter inlines them into every user message.
+ */
+type HarnessV1Skill = {
+    /** Stable identifier for the skill (kebab-case slug). */
+    readonly name: string;
+    /**
+     * Short, model-facing description. For runtimes that auto-select skills
+     * (Claude Code), this is what the runtime sees to decide whether the
+     * skill is relevant; for runtimes that load every skill on every turn
+     * (Codex), it appears alongside the content.
+     */
+    readonly description: string;
+    /** Full skill content the model loads when the skill is active. */
+    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;
+};
+
+/**
+ * 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 — the `claude` CLI
+     * picks them up from `.claude/skills/*.md`, while the `codex` adapter
+     * inlines them into every user message.
+     */
+    readonly skills?: ReadonlyArray<HarnessV1Skill>;
+    /**
+     * Optional resume payload returned by a prior session lifecycle method. When
+     * provided, the adapter should resume the existing session rather than create
+     * a fresh one.
+     */
+    readonly resumeFrom?: HarnessV1ResumeState;
+    /**
+     * 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;
+    /**
+     * 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 a resume payload. 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({ resumeFrom })`:
+     *
+     *  - 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 resume 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<HarnessV1ResumeState>;
+    /**
+     * Detach from the underlying runtime without tearing it down, returning a
+     * payload the host can later pass to `HarnessV1.doStart({ resumeFrom })`
+     * to reconnect. 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 state they can while leaving the sandbox running.
+     */
+    doDetach(): PromiseLike<HarnessV1ResumeState>;
+    /**
+     * 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<HarnessV1ResumeState>;
+    /**
+     * Stop the underlying runtime without returning resume 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;
+    /**
+     * Optional schema for resume payloads returned by the session lifecycle.
+     * When present, the adapter promises that exported state validated by this
+     * schema can be re-imported in a future `doStart({ resumeFrom })` call.
+     * Hosts use this to persist and re-hydrate resume payloads safely.
+     */
+    readonly resumeStateSchema?: 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 (or resume via `resumeFrom`). The host then issues
+     * prompts against the returned session, ending with `doDetach`, `doStop`, or
+     * `doDestroy`.
+     */
+    doStart(options: HarnessV1StartOptions): PromiseLike<HarnessV1Session>;
+};
+
+/**
+ * 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>;
+}
+
+/** 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;
+}
+
+type HarnessAgentToolApprovalConfiguration = Readonly<Record<string, ToolApprovalStatus>>;
+/**
+ * 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 HarnessAgentSettings<THarness extends HarnessV1<any> = HarnessV1, 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
+     * `HarnessV1ToolSpec`; 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<HarnessV1Skill>;
+    /**
+     * 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?: HarnessV1PermissionMode;
+    /**
+     * 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;
+    /**
+     * 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 onSandboxSession?: (opts: {
+        readonly session: Experimental_SandboxSession;
+        readonly sessionWorkDir: string;
+        readonly abortSignal?: AbortSignal;
+    }) => Promise<void>;
+    /**
+     * 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;
+};
+
+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[];
+
+/**
+ * Concrete `StreamTextResult` implementation backed by a single
+ * harness prompt turn.
+ *
+ * Wraps a `ReadableStream<TextStreamPart<TOOLS>>` that the calling
+ * driver pushes events into. Every `PromiseLike` accessor is backed by a
+ * `DelayedPromise` so the AI SDK consumer surface stays identical to
+ * `streamText`'s — consumers can `await result.text` or iterate
+ * `result.fullStream`, in either order.
+ *
+ * Each `finish-step` boundary in the driver translates to a `StepResult`
+ * built via `DefaultStepResult`. Step content is accumulated as
+ * `ContentPart[]` and fed straight to `DefaultStepResult`, which derives
+ * `text`, `toolCalls`, `toolResults`, `reasoning`, etc. via its getters.
+ *
+ * The Node.js response helpers (`pipeUIMessageStreamToResponse`,
+ * `pipeTextStreamToResponse`, `toTextStreamResponse`) and the
+ * output-specification surfaces (`partialOutputStream`/`elementStream`) are not
+ * implemented yet — they throw a clear error.
+ */
+declare class HarnessStreamTextResult<TOOLS extends ToolSet, RUNTIME_CONTEXT extends Context> implements StreamTextResult<TOOLS, RUNTIME_CONTEXT, never> {
+    private readonly _content;
+    private readonly _text;
+    private readonly _reasoning;
+    private readonly _reasoningText;
+    private readonly _files;
+    private readonly _sources;
+    private readonly _toolCalls;
+    private readonly _staticToolCalls;
+    private readonly _dynamicToolCalls;
+    private readonly _toolResults;
+    private readonly _staticToolResults;
+    private readonly _dynamicToolResults;
+    private readonly _finishReason;
+    private readonly _rawFinishReason;
+    private readonly _usage;
+    private readonly _warnings;
+    private readonly _steps;
+    private readonly _finalStep;
+    private readonly _request;
+    private readonly _response;
+    private readonly _responseMessages;
+    private readonly _providerMetadata;
+    private readonly fullStreamController;
+    readonly stream: AsyncIterableStream<TextStreamPart<TOOLS>>;
+    readonly fullStream: AsyncIterableStream<TextStreamPart<TOOLS>>;
+    readonly textStream: AsyncIterableStream<string>;
+    private readonly stepsBuffer;
+    private currentStepContent;
+    private currentStepWarnings;
+    private stepNumber;
+    private readonly tools;
+    private readonly runtimeContext;
+    private readonly toolsContext;
+    private readonly providerName;
+    private readonly modelId;
+    private accumulatedUsage;
+    private finalProviderMetadata;
+    private finalFinishReason;
+    private finalRawFinishReason;
+    private aggregateWarnings;
+    private settled;
+    constructor(options: {
+        tools: TOOLS;
+        runtimeContext: RUNTIME_CONTEXT;
+        toolsContext: never;
+        harnessId: string;
+        sessionId: string;
+    });
+    /**
+     * Push a translated `TextStreamPart` into `fullStream` and accumulate it
+     * into the current step's content array where applicable.
+     */
+    enqueue(part: TextStreamPart<TOOLS>): void;
+    /**
+     * Mark the end of a step. Builds a `StepResult` from the accumulated
+     * content and records it in the steps array. Accepts the V4-shaped
+     * finish reason / usage the harness emits and normalizes to AI SDK's
+     * flat shape internally.
+     */
+    finishStep(input: {
+        finishReason: LanguageModelV4FinishReason;
+        usage: LanguageModelV4Usage;
+        providerMetadata: ProviderMetadata | undefined;
+        warnings: CallWarning[];
+    }): void;
+    /**
+     * Resolve every delayed promise and close `fullStream`. Idempotent.
+     */
+    finish(): Promise<void>;
+    /**
+     * Surface a fatal error as a stream `error` part + reject every delayed
+     * promise so awaiting consumers stop hanging. Idempotent.
+     */
+    fail(error: unknown): void;
+    get content(): Promise<ContentPart<TOOLS>[]>;
+    get text(): Promise<string>;
+    get reasoning(): Promise<(ai.ReasoningOutput | ai.ReasoningFileOutput)[]>;
+    get reasoningText(): Promise<string | undefined>;
+    get files(): Promise<ai.Experimental_GeneratedImage[]>;
+    get sources(): Promise<_ai_sdk_provider.LanguageModelV4Source[]>;
+    get toolCalls(): Promise<ai.TypedToolCall<TOOLS>[]>;
+    get staticToolCalls(): Promise<ai.StaticToolCall<TOOLS>[]>;
+    get dynamicToolCalls(): Promise<ai.DynamicToolCall[]>;
+    get toolResults(): Promise<ai.TypedToolResult<TOOLS>[]>;
+    get staticToolResults(): Promise<ai.StaticToolResult<TOOLS>[]>;
+    get dynamicToolResults(): Promise<ai.DynamicToolResult[]>;
+    get finishReason(): Promise<FinishReason>;
+    get rawFinishReason(): Promise<string | undefined>;
+    get usage(): Promise<LanguageModelUsage>;
+    get totalUsage(): Promise<LanguageModelUsage>;
+    get warnings(): Promise<_ai_sdk_provider.SharedV4Warning[] | undefined>;
+    get steps(): Promise<StepResult<TOOLS, RUNTIME_CONTEXT>[]>;
+    get finalStep(): Promise<StepResult<TOOLS, RUNTIME_CONTEXT>>;
+    get request(): Promise<ai.LanguageModelRequestMetadata>;
+    get response(): Promise<ai.LanguageModelResponseMetadata>;
+    get responseMessages(): Promise<(AssistantModelMessage | ToolModelMessage)[]>;
+    get providerMetadata(): Promise<_ai_sdk_provider.SharedV4ProviderMetadata | undefined>;
+    get experimental_partialOutputStream(): never;
+    get partialOutputStream(): never;
+    get elementStream(): never;
+    get output(): never;
+    consumeStream(): Promise<void>;
+    toUIMessageStream<UI_MESSAGE extends UIMessage>({ originalMessages, generateMessageId, onFinish, messageMetadata, sendReasoning, sendSources, sendStart, sendFinish, onError, }?: UIMessageStreamOptions<UI_MESSAGE>): AsyncIterableStream<InferUIMessageChunk<UI_MESSAGE>>;
+    pipeUIMessageStreamToResponse(): never;
+    pipeTextStreamToResponse(): never;
+    toUIMessageStreamResponse<UI_MESSAGE extends UIMessage>({ originalMessages, generateMessageId, onFinish, messageMetadata, sendReasoning, sendSources, sendStart, sendFinish, onError, ...init }?: ResponseInit & {
+        consumeSseStream?: (options: {
+            stream: ReadableStream<string>;
+        }) => PromiseLike<void> | void;
+    } & UIMessageStreamOptions<UI_MESSAGE>): Response;
+    toTextStreamResponse(): never;
+    private appendToCurrentStepContent;
+}
+type AsyncIterableStream<T> = ReadableStream<T> & AsyncIterable<T>;
+
+/**
+ * Drive one prompt turn end-to-end:
+ *  - call `session.doPromptTurn` via `toHarnessStream`
+ *  - translate harness events to AI SDK `TextStreamPart`s and push into the
+ *    result object
+ *  - execute host-side user tools when their `tool-call` events arrive and
+ *    submit results back to the harness
+ *  - close the result when the harness signals `finish` (or on error)
+ *
+ * Returns the result synchronously after the stream is wired up; callers
+ * await its `PromiseLike` accessors to observe completion.
+ */
+declare function runPrompt<TOOLS extends ToolSet, RUNTIME_CONTEXT extends Context>(input: {
+    harness: HarnessV1;
+    session: HarnessV1Session;
+    /**
+     * Turn entry point. `'prompt'` (default) starts a new turn from `prompt`;
+     * `'continue'` continues the in-flight turn via `doContinueTurn` and ignores
+     * `prompt`/`instructions`.
+     */
+    mode?: 'prompt' | 'continue';
+    /** Required for `mode: 'prompt'`; absent for `mode: 'continue'`. */
+    prompt?: HarnessV1Prompt;
+    instructions: string | undefined;
+    tools: TOOLS;
+    toolSpecs: HarnessV1ToolSpec[];
+    sandboxSession: Experimental_SandboxSession;
+    sessionWorkDir: string;
+    runtimeContext: RUNTIME_CONTEXT;
+    abortSignal: AbortSignal | undefined;
+    telemetry?: TelemetryOptions | undefined;
+    toolApproval?: HarnessAgentToolApprovalConfiguration | undefined;
+    pendingToolApprovals?: readonly HarnessV1PendingToolApproval[];
+    toolApprovalContinuations?: readonly HarnessAgentToolApprovalContinuation[] | undefined;
+    onPendingToolApproval?: (approval: HarnessV1PendingToolApproval) => void;
+    onToolApprovalSettled?: (approvalId: string) => void;
+}): {
+    result: HarnessStreamTextResult<TOOLS, RUNTIME_CONTEXT>;
+    done: Promise<void>;
+};
+
+/**
+ * Live harness session held by the caller.
+ *
+ * Created by {@link import('./harness-agent').HarnessAgent.createSession}.
+ * Owns the underlying `HarnessV1Session`, 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 stopped;
+    /**
+     * Whether this session was created from a resume payload. Captured at
+     * construction so it survives lifecycle cleanup.
+     */
+    readonly isResume: boolean;
+    constructor(options: {
+        sessionId: string;
+        harness: HarnessV1;
+        underlyingSession: HarnessV1Session;
+        sandboxSession: HarnessV1NetworkSandboxSession;
+        sandboxProvider: HarnessV1SandboxProvider;
+        leasedBridgePort?: number;
+        sessionWorkDir: string;
+        toolApproval: HarnessAgentToolApprovalConfiguration | undefined;
+        pendingToolApprovals?: readonly HarnessV1PendingToolApproval[];
+    });
+    promptTurn<TOOLS extends ToolSet, RUNTIME_CONTEXT extends Context>(options: {
+        prompt: HarnessV1Prompt;
+        instructions: string | undefined;
+        tools: TOOLS;
+        toolSpecs: HarnessV1ToolSpec[];
+        runtimeContext: RUNTIME_CONTEXT;
+        abortSignal: AbortSignal | undefined;
+        telemetry: TelemetryOptions | undefined;
+    }): ReturnType<typeof runPrompt<TOOLS, RUNTIME_CONTEXT>>;
+    continueTurn<TOOLS extends ToolSet, RUNTIME_CONTEXT extends Context>(options: {
+        instructions: string | undefined;
+        tools: TOOLS;
+        toolSpecs: HarnessV1ToolSpec[];
+        runtimeContext: RUNTIME_CONTEXT;
+        abortSignal: AbortSignal | undefined;
+        telemetry: TelemetryOptions | undefined;
+        toolApprovalContinuations?: readonly HarnessAgentToolApprovalContinuation[] | undefined;
+    }): ReturnType<typeof runPrompt<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<HarnessV1ResumeState>;
+    /**
+     * 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<HarnessV1ResumeState>;
+    /**
+     * 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
+     * resume payload, **leaving the sandbox/runtime running** so the next process
+     * can resume. Resolves once the in-flight `stream()`/`continueTurn()`
+     * has cleanly wound down at a precise cursor (see
+     * {@link HarnessV1Session.doSuspendTurn}).
+     *
+     * After this call the session is marked stopped. 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<HarnessV1ResumeState>;
+    private getPendingToolApprovals;
+    private withPendingToolApprovals;
+    private endLocalHandle;
+    private releasePortLease;
+    private requireReusableSession;
+}
+
+/** Extract the builtin tool set type from a `HarnessV1<...>` parameter. */
+type BuiltinToolsOf<H> = H extends HarnessV1<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 HarnessV1<any>, TUserTools extends ToolSet> = Omit<BuiltinToolsOf<THarness>, keyof TUserTools> & TUserTools;
+/**
+ * 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 `HarnessV1` 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 `resumeStateSchema` before handing it to the adapter.
+ *  - **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 HarnessV1<any> = HarnessV1, 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 userTools;
+    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.resumeStateSchema` before handing
+         * it to the adapter.
+         */
+        resumeFrom?: HarnessV1ResumeState;
+        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**, 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.
+     */
+    continueTurn(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;
+}
+
+/**
+ * Pre-build 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 pre-warm 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 prewarmHarness(options: {
+    readonly harness: HarnessV1;
+    readonly sandboxProvider: HarnessV1SandboxProvider;
+    readonly abortSignal?: AbortSignal;
+}): Promise<void>;
+
+export { HarnessAgent, HarnessAgentSession, type HarnessAgentSettings, type HarnessAgentToolApprovalConfiguration, type HarnessAgentToolApprovalContinuation, type HarnessDebugConfig, type HarnessDebugLevel, type HarnessDiagnostic, type HarnessDiagnosticConsumer, collectHarnessAgentToolApprovalContinuations, prewarmHarness };