@ai-sdk/harness 0.0.0 → 1.0.0-beta.14

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

@@ -0,0 +1,123 @@
+import type { Experimental_SandboxSession as SandboxSession } from '@ai-sdk/provider-utils';
+
+/**
+ * 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.
+ */
+export interface HarnessV1NetworkSandboxSession extends 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: () => 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'`.
+ */
+export 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>;
+    };

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

@@ -0,0 +1,20 @@
+import type {
+  HarnessV1DebugConfig,
+  HarnessV1Diagnostic,
+} from './harness-v1-diagnostic';
+
+/**
+ * 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.
+ */
+export 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;
+};

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-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,272 @@
+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 {
+  HarnessV1ContinueTurnState,
+  HarnessV1ResumeSessionState,
+} from './harness-v1-lifecycle-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.
+   */
+  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;
+
+  /**
+   * 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;
+};
+
+/**
+ * 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;
+};
+
+/**
+ * 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 `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>;
+};

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

@@ -0,0 +1,36 @@
+/**
+ * A self-contained instruction bundle the underlying runtime can load into
+ * its context. Adapters decide how to surface skills to the runtime.
+ */
+export 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>;
+};
+
+export 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;
+};