@stackbilt/aegis-core 0.1.0

package/src/routes/observability.ts

@@ -0,0 +1,82 @@
+// Stub — full implementation not yet extracted to OSS
+
+import { Hono } from 'hono';
+import type { Env } from '../types.js';
+import { getAllProceduresWithDerivedStats, getActiveAgendaItems } from '../kernel/memory/index.js';
+
+const observability = new Hono<{ Bindings: Env }>();
+
+// ─── Shadow Write Stats ─────────────────────────────────────
+
+observability.get('/api/shadow-stats', async (c) => {
+  const days = parseInt(c.req.query('days') ?? '7', 10);
+
+  const summary = await c.env.DB.prepare(
+    "SELECT COUNT(*) as total_writes, SUM(CASE WHEN worker_ok THEN 1 ELSE 0 END) as worker_ok, SUM(CASE WHEN d1_ok THEN 1 ELSE 0 END) as d1_ok FROM shadow_writes WHERE created_at > datetime('now', '-' || ? || ' days')"
+  ).bind(days).first();
+
+  const errors = await c.env.DB.prepare(
+    "SELECT error_source, COUNT(*) as count FROM shadow_write_errors WHERE created_at > datetime('now', '-' || ? || ' days') GROUP BY error_source"
+  ).bind(days).all();
+
+  const recent = await c.env.DB.prepare(
+    "SELECT topic, worker_ok, d1_ok FROM shadow_writes WHERE created_at > datetime('now', '-' || ? || ' days') ORDER BY created_at DESC LIMIT 20"
+  ).bind(days).all();
+
+  return c.json({ days, summary, errors: errors.results, recent: recent.results });
+});
+
+// ─── Shadow Read Stats ──────────────────────────────────────
+
+observability.get('/api/shadow-read-stats', async (c) => {
+  const days = parseInt(c.req.query('days') ?? '7', 10);
+
+  const summary = await c.env.DB.prepare(
+    "SELECT COUNT(*) as total_reads, AVG(overlap_ratio) as avg_overlap_ratio FROM shadow_reads WHERE created_at > datetime('now', '-' || ? || ' days')"
+  ).bind(days).first();
+
+  const bySite = await c.env.DB.prepare(
+    "SELECT call_site, COUNT(*) as reads FROM shadow_reads WHERE created_at > datetime('now', '-' || ? || ' days') GROUP BY call_site"
+  ).bind(days).all();
+
+  const recent = await c.env.DB.prepare(
+    "SELECT call_site, query_text FROM shadow_reads WHERE created_at > datetime('now', '-' || ? || ' days') ORDER BY created_at DESC LIMIT 20"
+  ).bind(days).all();
+
+  return c.json({ days, summary, by_site: bySite.results, recent: recent.results });
+});
+
+// ─── Agenda ─────────────────────────────────────────────────
+
+observability.get('/agenda', async (c) => {
+  const items = await getActiveAgendaItems(c.env.DB);
+  return c.json({ count: items.length, items });
+});
+
+// ─── Procedures ─────────────────────────────────────────────
+
+observability.get('/procedures', async (c) => {
+  const raw = await getAllProceduresWithDerivedStats(c.env.DB, { reader: 'observability' });
+
+  const procedures = raw.map((p: any) => {
+    const total = p.success_count + p.fail_count;
+    const successRate = total > 0 ? Math.round((p.success_count / total) * 100) / 100 : 0;
+
+    return {
+      pattern: p.task_pattern,
+      executor: p.executor,
+      status: p.status,
+      successes: p.success_count,
+      failures: p.fail_count,
+      consecutiveFailures: p.consecutive_failures,
+      successRate,
+      avgLatencyMs: Math.round(p.avg_latency_ms),
+      avgCost: Math.round(p.avg_cost * 10000) / 10000,
+      lastUsed: p.last_used,
+    };
+  });
+
+  return c.json({ count: procedures.length, procedures });
+});
+
+export { observability };

package/src/routes/operator-logs.ts

@@ -0,0 +1,42 @@
+// Stub — full implementation not yet extracted to OSS
+
+import { Hono } from 'hono';
+import type { Env } from '../types.js';
+
+const operatorLogs = new Hono<{ Bindings: Env }>();
+
+// List operator logs with pagination
+operatorLogs.get('/api/operator-logs', async (c) => {
+  const limit = Math.min(parseInt(c.req.query('limit') ?? '20', 10), 100);
+  const offset = parseInt(c.req.query('offset') ?? '0', 10);
+
+  const logs = await c.env.DB.prepare(
+    'SELECT id, content, episodes_count, created_at FROM operator_logs ORDER BY created_at DESC LIMIT ? OFFSET ?'
+  ).bind(limit, offset).all();
+
+  const countRow = await c.env.DB.prepare(
+    'SELECT COUNT(*) as cnt FROM operator_logs'
+  ).first<{ cnt: number }>();
+
+  return c.json({
+    logs: logs.results,
+    total: countRow?.cnt ?? 0,
+  });
+});
+
+// Get single operator log by ID
+operatorLogs.get('/api/operator-logs/:id', async (c) => {
+  const id = parseInt(c.req.param('id'), 10);
+
+  const log = await c.env.DB.prepare(
+    'SELECT * FROM operator_logs WHERE id = ?'
+  ).bind(id).first();
+
+  if (!log) {
+    return c.json({ error: 'Not found' }, 404);
+  }
+
+  return c.json(log);
+});
+
+export { operatorLogs };

package/src/routes/pages.ts

@@ -0,0 +1,96 @@
+// Stub — full implementation not yet extracted to OSS
+
+import { Hono } from 'hono';
+import { bodyLimit } from 'hono/body-limit';
+import type { Env } from '../types.js';
+import { chatPage } from '../ui.js';
+import { landingPage } from '../landing.js';
+import { dashboardPage, getDashboardData } from '../dashboard.js';
+import { pulsePage, getPulseData } from '../pulse.js';
+
+const DEFAULT_BODY_LIMIT = 100 * 1024;
+
+const pages = new Hono<{ Bindings: Env }>();
+
+// ─── Landing ────────────────────────────────────────────────
+
+pages.get('/', (c) => {
+  return c.html(landingPage());
+});
+
+// ─── Chat ───────────────────────────────────────────────────
+
+pages.get('/chat', (c) => {
+  return c.html(chatPage());
+});
+
+// ─── Pulse ──────────────────────────────────────────────────
+
+pages.get('/pulse', async (c) => {
+  const data = await getPulseData(c.env.DB);
+  return c.html(pulsePage(data));
+});
+
+// ─── Dashboard ──────────────────────────────────────────────
+
+pages.get('/dashboard', async (c) => {
+  const data = await getDashboardData(c.env.DB);
+  return c.html(dashboardPage(data));
+});
+
+// ─── PWA Manifest ───────────────────────────────────────────
+
+pages.get('/manifest.json', (c) => {
+  return c.json({
+    name: 'AEGIS',
+    short_name: 'AEGIS',
+    start_url: '/chat',
+    display: 'standalone',
+    background_color: '#0a0a0f',
+    theme_color: '#8b8bff',
+    icons: [],
+  });
+});
+
+// ─── Service Worker ─────────────────────────────────────────
+
+pages.get('/sw.js', (c) => {
+  const sw = `
+self.addEventListener('install', () => { self.skipWaiting(); });
+self.addEventListener('activate', (event) => { event.waitUntil(clients.claim()); });
+`;
+  return new Response(sw.trim(), {
+    headers: { 'Content-Type': 'application/javascript; charset=utf-8' },
+  });
+});
+
+// ─── Events ─────────────────────────────────────────────────
+
+pages.post('/api/events', bodyLimit({ maxSize: DEFAULT_BODY_LIMIT }), async (c) => {
+  const body = await c.req.json<{ event_id?: string }>();
+  const eventId = body.event_id?.trim();
+
+  if (!eventId) {
+    return c.json({ error: 'event_id is required' }, 400);
+  }
+
+  await c.env.DB.prepare(
+    "INSERT OR REPLACE INTO web_events (event_id, received_at) VALUES (?, datetime('now'))"
+  ).bind(eventId).run();
+
+  return c.json({ ok: true, event_id: eventId });
+});
+
+// ─── Reading (TarotScript) ──────────────────────────────────
+
+pages.post('/api/reading', bodyLimit({ maxSize: DEFAULT_BODY_LIMIT }), async (c) => {
+  const tarotBinding = (c.env as any).TAROTSCRIPT;
+  if (!tarotBinding) {
+    return c.json({ error: 'TarotScript service binding not configured' }, 503);
+  }
+
+  // Full implementation not yet extracted
+  return c.json({ error: 'not implemented' }, 501);
+});
+
+export { pages };

package/src/routes/sessions.ts

@@ -0,0 +1,54 @@
+import { Hono } from 'hono';
+import { bodyLimit } from 'hono/body-limit';
+import type { Env } from '../types.js';
+
+const DEFAULT_BODY_LIMIT = 100 * 1024;
+
+export const sessions = new Hono<{ Bindings: Env }>();
+
+interface CCSessionPayload {
+  summary: string;
+  commits?: Array<{ hash: string; message: string; repo?: string }>;
+  files_changed?: string[];
+  issues_opened?: Array<{ repo: string; number: number; title: string }>;
+  issues_closed?: Array<{ repo: string; number: number; title: string }>;
+  decisions?: string[];
+  repos?: string[];
+  duration_minutes?: number;
+}
+
+sessions.post('/api/cc-session', bodyLimit({ maxSize: DEFAULT_BODY_LIMIT }), async (c) => {
+  const body = await c.req.json<CCSessionPayload>();
+  if (!body.summary?.trim()) {
+    return c.json({ error: 'summary is required' }, 400);
+  }
+
+  const id = crypto.randomUUID();
+  const sessionDate = new Date().toISOString().slice(0, 10);
+
+  await c.env.DB.prepare(`
+    INSERT INTO cc_sessions (id, session_date, summary, commits, files_changed, issues_opened, issues_closed, decisions, repos, duration_minutes)
+    VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?)
+  `).bind(
+    id,
+    sessionDate,
+    body.summary.trim(),
+    body.commits ? JSON.stringify(body.commits) : null,
+    body.files_changed ? JSON.stringify(body.files_changed) : null,
+    body.issues_opened ? JSON.stringify(body.issues_opened) : null,
+    body.issues_closed ? JSON.stringify(body.issues_closed) : null,
+    body.decisions ? JSON.stringify(body.decisions) : null,
+    body.repos ? JSON.stringify(body.repos) : null,
+    body.duration_minutes ?? null,
+  ).run();
+
+  return c.json({ id, session_date: sessionDate, status: 'recorded' }, 201);
+});
+
+sessions.get('/api/cc-sessions', async (c) => {
+  const days = parseInt(c.req.query('days') ?? '7', 10);
+  const sessions = await c.env.DB.prepare(
+    "SELECT * FROM cc_sessions WHERE created_at > datetime('now', '-' || ? || ' days') ORDER BY created_at DESC LIMIT 50"
+  ).bind(days).all();
+  return c.json({ sessions: sessions.results });
+});

package/src/sanitize.ts

@@ -0,0 +1,73 @@
+// sanitize.ts — strip PII and internal identifiers from content before publishing
+//
+// Used by operator-log and reflection pipelines to make internal content
+// safe for the public blog. Applies regex-based redactions in a single pass.
+
+// ─── Known internal entities (replace with generic labels) ───
+const ENTITY_MAP: [RegExp, string][] = [
+  // Company / product names that reveal internal structure
+  [/ExampleCo\s+LLC/gi, '[Company]'],
+  [/Citizens\s+Reunited,?\s*PBC/gi, '[Partner Org]'],
+  [/Citizens\s+Reunited/gi, '[Partner Org]'],
+
+  // People — full names only (first names are OK per journal guidelines)
+  [/Jane\s+Doe/gi, '[Operator]'],
+  [/John\s+Doe/gi, '[Client]'],
+
+  // Internal service names that shouldn't be public
+  [/bizops-copilot/gi, '[internal-service]'],
+  [/aegis-memory/gi, '[memory-service]'],
+];
+
+// ─── Regex patterns for sensitive data ───────────────────────
+const SENSITIVE_PATTERNS: [RegExp, string][] = [
+  // EIN (XX-XXXXXXX)
+  [/\b\d{2}-\d{7}\b/g, '[EIN-REDACTED]'],
+
+  // UUIDs
+  [/\b[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}\b/gi, '[ID-REDACTED]'],
+
+  // API tokens / bearer tokens (aegis_*, memory_*, sk-*, etc.)
+  [/\b(?:aegis|memory|sk|Bearer)\s*[_-]?[a-zA-Z0-9]{16,}\b/gi, '[TOKEN-REDACTED]'],
+
+  // Email addresses
+  [/\b[a-zA-Z0-9._%+-]+@[a-zA-Z0-9.-]+\.[a-zA-Z]{2,}\b/g, '[EMAIL-REDACTED]'],
+
+  // Phone numbers (US formats)
+  [/\b(?:\+?1[-.\s]?)?\(?[0-9]{3}\)?[-.\s]?[0-9]{3}[-.\s]?[0-9]{4}\b/g, '[PHONE-REDACTED]'],
+
+  // Credit card numbers (13-19 digits, possibly separated)
+  [/\b(?:\d[-\s]?){13,19}\b/g, '[CC-REDACTED]'],
+
+  // IP addresses
+  [/\b\d{1,3}\.\d{1,3}\.\d{1,3}\.\d{1,3}\b/g, '[IP-REDACTED]'],
+
+  // Dollar amounts with specific figures (keep general like "$500" but redact exact like "$10.42")
+  [/\$\d{1,3}(?:,\d{3})*\.\d{2}\b/g, '[AMOUNT-REDACTED]'],
+
+  // Cloudflare account IDs (32-char hex)
+  [/\b[0-9a-f]{32}\b/g, '[ACCOUNT-REDACTED]'],
+
+  // Internal URLs with tokens or auth paths
+  [/https?:\/\/[^\s]*(?:token|secret|key|auth)[^\s]*/gi, '[URL-REDACTED]'],
+];
+
+/**
+ * Sanitize content for public blog publication.
+ * Strips PII, internal identifiers, and sensitive business data.
+ */
+export function sanitizeForBlog(content: string): string {
+  let result = content;
+
+  // Pass 1: Named entity replacements
+  for (const [pattern, replacement] of ENTITY_MAP) {
+    result = result.replace(pattern, replacement);
+  }
+
+  // Pass 2: Sensitive data patterns
+  for (const [pattern, replacement] of SENSITIVE_PATTERNS) {
+    result = result.replace(pattern, replacement);
+  }
+
+  return result;
+}

package/src/schema-enums.ts

@@ -0,0 +1,155 @@
+// ─── Centralized Schema Enums ────────────────────────────────
+//
+// Single source of truth for all D1 CHECK constraint values.
+// SQL schema.sql defines the CHECK constraints; this file mirrors
+// them for TypeScript. When adding a new enum value, update BOTH
+// this file and the corresponding CHECK in schema.sql.
+//
+// Rule: no enum literal should appear inline in routes or kernel
+// files. Import from here.
+
+// ─── Helpers ─────────────────────────────────────────────────
+
+/** Derive a union type from a const array. */
+type EnumValues<T extends readonly string[]> = T[number];
+
+// ─── Chat ────────────────────────────────────────────────────
+
+export const MESSAGE_ROLES = ['user', 'assistant'] as const;
+export type MessageRole = EnumValues<typeof MESSAGE_ROLES>;
+
+// ─── Memory ──────────────────────────────────────────────────
+
+export const VALIDATION_STAGES = ['candidate', 'validated', 'expert', 'canonical', 'refuted'] as const;
+export type ValidationStage = EnumValues<typeof VALIDATION_STAGES>;
+
+export const EPISODIC_OUTCOMES = ['success', 'failure'] as const;
+export type EpisodicOutcome = EnumValues<typeof EPISODIC_OUTCOMES>;
+
+export const PROCEDURAL_STATUSES = ['learning', 'learned', 'degraded', 'broken'] as const;
+export type ProceduralStatus = EnumValues<typeof PROCEDURAL_STATUSES>;
+
+// ─── Agenda ──────────────────────────────────────────────────
+
+export const AGENDA_PRIORITIES = ['low', 'medium', 'high'] as const;
+export type AgendaPriority = EnumValues<typeof AGENDA_PRIORITIES>;
+
+export const AGENDA_STATUSES = ['active', 'done', 'dismissed'] as const;
+export type AgendaStatus = EnumValues<typeof AGENDA_STATUSES>;
+
+// ─── Goals & Actions ─────────────────────────────────────────
+
+export const GOAL_STATUSES = ['active', 'paused', 'completed', 'failed'] as const;
+export type GoalStatus = EnumValues<typeof GOAL_STATUSES>;
+
+export const AUTHORITY_LEVELS = ['propose', 'auto_low', 'auto_high'] as const;
+export type AuthorityLevel = EnumValues<typeof AUTHORITY_LEVELS>;
+
+export const ACTION_TYPES = ['proposed', 'executed', 'skipped'] as const;
+export type ActionType = EnumValues<typeof ACTION_TYPES>;
+
+export const ACTION_OUTCOMES = ['success', 'failure', 'pending'] as const;
+export type ActionOutcome = EnumValues<typeof ACTION_OUTCOMES>;
+
+// ─── Task Observability ─────────────────────────────────────
+
+export const HEARTBEAT_STATUSES = ['ok', 'error', 'skipped'] as const;
+export type HeartbeatStatus = EnumValues<typeof HEARTBEAT_STATUSES>;
+
+// ─── CC Tasks ────────────────────────────────────────────────
+
+export const TASK_STATUSES = ['pending', 'running', 'completed', 'failed', 'cancelled'] as const;
+export type TaskStatus = EnumValues<typeof TASK_STATUSES>;
+
+export const TASK_AUTHORITIES = ['proposed', 'auto_safe', 'operator'] as const;
+export type TaskAuthority = EnumValues<typeof TASK_AUTHORITIES>;
+
+export const TASK_CATEGORIES = ['docs', 'tests', 'research', 'bugfix', 'feature', 'refactor', 'deploy'] as const;
+export type TaskCategory = EnumValues<typeof TASK_CATEGORIES>;
+
+/** Categories that execute without operator approval. */
+export const AUTO_SAFE_CATEGORIES = new Set<TaskCategory>(['docs', 'tests', 'research', 'refactor']);
+
+/** Categories that require approval before execution. */
+export const PROPOSED_CATEGORIES = new Set<TaskCategory>(['bugfix', 'feature']);
+
+/** Subset safe for PR automerge. */
+export const AUTOMERGE_SAFE_CATEGORIES = new Set<TaskCategory>(['docs', 'tests', 'research']);
+
+// ─── Narratives ─────────────────────────────────────────────
+
+export const MEMORY_GOAL_STATUSES = ['active', 'resolved', 'stalled', 'abandoned'] as const;
+export type MemoryGoalStatus = EnumValues<typeof MEMORY_GOAL_STATUSES>;
+
+// ─── Knowledge Graph ─────────────────────────────────────────
+
+export const NODE_TYPES = [
+  'concept', 'project', 'person', 'decision', 'pattern', 'tool', 'event',
+  'file', 'module', 'function', 'class', 'interface', 'type_alias',
+] as const;
+export type NodeType = EnumValues<typeof NODE_TYPES>;
+
+export const SOURCE_SYSTEMS = ['cognitive', 'code', 'manual'] as const;
+export type SourceSystem = EnumValues<typeof SOURCE_SYSTEMS>;
+
+export const EDGE_RELATIONS = ['depends_on', 'part_of', 'decided_by', 'blocks', 'uses', 'related_to', 'caused'] as const;
+export type EdgeRelation = EnumValues<typeof EDGE_RELATIONS>;
+
+// ─── Feedback ────────────────────────────────────────────────
+
+export const FEEDBACK_CATEGORIES = ['general', 'bug', 'feature', 'question'] as const;
+export type FeedbackCategory = EnumValues<typeof FEEDBACK_CATEGORIES>;
+
+export const FEEDBACK_SOURCES = ['web', 'mcp', 'api'] as const;
+export type FeedbackSource = EnumValues<typeof FEEDBACK_SOURCES>;
+
+// ─── Board ───────────────────────────────────────────────────
+
+export const BOARD_COLUMNS = ['backlog', 'queued', 'in_progress', 'blocked', 'shipped'] as const;
+export type BoardColumn = EnumValues<typeof BOARD_COLUMNS>;
+
+export const CONTENT_TYPES = ['issue', 'pr'] as const;
+export type ContentType = EnumValues<typeof CONTENT_TYPES>;
+
+// ─── Content Queue ───────────────────────────────────────────
+
+export const CONTENT_QUEUE_STATUSES = ['scheduled', 'published', 'failed', 'cancelled'] as const;
+export type ContentQueueStatus = EnumValues<typeof CONTENT_QUEUE_STATUSES>;
+
+// ─── Dynamic Tools ───────────────────────────────────────────
+
+export const TOOL_EXECUTORS = ['gpt_oss', 'workers_ai', 'groq'] as const;
+export type ToolExecutor = EnumValues<typeof TOOL_EXECUTORS>;
+
+export const TOOL_STATUSES = ['active', 'promoted', 'retired', 'draft'] as const;
+export type ToolStatus = EnumValues<typeof TOOL_STATUSES>;
+
+// ─── CodeBeast Findings ─────────────────────────────────────
+
+export const FINDING_SEVERITIES = ['HIGH', 'MID', 'LOW', 'INFO'] as const;
+export type FindingSeverity = EnumValues<typeof FINDING_SEVERITIES>;
+
+export const FINDING_CATEGORIES = ['SECURITY', 'LOGIC', 'STYLE', 'DEPENDENCY', 'BOUNDARY'] as const;
+export type FindingCategory = EnumValues<typeof FINDING_CATEGORIES>;
+
+export const FINDING_PRIORITIES = ['high', 'medium', 'low'] as const;
+export type FindingPriority = EnumValues<typeof FINDING_PRIORITIES>;
+
+export const FINDING_STATUSES = ['open', 'resolved'] as const;
+export type FindingStatus = EnumValues<typeof FINDING_STATUSES>;
+
+// ─── Validation Helpers ──────────────────────────────────────
+
+/** Check if a value is a valid member of a const enum array. */
+export function isValidEnum<T extends readonly string[]>(values: T, input: unknown): input is T[number] {
+  return typeof input === 'string' && (values as readonly string[]).includes(input);
+}
+
+/** Validate and return the value, or fall back to a default. */
+export function validateEnum<T extends readonly string[]>(
+  values: T,
+  input: unknown,
+  fallback: T[number],
+): T[number] {
+  return isValidEnum(values, input) ? input : fallback;
+}

package/src/search.ts

@@ -0,0 +1,112 @@
+// Fetch-based web search and URL fetching — no external SDK
+// Follows the same pattern as groq.ts
+
+import { operatorConfig } from './operator/index.js';
+
+// ─── Brave Search ────────────────────────────────────────────
+
+export interface SearchResult {
+  title: string;
+  url: string;
+  snippet: string;
+}
+
+export async function braveSearch(
+  apiKey: string,
+  query: string,
+  maxResults: number = 5,
+): Promise<SearchResult[]> {
+  const url = `https://api.search.brave.com/res/v1/web/search?q=${encodeURIComponent(query)}&count=${Math.min(maxResults, 10)}`;
+
+  let response: Response;
+  try {
+    response = await fetch(url, {
+      headers: {
+        'Accept': 'application/json',
+        'Accept-Encoding': 'gzip',
+        'X-Subscription-Token': apiKey,
+      },
+      signal: AbortSignal.timeout(10_000),
+    });
+  } catch (err) {
+    if (err instanceof DOMException && err.name === 'TimeoutError') {
+      console.warn('[search] Brave Search timed out after 10s');
+      return [];
+    }
+    throw err;
+  }
+
+  if (!response.ok) {
+    const errText = await response.text();
+    throw new Error(`Brave Search API error ${response.status}: ${errText}`);
+  }
+
+  const data = await response.json<{
+    web?: {
+      results?: Array<{
+        title: string;
+        url: string;
+        description?: string;
+        extra_snippets?: string[];
+      }>;
+    };
+  }>();
+
+  const results = data.web?.results ?? [];
+  return results.map(r => ({
+    title: r.title,
+    url: r.url,
+    snippet: r.description ?? r.extra_snippets?.[0] ?? '',
+  }));
+}
+
+// ─── URL Fetch + Text Extraction ─────────────────────────────
+
+const STRIP_TAGS = /<script[\s\S]*?<\/script>|<style[\s\S]*?<\/style>|<[^>]+>/gi;
+const COLLAPSE_WHITESPACE = /\s{2,}/g;
+
+export async function fetchUrlText(url: string, maxChars: number = 8000): Promise<string> {
+  let response: Response;
+  try {
+    response = await fetch(url, {
+      headers: {
+        'User-Agent': operatorConfig.userAgent,
+        'Accept': 'text/html,text/plain,application/json',
+      },
+      redirect: 'follow',
+      signal: AbortSignal.timeout(10_000),
+    });
+  } catch (err) {
+    if (err instanceof DOMException && err.name === 'TimeoutError') {
+      return `[Error: request to ${url} timed out after 10s]`;
+    }
+    throw err;
+  }
+
+  if (!response.ok) {
+    throw new Error(`HTTP ${response.status} fetching ${url}`);
+  }
+
+  const contentType = response.headers.get('content-type') ?? '';
+  const raw = await response.text();
+
+  let text: string;
+  if (contentType.includes('application/json')) {
+    // Prettify JSON for readability
+    try {
+      text = JSON.stringify(JSON.parse(raw), null, 2);
+    } catch {
+      text = raw;
+    }
+  } else {
+    // Strip HTML tags, collapse whitespace
+    text = raw
+      .replace(STRIP_TAGS, ' ')
+      .replace(COLLAPSE_WHITESPACE, ' ')
+      .trim();
+  }
+
+  return text.length > maxChars
+    ? text.slice(0, maxChars) + `\n\n[... truncated at ${maxChars} chars — full page is ${text.length} chars ...]`
+    : text;
+}