@solarisdk/runloop-compat 0.0.0-stage → 0.1.0

package/COMPAT.md

@@ -0,0 +1,110 @@
+# COMPAT.md: Runloop SDK compatibility, TypeScript (target: @runloop/api-client 2.0.0)
+
+Mirrors `sdk/python-runloop-compat/COMPAT.md` (same mapping rules, see `src/mapping.ts` vs `solari_runloop/_mapping.py`).
+Legend: **OK** works and is tested live on staging; **DIFF** works with a behaviour difference; **GATEWAY** waits on a gateway
+endpoint; **NO** throws `SolariCompatUnsupported`.
+
+## Setup
+| Runloop | Here |
+|---|---|
+| `new Runloop({ bearerToken })`, `new RunloopSDK(...)`, env `RUNLOOP_API_KEY` | OK. Order: option (`bearerToken`/`apiKey`), `SOLARI_API_KEY`, `RUNLOOP_API_KEY`. **Only `slr_…` keys are used**: a non-`slr_` candidate (such as a real Runloop key in `RUNLOOP_API_KEY`) is skipped with a warning and never sent anywhere; if no Solari key is left the constructor throws. |
+| `baseURL`, env `RUNLOOP_BASE_URL` | OK. Order: option, `SOLARI_BASE_URL`, `RUNLOOP_BASE_URL`, default `https://api.getsolari.com`. `RUNLOOP_BASE_URL` is only used when it is `https://getsolari.com` or a subdomain, or a loopback address (`localhost`, `127.x.x.x`, `[::1]`); otherwise it is ignored with a warning, so the `slr_` key is never sent to Runloop (`https://api.runloop.ai`) or a lookalike host. The option and `SOLARI_BASE_URL` are used as given. |
+| `timeout`, `fetch` | OK (`timeout` is the control-channel call timeout). |
+| `maxRetries` | Accepted; Solari's own retry policy applies. |
+| `defaultHeaders`, `defaultQuery`, `httpAgent` | NO when non-empty. |
+
+## Object layer (`RunloopSDK`)
+| Call | Status | Notes |
+|---|---|---|
+| `devbox.create(params)` | OK | Waits for `running`. Parameters: see below. |
+| `devbox.createFromSnapshot(id)`, `snapshot.createDevbox()` | OK | `fromSnapshot`. |
+| `devbox.createFromBlueprintName(name)`, `createFromBlueprintId(id)`, `blueprint.createDevbox()` | OK, live | A Solari template: a built-in name (`base`) or a blueprint built with `blueprint.create`. Custom names resolve to the newest matching `tpl_` id. |
+| `devbox.fromId`, `devbox.list` | OK | `list` returns `Devbox[]` of the first page. |
+| `getInfo`, `awaitRunning`, `awaitSuspended`, `shutdown`, `suspend`, `resume`, `resumeAsync`, `keepAlive` | OK | `suspend`/`resume` = Solari pause/resume (RAM+disk). `keepAlive` re-arms the idle window the devbox was created with (default 30 min). `resume` waits for a stable `running` (the gateway view can flap for ~1 s). |
+| `cmd.exec(cmd, { stdout, stderr, output })` | OK | Runs `bash -lc "<cmd>"` from `$HOME` (created if missing). Callbacks get lines. Output is never truncated. |
+| `cmd.execAsync(...)` → `Execution` | DIFF | `result()`, `getState()`, `kill()`, `sendStdIn()` work **inside the creating process** (in-memory registry). From another process: GATEWAY (durable executions). `closeStdIn` NO. |
+| `shell(name)`, `shell_name` | GATEWAY | named persistent shells; throws until then. |
+| `file.read / write / upload / download` | OK | Relative paths resolve against `$HOME`; parent dirs are created on write/upload. `upload({file})` takes a `Blob`/`File`, `Response`, bytes or string. `download` returns a `Response`. |
+| `snapshotDisk(...)`, `snapshotDiskAsync(...)` | DIFF | Synchronous; returns a `Snapshot`. RAM+disk. `commit_message`/`metadata` are echoed on the return value, not stored (GATEWAY). |
+| `snapshot.getInfo / delete / awaitCompleted / queryStatus`, `snapshot.list`, `snapshot.fromId` | OK | `delete` returns when the snapshot is really gone: large snapshots are erased incrementally (the gateway answers `202 {status:"deleting"}`), so it repeats the DELETE with backoff up to 5 minutes and then raises an error naming the snapshot instead of claiming success. `snapshot.update({name, commit_message, metadata})`: OK on a gateway with `PATCH /snapshots/{id}` (#566), else unsupported. Deleting a snapshot with live children is a 409 `ConflictError`. |
+| `getTunnel()`, `getTunnelUrl(port)`, `net.enableTunnel()`, `net.removeTunnel()`, create `tunnel: {auth_mode, wake_on_http, http_keep_alive}` | DIFF, live | Solari's tunnel (`/sandboxes/:id/tunnel`, desktop#575): `auth_mode` `authenticated` (Runloop's default; returns `auth_token`, valid on every port for 1 h, sent as `x-solari-preview-token`) or `open`; `wake_on_http` (authenticated only; `open` + `wake_on_http` is refused) and `http_keep_alive` work. URLs are `https://<tunnel_key>-<port>.preview…` (the image of Runloop's `https://{port}-{key}.tunnel…`); `getTunnelUrl(port)` is the per-port preview URL, which carries a signed `slr_token`: treat it as a credential. `removeTunnel` revokes every token. `getTunnel()` is `null` when none is enabled. On a gateway without tunnel routes only `open` works (per-port preview). `net.createSSHKey` NO. |
+| `devbox.logs({execution_id, text})` | DIFF | Uses the gateway's `GET /sandboxes/{id}/logs` when it exists; until then returns the output of commands run through **this client instance** (not durable across processes). |
+| `devbox.update({name, metadata})` | OK on a gateway with `PATCH /sandboxes/{id}` (pinetree-desktop#566), else `SolariCompatUnsupported` | Detected per call: a 404 on the PATCH is re-checked against the devbox so a missing devbox is still `NotFoundError`. |
+| `onEvict`, `cancelOnEvict` | NO | |
+| `blueprint.create({name, dockerfile, system_setup_commands, file_mounts, base_blueprint_name/id, build_args, build_context, launch_parameters})` | DIFF, live | Builds a Solari template from a **Dockerfile subset** and waits for it (deleted again if the build fails). `FROM ubuntu/debian/base/workstation` = the native base; **any other public image** (docker.io, ghcr.io, public.ecr.aws, gcr.io, quay.io) becomes the gateway's native `fromImage` build (blueprint level 3b: desktop#572/#576, needs a golden with the new guest agent). A gateway without native image builds is detected from the 202 reply and the call raises `SolariCompatUnsupported` (the unwanted template is deleted when its build ends). `RUN ENV ARG WORKDIR ENTRYPOINT CMD`, `COPY`/`ADD` (below); not multi-stage, `USER`, `VOLUME`, `HEALTHCHECK`, `ONBUILD`. `code_mounts`, `services`, `secrets`, `network_policy_id` NO. |
+| `blueprint.fromId / list`, `Blueprint.getInfo / logs / delete / createDevbox` | OK, live | `list()` returns your org's custom templates only. Build logs have no timestamps/levels (Solari returns plain lines; stderr is `ERROR`). Status: `building` → `building`, `ready` → `build_complete`, `failed` → `failed`. |
+| `storageObject.uploadFromDir / uploadFromBytes`, `asBuildContext()`, `fromId`, `delete` | DIFF, live | Not real storage objects: a deterministic `.tar.gz` **held by this client** (honours `.dockerignore`, Docker semantics) and embedded in the build recipe in 60 KB chunks, capped at ~700 KB compressed (the template body limit is 1 MiB). `COPY`/`ADD` (incl. `--chown`, `--chmod`, globs, `ADD` of a local tar) copy from it; `COPY --from`, URLs and `../` or absolute sources are refused. **The context ends up inside the build recipe, so it is visible in the template's build record and logs: never put secrets in it.** A context from another process is `SolariCompatUnsupported`. The rest of `storageObject` (create, list, download, mounts) NO until the gateway has objects. |
+| `client.secrets.{create, retrieve, update, list, delete}`; create `secrets: {ENV: name}` | DIFF, live | Solari account secrets (`/secrets`, desktop#583): named, org-scoped, **write-only** (no call returns a value; `retrieve`/`list` give name and times; `id` is the name). `create` on an existing name is `ConflictError`. Injected as env vars at create; deleting or changing a secret never affects a devbox that already received it. Needs a gateway with `ORG_SECRETS_KEY` (otherwise `501`). The `runloop.secret` convenience namespace is NO. |
+| `agent`, `axon`, `networkPolicy`, `gatewayConfig`, `mcpConfig`, `secret` | NO | |
+
+## REST layer (`client.devboxes.*`)
+`create`, `createAndAwaitRunning`, `retrieve`, `list` (auto-iterable page: `for await`), `shutdown`, `suspend`, `resume`,
+`resumeAsync`, `keepAlive`, `awaitRunning`, `awaitSuspended`, `execute`, `executeSync`, `executeAsync`, `executeAndAwaitCompletion`,
+`waitForCommand`, `readFileContents`, `writeFileContents`, `uploadFile`, `downloadFile`, `snapshotDisk`, `snapshotDiskAsync`,
+`listDiskSnapshots`, `deleteDiskSnapshot`, `executions.{retrieve, awaitCompleted, executeAsync, executeSync, kill, sendStdIn}`,
+`diskSnapshots.{list, retrieve, delete}`: OK (same caveats). `update` and `logs` as above; `enableTunnel`, `removeTunnel` OK. `createSSHKey`, `watchEvictions` NO. `client.blueprints` (`create`, `retrieve`, `list`, `delete`, `logs`, `awaitBuildComplete`, `createAndAwaitBuildComplete`): OK (Dockerfile subset). `client.secrets` OK (account secrets). `objects`, `agents`, `axons`, `networkPolicies`,
+`gatewayConfigs`, `mcpConfigs`: every call throws `SolariCompatUnsupported`.
+
+## Create parameters
+| Runloop param | Mapping |
+|---|---|
+| `name` | metadata key `runloop.name` (hidden from `metadata`) |
+| `metadata` / `environment_variables` | `metadata` / `envs` |
+| `blueprint_name` / `snapshot_id` | `template` (custom names resolved to `tpl_` ids) / `fromSnapshot` |
+| `file_mounts` | files written after create |
+| `entrypoint` | started in the background after create |
+| `launch_parameters.launch_commands` | run in order after create; a non-zero exit fails the create (devbox is shut down) |
+| `launch_parameters.keep_alive_time_seconds` | idle window; `lifecycle.onTimeout = "kill"` |
+| `launch_parameters.after_idle` | idle window; `on_idle: "suspend"` → `onTimeout: "pause"`, else `"kill"` |
+| `launch_parameters` sizing | see sizes |
+| `blueprint_id` | a Solari template id |
+| `tunnel: {auth_mode, wake_on_http, http_keep_alive}` | enables the tunnel right after the devbox is up (a failure kills the devbox); see tunnels |
+| `secrets: {ENV: name}` | account secrets injected as env vars (see secrets); a name also in `environment_variables` is refused |
+| `code_mounts`, `mounts`, `gateways`, `mcp`, `network_policy_id`, `user_parameters`, `required_services`, any unknown parameter | NO |
+| `architecture`, `available_ports` | ignored |
+
+### Sizes (James's rule: cap silently, never error)
+CPU rounds **up** to a whole vCPU; capped at Solari's limits (**8 vCPU / 16 GiB**) with a `console.warn`. Disk is sent only when
+`custom_disk_size` is given. No size leaves Solari's defaults. Same table as the Python package:
+
+| `resource_size_request` | Sent to Solari |
+|---|---|
+| `X_SMALL` | 1 vCPU, 1 GiB |
+| `SMALL` | 1 vCPU, 2 GiB |
+| `MEDIUM` | 2 vCPU, 4 GiB |
+| `LARGE` | 2 vCPU, 8 GiB |
+| `X_LARGE` | 4 vCPU, 16 GiB |
+| `XX_LARGE` | 8 vCPU, 16 GiB (capped from 32) |
+| `CUSTOM_SIZE` | ceil(`custom_cpu_cores`) capped at 8; `custom_gb_memory` × 1024 MiB capped at 16384 |
+
+## Status, errors, pagination
+- Status: `starting`→`initializing`, `running`→`running`, `paused`→`suspended`, `archived`→`suspended`, `releasing`→`shutdown`,
+  `gone`→`shutdown`; anything else `failure`. `DevboxView` fields Solari lacks are synthesized (`create_time_ms`, one
+  `state_transitions` entry, `launch_parameters` from the real cpu/mem, `capabilities: []`).
+- Errors: 400 `BadRequestError`, 401 `AuthenticationError`, 402/403 `PermissionDeniedError` (`status` keeps 402), 404 `NotFoundError`,
+  409 `ConflictError`, 422 `UnprocessableEntityError`, 429 `RateLimitError`, 5xx `InternalServerError`; network `APIConnectionError`,
+  timeouts `APITimeoutError`. `.error` is Solari's `{code,error,message,retryable}` body.
+- IDs are Solari's opaque signed strings (`:` and `.` inside), not `dbx_…`. Snapshot ids are `snap_…`.
+- Pagination: `devboxes.list()` returns a page with `.devboxes`, `.has_more`, `.hasNextPage()`, `.getNextPage()`; it is async
+  iterable across pages. `starting_after` is sent as `startingAfter` to a gateway that supports it (#566, detected from `hasMore` in the list reply); on an older one the client scans from the start and skips past the id. `total_count` is the gateway's `totalCount` (with `include_total_count`) when it sends one, else the count so far.
+- Staging quirks handled: GET right after create can 404 (retried); the first control-channel call after a resume can fail
+  (handle dropped, reconnected, retried); a snapshot right after a resume can be `NotRunning` or "Not snapshottable" for up to ~20 s (stale reads on another gateway replica; retried for up to a minute); the snapshot record can 404 briefly. A snapshot takes 25-30 s on staging.
+
+## Runloop's own examples (v2.0.0, import swapped; `test-live/run-runloop-examples.sh`)
+| Example | Result |
+|---|---|
+| `devbox-snapshots` | PASS (suspend, resume, snapshot, two clones, isolation checks, snapshot deleted) |
+| `devbox-from-blueprint-lifecycle` | PASS (Dockerfile blueprint, build logs, devbox logs from this client's record) |
+| `blueprint-with-build-context` | PASS (`COPY . .` from a local directory context) |
+| `devbox-tunnel` | PASS (open tunnel; the HTTP request through Solari's preview URL returns the directory listing) |
+| `devbox-mounts`, `secrets-with-devbox`, `mcp-github-tools` | not run: object mounts / the secret store / MCP are not supported |
+They clean up after themselves; the script lists what is left on the account afterwards.
+
+## Test status
+- `test/blueprints.test.mjs`: offline: the Dockerfile compiler (including `FROM <image>` → native `fromImage`, chunked build contexts, COPY/ADD shapes), build contexts (deterministic tar.gz validated with `tar`, `.dockerignore`, long paths, size cap), blueprints against a fake gateway (create/await/delete-on-failure, name resolution, image-build detection), `update` / `logs` / `startingAfter` feature detection.
+- `test/compat.test.mjs`: offline (fake gateway): exports, auth/base-URL order, status map, sizes, create translation, errors,
+  pagination, unsupported calls.
+- `test-live/staging.test.mjs`: full lifecycle on staging (create, exec, files, async exec streaming, snapshot, create from snapshot,
+  keep-alive, list, suspend/resume, shutdown). `test-live/readme.test.mjs`: Runloop's TS README snippets with the import swapped
+  (quickstart, snapshot workflow, file write helpers, error handling, config); the README's `devbox.logs()`, blueprints and secrets
+  snippets assert the loud `SolariCompatUnsupported`.

package/LICENSE

@@ -0,0 +1,17 @@
+                                 Apache License
+                           Version 2.0, January 2004
+                        http://www.apache.org/licenses/
+
+   Copyright 2026 Solari Desktop
+
+   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.

package/LICENSE-RUNLOOP

@@ -0,0 +1,7 @@
+Copyright 2026 runloop
+
+Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

package/NOTICE

@@ -0,0 +1,14 @@
+@solarisdk/runloop-compat
+
+Parts of this package are derived from @runloop/api-client 2.0.0
+(https://github.com/runloopai/api-client-ts), which is distributed under the MIT
+licence:
+
+  Copyright 2026 runloop
+
+The licence text is reproduced in LICENSE-RUNLOOP. The derived files are
+src/types.ts, src/shared-types.ts and src/blueprint-types.ts (type definitions). Their headers say so.
+
+This package is not affiliated with, endorsed by, or sponsored by Runloop.
+"Runloop" and "Devbox" are names of Runloop's products; they appear here only to
+describe API compatibility.

package/README.md

@@ -1,3 +1,47 @@
-# Temporary Holding Version
+# @solarisdk/runloop-compat
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+A Runloop-compatible API on top of [Solari Sandbox](https://getsolari.com). Change the import, keep your devbox code.
+
+> **Not affiliated with, endorsed by, or sponsored by Runloop.** "Runloop" and "Devbox" are Runloop's product names; they
+> appear here only to describe API compatibility. Type definitions are derived from `@runloop/api-client` 2.0.0 (MIT), see
+> [NOTICE](./NOTICE). Do not look for this package under `@runloop/*`.
+
+```ts
+// before: import { RunloopSDK } from '@runloop/api-client';
+import { RunloopSDK } from '@solarisdk/runloop-compat';
+
+const sdk = new RunloopSDK({ bearerToken: process.env.SOLARI_API_KEY });
+const devbox = await sdk.devbox.create();
+const result = await devbox.cmd.exec('echo "Hello, World!"');
+console.log(await result.stdout(), result.exitCode);
+await devbox.shutdown();
+```
+
+Exports: `Runloop` (default and named; the REST layer, `client.devboxes.*`), `RunloopSDK` (the object layer), `Devbox`,
+`Snapshot`, `Execution`, `ExecutionResult`, the Runloop error classes (`RunloopError`, `APIError`, `BadRequestError`,
+`AuthenticationError`, `PermissionDeniedError`, `NotFoundError`, `ConflictError`, `UnprocessableEntityError`,
+`RateLimitError`, `InternalServerError`, `APIConnectionError`, `APITimeoutError`), `SolariCompatUnsupported`, and the types.
+
+## Configuration
+
+| | Order |
+|---|---|
+| API key | `bearerToken` / `apiKey` option, `SOLARI_API_KEY`, `RUNLOOP_API_KEY`: only an `slr_…` Solari key is ever used. A non-`slr_` value (for example a real Runloop key) is skipped with a warning (the key is never printed or sent); with no Solari key the constructor throws |
+| Base URL | `baseURL` option, `SOLARI_BASE_URL`, `RUNLOOP_BASE_URL` (only if it points at getsolari.com or loopback; otherwise ignored with a warning), default `https://api.getsolari.com` |
+
+A Runloop key does not work here: use a Solari API key.
+
+## What works, what does not
+
+[COMPAT.md](./COMPAT.md) is the support matrix. Anything Solari cannot do raises `SolariCompatUnsupported`
+(an `APIError`) naming the feature; nothing is silently ignored. The sibling Python package is
+`sdk/python-runloop-compat` and shares the same mapping rules.
+
+## Tests
+
+```sh
+npm test                                   # offline unit tests (a fake gateway)
+SOLARI_API_KEY=… SOLARI_BASE_URL=https://api-sta.getsolari.com node --test test-live/*.test.mjs   # staging; deletes what it creates
+```
+
+`test-live/readme.test.mjs` runs Runloop's own TypeScript README snippets with only the import swapped.