@directive-run/knowledge 0.2.0

package/ai/ai-orchestrator.md

@@ -0,0 +1,227 @@
+# AI Orchestrator (Single-Agent)
+
+The `createAgentOrchestrator` configures a Directive-backed runtime for a single AI agent with constraints, resolvers, guardrails, memory, budgets, and hooks.
+
+## Decision Tree: "How do I set up an orchestrator?"
+
+```
+Need to run an AI agent?
+├── Single agent → createAgentOrchestrator (this file)
+├── Multiple agents → createMultiAgentOrchestrator (see ai-multi-agent.md)
+│
+Setting up createAgentOrchestrator...
+├── Need schema? → factsSchema with t.*() builders (NOT TS types)
+├── Need guardrails? → guardrails: { input: [...], output: [...] }
+├── Need memory? → memory: createAgentMemory({ strategy, summarizer })
+├── Need budget control? → maxTokenBudget + budgetWarningThreshold
+├── Need streaming? → orchestrator.runStream(agent, prompt)
+└── Need approval workflow? → hooks.onBeforeRun returns { approved: boolean }
+```
+
+## Basic Setup
+
+```typescript
+import { createAgentOrchestrator, t } from "@directive-run/ai";
+import { createAnthropicRunner } from "@directive-run/ai/anthropic";
+
+const runner = createAnthropicRunner({
+  apiKey: process.env.ANTHROPIC_API_KEY,
+});
+
+const orchestrator = createAgentOrchestrator({
+  runner,
+  factsSchema: {
+    confidence: t.number(),
+    analysis: t.string(),
+    cache: t.array<string>(),
+  },
+  init: (facts) => {
+    facts.confidence = 0;
+    facts.analysis = "";
+    facts.cache = [];
+  },
+  constraints: {
+    lowConfidence: {
+      when: (facts) => facts.confidence < 0.5,
+      require: { type: "RE_ANALYZE" },
+    },
+  },
+  resolvers: {
+    reAnalyze: {
+      requirement: "RE_ANALYZE",
+      resolve: async (req, context) => {
+        context.facts.confidence = 0;
+      },
+    },
+  },
+  guardrails: {
+    input: [createPIIGuardrail({ redact: true })],
+    output: [createLengthGuardrail({ maxChars: 5000 })],
+  },
+  maxTokenBudget: 100000,
+  budgetWarningThreshold: 0.8,
+  memory: createAgentMemory({
+    strategy: createSlidingWindowStrategy({ maxMessages: 50 }),
+    summarizer: createKeyPointsSummarizer(),
+  }),
+  debug: true,
+  hooks: {
+    onStart: () => console.log("Orchestrator started"),
+    onBeforeRun: (agent, prompt) => ({ approved: true }),
+    onAfterRun: (agent, result) => console.log("Done", result.totalTokens),
+    onError: (error) => console.error(error),
+    onBudgetWarning: (usage) => console.warn("Budget:", usage),
+  },
+});
+```
+
+## Running the Agent
+
+```typescript
+const agent = {
+  name: "analyst",
+  instructions: "You are a data analyst.",
+  model: "claude-sonnet-4-5",
+};
+
+// Standard run
+const result = await orchestrator.run(agent, "Analyze this dataset");
+console.log(result.output);
+
+// Streaming run
+const stream = orchestrator.runStream(agent, "Summarize findings");
+for await (const chunk of stream) {
+  if (chunk.type === "token") {
+    process.stdout.write(chunk.data);
+  }
+}
+
+// Wait for all constraints/resolvers to settle
+await orchestrator.system.settle();
+```
+
+## OrchestratorState Fields
+
+```typescript
+// Access via orchestrator.system.facts
+orchestrator.system.facts.status;     // "idle" | "running" | "paused" | "error"
+orchestrator.system.facts.tokenUsage; // { inputTokens, outputTokens, total }
+orchestrator.system.facts.runCount;   // number of completed runs
+orchestrator.system.facts.lastError;  // Error | null
+```
+
+## Approval Workflow
+
+```typescript
+const orchestrator = createAgentOrchestrator({
+  runner,
+  hooks: {
+    onBeforeRun: async (agent, prompt) => {
+      const decision = await reviewPrompt(prompt);
+
+      return { approved: decision.ok, reason: decision.reason };
+    },
+  },
+});
+
+// If not approved, run() throws ApprovalDeniedError
+```
+
+## Pause / Resume
+
+```typescript
+orchestrator.pause();
+// Agent work suspends; in-flight requests complete but new ones queue
+
+orchestrator.resume();
+// Queued work begins executing
+```
+
+## Checkpoints
+
+```typescript
+// Save state
+const checkpoint = orchestrator.checkpoint();
+const serialized = JSON.stringify(checkpoint);
+
+// Restore state
+const restored = createAgentOrchestrator({
+  runner,
+  checkpoint: JSON.parse(serialized),
+});
+```
+
+## Anti-Patterns
+
+### #21: TypeScript types instead of t.*() for factsSchema
+
+```typescript
+// WRONG — TS types are erased at runtime, no schema validation
+const orchestrator = createAgentOrchestrator({
+  runner,
+  factsSchema: {} as { confidence: number; analysis: string },
+});
+
+// CORRECT — use t.*() builders for runtime schema
+const orchestrator = createAgentOrchestrator({
+  runner,
+  factsSchema: {
+    confidence: t.number(),
+    analysis: t.string(),
+  },
+});
+```
+
+### #22: Mutating arrays/objects in place
+
+```typescript
+// WRONG — proxy cannot detect in-place mutations
+context.facts.cache.push("new-item");
+
+// CORRECT — replace the entire value
+context.facts.cache = [...context.facts.cache, "new-item"];
+```
+
+### #23: Returning data from resolve
+
+```typescript
+// WRONG — resolvers return void, not data
+resolve: async (req, context) => {
+  const result = await analyzeData(req.input);
+
+  return result; // Return value is ignored
+},
+
+// CORRECT — mutate context.facts to store results
+resolve: async (req, context) => {
+  const result = await analyzeData(req.input);
+  context.facts.analysis = result;
+},
+```
+
+### #24: Forgetting start() for multi-agent
+
+```typescript
+// WRONG — multi-agent orchestrators require explicit start()
+const orchestrator = createMultiAgentOrchestrator({ agents, runner });
+const result = await orchestrator.runPattern("pipeline", "prompt");
+
+// CORRECT — call start() before running patterns
+const orchestrator = createMultiAgentOrchestrator({ agents, runner });
+orchestrator.start();
+const result = await orchestrator.runPattern("pipeline", "prompt");
+```
+
+Note: Single-agent `createAgentOrchestrator` does NOT require `start()`. Only `createMultiAgentOrchestrator` does.
+
+## Quick Reference
+
+| Method | Purpose |
+|---|---|
+| `orchestrator.run(agent, prompt)` | Run agent, return RunResult |
+| `orchestrator.runStream(agent, prompt)` | Run agent, return AsyncIterable<StreamChunk> |
+| `orchestrator.pause()` | Suspend new work |
+| `orchestrator.resume()` | Resume suspended work |
+| `orchestrator.checkpoint()` | Serialize current state |
+| `orchestrator.system.settle()` | Wait for all resolvers |
+| `orchestrator.system.facts` | Read orchestrator state |

package/ai/ai-security.md

@@ -0,0 +1,293 @@
+# AI Security
+
+PII detection/redaction, prompt injection defense, audit trails, GDPR/CCPA compliance, and security best practices for Directive AI applications.
+
+## Decision Tree: "What security do I need?"
+
+```
+What are you protecting against?
+├── PII leakage in prompts/outputs → createPIIGuardrail()
+├── Prompt injection attacks → createPromptInjectionGuardrail()
+├── Audit/compliance requirements → createAuditTrailPlugin()
+├── GDPR/CCPA data handling → createCompliancePlugin()
+│
+Where do guardrails go?
+├── Before agent receives prompt → guardrails.input
+├── After agent produces output → guardrails.output
+└── Both directions → guardrails.input + guardrails.output
+│
+Where do plugins go?
+└── Always → plugins: [createAuditTrailPlugin(), ...]
+    (Plugins are Directive core plugins, not AI-specific)
+```
+
+## PII Detection and Redaction
+
+Enhanced PII guardrail with built-in patterns and custom regex support:
+
+```typescript
+import { createPIIGuardrail } from "@directive-run/ai";
+
+const piiGuardrail = createPIIGuardrail({
+  // Redact PII instead of blocking (default: false = block)
+  redact: true,
+
+  // Replacement string (default: "[REDACTED]")
+  redactReplacement: "[REDACTED]",
+
+  // Additional custom patterns beyond built-ins
+  patterns: [
+    /\b\d{3}-\d{2}-\d{4}\b/,         // SSN
+    /\b[A-Z]{2}\d{6,8}\b/,           // Passport
+    /ACCT-\d{10}/,                     // Internal account IDs
+  ],
+});
+```
+
+Built-in patterns detect:
+- Email addresses
+- Phone numbers (US, international)
+- Credit card numbers (Visa, MC, Amex, Discover)
+- IP addresses (v4, v6)
+- Dates of birth (common formats)
+
+### Using PII Guardrail
+
+```typescript
+const orchestrator = createAgentOrchestrator({
+  runner,
+  guardrails: {
+    // Redact PII before the agent sees it
+    input: [piiGuardrail],
+
+    // Catch any PII the agent generates
+    output: [piiGuardrail],
+  },
+});
+```
+
+## Prompt Injection Detection
+
+Detect and block common prompt injection patterns:
+
+```typescript
+import { createPromptInjectionGuardrail } from "@directive-run/ai";
+
+const injectionGuardrail = createPromptInjectionGuardrail({
+  // Sensitivity: "low" | "medium" | "high" (default: "medium")
+  sensitivity: "high",
+
+  // Custom patterns to detect
+  additionalPatterns: [
+    /ignore previous instructions/i,
+    /you are now/i,
+    /system prompt/i,
+  ],
+
+  // Allow-list specific phrases that look like injections but are safe
+  allowlist: [
+    "you are now ready to proceed",
+  ],
+});
+```
+
+### Sensitivity Levels
+
+| Level | Detects | False Positives |
+|---|---|---|
+| `"low"` | Obvious injections (role overrides, ignore instructions) | Rare |
+| `"medium"` | Common patterns + encoded attacks | Occasional |
+| `"high"` | Aggressive detection + heuristic analysis | More frequent |
+
+### Applying Injection Defense
+
+```typescript
+const orchestrator = createAgentOrchestrator({
+  runner,
+  guardrails: {
+    // Check user input for injection attempts
+    input: [injectionGuardrail],
+  },
+});
+
+// Handle blocked input
+import { GuardrailError } from "@directive-run/ai";
+
+try {
+  const result = await orchestrator.run(agent, userInput);
+} catch (error) {
+  if (error instanceof GuardrailError) {
+    console.log(error.guardrailName);  // "prompt-injection"
+    console.log(error.errorCode);      // "GUARDRAIL_INPUT_BLOCKED"
+    console.log(error.reason);         // "Prompt injection detected: role override"
+  }
+}
+```
+
+## Audit Trail Plugin
+
+Log all AI interactions for compliance and forensics:
+
+```typescript
+import { createAuditTrailPlugin } from "@directive-run/core/plugins";
+
+const auditPlugin = createAuditTrailPlugin({
+  // Where to store audit logs
+  storage: "file",           // "file" | "console" | custom handler
+  filePath: "./audit.jsonl", // For file storage
+
+  // What to log
+  logInputs: true,
+  logOutputs: true,
+  logToolCalls: true,
+  logTokenUsage: true,
+
+  // Redact sensitive data in logs (recommended)
+  redactPII: true,
+
+  // Custom log handler (alternative to file/console)
+  onLog: async (entry) => {
+    await sendToSIEM(entry);
+  },
+});
+```
+
+### Audit Log Entry Shape
+
+```typescript
+interface AuditLogEntry {
+  timestamp: string;
+  eventType: "agent_run" | "tool_call" | "guardrail_check" | "error";
+  agentName: string;
+  input?: string;         // Redacted if redactPII: true
+  output?: string;        // Redacted if redactPII: true
+  toolCalls?: ToolCall[];
+  tokenUsage?: { inputTokens: number; outputTokens: number };
+  duration: number;
+  guardrails?: { name: string; passed: boolean; reason?: string }[];
+  error?: { message: string; code: string };
+}
+```
+
+## GDPR/CCPA Compliance Plugin
+
+Enforce data handling policies at the system level:
+
+```typescript
+import { createCompliancePlugin } from "@directive-run/core/plugins";
+
+const compliancePlugin = createCompliancePlugin({
+  // Data retention policy
+  retention: {
+    maxAge: 30 * 24 * 60 * 60 * 1000, // 30 days in ms
+    autoDelete: true,
+  },
+
+  // Right to deletion
+  onDeletionRequest: async (userId) => {
+    await deleteUserData(userId);
+    await deleteConversationHistory(userId);
+  },
+
+  // Data export (right to portability)
+  onExportRequest: async (userId) => {
+    const data = await getUserData(userId);
+
+    return JSON.stringify(data);
+  },
+
+  // Consent tracking
+  requireConsent: true,
+  consentCategories: ["analytics", "personalization", "training"],
+});
+```
+
+## Applying Security Plugins
+
+Plugins go on the orchestrator (they are Directive core plugins):
+
+```typescript
+import { createAgentOrchestrator } from "@directive-run/ai";
+
+const orchestrator = createAgentOrchestrator({
+  runner,
+  guardrails: {
+    input: [piiGuardrail, injectionGuardrail],
+    output: [piiGuardrail],
+  },
+  plugins: [auditPlugin, compliancePlugin],
+});
+```
+
+## Security Best Practices
+
+### Input Validation
+
+```typescript
+// WRONG — passing raw user input to the agent
+const result = await orchestrator.run(agent, userInput);
+
+// CORRECT — validate and sanitize input first
+const sanitized = sanitizeInput(userInput);
+const result = await orchestrator.run(agent, sanitized);
+```
+
+### Token Budget Limits
+
+```typescript
+// Always set a token budget to prevent runaway costs
+const orchestrator = createAgentOrchestrator({
+  runner,
+  maxTokenBudget: 100000,
+  budgetWarningThreshold: 0.8,
+});
+```
+
+### Tool Approval Workflows
+
+```typescript
+import { createToolGuardrail } from "@directive-run/ai";
+
+// Restrict which tools the agent can call
+const toolGuardrail = createToolGuardrail({
+  allowedTools: ["search", "calculator", "readFile"],
+  // Tools not in this list are blocked
+});
+
+// For MCP tools, use toolConstraints
+const mcp = createMCPAdapter({
+  servers: [...],
+  toolConstraints: {
+    "tools/write-file": { requireApproval: true },
+    "tools/delete": { requireApproval: true, maxAttempts: 1 },
+  },
+});
+```
+
+### Output Sanitization
+
+```typescript
+// Always validate agent output before using it
+const orchestrator = createAgentOrchestrator({
+  runner,
+  guardrails: {
+    output: [
+      createOutputSchemaGuardrail({ schema: expectedSchema, retries: 2 }),
+      createContentFilterGuardrail({ patterns: [/eval\(/, /<script/i], action: "block" }),
+      createPIIGuardrail({ redact: true }),
+    ],
+  },
+});
+```
+
+## Quick Reference
+
+| API | Import Path | Purpose |
+|---|---|---|
+| `createPIIGuardrail` | `@directive-run/ai` | Detect/redact PII |
+| `createPromptInjectionGuardrail` | `@directive-run/ai` | Block injection attacks |
+| `createAuditTrailPlugin` | `@directive-run/core/plugins` | Log all AI interactions |
+| `createCompliancePlugin` | `@directive-run/core/plugins` | GDPR/CCPA data policies |
+| `createToolGuardrail` | `@directive-run/ai` | Restrict tool access |
+| `createContentFilterGuardrail` | `@directive-run/ai` | Block unsafe content patterns |
+| `GuardrailError` | `@directive-run/ai` | Catch guardrail failures |