@nylorun/agents 0.14.0-beta → 0.16.1-beta

package/README.md

@@ -1,49 +1,85 @@
 # @nylorun/agents
 
-Tenant API client package: definition authoring, a session client, and the
-Action endpoint that runs your tools (`createActionHandler`). Depends only on `@nylorun/core` among Nylorun
+Runtime API client package: definition authoring and a session client. The Tenant's
+settings, models, vaults, 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).
 
-## Application entry (preferred): an Action endpoint
+## Application entry: save your agents
 
 ```ts
 // src/main.ts
-import { createServer } from "node:http";
-import { createActionHandler } from "@nylorun/agents";
+import { createClient } from "@nylorun/agents";
 import { agents } from "../agents/index.js";
 
-const url = process.env.NYLORUN_ACTIONS_URL ?? "http://localhost:3001/nylorun/actions";
-const actions = createActionHandler({ agents, url });
-createServer(actions.node).listen(3001); // or actions.fetch in Hono, Next.js, Workers, Bun
-await actions.register({ url });
+const client = createClient();
+for (const agent of agents) await client.saveAgent(agent);
 ```
 
-The Runtime delivers each tool call, hook and workflow function of these agents
-to `url`, signed with a short-lived **delivery token** that the handler checks
-(Tenant, URL, Action, generation and body) before any code runs. `register`
-saves the definitions, registers the URL and pings it through the Runtime. A
-process that only serves Actions needs no key: pass `runtime: { url }` and it
-reads the Tenant's public keys. Mark a long tool
-`tool({ …, background: true })`: the handler answers at once, heartbeats and
-posts the result. `npx @nylorun/cli endpoints` shows each endpoint and how its
-deliveries are doing.
-
-The URL must be one the Runtime can reach: `localhost` on a local Tenant
-(its Runtime runs in Docker and maps `localhost` to this machine), a public URL
-in production, or a tunnel (ngrok, Cloudflare Tunnel) for a remote Runtime.
-
-`connectAgents` and executors were removed in protocol 3: mount
-`createActionHandler` instead (see [MIGRATION.md](../MIGRATION.md)). The handler
-finds the Runtime through the two `NYLORUN_*` variables or the Project link
-that `npx nylorun start` writes; with neither, `register` fails with
-`connection_missing` and names those steps. See [MIGRATION.md](../MIGRATION.md#runtime-clients-and-admin-api-breaking-beta)
-for upgrading from `nylorun serve`.
+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
+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
+runs in the local engine (`@nylorun/harness/run`). `implementationVersion` defaults to
+`NYLORUN_IMPLEMENTATION_VERSION`, else `dev`.
+
+`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).
+
+## HTTP tools
+
+A tool can be one HTTP request to your service, made by the Runtime itself: no code of
+yours runs during the session.
+
+```ts
+import { Agent, http } from "@nylorun/agents";
+import { z } from "zod";
+
+const refundOrder = http({
+  name: "refund_order",
+  description: "Refund an order.",
+  input: z.object({ orderId: z.string(), amount: z.number() }), // or a JSON Schema object
+  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
+  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
+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
+`Idempotency-Key` that is the same when the Runtime re-sends the call after a
+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 operator's credential resolver is asked; without one the call fails before
+it is sent. `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
+only on the Runtime (a local `run()` reports `http.runtime-only`).
 
 ## Connection resolution
 
-`resolveConnection` / `createClient()` / `createActionHandler({ agents })`:
+`resolveConnection` / `createClient()`:
 
 1. Explicit `{ url, key }`
 2. Environment — if `NYLORUN_RUNTIME_URL` or `NYLORUN_SERVER_KEY` is set, both
@@ -59,22 +95,20 @@ Runtime serves one Tenant, so nothing names it: the `tenant` option is gone
 is ignored.
 
 ```ts
-import { Agent, createActionHandler, createClient, tool } from "@nylorun/agents";
+import { Agent, createClient, http } from "@nylorun/agents";
 import { z } from "zod";
 
 const assistant = Agent({ id: "assistant", name: "Assistant" })
   .instructions("Use the available tools.")
   .tools(
-    tool({
+    http({
       name: "lookup",
       input: z.object({ id: z.string() }),
-      async run({ id }, ctx) {
-        return { id, owner: ctx.info };
-      },
+      url: "https://items.example.com/lookup",
     }),
   );
 
-// Explicit Tenant API client (options or env / link via createClient()).
+// Explicit Runtime API client (options or env / link via createClient()).
 const client = createClient({
   url: process.env.NYLORUN_RUNTIME_URL,
   key: process.env.NYLORUN_SERVER_KEY,
@@ -86,20 +120,6 @@ const session = await client.createSession({
 });
 await session.input("Look up item 123", { idempotencyKey: requestId });
 const history = await session.history();
-
-// A process that only serves Actions holds no key: it reads the Tenant's public keys.
-const actions = createActionHandler({
-  agents: [assistant],
-  implementationVersion: "app-1",
-  runtime: { url: process.env.NYLORUN_RUNTIME_URL! },
-  url: "https://app.example.com/nylorun/actions",
-  onError: console.error,
-});
-app.post("/nylorun/actions", actions.node);
-// A deploy step with the application key registers the URL once:
-await createActionHandler({ agents: [assistant], client }).register({
-  url: "https://app.example.com/nylorun/actions",
-});
 ```
 
 ```sh
@@ -107,7 +127,7 @@ eval "$(npx @nylorun/cli env)"
 # → NYLORUN_RUNTIME_URL, NYLORUN_SERVER_KEY
 ```
 
-Every request sets `Nylorun-Protocol` (6) and no `Nylorun-Tenant`: the Runtime
+Every request sets `Nylorun-Protocol` (8) 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
@@ -125,7 +145,9 @@ 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). Supporting files (for example `references/`) are available through `read_skill_resource` after `load_skill`. The helper sets both the manifest skill catalog and the on-disk skill records so you do not duplicate content.
+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.
 
 Declare MCP servers with `.mcp(...)` (same map shape as agent-plugins `mcpServers`):
 
@@ -139,7 +161,7 @@ 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. Transports follow [Agent Plugins MCP servers](https://agent-plugins.org/plugin-authors/mcp-servers): `stdio`, `streamable-http`, and `sse`. Attach an Agent Plugin package with `.plugin(path)`.
+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.
 
 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:
 
@@ -154,7 +176,7 @@ const session = await client.createSession({
 });
 ```
 
-The model gets `bash`, `read`, `write`, `edit`, `grep` and `glob` on a persistent `/workspace`. These tools run in the Runtime, not in your process, so sandbox-only agents need no Action endpoint. 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`.
+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`.
 
 `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.
 
@@ -196,91 +218,161 @@ const support = Agent({ id: "support" })
   .subagents(researcher);
 ```
 
-The tool is named after the agent's `id` and takes `{ task: string }`; the agent's `description` (required) is what the parent's model reads to decide when to delegate. The child starts with a fresh context: it sees its own instructions and the task, nothing of the parent's conversation, and only its final text (or `outputSchema` result) comes back. It keeps its own tools, hooks, skills and MCP servers, served by the Action endpoint you already mount for the parent (`createActionHandler({ agents: [support] })` serves both), shares the session's sandbox, and starts with empty `ctx.state`. Tools can read `ctx.agent` (`{ id, path, delegationId }`). Several delegation calls in one model response run in parallel. An empty answer, a failure (with the child's last text marked as evidence) or a cancelled child reaches the parent's model as a failed tool result, never as success. The Runtime emits `delegation.started` and `delegation.completed`; `session.history({ agent })` filters by `delegationId` (one child invocation) or by path such as `support/researcher` (every concurrent child that shares that path).
+The tool is named after the agent's `id` and takes `{ task: string }`; the agent's `description` (required) is what the parent's model reads to decide when to delegate. The child starts with a fresh context: it sees its own instructions and the task, nothing of the parent's conversation, and only its final text (or `outputSchema` result) comes back. It keeps its own tools, skills and MCP servers, saved with the parent, and shares the session's sandbox. Several delegation calls in one model response run in parallel. An empty answer, a failure (with the child's last text marked as evidence) or a cancelled child reaches the parent's model as a failed tool result, never as success. The Runtime emits `delegation.started` and `delegation.completed`; `session.history({ agent })` filters by `delegationId` (one child invocation) or by path such as `support/researcher` (every concurrent child that shares that path).
 
-A flow agent can be a subagent too: `.subagents(researchFlow)` with a `description` like any other. Its manifest is inlined in the parent's, so it is saved with the parent and served by the parent's Action endpoint. When the model calls it, the flow runs on the Runtime in its own linked session (a fresh one per call, linked from the parent's with a `node.agent` event at `support/<flow id>`), its agents in theirs, and the flow's output comes back as the tool result; a failed flow is a failed tool result. Cancelling the parent cancels the flow. Flow agents as subagents run on the Runtime only, not in a local `run()`. An approval asked for inside the flow waits on the flow's own session.
+A flow agent can be a subagent too: `.subagents(researchFlow)` with a `description` like any other. Its manifest is inlined in the parent's, so it is saved with the parent. When the model calls it, the flow runs on the Runtime in its own linked session (a fresh one per call, linked from the parent's with a `node.agent` event at `support/<flow id>`), its agents in theirs, and the flow's output comes back as the tool result; a failed flow is a failed tool result. Cancelling the parent cancels the flow. Flow agents as subagents run on the Runtime only, not in a local `run()`. An approval asked for inside the flow waits on the flow's own session.
 
-Delegate when the parent should keep the answer. When a specialist should own the rest of the conversation, switch capabilities with a `.beforeModel()` patch instead. This version is one level deep and non-interactive: a delegated agent cannot use agents as tools, its tools cannot declare `approval` (keep those on the parent), and `ctx.ask`, `ctx.approve`, `ctx.sleep` or `ctx.waitFor` inside it fail with `delegation.interaction-unsupported`. Delegation is not an approval boundary; approvals live on tools.
+Delegate when the parent should keep the answer. When a specialist should own the rest of the conversation, send the next message with a turn manifest that has the specialist's instructions instead. This version is one level deep and non-interactive: a delegated agent cannot use agents as tools, and its tools cannot declare `approval` (keep those on the parent). In the local engine (`@nylorun/harness/run`), a delegated agent's `tool({ run })` tools start with empty `ctx.state`, can read `ctx.agent` (`{ id, path, delegationId }`), and fail with `delegation.interaction-unsupported` on `ctx.ask`, `ctx.approve`, `ctx.sleep` or `ctx.waitFor`. Delegation is not an approval boundary; approvals live on tools.
 
 ## Flow agents
 
-An agent's body is either a ReAct loop (the model decides) or a flow (your code
-decides). A flow agent is built from stages, each shaped `.stage(whatRuns, { how })`,
-and is registered, saved and opened as a session like any agent: put it in
-`export const agents`, `saveAgent(flowAgent)`, then `createSession({ agentId })`
-and `session.input(value)`. `input` sends string values as `content` and other JSON
-as `data`. On the wire a flow agent is a workflow manifest v2 (`kind: "workflow"`,
-`workflowSchemaVersion: 2`) 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.
+An agent's body is either a ReAct loop (the model decides) or a flow (its manifest
+decides). A flow agent is built from stages and is registered, saved and opened as a
+session like any agent: put it in `export const agents`, `saveAgent(flowAgent)`, then
+`createSession({ agentId })` and `session.input(value)`. `input` sends string values as
+`content` and other JSON as `data`. On the wire a flow agent is a workflow manifest v3
+(`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.
 
 ```ts
-import { Agent, tool } from "@nylorun/agents";
+import { Agent, VerdictSchema, http } from "@nylorun/agents";
 import { z } from "zod";
 
 const planner = Agent({ id: "planner" })
-  .instructions("Return { tasks: string[] }.")
-  .output(z.object({ tasks: z.array(z.string()) }));
+  .instructions("Return { items: string[] }, one task each.")
+  .output(z.object({ items: z.array(z.string()) }));
 
 const coder = Agent({ id: "coder" })
   .instructions("Implement one task. Return { summary }.")
   .output(z.object({ summary: z.string() }));
 
-const openPr = tool({
-  name: "open-pr",
+const reviewer = Agent({ id: "reviewer" })
+  .instructions("Pass the response when its summary says what changed.")
+  .output(VerdictSchema);
+
+const prWriter = Agent({ id: "pr-writer" })
+  .instructions("Return the summaries you are given as { summaries }.")
+  .output(z.object({ summaries: z.array(z.string()) }));
+
+// Your service serves POST /pull-requests and answers { url }.
+const openPr = http({
+  name: "open_pr",
   input: z.object({ summaries: z.array(z.string()) }),
-  async run({ summaries }, ctx) {
-    if (!(await ctx.approve("Open the PR?"))) throw new Error("Rejected");
-    return { opened: true, count: summaries.length };
-  },
+  output: z.object({ url: z.string() }),
+  url: "https://ci.example.com/pull-requests",
+  credential: "github",
 });
 
 export const shipFeature = Agent({ id: "ship-feature" })
-  .step(planner)
-  .map(
-    Agent({ id: "code" }).loop(coder, {
-      verify: ({ output }) => (output.summary ? { pass: true } : { pass: false, feedback: "Say what you changed." }),
-      max: 2,
-    }),
-    { id: "implement", input: ({ input }) => input.tasks },
-  )
-  .step(openPr, { input: ({ input }) => ({ summaries: input.map((item) => item.summary) }) });
+  .pipe(planner)
+  .map(Agent({ id: "code" }).loop(coder, { verify: reviewer, max: 2 }), { id: "implement" })
+  .pipe(prWriter, openPr);
 
 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);
+```
+
 | Stage | Role |
 | --- | --- |
-| **`.step(x, { id?, input? })`** | Run one agent, tool or `flow()`; its output is the next stage's input |
-| **`.switch({ ...cases, default? }, { on })`** | `on({ input })` returns a case name; exactly that case runs |
+| **`.pipe(a, b, …)`** | Run agents, tools or `flow()`s in order; each one's output is the next one's input |
+| **`.switch({ ...cases, default? })`** | Run the case the previous output names: a string, or its `route` field |
 | **`.parallel(branches)`** | Fixed named branches at once, same input; output is an object |
-| **`.map(each)`** | Run `each` once per item of the input, which must be an array; output is an array |
-| **`.loop(body, { verify, max?, decide? })`** | Run, verify, run again with the feedback until it passes; needs `max` or `decide` |
+| **`.map(each)`** | Run `each` once per item of the previous output: an array, or its `items`; output is an array |
+| **`.loop(body, { verify, max })`** | Run `body`, ask `verify` (an agent, or `http({ url })`), run again with its feedback until it passes, at most `max` times |
+
+Every stage takes `{ id }` to name it (`.loop` takes it beside `verify` and `max`).
+`flow()` builds a sequence with no id for a case, branch, map item or loop body that
+is more than one step. A verifier agent gets `{ task, response, iteration }` and returns
+a verdict, `{ pass, feedback? }` (`VerdictSchema`), with feedback when it fails; the
+verdict is recorded as a `loop.verified` event. An agent after the first stage also
+sees the flow's input, as the original request, before its own input. Types flow from
+each stage's `.output()` schema to the flow agent's output. `.step(x, { id })` is a
+deprecated alias for `.pipe(x.withId(id))`.
+
+An [HTTP tool](#http-tools) is a stage too: in `.pipe()`, a case, a Map item or a Loop
+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
+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`).
+
+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
+sends `{ input, output, iteration }` (the Loop's input, the attempt's output, its
+number) and reads a verdict, `{ pass, feedback? }`, from the answer; anything else, or a
+failed request, fails the Loop (`loop.verify-failed`). Its verdicts are recorded as
+`loop.verified`, as an agent's are.
 
-Every function receives one object: `{ input, results, flowInput }`. `input` is
-what the stage received, `results` holds earlier steps' outputs by step id, and
-`flowInput` is the agent's own input. The `input` option computes a stage's input;
-the `id` option names a step. `flow()` builds a sequence with no id for a case,
-branch, map item or loop body that is more than one step. Types flow from each
-step's `.output()` schema to the next stage's `input`.
+```ts
+import { Agent, http } from "@nylorun/agents";
+import { z } from "zod";
+
+const order = Agent({ id: "order" })
+  .instructions("Name the order to refund as { orderId }.")
+  .output(z.object({ orderId: z.string() }));
+
+const refund = http({
+  name: "refund",
+  input: z.object({ orderId: z.string() }),
+  output: z.object({ refundId: z.string() }),
+  url: "https://billing.example.com/refunds",
+  credential: "billing",
+});
+
+const fixer = Agent({ id: "fixer" }).instructions("Fix the failing test.");
+
+export const refunds = Agent({ id: "refunds" }).pipe(order, refund);
+export const fixTests = Agent({ id: "fix-tests" }).loop(fixer, {
+  verify: http({ url: "https://ci.example.com/verify", credential: "ci" }),
+  max: 3,
+});
+```
 
 Agents inside a flow keep their own sessions, linked from the flow's session and
-named by the agent: a step's id (the agent's id, or `{ id }`), with `[i]` for each
-Map item and a nested flow agent's id in front of its own agents'. Control stages
-add nothing, so 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
-`.step(writer, { id: "final-writer" })` or `writer.withId("…")`
-(`flow.duplicate-leaf`). Functions are bound under stage keys: a stage's `id`, or
-its position such as `@1.default.1`, plus `:input`, `:on`, `:verify` or `:decide`.
-Name the stages you may reorder.
-
-`Chain`, `Switch`, `Parallel`, `Map` and `Loop` still build workflow manifest v1
-directly and run as before; a flow agent can't be a child of them.
+named by the agent: its id (or `.withId("…")`), with `[i]` for each Map item and a
+nested flow agent's id in front of its own agents'. Control stages add nothing, so
+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.
 
 The agents in a flow share one sandbox: open the flow's session with it,
-`createSession({ …, sandbox: { … } })`, and every agent, tool step and `verify` in the
-flow uses it. Share it with other sessions by opening them all on one sandbox resource
+`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
-built-ins via `session.sandbox` (application) or `ctx.sandbox` (a tool).
+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:
@@ -293,15 +385,15 @@ Use `session.observe({ cursor, signal })` for resumable canonical events, `sessi
 
 Connection defaults follow `resolveConnection` (options → environment → Project
 link). Implementation version defaults from `NYLORUN_IMPLEMENTATION_VERSION`,
-then `dev`. `register` saves the definitions and registers one endpoint per
-served agent with the application key; serving deliveries needs no key.
-Agents do not hash the manifest, and an in-flight action is still delivered after
-the registered digest changes. Model selection and model credentials belong to
+then `dev`. Agents do not hash the manifest; the Runtime pins the digest of the
+definition a session opens with. Model selection and model credentials belong to
 the Tenant.
 
-After registration, the Runtime POSTs each Action to the endpoint with a delivery token signed by the Tenant's key; the handler verifies it before any code runs and answers with the outcome. A background tool answers `202`, heartbeats with the newest token and posts its result. A cancel aborts the request, which reaches the tool as `ctx.signal`; JavaScript cannot forcibly terminate a function that ignores its signal. The host makes lost in-flight deliveries uncertain instead of automatically repeating external effects.
-
-Tools receive state, info, identity, resume, signal, approval/response helpers and memoized `step`. Step outcomes survive a persisted wait result; they do not establish exactly-once external effects after an unacknowledged crash. `sleep` and `waitFor` currently return inspectable deferred outcomes; automatic timer/event wakeups remain runtime implementation work. Remote `onModelCall` convenience and progress-event transport are not supplied in this pass. Arbitrary middleware closures are rejected for durable definitions; use `before`/`after` hooks. The Action endpoint runs every capability registered at a hook point in one action. Agent definitions have no `.run()`; explicit local execution is available through `@nylorun/harness/run`.
+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
+local execution is available through `@nylorun/harness/run`.
 
 ## AG-UI
 
@@ -377,7 +469,7 @@ no reasoning, state, activity or subagent events, and an agent used as a tool
 shows only its result; frontend tools in `RunAgentInput.tools` are rejected
 (`400`); one text part per user message; earlier messages cannot be edited or
 regenerated. A browser reaches the Runtime only with a trusted issuer's token,
-never with a Tenant key.
+never with a key.
 
 ## A2A
 
@@ -495,12 +587,12 @@ completes.
 ## Acting for a person (app servers)
 
 A server that signs people in and calls the Runtime for them (an "app server")
-keeps the Tenant key to itself and names the person on each call:
+keeps its application key to itself and names the person on each call:
 
 ```ts
 import { createClient } from "@nylorun/agents";
 
-const app = createClient(); // the Tenant key, on the server only
+const app = 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"] });
@@ -519,22 +611,25 @@ 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, models and providers |
-| `tenant:settings` | The Tenant's status, model provider and sandbox settings |
-
-No scope reaches Tenant reset, config seed, Action endpoints, actions, vaults or
-the sandbox tool routes; call those without `as()`. Vaults are the
-installation's (`createVault({ scope: "installation", … })`); a person's own
-credentials come from your credential resolver
+| `agents:write` | Saving agents; listing agents |
+
+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 credentials come from your credential resolver
 ([DEPLOYMENT.md](../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.
 
-The Tenant's signing keys sign delivery tokens and capability links:
-`app.access.signingKeys.list()`, `.rotate()` (`{ force: true }` for incidents),
-`.revoke(kid)` and `app.access.jwks()`, or `nylo access signing-keys …` from the
-terminal.
+The Tenant's signing keys sign capability links and run tokens.
+`app.access.jwks()` reads the public keys (`GET /v1/access/jwks`, no key
+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.
 
 ## In the browser
 

package/dist/access.d.ts

@@ -1,34 +1,14 @@
 /**
- * The Tenant's signing keys and public keys, for app servers on the application key. The
- * Runtime signs delivery tokens (Action endpoints) and capability links with them; an Action
- * endpoint verifies delivery tokens with the public keys (`jwks`).
+ * The Tenant's public keys, which verify the tokens it signs (capability links, run tokens).
+ * Listing, rotating and revoking signing keys is the Management API's (`admin.signingKeys` in
+ * `@nylorun/admin`, protocol 8).
  */
-import type { Jwks, SigningKeyView } from "@nylorun/core/contracts";
-import { type Transport } from "./http.js";
-export declare class SigningKeysClient {
-    private readonly transport;
-    constructor(transport: Transport);
-    list(options?: {
-        signal?: AbortSignal;
-    }): Promise<SigningKeyView[]>;
-    /**
-     * standby → current → previous → revoked, and a new standby. Refused while the previous key
-     * may still verify live tokens; `force` skips that and ends those tokens.
-     */
-    rotate(options?: {
-        force?: boolean;
-        signal?: AbortSignal;
-    }): Promise<SigningKeyView[]>;
-    /** Revokes a previous or standby key; the current key must be rotated first. */
-    revoke(keyId: string, options?: {
-        signal?: AbortSignal;
-    }): Promise<SigningKeyView>;
-}
+import type { Jwks } from "@nylorun/core/contracts";
+import type { Transport } from "./http.js";
 export declare class AccessClient {
     private readonly transport;
-    readonly signingKeys: SigningKeysClient;
     constructor(transport: Transport);
-    /** The public keys that verify the Tenant's delivery tokens. */
+    /** The public keys that verify the tokens the Tenant signs. */
     jwks(options?: {
         signal?: AbortSignal;
     }): Promise<Jwks>;

package/dist/access.js

@@ -1,34 +1,9 @@
-import { id, segment } from "./http.js";
-export class SigningKeysClient {
-    transport;
-    constructor(transport) {
-        this.transport = transport;
-    }
-    async list(options = {}) {
-        const reply = await this.transport.json("/v1/access/signing-keys", "GET", undefined, options.signal);
-        return reply.keys;
-    }
-    /**
-     * standby → current → previous → revoked, and a new standby. Refused while the previous key
-     * may still verify live tokens; `force` skips that and ends those tokens.
-     */
-    async rotate(options = {}) {
-        const reply = await this.transport.json("/v1/access/signing-keys/rotate", "POST", { requestId: id(), ...(options.force ? { force: true } : {}) }, options.signal);
-        return reply.keys;
-    }
-    /** Revokes a previous or standby key; the current key must be rotated first. */
-    async revoke(keyId, options = {}) {
-        return this.transport.json(`/v1/access/signing-keys/${segment(keyId)}/revoke`, "POST", { requestId: id() }, options.signal);
-    }
-}
 export class AccessClient {
     transport;
-    signingKeys;
     constructor(transport) {
         this.transport = transport;
-        this.signingKeys = new SigningKeysClient(transport);
     }
-    /** The public keys that verify the Tenant's delivery tokens. */
+    /** The public keys that verify the tokens the Tenant signs. */
     async jwks(options = {}) {
         return this.transport.json("/v1/access/jwks", "GET", undefined, options.signal);
     }

package/dist/files.d.ts

@@ -0,0 +1,31 @@
+/**
+ * Definition files (track R2 M4): `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 definition naming a file it
+ * does not hold (`400 definition_files_missing`). `saveAgent` uploads an agent's files itself.
+ */
+import { type DefinitionFileView } from "@nylorun/core/contracts";
+import type { SkillFileSource } from "@nylorun/core/define";
+import { type Transport } from "./http.js";
+/** `sha256:<hex>` of `bytes`. */
+export declare function definitionFileHash(bytes: Uint8Array): Promise<string>;
+export declare class FilesClient {
+    private readonly transport;
+    constructor(transport: Transport);
+    /** Whether the Runtime holds the file `sha256` (`sha256:<hex>`) names. */
+    has(sha256: string, options?: {
+        signal?: AbortSignal;
+    }): Promise<boolean>;
+    /**
+     * Uploads one file, at most 10 MiB. The Runtime checks its bytes hash to `sha256` (default:
+     * their hash) and keeps a file it already holds as it is.
+     */
+    upload(bytes: Uint8Array, options?: {
+        sha256?: string;
+        signal?: AbortSignal;
+    }): Promise<DefinitionFileView>;
+    /** Uploads each of `files` the Runtime does not hold yet. */
+    ensure(files: ReadonlyMap<string, SkillFileSource>, options?: {
+        signal?: AbortSignal;
+    }): Promise<void>;
+}