@axiom-lattice/opensandbox-gateway 0.2.9 → 0.2.11

package/.turbo/turbo-build.log

@@ -1,5 +1,5 @@
 
-> @axiom-lattice/opensandbox-gateway@0.2.9 build /home/runner/work/agentic/agentic/packages/opensandbox-gateway
+> @axiom-lattice/opensandbox-gateway@0.2.11 build /home/runner/work/agentic/agentic/packages/opensandbox-gateway
 > tsup src/index.ts src/cli.ts --format esm --dts --clean --sourcemap
 
 CLI Building entry: src/cli.ts, src/index.ts
@@ -10,12 +10,12 @@
 ESM Build start
 ESM dist/cli.mjs                245.00 B
 ESM dist/index.mjs              196.00 B
-ESM dist/chunk-M6FKTT7J.mjs     38.24 KB
+ESM dist/chunk-QC7CI5UY.mjs     47.41 KB
 ESM dist/cli.mjs.map            387.00 B
 ESM dist/index.mjs.map          71.00 B
-ESM dist/chunk-M6FKTT7J.mjs.map 79.90 KB
-ESM ⚡️ Build success in 145ms
+ESM dist/chunk-QC7CI5UY.mjs.map 99.42 KB
+ESM ⚡️ Build success in 166ms
 DTS Build start
-DTS ⚡️ Build success in 29026ms
+DTS ⚡️ Build success in 18414ms
 DTS dist/cli.d.mts   20.00 B
-DTS dist/index.d.mts 10.55 KB
+DTS dist/index.d.mts 13.25 KB

package/CHANGELOG.md

@@ -1,5 +1,22 @@
 # @axiom-lattice/opensandbox-gateway
 
+## 0.2.11
+
+### Patch Changes
+
+- a19e0aa: Unify the sandbox service base-URL env and treat missing sandbox files as a structured not-found (ADR-174 / ADR-175).
+
+  The resident plugin deployment runtime now reads `MICROSANDBOX_SERVICE_BASE_URL` only (dropping `MICROSANDBOX_SERVICE_URL`), so a provider-only config also enables `manage_plugin` deploy/undeploy/status; `sandbox-console` reads `VITE_MICROSANDBOX_SERVICE_BASE_URL`. `MICROSANDBOX_SERVICE_URL` no longer has any effect.
+
+  `opensandbox-gateway` now preserves the sandbox's upstream HTTP status (and surfaces execd's `{ code, message }`) instead of collapsing every failure to `500 "Download failed"`, and `MicrosandboxServiceClient` attaches the HTTP status to request errors; `microsandbox-service` `readFile`/`downloadFile` map missing files to `404 FILE_NOT_FOUND` (matching `deleteFile`). A missing sandbox file (e.g. the plugin-skill manifest) is therefore classified as not-found rather than a hard failure, fixing `Error loading skill content: ... Download failed`.
+
+## 0.2.10
+
+### Patch Changes
+
+- 26fecff: task refactor
+- 910bd08: enhance tasks
+
 ## 0.2.9
 
 ### Patch Changes

package/README.md

@@ -193,10 +193,10 @@ lattice-opensandbox-gateway
 
 ## Connecting from Core
 
-Set the same `MICROSANDBOX_SERVICE_URL` used for microsandbox-service:
+Set the same `MICROSANDBOX_SERVICE_BASE_URL` used for microsandbox-service:
 
 ```bash
-MICROSANDBOX_SERVICE_URL=http://localhost:4002
+MICROSANDBOX_SERVICE_BASE_URL=http://localhost:4002
 ```
 
 The `MicrosandboxRemoteProvider` → `MicrosandboxServiceClient` → HTTP → gateway chain works identically.
@@ -254,7 +254,7 @@ Deploys the full sandbox stack (`opensandbox-server` + `opensandbox-gateway`) wi
 
 ```
 Core (agent)                              Docker host
-  │ MICROSANDBOX_SERVICE_URL                    │
+  │ MICROSANDBOX_SERVICE_BASE_URL                    │
   ▼                                             │
 opensandbox-gateway ──HTTP──▶ opensandbox-server ──docker.sock──▶ sandbox containers
 (Node Fastify, :4002)          (Python FastAPI, :8080)
@@ -299,7 +299,7 @@ curl -H "Authorization: Bearer $SANDBOX_API_KEY" http://localhost:4002/api/sandb
 On the agent process, set:
 
 ```bash
-MICROSANDBOX_SERVICE_URL=http://localhost:4002
+MICROSANDBOX_SERVICE_BASE_URL=http://localhost:4002
 MICROSANDBOX_API_KEY=<same as SANDBOX_API_KEY>
 MICROSANDBOX_IMAGE=kioko12520/sandbox:0.1.0   # optional, dynamic sandbox image
 ```

package/deploy/OFFLINE_DEPLOYMENT.md

@@ -69,7 +69,7 @@ curl -X POST "http://localhost:4002/api/files/read" \
 ## Connect the agent (Core)
 
 ```bash
-MICROSANDBOX_SERVICE_URL=http://localhost:4002
+MICROSANDBOX_SERVICE_BASE_URL=http://localhost:4002
 MICROSANDBOX_API_KEY=<same as SANDBOX_API_KEY>
 MICROSANDBOX_IMAGE=kioko12520/sandbox:0.1.0
 ```

package/deploy/README.md

@@ -14,7 +14,7 @@ Self-contained Docker Compose deployment for the Axiom Lattice OpenSandbox sandb
 
 ```
 Core (agent)                              Docker host
-  │ MICROSANDBOX_SERVICE_URL                    │
+  │ MICROSANDBOX_SERVICE_BASE_URL                    │
   ▼                                             ▼
 opensandbox-gateway ──HTTP──▶ opensandbox-server ──docker.sock──▶ sandbox containers
 (Node Fastify, :4002)          (Python FastAPI, :8080)
@@ -40,7 +40,7 @@ curl http://localhost:4002/health   # gateway
 Then on the agent process:
 
 ```bash
-MICROSANDBOX_SERVICE_URL=http://localhost:4002
+MICROSANDBOX_SERVICE_BASE_URL=http://localhost:4002
 MICROSANDBOX_API_KEY=<same as SANDBOX_API_KEY>
 MICROSANDBOX_IMAGE=kioko12520/sandbox:0.1.0   # optional; dynamic business sandbox image
 ```

package/dist/{chunk-M6FKTT7J.mjs → chunk-QC7CI5UY.mjs}

@@ -1,7 +1,7 @@
 // src/services/OpenSandboxRuntimeService.ts
 import { ConnectionConfig, Sandbox } from "@alibaba-group/opensandbox";
 import { SandboxManager } from "@alibaba-group/opensandbox";
-import { SandboxException } from "@alibaba-group/opensandbox";
+import { SandboxApiException, SandboxException } from "@alibaba-group/opensandbox";
 
 // src/lib/errors.ts
 var HttpError = class extends Error {
@@ -57,6 +57,37 @@ function getEnvNumber(key, fallback) {
   const v = process.env[key];
   return v ? Number(v) : fallback;
 }
+function isHttpStatus(value) {
+  return typeof value === "number" && Number.isInteger(value) && value >= 400 && value <= 599;
+}
+function mapSandboxErrorCodeToStatus(code) {
+  switch (code) {
+    case "NOT_FOUND":
+    case "FILE_NOT_FOUND":
+      return 404;
+    case "FORBIDDEN":
+      return 403;
+    case "CONFLICT":
+      return 409;
+    case "INVALID_REQUEST":
+    case "INVALID_ARGUMENT":
+      return 400;
+    default:
+      return 500;
+  }
+}
+function parseUpstreamError(rawBody) {
+  if (typeof rawBody !== "string" || rawBody.length === 0) return {};
+  try {
+    const parsed = JSON.parse(rawBody);
+    return {
+      code: typeof parsed.code === "string" ? parsed.code : void 0,
+      message: typeof parsed.message === "string" ? parsed.message : void 0
+    };
+  } catch {
+    return {};
+  }
+}
 var OpenSandboxRuntimeService = class {
   constructor() {
     this.cache = /* @__PURE__ */ new Map();
@@ -166,7 +197,10 @@ var OpenSandboxRuntimeService = class {
     const sandbox = await Sandbox.create({
       connectionConfig: this.connectionConfig,
       image: input.image ?? this.defaultImage,
-      timeoutSeconds: this.defaultTimeout,
+      // `null` means no expiry; `undefined` falls back to the service default.
+      // Parity with microsandbox: lifecycle is governed by the server TTL here
+      // (there is no local idle sweeper), so `null` already means "never expire".
+      timeoutSeconds: input.timeoutSeconds === null ? null : input.timeoutSeconds ?? this.defaultTimeout,
       readyTimeoutSeconds: 1800,
       resource: {
         cpu: String(input.cpus ?? this.defaultCpus),
@@ -175,7 +209,7 @@ var OpenSandboxRuntimeService = class {
       env: input.env ?? {},
       metadata: { [NAME_METADATA_KEY]: name },
       volumes: this.mapVolumes(input.volumes),
-      entrypoint: ["tail", "-f", "/dev/null"]
+      entrypoint: input.entrypoint ?? ["tail", "-f", "/dev/null"]
     });
     const info = await sandbox.getInfo();
     const entry = {
@@ -190,10 +224,12 @@ var OpenSandboxRuntimeService = class {
   wrapError(err, code, message) {
     if (err instanceof HttpError) throw err;
     if (err instanceof SandboxException) {
+      const upstream = err instanceof SandboxApiException ? parseUpstreamError(err.rawBody) : {};
+      const status = err instanceof SandboxApiException && isHttpStatus(err.statusCode) ? err.statusCode : mapSandboxErrorCodeToStatus(upstream.code ?? err.error.code);
       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
+        status,
+        upstream.code ?? err.error.code,
+        upstream.message ?? err.error.message ?? message
       );
     }
     throw new HttpError(500, code, message);
@@ -268,6 +304,64 @@ var OpenSandboxRuntimeService = class {
     }
     return { name, status: "unknown" };
   }
+  /**
+   * Resolve the relative proxy path for a guest port.
+   *
+   * The returned path is content-addressed to this service (never the sandbox
+   * host) so callers compose `${MICROSANDBOX_SERVICE_BASE_URL}${endpoint}` exactly
+   * like the microsandbox-service contract. The sandbox must exist, but the
+   * guest port is resolved on demand by {@link resolveProxyTarget}.
+   *
+   * @param name - Sandbox name
+   * @param port - Guest port
+   * @returns The relative proxy path
+   * @throws {HttpError} 404 `SANDBOX_NOT_FOUND` when the sandbox does not exist
+   */
+  async getEndpoint(name, port) {
+    await this.resolveEntry(name);
+    return { endpoint: `/api/sandboxes/${encodeURIComponent(name)}/proxy/${port}` };
+  }
+  /**
+   * Resolve the absolute upstream URL the sandbox proxy dials for a guest port.
+   *
+   * The SDK endpoint is scheme-less (e.g. `localhost:44772`); a missing scheme
+   * is prefixed with `http://`, while an already-absolute endpoint is preserved.
+   * Endpoint-specific headers returned by the SDK are surfaced so the proxy can
+   * forward them upstream.
+   *
+   * @param name - Sandbox name
+   * @param port - Guest port
+   * @returns The absolute upstream target and any required headers
+   * @throws {HttpError} 404 `SANDBOX_NOT_FOUND` when the sandbox does not exist
+   */
+  async resolveProxyTarget(name, port) {
+    const entry = await this.resolveEntry(name);
+    try {
+      const endpoint = await entry.sandbox.getEndpoint(port);
+      const target = endpoint.endpoint.includes("://") ? endpoint.endpoint : `http://${endpoint.endpoint}`;
+      return { target, headers: endpoint.headers };
+    } catch (err) {
+      throw this.wrapError(
+        err,
+        "ENDPOINT_NOT_FOUND",
+        `Endpoint for port ${port} not found on '${name}'`
+      );
+    }
+  }
+  /**
+   * Resolve a cached sandbox entry, recovering it from server metadata when the
+   * local cache is cold.
+   *
+   * @param name - Sandbox name
+   * @throws {HttpError} 404 `SANDBOX_NOT_FOUND` when no sandbox matches the name
+   */
+  async resolveEntry(name) {
+    const entry = this.cache.get(name) ?? await this.findByNameViaMetadata(name);
+    if (!entry) {
+      throw new HttpError(404, "SANDBOX_NOT_FOUND", `Sandbox '${name}' not found`);
+    }
+    return entry;
+  }
   resolvePath(path3) {
     if (path3 === "~" || path3 === "~/") return "/";
     if (path3.startsWith("~/")) return `/${path3.slice(2)}`;
@@ -575,6 +669,9 @@ function registerImageRoutes(app, imageService) {
   app.delete("/api/images/detail", controller.deleteImage);
 }
 
+// src/routes/sandbox.ts
+import { Transform } from "stream";
+
 // src/schemas/sandbox.ts
 import z2 from "zod";
 var bindMountSchema = z2.object({
@@ -601,7 +698,17 @@ var ensureSandboxSchema = z2.object({
   cpus: z2.number().int().positive().optional(),
   memoryMib: z2.number().int().positive().optional(),
   env: z2.record(z2.string()).optional(),
-  volumes: z2.record(volumeSchema).optional()
+  volumes: z2.record(volumeSchema).optional(),
+  /** Main process command; replaces the default `tail -f /dev/null`. */
+  entrypoint: z2.array(z2.string().min(1)).nonempty().optional(),
+  /** Absolute lifetime in seconds; `null` means no expiry. */
+  timeoutSeconds: z2.number().int().positive().nullable().optional(),
+  /** Guest ports to publish (resolved on demand by the server proxy). */
+  exposePorts: z2.array(z2.number().int().positive().max(65535)).optional()
+});
+var sandboxEndpointParamsSchema = z2.object({
+  name: z2.string().min(1),
+  port: z2.coerce.number().int().positive().max(65535)
 });
 var sandboxNameParamsSchema = z2.object({
   name: z2.string().min(1)
@@ -652,6 +759,90 @@ var sandboxLogsSchema = z2.object({
   sources: z2.array(z2.string()).optional()
 });
 
+// src/lib/proxy.ts
+import http from "http";
+var HOP_BY_HOP_HEADERS = /* @__PURE__ */ new Set([
+  "connection",
+  "keep-alive",
+  "proxy-authenticate",
+  "proxy-authorization",
+  "te",
+  "trailer",
+  "transfer-encoding",
+  "upgrade"
+]);
+function isHopByHop(header) {
+  return HOP_BY_HOP_HEADERS.has(header) || header.startsWith("proxy-");
+}
+function buildProxyHeaders(incoming, requestPath) {
+  void requestPath;
+  const headers = {};
+  for (const [rawKey, rawValue] of Object.entries(incoming)) {
+    if (rawValue === void 0) continue;
+    const key = rawKey.toLowerCase();
+    if (isHopByHop(key)) continue;
+    if (key === "host" || key === "content-length") continue;
+    if (key === "authorization") continue;
+    headers[key] = Array.isArray(rawValue) ? rawValue.join(", ") : rawValue;
+  }
+  return headers;
+}
+function parseTarget(target) {
+  const url = new URL(target.includes("://") ? target : `http://${target}`);
+  const basePath = url.pathname === "/" ? "" : url.pathname.replace(/\/$/, "");
+  return {
+    hostname: url.hostname,
+    port: url.port.length > 0 ? Number(url.port) : url.protocol === "https:" ? 443 : 80,
+    basePath
+  };
+}
+function toProxyError(error) {
+  if (error instanceof HttpError) return error;
+  const message = error instanceof Error ? error.message : String(error);
+  return new HttpError(502, "PROXY_ERROR", message);
+}
+function filterResponseHeaders(headers) {
+  const filtered = {};
+  for (const [rawKey, rawValue] of Object.entries(headers)) {
+    if (rawValue === void 0) continue;
+    const key = rawKey.toLowerCase();
+    if (isHopByHop(key)) continue;
+    filtered[key] = rawValue;
+  }
+  return filtered;
+}
+function pipeRequestUpstream(options) {
+  const { target, method, path: path3, headers, body, reply } = options;
+  const { hostname, port, basePath } = parseTarget(target);
+  return new Promise((resolve, reject) => {
+    const upstream = http.request(
+      { hostname, port, method, path: `${basePath}${path3}`, headers },
+      (upstreamResponse) => {
+        try {
+          reply.code(upstreamResponse.statusCode ?? 502);
+          reply.headers(filterResponseHeaders(upstreamResponse.headers));
+          reply.send(upstreamResponse);
+          resolve();
+        } catch (error) {
+          upstreamResponse.destroy();
+          reject(toProxyError(error));
+        }
+      }
+    );
+    upstream.on("error", (error) => reject(toProxyError(error)));
+    body.on("error", (error) => {
+      upstream.destroy();
+      reject(toProxyError(error));
+    });
+    const source = body;
+    if (source.readableEnded === true || source.destroyed === true) {
+      upstream.end();
+    } else {
+      body.pipe(upstream);
+    }
+  });
+}
+
 // src/controllers/sandbox.ts
 function createSandboxController(runtimeService) {
   return {
@@ -687,6 +878,48 @@ function createSandboxController(runtimeService) {
     getStatus: async (request, reply) => {
       return reply.send(ok(await runtimeService.getStatus(request.params.name)));
     },
+    getEndpoint: async (request, reply) => {
+      const parsed = sandboxEndpointParamsSchema.safeParse(request.params ?? {});
+      if (!parsed.success) {
+        throw new HttpError(400, "INVALID_REQUEST", parsed.error.message);
+      }
+      return reply.send(ok(await runtimeService.getEndpoint(parsed.data.name, parsed.data.port)));
+    },
+    /**
+     * Stream a request through to a sandbox's guest port.
+     *
+     * The caller authenticates to this service with its `Authorization` header;
+     * {@link buildProxyHeaders} strips that service key so it is not forwarded
+     * to the (unauthenticated) sandbox host. Endpoint headers returned by the
+     * SDK are merged on top so routing/credential headers reach the sandbox.
+     * The live request stream (body-limited by the scoped parser, or the raw
+     * request for bodyless methods) is piped upstream without buffering.
+     *
+     * @throws {HttpError} 404 `SANDBOX_NOT_FOUND` when the sandbox does not exist,
+     *   or 413 `PAYLOAD_TOO_LARGE` when the streaming body exceeds `bodyLimit`.
+     */
+    proxyRequest: async (request, reply) => {
+      const { name, port } = request.params;
+      const rest = request.params["*"] ?? "";
+      const resolved = await runtimeService.resolveProxyTarget(name, Number(port));
+      const path3 = `/${rest}`;
+      const headers = {
+        ...buildProxyHeaders(
+          request.headers,
+          path3
+        ),
+        ...resolved.headers ?? {}
+      };
+      const body = request.body ?? request.raw;
+      await pipeRequestUpstream({
+        target: resolved.target,
+        method: request.method,
+        path: path3,
+        headers,
+        body,
+        reply
+      });
+    },
     getSandboxLogs: async (request, reply) => {
       const body = sandboxLogsSchema.parse(request.body ?? {});
       return reply.send(ok(await runtimeService.getSandboxLogs(request.params.name, body)));
@@ -750,6 +983,7 @@ function registerSandboxRoutes(app, runtimeService) {
   app.post("/api/sandboxes/:name/kill", controller.killSandbox);
   app.delete("/api/sandboxes/:name", controller.deleteSandbox);
   app.get("/api/sandboxes/:name/status", controller.getStatus);
+  app.get("/api/sandboxes/:name/endpoints/:port", controller.getEndpoint);
   app.post("/api/sandboxes/:name/logs", controller.getSandboxLogs);
   app.post("/api/files/read", controller.readFile);
   app.post("/api/files/write", controller.writeFile);
@@ -760,6 +994,26 @@ function registerSandboxRoutes(app, runtimeService) {
   app.post("/api/files/upload", controller.uploadFile);
   app.get("/api/files/download", controller.downloadFile);
   app.post("/api/shell/exec", controller.execCommand);
+  app.register(async (instance) => {
+    const bodyLimit = instance.initialConfig.bodyLimit ?? 100 * 1024 * 1024;
+    instance.removeAllContentTypeParsers();
+    instance.addContentTypeParser("*", (_request, payload, done) => {
+      let received = 0;
+      const limiter = new Transform({
+        transform(chunk, _encoding, callback) {
+          received += chunk.length;
+          if (received > bodyLimit) {
+            callback(new HttpError(413, "PAYLOAD_TOO_LARGE", "Request body is too large"));
+            return;
+          }
+          callback(null, chunk);
+        }
+      });
+      payload.pipe(limiter);
+      done(null, limiter);
+    });
+    instance.all("/api/sandboxes/:name/proxy/:port/*", controller.proxyRequest);
+  });
 }
 
 // src/controllers/volume-fs.ts
@@ -986,9 +1240,9 @@ async function configureSwagger(app) {
 
 // src/app.ts
 async function buildApp({
+  runtimeService = new OpenSandboxRuntimeService(),
   apiKey
 } = {}) {
-  const runtimeService = new OpenSandboxRuntimeService();
   const imageService = new ImageService();
   const app = fastify({
     logger: false,
@@ -1123,4 +1377,4 @@ export {
   buildApp,
   startServer
 };
-//# sourceMappingURL=chunk-M6FKTT7J.mjs.map
+//# sourceMappingURL=chunk-QC7CI5UY.mjs.map