@stackbilt/aegis-core 0.1.0

package/src/kernel/executors/groq.ts

@@ -0,0 +1,18 @@
+import { askGroq } from '../../groq.js';
+import { buildGroqSystemPrompt } from '../../operator/prompt-builder.js';
+import type { KernelIntent } from '../types.js';
+import type { EdgeEnv } from '../dispatch.js';
+
+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 };
+}

package/src/kernel/executors/index.ts

@@ -0,0 +1,87 @@
+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';
+
+// 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';
+
+// ─── MCP Registry ────────────────────────────────────────────
+
+const CF_OBSERVABILITY_MCP_URL = 'https://observability.mcp.cloudflare.com/mcp';
+
+export function buildMcpRegistry(env: EdgeEnv): McpRegistry {
+  const registry = new McpRegistry();
+
+  // Always register BizOps (Service Binding)
+  registry.register(new McpClient({
+    url: operatorConfig.integrations.bizops.fallbackUrl,
+    token: env.bizopsToken,
+    prefix: 'bizops',
+    fetcher: env.bizopsFetcher,
+    rpcPath: '/rpc',
+  }));
+
+  // Colony OS MARA — Service Binding (Governor MCP, 8 tools)
+  if (env.maraToken) {
+    registry.register(new McpClient({
+      url: 'https://your-mara-worker.your-subdomain.workers.dev/mara/mcp',
+      token: env.maraToken,
+      prefix: 'mara',
+      fetcher: env.maraFetcher,
+    }));
+  }
+
+  // CodeBeast — adversarial code review + fix drain (Service Binding, stateless RPC)
+  if (env.codebeastFetcher) {
+    registry.register(new McpClient({
+      url: 'https://your-codebeast-worker.your-subdomain.workers.dev',
+      token: '',  // Service Binding — no auth needed
+      prefix: 'codebeast',
+      fetcher: env.codebeastFetcher,
+      rpcPath: '/rpc',
+    }));
+  }
+
+  // CF Observability — direct fetch (no Service Binding, external MCP server)
+  if (env.cfAnalyticsToken && operatorConfig.integrations.cfObservability.enabled) {
+    registry.register(new McpClient({
+      url: CF_OBSERVABILITY_MCP_URL,
+      token: env.cfAnalyticsToken,
+      prefix: 'cf_obs',
+    }));
+  }
+
+  return registry;
+}
+
+// ─── Anthropic Failover ─────────────────────────────────────
+// When Anthropic API is unavailable (billing, auth, rate limit),
+// fall back to GPT-OSS-120B which has tool-calling capability.
+
+export async function executeWithAnthropicFailover(
+  executor: 'claude' | 'claude_opus',
+  intent: import('../types.js').KernelIntent,
+  env: EdgeEnv,
+): Promise<{ text: string; cost: number; meta?: unknown; actualExecutor: Executor }> {
+  try {
+    const { executeClaude, executeClaudeOpus } = await import('./claude.js');
+    const result = executor === 'claude_opus'
+      ? await executeClaudeOpus(intent, env)
+      : await executeClaude(intent, env);
+    return { ...result, actualExecutor: executor };
+  } catch (err) {
+    const msg = err instanceof Error ? err.message : String(err);
+    if (msg.includes('Anthropic API error') || msg.includes('credit balance')) {
+      console.warn(`[dispatch] ${executor} failed, failover → gpt_oss: ${msg.slice(0, 120)}`);
+      const result = await executeGptOss(intent, env);
+      return { ...result, actualExecutor: 'gpt_oss' };
+    }
+    throw err;
+  }
+}

package/src/kernel/executors/tarotscript.ts

@@ -0,0 +1,104 @@
+// TarotScript Executor — symbolic consultation via Service Binding
+//
+// Calls the TarotScript worker's POST /run endpoint. Zero inference tokens
+// (pure JS execution + optional Oracle call on the TarotScript side).
+// Service binding = same colo, no network hop.
+
+import type { KernelIntent } from '../types.js';
+import type { EdgeEnv } from '../dispatch.js';
+
+// Explicit tarot_* classifications (for internal triggers)
+const MODE_MAP: Record<string, string> = {
+  tarot_pulse: 'pulse',
+  tarot_trajectory: 'trajectory',
+  tarot_multi_angle: 'multi-angle',
+  tarot_deep: 'deep',
+  tarot_shadow: 'shadow',
+  tarot_orchestration: 'orchestration',
+  tarot_planning: 'planning',
+  support_triage: 'triage',
+};
+
+// Mode → spread type (mirrors TarotScript's spread-selector.ts)
+const SPREAD_MAP: Record<string, string> = {
+  pulse: 'single',
+  trajectory: 'three-card',
+  'multi-angle': 'star',
+  deep: 'celtic-cross',
+  shadow: 'shadow-work',
+  orchestration: 'pipeline-cast',
+  planning: 'objective-cast',
+  triage: 'triage-cast',
+};
+
+function detectMode(intent: KernelIntent): string {
+  // Check explicit tarot_* classification first
+  if (intent.classified && MODE_MAP[intent.classified]) {
+    return MODE_MAP[intent.classified];
+  }
+
+  // Complexity-based fallback for symbolic_consultation
+  const complexity = intent.complexity ?? 2;
+  if (complexity <= 1) return 'pulse';
+  if (complexity >= 3) return 'deep';
+  return 'trajectory';
+}
+
+export async function executeTarotScript(
+  intent: KernelIntent,
+  env: EdgeEnv,
+): Promise<{ text: string; cost: number; meta?: unknown }> {
+  if (!env.tarotscriptFetcher) {
+    return { text: 'TarotScript service binding not available.', cost: 0 };
+  }
+
+  const mode = detectMode(intent);
+  const spreadType = SPREAD_MAP[mode] ?? 'three-card';
+
+  const response = await env.tarotscriptFetcher.fetch('https://tarotscript-worker/run', {
+    method: 'POST',
+    headers: { 'Content-Type': 'application/json' },
+    body: JSON.stringify({
+      spreadType,
+      querent: {
+        id: intent.source.threadId,
+        intention: intent.raw,
+        state: {
+          classification: intent.classified ?? 'symbolic_consultation',
+          complexity: String(intent.complexity ?? 2),
+          confidence: String(intent.confidence ?? 0.8),
+        },
+      },
+      inscribe: true,
+    }),
+  });
+
+  if (!response.ok) {
+    const err = await response.text().catch(() => `HTTP ${response.status}`);
+    return { text: `TarotScript execution failed: ${err}`, cost: 0 };
+  }
+
+  const result = await response.json() as {
+    output: string[];
+    facts: Record<string, unknown>;
+    analysis?: { dominantElement?: string; shadowDensity?: { ratio: number } };
+    receipt: { hash: string; seed: number };
+    spread?: { name: string };
+  };
+
+  const text = result.output.join('\n');
+
+  return {
+    text,
+    cost: 0.001, // Nominal bookkeeping — no inference tokens, pure JS + optional Oracle
+    meta: {
+      source: 'tarotScript',
+      spreadType: result.spread?.name ?? spreadType,
+      mode,
+      receipt: result.receipt,
+      dominantElement: result.analysis?.dominantElement,
+      shadowDensity: result.analysis?.shadowDensity?.ratio,
+      facts: result.facts,
+    },
+  };
+}

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

@@ -0,0 +1,54 @@
+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,
+  );
+}

package/src/kernel/insight-cache.ts

@@ -0,0 +1,76 @@
+// Cross-Repo Insight Cache (CRIX #106)
+// In-memory TTL cache for validated insights from the Memory Worker.
+// Keyword-scored matching injects relevant cross-repo intelligence into dispatch context.
+
+import type { EdgeEnv } from './dispatch.js';
+
+interface InsightEntry {
+  fact: string;
+  type: string;
+  origin: string;
+}
+
+let cache: { entries: InsightEntry[]; fetchedAt: number } | null = null;
+const CACHE_TTL_MS = 60 * 60 * 1000; // 1 hour
+const MAX_PER_DISPATCH = 3;
+
+export async function fetchRelevantInsights(
+  env: EdgeEnv,
+  classification: string,
+  rawQuery: string,
+): Promise<string | null> {
+  const now = Date.now();
+  if (!cache || (now - cache.fetchedAt) > CACHE_TTL_MS) {
+    try {
+      const fragments = await env.memoryBinding!.recall('aegis', {
+        topic: 'cross_repo_insights',
+        limit: 20,
+        min_confidence: 0.75,
+      });
+
+      cache = {
+        entries: fragments.map(f => {
+          // Parse "[type:pattern] (from repo-name) actual fact text"
+          const prefixMatch = f.content.match(/^\[([^\]]+)\]\s*\(from\s+([^)]+)\)\s*(.+)$/s);
+          return {
+            fact: prefixMatch ? prefixMatch[3] : f.content,
+            type: prefixMatch ? prefixMatch[1] : 'pattern',
+            origin: prefixMatch ? prefixMatch[2] : 'unknown',
+          };
+        }),
+        fetchedAt: now,
+      };
+    } catch {
+      return null;
+    }
+  }
+
+  if (!cache || cache.entries.length === 0) return null;
+
+  // Keyword matching
+  const queryWords = new Set(
+    rawQuery.toLowerCase()
+      .replace(/[^a-z0-9\s]/g, ' ')
+      .split(/\s+/)
+      .filter(w => w.length > 3)
+  );
+
+  const scored = cache.entries.map(entry => {
+    const factWords = entry.fact.toLowerCase().split(/\s+/);
+    const matches = factWords.filter(w => queryWords.has(w)).length;
+    return { ...entry, relevance: matches };
+  }).filter(e => e.relevance > 0);
+
+  scored.sort((a, b) => b.relevance - a.relevance);
+  const top = scored.slice(0, MAX_PER_DISPATCH);
+
+  if (top.length === 0) return null;
+
+  const lines = top.map(i => `- [${i.type}] (from ${i.origin}) ${i.fact}`);
+  return `[Cross-Repo Intelligence — validated patterns]\n${lines.join('\n')}`;
+}
+
+/** Reset cache — useful for testing */
+export function resetInsightCache(): void {
+  cache = null;
+}

package/src/kernel/memory/agenda.ts

@@ -0,0 +1,200 @@
+// ─── Agent Agenda ────────────────────────────────────────────
+//
+// Proposed Actions convention:
+// An agenda item is a [PROPOSED ACTION] when AEGIS has identified a specific,
+// executable action it can perform and is requesting approval before proceeding.
+//
+// Format:  item  = "[PROPOSED ACTION] <description>"
+//          context = full reasoning — what it would do, why, expected outcome
+//
+// AEGIS should use this prefix when:
+//   - It has identified a specific step it can execute in-session (not just a flag)
+//   - The action has real consequences (filing, creating records, sending emails)
+//   - It has enough context to act without further clarification
+//
+// Proposed actions surface before regular agenda items at session start,
+// with an explicit numbered approval prompt. The operator responds "approve N",
+// "reject N", or "defer N". Approved = AEGIS executes + resolves. Rejected =
+// dismissed. Deferred = stays active for next session.
+
+import type { AgendaPriority, AgendaStatus } from '../../schema-enums.js';
+
+export interface AgendaItem {
+  id: number;
+  item: string;
+  context: string | null;
+  priority: AgendaPriority;
+  status: AgendaStatus;
+  created_at: string;
+  resolved_at: string | null;
+  business_unit: string;
+}
+
+export const DEFAULT_BUSINESS_UNIT = 'stackbilt';
+
+// ─── Heartbeat History (#6) ──────────────────────────────────
+
+export interface HeartbeatResult {
+  id: number;
+  actionable: boolean;
+  severity: string;
+  summary: string;
+  checks_json: string;
+  created_at: string;
+}
+
+export async function getRecentHeartbeats(db: D1Database, limit = 5): Promise<HeartbeatResult[]> {
+  const result = await db.prepare(
+    'SELECT * FROM heartbeat_results ORDER BY created_at DESC LIMIT ?'
+  ).bind(limit).all();
+  return result.results as unknown as HeartbeatResult[];
+}
+
+export async function getActiveAgendaItems(
+  db: D1Database,
+  businessUnit?: string,
+): Promise<AgendaItem[]> {
+  const sql = businessUnit
+    ? "SELECT * FROM agent_agenda WHERE status = 'active' AND business_unit = ? ORDER BY CASE priority WHEN 'high' THEN 0 WHEN 'medium' THEN 1 ELSE 2 END, created_at ASC"
+    : "SELECT * FROM agent_agenda WHERE status = 'active' ORDER BY CASE priority WHEN 'high' THEN 0 WHEN 'medium' THEN 1 ELSE 2 END, created_at ASC";
+  const stmt = businessUnit
+    ? db.prepare(sql).bind(businessUnit)
+    : db.prepare(sql);
+  const result = await stmt.all();
+  return result.results as unknown as AgendaItem[];
+}
+
+const PRIORITY_RANK: Record<string, number> = { low: 0, medium: 1, high: 2 };
+
+function extractAgendaKeyPhrase(text: string): string {
+  return text
+    .replace(/^\[PROPOSED ACTION\]\s*/i, '')
+    .toLowerCase()
+    .replace(/[^a-z0-9 ]/g, ' ')
+    .replace(/\s+/g, ' ')
+    .trim();
+}
+
+export async function addAgendaItem(
+  db: D1Database,
+  item: string,
+  context: string | undefined,
+  priority: AgendaPriority,
+  businessUnit: string = DEFAULT_BUSINESS_UNIT,
+): Promise<number> {
+  // Dedup: check for existing active OR recently resolved items with similar text (#72)
+  // Include items resolved within 7 days to prevent zombie re-creation loops
+  // where a compliance item is re-flagged before the upstream source is updated.
+  const keyPhrase = extractAgendaKeyPhrase(item);
+  const words = keyPhrase.split(' ').filter(w => w.length > 3);
+  if (words.length > 0) {
+    // Dedup scoped to the same business_unit — different BUs can have
+    // legitimately overlapping item text without being duplicates.
+    const candidates = await db.prepare(
+      "SELECT id, item, priority, status FROM agent_agenda WHERE business_unit = ? AND (status = 'active' OR (status IN ('done', 'dismissed') AND resolved_at >= datetime('now', '-7 days')))"
+    ).bind(businessUnit).all<{ id: number; item: string; priority: string; status: string }>();
+
+    for (const existing of candidates.results) {
+      const existingKey = extractAgendaKeyPhrase(existing.item);
+      // Match if >50% of significant words overlap
+      const matches = words.filter(w => existingKey.includes(w)).length;
+      if (matches / words.length > 0.5) {
+        if (existing.status !== 'active') {
+          // Recently resolved — suppress re-creation entirely
+          return existing.id;
+        }
+        // Upgrade priority if new is higher
+        if ((PRIORITY_RANK[priority] ?? 0) > (PRIORITY_RANK[existing.priority] ?? 0)) {
+          await db.prepare(
+            'UPDATE agent_agenda SET priority = ? WHERE id = ?'
+          ).bind(priority, existing.id).run();
+        }
+        return existing.id;
+      }
+    }
+  }
+
+  const result = await db.prepare(
+    'INSERT INTO agent_agenda (item, context, priority, business_unit) VALUES (?, ?, ?, ?)'
+  ).bind(item, context ?? null, priority, businessUnit).run();
+  return result.meta.last_row_id as number;
+}
+
+export async function resolveAgendaItem(
+  db: D1Database,
+  id: number,
+  status: 'done' | 'dismissed',
+): Promise<void> {
+  await db.prepare(
+    "UPDATE agent_agenda SET status = ?, resolved_at = datetime('now') WHERE id = ?"
+  ).bind(status, id).run();
+}
+
+export const PROPOSED_ACTION_PREFIX = '[PROPOSED ACTION]';
+export const PROPOSED_TASK_PREFIX = '[PROPOSED TASK]';
+
+export async function createProposedTaskAgendaItem(
+  db: D1Database,
+  taskId: string,
+  title: string,
+  repo: string,
+  category: string,
+  rationale: string,
+): Promise<number> {
+  const summary = `${PROPOSED_TASK_PREFIX} ${title} (${repo}) — ${category}`;
+  const context = JSON.stringify({ task_id: taskId, repo, category, rationale });
+  return addAgendaItem(db, summary, context, 'medium');
+}
+
+export async function getAgendaContext(db: D1Database): Promise<string> {
+  const items = await getActiveAgendaItems(db);
+  if (items.length === 0) return '';
+
+  const proposed = items.filter(i => i.item.startsWith(PROPOSED_ACTION_PREFIX));
+  const regular  = items.filter(i => !i.item.startsWith(PROPOSED_ACTION_PREFIX));
+
+  let ctx = '';
+
+  if (proposed.length > 0) {
+    ctx += `\n## Pending Proposed Actions\n`;
+    ctx += `I have ${proposed.length} proposed action${proposed.length !== 1 ? 's' : ''} awaiting approval:\n\n`;
+    proposed.forEach((item, idx) => {
+      const description = item.item.slice(PROPOSED_ACTION_PREFIX.length).trim();
+      ctx += `${idx + 1}. **[PROPOSED ACTION #${item.id}]** ${description}\n`;
+      if (item.context) ctx += `   Reasoning: ${item.context}\n`;
+    });
+    ctx += `\nRespond "approve N", "reject N", or "defer N" for each — or "approve all".\n`;
+  }
+
+  if (regular.length > 0) {
+    const lines = regular.map(i =>
+      `- [${i.priority.toUpperCase()} #${i.id}] ${i.item}${i.context ? ` — ${i.context}` : ''}`
+    );
+    ctx += `\n## Active Agenda\n${lines.join('\n')}\n`;
+  }
+
+  return ctx;
+}
+
+// ─── Heartbeat Context ───────────────────────────────────────
+
+function formatAge(createdAt: string): string {
+  const ts = createdAt.endsWith('Z') ? createdAt : createdAt + 'Z';
+  const diffMs = Date.now() - new Date(ts).getTime();
+  const hours = Math.floor(diffMs / 3_600_000);
+  if (hours < 1) return 'just now';
+  if (hours < 24) return `${hours}h ago`;
+  return `${Math.floor(hours / 24)}d ago`;
+}
+
+export async function getRecentHeartbeatContext(db: D1Database): Promise<string> {
+  const result = await db.prepare(
+    'SELECT severity, summary, actionable, created_at FROM heartbeat_results ORDER BY created_at DESC LIMIT 2'
+  ).all();
+  const rows = result.results as unknown as { severity: string; summary: string; actionable: number; created_at: string }[];
+  if (rows.length === 0) return '';
+  const lines = rows.map(r =>
+    `- [${r.severity.toUpperCase()}${r.actionable ? ' ⚡' : ''}] ${r.summary} (${formatAge(r.created_at)})`
+  );
+  return `\n## Recent Heartbeat Status\n${lines.join('\n')}\n`;
+}