Skip to content

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

7.8 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 type { ExecdClient, ExecdPaths } from "@alibaba-group/opensandbox/internal";
import type { ServerStreamEvent } from "@alibaba-group/opensandbox";
import type { Execution, ExecutionHandlers } from "@alibaba-group/opensandbox";
import {
  ExecutionEventDispatcher,
  InvalidArgumentException,
} from "@alibaba-group/opensandbox";

import type { Codes } from "../services/codes.js";
import type { CodeContext, SupportedLanguage } from "../models.js";
import { throwOnOpenApiFetchError } from "./openapiError.js";
import { parseJsonEventStream } from "./sse.js";

type ApiCreateContextRequest =
  ExecdPaths["/code/context"]["post"]["requestBody"]["content"]["application/json"];
type ApiCreateContextOk =
  ExecdPaths["/code/context"]["post"]["responses"][200]["content"]["application/json"];
type ApiGetContextOk =
  ExecdPaths["/code/contexts/{context_id}"]["get"]["responses"][200]["content"]["application/json"];
type ApiListContextsOk =
  ExecdPaths["/code/contexts"]["get"]["responses"][200]["content"]["application/json"];
type ApiRunCodeRequest =
  ExecdPaths["/code"]["post"]["requestBody"]["content"]["application/json"];

/**
 * Single-layer codes adapter for the Code Interpreter SDK.
 *
 * - Handles HTTP/SSE streaming via the underlying execd adapter
 * - Builds the structured {@link Execution} result for `run(...)`
 */
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}`;
}

export class CodesAdapter implements Codes {
  private readonly fetch: typeof fetch;

  constructor(
    private readonly client: ExecdClient,
    private readonly opts: { baseUrl: string; fetch?: typeof fetch; headers?: Record<string, string> },
  ) {
    this.fetch = opts.fetch ?? fetch;
  }

  async createContext(language: SupportedLanguage): Promise<CodeContext> {
    const body: ApiCreateContextRequest = { language };
    const { data, error, response } = await this.client.POST("/code/context", {
      body,
    });
    throwOnOpenApiFetchError({ error, response }, "Create code context failed");
    const ok = data as ApiCreateContextOk | undefined;
    if (!ok || typeof ok !== "object") {
      throw new Error("Create code context failed: unexpected response shape");
    }
    if (typeof ok.language !== "string" || !ok.language) {
      throw new Error("Create code context failed: missing language");
    }
    return { id: ok.id, language: ok.language };
  }

  async getContext(contextId: string): Promise<CodeContext> {
    if (!contextId?.trim()) {
      throw new InvalidArgumentException({ message: "contextId cannot be empty" });
    }
    const { data, error, response } = await this.client.GET("/code/contexts/{context_id}", {
      params: { path: { context_id: contextId } },
    });
    throwOnOpenApiFetchError({ error, response }, "Get code context failed");
    const ok = data as ApiGetContextOk | undefined;
    if (!ok || typeof ok !== "object") {
      throw new Error("Get code context failed: unexpected response shape");
    }
    if (typeof (ok as any).language !== "string" || !(ok as any).language) {
      throw new Error("Get code context failed: missing language");
    }
    return { id: (ok as any).id, language: (ok as any).language };
  }

  async listContexts(language?: SupportedLanguage): Promise<CodeContext[]> {
    const { data, error, response } = await this.client.GET("/code/contexts", {
      params: language ? { query: { language } } : undefined,
    } as any);
    throwOnOpenApiFetchError({ error, response }, "List code contexts failed");
    const ok = data as ApiListContextsOk | undefined;
    if (!Array.isArray(ok)) {
      throw new Error("List code contexts failed: unexpected response shape");
    }
    return ok
      .filter((c) => c && typeof c === "object")
      .map((c: any) => ({ id: c.id, language: c.language as any }));
  }

  async deleteContext(contextId: string): Promise<void> {
    if (!contextId?.trim()) {
      throw new InvalidArgumentException({ message: "contextId cannot be empty" });
    }
    const { error, response } = await this.client.DELETE("/code/contexts/{context_id}", {
      params: { path: { context_id: contextId } },
    });
    throwOnOpenApiFetchError({ error, response }, "Delete code context failed");
  }

  async deleteContexts(language: SupportedLanguage): Promise<void> {
    const { error, response } = await this.client.DELETE("/code/contexts", {
      params: { query: { language } },
    });
    throwOnOpenApiFetchError({ error, response }, "Delete code contexts failed");
  }

  async interrupt(executionId: string): Promise<void> {
    // The query id targets an *execution* session id (mirrors the Python
    // SDK's interrupt(execution_id)); passing a context id yields a 500
    // "no such session" error from execd.
    if (!executionId?.trim()) {
      throw new InvalidArgumentException({ message: "executionId cannot be empty" });
    }
    const { error, response } = await this.client.DELETE("/code", {
      params: { query: { id: executionId } },
    });
    throwOnOpenApiFetchError({ error, response }, "Interrupt code failed");
  }

  async ping(signal?: AbortSignal): Promise<boolean> {
    const { error, response } = await this.client.GET("/ping", {
      parseAs: "text",
      signal,
    });
    throwOnOpenApiFetchError({ error, response }, "Execd ping failed");
    return true;
  }

  async *runStream(req: ApiRunCodeRequest, signal?: AbortSignal): AsyncIterable<ServerStreamEvent> {
    const url = joinUrl(this.opts.baseUrl, "/code");
    const body = JSON.stringify(req);
    const res = await this.fetch(url, {
      method: "POST",
      headers: {
        "accept": "text/event-stream",
        "content-type": "application/json",
        ...(this.opts.headers ?? {}),
      },
      body,
      signal,
    });

    for await (const ev of parseJsonEventStream<ServerStreamEvent>(res, { fallbackErrorMessage: "Run code failed" })) {
      yield ev;
    }
  }

  async run(
    code: string,
    opts: { context?: CodeContext; language?: SupportedLanguage; handlers?: ExecutionHandlers; signal?: AbortSignal } = {},
  ): Promise<Execution> {
    if (!code.trim()) {
      throw new InvalidArgumentException({ message: "Code cannot be empty" });
    }

    // Only a *mismatch* is an error (aligned with the Python SDK); a matching
    // pair is accepted and the context wins.
    if (opts.context && opts.language && opts.context.language !== opts.language) {
      throw new InvalidArgumentException({
        message: `language '${opts.language}' must match context.language '${opts.context.language}'`,
      });
    }

    const context: CodeContext =
      opts.context ??
      (opts.language
        ? { language: opts.language }
        : { language: "python" });

    // Make the OpenAPI contract explicit so backend schema changes surface quickly.
    const req: ApiRunCodeRequest = {
      code,
      context: { id: context.id, language: context.language },
    };

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

    for await (const ev of this.runStream(req, opts.signal)) {
      await dispatcher.dispatch(ev as any);
    }

    return execution;
  }
}