@stackbilt/aegis-core 0.1.0

package/src/kernel/board.ts

@@ -0,0 +1,91 @@
+// --- Project Board State Manager ---
+// D1 CRUD for board_items. Called by ARGUS webhooks, issue-watcher,
+// CC task lifecycle, and board-sync reconciliation.
+
+import type { BoardColumn } from '../schema-enums.js';
+export type { BoardColumn } from '../schema-enums.js';
+
+export interface BoardItem {
+  id: string;
+  project_id: string;
+  content_type: 'issue' | 'pr';
+  content_node_id: string;
+  repo: string;
+  number: number;
+  title: string;
+  status: BoardColumn;
+  labels: string;
+  assignee: string | null;
+  cc_task_id: string | null;
+  updated_at: string;
+  synced_at: string;
+}
+
+// --- Config ---
+// Override via operator config for your org
+export const PROJECT_TITLE = 'AEGIS Operations';
+export const ORG_LOGIN = 'ExampleOrg';
+
+// --- D1 Operations ---
+
+/** Upsert a board item into D1. */
+export async function upsertBoardItem(db: D1Database, item: Partial<BoardItem> & { repo: string; number: number }): Promise<void> {
+  await db.prepare(`
+    INSERT INTO board_items (id, project_id, content_type, content_node_id, repo, number, title, status, labels, assignee, cc_task_id, updated_at, synced_at)
+    VALUES (?1, ?2, ?3, ?4, ?5, ?6, ?7, ?8, ?9, ?10, ?11, datetime('now'), datetime('now'))
+    ON CONFLICT(repo, number) DO UPDATE SET
+      id = COALESCE(?1, board_items.id),
+      project_id = COALESCE(?2, board_items.project_id),
+      content_type = COALESCE(?3, board_items.content_type),
+      content_node_id = COALESCE(?4, board_items.content_node_id),
+      title = COALESCE(?7, board_items.title),
+      status = COALESCE(?8, board_items.status),
+      labels = COALESCE(?9, board_items.labels),
+      assignee = COALESCE(?10, board_items.assignee),
+      cc_task_id = COALESCE(?11, board_items.cc_task_id),
+      updated_at = datetime('now'),
+      synced_at = datetime('now')
+  `).bind(
+    item.id ?? null,
+    item.project_id ?? null,
+    item.content_type ?? null,
+    item.content_node_id ?? null,
+    item.repo,
+    item.number,
+    item.title ?? null,
+    item.status ?? null,
+    item.labels ?? null,
+    item.assignee ?? null,
+    item.cc_task_id ?? null,
+  ).run();
+}
+
+export async function ensureOnBoard(
+  db: D1Database,
+  githubToken: string,
+  projectId: string,
+  repo: string,
+  issueNumber: number,
+  title: string,
+  status: string,
+): Promise<void> {
+  throw new Error('not implemented');
+}
+
+export async function moveBoardItemLocal(
+  db: D1Database,
+  repo: string,
+  issueNumber: number,
+  status: 'queued' | 'in_progress' | 'shipped' | 'blocked' | 'backlog',
+): Promise<void> {
+  throw new Error('not implemented');
+}
+
+export async function linkTaskToBoard(
+  db: D1Database,
+  taskId: string,
+  repo: string,
+  issueNumber: number,
+): Promise<void> {
+  throw new Error('not implemented');
+}

package/src/kernel/briefing.ts

@@ -0,0 +1,177 @@
+// Re-entry Briefing: "Last time on the operator's empire"
+// Generates a concise situational briefing when the operator starts a session.
+// Thinks like the operator: what happened, what needs me, what's AEGIS working on.
+// No fluff, no preamble. Answer before the question is asked.
+
+import type { EdgeEnv } from './dispatch.js';
+
+export interface Briefing {
+  // What happened while you were away
+  shipped: string[];       // tasks completed, PRs merged
+  failed: string[];        // tasks that need attention
+  // What needs you right now
+  decisions: string[];     // proposed actions, stale agenda, approvals needed
+  // What AEGIS is working on
+  active: string[];        // running tasks, pending queue
+  // Signals
+  alerts: string[];        // ARGUS events, health issues
+  // One-liner state
+  cognitiveScore: number | null;
+  eventCount24h: number;
+}
+
+export async function generateBriefing(env: EdgeEnv): Promise<Briefing> {
+  const since = new Date(Date.now() - 24 * 60 * 60 * 1000).toISOString();
+
+  // All queries in parallel — fast
+  const [
+    completedTasks,
+    failedTasks,
+    pendingProposed,
+    runningTasks,
+    pendingTasks,
+    staleAgenda,
+    recentEvents,
+    healthAlerts,
+    cogMetrics,
+  ] = await Promise.all([
+    // Shipped in last 24h
+    env.db.prepare(
+      "SELECT title, repo, pr_url FROM cc_tasks WHERE status = 'completed' AND completed_at > ? ORDER BY completed_at DESC LIMIT 5"
+    ).bind(since).all<{ title: string; repo: string; pr_url: string | null }>(),
+
+    // Failed in last 24h
+    env.db.prepare(
+      "SELECT title, repo, error FROM cc_tasks WHERE status = 'failed' AND completed_at > ? ORDER BY completed_at DESC LIMIT 3"
+    ).bind(since).all<{ title: string; repo: string; error: string | null }>(),
+
+    // Proposed tasks awaiting approval
+    env.db.prepare(
+      "SELECT title, repo FROM cc_tasks WHERE authority = 'proposed' AND status = 'pending' ORDER BY created_at ASC LIMIT 5"
+    ).all<{ title: string; repo: string }>(),
+
+    // Currently running
+    env.db.prepare(
+      "SELECT title, repo FROM cc_tasks WHERE status = 'running' LIMIT 3"
+    ).all<{ title: string; repo: string }>(),
+
+    // Pending queue depth
+    env.db.prepare(
+      "SELECT COUNT(*) as cnt FROM cc_tasks WHERE status = 'pending'"
+    ).first<{ cnt: number }>(),
+
+    // High-priority agenda items older than 3 days (stale = needs attention)
+    env.db.prepare(
+      "SELECT item FROM agent_agenda WHERE status = 'active' AND priority = 'high' AND created_at < datetime('now', '-3 days') ORDER BY created_at ASC LIMIT 3"
+    ).all<{ item: string }>(),
+
+    // ARGUS events in last 24h
+    env.db.prepare(
+      "SELECT COUNT(*) as cnt FROM events WHERE ts > ?"
+    ).bind(since).first<{ cnt: number }>(),
+
+    // Recent health alerts (non-ok heartbeats in last 24h)
+    env.db.prepare(
+      "SELECT severity, summary FROM heartbeat_results WHERE severity IN ('high', 'critical') AND created_at > ? ORDER BY created_at DESC LIMIT 2"
+    ).bind(since).all<{ severity: string; summary: string }>(),
+
+    // Latest cognitive score
+    env.db.prepare(
+      "SELECT payload FROM digest_sections WHERE section = 'cognitive_metrics' ORDER BY created_at DESC LIMIT 1"
+    ).first<{ payload: string }>(),
+  ]);
+
+  // Parse cognitive score
+  let cognitiveScore: number | null = null;
+  if (cogMetrics?.payload) {
+    try {
+      const parsed = JSON.parse(cogMetrics.payload);
+      cognitiveScore = parsed.cognitive_score ?? null;
+    } catch { /* skip */ }
+  }
+
+  // Build briefing
+  const shipped = completedTasks.results.map(t =>
+    t.pr_url ? `${t.title} (${t.repo}) — PR: ${t.pr_url}` : `${t.title} (${t.repo})`
+  );
+
+  const failed = failedTasks.results.map(t =>
+    `${t.title} (${t.repo})${t.error ? ` — ${t.error.slice(0, 80)}` : ''}`
+  );
+
+  const decisions: string[] = [];
+  if (pendingProposed.results.length > 0) {
+    decisions.push(`${pendingProposed.results.length} proposed task${pendingProposed.results.length > 1 ? 's' : ''} awaiting approval: ${pendingProposed.results.map(t => t.title.slice(0, 50)).join(', ')}`);
+  }
+  for (const item of staleAgenda.results) {
+    decisions.push(item.item.slice(0, 100));
+  }
+
+  const active: string[] = [];
+  for (const t of runningTasks.results) {
+    active.push(`Running: ${t.title} (${t.repo})`);
+  }
+  const queueDepth = pendingTasks?.cnt ?? 0;
+  if (queueDepth > 0) {
+    active.push(`${queueDepth} task${queueDepth > 1 ? 's' : ''} in queue`);
+  }
+
+  const alerts: string[] = [];
+  for (const h of healthAlerts.results) {
+    alerts.push(`[${h.severity.toUpperCase()}] ${h.summary.slice(0, 100)}`);
+  }
+
+  return {
+    shipped,
+    failed,
+    decisions,
+    active,
+    alerts,
+    cognitiveScore,
+    eventCount24h: recentEvents?.cnt ?? 0,
+  };
+}
+
+// Format briefing as concise text for injection into greeting response
+export function formatBriefing(b: Briefing): string {
+  const sections: string[] = [];
+
+  // Header
+  const now = new Date();
+  const dayNames = ['Sunday', 'Monday', 'Tuesday', 'Wednesday', 'Thursday', 'Friday', 'Saturday'];
+  const day = dayNames[now.getUTCDay()];
+  const scoreStr = b.cognitiveScore !== null ? ` | Cognitive: ${b.cognitiveScore}/100` : '';
+  sections.push(`**${day}** — ${b.eventCount24h} events in last 24h${scoreStr}`);
+
+  // What needs you (decisions first — this is what the operator looks for)
+  if (b.decisions.length > 0) {
+    sections.push(`\n**Needs you:**\n${b.decisions.map(d => `- ${d}`).join('\n')}`);
+  }
+
+  // What shipped
+  if (b.shipped.length > 0) {
+    sections.push(`\n**Shipped (24h):**\n${b.shipped.map(s => `- ${s}`).join('\n')}`);
+  }
+
+  // What failed
+  if (b.failed.length > 0) {
+    sections.push(`\n**Failed:**\n${b.failed.map(f => `- ${f}`).join('\n')}`);
+  }
+
+  // Alerts
+  if (b.alerts.length > 0) {
+    sections.push(`\n**Alerts:**\n${b.alerts.map(a => `- ${a}`).join('\n')}`);
+  }
+
+  // What I'm working on
+  if (b.active.length > 0) {
+    sections.push(`\n**Active:**\n${b.active.map(a => `- ${a}`).join('\n')}`);
+  }
+
+  // Nothing happening
+  if (b.shipped.length === 0 && b.failed.length === 0 && b.decisions.length === 0 && b.alerts.length === 0) {
+    sections.push('\nQuiet 24h. Nothing on fire, nothing shipped. What do you want to work on?');
+  }
+
+  return sections.join('\n');
+}

package/src/kernel/classify-memory-topic.ts

@@ -0,0 +1,166 @@
+// Memory topic classification via TarotScript memory-topic-classify spread.
+//
+// The spread lives at Stackbilt-dev/tarotscript:spreads/memory-topic-classify.tarot
+// and draws from decks/memory-topics (15 canonical topics for AEGIS semantic
+// memory). See artifacts/tarotscript-classifier-migration.md in aegis-daemon
+// for the broader design and rollout plan.
+//
+// Contract:
+//   classifyMemoryTopic(fetcher, fact) → {
+//     topic: canonical topic string,
+//     confidence: 'high' | 'moderate' | 'low',
+//     source: 'classifier' | 'fallback',
+//     element?: element of drawn card (debugging aid),
+//   }
+//
+// When the classifier returns confidence='low', OR when the classification
+// lands on the 'general' fallback card, OR when the fetcher call fails for
+// any reason, the helper falls through to { topic: 'general', source: 'fallback' }.
+// Callers who want the raw classifier output can use runMemoryTopicClassification
+// directly instead.
+//
+// Telemetry: the helper does not log or persist anything itself. Callers are
+// responsible for recording divergence between operator-provided topics and
+// classifier-inferred topics during the observation rollout.
+
+// The set of canonical topics the classifier is trained to emit. Kept in sync
+// with decks/memory-topics.deck in the tarotscript repo. If the deck adds a
+// new card, also update this list so typecheck catches stale consumers.
+export type CanonicalMemoryTopic =
+  | 'operator'
+  | 'feedback'
+  | 'business_ops'
+  | 'compliance'
+  | 'execution'
+  | 'content'
+  | 'research'
+  | 'reflection'
+  | 'cross_repo_intelligence'
+  | 'feed_intel'
+  | 'aegis'
+  | 'tarotscript'
+  | 'infrastructure'
+  | 'portfolio_project'
+  | 'general';
+
+export const CANONICAL_MEMORY_TOPICS: readonly CanonicalMemoryTopic[] = [
+  'operator', 'feedback', 'business_ops', 'compliance', 'execution',
+  'content', 'research', 'reflection', 'cross_repo_intelligence',
+  'feed_intel', 'aegis', 'tarotscript', 'infrastructure',
+  'portfolio_project', 'general',
+] as const;
+
+export type ClassificationConfidence = 'high' | 'moderate' | 'low';
+
+export interface MemoryTopicClassification {
+  topic: CanonicalMemoryTopic;
+  confidence: ClassificationConfidence;
+  source: 'classifier' | 'fallback';
+  element?: string;
+  receipt_hash?: string;
+}
+
+/**
+ * Raw classification call. Invokes the memory-topic-classify spread on the
+ * tarotscript worker and returns the parsed facts object, or null if the
+ * call fails for any reason (network, auth, worker down, spread error).
+ * The helper wrapper `classifyMemoryTopic` applies fallback semantics on
+ * top of this; most callers should use the wrapper instead.
+ */
+export async function runMemoryTopicClassification(
+  fetcher: Fetcher,
+  fact: string,
+  opts: { seed?: number } = {},
+): Promise<{
+  classification?: string;
+  classification_confidence?: string;
+  classification_element?: string;
+  receipt_hash?: string;
+} | null> {
+  try {
+    const response = await fetcher.fetch('https://internal/run', {
+      method: 'POST',
+      headers: { 'Content-Type': 'application/json' },
+      body: JSON.stringify({
+        spreadType: 'memory-topic-classify',
+        querent: {
+          id: 'aegis',
+          intention: fact,
+        },
+        seed: opts.seed,
+        inscribe: false, // classification is metadata, not a consultation
+      }),
+    });
+
+    if (!response.ok) {
+      console.warn(`[classify-memory-topic] worker returned ${response.status}`);
+      return null;
+    }
+
+    const body = await response.json() as {
+      facts?: Record<string, string>;
+      receipt?: { hash?: string };
+    };
+
+    return {
+      classification: body.facts?.classification,
+      classification_confidence: body.facts?.classification_confidence,
+      classification_element: body.facts?.classification_element,
+      receipt_hash: body.receipt?.hash,
+    };
+  } catch (err) {
+    console.warn(
+      `[classify-memory-topic] fetch failed: ${err instanceof Error ? err.message : String(err)}`,
+    );
+    return null;
+  }
+}
+
+function isCanonicalTopic(value: string | undefined): value is CanonicalMemoryTopic {
+  return typeof value === 'string'
+    && (CANONICAL_MEMORY_TOPICS as readonly string[]).includes(value);
+}
+
+/**
+ * High-level classifier with fallback. Calls the memory-topic-classify spread,
+ * validates the output, and returns 'general' as a stable fallback when:
+ *   - the fetcher call fails (network, auth, worker down)
+ *   - the spread returns an unknown topic (deck drift — log + fall through)
+ *   - the classification confidence is 'low' (deck scoring was ambiguous)
+ *
+ * The fallback is 'general' on purpose — that card exists in the deck for
+ * exactly this reason and callers can filter on `source === 'fallback'` to
+ * distinguish model output from fall-through behavior.
+ */
+export async function classifyMemoryTopic(
+  fetcher: Fetcher,
+  fact: string,
+  opts: { seed?: number } = {},
+): Promise<MemoryTopicClassification> {
+  const raw = await runMemoryTopicClassification(fetcher, fact, opts);
+
+  if (!raw) {
+    return { topic: 'general', confidence: 'low', source: 'fallback' };
+  }
+
+  const confidence = (raw.classification_confidence ?? 'low') as ClassificationConfidence;
+
+  if (confidence === 'low') {
+    return { topic: 'general', confidence: 'low', source: 'fallback' };
+  }
+
+  if (!isCanonicalTopic(raw.classification)) {
+    console.warn(
+      `[classify-memory-topic] unknown canonical topic from classifier: "${raw.classification}" — falling through to 'general'`,
+    );
+    return { topic: 'general', confidence, source: 'fallback' };
+  }
+
+  return {
+    topic: raw.classification,
+    confidence,
+    source: 'classifier',
+    element: raw.classification_element,
+    receipt_hash: raw.receipt_hash,
+  };
+}