@axiom-lattice/microsandbox-service 0.1.11 → 1.0.0

package/CHANGELOG.md

@@ -1,5 +1,67 @@
 # @axiom-lattice/microsandbox-service
 
+## 1.0.0
+
+### Major Changes
+
+- 726c98a: Consolidated release notes for all pending changesets. Each package takes the highest bump type among the merged entries.
+
+  ## Sandbox shell-exec timeout unified on milliseconds (ADR-178, breaking)
+
+  Unify the sandbox shell-exec timeout on **milliseconds** across the framework.
+
+  Breaking changes:
+
+  - `SandboxShellService.execCommand` now takes `timeoutMs` (milliseconds) instead of `timeout` (seconds). Custom `SandboxInstance` implementations must rename the field and adjust units.
+  - `MicrosandboxShellExecInput.timeout` → `timeoutMs`; the `POST /api/shell/exec` wire field is now `timeoutMs` for both `microsandbox-service` and `opensandbox-gateway`.
+  - `PACK_DIRECTORY_TIMEOUT_SECONDS` → `PACK_DIRECTORY_TIMEOUT_MS` (public core export via `sandbox_lattice`).
+  - `sandbox-console` `SandboxExecInput.timeout` → `timeoutMs`.
+
+  Behavior:
+
+  - Provider adapters convert once at their boundary: Daytona / agent-infra (`remote`) / OpenSandbox convert ms→seconds; E2B and Local pass milliseconds directly.
+  - **Fix:** `opensandbox-gateway` no longer divides an already-seconds value by 1000 (which capped every command at 1s); it now converts `timeoutMs` → the SDK's `timeoutSeconds` (floored to at least 1s).
+  - **Fix:** `microsandbox-service` now honors the timeout by streaming the shell and killing it on expiry; previously `timeout` was accepted but ignored.
+  - LLM-facing tools `shell_exec` (`timeout`, seconds) and `code_eval` (`timeout_sec`, seconds) intentionally keep seconds and convert once; documented as exceptions.
+  - Sandbox lifetime `timeoutSeconds` (create/renew/idle) is unchanged and remains in seconds.
+
+  ## Sandbox service base URL + missing-file semantics (ADR-174 / ADR-175)
+
+  Unify the sandbox service base-URL env and treat missing sandbox files as a structured not-found.
+
+  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`.
+
+  ## Sandbox plugin result contract (ADR-177)
+
+  - `invokePluginTool` no longer returns `undefined` when a sandbox plugin handler reports `ok:true` without a `result` field. That `undefined` made the MCP App `tools/call` route (`/api/mcp-apps/rpc`) send an empty body (client `Response.json()` threw "Unexpected end of JSON input"). It now falls back to the handler's raw stdout via core's new `handlerResultText`; handlers that supply `result` are unchanged. `handlerResultText` is exported from `@axiom-lattice/core`.
+  - Sandbox plugin tool results no longer collapse to the string `"null"` when a handler reports `ok:true` but omits the `result` field. The normalized text now falls back to the handler's raw stdout via the new `handlerResultText` helper (used by `SandboxPluginCompiler`), and `manage_plugin test` returns that same normalized text so authors catch the missing `result` wrapper instead of seeing the raw envelope in `stdout` while the inline result is `"null"`.
+  - The sandbox plugin authoring skills now show an explicit ✅/❌ for the required `result` wrapper (payload must go under `result`, not the envelope top level), and the UI skill states that `ui/notifications/tool-result` is a `CallToolResult` read via `params.content[0].text` rather than the handler payload at the top level.
+
+  ## Plugin Builder skills
+
+  - Plugin Builder's `skill` middleware now uses `readAll: true` instead of a sandbox-plugin-only whitelist, so built-in skills (e.g. `ptc`) are actually loadable rather than merely advertised in `<available_skills>` (loading them previously returned `RESOURCE_NOT_ALLOWED`).
+  - Close three Plugin Builder capability gaps: add `sandbox-plugins-consume-open` (how a handler calls the platform's Open MCP surface via the injected `API_GATEWAY_URL`/`OPEN_API_TOKEN` + `listTools()`/`callTool()`), add a "Scenarios → skills" routing table to `sandbox-plugins-patterns`, and document in `sandbox-plugins-ui` that a View `tools/call` response is the handler's `result` value directly (not a `CallToolResult` wrapper) plus a self-check/debug section. The Plugin Builder prompt now routes to the new skill.
+
+  ## MCP App UI push semantics
+
+  Document the MCP App push semantics in `sandbox-plugins-ui`: `ui/notifications/tool-result` replays the tool result **recorded when the agent ran** (it does not re-execute the handler), whereas a View `tools/call` re-executes the handler live. This is why a stale/`"null"` push can coexist with a correct `tools/call` — re-run the tool for a fresh push instead of debugging the host.
+
+  ## MCP App same-origin rendering
+
+  `McpAppRenderer` no longer refuses to render when the gateway shares the console origin. Single-origin deployments previously saw "MCP App unavailable" because the outer sandbox proxy iframe (which carries `allow-same-origin`) was required to be cross-origin per the MCP Apps spec. The renderer now only requires that a gateway origin can be derived from `client.config.baseURL`; `event.origin`/`event.source` validation is unchanged, and the untrusted View still runs in an opaque-origin inner frame. Cross-origin deployments keep the stronger containment and are unchanged; the trade-off is documented in ADR-117.
+
+## 0.1.12
+
+### 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.1.11
 
 ### Patch Changes

package/README.md

@@ -54,6 +54,9 @@ Supported environment variables:
 - `MICROSANDBOX_IDLE_TIMEOUT_SEC` default: `600` — auto-stop after N seconds of inactivity. Set to `0` to disable
 - `MICROSANDBOX_VOLUME_QUOTA_MIB` default: `2048` — storage quota for named volumes
 - `MICROSANDBOX_CLI_PATH` default: `~/.microsandbox/bin/msb` — path to the `msb` binary
+- `MICROSANDBOX_API_KEY` — when set, every `/api/*` request must send `Authorization: Bearer <key>` (`/health` stays open)
+- `MICROSANDBOX_HOST_PORT_MIN` default: `40000` — lowest host port used when publishing guest ports
+- `MICROSANDBOX_HOST_PORT_MAX` default: `60000` — highest host port used when publishing guest ports
 
 Example:
 
@@ -132,6 +135,73 @@ pnpm --filter @axiom-lattice/microsandbox-service dev
 
 This command watches source files, rebuilds the package, and restarts the service automatically.
 
+## HTTP API
+
+Every response uses a JSON envelope: success is `{ "success": true, "data": ... }`, failure is
+`{ "success": false, "error": { "code": "...", "message": "..." } }`. When `MICROSANDBOX_API_KEY`
+is set, all `/api/*` requests require `Authorization: Bearer <key>` (`/health` stays open).
+
+### Sandbox lifecycle
+
+| Method | Path | Purpose |
+|--------|------|---------|
+| `GET` | `/api/sandboxes` | List sandboxes |
+| `GET` | `/api/sandboxes/:name` | Inspect one sandbox |
+| `PUT` | `/api/sandboxes/:name` | Create-or-reuse (`ensure`) |
+| `POST` | `/api/sandboxes/:name/start` | Start / resume |
+| `POST` | `/api/sandboxes/:name/stop` | Pause |
+| `POST` | `/api/sandboxes/:name/kill` | Kill |
+| `DELETE` | `/api/sandboxes/:name` | Delete |
+| `GET` | `/api/sandboxes/:name/status` | Status |
+| `POST` | `/api/sandboxes/:name/logs` | Logs |
+| `GET` | `/api/sandboxes/:name/endpoints/:port` | Resolve a published guest port |
+| `ANY` | `/api/sandboxes/:name/proxy/:port/*` | Stream to a published guest port |
+
+File/shell operations are under `/api/files/*` and `/api/shell/exec`; image and named-volume
+operations under `/api/images/*` and `/api/volumes/:name/fs/*`.
+
+### Resident-service primitives
+
+`PUT /api/sandboxes/:name` accepts three optional fields beyond image/resource/volume config:
+
+| Field | Type | Meaning |
+|-------|------|---------|
+| `entrypoint` | `string[]` | Main process command; replaces the default `tail -f /dev/null`. Use this to run a long-lived service (e.g. a plugin host daemon). |
+| `timeoutSeconds` | `number` \| `null` | Sandbox lifetime. `null` means no expiry. **Currently inert** in the registry — positive values are not yet applied and changes do not force a recreate (scheduled for Plan 3). |
+| `exposePorts` | `number[]` | Guest ports to publish. Each is mapped to a deterministic host port within `[MICROSANDBOX_HOST_PORT_MIN, MICROSANDBOX_HOST_PORT_MAX]`. |
+
+Create a resident service and resolve its endpoint:
+
+```bash
+curl -X PUT http://127.0.0.1:4002/api/sandboxes/plugin-weather \
+  -H 'content-type: application/json' \
+  -d '{
+    "image": "kioko12520/sandbox:0.1.0",
+    "entrypoint": ["node", "/root/.agents/.plugin-host/server.js"],
+    "exposePorts": [8080]
+  }'
+
+curl http://127.0.0.1:4002/api/sandboxes/plugin-weather/endpoints/8080
+# { "success": true, "data": { "endpoint": "/api/sandboxes/plugin-weather/proxy/8080" } }
+```
+
+`GET /api/sandboxes/:name/endpoints/:port` responses:
+
+- `200` — `{ "success": true, "data": { "endpoint": "/api/sandboxes/<name>/proxy/<port>" } }`
+  (a relative proxy path the caller composes with its configured service base URL; may also
+  include `headers` for proxied backends)
+- `400 INVALID_REQUEST` — `:port` is not an integer in `1..65535`
+- `404 ENDPOINT_NOT_PUBLISHED` — the port was not published for this sandbox
+
+The guest→host mapping is recovered from the sandbox's persisted config, so it survives service
+restarts. The loopback mapping stays internal; the returned path points at the proxy route below.
+
+`ANY /api/sandboxes/:name/proxy/:port/*` streams the request to the sandbox's published guest
+port (any method, unbuffered, so SSE and large payloads pass through). Authenticate to this
+service with `Authorization: Bearer <MICROSANDBOX_API_KEY>`; the proxy **strips** that header
+before forwarding, so the service key never reaches the (unauthenticated) sandbox host behind
+the loopback-bound port.
+
 ## Operational Notes
 
 - Invalid startup configuration exits non-zero.