@nebutra/agent-runtime 0.2.1 → 2.0.0

package/README.md

@@ -1,13 +1,19 @@
 # @nebutra/agent-runtime
 
-Status: **WIP**
+Status: **WIP** — Track A live (grammar + gateway demo); Track B Phase 1 docked
 
-> Status: WIP — not yet integrated into a production app. Track-B kernel
-> transport and durable-turn queue binding are interface-only.
+| Layer | State |
+|-------|--------|
+| Track A grammar (`runTurn`, policy, rollout, tools) | Shipped; gateway demo route behind `agent-runtime-demo` |
+| Track B adapter (`createCarinaSandbox` → Carina JSON-RPC) | **Phase 1 done** ([#382](https://github.com/Nebutra/Nebutra-Sailor/pull/382)) |
+| Track B host wire (env, ensureSession, `command_exec`, gateway bundle) | **Phase 2a done** (#386) |
+| Track B ship (workspace map, approval resolve, auto-approve, status) | **Phase 2b done** |
+| Product HITL UI (beyond API) | Optional |
+| Default without Carina endpoint | **Fail-closed** (`REFUSING_SANDBOX`) |
 
 Multi-tenant **agent-runtime grammar**. A faithful re-expression of a terminal
 coding-agent's runtime *design* into Sailor's grammar — TypeScript,
-multi-tenant, zero infra changes, **no in-process untrusted-code execution**.
+multi-tenant, zero in-process untrusted-code execution.
 
 ## Why this exists
 
@@ -24,9 +30,26 @@ them.
 
 - **Track A (this package)** — policy, protocol contract, model, rollout. All
   tenant-scoped. Runs inside Sailor's TS web runtime.
-- **Track B (decoupled, not this repo)** — an optional self-hosted isolator /
-  kernel sidecar that implements `ExternalSandbox` over the `./protocol`
-  contract. The protocol is the only coupling seam.
+- **Track B (Carina upstream)** — the **Nebutra/carina** kernel is the sole
+  product isolator. Self-deployed, local-first. Sailor docks via
+  `createCarinaSandbox` / `ExternalSandbox` — **kernel protocol is maintained
+  in Carina**, not reimplemented here.
+
+```ts
+import {
+  createCarinaSandbox,
+  REFUSING_SANDBOX,
+  type ExternalSandbox,
+} from "@nebutra/agent-runtime";
+
+// Production: only when a reachable Carina JSON-RPC base URL is configured.
+// Same-host co-deploy (default): unix socket /var/carina/run/daemon.sock
+import { resolveCarinaSandboxFromEnv } from "@nebutra/agent-runtime";
+const sandbox = resolveCarinaSandboxFromEnv();
+// Opt out: CARINA_CODEPLOY=0  |  optional HTTP: CARINA_JSONRPC_URL=…
+```
+
+See `docs/architecture/2026-08-03-carina-track-b-upstream.md`.
 
 ## Modules
 
@@ -37,16 +60,16 @@ them.
 | `./protocol` | JSON-RPC contract | method registry, **tenant+thread serialization scope**, server-initiated approval requests, notifications |
 | `./tools` | uniform tool/MCP | `ToolRegistry` (registry→router→hooks), `adaptMcpTool` (MCP-as-adapter) |
 | `./rollout` | event-sourced trace | append-only typed log, replay-to-state, compaction marker, per-item persistence policy |
-| `./sandbox` | external-sandbox seam | `ExternalSandbox` delegation interface; fail-closed `REFUSING_SANDBOX` default |
+| `./sandbox` | external-sandbox seam | `ExternalSandbox`; `createCarinaSandbox` (Track B); `REFUSING_SANDBOX` default; `createHttpSandbox` generic helper |
 | `./adapters/*` | reusable concrete bindings | MCP catalog, Web-standard SSE transport, and Prisma rollout persistence without a separate package |
 
 ## Non-negotiables enforced here
 
 - **Multi-tenant**: every scope, store key, and dispatch carries `tenantId`;
   cross-tenant requests can never share a serialization scope.
-- **No infra change**: no sandbox runtime, no new datastore — only interfaces.
 - **No in-process untrusted exec**: the default executor refuses; real
-  execution is delegated to a decoupled isolator.
+  execution is delegated to self-deployed Carina (or another `ExternalSandbox`).
+- **No second kernel**: OS sandbox / capability enforcement stay in Carina.
 
 See `docs/capabilities/agent-runtime/` for the capability map and replication
 guide.

package/dist/adapters/index.d.ts

@@ -1,12 +1,31 @@
+import { ModelInvoker } from '../loop.js';
 export { NotificationFrame, SseOptions, createRpcHandler, sseResponse, subscribeNotifications } from './dispatcher-sse.js';
 export { McpExecutorLike, McpRegistryLike, createMcpClientPort, createMcpServerCatalog } from './mcp-catalog.js';
 export { PrismaRolloutDelegate, RolloutDelegateResolver, createPrismaRolloutPersistence } from './prisma-rollout.js';
-import '../dispatcher.js';
-import '../protocol.js';
-import 'zod';
 import '../model.js';
+import '../policy.js';
+import 'zod';
+import '../protocol.js';
+import '../rollout.js';
+import '../tools.js';
+import '../dispatcher.js';
 import '@nebutra/mcp';
 import '../mcp-bridge.js';
-import '../tools.js';
 import '../rollout-store-persistent.js';
-import '../rollout.js';
+
+/**
+ * AgentsModelInvoker — the ONE bridge that makes the substrate's `runTurn` use
+ * the real provider stack. Implements `ModelInvoker` over @nebutra/agents
+ * `generateText` (which resolves the provider + model and runs the AI SDK).
+ * Each round sends the running history at the round's `config.model` — which is
+ * how a per-node model (resolved from a node's NodeModelSpec) reaches the
+ * provider.
+ *
+ * Tools are NOT passed here: the runtime's own ToolRegistry/loop owns tool
+ * dispatch; this round is a plain text completion. Errors propagate to the loop
+ * (which records them on the rollout), not swallowed.
+ */
+
+declare function createAgentsModelInvoker(): ModelInvoker;
+
+export { createAgentsModelInvoker };

package/dist/adapters/index.js

@@ -11,7 +11,34 @@ import {
   createPrismaRolloutPersistence
 } from "../chunk-57W3AR43.js";
 import "../chunk-424PT5DM.js";
+
+// src/adapters/agents-model-invoker.ts
+import { generateText } from "@nebutra/agents";
+function toRole(role) {
+  return role === "assistant" || role === "system" ? role : "user";
+}
+function createAgentsModelInvoker() {
+  return {
+    async invoke(request) {
+      const messages = request.history.map((m) => ({
+        role: toRole(m.role),
+        content: m.content
+      }));
+      const result = await generateText(messages, { model: request.config.model });
+      const text = result.text ?? "";
+      const usage = result.usage;
+      return {
+        emissions: text.length > 0 ? [{ kind: "text", text }] : [],
+        usage: {
+          inputTokens: usage?.inputTokens ?? 0,
+          outputTokens: usage?.outputTokens ?? 0
+        }
+      };
+    }
+  };
+}
 export {
+  createAgentsModelInvoker,
   createMcpClientPort,
   createMcpServerCatalog,
   createPrismaRolloutPersistence,

package/dist/adapters/index.js.map

@@ -1 +1 @@
-{"version":3,"sources":[],"sourcesContent":[],"mappings":"","names":[]}
+{"version":3,"sources":["../../src/adapters/agents-model-invoker.ts"],"sourcesContent":["/**\n * AgentsModelInvoker — the ONE bridge that makes the substrate's `runTurn` use\n * the real provider stack. Implements `ModelInvoker` over @nebutra/agents\n * `generateText` (which resolves the provider + model and runs the AI SDK).\n * Each round sends the running history at the round's `config.model` — which is\n * how a per-node model (resolved from a node's NodeModelSpec) reaches the\n * provider.\n *\n * Tools are NOT passed here: the runtime's own ToolRegistry/loop owns tool\n * dispatch; this round is a plain text completion. Errors propagate to the loop\n * (which records them on the rollout), not swallowed.\n */\n\nimport { generateText } from \"@nebutra/agents\";\nimport type { ModelInvoker, ModelRoundRequest, ModelRoundResult } from \"../loop\";\n\ntype Role = \"user\" | \"assistant\" | \"system\";\n\nfunction toRole(role: string): Role {\n  return role === \"assistant\" || role === \"system\" ? role : \"user\";\n}\n\nexport function createAgentsModelInvoker(): ModelInvoker {\n  return {\n    async invoke(request: ModelRoundRequest): Promise<ModelRoundResult> {\n      const messages = request.history.map((m) => ({\n        role: toRole(m.role),\n        content: m.content,\n      }));\n\n      const result = await generateText(messages, { model: request.config.model });\n\n      const text = result.text ?? \"\";\n      const usage = result.usage;\n      return {\n        emissions: text.length > 0 ? [{ kind: \"text\", text }] : [],\n        usage: {\n          inputTokens: usage?.inputTokens ?? 0,\n          outputTokens: usage?.outputTokens ?? 0,\n        },\n      };\n    },\n  };\n}\n"],"mappings":";;;;;;;;;;;;;;;AAaA,SAAS,oBAAoB;AAK7B,SAAS,OAAO,MAAoB;AAClC,SAAO,SAAS,eAAe,SAAS,WAAW,OAAO;AAC5D;AAEO,SAAS,2BAAyC;AACvD,SAAO;AAAA,IACL,MAAM,OAAO,SAAuD;AAClE,YAAM,WAAW,QAAQ,QAAQ,IAAI,CAAC,OAAO;AAAA,QAC3C,MAAM,OAAO,EAAE,IAAI;AAAA,QACnB,SAAS,EAAE;AAAA,MACb,EAAE;AAEF,YAAM,SAAS,MAAM,aAAa,UAAU,EAAE,OAAO,QAAQ,OAAO,MAAM,CAAC;AAE3E,YAAM,OAAO,OAAO,QAAQ;AAC5B,YAAM,QAAQ,OAAO;AACrB,aAAO;AAAA,QACL,WAAW,KAAK,SAAS,IAAI,CAAC,EAAE,MAAM,QAAQ,KAAK,CAAC,IAAI,CAAC;AAAA,QACzD,OAAO;AAAA,UACL,aAAa,OAAO,eAAe;AAAA,UACnC,cAAc,OAAO,gBAAgB;AAAA,QACvC;AAAA,MACF;AAAA,IACF;AAAA,EACF;AACF;","names":[]}

package/dist/{chunk-KCNN4QUQ.js → chunk-5UGIUYJR.js}

@@ -4,15 +4,15 @@ import {
 import {
   replay
 } from "./chunk-37BBB2P2.js";
-import {
-  RuntimeToolRegistry
-} from "./chunk-4Y25ZTKI.js";
 import {
   isTurnTerminal
 } from "./chunk-6EGG2OZC.js";
 import {
   DEFAULT_APPROVAL_POLICY
 } from "./chunk-CGRCUKGT.js";
+import {
+  RuntimeToolRegistry
+} from "./chunk-4Y25ZTKI.js";
 
 // src/pulsar.ts
 function newId(prefix) {
@@ -252,4 +252,4 @@ export {
   PulsarBuilder,
   Pulsar
 };
-//# sourceMappingURL=chunk-KCNN4QUQ.js.map
+//# sourceMappingURL=chunk-5UGIUYJR.js.map

package/dist/chunk-7ELA4SWE.js

@@ -0,0 +1,73 @@
+import {
+  isCarinaSandbox
+} from "./chunk-VXILZAXK.js";
+import {
+  DEFAULT_CAPABILITY_POLICY
+} from "./chunk-CGRCUKGT.js";
+import {
+  RuntimeToolRegistry
+} from "./chunk-4Y25ZTKI.js";
+
+// src/command-exec.ts
+import { z } from "zod";
+var COMMAND_EXEC_TOOL_NAME = "command_exec";
+var commandExecInputSchema = z.object({
+  command: z.string().min(1)
+});
+function registerCommandExecTool(registry, options) {
+  const {
+    sandbox,
+    workspaceRoot,
+    capabilityPolicy = DEFAULT_CAPABILITY_POLICY,
+    profile,
+    approvalMode
+  } = options;
+  registry.register(
+    {
+      name: COMMAND_EXEC_TOOL_NAME,
+      description: "Run a shell command in the external sandbox (Carina Track B). Never executes in the Sailor web process.",
+      inputSchema: commandExecInputSchema
+    },
+    async (input, ctx) => {
+      if (isCarinaSandbox(sandbox)) {
+        const root = workspaceRoot?.trim();
+        if (!root) {
+          throw new Error(
+            "command_exec: CARINA_WORKSPACE_ROOT / workspaceRoot required to create a Carina session before command.exec"
+          );
+        }
+        await sandbox.ensureSession({
+          threadId: ctx.threadId,
+          workspaceRoot: root,
+          tenantId: ctx.tenantId,
+          ...profile ? { profile } : {},
+          ...approvalMode ? { approvalMode } : {}
+        });
+      }
+      const result = await sandbox.exec({
+        tenantId: ctx.tenantId,
+        threadId: ctx.threadId,
+        command: input.command,
+        capabilityPolicy
+      });
+      return {
+        exitCode: result.exitCode,
+        aggregatedOutput: result.aggregatedOutput,
+        executedOn: result.executedOn,
+        ...result.decisionId !== void 0 ? { decisionId: result.decisionId } : {}
+      };
+    }
+  );
+}
+function buildSandboxToolRegistry(sandbox, options = {}) {
+  const registry = new RuntimeToolRegistry();
+  registerCommandExecTool(registry, { sandbox, ...options });
+  return registry;
+}
+
+export {
+  COMMAND_EXEC_TOOL_NAME,
+  registerCommandExecTool,
+  buildSandboxToolRegistry
+};
+//# sourceMappingURL=chunk-7ELA4SWE.js.map

package/dist/chunk-7ELA4SWE.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/command-exec.ts"],"sourcesContent":["/**\n * Native command-exec tool that delegates to {@link ExternalSandbox}.\n * Product Track B: pair with {@link createCarinaSandbox} + ensureSession.\n */\n\nimport { z } from \"zod\";\n\nimport { type CapabilityPolicy, DEFAULT_CAPABILITY_POLICY } from \"./policy\";\nimport { type ExternalSandbox, isCarinaSandbox, type SandboxExecResult } from \"./sandbox\";\nimport { RuntimeToolRegistry } from \"./tools\";\n\nexport const COMMAND_EXEC_TOOL_NAME = \"command_exec\" as const;\n\nconst commandExecInputSchema = z.object({\n  command: z.string().min(1),\n});\n\nexport type CommandExecToolInput = z.infer<typeof commandExecInputSchema>;\n\nexport type CommandExecToolOutput = {\n  readonly exitCode: number;\n  readonly aggregatedOutput: string;\n  readonly executedOn: string;\n  readonly decisionId?: string;\n};\n\nexport type RegisterCommandExecToolOptions = {\n  readonly sandbox: ExternalSandbox;\n  /**\n   * Absolute workspace on the Carina host. Required when sandbox is Carina\n   * (session.create). Gateway reads `CARINA_WORKSPACE_ROOT`.\n   */\n  readonly workspaceRoot?: string;\n  readonly capabilityPolicy?: CapabilityPolicy;\n  readonly profile?: string;\n  readonly approvalMode?: string;\n};\n\n/**\n * Register `command_exec` on a tool registry. For Carina sandboxes, ensures a\n * session for the turn thread before `command.exec`.\n */\nexport function registerCommandExecTool(\n  registry: RuntimeToolRegistry,\n  options: RegisterCommandExecToolOptions,\n): void {\n  const {\n    sandbox,\n    workspaceRoot,\n    capabilityPolicy = DEFAULT_CAPABILITY_POLICY,\n    profile,\n    approvalMode,\n  } = options;\n\n  registry.register(\n    {\n      name: COMMAND_EXEC_TOOL_NAME,\n      description:\n        \"Run a shell command in the external sandbox (Carina Track B). \" +\n        \"Never executes in the Sailor web process.\",\n      inputSchema: commandExecInputSchema,\n    },\n    async (input, ctx): Promise<CommandExecToolOutput> => {\n      if (isCarinaSandbox(sandbox)) {\n        const root = workspaceRoot?.trim();\n        if (!root) {\n          throw new Error(\n            \"command_exec: CARINA_WORKSPACE_ROOT / workspaceRoot required \" +\n              \"to create a Carina session before command.exec\",\n          );\n        }\n        await sandbox.ensureSession({\n          threadId: ctx.threadId,\n          workspaceRoot: root,\n          tenantId: ctx.tenantId,\n          ...(profile ? { profile } : {}),\n          ...(approvalMode ? { approvalMode } : {}),\n        });\n      }\n\n      const result: SandboxExecResult = await sandbox.exec({\n        tenantId: ctx.tenantId,\n        threadId: ctx.threadId,\n        command: input.command,\n        capabilityPolicy,\n      });\n\n      return {\n        exitCode: result.exitCode,\n        aggregatedOutput: result.aggregatedOutput,\n        executedOn: result.executedOn,\n        ...(result.decisionId !== undefined ? { decisionId: result.decisionId } : {}),\n      };\n    },\n  );\n}\n\n/**\n * Build a registry that includes `command_exec` delegated to the given sandbox.\n * Prefer this only when a real isolator is configured; with\n * {@link REFUSING_SANDBOX} the tool will throw NoExecutorConfiguredError on use.\n */\nexport function buildSandboxToolRegistry(\n  sandbox: ExternalSandbox,\n  options: Omit<RegisterCommandExecToolOptions, \"sandbox\"> = {},\n): RuntimeToolRegistry {\n  const registry = new RuntimeToolRegistry();\n  registerCommandExecTool(registry, { sandbox, ...options });\n  return registry;\n}\n"],"mappings":";;;;;;;;;;;AAKA,SAAS,SAAS;AAMX,IAAM,yBAAyB;AAEtC,IAAM,yBAAyB,EAAE,OAAO;AAAA,EACtC,SAAS,EAAE,OAAO,EAAE,IAAI,CAAC;AAC3B,CAAC;AA2BM,SAAS,wBACd,UACA,SACM;AACN,QAAM;AAAA,IACJ;AAAA,IACA;AAAA,IACA,mBAAmB;AAAA,IACnB;AAAA,IACA;AAAA,EACF,IAAI;AAEJ,WAAS;AAAA,IACP;AAAA,MACE,MAAM;AAAA,MACN,aACE;AAAA,MAEF,aAAa;AAAA,IACf;AAAA,IACA,OAAO,OAAO,QAAwC;AACpD,UAAI,gBAAgB,OAAO,GAAG;AAC5B,cAAM,OAAO,eAAe,KAAK;AACjC,YAAI,CAAC,MAAM;AACT,gBAAM,IAAI;AAAA,YACR;AAAA,UAEF;AAAA,QACF;AACA,cAAM,QAAQ,cAAc;AAAA,UAC1B,UAAU,IAAI;AAAA,UACd,eAAe;AAAA,UACf,UAAU,IAAI;AAAA,UACd,GAAI,UAAU,EAAE,QAAQ,IAAI,CAAC;AAAA,UAC7B,GAAI,eAAe,EAAE,aAAa,IAAI,CAAC;AAAA,QACzC,CAAC;AAAA,MACH;AAEA,YAAM,SAA4B,MAAM,QAAQ,KAAK;AAAA,QACnD,UAAU,IAAI;AAAA,QACd,UAAU,IAAI;AAAA,QACd,SAAS,MAAM;AAAA,QACf;AAAA,MACF,CAAC;AAED,aAAO;AAAA,QACL,UAAU,OAAO;AAAA,QACjB,kBAAkB,OAAO;AAAA,QACzB,YAAY,OAAO;AAAA,QACnB,GAAI,OAAO,eAAe,SAAY,EAAE,YAAY,OAAO,WAAW,IAAI,CAAC;AAAA,MAC7E;AAAA,IACF;AAAA,EACF;AACF;AAOO,SAAS,yBACd,SACA,UAA2D,CAAC,GACvC;AACrB,QAAM,WAAW,IAAI,oBAAoB;AACzC,0BAAwB,UAAU,EAAE,SAAS,GAAG,QAAQ,CAAC;AACzD,SAAO;AACT;","names":[]}

package/dist/chunk-Q62VKHIT.js

@@ -0,0 +1,178 @@
+// src/orchestration.ts
+import { hasCycleFrom } from "@nebutra/graph-model";
+import { z } from "zod";
+var budgetCapSchema = z.object({
+  durationMs: z.number().positive(),
+  costUsd: z.number().nonnegative(),
+  tokenLimit: z.number().positive()
+});
+var briefSchema = z.object({
+  id: z.string().trim().min(1),
+  objective: z.string().trim().min(1),
+  outputFormat: z.record(z.string(), z.unknown()),
+  allowedTools: z.array(z.string()).min(1),
+  contextRefs: z.array(z.string()),
+  boundaries: z.array(z.string()).min(1),
+  budget: budgetCapSchema,
+  dependsOn: z.array(z.string()).optional(),
+  model: z.object({
+    id: z.string().trim().min(1).optional(),
+    reasoningEffort: z.enum(["low", "medium", "high", "xhigh"]).optional(),
+    modality: z.enum(["text", "image", "video", "audio", "embedding"]).optional(),
+    capabilities: z.object({
+      vision: z.boolean().optional(),
+      toolCall: z.boolean().optional(),
+      reasoning: z.boolean().optional()
+    }).optional()
+  }).optional()
+});
+function fail(message, suggestion) {
+  throw new Error(`${message}. Suggestion: ${suggestion}`);
+}
+var BRIEF_FIELD_FAILURE = {
+  id: { message: "brief.id is required", suggestion: "Use a stable role or task id." },
+  objective: {
+    message: "brief.objective is required",
+    suggestion: "Write a concrete objective before dispatching."
+  },
+  outputFormat: {
+    message: "brief.outputFormat is invalid",
+    suggestion: "Provide an output schema object the worker must conform to."
+  },
+  allowedTools: {
+    message: "brief.allowedTools is required",
+    suggestion: "Constrain each subagent to an explicit tool scope."
+  },
+  contextRefs: {
+    message: "brief.contextRefs is invalid",
+    suggestion: "Pass an array of context references (may be empty)."
+  },
+  boundaries: {
+    message: "brief.boundaries is required",
+    suggestion: "State at least one boundary for the worker."
+  },
+  budget: {
+    message: "brief.budget is invalid",
+    suggestion: "Set positive token/time caps and a non-negative cost cap."
+  },
+  dependsOn: {
+    message: "brief.dependsOn is invalid",
+    suggestion: "List dependency brief ids as an array of strings."
+  },
+  model: {
+    message: "brief.model is invalid",
+    suggestion: "Use a preset alias or 'provider/model' id, or omit to inherit the run default."
+  }
+};
+function validateBrief(brief) {
+  const result = briefSchema.safeParse(brief);
+  if (result.success) return;
+  const topLevelField = result.error.issues[0]?.path[0];
+  const failure = typeof topLevelField === "string" ? BRIEF_FIELD_FAILURE[topLevelField] : void 0;
+  if (failure) fail(failure.message, failure.suggestion);
+  fail("brief is invalid", "Provide every required brief field with valid values.");
+}
+function dependencySet(briefs) {
+  const dependencies = /* @__PURE__ */ new Set();
+  for (const brief of briefs) {
+    for (const dep of brief.dependsOn ?? []) dependencies.add(dep);
+  }
+  return dependencies;
+}
+function briefEdges(briefs) {
+  const ids = new Set(briefs.map((brief) => brief.id));
+  const edges = [];
+  for (const brief of briefs) {
+    for (const dep of brief.dependsOn ?? []) {
+      if (ids.has(dep)) edges.push({ from: dep, to: brief.id });
+    }
+  }
+  return edges;
+}
+function assertAcyclic(briefs, edges) {
+  for (const brief of briefs) {
+    if (hasCycleFrom(edges, brief.id)) {
+      fail(
+        `subagent dependency cycle includes '${brief.id}'`,
+        "Remove the cycle or collapse the dependent work into one sequential brief."
+      );
+    }
+  }
+}
+function planWaves(briefs) {
+  const edges = briefEdges(briefs);
+  assertAcyclic(briefs, edges);
+  const byId = new Map(briefs.map((brief) => [brief.id, brief]));
+  const done = /* @__PURE__ */ new Set();
+  const waves = [];
+  while (done.size < briefs.length) {
+    const wave = [];
+    for (const brief of briefs) {
+      if (done.has(brief.id)) continue;
+      const deps = (brief.dependsOn ?? []).filter((dep) => byId.has(dep));
+      if (deps.every((dep) => done.has(dep))) wave.push(brief);
+    }
+    if (wave.length === 0) {
+      fail(
+        "subagent dependencies cannot be resolved into waves",
+        "Ensure every dependsOn id references a brief in the set."
+      );
+    }
+    for (const brief of wave) done.add(brief.id);
+    waves.push(wave);
+  }
+  return waves;
+}
+function topologicalOrder(briefs) {
+  return planWaves(briefs).flat();
+}
+function planSubagentDispatch(briefs, options = {}) {
+  if (briefs.length === 0) {
+    fail("at least one brief is required", "Create a concrete worker brief before dispatching.");
+  }
+  for (const brief of briefs) validateBrief(brief);
+  const dependencies = dependencySet(briefs);
+  if ((options.strategy ?? "auto") === "fanout" && dependencies.size > 0) {
+    fail(
+      "fan-out cannot run briefs that depend on each other",
+      "Use sequential dispatch for dependent work or split independent briefs only."
+    );
+  }
+  const order = topologicalOrder(briefs);
+  const strategy = options.strategy === "fanout" || options.strategy === "auto" && dependencies.size === 0 ? "fanout" : "sequential";
+  return { strategy, order };
+}
+async function fanOutSubagents(briefs, run) {
+  const plan = planSubagentDispatch(briefs, { strategy: "fanout" });
+  return Promise.all(plan.order.map((brief) => run(brief)));
+}
+async function runAgentWaves(briefs, run) {
+  for (const brief of briefs) validateBrief(brief);
+  const results = [];
+  for (const wave of planWaves(briefs)) {
+    const waveResults = await Promise.all(wave.map((brief) => run(brief)));
+    results.push(...waveResults);
+  }
+  return results;
+}
+function costReport(results) {
+  return {
+    totalInputTokens: results.reduce((sum, result) => sum + result.usage.inputTokens, 0),
+    totalOutputTokens: results.reduce((sum, result) => sum + result.usage.outputTokens, 0),
+    totalReasoningTokens: results.reduce(
+      (sum, result) => sum + result.usage.reasoningOutputTokens,
+      0
+    ),
+    maxDurationMs: results.reduce((max, result) => Math.max(max, result.durationMs), 0),
+    subagents: results.length
+  };
+}
+
+export {
+  planWaves,
+  planSubagentDispatch,
+  fanOutSubagents,
+  runAgentWaves,
+  costReport
+};
+//# sourceMappingURL=chunk-Q62VKHIT.js.map

package/dist/chunk-Q62VKHIT.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/orchestration.ts"],"sourcesContent":["import { type GraphEdge, hasCycleFrom } from \"@nebutra/graph-model\";\nimport { z } from \"zod\";\nimport type { TurnUsage } from \"./model\";\n\nexport interface BudgetCap {\n  readonly durationMs: number;\n  readonly costUsd: number;\n  readonly tokenLimit: number;\n}\n\n/** Thinking/reasoning effort for a node (maps to provider reasoning controls). */\nexport type ReasoningEffort = \"low\" | \"medium\" | \"high\" | \"xhigh\";\n\n/** Output modality a node produces. Mirrors @nebutra/ai-providers ModelModality. */\nexport type ModelModality = \"text\" | \"image\" | \"video\" | \"audio\" | \"embedding\";\n\n/**\n * Per-node model selection — the full model meta-info a node can declare. ALL\n * fields optional; an unset field inherits the run-level default\n * (WorkflowDefinition.defaultModel / runTurn config). The executor resolves\n * these HINTS against @nebutra/ai-providers/catalog (listModelsByModality /\n * resolveFrontierModel) to a concrete model — so a node can either PIN one\n * (`id`) or DESCRIBE what it needs (\"the latest fast text model with vision\").\n */\nexport interface NodeModelSpec {\n  /** Explicit pin: preset alias (`flagship`/`reasoning`/`fast`) or `provider/model` id. */\n  readonly id?: string;\n  /** Thinking effort: `low` → cheap/quick, `xhigh` → deepest reasoning. */\n  readonly reasoningEffort?: ReasoningEffort;\n  /** Output modality — selects a model of this modality when `id` is unset. */\n  readonly modality?: ModelModality;\n  /** Capabilities the selected model MUST have (e.g. a node needing image input). */\n  readonly capabilities?: {\n    readonly vision?: boolean;\n    readonly toolCall?: boolean;\n    readonly reasoning?: boolean;\n  };\n}\n\nexport interface Brief {\n  readonly id: string;\n  readonly objective: string;\n  readonly outputFormat: Record<string, unknown>;\n  readonly allowedTools: readonly string[];\n  readonly contextRefs: readonly string[];\n  readonly boundaries: readonly string[];\n  readonly budget: BudgetCap;\n  readonly dependsOn?: readonly string[];\n  /** Per-node model meta-info (id/preset · thinking effort · modality · capabilities). */\n  readonly model?: NodeModelSpec;\n}\n\n/**\n * Runtime shape + semantic validation for {@link Brief}. The public type keeps\n * its `readonly` immutability contract (see project immutability rules), so we\n * validate against this schema at the boundary rather than deriving the type\n * from it. Each rule mirrors a tailored DX suggestion surfaced via {@link fail}.\n */\nconst budgetCapSchema = z.object({\n  durationMs: z.number().positive(),\n  costUsd: z.number().nonnegative(),\n  tokenLimit: z.number().positive(),\n});\n\nconst briefSchema = z.object({\n  id: z.string().trim().min(1),\n  objective: z.string().trim().min(1),\n  outputFormat: z.record(z.string(), z.unknown()),\n  allowedTools: z.array(z.string()).min(1),\n  contextRefs: z.array(z.string()),\n  boundaries: z.array(z.string()).min(1),\n  budget: budgetCapSchema,\n  dependsOn: z.array(z.string()).optional(),\n  model: z\n    .object({\n      id: z.string().trim().min(1).optional(),\n      reasoningEffort: z.enum([\"low\", \"medium\", \"high\", \"xhigh\"]).optional(),\n      modality: z.enum([\"text\", \"image\", \"video\", \"audio\", \"embedding\"]).optional(),\n      capabilities: z\n        .object({\n          vision: z.boolean().optional(),\n          toolCall: z.boolean().optional(),\n          reasoning: z.boolean().optional(),\n        })\n        .optional(),\n    })\n    .optional(),\n});\n\nexport type DispatchStrategy = \"auto\" | \"sequential\" | \"fanout\";\n\nexport interface DispatchPlan {\n  readonly strategy: Exclude<DispatchStrategy, \"auto\">;\n  readonly order: readonly Brief[];\n}\n\nexport interface DispatchPlanOptions {\n  readonly strategy?: DispatchStrategy;\n}\n\nexport interface SubagentResult {\n  readonly briefId: string;\n  readonly output: unknown;\n  readonly usage: TurnUsage;\n  readonly durationMs: number;\n}\n\nexport interface SubagentCostReport {\n  readonly totalInputTokens: number;\n  readonly totalOutputTokens: number;\n  readonly totalReasoningTokens: number;\n  readonly maxDurationMs: number;\n  readonly subagents: number;\n}\n\nfunction fail(message: string, suggestion: string): never {\n  throw new Error(`${message}. Suggestion: ${suggestion}`);\n}\n\n/**\n * Per-top-level-field DX messages, keyed by the failing schema path. Keeps the\n * exact \"message. Suggestion: …\" surface the callers (and tests) rely on while\n * the heavy lifting (shape + bounds) moves into {@link briefSchema}.\n */\nconst BRIEF_FIELD_FAILURE: Record<string, { message: string; suggestion: string }> = {\n  id: { message: \"brief.id is required\", suggestion: \"Use a stable role or task id.\" },\n  objective: {\n    message: \"brief.objective is required\",\n    suggestion: \"Write a concrete objective before dispatching.\",\n  },\n  outputFormat: {\n    message: \"brief.outputFormat is invalid\",\n    suggestion: \"Provide an output schema object the worker must conform to.\",\n  },\n  allowedTools: {\n    message: \"brief.allowedTools is required\",\n    suggestion: \"Constrain each subagent to an explicit tool scope.\",\n  },\n  contextRefs: {\n    message: \"brief.contextRefs is invalid\",\n    suggestion: \"Pass an array of context references (may be empty).\",\n  },\n  boundaries: {\n    message: \"brief.boundaries is required\",\n    suggestion: \"State at least one boundary for the worker.\",\n  },\n  budget: {\n    message: \"brief.budget is invalid\",\n    suggestion: \"Set positive token/time caps and a non-negative cost cap.\",\n  },\n  dependsOn: {\n    message: \"brief.dependsOn is invalid\",\n    suggestion: \"List dependency brief ids as an array of strings.\",\n  },\n  model: {\n    message: \"brief.model is invalid\",\n    suggestion: \"Use a preset alias or 'provider/model' id, or omit to inherit the run default.\",\n  },\n};\n\nfunction validateBrief(brief: Brief): void {\n  const result = briefSchema.safeParse(brief);\n  if (result.success) return;\n\n  const topLevelField = result.error.issues[0]?.path[0];\n  const failure =\n    typeof topLevelField === \"string\" ? BRIEF_FIELD_FAILURE[topLevelField] : undefined;\n  if (failure) fail(failure.message, failure.suggestion);\n  fail(\"brief is invalid\", \"Provide every required brief field with valid values.\");\n}\n\nfunction dependencySet(briefs: readonly Brief[]): Set<string> {\n  const dependencies = new Set<string>();\n  for (const brief of briefs) {\n    for (const dep of brief.dependsOn ?? []) dependencies.add(dep);\n  }\n  return dependencies;\n}\n\n/** Dependency edges (dep → brief) over the brief set; refs to unknown ids drop. */\nfunction briefEdges(briefs: readonly Brief[]): GraphEdge[] {\n  const ids = new Set(briefs.map((brief) => brief.id));\n  const edges: GraphEdge[] = [];\n  for (const brief of briefs) {\n    for (const dep of brief.dependsOn ?? []) {\n      if (ids.has(dep)) edges.push({ from: dep, to: brief.id });\n    }\n  }\n  return edges;\n}\n\n/**\n * Cycle guard via the SINGLE repo-wide cycle-detection algorithm\n * (`@nebutra/graph-model` `hasCycleFrom`). No private DFS cycle-walker lives here.\n */\nfunction assertAcyclic(briefs: readonly Brief[], edges: readonly GraphEdge[]): void {\n  for (const brief of briefs) {\n    if (hasCycleFrom(edges, brief.id)) {\n      fail(\n        `subagent dependency cycle includes '${brief.id}'`,\n        \"Remove the cycle or collapse the dependent work into one sequential brief.\",\n      );\n    }\n  }\n}\n\n/**\n * Dependency-resolved execution WAVES — the agent node-topology scheduler. Each\n * wave is the set of briefs whose dependencies are satisfied by earlier waves;\n * waves run in order, briefs within a wave run in parallel. Input order is\n * preserved within a wave.\n */\nexport function planWaves(briefs: readonly Brief[]): readonly (readonly Brief[])[] {\n  const edges = briefEdges(briefs);\n  assertAcyclic(briefs, edges);\n\n  const byId = new Map(briefs.map((brief) => [brief.id, brief]));\n  const done = new Set<string>();\n  const waves: Brief[][] = [];\n\n  while (done.size < briefs.length) {\n    const wave: Brief[] = [];\n    for (const brief of briefs) {\n      if (done.has(brief.id)) continue;\n      const deps = (brief.dependsOn ?? []).filter((dep) => byId.has(dep));\n      if (deps.every((dep) => done.has(dep))) wave.push(brief);\n    }\n    if (wave.length === 0) {\n      // assertAcyclic already ruled out cycles; only a logic bug reaches here.\n      fail(\n        \"subagent dependencies cannot be resolved into waves\",\n        \"Ensure every dependsOn id references a brief in the set.\",\n      );\n    }\n    for (const brief of wave) done.add(brief.id);\n    waves.push(wave);\n  }\n  return waves;\n}\n\nfunction topologicalOrder(briefs: readonly Brief[]): Brief[] {\n  return planWaves(briefs).flat();\n}\n\nexport function planSubagentDispatch(\n  briefs: readonly Brief[],\n  options: DispatchPlanOptions = {},\n): DispatchPlan {\n  if (briefs.length === 0) {\n    fail(\"at least one brief is required\", \"Create a concrete worker brief before dispatching.\");\n  }\n  for (const brief of briefs) validateBrief(brief);\n\n  const dependencies = dependencySet(briefs);\n  if ((options.strategy ?? \"auto\") === \"fanout\" && dependencies.size > 0) {\n    fail(\n      \"fan-out cannot run briefs that depend on each other\",\n      \"Use sequential dispatch for dependent work or split independent briefs only.\",\n    );\n  }\n\n  const order = topologicalOrder(briefs);\n  const strategy =\n    options.strategy === \"fanout\" || (options.strategy === \"auto\" && dependencies.size === 0)\n      ? \"fanout\"\n      : \"sequential\";\n  return { strategy, order };\n}\n\nexport async function fanOutSubagents(\n  briefs: readonly Brief[],\n  run: (brief: Brief) => Promise<SubagentResult>,\n): Promise<readonly SubagentResult[]> {\n  const plan = planSubagentDispatch(briefs, { strategy: \"fanout\" });\n  return Promise.all(plan.order.map((brief) => run(brief)));\n}\n\n/**\n * Execute briefs as a dependency graph: each wave runs in parallel, waves run\n * sequentially. The node-topology execution path — `fanOutSubagents` is the\n * degenerate single-wave (all-independent) case of this.\n */\nexport async function runAgentWaves(\n  briefs: readonly Brief[],\n  run: (brief: Brief) => Promise<SubagentResult>,\n): Promise<readonly SubagentResult[]> {\n  for (const brief of briefs) validateBrief(brief);\n  const results: SubagentResult[] = [];\n  for (const wave of planWaves(briefs)) {\n    const waveResults = await Promise.all(wave.map((brief) => run(brief)));\n    results.push(...waveResults);\n  }\n  return results;\n}\n\nexport function costReport(results: readonly SubagentResult[]): SubagentCostReport {\n  return {\n    totalInputTokens: results.reduce((sum, result) => sum + result.usage.inputTokens, 0),\n    totalOutputTokens: results.reduce((sum, result) => sum + result.usage.outputTokens, 0),\n    totalReasoningTokens: results.reduce(\n      (sum, result) => sum + result.usage.reasoningOutputTokens,\n      0,\n    ),\n    maxDurationMs: results.reduce((max, result) => Math.max(max, result.durationMs), 0),\n    subagents: results.length,\n  };\n}\n"],"mappings":";AAAA,SAAyB,oBAAoB;AAC7C,SAAS,SAAS;AAyDlB,IAAM,kBAAkB,EAAE,OAAO;AAAA,EAC/B,YAAY,EAAE,OAAO,EAAE,SAAS;AAAA,EAChC,SAAS,EAAE,OAAO,EAAE,YAAY;AAAA,EAChC,YAAY,EAAE,OAAO,EAAE,SAAS;AAClC,CAAC;AAED,IAAM,cAAc,EAAE,OAAO;AAAA,EAC3B,IAAI,EAAE,OAAO,EAAE,KAAK,EAAE,IAAI,CAAC;AAAA,EAC3B,WAAW,EAAE,OAAO,EAAE,KAAK,EAAE,IAAI,CAAC;AAAA,EAClC,cAAc,EAAE,OAAO,EAAE,OAAO,GAAG,EAAE,QAAQ,CAAC;AAAA,EAC9C,cAAc,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,IAAI,CAAC;AAAA,EACvC,aAAa,EAAE,MAAM,EAAE,OAAO,CAAC;AAAA,EAC/B,YAAY,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,IAAI,CAAC;AAAA,EACrC,QAAQ;AAAA,EACR,WAAW,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,SAAS;AAAA,EACxC,OAAO,EACJ,OAAO;AAAA,IACN,IAAI,EAAE,OAAO,EAAE,KAAK,EAAE,IAAI,CAAC,EAAE,SAAS;AAAA,IACtC,iBAAiB,EAAE,KAAK,CAAC,OAAO,UAAU,QAAQ,OAAO,CAAC,EAAE,SAAS;AAAA,IACrE,UAAU,EAAE,KAAK,CAAC,QAAQ,SAAS,SAAS,SAAS,WAAW,CAAC,EAAE,SAAS;AAAA,IAC5E,cAAc,EACX,OAAO;AAAA,MACN,QAAQ,EAAE,QAAQ,EAAE,SAAS;AAAA,MAC7B,UAAU,EAAE,QAAQ,EAAE,SAAS;AAAA,MAC/B,WAAW,EAAE,QAAQ,EAAE,SAAS;AAAA,IAClC,CAAC,EACA,SAAS;AAAA,EACd,CAAC,EACA,SAAS;AACd,CAAC;AA4BD,SAAS,KAAK,SAAiB,YAA2B;AACxD,QAAM,IAAI,MAAM,GAAG,OAAO,iBAAiB,UAAU,EAAE;AACzD;AAOA,IAAM,sBAA+E;AAAA,EACnF,IAAI,EAAE,SAAS,wBAAwB,YAAY,gCAAgC;AAAA,EACnF,WAAW;AAAA,IACT,SAAS;AAAA,IACT,YAAY;AAAA,EACd;AAAA,EACA,cAAc;AAAA,IACZ,SAAS;AAAA,IACT,YAAY;AAAA,EACd;AAAA,EACA,cAAc;AAAA,IACZ,SAAS;AAAA,IACT,YAAY;AAAA,EACd;AAAA,EACA,aAAa;AAAA,IACX,SAAS;AAAA,IACT,YAAY;AAAA,EACd;AAAA,EACA,YAAY;AAAA,IACV,SAAS;AAAA,IACT,YAAY;AAAA,EACd;AAAA,EACA,QAAQ;AAAA,IACN,SAAS;AAAA,IACT,YAAY;AAAA,EACd;AAAA,EACA,WAAW;AAAA,IACT,SAAS;AAAA,IACT,YAAY;AAAA,EACd;AAAA,EACA,OAAO;AAAA,IACL,SAAS;AAAA,IACT,YAAY;AAAA,EACd;AACF;AAEA,SAAS,cAAc,OAAoB;AACzC,QAAM,SAAS,YAAY,UAAU,KAAK;AAC1C,MAAI,OAAO,QAAS;AAEpB,QAAM,gBAAgB,OAAO,MAAM,OAAO,CAAC,GAAG,KAAK,CAAC;AACpD,QAAM,UACJ,OAAO,kBAAkB,WAAW,oBAAoB,aAAa,IAAI;AAC3E,MAAI,QAAS,MAAK,QAAQ,SAAS,QAAQ,UAAU;AACrD,OAAK,oBAAoB,uDAAuD;AAClF;AAEA,SAAS,cAAc,QAAuC;AAC5D,QAAM,eAAe,oBAAI,IAAY;AACrC,aAAW,SAAS,QAAQ;AAC1B,eAAW,OAAO,MAAM,aAAa,CAAC,EAAG,cAAa,IAAI,GAAG;AAAA,EAC/D;AACA,SAAO;AACT;AAGA,SAAS,WAAW,QAAuC;AACzD,QAAM,MAAM,IAAI,IAAI,OAAO,IAAI,CAAC,UAAU,MAAM,EAAE,CAAC;AACnD,QAAM,QAAqB,CAAC;AAC5B,aAAW,SAAS,QAAQ;AAC1B,eAAW,OAAO,MAAM,aAAa,CAAC,GAAG;AACvC,UAAI,IAAI,IAAI,GAAG,EAAG,OAAM,KAAK,EAAE,MAAM,KAAK,IAAI,MAAM,GAAG,CAAC;AAAA,IAC1D;AAAA,EACF;AACA,SAAO;AACT;AAMA,SAAS,cAAc,QAA0B,OAAmC;AAClF,aAAW,SAAS,QAAQ;AAC1B,QAAI,aAAa,OAAO,MAAM,EAAE,GAAG;AACjC;AAAA,QACE,uCAAuC,MAAM,EAAE;AAAA,QAC/C;AAAA,MACF;AAAA,IACF;AAAA,EACF;AACF;AAQO,SAAS,UAAU,QAAyD;AACjF,QAAM,QAAQ,WAAW,MAAM;AAC/B,gBAAc,QAAQ,KAAK;AAE3B,QAAM,OAAO,IAAI,IAAI,OAAO,IAAI,CAAC,UAAU,CAAC,MAAM,IAAI,KAAK,CAAC,CAAC;AAC7D,QAAM,OAAO,oBAAI,IAAY;AAC7B,QAAM,QAAmB,CAAC;AAE1B,SAAO,KAAK,OAAO,OAAO,QAAQ;AAChC,UAAM,OAAgB,CAAC;AACvB,eAAW,SAAS,QAAQ;AAC1B,UAAI,KAAK,IAAI,MAAM,EAAE,EAAG;AACxB,YAAM,QAAQ,MAAM,aAAa,CAAC,GAAG,OAAO,CAAC,QAAQ,KAAK,IAAI,GAAG,CAAC;AAClE,UAAI,KAAK,MAAM,CAAC,QAAQ,KAAK,IAAI,GAAG,CAAC,EAAG,MAAK,KAAK,KAAK;AAAA,IACzD;AACA,QAAI,KAAK,WAAW,GAAG;AAErB;AAAA,QACE;AAAA,QACA;AAAA,MACF;AAAA,IACF;AACA,eAAW,SAAS,KAAM,MAAK,IAAI,MAAM,EAAE;AAC3C,UAAM,KAAK,IAAI;AAAA,EACjB;AACA,SAAO;AACT;AAEA,SAAS,iBAAiB,QAAmC;AAC3D,SAAO,UAAU,MAAM,EAAE,KAAK;AAChC;AAEO,SAAS,qBACd,QACA,UAA+B,CAAC,GAClB;AACd,MAAI,OAAO,WAAW,GAAG;AACvB,SAAK,kCAAkC,oDAAoD;AAAA,EAC7F;AACA,aAAW,SAAS,OAAQ,eAAc,KAAK;AAE/C,QAAM,eAAe,cAAc,MAAM;AACzC,OAAK,QAAQ,YAAY,YAAY,YAAY,aAAa,OAAO,GAAG;AACtE;AAAA,MACE;AAAA,MACA;AAAA,IACF;AAAA,EACF;AAEA,QAAM,QAAQ,iBAAiB,MAAM;AACrC,QAAM,WACJ,QAAQ,aAAa,YAAa,QAAQ,aAAa,UAAU,aAAa,SAAS,IACnF,WACA;AACN,SAAO,EAAE,UAAU,MAAM;AAC3B;AAEA,eAAsB,gBACpB,QACA,KACoC;AACpC,QAAM,OAAO,qBAAqB,QAAQ,EAAE,UAAU,SAAS,CAAC;AAChE,SAAO,QAAQ,IAAI,KAAK,MAAM,IAAI,CAAC,UAAU,IAAI,KAAK,CAAC,CAAC;AAC1D;AAOA,eAAsB,cACpB,QACA,KACoC;AACpC,aAAW,SAAS,OAAQ,eAAc,KAAK;AAC/C,QAAM,UAA4B,CAAC;AACnC,aAAW,QAAQ,UAAU,MAAM,GAAG;AACpC,UAAM,cAAc,MAAM,QAAQ,IAAI,KAAK,IAAI,CAAC,UAAU,IAAI,KAAK,CAAC,CAAC;AACrE,YAAQ,KAAK,GAAG,WAAW;AAAA,EAC7B;AACA,SAAO;AACT;AAEO,SAAS,WAAW,SAAwD;AACjF,SAAO;AAAA,IACL,kBAAkB,QAAQ,OAAO,CAAC,KAAK,WAAW,MAAM,OAAO,MAAM,aAAa,CAAC;AAAA,IACnF,mBAAmB,QAAQ,OAAO,CAAC,KAAK,WAAW,MAAM,OAAO,MAAM,cAAc,CAAC;AAAA,IACrF,sBAAsB,QAAQ;AAAA,MAC5B,CAAC,KAAK,WAAW,MAAM,OAAO,MAAM;AAAA,MACpC;AAAA,IACF;AAAA,IACA,eAAe,QAAQ,OAAO,CAAC,KAAK,WAAW,KAAK,IAAI,KAAK,OAAO,UAAU,GAAG,CAAC;AAAA,IAClF,WAAW,QAAQ;AAAA,EACrB;AACF;","names":[]}