@alibaba-group/opensandbox-code-interpreter 0.1.0-dev1

package/README.md

@@ -0,0 +1,187 @@
+# Alibaba Code Interpreter SDK for JavaScript/TypeScript
+
+English | [中文](README_zh.md)
+
+A TypeScript/JavaScript SDK for executing code in secure, isolated sandboxes. It provides a high-level API for running Python, Java, Go, TypeScript, and other languages safely, with support for code execution contexts.
+
+## Prerequisites
+
+This SDK requires a Docker image containing the Code Interpreter runtime environment. You must use the `opensandbox/code-interpreter` image (or a derivative) which includes pre-installed runtimes for Python, Java, Go, Node.js, etc.
+
+For detailed information about supported languages and versions, please refer to the [Environment Documentation](../../../sandboxes/code-interpreter/README.md).
+
+## Installation
+
+### npm
+
+```bash
+npm install @alibaba-group/opensandbox-code-interpreter
+```
+
+### pnpm
+
+```bash
+pnpm add @alibaba-group/opensandbox-code-interpreter
+```
+
+### yarn
+
+```bash
+yarn add @alibaba-group/opensandbox-code-interpreter
+```
+
+## Quick Start
+
+The following example demonstrates how to create a sandbox with a specific runtime configuration and execute a simple script.
+
+> **Note**: Before running this example, ensure the OpenSandbox service is running. See the root [README.md](../../../README.md) for startup instructions.
+
+```ts
+import { ConnectionConfig, Sandbox } from "@alibaba-group/opensandbox";
+import { CodeInterpreter, SupportedLanguages } from "@alibaba-group/opensandbox-code-interpreter";
+
+// 1. Configure connection
+const config = new ConnectionConfig({
+  domain: "api.opensandbox.io",
+  apiKey: "your-api-key",
+});
+
+// 2. Create a Sandbox with the code-interpreter image + runtime versions
+const sandbox = await Sandbox.create({
+  connectionConfig: config,
+  image: "opensandbox/code-interpreter:latest",
+  entrypoint: ["/opt/opensandbox/code-interpreter.sh"],
+  env: {
+    PYTHON_VERSION: "3.11",
+    JAVA_VERSION: "17",
+    NODE_VERSION: "20",
+    GO_VERSION: "1.24",
+  },
+  timeoutSeconds: 15 * 60,
+});
+
+// 3. Create CodeInterpreter wrapper
+const ci = await CodeInterpreter.create(sandbox);
+
+// 4. Create an execution context (Python)
+const ctx = await ci.codes.createContext(SupportedLanguages.PYTHON);
+
+// 5. Run code
+const result = await ci.codes.run("import sys\nprint(sys.version)\nresult = 2 + 2\nresult", {
+  context: ctx,
+});
+
+// 6. Print output
+console.log(result.result[0]?.text);
+
+// 7. Cleanup remote instance (optional but recommended)
+await sandbox.kill();
+```
+
+## Runtime Configuration
+
+### Docker Image
+
+The Code Interpreter SDK relies on a specialized environment. Ensure your sandbox provider has the `opensandbox/code-interpreter` image available.
+
+### Language Version Selection
+
+You can specify the desired version of a programming language by setting the corresponding environment variable when creating the `Sandbox`.
+
+| Language | Environment Variable | Example Value | Default (if unset) |
+| --- | --- | --- | --- |
+| Python | `PYTHON_VERSION` | `3.11` | Image default |
+| Java | `JAVA_VERSION` | `17` | Image default |
+| Node.js | `NODE_VERSION` | `20` | Image default |
+| Go | `GO_VERSION` | `1.24` | Image default |
+
+```ts
+const sandbox = await Sandbox.create({
+  connectionConfig: config,
+  image: "opensandbox/code-interpreter:latest",
+  entrypoint: ["/opt/opensandbox/code-interpreter.sh"],
+  env: {
+    JAVA_VERSION: "17",
+    GO_VERSION: "1.24",
+  },
+});
+```
+
+## Usage Examples
+
+### 0. Run with `language` (default language context)
+
+If you don't need to manage explicit context IDs, you can run code by specifying only `language`.
+When `context.id` is omitted, execd can create/reuse a default session for that language, so state can persist across runs.
+
+```ts
+import { SupportedLanguages } from "@alibaba-group/opensandbox-code-interpreter";
+
+await ci.codes.run("x = 42", { language: SupportedLanguages.PYTHON });
+const execution = await ci.codes.run("result = x\nresult", { language: SupportedLanguages.PYTHON });
+console.log(execution.result[0]?.text); // "42"
+```
+
+### 0.1 Context management (list/get/delete)
+
+You can manage contexts explicitly (aligned with Python/Kotlin SDKs):
+
+```ts
+const ctx = await ci.codes.createContext(SupportedLanguages.PYTHON);
+
+const same = await ci.codes.getContext(ctx.id!);
+console.log(same.id, same.language);
+
+const all = await ci.codes.listContexts();
+const pyOnly = await ci.codes.listContexts(SupportedLanguages.PYTHON);
+
+await ci.codes.deleteContext(ctx.id!);
+await ci.codes.deleteContexts(SupportedLanguages.PYTHON); // bulk cleanup
+```
+
+### 1. Java Code Execution
+
+```ts
+import { SupportedLanguages } from "@alibaba-group/opensandbox-code-interpreter";
+
+const javaCtx = await ci.codes.createContext(SupportedLanguages.JAVA);
+const execution = await ci.codes.run(
+  [
+    'System.out.println("Calculating sum...");',
+    "int a = 10;",
+    "int b = 20;",
+    "int sum = a + b;",
+    'System.out.println("Sum: " + sum);',
+    "sum",
+  ].join("\n"),
+  { context: javaCtx },
+);
+console.log(execution.logs.stdout.map((m) => m.text));
+```
+
+### 2. Streaming Output Handling
+
+Handle stdout/stderr and execution events in real-time.
+
+```ts
+import type { ExecutionHandlers } from "@alibaba-group/opensandbox";
+import { SupportedLanguages } from "@alibaba-group/opensandbox-code-interpreter";
+
+const handlers: ExecutionHandlers = {
+  onStdout: (m) => console.log("STDOUT:", m.text),
+  onStderr: (m) => console.error("STDERR:", m.text),
+  onResult: (r) => console.log("RESULT:", r.text),
+};
+
+const pyCtx = await ci.codes.createContext(SupportedLanguages.PYTHON);
+await ci.codes.run("import time\nfor i in range(5):\n    print(i)\n    time.sleep(0.2)", {
+  context: pyCtx,
+  handlers,
+});
+```
+
+## Notes
+
+- **Lifecycle**: `CodeInterpreter` wraps an existing `Sandbox` instance and reuses its connection configuration.
+- **Default context**: `codes.run(..., { language })` uses a language default context (state can persist across runs).
+

package/dist/adapters/codesAdapter.d.ts

@@ -0,0 +1,31 @@
+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 type { Codes } from "../services/codes.js";
+import type { CodeContext, SupportedLanguage } from "../models.js";
+type ApiRunCodeRequest = ExecdPaths["/code"]["post"]["requestBody"]["content"]["application/json"];
+export declare class CodesAdapter implements Codes {
+    private readonly client;
+    private readonly opts;
+    private readonly fetch;
+    constructor(client: ExecdClient, opts: {
+        baseUrl: string;
+        fetch?: typeof fetch;
+        headers?: Record<string, string>;
+    });
+    createContext(language: SupportedLanguage): Promise<CodeContext>;
+    getContext(contextId: string): Promise<CodeContext>;
+    listContexts(language?: SupportedLanguage): Promise<CodeContext[]>;
+    deleteContext(contextId: string): Promise<void>;
+    deleteContexts(language: SupportedLanguage): Promise<void>;
+    interrupt(contextId: string): Promise<void>;
+    runStream(req: ApiRunCodeRequest, signal?: AbortSignal): AsyncIterable<ServerStreamEvent>;
+    run(code: string, opts?: {
+        context?: CodeContext;
+        language?: SupportedLanguage;
+        handlers?: ExecutionHandlers;
+        signal?: AbortSignal;
+    }): Promise<Execution>;
+}
+export {};
+//# sourceMappingURL=codesAdapter.d.ts.map

package/dist/adapters/codesAdapter.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"codesAdapter.d.ts","sourceRoot":"","sources":["../../src/adapters/codesAdapter.ts"],"names":[],"mappings":"AAcA,OAAO,KAAK,EAAE,WAAW,EAAE,UAAU,EAAE,MAAM,qCAAqC,CAAC;AACnF,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,4BAA4B,CAAC;AACpE,OAAO,KAAK,EAAE,SAAS,EAAE,iBAAiB,EAAE,MAAM,4BAA4B,CAAC;AAM/E,OAAO,KAAK,EAAE,KAAK,EAAE,MAAM,sBAAsB,CAAC;AAClD,OAAO,KAAK,EAAE,WAAW,EAAE,iBAAiB,EAAE,MAAM,cAAc,CAAC;AAYnE,KAAK,iBAAiB,GACpB,UAAU,CAAC,OAAO,CAAC,CAAC,MAAM,CAAC,CAAC,aAAa,CAAC,CAAC,SAAS,CAAC,CAAC,kBAAkB,CAAC,CAAC;AAc5E,qBAAa,YAAa,YAAW,KAAK;IAItC,OAAO,CAAC,QAAQ,CAAC,MAAM;IACvB,OAAO,CAAC,QAAQ,CAAC,IAAI;IAJvB,OAAO,CAAC,QAAQ,CAAC,KAAK,CAAe;gBAGlB,MAAM,EAAE,WAAW,EACnB,IAAI,EAAE;QAAE,OAAO,EAAE,MAAM,CAAC;QAAC,KAAK,CAAC,EAAE,OAAO,KAAK,CAAC;QAAC,OAAO,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAA;KAAE;IAK9F,aAAa,CAAC,QAAQ,EAAE,iBAAiB,GAAG,OAAO,CAAC,WAAW,CAAC;IAgBhE,UAAU,CAAC,SAAS,EAAE,MAAM,GAAG,OAAO,CAAC,WAAW,CAAC;IAkBnD,YAAY,CAAC,QAAQ,CAAC,EAAE,iBAAiB,GAAG,OAAO,CAAC,WAAW,EAAE,CAAC;IAclE,aAAa,CAAC,SAAS,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;IAU/C,cAAc,CAAC,QAAQ,EAAE,iBAAiB,GAAG,OAAO,CAAC,IAAI,CAAC;IAO1D,SAAS,CAAC,SAAS,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;IAO1C,SAAS,CAAC,GAAG,EAAE,iBAAiB,EAAE,MAAM,CAAC,EAAE,WAAW,GAAG,aAAa,CAAC,iBAAiB,CAAC;IAmB1F,GAAG,CACP,IAAI,EAAE,MAAM,EACZ,IAAI,GAAE;QAAE,OAAO,CAAC,EAAE,WAAW,CAAC;QAAC,QAAQ,CAAC,EAAE,iBAAiB,CAAC;QAAC,QAAQ,CAAC,EAAE,iBAAiB,CAAC;QAAC,MAAM,CAAC,EAAE,WAAW,CAAA;KAAO,GACrH,OAAO,CAAC,SAAS,CAAC;CAiCtB"}

package/dist/adapters/codesAdapter.js

@@ -0,0 +1,146 @@
+// Copyright 2026 Alibaba Group Holding Ltd.
+// 
+// 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 { ExecutionEventDispatcher, InvalidArgumentException, } from "@alibaba-group/opensandbox";
+import { throwOnOpenApiFetchError } from "./openapiError.js";
+import { parseJsonEventStream } from "./sse.js";
+/**
+ * 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, pathname) {
+    const base = baseUrl.endsWith("/") ? baseUrl.slice(0, -1) : baseUrl;
+    const path = pathname.startsWith("/") ? pathname : `/${pathname}`;
+    return `${base}${path}`;
+}
+export class CodesAdapter {
+    client;
+    opts;
+    fetch;
+    constructor(client, opts) {
+        this.client = client;
+        this.opts = opts;
+        this.fetch = opts.fetch ?? fetch;
+    }
+    async createContext(language) {
+        const body = { language };
+        const { data, error, response } = await this.client.POST("/code/context", {
+            body,
+        });
+        throwOnOpenApiFetchError({ error, response }, "Create code context failed");
+        const ok = data;
+        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) {
+        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;
+        if (!ok || typeof ok !== "object") {
+            throw new Error("Get code context failed: unexpected response shape");
+        }
+        if (typeof ok.language !== "string" || !ok.language) {
+            throw new Error("Get code context failed: missing language");
+        }
+        return { id: ok.id, language: ok.language };
+    }
+    async listContexts(language) {
+        const { data, error, response } = await this.client.GET("/code/contexts", {
+            params: language ? { query: { language } } : undefined,
+        });
+        throwOnOpenApiFetchError({ error, response }, "List code contexts failed");
+        const ok = data;
+        if (!Array.isArray(ok)) {
+            throw new Error("List code contexts failed: unexpected response shape");
+        }
+        return ok
+            .filter((c) => c && typeof c === "object")
+            .map((c) => ({ id: c.id, language: c.language }));
+    }
+    async deleteContext(contextId) {
+        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) {
+        const { error, response } = await this.client.DELETE("/code/contexts", {
+            params: { query: { language } },
+        });
+        throwOnOpenApiFetchError({ error, response }, "Delete code contexts failed");
+    }
+    async interrupt(contextId) {
+        const { error, response } = await this.client.DELETE("/code", {
+            params: { query: { id: contextId } },
+        });
+        throwOnOpenApiFetchError({ error, response }, "Interrupt code failed");
+    }
+    async *runStream(req, signal) {
+        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(res, { fallbackErrorMessage: "Run code failed" })) {
+            yield ev;
+        }
+    }
+    async run(code, opts = {}) {
+        if (!code.trim()) {
+            throw new InvalidArgumentException({ message: "Code cannot be empty" });
+        }
+        if (opts.context && opts.language) {
+            throw new InvalidArgumentException({ message: "Provide either opts.context or opts.language, not both" });
+        }
+        const context = opts.context ??
+            (opts.language
+                ? { language: opts.language }
+                : { language: "python" });
+        // Make the OpenAPI contract explicit so backend schema changes surface quickly.
+        const req = {
+            code,
+            context: { id: context.id, language: context.language },
+        };
+        const 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);
+        }
+        return execution;
+    }
+}

package/dist/adapters/openapiError.d.ts

@@ -0,0 +1,5 @@
+export declare function throwOnOpenApiFetchError(result: {
+    error?: unknown;
+    response: Response;
+}, fallbackMessage: string): void;
+//# sourceMappingURL=openapiError.d.ts.map

package/dist/adapters/openapiError.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"openapiError.d.ts","sourceRoot":"","sources":["../../src/adapters/openapiError.ts"],"names":[],"mappings":"AAgBA,wBAAgB,wBAAwB,CACtC,MAAM,EAAE;IAAE,KAAK,CAAC,EAAE,OAAO,CAAC;IAAC,QAAQ,EAAE,QAAQ,CAAA;CAAE,EAC/C,eAAe,EAAE,MAAM,GACtB,IAAI,CAwBN"}

package/dist/adapters/openapiError.js

@@ -0,0 +1,35 @@
+// Copyright 2026 Alibaba Group Holding Ltd.
+// 
+// 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 { SandboxApiException, SandboxError } from "@alibaba-group/opensandbox";
+export function throwOnOpenApiFetchError(result, fallbackMessage) {
+    if (!result.error)
+        return;
+    const requestId = result.response.headers.get("x-request-id") ?? undefined;
+    const status = result.response.status ?? 0;
+    const err = result.error;
+    const message = err?.message ??
+        err?.error?.message ??
+        fallbackMessage;
+    const code = err?.code ?? err?.error?.code;
+    const msg = err?.message ?? err?.error?.message ?? message;
+    throw new SandboxApiException({
+        message: msg,
+        statusCode: status,
+        requestId,
+        error: code
+            ? new SandboxError(String(code), String(msg ?? ""))
+            : new SandboxError(SandboxError.UNEXPECTED_RESPONSE, String(msg ?? "")),
+        rawBody: result.error,
+    });
+}

package/dist/adapters/sse.d.ts

@@ -0,0 +1,9 @@
+/**
+ * Parses an SSE-like stream that may be either:
+ * - standard SSE frames (`data: {...}\n\n`)
+ * - newline-delimited JSON (one JSON object per line)
+ */
+export declare function parseJsonEventStream<T>(res: Response, opts?: {
+    fallbackErrorMessage?: string;
+}): AsyncIterable<T>;
+//# sourceMappingURL=sse.d.ts.map

package/dist/adapters/sse.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"sse.d.ts","sourceRoot":"","sources":["../../src/adapters/sse.ts"],"names":[],"mappings":"AAwBA;;;;GAIG;AACH,wBAAuB,oBAAoB,CAAC,CAAC,EAC3C,GAAG,EAAE,QAAQ,EACb,IAAI,CAAC,EAAE;IAAE,oBAAoB,CAAC,EAAE,MAAM,CAAA;CAAE,GACvC,aAAa,CAAC,CAAC,CAAC,CAyDlB"}

package/dist/adapters/sse.js

@@ -0,0 +1,83 @@
+// Copyright 2026 Alibaba Group Holding Ltd.
+// 
+// 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 { SandboxApiException, SandboxError } from "@alibaba-group/opensandbox";
+function tryParseJson(line) {
+    try {
+        return JSON.parse(line);
+    }
+    catch {
+        return undefined;
+    }
+}
+/**
+ * Parses an SSE-like stream that may be either:
+ * - standard SSE frames (`data: {...}\n\n`)
+ * - newline-delimited JSON (one JSON object per line)
+ */
+export async function* parseJsonEventStream(res, opts) {
+    if (!res.ok) {
+        const text = await res.text().catch(() => "");
+        const parsed = tryParseJson(text);
+        const err = parsed && typeof parsed === "object" ? parsed : undefined;
+        const requestId = res.headers.get("x-request-id") ?? undefined;
+        const message = err?.message ?? opts?.fallbackErrorMessage ?? `Stream request failed (status=${res.status})`;
+        const code = err?.code ? String(err.code) : SandboxError.UNEXPECTED_RESPONSE;
+        throw new SandboxApiException({
+            message,
+            statusCode: res.status,
+            requestId,
+            error: new SandboxError(code, err?.message ? String(err.message) : message),
+            rawBody: parsed ?? text,
+        });
+    }
+    if (!res.body)
+        return;
+    const reader = res.body.getReader();
+    const decoder = new TextDecoder("utf-8");
+    let buf = "";
+    while (true) {
+        const { value, done } = await reader.read();
+        if (done)
+            break;
+        buf += decoder.decode(value, { stream: true });
+        let idx;
+        while ((idx = buf.indexOf("\n")) >= 0) {
+            const rawLine = buf.slice(0, idx);
+            buf = buf.slice(idx + 1);
+            const line = rawLine.trim();
+            if (!line)
+                continue;
+            // Support standard SSE "data:" prefix
+            if (line.startsWith(":"))
+                continue;
+            if (line.startsWith("event:") || line.startsWith("id:") || line.startsWith("retry:"))
+                continue;
+            const jsonLine = line.startsWith("data:") ? line.slice("data:".length).trim() : line;
+            if (!jsonLine)
+                continue;
+            const parsed = tryParseJson(jsonLine);
+            if (!parsed)
+                continue;
+            yield parsed;
+        }
+    }
+    // flush last line if exists
+    const last = buf.trim();
+    if (last) {
+        const jsonLine = last.startsWith("data:") ? last.slice("data:".length).trim() : last;
+        const parsed = tryParseJson(jsonLine);
+        if (parsed)
+            yield parsed;
+    }
+}

package/dist/factory/adapterFactory.d.ts

@@ -0,0 +1,13 @@
+import type { Sandbox } from "@alibaba-group/opensandbox";
+import type { Codes } from "../services/codes.js";
+export interface CreateCodesStackOptions {
+    sandbox: Sandbox;
+    execdBaseUrl: string;
+}
+/**
+ * Factory abstraction for Code Interpreter SDK to decouple from concrete adapters/clients.
+ */
+export interface AdapterFactory {
+    createCodes(opts: CreateCodesStackOptions): Codes;
+}
+//# sourceMappingURL=adapterFactory.d.ts.map

package/dist/factory/adapterFactory.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"adapterFactory.d.ts","sourceRoot":"","sources":["../../src/factory/adapterFactory.ts"],"names":[],"mappings":"AAcA,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,4BAA4B,CAAC;AAC1D,OAAO,KAAK,EAAE,KAAK,EAAE,MAAM,sBAAsB,CAAC;AAElD,MAAM,WAAW,uBAAuB;IACtC,OAAO,EAAE,OAAO,CAAC;IACjB,YAAY,EAAE,MAAM,CAAC;CACtB;AAED;;GAEG;AACH,MAAM,WAAW,cAAc;IAC7B,WAAW,CAAC,IAAI,EAAE,uBAAuB,GAAG,KAAK,CAAC;CACnD"}

package/dist/factory/adapterFactory.js

@@ -0,0 +1,14 @@
+// Copyright 2026 Alibaba Group Holding Ltd.
+// 
+// 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.
+export {};

package/dist/factory/defaultAdapterFactory.d.ts

@@ -0,0 +1,7 @@
+import type { AdapterFactory, CreateCodesStackOptions } from "./adapterFactory.js";
+import type { Codes } from "../services/codes.js";
+export declare class DefaultAdapterFactory implements AdapterFactory {
+    createCodes(opts: CreateCodesStackOptions): Codes;
+}
+export declare function createDefaultAdapterFactory(): AdapterFactory;
+//# sourceMappingURL=defaultAdapterFactory.d.ts.map

package/dist/factory/defaultAdapterFactory.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"defaultAdapterFactory.d.ts","sourceRoot":"","sources":["../../src/factory/defaultAdapterFactory.ts"],"names":[],"mappings":"AAgBA,OAAO,KAAK,EAAE,cAAc,EAAE,uBAAuB,EAAE,MAAM,qBAAqB,CAAC;AAEnF,OAAO,KAAK,EAAE,KAAK,EAAE,MAAM,sBAAsB,CAAC;AAElD,qBAAa,qBAAsB,YAAW,cAAc;IAC1D,WAAW,CAAC,IAAI,EAAE,uBAAuB,GAAG,KAAK;CAclD;AAED,wBAAgB,2BAA2B,IAAI,cAAc,CAE5D"}

package/dist/factory/defaultAdapterFactory.js

@@ -0,0 +1,33 @@
+// Copyright 2026 Alibaba Group Holding Ltd.
+// 
+// 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 "@alibaba-group/opensandbox/internal";
+import { CodesAdapter } from "../adapters/codesAdapter.js";
+export class DefaultAdapterFactory {
+    createCodes(opts) {
+        const client = createExecdClient({
+            baseUrl: opts.execdBaseUrl,
+            headers: opts.sandbox.connectionConfig.headers,
+            fetch: opts.sandbox.connectionConfig.fetch,
+        });
+        return new CodesAdapter(client, {
+            baseUrl: opts.execdBaseUrl,
+            headers: opts.sandbox.connectionConfig.headers,
+            // Streaming calls (SSE) use a dedicated fetch, aligned with Kotlin/Python SDKs.
+            fetch: opts.sandbox.connectionConfig.sseFetch,
+        });
+    }
+}
+export function createDefaultAdapterFactory() {
+    return new DefaultAdapterFactory();
+}

package/dist/index.d.ts

@@ -0,0 +1,9 @@
+export { CodeInterpreter } from "./interpreter.js";
+export type { CodeInterpreterCreateOptions } from "./interpreter.js";
+export type { AdapterFactory } from "./factory/adapterFactory.js";
+export { DefaultAdapterFactory, createDefaultAdapterFactory } from "./factory/defaultAdapterFactory.js";
+export type { CodeContext, SupportedLanguage } from "./models.js";
+export { SupportedLanguage as SupportedLanguages } from "./models.js";
+export type { Codes } from "./services/codes.js";
+export type { Execution, ExecutionComplete, ExecutionError, ExecutionHandlers, ExecutionInit, ExecutionResult, OutputMessage, } from "@alibaba-group/opensandbox";
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAcA,OAAO,EAAE,eAAe,EAAE,MAAM,kBAAkB,CAAC;AACnD,YAAY,EAAE,4BAA4B,EAAE,MAAM,kBAAkB,CAAC;AAErE,YAAY,EAAE,cAAc,EAAE,MAAM,6BAA6B,CAAC;AAClE,OAAO,EAAE,qBAAqB,EAAE,2BAA2B,EAAE,MAAM,oCAAoC,CAAC;AAExG,YAAY,EAAE,WAAW,EAAE,iBAAiB,EAAE,MAAM,aAAa,CAAC;AAClE,OAAO,EAAE,iBAAiB,IAAI,kBAAkB,EAAE,MAAM,aAAa,CAAC;AAEtE,YAAY,EAAE,KAAK,EAAE,MAAM,qBAAqB,CAAC;AAEjD,YAAY,EACV,SAAS,EACT,iBAAiB,EACjB,cAAc,EACd,iBAAiB,EACjB,aAAa,EACb,eAAe,EACf,aAAa,GACd,MAAM,4BAA4B,CAAC"}

package/dist/index.js

@@ -0,0 +1,16 @@
+// Copyright 2026 Alibaba Group Holding Ltd.
+// 
+// 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.
+export { CodeInterpreter } from "./interpreter.js";
+export { DefaultAdapterFactory, createDefaultAdapterFactory } from "./factory/defaultAdapterFactory.js";
+export { SupportedLanguage as SupportedLanguages } from "./models.js";

package/dist/interpreter.d.ts

@@ -0,0 +1,26 @@
+import type { Sandbox } from "@alibaba-group/opensandbox";
+import type { AdapterFactory } from "./factory/adapterFactory.js";
+import type { Codes } from "./services/codes.js";
+export interface CodeInterpreterCreateOptions {
+    adapterFactory?: AdapterFactory;
+}
+/**
+ * Code interpreter facade (JS/TS).
+ *
+ * This class wraps an existing {@link Sandbox} and provides a high-level API for code execution.
+ *
+ * - Use {@link codes} to create contexts and run code.
+ * - {@link files}, {@link commands}, and {@link metrics} are exposed for convenience and are
+ *   the same instances as on the underlying {@link Sandbox}.
+ */
+export declare class CodeInterpreter {
+    readonly sandbox: Sandbox;
+    readonly codes: Codes;
+    private constructor();
+    static create(sandbox: Sandbox, opts?: CodeInterpreterCreateOptions): Promise<CodeInterpreter>;
+    get id(): string;
+    get files(): import("@alibaba-group/opensandbox").SandboxFiles;
+    get commands(): import("@alibaba-group/opensandbox").ExecdCommands;
+    get metrics(): import("@alibaba-group/opensandbox").ExecdMetrics;
+}
+//# sourceMappingURL=interpreter.d.ts.map

package/dist/interpreter.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"interpreter.d.ts","sourceRoot":"","sources":["../src/interpreter.ts"],"names":[],"mappings":"AAeA,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,4BAA4B,CAAC;AAG1D,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,6BAA6B,CAAC;AAClE,OAAO,KAAK,EAAE,KAAK,EAAE,MAAM,qBAAqB,CAAC;AAEjD,MAAM,WAAW,4BAA4B;IAC3C,cAAc,CAAC,EAAE,cAAc,CAAC;CACjC;AAED;;;;;;;;GAQG;AACH,qBAAa,eAAe;IAExB,QAAQ,CAAC,OAAO,EAAE,OAAO;IACzB,QAAQ,CAAC,KAAK,EAAE,KAAK;IAFvB,OAAO;WAKM,MAAM,CAAC,OAAO,EAAE,OAAO,EAAE,IAAI,GAAE,4BAAiC,GAAG,OAAO,CAAC,eAAe,CAAC;IAQxG,IAAI,EAAE,WAEL;IAED,IAAI,KAAK,sDAER;IAED,IAAI,QAAQ,uDAEX;IAED,IAAI,OAAO,sDAEV;CACF"}

package/dist/interpreter.js

@@ -0,0 +1,50 @@
+// Copyright 2026 Alibaba Group Holding Ltd.
+// 
+// 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 { DEFAULT_EXECD_PORT } from "@alibaba-group/opensandbox";
+import { createDefaultAdapterFactory } from "./factory/defaultAdapterFactory.js";
+/**
+ * Code interpreter facade (JS/TS).
+ *
+ * This class wraps an existing {@link Sandbox} and provides a high-level API for code execution.
+ *
+ * - Use {@link codes} to create contexts and run code.
+ * - {@link files}, {@link commands}, and {@link metrics} are exposed for convenience and are
+ *   the same instances as on the underlying {@link Sandbox}.
+ */
+export class CodeInterpreter {
+    sandbox;
+    codes;
+    constructor(sandbox, codes) {
+        this.sandbox = sandbox;
+        this.codes = codes;
+    }
+    static async create(sandbox, opts = {}) {
+        const execdBaseUrl = await sandbox.getEndpointUrl(DEFAULT_EXECD_PORT);
+        const adapterFactory = opts.adapterFactory ?? createDefaultAdapterFactory();
+        const codes = adapterFactory.createCodes({ sandbox, execdBaseUrl });
+        return new CodeInterpreter(sandbox, codes);
+    }
+    get id() {
+        return this.sandbox.id;
+    }
+    get files() {
+        return this.sandbox.files;
+    }
+    get commands() {
+        return this.sandbox.commands;
+    }
+    get metrics() {
+        return this.sandbox.metrics;
+    }
+}

package/dist/models.d.ts

@@ -0,0 +1,18 @@
+export declare const SupportedLanguage: {
+    readonly PYTHON: "python";
+    readonly JAVA: "java";
+    readonly GO: "go";
+    readonly TYPESCRIPT: "typescript";
+    readonly JAVASCRIPT: "javascript";
+    readonly BASH: "bash";
+};
+export type SupportedLanguage = (typeof SupportedLanguage)[keyof typeof SupportedLanguage];
+export interface CodeContext {
+    id?: string;
+    language: SupportedLanguage | (string & {});
+}
+export interface RunCodeRequest {
+    code: string;
+    context: CodeContext;
+}
+//# sourceMappingURL=models.d.ts.map

package/dist/models.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"models.d.ts","sourceRoot":"","sources":["../src/models.ts"],"names":[],"mappings":"AAcA,eAAO,MAAM,iBAAiB;;;;;;;CAOpB,CAAC;AAEX,MAAM,MAAM,iBAAiB,GAC3B,CAAC,OAAO,iBAAiB,CAAC,CAAC,MAAM,OAAO,iBAAiB,CAAC,CAAC;AAE7D,MAAM,WAAW,WAAW;IAC1B,EAAE,CAAC,EAAE,MAAM,CAAC;IACZ,QAAQ,EAAE,iBAAiB,GAAG,CAAC,MAAM,GAAG,EAAE,CAAC,CAAC;CAC7C;AAED,MAAM,WAAW,cAAc;IAC7B,IAAI,EAAE,MAAM,CAAC;IACb,OAAO,EAAE,WAAW,CAAC;CACtB"}

package/dist/models.js

@@ -0,0 +1,21 @@
+// Copyright 2026 Alibaba Group Holding Ltd.
+// 
+// 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.
+export const SupportedLanguage = {
+    PYTHON: "python",
+    JAVA: "java",
+    GO: "go",
+    TYPESCRIPT: "typescript",
+    JAVASCRIPT: "javascript",
+    BASH: "bash",
+};

package/dist/services/codes.d.ts

@@ -0,0 +1,31 @@
+import type { ServerStreamEvent } from "@alibaba-group/opensandbox";
+import type { Execution, ExecutionHandlers } from "@alibaba-group/opensandbox";
+import type { CodeContext, RunCodeRequest, SupportedLanguage } from "../models.js";
+export interface Codes {
+    createContext(language: SupportedLanguage): Promise<CodeContext>;
+    /**
+     * Get an existing context by id.
+     */
+    getContext(contextId: string): Promise<CodeContext>;
+    /**
+     * List active contexts. If language is provided, filters by language/runtime.
+     */
+    listContexts(language?: SupportedLanguage): Promise<CodeContext[]>;
+    /**
+     * Delete a context by id.
+     */
+    deleteContext(contextId: string): Promise<void>;
+    /**
+     * Delete all contexts under the specified language/runtime.
+     */
+    deleteContexts(language: SupportedLanguage): Promise<void>;
+    run(code: string, opts?: {
+        context?: CodeContext;
+        language?: SupportedLanguage;
+        handlers?: ExecutionHandlers;
+        signal?: AbortSignal;
+    }): Promise<Execution>;
+    runStream(req: RunCodeRequest, signal?: AbortSignal): AsyncIterable<ServerStreamEvent>;
+    interrupt(contextId: string): Promise<void>;
+}
+//# sourceMappingURL=codes.d.ts.map

package/dist/services/codes.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"codes.d.ts","sourceRoot":"","sources":["../../src/services/codes.ts"],"names":[],"mappings":"AAcA,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,4BAA4B,CAAC;AACpE,OAAO,KAAK,EAAE,SAAS,EAAE,iBAAiB,EAAE,MAAM,4BAA4B,CAAC;AAC/E,OAAO,KAAK,EAAE,WAAW,EAAE,cAAc,EAAE,iBAAiB,EAAE,MAAM,cAAc,CAAC;AAEnF,MAAM,WAAW,KAAK;IACpB,aAAa,CAAC,QAAQ,EAAE,iBAAiB,GAAG,OAAO,CAAC,WAAW,CAAC,CAAC;IACjE;;OAEG;IACH,UAAU,CAAC,SAAS,EAAE,MAAM,GAAG,OAAO,CAAC,WAAW,CAAC,CAAC;IACpD;;OAEG;IACH,YAAY,CAAC,QAAQ,CAAC,EAAE,iBAAiB,GAAG,OAAO,CAAC,WAAW,EAAE,CAAC,CAAC;IACnE;;OAEG;IACH,aAAa,CAAC,SAAS,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IAChD;;OAEG;IACH,cAAc,CAAC,QAAQ,EAAE,iBAAiB,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IAE3D,GAAG,CACD,IAAI,EAAE,MAAM,EACZ,IAAI,CAAC,EAAE;QAAE,OAAO,CAAC,EAAE,WAAW,CAAC;QAAC,QAAQ,CAAC,EAAE,iBAAiB,CAAC;QAAC,QAAQ,CAAC,EAAE,iBAAiB,CAAC;QAAC,MAAM,CAAC,EAAE,WAAW,CAAA;KAAE,GACjH,OAAO,CAAC,SAAS,CAAC,CAAC;IAEtB,SAAS,CACP,GAAG,EAAE,cAAc,EACnB,MAAM,CAAC,EAAE,WAAW,GACnB,aAAa,CAAC,iBAAiB,CAAC,CAAC;IAEpC,SAAS,CAAC,SAAS,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;CAC7C"}

package/dist/services/codes.js

@@ -0,0 +1,14 @@
+// Copyright 2026 Alibaba Group Holding Ltd.
+// 
+// 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.
+export {};

package/package.json

@@ -0,0 +1,45 @@
+{
+  "name": "@alibaba-group/opensandbox-code-interpreter",
+  "version": "0.1.0-dev1",
+  "description": "OpenSandbox Code Interpreter TypeScript/JavaScript SDK",
+  "license": "Apache-2.0",
+  "type": "module",
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "default": "./dist/index.js"
+    }
+  },
+  "browser": "./dist/index.js",
+  "sideEffects": false,
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/alibaba/OpenSandbox.git"
+  },
+  "bugs": {
+    "url": "https://github.com/alibaba/OpenSandbox/issues"
+  },
+  "homepage": "https://github.com/alibaba/OpenSandbox",
+  "files": [
+    "dist"
+  ],
+  "engines": {
+    "node": ">=20"
+  },
+  "dependencies": {
+    "@alibaba-group/opensandbox": "^0.1.0-dev1"
+  },
+  "devDependencies": {
+    "@eslint/js": "^9.39.2",
+    "eslint": "^9.39.2",
+    "typescript": "^5.7.2",
+    "typescript-eslint": "^8.52.0"
+  },
+  "scripts": {
+    "build": "tsc -p tsconfig.json",
+    "lint": "eslint src --max-warnings 0",
+    "clean": "rm -rf dist"
+  }
+}