@stackbilt/aegis-core 0.6.5 → 0.7.0

package/src/groq.ts

@@ -1,4 +1,24 @@
-// Edge-native Groq client — fetch-based, no OpenAI SDK dependency
+// Edge-native Groq helpers backed by @stackbilt/llm-providers
+
+import { createLLMProviderFactory, type LLMMessage } from '@stackbilt/llm-providers';
+import { tokenize, jaccardSimilarity } from './kernel/memory/index.js';
+import { cosineSimilarity } from './kernel/memory/semantic.js';
+import type { MemoryServiceBinding } from './types.js';
+
+function buildGroqFactory(apiKey: string, baseUrl: string) {
+  return createLLMProviderFactory({
+    groq: { apiKey, baseUrl },
+    fallbackRules: [],
+    enableCircuitBreaker: true,
+    enableRetries: true,
+  });
+}
+
+function coerceText(content: unknown): string {
+  if (typeof content === 'string') return content;
+  if (content == null) return '';
+  return typeof content === 'object' ? JSON.stringify(content) : String(content);
+}
 
 export async function askGroq(
   apiKey: string,
@@ -7,45 +27,27 @@ export async function askGroq(
   userPrompt: string,
   baseUrl = 'https://api.groq.com',
 ): Promise<string> {
-  const response = await fetch(`${baseUrl}/openai/v1/chat/completions`, {
-    method: 'POST',
-    headers: {
-      'Content-Type': 'application/json',
-      'Authorization': `Bearer ${apiKey}`,
-    },
-    body: JSON.stringify({
+  try {
+    const result = await buildGroqFactory(apiKey, baseUrl).generateResponse({
       model,
+      systemPrompt,
       temperature: 0.3,
-      max_tokens: 500,
+      maxTokens: 500,
       messages: [
-        { role: 'system', content: systemPrompt },
         { role: 'user', content: userPrompt },
       ],
-    }),
-  });
-
-  if (!response.ok) {
-    const errText = await response.text();
-    throw new Error(`Groq API error ${response.status}: ${errText}`);
+    });
+    return coerceText(result.message);
+  } catch (err) {
+    const msg = err instanceof Error ? err.message : String(err);
+    throw new Error(`Groq API error: ${msg}`);
   }
-
-  const data = await response.json<{
-    choices: { message: { content: unknown } }[];
-    usage?: { total_tokens: number };
-  }>();
-
-  const content = data.choices[0]?.message?.content;
-  if (typeof content === 'string') return content;
-  if (content == null) return '';
-  // Some Groq-routed models (notably gpt-oss tool-calling variants) return content
-  // as an array of content blocks. Coerce so downstream string operations don't crash.
-  return typeof content === 'object' ? JSON.stringify(content) : String(content);
 }
 
-// ─── Logprobs-enabled classification ─────────────────────────
-// Requests logprobs from Groq's OpenAI-compatible API and computes
-// geometric mean of token probabilities for the classification value.
-// Returns both self-reported confidence and token-level confidence.
+// ─── Classification confidence helper ────────────────────────
+// Provider-backed replacement for the former raw Groq logprobs call.
+// llm-providers does not expose provider logprob request options yet, so
+// tokenConfidence mirrors self-reported confidence until that contract lands.
 
 export interface LogprobClassification {
   pattern: string;
@@ -62,65 +64,20 @@ export async function askGroqWithLogprobs(
   userPrompt: string,
   baseUrl = 'https://api.groq.com',
 ): Promise<LogprobClassification> {
-  const response = await fetch(`${baseUrl}/openai/v1/chat/completions`, {
-    method: 'POST',
-    headers: {
-      'Content-Type': 'application/json',
-      'Authorization': `Bearer ${apiKey}`,
-    },
-    body: JSON.stringify({
-      model,
-      temperature: 0.1,
-      max_tokens: 200,
-      response_format: { type: 'json_object' },
-      logprobs: true,
-      top_logprobs: 3,
-      messages: [
-        { role: 'system', content: systemPrompt },
-        { role: 'user', content: userPrompt },
-      ],
-    }),
-  });
-
-  if (!response.ok) {
-    const errText = await response.text();
-    throw new Error(`Groq logprobs API error ${response.status}: ${errText}`);
-  }
-
-  interface LogprobToken {
-    token: string;
-    logprob: number;
-  }
-
-  const data = await response.json<{
-    choices: {
-      message: { content: string };
-      logprobs?: { content?: LogprobToken[] };
-    }[];
-  }>();
-
-  const raw = data.choices[0]?.message?.content ?? '{}';
-  const parsed = JSON.parse(raw) as {
+  const { parsed } = await askGroqJson<{
     pattern?: string;
     complexity?: number;
     needs_tools?: boolean;
     confidence?: number;
-  };
-
-  // Compute geometric mean of token logprobs
-  let tokenConfidence = 0.5; // fallback if no logprobs
-  const logprobTokens = data.choices[0]?.logprobs?.content;
-  if (logprobTokens && logprobTokens.length > 0) {
-    const sumLogprobs = logprobTokens.reduce((sum, t) => sum + t.logprob, 0);
-    tokenConfidence = Math.exp(sumLogprobs / logprobTokens.length);
-  }
+  }>(apiKey, model, systemPrompt, userPrompt, baseUrl, { maxTokens: 200, temperature: 0.1 });
+  const confidence = parsed.confidence ?? 0.5;
 
   return {
     pattern: (parsed.pattern ?? 'general_knowledge').toLowerCase().replace(/[^a-z_]/g, ''),
     complexity: parsed.complexity ?? 2,
     needs_tools: parsed.needs_tools ?? false,
-    selfReportedConfidence: parsed.confidence ?? 0.5,
-    tokenConfidence,
+    selfReportedConfidence: confidence,
+    tokenConfidence: confidence,
   };
 }
 
@@ -130,10 +87,6 @@ export async function askGroqWithLogprobs(
 // Jaccard when memoryBinding is unavailable.
 // Returns σ metric: 0=all agree, 0.5=partial, 1.0=disagree.
 
-import { tokenize, jaccardSimilarity } from './kernel/memory/index.js';
-import { cosineSimilarity } from './kernel/memory/semantic.js';
-import type { MemoryServiceBinding } from './types.js';
-
 const PROBE_TIMEOUT_MS = 3_000;
 const JACCARD_AGREEMENT_THRESHOLD = 0.5;
 const COSINE_AGREEMENT_THRESHOLD = 0.85;
@@ -210,8 +163,7 @@ export async function askGroqJson<T = unknown>(
   baseUrl = 'https://api.groq.com',
   options?: { maxTokens?: number; temperature?: number; prefill?: string },
 ): Promise<{ parsed: T; raw: string; usage?: { prompt_tokens: number; completion_tokens: number } }> {
-  const messages: Array<{ role: string; content: string }> = [
-    { role: 'system', content: systemPrompt },
+  const messages: LLMMessage[] = [
     { role: 'user', content: userPrompt },
   ];
   // Prefilling: seed the assistant response to steer tone/format
@@ -219,34 +171,30 @@ export async function askGroqJson<T = unknown>(
     messages.push({ role: 'assistant', content: options.prefill });
   }
 
-  const response = await fetch(`${baseUrl}/openai/v1/chat/completions`, {
-    method: 'POST',
-    headers: {
-      'Content-Type': 'application/json',
-      'Authorization': `Bearer ${apiKey}`,
-    },
-    body: JSON.stringify({
+  try {
+    const result = await buildGroqFactory(apiKey, baseUrl).generateResponse({
       model,
+      systemPrompt,
       temperature: options?.temperature ?? 0.2,
-      max_tokens: options?.maxTokens ?? 2000,
+      maxTokens: options?.maxTokens ?? 2000,
       response_format: { type: 'json_object' },
       messages,
-    }),
-  });
-
-  if (!response.ok) {
-    const errText = await response.text();
-    throw new Error(`Groq API error ${response.status}: ${errText}`);
+    });
+
+    const completion = result.message ?? '{}';
+    // If prefilled, the model continues from the prefill — concatenate for valid JSON
+    const raw = options?.prefill ? options.prefill + completion : completion;
+    const parsed = JSON.parse(raw) as T;
+    return {
+      parsed,
+      raw,
+      usage: {
+        prompt_tokens: result.usage.inputTokens,
+        completion_tokens: result.usage.outputTokens,
+      },
+    };
+  } catch (err) {
+    const msg = err instanceof Error ? err.message : String(err);
+    throw new Error(`Groq API error: ${msg}`);
   }
-
-  const data = await response.json<{
-    choices: { message: { content: string } }[];
-    usage?: { prompt_tokens: number; completion_tokens: number };
-  }>();
-
-  const completion = data.choices[0]?.message?.content ?? '{}';
-  // If prefilled, the model continues from the prefill — concatenate for valid JSON
-  const raw = options?.prefill ? options.prefill + completion : completion;
-  const parsed = JSON.parse(raw) as T;
-  return { parsed, raw, usage: data.usage };
 }

package/src/index.ts

@@ -24,6 +24,7 @@ import { observability } from './routes/observability.js';
 import { pages } from './routes/pages.js';
 import { ccTasks } from './routes/cc-tasks.js';
 import { messages } from './routes/messages.js';
+import { chatWs } from './routes/chat-ws.js';
 import { content } from './routes/content.js';
 import { codebeast } from './routes/codebeast.js';
 import { bluesky } from './routes/bluesky.js';
@@ -44,6 +45,7 @@ app.route('/', observability);
 app.route('/', pages);
 app.route('/', ccTasks);
 app.route('/', messages);
+app.route('/', chatWs);
 app.route('/', content);
 app.route('/', codebeast);
 app.route('/', bluesky);
@@ -87,3 +89,5 @@ export default {
     ctx.waitUntil(runScheduledTasks(buildEdgeEnv(env)));
   },
 };
+
+export { ChatSession } from './durable-objects/chat-session.js';

package/src/kernel/disambiguation.ts

@@ -0,0 +1,55 @@
+export interface DisambiguationRequest {
+  concept: string;
+  question: string;
+}
+
+const DATA_INTENT =
+  /\b(what|show|calculate|report|compare|analy[sz]e|trend|metric|dashboard|how many|how much|rate)\b/i;
+
+const KNOWN_DATA_SURFACES =
+  /\b(compliance|deadline|deadlines|filing|filings|document|documents|project|projects|agenda|goal|goals|task|tasks|health|heartbeat)\b/i;
+
+const DISAMBIGUATORS =
+  /\b(by|defined as|definition|seat count|seats|mrr|arr|gross|net|monthly|annual|period|last \d+|past \d+|count|rate)\b/i;
+
+const AMBIGUOUS_CONCEPTS: Array<{ name: string; pattern: RegExp; question: string }> = [
+  {
+    name: 'churn',
+    pattern: /\bchurn\b/i,
+    question: 'Do you mean churn by seat count, account count, revenue, MRR, or another defined basis?',
+  },
+  {
+    name: 'retention',
+    pattern: /\bretention\b/i,
+    question: 'Do you mean retention by user, account, seat, revenue, cohort, or another defined basis?',
+  },
+  {
+    name: 'active users',
+    pattern: /\b(active users?|users?)\b/i,
+    question: 'Do you mean active users by login, event activity, paid seat, account membership, or another defined rule?',
+  },
+  {
+    name: 'conversion',
+    pattern: /\b(conversion|activation)\b/i,
+    question: 'Do you mean conversion by visit, signup, qualified lead, paid account, or another funnel step?',
+  },
+  {
+    name: 'revenue',
+    pattern: /\b(revenue|growth)\b/i,
+    question: 'Do you mean revenue by gross, net, MRR, ARR, cash receipts, or another defined basis?',
+  },
+];
+
+export function detectDisambiguationNeed(message: string): DisambiguationRequest | null {
+  if (!DATA_INTENT.test(message)) return null;
+  if (KNOWN_DATA_SURFACES.test(message)) return null;
+  if (DISAMBIGUATORS.test(message)) return null;
+
+  for (const concept of AMBIGUOUS_CONCEPTS) {
+    if (concept.pattern.test(message)) {
+      return { concept: concept.name, question: concept.question };
+    }
+  }
+
+  return null;
+}

package/src/kernel/dispatch.ts

@@ -1,12 +1,20 @@
 import { route } from './router.js';
 import { recordEpisode, retrogradeEpisode, upsertProcedure, addRefinement, degradeProcedure, getProcedure, procedureKey } from './memory/index.js';
-import { searchMemoryByKeywords, getAllMemoryForContext } from './memory-adapter.js';
+import { getAllMemoryForContext } from './memory-adapter.js';
 import { generateBriefing, formatBriefing } from './briefing.js';
-import { fetchRelevantInsights } from './insight-cache.js';
 import { probeConsistency } from '../groq.js';
 import { executeComposite } from '../composite.js';
 import { buildGroqSystemPrompt } from '../operator/prompt-builder.js';
 import type { KernelIntent, DispatchResult, Executor } from './types.js';
+import type { GroundingEnvelope } from './grounding/fanout.js';
+import {
+  augmentWithEntityGrounding,
+  augmentWithInsights,
+  augmentWithMemoryRecall,
+  applyFabricationCheck,
+  applyGapSignal,
+  applyGroundingProof,
+} from './grounding-layer.js';
 import {
   executeGptOss,
   executeClaudeStream,
@@ -113,6 +121,7 @@ async function recordOutcome(
   latencyMs: number,
   nearMiss: string | null | undefined,
   outcome: 'success' | 'failure' | 'partial_failure',
+  groundingGap: boolean,
   reclassified?: boolean,
 ): Promise<void> {
   await recordEpisode(env.db, {
@@ -127,6 +136,7 @@ async function recordOutcome(
     reclassified,
     thread_id: intent.source.threadId,
     executor: plan.executor,
+    grounding_gap: groundingGap,
   });
 
   await upsertProcedure(env.db, procKey, plan.executor, JSON.stringify({ executor: plan.executor }), outcome, latencyMs, cost);
@@ -156,43 +166,29 @@ interface AugmentedContext {
   classification: string;
   procKey: string;
   existingProcedure: Awaited<ReturnType<typeof getProcedure>>;
+  grounding?: GroundingEnvelope;
 }
 
 async function augmentIntent(intent: KernelIntent, env: EdgeEnv): Promise<AugmentedContext> {
   // 1. Route
   const { plan, nearMiss, reclassified } = await route(intent, env.db, env.groqApiKey, env.groqModel, env.groqBaseUrl, env.ai, env.tarotscriptFetcher);
+  if (intent.forcedExecutor) {
+    plan.executor = intent.forcedExecutor;
+    plan.reasoning = `Forced by channel frame: ${intent.forcedExecutor}`;
+    plan.costCeiling = intent.forcedExecutor === 'direct' ? 'free'
+      : intent.forcedExecutor === 'workers_ai' || intent.forcedExecutor === 'gpt_oss' || intent.forcedExecutor === 'groq'
+        ? 'cheap'
+        : 'expensive';
+  }
   const classification = intent.classified ?? 'unknown';
   const procKey = procedureKey(classification, intent.complexity);
   const existingProcedure = await getProcedure(env.db, procKey);
 
-  // 1.3. Cross-repo insight augmentation (CRIX #106)
-  if (env.memoryBinding && classification !== 'greeting' && classification !== 'heartbeat') {
-    try {
-      const insightContext = await fetchRelevantInsights(env, classification, intent.raw);
-      if (insightContext) {
-        intent.raw = `${insightContext}\n\n${intent.raw}`;
-      }
-    } catch (err) {
-      console.warn('[dispatch] Insight fetch failed (non-fatal):', err instanceof Error ? err.message : String(err));
-    }
-  }
-
-  // 1.5. Memory-recall augmentation
-  if (classification === 'memory_recall') {
-    try {
-      if (env.memoryBinding) {
-        const relevant = await searchMemoryByKeywords(env.memoryBinding, intent.raw, 10);
-        if (relevant.length > 0) {
-          const memLines = relevant.map(m => `- [${m.topic}] ${m.fact} (confidence: ${m.confidence})`).join('\n');
-          intent.raw = `[Relevant memory entries matching this query]\n${memLines}\n\n[User's question]\n${intent.raw}`;
-        }
-      } else {
-        console.warn('[dispatch] Memory binding unavailable — skipping memory recall augmentation');
-      }
-    } catch (err) {
-      console.warn('[dispatch] Memory search failed (non-fatal):', err instanceof Error ? err.message : String(err));
-    }
-  }
+  // 1.3-1.5. Grounding-layer augmentations: cross-repo insights, entity
+  // grounding, and memory recall. Each helper is non-fatal by contract.
+  await augmentWithInsights(intent, classification, env);
+  const grounding = await augmentWithEntityGrounding(intent, classification, env);
+  await augmentWithMemoryRecall(intent, classification, env);
 
   // 1.6. Implicit feedback — retrograde previous episode on user correction
   if (classification === 'user_correction' && intent.source.threadId) {
@@ -221,7 +217,7 @@ async function augmentIntent(intent: KernelIntent, env: EdgeEnv): Promise<Augmen
     }
   }
 
-  return { plan, nearMiss, reclassified, classification, procKey, existingProcedure };
+  return { plan, nearMiss, reclassified, classification, procKey, existingProcedure, grounding };
 }
 
 // ─── Self-Improvement ACK ────────────────────────────────────
@@ -275,7 +271,6 @@ interface ExecuteResult {
   meta?: unknown;
   outcome: 'success' | 'failure' | 'partial_failure';
   probeResult?: 'agreed' | 'split' | 'escalated';
-  earlyReturn?: DispatchResult; // probe agreed → skip executor
 }
 
 async function probeAndExecute(
@@ -302,11 +297,8 @@ async function probeAndExecute(
         probeResult = 'agreed';
         plan.executor = 'groq';
         if (onDelta) onDelta(text);
-        const latencyMs = Date.now() - startMs;
-        await recordOutcome(env, intent, classification, procKey, plan, existingProcedure, text, cost, latencyMs, nearMiss, 'success', ctx.reclassified);
         return {
           text, cost, outcome: 'success', probeResult,
-          earlyReturn: { text, executor: plan.executor, cost, latency_ms: latencyMs, procedureHit: !!plan.procedureId, classification, confidence: intent.confidence, reclassified: ctx.reclassified, probeResult, meta: undefined },
         };
       } else if (probe.sigma === 1.0) {
         const prev = plan.executor;
@@ -489,7 +481,7 @@ function buildResult(
   exec: ExecuteResult,
   latencyMs: number,
 ): DispatchResult {
-  return {
+  const result: DispatchResult = {
     text: exec.text,
     executor: ctx.plan.executor,
     cost: exec.cost,
@@ -501,6 +493,29 @@ function buildResult(
     probeResult: exec.probeResult,
     meta: exec.meta,
   };
+  if (ctx.grounding) {
+    result.grounded = ctx.grounding.grounded;
+    result.sources = ctx.grounding.sources;
+    result.unknowns = ctx.grounding.unknowns;
+    result.searched = ctx.grounding.searched;
+  }
+  return result;
+}
+
+async function finalizeGrounding(
+  ctx: AugmentedContext,
+  intent: KernelIntent,
+  env: EdgeEnv,
+  exec: ExecuteResult,
+  latencyMs: number,
+): Promise<{ result: DispatchResult; outcome: 'success' | 'failure' | 'partial_failure'; groundingGap: boolean }> {
+  const result = buildResult(ctx, intent, exec, latencyMs);
+  await applyFabricationCheck(result, exec.text, env);
+  const outcome = applyGroundingProof(exec.outcome, ctx.classification, result);
+  const groundingGap =
+    (result.unverified_claims?.length ?? 0) > 0 ||
+    (result.unknowns?.length ?? 0) > 0;
+  return { result, outcome, groundingGap };
 }
 
 // ─── Main Dispatch Loop ──────────────────────────────────────
@@ -514,10 +529,10 @@ export async function dispatch(intent: KernelIntent, env: EdgeEnv): Promise<Disp
   if (ack) return ack;
 
   const exec = await probeAndExecute(ctx, intent, env, startMs);
-  if (exec.earlyReturn) return exec.earlyReturn;
-
   const latencyMs = Date.now() - startMs;
-  await recordOutcome(env, intent, ctx.classification, ctx.procKey, ctx.plan, ctx.existingProcedure, exec.text, exec.cost, latencyMs, ctx.nearMiss, exec.outcome, ctx.reclassified);
+  const { result, outcome, groundingGap } = await finalizeGrounding(ctx, intent, env, exec, latencyMs);
+  await recordOutcome(env, intent, ctx.classification, ctx.procKey, ctx.plan, ctx.existingProcedure, exec.text, exec.cost, latencyMs, ctx.nearMiss, outcome, groundingGap, ctx.reclassified);
+  await applyGapSignal(result, ctx.procKey, ctx.classification, env);
 
   // Background: shadow exploration + shadow read
   if (env.ctx) {
@@ -533,7 +548,7 @@ export async function dispatch(intent: KernelIntent, env: EdgeEnv): Promise<Disp
     }
   }
 
-  return buildResult(ctx, intent, exec, latencyMs);
+  return result;
 }
 
 // ─── Streaming Dispatch ──────────────────────────────────────
@@ -547,10 +562,10 @@ export async function dispatchStream(
   const ctx = await augmentIntent(intent, env);
 
   const exec = await probeAndExecute(ctx, intent, env, startMs, onDelta);
-  if (exec.earlyReturn) return exec.earlyReturn;
-
   const latencyMs = Date.now() - startMs;
-  await recordOutcome(env, intent, ctx.classification, ctx.procKey, ctx.plan, ctx.existingProcedure, exec.text, exec.cost, latencyMs, ctx.nearMiss, exec.outcome, ctx.reclassified);
+  const { result, outcome, groundingGap } = await finalizeGrounding(ctx, intent, env, exec, latencyMs);
+  await recordOutcome(env, intent, ctx.classification, ctx.procKey, ctx.plan, ctx.existingProcedure, exec.text, exec.cost, latencyMs, ctx.nearMiss, outcome, groundingGap, ctx.reclassified);
+  await applyGapSignal(result, ctx.procKey, ctx.classification, env);
 
   // Background: shadow exploration + shadow read
   if (env.ctx) {
@@ -566,5 +581,5 @@ export async function dispatchStream(
     }
   }
 
-  return buildResult(ctx, intent, exec, latencyMs);
+  return result;
 }

package/src/kernel/dynamic-tools.ts

@@ -3,6 +3,7 @@
 // No eval(). No code execution. Just parameterized prompts.
 
 import { type EdgeEnv } from './dispatch.js';
+import { buildLLMProviderFactory } from './provider-factory.js';
 import type { ToolExecutor, ToolStatus } from '../schema-enums.js';
 
 // ─── Types ──────────────────────────────────────────────────
@@ -160,58 +161,20 @@ export async function executeDynamicTool(
 ): Promise<ToolInvocationResult> {
   const rendered = renderPrompt(tool.prompt_template, inputs);
   const start = Date.now();
-  let text = '';
-  let cost = 0;
-
-  if (tool.executor === 'workers_ai' && env.ai) {
-    // Workers AI — free inference
-    const result = await env.ai.run('@cf/meta/llama-3.1-8b-instruct' as Parameters<Ai['run']>[0], {
-      messages: [
-        { role: 'system', content: 'You are a focused tool. Answer precisely. No preamble.' },
-        { role: 'user', content: rendered },
-      ],
-      max_tokens: 1024,
-    }) as { response?: string };
-    text = result.response ?? '';
-    cost = 0;
-  } else if (tool.executor === 'groq' && env.groqApiKey) {
-    // Groq — fast, cheap
-    const res = await fetch('https://api.groq.com/openai/v1/chat/completions', {
-      method: 'POST',
-      headers: {
-        'Authorization': `Bearer ${env.groqApiKey}`,
-        'Content-Type': 'application/json',
-      },
-      body: JSON.stringify({
-        model: env.groqModel ?? 'llama-3.3-70b-versatile',
-        messages: [
-          { role: 'system', content: 'You are a focused tool. Answer precisely. No preamble.' },
-          { role: 'user', content: rendered },
-        ],
-        max_tokens: 1024,
-      }),
-      signal: AbortSignal.timeout(15_000),
-    });
-    if (!res.ok) throw new Error(`Groq error: ${res.status}`);
-    const data = await res.json() as { choices: Array<{ message: { content: string } }> };
-    text = data.choices[0]?.message?.content ?? '';
-    cost = 0.001; // ~$0.001 per Groq call
-  } else {
-    // Default: Workers AI fallback (always available on CF Workers)
-    if (env.ai) {
-      const result = await env.ai.run('@cf/meta/llama-3.1-8b-instruct' as Parameters<Ai['run']>[0], {
-        messages: [
-          { role: 'system', content: 'You are a focused tool. Answer precisely. No preamble.' },
-          { role: 'user', content: rendered },
-        ],
-        max_tokens: 1024,
-      }) as { response?: string };
-      text = result.response ?? '';
-      cost = 0;
-    } else {
-      throw new Error(`Executor "${tool.executor}" not available — no API key or binding`);
-    }
-  }
+  const executor = tool.executor as ToolExecutor;
+  const model = resolveDynamicToolModel(executor, env);
+  const factory = buildLLMProviderFactory(env);
+  const result = await factory.generateResponse({
+    model,
+    messages: [
+      { role: 'system', content: 'You are a focused tool. Answer precisely. No preamble.' },
+      { role: 'user', content: rendered },
+    ],
+    maxTokens: 1024,
+    temperature: 0.2,
+  });
+  const text = result.message ?? '';
+  const cost = result.usage.cost;
 
   const latencyMs = Date.now() - start;
 
@@ -229,6 +192,21 @@ export async function executeDynamicTool(
   return { text, cost, latency_ms: latencyMs, executor: tool.executor };
 }
 
+function resolveDynamicToolModel(executor: ToolExecutor, env: EdgeEnv): string {
+  if (executor === 'workers_ai') {
+    if (!env.ai) throw new Error('Executor "workers_ai" not available — no AI binding');
+    return '@cf/meta/llama-3.1-8b-instruct';
+  }
+
+  if (executor === 'groq') {
+    if (!env.groqApiKey) throw new Error('Executor "groq" not available — no Groq API key');
+    return env.groqModel ?? 'llama-3.3-70b-versatile';
+  }
+
+  if (!env.ai) throw new Error(`Executor "${executor}" not available — no AI binding`);
+  return env.gptOssModel;
+}
+
 // ─── Lifecycle (GC + Promotion) ─────────────────────────────
 
 const MAX_ACTIVE_TOOLS = 50;

package/src/kernel/executors/claude.ts

@@ -28,6 +28,7 @@ function buildClaudeConfig(env: EdgeEnv, intent: KernelIntent, model: string, re
     braveApiKey: env.braveApiKey,
     roundtableDb: env.roundtableDb,
     memoryBinding: env.memoryBinding,
+    edgeEnv: env,
   };
 }
 

package/src/kernel/executors/direct.ts

@@ -90,6 +90,20 @@ export async function executeDirect(
   intent: KernelIntent,
   env: EdgeEnv,
 ): Promise<{ text: string; cost: number; meta?: unknown }> {
+  if (intent.classified === 'request_clarification') {
+    const question = intent.disambiguation?.question
+      ?? 'This data concept is ambiguous. Which exact definition should I use?';
+    return {
+      text: question,
+      cost: 0,
+      meta: {
+        clarificationRequired: true,
+        concept: intent.disambiguation?.concept ?? 'unknown',
+        source: 'disambiguation_firewall',
+      },
+    };
+  }
+
   if (intent.classified === 'heartbeat') {
     // Edge heartbeat: call BizOps dashboard + CF infrastructure in parallel, triage with structured JSON
     const mcpClient = new McpClient({