@directive-run/knowledge 1.14.0 → 1.15.0

package/ai/ai-multi-agent.md

@@ -1,22 +1,28 @@
-# AI Multi-Agent Orchestrator
+# AI multi-agent orchestrator
 
-`createMultiAgentOrchestrator` coordinates multiple agents using 8 composition patterns. Each agent becomes a namespaced Directive module with a shared coordinator.
+> Covers `@directive-run/ai/multi-agent` — `createMultiAgentOrchestrator` + 8 composition patterns (parallel / sequential / supervisor / dag / reflect / race / debate / goal).
 
-## Decision Tree: "Which pattern do I need?"
+`createMultiAgentOrchestrator` coordinates multiple agents using 8 composition patterns. Each agent becomes a namespaced Directive module with a shared coordinator. Patterns are pure config objects you assemble with factory functions and pass via the `patterns:` option.
+
+For a single agent, see `ai-orchestrator.md`.
+
+## Decision tree
 
 ```
 How should agents interact?
 ├── Independent, combine results → parallel()
-├── One feeds the next        → sequential()
-├── One agent delegates        → supervisor()
+├── One feeds the next         → sequential()
+├── One agent delegates work   → supervisor()
 ├── Complex dependency graph   → dag()
-├── Agent critiques own output → reflect()
-├── First to finish wins      → race()
-├── Agents argue to consensus → debate()
-└── Iterate until goal met    → goal()
+├── Producer + evaluator loop  → reflect()
+├── First to finish wins       → race()
+├── Multiple positions debated → debate()
+└── Iterate until goal met     → goal()
 ```
 
-## Basic Setup
+## Basic setup
+
+Import from the subpath barrel — the main `@directive-run/ai` barrel re-exports these with `@deprecated` notices for v2 removal.
 
 ```typescript
 import {
@@ -29,246 +35,334 @@ import {
   race,
   debate,
   goal,
-} from "@directive-run/ai";
+} from "@directive-run/ai/multi-agent";
 import { createAnthropicRunner } from "@directive-run/ai/anthropic";
 
 const runner = createAnthropicRunner({
-  apiKey: process.env.ANTHROPIC_API_KEY,
+  apiKey: process.env.ANTHROPIC_API_KEY!,
 });
 
 const orchestrator = createMultiAgentOrchestrator({
   agents: {
-    researcher: {
-      name: "researcher",
-      instructions: "Research the topic thoroughly.",
-      model: "claude-sonnet-4-5",
-    },
-    writer: {
-      name: "writer",
-      instructions: "Write clear, engaging content.",
-      model: "claude-sonnet-4-5",
-    },
-    editor: {
-      name: "editor",
-      instructions: "Edit for clarity and correctness.",
-      model: "claude-haiku-3-5",
-    },
+    researcher: { name: "researcher", instructions: "Research the topic thoroughly.", model: "claude-sonnet-4-5" },
+    writer:     { name: "writer",     instructions: "Write clear, engaging content.", model: "claude-sonnet-4-5" },
+    editor:     { name: "editor",     instructions: "Edit for clarity and correctness.", model: "claude-haiku-4-5" },
   },
   patterns: {
-    pipeline: sequential(["researcher", "writer", "editor"]),
-    brainstorm: parallel(["researcher", "writer"], mergeResults),
-    managed: supervisor("editor", ["researcher", "writer"]),
-    workflow: dag([
-      { id: "research", handler: "researcher" },
-      { id: "write", handler: "writer", dependencies: ["research"] },
-      { id: "edit", handler: "editor", dependencies: ["write"] },
-    ]),
+    pipeline:  sequential(["researcher", "writer", "editor"]),
+    brainstorm: parallel(["researcher", "writer"], (results) => results.map((r) => String(r.output)).join("\n\n")),
+    managed:   supervisor("editor", ["researcher", "writer"]),
+    workflow:  dag({
+      research:  { handler: "researcher" },
+      write:     { handler: "writer", deps: ["research"] },
+      edit:      { handler: "editor", deps: ["write"] },
+    }),
   },
   runner,
 });
 
-// REQUIRED for multi-agent – must call start() before running patterns
+// REQUIRED — call start() before runPattern. Single-agent createAgentOrchestrator does NOT need this.
 orchestrator.start();
 
 const result = await orchestrator.runPattern("pipeline", "Write about AI");
 ```
 
-## Pattern Details
+## Patterns in depth
+
+### `parallel(handlers, merge, options?)`
 
-### parallel – Run agents concurrently, merge results
+Runs handlers concurrently and combines their results. **`merge` is REQUIRED as positional argument 2** — without it the call fails at registration. `options?` accepts `minSuccess` and `timeout`.
 
 ```typescript
 const brainstorm = parallel(
   ["researcher", "writer"],
-  (results) => {
-    // results: Map<string, RunResult>
-    const combined = Array.from(results.values())
-      .map((r) => r.output)
-      .join("\n\n");
-
-    return combined;
-  },
+  (results) => results.map((r) => String(r.output)).join("\n\n"),
+  { minSuccess: 1, timeout: 30_000 },
 );
 ```
 
-### sequential – Chain agents in order
+The `results` arg is `RunResult<unknown>[]` — array, in handler order.
+
+### `sequential(handlers, options?)`
+
+Each handler's output feeds as input to the next. `options.transform(output, handlerId, index)` adapts the hand-off; `options.extract(finalOutput)` shapes the return.
 
 ```typescript
-// Each agent receives the previous agent's output as its prompt
 const pipeline = sequential(["researcher", "writer", "editor"]);
+
+const writeReview = sequential(["writer", "reviewer"], {
+  transform: (output) => `Review this draft:\n${output}`,
+});
 ```
 
-### supervisor – One agent delegates to workers
+### `supervisor(supervisorAgent, workers, options?)`
+
+The supervisor runs first and delegates to workers based on its output. Repeats up to `maxRounds` until the supervisor signals completion.
 
 ```typescript
-// Editor decides which worker to invoke and when to stop
-const managed = supervisor("editor", ["researcher", "writer"]);
+const managed = supervisor("manager", ["worker1", "worker2"], { maxRounds: 3 });
 ```
 
-### dag – Directed acyclic graph of dependencies
+### `dag(nodes, merge?, options?)`
+
+**Nodes are a `Record<string, DagNode>`, NOT an array.** Each node's edges are listed in `deps` (not `dependencies`). The runtime validates the graph is acyclic and that all `deps` refer to declared nodes.
 
 ```typescript
-// DagNode shape
-interface DagNode {
-  id: string;
-  handler: string;          // agent name
-  dependencies?: string[];  // node IDs this depends on
-  transform?: (input: string, depResults: Map<string, string>) => string;
-}
-
-const workflow = dag([
-  { id: "research", handler: "researcher" },
-  {
-    id: "write",
-    handler: "writer",
-    dependencies: ["research"],
-    transform: (input, deps) => {
-      const research = deps.get("research");
+import type { DagNode, DagExecutionContext } from "@directive-run/ai/multi-agent";
 
-      return `Based on research:\n${research}\n\nWrite about: ${input}`;
-    },
+const workflow = dag(
+  {
+    research:  { handler: "researcher" },
+    analyze:   { handler: "analyzer", deps: ["research"] },
+    summarize: { handler: "summarizer", deps: ["analyze"] },
+  },
+  // optional merge — receives the execution context with .outputs Record
+  (context: DagExecutionContext) => context.outputs.summarize,
+  // optional config
+  {
+    timeout: 60_000,
+    maxConcurrent: 4,
+    onNodeError: "skip-downstream", // "fail" (default) | "skip-downstream" | "continue"
   },
-  { id: "edit", handler: "editor", dependencies: ["write"] },
-]);
+);
 ```
 
-### reflect – Agent critiques and revises its own output
+### `reflect(handler, evaluator, options?)`
+
+Producer + evaluator loop. The producer generates output, the evaluator scores it; if the score is below `threshold` the producer retries with feedback, up to `maxIterations`. **`evaluator` is REQUIRED as positional argument 2.**
 
 ```typescript
-const selfImprove = reflect("writer", {
+const selfImprove = reflect("writer", "reviewer", {
   maxIterations: 3,
-  stopWhen: (output, iteration) => {
-    return output.includes("FINAL") || iteration >= 3;
-  },
+  threshold: 0.8,
+  onExhausted: "accept-best", // "accept-last" | "accept-best" | "throw"
+  onIteration: (record) => console.log(`iter ${record.iteration}: ${record.score}`),
 });
 ```
 
-### race – First agent to finish wins
+### `race(handlers, options?)`
+
+All handlers start simultaneously; the first to complete successfully wins. Use `minSuccess` to wait for N before picking.
 
 ```typescript
-const fastest = race(["researcher", "writer"], {
-  minSuccess: 1,       // How many must complete (default: 1)
-  timeout: 30000,      // Cancel remaining after timeout
+const fastest = race(["fast-model", "smart-model"], {
+  timeout: 5000,
+  minSuccess: 1, // must be ≤ handlers.length
 });
 ```
 
-### debate – Agents argue to consensus
+### `debate(config)`
+
+**Takes a single `DebateConfig` object.** The discriminator agents argue from different positions; the `evaluator` agent judges. There is no `judge` field — it's `evaluator`.
 
 ```typescript
-const consensus = debate(["researcher", "writer"], {
-  maxRounds: 5,
-  judge: "editor",     // Agent that decides when consensus is reached
+const consensus = debate({
+  handlers: ["optimist", "pessimist"],
+  evaluator: "judge",
+  maxRounds: 2,
 });
 ```
 
-### goal – Iterate until a condition is met
+### `goal(nodes, when, options?)`
+
+Goal-driven execution. Each node declares what it `produces` and `requires`; the runtime infers the execution graph and runs agents until `when(facts)` returns true. There is no single-agent string form.
 
 ```typescript
-const iterative = goal("researcher", {
-  maxIterations: 10,
-  goalCheck: (output, facts) => {
-    return facts.confidence > 0.9;
+import type { GoalNode } from "@directive-run/ai/multi-agent";
+
+const pipeline = goal(
+  {
+    researcher: {
+      handler: "researcher",
+      produces: ["research.findings"],
+      requires: ["research.topic"],
+      extractOutput: (r) => ({ "research.findings": r.output }),
+    },
+    writer: {
+      handler: "writer",
+      produces: ["article.draft"],
+      requires: ["research.findings"],
+      extractOutput: (r) => ({ "article.draft": r.output }),
+    },
   },
-});
+  (facts) => facts["article.draft"] != null,
+  {
+    maxSteps: 10,
+    extract: (facts) => facts["article.draft"],
+    satisfaction: (facts) => (facts["article.draft"] ? 1.0 : 0.0),
+  },
+);
 ```
 
-## Fact Propagation
+## Fact propagation
 
-Each agent has its own namespaced facts. The coordinator module (`__coord`) holds shared state:
+Each agent has its own namespaced facts module. A coordinator module (`__coord`) tracks shared orchestration state.
 
 ```typescript
-// Read agent-specific facts
+// Per-agent state — module is named after the agent's key in `agents:`
 orchestrator.system.facts.researcher.status;
-orchestrator.system.facts.writer.lastOutput;
+orchestrator.system.facts.writer.output;
 
-// Read coordinator facts
+// Coordinator state
 orchestrator.system.facts.__coord.activePattern;
 orchestrator.system.facts.__coord.completedAgents;
 ```
 
-## Checkpoint Serialization
+## Checkpoints
+
+Multi-agent uses the same checkpoint shape as single-agent. **`checkpoint()` is async** — returns a `Promise<Checkpoint>`. Restore on an existing instance via `orch.restore(cp)`. There is no `createMultiAgentOrchestrator({ checkpoint })` constructor option.
 
 ```typescript
-// Save entire multi-agent state
-const checkpoint = orchestrator.checkpoint();
-const serialized = JSON.stringify(checkpoint);
-
-// Restore from checkpoint
-const restored = createMultiAgentOrchestrator({
-  agents,
-  patterns,
-  runner,
-  checkpoint: JSON.parse(serialized),
-});
+const cp = await orchestrator.checkpoint({ label: "after-pipeline" });
+const serialized = JSON.stringify(cp);
+
+// On a fresh orchestrator with the same agents/patterns/runner:
+const restored = createMultiAgentOrchestrator({ agents, patterns, runner });
+restored.restore(JSON.parse(serialized));
 restored.start();
 ```
 
-## Tasks in Multi-Agent Patterns
+## Tasks alongside agents
 
-Tasks and agents share the DAG/sequential/parallel namespace. See `ai-tasks.md` for details.
+Tasks (registered via `tasks:`) share the handler namespace with agents — a `dag` or `sequential` can refer to either by ID. See `ai-tasks.md` for the full task surface.
 
 ```typescript
-const workflow = dag([
-  { id: "research", handler: "researcher" },
-  { id: "format", handler: "formatter-task" },  // task, not agent
-  { id: "edit", handler: "editor", dependencies: ["research", "format"] },
-]);
+const workflow = dag({
+  research:  { handler: "researcher" },
+  format:    { handler: "formatter-task" }, // a task, not an agent
+  edit:      { handler: "editor", deps: ["research", "format"] },
+});
 ```
 
-## Anti-Patterns
+## Anti-patterns
 
-### #24: Forgetting start() for multi-agent
+### Forgetting `start()` on multi-agent
 
 ```typescript
-// WRONG – multi-agent orchestrators require explicit start()
-const orchestrator = createMultiAgentOrchestrator({ agents, runner });
-const result = await orchestrator.runPattern("pipeline", "prompt");
-// Error: Orchestrator not started
+// WRONG — multi-agent orchestrators require explicit start()
+const orch = createMultiAgentOrchestrator({ agents, patterns, runner });
+await orch.runPattern("pipeline", "prompt"); // throws — not started
 
 // CORRECT
-const orchestrator = createMultiAgentOrchestrator({ agents, runner });
-orchestrator.start();
-const result = await orchestrator.runPattern("pipeline", "prompt");
+const orch = createMultiAgentOrchestrator({ agents, patterns, runner });
+orch.start();
+await orch.runPattern("pipeline", "prompt");
 ```
 
-### #30: race minSuccess greater than agent count
+Single-agent `createAgentOrchestrator` does NOT require `start()`. Only multi-agent does.
+
+### Array-form `dag` and `dependencies` key
 
 ```typescript
-// WRONG – minSuccess cannot exceed the number of agents
-const broken = race(["researcher", "writer"], {
-  minSuccess: 3, // Only 2 agents, will never satisfy
-});
+// WRONG — dag takes Record<string, DagNode>, not an array; and the edge key is `deps`
+dag([
+  { id: "research",  handler: "researcher" },
+  { id: "write",     handler: "writer", dependencies: ["research"] },
+])
+
+// CORRECT
+dag({
+  research: { handler: "researcher" },
+  write:    { handler: "writer", deps: ["research"] },
+})
+```
+
+### `parallel` without the merge arg
+
+```typescript
+// WRONG — merge is a REQUIRED positional argument, not in options
+parallel(["researcher", "writer"], { minSuccess: 1 })
+
+// CORRECT — merge first, options second
+parallel(
+  ["researcher", "writer"],
+  (results) => results.map((r) => String(r.output)).join("\n"),
+  { minSuccess: 1 },
+)
+```
+
+### `reflect` with a single agent
+
+```typescript
+// WRONG — reflect needs a SEPARATE evaluator handler; stopWhen is not an option
+reflect("writer", { maxIterations: 3, stopWhen: (out) => out.includes("FINAL") })
+
+// CORRECT — handler + evaluator + threshold (the evaluator decides when to stop)
+reflect("writer", "reviewer", { maxIterations: 3, threshold: 0.8 })
+```
+
+### `debate` with `judge:` option
+
+```typescript
+// WRONG — debate uses `evaluator`, not `judge`; and it's a single config arg
+debate(["researcher", "writer"], { maxRounds: 5, judge: "editor" })
 
-// CORRECT – minSuccess <= agents.length
-const working = race(["researcher", "writer"], {
-  minSuccess: 1,
+// CORRECT — single config object, evaluator key
+debate({ handlers: ["researcher", "writer"], evaluator: "editor", maxRounds: 5 })
+```
+
+### `goal` with a single agent string
+
+```typescript
+// WRONG — goal does not take a single agent + goalCheck; it takes a node map + when()
+goal("researcher", { maxIterations: 10, goalCheck: (out, facts) => facts.confidence > 0.9 })
+
+// CORRECT — declarative node map + a when() predicate
+goal(
+  {
+    researcher: {
+      handler: "researcher",
+      produces: ["confidence"],
+      requires: ["topic"],
+      extractOutput: (r) => ({ confidence: (r.output as { confidence: number }).confidence }),
+    },
+  },
+  (facts) => (facts.confidence as number) > 0.9,
+  { maxSteps: 10 },
+)
+```
+
+### Handler IDs that don't match `agents:` keys
+
+```typescript
+// WRONG — handler refs must match the keys in agents/tasks
+createMultiAgentOrchestrator({
+  agents: { researcher: {...}, writer: {...} },
+  patterns: { pipeline: sequential(["research-agent", "write-agent"]) }, // wrong names
 });
+
+// CORRECT
+patterns: { pipeline: sequential(["researcher", "writer"]) }
 ```
 
-### Reusing agent names across patterns
+### `race` with `minSuccess` greater than the handler count
 
 ```typescript
-// WRONG – agent names must match keys in the agents config
-patterns: {
-  pipeline: sequential(["research-agent", "write-agent"]),
-  // These don't match the keys "researcher", "writer"
-},
-
-// CORRECT – use the exact keys from agents config
-patterns: {
-  pipeline: sequential(["researcher", "writer"]),
-},
+// WRONG — minSuccess can never exceed handlers.length
+race(["researcher", "writer"], { minSuccess: 3 }) // 2 handlers, impossible
+```
+
+### Restoring via a constructor option
+
+```typescript
+// WRONG — there is no `checkpoint` option on createMultiAgentOrchestrator
+createMultiAgentOrchestrator({ agents, patterns, runner, checkpoint: cp })
+
+// CORRECT — restore on an existing instance, then start()
+const orch = createMultiAgentOrchestrator({ agents, patterns, runner });
+orch.restore(cp);
+orch.start();
 ```
 
-## Quick Reference
+## Quick reference
 
-| Pattern | Use Case | Key Option |
+| Pattern | Signature | Required arg 2 |
 |---|---|---|
-| `parallel()` | Independent work, merge results | merge function |
-| `sequential()` | Pipeline, each feeds next | agent order |
-| `supervisor()` | Dynamic delegation | supervisor agent |
-| `dag()` | Complex dependencies | DagNode[] |
-| `reflect()` | Self-improvement loop | maxIterations, stopWhen |
-| `race()` | Fastest wins | minSuccess, timeout |
-| `debate()` | Consensus building | maxRounds, judge |
-| `goal()` | Condition-driven iteration | goalCheck |
+| `parallel(handlers, merge, options?)` | `string[], (results) => T, { minSuccess?, timeout? }` | merge |
+| `sequential(handlers, options?)` | `string[], { transform?, extract?, continueOnError? }` | — |
+| `supervisor(supervisorAgent, workers, options?)` | `string, string[], { maxRounds?, extract? }` | workers |
+| `dag(nodes, merge?, options?)` | `Record<string, DagNode>, (ctx) => T, { timeout?, maxConcurrent?, onNodeError? }` | — |
+| `reflect(handler, evaluator, options?)` | `string, string, { maxIterations?, threshold?, onExhausted?, onIteration? }` | evaluator |
+| `race(handlers, options?)` | `string[], { timeout?, minSuccess?, extract? }` | — |
+| `debate(config)` | `{ handlers, evaluator, maxRounds?, extract?, parseJudgement? }` | — (single arg) |
+| `goal(nodes, when, options?)` | `Record<string, GoalNode>, (facts) => boolean, { maxSteps?, extract?, satisfaction? }` | when |