@agent-relay/sandbox 0.1.2 → 0.1.3

package/dist/modal/bench.js

@@ -0,0 +1,450 @@
+/**
+ * Modal benchmark harness: ledger, cost guards, and measurement.
+ *
+ * This module is deliberately separate from any live credential. It contains
+ * no I/O of its own — it drives a `SandboxRuntime` that the caller supplies —
+ * so every guard below is unit-testable against a fake runtime, and the guards
+ * are proven *before* they are trusted with a real account.
+ *
+ * The safety model has three independent layers, and each one alone is
+ * sufficient to stop a runaway:
+ *
+ *  1. **Ledger before use.** Every sandbox is recorded as *intended* before the
+ *     create call is made, not after it returns. A create that times out or
+ *     crashes mid-flight still leaves a record, so a sandbox that was actually
+ *     provisioned can never be invisible to cleanup.
+ *  2. **Bounded cost.** A projected cost is computed for each sandbox from
+ *     Modal's published rates and charged against a hard budget *before* the
+ *     create. The run aborts rather than exceeding it.
+ *  3. **Verified cleanup.** Teardown runs in a `finally`, and afterwards each
+ *     ledger entry is re-checked against the provider. Anything still present
+ *     is reported as a leak rather than being assumed gone.
+ */
+import { MODAL_MIN_CPU_CORES } from "./config.js";
+// --- published rates -------------------------------------------------------
+/**
+ * Modal's published per-second rates, read from <https://modal.com/pricing> on
+ * 2026-08-21.
+ *
+ * Note the two cards. Modal bills **Sandboxes at roughly 3× its own Functions**,
+ * and the pricing page presents both in one table, so quoting the Function rate
+ * for a sandbox workload understates it threefold. Only the Sandbox card is
+ * correct for this adapter; the Function card is kept solely so the ratio can
+ * be asserted in a test rather than restated as a comment.
+ *
+ * Provider pricing is time-unstable. Re-verify before these decide anything.
+ */
+export const MODAL_RATES = {
+    /** Sandbox/Notebook rate, USD per **physical core** per second. */
+    sandboxCpuCoreSecondUsd: 0.00003942,
+    /** Sandbox/Notebook rate, USD per GiB of memory per second. */
+    sandboxMemoryGiBSecondUsd: 0.00000667,
+    /** Ordinary Function rate, USD per physical core per second. */
+    functionCpuCoreSecondUsd: 0.0000131,
+    /** Ordinary Function rate, USD per GiB of memory per second. */
+    functionMemoryGiBSecondUsd: 0.00000222,
+    /** Volume storage, USD per GiB per month. Not charged per second. */
+    volumeStorageGiBMonthUsd: 0.09,
+    /** Modal counts one physical core as this many vCPU. */
+    vcpuPerPhysicalCore: 2,
+};
+/**
+ * Projected USD cost of one sandbox at Modal's **Sandbox** rate.
+ *
+ * Deliberately not clamped or rounded: a budget guard that quietly rounds a
+ * projection down is a budget guard that can be walked past.
+ */
+export function estimateModalSandboxCostUsd(input) {
+    requireCpuAtLeastFloor(input.cpuCores);
+    requireFinitePositive(input.memoryGiB, "memoryGiB");
+    requireFiniteNonNegative(input.seconds, "seconds");
+    return (input.cpuCores * MODAL_RATES.sandboxCpuCoreSecondUsd
+        + input.memoryGiB * MODAL_RATES.sandboxMemoryGiBSecondUsd) * input.seconds;
+}
+/** The same shape billed as an ordinary Function, for ratio reporting only. */
+export function estimateModalFunctionCostUsd(input) {
+    requireCpuAtLeastFloor(input.cpuCores);
+    requireFinitePositive(input.memoryGiB, "memoryGiB");
+    requireFiniteNonNegative(input.seconds, "seconds");
+    return (input.cpuCores * MODAL_RATES.functionCpuCoreSecondUsd
+        + input.memoryGiB * MODAL_RATES.functionMemoryGiBSecondUsd) * input.seconds;
+}
+/**
+ * A record of every sandbox this harness intended to create.
+ *
+ * "Intended" is the important word. Recording only successful creates would
+ * lose exactly the sandboxes most likely to leak: those whose create call
+ * timed out or was interrupted after the provider had already provisioned
+ * them. An entry is written before the attempt and updated after.
+ */
+export class ModalBenchLedger {
+    entries = [];
+    budgetUsd;
+    constructor(options) {
+        requireFinitePositive(options.budgetUsd, "budgetUsd");
+        this.budgetUsd = options.budgetUsd;
+    }
+    /** Total projected cost of everything recorded so far. */
+    committedUsd() {
+        return this.entries.reduce((sum, entry) => sum + entry.projectedCostUsd, 0);
+    }
+    remainingUsd() {
+        return this.budgetUsd - this.committedUsd();
+    }
+    /**
+     * Reserve budget and record intent. Throws *before* any provider call if the
+     * projection would breach the cap, so the guard cannot be raced by the
+     * create it is guarding.
+     */
+    recordIntent(label, projectedCostUsd) {
+        requireFiniteNonNegative(projectedCostUsd, "projectedCostUsd");
+        const wouldCommit = this.committedUsd() + projectedCostUsd;
+        if (wouldCommit > this.budgetUsd) {
+            throw new ModalBudgetExceededError({
+                budgetUsd: this.budgetUsd,
+                committedUsd: this.committedUsd(),
+                requestedUsd: projectedCostUsd,
+                label,
+            });
+        }
+        const entry = { label, state: "intended", projectedCostUsd };
+        this.entries.push(entry);
+        return entry;
+    }
+    all() {
+        return this.entries;
+    }
+    /** Entries that may still correspond to a live provider resource. */
+    outstanding() {
+        return this.entries.filter((entry) => entry.state !== "verified-gone"
+            && entry.state !== "create-failed");
+    }
+    leaked() {
+        return this.entries.filter((entry) => entry.state === "leaked");
+    }
+}
+/** A create was refused because it would breach the run's cost cap. */
+export class ModalBudgetExceededError extends Error {
+    budgetUsd;
+    committedUsd;
+    requestedUsd;
+    constructor(options) {
+        super(`Modal benchmark refused to create "${options.label}": projected $${options.requestedUsd.toFixed(6)} `
+            + `on top of $${options.committedUsd.toFixed(6)} would exceed the $${options.budgetUsd.toFixed(6)} cap`);
+        this.name = "ModalBudgetExceededError";
+        this.budgetUsd = options.budgetUsd;
+        this.committedUsd = options.committedUsd;
+        this.requestedUsd = options.requestedUsd;
+    }
+}
+/** Teardown finished with provider resources still present. */
+export class ModalLeakedSandboxError extends Error {
+    leaked;
+    constructor(leaked) {
+        super(`Modal benchmark leaked ${leaked.length} sandbox(es) that are still present after teardown: `
+            + leaked.map((entry) => `${entry.label}=${entry.sandboxId ?? "unknown-id"}`).join(", "));
+        this.name = "ModalLeakedSandboxError";
+        this.leaked = leaked;
+    }
+}
+/**
+ * Linear-interpolated percentile over a sorted copy of `values`.
+ *
+ * Returns `null` for an empty input rather than 0, because "no samples" and
+ * "zero milliseconds" are different claims and the second one is a lie.
+ */
+export function percentile(values, p) {
+    if (values.length === 0) {
+        return null;
+    }
+    if (!Number.isFinite(p) || p < 0 || p > 100) {
+        throw new Error(`percentile p must be within [0, 100]; got ${String(p)}`);
+    }
+    const sorted = [...values].sort((a, b) => a - b);
+    if (sorted.length === 1) {
+        return sorted[0];
+    }
+    const rank = (p / 100) * (sorted.length - 1);
+    const lower = Math.floor(rank);
+    const upper = Math.ceil(rank);
+    if (lower === upper) {
+        return sorted[lower];
+    }
+    return sorted[lower] + (sorted[upper] - sorted[lower]) * (rank - lower);
+}
+/**
+ * Run the benchmark.
+ *
+ * Cleanup is unconditional and verified. Even when the run aborts on the
+ * budget guard or a create throws, teardown still runs over everything the
+ * ledger recorded, and the returned report names anything that survived.
+ */
+export async function runModalBenchmark(runtime, options) {
+    // Reject a non-integer instead of silently truncating: a caller who passes
+    // `count: 2.7` almost certainly typed a wrong number, and running 2 without
+    // saying so buys a benchmark for a shape that was never requested.
+    if (!Number.isFinite(options.count)
+        || !Number.isInteger(options.count)
+        || options.count < 1) {
+        throw new Error(`Modal benchmark count must be a positive integer; got ${String(options.count)}`);
+    }
+    const count = options.count;
+    // A zero-lifetime projection reserves $0 in the ledger but still creates
+    // sandboxes with a positive provider lifetime, so the budget guard cannot
+    // stop the run before it bills. Guard here where the value crosses into the
+    // guard rather than deep in the estimator.
+    if (!Number.isFinite(options.projectedLifetimeSeconds)
+        || options.projectedLifetimeSeconds <= 0) {
+        throw new Error("Modal benchmark projectedLifetimeSeconds must be a finite, positive number of seconds "
+            + "(and should cover the runtime's configured maxLifetimeMs, because a leaked "
+            + `sandbox bills for its whole lifetime); got ${String(options.projectedLifetimeSeconds)}`);
+    }
+    const now = options.now ?? (() => Date.now());
+    const ledger = new ModalBenchLedger({ budgetUsd: options.budgetUsd });
+    const perSandboxUsd = estimateModalSandboxCostUsd({
+        cpuCores: options.shape.cpuCores,
+        memoryGiB: options.shape.memoryGiB,
+        seconds: options.projectedLifetimeSeconds,
+    });
+    const samples = [];
+    const labels = options.labels ?? {};
+    // Only sweep-by-label if the caller supplied labels *and* the runtime can
+    // list by them. Without both, a stray sandbox cannot be attributed to this
+    // run and the entry stays `create-failed` — the pre-existing shape.
+    const canReconcileByLabel = Object.keys(labels).length > 0
+        && typeof runtime.findAllByLabels === "function";
+    const acquire = async (index) => {
+        const label = `bench-${index}`;
+        // Budget check and ledger write happen together, before any provider call.
+        const entry = ledger.recordIntent(label, perSandboxUsd);
+        const startedAt = now();
+        let handle;
+        try {
+            handle = await runtime.launch({ name: label, labels });
+        }
+        catch (error) {
+            entry.error = errorMessage(error);
+            // Leave the entry `intended` when a label sweep can reconcile it:
+            // `launch` throwing does not prove the provider created nothing, and
+            // marking `create-failed` here would hide any sandbox that materialised
+            // after the client-side deadline fired. Teardown's sweep either
+            // reattaches the stray and destroys it, or promotes the entry to
+            // `create-failed` once absence has been checked.
+            if (!canReconcileByLabel) {
+                entry.state = "create-failed";
+            }
+            samples.push({ label, createMs: now() - startedAt, error: entry.error });
+            return;
+        }
+        const createMs = now() - startedAt;
+        entry.state = "created";
+        entry.sandboxId = handle.id;
+        let firstExecMs;
+        let execError;
+        if (options.measureFirstExec) {
+            const execStartedAt = now();
+            try {
+                const result = await runtime.runScript(handle, {
+                    command: options.firstExecCommand ?? "echo modal-bench-ready",
+                });
+                // A canary that exits nonzero is a failure, not a latency sample.
+                // Recording `firstExecMs` for a failed command would let the harness
+                // report a green measurement for a command that never worked.
+                if (result.exitCode === 0) {
+                    firstExecMs = now() - execStartedAt;
+                }
+                else {
+                    execError = `first exec exited with code ${String(result.exitCode ?? "unknown")}`;
+                }
+            }
+            catch (error) {
+                execError = errorMessage(error);
+            }
+        }
+        samples.push({
+            label,
+            createMs,
+            sandboxId: handle.id,
+            ...(firstExecMs === undefined ? {} : { firstExecMs }),
+            ...(execError === undefined ? {} : { error: execError }),
+        });
+    };
+    let abortError;
+    try {
+        if (options.concurrent) {
+            // `allSettled`, not `all`: one create failing must not skip teardown for
+            // the others, which would be exactly how a concurrency test leaks.
+            const results = await Promise.allSettled(Array.from({ length: count }, (_unused, index) => acquire(index)));
+            const rejected = results.find((result) => result.status === "rejected");
+            if (rejected && rejected.status === "rejected") {
+                abortError = rejected.reason;
+            }
+        }
+        else {
+            for (let index = 0; index < count; index += 1) {
+                await acquire(index);
+            }
+        }
+    }
+    catch (error) {
+        // A budget breach aborts the run but must never skip teardown.
+        abortError = error;
+    }
+    finally {
+        await teardown(runtime, ledger, labels);
+    }
+    const leaked = ledger.leaked();
+    const report = {
+        requested: count,
+        succeeded: samples.filter((sample) => sample.sandboxId !== undefined && !sample.error).length,
+        failed: samples.filter((sample) => sample.error !== undefined).length,
+        samples,
+        createMsP50: percentile(successfulCreates(samples), 50),
+        createMsP95: percentile(successfulCreates(samples), 95),
+        firstExecMsP50: percentile(firstExecs(samples), 50),
+        firstExecMsP95: percentile(firstExecs(samples), 95),
+        projectedCostUsd: ledger.committedUsd(),
+        ledger: ledger.all(),
+        leaked,
+    };
+    if (leaked.length > 0) {
+        // Loud by design. A silent leak on a metered provider is the one failure
+        // mode this harness exists to prevent.
+        throw Object.assign(new ModalLeakedSandboxError(leaked), { report });
+    }
+    if (abortError !== undefined) {
+        throw Object.assign(toError(abortError), { report });
+    }
+    return report;
+}
+/**
+ * Destroy everything the ledger knows about, then prove it is gone.
+ *
+ * Every entry is attempted even if an earlier one throws, because stopping at
+ * the first failure would strand the rest.
+ */
+async function teardown(runtime, ledger, labels) {
+    // Pass 1: destroy sandboxes we already have ids for.
+    for (const entry of ledger.outstanding()) {
+        if (entry.sandboxId === undefined) {
+            continue;
+        }
+        try {
+            await runtime.destroy({ id: entry.sandboxId });
+            entry.state = "destroyed";
+        }
+        catch (error) {
+            entry.state = "destroy-failed";
+            entry.error = errorMessage(error);
+        }
+    }
+    // Pass 2: reconcile launches that threw without returning a handle. A
+    // `launch` rejection does not prove the provider created nothing — a
+    // sandbox that landed just after the client-side deadline fired would
+    // otherwise leak invisibly. Sweep by the caller's labels, associate any
+    // stray with an outstanding no-id entry, and destroy it. This is why the
+    // acquire loop leaves such entries `intended` rather than `create-failed`.
+    const unaccounted = ledger.outstanding().filter((entry) => entry.sandboxId === undefined);
+    const canSweep = unaccounted.length > 0
+        && Object.keys(labels).length > 0
+        && typeof runtime.findAllByLabels === "function";
+    if (canSweep) {
+        const knownIds = new Set(ledger.all()
+            .map((entry) => entry.sandboxId)
+            .filter((id) => id !== undefined));
+        let strays = [];
+        try {
+            strays = (await runtime.findAllByLabels(labels))
+                .filter((handle) => !knownIds.has(handle.id));
+        }
+        catch (error) {
+            // A sweep failure is not fatal, but it does mean any remaining no-id
+            // entries have to fall through as unverified — see below.
+            for (const entry of unaccounted) {
+                entry.error = errorMessage(error);
+            }
+        }
+        for (const entry of unaccounted) {
+            const match = strays.shift();
+            if (match === undefined) {
+                // Sweep ran and no matching stray exists: this create truly failed.
+                entry.state = "create-failed";
+                entry.error ??= "create rejected and no stray sandbox was found by label sweep";
+                continue;
+            }
+            entry.sandboxId = match.id;
+            try {
+                await runtime.destroy(match);
+                entry.state = "destroyed";
+            }
+            catch (error) {
+                entry.state = "destroy-failed";
+                entry.error = errorMessage(error);
+            }
+        }
+    }
+    else {
+        for (const entry of unaccounted) {
+            entry.state = "leaked";
+            entry.error ??= "create outcome unknown: no sandbox id was ever observed "
+                + "and no label sweep was possible";
+        }
+    }
+    // Pass 3: verify. `destroy` returning is not proof; a re-lookup reporting
+    // absence is.
+    for (const entry of ledger.outstanding()) {
+        if (entry.sandboxId === undefined) {
+            continue;
+        }
+        if (typeof runtime.getById !== "function") {
+            // Without reattach there is no way to prove absence, so it is not
+            // claimed. The entry stays outstanding rather than being upgraded.
+            continue;
+        }
+        try {
+            const found = await runtime.getById(entry.sandboxId);
+            entry.state = found === null ? "verified-gone" : "leaked";
+        }
+        catch (error) {
+            entry.state = "leaked";
+            entry.error = errorMessage(error);
+        }
+    }
+}
+// --- helpers ---------------------------------------------------------------
+function successfulCreates(samples) {
+    return samples.filter((s) => s.sandboxId !== undefined).map((s) => s.createMs);
+}
+function firstExecs(samples) {
+    return samples
+        .map((s) => s.firstExecMs)
+        .filter((value) => value !== undefined);
+}
+function errorMessage(error) {
+    return error instanceof Error ? error.message : String(error);
+}
+function toError(error) {
+    return error instanceof Error ? error : new Error(String(error));
+}
+function requireFinitePositive(value, field) {
+    if (!Number.isFinite(value) || value <= 0) {
+        throw new Error(`Modal benchmark ${field} must be a finite, positive number; got ${String(value)}`);
+    }
+}
+function requireFiniteNonNegative(value, field) {
+    if (!Number.isFinite(value) || value < 0) {
+        throw new Error(`Modal benchmark ${field} must be a finite, non-negative number; got ${String(value)}`);
+    }
+}
+/**
+ * Modal charges as if the reservation were at least its per-container floor.
+ * Accepting a below-floor CPU value in the estimator would understate spend
+ * and let the budget guard be walked past.
+ */
+function requireCpuAtLeastFloor(cpuCores) {
+    if (!Number.isFinite(cpuCores) || cpuCores < MODAL_MIN_CPU_CORES) {
+        throw new Error(`Modal benchmark cpuCores must be a finite number >= ${MODAL_MIN_CPU_CORES} `
+            + `physical cores (Modal's per-container floor); got ${String(cpuCores)}`);
+    }
+}
+//# sourceMappingURL=bench.js.map

package/dist/modal/bench.js.map

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

package/dist/modal/capabilities.d.ts

@@ -0,0 +1,180 @@
+/**
+ * SDK-free capability metadata for the Modal adapter.
+ *
+ * House rule: a behavioral claim stays `false` until a live probe against the
+ * pinned SDK establishes it. "The SDK has a method for it" is not evidence —
+ * a method can exist and degrade, and a capability means *reachable through
+ * this package's port*, not *present in the vendor surface*.
+ */
+export declare const modalSandboxCapabilities: {
+    /**
+     * Modal genuinely has server-side label search: `sandboxes.list({ tags })`
+     * returns only sandboxes carrying all the given tags, and the adapter routes
+     * every lookup through it. That is a real warm-lease implementation, unlike
+     * providers where `findAllByLabels` degrades to `[]`.
+     *
+     * It is nevertheless declared `false` until the live canary proves that a
+     * tagged sandbox is actually returned by a tag-filtered list. Promoting it
+     * on the strength of a type signature is exactly the inference this field
+     * exists to prevent, and `false` fails in the safe direction: the
+     * orchestrator declines to rely on warm leases rather than leaking them.
+     */
+    readonly warmLease: false;
+    /**
+     * Permanently false, and not pending verification.
+     *
+     * Modal exposes no stop/start for a Sandbox. `terminate()` is the only
+     * lifecycle transition and it is terminal — there is no suspend, resume, or
+     * wake. The adapter therefore omits `start`/`stop` entirely rather than
+     * shipping no-ops, and this flag records the structural fact for the
+     * capability resolver, which cannot see an absent method.
+     */
+    readonly lifecycle: false;
+};
+/**
+ * Bootstrap-plane capabilities. Note this is `RuntimeCapabilities` from
+ * `../types.js` — the live in-sandbox plane — and NOT the orchestration-plane
+ * `SandboxRuntimeCapabilities`. The two are deliberately distinct.
+ */
+export declare const modalWorkflowCapabilities: {
+    /**
+     * Modal supports PTY on both `create` and `exec` (`pty: true`, which
+     * multiplexes stderr into stdout). This package's port exposes no PTY
+     * operation, so it is not reachable here.
+     */
+    readonly pty: false;
+    /**
+     * Modal exposes real filesystem snapshots — `snapshotFilesystem()` and
+     * `snapshotDirectory(path)`, both returning an `Image` reusable as a create
+     * source (30-day default TTL, `ttlMs: null` to retain indefinitely). This
+     * package's port exposes no snapshot operation, so the capability is not
+     * reachable through it. Documented here so the surface is not lost.
+     */
+    readonly snapshots: false;
+    /** Modal Sandboxes are gVisor-isolated containers with their own filesystem. */
+    readonly isolation: "strong";
+    /** A sandbox id survives the client: `sandboxes.fromId(id)` re-resolves it. */
+    readonly persistentHandle: true;
+    /**
+     * `exec()` returns live `stdout`/`stderr` as `ReadableStream`s, so Modal can
+     * genuinely stream. The adapter drains them to completion to satisfy the
+     * port's buffered `RunScriptResult`, and the port exposes no streaming
+     * surface, so this is false *for this port* while true of the provider.
+     */
+    readonly streamingLogs: false;
+};
+/**
+ * Cells proven by a live run against Modal. Everything starts `false` and is
+ * promoted only by an observation recorded in the adapter's docs, never by
+ * reading the SDK's types.
+ */
+export type ModalObservedCapabilities = {
+    /** A terminated sandbox verifiably left the account, checked by re-lookup. */
+    cleanupVerified: boolean;
+    /** `snapshotFilesystem` produced an Image that booted a new sandbox. */
+    snapshotCapture: boolean;
+    /** Tag-filtered `list()` returned a sandbox we tagged at create. */
+    warmLease: boolean;
+    /** `fromId` re-resolved a sandbox created by a different client instance. */
+    reattach: boolean;
+    /** stop -> settled -> start -> exec succeeded. Structurally impossible on Modal. */
+    lifecycle: boolean;
+    /**
+     * A sandbox can be kept alive indefinitely with no termination deadline.
+     *
+     * Structurally false on Modal, like {@link lifecycle}, and for the same kind
+     * of reason: *every* Modal Sandbox carries a maximum lifetime. It defaults to
+     * five minutes, it can be raised only as far as 24 hours, and the provider
+     * terminates the sandbox when it elapses. There is no "no deadline" setting.
+     * Past 24 hours Modal's own guidance is to snapshot the filesystem and
+     * restore it into a *new* sandbox, which is a rebuild rather than a
+     * continuation. No live run can promote this.
+     */
+    neverIdle: boolean;
+    /** A sandbox outlived Modal's 5-minute default because we set maxLifetimeMs. */
+    lifetimeOverride: boolean;
+    /** Concurrent creates all reached ready without provider-side throttling. */
+    concurrencyCeiling: boolean;
+};
+/** Nothing promoted yet: no live run has happened. Awaiting credentials. */
+export declare const modalObservedCapabilities: ModalObservedCapabilities;
+/**
+ * Cells that are **settled structural facts**, not pending observations.
+ *
+ * The distinction matters for review: everything else in
+ * {@link modalObservedCapabilities} is `false` only because no live run has
+ * happened yet and will flip when one does. These two are `false` because the
+ * provider cannot do the thing at all, so a future canary must not "promote"
+ * them and a future reader must not try to "fix" them.
+ */
+export declare const MODAL_STRUCTURALLY_FALSE: readonly ["lifecycle", "neverIdle"];
+/**
+ * Structured capability modes for the Modal adapter.
+ *
+ * Every cell below restates, in the type system, something this file already
+ * documented in prose. That is the whole reason to fill them in: the booleans
+ * above cannot distinguish "Modal cannot do this" from "Modal can, but our port
+ * exposes no operation reaching it" from "nobody has checked yet", and this
+ * adapter is the one that had to work around that by hand — see
+ * {@link MODAL_STRUCTURALLY_FALSE}.
+ *
+ * Note what is deliberately *not* here: `warmLease` stays a `false` boolean
+ * pending the live canary. Modes describe the shape of a capability, not its
+ * verification state, so a mode is not a back door for promoting a cell that
+ * the house rule keeps unproven.
+ */
+export declare const modalCapabilityModes: {
+    /**
+     * `buffered`, not `separate-streams`.
+     *
+     * Modal's `exec()` does return live `stdout`/`stderr` as separate
+     * `ReadableStream`s, and `runScript` does hand back separated `stdout` and
+     * `stderr` fields. But both streaming members of the union require output to
+     * be *streamed live*, and the adapter drains both pipes to completion with
+     * `readText()` before it returns anything. Separated-after-the-fact is still
+     * buffered. Declaring `separate-streams` would promise callers an incremental
+     * channel this port does not have.
+     */
+    readonly outputStreams: "buffered";
+    /**
+     * Anything written is lost when the sandbox goes away, and on Modal it always
+     * goes away: `terminate()` is the only lifecycle transition and it is
+     * terminal. There is no stop/start pair for state to survive across, so
+     * `persistent` cannot apply.
+     */
+    readonly filesystem: "ephemeral";
+    /**
+     * The structural fact behind `neverIdle: false` in
+     * {@link MODAL_STRUCTURALLY_FALSE}, now stated in the type rather than in a
+     * hand-maintained list. *Every* Modal Sandbox carries a maximum lifetime —
+     * five minutes by default, 24 hours at the ceiling (`MODAL_MAX_LIFETIME_MS`),
+     * and the provider terminates it when that elapses. There is no "no deadline"
+     * setting, so no live run can ever move this.
+     *
+     * `deadline` says that on its own; per the union's own note, a provider that
+     * always terminates at a deadline cannot offer a never-idle tier, so this
+     * needs no separate `unsupported`.
+     */
+    readonly lifetime: "deadline";
+    /**
+     * `not-exposed`, emphatically not `unsupported`: Modal supports PTY on both
+     * `create` and `exec` (`pty: true`). This package's port declares no PTY
+     * operation, so it is unreachable *here*. It moves if someone adds one — and
+     * `isPendingEvidence()` correctly reports false for it, because no canary
+     * against Modal can change a fact about our own port surface.
+     */
+    readonly interactive: "not-exposed";
+    /**
+     * Also `not-exposed`. Modal has real filesystem snapshots —
+     * `snapshotFilesystem()` and `snapshotDirectory(path)`, both returning an
+     * `Image` reusable as a create source. The port exposes no snapshot
+     * operation, so the capability is not reachable through it.
+     *
+     * This is exactly the cell the absence vocabulary was added to protect:
+     * `modalObservedCapabilities.snapshotCapture` is a *pending* observation
+     * about the provider, while this is a *settled* fact about our port. A canary
+     * may promote that one; it must never promote this one.
+     */
+    readonly snapshots: "not-exposed";
+};
+//# sourceMappingURL=capabilities.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"capabilities.d.ts","sourceRoot":"","sources":["../../src/modal/capabilities.ts"],"names":[],"mappings":"AAMA;;;;;;;GAOG;AACH,eAAO,MAAM,wBAAwB;IACnC;;;;;;;;;;;OAWG;;IAEH;;;;;;;;OAQG;;CAEkD,CAAC;AAExD;;;;GAIG;AACH,eAAO,MAAM,yBAAyB;IACpC;;;;OAIG;;IAEH;;;;;;OAMG;;IAEH,gFAAgF;;IAEhF,+EAA+E;;IAE/E;;;;;OAKG;;CAEmC,CAAC;AAEzC;;;;GAIG;AACH,MAAM,MAAM,yBAAyB,GAAG;IACtC,8EAA8E;IAC9E,eAAe,EAAE,OAAO,CAAC;IACzB,wEAAwE;IACxE,eAAe,EAAE,OAAO,CAAC;IACzB,oEAAoE;IACpE,SAAS,EAAE,OAAO,CAAC;IACnB,6EAA6E;IAC7E,QAAQ,EAAE,OAAO,CAAC;IAClB,oFAAoF;IACpF,SAAS,EAAE,OAAO,CAAC;IACnB;;;;;;;;;;OAUG;IACH,SAAS,EAAE,OAAO,CAAC;IACnB,gFAAgF;IAChF,gBAAgB,EAAE,OAAO,CAAC;IAC1B,6EAA6E;IAC7E,kBAAkB,EAAE,OAAO,CAAC;CAC7B,CAAC;AAEF,4EAA4E;AAC5E,eAAO,MAAM,yBAAyB,EAAE,yBASvC,CAAC;AAEF;;;;;;;;GAQG;AACH,eAAO,MAAM,wBAAwB,qCAG8B,CAAC;AAEpE;;;;;;;;;;;;;;GAcG;AACH,eAAO,MAAM,oBAAoB;IAC/B;;;;;;;;;;OAUG;;IAEH;;;;;OAKG;;IAEH;;;;;;;;;;;OAWG;;IAEH;;;;;;OAMG;;IAEH;;;;;;;;;;OAUG;;CAEsC,CAAC"}