@agent-relay/sandbox 0.1.2 → 0.1.3

package/dist/modal/internal/sdk.d.ts

@@ -0,0 +1,141 @@
+/**
+ * The only module in this package that imports the Modal SDK.
+ *
+ * Everything the adapter uses is expressed here as a structural interface, so
+ * `runtime.ts` depends on shapes rather than on the vendor package. That
+ * matters more for Modal than for a REST provider: the official SDK speaks
+ * **gRPC** (`nice-grpc` / `protobufjs` / `cbor-x`), so there is no HTTP layer
+ * to intercept and no injectable `fetch` seam of the kind the Agent37 client
+ * uses. Structural interfaces plus a factory are the only way to keep the
+ * adapter's tests off the wire.
+ *
+ * Pinned surface: `modal@0.9.0` (modal-labs/libmodal), published 2026-07-09,
+ * Apache-2.0.
+ *   integrity sha512-kCXcdJkhbJorf/q/6T9Wdlg6in9JmRnCNQnV6rVBMyeqNV/iXI6BYk4IzY4cvZ6dbauNeDMjk/Q08cbxvoIaXg==
+ *   gitHead  79b729fb75abdde51d1130d3a7347416a5da75b6
+ *   docs     https://modal.com/docs/sdk/js/latest/Sandbox
+ * The declarations below were read from that release's shipped `index.d.ts`,
+ * whose tarball SHA-1 was verified against the registry's `dist.shasum`.
+ *
+ * The SDK is a `0.x` beta and its own README warns that breaking changes ship
+ * in `0.X.0` releases, which is why the peer range is pinned narrowly.
+ */
+import type { ResolvedModalRuntimeOptions } from "../config.js";
+/** A Modal App. Opaque: the adapter only ever passes it back to `create`. */
+export interface ModalAppLike {
+    readonly appId?: string;
+}
+/** A Modal Image. Opaque: the adapter only ever passes it back to `create`. */
+export interface ModalImageLike {
+    readonly imageId?: string;
+}
+/** A drainable output stream. Modal's `ModalReadStream` satisfies this. */
+export interface ModalReadStreamLike {
+    readText(): Promise<string>;
+}
+/**
+ * A running exec.
+ *
+ * Note what is *absent*: there is no public way to re-resolve a
+ * `ContainerProcess` from an id later. Its `execId` reattach path is marked
+ * `@ignore` in the SDK and is not exported. That absence is why this adapter
+ * declines to implement the port's async-exec trio — see `runtime.ts`.
+ */
+export interface ModalContainerProcessLike {
+    readonly stdout: ModalReadStreamLike;
+    readonly stderr: ModalReadStreamLike;
+    wait(): Promise<number>;
+}
+/** The subset of Modal's `SandboxFilesystem` the adapter uses. */
+export interface ModalFilesystemLike {
+    writeBytes(data: Uint8Array, remotePath: string): Promise<void>;
+    readBytes(remotePath: string): Promise<Uint8Array>;
+    makeDirectory(remotePath: string, options?: {
+        createParents?: boolean;
+    }): Promise<void>;
+}
+export interface ModalExecParams {
+    workdir?: string;
+    timeoutMs?: number;
+    env?: Record<string, string>;
+    stdout?: "pipe" | "ignore";
+    stderr?: "pipe" | "ignore";
+}
+/** The subset of Modal's `Sandbox` the adapter uses. */
+export interface ModalSandboxLike {
+    readonly sandboxId: string;
+    readonly filesystem: ModalFilesystemLike;
+    /**
+     * Note the signature: Modal takes an **argv array**, not a shell string.
+     * The adapter is responsible for wrapping caller commands.
+     */
+    exec(command: string[], params?: ModalExecParams): Promise<ModalContainerProcessLike>;
+    /**
+     * Terminate the sandbox. With `{ wait: true }` Modal resolves only once the
+     * sandbox has actually finished and returns its exit code — the provider's
+     * own verified-gone signal, which the adapter prefers over polling.
+     */
+    terminate(params?: {
+        wait?: boolean;
+    }): Promise<number | void>;
+    /** `null` while running; the exit code once finished. */
+    poll(): Promise<number | null>;
+    wait(): Promise<number>;
+    setTags(tags: Record<string, string>): Promise<void>;
+    getTags(): Promise<Record<string, string>>;
+}
+export interface ModalSandboxCreateParams {
+    name?: string;
+    tags?: Record<string, string>;
+    env?: Record<string, string>;
+    command?: string[];
+    workdir?: string;
+    /** Maximum sandbox lifetime. Modal terminates the sandbox once it elapses. */
+    timeoutMs?: number;
+    idleTimeoutMs?: number;
+    cpu?: number;
+    cpuLimit?: number;
+    memoryMiB?: number;
+    memoryLimitMiB?: number;
+    cloud?: string;
+    regions?: string[];
+    blockNetwork?: boolean;
+}
+export interface ModalSandboxListParams {
+    appId?: string;
+    tags?: Record<string, string>;
+    environment?: string;
+}
+export interface ModalSandboxServiceLike {
+    create(app: ModalAppLike, image: ModalImageLike, params?: ModalSandboxCreateParams): Promise<ModalSandboxLike>;
+    fromId(sandboxId: string): Promise<ModalSandboxLike>;
+    /** Server-side tag filter: yields only sandboxes carrying *all* given tags. */
+    list(params?: ModalSandboxListParams): AsyncIterable<ModalSandboxLike>;
+}
+export interface ModalClientLike {
+    readonly apps: {
+        fromName(name: string, params?: {
+            environment?: string;
+            createIfMissing?: boolean;
+        }): Promise<ModalAppLike>;
+    };
+    readonly images: {
+        fromRegistry(tag: string): ModalImageLike;
+    };
+    readonly sandboxes: ModalSandboxServiceLike;
+    /** Closes the gRPC channel. Not optional in practice: see `runtime.ts`. */
+    close(): void;
+}
+/** Injection seam. The adapter never constructs a vendor client directly. */
+export type ModalClientFactory = (options: ResolvedModalRuntimeOptions) => Promise<ModalClientLike> | ModalClientLike;
+/**
+ * Construct the official client.
+ *
+ * Credentials are passed explicitly rather than left to the SDK's ambient
+ * resolution (`~/.modal.toml`, `MODAL_TOKEN_*`). The SDK will happily fall back
+ * to a developer's local profile if `tokenId`/`tokenSecret` are omitted, which
+ * would make this adapter silently use whatever account the host happens to be
+ * logged into. Passing both explicitly closes that path.
+ */
+export declare function createOfficialModalClient(options: ResolvedModalRuntimeOptions): Promise<ModalClientLike>;
+//# sourceMappingURL=sdk.d.ts.map

package/dist/modal/internal/sdk.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"sdk.d.ts","sourceRoot":"","sources":["../../../src/modal/internal/sdk.ts"],"names":[],"mappings":"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"}

package/dist/modal/internal/sdk.js

@@ -0,0 +1,51 @@
+/**
+ * The only module in this package that imports the Modal SDK.
+ *
+ * Everything the adapter uses is expressed here as a structural interface, so
+ * `runtime.ts` depends on shapes rather than on the vendor package. That
+ * matters more for Modal than for a REST provider: the official SDK speaks
+ * **gRPC** (`nice-grpc` / `protobufjs` / `cbor-x`), so there is no HTTP layer
+ * to intercept and no injectable `fetch` seam of the kind the Agent37 client
+ * uses. Structural interfaces plus a factory are the only way to keep the
+ * adapter's tests off the wire.
+ *
+ * Pinned surface: `modal@0.9.0` (modal-labs/libmodal), published 2026-07-09,
+ * Apache-2.0.
+ *   integrity sha512-kCXcdJkhbJorf/q/6T9Wdlg6in9JmRnCNQnV6rVBMyeqNV/iXI6BYk4IzY4cvZ6dbauNeDMjk/Q08cbxvoIaXg==
+ *   gitHead  79b729fb75abdde51d1130d3a7347416a5da75b6
+ *   docs     https://modal.com/docs/sdk/js/latest/Sandbox
+ * The declarations below were read from that release's shipped `index.d.ts`,
+ * whose tarball SHA-1 was verified against the registry's `dist.shasum`.
+ *
+ * The SDK is a `0.x` beta and its own README warns that breaking changes ship
+ * in `0.X.0` releases, which is why the peer range is pinned narrowly.
+ */
+/**
+ * Construct the official client.
+ *
+ * Credentials are passed explicitly rather than left to the SDK's ambient
+ * resolution (`~/.modal.toml`, `MODAL_TOKEN_*`). The SDK will happily fall back
+ * to a developer's local profile if `tokenId`/`tokenSecret` are omitted, which
+ * would make this adapter silently use whatever account the host happens to be
+ * logged into. Passing both explicitly closes that path.
+ */
+export async function createOfficialModalClient(options) {
+    const { ModalClient } = await import("modal");
+    // Deliberately a *checked* assignment, not an `as unknown as` cast.
+    //
+    // Every declaration in this module is a hand-written mirror of a vendor type,
+    // and the SDK is a 0.x beta that ships breaking changes in minor releases.
+    // A blind cast would let the real surface drift away from this mirror and
+    // fail at runtime, in production, against a live sandbox. Assigning through
+    // the structural type instead makes any drift a build error here, which is
+    // the whole reason the boundary exists.
+    const client = new ModalClient({
+        tokenId: options.credentials.tokenId,
+        tokenSecret: options.credentials.tokenSecret,
+        timeoutMs: options.requestTimeoutMs,
+        ...(options.environment === undefined ? {} : { environment: options.environment }),
+        ...(options.endpoint === undefined ? {} : { endpoint: options.endpoint }),
+    });
+    return client;
+}
+//# sourceMappingURL=sdk.js.map

package/dist/modal/internal/sdk.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"sdk.js","sourceRoot":"","sources":["../../../src/modal/internal/sdk.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;GAqBG;AA6HH;;;;;;;;GAQG;AACH,MAAM,CAAC,KAAK,UAAU,yBAAyB,CAC7C,OAAoC;IAEpC,MAAM,EAAE,WAAW,EAAE,GAAG,MAAM,MAAM,CAAC,OAAO,CAAC,CAAC;IAC9C,oEAAoE;IACpE,EAAE;IACF,8EAA8E;IAC9E,2EAA2E;IAC3E,0EAA0E;IAC1E,4EAA4E;IAC5E,2EAA2E;IAC3E,wCAAwC;IACxC,MAAM,MAAM,GAAoB,IAAI,WAAW,CAAC;QAC9C,OAAO,EAAE,OAAO,CAAC,WAAW,CAAC,OAAO;QACpC,WAAW,EAAE,OAAO,CAAC,WAAW,CAAC,WAAW;QAC5C,SAAS,EAAE,OAAO,CAAC,gBAAgB;QACnC,GAAG,CAAC,OAAO,CAAC,WAAW,KAAK,SAAS,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,EAAE,WAAW,EAAE,OAAO,CAAC,WAAW,EAAE,CAAC;QAClF,GAAG,CAAC,OAAO,CAAC,QAAQ,KAAK,SAAS,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,EAAE,QAAQ,EAAE,OAAO,CAAC,QAAQ,EAAE,CAAC;KAC1E,CAAC,CAAC;IACH,OAAO,MAAM,CAAC;AAChB,CAAC"}

package/dist/modal/runtime.d.ts

@@ -0,0 +1,271 @@
+import { Buffer } from "node:buffer";
+import type { DeclaredSandboxRuntimeCapabilities, RunScriptResult, SandboxCapabilityModes, SandboxCountOptions, SandboxLookupOptions, SandboxRuntime } from "../port.js";
+import type { RuntimeHandle } from "../types.js";
+import { type ModalRuntimeOptions } from "./config.js";
+import { type ModalClientFactory } from "./internal/sdk.js";
+/**
+ * Modal sandbox runtime.
+ *
+ * ## How Modal's model differs, and what this adapter does about it
+ *
+ * **Sandboxes are children of an App, built from an Image.** `create` takes
+ * both, so the runtime resolves one `App` and one `Image` up front and reuses
+ * them. Neither has a default; both come from config.
+ *
+ * **Sandboxes have a maximum lifetime and the SDK default is five minutes.**
+ * The provider terminates the sandbox when it elapses, running work included.
+ * `maxLifetimeMs` is therefore required config and is always sent explicitly.
+ * It is unrelated to any request deadline — see the note on
+ * `createTimeoutSeconds` in {@link ModalRuntime.launch}.
+ *
+ * **Sandboxes cannot be stopped and restarted.** `terminate()` is the only
+ * lifecycle transition and it is terminal. `start`/`stop` are absent from this
+ * class rather than present as no-ops, and `lifecycle: false` is declared so
+ * the capability resolver — which cannot see an absent method — agrees.
+ *
+ * **Ownership rides on Modal's native, server-side tags.** Every sandbox is
+ * created carrying an ownership tag, every lookup filters on it server-side,
+ * and every destructive or reattaching operation re-checks it. Collision
+ * safety is structural here, not a naming convention.
+ *
+ * **Async exec is deliberately not implemented.** Modal's `exec` hands back a
+ * live `ContainerProcess`, but nothing public re-resolves one from an id after
+ * the fact. Implementing `startScript` without a real `getScriptStatus` would
+ * let a caller submit a command it could never poll or reap — precisely the
+ * failure the port's all-or-nothing `asyncExec` rule exists to prevent. The
+ * trio is omitted, so the resolver derives `asyncExec: false`.
+ *
+ * **V1 `create` is pinned on purpose.** Modal also offers
+ * `experimentalCreate` (the V2 backend). V2 sandboxes do not support tags and
+ * are not returned by `sandboxes.list()`, which would silently destroy both the
+ * ownership model and the cleanup story above. Do not "upgrade" this call.
+ */
+export declare class ModalRuntime implements SandboxRuntime {
+    readonly id = "modal";
+    readonly declaredCapabilities: Partial<DeclaredSandboxRuntimeCapabilities>;
+    readonly declaredCapabilityModes: Partial<SandboxCapabilityModes>;
+    private readonly options;
+    private readonly clientFactory;
+    private clientPromise;
+    private contextPromise;
+    /**
+     * Reconciliation tasks that outlive their caller.
+     *
+     * The only source today is `launch()` racing a `sandboxes.create()` past its
+     * client-side deadline: when the deadline fires the create can still complete
+     * and hand back a sandbox that would otherwise bill silently. `close()` awaits
+     * these before releasing the gRPC channel so that a reconciliation cannot be
+     * orphaned by teardown.
+     */
+    private readonly reconciliations;
+    constructor(options: ModalRuntimeOptions & {
+        clientFactory?: ModalClientFactory;
+    });
+    findByLabels(labels: Record<string, string>, options?: SandboxLookupOptions): Promise<RuntimeHandle | null>;
+    /**
+     * Server-side tag search.
+     *
+     * Two honesty notes:
+     *
+     *  - Modal's `list` yields sandboxes carrying *at least* the requested tags,
+     *    so the ownership tag is merged into the filter rather than applied after
+     *    the fact. A foreign sandbox is never fetched, let alone returned.
+     *  - Modal's `Sandbox` object carries **no state field**. The only way to
+     *    learn whether one is running is `poll()`, one round trip each. So state
+     *    is left `undefined` unless the caller actually asked to filter on it,
+     *    in which case each candidate costs one extra call. Reporting a guessed
+     *    state for free would be worse than reporting none.
+     */
+    findAllByLabels(labels: Record<string, string>, options?: SandboxLookupOptions): Promise<RuntimeHandle[]>;
+    countByLabels(labels: Record<string, string>, options?: SandboxCountOptions): Promise<number>;
+    /**
+     * Re-resolve a sandbox by id.
+     *
+     * Ownership is re-checked here, not assumed. `fromId` will happily return any
+     * sandbox in the workspace, so a caller holding a synthesized or stale id
+     * could otherwise reattach to a sandbox belonging to another lane. A foreign
+     * sandbox reads as absent (`null`) rather than raising, because "not one of
+     * mine" and "not there" are the same answer to this question.
+     *
+     * Unlike `findAllByLabels`/`countByLabels`, this path is not server-side
+     * tag-filtered: Modal's `fromId` accepts no tag argument, so a foreign
+     * sandbox is fetched before `isOwned()` can reject it. That costs one extra
+     * `getTags()` round trip for a lookup a lane could otherwise have skipped;
+     * the trade is deliberate because `fromId` is the only reattach primitive
+     * Modal exposes.
+     */
+    getById(id: string, options?: {
+        states?: readonly string[] | null;
+        owned?: boolean;
+    }): Promise<RuntimeHandle | null>;
+    /**
+     * Create a sandbox.
+     *
+     * `createTimeoutSeconds` is a **client-side deadline on this call**. It is
+     * deliberately NOT forwarded to Modal's `timeoutMs`, which despite the name
+     * is the sandbox's maximum lifetime. Conflating them would make a caller who
+     * asked to wait 30 s for provisioning receive a sandbox that self-destructs
+     * 30 s later. Lifetime comes from `maxLifetimeMs` config and nowhere else.
+     */
+    launch(options?: {
+        name?: string;
+        env?: Record<string, string>;
+        labels?: Record<string, string>;
+        createTimeoutSeconds?: number;
+    }): Promise<RuntimeHandle>;
+    /**
+     * Terminate a create that outlived its deadline.
+     *
+     * Runs after `launch()` has already rejected, so the caller has no handle
+     * for the sandbox that might still be materialising. Failure modes here are
+     * all silent by design: if the create ultimately rejects there is nothing to
+     * clean up; if terminate fails there is no caller to raise to. `close()`
+     * awaits these before releasing the gRPC channel so a reconciliation cannot
+     * be orphaned by teardown.
+     */
+    private reconcileOrphanedCreate;
+    private trackReconciliation;
+    /**
+     * Terminate a sandbox and verify it is gone.
+     *
+     * Ownership is checked before the terminate, not after. `destroy` is
+     * irreversible, so paying one extra round trip to be certain the sandbox is
+     * ours is the correct trade — a mis-routed handle must fail loudly rather
+     * than delete another lane's work.
+     *
+     * Verification prefers Modal's own signal: `terminate({ wait: true })`
+     * resolves with an exit code only once the sandbox has actually finished. If
+     * the provider resolves without one, the adapter falls back to polling until
+     * `poll()` reports a finished sandbox, so `cleanupVerified` never rests on a
+     * request merely having been accepted.
+     */
+    destroy(handle: RuntimeHandle): Promise<void>;
+    uploadBundle(handle: RuntimeHandle, options: {
+        files: Array<{
+            source: string | Buffer;
+            destination: string;
+        }>;
+    }): Promise<void>;
+    /**
+     * Run a command to completion and return its buffered output.
+     *
+     * Modal's `exec` takes an **argv array**, not a shell string, so the caller's
+     * command is wrapped in `sh -lc`. Without that wrapping every pipeline,
+     * redirect, and variable expansion a caller writes would be passed through as
+     * a literal argument.
+     *
+     * stdout, stderr, and the exit code are awaited together. Draining the
+     * streams only after `wait()` resolves risks deadlocking against a process
+     * that fills a pipe buffer and blocks before exiting.
+     */
+    runScript(handle: RuntimeHandle, options: {
+        command: string;
+        sessionId?: string;
+        timeoutMs?: number;
+        env?: Record<string, string>;
+    }): Promise<RunScriptResult>;
+    /** Tags every sandbox this runtime creates must carry. */
+    private ownerTags;
+    /**
+     * Merge caller labels with the ownership tag, refusing to let a caller
+     * overwrite it. Silently winning that collision either way is a bug: our
+     * value would make a foreign sandbox look owned, theirs would make ours
+     * invisible to cleanup.
+     */
+    private buildOwnedTags;
+    private buildLookupTags;
+    private listParams;
+    /**
+     * Confirm in-process that a listed sandbox really carries the tags we
+     * filtered on.
+     *
+     * The server-side filter is the mechanism this adapter's ownership rests on,
+     * and it has not yet been proven live — `warmLease` is still `false`. A
+     * filter that is silently ignored or partially applied would return a foreign
+     * sandbox, and handing that back as a warm lease is worse than returning
+     * nothing: the caller would exec into another tenant's container. So the
+     * claim is re-checked against the sandbox's own tags rather than trusted.
+     *
+     * Skipped when there is nothing to check, so an unfiltered audit listing
+     * (`owned: false` with no labels) does not pay for a round trip that could
+     * not reject anything.
+     */
+    private tagsReallyMatch;
+    private isOwned;
+    /**
+     * Resolve a sandbox by id and prove ownership before returning it.
+     *
+     * Every write-or-execute path that takes a caller-supplied id must go
+     * through this: `fromId` will happily return any sandbox in the workspace,
+     * so a stale or synthesized handle would otherwise let a caller reattach to
+     * another lane's sandbox and mutate it. `destroy` uses its own resolution
+     * because it must also treat an already-absent sandbox as success — the
+     * only shape here that is idempotent.
+     */
+    private ownedSandbox;
+    private waitUntilGone;
+    private sandboxName;
+    private toHandle;
+    private deadline;
+    private client;
+    /**
+     * Resolve the App and Image once and reuse them. Both are required by every
+     * `create`, neither changes over the runtime's life, and each resolution is
+     * a round trip.
+     */
+    private context;
+    /**
+     * Release the gRPC channel.
+     *
+     * Not part of `SandboxRuntime`, but necessary: the SDK holds an open HTTP/2
+     * connection, and a Node process that never calls this will not exit on its
+     * own. Long-lived hosts can ignore it; short-lived scripts and tests cannot.
+     */
+    close(): Promise<void>;
+}
+/** A handle that does not carry this runtime's ownership tag. */
+export declare class ModalForeignSandboxError extends Error {
+    readonly sandboxId: string;
+    readonly expectedOwner: string;
+    constructor(sandboxId: string, expectedOwner: string);
+}
+/** A caller label collided with the reserved ownership tag key. */
+export declare class ModalTagCollisionError extends Error {
+    readonly tagKey: string;
+    constructor(tagKey: string);
+}
+/**
+ * An operation exceeded its explicit client-side deadline.
+ *
+ * Two independent caps bound any Modal call: this per-operation budget, and
+ * the SDK's own per-request `requestTimeoutMs`. They fail differently on
+ * purpose — the SDK's cap surfaces as a gRPC error from the vendor, this one
+ * as `ModalDeadlineExceededError` — so the error *type* already says which
+ * fired. The message names the sibling cap anyway, because a reader looking at
+ * a timeout usually needs to check both numbers before concluding the network
+ * was slow.
+ */
+export declare class ModalDeadlineExceededError extends Error {
+    readonly operation: string;
+    readonly timeoutMs: number;
+    /** The SDK's per-request cap, when the runtime knew it. */
+    readonly requestTimeoutMs: number | undefined;
+    constructor(operation: string, timeoutMs: number, requestTimeoutMs?: number);
+}
+/** Declared capabilities disagree with what this class actually implements. */
+export declare class ModalCapabilityMismatchError extends Error {
+    readonly mismatches: readonly string[];
+    constructor(mismatches: readonly string[]);
+}
+/**
+ * Assert at construction time that every declared capability matches what this
+ * class actually implements.
+ *
+ * The point is to fail on the developer's machine rather than in production.
+ * A declaration and an implementation drift apart silently — someone adds a
+ * `stop` that no-ops, or flips `warmLease` to true while `findAllByLabels`
+ * still returns `[]` — and the orchestrator believes the declaration. Every
+ * rule below encodes a way this adapter could lie.
+ */
+export declare function reconcileModalCapabilities(runtime: SandboxRuntime): void;
+//# sourceMappingURL=runtime.d.ts.map

package/dist/modal/runtime.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"runtime.d.ts","sourceRoot":"","sources":["../../src/modal/runtime.ts"],"names":[],"mappings":"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"}