@nylorun/runtime 0.23.0-beta → 0.25.0-beta

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,19 @@ 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" },
+            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.",
+            },
         },
-    }, 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"],
@@ -82,10 +90,17 @@ export function sessionRoutes(api) {
         path: "/v1/agents/{agentId}",
         tags: ["Agents"],
         summary: "Put an agent's definition",
-        request: { params: z.object({ agentId: z.string() }), body: body(PutAgentRequest) },
-        responses: { 200: json(PutAgentResponse, "The definition, stored") },
+        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))));
+        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" }));
     });
     tenantRoute(api, OWN_SESSIONS, {
         method: "get",
@@ -119,8 +134,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,13 +1,15 @@
 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, PutModelInputsRequestSchema, PutHostModelRequestSchema, PutTenantEnvironmentsRequestSchema, ResetTenantRequestSchema, SeedTenantConfigRequestSchema, SelectHostModelRequestSchema, } from "@nylorun/core/contracts";
+import { HostModelCatalog, HostModelView, ListProvidersResponse, ModelBudgets, ModelInputsView, ModelUsageTotals, PutModelBudgetsRequest, PutToolPolicyRequest, PutModelInputsRequest, ToolPolicy, PutHostModelRequest, PutTenantEnvironmentsRequest, ResetTenantRequest, ResetTenantResponse, SeedTenantConfigRequest, SeedTenantConfigResponse, SelectHostModelRequest, TenantSandboxView, TenantStatus, } from "../../components.js";
 import { periodStart } from "../../../gates/meter.js";
-import { hostModelCatalog } from "../../../model/catalog.js";
+import { readToolPolicy, TOOL_POLICY_SETTING } from "../../../gates/policy.js";
+import { addableInputs, capabilitiesOf, inputsError } from "../../../model/capabilities.js";
+import { catalogModel, hostModelCatalog } from "../../../model/catalog.js";
 import { sandboxConfigErrors } from "../../../sandbox/resolve.js";
 import { effectiveSandboxConfig, readSandboxConfig, writeSandboxConfig, } from "../../../sandbox/tenant-config.js";
 import { fail } from "../../../tenant/http.js";
 import { clearObservers } from "../../../tenant/session-streams.js";
-import { usesFixtureModel } from "../../../tenant/model-setting.js";
+import { readAddedInputs, usesFixtureModel, writeAddedInputs } from "../../../tenant/model-setting.js";
 import { resetTenant } from "../../../tenant/reset.js";
 import { clearWork, drain } from "../../../tenant/scheduler.js";
 import { buildTenantStatus, harnessStatusOf, seedTenantConfig } from "../../../tenant/status.js";
@@ -15,7 +17,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 +107,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 +116,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,
@@ -149,29 +151,56 @@ export function tenantRoutes(api) {
         path: "/v1/tenant/models",
         tags: ["Tenant"],
         summary: "List model providers and models",
-        responses: { 200: json(HostModelCatalog, "Provider and model names") },
+        description: "Each model says what it reads (`inputs`: its catalog's inputs and those the operator added) and what may be added (`addableInputs`).",
+        responses: { 200: json(HostModelCatalog, "Provider and model names, and their inputs") },
     }, async (c) => {
-        c.env.tenant;
-        return jsonResponse(200, hostModelCatalog());
+        const added = await c.env.tenant.store.tx((t) => readAddedInputs(t));
+        return jsonResponse(200, hostModelCatalog(added));
+    });
+    tenantRoute(api, MANAGEMENT, {
+        method: "put",
+        path: "/v1/tenant/models/inputs",
+        tags: ["Tenant"],
+        summary: "Set what a catalog model reads",
+        description: "Replaces the inputs the operator added to one catalog model (Tenant setting `model.inputs`): only those in its `addableInputs`, which its provider API carries. Its catalog's own inputs always stay; an empty list removes the additions. A message naming a file the Tenant's model does not read is refused with `422 attachment_unsupported`. A custom endpoint sets `settings.inputs` on `PUT /v1/tenant/model` instead.",
+        request: { body: body(PutModelInputsRequest) },
+        responses: { 200: json(ModelInputsView, "What the model reads now") },
+    }, async (c) => {
+        const { provider, model, inputs } = PutModelInputsRequestSchema.parse(await readJson(c.req.raw));
+        if (provider === "custom")
+            fail(400, "A custom endpoint's inputs are its settings: set settings.inputs on PUT /v1/tenant/model.");
+        const found = catalogModel(provider, model);
+        if (!found)
+            fail(400, `Unknown model ${provider}/${model}.`);
+        const refused = inputsError(found, inputs);
+        if (refused)
+            fail(400, refused);
+        const added = inputs.filter((input) => addableInputs(found).includes(input));
+        await c.env.tenant.store.tx((t) => writeAddedInputs(t, `${provider}/${model}`, added));
+        return jsonResponse(200, {
+            provider,
+            model,
+            inputs: capabilitiesOf(found, added).inputs,
+        });
     });
     tenantRoute(api, MANAGEMENT, {
         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 +265,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",

package/dist/api/inbound-files.d.ts

@@ -0,0 +1,65 @@
+/**
+ * Files that arrive inside a message (multimodal messages, M7): the AG-UI and A2A endpoints take
+ * a file's bytes inline (base64), store them as an artifact of the message's session, and send
+ * the message as `parts` through the session's normal command path, so every check a message
+ * with file parts meets applies. A file by URL is refused: the Runtime fetches nothing.
+ *
+ * A retried message (the same idempotency key) reuses the files the first one stored rather than
+ * storing them again, so it replays the first turn instead of conflicting with it. A message the
+ * Runtime refuses takes the files it stored with it (`discardFiles`).
+ */
+import type { MessagePart } from "@nylorun/core/contracts";
+import { type ArtifactAccess } from "../artifacts/service.js";
+import type { TenantContext } from "../tenant/context.js";
+/** The largest file a message may carry inline, decoded. */
+export declare const INLINE_FILE_MAX_BYTES: number;
+/**
+ * The request body of an endpoint that takes inline files: one file at the cap, base64-encoded
+ * (a third larger), and the rest of the request.
+ */
+export declare const INLINE_BODY_MAX_BYTES: number;
+/** A file sent inline: its name, declared media type and base64 bytes. */
+export interface InlineFile {
+    readonly name: string;
+    readonly mediaType: string;
+    /** The bytes, base64 (standard or URL-safe alphabet). */
+    readonly data: string;
+}
+/** One part of an inbound message: text, a file sent inline, or an artifact the Runtime holds. */
+export type InboundPart = {
+    readonly type: "text";
+    readonly text: string;
+} | ({
+    readonly type: "inline";
+} & InlineFile) | {
+    readonly type: "artifact";
+    readonly artifactId: string;
+};
+/** The 400 for a file sent by URL. */
+export declare function refuseUrl(): never;
+/** A name for a file its client did not name: its place in the message and its type's extension. */
+export declare function inlineFileName(mediaType: string, index: number): string;
+/**
+ * Stores `file` as a new artifact of `sessionId`, within the inline cap and the Tenant's
+ * artifact limits: `400` for bad base64 or a bad media type, `413 limit_exceeded` past a limit.
+ */
+export declare function storeInlineFile(ctx: TenantContext, sessionId: string, file: InlineFile, access: ArtifactAccess): Promise<{
+    artifactId: string;
+    version: number;
+}>;
+/**
+ * The parts of the message the session already took under `idempotencyKey`, when it took one
+ * with parts: a retry sends the same files again.
+ */
+export declare function priorParts(ctx: TenantContext, sessionId: string, idempotencyKey: string): Promise<readonly MessagePart[] | undefined>;
+/**
+ * A message's parts, its inline files stored as artifacts of `sessionId` (or, on a retry, the
+ * first message's files in their place, by position). `stored` lists the artifacts this call
+ * created, for `discardFiles` when the message is refused.
+ */
+export declare function messageParts(ctx: TenantContext, sessionId: string, idempotencyKey: string, inbound: readonly InboundPart[], access: ArtifactAccess): Promise<{
+    parts: MessagePart[];
+    stored: string[];
+}>;
+/** Deletes the artifacts a refused message stored; one already gone is no error. */
+export declare function discardFiles(ctx: TenantContext, artifactIds: readonly string[], access: ArtifactAccess): Promise<void>;

package/dist/api/inbound-files.js

@@ -0,0 +1,115 @@
+import { MAX_MESSAGE_PARTS } from "@nylorun/core/contracts";
+import { commandKey } from "../core/flow-host.js";
+import { extensionFor, normalizeContentType } from "../artifacts/media-types.js";
+import { deleteArtifact, uploadArtifact } from "../artifacts/service.js";
+import { fail } from "../tenant/http.js";
+/** The largest file a message may carry inline, decoded. */
+export const INLINE_FILE_MAX_BYTES = 20 * 1024 * 1024;
+/**
+ * The request body of an endpoint that takes inline files: one file at the cap, base64-encoded
+ * (a third larger), and the rest of the request.
+ */
+export const INLINE_BODY_MAX_BYTES = 28 * 1024 * 1024;
+const BASE64 = /^[A-Za-z0-9+/_-]*={0,2}$/;
+/** The 400 for a file sent by URL. */
+export function refuseUrl() {
+    return fail(400, "File URLs are not fetched yet; send the bytes inline", {
+        code: "invalid_request",
+    });
+}
+/** A name for a file its client did not name: its place in the message and its type's extension. */
+export function inlineFileName(mediaType, index) {
+    const extension = extensionFor(mediaType);
+    return `file-${index + 1}${extension ? `.${extension}` : ""}`;
+}
+/**
+ * Stores `file` as a new artifact of `sessionId`, within the inline cap and the Tenant's
+ * artifact limits: `400` for bad base64 or a bad media type, `413 limit_exceeded` past a limit.
+ */
+export async function storeInlineFile(ctx, sessionId, file, access) {
+    const data = file.data.replace(/\s+/gu, "");
+    if (!BASE64.test(data) || data.length % 4 === 1)
+        fail(400, `File "${file.name}" is not valid base64`, { code: "invalid_request" });
+    // Three bytes per four characters, before decoding a byte.
+    if (Math.floor((data.length * 3) / 4) > INLINE_FILE_MAX_BYTES + 2)
+        fail(413, `A file sent inline may hold at most ${INLINE_FILE_MAX_BYTES} bytes`, {
+            code: "limit_exceeded",
+            details: { limitBytes: INLINE_FILE_MAX_BYTES },
+        });
+    // Node's base64 decoder reads both alphabets.
+    const bytes = Buffer.from(data, "base64");
+    if (bytes.byteLength > INLINE_FILE_MAX_BYTES)
+        fail(413, `A file sent inline may hold at most ${INLINE_FILE_MAX_BYTES} bytes`, {
+            code: "limit_exceeded",
+            details: { limitBytes: INLINE_FILE_MAX_BYTES },
+        });
+    if (bytes.byteLength === 0)
+        fail(400, `File "${file.name}" is empty`, { code: "invalid_request" });
+    const contentType = normalizeContentType(file.mediaType) ??
+        fail(400, `File "${file.name}" has no valid media type`, { code: "invalid_request" });
+    const { artifact, version } = await uploadArtifact(ctx, {
+        name: file.name,
+        contentType,
+        sessionId,
+        declaredBytes: bytes.byteLength,
+        source: "upload",
+    }, new Uint8Array(bytes.buffer, bytes.byteOffset, bytes.byteLength), access);
+    return { artifactId: artifact.artifactId, version: version.version };
+}
+/**
+ * The parts of the message the session already took under `idempotencyKey`, when it took one
+ * with parts: a retry sends the same files again.
+ */
+export async function priorParts(ctx, sessionId, idempotencyKey) {
+    const prior = await ctx.store.tx((t) => t.get("commands", commandKey(sessionId, idempotencyKey)));
+    return prior?.command.type === "message" && Array.isArray(prior.command.parts)
+        ? prior.command.parts
+        : undefined;
+}
+/**
+ * A message's parts, its inline files stored as artifacts of `sessionId` (or, on a retry, the
+ * first message's files in their place, by position). `stored` lists the artifacts this call
+ * created, for `discardFiles` when the message is refused.
+ */
+export async function messageParts(ctx, sessionId, idempotencyKey, inbound, access) {
+    const parts = inbound.filter((part) => part.type !== "text" || part.text !== "");
+    if (parts.length > MAX_MESSAGE_PARTS)
+        fail(400, `A message may carry at most ${MAX_MESSAGE_PARTS} parts`, { code: "invalid_request" });
+    const prior = parts.some((part) => part.type === "inline")
+        ? (await priorParts(ctx, sessionId, idempotencyKey))?.filter((part) => part.type === "file")
+        : undefined;
+    const out = [];
+    const stored = [];
+    let files = 0;
+    try {
+        for (const part of parts) {
+            if (part.type === "text") {
+                out.push({ type: "text", text: part.text });
+                continue;
+            }
+            const index = files++;
+            if (part.type === "artifact") {
+                out.push({ type: "file", artifactId: part.artifactId });
+                continue;
+            }
+            const again = prior?.[index];
+            if (again) {
+                out.push(again);
+                continue;
+            }
+            const file = await storeInlineFile(ctx, sessionId, part, access);
+            stored.push(file.artifactId);
+            out.push({ type: "file", artifactId: file.artifactId, version: file.version });
+        }
+    }
+    catch (error) {
+        await discardFiles(ctx, stored, access);
+        throw error;
+    }
+    return { parts: out, stored };
+}
+/** Deletes the artifacts a refused message stored; one already gone is no error. */
+export async function discardFiles(ctx, artifactIds, access) {
+    for (const id of artifactIds)
+        await deleteArtifact(ctx, id, access).catch(() => undefined);
+}

package/dist/api/openapi.js

@@ -135,6 +135,8 @@ const RUNTIME_TAGS = [
             "GET /v1/sessions/{sessionId}/manifest",
             "GET /v1/sessions/{sessionId}/usage",
             "GET /v1/sessions/{sessionId}/calls/model",
+            "GET /v1/sessions/{sessionId}/calls/tool",
+            "GET /v1/sessions/{sessionId}/turns/{turnId}/trace",
             "POST /v1/sessions/{sessionId}/sandbox/{tool}",
         ],
     },
@@ -156,17 +158,39 @@ const RUNTIME_TAGS = [
         operations: ["GET /v1/a2a/agents/{agentId}/card", "POST /v1/a2a/agents/{agentId}"],
     },
     {
-        name: "Sandboxes",
-        group: "Sandboxes",
-        description: "Isolated machines an agent works in: create or find one, watch its lifecycle, stop, reset or delete it. In `@nylorun/agents`.",
+        name: "Environments",
+        group: "Environments",
+        description: "Where sessions run: one sandbox (a virtual workspace, a pod with its own volume, or none) made from an environment manifest or inline fields and never changed after that, and one vault of secrets for its shell, MCP servers and HTTP tools. Create or find one, watch its lifecycle, stop, reset or delete it, and write its secrets. In `@nylorun/agents`.",
         operations: [
-            "PUT /v1/sandboxes/{sandboxId}",
-            "GET /v1/sandboxes",
-            "GET /v1/sandboxes/{sandboxId}",
-            "GET /v1/sandboxes/{sandboxId}/events",
-            "POST /v1/sandboxes/{sandboxId}/stop",
-            "POST /v1/sandboxes/{sandboxId}/reset",
-            "DELETE /v1/sandboxes/{sandboxId}",
+            "PUT /v1/environments/{environmentId}",
+            "GET /v1/environments",
+            "GET /v1/environments/{environmentId}",
+            "GET /v1/environments/{environmentId}/events",
+            "POST /v1/environments/{environmentId}/stop",
+            "POST /v1/environments/{environmentId}/reset",
+            "DELETE /v1/environments/{environmentId}",
+            "GET /v1/environments/{environmentId}/secrets",
+            "GET /v1/environments/{environmentId}/secrets/{name}",
+            "PUT /v1/environments/{environmentId}/secrets/{name}",
+            "DELETE /v1/environments/{environmentId}/secrets/{name}",
+            "POST /v1/environments/{environmentId}/snapshot",
+            "POST /v1/environments/{environmentId}/restore",
+            "POST /v1/environments/{environmentId}/fork",
+            "GET /v1/environments/{environmentId}/versions",
+            "DELETE /v1/environments/{environmentId}/versions/{version}",
+        ],
+    },
+    {
+        name: "Environment manifests",
+        group: "Environments",
+        description: "Named, versioned definitions of a kind of Environment, saved like agents (protocol 14). Save one with a plan first (`?dryRun=true`) and `If-Match`; an Environment is made from one version and keeps it, so a save changes no Environment. In `@nylorun/agents`.",
+        operations: [
+            "PUT /v1/environment-manifests/{name}",
+            "GET /v1/environment-manifests",
+            "GET /v1/environment-manifests/{name}",
+            "GET /v1/environment-manifests/{name}/versions",
+            "GET /v1/environment-manifests/{name}/versions/{version}",
+            "DELETE /v1/environment-manifests/{name}",
         ],
     },
     {
@@ -221,9 +245,10 @@ const MANAGEMENT_TAGS = [
     },
     {
         name: "Models",
-        description: "Model providers, their credentials, the model the Tenant uses, what it spent, every model call for export, and the budgets that cap it. `admin.models`.",
+        description: "Model providers, their credentials, the model the Tenant uses, what each model reads, what it spent, every model call for export, and the budgets that cap it. `admin.models`.",
         operations: [
             "GET /v1/tenant/models",
+            "PUT /v1/tenant/models/inputs",
             "GET /v1/tenant/providers",
             "GET /v1/tenant/model",
             "PUT /v1/tenant/model",
@@ -235,23 +260,18 @@ const MANAGEMENT_TAGS = [
         ],
     },
     {
-        name: "Vaults",
-        description: "The installation's and each person's credentials for agents' tools: API keys, bound to the URL they are sent to. Sessions attach a vault by id. `admin.vaults`.",
-        operations: [
-            "POST /v1/tenant/vaults",
-            "GET /v1/tenant/vaults",
-            "GET /v1/tenant/vaults/{vaultId}",
-            "DELETE /v1/tenant/vaults/{vaultId}",
-            "POST /v1/tenant/vaults/{vaultId}/credentials",
-            "GET /v1/tenant/vaults/{vaultId}/credentials",
-            "GET /v1/tenant/vaults/{vaultId}/credentials/{credentialId}",
-            "POST /v1/tenant/vaults/{vaultId}/credentials/{credentialId}",
-            "DELETE /v1/tenant/vaults/{vaultId}/credentials/{credentialId}",
-        ],
+        name: "Tool policy",
+        description: "The rules the Tool Gate applies to every MCP and HTTP tool call of every harness: refuse it, hold it for a person's approval, or run it. `admin.toolPolicy`.",
+        operations: ["GET /v1/tenant/tool-policy", "PUT /v1/tenant/tool-policy"],
+    },
+    {
+        name: "Credential coverage",
+        description: "Which secret of an Environment each of an agent's MCP servers and HTTP tools would get, before a session opens. The secrets themselves are written on the Runtime API. `admin.coverage`.",
+        operations: ["POST /v1/tenant/credential-coverage"],
     },
     {
         name: "MCP servers",
-        description: "See a remote MCP server's tools before an agent names it, with the installation vault's credential for its URL: their model names, sizes and annotations, or that it needs a person's sign-in. `admin.mcp`.",
+        description: "See a remote MCP server's tools before an agent names it, with an Environment's credential for its URL: their model names, sizes and annotations, or that it needs a person's sign-in. `admin.mcp`.",
         operations: ["POST /v1/tenant/mcp/preview"],
     },
     {
@@ -265,7 +285,7 @@ const MANAGEMENT_TAGS = [
     },
     {
         name: "Settings",
-        description: "The Tenant's sandbox and artifact settings. `admin.settings`.",
+        description: "The Tenant's sandbox backend, Environment and artifact settings. `admin.settings`.",
         operations: [
             "GET /v1/tenant/sandbox",
             "PUT /v1/tenant/sandbox",
@@ -368,11 +388,11 @@ function documents() {
     built = {
         runtime: document(all, RUNTIME_TAGS, {
             title: "Nylorun Runtime API",
-            description: "For developers: agents, sessions (with AG-UI and A2A), sandboxes and artifacts, through `@nylorun/agents`. Every Tenant serves it on its one URL, beside the Management API (`/openapi/management.json`). Every request sends `Nylorun-Protocol`. Who may call each operation is its `security` and its `x-nylorun-credentials` and `x-nylorun-scopes` (the subject scopes that reach it) fields: an application key (servers) or a trusted issuer's token (browsers and apps).",
+            description: "For developers: agents, sessions (with AG-UI and A2A), Environments and artifacts, through `@nylorun/agents`. Every Tenant serves it on its one URL, beside the Management API (`/openapi/management.json`). Every request sends `Nylorun-Protocol`. Who may call each operation is its `security` and its `x-nylorun-credentials` and `x-nylorun-scopes` (the subject scopes that reach it) fields: an application key (servers) or a trusted issuer's token (browsers and apps).",
         }),
         management: document(all, MANAGEMENT_TAGS, {
             title: "Nylorun Management API",
-            description: "For operators: the Tenant's models, vaults, signing keys, settings and application keys, at `/v1/tenant/*` on the Tenant's URL, through `@nylorun/admin`. Every operation takes a management key, acting as itself: never for a subject and never from a browser. Management keys are issued only on the Tenant's machine (`nylorun key put <id> --management`) or from `NYLORUN_MANAGEMENT_KEY_FILE`.",
+            description: "For operators: the Tenant's models, vaults, signing keys, settings and application keys, at `/v1/tenant/*` on the Tenant's URL, through `@nylorun/admin`. Every operation takes a management key, acting as itself: never for a subject and never from a browser. Management keys are issued only on the Tenant's machine (`nylorun tenant keys put <id> --management`) or from `NYLORUN_MANAGEMENT_KEY_FILE`.",
         }),
     };
     return built;