nylorun 0.15.1-beta → 0.17.0-beta

package/CHANGELOG.md

@@ -1,5 +1,139 @@
 # 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
+
+- 0a2fbc5: **Artifacts reach the harness through the Harness API; `read_artifact` and `save_artifact` run in the harness (protocol 15, Harness API 4).** The first step of the harness boundary: model-facing work belongs to the harness, and the Runtime offers primitives and holds limits and access. A fresh start for agent sessions: the Runtime speaks protocol 15 only. See MIGRATION.md.
+
+  - **The artifact seam.** A harness reads and writes the artifacts of the run it holds: `artifact.read {artifactId, version?, offset?, length?}` answers the version's metadata (`ArtifactMetaSchema`) and its bytes from `offset`, at most `turn.start.limits.chunkBytes`; `artifact.write` (`begin`, `chunk`, `commit`, `abort`) makes a file artifact of the session or a new version of one of its own, streamed with backpressure into the Object store and committed in Postgres within the Tenant's and the Environment's artifact limits. The scope is always the run's session: its own artifacts, and the Tenant-wide ones its messages named; anything else is the new error code `not_found`, alike. A write's `key` makes it idempotent within the session (`artifact_versions.write_key`, migration 0028), and its `effectId` links the artifact to a tool call of the turn, whose call id `artifact.created` carries. An upload the run leaves open commits nothing. Client helpers: `readArtifact`, `openArtifactWrite`, `writeArtifactBytes`, `toBase64` and `fromBase64` in `@nylorun/core/harness-api`.
+  - **Our harness runs the artifact tools.** `read_artifact` (every agent) and `save_artifact` (with a sandbox) are our engine's tools, defined in `@nylorun/harness` (`artifactToolsFor`, `runArtifactTool`) and run over the seam and the run's sandbox files (`HarnessExecutors.files`, `SandboxManager.writeBytes`); their calls are kind `harness`. `save_artifact` keys its write by its effect id. `read_artifact` takes `path` with a sandbox, which copies the whole artifact into it, and hands a file of any other type to the model as a file of the result (the Model Gate writes the note for one the model does not read; `artifact.unsupported` is gone). Its page is harness configuration, `createHarness({ artifactPageBytes })` (32 KiB by default), and now always ends on a whole character. `runDurable` takes `engineTools`; `apiHost` takes the engine's configuration.
+  - **The Runtime pins no artifact tools.** `runtimeManifestFor` has no `save` or `read`; `RUNTIME_TOOL_NAMES` no longer holds the two names, so an author tool may take one (our harness then refuses the turn). A session without a sandbox or skills pins its definition unchanged. Core no longer runs either tool (`tenant/artifact-tool.ts` is gone). Migration 0029 closes every agent session that pinned them (`closedReason: "protocol_15"`, `409 session_closed`); workflow sessions carry over.
+  - **Media types are core's.** `contentTypeFor`, `essence`, `normalizeContentType`, `isText`, `isModelImage`, `modelInputOf`, `inputLabel`, `extensionFor`, `unreadableReason`, `MODEL_IMAGE_TYPES` and `DEFAULT_CONTENT_TYPE` are exported from `@nylorun/core/contracts`, for the Runtime and harnesses alike.
+  - `PROTOCOL_VERSION` 15 with required feature `harness-boundary`; `HARNESS_API_VERSION` 4. The SDKs and the CLI send protocol 15.
+
+- b1e815d: **Runtime limits are a Tenant setting, and harnesses get them in `turn.start.limits`.**
+
+  - What one record entry, model call, model file, tool answer, custom harness state and Harness API chunk may hold is the new Management API setting `GET`/`PUT /v1/tenant/limits` (`{ limits: { recordEntryBytes, modelCallBytes, modelFileBytes, toolAnswerBytes, harnessStateBytes, chunkBytes } }`), also `admin.settings.limits` and `nylorun tenant settings limits [get | put <file|->]`.
+    - The defaults are today's sizes (`RUNTIME_LIMIT_DEFAULTS`): 960 KiB, 32 MiB, 8 MiB, 8 MiB, 256 KiB and 16 MiB. A limit left out of a `PUT` takes its default.
+    - Each limit has a ceiling a dependency sets (`RUNTIME_LIMIT_CEILINGS`): S2's 1 MiB record less 64 KiB for the event's envelope, the 64 MiB Harness API frame, the longest JavaScript string. A limit above its ceiling is `400`, naming the ceiling.
+    - Each is read from the Tenant's database where it is checked; nothing keeps it.
+  - **The record holds every write to `recordEntryBytes`.** An event whose payload, or an effect outcome whose value, is larger, whoever wrote it, is refused with `limit_exceeded`: `413` (`details.limit: "recordEntryBytes"`) to an API client, the new Harness API error code `limit_exceeded` to a harness. A harness's claimed event past it is refused rather than dropped. Before, such an event reached a record S2 could not take.
+  - **The gates read the setting.** The Model Gate refuses a body past `modelCallBytes` and a file past `modelFileBytes`; the Tool Gate keeps no MCP or HTTP answer past `toolAnswerBytes` (`mcp.too-large`, `http.too-large`) and reads no tool body past it. A custom harness's state past `harnessStateBytes` fails its turn with `limit_exceeded` (it was `invalid`), and a `definition.file` range longer than `chunkBytes` is `limit_exceeded`. Core's step budget for tool results is unchanged (256 KiB), or half `recordEntryBytes` when that is less.
+  - **`turn.start` carries `limits`** (`RuntimeLimitsSchema`), the limits in force when the segment started. Harness API 3 and protocol 14 are unchanged, but `TurnStartSchema` is strict: a harness built against an older `@nylorun/core` refuses a `turn.start` with `limits`, so upgrade a custom harness with the Runtime. Our harness asks for skill files `limits.chunkBytes` at a time, and holds MCP answers on its own connections to `limits.toolAnswerBytes`. `createHarness` takes `onStart(grant, start)`.
+  - **Removed exports:** `MAX_MODEL_CALL_BYTES`, `MAX_TOOL_BODY_BYTES`, `MAX_HARNESS_STATE_BYTES` and `DEFINITION_FILE_CHUNK_BYTES` from `@nylorun/core`. Added: `RuntimeLimitsSchema`, `RUNTIME_LIMIT_DEFAULTS`, `RUNTIME_LIMIT_CEILINGS`, `runtimeLimitsOf`, `runtimeLimitIssues`, `limitExceededMessage`, `S2_RECORD_MAX_BYTES`, `RECORD_ENVELOPE_RESERVE_BYTES`, `JS_STRING_MAX_LENGTH` and the `TenantLimits*` schemas.
+
+- f2e9b0a: **Skill and artifact limits are set per Tenant and per Environment manifest; a skill holds up to 2 GiB by default, with no limit per file or on the number of files.**
+
+  - The 10 MiB limit per skill file and the 500-file limit are gone. A skill's files may hold up to the Tenant's skill limit together: 2 GiB by default (`SKILL_TOTAL_BYTES_DEFAULT`). A file at two paths counts twice, since a sandbox holds both copies. `SKILL_FILES_MAX` and `DEFINITION_FILE_MAX_BYTES` are no longer exported.
+  - The Tenant's skill limit is the new Management API setting `GET`/`PUT /v1/tenant/skills` (`{ limits: { totalBytes } }`), also available as `admin.settings.skills` and `nylorun tenant settings skills [get | put <file|->]`.
+    - `PUT /v1/files/sha256:<hex>` takes a file up to that limit.
+    - `PUT /v1/agents/{id}` refuses a skill over it, an agent used as a tool included: `413 limit_exceeded`, with `details.skills` listing each skill and its size.
+  - An environment manifest, or the inline fields of `PUT /v1/environments/{id}`, may set `limits`: `artifacts.fileBytes`, `artifacts.totalBytes` and `skills.totalBytes`. Like the manifest's other fields, they are fixed for the Environment's life.
+    - Each limit must be at most the Tenant's. A higher one is refused with `400` when the Environment is made or the manifest is saved.
+    - A limit left out is the Tenant's at the time it is checked. A Tenant that lowers a limit lowers it for every Environment.
+    - The Environment view's new `limits` field gives the limits in force.
+  - An Environment's artifacts are its sessions' artifacts and its disk versions. Uploads, `save_artifact`, turn-end exports and disk snapshots hold them to the Environment's per-file limit and to its own total, as well as to the Tenant's total. A turn-end export past the Environment's total is skipped with the new reason `environment_total`, and a disk snapshot past it is `413` with `details.limit: "environment_total"`.
+  - A session opens on an Environment only when its agent's skills fit the Environment's skill limit; otherwise it is `409 environment_unsuitable`, with `details.skills`.
+  - `PUT /v1/files` streams the body to the Object store instead of holding it in memory. Only bytes that match the named hash reach the file's key. Environment files named by hash are held to the same per-file maximum.
+  - `@nylorun/agents`: loading a skills folder no longer checks a size, since the limit is the Tenant's; the Runtime refuses an oversized skill. The `skills.file-too-large` and `skills.too-many-files` errors are gone. Files are hashed and read a chunk at a time.
+  - Sandboxes get skill files as a stream. A harness fetches them from core 16 MiB at a time: `definition.file` takes optional `offset` and `length` (at most the Runtime limit `chunkBytes`).
+  - `load_skill` and `read_skill_resource` read files of up to 10 MiB into the model's context. A larger file fails with `skill.resource_too_large`, and the error names the file's path in the sandbox when there is one.
+
+### Patch Changes
+
+- cf425c6: **The harness mounts skills and saves outputs; the in-process harness uses the gates; compaction is a transcript edit (protocol 15).** The fifth step of the harness boundary, still protocol 15 and Harness API 4. See MIGRATION.md.
+
+  - **Skill folders are our engine's.** Before each sandbox call our engine mounts each skill version of the turn's tree at `/skills/<name>@<hash>/` with `executors.files.mount`, reading the bytes over `definition.file`; the SandboxManager only writes them (`mountFolder`), once per open sandbox (`present` after). `SandboxManager.mountSkills`, its `definitionFile` port and `SandboxSessionRef.manifest` are gone, and the operator sandbox route mounts nothing.
+  - **The outputs folder is our engine's (Q5).** At a completed turn's end in a sandbox our engine saves `/workspace/outputs` as the session's `outputs` folder before `turn.completed`, over the new folder mode of `artifact.write` (`kind: "folder"`, `file`, chunks named by hash, `unchanged`, `refused`). Core takes every byte, checks each file's hash before content is stored under it, dedupes, and keeps the content epoch and quotas. Versions say `source: "engine"`; `artifact.export.skipped` and `artifact.export.failed` are harness claims. Core's export (`artifacts/export.ts`, the `WorkspaceReader`, `workspace.read` listing and bytes calls) is removed.
+  - **No limit literals.** The new Runtime limit `folderEntries` (10,000; a count, its ceiling from the manifest's one string) replaces `EXPORT_MAX_FILES`, and `createHarness({ outputs: { dir, maxBytes } })` (`/workspace/outputs`, 1 GiB) replaces `EXPORT_MAX_BYTES`. `RUNTIME_LIMIT_CEILINGS` entries are `{value, unit, why}`.
+  - **In-process parity.** Every model call goes through the Model Gate: a scripted model is served by `providerModelGate`, metered like any. The MCP pool opens every server through the Tool Gate (`openRemote` is required; the in-process gate's `openMcp` finds the server in the session's pinned manifest and authorizes it with the vault). `ModelRoute` is `{tenantId, modelGate}`; `TenantContext.modelProvider`, `useVaultModel` and `workspaces` are gone.
+  - **Compaction is a transcript edit (Q4).** Summary calls say `purpose: "summary"` (no `message.assistant`), and the segment's edit that replaced the history says `kind: "compaction"` with its facts and summary calls (`CompactionFactsSchema`, `transcriptUpdates(..., compaction)`). Core checks the calls and writes one `context.compacted`, which loses `partial`.
+
+- dc75e58: **Host timings, retries and engine settings are configuration with defaults (B15).** Still protocol 15 and Harness API 4. See MIGRATION.md and DEPLOYMENT.md ("Host tuning").
+
+  - **Host tuning.** The Runtime processes' timeouts, retries, poll intervals and internal sizes are one typed schema with a default each (`HostTuningSchema`, `runtime/server/src/tuning.ts`): keys, the Harness API, the API's streams, the Host, the Object store, the Tenant, its sweep, Durable Session Execution, Restate, Postgres, Durable Streams and the relay, the gates, egress-gate, sandbox pods, harnesses and traces. An operator sets any part in `NYLORUN_TUNING` (JSON), parsed with the stack configuration and read once at start; every default is the value before. An unknown key or a value past its ceiling (Node's longest timer, S3's part sizes, S2's batch, the sandboxes service's wait) stops the process naming the key. Core hands a sandbox pod's engine the `harness` and `engine` groups the operator set. `nylorun start` passes `NYLORUN_TUNING` to the runtime, gateway and harness containers.
+  - **Our engine's loop is configuration.** `createHarness` takes `compaction` (`CompactionConfig`, `DEFAULT_COMPACTION_CONFIG`: the kept tail, the reply's reserve, the estimate), `partialOutputChars` (a failed agent-as-tool's output its parent sees), `resendDelaysMs` and `leaseRetryMs`; `runDurable` takes `loop` (`LoopConfig`), which an invocation hands its agents used as tools. `EngineToolConfig` is `EngineConfig`. The Runtime's harness host passes the tuning's `engine` group to `createHarness`.
+  - **Kept as constants**, each justified where it is defined: Node's longest timer, S3's part sizes and object key, S2's batch, the sandboxes service's longest wait and pod variable, the `environment.egress` event's 16 running turns, W3C's 512-character `tracestate`, and the 24-hour floor of a wake's dedupe key.
+
+- 23774c4: **The last hard-coded limits are configuration (harness boundary B15c).** Still protocol 15 and Harness API 4. Every default is the value before. See MIGRATION.md, and DEPLOYMENT.md's Runtime limits and Host tuning.
+
+  - **21 more Runtime limits** (`GET`/`PUT /v1/tenant/limits`): a message's parts (`messageParts`), page sizes (`pageItems`, `exportPageItems`, `environmentEventItems`; a page asked larger holds that many), labels (`artifactLabels`, `labelKeyChars`, `labelValueChars`), a manifest's setup command, descriptions and secret hosts (`setupCommandChars`, `manifestDescriptionChars`, `secretDescriptionChars`, `secretHosts`), a failed pod's reason (`setupReasonChars`, `setupCommandExcerptChars`), secret values (`secretValueChars`), the tool policy and budgets (`toolRules`, `toolRuleFieldChars`, `toolRuleTextChars`, `modelBudgets`) and flows (`flowConcurrency`, `flowMapItems`, `flowLoopIterations`, replacing the `NYLORUN_FLOW_*` variables no Host read). Request schemas lose these maxima; the Runtime checks the Tenant's.
+  - **More Host tuning** (`NYLORUN_TUNING`): token lifetimes and clock tolerance (`keys.*`), the advance deadline and grace (`execution.*`), `nylorun-operate`'s waits, the credential store's lock, sweep arming, Postgres batches and the replication pool, a basin repair's log cadence, egress sockets, the engine poll and sandbox memory floor, MCP listing pages and diagnostics, sandbox helper commands, the scrub threshold, exec event and local stream sizes; and in the engine, `flowValueChars` and `toolResults.minPreviewBytes`.
+  - **The CLI's own waits are `NYLORUN_CLI_TUNING`**: `nylorun start`'s waits and polls, the Compose healthchecks and WAL cap, and `nylorun local sandbox`'s waits.
+  - **Studio follows the Runtime's limits**: no upload cap of its own, the Tenant's `requestBodyBytes` read for a write it parses past the default (`@nylorun/agents` exports `RUNTIME_LIMIT_DEFAULTS`), no CPU cap in its form.
+  - **Kept, each justified where it is defined**: Linux's `MAX_ARG_STRLEN` (a setup command's ceiling) and `PATH_MAX` (a link target), a model-facing tool name's 64 characters, RFC 6838's media type length, Postgres's 65,535 bind parameters, a tmpfs page, and identifier grammars (the protocol's).
+
+- 6772612: **The remaining request, upload, token and sandbox limits are Tenant settings (harness boundary B15).** Still protocol 15 and Harness API 4. See MIGRATION.md and DEPLOYMENT.md's Runtime limits.
+
+  - **27 more Runtime limits** in `GET`/`PUT /v1/tenant/limits`, each with today's value as its default and a ceiling from a dependency (a JavaScript string or timer, a request read as one string, a Harness API frame, a JavaScript number): request bodies and inline files (`requestBodyBytes`, `inlineFileBytes`), `a2aWaitMs`, `errorExcerptChars`, `traceContentBytes`, an Environment's labels, setup and input files (`environmentLabels`, `environmentSetupCommands`, `environmentFiles`, `environmentFilesPerEntry`, `environmentSecretSlots`, `setupCommandMs`, `setupOutputChars`), disk versions (`diskVersionEntries`, `diskVersionBytes`, `diskLeaseMs`, `diskPodWaitMs`; an Environment's manifest may lower the first two with `limits.disk`), model calls (`modelRequestMs`, `modelIdleMs`, `modelAttempts`, `modelRetryDelayMs`, `modelProviderRetries`, `modelRetryDelayMaxMs`, read by the gates for each call) and tools (`toolAttempts`, `httpToolTimeoutMs`, `mcpPreviewMs`, `mcpMetadataBytes`, and the new `mcpSnapshotBytes`: what a session pins of its MCP servers' tools and instructions, past which a server is left out with a diagnostic).
+  - **Schema maxima are checked against the Tenant's limits**: an Environment's labels, setup commands, input files, files per entry, secret slots and setup timeout, and an HTTP tool's `timeoutMs` (at deploy and at each call). `limits.environments` and `lifecycle.stopGrace` lose their arbitrary caps; an identity file's issuer takes any number of grants and `jwksFetch` settings.
+  - **`turn.start.limits` carries only a harness's limits** (`HarnessLimitsSchema`, `harnessLimitsOf`), and a harness drops one it does not know. `transcriptUpdates` takes `recordEntryBytes` and fills each event up to it; `CHUNK_BYTES` is gone.
+  - **Constants a dependency or a standard fixes stay, named for it**: a token is read up to Node's `http.maxHeaderSize`; artifact names and folder paths keep `FILE_NAME_MAX` (255) and `FILE_PATH_MAX` (1,024); a skill file's path is what `FILE_PATH_MAX` leaves under its mount folder; `tracestate` keeps W3C's 512.
+  - **Removed**: `ENVIRONMENT_LABELS_MAX`, `ENVIRONMENT_SETUP_MAX`, `ENVIRONMENT_SETUP_TIMEOUT_MAX_MS` (now `ENVIRONMENT_SETUP_TIMEOUT_DEFAULT`), `ENVIRONMENT_FILES_MAX`, `ENVIRONMENT_SECRET_SLOTS_MAX`, `TOKEN_ENVIRONMENT_GRANTS_MAX`, `HTTP_TOOL_MAX_TIMEOUT_MS`, `READ_ARTIFACT_MAX_BYTES` and `CHUNK_BYTES` from `@nylorun/core`; the image checks (`decodeImageBase64`, `validateImageBytes`, `IMAGE_MEDIA_TYPES`, `MAX_IMAGE_BYTES`), the Tenant configuration's `modelCall` and `TrustedIssuersOptions`' `refetchMs`/`maxAgeMs` from `@nylorun/runtime`. Studio's Environment form no longer caps setup commands and input files at 16: the Runtime checks the Tenant's limit.
+
+- 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 [0a2fbc5]
+- Updated dependencies [ebe7348]
+- Updated dependencies [ff6470e]
+- Updated dependencies [f443475]
+- Updated dependencies [cf425c6]
+- Updated dependencies [23774c4]
+- Updated dependencies [b1e815d]
+- Updated dependencies [2459430]
+- Updated dependencies [f2e9b0a]
+- Updated dependencies [6772612]
+- Updated dependencies
+- Updated dependencies
+  - @nylorun/core@0.23.0-beta
+  - @nylorun/agents@0.23.0-beta
+  - @nylorun/admin@0.18.0-beta
+
 ## 0.15.1-beta
 
 ### Patch 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 [get | put <file|->] [--tenant <name>]   # Environment and artifact store settings
-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`.
@@ -510,13 +554,14 @@ already has a credential, keeping its model (or `--model`) and endpoint.
 
 ### Files in, files out
 
-`budgets`, `tool-policy`, `settings sandbox` and `settings artifacts` are
-documents: `get` (the default) prints one as JSON, and `put <file>` (or `put -`
-for stdin) replaces the whole document with the JSON body in the file, the
-Management API's request body (`PUT /v1/tenant/budgets`, `/tool-policy`,
-`/sandbox`, `/artifacts`). The body is checked against its schema before
-anything is sent; one that does not parse exits 2. What `budgets`, `tool-policy`
-and `settings artifacts` print, `put` takes back (their `updatedAt` and
+`budgets`, `tool-policy`, `settings sandbox`, `settings artifacts`,
+`settings skills` and `settings limits` are documents: `get` (the default)
+prints one as JSON, and `put <file>` (or `put -` for stdin) replaces the whole
+document with the JSON body in the file, the Management API's request body
+(`PUT /v1/tenant/budgets`, `/tool-policy`, `/sandbox`, `/artifacts`, `/skills`,
+`/limits`). The body is checked against its schema before anything is sent; one
+that does not parse exits 2. What `budgets`, `tool-policy`, `settings artifacts`,
+`settings skills` and `settings limits` print, `put` takes back (their `updatedAt` and
 `usedBytes` are dropped), so they can be kept in a repository and applied from
 CI:
 
@@ -528,11 +573,28 @@ nylorun tenant tool-policy put tool-policy.json
 `settings sandbox get` prints the effective settings and what the Host offers;
 its `put` takes the settings alone (`limits`, `lifecycle`, `placement`).
 
+`settings limits` is the Tenant's Runtime limits: the sizes, counts and
+deadlines the Runtime holds what crosses it to, such as `recordEntryBytes`,
+`requestBodyBytes`, `environmentLabels`, `pageItems`, `modelRequestMs` and
+`httpToolTimeoutMs` (each one, with its default and ceiling, in DEPLOYMENT.md's
+Runtime limits). A
+limit left out of a `put` takes its default; one above its ceiling (S2's 1 MiB
+record, the Harness API's 64 MiB frame, a JavaScript timer) is refused, and the
+error names the ceiling.
+
 `nylorun tenant calls` prints each recorded model call as one JSON line, page
 after page, until it is caught up, then the cursor on stderr: pass it as
 `--after` to read only the newer calls. A call may come twice across runs;
 deduplicate by `id`.
 
+### The CLI's own waits
+
+How long `nylorun start` waits for the stack, how often it polls, the healthchecks
+it writes into the Compose file and the waits of `nylorun local sandbox` are the
+CLI's tuning: a JSON object in `NYLORUN_CLI_TUNING`, each value left out keeping
+its default (`{"stack":{"healthWaitMs":120000}}`). DEPLOYMENT.md ("The CLI") lists
+them. The Runtime's own are `NYLORUN_TUNING`, which `nylorun start` passes on.
+
 ## Exit codes
 
 | Code | Meaning |
@@ -540,7 +602,7 @@ deduplicate by `id`.
 | 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) |
@@ -559,7 +621,7 @@ deduplicate by `id`.
 | 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 |