@nylorun/runtime 0.23.0-beta → 0.25.0-beta

package/dist/store/types.d.ts

@@ -63,8 +63,7 @@
 import type { KeyRole } from "@nylorun/core/compatibility";
 import type { RecordReader } from "../streams/relay/types.js";
 import type { SandboxSignal, Wake } from "../execution/types.js";
-import type { EventPayload, EventType, LiveEvent, SandboxEvent, SandboxEventPayload, SandboxEventType, SandboxKind, SandboxPodDesired, SandboxPodObserved, SessionEventOf } from "@nylorun/core/contracts";
-import type { SandboxManifest } from "@nylorun/core/define";
+import type { EventPayload, EventType, EventWriter, LiveEvent, EnvironmentEvent, EnvironmentEventPayload, EnvironmentEventType, EnvironmentKind, EnvironmentManifest, EnvironmentRecipe, PodDesired, PodObserved, SessionEventOf } from "@nylorun/core/contracts";
 import type { HostEffect } from "@nylorun/harness/run";
 import type { ArtifactRow, ArtifactVersionRow, DefinitionFileRow, ModelBudgetRow, ModelUsageRow, ModelUsageWrite, PrincipalRow, ToolCrossingRow, SigningKeyRow, VaultAuditRow, VaultCredentialRow, VaultIdempotencyRow, VaultRow } from "./postgres/schema.js";
 /** Tables holding JSON documents keyed by `id`. */
@@ -73,7 +72,9 @@ export declare const DOC_TABLES: readonly DocTable[];
 /** Session lifecycle (architecture §10.2). */
 export type SessionStatus = "idle" | "runnable" | "running" | "waiting" | "paused" | "uncertain" | "completed" | "failed" | "cancelled";
 /** Effect states (§10.3), plus the flow host's `queued` and `cancelled`. */
-export type EffectStatus = "pending" | "invoking" | "completed" | "uncertain" | "queued" | "cancelled";
+export type EffectStatus = "pending" | "invoking"
+/** A tool call the Tool Gate held for a person's approval (R5 step 2): nothing was sent. */
+ | "held" | "completed" | "uncertain" | "queued" | "cancelled";
 export type EffectKind = HostEffect["kind"];
 /**
  * Ownership of a session by a Worker (§10.6). Read with the session; written
@@ -126,28 +127,81 @@ export interface DefinitionDoc {
 export interface SandboxDoc {
     key: string;
 }
-/** A sandbox resource (`sandbox_resources`): what `PUT /v1/sandboxes/{id}` created. */
-export interface SandboxResource {
+/** An Environment (`environments`, D55): what `PUT /v1/environments/{id}` created. */
+export interface Environment {
     id: string;
-    kind: SandboxKind;
-    /** The spec resolved against the Tenant's limits when the sandbox was created. */
-    spec: SandboxManifest;
+    kind: EnvironmentKind;
     labels: Record<string, string>;
+    /** What the app asked for, resolved against the Tenant's limits. */
+    recipe: EnvironmentRecipe;
+    /** The recipe the current pod or workspace runs (copied from `recipe` at the next wake). */
+    applied: EnvironmentRecipe;
+    version: number;
+    appliedVersion: number;
+    /** The owner guard: only this owner's sessions may name it. */
+    ownerUserId?: string;
+    /** ISO time it was last used (`lifecycle.deleteAfter` counts from it). */
+    lastUsedAt: string;
     createdAt: string;
     updatedAt: string;
-    /** Kind `pod`: the pod's lifecycle (F7.2). Absent for a virtual sandbox. */
+    /** Kind `pod`: the pod's lifecycle (F7.2). Absent otherwise. */
     pod?: SandboxPodState;
+    /** The disk lease while a snapshot, restore or seed copies the disk (R2d step 3). */
+    diskOp?: DiskOperation;
+    /**
+     * The disk version the next volume starts from (R2d step 3). `setup` (a fork onto other setup,
+     * Q17): the setup runs once the version is written (`written`), and the seed stays until it is done.
+     */
+    diskSeed?: DiskSeed;
+    /** The environment manifest it was made from and its version (D63); absent for an inline one. */
+    manifestName?: string;
+    manifestVersion?: number;
+    /** The hash of what it runs (`recipe`), recorded at creation (protocol 14). */
+    manifestHash?: string;
+    /** The Environment it was forked from and the disk version it started from (Q15). */
+    forkedFrom?: {
+        environment: string;
+        disk: number | null;
+    };
+}
+/** A pending seed of an Environment's disk (`disk_seed`). */
+export interface DiskSeed {
+    artifactId: string;
+    version: number;
+    /** Run the setup on the seeded disk (a fork onto other setup, Q17). */
+    setup?: true;
+    /** The version is written; with `setup`, the seed waits for the setup to be done. */
+    written?: true;
+}
+/** One version of an environment manifest (`environment_manifests`, D63). */
+export interface EnvironmentManifestRow {
+    name: string;
+    version: number;
+    body: EnvironmentManifest;
+    hash: string;
+    savedBy: {
+        actor: string;
+    };
+    createdAt: string;
+}
+/** A disk lease (R2d step 3): what holds the disk, since when, and until when unless renewed. */
+export interface DiskOperation {
+    kind: "snapshot" | "restore" | "seed";
+    version?: number;
+    /** ISO times. */
+    startedAt: string;
+    until: string;
 }
 /**
- * A pod sandbox's lifecycle columns (`sandbox_resources`, F7.2, D34): what the Runtime wants
+ * A pod Environment's lifecycle columns (`environments`, 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;
+    desired: PodDesired;
+    observed: PodObserved;
     /** The UID of the pod that last joined. */
     podUid?: string;
     /** Bumped by every join, relaunch, loss and reset; host and egress tokens carry it. */
@@ -158,13 +212,17 @@ export interface SandboxPodState {
     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;
+    /**
+     * The workload image by digest (`repo@sha256:…`), recorded the first time a pod of the
+     * Environment is ready (Q14): every later pod, after a stop, a relaunch or a reset, runs it.
+     */
+    imageDigest?: string;
 }
 /** A change to a pod's columns: `null` clears an optional one. */
 export type SandboxPodPatch = {
@@ -233,7 +291,7 @@ export interface StoreCounts {
     sandboxes: number;
     definitions: number;
 }
-export type ResetScope = "sessions" | "sandboxes" | "all";
+export type ResetScope = "sessions" | "environments" | "all";
 /** Result of `takeOwnership`. */
 export type TakeOwnership = {
     status: "owned";
@@ -406,7 +464,9 @@ export interface Tx {
      * commit listeners. Rejects when the session does not exist. The returned
      * cursor is final.
      */
-    event<T extends EventType>(sessionId: string, turnId: string | null, type: T, payload: EventPayload<T>): Promise<SessionEventOf<T>>;
+    event<T extends EventType>(sessionId: string, turnId: string | null, type: T, payload: EventPayload<T>, 
+    /** Who wrote it (R4.9): absent, core, observed. */
+    writer?: EventWriter): Promise<SessionEventOf<T>>;
     /**
      * Asks for an advance of `sessionId` once this transaction commits. The request is a row
      * of the wake outbox written in this transaction, so it commits, or rolls back, with what
@@ -483,37 +543,65 @@ 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?: {
+    /** Environment `id`; with `lock`, its row is locked until the transaction ends. */
+    environment(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?: {
+    }): Promise<Environment | undefined>;
+    /**
+     * Creates the Environment unless one with its id exists, while the Tenant holds fewer than
+     * `limit`: `exists` and `limit` write nothing. Serialized with every other create.
+     */
+    createEnvironment(row: Environment, limit: number): Promise<"created" | "exists" | "limit">;
+    /**
+     * Changes an Environment's columns other than its pod's (the caller holds the row's lock):
+     * labels, recipe and version, the applied recipe and its version, the owner guard (`null`
+     * clears it), and when it was last used.
+     */
+    updateEnvironment(id: string, patch: {
+        labels?: Record<string, string>;
+        recipe?: EnvironmentRecipe;
+        version?: number;
+        applied?: EnvironmentRecipe;
+        appliedVersion?: number;
+        ownerUserId?: string | null;
+        lastUsedAt?: string;
+        diskOp?: DiskOperation | null;
+        diskSeed?: DiskSeed | null;
+    }, updatedAt: string): Promise<void>;
+    /** Changes a pod Environment's lifecycle columns (the caller holds the row's lock). */
+    updateEnvironmentPod(id: string, patch: SandboxPodPatch, updatedAt: string): Promise<void>;
+    /** Deletes the Environment; its vault and credentials go with it (foreign key). */
+    deleteEnvironment(id: string): Promise<void>;
+    /** Environments by id, those with every label in `labels` when it is given. */
+    listEnvironments(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>[]>;
+    }): Promise<Environment[]>;
+    /** Sessions that name Environment `environmentId` (`Session.environmentId`), by id. */
+    sessionsOnEnvironment<T extends SessionDoc = SessionDoc>(environmentId: 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).
+     * Appends an event to the Environment's lifecycle stream through the record module. The
+     * caller holds the Environment 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[]>;
+    environmentEvent<T extends EnvironmentEventType>(environmentId: string, type: T, payload: EnvironmentEventPayload<T>): Promise<EnvironmentEvent>;
+    /**
+     * The Environment's stream, from `fromSeq` on, at most `limit` events: only `types` when given,
+     * and only events recorded at or after `since` and before `until` (ISO times) when given.
+     */
+    environmentEvents(environmentId: string, options?: EnvironmentEventsQuery): Promise<EnvironmentEvent[]>;
+    /** Holds manifest `name`'s save lock until the transaction ends, so saves of one name are serial. */
+    lockEnvironmentManifest(name: string): Promise<void>;
+    /** Version `version` of manifest `name`, or its latest when `version` is omitted. */
+    environmentManifest(name: string, version?: number): Promise<EnvironmentManifestRow | undefined>;
+    /** Writes a new version (the caller holds the name's lock and chose the next number). */
+    insertEnvironmentManifest(row: EnvironmentManifestRow): Promise<void>;
+    /** Each manifest's latest version, by name. */
+    listEnvironmentManifests(): Promise<EnvironmentManifestRow[]>;
+    /** Every version of manifest `name`, newest first. */
+    environmentManifestVersions(name: string): Promise<EnvironmentManifestRow[]>;
+    /** Deletes every version of manifest `name`; how many there were. */
+    deleteEnvironmentManifest(name: string): Promise<number>;
+    /** How many Environments were made from each version of manifest `name` (deleting ones too). */
+    environmentsOfManifest(name: string): Promise<Map<number, number>>;
     /** `invoking` effects of one session; takeover turns them `uncertain`. */
     invokingEffects<T extends EffectDoc = EffectDoc>(sessionId: string): Promise<T[]>;
     effectsForSession<T extends EffectDoc = EffectDoc>(sessionId: string, filter?: SessionEffectFilter): Promise<T[]>;
@@ -549,20 +637,20 @@ export interface Tx {
     putPrincipal(id: string, tokenHash: string, createdAt: string, role?: KeyRole): Promise<PrincipalRow>;
     /** Deletes principal `id`; false when there was none. */
     deletePrincipal(id: string): Promise<boolean>;
-    /** Rejects on a duplicate id, or a second `host` vault. */
+    /** Rejects on a duplicate id, or a second vault for one Environment. */
     insertVault(row: VaultRow): Promise<void>;
     getVault(id: string): Promise<VaultRow | undefined>;
-    /** User vaults of one owner, ordered by `createdAt`, then id. */
-    vaultsByOwner(ownerUserId: string): Promise<VaultRow[]>;
-    /** Installation vaults (any session may attach them), ordered by `createdAt`, then id. */
-    installationVaults(): Promise<VaultRow[]>;
+    /** The vault of Environment `environmentId` (D56). */
+    vaultOfEnvironment(environmentId: string): Promise<VaultRow | undefined>;
     updateVaultMetadata(id: string, metadataJson: string | null): Promise<void>;
     /** Deletes the vault and its credentials. */
     deleteVault(id: string): Promise<void>;
     /** Rejects on a duplicate id or an unknown vault. */
     insertCredential(row: VaultCredentialRow): Promise<void>;
-    /** Looks a credential up by id alone (attachment checks); callers compare `vaultId`. */
+    /** Looks a credential up by id alone; callers compare `vaultId`. */
     getCredential(id: string): Promise<VaultCredentialRow | undefined>;
+    /** The credential named `name` in vault `vaultId` (names are unique per vault). */
+    credentialByName(vaultId: string, name: string): Promise<VaultCredentialRow | undefined>;
     /** Credentials of one vault, ordered by `createdAt`, then id. */
     credentialsForVault(vaultId: string, filter?: {
         type?: VaultCredentialRow["type"];
@@ -600,6 +688,11 @@ export interface Tx {
     countSigningKeys(): Promise<number>;
     /** Appends a row, setting `duplicate` when one with the same `effectKey` exists; returns it. */
     recordModelUsage(row: ModelUsageWrite): Promise<ModelUsageRow>;
+    /**
+     * The first row the gate recorded for the model call `effectKey` (R7.1), never a `duplicate`;
+     * undefined when no gate metered it.
+     */
+    modelUsageOf(effectKey: string): Promise<ModelUsageRow | undefined>;
     modelUsageTotals(query: ModelUsageQuery): Promise<ModelUsageTotals>;
     /** Every budget, ordered by scope, then scope id. */
     listModelBudgets(): Promise<ModelBudgetRow[]>;
@@ -608,6 +701,11 @@ export interface Tx {
     toolCrossing(key: string): Promise<ToolCrossingRow | undefined>;
     /** Inserts the running call's row; false when a row with `key` already exists. */
     startToolCrossing(row: Pick<ToolCrossingRow, "key" | "hash" | "startedAt">): Promise<boolean>;
+    /**
+     * Starts a lost call's row again (R5.3): `startedAt` moves on, on a row with no answer and
+     * `hash`. False when the row is gone, settled, or another request's.
+     */
+    restartToolCrossing(row: Pick<ToolCrossingRow, "key" | "hash" | "startedAt">): Promise<boolean>;
     /** Records the call's answer. */
     settleToolCrossing(key: string, answer: unknown, settledAt: string): Promise<void>;
     /** Deletes rows that settled before `before`; returns how many. */
@@ -616,6 +714,10 @@ export interface Tx {
     artifact(id: string, options?: {
         lock?: boolean;
     }): Promise<ArtifactRow | undefined>;
+    /** The folder artifact that holds Environment `environmentId`'s disk versions (R2d step 3). */
+    diskArtifact(environmentId: 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;
@@ -632,6 +734,11 @@ export interface Tx {
     artifactVersions(artifactId: string): Promise<ArtifactVersionRow[]>;
     /** Deletes the artifact and its versions; returns the versions' blob keys (empty when none). */
     deleteArtifact(id: string): Promise<string[]>;
+    /**
+     * Deletes one version of a locked artifact (its content rows go with it) and returns its blob
+     * key; the latest version becomes the newest one left. The artifact itself stays, even empty.
+     */
+    deleteArtifactVersion(artifactId: string, version: number): Promise<string | undefined>;
     /**
      * Serializes the Tenant's artifact writes: held until the transaction ends. Take it before
      * reading the total a new version must fit under.
@@ -677,11 +784,19 @@ export interface Tx {
      *   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, sandbox resources and their lifecycle streams;
+     * - `environments`: sandbox records, Environments with their vaults, and their lifecycle
+     *   streams;
      * - `all`: both, plus definitions (and which definition files they use),
-     *   user vaults with their credentials,
      *   the model usage ledger, the model budgets and Tenant-wide artifacts. The host vault, principals, signing keys,
      *   settings, audit and vault idempotency rows stay.
      */
     reset(scope: ResetScope): Promise<void>;
 }
+/** Which of an Environment's events to read (`Tx.environmentEvents`). */
+export interface EnvironmentEventsQuery {
+    readonly fromSeq?: number;
+    readonly limit?: number;
+    readonly types?: readonly string[];
+    readonly since?: string;
+    readonly until?: string;
+}

package/dist/tenant/advance.d.ts

@@ -1,6 +1,6 @@
 import type { AdvanceResult } from "../execution/types.js";
 import type { Tx } from "../store/types.js";
-import type { Session, TenantContext } from "./context.js";
+import { type Session, type TenantContext } from "./context.js";
 /**
  * Advance session `id` if it has a runnable checkpoint (`WorkerHandlers.advance`). Returns
  * `busy` when another advance holds a live lease, `done` otherwise.
@@ -9,12 +9,13 @@ export declare function advance(ctx: TenantContext, id: string, signal: AbortSig
 /**
  * Takeover (§10.5 step 2, §11.4), inside the transaction that took ownership: the dead
  * owner's `invoking` effects become `uncertain` and are never invoked again, except model
- * calls when the gate recovers them (P1.2) and remote MCP and HTTP tool calls when the Tool
- * Gate does (F4.1 G3): those stay `invoking`, and the replay re-sends them. When one belongs
- * to the active turn, the session becomes `uncertain` too, with an `effect.uncertain` event.
- * Mutates and writes `s`. Returns the effect ids it marked.
+ * calls when the gate recovers them (P1.2) and every tool call (R5.3): those stay `invoking`,
+ * and the replay decides. It re-sends a model call, and an MCP or HTTP tool call with the same
+ * key; a sandbox or core-served tool call fails to the model as `tool.interrupted`
+ * (`harness-api/tool-journal.ts`). When an effect marked `uncertain` belongs to the active
+ * turn, the session becomes `uncertain` too, with an `effect.uncertain` event. Mutates and
+ * writes `s`. Returns the effect ids it marked.
  */
 export declare function takeOver(t: Tx, s: Session, options?: {
     recoversModelCalls?: boolean;
-    recoversToolCalls?: boolean;
 }): Promise<string[]>;