@directive-run/knowledge 1.23.0 → 1.24.0

package/ai/ai-adapters.md

@@ -74,6 +74,27 @@ const proxiedRunner = createAnthropicRunner({
 });
 ```
 
+### Prompt Caching (Anthropic)
+
+Opt in with `promptCaching: "automatic"` to add a `cache_control` breakpoint on the agent's instructions. Anthropic caches that stable system prefix so repeat calls that share it read from cache (~0.1x input cost) instead of reprocessing it; the variable message suffix stays uncached. Off by default (bare-string system, unchanged prior behavior), non-breaking, and no beta header is required on `anthropic-version: 2023-06-01`. Supported on the non-streaming `createAnthropicRunner` (streaming is a follow-up).
+
+```typescript
+const runner = createAnthropicRunner({
+  apiKey: process.env.ANTHROPIC_API_KEY,
+  promptCaching: "automatic",
+});
+const result = await runner(agent, prompt);
+
+// Cache usage is surfaced on tokenUsage – present only when caching is active:
+const { cacheReadTokens = 0, cacheCreationTokens = 0 } = result.tokenUsage;
+// cacheCreationTokens – tokens written to cache on the first call (~1.25x cost)
+// cacheReadTokens     – tokens served from cache on repeat calls (~0.1x cost)
+```
+
+`inputTokens` remains the uncached remainder; the cache fields are separate and additive, and `totalTokens` includes all four (input + output + cache-read + cache-creation).
+
+**Minimum cacheable prefix (the #1 support gotcha).** Anthropic silently ignores `cache_control` when the cached prefix is below a per-model minimum – ~1024 tokens on Sonnet-tier models, 2048 on Sonnet-4.6 & Haiku-3.5, 4096 on Opus & Haiku-4.5. No error is raised: caching simply doesn't happen and `cacheReadTokens` stays `0` on repeat calls (that `0` is the diagnostic). Since Directive caches `agent.instructions`, short instructions commonly fall below the threshold. The `ephemeral` breakpoint also carries a 5-minute default TTL – a prefix not re-read within that window is evicted. (Cost note: `withBudget`/`estimateCost` weight all tokens equally today, so cached runs are not yet repriced for the ~0.1x read / ~1.25x write rates – cache-aware pricing is a planned follow-up.)
+
 ## OpenAI Adapter
 
 ```typescript
@@ -147,7 +168,7 @@ console.log(result.tokenUsage.input_tokens); // undefined!
 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
+console.log(result.totalTokens);               // inputTokens + outputTokens (+ cache tokens when caching is active)
 ```
 
 All adapters normalize token usage to the same shape regardless of provider:
@@ -156,9 +177,14 @@ All adapters normalize token usage to the same shape regardless of provider:
 interface NormalizedTokenUsage {
   inputTokens: number;
   outputTokens: number;
+  // Populated by adapters with prompt caching active (e.g. Anthropic
+  // `promptCaching: "automatic"`); omitted otherwise.
+  cacheReadTokens?: number;
+  cacheCreationTokens?: number;
 }
 
 // result.totalTokens = inputTokens + outputTokens
+//   + cacheReadTokens + cacheCreationTokens (cache fields are 0 when absent)
 ```
 
 ## Adapter Hooks
@@ -244,7 +270,7 @@ const orchestrator = createAgentOrchestrator({ runner });
 
 | Adapter | Import Path | Key Options |
 |---|---|---|
-| Anthropic | `@directive-run/ai/anthropic` | `apiKey`, `defaultModel`, `maxTokens` |
+| Anthropic | `@directive-run/ai/anthropic` | `apiKey`, `defaultModel`, `maxTokens`, `promptCaching` |
 | OpenAI | `@directive-run/ai/openai` | `apiKey`, `defaultModel`, `organization` |
 | Ollama | `@directive-run/ai/ollama` | `baseURL`, `defaultModel` |
 | Gemini | `@directive-run/ai/gemini` | `apiKey`, `defaultModel` |

package/ai/ai-agents-streaming.md

@@ -55,7 +55,11 @@ interface RunResult<T = unknown> {
 interface TokenUsage {
   inputTokens: number;
   outputTokens: number;
-  // Note: NO `total` field — sum `inputTokens + outputTokens` when needed, or use `result.totalTokens`.
+  // Populated by adapters with prompt caching active (e.g. Anthropic
+  // `promptCaching: "automatic"`); omitted otherwise.
+  cacheReadTokens?: number;
+  cacheCreationTokens?: number;
+  // Note: NO `total` field — sum `inputTokens + outputTokens` (+ cache tokens when present) when needed, or use `result.totalTokens`.
 }
 ```
 

package/ai/ai-security.md

@@ -388,8 +388,8 @@ source publishes PII into a fact and the agent's prompt template embeds
 that fact (`"Hello ${facts.email}..."`), the PII reaches the LLM call
 without hitting the input guardrail chain.
 
-This is the documented R5 audit finding (red team, privacy, AI-integration
-reviewers independently flagged it). The Tier 0 fix:
+This is a documented gap in the input-only guardrail chain — the fix
+is a fact-store-boundary guardrail that runs on every fact write:
 
 ```ts
 import { createSystem, createModule, t } from "@directive-run/core";

package/examples/cloudflare-directive-ai.ts

@@ -0,0 +1,178 @@
+// Example: cloudflare-directive-ai
+// Source: examples/cloudflare-directive-ai/src/module.ts
+// Pure module file — no DOM wiring
+
+import { createModule, createSystem } from "@directive-run/core";
+import { sourceFromDOAlarm } from "@directive-run/sources/cloudflare";
+import { schema, type PublishingStatus } from "./schema.js";
+import type { AuditLog, Broadcaster } from "./deps.js";
+import { createPublishingChain, type PublishingChain } from "./agents.js";
+
+export interface PublishingDeps {
+  auditLog: AuditLog;
+  broadcaster: Broadcaster;
+  anthropicApiKey: string;
+  storage: DurableObjectStorage;
+  intervalMs?: number;
+}
+
+export interface PublishingModuleHandle {
+  alarmTick: () => void;
+}
+
+export function createPublishingSystem(deps: PublishingDeps) {
+  const chain = createPublishingChain(deps.anthropicApiKey);
+  const handle: PublishingModuleHandle = {
+    alarmTick: () => {},
+  };
+
+  const alarmSource = sourceFromDOAlarm({
+    storage: deps.storage,
+    intervalMs: deps.intervalMs ?? 5 * 60 * 1000,
+    eventName: "tick",
+    payload: () => ({}),
+    onTickRegistered: (tick) => {
+      handle.alarmTick = tick;
+    },
+  });
+
+  const publishingModule = createModule("publishing", {
+    schema,
+
+    init: (facts) => {
+      facts.status = "idle" satisfies PublishingStatus;
+      facts.currentArticle = {};
+      facts.ingestQueue = [];
+      facts.reviewQueue = [];
+      facts.errorLog = [];
+    },
+
+    derive: {
+      queueDepth: (facts) => facts.ingestQueue.length,
+      reviewDepth: (facts) => facts.reviewQueue.length,
+      isReadyToAggregate: (facts) =>
+        facts.ingestQueue.length >= 3 && facts.status === "idle",
+    },
+
+    events: {
+      ingest: (facts, payload) => {
+        facts.ingestQueue = [
+          ...facts.ingestQueue,
+          { url: payload.url, capturedAt: new Date().toISOString() },
+        ];
+      },
+      tick: (facts) => {
+        if (facts.status === "failed" || facts.status === "published") {
+          facts.status = "idle";
+        }
+      },
+    },
+
+    sources: {
+      alarm: alarmSource,
+    },
+
+    constraints: {
+      startAggregation: {
+        priority: 100,
+        when: (facts) =>
+          facts.ingestQueue.length >= 3 && facts.status === "idle",
+        require: (facts) => ({
+          type: "RUN_PUBLISHING_CHAIN",
+          sources: facts.ingestQueue.slice(0, 8),
+        }),
+      },
+
+      routeArticle: {
+        priority: 90,
+        when: (facts) => facts.status === "reviewing",
+        require: (facts) => ({
+          type: "ROUTE_ARTICLE",
+          article: facts.currentArticle,
+        }),
+      },
+    },
+
+    resolvers: {
+      runChain: {
+        requirement: "RUN_PUBLISHING_CHAIN",
+        key: (req) => `chain-${req.sources.map((s) => s.url).join("|")}`,
+        resolve: async (req, context) => {
+          context.facts.status = "aggregating";
+          context.facts.ingestQueue = context.facts.ingestQueue.slice(
+            req.sources.length,
+          );
+
+          try {
+            const result = await chain.run(req.sources, "demo");
+
+            context.facts.currentArticle = result;
+            context.facts.status = "reviewing";
+            await deps.auditLog.append({
+              event: "chain-completed",
+              at: new Date().toISOString(),
+              sources: req.sources.length,
+              confidence: result.confidence,
+              slug: result.slug,
+            });
+          } catch (err) {
+            const message = err instanceof Error ? err.message : String(err);
+            context.facts.errorLog = [
+              ...context.facts.errorLog,
+              {
+                at: new Date().toISOString(),
+                source: "publishing-chain",
+                message,
+              },
+            ];
+            context.facts.status = "failed";
+            await deps.auditLog.append({
+              event: "chain-failed",
+              at: new Date().toISOString(),
+              error: message,
+            });
+          }
+        },
+      },
+
+      routeArticle: {
+        requirement: "ROUTE_ARTICLE",
+        key: (req) => `route-${req.article.slug ?? "unknown"}`,
+        resolve: async (req, context) => {
+          const confidence = req.article.confidence ?? 0;
+          const slug = req.article.slug ?? "unknown";
+
+          if (confidence >= 0.85) {
+            await deps.broadcaster.send(req.article);
+            context.facts.status = "published";
+            await deps.auditLog.append({
+              event: "auto-published",
+              at: new Date().toISOString(),
+              slug,
+              confidence,
+            });
+          } else {
+            context.facts.reviewQueue = [
+              ...context.facts.reviewQueue,
+              { articleId: slug, confidence },
+            ];
+            context.facts.status = "idle";
+            await deps.auditLog.append({
+              event: "routed-to-review",
+              at: new Date().toISOString(),
+              slug,
+              confidence,
+            });
+          }
+        },
+      },
+    },
+  });
+
+  const system = createSystem({ module: publishingModule });
+
+  return { system, handle };
+}
+
+export type PublishingSystem = ReturnType<typeof createPublishingSystem>;
+export type { PublishingChain };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@directive-run/knowledge",
-  "version": "1.23.0",
+  "version": "1.24.0",
   "description": "Knowledge files, examples, and validation for Directive — the constraint-driven TypeScript runtime.",
   "license": "(MIT OR Apache-2.0)",
   "author": "Jason Comes",
@@ -52,9 +52,9 @@
     "tsup": "^8.3.5",
     "tsx": "^4.19.2",
     "typescript": "^5.7.2",
-    "vitest": "^3.0.0",
-    "@directive-run/core": "1.23.0",
-    "@directive-run/ai": "1.23.0"
+    "vitest": "^3.2.6",
+    "@directive-run/core": "1.24.0",
+    "@directive-run/ai": "1.24.0"
   },
   "scripts": {
     "build": "tsx scripts/generate-api-skeleton.ts && tsx scripts/generate-sitemap.ts && tsx scripts/extract-examples.ts && tsup",

package/sitemap.md

@@ -86,6 +86,7 @@ Website: https://directive.run
 - [Persistence](https://directive.run/docs/plugins/persistence)
 - [Performance](https://directive.run/docs/plugins/performance)
 - [Circuit Breaker](https://directive.run/docs/plugins/circuit-breaker)
+- [Clobber Loop Detector](https://directive.run/docs/plugins/clobber-loop)
 - [Observability](https://directive.run/docs/plugins/observability)
 - [Custom Plugins](https://directive.run/docs/plugins/custom)
 
@@ -108,6 +109,14 @@ Website: https://directive.run
 - [Resolver Binding](https://directive.run/docs/resolver-binding)
 - [Audit Ledger](https://directive.run/docs/audit-ledger)
 
+### Broadcast
+- [Overview](https://directive.run/docs/broadcast)
+- [GitHub Action](https://directive.run/docs/broadcast/action)
+- [CLI](https://directive.run/docs/broadcast/cli)
+- [Cloudflare Worker](https://directive.run/docs/broadcast/worker)
+- [MCP server](https://directive.run/docs/broadcast/mcp)
+- [README badge](https://directive.run/docs/broadcast/badge)
+
 ### Examples
 - [Number Match](https://directive.run/docs/examples/counter)
 - [Auth Flow](https://directive.run/docs/examples/auth-flow)