@nylorun/agents 0.8.0-beta → 0.9.0-beta

package/CHANGELOG.md

@@ -1,5 +1,41 @@
 # @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

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.
 
-## Workflows
+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.
 
-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)`.
+## 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.
 
 ```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

package/dist/builder.d.ts

@@ -0,0 +1,20 @@
+import { Agent as CoreAgent, AgentBuilder as CoreAgentBuilder } from "@nylorun/core/define";
+import type { AgentOptions, ToolSchemaSource } from "@nylorun/core/define";
+import { type SkillsOptions } from "./skills/index.js";
+/**
+ * The agent builder with the capabilities that read files: `.skills()` and `.plugin()`.
+ * `@nylorun/agents/define` exports the portable builder from core, without them.
+ */
+export declare class AgentBuilder<Info = unknown, Schema extends ToolSchemaSource | undefined = undefined, Id extends string = string> extends CoreAgentBuilder<Info, Schema, Id> {
+    /** Load an Agent Skills folder. */
+    skills(directory: string, options?: SkillsOptions): this;
+    /** Attach an Agent Plugin package. */
+    plugin(directory: string): this;
+    output<S extends ToolSchemaSource>(schema: S): AgentBuilder<Info, S, Id>;
+}
+export declare function Agent<Info = unknown, Schema extends ToolSchemaSource | undefined = undefined, const Id extends string = string>(options: AgentOptions<Schema> & {
+    readonly id: Id;
+}): AgentBuilder<Info, Schema, Id>;
+export declare namespace Agent {
+    const from: typeof CoreAgent.from;
+}

package/dist/builder.js

@@ -0,0 +1,26 @@
+import { Agent as CoreAgent, AgentBuilder as CoreAgentBuilder, } from "@nylorun/core/define";
+import { skills } from "./skills/index.js";
+import { plugin } from "./plugins/plugin.js";
+/**
+ * The agent builder with the capabilities that read files: `.skills()` and `.plugin()`.
+ * `@nylorun/agents/define` exports the portable builder from core, without them.
+ */
+export class AgentBuilder extends CoreAgentBuilder {
+    /** Load an Agent Skills folder. */
+    skills(directory, options) {
+        return this.capability(skills(directory, options));
+    }
+    /** Attach an Agent Plugin package. */
+    plugin(directory) {
+        return this.capability(plugin(directory));
+    }
+    output(schema) {
+        return super.output(schema);
+    }
+}
+export function Agent(options) {
+    return new AgentBuilder(options);
+}
+(function (Agent) {
+    Agent.from = CoreAgent.from;
+})(Agent || (Agent = {}));

package/dist/client.js

@@ -38,9 +38,15 @@ function declarationsOf(agent) {
         return [];
     const found = (binding.declarations ?? []).map((item) => ({ key: item.id, item }));
     for (const tool of binding.tools ?? []) {
-        const child = delegateOf(tool)?.agent;
+        const delegate = delegateOf(tool);
+        const child = delegate?.agent;
         for (const item of child?.getBinding().declarations ?? [])
             found.push({ key: `${child.id}/${item.id}`, item });
+        // A flow agent used as a tool: its agents' declarations, keyed `<flow>/<agent>/<capability>`.
+        const flow = delegate?.workflow;
+        for (const leaf of Object.values(flow?.getBinding().agents ?? {}))
+            for (const item of leaf.declarations ?? [])
+                found.push({ key: `${flow.id}/${leaf.manifest.id}/${item.id}`, item });
     }
     return found;
 }
@@ -100,6 +106,22 @@ export class AgentsClient {
         return this.transport.json(`/v1/sessions${query}`, "GET", undefined, options.signal);
     }
     async saveAgent(agent, options) {
+        if (isBuiltWorkflow(agent) && agent.manifest.workflowSchemaVersion === 2) {
+            // A v2 workflow embeds its agents: one document, carrying their plugin roots.
+            const pluginRoots = {};
+            for (const binding of Object.values(agent.getBinding().agents)) {
+                const leaf = { id: binding.manifest.id, manifest: binding.manifest, getBinding: () => binding };
+                assertNoMiddlewareClosures(leaf);
+                for (const [key, root] of Object.entries(pluginRootsOf(leaf) ?? {}))
+                    pluginRoots[`${leaf.id}/${key}`] = root;
+            }
+            return this.transport.json(`/v1/agents/${segment(agent.id)}`, "PUT", {
+                requestId: options.requestId ?? id(),
+                manifest: agent.manifest,
+                implementationVersion: options.implementationVersion,
+                ...(Object.keys(pluginRoots).length === 0 ? {} : { pluginRoots }),
+            });
+        }
         if (isBuiltWorkflow(agent)) {
             for (const binding of Object.values(agent.getBinding().agents)) {
                 await this.saveAgent({

package/dist/executor.js

@@ -1,5 +1,5 @@
 import { AgentManifestSchema, ActionSchema, ActionClaimResponseSchema, } from "@nylorun/core/contracts";
-import { agentFrom, isBuiltWorkflow, } from "@nylorun/core/define";
+import { agentFrom, delegateOf, hashManifest, isFlowDelegate, isBuiltWorkflow, } from "@nylorun/core/define";
 import { AgentsClient, assertNoMiddlewareClosures, } from "./client.js";
 import { resolveConnection } from "./connection.js";
 import { deriveExecutorToken } from "./derived-credentials.js";
@@ -12,39 +12,87 @@ function implementationVersionOf(options) {
         env("NYLORUN_IMPLEMENTATION_VERSION") ??
         "dev");
 }
+/** Agents embedded in a v2 workflow: served here, but saved only as part of the workflow. */
+const embeddedAgents = new WeakMap();
 function buildAgents(options) {
     const agents = new Map();
-    const addAgent = (built) => {
+    const embedded = new Set();
+    /**
+     * Agents embedded in another definition (a v2 flow's agents, a flow agent used as a
+     * tool) may be reached from more than one place; the same definition is served once.
+     */
+    const sameAsServed = (id, manifest) => {
+        const served = agents.get(id);
+        if (!served)
+            return false;
+        if (hashManifest(served.manifest) === hashManifest(manifest))
+            return true;
+        throw new Error(`Duplicate connected agent ${id}`);
+    };
+    const addAgent = (built, shared = false) => {
         assertNoMiddlewareClosures(built);
         AgentManifestSchema.parse(built.manifest);
-        if (agents.has(built.id))
-            throw new Error(`Duplicate connected agent ${built.id}`);
+        if (shared ? sameAsServed(built.id, built.manifest) : agents.has(built.id)) {
+            if (!shared)
+                throw new Error(`Duplicate connected agent ${built.id}`);
+            return;
+        }
         agents.set(built.id, built);
+        for (const tool of built.getBinding().tools) {
+            const delegate = delegateOf(tool);
+            if (!delegate || !isFlowDelegate(delegate))
+                continue;
+            // A flow agent used as a tool runs in its own linked session: serve its code too.
+            if (!delegate.workflow)
+                throw new Error(`Flow agent '${delegate.manifest.id}' is used as a tool by '${built.id}' but has no local implementation`);
+            addWorkflow(delegate.workflow, true);
+            embedded.add(delegate.workflow.id);
+        }
+    };
+    const addWorkflow = (workflow, shared = false) => {
+        if (shared ? sameAsServed(workflow.id, workflow.manifest) : agents.has(workflow.id)) {
+            if (!shared)
+                throw new Error(`Duplicate connected agent ${workflow.id}`);
+            return;
+        }
+        agents.set(workflow.id, workflow);
+        const v2 = workflow.manifest.workflowSchemaVersion === 2;
+        for (const binding of Object.values(workflow.getBinding().agents)) {
+            addAgent(agentFrom(binding.manifest, binding.implementations), v2);
+            if (v2)
+                embedded.add(binding.manifest.id);
+        }
     };
     for (const source of options.agents) {
         if (isBuiltWorkflow(source)) {
-            if (agents.has(source.id))
-                throw new Error(`Duplicate connected agent ${source.id}`);
-            agents.set(source.id, source);
-            for (const binding of Object.values(source.getBinding().agents))
-                addAgent(agentFrom(binding.manifest, binding.implementations));
+            addWorkflow(source);
             continue;
         }
         const built = source.build?.() ?? source;
         if (isBuiltWorkflow(built)) {
-            if (agents.has(built.id))
-                throw new Error(`Duplicate connected agent ${built.id}`);
-            agents.set(built.id, built);
-            for (const binding of Object.values(built.getBinding().agents))
-                addAgent(agentFrom(binding.manifest, binding.implementations));
+            addWorkflow(built);
             continue;
         }
         addAgent(built);
     }
     if (!agents.size)
         throw new Error("connectAgents requires at least one agent");
+    // A definition passed in directly is saved on its own, even if another one embeds it.
+    for (const source of options.agents)
+        embedded.delete(source.id);
+    embeddedAgents.set(agents, embedded);
     return agents;
 }
+/**
+ * The manifest hash an executor serves for a workflow's flow actions. A run is pinned to
+ * one workflow manifest, and its stage keys may shift between deploys, so flow actions
+ * for another hash are left for the executor that serves it.
+ */
+function flowManifestHash(agent) {
+    return isBuiltWorkflow(agent) && agent.manifest.workflowSchemaVersion === 2
+        ? hashManifest(agent.manifest)
+        : undefined;
+}
 function connectExecutorMode(options, runtime, agents) {
     const transport = new Transport(runtime, "executor");
     const version = implementationVersionOf(options);
@@ -65,6 +113,7 @@ function connectExecutorMode(options, runtime, agents) {
         }
         catch { }
     };
+    const skipped = new Set();
     let discovering = false, dirty = false;
     const discover = async () => {
         dirty = true;
@@ -86,6 +135,14 @@ function connectExecutorMode(options, runtime, agents) {
                     const agent = agents.get(action.agentId);
                     if (!agent || action.status !== "pending" || active.has(action.actionId))
                         continue;
+                    const served = flowManifestHash(agent);
+                    if (served !== undefined && "key" in action && action.manifestHash !== served) {
+                        if (!skipped.has(action.actionId)) {
+                            skipped.add(action.actionId);
+                            report(new Error(`Skipped action ${action.actionId}: it belongs to manifest ${action.manifestHash} of '${action.agentId}', and this executor serves ${served}`));
+                        }
+                        continue;
+                    }
                     const work = new AbortController();
                     active.set(action.actionId, work);
                     let delivered = false;
@@ -264,14 +321,21 @@ function connectApplicationMode(options, application, agents) {
     });
     void ready.catch(() => { });
     const boot = (async () => {
+        const embedded = embeddedAgents.get(agents) ?? new Set();
         for (const agent of agents.values()) {
+            if (embedded.has(agent.id))
+                continue;
             await application.saveAgent(agent, { implementationVersion: version });
         }
-        const registrations = [...agents.values()].map((agent) => ({
-            agentId: agent.id,
-            token: deriveExecutorToken(application.transport.key, application.transport.tenant, agent.id),
-            implementationVersion: version,
-        }));
+        const registrations = [...agents.values()].map((agent) => {
+            const manifestHash = flowManifestHash(agent);
+            return {
+                agentId: agent.id,
+                token: deriveExecutorToken(application.transport.key, application.transport.tenant, agent.id),
+                implementationVersion: version,
+                ...(manifestHash === undefined ? {} : { manifestHash }),
+            };
+        });
         await application.transport.json("/v1/executors", "PUT", {
             executors: registrations,
         });

package/dist/index.d.ts

@@ -1,6 +1,8 @@
 export { hashManifest, PROTOCOL_VERSION, PROTOCOL_FEATURES, HOST_PROTOCOL, DEFINITION_SCHEMA_VERSION, TENANT_HEADER, PROTOCOL_HEADER, SUBJECT_HEADER, SCOPES_HEADER, TENANT_ID_PATTERN, isTenantId, newTenantId, newPrincipalId, checkCompatibility, compareVersions, ERROR_CODES, } from "@nylorun/core/compatibility";
 export type { ProtocolFeature, ProtocolRange, Compatibility, ErrorCode, } from "@nylorun/core/compatibility";
-export { Agent, AgentBuilder, AgentBuildError, AgentLifecycleError, Loop, Chain, Switch, Parallel, Map, VerdictSchema, isVerdict, withInstructions, withoutTools, WorkflowBuildError, isBuiltWorkflow, capability, tool, defineSchema, ToolError, } from "@nylorun/core/define";
+export { Agent, AgentBuilder } from "./builder.js";
+export { AgentBuildError, AgentLifecycleError, Loop, Chain, Switch, Parallel, Map, VerdictSchema, isVerdict, withInstructions, withoutTools, WorkflowBuildError, isBuiltWorkflow, capability, CapabilityBuilder, flow, tool, defineSchema, ToolError, } from "@nylorun/core/define";
+export type { FlowAgentBuilder, Flow, Named, StageArgs, NestedStageArgs, CapabilityIdentity, } from "@nylorun/core/define";
 export type { AgentOptions, AgentManifest, BuiltAgent, BuiltWorkflow, LoopOptions, LoopDecideArgs, LoopVerifyArgs, LoopDecision, ChainOptions, SwitchOptions, ParallelOptions, MapOptions, Verdict, WorkflowBinding, WorkflowManifest, ToolDefinition, ToolExecutionContext, ToolOutcome, Patch, Decision, TurnDecision, HookScope, BeforeHook, AfterHook, JsonValue, JsonObject, } from "@nylorun/core/define";
 export type { LiveEvent, SessionCommand, Action, ActionOutcome, CredentialInfo, CredentialSelection, VaultInfo, SubjectScope, } from "@nylorun/core/contracts";
 export { SUBJECT_SCOPES } from "@nylorun/core/contracts";
@@ -23,7 +25,7 @@ export type { StdioLaunch } from "./plugins/launch.js";
 export { skills, loadSkillsFromDirectory, resolveSkillsRoot, parseSkill, SkillsError, formatSkillCatalog, SKILLS_USAGE, } from "./skills/index.js";
 export type { SkillsCapability, SkillsOptions, SkillDiagnostic, } from "./skills/index.js";
 export { mcp, McpError } from "./mcp/index.js";
-export type { McpCapability, McpOptions } from "./mcp/index.js";
+export type { McpCapability, McpOptions, McpServerSpec } from "./mcp/index.js";
 export { sandbox, SandboxError } from "./sandbox/index.js";
 export type { SandboxCapability, SandboxCapabilityOptions, SandboxOptions, ActionSandbox, ActionSandboxToolResult, CreateActionSandboxOptions, } from "./sandbox/index.js";
 export { createActionSandbox, definitionDeclaresSandbox, isActionSandboxTool, } from "./sandbox/index.js";

package/dist/index.js

@@ -1,6 +1,7 @@
 // Definition authoring and wire contracts are the only harness runtime imports.
 export { hashManifest, PROTOCOL_VERSION, PROTOCOL_FEATURES, HOST_PROTOCOL, DEFINITION_SCHEMA_VERSION, TENANT_HEADER, PROTOCOL_HEADER, SUBJECT_HEADER, SCOPES_HEADER, TENANT_ID_PATTERN, isTenantId, newTenantId, newPrincipalId, checkCompatibility, compareVersions, ERROR_CODES, } from "@nylorun/core/compatibility";
-export { Agent, AgentBuilder, AgentBuildError, AgentLifecycleError, Loop, Chain, Switch, Parallel, Map, VerdictSchema, isVerdict, withInstructions, withoutTools, WorkflowBuildError, isBuiltWorkflow, capability, tool, defineSchema, ToolError, } from "@nylorun/core/define";
+export { Agent, AgentBuilder } from "./builder.js";
+export { AgentBuildError, AgentLifecycleError, Loop, Chain, Switch, Parallel, Map, VerdictSchema, isVerdict, withInstructions, withoutTools, WorkflowBuildError, isBuiltWorkflow, capability, CapabilityBuilder, flow, tool, defineSchema, ToolError, } from "@nylorun/core/define";
 export { SUBJECT_SCOPES } from "@nylorun/core/contracts";
 export { AgentsClient, SessionClient, createClient } from "./client.js";
 export { connectAgents } from "./executor.js";

package/dist/mcp/index.d.ts

@@ -1,2 +1,2 @@
-export { mcp, McpError } from "./mcp.js";
-export type { McpCapability, McpOptions } from "./mcp.js";
+export { mcp, McpError, normalizeMcpServers } from "@nylorun/core/define";
+export type { McpCapability, McpOptions, McpServerSpec } from "@nylorun/core/define";

package/dist/mcp/index.js

@@ -1 +1 @@
-export { mcp, McpError } from "./mcp.js";
+export { mcp, McpError, normalizeMcpServers } from "@nylorun/core/define";

package/dist/sandbox/index.d.ts

@@ -1,4 +1,4 @@
-export { sandbox, SandboxError } from "./sandbox.js";
-export type { SandboxCapability, SandboxCapabilityOptions, SandboxOptions, } from "./sandbox.js";
+export { sandbox, SandboxError } from "@nylorun/core/define";
+export type { SandboxCapability, SandboxCapabilityOptions, SandboxOptions, } from "@nylorun/core/define";
 export { createActionSandbox, definitionDeclaresSandbox, isActionSandboxTool, } from "./client.js";
 export type { ActionSandbox, ActionSandboxToolResult, CreateActionSandboxOptions, } from "./client.js";

package/dist/sandbox/index.js

@@ -1,2 +1,2 @@
-export { sandbox, SandboxError } from "./sandbox.js";
+export { sandbox, SandboxError } from "@nylorun/core/define";
 export { createActionSandbox, definitionDeclaresSandbox, isActionSandboxTool, } from "./client.js";

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@nylorun/agents",
-  "version": "0.8.0-beta",
+  "version": "0.9.0-beta",
   "description": "Nylorun agent definitions, session client and connected executor",
   "type": "module",
   "license": "Apache-2.0",
@@ -40,7 +40,7 @@
   },
   "dependencies": {
     "@ag-ui/core": "~1.0.0",
-    "@nylorun/core": "0.7.0-beta",
+    "@nylorun/core": "0.8.0-beta",
     "gray-matter": "^4.0.3"
   },
   "peerDependencies": {

package/dist/mcp/mcp.d.ts

@@ -1,30 +0,0 @@
-import type { CapabilityDeclaration, McpServerManifest } from "@nylorun/core/define";
-export interface McpOptions {
-    /** Capability id. Defaults to `"mcp"`. */
-    readonly id?: string;
-}
-export interface McpCapability extends CapabilityDeclaration {
-    readonly mcpServers: Readonly<Record<string, McpServerManifest>>;
-}
-export declare class McpError extends Error {
-    readonly code: string;
-    constructor(code: string, message: string);
-}
-/**
- * Declare MCP servers as one capability for `Agent.use`.
- *
- * The map shape matches agent-plugins `mcpServers` and manifest v3: each key
- * must equal that server's `name`. Supported transports are `stdio`,
- * `streamable-http`, and `sse` (see https://agent-plugins.org/plugin-authors/mcp-servers).
- *
- * ```ts
- * Agent({...}).use(mcp({
- *   github: {
- *     name: "github",
- *     type: "streamable-http",
- *     url: "https://mcp.example.com/github",
- *   },
- * }))
- * ```
- */
-export declare function mcp(servers: Readonly<Record<string, McpServerManifest>>, options?: McpOptions): McpCapability;

package/dist/mcp/mcp.js

@@ -1,80 +0,0 @@
-export class McpError extends Error {
-    code;
-    constructor(code, message) {
-        super(message);
-        this.name = "McpError";
-        this.code = code;
-    }
-}
-/**
- * Declare MCP servers as one capability for `Agent.use`.
- *
- * The map shape matches agent-plugins `mcpServers` and manifest v3: each key
- * must equal that server's `name`. Supported transports are `stdio`,
- * `streamable-http`, and `sse` (see https://agent-plugins.org/plugin-authors/mcp-servers).
- *
- * ```ts
- * Agent({...}).use(mcp({
- *   github: {
- *     name: "github",
- *     type: "streamable-http",
- *     url: "https://mcp.example.com/github",
- *   },
- * }))
- * ```
- */
-export function mcp(servers, options = {}) {
-    const id = options.id ?? "mcp";
-    if (!isRecord(servers)) {
-        throw new McpError("mcp.invalid", "mcp() expects a non-empty map of MCP servers");
-    }
-    const entries = Object.entries(servers);
-    if (entries.length === 0) {
-        throw new McpError("mcp.empty", "mcp() requires at least one MCP server");
-    }
-    const mcpServers = {};
-    for (const [key, server] of entries) {
-        if (!isMcpServer(server)) {
-            throw new McpError("mcp.invalid-server", `MCP server '${key}' is not a valid stdio, streamable-http, or sse declaration`);
-        }
-        if (server.name !== key) {
-            throw new McpError("mcp.name-mismatch", `MCP server key '${key}' must equal the server name '${server.name}'`);
-        }
-        mcpServers[key] = freezeServer(server);
-    }
-    return { id, mcpServers: Object.freeze(mcpServers) };
-}
-function freezeServer(server) {
-    if (server.type === "stdio") {
-        return Object.freeze({
-            name: server.name,
-            type: "stdio",
-            command: server.command,
-            ...(server.args === undefined ? {} : { args: Object.freeze([...server.args]) }),
-            ...(server.env === undefined
-                ? {}
-                : { env: Object.freeze({ ...server.env }) }),
-            ...(server.cwd === undefined ? {} : { cwd: server.cwd }),
-        });
-    }
-    return Object.freeze({
-        name: server.name,
-        type: server.type,
-        url: server.url,
-        ...(server.headers === undefined
-            ? {}
-            : { headers: Object.freeze({ ...server.headers }) }),
-    });
-}
-function isMcpServer(value) {
-    if (!isRecord(value) || typeof value.name !== "string" || !value.name)
-        return false;
-    if (value.type === "stdio")
-        return typeof value.command === "string" && value.command.length > 0;
-    if (value.type === "streamable-http" || value.type === "sse")
-        return typeof value.url === "string" && value.url.length > 0;
-    return false;
-}
-function isRecord(value) {
-    return !!value && typeof value === "object" && !Array.isArray(value);
-}

package/dist/sandbox/sandbox.d.ts

@@ -1,27 +0,0 @@
-import type { CapabilityDeclaration, SandboxManifest, ToolDefinition } from "@nylorun/core/define";
-/** What computer the agent needs. The Runtime decides where it runs. */
-export type SandboxOptions = SandboxManifest;
-export interface SandboxCapabilityOptions {
-    /** Capability id. Defaults to `"sandbox"`. */
-    readonly id?: string;
-}
-export interface SandboxCapability extends CapabilityDeclaration {
-    readonly sandbox: SandboxManifest;
-    readonly tools: readonly ToolDefinition[];
-}
-export declare class SandboxError extends Error {
-    readonly code: string;
-    constructor(code: string, message: string);
-}
-/**
- * Give the agent an isolated Linux machine with a persistent `/workspace`.
- *
- * Adds the built-in `bash`, `read`, `write`, `edit`, `grep` and `glob` tools. They run in the
- * Nylorun Runtime, which picks the backend. Agent code declares requirements only.
- *
- * ```ts
- * Agent({ id: "analyst", instructions: "..." }).use(sandbox())
- * Agent({ ... }).use(sandbox({ image: "node:24", network: { allow: ["api.github.com"] } }))
- * ```
- */
-export declare function sandbox(options?: SandboxOptions, capability?: SandboxCapabilityOptions): SandboxCapability;

package/dist/sandbox/sandbox.js

@@ -1,92 +0,0 @@
-import { SANDBOX_DEFERRED_FIELDS, SANDBOX_FIELDS, SANDBOX_INSTRUCTIONS, SANDBOX_NETWORK_PRESETS, createSandboxTools, isSandboxHostPattern, parseSandboxDuration, parseSandboxSize, } from "@nylorun/core/define";
-export class SandboxError extends Error {
-    code;
-    constructor(code, message) {
-        super(message);
-        this.name = "SandboxError";
-        this.code = code;
-    }
-}
-/**
- * Give the agent an isolated Linux machine with a persistent `/workspace`.
- *
- * Adds the built-in `bash`, `read`, `write`, `edit`, `grep` and `glob` tools. They run in the
- * Nylorun Runtime, which picks the backend. Agent code declares requirements only.
- *
- * ```ts
- * Agent({ id: "analyst", instructions: "..." }).use(sandbox())
- * Agent({ ... }).use(sandbox({ image: "node:24", network: { allow: ["api.github.com"] } }))
- * ```
- */
-export function sandbox(options = {}, capability = {}) {
-    const id = capability.id ?? "sandbox";
-    if (!isRecord(options))
-        throw new SandboxError("sandbox.invalid", "sandbox() expects an options object");
-    for (const key of Object.keys(options)) {
-        if (SANDBOX_DEFERRED_FIELDS.includes(key))
-            throw new SandboxError("sandbox.unsupported", `sandbox({ ${key} }) is not supported in this version. ` +
-                `Supported options: ${SANDBOX_FIELDS.join(", ")}. See docs/design/sandboxes.md for what is planned.`);
-        if (!SANDBOX_FIELDS.includes(key))
-            throw new SandboxError("sandbox.unknown-option", `Unknown sandbox option '${key}'. Supported options: ${SANDBOX_FIELDS.join(", ")}`);
-    }
-    return Object.freeze({
-        id,
-        instructions: Object.freeze([SANDBOX_INSTRUCTIONS]),
-        tools: createSandboxTools(),
-        sandbox: freezeOptions(options),
-    });
-}
-function freezeOptions(options) {
-    const result = {};
-    if (options.image !== undefined) {
-        if (typeof options.image !== "string" || options.image.trim().length === 0)
-            throw new SandboxError("sandbox.invalid-image", "sandbox({ image }) must be a non-empty OCI image reference");
-        result.image = options.image;
-    }
-    if (options.network !== undefined) {
-        if (!isRecord(options.network))
-            throw new SandboxError("sandbox.invalid-network", "sandbox({ network }) must be an object");
-        for (const key of Object.keys(options.network))
-            if (key !== "preset" && key !== "allow")
-                throw new SandboxError("sandbox.invalid-network", `Unknown network option '${key}'. Use preset and allow.`);
-        const { preset, allow } = options.network;
-        if (preset !== undefined && !SANDBOX_NETWORK_PRESETS.includes(preset))
-            throw new SandboxError("sandbox.invalid-network", `network.preset must be one of ${SANDBOX_NETWORK_PRESETS.join(", ")}`);
-        if (allow !== undefined) {
-            if (!Array.isArray(allow))
-                throw new SandboxError("sandbox.invalid-network", "network.allow must be an array of host names");
-            for (const host of allow)
-                if (typeof host !== "string" || !isSandboxHostPattern(host))
-                    throw new SandboxError("sandbox.invalid-network", `network.allow entry '${String(host)}' must be a host name such as api.github.com or *.example.com (no scheme, port or path)`);
-        }
-        result.network = Object.freeze({
-            ...(preset === undefined ? {} : { preset: preset }),
-            ...(allow === undefined ? {} : { allow: Object.freeze([...allow]) }),
-        });
-    }
-    if (options.resources !== undefined) {
-        if (!isRecord(options.resources))
-            throw new SandboxError("sandbox.invalid-resources", "sandbox({ resources }) must be an object");
-        for (const key of Object.keys(options.resources))
-            if (key !== "cpus" && key !== "memory")
-                throw new SandboxError("sandbox.invalid-resources", `resources.${key} is not supported in this version. Use cpus and memory.`);
-        const { cpus, memory } = options.resources;
-        if (cpus !== undefined && (!Number.isInteger(cpus) || cpus < 1 || cpus > 64))
-            throw new SandboxError("sandbox.invalid-resources", "resources.cpus must be an integer from 1 to 64");
-        if (memory !== undefined && (typeof memory !== "string" || parseSandboxSize(memory) === undefined))
-            throw new SandboxError("sandbox.invalid-resources", "resources.memory must be a size such as 512MiB or 2GiB");
-        result.resources = Object.freeze({
-            ...(cpus === undefined ? {} : { cpus }),
-            ...(memory === undefined ? {} : { memory }),
-        });
-    }
-    if (options.idle !== undefined) {
-        if (typeof options.idle !== "string" || parseSandboxDuration(options.idle) === undefined)
-            throw new SandboxError("sandbox.invalid-idle", "sandbox({ idle }) must be a duration such as 30s, 15m or 1h");
-        result.idle = options.idle;
-    }
-    return Object.freeze(result);
-}
-function isRecord(value) {
-    return !!value && typeof value === "object" && !Array.isArray(value);
-}