@nylorun/agents 0.19.1-beta → 0.21.0-beta

package/README.md

@@ -1,11 +1,11 @@
 # @nylorun/agents
 
 Runtime API client package: definition authoring and a session client. The Tenant's
-settings, models, vaults, signing keys and application keys are the Management
+settings, models, credential coverage, signing keys and application keys are the Management
 API's, through [`@nylorun/admin`](../admin/README.md). Depends only on `@nylorun/core` among Nylorun
 packages. A developer application's production tree should contain only this
 package and `@nylorun/core` from Nylorun. Vocabulary:
-[runtime/src/CONTEXT.md](../runtime/src/CONTEXT.md).
+[runtime/server/src/CONTEXT.md](../../runtime/server/src/CONTEXT.md).
 
 ## Application entry: save your agents
 
@@ -14,12 +14,12 @@ package and `@nylorun/core` from Nylorun. Vocabulary:
 import { createClient } from "@nylorun/agents";
 import { agents } from "../agents/index.js";
 
-const client = createClient();
+const client = await createClient();
 for (const agent of agents) await client.saveAgent(agent);
 ```
 
-The Runtime runs each agent from its manifest and the files saved with it (skills), and
-never calls your code during a session. Your services are reached as tools: [HTTP
+The Runtime runs each agent entirely from its manifest and the files saved with it
+(skills), so a session needs nothing from your process. Your services are reached as tools: [HTTP
 tools](#http-tools) and remote MCP servers. `saveAgent` refuses, before sending anything, an
 agent with a tool that would run your code (`tool({ run })`) or a flow agent with a tool
 stage: make it an `http()` tool or serve it from a remote MCP server. `tool({ run })` still
@@ -29,7 +29,7 @@ runs in the local engine (`@nylorun/harness/run`). `implementationVersion` defau
 `createClient()` finds the Runtime through the two `NYLORUN_*` variables or the Project link
 that `npx nylorun start` writes; with neither, it fails with `connection_missing` and names
 those steps. Action endpoints (`createActionHandler`), and before them `connectAgents` and
-executors, were removed; see [MIGRATION.md](../MIGRATION.md#action-endpoints-are-removed).
+executors, were removed; see [MIGRATION.md](../../guides/MIGRATION.md#action-endpoints-are-removed).
 
 ## HTTP tools
 
@@ -47,15 +47,14 @@ const refundOrder = http({
   output: z.object({ refundId: z.string() }), // optional
   url: "https://billing.example.com/refunds",
   method: "POST", // default; or PUT, PATCH
-  credential: "billing", // optional: a vault credential bound to this URL
+  credential: "billing", // optional: the session's Environment holds a credential for this URL
   timeoutMs: 20_000, // default 60000, at most 300000
-  approval: "always", // optional: each call waits for session.approve()
 });
 
 export const support = Agent({ id: "support" }).tools(refundOrder);
 ```
 
-The tool goes into the manifest as `http` (and `approval`), and the Runtime's
+The tool goes into the manifest as `http`, and the Runtime's
 Tool Gate sends the model's input as the JSON body, under the Host's address
 policy (`NYLORUN_ENDPOINT_*`), with `content-type: application/json`,
 `Nylorun-Session-Id`, `Nylorun-Turn-Id`, `Nylorun-Agent-Id` and an
@@ -63,21 +62,76 @@ policy (`NYLORUN_ENDPOINT_*`), with `content-type: application/json`,
 restart, so your service can drop duplicates. A `2xx` JSON answer is the output
 (text when it is not JSON and the tool has no `output`), checked against
 `output`. Any other status (with the start of its body), a timeout, a refused
-address or a mismatched output is a tool error the model sees. A call whose
-answer was lost with the gateway is `uncertain` and never sent again.
-
-`credential` works as for a remote MCP server: the session's attached vaults
-must hold a credential bound to the tool's exact URL (a `credentialSelections`
-entry whose `serverName` is the `credential` picks one when several are), else
-the call fails before it is sent (`http.credential`). A credential with `via`
+address or a mismatched output is a tool error the model sees.
+
+**How tool calls are delivered.** Each MCP or HTTP tool call the model decides
+is sent at least once, and every send carries the same key: `Idempotency-Key`
+for an HTTP tool, `_meta["nylorun/idempotency-key"]` on an MCP `tools/call`. A
+crash, a restart or a lost connection to the gateway sends the call again with
+that key, up to 3 sends; after that the model gets `tool.interrupted` ("may
+have run") and decides. A tool that honors the key runs once; one that ignores
+it may act twice, and `attempts` above 1 in `tool.completed` and in
+`session.toolCalls()` marks where. Both also say where each call ran (`kind`:
+`mcp`, `http`, `sandbox`, `platform` for the Runtime's own tools, or `harness`),
+its `server`, the `skill` it ran and the `plugin` that brought its server or
+skill. A sandbox command (`bash`, `write` and the
+rest) is never run twice by the Runtime: a crash fails it to the model as
+`tool.interrupted`. When the model decides the same call again, in a later
+turn say, that is a new call with a new key: put a business key (an order or
+charge id) in the tool's input schema to refuse it too.
+
+`credential` works as for a remote MCP server: the vault of the session's
+Environment must hold a credential bound to the tool's exact URL, else the call
+fails before it is sent (`http.credential`). A credential with `via`
 sends the call there instead, such as a gateway, with the session owner in its
-identity header, and a `401` is `credential_rejected` to the model, not retried. `approval: "always"` pauses the turn for `session.approve()`; a
-denied call never runs and the model sees the denial. A remote MCP server takes
-`approval: "always"` too, for every one of its tools:
-`.mcp({ shop: { type: "streamable-http", url, approval: "always" } })`.
-An HTTP tool is also a flow stage (see [Flow agents](#flow-agents)), and runs
+identity header, and a `401` is `credential_rejected` to the model, not retried.
+Whether a call waits for a person is not the tool's to say: it is the Tenant's
+[tool policy](#tool-policy). An HTTP tool is also a flow stage (see [Flow agents](#flow-agents)), and runs
 only on the Runtime (a local `run()` reports `http.runtime-only`).
 
+## Tool policy
+
+Which MCP and HTTP tool calls run, wait for a person, or are refused is the
+Tenant's tool policy, set by the operator on the Management API with a
+management key (`PUT /v1/tenant/tool-policy`, `admin.toolPolicy.put()` in
+`@nylorun/admin`). The Runtime applies it to every call of every harness as it
+journals the call, before anything is sent, and its Tool Gate runs only a call
+the journal holds running, so a harness cannot skip it.
+
+```ts
+import { createAdmin } from "@nylorun/admin";
+
+await createAdmin().toolPolicy.put({
+  rules: [
+    { effect: "ask", tool: "refund_order", reason: "Refunds need a person" },
+    { effect: "deny", tool: "refund_order", when: { amount: { gt: 10_000 } } },
+    { effect: "ask", server: "github", tool: "github__delete_*" },
+  ],
+});
+```
+
+A rule matches a call when every selector it sets matches: `tool` (the name the
+model calls it by; `*` matches any run of characters), `server` (an MCP
+server's name), `kind` (`mcp` or `http`), `agent` (the agent that calls it) and
+`when` (fields of the call's input by dotted path, each tested with `equals`,
+`in`, `gt`, `gte`, `lt`, `lte` or `matches`). The strictest matching rule
+decides, and a call no rule matches runs:
+
+- `deny`: the call is never sent; the model gets `tool.denied` with the rule's
+  `reason`.
+- `ask`: the turn pauses (`turn.paused`, with the tool, its input and the
+  reason). `session.approve(interactionId, true)` sends that exact call;
+  `false` fails it to the model as `tool.denied`, unsent. Nothing holds a
+  process while it waits, so an approval can wait a day, or a Runtime restart.
+  Studio shows an approval card; AG-UI ends the run with a `tool_approval`
+  interrupt.
+- `allow`: it runs.
+
+Sandbox tools never cross the gate: their network side is egress policy. A
+manifest no longer sets `approval` (the Runtime and `saveAgent` refuse it); a
+session pinned to a manifest saved with `approval: "always"` keeps it, as an
+ask, until it ends.
+
 ## Connection resolution
 
 `resolveConnection` / `createClient()`:
@@ -92,7 +146,7 @@ only on the Runtime (a local `run()` reports `http.runtime-only`).
    (format 0 to 2), a link without credentials, or a file that does not
    validate fails with `connection_missing`: run `npx nylorun start` in the
    project again. The Project files are read by `@nylorun/core/project`, as
-   `@nylorun/admin`, `nylorun` and `nylo` read them.
+   `@nylorun/admin` and `nylorun` read them.
 
 Sources never mix. Partial environment fails with `connection_missing`. A
 Runtime serves one Tenant, so nothing names it: the `tenant` option is gone
@@ -127,12 +181,7 @@ await session.input("Look up item 123", { idempotencyKey: requestId });
 const history = await session.history();
 ```
 
-```sh
-eval "$(npx @nylorun/cli env)"
-# → NYLORUN_RUNTIME_URL, NYLORUN_SERVER_KEY
-```
-
-Every request sets `Nylorun-Protocol` (8) and no `Nylorun-Tenant`: the Runtime
+Every request sets `Nylorun-Protocol` (14) and no `Nylorun-Tenant`: the Runtime
 serves one Tenant. Before the first authenticated
 request, `Transport` fetches `/health` once, checks protocol compatibility, and
 throws `IncompatibleRuntimeError` / `incompatible_host` when the Host range or
@@ -152,7 +201,7 @@ const assistant = Agent({ id: "assistant", name: "Order assistant" })
 
 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`), at most 500 files of 10 MiB each. `saveAgent` uploads the files the Runtime does not hold (`client.files`, `PUT /v1/files/sha256:<hex>`) before it puts the definition, which the Runtime refuses while it names a file it lacks (`400 definition_files_missing`).
 
-The Runtime serves the skills itself, with no call to your process: `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>/`, so the model can run a skill's scripts with `bash`. Run without a Runtime, the skill tools only say so.
+The Runtime serves the skills itself, with no call to your process. When a session pins the agent, the Runtime adds the skill catalog to the instructions and two tools to the manifest's `runtime` block: `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`.
 
 Declare MCP servers with `.mcp(...)` (same map shape as agent-plugins `mcpServers`):
 
@@ -166,44 +215,76 @@ const assistant = Agent({ id: "assistant", name: "Assistant" })
   });
 ```
 
-Each key names a server; its `name` defaults to the key and, when given, must equal it. Repeated `.mcp()` calls add servers to the same capability. Nylorun accepts remote servers only: `streamable-http` and `sse` ([Agent Plugins MCP servers](https://agent-plugins.org/plugin-authors/mcp-servers)); a `stdio` server is refused, so run it behind an HTTP transport and declare its URL. Attach an Agent Plugin package with `.plugin(path)`: its skills and remote MCP servers join the agent, and a stdio server in its `mcp.json` throws.
+Each key names a server; its `name` defaults to the key and, when given, must equal it. Repeated `.mcp()` calls add servers to the manifest's `mcpServers`. Nylorun accepts remote servers only: `streamable-http` and `sse` ([Agent Plugins MCP servers](https://agent-plugins.org/plugin-authors/mcp-servers)); a `stdio` server is refused, so run it behind an HTTP transport and declare its URL. Attach an Agent Plugin package with `.plugin(path)`: its skills and remote MCP servers join the agent's `skills` and `mcpServers`, each labelled `plugin: { name, version }` from its `plugin.json`, and a stdio server in its `mcp.json` throws. Names are unique across the agent's tools, skills and servers.
 
-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, approval: "always" } }` is an allowlist with one approval. 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. Either setting makes the manifest v6 (see MIGRATION.md).
+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. Either setting makes the manifest v6 (see MIGRATION.md).
 
-A manifest never carries a server's credential, and its `headers` hold no secret. The operator gives the server's URL a vault credential (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), and the session's attached vaults supply it: [DEPLOYMENT.md](../DEPLOYMENT.md#mcp-servers-and-http-tools), which also shows `nylorun mcp inspect` for listing a server's tools first. 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. You write a credential for the server's URL into an Environment (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.environments.secrets.put`), and sessions that name the Environment use it: [DEPLOYMENT.md](../../guides/DEPLOYMENT.md#mcp-servers-and-http-tools), which also shows `nylorun mcp inspect` for listing a server's tools first. After `saveAgent`, `admin.coverage({ agentId, environmentId })` in `@nylorun/admin` says which credential each server and HTTP tool would get in that Environment ([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`.
 
-Give a session a sandbox when you open it. The agent declares nothing, so the same agent runs with or without one, in any Tenant:
+A session runs in an **Environment**: one sandbox and one vault, with an id you choose, which outlives the sessions that name it (protocol 11). It is made from one version of an **environment manifest** or from inline fields, and never changes what it runs after that (protocol 14). The agent names no Environment, so the same agent runs in any Tenant; it may state what it needs (`.requires()`). Whether an Environment serves one session, one person or a project is your app's choice:
 
 ```ts
-const session = await client.createSession({
-  agentId: "analyst",
-  ownerUserId,
-  sandbox: {
-    network: { allow: ["pypi.org", "files.pythonhosted.org"] }, // no egress unless you list hosts
-    resources: { cpus: 2, memory: "2GiB" },
-  },
+import { environmentManifest } from "@nylorun/agents";
+
+// A kind of Environment, saved like an agent: a named, versioned definition (or a JSON file with $schema).
+const analystBox = environmentManifest({
+  name: "analyst-box",
+  kind: "pod",
+  image: "python:3.13-slim",
+  network: { allowedHosts: ["pypi.org", "files.pythonhosted.org", "api.github.com"] },
+  setup: [{ command: "pip install pandas" }],
+  secrets: { GH_TOKEN: { type: "environment_secret", allowedHosts: ["api.github.com"], required: true } },
+});
+const plan = await client.environments.manifests.plan(analystBox); // changes, errors, warnings, Environments behind
+await client.environments.manifests.save(analystBox, { ifMatch: plan.from ?? 0 });
+
+// One per person or project, made from the manifest's latest version and pinned to it.
+await client.environments.put("users/alice/analyst", { manifest: "analyst-box", ownerUserId: "alice" });
+await client.environments.secrets.put("users/alice/analyst", "GH_TOKEN", { value: process.env.ALICE_GITHUB_TOKEN! });
+
+// Or from inline fields: get-or-create by id, write its secrets, open sessions on it.
+await client.environments.put("users/alice/web", {
+  kind: "virtual", // the default; "pod" for a container with its own volume, "none" for a vault without compute
+  network: { allowedHosts: ["pypi.org", "files.pythonhosted.org"] }, // no egress unless you list hosts
+  ownerUserId: "alice", // the owner guard: only alice's sessions may name it
+  labels: { team: "data" },
+  lifecycle: { deleteAfter: "30d" }, // deleted once unused this long
+});
+await client.environments.secrets.put("users/alice/web", "GH_TOKEN", {
+  type: "environment_secret",
+  value: process.env.ALICE_GITHUB_TOKEN!,
+  allowedHosts: ["api.github.com"],
+});
+const session = await client.createSession({ agentId: "analyst", ownerUserId: "alice", environment: "users/alice/web" });
+
+// One per session: created with the session (id `sessions/<session id>`), deleted by release().
+const { session: scratch, release } = await client.environments.forSession({
+  session: { agentId: "analyst", ownerUserId: "alice" },
+  recipe: { network: { allowedHosts: ["pypi.org"] } },
 });
+await release();
 ```
 
-The model gets `bash`, `read`, `write`, `edit`, `grep` and `glob` on a persistent `/workspace`. These tools run in the Runtime, not in your process. The Runtime decides where the sandbox runs: today an emulated shell in the Runtime process, which is not a VM boundary and takes no `image`.
+With a sandbox (kind `virtual` or `pod`), the model gets `bash`, `read`, `write`, `edit`, `grep` and `glob` on a persistent `/workspace`. These tools run in the Runtime, not in your process. A `virtual` Environment is an emulated shell in the Runtime's harness, which is not a VM boundary and takes no `image`; a `pod` runs `image` with its own volume (`storage`) once the Tenant has sandbox pods (`nylorun local sandbox enable`). Kind `none` has a vault and no sandbox, for agents that use only remote MCP servers and HTTP tools. A session that names no Environment has no sandbox and no credentials.
 
-`sandbox` takes `false` for none, `{ id }` to attach a sandbox resource (below), or an inline sandbox as above; omit it for the Tenant's default. `{ session }`, sharing another session's sandbox, still works and is deprecated. The Runtime checks it against the Tenant's limits (`GET`/`PUT /v1/tenant/sandbox`: a network ceiling, a resource maximum, the idle timeout) and answers `400` with every problem it finds. A caller acting for a user (`app.as(...)`) can't define one inline; it gets the Tenant's default or `false`. Private networks, loopback, the host and cloud metadata endpoints are always blocked.
+An Environment never changes what it runs (protocol 14, its view's `manifest`): a `put` on an existing one may change its `labels` and owner guard, fields that match are accepted (so get-or-create stays one call), and anything else is `409 environment_immutable`. A save of a new manifest version changes no Environment: make a new one, which can start from the old one's disk (`from`). The Runtime checks what an Environment runs against the Tenant's limits (`GET`/`PUT /v1/tenant/sandbox`: a network ceiling, a resource maximum, the idle timeout) and answers `400` with every problem it finds. `lifecycle.idle` stops a pod after that long without a turn (at most the Tenant's); `lifecycle.deleteAfter` deletes the Environment, its vault and its files once nothing has used it that long. Private networks, loopback, the host and cloud metadata endpoints are always blocked.
 
-A sandbox can also be a resource with its own id, which outlives the sessions attached to it (Host feature `sandboxes`). Whether it serves one session, one person or a project is your choice:
+Secrets are write-only: `client.environments.secrets.put(id, name, secret)` creates or replaces one, and `list`, `get` and `delete` never return a value. 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)). When what an Environment runs declares a secret's slot (a manifest's `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`. An agent built with `.requires({ sandbox: "pod", secrets: ["GH_TOKEN"] })` opens a session only on an Environment that has them (`409 environment_unsuitable`). `saveAgent(agent, { dryRun: true })` checks a definition and saves nothing.
+
+Sessions on one Environment 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 environment_busy`). Deleting a session only detaches it. With `ownerUserId` set, a session of another owner is `403 environment_owner_mismatch` (a caller acting for a person gets the `404` of a missing Environment), checked when it opens and at every turn start. `client.environments.list({ labels })`, `page`, `get(id)`, `events(id, { types, since, until })` (its lifecycle, and `environment.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 local sandbox ls | rm` does the same on a local Tenant. Acting for a person (`app.as(...)`), changing an Environment or its secrets needs `environments:write`. A trusted issuer's token reaches only the Environments its issuer grants (the identity file's `environments` 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).
+
+A pod's disk can start prepared: `files` copies versions of Tenant-wide artifacts in, then `setup` runs its commands, once per new disk and before its first turn (a failed command fails the pod, and the next turn start runs the setup again). Between turns, `client.environments.snapshot(id)` keeps a version of the disk, `restore(id, version)` puts one back (a pod on a new volume seeded before its next turn), `put(newId, { from: { environment: id, version: "latest" } })` starts a new Environment from it, and `versions(id)` and `deleteVersion(id, n)` manage them ([DEPLOYMENT.md](../../guides/DEPLOYMENT.md#environments)):
 
 ```ts
-// One per session: created with the session, deleted by release().
-const { session, release } = await client.sandboxes.forSession({
-  session: { agentId: "analyst", ownerUserId },
-  spec: { network: { allow: ["pypi.org"] } },
+await client.environments.put("projects/acme", {
+  kind: "pod",
+  files: [{ artifactId: repoTarball.artifactId, version: 1, path: "/workspace/app" }],
+  setup: [{ command: "npm ci", cwd: "/workspace/app", timeout: "15m" }],
 });
-// One per person or project: get-or-create by id, then attach sessions to it.
-await client.sandboxes.ensure("team-a/proj-42", { labels: { project: "acme" } });
-await client.createSession({ agentId: "analyst", ownerUserId, sandbox: { id: "team-a/proj-42" } });
+const { version } = await client.environments.snapshot("projects/acme");
+await client.environments.put("projects/acme-try", { kind: "pod", from: { environment: "projects/acme", version } });
 ```
 
-Sessions attached to one sandbox share its `/workspace`, and one turn runs in it at a time: a second session's turn is refused with `409 sandbox_busy` until the first ends. Deleting a session only detaches it. A spec is fixed once the sandbox exists; `labels` can change. `client.sandboxes.list({ labels })`, `get(id)` and `delete(id)` manage them, and `npx nylorun sandbox ls | rm` does the same on a local Tenant. A trusted issuer's token reaches only the sandboxes its issuer grants (the identity file's `sandboxes` templates, exact ids or prefixes ending in `/*`), checked at every turn start; creating and deleting through one needs `sandboxes:write`. The Tenant holds at most `limits.sandboxes` of them (`PUT /v1/tenant/sandbox`, default 100).
-
 Add an agent with `.subagents()` to let the model delegate to it:
 
 ```ts
@@ -243,9 +324,9 @@ session like any agent: put it in `export const agents`, `saveAgent(flowAgent)`,
 (`kind: "workflow"`, `workflowSchemaVersion: 3`) that embeds the agents it runs, so one
 document and one manifest hash cover the whole flow; its agents are not listed on their own.
 
-A flow runs no code of yours: the first stage gets the flow's input, and every later stage
-gets the previous stage's output. So each agent returns, through its `.output()` schema,
-what the next stage needs.
+A flow passes data between its stages itself: the first stage gets the flow's input, and
+every later stage gets the previous stage's output. So each agent returns, through its
+`.output()` schema, what the next stage needs.
 
 ```ts
 import { Agent, VerdictSchema, http } from "@nylorun/agents";
@@ -284,28 +365,9 @@ export const shipFeature = Agent({ id: "ship-feature" })
 export const agents = [shipFeature];
 ```
 
-A flow stage cannot take `approval` yet (`flow.approval-unsupported`). To have a person
-approve opening the PR, give the HTTP tool to an agent as the last stage instead: that
-agent's turn pauses until the call is approved, and the flow session's `pending()` lists
-the wait:
-
-```ts
-const prOpener = Agent({ id: "pr-opener" })
-  .instructions("Open one pull request with open_pr from the summaries you are given.")
-  .tools(
-    http({
-      name: "open_pr",
-      description: "Open a pull request with the given summaries.",
-      input: z.object({ summaries: z.array(z.string()) }),
-      url: "https://ci.example.com/pull-requests",
-      credential: "github",
-      approval: "always",
-    }),
-  );
-
-// …
-  .pipe(prWriter, prOpener);
-```
+The Tenant's [tool policy](#tool-policy) decides a flow's HTTP stages as it decides an
+agent's HTTP tool calls: an `ask` rule on `open_pr` pauses the flow's turn until a person
+approves the call, and the flow session's `pending()` lists the wait.
 
 | Stage | Role |
 | --- | --- |
@@ -329,12 +391,11 @@ body. Its input is the previous output, which must match the tool's `input` (an
 object); a mismatch the build can see, such as an agent with no `.output()` before it,
 is refused (`flow.input-mismatch`), and any other fails the stage when it runs
 (`tool.invalid-input`). The Runtime makes the request as for an agent's HTTP tool, with
-`Nylorun-Agent-Id` set to the flow agent's id and `credential` taken from the flow
-session's vaults; its answer is the next stage's input. A failure status, a timeout or
+`Nylorun-Agent-Id` set to the flow agent's id and `credential` taken from the
+vault of the flow session's Environment; its answer is the next stage's input. A failure status, a timeout or
 an answer that does not match `output` fails the stage with its code (`http.status`,
 `http.timeout`, `tool.invalid-output`, …). A Loop body that starts with an HTTP stage
-is retried with the Loop's input, not the feedback. `approval: "always"` is not
-supported on a flow stage yet (`flow.approval-unsupported`).
+is retried with the Loop's input, not the feedback.
 
 A Loop may be judged by your service instead of an agent: `http({ url, method?,
 credential?, timeoutMs? })`, with no name or input, is an HTTP verifier. The Runtime
@@ -374,21 +435,21 @@ nested flow agent's id in front of its own agents'. Control stages add nothing,
 wrapping a step in `.loop()` or moving it between cases keeps its session. An agent
 may appear once per flow; use it again under a new id with `writer.withId("final-writer")`
 (`flow.duplicate-leaf`). A code tool stage (`.pipe(tool({ run }))`) runs only in the local
-engine: the Runtime runs no code of yours, so `saveAgent` refuses a flow agent with one. Use
-an HTTP stage instead.
+engine: the Runtime runs flows from their manifests alone, so `saveAgent` refuses a flow
+agent with one. Use an HTTP stage instead.
 
-The agents in a flow share one sandbox: open the flow's session with it,
-`createSession({ …, sandbox: { … } })`, and every agent in the flow uses it. Share it
-with other sessions by opening them all on one sandbox resource
-(`sandbox: { id }`, see `client.sandboxes`), and call
+The agents in a flow share one Environment: open the flow's session on it,
+`createSession({ …, environment: id })`, and every linked session in the flow
+inherits it; turns within one flow do not block each other. Other sessions share
+it by naming the same id (see `client.environments`). Call the sandbox
 built-ins via `session.sandbox` (application).
 Observe with `session.observe({ follow: true })` to merge linked agent streams;
 `pending()` lists waits across the tree. Studio renders the manifest tree and
 live node status. Source examples:
 `examples/agents/{chain,switch,parallel,map,loop,ship-feature}/` (outside the
 default release registry). Host contract:
-[HOST_CONTRACT.md](../harness/HOST_CONTRACT.md). Vocabulary (turn loop vs
-workflow Loop): [harness/src/CONTEXT.md](../harness/src/CONTEXT.md).
+[HOST_CONTRACT.md](../../runtime/harness/HOST_CONTRACT.md). Vocabulary (turn loop vs
+workflow Loop): [runtime/harness/src/CONTEXT.md](../../runtime/harness/src/CONTEXT.md).
 
 Use `session.observe({ cursor, signal })` for resumable canonical events, `session.inspect()` for waiting/uncertain state, and `approve`, `respond`, or `cancel` with an explicit stable idempotency key. Retry the same semantic command with the same key. `ownerUserId` must come from trusted server authentication. Application credentials are not browser credentials; browser applications need an authorized backend. Definition authoring is browser-bundleable.
 
@@ -400,8 +461,8 @@ the Tenant.
 
 The Runtime makes a lost HTTP tool call `uncertain` instead of repeating its external effect.
 In the local engine (`@nylorun/harness/run`), `tool({ run })` tools receive state, info,
-identity, resume, signal, approval/response helpers and memoized `step`. Arbitrary middleware
-closures are rejected for durable definitions. Agent definitions have no `.run()`; explicit
+identity, resume, signal, approval/response helpers and memoized `step`. Agent definitions
+have no `.run()`; explicit
 local execution is available through `@nylorun/harness/run`.
 
 ## AG-UI
@@ -446,8 +507,8 @@ createServer(toNodeListener(agui)).listen(3000);
 
 `run`, `history`, `reattach` and `cancel` are also on the handler for your own
 routing. The default `client` is `createClient()`; pass `client` to use another
-one, and `session(subject, agentId)` to add the person's `vaultIds`,
-`credentialSelections` or `info`. They apply when the thread's session is
+one, and `session(subject, agentId)` to add the person's `environment` (their
+Environment's id: its sandbox and its vault's credentials) or `info`. They apply when the thread's session is
 created, on its first run; later runs keep them. Whatever the browser sends in
 `forwardedProps.nylorun` is replaced.
 
@@ -471,7 +532,7 @@ created, on its first run; later runs keep them. Whatever the browser sends in
   package itself: the Runtime does the protocol work.
 
 A complete web backend with a test is in
-[examples/src/ag-ui](../examples/README.md#an-agent-in-your-web-app-ag-ui).
+[examples/src/ag-ui](../../examples/README.md#an-agent-in-your-web-app-ag-ui).
 
 Limitations: assistant text arrives once per model step (no token streaming);
 no reasoning, state, activity or subagent events, and an agent used as a tool
@@ -537,7 +598,7 @@ What the Runtime answers (Host feature `a2a-endpoint`):
   (`UnsupportedOperationError`; the card says `streaming: false`), push
   notifications, the extended card, and approvals. An agent that pauses for an
   approval shows `INPUT_REQUIRED`, refuses a reply, and can be canceled, so do
-  not publish agents with approval-gated tools yet.
+  not publish agents whose tools the Tenant's tool policy asks about yet.
 - The handler calls the Runtime as the partner's subject with the scope
   `sessions:own` only, so one partner never reaches another's tasks. It sends
   no header the partner chose except `A2A-Version` and `A2A-Extensions`. Without
@@ -571,6 +632,29 @@ refuse a larger upload with `413 limit_exceeded`, and nothing is stored. Acting
 a person (`as()`, or a trusted issuer's token), a client reaches only the artifacts of that
 person's sessions, and an upload names one of them.
 
+Hosts advertising `artifact-reads` also support bounded metadata pages, newest
+first. `artifacts.page()` defaults to 50 rows (1–200), checks feature discovery,
+and returns `{ artifacts, nextCursor }`. Pass the same filters on every page:
+
+```ts
+const filters = { kind: "file" as const, labels: { team: "design" } };
+let cursor: string | undefined;
+do {
+  const page = await client.artifacts.page({ ...filters, cursor });
+  for (const artifact of page.artifacts) console.log(artifact.name, artifact.latestVersion);
+  cursor = page.nextCursor ?? undefined;
+} while (cursor);
+```
+
+Omit `sessionId` for all reachable artifacts, including Tenant-owned artifacts
+when using an application key as itself. With `sessionId`, only that session's
+artifacts are included; acting for a person also applies ownership and agent
+grants on every page. Every label must match exactly. Pages omit version histories
+and bytes: use `get()` and the existing version/download methods for those.
+Cursors bind to the Tenant and filters. Pages are independent reads; refresh from
+the beginning for newer artifacts. The existing unbounded `list()` keeps its
+oldest-first behavior and does not require `artifact-reads`.
+
 ### Outputs: folder artifacts
 
 At the end of each turn, the Runtime exports the files the agent wrote into
@@ -601,7 +685,7 @@ keeps its application key to itself and names the person on each call:
 ```ts
 import { createClient } from "@nylorun/agents";
 
-const app = createClient(); // the application key, on the server only
+const app = await createClient(); // the application key, on the server only
 
 // Per request, after your own sign-in:
 const person = app.as(`app:${user.id}`, { scopes: ["sessions:own"] });
@@ -621,14 +705,15 @@ compatibility check, so calling `as()` per request is cheap.
 | `sessions:own` | The person's own sessions: create, list, read, stream, message, approve, respond, cancel; and their artifacts |
 | `agents:read` | Listing the Tenant's agents |
 | `agents:write` | Saving agents; listing agents |
+| `environments:write` | Creating, changing, stopping, resetting and deleting Environments, and writing their secrets (reading them takes `sessions:own` or this) |
 
 No scope reaches the sandbox tool routes; call them without `as()`. `tenant:settings` is retired (protocol 8): it grants
-nothing, and no subject reaches the Management API (`/v1/tenant/*`). Vaults are
-the installation's, created through the Management API with a management key
-(`admin.vaults.create({ scope: "installation", … })` in
-[`@nylorun/admin`](../admin/README.md)); a session attaches them with
-`vaultIds`, and a person's own keys go in their user vault
-([DEPLOYMENT.md](../DEPLOYMENT.md#credentials)). A subject is 1–200 visible ASCII
+nothing, and no subject reaches the Management API (`/v1/tenant/*`).
+`sandboxes:write` (protocol 10) is refused with a message naming
+`environments:write`. Credentials live in Environments: the server writes a
+person's own keys into their Environment (with `ownerUserId` set to them) and
+names it when it opens their sessions
+([DEPLOYMENT.md](../../guides/DEPLOYMENT.md#credentials)). A subject is 1–200 visible ASCII
 characters (spaces only inside) and `host` is reserved. Your server must drop
 any `Nylorun-*` header its own clients send, and only an application key can act
 for a subject.
@@ -638,14 +723,14 @@ The Tenant's signing keys sign capability links and run tokens.
 needed). Listing, rotating
 and revoking them is management: `admin.signingKeys.list()`, `.rotate()`
 (`{ force: true }` for incidents) and `.revoke(kid)` in `@nylorun/admin`, or
-`nylo access signing-keys …` from the terminal.
+`nylorun tenant signing-keys …` from the terminal.
 
 ## In the browser
 
 A web page or an app calls the Runtime directly with the JWT your identity
 provider gave the person: list the provider in the Runtime's identity file
-([Trusted issuers](../DEPLOYMENT.md#trusted-issuers)), and the Runtime takes the
-token's subject, scopes, agents and sandbox grants from it. Nylorun mints no
+([Trusted issuers](../../guides/DEPLOYMENT.md#trusted-issuers)), and the Runtime takes the
+token's subject, scopes, agents and Environment grants from it. Nylorun mints no
 token and ships no browser client: use your provider's SDK for sign-in and send
 the token as `Authorization: Bearer <token>` with `Nylorun-Protocol`, through a
 reverse proxy that answers CORS (the Runtime sends no CORS headers). An expired
@@ -653,7 +738,7 @@ token answers `401` with `code: "token_expired"`; `GET /v1/me` shows what a toke
 renders to. For a chat UI, give `@ag-ui/client`'s `HttpAgent` a `fetch` that adds
 those headers.
 
-The SDK depends only on core within the Nylorun packages; installing it does not install harness or any AG-UI or A2A package. Use `/define`, `/client`, `/ag-ui` or `/a2a` for focused imports, or the root for convenience. Studio uses `/client`. See [the adopted host contract](../harness/HOST_CONTRACT.md).
+The SDK depends only on core within the Nylorun packages; installing it does not install harness or any AG-UI or A2A package. Use `/define`, `/client`, `/ag-ui` or `/a2a` for focused imports, or the root for convenience. Studio uses `/client`. See [the adopted host contract](../../runtime/harness/HOST_CONTRACT.md).
 
 ## Embedding Studio (desktop apps)
 

package/dist/ag-ui/handler.d.ts

@@ -11,12 +11,12 @@
 import { type SubjectScope } from "@nylorun/core/contracts";
 import type { BuiltWorkflow } from "@nylorun/core/define";
 import { type AgentSource, type AgentsClient } from "../client.js";
-/** Per-session parameters the host may add, such as the person's vault for MCP servers. */
+/** Per-session parameters the host may add, such as the person's Environment. */
 export interface AgUiSessionOptions {
     /** Set when the thread's session is created, on its first run; later runs keep them. */
     info?: Record<string, unknown>;
-    vaultIds?: readonly string[];
-    credentialSelections?: Parameters<AgentsClient["createSession"]>[0]["credentialSelections"];
+    /** The Environment the thread's session runs in: its sandbox and its vault's credentials. */
+    environment?: string;
 }
 export interface AgUiHandlerOptions {
     /** Agents this endpoint may run: built agents, workflows or their ids. Nothing else is reachable. */
@@ -29,7 +29,7 @@ export interface AgUiHandlerOptions {
     client?: AgentsClient | Promise<AgentsClient>;
     /** What each subject may do through this endpoint. Default `["sessions:own"]`. */
     scopes?: readonly SubjectScope[];
-    /** Optional per-session parameters, e.g. the person's vault for connected accounts. */
+    /** Optional per-session parameters, e.g. the person's Environment with their keys. */
     session?(subject: string, agentId: string): AgUiSessionOptions | Promise<AgUiSessionOptions>;
 }
 export interface AgUiHandler {

package/dist/artifacts.d.ts

@@ -11,7 +11,7 @@
  *
  * Acting for a person (`client.as`, or a trusted issuer's token), only the artifacts of their own sessions.
  */
-import type { ArtifactDiff, ArtifactLink, ArtifactTree, ArtifactView, DeleteArtifactResponse, UploadArtifactResponse } from "@nylorun/core/contracts";
+import { type ArtifactKind, type ArtifactPage, type ArtifactDiff, type ArtifactLink, type ArtifactTree, type ArtifactView, type DeleteArtifactResponse, type UploadArtifactResponse } from "@nylorun/core/contracts";
 import { type Transport } from "./http.js";
 /** What an upload sends: bytes, a `Blob` or `File`, text, or a stream of bytes. */
 export type ArtifactBody = Uint8Array | ArrayBuffer | Blob | string | ReadableStream<Uint8Array>;
@@ -25,6 +25,17 @@ export interface UploadArtifactOptions {
     readonly labels?: Readonly<Record<string, string>>;
     readonly signal?: AbortSignal;
 }
+export interface ArtifactPageOptions {
+    /** Only this session's artifacts; excludes Tenant-owned artifacts. */
+    readonly sessionId?: string;
+    readonly kind?: ArtifactKind;
+    /** Every label must match exactly. */
+    readonly labels?: Readonly<Record<string, string>>;
+    /** Default 50, from 1 to 200. */
+    readonly limit?: number;
+    readonly cursor?: string;
+    readonly signal?: AbortSignal;
+}
 /** A capability link, with the absolute URL to open on this Runtime. */
 export type ArtifactLinkWithUrl = ArtifactLink & {
     readonly url: string;
@@ -48,6 +59,8 @@ export declare class ArtifactsClient {
         sessionId?: string;
         signal?: AbortSignal;
     }): Promise<ArtifactView[]>;
+    /** Newest first, with metadata only (Host feature `artifact-reads`). */
+    page(options?: ArtifactPageOptions): Promise<ArtifactPage>;
     /** The artifact, with every version. */
     get(artifactId: string, options?: {
         signal?: AbortSignal;

package/dist/artifacts.js

@@ -1,3 +1,17 @@
+/**
+ * Artifacts (protocol 6): `client.artifacts`. A file is uploaded in one streamed request and
+ * kept as an artifact with numbered versions; a session's artifacts appear in its history as
+ * `artifact.*` events. Download through the Runtime (with Range), or mint a capability link: a
+ * 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
+ * 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.
+ *
+ * Acting for a person (`client.as`, or a trusted issuer's token), only the artifacts of their own sessions.
+ */
+import { ArtifactPageSchema, } from "@nylorun/core/contracts";
 import { segment } from "./http.js";
 function contentTypeOf(body, declared) {
     if (declared)
@@ -46,6 +60,20 @@ export class ArtifactsClient {
         const reply = await this.transport.json(`/v1/artifacts${query}`, "GET", undefined, options.signal);
         return reply.artifacts;
     }
+    /** Newest first, with metadata only (Host feature `artifact-reads`). */
+    async page(options = {}) {
+        await this.transport.requireFeature("artifact-reads", options.signal);
+        const query = new URLSearchParams({ limit: String(options.limit ?? 50) });
+        if (options.cursor !== undefined)
+            query.set("cursor", options.cursor);
+        if (options.sessionId !== undefined)
+            query.set("sessionId", options.sessionId);
+        if (options.kind !== undefined)
+            query.set("kind", options.kind);
+        for (const [key, value] of Object.entries(options.labels ?? {}))
+            query.append("label", `${key}=${value}`);
+        return ArtifactPageSchema.parse(await this.transport.json(`/v1/artifacts?${query}`, "GET", undefined, options.signal));
+    }
     /** The artifact, with every version. */
     get(artifactId, options = {}) {
         return this.transport.json(`/v1/artifacts/${segment(artifactId)}`, "GET", undefined, options.signal);