Secure, Fast, and Extensible Sandbox runtime for AI agents.
// 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 } from "../openapi/execdClient.js";
import { throwOnOpenApiFetchError } from "./openapiError.js";
import { parseJsonEventStream } from "./sse.js";
import type { paths as ExecdPaths } from "../api/execd.js";
import type {
CommandExecution,
CommandLogs,
CommandStatus,
RunCommandOpts,
ServerStreamEvent,
} from "../models/execd.js";
import type { ExecdCommands } from "../services/execdCommands.js";
import type { ExecutionHandlers } from "../models/execution.js";
import { inferExecutionExitCode } from "../models/execution.js";
import { ExecutionEventDispatcher } from "../models/executionEventDispatcher.js";
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}`;
}
/** Request body for POST /command (from generated spec; includes uid, gid, envs). */
type ApiRunCommandRequest =
ExecdPaths["/command"]["post"]["requestBody"]["content"]["application/json"];
type ApiCommandStatusOk =
ExecdPaths["/command/status/{id}"]["get"]["responses"][200]["content"]["application/json"];
type ApiCreateSessionRequest =
NonNullable<ExecdPaths["/session"]["post"]["requestBody"]>["content"]["application/json"];
type ApiCreateSessionOk =
ExecdPaths["/session"]["post"]["responses"][200]["content"]["application/json"];
type ApiRunInSessionRequest =
ExecdPaths["/session/{sessionId}/run"]["post"]["requestBody"]["content"]["application/json"];
interface StreamingExecutionSpec<TBody> {
pathname: string;
body: TBody;
fallbackErrorMessage: string;
}
function toRunCommandRequest(command: string | string[], opts?: RunCommandOpts): ApiRunCommandRequest {
if (opts?.gid != null && opts.uid == null) {
throw new Error("uid is required when gid is provided");
}
const body: ApiRunCommandRequest = {
...(typeof command === "string" ? { command } : { argv: command }),
cwd: opts?.workingDirectory,
background: !!opts?.background,
};
if (opts?.timeoutSeconds != null) {
body.timeout = Math.round(opts.timeoutSeconds * 1000);
}
if (opts?.uid != null) {
body.uid = opts.uid;
}
if (opts?.gid != null) {
body.gid = opts.gid;
}
if (opts?.envs != null) {
body.envs = opts.envs;
}
return body;
}
function toRunInSessionRequest(
command: string,
opts?: { workingDirectory?: string; timeoutSeconds?: number },
): ApiRunInSessionRequest {
const body: ApiRunInSessionRequest = {
command,
};
if (opts?.workingDirectory != null) {
body.cwd = opts.workingDirectory;
}
if (opts?.timeoutSeconds != null) {
body.timeout = Math.round(opts.timeoutSeconds * 1000);
}
return body;
}
function assertNonBlank(value: string, field: string): void {
if (!value.trim()) {
throw new Error(`${field} cannot be empty`);
}
}
const ENV_KEY_PATTERN = /^[A-Za-z_][A-Za-z0-9_]*$/;
/** Quotes a string as a single POSIX shell word. */
function shellQuote(value: string): string {
return `'${value.replaceAll("'", `'\\''`)}'`;
}
/** Escapes a value for the runtime env file's double-quoted form. */
function escapeDoubleQuoted(value: string): string {
return value
.replaceAll("\\", "\\\\")
.replaceAll('"', '\\"')
.replaceAll("\n", "\\n")
.replaceAll("\r", "\\r")
.replaceAll("\t", "\\t");
}
/**
* Builds the sandbox-side snippet that appends KEY=VALUE to the env file named
* by the sandbox's EXECD_ENVS variable. Values without a single quote use the
* runtime env file's lossless single-quoted form; otherwise the double-quoted
* form is used (shell-style `$NAME` sequences in such values may be expanded
* when the runtime loads the file).
*/
function buildSetEnvCommand(key: string, value: string): string {
if (!ENV_KEY_PATTERN.test(key)) {
throw new Error(`setEnv key must match ${ENV_KEY_PATTERN.source}, got '${key}'`);
}
if (value.includes("\0")) {
throw new Error("setEnv value cannot contain NUL bytes");
}
const entry = value.includes("'")
? `${key}="${escapeDoubleQuoted(value)}"`
: `${key}='${value}'`;
return [
`if [ -z "\${EXECD_ENVS:-}" ]; then printf '%s\\n' 'EXECD_ENVS is not set; cannot persist environment variable ${key}' >&2; exit 1; fi`,
`mkdir -p "$(dirname "$EXECD_ENVS")"`,
`printf '%s\\n' ${shellQuote(entry)} >> "$EXECD_ENVS"`,
].join("\n");
}
function parseOptionalDate(value: unknown, field: string): Date | undefined {
if (value == null) return undefined;
if (value instanceof Date) return value;
if (typeof value !== "string") {
throw new Error(`Invalid ${field}: expected ISO string, got ${typeof value}`);
}
const parsed = new Date(value);
if (Number.isNaN(parsed.getTime())) {
throw new Error(`Invalid ${field}: ${value}`);
}
return parsed;
}
export interface CommandsAdapterOptions {
/**
* Must match the baseUrl used by the ExecdClient.
*/
baseUrl: string;
fetch?: typeof fetch;
headers?: Record<string, string>;
}
export class CommandsAdapter implements ExecdCommands {
private readonly fetch: typeof fetch;
constructor(
private readonly client: ExecdClient,
private readonly opts: CommandsAdapterOptions,
) {
this.fetch = opts.fetch ?? fetch;
}
private buildRunStreamSpec(
command: string | string[],
opts?: RunCommandOpts,
): StreamingExecutionSpec<ApiRunCommandRequest> {
if (typeof command === "string") {
assertNonBlank(command, "command");
} else {
if (!Array.isArray(command) || !command.length || !command[0]) {
throw new Error("argv requires a non-empty executable and strings without NUL");
}
for (const arg of command) {
if (typeof arg !== "string" || arg.includes("\0")) {
throw new Error("argv requires a non-empty executable and strings without NUL");
}
}
}
return {
pathname: "/command",
body: toRunCommandRequest(command, opts),
fallbackErrorMessage: "Run command failed",
};
}
private buildRunInSessionStreamSpec(
sessionId: string,
command: string,
opts?: { workingDirectory?: string; timeoutSeconds?: number },
): StreamingExecutionSpec<ApiRunInSessionRequest> {
assertNonBlank(sessionId, "sessionId");
assertNonBlank(command, "command");
return {
pathname: `/session/${encodeURIComponent(sessionId)}/run`,
body: toRunInSessionRequest(command, opts),
fallbackErrorMessage: "Run in session failed",
};
}
private async *streamExecution<TBody>(
spec: StreamingExecutionSpec<TBody>,
signal?: AbortSignal,
): AsyncIterable<ServerStreamEvent> {
const url = joinUrl(this.opts.baseUrl, spec.pathname);
const res = await this.fetch(url, {
method: "POST",
headers: {
accept: "text/event-stream",
"content-type": "application/json",
...(this.opts.headers ?? {}),
},
body: JSON.stringify(spec.body),
signal,
});
for await (const ev of parseJsonEventStream<ServerStreamEvent>(res, {
fallbackErrorMessage: spec.fallbackErrorMessage,
})) {
yield ev;
}
}
private async consumeExecutionStream(
stream: AsyncIterable<ServerStreamEvent>,
handlers?: ExecutionHandlers,
inferExitCode = false,
isBackground = false,
): Promise<CommandExecution> {
const execution: CommandExecution = {
logs: { stdout: [], stderr: [] },
result: [],
};
const dispatcher = new ExecutionEventDispatcher(execution, handlers);
for await (const ev of stream) {
if (ev.type === "init" && (ev.text ?? "") === "" && execution.id) {
(ev as { text?: string }).text = execution.id;
}
await dispatcher.dispatch(ev as any);
if (isBackground && ev.type === "execution_complete") {
// Background commands are done once execution_complete arrives; do
// not wait for the chunked terminator, which older execd versions
// delay with a grace-period sleep and can be lost if the connection is
// closed early (#1528).
break;
}
}
if (inferExitCode) {
execution.exitCode = inferExecutionExitCode(execution);
}
return execution;
}
async setEnv(key: string, value: string): Promise<void> {
const command = buildSetEnvCommand(key, value);
const execution = await this.run(command);
if (execution.error != null || execution.exitCode !== 0) {
const stderr = execution.logs.stderr.map((m) => m.text).join("").trim();
const detail = stderr.length > 0 ? stderr : (execution.error?.value?.trim() ?? "");
throw new Error(`commands.setEnv failed for '${key}'${detail ? `: ${detail}` : ""}`);
}
}
async interrupt(sessionId: string): Promise<void> {
const { error, response } = await this.client.DELETE("/command", {
params: { query: { id: sessionId } },
});
throwOnOpenApiFetchError({ error, response }, "Interrupt command failed");
}
async getCommandStatus(commandId: string): Promise<CommandStatus> {
const { data, error, response } = await this.client.GET("/command/status/{id}", {
params: { path: { id: commandId } },
});
throwOnOpenApiFetchError({ error, response }, "Get command status failed");
const ok = data as ApiCommandStatusOk | undefined;
if (!ok || typeof ok !== "object") {
throw new Error("Get command status failed: unexpected response shape");
}
return {
id: ok.id,
content: ok.content,
running: ok.running,
exitCode: ok.exit_code ?? null,
error: ok.error,
startedAt: parseOptionalDate(ok.started_at, "startedAt"),
finishedAt: parseOptionalDate(ok.finished_at, "finishedAt") ?? null,
};
}
async getBackgroundCommandLogs(commandId: string, cursor?: number): Promise<CommandLogs> {
if (cursor != null && cursor < 0) {
throw new Error("cursor cannot be negative");
}
const { data, error, response } = await this.client.GET("/command/{id}/logs", {
params: { path: { id: commandId }, query: cursor == null ? {} : { cursor } },
parseAs: "text",
});
throwOnOpenApiFetchError({ error, response }, "Get command logs failed");
let content: string;
if (typeof data === "string") {
content = data;
} else if (data == null && response.ok) {
content = "";
} else {
throw new Error("Get command logs failed: unexpected response shape");
}
const cursorHeader = response.headers.get("EXECD-COMMANDS-TAIL-CURSOR");
const parsedCursor = cursorHeader != null && cursorHeader !== "" ? Number(cursorHeader) : undefined;
return {
content,
cursor: Number.isFinite(parsedCursor ?? NaN) ? parsedCursor : undefined,
};
}
async *runStream(
command: string | string[],
opts?: RunCommandOpts,
signal?: AbortSignal,
): AsyncIterable<ServerStreamEvent> {
for await (const ev of this.streamExecution(
this.buildRunStreamSpec(command, opts),
signal,
)) {
yield ev;
}
}
async run(
command: string | string[],
opts?: RunCommandOpts,
handlers?: ExecutionHandlers,
signal?: AbortSignal,
): Promise<CommandExecution> {
return this.consumeExecutionStream(
this.runStream(command, opts, signal),
handlers,
!opts?.background,
!!opts?.background,
);
}
async createSession(options?: { workingDirectory?: string }): Promise<string> {
const body: ApiCreateSessionRequest =
options?.workingDirectory != null ? { cwd: options.workingDirectory } : {};
const { data, error, response } = await this.client.POST("/session", {
body,
});
throwOnOpenApiFetchError({ error, response }, "Create session failed");
const ok = data as ApiCreateSessionOk | undefined;
if (!ok || typeof (ok as { session_id?: string }).session_id !== "string") {
throw new Error("Create session failed: unexpected response shape");
}
return (ok as { session_id: string }).session_id;
}
async *runInSessionStream(
sessionId: string,
command: string,
opts?: { workingDirectory?: string; timeoutSeconds?: number },
signal?: AbortSignal,
): AsyncIterable<ServerStreamEvent> {
for await (const ev of this.streamExecution(
this.buildRunInSessionStreamSpec(sessionId, command, opts),
signal,
)) {
yield ev;
}
}
async runInSession(
sessionId: string,
command: string,
options?: { workingDirectory?: string; timeoutSeconds?: number },
handlers?: ExecutionHandlers,
signal?: AbortSignal,
): Promise<CommandExecution> {
return this.consumeExecutionStream(
this.runInSessionStream(sessionId, command, options, signal),
handlers,
true,
);
}
async deleteSession(sessionId: string): Promise<void> {
const { error, response } = await this.client.DELETE(
"/session/{sessionId}",
{ params: { path: { sessionId } } },
);
throwOnOpenApiFetchError({ error, response }, "Delete session failed");
}
}