@agent-relay/sandbox 0.1.2 → 0.1.3

package/dist/agent37/runtime.js

@@ -0,0 +1,855 @@
+import { Buffer } from "node:buffer";
+import { writeFile } from "node:fs/promises";
+import { Agent37ApiError, Agent37Client } from "./client.js";
+/**
+ * The provider's hard ceiling on a single command, in milliseconds. Every
+ * command is bounded by this whether the caller asks for it or not, which is
+ * what makes a `timeoutMs` of at least this value honestly satisfiable.
+ */
+export const AGENT37_COMMAND_CAP_MS = 280_000;
+/** Raised when `env` would be rejected by the provider's own create validation. */
+export class Agent37EnvValidationError extends Error {
+    constructor(message) {
+        super(message);
+        this.name = "Agent37EnvValidationError";
+    }
+}
+/**
+ * Raised when start / stop / destroy is handed an instance this runtime knows
+ * nothing about.
+ *
+ * Ownership here is *caller-declared attachment*, not in-process provenance:
+ * `launch` owns what it creates, and `getById` / `findAllByLabels` attach as
+ * unowned unless the caller passes `owned: true`. An instance that was never
+ * resolved through any of those is refused outright rather than mutated on a
+ * guess.
+ *
+ * This is deliberately louder than the Daytona adapter, which silently returns
+ * for an unregistered handle. A destroy that quietly does nothing reads to the
+ * caller as a completed teardown that never happened, which is the more
+ * expensive of the two failure modes.
+ */
+export class Agent37ForeignHandleError extends Error {
+    constructor(id, operation) {
+        super(`Agent37 refused to ${operation} instance "${id}": this runtime has no ` +
+            "registration for it. Resolve it with getById(id, { owned: true }) to " +
+            "declare ownership before mutating or destroying it.");
+        this.name = "Agent37ForeignHandleError";
+    }
+}
+/**
+ * Raised when a command completes but the provider's reply carries no
+ * `exit_code`, so its outcome is unknown.
+ *
+ * `runScript` reports this as `exitCode: null`, which the port models. `exec`
+ * cannot: `ExecResult.exitCode` is a number, and the only numbers available are
+ * lies — `0` would report a command that may have failed as a success.
+ */
+export class Agent37UnknownExitCodeError extends Error {
+    output;
+    constructor(id, output) {
+        super(`Agent37 exec on instance "${id}" returned no exit_code, so the command's ` +
+            "outcome is unknown; refusing to report it as success");
+        this.name = "Agent37UnknownExitCodeError";
+        this.output = output;
+    }
+}
+/**
+ * Raised when a caller asks for a command lifetime Agent37 cannot enforce.
+ *
+ * `timeoutMs` on the port means the command is no longer running once it
+ * elapses. Agent37's `exec` accepts no timeout, and aborting the HTTP request
+ * only abandons the response — the command keeps running inside the instance.
+ * The single lifetime bound Agent37 genuinely enforces is its own
+ * {@link AGENT37_COMMAND_CAP_MS} cap, so anything shorter is refused instead of
+ * being faked with an `AbortSignal`.
+ *
+ * Callers that want to stop *waiting* (as opposed to stopping the command) want
+ * `requestTimeoutMs`, which is named for what it actually does.
+ */
+export class Agent37CommandTimeoutUnsupportedError extends Error {
+    constructor(timeoutMs) {
+        super(`Agent37 cannot enforce a ${timeoutMs}ms command timeout: exec takes no ` +
+            `timeout, and aborting the request leaves the command running. The only ` +
+            `lifetime bound is the provider's own ${AGENT37_COMMAND_CAP_MS}ms cap, so ` +
+            `timeoutMs must be at least that. To bound how long this client waits ` +
+            `— which does not stop the command — use requestTimeoutMs instead.`);
+        this.name = "Agent37CommandTimeoutUnsupportedError";
+    }
+}
+/**
+ * Raised when a 2xx reply does not carry the shape the endpoint documents.
+ *
+ * The alternative is worse than an error, because a tolerant decode turns a
+ * broken response into a *confident negative*: `GET /v1/instances` answering
+ * with HTML from a proxy would read as "no instance matches these labels",
+ * which is the exact answer that makes a caller abandon a running warm lease
+ * and pay to launch a replacement. Similarly, a create reply with no `id`
+ * would register ownership under `undefined` and aim a later DELETE at a
+ * garbage path.
+ *
+ * So the adapter fails closed: an unusable reply is reported as unusable, and
+ * the caller retries or escalates instead of acting on a fiction. Only `id` and
+ * `status` are required to be non-empty strings — an *unrecognized* status is
+ * forward compatibility, not corruption, and {@link normalizeStatus} already
+ * treats anything but `running` as not ready.
+ */
+export class Agent37MalformedResponseError extends Error {
+    /** Method and path only, matching {@link Agent37ApiError.request}. */
+    request;
+    constructor(request, detail) {
+        super(`Agent37 ${request} returned a malformed 2xx response: ${detail}`);
+        this.name = "Agent37MalformedResponseError";
+        this.request = request;
+    }
+}
+/**
+ * Raised when a caller asks `launch` to bound how long instance creation may
+ * take.
+ *
+ * HOLD — not implementable against the documented contract. `POST
+ * /v1/instances` is synchronous: it returns 201 only once the instance reports
+ * `running`. Abandoning that request client-side does not un-allocate anything
+ * the provider has already started building, and the reply that would have
+ * carried the new instance's `id` is discarded with it. The result is an
+ * orphan the caller cannot name, let alone delete — a billed leak dressed up
+ * as a timeout.
+ *
+ * Cleaning up afterwards would need one of three things the API does not
+ * document: an idempotency key to correlate a retry with the original create,
+ * a create call that returns an id before the instance is ready, or a
+ * guarantee about whether a still-provisioning instance appears in `GET
+ * /v1/instances` (and carries the `metadata` it was created with) so a bounded
+ * sweep could identify exactly the one that was abandoned. Sweeping on labels
+ * alone is not a substitute: labels are reused precisely so warm leases can be
+ * found by them, so a sweep could delete a healthy instance belonging to
+ * someone else.
+ *
+ * Verifying any of that needs live calls against the provider, which this work
+ * is not authorized to make. Until it is verified, the option is refused rather
+ * than shipped as an `AbortSignal` that reads like a cancellation and is not
+ * one.
+ *
+ * The refusal is purely a runtime one, and deliberately so. `createTimeoutSeconds`
+ * lives on the shared `LaunchOptions` and on `SandboxRuntime.launch` because
+ * other providers honour it, so it typechecks against this adapter too and no
+ * compile error is available to lean on. Narrowing this one signature would not
+ * change that — TypeScript compares method parameters bivariantly, so a caller
+ * holding a `SandboxRuntime` reference could still pass the option — and it
+ * would trade a real guarantee for the appearance of one while breaking the
+ * substitutability the port exists to provide.
+ *
+ * Callers that need a bound should launch with labels unique to the attempt,
+ * apply their own deadline around `launch`, and reconcile with
+ * `findAllByLabels(..., { owned: true })` — a recovery they can reason about,
+ * because they chose the labels.
+ */
+export class Agent37CreateTimeoutUnsupportedError extends Error {
+    constructor() {
+        super("Agent37 cannot bound instance creation: POST /v1/instances returns only " +
+            "once the instance is running, and aborting that request neither stops " +
+            "the allocation nor yields the id needed to delete it, so the timeout " +
+            "would leak a billed orphan. The API documents no idempotency key and no " +
+            "way to identify an abandoned create, so no cleanup is possible either. " +
+            "Apply your own deadline around launch(), using labels unique to the " +
+            "attempt, and reconcile with findAllByLabels(labels, { owned: true }).");
+        this.name = "Agent37CreateTimeoutUnsupportedError";
+    }
+}
+// The provider documents `env` as at most 32 entries, keys of uppercase
+// letters, digits, and underscores starting with a letter, values up to 4096
+// characters. Checking locally turns a 400 after a round trip into an
+// immediate, specific error — and, more importantly, keeps a malformed key
+// from ever being interpolated into a shell.
+const ENV_MAX_ENTRIES = 32;
+const ENV_MAX_VALUE_LENGTH = 4096;
+const ENV_KEY_RE = /^[A-Za-z][A-Za-z0-9_]*$/;
+const DEFAULT_EXEC_UPLOAD_MAX_BYTES = 262_144; // 256 KiB
+export class Agent37Runtime {
+    id = "agent37";
+    /**
+     * Bootstrap-plane capabilities (the live in-sandbox session), distinct from
+     * `SandboxRuntimeCapabilities`.
+     *
+     * `pty: false` and `streamingLogs: false` are facts, not caution: `exec` is a
+     * single buffered request/response with no TTY, and the one log endpoint
+     * (`GET /v1/instances/{id}/logs`) returns a snapshot with a `tail` count, not
+     * a stream. `snapshots: false` likewise — templates are built from a
+     * Dockerfile ahead of time; there is no documented call that captures a
+     * running instance as a reusable image.
+     */
+    capabilities = {
+        pty: false,
+        snapshots: false,
+        isolation: "strong",
+        persistentHandle: true,
+        streamingLogs: false,
+    };
+    /**
+     * `lifecycle: true` because `start` and `stop` are real hosting-plane calls
+     * that change `status`, not the no-ops some providers ship.
+     *
+     * `warmLease: true` because label lookup returns real matches. `GET
+     * /v1/instances` documents no server-side filter, so the filtering happens
+     * here — but it happens over a complete, unpaginated list, which makes an
+     * empty result mean "no match" and nothing else. That is the ambiguity the
+     * capability exists to rule out, and it is ruled out.
+     *
+     * `asyncExec` is not declared here; it is derived from method presence by
+     * `resolveSandboxRuntimeCapabilities`. Async exec is absent from this adapter
+     * because nohup+/tmp emulation cannot provide durable, idempotent guarantees.
+     */
+    declaredCapabilities = { warmLease: true, lifecycle: true };
+    client;
+    defaultHomeDir;
+    template;
+    resources;
+    instanceType;
+    budget;
+    autoSleep;
+    idleTimeoutSeconds;
+    publicPorts;
+    user;
+    execUploadMaxBytes;
+    // An instance's own origin is only knowable from its instance object. Cache
+    // what has been seen so the file plane does not re-GET on every transfer.
+    instanceUrls = new Map();
+    // What this runtime has been told about each instance it has resolved:
+    // `true` for one it launched or that the caller explicitly claimed, `false`
+    // for a plain attachment. Absent means "never seen", which is refused rather
+    // than mutated. Deliberately not a provenance set — a process that crashed
+    // and restarted launched nothing, yet must still be able to delete its own
+    // instances, which it does by resolving them with `owned: true`.
+    ownership = new Map();
+    constructor(options) {
+        if (!options.defaultHomeDir?.trim()) {
+            throw new Error("Agent37Runtime requires an explicit defaultHomeDir: it is template-specific");
+        }
+        this.client = options.client ?? new Agent37Client(toClientOptions(options));
+        this.defaultHomeDir = options.defaultHomeDir.trim();
+        if (options.template !== undefined) {
+            this.template = options.template;
+        }
+        if (options.resources !== undefined) {
+            this.resources = options.resources;
+        }
+        if (options.type !== undefined) {
+            this.instanceType = options.type;
+        }
+        if (options.budget !== undefined) {
+            this.budget = options.budget;
+        }
+        if (options.autoSleep !== undefined) {
+            this.autoSleep = options.autoSleep;
+        }
+        if (options.idleTimeoutSeconds !== undefined) {
+            this.idleTimeoutSeconds = options.idleTimeoutSeconds;
+        }
+        if (options.publicPorts !== undefined) {
+            this.publicPorts = options.publicPorts;
+        }
+        if (options.user !== undefined) {
+            this.user = options.user;
+        }
+        this.execUploadMaxBytes = options.execUploadMaxBytes ?? DEFAULT_EXEC_UPLOAD_MAX_BYTES;
+    }
+    // --- discovery ----------------------------------------------------------
+    async findByLabels(labels, options = {}) {
+        const excluded = new Set(options.excludeIds ?? []);
+        const handles = await this.findAllByLabels(labels, options);
+        return handles.find((handle) => !excluded.has(handle.id)) ?? null;
+    }
+    async findAllByLabels(labels, options = {}) {
+        const states = options.states === undefined ? ["STARTED"] : options.states;
+        const limit = options.limit ?? options.pageSize;
+        // A non-positive cap means "zero handles wanted": the post-push break at
+        // the loop tail runs one iteration late, so limit:0 leaked one handle. Fold
+        // that into the pre-fetch short circuit — no lookup, no ownership claim.
+        if (limit !== undefined && limit <= 0) {
+            return [];
+        }
+        const excluded = new Set(options.excludeIds ?? []);
+        const instances = await this.listInstances(options.timeoutMs);
+        const handles = [];
+        for (const instance of instances) {
+            if (excluded.has(instance.id)) {
+                continue;
+            }
+            if (!matchesLabels(instance, labels)) {
+                continue;
+            }
+            if (!matchesState(instance.status, states)) {
+                continue;
+            }
+            this.declareOwnership(instance.id, options.owned === true);
+            handles.push(this.registerInstance(instance));
+            if (limit !== undefined && handles.length >= limit) {
+                break;
+            }
+        }
+        return handles;
+    }
+    async countByLabels(labels, options = {}) {
+        const maxCount = options.maxCount === undefined
+            ? Number.POSITIVE_INFINITY
+            : Math.max(0, Math.floor(options.maxCount));
+        if (maxCount === 0) {
+            return 0;
+        }
+        const lookup = {
+            ...(options.states === undefined ? {} : { states: options.states }),
+            ...(options.timeoutMs === undefined ? {} : { timeoutMs: options.timeoutMs }),
+            ...(Number.isFinite(maxCount) ? { limit: maxCount } : {}),
+        };
+        const handles = await this.findAllByLabels(labels, lookup);
+        return handles.length;
+    }
+    async getById(id, options = {}) {
+        const instance = await this.fetchInstance(id);
+        if (!instance) {
+            return null;
+        }
+        // `states: undefined` means "no filter" on reattach: a caller resolving a
+        // known id wants the instance whatever state it is in, so it can decide
+        // whether to start it. That is the opposite of the label search default,
+        // which is looking for something ready to use right now.
+        const states = options.states === undefined ? null : options.states;
+        if (!matchesState(instance.status, states)) {
+            return null;
+        }
+        // `owned: true` is the caller asserting this instance is theirs — the one
+        // way a restarted process reacquires the right to tear down what a previous
+        // run created.
+        this.declareOwnership(id, options.owned === true);
+        const handle = this.registerInstance(instance);
+        return {
+            ...handle,
+            ...(options.homeDir ? { homeDir: options.homeDir } : {}),
+            ...(options.workdir ? { workdir: options.workdir } : {}),
+        };
+    }
+    // --- lifecycle ----------------------------------------------------------
+    async launch(options = {}) {
+        // Refused before anything is sent. This is the *only* line that stops the
+        // option, because it is part of the shared cross-provider `LaunchOptions`
+        // and so typechecks against `launch` and against the `SandboxRuntime`
+        // interface alike. Silently dropping it would leave a caller that had
+        // configured a creation bound believing it was in force.
+        if (options.createTimeoutSeconds !== undefined) {
+            throw new Agent37CreateTimeoutUnsupportedError();
+        }
+        const env = options.env;
+        if (env) {
+            assertValidEnv(env);
+        }
+        // The singular `label` from LaunchOptions populates a "label" metadata key.
+        // Explicit `labels` entries merge on top and take precedence if both are provided.
+        const rawMetadata = {};
+        if (options.label !== undefined) {
+            rawMetadata["label"] = options.label;
+        }
+        if (options.labels) {
+            Object.assign(rawMetadata, options.labels);
+        }
+        // Reap-ephemeral contract (see LaunchOptions docs and
+        // scripts/reap-ephemeral.ts). Persisted under reserved metadata keys so the
+        // out-of-process reaper can identify safe-to-reap leaks after a caller
+        // crash. Written LAST so caller labels cannot shadow them.
+        if (options.attributionTag !== undefined) {
+            rawMetadata["_sandbox.attributionTag"] = options.attributionTag;
+        }
+        if (options.ephemeralUntil !== undefined) {
+            rawMetadata["_sandbox.ephemeralUntil"] = String(typeof options.ephemeralUntil === "number"
+                ? options.ephemeralUntil
+                : Date.parse(options.ephemeralUntil));
+        }
+        const metadata = Object.keys(rawMetadata).length > 0 ? rawMetadata : undefined;
+        const body = {
+            ...(this.template === undefined ? {} : { template: this.template }),
+            ...(this.resources === undefined ? {} : { resources: this.resources }),
+            ...(this.instanceType === undefined ? {} : { type: this.instanceType }),
+            ...(this.budget === undefined ? {} : { budget: this.budget }),
+            ...(this.autoSleep === undefined ? {} : { auto_sleep: this.autoSleep }),
+            ...(this.idleTimeoutSeconds === undefined
+                ? {}
+                : { idle_timeout_seconds: this.idleTimeoutSeconds }),
+            ...(this.publicPorts === undefined ? {} : { public_ports: this.publicPorts }),
+            ...(this.user === undefined ? {} : { user: this.user }),
+            ...(options.name === undefined ? {} : { name: options.name }),
+            ...(metadata ? { metadata } : {}),
+            ...(env && Object.keys(env).length > 0 ? { env } : {}),
+        };
+        const payload = await this.client.hosting("POST", "/v1/instances", { body });
+        // Validated before the id is recorded. Registering ownership off an
+        // unusable reply would key it on `undefined` and aim a later DELETE at
+        // `/v1/instances/undefined`.
+        const instance = parseInstance(payload, "POST /v1/instances");
+        this.declareOwnership(instance.id, true);
+        const handle = this.registerInstance(instance);
+        return {
+            ...handle,
+            homeDir: this.defaultHomeDir,
+            ...(options.workdir ? { workdir: options.workdir } : {}),
+        };
+    }
+    async start(handle) {
+        if (!this.requireOwnership(handle.id, "start")) {
+            // Attached, not owned: the instance's lifecycle belongs to whoever does
+            // own it. Returning the handle unchanged is honest; claiming STARTED
+            // would not be.
+            return handle;
+        }
+        const request = `POST /v1/instances/${handle.id}/start`;
+        const ack = await this.client.hosting("POST", `/v1/instances/${encodeURIComponent(handle.id)}/start`);
+        // An ack with no status must not be normalized: `normalizeStatus(undefined)`
+        // is STOPPED, which would report a successful start as a failed one.
+        const status = readNonBlankString(ack, "status");
+        if (status === null) {
+            throw new Agent37MalformedResponseError(request, "no `status` on the start acknowledgement");
+        }
+        return { ...handle, state: normalizeStatus(status) };
+    }
+    async stop(handle) {
+        if (!this.requireOwnership(handle.id, "stop")) {
+            return;
+        }
+        await this.client.hosting("POST", `/v1/instances/${encodeURIComponent(handle.id)}/stop`);
+    }
+    async destroy(handle) {
+        if (!this.requireOwnership(handle.id, "destroy")) {
+            // Destroying an attachment releases this runtime's reference to it and
+            // nothing else. The instance is caller-managed, so deleting it here would
+            // be destroying someone else's sandbox.
+            this.forget(handle.id);
+            return;
+        }
+        try {
+            await this.client.hosting("DELETE", `/v1/instances/${encodeURIComponent(handle.id)}`);
+        }
+        catch (error) {
+            // Delete acts once: a repeat returns 404. An already-gone instance is
+            // the caller's desired end state, so absorb it rather than making every
+            // teardown path handle a race it cannot prevent.
+            if (isNotFound(error)) {
+                this.forget(handle.id);
+                return;
+            }
+            // Order matters: the registration is dropped only on a terminal outcome.
+            // Forgetting first would strip ownership from a handle whose delete has
+            // not happened yet, leaving the caller unable to retry its own teardown.
+            throw error;
+        }
+        this.forget(handle.id);
+    }
+    // --- execution ----------------------------------------------------------
+    async exec(handle, command, options = {}) {
+        const result = await this.runScript(handle, {
+            command,
+            ...(options.cwd === undefined ? {} : { cwd: options.cwd }),
+            ...(options.env === undefined ? {} : { env: options.env }),
+            ...(options.timeoutMs === undefined ? {} : { timeoutMs: options.timeoutMs }),
+            ...(options.requestTimeoutMs === undefined
+                ? {}
+                : { requestTimeoutMs: options.requestTimeoutMs }),
+        });
+        if (result.exitCode === null) {
+            throw new Agent37UnknownExitCodeError(handle.id, result.output);
+        }
+        return {
+            output: result.output,
+            exitCode: result.exitCode,
+            ...(result.truncated === true ? { truncated: true } : {}),
+        };
+    }
+    async runScript(handle, options) {
+        assertHonourableCommandTimeout(options.timeoutMs);
+        if (options.env) {
+            assertValidEnv(options.env);
+        }
+        const cwd = options.cwd ?? handle.workdir;
+        const script = composeScript(options.command, {
+            ...(cwd ? { cwd } : {}),
+            ...(options.env ? { env: options.env } : {}),
+        });
+        // Only `requestTimeoutMs` becomes an abort signal. `timeoutMs` is a command
+        // lifetime, and it got here only because the provider's own cap already
+        // satisfies it — turning it into an HTTP abort would abandon the response
+        // while the command ran on.
+        const result = await this.execRaw(handle.id, script, options.requestTimeoutMs);
+        return {
+            output: combineOutput(result.stdout, result.stderr),
+            ...(result.stdout ? { stdout: result.stdout } : {}),
+            ...(result.stderr ? { stderr: result.stderr } : {}),
+            exitCode: result.exit_code,
+            ...(result.truncated === true ? { truncated: true } : {}),
+        };
+    }
+    // --- files --------------------------------------------------------------
+    async uploadBundle(handle, options) {
+        for (const file of options.files) {
+            await this.uploadFile(handle, file.source, file.destination);
+        }
+    }
+    async uploadFile(handle, source, destination) {
+        const bytes = typeof source === "string" ? Buffer.from(source, "utf8") : source;
+        const instanceUrl = await this.resolveInstanceUrl(handle.id);
+        if (instanceUrl) {
+            await this.client.instance(instanceUrl, "PUT", "/v1/files/content", {
+                query: { path: destination },
+                body: new Uint8Array(bytes),
+                contentType: "application/octet-stream",
+            });
+            return;
+        }
+        // A template registered with no ports has no URL of its own, so the file
+        // plane is unreachable and the only way in is through the hosting plane's
+        // exec. That path carries the payload inside a shell command, so it is
+        // bounded rather than silently attempted at any size.
+        if (bytes.byteLength > this.execUploadMaxBytes) {
+            throw new Error(`Agent37 instance "${handle.id}" exposes no URL, so uploads fall back to exec, ` +
+                `which is capped at ${this.execUploadMaxBytes} bytes; "${destination}" is ` +
+                `${bytes.byteLength} bytes. Register the template with a port to use the file API.`);
+        }
+        const dir = posixDirname(destination);
+        const command = [
+            ...(dir ? [`mkdir -p ${shellQuote(dir)}`] : []),
+            writeFileViaBase64(destination, bytes),
+        ].join("\n");
+        const result = await this.execRaw(handle.id, command);
+        if (result.exit_code !== 0) {
+            throw new Error(`Agent37 exec upload of "${destination}" failed (exit ${result.exit_code}): ${combineOutput(result.stdout, result.stderr).slice(0, 2000)}`);
+        }
+    }
+    async downloadFile(handle, source, destination) {
+        const instanceUrl = await this.resolveInstanceUrl(handle.id);
+        const buffer = instanceUrl
+            ? Buffer.from(await this.client.instanceBytes(instanceUrl, "GET", "/v1/files/content", {
+                query: { path: source, disposition: "attachment" },
+            }))
+            : await this.downloadFileViaExec(handle.id, source);
+        if (destination === undefined) {
+            return buffer;
+        }
+        await writeFile(destination, buffer);
+    }
+    /**
+     * Read-side counterpart to `uploadFile`'s exec fallback: templates registered
+     * with no ports have no URL of their own, so the file plane is unreachable
+     * and the only way out is through the hosting plane's exec. The payload is
+     * carried inside a bounded shell script that first sizes the file, refuses
+     * anything larger than `execUploadMaxBytes` (the same cap as the upload
+     * path), then emits base64 on stdout. Truncated exec output is rejected
+     * rather than decoded — a truncated base64 stream would decode into the
+     * wrong bytes without error.
+     */
+    async downloadFileViaExec(id, source) {
+        const cap = this.execUploadMaxBytes;
+        const quoted = shellQuote(source);
+        const script = [
+            `set -e`,
+            `if [ ! -f ${quoted} ]; then echo "agent37: missing file" >&2; exit 66; fi`,
+            `size=$(wc -c < ${quoted})`,
+            `if [ "$size" -gt ${cap} ]; then`,
+            `  echo "agent37: file exceeds exec download cap of ${cap} bytes ($size bytes)" >&2`,
+            `  exit 67`,
+            `fi`,
+            // `base64 -w0` on GNU coreutils avoids the 76-column wrap. macOS/BSD
+            // `base64` has no `-w` but also does not wrap unless `-b` is given, so a
+            // graceful fallback keeps both platforms honest without try/catch.
+            `if base64 -w0 < ${quoted} 2>/dev/null; then :; else base64 < ${quoted}; fi`,
+        ].join("\n");
+        const result = await this.execRaw(id, script);
+        if (result.truncated) {
+            throw new Error(`Agent37 exec download of "${source}" was truncated by the exec plane; ` +
+                "register the template with a port to use the file API.");
+        }
+        if (result.exit_code !== 0) {
+            throw new Error(`Agent37 exec download of "${source}" failed (exit ${result.exit_code}): ${combineOutput(result.stdout, result.stderr).slice(0, 2000)}`);
+        }
+        // `base64` prints only the payload on stdout; ignore stderr (empty on
+        // success). Any whitespace is harmless — `Buffer.from(..., "base64")` skips
+        // characters outside the base64 alphabet.
+        return Buffer.from(result.stdout, "base64");
+    }
+    async getHomeDir(handle) {
+        return handle.homeDir ?? this.defaultHomeDir;
+    }
+    // --- diagnostics --------------------------------------------------------
+    /**
+     * Container boot and runtime logs. Unlike `exec`, this works in any state,
+     * which is what makes it the tool for an instance that will not stay up.
+     */
+    async getContainerLogs(handle, options = {}) {
+        return this.client.hosting("GET", `/v1/instances/${encodeURIComponent(handle.id)}/logs`, {
+            ...(options.tail === undefined ? {} : { query: { tail: String(options.tail) } }),
+        });
+    }
+    // --- internals ----------------------------------------------------------
+    /**
+     * Record what the caller declared about an instance.
+     *
+     * Monotonic on purpose: once ownership is claimed it survives later read-only
+     * resolutions of the same id. A plain `findAllByLabels` sweep listing an
+     * instance must not quietly revoke the delete rights a caller already
+     * declared through `getById(id, { owned: true })`.
+     */
+    declareOwnership(id, owned) {
+        if (owned) {
+            this.ownership.set(id, true);
+            return;
+        }
+        if (!this.ownership.has(id)) {
+            this.ownership.set(id, false);
+        }
+    }
+    /**
+     * Resolve what may be done to `id`: `true` to mutate it, `false` for an
+     * attachment this runtime must leave alone. Throws when the id was never
+     * registered, because that is a caller mistake rather than a policy decision.
+     */
+    requireOwnership(id, operation) {
+        const owned = this.ownership.get(id);
+        if (owned === undefined) {
+            throw new Agent37ForeignHandleError(id, operation);
+        }
+        return owned;
+    }
+    /** Drop every trace of an instance this runtime is done with. */
+    forget(id) {
+        this.ownership.delete(id);
+        this.instanceUrls.delete(id);
+    }
+    async execRaw(id, command, timeoutMs) {
+        const response = await this.client.hosting("POST", `/v1/instances/${encodeURIComponent(id)}/exec`, {
+            body: { command },
+            ...(timeoutMs === undefined ? {} : { timeoutMs }),
+        });
+        return {
+            // A response that omits `exit_code` is an unknown outcome, never a
+            // success. Defaulting it to 0 would let a malformed reply read as a
+            // command that passed.
+            exit_code: typeof response.exit_code === "number" ? response.exit_code : null,
+            stdout: response.stdout ?? "",
+            stderr: response.stderr ?? "",
+            ...(response.truncated === undefined ? {} : { truncated: response.truncated }),
+        };
+    }
+    async listInstances(timeoutMs) {
+        const request = "GET /v1/instances";
+        const payload = await this.client.hosting("GET", "/v1/instances", {
+            ...(timeoutMs === undefined ? {} : { timeoutMs }),
+        });
+        // `{ "data": [...] }` is the documented envelope. Anything else is a broken
+        // response, and coercing it to `[]` would answer "no warm lease" — the one
+        // answer that makes a caller discard a running instance and launch another.
+        // An empty `data` array still means exactly that, honestly.
+        if (!isPlainObject(payload) || !Array.isArray(payload["data"])) {
+            throw new Agent37MalformedResponseError(request, "no `data` array on the instance list");
+        }
+        return payload["data"].map((entry, index) => parseInstance(entry, `${request}[${index}]`));
+    }
+    async fetchInstance(id) {
+        try {
+            const payload = await this.client.hosting("GET", `/v1/instances/${encodeURIComponent(id)}`);
+            return parseInstance(payload, `GET /v1/instances/${id}`);
+        }
+        catch (error) {
+            if (isNotFound(error)) {
+                return null;
+            }
+            throw error;
+        }
+    }
+    async resolveInstanceUrl(id) {
+        const cached = this.instanceUrls.get(id);
+        if (cached) {
+            return cached;
+        }
+        const instance = await this.fetchInstance(id);
+        if (!instance) {
+            throw new Error(`Agent37 instance "${id}" is no longer available`);
+        }
+        this.registerInstance(instance);
+        return this.instanceUrls.get(id) ?? null;
+    }
+    registerInstance(instance) {
+        if (instance.url) {
+            this.instanceUrls.set(instance.id, instance.url.replace(/\/+$/, ""));
+        }
+        return {
+            id: instance.id,
+            state: normalizeStatus(instance.status),
+            ...(typeof instance.created === "number"
+                ? { createdAt: new Date(instance.created * 1000).toISOString() }
+                : {}),
+        };
+    }
+}
+// --- helpers --------------------------------------------------------------
+function toClientOptions(options) {
+    return {
+        apiKey: options.apiKey,
+        baseUrl: options.baseUrl,
+        ...(options.fetch === undefined ? {} : { fetch: options.fetch }),
+        ...(options.maxAttempts === undefined ? {} : { maxAttempts: options.maxAttempts }),
+        ...(options.retryBaseDelayMs === undefined
+            ? {}
+            : { retryBaseDelayMs: options.retryBaseDelayMs }),
+        ...(options.sleep === undefined ? {} : { sleep: options.sleep }),
+    };
+}
+/**
+ * Map a provider status onto the normalized vocabulary the delivery path
+ * reasons about.
+ *
+ * Only `running` is `STARTED`. Every transitional status — `provisioning`,
+ * `starting`, `waking`, `restarting`, `updating` — reads as `STOPPED`, so the
+ * default `["STARTED"]` filter can never hand a caller an instance that is not
+ * yet able to accept an exec.
+ */
+export function normalizeStatus(status) {
+    return status === "running" ? "STARTED" : "STOPPED";
+}
+function matchesState(status, states) {
+    if (states === null) {
+        return true;
+    }
+    return states.includes(normalizeStatus(status));
+}
+function matchesLabels(instance, labels) {
+    const entries = Object.entries(labels);
+    if (entries.length === 0) {
+        return true;
+    }
+    const metadata = instance.metadata;
+    if (!metadata) {
+        return false;
+    }
+    return entries.every(([key, value]) => metadata[key] === value);
+}
+function isPlainObject(value) {
+    return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+/**
+ * The property as a non-blank string, or `null` if it is anything else.
+ *
+ * Blank, not merely empty: an id of `"   "` is exactly as unusable as `""`,
+ * but it would survive an `!== ""` check and go on to address
+ * `/v1/instances/%20%20%20`. The value is returned unmodified rather than
+ * trimmed — a provider id is opaque, so refusing a blank one is this
+ * function's business while rewriting a non-blank one is not.
+ */
+function readNonBlankString(value, key) {
+    if (!isPlainObject(value)) {
+        return null;
+    }
+    const field = value[key];
+    return typeof field === "string" && field.trim() !== "" ? field : null;
+}
+/**
+ * Accept a 2xx body as an instance object, or refuse it.
+ *
+ * Only `id` and `status` are checked, and only for being non-blank strings.
+ * That is the whole load-bearing minimum: `id` is what every subsequent call
+ * addresses and what ownership is keyed on, and `status` is what decides
+ * whether the instance is handed out as ready. Every other field is optional in
+ * the contract and already treated as such. Notably the *value* of `status` is
+ * not constrained to the known set — a status this adapter has not heard of is
+ * the provider moving forward, and {@link normalizeStatus} maps anything but
+ * `running` to STOPPED, so an unknown one is already handled conservatively.
+ */
+function parseInstance(value, request) {
+    const id = readNonBlankString(value, "id");
+    if (id === null) {
+        throw new Agent37MalformedResponseError(request, "no `id` on the instance object");
+    }
+    const status = readNonBlankString(value, "status");
+    if (status === null) {
+        throw new Agent37MalformedResponseError(request, `no \`status\` on instance "${id}"`);
+    }
+    return { ...value, id, status: status };
+}
+function isNotFound(error) {
+    return error instanceof Agent37ApiError && (error.status === 404 || error.code === "not_found");
+}
+/**
+ * Reject a command lifetime Agent37 cannot deliver.
+ *
+ * Anything at or above the provider's cap is genuinely satisfied — the command
+ * cannot outlive the cap, so it certainly cannot outlive a longer deadline.
+ * Anything below it would need real cancellation, which `exec` does not offer.
+ */
+export function assertHonourableCommandTimeout(timeoutMs) {
+    if (timeoutMs !== undefined && timeoutMs < AGENT37_COMMAND_CAP_MS) {
+        throw new Agent37CommandTimeoutUnsupportedError(timeoutMs);
+    }
+}
+export function assertValidEnv(env) {
+    const keys = Object.keys(env);
+    if (keys.length > ENV_MAX_ENTRIES) {
+        throw new Agent37EnvValidationError(`Agent37 accepts at most ${ENV_MAX_ENTRIES} env entries; received ${keys.length}`);
+    }
+    for (const key of keys) {
+        if (!ENV_KEY_RE.test(key)) {
+            // The name is safe to quote (it failed a character-class test, so it is
+            // reported as-is); the value never appears in the message.
+            throw new Agent37EnvValidationError(`Agent37 env name ${JSON.stringify(key)} is not a valid shell identifier`);
+        }
+        const value = env[key];
+        if (typeof value !== "string") {
+            throw new Agent37EnvValidationError(`Agent37 env value for ${JSON.stringify(key)} must be a string`);
+        }
+        if (value.length > ENV_MAX_VALUE_LENGTH) {
+            throw new Agent37EnvValidationError(`Agent37 env value for ${JSON.stringify(key)} exceeds ${ENV_MAX_VALUE_LENGTH} characters`);
+        }
+    }
+}
+/**
+ * Build the shell program for one run.
+ *
+ * `exec` accepts a command and nothing else — no cwd, no env, no timeout — so
+ * both are expressed in the program itself. Values are single-quoted, and a
+ * failed `cd` aborts rather than silently running the command in the wrong
+ * directory.
+ */
+export function composeScript(command, options = {}) {
+    const lines = [];
+    if (options.cwd) {
+        lines.push(`cd ${shellQuote(options.cwd)} || exit 1`);
+    }
+    for (const [key, value] of Object.entries(options.env ?? {})) {
+        lines.push(`export ${key}=${shellQuote(value)}`);
+    }
+    lines.push(command);
+    return `${lines.join("\n")}\n`;
+}
+/**
+ * A shell line that materializes `contents` at `path`.
+ *
+ * The payload is base64, whose alphabet cannot escape a single-quoted word, so
+ * no caller-supplied byte is ever parsed as shell syntax.
+ */
+function writeFileViaBase64(path, contents) {
+    const encoded = (typeof contents === "string" ? Buffer.from(contents, "utf8") : contents)
+        .toString("base64");
+    return `printf %s '${encoded}' | base64 -d > ${shellQuote(path)}`;
+}
+function posixDirname(path) {
+    const index = path.lastIndexOf("/");
+    if (index <= 0) {
+        return "";
+    }
+    return path.slice(0, index);
+}
+function combineOutput(stdout, stderr) {
+    if (stdout && stderr) {
+        return stdout.endsWith("\n") || stderr.startsWith("\n")
+            ? `${stdout}${stderr}`
+            : `${stdout}\n${stderr}`;
+    }
+    return stdout || stderr || "";
+}
+export function shellQuote(value) {
+    return `'${value.replace(/'/g, `'\\''`)}'`;
+}
+//# sourceMappingURL=runtime.js.map