@nylorun/runtime 0.26.0-beta → 0.28.0-beta

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

@@ -16,17 +16,17 @@ export function mcpRoutes(api) {
         path: "/v1/tenant/mcp/preview",
         tags: ["MCP servers"],
         summary: "Preview an MCP server's tools",
-        description: "Connects to the remote MCP server at `url` with the credential for that URL in the vault of `environmentId`, if given (its headers and `via`; never an identity header), under the Host's address policy, lists its tools within 15 s and closes the connection. It never calls a tool. Each tool comes with the name the model would call it (`modelName`, made with `name`), its annotations and its input schema's size. A server that answers `401` is `authRequired`, with its RFC 9728 protected-resource metadata when it publishes any: it needs a person's sign-in, so reach it through a gateway (`via`), or with a key. No credential value is in the answer.",
+        description: "Connects to the remote MCP server at `url` with the credential for that URL in the vault of the Agent `agentId`, if given (its headers and `via`; never an identity header), under the Host's address policy, lists its tools within 15 s and closes the connection. It never calls a tool. Each tool comes with the name the model would call it (`modelName`, made with `name`), its annotations and its input schema's size. A server that answers `401` is `authRequired`, with its RFC 9728 protected-resource metadata when it publishes any: it needs a person's sign-in, so reach it through a gateway (`via`), or with a key. No credential value is in the answer.",
         request: {
             body: { required: true, content: { "application/json": { schema: McpPreviewRequest } } },
         },
         responses: {
             200: json(McpPreview, "The server's tools, or that it needs a credential (`authRequired`)"),
-            409: json(Rejected, "The Environment's credential for the URL cannot be used"),
+            409: json(Rejected, "The Agent's credential for the URL cannot be used"),
             502: json(Rejected, "The server could not be listed (`mcp_preview_failed`): `details.failure` is the code a tool call would have failed with, such as `mcp.unreachable` for an address the Host refuses"),
         },
     }, async (c) => {
-        const request = McpPreviewRequestSchema.parse(await readJson(c.req.raw));
+        const request = McpPreviewRequestSchema.parse(await readJson(c));
         return jsonResponse(200, await c.env.tenant.keys.previewMcp(request));
     });
 }

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

@@ -1,7 +1,7 @@
 /**
  * `GET /v1/me` (Host feature `trusted-issuers`): who the Runtime takes the caller to be, for any
  * credential that acts on the Tenant. It shows what a trusted issuer's token renders to (its
- * subject, scopes, agents and sandbox grants), so an operator can check an identity file, and
+ * subject, scopes and Agent grants), so an operator can check an identity file, and
  * Studio can check a forwarded token for the `studio` scope.
  */
 import type { OpenAPIHono } from "@hono/zod-openapi";

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

@@ -19,7 +19,6 @@ export function describeCaller(scope) {
                 subject: scope.subject,
                 scopes: ordered(scope.scopes),
                 agents: scope.agents === "*" ? "*" : [...scope.agents].sort(),
-                environments: [...(scope.environments ?? [])],
                 via: `issuer:${scope.issuer}`,
             };
         case "management":
@@ -34,7 +33,7 @@ export function meRoutes(api) {
         path: "/v1/me",
         tags: ["Access"],
         summary: "Get who the caller is",
-        description: "The subject, scopes, agents and sandbox grants of the credential that sends it: an " +
+        description: "The subject, scopes and Agent grants of the credential that sends it: an " +
             "application key (alone or acting for a subject), a management key " +
             "(`via: management:<principalId>`, no scopes, no agents), or a trusted issuer's token " +
             "(`via: issuer:<name>`).",

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

@@ -0,0 +1,9 @@
+/**
+ * An Agent's memories (track T5, D72), shaped like Anthropic's memory stores: list, read, write
+ * whole, delete, and the versions every change leaves. A memory's path is relative to
+ * `/memories`, with `/` percent-encoded (`conventions%2Frelease.md`), as an Agent id is. The
+ * caller reaches an Agent's memories as it reaches the Agent; writes are `agents:write`.
+ */
+import type { OpenAPIHono } from "@hono/zod-openapi";
+import type { TenantEnv } from "../app.js";
+export declare function memoryRoutes(api: OpenAPIHono<TenantEnv>): void;

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

@@ -0,0 +1,152 @@
+import { z } from "zod";
+import { isAgentId, PutMemoryRequestSchema } from "@nylorun/core/contracts";
+import { MemoryList, MemoryVersionDetail, MemoryVersionPage, MemoryView, PutMemoryRequest } from "../../components.js";
+import { assertReaches } from "../../../tenant/agents.js";
+import { fail } from "../../../tenant/http.js";
+import { deleteMemoryPath, listMemories, listMemoryVersions, putMemoryContent, readMemory, readMemoryVersion, } from "../../../tenant/memories.js";
+import { readJson } from "../body.js";
+import { tenantRoute } from "../define.js";
+import { pageQuery, pageSize, parseQuery } from "./reads.js";
+import { jsonResponse } from "../respond.js";
+const READ = {
+    credentials: ["application", "subject", "token"],
+    scopes: ["sessions:own", "agents:read", "agents:write"],
+};
+const WRITE = {
+    credentials: ["application", "subject", "token"],
+    scopes: ["agents:write"],
+};
+const json = (schema, description) => ({
+    description,
+    content: { "application/json": { schema } },
+});
+const agentId = z.object({
+    agentId: z.string().meta({ description: "The Agent id, percent-encoded" }),
+});
+const memoryPath = agentId.extend({
+    path: z.string().meta({
+        description: "The memory's path under `/memories`, percent-encoded: `conventions%2Frelease.md` is `/memories/conventions/release.md`",
+    }),
+});
+function idOf(value) {
+    if (!isAgentId(value))
+        return fail(400, "An Agent id is up to 200 characters: /-separated segments of letters, digits, '.', '_' and '-'");
+    return value;
+}
+export function memoryRoutes(api) {
+    tenantRoute(api, READ, {
+        method: "get",
+        path: "/v1/agents/{agentId}/memories",
+        tags: ["Memory"],
+        summary: "List an Agent's memories",
+        description: "Its memories by path, each with its size, `content_sha256`, frontmatter `description` and version. `pathPrefix` keeps one folder's (`conventions` for `/memories/conventions/…`).",
+        request: {
+            params: agentId,
+            query: pageQuery.extend({
+                pathPrefix: z.string().optional().meta({ description: "Only the memories in this folder, relative to `/memories`" }),
+            }),
+        },
+        responses: { 200: json(MemoryList, "A page of memories") },
+    }, async (c) => {
+        const id = idOf(c.req.param("agentId"));
+        assertReaches(c.get("scope"), id);
+        const pathPrefix = c.req.query("pathPrefix");
+        const { limit, cursor } = parseQuery(pageQuery, { limit: c.req.query("limit"), cursor: c.req.query("cursor") });
+        return jsonResponse(200, await listMemories(c.env.tenant, id, {
+            ...(pathPrefix ? { pathPrefix } : {}),
+            ...(cursor ? { cursor } : {}),
+            limit: await pageSize(c.env.tenant, limit, { fallback: 100 }),
+        }));
+    });
+    tenantRoute(api, READ, {
+        method: "get",
+        path: "/v1/agents/{agentId}/memories/{path}",
+        tags: ["Memory"],
+        summary: "Read a memory",
+        description: "The memory's content, with its size, `content_sha256`, description and version.",
+        request: { params: memoryPath },
+        responses: { 200: json(MemoryView, "The memory"), 404: { description: "No memory has this path" } },
+    }, async (c) => {
+        const id = idOf(c.req.param("agentId"));
+        assertReaches(c.get("scope"), id);
+        return jsonResponse(200, await readMemory(c.env.tenant, id, c.req.param("path") ?? ""));
+    });
+    tenantRoute(api, WRITE, {
+        method: "put",
+        path: "/v1/agents/{agentId}/memories/{path}",
+        tags: ["Memory"],
+        summary: "Write a memory",
+        description: "Creates the memory or replaces its content, as the `memory` tool's `create` does, and records a version with the caller as its actor. This is how an app seeds an Agent's memory. With `contentSha256` the write applies only while the memory still has that content (`\"\"`: only while no memory has the path); otherwise `409 memory_conflict` with the current memory. The path ends in `.md`; the Runtime limits `memoryBytes` (`413`) and `memoriesPerAgent` (`409 limit_exceeded`) hold.",
+        request: {
+            params: memoryPath,
+            body: { required: true, content: { "application/json": { schema: PutMemoryRequest } } },
+        },
+        responses: {
+            200: json(MemoryView, "The memory as written"),
+            409: { description: "The `contentSha256` precondition no longer holds, or a folder has this path (`memory_conflict`)" },
+            413: { description: "Larger than the Runtime limit `memoryBytes`" },
+        },
+    }, async (c) => {
+        const id = idOf(c.req.param("agentId"));
+        const scope = c.get("scope");
+        assertReaches(scope, id);
+        const body = PutMemoryRequestSchema.safeParse(await readJson(c));
+        if (!body.success)
+            fail(400, "The body is { content, contentSha256? }", { code: "invalid_request" });
+        return jsonResponse(200, await putMemoryContent(c.env.tenant, id, c.req.param("path") ?? "", body.data, scope));
+    });
+    tenantRoute(api, WRITE, {
+        method: "delete",
+        path: "/v1/agents/{agentId}/memories/{path}",
+        tags: ["Memory"],
+        summary: "Delete a memory or a folder",
+        description: "Deletes the memory, or every memory in the folder the path names, each with a version that records the delete. Versions stay with the Agent.",
+        request: { params: memoryPath },
+        responses: {
+            200: json(z.object({ path: z.string(), deleted: z.number().int().nonnegative() }).strict(), "What was deleted"),
+            404: { description: "No memory or folder has this path" },
+        },
+    }, async (c) => {
+        const id = idOf(c.req.param("agentId"));
+        const scope = c.get("scope");
+        assertReaches(scope, id);
+        return jsonResponse(200, await deleteMemoryPath(c.env.tenant, id, c.req.param("path") ?? "", scope));
+    });
+    tenantRoute(api, READ, {
+        method: "get",
+        path: "/v1/agents/{agentId}/memory_versions",
+        tags: ["Memory"],
+        summary: "List an Agent's memory versions",
+        description: "Every change to its memories, newest first: the operation, the path (a rename's names its old one), and who made it: `agent:<manifest>@<version>` with the session, turn and trigger run of a turn's write, or the API caller. `path` keeps one memory's.",
+        request: {
+            params: agentId,
+            query: pageQuery.extend({
+                path: z.string().optional().meta({ description: "Only this memory's versions, relative to `/memories`" }),
+            }),
+        },
+        responses: { 200: json(MemoryVersionPage, "A page of versions") },
+    }, async (c) => {
+        const id = idOf(c.req.param("agentId"));
+        assertReaches(c.get("scope"), id);
+        const path = c.req.query("path");
+        const { limit, cursor } = parseQuery(pageQuery, { limit: c.req.query("limit"), cursor: c.req.query("cursor") });
+        return jsonResponse(200, await listMemoryVersions(c.env.tenant, id, {
+            ...(path ? { path } : {}),
+            ...(cursor ? { cursor } : {}),
+            limit: await pageSize(c.env.tenant, limit, { fallback: 50 }),
+        }));
+    });
+    tenantRoute(api, READ, {
+        method: "get",
+        path: "/v1/agents/{agentId}/memory_versions/{versionId}",
+        tags: ["Memory"],
+        summary: "Read a memory version",
+        description: "One version with the content it left (`null` for a delete). To roll a memory back, write this content again.",
+        request: { params: agentId.extend({ versionId: z.string().meta({ description: "The version's id (`mv_…`)" }) }) },
+        responses: { 200: json(MemoryVersionDetail, "The version"), 404: { description: "No such version" } },
+    }, async (c) => {
+        const id = idOf(c.req.param("agentId"));
+        assertReaches(c.get("scope"), id);
+        return jsonResponse(200, await readMemoryVersion(c.env.tenant, id, c.req.param("versionId") ?? ""));
+    });
+}

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

@@ -6,6 +6,15 @@ export declare const pageQuery: z.ZodObject<{
     limit: z.ZodOptional<z.ZodCoercedNumber<unknown>>;
     cursor: z.ZodOptional<z.ZodString>;
 }, z.core.$strip>;
+/**
+ * The size of a page: `asked`, or, when the query names none, `fallback`, each within the Tenant's
+ * Runtime limit `name` (read for each request): a page asked larger holds that many, and its
+ * cursor reads on.
+ */
+export declare function pageSize(ctx: TenantEnv["Bindings"]["tenant"], asked: number | undefined, options?: {
+    fallback?: number;
+    name?: "pageItems" | "exportPageItems";
+}): Promise<number>;
 export declare const sessionPageQuery: z.ZodObject<{
     limit: z.ZodOptional<z.ZodCoercedNumber<unknown>>;
     cursor: z.ZodOptional<z.ZodString>;
@@ -21,7 +30,7 @@ export declare const sessionPageQuery: z.ZodObject<{
         uncertain: "uncertain";
         waiting: "waiting";
     }>>;
-    environmentId: z.ZodOptional<z.ZodString>;
+    manifest: z.ZodOptional<z.ZodString>;
     ownerUserId: z.ZodOptional<z.ZodString>;
 }, z.core.$strict>;
 export declare function parseQuery<T>(schema: z.ZodType<T>, query: unknown): T;
@@ -33,119 +42,9 @@ export declare function sessionPage(ctx: TenantEnv["Bindings"]["tenant"], scope:
         status: "cancelled" | "completed" | "failed" | "idle" | "paused" | "runnable" | "running" | "uncertain" | "waiting";
         activeTurnId: string | null;
         lastTurnId: string | null;
-        environmentId: string | null;
         createdAt: string | null;
         lastEventAt: string | null;
     }[];
     nextCursor: string | null;
 }>;
-export declare function environmentPage(ctx: TenantEnv["Bindings"]["tenant"], scope: TenantEnv["Variables"]["scope"], query: Record<string, string>, labels: Record<string, string>): Promise<{
-    environments: {
-        id: string;
-        kind: "none" | "pod" | "virtual";
-        labels: Record<string, string>;
-        manifest: {
-            image?: string | undefined;
-            resources?: {
-                cpus: number;
-                memory: string;
-            } | undefined;
-            storage?: string | undefined;
-            network?: {
-                allowedHosts: string[];
-            } | undefined;
-            harness: string;
-            lifecycle: {
-                idle?: string | undefined;
-                deleteAfter?: string | undefined;
-            };
-            setup?: {
-                command: string;
-                cwd?: string | undefined;
-                timeout?: string | undefined;
-            }[] | undefined;
-            files?: ({
-                artifactId: string;
-                version: number;
-                path: string;
-            } | {
-                path: string;
-                files: Record<string, string>;
-            })[] | undefined;
-            secrets?: Record<string, {
-                required?: boolean | undefined;
-                description?: string | undefined;
-                type: "environment_secret";
-                allowedHosts: string[];
-                inject?: {
-                    header: string;
-                    format: string;
-                } | undefined;
-            } | {
-                required?: boolean | undefined;
-                description?: string | undefined;
-                type: "environment_variable";
-            } | {
-                via?: string | undefined;
-                identity?: {
-                    header: string;
-                } | undefined;
-                required?: boolean | undefined;
-                description?: string | undefined;
-                type: "bearer";
-                url: string;
-            } | {
-                via?: string | undefined;
-                identity?: {
-                    header: string;
-                } | undefined;
-                required?: boolean | undefined;
-                description?: string | undefined;
-                type: "headers";
-                url: string;
-            }> | undefined;
-        };
-        manifestName?: string | undefined;
-        manifestVersion?: number | undefined;
-        manifestHash?: string | undefined;
-        forkedFrom?: {
-            environment: string;
-            disk: number | null;
-        } | undefined;
-        slots?: {
-            name: string;
-            type: string;
-            required: boolean;
-            set: boolean;
-        }[] | undefined;
-        version: number;
-        appliedVersion: number;
-        ownerUserId: string | null;
-        state: string;
-        pod?: {
-            desired: "deleted" | "running" | "suspended";
-            observed: "creating" | "deleting" | "failed" | "lost" | "running" | "suspended";
-            volumeGeneration: number;
-            hostEpoch: number;
-            reason?: string | undefined;
-            imageDigest?: string | undefined;
-        } | undefined;
-        lastUsedAt: string;
-        disk?: {
-            latestVersion: number | null;
-            operation?: {
-                kind: "restore" | "seed" | "snapshot";
-                version?: number | undefined;
-                startedAt: string;
-            } | undefined;
-        } | undefined;
-        sessions: {
-            id: string;
-            activeTurnId: string | null;
-        }[];
-        createdAt: string;
-        updatedAt: string;
-    }[];
-    nextCursor: string | null;
-}>;
 export declare function readRoutes(api: OpenAPIHono<TenantEnv>): void;

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

@@ -5,18 +5,42 @@ import { turnTrace } from "../../../traces/read.js";
 import { readAccess, readStoreOf } from "../../../reads/access.js";
 import { requireApplication, requirePrincipal } from "../../../tenant/auth.js";
 import { fail } from "../../../tenant/http.js";
-import { environmentGrantsOf } from "../../../tenant/environments.js";
+import { readRuntimeLimits } from "../../../tenant/runtime-limits.js";
 import { tenantRoute } from "../define.js";
 import { jsonResponse } from "../respond.js";
+/** A page's `limit`, held to the Tenant's Runtime limit `pageItems` (`pageSize`). */
+const limitParam = (fallback) => z.coerce
+    .number()
+    .int()
+    .min(1)
+    .optional()
+    .meta({
+    description: `A page holds at most the Tenant's Runtime limit \`pageItems\` (default 200); a larger limit gets that many${fallback === undefined ? "" : `. Default ${fallback}, or that limit when it is lower`}`,
+});
 export const pageQuery = z.object({
-    limit: z.coerce.number().int().min(1).max(200).optional(),
+    limit: limitParam(),
     cursor: z.string().optional(),
 });
+/** The size of a page of a session's calls when the query names none (within `pageItems`). */
+const CALLS_PAGE_DEFAULT = 50;
+/** The size of a page of the model call export when the query names none (within `exportPageItems`). */
+const EXPORT_PAGE_DEFAULT = 200;
+/**
+ * The size of a page: `asked`, or, when the query names none, `fallback`, each within the Tenant's
+ * Runtime limit `name` (read for each request): a page asked larger holds that many, and its
+ * cursor reads on.
+ */
+export async function pageSize(ctx, asked, options = {}) {
+    const name = options.name ?? "pageItems";
+    const limit = (await ctx.store.tx((t) => readRuntimeLimits(t)))[name];
+    return Math.min(asked ?? options.fallback ?? limit, limit);
+}
 export const sessionPageQuery = pageQuery
     .extend({
     agentId: z.string().optional(),
     status: z.enum(SESSION_STATUSES).optional(),
-    environmentId: z.string().optional(),
+    /** Sessions that pinned a version of this agent manifest. */
+    manifest: z.string().optional(),
     ownerUserId: z.string().optional(),
 })
     .strict();
@@ -30,13 +54,7 @@ export async function sessionPage(ctx, scope, query) {
         return fail(400, "Pagination requires limit");
     if (filters.ownerUserId !== undefined)
         requireApplication(scope);
-    return readStoreOf(ctx).sessions(filters, { limit, cursor }, readAccess(scope));
-}
-export async function environmentPage(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).environments(labels, { limit, cursor }, readAccess(scope), environmentGrantsOf(scope));
+    return readStoreOf(ctx).sessions(filters, { limit: await pageSize(ctx, limit), cursor }, readAccess(scope));
 }
 export function readRoutes(api) {
     const sessionId = z.object({ sessionId: z.string() });
@@ -57,15 +75,14 @@ export function readRoutes(api) {
         requirePrincipal(c.get("scope"));
         return jsonResponse(200, await readStoreOf(c.env.tenant).manifest(c.req.param("sessionId"), readAccess(c.get("scope"))));
     });
+    const callsQuery = turnQuery
+        .extend({
+        limit: limitParam(CALLS_PAGE_DEFAULT),
+        cursor: z.string().optional(),
+    })
+        .strict();
     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();
+        const query = kind === "usage" ? turnQuery : callsQuery;
         // 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" }, {
@@ -93,18 +110,14 @@ export function readRoutes(api) {
                 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 q = parseQuery(callsQuery, c.req.query());
+            const limit = await pageSize(c.env.tenant, q.limit, { fallback: CALLS_PAGE_DEFAULT });
+            return jsonResponse(200, await store.modelCalls(id, q.turnId, { ...q, limit }, access));
         });
     }
     const toolCallsQuery = turnQuery
         .extend({
-        limit: z.coerce.number().int().min(1).max(200).default(50),
+        limit: limitParam(CALLS_PAGE_DEFAULT),
         cursor: z.string().optional(),
     })
         .strict();
@@ -125,7 +138,8 @@ export function readRoutes(api) {
     }, async (c) => {
         requirePrincipal(c.get("scope"));
         const q = parseQuery(toolCallsQuery, c.req.query());
-        return jsonResponse(200, await readStoreOf(c.env.tenant).toolCalls(c.req.param("sessionId"), q.turnId, q, readAccess(c.get("scope"))));
+        const limit = await pageSize(c.env.tenant, q.limit, { fallback: CALLS_PAGE_DEFAULT });
+        return jsonResponse(200, await readStoreOf(c.env.tenant).toolCalls(c.req.param("sessionId"), q.turnId, { ...q, limit }, readAccess(c.get("scope"))));
     });
     // A turn's spans (R7.5): the same mapping the trace projector posts, from the turn's log rows,
     // with the installation's content opt-ins. Spans carry cost: the application's, as /calls are.
@@ -153,7 +167,14 @@ export function readRoutes(api) {
     const exportQuery = z
         .object({
         after: z.string().optional(),
-        limit: z.coerce.number().int().min(1).max(1000).default(200),
+        limit: z.coerce
+            .number()
+            .int()
+            .min(1)
+            .optional()
+            .meta({
+            description: `A page holds at most the Tenant's Runtime limit \`exportPageItems\` (default 1000); a larger limit gets that many. Default ${EXPORT_PAGE_DEFAULT}, or that limit when it is lower`,
+        }),
     })
         .strict();
     // The whole Tenant's ledger is the Management API's (protocol 8): a management key, as itself.
@@ -171,6 +192,7 @@ export function readRoutes(api) {
         },
     }, async (c) => {
         const q = parseQuery(exportQuery, c.req.query());
-        return jsonResponse(200, await readStoreOf(c.env.tenant).exportModel(q.after, q.limit));
+        const limit = await pageSize(c.env.tenant, q.limit, { fallback: EXPORT_PAGE_DEFAULT, name: "exportPageItems" });
+        return jsonResponse(200, await readStoreOf(c.env.tenant).exportModel(q.after, limit));
     });
 }

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

@@ -1,19 +1,20 @@
 import { RESPONSE_ALREADY_SENT } from "@hono/node-server/utils/response";
 import { z } from "zod";
-import { PutAgentRequestSchema, PutSessionRequestSchema, SessionCommandSchema, } from "@nylorun/core/contracts";
+import { PROTOCOL_HEADER } from "@nylorun/core/compatibility";
+import { PutSessionRequestSchema, SessionCommandSchema, } from "@nylorun/core/contracts";
 import { handleSessionSandboxTool, SandboxRouteError } from "../../../core/sandbox-routes.js";
 import { traceContextOf } from "../../../traces/ids.js";
-import { AcceptedResponse, ListAgentsResponse, ListPublicAgentsResponse, ListSessionsResponse, SessionPage, HistoryPage, SessionEvent, PutAgentRequest, PutAgentResponse, PutSessionRequest, SandboxToolOutcome, SessionCommand, SessionItemsResponse, SessionView, StreamClosedFrame, } from "../../components.js";
+import { AcceptedResponse, QueuedResponse, ListSessionsResponse, SessionPage, HistoryPage, SessionEvent, 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 { environmentGrantsOf, sandboxRouteDeps } from "../../../tenant/environments.js";
+import { agentGrantsOf, sandboxRouteDeps } from "../../../tenant/agents.js";
 import { readHistory, requestCursor, streamHolderOf, streamSessionEvents } from "../../../tenant/session-streams.js";
-import { listAgentsPublic, listDefinitions, listSessions, putDefinition, putSession, sessionView, } from "../../../tenant/sessions.js";
+import { listSessions, putSession, sessionView } from "../../../tenant/sessions.js";
 import { readJson } from "../body.js";
 import { TraceHeaders, tenantRoute } from "../define.js";
-import { pageQuery, sessionPage, sessionPageQuery, parseQuery } from "./reads.js";
+import { pageQuery, pageSize, sessionPage, sessionPageQuery, parseQuery } from "./reads.js";
 import { jsonResponse } from "../respond.js";
 const OWN_SESSIONS = {
     credentials: ["application", "subject", "token"],
@@ -46,61 +47,31 @@ async function sessionBelow(ctx, incoming, id, access) {
     await loadSession(ctx, id, access);
     return requestCursor(incoming, urlOf(incoming));
 }
+/**
+ * What a message to a busy session does when it says nothing (D76): a protocol 17 client's waits
+ * in the queue; a protocol 16 client's is refused, as before.
+ */
+function deliveryFor(headers) {
+    const protocol = Number(headers.get(PROTOCOL_HEADER)?.trim());
+    return Number.isInteger(protocol) && protocol >= 17 ? "queue" : "reject";
+}
 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`.",
+        description: "A message starts a turn, or waits in the session's queue while a turn runs or waits (protocol 17; `delivery: \"reject\"` is refused with `409 session_busy` instead); the others answer what the session waits on, or cancel. Idempotent on the command's `idempotencyKey`.",
         request: { params: sessionId, body: body(SessionCommand), headers: TraceHeaders },
         responses: {
-            200: json(AcceptedResponse, "The command, accepted"),
-            409: { description: "A turn is running, or the session does not wait on this" },
-            422: {
-                description: "A message names a file the Tenant's model does not read (`attachment_unsupported`; `details.parts` lists each with its reason). No turn starts.",
-            },
+            200: json(z.union([AcceptedResponse, QueuedResponse]), "The command, accepted; a message may be queued"),
+            409: { description: "A turn is running (`session_busy`), or the session does not wait on this" },
+            429: { description: "The session's queue is full (`queue_full`)" },
         },
     }, async (c) => {
         // A `traceparent` joins the turn to the caller's trace (R7.4); a malformed one is ignored.
         const trace = traceContextOf(c.req.raw.headers);
-        return jsonResponse(200, await command(c.env.tenant, c.req.param("sessionId"), SessionCommandSchema.parse(await readJson(c.req.raw)), c.get("scope"), trace ? { trace } : {}));
-    });
-    tenantRoute(api, {
-        credentials: ["application", "subject", "token"],
-        scopes: ["agents:read", "agents:write"],
-    }, {
-        method: "get",
-        path: "/v1/agents",
-        tags: ["Agents"],
-        summary: "List agents",
-        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;
-        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",
-        description: "Saves the agent's definition. With `?dryRun=true` (protocol 14) every check runs and nothing is saved: the answer says what a save would record.",
-        request: {
-            params: z.object({ agentId: z.string() }),
-            query: z.object({
-                dryRun: z.enum(["true", "false"]).optional().meta({ description: "`true`: check and save nothing" }),
-            }),
-            body: body(PutAgentRequest),
-        },
-        responses: { 200: json(PutAgentResponse, "The definition, stored (or checked, with dryRun)") },
-    }, async (c) => {
-        return jsonResponse(200, await putDefinition(c.env.tenant, c.req.param("agentId"), PutAgentRequestSchema.parse(await readJson(c.req.raw)), { dryRun: c.req.query("dryRun") === "true" }));
+        return jsonResponse(200, await command(c.env.tenant, c.req.param("sessionId"), SessionCommandSchema.parse(await readJson(c)), c.get("scope"), { ...(trace ? { trace } : {}), delivery: deliveryFor(c.req.raw.headers) }));
     });
     tenantRoute(api, OWN_SESSIONS, {
         method: "get",
@@ -121,7 +92,7 @@ export function sessionRoutes(api) {
         path: "/v1/sessions/{sessionId}",
         tags: ["Sessions"],
         summary: "Open a session",
-        description: "Creates the session, or answers the one already opened with the same agent, owner, info and Environment. Its Environment (its sandbox and vault) is chosen now and fixed for its life.",
+        description: "Creates the session on an Agent, or answers the one already opened with the same Agent, owner and info. Its Agent (its sandbox and vault) is fixed for its life, and it pins the manifest version the Agent runs. No session is special: an app that keeps one conversation going reuses its id.",
         request: { params: sessionId, body: body(PutSessionRequest) },
         responses: {
             200: json(SessionView, "The session"),
@@ -130,12 +101,12 @@ export function sessionRoutes(api) {
     }, async (c) => {
         const scope = c.get("scope");
         const ctx = c.env.tenant;
-        const request = PutSessionRequestSchema.parse(await readJson(c.req.raw));
+        const request = PutSessionRequestSchema.parse(await readJson(c));
         // Agent code may trust `info`: only an app server sets it.
         if (scope.kind === "token" && request.info !== undefined)
             fail(403, "A token caller cannot set session info", { code: "scope_required" });
-        const grants = environmentGrantsOf(scope);
-        const session = await putSession(ctx, c.req.param("sessionId"), request, accessOf(scope), grants === undefined ? {} : { environmentGrants: grants });
+        const grants = agentGrantsOf(scope);
+        const session = await putSession(ctx, c.req.param("sessionId"), request, accessOf(scope), grants === undefined ? {} : { agentGrants: grants });
         return jsonResponse(200, await ctx.store.tx((t) => sessionView(t, session)));
     });
     tenantRoute(api, OWN_SESSIONS, {
@@ -172,7 +143,8 @@ export function sessionRoutes(api) {
         const ctx = c.env.tenant;
         const id = c.req.param("sessionId");
         const cursor = await sessionBelow(ctx, c.env.incoming, id, accessOf(scope));
-        const { limit } = parseQuery(pageQuery.pick({ limit: true }), { limit: c.req.query("limit") });
+        const { limit: asked } = parseQuery(pageQuery.pick({ limit: true }), { limit: c.req.query("limit") });
+        const limit = asked === undefined ? undefined : await pageSize(ctx, asked);
         return jsonResponse(200, await readHistory(ctx, id, cursor, c.req.query("agent"), limit));
     });
     tenantRoute(api, OWN_SESSIONS, {
@@ -222,7 +194,7 @@ export function sessionRoutes(api) {
         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));
+            return jsonResponse(200, await handleSessionSandboxTool(sandboxRouteDeps(ctx), id, c.req.param("tool"), await readJson(c), c.req.raw.signal));
         }
         catch (error) {
             if (error instanceof SandboxRouteError)

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

@@ -1,7 +1,7 @@
 /**
  * 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.
+ * model it calls, what its model calls cost and may cost (budgets), the sandboxes its
+ * sessions get, and its Runtime limits.
  *
  * 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.