@nylorun/runtime 0.15.1-beta → 0.16.0-beta

package/dist/sandbox/manager.js

@@ -1,18 +1,11 @@
-import { createHash } from "node:crypto";
-import { isSandboxToolName, } from "@nylorun/core/define";
+import { SANDBOX_WORKSPACE, } from "@nylorun/core/define";
+import { sandboxWorkspaceKey, sessionWorkspaceKey, workspacePrefix, } from "./records.js";
 import { DEFAULT_SANDBOX_CPUS, DEFAULT_SANDBOX_IMAGE, describeNetwork, idleMsOf, memoryMiBOf, resolveNetwork, } from "./policy.js";
 import { parseSandboxPreference, reportSelection, selectSandboxBackend, } from "./select.js";
-import { runSandboxTool } from "./tools.js";
+import { resolveSandboxPath, runSandboxTool, } from "./tools.js";
+import { SandboxFileTooLargeError, } from "./types.js";
+export { sandboxCapabilityOf } from "./capability.js";
 const READ_TOOLS = new Set(["read", "grep", "glob"]);
-/** The sandbox capability that owns this tool call, when the call is a built-in sandbox tool. */
-export function sandboxCapabilityOf(manifest, capabilityId, toolName) {
-    if (!manifest || !capabilityId || !toolName || !isSandboxToolName(toolName))
-        return undefined;
-    const capability = manifest.capabilities.find((item) => item.id === capabilityId);
-    return capability?.sandbox && capability.tools?.some((tool) => tool.name === toolName)
-        ? capability
-        : undefined;
-}
 export class SandboxManager {
     options;
     selection;
@@ -22,21 +15,33 @@ export class SandboxManager {
     reconciled = false;
     constructor(options) {
         this.options = options;
-        this.prefix = `nylorun-${options.scope}-`;
+        this.prefix = workspacePrefix(options.scope);
     }
     /**
-     * One Tenant sweep pass:
-     * - stops sandboxes idle for at least their idle timeout (their files remain; the next
-     *   call reattaches);
-     * - marks records whose compute this process does not hold as stopped (compute is gone
-     *   after a Runtime restart);
-     * - on the first pass of this process, removes sandboxes whose session no longer exists
-     *   (skipped for ephemeral Runtimes, which delete theirs on close).
+     * One sweep pass of core's process: `stopIdle`, then, on the first pass of this process,
+     * `reconcile` (skipped for ephemeral Runtimes, which delete theirs on close).
      */
     async sweep(options) {
         if (this.closing)
             return;
-        const now = options.now ?? Date.now();
+        await this.stopIdle(options.now);
+        if (this.reconciled || this.options.ephemeral)
+            return;
+        this.reconciled = true;
+        if (!(await this.hasRecords()))
+            return;
+        await this.reconcile(async (sessionId) => [...this.live.values()].some((live) => live.sessionId === sessionId) ||
+            (await options.sessionExists(sessionId)), options.sandboxExists ?? (() => true));
+    }
+    /**
+     * Stops sandboxes idle for at least their idle timeout (their files remain; the next call
+     * reattaches), and marks records whose compute this process does not hold as stopped
+     * (compute is gone after a restart).
+     */
+    async stopIdle(at) {
+        if (this.closing)
+            return;
+        const now = at ?? Date.now();
         const idle = (live) => !!live.handle && live.active === 0 && now - live.lastUsedAt >= live.idleMs;
         const stops = [];
         for (const [key, live] of this.live) {
@@ -49,23 +54,18 @@ export class SandboxManager {
             stops.push(live.tail);
         }
         await Promise.all(stops);
-        await this.options.store.tx(async (t) => {
-            for (const record of await t.listSandboxes()) {
-                if (record.state === "stopped")
-                    continue;
-                const live = this.live.get(record.key);
-                if (live && (live.handle || live.active > 0))
-                    continue;
-                await t.put("sandboxes", record.key, { ...record, state: "stopped" });
-            }
-        });
-        if (this.reconciled || this.options.ephemeral)
-            return;
-        this.reconciled = true;
-        if (!(await this.hasRecords()))
-            return;
-        await this.reconcile(async (sessionId) => [...this.live.values()].some((live) => live.sessionId === sessionId) ||
-            (await options.sessionExists(sessionId)));
+        for (const record of await this.options.records.list()) {
+            if (record.state === "stopped")
+                continue;
+            const live = this.live.get(record.key);
+            if (live && (live.handle || live.active > 0))
+                continue;
+            await this.options.records.put({ ...record, state: "stopped" });
+        }
+    }
+    /** Every workspace record this manager keeps. */
+    workspaces() {
+        return this.options.records.list();
     }
     /** Backends are probed once, on first use, and the choice holds for the life of the Runtime. */
     get ready() {
@@ -83,15 +83,126 @@ export class SandboxManager {
     }
     /** Whether any sandbox was ever recorded, so startup can skip probing for agents without one. */
     async hasRecords() {
-        return (await this.options.store.tx((t) => t.counts())).sandboxes > 0;
+        return (await this.options.records.count()) > 0;
     }
     keyOf(sessionId) {
-        return this.prefix + createHash("sha256").update(sessionId).digest("hex").slice(0, 16);
+        return sessionWorkspaceKey(this.options.scope, sessionId);
+    }
+    /** The workspace key of sandbox resource `sandboxId` (`sandboxWorkspaceKey`). */
+    sandboxKeyOf(sandboxId) {
+        return sandboxWorkspaceKey(this.options.scope, sandboxId);
+    }
+    keyFor(session) {
+        return session.sandboxId === undefined
+            ? this.keyOf(session.id)
+            : this.sandboxKeyOf(session.sandboxId);
     }
     async report() {
         return { ...reportSelection(await this.ready), defaultImage: DEFAULT_SANDBOX_IMAGE };
     }
     async run(session, capability, toolName, input, signal) {
+        const prepared = await this.prepare(session, capability);
+        if ("kind" in prepared)
+            return prepared;
+        const { live: entry, spec } = prepared;
+        const task = entry.tail.then(() => this.execute(entry, session, spec, toolName, input, signal));
+        entry.tail = task.catch(() => undefined);
+        return task;
+    }
+    /**
+     * The bytes of one file in the session's sandbox, for `save_artifact` (F8.1), in the same queue
+     * as its tool calls: `missing` when there is no such file, a failed outcome when the sandbox
+     * cannot open or the file is larger than `maxBytes`. Relative paths resolve in the workspace.
+     */
+    async readBytes(session, capability, path, maxBytes, signal) {
+        return this.withHandle(session, capability, signal, async (handle, live) => {
+            const resolved = resolveSandboxPath(path, handle.workspace ?? SANDBOX_WORKSPACE);
+            if (!handle.readBytes)
+                return {
+                    kind: "failed",
+                    code: "sandbox.unsupported",
+                    message: `The ${live.backend.name} backend cannot read files as bytes`,
+                };
+            try {
+                const bytes = await handle.readBytes(resolved, maxBytes);
+                return bytes === undefined
+                    ? { kind: "missing", path: resolved }
+                    : { kind: "read", path: resolved, bytes };
+            }
+            catch (error) {
+                if (error instanceof SandboxFileTooLargeError)
+                    return {
+                        kind: "failed",
+                        code: "artifact.too_large",
+                        message: `${resolved} is ${error.size} bytes; an artifact may hold at most ${maxBytes}`,
+                    };
+                throw error;
+            }
+        });
+    }
+    /**
+     * The files under directory `dir` of the session's sandbox, for the turn-end export (F8.2), in
+     * the same queue as its tool calls. `missing` when the sandbox was never created (nothing is
+     * started to look) or `dir` is not a directory. Relative paths resolve in the workspace.
+     */
+    async listFiles(session, capability, dir, maxEntries, signal) {
+        const key = this.keyFor(session);
+        if (!this.live.get(key)?.handle) {
+            const record = await this.options.records.get(key);
+            if (!record)
+                return { kind: "missing", path: dir };
+        }
+        return this.withHandle(session, capability, signal, async (handle, live) => {
+            const resolved = resolveSandboxPath(dir, handle.workspace ?? SANDBOX_WORKSPACE);
+            if (!handle.listFiles)
+                return {
+                    kind: "failed",
+                    code: "sandbox.unsupported",
+                    message: `The ${live.backend.name} backend cannot list files`,
+                };
+            const listing = await handle.listFiles(resolved, maxEntries);
+            return listing === undefined
+                ? { kind: "missing", path: resolved }
+                : { kind: "listed", path: resolved, listing };
+        });
+    }
+    /** Runs `use` on the session's sandbox in its queue, starting it first when it is stopped. */
+    async withHandle(session, capability, signal, use) {
+        const prepared = await this.prepare(session, capability);
+        if ("kind" in prepared)
+            return prepared;
+        const { live, spec } = prepared;
+        const task = live.tail.then(async () => {
+            if (signal.aborted)
+                throw new Error("Turn cancelled");
+            if (this.closing)
+                throw new Error("Runtime is shutting down");
+            live.active += 1;
+            try {
+                if (!live.handle) {
+                    try {
+                        live.handle = await this.open(live, session, spec);
+                    }
+                    catch (error) {
+                        return {
+                            kind: "failed",
+                            code: "sandbox.start_failed",
+                            message: `The sandbox could not start: ${error instanceof Error ? error.message : String(error)}`,
+                        };
+                    }
+                }
+                return await use(live.handle, live);
+            }
+            finally {
+                live.active -= 1;
+                live.lastUsedAt = Date.now();
+            }
+        });
+        live.tail = task.catch(() => undefined);
+        return task;
+    }
+    /** The session's live sandbox entry and spec, or why it cannot run here. */
+    async prepare(session, capability) {
         const selection = await this.ready;
         const backend = selection.backend;
         if (!backend)
@@ -100,7 +211,7 @@ export class SandboxManager {
                 code: "sandbox.unavailable",
                 message: `No sandbox is available: ${selection.reason}. Run \`npx nylorun doctor sandbox\` for options.`,
             };
-        const key = this.keyOf(session.id);
+        const key = this.keyFor(session);
         const spec = {
             key,
             image: capability.sandbox?.image ?? DEFAULT_SANDBOX_IMAGE,
@@ -119,6 +230,7 @@ export class SandboxManager {
         if (!live) {
             live = {
                 sessionId: session.id,
+                ...(session.sandboxId === undefined ? {} : { sandboxId: session.sandboxId }),
                 backend,
                 idleMs: idleMsOf(capability.sandbox),
                 active: 0,
@@ -127,10 +239,7 @@ export class SandboxManager {
             };
             this.live.set(key, live);
         }
-        const entry = live;
-        const task = entry.tail.then(() => this.execute(entry, session, spec, toolName, input, signal));
-        entry.tail = task.catch(() => undefined);
-        return task;
+        return { live, spec };
     }
     async execute(live, session, spec, toolName, input, signal) {
         if (signal.aborted)
@@ -153,12 +262,8 @@ export class SandboxManager {
             }
             catch (error) {
                 const message = error instanceof Error ? error.message : String(error);
-                await this.record(spec.key, session.id, live.backend.name, spec.image, "stopped");
-                await this.options.emit(session.id, session.activeTurnId, "sandbox.state", {
-                    state: "stopped",
-                    backend: live.backend.name,
-                    error: message,
-                });
+                const record = await this.record(spec.key, live, session.id, spec.image, "stopped");
+                await this.options.emit(session.id, session.activeTurnId, "sandbox.state", { state: "stopped", backend: live.backend.name, error: message }, { record, ...claimOf(session) });
                 // Nothing ran yet, so a failed start is a definite outcome, not an uncertain one.
                 return {
                     kind: "failed",
@@ -180,7 +285,7 @@ export class SandboxManager {
                 outcome: outcome.kind,
                 ...(outcome.kind === "failed" ? { code: outcome.code } : {}),
                 durationMs: Date.now() - started,
-            });
+            }, claimOf(session));
             return outcome;
         }
         catch (error) {
@@ -196,28 +301,24 @@ export class SandboxManager {
         }
     }
     async open(live, session, spec) {
-        const existing = await this.options.store.tx((t) => t.get("sandboxes", spec.key));
+        const existing = await this.options.records.get(spec.key);
         const payload = {
             backend: live.backend.name,
             isolation: live.backend.isolation,
             image: spec.image,
             network: describeNetwork(spec.network),
         };
-        await this.record(spec.key, session.id, live.backend.name, spec.image, "creating", existing);
-        await this.options.emit(session.id, session.activeTurnId, "sandbox.state", {
-            state: "creating",
-            ...payload,
-            ...(existing ? { reattach: true } : {}),
-        });
+        const creating = await this.record(spec.key, live, session.id, spec.image, "creating", existing);
+        await this.options.emit(session.id, session.activeTurnId, "sandbox.state", { state: "creating", ...payload, ...(existing ? { reattach: true } : {}) }, { record: creating, ...claimOf(session) });
         const handle = await live.backend.open(spec);
-        await this.record(spec.key, session.id, live.backend.name, spec.image, "running", existing);
+        const running = await this.record(spec.key, live, session.id, spec.image, "running", existing);
         await this.options.emit(session.id, session.activeTurnId, "sandbox.state", {
             state: "running",
             ...payload,
             ...(existing && handle.created
                 ? { lost: true, note: "The sandbox was gone and was created again; its earlier files are lost." }
                 : {}),
-        });
+        }, { record: running, ...claimOf(session) });
         return handle;
     }
     async stop(key, live) {
@@ -229,40 +330,68 @@ export class SandboxManager {
             await handle.stop();
         }
         finally {
-            await this.record(key, live.sessionId, live.backend.name, undefined, "stopped");
-            await this.options.emit(live.sessionId, null, "sandbox.state", { state: "stopped", backend: live.backend.name });
+            const record = await this.record(key, live, live.sessionId, undefined, "stopped");
+            await this.options.emit(live.sessionId, null, "sandbox.state", { state: "stopped", backend: live.backend.name }, { record });
         }
     }
-    async record(key, sessionId, backend, image, state, known) {
+    async record(key, live, sessionId, image, state, known) {
         const now = new Date().toISOString();
-        await this.options.store.tx(async (t) => {
-            const existing = known ?? (await t.get("sandboxes", key));
-            await t.put("sandboxes", key, {
-                key,
-                sessionId,
-                backend,
-                image: image ?? existing?.image ?? "",
-                state,
-                createdAt: existing?.createdAt ?? now,
-                updatedAt: now,
-            });
-        });
+        const existing = known ?? (await this.options.records.get(key));
+        const record = {
+            key,
+            sessionId,
+            ...(live.sandboxId === undefined ? {} : { sandboxId: live.sandboxId }),
+            backend: live.backend.name,
+            image: image ?? existing?.image ?? "",
+            state,
+            createdAt: existing?.createdAt ?? now,
+            updatedAt: now,
+        };
+        await this.options.records.put(record);
+        return record;
     }
     /** The sandbox record for a session, if one was ever created. */
     status(sessionId) {
-        return this.options.store.tx((t) => t.get("sandboxes", this.keyOf(sessionId)));
+        return this.options.records.get(this.keyOf(sessionId));
+    }
+    /**
+     * Deletes sandbox resource `sandboxId`'s workspace, its files and its compute record, after
+     * any command queued on it. Called once the resource is deleted.
+     */
+    async removeSandbox(sandboxId) {
+        await this.remove(this.sandboxKeyOf(sandboxId));
+    }
+    /** Deletes the workspace `key`, its files and its record, after any command queued on it. */
+    async remove(key) {
+        const live = this.live.get(key);
+        if (live) {
+            await live.tail.catch(() => undefined);
+            live.handle = undefined;
+            this.live.delete(key);
+        }
+        const { backend } = await this.ready;
+        if (backend)
+            await backend.remove(key);
+        await this.options.records.delete(key);
     }
-    /** Delete sandboxes this Runtime owns whose session no longer exists. */
-    async reconcile(sessionExists) {
+    /**
+     * Delete workspaces this Runtime owns whose owner is gone: a session's when `sessionExists`
+     * says the session is gone, a sandbox resource's when `sandboxExists` says the resource is.
+     */
+    async reconcile(sessionExists, sandboxExists) {
         const { backend } = await this.ready;
         if (!backend)
             return;
         for (const key of await backend.list(this.prefix)) {
-            const record = await this.options.store.tx((t) => t.get("sandboxes", key));
-            if (record && (await sessionExists(record.sessionId)))
-                continue;
-            await backend.remove(key);
-            await this.options.store.tx((t) => t.delete("sandboxes", key));
+            const record = await this.options.records.get(key);
+            if (record) {
+                const kept = record.sandboxId === undefined
+                    ? await sessionExists(record.sessionId)
+                    : await sandboxExists(record.sandboxId);
+                if (kept)
+                    continue;
+            }
+            await this.remove(key);
         }
     }
     async close() {
@@ -282,3 +411,6 @@ export class SandboxManager {
         this.live.clear();
     }
 }
+function claimOf(session) {
+    return session.claim === undefined ? {} : { claim: session.claim };
+}

package/dist/sandbox/placement.d.ts

@@ -0,0 +1,27 @@
+/**
+ * Placement (F7.2, D38): where a session's harness runs, checked when the session opens and
+ * never downgraded afterwards. The Tenant maps harness ids (`nylorun`, or `*` for the rest) to
+ * the hosts they may run on (`sandbox.config` `placement`): `harness-container` (the Runtime's
+ * harness: in process, or the harness container) and `sandbox` (the engine in a pod sandbox).
+ * Default: both.
+ *
+ * A session attached to a pod sandbox runs on `sandbox`; every other session on
+ * `harness-container`. A host the Tenant does not allow is `409 placement_refused`. A pod
+ * sandbox needs sandbox pods: without a cluster (`nylorun sandbox enable`), or with the
+ * sandboxes service not ready, it is `409 sandbox_unavailable`.
+ */
+import type { SandboxPlacementHost, TenantSandboxConfig } from "@nylorun/core/contracts";
+import type { TenantPods } from "../tenant/context.js";
+/** The harness every session of this Runtime runs (blueprint D38). */
+export declare const HARNESS_ID = "nylorun";
+export declare const DEFAULT_PLACEMENT: readonly SandboxPlacementHost[];
+/** The hosts harness `harnessId` may run on. */
+export declare function placementOf(config: TenantSandboxConfig, harnessId?: string): readonly SandboxPlacementHost[];
+/** How to enable sandbox pods, for the messages that need them. */
+export declare const ENABLE_PODS = "run `nylorun sandbox enable --context <name>` to give this Tenant a cluster";
+/** Refuses a session whose sandbox needs a host the Tenant does not allow. */
+export declare function checkPlacement(config: TenantSandboxConfig, kind: "virtual" | "pod" | undefined): void;
+/** Whether the sandboxes service is up, cached for a few seconds. */
+export declare function podsReady(pods: TenantPods): Promise<boolean>;
+/** Refuses a pod sandbox without sandbox pods, or with the sandboxes service down. */
+export declare function requirePods(pods: TenantPods | undefined, what: string): Promise<TenantPods>;

package/dist/sandbox/placement.js

@@ -0,0 +1,44 @@
+import { fail } from "../tenant/http.js";
+/** The harness every session of this Runtime runs (blueprint D38). */
+export const HARNESS_ID = "nylorun";
+export const DEFAULT_PLACEMENT = ["harness-container", "sandbox"];
+/** The hosts harness `harnessId` may run on. */
+export function placementOf(config, harnessId = HARNESS_ID) {
+    const placement = config.placement;
+    return placement?.[harnessId]?.hosts ?? placement?.["*"]?.hosts ?? DEFAULT_PLACEMENT;
+}
+/** How to enable sandbox pods, for the messages that need them. */
+export const ENABLE_PODS = "run `nylorun sandbox enable --context <name>` to give this Tenant a cluster";
+/** Refuses a session whose sandbox needs a host the Tenant does not allow. */
+export function checkPlacement(config, kind) {
+    const host = kind === "pod" ? "sandbox" : "harness-container";
+    const allowed = placementOf(config);
+    if (!allowed.includes(host))
+        fail(409, kind === "pod"
+            ? `This Tenant does not let the ${HARNESS_ID} harness run in a sandbox pod (placement allows ${allowed.join(", ")}).`
+            : `This Tenant runs the ${HARNESS_ID} harness only in sandbox pods (placement allows ${allowed.join(", ")}): attach a pod sandbox with sandbox: { id }.`, { code: "placement_refused", details: { harness: HARNESS_ID, host, allowed: [...allowed] } });
+}
+const READY_CACHE_MS = 5_000;
+const ready = new WeakMap();
+/** Whether the sandboxes service is up, cached for a few seconds. */
+export async function podsReady(pods) {
+    const cached = ready.get(pods);
+    if (cached && Date.now() - cached.at < READY_CACHE_MS)
+        return cached.ready;
+    const answer = await pods.client.ready();
+    ready.set(pods, { at: Date.now(), ready: answer });
+    return answer;
+}
+/** Refuses a pod sandbox without sandbox pods, or with the sandboxes service down. */
+export async function requirePods(pods, what) {
+    if (!pods)
+        return fail(409, `${what} needs sandbox pods, and this Runtime has no cluster: ${ENABLE_PODS}.`, {
+            code: "sandbox_unavailable",
+        });
+    if (!(await podsReady(pods)))
+        fail(409, `${what} needs sandbox pods, and the sandboxes service is not ready. Check \`nylorun sandbox status\`.`, {
+            code: "sandbox_unavailable",
+            details: { retryAfterSeconds: 5 },
+        }, { "retry-after": "5" });
+    return pods;
+}

package/dist/sandbox/pods/client.d.ts

@@ -0,0 +1,90 @@
+/**
+ * The sandboxes service's client (F7.2, D32): the Go service (`sandboxes/`) that alone holds
+ * the cluster credentials and drives agent-sandbox Sandboxes in the Tenant's namespace. Core
+ * reaches it at `NYLORUN_SANDBOXES_URL` with `NYLORUN_SANDBOXES_TOKEN`; nothing else does.
+ *
+ * Pull, not push: the service never calls core. Core reads a Sandbox's status when it
+ * reconciles (`GET /v1/pods/{name}`, optionally blocking with `?wait=`), and every change it
+ * asks for carries an operation id, so a retried `PUT` is a no-op.
+ */
+/** `PUT /v1/pods/{name}`: the Sandbox the service applies (`driver.Spec` in Go). */
+export interface PodSpec {
+    readonly opId: string;
+    readonly mode: "Running" | "Suspended";
+    /** The workload image; the service defaults it to `python:3.13-slim`. */
+    readonly image?: string;
+    /** The Runtime image the engine is copied from. */
+    readonly harnessImage?: string;
+    /** Replaces the engine command (diagnostics). */
+    readonly command?: readonly string[];
+    readonly cpus?: number;
+    readonly memoryMiB?: number;
+    readonly storageGiB?: number;
+    readonly stopGraceSeconds?: number;
+    /** RFC 3339: the Sandbox expires then (agent-sandbox `shutdownTime`). */
+    readonly shutdownTime?: string;
+    readonly shutdownPolicy?: "Retain" | "Delete";
+    readonly env?: Readonly<Record<string, string>>;
+    /** Written to the Sandbox's join Secret before it is applied. */
+    readonly joinToken?: string;
+}
+/** A Sandbox as the service's informers see it (`driver.Status` in Go). */
+export interface PodStatus {
+    readonly name: string;
+    readonly exists: boolean;
+    readonly deleting: boolean;
+    readonly mode?: string;
+    readonly ready: boolean;
+    readonly suspended: boolean;
+    readonly expired: boolean;
+    readonly podUID?: string;
+    readonly podPhase?: string;
+    readonly volume: "present" | "missing";
+    readonly opId?: string;
+    readonly shutdownTime?: string;
+    readonly reason?: string;
+    readonly message?: string;
+    /** With `?wait=`: whether the state was reached before the timeout. */
+    readonly met?: boolean;
+}
+/** `GET /v1/info`: the cluster `nylorun sandbox enable` recorded. */
+export interface ClusterInfo {
+    readonly namespace: string;
+    readonly context: string;
+    readonly controllerVersion?: string;
+    readonly apiVersion?: string;
+    readonly hostAddress?: string;
+    readonly ports?: Readonly<Record<string, number>>;
+    readonly networkPolicy?: {
+        readonly enforced: boolean;
+        readonly probedAt?: string;
+    };
+}
+export type PodWait = "ready" | "suspended" | "expired" | "gone";
+export interface SandboxesClient {
+    /** Whether the service is up and its informers synced (`GET /ready`). Never throws. */
+    ready(signal?: AbortSignal): Promise<boolean>;
+    info(signal?: AbortSignal): Promise<ClusterInfo>;
+    put(name: string, spec: PodSpec, signal?: AbortSignal): Promise<PodStatus>;
+    status(name: string, options?: {
+        wait?: PodWait;
+        timeoutMs?: number;
+        signal?: AbortSignal;
+    }): Promise<PodStatus>;
+    delete(name: string, opId: string, signal?: AbortSignal): Promise<PodStatus>;
+}
+/** The service refused a request, or did not answer. */
+export declare class SandboxesError extends Error {
+    readonly status: number;
+    readonly code: string;
+    readonly name = "SandboxesError";
+    constructor(status: number, code: string, message: string);
+}
+/** The sandboxes service over HTTP. */
+export declare function httpSandboxesClient(options: {
+    readonly url: string;
+    readonly token: string;
+    readonly fetch?: typeof fetch;
+    /** Per request, unless the request waits longer. Default 20 s. */
+    readonly timeoutMs?: number;
+}): SandboxesClient;

package/dist/sandbox/pods/client.js

@@ -0,0 +1,79 @@
+/**
+ * The sandboxes service's client (F7.2, D32): the Go service (`sandboxes/`) that alone holds
+ * the cluster credentials and drives agent-sandbox Sandboxes in the Tenant's namespace. Core
+ * reaches it at `NYLORUN_SANDBOXES_URL` with `NYLORUN_SANDBOXES_TOKEN`; nothing else does.
+ *
+ * Pull, not push: the service never calls core. Core reads a Sandbox's status when it
+ * reconciles (`GET /v1/pods/{name}`, optionally blocking with `?wait=`), and every change it
+ * asks for carries an operation id, so a retried `PUT` is a no-op.
+ */
+/** The service refused a request, or did not answer. */
+export class SandboxesError extends Error {
+    status;
+    code;
+    name = "SandboxesError";
+    constructor(status, code, message) {
+        super(message);
+        this.status = status;
+        this.code = code;
+    }
+}
+/** The sandboxes service over HTTP. */
+export function httpSandboxesClient(options) {
+    const base = options.url.replace(/\/+$/, "");
+    const call = options.fetch ?? fetch;
+    const request = async (method, path, init = {}) => {
+        const timeout = AbortSignal.timeout(init.timeoutMs ?? options.timeoutMs ?? 20_000);
+        const signal = init.signal ? AbortSignal.any([init.signal, timeout]) : timeout;
+        let response;
+        try {
+            response = await call(`${base}${path}`, {
+                method,
+                headers: {
+                    ...(init.auth === false ? {} : { authorization: `Bearer ${options.token}` }),
+                    ...(init.body === undefined ? {} : { "content-type": "application/json" }),
+                },
+                ...(init.body === undefined ? {} : { body: JSON.stringify(init.body) }),
+                signal,
+            });
+        }
+        catch (error) {
+            throw new SandboxesError(0, "unreachable", `The sandboxes service did not answer: ${error instanceof Error ? error.message : String(error)}`);
+        }
+        const text = await response.text();
+        let body;
+        try {
+            body = text === "" ? undefined : JSON.parse(text);
+        }
+        catch {
+            body = undefined;
+        }
+        if (!response.ok) {
+            const error = body?.error;
+            throw new SandboxesError(response.status, error?.code ?? "error", error?.message ?? `The sandboxes service answered ${response.status}`);
+        }
+        return body;
+    };
+    const pod = (name) => `/v1/pods/${encodeURIComponent(name)}`;
+    return {
+        async ready(signal) {
+            try {
+                await request("GET", "/ready", { auth: false, timeoutMs: 3_000, ...(signal ? { signal } : {}) });
+                return true;
+            }
+            catch {
+                return false;
+            }
+        },
+        info: (signal) => request("GET", "/v1/info", signal ? { signal } : {}),
+        put: (name, spec, signal) => request("PUT", pod(name), { body: spec, ...(signal ? { signal } : {}) }),
+        status(name, { wait, timeoutMs, signal } = {}) {
+            const query = wait ? `?wait=${wait}&timeoutMs=${Math.min(timeoutMs ?? 30_000, 30_000)}` : "";
+            return request("GET", `${pod(name)}${query}`, {
+                ...(signal ? { signal } : {}),
+                ...(wait ? { timeoutMs: Math.min(timeoutMs ?? 30_000, 30_000) + 10_000 } : {}),
+            });
+        },
+        delete: (name, opId, signal) => request("DELETE", `${pod(name)}?opId=${encodeURIComponent(opId)}`, signal ? { signal } : {}),
+    };
+}