@nylorun/runtime 0.13.0-beta → 0.14.0-beta

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

@@ -0,0 +1,259 @@
+import { z } from "zod";
+import { newPublishableKey, newPublishableKeyId } from "@nylorun/core/compatibility";
+import { CreatePublishableKeyRequestSchema, CreateTokenRequestSchema, PutAccessPolicyRequestSchema, RevokeSigningKeyRequestSchema, RevokeSubjectRequestSchema, RotateSigningKeysRequestSchema, UpdatePublishableKeyRequestSchema, } from "@nylorun/core/contracts";
+import { AccessPolicyResponse, CreatePublishableKeyRequest, CreateTokenRequest, CreateTokenResponse, Jwks, ListPublishableKeysResponse, PublishableKey, PutAccessPolicyRequest, RevokeSigningKeyRequest, RevokeSubjectRequest, RevokeSubjectResponse, RotateSigningKeysRequest, SigningKeyList, SigningKeyView, UpdatePublishableKeyRequest, } from "../../components.js";
+import { signalSubjectRevoked } from "../../../streams/control.js";
+import { readPolicy, writePolicy } from "../../../tenant/access-policy.js";
+import { currentBasin, endSubjectStreams } from "../../../tenant/session-streams.js";
+import { requireApplication } from "../../../tenant/auth.js";
+import { fail } from "../../../tenant/http.js";
+import { publicJwk, signingKeyView } from "../../../tenant/signing-keys.js";
+import { mintToken } from "../../../tenant/tokens.js";
+import { readJson } from "../body.js";
+import { tenantRoute } from "../define.js";
+import { jsonResponse } from "../respond.js";
+const APPLICATION = { credentials: ["application"], scopes: "never" };
+const json = (schema, description) => ({
+    description,
+    content: { "application/json": { schema } },
+});
+const body = (schema) => ({
+    required: true,
+    content: { "application/json": { schema } },
+});
+const keyId = z.object({ keyId: z.string() });
+export function accessRoutes(api) {
+    tenantRoute(api, {
+        credentials: ["application", "subject", "token", "publishable"],
+        scopes: "any",
+        browser: true,
+        // Public keys: an Action endpoint verifies delivery tokens with them and holds no key.
+        anonymous: true,
+    }, {
+        method: "get",
+        path: "/v1/access/jwks",
+        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.",
+        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"]);
+        });
+        return jsonResponse(200, { keys: rows.map(publicJwk) });
+    });
+    tenantRoute(api, APPLICATION, {
+        method: "post",
+        path: "/v1/tokens",
+        tags: ["Access"],
+        summary: "Mint a subject token",
+        description: "A token for one person and one role of the access policy, for their browser or app to call the Runtime with. At most 15 minutes.",
+        request: { body: body(CreateTokenRequest) },
+        responses: { 200: json(CreateTokenResponse, "The token, its scopes and expiry") },
+    }, async (c) => {
+        requireApplication(c.get("scope"));
+        return jsonResponse(200, await mintToken(c.env.tenant, CreateTokenRequestSchema.parse(await readJson(c.req.raw))));
+    });
+    tenantRoute(api, APPLICATION, {
+        method: "get",
+        path: "/v1/access/policy",
+        tags: ["Access"],
+        summary: "Get the access policy",
+        responses: { 200: json(AccessPolicyResponse, "Roles, the anonymous grant and token lifetime") },
+    }, async (c) => {
+        requireApplication(c.get("scope"));
+        return jsonResponse(200, { policy: await c.env.tenant.store.tx((t) => readPolicy(t)) });
+    });
+    tenantRoute(api, APPLICATION, {
+        method: "put",
+        path: "/v1/access/policy",
+        tags: ["Access"],
+        summary: "Set the access policy",
+        request: { body: body(PutAccessPolicyRequest) },
+        responses: { 200: json(AccessPolicyResponse, "The policy now in force") },
+    }, async (c) => {
+        requireApplication(c.get("scope"));
+        const request = PutAccessPolicyRequestSchema.parse(await readJson(c.req.raw));
+        await c.env.tenant.store.tx((t) => writePolicy(t, request.policy));
+        return jsonResponse(200, { policy: request.policy });
+    });
+    tenantRoute(api, APPLICATION, {
+        method: "get",
+        path: "/v1/access/signing-keys",
+        tags: ["Access"],
+        summary: "List signing keys",
+        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();
+        });
+        return jsonResponse(200, { keys: rows.map(signingKeyView) });
+    });
+    tenantRoute(api, APPLICATION, {
+        method: "post",
+        path: "/v1/access/signing-keys/rotate",
+        tags: ["Access"],
+        summary: "Rotate the signing keys",
+        description: "The standby key signs from now on; the current one still verifies tokens it signed. `force` also ends every outstanding token.",
+        request: { body: body(RotateSigningKeysRequest) },
+        responses: {
+            200: json(SigningKeyList, "The keys after rotation"),
+            409: { description: "The previous key may still verify outstanding tokens" },
+        },
+    }, async (c) => {
+        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));
+        ctx.config.logger.info("signing keys rotated", { force: request.force === true });
+        return jsonResponse(200, { keys: rows.map(signingKeyView) });
+    });
+    tenantRoute(api, APPLICATION, {
+        method: "post",
+        path: "/v1/access/signing-keys/{kid}/revoke",
+        tags: ["Access"],
+        summary: "Revoke a signing key",
+        request: { params: z.object({ kid: z.string() }), body: body(RevokeSigningKeyRequest) },
+        responses: {
+            200: json(SigningKeyView, "The key, revoked"),
+            409: { description: "Rotate before revoking the current key" },
+        },
+    }, async (c) => {
+        requireApplication(c.get("scope"));
+        const ctx = c.env.tenant;
+        RevokeSigningKeyRequestSchema.parse(await readJson(c.req.raw));
+        const row = await ctx.store.tx((t) => ctx.signingKeys.revoke(t, c.req.param("kid")));
+        ctx.config.logger.info("signing key revoked", { kid: row.id });
+        return jsonResponse(200, signingKeyView(row));
+    });
+    tenantRoute(api, APPLICATION, {
+        method: "get",
+        path: "/v1/access/publishable-keys",
+        tags: ["Access"],
+        summary: "List publishable keys",
+        responses: { 200: json(ListPublishableKeysResponse, "The keys, revoked ones included") },
+    }, async (c) => {
+        requireApplication(c.get("scope"));
+        return jsonResponse(200, {
+            keys: (await c.env.tenant.store.tx((t) => t.publishableKeys())).map(publishableKeyView),
+        });
+    });
+    tenantRoute(api, APPLICATION, {
+        method: "post",
+        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.",
+        request: { body: body(CreatePublishableKeyRequest) },
+        responses: {
+            200: json(PublishableKey, "The key"),
+            409: { description: "A key with this name exists" },
+        },
+    }, async (c) => {
+        requireApplication(c.get("scope"));
+        const ctx = c.env.tenant;
+        const request = CreatePublishableKeyRequestSchema.parse(await readJson(c.req.raw));
+        const row = {
+            id: newPublishableKeyId(),
+            key: newPublishableKey(ctx.config.tenantId),
+            name: request.name,
+            originsJson: JSON.stringify(request.origins),
+            createdAt: new Date().toISOString(),
+            revokedAt: null,
+        };
+        await ctx.store.tx(async (t) => {
+            if ((await t.publishableKeys()).some((other) => other.name === request.name))
+                fail(409, `A publishable key named ${request.name} exists`);
+            await t.insertPublishableKey(row);
+        });
+        ctx.config.logger.info("publishable key created", { keyId: row.id });
+        return jsonResponse(200, publishableKeyView(row));
+    });
+    for (const method of ["put", "delete"])
+        tenantRoute(api, APPLICATION, {
+            method,
+            path: "/v1/access/publishable-keys/{keyId}",
+            tags: ["Access"],
+            summary: method === "put" ? "Set a publishable key's origins" : "Revoke a publishable key",
+            request: {
+                params: keyId,
+                ...(method === "put" ? { body: body(UpdatePublishableKeyRequest) } : {}),
+            },
+            responses: {
+                200: json(PublishableKey, method === "put" ? "The key" : "The key, revoked (again: unchanged)"),
+            },
+        }, async (c) => {
+            requireApplication(c.get("scope"));
+            const ctx = c.env.tenant;
+            const id = c.req.param("keyId");
+            const patch = method === "put"
+                ? {
+                    originsJson: JSON.stringify(UpdatePublishableKeyRequestSchema.parse(await readJson(c.req.raw)).origins),
+                }
+                : { revokedAt: new Date().toISOString() };
+            const row = await ctx.store.tx(async (t) => {
+                const existing = (await t.publishableKey(id)) ?? fail(404, "Publishable key not found");
+                // Revoking twice keeps the first time.
+                if (method === "delete" && existing.revokedAt !== null)
+                    return existing;
+                await t.updatePublishableKey(id, patch);
+                return { ...existing, ...patch };
+            });
+            ctx.config.logger.info(method === "put" ? "publishable key updated" : "publishable key revoked", { keyId: row.id });
+            return jsonResponse(200, publishableKeyView(row));
+        });
+    tenantRoute(api, APPLICATION, {
+        method: "post",
+        path: "/v1/access/revocations",
+        tags: ["Access"],
+        summary: "Revoke a subject",
+        description: "Ends every token minted for the subject so far, and their open streams on every process. Turns in progress continue.",
+        request: { body: body(RevokeSubjectRequest) },
+        responses: { 200: json(RevokeSubjectResponse, "The subject's new epoch") },
+    }, async (c) => {
+        requireApplication(c.get("scope"));
+        const request = RevokeSubjectRequestSchema.parse(await readJson(c.req.raw));
+        return jsonResponse(200, await revokeSubject(c.env.tenant, request.subject));
+    });
+}
+/** A publishable key as the API shows it. */
+export function publishableKeyView(row) {
+    return {
+        id: row.id,
+        name: row.name,
+        key: row.key,
+        origins: JSON.parse(row.originsJson),
+        createdAt: row.createdAt,
+        revokedAt: row.revokedAt,
+    };
+}
+/**
+ * Ends every token of `subject` minted so far: bumps its epoch, then ends its open streams
+ * here and, through `tenant/control`, on every other process. Running turns continue.
+ */
+export async function revokeSubject(ctx, subject) {
+    const epoch = await ctx.store.tx(async (t) => {
+        const next = await t.bumpSubjectEpoch(subject, new Date().toISOString());
+        t.afterCommit(async () => {
+            endSubjectStreams(ctx.sessionStreams, subject, next);
+            const streams = ctx.sessionStreams.wiring?.streams;
+            if (streams)
+                await signalSubjectRevoked(streams, currentBasin(ctx), subject, next).catch((error) => ctx.config.logger.warn("subject revocation signal failed", {
+                    message: error instanceof Error ? error.message : String(error),
+                }));
+        });
+        return next;
+    });
+    ctx.config.logger.info("subject revoked", { epoch });
+    return { subject, epoch };
+}

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

@@ -0,0 +1,8 @@
+/**
+ * Session commands, and the callbacks an Action endpoint makes about the Action it was
+ * delivered: heartbeats and sandbox tools, with the Action's delivery token (Action endpoints).
+ * The background result is in `endpoints.ts`.
+ */
+import type { OpenAPIHono } from "@hono/zod-openapi";
+import type { TenantEnv } from "../app.js";
+export declare function actionRoutes(api: OpenAPIHono<TenantEnv>): void;

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

@@ -0,0 +1,76 @@
+import { z } from "zod";
+import { SessionCommandSchema } from "@nylorun/core/contracts";
+import { AcceptedResponse, DeliveryHeartbeatResponse, SandboxToolOutcome, SessionCommand, } from "../../components.js";
+import { actionSandboxTool } from "../../../tenant/actions.js";
+import { command } from "../../../tenant/commands.js";
+import { deliveryHeartbeat } from "../../../tenant/delivery.js";
+import { fail } from "../../../tenant/http.js";
+import { readJson } from "../body.js";
+import { tenantRoute } from "../define.js";
+import { jsonResponse } from "../respond.js";
+/** An Action's callbacks: only the delivery token of its current delivery. */
+const CALLBACK = { credentials: ["delivery"], scopes: "never" };
+const json = (schema, description) => ({
+    description,
+    content: { "application/json": { schema } },
+});
+const body = (schema) => ({
+    required: true,
+    content: { "application/json": { schema } },
+});
+const actionId = z.object({ actionId: z.string() });
+const SANDBOX_TOOLS = ["bash", "read", "write", "edit", "grep", "glob"];
+function deliveryOf(scope) {
+    if (scope.kind !== "delivery")
+        return fail(403, "A delivery token is required");
+    return scope;
+}
+export function actionRoutes(api) {
+    tenantRoute(api, CALLBACK, {
+        method: "post",
+        path: "/v1/actions/{actionId}/sandbox/{tool}",
+        tags: ["Action endpoints"],
+        summary: "Run a sandbox tool for an Action being delivered",
+        description: "Called by the Action endpoint with the Action's delivery token. The body is the tool's input.",
+        request: {
+            params: actionId.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: "The delivery was cancelled, lost or sent again" },
+        },
+    }, async (c) => jsonResponse(200, await actionSandboxTool(c.env.tenant, deliveryOf(c.get("scope")), c.req.param("actionId"), c.req.param("tool"), () => readJson(c.req.raw), c.req.raw.signal)));
+    tenantRoute(api, CALLBACK, {
+        method: "post",
+        path: "/v1/actions/{actionId}/heartbeat",
+        tags: ["Action endpoints"],
+        summary: "Keep a background delivery alive",
+        description: "Called by an Action endpoint that answered a delivery with 202: extends the delivery by a " +
+            "lease and returns a fresh delivery token.",
+        request: { params: actionId },
+        responses: {
+            200: json(DeliveryHeartbeatResponse, "The delivery's new deadline, and a fresh token"),
+            409: { description: "The delivery was cancelled, lost or sent again" },
+        },
+    }, async (c) => jsonResponse(200, await deliveryHeartbeat(c.env.tenant, deliveryOf(c.get("scope")), c.req.param("actionId"))));
+    tenantRoute(api, {
+        credentials: ["application", "subject", "token"],
+        scopes: ["sessions:own"],
+        browser: true,
+    }, {
+        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: z.object({ sessionId: z.string() }),
+            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"))));
+}

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

@@ -0,0 +1,7 @@
+/**
+ * Action endpoints: where the Runtime delivers each agent's Actions (design: Action endpoints
+ * §4.2). Registered, listed and removed with the application key; no subject reaches them.
+ */
+import type { OpenAPIHono } from "@hono/zod-openapi";
+import type { TenantEnv } from "../app.js";
+export declare function endpointRoutes(api: OpenAPIHono<TenantEnv>): void;

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

@@ -0,0 +1,100 @@
+import { z } from "zod";
+import { PutEndpointsRequestSchema } from "@nylorun/core/contracts";
+import { DeleteEndpointResponse, EndpointPingResponse, ListEndpointsResponse, PutEndpointsRequest, } from "../../components.js";
+import { ActionOutcomeSchema } from "@nylorun/core/contracts";
+import { ActionOutcome, ActionResultReceipt } from "../../components.js";
+import { deliveryResult, pingEndpoint } from "../../../tenant/delivery.js";
+import { requireApplication } from "../../../tenant/auth.js";
+import { fail } from "../../../tenant/http.js";
+import { deleteEndpoint, listEndpoints, putEndpoints, } from "../../../tenant/endpoints.js";
+import { readJson } from "../body.js";
+import { tenantRoute } from "../define.js";
+import { jsonResponse } from "../respond.js";
+const APPLICATION = { credentials: ["application"], scopes: "never" };
+const json = (schema, description) => ({
+    description,
+    content: { "application/json": { schema } },
+});
+export function endpointRoutes(api) {
+    tenantRoute(api, APPLICATION, {
+        method: "get",
+        path: "/v1/endpoints",
+        tags: ["Action endpoints"],
+        summary: "List Action endpoints",
+        description: "Each agent's Action endpoint, with what recent deliveries say about it.",
+        responses: { 200: json(ListEndpointsResponse, "The endpoints") },
+    }, async (c) => {
+        requireApplication(c.get("scope"));
+        return jsonResponse(200, await listEndpoints(c.env.tenant));
+    });
+    tenantRoute(api, APPLICATION, {
+        method: "put",
+        path: "/v1/endpoints",
+        tags: ["Action endpoints"],
+        summary: "Register Action endpoints",
+        description: "Points the Runtime at the URL that runs each agent's Actions. A new URL starts with no " +
+            "health.",
+        request: {
+            body: { required: true, content: { "application/json": { schema: PutEndpointsRequest } } },
+        },
+        responses: { 200: json(ListEndpointsResponse, "The registered endpoints") },
+    }, async (c) => {
+        const principalId = requireApplication(c.get("scope"));
+        return jsonResponse(200, await putEndpoints(c.env.tenant, principalId, PutEndpointsRequestSchema.parse(await readJson(c.req.raw))));
+    });
+    tenantRoute(api, APPLICATION, {
+        method: "delete",
+        path: "/v1/endpoints/{agentId}",
+        tags: ["Action endpoints"],
+        summary: "Remove an agent's Action endpoint",
+        description: "The agent's pending Actions wait until an endpoint is registered again.",
+        request: { params: z.object({ agentId: z.string() }) },
+        responses: {
+            200: json(DeleteEndpointResponse, "The endpoint was removed"),
+            404: { description: "The agent has no endpoint" },
+        },
+    }, async (c) => {
+        requireApplication(c.get("scope"));
+        return jsonResponse(200, await deleteEndpoint(c.env.tenant, c.req.param("agentId")));
+    });
+    tenantRoute(api, APPLICATION, {
+        method: "post",
+        path: "/v1/endpoints/{agentId}/ping",
+        tags: ["Action endpoints"],
+        summary: "Ping an agent's Action endpoint",
+        description: "Sends a signed ping through the endpoint and records what it answers it serves. A " +
+            "wrong URL, a tunnel that is down or a handler that does not serve the agent answers 502.",
+        request: { params: z.object({ agentId: z.string() }) },
+        responses: {
+            200: json(EndpointPingResponse, "What the endpoint serves"),
+            404: { description: "The agent has no endpoint" },
+            502: { description: "The endpoint did not answer the ping" },
+        },
+    }, async (c) => {
+        requireApplication(c.get("scope"));
+        return jsonResponse(200, await pingEndpoint(c.env.tenant, c.req.param("agentId")));
+    });
+    tenantRoute(api, { credentials: ["delivery"], scopes: "never" }, {
+        method: "post",
+        path: "/v1/actions/{actionId}/result",
+        tags: ["Action endpoints"],
+        summary: "Post the outcome of an Action answered with 202",
+        description: "Called by an Action endpoint with the Action's delivery token after it answered the " +
+            "delivery with 202. The same result again returns the first receipt.",
+        request: {
+            params: z.object({ actionId: z.string() }),
+            body: { required: true, content: { "application/json": { schema: ActionOutcome } } },
+        },
+        responses: {
+            200: json(ActionResultReceipt, "The outcome was recorded"),
+            409: {
+                description: "The delivery was cancelled, lost or sent again, or the Action has another result",
+            },
+        },
+    }, async (c) => {
+        const scope = c.get("scope");
+        if (scope.kind !== "delivery")
+            return fail(403, "A delivery token is required");
+        return jsonResponse(200, await deliveryResult(c.env.tenant, scope, c.req.param("actionId"), ActionOutcomeSchema.parse(await readJson(c.req.raw))));
+    });
+}

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;
+        }
+    });
+}