@nylorun/runtime 0.13.0-beta → 0.15.0-beta

package/dist/tenant/types.d.ts

@@ -1,13 +1,15 @@
 import type { IncomingMessage, ServerResponse } from "node:http";
-import type { AdminTenant, AdminTenantStatus, HostAggregate, TenantEnvelope } from "@nylorun/core/contracts";
+import type { HostAggregate, HostTenant, TenantEnvelope } from "@nylorun/core/contracts";
 import type { FlowLimits } from "../core/limits.js";
 import type { SessionStore } from "../store/types.js";
 import type { SandboxBackend } from "../sandbox/types.js";
+import type { TenantCause } from "./cause.js";
+import type { OutboundPolicy } from "./outbound.js";
 import type { TenantWorker } from "./worker.js";
 export type TenantMode = "shared" | "ephemeral" | "test";
 /**
- * The Tenant directory on the Host root. The Tenant's data lives in its store (a Postgres
- * schema); this holds what stays on the Host: the vault key, plugin data, logs, and the
+ * The Tenant directory on the Host root (`<Host root>/tenant/`). The Tenant's data lives in
+ * its database; this holds what stays on the Host: the vault key, plugin data, logs, and the
  * private home, tmp and sandbox directories.
  */
 export interface TenantPaths {
@@ -22,10 +24,6 @@ export interface TenantPaths {
 }
 export type TenantModelConfig = {
     kind: "vault";
-} | {
-    kind: "gateway";
-    url: string;
-    model: string;
 } | {
     kind: "fixture";
 } | {
@@ -41,8 +39,21 @@ export interface TenantConfig {
         backends?: readonly SandboxBackend[];
     };
     model: TenantModelConfig;
+    /**
+     * Segment rollover (Model Calls §10): a turn ends its segment at a step boundary after this
+     * many steps or milliseconds and continues in a new one, so no advance reaches its
+     * deadline. Default 50 steps or 20 minutes.
+     */
+    rollover?: {
+        steps?: number;
+        ms?: number;
+    };
+    /** Retries and timeouts for model calls (Model Calls §5, §6). Defaults in `piModel`. */
+    modelCall?: import("../gates/model-gate.js").ModelCallSettings;
     childEnv: Readonly<Record<string, string>>;
     /** Action claim lease. Default 30 s. */
+    /** How the Runtime may call Action endpoints (Host settings). Default: http and private addresses allowed. */
+    delivery?: OutboundPolicy;
     leaseMs?: number;
     /** Ownership lease of an advance (§10.6); renewed every third while it runs. Default 30 s. */
     ownerLeaseMs?: number;
@@ -69,135 +80,95 @@ export interface Logger {
 export interface TenantSummary {
     ready: boolean;
     runningSessions: number;
-    connectedExecutors: number;
+    /** Deliveries to Action endpoints in flight on this process. */
+    inFlightDeliveries: number;
     pendingActions: number;
     uncertainEffects: number;
-    /** Events committed but not yet relayed to Durable Streams. */
-    outboxDepth?: number;
-    /** The oldest unrelayed event's age; 0 when none waits. */
-    relayLagMs?: number;
+}
+/**
+ * The Node request and response behind a `Request`, for what still writes to Node directly
+ * (event streams). The shape of `@hono/node-server`'s `HttpBindings`.
+ */
+export interface NodeBindings {
+    readonly incoming: IncomingMessage;
+    readonly outgoing: ServerResponse;
 }
 /** An open Tenant Runtime. Created only by the Tenant module. */
 export interface TenantHandle {
     readonly envelope: TenantEnvelope;
     /** The handlers Durable Session Execution calls for this Tenant (`worker.ts`). */
     readonly worker?: TenantWorker;
-    /** Headers already validated by the Host. Authenticates, authorizes, dispatches. */
-    handle(request: IncomingMessage, response: ServerResponse, url: URL): Promise<void>;
+    /**
+     * A Tenant API request whose headers the Host has validated: authenticates, authorizes,
+     * dispatches. A response already written to `node.outgoing` is `RESPONSE_ALREADY_SENT`.
+     */
+    fetch(request: Request, node: NodeBindings): Promise<Response>;
     summary(): Promise<TenantSummary>;
     /** Stop scheduling; wait for or cancel active turns. */
     drain(activeWork: "drain" | "cancel", timeoutMs?: number): Promise<void>;
     close(): Promise<void>;
 }
+/**
+ * The Host's Tenant for a request: open, or unavailable. `cause` says why when opening it
+ * failed; without one the Host is starting or closing. Either way the request gets the opaque
+ * 404.
+ */
 export type TenantResolution = {
     kind: "open";
     handle: TenantHandle;
 } | {
-    kind: "not-found";
-} | {
-    kind: "quarantined";
-    quarantine: Quarantine;
+    kind: "unavailable";
+    cause?: TenantCause;
 };
-export interface Quarantine {
-    code: "kek-missing" | "corrupt" | "schema-too-new" | "migration-failed" | "envelope-invalid" | "open-timeout" | "open-failed";
-    message: string;
-    repair: string;
-}
-export interface BootstrapPrincipal {
-    principalId: string;
-    credentialHash: string;
-    idempotencyKey: string;
-    /** When set, also registers application principal `studio` with this hash. */
-    studioCredentialHash?: string;
-    /** Application principals whose keys the admin key derives (feature `derived-principals`). */
-    derivedPrincipals?: readonly DerivedPrincipal[];
-}
-export interface DerivedPrincipal {
-    id: string;
-    credentialHash: string;
-}
 /**
- * The deep module (§8). HTTP, CLI and tests use only this.
+ * The deep module (§8): the one Tenant a Host serves (tenancy.md §5). HTTP, the Worker and
+ * tests use only this.
  *
- * Tenants open on demand (architecture §8.2): the first `resolve`, `status`, `worker` or
- * `delete` naming a Tenant opens it (bounded by the open timeout) and caches the handle or
- * the quarantine; `start` only marks discovery done, so a Host with many Tenants opens none
- * at startup.
+ * `start` opens the Tenant; the Host has it open from readiness to shutdown. There is no
+ * Tenant list, no opening on demand of other Tenants and no quarantine cache: when opening
+ * fails for a reason in the Tenant (a `TenantCause`), the Host fails readiness and reports
+ * the cause until it is restarted. A failure outside the Tenant (`TenantUnavailableError`:
+ * Postgres unreachable) is retried in the background and by the next request.
  */
 export interface TenantModule {
-    /** Marks discovery done (`/ready`). Opens nothing. */
+    /** Opens the Tenant. Never rejects: a failure is recorded and reported by `tenant()`. */
     start(): Promise<void>;
-    readonly started: boolean;
-    /** Opens the Tenant on first use; a missing Tenant is `not-found`. */
-    resolve(id: string): Promise<TenantResolution>;
+    /** The Tenant is open (`/ready`). */
+    readonly ready: boolean;
     /**
-     * The Tenant's Worker handlers, opening it on demand, for `TenantWorkers.resolve`.
-     * Undefined when the Tenant does not exist, is quarantined or is being deleted, or the
-     * module is closed.
+     * The open Tenant, waiting for an open in progress. Rejects with `TenantUnavailableError`
+     * when it cannot be reached for a reason outside it.
      */
-    worker(id: string): Promise<TenantWorker | undefined>;
-    create(input: {
-        tenantId: string;
-        name: string;
-    } & BootstrapPrincipal): Promise<{
-        envelope: TenantEnvelope;
-        created: boolean;
-    }>;
+    resolve(): Promise<TenantResolution>;
     /**
-     * Every Tenant the store holds, without opening any. A Tenant not opened yet is listed
-     * `open` when its envelope reads; opening it may still quarantine it.
+     * The Tenant's Worker handlers when `id` is the open Tenant's, for `TenantWorkers.resolve`.
+     * Undefined otherwise, or once the module is closed.
      */
-    list(): Promise<readonly AdminTenant[]>;
-    status(id: string): Promise<AdminTenantStatus | undefined>;
-    delete(id: string, activeWork: "refuse" | "drain" | "cancel"): Promise<void>;
+    worker(id: string): Promise<TenantWorker | undefined>;
+    /** The Tenant as `/v1/admin/status` reports it. */
+    tenant(): HostTenant;
     summarize(): Promise<HostAggregate>;
     close(): Promise<void>;
 }
 /**
- * Storage adapter behind the module (§8): a Postgres schema per Tenant (`store-pg.ts`), and
- * in-memory for tests (`store-memory.ts`).
+ * Opens the Host's Tenant (`store-pg.ts`): migrates its database, creates the Tenant when it
+ * has none, and opens the Tenant Runtime. Rejects with a `TenantOpenError` (`cause.ts`) when
+ * the Tenant itself cannot be opened, and with `TenantUnavailableError` when something
+ * outside it failed.
  */
-export interface TenantStore {
-    /** Ids of every Tenant the store holds. */
-    enumerate(): Promise<readonly string[]>;
-    /** Throws a quarantine error when unreadable, `TenantNotFoundError` when gone. */
-    readEnvelope(id: string): Promise<TenantEnvelope>;
-    /**
-     * Creates the Tenant, or returns `exists` when it already exists (whatever its bootstrap
-     * material; the module compares it with `bootstrapMatches`). The stored envelope's
-     * `schemaVersion` is the store's own; read it back with `readEnvelope`.
-     */
-    create(envelope: TenantEnvelope, bootstrap: BootstrapPrincipal): Promise<"created" | "exists">;
-    bootstrapMatches(id: string, bootstrap: BootstrapPrincipal): Promise<boolean>;
-    /**
-     * Opens the Tenant Runtime; runs migration. Throws `TenantNotFoundError` when the Tenant
-     * does not exist, `TenantUnavailableError` when something outside the Tenant failed, and
-     * any other error (a quarantine error, ideally) when the Tenant itself cannot be opened.
-     */
-    open(id: string): Promise<TenantHandle>;
-    /** Removes the Tenant: its data and its Tenant directory. */
-    trash(id: string, now: Date): Promise<void>;
-    /** Removes what a failed `create` left, never an existing Tenant. */
-    removePartial(id: string): Promise<void>;
-}
+export type TenantOpener = () => Promise<TenantHandle>;
 /**
- * Thrown by a store when a Tenant cannot be reached for a reason outside it (the database
- * or Durable Session Execution is unavailable). The module does not quarantine it: the next
- * use tries again. The Host answers 503.
+ * Thrown when the Tenant cannot be reached for a reason outside it (the database or Durable
+ * Session Execution is unavailable). Not a cause: the next use tries again. The Host answers
+ * 503.
  */
 export declare class TenantUnavailableError extends Error {
-    readonly tenantId: string;
     readonly status = 503;
-    constructor(tenantId: string, options?: {
+    constructor(options?: {
         cause?: unknown;
     });
 }
-/** Thrown by `TenantStore.open` for a Tenant that does not exist. */
-export declare class TenantNotFoundError extends Error {
-    readonly tenantId: string;
-    constructor(tenantId: string);
-}
-/** What a Tenant store hands the Tenant Runtime it opens. */
+/** What the Tenant opener hands the Tenant Runtime it opens. */
 export interface OpenedTenant {
     /**
      * The Tenant's opened Session Store. The Tenant Runtime owns it from here on and closes it
@@ -207,5 +178,5 @@ export interface OpenedTenant {
     /** The Tenant envelope as its store reports it. */
     envelope: TenantEnvelope;
 }
-/** Opens the Tenant Runtime on a store the Tenant store opened (injected, so tests can fake it). */
+/** Opens the Tenant Runtime on an opened store (injected, so tests can fake it). */
 export type OpenTenantRuntime = (config: TenantConfig, opened: OpenedTenant) => Promise<TenantHandle>;

package/dist/tenant/types.js

@@ -1,23 +1,12 @@
 /**
- * Thrown by a store when a Tenant cannot be reached for a reason outside it (the database
- * or Durable Session Execution is unavailable). The module does not quarantine it: the next
- * use tries again. The Host answers 503.
+ * Thrown when the Tenant cannot be reached for a reason outside it (the database or Durable
+ * Session Execution is unavailable). Not a cause: the next use tries again. The Host answers
+ * 503.
  */
 export class TenantUnavailableError extends Error {
-    tenantId;
     status = 503;
-    constructor(tenantId, options) {
+    constructor(options) {
         super("Tenant is temporarily unavailable", options);
-        this.tenantId = tenantId;
         this.name = "TenantUnavailableError";
     }
 }
-/** Thrown by `TenantStore.open` for a Tenant that does not exist. */
-export class TenantNotFoundError extends Error {
-    tenantId;
-    constructor(tenantId) {
-        super(`Tenant ${tenantId} not found`);
-        this.tenantId = tenantId;
-        this.name = "TenantNotFoundError";
-    }
-}

package/dist/tenant/worker.d.ts

@@ -1,4 +1,4 @@
-import type { AdvanceResult, DurableExecution, StuckInvocation, WorkerHandlers } from "../execution/types.js";
+import type { AdvanceResult, DeliverResult, DurableExecution, StuckInvocation, WorkerHandlers } from "../execution/types.js";
 import type { Logger } from "./types.js";
 /** This process's Worker id: the `owner` it writes on the sessions it advances (§10.6). */
 export declare const WORKER_ID: string;
@@ -38,6 +38,8 @@ export interface TenantWorker {
     advance(sessionId: string, signal: AbortSignal): Promise<AdvanceResult>;
     /** One pass of the Tenant sweep. */
     sweep(): Promise<void>;
+    /** Delivers one Action to its endpoint. Only infrastructure errors throw. */
+    deliver?(actionId: string, signal: AbortSignal): Promise<DeliverResult>;
 }
 export interface TenantWorkersOptions {
     /** Finds or opens a Tenant that is not registered on this process. */

package/dist/tenant/worker.js

@@ -1,18 +1,20 @@
 /**
  * The Worker side of Durable Session Execution (architecture §12.3): what a `DurableExecution`
- * calls for one Tenant, and the registry that lets one execution serve every Tenant open on
- * this process.
+ * calls for the Tenant, and the registry its handlers dispatch through by Tenant id.
  *
  * - `TenantWorker` is one open Tenant's handlers: `advance(sessionId, signal)` (§10.5, in
- *   `advance.ts`) and `sweep()` (the Tenant sweep, in `sweep.ts`).
+ *   `advance.ts`), `sweep()` (the Tenant sweep, in `sweep.ts`) and, optionally,
+ *   `deliver(actionId, signal)` (one Action to its Action endpoint).
  * - `TenantWorkers` is the registry. Its `handlers` are the `WorkerHandlers` an execution is
  *   started with; they dispatch by `tenantId` to the registered `TenantWorker`. A Tenant
  *   registers when it opens and unregisters when it closes. A call for a Tenant that is not
- *   open here asks the optional `resolve` hook (the Host can open it on demand); without one,
- *   the advance returns `done` and the sweep does nothing. Nothing is lost: the Tenant's sweep
- *   re-wakes its orphaned sessions once it is open again.
+ *   open here asks the optional `resolve` hook (the Host's, which waits for its Tenant to
+ *   open, and knows no other); without one,
+ *   the advance and the delivery return `done` and the sweep does nothing. Nothing is lost:
+ *   the Tenant's sweep re-wakes its orphaned sessions once it is open again, and an Action
+ *   that was not delivered stays pending.
  * - `TenantExecution` pairs an execution with its registry. The Host creates one per process
- *   (`host/execution.ts`) and passes it to every Tenant it opens; a Tenant opened without one
+ *   (`host/execution.ts`) and passes it to its Tenant; a Tenant opened without one
  *   (tests, ephemeral) gets its own in-process `MemoryExecution`.
  *
  * ## Advance deadline
@@ -132,6 +134,10 @@ export class TenantWorkers {
         sweep: async (tenantId) => {
             await (await this.find(tenantId))?.sweep();
         },
+        deliver: async (tenantId, actionId, signal) => {
+            const worker = await this.find(tenantId);
+            return worker?.deliver ? worker.deliver(actionId, signal) : DONE;
+        },
     };
     /** Runs one advance under the deadline and the grace period (see the module comment). */
     async bounded(tenantId, sessionId, worker, signal) {

package/dist/vault/host-model.d.ts

@@ -0,0 +1,31 @@
+/**
+ * The Tenant's host model credential in plaintext: reading it to call the provider, and
+ * writing back a credential the provider adapter refreshed (OAuth). Only the Model Gate holds
+ * one (`gates/`; `scripts/check-boundaries.mjs` enforces it), so the loop process never reads a
+ * model credential. `VaultService` seals the credential but never reads it back.
+ *
+ * Decryption runs after the read commits; the key is resolved before the write's transaction.
+ */
+import type { SessionStore } from "../store/types.js";
+import { type HostModelSecret } from "./service.js";
+export interface HostModelVaultOptions {
+    readonly store: SessionStore;
+    /** The Tenant's key-encryption key; may throw when it is missing. */
+    readonly kek: () => Buffer;
+}
+export declare class HostModelVault {
+    private readonly store;
+    private readonly kek;
+    constructor(options: HostModelVaultOptions);
+    /** Reads the active host model secret. Decrypts after the read commits. */
+    readHostModel(): Promise<HostModelSecret | undefined>;
+    /** Replaces the active host model's secret, keeping its binding. */
+    updateHostCredential(credential: {
+        type: "api_key" | "oauth";
+        key?: string;
+        env?: Record<string, string>;
+        refresh?: string;
+        access?: string;
+        expires?: number;
+    }): Promise<void>;
+}

package/dist/vault/host-model.js

@@ -0,0 +1,57 @@
+import { encryptSecret } from "./crypto.js";
+import { VaultError } from "./error.js";
+import { activeHostCredentialRow, HOST_VAULT_ID, hostModelAad, modelBinding, readHostPayload, } from "./service.js";
+export class HostModelVault {
+    store;
+    kek;
+    constructor(options) {
+        this.store = options.store;
+        this.kek = options.kek;
+    }
+    /** Reads the active host model secret. Decrypts after the read commits. */
+    async readHostModel() {
+        const row = await this.store.tx((t) => activeHostCredentialRow(t));
+        if (!row)
+            return undefined;
+        const binding = modelBinding(row);
+        const payload = readHostPayload(this.kek(), row, binding);
+        const credential = binding.authType === "oauth"
+            ? { type: "oauth", ...payload.oauth }
+            : {
+                type: "api_key",
+                key: payload.apiKey,
+                ...(payload.env ? { env: payload.env } : {}),
+            };
+        return {
+            provider: binding.provider,
+            model: binding.model,
+            ...(binding.baseUrl ? { baseUrl: binding.baseUrl } : {}),
+            ...(binding.settings ? { settings: binding.settings } : {}),
+            authType: binding.authType,
+            credential,
+        };
+    }
+    /** Replaces the active host model's secret, keeping its binding. */
+    async updateHostCredential(credential) {
+        const kek = this.kek();
+        await this.store.tx(async (t) => {
+            const row = await activeHostCredentialRow(t);
+            if (!row)
+                throw new VaultError(404, "Model provider is not configured");
+            const binding = modelBinding(row);
+            const payload = credential.type === "oauth"
+                ? { oauth: credential }
+                : {
+                    apiKey: credential.key,
+                    ...(credential.env ? { env: credential.env } : {}),
+                };
+            const sealed = encryptSecret(kek, hostModelAad(binding.provider, binding.model), Buffer.from(JSON.stringify(payload), "utf8"));
+            await t.updateCredential(HOST_VAULT_ID, row.id, {
+                type: "model",
+                bindingJson: JSON.stringify({ ...binding, authType: credential.type }),
+                ...sealed,
+                rotatedAt: new Date().toISOString(),
+            });
+        });
+    }
+}

package/dist/vault/service.d.ts

@@ -1,9 +1,12 @@
-import type { CreateCredentialRequest, CreateVaultRequest, CredentialInfo, CredentialSelection, HostModelProviderInfo, HostModelView, PutHostModelRequest, RotateCredentialRequest, SelectHostModelRequest, VaultInfo } from "@nylorun/core/contracts";
-import type { SessionStore, Tx } from "../store/types.js";
+import type { CreateCredentialRequest, CreateVaultRequest, CredentialInfo, CredentialSelection, HostModelProviderInfo, HostModelView, PutHostModelRequest, CustomModelSettings, RotateCredentialRequest, SelectHostModelRequest, VaultInfo } from "@nylorun/core/contracts";
+import type { SessionStore, Tx, VaultCredentialRow } from "../store/types.js";
+export declare const HOST_VAULT_ID = "host";
 export type HostModelSecret = {
     provider: string;
     model: string;
     baseUrl?: string;
+    /** A custom endpoint's window, output limit, reasoning and pi-ai compat (Model Calls §7). */
+    settings?: CustomModelSettings;
     authType: "api_key" | "oauth";
     credential: {
         type: "api_key" | "oauth";
@@ -37,11 +40,16 @@ export interface VaultServiceOptions {
     kek: () => Buffer;
     /** Used only for OAuth refresh, always outside a transaction. */
     fetch: typeof fetch;
+    /** How long a token endpoint may take to answer a refresh. Default 30 s. */
+    refreshTimeoutMs?: number;
 }
 export declare class VaultService {
     private readonly store;
     private readonly kek;
     private readonly fetchImpl;
+    private readonly refreshTimeoutMs;
+    /** Refreshes in progress by credential id: concurrent uses share one. */
+    private readonly refreshing;
     constructor(options: VaultServiceOptions);
     createVault(body: CreateVaultRequest): Promise<VaultInfo>;
     listVaults(ownerUserId: string): Promise<VaultInfo[]>;
@@ -80,18 +88,17 @@ export declare class VaultService {
     }>;
     putHostModel(body: PutHostModelRequest): Promise<HostModelView>;
     selectHostModel(body: SelectHostModelRequest): Promise<HostModelView>;
-    /** Reads the active host model secret. Decrypts after the read commits. */
-    readHostModel(): Promise<HostModelSecret | undefined>;
-    updateHostCredential(credential: {
-        type: "api_key" | "oauth";
-        key?: string;
-        env?: Record<string, string>;
-        refresh?: string;
-        access?: string;
-        expires?: number;
-    }): Promise<void>;
-    reject(route: string): Promise<void>;
     /** Calls the token endpoint outside any transaction, then stores the result. */
+    /**
+     * Refreshes an OAuth grant once for every concurrent use in this process. A rotating refresh
+     * token is valid once, so two refreshes with it would fail the second, or make the provider
+     * revoke the grant.
+     */
+    private refreshShared;
+    /** Uses a token another process refreshed instead of refreshing again, before and after. */
+    private refreshLatest;
+    /** The credential's payload when it was rotated after `row` was read and is not due. */
+    private rotatedSince;
     private refresh;
     private replay;
     /** Re-seals a user credential's payload and returns the updated row. */
@@ -101,12 +108,32 @@ export declare class VaultService {
     private validateHostModel;
     private insertHostCredential;
     private hostModelView;
-    private hostModelRows;
-    private hostCredentialRowFor;
-    private activeHostCredentialRow;
-    private activeProviderId;
     private setActiveProvider;
     private deleteHostProviderRows;
     private credentialRow;
     private audit;
 }
+/** The host vault's model credential rows that parse. */
+export declare function hostModelRows(t: Tx): Promise<VaultCredentialRow[]>;
+/** The host model credential of `provider`. */
+export declare function hostCredentialRowFor(t: Tx, provider: string): Promise<VaultCredentialRow | undefined>;
+/** The provider the host model selection names, or the only (or legacy) one configured. */
+export declare function activeProviderId(t: Tx): Promise<string | undefined>;
+/** The active host model credential row (ciphertext), in `t`. */
+export declare function activeHostCredentialRow(t: Tx): Promise<VaultCredentialRow | undefined>;
+export declare function readHostPayload(kek: Buffer, row: VaultCredentialRow, binding: ModelBinding): HostSecretPayload;
+type ModelBinding = {
+    provider: string;
+    model: string;
+    baseUrl?: string;
+    settings?: CustomModelSettings;
+    authType: "api_key" | "oauth";
+};
+type HostSecretPayload = {
+    apiKey?: string;
+    env?: Record<string, string>;
+    oauth?: HostModelSecret["credential"];
+};
+export declare function modelBinding(row: VaultCredentialRow): ModelBinding;
+export declare function hostModelAad(provider: string, model: string): Buffer;
+export {};