@nylorun/runtime 0.14.0-beta → 0.15.0-beta

package/dist/gates/meter.js

@@ -0,0 +1,165 @@
+/**
+ * The meter (blueprint §15, P1.3). Every model call a gate serves is recorded once in the
+ * Tenant's usage ledger (`model_usage`), by the gate itself: the gates service for the stack,
+ * the in-process gate otherwise. A failed ledger write is logged and never fails the call.
+ *
+ * Before the call the meter checks the Tenant's budgets (hard caps). There is no reservation
+ * (M7): a cap is reached when the scope's recorded spend, plus this gate's calls in flight in
+ * the scope at the scope's average cost per call, reaches its limit. Calls in a turn run one
+ * at a time, so a scope overspends by at most one call per concurrent call. The refusal is a
+ * `budget_exhausted` failure, which the turn does not retry.
+ */
+import { randomUUID } from "node:crypto";
+import { failure } from "../model/classify.js";
+export function createMeter(options) {
+    const now = options.now ?? (() => new Date());
+    /** Calls running through this gate, per Tenant and budget scope. */
+    const inflight = new Map();
+    async function check(store, request) {
+        const at = now();
+        try {
+            return await store.tx(async (t) => {
+                const keys = [];
+                for (const budget of await t.listModelBudgets()) {
+                    const query = scopeOf(budget, request, at);
+                    if (!query)
+                        continue;
+                    const key = `${request.tenantId}|${query.scope}|${query.id ?? "*"}|${query.since ?? ""}`;
+                    keys.push(key);
+                    const reached = capReached(budget, await t.modelUsageTotals(query), inflight.get(key) ?? 0);
+                    if (reached) {
+                        options.logger.warn("model_budget_exhausted", {
+                            tenant: request.tenantId,
+                            session: request.sessionId,
+                            effect: request.effectId,
+                            scope: budget.scope,
+                            ...(budget.scope === "agent" ? { agent: budget.scopeId } : {}),
+                        });
+                        return { keys, refusal: failure("budget_exhausted", reached, false) };
+                    }
+                }
+                return { keys };
+            });
+        }
+        catch (error) {
+            // The caps can't be read: the call goes ahead, as it would without budgets.
+            options.logger.warn("model_budget_check_failed", {
+                tenant: request.tenantId,
+                effect: request.effectId,
+                message: error instanceof Error ? error.message : String(error),
+            });
+            return { keys: [] };
+        }
+    }
+    return {
+        async call(store, request, call) {
+            const { keys, refusal } = await check(store, request);
+            if (refusal)
+                return refusal;
+            // A call counts as in flight until its usage is recorded, so the check never misses it.
+            for (const key of keys)
+                inflight.set(key, (inflight.get(key) ?? 0) + 1);
+            try {
+                const outcome = await call();
+                await record(store, request, outcome);
+                return outcome;
+            }
+            finally {
+                for (const key of keys) {
+                    const left = (inflight.get(key) ?? 1) - 1;
+                    if (left > 0)
+                        inflight.set(key, left);
+                    else
+                        inflight.delete(key);
+                }
+            }
+        },
+    };
+    async function record(store, request, outcome) {
+        const row = usageRow(request, outcome, now());
+        if (!row)
+            return;
+        try {
+            const recorded = await store.tx((t) => t.recordModelUsage(row));
+            if (recorded.duplicate)
+                options.logger.warn("model_usage_duplicate", {
+                    tenant: request.tenantId,
+                    effect: request.effectId,
+                });
+        }
+        catch (error) {
+            options.logger.warn("model_usage_failed", {
+                tenant: request.tenantId,
+                effect: request.effectId,
+                message: error instanceof Error ? error.message : String(error),
+            });
+        }
+    }
+}
+/** The ledger row of an outcome that carries usage; undefined for a failure. */
+export function usageRow(request, outcome, at) {
+    if (typeof outcome !== "object" || "kind" in outcome || !outcome.usage)
+        return undefined;
+    const usage = outcome.usage;
+    const producer = producerOf(outcome);
+    const inputTokens = count(usage.inputTokens);
+    const outputTokens = count(usage.outputTokens);
+    return {
+        id: randomUUID(),
+        effectKey: request.effectId,
+        sessionId: request.sessionId,
+        turnId: request.turnId,
+        agentId: request.agentId,
+        provider: producer.provider ?? null,
+        model: producer.model ?? outcome.evidence?.resolvedModel ?? request.call.model?.id ?? null,
+        inputTokens,
+        outputTokens,
+        totalTokens: count(usage.totalTokens) || inputTokens + outputTokens,
+        cachedTokens: count(usage.cachedTokens),
+        cacheWriteTokens: count(usage.cacheWriteTokens),
+        reasoningTokens: count(usage.reasoningTokens),
+        costUsd: Number.isFinite(usage.costUsd) && usage.costUsd > 0 ? usage.costUsd : 0,
+        createdAt: at.toISOString(),
+    };
+}
+/** The ledger rows a budget counts for `request`; undefined when it doesn't apply. */
+function scopeOf(budget, request, at) {
+    const since = budget.period ? { since: periodStart(budget.period, at) } : {};
+    if (budget.scope === "turn")
+        return { scope: "turn", id: request.turnId };
+    if (budget.scope === "agent")
+        return budget.scopeId === request.agentId ? { scope: "agent", id: request.agentId, ...since } : undefined;
+    return { scope: "tenant", ...since };
+}
+/**
+ * Why the budget refuses another call, or undefined. Calls in flight count at the scope's
+ * average cost per recorded call.
+ */
+export function capReached(budget, spent, inflight) {
+    const projected = (total) => total + (spent.calls > 0 ? (inflight * total) / spent.calls : 0);
+    const name = budget.scope === "turn"
+        ? "The turn's cap"
+        : `${budget.scope === "agent" ? `Agent ${budget.scopeId}'s` : "The Tenant's"} ${budget.period === "day" ? "daily" : "monthly"} cap`;
+    const raise = "raise it with PUT /v1/tenant/budgets";
+    if (budget.limitTokens !== null && projected(spent.tokens) >= budget.limitTokens)
+        return `${name} of ${budget.limitTokens} tokens is reached (${spent.tokens} used); ${raise}`;
+    if (budget.limitUsd !== null && projected(spent.costUsd) >= budget.limitUsd)
+        return `${name} of $${budget.limitUsd} is reached ($${spent.costUsd.toFixed(4)} spent); ${raise}`;
+    return undefined;
+}
+/** When the UTC `period` containing `now` started, as an ISO time. */
+export function periodStart(period, now) {
+    return new Date(Date.UTC(now.getUTCFullYear(), now.getUTCMonth(), period === "day" ? now.getUTCDate() : 1)).toISOString();
+}
+const count = (value) => Number.isFinite(value) && value > 0 ? Math.round(value) : 0;
+/** The provider and model `piModel` records as the candidate's producer. */
+function producerOf(candidate) {
+    const producer = candidate.evidence?.extras?.producer;
+    if (typeof producer !== "object" || producer === null || Array.isArray(producer))
+        return {};
+    const { provider, model } = producer;
+    return {
+        ...(typeof provider === "string" ? { provider } : {}),
+        ...(typeof model === "string" ? { model } : {}),
+    };
+}

package/dist/gates/model-gate.d.ts

@@ -0,0 +1,45 @@
+/**
+ * The Model Gate seam (blueprint §15, P1.1). Every vault-backed model call of the loop goes
+ * through one `ModelGate`: the call, who it is for, and nothing else. The gate owns what the
+ * call needs that the loop must not hold: the provider credential, pi-ai, its retries and
+ * idle watchdog, failure classification and scrubbing.
+ *
+ * Two implementations: `inProcessModelGate` (embedding, the ephemeral Runtime, tests) and the
+ * HTTP client of the gates service (the `gateway` container), which keeps the credential out
+ * of the loop process. Both return what `piModel` returns, so the effect journal is the same
+ * either way.
+ */
+import type { RuntimeModelAdapter, RuntimeModelCall } from "../contracts.js";
+export type { ModelCallSettings } from "../model/pi-model.js";
+/** One model call, as the loop hands it to the gate. JSON-safe: it crosses the network. */
+export interface ModelGateRequest {
+    readonly tenantId: string;
+    readonly sessionId: string;
+    readonly turnId: string;
+    /** The session's agent, for the usage ledger and its budgets (P1.3). */
+    readonly agentId: string;
+    /** The effect's journal id; sent as `Idempotency-Key` (acted on from P1.2). */
+    readonly effectId: string;
+    readonly invocationId: string;
+    readonly call: RuntimeModelCall;
+}
+/** A model candidate or a failure outcome: exactly what `piModel` returns. */
+export type ModelGateOutcome = Awaited<ReturnType<RuntimeModelAdapter>>;
+export interface ModelGate {
+    /**
+     * Calls the model. A provider or gate failure comes back as a failure outcome; only an abort
+     * of `signal` throws, so the advance decides what the abort means.
+     */
+    call(request: ModelGateRequest, signal: AbortSignal): Promise<ModelGateOutcome>;
+    /**
+     * True when a call outlives the caller's process (the gates service, P1.2): after a takeover
+     * or a shutdown, re-sending the journaled request joins the call or returns its outcome
+     * instead of calling the provider again. The in-process gate dies with the loop.
+     */
+    readonly recovers?: boolean;
+    /**
+     * Stops a call that outlives its caller (a user cancel). Best-effort: never rejects. Only a
+     * gate that `recovers` needs it; for the others aborting `signal` already stops the call.
+     */
+    cancel?(request: Pick<ModelGateRequest, "tenantId" | "effectId">): Promise<void>;
+}

package/dist/gates/model-gate.js

@@ -0,0 +1 @@
+export {};

package/dist/gates/tenant-vaults.d.ts

@@ -0,0 +1,64 @@
+/**
+ * What the gates service opens of the Tenant: its vault's host model, and nothing else. The
+ * full Tenant (`TenantRuntime.open`) migrates its database, creates its key file and starts
+ * its services; the gate does none of that. The database holds one Tenant (tenancy.md §1):
+ * the gate reads which one from it, refuses a database whose Tenant schema isn't at this
+ * build's version (the Runtime migrates it when it opens the Tenant) and never creates a vault
+ * key. The vault is opened once and kept.
+ */
+import type { Credential } from "@earendil-works/pi-ai";
+import type { ModelFailureOutcome } from "@nylorun/core/define";
+import type { PostgresClient } from "../store/postgres/connect.js";
+import { VaultService, type AuthorizeResult, type HostModelSecret } from "../vault/service.js";
+import type { SessionStore } from "../store/types.js";
+import type { Session } from "../tenant/context.js";
+import { type Keys } from "../keys/keys.js";
+/** The Tenant, as a model call needs it. */
+export interface TenantVault {
+    readonly tenantId: string;
+    /** The Tenant's store, for the usage ledger (P1.3). */
+    readonly store: SessionStore;
+    /** The Tenant's home: secrets found there are redacted from failure messages. */
+    readonly root: string;
+    readHostModel(): Promise<HostModelSecret | undefined>;
+    /** Writes back a credential pi-ai refreshed (OAuth). */
+    writeHostCredential(credential: Credential): Promise<void>;
+    /** A session, for the remote MCP servers its pinned manifest declares (F4.1). */
+    session(sessionId: string): Promise<Session | undefined>;
+    /**
+     * The vault authorization of one request to a session's remote MCP server: its credential
+     * from the session's attached vaults, refreshed when due (F4.1).
+     */
+    authorizeMcp(sessionId: string, request: {
+        url: string;
+        serverName: string;
+    }): Promise<AuthorizeResult>;
+    /** Vault writes and token signing with the Tenant's vault key (the keys service, F4.2). */
+    keys(): Keys;
+}
+export interface TenantVaults {
+    /**
+     * Opens the Tenant's vault, or rejects with a `GateRefusal`. `tenantId`, when the caller
+     * names one, must be the database's Tenant.
+     */
+    open(tenantId?: string): Promise<TenantVault>;
+}
+/** A call the gate refuses before the provider is called; it answers with `outcome`. */
+export declare class GateRefusal extends Error {
+    readonly outcome: ModelFailureOutcome;
+    constructor(outcome: ModelFailureOutcome);
+}
+export interface TenantVaultsOptions {
+    readonly sql: PostgresClient;
+    /** The Host root; the gate reads `keys/vault-kek` and `tenant/home` under it. */
+    readonly hostRoot: string;
+}
+export declare function createTenantVaults(options: TenantVaultsOptions): TenantVaults;
+/**
+ * A request to a session's remote MCP server, authorized from the session's attached vaults:
+ * what the loop did in its own process before F4.1 (`tenant/effects.ts` `authorize`).
+ */
+export declare function authorizeSessionMcp(credentials: VaultService, session: (sessionId: string) => Promise<Session | undefined>, sessionId: string, request: {
+    url: string;
+    serverName: string;
+}): Promise<AuthorizeResult>;

package/dist/gates/tenant-vaults.js

@@ -0,0 +1,94 @@
+import { isTenantId } from "@nylorun/core/compatibility";
+import { failure } from "../model/classify.js";
+import { database } from "../store/postgres/db.js";
+import { expectedSchemaVersion, readSchemaVersion } from "../store/postgres/migrate.js";
+import { readTenantEnvelope } from "../store/postgres/tenant.js";
+import { createPostgresSessionStore } from "../store/postgres/store.js";
+import { tenantPaths } from "../tenant/paths.js";
+import { readVaultKek } from "../vault/kek.js";
+import { HostModelVault } from "../vault/host-model.js";
+import { VaultService } from "../vault/service.js";
+import { inProcessKeys } from "../keys/keys.js";
+import { SigningKeys } from "../tenant/signing-keys.js";
+/** A call the gate refuses before the provider is called; it answers with `outcome`. */
+export class GateRefusal extends Error {
+    outcome;
+    constructor(outcome) {
+        super(outcome.message);
+        this.outcome = outcome;
+        this.name = "GateRefusal";
+    }
+}
+export function createTenantVaults(options) {
+    const { sql, hostRoot } = options;
+    let opened;
+    function build(tenantId) {
+        const paths = tenantPaths(hostRoot);
+        const store = createPostgresSessionStore({ sql, tenantId });
+        let kek;
+        const readKek = () => {
+            kek ??= readVaultKek({ vaultKekPath: paths.kek });
+            if (!kek)
+                throw new GateRefusal(failure("auth", "The Tenant's vault key is missing on the gateway container; check that it mounts the Host's keys directory, which `nylorun start` creates", false));
+            return kek;
+        };
+        const vault = new HostModelVault({ store, kek: readKek });
+        const credentials = new VaultService({ store, kek: readKek, fetch: globalThis.fetch });
+        const keys = inProcessKeys({
+            store,
+            vault: credentials,
+            signingKeys: new SigningKeys({ tenantId, kek: readKek }),
+            kek: readKek,
+        });
+        const session = (sessionId) => store.tx((t) => t.get("sessions", sessionId));
+        return {
+            tenantId,
+            store,
+            root: paths.home,
+            readHostModel: () => vault.readHostModel(),
+            writeHostCredential: (credential) => vault.updateHostCredential(credential),
+            session,
+            authorizeMcp: (sessionId, request) => authorizeSessionMcp(credentials, session, sessionId, request),
+            keys: () => keys,
+        };
+    }
+    /** The database's Tenant, once its schema is at this build's version. */
+    async function load() {
+        const version = await readSchemaVersion(database(sql));
+        const expected = expectedSchemaVersion();
+        if (version === undefined || version === 0)
+            throw new GateRefusal(failure("transient", "The Tenant's database is not migrated yet; the Runtime does that when it starts", true));
+        if (version !== expected)
+            throw new GateRefusal(failure("transient", `The Tenant is at schema version ${version}; the gateway serves version ${expected}`, version < expected));
+        const envelope = await readTenantEnvelope(sql).catch(() => undefined);
+        if (!envelope)
+            throw new GateRefusal(failure("transient", "The database holds no Tenant yet; the Runtime creates it when it starts", true));
+        return build(envelope.id);
+    }
+    return {
+        async open(tenantId) {
+            if (tenantId !== undefined && !isTenantId(tenantId))
+                throw new GateRefusal(failure("invalid_request", "Not a Tenant id", false));
+            opened ??= await load();
+            if (tenantId !== undefined && tenantId !== opened.tenantId)
+                throw new GateRefusal(failure("invalid_request", `Tenant ${tenantId} is not this installation's Tenant`, false));
+            return opened;
+        },
+    };
+}
+/**
+ * A request to a session's remote MCP server, authorized from the session's attached vaults:
+ * what the loop did in its own process before F4.1 (`tenant/effects.ts` `authorize`).
+ */
+export async function authorizeSessionMcp(credentials, session, sessionId, request) {
+    const found = await session(sessionId);
+    if (!found)
+        throw new Error(`Session ${sessionId} not found`);
+    return credentials.authorize({
+        sessionId,
+        vaultIds: found.vaultIds ?? [],
+        credentialSelections: found.credentialSelections ?? [],
+        url: request.url,
+        serverName: request.serverName,
+    });
+}

package/dist/gates/tool-calls.d.ts

@@ -0,0 +1,51 @@
+/**
+ * Keyed remote MCP calls in the gates service (F4.1 G3). A call sent with an `Idempotency-Key`
+ * (the loop's effect id) runs once:
+ *
+ * - While it runs, and for 30 minutes after, a re-send joins it or gets its answer from memory
+ *   (`inflight.ts`), as model calls do (P1.2). So a runtime that dies or shuts down mid-call
+ *   leaves nothing `uncertain`: the next owner re-sends the call and gets its answer.
+ * - The gate also writes a `tool_crossings` row before it calls the server, and the answer
+ *   after. A re-send that finds the answer gets it. One that finds a row without an answer,
+ *   for a call this gateway is not running, was lost with an earlier gateway (a restart mid
+ *   call): it answers `uncertain`, because the call may have run, and is never run again.
+ *
+ * A cancel aborts the call and leaves its row without an answer. Settled rows are deleted a day
+ * later (`prune`).
+ */
+import type { McpServerRef } from "../mcp/pool.js";
+import type { Logger } from "../tenant/types.js";
+import { type InflightCallsOptions } from "./inflight.js";
+import type { McpHandler } from "./mcp-handler.js";
+import type { TenantVaults } from "./tenant-vaults.js";
+import type { McpAnswer } from "./tool-contract.js";
+/** How long a settled crossing is kept. */
+export declare const TOOL_CROSSING_TTL_MS: number;
+export type ToolCallAnswer = McpAnswer<Record<string, unknown>>;
+export interface ToolCallRequest {
+    readonly server: McpServerRef;
+    readonly effectId: string;
+    readonly name: string;
+    readonly arguments: Record<string, unknown>;
+}
+export interface ToolCalls {
+    /**
+     * Runs, joins or answers the call under `key`. Rejects with `InflightConflict` when a
+     * different request already ran under it.
+     */
+    run(tenantId: string | undefined, key: string, hash: string, request: ToolCallRequest): Promise<ToolCallAnswer>;
+    /** Aborts the call under `key`; it is never run again under that key. */
+    cancel(key: string): void;
+    /** Aborts every running call (gateway shutdown). */
+    close(): void;
+    /** Deletes crossings settled more than `TOOL_CROSSING_TTL_MS` ago. */
+    prune(): Promise<void>;
+}
+export interface ToolCallsOptions {
+    readonly vaults: TenantVaults;
+    readonly mcp: McpHandler;
+    readonly logger: Logger;
+    readonly inflight?: InflightCallsOptions;
+    readonly now?: () => number;
+}
+export declare function createToolCalls(options: ToolCallsOptions): ToolCalls;

package/dist/gates/tool-calls.js

@@ -0,0 +1,64 @@
+import { createInflightCalls, InflightConflict } from "./inflight.js";
+/** How long a settled crossing is kept. */
+export const TOOL_CROSSING_TTL_MS = 24 * 60 * 60_000;
+const LOST = {
+    ok: false,
+    error: {
+        uncertain: true,
+        message: "The gateway stopped while this MCP call ran; the call may have reached the server, so it is not run again",
+    },
+};
+export function createToolCalls(options) {
+    const { vaults, mcp, logger } = options;
+    const now = options.now ?? Date.now;
+    const inflight = createInflightCalls(options.inflight);
+    const iso = () => new Date(now()).toISOString();
+    return {
+        async run(tenantId, key, hash, request) {
+            if (inflight.has(key))
+                return inflight.run(key, hash, () => Promise.resolve(LOST));
+            const vault = await vaults.open(tenantId);
+            const store = vault.store;
+            const row = await store.tx((t) => t.toolCrossing(key));
+            if (row) {
+                if (row.hash !== hash)
+                    throw new InflightConflict(`A different request already ran under ${key}`);
+                if (row.answer !== null && row.answer !== undefined)
+                    return row.answer;
+                // Started here a moment ago, or lost with an earlier gateway.
+                if (inflight.has(key))
+                    return inflight.run(key, hash, () => Promise.resolve(LOST));
+                return LOST;
+            }
+            return inflight.run(key, hash, async (signal) => {
+                const started = await store.tx((t) => t.startToolCrossing({ key, hash, startedAt: iso() }));
+                // Another gateway process wrote it between the read and now: never run it twice.
+                if (!started)
+                    return LOST;
+                const answer = await mcp.call(tenantId, request, signal);
+                // A cancel or a shutdown: the call may have reached the server; the row stays open.
+                if (signal.aborted)
+                    throw signal.reason ?? new Error("aborted");
+                await store
+                    .tx((t) => t.settleToolCrossing(key, answer, iso()))
+                    .catch((error) => logger.warn("tool_crossing_unsettled", {
+                    effect: key,
+                    message: error instanceof Error ? error.message : String(error),
+                }));
+                return answer;
+            });
+        },
+        cancel: (key) => inflight.cancel(key),
+        close: () => inflight.close(),
+        async prune() {
+            try {
+                const vault = await vaults.open(undefined);
+                const before = new Date(now() - TOOL_CROSSING_TTL_MS).toISOString();
+                await vault.store.tx((t) => t.pruneToolCrossings(before));
+            }
+            catch {
+                // The database is not ready yet; the next pass prunes.
+            }
+        },
+    };
+}

package/dist/gates/tool-client.d.ts

@@ -0,0 +1,12 @@
+import type { ToolGate } from "./tool-gate.js";
+export interface HttpToolGateOptions {
+    /** The gates service, e.g. `http://gateway:4100` (`NYLORUN_GATES_URL`). */
+    readonly url: string;
+    /** `NYLORUN_GATES_TOKEN`. */
+    readonly token: string;
+    /** Sent as `Nylorun-Tenant`; the gate checks it against its database's Tenant. */
+    readonly tenantId?: string;
+    /** How long an MCP request may stay silent. Default `GATE_CLIENT_TIMEOUT_MS`. */
+    readonly timeoutMs?: number;
+}
+export declare function httpToolGate(options: HttpToolGateOptions): ToolGate;