@nylorun/agents 0.24.0-beta → 0.26.0-beta

package/CHANGELOG.md

@@ -1,5 +1,38 @@
 # @nylorun/agents
 
+## 0.26.0-beta
+
+### Minor Changes
+
+- ab7c08a: A gateway's tool prefix (#494, Host feature `gateway-credentials`). A `bearer` or `headers` credential with `via`, written to an Agent's vault, may add `toolPrefix`: what the gateway at `via` puts before each tool name it lists, such as LiteLLM's `github-`. The Runtime lists the server's tools without it, so tool names (`github__create_issue`), a manifest's `tools` settings and tool policy rules name the server's own tools whether or not a gateway is in between, and calls each tool by the name the gateway listed. A listed tool that lacks the prefix keeps its name, and the server's `mcp.discovered` message names it. `toolPrefix` needs `via`, and secret views carry it. It is the installation's routing, never a manifest's: a manifest's secret slot cannot name it, and a slot's value write (`{ headers, toolPrefix }`) adds it. A fork keeps it while the new slot keeps `via`. No protocol change.
+
+### Patch Changes
+
+- Pin core to the tested release.
+- Updated dependencies [fce0c9b]
+- Updated dependencies [ab7c08a]
+- Updated dependencies [4a563e7]
+  - @nylorun/core@0.26.0-beta
+
+## 0.25.0-beta
+
+### Minor Changes
+
+- ed08ba8: `agentManifests.save({ agent, runtime, memory })` turns on a built agent's memory (`harness.memory`, `{ access?, instructions? }`), and a skill folder's `SKILL.md` may list the secret slots its scripts read in its frontmatter (`secrets: [GH_TOKEN]`): `.skills()`, `.plugin()` and `composeManifest` make them the skill's `secrets` in the harness section, which the Runtime checks against `runtime.secrets` at save. A `secrets` that is not a list of environment variable names skips the skill with a warning.
+- eeb6294: Session usage as one ledger (protocol 18). The usage ledger keeps each model call's cost by token kind (uncached input, cache read, cache write, output) at the prices the adapter applied (migration 0037). For a protocol 18 client, `GET /v1/sessions/{id}/calls/model` returns each call's `startedAt`, `endedAt` and `usage.costSplit` (null for a call recorded before), and `GET /v1/sessions/{id}/usage` adds `costSplit` with `splitCalls`, and the calls' durations added up as `modelTimeMs` with `timedCalls`. A protocol 16 or 17 client reads usage as before. Studio's Usage tab is rebuilt on them: a Session card with one tokens bar and a ledger of tokens and cost by kind adding up to a total row, then the model calls grouped by turn with the same columns (cached, uncached, output, total, time, cost), and a row menu whose View event opens the call's event in the Events tab.
+
+### Patch Changes
+
+- ed08ba8: `composeManifest(dir)`, and so `nylorun apply`, keep a `harness.manifest.json`'s `memory`: the composed harness section turned the Agent's memory on only when the manifest was saved as one document.
+- ed08ba8: Public text names no internal roadmap codes: the OpenAPI documents' descriptions, the type comments of `@nylorun/core`, `@nylorun/agents` and `@nylorun/admin`, and the CLI's help, README and generated compose file. A Runtime test fails when either OpenAPI document names one.
+- Pin core to the tested release.
+- Updated dependencies [ed08ba8]
+- Updated dependencies [ed08ba8]
+- Updated dependencies [ed08ba8]
+- Updated dependencies [eeb6294]
+- Updated dependencies [ed08ba8]
+  - @nylorun/core@0.25.0-beta
+
 ## 0.24.0-beta
 
 ### Minor Changes
@@ -11,7 +44,7 @@
 
   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.
+- 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 KiB) 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`.

package/README.md

@@ -252,7 +252,7 @@ const assistant = Agent({ id: "assistant", name: "Order assistant" })
   .skills("./assistant-skills");
 ```
 
-Each subdirectory under the catalog must contain a `SKILL.md` with YAML frontmatter (`name`, `description`) per [Agent Skills](https://agentskills.io/home). Every file of a skill's folder, binary included (not `.git/`, `node_modules/`, OS files like `.DS_Store`, or `.env` and `.env.*` files, which hold secrets), is part of the definition: the manifest names each one by path and SHA-256 (`skills.<name>.files`). A skill's files may hold together at most the Tenant's skill limit (`PUT /v1/tenant/skills`, default 2 GiB); no file and no count of files has a limit of its own, and a manifest's runtime section may set a lower limit for its Agents' sessions (`runtime.limits.skills.totalBytes`). Skills need a sandbox: the runtime section's kind is `virtual` or `pod`, which the Runtime checks when the manifest is saved. `agentManifests.save` uploads the files the Runtime does not hold (`client.files`, `PUT /v1/files/sha256:<hex>`) before it saves the manifest, which the Runtime refuses while it names a file it lacks (`400 definition_files_missing`) or a skill past the Tenant's limit (`413 limit_exceeded`). `read_skill_resource` reads files of up to 10 MiB into the model's context; a larger one is used in the sandbox.
+Each subdirectory under the catalog must contain a `SKILL.md` with YAML frontmatter (`name`, `description`) per [Agent Skills](https://agentskills.io/home). Its `secrets` (`secrets: [GH_TOKEN]`, environment variable names) are the skill's `secrets` in the harness section: the `runtime.secrets` slots its scripts read, of type `environment_secret` or `environment_variable`; a skill whose `secrets` is not such a list is skipped with a warning. Every file of a skill's folder, binary included (not `.git/`, `node_modules/`, OS files like `.DS_Store`, or `.env` and `.env.*` files, which hold secrets), is part of the definition: the manifest names each one by path and SHA-256 (`skills.<name>.files`). A skill's files may hold together at most the Tenant's skill limit (`PUT /v1/tenant/skills`, default 2 GiB); no file and no count of files has a limit of its own, and a manifest's runtime section may set a lower limit for its Agents' sessions (`runtime.limits.skills.totalBytes`). Skills need a sandbox: the runtime section's kind is `virtual` or `pod`, which the Runtime checks when the manifest is saved. `agentManifests.save` uploads the files the Runtime does not hold (`client.files`, `PUT /v1/files/sha256:<hex>`) before it saves the manifest, which the Runtime refuses while it names a file it lacks (`400 definition_files_missing`) or a skill past the Tenant's limit (`413 limit_exceeded`). `read_skill_resource` reads files of up to 10 MiB into the model's context; a larger one is used in the sandbox.
 
 The Runtime serves the skills itself, with no call to your process. When our harness runs a turn, it adds the skill catalog to the instructions and two tools: `load_skill` returns a skill's `SKILL.md` body and the paths of its other files, and `read_skill_resource` returns a text file. A session with a sandbox also has each skill's files read-only under `/skills/<name>@<hash>/`, so the model can run a skill's scripts with `bash`.
 
@@ -272,13 +272,13 @@ Each key names a server; its `name` defaults to the key and, when given, must eq
 
 Set a server's tools one by one with `tools`, keyed by the server's own tool names, `"*"` for the rest: `{ "*": { enabled: false }, search_issues: { enabled: true }, create_issue: { enabled: true } }` is an allowlist (whether a call waits for a person is the [tool policy](#tool-policy)). When an agent's MCP tools would fill more than a tenth of the model's context window, the Runtime defers them: the model finds them with `tool_search` and runs them with `tool_call`. `deferred: true` or `false`, on a tool or on the server, decides instead.
 
-A manifest never carries a server's credential, and its `headers` hold no secret. A server may name the runtime section's secret slot it authenticates with (`credential`: a `bearer` or `headers` slot bound to its URL, checked when the manifest is saved), and you write the credential into each Agent's vault (a token or a header map, or a gateway's key with `via` and an identity header for servers that need each person's sign-in, with `client.agents.secrets.put`); the sessions on that Agent use it: [DEPLOYMENT.md](../../guides/DEPLOYMENT.md#mcp-servers-and-http-tools), which also shows `nylorun tenant mcp inspect` for listing a server's tools first. `admin.coverage({ agentId })` in `@nylorun/admin` says which credential each server and HTTP tool of an Agent's manifest version would get from its vault ([Checking an agent's credentials](../../guides/DEPLOYMENT.md#checking-an-agents-credentials)). The model knows each tool as `server__tool`, with characters outside `[A-Za-z0-9_-]` replaced by `_`; a failed call reaches it with a code (`credential_rejected` on a `401`, `mcp.unreachable`, …), and a result past 32 KiB, or an image, becomes an artifact of the session that it reads with `read_artifact`.
+A manifest never carries a server's credential, and its `headers` hold no secret. A server may name the runtime section's secret slot it authenticates with (`credential`: a `bearer` or `headers` slot bound to its URL, checked when the manifest is saved), and you write the credential into each Agent's vault (a token or a header map, or a gateway's key with `via`, its tool prefix (`toolPrefix`) and an identity header for servers that need each person's sign-in, with `client.agents.secrets.put`); the sessions on that Agent use it: [DEPLOYMENT.md](../../guides/DEPLOYMENT.md#mcp-servers-and-http-tools), which also shows `nylorun tenant mcp inspect` for listing a server's tools first. `admin.coverage({ agentId })` in `@nylorun/admin` says which credential each server and HTTP tool of an Agent's manifest version would get from its vault ([Checking an agent's credentials](../../guides/DEPLOYMENT.md#checking-an-agents-credentials)). The model knows each tool as `server__tool`, with characters outside `[A-Za-z0-9_-]` replaced by `_`; a failed call reaches it with a code (`credential_rejected` on a `401`, `mcp.unreachable`, …), and a result past 32 KiB, or an image, becomes an artifact of the session that it reads with `read_artifact`.
 
 ## Agent manifests and Agents
 
-An **agent manifest** (v8, protocol 16) is one named, versioned document with two sections: `harness`, what runs inside the agent loop (the harness's `id`, `instructions`, `tools`, `skills`, `mcpServers`, `plugins`, `outputSchema` and the harness's own `loop` settings; or a flow, `kind: "workflow"`), and `runtime`, what the Runtime provides around it (`kind`, `image`, `network`, `setup`, `files`, `limits`, `lifecycle` and its secret slots, `secrets`). The Runtime checks the two against each other when the manifest is saved and refuses every gap at once (`422 manifest_inconsistent`, `details.gaps`): a custom harness off a pod, a `credential` or a skill's `secrets` that is no declared slot of the right type, skills on a runtime without a sandbox. A manifest without `runtime` makes Agents of kind `none`.
+An **agent manifest** (v8, protocol 16) is one named, versioned document with two sections: `harness`, what runs inside the agent loop (the harness's `id`, `instructions`, `tools`, `skills`, `mcpServers`, `plugins`, `outputSchema`, the harness's own `loop` settings and the Agent's `memory`; or a flow, `kind: "workflow"`), and `runtime`, what the Runtime provides around it (`kind`, `image`, `network`, `setup`, `files`, `limits`, `lifecycle` and its secret slots, `secrets`). The Runtime checks the two against each other when the manifest is saved and refuses every gap at once (`422 manifest_inconsistent`, `details.gaps`): a custom harness off a pod, a `credential` or a skill's `secrets` that is no declared slot of the right type, skills on a runtime without a sandbox. A manifest without `runtime` makes Agents of kind `none`.
 
-An **Agent** is the live instance of one version of a manifest: one environment of its runtime's kind, one vault, and the sessions that run on it, with an id you choose (`users/alice/triage`), which outlives them. It is made only from a saved manifest: `manifest: "triage"` tracks the manifest (its latest version when the Agent is made), `"triage@3"` pins version 3; either way it resolves the version once and keeps it. Every session runs on one Agent (`createSession({ agent })`), and no session is special: creating an Agent opens none, and the app picks session ids (D71). Whether an Agent serves one person or a project is your app's choice:
+An **Agent** is the live instance of one version of a manifest: one environment of its runtime's kind, one vault, and the sessions that run on it, with an id you choose (`users/alice/triage`), which outlives them. It is made only from a saved manifest: `manifest: "triage"` tracks the manifest (its latest version when the Agent is made), `"triage@3"` pins version 3; either way it resolves the version once and keeps it. Every session runs on one Agent (`createSession({ agent })`), and no session is special: creating an Agent opens none, and the app picks session ids. Whether an Agent serves one person or a project is your app's choice:
 
 ```ts
 // The manifest, from a built agent and the runtime section to run it in.
@@ -301,7 +301,7 @@ await client.agents.secrets.put("users/alice/analyst", "GH_TOKEN", { value: proc
 const session = await client.createSession({ id: "alice-q3", agent: "users/alice/analyst", ownerUserId: "alice" });
 ```
 
-`agentManifests.save(input, { ifMatch, requestId })` and `plan(input, { ifMatch })` (a dry run that saves nothing) take a v8 document, what `composeManifest` read, or `{ agent, runtime?, harness?, loop?, name?, description?, metadata? }`: the SDK makes the harness section from the built agent or flow (`harnessSectionOf`; `harness` is the harness's id) and names the manifest after the agent's id. First it uploads every file the manifest names by hash that the Runtime does not hold: the agent's skills, a flow's agents' skills, and the runtime's files (`runtimeFiles(path, contents)` hashes a `files` entry; pass its `bytes` as `files`). `If-Match` is the version you read (`0` for a new manifest). A save that changes nothing answers the latest version, `unchanged`. `get(name, version?)`, `list()`, `versions(name)` (with the Agents made from each) and `delete(name)` (refused while an Agent was made from it: `409 manifest_in_use`) read and remove them.
+`agentManifests.save(input, { ifMatch, requestId })` and `plan(input, { ifMatch })` (a dry run that saves nothing) take a v8 document, what `composeManifest` read, or `{ agent, runtime?, harness?, loop?, memory?, name?, description?, metadata? }`: the SDK makes the harness section from the built agent or flow (`harnessSectionOf`, with its skills' `secrets`; `harness` is the harness's id; `memory`, `{ access?, instructions? }`, turns on an agent's memory, not a flow's) and names the manifest after the agent's id. First it uploads every file the manifest names by hash that the Runtime does not hold: the agent's skills, a flow's agents' skills, and the runtime's files (`runtimeFiles(path, contents)` hashes a `files` entry; pass its `bytes` as `files`). `If-Match` is the version you read (`0` for a new manifest). A save that changes nothing answers the latest version, `unchanged`. `get(name, version?)`, `list()`, `versions(name)` (with the Agents made from each) and `delete(name)` (refused while an Agent was made from it: `409 manifest_in_use`) read and remove them.
 
 ### Three files: `composeManifest`
 
@@ -314,10 +314,11 @@ A manifest can also be authored as files, so a runtime is shared by many agents
 // agents/triage/harness.manifest.json
 {
   "instructions": ["Triage each new issue."],
-  "skills": "./skills",                      // each subfolder with a SKILL.md is a skill
+  "skills": "./skills",                      // each subfolder with a SKILL.md is a skill; its secrets, the frontmatter's
   "mcpServers": "./mcp.json",                // the Agent Plugins format
   "plugins": ["../../plugins/github"],       // folded in as .plugin() folds it
   "credentials": { "linear": "linear" },     // MCP server or HTTP tool → runtime.secrets slot
+  "memory": { "access": "read_write" },     // turns on the Agent's memory
   "requires": { "sandbox": "any", "secrets": ["GH_TOKEN"] } // checked here only
 }
 
@@ -348,7 +349,7 @@ With a sandbox (kind `virtual` or `pod`), the model gets `bash`, `read`, `write`
 
 An Agent runs one version of its manifest at a time and evolves in place, with its id, disk, vault and sessions: a `put` on an existing one may change its `labels` and `owner` guard and moves it to the version its `manifest` names (`"name"` tracks the latest, `"name@n"` pins), `plan(id, input)` answers what that move would do, and a save of a new version moves every Agent that tracks the manifest. A harness change applies at once (each session's next turn runs it); a pod's runtime change waits for its next start on the same volume (`targetVersion`, `waitingFor: "start"`; `restart(id)` applies it now), and a start that fails goes back to the version it ran (`failedVersion`; `restart(id, { retry: true })` tries again). A version that adds a required secret waits for its value (`waitingFor: "secrets"`). `list({ outdated: true })` lists the Agents still moving. Its manifest's name, kind, harness and storage are fixed (`409 agent_fixed_field`): `fork(id, { id: next, manifest? })` makes a new Agent (default the source's manifest, tracking), with the source's disk (`disk`: `latest`, a version, or `empty`) and the secrets the new manifest declares (`secrets: "none"` copies none), and `planFork` answers what a fork would do. The Runtime checks the runtime section against the Tenant's limits (`GET`/`PUT /v1/tenant/sandbox`: a network ceiling, a resource maximum, the idle timeout; `/v1/tenant/artifacts` and `/v1/tenant/skills` for its `limits`). `lifecycle.idle` stops a pod after that long without a turn (at most the Tenant's); `lifecycle.deleteAfter` deletes the Agent, its vault and its files once nothing has used it that long. Private networks, loopback, the host and cloud metadata endpoints are always blocked.
 
-Secrets are write-only: `client.agents.secrets.put(id, name, secret)` creates or replaces one, and `list`, `get` and `delete` never return a value. When the manifest declares the secret's slot (`runtime.secrets`), send only `{ value }` (or `{ headers }`): the type and binding come from the slot, and a name it does not declare is `409 secret_not_in_manifest`. Typed, an `environment_secret` (`{ value, allowedHosts, inject? }`) shows its name to commands as the sentinel `nylorun_managed`, and egress-gate sets its header on HTTPS requests to `allowedHosts` (pods only); an `environment_variable` (`{ value }`) is a plain variable; `bearer` (`{ url, value, via?, identity? }`) and `headers` (`{ url, headers, via?, identity? }`) are credentials for the MCP servers and HTTP tools at `url`. A second secret for one host, or a second credential for one URL, is `409 credential_conflict` at the write ([DEPLOYMENT.md](../../guides/DEPLOYMENT.md#credentials)).
+Secrets are write-only: `client.agents.secrets.put(id, name, secret)` creates or replaces one, and `list`, `get` and `delete` never return a value. When the manifest declares the secret's slot (`runtime.secrets`), send only `{ value }` (or `{ headers }`): the type and binding come from the slot, and a name it does not declare is `409 secret_not_in_manifest`. Typed, an `environment_secret` (`{ value, allowedHosts, inject? }`) shows its name to commands as the sentinel `nylorun_managed`, and egress-gate sets its header on HTTPS requests to `allowedHosts` (pods only); an `environment_variable` (`{ value }`) is a plain variable; `bearer` (`{ url, value, via?, toolPrefix?, identity? }`) and `headers` (`{ url, headers, via?, toolPrefix?, identity? }`) are credentials for the MCP servers and HTTP tools at `url`. A second secret for one host, or a second credential for one URL, is `409 credential_conflict` at the write ([DEPLOYMENT.md](../../guides/DEPLOYMENT.md#credentials)).
 
 Sessions on one Agent share its `/workspace` and run their turns at the same time (one turn per session); which sessions work on one disk, and when, is your app's call. Stop, reset, snapshot and restore wait until no turn runs (`409 agent_busy`). Deleting a session only detaches it. With `owner` set, a session of another owner is `403 agent_owner_mismatch` (a caller acting for a person gets the `404` of a missing Agent), checked when it opens and at every turn start. An Agent's view says what it runs (`manifest`, `resolvedVersion`, `tracking`), its `state` (`working`, `sleeping`, `input_required`, `failing` or `paused`, `AGENT_STATES`) with the sessions behind it (`attention`), its compute (`compute.state`) and its slots. `client.agents.list({ labels, state, manifest })`, `page`, `get(id)`, `events(id, { types, since, until })` (its lifecycle, and `agent.egress` for every connection its sandbox opens, naming the turns that were running), `stop(id)`, `reset(id)` and `delete(id)` manage them, and `npx nylorun agents list | put | rm` does the same from the command line. Acting for a person (`app.as(...)`), changing an Agent or its secrets needs `agents:write`, and saving a manifest `agent-manifests:write`. A trusted issuer's token reaches only the Agents its issuer grants (the identity file's `agents` templates, exact ids or prefixes ending in `/*`), checked at every turn start. The Tenant holds at most `limits.environments` of them (`PUT /v1/tenant/sandbox`, default 100).
 

package/dist/agent-manifests.d.ts

@@ -1,20 +1,20 @@
 /**
- * Agent manifests (protocol 16, track T2): `client.agentManifests`. An agent manifest (v8) is one
+ * Agent manifests (protocol 16): `client.agentManifests`. An agent manifest (v8) is one
  * named, versioned document with what runs inside the agent loop (`harness`: the harness's id,
  * instructions, tools, skills, MCP servers, plugins, output schema, the harness's own `loop`
- * settings; or a flow, `kind: "workflow"`) and what the Runtime provides around it (`runtime`:
- * kind, image, network, setup, files, limits, secret slots). The Runtime checks the two against
- * each other when it is saved (`422 manifest_inconsistent`); an Agent (`client.agents`) is made
- * from one version.
+ * settings, memory; or a flow, `kind: "workflow"`) and what the Runtime provides around it
+ * (`runtime`: kind, image, network, setup, files, limits, secret slots). The Runtime checks the
+ * two against each other when it is saved (`422 manifest_inconsistent`); an Agent
+ * (`client.agents`) is made from one version.
  *
  * `save` takes the document, what `composeManifest` read from a folder, or a built agent or flow
  * with the runtime section to run it in: the SDK makes the harness section from the agent's
- * manifest (`harnessSectionOf`). It first uploads the files the manifest names by hash that the
- * Runtime does not hold (skills, a flow's agents' skills, runtime files), and refuses before
- * sending a tool that runs your code or an `approval`, as the Runtime runs agents from their
- * manifests alone.
+ * manifest (`harnessSectionOf`), with its skills' `secrets`, `loop` and `memory`. It first
+ * uploads the files the manifest names by hash that the Runtime does not hold (skills, a flow's
+ * agents' skills, runtime files), and refuses before sending a tool that runs your code or an
+ * `approval`, as the Runtime runs agents from their manifests alone.
  */
-import { AGENT_MANIFEST_V8_SCHEMA_VERSION, type AgentManifestPlan, type AgentManifestV8, type AgentManifestVersions, type AgentManifestView, type DeleteAgentManifestResponse, type RuntimeSection, type SaveAgentManifestResponse } from "@nylorun/core/contracts";
+import { AGENT_MANIFEST_V8_SCHEMA_VERSION, type AgentManifestPlan, type AgentManifestV8, type AgentMemorySettings, type AgentManifestVersions, type AgentManifestView, type DeleteAgentManifestResponse, type RuntimeSection, type SaveAgentManifestResponse } from "@nylorun/core/contracts";
 import { type AgentManifest, type BuiltAgent, type BuiltWorkflow, type JsonObject, type SkillFileSource, type WorkflowManifest } from "@nylorun/core/define";
 import { type Transport } from "./http.js";
 /** A built agent or flow, or anything with its id and manifest. */
@@ -44,6 +44,11 @@ export interface AgentManifestFromAgent {
     readonly runtime?: RuntimeSection;
     /** The harness's own settings (`harness.loop`), passed to it in `turn.start`. */
     readonly loop?: JsonObject;
+    /**
+     * Turns on the Agent's memory (`harness.memory`): `access` `read_write` (the default) or
+     * `read_only`, and `instructions` on what to remember. An agent's only, not a flow's.
+     */
+    readonly memory?: AgentMemorySettings;
 }
 /** What `composeManifest` read from a folder: the document, the bytes of the files it names, its gaps. */
 export interface ComposedManifest {
@@ -98,7 +103,7 @@ export declare class AgentManifestsClient {
     private send;
     /**
      * Saves the manifest's next version (`PUT /v1/agent-manifests/{name}`), or answers the latest
-     * unchanged; every Agent that tracks the manifest moves to it (track T3). Refused before anything is sent when it
+     * unchanged; every Agent that tracks the manifest moves to it. Refused before anything is sent when it
      * misses its `requires` or, composed, its sections do not fit (`ManifestGapsError`).
      */
     save(input: AgentManifestInput, options?: AgentManifestSaveOptions): Promise<SaveAgentManifestResponse>;

package/dist/agent-manifests.js

@@ -1,18 +1,18 @@
 /**
- * Agent manifests (protocol 16, track T2): `client.agentManifests`. An agent manifest (v8) is one
+ * Agent manifests (protocol 16): `client.agentManifests`. An agent manifest (v8) is one
  * named, versioned document with what runs inside the agent loop (`harness`: the harness's id,
  * instructions, tools, skills, MCP servers, plugins, output schema, the harness's own `loop`
- * settings; or a flow, `kind: "workflow"`) and what the Runtime provides around it (`runtime`:
- * kind, image, network, setup, files, limits, secret slots). The Runtime checks the two against
- * each other when it is saved (`422 manifest_inconsistent`); an Agent (`client.agents`) is made
- * from one version.
+ * settings, memory; or a flow, `kind: "workflow"`) and what the Runtime provides around it
+ * (`runtime`: kind, image, network, setup, files, limits, secret slots). The Runtime checks the
+ * two against each other when it is saved (`422 manifest_inconsistent`); an Agent
+ * (`client.agents`) is made from one version.
  *
  * `save` takes the document, what `composeManifest` read from a folder, or a built agent or flow
  * with the runtime section to run it in: the SDK makes the harness section from the agent's
- * manifest (`harnessSectionOf`). It first uploads the files the manifest names by hash that the
- * Runtime does not hold (skills, a flow's agents' skills, runtime files), and refuses before
- * sending a tool that runs your code or an `approval`, as the Runtime runs agents from their
- * manifests alone.
+ * manifest (`harnessSectionOf`), with its skills' `secrets`, `loop` and `memory`. It first
+ * uploads the files the manifest names by hash that the Runtime does not hold (skills, a flow's
+ * agents' skills, runtime files), and refuses before sending a tool that runs your code or an
+ * `approval`, as the Runtime runs agents from their manifests alone.
  */
 import { AGENT_MANIFEST_V8_SCHEMA_VERSION, AgentManifestV8Schema, isAgentManifestName, } from "@nylorun/core/contracts";
 import { approvalRefusal, codeToolRefusal, delegateOf, harnessSectionOf, isBuiltWorkflow, loopManifestOf, } from "@nylorun/core/define";
@@ -31,15 +31,20 @@ export class ManifestGapsError extends Error {
         this.name = "ManifestGapsError";
     }
 }
-/** The agent's declarations, then those of each agent it uses as a tool. */
-function declarationsOf(agent) {
+/** An agent's binding, with its parts; none for a flow. */
+function agentBindingOf(agent) {
     if (isBuiltWorkflow(agent) || agent.manifest.kind === "workflow")
-        return [];
+        return undefined;
     const built = agent.build?.() ?? agent;
     if (isBuiltWorkflow(built))
-        return [];
+        return undefined;
     const binding = built.getBinding?.();
-    if (!binding || !("parts" in binding))
+    return binding && "parts" in binding ? binding : undefined;
+}
+/** The agent's declarations, then those of each agent it uses as a tool. */
+function declarationsOf(agent) {
+    const binding = agentBindingOf(agent);
+    if (!binding)
         return [];
     const found = [...(binding.parts ?? [])];
     for (const tool of binding.tools ?? []) {
@@ -64,6 +69,16 @@ function skillFilesOf(agent, into = new Map()) {
             into.set(sha256, source);
     return into;
 }
+/**
+ * The harness section's skills with the secret slots each reads (a SKILL.md's `secrets`, which
+ * `.skills()` and `.plugin()` keep on the agent's parts, outside its v7 manifest).
+ */
+function withSkillSecrets(agent, skills) {
+    const secrets = Object.assign({}, ...(agentBindingOf(agent)?.parts ?? []).map((part) => part.skillSecrets ?? {}));
+    if (skills === undefined || Object.keys(secrets).length === 0)
+        return skills;
+    return Object.fromEntries(Object.entries(skills).map(([key, skill]) => [key, secrets[key] ? { ...skill, secrets: [...secrets[key]] } : skill]));
+}
 const quoted = (value) => JSON.stringify(value);
 /**
  * Where a runtime section misses what a harness `requires` (agent manifest v7's, and
@@ -114,9 +129,15 @@ function prepare(input) {
         const loop = agent.manifest;
         refuse(loop);
         // `harnessSectionOf` leaves out the loop manifest's identity and its `requires`, checked here.
+        const section = harnessSectionOf(loop, input.harness === undefined ? {} : { harness: input.harness });
+        if (input.memory !== undefined && "kind" in section)
+            throw new TypeError(`memory turns on an agent's memory; ${agent.id} is a flow, whose harness section has none`);
+        const skills = "kind" in section ? undefined : withSkillSecrets(agent, section.skills);
         const harness = {
-            ...harnessSectionOf(loop, input.harness === undefined ? {} : { harness: input.harness }),
+            ...section,
+            ...(skills === undefined ? {} : { skills }),
             ...(input.loop === undefined ? {} : { loop: input.loop }),
+            ...(input.memory === undefined ? {} : { memory: input.memory }),
         };
         const description = input.description ?? loop.description;
         const metadata = input.metadata ?? loop.metadata;
@@ -168,7 +189,7 @@ export class AgentManifestsClient {
     }
     /**
      * Saves the manifest's next version (`PUT /v1/agent-manifests/{name}`), or answers the latest
-     * unchanged; every Agent that tracks the manifest moves to it (track T3). Refused before anything is sent when it
+     * unchanged; every Agent that tracks the manifest moves to it. Refused before anything is sent when it
      * misses its `requires` or, composed, its sections do not fit (`ManifestGapsError`).
      */
     async save(input, options = {}) {

package/dist/agents.d.ts

@@ -4,24 +4,24 @@
  * `pod` or `none`), one vault of secrets for its shell, MCP servers and HTTP tools, and the
  * sessions that run on it. It is made only from a saved manifest, `name` (tracking) or `name@n`
  * (pinned), and runs one version of it at a time: `put` with another version moves it, and a save
- * moves every Agent that tracks the manifest (track T3). Its manifest, kind, harness and storage
+ * moves every Agent that tracks the manifest. Its manifest, kind, harness and storage
  * are fixed (`409 agent_fixed_field`): `fork` makes a new Agent to change them. It has
  * its own id and outlives its sessions; whether it serves one person or a project is the app's
  * choice, made by its id:
  *
  * - `agents.put("users/alice/triage", { manifest: "triage", owner: "alice" })`: get-or-create
  *   in one call. Write its secrets with `agents.secrets.put(id, name, { value })` and open
- *   sessions on it with `createSession({ agent: id, ... })`. Creating it opens no session (D71).
+ *   sessions on it with `createSession({ agent: id, ... })`. Creating it opens no session.
  *
  * Ids may hold `/`; they are sent percent-encoded as one path segment. Secret values are
  * write-only: no call reads one back.
  *
- * Triggers (track T4, D74): what its manifest's `runtime.triggers` declares starts its turns with
+ * Triggers: what its manifest's `runtime.triggers` declares starts its turns with
  * no client connected. `triggers(id)` lists them with their status and next run, `pauseTrigger`,
  * `resumeTrigger` and `runTrigger` change or run one, `rotateWebhookSecret` makes a webhook
- * trigger's signing secret (D75), and `runs(id)` pages what each fire came to.
+ * trigger's signing secret, and `runs(id)` pages what each fire came to.
  *
- * Memory (track T5, D72): an Agent whose manifest sets `harness.memory` keeps Markdown files under
+ * Memory: an Agent whose manifest sets `harness.memory` keeps Markdown files under
  * `/memories` across sessions. `agents.memories` lists, reads, writes (to seed it), deletes and
  * pages the versions every change leaves.
  *
@@ -35,7 +35,7 @@ import { type Transport } from "./http.js";
 export type AgentInput = Omit<PutAgentRequest, "requestId">;
 /**
  * One secret of an Agent's vault, as written: typed, or only its value (`{ value }`, or
- * `{ headers }` for a `headers` secret) when its manifest declares the slot (D64).
+ * `{ headers }` for a `headers` secret) when its manifest declares the slot.
  */
 export type AgentSecretInput = PutAgentSecretRequest | {
     readonly value: string;
@@ -49,13 +49,13 @@ export interface AgentFilter {
     readonly state?: string;
     /** The agent manifest's name. */
     readonly manifest?: string;
-    /** `true`: only Agents moving to another version of their manifest (track T3); `false`: the others. */
+    /** `true`: only Agents moving to another version of their manifest; `false`: the others. */
     readonly outdated?: boolean;
 }
 /** The bytes of files by hash, by `sha256:<hex>` (`runtimeFiles(...).bytes`). */
 export type RuntimeFileBytes = Readonly<Record<string, Uint8Array>>;
 /**
- * A runtime section's `files` entry by content hash (Q6): `contents` (each file's path under
+ * A runtime section's `files` entry by content hash: `contents` (each file's path under
  * `path` and its bytes or text) hashed, as `entry` for the manifest's `runtime.files` and `bytes`
  * for `agentManifests.save`'s `files`, which uploads them. Each file holds at most 2 GiB.
  */
@@ -75,7 +75,7 @@ export declare class AgentSecretsClient {
      * Creates or replaces secret `name` (`PUT /v1/agents/{id}/secrets/{name}`): for
      * `environment_secret` and `environment_variable` the name is the variable's. A second
      * credential for a host or a URL is a 409 `credential_conflict`. When the Agent's manifest
-     * declares the secret's slot (D64), send only `{ value }` (or `{ headers }`); a name it does
+     * declares the secret's slot, send only `{ value }` (or `{ headers }`); a name it does
      * not declare is `409 secret_not_in_manifest`.
      */
     put(agentId: string, name: string, secret: AgentSecretInput, options?: {
@@ -95,7 +95,7 @@ export declare class AgentSecretsClient {
     }>;
 }
 /**
- * An Agent's memories (track T5, D72): `client.agents.memories`. A path is a memory's path under
+ * An Agent's memories: `client.agents.memories`. A path is a memory's path under
  * `/memories` (`conventions/release.md` or `/memories/conventions/release.md`).
  */
 export declare class AgentMemoriesClient {
@@ -149,14 +149,14 @@ export declare class AgentInstancesClient {
     private path;
     /** The Agent's secrets. */
     get secrets(): AgentSecretsClient;
-    /** The Agent's memories (track T5). */
+    /** The Agent's memories. */
     get memories(): AgentMemoriesClient;
     /**
      * Creates the Agent, its vault and its compute from a saved agent manifest, or finds the one
      * with this id (`PUT /v1/agents/{id}`): `{ manifest: "name" }` tracks the manifest (its latest
      * version when the Agent is made), `"name@n"` pins version n. On an existing Agent, labels
      * replace, `owner` sets or clears the owner guard, and `manifest` moves it to that version of
-     * its manifest (track T3): at once, at its pod's next start for a runtime change (`targetVersion`,
+     * its manifest: at once, at its pod's next start for a runtime change (`targetVersion`,
      * `waitingFor: "start"`), or once a required secret the version adds is set. Another manifest,
      * kind, harness or storage is `409 agent_fixed_field` (fork it instead).
      */
@@ -164,7 +164,7 @@ export declare class AgentInstancesClient {
         signal?: AbortSignal;
     }): Promise<AgentView>;
     /**
-     * What `put` would do to the existing Agent (`PUT /v1/agents/{id}?dryRun=true`, track T3): the
+     * What `put` would do to the existing Agent (`PUT /v1/agents/{id}?dryRun=true`): the
      * version it runs and the one `input.manifest` names, when that applies (`now`, `next_start`,
      * `secrets`, or `refused` with each fixed field), the changes, and the secrets it would wait
      * for or leave unused. Nothing changes.
@@ -343,7 +343,7 @@ export declare class AgentInstancesClient {
         signal?: AbortSignal;
     }): Promise<AgentView>;
     /**
-     * Applies a version the Agent waits to apply (`POST /v1/agents/{id}/restart`, track T3): a
+     * Applies a version the Agent waits to apply (`POST /v1/agents/{id}/restart`): a
      * running pod stops, so the next turn starts it on the version; a stopped one starts at once.
      * `retry` first moves it to the version that failed to start again. Refused during a turn.
      */
@@ -370,7 +370,7 @@ export declare class AgentInstancesClient {
         signal?: AbortSignal;
     }): Promise<AgentRestore>;
     /**
-     * Forks the Agent into a new one, `options.id` (Q15): how an Agent changes what is fixed for its
+     * Forks the Agent into a new one, `options.id`: how an Agent changes what is fixed for its
      * life (its manifest, kind, harness or storage). It is made from `options.manifest` (default the source's manifest,
      * tracking), its disk starts from `options.disk` (`latest`, the default, snapshots first; a
      * version; or `empty`) and the secrets the new manifest declares are copied

package/dist/agents.js

@@ -4,24 +4,24 @@
  * `pod` or `none`), one vault of secrets for its shell, MCP servers and HTTP tools, and the
  * sessions that run on it. It is made only from a saved manifest, `name` (tracking) or `name@n`
  * (pinned), and runs one version of it at a time: `put` with another version moves it, and a save
- * moves every Agent that tracks the manifest (track T3). Its manifest, kind, harness and storage
+ * moves every Agent that tracks the manifest. Its manifest, kind, harness and storage
  * are fixed (`409 agent_fixed_field`): `fork` makes a new Agent to change them. It has
  * its own id and outlives its sessions; whether it serves one person or a project is the app's
  * choice, made by its id:
  *
  * - `agents.put("users/alice/triage", { manifest: "triage", owner: "alice" })`: get-or-create
  *   in one call. Write its secrets with `agents.secrets.put(id, name, { value })` and open
- *   sessions on it with `createSession({ agent: id, ... })`. Creating it opens no session (D71).
+ *   sessions on it with `createSession({ agent: id, ... })`. Creating it opens no session.
  *
  * Ids may hold `/`; they are sent percent-encoded as one path segment. Secret values are
  * write-only: no call reads one back.
  *
- * Triggers (track T4, D74): what its manifest's `runtime.triggers` declares starts its turns with
+ * Triggers: what its manifest's `runtime.triggers` declares starts its turns with
  * no client connected. `triggers(id)` lists them with their status and next run, `pauseTrigger`,
  * `resumeTrigger` and `runTrigger` change or run one, `rotateWebhookSecret` makes a webhook
- * trigger's signing secret (D75), and `runs(id)` pages what each fire came to.
+ * trigger's signing secret, and `runs(id)` pages what each fire came to.
  *
- * Memory (track T5, D72): an Agent whose manifest sets `harness.memory` keeps Markdown files under
+ * Memory: an Agent whose manifest sets `harness.memory` keeps Markdown files under
  * `/memories` across sessions. `agents.memories` lists, reads, writes (to seed it), deletes and
  * pages the versions every change leaves.
  *
@@ -33,7 +33,7 @@ import { AgentPageSchema, isAgentId, } from "@nylorun/core/contracts";
 import { definitionFileHash } from "./files.js";
 import { id, segment } from "./http.js";
 /**
- * A runtime section's `files` entry by content hash (Q6): `contents` (each file's path under
+ * A runtime section's `files` entry by content hash: `contents` (each file's path under
  * `path` and its bytes or text) hashed, as `entry` for the manifest's `runtime.files` and `bytes`
  * for `agentManifests.save`'s `files`, which uploads them. Each file holds at most 2 GiB.
  */
@@ -71,7 +71,7 @@ export class AgentSecretsClient {
      * Creates or replaces secret `name` (`PUT /v1/agents/{id}/secrets/{name}`): for
      * `environment_secret` and `environment_variable` the name is the variable's. A second
      * credential for a host or a URL is a 409 `credential_conflict`. When the Agent's manifest
-     * declares the secret's slot (D64), send only `{ value }` (or `{ headers }`); a name it does
+     * declares the secret's slot, send only `{ value }` (or `{ headers }`); a name it does
      * not declare is `409 secret_not_in_manifest`.
      */
     async put(agentId, name, secret, options = {}) {
@@ -90,7 +90,7 @@ export class AgentSecretsClient {
     }
 }
 /**
- * An Agent's memories (track T5, D72): `client.agents.memories`. A path is a memory's path under
+ * An Agent's memories: `client.agents.memories`. A path is a memory's path under
  * `/memories` (`conventions/release.md` or `/memories/conventions/release.md`).
  */
 export class AgentMemoriesClient {
@@ -158,7 +158,7 @@ export class AgentInstancesClient {
     get secrets() {
         return new AgentSecretsClient(this.transport, (agentId) => this.path(agentId));
     }
-    /** The Agent's memories (track T5). */
+    /** The Agent's memories. */
     get memories() {
         return new AgentMemoriesClient(this.transport, (agentId) => this.path(agentId));
     }
@@ -167,7 +167,7 @@ export class AgentInstancesClient {
      * with this id (`PUT /v1/agents/{id}`): `{ manifest: "name" }` tracks the manifest (its latest
      * version when the Agent is made), `"name@n"` pins version n. On an existing Agent, labels
      * replace, `owner` sets or clears the owner guard, and `manifest` moves it to that version of
-     * its manifest (track T3): at once, at its pod's next start for a runtime change (`targetVersion`,
+     * its manifest: at once, at its pod's next start for a runtime change (`targetVersion`,
      * `waitingFor: "start"`), or once a required secret the version adds is set. Another manifest,
      * kind, harness or storage is `409 agent_fixed_field` (fork it instead).
      */
@@ -175,7 +175,7 @@ export class AgentInstancesClient {
         return this.transport.json(this.path(agentId), "PUT", { requestId: id(), ...input }, options.signal);
     }
     /**
-     * What `put` would do to the existing Agent (`PUT /v1/agents/{id}?dryRun=true`, track T3): the
+     * What `put` would do to the existing Agent (`PUT /v1/agents/{id}?dryRun=true`): the
      * version it runs and the one `input.manifest` names, when that applies (`now`, `next_start`,
      * `secrets`, or `refused` with each fixed field), the changes, and the secrets it would wait
      * for or leave unused. Nothing changes.
@@ -207,7 +207,7 @@ export class AgentInstancesClient {
         return this.transport.json(`${this.path(agentId)}/stop`, "POST", {}, options.signal);
     }
     /**
-     * Applies a version the Agent waits to apply (`POST /v1/agents/{id}/restart`, track T3): a
+     * Applies a version the Agent waits to apply (`POST /v1/agents/{id}/restart`): a
      * running pod stops, so the next turn starts it on the version; a stopped one starts at once.
      * `retry` first moves it to the version that failed to start again. Refused during a turn.
      */
@@ -235,7 +235,7 @@ export class AgentInstancesClient {
         return this.transport.json(`${this.path(agentId)}/restore`, "POST", { requestId: id(), version }, options.signal);
     }
     /**
-     * Forks the Agent into a new one, `options.id` (Q15): how an Agent changes what is fixed for its
+     * Forks the Agent into a new one, `options.id`: how an Agent changes what is fixed for its
      * life (its manifest, kind, harness or storage). It is made from `options.manifest` (default the source's manifest,
      * tracking), its disk starts from `options.disk` (`latest`, the default, snapshots first; a
      * version; or `empty`) and the secrets the new manifest declares are copied

package/dist/artifacts.d.ts

@@ -5,7 +5,7 @@
  * short-lived URL that needs no credential, for `<img>` tags and sharing. A message names an
  * artifact in a file part (`session.inputParts`), and the model reads it.
  *
- * Folders (F8.2): at the end of each turn the Runtime exports `/workspace/outputs` of the
+ * Folders: at the end of each turn the Runtime exports `/workspace/outputs` of the
  * session's sandbox as a version of its `outputs` folder. Read one as a tree, one file by path,
  * a diff between versions or a zip.
  *

package/dist/artifacts.js

@@ -5,7 +5,7 @@
  * short-lived URL that needs no credential, for `<img>` tags and sharing. A message names an
  * artifact in a file part (`session.inputParts`), and the model reads it.
  *
- * Folders (F8.2): at the end of each turn the Runtime exports `/workspace/outputs` of the
+ * Folders: at the end of each turn the Runtime exports `/workspace/outputs` of the
  * session's sandbox as a version of its `outputs` folder. Read one as a tree, one file by path,
  * a diff between versions or a zip.
  *

package/dist/compose.js

@@ -1,12 +1,13 @@
 /**
- * Three-file authoring (protocol 16, track T2): `composeManifest(dir)` reads `agent.manifest.json`
+ * Three-file authoring (protocol 16): `composeManifest(dir)` reads `agent.manifest.json`
  * and the files it names, and makes the one agent manifest v8 document the Runtime saves, with
  * the bytes of every file it names by hash. `nylorun apply` runs it for each folder.
  *
  * - `agent.manifest.json` (`AgentManifestFileSchema`): the manifest's name, description and
  *   metadata, with `harness` and `runtime` inline or as paths to the two files below.
  * - `harness.manifest.json` (`HarnessManifestFileSchema`): the harness section, whose `skills`
- *   may be a folder of skill folders, `mcpServers` an `mcp.json` (the Agent Plugins format), and
+ *   may be a folder of skill folders (each skill's `secrets` from its SKILL.md's frontmatter),
+ *   `mcpServers` an `mcp.json` (the Agent Plugins format), and
  *   `plugins` Agent Plugin folders, folded in as `.plugin()` folds them; `credentials` names the
  *   `runtime.secrets` slot each MCP server or HTTP tool authenticates with; `requires` is checked
  *   against the runtime section here, since the API never sees it.
@@ -101,6 +102,15 @@ function warningsOf(diagnostics) {
 function relativeTo(path) {
     return relative(process.cwd(), path) || path;
 }
+/** A skill read from its folder as the harness section declares it, with its SKILL.md's `secrets`. */
+function harnessSkill(skill) {
+    return {
+        name: skill.name,
+        description: skill.description,
+        files: { ...skill.files },
+        ...(skill.secrets === undefined ? {} : { secrets: [...skill.secrets] }),
+    };
+}
 /** The agent harness section a `harness.manifest.json` describes, its paths resolved. */
 function agentHarness(file, base, where, files, warnings) {
     const skills = {};
@@ -120,7 +130,7 @@ function agentHarness(file, base, where, files, warnings) {
     if (typeof file.skills === "string") {
         const diagnostics = [];
         for (const skill of Object.values(loadSkillsFromDirectory(resolve(base, file.skills), diagnostics))) {
-            addSkill({ name: skill.name, description: skill.description, files: { ...skill.files } }, file.skills);
+            addSkill(harnessSkill(skill), file.skills);
             for (const [sha256, source] of Object.entries(skill.sources))
                 files.set(sha256, source);
         }
@@ -156,7 +166,7 @@ function agentHarness(file, base, where, files, warnings) {
         warnings.push(...warningsOf(loaded.diagnostics).map((message) => `Plugin '${loaded.name}': ${message}`));
         const label = { name: loaded.name, ...(loaded.version === undefined ? {} : { version: loaded.version }) };
         for (const skill of Object.values(loaded.skills)) {
-            addSkill({ name: skill.name, description: skill.description, files: { ...skill.files }, plugin: label }, entry);
+            addSkill({ ...harnessSkill(skill), plugin: label }, entry);
             for (const [sha256, source] of Object.entries(skill.sources))
                 files.set(sha256, source);
         }
@@ -185,6 +195,7 @@ function agentHarness(file, base, where, files, warnings) {
         ...(plugins.length === 0 ? {} : { plugins }),
         ...(file.outputSchema === undefined ? {} : { outputSchema: file.outputSchema }),
         ...(file.loop === undefined ? {} : { loop: file.loop }),
+        ...(file.memory === undefined ? {} : { memory: file.memory }),
     };
 }
 /**

package/dist/files.d.ts

@@ -1,5 +1,5 @@
 /**
- * Definition files (track R2 M4): `client.files`. A definition names the files it needs by the
+ * Definition files: `client.files`. A definition names the files it needs by the
  * SHA-256 of their bytes (a skill's folder, `SkillManifest.files`); the Runtime holds each one
  * once, uploaded with `PUT /v1/files/sha256:<hex>`, and refuses a manifest naming a file it
  * does not hold (`400 definition_files_missing`). `agentManifests.save` uploads them itself.

package/dist/files.js

@@ -1,5 +1,5 @@
 /**
- * Definition files (track R2 M4): `client.files`. A definition names the files it needs by the
+ * Definition files: `client.files`. A definition names the files it needs by the
  * SHA-256 of their bytes (a skill's folder, `SkillManifest.files`); the Runtime holds each one
  * once, uploaded with `PUT /v1/files/sha256:<hex>`, and refuses a manifest naming a file it
  * does not hold (`400 definition_files_missing`). `agentManifests.save` uploads them itself.

package/dist/index.d.ts

@@ -6,7 +6,7 @@ export { Agent, AgentBuilder } from "./builder.js";
 export { AgentBuildError, AgentLifecycleError, VerdictSchema, isVerdict, WorkflowBuildError, isBuiltWorkflow, flow, tool, http, defineSchema, ToolError, } from "@nylorun/core/define";
 export type { FlowAgentBuilder, Flow, Named, LoopOptions, StageOptions, HttpTarget, } from "@nylorun/core/define";
 export type { AgentOptions, AgentManifest, BuiltAgent, BuiltWorkflow, Verdict, WorkflowBinding, WorkflowManifest, ToolDefinition, ToolExecutionContext, ToolOutcome, JsonValue, JsonObject, } from "@nylorun/core/define";
-export type { SessionPage, SessionListItem, SessionManifestView, HistoryPage, SessionUsageTotals, ModelCall, ModelCallsPage, AgentPage, ToolCall, ToolCallsPage, LiveEvent, SessionEvent, SessionEventOf, EventType, SessionCommand, SubjectScope, AgentView, AgentState, AgentAttention, AgentEvent, AgentEventType, EgressRunningTurn, EnvironmentKind, EnvironmentRecipe, EnvironmentSecretSlot, AgentSecretView, AgentSnapshot, AgentRestore, AgentDiskVersions, RestoreAgentRequest, AgentForkPlan, AgentMovePlan, RestartAgentRequest, ForkAgentRequest, ForkAgentResponse, DeleteAgentResponse, PutAgentRequest, PutAgentSecretRequest, AgentManifestV8, AgentManifestFile, HarnessManifestFile, RuntimeManifestFile, RuntimeSection, AgentManifestChange, AgentManifestWarning, AgentManifestPlan, AgentManifestView, AgentManifestVersions, SaveAgentManifestResponse, DeleteAgentManifestResponse, MessagePart, ArtifactView, ArtifactKind, ArtifactListItem, ArtifactPage, ArtifactVersionView, ArtifactLink, UploadArtifactResponse, DefinitionFileView, ArtifactTree, ArtifactDiff, FolderEntry, } from "@nylorun/core/contracts";
+export type { SessionPage, SessionListItem, SessionManifestView, HistoryPage, SessionUsageTotals, CostSplit, ModelCall, ModelCallsPage, AgentPage, ToolCall, ToolCallsPage, LiveEvent, SessionEvent, SessionEventOf, EventType, SessionCommand, SubjectScope, AgentView, AgentState, AgentAttention, AgentEvent, AgentEventType, EgressRunningTurn, EnvironmentKind, EnvironmentRecipe, EnvironmentSecretSlot, AgentSecretView, AgentSnapshot, AgentRestore, AgentDiskVersions, RestoreAgentRequest, AgentForkPlan, AgentMovePlan, RestartAgentRequest, ForkAgentRequest, ForkAgentResponse, DeleteAgentResponse, PutAgentRequest, PutAgentSecretRequest, AgentManifestV8, AgentManifestFile, HarnessManifestFile, RuntimeManifestFile, RuntimeSection, AgentManifestChange, AgentManifestWarning, AgentManifestPlan, AgentManifestView, AgentManifestVersions, SaveAgentManifestResponse, DeleteAgentManifestResponse, MessagePart, ArtifactView, ArtifactKind, ArtifactListItem, ArtifactPage, ArtifactVersionView, ArtifactLink, UploadArtifactResponse, DefinitionFileView, ArtifactTree, ArtifactDiff, FolderEntry, } from "@nylorun/core/contracts";
 export { AGENT_EVENT_TYPES, AGENT_STATES, COMPUTE_STATES, RUNTIME_LIMIT_DEFAULTS, SUBJECT_SCOPES, } from "@nylorun/core/contracts";
 export type { AgentHarnessSection, HarnessSection, HarnessSkill, HarnessMcpServer, WorkflowHarnessSection, } from "@nylorun/core";
 export { AgentsClient, SessionClient, createClient } from "./client.js";

package/dist/session-client.d.ts

@@ -26,7 +26,7 @@ export interface SessionView {
 }
 /** `AgentsClient.createSession`'s options. */
 export interface CreateSessionOptions {
-    /** The session's id, which the app chooses (D71). Default: a new UUID. */
+    /** The session's id, which the app chooses. Default: a new UUID. */
     id?: string;
     /**
      * The Agent the session runs on (`client.agents`): its manifest version, its sandbox and its
@@ -221,6 +221,15 @@ export declare class SessionClient {
         unpricedCalls: number;
         unreportedCalls: number;
         unknownQualityCalls: number;
+        costSplit: {
+            input: number;
+            cacheRead: number;
+            cacheWrite: number;
+            output: number;
+        };
+        splitCalls: number;
+        modelTimeMs: number;
+        timedCalls: number;
     }>;
     modelCalls(options?: {
         turnId?: string;
@@ -237,6 +246,8 @@ export declare class SessionClient {
             provider: string | null;
             model: string | null;
             at: string;
+            startedAt: string | null;
+            endedAt: string | null;
             outcome: "completed" | "failed";
             usage: {
                 inputTokens: number;
@@ -249,13 +260,19 @@ export declare class SessionClient {
                 duplicate: boolean;
                 tokensReported: boolean | null;
                 costKnown: boolean | null;
+                costSplit: {
+                    input: number;
+                    cacheRead: number;
+                    cacheWrite: number;
+                    output: number;
+                } | null;
             } | null;
         }[];
         nextCursor: string | null;
         asOf: string;
     }>;
     /**
-     * The session's tool calls (R5, Host feature `tool-calls`), in the order they were first sent:
+     * The session's tool calls (Host feature `tool-calls`), in the order they were first sent:
      * each one's tool, input, status and sends. `attempts` above 1: a crash re-sent it.
      */
     toolCalls(options?: {
@@ -292,7 +309,7 @@ export declare class SessionClient {
         asOf: string;
     }>;
     /**
-     * A turn's trace (R7, Host feature `traces`): its spans as OTLP/HTTP JSON (`resourceSpans`), as
+     * A turn's trace (Host feature `traces`): its spans as OTLP/HTTP JSON (`resourceSpans`), as
      * the Runtime posts them to an OTLP collector. Post it to a collector's `/v1/traces` to backfill
      * one, or read it without one.
      */

package/dist/session-client.js

@@ -215,7 +215,7 @@ export class SessionClient {
         return ModelCallsPageSchema.parse(await this.transport.json(`${this.path}/calls/model?${query}`, "GET", undefined, options.signal));
     }
     /**
-     * The session's tool calls (R5, Host feature `tool-calls`), in the order they were first sent:
+     * The session's tool calls (Host feature `tool-calls`), in the order they were first sent:
      * each one's tool, input, status and sends. `attempts` above 1: a crash re-sent it.
      */
     async toolCalls(options = {}) {
@@ -228,7 +228,7 @@ export class SessionClient {
         return ToolCallsPageSchema.parse(await this.transport.json(`${this.path}/calls/tool?${query}`, "GET", undefined, options.signal));
     }
     /**
-     * A turn's trace (R7, Host feature `traces`): its spans as OTLP/HTTP JSON (`resourceSpans`), as
+     * A turn's trace (Host feature `traces`): its spans as OTLP/HTTP JSON (`resourceSpans`), as
      * the Runtime posts them to an OTLP collector. Post it to a collector's `/v1/traces` to backfill
      * one, or read it without one.
      */

package/dist/skills/load.d.ts

@@ -14,6 +14,11 @@ export declare class SkillsError extends Error {
 export interface LoadedSkill {
     readonly name: string;
     readonly description: string;
+    /**
+     * The `runtime.secrets` slots its scripts read (`environment_secret` or `environment_variable`),
+     * from its SKILL.md's frontmatter `secrets`: sorted, each once.
+     */
+    readonly secrets?: readonly string[];
     /** Every file of the folder by its `/`-separated path, as `sha256:<hex>`. */
     readonly files: Readonly<Record<string, string>>;
     /** Each file's bytes, by `sha256:<hex>`, for the client to upload. */
@@ -32,11 +37,14 @@ export declare function loadSkillsFromDirectory(directory: string, diagnostics:
     readonly boundary?: string;
     readonly codePrefix?: string;
 }): Readonly<Record<string, LoadedSkill>>;
-export declare function parseSkill(text: string, directoryName: string): {
+/** A SKILL.md's frontmatter and instructions: `secrets` lists the secret slots its scripts read. */
+export interface ParsedSkill {
     name: string;
     description: string;
+    secrets?: string[];
     instructions: string;
-} | undefined;
+}
+export declare function parseSkill(text: string, directoryName: string): ParsedSkill | undefined;
 /**
  * Every file of `directory` (a runtime section's `files` entry with `from`), hashed as a skill's
  * folder is: each by its `/`-separated path, with where to read its bytes. Version control, OS

package/dist/skills/load.js

@@ -3,6 +3,7 @@ import { closeSync, existsSync, openSync, readdirSync, readFileSync, readSync, r
 import { open } from "node:fs/promises";
 import { isAbsolute, join, relative, resolve, sep } from "node:path";
 import { SKILL_ENTRY, skillFilePathIssue, } from "@nylorun/core/define";
+import { ENVIRONMENT_NAME_PATTERN } from "@nylorun/core/contracts";
 import matter from "gray-matter";
 const SKILL_NAME = /^[a-z0-9]+(?:-[a-z0-9]+)*$/;
 /** Version control and operating system files, never part of a skill. */
@@ -71,12 +72,12 @@ export function loadSkillsFromDirectory(directory, diagnostics, options = {}) {
             });
             continue;
         }
-        const parsed = parseSkill(readFileSync(skillReal, "utf8"), entry.name);
-        if (!parsed) {
+        const parsed = readSkill(readFileSync(skillReal, "utf8"), entry.name);
+        if (typeof parsed === "string") {
             diagnostics.push({
                 severity: "warning",
                 code: `${prefix}.skill-skipped`,
-                message: `Skipped skill '${entry.name}' because SKILL.md is not a valid Agent Skill`,
+                message: `Skipped skill '${entry.name}' because SKILL.md ${parsed}`,
                 path: skillFile,
             });
             continue;
@@ -93,28 +94,43 @@ export function loadSkillsFromDirectory(directory, diagnostics, options = {}) {
         skills[parsed.name] = {
             name: parsed.name,
             description: parsed.description,
+            ...(parsed.secrets === undefined ? {} : { secrets: parsed.secrets }),
             ...readFiles(`skill '${parsed.name}'`, boundary, directoryReal, diagnostics, prefix),
         };
     }
     return skills;
 }
 export function parseSkill(text, directoryName) {
+    const parsed = readSkill(text, directoryName);
+    return typeof parsed === "string" ? undefined : parsed;
+}
+const INVALID_SKILL = "is not a valid Agent Skill";
+/** The skill a SKILL.md declares, or why it declares none. */
+function readSkill(text, directoryName) {
     let parsed;
     try {
         parsed = matter(text);
     }
     catch {
-        return undefined;
+        return INVALID_SKILL;
     }
     const name = asTrimmedString(parsed.data.name);
     const description = asTrimmedString(parsed.data.description);
     if (!name || !description || description.length > 1024)
-        return undefined;
+        return INVALID_SKILL;
     if (name.length > 64 || !SKILL_NAME.test(name) || name !== directoryName)
-        return undefined;
+        return INVALID_SKILL;
+    const secrets = parsed.data.secrets;
+    if (secrets !== undefined &&
+        (!Array.isArray(secrets) ||
+            !secrets.every((item) => typeof item === "string" && ENVIRONMENT_NAME_PATTERN.test(item))))
+        return "has secrets that are not a list of environment variable names";
     return {
         name,
         description,
+        ...(secrets === undefined || secrets.length === 0
+            ? {}
+            : { secrets: [...new Set(secrets)].sort() }),
         instructions: parsed.content.replace(/^\r?\n/, ""),
     };
 }

package/dist/skills/skills.d.ts

@@ -18,13 +18,15 @@ export interface SkillsPart extends PartDeclaration {
  * ```
  *
  * Sets `skills`: each skill's name, description and files (every file of its folder, binary
- * included, by content hash). The client uploads the files the Runtime lacks when it saves the
- * agent's manifest; the Runtime adds the skill catalog and serves `load_skill` / `read_skill_resource`
- * from them.
+ * included, by content hash). A SKILL.md's frontmatter `secrets` (environment variable names)
+ * become the skill's `secrets` in the harness section when the agent's manifest is saved. The
+ * client uploads the files the Runtime lacks when it saves the agent's manifest; the Runtime adds
+ * the skill catalog and serves `load_skill` / `read_skill_resource` from them.
  */
 export declare function skills(directory: string): SkillsPart;
 /**
- * The manifest's skills and the bytes behind their files. A plugin's skills carry its label, so
- * a tool call can be traced to the plugin that brought the skill.
+ * The manifest's skills, the bytes behind their files and the secret slots their SKILL.md lists
+ * (`secrets`, the harness section's when the agent is saved). A plugin's skills carry its label,
+ * so a tool call can be traced to the plugin that brought the skill.
  */
-export declare function skillsDeclaration(listed: readonly LoadedSkill[], plugin?: PluginLabel): Required<Pick<PartDeclaration, "skills" | "skillFiles">>;
+export declare function skillsDeclaration(listed: readonly LoadedSkill[], plugin?: PluginLabel): Required<Pick<PartDeclaration, "skills" | "skillFiles">> & Pick<PartDeclaration, "skillSecrets">;

package/dist/skills/skills.js

@@ -13,9 +13,10 @@ import { loadSkillsFromDirectory, resolveSkillsRoot, } from "./load.js";
  * ```
  *
  * Sets `skills`: each skill's name, description and files (every file of its folder, binary
- * included, by content hash). The client uploads the files the Runtime lacks when it saves the
- * agent's manifest; the Runtime adds the skill catalog and serves `load_skill` / `read_skill_resource`
- * from them.
+ * included, by content hash). A SKILL.md's frontmatter `secrets` (environment variable names)
+ * become the skill's `secrets` in the harness section when the agent's manifest is saved. The
+ * client uploads the files the Runtime lacks when it saves the agent's manifest; the Runtime adds
+ * the skill catalog and serves `load_skill` / `read_skill_resource` from them.
  */
 export function skills(directory) {
     const root = resolveSkillsRoot(directory);
@@ -29,10 +30,12 @@ export function skills(directory) {
     return { id, root, ...skillsDeclaration(listed), diagnostics };
 }
 /**
- * The manifest's skills and the bytes behind their files. A plugin's skills carry its label, so
- * a tool call can be traced to the plugin that brought the skill.
+ * The manifest's skills, the bytes behind their files and the secret slots their SKILL.md lists
+ * (`secrets`, the harness section's when the agent is saved). A plugin's skills carry its label,
+ * so a tool call can be traced to the plugin that brought the skill.
  */
 export function skillsDeclaration(listed, plugin) {
+    const secrets = listed.filter((skill) => skill.secrets !== undefined).map((skill) => [skill.name, skill.secrets]);
     return {
         skills: Object.fromEntries(listed.map((skill) => [
             skill.name,
@@ -44,5 +47,6 @@ export function skillsDeclaration(listed, plugin) {
             },
         ])),
         skillFiles: Object.assign({}, ...listed.map((skill) => skill.sources)),
+        ...(secrets.length === 0 ? {} : { skillSecrets: Object.fromEntries(secrets) }),
     };
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@nylorun/agents",
-  "version": "0.24.0-beta",
+  "version": "0.26.0-beta",
   "description": "Nylorun agent definitions and session client",
   "type": "module",
   "license": "Apache-2.0",
@@ -43,7 +43,7 @@
     "test": "vitest run --passWithNoTests"
   },
   "dependencies": {
-    "@nylorun/core": "0.24.0-beta",
+    "@nylorun/core": "0.26.0-beta",
     "gray-matter": "^4.0.3"
   },
   "peerDependencies": {