@nylorun/runtime 0.8.0-beta → 0.9.0-beta

package/CHANGELOG.md

@@ -1,5 +1,22 @@
 # Changelog
 
+## 0.9.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.
+- Pin harness to the tested release.
+- Updated dependencies [1cd7dc7]
+- Updated dependencies
+  - @nylorun/core@0.4.0-beta
+  - @nylorun/harness@0.18.0-beta
+
 ## 0.8.0-beta
 
 ### Minor Changes

package/dist/core/runtime.js

@@ -7,7 +7,7 @@ import { tmpdir } from "node:os";
 import { AgentManifestSchema, CreateCredentialRequestSchema, CreateVaultRequestSchema, PutAgentRequestSchema, PutHostModelRequestSchema, SelectHostModelRequestSchema, PutSessionRequestSchema, RegisterExecutorsRequestSchema, RotateCredentialRequestSchema, SessionCommandSchema, ActionClaimRequestSchema, ActionHeartbeatRequestSchema, } from "@nylorun/core/contracts";
 import { createDurableCheckpoint, runDurable, } from "@nylorun/harness/run";
 import { hashManifest } from "@nylorun/core/compatibility";
-import { schemaFromJSON, } from "@nylorun/core/define";
+import { delegateManifest, schemaFromJSON, } from "@nylorun/core/define";
 import { Store, canonical } from "./store.js";
 import { ExecutorRegistry, assertExecutorCredential, hashToken, } from "./executors.js";
 import { RUNTIME_VERSION } from "../version.js";
@@ -18,7 +18,7 @@ import { scrub } from "../redact.js";
 import { createKekFile, defaultKekPath, readVaultKek } from "../vault/kek.js";
 import { VaultError } from "../vault/error.js";
 import { VaultService } from "../vault/service.js";
-import { McpPool } from "../mcp/pool.js";
+import { McpPool, serversOf } from "../mcp/pool.js";
 import { SandboxManager, sandboxCapabilityOf } from "../sandbox/manager.js";
 import { defaultSandboxBackends } from "../sandbox/select.js";
 class HttpError extends Error {
@@ -35,6 +35,7 @@ function sessionToolsOf(snapshot) {
     if (!snapshot?.mcpTools.length)
         return undefined;
     return snapshot.mcpTools.map((tool) => ({
+        ...(tool.agentId === undefined ? {} : { agentId: tool.agentId }),
         capabilityId: tool.capabilityId,
         name: tool.name,
         ...(tool.description === undefined
@@ -46,8 +47,14 @@ function sessionToolsOf(snapshot) {
             : { outputSchema: tool.outputSchema }),
     }));
 }
-function mcpToolOf(session, capabilityId, toolName) {
-    return session.mcpSnapshot?.mcpTools.find((tool) => tool.capabilityId === capabilityId && tool.name === toolName);
+function mcpToolOf(session, request) {
+    return session.mcpSnapshot?.mcpTools.find((tool) => tool.agentId === request.agent?.id &&
+        tool.capabilityId === request.capabilityId &&
+        tool.name === request.toolName);
+}
+/** The manifest of the agent an effect belongs to: the root, or an agent it uses as a tool. */
+function manifestFor(manifest, agent) {
+    return agent ? delegateManifest(manifest, agent.id) : manifest;
 }
 function pinnedTool(manifest, capabilityId, toolName) {
     const capability = manifest.capabilities.find((item) => item.id === capabilityId);
@@ -351,6 +358,7 @@ export class CoreRuntime {
                         this.store.put("sessions", s.id, s);
                         events.push(this.store.event(s.id, s.activeTurnId, "action.uncertain", {
                             actionId: action.actionId,
+                            ...(action.agent ? { agent: action.agent } : {}),
                         }));
                     }
                 }
@@ -509,11 +517,24 @@ export class CoreRuntime {
                             : "pending",
                     };
             }
-            const mcpTool = request.kind === "tool"
-                ? mcpToolOf(s, request.capabilityId, request.toolName)
-                : undefined;
+            if (request.kind === "delegation") {
+                // Lifecycle points of an agent used as a tool: journaled once, so replays never re-emit.
+                const outcome = { value: null };
+                this.store.put("effects", request.effectId, {
+                    request,
+                    status: "completed",
+                    outcome,
+                });
+                const settled = request.effectId.endsWith(":settled");
+                event = this.store.event(s.id, s.activeTurnId, settled ? "delegation.completed" : "delegation.started", { agent: request.agent, ...request.input });
+                return { status: "completed", outcome };
+            }
+            const agentManifest = manifestFor(s.manifest, request.agent);
+            if (!agentManifest)
+                throw new Error(`Agent '${request.agent?.id ?? ""}' is not used as a tool`);
+            const mcpTool = request.kind === "tool" ? mcpToolOf(s, request) : undefined;
             const sandboxTool = request.kind === "tool" && !mcpTool
-                ? sandboxCapabilityOf(s.manifest, request.capabilityId, request.toolName)
+                ? sandboxCapabilityOf(agentManifest, request.capabilityId, request.toolName)
                 : undefined;
             this.store.put("effects", request.effectId, {
                 request,
@@ -526,7 +547,7 @@ export class CoreRuntime {
                 return undefined;
             }
             const tool = request.kind === "tool"
-                ? pinnedTool(s.manifest, request.capabilityId, request.toolName)
+                ? pinnedTool(agentManifest, request.capabilityId, request.toolName)
                 : undefined;
             const base = {
                 actionId: request.effectId,
@@ -541,6 +562,7 @@ export class CoreRuntime {
                 generation: 0,
                 claimId: null,
                 leaseExpiresAt: null,
+                ...(request.agent ? { agent: request.agent } : {}),
             };
             const action = request.kind === "hook"
                 ? {
@@ -907,7 +929,11 @@ export class CoreRuntime {
                         action.claimId = randomUUID();
                         action.leaseExpiresAt = new Date(Date.now() + (this.options.leaseMs ?? 30000)).toISOString();
                         this.store.put("actions", actionId, action);
-                        event = this.store.event(action.sessionId, action.turnId, "action.claimed", { actionId, generation: action.generation });
+                        event = this.store.event(action.sessionId, action.turnId, "action.claimed", {
+                            actionId,
+                            generation: action.generation,
+                            ...(action.agent ? { agent: action.agent } : {}),
+                        });
                         return {
                             action,
                             claimId: action.claimId,
@@ -1127,7 +1153,7 @@ export class CoreRuntime {
                         ? request.headers["last-event-id"]
                         : undefined);
                 if (method === "GET" && path[3] === "items")
-                    return json(this.store.history(id, cursor));
+                    return json(this.store.history(id, cursor, url.searchParams.get("agent") ?? undefined));
                 if (method === "GET" && path[3] === "events") {
                     const history = this.store.history(id, cursor);
                     const set = this.observers.get(id) ?? new Set();
@@ -1199,9 +1225,7 @@ export class CoreRuntime {
     }
     async prepareMcp(id, signal) {
         const s = this.session(id);
-        const declared = s.manifest.capabilities.some((capability) => capability.mcpServers !== undefined &&
-            Object.keys(capability.mcpServers).length > 0);
-        if (!declared)
+        if (serversOf(s.manifest).length === 0)
             return;
         if (!s.mcpSnapshot) {
             const found = await this.mcp.discover({
@@ -1247,11 +1271,12 @@ export class CoreRuntime {
     }
     async callMcpTool(request) {
         const s = this.session(request.sessionId);
-        const tool = mcpToolOf(s, request.capabilityId, request.toolName);
+        const tool = mcpToolOf(s, request);
         if (!tool)
             throw new Error(`MCP tool '${request.toolName ?? ""}' is not in the session snapshot`);
         return this.mcp.call({
             sessionId: s.id,
+            ...(tool.agentId === undefined ? {} : { agentId: tool.agentId }),
             capabilityId: tool.capabilityId,
             serverName: tool.serverName,
             serverToolName: tool.serverToolName,
@@ -1262,7 +1287,8 @@ export class CoreRuntime {
     }
     async callSandboxTool(request, signal) {
         const s = this.session(request.sessionId);
-        const capability = sandboxCapabilityOf(s.manifest, request.capabilityId, request.toolName);
+        // Agents used as tools share the session's sandbox; the tree declares one sandbox spec.
+        const capability = sandboxCapabilityOf(manifestFor(s.manifest, request.agent), request.capabilityId, request.toolName);
         if (!capability)
             throw new Error(`'${request.toolName ?? ""}' is not a sandbox tool`);
         return this.sandbox.run({ id: s.id, activeTurnId: s.activeTurnId, manifest: s.manifest }, capability, request.toolName, request.input, signal);
@@ -1414,5 +1440,8 @@ export async function startRuntime(options) {
 }
 /** What an action runs, for events: a tool name, or a hook point and its capabilities. */
 function actionTarget(action) {
-    return action.kind === "hook" ? { hook: action.hook } : { toolName: action.toolName };
+    return {
+        ...(action.kind === "hook" ? { hook: action.hook } : { toolName: action.toolName }),
+        ...(action.agent ? { agent: action.agent } : {}),
+    };
 }

package/dist/core/store.d.ts

@@ -22,7 +22,8 @@ export declare class Store {
     deleteExecutor(agentId: string): void;
     event(sessionId: string, turnId: string | null, type: string, payload: unknown): LiveEvent;
     credentialCount(): number;
-    history(sessionId: string, cursor?: string): {
+    /** `agent` keeps only events of one agent used as a tool, by delegationId or path. */
+    history(sessionId: string, cursor?: string, agent?: string): {
         items: LiveEvent[];
         cursor: string | null;
     };

package/dist/core/store.js

@@ -164,7 +164,8 @@ export class Store {
             .get();
         return Number(row.n);
     }
-    history(sessionId, cursor) {
+    /** `agent` keeps only events of one agent used as a tool, by delegationId or path. */
+    history(sessionId, cursor, agent) {
         let sequence = 0;
         if (cursor) {
             const decoded = Buffer.from(cursor, "base64url").toString();
@@ -177,7 +178,8 @@ export class Store {
         const items = this.db
             .prepare("SELECT body FROM events WHERE session_id=? AND sequence>? ORDER BY sequence")
             .all(sessionId, sequence)
-            .map((r) => JSON.parse(String(r.body)));
+            .map((r) => JSON.parse(String(r.body)))
+            .filter((event) => agent === undefined || belongsTo(event, agent));
         const last = this.db
             .prepare("SELECT body FROM events WHERE session_id=? ORDER BY sequence DESC LIMIT 1")
             .get(sessionId);
@@ -187,6 +189,11 @@ export class Store {
         };
     }
 }
+function belongsTo(event, agent) {
+    const ref = event.payload
+        ?.agent;
+    return ref?.delegationId === agent || ref?.path === agent;
+}
 function migrateVaultScope(db) {
     const columns = db.prepare("PRAGMA table_info(vaults)").all();
     if (!columns.some((column) => column.name === "scope"))

package/dist/mcp/pool.d.ts

@@ -1,4 +1,4 @@
-import type { AgentManifest } from "@nylorun/core/define";
+import type { AgentManifest, McpServerManifest } from "@nylorun/core/define";
 import type { AuthorizeResult } from "../vault/service.js";
 import { callMcpTool } from "./connect.js";
 import { type McpDiagnostic, type McpSnapshot, type McpToolRecord } from "./snapshot.js";
@@ -31,6 +31,7 @@ export declare class McpPool {
     }): Promise<McpDiagnostic[]>;
     call(input: {
         sessionId: string;
+        agentId?: string;
         capabilityId: string;
         serverName: string;
         serverToolName: string;
@@ -43,3 +44,14 @@ export declare class McpPool {
     private liveKey;
     private connectDeclared;
 }
+interface DeclaredServer {
+    /** Absent for the session's root agent. */
+    readonly agentId?: string;
+    /** The manifest of the agent that declares the server. */
+    readonly manifest: AgentManifest;
+    readonly capabilityId: string;
+    readonly server: McpServerManifest;
+}
+/** Servers of the root agent, then of each agent it uses as a tool. */
+export declare function serversOf(manifest: AgentManifest): DeclaredServer[];
+export {};

package/dist/mcp/pool.js

@@ -1,4 +1,5 @@
 import { join } from "node:path";
+import { delegatesOf } from "@nylorun/core/define";
 import { callMcpTool, diagnosticFromError, listMcpTools, openMcpServer, } from "./connect.js";
 import { declaredToolNames, } from "./snapshot.js";
 export class McpPool {
@@ -8,7 +9,8 @@ export class McpPool {
         this.options = options;
     }
     async discover(input) {
-        const taken = declaredToolNames(input.manifest);
+        // Each agent names its own tools, so collisions are checked per agent.
+        const taken = new Map();
         const tools = [];
         const diagnostics = [];
         for (const declared of serversOf(input.manifest)) {
@@ -19,13 +21,16 @@ export class McpPool {
                 continue;
             }
             try {
+                if (!taken.has(declared.agentId))
+                    taken.set(declared.agentId, declaredToolNames(declared.manifest));
                 const listed = await listMcpTools(opened.connection.client, {
                     capabilityId: declared.capabilityId,
                     serverName: declared.server.name,
-                    taken,
+                    taken: taken.get(declared.agentId),
                 });
-                tools.push(...listed.tools);
+                tools.push(...listed.tools.map((tool) => owned(declared, tool)));
                 diagnostics.push({
+                    ...ownerOf(declared),
                     capabilityId: declared.capabilityId,
                     serverName: declared.server.name,
                     outcome: "connected",
@@ -37,7 +42,7 @@ export class McpPool {
             }
             catch (error) {
                 await opened.connection.close().catch(() => { });
-                diagnostics.push(diagnosticFromError(declared.capabilityId, declared.server.name, error));
+                diagnostics.push(owned(declared, diagnosticFromError(declared.capabilityId, declared.server.name, error)));
             }
         }
         return {
@@ -53,16 +58,17 @@ export class McpPool {
         const diagnostics = [];
         const seen = new Set();
         for (const tool of input.tools) {
-            const key = `${tool.capabilityId}\0${tool.serverName}`;
+            const key = this.liveKey(input.sessionId, tool.agentId, tool.capabilityId, tool.serverName);
             if (seen.has(key))
                 continue;
             seen.add(key);
-            if (this.live.has(this.liveKey(input.sessionId, tool.capabilityId, tool.serverName)))
+            if (this.live.has(key))
                 continue;
             input.signal?.throwIfAborted();
-            const declared = serversOf(input.manifest).find((item) => item.capabilityId === tool.capabilityId && item.server.name === tool.serverName);
+            const declared = findServer(input.manifest, tool.agentId, tool.capabilityId, tool.serverName);
             if (!declared) {
                 diagnostics.push({
+                    ...(tool.agentId === undefined ? {} : { agentId: tool.agentId }),
                     capabilityId: tool.capabilityId,
                     serverName: tool.serverName,
                     outcome: "failed",
@@ -80,10 +86,10 @@ export class McpPool {
         return diagnostics;
     }
     async call(input) {
-        const key = this.liveKey(input.sessionId, input.capabilityId, input.serverName);
+        const key = this.liveKey(input.sessionId, input.agentId, input.capabilityId, input.serverName);
         let live = this.live.get(key);
         if (!live) {
-            const declared = serversOf(input.manifest).find((item) => item.capabilityId === input.capabilityId && item.server.name === input.serverName);
+            const declared = findServer(input.manifest, input.agentId, input.capabilityId, input.serverName);
             if (!declared)
                 throw new Error(`MCP server '${input.serverName}' is not declared`);
             const opened = await this.connectDeclared(input, declared);
@@ -102,21 +108,21 @@ export class McpPool {
         await Promise.all(connections.map((item) => item.connection.close().catch(() => { })));
     }
     remember(sessionId, declared, connection) {
-        this.live.set(this.liveKey(sessionId, declared.capabilityId, declared.server.name), {
+        this.live.set(this.liveKey(sessionId, declared.agentId, declared.capabilityId, declared.server.name), {
             capabilityId: declared.capabilityId,
             serverName: declared.server.name,
             connection,
         });
     }
-    liveKey(sessionId, capabilityId, serverName) {
-        return JSON.stringify([sessionId, capabilityId, serverName]);
+    liveKey(sessionId, agentId, capabilityId, serverName) {
+        return JSON.stringify([sessionId, agentId ?? null, capabilityId, serverName]);
     }
     async connectDeclared(input, declared) {
         try {
             const connection = await openMcpServer({
                 server: declared.server,
-                pluginRoot: input.pluginRoots[declared.capabilityId],
-                pluginData: join(this.options.dataDir, "plugin-data", declared.capabilityId),
+                pluginRoot: input.pluginRoots[pluginKey(declared)],
+                pluginData: join(this.options.dataDir, "plugin-data", ...pluginKey(declared).split("/")),
                 authorize: declared.server.type === "stdio"
                     ? undefined
                     : (url) => this.options.authorize(input.sessionId, {
@@ -129,15 +135,43 @@ export class McpPool {
         catch (error) {
             return {
                 ok: false,
-                diagnostic: diagnosticFromError(declared.capabilityId, declared.server.name, error),
+                diagnostic: owned(declared, diagnosticFromError(declared.capabilityId, declared.server.name, error)),
             };
         }
     }
 }
-function serversOf(manifest) {
+/** Servers of the root agent, then of each agent it uses as a tool. */
+export function serversOf(manifest) {
     const servers = [];
-    for (const capability of manifest.capabilities)
-        for (const server of Object.values(capability.mcpServers ?? {}))
-            servers.push({ capabilityId: capability.id, server });
+    const add = (agent, agentId) => {
+        for (const capability of agent.capabilities)
+            for (const server of Object.values(capability.mcpServers ?? {}))
+                servers.push({
+                    ...(agentId === undefined ? {} : { agentId }),
+                    manifest: agent,
+                    capabilityId: capability.id,
+                    server,
+                });
+    };
+    add(manifest);
+    for (const child of delegatesOf(manifest))
+        add(child.manifest, child.manifest.id);
     return servers;
 }
+function findServer(manifest, agentId, capabilityId, serverName) {
+    return serversOf(manifest).find((item) => item.agentId === agentId &&
+        item.capabilityId === capabilityId &&
+        item.server.name === serverName);
+}
+/** Plugin roots of agents used as tools are registered as `<agent>/<capability>`. */
+function pluginKey(declared) {
+    return declared.agentId === undefined
+        ? declared.capabilityId
+        : `${declared.agentId}/${declared.capabilityId}`;
+}
+function ownerOf(declared) {
+    return declared.agentId === undefined ? {} : { agentId: declared.agentId };
+}
+function owned(declared, value) {
+    return { ...ownerOf(declared), ...value };
+}

package/dist/mcp/snapshot.d.ts

@@ -1,6 +1,8 @@
 import type { JsonObject } from "@nylorun/core/define";
 import type { AgentManifest } from "@nylorun/core/define";
 export interface McpToolRecord {
+    /** The agent used as a tool that declares the server; absent for the session's root agent. */
+    readonly agentId?: string;
     readonly capabilityId: string;
     readonly serverName: string;
     readonly serverToolName: string;
@@ -15,6 +17,8 @@ export interface McpSnapshot {
     readonly mcpTools: readonly McpToolRecord[];
 }
 export interface McpDiagnostic {
+    /** The agent used as a tool that declares the server; absent for the session's root agent. */
+    readonly agentId?: string;
     readonly capabilityId: string;
     readonly serverName: string;
     readonly outcome: "connected" | "refused" | "failed";

package/dist/version.d.ts

@@ -1 +1 @@
-export declare const RUNTIME_VERSION = "0.8.0-beta";
+export declare const RUNTIME_VERSION = "0.9.0-beta";

package/dist/version.js

@@ -1,3 +1,3 @@
 // Kept in step with package.json by runtime/scripts/check-package.mjs, which runs in npm run check.
 // release:prepare also rewrites this when it bumps @nylorun/runtime.
-export const RUNTIME_VERSION = "0.8.0-beta";
+export const RUNTIME_VERSION = "0.9.0-beta";

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@nylorun/runtime",
-  "version": "0.8.0-beta",
+  "version": "0.9.0-beta",
   "description": "SQLite agent execution host and model providers.",
   "type": "module",
   "license": "Apache-2.0",
@@ -55,8 +55,8 @@
     "@modelcontextprotocol/sdk": "^1.30.0",
     "@earendil-works/pi-ai": "0.85.1",
     "@hono/node-server": "^2.1.1",
-    "@nylorun/harness": "0.17.0-beta",
-    "@nylorun/core": "0.3.0-beta",
+    "@nylorun/harness": "0.18.0-beta",
+    "@nylorun/core": "0.4.0-beta",
     "just-bash": "3.4.2"
   },
   "optionalDependencies": {