@directive-run/knowledge 0.2.0

package/ai/ai-budget-resilience.md

@@ -0,0 +1,235 @@
+# AI Budget and Resilience
+
+Budget wrappers, retry policies, fallback chains, circuit breakers, health monitors, semantic caching, and constraint-driven provider routing for AI runners.
+
+## Decision Tree: "How do I protect my AI calls?"
+
+```
+What failure mode are you guarding against?
+├── Cost overruns → withBudget(runner, { budgets: [...] })
+├── Transient errors → withRetry(runner, { maxRetries, backoff })
+├── Provider outage → withFallback(primaryRunner, fallbackRunner)
+├── Repeated failures → createCircuitBreaker({ failureThreshold })
+├── Fleet monitoring → createHealthMonitor({ agents: {...} })
+│
+Want to avoid redundant LLM calls?
+├── Yes, similar inputs → createSemanticCache({ embedder, similarity })
+│
+Need dynamic provider selection?
+└── Yes → createConstraintRouter({ providers: [...], constraints: [...] })
+```
+
+## Budget Wrapping
+
+Wrap any runner with cost tracking and enforcement per time window:
+
+```typescript
+import { withBudget } from "@directive-run/ai";
+
+const budgetRunner = withBudget(baseRunner, {
+  // Hard cap per single LLM call
+  maxCostPerCall: 0.10,
+
+  // Time-window budgets (multiple allowed)
+  budgets: [
+    {
+      window: "hour",
+      maxCost: 1.0,
+      pricing: { inputPerMillion: 3, outputPerMillion: 15 },
+    },
+    {
+      window: "day",
+      maxCost: 10.0,
+      pricing: { inputPerMillion: 3, outputPerMillion: 15 },
+    },
+  ],
+
+  // Callback when approaching limit (0-1 percentage)
+  budgetWarningThreshold: 0.8,
+  onWarning: (usage) => {
+    console.warn(`Budget at ${(usage.percentage * 100).toFixed(0)}%`);
+  },
+});
+```
+
+### Anti-Pattern #29: budgetWarningThreshold out of range
+
+```typescript
+// WRONG — threshold must be a 0-1 percentage
+const budgetRunner = withBudget(baseRunner, {
+  budgetWarningThreshold: 80, // Not a percentage!
+  budgets: [{ window: "hour", maxCost: 1.0, pricing: { inputPerMillion: 3, outputPerMillion: 15 } }],
+});
+
+// CORRECT — use a decimal between 0 and 1
+const budgetRunner = withBudget(baseRunner, {
+  budgetWarningThreshold: 0.8, // 80%
+  budgets: [{ window: "hour", maxCost: 1.0, pricing: { inputPerMillion: 3, outputPerMillion: 15 } }],
+});
+```
+
+## Retry Policies
+
+Wrap a runner with automatic retry on transient failures:
+
+```typescript
+import { withRetry } from "@directive-run/ai";
+
+const retryRunner = withRetry(baseRunner, {
+  maxRetries: 3,
+  backoff: "exponential", // "exponential" | "linear" | "none"
+  baseDelayMs: 100,
+
+  // Only retry specific errors
+  shouldRetry: (error) => {
+    return error.status === 429 || error.status >= 500;
+  },
+});
+```
+
+## Fallback Chains
+
+Automatically switch to a backup runner when the primary fails:
+
+```typescript
+import { withFallback } from "@directive-run/ai";
+import { createAnthropicRunner } from "@directive-run/ai/anthropic";
+import { createOpenAIRunner } from "@directive-run/ai/openai";
+
+const primary = createAnthropicRunner({ apiKey: process.env.ANTHROPIC_API_KEY });
+const backup = createOpenAIRunner({ apiKey: process.env.OPENAI_API_KEY });
+
+// Falls back to backup when primary throws
+const resilientRunner = withFallback(primary, backup);
+```
+
+## Circuit Breaker
+
+Prevent repeated calls to a failing provider. Opens after N failures, resets after a timeout:
+
+```typescript
+import { createCircuitBreaker } from "@directive-run/ai";
+
+const breaker = createCircuitBreaker({
+  failureThreshold: 3,     // Open after 3 consecutive failures
+  resetTimeout: 30000,     // Try again after 30s (half-open state)
+  halfOpenMaxAttempts: 1,  // Allow 1 test request in half-open
+});
+
+// Use with a runner
+const protectedRunner = breaker.wrap(baseRunner);
+
+// Check state
+console.log(breaker.state); // "closed" | "open" | "half-open"
+breaker.reset();            // Force back to closed
+```
+
+### Anti-Pattern #28: Sharing a CircuitBreaker across unrelated agents
+
+```typescript
+// WRONG — one failing agent opens the breaker for all agents
+const sharedBreaker = createCircuitBreaker({ failureThreshold: 3, resetTimeout: 30000 });
+const researchRunner = sharedBreaker.wrap(baseRunner);
+const writerRunner = sharedBreaker.wrap(baseRunner); // Same breaker!
+
+// CORRECT — each agent gets its own breaker instance
+const researchBreaker = createCircuitBreaker({ failureThreshold: 3, resetTimeout: 30000 });
+const writerBreaker = createCircuitBreaker({ failureThreshold: 3, resetTimeout: 30000 });
+
+const researchRunner = researchBreaker.wrap(baseRunner);
+const writerRunner = writerBreaker.wrap(baseRunner);
+```
+
+## Health Monitor
+
+Monitor agent health across the system, track circuit breaker states, and report status:
+
+```typescript
+import { createHealthMonitor } from "@directive-run/ai";
+
+const monitor = createHealthMonitor({
+  agents: {
+    researcher: { runner: researchRunner, circuitBreaker: researchBreaker },
+    writer: { runner: writerRunner, circuitBreaker: writerBreaker },
+  },
+  checkInterval: 60000, // Health check every 60s
+
+  onStatusChange: (agent, status) => {
+    console.log(`${agent}: ${status}`); // "healthy" | "degraded" | "unhealthy"
+  },
+});
+
+monitor.start();
+const report = monitor.getReport();
+monitor.stop();
+```
+
+## Semantic Cache
+
+Cache LLM responses by semantic similarity to avoid redundant calls:
+
+```typescript
+import { createSemanticCache } from "@directive-run/ai";
+import { createOpenAIEmbedder } from "@directive-run/ai/openai";
+
+const cache = createSemanticCache({
+  embedder: createOpenAIEmbedder({ apiKey: process.env.OPENAI_API_KEY }),
+  similarity: 0.98,   // Minimum cosine similarity to count as a hit
+  maxSize: 1000,       // Max cached entries (LRU eviction)
+  ttl: 3600000,        // Cache entry TTL in ms (1 hour)
+});
+
+// Wrap a runner with caching
+const cachedRunner = cache.wrap(baseRunner);
+```
+
+## Constraint-Driven Provider Routing
+
+Route LLM calls to different providers based on runtime constraints:
+
+```typescript
+import { createConstraintRouter } from "@directive-run/ai";
+
+const router = createConstraintRouter({
+  providers: [
+    { name: "anthropic", runner: anthropicRunner, costPerMillion: 3 },
+    { name: "openai", runner: openaiRunner, costPerMillion: 5 },
+    { name: "ollama", runner: ollamaRunner, costPerMillion: 0 },
+  ],
+  constraints: [
+    // Use cheapest provider when budget is low
+    { when: (context) => context.budgetRemaining < 1.0, prefer: "ollama" },
+    // Use best provider for high-priority tasks
+    { when: (context) => context.priority === "high", prefer: "anthropic" },
+  ],
+});
+```
+
+## Combining Wrappers
+
+Wrappers compose — apply them inside-out (innermost runs first):
+
+```typescript
+import { withBudget, withRetry, withFallback } from "@directive-run/ai";
+
+// Order: retry → budget → fallback
+const resilientRunner = withFallback(
+  withBudget(
+    withRetry(primaryRunner, { maxRetries: 3, backoff: "exponential", baseDelayMs: 100 }),
+    { budgets: [{ window: "hour", maxCost: 1.0, pricing: { inputPerMillion: 3, outputPerMillion: 15 } }] },
+  ),
+  fallbackRunner,
+);
+```
+
+## Quick Reference
+
+| Utility | Purpose | Key Options |
+|---|---|---|
+| `withBudget` | Cost caps per time window | `budgets`, `maxCostPerCall` |
+| `withRetry` | Retry transient failures | `maxRetries`, `backoff`, `shouldRetry` |
+| `withFallback` | Switch to backup runner | primary, fallback runners |
+| `createCircuitBreaker` | Stop calling failing providers | `failureThreshold`, `resetTimeout` |
+| `createHealthMonitor` | Fleet health tracking | `agents`, `checkInterval` |
+| `createSemanticCache` | Avoid redundant LLM calls | `similarity`, `maxSize`, `ttl` |
+| `createConstraintRouter` | Dynamic provider selection | `providers`, `constraints` |

package/ai/ai-communication.md

@@ -0,0 +1,281 @@
+# AI Communication
+
+Cross-agent messaging, agent networks, shared state via derivations, scratchpad coordination, and handoff patterns.
+
+## Decision Tree: "How do agents communicate?"
+
+```
+What kind of communication?
+├── Fire-and-forget notification → bus.publish({ type: "INFORM", ... })
+├── Request-response (await reply) → bus.request({ type: "REQUEST", ... })
+├── Delegate work to another agent → bus.publish({ type: "DELEGATION", ... })
+├── Subscribe to ongoing updates → bus.publish({ type: "SUBSCRIBE", ... })
+│
+How do agents share state?
+├── Read another agent's facts → orchestrator.system.facts.agentName.key
+├── Cross-agent derivations → orchestrator.derive.agentName.derivation
+├── Ephemeral key-value store → context.scratchpad
+│
+How do agents hand off work?
+├── One-time transfer → handoff pattern (DELEGATION + await DELEGATION_RESULT)
+├── Ongoing collaboration → agent network with capabilities
+└── Conditional routing → reroute in supervisor pattern
+```
+
+## Message Bus
+
+The message bus enables structured communication between agents:
+
+```typescript
+import { createMessageBus } from "@directive-run/ai";
+
+const bus = createMessageBus();
+```
+
+## Publishing Messages
+
+```typescript
+// Fire-and-forget notification
+bus.publish({
+  type: "INFORM",
+  from: "researcher",
+  to: "writer",
+  content: "Found 5 relevant sources",
+  metadata: { sourceCount: 5, topics: ["AI", "ML"] },
+});
+
+// Broadcast to all agents (omit "to")
+bus.publish({
+  type: "INFORM",
+  from: "coordinator",
+  content: "System entering maintenance mode",
+});
+```
+
+## Request-Response Pattern
+
+```typescript
+// Send a request and await the response
+const response = await bus.request({
+  type: "REQUEST",
+  from: "writer",
+  to: "researcher",
+  action: "verify_claim",
+  payload: { claim: "Transformers were invented in 2017" },
+  timeout: 5000, // Throws after 5s if no response
+});
+
+console.log(response.content); // "Verified: correct"
+console.log(response.metadata); // { confidence: 0.95, source: "..." }
+```
+
+## Message Types
+
+All 11 message types in the system:
+
+| Type | Direction | Purpose |
+|---|---|---|
+| `REQUEST` | Agent-to-agent | Ask another agent to do something |
+| `RESPONSE` | Agent-to-agent | Reply to a REQUEST |
+| `DELEGATION` | Agent-to-agent | Hand off a task to another agent |
+| `DELEGATION_RESULT` | Agent-to-agent | Return result of delegated work |
+| `QUERY` | Agent-to-agent | Ask for information without side effects |
+| `INFORM` | Agent-to-agent/all | Share information, no response expected |
+| `SUBSCRIBE` | Agent-to-agent | Request ongoing updates on a topic |
+| `UNSUBSCRIBE` | Agent-to-agent | Stop receiving updates |
+| `UPDATE` | Agent-to-subscriber | Push update to a subscriber |
+| `ACK` | Agent-to-agent | Acknowledge receipt |
+| `NACK` | Agent-to-agent | Reject or refuse a message |
+
+## Subscribing to Messages
+
+```typescript
+// Subscribe to all messages for an agent
+const unsubscribe = bus.subscribe("writer", (message) => {
+  switch (message.type) {
+    case "INFORM":
+      console.log(`Info from ${message.from}: ${message.content}`);
+      break;
+    case "REQUEST":
+      // Handle and respond
+      bus.publish({
+        type: "RESPONSE",
+        from: "writer",
+        to: message.from,
+        correlationId: message.id,
+        content: "Done",
+      });
+      break;
+  }
+});
+
+// Clean up
+unsubscribe();
+```
+
+## Agent Network
+
+Higher-level abstraction for capability-based agent discovery:
+
+```typescript
+import { createAgentNetwork } from "@directive-run/ai";
+
+const network = createAgentNetwork({
+  bus,
+  agents: {
+    researcher: {
+      capabilities: ["search", "verify", "cite"],
+    },
+    writer: {
+      capabilities: ["draft", "edit", "summarize"],
+    },
+    analyst: {
+      capabilities: ["analyze", "chart", "report"],
+    },
+  },
+});
+
+// Find agents by capability
+const writers = network.findByCapability("draft");
+// ["writer"]
+
+const verifiers = network.findByCapability("verify");
+// ["researcher"]
+
+// Route a request to the best agent for a capability
+const result = await network.route("verify", {
+  claim: "GPT-4 has 1.8T parameters",
+});
+```
+
+## Cross-Agent State via Derivations
+
+Agents can read each other's facts and derivations through the shared system:
+
+```typescript
+const orchestrator = createMultiAgentOrchestrator({
+  agents: {
+    researcher: {
+      name: "researcher",
+      instructions: "...",
+      model: "claude-sonnet-4-5",
+    },
+    writer: {
+      name: "writer",
+      instructions: "...",
+      model: "claude-sonnet-4-5",
+    },
+  },
+  runner,
+});
+
+orchestrator.start();
+
+// Read another agent's facts (read-only)
+const researchStatus = orchestrator.system.facts.researcher.status;
+const writerOutput = orchestrator.system.facts.writer.lastOutput;
+
+// Cross-agent derivations react to fact changes
+const isReady = orchestrator.system.derive.researcher.isComplete;
+```
+
+## Scratchpad Coordination
+
+The scratchpad is an ephemeral key-value store scoped to a single pattern execution. Tasks and agents in the same pattern share it:
+
+```typescript
+// In a task — write to scratchpad
+tasks: {
+  gather: {
+    run: async (input, context) => {
+      const data = JSON.parse(input);
+      context.scratchpad.researchData = data;
+      context.scratchpad.timestamp = Date.now();
+
+      return input;
+    },
+  },
+  format: {
+    run: async (input, context) => {
+      // Read from scratchpad set by earlier task
+      const data = context.scratchpad.researchData;
+      const ts = context.scratchpad.timestamp as number;
+
+      return JSON.stringify({ data, processedAt: ts });
+    },
+  },
+},
+```
+
+## Handoff Patterns
+
+### One-Time Delegation
+
+```typescript
+// Agent A delegates work to Agent B
+bus.publish({
+  type: "DELEGATION",
+  from: "coordinator",
+  to: "researcher",
+  content: "Research the topic: quantum computing",
+  metadata: { priority: "high", deadline: Date.now() + 60000 },
+});
+
+// Agent B returns the result
+bus.publish({
+  type: "DELEGATION_RESULT",
+  from: "researcher",
+  to: "coordinator",
+  correlationId: originalMessage.id,
+  content: "Research findings: ...",
+  metadata: { sourcesFound: 12 },
+});
+```
+
+### Supervisor Reroute
+
+In a supervisor pattern, the supervisor can reroute work mid-execution:
+
+```typescript
+const managed = supervisor("editor", ["researcher", "writer"], {
+  onReroute: (from, to, reason) => {
+    console.log(`Rerouting from ${from} to ${to}: ${reason}`);
+  },
+});
+```
+
+## Message Bus with Orchestrator
+
+```typescript
+import { createMultiAgentOrchestrator, createMessageBus } from "@directive-run/ai";
+
+const bus = createMessageBus();
+
+const orchestrator = createMultiAgentOrchestrator({
+  agents: { researcher, writer },
+  runner,
+  bus, // Attach the message bus
+});
+
+orchestrator.start();
+
+// External systems can also publish to the bus
+bus.publish({
+  type: "INFORM",
+  from: "external",
+  to: "researcher",
+  content: "New data available",
+});
+```
+
+## Quick Reference
+
+| API | Purpose | Key Options |
+|---|---|---|
+| `createMessageBus()` | Agent-to-agent messaging | subscribe, publish, request |
+| `createAgentNetwork()` | Capability-based discovery | agents with capabilities |
+| `bus.publish()` | Fire-and-forget message | type, from, to, content |
+| `bus.request()` | Request-response with timeout | action, payload, timeout |
+| `bus.subscribe()` | Listen for messages | agentName, callback |
+| `network.findByCapability()` | Find agents by skill | capability string |
+| `network.route()` | Route work to capable agent | capability, payload |