@directive-run/knowledge 0.2.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Jason Comes
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,63 @@
+# @directive-run/knowledge
+
+Knowledge files, examples, and validation scripts for the [Directive](https://directive.run) runtime.
+
+This package is the **source of truth** for all Directive coding knowledge used by:
+- `@directive-run/cli` — generates AI rules files (`.cursorrules`, `CLAUDE.md`, etc.)
+- `@directive-run/claude-plugin` — builds Claude Code plugin skills
+- `directive.run/llms.txt` — website LLM reference
+
+## Contents
+
+| Directory | Count | Description |
+|-----------|-------|-------------|
+| `core/` | 13 | Core Directive knowledge (modules, constraints, resolvers, etc.) |
+| `ai/` | 12 | AI orchestrator knowledge (agents, streaming, guardrails, etc.) |
+| `examples/` | 32 | Extracted examples (auto-generated, DOM wiring stripped) |
+| `api-skeleton.md` | 1 | Auto-generated API reference skeleton |
+
+## Programmatic API
+
+```typescript
+import {
+  getKnowledge,
+  getAllKnowledge,
+  getExample,
+  getAllExamples,
+  getKnowledgeFiles,
+  getExampleFiles,
+  clearCache,
+} from "@directive-run/knowledge";
+
+// Get a single knowledge file
+const patterns = getKnowledge("core-patterns");
+
+// Get multiple files joined with --- separator
+const combined = getKnowledgeFiles(["constraints", "resolvers"]);
+
+// Get all examples as a Map<name, content>
+const examples = getAllExamples();
+
+// Clear cached knowledge and examples (useful for dev/watch mode)
+clearCache();
+```
+
+## Scripts
+
+```bash
+pnpm --filter @directive-run/knowledge generate          # Regenerate api-skeleton.md
+pnpm --filter @directive-run/knowledge extract-examples  # Re-extract examples
+pnpm --filter @directive-run/knowledge validate          # Validate symbol references
+pnpm --filter @directive-run/knowledge test              # Run all tests
+pnpm --filter @directive-run/knowledge build             # Full build (generate + extract + tsup)
+```
+
+## Adding Examples
+
+Examples are **auto-discovered** from `examples/*/` in the repo root. The `extract-examples.ts` script:
+1. Scans all example directories
+2. Finds the best source file (prefers `<name>.ts` > `module.ts` > `main.ts`)
+3. Strips DOM wiring code
+4. Outputs clean TypeScript
+
+To exclude an example, add it to `EXCLUDED_EXAMPLES` in `scripts/extract-examples.ts`.

package/ai/ai-adapters.md

@@ -0,0 +1,250 @@
+# AI Adapters
+
+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.

package/ai/ai-agents-streaming.md

@@ -0,0 +1,269 @@
+# AI Agents and Streaming
+
+Defines the AgentLike interface (what runners receive), RunResult (what runners return), StreamChunk union types, backpressure strategies, and SSE transport.
+
+## Decision Tree: "How do I get output from an agent?"
+
+```
+Need the complete result?
+├── Yes → orchestrator.run(agent, prompt) → RunResult
+└── No, need incremental output
+    ├── AsyncIterable → orchestrator.runStream(agent, prompt)
+    ├── Callback-based → StreamingCallbackRunner
+    └── Server-Sent Events → createSSEResponse()
+        │
+        Backpressure concern?
+        ├── Consumer is slow → strategy: "block"
+        ├── Can drop tokens  → strategy: "drop"
+        └── Default          → strategy: "buffer"
+```
+
+## AgentLike — What the Runner Receives
+
+```typescript
+interface AgentLike {
+  // Required — unique identifier
+  name: string;
+
+  // System prompt / instructions
+  instructions?: string;
+
+  // Model identifier (adapter-specific)
+  model?: string;
+
+  // Tools the agent can use
+  tools?: unknown[];
+}
+
+// Usage
+const agent: AgentLike = {
+  name: "analyst",
+  instructions: "You analyze data and provide insights.",
+  model: "claude-sonnet-4-5",
+  tools: [searchTool, calculatorTool],
+};
+```
+
+## RunResult — What the Runner Returns
+
+```typescript
+interface RunResult<T = unknown> {
+  // The agent's final output
+  output: T;
+
+  // Full message history from this run
+  messages: Message[];
+
+  // Tool calls made during this run
+  toolCalls: ToolCall[];
+
+  // Total tokens consumed (input + output)
+  totalTokens: number;
+
+  // Detailed token breakdown
+  tokenUsage?: {
+    inputTokens: number;
+    outputTokens: number;
+  };
+}
+
+// Usage
+const result = await orchestrator.run(agent, "Analyze sales data");
+console.log(result.output);
+console.log(`Tokens used: ${result.totalTokens}`);
+console.log(`Tool calls: ${result.toolCalls.length}`);
+```
+
+## StreamChunk Union Types
+
+Each chunk from `runStream` is one of these discriminated union types:
+
+```typescript
+type StreamChunk =
+  // Text token from the model
+  | { type: "token"; data: string; tokenCount: number }
+
+  // Tool execution started
+  | { type: "tool_start"; tool: string; toolCallId: string; arguments: string }
+
+  // Tool execution completed
+  | { type: "tool_end"; tool: string; toolCallId: string; result: string }
+
+  // Complete message added to history
+  | { type: "message"; message: Message }
+
+  // Guardrail was triggered during streaming
+  | { type: "guardrail_triggered"; guardrailName: string; reason: string; stopped: boolean }
+
+  // Progress indicator
+  | { type: "progress"; phase: "starting" | "generating" | "tool_calling" | "finishing" }
+
+  // Stream completed
+  | { type: "done"; totalTokens: number; duration: number; droppedTokens: number }
+
+  // Error during streaming
+  | { type: "error"; error: Error };
+```
+
+## Consuming a Stream
+
+```typescript
+const stream = 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(`\nCalling tool: ${chunk.tool}`);
+      break;
+    case "tool_end":
+      console.log(`Tool 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}, Duration: ${chunk.duration}ms`);
+      break;
+    case "error":
+      console.error("Stream error:", chunk.error);
+      break;
+  }
+}
+```
+
+## Backpressure Strategies
+
+Control behavior when the consumer cannot keep up with token production:
+
+```typescript
+const stream = orchestrator.runStream(agent, "Generate long report", {
+  backpressure: "buffer",  // default — buffer all tokens in memory
+});
+
+const stream = orchestrator.runStream(agent, "Generate long report", {
+  backpressure: "block",   // pause generation until consumer catches up
+});
+
+const stream = orchestrator.runStream(agent, "Generate long report", {
+  backpressure: "drop",    // drop tokens consumer cannot process in time
+});
+```
+
+| 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 |
+
+When using `"drop"`, the `done` chunk reports `droppedTokens` count.
+
+## StreamingCallbackRunner
+
+For callback-based streaming (instead of AsyncIterable):
+
+```typescript
+import { createStreamingCallbackRunner } from "@directive-run/ai";
+
+const callbackRunner = createStreamingCallbackRunner(runner, {
+  onToken: (token) => process.stdout.write(token),
+  onToolStart: (tool, id) => console.log(`Tool: ${tool}`),
+  onToolEnd: (tool, id, result) => console.log(`Result: ${result}`),
+  onComplete: (result) => console.log("Done:", result.totalTokens),
+  onError: (error) => console.error(error),
+});
+
+// Use in orchestrator
+const orchestrator = createAgentOrchestrator({
+  runner: callbackRunner,
+});
+```
+
+## SSE Transport (Server-Sent Events)
+
+Pipe agent streaming to HTTP responses for web servers:
+
+```typescript
+import { createSSEResponse } from "@directive-run/ai";
+
+// Express / Node HTTP handler
+app.post("/api/chat", async (req, res) => {
+  const stream = orchestrator.runStream(agent, req.body.prompt);
+
+  // Creates a ReadableStream of SSE-formatted events
+  const sseResponse = createSSEResponse(stream);
+
+  res.setHeader("Content-Type", "text/event-stream");
+  res.setHeader("Cache-Control", "no-cache");
+  res.setHeader("Connection", "keep-alive");
+
+  for await (const event of sseResponse) {
+    res.write(event);
+  }
+
+  res.end();
+});
+```
+
+Client-side consumption:
+
+```typescript
+const eventSource = new EventSource("/api/chat");
+
+eventSource.onmessage = (event) => {
+  const chunk = JSON.parse(event.data);
+  if (chunk.type === "token") {
+    appendToDisplay(chunk.data);
+  }
+};
+```
+
+## Common Mistakes
+
+### Not checking chunk.type before accessing fields
+
+```typescript
+// WRONG — not all chunks have .data
+for await (const chunk of stream) {
+  console.log(chunk.data); // undefined for non-token chunks
+}
+
+// CORRECT — switch on chunk.type
+for await (const chunk of stream) {
+  if (chunk.type === "token") {
+    console.log(chunk.data);
+  }
+}
+```
+
+### Ignoring the stopped flag on guardrail chunks
+
+```typescript
+// WRONG — continuing after a stopping guardrail
+case "guardrail_triggered":
+  console.log("Guardrail triggered, continuing...");
+  break;
+
+// CORRECT — check if the stream was stopped
+case "guardrail_triggered":
+  if (chunk.stopped) {
+    console.error(`Stopped by ${chunk.guardrailName}: ${chunk.reason}`);
+    // Handle stream termination
+  }
+  break;
+```
+
+## Quick Reference
+
+| Type | Interface | Purpose |
+|---|---|---|
+| `AgentLike` | `{ name, instructions?, model?, tools? }` | Agent definition |
+| `RunResult` | `{ output, messages, toolCalls, totalTokens }` | Complete run result |
+| `StreamChunk` | Discriminated union (8 types) | Incremental output |
+| `StreamingCallbackRunner` | Callback-based adapter | Alternative to AsyncIterable |
+| `createSSEResponse` | SSE formatter | Web server streaming |