@nylorun/runtime 0.27.0-beta → 0.29.0-beta

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

@@ -0,0 +1,183 @@
+import { z } from "zod";
+import { isAgentId } from "@nylorun/core/contracts";
+import { RunTriggerResponse, TriggerList, TriggerRunPage, WebhookAcceptedResponse, WebhookSecretResponse, } from "../../components.js";
+import { assertReaches } from "../../../tenant/agents.js";
+import { fail } from "../../../tenant/http.js";
+import { listRuns, listTriggers, receiveWebhook, rotateWebhookSecret, runTriggerNow, setTriggerStatus, } from "../../../tenant/triggers.js";
+import { readRuntimeLimits } from "../../../tenant/runtime-limits.js";
+import { readBytes } from "../body.js";
+import { tenantRoute } from "../define.js";
+import { pageQuery, pageSize, parseQuery } from "./reads.js";
+import { jsonResponse } from "../respond.js";
+const READ = {
+    credentials: ["application", "subject", "token"],
+    scopes: ["sessions:own", "agents:read", "agents:write"],
+};
+const WRITE = {
+    credentials: ["application", "subject", "token"],
+    scopes: ["agents:write"],
+};
+const json = (schema, description) => ({
+    description,
+    content: { "application/json": { schema } },
+});
+const agentId = z.object({
+    agentId: z.string().meta({ description: "The Agent id, percent-encoded" }),
+});
+const triggerPath = agentId.extend({
+    triggerId: z.string().meta({ description: "The trigger's id in the manifest's `runtime.triggers`" }),
+});
+function idOf(value) {
+    if (!isAgentId(value))
+        return fail(400, "An Agent id is up to 200 characters: /-separated segments of letters, digits, '.', '_' and '-'");
+    return value;
+}
+export function triggerRoutes(api) {
+    tenantRoute(api, READ, {
+        method: "get",
+        path: "/v1/agents/{agentId}/triggers",
+        tags: ["Triggers"],
+        summary: "List an Agent's triggers",
+        description: "Each trigger its manifest declares, with what the Agent holds of it: its status (`active`, `paused` with a reason, `completed` for an `at` that ran), when it runs next and last ran.",
+        request: { params: agentId },
+        responses: { 200: json(TriggerList, "The triggers") },
+    }, async (c) => {
+        const id = idOf(c.req.param("agentId"));
+        assertReaches(c.get("scope"), id);
+        return jsonResponse(200, await listTriggers(c.env.tenant, id, originOf(c)));
+    });
+    for (const action of ["pause", "resume"])
+        tenantRoute(api, WRITE, {
+            method: "post",
+            path: `/v1/agents/{agentId}/triggers/{triggerId}/${action}`,
+            tags: ["Triggers"],
+            summary: action === "pause" ? "Pause a trigger" : "Resume a trigger",
+            description: action === "pause"
+                ? "It stops firing until it is resumed; a run already started or queued goes on."
+                : "It fires again from its next time after now; missed times are not run. An `at` whose time has passed is refused (`trigger_expired`).",
+            request: { params: triggerPath },
+            responses: {
+                200: json(TriggerList, "The Agent's triggers"),
+                409: { description: "An `at` whose time has passed (`trigger_expired`)" },
+            },
+        }, async (c) => {
+            const id = idOf(c.req.param("agentId"));
+            assertReaches(c.get("scope"), id);
+            return jsonResponse(200, await setTriggerStatus(c.env.tenant, id, c.req.param("triggerId"), action, originOf(c)));
+        });
+    tenantRoute(api, WRITE, {
+        method: "post",
+        path: "/v1/agents/{agentId}/triggers/{triggerId}/run",
+        tags: ["Triggers"],
+        summary: "Run a trigger now",
+        description: "Runs it once now, paused or not, as if it had fired: a turn on its session, or a queued message when a turn runs there. A retried request with the same `Idempotency-Key` answers the same run.",
+        request: {
+            params: triggerPath,
+            headers: z.object({ "Idempotency-Key": z.string().min(1).max(200) }),
+        },
+        responses: { 200: json(RunTriggerResponse, "The run") },
+    }, async (c) => {
+        const id = idOf(c.req.param("agentId"));
+        assertReaches(c.get("scope"), id);
+        const key = c.req.header("idempotency-key")?.trim();
+        if (!key || key.length > 200)
+            fail(400, "Idempotency-Key is required: 1-200 characters");
+        return jsonResponse(200, { run: await runTriggerNow(c.env.tenant, id, c.req.param("triggerId"), key) });
+    });
+    tenantRoute(api, READ, {
+        method: "get",
+        path: "/v1/agents/{agentId}/runs",
+        tags: ["Triggers"],
+        summary: "List an Agent's runs",
+        description: "Each time one of its triggers fired or was run by hand, newest first: when it was due, whether it was late, and what came of it (`started`, `queued`, `skipped` or `failed`, with a reason), with the session and turn.",
+        request: {
+            params: agentId,
+            query: pageQuery.extend({
+                triggerId: z.string().optional().meta({ description: "Only this trigger's runs" }),
+            }),
+        },
+        responses: { 200: json(TriggerRunPage, "A page of runs") },
+    }, async (c) => {
+        const id = idOf(c.req.param("agentId"));
+        assertReaches(c.get("scope"), id);
+        const triggerId = c.req.query("triggerId");
+        const { limit, cursor } = parseQuery(pageQuery, { limit: c.req.query("limit"), cursor: c.req.query("cursor") });
+        return jsonResponse(200, await listRuns(c.env.tenant, id, {
+            ...(triggerId ? { triggerId } : {}),
+            ...(cursor ? { cursor } : {}),
+            limit: await pageSize(c.env.tenant, limit, { fallback: 50 }),
+        }));
+    });
+}
+/** A delivery: no credential, no protocol header, any body; the endpoint id and the signature are the grant. */
+const DELIVERY = {
+    credentials: [],
+    scopes: "any",
+    anonymous: true,
+    unversioned: true,
+    bytes: true,
+};
+export function webhookRoutes(api) {
+    tenantRoute(api, WRITE, {
+        method: "post",
+        path: "/v1/agents/{agentId}/triggers/{triggerId}/secret",
+        tags: ["Triggers"],
+        summary: "Make a webhook trigger's signing secret",
+        description: "A new Standard Webhooks secret (`whsec_…`) for a webhook trigger, shown this once; the one before stops working at once. Give it to the sender with the trigger's `webhookUrl`.",
+        request: { params: triggerPath },
+        responses: {
+            200: json(WebhookSecretResponse, "The secret, this once"),
+            400: { description: "Not a webhook trigger" },
+        },
+    }, async (c) => {
+        const id = idOf(c.req.param("agentId"));
+        assertReaches(c.get("scope"), id);
+        return jsonResponse(200, await rotateWebhookSecret(c.env.tenant, id, c.req.param("triggerId"), originOf(c)));
+    });
+    tenantRoute(api, DELIVERY, {
+        method: "post",
+        path: "/v1/webhooks/{endpointId}",
+        tags: ["Triggers"],
+        summary: "Deliver to a webhook trigger",
+        description: "A sender's delivery, signed with Standard Webhooks (`webhook-id`, `webhook-timestamp` within 5 minutes by default, `webhook-signature`): no credential (an `Authorization` header is ignored) and no `Nylorun-Protocol`. The body, any media type, at most the Runtime limit `webhookBodyBytes`, is read as bytes and verified before anything else. It runs the trigger once per `webhook-id`: a retry answers the first run. The body reaches the model as data under the trigger's prompt. Other senders (GitHub, Stripe, Slack) are relayed by an app.",
+        request: {
+            params: z.object({ endpointId: z.string().meta({ description: "The trigger's endpoint id, `wh_…`" }) }),
+            headers: z.object({
+                "webhook-id": z.string().meta({ description: "The delivery's id; a retry sends the same" }),
+                "webhook-timestamp": z.string().meta({ description: "Seconds since the epoch" }),
+                "webhook-signature": z.string().meta({ description: "`v1,<base64>`, space-separated" }),
+            }),
+            body: {
+                required: true,
+                description: "The payload, of any media type",
+                content: { "*/*": { schema: z.string().meta({ format: "binary" }) } },
+            },
+        },
+        responses: {
+            202: json(WebhookAcceptedResponse, "The run it made: started, queued, skipped or failed"),
+            401: { description: "Unsigned, not signed with the endpoint's secret, or a timestamp out of tolerance" },
+            404: { description: "No endpoint has this id" },
+            409: { description: "The trigger is paused (`trigger_paused`)" },
+            413: { description: "Over `webhookBodyBytes`" },
+        },
+    }, async (c) => {
+        const tenant = c.env.tenant;
+        const { webhookBodyBytes } = await tenant.store.tx((t) => readRuntimeLimits(t));
+        const body = await readBytes(c.req.raw, webhookBodyBytes, "webhookBodyBytes");
+        const header = (name) => c.req.header(name)?.trim() || undefined;
+        return jsonResponse(202, await receiveWebhook(tenant, c.req.param("endpointId"), {
+            id: header("webhook-id"),
+            timestamp: header("webhook-timestamp"),
+            signature: header("webhook-signature"),
+            contentType: header("content-type"),
+            body,
+        }));
+    });
+}
+/**
+ * Where its webhook URLs live: the Runtime's public URL (`NYLORUN_PUBLIC_URL`), else the origin
+ * the request reached, which behind a proxy that rewrites `Host` is the Runtime's own.
+ */
+function originOf(c) {
+    return c.env.tenant.config.publicUrl ?? new URL(c.req.url).origin;
+}

package/dist/api/openapi.js

@@ -110,21 +110,79 @@ function tenantSchemes(registry) {
 }
 const RUNTIME_TAGS = [
     {
-        name: "Agents",
+        name: "Agent manifests",
         group: "Agents",
-        description: "The agents a Tenant can run: put a definition, list what is there. In `@nylorun/agents`.",
-        operations: ["PUT /v1/agents/{agentId}", "GET /v1/agents"],
+        description: "Named, versioned agent manifests (protocol 16): one document with what runs inside an agent's loop (`harness`) and what the Runtime provides around it (`runtime`), checked against each other when it is saved. Save one with a plan first (`?dryRun=true`) and `If-Match`; an Agent runs one version at a time, and a save moves every Agent that tracks the manifest to the new version, while a pinned one stays. `client.agentManifests` in `@nylorun/agents`, and `nylorun apply`.",
+        operations: [
+            "PUT /v1/agent-manifests/{name}",
+            "GET /v1/agent-manifests",
+            "GET /v1/agent-manifests/{name}",
+            "GET /v1/agent-manifests/{name}/versions",
+            "GET /v1/agent-manifests/{name}/versions/{version}",
+            "DELETE /v1/agent-manifests/{name}",
+        ],
     },
     {
         name: "Definition files",
         group: "Agents",
-        description: "The files a definition names by the SHA-256 of their bytes (each skill's folder): upload each once before putting the definition, which is refused while it names one the Runtime does not hold (`definition_files_missing`) or a skill whose files hold more than the Tenant's skill limit together (`limit_exceeded`; `/v1/tenant/skills`, default 2 GiB). No file and no count of files has a limit of its own. `saveAgent` in `@nylorun/agents` does both.",
+        description: "The files an agent manifest names by the SHA-256 of their bytes (each skill's folder, a runtime section's input files): upload each once before saving the manifest, which is refused while it names one the Runtime does not hold (`definition_files_missing`) or a skill whose files hold more than its skill limit together (`limit_exceeded`; `/v1/tenant/skills`, default 2 GiB). No file and no count of files has a limit of its own. `client.agentManifests.save` in `@nylorun/agents` does both.",
         operations: ["PUT /v1/files/{file}", "HEAD /v1/files/{file}"],
     },
+    {
+        name: "Agents",
+        group: "Agents",
+        description: "The live instances of agent manifests: an Agent has a stable id, its manifest version, one sandbox (a virtual workspace, a pod with its own volume, or none), one vault of secrets for its shell, MCP servers and HTTP tools, its disk versions, and its sessions. Its `state` says whether it is working, sleeping, needs a person (`input_required`), is failing or paused. Create or find one from a saved manifest, watch its lifecycle, stop, reset, fork or delete it, and write its secrets. In `@nylorun/agents`.",
+        operations: [
+            "PUT /v1/agents/{agentId}",
+            "GET /v1/agents",
+            "GET /v1/agents/{agentId}",
+            "GET /v1/agents/{agentId}/events",
+            "POST /v1/agents/{agentId}/stop",
+            "POST /v1/agents/{agentId}/reset",
+            "POST /v1/agents/{agentId}/restart",
+            "DELETE /v1/agents/{agentId}",
+            "GET /v1/agents/{agentId}/secrets",
+            "GET /v1/agents/{agentId}/secrets/{name}",
+            "PUT /v1/agents/{agentId}/secrets/{name}",
+            "DELETE /v1/agents/{agentId}/secrets/{name}",
+            "POST /v1/agents/{agentId}/snapshot",
+            "POST /v1/agents/{agentId}/restore",
+            "POST /v1/agents/{agentId}/fork",
+            "GET /v1/agents/{agentId}/versions",
+            "DELETE /v1/agents/{agentId}/versions/{version}",
+        ],
+    },
+    {
+        name: "Triggers",
+        group: "Agents",
+        description: "What starts an Agent's turns with no client connected: the schedules, one-shot times and webhook endpoints its manifest's `runtime.triggers` declare. Each trigger's status is the Agent's: pause and resume it, run it now, make a webhook trigger's signing secret, and read its runs (`started`, `queued`, `skipped` or `failed`, with a reason). In `@nylorun/agents` and `nylorun agents triggers`.",
+        operations: [
+            "GET /v1/agents/{agentId}/triggers",
+            "POST /v1/agents/{agentId}/triggers/{triggerId}/pause",
+            "POST /v1/agents/{agentId}/triggers/{triggerId}/resume",
+            "POST /v1/agents/{agentId}/triggers/{triggerId}/run",
+            "GET /v1/agents/{agentId}/runs",
+            "POST /v1/agents/{agentId}/triggers/{triggerId}/secret",
+            "POST /v1/webhooks/{endpointId}",
+        ],
+    },
+    {
+        name: "Memory",
+        group: "Agents",
+        description: "An Agent's memories: Markdown files under `/memories` it keeps across sessions, wakes and upgrades, shaped like Anthropic's memory stores. List and read them, write one whole (with a `content_sha256` precondition), delete one or a folder, and read the version every change leaves, with who made it. In `@nylorun/agents` and `nylorun agents memories`.",
+        operations: [
+            "GET /v1/agents/{agentId}/memories",
+            "GET /v1/agents/{agentId}/memories/{path}",
+            "PUT /v1/agents/{agentId}/memories/{path}",
+            "DELETE /v1/agents/{agentId}/memories/{path}",
+            "GET /v1/agents/{agentId}/memory_versions",
+            "GET /v1/agents/{agentId}/memory_versions/{versionId}",
+        ],
+    },
     {
         name: "Sessions API",
         group: "Sessions",
-        description: "A conversation with an agent: open a session, send commands, follow its events, read its history. In `@nylorun/agents`.",
+        description: "A conversation with an Agent: open a session on it, send commands, follow its events, read its history. No session is special: an app that keeps one conversation going reuses its id. In `@nylorun/agents`.",
         operations: [
             "PUT /v1/sessions/{sessionId}",
             "GET /v1/sessions",
@@ -143,7 +201,7 @@ const RUNTIME_TAGS = [
     {
         name: "AG-UI",
         group: "Sessions",
-        description: "The same sessions through AG-UI: a thread is one session per person, agent and thread, and each run is a turn.",
+        description: "The same sessions through AG-UI: a thread is one session per person, Agent and thread, and each run is a turn.",
         operations: [
             "POST /v1/ag-ui/agents/{agentId}",
             "GET /v1/ag-ui/agents/{agentId}/threads/{threadId}/events",
@@ -154,45 +212,9 @@ const RUNTIME_TAGS = [
     {
         name: "A2A",
         group: "Sessions",
-        description: "The same sessions through Agent2Agent: a context is one session per subject, agent and `contextId`, and a task is one turn. The card is how an A2A client finds the agent.",
+        description: "The same sessions through Agent2Agent: a context is one session per subject, Agent and `contextId`, and a task is one turn; every caller's session runs on the Agent's disk and vault, so an app that serves several audiences makes an Agent for each. The card is how an A2A client finds the Agent.",
         operations: ["GET /v1/a2a/agents/{agentId}/card", "POST /v1/a2a/agents/{agentId}"],
     },
-    {
-        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/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}",
-        ],
-    },
     {
         name: "Artifacts",
         group: "Artifacts",
@@ -266,12 +288,12 @@ const MANAGEMENT_TAGS = [
     },
     {
         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`.",
+        description: "Which secret of an Agent's vault each of its manifest'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 an Environment'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 Agent'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"],
     },
     {
@@ -285,7 +307,7 @@ const MANAGEMENT_TAGS = [
     },
     {
         name: "Settings",
-        description: "The Tenant's sandbox backend, Environment, artifact and skill settings, and its Runtime limits. `admin.settings`.",
+        description: "The Tenant's sandbox backend, Agent compute, artifact and skill settings, and its Runtime limits. `admin.settings`.",
         operations: [
             "GET /v1/tenant/sandbox",
             "PUT /v1/tenant/sandbox",
@@ -392,7 +414,7 @@ function documents() {
     built = {
         runtime: document(all, RUNTIME_TAGS, {
             title: "Nylorun Runtime API",
-            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).",
+            description: "For developers: agent manifests, Agents, sessions (with AG-UI and A2A) 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",

package/dist/artifacts/disk.d.ts

@@ -1,20 +1,20 @@
-import { type EnvironmentRestore, type EnvironmentSnapshot, type EnvironmentVersions } from "@nylorun/core/contracts";
+import { type AgentRestore, type AgentSnapshot, type AgentDiskVersions } from "@nylorun/core/contracts";
 import type { Tx } from "../store/types.js";
 import type { TenantContext } from "../tenant/context.js";
-import { assertReaches } from "../tenant/environments.js";
+import { assertReaches } from "../tenant/agents.js";
 /** The name of an Environment's disk artifact. */
 export declare const DISK_ARTIFACT_NAME = "disk";
 /**
- * `POST /v1/environments/{id}/snapshot`: a new version of the Environment's disk, between turns.
+ * `POST /v1/agents/{id}/snapshot`: a new version of the Environment's disk, between turns.
  * A pod that is stopped is started first. An unchanged disk makes no version.
  */
-export declare function snapshotEnvironment(ctx: TenantContext, id: string, scope: Parameters<typeof assertReaches>[0]): Promise<EnvironmentSnapshot>;
+export declare function snapshotEnvironment(ctx: TenantContext, id: string, scope: Parameters<typeof assertReaches>[0]): Promise<AgentSnapshot>;
 /**
- * `POST /v1/environments/{id}/restore`: puts disk version `version` back. A virtual
+ * `POST /v1/agents/{id}/restore`: puts disk version `version` back. A virtual
  * Environment's workspace is rewritten at once; a pod gets a new volume, seeded from the version
  * before any turn (`status: pending` until then).
  */
-export declare function restoreEnvironment(ctx: TenantContext, id: string, scope: Parameters<typeof assertReaches>[0], version: number | "latest"): Promise<EnvironmentRestore>;
+export declare function restoreEnvironment(ctx: TenantContext, id: string, scope: Parameters<typeof assertReaches>[0], version: number | "latest"): Promise<AgentRestore>;
 /**
  * Writes Environment `id`'s pending seed (`disk_seed`) into its disk, once its pod's engine is
  * connected (or at once for a virtual one), then clears the seed and the lease. Started after a
@@ -37,14 +37,14 @@ export declare function forkSeedOf(t: Tx, from: {
     artifactId: string;
     version: number;
 }>;
-/** `GET /v1/environments/{id}/versions`: its disk versions, newest first. */
-export declare function environmentVersions(ctx: TenantContext, id: string, scope: Parameters<typeof assertReaches>[0]): Promise<EnvironmentVersions>;
+/** `GET /v1/agents/{id}/versions`: its disk versions, newest first. */
+export declare function environmentVersions(ctx: TenantContext, id: string, scope: Parameters<typeof assertReaches>[0]): Promise<AgentDiskVersions>;
 /**
- * `DELETE /v1/environments/{id}/versions/{n}`: deletes one disk version, and the stored files no
+ * `DELETE /v1/agents/{id}/versions/{n}`: deletes one disk version, and the stored files no
  * other version names. Refused while a seed reads it.
  */
 export declare function deleteEnvironmentVersion(ctx: TenantContext, id: string, scope: Parameters<typeof assertReaches>[0], version: number): Promise<{
-    environmentId: string;
+    agentId: string;
     version: number;
     deleted: boolean;
 }>;

package/dist/artifacts/disk.js

@@ -18,14 +18,14 @@
  *   until the engine has run that setup on the written disk; turns wait for both.
  *
  * Nothing here runs inside a transaction but the lease and the commit. No event type is new:
- * a restore or recovery is `environment.reset` with `reason` and `from`.
+ * a restore or recovery is `agent.reset` with `reason` and `from`.
  */
 import { createHash, randomUUID } from "node:crypto";
 import { newArtifactId } from "@nylorun/core/compatibility";
 import { FOLDER_CONTENT_TYPE, FOLDER_MANIFEST_FORMAT_V2, } from "@nylorun/core/contracts";
 import { sandboxSpecOf } from "../sandbox/resolve.js";
 import { effectiveSandboxConfig, readSandboxConfig } from "../sandbox/tenant-config.js";
-import { assertReaches, diskHeld, liveEnvironment, newVolume, wakePod, } from "../tenant/environments.js";
+import { assertReaches, diskHeld, liveEnvironment, newVolume, wakePod, } from "../tenant/agents.js";
 import { fail, failRetryLater } from "../tenant/http.js";
 import { hostTuning } from "../tuning.js";
 import { artifactQuota, totalSubject } from "./quota.js";
@@ -63,25 +63,25 @@ async function diskTarget(ctx, environment) {
         spec,
     };
 }
-/** One disk operation through the workspace, or a `409 environment_unavailable`. */
+/** One disk operation through the workspace, or a `409 agent_unavailable`. */
 async function diskOp(ctx, target, op) {
     const answer = await ctx.sandbox.disk(target.ref, target.spec, op, new AbortController().signal);
     if ("code" in answer)
-        return fail(409, `The disk could not be reached: ${answer.message}`, { code: "environment_unavailable" });
+        return fail(409, `The disk could not be reached: ${answer.message}`, { code: "agent_unavailable" });
     return answer;
 }
 /**
- * Takes the disk lease of Environment `id` for `kind`: refused (`409 environment_busy`) while a
+ * Takes the disk lease of Environment `id` for `kind`: refused (`409 agent_busy`) while a
  * turn runs or another copy holds it; `400` for kind `none`, which has no disk.
  */
 async function lease(ctx, id, kind, leaseMs, version) {
     return ctx.store.tx(async (t) => {
-        const environment = (await liveEnvironment(t, id, { lock: true })) ?? fail(404, "Environment not found");
+        const environment = (await liveEnvironment(t, id, { lock: true })) ?? fail(404, "Agent not found");
         if (environment.kind === "none")
-            fail(400, `Environment ${id} is of kind none: it has no disk.`);
+            fail(400, `Agent ${id} is of kind none: it has no disk.`);
         const busy = (await t.sessionsOnEnvironment(id)).some((session) => session.activeTurnId);
         if (busy || diskHeld(environment))
-            failRetryLater(`Environment ${id} has a turn running or its disk is being copied. Try again shortly.`, "environment_busy");
+            failRetryLater(`Agent ${id} has a turn running or its disk is being copied. Try again shortly.`, "agent_busy");
         const now = new Date();
         const operation = {
             kind,
@@ -134,7 +134,7 @@ async function awaitEngine(ctx, id, waitMs) {
     const deadline = Date.now() + waitMs;
     while (!ctx.harness.hosting(id)) {
         if (Date.now() > deadline)
-            failRetryLater(`Environment ${id}'s pod did not start within ${waitMs / 1000} s (the Runtime limit diskPodWaitMs).`, "environment_unavailable");
+            failRetryLater(`Agent ${id}'s pod did not start within ${waitMs / 1000} s (the Runtime limit diskPodWaitMs).`, "agent_unavailable");
         await new Promise((resolve) => setTimeout(resolve, hostTuning().pods.enginePollMs));
     }
 }
@@ -158,7 +158,7 @@ async function readFile(ctx, target, path, rangeBytes) {
     return { bytes: Buffer.concat(chunks), sha256: hash.digest("hex") };
 }
 /**
- * `POST /v1/environments/{id}/snapshot`: a new version of the Environment's disk, between turns.
+ * `POST /v1/agents/{id}/snapshot`: a new version of the Environment's disk, between turns.
  * A pod that is stopped is started first. An unchanged disk makes no version.
  */
 export async function snapshotEnvironment(ctx, id, scope) {
@@ -226,7 +226,7 @@ export async function snapshotEnvironment(ctx, id, scope) {
             durationMs: Date.now() - started,
         });
         return {
-            environmentId: id,
+            agentId: id,
             artifactId: committed.artifact.id,
             version: committed.version.version,
             format: FOLDER_MANIFEST_FORMAT_V2,
@@ -265,7 +265,7 @@ async function commitDiskVersion(ctx, id, entries, epoch) {
     const key = `artifacts/${artifactId}/${randomUUID()}`;
     await ctx.blobs.put(key, manifest, { contentType: FOLDER_CONTENT_TYPE });
     return ctx.store.tx(async (t) => {
-        (await liveEnvironment(t, id, { lock: true })) ?? fail(404, "Environment not found");
+        (await liveEnvironment(t, id, { lock: true })) ?? fail(404, "Agent not found");
         const quota = await artifactQuota(t, id);
         await t.lockArtifactQuota();
         const shas = [...files.keys()];
@@ -274,7 +274,7 @@ async function commitDiskVersion(ctx, id, entries, epoch) {
         if ((await contentEpoch(t)) !== epoch)
             for (const sha of fresh)
                 if (!(await ctx.blobs.head(contentKey(sha))))
-                    fail(409, "A file's bytes were removed while the snapshot ran; try again.", { code: "environment_busy" });
+                    fail(409, "A file's bytes were removed while the snapshot ran; try again.", { code: "agent_busy" });
         for (const total of quota.totals) {
             // A file adds bytes to a total unless an artifact it counts already holds the file.
             const scope = total.environmentId === undefined ? undefined : { environmentId: total.environmentId };
@@ -397,11 +397,11 @@ async function versionOf(t, id, version) {
     const artifact = await t.diskArtifact(id);
     const number = version === "latest" ? artifact?.latestVersion : version;
     if (!artifact || !number || !(await t.artifactVersion(artifact.id, number)))
-        return fail(404, `Environment ${id} has no disk version ${version}`);
+        return fail(404, `Agent ${id} has no disk version ${version}`);
     return { artifactId: artifact.id, version: number };
 }
 /**
- * `POST /v1/environments/{id}/restore`: puts disk version `version` back. A virtual
+ * `POST /v1/agents/{id}/restore`: puts disk version `version` back. A virtual
  * Environment's workspace is rewritten at once; a pod gets a new volume, seeded from the version
  * before any turn (`status: pending` until then).
  */
@@ -410,16 +410,16 @@ export async function restoreEnvironment(ctx, id, scope, version) {
     const seed = await ctx.store.tx((t) => versionOf(t, id, version));
     const found = await ctx.store.tx((t) => liveEnvironment(t, id));
     if (!found)
-        return fail(404, "Environment not found");
+        return fail(404, "Agent not found");
     if (found.kind === "pod") {
         const volumeGeneration = await ctx.store.tx(async (t) => {
-            const environment = (await liveEnvironment(t, id, { lock: true })) ?? fail(404, "Environment not found");
+            const environment = (await liveEnvironment(t, id, { lock: true })) ?? fail(404, "Agent not found");
             const busy = (await t.sessionsOnEnvironment(id)).some((session) => session.activeTurnId);
             if (busy || diskHeld(environment) || environment.pod.retiring !== undefined)
-                failRetryLater(`Environment ${id} has a turn running, its disk is being copied or its last volume is still being deleted.`, "environment_busy");
+                failRetryLater(`Agent ${id} has a turn running, its disk is being copied or its last volume is still being deleted.`, "agent_busy");
             return newVolume(ctx, t, environment, { seed, reason: "restore" });
         });
-        return { environmentId: id, restored: seed.version, status: "pending", volumeGeneration };
+        return { agentId: id, restored: seed.version, status: "pending", volumeGeneration };
     }
     const limits = await copyLimits(ctx, found);
     const environment = await lease(ctx, id, "restore", limits.leaseMs, seed.version);
@@ -430,7 +430,7 @@ export async function restoreEnvironment(ctx, id, scope, version) {
     finally {
         await beat.stop();
     }
-    return { environmentId: id, restored: seed.version, status: "done" };
+    return { agentId: id, restored: seed.version, status: "done" };
 }
 /** Seeds that run in this process, so the sweep starts no second copy. */
 const running = new Set();
@@ -516,15 +516,15 @@ export async function recoverLostVolume(ctx, id) {
 export async function forkSeedOf(t, from) {
     return versionOf(t, from.environment, from.version);
 }
-/** `GET /v1/environments/{id}/versions`: its disk versions, newest first. */
+/** `GET /v1/agents/{id}/versions`: its disk versions, newest first. */
 export async function environmentVersions(ctx, id, scope) {
     assertReaches(scope, id);
     return ctx.store.tx(async (t) => {
-        (await liveEnvironment(t, id)) ?? fail(404, "Environment not found");
+        (await liveEnvironment(t, id)) ?? fail(404, "Agent not found");
         const artifact = await t.diskArtifact(id);
         const versions = artifact ? await t.artifactVersions(artifact.id) : [];
         return {
-            environmentId: id,
+            agentId: id,
             artifactId: artifact?.id ?? null,
             latest: artifact && artifact.latestVersion > 0 ? artifact.latestVersion : null,
             versions: versions
@@ -534,18 +534,18 @@ export async function environmentVersions(ctx, id, scope) {
     });
 }
 /**
- * `DELETE /v1/environments/{id}/versions/{n}`: deletes one disk version, and the stored files no
+ * `DELETE /v1/agents/{id}/versions/{n}`: deletes one disk version, and the stored files no
  * other version names. Refused while a seed reads it.
  */
 export async function deleteEnvironmentVersion(ctx, id, scope, version) {
     assertReaches(scope, id);
     const blobKey = await ctx.store.tx(async (t) => {
-        const environment = (await liveEnvironment(t, id, { lock: true })) ?? fail(404, "Environment not found");
+        const environment = (await liveEnvironment(t, id, { lock: true })) ?? fail(404, "Agent not found");
         const artifact = await t.diskArtifact(id, { lock: true });
         if (!artifact)
             return undefined;
         if (environment.diskSeed?.artifactId === artifact.id && environment.diskSeed.version === version)
-            failRetryLater(`A new volume of Environment ${id} is being seeded from version ${version}.`, "environment_busy");
+            failRetryLater(`A new volume of Agent ${id} is being seeded from version ${version}.`, "agent_busy");
         await t.lockArtifactQuota();
         const content = await t.artifactContentShas({ artifactId: artifact.id });
         const key = await t.deleteArtifactVersion(artifact.id, version);
@@ -555,7 +555,7 @@ export async function deleteEnvironmentVersion(ctx, id, scope, version) {
     });
     if (blobKey !== undefined)
         await ctx.blobs.delete(blobKey).catch(() => undefined);
-    return { environmentId: id, version, deleted: blobKey !== undefined };
+    return { agentId: id, version, deleted: blobKey !== undefined };
 }
 /**
  * Deletes Environment `id`'s disk artifact with its versions, in the transaction that deletes the

package/dist/artifacts/quota.d.ts

@@ -30,7 +30,7 @@ export declare function artifactUsage(t: Tx, quota: ArtifactQuota): Promise<Arti
 export declare function tightest(usage: readonly ArtifactUsage[]): ArtifactUsage & {
     readonly roomBytes: number;
 };
-/** Whose artifacts a total counts: `The Tenant's artifacts`, or `Environment <id>'s artifacts`. */
+/** Whose artifacts a total counts: `The Tenant's artifacts`, or `Agent <id>'s artifacts`. */
 export declare function totalSubject(total: ArtifactTotal): string;
 /** The Environment a session's artifacts belong to, if it names one. */
 export declare function environmentOfSession(t: Tx, sessionId: string | null): Promise<string | undefined>;

package/dist/artifacts/quota.js

@@ -32,9 +32,9 @@ export function tightest(usage) {
             best = entry;
     return { ...best, roomBytes: best.total.limitBytes - best.usedBytes };
 }
-/** Whose artifacts a total counts: `The Tenant's artifacts`, or `Environment <id>'s artifacts`. */
+/** Whose artifacts a total counts: `The Tenant's artifacts`, or `Agent <id>'s artifacts`. */
 export function totalSubject(total) {
-    return total.environmentId === undefined ? "The Tenant's artifacts" : `Environment ${total.environmentId}'s artifacts`;
+    return total.environmentId === undefined ? "The Tenant's artifacts" : `Agent ${total.environmentId}'s artifacts`;
 }
 /** The Environment a session's artifacts belong to, if it names one. */
 export async function environmentOfSession(t, sessionId) {

package/dist/artifacts/service.js

@@ -82,7 +82,7 @@ export function artifactView(row, versions) {
         name: row.name,
         contentType: row.contentType,
         ...(row.sessionId === null ? {} : { sessionId: row.sessionId }),
-        ...(row.environmentId === null ? {} : { environmentId: row.environmentId }),
+        ...(row.environmentId === null ? {} : { agentId: row.environmentId }),
         latestVersion: row.latestVersion,
         ...(row.labelsJson === null ? {} : { labels: JSON.parse(row.labelsJson) }),
         createdAt: row.createdAt,
@@ -332,7 +332,7 @@ export async function deleteArtifact(ctx, id, access) {
     const keys = await ctx.store.tx(async (t) => {
         const found = await readableArtifact(t, id, access);
         if (found.environmentId !== null)
-            fail(409, `Artifact ${id} holds Environment ${found.environmentId}'s disk versions: delete them with DELETE /v1/environments/{id}/versions/{version}, or delete the Environment.`);
+            fail(409, `Artifact ${id} holds Agent ${found.environmentId}'s disk versions: delete them with DELETE /v1/agents/{id}/versions/{version}, or delete the Agent.`);
         if (found.sessionId !== null)
             await lockedSession(t, found.sessionId, access);
         if (found.kind === "folder")