Skip to content

Secure, Fast, and Extensible Sandbox runtime for AI agents.

12.7 KB
Raw Blame
// Copyright 2026 The OpenSandbox Authors
//
// Licensed under the Apache License, Version 2.0 (the "License");
// you may not use this file except in compliance with the License.
// You may obtain a copy of the License at
//
//     http://www.apache.org/licenses/LICENSE-2.0
//
// Unless required by applicable law or agreed to in writing, software
// distributed under the License is distributed on an "AS IS" BASIS,
// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
// See the License for the specific language governing permissions and
// limitations under the License.

import { createExecdClient } from "../openapi/execdClient.js";
import { IsolatedFilesystemAdapter } from "./isolatedFilesystemAdapter.js";
import { parseJsonEventStream } from "./sse.js";
import type { components as ExecdComponents } from "../api/execd.js";
import type { CommandExecution, ServerStreamEvent } from "../models/execd.js";
import type { ExecutionHandlers } from "../models/execution.js";
import { inferExecutionExitCode } from "../models/execution.js";
import { ExecutionEventDispatcher } from "../models/executionEventDispatcher.js";
import type { SandboxFiles } from "../services/filesystem.js";
import type {
  IsolationService,
  IsolationSession,
  RunOnceOpts,
} from "../services/isolatedSessions.js";
import type {
  CreateIsolatedSessionRequest,
  IsolatedBackgroundRun,
  IsolatedCapabilities,
  IsolatedRunLogs,
  IsolatedRunOpts,
  IsolatedRunStatus,
  IsolatedSessionInfo,
  IsolatedSessionState,
  IsolatedSessionSummary,
  ListIsolatedSessionsResponse,
} from "../models/isolated.js";

type SessionStateWire = ExecdComponents["schemas"]["SessionState"];

const TAIL_CURSOR_HEADER = "EXECD-ISOLATED-TAIL-CURSOR";

function joinUrl(baseUrl: string, pathname: string): string {
  const base = baseUrl.endsWith("/") ? baseUrl.slice(0, -1) : baseUrl;
  const path = pathname.startsWith("/") ? pathname : `/${pathname}`;
  return `${base}${path}`;
}

function assertNonBlank(value: string, field: string): void {
  if (!value.trim()) {
    throw new Error(`${field} cannot be empty`);
  }
}

function utf8ByteLength(text: string): number {
  return new TextEncoder().encode(text).byteLength;
}

export interface IsolatedSessionsAdapterOptions {
  baseUrl: string;
  fetch?: typeof fetch;
  /** Unbounded-timeout fetch for SSE streaming (run endpoint). Falls back to `fetch`. */
  sseFetch?: typeof fetch;
  /**
   * No-overall-timeout fetch for uploads of caller-provided bodies. See
   * `ConnectionConfig.uploadFetch`. Falls back to `fetch`.
   */
  uploadFetch?: typeof fetch;
  headers?: Record<string, string>;
}

class IsolationSessionHandle implements IsolationSession {
  private _files: SandboxFiles | undefined;

  constructor(
    private readonly _info: IsolatedSessionInfo,
    private readonly adapter: IsolatedSessionsAdapter,
  ) {}

  get sessionId(): string { return this._info.session_id; }
  get info(): IsolatedSessionInfo { return this._info; }
  get files(): SandboxFiles {
    if (!this._files) {
      const client = createExecdClient({
        baseUrl: this.adapter.opts.baseUrl,
        headers: this.adapter.opts.headers,
        fetch: this.adapter.opts.fetch,
      });
      this._files = new IsolatedFilesystemAdapter(client, {
        baseUrl: this.adapter.opts.baseUrl,
        sessionId: this._info.session_id,
        fetch: this.adapter.opts.fetch,
        uploadFetch: this.adapter.opts.uploadFetch,
        headers: this.adapter.opts.headers,
      });
    }
    return this._files;
  }

  run(code: string, opts?: IsolatedRunOpts, handlers?: ExecutionHandlers, signal?: AbortSignal): Promise<CommandExecution> {
    return this.adapter._run(this._info.session_id, code, opts, handlers, signal);
  }
  runBackground(code: string, opts?: IsolatedRunOpts): Promise<IsolatedBackgroundRun> {
    return this.adapter._runBackground(this._info.session_id, code, opts);
  }
  getRunStatus(runId: string): Promise<IsolatedRunStatus> {
    return this.adapter._getRunStatus(this._info.session_id, runId);
  }
  getRunLogs(runId: string, cursor?: number): Promise<IsolatedRunLogs> {
    return this.adapter._getRunLogs(this._info.session_id, runId, cursor);
  }
  get(): Promise<IsolatedSessionState> {
    return this.adapter._get(this._info.session_id);
  }
  delete(): Promise<void> {
    return this.adapter._delete(this._info.session_id);
  }
}

export class IsolatedSessionsAdapter implements IsolationService {
  private readonly fetch: typeof fetch;
  private readonly sseFetch: typeof fetch;

  constructor(readonly opts: IsolatedSessionsAdapterOptions) {
    this.fetch = opts.fetch ?? fetch;
    this.sseFetch = opts.sseFetch ?? this.fetch;
  }

  private async jsonRequest<T>(
    method: string,
    pathname: string,
    body?: unknown,
  ): Promise<T> {
    const url = joinUrl(this.opts.baseUrl, pathname);
    const headers: Record<string, string> = {
      "content-type": "application/json",
      accept: "application/json",
      ...(this.opts.headers ?? {}),
    };
    const res = await this.fetch(url, {
      method,
      headers,
      body: body != null ? JSON.stringify(body) : undefined,
    });
    if (!res.ok) {
      const text = await res.text().catch(() => "");
      throw new Error(`${method} ${pathname} failed: ${res.status} ${text}`);
    }
    if (res.status === 204) return undefined as T;
    const text = await res.text();
    if (!text) return undefined as T;
    return JSON.parse(text) as T;
  }

  async create(request: CreateIsolatedSessionRequest): Promise<IsolationSessionHandle> {
    const info = await this.jsonRequest<IsolatedSessionInfo>(
      "POST",
      "/v1/isolated/session",
      request,
    );
    return new IsolationSessionHandle(info, this);
  }

  async attach(sessionId: string): Promise<IsolationSessionHandle> {
    assertNonBlank(sessionId, "sessionId");
    const state = await this.jsonRequest<SessionStateWire>(
      "GET",
      `/v1/isolated/session/${encodeURIComponent(sessionId)}`,
    );
    // Build an IsolatedSessionInfo from the SessionState response.
    // Creation-parameter echo fields are optional; older execd builds omit
    // them. Unknown/absent fields become `undefined` so the handle is still
    // usable via sessionId for run/get/delete/files.
    const info: IsolatedSessionInfo = {
      session_id: sessionId,
      created_at: state.created_at ?? "",
    };
    if (state.profile !== undefined) info.profile = state.profile;
    if (state.workspace !== undefined) info.workspace = state.workspace;
    if (state.overlays !== undefined) info.overlays = state.overlays;
    if (state.extra_writable !== undefined) info.extra_writable = state.extra_writable;
    if (state.binds !== undefined) info.binds = state.binds;
    if (state.share_net !== undefined) info.share_net = state.share_net;
    if (state.env_passthrough !== undefined) info.env_passthrough = state.env_passthrough;
    if (state.uid !== undefined) info.uid = state.uid;
    if (state.gid !== undefined) info.gid = state.gid;
    if (state.uid_mode !== undefined) info.uid_mode = state.uid_mode;
    if (state.idle_timeout_seconds !== undefined) {
      info.idle_timeout_seconds = state.idle_timeout_seconds;
    }
    return new IsolationSessionHandle(info, this);
  }

  async _get(sessionId: string): Promise<IsolatedSessionState> {
    assertNonBlank(sessionId, "sessionId");
    return this.jsonRequest<IsolatedSessionState>(
      "GET",
      `/v1/isolated/session/${encodeURIComponent(sessionId)}`,
    );
  }

  async _run(
    sessionId: string,
    code: string,
    opts?: IsolatedRunOpts,
    handlers?: ExecutionHandlers,
    signal?: AbortSignal,
  ): Promise<CommandExecution> {
    assertNonBlank(sessionId, "sessionId");
    assertNonBlank(code, "code");

    const body: Record<string, unknown> = { code };
    if (opts?.envs) body.envs = opts.envs;
    if (opts?.timeout_seconds != null) body.timeout_seconds = opts.timeout_seconds;

    const url = joinUrl(
      this.opts.baseUrl,
      `/v1/isolated/session/${encodeURIComponent(sessionId)}/run`,
    );
    const res = await this.sseFetch(url, {
      method: "POST",
      headers: {
        accept: "text/event-stream",
        "content-type": "application/json",
        ...(this.opts.headers ?? {}),
      },
      body: JSON.stringify(body),
      signal,
    });

    const execution: CommandExecution = {
      logs: { stdout: [], stderr: [] },
      result: [],
    };
    const dispatcher = new ExecutionEventDispatcher(execution, handlers);

    for await (const ev of parseJsonEventStream<ServerStreamEvent>(res, {
      fallbackErrorMessage: "Run in isolated session failed",
    })) {
      await dispatcher.dispatch(ev as any);
    }

    execution.exitCode = inferExecutionExitCode(execution);
    return execution;
  }

  async _delete(sessionId: string): Promise<void> {
    assertNonBlank(sessionId, "sessionId");
    await this.jsonRequest<void>(
      "DELETE",
      `/v1/isolated/session/${encodeURIComponent(sessionId)}`,
    );
  }

  async _runBackground(
    sessionId: string,
    code: string,
    opts?: IsolatedRunOpts,
  ): Promise<IsolatedBackgroundRun> {
    assertNonBlank(sessionId, "sessionId");
    assertNonBlank(code, "code");

    const body: Record<string, unknown> = { code, background: true };
    if (opts?.envs) body.envs = opts.envs;
    // timeout_seconds is foreground-only and deliberately not sent.

    const pathname = `/v1/isolated/session/${encodeURIComponent(sessionId)}/run`;
    const res = await this.fetch(joinUrl(this.opts.baseUrl, pathname), {
      method: "POST",
      headers: {
        accept: "application/json",
        "content-type": "application/json",
        ...(this.opts.headers ?? {}),
      },
      body: JSON.stringify(body),
    });
    if (res.status !== 202) {
      const text = await res.text().catch(() => "");
      throw new Error(`POST ${pathname} failed: ${res.status} ${text}`);
    }
    const raw = await res.text();
    return JSON.parse(raw) as IsolatedBackgroundRun;
  }

  async _getRunStatus(
    sessionId: string,
    runId: string,
  ): Promise<IsolatedRunStatus> {
    assertNonBlank(sessionId, "sessionId");
    assertNonBlank(runId, "runId");
    return this.jsonRequest<IsolatedRunStatus>(
      "GET",
      `/v1/isolated/session/${encodeURIComponent(sessionId)}/runs/${encodeURIComponent(runId)}`,
    );
  }

  async _getRunLogs(
    sessionId: string,
    runId: string,
    cursor = 0,
  ): Promise<IsolatedRunLogs> {
    assertNonBlank(sessionId, "sessionId");
    assertNonBlank(runId, "runId");
    if (cursor < 0) {
      throw new Error("cursor cannot be negative");
    }

    const pathname = `/v1/isolated/session/${encodeURIComponent(sessionId)}/runs/${encodeURIComponent(runId)}/logs`;
    const url = new URL(joinUrl(this.opts.baseUrl, pathname));
    if (cursor > 0) {
      url.searchParams.set("cursor", String(cursor));
    }
    const res = await this.fetch(url.toString(), {
      method: "GET",
      headers: {
        accept: "text/plain",
        ...(this.opts.headers ?? {}),
      },
    });
    if (!res.ok) {
      const text = await res.text().catch(() => "");
      throw new Error(`GET ${pathname} failed: ${res.status} ${text}`);
    }

    const text = await res.text();
    const headerValue = res.headers.get(TAIL_CURSOR_HEADER);
    const parsedHeader = headerValue != null ? Number(headerValue) : NaN;
    const nextCursor =
      Number.isInteger(parsedHeader) && parsedHeader >= 0
        ? parsedHeader
        : cursor + utf8ByteLength(text);
    return { text, cursor: nextCursor };
  }

  async capabilities(): Promise<IsolatedCapabilities> {
    const response = await this.jsonRequest<IsolatedCapabilities>(
      "GET",
      "/v1/isolated/capabilities",
    );
    return {
      ...response,
      setpriv_available: response.setpriv_available ?? false,
      userns_available: response.userns_available ?? false,
    };
  }

  async list(): Promise<IsolatedSessionSummary[]> {
    const resp = await this.jsonRequest<ListIsolatedSessionsResponse>(
      "GET",
      "/v1/isolated/sessions",
    );
    return resp.sessions ?? [];
  }

  async runOnce(
    code: string,
    workspace: string,
    opts?: RunOnceOpts,
  ): Promise<CommandExecution> {
    const session = await this.create({
      workspace: { path: workspace, mode: opts?.workspaceMode },
      profile: opts?.profile,
      share_net: opts?.shareNet,
      binds: opts?.binds,
    });
    try {
      return await session.run(code, opts?.runOpts, opts?.handlers, opts?.signal);
    } finally {
      try { await session.delete(); } catch { /* best-effort cleanup */ }
    }
  }

  async withSession<T>(
    request: CreateIsolatedSessionRequest,
    fn: (session: IsolationSession) => Promise<T>,
  ): Promise<T> {
    const session = await this.create(request);
    try {
      return await fn(session);
    } finally {
      try { await session.delete(); } catch { /* best-effort cleanup */ }
    }
  }
}