@stackbilt/aegis-core 0.6.4 → 0.7.0

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

@@ -53,7 +53,11 @@ export async function executeGptOss(
     githubToken: env.githubToken,
     githubRepo: env.githubRepo,
     braveApiKey: env.braveApiKey,
+    roundtableDb: env.roundtableDb,
+    memoryBinding: env.memoryBinding,
+    resendApiKeys: { resendApiKey: env.resendApiKey, resendApiKeyPersonal: env.resendApiKeyPersonal },
     userQuery: intent.raw,
+    edgeEnv: env,
   };
   const { systemPrompt, tools: anthropicTools } = await buildContext(pseudoConfig);
   // toOpenAiTools output matches factory Tool shape exactly
@@ -105,6 +109,7 @@ export async function executeGptOss(
         env.githubToken, env.githubRepo, env.braveApiKey,
         undefined, undefined, env.memoryBinding,
         { resendApiKey: env.resendApiKey, resendApiKeyPersonal: env.resendApiKeyPersonal },
+        env,
       );
 
       if (inProcess !== null) {

package/src/kernel/memory/episodic.ts

@@ -16,13 +16,15 @@ export function sanitizeEpisodicOutcome(raw: string | null | undefined): Episodi
 
 export async function recordEpisode(db: D1Database, entry: Omit<EpisodicEntry, 'id' | 'created_at'>): Promise<void> {
   const safeOutcome = sanitizeEpisodicOutcome(entry.outcome);
+  const groundingGap = entry.grounding_gap ? 1 : 0;
   await db.prepare(
-    'INSERT INTO episodic_memory (intent_class, channel, summary, outcome, cost, latency_ms, near_miss, classifier_confidence, reclassified, thread_id, executor) VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)'
+    'INSERT INTO episodic_memory (intent_class, channel, summary, outcome, cost, latency_ms, near_miss, classifier_confidence, reclassified, thread_id, executor, grounding_gap) VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)'
   ).bind(
     entry.intent_class, entry.channel, entry.summary, safeOutcome,
     entry.cost, entry.latency_ms, entry.near_miss ?? null,
     entry.classifier_confidence ?? null, entry.reclassified ? 1 : 0,
     entry.thread_id ?? null, entry.executor ?? null,
+    groundingGap,
   ).run();
 }
 

package/src/kernel/router.ts

@@ -1,8 +1,10 @@
+import { createLLMProviderFactory } from '@stackbilt/llm-providers';
 import { getProcedure, findNearMiss, procedureKey, PROCEDURE_MIN_SUCCESSES, PROCEDURE_MIN_SUCCESS_RATE, getConversationHistory } from './memory/index.js';
 import { askGroq, askGroqWithLogprobs } from '../groq.js';
 import type { KernelIntent, ExecutionPlan, Executor } from './types.js';
 import { buildClassifySystem, getTaskPatterns } from '../operator/prompt-builder.js';
 import { domainPreFilter } from './domain.js';
+import { detectDisambiguationNeed } from './disambiguation.js';
 
 // ─── Confidence Thresholds ──────────────────────────────────
 const CONFIDENCE_TRUST = 0.80;   // ≥ 0.80 → use classification as-is
@@ -72,21 +74,21 @@ async function classifyWithWorkersAI(
   systemPrompt: string,
   userPrompt: string,
 ): Promise<string> {
-  const result = await ai.run('@cf/meta/llama-3.2-3b-instruct', {
+  const result = await createLLMProviderFactory({
+    cloudflare: { ai },
+    fallbackRules: [],
+    enableCircuitBreaker: true,
+    enableRetries: true,
+  }).generateResponse({
+    model: '@cf/meta/llama-3.1-8b-instruct',
+    systemPrompt,
     messages: [
-      { role: 'system', content: systemPrompt },
       { role: 'user', content: userPrompt },
     ],
-    max_tokens: 200,
+    maxTokens: 200,
     temperature: 0.1,
-  }) as { response?: unknown };
-  const raw = result.response;
-  if (typeof raw === 'string') return raw;
-  if (raw == null) return '';
-  // Workers AI sometimes returns structured responses (objects with tool_calls,
-  // arrays of segments, etc.). Coerce to string so downstream .trim()/JSON.parse
-  // callers don't crash on non-string payloads.
-  return typeof raw === 'object' ? JSON.stringify(raw) : String(raw);
+  });
+  return result.message ?? '';
 }
 
 
@@ -94,6 +96,7 @@ async function classifyWithWorkersAI(
 // Fallback routes — used for degraded procedure replanning and when JSON classification fails
 const DEFAULT_ROUTES: Record<string, Executor> = {
   heartbeat: 'direct',
+  request_clarification: 'direct',
   bizops_read: 'gpt_oss',
   bizops_mutate: 'gpt_oss',
   general_knowledge: 'gpt_oss',
@@ -241,6 +244,25 @@ export async function route(
     };
   }
 
+  // ─── Phase 0.25: Disambiguation firewall ──────────────────
+  const disambiguation = detectDisambiguationNeed(intent.raw);
+  if (disambiguation) {
+    intent.classified = 'request_clarification';
+    intent.complexity = 0;
+    intent.needsTools = false;
+    intent.confidence = 1;
+    intent.disambiguation = disambiguation;
+    return {
+      plan: {
+        executor: 'direct',
+        reasoning: `Disambiguation firewall halted undefined data concept "${disambiguation.concept}"`,
+        costCeiling: 'free',
+      },
+      nearMiss: `disambiguation:${disambiguation.concept}`,
+      reclassified: false,
+    };
+  }
+
   // ─── Phase 0.5: Domain pre-filter (observe only) ──────────
   const domainTag = domainPreFilter(intent.raw);
   intent.domain = domainTag.domain;

package/src/kernel/scheduled/conversation-facts.ts

@@ -5,6 +5,7 @@
 // Workers AI llama-3.1-8b (free tier) as fallback.
 
 import { type EdgeEnv } from '../dispatch.js';
+import { buildLLMProviderFactory } from '../provider-factory.js';
 import { recordMemory as recordMemoryAdapter } from '../memory-adapter.js';
 import { askGroq } from '../../groq.js';
 import { pushFactsToMindSpring, type FactEntry } from './mindspring-notebook.js';
@@ -97,13 +98,14 @@ async function askAi(
   }
   // Workers AI fallback — llama-3.1-8b is on the genuine free tier
   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: system }, { role: 'user', content: user }] },
-    );
-    if (typeof result === 'string') return result;
-    const obj = result as { response?: string; choices?: Array<{ message?: { content?: string } }> };
-    return obj.choices?.[0]?.message?.content ?? obj.response ?? '';
+    const result = await buildLLMProviderFactory(env).generateResponse({
+      model: '@cf/meta/llama-3.1-8b-instruct',
+      systemPrompt: system,
+      messages: [{ role: 'user', content: user }],
+      maxTokens: 1024,
+      temperature: 0.2,
+    });
+    return result.message ?? '';
   }
   throw new Error('[conv-facts] No LLM provider available (groqApiKey and env.ai both missing)');
 }

package/src/kernel/scheduled/digest.ts

@@ -17,9 +17,11 @@ import {
 // Operator log runs at 08:00 UTC to generate content before this fires.
 
 export async function runDailyDigest(env: EdgeEnv): Promise<void> {
-  // Time gate: fire at 09:00 UTC (4:00 AM CT)
+  // Time gate: fire at or after 09:00 UTC (4:00 AM CT).
+  // The 22h cooldown below prevents double-sends, while allowing same-day
+  // catch-up after a transient 09:00 send failure.
   const now = new Date();
-  if (now.getUTCHours() !== 9) return;
+  if (now.getUTCHours() < 9) return;
 
   // Cooldown: 22 hours since last digest
   const lastDigest = await env.db.prepare(
@@ -253,7 +255,7 @@ export async function runDailyDigest(env: EdgeEnv): Promise<void> {
   }
 
   // ── Send digest email ──
-  await sendDailyDigest(
+  await sendDailyDigestWithRetry(
     { resendApiKey: env.resendApiKey, resendApiKeyPersonal: env.resendApiKeyPersonal },
     sections,
     env.notifyEmail,
@@ -272,6 +274,31 @@ export async function runDailyDigest(env: EdgeEnv): Promise<void> {
   console.log(`[digest] Daily digest sent: ${sections.completedTasks.length} completed, ${sections.failedTasks.length} failed, ${sections.proposedTasks.length} proposed, ${sections.healthChecks.length} health checks`);
 }
 
+export async function sendDailyDigestWithRetry(
+  apiKeys: { resendApiKey: string; resendApiKeyPersonal: string },
+  sections: DigestSections,
+  notifyEmail?: string,
+  delaysMs: number[] = [1_000, 5_000],
+): Promise<void> {
+  let attempt = 0;
+  for (;;) {
+    try {
+      await sendDailyDigest(apiKeys, sections, notifyEmail);
+      return;
+    } catch (err) {
+      if (attempt >= delaysMs.length) throw err;
+      const delayMs = delaysMs[attempt];
+      attempt += 1;
+      console.warn(
+        `[digest] Daily digest send failed; retrying in ${delayMs}ms ` +
+        `(attempt ${attempt + 1}/${delaysMs.length + 1}):`,
+        err instanceof Error ? err.message : String(err),
+      );
+      await new Promise(resolve => setTimeout(resolve, delayMs));
+    }
+  }
+}
+
 // ─── Health Check Deduplication (#309) ──────────────────────
 // Each DigestHealthCheck has { severity, checks: [{name, status, detail}], timestamp }.
 // Multiple heartbeat runs can produce entries with the same check name (e.g. stale_agenda_151).

package/src/kernel/scheduled/dreaming/llm.ts

@@ -1,6 +1,7 @@
 // Shared LLM helper — Groq first (free, 70B quality), Workers AI 70B fallback
 
 import type { EdgeEnv } from '../../dispatch.js';
+import { buildLLMProviderFactory } from '../../provider-factory.js';
 import { askGroq } from '../../../groq.js';
 
 export async function askWorkersAiOrGroq(
@@ -20,11 +21,14 @@ export async function askWorkersAiOrGroq(
   }
   // Workers AI fallback — only fires if Groq is unavailable or throws
   if (env.ai) {
-    const result = await env.ai.run(
-      '@cf/meta/llama-3.3-70b-instruct-fp8-fast' as Parameters<Ai['run']>[0],
-      { messages: [{ role: 'system', content: system }, { role: 'user', content: user }] },
-    ) as { response?: string; choices?: Array<{ message?: { content?: string } }> };
-    return result.choices?.[0]?.message?.content ?? result.response ?? '';
+    const result = await buildLLMProviderFactory(env).generateResponse({
+      model: '@cf/meta/llama-3.3-70b-instruct-fp8-fast',
+      systemPrompt: system,
+      messages: [{ role: 'user', content: user }],
+      maxTokens: 2048,
+      temperature: 0.2,
+    });
+    return result.message ?? '';
   }
   throw new Error('[dreaming] No LLM provider available (groqApiKey and env.ai both missing)');
 }

package/src/kernel/scheduled/social-engage.ts

@@ -2,6 +2,7 @@
 // Runs every 6 hours. Likes replies, follows back real accounts,
 // replies to substantive comments with Workers AI.
 
+import { createLLMProviderFactory } from '@stackbilt/llm-providers';
 import { type EdgeEnv } from '../dispatch.js';
 import {
   getNotifications,
@@ -153,21 +154,24 @@ async function generateReply(
   incomingText: string,
   authorHandle: string,
 ): Promise<string | null> {
-  const result = await ai.run('@cf/meta/llama-3.1-8b-instruct' as Parameters<Ai['run']>[0], {
+  const result = await createLLMProviderFactory({
+    cloudflare: { ai },
+    fallbackRules: [],
+    enableCircuitBreaker: true,
+    enableRetries: true,
+  }).generateResponse({
+    model: '@cf/meta/llama-3.1-8b-instruct',
+    systemPrompt: `You are the operator's social media voice. Direct, builder-energy, anti-corporate. No emoji spam. No "excited to announce." Keep replies under 200 chars. Be genuine and conversational. If you can't add value, return SKIP.`,
     messages: [
-      {
-        role: 'system',
-        content: `You are the operator's social media voice. Direct, builder-energy, anti-corporate. No emoji spam. No "excited to announce." Keep replies under 200 chars. Be genuine and conversational. If you can't add value, return SKIP.`,
-      },
       {
         role: 'user',
         content: `@${authorHandle} replied to our Bluesky post: "${incomingText}"\n\nWrite a brief, genuine reply. Return ONLY the reply text, or SKIP if there's nothing meaningful to add.`,
       },
     ],
-    max_tokens: 100,
-  }) as { response?: string };
+    maxTokens: 100,
+  });
 
-  const reply = result.response?.trim();
+  const reply = result.message?.trim();
   if (!reply || reply === 'SKIP' || reply.length < 5) return null;
 
   // Safety: truncate to 300 chars (Bluesky limit)

package/src/kernel/types.ts

@@ -18,9 +18,14 @@ export interface KernelIntent {
   confidence?: number;
   domain?: string;
   domainConfidence?: number;
+  disambiguation?: {
+    concept: string;
+    question: string;
+  };
   timestamp: number;
   costCeiling: 'free' | 'cheap' | 'expensive';
   classifierSource?: 'classify-cast' | 'workers-ai' | 'groq';
+  forcedExecutor?: Executor;
 }
 
 // ─── Memory Types ────────────────────────────────────────────
@@ -40,6 +45,7 @@ export interface EpisodicEntry {
   executor?: string | null;
   complexity_tier?: string | null;
   executor_config?: string | null;
+  grounding_gap?: boolean | number;
   created_at?: string;
 }
 

package/src/operator/prompt-builder.ts

@@ -81,6 +81,7 @@ If conversation context is provided, use it to understand what the user is reall
 
 Categories:
 - heartbeat: Explicitly asking to run a health check, status check, or heartbeat — ONLY when the user directly requests a system diagnostic. NOT for pasting technical data, reporting findings, discussing system state, or asking what needs attention
+- request_clarification: The user asks for an internal data or metric concept whose definition is not strictly specified. Halt and ask which definition to use instead of guessing
 ${bizopsCategories}
 - general_knowledge: General factual questions, conceptual explanations, abstract advice with NO connection to the operator's businesses, projects, or operations
 - memory_recall: Questions about what the agent remembers, past conversations
@@ -100,6 +101,7 @@ Tiebreaker: "roundtable", "generate a roundtable", "show roundtable drafts", "pu
 Tiebreaker: When the user discusses actions to take on their business infrastructure, projects, migrations, deployments, or asks for recommendations tied to business operations → prefer bizops_mutate over general_knowledge. "general_knowledge" is for questions with NO business/operational context (e.g., "what is OAuth?", "explain quantum computing").
 Tiebreaker: When a message reports a bug, error, broken feature, or asks for help using a Stackbilt product → always support_triage, never bizops_read. "bizops_read" is for the operator querying internal business state, not for end-user support requests.
 Tiebreaker: If the user asks "what do you think?" or "what are your thoughts?" in a conversation about business decisions, projects, or operations → bizops_mutate (they want actionable advice + BizOps actions, not a generic essay).
+Disambiguation firewall: If the user asks for data or metrics and the definition is not strictly defined in context, DO NOT GUESS. Use request_clarification. Example: "what is churn?" is ambiguous; ask whether they mean churn by seat count, account count, revenue, MRR, or another defined basis.
 
 Examples:
 - "hi" → {"pattern":"greeting","complexity":0,"needs_tools":false,"confidence":0.99}
@@ -167,6 +169,7 @@ export function getTaskPatterns(): readonly string[] {
 
   const patterns: string[] = [
     'heartbeat',
+    'request_clarification',
     'general_knowledge',
     'memory_recall',
     'greeting',

package/src/routes/chat-ws.ts

@@ -0,0 +1,17 @@
+import { Hono } from 'hono';
+import type { Env } from '../types.js';
+
+export const chatWs = new Hono<{ Bindings: Env }>();
+
+chatWs.get('/chat/ws', async (c) => {
+  if (c.req.header('Upgrade')?.toLowerCase() !== 'websocket') {
+    return c.text('Expected WebSocket upgrade', 426);
+  }
+  if (!c.env.CHAT_SESSION) {
+    return c.text('CHAT_SESSION Durable Object binding is not configured', 503);
+  }
+
+  const id = c.env.CHAT_SESSION.idFromName('operator');
+  const stub = c.env.CHAT_SESSION.get(id);
+  return stub.fetch(c.req.raw);
+});

package/src/routes/pages.ts

@@ -15,6 +15,10 @@ const pages = new Hono<{ Bindings: Env }>();
 // ─── Landing ────────────────────────────────────────────────
 
 pages.get('/', (c) => {
+  return c.html(chatPage());
+});
+
+pages.get('/about', (c) => {
   return c.html(landingPage());
 });
 
@@ -44,7 +48,7 @@ pages.get('/manifest.json', (c) => {
   return c.json({
     name: 'AEGIS',
     short_name: 'AEGIS',
-    start_url: '/chat',
+    start_url: '/',
     display: 'standalone',
     background_color: '#0a0a0f',
     theme_color: '#8b8bff',

package/src/types.ts

@@ -4,6 +4,7 @@ export interface Env {
   DB: D1Database;
   AI: Ai;
   AEGIS_TOKEN: string;
+  CHAT_SESSION?: DurableObjectNamespace;
 
   // OAuth 2.1 (injected by OAuthProvider wrapper at runtime)
   OAUTH_PROVIDER: OAuthHelpers;
@@ -190,5 +191,10 @@ export interface MessageMetadata {
   confidence?: number;
   reclassified?: boolean;
   probeResult?: string;
+  grounded?: boolean;
+  sources?: string[];
+  unknowns?: string[];
+  searched?: string[];
+  unverifiedClaims?: string[];
   error?: boolean;
 }