@nylorun/agents 0.4.0-beta → 0.5.0-beta

package/CHANGELOG.md

@@ -1,5 +1,19 @@
 # @nylorun/agents
 
+## 0.5.0-beta
+
+### Minor Changes
+
+- 1cd7dc7: Add subagents: put an agent in another agent's `tools` (`Agent({ tools: [lookupOrder, researcher] })` or `.use({ tools: [researcher] })`) and the model can delegate to it. The tool is named after the agent's id, takes `{ task: string }`, and its description is the agent's `description`, which is now required for an agent used as a tool. The engine runs the child inside the parent's turn as a durable branch: fresh context, its own tools and hooks served by the root agent's executor, its own MCP servers, the session's sandbox, and only its final output (or `outputSchema` result) returned. Empty output, failures (with partial output marked as evidence), and requests for input or approval inside a child reach the parent as failed tool results. Parallel delegation calls run concurrently, completed child work is never re-run on replay, and cancelling the session cancels every child.
+
+  v1 is one level deep and non-interactive. Nested delegation, child tools that declare `approval`, and differing sandboxes across the tree fail the build with a named diagnostic. The manifest adds an optional `agent` body on a tool (schema version unchanged), actions and effects carry `agent: { id, path, delegationId }`, tool context gains `ctx.agent`, the durable host resolves a new `delegation` effect kind, and the Runtime emits `delegation.started` / `delegation.completed` events and filters history with `?agent=` (`session.history({ agent })`). Studio shows delegations, labels child actions with their agent, and filters events by agent.
+
+### Patch Changes
+
+- Pin core to the tested release.
+- Updated dependencies [1cd7dc7]
+  - @nylorun/core@0.4.0-beta
+
 ## 0.4.0-beta
 
 ### Minor Changes

package/README.md

@@ -110,6 +110,31 @@ The model gets `bash`, `read`, `write`, `edit`, `grep` and `glob` on a Linux mac
 
 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`, `scope`, ...) throw a `SandboxError` that says so. See [the sandbox design](../docs/design/sandboxes.md).
 
+Put an agent in another agent's `tools` to let the model delegate to it:
+
+```ts
+import { Agent } from "@nylorun/agents";
+import { z } from "zod";
+
+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()) }),
+});
+
+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],
+});
+```
+
+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.
+
 Use `session.observe({ cursor, signal })` for resumable canonical events, `session.inspect()` for waiting/uncertain state, and `approve`, `respond`, or `cancel` with an explicit stable idempotency key. Retry the same semantic command with the same key. `ownerUserId` must come from trusted server authentication. Application credentials are not browser credentials; browser applications need an authorized backend. Definition authoring is browser-bundleable.
 
 The Runtime destination is explicit, or defaults from `NYLORUN_RUNTIME_URL`. Application and executor keys default from `NYLORUN_SERVER_KEY` and `NYLORUN_EXECUTOR_KEY`. Implementation version defaults from `NYLORUN_IMPLEMENTATION_VERSION`, then `dev`. A host must provision executor scope for the agent id. Agents do not hash the manifest, and an in-flight action stays claimable after the registered digest changes. Model selection and model credentials belong to the Runtime.

package/dist/client.d.ts

@@ -153,8 +153,10 @@ export declare class SessionClient {
         cursor: string | null;
         requestId: string;
     }>;
+    /** `agent` narrows to one agent used as a tool: its delegationId or its path. */
     history(options?: {
         cursor?: string;
+        agent?: string;
         signal?: AbortSignal;
     }): Promise<{
         items: {

package/dist/client.js

@@ -1,21 +1,30 @@
+import { delegateOf } from "@nylorun/core/define";
 import { LiveEventSchema, SessionItemsResponseSchema, } from "@nylorun/core/contracts";
 import { Transport, id, segment } from "./http.js";
 import { observeSSE } from "./sse.js";
 const middlewareClosure = "Hosted definitions support declarative capabilities and before/after hooks, not middleware closures";
-function pluginRootsOf(agent) {
+/** The agent's declarations, then those of each agent it uses as a tool, keyed `<child>/<capability>`. */
+function declarationsOf(agent) {
     const built = agent.build?.() ?? agent;
-    const declarations = built.getBinding?.().declarations ?? [];
+    const binding = built.getBinding?.();
+    const found = (binding?.declarations ?? []).map((item) => ({ key: item.id, item }));
+    for (const tool of binding?.tools ?? []) {
+        const child = delegateOf(tool)?.agent;
+        for (const item of child?.getBinding().declarations ?? [])
+            found.push({ key: `${child.id}/${item.id}`, item });
+    }
+    return found;
+}
+function pluginRootsOf(agent) {
     const roots = {};
-    for (const item of declarations) {
+    for (const { key, item } of declarationsOf(agent))
         if (item.pluginRoot)
-            roots[item.id] = item.pluginRoot;
-    }
+            roots[key] = item.pluginRoot;
     return Object.keys(roots).length === 0 ? undefined : roots;
 }
 /** Closures stay on the live binding. The published manifest cannot name them. */
 export function assertNoMiddlewareClosures(agent) {
-    const built = agent.build?.() ?? agent;
-    if (built.getBinding?.().declarations.some((item) => item.hasMiddleware))
+    if (declarationsOf(agent).some(({ item }) => item.hasMiddleware))
         throw new Error(middlewareClosure);
 }
 export class AgentsClient {
@@ -152,8 +161,15 @@ export class SessionClient {
             ...(options.reason ? { reason: options.reason } : {}),
         }, options.signal);
     }
+    /** `agent` narrows to one agent used as a tool: its delegationId or its path. */
     async history(options = {}) {
-        return SessionItemsResponseSchema.parse(await this.transport.json(`${this.path}/items${options.cursor ? `?cursor=${encodeURIComponent(options.cursor)}` : ""}`, "GET", undefined, options.signal));
+        const query = new URLSearchParams();
+        if (options.cursor)
+            query.set("cursor", options.cursor);
+        if (options.agent)
+            query.set("agent", options.agent);
+        const search = query.toString();
+        return SessionItemsResponseSchema.parse(await this.transport.json(`${this.path}/items${search ? `?${search}` : ""}`, "GET", undefined, options.signal));
     }
     async *observe(options = {}) {
         for await (const frame of observeSSE(this.transport, `${this.path}/events`, options)) {

package/dist/execute-action.d.ts

@@ -1,4 +1,4 @@
 import { type BuiltAgent } from "@nylorun/core/define";
 import type { Action, ActionOutcome } from "@nylorun/core/contracts";
 /** Executes code only after a host-issued claim. No engine dependency. */
-export declare function executeAction(action: Action, agent: BuiltAgent, signal: AbortSignal): Promise<ActionOutcome>;
+export declare function executeAction(action: Action, root: BuiltAgent, signal: AbortSignal): Promise<ActionOutcome>;

package/dist/execute-action.js

@@ -1,4 +1,4 @@
-import { implementationsFor, isToolError, normalizeToolDefinition, normalizedSchemasFor, runHookPoint, } from "@nylorun/core/define";
+import { delegateOf, implementationsFor, isToolError, normalizeToolDefinition, normalizedSchemasFor, runHookPoint, } from "@nylorun/core/define";
 class Suspend {
     outcome;
     constructor(outcome) {
@@ -9,7 +9,10 @@ const object = (value) => value !== null && typeof value === "object" && !Array.
     ? value
     : {};
 /** Executes code only after a host-issued claim. No engine dependency. */
-export async function executeAction(action, agent, signal) {
+export async function executeAction(action, root, signal) {
+    // Work for an agent used as a tool runs that agent's code, served from the root's binding.
+    const agent = action.agent ? delegatedAgent(root, action.agent.id) : root;
+    const ref = action.agent ?? { id: root.id, path: root.id };
     if (action.kind === "hook")
         // All capabilities at this hook point run concurrently in one action. Never throws.
         return {
@@ -77,6 +80,7 @@ export async function executeAction(action, agent, signal) {
         signal,
         info: ctx.info,
         session: { id: action.sessionId },
+        agent: ref,
         ...(ctx.resume ? { resume: ctx.resume } : {}),
         state: {
             get: (key) => state[key],
@@ -170,6 +174,14 @@ export async function executeAction(action, agent, signal) {
         };
     }
 }
+function delegatedAgent(root, id) {
+    for (const capability of Object.values(implementationsFor(root))) {
+        const child = delegateOf(capability.tools?.[id])?.agent;
+        if (child)
+            return child;
+    }
+    throw new Error(`Agent '${root.id}' does not use '${id}' as a tool`);
+}
 function message(error) {
     return error instanceof Error ? error.message : String(error);
 }

package/package.json

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