@nylorun/runtime 0.16.0-beta → 0.19.0-beta

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.d.ts

@@ -1,8 +1,8 @@
 /**
  * Sandboxes as a resource (`/v1/sandboxes/**`, Host feature `sandboxes`): create or find one by
  * id, read it, list them by label, read its lifecycle stream, and delete it. Ids may hold `/`,
- * sent percent-encoded as one path segment (`team-a%2Fproj-42`). A subject token reaches only
- * the ids its `sbx` grants match, and changes them only with `sandboxes:write`.
+ * sent percent-encoded as one path segment (`team-a%2Fproj-42`). A token caller reaches only
+ * the ids its sandbox grants match, and changes them only with `sandboxes:write`.
  */
 import type { OpenAPIHono } from "@hono/zod-openapi";
 import type { TenantEnv } from "../app.js";

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

@@ -1,22 +1,21 @@
 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 = {
     credentials: ["application", "subject", "token"],
     scopes: ["sessions:own", "sandboxes:write"],
-    browser: true,
 };
 /** Creating or deleting one. */
 const WRITE = {
     credentials: ["application", "subject", "token"],
     scopes: ["sandboxes:write"],
-    browser: true,
 };
 const json = (schema, description) => ({
     description,
@@ -50,17 +49,19 @@ export function sandboxRoutes(api) {
         path: "/v1/sandboxes",
         tags: ["Sandboxes"],
         summary: "List sandboxes",
-        description: "Every sandbox with all the labels asked for. A subject token sees only the sandboxes its grants reach.",
+        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,22 +1,22 @@
 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 { readHistory, requestCursor, streamSessionEvents } from "../../../tenant/session-streams.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"],
     scopes: ["sessions:own"],
-    browser: true,
 };
 const json = (schema, description) => ({
     description,
@@ -46,24 +46,33 @@ 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", "publishable"],
+        credentials: ["application", "subject", "token"],
         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.",
+        description: "With an application key, every definition, manifest included. With a trusted issuer's token, 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));
@@ -84,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, {
@@ -107,7 +118,7 @@ export function sessionRoutes(api) {
         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" });
+            fail(403, "A token caller cannot set session info", { code: "scope_required" });
         const grants = sandboxGrantsOf(scope);
         const session = await putSession(ctx, c.req.param("sessionId"), request, accessOf(scope), grants === undefined ? {} : { sandboxGrants: grants });
         return jsonResponse(200, await ctx.store.tx((t) => sessionView(t, session)));
@@ -133,26 +144,28 @@ 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",
         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.",
+        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 trusted issuer's token's stream ends with `event: nylorun.closed` when the token expires. A `: keepalive` comment every 15 seconds.",
         request: { params: sessionId, query: resume },
         responses: {
             200: {
@@ -170,9 +183,7 @@ export function sessionRoutes(api) {
         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);
+        await streamSessionEvents(ctx, incoming, outgoing, id, cursor, streamHolderOf(scope));
         return RESPONSE_ALREADY_SENT;
     });
     tenantRoute(api, { credentials: ["application"], scopes: "never" }, {

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,8 +1,18 @@
 /**
- * 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.
+ * 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: 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";
+/** Where the authorization server sends the browser back. */
+export declare const OAUTH_CALLBACK_PATH = "/v1/oauth/callback";
 export declare function vaultRoutes(api: OpenAPIHono<TenantEnv>): void;