@nylorun/runtime 0.13.0-beta → 0.15.0-beta

package/dist/api/http/define.js

@@ -0,0 +1,122 @@
+import { z } from "zod";
+import { PROTOCOL_VERSION } from "@nylorun/core/compatibility";
+import { authenticate, requireScopes } from "../../tenant/auth.js";
+import { identifyClient } from "../../tenant/browser.js";
+import { fail } from "../../tenant/http.js";
+import { ProtocolRejected, Rejected } from "../components.js";
+const SCHEMES = {
+    application: "applicationKey",
+    subject: "applicationKey",
+    token: "subjectToken",
+    publishable: "publishableKey",
+    delivery: "deliveryToken",
+};
+const rejected = (description) => ({
+    description,
+    content: { "application/json": { schema: Rejected } },
+});
+/** The route's path segments, decoded, as the Tenant's checks read them. */
+export function pathSegments(incoming) {
+    return new URL(incoming.url ?? "/", "http://runtime").pathname
+        .split("/")
+        .filter(Boolean)
+        .map((segment) => {
+        try {
+            return decodeURIComponent(segment);
+        }
+        catch {
+            return fail(400, "Malformed path");
+        }
+    });
+}
+/** Who is calling: the browser client and the bearer, as every Tenant request checks them. */
+export async function authenticateCaller(c, 
+/** The route serves public data (`RouteAccess.anonymous`): no credential is needed. */
+anonymous = false) {
+    const { tenant, incoming, outgoing } = c.env;
+    // The client app first: a browser's origin is checked, and CORS headers set, before the
+    // bearer is looked at, so every answer from here on is readable by an allowed page.
+    const client = await identifyClient(tenant, incoming, outgoing);
+    if (anonymous && !client && incoming.headers.authorization === undefined)
+        return { kind: "anonymous" };
+    return await authenticate(tenant, incoming, client);
+}
+const declared = [];
+/** The declared route `method path` is, if any. `{param}` segments match any one segment. */
+export function declaredRoute(method, segments) {
+    return declared.find((route) => route.method === method.toUpperCase() &&
+        route.segments.length === segments.length &&
+        route.segments.every((segment, index) => segment === segments[index] ||
+            (segment.startsWith("{") && segments[index] !== "")))?.access;
+}
+function authenticated(access) {
+    return async (c, next) => {
+        const scope = await authenticateCaller(c, access.anonymous === true);
+        requireScopes(scope, access.scopes);
+        if (scope.kind === "publishable" && !access.credentials.includes("publishable"))
+            fail(403, "A publishable key alone reaches only the agent list", {
+                code: "scope_required",
+            });
+        // Handlers tell callers apart by kind, and a delivery token is none of theirs: only the
+        // routes that list it may see one.
+        if (scope.kind === "delivery" && !access.credentials.includes("delivery"))
+            fail(403, "A delivery token reaches only its Action's callbacks");
+        c.set("scope", scope);
+        await next();
+    };
+}
+export function tenantRoute(api, access, route, handler) {
+    const takes = (credential) => access.credentials.includes(credential);
+    const schemes = [...new Set(access.credentials.map((credential) => SCHEMES[credential]))];
+    const headers = z.object({
+        "Nylorun-Protocol": z.string().meta({ description: `The protocol version, \`${PROTOCOL_VERSION}\`` }),
+        ...(takes("subject")
+            ? {
+                "Nylorun-Subject": z
+                    .string()
+                    .optional()
+                    .meta({ description: "The person an application key acts for" }),
+                "Nylorun-Scopes": z
+                    .string()
+                    .optional()
+                    .meta({ description: "The subject's space-separated scopes; required with a subject" }),
+            }
+            : {}),
+        ...(takes("publishable")
+            ? {
+                "Nylorun-Key": z
+                    .string()
+                    .optional()
+                    .meta({ description: "A publishable key, from a browser page on an allowed origin" }),
+            }
+            : {}),
+    });
+    api.openAPIRegistry.registerPath({
+        ...route,
+        // `{}`: no credential needed (OpenAPI's optional security).
+        security: [
+            ...schemes.map((scheme) => ({ [scheme]: [] })),
+            ...(access.anonymous ? [{}] : []),
+        ],
+        request: { ...route.request, headers },
+        responses: {
+            400: rejected("Invalid headers, path, body or cursor"),
+            ...(takes("token") ? { 401: rejected("The subject token expired or was revoked (`token_expired`)") } : {}),
+            403: rejected("Not allowed for this credential, subject scope or origin"),
+            404: rejected("Not found, or a credential the Tenant does not know (`not_found`)"),
+            426: { description: "`Nylorun-Protocol` missing or unsupported", content: { "application/json": { schema: ProtocolRejected } } },
+            ...(takes("token") ? { 429: rejected("The subject's turn limits are reached (`limit_exceeded`)") } : {}),
+            503: rejected("The Tenant's storage or streams are unavailable"),
+            ...route.responses,
+        },
+        "x-nylorun-credentials": access.credentials,
+        "x-nylorun-scopes": access.scopes,
+        "x-nylorun-browser": access.browser === true,
+    });
+    declared.push({
+        method: route.method.toUpperCase(),
+        segments: route.path.split("/").filter(Boolean),
+        access,
+    });
+    api.on(route.method.toUpperCase(), route.path.replaceAll(/\/{(.+?)}/g, "/:$1"), authenticated(access), handler);
+}

package/dist/api/http/respond.d.ts

@@ -0,0 +1,9 @@
+/** A JSON answer. CORS headers a browser needs are already on the Node response. */
+export declare function jsonResponse(status: number, body: unknown, headers?: Readonly<Record<string, string>>): Response;
+export interface Rejection {
+    readonly status: number;
+    readonly body: unknown;
+    readonly headers: Readonly<Record<string, string>>;
+}
+/** What a Tenant route that threw `error` answers. */
+export declare function rejectionOf(error: unknown): Rejection;

package/dist/api/http/respond.js

@@ -0,0 +1,44 @@
+/**
+ * How the Tenant API answers: JSON with an explicit length, and the one mapping from what a
+ * route throws to the rejection a client sees. The Hono routes and the router they replace
+ * (`routes.ts`) both answer through here, so a route answers the same wherever it runs.
+ */
+import { SandboxRouteError } from "../../core/sandbox-routes.js";
+import { HttpError, OpaqueAuthError } from "../../tenant/http.js";
+import { VaultError } from "../../vault/error.js";
+/** A JSON answer. CORS headers a browser needs are already on the Node response. */
+export function jsonResponse(status, body, headers = {}) {
+    const payload = JSON.stringify(body);
+    return new Response(payload, {
+        status,
+        headers: {
+            ...headers,
+            "content-type": "application/json",
+            "content-length": String(Buffer.byteLength(payload)),
+        },
+    });
+}
+/** What a Tenant route that threw `error` answers. */
+export function rejectionOf(error) {
+    if (error instanceof OpaqueAuthError)
+        return { status: error.status, body: error.body, headers: {} };
+    const status = error instanceof HttpError ||
+        error instanceof VaultError ||
+        error instanceof SandboxRouteError
+        ? error.status
+        : error?.name === "ZodError" ||
+            error?.message === "Invalid cursor"
+            ? 400
+            : 500;
+    const rejection = error instanceof HttpError ? error.rejection : {};
+    return {
+        status,
+        body: {
+            status: "rejected",
+            code: status === 500 ? "internal_error" : (rejection.code ?? "request_rejected"),
+            message: status === 500 ? "Runtime request failed" : error.message,
+            ...(rejection.details === undefined ? {} : { details: rejection.details }),
+        },
+        headers: error instanceof HttpError ? error.headers : {},
+    };
+}

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

@@ -0,0 +1,24 @@
+/**
+ * Access management (Host feature `subject-tokens`), for the application key only: subject
+ * tokens, the access policy, signing keys, publishable keys and subject revocation; and the
+ * public keys, for any caller that reached the Tenant.
+ *
+ * Subjects travel in bodies, not paths, because they may be email addresses and request paths
+ * are logged.
+ */
+import type { OpenAPIHono } from "@hono/zod-openapi";
+import type { PublishableKey as PublishableKeyBody } from "@nylorun/core/contracts";
+import type { PublishableKeyRow } from "../../../store/types.js";
+import type { TenantContext } from "../../../tenant/context.js";
+import type { TenantEnv } from "../app.js";
+export declare function accessRoutes(api: OpenAPIHono<TenantEnv>): void;
+/** A publishable key as the API shows it. */
+export declare function publishableKeyView(row: PublishableKeyRow): PublishableKeyBody;
+/**
+ * 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 declare function revokeSubject(ctx: TenantContext, subject: string): Promise<{
+    subject: string;
+    epoch: number;
+}>;

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

@@ -0,0 +1,266 @@
+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.",
+        responses: { 200: json(Jwks, "The public keys") },
+    }, async (c) => {
+        // Anonymous: reads the public keys. Only when the current or standby key is missing does
+        // it ask the keys service to create it, so a verifier never caches a set without them.
+        const ctx = c.env.tenant;
+        const read = () => ctx.store.tx((t) => t.signingKeys(["standby", "current", "previous"]));
+        let rows = await read();
+        if (!complete(rows)) {
+            await ctx.keys.ensureSigningKeys();
+            rows = await read();
+        }
+        return jsonResponse(200, { keys: rows.map(publicJwk) });
+    });
+    tenantRoute(api, APPLICATION, {
+        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 ctx = c.env.tenant;
+        const read = () => ctx.store.tx((t) => t.signingKeys());
+        let rows = await read();
+        if (!complete(rows)) {
+            await ctx.keys.ensureSigningKeys();
+            rows = await read();
+        }
+        return jsonResponse(200, { keys: rows.map(signingKeyView) });
+    });
+    tenantRoute(api, APPLICATION, {
+        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 maxTtlSeconds = await ctx.store.tx(async (t) => (await readPolicy(t)).tokens.maxTtlSeconds);
+        const keys = await ctx.keys.rotateSigningKeys({ maxTtlSeconds, force: request.force === true });
+        ctx.config.logger.info("signing keys rotated", { force: request.force === true });
+        return jsonResponse(200, { keys });
+    });
+    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 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 };
+}
+/** True when the Tenant has a current and a standby signing key. */
+function complete(rows) {
+    return rows.some((row) => row.state === "current") && rows.some((row) => row.state === "standby");
+}

package/dist/api/http/routes/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))));
+    });
+}