@directive-run/claude-plugin 1.16.0

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

@@ -0,0 +1,414 @@
+---
+name: building-ai-agents
+description: "Configure AI provider runners (Anthropic, OpenAI, Ollama), stream tokens and structured output, and wire cross-agent communication. Use when setting up LLM provider connections, implementing token streaming, choosing between providers, or building agents that communicate results to each other."
+---
+
+# Building AI Agents
+
+## Prerequisites
+
+This skill applies when the project uses `@directive-run/ai`. If not found in `package.json`, suggest installing it: `npm install @directive-run/ai`.
+
+## When Claude Should Use This Skill
+
+## Auto-Invoke Triggers
+- User asks which LLM provider to use or how to set one up
+- User wants to stream tokens or handle streaming responses
+- User mentions `createAnthropicRunner`, `createOpenAIRunner`, `createOllamaRunner`
+- User asks how agents share data or pass results between each other
+- User needs to switch providers or implement a provider abstraction
+
+## Exclusions
+- Do NOT invoke for orchestrator structure (constraints/resolvers) – use `building-ai-orchestrators`
+- Do NOT invoke for rate limits, budgets, or guardrails – use `hardening-ai-systems`
+- Do NOT invoke for testing runners – use `testing-ai-systems`
+
+---
+
+## Quick Reference
+
+## Decision Tree: Which Runner?
+
+```
+Choosing a provider?
+├── Production, best quality → createAnthropicRunner (claude-opus-4-6)
+├── Production, cost-efficient → createAnthropicRunner (claude-haiku-4-5)
+├── OpenAI ecosystem / GPT models → createOpenAIRunner
+├── Local / private / no API key → createOllamaRunner
+└── Custom provider → implement AgentRunner interface
+```
+
+## Decision Tree: Streaming vs Non-Streaming?
+
+```
+Need the response immediately as it arrives?
+├── Yes, show tokens as they generate → runStream() + "token" events
+├── Yes, but structured JSON → runStream() + "structured" events
+└── No, wait for full response → run()
+```
+
+---
+
+## Provider Runners
+
+### Anthropic
+
+```typescript
+import { createAnthropicRunner } from "@directive-run/ai/anthropic";
+
+const runner = createAnthropicRunner({
+  model: "claude-opus-4-6",           // or "claude-haiku-4-5", "claude-sonnet-4-6"
+  apiKey: process.env.ANTHROPIC_API_KEY,
+  maxTokens: 4096,                    // optional, default: 1024
+  temperature: 0.7,                   // optional, default: 1.0
+  systemPrompt: "You are helpful.",   // optional default system prompt
+});
+```
+
+### OpenAI
+
+```typescript
+import { createOpenAIRunner } from "@directive-run/ai/openai";
+
+const runner = createOpenAIRunner({
+  model: "gpt-4o",                    // or "gpt-4o-mini", "gpt-3.5-turbo"
+  apiKey: process.env.OPENAI_API_KEY,
+  maxTokens: 4096,
+  temperature: 0.7,
+  organization: "org-...",            // optional
+});
+```
+
+### Ollama (Local)
+
+```typescript
+import { createOllamaRunner } from "@directive-run/ai/ollama";
+
+const runner = createOllamaRunner({
+  model: "llama3.2",                  // any Ollama-installed model
+  baseUrl: "http://localhost:11434",  // default Ollama endpoint
+  temperature: 0.8,
+});
+```
+
+---
+
+## Running LLM Calls Inside Resolvers
+
+```typescript
+resolvers: {
+  generate: {
+    requirement: "GENERATE",
+    resolve: async (req, context) => {
+      // Basic call – returns full response when complete
+      const result = await context.runner.run({
+        prompt: "Explain quantum entanglement simply.",
+        system: "You are a science communicator.",
+        maxTokens: 500,
+      });
+
+      context.facts.output = result.text;
+      context.facts.tokenUsage = result.usage.totalTokens;
+    },
+  },
+},
+```
+
+## Runner Result Shape
+
+```typescript
+interface RunnerResult {
+  text: string;           // Generated text
+  usage: {
+    inputTokens: number;
+    outputTokens: number;
+    totalTokens: number;
+  };
+  model: string;          // Model used
+  stopReason: "end_turn" | "max_tokens" | "stop_sequence";
+  raw: unknown;           // Raw provider response
+}
+```
+
+---
+
+## Streaming
+
+### Token Streaming
+
+```typescript
+// orchestrator.runStream() returns AsyncIterable<OrchestratorEvent>
+const stream = orchestrator.runStream({ input: "Write a story about..." });
+
+for await (const event of stream) {
+  if (event.type === "token") {
+    // Arrives as the LLM generates – display immediately
+    process.stdout.write(event.text);
+  }
+
+  if (event.type === "done") {
+    console.log("\nFinal facts:", event.facts);
+  }
+
+  if (event.type === "error") {
+    console.error("Stream error:", event.error.message);
+    break;
+  }
+}
+```
+
+### All Stream Event Types
+
+```typescript
+type OrchestratorEvent =
+  | { type: "token"; text: string; agentId?: string }
+  | { type: "requirement_met"; requirementType: string; agentId?: string }
+  | { type: "requirement_queued"; requirementType: string }
+  | { type: "agent_started"; agentId: string }
+  | { type: "agent_done"; agentId: string }
+  | { type: "done"; facts: Record<string, unknown> }
+  | { type: "error"; error: Error };
+```
+
+### Structured Output Streaming
+
+```typescript
+import { z } from "zod";
+
+// When you need typed JSON output, not raw text
+const result = await context.runner.runStructured({
+  prompt: "Extract product info from this description: ...",
+  schema: z.object({
+    name: z.string(),
+    price: z.number(),
+    inStock: z.boolean(),
+  }),
+});
+
+// result.data is typed to the schema
+context.facts.productName = result.data.name;
+context.facts.price = result.data.price;
+```
+
+### Emitting Custom Stream Events from Resolvers
+
+```typescript
+resolve: async (req, context) => {
+  // Emit custom events consumers can observe
+  context.emit({ type: "token", text: "Starting analysis..." });
+
+  const result = await context.runner.run({ prompt: req.input });
+
+  context.emit({ type: "token", text: result.text });
+  context.facts.output = result.text;
+},
+```
+
+---
+
+## Cross-Agent Communication
+
+### Via Coordinator Facts (Recommended)
+
+In `createMultiAgentOrchestrator`, agents share coordinator facts. The coordinator acts as the message bus.
+
+```typescript
+// researcher agent writes to coordinator facts
+resolve: async (req, context) => {
+  const result = await context.runner.run({ prompt: "Research AI trends..." });
+  // Writing to shared coordinator facts signals the next agent
+  context.facts.researchComplete = true;
+  context.facts.researchNotes = result.text;
+},
+
+// writer agent reads coordinator facts set by researcher
+constraints: {
+  startWriting: {
+    // Only activates after researcher signals completion
+    when: (facts) => facts.researchComplete && !!facts.researchNotes,
+    require: { type: "WRITE_ARTICLE" },
+  },
+},
+```
+
+### Via Requirement Payload
+
+```typescript
+// Pass structured data in the requirement itself
+constraints: {
+  routeToSpecialist: {
+    when: (facts) => facts.analysisType === "legal",
+    require: (facts) => ({
+      type: "SPECIALIST_REVIEW",
+      category: facts.analysisType,
+      priority: facts.urgency,
+      content: facts.draftOutput,
+    }),
+  },
+},
+
+resolvers: {
+  specialistReview: {
+    requirement: "SPECIALIST_REVIEW",
+    resolve: async (req, context) => {
+      // req contains { category, priority, content } from above
+      const result = await context.runner.run({
+        prompt: `Review this ${req.category} content: ${req.content}`,
+      });
+      context.facts.reviewedOutput = result.text;
+    },
+  },
+},
+```
+
+---
+
+## Custom Provider – Implement AgentRunner Interface
+
+```typescript
+import type { AgentRunner, RunOptions, RunnerResult } from "@directive-run/ai";
+
+class MyCustomRunner implements AgentRunner {
+  async run(options: RunOptions): Promise<RunnerResult> {
+    // Call your provider
+    const response = await myProviderClient.generate({
+      prompt: options.prompt,
+      system: options.system,
+    });
+
+    return {
+      text: response.text,
+      usage: {
+        inputTokens: response.usage.input,
+        outputTokens: response.usage.output,
+        totalTokens: response.usage.total,
+      },
+      model: "my-custom-model",
+      stopReason: "end_turn",
+      raw: response,
+    };
+  }
+
+  // Optional: implement for streaming support
+  async *runStream(options: RunOptions): AsyncIterable<string> {
+    for await (const chunk of myProviderClient.stream(options)) {
+      yield chunk.text;
+    }
+  }
+}
+```
+
+---
+
+## Multi-Turn Conversations
+
+```typescript
+// Maintain conversation history in facts
+factsSchema: {
+  messages: t.array(t.object<{ role: "user" | "assistant"; content: string }>()),
+  latestInput: t.string(),
+  latestOutput: t.string().optional(),
+},
+
+init: (facts) => {
+  facts.messages = [];
+},
+
+resolve: async (req, context) => {
+  // Add user message to history
+  context.facts.messages.push({
+    role: "user",
+    content: context.facts.latestInput,
+  });
+
+  const result = await context.runner.run({
+    messages: context.facts.messages,  // Pass full history
+    system: "You are a helpful assistant.",
+  });
+
+  // Add assistant reply to history
+  context.facts.messages.push({
+    role: "assistant",
+    content: result.text,
+  });
+
+  context.facts.latestOutput = result.text;
+},
+```
+
+---
+
+## Critical Anti-Patterns
+
+## Not handling stream errors
+
+```typescript
+// WRONG – if stream throws, it crashes uncaught
+for await (const event of orchestrator.runStream(input)) {
+  if (event.type === "token") {
+    process.stdout.write(event.text);
+  }
+}
+
+// CORRECT – always handle error events
+for await (const event of orchestrator.runStream(input)) {
+  if (event.type === "token") {
+    process.stdout.write(event.text);
+  }
+
+  if (event.type === "error") {
+    console.error("Stream failed:", event.error.message);
+    break;
+  }
+}
+```
+
+## Blocking on stream consumption inside a resolver
+
+```typescript
+// WRONG – consuming a stream inside a resolver blocks the engine
+resolve: async (req, context) => {
+  const stream = orchestrator.runStream(req.input);
+  for await (const event of stream) { /* deadlock risk */ }
+},
+
+// CORRECT – use context.runner.run() inside resolvers
+resolve: async (req, context) => {
+  const result = await context.runner.run({ prompt: req.input });
+  context.facts.output = result.text;
+},
+```
+
+### Resolver parameter naming
+Always use `(req, context)` – never `(req, ctx)` or `(request, context)`.
+
+## Hardcoding API keys
+
+```typescript
+// WRONG
+const runner = createAnthropicRunner({ apiKey: "sk-ant-..." });
+
+// CORRECT
+const runner = createAnthropicRunner({ apiKey: process.env.ANTHROPIC_API_KEY });
+```
+
+## Ignoring token usage
+
+```typescript
+// WRONG – fire and forget, no budget awareness
+const result = await context.runner.run({ prompt });
+context.facts.output = result.text;
+
+// CORRECT – track usage for budget management
+const result = await context.runner.run({ prompt });
+context.facts.output = result.text;
+context.facts.tokensUsed = (context.facts.tokensUsed ?? 0) + result.usage.totalTokens;
+```
+
+---
+
+## Reference Files
+
+- `ai-agents-streaming.md` – Streaming events, AsyncIterable patterns, token buffering
+- `ai-adapters.md` – Provider adapter interface, all runner options, custom runner guide
+- `ai-communication.md` – Cross-agent communication, coordinator facts, requirement payloads

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

@@ -0,0 +1,257 @@
+# AI Adapters
+
+> Covers `@directive-run/ai/{openai,anthropic,ollama,gemini}` — provider runners that normalize to the `AgentRunner` interface (zero SDK deps).
+
+Adapters connect the orchestrator to LLM providers. Each adapter normalizes provider-specific APIs into Directive's `AgentRunner` interface.
+
+## Decision Tree: "Which adapter do I need?"
+
+```
+Which LLM provider?
+├── Anthropic (Claude) → createAnthropicRunner from '@directive-run/ai/anthropic'
+├── OpenAI (GPT)       → createOpenAIRunner from '@directive-run/ai/openai'
+├── Google (Gemini)    → createGeminiRunner from '@directive-run/ai/gemini'
+└── Ollama (local)     → createOllamaRunner from '@directive-run/ai/ollama'
+    │
+    Need streaming?
+    ├── Yes → create*StreamingRunner from the same subpath
+    └── No  → create*Runner is sufficient
+    │
+    Need a proxy/self-hosted URL?
+    └── Yes → pass baseURL option
+```
+
+## CRITICAL: Subpath Imports
+
+Every adapter MUST be imported from its subpath. The main `@directive-run/ai` entry does NOT export adapters.
+
+```typescript
+// CORRECT – subpath imports
+import { createAnthropicRunner } from "@directive-run/ai/anthropic";
+import { createOpenAIRunner } from "@directive-run/ai/openai";
+import { createOllamaRunner } from "@directive-run/ai/ollama";
+import { createGeminiRunner } from "@directive-run/ai/gemini";
+```
+
+### Anti-Pattern #26: Importing adapters from the main entry
+
+```typescript
+// WRONG – adapters are NOT exported from the main package
+import { createOpenAIRunner } from "@directive-run/ai";
+import { createAnthropicRunner } from "@directive-run/ai";
+
+// CORRECT – use subpath imports
+import { createOpenAIRunner } from "@directive-run/ai/openai";
+import { createAnthropicRunner } from "@directive-run/ai/anthropic";
+```
+
+## Anthropic Adapter
+
+```typescript
+import {
+  createAnthropicRunner,
+  createAnthropicStreamingRunner,
+} from "@directive-run/ai/anthropic";
+
+// Standard runner
+const runner = createAnthropicRunner({
+  apiKey: process.env.ANTHROPIC_API_KEY,
+  defaultModel: "claude-sonnet-4-5",
+  maxTokens: 4096,
+});
+
+// Streaming runner
+const streamingRunner = createAnthropicStreamingRunner({
+  apiKey: process.env.ANTHROPIC_API_KEY,
+  defaultModel: "claude-sonnet-4-5",
+  maxTokens: 4096,
+});
+
+// With proxy URL
+const proxiedRunner = createAnthropicRunner({
+  apiKey: process.env.ANTHROPIC_API_KEY,
+  baseURL: "https://my-proxy.example.com/v1",
+});
+```
+
+## OpenAI Adapter
+
+```typescript
+import {
+  createOpenAIRunner,
+  createOpenAIStreamingRunner,
+} from "@directive-run/ai/openai";
+
+const runner = createOpenAIRunner({
+  apiKey: process.env.OPENAI_API_KEY,
+  defaultModel: "gpt-4o",
+  organization: "org-xxx", // Optional
+});
+
+// Azure OpenAI
+const azureRunner = createOpenAIRunner({
+  apiKey: process.env.AZURE_OPENAI_KEY,
+  baseURL: "https://my-instance.openai.azure.com/openai/deployments/gpt-4o",
+  defaultHeaders: {
+    "api-version": "2024-02-01",
+  },
+});
+```
+
+## Ollama Adapter (Local Models)
+
+```typescript
+import {
+  createOllamaRunner,
+  createOllamaStreamingRunner,
+} from "@directive-run/ai/ollama";
+
+const runner = createOllamaRunner({
+  // Default: http://localhost:11434
+  baseURL: "http://localhost:11434",
+  defaultModel: "llama3.1",
+});
+
+// Remote Ollama instance
+const remoteRunner = createOllamaRunner({
+  baseURL: "https://ollama.my-server.com",
+  defaultModel: "mistral",
+});
+```
+
+## Gemini Adapter
+
+```typescript
+import {
+  createGeminiRunner,
+  createGeminiStreamingRunner,
+} from "@directive-run/ai/gemini";
+
+const runner = createGeminiRunner({
+  apiKey: process.env.GOOGLE_API_KEY,
+  defaultModel: "gemini-2.0-flash",
+});
+```
+
+## Token Normalization
+
+### Anti-Pattern #27: Assuming provider-specific token structure
+
+```typescript
+// WRONG – Anthropic returns { input_tokens, output_tokens } natively
+// but adapters normalize this
+const result = await runner.run(agent, prompt);
+console.log(result.tokenUsage.input_tokens); // undefined!
+
+// CORRECT – adapters normalize to camelCase
+const result = await runner.run(agent, prompt);
+console.log(result.tokenUsage.inputTokens);   // number
+console.log(result.tokenUsage.outputTokens);   // number
+console.log(result.totalTokens);               // inputTokens + outputTokens
+```
+
+All adapters normalize token usage to the same shape regardless of provider:
+
+```typescript
+interface NormalizedTokenUsage {
+  inputTokens: number;
+  outputTokens: number;
+}
+
+// result.totalTokens = inputTokens + outputTokens
+```
+
+## Adapter Hooks
+
+Every adapter supports lifecycle hooks for logging, metrics, or request modification:
+
+```typescript
+const runner = createAnthropicRunner({
+  apiKey: process.env.ANTHROPIC_API_KEY,
+  hooks: {
+    // Called before every LLM API call
+    onBeforeCall: (agent, prompt, options) => {
+      console.log(`Calling ${agent.model} for ${agent.name}`);
+      metrics.increment("llm.calls");
+    },
+
+    // Called after every successful LLM API call
+    onAfterCall: (agent, result) => {
+      console.log(`${agent.name}: ${result.totalTokens} tokens`);
+      metrics.histogram("llm.tokens", result.totalTokens);
+    },
+
+    // Called on LLM API errors
+    onError: (agent, error) => {
+      console.error(`${agent.name} failed:`, error.message);
+      metrics.increment("llm.errors");
+    },
+  },
+});
+```
+
+## Using Adapters with Orchestrators
+
+```typescript
+import { createAgentOrchestrator } from "@directive-run/ai";
+import { createAnthropicRunner } from "@directive-run/ai/anthropic";
+
+const runner = createAnthropicRunner({
+  apiKey: process.env.ANTHROPIC_API_KEY,
+});
+
+// Single-agent
+const orchestrator = createAgentOrchestrator({ runner });
+
+// Multi-agent – same runner shared across all agents
+const multiOrchestrator = createMultiAgentOrchestrator({
+  agents: { /* ... */ },
+  runner,
+});
+```
+
+## Switching Adapters
+
+Adapters are interchangeable. Switch providers by changing the import and config:
+
+```typescript
+// Before: Anthropic
+import { createAnthropicRunner } from "@directive-run/ai/anthropic";
+const runner = createAnthropicRunner({
+  apiKey: process.env.ANTHROPIC_API_KEY,
+});
+
+// After: OpenAI – same orchestrator, different runner
+import { createOpenAIRunner } from "@directive-run/ai/openai";
+const runner = createOpenAIRunner({
+  apiKey: process.env.OPENAI_API_KEY,
+});
+
+// Orchestrator code remains unchanged
+const orchestrator = createAgentOrchestrator({ runner });
+```
+
+## Custom BaseURL Patterns
+
+| Provider | Default BaseURL | Custom Use Case |
+|---|---|---|
+| Anthropic | `https://api.anthropic.com` | Corporate proxy, VPN relay |
+| OpenAI | `https://api.openai.com/v1` | Azure OpenAI, LiteLLM proxy |
+| Ollama | `http://localhost:11434` | Remote GPU server |
+| Gemini | `https://generativelanguage.googleapis.com` | Regional endpoint |
+
+## Quick Reference
+
+| Adapter | Import Path | Key Options |
+|---|---|---|
+| Anthropic | `@directive-run/ai/anthropic` | `apiKey`, `defaultModel`, `maxTokens` |
+| OpenAI | `@directive-run/ai/openai` | `apiKey`, `defaultModel`, `organization` |
+| Ollama | `@directive-run/ai/ollama` | `baseURL`, `defaultModel` |
+| Gemini | `@directive-run/ai/gemini` | `apiKey`, `defaultModel` |
+
+All adapters support: `baseURL`, `defaultHeaders`, `hooks`, streaming variant.
+
+## See also
+
+- [`ai-orchestrator.md`](./ai-orchestrator.md) — where the `AgentRunner` an adapter produces gets consumed
+- [`ai-agents-streaming.md`](./ai-agents-streaming.md) — the `StreamingCallbackRunner` shape each adapter's streaming variant satisfies