@nylorun/runtime 0.24.0-beta → 0.25.0-beta

package/dist/api/components.js

@@ -5,7 +5,7 @@
  * global registry.
  */
 import { z } from "zod";
-import { SessionListItemSchema, ModelCallSchema, SessionPageSchema, SessionManifestViewSchema, HistoryPageSchema, SessionUsageTotalsSchema, ModelCallsPageSchema, ModelCallExportPageSchema, EnvironmentPageSchema, ToolCallSchema, ToolCallsPageSchema, TurnTraceSchema, JwksSchema, SigningKeyListSchema, SigningKeyViewSchema, RotateSigningKeysRequestSchema, RevokeSigningKeyRequestSchema, MeResponseSchema, TenantStatusSchema, ResetTenantRequestSchema, ResetTenantResponseSchema, SeedTenantConfigRequestSchema, SeedTenantConfigResponseSchema, HostModelCatalogSchema, TenantSandboxViewSchema, ModelUsageTotalsSchema, ModelBudgetsSchema, PutModelBudgetsRequestSchema, ToolPolicySchema, PutToolPolicyRequestSchema, PutTenantEnvironmentsRequestSchema, ListProvidersResponseSchema, HostModelViewSchema, PutHostModelRequestSchema, SelectHostModelRequestSchema, PutEnvironmentSecretRequestSchema, EnvironmentSecretViewSchema, ListEnvironmentSecretsResponseSchema, McpPreviewRequestSchema, McpPreviewSchema, CredentialCoverageRequestSchema, CredentialCoverageSchema, DeletedResponseSchema, ListAgentsResponseSchema, ListPublicAgentsResponseSchema, ListSessionsResponseSchema, LiveEventSchema, PutAgentRequestSchema, PutAgentResponseSchema, PutSessionRequestSchema, SessionItemsResponseSchema, SessionViewSchema, StreamClosedFrameSchema, AcceptedResponseSchema, SandboxToolOutcomeSchema, PutEnvironmentRequestSchema, EnvironmentViewSchema, EnvironmentSnapshotSchema, RestoreEnvironmentRequestSchema, EnvironmentRestoreSchema, EnvironmentVersionsSchema, ListEnvironmentsResponseSchema, DeleteEnvironmentResponseSchema, ListEnvironmentEventsResponseSchema, ArtifactViewSchema, ArtifactListItemSchema, ArtifactPageSchema, ArtifactVersionViewSchema, ListArtifactsResponseSchema, UploadArtifactResponseSchema, DefinitionFileViewSchema, DeleteArtifactResponseSchema, CreateArtifactLinkRequestSchema, ArtifactLinkSchema, PutTenantArtifactsRequestSchema, TenantArtifactsViewSchema, ArtifactTreeSchema, ArtifactDiffSchema, SessionCommandSchema, ListOperatorKeysResponseSchema, PutOperatorKeyResponseSchema, DeleteOperatorKeyResponseSchema, OperatorKeySchema, ProtocolRejectedResponseSchema, RejectedResponseSchema, EVENT_SCHEMAS, EVENT_TYPES, } from "@nylorun/core/contracts";
+import { EnvironmentManifestSchema, EnvironmentSecretSlotsSchema, DeleteEnvironmentManifestResponseSchema, EnvironmentManifestPlanSchema, EnvironmentManifestVersionsSchema, EnvironmentManifestViewSchema, ListEnvironmentManifestsResponseSchema, PutEnvironmentManifestRequestSchema, PutEnvironmentSecretValueRequestSchema, SaveEnvironmentManifestResponseSchema, SessionListItemSchema, ModelCallSchema, SessionPageSchema, SessionManifestViewSchema, HistoryPageSchema, SessionUsageTotalsSchema, ModelCallsPageSchema, ModelCallExportPageSchema, EnvironmentPageSchema, ToolCallSchema, ToolCallsPageSchema, TurnTraceSchema, JwksSchema, SigningKeyListSchema, SigningKeyViewSchema, RotateSigningKeysRequestSchema, RevokeSigningKeyRequestSchema, MeResponseSchema, TenantStatusSchema, ResetTenantRequestSchema, ResetTenantResponseSchema, SeedTenantConfigRequestSchema, SeedTenantConfigResponseSchema, HostModelCatalogSchema, TenantSandboxViewSchema, ModelUsageTotalsSchema, ModelBudgetsSchema, PutModelBudgetsRequestSchema, ToolPolicySchema, PutToolPolicyRequestSchema, PutModelInputsRequestSchema, ModelInputsViewSchema, PutTenantEnvironmentsRequestSchema, ListProvidersResponseSchema, HostModelViewSchema, PutHostModelRequestSchema, SelectHostModelRequestSchema, PutEnvironmentSecretRequestSchema, EnvironmentSecretViewSchema, ListEnvironmentSecretsResponseSchema, McpPreviewRequestSchema, McpPreviewSchema, CredentialCoverageRequestSchema, CredentialCoverageSchema, DeletedResponseSchema, ListAgentsResponseSchema, ListPublicAgentsResponseSchema, ListSessionsResponseSchema, LiveEventSchema, PutAgentRequestSchema, PutAgentResponseSchema, PutSessionRequestSchema, SessionItemsResponseSchema, SessionViewSchema, StreamClosedFrameSchema, AcceptedResponseSchema, SandboxToolOutcomeSchema, PutEnvironmentRequestSchema, EnvironmentViewSchema, EnvironmentSnapshotSchema, RestoreEnvironmentRequestSchema, ForkEnvironmentRequestSchema, EnvironmentForkPlanSchema, ForkEnvironmentResponseSchema, EnvironmentRestoreSchema, EnvironmentVersionsSchema, ListEnvironmentsResponseSchema, DeleteEnvironmentResponseSchema, ListEnvironmentEventsResponseSchema, ArtifactViewSchema, ArtifactListItemSchema, ArtifactPageSchema, ArtifactVersionViewSchema, ListArtifactsResponseSchema, UploadArtifactResponseSchema, DefinitionFileViewSchema, DeleteArtifactResponseSchema, CreateArtifactLinkRequestSchema, ArtifactLinkSchema, PutTenantArtifactsRequestSchema, TenantArtifactsViewSchema, ArtifactTreeSchema, ArtifactDiffSchema, SessionCommandSchema, ListOperatorKeysResponseSchema, PutOperatorKeyResponseSchema, DeleteOperatorKeyResponseSchema, OperatorKeySchema, ProtocolRejectedResponseSchema, RejectedResponseSchema, EVENT_SCHEMAS, EVENT_TYPES, } from "@nylorun/core/contracts";
 function named(id, schema) {
     return schema.meta({ id });
 }
@@ -18,9 +18,22 @@ export const DeleteOperatorKeyResponse = named("DeleteOperatorKeyResponse", Dele
 export const SandboxToolOutcome = named("SandboxToolOutcome", SandboxToolOutcomeSchema);
 export const PutEnvironmentRequest = named("PutEnvironmentRequest", PutEnvironmentRequestSchema);
 export const EnvironmentView = named("EnvironmentView", EnvironmentViewSchema);
+export const EnvironmentSecretSlots = named("EnvironmentSecretSlots", EnvironmentSecretSlotsSchema);
+export const EnvironmentManifest = named("EnvironmentManifest", EnvironmentManifestSchema);
+export const PutEnvironmentManifestRequest = named("PutEnvironmentManifestRequest", PutEnvironmentManifestRequestSchema);
+export const EnvironmentManifestView = named("EnvironmentManifestView", EnvironmentManifestViewSchema);
+export const EnvironmentManifestPlan = named("EnvironmentManifestPlan", EnvironmentManifestPlanSchema);
+export const SaveEnvironmentManifestResponse = named("SaveEnvironmentManifestResponse", SaveEnvironmentManifestResponseSchema);
+export const ListEnvironmentManifestsResponse = named("ListEnvironmentManifestsResponse", ListEnvironmentManifestsResponseSchema);
+export const EnvironmentManifestVersions = named("EnvironmentManifestVersions", EnvironmentManifestVersionsSchema);
+export const DeleteEnvironmentManifestResponse = named("DeleteEnvironmentManifestResponse", DeleteEnvironmentManifestResponseSchema);
+export const PutEnvironmentSecretValueRequest = named("PutEnvironmentSecretValueRequest", PutEnvironmentSecretValueRequestSchema);
 export const EnvironmentSnapshot = named("EnvironmentSnapshot", EnvironmentSnapshotSchema);
 export const RestoreEnvironmentRequest = named("RestoreEnvironmentRequest", RestoreEnvironmentRequestSchema);
 export const EnvironmentRestore = named("EnvironmentRestore", EnvironmentRestoreSchema);
+export const ForkEnvironmentRequest = named("ForkEnvironmentRequest", ForkEnvironmentRequestSchema);
+export const EnvironmentForkPlan = named("EnvironmentForkPlan", EnvironmentForkPlanSchema);
+export const ForkEnvironmentResponse = named("ForkEnvironmentResponse", ForkEnvironmentResponseSchema);
 export const EnvironmentVersions = named("EnvironmentVersions", EnvironmentVersionsSchema);
 export const ListEnvironmentsResponse = named("ListEnvironmentsResponse", ListEnvironmentsResponseSchema);
 export const DeleteEnvironmentResponse = named("DeleteEnvironmentResponse", DeleteEnvironmentResponseSchema);
@@ -72,6 +85,8 @@ export const ModelBudgets = named("ModelBudgets", ModelBudgetsSchema);
 export const PutModelBudgetsRequest = named("PutModelBudgetsRequest", PutModelBudgetsRequestSchema);
 export const ToolPolicy = named("ToolPolicy", ToolPolicySchema);
 export const PutToolPolicyRequest = named("PutToolPolicyRequest", PutToolPolicyRequestSchema);
+export const PutModelInputsRequest = named("PutModelInputsRequest", PutModelInputsRequestSchema);
+export const ModelInputsView = named("ModelInputsView", ModelInputsViewSchema);
 export const PutTenantEnvironmentsRequest = named("PutTenantEnvironmentsRequest", PutTenantEnvironmentsRequestSchema);
 export const ListProvidersResponse = named("ListProvidersResponse", ListProvidersResponseSchema);
 export const HostModelView = named("HostModelView", HostModelViewSchema);

package/dist/api/gate/keys.d.ts

@@ -1,7 +1,8 @@
 /**
  * The `keys` service's route on the gateway's listener (F4.2, `contract.ts`): one operation of
  * `Keys` per request, run with the vault key of the gateway's Tenant. Errors keep their status,
- * code and details. Logs the operation and its outcome, never an argument or a result.
+ * code and details. Logs the operation, its outcome and an internal failure's cause, never an
+ * argument or a result.
  */
 import type { Env, Hono, MiddlewareHandler } from "hono";
 import type { Logger } from "../../tenant/types.js";

package/dist/api/gate/keys.js

@@ -29,6 +29,13 @@ export function mountKeysRoutes(app, options) {
         }
         catch (error) {
             answer = { error: errorOf(error) };
+            // The caller sees only "The keys service failed": the cause is logged, never the args.
+            if (answer.error.status === 500)
+                options.logger.error("keys_request_failed", {
+                    operation,
+                    error: error?.message ?? String(error),
+                    stack: error?.stack,
+                });
         }
         options.logger.info("keys_request", {
             operation,

package/dist/api/gate/routes.js

@@ -20,6 +20,7 @@
 import { createHash } from "node:crypto";
 import { Hono } from "hono";
 import { bodyLimit } from "hono/body-limit";
+import { HTTPException } from "hono/http-exception";
 import { isTenantId } from "@nylorun/core/compatibility";
 import { MAX_MODEL_CALL_BYTES, MODEL_CALLS_PATH, ModelCallBodySchema, TENANT_HEADER, } from "../../gates/contract.js";
 import { InflightConflict, InflightStale } from "../../gates/inflight.js";
@@ -38,6 +39,18 @@ export function createGatesApp(options) {
     const app = new Hono();
     const maxSize = options.maxBodyBytes ?? MAX_MODEL_CALL_BYTES;
     const logger = options.logger ?? { info() { }, warn() { }, error() { } };
+    // Hono's default, but logged through the logger: never the body, which may hold secrets.
+    app.onError((error, c) => {
+        if (error instanceof HTTPException)
+            return error.getResponse();
+        logger.error("request_failed", {
+            method: c.req.method,
+            route: c.req.routePath,
+            error: error.message,
+            stack: error.stack,
+        });
+        return c.text("Internal Server Error", 500);
+    });
     app.get("/health", (c) => c.json({ status: "ok" }));
     app.get("/ready", async (c) => (await options.ready()) ? c.json({ ready: true }) : c.json({ ready: false }, 503));
     const bearerOf = (c) => /^Bearer (.+)$/.exec(c.req.header("authorization") ?? "")?.[1];

package/dist/api/http/app.js

@@ -13,6 +13,7 @@ import { jsonResponse, rejectionOf } from "./respond.js";
 import { accessRoutes } from "./routes/access.js";
 import { meRoutes } from "./routes/me.js";
 import { environmentRoutes } from "./routes/environments.js";
+import { environmentManifestRoutes } from "./routes/environment-manifests.js";
 import { artifactRoutes } from "./routes/artifacts.js";
 import { readRoutes } from "./routes/reads.js";
 import { sessionRoutes } from "./routes/sessions.js";
@@ -45,6 +46,7 @@ function build() {
     sessionRoutes(api);
     fileRoutes(api);
     environmentRoutes(api);
+    environmentManifestRoutes(api);
     artifactRoutes(api);
     tenantRoutes(api);
     keyRoutes(api);
@@ -56,13 +58,22 @@ function build() {
     a2aRoutes(api);
     api.notFound(routeNotFound);
     api.onError((error, c) => {
-        const { outgoing } = c.env;
+        const { outgoing, tenant } = c.env;
+        const rejection = rejectionOf(error);
+        // The client sees only `internal_error`: the operator's log has the cause. The route's
+        // pattern, not its path, and never the body, which may hold secrets.
+        if (rejection.status === 500)
+            tenant.config.logger.error("request_failed", {
+                method: c.req.method,
+                route: c.req.routePath,
+                error: error.message,
+                stack: error.stack,
+            });
         // Once a response has started, the rejection can only end it.
         if (outgoing.headersSent) {
             outgoing.end();
             return RESPONSE_ALREADY_SENT;
         }
-        const rejection = rejectionOf(error);
         return jsonResponse(rejection.status, rejection.body, rejection.headers);
     });
     readRoutes(api);

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

@@ -1,4 +1,4 @@
-/** The body as text. */
-export declare function readText(request: Request): Promise<string>;
+/** The body as text; past `maxBytes`, `413 Request too large`. */
+export declare function readText(request: Request, maxBytes?: number): Promise<string>;
 /** The body as JSON, before any schema. */
-export declare function readJson(request: Request): Promise<unknown>;
+export declare function readJson(request: Request, maxBytes?: number): Promise<unknown>;

package/dist/api/http/body.js

@@ -1,12 +1,12 @@
 /**
  * Request bodies of Tenant routes, read as the router they replace read them
- * (`tenant/http.ts`): at most 1 MiB, UTF-8, and a missing or malformed JSON body is
- * `400 Invalid JSON`.
+ * (`tenant/http.ts`): at most 1 MiB unless a route allows more (an endpoint that takes files
+ * inline), UTF-8, and a missing or malformed JSON body is `400 Invalid JSON`.
  */
 import { fail } from "../../tenant/http.js";
 const MAX_BODY_BYTES = 1024 * 1024;
-/** The body as text. */
-export async function readText(request) {
+/** The body as text; past `maxBytes`, `413 Request too large`. */
+export async function readText(request, maxBytes = MAX_BODY_BYTES) {
     if (request.body === null)
         return "";
     const chunks = [];
@@ -17,7 +17,7 @@ export async function readText(request) {
         if (done)
             break;
         bytes += value.byteLength;
-        if (bytes > MAX_BODY_BYTES) {
+        if (bytes > maxBytes) {
             await reader.cancel();
             fail(413, "Request too large");
         }
@@ -26,8 +26,8 @@ export async function readText(request) {
     return Buffer.concat(chunks).toString("utf8");
 }
 /** The body as JSON, before any schema. */
-export async function readJson(request) {
-    const text = await readText(request);
+export async function readJson(request, maxBytes = MAX_BODY_BYTES) {
+    const text = await readText(request, maxBytes);
     try {
         return JSON.parse(text);
     }

package/dist/api/http/routes/environment-manifests.d.ts

@@ -0,0 +1,9 @@
+/**
+ * Environment manifests (`/v1/environment-manifests/**`, protocol 14, D63): save, read, list and
+ * delete the named, versioned definitions Environments are made from. A save never changes an
+ * Environment. Reading needs what reading an Environment needs; saving and deleting need
+ * `environments:write`, from any client (Q12).
+ */
+import type { OpenAPIHono } from "@hono/zod-openapi";
+import type { TenantEnv } from "../app.js";
+export declare function environmentManifestRoutes(api: OpenAPIHono<TenantEnv>): void;

package/dist/api/http/routes/environment-manifests.js

@@ -0,0 +1,118 @@
+import { z } from "zod";
+import { isEnvironmentManifestName, PutEnvironmentManifestRequestSchema } from "@nylorun/core/contracts";
+import { DeleteEnvironmentManifestResponse, EnvironmentManifestPlan, EnvironmentManifestVersions, EnvironmentManifestView, ListEnvironmentManifestsResponse, PutEnvironmentManifestRequest, SaveEnvironmentManifestResponse, } from "../../components.js";
+import { fail } from "../../../tenant/http.js";
+import { deleteEnvironmentManifest, environmentManifestVersions, getEnvironmentManifest, listEnvironmentManifests, saveEnvironmentManifest, } from "../../../tenant/environment-manifests.js";
+import { readJson } from "../body.js";
+import { tenantRoute } from "../define.js";
+import { jsonResponse } from "../respond.js";
+const READ = {
+    credentials: ["application", "subject", "token"],
+    scopes: ["sessions:own", "environments:write"],
+};
+const WRITE = {
+    credentials: ["application", "subject", "token"],
+    scopes: ["environments:write"],
+};
+const json = (schema, description) => ({
+    description,
+    content: { "application/json": { schema } },
+});
+const namePath = z.object({
+    name: z.string().meta({ description: "The environment manifest's name, such as `analyst-box`" }),
+});
+function nameOf(value) {
+    if (!isEnvironmentManifestName(value))
+        return fail(400, "An environment manifest's name is 1-64 letters, digits, '.', '_' and '-', starting with a letter or digit");
+    return value;
+}
+function versionOf(value) {
+    const version = Number(value);
+    if (!Number.isInteger(version) || version < 1)
+        return fail(400, "version is a positive integer");
+    return version;
+}
+/** `If-Match: <version>` (or `"<version>"`), when sent. */
+function ifMatchOf(value) {
+    if (value === undefined || value.trim() === "")
+        return undefined;
+    const version = Number(value.trim().replace(/^W\//, "").replace(/^"|"$/g, ""));
+    if (!Number.isInteger(version) || version < 0)
+        return fail(400, "If-Match is the version you read: a whole number, 0 for none yet");
+    return version;
+}
+export function environmentManifestRoutes(api) {
+    tenantRoute(api, READ, {
+        method: "get",
+        path: "/v1/environment-manifests",
+        tags: ["Environment manifests"],
+        summary: "List environment manifests",
+        description: "Each manifest's latest version, by name, with how many Environments were made from it.",
+        responses: { 200: json(ListEnvironmentManifestsResponse, "The manifests") },
+    }, async (c) => jsonResponse(200, await listEnvironmentManifests(c.env.tenant)));
+    tenantRoute(api, WRITE, {
+        method: "put",
+        path: "/v1/environment-manifests/{name}",
+        tags: ["Environment manifests"],
+        summary: "Save an environment manifest",
+        description: "Saves the manifest as its next version, or answers the latest unchanged when nothing differs. No Environment changes: an Environment keeps the version it was made from, and a fork moves it to another (D63). `If-Match: <version>` refuses the save with `412 manifest_changed` when the latest version is no longer the one you read (`0` for a manifest that does not exist yet). With `?dryRun=true` the answer is the plan: the changes, every reason a save would be refused (`errors`), warnings, and how many Environments stay on older versions; nothing is saved. Clients drop a file's `$schema` before they send it.",
+        request: {
+            params: namePath,
+            query: z.object({
+                dryRun: z.enum(["true", "false"]).optional().meta({ description: "`true`: answer the plan and save nothing" }),
+            }),
+            body: { required: true, content: { "application/json": { schema: PutEnvironmentManifestRequest } } },
+        },
+        responses: {
+            200: json(z.union([SaveEnvironmentManifestResponse, EnvironmentManifestPlan]), "The version saved, or the plan with dryRun"),
+            400: { description: "The manifest breaks the Tenant's limits or names files the Runtime cannot use" },
+            412: { description: "If-Match named a version that is no longer the latest (`manifest_changed`)" },
+        },
+    }, async (c) => {
+        const name = nameOf(c.req.param("name"));
+        const body = PutEnvironmentManifestRequestSchema.parse(await readJson(c.req.raw));
+        const ifMatch = ifMatchOf(c.req.header("if-match"));
+        const options = ifMatch === undefined ? {} : { ifMatch };
+        return jsonResponse(200, c.req.query("dryRun") === "true"
+            ? await saveEnvironmentManifest(c.env.tenant, name, body, c.get("scope"), { ...options, dryRun: true })
+            : await saveEnvironmentManifest(c.env.tenant, name, body, c.get("scope"), options));
+    });
+    tenantRoute(api, READ, {
+        method: "get",
+        path: "/v1/environment-manifests/{name}",
+        tags: ["Environment manifests"],
+        summary: "Get an environment manifest",
+        description: "Its latest version.",
+        request: { params: namePath },
+        responses: { 200: json(EnvironmentManifestView, "The latest version") },
+    }, async (c) => jsonResponse(200, await getEnvironmentManifest(c.env.tenant, nameOf(c.req.param("name")))));
+    tenantRoute(api, READ, {
+        method: "get",
+        path: "/v1/environment-manifests/{name}/versions",
+        tags: ["Environment manifests"],
+        summary: "List an environment manifest's versions",
+        description: "Every version, newest first, with who saved it and how many Environments were made from it.",
+        request: { params: namePath },
+        responses: { 200: json(EnvironmentManifestVersions, "The versions") },
+    }, async (c) => jsonResponse(200, await environmentManifestVersions(c.env.tenant, nameOf(c.req.param("name")))));
+    tenantRoute(api, READ, {
+        method: "get",
+        path: "/v1/environment-manifests/{name}/versions/{version}",
+        tags: ["Environment manifests"],
+        summary: "Get one version of an environment manifest",
+        request: { params: namePath.extend({ version: z.string().meta({ description: "The version number" }) }) },
+        responses: { 200: json(EnvironmentManifestView, "The version") },
+    }, async (c) => jsonResponse(200, await getEnvironmentManifest(c.env.tenant, nameOf(c.req.param("name")), versionOf(c.req.param("version")))));
+    tenantRoute(api, WRITE, {
+        method: "delete",
+        path: "/v1/environment-manifests/{name}",
+        tags: ["Environment manifests"],
+        summary: "Delete an environment manifest",
+        description: "Deletes every version. Refused while any Environment was made from one (`409 manifest_in_use`).",
+        request: { params: namePath },
+        responses: {
+            200: json(DeleteEnvironmentManifestResponse, "Deleted, or there was none"),
+            409: { description: "An Environment was made from one of its versions (`manifest_in_use`)" },
+        },
+    }, async (c) => jsonResponse(200, await deleteEnvironmentManifest(c.env.tenant, nameOf(c.req.param("name")))));
+}

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

@@ -1,9 +1,9 @@
 import { z } from "zod";
-import { isEnvironmentId, PutEnvironmentRequestSchema, PutEnvironmentSecretRequestSchema, RestoreEnvironmentRequestSchema, } from "@nylorun/core/contracts";
+import { ENVIRONMENT_EVENT_TYPES, ForkEnvironmentRequestSchema, isEnvironmentId, PutEnvironmentRequestSchema, 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 { DeleteEnvironmentResponse, DeletedResponse, EnvironmentPage, EnvironmentRestore, EnvironmentSnapshot, EnvironmentVersions, ForkEnvironmentRequest, ForkEnvironmentResponse, RestoreEnvironmentRequest, EnvironmentSecretView, EnvironmentView, ListEnvironmentEventsResponse, ListEnvironmentSecretsResponse, ListEnvironmentsResponse, PutEnvironmentRequest, PutEnvironmentSecretRequest, PutEnvironmentSecretValueRequest, } from "../../components.js";
 import { fail } from "../../../tenant/http.js";
-import { actorOf, assertReaches, deleteEnvironment, environmentEventsOf, getEnvironment, listEnvironments, putEnvironment, resetEnvironment, stopEnvironment, } from "../../../tenant/environments.js";
+import { actorOf, assertReaches, deleteEnvironment, environmentEventsOf, forkEnvironment, getEnvironment, listEnvironments, putEnvironment, resetEnvironment, secretRequestFor, stopEnvironment, } from "../../../tenant/environments.js";
 import { readJson } from "../body.js";
 import { tenantRoute } from "../define.js";
 import { environmentPage, pageQuery } from "./reads.js";
@@ -75,7 +75,7 @@ export function environmentRoutes(api) {
         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.",
+        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. It is made from one version of an environment manifest (`manifest: \"name\"` takes the latest, `\"name@n\"` version n) or from the inline fields, and never changes what it runs after that (protocol 14, D63): on an existing one, labels replace, `ownerUserId` sets or (with `null`) clears the owner guard, fields that match what it runs are accepted, and anything else is `409 environment_immutable`, which names the fork that makes a new Environment instead. Kind `pod` needs sandbox pods (`nylorun local sandbox enable`) and is created at once.",
         request: {
             params: environmentId,
             body: { required: true, content: { "application/json": { schema: PutEnvironmentRequest } } },
@@ -83,7 +83,7 @@ export function environmentRoutes(api) {
         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`)",
+                description: "An Environment with this id runs something else (`environment_immutable`), 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) => {
@@ -104,12 +104,15 @@ export function environmentRoutes(api) {
         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.",
+        summary: "Read an Environment's events",
+        description: "`environment.created`, `.attached`, `.detached`, `.deleted`, a pod's `.running`, `.suspended`, `.relaunched`, `.lost`, `.reset` and `.failed`, and `environment.egress` for every connection its sandbox opens through egress-gate, naming the turns that were running (D67), in order, numbered from 0, at most 1000 per call.",
         request: {
             params: environmentId,
             query: z.object({
                 from: z.string().optional().meta({ description: "The first `seq` to return" }),
+                types: z.string().optional().meta({ description: "Only these event types, comma-separated (`environment.egress`)" }),
+                since: z.string().optional().meta({ description: "Only events recorded at or after this ISO time" }),
+                until: z.string().optional().meta({ description: "Only events recorded before this ISO time" }),
             }),
         },
         responses: { 200: json(ListEnvironmentEventsResponse, "The events") },
@@ -117,7 +120,27 @@ export function environmentRoutes(api) {
         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)));
+        const types = c.req.query("types")?.split(",").map((type) => type.trim()).filter(Boolean);
+        const unknown = types?.find((type) => !ENVIRONMENT_EVENT_TYPES.includes(type));
+        if (unknown !== undefined)
+            fail(400, `types: ${unknown} is not an Environment event type`);
+        const time = (name) => {
+            const value = c.req.query(name);
+            if (value === undefined)
+                return undefined;
+            const at = Date.parse(value);
+            if (!Number.isFinite(at))
+                fail(400, `${name} must be an ISO time`);
+            return new Date(at).toISOString();
+        };
+        const since = time("since");
+        const until = time("until");
+        return jsonResponse(200, await environmentEventsOf(c.env.tenant, idOf(c.req.param("environmentId")), c.get("scope"), {
+            ...(from === undefined ? {} : { fromSeq: Number(from) }),
+            ...(types === undefined || types.length === 0 ? {} : { types }),
+            ...(since === undefined ? {} : { since }),
+            ...(until === undefined ? {} : { until }),
+        }));
     });
     tenantRoute(api, WRITE, {
         method: "delete",
@@ -193,6 +216,28 @@ export function environmentRoutes(api) {
         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, WRITE, {
+        method: "post",
+        path: "/v1/environments/{environmentId}/fork",
+        tags: ["Environments"],
+        summary: "Fork an Environment",
+        description: "How an Environment gets a new manifest version (Q15): a new Environment `id`, made from `manifest` (default the source's manifest at its latest version), its disk started from a version of this one's (`disk`: `latest`, the default, takes a snapshot first; a version number; or `empty`) and its secrets copied inside the Runtime (`secrets`: `copy`, the default, copies those the new manifest declares; `none`). On a fork onto other setup the new manifest's setup runs on the copied disk before its first turn. This Environment keeps what it runs, its disk and its sessions. `dryRun` answers the plan and makes nothing.",
+        request: {
+            params: environmentId,
+            body: { required: true, content: { "application/json": { schema: ForkEnvironmentRequest } } },
+        },
+        responses: {
+            200: json(ForkEnvironmentResponse, "The plan (`dryRun`)"),
+            201: json(ForkEnvironmentResponse, "The new Environment, and the plan it ran"),
+            400: { description: "The source was made from inline fields and no manifest is named, or the manifest does not resolve" },
+            404: { description: "No such Environment, manifest version (`manifest_not_found`) or disk version" },
+            409: { description: "The id exists, or a turn or another copy holds the source's disk (`environment_busy`)" },
+        },
+    }, async (c) => {
+        const body = ForkEnvironmentRequestSchema.parse(await readJson(c.req.raw));
+        const answer = await forkEnvironment(c.env.tenant, idOf(c.req.param("environmentId")), body, c.get("scope"));
+        return jsonResponse("dryRun" in answer ? 200 : 201, answer);
+    });
     tenantRoute(api, READ, {
         method: "get",
         path: "/v1/environments/{environmentId}/versions",
@@ -250,10 +295,13 @@ export function environmentRoutes(api) {
         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`.",
+        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`. When what the Environment runs declares secret slots (protocol 14, D64), send only the value (`{ value }`, or `{ headers }` for a `headers` slot): the type and binding come from the slot, and a name it does not declare is `409 secret_not_in_manifest`.",
         request: {
             params: secretPath,
-            body: { required: true, content: { "application/json": { schema: PutEnvironmentSecretRequest } } },
+            body: {
+                required: true,
+                content: { "application/json": { schema: z.union([PutEnvironmentSecretRequest, PutEnvironmentSecretValueRequest]) } },
+            },
         },
         responses: {
             200: json(EnvironmentSecretView, "The secret, without its value"),
@@ -263,8 +311,9 @@ export function environmentRoutes(api) {
         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)));
+        const name = c.req.param("name") ?? "";
+        const body = await secretRequestFor(c.env.tenant, id, name, await readJson(c.req.raw));
+        return jsonResponse(200, await c.env.tenant.keys.putEnvironmentSecret(id, name, body, actorOf(scope)));
     });
     tenantRoute(api, WRITE, {
         method: "delete",

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

@@ -44,7 +44,7 @@ export declare function environmentPage(ctx: TenantEnv["Bindings"]["tenant"], sc
         id: string;
         kind: "none" | "pod" | "virtual";
         labels: Record<string, string>;
-        recipe: {
+        manifest: {
             image?: string | undefined;
             resources?: {
                 cpus: number;
@@ -64,12 +64,60 @@ export declare function environmentPage(ctx: TenantEnv["Bindings"]["tenant"], sc
                 cwd?: string | undefined;
                 timeout?: string | undefined;
             }[] | undefined;
-            files?: {
+            files?: ({
                 artifactId: string;
                 version: number;
                 path: string;
-            }[] | undefined;
+            } | {
+                path: string;
+                files: Record<string, string>;
+            })[] | undefined;
+            secrets?: Record<string, {
+                required?: boolean | undefined;
+                description?: string | undefined;
+                type: "environment_secret";
+                allowedHosts: string[];
+                inject?: {
+                    header: string;
+                    format: string;
+                } | undefined;
+            } | {
+                required?: boolean | undefined;
+                description?: string | undefined;
+                type: "environment_variable";
+            } | {
+                via?: string | undefined;
+                identity?: {
+                    header: string;
+                } | undefined;
+                required?: boolean | undefined;
+                description?: string | undefined;
+                type: "bearer";
+                url: string;
+            } | {
+                via?: string | undefined;
+                identity?: {
+                    header: string;
+                } | undefined;
+                required?: boolean | undefined;
+                description?: string | undefined;
+                type: "headers";
+                url: string;
+            }> | undefined;
         };
+        manifestName?: string | undefined;
+        manifestVersion?: number | undefined;
+        manifestHash?: string | undefined;
+        forkedFrom?: {
+            environment: string;
+            disk: number | null;
+        } | undefined;
+        slots?: {
+            name: string;
+            type: string;
+            required: boolean;
+            set: boolean;
+        }[] | undefined;
         version: number;
         appliedVersion: number;
         ownerUserId: string | null;
@@ -80,6 +128,7 @@ export declare function environmentPage(ctx: TenantEnv["Bindings"]["tenant"], sc
             volumeGeneration: number;
             hostEpoch: number;
             reason?: string | undefined;
+            imageDigest?: string | undefined;
         } | undefined;
         lastUsedAt: string;
         disk?: {

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

@@ -57,6 +57,9 @@ export function sessionRoutes(api) {
         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) => {
         // A `traceparent` joins the turn to the caller's trace (R7.4); a malformed one is ignored.
@@ -87,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",