@nylorun/runtime 0.23.0-beta → 0.25.0-beta

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.d.ts

@@ -0,0 +1,11 @@
+/**
+ * Environments (`/v1/environments/**`, protocol 11, D55, D56): create, find or change one by id,
+ * read it, list them by label, read its lifecycle stream, stop, reset and delete it, and write
+ * its vault's secrets. Ids may hold `/`, sent percent-encoded as one path segment
+ * (`users%2Falice%2Fweb`). A token caller reaches only the ids its Environment grants match,
+ * and changes them only with `environments:write`. Secret values are write-only: no route reads
+ * one back.
+ */
+import type { OpenAPIHono } from "@hono/zod-openapi";
+import type { TenantEnv } from "../app.js";
+export declare function environmentRoutes(api: OpenAPIHono<TenantEnv>): void;

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

@@ -0,0 +1,332 @@
+import { z } from "zod";
+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, 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, 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";
+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. 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 } } },
+        },
+        responses: {
+            200: json(EnvironmentView, "The Environment"),
+            409: {
+                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) => {
+        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 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") },
+    }, async (c) => {
+        const from = c.req.query("from");
+        if (from !== undefined && !/^\d+$/.test(from))
+            fail(400, "from must be a seq");
+        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",
+        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, 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",
+        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`. 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: z.union([PutEnvironmentSecretRequest, PutEnvironmentSecretValueRequest]) } },
+            },
+        },
+        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 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",
+        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,26 +33,111 @@ 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";
+        manifest: {
+            image?: string | undefined;
+            resources?: {
+                cpus: number;
+                memory: string;
+            } | undefined;
+            storage?: string | undefined;
+            network?: {
+                allowedHosts: string[];
+            } | undefined;
+            harness: string;
+            lifecycle: {
+                idle?: string | undefined;
+                deleteAfter?: string | undefined;
+            };
+            setup?: {
+                command: string;
+                cwd?: string | undefined;
+                timeout?: string | undefined;
+            }[] | undefined;
+            files?: ({
+                artifactId: string;
+                version: number;
+                path: string;
+            } | {
+                path: string;
+                files: Record<string, string>;
+            })[] | undefined;
+            secrets?: Record<string, {
+                required?: boolean | undefined;
+                description?: string | undefined;
+                type: "environment_secret";
+                allowedHosts: string[];
+                inject?: {
+                    header: string;
+                    format: string;
+                } | undefined;
+            } | {
+                required?: boolean | undefined;
+                description?: string | undefined;
+                type: "environment_variable";
+            } | {
+                via?: string | undefined;
+                identity?: {
+                    header: string;
+                } | undefined;
+                required?: boolean | undefined;
+                description?: string | undefined;
+                type: "bearer";
+                url: string;
+            } | {
+                via?: string | undefined;
+                identity?: {
+                    header: string;
+                } | undefined;
+                required?: boolean | undefined;
+                description?: string | undefined;
+                type: "headers";
+                url: string;
+            }> | undefined;
+        };
+        manifestName?: string | undefined;
+        manifestVersion?: number | undefined;
+        manifestHash?: string | undefined;
+        forkedFrom?: {
+            environment: string;
+            disk: number | null;
+        } | undefined;
+        slots?: {
+            name: string;
+            type: string;
+            required: boolean;
+            set: boolean;
+        }[] | undefined;
+        version: number;
+        appliedVersion: number;
+        ownerUserId: string | null;
+        state: string;
         pod?: {
             desired: "deleted" | "running" | "suspended";
-            observed: "creating" | "deleting" | "expired" | "failed" | "lost" | "running" | "suspended";
+            observed: "creating" | "deleting" | "failed" | "lost" | "running" | "suspended";
             volumeGeneration: number;
             hostEpoch: number;
-            expiresAt?: string | undefined;
             reason?: string | undefined;
+            imageDigest?: string | undefined;
+        } | undefined;
+        lastUsedAt: string;
+        disk?: {
+            latestVersion: number | null;
+            operation?: {
+                kind: "restore" | "seed" | "snapshot";
+                version?: number | undefined;
+                startedAt: string;
+            } | undefined;
         } | undefined;
         sessions: {
             id: string;