@nylorun/runtime 0.15.2-beta → 0.16.0-beta

package/dist/tenant/run-token.js

@@ -0,0 +1,138 @@
+/**
+ * Run tokens (F5, gate trust): the ES256 JWT core mints for one advance's lease of a session.
+ * It is the only credential of a model call at the gates, and the credential of a session's
+ * remote MCP calls. The gates take session, turn and agent from it, never from the body, and
+ * check on every call that the lease it names is still the session's (`staleRun`).
+ *
+ * Signed by the keys service with the Tenant's current signing key, like subject and delivery
+ * tokens, and told apart from them by `typ` and `aud`. Internal: not in `openapi.json`. A token
+ * lives `RUN_TOKEN_TTL_SECONDS`, no longer than a delivery token, so a key rotation never
+ * revokes a live one (`signing-keys.ts`).
+ *
+ * ```text
+ * header  { alg: ES256, typ: nylorun-run+jwt, kid }
+ * claims  { iss: urn:nylorun:tenant:<id>, aud: nylorun-gates, sub: <sessionId>,
+ *           trn: <turnId>, agt: <root agentId>, epc: <lease epoch>, iat, exp, jti }
+ * ```
+ */
+import { randomUUID } from "node:crypto";
+import { errors, importJWK, jwtVerify } from "jose";
+import { subjectTokenIssuer } from "@nylorun/core/contracts";
+import { CLOCK_TOLERANCE_SECONDS, tokenKeyId } from "./jwt.js";
+export const RUN_TOKEN_TYP = "nylorun-run+jwt";
+export const RUN_TOKEN_AUD = "nylorun-gates";
+/** How long a run token lives. */
+export const RUN_TOKEN_TTL_SECONDS = 15 * 60;
+/** The lease heartbeat re-mints a token with less than this left. */
+export const RUN_TOKEN_RENEW_SECONDS = 5 * 60;
+/** Allowed spread between `iat` and `exp` beyond the lifetime. */
+const LIFETIME_SLACK_SECONDS = 60;
+/**
+ * Mints the run token of `lease` over `session`'s active turn. Throws when the session has
+ * no active turn: there is no run to name.
+ */
+export async function mintRunToken(signer, lease, session) {
+    const turnId = session.activeTurnId;
+    if (!turnId)
+        throw new Error(`Session ${lease.sessionId} has no active turn to mint a run token for`);
+    const tenantId = signer.config.tenantId;
+    const iat = Math.floor(Date.now() / 1000);
+    const exp = iat + RUN_TOKEN_TTL_SECONDS;
+    // Signed by the keys service (F4.2): this process never holds the private key.
+    const { token } = await signer.keys.sign({
+        typ: RUN_TOKEN_TYP,
+        claims: {
+            iss: subjectTokenIssuer(tenantId),
+            aud: RUN_TOKEN_AUD,
+            sub: lease.sessionId,
+            trn: turnId,
+            agt: session.agentId,
+            epc: lease.epoch,
+            iat,
+            exp,
+            jti: randomUUID(),
+        },
+    });
+    return {
+        token,
+        claims: {
+            tenantId,
+            sessionId: lease.sessionId,
+            turnId,
+            agentId: session.agentId,
+            epoch: lease.epoch,
+            expiresAt: exp * 1000,
+        },
+    };
+}
+/**
+ * Verifies a run token of Tenant `tenantId` against the public keys in `store`: everything a
+ * forger controls (size, shape, header) is checked before any key is read, then the
+ * signature, `iss`, `aud`, `typ`, lifetime and claims. A revoked key refuses even a token it
+ * signed while it was live.
+ */
+export async function verifyRunToken(store, tenantId, raw, cache = new Map()) {
+    const refused = (reason) => ({ ok: false, reason: `run_token_${reason}` });
+    const checked = tokenKeyId(raw, RUN_TOKEN_TYP);
+    if ("refused" in checked)
+        return refused(checked.refused);
+    const { kid } = checked;
+    const row = await store.tx((t) => t.signingKey(kid));
+    if (!row)
+        return refused("key_unknown");
+    let key = cache.get(kid);
+    if (!key) {
+        key = await importJWK({ ...JSON.parse(row.publicJwk), alg: "ES256" }, "ES256");
+        cache.set(kid, key);
+    }
+    let payload;
+    try {
+        const verified = await jwtVerify(raw, key, {
+            algorithms: ["ES256"],
+            issuer: subjectTokenIssuer(tenantId),
+            audience: RUN_TOKEN_AUD,
+            typ: RUN_TOKEN_TYP,
+            clockTolerance: CLOCK_TOLERANCE_SECONDS,
+            requiredClaims: ["sub", "iat", "exp", "jti"],
+        });
+        payload = verified.payload;
+    }
+    catch (error) {
+        return refused(error instanceof errors.JWTExpired ? "expired" : "invalid");
+    }
+    if (row.state === "revoked")
+        return refused("key_revoked");
+    const { sub, trn, agt, epc, iat, exp } = payload;
+    if (typeof sub !== "string" ||
+        sub === "" ||
+        typeof trn !== "string" ||
+        trn === "" ||
+        typeof agt !== "string" ||
+        agt === "" ||
+        typeof epc !== "number" ||
+        !Number.isSafeInteger(epc) ||
+        epc < 1 ||
+        exp - iat > RUN_TOKEN_TTL_SECONDS + LIFETIME_SLACK_SECONDS)
+        return refused("claims");
+    return {
+        ok: true,
+        claims: { tenantId, sessionId: sub, turnId: trn, agentId: agt, epoch: epc, expiresAt: exp * 1000 },
+    };
+}
+/**
+ * Why calls under `claims` are stale, or undefined while its lease is still the session's
+ * (G4): the session's epoch is the token's, its active turn is the token's, and it is not
+ * cancelled. One indexed read of the session row.
+ */
+export async function staleRun(store, claims) {
+    const state = await store.tx((t) => t.runState(claims.sessionId));
+    if (!state)
+        return "the session is gone";
+    if (state.epoch !== claims.epoch)
+        return "another advance owns the session now";
+    if (state.activeTurnId !== claims.turnId)
+        return "the turn has ended";
+    if (state.status === "cancelled")
+        return "the turn was cancelled";
+    return undefined;
+}

package/dist/tenant/runtime.d.ts

@@ -8,6 +8,12 @@ import { type StreamsStatus } from "./streams.js";
 import { type TenantExecution, type TenantWorker } from "./worker.js";
 import { type ToolGate } from "../gates/tool-gate.js";
 import { type Keys } from "../keys/keys.js";
+import type { RunGrants } from "./run-grants.js";
+import { type BlobStore } from "../blob/index.js";
+import type { HarnessChannel, MemoryPortsOptions } from "@nylorun/core/harness-api";
+import { type HarnessPeer } from "../harness-api/server.js";
+import { type HostAuthority } from "../sandbox/join.js";
+import type { TenantPods } from "./context.js";
 /** TENANTS-CCR: test/injection hooks until TenantConfig gains them. */
 export type TenantOpenHooks = {
     modelProvider?: ModelProvider;
@@ -26,6 +32,11 @@ export type TenantOpenHooks = {
      * process never reads, creates or holds the vault key. Without one, it does them here.
      */
     keys?: Keys;
+    /**
+     * The run grants the gates service's clients read (F5): each advance mints its session's
+     * run token into them. Give the same object to `modelGate` and `toolGate`.
+     */
+    runGrants?: RunGrants;
     vaultKek?: Buffer | string | null;
     /** When true, create the KEK file on first vault write (tests / new Tenants). */
     createKekIfMissing?: boolean;
@@ -50,6 +61,28 @@ export type TenantOpenHooks = {
     hostRelay?: boolean;
     /** How long a retired stream basin is kept after a reset (tests). Default 60 s. */
     retireGraceMs?: number;
+    /**
+     * The Object store, owned by the caller (the Host's `s3` BlobStore, D35). Without one the
+     * Tenant keeps blobs on disk under `paths.blobs` (the `fs` adapter: embedding, tests).
+     */
+    blobs?: BlobStore;
+    /**
+     * The Tenant's harness (F6.1, F6.2): `memory` (default) runs one in this process over a memory
+     * channel, with the Tenant's MCP pool and SandboxManager; `json` the same through JSON with
+     * every frame validated (tests). `remote` runs none: harnesses attach with
+     * `TenantHandle.attachHarness` (the Harness API listener, `NYLORUN_HARNESS=remote`), and the
+     * one that declares `workspace` holds the workspaces; this process has no MCP pool and no
+     * SandboxManager. `ws` is `remote` with a harness service in this process over a loopback
+     * WebSocket (tests).
+     */
+    harness?: "memory" | "json" | "ws" | "remote";
+    /** Sees each frame of the in-process harness's channel (tests and benchmarks). */
+    harnessTap?: MemoryPortsOptions["tap"];
+    /**
+     * Sandbox pods (F7.2): the sandboxes service (`NYLORUN_SANDBOXES_URL`) and the Runtime image
+     * pods copy the engine from. Without it, kind `pod` is `sandbox_unavailable`.
+     */
+    pods?: TenantPods;
 } & OpenedTenant;
 export declare class TenantRuntime implements TenantHandle {
     private readonly ctx;
@@ -59,7 +92,11 @@ export declare class TenantRuntime implements TenantHandle {
     private readonly detach;
     /** How long close waits for running advances: the execution's advance grace period. */
     private readonly closeGraceMs;
+    private readonly harness?;
+    private readonly hosts?;
     private constructor();
+    /** The Tenant's side of a sandbox pod's join (F7.2). */
+    hostAuthority(): HostAuthority | undefined;
     static open(config: TenantConfig, hooks: TenantOpenHooks): Promise<TenantRuntime>;
     fetch(request: Request, node: NodeBindings): Promise<Response>;
     authorize(sessionId: string, request: {
@@ -80,6 +117,7 @@ export declare class TenantRuntime implements TenantHandle {
     streamsStatus(): Promise<StreamsStatus>;
     /** Adds a callback to the Tenant sweep. Returns a function that removes it. */
     onSweep(hook: () => Promise<void>): () => void;
+    attachHarness(channel: HarnessChannel, peer: HarnessPeer): () => void;
     close(): Promise<void>;
 }
 /**

package/dist/tenant/runtime.js

@@ -7,6 +7,7 @@ import { SigningKeys } from "./signing-keys.js";
 import { VaultService } from "../vault/service.js";
 import { McpPool } from "../mcp/pool.js";
 import { SandboxManager } from "../sandbox/manager.js";
+import { storeSandboxRecords } from "../sandbox/records.js";
 import { defaultSandboxBackends } from "../sandbox/select.js";
 import { MemoryExecution } from "../execution/memory.js";
 import { openError } from "./cause.js";
@@ -22,6 +23,14 @@ import { authorize } from "./effects.js";
 import { inProcessToolGate } from "../gates/tool-gate.js";
 import { inProcessKeys } from "../keys/keys.js";
 import { tenantApi } from "../api/http/app.js";
+import { createFsBlobStore } from "../blob/index.js";
+import { createHarnessApiServer, } from "../harness-api/server.js";
+import { harnessStatusOf } from "./status.js";
+import { startInProcessHarness, startLoopbackHarness, } from "../harness-api/in-process.js";
+import { localWorkspace, remoteWorkspace, withPodWorkspaces, } from "../harness-api/workspace.js";
+import { hostAuthority } from "../sandbox/join.js";
+import { reconcileSandbox } from "../sandbox/pods/reconcile.js";
+import { sandboxWorkspaceReader } from "../artifacts/workspace.js";
 /** Default ownership lease of an advance; the heartbeat renews it every third. */
 const DEFAULT_OWNER_LEASE_MS = 30_000;
 function validateConfig(config) {
@@ -45,16 +54,24 @@ export class TenantRuntime {
     worker;
     detach;
     closeGraceMs;
+    harness;
+    hosts;
     constructor(ctx, envelope, 
     /** This Tenant's Worker handlers, as registered with the execution. */
     worker, detach, 
     /** How long close waits for running advances: the execution's advance grace period. */
-    closeGraceMs) {
+    closeGraceMs, harness, hosts) {
         this.ctx = ctx;
         this.envelope = envelope;
         this.worker = worker;
         this.detach = detach;
         this.closeGraceMs = closeGraceMs;
+        this.harness = harness;
+        this.hosts = hosts;
+    }
+    /** The Tenant's side of a sandbox pod's join (F7.2). */
+    hostAuthority() {
+        return this.ctx.closing || this.ctx.closed ? undefined : this.hosts;
     }
     static async open(config, hooks) {
         const envelope = hooks.envelope;
@@ -69,6 +86,7 @@ export class TenantRuntime {
         const store = hooks.store;
         let wired;
         let detach;
+        let harness;
         try {
             // With the keys service (F4.2) the key lives in the gateway: this process never reads,
             // creates or holds it, and the gateway reports a missing key on its readiness.
@@ -108,31 +126,63 @@ export class TenantRuntime {
             const toolGate = hooks.toolGate ?? inProcessToolGate(config.delivery ?? {});
             const signingKeys = new SigningKeys({ tenantId: config.tenantId, kek: ensureKek });
             const keys = hooks.keys ?? inProcessKeys({ store: opened, vault, signingKeys, kek: ensureKek });
-            const mcp = new McpPool({
-                pluginData: paths.pluginData,
-                childEnv: config.childEnv,
-                authorize: (sessionId, request) => authorize(ctx, sessionId, request),
-                ...(toolGate.openMcp ? { openRemote: (server) => toolGate.openMcp(server) } : {}),
-            });
+            const harnessMode = hooks.harness ?? "memory";
+            const inProcess = harnessMode === "memory" || harnessMode === "json";
+            const preference = seededBackend ?? config.sandbox.backend;
+            // With a harness in this process, the Tenant's MCP pool and SandboxManager are its
+            // executors; otherwise the harness holds both (F6.2).
+            const mcp = inProcess
+                ? new McpPool({
+                    pluginData: paths.pluginData,
+                    childEnv: config.childEnv,
+                    authorize: (sessionId, request) => authorize(ctx, sessionId, request),
+                    ...(toolGate.openMcp ? { openRemote: (server) => toolGate.openMcp(server) } : {}),
+                })
+                : undefined;
             const ephemeral = config.mode === "ephemeral";
-            const sandbox = new SandboxManager({
-                scope: config.tenantId,
-                store: opened,
-                backends: config.sandbox.backends ??
-                    defaultSandboxBackends({ root: paths.sandboxes }),
-                preference: seededBackend ?? config.sandbox.backend,
-                ephemeral,
-                emit: async (sessionId, turnId, type, payload) => {
-                    if (ctx.closed)
-                        return;
-                    try {
-                        await opened.tx((t) => t.event(sessionId, turnId, type, payload));
-                    }
-                    catch {
-                        /* the session is gone (reset) or the store closed */
-                    }
-                },
-            });
+            const manager = inProcess
+                ? new SandboxManager({
+                    scope: config.tenantId,
+                    records: storeSandboxRecords(opened),
+                    backends: config.sandbox.backends ??
+                        defaultSandboxBackends({ root: paths.sandboxes }),
+                    preference,
+                    ephemeral,
+                    emit: async (sessionId, turnId, type, payload) => {
+                        if (ctx.closed)
+                            return;
+                        try {
+                            await opened.tx((t) => t.event(sessionId, turnId, type, payload));
+                        }
+                        catch {
+                            /* the session is gone (reset) or the store closed */
+                        }
+                    },
+                })
+                : undefined;
+            let harnessServer;
+            const workspaces = manager
+                ? localWorkspace(manager)
+                : remoteWorkspace({
+                    get server() {
+                        return harnessServer;
+                    },
+                    store: opened,
+                    logger: config.logger,
+                    preference,
+                });
+            // A pod sandbox's workspace is in its pod, served by its engine (F7.2).
+            const sandbox = hooks.pods
+                ? withPodWorkspaces(workspaces, {
+                    get server() {
+                        return harnessServer;
+                    },
+                    store: opened,
+                    logger: config.logger,
+                    preference,
+                    isPod: async (sandboxId) => (await opened.tx((t) => t.sandboxResource(sandboxId)))?.kind === "pod",
+                })
+                : workspaces;
             const useVaultModel = config.model.kind === "vault";
             let modelProvider;
             if (hooks.modelProvider)
@@ -143,6 +193,7 @@ export class TenantRuntime {
                 modelProvider = toolFixtureModel();
             else
                 modelProvider = scriptedModel();
+            const blobs = hooks.blobs ?? createFsBlobStore({ root: paths.blobs });
             // With the gates service the loop never reads a model credential: only a Runtime
             // without one (embedding, the ephemeral Runtime, tests) reads it here.
             const modelGate = hooks.modelGate ??
@@ -151,40 +202,47 @@ export class TenantRuntime {
                     kek: ensureKek,
                     root: paths.home,
                     logger: config.logger,
+                    blobs,
                     ...(config.modelCall ? { settings: config.modelCall } : {}),
                 });
             const sessionStreams = createSessionStreams();
+            const workers = hooks.execution?.workers ?? new TenantWorkers();
             const local = hooks.execution
                 ? undefined
                 : new MemoryExecution({
                     sweepIntervalMs: config.sweepIntervalMs ?? Math.min(config.leaseMs ?? 30_000, 5000),
+                    // Close's `detach` step waits no longer for running work than for its advances.
+                    stopGraceMs: workers.graceMs,
                     onError: (error) => config.logger.error("tenant execution failed", {
                         message: error instanceof Error ? error.message : String(error),
                     }),
                 });
-            const { execution, workers } = hooks.execution ?? {
-                execution: local,
-                workers: new TenantWorkers(),
-            };
+            const execution = hooks.execution?.execution ?? local;
             const sweepHooks = new Set();
             ctx = {
                 config,
                 envelope,
                 store: opened,
                 vault,
-                mcp,
+                ...(mcp ? { mcp } : {}),
                 sandbox,
                 flowLimits,
                 modelProvider,
                 useVaultModel,
                 modelGate,
                 toolGate,
+                get harness() {
+                    return harnessServer;
+                },
                 closing: false,
                 closed: false,
                 work: createWorkState(),
                 sessionStreams,
                 signingKeys,
                 keys,
+                blobs,
+                workspaces: sandboxWorkspaceReader(sandbox),
+                ...(hooks.runGrants ? { runGrants: hooks.runGrants } : {}),
                 workerId: hooks.workerId ?? WORKER_ID,
                 ownerLeaseMs: config.ownerLeaseMs ?? DEFAULT_OWNER_LEASE_MS,
                 wake: async (sessionId, wake) => {
@@ -198,6 +256,12 @@ export class TenantRuntime {
                         return;
                     await execution.deliver(config.tenantId, actionId);
                 },
+                ...(hooks.pods ? { pods: hooks.pods } : {}),
+                sandboxSignal: async (sandboxId, signal) => {
+                    if (ctx.closing || ctx.closed || !execution.sandbox)
+                        return;
+                    await execution.sandbox(config.tenantId, sandboxId, signal);
+                },
                 ...(hooks.execution?.stuckInvocations
                     ? {
                         stuckInvocations: () => hooks.execution.stuckInvocations(config.tenantId),
@@ -209,6 +273,16 @@ export class TenantRuntime {
                     return () => sweepHooks.delete(hook);
                 },
             };
+            harnessServer = createHarnessApiServer(ctx, { sandboxPreference: preference });
+            if (mcp && manager)
+                harness = await startInProcessHarness(ctx, { mcp, sandbox: manager }, {
+                    json: harnessMode === "json",
+                    ...(hooks.harnessTap ? { tap: hooks.harnessTap } : {}),
+                });
+            else if (harnessMode === "ws")
+                harness = await startLoopbackHarness(ctx, {
+                    ...(config.sandbox.backends ? { sandboxBackends: config.sandbox.backends } : {}),
+                });
             wired = await wireStreams(ctx, {
                 store: opened,
                 streams: hooks.streams ?? new MemoryStreams(),
@@ -223,6 +297,7 @@ export class TenantRuntime {
                 advance: (sessionId, signal) => advance(ctx, sessionId, signal),
                 deliver: (actionId, signal) => deliverAction(ctx, actionId, signal),
                 sweep: () => sweep(ctx),
+                sandbox: (sandboxId, trigger) => reconcileSandbox(ctx, sandboxId, trigger),
             };
             const unregister = workers.register(config.tenantId, worker);
             detach = async () => {
@@ -232,10 +307,11 @@ export class TenantRuntime {
             if (local)
                 await local.start(workers.handlers);
             await execution.armSweep(config.tenantId);
-            return new TenantRuntime(ctx, envelope, worker, detach, workers.graceMs);
+            return new TenantRuntime(ctx, envelope, worker, detach, workers.graceMs, harness, hooks.pods ? hostAuthority(ctx) : undefined);
         }
         catch (error) {
             await detach?.().catch(() => undefined);
+            await harness?.stop().catch(() => undefined);
             await wired?.close().catch(() => undefined);
             await store.close().catch(() => undefined);
             throw error;
@@ -256,6 +332,7 @@ export class TenantRuntime {
             inFlightDeliveries: [...this.ctx.work.deliveries.values()].reduce((n, set) => n + set.size, 0),
             pendingActions: counts.pendingActions,
             uncertainEffects: counts.uncertainEffects,
+            harness: harnessStatusOf(this.ctx),
         };
     }
     drain(activeWork, timeoutMs = 30_000) {
@@ -279,6 +356,9 @@ export class TenantRuntime {
     onSweep(hook) {
         return this.ctx.onSweep(hook);
     }
+    attachHarness(channel, peer) {
+        return this.ctx.harness.attach(channel, peer);
+    }
     async close() {
         const ctx = this.ctx;
         ctx.closing = true;
@@ -289,10 +369,18 @@ export class TenantRuntime {
         // error is rethrown at the end.
         const steps = [
             ["detach", () => this.detach()],
-            ["mcp", () => ctx.mcp.close()],
+            ["mcp", () => ctx.mcp?.close()],
             ["session streams", () => endAllStreams(ctx.sessionStreams)],
             // Bounded: an advance that ignores its abort is abandoned; its lease lapses (§11.4).
             ["idle", () => waitForIdle(ctx, Math.max(0, idleBy - Date.now()))],
+            [
+                "harness",
+                async () => {
+                    ctx.harness.close();
+                    // Advances still running were abandoned at "idle": their runs are left behind too.
+                    await this.harness?.stop(Math.max(0, idleBy - Date.now()));
+                },
+            ],
             ["sandbox", () => ctx.sandbox.close()],
             [
                 "streams",

package/dist/tenant/sandboxes.d.ts

@@ -0,0 +1,119 @@
+/**
+ * Sandboxes as a resource (blueprint D39, F7.1; Host feature `sandboxes`): `PUT`, `GET` and
+ * `DELETE /v1/sandboxes/{id}`, the list by label, sessions attaching with `sandbox: { id }`, and
+ * the checks every turn start makes on the sandbox its session is attached to.
+ *
+ * - **No scope.** The Runtime decides nothing about who shares a sandbox. It stores the
+ *   sandbox's id, kind, spec and labels, and the session body names the sandbox it is attached
+ *   to (`Session.sandboxId`); deleting a session (a sessions reset) only detaches it.
+ * - **Access.** An application key reaches every sandbox, and so does an application key acting
+ *   for a subject (`Nylorun-Subject`), which needs `sandboxes:write` to change one. A subject
+ *   token reaches only the ids its `sbx` grants match, and changes them only with
+ *   `sandboxes:write`; any other id is the 404 of a missing one.
+ * - **Serial turns.** One turn at a time per sandbox: a session whose sandbox another attached
+ *   session's turn holds is refused (`409 sandbox_busy`), as the session sandbox route is
+ *   refused while its session's turn runs. Commands within the workspace keep queueing in the
+ *   Sandbox Manager.
+ * - **Kinds.** `virtual`: its workspace is the virtual backend's, keyed by the sandbox id
+ *   (`SandboxManager.sandboxKeyOf`) and created on the first tool call. `pod` (F7.2, Host feature
+ *   `sandbox-pods`): an agent-sandbox pod on the Tenant's cluster, created at once, whose engine
+ *   runs the turns of the sessions attached to it. Its lifecycle (`sandbox/pods/lifecycle.ts`)
+ *   runs in the `Sandbox` object: this module records what is wanted (`desired`, `rev`) and asks
+ *   for a reconcile after the commit (`ctx.sandboxSignal`). Without sandbox pods kind `pod` is
+ *   `409 sandbox_unavailable`. `POST .../stop` suspends a pod (the volume is kept; the next turn
+ *   starts it), `POST .../reset` gives it a new pod on a new volume. An expired pod refuses
+ *   turns (`sandbox_expired`) until a `PUT` sets a longer `lifecycle.ttl`; a lost one
+ *   (`sandbox_lost`) until a reset. Deleting a pod sandbox keeps its row (`desired: deleted`,
+ *   invisible here) until its Sandbox is gone.
+ * - **Lifecycle events** go to the sandbox's own stream in the record (`Tx.sandboxEvent`,
+ *   `record/sandbox.ts`); the session's log records `sandbox.attached` too.
+ */
+import { type PutSandboxRequest, type SandboxView } from "@nylorun/core/contracts";
+import type { SandboxResource, Tx } from "../store/types.js";
+import type { AuthScope, Session, TenantContext } from "./context.js";
+/** The `sbx` grants that limit `scope`, or undefined when it reaches every sandbox. */
+export declare function sandboxGrantsOf(scope: AuthScope): readonly string[] | undefined;
+/** A sandbox resource, unless it is gone or being deleted. */
+export declare function liveSandbox(t: Tx, id: string, options?: {
+    lock?: boolean;
+}): Promise<SandboxResource | undefined>;
+/**
+ * `PUT /v1/sandboxes/{id}`: creates the sandbox (within the Tenant's limit on their number), or
+ * finds the one with this id, so "get or create" is one call. The spec is fixed once it exists;
+ * labels, when sent, replace its labels. On an existing pod sandbox it also starts a stopped or
+ * failed pod again, and a new `lifecycle.ttl` sets a new expiry (reviving an expired one).
+ */
+export declare function putSandbox(ctx: TenantContext, id: string, body: PutSandboxRequest, scope: AuthScope): Promise<SandboxView>;
+/** `GET /v1/sandboxes/{id}`. */
+export declare function getSandbox(ctx: TenantContext, id: string, scope: AuthScope): Promise<SandboxView>;
+/** `GET /v1/sandboxes?label=k=v`: every sandbox with all the labels, that the caller reaches. */
+export declare function listSandboxes(ctx: TenantContext, labels: Record<string, string>, scope: AuthScope): Promise<{
+    sandboxes: SandboxView[];
+}>;
+/**
+ * `DELETE /v1/sandboxes/{id}`: deletes the sandbox and its workspace. Refused while a session
+ * attached to it has an active turn. Sessions stay attached by id: their next turn is refused
+ * (`sandbox_unavailable`) unless a sandbox with this id exists again. A pod sandbox's row stays
+ * (`desired: deleted`) until its Sandbox is gone.
+ */
+export declare function deleteSandbox(ctx: TenantContext, id: string, scope: AuthScope): Promise<{
+    id: string;
+    deleted: boolean;
+}>;
+/**
+ * `POST /v1/sandboxes/{id}/stop`: suspends a pod sandbox. Its volume is kept, and the next turn
+ * of a session attached to it (or a `PUT`) starts it again. Refused during a turn.
+ */
+export declare function stopSandbox(ctx: TenantContext, id: string, scope: AuthScope): Promise<SandboxView>;
+/**
+ * `POST /v1/sandboxes/{id}/reset`: a new pod on a new, empty volume (the next volume
+ * generation), with a new join token; the old Sandbox and volume are deleted. Leaves `lost` and
+ * `failed`; an expired sandbox stays expired. Refused during a turn, and while an earlier
+ * reset's Sandbox is still being deleted.
+ */
+export declare function resetSandbox(ctx: TenantContext, id: string, scope: AuthScope): Promise<SandboxView>;
+/** `GET /v1/sandboxes/{id}/events`: the sandbox's lifecycle stream. */
+export declare function sandboxEventsOf(ctx: TenantContext, id: string, scope: AuthScope, fromSeq: number | undefined): Promise<{
+    events: {
+        schema: "nylorun.sandbox-event/1";
+        eventId: string;
+        tenantId: string;
+        sandboxId: string;
+        seq: number;
+        time: string;
+        type: "sandbox.attached" | "sandbox.created" | "sandbox.deleted" | "sandbox.detached" | "sandbox.expired" | "sandbox.failed" | "sandbox.lost" | "sandbox.relaunched" | "sandbox.reset" | "sandbox.running" | "sandbox.suspended";
+        payload: Record<string, unknown>;
+    }[];
+}>;
+/**
+ * Attaches a new session to sandbox `id` (`PutSessionRequest.sandbox = { id }`): the sandbox
+ * must exist and be reachable with `grants`. Returns its spec, which the session pins. Runs in
+ * the session's transaction, after its session row lock.
+ */
+export declare function attachSandbox(t: Tx, id: string, grants: readonly string[] | undefined): Promise<SandboxResource>;
+/** Records the attachment on the session's log and on the sandbox's stream. */
+export declare function recordAttachment(t: Tx, sessionId: string, sandboxId: string): Promise<void>;
+/**
+ * Checks a turn start on a session attached to a sandbox, in the command's transaction after
+ * the session row lock: the sandbox still exists, a subject token's `sbx` grants reach it, and
+ * no other session attached to it has a turn running. Holds the sandbox row's lock until the
+ * transaction ends, so two turn starts on one sandbox are decided one after the other.
+ *
+ * A pod sandbox must also be usable: not lost (`sandbox_lost`) or expired (`sandbox_expired`),
+ * on a Runtime with sandbox pods (`sandbox_unavailable`). A stopped or failed pod is asked to
+ * run again, after the commit.
+ */
+export declare function checkSandboxTurn(t: Tx, session: Session, scope: AuthScope, ctx?: TenantContext): Promise<void>;
+/** A sessions reset detaches every session from its sandbox: each sandbox's stream says so. */
+export declare function detachAllSessions(t: Tx): Promise<void>;
+/**
+ * Marks the end of a turn's segment on pod sandbox `id`: idle counts from now, and the idle
+ * timer is armed (D34). Best effort.
+ */
+export declare function touchPodSandbox(ctx: TenantContext, id: string): Promise<void>;
+/**
+ * Re-arms the idle timer of every running pod sandbox after the Tenant's settings change, so a
+ * shorter `limits.idle` applies to pods already idle (D36: the settings are read whenever a
+ * timer is set). Best effort.
+ */
+export declare function rearmPodTimers(ctx: TenantContext): Promise<void>;