@stackbilt/aegis-core 0.6.2 → 0.6.3

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@stackbilt/aegis-core",
-  "version": "0.6.2",
+  "version": "0.6.3",
   "description": "Persistent AI agent framework for Cloudflare Workers. Multi-tier memory, autonomous goals, dreaming cycles, MCP native.",
   "license": "Apache-2.0",
   "publishConfig": {
@@ -33,6 +33,8 @@
     "./kernel/argus-correlation": "./src/kernel/argus-correlation.ts",
     "./kernel/port": "./src/kernel/port.ts",
     "./kernel/executor-port": "./src/kernel/executor-port.ts",
+    "./kernel/executor-router": "./src/kernel/executor-router.ts",
+    "./kernel/provider-factory": "./src/kernel/provider-factory.ts",
     "./kernel/executors": "./src/kernel/executors/index.ts",
     "./kernel/scheduled": "./src/kernel/scheduled/index.ts",
     "./kernel/scheduled/dreaming": "./src/kernel/scheduled/dreaming.ts",
@@ -84,7 +86,7 @@
     "@cloudflare/voice": "^0.1.3",
     "@cloudflare/workers-oauth-provider": "^0.2.4",
     "@stackbilt/contracts": "^0.2.1",
-    "@stackbilt/llm-providers": "^1.6.0",
+    "@stackbilt/llm-providers": "^1.6.4",
     "agents": "^0.12.3",
     "hono": "^4.12.12",
     "zod": "^4.4.3"

package/src/kernel/dispatch.ts

@@ -8,17 +8,14 @@ import { executeComposite } from '../composite.js';
 import { buildGroqSystemPrompt } from '../operator/prompt-builder.js';
 import type { KernelIntent, DispatchResult, Executor } from './types.js';
 import {
-  executeClaude,
-  executeClaudeOpus,
-  executeClaudeStream,
-  executeGroq,
-  executeWorkersAi,
   executeGptOss,
+  executeClaudeStream,
   executeDirect,
   executeCodeTask,
   executeWithAnthropicFailover,
   executeTarotScript,
   buildMcpRegistry,
+  EXECUTOR_FNS,
 } from './executors/index.js';
 // ─── Edge Environment ────────────────────────────────────────
 
@@ -366,15 +363,6 @@ async function probeAndExecute(
         case 'composite':
           result = await executeComposite(intent, env, buildMcpRegistry(env));
           break;
-        case 'gpt_oss':
-          result = await executeGptOss(intent, env);
-          break;
-        case 'workers_ai':
-          result = await executeWorkersAi(intent, env);
-          break;
-        case 'groq':
-          result = await executeGroq(intent, env);
-          break;
         case 'direct':
           result = await executeDirect(intent, env);
           break;
@@ -384,8 +372,11 @@ async function probeAndExecute(
         case 'tarotscript':
           result = await executeTarotScript(intent, env);
           break;
-        default:
-          throw new Error(`Unknown executor: ${plan.executor}`);
+        default: {
+          const fn = EXECUTOR_FNS[plan.executor as Executor];
+          if (!fn) throw new Error(`Unknown executor: ${plan.executor}`);
+          result = await fn(intent, env);
+        }
       }
 
       // For streaming non-Claude executors, emit full text as single delta
@@ -464,21 +455,10 @@ async function tryShadowExploration(
   try {
     // Clone intent to avoid mutation
     const shadowIntent: KernelIntent = { ...intent, classified: shadowExecutor };
-    let result: { text: string; cost: number };
-
-    switch (shadowExecutor) {
-      case 'gpt_oss':
-        result = await executeGptOss(shadowIntent, env);
-        break;
-      case 'workers_ai':
-        result = await executeWorkersAi(shadowIntent, env);
-        break;
-      case 'claude':
-        result = await executeClaude(shadowIntent, env);
-        break;
-      default:
-        return;
-    }
+
+    const fn = EXECUTOR_FNS[shadowExecutor];
+    if (!fn) return;
+    const result = await fn(shadowIntent, env);
 
     const passed = shadowQualityPass(primaryText, result.text);
     const outcome = passed ? 'success' : 'failure';

package/src/kernel/executor-router.ts

@@ -0,0 +1,95 @@
+import type { EdgeEnv } from './dispatch.js';
+import type { Executor } from './types.js';
+
+// ─── Provider Names ──────────────────────────────────────────
+// 'anthropic' and 'cloudflare' are wired in @stackbilt/llm-providers v1.6.0.
+// 'groq' and 'cerebras' are forward-declared — no LLMProviderFactory entry yet.
+// A future session can wire them when provider support lands.
+export type LLMProviderName = 'anthropic' | 'cloudflare' | 'groq' | 'cerebras';
+
+// ─── LLM Executor Subset ─────────────────────────────────────
+// These are the executors that call an external LLM provider.
+// Excluded from EXECUTOR_ROUTES (dispatch keeps its own branches):
+//   'direct'      — returns a rule-based response without an LLM call
+//   'claude_code' — spins a Claude Code CLI session, not a provider call
+//   'tarotscript' — service-binding fetcher, not an LLM call
+//   'composite'   — orchestrates multiple executors; no single provider entry
+export type LLMExecutor = Extract<
+  Executor,
+  'claude' | 'claude_opus' | 'gpt_oss' | 'workers_ai' | 'groq' | 'cerebras_mid' | 'cerebras_reasoning'
+>;
+
+// ─── Route Shape ─────────────────────────────────────────────
+
+export interface ExecutorRoute {
+  provider: LLMProviderName;
+  // Resolves the concrete model string at dispatch time — called with the live
+  // EdgeEnv so per-deployment env-var overrides and AI Gateway config are respected.
+  model: (env: EdgeEnv) => string;
+  // Semantic fallback executor to try when this provider errors (credit, rate-limit, auth).
+  // CONSUMER CONTRACT: when a fallback fires, the consumer must propagate actualExecutor
+  // back to the telemetry layer. executeWithAnthropicFailover (executors/index.ts:67)
+  // returns { actualExecutor } which dispatch.ts:363 uses to mutate plan.executor before
+  // the procedure store records the outcome. A routing-layer consumer must preserve this.
+  fallback?: LLMExecutor;
+}
+
+// ─── Route Table ─────────────────────────────────────────────
+// Covers every LLMExecutor. Non-LLM executors (see above) are intentionally absent.
+//
+// Future consumer sketch (D.2 wiring session):
+//   const route = EXECUTOR_ROUTES[plan.executor as LLMExecutor];
+//   const provider = factory.get(route.provider);   // only 'anthropic'|'cloudflare' today
+//   const model    = route.model(env);
+//   try { result = await provider.generateResponse({ model, messages }); }
+//   catch { if (route.fallback) { /* re-dispatch, record actualExecutor */ } }
+
+export const EXECUTOR_ROUTES: Record<LLMExecutor, ExecutorRoute> = {
+  claude: {
+    provider: 'anthropic',
+    model: (env) => env.claudeModel,
+    fallback: 'gpt_oss',
+  },
+  claude_opus: {
+    provider: 'anthropic',
+    model: (env) => env.opusModel,
+    // Falls back directly to gpt_oss — mirrors executeWithAnthropicFailover behavior.
+    // A two-hop chain (opus → claude → gpt_oss) is a possible future refinement.
+    fallback: 'gpt_oss',
+  },
+  gpt_oss: {
+    provider: 'cloudflare',
+    model: (env) => env.gptOssModel,
+    // Terminal fallback — no further fallback defined.
+  },
+  workers_ai: {
+    provider: 'cloudflare',
+    // Hardcoded in executeWorkersAi today; no env override.
+    model: () => '@cf/meta/llama-3.3-70b-instruct-fp8-fast',
+  },
+  groq: {
+    provider: 'groq',
+    // groqResponseModel = 8B (llama-3.1-8b-instant) — fast/cheap for greetings.
+    // Intentionally NOT groqModel (70B). See executors/groq.ts:12.
+    model: (env) => env.groqResponseModel,
+  },
+  cerebras_mid: {
+    // TODO: EdgeEnv has no cerebras fields yet. Add cerebrasApiKey + cerebrasModel
+    // when executors/cerebras.ts lands. Model name below is a placeholder.
+    provider: 'cerebras',
+    model: () => 'llama3.1-8b',
+  },
+  cerebras_reasoning: {
+    // TODO: EdgeEnv has no cerebras fields yet. Add cerebrasApiKey + cerebrasReasoningModel
+    // when executors/cerebras.ts lands. Model name below is a placeholder.
+    provider: 'cerebras',
+    model: () => 'qwen-3-32b',
+  },
+};
+
+// ─── Lookup Helper ────────────────────────────────────────────
+// Returns null for non-LLM executors (direct, claude_code, tarotscript, composite).
+// Dispatch uses the null path to keep its own branches for those cases.
+export function getExecutorRoute(executor: Executor): ExecutorRoute | null {
+  return (EXECUTOR_ROUTES as Record<string, ExecutorRoute>)[executor] ?? null;
+}

package/src/kernel/executors/groq.ts

@@ -1,4 +1,4 @@
-import { askGroq } from '../../groq.js';
+import { buildLLMProviderFactory } from '../provider-factory.js';
 import { buildGroqSystemPrompt } from '../../operator/prompt-builder.js';
 import type { KernelIntent } from '../types.js';
 import type { EdgeEnv } from '../dispatch.js';
@@ -7,12 +7,13 @@ export async function executeGroq(
   intent: KernelIntent,
   env: EdgeEnv,
 ): Promise<{ text: string; cost: number }> {
-  const text = await askGroq(
-    env.groqApiKey,
-    env.groqResponseModel, // 8B model for greetings — fast + cheap
-    buildGroqSystemPrompt(),
-    intent.raw,
-    env.groqBaseUrl,
-  );
-  return { text, cost: 0.0001 };
+  const factory = buildLLMProviderFactory(env);
+  const result = await factory.generateResponse({
+    messages: [{ role: 'user', content: intent.raw }],
+    model: env.groqResponseModel, // 8B — fast/cheap for greetings
+    systemPrompt: buildGroqSystemPrompt(),
+    temperature: 0.3,
+    maxTokens: 500,
+  });
+  return { text: result.message || '(no response)', cost: result.usage.cost };
 }

package/src/kernel/executors/index.ts

@@ -2,14 +2,31 @@ import { McpClient, McpRegistry } from '../../mcp-client.js';
 import { operatorConfig } from '../../operator/index.js';
 import type { Executor } from '../types.js';
 import type { EdgeEnv } from '../dispatch.js';
-import { executeGptOss } from './workers-ai.js';
+import type { KernelIntent } from '../types.js';
 
-// Re-export all executors
-export { executeClaude, executeClaudeOpus, executeClaudeStream } from './claude.js';
-export { executeGroq } from './groq.js';
-export { executeWorkersAi, executeGptOss } from './workers-ai.js';
-export { executeDirect, executeCodeTask } from './direct.js';
-export { executeTarotScript } from './tarotscript.js';
+// Import then re-export so EXECUTOR_FNS can hold live references
+import { executeClaude, executeClaudeOpus, executeClaudeStream } from './claude.js';
+import { executeGroq } from './groq.js';
+import { executeWorkersAi, executeGptOss } from './workers-ai.js';
+import { executeDirect, executeCodeTask } from './direct.js';
+import { executeTarotScript } from './tarotscript.js';
+export { executeClaude, executeClaudeOpus, executeClaudeStream };
+export { executeGroq };
+export { executeWorkersAi, executeGptOss };
+export { executeDirect, executeCodeTask };
+export { executeTarotScript };
+
+// ─── Uniform Executor Dispatch Map ──────────────────────────
+// Executors that share the (intent, env) → {text, cost} signature.
+// Used by dispatch to drive simple cases from the route table,
+// eliminating per-executor switch branches for groq/workers_ai/gpt_oss.
+// claude is included for the shadow exploration path (no failover there).
+export const EXECUTOR_FNS: Partial<Record<Executor, (intent: KernelIntent, env: EdgeEnv) => Promise<{ text: string; cost: number }>>> = {
+  groq: executeGroq,
+  workers_ai: executeWorkersAi,
+  gpt_oss: executeGptOss,
+  claude: executeClaude,
+};
 
 // ─── MCP Registry ────────────────────────────────────────────
 

package/src/kernel/executors/workers-ai.ts

@@ -1,54 +1,197 @@
-import { executeWorkersAiChat } from '../../workers-ai-chat.js';
-import { McpClient } from '../../mcp-client.js';
-import { operatorConfig } from '../../operator/index.js';
-import { buildGroqSystemPrompt } from '../../operator/prompt-builder.js';
-import type { KernelIntent } from '../types.js';
-import type { EdgeEnv } from '../dispatch.js';
-import { buildMcpRegistry } from './index.js';
-
-export async function executeWorkersAi(
-  intent: KernelIntent,
-  env: EdgeEnv,
-): Promise<{ text: string; cost: number }> {
-  if (!env.ai) throw new Error('Workers AI binding not available');
-  const result = await env.ai.run('@cf/meta/llama-3.3-70b-instruct-fp8-fast', {
-    messages: [
-      { role: 'system', content: buildGroqSystemPrompt() },
-      { role: 'user', content: intent.raw },
-    ],
-  }) as { response?: string };
-  return { text: result.response ?? '(no response)', cost: 0.005 };
-}
-
-export async function executeGptOss(
-  intent: KernelIntent,
-  env: EdgeEnv,
-): Promise<{ text: string; cost: number }> {
-  if (!env.ai) throw new Error('Workers AI binding not available');
-  const registry = buildMcpRegistry(env);
-  const mcpClient = new McpClient({
-    url: operatorConfig.integrations.bizops.fallbackUrl,
-    token: env.bizopsToken,
-    prefix: 'bizops',
-    fetcher: env.bizopsFetcher,
-    rpcPath: '/rpc',
-  });
-
-  return executeWorkersAiChat(
-    {
-      ai: env.ai,
-      model: env.gptOssModel,
-      mcpClient,
-      mcpRegistry: registry,
-      db: env.db,
-      channel: 'web',
-      conversationId: intent.source.threadId,
-      githubToken: env.githubToken,
-      githubRepo: env.githubRepo,
-      braveApiKey: env.braveApiKey,
-      memoryBinding: env.memoryBinding,
-      resendApiKeys: { resendApiKey: env.resendApiKey, resendApiKeyPersonal: env.resendApiKeyPersonal },
-    },
-    intent.raw,
-  );
-}
+import type { LLMMessage, ToolResult as LLMToolResult } from '@stackbilt/llm-providers';
+import { McpClient } from '../../mcp-client.js';
+import { operatorConfig } from '../../operator/index.js';
+import { buildGroqSystemPrompt } from '../../operator/prompt-builder.js';
+import { buildContext, handleInProcessTool, callMcpWithRetry, resolveMcpTool } from '../../claude.js';
+import { toOpenAiTools } from '../../workers-ai-chat.js';
+import { getConversationHistory, budgetConversationHistory } from '../memory/index.js';
+import { buildLLMProviderFactory } from '../provider-factory.js';
+import type { KernelIntent } from '../types.js';
+import type { EdgeEnv } from '../dispatch.js';
+import { buildMcpRegistry } from './index.js';
+
+export async function executeWorkersAi(
+  intent: KernelIntent,
+  env: EdgeEnv,
+): Promise<{ text: string; cost: number }> {
+  if (!env.ai) throw new Error('Workers AI binding not available');
+  const factory = buildLLMProviderFactory(env);
+  const result = await factory.generateResponse({
+    messages: [{ role: 'user', content: intent.raw }],
+    model: '@cf/meta/llama-3.3-70b-instruct-fp8-fast',
+    systemPrompt: buildGroqSystemPrompt(),
+  });
+  return { text: result.message || '(no response)', cost: result.usage.cost };
+}
+
+const GPT_OSS_TOOL_ROUNDS = 8; // 10 max − 2 reserved for summary
+
+export async function executeGptOss(
+  intent: KernelIntent,
+  env: EdgeEnv,
+): Promise<{ text: string; cost: number }> {
+  if (!env.ai) throw new Error('Workers AI binding not available');
+
+  const factory = buildLLMProviderFactory(env);
+  const registry = buildMcpRegistry(env);
+  const mcpClient = new McpClient({
+    url: operatorConfig.integrations.bizops.fallbackUrl,
+    token: env.bizopsToken,
+    prefix: 'bizops',
+    fetcher: env.bizopsFetcher,
+    rpcPath: '/rpc',
+  });
+
+  const pseudoConfig = {
+    apiKey: '',
+    model: env.gptOssModel,
+    mcpClient,
+    mcpRegistry: registry,
+    db: env.db,
+    channel: 'web',
+    conversationId: intent.source.threadId,
+    githubToken: env.githubToken,
+    githubRepo: env.githubRepo,
+    braveApiKey: env.braveApiKey,
+    userQuery: intent.raw,
+  };
+  const { systemPrompt, tools: anthropicTools } = await buildContext(pseudoConfig);
+  // toOpenAiTools output matches factory Tool shape exactly
+  const tools = toOpenAiTools(anthropicTools) as Parameters<typeof factory.generateResponse>[0]['tools'];
+
+  const history = intent.source.threadId
+    ? await getConversationHistory(env.db, intent.source.threadId, 10)
+    : [];
+  const priorHistory = history.length > 0 && history[history.length - 1]?.role === 'user'
+    ? history.slice(0, -1)
+    : history;
+
+  const messages: LLMMessage[] = [
+    { role: 'system', content: systemPrompt },
+    ...budgetConversationHistory(priorHistory).map(m => ({
+      role: m.role as 'user' | 'assistant',
+      content: m.content,
+    })),
+    { role: 'user', content: intent.raw },
+  ];
+
+  let totalCost = 0;
+
+  // Phase 1: tool-calling rounds
+  for (let round = 0; round < GPT_OSS_TOOL_ROUNDS; round++) {
+    const result = await factory.generateResponse({
+      messages,
+      model: env.gptOssModel,
+      tools,
+      maxTokens: 4096,
+      temperature: 0.2,
+      topP: 0.9,
+      frequencyPenalty: 0.3,
+    });
+    totalCost += result.usage.cost;
+
+    if (!result.toolCalls || result.toolCalls.length === 0) {
+      return { text: result.message || '(no response)', cost: totalCost };
+    }
+
+    const toolResults: LLMToolResult[] = [];
+    for (const call of result.toolCalls) {
+      let args: Record<string, unknown> = {};
+      try { args = JSON.parse(call.function.arguments); } catch { /* empty args */ }
+
+      let output: string;
+      const inProcess = await handleInProcessTool(
+        env.db, call.function.name, args,
+        env.githubToken, env.githubRepo, env.braveApiKey,
+        undefined, undefined, env.memoryBinding,
+        { resendApiKey: env.resendApiKey, resendApiKeyPersonal: env.resendApiKeyPersonal },
+      );
+
+      if (inProcess !== null) {
+        output = inProcess;
+      } else {
+        const resolved = resolveMcpTool(call.function.name, mcpClient, registry);
+        if (resolved) {
+          output = await callMcpWithRetry(resolved.client, resolved.mcpName, args);
+        } else {
+          output = `Unknown tool: ${call.function.name}`;
+        }
+      }
+      toolResults.push({ id: call.id, output });
+    }
+
+    // Attach tool results to the assistant message; cloudflare provider expands
+    // toolResults into separate role:'tool' messages when serializing the next request
+    messages.push({
+      role: 'assistant',
+      content: result.message,
+      toolCalls: result.toolCalls,
+      toolResults,
+    });
+  }
+
+  // Phase 2: condense tool history and generate a text-only summary.
+  // Condensed messages carry no toolCalls/toolResults, so the factory's
+  // usesTools check is false and no tool definitions are sent — preserving
+  // the GPT-OSS "no tools in Phase 2" invariant.
+  const condensed: LLMMessage[] = [messages[0]]; // system prompt
+  const toolFindings: string[] = [];
+  let lastAssistantText = '';
+
+  for (let i = 1; i < messages.length; i++) {
+    const msg = messages[i];
+    if (msg.role === 'user') {
+      condensed.push({ role: 'user', content: msg.content });
+    } else if (msg.role === 'assistant') {
+      if (msg.content?.trim().length) lastAssistantText = msg.content;
+      if (msg.content) toolFindings.push(msg.content);
+      if (msg.toolResults) {
+        for (const tr of msg.toolResults) {
+          const truncated = tr.output.length > 2000
+            ? tr.output.slice(0, 2000) + '... [truncated]'
+            : tr.output;
+          toolFindings.push(truncated);
+        }
+      }
+    }
+  }
+
+  if (toolFindings.length > 0) {
+    const BUDGET = 30_000;
+    let accumulated = '';
+    for (const finding of toolFindings) {
+      if (accumulated.length + finding.length > BUDGET) {
+        accumulated += '\n[... additional findings truncated for summary]';
+        break;
+      }
+      accumulated += '\n' + finding;
+    }
+    condensed.push({ role: 'assistant', content: `Here is what I gathered:\n${accumulated.trim()}` });
+  }
+  condensed.push({ role: 'user', content: 'Based on everything you have gathered from the tools above, provide your complete answer now. Summarize your findings clearly and concisely.' });
+
+  let summaryText: string | undefined;
+  try {
+    const summaryResult = await factory.generateResponse({
+      messages: condensed,
+      model: env.gptOssModel,
+      maxTokens: 4096,
+      temperature: 0.2,
+      topP: 0.9,
+      frequencyPenalty: 0.3,
+    });
+    totalCost += summaryResult.usage.cost;
+    summaryText = summaryResult.message || undefined;
+    if (!summaryText) {
+      console.warn('[executeGptOss] Summary phase returned no text.');
+    }
+  } catch (err) {
+    console.error('[executeGptOss] Summary phase failed:', err instanceof Error ? err.message : String(err));
+  }
+
+  if (!summaryText && lastAssistantText.length > 20) {
+    summaryText = lastAssistantText;
+  }
+
+  return { text: summaryText ?? '(could not generate summary)', cost: totalCost };
+}

package/src/kernel/provider-factory.ts

@@ -0,0 +1,36 @@
+import { createLLMProviderFactory, type LLMProviderFactory } from '@stackbilt/llm-providers';
+import type { EdgeEnv } from './dispatch.js';
+
+// ─── Fallback ownership ──────────────────────────────────────
+// EXECUTOR_ROUTES (executor-router.ts) owns the fallback policy, not this factory.
+// Factory-level fallbackRules are left empty to prevent double-firing:
+//   - Router fallback re-dispatches with a different *semantic executor* (different
+//     model, cost ceiling, telemetry tag) and must surface actualExecutor to the
+//     procedure store (see executeWithAnthropicFailover in executors/index.ts:67).
+//   - A factory-level fallback would silently swap providers inside a single call,
+//     bypassing actualExecutor tracking and producing wrong telemetry.
+// Circuit breaker and retries operate below the executor boundary and do not
+// interfere with executor-level fallback routing — they are kept enabled.
+
+export function buildLLMProviderFactory(env: EdgeEnv): LLMProviderFactory {
+  return createLLMProviderFactory({
+    anthropic: {
+      apiKey: env.anthropicApiKey,
+      baseUrl: env.anthropicBaseUrl,
+    },
+    // Cloudflare Workers AI: wired when the AI binding is present.
+    // The factory uses the `ai` binding directly for Workers AI inference;
+    // no accountId is required for service-binding usage.
+    cloudflare: env.ai ? { ai: env.ai } : undefined,
+    groq: {
+      apiKey: env.groqApiKey,
+      baseUrl: env.groqBaseUrl || undefined,
+    },
+    // Cerebras: no EdgeEnv fields yet (cerebrasApiKey, cerebrasModel).
+    // Add here when executors/cerebras.ts and the corresponding EdgeEnv fields land.
+
+    fallbackRules: [],
+    enableCircuitBreaker: true,
+    enableRetries: true,
+  });
+}

package/src/routes/observability.ts

@@ -3,9 +3,16 @@
 import { Hono } from 'hono';
 import type { Env } from '../types.js';
 import { getAllProceduresWithDerivedStats, getActiveAgendaItems } from '../kernel/memory/index.js';
+import { detectEntropy } from '../kernel/scheduled/entropy.js';
+import { buildEdgeEnv } from '../edge-env.js';
 
 const observability = new Hono<{ Bindings: Env }>();
 
+function boundedDays(value: string | undefined, fallback: number, max: number): number {
+  const days = parseInt(value ?? String(fallback), 10);
+  return Number.isNaN(days) || days < 1 || days > max ? fallback : days;
+}
+
 // ─── Shadow Write Stats ─────────────────────────────────────
 
 observability.get('/api/shadow-stats', async (c) => {
@@ -46,6 +53,124 @@ observability.get('/api/shadow-read-stats', async (c) => {
   return c.json({ days, summary, by_site: bySite.results, recent: recent.results });
 });
 
+// ─── Entropy ────────────────────────────────────────────────
+
+observability.get('/api/entropy', async (c) => {
+  // detectEntropy needs the full EdgeEnv (API keys, model config) — not just c.env.DB
+  const env = buildEdgeEnv(c.env);
+  const report = await detectEntropy(env);
+  return c.json(report);
+});
+
+// ─── Shadow Read Drift ──────────────────────────────────────
+
+observability.get('/api/shadow-read-drift', async (c) => {
+  const days = boundedDays(c.req.query('days'), 7, 30);
+  const reader = c.req.query('reader');
+
+  const latestWhere = reader
+    ? "WHERE reader = ? AND sampled_at > datetime('now', '-' || ? || ' days')"
+    : "WHERE sampled_at > datetime('now', '-' || ? || ' days')";
+  // latestBindings: reader-first to match latestWhere (WHERE reader = ? AND sampled_at...)
+  // windowBindings: days-first to match the WHERE sampled_at... AND reader = ? pattern used in distribution/topDrifters
+  const latestBindings = reader ? [reader, days] : [days];
+  const windowBindings = reader ? [days, reader] : [days];
+
+  const [distribution, readiness, topDrifters] = await Promise.all([
+    c.env.DB.prepare(`
+      WITH ranked AS (
+        SELECT reader,
+          ABS((cached_count - pre_tier_count) - derived_count) AS count_abs_drift,
+          ABS(cached_avg_latency_ms - derived_avg_latency_ms) AS latency_abs_drift,
+          ABS(cached_avg_cost - derived_avg_cost) AS cost_abs_drift,
+          ROW_NUMBER() OVER (PARTITION BY reader ORDER BY ABS((cached_count - pre_tier_count) - derived_count)) AS count_rank,
+          ROW_NUMBER() OVER (PARTITION BY reader ORDER BY ABS(cached_avg_latency_ms - derived_avg_latency_ms)) AS latency_rank,
+          ROW_NUMBER() OVER (PARTITION BY reader ORDER BY ABS(cached_avg_cost - derived_avg_cost)) AS cost_rank,
+          COUNT(*) OVER (PARTITION BY reader) AS n
+        FROM shadow_read_drift
+        WHERE sampled_at > datetime('now', '-' || ? || ' days')
+        ${reader ? 'AND reader = ?' : ''}
+      )
+      SELECT reader,
+        MAX(n) AS samples,
+        ROUND(AVG(count_abs_drift), 2) AS avg_abs_count_drift,
+        ROUND(MAX(count_abs_drift), 2) AS max_abs_count_drift,
+        ROUND(MAX(CASE WHEN count_rank = MAX(1, (n + 1) / 2) THEN count_abs_drift END), 2) AS p50_count_drift,
+        ROUND(MAX(CASE WHEN count_rank = MAX(1, (n * 19 + 19) / 20) THEN count_abs_drift END), 2) AS p95_count_drift,
+        ROUND(MAX(CASE WHEN count_rank = MAX(1, (n * 99 + 99) / 100) THEN count_abs_drift END), 2) AS p99_count_drift,
+        ROUND(AVG(latency_abs_drift), 2) AS avg_latency_drift_ms,
+        ROUND(MAX(latency_abs_drift), 2) AS max_latency_drift_ms,
+        ROUND(MAX(CASE WHEN latency_rank = MAX(1, (n + 1) / 2) THEN latency_abs_drift END), 2) AS p50_latency_drift_ms,
+        ROUND(MAX(CASE WHEN latency_rank = MAX(1, (n * 19 + 19) / 20) THEN latency_abs_drift END), 2) AS p95_latency_drift_ms,
+        ROUND(MAX(CASE WHEN latency_rank = MAX(1, (n * 99 + 99) / 100) THEN latency_abs_drift END), 2) AS p99_latency_drift_ms,
+        ROUND(AVG(cost_abs_drift), 6) AS avg_cost_drift,
+        ROUND(MAX(cost_abs_drift), 6) AS max_cost_drift,
+        ROUND(MAX(CASE WHEN cost_rank = MAX(1, (n + 1) / 2) THEN cost_abs_drift END), 6) AS p50_cost_drift,
+        ROUND(MAX(CASE WHEN cost_rank = MAX(1, (n * 19 + 19) / 20) THEN cost_abs_drift END), 6) AS p95_cost_drift,
+        ROUND(MAX(CASE WHEN cost_rank = MAX(1, (n * 99 + 99) / 100) THEN cost_abs_drift END), 6) AS p99_cost_drift
+      FROM ranked
+      GROUP BY reader
+    `).bind(...windowBindings).all(),
+
+    c.env.DB.prepare(`
+      WITH latest AS (
+        SELECT reader, task_pattern, cached_count, cached_success_count,
+          cached_avg_latency_ms, cached_avg_cost,
+          derived_count, derived_success_count,
+          derived_avg_latency_ms, derived_avg_cost,
+          pre_tier_count,
+          ROW_NUMBER() OVER (PARTITION BY reader, task_pattern ORDER BY sampled_at DESC) as rn
+        FROM shadow_read_drift
+        ${latestWhere}
+      )
+      SELECT
+        COUNT(*) as total_pairs,
+        COUNT(DISTINCT task_pattern) as distinct_procedures,
+        SUM(CASE WHEN pre_tier_count = 0 THEN 1 ELSE 0 END) as clean_pairs,
+        SUM(CASE
+          WHEN pre_tier_count = 0
+           AND cached_count = derived_count
+           AND cached_success_count = derived_success_count
+           AND ABS(cached_avg_latency_ms - derived_avg_latency_ms) < 10
+           AND ABS(cached_avg_cost - derived_avg_cost) < 0.0001
+          THEN 1 ELSE 0 END) as ready_pairs
+      FROM latest WHERE rn = 1
+    `).bind(...latestBindings).first(),
+
+    c.env.DB.prepare(`
+      WITH latest_per_pattern AS (
+        SELECT task_pattern, reader,
+          cached_count, derived_count, pre_tier_count,
+          cached_avg_latency_ms, derived_avg_latency_ms,
+          cached_avg_cost, derived_avg_cost,
+          sampled_at,
+          ROW_NUMBER() OVER (PARTITION BY task_pattern, reader ORDER BY sampled_at DESC) as rn
+        FROM shadow_read_drift
+        WHERE sampled_at > datetime('now', '-' || ? || ' days')
+        ${reader ? 'AND reader = ?' : ''}
+      )
+      SELECT task_pattern, reader,
+        cached_count, derived_count, pre_tier_count,
+        ABS((cached_count - pre_tier_count) - derived_count) as count_drift,
+        ROUND(ABS(cached_avg_latency_ms - derived_avg_latency_ms), 1) as latency_drift,
+        ROUND(ABS(cached_avg_cost - derived_avg_cost), 6) as cost_drift,
+        sampled_at
+      FROM latest_per_pattern
+      WHERE rn = 1
+      ORDER BY ABS((cached_count - pre_tier_count) - derived_count) DESC
+      LIMIT 15
+    `).bind(...windowBindings).all(),
+  ]);
+
+  return c.json({
+    days,
+    reader_filter: reader ?? null,
+    distribution: distribution.results,
+    readiness,
+    top_drifters: topDrifters.results,
+  });
+});
+
 // ─── Agenda ─────────────────────────────────────────────────
 
 observability.get('/agenda', async (c) => {