@directive-run/claude-plugin 1.16.0

package/skills/building-ai-agents/ai-agents-streaming.md

@@ -0,0 +1,307 @@
+# AI agents + streaming
+
+> Covers `@directive-run/ai` — `AgentLike`, `RunResult`, `StreamChunk`, backpressure, `createStreamingRunner`, `createSSETransport`.
+
+Defines the `AgentLike` shape, the `RunResult` returned by every runner, the `StreamChunk` discriminated union, backpressure strategies, the streaming runner wrapper, and the SSE transport for piping tokens to a browser.
+
+## Decision tree
+
+```
+Need the complete result?
+├── Yes                          → orchestrator.run(agent, prompt) → Promise<RunResult>
+└── No, need incremental output
+    ├── Async-iterator stream    → orchestrator.runStream(agent, prompt) → { stream, result, abort }
+    ├── Wrap a base runner       → createStreamingRunner(baseRunner, opts) → StreamRunner
+    └── Server-Sent Events to HTTP → createSSETransport(config) → { toResponse, toStream }
+
+Backpressure concern?
+├── Consumer is slow             → backpressure: "buffer" (default)
+├── Need every token             → backpressure: "block"
+└── Real-time, can drop          → backpressure: "drop"
+```
+
+## `AgentLike`
+
+```typescript
+interface AgentLike {
+  name: string;            // required — unique identifier
+  instructions?: string;   // system prompt
+  model?: string;          // adapter-specific model id
+  tools?: unknown[];       // tools the agent can call
+}
+
+const agent: AgentLike = {
+  name: "analyst",
+  instructions: "You analyze data and provide insights.",
+  model: "claude-sonnet-4-5",
+  tools: [searchTool, calculatorTool],
+};
+```
+
+## `RunResult<T>`
+
+Every runner — wrapped, mocked, real — resolves to this shape.
+
+```typescript
+interface RunResult<T = unknown> {
+  output: T;                 // the agent's final output
+  messages: Message[];       // full message history from this run
+  toolCalls: ToolCall[];     // tool calls executed during this run
+  totalTokens: number;       // cumulative tokens
+  tokenUsage?: TokenUsage;   // optional input/output breakdown when the provider supplies it
+  isCached?: boolean;        // true when served from a semantic cache hit
+}
+
+interface TokenUsage {
+  inputTokens: number;
+  outputTokens: number;
+  // Note: NO `total` field — sum `inputTokens + outputTokens` when needed, or use `result.totalTokens`.
+}
+```
+
+## `StreamChunk` discriminated union
+
+```typescript
+type StreamChunk =
+  | { type: "token"; data: string; tokenCount: number }                                   // a text token from the model
+  | { type: "tool_start"; tool: string; toolCallId: string; arguments: string }            // tool started executing
+  | { type: "tool_end"; tool: string; toolCallId: string; result: string }                 // tool finished
+  | { type: "message"; message: Message }                                                  // a complete message added to history
+  | { type: "guardrail_triggered"; guardrailName: string; reason: string; stopped: boolean } // a guardrail fired during streaming
+  | { type: "progress"; phase: "starting" | "generating" | "tool_calling" | "finishing" }   // coarse progress
+  | { type: "done"; totalTokens: number; duration: number; droppedTokens: number }          // stream complete
+  | { type: "error"; error: Error };                                                       // stream aborted with an error
+```
+
+## Consuming `runStream`
+
+`orchestrator.runStream(agent, input, options?)` returns **`OrchestratorStreamResult<T>`** — a `{ stream, result, abort }` triple, NOT an `AsyncIterable` directly. Destructure it before iterating.
+
+```typescript
+const { stream, result, abort } = orchestrator.runStream(agent, "Write a report");
+
+for await (const chunk of stream) {
+  switch (chunk.type) {
+    case "token":
+      process.stdout.write(chunk.data);
+      break;
+    case "tool_start":
+      console.log(`\ntool: ${chunk.tool}`);
+      break;
+    case "tool_end":
+      console.log(`result: ${chunk.result.slice(0, 100)}`);
+      break;
+    case "guardrail_triggered":
+      console.warn(`guardrail ${chunk.guardrailName}: ${chunk.reason}`);
+      if (chunk.stopped) {
+        console.error("stream stopped by guardrail");
+      }
+      break;
+    case "done":
+      console.log(`\ntokens: ${chunk.totalTokens}, ${chunk.duration}ms`);
+      break;
+    case "error":
+      console.error("stream error:", chunk.error);
+      break;
+  }
+}
+
+const final = await result; // RunResult<T>
+
+// Cancel mid-stream
+abort();
+```
+
+## Backpressure strategies
+
+Configure how the stream behaves when the consumer can't keep up. Pass via `runStream`'s `options` (orchestrator-side) or via the `StreamRunOptions` if you're calling a `StreamRunner` directly.
+
+```typescript
+const { stream, result } = orchestrator.runStream(agent, "Generate a long report", {
+  signal: abortController.signal,
+  backpressure: "buffer",   // default — buffer all tokens
+  // backpressure: "block"   // pause generation until consumer catches up
+  // backpressure: "drop"    // drop unprocessed tokens; `done.droppedTokens` reports the count
+  bufferSize: 1000,
+  stopOnGuardrail: true,
+  guardrailCheckInterval: 100,
+});
+```
+
+| Strategy | Behavior | Use when |
+|---|---|---|
+| `"buffer"` | Buffers all tokens in memory | Consumer is slightly slow; memory is available |
+| `"block"` | Pauses model generation | Consumer must process every token |
+| `"drop"` | Drops unprocessed tokens | Real-time display; some loss acceptable |
+
+## `createStreamingRunner(baseRunner, options?)`
+
+Wrap a base streaming runner (a `StreamingCallbackRunner` — the callback-based adapter interface) into a `StreamRunner` that produces the async-iterator chunks shown above. The factory is `createStreamingRunner`, NOT `createStreamingCallbackRunner` (the "callback" form is the INPUT to this wrapper, not a separate factory).
+
+```typescript
+import { createStreamingRunner, type StreamingCallbackRunner } from "@directive-run/ai";
+
+// The base runner is callback-driven. You supply this from your provider adapter.
+const callbackBased: StreamingCallbackRunner = (agent, input, { onToken, onToolStart, onToolEnd, onComplete, signal }) => {
+  // … call your provider's streaming API; invoke the callbacks as tokens arrive
+};
+
+const streamRunner = createStreamingRunner(callbackBased, {
+  streamingGuardrails: [],
+});
+
+// Use it directly — returns the same { stream, result, abort } shape
+const { stream, result, abort } = streamRunner(agent, "prompt", { backpressure: "buffer" });
+```
+
+## `createSSETransport(config?)`
+
+Pipes a token stream to Server-Sent Events for browser consumption. `createSSEResponse` does NOT exist — the real factory is `createSSETransport`, and it returns `{ toResponse, toStream }`.
+
+```typescript
+import { createSSETransport } from "@directive-run/ai";
+
+const sse = createSSETransport({
+  maxResponseChars: 50_000,
+  truncationMessage: "\n\n*[Response truncated]*",
+  heartbeatIntervalMs: 15_000,
+  headers: { "X-AI-Service": "directive" },
+  errorMessages: { rate_limit: "Service busy — please retry shortly." },
+});
+
+// Modern web frameworks (Hono, Next.js, Bun, Deno) — return a Response directly
+export async function POST(req: Request) {
+  const { prompt } = await req.json();
+  const { stream } = orchestrator.runStream(agent, prompt);
+
+  return sse.toResponse(stream, agent.name, prompt);
+}
+
+// Express / Koa — write to res via the ReadableStream
+app.post("/api/chat", async (req, res) => {
+  const { stream } = orchestrator.runStream(agent, req.body.prompt);
+  const readable = sse.toStream(stream, agent.name, req.body.prompt);
+
+  res.setHeader("Content-Type", "text/event-stream");
+  res.setHeader("Cache-Control", "no-cache");
+  res.setHeader("Connection", "keep-alive");
+
+  for await (const chunk of readable) {
+    res.write(chunk);
+  }
+  res.end();
+});
+```
+
+Client-side consumption is plain SSE:
+
+```typescript
+const eventSource = new EventSource("/api/chat");
+
+eventSource.addEventListener("text", (event) => {
+  const data = JSON.parse(event.data) as { type: "text"; text: string };
+  appendToDisplay(data.text);
+});
+
+eventSource.addEventListener("done", () => eventSource.close());
+```
+
+## Anti-patterns
+
+### Iterating `runStream` directly
+
+```typescript
+// WRONG — runStream returns { stream, result, abort }, not the iterator itself
+const stream = orchestrator.runStream(agent, prompt);
+for await (const chunk of stream) { /* won't iterate the right thing */ }
+
+// CORRECT — destructure
+const { stream, result, abort } = orchestrator.runStream(agent, prompt);
+for await (const chunk of stream) { /* … */ }
+const final = await result;
+```
+
+### Importing `createStreamingCallbackRunner`
+
+```typescript
+// WRONG — no factory by that name
+import { createStreamingCallbackRunner } from "@directive-run/ai";
+
+// CORRECT — wrap a callback-based runner with createStreamingRunner
+import { createStreamingRunner } from "@directive-run/ai";
+const wrapped = createStreamingRunner(callbackBasedRunner, { streamingGuardrails: [] });
+```
+
+### Importing `createSSEResponse`
+
+```typescript
+// WRONG — no factory by that name
+import { createSSEResponse } from "@directive-run/ai";
+const sse = createSSEResponse(stream);
+
+// CORRECT — createSSETransport returns { toResponse, toStream }
+import { createSSETransport } from "@directive-run/ai";
+const sse = createSSETransport({ heartbeatIntervalMs: 15_000 });
+return sse.toResponse(stream, agentId, prompt);
+```
+
+### Reading `tokenUsage.total`
+
+```typescript
+// WRONG — TokenUsage has no `total` field
+console.log(result.tokenUsage?.total);
+
+// CORRECT — sum, or use the top-level totalTokens
+console.log(result.totalTokens);
+console.log((result.tokenUsage?.inputTokens ?? 0) + (result.tokenUsage?.outputTokens ?? 0));
+```
+
+### Not checking `chunk.type` before accessing fields
+
+```typescript
+// WRONG — not every chunk has .data; this is undefined for tool_start/done/etc.
+for await (const chunk of stream) {
+  console.log(chunk.data);
+}
+
+// CORRECT — switch / narrow on chunk.type
+for await (const chunk of stream) {
+  if (chunk.type === "token") {
+    process.stdout.write(chunk.data);
+  }
+}
+```
+
+### Ignoring `guardrail_triggered.stopped`
+
+```typescript
+// WRONG — continuing after a stopping guardrail
+case "guardrail_triggered":
+  console.log("guardrail fired, continuing…");
+  break;
+
+// CORRECT — `stopped: true` means the stream was terminated by the guardrail
+case "guardrail_triggered":
+  if (chunk.stopped) {
+    console.error(`stopped by ${chunk.guardrailName}: ${chunk.reason}`);
+    abort();
+    return;
+  }
+  break;
+```
+
+## Quick reference
+
+| Type / API | Path | Purpose |
+|---|---|---|
+| `AgentLike` | `@directive-run/ai` | `{ name, instructions?, model?, tools? }` — what runners receive |
+| `RunResult<T>` | `@directive-run/ai` | `{ output, messages, toolCalls, totalTokens, tokenUsage?, isCached? }` |
+| `StreamChunk` | `@directive-run/ai` | 8-way discriminated union for streaming output |
+| `orchestrator.runStream(agent, input, opts?)` | instance method | Returns `{ stream, result, abort }` |
+| `createStreamingRunner(baseRunner, opts?)` | `@directive-run/ai` | Wrap a `StreamingCallbackRunner` into a `StreamRunner` |
+| `createSSETransport(config?)` | `@directive-run/ai` | `{ toResponse, toStream }` for piping a stream to SSE |
+
+## See also
+
+- [`ai-adapters.md`](./ai-adapters.md) — provider runners that produce the streams this file consumes
+- [`ai-orchestrator.md`](./ai-orchestrator.md) — `orchestrator.runStream(agent, input)` returns the `{ stream, result, abort }` triple this file documents

package/skills/building-ai-agents/ai-communication.md

@@ -0,0 +1,304 @@
+# AI inter-agent communication
+
+> Covers `@directive-run/ai` — `createMessageBus`, `createAgentNetwork`, request/response patterns, scratchpad, cross-agent fact reads.
+
+`createMessageBus` for typed pub/sub, `createAgentNetwork` for capability-based discovery and request/response patterns, plus the scratchpad and cross-agent state access available via a multi-agent orchestrator. Import from `@directive-run/ai`.
+
+## Decision tree
+
+```
+What do you need?
+├── Typed pub/sub between agents          → createMessageBus(config?)
+├── Capability lookup + request/response  → createAgentNetwork({ bus, agents? })
+├── Per-pattern ephemeral state           → context.scratchpad inside tasks/agents
+├── Reading another agent's facts         → orchestrator.system.facts[agentId].x
+└── Cross-agent derived state             → orchestrator.system.derive[agentId].x
+```
+
+## `createMessageBus(config?)`
+
+Fire-and-forget pub/sub keyed by `agentId`. `publish()` is synchronous — it returns the message id before delivery completes. Use `onDelivery` / `onDeliveryError` in config to observe delivery status.
+
+```typescript
+import { createMessageBus, type TypedAgentMessage } from "@directive-run/ai";
+
+const bus = createMessageBus({
+  maxHistory: 1000,
+  defaultTtlMs: 60 * 60 * 1000,
+  maxPendingPerAgent: 100,
+  onDelivery:      (msg, recipients) => log("delivered", msg.id, recipients),
+  onDeliveryError: (msg, error) => log("delivery_failed", msg.id, error.message),
+});
+
+// Subscribe — returns a Subscription object with an .unsubscribe() method
+const sub = bus.subscribe("writer", (message: TypedAgentMessage) => {
+  console.log(`writer received: ${message.type}`);
+});
+
+// Later
+sub.unsubscribe();
+
+// Publish — returns the message id (sync)
+const id = bus.publish({
+  type: "DELEGATION",
+  from: "researcher",
+  to: "writer",
+  task: "Summarize the findings",
+  context: { sources: 12 },
+});
+
+// Inspect
+bus.getHistory({ from: "researcher" }, 50);
+bus.getMessage(id);
+bus.getPending("writer"); // messages queued for an offline subscriber
+
+bus.clear();
+bus.destroy();
+```
+
+There is no `bus.request(...)` method — request/response lives on the AgentNetwork (next section).
+
+## `createAgentNetwork({ bus, agents? })`
+
+Wraps a MessageBus with registry, capability lookup, and request/response patterns. **Capability lookup returns `AgentInfo[]`, not `string[]`.** Request/response shapes — `request`, `delegate`, `query`, `broadcast`, `listen`, `send` — are all on the network, NOT on the bus.
+
+```typescript
+import { createAgentNetwork, type AgentInfo } from "@directive-run/ai";
+
+const network = createAgentNetwork({
+  bus,
+  agents: {
+    researcher: { capabilities: ["search", "verify", "cite"] },
+    writer:     { capabilities: ["draft", "edit", "summarize"] },
+    analyst:    { capabilities: ["analyze", "chart", "report"] },
+  },
+  defaultTimeout: 30_000,
+  onAgentOnline:  (id) => log(`${id} online`),
+  onAgentOffline: (id) => log(`${id} offline`),
+});
+
+// Find — returns AgentInfo[], not string[]
+const verifiers: AgentInfo[] = network.findByCapability("verify");
+verifiers.forEach((info) => console.log(info.id, info.capabilities));
+
+// Request/response with timeout
+const reply = await network.request("coordinator", "researcher", "verify-claim", {
+  claim: "GPT-4 has 1.8T parameters",
+}, 10_000);
+console.log(reply.payload);
+
+// Delegate a task and await its result
+const result = await network.delegate(
+  "coordinator",
+  "writer",
+  "Draft a 200-word summary",
+  { source: reply.payload },
+);
+
+// Question / answer
+const answer = await network.query("coordinator", "analyst", "What's the median latency?", { window: "24h" });
+
+// Broadcast to all agents
+network.broadcast("coordinator", { type: "INFORM", content: "Cache cleared" });
+
+// Plain fire-and-forget through the network (returns message id)
+network.send("coordinator", "writer", { type: "INFORM", content: "Starting batch" });
+
+// Subscribe an agent — same as bus.subscribe but registered through the network
+const sub = network.listen("writer", (msg) => console.log(msg.type));
+sub.unsubscribe();
+
+network.destroy();
+```
+
+There is no `network.route(capability, payload)` — pick the agent yourself via `findByCapability(...)`, then call `request` / `delegate` against the chosen `agent.id`.
+
+```typescript
+const candidates = network.findByCapability("verify");
+if (candidates.length === 0) throw new Error("no verifier available");
+const target = candidates[0];
+
+const result = await network.request("coordinator", target.id, "verify", { claim });
+```
+
+## Cross-agent state via facts + derivations
+
+Each agent in a multi-agent orchestrator becomes a namespaced module, so its facts and derivations are readable on `orchestrator.system`.
+
+```typescript
+const orchestrator = createMultiAgentOrchestrator({
+  agents: { researcher, writer },
+  runner,
+});
+
+orchestrator.start();
+
+// Read another agent's namespaced state (read-only outside its own resolvers)
+const status   = orchestrator.system.facts.researcher.status;
+const output   = orchestrator.system.facts.writer.output;
+const isReady  = orchestrator.system.derive.researcher.isComplete;
+```
+
+For a deeper treatment of multi-module fact access + cross-module dependencies, see `multi-module.md`.
+
+## Scratchpad — per-pattern ephemeral state
+
+The scratchpad is a read-only context object shared across tasks/agents inside a single pattern execution. **You cannot mutate `context.scratchpad` directly** — pass updates back through the task's return value, or use `network.send` / `bus.publish` for messages that outlive the pattern.
+
+```typescript
+tasks: {
+  gather: {
+    run: async (input, signal, context) => {
+      // context.scratchpad is Readonly — do NOT do context.scratchpad.x = …
+      const seed = context.scratchpad.seed;
+      return JSON.stringify({ seed, data: await fetchData(seed) });
+    },
+  },
+  format: {
+    run: async (input, signal, context) => {
+      // Read scratchpad written by the pattern config
+      const region = context.scratchpad.region;
+      const parsed = JSON.parse(input);
+      return JSON.stringify({ ...parsed, region });
+    },
+  },
+},
+```
+
+For full task surface, see `ai-tasks.md`.
+
+## Message bus + orchestrator wiring
+
+The orchestrator does NOT accept a `bus:` option directly — wire the bus alongside the orchestrator and route messages explicitly.
+
+```typescript
+import { createMultiAgentOrchestrator } from "@directive-run/ai/multi-agent";
+import { createMessageBus, createAgentNetwork } from "@directive-run/ai";
+
+const bus = createMessageBus({ maxHistory: 1000 });
+const network = createAgentNetwork({
+  bus,
+  agents: {
+    researcher: { capabilities: ["search", "verify"] },
+    writer:     { capabilities: ["draft", "edit"] },
+  },
+});
+
+const orchestrator = createMultiAgentOrchestrator({
+  agents: { researcher, writer },
+  runner,
+  hooks: {
+    onAgentStart: (e) => {
+      bus.publish({
+        type: "AGENT_START",
+        from: "orchestrator",
+        to: e.agentName,
+        input: e.input,
+      });
+    },
+  },
+});
+
+orchestrator.start();
+
+// External systems can publish to the bus directly
+bus.publish({
+  type: "INFORM",
+  from: "external-pipeline",
+  to: "researcher",
+  content: "New corpus available",
+});
+```
+
+## Anti-patterns
+
+### `bus.request(...)`
+
+```typescript
+// WRONG — there is no request method on MessageBus
+const reply = await bus.request({ type: "REQUEST", from: "a", to: "b", action: "verify", timeout: 10_000 });
+
+// CORRECT — request/response is on AgentNetwork
+const reply = await network.request("a", "b", "verify", { /* payload */ }, 10_000);
+```
+
+### `const unsub = bus.subscribe(...); unsub();`
+
+```typescript
+// WRONG — subscribe returns a Subscription object, not the unsubscribe function
+const unsub = bus.subscribe("writer", handler);
+unsub();
+
+// CORRECT — call .unsubscribe() on the returned Subscription
+const sub = bus.subscribe("writer", handler);
+sub.unsubscribe();
+```
+
+### `network.findByCapability(...)` returning strings
+
+```typescript
+// WRONG — assumes the return is string[]
+const writers = network.findByCapability("draft"); // ["writer"]?
+network.send("coordinator", writers[0], message);   // passes a string where AgentInfo was expected? No — but we lost capabilities/metadata
+
+// CORRECT — it returns AgentInfo[]; use .id when you need the string
+const candidates = network.findByCapability("draft");
+network.send("coordinator", candidates[0].id, message);
+```
+
+### `network.route(capability, payload)`
+
+```typescript
+// WRONG — no such method
+await network.route("verify", { claim });
+
+// CORRECT — pick an agent via findByCapability, then request/delegate
+const verifiers = network.findByCapability("verify");
+if (verifiers.length === 0) throw new Error("no verifier");
+const result = await network.request("coordinator", verifiers[0].id, "verify", { claim });
+```
+
+### `createMultiAgentOrchestrator({ bus })`
+
+```typescript
+// WRONG — bus is not an option on MultiAgentOrchestratorOptions
+createMultiAgentOrchestrator({ agents, runner, bus })
+
+// CORRECT — wire the bus separately and publish through hooks/handlers
+createMultiAgentOrchestrator({
+  agents,
+  runner,
+  hooks: {
+    onAgentComplete: (e) => bus.publish({ type: "AGENT_COMPLETE", from: "orchestrator", to: e.agentName, output: e.output }),
+  },
+});
+```
+
+### Mutating `context.scratchpad`
+
+```typescript
+// WRONG — context.scratchpad is Readonly
+context.scratchpad.researchData = data;
+context.scratchpad.timestamp = Date.now();
+
+// CORRECT — return new state from the task; or use bus.publish to broadcast
+return JSON.stringify({ ...JSON.parse(input), researchData: data, timestamp: Date.now() });
+```
+
+## Quick reference
+
+| API | Purpose | Notes |
+|---|---|---|
+| `createMessageBus(config?)` | Pub/sub primitive | `publish` / `subscribe` / `getHistory` / `getMessage` / `getPending` / `clear` / `destroy` |
+| `bus.subscribe(id, handler, filter?)` | Subscribe | returns a `Subscription` — call `sub.unsubscribe()` |
+| `createAgentNetwork({ bus, agents? })` | Capability-aware coordination | `request` / `delegate` / `query` / `broadcast` / `send` / `listen` / `findByCapability` |
+| `network.findByCapability(cap)` | Discovery | returns `AgentInfo[]` (NOT `string[]`) |
+| `network.request(from, to, action, payload, timeout?)` | Request/response | `Promise<ResponseMessage>` |
+| `network.delegate(from, to, task, context)` | Delegated task with result | `Promise<DelegationResultMessage>` |
+| `orchestrator.system.facts[agentId].x` | Cross-agent fact read | each agent is a namespaced module |
+| `context.scratchpad` | Per-pattern ephemeral state | Readonly inside tasks/agents |
+
+## See also
+
+- [`ai-multi-agent.md`](./ai-multi-agent.md) — the orchestrator that owns the namespaced facts this file's primitives read
+- [`ai-tasks.md`](./ai-tasks.md) — tasks share the scratchpad surface this file documents

package/skills/building-ai-agents/api-skeleton.md

@@ -0,0 +1,5 @@
+# API Skeleton
+
+> Auto-generated. Do not edit.
+
+> Source JSON not found. Build website docs first.