@stackbilt/aegis-core 0.1.0

package/src/kernel/dynamic-tools.ts

@@ -0,0 +1,322 @@
+// ─── Dynamic Tools — runtime tool creation + execution ──────
+// Tools are prompt templates stored in D1, executed via LLM.
+// No eval(). No code execution. Just parameterized prompts.
+
+import { type EdgeEnv } from './dispatch.js';
+import type { ToolExecutor, ToolStatus } from '../schema-enums.js';
+
+// ─── Types ──────────────────────────────────────────────────
+
+export interface DynamicTool {
+  id: string;
+  name: string;
+  description: string;
+  input_schema: string;
+  prompt_template: string;
+  executor: string;
+  created_by: string;
+  status: ToolStatus;
+  ttl_days: number | null;
+  use_count: number;
+  last_used_at: string | null;
+  avg_latency_ms: number;
+  avg_cost: number;
+  created_at: string;
+  updated_at: string;
+  expires_at: string | null;
+}
+
+export interface CreateToolOpts {
+  name: string;
+  description: string;
+  input_schema?: string;
+  prompt_template: string;
+  executor?: ToolExecutor;
+  created_by?: string;
+  ttl_days?: number;
+  status?: 'active' | 'draft';
+}
+
+export interface ToolInvocationResult {
+  text: string;
+  cost: number;
+  latency_ms: number;
+  executor: string;
+}
+
+// ─── Reserved names (cannot conflict with built-in tools) ────
+
+const RESERVED_PREFIXES = ['aegis_', 'mcp_', 'bizops_'];
+
+function isReservedName(name: string): boolean {
+  return RESERVED_PREFIXES.some(p => name.startsWith(p));
+}
+
+// ─── CRUD ───────────────────────────────────────────────────
+
+export async function createDynamicTool(db: D1Database, opts: CreateToolOpts): Promise<string> {
+  if (isReservedName(opts.name)) {
+    throw new Error(`Tool name "${opts.name}" conflicts with reserved prefix`);
+  }
+  if (!/^[a-z][a-z0-9_]{1,48}$/.test(opts.name)) {
+    throw new Error('Tool name must be snake_case, 2-49 chars, start with letter');
+  }
+
+  const id = crypto.randomUUID();
+  const executor = opts.executor ?? 'gpt_oss';
+  const status = opts.status ?? 'active';
+  const expiresAt = opts.ttl_days
+    ? new Date(Date.now() + opts.ttl_days * 24 * 60 * 60 * 1000).toISOString()
+    : null;
+
+  await db.prepare(`
+    INSERT INTO dynamic_tools (id, name, description, input_schema, prompt_template, executor, created_by, status, ttl_days, expires_at)
+    VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?)
+  `).bind(
+    id,
+    opts.name,
+    opts.description,
+    opts.input_schema ?? '{}',
+    opts.prompt_template,
+    executor,
+    opts.created_by ?? 'operator',
+    status,
+    opts.ttl_days ?? null,
+    expiresAt,
+  ).run();
+
+  return id;
+}
+
+export async function getDynamicTool(db: D1Database, nameOrId: string): Promise<DynamicTool | null> {
+  return db.prepare(
+    'SELECT * FROM dynamic_tools WHERE (name = ? OR id = ?) AND status != ?'
+  ).bind(nameOrId, nameOrId, 'retired').first<DynamicTool>();
+}
+
+export async function listDynamicTools(
+  db: D1Database,
+  opts?: { status?: string; limit?: number },
+): Promise<DynamicTool[]> {
+  const limit = Math.min(opts?.limit ?? 50, 100);
+  if (opts?.status) {
+    const result = await db.prepare(
+      'SELECT * FROM dynamic_tools WHERE status = ? ORDER BY use_count DESC, created_at DESC LIMIT ?'
+    ).bind(opts.status, limit).all<DynamicTool>();
+    return result.results;
+  }
+  const result = await db.prepare(
+    "SELECT * FROM dynamic_tools WHERE status IN ('active', 'promoted') ORDER BY use_count DESC, created_at DESC LIMIT ?"
+  ).bind(limit).all<DynamicTool>();
+  return result.results;
+}
+
+export async function updateDynamicTool(
+  db: D1Database,
+  id: string,
+  updates: Partial<Pick<DynamicTool, 'description' | 'prompt_template' | 'executor' | 'input_schema' | 'status'>>,
+): Promise<void> {
+  const sets: string[] = [];
+  const binds: unknown[] = [];
+
+  for (const [key, value] of Object.entries(updates)) {
+    if (value !== undefined) {
+      sets.push(`${key} = ?`);
+      binds.push(value);
+    }
+  }
+  if (sets.length === 0) return;
+
+  sets.push("updated_at = datetime('now')");
+  binds.push(id);
+
+  await db.prepare(
+    `UPDATE dynamic_tools SET ${sets.join(', ')} WHERE id = ?`
+  ).bind(...binds).run();
+}
+
+export async function retireDynamicTool(db: D1Database, id: string): Promise<void> {
+  await db.prepare(
+    "UPDATE dynamic_tools SET status = 'retired', updated_at = datetime('now') WHERE id = ?"
+  ).bind(id).run();
+}
+
+// ─── Prompt Rendering ───────────────────────────────────────
+
+export function renderPrompt(template: string, inputs: Record<string, unknown>): string {
+  return template.replace(/\{\{(\w+)\}\}/g, (match, key) => {
+    const value = inputs[key];
+    if (value === undefined) return match; // Leave unresolved placeholders as-is
+    return String(value);
+  });
+}
+
+// ─── Execution ──────────────────────────────────────────────
+
+export async function executeDynamicTool(
+  tool: DynamicTool,
+  inputs: Record<string, unknown>,
+  env: EdgeEnv,
+): 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 latencyMs = Date.now() - start;
+
+  // Update usage stats (running average for latency/cost)
+  const newCount = tool.use_count + 1;
+  const newAvgLatency = ((tool.avg_latency_ms * tool.use_count) + latencyMs) / newCount;
+  const newAvgCost = ((tool.avg_cost * tool.use_count) + cost) / newCount;
+
+  await env.db.prepare(`
+    UPDATE dynamic_tools
+    SET use_count = ?, last_used_at = datetime('now'), avg_latency_ms = ?, avg_cost = ?, updated_at = datetime('now')
+    WHERE id = ?
+  `).bind(newCount, newAvgLatency, newAvgCost, tool.id).run();
+
+  return { text, cost, latency_ms: latencyMs, executor: tool.executor };
+}
+
+// ─── Lifecycle (GC + Promotion) ─────────────────────────────
+
+const MAX_ACTIVE_TOOLS = 50;
+const PROMOTION_THRESHOLD = 20; // use_count to auto-promote
+const UNUSED_EXPIRY_DAYS = 30;  // retire if never used after 30d
+
+export async function garbageCollectTools(db: D1Database): Promise<{ expired: number; unused: number }> {
+  // 1. Expire tools past TTL
+  const expiredResult = await db.prepare(`
+    UPDATE dynamic_tools SET status = 'retired', updated_at = datetime('now')
+    WHERE status = 'active' AND expires_at IS NOT NULL AND expires_at < datetime('now')
+  `).run();
+
+  // 2. Retire tools never used after 30 days
+  const unusedResult = await db.prepare(`
+    UPDATE dynamic_tools SET status = 'retired', updated_at = datetime('now')
+    WHERE status = 'active' AND use_count = 0 AND created_by != 'operator'
+      AND created_at < datetime('now', '-${UNUSED_EXPIRY_DAYS} days')
+  `).run();
+
+  // 3. Enforce ceiling — retire lowest-use active tools over cap
+  const activeCount = await db.prepare(
+    "SELECT COUNT(*) as cnt FROM dynamic_tools WHERE status IN ('active', 'promoted')"
+  ).first<{ cnt: number }>();
+
+  let overflowRetired = 0;
+  if (activeCount && activeCount.cnt > MAX_ACTIVE_TOOLS) {
+    const excess = activeCount.cnt - MAX_ACTIVE_TOOLS;
+    await db.prepare(`
+      UPDATE dynamic_tools SET status = 'retired', updated_at = datetime('now')
+      WHERE id IN (
+        SELECT id FROM dynamic_tools
+        WHERE status = 'active' AND created_by != 'operator'
+        ORDER BY use_count ASC, created_at ASC
+        LIMIT ?
+      )
+    `).bind(excess).run();
+    overflowRetired = excess;
+  }
+
+  return {
+    expired: expiredResult.meta.changes,
+    unused: unusedResult.meta.changes + overflowRetired,
+  };
+}
+
+export async function promoteHighUsageTools(db: D1Database): Promise<number> {
+  const result = await db.prepare(`
+    UPDATE dynamic_tools SET status = 'promoted', updated_at = datetime('now')
+    WHERE status = 'active' AND use_count >= ?
+  `).bind(PROMOTION_THRESHOLD).run();
+
+  return result.meta.changes;
+}
+
+// ─── Tool Definition Formatters (for Claude tool loop) ──────
+
+export function toChatToolDef(tool: DynamicTool): { name: string; description: string; input_schema: Record<string, unknown> } {
+  let schema: Record<string, unknown>;
+  try {
+    schema = JSON.parse(tool.input_schema);
+  } catch {
+    schema = { type: 'object', properties: {} };
+  }
+  // Ensure it has a type
+  if (!schema.type) schema.type = 'object';
+
+  return {
+    name: `dt_${tool.name}`,
+    description: `[Dynamic Tool] ${tool.description}`,
+    input_schema: schema,
+  };
+}
+
+// ─── Cache ──────────────────────────────────────────────────
+
+let toolCache: { tools: DynamicTool[]; expiresAt: number } | null = null;
+const CACHE_TTL_MS = 5 * 60 * 1000; // 5 minutes
+
+export async function getCachedActiveTools(db: D1Database): Promise<DynamicTool[]> {
+  if (toolCache && Date.now() < toolCache.expiresAt) {
+    return toolCache.tools;
+  }
+  const tools = await listDynamicTools(db);
+  toolCache = { tools, expiresAt: Date.now() + CACHE_TTL_MS };
+  return tools;
+}
+
+export function invalidateToolCache(): void {
+  toolCache = null;
+}

package/src/kernel/executor-port.ts

@@ -0,0 +1,45 @@
+import { executeClaudeStream } from './executors/index.js';
+import { createIntent } from './dispatch.js';
+import type { EdgeEnv } from './dispatch.js';
+import type { AegisExecutorPort, AegisTurnInput, AegisTurnEvent } from './port.js';
+
+// Bridges the callback-style executeClaudeStream to the AsyncIterable<AegisTurnEvent>
+// contract required by AegisExecutorPort. The kernel's execution loop is untouched.
+export class KernelExecutorPort implements AegisExecutorPort {
+  constructor(private readonly env: EdgeEnv) {}
+
+  async *dispatch(input: AegisTurnInput): AsyncIterable<AegisTurnEvent> {
+    const intent = createIntent(input.sessionId, input.text);
+
+    // Push-queue bridge: callback fires synchronously from within the stream loop;
+    // the generator drains it between awaits so no events are dropped.
+    const queue: Array<AegisTurnEvent | null> = [];
+    let notify: (() => void) | null = null;
+
+    const push = (event: AegisTurnEvent | null) => {
+      queue.push(event);
+      const n = notify;
+      notify = null;
+      n?.();
+    };
+
+    executeClaudeStream(intent, this.env, (text) => push({ type: 'text.delta', text }))
+      .then(() => push(null))
+      .catch((err) => {
+        push({ type: 'warning', message: err instanceof Error ? err.message : String(err) });
+        push(null);
+      });
+
+    while (true) {
+      if (queue.length === 0) {
+        await new Promise<void>((r) => { notify = r; });
+      }
+      const item = queue.shift()!;
+      if (item === null) {
+        yield { type: 'done' };
+        return;
+      }
+      yield item;
+    }
+  }
+}

package/src/kernel/executors/claude.ts

@@ -0,0 +1,73 @@
+import { executeClaudeChat, executeClaudeChatStream } from '../../claude.js';
+import { McpClient, McpRegistry } from '../../mcp-client.js';
+import { operatorConfig } from '../../operator/index.js';
+import type { KernelIntent } from '../types.js';
+import type { EdgeEnv } from '../dispatch.js';
+import { buildMcpRegistry } from './index.js';
+
+function buildClaudeConfig(env: EdgeEnv, intent: KernelIntent, model: string, registry: McpRegistry) {
+  const mcpClient = new McpClient({
+    url: operatorConfig.integrations.bizops.fallbackUrl,
+    token: env.bizopsToken,
+    prefix: 'bizops',
+    fetcher: env.bizopsFetcher,
+    rpcPath: '/rpc',
+  });
+
+  return {
+    apiKey: env.anthropicApiKey,
+    model,
+    baseUrl: env.anthropicBaseUrl,
+    mcpClient,
+    mcpRegistry: registry,
+    db: env.db,
+    channel: 'web' as const,
+    conversationId: intent.source.threadId,
+    githubToken: env.githubToken,
+    githubRepo: env.githubRepo,
+    braveApiKey: env.braveApiKey,
+    roundtableDb: env.roundtableDb,
+    memoryBinding: env.memoryBinding,
+  };
+}
+
+export async function executeClaude(
+  intent: KernelIntent,
+  env: EdgeEnv,
+): Promise<{ text: string; cost: number }> {
+  const registry = buildMcpRegistry(env);
+  return executeClaudeChat(buildClaudeConfig(env, intent, env.claudeModel, registry), intent.raw);
+}
+
+export async function executeClaudeOpus(
+  intent: KernelIntent,
+  env: EdgeEnv,
+): Promise<{ text: string; cost: number }> {
+  const registry = buildMcpRegistry(env);
+  return executeClaudeChat(buildClaudeConfig(env, intent, env.opusModel, registry), intent.raw);
+}
+
+export async function executeClaudeStream(
+  intent: KernelIntent,
+  env: EdgeEnv,
+  onDelta: (text: string) => void,
+): Promise<{ text: string; cost: number }> {
+  const registry = buildMcpRegistry(env);
+  const mcpClient = new McpClient({
+    url: operatorConfig.integrations.bizops.fallbackUrl,
+    token: env.bizopsToken,
+    prefix: 'bizops',
+    fetcher: env.bizopsFetcher,
+    rpcPath: '/rpc',
+  });
+
+  return executeClaudeChatStream(
+    {
+      ...buildClaudeConfig(env, intent, intent.classified === 'claude_opus' ? env.opusModel : env.claudeModel, registry),
+      mcpClient,
+      resendApiKeys: { resendApiKey: env.resendApiKey, resendApiKeyPersonal: env.resendApiKeyPersonal },
+    },
+    intent.raw,
+    onDelta,
+  );
+}

package/src/kernel/executors/direct.ts

@@ -0,0 +1,237 @@
+import { askGroq } from '../../groq.js';
+import { drainMcpToolHealth } from '../../claude.js';
+import { McpClient } from '../../mcp-client.js';
+import { operatorConfig } from '../../operator/index.js';
+import type { KernelIntent } from '../types.js';
+import type { EdgeEnv } from '../dispatch.js';
+
+// ─── Heartbeat Triage ────────────────────────────────────────
+
+const CF_OBSERVABILITY_MCP_URL = 'https://observability.mcp.cloudflare.com/mcp';
+
+const HEARTBEAT_TRIAGE_SYSTEM = `You are AEGIS, a business operations monitoring agent. Evaluate the dashboard data and return a JSON triage verdict.
+
+Evaluate these checks:
+1. overdue_compliance — Any overdue compliance items. alert if any exist: high (1-2), critical (3+).
+2. upcoming_deadlines — Compliance items due within 7 days. warn if any: medium severity.
+3. runway_status — Monthly net burn. alert if net < -$500 (high), warn if net < $0 (medium).
+4. document_gaps — Missing/needed documents. ONLY warn if the dashboard explicitly lists a document as HIGH or CRITICAL priority AND status is "missing" or "needed". Advisory, low-priority, informational, or "nice-to-have" gaps MUST be reported as "ok". When in doubt, report "ok". The compliance goal loop handles deadline tracking separately — the heartbeat should NOT duplicate that work.
+5. separation_scores — Always report as "ok". Corporate veil separation scores 30-70 are normal during solo-founder bootstrapping. Do NOT warn or alert on separation scores.
+6. upcoming_deadlines — Compliance items due within 7 days. ONLY warn if the dashboard data shows a specific item with a specific deadline within 7 days. If the dashboard shows no upcoming deadlines or says "none", report as "ok" — do NOT warn about the absence of deadlines.
+7. worker_errors — CF Worker error rate. alert if > 5% (high), warn if > 1% (medium).
+8. worker_latency — Worker p99 latency. alert if > 10s (high), warn if > 3s (medium).
+9. worker_volume — Unusual request volume drop. warn if > 50% below typical (medium).
+
+If Cloudflare metrics are not available, skip worker_* checks.
+
+Return ONLY valid JSON matching this schema (no markdown, no explanation):
+{
+  "actionable": boolean,
+  "severity": "none" | "low" | "medium" | "high" | "critical",
+  "summary": "one-line human summary",
+  "checks": [
+    { "name": "check_name", "status": "ok" | "warn" | "alert", "detail": "brief detail" }
+  ]
+}
+
+Overall severity = highest individual check severity. actionable = true if any check is warn or alert.
+If dashboard is empty or has no issues, return actionable: false, severity: "none".`;
+
+function parseHeartbeatVerdict(raw: string): { actionable: boolean; severity: string; summary: string; checks: unknown[] } {
+  if (!raw) return { actionable: false, severity: 'info', summary: 'No response', checks: [] };
+  const cleaned = raw.replace(/```json\s*/g, '').replace(/```\s*/g, '').trim();
+  try {
+    const parsed = JSON.parse(cleaned);
+    return {
+      actionable: Boolean(parsed.actionable),
+      severity: parsed.severity ?? 'none',
+      summary: parsed.summary ?? 'No summary',
+      checks: Array.isArray(parsed.checks) ? parsed.checks : [],
+    };
+  } catch {
+    return {
+      actionable: false,
+      severity: 'none',
+      summary: `Parse error: ${cleaned.slice(0, 100)}`,
+      checks: [{ name: 'parse_error', status: 'warn', detail: 'Could not parse Groq response' }],
+    };
+  }
+}
+
+async function fetchCfObservability(env: EdgeEnv): Promise<string | null> {
+  if (!env.cfAnalyticsToken || !operatorConfig.integrations.cfObservability.enabled) return null;
+
+  try {
+    const cfClient = new McpClient({
+      url: CF_OBSERVABILITY_MCP_URL,
+      token: env.cfAnalyticsToken,
+      prefix: 'cf_obs',
+    });
+
+    const result = await Promise.race([
+      cfClient.callTool('query_worker_observability', {
+        query: 'Show error rates, p99 latency, and request volume for all workers in the last hour',
+      }),
+      new Promise<never>((_, rej) =>
+        setTimeout(() => rej(new Error('CF observability timeout')), 10_000),
+      ),
+    ]);
+
+    return typeof result === 'string' ? result : JSON.stringify(result);
+  } catch (err) {
+    console.warn(`[heartbeat] CF observability fetch failed: ${err instanceof Error ? err.message : String(err)}`);
+    return null;
+  }
+}
+
+// ─── Executor ────────────────────────────────────────────────
+
+export async function executeDirect(
+  intent: KernelIntent,
+  env: EdgeEnv,
+): Promise<{ text: string; cost: number; meta?: unknown }> {
+  if (intent.classified === 'heartbeat') {
+    // Edge heartbeat: call BizOps dashboard + CF infrastructure in parallel, triage with structured JSON
+    const mcpClient = new McpClient({
+      url: operatorConfig.integrations.bizops.fallbackUrl,
+      token: env.bizopsToken,
+      prefix: 'bizops',
+      fetcher: env.bizopsFetcher,
+      rpcPath: '/rpc',
+    });
+
+    try {
+      const [dashboard, cfMetrics] = await Promise.all([
+        mcpClient.callTool('dashboard_summary', {}),
+        fetchCfObservability(env),
+      ]);
+
+      // Track whether the dashboard call itself was degraded
+      const dashboardDegraded = dashboard === '(no output)';
+
+      let userPrompt = `Evaluate this BizOps dashboard snapshot:\n\n${typeof dashboard === 'string' ? dashboard : JSON.stringify(dashboard, null, 2)}`;
+      if (cfMetrics) {
+        userPrompt += `\n\n--- Cloudflare Infrastructure Metrics ---\n${cfMetrics}`;
+      }
+      const groqResponse = await askGroq(
+        env.groqApiKey,
+        env.groqModel,
+        HEARTBEAT_TRIAGE_SYSTEM,
+        userPrompt,
+        env.groqBaseUrl,
+      );
+      const verdict = parseHeartbeatVerdict(groqResponse);
+
+      // ─── Suppress bootstrapping noise ───
+      // During solo-founder bootstrapping, certain checks produce false positives:
+      // - separation_scores: shared operator across orgs is structural, not a risk
+      // - document_gaps at warn level: advisory gaps aren't actionable
+      // Only let through genuine alerts (score <30 or critical docs missing).
+      // Groq may use variant names (document_gap, missing_documents, doc_gaps) — match loosely.
+      verdict.checks = (verdict.checks as Array<{ name: string; status: string; detail: string }>).filter(c => {
+        // Separation scores: suppress entirely (prompt says skip, but LLM may still emit)
+        if (c.name === 'separation_scores' || c.name.includes('separation')) return false;
+        // Document gaps: only surface alerts (critical missing docs), suppress warns (advisory gaps)
+        const isDocGapCheck = c.name === 'document_gaps' || c.name.includes('document') || c.name.includes('doc_gap') || c.name.includes('missing_doc');
+        if (isDocGapCheck && c.status === 'warn') return false;
+        // Upcoming deadlines at warn with "no items" / "none" in detail — Groq sometimes emits
+        // a warn-level upcoming_deadlines check even when there's nothing due
+        if (c.name === 'upcoming_deadlines' && c.status === 'warn' && /\b(no |none|0 item|no upcoming)\b/i.test(c.detail)) return false;
+        return true;
+      });
+      // Recalculate actionable/severity after suppression
+      const activeChecks = (verdict.checks as Array<{ name: string; status: string }>).filter(c => c.status !== 'ok');
+      if (activeChecks.length === 0) {
+        verdict.actionable = false;
+        verdict.severity = 'none';
+      }
+
+      // ─── Docs sync staleness check (direct DB, no LLM) ───
+      const DOCS_STALE_THRESHOLD_MS = 48 * 60 * 60 * 1000; // 48 hours
+      try {
+        const lastSync = await env.db.prepare(
+          "SELECT received_at FROM web_events WHERE event_id = 'last_docs_sync_at'"
+        ).first<{ received_at: string }>();
+        if (!lastSync) {
+          // No watermark yet — seed it now so future checks have a baseline.
+          // The self-improvement scheduled job will update it on actual sync.
+          await env.db.prepare(
+            "INSERT OR REPLACE INTO web_events (event_id, received_at) VALUES ('last_docs_sync_at', datetime('now'))"
+          ).run();
+          verdict.checks.push({ name: 'docs_sync_staleness', status: 'ok', detail: 'Watermark initialized — tracking starts now' });
+        } else {
+          const lastSyncMs = new Date(lastSync.received_at + 'Z').getTime();
+          const syncAge = Date.now() - lastSyncMs;
+          if (syncAge > DOCS_STALE_THRESHOLD_MS) {
+            const ageDays = Math.round(syncAge / 86_400_000);
+            const status = ageDays > 7 ? 'alert' : 'warn';
+            verdict.checks.push({
+              name: 'docs_sync_staleness',
+              status,
+              detail: `Last docs sync was ${ageDays}d ago — drift likely accumulating`,
+            });
+            verdict.actionable = true;
+            if (verdict.severity === 'none') verdict.severity = 'medium';
+          } else {
+            verdict.checks.push({ name: 'docs_sync_staleness', status: 'ok', detail: `Synced ${Math.round(syncAge / 3_600_000)}h ago` });
+          }
+        }
+      } catch (err) {
+        console.warn(`[heartbeat] docs sync staleness check failed: ${err instanceof Error ? err.message : String(err)}`);
+      }
+
+      // Append MCP tool health checks from the inter-heartbeat window
+      const mcpHealth = drainMcpToolHealth();
+      if (dashboardDegraded) {
+        verdict.checks.push({
+          name: 'mcp_tool_health',
+          status: 'alert',
+          detail: 'BizOps dashboard_summary returned (no output) — heartbeat operating on stale data',
+        });
+        verdict.actionable = true;
+        if (verdict.severity === 'none') verdict.severity = 'medium';
+      }
+      for (const [tool, stats] of mcpHealth) {
+        const failRate = stats.calls > 0 ? (stats.failures + stats.degraded) / stats.calls : 0;
+        if (failRate > 0) {
+          const status = failRate >= 0.5 ? 'alert' : 'warn';
+          const detail = `${stats.failures} failures, ${stats.degraded} degraded out of ${stats.calls} calls`
+            + (stats.lastFailure ? ` — last error: ${stats.lastFailure}` : '');
+          verdict.checks.push({ name: `mcp_tool:${tool}`, status, detail });
+          if (status === 'alert') verdict.actionable = true;
+        }
+      }
+
+      return {
+        text: verdict.summary,
+        cost: 0.002,
+        meta: { actionable: verdict.actionable, severity: verdict.severity, checks: verdict.checks, source: 'edge_heartbeat' },
+      };
+    } catch (err) {
+      return {
+        text: `Heartbeat error: ${err instanceof Error ? err.message : String(err)}`,
+        cost: 0,
+        meta: { actionable: false, severity: 'none', checks: [], source: 'edge_heartbeat' },
+      };
+    }
+  }
+
+  throw new Error(`No direct handler for pattern: ${intent.classified}`);
+}
+
+export async function executeCodeTask(
+  intent: KernelIntent,
+  env: EdgeEnv,
+): Promise<{ text: string; cost: number }> {
+  // code_task classified requests often involve repo queries (list files, read issues)
+  // that the Claude executor can handle with its GitHub in-process tools.
+  // Fall through to Claude if GitHub tools are available; only punt if not.
+  if (env.githubToken && env.githubRepo) {
+    const { executeClaude } = await import('./claude.js');
+    return executeClaude(intent, env);
+  }
+  return {
+    text: 'I can\'t execute code tasks from the web interface — that requires local filesystem access. If you need me to write or modify code, connect via the CLI on your development machine. I can still help you think through the approach, review logic, or plan the implementation here.',
+    cost: 0,
+  };
+}