@nylorun/runtime 0.27.0-beta → 0.29.0-beta

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

@@ -30,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;
@@ -42,145 +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;
-            limits?: {
-                artifacts?: {
-                    fileBytes?: number | undefined;
-                    totalBytes?: number | undefined;
-                } | undefined;
-                skills?: {
-                    totalBytes?: number | undefined;
-                } | undefined;
-                disk?: {
-                    versionBytes?: number | undefined;
-                    versionEntries?: number | undefined;
-                } | undefined;
-            } | 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;
-        limits: {
-            artifacts: {
-                fileBytes: number;
-                totalBytes: number;
-            };
-            skills: {
-                totalBytes: number;
-            };
-            disk: {
-                versionBytes: number;
-                versionEntries: number;
-            };
-        };
-        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

@@ -1,14 +1,35 @@
 import { z } from "zod";
 import { SESSION_STATUSES } from "@nylorun/core/contracts";
+import { PROTOCOL_HEADER } from "@nylorun/core/compatibility";
 import { SessionManifestView, SessionUsageTotals, ModelCallsPage, ModelCallExportPage, ToolCallsPage, TurnTrace, } from "../../components.js";
 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 { readRuntimeLimits } from "../../../tenant/runtime-limits.js";
-import { environmentGrantsOf } from "../../../tenant/environments.js";
 import { tenantRoute } from "../define.js";
 import { jsonResponse } from "../respond.js";
+/**
+ * Whether a client speaks protocol 18, whose usage reads carry the calls' timing and the cost by
+ * token kind. An older client's SDK parses these reads strictly, so it gets them without.
+ */
+function usageByKind(header) {
+    const protocol = Number(header?.trim());
+    return Number.isInteger(protocol) && protocol >= 18;
+}
+/** A session's usage as a protocol 16 or 17 client reads it. */
+function totalsBefore18(totals) {
+    const { costSplit: _split, splitCalls: _splitCalls, modelTimeMs: _time, timedCalls: _timed, ...rest } = totals;
+    return rest;
+}
+/** A model call as a protocol 16 or 17 client reads it. */
+function callBefore18(call) {
+    const { startedAt: _started, endedAt: _ended, usage, ...rest } = call;
+    if (usage === null)
+        return { ...rest, usage };
+    const { costSplit: _split, ...counts } = usage;
+    return { ...rest, usage: counts };
+}
 /** A page's `limit`, held to the Tenant's Runtime limit `pageItems` (`pageSize`). */
 const limitParam = (fallback) => z.coerce
     .number()
@@ -40,7 +61,8 @@ 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();
@@ -56,12 +78,6 @@ export async function sessionPage(ctx, scope, query) {
         requireApplication(scope);
     return readStoreOf(ctx).sessions(filters, { limit: await pageSize(ctx, 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: await pageSize(ctx, limit), cursor }, readAccess(scope), environmentGrantsOf(scope));
-}
 export function readRoutes(api) {
     const sessionId = z.object({ sessionId: z.string() });
     const turnQuery = z.object({ turnId: z.string().optional() }).strict();
@@ -111,14 +127,16 @@ export function readRoutes(api) {
             },
         }, async (c) => {
             requirePrincipal(c.get("scope"));
-            const store = readStoreOf(c.env.tenant), access = readAccess(c.get("scope")), id = c.req.param("sessionId");
+            const store = readStoreOf(c.env.tenant), access = readAccess(c.get("scope")), id = c.req.param("sessionId"), current = usageByKind(c.req.header(PROTOCOL_HEADER));
             if (kind === "usage") {
                 const q = parseQuery(turnQuery, c.req.query());
-                return jsonResponse(200, await store.usage(id, q.turnId, access));
+                const totals = await store.usage(id, q.turnId, access);
+                return jsonResponse(200, current ? totals : totalsBefore18(totals));
             }
             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 page = await store.modelCalls(id, q.turnId, { ...q, limit }, access);
+            return jsonResponse(200, current ? page : { ...page, calls: page.calls.map(callBefore18) });
         });
     }
     const toolCallsQuery = turnQuery
@@ -199,6 +217,7 @@ export function readRoutes(api) {
     }, async (c) => {
         const q = parseQuery(exportQuery, c.req.query());
         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));
+        const page = await readStoreOf(c.env.tenant).exportModel(q.after, limit);
+        return jsonResponse(200, usageByKind(c.req.header(PROTOCOL_HEADER)) ? page : { ...page, calls: page.calls.map(callBefore18) });
     });
 }

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

@@ -1,16 +1,17 @@
 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, pageSize, sessionPage, sessionPageQuery, parseQuery } from "./reads.js";
@@ -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" },
+            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)), 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)"),
-            413: { description: "A skill's files hold more than the Tenant's skill limit together (`limit_exceeded`)" },
-        },
-    }, async (c) => {
-        return jsonResponse(200, await putDefinition(c.env.tenant, c.req.param("agentId"), PutAgentRequestSchema.parse(await readJson(c)), { 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"),
@@ -134,8 +105,8 @@ export function sessionRoutes(api) {
         // 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, {

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

@@ -18,7 +18,7 @@ import { tenantReset, streamsStatus, } from "../../../tenant/streams.js";
 import { readJson } from "../body.js";
 import { pathSegments, tenantRoute } from "../define.js";
 import { jsonResponse } from "../respond.js";
-import { rearmPodTimers } from "../../../tenant/environments.js";
+import { rearmPodTimers } from "../../../tenant/agents.js";
 import { hostTuning } from "../../../tuning.js";
 import { budgetIssues, toolPolicyIssues } from "../../../tenant/limits.js";
 /** Every Management API route (`/v1/tenant/*`): a management key, acting as itself (protocol 8). */
@@ -37,7 +37,7 @@ const body = (schema) => ({
 });
 const budgetRow = (budget, updatedAt) => ({
     scope: budget.scope,
-    scopeId: budget.scope === "agent" ? budget.id : "*",
+    scopeId: budget.scope === "manifest" ? budget.id : "*",
     period: budget.period ?? null,
     limitUsd: budget.limitUsd ?? null,
     limitTokens: budget.limitTokens ?? null,
@@ -45,7 +45,7 @@ const budgetRow = (budget, updatedAt) => ({
 });
 const budgetView = (row) => ({
     scope: row.scope,
-    ...(row.scope === "agent" ? { id: row.scopeId } : {}),
+    ...(row.scope === "manifest" ? { id: row.scopeId } : {}),
     ...(row.period ? { period: row.period } : {}),
     ...(row.limitUsd !== null ? { limitUsd: row.limitUsd } : {}),
     ...(row.limitTokens !== null ? { limitTokens: row.limitTokens } : {}),
@@ -114,7 +114,7 @@ export function tenantRoutes(api) {
         path: "/v1/tenant/reset",
         tags: ["Tenant"],
         summary: "Reset the Tenant",
-        description: "Deletes its sessions, its Environments (with their vaults), or both, after draining or cancelling the turns in progress. The Tenant stays open.",
+        description: "Deletes its sessions, its Agents (with their vaults), or both, after draining or cancelling the turns in progress. The Tenant stays open.",
         request: { body: body(ResetTenantRequest) },
         responses: { 200: json(ResetTenantResponse, "Reset") },
     }, async (c) => {
@@ -123,7 +123,7 @@ export function tenantRoutes(api) {
         await drain(ctx, request.activeWork, hostTuning().tenant.drainTimeoutMs);
         // A sessions reset moves the Tenant to a new basin generation, so a session created
         // again with the same id, during or after the reset, starts in an empty basin at 0.
-        const sessionsReset = request.scope !== "environments";
+        const sessionsReset = request.scope !== "agents";
         await resetTenant({
             store: ctx.store,
             sandbox: ctx.sandbox,
@@ -221,15 +221,15 @@ export function tenantRoutes(api) {
         method: "get",
         path: "/v1/tenant/sandbox",
         tags: ["Tenant"],
-        summary: "Get the Tenant's sandbox backend and Environment settings",
+        summary: "Get the Tenant's sandbox backend and Agent compute settings",
         responses: { 200: json(TenantSandboxView, "The backend in use and the configuration in force") },
     }, async (c) => jsonResponse(200, await sandboxView(c.env.tenant)));
     tenantRoute(api, MANAGEMENT, {
         method: "put",
         path: "/v1/tenant/sandbox",
         tags: ["Tenant"],
-        summary: "Set the Tenant's Environment settings",
-        description: "The limits every Environment's recipe must fit, the pods' stop grace and where harnesses may run (Tenant setting `environments.config`).",
+        summary: "Set the Tenant's Agent compute settings",
+        description: "The limits every Agent's runtime must fit, the pods' stop grace and where harnesses may run (Tenant setting `environments.config`).",
         request: { body: body(PutTenantEnvironmentsRequest) },
         responses: { 200: json(TenantSandboxView, "The configuration now in force") },
     }, async (c) => {
@@ -307,7 +307,10 @@ export function tenantRoutes(api) {
         path: "/v1/tenant/tool-policy",
         tags: ["Tenant"],
         summary: "Get the Tenant's tool policy",
-        responses: { 200: json(ToolPolicy, "The rules the Tool Gate applies to every MCP and HTTP tool call") },
+        responses: {
+            200: json(ToolPolicy, "The rules the Tool Gate applies to every MCP and HTTP tool call"),
+            409: { description: "A stored rule names an MCP tool by its model-facing `server__tool` name: every call is refused until the policy is set again" },
+        },
     }, async (c) => {
         try {
             return jsonResponse(200, await c.env.tenant.store.tx((t) => readToolPolicy(t)));
@@ -325,7 +328,7 @@ export function tenantRoutes(api) {
         path: "/v1/tenant/tool-policy",
         tags: ["Tenant"],
         summary: "Set the Tenant's tool policy",
-        description: "Replaces every rule. The Tool Gate applies them to each MCP and HTTP tool call of every harness, before it sends the call: the strictest rule that matches decides. `deny` refuses the call (the model gets `tool.denied`), `ask` holds it and pauses the turn until a person answers it with an `approve` command on the session, `allow` runs it. A call no rule matches runs. A rule matches when every selector it sets matches: `tool` (the name the model calls it by; `*` matches any run of characters), `server` (an MCP server's name), `kind` (`mcp` or `http`), `agent` (the agent that calls it) and `when` (fields of the call's input by dotted path, each tested with `equals`, `in`, `gt`, `gte`, `lt`, `lte` or `matches`). Sandbox tools never cross the gate. An empty list allows every call.",
+        description: "Replaces every rule. The Tool Gate applies them to each MCP and HTTP tool call of every harness, before it sends the call: the strictest rule that matches decides. `deny` refuses the call (the model gets `tool.denied`), `ask` holds it and pauses the turn until a person answers it with an `approve` command on the session, `allow` runs it. A call no rule matches runs. A rule matches when every selector it sets matches: `tool` (the tool's identity: an MCP tool's own name on its `server`, or an HTTP tool's declared name, never the name the model calls it by; `*` matches any run of characters), `server` (an MCP server's name), `kind` (`mcp` or `http`), `agent` (the agent that calls it: the agent manifest's name, or the id of an agent used as a tool or of a flow's agent, never an Agent's id) and `when` (fields of the call's input by dotted path, each tested with `equals`, `in`, `gt`, `gte`, `lt`, `lte` or `matches`). A `tool` with `__` in it, a model-facing `server__tool` name, is refused (`400`): name an MCP tool by `server` and `tool`. A stored policy with such a rule refuses every call until it is set again. Sandbox tools never cross the gate. An empty list allows every call.",
         request: { body: body(PutToolPolicyRequest) },
         responses: { 200: json(ToolPolicy, "The policy now in force") },
     }, async (c) => {

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

@@ -0,0 +1,10 @@
+/**
+ * An Agent's triggers and their runs (track T4, D74): read them, pause and resume one, run one now
+ * (keyed by `Idempotency-Key`), and page the runs; make a webhook trigger's signing secret, and
+ * take a sender's delivery at its endpoint (D75), an anonymous, unversioned route. What a trigger is lives in the Agent's manifest
+ * (`runtime.triggers`); these routes change only what the Agent owns, its status.
+ */
+import type { OpenAPIHono } from "@hono/zod-openapi";
+import type { TenantEnv } from "../app.js";
+export declare function triggerRoutes(api: OpenAPIHono<TenantEnv>): void;
+export declare function webhookRoutes(api: OpenAPIHono<TenantEnv>): void;