@nylorun/runtime 0.17.0-beta → 0.19.1-beta

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

@@ -0,0 +1,77 @@
+import { z } from "zod";
+import { DEFINITION_FILE_MAX_BYTES } from "@nylorun/core/contracts";
+import { DefinitionFileView } from "../../components.js";
+import { normalizeContentType } from "../../../artifacts/media-types.js";
+import { hasDefinitionFile, putDefinitionFile } from "../../../tenant/definition-files.js";
+import { fail } from "../../../tenant/http.js";
+import { tenantRoute } from "../define.js";
+import { jsonResponse } from "../respond.js";
+const APPLICATION = { credentials: ["application"], scopes: "never" };
+const UPLOAD = { ...APPLICATION, bytes: true };
+const file = z.object({
+    file: z.string().meta({ description: "`sha256:` and the SHA-256 of the file's bytes, 64 lowercase hex digits" }),
+});
+const view = (description) => ({
+    description,
+    content: { "application/json": { schema: DefinitionFileView } },
+});
+/** The declared `Content-Length`, when there is one. */
+function declaredLength(request) {
+    const raw = request.headers.get("content-length");
+    return raw !== null && /^\d+$/.test(raw) ? Number(raw) : undefined;
+}
+/** The declared media type, unless it is absent or `application/octet-stream`. */
+function declaredType(request) {
+    const raw = request.headers.get("content-type") ?? undefined;
+    if (raw === undefined)
+        return undefined;
+    const type = normalizeContentType(raw);
+    if (type === undefined)
+        return fail(400, "Content-Type is not a media type");
+    return type.toLowerCase().startsWith("application/octet-stream") ? undefined : type;
+}
+export function fileRoutes(api) {
+    tenantRoute(api, UPLOAD, {
+        method: "put",
+        path: "/v1/files/{file}",
+        tags: ["Definition files"],
+        summary: "Upload a definition file",
+        description: `Stores the body, at most ${DEFINITION_FILE_MAX_BYTES} bytes, at the SHA-256 the path names; a body with another hash stores nothing (\`400\`). A file the Tenant holds already is kept as it is (\`200\`).`,
+        request: {
+            params: file,
+            body: {
+                required: true,
+                description: "The file's bytes",
+                content: { "application/octet-stream": { schema: z.string().meta({ format: "binary" }) } },
+            },
+        },
+        responses: {
+            200: view("The Tenant held the file already"),
+            201: view("The file, stored"),
+            413: { description: `Larger than ${DEFINITION_FILE_MAX_BYTES} bytes (\`limit_exceeded\`)` },
+        },
+    }, async (c) => {
+        const request = c.req.raw;
+        const length = declaredLength(request);
+        const type = declaredType(request);
+        const stored = await putDefinitionFile(c.env.tenant, c.req.param("file"), {
+            body: request.body,
+            ...(length === undefined ? {} : { declaredBytes: length }),
+            ...(type === undefined ? {} : { contentType: type }),
+        }, request.signal);
+        return jsonResponse(stored.status, stored.view);
+    });
+    tenantRoute(api, APPLICATION, {
+        method: "head",
+        path: "/v1/files/{file}",
+        tags: ["Definition files"],
+        summary: "Whether the Runtime holds a definition file",
+        description: "`200` when the Tenant holds the file, `404` when it does not: upload it.",
+        request: { params: file },
+        responses: { 200: { description: "The Tenant holds the file" } },
+    }, async (c) => {
+        if (!(await hasDefinitionFile(c.env.tenant, c.req.param("file"))))
+            return fail(404, "The Runtime does not hold this file");
+        return new Response(null, { status: 200 });
+    });
+}

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

@@ -0,0 +1,10 @@
+/**
+ * Application keys (`/v1/tenant/keys`, the Management API, protocol 8): a management key
+ * creates, rotates, lists and deletes the Tenant's application keys by name. It never touches a
+ * management key, `studio` or `bootstrap`: those come only from the Tenant's machine
+ * (`nylorun-operate`, `NYLORUN_MANAGEMENT_KEY_FILE`), so a leaked management key cannot mint
+ * another. A rotated or deleted key stops authenticating on its next request.
+ */
+import type { OpenAPIHono } from "@hono/zod-openapi";
+import type { TenantEnv } from "../app.js";
+export declare function keyRoutes(api: OpenAPIHono<TenantEnv>): void;

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

@@ -0,0 +1,64 @@
+import { z } from "zod";
+import { DeleteOperatorKeyResponse, ListOperatorKeysResponse, PutOperatorKeyResponse, } from "../../components.js";
+import { fail } from "../../../tenant/http.js";
+import { operatorKeys } from "../../../tenant/operator-keys.js";
+import { tenantRoute } from "../define.js";
+import { jsonResponse } from "../respond.js";
+const MANAGEMENT = { credentials: ["management"], scopes: "never" };
+const keyId = z.object({
+    keyId: z
+        .string()
+        .meta({ description: "The key's name: `^[a-z][a-z0-9-]{0,31}$`, never `studio` or `bootstrap`" }),
+});
+const json = (schema, description) => ({
+    description,
+    content: { "application/json": { schema } },
+});
+function refused(refusal) {
+    return fail(400, refusal.message, {
+        code: refusal.reason === "invalid" ? "invalid_request" : "request_rejected",
+    });
+}
+export function keyRoutes(api) {
+    tenantRoute(api, MANAGEMENT, {
+        method: "get",
+        path: "/v1/tenant/keys",
+        tags: ["Application keys"],
+        summary: "List the Tenant's keys",
+        description: "Every key of the Tenant by name, with its role (`application`, `management` or `studio`) and when it was issued. Keys themselves are never shown again.",
+        responses: { 200: json(ListOperatorKeysResponse, "The keys, by id") },
+    }, async (c) => jsonResponse(200, { keys: await operatorKeys(c.env.tenant.store).list() }));
+    tenantRoute(api, MANAGEMENT, {
+        method: "put",
+        path: "/v1/tenant/keys/{keyId}",
+        tags: ["Application keys"],
+        summary: "Create or rotate an application key",
+        description: "Issues a new application key named `keyId` and returns it this once. An application key of that name is replaced: the old one stops authenticating at once. A management key, `studio` and `bootstrap` are refused.",
+        request: { params: keyId },
+        responses: {
+            200: json(PutOperatorKeyResponse, "The new key, shown once"),
+            400: { description: "Not a key name, a reserved name, or a management key's name" },
+        },
+    }, async (c) => {
+        const put = await operatorKeys(c.env.tenant.store).put(c.req.param("keyId"), "application");
+        return "reason" in put ? refused(put) : jsonResponse(200, put);
+    });
+    tenantRoute(api, MANAGEMENT, {
+        method: "delete",
+        path: "/v1/tenant/keys/{keyId}",
+        tags: ["Application keys"],
+        summary: "Delete an application key",
+        description: "The key stops authenticating at once. A management key, `studio` and `bootstrap` are refused.",
+        request: { params: keyId },
+        responses: {
+            200: json(DeleteOperatorKeyResponse, "The key is deleted"),
+            400: { description: "Not a key name, a reserved name, or a management key's name" },
+        },
+    }, async (c) => {
+        const id = c.req.param("keyId");
+        const deleted = await operatorKeys(c.env.tenant.store).delete(id, "application");
+        if (typeof deleted !== "boolean")
+            return refused(deleted);
+        return deleted ? jsonResponse(200, { id, deleted: true }) : fail(404, `No key ${id}`);
+    });
+}

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

@@ -22,18 +22,21 @@ export function describeCaller(scope) {
                 sandboxes: [...(scope.sandboxes ?? [])],
                 via: `issuer:${scope.issuer}`,
             };
+        case "management":
+            return { scopes: [], agents: [], via: `management:${scope.principalId}` };
         default:
             return fail(403, "This credential acts on no Tenant resource");
     }
 }
 export function meRoutes(api) {
-    tenantRoute(api, { credentials: ["application", "subject", "token"], scopes: "any" }, {
+    tenantRoute(api, { credentials: ["application", "subject", "management", "token"], scopes: "any" }, {
         method: "get",
         path: "/v1/me",
         tags: ["Access"],
         summary: "Get who the caller is",
         description: "The subject, scopes, agents and sandbox grants of the credential that sends it: an " +
-            "application key (alone or acting for a subject), or a trusted issuer's token " +
+            "application key (alone or acting for a subject), a management key " +
+            "(`via: management:<principalId>`, no scopes, no agents), or a trusted issuer's token " +
             "(`via: issuer:<name>`).",
         responses: {
             200: {

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

@@ -0,0 +1,66 @@
+/** Read-only sub-resources and opt-in pages. The execution routes retain their contracts. */
+import type { OpenAPIHono } from "@hono/zod-openapi";
+import { z } from "zod";
+import type { TenantEnv } from "../app.js";
+export declare const pageQuery: z.ZodObject<{
+    limit: z.ZodOptional<z.ZodCoercedNumber<unknown>>;
+    cursor: z.ZodOptional<z.ZodString>;
+}, z.core.$strip>;
+export declare const sessionPageQuery: z.ZodObject<{
+    limit: z.ZodOptional<z.ZodCoercedNumber<unknown>>;
+    cursor: z.ZodOptional<z.ZodString>;
+    agentId: z.ZodOptional<z.ZodString>;
+    status: z.ZodOptional<z.ZodEnum<{
+        cancelled: "cancelled";
+        completed: "completed";
+        failed: "failed";
+        idle: "idle";
+        paused: "paused";
+        runnable: "runnable";
+        running: "running";
+        uncertain: "uncertain";
+        waiting: "waiting";
+    }>>;
+    sandboxId: z.ZodOptional<z.ZodString>;
+    ownerUserId: z.ZodOptional<z.ZodString>;
+}, z.core.$strict>;
+export declare function parseQuery<T>(schema: z.ZodType<T>, query: unknown): T;
+export declare function sessionPage(ctx: TenantEnv["Bindings"]["tenant"], scope: TenantEnv["Variables"]["scope"], query: Record<string, string>): Promise<{
+    sessions: {
+        id: string;
+        agentId: string;
+        ownerUserId: string;
+        status: "cancelled" | "completed" | "failed" | "idle" | "paused" | "runnable" | "running" | "uncertain" | "waiting";
+        activeTurnId: string | null;
+        lastTurnId: string | null;
+        sandboxId: string | null;
+        createdAt: string | null;
+        lastEventAt: string | null;
+    }[];
+    nextCursor: string | null;
+}>;
+export declare function sandboxPage(ctx: TenantEnv["Bindings"]["tenant"], scope: TenantEnv["Variables"]["scope"], query: Record<string, string>, labels: Record<string, string>): Promise<{
+    sandboxes: {
+        id: string;
+        kind: "pod" | "virtual";
+        labels: Record<string, string>;
+        spec: Record<string, unknown>;
+        state: "creating" | "ready" | "running" | "stopped";
+        pod?: {
+            desired: "deleted" | "running" | "suspended";
+            observed: "creating" | "deleting" | "expired" | "failed" | "lost" | "running" | "suspended";
+            volumeGeneration: number;
+            hostEpoch: number;
+            expiresAt?: string | undefined;
+            reason?: string | undefined;
+        } | undefined;
+        sessions: {
+            id: string;
+            activeTurnId: string | null;
+        }[];
+        createdAt: string;
+        updatedAt: string;
+    }[];
+    nextCursor: string | null;
+}>;
+export declare function readRoutes(api: OpenAPIHono<TenantEnv>): void;

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

@@ -0,0 +1,127 @@
+import { z } from "zod";
+import { SESSION_STATUSES } from "@nylorun/core/contracts";
+import { SessionManifestView, SessionUsageTotals, ModelCallsPage, ModelCallExportPage, } from "../../components.js";
+import { readAccess, readStoreOf } from "../../../reads/access.js";
+import { requireApplication, requirePrincipal } from "../../../tenant/auth.js";
+import { fail } from "../../../tenant/http.js";
+import { sandboxGrantsOf } from "../../../tenant/sandboxes.js";
+import { tenantRoute } from "../define.js";
+import { jsonResponse } from "../respond.js";
+export const pageQuery = z.object({
+    limit: z.coerce.number().int().min(1).max(200).optional(),
+    cursor: z.string().optional(),
+});
+export const sessionPageQuery = pageQuery
+    .extend({
+    agentId: z.string().optional(),
+    status: z.enum(SESSION_STATUSES).optional(),
+    sandboxId: z.string().optional(),
+    ownerUserId: z.string().optional(),
+})
+    .strict();
+export function parseQuery(schema, query) {
+    const result = schema.safeParse(query);
+    return result.success ? result.data : fail(400, "Invalid read query", { code: "query_invalid" });
+}
+export async function sessionPage(ctx, scope, query) {
+    const { limit, cursor, ...filters } = parseQuery(sessionPageQuery, query);
+    if (limit === undefined)
+        return fail(400, "Pagination requires limit");
+    if (filters.ownerUserId !== undefined)
+        requireApplication(scope);
+    return readStoreOf(ctx).sessions(filters, { limit, cursor }, readAccess(scope));
+}
+export async function sandboxPage(ctx, scope, query, labels) {
+    const { limit, cursor } = parseQuery(pageQuery.extend({ label: z.string().optional() }).strict(), query);
+    if (limit === undefined)
+        return fail(400, "Pagination requires limit");
+    return readStoreOf(ctx).sandboxes(labels, { limit, cursor }, readAccess(scope), sandboxGrantsOf(scope));
+}
+export function readRoutes(api) {
+    const sessionId = z.object({ sessionId: z.string() });
+    const turnQuery = z.object({ turnId: z.string().optional() }).strict();
+    tenantRoute(api, { credentials: ["application", "subject"], scopes: ["agents:read", "agents:write"] }, {
+        method: "get",
+        path: "/v1/sessions/{sessionId}/manifest",
+        tags: ["Sessions"],
+        summary: "Read the session's pinned manifest",
+        request: { params: sessionId },
+        responses: {
+            200: {
+                description: "The pinned public manifest",
+                content: { "application/json": { schema: SessionManifestView } },
+            },
+        },
+    }, async (c) => {
+        requirePrincipal(c.get("scope"));
+        return jsonResponse(200, await readStoreOf(c.env.tenant).manifest(c.req.param("sessionId"), readAccess(c.get("scope"))));
+    });
+    for (const kind of ["usage", "calls/model"]) {
+        const query = kind === "usage"
+            ? turnQuery
+            : turnQuery
+                .extend({
+                limit: z.coerce.number().int().min(1).max(200).default(50),
+                cursor: z.string().optional(),
+            })
+                .strict();
+        // Spend is the application's to show: no subject scope reaches it (`tenant:settings`,
+        // which used to, is retired in protocol 8).
+        tenantRoute(api, { credentials: ["application"], scopes: "never" }, {
+            method: "get",
+            path: `/v1/sessions/{sessionId}/${kind}`,
+            tags: ["Sessions"],
+            summary: kind === "usage"
+                ? "Read a session's recorded model usage"
+                : "Page a session's model calls",
+            request: { params: sessionId, query },
+            responses: {
+                200: {
+                    description: "Recorded usage, including duplicate billed calls",
+                    content: {
+                        "application/json": {
+                            schema: kind === "usage" ? SessionUsageTotals : ModelCallsPage,
+                        },
+                    },
+                },
+            },
+        }, async (c) => {
+            requirePrincipal(c.get("scope"));
+            const store = readStoreOf(c.env.tenant), access = readAccess(c.get("scope")), id = c.req.param("sessionId");
+            if (kind === "usage") {
+                const q = parseQuery(turnQuery, c.req.query());
+                return jsonResponse(200, await store.usage(id, q.turnId, access));
+            }
+            const q = parseQuery(turnQuery
+                .extend({
+                limit: z.coerce.number().int().min(1).max(200).default(50),
+                cursor: z.string().optional(),
+            })
+                .strict(), c.req.query());
+            return jsonResponse(200, await store.modelCalls(id, q.turnId, q, access));
+        });
+    }
+    const exportQuery = z
+        .object({
+        after: z.string().optional(),
+        limit: z.coerce.number().int().min(1).max(1000).default(200),
+    })
+        .strict();
+    // The whole Tenant's ledger is the Management API's (protocol 8): a management key, as itself.
+    tenantRoute(api, { credentials: ["management"], scopes: "never" }, {
+        method: "get",
+        path: "/v1/tenant/calls/model",
+        tags: ["Tenant"],
+        summary: "Export committed model calls in safe transaction order",
+        request: { query: exportQuery },
+        responses: {
+            200: {
+                description: "An unfiltered resumable ledger page",
+                content: { "application/json": { schema: ModelCallExportPage } },
+            },
+        },
+    }, async (c) => {
+        const q = parseQuery(exportQuery, c.req.query());
+        return jsonResponse(200, await readStoreOf(c.env.tenant).exportModel(q.after, q.limit));
+    });
+}

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

@@ -1,10 +1,11 @@
 import { z } from "zod";
 import { isSandboxId, PutSandboxRequestSchema } from "@nylorun/core/contracts";
-import { DeleteSandboxResponse, ListSandboxEventsResponse, ListSandboxesResponse, PutSandboxRequest, SandboxView, } from "../../components.js";
+import { DeleteSandboxResponse, ListSandboxEventsResponse, ListSandboxesResponse, SandboxPage, PutSandboxRequest, SandboxView, } from "../../components.js";
 import { fail } from "../../../tenant/http.js";
 import { deleteSandbox, getSandbox, listSandboxes, putSandbox, resetSandbox, sandboxEventsOf, stopSandbox, } from "../../../tenant/sandboxes.js";
 import { readJson } from "../body.js";
 import { tenantRoute } from "../define.js";
+import { pageQuery, sandboxPage } from "./reads.js";
 import { jsonResponse } from "../respond.js";
 /** Reading a sandbox: any caller that may use sessions, or change sandboxes. */
 const READ = {
@@ -50,15 +51,17 @@ export function sandboxRoutes(api) {
         summary: "List sandboxes",
         description: "Every sandbox with all the labels asked for. A token caller sees only the sandboxes its grants reach.",
         request: {
-            query: z.object({
+            query: pageQuery.extend({
                 label: z
                     .union([z.string(), z.array(z.string())])
                     .optional()
                     .meta({ description: "`key=value`; repeat it to require several labels" }),
             }),
         },
-        responses: { 200: json(ListSandboxesResponse, "The sandboxes") },
-    }, async (c) => jsonResponse(200, await listSandboxes(c.env.tenant, labelsOf(c.req.queries("label")), c.get("scope"))));
+        responses: { 200: json(z.union([ListSandboxesResponse, SandboxPage]), "The sandboxes; limit opts into pagination") },
+    }, async (c) => jsonResponse(200, c.req.query("limit") !== undefined
+        ? await sandboxPage(c.env.tenant, c.get("scope"), c.req.query(), labelsOf(c.req.queries("label")))
+        : await listSandboxes(c.env.tenant, labelsOf(c.req.queries("label")), c.get("scope"))));
     tenantRoute(api, WRITE, {
         method: "put",
         path: "/v1/sandboxes/{sandboxId}",

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

@@ -1,17 +1,18 @@
 import { RESPONSE_ALREADY_SENT } from "@hono/node-server/utils/response";
 import { z } from "zod";
-import { PutAgentRequestSchema, PutSessionRequestSchema } from "@nylorun/core/contracts";
+import { PutAgentRequestSchema, PutSessionRequestSchema, SessionCommandSchema, } from "@nylorun/core/contracts";
 import { handleSessionSandboxTool, SandboxRouteError } from "../../../core/sandbox-routes.js";
-import { ListAgentsResponse, ListPublicAgentsResponse, ListSessionsResponse, SessionEvent, PutAgentRequest, PutAgentResponse, PutSessionRequest, SandboxToolOutcome, SessionItemsResponse, SessionView, StreamClosedFrame, } from "../../components.js";
-import { sandboxRouteDeps } from "../../../tenant/actions.js";
+import { AcceptedResponse, ListAgentsResponse, ListPublicAgentsResponse, ListSessionsResponse, SessionPage, HistoryPage, SessionEvent, PutAgentRequest, PutAgentResponse, PutSessionRequest, SandboxToolOutcome, SessionCommand, SessionItemsResponse, SessionView, StreamClosedFrame, } from "../../components.js";
 import { accessOf, requireApplication } from "../../../tenant/auth.js";
+import { command } from "../../../tenant/commands.js";
 import { loadSession, sessionOf } from "../../../tenant/context.js";
 import { fail } from "../../../tenant/http.js";
-import { sandboxGrantsOf } from "../../../tenant/sandboxes.js";
+import { sandboxGrantsOf, sandboxRouteDeps } from "../../../tenant/sandboxes.js";
 import { readHistory, requestCursor, streamHolderOf, streamSessionEvents } from "../../../tenant/session-streams.js";
 import { listAgentsPublic, listDefinitions, listSessions, putDefinition, putSession, sessionView, } from "../../../tenant/sessions.js";
 import { readJson } from "../body.js";
 import { tenantRoute } from "../define.js";
+import { pageQuery, sessionPage, sessionPageQuery, parseQuery } from "./reads.js";
 import { jsonResponse } from "../respond.js";
 const OWN_SESSIONS = {
     credentials: ["application", "subject", "token"],
@@ -45,6 +46,18 @@ async function sessionBelow(ctx, incoming, id, access) {
     return requestCursor(incoming, urlOf(incoming));
 }
 export function sessionRoutes(api) {
+    tenantRoute(api, OWN_SESSIONS, {
+        method: "post",
+        path: "/v1/sessions/{sessionId}/commands",
+        tags: ["Sessions"],
+        summary: "Send a command to a session",
+        description: "A message starts a turn; the others answer what the session waits on, or cancel. Idempotent on the command's `idempotencyKey`.",
+        request: { params: sessionId, body: body(SessionCommand) },
+        responses: {
+            200: json(AcceptedResponse, "The command, accepted"),
+            409: { description: "A turn is running, or the session does not wait on this" },
+        },
+    }, async (c) => jsonResponse(200, await command(c.env.tenant, c.req.param("sessionId"), SessionCommandSchema.parse(await readJson(c.req.raw)), c.get("scope"))));
     tenantRoute(api, {
         credentials: ["application", "subject", "token"],
         scopes: ["agents:read", "agents:write"],
@@ -80,10 +93,12 @@ export function sessionRoutes(api) {
         tags: ["Sessions"],
         summary: "List sessions",
         description: "Acting for a person, only theirs.",
-        request: { query: z.object({ agentId: z.string().optional() }) },
-        responses: { 200: json(ListSessionsResponse, "The sessions") },
+        request: { query: sessionPageQuery },
+        responses: { 200: json(z.union([ListSessionsResponse, SessionPage]), "The sessions; limit opts into pagination") },
     }, async (c) => {
         const scope = c.get("scope");
+        if (c.req.query("limit") !== undefined)
+            return jsonResponse(200, await sessionPage(c.env.tenant, scope, c.req.query()));
         return jsonResponse(200, await listSessions(c.env.tenant, c.req.query("agentId") ?? null, accessOf(scope)));
     });
     tenantRoute(api, OWN_SESSIONS, {
@@ -129,19 +144,21 @@ export function sessionRoutes(api) {
         request: {
             params: sessionId,
             query: resume.extend({
+                limit: pageQuery.shape.limit,
                 agent: z
                     .string()
                     .optional()
                     .meta({ description: "Only the events of this agent (the root agent, or one it uses as a tool)" }),
             }),
         },
-        responses: { 200: json(SessionItemsResponse, "Events up to now, and the cursor to continue") },
+        responses: { 200: json(z.union([SessionItemsResponse, HistoryPage]), "Events up to now; limit returns a bounded page and tail") },
     }, async (c) => {
         const scope = c.get("scope");
         const ctx = c.env.tenant;
         const id = c.req.param("sessionId");
         const cursor = await sessionBelow(ctx, c.env.incoming, id, accessOf(scope));
-        return jsonResponse(200, await readHistory(ctx, id, cursor, c.req.query("agent")));
+        const { limit } = parseQuery(pageQuery.pick({ limit: true }), { limit: c.req.query("limit") });
+        return jsonResponse(200, await readHistory(ctx, id, cursor, c.req.query("agent"), limit));
     });
     tenantRoute(api, OWN_SESSIONS, {
         method: "get",

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

@@ -16,11 +16,8 @@ import { readJson } from "../body.js";
 import { pathSegments, tenantRoute } from "../define.js";
 import { jsonResponse } from "../respond.js";
 import { rearmPodTimers } from "../../../tenant/sandboxes.js";
-const settings = (scopes) => ({
-    credentials: scopes === "never" ? ["application"] : ["application", "subject"],
-    scopes,
-});
-const SETTINGS = settings(["tenant:settings"]);
+/** Every Management API route (`/v1/tenant/*`): a management key, acting as itself (protocol 8). */
+const MANAGEMENT = { credentials: ["management"], scopes: "never" };
 const json = (schema, description) => ({
     description,
     content: { "application/json": { schema } },
@@ -79,7 +76,7 @@ async function clusterOf(ctx) {
     }
 }
 export function tenantRoutes(api) {
-    tenantRoute(api, SETTINGS, {
+    tenantRoute(api, MANAGEMENT, {
         method: "get",
         path: "/v1/tenant",
         tags: ["Tenant"],
@@ -103,7 +100,7 @@ export function tenantRoutes(api) {
             harness: harnessStatusOf(ctx),
         }));
     });
-    tenantRoute(api, settings("never"), {
+    tenantRoute(api, MANAGEMENT, {
         method: "post",
         path: "/v1/tenant/reset",
         tags: ["Tenant"],
@@ -134,7 +131,7 @@ export function tenantRoutes(api) {
         ctx.closing = false;
         return jsonResponse(200, { ok: true });
     });
-    tenantRoute(api, settings("never"), {
+    tenantRoute(api, MANAGEMENT, {
         method: "put",
         path: "/v1/tenant/config/seed",
         tags: ["Tenant"],
@@ -147,7 +144,7 @@ export function tenantRoutes(api) {
         const request = SeedTenantConfigRequestSchema.parse(await readJson(c.req.raw));
         return jsonResponse(200, await seedTenantConfig({ store: ctx.store, vault: ctx.vault, keys: ctx.keys }, request));
     });
-    tenantRoute(api, settings(["tenant:settings", "agents:write"]), {
+    tenantRoute(api, MANAGEMENT, {
         method: "get",
         path: "/v1/tenant/models",
         tags: ["Tenant"],
@@ -157,14 +154,14 @@ export function tenantRoutes(api) {
         c.env.tenant;
         return jsonResponse(200, hostModelCatalog());
     });
-    tenantRoute(api, SETTINGS, {
+    tenantRoute(api, MANAGEMENT, {
         method: "get",
         path: "/v1/tenant/sandbox",
         tags: ["Tenant"],
         summary: "Get the Tenant's sandbox configuration",
         responses: { 200: json(TenantSandboxView, "The backend in use and the configuration in force") },
     }, async (c) => jsonResponse(200, await sandboxView(c.env.tenant)));
-    tenantRoute(api, SETTINGS, {
+    tenantRoute(api, MANAGEMENT, {
         method: "put",
         path: "/v1/tenant/sandbox",
         tags: ["Tenant"],
@@ -183,7 +180,7 @@ export function tenantRoutes(api) {
         await rearmPodTimers(ctx);
         return jsonResponse(200, await sandboxView(ctx));
     });
-    tenantRoute(api, SETTINGS, {
+    tenantRoute(api, MANAGEMENT, {
         method: "get",
         path: "/v1/tenant/usage",
         tags: ["Tenant"],
@@ -212,7 +209,7 @@ export function tenantRoutes(api) {
             ...totals,
         });
     });
-    tenantRoute(api, SETTINGS, {
+    tenantRoute(api, MANAGEMENT, {
         method: "get",
         path: "/v1/tenant/budgets",
         tags: ["Tenant"],
@@ -222,7 +219,7 @@ export function tenantRoutes(api) {
         const rows = await c.env.tenant.store.tx((t) => t.listModelBudgets());
         return jsonResponse(200, { budgets: rows.map(budgetView) });
     });
-    tenantRoute(api, SETTINGS, {
+    tenantRoute(api, MANAGEMENT, {
         method: "put",
         path: "/v1/tenant/budgets",
         tags: ["Tenant"],
@@ -239,21 +236,21 @@ export function tenantRoutes(api) {
         });
         return jsonResponse(200, { budgets: rows.map(budgetView) });
     });
-    tenantRoute(api, settings(["tenant:settings", "agents:write"]), {
+    tenantRoute(api, MANAGEMENT, {
         method: "get",
         path: "/v1/tenant/providers",
         tags: ["Tenant"],
         summary: "List the model providers the Tenant has credentials for",
         responses: { 200: json(ListProvidersResponse, "The providers") },
     }, async (c) => jsonResponse(200, await (c.env.tenant).vault.listHostProviders()));
-    tenantRoute(api, SETTINGS, {
+    tenantRoute(api, MANAGEMENT, {
         method: "get",
         path: "/v1/tenant/model",
         tags: ["Tenant"],
         summary: "Get the Tenant's model",
         responses: { 200: json(HostModelView, "The model its sessions call") },
     }, async (c) => jsonResponse(200, await (c.env.tenant).vault.getHostModel()));
-    tenantRoute(api, SETTINGS, {
+    tenantRoute(api, MANAGEMENT, {
         method: "put",
         path: "/v1/tenant/model",
         tags: ["Tenant"],
@@ -264,7 +261,7 @@ export function tenantRoutes(api) {
         const ctx = c.env.tenant;
         return jsonResponse(200, await ctx.keys.putHostModel(PutHostModelRequestSchema.parse(await readJson(c.req.raw))));
     });
-    tenantRoute(api, SETTINGS, {
+    tenantRoute(api, MANAGEMENT, {
         method: "put",
         path: "/v1/tenant/model/selection",
         tags: ["Tenant"],

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

@@ -1,14 +1,15 @@
 /**
- * Vaults and their credentials (`/v1/vaults/**`): secrets a session's tools use. Only an
- * application key acting for no one (an operator key, Studio) reaches these routes (protocol 7):
- * a request acting for a subject, or a trusted issuer's token, is `403 scope_required`. The
- * installation's own vaults (`scope: "installation"`) attach to any session; a vault of one
- * person (`ownerUserId`) attaches only to that person's sessions. A person's own credentials
- * come from the operator's credential resolver (`vault/sources.ts`), not from these routes.
+ * Vaults and their credentials (`/v1/tenant/vaults/**`, the Management API, protocol 8): secrets
+ * a session's tools use. Only a management key (or Studio's key, acting as itself) reaches these
+ * routes; an application key is `403 key_role_mismatch`, and nothing acts for a subject here. The
+ * installation's own vaults (`scope: "installation"`) attach to any session (`vaultIds`); a vault
+ * of one person (`ownerUserId`) attaches only to that person's sessions. A person's own
+ * credentials come from the operator's credential resolver (`vault/sources.ts`), not from these
+ * routes.
  *
- * MCP OAuth connect (F9 C2): an application key starts one into an installation vault
- * (`/oauth/start`); the authorization server sends the browser back to the anonymous, unversioned
- * `GET /v1/oauth/callback`. Both only route: the gateway's keys module does the OAuth (F9-D14).
+ * MCP OAuth connect: a management key starts one into an installation vault (`/oauth/start`);
+ * the authorization server sends the browser back to the anonymous, unversioned
+ * `GET /v1/oauth/callback`. Both only route: the gateway's keys module does the OAuth.
  */
 import type { OpenAPIHono } from "@hono/zod-openapi";
 import type { TenantEnv } from "../app.js";