@nylorun/runtime 0.13.0-beta → 0.15.0-beta

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

@@ -0,0 +1,3 @@
+import type { OpenAPIHono } from "@hono/zod-openapi";
+import type { TenantEnv } from "../app.js";
+export declare function sessionRoutes(api: OpenAPIHono<TenantEnv>): void;

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

@@ -0,0 +1,205 @@
+import { RESPONSE_ALREADY_SENT } from "@hono/node-server/utils/response";
+import { z } from "zod";
+import { PutAgentRequestSchema, PutSessionRequestSchema } 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 { accessOf, requireApplication } from "../../../tenant/auth.js";
+import { loadSession, sessionOf } from "../../../tenant/context.js";
+import { fail } from "../../../tenant/http.js";
+import { readHistory, requestCursor, 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 { jsonResponse } from "../respond.js";
+const OWN_SESSIONS = {
+    credentials: ["application", "subject", "token"],
+    scopes: ["sessions:own"],
+    browser: true,
+};
+const json = (schema, description) => ({
+    description,
+    content: { "application/json": { schema } },
+});
+const body = (schema) => ({
+    required: true,
+    content: { "application/json": { schema } },
+});
+const sessionId = z.object({ sessionId: z.string() });
+const SANDBOX_TOOLS = ["bash", "read", "write", "edit", "grep", "glob"];
+const resume = z.object({
+    cursor: z
+        .string()
+        .optional()
+        .meta({ description: "Continue after this event's cursor; `Last-Event-ID` works too" }),
+});
+function urlOf(incoming) {
+    return new URL(incoming.url ?? "/", "http://runtime");
+}
+/**
+ * A session route below the session itself: the session must exist and be the caller's, and a
+ * resume cursor must be well formed, before anything else.
+ */
+async function sessionBelow(ctx, incoming, id, access) {
+    await loadSession(ctx, id, access);
+    return requestCursor(incoming, urlOf(incoming));
+}
+export function sessionRoutes(api) {
+    tenantRoute(api, {
+        credentials: ["application", "subject", "token", "publishable"],
+        scopes: ["agents:read", "agents:write"],
+        browser: true,
+    }, {
+        method: "get",
+        path: "/v1/agents",
+        tags: ["Agents"],
+        summary: "List agents",
+        description: "With an application key, every definition, manifest included. With a subject token or a publishable key, only the agents it may use, by name.",
+        responses: {
+            200: json(z.union([ListAgentsResponse, ListPublicAgentsResponse]), "The agents"),
+        },
+    }, async (c) => {
+        const scope = c.get("scope");
+        const ctx = c.env.tenant;
+        if (scope.kind === "publishable")
+            return jsonResponse(200, await listAgentsPublic(ctx, scope.agents));
+        return jsonResponse(200, scope.kind === "token"
+            ? await listAgentsPublic(ctx, scope.agents)
+            : await listDefinitions(ctx));
+    });
+    tenantRoute(api, { credentials: ["application", "subject"], scopes: ["agents:write"] }, {
+        method: "put",
+        path: "/v1/agents/{agentId}",
+        tags: ["Agents"],
+        summary: "Put an agent's definition",
+        request: { params: z.object({ agentId: z.string() }), body: body(PutAgentRequest) },
+        responses: { 200: json(PutAgentResponse, "The definition, stored") },
+    }, async (c) => {
+        return jsonResponse(200, await putDefinition(c.env.tenant, c.req.param("agentId"), PutAgentRequestSchema.parse(await readJson(c.req.raw))));
+    });
+    tenantRoute(api, OWN_SESSIONS, {
+        method: "get",
+        path: "/v1/sessions",
+        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") },
+    }, async (c) => {
+        const scope = c.get("scope");
+        return jsonResponse(200, await listSessions(c.env.tenant, c.req.query("agentId") ?? null, accessOf(scope)));
+    });
+    tenantRoute(api, OWN_SESSIONS, {
+        method: "put",
+        path: "/v1/sessions/{sessionId}",
+        tags: ["Sessions"],
+        summary: "Open a session",
+        description: "Creates the session, or re-attaches vaults to an identical one. Its sandbox is chosen now and fixed for its life.",
+        request: { params: sessionId, body: body(PutSessionRequest) },
+        responses: {
+            200: json(SessionView, "The session"),
+            409: { description: "A session with this id was opened with other parameters" },
+        },
+    }, async (c) => {
+        const scope = c.get("scope");
+        const ctx = c.env.tenant;
+        const request = PutSessionRequestSchema.parse(await readJson(c.req.raw));
+        // Agent code may trust `info`: only an app server sets it.
+        if (scope.kind === "token" && request.info !== undefined)
+            fail(403, "A subject token cannot set session info", { code: "scope_required" });
+        const session = await putSession(ctx, c.req.param("sessionId"), request, accessOf(scope));
+        return jsonResponse(200, await ctx.store.tx((t) => sessionView(t, session)));
+    });
+    tenantRoute(api, OWN_SESSIONS, {
+        method: "get",
+        path: "/v1/sessions/{sessionId}",
+        tags: ["Sessions"],
+        summary: "Get a session",
+        request: { params: sessionId },
+        responses: { 200: json(SessionView, "The session") },
+    }, async (c) => {
+        const scope = c.get("scope");
+        const ctx = c.env.tenant;
+        const id = c.req.param("sessionId");
+        return jsonResponse(200, await ctx.store.tx(async (t) => sessionView(t, await sessionOf(t, id, accessOf(scope)))));
+    });
+    tenantRoute(api, OWN_SESSIONS, {
+        method: "get",
+        path: "/v1/sessions/{sessionId}/items",
+        tags: ["Sessions"],
+        summary: "Read a session's history",
+        request: {
+            params: sessionId,
+            query: resume.extend({
+                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") },
+    }, 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")));
+    });
+    tenantRoute(api, OWN_SESSIONS, {
+        method: "get",
+        path: "/v1/sessions/{sessionId}/events",
+        tags: ["Sessions"],
+        summary: "Follow a session's events",
+        description: "Server-sent events, each with its type as `event` and its cursor as `id`, from the cursor on. Events are on the `nylorun.event/2` envelope, typed by `SessionEvent`; a client ignores a type it does not know. A subject token's stream ends with `event: nylorun.closed` when the token expires or the subject is revoked. A `: keepalive` comment every 15 seconds.",
+        request: { params: sessionId, query: resume },
+        responses: {
+            200: {
+                description: "The session's events",
+                content: {
+                    "text/event-stream": {
+                        itemSchema: z.union([SessionEvent, StreamClosedFrame]),
+                    },
+                },
+            },
+        },
+    }, async (c) => {
+        const scope = c.get("scope");
+        const ctx = c.env.tenant;
+        const { incoming, outgoing } = c.env;
+        const id = c.req.param("sessionId");
+        const cursor = await sessionBelow(ctx, incoming, id, accessOf(scope));
+        await streamSessionEvents(ctx, incoming, outgoing, id, cursor, scope.kind === "token"
+            ? { subject: scope.subject, epoch: scope.epoch, expiresAt: scope.expiresAt }
+            : undefined);
+        return RESPONSE_ALREADY_SENT;
+    });
+    tenantRoute(api, { credentials: ["application"], scopes: "never" }, {
+        method: "post",
+        path: "/v1/sessions/{sessionId}/sandbox/{tool}",
+        tags: ["Sessions"],
+        summary: "Run a sandbox tool in a session",
+        description: "For an app's own tools; not while a turn is running.",
+        request: {
+            params: sessionId.extend({ tool: z.enum(SANDBOX_TOOLS) }),
+            body: body(z.looseObject({}).meta({ description: "The tool's input" })),
+        },
+        responses: {
+            200: json(SandboxToolOutcome, "The tool's output, or why it failed"),
+            409: { description: "A turn is running" },
+        },
+    }, async (c) => {
+        const scope = c.get("scope");
+        const ctx = c.env.tenant;
+        const id = c.req.param("sessionId");
+        await sessionBelow(ctx, c.env.incoming, id, accessOf(scope));
+        requireApplication(scope);
+        try {
+            return jsonResponse(200, await handleSessionSandboxTool(sandboxRouteDeps(ctx), id, c.req.param("tool"), await readJson(c.req.raw), c.req.raw.signal));
+        }
+        catch (error) {
+            if (error instanceof SandboxRouteError)
+                fail(error.status, error.message);
+            throw error;
+        }
+    });
+}

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

@@ -0,0 +1,11 @@
+/**
+ * The Tenant's own settings (`/v1/tenant/**`): its status, reset, a first configuration, the
+ * 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.
+ */
+import type { OpenAPIHono } from "@hono/zod-openapi";
+import type { TenantEnv } from "../app.js";
+export declare function tenantRoutes(api: OpenAPIHono<TenantEnv>): void;

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

@@ -0,0 +1,244 @@
+import { z } from "zod";
+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";
+import { fail } from "../../../tenant/http.js";
+import { clearObservers } from "../../../tenant/session-streams.js";
+import { usesFixtureModel } from "../../../tenant/model-setting.js";
+import { resetTenant } from "../../../tenant/reset.js";
+import { clearWork, drain } from "../../../tenant/scheduler.js";
+import { buildTenantStatus, seedTenantConfig } from "../../../tenant/status.js";
+import { tenantReset, streamsStatus, } from "../../../tenant/streams.js";
+import { readJson } from "../body.js";
+import { pathSegments, tenantRoute } from "../define.js";
+import { jsonResponse } from "../respond.js";
+const settings = (scopes) => ({
+    credentials: scopes === "never" ? ["application"] : ["application", "subject"],
+    scopes,
+});
+const SETTINGS = settings(["tenant:settings"]);
+const json = (schema, description) => ({
+    description,
+    content: { "application/json": { schema } },
+});
+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));
+    return { ...(await ctx.sandbox.report()), config: effectiveSandboxConfig(config) };
+}
+export function tenantRoutes(api) {
+    tenantRoute(api, SETTINGS, {
+        method: "get",
+        path: "/v1/tenant",
+        tags: ["Tenant"],
+        summary: "Get the Tenant's status",
+        responses: { 200: json(TenantStatus, "Readiness, model, sandboxes, streams and counts") },
+    }, async (c) => {
+        const ctx = c.env.tenant;
+        const { vault } = ctx;
+        return jsonResponse(200, await buildTenantStatus({
+            envelope: ctx.envelope,
+            config: ctx.config,
+            store: ctx.store,
+            vault,
+            sandbox: ctx.sandbox,
+            closing: ctx.closing || ctx.closed,
+            modelConfigured: !ctx.useVaultModel ||
+                (await ctx.store.tx((t) => usesFixtureModel(t))) ||
+                (await vault.getHostModel()).configured,
+            ...(ctx.stuckInvocations ? { stuckInvocations: ctx.stuckInvocations } : {}),
+            streamsStatus: () => streamsStatus(ctx),
+        }));
+    });
+    tenantRoute(api, settings("never"), {
+        method: "post",
+        path: "/v1/tenant/reset",
+        tags: ["Tenant"],
+        summary: "Reset the Tenant",
+        description: "Deletes its sessions, its sandboxes, or both, after draining or cancelling the turns in progress. The Tenant stays open.",
+        request: { body: body(ResetTenantRequest) },
+        responses: { 200: json(ResetTenantResponse, "Reset") },
+    }, async (c) => {
+        const ctx = c.env.tenant;
+        const request = ResetTenantRequestSchema.parse(await readJson(c.req.raw));
+        await drain(ctx, request.activeWork, 30_000);
+        // A sessions reset moves the Tenant to a new basin generation, so a session created
+        // again with the same id, during or after the reset, starts in an empty basin at 0.
+        const sessionsReset = request.scope !== "sandboxes";
+        await resetTenant({
+            store: ctx.store,
+            sandbox: ctx.sandbox,
+            paths: ctx.config.paths,
+            clearSessionState: () => {
+                clearWork(ctx);
+                clearObservers(ctx.sessionStreams);
+            },
+        }, request.scope);
+        if (sessionsReset)
+            await tenantReset(ctx);
+        // Reset leaves the Tenant open for new work.
+        ctx.closing = false;
+        return jsonResponse(200, { ok: true });
+    });
+    tenantRoute(api, settings("never"), {
+        method: "put",
+        path: "/v1/tenant/config/seed",
+        tags: ["Tenant"],
+        summary: "Seed the Tenant's configuration",
+        description: "Sets each setting the Tenant does not have yet; keeps the ones it has.",
+        request: { body: body(SeedTenantConfigRequest) },
+        responses: { 200: json(SeedTenantConfigResponse, "What was set, and what was kept") },
+    }, 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, keys: ctx.keys }, request));
+    });
+    tenantRoute(api, settings(["tenant:settings", "agents:write"]), {
+        method: "get",
+        path: "/v1/tenant/models",
+        tags: ["Tenant"],
+        summary: "List model providers and models",
+        responses: { 200: json(HostModelCatalog, "Provider and model names") },
+    }, async (c) => {
+        c.env.tenant;
+        return jsonResponse(200, hostModelCatalog());
+    });
+    tenantRoute(api, SETTINGS, {
+        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, {
+        method: "put",
+        path: "/v1/tenant/sandbox",
+        tags: ["Tenant"],
+        summary: "Set the Tenant's sandbox configuration",
+        description: "What a session gets when it names no sandbox, and the limits every session's sandbox must fit.",
+        request: { body: body(PutTenantSandboxRequest) },
+        responses: { 200: json(TenantSandboxView, "The configuration now in force") },
+    }, async (c) => {
+        const ctx = c.env.tenant;
+        const { requestId: _requestId, ...config } = PutTenantSandboxRequestSchema.parse(await readJson(c.req.raw));
+        const errors = sandboxConfigErrors(effectiveSandboxConfig(config));
+        if (errors.length > 0)
+            fail(400, errors.join(" "));
+        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",
+        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, {
+        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, {
+        method: "put",
+        path: "/v1/tenant/model",
+        tags: ["Tenant"],
+        summary: "Set a model provider's credentials",
+        request: { body: body(PutHostModelRequest) },
+        responses: { 200: json(HostModelView, "The model now in force") },
+    }, async (c) => {
+        const ctx = c.env.tenant;
+        return jsonResponse(200, await ctx.keys.putHostModel(PutHostModelRequestSchema.parse(await readJson(c.req.raw))));
+    });
+    tenantRoute(api, SETTINGS, {
+        method: "put",
+        path: "/v1/tenant/model/selection",
+        tags: ["Tenant"],
+        summary: "Choose the provider and model",
+        request: { body: body(SelectHostModelRequest) },
+        responses: { 200: json(HostModelView, "The model now in force") },
+    }, async (c) => {
+        const ctx = c.env.tenant;
+        return jsonResponse(200, await ctx.keys.selectHostModel(SelectHostModelRequestSchema.parse(await readJson(c.req.raw))));
+    });
+}

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

@@ -0,0 +1,8 @@
+/**
+ * Vaults and their credentials (`/v1/vaults/**`): secrets a session's tools use, owned by one
+ * person. Acting for a subject reaches only the subject's own vaults, and never on another's
+ * behalf.
+ */
+import type { OpenAPIHono } from "@hono/zod-openapi";
+import type { TenantEnv } from "../app.js";
+export declare function vaultRoutes(api: OpenAPIHono<TenantEnv>): void;

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

@@ -0,0 +1,167 @@
+import { z } from "zod";
+import { CreateCredentialRequestSchema, CreateVaultRequestSchema, RotateCredentialRequestSchema, } from "@nylorun/core/contracts";
+import { CreateCredentialRequest, CreateVaultRequest, CredentialInfo, DeletedResponse, ListCredentialsResponse, ListVaultsResponse, RotateCredentialRequest, VaultInfo, } from "../../components.js";
+import { ownerOf } from "../../../tenant/auth.js";
+import { fail } from "../../../tenant/http.js";
+import { readJson } from "../body.js";
+import { pathSegments, tenantRoute } from "../define.js";
+import { jsonResponse } from "../respond.js";
+const OWN_VAULTS = {
+    credentials: ["application", "subject", "token"],
+    scopes: ["vaults:own"],
+    browser: true,
+};
+const json = (schema, description) => ({
+    description,
+    content: { "application/json": { schema } },
+});
+const body = (schema) => ({
+    required: true,
+    content: { "application/json": { schema } },
+});
+const vaultId = z.object({ vaultId: z.string() });
+const credentialId = vaultId.extend({ credentialId: z.string() });
+/**
+ * Who a vault route acts for: the subject, or no one in particular (an application key). Below
+ * a vault, the vault must be the subject's before anything else.
+ */
+async function ownerFor(c) {
+    const { vault } = c.env.tenant;
+    const owner = ownerOf(c.get("scope"));
+    const id = c.req.param("vaultId");
+    if (id !== undefined && owner !== undefined)
+        await vault.assertOwner(id, owner);
+    return owner;
+}
+export function vaultRoutes(api) {
+    tenantRoute(api, OWN_VAULTS, {
+        method: "post",
+        path: "/v1/vaults",
+        tags: ["Vaults"],
+        summary: "Create a vault",
+        request: { body: body(CreateVaultRequest) },
+        responses: {
+            200: json(VaultInfo, "The vault"),
+            409: { description: "The idempotency key was used for another vault" },
+        },
+    }, async (c) => {
+        const owner = await ownerFor(c);
+        const request = CreateVaultRequestSchema.parse(await readJson(c.req.raw));
+        if (owner !== undefined && request.ownerUserId !== owner)
+            fail(403, "ownerUserId must be the subject");
+        return jsonResponse(200, await c.env.tenant.vault.createVault(request));
+    });
+    tenantRoute(api, OWN_VAULTS, {
+        method: "get",
+        path: "/v1/vaults",
+        tags: ["Vaults"],
+        summary: "List a person's vaults",
+        request: {
+            query: z.object({
+                ownerUserId: z
+                    .string()
+                    .optional()
+                    .meta({ description: "Whose vaults; required with an application key acting for no one" }),
+            }),
+        },
+        responses: { 200: json(ListVaultsResponse, "The vaults") },
+    }, async (c) => {
+        const owner = await ownerFor(c);
+        const ownerUserId = c.req.query("ownerUserId") ?? owner ?? fail(400, "ownerUserId is required");
+        if (owner !== undefined && ownerUserId !== owner)
+            fail(403, "ownerUserId must be the subject");
+        return jsonResponse(200, { vaults: await c.env.tenant.vault.listVaults(ownerUserId) });
+    });
+    tenantRoute(api, OWN_VAULTS, {
+        method: "get",
+        path: "/v1/vaults/{vaultId}",
+        tags: ["Vaults"],
+        summary: "Get a vault",
+        request: { params: vaultId },
+        responses: { 200: json(VaultInfo, "The vault") },
+    }, async (c) => {
+        await ownerFor(c);
+        return jsonResponse(200, await c.env.tenant.vault.getVault(c.req.param("vaultId")));
+    });
+    tenantRoute(api, OWN_VAULTS, {
+        method: "delete",
+        path: "/v1/vaults/{vaultId}",
+        tags: ["Vaults"],
+        summary: "Delete a vault and its credentials",
+        request: { params: vaultId },
+        responses: { 200: json(DeletedResponse, "Deleted") },
+    }, async (c) => {
+        await ownerFor(c);
+        return jsonResponse(200, await c.env.tenant.vault.deleteVault(c.req.param("vaultId")));
+    });
+    tenantRoute(api, OWN_VAULTS, {
+        method: "post",
+        path: "/v1/vaults/{vaultId}/credentials",
+        tags: ["Vaults"],
+        summary: "Add a credential",
+        description: "A bearer token or OAuth tokens, bound to the URLs a tool may send them to. A subject token cannot store OAuth refresh credentials.",
+        request: { params: vaultId, body: body(CreateCredentialRequest) },
+        responses: { 200: json(CredentialInfo, "The credential, without its secret") },
+    }, async (c) => {
+        await ownerFor(c);
+        const request = CreateCredentialRequestSchema.parse(await readJson(c.req.raw));
+        // The Runtime calls a refresh credential's token endpoint itself: never for a browser.
+        if (c.get("scope").kind === "token" &&
+            request.auth.type === "oauth" &&
+            request.auth.refresh)
+            fail(403, "A subject token cannot store OAuth refresh credentials", {
+                code: "scope_required",
+            });
+        return jsonResponse(200, await c.env.tenant.keys.createCredential(c.req.param("vaultId"), request));
+    });
+    tenantRoute(api, OWN_VAULTS, {
+        method: "get",
+        path: "/v1/vaults/{vaultId}/credentials",
+        tags: ["Vaults"],
+        summary: "List a vault's credentials",
+        request: { params: vaultId },
+        responses: { 200: json(ListCredentialsResponse, "The credentials, without their secrets") },
+    }, async (c) => {
+        await ownerFor(c);
+        return jsonResponse(200, {
+            credentials: await c.env.tenant.vault.listCredentials(c.req.param("vaultId")),
+        });
+    });
+    tenantRoute(api, OWN_VAULTS, {
+        method: "get",
+        path: "/v1/vaults/{vaultId}/credentials/{credentialId}",
+        tags: ["Vaults"],
+        summary: "Get a credential",
+        request: { params: credentialId },
+        responses: { 200: json(CredentialInfo, "The credential, without its secret") },
+    }, async (c) => {
+        await ownerFor(c);
+        return jsonResponse(200, await c.env.tenant.vault.getCredential(c.req.param("vaultId"), c.req.param("credentialId")));
+    });
+    tenantRoute(api, OWN_VAULTS, {
+        method: "post",
+        path: "/v1/vaults/{vaultId}/credentials/{credentialId}",
+        tags: ["Vaults"],
+        summary: "Rotate a credential's secret",
+        request: { params: credentialId, body: body(RotateCredentialRequest) },
+        responses: {
+            200: json(CredentialInfo, "The credential"),
+            409: { description: "A credential's type cannot change" },
+        },
+    }, async (c) => {
+        await ownerFor(c);
+        const request = RotateCredentialRequestSchema.parse(await readJson(c.req.raw));
+        return jsonResponse(200, await c.env.tenant.keys.rotateCredential(c.req.param("vaultId"), c.req.param("credentialId"), request));
+    });
+    tenantRoute(api, OWN_VAULTS, {
+        method: "delete",
+        path: "/v1/vaults/{vaultId}/credentials/{credentialId}",
+        tags: ["Vaults"],
+        summary: "Delete a credential",
+        request: { params: credentialId },
+        responses: { 200: json(DeletedResponse, "Deleted") },
+    }, async (c) => {
+        await ownerFor(c);
+        return jsonResponse(200, await c.env.tenant.vault.deleteCredential(c.req.param("vaultId"), c.req.param("credentialId")));
+    });
+}

package/dist/api/openapi.d.ts

@@ -0,0 +1,19 @@
+/**
+ * The Runtime's OpenAPI 3.2 documents, generated from the routes as declared for serving:
+ *
+ * - the Tenant API (`tenantDocument`): every Tenant route, with `/health`, `/ready` and
+ *   `/openapi.json`. Served at `GET /openapi.json`, packed as `@nylorun/runtime/openapi.json`
+ *   and attached to each release.
+ * - the Admin API (`adminDocument`): served at `GET /v1/admin/openapi.json` behind the admin
+ *   key, packed as `@nylorun/runtime/admin-openapi.json`.
+ *
+ * Event streams are `text/event-stream` with an `itemSchema` (OpenAPI 3.2). Nothing here reads
+ * the environment: the same Runtime makes the same document.
+ */
+import { OpenApiGeneratorV32 } from "@asteasolutions/zod-to-openapi";
+type OpenApiDocument = ReturnType<OpenApiGeneratorV32["generateDocument"]>;
+/** The Tenant API's document. */
+export declare function tenantDocument(): OpenApiDocument;
+/** The Admin API's document. */
+export declare function adminDocument(): OpenApiDocument;
+export {};