@stackbilt/aegis-core 0.1.0

package/src/kernel/scheduled/goals.ts

@@ -0,0 +1,214 @@
+import { createIntent, dispatch, type EdgeEnv } from '../dispatch.js';
+import { getActiveGoals, touchGoal, recordGoalAction, getGoalActions, downgradeGoalAuthority, type AgentGoal } from '../memory/index.js';
+
+// ─── Autonomous Goal Loop (#14, #28) ─────────────────────────
+
+// Standing Orders: structured context for goal execution.
+// Stored in agent_goals.context_json. Defines scope, guardrails,
+// and escalation rules so goals operate with clear boundaries.
+export interface GoalContext {
+  scope?: string[];          // What this goal IS authorized to do
+  guardrails?: string[];     // What this goal must NOT do
+  escalation?: string[];     // When to stop and flag for human attention
+  triggers?: string[];       // Additional trigger conditions beyond schedule
+  deadline?: string;         // ISO date — auto-complete goal after this date
+}
+
+// Coerce string fields to string[] — context_json in the DB may have been written
+// with a plain string instead of an array, which passes the optional-chain length
+// guard but causes .map() to throw at runtime (aegis#585).
+function normalizeContext(raw: GoalContext): GoalContext {
+  const toArr = (v: unknown): string[] | undefined => {
+    if (!v) return undefined;
+    if (Array.isArray(v)) return v.map(String);
+    if (typeof v === 'string') return [v];
+    return undefined;
+  };
+  return {
+    ...raw,
+    scope:      toArr(raw.scope),
+    guardrails: toArr(raw.guardrails),
+    escalation: toArr(raw.escalation),
+    triggers:   toArr(raw.triggers),
+  };
+}
+
+function formatStandingOrders(ctx: GoalContext): string {
+  const sections: string[] = [];
+
+  if (ctx.scope?.length) {
+    sections.push(`Scope (what you MAY do):\n${ctx.scope.map(s => `  - ${s}`).join('\n')}`);
+  }
+  if (ctx.guardrails?.length) {
+    sections.push(`Guardrails (what you must NOT do):\n${ctx.guardrails.map(g => `  - ${g}`).join('\n')}`);
+  }
+  if (ctx.escalation?.length) {
+    sections.push(`Escalation (stop and flag if):\n${ctx.escalation.map(e => `  - ${e}`).join('\n')}`);
+  }
+  if (ctx.triggers?.length) {
+    sections.push(`Additional triggers:\n${ctx.triggers.map(t => `  - ${t}`).join('\n')}`);
+  }
+
+  return sections.length > 0
+    ? `\nStanding Orders:\n${sections.join('\n')}`
+    : '';
+}
+
+export const MAX_GOALS_PER_CYCLE = 3;
+
+// Approved tools for auto_low execution — reversible, low-risk actions only
+// NOTE: Only list tools that ACTUALLY EXIST. Phantom tools cause silent correctness failures
+// where error messages pass the >50 char check and get recorded as "success".
+export const AUTO_LOW_APPROVED_TOOLS: ReadonlySet<string> = new Set([
+  'record_memory_entry',
+  'resolve_agenda_item',
+  'add_agenda_item',
+]);
+
+export const AUTO_LOW_MAX_ACTIONS_PER_RUN = 3;
+export const AUTO_LOW_FAILURE_THRESHOLD = 2; // consecutive failures before downgrade
+
+export async function runGoalLoop(env: EdgeEnv): Promise<void> {
+  const goals = await getActiveGoals(env.db);
+  if (goals.length === 0) return;
+
+  const nowMs = Date.now();
+  const seen = new Set<string | number>();
+  // Parse next_run_at to Date for correct comparison — D1 stores 'YYYY-MM-DD HH:MM:SS'
+  // while JS toISOString() uses 'YYYY-MM-DDTHH:MM:SS.sssZ'. Lexicographic comparison
+  // breaks because space (ASCII 32) < T (ASCII 84), making every goal appear overdue.
+  const due = goals.filter(g => {
+      if (g.next_run_at === null) return true;
+      const nextRunMs = new Date(g.next_run_at + 'Z').getTime();
+      return nextRunMs <= nowMs;
+    })
+    .filter(g => { if (seen.has(g.id)) return false; seen.add(g.id); return true; })
+    .sort((a, b) => {
+      const aMs = a.next_run_at ? new Date(a.next_run_at + 'Z').getTime() : 0;
+      const bMs = b.next_run_at ? new Date(b.next_run_at + 'Z').getTime() : 0;
+      return aMs - bMs;
+    })
+    .slice(0, MAX_GOALS_PER_CYCLE);
+  if (due.length === 0) return;
+
+  console.log(`[goals] ${due.length} goal(s) due for execution (capped at ${MAX_GOALS_PER_CYCLE})`);
+  for (const goal of due) {
+    // Check consecutive failures for auto_low goals before running
+    if (goal.authority_level === 'auto_low') {
+      const recentActions = await getGoalActions(env.db, goal.id, AUTO_LOW_FAILURE_THRESHOLD);
+      const consecutiveFailures = recentActions.filter(a => a.outcome === 'failure').length;
+      if (consecutiveFailures >= AUTO_LOW_FAILURE_THRESHOLD) {
+        await downgradeGoalAuthority(env.db, goal.id, `${consecutiveFailures} consecutive failures`);
+        goal.authority_level = 'propose'; // reflect downgrade for this run
+      }
+    }
+    await runSingleGoal(env, goal);
+  }
+}
+
+export async function runSingleGoal(env: EdgeEnv, goal: AgentGoal): Promise<void> {
+  // Parse standing orders from context_json
+  let goalContext: GoalContext | null = null;
+  if (goal.context_json) {
+    try {
+      goalContext = normalizeContext(JSON.parse(goal.context_json) as GoalContext);
+    } catch {
+      console.warn(`[goals] Failed to parse context_json for "${goal.title}"`);
+    }
+  }
+
+  // Check deadline — auto-complete expired goals
+  if (goalContext?.deadline) {
+    const deadlineMs = new Date(goalContext.deadline).getTime();
+    if (!isNaN(deadlineMs) && Date.now() > deadlineMs) {
+      console.log(`[goals] Goal "${goal.title}" past deadline (${goalContext.deadline}), marking completed`);
+      await env.db.prepare("UPDATE agent_goals SET status = 'completed', completed_at = datetime('now') WHERE id = ?").bind(goal.id).run();
+      return;
+    }
+  }
+
+  const isAutoLow = goal.authority_level === 'auto_low';
+
+  const authorityInstructions = isAutoLow
+    ? `Authority: auto_low — you may DIRECTLY execute these approved actions without human approval:
+  - record_memory_entry (record observations)
+  - resolve_agenda_item (close stale agenda items)
+  - add_agenda_item (create new agenda items)
+  - Read-only BizOps tools (compliance_items, compliance_status, document_status, dashboard_summary)
+
+  For any action NOT in this list, create a [PROPOSED ACTION] agenda item instead.
+  Maximum ${AUTO_LOW_MAX_ACTIONS_PER_RUN} autonomous actions per run.`
+    : 'Authority: propose — create [PROPOSED ACTION] agenda items, do not execute autonomously.';
+
+  const standingOrders = goalContext ? formatStandingOrders(goalContext) : '';
+
+  const prompt = `You are running the autonomous goal loop. Evaluate the following goal and take appropriate action.
+
+**Goal #${goal.id}: ${goal.title}**
+${goal.description ? `Description: ${goal.description}` : ''}
+${authorityInstructions}${standingOrders}
+Run count: ${goal.run_count}
+
+Procedure:
+1. Use BizOps tools to check current state relevant to this goal
+2. Determine if action is needed
+3. ${isAutoLow
+    ? 'If yes and action is in approved list: execute it directly. Otherwise: create [PROPOSED ACTION] agenda item.'
+    : 'If yes: call add_agenda_item with "[PROPOSED ACTION]" prefix and full reasoning in the context field'}
+4. If no: call record_memory_entry noting what was checked and that no action is needed
+5. ${isAutoLow ? `Maximum ${AUTO_LOW_MAX_ACTIONS_PER_RUN} actions per run.` : 'One proposed action max per run unless multiple urgent issues exist'}
+
+Be concise. This is a scheduled check, not a full analysis.`;
+
+  try {
+    const intent = createIntent(`goal-${goal.id}`, prompt, {
+      source: { channel: 'internal', threadId: `goal-${goal.id}` },
+      classified: 'goal_execution',
+      costCeiling: 'expensive',
+      raw: prompt,
+    });
+
+    const result = await dispatch(intent, env);
+    const partialMeta = result.meta as { partialFailure?: boolean; failedSubtasks?: number; subtasksPlanned?: number } | undefined;
+    const isPartial = partialMeta?.partialFailure;
+    // Partial failure is only a true failure if ALL subtasks failed or the response is empty.
+    // If some subtasks succeeded and returned data, treat as success (the data is usable).
+    // BUT: error messages are NOT usable data — check for known failure patterns.
+    const errorPatterns = ['Tool unavailable', 'Method not found', 'MCP RPC error', 'Unknown tool', 'Memory Worker binding unavailable', 'Memory write failed', 'Cannot read properties of undefined'];
+    const looksLikeError = errorPatterns.some(p => result.text.includes(p));
+    // Clean result patterns indicate the goal achieved its purpose even if subtasks errored
+    const cleanPatterns = ['no overdue', 'all clear', 'compliance posture is clean', 'no deadlines within', 'no action needed', 'recording the check', 'recording clean'];
+    const looksClean = cleanPatterns.some(p => result.text.toLowerCase().includes(p));
+    const hasUsableData = result.text.length > 50 && (!looksLikeError || looksClean);
+    const allFailed = isPartial && (partialMeta?.failedSubtasks ?? 0) >= (partialMeta?.subtasksPlanned ?? 1);
+    // A clean result overrides partial failure — the goal loop got the answer it needed
+    const goalOutcome = (!looksClean && (allFailed || !hasUsableData)) ? 'failure' : 'success';
+    const desc = isPartial
+      ? `${result.text.slice(0, 400)} [partial: ${partialMeta.failedSubtasks} subtask(s) failed]`
+      : result.text.slice(0, 500);
+    await recordGoalAction(env.db, goal.id, 'executed', desc, goalOutcome, {
+      autoExecuted: isAutoLow,
+      authorityLevel: goal.authority_level,
+    });
+    console.log(`[goals] goal "${goal.title}" ${goalOutcome} (${goal.authority_level}) — ${result.text.slice(0, 100)}`);
+  } catch (err) {
+    const msg = err instanceof Error ? err.message : String(err);
+    try {
+      await recordGoalAction(env.db, goal.id, 'skipped', `Error: ${msg}`, 'failure', {
+        autoExecuted: false,
+        authorityLevel: goal.authority_level,
+      });
+    } catch { /* don't let recording failure prevent touchGoal */ }
+    console.error(`[goals] goal "${goal.title}" failed:`, msg);
+
+    // Failure downgrade: auto_low goal that fails reverts to propose
+    if (isAutoLow) {
+      await downgradeGoalAuthority(env.db, goal.id, `Execution failure: ${msg.slice(0, 200)}`);
+    }
+  } finally {
+    // Always advance schedule — prevents runaway re-execution on persistent errors (#83)
+    await touchGoal(env.db, goal.id, goal.schedule_hours).catch(err =>
+      console.error(`[goals] touchGoal failed for "${goal.title}":`, err instanceof Error ? err.message : String(err))
+    );
+  }
+}

package/src/kernel/scheduled/governance.ts

@@ -0,0 +1,41 @@
+// Task Governance Limits — safety checks before auto-creating cc_tasks
+// Prevents runaway task creation by enforcing caps on active AEGIS tasks.
+
+/**
+ * Check whether AEGIS is allowed to create another task.
+ * Returns { allowed: true } or { allowed: false, reason: string }.
+ */
+export async function checkTaskGovernanceLimits(
+  db: D1Database,
+  opts: { repo: string; title: string; category: string },
+): Promise<{ allowed: true } | { allowed: false; reason: string }> {
+  // Per-repo cap: max 5 active AEGIS tasks per repo
+  const repoPending = await db.prepare(
+    `SELECT COUNT(*) as c FROM cc_tasks WHERE status IN ('pending', 'running') AND created_by LIKE 'aegis%' AND repo = ?`
+  ).bind(opts.repo).first<{ c: number }>();
+
+  if (repoPending && repoPending.c >= 5) {
+    return { allowed: false, reason: `Per-repo cap reached (${repoPending.c}/5 active AEGIS tasks for ${opts.repo})` };
+  }
+
+  // Global active cap: max 20 pending/running AEGIS tasks across all repos
+  // Completed tasks don't block new work — cap is self-regulating via consumption
+  const activeCount = await db.prepare(
+    `SELECT COUNT(*) as c FROM cc_tasks WHERE status IN ('pending', 'running') AND created_by LIKE 'aegis%'`
+  ).first<{ c: number }>();
+
+  if (activeCount && activeCount.c >= 20) {
+    return { allowed: false, reason: `Active task cap reached (${activeCount.c}/20 pending/running AEGIS tasks)` };
+  }
+
+  // Duplicate title detection: prevent creating tasks with identical titles that are active or completed
+  const duplicate = await db.prepare(
+    `SELECT COUNT(*) as c FROM cc_tasks WHERE title = ? AND status IN ('pending', 'running', 'completed')`
+  ).bind(opts.title).first<{ c: number }>();
+
+  if (duplicate && duplicate.c > 0) {
+    return { allowed: false, reason: `Duplicate task: "${opts.title}" is already pending` };
+  }
+
+  return { allowed: true };
+}

package/src/kernel/scheduled/heartbeat.ts

@@ -0,0 +1,220 @@
+import { createIntent, dispatch, type EdgeEnv } from '../dispatch.js';
+import { getActiveAgendaItems, getRecentHeartbeats, PROPOSED_ACTION_PREFIX } from '../memory/index.js';
+import { type StaleHighItem } from './escalation.js';
+
+export const ALERT_SEVERITIES = new Set(['medium', 'high', 'critical']);
+
+/** Hours between heartbeat runs (directive: reduce from 1h to 6h) */
+const HEARTBEAT_CADENCE_HOURS = 6;
+
+/** Consecutive medium runs before severity decays to LOW (directive: 10+ → downgrade) */
+const CHRONIC_MEDIUM_THRESHOLD = 10;
+
+/** Once decayed to LOW, only re-surface weekly (runs at 6h cadence = 28 runs/week) */
+const LOW_RESURFACE_INTERVAL = 28;
+
+export type CheckStatus = 'ok' | 'warn' | 'alert';
+export interface HeartbeatCheck { name: string; status: CheckStatus; detail: string }
+
+export async function runHeartbeat(env: EdgeEnv, staleHighItems: StaleHighItem[] = []): Promise<void> {
+  // Cadence gate: only run every 6 hours (0, 6, 12, 18 UTC)
+  // Skip at 12 UTC — daily digest covers that slot
+  const hour = new Date().getUTCHours();
+  if (hour % HEARTBEAT_CADENCE_HOURS !== 0 || hour === 12) return;
+
+  // Load prior heartbeat history for trend context (#6)
+  const priorRuns = await getRecentHeartbeats(env.db, 12);
+  const priorChecksMap = new Map<string, CheckStatus[]>();
+  for (const run of priorRuns) {
+    const checks = JSON.parse(run.checks_json) as HeartbeatCheck[];
+    for (const c of checks) {
+      const history = priorChecksMap.get(c.name) ?? [];
+      history.push(c.status);
+      priorChecksMap.set(c.name, history);
+    }
+  }
+
+  const intent = createIntent('scheduled', 'heartbeat check', {
+    source: { channel: 'internal', threadId: 'scheduled' },
+    classified: 'heartbeat',
+    costCeiling: 'free',
+  });
+  const result = await dispatch(intent, env);
+  const meta = result.meta as { actionable?: boolean; severity?: string; checks?: unknown[] } | undefined;
+
+  const actionable = meta?.actionable ?? false;
+  const severity = meta?.severity ?? 'none';
+  const checks = (meta?.checks ?? []) as HeartbeatCheck[];
+
+  const checksJson = JSON.stringify(checks);
+
+  await env.db.prepare(
+    'INSERT INTO heartbeat_results (actionable, severity, summary, checks_json) VALUES (?, ?, ?, ?)'
+  ).bind(
+    actionable ? 1 : 0,
+    severity,
+    result.text.slice(0, 500),
+    checksJson,
+  ).run();
+
+  // Payload dedup: if checks are identical to the last run, suppress all email/digest writes.
+  // Only recording the result above (for trend history) and agenda sync still proceed.
+  const lastRun = priorRuns[0];
+  if (lastRun && lastRun.checks_json === checksJson) {
+    console.log('[heartbeat] Payload identical to previous run — suppressing email/digest');
+    return;
+  }
+
+  // Classify each check as new / persisting / escalated / resolved (#6)
+  // emailableChecks: new + escalated (triggers alert email)
+  // agendaChecks: new + escalated + persisting (synced to agenda, but no re-email for persisters)
+  const { emailableChecks, agendaChecks, resolved } = classifyCheckDeltas(checks, priorChecksMap);
+
+  // Per-check email cooldown (24h) — prevents re-alerting when checks flap due to
+  // transient BizOps timeouts or data fluctuations resetting the history window
+  const ALERT_COOLDOWN_MS = 24 * 60 * 60 * 1000;
+  const dedupedEmailChecks: HeartbeatCheck[] = [];
+  for (const check of emailableChecks) {
+    const eventKey = `heartbeat_alert_${check.name}`;
+    const lastAlert = await env.db.prepare(
+      "SELECT received_at FROM web_events WHERE event_id = ?"
+    ).bind(eventKey).first<{ received_at: string }>();
+    if (lastAlert && (Date.now() - new Date(lastAlert.received_at + 'Z').getTime()) < ALERT_COOLDOWN_MS) {
+      continue; // already alerted within 24h
+    }
+    dedupedEmailChecks.push(check);
+  }
+
+  await syncChecksToAgenda(env.db, agendaChecks);
+
+  // Auto-resolve agenda items for checks that cleared
+  await resolveAgendaForChecks(env.db, resolved);
+
+  // Inject stale escalation items as heartbeat checks so they appear in the same email
+  if (staleHighItems.length > 0) {
+    for (const s of staleHighItems) {
+      const alreadyTracked = dedupedEmailChecks.some(c => c.name === `stale_agenda_${s.id}`);
+      if (!alreadyTracked) {
+        dedupedEmailChecks.push({
+          name: `stale_agenda_${s.id}`,
+          status: 'warn',
+          detail: `${s.item.slice(0, 120)} (${Math.floor(s.ageDays)}d stale)`,
+        });
+      }
+    }
+  }
+
+  // Ensure severity covers escalation items even if LLM heartbeat was clean
+  const effectiveSeverity = dedupedEmailChecks.length > 0 && !ALERT_SEVERITIES.has(severity)
+    ? 'medium'
+    : severity;
+
+  // All heartbeat alerts — write to digest_sections for daily digest consolidation.
+  // No standalone emails. Critical ARGUS events (CI failures, payment issues) handle
+  // real-time alerting; heartbeat checks are not time-sensitive enough for inbox spam.
+  if (dedupedEmailChecks.length > 0 && ALERT_SEVERITIES.has(effectiveSeverity)) {
+    const payload = JSON.stringify({
+      severity: effectiveSeverity,
+      checks: dedupedEmailChecks,
+      timestamp: new Date().toISOString(),
+    });
+    await env.db.prepare(
+      "INSERT INTO digest_sections (section, payload) VALUES ('health_check', ?)"
+    ).bind(payload).run();
+    // Record per-check cooldown timestamps
+    for (const check of dedupedEmailChecks) {
+      const eventKey = `heartbeat_alert_${check.name}`;
+      await env.db.prepare(
+        "INSERT OR REPLACE INTO web_events (event_id, received_at) VALUES (?, datetime('now'))"
+      ).bind(eventKey).run();
+    }
+  }
+}
+
+export function classifyCheckDeltas(
+  current: HeartbeatCheck[],
+  priorMap: Map<string, CheckStatus[]>,
+): { emailableChecks: HeartbeatCheck[]; agendaChecks: HeartbeatCheck[]; resolved: string[] } {
+  const emailableChecks: HeartbeatCheck[] = []; // new + escalated → triggers email
+  const agendaChecks: HeartbeatCheck[] = [];    // new + escalated + persisting → agenda sync
+  const resolved: string[] = [];
+
+  for (const check of current) {
+    const prior = priorMap.get(check.name) ?? [];
+    const lastStatus = prior[0]; // most recent prior run
+
+    if (check.status === 'ok') {
+      // Was previously warn/alert → now ok = resolved
+      if (lastStatus && lastStatus !== 'ok') resolved.push(check.name);
+      continue;
+    }
+
+    if (!lastStatus || lastStatus === 'ok') {
+      // New issue — email + agenda
+      emailableChecks.push(check);
+      agendaChecks.push(check);
+    } else if (check.status === 'alert' && lastStatus === 'warn') {
+      // Escalated warn→alert — email + agenda
+      emailableChecks.push(check);
+      agendaChecks.push(check);
+    } else {
+      // Persisting — check for chronic medium decay before deciding re-surface cadence
+      const allPrior = [lastStatus, ...prior.slice(1)];
+      const consecutivePersist = allPrior.filter(s => s !== 'ok').length;
+
+      // Severity decay: medium items persisting 10+ runs are accepted risks.
+      // Downgrade to LOW and only re-surface weekly (~28 runs at 6h cadence).
+      if (check.status === 'warn' && consecutivePersist >= CHRONIC_MEDIUM_THRESHOLD) {
+        if (consecutivePersist > 0 && consecutivePersist % LOW_RESURFACE_INTERVAL === 0) {
+          agendaChecks.push({ ...check, detail: `${check.detail} (known risk, weekly check-in — ${consecutivePersist + 1} runs)` });
+        }
+        // Otherwise fully suppress — operator is aware
+      } else if (consecutivePersist > 0 && consecutivePersist % 12 === 0) {
+        // Normal persisting items re-surface every 12 runs (~3 days at 6h cadence)
+        agendaChecks.push({ ...check, detail: `${check.detail} (persisting ${consecutivePersist + 1} runs)` });
+      }
+      // Otherwise suppress entirely — already on agenda
+    }
+  }
+
+  return { emailableChecks, agendaChecks, resolved };
+}
+
+export async function syncChecksToAgenda(db: D1Database, checks: HeartbeatCheck[]): Promise<void> {
+  for (const check of checks) {
+    const existing = await db.prepare(
+      "SELECT id FROM agent_agenda WHERE status = 'active' AND item LIKE ?"
+    ).bind(`%${check.name}%`).first();
+    if (existing) continue;
+
+    // Respect dismissed items — don't re-create if dismissed within the last 7 days.
+    // This prevents agenda churn where a known structural condition (e.g. low separation
+    // scores) gets re-created every heartbeat cycle after the operator dismisses it.
+    const recentlyDismissed = await db.prepare(
+      "SELECT id FROM agent_agenda WHERE status = 'dismissed' AND item LIKE ? AND resolved_at > datetime('now', '-7 days')"
+    ).bind(`%${check.name}%`).first();
+    if (recentlyDismissed) continue;
+
+    // Alert-level checks become proposed actions — AEGIS has a specific recommended step.
+    // Warn-level checks are regular agenda items (flag only, no clear action yet).
+    const isProposed = check.status === 'alert';
+    const item = isProposed
+      ? `${PROPOSED_ACTION_PREFIX} ${check.name}: ${check.detail}`
+      : `${check.name}: ${check.detail}`;
+    const context = isProposed
+      ? `Auto-detected by heartbeat. Review in BizOps and resolve the underlying issue, then mark this item done.`
+      : 'Auto-detected by heartbeat';
+
+    await db.prepare(
+      'INSERT INTO agent_agenda (item, context, priority) VALUES (?, ?, ?)'
+    ).bind(item, context, isProposed ? 'high' : 'medium').run();
+  }
+}
+
+export async function resolveAgendaForChecks(db: D1Database, checkNames: string[]): Promise<void> {
+  for (const name of checkNames) {
+    await db.prepare(
+      "UPDATE agent_agenda SET status = 'done', resolved_at = datetime('now') WHERE status = 'active' AND item LIKE ?"
+    ).bind(`%${name}%`).run();
+  }
+}

package/src/kernel/scheduled/inbox-processor.ts

@@ -0,0 +1,174 @@
+// --- Agent Inbox Processor ---
+// Runs every hour in the heartbeat phase. Reads AEGIS's unread
+// inbox messages, processes them by type, acks, and responds.
+// Zero LLM cost -- all processing is D1 reads/writes + memory lookups.
+// For context_request: pull relevant memory and post a reply.
+// For task_proposal: create agenda item for operator approval.
+// For alert: escalate to agenda.
+// For status_update/message: ack and optionally record to memory.
+
+import { type EdgeEnv } from '../dispatch.js';
+import { searchMemoryByKeywords, recordMemory } from '../memory-adapter.js';
+import { addAgendaItem } from '../memory/index.js';
+
+interface InboxMessage {
+  id: string;
+  sender: string;
+  recipient: string;
+  channel: string;
+  msg_type: string;
+  subject: string;
+  body: string;
+  created_at: string;
+}
+
+async function ackMessage(db: D1Database, id: string): Promise<void> {
+  await db.prepare("UPDATE agent_inbox SET acked_at = datetime('now') WHERE id = ?").bind(id).run();
+}
+
+async function postReply(db: D1Database, sender: string, recipient: string, channel: string, msgType: string, subject: string, body: string): Promise<void> {
+  const id = crypto.randomUUID();
+  await db.prepare(`
+    INSERT INTO agent_inbox (id, sender, recipient, channel, msg_type, subject, body)
+    VALUES (?, ?, ?, ?, ?, ?, ?)
+  `).bind(id, sender, recipient, channel, msgType, subject, body).run();
+}
+
+async function handleContextRequest(msg: InboxMessage, env: EdgeEnv): Promise<void> {
+  // Extract keywords from subject + body for memory search
+  const searchTerms = `${msg.subject} ${msg.body}`.slice(0, 500);
+
+  // Search semantic memory (requires Memory Worker binding)
+  const memories = env.memoryBinding
+    ? await searchMemoryByKeywords(env.memoryBinding, searchTerms, 15)
+    : [];
+
+  // Also check episodic memory for recent conversations on the topic
+  const episodes = await env.db.prepare(`
+    SELECT intent, classification, outcome, created_at
+    FROM episodic_memory
+    WHERE intent LIKE ? OR classification LIKE ?
+    ORDER BY created_at DESC LIMIT 10
+  `).bind(`%${msg.subject.split(' ')[0]}%`, `%${msg.subject.split(' ')[0]}%`).all();
+
+  // Build response
+  const memorySection = memories.length > 0
+    ? memories.map(m => `- [${m.topic}] ${m.fact} (confidence: ${m.confidence})`).join('\n')
+    : '(no relevant memories found)';
+
+  const episodeSection = (episodes.results?.length ?? 0) > 0
+    ? (episodes.results as Array<{ intent: string; classification: string; outcome: string; created_at: string }>)
+        .map(e => `- [${e.created_at}] ${e.classification}: ${e.intent?.slice(0, 100)}`)
+        .join('\n')
+    : '(no recent episodes)';
+
+  const response = `## Context: ${msg.subject}
+
+### Semantic Memory (${memories.length} entries)
+${memorySection}
+
+### Recent Episodes (${episodes.results?.length ?? 0})
+${episodeSection}
+
+---
+_Auto-generated by AEGIS inbox processor in response to context_request from ${msg.sender}_`;
+
+  await postReply(env.db, 'aegis', msg.sender, msg.channel, 'message', `Re: ${msg.subject}`, response);
+  await ackMessage(env.db, msg.id);
+  console.log(`[inbox] Replied to context_request from ${msg.sender}: ${msg.subject}`);
+}
+
+async function handleTaskProposal(msg: InboxMessage, env: EdgeEnv): Promise<void> {
+  // Create agenda item for operator approval
+  await addAgendaItem(
+    env.db,
+    `[${msg.sender.toUpperCase()}] Task proposal: ${msg.subject}`,
+    `From ${msg.sender} via agent inbox:\n\n${msg.body}`,
+    'medium',
+  );
+
+  await postReply(env.db, 'aegis', msg.sender, msg.channel, 'message',
+    `Re: ${msg.subject}`,
+    `Task proposal received and added to operator agenda for review. Will update when the operator responds.`);
+
+  await ackMessage(env.db, msg.id);
+  console.log(`[inbox] Task proposal from ${msg.sender} -> agenda: ${msg.subject}`);
+}
+
+async function handleAlert(msg: InboxMessage, env: EdgeEnv): Promise<void> {
+  // Alerts go directly to high-priority agenda
+  await addAgendaItem(
+    env.db,
+    `[ALERT:${msg.sender.toUpperCase()}] ${msg.subject}`,
+    `Agent alert from ${msg.sender}:\n\n${msg.body}`,
+    'high',
+  );
+
+  await ackMessage(env.db, msg.id);
+  console.log(`[inbox] Alert from ${msg.sender} escalated to agenda: ${msg.subject}`);
+}
+
+async function handleStatusUpdate(msg: InboxMessage, env: EdgeEnv): Promise<void> {
+  // Record significant status updates to memory
+  if (env.memoryBinding) {
+    await recordMemory(env.memoryBinding, 'aegis', `[${msg.sender}] ${msg.subject}: ${msg.body.slice(0, 500)}`, 0.7, 'agent_inbox');
+  }
+  await ackMessage(env.db, msg.id);
+  console.log(`[inbox] Status update from ${msg.sender} recorded: ${msg.subject}`);
+}
+
+async function handleMessage(msg: InboxMessage, env: EdgeEnv): Promise<void> {
+  // Generic messages -- ack and log
+  await ackMessage(env.db, msg.id);
+  console.log(`[inbox] Message from ${msg.sender} acked: ${msg.subject}`);
+}
+
+export async function runInboxProcessor(env: EdgeEnv): Promise<void> {
+  // Read unread messages for AEGIS
+  const result = await env.db.prepare(`
+    SELECT id, sender, recipient, channel, msg_type, subject, body, created_at
+    FROM agent_inbox
+    WHERE (recipient = 'aegis' OR recipient = 'all')
+      AND acked_at IS NULL
+    ORDER BY created_at ASC
+    LIMIT 20
+  `).all<InboxMessage>();
+
+  const messages = result.results ?? [];
+  if (messages.length === 0) return;
+
+  console.log(`[inbox] Processing ${messages.length} unread message(s)`);
+
+  for (const msg of messages) {
+    // Don't process our own broadcasts
+    if (msg.sender === 'aegis' && msg.recipient === 'all') {
+      await ackMessage(env.db, msg.id);
+      continue;
+    }
+
+    try {
+      switch (msg.msg_type) {
+        case 'context_request':
+          await handleContextRequest(msg, env);
+          break;
+        case 'task_proposal':
+          await handleTaskProposal(msg, env);
+          break;
+        case 'alert':
+          await handleAlert(msg, env);
+          break;
+        case 'status_update':
+          await handleStatusUpdate(msg, env);
+          break;
+        case 'message':
+        default:
+          await handleMessage(msg, env);
+          break;
+      }
+    } catch (err) {
+      console.error(`[inbox] Error processing message ${msg.id} from ${msg.sender}:`, err instanceof Error ? err.message : String(err));
+      // Ack anyway to prevent infinite reprocessing
+      await ackMessage(env.db, msg.id);
+    }
+  }
+}