@axiom-lattice/opensandbox-gateway 0.1.2

package/src/services/OpenSandboxRuntimeService.ts

@@ -0,0 +1,576 @@
+import { ConnectionConfig, Sandbox, type Volume } from "@alibaba-group/opensandbox";
+import { SandboxManager, type SandboxFilter } from "@alibaba-group/opensandbox";
+import { SandboxException } from "@alibaba-group/opensandbox";
+import type { RuntimeService } from "../types/runtime-service";
+import type { EnsureSandboxInput, ListSandboxesQuery, ShellExecInput } from "../schemas/sandbox";
+import type { SandboxLogsInput } from "../schemas/sandbox";
+import type { SandboxRuntimeMetrics } from "../types/runtime-service";
+import { HttpError } from "../lib/errors";
+
+type CachedEntry = {
+  sandbox: Sandbox;
+  sandboxId: string;
+  createdAt: string;
+  lastUsedAt: number;
+};
+
+type VolumeDefinition = NonNullable<EnsureSandboxInput["volumes"]>[string];
+
+const NAME_METADATA_KEY = "axiom-lattice/name";
+
+function getEnv(key: string, fallback: string): string {
+  return process.env[key] ?? fallback;
+}
+
+function getEnvNumber(key: string, fallback: number): number {
+  const v = process.env[key];
+  return v ? Number(v) : fallback;
+}
+
+export class OpenSandboxRuntimeService implements RuntimeService {
+  private cache = new Map<string, CachedEntry>();
+  private pendingCreates = new Map<string, Promise<CachedEntry>>();
+  private connectionConfig: ConnectionConfig;
+  private defaultImage: string;
+  private defaultCpus: number;
+  private defaultMemoryMib: number;
+  private defaultTimeout: number;
+  private idleTimeoutMs: number;
+
+  constructor() {
+    this.connectionConfig = new ConnectionConfig({
+      domain: getEnv("OPEN_SANDBOX_DOMAIN", "localhost:8080"),
+      protocol: getEnv("OPEN_SANDBOX_PROTOCOL", "http") as "http" | "https",
+      apiKey: process.env["OPEN_SANDBOX_API_KEY"],
+      useServerProxy: getEnv("OPEN_SANDBOX_USE_SERVER_PROXY", "false") === "true",
+    });
+
+    this.defaultImage = getEnv("OPEN_SANDBOX_DEFAULT_IMAGE", "ubuntu:22.04");
+    this.defaultCpus = getEnvNumber("OPEN_SANDBOX_DEFAULT_CPUS", 1);
+    this.defaultMemoryMib = getEnvNumber("OPEN_SANDBOX_DEFAULT_MEMORY_MIB", 2048);
+    this.defaultTimeout = getEnvNumber("OPEN_SANDBOX_DEFAULT_TIMEOUT", 600);
+    this.idleTimeoutMs = getEnvNumber("SANDBOX_IDLE_TIMEOUT_MS", 600_000);
+  }
+
+  private mapVolumes(volumes?: Record<string, VolumeDefinition>): Volume[] {
+    if (!volumes) return [];
+    return Object.entries(volumes).map(([mountPath, def]) => {
+      if (def.type === "bind" && def.source) {
+        return { name: mountPath, host: { path: def.source }, mountPath, readOnly: def.readonly };
+      }
+      if (def.type === "named" && def.name) {
+        return { name: mountPath, pvc: { claimName: def.name }, mountPath, readOnly: def.readonly };
+      }
+      if (def.type === "tmpfs") {
+        throw new HttpError(400, "INVALID_REQUEST", "tmpfs volumes are not supported by OpenSandbox");
+      }
+      throw new HttpError(400, "INVALID_REQUEST", `Unsupported volume type at ${mountPath}`);
+    });
+  }
+
+  private getCached(name: string): CachedEntry {
+    const entry = this.cache.get(name);
+    if (!entry) {
+      throw new HttpError(404, "SANDBOX_NOT_FOUND", `Sandbox '${name}' not found`);
+    }
+    return entry;
+  }
+
+  private async findByNameViaMetadata(name: string): Promise<CachedEntry | null> {
+    try {
+      const manager = SandboxManager.create({ connectionConfig: this.connectionConfig });
+      const result = await manager.listSandboxInfos({
+        metadata: { [NAME_METADATA_KEY]: name },
+        pageSize: 1,
+      });
+
+      if (result.items.length === 0) {
+        return null;
+      }
+
+      const info = result.items[0];
+      const sandbox = await Sandbox.resume({
+        sandboxId: info.id,
+        connectionConfig: this.connectionConfig,
+      });
+
+      const entry: CachedEntry = {
+        sandbox,
+        sandboxId: info.id,
+        createdAt: info.createdAt ? new Date(info.createdAt).toISOString() : new Date().toISOString(),
+        lastUsedAt: Date.now(),
+      };
+      this.cache.set(name, entry);
+      return entry;
+    } catch (err) {
+      if (err instanceof SandboxException && err.error.code === "NOT_FOUND") {
+        return null;
+      }
+      console.warn(`[OpenSandboxRuntimeService] metadata lookup for name=${name} failed:`, err);
+      return null;
+    }
+  }
+
+  async ensureSandbox(
+    name: string,
+    input: EnsureSandboxInput
+  ): Promise<{ name: string; status: string }> {
+    // 1. Check cache
+    const cached = this.cache.get(name);
+    if (cached) {
+      try {
+        const info = await cached.sandbox.getInfo();
+        if (info.status.state === "Running") {
+          cached.lastUsedAt = Date.now();
+          await cached.sandbox.renew(this.defaultTimeout).catch(() => {
+          });
+          return { name, status: "running" };
+        }
+        this.cache.delete(name);
+      } catch {
+        this.cache.delete(name);
+      }
+    }
+
+    // 2. Dedup concurrent creates for same name
+    const inflight = this.pendingCreates.get(name);
+    if (inflight) {
+      await inflight;
+      return { name, status: "running" };
+    }
+
+    // 3. Try metadata recovery (crash recovery)
+    const recovered = await this.findByNameViaMetadata(name);
+    if (recovered) {
+      return { name, status: "running" };
+    }
+
+    // 4. Create new sandbox
+    const creation = this.doCreateSandbox(name, input);
+    this.pendingCreates.set(name, creation);
+    try {
+      await creation;
+      return { name, status: "running" };
+    } finally {
+      this.pendingCreates.delete(name);
+    }
+  }
+
+  private async doCreateSandbox(
+    name: string,
+    input: EnsureSandboxInput
+  ): Promise<CachedEntry> {
+    const sandbox = await Sandbox.create({
+      connectionConfig: this.connectionConfig,
+      image: input.image ?? this.defaultImage,
+      timeoutSeconds: this.defaultTimeout,
+      resource: {
+        cpu: String(input.cpus ?? this.defaultCpus),
+        memory: `${input.memoryMib ?? this.defaultMemoryMib}Mi`,
+      },
+      env: input.env ?? {},
+      metadata: { [NAME_METADATA_KEY]: name },
+      volumes: this.mapVolumes(input.volumes),
+      entrypoint: ["tail", "-f", "/dev/null"],
+    });
+
+    const info = await sandbox.getInfo();
+
+    const entry: CachedEntry = {
+      sandbox,
+      sandboxId: info.id,
+      createdAt: info.createdAt ? new Date(info.createdAt).toISOString() : new Date().toISOString(),
+      lastUsedAt: Date.now(),
+    };
+    this.cache.set(name, entry);
+    return entry;
+  }
+
+  private wrapError(err: unknown, code: string, message: string): never {
+    if (err instanceof HttpError) throw err;
+    if (err instanceof SandboxException) {
+      throw new HttpError(
+        err.error.code === "NOT_FOUND" ? 404
+          : err.error.code === "FORBIDDEN" ? 403
+          : err.error.code === "CONFLICT" ? 409
+          : err.error.code === "INVALID_REQUEST" ? 400
+          : 500,
+        err.error.code,
+        err.error.message ?? message
+      );
+    }
+    throw new HttpError(500, code, message);
+  }
+
+  async startSandbox(name: string): Promise<{ name: string; status: string }> {
+    const entry = this.getCached(name);
+    try {
+      const resumed = await Sandbox.resume({
+        sandboxId: entry.sandboxId,
+        connectionConfig: this.connectionConfig,
+      });
+      // Update cache with new Sandbox instance (sandboxId may change on K8s)
+      const info = await resumed.getInfo();
+      entry.sandbox = resumed;
+      entry.sandboxId = info.id;
+      entry.lastUsedAt = Date.now();
+      return { name, status: "running" };
+    } catch (err) {
+      throw this.wrapError(err, "SANDBOX_NOT_FOUND", `Failed to start sandbox '${name}'`);
+    }
+  }
+
+  async stopSandbox(name: string): Promise<{ name: string; status: string }> {
+    const entry = this.getCached(name);
+    try {
+      await entry.sandbox.pause();
+      return { name, status: "stopped" };
+    } catch (err) {
+      throw this.wrapError(err, "INTERNAL_ERROR", `Failed to stop sandbox '${name}'`);
+    }
+  }
+
+  async killSandbox(name: string): Promise<{ name: string; status: string }> {
+    const entry = this.cache.get(name);
+    if (!entry) {
+      throw new HttpError(404, "SANDBOX_NOT_FOUND", `Sandbox '${name}' not found`);
+    }
+    try {
+      await entry.sandbox.kill();
+    } catch {
+      // kill failure is non-fatal
+    }
+    try {
+      await entry.sandbox.close();
+    } catch {
+      // close failure is non-fatal
+    }
+    this.cache.delete(name);
+    return { name, status: "unknown" };
+  }
+
+  async deleteSandbox(name: string): Promise<{ name: string; status: string }> {
+    return this.killSandbox(name);
+  }
+
+  async getStatus(name: string): Promise<{ name: string; status: string }> {
+    const entry = this.cache.get(name);
+    if (entry) {
+      try {
+        const info = await entry.sandbox.getInfo();
+        const status = info.status.state.toLowerCase();
+        return { name, status };
+      } catch {
+        return { name, status: "unknown" };
+      }
+    }
+    // Try server-side lookup
+    try {
+      const manager = SandboxManager.create({ connectionConfig: this.connectionConfig });
+      const result = await manager.listSandboxInfos({
+        metadata: { [NAME_METADATA_KEY]: name },
+        pageSize: 1,
+      });
+      if (result.items.length > 0) {
+        return { name, status: result.items[0].status.state.toLowerCase() };
+      }
+    } catch {
+      // ignore
+    }
+    return { name, status: "unknown" };
+  }
+
+  private resolvePath(path: string): string {
+    if (path === "~" || path === "~/") return "/";
+    if (path.startsWith("~/")) return `/${path.slice(2)}`;
+    return path;
+  }
+
+  async readFile(sandboxName: string, path: string): Promise<{ path: string; content: string }> {
+    const resolvedPath = this.resolvePath(path);
+    const entry = this.getCached(sandboxName);
+    try {
+      const content = await entry.sandbox.files.readFile(resolvedPath);
+      return { path: resolvedPath, content };
+    } catch (err) {
+      throw this.wrapError(err, "INTERNAL_ERROR", `Failed to read file '${resolvedPath}' in sandbox '${sandboxName}'`);
+    }
+  }
+
+  async writeFile(sandboxName: string, path: string, content: string): Promise<{ path: string }> {
+    const resolvedPath = this.resolvePath(path);
+    const entry = this.getCached(sandboxName);
+    try {
+      // Create parent directories if needed
+      const parentDir = resolvedPath.split("/").slice(0, -1).join("/") || "/";
+      await entry.sandbox.files.createDirectories([{ path: parentDir }]).catch(() => {
+        // parent may already exist
+      });
+      await entry.sandbox.files.writeFiles([{ path: resolvedPath, data: content }]);
+      return { path: resolvedPath };
+    } catch (err) {
+      throw this.wrapError(err, "INTERNAL_ERROR", `Failed to write file '${resolvedPath}' in sandbox '${sandboxName}'`);
+    }
+  }
+
+  async listPath(
+    sandboxName: string,
+    path: string,
+    recursive?: boolean
+  ): Promise<{ entries: Array<{ path: string; type: string }> }> {
+    const resolvedPath = this.resolvePath(path);
+    const entry = this.getCached(sandboxName);
+    try {
+      const files = await entry.sandbox.files.listDirectory({
+        path: resolvedPath,
+        depth: recursive ? undefined : 1,
+      });
+      return {
+        entries: files.map((f) => ({
+          path: f.path,
+          type: f.isDir === true ? "directory" : f.isSymlink === true ? "symlink" : "file",
+        })),
+      };
+    } catch (err) {
+      throw this.wrapError(err, "INTERNAL_ERROR", `Failed to list path '${resolvedPath}' in sandbox '${sandboxName}'`);
+    }
+  }
+
+  async findFiles(sandboxName: string, path: string, pattern: string): Promise<{ files: string[] }> {
+    const resolvedPath = this.resolvePath(path);
+    const entry = this.getCached(sandboxName);
+    try {
+      const results = await entry.sandbox.files.search({
+        path: resolvedPath,
+        pattern: pattern || "*",
+      });
+      return { files: results.map((r) => r.path) };
+    } catch (err) {
+      // Fallback to shell find command
+      try {
+        const result = await entry.sandbox.commands.run(
+          `find ${resolvedPath} -name '${pattern}' -type f`,
+          { timeoutSeconds: 30 }
+        );
+        return { files: result.logs.stdout.map((s) => s.text).join("").split("\n").filter(Boolean) };
+      } catch {
+        throw this.wrapError(err, "INTERNAL_ERROR", `Failed to find files in '${resolvedPath}'`);
+      }
+    }
+  }
+
+  async searchInFile(
+    sandboxName: string,
+    path: string,
+    query: string
+  ): Promise<{ matches: Array<{ line: number; content: string }> }> {
+    const resolvedPath = this.resolvePath(path);
+    const entry = this.getCached(sandboxName);
+    try {
+      const result = await entry.sandbox.commands.run(
+        `grep -n -E '${query.replace(/'/g, "'\\''")}' ${resolvedPath}`,
+        { timeoutSeconds: 30 }
+      );
+      const stdout = result.logs.stdout.map((s) => s.text).join("");
+      if (!stdout.trim()) return { matches: [] };
+      return {
+        matches: stdout.split("\n").filter(Boolean).map((line) => {
+          const idx = line.indexOf(":");
+          return { line: Number(line.slice(0, idx)), content: line.slice(idx + 1) };
+        }),
+      };
+    } catch (err: unknown) {
+      // grep returns exit code 1 for no matches — may throw or not
+      if (err instanceof SandboxException) return { matches: [] };
+      if (typeof err === "object" && err !== null && "code" in err && (err as { code: number }).code === 1) {
+        return { matches: [] };
+      }
+      return { matches: [] };
+    }
+  }
+
+  async replaceInFile(
+    sandboxName: string,
+    input: { path: string; search: string; replace: string }
+  ): Promise<{ replaced: number }> {
+    const resolvedPath = this.resolvePath(input.path);
+    const entry = this.getCached(sandboxName);
+    try {
+      const original = await entry.sandbox.files.readFile(resolvedPath);
+      if (!input.search) return { replaced: 0 };
+      const occurrences = original.split(input.search).length - 1;
+      if (occurrences === 0) return { replaced: 0 };
+      const updated = original.split(input.search).join(input.replace);
+      await entry.sandbox.files.writeFiles([{ path: resolvedPath, data: updated }]);
+      return { replaced: occurrences };
+    } catch (err) {
+      throw this.wrapError(err, "INTERNAL_ERROR", `Failed to replace in file '${resolvedPath}'`);
+    }
+  }
+
+  async uploadFile(sandboxName: string, path: string, contentBase64: string): Promise<{ path: string }> {
+    const resolvedPath = this.resolvePath(path);
+    const entry = this.getCached(sandboxName);
+    try {
+      const data = Buffer.from(contentBase64, "base64").toString("utf-8");
+      await entry.sandbox.files.writeFiles([{ path: resolvedPath, data }]);
+      return { path: resolvedPath };
+    } catch (err) {
+      throw this.wrapError(err, "INTERNAL_ERROR", `Failed to upload file '${resolvedPath}'`);
+    }
+  }
+
+  async downloadFile(sandboxName: string, path: string): Promise<{ path: string; contentBase64: string }> {
+    const resolvedPath = this.resolvePath(path);
+    const entry = this.getCached(sandboxName);
+    try {
+      const data = await entry.sandbox.files.readBytes(resolvedPath);
+      const b64 = Buffer.from(data).toString("base64");
+      return { path: resolvedPath, contentBase64: b64 };
+    } catch (err) {
+      throw this.wrapError(err, "INTERNAL_ERROR", `Failed to download file '${resolvedPath}'`);
+    }
+  }
+
+  async execCommand(input: ShellExecInput): Promise<{ stdout: string; stderr: string; exitCode: number }> {
+    const entry = this.getCached(input.sandboxName);
+    try {
+      const result = await entry.sandbox.commands.run(input.command, {
+        workingDirectory: input.exec_dir,
+        timeoutSeconds: input.timeout ? Math.ceil(input.timeout / 1000) : undefined,
+      });
+      return {
+        stdout: result.logs.stdout.map((s) => s.text).join(""),
+        stderr: result.logs.stderr.map((s) => s.text).join(""),
+        exitCode: result.exitCode ?? 0,
+      };
+    } catch (err) {
+      throw this.wrapError(err, "INTERNAL_ERROR", `Command execution failed in sandbox '${input.sandboxName}'`);
+    }
+  }
+
+  async getSandbox(
+    name: string
+  ): Promise<{
+    name: string;
+    status: string;
+    image: unknown;
+    cpus?: number;
+    memoryMib?: number;
+    env: unknown;
+    volumes: Record<string, unknown>;
+    metrics?: SandboxRuntimeMetrics;
+    createdAt: string;
+    updatedAt: string;
+  } | undefined> {
+    // Try cache first
+    const entry = this.cache.get(name);
+    if (entry) {
+      try {
+        const info = await entry.sandbox.getInfo();
+        return {
+          name,
+          status: info.status.state.toLowerCase(),
+          image: info.image?.uri ?? "unknown",
+          cpus: undefined,
+          memoryMib: undefined,
+          env: {},
+          volumes: {},
+          metrics: undefined,
+          createdAt: info.createdAt ? new Date(info.createdAt).toISOString() : entry.createdAt,
+          updatedAt: info.createdAt ? new Date(info.createdAt).toISOString() : entry.createdAt,
+        };
+      } catch {
+        this.cache.delete(name);
+      }
+    }
+
+    // Try server-side lookup via metadata
+    try {
+      const manager = SandboxManager.create({ connectionConfig: this.connectionConfig });
+      const result = await manager.listSandboxInfos({
+        metadata: { [NAME_METADATA_KEY]: name },
+        pageSize: 1,
+      });
+      if (result.items.length > 0) {
+        const info = result.items[0];
+        return {
+          name,
+          status: info.status.state.toLowerCase(),
+          image: info.image?.uri ?? "unknown",
+          cpus: undefined,
+          memoryMib: undefined,
+          env: {},
+          volumes: {},
+          metrics: undefined,
+          createdAt: info.createdAt ? new Date(info.createdAt).toISOString() : "",
+          updatedAt: info.createdAt ? new Date(info.createdAt).toISOString() : "",
+        };
+      }
+    } catch {
+      // ignore
+    }
+
+    return undefined;
+  }
+
+  async listSandboxes(_query: ListSandboxesQuery): Promise<{
+    items: Array<{
+      name: string;
+      status: string;
+      image: unknown;
+      cpus?: number;
+      memoryMib?: number;
+      envCount: number;
+      volumeCount: number;
+      createdAt: string;
+      updatedAt: string;
+    }>;
+    total: number;
+  }> {
+    try {
+      const manager = SandboxManager.create({ connectionConfig: this.connectionConfig });
+      const filter: SandboxFilter = {};
+      if (_query.status) filter.states = [_query.status];
+      const result = await manager.listSandboxInfos(filter);
+
+      const items = result.items
+        .filter((info) => {
+          if (_query.search) {
+            const haystack = [info.id, info.image?.uri].filter(Boolean).join(" ").toLowerCase();
+            return haystack.includes(_query.search.toLowerCase());
+          }
+          return true;
+        })
+        .map((info) => ({
+          name: info.id,
+          status: info.status.state.toLowerCase(),
+          image: info.image?.uri ?? "unknown",
+          cpus: undefined,
+          memoryMib: undefined,
+          envCount: 0,
+          volumeCount: 0,
+          createdAt: info.createdAt ? new Date(info.createdAt).toISOString() : "",
+          updatedAt: info.createdAt ? new Date(info.createdAt).toISOString() : "",
+        }));
+
+      return { items, total: items.length };
+    } catch {
+      return { items: [], total: 0 };
+    }
+  }
+
+  async getSandboxLogs(
+    _name: string,
+    _opts: SandboxLogsInput
+  ): Promise<{
+    entries: Array<{
+      timestamp: string;
+      source: string;
+      sessionId: number | null;
+      text: string;
+    }>;
+  }> {
+    return { entries: [] };
+  }
+}

package/src/swagger.ts

@@ -0,0 +1,40 @@
+import type { FastifyInstance } from "fastify";
+import swagger from "@fastify/swagger";
+import swaggerUi from "@fastify/swagger-ui";
+
+const swaggerConfig = {
+  openapi: {
+    openapi: "3.0.0",
+    info: {
+      title: "OpenSandbox Gateway API",
+      description: "Sandbox lifecycle management backed by OpenSandbox",
+      version: "1.0.0",
+    },
+    servers: [{ url: "http://localhost:4002", description: "Local development" }],
+    components: {
+      securitySchemes: {
+        bearerAuth: { type: "http" as const, scheme: "bearer" as const, bearerFormat: "API Key" },
+      },
+    },
+    tags: [
+      { name: "Sandboxes", description: "Sandbox lifecycle" },
+      { name: "Files", description: "File operations inside sandboxes" },
+      { name: "Shell", description: "Execute commands inside sandboxes" },
+      { name: "Images", description: "Image management (stub)" },
+      { name: "Volumes", description: "Named volume filesystem operations" },
+      { name: "Health", description: "Service health check" },
+    ],
+  },
+};
+
+const swaggerUiConfig = {
+  routePrefix: "/api-docs",
+  uiConfig: { docExpansion: "list" as const, deepLinking: true },
+  staticCSP: true,
+  transformStaticCSP: (header: string) => header,
+};
+
+export async function configureSwagger(app: FastifyInstance) {
+  await app.register(swagger, swaggerConfig);
+  await app.register(swaggerUi, swaggerUiConfig);
+}

package/src/types/runtime-service.ts

@@ -0,0 +1,79 @@
+import type { EnsureSandboxInput, ListSandboxesQuery, ShellExecInput } from "../schemas/sandbox";
+
+export type SandboxRuntimeMetrics = {
+  cpuPercent: number;
+  memoryBytes: number;
+  memoryLimitBytes: number;
+  diskReadBytes: number;
+  diskWriteBytes: number;
+  netRxBytes: number;
+  netTxBytes: number;
+  uptimeMs: number;
+  timestampMs: number;
+};
+
+export interface RuntimeService {
+  ensureSandbox(name: string, input: EnsureSandboxInput): Promise<{ name: string; status: string }>;
+  startSandbox(name: string): Promise<{ name: string; status: string }>;
+  stopSandbox(name: string): Promise<{ name: string; status: string }>;
+  killSandbox(name: string): Promise<{ name: string; status: string }>;
+  deleteSandbox(name: string): Promise<{ name: string; status: string }>;
+  listSandboxes(query: ListSandboxesQuery): Promise<{
+    items: Array<{
+      name: string;
+      status: string;
+      image: unknown;
+      cpus?: number;
+      memoryMib?: number;
+      envCount: number;
+      volumeCount: number;
+      createdAt: string;
+      updatedAt: string;
+    }>;
+    total: number;
+  }>;
+  getSandbox(name: string): Promise<{
+    name: string;
+    status: string;
+    image: unknown;
+    cpus?: number;
+    memoryMib?: number;
+    env: unknown;
+    volumes: Record<string, unknown>;
+    metrics?: SandboxRuntimeMetrics;
+    createdAt: string;
+    updatedAt: string;
+  } | undefined>;
+  getStatus(name: string): Promise<{ name: string; status: string }>;
+  readFile(sandboxName: string, path: string): Promise<{ path: string; content: string }>;
+  writeFile(sandboxName: string, path: string, content: string): Promise<{ path: string }>;
+  listPath(
+    sandboxName: string,
+    path: string,
+    recursive?: boolean
+  ): Promise<{ entries: Array<{ path: string; type: string }> }>;
+  findFiles(sandboxName: string, path: string, pattern: string): Promise<{ files: string[] }>;
+  searchInFile(
+    sandboxName: string,
+    path: string,
+    query: string
+  ): Promise<{ matches: Array<{ line: number; content: string }> }>;
+  replaceInFile(
+    sandboxName: string,
+    input: { path: string; search: string; replace: string }
+  ): Promise<{ replaced: number }>;
+  uploadFile(sandboxName: string, path: string, contentBase64: string): Promise<{ path: string }>;
+  downloadFile(sandboxName: string, path: string): Promise<{ path: string; contentBase64: string }>;
+  execCommand(input: ShellExecInput): Promise<{ stdout: string; stderr: string; exitCode: number }>;
+  getSandboxLogs(
+    name: string,
+    opts: { tail?: number; since?: string; until?: string; sources?: string[] }
+  ): Promise<{
+    entries: Array<{
+      timestamp: string;
+      source: string;
+      sessionId: number | null;
+      text: string;
+    }>;
+  }>;
+}