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

package/src/v1/harness-v1-permission-mode.ts

@@ -0,0 +1,11 @@
+/**
+ * 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.
+ */
+export type HarnessV1PermissionMode =
+  | 'allow-reads'
+  | 'allow-edits'
+  | 'allow-all';

package/src/v1/harness-v1-prompt-control.ts

@@ -0,0 +1,41 @@
+/**
+ * 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`).
+ */
+export 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>;
+};

package/src/v1/harness-v1-prompt.ts

@@ -0,0 +1,11 @@
+import type { UserModelMessage } from '@ai-sdk/provider-utils';
+
+/**
+ * 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`.
+ */
+export type HarnessV1Prompt = string | UserModelMessage;

package/src/v1/harness-v1-resume-state.ts

@@ -0,0 +1,46 @@
+import type { JSONValue } from '@ai-sdk/provider';
+
+export 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`.
+ */
+export 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[];
+};

package/src/v1/harness-v1-sandbox-provider.ts

@@ -0,0 +1,76 @@
+import type { Experimental_SandboxSession as SandboxSession } from '@ai-sdk/provider-utils';
+import type { HarnessV1NetworkSandboxSession } from './harness-v1-network-sandbox-session';
+
+/**
+ * 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()`.
+ */
+export 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: 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>;
+}

package/src/v1/harness-v1-session.ts

@@ -0,0 +1,268 @@
+import type { HarnessV1NetworkSandboxSession } from './harness-v1-network-sandbox-session';
+import type { HarnessV1Observability } from './harness-v1-observability';
+import type { HarnessV1PermissionMode } from './harness-v1-permission-mode';
+import type { HarnessV1Prompt } from './harness-v1-prompt';
+import type { HarnessV1PromptControl } from './harness-v1-prompt-control';
+import type { HarnessV1ResumeState } from './harness-v1-resume-state';
+import type { HarnessV1Skill } from './harness-v1-skill';
+import type { HarnessV1StreamPart } from './harness-v1-stream-part';
+import type { HarnessV1ToolSpec } from './harness-v1-tool-spec';
+
+/**
+ * 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.
+ */
+export 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`.
+ */
+export 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;
+};
+
+export type HarnessV1PromptOptions = HarnessV1PromptTurnOptions;
+
+/**
+ * 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.
+ */
+export 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;
+};
+
+export type HarnessV1ContinueOptions = HarnessV1ContinueTurnOptions;
+
+/**
+ * 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`.
+ */
+export 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>;
+};

package/src/v1/harness-v1-skill.ts

@@ -0,0 +1,22 @@
+/**
+ * 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.
+ */
+export 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;
+};