@nylorun/runtime 0.14.0-beta → 0.15.1-beta

package/dist/api/gate/routes.js

@@ -0,0 +1,235 @@
+/**
+ * The gates service's HTTP routes (blueprint §15, P1.1): the Model Gate's IR endpoint, the Tool
+ * Gate's remote MCP and delivery routes (F4.1), and the health and readiness probes. Internal:
+ * only the loop calls them, with the stack's gates token, so they are not in the published
+ * OpenAPI documents. The wire formats are `gates/contract.ts` and `gates/tool-contract.ts`.
+ */
+import { createHash } from "node:crypto";
+import { Hono } from "hono";
+import { bodyLimit } from "hono/body-limit";
+import { isTenantId } from "@nylorun/core/compatibility";
+import { MAX_MODEL_CALL_BYTES, MODEL_CALLS_PATH, ModelCallBodySchema, TENANT_HEADER, } from "../../gates/contract.js";
+import { InflightConflict } from "../../gates/inflight.js";
+import { mountKeysRoutes } from "./keys.js";
+import { DELIVERIES_PATH, DELIVERY_HEADERS, DeliveryBodySchema, MAX_TOOL_BODY_BYTES, MCP_CLOSE_PATH, MCP_CONNECT_PATH, MCP_LIST_PATH, McpListBodySchema, McpServerBodySchema, TOOL_CALLS_PATH, ToolCallBodySchema, } from "../../gates/tool-contract.js";
+import { post } from "../../tenant/outbound.js";
+import { adminKeyMatches } from "../../host/http.js";
+import { canonical } from "../../store/canonical.js";
+const invalid = (message) => ({
+    error: { code: "invalid_request", message },
+});
+export function createGatesApp(options) {
+    const app = new Hono();
+    const maxSize = options.maxBodyBytes ?? MAX_MODEL_CALL_BYTES;
+    app.get("/health", (c) => c.json({ status: "ok" }));
+    app.get("/ready", async (c) => (await options.ready()) ? c.json({ ready: true }) : c.json({ ready: false }, 503));
+    const authorized = async (c, next) => {
+        const presented = /^Bearer (.+)$/.exec(c.req.header("authorization") ?? "")?.[1];
+        if (!adminKeyMatches(presented, options.token)) {
+            const body = {
+                error: {
+                    code: "gate_unauthorized",
+                    message: "Missing or wrong gates token; the caller and the gateway must share NYLORUN_GATES_TOKEN",
+                },
+            };
+            return c.json(body, 401);
+        }
+        await next();
+    };
+    const tenantOf = (c) => {
+        const tenantId = c.req.header(TENANT_HEADER);
+        return tenantId !== undefined && !isTenantId(tenantId) ? false : tenantId;
+    };
+    const toolBodies = bodyLimit({
+        maxSize: MAX_TOOL_BODY_BYTES,
+        onError: (c) => c.json(invalid(`A request body may be at most ${MAX_TOOL_BODY_BYTES} bytes`), 400),
+    });
+    /** The parsed body, or the 400 to answer. */
+    async function read(c, schema) {
+        const tenantId = tenantOf(c);
+        if (tenantId === false)
+            return { ok: false, response: c.json(invalid(`The ${TENANT_HEADER} header must name a Tenant`), 400) };
+        let raw;
+        try {
+            raw = await c.req.json();
+        }
+        catch {
+            return { ok: false, response: c.json(invalid("The body must be JSON"), 400) };
+        }
+        const parsed = schema.safeParse(raw);
+        if (!parsed.success)
+            return {
+                ok: false,
+                response: c.json(invalid(`Invalid request: ${parsed.error.issues[0]?.message ?? "malformed"}`), 400),
+            };
+        return { ok: true, tenantId, body: parsed.data };
+    }
+    if (options.keys)
+        mountKeysRoutes(app, {
+            authorized,
+            keys: options.keys,
+            logger: options.logger ?? { info() { }, warn() { }, error() { } },
+        });
+    const mcp = options.mcp;
+    if (mcp) {
+        app.post(MCP_CONNECT_PATH, authorized, toolBodies, async (c) => {
+            const request = await read(c, McpServerBodySchema);
+            if (!request.ok)
+                return request.response;
+            return c.json(await mcp.connect(request.tenantId, request.body.server));
+        });
+        app.post(MCP_LIST_PATH, authorized, toolBodies, async (c) => {
+            const request = await read(c, McpListBodySchema);
+            if (!request.ok)
+                return request.response;
+            const { server, cursor } = request.body;
+            return c.json(await mcp.list(request.tenantId, server, cursor, c.req.raw.signal));
+        });
+        app.post(MCP_CLOSE_PATH, authorized, toolBodies, async (c) => {
+            const request = await read(c, McpServerBodySchema);
+            if (!request.ok)
+                return request.response;
+            await mcp.close(request.body.server);
+            return c.body(null, 204);
+        });
+        const toolCalls = options.toolCalls;
+        app.post(`${TOOL_CALLS_PATH}/:key/cancel`, authorized, (c) => {
+            if (tenantOf(c) === false)
+                return c.json(invalid(`The ${TENANT_HEADER} header must name a Tenant`), 400);
+            toolCalls?.cancel(c.req.param("key"));
+            return c.body(null, 204);
+        });
+        app.post(TOOL_CALLS_PATH, authorized, toolBodies, async (c) => {
+            const request = await read(c, ToolCallBodySchema);
+            if (!request.ok)
+                return request.response;
+            const signal = c.req.raw.signal;
+            const key = c.req.header("idempotency-key");
+            try {
+                // Keyed: the call runs under its own signal, once, and outlives this request (G3).
+                const answer = key && toolCalls
+                    ? await untilAborted(toolCalls.run(request.tenantId, key, createHash("sha256").update(canonical(request.body)).digest("hex"), request.body), signal)
+                    : await mcp.call(request.tenantId, request.body, signal);
+                if (signal.aborted)
+                    return new Response(null, { status: 499 });
+                return c.json(answer);
+            }
+            catch (error) {
+                if (error instanceof InflightConflict) {
+                    const body = { error: { code: "gate_conflict", message: error.message } };
+                    return c.json(body, 409);
+                }
+                if (signal.aborted)
+                    return new Response(null, { status: 499 });
+                throw error;
+            }
+        });
+    }
+    const policy = options.delivery;
+    if (policy) {
+        app.post(DELIVERIES_PATH, authorized, toolBodies, async (c) => {
+            const request = await read(c, DeliveryBodySchema);
+            if (!request.ok)
+                return request.response;
+            const { url, body, headers, timeoutMs } = request.body;
+            const forwarded = {};
+            for (const [name, value] of Object.entries(headers)) {
+                if (!DELIVERY_HEADERS.has(name.toLowerCase()))
+                    return c.json(invalid(`A delivery may not carry the header ${name}`), 400);
+                forwarded[name] = value;
+            }
+            const signal = c.req.raw.signal;
+            const result = await post(url, body, forwarded, {
+                policy,
+                signal: AbortSignal.any([signal, AbortSignal.timeout(timeoutMs)]),
+            });
+            if (signal.aborted)
+                return new Response(null, { status: 499 });
+            const answer = {
+                result: result.kind === "response"
+                    ? {
+                        kind: "response",
+                        status: result.status,
+                        headers: result.headers,
+                        body: result.body.toString("base64"),
+                    }
+                    : result,
+            };
+            return c.json(answer);
+        });
+    }
+    app.post(`${MODEL_CALLS_PATH}/:key/cancel`, authorized, (c) => {
+        // Optional, as on a call: the gate serves one Tenant, so the key alone names the call.
+        const tenantId = c.req.header(TENANT_HEADER);
+        if (tenantId !== undefined && !isTenantId(tenantId))
+            return c.json(invalid(`The ${TENANT_HEADER} header must name a Tenant`), 400);
+        options.inflight.cancel(c.req.param("key"));
+        return c.body(null, 204);
+    });
+    app.post(MODEL_CALLS_PATH, authorized, bodyLimit({
+        maxSize,
+        onError: (c) => c.json(invalid(`A model call body may be at most ${maxSize} bytes`), 400),
+    }), async (c) => {
+        // Optional: the gate serves its database's one Tenant, and refuses a call naming another.
+        const tenantId = c.req.header(TENANT_HEADER);
+        if (tenantId !== undefined && !isTenantId(tenantId))
+            return c.json(invalid(`The ${TENANT_HEADER} header must name a Tenant`), 400);
+        let raw;
+        try {
+            raw = await c.req.json();
+        }
+        catch {
+            return c.json(invalid("The body must be JSON"), 400);
+        }
+        const parsed = ModelCallBodySchema.safeParse(raw);
+        if (!parsed.success)
+            return c.json(invalid(`Invalid model call: ${parsed.error.issues[0]?.message ?? "malformed"}`), 400);
+        const { call, ...ids } = parsed.data;
+        const request = {
+            ...(tenantId === undefined ? {} : { tenantId }),
+            ...ids,
+            call: call,
+        };
+        const signal = c.req.raw.signal;
+        const key = c.req.header("idempotency-key");
+        try {
+            let outcome;
+            if (key) {
+                // Keyed: the call runs under its own signal and outlives this request (P1.2). The
+                // gate serves one Tenant, so the effect id alone is the key.
+                const hash = createHash("sha256").update(canonical(parsed.data)).digest("hex");
+                outcome = await untilAborted(options.inflight.run(key, hash, (own) => options.modelGate.call(request, own)), signal);
+            }
+            else
+                outcome = await options.modelGate.call(request, signal);
+            return c.json({ outcome });
+        }
+        catch (error) {
+            if (error instanceof InflightConflict) {
+                const body = { error: { code: "gate_conflict", message: error.message } };
+                return c.json(body, 409);
+            }
+            // The caller went away (or cancelled): nobody reads the answer.
+            if (signal.aborted)
+                return new Response(null, { status: 499 });
+            throw error;
+        }
+    });
+    return app;
+}
+/** `promise`, or a rejection as soon as `signal` aborts (the call itself keeps running). */
+function untilAborted(promise, signal) {
+    if (signal.aborted)
+        return Promise.reject(signal.reason);
+    return new Promise((resolve, reject) => {
+        const onAbort = () => reject(signal.reason);
+        signal.addEventListener("abort", onAbort, { once: true });
+        promise.then((value) => {
+            signal.removeEventListener("abort", onAbort);
+            resolve(value);
+        }, (error) => {
+            signal.removeEventListener("abort", onAbort);
+            reject(error);
+        });
+    });
+}

package/dist/api/http/define.js

@@ -70,14 +70,6 @@ export function tenantRoute(api, access, route, handler) {
     const schemes = [...new Set(access.credentials.map((credential) => SCHEMES[credential]))];
     const headers = z.object({
         "Nylorun-Protocol": z.string().meta({ description: `The protocol version, \`${PROTOCOL_VERSION}\`` }),
-        ...(access.browser || takes("publishable")
-            ? {
-                "Nylorun-Tenant": z
-                    .string()
-                    .optional()
-                    .meta({ description: "The Tenant; optional with a publishable key, which names it" }),
-            }
-            : { "Nylorun-Tenant": z.string().meta({ description: "The Tenant" }) }),
         ...(takes("subject")
             ? {
                 "Nylorun-Subject": z

package/dist/api/http/routes/access.js

@@ -35,15 +35,18 @@ export function accessRoutes(api) {
         tags: ["Access"],
         summary: "Get the public keys subject and delivery tokens are signed with",
         description: "A JSON Web Key Set, to verify a subject token or a delivery token without calling the " +
-            "Runtime. No credential is needed: `Nylorun-Tenant` alone names the Tenant.",
+            "Runtime. No credential is needed.",
         responses: { 200: json(Jwks, "The public keys") },
     }, async (c) => {
-        const keys = c.env.tenant.signingKeys;
-        const kek = keys.kek();
-        const rows = await c.env.tenant.store.tx(async (t) => {
-            await keys.ensure(t, kek);
-            return t.signingKeys(["standby", "current", "previous"]);
-        });
+        // Anonymous: reads the public keys. Only when the current or standby key is missing does
+        // it ask the keys service to create it, so a verifier never caches a set without them.
+        const ctx = c.env.tenant;
+        const read = () => ctx.store.tx((t) => t.signingKeys(["standby", "current", "previous"]));
+        let rows = await read();
+        if (!complete(rows)) {
+            await ctx.keys.ensureSigningKeys();
+            rows = await read();
+        }
         return jsonResponse(200, { keys: rows.map(publicJwk) });
     });
     tenantRoute(api, APPLICATION, {
@@ -89,12 +92,13 @@ export function accessRoutes(api) {
         responses: { 200: json(SigningKeyList, "Standby, current, previous and revoked keys") },
     }, async (c) => {
         requireApplication(c.get("scope"));
-        const keys = c.env.tenant.signingKeys;
-        const kek = keys.kek();
-        const rows = await c.env.tenant.store.tx(async (t) => {
-            await keys.ensure(t, kek);
-            return t.signingKeys();
-        });
+        const ctx = c.env.tenant;
+        const read = () => ctx.store.tx((t) => t.signingKeys());
+        let rows = await read();
+        if (!complete(rows)) {
+            await ctx.keys.ensureSigningKeys();
+            rows = await read();
+        }
         return jsonResponse(200, { keys: rows.map(signingKeyView) });
     });
     tenantRoute(api, APPLICATION, {
@@ -112,11 +116,10 @@ export function accessRoutes(api) {
         requireApplication(c.get("scope"));
         const ctx = c.env.tenant;
         const request = RotateSigningKeysRequestSchema.parse(await readJson(c.req.raw));
-        const keys = ctx.signingKeys;
-        const kek = keys.kek();
-        const rows = await ctx.store.tx(async (t) => keys.rotate(t, kek, (await readPolicy(t)).tokens.maxTtlSeconds, request.force === true));
+        const maxTtlSeconds = await ctx.store.tx(async (t) => (await readPolicy(t)).tokens.maxTtlSeconds);
+        const keys = await ctx.keys.rotateSigningKeys({ maxTtlSeconds, force: request.force === true });
         ctx.config.logger.info("signing keys rotated", { force: request.force === true });
-        return jsonResponse(200, { keys: rows.map(signingKeyView) });
+        return jsonResponse(200, { keys });
     });
     tenantRoute(api, APPLICATION, {
         method: "post",
@@ -153,7 +156,7 @@ export function accessRoutes(api) {
         path: "/v1/access/publishable-keys",
         tags: ["Access"],
         summary: "Create a publishable key",
-        description: "A key a browser page on one of the origins sends as `Nylorun-Key`. Public by design; it names the Tenant and grants the policy's anonymous scopes.",
+        description: "A key a browser page on one of the origins sends as `Nylorun-Key`. Public by design; it grants the policy's anonymous scopes.",
         request: { body: body(CreatePublishableKeyRequest) },
         responses: {
             200: json(PublishableKey, "The key"),
@@ -257,3 +260,7 @@ export async function revokeSubject(ctx, subject) {
     ctx.config.logger.info("subject revoked", { epoch });
     return { subject, epoch };
 }
+/** True when the Tenant has a current and a standby signing key. */
+function complete(rows) {
+    return rows.some((row) => row.state === "current") && rows.some((row) => row.state === "standby");
+}

package/dist/api/http/routes/tenant.d.ts

@@ -1,6 +1,7 @@
 /**
  * The Tenant's own settings (`/v1/tenant/**`): its status, reset, a first configuration, the
- * model it calls and the sandboxes its sessions get.
+ * model it calls, what its model calls cost and may cost (budgets), and the sandboxes its
+ * sessions get.
  *
  * A reset that deletes sessions moves the Tenant to a new basin generation, so a session
  * created again starts in an empty basin; the old basin is deleted after a grace period.

package/dist/api/http/routes/tenant.js

@@ -1,6 +1,7 @@
 import { z } from "zod";
-import { PutHostModelRequestSchema, PutTenantSandboxRequestSchema, ResetTenantRequestSchema, SeedTenantConfigRequestSchema, SelectHostModelRequestSchema, } from "@nylorun/core/contracts";
-import { HostModelCatalog, HostModelView, ListProvidersResponse, PutHostModelRequest, PutTenantSandboxRequest, ResetTenantRequest, ResetTenantResponse, SeedTenantConfigRequest, SeedTenantConfigResponse, SelectHostModelRequest, TenantSandboxView, TenantStatus, } from "../../components.js";
+import { ModelUsageQuerySchema, PutModelBudgetsRequestSchema, PutHostModelRequestSchema, PutTenantSandboxRequestSchema, ResetTenantRequestSchema, SeedTenantConfigRequestSchema, SelectHostModelRequestSchema, } from "@nylorun/core/contracts";
+import { HostModelCatalog, HostModelView, ListProvidersResponse, ModelBudgets, ModelUsageTotals, PutModelBudgetsRequest, PutHostModelRequest, PutTenantSandboxRequest, ResetTenantRequest, ResetTenantResponse, SeedTenantConfigRequest, SeedTenantConfigResponse, SelectHostModelRequest, TenantSandboxView, TenantStatus, } from "../../components.js";
+import { periodStart } from "../../../gates/meter.js";
 import { hostModelCatalog } from "../../../model/catalog.js";
 import { sandboxConfigErrors } from "../../../sandbox/resolve.js";
 import { effectiveSandboxConfig, readSandboxConfig, writeSandboxConfig, } from "../../../sandbox/tenant-config.js";
@@ -27,6 +28,21 @@ const body = (schema) => ({
     required: true,
     content: { "application/json": { schema } },
 });
+const budgetRow = (budget, updatedAt) => ({
+    scope: budget.scope,
+    scopeId: budget.scope === "agent" ? budget.id : "*",
+    period: budget.period ?? null,
+    limitUsd: budget.limitUsd ?? null,
+    limitTokens: budget.limitTokens ?? null,
+    updatedAt,
+});
+const budgetView = (row) => ({
+    scope: row.scope,
+    ...(row.scope === "agent" ? { id: row.scopeId } : {}),
+    ...(row.period ? { period: row.period } : {}),
+    ...(row.limitUsd !== null ? { limitUsd: row.limitUsd } : {}),
+    ...(row.limitTokens !== null ? { limitTokens: row.limitTokens } : {}),
+});
 /** `GET /v1/tenant/sandbox`: the backend report and the configuration with defaults applied. */
 async function sandboxView(ctx) {
     const config = await ctx.store.tx((t) => readSandboxConfig(t));
@@ -97,7 +113,7 @@ export function tenantRoutes(api) {
     }, async (c) => {
         const ctx = c.env.tenant;
         const request = SeedTenantConfigRequestSchema.parse(await readJson(c.req.raw));
-        return jsonResponse(200, await seedTenantConfig({ store: ctx.store, vault: ctx.vault }, request));
+        return jsonResponse(200, await seedTenantConfig({ store: ctx.store, vault: ctx.vault, keys: ctx.keys }, request));
     });
     tenantRoute(api, settings(["tenant:settings", "agents:write"]), {
         method: "get",
@@ -133,6 +149,62 @@ export function tenantRoutes(api) {
         await ctx.store.tx((t) => writeSandboxConfig(t, config));
         return jsonResponse(200, await sandboxView(ctx));
     });
+    tenantRoute(api, SETTINGS, {
+        method: "get",
+        path: "/v1/tenant/usage",
+        tags: ["Tenant"],
+        summary: "Get what the Tenant's model calls used",
+        description: "Totals from the model usage ledger, which the model gate writes once per call: for the Tenant, one agent or one turn, over the current UTC day or month, or all time.",
+        request: { query: ModelUsageQuerySchema },
+        responses: { 200: json(ModelUsageTotals, "The calls, tokens and cost") },
+    }, async (c) => {
+        const parsed = ModelUsageQuerySchema.safeParse(c.req.query());
+        if (!parsed.success)
+            return fail(400, parsed.error.issues[0]?.message ?? "Invalid query");
+        const { scope, id, period } = parsed.data;
+        if (scope !== "tenant" && !id)
+            fail(400, `The ${scope} scope needs an id`);
+        const since = period === "total" ? undefined : periodStart(period, new Date());
+        const totals = await c.env.tenant.store.tx((t) => t.modelUsageTotals({
+            scope,
+            ...(scope !== "tenant" ? { id: id } : {}),
+            ...(since ? { since } : {}),
+        }));
+        return jsonResponse(200, {
+            scope,
+            ...(scope !== "tenant" ? { id } : {}),
+            period,
+            ...(since ? { since } : {}),
+            ...totals,
+        });
+    });
+    tenantRoute(api, SETTINGS, {
+        method: "get",
+        path: "/v1/tenant/budgets",
+        tags: ["Tenant"],
+        summary: "Get the Tenant's model budgets",
+        responses: { 200: json(ModelBudgets, "The hard caps on model spend") },
+    }, async (c) => {
+        const rows = await c.env.tenant.store.tx((t) => t.listModelBudgets());
+        return jsonResponse(200, { budgets: rows.map(budgetView) });
+    });
+    tenantRoute(api, SETTINGS, {
+        method: "put",
+        path: "/v1/tenant/budgets",
+        tags: ["Tenant"],
+        summary: "Set the Tenant's model budgets",
+        description: "Replaces every budget. Before each model call the gate checks the scope's spend against its cap; once a cap is reached the call fails with `budget_exhausted` and the turn with `model.budget_exhausted`. An empty list removes every cap.",
+        request: { body: body(PutModelBudgetsRequest) },
+        responses: { 200: json(ModelBudgets, "The budgets now in force") },
+    }, async (c) => {
+        const { budgets } = PutModelBudgetsRequestSchema.parse(await readJson(c.req.raw));
+        const updatedAt = new Date().toISOString();
+        const rows = await c.env.tenant.store.tx(async (t) => {
+            await t.putModelBudgets(budgets.map((budget) => budgetRow(budget, updatedAt)));
+            return t.listModelBudgets();
+        });
+        return jsonResponse(200, { budgets: rows.map(budgetView) });
+    });
     tenantRoute(api, settings(["tenant:settings", "agents:write"]), {
         method: "get",
         path: "/v1/tenant/providers",
@@ -156,7 +228,7 @@ export function tenantRoutes(api) {
         responses: { 200: json(HostModelView, "The model now in force") },
     }, async (c) => {
         const ctx = c.env.tenant;
-        return jsonResponse(200, await ctx.vault.putHostModel(PutHostModelRequestSchema.parse(await readJson(c.req.raw))));
+        return jsonResponse(200, await ctx.keys.putHostModel(PutHostModelRequestSchema.parse(await readJson(c.req.raw))));
     });
     tenantRoute(api, SETTINGS, {
         method: "put",
@@ -167,6 +239,6 @@ export function tenantRoutes(api) {
         responses: { 200: json(HostModelView, "The model now in force") },
     }, async (c) => {
         const ctx = c.env.tenant;
-        return jsonResponse(200, await ctx.vault.selectHostModel(SelectHostModelRequestSchema.parse(await readJson(c.req.raw))));
+        return jsonResponse(200, await ctx.keys.selectHostModel(SelectHostModelRequestSchema.parse(await readJson(c.req.raw))));
     });
 }

package/dist/api/http/routes/vaults.js

@@ -112,7 +112,7 @@ export function vaultRoutes(api) {
             fail(403, "A subject token cannot store OAuth refresh credentials", {
                 code: "scope_required",
             });
-        return jsonResponse(200, await c.env.tenant.vault.createCredential(c.req.param("vaultId"), request));
+        return jsonResponse(200, await c.env.tenant.keys.createCredential(c.req.param("vaultId"), request));
     });
     tenantRoute(api, OWN_VAULTS, {
         method: "get",
@@ -151,7 +151,7 @@ export function vaultRoutes(api) {
     }, async (c) => {
         await ownerFor(c);
         const request = RotateCredentialRequestSchema.parse(await readJson(c.req.raw));
-        return jsonResponse(200, await c.env.tenant.vault.rotateCredential(c.req.param("vaultId"), c.req.param("credentialId"), request));
+        return jsonResponse(200, await c.env.tenant.keys.rotateCredential(c.req.param("vaultId"), c.req.param("credentialId"), request));
     });
     tenantRoute(api, OWN_VAULTS, {
         method: "delete",

package/dist/api/openapi.js

@@ -49,7 +49,7 @@ function hostRoutes() {
         path: "/ready",
         tags: ["Host"],
         summary: "Check the Runtime is ready",
-        description: "The listeners, Tenant discovery, Postgres, Restate and S2.",
+        description: "The listeners, the Tenant (open), Postgres, Restate and S2.",
         responses: {
             200: {
                 description: "Ready",
@@ -75,7 +75,7 @@ function tenantSchemes(registry) {
         type: "apiKey",
         in: "header",
         name: "Nylorun-Key",
-        description: "A publishable key, sent by a browser page on one of its origins. Public by design: it names the Tenant and grants the access policy's anonymous scopes.",
+        description: "A publishable key, sent by a browser page on one of its origins. Public by design: it grants the access policy's anonymous scopes.",
     });
 }
 let tenant;
@@ -94,13 +94,13 @@ export function tenantDocument() {
         info: {
             title: "Nylorun Runtime: Tenant API",
             version: RUNTIME_VERSION,
-            description: "Agents, sessions and their events, vaults, access and the Tenant's settings, for one Tenant (`Nylorun-Tenant`). Every request sends `Nylorun-Protocol`. Who may call each operation is its `security` and its `x-nylorun-credentials`, `x-nylorun-scopes` (the subject scopes that reach it) and `x-nylorun-browser` fields.",
+            description: "Agents, sessions and their events, vaults, access and the Tenant's settings. A Runtime serves one Tenant: its URL is the Tenant's, and no request names it. Every request sends `Nylorun-Protocol`. Who may call each operation is its `security` and its `x-nylorun-credentials`, `x-nylorun-scopes` (the subject scopes that reach it) and `x-nylorun-browser` fields.",
             "x-nylorun-protocol": PROTOCOL,
         },
         servers: [
             {
                 url: "{origin}",
-                description: "A Runtime: the local stack (`nylorun start`), or where yours runs",
+                description: "A Runtime: a local Tenant (`nylorun start`), or where yours runs",
                 variables: { origin: { default: "http://localhost:8787" } },
             },
         ],
@@ -113,7 +113,6 @@ export function adminDocument() {
         return admin;
     // Only the routes' declarations are read: nothing is served from this app.
     const api = createAdminApi({
-        module: undefined,
         status: () => Promise.reject(new Error("Not served")),
         shutdown: () => { },
     });
@@ -123,13 +122,13 @@ export function adminDocument() {
         info: {
             title: "Nylorun Runtime: Admin API",
             version: RUNTIME_VERSION,
-            description: "Tenants and the Host's status, with the admin key. Served on the operator listener when the Host has one; the public listener answers these routes with the opaque 404.",
+            description: "The Host's status, its Tenant's state and shutdown, with the admin key. Served on the operator listener when the Host has one; the public listener answers these routes with the opaque 404.",
             "x-nylorun-protocol": PROTOCOL,
         },
         servers: [
             {
                 url: "{origin}",
-                description: "The operator listener: the local stack's, or where yours runs",
+                description: "The operator listener: a local Tenant's, or where yours runs",
                 variables: { origin: { default: "http://localhost:8788" } },
             },
         ],

package/dist/gates/contract.d.ts

@@ -0,0 +1,51 @@
+/**
+ * The gates service's wire format (blueprint §15, P1.1). Internal: only the loop calls it, so
+ * it is not in the published OpenAPI documents.
+ *
+ * `POST /nylorun/v1/model-calls`
+ * - Headers: `Authorization: Bearer <NYLORUN_GATES_TOKEN>`, `Idempotency-Key: <effect id>`,
+ *   and optionally `Nylorun-Tenant: <tenant id>`, which must then be the database's one
+ *   Tenant (a call naming another is refused).
+ * - Body: `ModelCallBody`, at most `MAX_MODEL_CALL_BYTES`.
+ * - `200 {outcome}` once the call has finished, whether the outcome is a candidate or a
+ *   failure; nothing is sent while it runs. `401 gate_unauthorized` for a missing or wrong
+ *   token, `400 invalid_request` for a malformed Tenant header or a bad body, `409
+ *   gate_conflict` when a different request already runs under the same key.
+ * - With an `Idempotency-Key` the call outlives its client (P1.2): a re-send with the same key
+ *   and body joins it, or gets its outcome for 30 minutes. Without one, a client that goes
+ *   away aborts the call.
+ *
+ * `POST /nylorun/v1/model-calls/{key}/cancel` (same headers): aborts the keyed call; `204`
+ * whether or not it exists.
+ */
+import { z } from "zod";
+import type { ModelGateOutcome } from "./model-gate.js";
+export declare const MODEL_CALLS_PATH = "/nylorun/v1/model-calls";
+/** Header naming the Tenant a call is for: optional, and checked against the gate's Tenant. */
+export declare const TENANT_HEADER = "nylorun-tenant";
+/** Largest request body the gate reads: one `ModelCall` with its whole projected history. */
+export declare const MAX_MODEL_CALL_BYTES: number;
+export declare const ModelCallBodySchema: z.ZodObject<{
+    sessionId: z.ZodString;
+    turnId: z.ZodString;
+    agentId: z.ZodString;
+    effectId: z.ZodString;
+    invocationId: z.ZodString;
+    call: z.ZodObject<{
+        prompt: z.ZodArray<z.ZodUnknown>;
+        tools: z.ZodArray<z.ZodObject<{
+            name: z.ZodString;
+        }, z.core.$loose>>;
+    }, z.core.$loose>;
+}, z.core.$strip>;
+export type ModelCallBody = z.infer<typeof ModelCallBodySchema>;
+export interface ModelCallResponse {
+    readonly outcome: ModelGateOutcome;
+}
+/** An error answer: `{error: {code, message}}`. */
+export interface GateErrorBody {
+    readonly error: {
+        readonly code: "gate_unauthorized" | "invalid_request" | "gate_conflict";
+        readonly message: string;
+    };
+}

package/dist/gates/contract.js

@@ -0,0 +1,37 @@
+/**
+ * The gates service's wire format (blueprint §15, P1.1). Internal: only the loop calls it, so
+ * it is not in the published OpenAPI documents.
+ *
+ * `POST /nylorun/v1/model-calls`
+ * - Headers: `Authorization: Bearer <NYLORUN_GATES_TOKEN>`, `Idempotency-Key: <effect id>`,
+ *   and optionally `Nylorun-Tenant: <tenant id>`, which must then be the database's one
+ *   Tenant (a call naming another is refused).
+ * - Body: `ModelCallBody`, at most `MAX_MODEL_CALL_BYTES`.
+ * - `200 {outcome}` once the call has finished, whether the outcome is a candidate or a
+ *   failure; nothing is sent while it runs. `401 gate_unauthorized` for a missing or wrong
+ *   token, `400 invalid_request` for a malformed Tenant header or a bad body, `409
+ *   gate_conflict` when a different request already runs under the same key.
+ * - With an `Idempotency-Key` the call outlives its client (P1.2): a re-send with the same key
+ *   and body joins it, or gets its outcome for 30 minutes. Without one, a client that goes
+ *   away aborts the call.
+ *
+ * `POST /nylorun/v1/model-calls/{key}/cancel` (same headers): aborts the keyed call; `204`
+ * whether or not it exists.
+ */
+import { z } from "zod";
+export const MODEL_CALLS_PATH = "/nylorun/v1/model-calls";
+/** Header naming the Tenant a call is for: optional, and checked against the gate's Tenant. */
+export const TENANT_HEADER = "nylorun-tenant";
+/** Largest request body the gate reads: one `ModelCall` with its whole projected history. */
+export const MAX_MODEL_CALL_BYTES = 32 * 1024 * 1024;
+export const ModelCallBodySchema = z.object({
+    sessionId: z.string().min(1),
+    turnId: z.string().min(1),
+    agentId: z.string().min(1),
+    effectId: z.string().min(1),
+    invocationId: z.string().min(1),
+    call: z.looseObject({
+        prompt: z.array(z.unknown()),
+        tools: z.array(z.looseObject({ name: z.string() })),
+    }),
+});

package/dist/gates/handler.d.ts

@@ -0,0 +1,21 @@
+import type { Logger } from "../tenant/types.js";
+import type { ModelCallSettings, ModelGate, ModelGateRequest } from "./model-gate.js";
+import { type TenantVaults } from "./tenant-vaults.js";
+export interface ModelCallHandlerOptions {
+    readonly vaults: TenantVaults;
+    readonly logger: Logger;
+    /** Retries and timeouts; `piModel`'s defaults when absent. */
+    readonly settings?: ModelCallSettings;
+}
+/**
+ * A model call as the gate receives it: the Tenant is optional (the loop of a protocol 4
+ * Runtime names it; the gate serves the database's one Tenant either way).
+ */
+export type ModelCallRequest = Omit<ModelGateRequest, "tenantId"> & {
+    readonly tenantId?: string;
+};
+/** What the gate's route calls: a `ModelGate` whose request may leave the Tenant out. */
+export interface ModelCallHandler {
+    call(request: ModelCallRequest, signal: AbortSignal): ReturnType<ModelGate["call"]>;
+}
+export declare function createModelCallHandler(options: ModelCallHandlerOptions): ModelCallHandler;