@nylorun/runtime 0.22.0-beta → 0.24.0-beta

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

@@ -0,0 +1,283 @@
+import { z } from "zod";
+import { isEnvironmentId, PutEnvironmentRequestSchema, PutEnvironmentSecretRequestSchema, RestoreEnvironmentRequestSchema, } from "@nylorun/core/contracts";
+import { deleteEnvironmentVersion, environmentVersions, restoreEnvironment, snapshotEnvironment, } from "../../../artifacts/disk.js";
+import { DeleteEnvironmentResponse, DeletedResponse, EnvironmentPage, EnvironmentRestore, EnvironmentSnapshot, EnvironmentVersions, RestoreEnvironmentRequest, EnvironmentSecretView, EnvironmentView, ListEnvironmentEventsResponse, ListEnvironmentSecretsResponse, ListEnvironmentsResponse, PutEnvironmentRequest, PutEnvironmentSecretRequest, } from "../../components.js";
+import { fail } from "../../../tenant/http.js";
+import { actorOf, assertReaches, deleteEnvironment, environmentEventsOf, getEnvironment, listEnvironments, putEnvironment, resetEnvironment, stopEnvironment, } from "../../../tenant/environments.js";
+import { readJson } from "../body.js";
+import { tenantRoute } from "../define.js";
+import { environmentPage, pageQuery } from "./reads.js";
+import { jsonResponse } from "../respond.js";
+/** Reading an Environment: any caller that may use sessions, or change Environments. */
+const READ = {
+    credentials: ["application", "subject", "token"],
+    scopes: ["sessions:own", "environments:write"],
+};
+/** Creating, changing or deleting one, and writing its secrets. */
+const WRITE = {
+    credentials: ["application", "subject", "token"],
+    scopes: ["environments:write"],
+};
+const json = (schema, description) => ({
+    description,
+    content: { "application/json": { schema } },
+});
+const environmentId = z.object({
+    environmentId: z
+        .string()
+        .meta({ description: "The Environment id, percent-encoded: `users%2Falice%2Fweb` for `users/alice/web`" }),
+});
+const secretPath = environmentId.extend({
+    name: z.string().meta({
+        description: "The secret's name: the variable for `environment_secret` and `environment_variable`, a label for `bearer` and `headers`",
+    }),
+});
+/** The path's Environment id, or a 400 naming the rule. */
+function idOf(value) {
+    if (!isEnvironmentId(value))
+        return fail(400, "An Environment id is up to 200 characters: /-separated segments of letters, digits, '.', '_' and '-'");
+    return value;
+}
+/** `label=k=v`, repeated: every one must match. */
+function labelsOf(values) {
+    const labels = {};
+    for (const value of values ?? []) {
+        const at = value.indexOf("=");
+        if (at <= 0)
+            fail(400, `label must be key=value, not ${value}`);
+        labels[value.slice(0, at)] = value.slice(at + 1);
+    }
+    return labels;
+}
+export function environmentRoutes(api) {
+    tenantRoute(api, READ, {
+        method: "get",
+        path: "/v1/environments",
+        tags: ["Environments"],
+        summary: "List Environments",
+        description: "Every Environment with all the labels asked for. A token caller sees only the Environments its grants reach.",
+        request: {
+            query: pageQuery.extend({
+                label: z
+                    .union([z.string(), z.array(z.string())])
+                    .optional()
+                    .meta({ description: "`key=value`; repeat it to require several labels" }),
+            }),
+        },
+        responses: {
+            200: json(z.union([ListEnvironmentsResponse, EnvironmentPage]), "The Environments; limit opts into pagination"),
+        },
+    }, async (c) => jsonResponse(200, c.req.query("limit") !== undefined
+        ? await environmentPage(c.env.tenant, c.get("scope"), c.req.query(), labelsOf(c.req.queries("label")))
+        : await listEnvironments(c.env.tenant, labelsOf(c.req.queries("label")), c.get("scope"))));
+    tenantRoute(api, WRITE, {
+        method: "put",
+        path: "/v1/environments/{environmentId}",
+        tags: ["Environments"],
+        summary: "Create, find or change an Environment",
+        description: "Creates the Environment and its vault within the Tenant's limits, or answers the one with this id, so get-or-create is one call. On an existing one the fields sent are compared: `kind` and `storage` are fixed (`409`), labels replace, `ownerUserId` sets or (with `null`) clears the owner guard, and any other change writes the recipe and bumps `version`. A pod's image and resources apply when it is next started from stopped (`appliedVersion`); `network.allowedHosts`, `harness` and `lifecycle` apply at once. Kind `pod` needs sandbox pods (`nylorun sandbox enable`) and is created at once.",
+        request: {
+            params: environmentId,
+            body: { required: true, content: { "application/json": { schema: PutEnvironmentRequest } } },
+        },
+        responses: {
+            200: json(EnvironmentView, "The Environment"),
+            409: {
+                description: "An Environment with this id has another kind or storage, the Tenant holds as many Environments as it allows (`limit_exceeded`), kind pod without sandbox pods (`environment_unavailable`), or it is being deleted (`environment_busy`)",
+            },
+        },
+    }, async (c) => {
+        const id = idOf(c.req.param("environmentId"));
+        const body = PutEnvironmentRequestSchema.parse(await readJson(c.req.raw));
+        return jsonResponse(200, await putEnvironment(c.env.tenant, id, body, c.get("scope")));
+    });
+    tenantRoute(api, READ, {
+        method: "get",
+        path: "/v1/environments/{environmentId}",
+        tags: ["Environments"],
+        summary: "Get an Environment",
+        description: "Its recipe, versions, labels, owner guard, state and the sessions that name it (acting for a person, only theirs).",
+        request: { params: environmentId },
+        responses: { 200: json(EnvironmentView, "The Environment") },
+    }, async (c) => jsonResponse(200, await getEnvironment(c.env.tenant, idOf(c.req.param("environmentId")), c.get("scope"))));
+    tenantRoute(api, READ, {
+        method: "get",
+        path: "/v1/environments/{environmentId}/events",
+        tags: ["Environments"],
+        summary: "Read an Environment's lifecycle events",
+        description: "`environment.created`, `.attached`, `.detached`, `.deleted` and a pod's `.running`, `.suspended`, `.relaunched`, `.lost`, `.reset` and `.failed`, in order, numbered from 0.",
+        request: {
+            params: environmentId,
+            query: z.object({
+                from: z.string().optional().meta({ description: "The first `seq` to return" }),
+            }),
+        },
+        responses: { 200: json(ListEnvironmentEventsResponse, "The events") },
+    }, async (c) => {
+        const from = c.req.query("from");
+        if (from !== undefined && !/^\d+$/.test(from))
+            fail(400, "from must be a seq");
+        return jsonResponse(200, await environmentEventsOf(c.env.tenant, idOf(c.req.param("environmentId")), c.get("scope"), from === undefined ? undefined : Number(from)));
+    });
+    tenantRoute(api, WRITE, {
+        method: "delete",
+        path: "/v1/environments/{environmentId}",
+        tags: ["Environments"],
+        summary: "Delete an Environment",
+        description: "Deletes the Environment, its vault with every secret, and its files. Sessions that name it keep its id; their next turn is refused (`environment_unavailable`) until an Environment with this id exists again.",
+        request: { params: environmentId },
+        responses: {
+            200: json(DeleteEnvironmentResponse, "Deleted, or there was none"),
+            409: { description: "A session that names it has a turn running (`environment_busy`)" },
+        },
+    }, async (c) => jsonResponse(200, await deleteEnvironment(c.env.tenant, idOf(c.req.param("environmentId")), c.get("scope"))));
+    for (const [action, summary, description, run] of [
+        [
+            "stop",
+            "Stop a pod Environment",
+            "Suspends the pod: its volume is kept, and the next turn of a session that names it starts it again. Refused during a turn (`environment_busy`).",
+            stopEnvironment,
+        ],
+        [
+            "reset",
+            "Reset a pod Environment",
+            "A new pod on a new, empty volume with the recipe applied; the old pod and volume are deleted. The way out of `environment_lost`. Refused during a turn (`environment_busy`).",
+            resetEnvironment,
+        ],
+    ])
+        tenantRoute(api, WRITE, {
+            method: "post",
+            path: `/v1/environments/{environmentId}/${action}`,
+            tags: ["Environments"],
+            summary,
+            description,
+            request: { params: environmentId },
+            responses: {
+                200: json(EnvironmentView, "The Environment"),
+                400: { description: "The Environment is not of kind pod" },
+                409: {
+                    description: "A turn holds it (`environment_busy`), or no sandbox pods (`environment_unavailable`)",
+                },
+            },
+        }, async (c) => jsonResponse(200, await run(c.env.tenant, idOf(c.req.param("environmentId")), c.get("scope"))));
+    tenantRoute(api, WRITE, {
+        method: "post",
+        path: "/v1/environments/{environmentId}/snapshot",
+        tags: ["Environments"],
+        summary: "Snapshot an Environment's disk",
+        description: "Between turns, a new version of the Environment's disk (`/workspace`, and a pod's `/harness` but the engine's own files): files with their modes and modification times, links and empty directories, as a version of the folder artifact the Environment owns. Unchanged files are stored once; an unchanged disk makes no version (`unchanged`). A stopped pod is started first. Refused during a turn or another copy (`environment_busy`).",
+        request: { params: environmentId },
+        responses: {
+            201: json(EnvironmentSnapshot, "The version"),
+            400: { description: "The Environment is of kind none" },
+            409: { description: "A turn or another copy holds the disk (`environment_busy`), or the pod could not start (`environment_unavailable`)" },
+            413: { description: "Past the entries, bytes or Tenant total a version may hold (`limit_exceeded`)" },
+        },
+    }, async (c) => jsonResponse(201, await snapshotEnvironment(c.env.tenant, idOf(c.req.param("environmentId")), c.get("scope"))));
+    tenantRoute(api, WRITE, {
+        method: "post",
+        path: "/v1/environments/{environmentId}/restore",
+        tags: ["Environments"],
+        summary: "Restore a version of an Environment's disk",
+        description: "Puts disk version `version` (or `latest`) back. A virtual Environment's workspace is rewritten at once (`done`); a pod gets a new volume seeded from the version before any turn (`pending`, with `disk.operation` in the view until it ends). The Environment keeps its id, vault and sessions. Refused during a turn or another copy (`environment_busy`).",
+        request: {
+            params: environmentId,
+            body: { required: true, content: { "application/json": { schema: RestoreEnvironmentRequest } } },
+        },
+        responses: {
+            200: json(EnvironmentRestore, "Restored, or being restored"),
+            404: { description: "No such Environment, or no such version" },
+            409: { description: "A turn or another copy holds the disk (`environment_busy`)" },
+        },
+    }, async (c) => {
+        const body = RestoreEnvironmentRequestSchema.parse(await readJson(c.req.raw));
+        return jsonResponse(200, await restoreEnvironment(c.env.tenant, idOf(c.req.param("environmentId")), c.get("scope"), body.version));
+    });
+    tenantRoute(api, READ, {
+        method: "get",
+        path: "/v1/environments/{environmentId}/versions",
+        tags: ["Environments"],
+        summary: "List an Environment's disk versions",
+        description: "Newest first. Read a version's tree, files, diff and zip through `/v1/artifacts/{artifactId}/versions/{version}/…`.",
+        request: { params: environmentId },
+        responses: { 200: json(EnvironmentVersions, "The versions") },
+    }, async (c) => jsonResponse(200, await environmentVersions(c.env.tenant, idOf(c.req.param("environmentId")), c.get("scope"))));
+    tenantRoute(api, WRITE, {
+        method: "delete",
+        path: "/v1/environments/{environmentId}/versions/{version}",
+        tags: ["Environments"],
+        summary: "Delete an Environment's disk version",
+        description: "Deletes the version, and the stored files no other version names. Refused while a seed reads it.",
+        request: { params: environmentId.extend({ version: z.string() }) },
+        responses: {
+            200: json(z.object({ environmentId: z.string(), version: z.number(), deleted: z.boolean() }), "Deleted, or there was none"),
+            409: { description: "A new volume is being seeded from it (`environment_busy`)" },
+        },
+    }, async (c) => {
+        const version = c.req.param("version") ?? "";
+        if (!/^[1-9]\d{0,8}$/.test(version))
+            fail(400, "version must be a version number");
+        return jsonResponse(200, await deleteEnvironmentVersion(c.env.tenant, idOf(c.req.param("environmentId")), c.get("scope"), Number(version)));
+    });
+    tenantRoute(api, READ, {
+        method: "get",
+        path: "/v1/environments/{environmentId}/secrets",
+        tags: ["Environments"],
+        summary: "List an Environment's secrets",
+        description: "Each secret's name, type and binding (its URL, or its hosts and header). Never a value.",
+        request: { params: environmentId },
+        responses: { 200: json(ListEnvironmentSecretsResponse, "The secrets") },
+    }, async (c) => {
+        const id = idOf(c.req.param("environmentId"));
+        assertReaches(c.get("scope"), id);
+        return jsonResponse(200, { secrets: await c.env.tenant.vault.listEnvironmentSecrets(id) });
+    });
+    tenantRoute(api, READ, {
+        method: "get",
+        path: "/v1/environments/{environmentId}/secrets/{name}",
+        tags: ["Environments"],
+        summary: "Get an Environment's secret",
+        description: "Its name, type and binding. Never its value.",
+        request: { params: secretPath },
+        responses: { 200: json(EnvironmentSecretView, "The secret") },
+    }, async (c) => {
+        const id = idOf(c.req.param("environmentId"));
+        assertReaches(c.get("scope"), id);
+        return jsonResponse(200, await c.env.tenant.vault.getEnvironmentSecret(id, c.req.param("name") ?? ""));
+    });
+    tenantRoute(api, WRITE, {
+        method: "put",
+        path: "/v1/environments/{environmentId}/secrets/{name}",
+        tags: ["Environments"],
+        summary: "Write an Environment's secret",
+        description: "Creates or replaces one credential of the Environment's vault: an `environment_secret` (the variable `name` reads the sentinel `nylorun-managed` in the sandbox, and egress-gate sets the value as a header on requests to `allowedHosts`), an `environment_variable` (a plain variable), or a `bearer` token or `headers` map for the MCP servers and HTTP tools at `url`. The same name and type re-seals the value and binding; another type replaces it. A rotated value is used from the next request. A second credential for a host or a URL is `409 credential_conflict`.",
+        request: {
+            params: secretPath,
+            body: { required: true, content: { "application/json": { schema: PutEnvironmentSecretRequest } } },
+        },
+        responses: {
+            200: json(EnvironmentSecretView, "The secret, without its value"),
+            409: { description: "Another credential is bound to one of its hosts or to its URL (`credential_conflict`)" },
+        },
+    }, async (c) => {
+        const id = idOf(c.req.param("environmentId"));
+        const scope = c.get("scope");
+        assertReaches(scope, id);
+        const body = PutEnvironmentSecretRequestSchema.parse(await readJson(c.req.raw));
+        return jsonResponse(200, await c.env.tenant.keys.putEnvironmentSecret(id, c.req.param("name") ?? "", body, actorOf(scope)));
+    });
+    tenantRoute(api, WRITE, {
+        method: "delete",
+        path: "/v1/environments/{environmentId}/secrets/{name}",
+        tags: ["Environments"],
+        summary: "Delete an Environment's secret",
+        description: "The next request that would have used it gets none.",
+        request: { params: secretPath },
+        responses: { 200: json(DeletedResponse, "Deleted") },
+    }, async (c) => {
+        const id = idOf(c.req.param("environmentId"));
+        const scope = c.get("scope");
+        assertReaches(scope, id);
+        return jsonResponse(200, await c.env.tenant.vault.deleteEnvironmentSecret(id, c.req.param("name") ?? "", actorOf(scope)));
+    });
+}

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

@@ -1,7 +1,7 @@
 /**
  * A remote MCP server's tools before an agent names it (`POST /v1/tenant/mcp/preview`, R2b C12,
  * the Management API): a management key (or Studio's key, acting as itself), as the vault routes
- * take. The keys service runs it (`Keys.previewMcp`), since it sends an installation vault's
+ * take. The keys service runs it (`Keys.previewMcp`), since it sends an Environment's
  * credential; this process never reads the plaintext.
  */
 import type { OpenAPIHono } from "@hono/zod-openapi";

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

@@ -16,13 +16,13 @@ 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 installation vault's credential for that URL (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 `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.",
         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, "Several installation vaults hold a credential for the URL (name one with `vaultId`), or the one there cannot be used"),
+            409: json(Rejected, "The Environment'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) => {

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

@@ -19,7 +19,7 @@ export function describeCaller(scope) {
                 subject: scope.subject,
                 scopes: ordered(scope.scopes),
                 agents: scope.agents === "*" ? "*" : [...scope.agents].sort(),
-                sandboxes: [...(scope.sandboxes ?? [])],
+                environments: [...(scope.environments ?? [])],
                 via: `issuer:${scope.issuer}`,
             };
         case "management":

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

@@ -21,7 +21,7 @@ export declare const sessionPageQuery: z.ZodObject<{
         uncertain: "uncertain";
         waiting: "waiting";
     }>>;
-    sandboxId: z.ZodOptional<z.ZodString>;
+    environmentId: 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,27 +33,63 @@ 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;
-        sandboxId: string | null;
+        environmentId: string | null;
         createdAt: string | null;
         lastEventAt: string | null;
     }[];
     nextCursor: string | null;
 }>;
-export declare function sandboxPage(ctx: TenantEnv["Bindings"]["tenant"], scope: TenantEnv["Variables"]["scope"], query: Record<string, string>, labels: Record<string, string>): Promise<{
-    sandboxes: {
+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: "pod" | "virtual";
+        kind: "none" | "pod" | "virtual";
         labels: Record<string, string>;
-        spec: Record<string, unknown>;
-        state: "creating" | "ready" | "running" | "stopped";
+        recipe: {
+            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;
+            }[] | undefined;
+        };
+        version: number;
+        appliedVersion: number;
+        ownerUserId: string | null;
+        state: string;
         pod?: {
             desired: "deleted" | "running" | "suspended";
-            observed: "creating" | "deleting" | "expired" | "failed" | "lost" | "running" | "suspended";
+            observed: "creating" | "deleting" | "failed" | "lost" | "running" | "suspended";
             volumeGeneration: number;
             hostEpoch: number;
-            expiresAt?: string | undefined;
             reason?: 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;

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

@@ -1,10 +1,11 @@
 import { z } from "zod";
 import { SESSION_STATUSES } from "@nylorun/core/contracts";
-import { SessionManifestView, SessionUsageTotals, ModelCallsPage, ModelCallExportPage, } from "../../components.js";
+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 { sandboxGrantsOf } from "../../../tenant/sandboxes.js";
+import { environmentGrantsOf } from "../../../tenant/environments.js";
 import { tenantRoute } from "../define.js";
 import { jsonResponse } from "../respond.js";
 export const pageQuery = z.object({
@@ -15,7 +16,7 @@ export const sessionPageQuery = pageQuery
     .extend({
     agentId: z.string().optional(),
     status: z.enum(SESSION_STATUSES).optional(),
-    sandboxId: z.string().optional(),
+    environmentId: z.string().optional(),
     ownerUserId: z.string().optional(),
 })
     .strict();
@@ -31,11 +32,11 @@ export async function sessionPage(ctx, scope, query) {
         requireApplication(scope);
     return readStoreOf(ctx).sessions(filters, { limit, cursor }, readAccess(scope));
 }
-export async function sandboxPage(ctx, scope, query, labels) {
+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).sandboxes(labels, { limit, cursor }, readAccess(scope), sandboxGrantsOf(scope));
+    return readStoreOf(ctx).environments(labels, { limit, cursor }, readAccess(scope), environmentGrantsOf(scope));
 }
 export function readRoutes(api) {
     const sessionId = z.object({ sessionId: z.string() });
@@ -101,6 +102,54 @@ export function readRoutes(api) {
             return jsonResponse(200, await store.modelCalls(id, q.turnId, q, access));
         });
     }
+    const toolCallsQuery = turnQuery
+        .extend({
+        limit: z.coerce.number().int().min(1).max(200).default(50),
+        cursor: z.string().optional(),
+    })
+        .strict();
+    // What ran, with what input, how many sends and how it ended (R5.2): the effect journal's tool
+    // rows, readable as the model calls are.
+    tenantRoute(api, { credentials: ["application"], scopes: "never" }, {
+        method: "get",
+        path: "/v1/sessions/{sessionId}/calls/tool",
+        tags: ["Sessions"],
+        summary: "Page a session's tool calls",
+        request: { params: sessionId, query: toolCallsQuery },
+        responses: {
+            200: {
+                description: "Each tool call in the order it was first sent, with its status and sends",
+                content: { "application/json": { schema: ToolCallsPage } },
+            },
+        },
+    }, 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"))));
+    });
+    // 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.
+    tenantRoute(api, { credentials: ["application"], scopes: "never" }, {
+        method: "get",
+        path: "/v1/sessions/{sessionId}/turns/{turnId}/trace",
+        tags: ["Sessions"],
+        summary: "Read a turn's trace",
+        description: "The turn's spans as OTLP/HTTP JSON (`resourceSpans`), as the Runtime posts them to an OTLP collector: a root span for the turn, a span for each model, tool and egress crossing, ids derived so every read agrees. Post it to a collector's `/v1/traces` to backfill. A turn still running has no root span yet; a turn the session never had has no spans.",
+        request: { params: sessionId.extend({ turnId: z.string() }) },
+        responses: {
+            200: {
+                description: "The turn's spans",
+                content: { "application/json": { schema: TurnTrace } },
+            },
+        },
+    }, async (c) => {
+        requirePrincipal(c.get("scope"));
+        const ctx = c.env.tenant;
+        const id = c.req.param("sessionId");
+        const turnId = c.req.param("turnId");
+        const events = await readStoreOf(ctx).turnEvents(id, turnId, readAccess(c.get("scope")));
+        return jsonResponse(200, await turnTrace(ctx, id, turnId, events));
+    });
     const exportQuery = z
         .object({
         after: z.string().optional(),

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

@@ -2,16 +2,17 @@ import { RESPONSE_ALREADY_SENT } from "@hono/node-server/utils/response";
 import { z } from "zod";
 import { PutAgentRequestSchema, 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 { accessOf, requireApplication } from "../../../tenant/auth.js";
 import { command } from "../../../tenant/commands.js";
 import { loadSession, sessionOf } from "../../../tenant/context.js";
 import { fail } from "../../../tenant/http.js";
-import { sandboxGrantsOf, sandboxRouteDeps } from "../../../tenant/sandboxes.js";
+import { environmentGrantsOf, sandboxRouteDeps } from "../../../tenant/environments.js";
 import { readHistory, requestCursor, streamHolderOf, streamSessionEvents } from "../../../tenant/session-streams.js";
 import { listAgentsPublic, listDefinitions, listSessions, putDefinition, putSession, sessionView, } from "../../../tenant/sessions.js";
 import { readJson } from "../body.js";
-import { tenantRoute } from "../define.js";
+import { TraceHeaders, tenantRoute } from "../define.js";
 import { pageQuery, sessionPage, sessionPageQuery, parseQuery } from "./reads.js";
 import { jsonResponse } from "../respond.js";
 const OWN_SESSIONS = {
@@ -52,12 +53,16 @@ export function sessionRoutes(api) {
         tags: ["Sessions"],
         summary: "Send a command to a session",
         description: "A message starts a turn; the others answer what the session waits on, or cancel. Idempotent on the command's `idempotencyKey`.",
-        request: { params: sessionId, body: body(SessionCommand) },
+        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" },
         },
-    }, async (c) => jsonResponse(200, await command(c.env.tenant, c.req.param("sessionId"), SessionCommandSchema.parse(await readJson(c.req.raw)), c.get("scope"))));
+    }, 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"],
@@ -119,8 +124,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 = sandboxGrantsOf(scope);
-        const session = await putSession(ctx, c.req.param("sessionId"), request, accessOf(scope), grants === undefined ? {} : { sandboxGrants: grants });
+        const grants = environmentGrantsOf(scope);
+        const session = await putSession(ctx, c.req.param("sessionId"), request, accessOf(scope), grants === undefined ? {} : { environmentGrants: grants });
         return jsonResponse(200, await ctx.store.tx((t) => sessionView(t, session)));
     });
     tenantRoute(api, OWN_SESSIONS, {

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

@@ -1,7 +1,8 @@
 import { z } from "zod";
-import { ModelUsageQuerySchema, PutModelBudgetsRequestSchema, PutHostModelRequestSchema, PutTenantSandboxRequestSchema, ResetTenantRequestSchema, SeedTenantConfigRequestSchema, SelectHostModelRequestSchema, } from "@nylorun/core/contracts";
-import { HostModelCatalog, HostModelView, ListProvidersResponse, ModelBudgets, ModelUsageTotals, PutModelBudgetsRequest, PutHostModelRequest, PutTenantSandboxRequest, ResetTenantRequest, ResetTenantResponse, SeedTenantConfigRequest, SeedTenantConfigResponse, SelectHostModelRequest, TenantSandboxView, TenantStatus, } from "../../components.js";
+import { ModelUsageQuerySchema, PutModelBudgetsRequestSchema, PutToolPolicyRequestSchema, PutHostModelRequestSchema, PutTenantEnvironmentsRequestSchema, ResetTenantRequestSchema, SeedTenantConfigRequestSchema, SelectHostModelRequestSchema, } from "@nylorun/core/contracts";
+import { HostModelCatalog, HostModelView, ListProvidersResponse, ModelBudgets, ModelUsageTotals, PutModelBudgetsRequest, PutToolPolicyRequest, ToolPolicy, PutHostModelRequest, PutTenantEnvironmentsRequest, ResetTenantRequest, ResetTenantResponse, SeedTenantConfigRequest, SeedTenantConfigResponse, SelectHostModelRequest, TenantSandboxView, TenantStatus, } from "../../components.js";
 import { periodStart } from "../../../gates/meter.js";
+import { readToolPolicy, TOOL_POLICY_SETTING } from "../../../gates/policy.js";
 import { hostModelCatalog } from "../../../model/catalog.js";
 import { sandboxConfigErrors } from "../../../sandbox/resolve.js";
 import { effectiveSandboxConfig, readSandboxConfig, writeSandboxConfig, } from "../../../sandbox/tenant-config.js";
@@ -15,7 +16,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/sandboxes.js";
+import { rearmPodTimers } from "../../../tenant/environments.js";
 /** Every Management API route (`/v1/tenant/*`): a management key, acting as itself (protocol 8). */
 const MANAGEMENT = { credentials: ["management"], scopes: "never" };
 const json = (schema, description) => ({
@@ -105,7 +106,7 @@ export function tenantRoutes(api) {
         path: "/v1/tenant/reset",
         tags: ["Tenant"],
         summary: "Reset the Tenant",
-        description: "Deletes its sessions, its sandboxes, or both, after draining or cancelling the turns in progress. The Tenant stays open.",
+        description: "Deletes its sessions, its Environments (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) => {
@@ -114,7 +115,7 @@ export function tenantRoutes(api) {
         await drain(ctx, request.activeWork, 30_000);
         // 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 !== "sandboxes";
+        const sessionsReset = request.scope !== "environments";
         await resetTenant({
             store: ctx.store,
             sandbox: ctx.sandbox,
@@ -158,20 +159,20 @@ export function tenantRoutes(api) {
         method: "get",
         path: "/v1/tenant/sandbox",
         tags: ["Tenant"],
-        summary: "Get the Tenant's sandbox configuration",
+        summary: "Get the Tenant's sandbox backend and Environment 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 sandbox configuration",
-        description: "What a session gets when it names no sandbox, and the limits every session's sandbox must fit.",
-        request: { body: body(PutTenantSandboxRequest) },
+        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`).",
+        request: { body: body(PutTenantEnvironmentsRequest) },
         responses: { 200: json(TenantSandboxView, "The configuration now in force") },
     }, async (c) => {
         const ctx = c.env.tenant;
-        const { requestId: _requestId, ...config } = PutTenantSandboxRequestSchema.parse(await readJson(c.req.raw));
+        const { requestId: _requestId, ...config } = PutTenantEnvironmentsRequestSchema.parse(await readJson(c.req.raw));
         const errors = sandboxConfigErrors(effectiveSandboxConfig(config));
         if (errors.length > 0)
             fail(400, errors.join(" "));
@@ -236,6 +237,27 @@ export function tenantRoutes(api) {
         });
         return jsonResponse(200, { budgets: rows.map(budgetView) });
     });
+    tenantRoute(api, MANAGEMENT, {
+        method: "get",
+        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") },
+    }, async (c) => jsonResponse(200, await c.env.tenant.store.tx((t) => readToolPolicy(t))));
+    tenantRoute(api, MANAGEMENT, {
+        method: "put",
+        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.",
+        request: { body: body(PutToolPolicyRequest) },
+        responses: { 200: json(ToolPolicy, "The policy now in force") },
+    }, async (c) => {
+        const { rules } = PutToolPolicyRequestSchema.parse(await readJson(c.req.raw));
+        const policy = { rules, updatedAt: new Date().toISOString() };
+        await c.env.tenant.store.tx((t) => t.putSetting(TOOL_POLICY_SETTING, JSON.stringify(policy)));
+        return jsonResponse(200, policy);
+    });
     tenantRoute(api, MANAGEMENT, {
         method: "get",
         path: "/v1/tenant/providers",