@nylorun/runtime 0.22.0-beta → 0.24.0-beta

package/dist/tenant/sandboxes.d.ts

@@ -1,122 +0,0 @@
-/**
- * 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 token
- *   caller (a trusted issuer's token) reaches only the ids its 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 { SandboxRouteDeps } from "../core/sandbox-routes.js";
-import { type AuthScope, type Session, type TenantContext } from "./context.js";
-/** The sandbox 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 token caller's 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>;
-/** Session lookups for the sandbox route handlers (`core/sandbox-routes.ts`). */
-export declare function sandboxRouteDeps(ctx: TenantContext): SandboxRouteDeps;