nylorun 0.16.0-beta → 0.17.0-beta

package/CHANGELOG.md

@@ -1,5 +1,46 @@
 # nylorun
 
+## 0.17.0-beta
+
+### Minor Changes
+
+- cc8d034: Track T3 in the clients. The SDK has `client.agents.plan(id, input)` (what a move would do), `client.agents.restart(id, { retry? })` and `list({ outdated: true })`. The CLI has `nylorun agents pin <id> <n>`, `track <id>`, `restart <id> [--retry]`, `put --dry-run`, and `list --outdated` (`--behind` kept as its alias), and prints the version an Agent moves to. Studio's Agent page moves an Agent (Move to vN, Pin, Track), restarts it on a pending version or retries a failed one, and shows "vN at next start", a version waiting for secrets, or one that failed to start. The starter's dev loop no longer deletes and remakes its Agent: the tracking Agent moves on each save.
+- 22c61ce: Protocol 16, Agents from one manifest (track T2), a fresh start. An agent manifest (v8) is one versioned document at `/v1/agent-manifests/{name}` with a `harness` section (what runs inside the loop, including the harness's id) and a `runtime` section (what an environment manifest said). The Runtime checks the two against each other when it is saved (`422 manifest_inconsistent` with `details.gaps`), in place of `requires` at session open. Agent definitions and environment manifests are gone.
+
+  Environments are Agents: `/v1/agents/{id}` and its sub-routes, made from a saved manifest only (`manifest: "name"` tracks it, `"name@n"` pins a version; either resolves once, into `resolvedVersion`), with a derived `state` (`working`, `sleeping`, `input_required`, `failing`, `paused`) and `attention`. Every session runs on one Agent (`PUT /v1/sessions/{id} { agent, ownerUserId }`) and pins its manifest version. No session is special (D71). Error codes, events (`agent.*`), scopes (`agents:write`, `agent-manifests:write`) and identity-file grants (`agents`) say Agent; model budget scope `agent` is `manifest`. Harness API 5: `turn.start.agent` replaces `turn.start.environment`, with `definition` and `loop`. Migration 0032 closes older sessions (`protocol_16`) and drops Environments with their disks and vaults.
+
+  The SDK has `client.agentManifests`, `client.agents` and `composeManifest(dir)` for three-file authoring; the CLI has `nylorun apply`, `nylorun agent-manifests`, `nylorun agents` and `nylorun migrate v8`; Studio has an Agents screen, an Agent page and an Agent manifests screen. See MIGRATION.md.
+
+- 4fa160d: Agent memory, storage and API (track T5, D72). An agent manifest's `harness.memory` (`access`: `read_write` or `read_only`; `instructions`, at most 4,096 characters) turns on the Agent's memory: Markdown files under `/memories` it keeps across sessions, wakes and upgrades. The Runtime keeps them in Postgres (`memories`, `memory_versions`, migration 0036) with a version per change and who made it. `GET /v1/agents/{id}/memories` lists them (`pathPrefix`), `GET`, `PUT` (whole content, with an optional `contentSha256` precondition: `409 memory_conflict`) and `DELETE /v1/agents/{id}/memories/{path}` read, write and delete one (or a folder), and `GET /v1/agents/{id}/memory_versions` and `.../memory_versions/{versionId}` page the versions. A fork copies the memories (the fork plan adds `memories`); a delete removes them. `@nylorun/core` adds `memoryPathOf`, `memoryDescriptionOf` and the memory contracts; new Runtime limits `memoryBytes` (100 KB) and `memoriesPerAgent` (10,000); new error code `memory_conflict`. The SDK adds `client.agents.memories`; the CLI adds `nylorun agents memories ls|cat|put|rm|versions`. The model's `memory` tool arrives in the next steps of T5.
+- 9e60e40: Protocol 17, a queue per session (track T4, D76). A message sent while the session's turn runs or waits is queued (`{status: "queued", queuedMessageId, position}`, `message.queued`) and starts the next turn when this one ends, with every queued message, each its own user message (`queue.taken`); a cancel ends the turn, not the queue. `delivery: "reject"` keeps the refusal, now `409 session_busy`, and a protocol 16 client's messages default to it, so the Host serves protocol 16 and 17. The queue holds at most the Runtime limit `sessionQueuedMessages` (`429 queue_full`), and session reads count `queuedMessages`. Our engine takes `{kind: "messages", messages}` as a turn's input. The SDK's `input` and `inputParts` take `delivery`, and the CLI's `sessions send` takes `--reject-if-busy`. See MIGRATION.md.
+- f85483d: Triggers (track T4, D74). An agent manifest's `runtime.triggers` declares `schedule` (cron with an IANA `timezone`) and `at` triggers, each with the session its runs go to (a session id, opened on the first run, or `new` for a session per run) and its prompt. They start active with a new Agent, fire on a durable timer per trigger with Postgres as the truth (one late fire after downtime, never a backfill, a fixed jitter per trigger), and each fire is a run (`started`, `queued`, `skipped` or `failed`, with a reason) at `GET /v1/agents/{id}/runs`. A schedule adds at most one queued message to a busy session. `GET /v1/agents/{id}/triggers` and `POST .../triggers/{triggerId}/pause`, `/resume` and `/run` (with an `Idempotency-Key`); Agent reads add `nextWakeAt`, and the Agent's stream adds `agent.run`, `agent.trigger_paused` and `agent.trigger_resumed`. New Runtime limits: `triggersPerAgent`, `triggerMinIntervalMs` and `triggerRunRetentionMs` (with floors), `triggerRunsPerHour`, `triggerJitterPercent`, `triggerJitterMaxMs`, `triggerPromptChars`; Host tuning `triggers.lateGraceMs` and `triggers.intervalCheckFires`. The SDK's `client.agents` adds `triggers`, `pauseTrigger`, `resumeTrigger`, `runTrigger` and `runs`; the CLI adds `nylorun agents triggers` and `nylorun agents runs`.
+- ae54de7: Webhook triggers (track T4, D75). A `webhook: "standard-webhooks"` trigger has an endpoint, `POST /v1/webhooks/{endpointId}`, an anonymous, unversioned route that takes any body up to the new Runtime limit `webhookBodyBytes` and verifies Standard Webhooks (`webhook-id`, `webhook-timestamp` within the Host's `triggers.webhookToleranceMs`, `webhook-signature`) in the keys service, which alone opens the trigger's sealed secret; anything else is `401` and writes nothing. A delivery runs the trigger once per `webhook-id` (`202 {runId, status}`); a paused trigger answers a signed one `409 trigger_paused`. `POST /v1/agents/{id}/triggers/{triggerId}/secret` makes or replaces the `whsec_` secret, shown once (`agent.trigger_secret_rotated`); trigger reads show `webhookUrl` and `secretSet`. The payload reaches the model under the trigger's prompt in a labelled `<trigger-payload>` block. The SDK adds `agents.rotateWebhookSecret`, and the CLI `nylorun agents triggers new-secret`.
+
+### Patch Changes
+
+- Pin core to the tested release.
+- Pin agents to the tested release.
+- Pin admin to the tested release.
+- Pin runtime to the tested release.
+- Pin studio to the tested release.
+- Updated dependencies [218b078]
+- Updated dependencies [cc8d034]
+- Updated dependencies [22c61ce]
+- Updated dependencies [1ded443]
+- Updated dependencies [76dcd11]
+- Updated dependencies [bf942ed]
+- Updated dependencies [4fa160d]
+- Updated dependencies [9fed948]
+- Updated dependencies [ffeb3bb]
+- Updated dependencies [9e60e40]
+- Updated dependencies [f85483d]
+- Updated dependencies [ae54de7]
+- Updated dependencies
+- Updated dependencies
+  - @nylorun/core@0.24.0-beta
+  - @nylorun/agents@0.24.0-beta
+  - @nylorun/admin@0.19.0-beta
+
 ## 0.16.0-beta
 
 ### Minor Changes

package/README.md

@@ -15,7 +15,7 @@ and S2, serving exactly that Tenant, and its name is the Tenant's name.
 `nylorun start` in a project creates the project's Tenant (the Runtime creates
 it on its first start) and links the project to it; anywhere else, it starts
 the Tenant `default`. Projects that must not share agents, credentials or
-history run separate Tenants. The `tenant` and `environments` groups act on a
+history run separate Tenants. The `tenant`, `agents` and `apply` commands act on a
 Tenant over its APIs, so they work on a remote installation too
 ([below](#remote-installations)). Depends on `@nylorun/core`,
 `@nylorun/admin` and `@nylorun/agents` among Nylorun packages and never imports
@@ -50,32 +50,33 @@ nylorun studio [--tenant <name>] [--no-open]   # sign a browser in to Studio on
 nylorun doctor [--json]            # prerequisites and the Tenant's health
 nylorun doctor sandbox [--tenant <name>] [--json]   # the sandbox backend the Tenant's Host offers
 
-# agents, sessions, environments, artifacts: the Runtime API (an application key, or NYLORUN_TOKEN)
+# apply, agent-manifests, agents, sessions, artifacts: the Runtime API (an application key, or NYLORUN_TOKEN)
 # every one takes --tenant <name>, and --as <subject> [--scope <scope>]... to act for a person
-nylorun agents list [--json]
-nylorun agents get <id>                     # its manifest
-nylorun agents save <manifest.json|-> [--files <dir>]... [--implementation-version <v>] [--dry-run]
-nylorun sessions list [--agent <id>] [--status <s>] [--environment <id>] [--owner <user>] [--limit <n>] [--cursor <c>] [--json]
-nylorun sessions create --agent <id> --owner <user> [--environment <id>] [--id <id>] [--info <json>]
+nylorun apply [<dir>...] [--dry-run] [--if-match <n>]   # plan, then save each folder's agent.manifest.json, its files uploaded
+nylorun migrate v8 <agent.json> [--runtime <environment-manifest.json>] [--name <name>] [--out <dir>]   # the three files from a v7 manifest; reads no Runtime
+nylorun agent-manifests list [--json]       # name, latest version, runtime kind, harness, Agents
+nylorun agent-manifests get <name>[@<n>] | versions <name> | rm <name>
+nylorun agents list [--state <s>] [--manifest <name>] [--label <key=value>]... [--behind] [--limit <n>] [--cursor <c>] [--json]   # --behind: on an older manifest version
+nylorun agents get|stop|reset|rm|snapshot|versions <id>
+nylorun agents put <id> --manifest <name[@n]> [--owner <user>] [--label <key=value>]...   # name tracks its latest version, name@n pins one
+nylorun agents fork <id> <new-id> [--manifest <name[@n]>] [--disk <latest|n|empty>] [--secrets <copy|none>] [--dry-run]   # onto a new manifest version
+nylorun agents restore <id> <version|latest>
+nylorun agents delete-version <id> <version>
+nylorun agents events <id> [--from <n>] [--types <type,…>] [--since <time>] [--until <time>]
+nylorun agents triggers list <id> | pause|resume <id> <trigger> | run <id> <trigger> [--idempotency-key <k>] | new-secret <id> <trigger>
+nylorun agents runs <id> [--trigger <id>] [--limit <n>] [--cursor <c>]   # what each trigger fire came to
+nylorun agents memories ls|cat|put|rm|versions <id> [<path>] [<file|->]   # its memories (track T5); put seeds one
+nylorun agents secrets list|get|put|rm <id> [<name>] [<secret.json|->]   # put without a file: a slot's value on stdin
+nylorun sessions list [--agent <id>] [--manifest <name>] [--status <s>] [--owner <user>] [--limit <n>] [--cursor <c>] [--json]
+nylorun sessions create --agent <id> --owner <user> [--id <id>] [--info <json>]   # a session on Agent <id>
 nylorun sessions get <id>
-nylorun sessions send <id> [<text>] [--data <json>] [--file <artifact>[@<version>]]... [--idempotency-key <k>]
+nylorun sessions send <id> [<text>] [--data <json>] [--file <artifact>[@<version>]]... [--idempotency-key <k>] [--reject-if-busy]   # queued while a turn runs
 nylorun sessions approve <id> <interaction> [--deny]
 nylorun sessions respond <id> <interaction> <json>
 nylorun sessions cancel <id> [--reason <text>]
 nylorun sessions watch <id> [--follow] [--cursor <c>]   # events as JSON lines until interrupted
 nylorun sessions history|usage|calls [--tool]|trace <id> …
 nylorun sessions exec <id> [--timeout <s>] -- <command>...   # bash in the session's sandbox
-nylorun environments list [--label <key=value>]... [--behind] [--limit <n>] [--cursor <c>] [--json]   # --behind: made from an older manifest version
-nylorun environments get|stop|reset|delete|snapshot|versions <id>
-nylorun environments put <id> --manifest <name[@n]> [--label <key=value>]...   # made from a manifest version; what it runs never changes
-nylorun environments put <id> [<inline.json|->] [--kind <virtual|pod|none>] [--label <key=value>]...
-nylorun environments fork <id> <new-id> [--manifest <name[@n]>] [--disk <latest|n|empty>] [--secrets <copy|none>] [--dry-run]   # onto a new manifest version
-nylorun environments restore <id> <version|latest>
-nylorun environments delete-version <id> <version>
-nylorun environments events <id> [--from <n>] [--types <type,…>] [--since <time>] [--until <time>]
-nylorun environments secrets list|get|put|rm <id> [<name>] [<secret.json|->]   # put without a file: a slot's value on stdin
-nylorun environments manifests list [--json] | get <name> [--version <n>] | versions <name> | rm <name>
-nylorun environments manifests save <manifest.json>... [--if-match <n>] [--dry-run]   # files with "from": a folder, uploaded by hash
 nylorun artifacts list [--session <id>] [--label <key=value>]... [--limit <n>] [--cursor <c>] [--json]
 nylorun artifacts get|tree|diff|link|rm <id> …
 nylorun artifacts upload <file|-> [--name <name>] [--content-type <type>] [--session <id>] [--label <key=value>]... [--to <id>]
@@ -83,7 +84,7 @@ nylorun artifacts download <id> [--version <n>] [--output <file>]
 nylorun artifacts zip <id> [--version <n>] --output <file>
 
 # tenant: the Tenant's settings (Management API, a management key)
-nylorun tenant reset [--sessions|--environments|--all] [--yes] [--tenant <name>]
+nylorun tenant reset [--sessions|--agents|--all] [--yes] [--tenant <name>]
 nylorun tenant keys put <id> [--management] [--tenant <name>]   # create or rotate key <id>; prints it once
 nylorun tenant keys list [--tenant <name>] [--json]   # id, role, when issued
 nylorun tenant keys rm <id> [--tenant <name>]         # it stops working at once
@@ -92,13 +93,13 @@ nylorun tenant models catalog|providers|get [--tenant <name>] [--json]   # the m
 nylorun tenant models set [--tenant <name>]           # sign in to a model provider and set the Tenant's model
 nylorun tenant models set --provider <id> --model <id> [--base-url <url>] [--tenant <name>]   # the same, with an API key piped in on stdin (CI)
 nylorun tenant models select <provider> [--model <id>] [--tenant <name>]   # use another provider that has a credential
-nylorun tenant usage [--scope tenant|agent|turn] [--id <id>] [--period day|month|total] [--tenant <name>]   # calls, tokens and cost (JSON)
+nylorun tenant usage [--scope tenant|manifest|turn] [--id <id>] [--period day|month|total] [--tenant <name>]   # calls, tokens and cost (JSON); manifest: the Agents made from agent manifest <id>
 nylorun tenant calls [--after <cursor>] [--limit <n>] [--tenant <name>]   # every recorded model call as NDJSON, until caught up
-nylorun tenant budgets [get | put <file|->] [--tenant <name>]       # the model spend caps
+nylorun tenant budgets [get | put <file|->] [--tenant <name>]       # the model spend caps: tenant, manifest (id: its name) or turn
 nylorun tenant tool-policy [get | put <file|->] [--tenant <name>]   # the Tool Gate's rules
-nylorun tenant settings sandbox|artifacts|skills|limits [get | put <file|->] [--tenant <name>]   # Environment, artifact store and skill settings, Runtime limits
-nylorun tenant coverage --agent <id> [--environment <id>] [--tenant <name>] [--json]   # which secret each MCP server and HTTP tool would get
-nylorun tenant mcp inspect <url> [--server <name>] [--environment <id>] [--sse] [--tenant <name>] [--json]
+nylorun tenant settings sandbox|artifacts|skills|limits [get | put <file|->] [--tenant <name>]   # Agents' environments, artifact store and skill settings, Runtime limits
+nylorun tenant coverage --agent <id> [--tenant <name>] [--json]   # which secret of Agent <id>'s vault each MCP server and HTTP tool would get
+nylorun tenant mcp inspect <url> [--server <name>] [--agent <id>] [--sse] [--tenant <name>] [--json]
 
 # local: the Tenants on this machine (Docker and kubectl)
 nylorun local ls [--json]          # the Tenants on this machine, with their state, memory and URLs
@@ -116,10 +117,13 @@ stops the containers and keeps the volumes, so no Tenant data is lost. A command
 that moved into a group, or was removed, exits 2 naming its replacement:
 `nylorun logs`, `ls`, `delete`, `reset` and `telemetry` are under `local` (and
 `sandbox enable|disable|status`); `nylorun key` and `mcp` are under `tenant`;
-`nylorun sandbox ls|rm` is `nylorun environments list|delete`; `nylorun
-configure` is `nylorun tenant models set`. `nylorun dev`, `nylorun env` and the
-MCP OAuth `connect` subcommand of `nylorun tenant mcp` (protocol 10: write a key
-or a gateway credential as an Environment's secret instead) are gone.
+`nylorun sandbox ls|rm` is `nylorun agents list|rm`; `nylorun environments` is
+`nylorun agents` (protocol 16: Environments are Agents, and environment manifests
+are the runtime section of an agent manifest); `nylorun agents save` is `nylorun
+apply`; `nylorun configure` is `nylorun tenant models set`. `nylorun dev`,
+`nylorun env` and the MCP OAuth `connect` subcommand of `nylorun tenant mcp`
+(protocol 10: write a key or a gateway credential as an Agent's secret instead)
+are gone.
 
 The package's second command, `nylo`, was the Runtime client until nylorun took
 its commands. For one release it names the `nylorun` command that replaced each
@@ -260,19 +264,21 @@ shows each key's id, role and when it was issued, never the keys; `nylorun
 tenant keys rm <id>` deletes one. Ids match `^[a-z][a-z0-9-]{0,31}$`; `studio`
 belongs to Studio and `bootstrap` to `NYLORUN_MANAGEMENT_KEY_FILE`, and both are
 refused. Putting an id that holds the other role is refused. Give each app server
-its own application key. On a local Tenant, the `tenant` and `environments`
+its own application key. On a local Tenant, the `tenant` and Runtime API
 commands use the linked project's keys, or the keys `cli` and `cli-management`
 they put once and keep in `<Host root>/cli-credentials.json` (mode 0600).
 
 ## MCP servers
 
-An agent names its MCP servers by URL; a session gets a credential for a URL from
-the Environment it is opened on (`createSession({ environment })`): a secret of that
-Environment, a `bearer` token or a `headers` map, with `via` and an identity
-header when an MCP gateway holds each person's sign-in. Write it with
-`nylorun environments secrets put <id> <name> <secret.json|->` (the secret's JSON
+An agent manifest names its MCP servers by URL, and may name the runtime
+section's secret slot each one authenticates with (`credential`); a session gets
+a credential for a URL from the Agent it runs on (`createSession({ agent })`): a
+secret of that Agent's vault, a `bearer` token or a `headers` map, with `via` and
+an identity header when an MCP gateway holds each person's sign-in. Write it with
+`nylorun agents secrets put <id> <name>` (a slot's value on standard input) or
+`nylorun agents secrets put <id> <name> <secret.json|->` (the secret's JSON
 comes from a file or standard input, never the command line),
-`client.environments.secrets.put(id, name, secret)` of `@nylorun/agents` (the
+`client.agents.secrets.put(id, name, secret)` of `@nylorun/agents` (the
 Runtime API, an application key) or in Studio.
 The whole flow, with gateway recipes, is in
 [DEPLOYMENT.md](../../guides/DEPLOYMENT.md#mcp-servers-and-http-tools).
@@ -280,7 +286,7 @@ The whole flow, with gateway recipes, is in
 `nylorun tenant mcp inspect <url>` shows what a remote MCP server offers before an
 agent names it, through the Tenant's Management API
 (`POST /v1/tenant/mcp/preview`, with the management key). The Runtime connects
-with Environment `<id>`'s credential for `<url>` when `--environment <id>` names one
+with Agent `<id>`'s credential for `<url>` when `--agent <id>` names one
 (without it, no credential is sent), lists the tools within 15 s and calls none. It
 prints a table of each tool's model name, input schema size, hints
 (`read-only`, `destructive`, `idempotent`) and description, then the tools
@@ -288,7 +294,7 @@ renamed for the model. `--server` is the server name your manifest uses (default
 the host's name, `linear` for `mcp.linear.app`); `--sse` speaks the older SSE
 transport; `--json` prints the Runtime's answer. A server that answers `401`
 needs a credential: it says so, and names the server's sign-in from its
-protected-resource metadata, since such a server needs a key in an Environment's
+protected-resource metadata, since such a server needs a key in an Agent's
 secrets or an MCP gateway that holds each person's sign-in. A server it cannot list exits 1 with
 the reason (`mcp.unreachable` for an address the Runtime refuses).
 
@@ -382,20 +388,22 @@ on every start and writes the result to `NYLORUN_STUDIO_ANALYTICS_ID` in
 
 ## Sandboxes
 
-A session gets a sandbox from the Environment it is opened on
-(`createSession({ environment: id })`; protocol 11): an Environment has its own id
-(`PUT /v1/environments/{id}`, `client.environments` in `@nylorun/agents`), one
-sandbox and one vault of secrets, and outlives the sessions that name it. A session
-opened on none has no sandbox. Kind `virtual` (the default) runs on the Runtime's
-**virtual** backend: an emulated shell in the Runtime process, with no extra
-containers. It is not a VM or container boundary. Kind `pod` runs in a pod on a
-cluster (below).
-
-`nylorun environments list` lists the Tenant's Environments with their kind,
-state, sessions and labels; `nylorun environments delete <id>` deletes one, with its files
-and vault (refused while a turn runs in it). Neither starts a stopped Tenant
-(exit 3). The Tenant's limits for Environments (`limits.environments`, `idle`,
-resources, network) are `PUT /v1/tenant/sandbox` on the Management API.
+A session gets a sandbox from the Agent it runs on (`createSession({ agent: id })`;
+protocol 16): an Agent has its own id (`PUT /v1/agents/{id}`, `client.agents` in
+`@nylorun/agents`), is made from a saved agent manifest, has the sandbox its
+manifest's `runtime.kind` gives and one vault of secrets, and outlives its
+sessions. Kind `virtual` runs on the Runtime's **virtual** backend: an emulated
+shell in the Runtime process, with no extra containers. It is not a VM or
+container boundary. Kind `pod` runs in a pod on a cluster (below); kind `none`
+has no sandbox, and a manifest with no runtime section makes Agents of kind
+`none`.
+
+`nylorun agents list` lists the Tenant's Agents with the manifest version each
+runs, its kind, state, sessions, owner and labels; `nylorun agents rm <id>`
+deletes one, with its files and vault (refused while a turn runs on it). Neither
+starts a stopped Tenant (exit 3). The Tenant's limits for Agents
+(`limits.environments`, `idle`, resources, network) are `PUT /v1/tenant/sandbox`
+on the Management API.
 
 ### Pods on a cluster (preview)
 
@@ -411,7 +419,7 @@ service to the Tenant: the one container holding the cluster credentials
 (`<Host root>/sandboxes/`). On kind under Linux, pass `--host-address 172.17.0.1`.
 `nylorun local sandbox disable` removes the service (`--delete-namespace` also deletes
 the namespace and every sandbox in it). Sessions run in a pod when their
-Environment has kind `pod` (`client.environments.put(id, { kind: "pod" })`).
+Agent's manifest has `runtime.kind` `pod`.
 
 ## Host root
 
@@ -431,14 +439,14 @@ containers, volumes and Host root: the vault key (KEK) and all its data go with
 
 ## Remote installations
 
-The `agents`, `sessions`, `environments`, `artifacts` and `tenant` groups,
+The `apply`, `agent-manifests`, `agents`, `sessions`, `artifacts` and `tenant` commands,
 `status` and `doctor sandbox` act on a Tenant over its APIs. Without `--tenant`, they act on the installation the
 environment names, when it names one for their API:
 
 | Variables | Acts on |
 | --- | --- |
 | `NYLORUN_RUNTIME_URL` and `NYLORUN_MANAGEMENT_KEY` | `status`, `doctor sandbox` and `tenant` (the Management API) |
-| `NYLORUN_RUNTIME_URL` and `NYLORUN_SERVER_KEY` | `agents`, `sessions`, `environments` and `artifacts` (the Runtime API) |
+| `NYLORUN_RUNTIME_URL` and `NYLORUN_SERVER_KEY` | `apply`, `agent-manifests`, `agents`, `sessions` and `artifacts` (the Runtime API) |
 | `NYLORUN_RUNTIME_URL` and `NYLORUN_TOKEN` | the same, with an identity provider's token in place of the key: the person it names, with the scopes it grants |
 
 `NYLORUN_RUNTIME_URL` alone is an app's and names nothing, as for
@@ -459,16 +467,52 @@ sessions and to the scopes given (`--scope`, repeatable; default
 `sessions:own`). Use it to see what one person sees, or to act on their sessions
 from a terminal.
 
-### Saving an agent from its manifest
+### Agent manifests: `apply`
 
-`nylorun agents save agent.json --files skills/` saves the agent a manifest
-describes, as `saveAgent` does from code. A manifest names each definition file
-(a skill folder's files) by the SHA-256 of its bytes, so the files under the
-`--files` folders are matched by content, whatever their paths; the ones the
-Runtime does not hold are uploaded first (`PUT /v1/files/sha256:…`). A file the
-manifest names but no folder holds stops the save before any request, naming
-where the manifest names it. `nylorun agents get <id>` prints a saved agent's
-manifest; the Runtime does not hand files back, so keep them with the manifest.
+An agent runs from a saved **agent manifest** (protocol 16): one named, versioned
+document with a harness section (instructions, tools, skills, MCP servers,
+plugins) and a runtime section (kind, image, network, setup, files, secret
+slots). Author it as files, one folder per agent:
+
+```
+agents/triage/agent.manifest.json     # { "manifestSchemaVersion": 8, "name": "triage",
+                                      #   "harness": "./harness.manifest.json",
+                                      #   "runtime": "../../shared/runtime.manifest.json" }
+agents/triage/harness.manifest.json   # instructions, tools, "skills": "./skills",
+                                      # "mcpServers": "./mcp.json", "plugins": ["../../plugins/github"],
+                                      # "credentials": { "linear": "linear" }, "requires": { "sandbox": "any" }
+agents/triage/skills/<skill>/SKILL.md
+shared/runtime.manifest.json          # kind, image, "files": [{ "path": "/workspace/kit", "from": "./kit" }], secrets
+```
+
+`nylorun apply agents/triage` composes the folder as `composeManifest` of
+`@nylorun/agents` does (each path relative to the file that names it; skills,
+plugins and `from` folders hashed; `credentials` set on the servers and HTTP
+tools it names; `requires` checked against the runtime and left out), prints the
+plan (`triage: version 2 → 3`, then each change as `section path op`, warnings
+and errors) and saves it under `If-Match` set to the version it planned
+against, uploading the files the Runtime does not hold (`PUT /v1/files/sha256:…`).
+A manifest whose sections do not fit, or whose runtime misses what its harness
+`requires`, is an error: nothing is saved and the command exits 1. `--dry-run`
+prints the plans only; `--if-match <n>` saves only over version `n`.
+`nylorun apply agents/` applies every subfolder with an `agent.manifest.json`;
+every folder composes before anything is sent.
+
+`nylorun agent-manifests list` shows each manifest's latest version, runtime
+kind, harness and the Agents made from it; `get <name>[@<n>]` prints a version,
+`versions <name>` its history and `rm <name>` deletes it (refused while an Agent
+was made from it). Make an Agent from it with `nylorun agents put <id> --manifest
+<name>` (tracking its latest version) or `--manifest <name>@<n>` (pinned), and
+open sessions on it with `nylorun sessions create --agent <id> --owner <user>`.
+
+`nylorun migrate v8 agent.json [--runtime box.json] [--out agents/triage]`
+writes the three files from an agent manifest v7 (as `nylorun agents save` took
+it) and the environment manifest v1 its sessions ran in: the environment
+manifest's fields become the runtime file, its `harness` the harness file's `id`,
+and v7's `requires` stays in the harness file for `apply` to check. With no
+environment manifest the kind is `pod` when the agent requires one, `virtual`
+when it has skills or requires a sandbox, else `none`. It overwrites no file and
+prints the gaps to fix before `apply`.
 
 ### `local reset` or `tenant reset`
 
@@ -477,7 +521,7 @@ Both reset a Tenant, in different ways:
 | | `nylorun local reset` | `nylorun tenant reset` |
 | --- | --- | --- |
 | Acts on | the local Tenant on this machine, through Docker | the Tenant, local or remote, through the Management API with a management key |
-| Deletes | all the Tenant's data: volumes, `tenant/` and the vault key; the next `start` creates it anew, with a new id, and relinks the project | the sessions (the default), the Environments (`--environments`) or all the data (`--all`) after draining work in flight; the Tenant, its keys and the Project link are kept |
+| Deletes | all the Tenant's data: volumes, `tenant/` and the vault key; the next `start` creates it anew, with a new id, and relinks the project | the sessions (the default), the Agents with their vaults, disks and sessions (`--agents`) or all the data (`--all`) after draining work in flight; the Tenant, its keys and the Project link are kept |
 
 `nylorun tenant reset --all` asks first; pass `--yes` when not in a terminal.
 `nylorun local reset` asks too, or takes `--yes`.
@@ -558,7 +602,7 @@ them. The Runtime's own are `NYLORUN_TUNING`, which `nylorun start` passes on.
 | 0 | Success |
 | 1 | Generic failure, including a missing Docker or Compose v2 |
 | 2 | Usage error (including no Tenant selected, or `local delete` without `--yes`), or a removed or moved command |
-| 3 | `status`: the Runtime is not answering; `tenant`, `environments`, `local sandbox`: the local Tenant is not running; `stop`/`local logs`: no Tenant yet; `local delete`: no such Tenant; `start`: a Tenant created by nylorun 0.5 (reset it) |
+| 3 | `status`: the Runtime is not answering; `tenant`, `agents`, `apply`, `local sandbox`: the local Tenant is not running; `stop`/`local logs`: no Tenant yet; `local delete`: no such Tenant; `start`: a Tenant created by nylorun 0.5 (reset it) |
 | 4 | The Runtime port is held by another Host |
 | 5 | `up`/`start`/`studio`: this nylorun pins a Runtime older than the one that last ran the Tenant; update nylorun, or `start --allow-downgrade` |
 | 7 | The containers, the Tenant or Studio did not become ready (an unavailable Tenant's cause is printed) |
@@ -577,7 +621,7 @@ them. The Runtime's own are `NYLORUN_TUNING`, which `nylorun start` passes on.
 | Studio login expired | `nylorun studio` |
 | Which Studio is which | `nylorun local ls` lists each Tenant's Studio URL; `nylorun studio --tenant <name>` opens one signed in |
 | `Tenant … was created by nylorun 0.5` (exit 3) | `nylorun local reset --tenant <name>` (its data starts fresh) |
-| `tenant` or `environments`: the Tenant is not running or not open | `npx nylorun start`, then `npx nylorun status`, which shows the cause and its `repair` |
+| `tenant`, `agents` or `apply`: the Tenant is not running or not open | `npx nylorun start`, then `npx nylorun status`, which shows the cause and its `repair` |
 | No management key for a remote installation | Set `NYLORUN_MANAGEMENT_KEY`; on the Runtime's machine `nylorun tenant keys put <id> --management` issues one |
 | `403 key_role_mismatch` | The key belongs to the other API: a management key for the Management API, an application key for the Runtime API |
 | Old Project link refused | `npx nylorun start` in the project |

package/dist/cli.js

@@ -12,14 +12,24 @@ ${stackUsage}
   doctor sandbox [--tenant <name>] [--json]
                                       the sandbox backend the Tenant's Host offers
 
+Agent manifests:
+  apply [<dir>...] [--dry-run] [--if-match <n>]
+                                      save the agent manifest each folder's agent.manifest.json
+                                      describes, with the files it names (Runtime API)
+  migrate v8 <agent.json> [--runtime <environment-manifest.json>] [--out <dir>]
+                                      write the three manifest files from an agent manifest v7
+                                      and an environment manifest v1 (reads no Runtime)
+
 Groups, each with its own --help:
-  agents        list | get | save     the Tenant's agents (Runtime API, an application key)
+  agent-manifests  list | get | versions | rm
+                                      the Tenant's agent manifests (Runtime API)
+  agents        list | get | put | fork | stop | reset | rm | snapshot | restore
+                versions | delete-version | events | secrets
+                                      the Tenant's Agents, made from saved manifests; sessions
+                                      run on them (Runtime API)
   sessions      list | create | get | send | approve | respond | cancel | watch | history
                 usage | calls | trace | exec
                                       the Tenant's sessions (Runtime API)
-  environments  list | get | put | fork | stop | reset | delete | snapshot | restore
-                versions | delete-version | events | secrets | manifests
-                                      the Tenant's Environments (Runtime API)
   artifacts     list | get | upload | download | tree | diff | zip | link | rm
                                       the Tenant's file artifacts (Runtime API)
   tenant        reset | keys | signing-keys | models | usage | calls | budgets | tool-policy |
@@ -32,7 +42,8 @@ A command acts on the local Tenant --tenant names, else the linked project's, el
 project) the default Tenant; NYLORUN_HOME sets its Host root (default
 ~/.nylorun/tenants/<name>). Without --tenant, NYLORUN_RUNTIME_URL names a remote installation:
 with NYLORUN_MANAGEMENT_KEY for status, doctor sandbox and tenant; with NYLORUN_SERVER_KEY, or an
-identity provider's token in NYLORUN_TOKEN, for agents, sessions, environments and artifacts.
+identity provider's token in NYLORUN_TOKEN, for apply, agent-manifests, agents, sessions and
+artifacts.
 The Runtime API groups act for a person with --as <subject> [--scope <scope>]...`;
 const localUsage = `nylorun local <command>
 
@@ -54,7 +65,8 @@ const MOVED = {
     ls: "nylorun ls moved: nylorun local ls",
     delete: "nylorun delete moved: nylorun local delete",
     telemetry: "nylorun telemetry moved: nylorun local telemetry",
-    reset: "nylorun reset moved: nylorun local reset deletes a local Tenant's volumes; nylorun tenant reset clears its sessions or Environments through the Management API",
+    reset: "nylorun reset moved: nylorun local reset deletes a local Tenant's volumes; nylorun tenant reset clears its sessions or Agents through the Management API",
+    environments: "nylorun environments is nylorun agents in protocol 16: Environments are Agents, made from saved agent manifests (nylorun apply). Environment manifests are the runtime section of an agent manifest (nylorun migrate v8).",
     key: "nylorun key moved: nylorun tenant keys put|list|rm",
     keys: "nylorun keys is nylorun tenant keys put|list|rm",
     mcp: "nylorun mcp moved: nylorun tenant mcp inspect <url>",
@@ -66,10 +78,10 @@ const MOVED = {
     runtime: "nylorun runtime was removed: the local Runtime runs in Docker Compose. Use nylorun up|down|status and nylorun local logs.",
 };
 const SANDBOX_MOVED = {
-    ls: "nylorun sandbox ls moved: nylorun environments list",
-    list: "nylorun sandbox ls moved: nylorun environments list",
-    rm: "nylorun sandbox rm moved: nylorun environments delete <id>",
-    delete: "nylorun sandbox rm moved: nylorun environments delete <id>",
+    ls: "nylorun sandbox ls moved: nylorun agents list",
+    list: "nylorun sandbox ls moved: nylorun agents list",
+    rm: "nylorun sandbox rm moved: nylorun agents rm <id>",
+    delete: "nylorun sandbox rm moved: nylorun agents rm <id>",
 };
 const LOCAL_UI_REMOVED = "--local-ui was removed: Studio runs in its own container. Run nylorun studio.";
 const usageError = (message) => new CliError(message, 2);
@@ -150,11 +162,18 @@ async function main() {
         process.exitCode = await tenantCommand(defaultStackDeps(env), args);
         return;
     }
-    if (command === "agents" || command === "sessions" || command === "environments" || command === "artifacts") {
+    if (command === "apply" ||
+        command === "migrate" ||
+        command === "agent-manifests" ||
+        command === "agents" ||
+        command === "sessions" ||
+        command === "artifacts") {
         const group = {
+            apply: async () => (await import("./client/apply.js")).applyCommand,
+            migrate: async () => (await import("./client/migrate.js")).migrateCommand,
+            "agent-manifests": async () => (await import("./client/agent-manifests.js")).agentManifestsCommand,
             agents: async () => (await import("./client/agents.js")).agentsCommand,
             sessions: async () => (await import("./client/sessions.js")).sessionsCommand,
-            environments: async () => (await import("./client/environments.js")).environmentsCommand,
             artifacts: async () => (await import("./client/artifacts.js")).artifactsCommand,
         }[command];
         process.exitCode = await (await group())(defaultStackDeps(env), args);

package/dist/client/agent-manifests.d.ts

@@ -0,0 +1,4 @@
+import type { StackDeps } from "../stack/commands.js";
+export declare const agentManifestsUsage: string;
+/** `nylorun agent-manifests <command> ...` */
+export declare function agentManifestsCommand(deps: StackDeps, args: readonly string[]): Promise<number>;

package/dist/client/agent-manifests.js

@@ -0,0 +1,100 @@
+import { parseAgentManifestRef } from "@nylorun/core/contracts";
+import { parseFlags, positional, printJson, printTable, runtimeCall, runtimeClient, runtimeFlagsUsage, usageError, } from "./runtime.js";
+export const agentManifestsUsage = `nylorun agent-manifests <command>
+
+The Tenant's agent manifests, through the Runtime API with an application key (or
+NYLORUN_TOKEN). Save one with nylorun apply <dir>.
+
+  list [--json]                       each manifest's latest version: its runtime kind, harness
+                                      and the Agents made from it
+  get <name>[@<n>]                    a manifest's latest version (or version n), as JSON
+  versions <name>                     its versions, with the Agents made from each
+  rm <name>                           delete every version (refused while an Agent was made
+                                      from one)
+
+${runtimeFlagsUsage}`;
+/** The harness that runs a manifest's loop, as the list prints it. */
+function harnessOf(view) {
+    const { harness } = view.manifest;
+    const id = harness.id ?? "nylorun";
+    return "kind" in harness && harness.kind === "workflow" ? `${id} (flow)` : id;
+}
+async function list(deps, args) {
+    const usage = "nylorun agent-manifests list [--json]";
+    const flags = parseFlags(args, { booleans: ["--json"] }, usage);
+    positional(flags, 0, usage);
+    const { client, connection } = await runtimeClient(deps, flags);
+    const manifests = await runtimeCall(() => client.agentManifests.list());
+    if (flags.booleans.has("--json")) {
+        printJson(deps, manifests);
+        return 0;
+    }
+    if (manifests.length === 0)
+        deps.out(`No agent manifests on ${connection.label}. Save one with nylorun apply <dir>.`);
+    else
+        printTable(deps, [
+            ["NAME", "VERSION", "KIND", "HARNESS", "AGENTS"],
+            ...manifests.map((view) => [
+                view.name,
+                String(view.version),
+                view.manifest.runtime?.kind ?? "none",
+                harnessOf(view),
+                String(view.agents),
+            ]),
+        ]);
+    return 0;
+}
+async function get(deps, args) {
+    const usage = "nylorun agent-manifests get <name>[@<n>]";
+    const flags = parseFlags(args, {}, usage);
+    const [ref] = positional(flags, 1, usage);
+    const parsed = parseAgentManifestRef(ref);
+    if (!parsed)
+        throw usageError(`${ref} is not an agent manifest's name, or name@version such as triage@3.`);
+    const { client } = await runtimeClient(deps, flags);
+    printJson(deps, await runtimeCall(() => client.agentManifests.get(parsed.name, parsed.version)));
+    return 0;
+}
+async function versions(deps, args) {
+    const usage = "nylorun agent-manifests versions <name>";
+    const flags = parseFlags(args, {}, usage);
+    const [name] = positional(flags, 1, usage);
+    const { client } = await runtimeClient(deps, flags);
+    printJson(deps, await runtimeCall(() => client.agentManifests.versions(name)));
+    return 0;
+}
+async function remove(deps, args) {
+    const usage = "nylorun agent-manifests rm <name>";
+    const flags = parseFlags(args, {}, usage);
+    const [name] = positional(flags, 1, usage);
+    const { client, connection } = await runtimeClient(deps, flags);
+    const deleted = await runtimeCall(() => client.agentManifests.delete(name));
+    if (!deleted.deleted) {
+        deps.err(`No agent manifest ${name} on ${connection.label}.`);
+        return 1;
+    }
+    deps.out(`Deleted agent manifest ${name}: every version.`);
+    return 0;
+}
+const COMMANDS = {
+    list,
+    ls: list,
+    get,
+    versions,
+    rm: remove,
+    delete: remove,
+};
+/** `nylorun agent-manifests <command> ...` */
+export async function agentManifestsCommand(deps, args) {
+    const [sub, ...rest] = args;
+    if (sub === "--help" || sub === "-h") {
+        deps.out(agentManifestsUsage);
+        return 0;
+    }
+    if (sub === "save")
+        throw usageError("Save an agent manifest with nylorun apply <dir>: it composes agent.manifest.json and the files it names.");
+    const command = sub !== undefined && Object.hasOwn(COMMANDS, sub) ? COMMANDS[sub] : undefined;
+    if (!command)
+        throw usageError(sub ? `Unknown agent-manifests command ${sub}.\n${agentManifestsUsage}` : agentManifestsUsage);
+    return command(deps, rest);
+}

package/dist/client/agents.d.ts

@@ -1,6 +1,4 @@
 import type { StackDeps } from "../stack/commands.js";
 export declare const agentsUsage: string;
-/** Every `sha256:<hex>` a manifest names under a `files` map, with where it names it. */
-export declare function namedFiles(manifest: unknown): Map<string, string>;
-/** `nylorun agents <list|get|save> ...` */
+/** `nylorun agents <command> ...` */
 export declare function agentsCommand(deps: StackDeps, args: readonly string[]): Promise<number>;