@agent-relay/sandbox 0.1.2 → 0.1.5

package/README.md

@@ -10,10 +10,8 @@ run commands, stream results back, and tear it down.
 The point of the port is that the orchestration layer holds no provider
 knowledge. Swapping providers is a change of adapter, not a change of caller.
 
-> **Status: pre-release scaffold.** This repository currently contains the
-> package skeleton — build, typecheck, test, and release wiring. The runtime
-> adapters and orchestrator land in subsequent changes, and the public API is
-> not stable until a `1.0.0` release.
+> **Status: pre-1.0.** The public API may still change before a `1.0.0`
+> release.
 
 ## Install
 
@@ -23,6 +21,68 @@ npm install @agent-relay/sandbox
 
 Provider SDKs are peer dependencies: install the one you intend to use. A
 consumer that only runs local sandboxes does not need a remote provider SDK.
+Adapters for providers that publish no JavaScript SDK speak their HTTP API
+directly and add no dependency at all; they take an injectable `fetch` instead.
+
+Import provider-neutral APIs and the selected adapter from separate entrypoints:
+
+```ts
+import { SandboxOrchestrator } from "@agent-relay/sandbox/core";
+import { DaytonaRuntime } from "@agent-relay/sandbox/daytona";
+```
+
+The provider entrypoints are `agent37`, `agentcore`, `daytona`, `e2b`,
+`freestyle`, `local`, `microsandbox`, `modal`, and `vercel`. Each points at its
+own barrel, so a bundler does not have to resolve the other optional provider SDKs.
+The root `@agent-relay/sandbox` barrel still exports the complete historical
+surface for compatibility, but new runtime imports should use `core` plus one
+provider subpath.
+
+The export map uses `./* -> ./dist/*/index.js` rather than enumerating today’s
+providers. To add another provider safely, add `src/<provider>/index.ts` as its
+isolated public barrel and declare its SDK as an optional peer. The package
+contract test requires every runtime directory (and every optional peer owner)
+to have such a barrel, and the packed-package smoke test verifies those barrels
+ship and import without installing any optional peers.
+
+### Provider constraints
+
+Each adapter inherits its provider SDK's requirements, and they are not all the
+same as this package's:
+
+| Adapter | Peer dependency | Requirements beyond this package's |
+| --- | --- | --- |
+| `DaytonaRuntime` | `@daytonaio/sdk` 0.180–0.205 | — |
+| `E2BSandboxRuntime` | `e2b` | — |
+| `MicrosandboxRuntime` | `microsandbox` | **Node.js 22+**, a platform-specific native addon (macOS arm64, Linux x64/arm64, Windows x64/arm64), and — for its `local` backend — hardware virtualization: KVM on Linux, Apple Silicon on macOS, or WHP on Windows 10+ |
+| `LocalSandboxRuntime` | — | A reachable local sandbox service |
+
+The package itself keeps a Node 20 floor, because a consumer that never touches
+the microsandbox adapter never loads that SDK: it is imported lazily, at first
+use, and a load failure is reported with the constraint that most often
+explains it.
+
+### Microsandbox capabilities are backend-sensitive
+
+`MicrosandboxRuntime.capabilities` is derived from the backend the instance is
+bound to, not reported as a single process-wide constant:
+
+| Capability | `local` | `cloud` | Why |
+| --- | --- | --- | --- |
+| `snapshots` | `true` | `false` | A snapshot is a host-local artifact: the installed SDK's typings describe `Snapshot` as an artifact on disk and resolve one under `~/.microsandbox/snapshots/<name>/`. This adapter consumes such an artifact from the calling host and never transfers it, so a create issued against a remote backend has nothing to resolve. Configuring `snapshot` with a cloud backend is refused in the constructor, before any SDK call. |
+| `isolation` | `'strong'` | `'unknown'` | Locally the SDK boots a microVM with its own guest kernel on a virtualization-capable host, and the installed package states that requirement itself, so `'strong'` rests on something checkable here. This adapter observes and measures nothing about the cloud backend's isolation. |
+
+Both values describe what this package has **established**, not what any
+provider documents. `'unknown'` is not a synonym for weak and is not a claim
+that the guarantee is missing — it means this package has not established one,
+so a caller that requires a specific guarantee must decide for itself rather
+than read an unverified `'strong'`.
+
+Cloud region placement and resource enforcement are likewise not represented as
+measured facts. Custom or published **ports are not supported**: the SDK builder
+exposes `port()`/`portBind()`, but the ports this package targets have no
+public-port surface, so the adapter never calls them and never implies a
+reachable port.
 
 ## Design
 
@@ -40,6 +100,187 @@ is a required argument supplied by the caller. This keeps the package usable
 outside the environment it was extracted from, and keeps credential handling in
 the caller where it belongs.
 
+Each adapter also declares what it genuinely supports rather than what its
+method names imply. `resolveSandboxRuntimeCapabilities` reads that declaration,
+so a caller learns up front whether a provider can reattach to a sandbox by id,
+poll a background command, hand back a still-booting sandbox, or search by
+label — instead of discovering the answer from a failure at run time.
+
+### Daytona restart recovery
+
+`DaytonaRuntime.start()` does not trust the provider state transition alone. It
+rehydrates the SDK sandbox and runs a bounded `true` readiness probe after `start`,
+because Daytona can report `STARTED` while its Toolbox exec daemon remains
+unavailable. A healthy restart keeps the same sandbox ID. A failure during that
+rehydration itself (auth, rate limit, or network) is not proof the exec daemon
+is dead, so it is propagated as-is and never triggers a replacement.
+
+When the post-start readiness probe fails, the runtime defaults to creating and proving
+a replacement before deleting the unusable sandbox. The returned handle is
+updated in place and can therefore have a new `id`; callers must persist that
+returned ID. The replacement preserves the configured snapshot plus provider
+labels, environment, lifecycle, volume, and network settings, but non-volume
+filesystem changes in the old sandbox are not copied. Stateful callers that
+prefer a hard failure to that trade-off can set `recreateOnFailedStart: false`.
+
+### E2B runtime contract
+
+`E2BSandboxRuntime` implements both the outer orchestration port and the live
+`WorkflowRuntime` surface: metadata/state lookup, reattachment, synchronous and
+durable asynchronous execution, upload/download, home-directory resolution,
+pause/resume, and owned-resource teardown. It deliberately does not expose a
+detached-launch method because E2B's public create call waits for a running
+sandbox. Its live capability descriptor likewise reports PTY and streaming logs
+as unsupported because this adapter exposes neither behavior, even though the
+provider SDK has lower-level APIs for them.
+
+The adapter applies an explicit sandbox lifetime on create, reconnect, and
+synchronous use; `sandboxLifetimeMs` defaults to the configured asynchronous
+run budget.
+
+Synchronous runs always carry an explicit command lifetime cap, because E2B —
+alone among the providers here — applies a 60-second default when the field is
+omitted, while the orchestrator omits `timeoutMs` on most execs. A run without a
+caller timeout therefore uses `syncRunBudgetMs`, which defaults to the
+configured `runBudgetMs` (30 minutes unless set). An explicit caller timeout
+always wins, and is the only thing that extends the sandbox past
+`sandboxLifetimeMs`; the implicit budget never does.
+
+Asynchronous session IDs are immutable idempotency keys. A retry
+reconciles the durable admission record with E2B's process list and will not
+erase the session directory or submit another copy. Status is pending only
+while the matching provider process is present. If that process disappears
+without publishing its exit sidecar, status becomes terminal with
+`E2B_ASYNC_PROCESS_LOST_EXIT_CODE` (`255`).
+
+### Daytona wire-supplement
+
+Daytona's Sandbox wire response carries two fields — `sandboxClass` (the
+sandbox's class/tier) and `warmPoolId` (set while a sandbox is an unclaimed
+warm-pool member) — that exist on the low-level `@daytona/api-client` DTOs but
+that the vendored `@daytonaio/sdk`'s `Sandbox` class does not copy onto
+itself. `DaytonaRuntime.getWireSupplement(handle)` fetches both directly via
+the SDK's low-level `sandboxApi`, the same reach pattern `runtime.ts` already
+uses for detached create.
+
+This is a narrow, deliberately temporary gap, not a fork of the SDK: the
+other fields once suspected missing (`autoDestroyAt`, `autoPauseInterval`,
+`spot`) already ship on the public `Sandbox` class as of `@daytonaio/sdk`
+0.200.0–0.205.0 — a dependency bump alone covers those. Tracked upstream at
+[daytona/clients#207](https://github.com/daytona/clients/issues/207)
+(precedent: [#192](https://github.com/daytona/clients/pull/192), which added
+`spot` the same way). Retire `src/daytona/wire-supplement.ts` once
+`processSandboxDto()` copies `sandboxClass`/`warmPoolId` and a subsequent SDK
+bump picks that up — `runtime.test.ts`'s `DaytonaRuntime smoke` suite has a
+load-bearing regression test that fails once that happens.
+### Freestyle runtime contract
+
+`FreestyleRuntime` uses an explicit API key, home directory, ownership-name
+prefix, and persistence policy. It never reads ambient credentials. Freestyle
+does not expose labels on VM creation, so label lookup and warm leasing remain
+unsupported; ownership and cleanup are scoped to collision-safe names under the
+configured prefix. Deleted list rows are treated as gone only when the provider
+sets `deleted: true`.
+
+The adapter exposes buffered exec, file transfer, reattachment, owned-resource
+listing, and verified deletion. Stop/start methods exist as a conservative
+probe surface, but lifecycle remains undeclared because the live validation
+account could not create a persistent VM. PTY, snapshots, streaming logs, fork,
+and never-idle behavior are likewise not advertised without the required live
+proof through this package's public port.
+
+The official SDK is isolated under `src/freestyle/internal/`; public
+configuration and capability metadata do not import vendor types. All create,
+lookup, exec, lifecycle, and deletion operations have explicit deadlines. See
+[the Freestyle adapter notes](./docs/freestyle.md) for dependency provenance,
+provider constraints, and capability evidence.
+
+### Vercel Sandbox runtime contract
+
+`VercelSandboxRuntime` takes an explicit token, team id, project id, ownership
+name prefix, and home directory, and passes credentials on every SDK call so the
+vendor's own environment and on-disk OAuth fallbacks can never supply an
+operator's identity.
+
+A Vercel sandbox is addressed by its **name**, not an opaque id, so
+`RuntimeHandle.id` carries the name and the configured prefix is a real
+ownership boundary: stop, start, and delete refuse any name outside it.
+`Sandbox.list` supports server-side `namePrefix` and `tags` filters, so label
+lookup is a real search here — but every row is re-checked against the requested
+tags in process, because a server filter that were ever ignored would hand back
+someone else's sandbox as a warm lease. `getById` is implemented over `list`
+rather than `Sandbox.get`, which resumes and bills the sandbox as a side effect.
+
+Deletion is verified by absence, and a row that reappears under the same name
+with a different `createdAt` counts as proof our sandbox is gone rather than as
+a survivor. Failed verification retains the registration so cleanup stays
+retryable. `acquire()` returns an `AsyncDisposable` for `await using` scopes.
+
+Commands run as `sh -c` with `cwd` and `env` passed through provider fields, so
+no caller value is spliced into a command string. Every operation carries its
+own deadline, under an absolute `retryDeadlineMs` ceiling that spans the SDK's
+internal retries.
+
+Warm leasing, lifecycle, PTY, snapshots, streaming logs, fork, and verified
+cleanup are all declared `false` pending live evidence; never-idle is settled
+false, because every Vercel sandbox carries a termination deadline. The official
+SDK is isolated under `src/vercel/internal/`. See
+[the Vercel adapter notes](./docs/vercel.md) for dependency provenance,
+capability evidence, and the active-CPU-versus-wall-clock pricing analysis.
+
+Capabilities are also declared structurally. PTY and snapshots resolve to
+`"not-exposed"` — real in the SDK, unreachable through this port, and so not
+something a live probe may promote — while `lifetime` resolves to `"deadline"`,
+the settled reason a Vercel sandbox has no never-idle tier. `filesystem` is
+deliberately left `"unknown"`: durability is per-instance configuration
+(`persistent`), and surviving a stop/resume is the same round trip `lifecycle`
+is still awaiting live proof of.
+
+### Modal runtime contract
+
+`ModalRuntime` takes an explicit Modal **token pair** (`tokenId` and
+`tokenSecret` — Modal does not use a single bearer key), an App name, an image
+tag, a home directory, and an ownership-name prefix. It never reads ambient
+credentials or a local Modal profile.
+
+A Modal Sandbox is a child of an App, built from an Image, and it has a
+**maximum lifetime after which the provider terminates it** — the SDK's own
+default is five minutes. `maxLifetimeMs` is therefore required configuration and
+is always sent explicitly. `createTimeoutSeconds` on `launch` is a deadline on
+the create call and is deliberately not forwarded to that lifetime.
+
+Modal exposes no stop/start for a Sandbox; `terminate` is the only lifecycle
+transition and it is terminal. `start` and `stop` are absent rather than
+no-ops, and `lifecycle` is declared false permanently. Async exec is likewise
+not implemented: Modal cannot re-resolve a running exec by id, so the
+`startScript`/`getScriptStatus`/`getScriptLogs` trio is omitted entirely instead
+of being half-supported.
+
+Ownership rides on Modal's native server-side tags rather than on a naming
+convention. Every sandbox carries an ownership tag, every lookup filters on it
+server-side, and reattachment and deletion both re-check it. Warm leasing is
+implemented against that real tag filter but remains undeclared until a live
+probe confirms it. Snapshots, volumes, PTY, and tunnels exist in the provider
+and are documented, but are not advertised because this package's port exposes
+no operation for them.
+
+That last distinction is now stated structurally rather than in prose. The
+adapter declares `declaredCapabilityModes`, so PTY and snapshots resolve to
+`"not-exposed"` — a fact about this package's port, which `isPendingEvidence()`
+reports as unmovable — rather than to a bare `false` a later canary might read
+as merely unverified. `lifetime` resolves to `"deadline"`, which is the
+structural reason a Modal sandbox can never be never-idle. Output is
+`"buffered"`: Modal streams, the adapter drains. Warm leasing deliberately gets
+no mode, because modes describe a capability's shape and not its verification
+state.
+
+The official SDK is isolated under `src/modal/internal/`, and because that SDK
+speaks gRPC rather than HTTP there is no injectable transport seam; the boundary
+is a structural mirror that is checked at build time instead. All create,
+lookup, exec, upload, and deletion operations have explicit deadlines. See
+[the Modal adapter notes](./docs/modal.md) for dependency provenance, provider
+constraints, cost model, and capability evidence.
+
 ## Development
 
 ```bash
@@ -49,7 +290,8 @@ npm run typecheck
 npm test           # node:test
 ```
 
-Requires Node.js 20 or newer.
+Requires Node.js 20 or newer. The microsandbox adapter's own tests need Node 22+
+to load the real SDK; without it, its SDK-contract checks skip rather than fail.
 
 ## Releasing
 

package/dist/agent37/client.d.ts

@@ -0,0 +1,115 @@
+/**
+ * Minimal HTTP client for the Agent37 Cloud API.
+ *
+ * There is no official Agent37 JavaScript SDK to depend on: the only published
+ * npm package (`agent37`) is a command-line interface that exposes a `bin`, no
+ * library entry point, and no runtime dependencies. So this adapter speaks the
+ * documented HTTP contract directly over `fetch`, and takes an injectable
+ * `fetch` seam instead of a peer dependency. That is deliberate — an optional
+ * peer dependency pointing at a CLI would be a dependency on something that
+ * cannot be imported.
+ *
+ * Agent37 exposes two planes that share one credential but not one header:
+ *
+ *  - the **hosting plane** (`{baseUrl}/v1/instances/...`), authenticated with
+ *    `Authorization: Bearer <key>`, which creates, lists, execs, and tears down
+ *    instances; and
+ *  - the **instance plane** (the `url` an instance object reports),
+ *    authenticated with `X-Agent37-Key: <key>`, which serves that one
+ *    instance's filesystem.
+ *
+ * The instance plane's origin is never constructed here. It is read off the
+ * instance object, so no provider hostname is baked into this package.
+ */
+/** Response shape this client needs. Structurally satisfied by global `Response`. */
+export type Agent37FetchResponse = {
+    readonly ok: boolean;
+    readonly status: number;
+    text(): Promise<string>;
+    arrayBuffer(): Promise<ArrayBuffer>;
+};
+/** Request shape this client sends. Structurally satisfied by global `RequestInit`. */
+export type Agent37FetchInit = {
+    method?: string;
+    headers?: Record<string, string>;
+    body?: string | Uint8Array;
+    signal?: AbortSignal;
+};
+/** Injection seam for the transport. Global `fetch` is assignable to this. */
+export type Agent37Fetch = (url: string, init?: Agent37FetchInit) => Promise<Agent37FetchResponse>;
+/**
+ * A non-2xx response from either Agent37 plane.
+ *
+ * `code` is the machine-readable identifier the API documents callers should
+ * branch on — never the message text, and never the HTTP status alone, because
+ * one status carries several codes (409 is both `try_again` and
+ * `instance_limit_reached`).
+ */
+export declare class Agent37ApiError extends Error {
+    readonly status: number;
+    readonly code: string;
+    /** Method and path only. Never the query string, body, or any header. */
+    readonly request: string;
+    readonly retryable: boolean;
+    constructor(options: {
+        status: number;
+        code: string;
+        message: string;
+        request: string;
+        retryable: boolean;
+    });
+}
+export type Agent37ClientOptions = {
+    /**
+     * An `sk_live_` workspace key. Required, and never read from the environment
+     * by this package: credential sourcing belongs to the caller.
+     */
+    apiKey: string;
+    /**
+     * Origin of the Agent37 hosting API, without a trailing slash — for example
+     * the provider's public control plane, or a proxy in front of it. Required:
+     * this package ships no endpoint defaults.
+     */
+    baseUrl: string;
+    /** Transport seam. Defaults to the global `fetch`. */
+    fetch?: Agent37Fetch;
+    /** Total attempts for a retryable failure, including the first. Default 3. */
+    maxAttempts?: number;
+    /** First backoff step; doubles per attempt. Default 250ms. */
+    retryBaseDelayMs?: number;
+    /** Sleep seam, so retry backoff is deterministic under test. */
+    sleep?: (ms: number) => Promise<void>;
+};
+export declare class Agent37Client {
+    private readonly apiKey;
+    private readonly baseUrl;
+    private readonly fetchImpl;
+    private readonly maxAttempts;
+    private readonly retryBaseDelayMs;
+    private readonly sleep;
+    constructor(options: Agent37ClientOptions);
+    /** JSON call against the hosting plane (`Authorization: Bearer`). */
+    hosting<T>(method: string, path: string, options?: {
+        body?: unknown;
+        query?: Record<string, string | undefined>;
+        timeoutMs?: number;
+    }): Promise<T>;
+    /** JSON call against one instance's own plane (`X-Agent37-Key`). */
+    instance<T>(instanceUrl: string, method: string, path: string, options?: {
+        body?: string | Uint8Array;
+        contentType?: string;
+        query?: Record<string, string | undefined>;
+        timeoutMs?: number;
+        headers?: Record<string, string>;
+    }): Promise<T>;
+    /** Byte-stream call against one instance's own plane, for file downloads. */
+    instanceBytes(instanceUrl: string, method: string, path: string, options?: {
+        query?: Record<string, string | undefined>;
+        timeoutMs?: number;
+    }): Promise<Uint8Array>;
+    private send;
+    private buildHeaders;
+}
+/** Exported for tests and for callers that want to mirror the retry policy. */
+export declare function isRetryableAgent37Code(code: string): boolean;
+//# sourceMappingURL=client.d.ts.map

package/dist/agent37/client.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"client.d.ts","sourceRoot":"","sources":["../../src/agent37/client.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;GAsBG;AAEH,qFAAqF;AACrF,MAAM,MAAM,oBAAoB,GAAG;IACjC,QAAQ,CAAC,EAAE,EAAE,OAAO,CAAC;IACrB,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IACxB,IAAI,IAAI,OAAO,CAAC,MAAM,CAAC,CAAC;IACxB,WAAW,IAAI,OAAO,CAAC,WAAW,CAAC,CAAC;CACrC,CAAC;AAEF,uFAAuF;AACvF,MAAM,MAAM,gBAAgB,GAAG;IAC7B,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,OAAO,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IACjC,IAAI,CAAC,EAAE,MAAM,GAAG,UAAU,CAAC;IAC3B,MAAM,CAAC,EAAE,WAAW,CAAC;CACtB,CAAC;AAEF,8EAA8E;AAC9E,MAAM,MAAM,YAAY,GAAG,CACzB,GAAG,EAAE,MAAM,EACX,IAAI,CAAC,EAAE,gBAAgB,KACpB,OAAO,CAAC,oBAAoB,CAAC,CAAC;AAEnC;;;;;;;GAOG;AACH,qBAAa,eAAgB,SAAQ,KAAK;IACxC,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IACxB,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,yEAAyE;IACzE,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;IACzB,QAAQ,CAAC,SAAS,EAAE,OAAO,CAAC;gBAEhB,OAAO,EAAE;QACnB,MAAM,EAAE,MAAM,CAAC;QACf,IAAI,EAAE,MAAM,CAAC;QACb,OAAO,EAAE,MAAM,CAAC;QAChB,OAAO,EAAE,MAAM,CAAC;QAChB,SAAS,EAAE,OAAO,CAAC;KACpB;CAQF;AAiCD,MAAM,MAAM,oBAAoB,GAAG;IACjC;;;OAGG;IACH,MAAM,EAAE,MAAM,CAAC;IACf;;;;OAIG;IACH,OAAO,EAAE,MAAM,CAAC;IAChB,sDAAsD;IACtD,KAAK,CAAC,EAAE,YAAY,CAAC;IACrB,8EAA8E;IAC9E,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,8DAA8D;IAC9D,gBAAgB,CAAC,EAAE,MAAM,CAAC;IAC1B,gEAAgE;IAChE,KAAK,CAAC,EAAE,CAAC,EAAE,EAAE,MAAM,KAAK,OAAO,CAAC,IAAI,CAAC,CAAC;CACvC,CAAC;AAgBF,qBAAa,aAAa;IACxB,OAAO,CAAC,QAAQ,CAAC,MAAM,CAAS;IAChC,OAAO,CAAC,QAAQ,CAAC,OAAO,CAAS;IACjC,OAAO,CAAC,QAAQ,CAAC,SAAS,CAAe;IACzC,OAAO,CAAC,QAAQ,CAAC,WAAW,CAAS;IACrC,OAAO,CAAC,QAAQ,CAAC,gBAAgB,CAAS;IAC1C,OAAO,CAAC,QAAQ,CAAC,KAAK,CAAgC;gBAE1C,OAAO,EAAE,oBAAoB;IAsCzC,qEAAqE;IAC/D,OAAO,CAAC,CAAC,EACb,MAAM,EAAE,MAAM,EACd,IAAI,EAAE,MAAM,EACZ,OAAO,GAAE;QACP,IAAI,CAAC,EAAE,OAAO,CAAC;QACf,KAAK,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,GAAG,SAAS,CAAC,CAAC;QAC3C,SAAS,CAAC,EAAE,MAAM,CAAC;KACf,GACL,OAAO,CAAC,CAAC,CAAC;IAeb,oEAAoE;IAC9D,QAAQ,CAAC,CAAC,EACd,WAAW,EAAE,MAAM,EACnB,MAAM,EAAE,MAAM,EACd,IAAI,EAAE,MAAM,EACZ,OAAO,GAAE;QACP,IAAI,CAAC,EAAE,MAAM,GAAG,UAAU,CAAC;QAC3B,WAAW,CAAC,EAAE,MAAM,CAAC;QACrB,KAAK,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,GAAG,SAAS,CAAC,CAAC;QAC3C,SAAS,CAAC,EAAE,MAAM,CAAC;QACnB,OAAO,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;KAC7B,GACL,OAAO,CAAC,CAAC,CAAC;IAeb,6EAA6E;IACvE,aAAa,CACjB,WAAW,EAAE,MAAM,EACnB,MAAM,EAAE,MAAM,EACd,IAAI,EAAE,MAAM,EACZ,OAAO,GAAE;QAAE,KAAK,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,GAAG,SAAS,CAAC,CAAC;QAAC,SAAS,CAAC,EAAE,MAAM,CAAA;KAAO,GAC/E,OAAO,CAAC,UAAU,CAAC;YAcR,IAAI;IAgClB,OAAO,CAAC,YAAY;CAYrB;AA2ED,+EAA+E;AAC/E,wBAAgB,sBAAsB,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAE5D"}

package/dist/agent37/client.js

@@ -0,0 +1,270 @@
+/**
+ * Minimal HTTP client for the Agent37 Cloud API.
+ *
+ * There is no official Agent37 JavaScript SDK to depend on: the only published
+ * npm package (`agent37`) is a command-line interface that exposes a `bin`, no
+ * library entry point, and no runtime dependencies. So this adapter speaks the
+ * documented HTTP contract directly over `fetch`, and takes an injectable
+ * `fetch` seam instead of a peer dependency. That is deliberate — an optional
+ * peer dependency pointing at a CLI would be a dependency on something that
+ * cannot be imported.
+ *
+ * Agent37 exposes two planes that share one credential but not one header:
+ *
+ *  - the **hosting plane** (`{baseUrl}/v1/instances/...`), authenticated with
+ *    `Authorization: Bearer <key>`, which creates, lists, execs, and tears down
+ *    instances; and
+ *  - the **instance plane** (the `url` an instance object reports),
+ *    authenticated with `X-Agent37-Key: <key>`, which serves that one
+ *    instance's filesystem.
+ *
+ * The instance plane's origin is never constructed here. It is read off the
+ * instance object, so no provider hostname is baked into this package.
+ */
+/**
+ * A non-2xx response from either Agent37 plane.
+ *
+ * `code` is the machine-readable identifier the API documents callers should
+ * branch on — never the message text, and never the HTTP status alone, because
+ * one status carries several codes (409 is both `try_again` and
+ * `instance_limit_reached`).
+ */
+export class Agent37ApiError extends Error {
+    status;
+    code;
+    /** Method and path only. Never the query string, body, or any header. */
+    request;
+    retryable;
+    constructor(options) {
+        super(`Agent37 ${options.request} failed: ${options.status} ${options.code}: ${options.message}`);
+        this.name = "Agent37ApiError";
+        this.status = options.status;
+        this.code = options.code;
+        this.request = options.request;
+        this.retryable = options.retryable;
+    }
+}
+/**
+ * Codes the API documents as safe to retry with backoff.
+ *
+ * Everything absent from this set is retried never, not "retried cautiously".
+ * Two exclusions are load-bearing rather than conservative:
+ *
+ *  - `provisioning_failed` (502) is also what a synchronous `exec` returns when
+ *    it passes the provider's 280-second command cap. Retrying it would run the
+ *    caller's command a second time, on an instance where the first copy is
+ *    still running.
+ *  - `container_unavailable` (502) means the instance is stopped. Retrying
+ *    cannot change that; `start` can.
+ */
+const RETRYABLE_CODES = new Set([
+    // hosting plane
+    "no_capacity",
+    "try_again",
+    // transport plane
+    "container_unreachable",
+    "upstream_unreachable",
+    "host_mesh_not_ready",
+    "instance_saturated",
+    "wake_timeout",
+    "upstream_timeout",
+    // agent plane
+    "rate_limited",
+]);
+const DEFAULT_MAX_ATTEMPTS = 3;
+const DEFAULT_RETRY_BASE_DELAY_MS = 250;
+export class Agent37Client {
+    apiKey;
+    baseUrl;
+    fetchImpl;
+    maxAttempts;
+    retryBaseDelayMs;
+    sleep;
+    constructor(options) {
+        const apiKey = options.apiKey?.trim();
+        if (!apiKey) {
+            throw new Error("Agent37Client requires a non-empty apiKey");
+        }
+        const baseUrl = options.baseUrl?.trim();
+        if (!baseUrl) {
+            throw new Error("Agent37Client requires an explicit baseUrl: this package ships no endpoint defaults");
+        }
+        this.apiKey = apiKey;
+        this.baseUrl = stripTrailingSlash(baseUrl);
+        this.fetchImpl = options.fetch ?? globalThis.fetch;
+        if (typeof this.fetchImpl !== "function") {
+            throw new Error("Agent37Client requires a fetch implementation (none found on globalThis)");
+        }
+        // Non-finite maxAttempts (NaN, ±Infinity) would poison the retry loop:
+        // `attempt >= NaN` is always false, so the throw guard never fires and the
+        // loop retries a retryable failure forever. Reject explicitly rather than
+        // silently coercing.
+        const requestedAttempts = options.maxAttempts ?? DEFAULT_MAX_ATTEMPTS;
+        if (!Number.isFinite(requestedAttempts)) {
+            throw new Error(`Agent37Client maxAttempts must be a finite number; got ${String(options.maxAttempts)}`);
+        }
+        this.maxAttempts = Math.max(1, Math.floor(requestedAttempts));
+        const requestedRetryBase = options.retryBaseDelayMs ?? DEFAULT_RETRY_BASE_DELAY_MS;
+        if (!Number.isFinite(requestedRetryBase) || requestedRetryBase < 0) {
+            throw new Error(`Agent37Client retryBaseDelayMs must be a finite, non-negative number; got ${String(options.retryBaseDelayMs)}`);
+        }
+        this.retryBaseDelayMs = requestedRetryBase;
+        this.sleep = options.sleep ?? ((ms) => new Promise((resolve) => setTimeout(resolve, ms)));
+    }
+    /** JSON call against the hosting plane (`Authorization: Bearer`). */
+    async hosting(method, path, options = {}) {
+        const response = await this.send({
+            method,
+            origin: this.baseUrl,
+            path,
+            ...(options.query ? { query: options.query } : {}),
+            headerStyle: "bearer",
+            ...(options.body === undefined
+                ? {}
+                : { body: JSON.stringify(options.body), contentType: "application/json" }),
+            ...(options.timeoutMs === undefined ? {} : { timeoutMs: options.timeoutMs }),
+        });
+        return (await readJson(response));
+    }
+    /** JSON call against one instance's own plane (`X-Agent37-Key`). */
+    async instance(instanceUrl, method, path, options = {}) {
+        const response = await this.send({
+            method,
+            origin: stripTrailingSlash(instanceUrl),
+            path,
+            ...(options.query ? { query: options.query } : {}),
+            headerStyle: "instance-key",
+            ...(options.body === undefined ? {} : { body: options.body }),
+            ...(options.contentType === undefined ? {} : { contentType: options.contentType }),
+            ...(options.timeoutMs === undefined ? {} : { timeoutMs: options.timeoutMs }),
+            ...(options.headers ? { headers: options.headers } : {}),
+        });
+        return (await readJson(response));
+    }
+    /** Byte-stream call against one instance's own plane, for file downloads. */
+    async instanceBytes(instanceUrl, method, path, options = {}) {
+        const response = await this.send({
+            method,
+            origin: stripTrailingSlash(instanceUrl),
+            path,
+            ...(options.query ? { query: options.query } : {}),
+            headerStyle: "instance-key",
+            ...(options.timeoutMs === undefined ? {} : { timeoutMs: options.timeoutMs }),
+        });
+        return new Uint8Array(await response.arrayBuffer());
+    }
+    // --- internals ----------------------------------------------------------
+    async send(options) {
+        // `request` is what surfaces in errors: method and path, never the query
+        // string (it carries filesystem paths) and never a header (it carries the
+        // credential).
+        const request = `${options.method} ${options.path}`;
+        const url = buildUrl(options.origin, options.path, options.query);
+        let attempt = 0;
+        for (;;) {
+            attempt += 1;
+            // A thrown transport failure is NOT retried. The outcome of a POST that
+            // never returned is unknown, and re-sending it is how one submitted
+            // command becomes two. Only a *classified* response is retried, because
+            // only then is it known that the server rejected rather than accepted.
+            const response = await this.fetchImpl(url, {
+                method: options.method,
+                headers: this.buildHeaders(options),
+                ...(options.body === undefined ? {} : { body: options.body }),
+                ...(options.timeoutMs === undefined || options.timeoutMs <= 0
+                    ? {}
+                    : { signal: AbortSignal.timeout(options.timeoutMs) }),
+            });
+            if (response.ok) {
+                return response;
+            }
+            const error = await toApiError(response, request);
+            if (!error.retryable || attempt >= this.maxAttempts) {
+                throw error;
+            }
+            await this.sleep(this.retryBaseDelayMs * 2 ** (attempt - 1));
+        }
+    }
+    buildHeaders(options) {
+        const headers = { ...(options.headers ?? {}) };
+        if (options.headerStyle === "bearer") {
+            headers.Authorization = `Bearer ${this.apiKey}`;
+        }
+        else {
+            headers["X-Agent37-Key"] = this.apiKey;
+        }
+        if (options.contentType) {
+            headers["Content-Type"] = options.contentType;
+        }
+        return headers;
+    }
+}
+// --- helpers --------------------------------------------------------------
+function stripTrailingSlash(value) {
+    return value.replace(/\/+$/, "");
+}
+function buildUrl(origin, path, query) {
+    const params = new URLSearchParams();
+    for (const [key, value] of Object.entries(query ?? {})) {
+        if (value !== undefined) {
+            params.append(key, value);
+        }
+    }
+    const search = params.toString();
+    return `${origin}${path}${search ? `?${search}` : ""}`;
+}
+async function readJson(response) {
+    const text = await response.text();
+    if (!text) {
+        return {};
+    }
+    try {
+        return JSON.parse(text);
+    }
+    catch {
+        return {};
+    }
+}
+/**
+ * Normalize the three documented error envelopes into one error.
+ *
+ *  - hosting/agent plane: `{ "error": { "code", "message", ... } }`
+ *  - transport plane:     `{ "error": "flat_string_code" }`
+ *  - neither (HTML from a proxy, empty body): synthesize `http_<status>`, which
+ *    is never in the retryable set, so an unparseable failure fails fast.
+ */
+async function toApiError(response, request) {
+    let code = `http_${response.status}`;
+    let message = "";
+    try {
+        const parsed = JSON.parse(await response.text());
+        const raw = parsed.error;
+        if (typeof raw === "string" && raw) {
+            code = raw;
+        }
+        else if (raw && typeof raw === "object") {
+            const shaped = raw;
+            if (typeof shaped.code === "string" && shaped.code) {
+                code = shaped.code;
+            }
+            if (typeof shaped.message === "string") {
+                message = shaped.message;
+            }
+        }
+    }
+    catch {
+        // Leave the synthesized code in place.
+    }
+    return new Agent37ApiError({
+        status: response.status,
+        code,
+        message,
+        request,
+        retryable: RETRYABLE_CODES.has(code),
+    });
+}
+/** Exported for tests and for callers that want to mirror the retry policy. */
+export function isRetryableAgent37Code(code) {
+    return RETRYABLE_CODES.has(code);
+}
+//# sourceMappingURL=client.js.map