@coder/ai-sdk-sandbox 0.1.0

package/dist/index.d.ts

@@ -0,0 +1,447 @@
+import { HarnessV1SandboxProvider, HarnessV1NetworkSandboxSession } from '@ai-sdk/harness';
+import { Experimental_SandboxSession } from '@ai-sdk/provider-utils';
+
+/**
+ * Transport abstraction over a Coder workspace. The sandbox session talks to a
+ * workspace exclusively through this interface, which keeps the harness-facing
+ * session decoupled from *how* we reach Coder (the default is the `coder` CLI;
+ * tests inject a mock, and a future implementation could use the Coder REST API
+ * or a persistent SSH/SFTP connection).
+ */
+interface CoderTransport {
+    /** Run a command to completion, buffering stdout/stderr into strings. */
+    exec(options: TransportExecOptions): Promise<ExecResult>;
+    /** Start a long-running process and return streaming handles immediately. */
+    spawn(options: TransportExecOptions): SpawnedProcess;
+    /**
+     * Open a TCP port-forward from the host to a port inside the workspace and
+     * resolve once the local endpoint accepts connections.
+     */
+    forwardPort(options: ForwardPortOptions): Promise<PortForward>;
+    /** Ensure the workspace is started. Should be idempotent. */
+    start(workspace: string, options?: LifecycleOptions): Promise<void>;
+    /** Stop the workspace. Should be idempotent. */
+    stop(workspace: string, options?: LifecycleOptions): Promise<void>;
+    /** Delete the workspace. Must tolerate an already-stopped workspace. */
+    destroy(workspace: string, options?: LifecycleOptions): Promise<void>;
+    /**
+     * Look up a workspace's current status, or `null` if it does not exist. Used
+     * for get-or-create and for polling readiness after a create/start.
+     */
+    status(workspace: string, options?: LifecycleOptions): Promise<WorkspaceStatus | null>;
+    /**
+     * Create a workspace from a template. Resolves once the provisioner build
+     * completes (which is *not* the same as the agent being ready — poll
+     * {@link CoderTransport.status} for that).
+     */
+    create(options: CreateWorkspaceOptions): Promise<void>;
+    /**
+     * List the presets defined for a template (optionally a specific version).
+     * Used for preflight validation of a requested preset name.
+     */
+    listPresets(options: ListPresetsOptions): Promise<PresetInfo[]>;
+}
+/**
+ * Workspace-level build status (`latest_build.status` in the Coder API) — the
+ * computed state of the workspace, not the raw provisioner-job status. A fully
+ * started workspace reports `'running'`.
+ *
+ * The trailing `string & Record<never, never>` arm accepts statuses from newer
+ * Coder versions while preserving editor autocomplete for the known values (the
+ * same idiom is used by the other status unions below).
+ */
+type WorkspaceBuildStatus = "pending" | "starting" | "running" | "stopping" | "stopped" | "failed" | "canceling" | "canceled" | "deleting" | "deleted" | (string & Record<never, never>);
+/** Connectivity of a workspace agent (`agent.status`). */
+type WorkspaceAgentStatus = "connecting" | "connected" | "disconnected" | "timeout" | (string & Record<never, never>);
+/** Startup-script lifecycle of a workspace agent (`agent.lifecycle_state`). */
+type WorkspaceAgentLifecycle = "created" | "starting" | "start_timeout" | "start_error" | "ready" | "shutting_down" | "shutdown_timeout" | "shutdown_error" | "off" | (string & Record<never, never>);
+interface WorkspaceAgentInfo {
+    /** Agent name (e.g. `main`). */
+    name: string;
+    /** Connectivity to the control plane. */
+    status: WorkspaceAgentStatus;
+    /** Startup-script progress; `'ready'` means the startup script finished. */
+    lifecycleState: WorkspaceAgentLifecycle;
+}
+interface WorkspaceStatus {
+    /** Workspace name (without owner/agent qualifiers). */
+    name: string;
+    /** Workspace-level build status (`latest_build.status`). */
+    buildStatus: WorkspaceBuildStatus;
+    /** Direction of the latest build: `'start' | 'stop' | 'delete'`. */
+    transition: "start" | "stop" | "delete" | (string & Record<never, never>);
+    /** Agents across the latest build's resources. */
+    agents: WorkspaceAgentInfo[];
+}
+interface CreateWorkspaceOptions {
+    /** Workspace name to create, optionally `owner/name`. */
+    workspace: string;
+    /** Template name to create from. */
+    template: string;
+    /** Specific template version name; defaults to the template's active version. */
+    templateVersion?: string;
+    /** Named preset to apply (`--preset`); `'none'` forces no preset. */
+    preset?: string;
+    /** Rich parameter values, already stringified (`--parameter name=value`). */
+    parameters?: Record<string, string>;
+    /** Path to a YAML rich-parameter file (`--rich-parameter-file`). */
+    parameterFile?: string;
+    /** Accept template defaults for any parameter not otherwise provided. */
+    useParameterDefaults?: boolean;
+    /** Ephemeral (one-time build) parameter values, already stringified. */
+    ephemeralParameters?: Record<string, string>;
+    /** Auto-stop the workspace after this duration, e.g. `'8h'` (`--stop-after`). */
+    stopAfter?: string;
+    /** `--automatic-updates` setting. */
+    automaticUpdates?: "always" | "never";
+    /** Organization name or uuid for ambiguous template names (`--org`). */
+    org?: string;
+    abortSignal?: AbortSignal;
+}
+interface ListPresetsOptions {
+    template: string;
+    templateVersion?: string;
+    org?: string;
+    abortSignal?: AbortSignal;
+}
+interface PresetInfo {
+    name: string;
+    /** Whether the template author marked this as the default preset. */
+    default: boolean;
+    description?: string;
+}
+interface TransportExecOptions {
+    /** Workspace reference: `[owner/]workspace[.agent]`. */
+    workspace: string;
+    /** Command to run, as a shell string executed by bash inside the workspace. */
+    command: string;
+    /** Absolute working directory to run in. */
+    workingDirectory?: string;
+    /** Environment variables to set for the command (remote-side). */
+    env?: Record<string, string>;
+    /** Payload written to the command's stdin, then closed. */
+    stdin?: Uint8Array | string;
+    abortSignal?: AbortSignal;
+}
+interface ExecResult {
+    exitCode: number;
+    stdout: string;
+    stderr: string;
+}
+/**
+ * Handle to a spawned process. Structurally compatible with the AI SDK's
+ * `Experimental_SandboxProcess`, so the session can return it directly.
+ */
+interface SpawnedProcess {
+    readonly pid?: number;
+    readonly stdout: ReadableStream<Uint8Array>;
+    readonly stderr: ReadableStream<Uint8Array>;
+    wait(): Promise<{
+        exitCode: number;
+    }>;
+    kill(): Promise<void>;
+}
+interface ForwardPortOptions {
+    workspace: string;
+    /** Port inside the workspace to forward to. */
+    remotePort: number;
+    abortSignal?: AbortSignal;
+}
+interface PortForward {
+    /** Host interface the forward listens on (typically `127.0.0.1`). */
+    readonly localHost: string;
+    /** Host port that tunnels to the workspace's `remotePort`. */
+    readonly localPort: number;
+    /**
+     * `true` once the underlying tunnel process has exited or errored. Consumers
+     * read this to detect a dead tunnel and re-establish the forward.
+     */
+    readonly closed: boolean;
+    /** Tear down the forward. Idempotent. */
+    close(): Promise<void>;
+}
+interface LifecycleOptions {
+    abortSignal?: AbortSignal;
+}
+
+interface CoderCliTransportOptions {
+    /** Path or name of the coder binary. Default: `coder`. */
+    coderBinary?: string;
+    /**
+     * Path or name of the OpenSSH client used for exec/spawn. Default: `ssh`.
+     * Exec goes through real OpenSSH (via a `coder ssh --stdio` ProxyCommand)
+     * rather than `coder ssh <ws> -- cmd`, because the latter allocates a PTY —
+     * which mangles output (CRLF), merges stdout/stderr, and breaks exit-code
+     * propagation. `coder ssh`'s own help recommends `coder config-ssh` for full
+     * SSH parity; this is the programmatic equivalent.
+     */
+    sshBinary?: string;
+    /** Coder deployment URL; sets `CODER_URL`. Falls back to ambient `coder login`. */
+    url?: string;
+    /** Coder session token; sets `CODER_SESSION_TOKEN`. Falls back to ambient login. */
+    token?: string;
+    /** Extra environment merged into every coder/ssh invocation. */
+    env?: Record<string, string>;
+    /**
+     * Run remote commands through a bash *login* shell (`bash -lc`) so PATH and
+     * profile-managed toolchains (nvm, asdf, mise, …) resolve. Default: `true`.
+     */
+    loginShell?: boolean;
+    /**
+     * Coder startup-script wait behavior for the proxied connection
+     * (`coder ssh --wait`). Default `'no'`: programmatic exec should not block on
+     * (or stream the logs of) startup scripts. Set `'auto'`/`'yes'` if your
+     * workspace provisions required tooling in a blocking startup script.
+     */
+    waitMode?: "yes" | "no" | "auto";
+    /**
+     * Redirect the ProxyCommand's own stderr to /dev/null so coder CLI chatter
+     * (version-mismatch warnings, startup logs) does not bleed into a command's
+     * stderr. Default: `true`. Disable to surface coder connection errors.
+     */
+    silenceProxyStderr?: boolean;
+    /** Timeout (ms) to wait for a port-forward's local endpoint. Default 30000. */
+    portForwardTimeoutMs?: number;
+}
+/**
+ * Default {@link CoderTransport}. Exec/spawn use OpenSSH via a
+ * `coder ssh --stdio` ProxyCommand; port-forward and lifecycle use the `coder`
+ * CLI directly.
+ */
+declare class CoderCliTransport implements CoderTransport {
+    #private;
+    constructor(options?: CoderCliTransportOptions);
+    exec(options: TransportExecOptions): Promise<ExecResult>;
+    spawn(options: TransportExecOptions): SpawnedProcess;
+    forwardPort(options: ForwardPortOptions): Promise<PortForward>;
+    start(workspace: string, options?: LifecycleOptions): Promise<void>;
+    stop(workspace: string, options?: LifecycleOptions): Promise<void>;
+    destroy(workspace: string, options?: LifecycleOptions): Promise<void>;
+    status(workspace: string, options?: LifecycleOptions): Promise<WorkspaceStatus | null>;
+    create(options: CreateWorkspaceOptions): Promise<void>;
+    listPresets(options: ListPresetsOptions): Promise<PresetInfo[]>;
+}
+
+/** Stable provider id reported on the {@link HarnessV1SandboxProvider}. */
+declare const CODER_WORKSPACE_PROVIDER_ID = "coder-workspace";
+/**
+ * Settings for creating a workspace on demand from a template. Set this as the
+ * `create` field on {@link CoderWorkspaceSettings} to enable "create mode": the
+ * provider will get-or-create a workspace (rather than only wrapping an existing
+ * one) and wait for its agent to become ready before running the harness.
+ */
+interface CoderCreateSettings {
+    /** Template name to create from. Required to enable creation. */
+    template: string;
+    /** Specific template version name; defaults to the template's active version. */
+    templateVersion?: string;
+    /**
+     * Named preset to apply (`coder create --preset`). Use `'none'` to force no
+     * preset. Note: a preset's parameter values take precedence over any
+     * overlapping {@link CoderCreateSettings.parameters} (Coder's behavior) — set
+     * a given value via the preset *or* `parameters`, not both.
+     */
+    preset?: string;
+    /**
+     * Rich parameter values by parameter name. Numbers and booleans are
+     * stringified. For `list(string)` parameters prefer {@link parameterFile}.
+     */
+    parameters?: Record<string, string | number | boolean>;
+    /** Path to a YAML rich-parameter file (`--rich-parameter-file`). */
+    parameterFile?: string;
+    /** Accept template defaults for any parameter not otherwise provided. */
+    useParameterDefaults?: boolean;
+    /** Ephemeral (one-time build) parameter values by name. */
+    ephemeralParameters?: Record<string, string | number | boolean>;
+    /** Auto-stop the workspace after this duration, e.g. `'8h'` (`--stop-after`). */
+    stopAfter?: string;
+    /** `--automatic-updates` setting (default: Coder's, `never`). */
+    automaticUpdates?: "always" | "never";
+    /** Organization name or uuid for ambiguous template names (`--org`). */
+    org?: string;
+    /**
+     * Owner for an auto-derived workspace name (`owner/name`). Only applied when
+     * the name is derived from the sessionId; when you pass an explicit
+     * `workspace` string, include the owner there. Defaults to the authenticated
+     * user.
+     */
+    owner?: string;
+    /**
+     * What to do if a workspace with the target name already exists:
+     * `'attach'` (default) reuses it; `'error'` fails.
+     */
+    ifExists?: "attach" | "error";
+    /**
+     * Prefix for the workspace name derived from the harness sessionId when no
+     * explicit `workspace` is set (fresh-per-session). Default: `'agent'`.
+     */
+    namePrefix?: string;
+    /**
+     * Preflight-validate the requested {@link preset} name against the template's
+     * presets before creating, failing fast with the available names. Best-effort
+     * (skipped silently if introspection fails). Default: `true`.
+     */
+    validate?: boolean;
+}
+/**
+ * A workspace reference: a fixed `[owner/]workspace[.agent]`, or a resolver from
+ * the harness `sessionId`.
+ */
+type CoderWorkspaceRef = string | ((sessionId: string | undefined) => string);
+/** Settings common to every {@link createCoderWorkspace} configuration. */
+interface CoderWorkspaceBaseSettings {
+    /** Max time (ms) to wait for the agent to become ready after create/start. Default 300000. */
+    readyTimeoutMs?: number;
+    /**
+     * Ports the workspace exposes. The bridge-backed adapters resolve the bridge
+     * port from `createClaudeCode({ port })` or, failing that, `ports[0]`, so the
+     * default exposes a single port (4000) that the bridge will bind and that
+     * `getPortUrl` will forward. Default: `[4000]`.
+     */
+    ports?: number[];
+    /**
+     * Absolute default working directory. If omitted, it is resolved from `$HOME`
+     * in the workspace at session-create time, falling back to `/home/coder`.
+     */
+    defaultWorkingDirectory?: string;
+    /**
+     * Whether this provider owns the workspace lifecycle (`stop()`/`destroy()`
+     * actually stop/delete it). Default depends on mode:
+     * - **wrap mode** (no `create`): `false` — `stop()`/`destroy()` only release
+     *   host-side resources and never touch the workspace.
+     * - **create mode**: `true` — but a workspace the provider only *attached* to
+     *   (an explicitly-named, pre-existing one) is never deleted; only workspaces
+     *   the provider actually created are. A per-session derived name is always
+     *   treated as owned.
+     */
+    ownsLifecycle?: boolean;
+    /** Run `coder start` before attaching (useful for stopped workspaces in wrap mode). */
+    ensureStarted?: boolean;
+    /**
+     * Transport used to reach Coder. Defaults to a {@link CoderCliTransport} that
+     * shells out to an ambient `coder` login. To configure the CLI transport —
+     * binary paths, `url`/`token`, extra env, login shell, startup-wait behavior —
+     * construct one explicitly, e.g. `transport: new CoderCliTransport({ url, token })`.
+     * You can also supply a non-CLI transport (REST, tests, …).
+     */
+    transport?: CoderTransport;
+}
+/**
+ * Settings for {@link createCoderWorkspace}. **At least one of `workspace` or
+ * `create` is required** — and you may set both:
+ * - `workspace` only — wrap an existing workspace.
+ * - `create` only — create a fresh per-session workspace from a template (its
+ *   name is derived from the harness `sessionId`), deleted on `destroy()`.
+ * - both — get-or-create the named `workspace` from the template.
+ */
+type CoderWorkspaceSettings = CoderWorkspaceBaseSettings & ({
+    /**
+     * The workspace to use, as `[owner/]workspace[.agent]` — a fixed name or
+     * a resolver from the harness `sessionId`. With `create` it is
+     * get-or-created; otherwise it must already exist.
+     */
+    workspace: CoderWorkspaceRef;
+    /** Optionally create the workspace from a template if it doesn't exist. */
+    create?: CoderCreateSettings;
+} | {
+    /**
+     * Optional explicit workspace name/resolver. Omit to derive a fresh
+     * per-session name from the harness `sessionId`.
+     */
+    workspace?: CoderWorkspaceRef;
+    /** Create the workspace on demand from a template. See {@link CoderCreateSettings}. */
+    create: CoderCreateSettings;
+});
+/**
+ * Create a {@link HarnessV1SandboxProvider} that runs harness sessions inside a
+ * Coder workspace. Either wraps an existing workspace, or — when a `create`
+ * block is supplied — creates one on demand from a template.
+ *
+ * @example Wrap an existing workspace
+ * ```ts
+ * createCoderWorkspace({ workspace: 'my-dev-workspace' })
+ * ```
+ *
+ * @example Create a fresh per-session workspace from a template
+ * ```ts
+ * createCoderWorkspace({
+ *   create: { template: 'docker', preset: 'Large' },
+ * })
+ * ```
+ */
+declare function createCoderWorkspace(settings: CoderWorkspaceSettings): HarnessV1SandboxProvider;
+
+interface ReadFileOptions {
+    path: string;
+    abortSignal?: AbortSignal;
+}
+interface ReadTextFileOptions extends ReadFileOptions {
+    encoding?: string;
+    startLine?: number;
+    endLine?: number;
+}
+interface WriteFileOptions<CONTENT> {
+    path: string;
+    content: CONTENT;
+    abortSignal?: AbortSignal;
+}
+interface WriteTextFileOptions extends WriteFileOptions<string> {
+    encoding?: string;
+}
+
+type SandboxProcessOptions = Parameters<Experimental_SandboxSession["run"]>[0];
+interface CoderWorkspaceSessionConfig {
+    transport: CoderTransport;
+    /** Workspace reference: `[owner/]workspace[.agent]`. */
+    workspace: string;
+    /** Stable id used by the harness for cross-process resume (the workspace name). */
+    id: string;
+    /** Absolute default working directory for `run`/`spawn` and relative file paths. */
+    defaultWorkingDirectory: string;
+    /** Ports the workspace exposes; `ports[0]` is what the adapter binds the bridge to. */
+    ports: number[];
+    /**
+     * When true, `stop()`/`destroy()` actually stop/delete the workspace. When
+     * false (wrapping a caller-owned workspace) they only release host-side
+     * resources (port-forwards) and leave the workspace running.
+     */
+    ownsLifecycle: boolean;
+}
+/**
+ * A {@link HarnessV1NetworkSandboxSession} backed by a Coder workspace.
+ *
+ * Exec maps to `coder ssh`, file I/O to base64-over-`coder ssh`, and
+ * `getPortUrl` to an OpenSSH `-L` local forward over a `coder ssh --stdio`
+ * ProxyCommand, exposed as a local `ws://127.0.0.1:<port>` URL — which is what
+ * bridge-backed harness adapters (Claude Code, Codex) open their WebSocket
+ * against.
+ */
+declare class CoderWorkspaceSession implements HarnessV1NetworkSandboxSession {
+    #private;
+    readonly id: string;
+    readonly defaultWorkingDirectory: string;
+    readonly description: string;
+    constructor(config: CoderWorkspaceSessionConfig);
+    get ports(): ReadonlyArray<number>;
+    readonly run: (options: SandboxProcessOptions) => Promise<ExecResult>;
+    readonly spawn: (options: SandboxProcessOptions) => Promise<SpawnedProcess>;
+    readonly readFile: (options: ReadFileOptions) => Promise<ReadableStream<Uint8Array<ArrayBufferLike>> | null>;
+    readonly readBinaryFile: (options: ReadFileOptions) => Promise<Uint8Array<ArrayBufferLike> | null>;
+    readonly readTextFile: (options: ReadTextFileOptions) => Promise<string | null>;
+    readonly writeFile: (options: WriteFileOptions<ReadableStream<Uint8Array>>) => Promise<void>;
+    readonly writeBinaryFile: (options: WriteFileOptions<Uint8Array>) => Promise<void>;
+    readonly writeTextFile: (options: WriteTextFileOptions) => Promise<void>;
+    readonly getPortUrl: (options: {
+        port: number;
+        protocol?: "http" | "https" | "ws";
+    }) => Promise<string>;
+    readonly setPorts: (ports: ReadonlyArray<number>, _options?: {
+        abortSignal?: AbortSignal;
+    }) => Promise<void>;
+    readonly stop: () => Promise<void>;
+    readonly destroy: () => Promise<void>;
+    /** Reduced view exposing only the base file/exec surface (no infra controls). */
+    readonly restricted: () => Experimental_SandboxSession;
+}
+
+export { CODER_WORKSPACE_PROVIDER_ID, CoderCliTransport, type CoderCliTransportOptions, type CoderCreateSettings, type CoderTransport, type CoderWorkspaceBaseSettings, type CoderWorkspaceRef, CoderWorkspaceSession, type CoderWorkspaceSessionConfig, type CoderWorkspaceSettings, type CreateWorkspaceOptions, type ExecResult, type ForwardPortOptions, type LifecycleOptions, type ListPresetsOptions, type PortForward, type PresetInfo, type SpawnedProcess, type TransportExecOptions, type WorkspaceAgentInfo, type WorkspaceAgentLifecycle, type WorkspaceAgentStatus, type WorkspaceBuildStatus, type WorkspaceStatus, createCoderWorkspace };