@nylorun/runtime 0.15.1-beta → 0.16.0-beta

package/dist/record/index.d.ts

@@ -9,3 +9,4 @@
 export { buildEvent, InvalidEventError, type EventInput } from "./envelope.js";
 export { decodeCursor, encodeCursor } from "./cursor.js";
 export { appendEvent, type AppendInput, type RecordWriter } from "./append.js";
+export { appendSandboxEvent, buildSandboxEvent, type SandboxAppendInput, type SandboxRecordWriter, } from "./sandbox.js";

package/dist/record/index.js

@@ -9,3 +9,4 @@
 export { buildEvent, InvalidEventError } from "./envelope.js";
 export { decodeCursor, encodeCursor } from "./cursor.js";
 export { appendEvent } from "./append.js";
+export { appendSandboxEvent, buildSandboxEvent, } from "./sandbox.js";

package/dist/record/sandbox.d.ts

@@ -0,0 +1,25 @@
+import { type SandboxEvent, type SandboxEventPayload, type SandboxEventType } from "@nylorun/core/contracts";
+/** The sandbox stream's two statements, in the caller's transaction. */
+export interface SandboxRecordWriter {
+    /** The seq the sandbox's next event takes: one past its last, or 0. */
+    nextSeq(sandboxId: string): Promise<number>;
+    insert(row: {
+        sandboxId: string;
+        seq: number;
+        type: string;
+        body: SandboxEvent;
+    }): Promise<void>;
+}
+export interface SandboxAppendInput<T extends SandboxEventType> {
+    tenantId: string;
+    sandboxId: string;
+    time: Date;
+    type: T;
+    payload: SandboxEventPayload<T>;
+}
+/** Builds the event and checks it against the sandbox event catalog. */
+export declare function buildSandboxEvent<T extends SandboxEventType>(input: SandboxAppendInput<T> & {
+    seq: number;
+}): SandboxEvent;
+/** Appends one event to the sandbox's stream through `writer`. */
+export declare function appendSandboxEvent<T extends SandboxEventType>(writer: SandboxRecordWriter, input: SandboxAppendInput<T>): Promise<SandboxEvent>;

package/dist/record/sandbox.js

@@ -0,0 +1,43 @@
+/**
+ * A sandbox's lifecycle stream (blueprint D39, F7.1): `sandbox.created`, `sandbox.attached`,
+ * `sandbox.detached` and `sandbox.deleted`, on the `nylorun.sandbox-event/1` envelope, numbered
+ * from 0 per sandbox id in `nylorun_streams.sandbox_events`. The record module is its only
+ * writer, as for session events; the store runs the two statements through
+ * `SandboxRecordWriter` in the caller's transaction, under the sandbox row's lock (or, for a
+ * sandbox being created, its new row).
+ *
+ * The stream lives in the record only: it is not published to the stream relay, so no S2
+ * stream follows it yet. Clients read it with `GET /v1/sandboxes/{id}/events`.
+ */
+import { randomUUID } from "node:crypto";
+import { z } from "zod";
+import { SANDBOX_EVENT_PAYLOADS, SANDBOX_EVENT_SCHEMA, SandboxEventSchema, } from "@nylorun/core/contracts";
+import { InvalidEventError } from "./envelope.js";
+/** Builds the event and checks it against the sandbox event catalog. */
+export function buildSandboxEvent(input) {
+    const payload = SANDBOX_EVENT_PAYLOADS[input.type];
+    const checkedPayload = payload.safeParse(input.payload);
+    if (!checkedPayload.success)
+        throw new InvalidEventError(input.type, z.prettifyError(checkedPayload.error));
+    const event = JSON.parse(JSON.stringify({
+        schema: SANDBOX_EVENT_SCHEMA,
+        eventId: randomUUID(),
+        tenantId: input.tenantId,
+        sandboxId: input.sandboxId,
+        seq: input.seq,
+        time: input.time.toISOString(),
+        type: input.type,
+        payload: input.payload,
+    }));
+    const checked = SandboxEventSchema.safeParse(event);
+    if (!checked.success)
+        throw new InvalidEventError(input.type, z.prettifyError(checked.error));
+    return event;
+}
+/** Appends one event to the sandbox's stream through `writer`. */
+export async function appendSandboxEvent(writer, input) {
+    const seq = await writer.nextSeq(input.sandboxId);
+    const event = buildSandboxEvent({ ...input, seq });
+    await writer.insert({ sandboxId: input.sandboxId, seq, type: input.type, body: event });
+    return event;
+}

package/dist/sandbox/capability.d.ts

@@ -0,0 +1,3 @@
+import { type AgentManifest, type CapabilityManifest } from "@nylorun/core/define";
+/** The sandbox capability that owns this tool call, when the call is a built-in sandbox tool. */
+export declare function sandboxCapabilityOf(manifest: AgentManifest | undefined, capabilityId: string | undefined, toolName: string | undefined): CapabilityManifest | undefined;

package/dist/sandbox/capability.js

@@ -0,0 +1,10 @@
+import { isSandboxToolName, } from "@nylorun/core/define";
+/** 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;
+}

package/dist/sandbox/egress-token.d.ts

@@ -0,0 +1,26 @@
+/**
+ * Egress tokens (F7.2, D42), as egress-gate sees them: the proxy credential a pod's engine
+ * receives at join with its host token (`sandbox/join.ts`) and presents in `Proxy-Authorization`.
+ * Minted and verified by `tenant/host-token.ts`, the one place host and egress tokens are made:
+ *
+ * ```text
+ * header  { alg: ES256, typ: nylorun-egress+jwt, kid }
+ * claims  { iss: urn:nylorun:tenant:<id>, aud: nylorun-egress, sbx: <sandboxId>,
+ *           epc: <host epoch>, pod: <pod UID>, iat, exp, jti }
+ * ```
+ *
+ * Verification checks shape and header before any key is read, then the signature, `iss`,
+ * `aud`, `typ`, lifetime and claims; whether the epoch is still the sandbox's is egress-gate's
+ * check (`EgressSandboxes.live`).
+ */
+import type { SessionStore } from "../store/types.js";
+import { EGRESS_TOKEN_AUD, EGRESS_TOKEN_TYP, mintEgressToken, type EgressTokenRequest, type HostClaims, type HostTokenKeyCache, type HostTokenVerdict } from "../tenant/host-token.js";
+export { EGRESS_TOKEN_AUD, EGRESS_TOKEN_TYP, mintEgressToken, type EgressTokenRequest };
+/** The longest lifetime an egress token has: a host token's. */
+export declare const EGRESS_TOKEN_MAX_TTL_SECONDS: number;
+export type EgressClaims = HostClaims;
+export type EgressTokenVerdict = HostTokenVerdict;
+/** Public keys imported by key id; the key row is still read on every verification. */
+export type EgressTokenKeyCache = HostTokenKeyCache;
+/** Verifies an egress token of Tenant `tenantId`; refusal reasons are `egress_token_*`. */
+export declare function verifyEgressToken(store: SessionStore, tenantId: string, raw: string, cache?: EgressTokenKeyCache): Promise<EgressTokenVerdict>;

package/dist/sandbox/egress-token.js

@@ -0,0 +1,8 @@
+import { EGRESS_TOKEN_AUD, EGRESS_TOKEN_TYP, HOST_TOKEN_TTL_SECONDS, mintEgressToken, verifyHostToken, } from "../tenant/host-token.js";
+export { EGRESS_TOKEN_AUD, EGRESS_TOKEN_TYP, mintEgressToken };
+/** The longest lifetime an egress token has: a host token's. */
+export const EGRESS_TOKEN_MAX_TTL_SECONDS = HOST_TOKEN_TTL_SECONDS;
+/** Verifies an egress token of Tenant `tenantId`; refusal reasons are `egress_token_*`. */
+export function verifyEgressToken(store, tenantId, raw, cache = new Map()) {
+    return verifyHostToken(store, tenantId, raw, "egress", cache);
+}

package/dist/sandbox/join.d.ts

@@ -0,0 +1,37 @@
+import type { TenantContext } from "../tenant/context.js";
+import { type HostClaims } from "../tenant/host-token.js";
+export interface HostJoinRequest {
+    readonly sandboxId: string;
+    readonly podUid: string;
+    readonly joinToken: string;
+    /** The id the engine keeps on the volume (`/harness/volume-id`). */
+    readonly volumeId?: string;
+}
+/** What `join` and `renew` answer. */
+export interface HostJoinAnswer {
+    readonly hostToken: string;
+    readonly egressToken: string;
+    readonly sandboxId: string;
+    readonly epoch: number;
+    /** ISO time the tokens expire. */
+    readonly expiresAt: string;
+}
+/** A refused join, renewal or host connection. */
+export declare class HostAuthError extends Error {
+    readonly status: 400 | 401 | 503;
+    /** Logged, never answered. */
+    readonly reason?: string | undefined;
+    readonly name = "HostAuthError";
+    constructor(status: 400 | 401 | 503, message: string, 
+    /** Logged, never answered. */
+    reason?: string | undefined);
+}
+/** The Tenant's side of the exchange, as the Harness API listener calls it. */
+export interface HostAuthority {
+    join(request: HostJoinRequest): Promise<HostJoinAnswer>;
+    renew(hostToken: string): Promise<HostJoinAnswer>;
+    /** The claims of a current host's token, for a connection; refuses a stale one. */
+    verify(hostToken: string): Promise<HostClaims>;
+}
+export declare function sha256Hex(value: string): string;
+export declare function hostAuthority(ctx: TenantContext): HostAuthority;

package/dist/sandbox/join.js

@@ -0,0 +1,165 @@
+/**
+ * Join token → host token (F7.2, D42): how a pod sandbox's engine becomes the sandbox's host.
+ *
+ * Core mints a join token (32 random bytes) per incarnation of a pod sandbox (a create, a
+ * reset), keeps only its sha256 (`sandbox_resources.join_token_hash`), and hands the plaintext
+ * once to the sandboxes service, which writes it to the Sandbox's join Secret, mounted in the
+ * pod. The engine exchanges it at the Harness API listener (`POST
+ * /nylorun/harness/v1/host/join`, `ws-server.ts`) with its pod's UID:
+ *
+ * 1. the hash matches, the sandbox is a pod sandbox that is neither deleted, lost nor expired;
+ * 2. the UID is the pod the sandboxes service sees in the Sandbox now (a token copied to
+ *    another pod is refused);
+ * 3. the volume is the sandbox's: the engine keeps an id on the volume (`volumeId`), recorded
+ *    at the first join of an incarnation. agent-sandbox recreates a claim that was deleted, empty;
+ *    a join from such a volume finds the sandbox `lost` (`sandbox.lost`) and is refused;
+ * 4. the host epoch is bumped: tokens of the previous host stop working, and its connection is
+ *    closed (`HarnessApiServer.revokeHost`), so its runs are given to the next advance. A pod
+ *    other than the one that joined last records `sandbox.relaunched` (same volume, new pod);
+ *    a first pod after a create, resume or reset records `sandbox.running`.
+ *
+ * The answer is a host token (`nylorun-host+jwt`, accepted only by the Harness API listener,
+ * for a connection that serves this sandbox alone) and an egress token
+ * (`nylorun-egress+jwt`, accepted only by egress-gate), both bound to the sandbox, the epoch
+ * and the pod (`tenant/host-token.ts`). `renew` mints a new pair at the same epoch while the
+ * host is current; it is refused once the epoch moved.
+ *
+ * Every refusal answers the same 401 (the reason is logged), so a caller learns nothing about
+ * which check failed.
+ */
+import { createHash, timingSafeEqual } from "node:crypto";
+import { isSandboxId } from "@nylorun/core/contracts";
+import { mintHostTokens, staleHost, verifyHostToken, } from "../tenant/host-token.js";
+/** A refused join, renewal or host connection. */
+export class HostAuthError extends Error {
+    status;
+    reason;
+    name = "HostAuthError";
+    constructor(status, message, 
+    /** Logged, never answered. */
+    reason) {
+        super(message);
+        this.status = status;
+        this.reason = reason;
+    }
+}
+const POD_UID = /^[A-Za-z0-9-]{1,64}$/;
+const REFUSED = "The join was refused";
+export function sha256Hex(value) {
+    return createHash("sha256").update(value).digest("hex");
+}
+function sameHash(a, b) {
+    const left = Buffer.from(a, "hex");
+    const right = Buffer.from(b, "hex");
+    return left.length === right.length && left.length > 0 && timingSafeEqual(left, right);
+}
+function answerOf(grant) {
+    return {
+        hostToken: grant.hostToken,
+        egressToken: grant.egressToken,
+        sandboxId: grant.claims.sandboxId,
+        epoch: grant.claims.epoch,
+        expiresAt: new Date(grant.claims.expiresAt).toISOString(),
+    };
+}
+export function hostAuthority(ctx) {
+    const cache = new Map();
+    const refuse = (reason) => {
+        throw new HostAuthError(401, REFUSED, reason);
+    };
+    const verified = async (raw) => {
+        const verdict = await verifyHostToken(ctx.store, ctx.config.tenantId, raw, "host", cache);
+        if (!verdict.ok)
+            return refuse(verdict.reason);
+        const stale = await staleHost(ctx.store, verdict.claims);
+        if (stale)
+            return refuse(stale);
+        return verdict.claims;
+    };
+    return {
+        async join(request) {
+            const { sandboxId, podUid, joinToken, volumeId } = request;
+            if (!isSandboxId(sandboxId) ||
+                typeof podUid !== "string" ||
+                !POD_UID.test(podUid) ||
+                typeof joinToken !== "string" ||
+                joinToken.length === 0 ||
+                joinToken.length > 512 ||
+                (volumeId !== undefined && (typeof volumeId !== "string" || !POD_UID.test(volumeId))))
+                throw new HostAuthError(400, "A join is { sandboxId, podUid, joinToken }");
+            const pods = ctx.pods;
+            if (!pods)
+                return refuse("this Runtime has no sandbox pods");
+            const hash = sha256Hex(joinToken);
+            const usable = (row) => {
+                const pod = row?.pod;
+                if (!row || row.kind !== "pod" || !pod)
+                    return refuse("no such pod sandbox");
+                if (!pod.joinTokenHash || !sameHash(pod.joinTokenHash, hash))
+                    return refuse("join token mismatch");
+                if (pod.desired === "deleted")
+                    return refuse("the sandbox was deleted");
+                // A pod being stopped joins nothing: its sandbox runs again only when asked to.
+                if (pod.desired !== "running")
+                    return refuse("the sandbox is stopped");
+                if (pod.observed === "lost" || pod.observed === "expired")
+                    return refuse(`the sandbox is ${pod.observed}`);
+                return pod;
+            };
+            const readRow = () => ctx.store.tx((t) => t.sandboxResource(sandboxId));
+            const before = usable(await readRow());
+            let current;
+            try {
+                current = (await pods.client.status(before.k8sName)).podUID;
+            }
+            catch (error) {
+                throw new HostAuthError(503, "The sandboxes service did not answer; try again", error instanceof Error ? error.message : String(error));
+            }
+            if (current !== podUid)
+                refuse("the pod is not the sandbox's current pod");
+            const joined = await ctx.store.tx(async (t) => {
+                const row = await t.sandboxResource(sandboxId, { lock: true });
+                const pod = usable(row);
+                if (pod.k8sName !== before.k8sName)
+                    refuse("the sandbox was reset during the join");
+                const epoch = pod.hostEpoch + 1;
+                const now = new Date().toISOString();
+                if (pod.volumeId !== undefined && volumeId !== pod.volumeId) {
+                    // A new, empty volume under the same Sandbox: the sandbox's files are gone.
+                    const reason = "The sandbox's volume was replaced: its files are gone";
+                    await t.updateSandboxPod(sandboxId, { observed: "lost", reason, hostEpoch: epoch }, now);
+                    await t.sandboxEvent(sandboxId, "sandbox.lost", { reason });
+                    return { lost: epoch };
+                }
+                await t.updateSandboxPod(sandboxId, {
+                    hostEpoch: epoch,
+                    podUid,
+                    ...(pod.volumeId === undefined && volumeId !== undefined ? { volumeId } : {}),
+                    ...(pod.desired === "running" ? { observed: "running", reason: null } : {}),
+                }, now);
+                if (pod.podUid !== podUid) {
+                    if (pod.podUid !== undefined)
+                        await t.sandboxEvent(sandboxId, "sandbox.relaunched", { hostEpoch: epoch });
+                    else
+                        await t.sandboxEvent(sandboxId, "sandbox.running", { hostEpoch: epoch });
+                }
+                return epoch;
+            });
+            if (typeof joined === "object") {
+                ctx.harness.revokeHost(sandboxId, joined.lost);
+                // Its Sandbox is deleted; only a reset brings the sandbox back.
+                await ctx.sandboxSignal(sandboxId, { kind: "reconcile" });
+                return refuse("the volume was replaced: the sandbox is lost");
+            }
+            // The previous host's connection (an older epoch) serves nothing more.
+            ctx.harness.revokeHost(sandboxId, joined);
+            ctx.config.logger.info("sandbox host joined", { sandboxId, epoch: joined });
+            return answerOf(await mintHostTokens(ctx, { sandboxId, epoch: joined, podUid }));
+        },
+        async renew(hostToken) {
+            const claims = await verified(hostToken);
+            return answerOf(await mintHostTokens(ctx, claims));
+        },
+        verify: verified,
+    };
+}

package/dist/sandbox/manager.d.ts

@@ -1,55 +1,71 @@
 /**
- * Sandbox Manager: owns sandbox lifecycle for the Runtime. One sandbox per session, created on
- * the first sandbox tool call, stopped after its idle timeout, reattached on the next call.
- * Commands against one sandbox run one at a time.
+ * Sandbox Manager: owns sandbox lifecycle for the Runtime. One workspace per sandbox resource
+ * (`sandbox: { id }`, keyed by the sandbox id), or per owning session for a sandbox chosen
+ * inline or by the Tenant default (keyed by the session id); created on the first sandbox tool
+ * call, stopped after its idle timeout, reattached on the next call. Commands against one
+ * workspace run one at a time, whichever session sends them.
  *
- * The manager keeps no timers. The Tenant sweep calls `sweep`, which stops sandboxes idle
- * past their timeout, marks records of compute this process no longer holds as stopped
- * (after a restart), and, once per process, removes sandboxes whose session is gone.
+ * The manager keeps no timers and reaches no store: it keeps its compute records through a
+ * `SandboxRecords` port (the Tenant's `sandboxes` table in core's process, a file in a harness's)
+ * and writes its events through `emit`. Its owner drives it: `stopIdle` stops sandboxes idle
+ * past their timeout and marks records of compute this process no longer holds as stopped
+ * (after a restart); `reconcile` removes workspaces whose owner is gone. `sweep` does both, the
+ * reconcile once per process, as the Tenant sweep does in core's process.
  */
 import type { EventPayload } from "@nylorun/core/contracts";
 import { type AgentManifest, type CapabilityManifest, type SandboxToolName } from "@nylorun/core/define";
-import type { SessionStore } from "../store/types.js";
+import { type SandboxRecord, type SandboxRecords } from "./records.js";
 import { type SandboxSelection, type SandboxSelectionReport } from "./select.js";
 import { type SandboxToolOutcome } from "./tools.js";
-import type { SandboxBackend } from "./types.js";
+import { type SandboxBackend, type SandboxListing } from "./types.js";
+export { sandboxCapabilityOf } from "./capability.js";
+export type { SandboxRecord, SandboxRecords, SandboxState } from "./records.js";
 export interface SandboxSessionRef {
+    /** The session whose log records the workspace's events: the owning session. */
     readonly id: string;
     readonly activeTurnId: string | null;
-    readonly manifest: AgentManifest;
+    readonly manifest?: AgentManifest;
+    /**
+     * The sandbox resource the owning session is attached to. Its workspace is keyed by this id,
+     * so every session attached to it shares the files; absent, the workspace is the session's.
+     */
+    readonly sandboxId?: string;
+    /**
+     * Who the call's events are claimed for, passed back to `emit`: in a harness, the run that
+     * made the call (its run id).
+     */
+    readonly claim?: string;
 }
-export type SandboxState = "creating" | "running" | "stopped";
-interface SandboxRecord {
-    key: string;
-    sessionId: string;
-    backend: string;
-    image: string;
-    state: SandboxState;
-    createdAt: string;
-    updatedAt: string;
+/** What `emit` gets with an event besides its payload. */
+export interface SandboxEventMeta {
+    /** With `sandbox.state`: the workspace's record as it is now. */
+    readonly record?: SandboxRecord;
+    /** The `claim` of the call that caused the event; absent for an idle stop. */
+    readonly claim?: string;
 }
 export interface SandboxSweepOptions {
     /** The sweep's clock, in ms since the epoch. Defaults to `Date.now()`. */
     readonly now?: number;
     /** Whether a session still exists; sandboxes of deleted sessions are removed. */
     readonly sessionExists: (sessionId: string) => boolean | Promise<boolean>;
+    /** Whether a sandbox resource still exists. Default: every one does. */
+    readonly sandboxExists?: (sandboxId: string) => boolean | Promise<boolean>;
 }
 export interface SandboxManagerOptions {
-    /** Distinguishes this Runtime's sandboxes from other Runtimes on the same machine. */
+    /** Distinguishes this Runtime's sandboxes from other Runtimes on the same machine: the Tenant id. */
     readonly scope: string;
-    readonly store: SessionStore;
+    /** Where the workspaces' compute records are kept. */
+    readonly records: SandboxRecords;
     readonly backends: readonly SandboxBackend[];
     /** `auto` or `virtual`. Undefined means an invalid NYLORUN_SANDBOX value. */
     readonly preference: string | undefined;
     /** Delete sandboxes on close (the Runtime's store does not outlive the process). */
     readonly ephemeral: boolean;
-    /** Writes a session event in its own transaction; never called inside one. */
-    readonly emit: <T extends SandboxEventType>(sessionId: string, turnId: string | null, type: T, payload: EventPayload<T>) => void | Promise<void>;
+    /** Writes a session event (in core, in its own transaction; in a harness, as a claim). */
+    readonly emit: <T extends SandboxEventType>(sessionId: string, turnId: string | null, type: T, payload: EventPayload<T>, meta: SandboxEventMeta) => void | Promise<void>;
 }
 /** The session events a sandbox writes. */
 export type SandboxEventType = "sandbox.state" | "sandbox.exec";
-/** The sandbox capability that owns this tool call, when the call is a built-in sandbox tool. */
-export declare function sandboxCapabilityOf(manifest: AgentManifest | undefined, capabilityId: string | undefined, toolName: string | undefined): CapabilityManifest | undefined;
 export declare class SandboxManager {
     private readonly options;
     private selection?;
@@ -59,24 +75,64 @@ export declare class SandboxManager {
     private reconciled;
     constructor(options: SandboxManagerOptions);
     /**
-     * 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).
      */
     sweep(options: SandboxSweepOptions): Promise<void>;
+    /**
+     * 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).
+     */
+    stopIdle(at?: number): Promise<void>;
+    /** Every workspace record this manager keeps. */
+    workspaces(): Promise<SandboxRecord[]>;
     /** Backends are probed once, on first use, and the choice holds for the life of the Runtime. */
     get ready(): Promise<SandboxSelection>;
     /** Whether any sandbox was ever recorded, so startup can skip probing for agents without one. */
     hasRecords(): Promise<boolean>;
     keyOf(sessionId: string): string;
+    /** The workspace key of sandbox resource `sandboxId` (`sandboxWorkspaceKey`). */
+    sandboxKeyOf(sandboxId: string): string;
+    private keyFor;
     report(): Promise<SandboxSelectionReport & {
         readonly defaultImage: string;
     }>;
     run(session: SandboxSessionRef, capability: CapabilityManifest, toolName: SandboxToolName, input: unknown, signal: AbortSignal): Promise<SandboxToolOutcome>;
+    /**
+     * 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.
+     */
+    readBytes(session: SandboxSessionRef, capability: CapabilityManifest, path: string, maxBytes: number, signal: AbortSignal): Promise<{
+        kind: "read";
+        path: string;
+        bytes: Uint8Array;
+    } | {
+        kind: "missing";
+        path: string;
+    } | Extract<SandboxToolOutcome, {
+        kind: "failed";
+    }>>;
+    /**
+     * 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.
+     */
+    listFiles(session: SandboxSessionRef, capability: CapabilityManifest, dir: string, maxEntries: number, signal: AbortSignal): Promise<{
+        kind: "listed";
+        path: string;
+        listing: SandboxListing;
+    } | {
+        kind: "missing";
+        path: string;
+    } | Extract<SandboxToolOutcome, {
+        kind: "failed";
+    }>>;
+    /** Runs `use` on the session's sandbox in its queue, starting it first when it is stopped. */
+    private withHandle;
+    /** The session's live sandbox entry and spec, or why it cannot run here. */
+    private prepare;
     private execute;
     private executeOpen;
     private open;
@@ -84,8 +140,17 @@ export declare class SandboxManager {
     private record;
     /** The sandbox record for a session, if one was ever created. */
     status(sessionId: string): Promise<SandboxRecord | undefined>;
-    /** Delete sandboxes this Runtime owns whose session no longer exists. */
-    reconcile(sessionExists: (sessionId: string) => boolean | Promise<boolean>): Promise<void>;
+    /**
+     * Deletes sandbox resource `sandboxId`'s workspace, its files and its compute record, after
+     * any command queued on it. Called once the resource is deleted.
+     */
+    removeSandbox(sandboxId: string): Promise<void>;
+    /** Deletes the workspace `key`, its files and its record, after any command queued on it. */
+    remove(key: string): Promise<void>;
+    /**
+     * 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.
+     */
+    reconcile(sessionExists: (sessionId: string) => boolean | Promise<boolean>, sandboxExists: (sandboxId: string) => boolean | Promise<boolean>): Promise<void>;
     close(): Promise<void>;
 }
-export {};