@nylorun/runtime 0.15.2-beta → 0.16.0-beta

package/dist/store/types.d.ts

@@ -55,9 +55,10 @@
  * them there (`tenant/session-streams.ts`).
  */
 import type { RecordReader } from "../streams/relay/types.js";
-import type { Action, EventPayload, EventType, LiveEvent, SessionEventOf } from "@nylorun/core/contracts";
+import type { Action, EventPayload, EventType, LiveEvent, SandboxEvent, SandboxEventPayload, SandboxEventType, SandboxKind, SandboxPodDesired, SandboxPodObserved, SessionEventOf } from "@nylorun/core/contracts";
+import type { SandboxManifest } from "@nylorun/core/define";
 import type { HostEffect } from "@nylorun/harness/run";
-import type { ModelBudgetRow, ModelUsageRow, PrincipalRow, ToolCrossingRow, PublishableKeyRow, SigningKeyRow, SubjectUsageRow, VaultAuditRow, VaultCredentialRow, VaultIdempotencyRow, VaultRow } from "./postgres/schema.js";
+import type { ArtifactRow, ArtifactVersionRow, ModelBudgetRow, ModelUsageRow, PrincipalRow, ToolCrossingRow, PublishableKeyRow, SigningKeyRow, SubjectUsageRow, VaultAuditRow, VaultCredentialRow, VaultIdempotencyRow, VaultRow } from "./postgres/schema.js";
 /** Tables holding JSON documents keyed by `id`. */
 export type DocTable = "definitions" | "sessions" | "commands" | "effects" | "actions" | "sandboxes" | "links";
 export declare const DOC_TABLES: readonly DocTable[];
@@ -80,6 +81,12 @@ export interface SessionOwnership {
     /** ISO time the owner's lease ends, or null without an owner. */
     ownerExpiresAt: string | null;
 }
+/** A session's lease epoch, status and active turn: what a run token must still match. */
+export interface SessionRunState {
+    readonly epoch: number;
+    readonly status: string;
+    readonly activeTurnId: string | null;
+}
 /**
  * The fields of a session document that the store indexes. The
  * Runtime's own session type extends this; everything else in the body is
@@ -115,6 +122,50 @@ export interface DefinitionDoc {
 export interface SandboxDoc {
     key: string;
 }
+/** A sandbox resource (`sandbox_resources`): what `PUT /v1/sandboxes/{id}` created. */
+export interface SandboxResource {
+    id: string;
+    kind: SandboxKind;
+    /** The spec resolved against the Tenant's limits when the sandbox was created. */
+    spec: SandboxManifest;
+    labels: Record<string, string>;
+    createdAt: string;
+    updatedAt: string;
+    /** Kind `pod`: the pod's lifecycle (F7.2). Absent for a virtual sandbox. */
+    pod?: SandboxPodState;
+}
+/**
+ * A pod sandbox's lifecycle columns (`sandbox_resources`, F7.2, D34): what the Runtime wants
+ * (`desired`), what it last saw (`observed`), and the fences of its incarnations.
+ */
+export interface SandboxPodState {
+    /** The agent-sandbox Sandbox's name (`podName`), of generation `volumeGen`. */
+    k8sName: string;
+    volumeGen: number;
+    desired: SandboxPodDesired;
+    observed: SandboxPodObserved;
+    /** The UID of the pod that last joined. */
+    podUid?: string;
+    /** Bumped by every join, relaunch, loss and reset; host and egress tokens carry it. */
+    hostEpoch: number;
+    /** sha256 hex of the incarnation's join token. */
+    joinTokenHash?: string;
+    /** Bumped by every change asked of the pod (the sandboxes service's `opId`). */
+    rev: number;
+    /** ISO times. */
+    lastActiveAt?: string;
+    expiresAt?: string;
+    startedAt?: string;
+    reason?: string;
+    /** An earlier incarnation's Sandbox still to delete (after a reset or a loss). */
+    retiring?: string;
+    /** The id the engine keeps on the volume, from the first join. */
+    volumeId?: string;
+}
+/** A change to a pod's columns: `null` clears an optional one. */
+export type SandboxPodPatch = {
+    [K in keyof SandboxPodState]?: undefined extends SandboxPodState[K] ? SandboxPodState[K] | null : SandboxPodState[K];
+};
 /** A session as read from the store: its document plus the store-managed ownership fields. */
 export type StoredSession<T extends SessionDoc = SessionDoc> = T & SessionOwnership;
 /** A link row together with the agent session it names. */
@@ -194,7 +245,7 @@ export type EndpointHealthUpdate =
  * Tenant's signing keys, a subject's turn bucket, a publishable key, a model call in the usage
  * ledger and a model budget.
  */
-export type { ModelBudgetRow, ModelUsageRow, ToolCrossingRow, PrincipalRow, PublishableKeyRow, SigningKeyRow, SubjectUsageRow, VaultAuditRow, VaultCredentialRow, VaultIdempotencyRow, VaultRow, };
+export type { ArtifactRow, ArtifactVersionRow, ModelBudgetRow, ModelUsageRow, ToolCrossingRow, PrincipalRow, PublishableKeyRow, SigningKeyRow, SubjectUsageRow, VaultAuditRow, VaultCredentialRow, VaultIdempotencyRow, VaultRow, };
 /** Which rows of the usage ledger a total covers. */
 export interface ModelUsageQuery {
     scope: "tenant" | "agent" | "turn";
@@ -340,6 +391,11 @@ export interface Tx {
      * advance calls this first; see `ownedTx` in `store/ownership.ts`.
      */
     assertEpoch<T extends SessionDoc = SessionDoc>(sessionId: string, epoch: number): Promise<StoredSession<T>>;
+    /**
+     * What a run token's live check reads of a session (F5 gate trust): its lease epoch, status
+     * and active turn, without the body. Undefined when the session is gone. Does not lock.
+     */
+    runState(sessionId: string): Promise<SessionRunState | undefined>;
     sessionsWithStatus<T extends SessionDoc = SessionDoc>(statuses: readonly (SessionStatus | (string & {}))[]): Promise<StoredSession<T>[]>;
     /**
      * Sessions `running` or `runnable` with no owner or an owner whose lease
@@ -353,6 +409,37 @@ export interface Tx {
     }): Promise<StoredSession<T>[]>;
     listDefinitions<T extends DefinitionDoc = DefinitionDoc>(): Promise<T[]>;
     listSandboxes<T extends SandboxDoc = SandboxDoc>(): Promise<T[]>;
+    /** The sandbox resource `id`; with `lock`, its row is locked until the transaction ends. */
+    sandboxResource(id: string, options?: {
+        lock?: boolean;
+    }): Promise<SandboxResource | undefined>;
+    /**
+     * Creates the sandbox resource unless one with its id exists, while the Tenant holds fewer
+     * than `limit`: `exists` and `limit` write nothing. Serialized with every other create.
+     */
+    createSandboxResource(row: SandboxResource, limit: number): Promise<"created" | "exists" | "limit">;
+    updateSandboxLabels(id: string, labels: Record<string, string>, updatedAt: string): Promise<void>;
+    /** Replaces a sandbox's spec (a pod's new `lifecycle.ttl`; the caller holds the row's lock). */
+    updateSandboxSpec(id: string, spec: SandboxManifest, updatedAt: string): Promise<void>;
+    /** Changes a pod sandbox's lifecycle columns (the caller holds the row's lock). */
+    updateSandboxPod(id: string, patch: SandboxPodPatch, updatedAt: string): Promise<void>;
+    deleteSandboxResource(id: string): Promise<void>;
+    /** Sandbox resources by id, those with every label in `labels` when it is given. */
+    listSandboxResources(filter?: {
+        labels?: Record<string, string>;
+    }): Promise<SandboxResource[]>;
+    /** Sessions attached to sandbox resource `sandboxId` (`Session.sandboxId`), by id. */
+    sessionsOnSandbox<T extends SessionDoc = SessionDoc>(sandboxId: string): Promise<StoredSession<T>[]>;
+    /**
+     * Appends an event to the sandbox's lifecycle stream through the record module. The caller
+     * holds the sandbox row's lock (or created the row in this transaction).
+     */
+    sandboxEvent<T extends SandboxEventType>(sandboxId: string, type: T, payload: SandboxEventPayload<T>): Promise<SandboxEvent>;
+    /** The sandbox's lifecycle stream, from `fromSeq` on, at most `limit` events. */
+    sandboxEvents(sandboxId: string, options?: {
+        fromSeq?: number;
+        limit?: number;
+    }): Promise<SandboxEvent[]>;
     /** One agent's `pending` actions, delivered when its endpoint is registered. */
     pendingActions(agentId: string): Promise<ActionDoc[]>;
     /** How many of one agent's actions are `delivering` (Action endpoints). */
@@ -476,17 +563,67 @@ export interface Tx {
     settleToolCrossing(key: string, answer: unknown, settledAt: string): Promise<void>;
     /** Deletes rows that settled before `before`; returns how many. */
     pruneToolCrossings(before: string): Promise<number>;
+    /** The artifact `id`; with `lock`, its row is locked until the transaction ends. */
+    artifact(id: string, options?: {
+        lock?: boolean;
+    }): Promise<ArtifactRow | undefined>;
+    /** Artifacts by creation time, then id: those of one session when `sessionId` is given. */
+    listArtifacts(filter?: {
+        sessionId?: string;
+    }): Promise<ArtifactRow[]>;
+    /** Writes a new artifact with its first version. Rejects on a duplicate id. */
+    insertArtifact(row: ArtifactRow, version: ArtifactVersionRow): Promise<void>;
+    /**
+     * Adds the next version of a locked artifact and makes it the latest (its content type and
+     * `updatedAt` follow the version).
+     */
+    insertArtifactVersion(version: ArtifactVersionRow): Promise<void>;
+    /** One version, or every version oldest first. */
+    artifactVersion(artifactId: string, version: number): Promise<ArtifactVersionRow | undefined>;
+    artifactVersions(artifactId: string): Promise<ArtifactVersionRow[]>;
+    /** Deletes the artifact and its versions; returns the versions' blob keys (empty when none). */
+    deleteArtifact(id: string): Promise<string[]>;
+    /**
+     * Serializes the Tenant's artifact writes: held until the transaction ends. Take it before
+     * reading the total a new version must fit under.
+     */
+    lockArtifactQuota(): Promise<void>;
+    /**
+     * The bytes the artifacts store: every file version, plus each distinct content-addressed file
+     * of the folders once (F8.2).
+     */
+    artifactBytes(): Promise<number>;
+    /**
+     * The blob keys of every artifact version (a folder's: its manifests): of session artifacts
+     * only, or of all of them.
+     */
+    artifactBlobKeys(scope: "sessions" | "all"): Promise<string[]>;
+    /** Records the distinct content-addressed files a folder version references (F8.2). */
+    insertArtifactContent(artifactId: string, version: number, files: readonly {
+        sha256: string;
+        size: number;
+    }[]): Promise<void>;
+    /** Those of `shas` some committed folder version references. */
+    referencedArtifactContent(shas: readonly string[]): Promise<Set<string>>;
+    /**
+     * The distinct content-addressed files folder versions reference: of one artifact, of session
+     * artifacts only, or of all of them.
+     */
+    artifactContentShas(scope: "sessions" | "all" | {
+        artifactId: string;
+    }): Promise<string[]>;
     getSetting(key: string): Promise<string | undefined>;
     putSetting(key: string, value: string): Promise<void>;
     /**
      * Deletes Tenant state by scope, in this transaction:
      * - `sessions`: sessions, commands, effects, actions, links, subject turn
-     *   buckets and the Tenant's record rows and log heads. The Tenant moves to the next basin
+     *   buckets, the artifacts of sessions (their blobs are the caller's to delete) and the
+     *   Tenant's record rows and log heads. The Tenant moves to the next basin
      *   generation and the current one is retired, so session ids it frees start again in an
      *   empty basin;
-     * - `sandboxes`: sandbox records;
+     * - `sandboxes`: sandbox records, sandbox resources and their lifecycle streams;
      * - `all`: both, plus definitions, Action endpoints, user vaults with their credentials,
-     *   the model usage ledger and the model budgets. The host vault, principals, signing keys, subject epochs,
+     *   the model usage ledger, the model budgets and Tenant-wide artifacts. The host vault, principals, signing keys, subject epochs,
      *   publishable keys, settings, audit and vault idempotency rows stay.
      */
     reset(scope: ResetScope): Promise<void>;

package/dist/streams/control.d.ts

@@ -6,6 +6,8 @@
 import { type DurableStreams } from "./types.js";
 /** Appends a `session.cancel` signal: the process running the session's advance aborts it. */
 export declare function signalCancel(streams: DurableStreams, basin: string, sessionId: string, turnId?: string): Promise<void>;
+/** Appends an `action.resolved` signal: a run held for the Action goes on with its outcome. */
+export declare function signalActionResolved(streams: DurableStreams, basin: string, sessionId: string, actionId: string): Promise<void>;
 /**
  * Appends a `sessions.reset` signal to the old generation's basin: every process with the
  * Tenant open moves its readers to `generation` and ends the streams of deleted sessions.

package/dist/streams/control.js

@@ -15,6 +15,11 @@ export async function signalCancel(streams, basin, sessionId, turnId) {
     };
     await streams.append(basin, CONTROL_STREAM, [signal]);
 }
+/** Appends an `action.resolved` signal: a run held for the Action goes on with its outcome. */
+export async function signalActionResolved(streams, basin, sessionId, actionId) {
+    const signal = { type: "action.resolved", sessionId, actionId };
+    await streams.append(basin, CONTROL_STREAM, [signal]);
+}
 /**
  * Appends a `sessions.reset` signal to the old generation's basin: every process with the
  * Tenant open moves its readers to `generation` and ends the streams of deleted sessions.

package/dist/streams/types.d.ts

@@ -147,4 +147,13 @@ export interface SubjectRevokedSignal {
     subject: string;
     epoch: number;
 }
-export type ControlSignal = SessionCancelSignal | SessionsResetSignal | SubjectRevokedSignal;
+/**
+ * An Action of `sessionId` has its outcome (F6.2): the process whose harness holds the
+ * session's run while the Action is pending passes it on (`effect.resolved`).
+ */
+export interface ActionResolvedSignal {
+    type: "action.resolved";
+    sessionId: string;
+    actionId: string;
+}
+export type ControlSignal = SessionCancelSignal | SessionsResetSignal | SubjectRevokedSignal | ActionResolvedSignal;