@nylorun/runtime 0.15.2-beta → 0.17.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, SigningKeyRow, VaultAuditRow, VaultCredentialRow, VaultIdempotencyRow, VaultRow, OAuthPendingRow } 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. */
@@ -191,10 +242,9 @@ export type EndpointHealthUpdate =
  * The rows of the typed tables, inferred from the tables Drizzle defines
  * (`store/postgres/schema.ts`): a principal, a vault and its credentials (secrets sealed in
  * `bytea` columns, never inside a JSON body), the vault's audit and idempotency records, the
- * Tenant's signing keys, a subject's turn bucket, a publishable key, a model call in the usage
- * ledger and a model budget.
+ * Tenant's signing keys, 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, SigningKeyRow, VaultAuditRow, VaultCredentialRow, VaultIdempotencyRow, VaultRow, OAuthPendingRow, };
 /** Which rows of the usage ledger a total covers. */
 export interface ModelUsageQuery {
     scope: "tenant" | "agent" | "turn";
@@ -340,6 +390,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 +408,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). */
@@ -393,11 +479,23 @@ export interface Tx {
     principalByTokenHash(tokenHash: string): Promise<PrincipalRow | undefined>;
     principalById(id: string): Promise<PrincipalRow | undefined>;
     applicationTokenHashes(): Promise<string[]>;
+    /** Every principal, ordered by id. */
+    listPrincipals(): Promise<PrincipalRow[]>;
+    /**
+     * Creates application principal `id` with `tokenHash`, or gives an existing one this hash
+     * (and `createdAt`): its previous key stops authenticating. Rejects when another principal
+     * holds the hash.
+     */
+    putPrincipal(id: string, tokenHash: string, createdAt: string): 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. */
     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[]>;
     updateVaultMetadata(id: string, metadataJson: string | null): Promise<void>;
     /** Deletes the vault and its credentials. */
     deleteVault(id: string): Promise<void>;
@@ -423,6 +521,12 @@ export interface Tx {
     getVaultIdempotency(id: string): Promise<VaultIdempotencyRow | undefined>;
     /** Rejects when the id exists. */
     insertVaultIdempotency(row: VaultIdempotencyRow): Promise<void>;
+    /** An MCP OAuth connect's start (F9 C2). Rejects on a duplicate state or an unknown vault. */
+    insertOAuthPending(row: OAuthPendingRow): Promise<void>;
+    /** Deletes and returns the pending connect of `stateHash`, expired or not: each is used once. */
+    takeOAuthPending(stateHash: string): Promise<OAuthPendingRow | undefined>;
+    /** Deletes the pending connects that expired before `now` (ISO); returns how many. */
+    deleteExpiredOAuthPending(now: string): Promise<number>;
     /**
      * Serializes signing key changes: held until the transaction ends. Take it before reading
      * the keys a change depends on, so concurrent first uses or rotations do not collide.
@@ -440,28 +544,6 @@ export interface Tx {
      */
     setSigningKeyState(id: string, from: SigningKeyRow["state"], to: SigningKeyRow["state"], at: string): Promise<boolean>;
     countSigningKeys(): Promise<number>;
-    /** The subject's revocation epoch; 0 when it was never revoked. */
-    subjectEpoch(subject: string): Promise<number>;
-    /** The epochs of several subjects; subjects never revoked are absent. */
-    subjectEpochs(subjects: readonly string[]): Promise<Map<string, number>>;
-    /** Adds one to the subject's epoch and returns the new value. */
-    bumpSubjectEpoch(subject: string, at: string): Promise<number>;
-    /**
-     * The subject's turn bucket, created from `initial` when missing, locked until the
-     * transaction ends so concurrent commands of one subject serialize.
-     */
-    lockSubjectUsage(initial: SubjectUsageRow): Promise<SubjectUsageRow>;
-    putSubjectUsage(row: SubjectUsageRow): Promise<void>;
-    /** How many sessions of `ownerUserId` are in one of `statuses`. */
-    countOwnerSessions(ownerUserId: string, statuses: readonly string[]): Promise<number>;
-    /** Rejects on a duplicate id, key or name. */
-    insertPublishableKey(row: PublishableKeyRow): Promise<void>;
-    publishableKeyByKey(key: string): Promise<PublishableKeyRow | undefined>;
-    publishableKey(id: string): Promise<PublishableKeyRow | undefined>;
-    /** All keys, revoked ones included, ordered by `createdAt`, then id. */
-    publishableKeys(): Promise<PublishableKeyRow[]>;
-    /** Returns false when the key does not exist. */
-    updatePublishableKey(id: string, patch: Partial<Pick<PublishableKeyRow, "originsJson" | "revokedAt">>): Promise<boolean>;
     /** Appends a row, setting `duplicate` when one with the same `effectKey` exists; returns it. */
     recordModelUsage(row: Omit<ModelUsageRow, "duplicate">): Promise<ModelUsageRow>;
     modelUsageTotals(query: ModelUsageQuery): Promise<ModelUsageTotals>;
@@ -476,18 +558,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
+     * - `sessions`: sessions, commands, effects, actions, links, 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,
-     *   publishable keys, settings, audit and vault idempotency rows stay.
+     *   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>;
 }

package/dist/streams/control.d.ts

@@ -6,13 +6,10 @@
 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.
  */
 export declare function signalSessionsReset(streams: DurableStreams, basin: string, generation: number): Promise<void>;
-/**
- * Appends a `subject.revoked` signal: every process with the Tenant open ends the subject's
- * streams opened with a token older than `epoch`.
- */
-export declare function signalSubjectRevoked(streams: DurableStreams, basin: string, subject: string, epoch: number): Promise<void>;

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.
@@ -23,11 +28,3 @@ export async function signalSessionsReset(streams, basin, generation) {
     const signal = { type: "sessions.reset", generation };
     await streams.append(basin, CONTROL_STREAM, [signal]);
 }
-/**
- * Appends a `subject.revoked` signal: every process with the Tenant open ends the subject's
- * streams opened with a token older than `epoch`.
- */
-export async function signalSubjectRevoked(streams, basin, subject, epoch) {
-    const signal = { type: "subject.revoked", subject, epoch };
-    await streams.append(basin, CONTROL_STREAM, [signal]);
-}

package/dist/streams/types.d.ts

@@ -7,7 +7,7 @@
  * | Stream | Contents | Written by | Read by |
  * | --- | --- | --- | --- |
  * | `sessions/<sessionId>` | every event of the session, in sequence | the stream relay, from the record | history and session SSE |
- * | `tenant/control` | `session.cancel`, `sessions.reset` and `subject.revoked` signals | API nodes | every process with the Tenant open |
+ * | `tenant/control` | `session.cancel`, `sessions.reset` and `action.resolved` signals | API nodes | every process with the Tenant open |
  *
  * **Basin generations.** A session id is unique within its Tenant's basin generation. A
  * Tenant reset, the only path that frees ids, moves the Tenant to the next generation, so
@@ -139,12 +139,12 @@ export interface SessionsResetSignal {
     generation?: number;
 }
 /**
- * A subject's tokens older than `epoch` were revoked: each process ends that subject's
- * streams opened with them.
+ * 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 SubjectRevokedSignal {
-    type: "subject.revoked";
-    subject: string;
-    epoch: number;
+export interface ActionResolvedSignal {
+    type: "action.resolved";
+    sessionId: string;
+    actionId: string;
 }
-export type ControlSignal = SessionCancelSignal | SessionsResetSignal | SubjectRevokedSignal;
+export type ControlSignal = SessionCancelSignal | SessionsResetSignal | ActionResolvedSignal;

package/dist/streams/types.js

@@ -7,7 +7,7 @@
  * | Stream | Contents | Written by | Read by |
  * | --- | --- | --- | --- |
  * | `sessions/<sessionId>` | every event of the session, in sequence | the stream relay, from the record | history and session SSE |
- * | `tenant/control` | `session.cancel`, `sessions.reset` and `subject.revoked` signals | API nodes | every process with the Tenant open |
+ * | `tenant/control` | `session.cancel`, `sessions.reset` and `action.resolved` signals | API nodes | every process with the Tenant open |
  *
  * **Basin generations.** A session id is unique within its Tenant's basin generation. A
  * Tenant reset, the only path that frees ids, moves the Tenant to the next generation, so