@nylorun/agents 0.7.0-beta → 0.9.0-beta

package/CHANGELOG.md

@@ -1,5 +1,72 @@
 # @nylorun/agents
 
+## 0.9.0-beta
+
+### Minor Changes
+
+- e537a82: **One `Agent` builder: named methods and flow agents.** Every capability has its own method, and deterministic workflows are written on the same builder. ReAct agent manifests are unchanged: the new syntax compiles to exactly what the old syntax produced.
+
+  - ReAct agents: `.instructions()`, `.tools()`, `.subagents()`, `.mcp()` (a server's `name` defaults to its key; calls merge), `.skills()`, `.plugin()`, `.capability()`, `.sandbox()`, `.beforeTurn()`, `.beforeModel()`, `.afterModel()`, `.afterTurn()`, `.output()`. `capability({ id })` returns a builder with the same methods.
+  - Flow agents: `.step()`, `.switch({ ...cases, default }, { on })`, `.parallel()`, `.map()` (runs over its input), `.loop(body, { verify, max | decide })`, plus `.input()`, `.output()`, `.sandbox()`, `flow()` for nested sequences and `.withId()`. Functions receive `{ input, results, flowInput }`, typed from each step's output schema. A flow agent compiles to a workflow manifest (v2, see the flow-manifest-v2 changeset).
+  - Build diagnostics: `agent.mixed-body`, `flow.no-model`, `agent.single-value`, `flow.empty`, `loop.max-required`, `loop.invalid-max`, `mcp.duplicate-server`, `delegation.flow-unsupported`.
+  - `sandbox()` and `mcp()` move to `@nylorun/core/define` (still exported from `@nylorun/agents`).
+  - Deprecated, warning once each: options-form `instructions`/`tools`/`outputSchema` (`NYLORUN_DEP_AGENT_OPTIONS`), `.use(capability)` (`NYLORUN_DEP_USE`), `.before()`/`.after()` (`NYLORUN_DEP_HOOKS`), and `capability({ tools, instructions, … })` (`NYLORUN_DEP_CAPABILITY_OPTIONS`). See MIGRATION.md.
+
+- 5278b4e: **Flow agents on workflow manifest v2.** A flow agent compiles to `workflowSchemaVersion: 2` and runs on the new `flow-2` engine; v1 workflows (`Chain`, `Switch`, `Parallel`, `Map`, `Loop`) keep running on `flow-1`, so in-flight runs finish as they began.
+
+  - **Manifest (core).** Any node may carry `id` and `input`; there are no slots. `chain` and `parallel` are bare collections, a Map is `{ map: { each } }` over its input, and a Loop has `max?` and `decide?`. The header adds `name`, `description`, `metadata`, `inputSchema` and `outputSchema`, and `agents` embeds every agent the flow runs, so one manifest hash covers the whole flow. `Agent.from(json, { nodes, agents })` rebuilds a flow agent. Path and key helpers (`leafPath`, `stageKey`, `forEachFlowNode`, `embeddedAgent`, …) are exported from `@nylorun/core/define`.
+  - **Paths (harness).** Linked agent sessions are named by the agent: its id, `[i]` per Map item, and a nested flow agent's id in front. Control stages add nothing, so wrapping a step in a Loop keeps its session. Functions are bound under stage keys (`route:on`, `@1.default.1:input`) and all receive `{ input, results, flowInput }`; `flowInput` works inside nested `flow()`. A Loop without `decide` retries with the verifier's feedback up to `max` and then fails with `loop.exhausted`. Nested flow agents run inline.
+  - **Runtime.** Leaves of a v2 workflow resolve from its embedded `agents` (with the workflow's plugin roots, keyed `<agent>/<capability>`) instead of the registry. `loop.iteration` is emitted only for a Loop's own agent turns.
+  - **Agents SDK.** `saveAgent(flowAgent)` PUTs one document; application mode registers the flow's executor with its manifest hash. An executor leaves `fn`, `verify` and tool actions of a v2 flow unclaimed when they belong to another manifest hash, because stage keys can shift between deploys; it reports each skipped action once through `onError`.
+  - **Studio.** Draws v2 manifests: agents and tools at their session paths, control stages at their stage keys, nested flow agents inline, and lights a Map's agent from its item sessions.
+  - Build diagnostics: `flow.duplicate-leaf`, `flow.duplicate-id`, `flow.agent-conflict`, `flow.v1-workflow`, `loop.invalid-verify`, `workflow.flow-agent-child`. Also fixes v1 flows passing an agent step's output to the next step still wrapped in the runtime's turn marker.
+
+- 426fd27: **Flow agents as subagents.** `.subagents(flowAgent)` lets a ReAct agent delegate to a flow agent. The flow's workflow manifest v2 is inlined in the delegating tool (`ToolManifest.agent` may be a workflow manifest), so it is saved with the parent and served by the parent's executor, plugin roots included (`<flow>/<agent>/<capability>`).
+
+  - **Engine (harness).** A call to a flow subagent is one durable `agent` effect (`role: "delegate"`) between the delegation's start and settle points; the flow's output is the tool result, and a failed flow is a failed tool result. Local `run()` refuses flow subagents, which need the Runtime.
+  - **Runtime.** The effect starts a linked flow session from the parent's pinned manifest, fresh per call, and settles when the flow's turn ends. Cancelling any session now cascades to the linked sessions it started, not only a workflow's.
+  - **Core.** `delegation.flow-unsupported` now only reports a workflow built with `Chain`, `Switch`, `Parallel`, `Map` or `Loop`. New helpers: `flowDelegatesOf`, `flowDelegateManifest`, `isFlowDelegate`; `delegatesOf` lists only the ReAct agents run in-process.
+
+### Patch Changes
+
+- Pin core to the tested release.
+- Updated dependencies [e537a82]
+- Updated dependencies [5278b4e]
+- Updated dependencies [426fd27]
+- Updated dependencies [8cda500]
+  - @nylorun/core@0.8.0-beta
+
+## 0.8.0-beta
+
+### Minor Changes
+
+- a322696: **`@nylorun/agents/ag-ui`: serve agents to AG-UI clients from your own server.** `createAgUiHandler({ basePath, agents, subject })` returns a web-standard `fetch` handler (plus `run`, `history`, `reattach` and `cancel`), and `toNodeListener` adapts it to `node:http` and Express.
+
+  - One session per person, agent and thread; the AG-UI message id is the idempotency key, so a retried run replays the same turn.
+  - Approvals become AG-UI interrupts and resume through `runAgent({ resume })`.
+  - History returns a plain AG-UI `Message[]` with the ids the live run used; reattach continues a run from `Last-Event-ID`.
+  - Needs a Runtime with `transcript-events`. Adds the `@ag-ui/core` dependency (`~1.0.0`), loaded only by this subpath.
+
+  `AgentsClient.hostFeatures()` returns the Runtime's protocol features, including optional ones.
+
+- 844bff3: **Act for a person: `Nylorun-Subject` and `Nylorun-Scopes`.** An app server that holds the Tenant key can name the person each request is for, and the Runtime enforces it (optional Host feature `subject-headers`).
+
+  - `client.as(subject, { scopes })` in `@nylorun/agents` sends both headers on every call, event streams included. Scopes: `agents:read`, `agents:write`, `sessions:own`, `vaults:own`, `tenant:settings`; default `["sessions:own"]`.
+  - The Runtime limits a subject to the routes its scopes allow (`403 scope_required`) and to its own sessions and vaults: another owner's session, vault or sandbox is the same `404` as a missing one, including `PUT` on its session id (was `409`). Reset, config seed, executors, actions and the sandbox tool routes are open to no subject. Only application keys may send the headers.
+  - The AG-UI handler calls the Runtime as each person and requires `subject-headers`; new optional `scopes` option. The host's `session()` parameters can no longer replace a session's id, agent or owner.
+  - Core exports `SUBJECT_HEADER`, `SCOPES_HEADER`, `SUBJECT_SCOPES` and `parseSubjectHeaders`. Postgres Tenant schemas migrate to version 2 (an indexed session owner column).
+
+  Requests without `Nylorun-Subject` are unchanged.
+
+### Patch Changes
+
+- 42272f8: The AG-UI handler answers `400` (`invalid_request`) when the Runtime refuses what the client sent, such as a `Last-Event-ID` it cannot read, instead of `502`.
+- Pin core to the tested release.
+- Updated dependencies [a322696]
+- Updated dependencies [844bff3]
+- Updated dependencies [a322696]
+  - @nylorun/core@0.7.0-beta
+
 ## 0.7.0-beta
 
 ### Minor Changes

package/README.md

@@ -41,11 +41,9 @@ Sources never mix. Partial environment fails with `connection_missing`.
 import { Agent, createClient, connectAgents, tool } from "@nylorun/agents";
 import { z } from "zod";
 
-const assistant = Agent({
-  id: "assistant",
-  name: "Assistant",
-  instructions: "Use the available tools.",
-  tools: [
+const assistant = Agent({ id: "assistant", name: "Assistant" })
+  .instructions("Use the available tools.")
+  .tools(
     tool({
       name: "lookup",
       input: z.object({ id: z.string() }),
@@ -53,8 +51,7 @@ const assistant = Agent({
         return { id, owner: ctx.info };
       },
     }),
-  ],
-});
+  );
 
 // Explicit Tenant API client (options or env / link via createClient()).
 const client = createClient({
@@ -97,68 +94,57 @@ throws `IncompatibleRuntimeError` / `incompatible_host` when the Host range or
 required features do not match. Re-exports include `PROTOCOL_FEATURES`,
 `ERROR_CODES` and `compareVersions`.
 
-Load Agent Skills from a local catalog folder with `skills(path)`:
+Load Agent Skills from a local catalog folder with `.skills(path)`:
 
 ```ts
-import { Agent, skills } from "@nylorun/agents";
-
-const assistant = Agent({
-  id: "assistant",
-  name: "Order assistant",
-  instructions: "Use lookup_order for orders.",
-  tools: [lookupOrder],
-}).use(skills("./assistant-skills"));
+import { Agent } from "@nylorun/agents";
+
+const assistant = Agent({ id: "assistant", name: "Order assistant" })
+  .instructions("Use lookup_order for orders.")
+  .tools(lookupOrder)
+  .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.
 
-Declare MCP servers with `mcp(...)` (same map shape as agent-plugins `mcpServers` / manifest v3):
+Declare MCP servers with `.mcp(...)` (same map shape as agent-plugins `mcpServers`):
 
 ```ts
-import { Agent, mcp } from "@nylorun/agents";
-
-const assistant = Agent({
-  id: "assistant",
-  name: "Assistant",
-  instructions: "Use the available tools.",
-}).use(
-  mcp({
-    github: {
-      name: "github",
-      type: "streamable-http",
-      url: "https://mcp.example.com/github",
-    },
-  }),
-);
+import { Agent } from "@nylorun/agents";
+
+const assistant = Agent({ id: "assistant", name: "Assistant" })
+  .instructions("Use the available tools.")
+  .mcp({
+    github: { type: "streamable-http", url: "https://mcp.example.com/github" },
+  });
 ```
 
-Each key must equal that server's `name`. Transports follow [Agent Plugins MCP servers](https://agent-plugins.org/plugin-authors/mcp-servers): `stdio`, `streamable-http`, and `sse`. Pass `{ id: "…" }` as the second argument to override the default capability id `"mcp"`.
+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)`.
 
-Give an agent an isolated computer with `sandbox()`:
+Give an agent an isolated computer with `.sandbox()`:
 
 ```ts
-import { Agent, sandbox } from "@nylorun/agents";
+import { Agent } from "@nylorun/agents";
 
-const analyst = Agent({
-  id: "analyst",
-  instructions: "Analyse the data the user gives you. Use Python.",
-}).use(sandbox());
+const analyst = Agent({ id: "analyst" })
+  .instructions("Analyse the data the user gives you. Use Python.")
+  .sandbox();
 ```
 
 The model gets `bash`, `read`, `write`, `edit`, `grep` and `glob` on a Linux machine with a persistent `/workspace`. These tools run in the Runtime, not in your process, so sandbox-only agents need no connected executor. The agent declares what it needs; the Runtime decides where it runs (today an emulated shell in the Runtime process). Every option is optional plain data:
 
 ```ts
-.use(sandbox({
+.sandbox({
   image: "python:3.13",                           // any OCI image; default python:3.13-slim
   network: { preset: "dev", allow: ["api.example.com"] }, // "none" | "dev" (default) | "open"
   resources: { cpus: 2, memory: "2GiB" },
   idle: "15m",                                    // stop compute when idle; files persist
-}))
+})
 ```
 
 The `dev` preset allows package registries and code hosts. Private networks, loopback, the host and cloud metadata endpoints are always blocked. Options from the full design that are not in this version (`setup`, `files`, `secrets`, `mount`, `onStart`, …) throw a `SandboxError` that says so.
 
-Put an agent in another agent's `tools` to let the model delegate to it:
+Add an agent with `.subagents()` to let the model delegate to it:
 
 ```ts
 import { Agent } from "@nylorun/agents";
@@ -168,54 +154,47 @@ const researcher = Agent({
   id: "researcher",
   description:
     "Investigates an order's history. Returns a short summary with the ids it relied on.",
-  instructions:
-    "Investigate one question about one order. Be exhaustive, then be brief.",
-  tools: [searchOrders, readTicket],
-  outputSchema: z.object({
-    summary: z.string(),
-    evidence: z.array(z.string()),
-  }),
-});
+})
+  .instructions("Investigate one question about one order. Be exhaustive, then be brief.")
+  .tools(searchOrders, readTicket)
+  .output(z.object({ summary: z.string(), evidence: z.array(z.string()) }));
 
-const support = Agent({
-  id: "support",
-  instructions:
+const support = Agent({ id: "support" })
+  .instructions(
     "For anything needing more than two lookups, delegate to researcher with a complete, self-contained task.",
-  tools: [lookupOrder, refundOrder, researcher],
-});
+  )
+  .tools(lookupOrder, refundOrder)
+  .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 executor you already run for the parent (`connectAgents({ 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).
 
-Delegate when the parent should keep the answer. When a specialist should own the rest of the conversation, switch capabilities with a `before("step")` 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.
+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 executor. 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.
 
-## Workflows
+## Flow agents
 
-Nest `Chain`, `Switch`, `Parallel`, `Map`, and `Loop` around agents and `tool()` to
-build durable flows. A workflow is a definition with `kind: "workflow"`: register
-it in `export const agents` (or `saveAgent(workflow)` — referenced agents are
-saved first), then `createSession({ agentId })` and `session.input(value)` like
-any agent. `input` sends string values as `content` and other JSON as `data`.
-`connectAgents({ agents: [workflow] })` saves the tree and connects executors for
-the workflow id and every referenced agent. Tool nodes, pure functions (slot
-`input`, Switch `on`, Map `over`, Loop `decide`), and Loop `verify` run as Actions
-routed by `(workflowId, key)`.
+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.
 
 ```ts
-import { Agent, Chain, Loop, Map, tool } from "@nylorun/agents";
+import { Agent, tool } from "@nylorun/agents";
 import { z } from "zod";
 
-const planner = Agent({
-  id: "planner",
-  instructions: "Return { tasks: string[] }.",
-  outputSchema: z.object({ tasks: z.array(z.string()) }),
-}).build();
+const planner = Agent({ id: "planner" })
+  .instructions("Return { tasks: string[] }.")
+  .output(z.object({ tasks: z.array(z.string()) }));
 
-const coder = Agent({
-  id: "coder",
-  instructions: "Implement one task. Return { summary }.",
-  outputSchema: z.object({ summary: z.string() }),
-}).build();
+const coder = Agent({ id: "coder" })
+  .instructions("Implement one task. Return { summary }.")
+  .output(z.object({ summary: z.string() }));
 
 const openPr = tool({
   name: "open-pr",
@@ -226,43 +205,51 @@ const openPr = tool({
   },
 });
 
-export const shipFeature = Chain({
-  id: "ship-feature",
-  steps: [
-    planner,
-    Map({
-      id: "implement",
-      over: (plan) => plan.tasks,
-      each: Loop({
-        id: "code",
-        run: coder,
-        verify: () => ({ pass: true }),
-        decide: ({ output }) => ({ output }),
-      }),
+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,
     }),
-    {
-      run: openPr,
-      input: ({ value }) => ({
-        summaries: value.map((item: { summary: string }) => item.summary),
-      }),
-    },
-  ],
-});
+    { id: "implement", input: ({ input }) => input.tasks },
+  )
+  .step(openPr, { input: ({ input }) => ({ summaries: input.map((item) => item.summary) }) });
 
 export const agents = [shipFeature];
 ```
 
-| Primitive | Role |
+| Stage | Role |
 | --- | --- |
-| **Chain** | Steps in order; slots reshape with `{ run, id?, input? }` |
-| **Switch** | Pure `on(input) → key`, then the matching case (or `default`) |
-| **Parallel** | Fixed named branches at once; output is an object |
-| **Map** | Pure `over(input) → items`, one child per item; output is an array |
-| **Loop** | `run` → `verify` → `decide` until `{ output }` |
-
-Agents inside a workflow keep their own sessions (linked from the workflow
-session) and share one sandbox: declare identical specs on every agent that
-uses one, attach with `createSession({ …, sandbox: { session } })`, call
+| **`.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 |
+| **`.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` |
+
+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`.
+
+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.
+
+The agents in a flow share one sandbox: declare it with `.sandbox(spec)` on the
+flow agent and give the agents that use it `.sandbox()` with no options (an agent
+that declares its own spec must match), attach with `createSession({ …, sandbox: { session } })`, call
 built-ins via `session.sandbox` (application) or `ctx.sandbox` (executor).
 Observe with `session.observe({ follow: true })` to merge linked agent streams;
 `pending()` lists waits across the tree. Studio renders the manifest tree and
@@ -286,4 +273,107 @@ After registration, `connectAgents` opens authenticated fetch SSE before discove
 
 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 executor 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 SDK depends only on core within the Nylorun packages; installing it does not install harness. Use `/define`, `/client`, or `/executor` for focused imports, or the root for convenience. Studio uses `/client`. See [the adopted host contract](../harness/HOST_CONTRACT.md).
+## AG-UI
+
+`@nylorun/agents/ag-ui` serves the Tenant's agents to any
+[AG-UI](https://docs.ag-ui.com) client (`@ag-ui/client`'s `HttpAgent`,
+CopilotKit, a desktop renderer) from your own server. Your server signs people
+in and names the person each request is for; the handler maps each AG-UI thread
+to one session per person, agent and thread, and streams it as AG-UI events.
+
+```ts
+import { createServer } from "node:http";
+import { createAgUiHandler, toNodeListener } from "@nylorun/agents/ag-ui";
+import support from "./agents/support.js";
+
+const agui = createAgUiHandler({
+  basePath: "/api/agui",
+  agents: [support], // nothing else is reachable
+  subject: async (request) => (await getSignedInUser(request))?.id, // undefined → 401
+});
+
+createServer(toNodeListener(agui)).listen(3000);
+// Next.js, Hono, Bun, Deno, Workers: export or mount `agui.fetch` directly.
+```
+
+| Method and path under `basePath` | Operation |
+| --- | --- |
+| `POST /{agentId}` | Run: an AG-UI `RunAgentInput` in, server-sent events out |
+| `GET /{agentId}/threads/{threadId}/messages` | History as a plain AG-UI `Message[]`, usable as `HttpAgent`'s `initialMessages` |
+| `GET /{agentId}/threads/{threadId}/events` | Reattach: the rest of a run after a dropped connection, from `Last-Event-ID` (or `?cursor=`); `204` when nothing is left |
+| `POST /{agentId}/threads/{threadId}/cancel` | Cancel the running turn |
+
+`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` or
+`credentialSelections` (keep `info` stable: it is part of the session's
+identity).
+
+- Each AG-UI message id is the command's idempotency key: a retried run replays
+  the same turn instead of starting a second one.
+- An approval ends the run with an AG-UI interrupt (`reason: "tool_approval"`,
+  `toolCallId` the model's call id). Resume with
+  `runAgent({ resume: [{ interruptId, status: "resolved", payload: { approved: true } }] })`.
+  Other interactions answer with `payload` as the response.
+- Every event that ends a group carries the Runtime cursor as its SSE `id`.
+  `HttpAgent` does not reconnect by itself; call the reattach route with the
+  last id you received.
+- Closing the connection stops reading; it never cancels the turn.
+- A busy or paused thread ends the run with `RUN_ERROR` code `session_busy`.
+- The handler calls the Runtime as each person (`client.as(subject, { scopes })`,
+  below), so the Runtime itself keeps one person out of another's threads.
+  `scopes` defaults to `["sessions:own"]`; add `"vaults:own"` when `session()`
+  attaches the person's vaults. A `subject` the Runtime cannot name (see below)
+  answers `500` (`subject_invalid`).
+- The handler needs a Runtime with the optional features `transcript-events`
+  and `subject-headers` and answers `502` (`runtime_feature_missing`) without
+  them.
+
+A complete web backend with a test is in
+[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
+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. Browsers always go through your server: never let one call the
+Runtime directly.
+
+## 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:
+
+```ts
+import { createClient } from "@nylorun/agents";
+
+const app = createClient(); // the Tenant key, on the server only
+
+// Per request, after your own sign-in:
+const person = app.as(`app:${user.id}`, { scopes: ["sessions:own", "vaults:own"] });
+await person.createSession({ agentId: "support", ownerUserId: `app:${user.id}` });
+await person.listSessions(); // only this person's sessions
+```
+
+`as()` sends `Nylorun-Subject` and `Nylorun-Scopes` on every call, event
+streams included, and the Runtime (optional feature `subject-headers`)
+enforces both: another person's sessions and vaults answer the same `404` as
+missing ones, and a route outside the scopes answers `403` (`scope_required`).
+Nothing is minted, cached or refreshed, and the copy shares the client's
+compatibility check, so calling `as()` per request is cheap.
+
+| Scope | Allows |
+| --- | --- |
+| `sessions:own` | The person's own sessions: create, list, read, stream, message, approve, respond, cancel |
+| `vaults:own` | The person's own vaults and credentials |
+| `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, executors, actions or the sandbox
+tool routes; call those without `as()`. 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: an executor key that tries is `403`.
+
+The SDK depends only on core within the Nylorun packages; installing it does not install harness. `/ag-ui` adds `@ag-ui/core`; nothing else imports it. Use `/define`, `/client`, `/executor` or `/ag-ui` for focused imports, or the root for convenience. Studio uses `/client`. See [the adopted host contract](../harness/HOST_CONTRACT.md).

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

@@ -0,0 +1,42 @@
+import type { BuiltWorkflow } from "@nylorun/core/define";
+import { type SubjectScope } from "@nylorun/core/contracts";
+import { type AgentSource, type AgentsClient } from "../client.js";
+/** Per-session parameters the host may add, such as the person's vault for MCP servers. */
+export interface AgUiSessionOptions {
+    /** Part of the session's identity: keep it stable for a subject and agent, or runs get 409. */
+    info?: Record<string, unknown>;
+    vaultIds?: readonly string[];
+    credentialSelections?: Parameters<AgentsClient["createSession"]>[0]["credentialSelections"];
+}
+export interface AgUiHandlerOptions {
+    /** Agents this endpoint may run: built agents, workflows or their ids. Nothing else is reachable. */
+    agents: readonly (AgentSource | BuiltWorkflow | string)[];
+    /** The signed-in person the request is for. `undefined` answers 401; there is no anonymous mode. */
+    subject(request: Request): string | undefined | Promise<string | undefined>;
+    /** Where `fetch` is mounted, e.g. `/api/agui`. Default `/`. */
+    basePath?: string;
+    /** Application client. Default: `createClient()`, from the environment or the Project link. */
+    client?: AgentsClient | Promise<AgentsClient>;
+    /**
+     * What each subject may do through this endpoint. Default `["sessions:own"]`; add
+     * `vaults:own` if `session()` attaches the person's vaults.
+     */
+    scopes?: readonly SubjectScope[];
+    /** Optional per-session parameters, e.g. the person's vault for connected accounts. */
+    session?(subject: string, agentId: string): AgUiSessionOptions | Promise<AgUiSessionOptions>;
+}
+export interface AgUiHandler {
+    /** One entry point that routes by method and path under `basePath`. Bound. */
+    readonly fetch: (request: Request) => Promise<Response>;
+    /** `POST`: an AG-UI `RunAgentInput` in, the run's events out as server-sent events. */
+    run(request: Request, agentId: string): Promise<Response>;
+    /** `GET`: the thread's messages as a plain AG-UI `Message[]`. */
+    history(request: Request, agentId: string, threadId: string): Promise<Response>;
+    /** `GET`: the rest of a run after a dropped connection, from `Last-Event-ID` or `?cursor=`. */
+    reattach(request: Request, agentId: string, threadId: string): Promise<Response>;
+    /** `POST`: cancels the thread's running turn. */
+    cancel(request: Request, agentId: string, threadId: string): Promise<Response>;
+}
+/** A session per subject, agent and thread; one subject can never name another's session. */
+export declare function sessionIdFor(subject: string, agentId: string, threadId: string): string;
+export declare function createAgUiHandler(options: AgUiHandlerOptions): AgUiHandler;