agentlife 1.0.0

package/index.ts

@@ -0,0 +1,1433 @@
+import type { OpenClawPluginApi, OpenClawConfig } from "openclaw/plugin-sdk";
+import * as fs from "node:fs/promises";
+import * as fsSync from "node:fs";
+import { createRequire } from "node:module";
+import * as os from "node:os";
+import * as path from "node:path";
+
+// -- SQLite helpers (node:sqlite, lazy-loaded) --------------------------------
+
+const nodeRequire = createRequire(import.meta.url);
+let sqliteModule: typeof import("node:sqlite") | null = null;
+
+function requireSqlite() {
+  if (sqliteModule) return sqliteModule;
+  sqliteModule = nodeRequire("node:sqlite") as typeof import("node:sqlite");
+  return sqliteModule;
+}
+
+// Per-agent DB connections (lazy, cached)
+const agentDbs = new Map<string, import("node:sqlite").DatabaseSync>();
+let dbBaseDir: string | null = null;
+
+function getOrCreateAgentDb(agentId: string) {
+  let db = agentDbs.get(agentId);
+  if (db) return db;
+  if (!dbBaseDir) throw new Error("DB base dir not initialized");
+  fsSync.mkdirSync(dbBaseDir, { recursive: true });
+  const { DatabaseSync } = requireSqlite();
+  db = new DatabaseSync(path.join(dbBaseDir, `${agentId}.db`));
+  agentDbs.set(agentId, db);
+  return db;
+}
+
+// Shared agentlife DB (for surface history)
+let historyDb: import("node:sqlite").DatabaseSync | null = null;
+let historyDbPath: string | null = null;
+
+function getOrCreateHistoryDb() {
+  if (historyDb) return historyDb;
+  if (!historyDbPath) throw new Error("History DB path not initialized");
+  fsSync.mkdirSync(path.dirname(historyDbPath), { recursive: true });
+  const { DatabaseSync } = requireSqlite();
+  historyDb = new DatabaseSync(historyDbPath);
+  historyDb.exec(`
+    CREATE TABLE IF NOT EXISTS surface_events (
+      id INTEGER PRIMARY KEY AUTOINCREMENT,
+      surfaceId TEXT NOT NULL,
+      agentId TEXT,
+      event TEXT NOT NULL,
+      dsl TEXT,
+      metadata TEXT,
+      createdAt INTEGER NOT NULL
+    );
+    CREATE INDEX IF NOT EXISTS idx_se_surface ON surface_events(surfaceId);
+    CREATE INDEX IF NOT EXISTS idx_se_agent ON surface_events(agentId);
+    CREATE INDEX IF NOT EXISTS idx_se_time ON surface_events(createdAt);
+  `);
+  return historyDb;
+}
+
+function recordSurfaceEvent(surfaceId: string, event: string, dsl?: string, agentId?: string) {
+  try {
+    getOrCreateHistoryDb()
+      .prepare("INSERT INTO surface_events (surfaceId,agentId,event,dsl,createdAt) VALUES (?,?,?,?,?)")
+      .run(surfaceId, agentId ?? null, event, dsl ?? null, Date.now());
+  } catch (err: any) {
+    console.warn("[agentlife] failed to record surface event:", err?.message);
+  }
+}
+
+/** Close all open DB connections — exported for test cleanup. */
+export function _closeAllDbs() {
+  for (const db of agentDbs.values()) {
+    try { db.close(); } catch {}
+  }
+  agentDbs.clear();
+  if (historyDb) {
+    try { historyDb.close(); } catch {}
+    historyDb = null;
+  }
+}
+
+// -- Surface persistence state ------------------------------------------------
+
+interface SurfaceMeta {
+  lines: string[];
+  createdAt: number;       // epoch ms
+  updatedAt: number;       // reset on any message for this surface
+  ttl?: string;            // "30m", "6h", "7d", "none" — from _ttl
+  expireAt?: string;       // ISO 8601 — from _expireAt
+  expireHint?: string;     // free text — from _expireHint
+  expiredSince?: number;   // epoch ms — set when first detected as expired
+}
+
+/** surfaceId -> SurfaceMeta (DSL lines + lifecycle). */
+const surfaceStore = new Map<string, SurfaceMeta>();
+
+/** Input-overlay surfaces — transient, never persisted. */
+const transientSurfaces = new Set<string>();
+
+/** Resolved path for surfaces.json (set on service start). */
+let surfacesFilePath: string | null = null;
+
+/** Debounce flag for disk writes. */
+let writeScheduled = false;
+
+// -- TTL parsing & expiry evaluation ------------------------------------------
+
+const TTL_PATTERN = /^(\d+)(m|h|d)$/;
+const DEFAULT_CEILING_MS = 7 * 24 * 60 * 60 * 1000; // 7 days
+const GRACE_PERIOD_MS = 24 * 60 * 60 * 1000;         // 24h
+
+function parseTtlMs(ttl: string): number | null {
+  const match = ttl.match(TTL_PATTERN);
+  if (!match) return null;
+  const value = parseInt(match[1], 10);
+  switch (match[2]) {
+    case "m": return value * 60 * 1000;
+    case "h": return value * 60 * 60 * 1000;
+    case "d": return value * 24 * 60 * 60 * 1000;
+    default: return null;
+  }
+}
+
+function isExpired(meta: SurfaceMeta, now: number = Date.now()): boolean {
+  // Explicit opt-out — never expires
+  if (meta.ttl === "none") return false;
+
+  // TTL set — check duration from updatedAt
+  if (meta.ttl) {
+    const ttlMs = parseTtlMs(meta.ttl);
+    if (ttlMs !== null && now - meta.updatedAt > ttlMs) return true;
+  }
+
+  // Absolute expiry
+  if (meta.expireAt) {
+    const expireMs = new Date(meta.expireAt).getTime();
+    if (!isNaN(expireMs) && now > expireMs) return true;
+  }
+
+  // Default ceiling — no lifecycle fields at all
+  if (!meta.ttl && !meta.expireAt && !meta.expireHint) {
+    if (now - meta.updatedAt > DEFAULT_CEILING_MS) return true;
+  }
+
+  return false;
+}
+
+/** True if the surface has been expired for longer than the 24h grace period. */
+function isPastGrace(meta: SurfaceMeta, now: number = Date.now()): boolean {
+  return !!meta.expiredSince && (now - meta.expiredSince > GRACE_PERIOD_MS);
+}
+
+/** Format a duration in ms as a human-readable string. */
+function formatAge(ms: number): string {
+  if (ms < 60_000) return "just now";
+  const minutes = Math.floor(ms / 60_000);
+  if (minutes < 60) return `${minutes}min ago`;
+  const hours = Math.floor(minutes / 60);
+  if (hours < 24) return `${hours}h ago`;
+  const days = Math.floor(hours / 24);
+  return `${days}d ago`;
+}
+
+// -- Disk I/O helpers ---------------------------------------------------------
+
+interface DiskFormat {
+  _version: 2;
+  surfaces: Record<string, {
+    lines: string[];
+    createdAt: number;
+    updatedAt: number;
+    ttl?: string;
+    expireAt?: string;
+    expireHint?: string;
+    expiredSince?: number;
+  }>;
+}
+
+async function loadFromDisk(): Promise<void> {
+  if (!surfacesFilePath) return;
+  try {
+    const raw = await fs.readFile(surfacesFilePath, "utf-8");
+    const data = JSON.parse(raw);
+    surfaceStore.clear();
+
+    const now = Date.now();
+
+    for (const [surfaceId, meta] of Object.entries(data.surfaces ?? {})) {
+      const m = meta as DiskFormat["surfaces"][string];
+      if (Array.isArray(m.lines) && m.lines.length > 0) {
+        surfaceStore.set(surfaceId, {
+          lines: m.lines,
+          createdAt: m.createdAt ?? now,
+          updatedAt: m.updatedAt ?? now,
+          ttl: m.ttl,
+          expireAt: m.expireAt,
+          expireHint: m.expireHint,
+          expiredSince: m.expiredSince,
+        });
+      }
+    }
+
+    // Hard purge — surfaces past 24h grace period
+    let purged = 0;
+    for (const [surfaceId, meta] of surfaceStore.entries()) {
+      if (isPastGrace(meta, now)) {
+        surfaceStore.delete(surfaceId);
+        recordSurfaceEvent(surfaceId, "expired");
+        purged++;
+      }
+    }
+
+    // Stamp expiredSince on any newly-expired surfaces (so 24h grace starts)
+    for (const [, meta] of surfaceStore.entries()) {
+      if (isExpired(meta, now) && !meta.expiredSince) {
+        meta.expiredSince = now;
+      }
+    }
+
+    console.log(
+      "[agentlife] loaded %d persisted surfaces from disk%s",
+      surfaceStore.size,
+      purged > 0 ? ` (purged ${purged} past grace period)` : "",
+    );
+  } catch (e: any) {
+    if (e?.code === "ENOENT") {
+      console.log("[agentlife] no persisted surfaces file, starting empty");
+    } else {
+      console.warn("[agentlife] failed to load surfaces from disk:", e?.message);
+    }
+    surfaceStore.clear();
+  }
+}
+
+async function saveToDisk(): Promise<void> {
+  if (!surfacesFilePath) return;
+  try {
+    const data: DiskFormat = { _version: 2, surfaces: {} };
+    for (const [surfaceId, meta] of surfaceStore.entries()) {
+      data.surfaces[surfaceId] = {
+        lines: meta.lines,
+        createdAt: meta.createdAt,
+        updatedAt: meta.updatedAt,
+        ...(meta.ttl !== undefined && { ttl: meta.ttl }),
+        ...(meta.expireAt !== undefined && { expireAt: meta.expireAt }),
+        ...(meta.expireHint !== undefined && { expireHint: meta.expireHint }),
+        ...(meta.expiredSince !== undefined && { expiredSince: meta.expiredSince }),
+      };
+    }
+    const dir = path.dirname(surfacesFilePath);
+    await fs.mkdir(dir, { recursive: true });
+    // Atomic write: temp file + rename
+    const tmp = surfacesFilePath + ".tmp";
+    await fs.writeFile(tmp, JSON.stringify(data, null, 2), "utf-8");
+    await fs.rename(tmp, surfacesFilePath);
+  } catch (e: any) {
+    console.warn("[agentlife] failed to save surfaces to disk:", e?.message);
+  }
+}
+
+function scheduleSave(): void {
+  if (writeScheduled) return;
+  writeScheduled = true;
+  setImmediate(() => {
+    writeScheduled = false;
+    saveToDisk();
+  });
+}
+
+// -- Agent registry (descriptions for orchestrator routing) -------------------
+
+interface AgentRegistryEntry {
+  name: string;
+  description: string;
+  model?: string;
+  createdAt: number;
+  needsEnrichment?: boolean;
+}
+
+/** agentId -> registry entry. */
+const agentRegistry = new Map<string, AgentRegistryEntry>();
+
+/** Resolved path for agent-registry.json (set on service start). */
+let registryFilePath: string | null = null;
+
+async function loadRegistryFromDisk(): Promise<void> {
+  if (!registryFilePath) return;
+  try {
+    const raw = await fs.readFile(registryFilePath, "utf-8");
+    const data = JSON.parse(raw);
+    agentRegistry.clear();
+    for (const [id, entry] of Object.entries(data.agents ?? {})) {
+      const e = entry as AgentRegistryEntry;
+      if (e.description) {
+        agentRegistry.set(id, {
+          name: e.name ?? id,
+          description: e.description,
+          model: e.model,
+          createdAt: e.createdAt ?? Date.now(),
+          needsEnrichment: e.needsEnrichment,
+        });
+      }
+    }
+    console.log("[agentlife] loaded %d agents from registry", agentRegistry.size);
+  } catch (e: any) {
+    if (e?.code === "ENOENT") {
+      console.log("[agentlife] no agent registry file, starting empty");
+    } else {
+      console.warn("[agentlife] failed to load agent registry:", e?.message);
+    }
+    agentRegistry.clear();
+  }
+}
+
+async function saveRegistryToDisk(): Promise<void> {
+  if (!registryFilePath) return;
+  try {
+    const data: { _version: 1; agents: Record<string, AgentRegistryEntry> } = {
+      _version: 1,
+      agents: {},
+    };
+    for (const [id, entry] of agentRegistry.entries()) {
+      data.agents[id] = entry;
+    }
+    const dir = path.dirname(registryFilePath);
+    await fs.mkdir(dir, { recursive: true });
+    const tmp = registryFilePath + ".tmp";
+    await fs.writeFile(tmp, JSON.stringify(data, null, 2), "utf-8");
+    await fs.rename(tmp, registryFilePath);
+  } catch (e: any) {
+    console.warn("[agentlife] failed to save agent registry:", e?.message);
+  }
+}
+
+/** Build a text block listing all registered agents for orchestrator bootstrap. */
+function buildAgentRegistryContext(): string | null {
+  if (agentRegistry.size === 0) return null;
+  const lines: string[] = ["## Available Agents", ""];
+  for (const [id, entry] of agentRegistry.entries()) {
+    lines.push(`- **${entry.name}** (id: ${id}) — ${entry.description}`);
+  }
+  lines.push("");
+  lines.push("Route to agents by matching user intent to these descriptions.");
+  lines.push("If no registered agent matches, fall back to agents_list to discover unregistered agents.");
+  return lines.join("\n");
+}
+
+// -- CardDSL processing (opaque storage + regex metadata) ---------------------
+
+function processDslBlock(dsl: string): void {
+  const now = Date.now();
+  // Split by --- separator
+  const blocks = dsl.split(/\n---(?:\n|$)/).filter((b) => b.trim().length > 0);
+
+  for (const block of blocks) {
+    const firstLine = block.trim().split("\n")[0]?.trim() ?? "";
+
+    // Handle delete command
+    if (firstLine.startsWith("delete ")) {
+      const sid = firstLine.slice(7).trim();
+      if (sid) {
+        surfaceStore.delete(sid);
+        transientSurfaces.delete(sid);
+        recordSurfaceEvent(sid, "deleted");
+      }
+      continue;
+    }
+
+    // Extract surfaceId: "surface <id> [overlay]"
+    const surfaceMatch = block.match(/^surface\s+(\S+)/m);
+    if (!surfaceMatch) continue;
+    const sid = surfaceMatch[1];
+
+    // Check for overlay — transient, don't persist
+    const headerLine = block.match(/^surface\s+.*/m)?.[0] ?? "";
+    if (/\boverlay\b/.test(headerLine)) {
+      transientSurfaces.add(sid);
+      continue;
+    }
+    transientSurfaces.delete(sid);
+
+    // Extract lifecycle metadata via regex
+    const ttlMatch = block.match(/^\s*ttl:\s*(.+)/m);
+    const expireAtMatch = block.match(/^\s*expireAt:\s*(.+)/m);
+    const expireHintMatch = block.match(/^\s*expireHint:\s*(.+)/m);
+
+    const existing = surfaceStore.get(sid);
+    surfaceStore.set(sid, {
+      lines: block.split("\n"),
+      createdAt: existing?.createdAt ?? now,
+      updatedAt: now,
+      ttl: ttlMatch?.[1]?.trim() ?? existing?.ttl,
+      expireAt: expireAtMatch?.[1]?.trim() ?? existing?.expireAt,
+      expireHint: expireHintMatch?.[1]?.trim() ?? existing?.expireHint,
+      expiredSince: undefined,
+    });
+    recordSurfaceEvent(sid, existing ? "updated" : "created", block);
+  }
+}
+
+// -- Dashboard state context builder ------------------------------------------
+
+/** Extract title and detail from stored DSL lines. */
+function extractTitleAndDetail(meta: SurfaceMeta): { title: string | null; detail: string | null } {
+  let title: string | null = null;
+  let detail: string | null = null;
+  const fullText = meta.lines.join("\n");
+
+  // DSL: extract title from `text "..." h3` or `text "..." h4`
+  const titleMatch = fullText.match(/text\s+"([^"]+)"\s+h[34]/);
+  if (titleMatch) title = titleMatch[1];
+
+  // DSL: extract detail (inline or multiline block)
+  const inlineDetail = fullText.match(/^\s*detail:\s*(.+)/m);
+  if (inlineDetail && inlineDetail[1].trim().length > 0) {
+    detail = inlineDetail[1].trim().replace(/^"|"$/g, "");
+  } else {
+    // Multi-line detail block
+    const detailBlockMatch = fullText.match(/^\s*detail:\s*\n((?:\s+.+\n?)+)/m);
+    if (detailBlockMatch) {
+      detail = detailBlockMatch[1].replace(/^ {2,4}/gm, "").trim();
+    }
+  }
+
+  return { title, detail };
+}
+
+/**
+ * Build a text block describing the current dashboard state for agent bootstrap.
+ * Includes age, lifecycle metadata, and EXPIRED flags for agent decision-making.
+ */
+function buildDashboardStateContext(): string | null {
+  const now = Date.now();
+
+  // Count non-expired surfaces to detect empty dashboard
+  let hasActiveSurfaces = false;
+  for (const [, meta] of surfaceStore.entries()) {
+    if (!isExpired(meta, now)) {
+      hasActiveSurfaces = true;
+      break;
+    }
+  }
+
+  if (surfaceStore.size === 0 || !hasActiveSurfaces) {
+    // Build empty dashboard context — may still have expired entries to show
+    let result = `## Dashboard is Empty\n\nThe user's dashboard has no active cards. Push 3-4 personalized suggestion cards based on what you know about the user — their interests, location, routine, or recent topics.\n\nEach suggestion = a compact card with size=s (h3 title + body one-liner + action button). Use a descriptive surfaceId per topic. Set ttl: none so suggestions persist until activated.\nWhen the user taps a suggestion button, replace that card (same surfaceId) with real data and set an appropriate ttl.\n`;
+
+    // Still show expired cards so agent can decide whether to refresh
+    if (surfaceStore.size > 0) {
+      const expiredEntries: string[] = [];
+      for (const [surfaceId, meta] of surfaceStore.entries()) {
+        const { title } = extractTitleAndDetail(meta);
+        if (isExpired(meta, now) && !meta.expiredSince) {
+          meta.expiredSince = now;
+        }
+        expiredEntries.push(`[${surfaceId}] ${title ?? surfaceId} (updated ${formatAge(now - meta.updatedAt)}, EXPIRED)`);
+      }
+      if (expiredEntries.length > 0) {
+        result += `\n### Recently Expired\n\n${expiredEntries.join("\n")}`;
+      }
+    }
+
+    return result;
+  }
+
+  const activeEntries: string[] = [];
+  const expiredEntries: string[] = [];
+
+  for (const [surfaceId, meta] of surfaceStore.entries()) {
+    const { title, detail } = extractTitleAndDetail(meta);
+
+    const label = title ?? surfaceId;
+    const age = formatAge(now - meta.updatedAt);
+    const expired = isExpired(meta, now);
+
+    // Stamp expiredSince on first detection
+    if (expired && !meta.expiredSince) {
+      meta.expiredSince = now;
+    }
+
+    // Build lifecycle annotation
+    const parts: string[] = [`updated ${age}`];
+    if (meta.ttl === "none") {
+      parts.push("persistent");
+    } else if (meta.ttl) {
+      parts.push(`ttl: ${meta.ttl}`);
+    }
+    if (meta.expireAt) {
+      parts.push(`expires: ${meta.expireAt}`);
+    }
+    if (!meta.ttl && !meta.expireAt && !meta.expireHint) {
+      parts.push("default 7d ceiling");
+    }
+    if (expired) {
+      parts.push("EXPIRED");
+    }
+
+    const headerLine = meta.lines.find(l => l.trim().startsWith("surface ")) ?? "";
+    const sizeMatch = headerLine.match(/\bsize=(\w+)/);
+    if (sizeMatch) parts.push(`size=${sizeMatch[1]}`);
+    const priorityMatch = headerLine.match(/\bpriority=(\w+)/);
+    if (priorityMatch) parts.push(`priority=${priorityMatch[1]}`);
+
+    let entry = `[${surfaceId}] ${label} (${parts.join(", ")})`;
+    if (meta.expireHint) {
+      entry += `\n  hint: ${meta.expireHint}`;
+    }
+    if (detail) {
+      const truncated = detail.length > 500 ? detail.slice(0, 500) + "..." : detail;
+      entry += `\n  detail: ${truncated}`;
+    }
+
+    if (expired) {
+      expiredEntries.push(entry);
+    } else {
+      activeEntries.push(entry);
+    }
+  }
+
+  if (activeEntries.length === 0 && expiredEntries.length === 0) return null;
+
+  let result = `## Current Dashboard State\n\nThese cards are on the user's dashboard. Use stored details for follow-up — do not re-fetch data you already have.\n`;
+
+  if (activeEntries.length > 0) {
+    result += `\n### Active Cards\n\n${activeEntries.join("\n\n")}`;
+  }
+
+  if (expiredEntries.length > 0) {
+    result += `\n\n### Expired Cards (delete or refresh)\n\n${expiredEntries.join("\n\n")}`;
+  }
+
+  return result;
+}
+
+// -- Agent guidance -----------------------------------------------------------
+
+// Injected once per session via agent:bootstrap — not per turn.
+const TENAZITAS_GUIDANCE = `\
+## Agent Life Dashboard
+
+**CRITICAL — call canvas with action="a2ui_push", pass WidgetDSL in jsonl. ONLY WidgetDSL (indented plaintext). NEVER JSON.**
+
+**Users CANNOT read chat. They only see widgets. Reply "done" in chat.**
+**detail: is MANDATORY — it IS your full response. The widget face is just the headline.**
+**First reply: push a loading widget (same surfaceId you will use for the result).**
+
+## Widget Rules
+
+A widget is a glanceable surface — like a phone home screen widget. Compact, visual, informative. It is the entry point to the detail panel.
+
+Widget face: structured components only (metric, progress, sparkline, icon+text rows). Text components limited to title (h3/h4) and one-line captions. If you are generating prose, it goes in detail:, not on the widget face.
+
+detail: is the full response. Everything you would have said in chat goes here as markdown. Users tap the widget to read it.
+
+## Size and Priority
+
+On the surface line, set size and priority:
+  size=s — compact (~120dp): single metric, status, title+subtitle
+  size=m — standard (~200dp): weather summary, comparison verdict, progress with context
+  size=l — tall (~320dp): sparkline chart, short list, multi-section layout
+
+  priority=high — floats to top of dashboard
+  priority=normal — default
+  priority=low — sinks to bottom
+
+Pick the smallest size that fits. Default is size=m priority=normal.
+
+## Core Rules (MUST follow)
+
+1. ONE request = ONE widget. Never split into multiple.
+2. Loading and result widget MUST use the same surfaceId.
+3. ALWAYS set size= on every surface.
+4. Widget face: visual components only. No text walls. No paragraphs.
+5. detail: is MANDATORY for all non-trivial content.
+
+## WidgetDSL Structure
+
+surface <id> starts each widget. Children indented 2 spaces. Every widget: card > column > content. Metadata after the component tree.
+
+## WidgetDSL Reference
+
+Components: text, row, column, card, button, image, icon, divider,
+            textfield "Label" type=email, checkbox "Label" checked,
+            metric "Label" "Value" trend=up|down|flat,
+            sparkline [1,2,3] height=60 color=#hex filled,
+            progress value=0.7 "Loading" color=#hex
+
+Text hints: h1 h2 h3 h4 h5 body caption
+Row/column props: distribute=spaceBetween|spaceAround|center align=center|start|end
+Button: action=<name> primary (optional)
+Surface: surface <id> size=s|m|l priority=high|normal|low
+Overlay: surface <id> overlay
+Delete: delete <id>
+Separate multiple surfaces with ---
+Meta: detail: (inline or indented block), ttl:, expireAt:, expireHint:
+
+## Widget Lifecycle
+
+Set lifecycle so the dashboard stays fresh:
+  ttl: "30m", "1h", "6h", "7d", "none" (persistent)
+  expireAt: ISO 8601 absolute deadline
+  expireHint: free-text reason
+Widgets without lifecycle expire after 7 days. At session start, review EXPIRED widgets — delete stale, refresh useful.
+
+## Suggestion Widgets
+
+When asked to suggest: push 3-4 compact widgets (size=s each) with title + one-liner + action button. Set ttl: none.
+On tap, replace with real data (same surfaceId) and set appropriate ttl.
+
+## Interactive Input Overlay
+
+When you cannot complete a task because you need information from the user, ALWAYS use an overlay — never ask questions in a regular widget or chat text. Regular widgets are for results, overlays are for questions.
+
+Render an overlay above the input box: surface <id> overlay
+
+Rules:
+  1. One question at a time — break multi-field input into steps
+  2. Buttons ONLY — no textfield in overlays. Offer common presets as buttons.
+     For free-form input, show buttons for presets + a "Custom" button that tells the user to type in the input bar.
+  3. Replace, don't append — each step replaces the previous overlay (same surfaceId or delete + create)
+  4. Delete when done — remove overlay after collecting all needed info
+  5. Result goes in a dashboard widget, not the overlay
+
+## Delegation Policy
+
+When you receive a message via sessions_send (delegated from the orchestrator):
+Do the work yourself and push a dashboard widget with the result. Do NOT re-delegate via sessions_spawn — the orchestrator already chose you as the executor. Sub-agents cannot push dashboard widgets, so re-delegating wastes cost and time with no benefit.
+
+## Ping-Pong Steps
+
+If you receive an "Agent-to-agent reply step" message, always reply exactly: REPLY_SKIP
+Your work is done — you already pushed a widget. No back-and-forth needed.
+
+## Agent Database (SQLite)
+
+Private SQLite for structured data. Use instead of markdown for queries.
+
+Methods:
+  agentlife.db.exec  — { agentId, sql, params }
+  agentlife.db.query — { agentId, sql, params }
+
+Rules: CREATE TABLE IF NOT EXISTS, use params array, max 1000 rows, persists across sessions.
+`;
+
+// -- Provisioned agent instructions -------------------------------------------
+
+const ORCHESTRATOR_AGENTS_MD = `\
+# AgentLife Orchestrator
+
+You are a message router. You never answer questions, perform tasks, or produce content.
+Your job: understand what the user wants → route the message to the right agent.
+
+## Rules
+
+1. Never answer directly. Never use exec, read, write, web, or any content-producing tool. You ONLY use sessions_send and subagents.
+2. Never use the canvas tool. Specialist agents own their UI.
+3. Every user message gets routed to an agent. No exceptions.
+4. Keep your text output to one short sentence.
+
+## Agent Discovery
+
+Your bootstrap context includes AGENT_REGISTRY.md with all registered agents and their
+descriptions. Use these descriptions to match user intent — not just agent names.
+
+If a request doesn't match any registered agent, fall back to \`agents_list\` to discover
+agents created outside the builder (they won't have descriptions — route by name).
+
+## Routing Flow
+
+1. Read your AGENT_REGISTRY.md context. Match the user's intent to agent descriptions.
+2. Decide WHO gets this message — one agent or multiple:
+   - Single domain → one agent
+   - Crosses multiple domains → fan-out to ALL relevant agents in parallel
+3. Deliver via \`sessions_send\` to sessionKey "agent:{agentId}:main" with **timeoutSeconds: 0** (fire-and-forget).
+   The agent pushes a widget to the dashboard automatically. Do not wait.
+   Never use \`sessions_spawn\` unless the user explicitly asks for a new/fresh thread.
+
+## Critical: No Retries
+
+- timeoutSeconds: 0 means you always get status "accepted". There is no timeout.
+- NEVER send the same request to a second agent. One intent = one agent. It WILL process.
+- If sessions_send returns error/forbidden: respond "Cannot reach [agent name]." Do NOT try another agent.
+
+## Multi-Agent Fan-Out
+
+When a message is relevant to multiple agents, send to ALL of them in parallel.
+Each agent processes through its own lens and renders its own card.
+The user gets multiple perspectives from a single input.
+
+## Agent Selection
+
+- Match by description, not just names.
+- When fan-out applies, send to every relevant agent — don't pick just one.
+- If only one agent exists (besides agentlife and agentlife-builder), route everything there.
+- If the user asks to create, modify, or improve an agent → route to "agentlife-builder".
+  Always use sessions_send to agent:agentlife-builder:main (context continuity matters).
+
+## Edge Cases
+
+- No agents in registry AND no agents in agents_list: you ARE the assistant. Handle the user's message directly. Use all available tools (exec, read, write, web search, etc.). Push dashboard widgets via canvas a2ui_push. Do NOT say "no agents configured" or suggest building agents unless the user explicitly asks about agents.
+- sessions_send returns error/forbidden: respond "Cannot reach [agent name]." Do NOT retry with a different agent.
+- No matching agent for the intent: route to the closest match anyway. Every agent can handle unexpected requests better than you can.
+
+## Ping-Pong Steps
+
+If you receive an "Agent-to-agent reply step" message, always reply exactly: REPLY_SKIP
+You are a router — you have nothing to add in back-and-forth exchanges.
+
+## What You Are Not
+
+- Not a chatbot — no greetings, no small talk
+- Not a formatter — do not restructure specialist output
+- Not a gatekeeper — do not refuse or moderate requests
+`;
+
+const BUILDER_AGENTS_MD = `\
+# AgentLife Builder
+
+You are an expert at creating and improving OpenClaw agents. When the user needs a new
+specialist agent or wants to improve an existing one, you design and build it.
+
+## What You Build
+
+Each agent is defined by:
+1. **Workspace directory** — \`~/.openclaw/workspace-{agentId}/\`
+2. **AGENTS.md** — the agent's core instructions (identity, rules, behavior)
+3. **Config entry** — registered via the \`agentlife.createAgent\` gateway method
+
+Optional workspace files: SOUL.md (personality/tone), TOOLS.md (tool notes, API keys, SSH details).
+
+## Creating a New Agent
+
+### Step 1: Understand the Need — Use Interactive Overlays
+
+NEVER ask multiple questions in text. Use the canvas overlay to ask ONE question at a time
+with button choices. Each step replaces the previous overlay (same surfaceId).
+
+Flow for gathering requirements:
+
+1. Push an overlay asking the first question (e.g., "What should this agent focus on?")
+   with 2-4 button options. Example:
+
+   canvas action=a2ui_push jsonl:
+   surface builder-q overlay
+     card
+       column
+         text "What should this agent focus on?" h4
+         row distribute=spaceAround
+           button "Research" action=focus-research
+           button "Automation" action=focus-automation
+           button "Analysis" action=focus-analysis
+
+2. When the user taps a button (you receive "[action:focus-research] surfaceId=builder-q"),
+   push the NEXT question as a new overlay (same surfaceId "builder-q" — it replaces).
+
+3. Ask 2-4 questions total. Typical sequence:
+   Q1: What domain/focus? (buttons)
+   Q2: What tools/APIs needed? (buttons)
+   Q3: How should it output results? (buttons: "Dashboard cards" / "Text" / "Both")
+   Q4: Any specific requirements? (let user type in the input bar — delete the overlay first)
+
+4. When you have enough info, delete the overlay and proceed to build:
+   canvas action=a2ui_push jsonl:
+   delete builder-q
+
+NEVER dump a numbered list of questions in text. NEVER ask more than one question per overlay.
+The user interacts via buttons, not by typing answers to a text list.
+
+### Step 2: Create Workspace
+Use exec to create the directory:
+  mkdir -p ~/.openclaw/workspace-{agentId}
+
+### Step 3: Write AGENTS.md
+This is the most important file. Write precise, actionable instructions:
+- Clear role definition (what the agent does and doesn't do)
+- Specific tool usage patterns (when to use which tools, in what order)
+- Output format constraints (especially for canvas/a2ui if the dashboard is connected)
+- Error recovery patterns
+- Edge case handling
+
+Keep it under 4000 characters. Concise instructions outperform verbose ones.
+
+### Step 4: Register the Agent
+Call the gateway tool with method "agentlife.createAgent" and params:
+  {"id": "{agentId}", "name": "Display Name", "model": "{model}", "workspace": "/full/path/to/workspace", "description": "One sentence describing what this agent does and what domains it covers"}
+
+The workspace param must be the full absolute path (use $HOME, not ~).
+The description is critical — the orchestrator uses it to route messages. Be specific about
+what domains, topics, and data types the agent handles. Example:
+  "Tracks sleep, exercise, and nutrition. Logs data points, shows trends, flags health concerns."
+
+### Step 5: Confirm via Dashboard Widget
+Push a confirmation widget (not text) showing the new agent is ready:
+
+  surface agent-created w=6
+    card
+      column
+        text "{Agent Name} is ready" h3
+        text "Model: {model} · ID: {agentId}" caption
+        button "Try it now" action=try-agent primary
+  detail: Created agent "{agentId}" with workspace at ~/.openclaw/workspace-{agentId}. The orchestrator will automatically route matching requests to this agent. You can start using it immediately.
+
+## Writing Effective AGENTS.md
+
+1. **Be specific, not generic.** "Search flights on Google Flights" > "Help with travel."
+2. **Define boundaries.** What the agent does NOT do matters as much as what it does.
+3. **Tool-first thinking.** Write instructions around available tools, not abstract behaviors.
+4. **Output format matters.** If rendering dashboard cards, specify the exact DSL format.
+5. **Error paths.** What should the agent do when things fail?
+6. **No fluff.** Cut every word that doesn't change behavior.
+
+## Agent Database
+
+Agents can store structured data in a private SQLite database via gateway methods
+(agentlife.db.exec, agentlife.db.query). When building agents that track data over time,
+include schema design in their AGENTS.md.
+
+## Registry Enrichment
+
+When you receive an enrichment request (message containing "Enrich agent registry descriptions"),
+this is a system task — not a user request. Do NOT push any dashboard widgets or overlays.
+
+For each agent ID listed:
+1. Call agents_list to find the agent's workspace path
+2. Read SOUL.md from the workspace — this defines who the agent is
+3. Read AGENTS.md from the workspace — this defines what the agent does
+4. Write a one-sentence description that captures:
+   - What domains/topics the agent handles
+   - What actions it performs (tracks, monitors, analyzes, etc.)
+   - What data types it works with
+   Example: "Tracks sleep, exercise, and nutrition. Logs data points, shows trends, flags health concerns."
+5. Call the gateway tool with method "agentlife.createAgent" and params:
+   {"id": "{agentId}", "name": "{name}", "workspace": "{workspace}", "description": "{your description}"}
+
+Rules:
+- One sentence max per description. No fluff.
+- Be specific — the orchestrator uses descriptions to route messages, so vague = misrouted.
+- Process all agents, then respond with "Done" (no widget needed).
+
+## Improving Existing Agents
+
+When asked to improve an agent:
+1. Read the current AGENTS.md from its workspace (check agents_list for the id, workspace is at ~/.openclaw/workspace-{id}/)
+2. Understand what's working and what's not
+3. Make targeted edits — don't rewrite from scratch unless fundamentally broken
+4. Write the updated AGENTS.md back
+
+## What You Are Not
+
+- Not an orchestrator — you don't route messages or manage sessions
+- Not a general assistant — you only handle agent creation and improvement
+- When done building, tell the user the agent is ready to use
+`;
+
+// -- Provisioning helpers -----------------------------------------------------
+
+interface ProvisionedAgent {
+  id: string;
+  name: string;
+  isDefault?: boolean;
+  agentsMd: string;
+  subagents?: { allowAgents: string[] };
+}
+
+const PROVISIONED_AGENTS: ProvisionedAgent[] = [
+  {
+    id: "agentlife",
+    name: "AgentLife",
+    isDefault: true,
+    agentsMd: ORCHESTRATOR_AGENTS_MD,
+    subagents: { allowAgents: ["*"] },
+  },
+  {
+    id: "agentlife-builder",
+    name: "AgentLife Builder",
+    agentsMd: BUILDER_AGENTS_MD,
+  },
+];
+
+interface ProvisionRuntime {
+  config: { loadConfig: () => OpenClawConfig; writeConfigFile: (cfg: OpenClawConfig) => Promise<void> };
+  system?: { runCommandWithTimeout: (argv: string[], opts: { timeoutMs: number }) => Promise<unknown> };
+}
+
+/** Reject descriptions that are too short, repeat the name/id, or are boilerplate. */
+function isUsableDescription(desc: string, id: string, name: string): boolean {
+  const d = desc.toLowerCase().replace(/[^a-z0-9\s]/g, "").trim();
+  if (d.length < 20) return false;
+  if (d === id.toLowerCase() || d === name.toLowerCase()) return false;
+  return true;
+}
+
+interface EnrichmentTarget {
+  id: string;
+  name: string;
+  workspace: string;
+  model?: string;
+  soulMd: string;
+  agentsMd: string;
+}
+
+function scheduleEnrichment(
+  runtime: ProvisionRuntime,
+  targets: EnrichmentTarget[],
+  log: (msg: string) => void,
+): void {
+  if (!runtime.system?.runCommandWithTimeout) {
+    log("[agentlife] enrichment skipped — runtime.system not available");
+    return;
+  }
+
+  const run = runtime.system.runCommandWithTimeout;
+  // Delay 5s to ensure gateway is fully ready
+  setTimeout(async () => {
+    log(`[agentlife] starting registry enrichment for ${targets.length} agents`);
+    const promises = targets.map(async (t) => {
+      const msg = [
+        `Write a one-sentence description for agent "${t.name}" (id: ${t.id}).`,
+        `The description must capture what domains/topics the agent handles and what actions it performs.`,
+        `Reply with ONLY the description sentence — no preamble, no quotes, no explanation.`,
+        ``,
+        `SOUL.md:`,
+        "```",
+        t.soulMd || "(empty)",
+        "```",
+        ``,
+        `AGENTS.md:`,
+        "```",
+        t.agentsMd || "(empty)",
+        "```",
+      ].join("\n");
+
+      try {
+        const result = await run(
+          ["openclaw", "agent", "--agent", "agentlife-builder", "--message", msg, "--json"],
+          { timeoutMs: 60_000 },
+        ) as { stdout?: string; stderr?: string };
+        const stdout = result?.stdout ?? "";
+
+        // Parse JSON output: { result: { payloads: [{ text: "..." }] } }
+        let description = "";
+        try {
+          const json = JSON.parse(stdout);
+          const payloads = json?.result?.payloads as { text?: string }[] | undefined;
+          if (Array.isArray(payloads)) {
+            description = payloads.map((p) => p.text ?? "").join(" ").trim();
+          }
+        } catch {}
+
+        if (description && isUsableDescription(description, t.id, t.name)) {
+          agentRegistry.set(t.id, {
+            name: t.name,
+            description,
+            model: t.model,
+            createdAt: agentRegistry.get(t.id)?.createdAt ?? Date.now(),
+          });
+          await saveRegistryToDisk();
+          log(`[agentlife] enriched ${t.id}: ${description}`);
+        } else {
+          log(`[agentlife] enrichment for ${t.id} produced unusable description: ${description || "(empty)"}`);
+        }
+      } catch (err: any) {
+        log(`[agentlife] enrichment failed for ${t.id} (non-critical): ${err?.message}`);
+      }
+    });
+    await Promise.all(promises);
+    log("[agentlife] enrichment complete");
+  }, 5000);
+}
+
+async function provisionAgents(
+  cfg: OpenClawConfig,
+  runtime: ProvisionRuntime,
+  log: (msg: string) => void,
+): Promise<void> {
+  const home = os.homedir();
+  const currentList = [...(cfg.agents?.list ?? [])];
+  let configChanged = false;
+
+  for (const agent of PROVISIONED_AGENTS) {
+    const workspaceDir = path.join(home, ".openclaw", `workspace-${agent.id}`);
+
+    // Always create workspace + overwrite AGENTS.md (infrastructure, not user content)
+    await fs.mkdir(workspaceDir, { recursive: true });
+    await fs.writeFile(path.join(workspaceDir, "AGENTS.md"), agent.agentsMd, "utf-8");
+
+    // Write empty stubs for files we don't need — prevents OpenClaw core from
+    // seeding them with template boilerplate (ensureAgentWorkspace uses wx flag,
+    // so existing files are never overwritten). Saves ~5KB of wasted tokens.
+    const stubs = ["SOUL.md", "TOOLS.md", "IDENTITY.md", "USER.md", "HEARTBEAT.md", "BOOTSTRAP.md"];
+    for (const stub of stubs) {
+      const stubPath = path.join(workspaceDir, stub);
+      await fs.writeFile(stubPath, "", { encoding: "utf-8", flag: "wx" }).catch(() => {});
+    }
+
+    // Add to config if missing — don't touch existing entries (preserves user's model choice)
+    const exists = currentList.some((a: any) => a.id === agent.id);
+    if (!exists) {
+      const entry: Record<string, unknown> = {
+        id: agent.id,
+        name: agent.name,
+        workspace: workspaceDir,
+      };
+      if (agent.isDefault) entry.default = true;
+      if (agent.subagents) entry.subagents = agent.subagents;
+
+      if (agent.isDefault) {
+        // Prepend so orchestrator is the first default agent
+        currentList.unshift(entry as any);
+      } else {
+        currentList.push(entry as any);
+      }
+      configChanged = true;
+      log(`[agentlife] provisioned agent: ${agent.id}`);
+    }
+  }
+
+  if (configChanged) {
+    const updatedCfg: OpenClawConfig = {
+      ...cfg,
+      agents: {
+        ...cfg.agents,
+        list: currentList,
+      },
+    };
+    await runtime.config.writeConfigFile(updatedCfg);
+    log("[agentlife] config updated with provisioned agents");
+  }
+
+  // Seed registry from existing agents — so the orchestrator can route on first boot.
+  const SKIP_IDS = new Set(PROVISIONED_AGENTS.map((a) => a.id));
+  const finalList = runtime.config.loadConfig().agents?.list ?? currentList;
+  let seeded = 0;
+
+  for (const agent of finalList as any[]) {
+    const id = agent?.id;
+    if (!id || SKIP_IDS.has(id) || agentRegistry.has(id)) continue;
+
+    const name = (agent.name as string) || id;
+    agentRegistry.set(id, {
+      name,
+      description: name,
+      model: (agent.model as string) || undefined,
+      createdAt: Date.now(),
+      needsEnrichment: true,
+    });
+    seeded++;
+  }
+
+  if (seeded > 0) {
+    await saveRegistryToDisk();
+    log(`[agentlife] seeded registry with ${seeded} existing agents`);
+  }
+
+  // Collect enrichment targets — read workspace files for each needsEnrichment agent.
+  const enrichTargets: EnrichmentTarget[] = [];
+  for (const [id, entry] of agentRegistry.entries()) {
+    if (!entry.needsEnrichment) continue;
+    const agent = (finalList as any[]).find((a: any) => a?.id === id);
+    const workspace = (agent?.workspace as string) || "";
+    let soulMd = "";
+    let agentsMd = "";
+    if (workspace) {
+      try { soulMd = await fs.readFile(path.join(workspace, "SOUL.md"), "utf-8"); } catch {}
+      try { agentsMd = await fs.readFile(path.join(workspace, "AGENTS.md"), "utf-8"); } catch {}
+    }
+    enrichTargets.push({ id, name: entry.name, workspace, model: entry.model, soulMd, agentsMd });
+  }
+  if (enrichTargets.length > 0) {
+    scheduleEnrichment(runtime, enrichTargets, log);
+  }
+
+  log("[agentlife] agent provisioning complete");
+}
+
+type BootstrapFile = { name: string; path: string; content: string; missing: boolean };
+
+// Last injected snapshot — exposed via gateway method for debugging.
+let lastBootstrapSnapshot: BootstrapFile[] = [];
+
+export default function register(api: OpenClawPluginApi) {
+  // -- Service: load persisted surfaces on gateway start ----------------------
+  api.registerService({
+    id: "agentlife-surfaces",
+    start: async (ctx: any) => {
+      const agentlifeDir = path.join(ctx.stateDir, "agentlife");
+      surfacesFilePath = path.join(agentlifeDir, "surfaces.json");
+      registryFilePath = path.join(agentlifeDir, "agent-registry.json");
+      dbBaseDir = path.join(agentlifeDir, "db");
+      historyDbPath = path.join(agentlifeDir, "agentlife.db");
+      await loadFromDisk();
+      await loadRegistryFromDisk();
+      console.log("[agentlife] surface persistence service started (file: %s)", surfacesFilePath);
+    },
+  });
+
+  // -- Service: provision orchestrator + builder agents on startup -------------
+  api.registerService({
+    id: "agentlife-provisioning",
+    start: async () => {
+      const cfg = api.runtime.config.loadConfig();
+      await provisionAgents(cfg, api.runtime, console.log);
+    },
+  });
+
+  // -- Service: show pairing QR on first run (no paired Agent Life devices) ----
+  api.registerService({
+    id: "agentlife-pairing-qr",
+    start: async (ctx: any) => {
+      try {
+        const cfg = api.runtime.config.loadConfig();
+        // Build setup code from gateway config
+        const bind = cfg.gateway?.bind ?? "loopback";
+        const port = cfg.gateway?.port ?? 18789;
+        const token = cfg.gateway?.auth?.token;
+        if (!token) return;
+
+        let host: string;
+        if (bind === "lan" || bind === "auto" || bind === "custom") {
+          const nets = os.networkInterfaces();
+          const lanIp = Object.values(nets).flat()
+            .find((n: any) => n && !n.internal && n.family === "IPv4")?.address;
+          host = lanIp ?? "127.0.0.1";
+        } else {
+          host = "127.0.0.1";
+        }
+
+        const payload = JSON.stringify({ url: `ws://${host}:${port}`, token });
+        const setupCode = Buffer.from(payload).toString("base64");
+
+        // Render QR in terminal — resolve qrcode-terminal from openclaw's deps
+        let qrTerminal: any = null;
+        try {
+          const realPath = fsSync.realpathSync(process.argv[1] || "");
+          const mainRequire = createRequire(realPath);
+          qrTerminal = mainRequire("qrcode-terminal");
+        } catch { /* not found */ }
+
+        console.log("\n\x1b[36m[agentlife]\x1b[0m \x1b[1mPairing QR\x1b[0m");
+        console.log("Scan this with the Agent Life mobile app to connect.\n");
+        if (qrTerminal?.generate) {
+          qrTerminal.generate(setupCode, { small: true }, (qr: string) => {
+            console.log(qr);
+            console.log(`Setup code: ${setupCode}\n`);
+          });
+        } else {
+          // Fallback: just print the setup code (user can run `openclaw qr` manually)
+          console.log(`Setup code: ${setupCode}`);
+          console.log("Run 'openclaw qr' for a scannable QR code.\n");
+        }
+      } catch (err: any) {
+        // Non-fatal — don't block gateway startup
+        console.warn("[agentlife] QR generation skipped:", err?.message);
+      }
+    },
+  });
+
+  // -- Gateway method: create agent (used by builder agent) -------------------
+
+  api.registerGatewayMethod("agentlife.createAgent", async ({ params, respond }: any) => {
+    const id = typeof params?.id === "string" ? params.id.trim() : "";
+    const name = typeof params?.name === "string" ? params.name.trim() : "";
+    const model = typeof params?.model === "string" ? params.model.trim() : "";
+    const workspace = typeof params?.workspace === "string" ? params.workspace.trim() : "";
+    const description = typeof params?.description === "string" ? params.description.trim() : "";
+
+    if (!id) { respond(false, { error: "missing agent id" }); return; }
+    if (!workspace) { respond(false, { error: "missing workspace path" }); return; }
+
+    const cfg = api.runtime.config.loadConfig();
+    const currentList = cfg.agents?.list ?? [];
+    const alreadyExists = currentList.some((a: any) => a.id === id);
+
+    if (!alreadyExists) {
+      const entry: Record<string, unknown> = { id, workspace };
+      if (name) entry.name = name;
+      if (model) entry.model = model;
+
+      const updatedCfg: OpenClawConfig = {
+        ...cfg,
+        agents: {
+          ...cfg.agents,
+          list: [...currentList, entry as any],
+        },
+      };
+      await api.runtime.config.writeConfigFile(updatedCfg);
+      console.log("[agentlife] builder created agent: %s (workspace: %s)", id, workspace);
+    }
+
+    // Always update registry (even if agent config already existed)
+    if (description && isUsableDescription(description, id, name)) {
+      agentRegistry.set(id, {
+        name: name || id,
+        description,
+        model: model || undefined,
+        createdAt: agentRegistry.get(id)?.createdAt ?? Date.now(),
+      });
+      await saveRegistryToDisk();
+      console.log("[agentlife] registered agent in registry: %s — %s", id, description);
+    } else if (description) {
+      console.log("[agentlife] rejected low-quality description for %s: %s", id, description);
+    }
+
+    respond(true, { status: alreadyExists ? "exists" : "created", id, name, model, workspace, description });
+  });
+
+  // -- Gateway method: list registered agents with descriptions ---------------
+  api.registerGatewayMethod("agentlife.agents", ({ respond }: any) => {
+    const agents: Record<string, { name: string; description: string; model?: string }> = {};
+    for (const [id, entry] of agentRegistry.entries()) {
+      agents[id] = { name: entry.name, description: entry.description, model: entry.model };
+    }
+    respond(true, { agents, count: agentRegistry.size });
+  });
+
+  // -- Gateway method: agentlife.db.exec (DDL + DML) --------------------------
+  api.registerGatewayMethod("agentlife.db.exec", ({ params, respond }: any) => {
+    const agentId = typeof params?.agentId === "string" ? params.agentId.trim() : "";
+    const sql = typeof params?.sql === "string" ? params.sql.trim() : "";
+    const sqlParams = Array.isArray(params?.params) ? params.params : [];
+
+    if (!agentId) return respond(false, { error: "missing agentId" });
+    if (!sql) return respond(false, { error: "missing sql" });
+    if (/^\s*SELECT\b/i.test(sql)) return respond(false, { error: "use agentlife.db.query for SELECT" });
+
+    try {
+      const db = getOrCreateAgentDb(agentId);
+      if (sqlParams.length > 0) {
+        const result = db.prepare(sql).run(...sqlParams) as any;
+        respond(true, { changes: result.changes ?? 0, lastInsertRowid: Number(result.lastInsertRowid ?? 0) });
+      } else {
+        db.exec(sql);
+        respond(true, { changes: 0, lastInsertRowid: 0 });
+      }
+    } catch (err: any) {
+      respond(false, { error: err?.message ?? "db error" });
+    }
+  });
+
+  // -- Gateway method: agentlife.db.query (SELECT only) -----------------------
+  api.registerGatewayMethod("agentlife.db.query", ({ params, respond }: any) => {
+    const agentId = typeof params?.agentId === "string" ? params.agentId.trim() : "";
+    const sql = typeof params?.sql === "string" ? params.sql.trim() : "";
+    const sqlParams = Array.isArray(params?.params) ? params.params : [];
+
+    if (!agentId) return respond(false, { error: "missing agentId" });
+    if (!sql) return respond(false, { error: "missing sql" });
+    if (!/^\s*SELECT\b/i.test(sql)) return respond(false, { error: "use agentlife.db.exec for non-SELECT" });
+
+    try {
+      const db = getOrCreateAgentDb(agentId);
+      const rows = db.prepare(sql).all(...sqlParams) as Record<string, unknown>[];
+      const MAX = 1000;
+      const truncated = rows.length > MAX;
+      const result = truncated ? rows.slice(0, MAX) : rows;
+      const columns = result.length > 0 ? Object.keys(result[0]) : [];
+      respond(true, { rows: result, columns, count: result.length, truncated });
+    } catch (err: any) {
+      respond(false, { error: err?.message ?? "db error" });
+    }
+  });
+
+  // -- Gateway method: agentlife.history (surface event history) ---------------
+  api.registerGatewayMethod("agentlife.history", ({ params, respond }: any) => {
+    try {
+      const db = getOrCreateHistoryDb();
+      const conds: string[] = [];
+      const bind: unknown[] = [];
+
+      if (typeof params?.surfaceId === "string" && params.surfaceId) { conds.push("surfaceId = ?"); bind.push(params.surfaceId); }
+      if (typeof params?.agentId === "string" && params.agentId) { conds.push("agentId = ?"); bind.push(params.agentId); }
+      if (typeof params?.event === "string" && params.event) { conds.push("event = ?"); bind.push(params.event); }
+      if (typeof params?.search === "string" && params.search) { conds.push("dsl LIKE ?"); bind.push(`%${params.search}%`); }
+      if (typeof params?.since === "number") { conds.push("createdAt >= ?"); bind.push(params.since); }
+      if (typeof params?.until === "number") { conds.push("createdAt <= ?"); bind.push(params.until); }
+
+      const where = conds.length > 0 ? `WHERE ${conds.join(" AND ")}` : "";
+      const limit = Math.min(typeof params?.limit === "number" ? params.limit : 100, 500);
+      const offset = typeof params?.offset === "number" ? params.offset : 0;
+      bind.push(limit, offset);
+
+      const rows = db.prepare(`SELECT * FROM surface_events ${where} ORDER BY createdAt DESC LIMIT ? OFFSET ?`).all(...bind) as any[];
+      respond(true, { events: rows, count: rows.length });
+    } catch (err: any) {
+      respond(false, { error: err?.message ?? "history error" });
+    }
+  });
+
+  // -- Bootstrap: inject A2UI guidance + dashboard state per session ----------
+  // Only skip guidance for the orchestrator — it never renders widgets.
+  // The builder NEEDS guidance to render overlays and confirmation widgets.
+  const SKIP_GUIDANCE_AGENTS = new Set(["agentlife"]);
+
+  api.registerHook("agent:bootstrap", (event) => {
+    const ctx = event.context as { bootstrapFiles: BootstrapFile[]; agentId?: string };
+    if (!ctx?.bootstrapFiles) {
+      return;
+    }
+
+    if (ctx.agentId && SKIP_GUIDANCE_AGENTS.has(ctx.agentId)) {
+      // Orchestrator doesn't get widget guidance, but DOES get the agent registry
+      const registryContext = buildAgentRegistryContext();
+      if (registryContext) {
+        const regIdx = ctx.bootstrapFiles.findIndex((f) => f.name === "AGENT_REGISTRY.md");
+        const regEntry: BootstrapFile = {
+          name: "AGENT_REGISTRY.md",
+          path: "agentlife://agent-registry",
+          content: registryContext,
+          missing: false,
+        };
+        if (regIdx >= 0) {
+          ctx.bootstrapFiles[regIdx] = regEntry;
+        } else {
+          ctx.bootstrapFiles.push(regEntry);
+        }
+        console.log("[agentlife] injected agent registry (%d agents) into %s bootstrap", agentRegistry.size, ctx.agentId);
+      } else {
+        console.log("[agentlife] no agents in registry for %s bootstrap", ctx.agentId);
+      }
+      return;
+    }
+
+    // Replace existing TOOLS.md (loaded as missing/empty from disk) instead of pushing a duplicate.
+    const idx = ctx.bootstrapFiles.findIndex((f) => f.name === "TOOLS.md");
+    const entry: BootstrapFile = {
+      name: "TOOLS.md",
+      path: "agentlife://a2ui-guidance",
+      content: TENAZITAS_GUIDANCE,
+      missing: false,
+    };
+    if (idx >= 0) {
+      ctx.bootstrapFiles[idx] = entry;
+    } else {
+      ctx.bootstrapFiles.push(entry);
+    }
+
+    // Inject current dashboard state so the agent knows what's on screen.
+    // Replace existing entry to avoid duplicates across bootstrap calls.
+    const dashboardState = buildDashboardStateContext();
+    if (dashboardState) {
+      const dsIdx = ctx.bootstrapFiles.findIndex((f) => f.name === "DASHBOARD_STATE.md");
+      const dsEntry: BootstrapFile = {
+        name: "DASHBOARD_STATE.md",
+        path: "agentlife://dashboard-state",
+        content: dashboardState,
+        missing: false,
+      };
+      if (dsIdx >= 0) {
+        ctx.bootstrapFiles[dsIdx] = dsEntry;
+      } else {
+        ctx.bootstrapFiles.push(dsEntry);
+      }
+    }
+
+    // Persist any expiredSince changes from bootstrap evaluation.
+    scheduleSave();
+
+    // Save snapshot for debug introspection.
+    lastBootstrapSnapshot = ctx.bootstrapFiles.map((f) => ({ ...f }));
+    console.log(
+      "[agentlife] injected A2UI guidance (%d bytes) + dashboard state (%s) into bootstrap",
+      TENAZITAS_GUIDANCE.length,
+      dashboardState ? `${dashboardState.length} bytes` : "empty",
+    );
+  }, { name: "agentlife-a2ui-guidance", description: "Inject A2UI component catalog, dashboard rules, and current dashboard state" });
+
+  // -- Hook: capture canvas tool calls for persistence ------------------------
+  api.on("after_tool_call", (event: any) => {
+    if (event.toolName !== "canvas") return;
+    const action = event.params?.action;
+    if (action === "a2ui_push" && typeof event.params?.jsonl === "string") {
+      processDslBlock(event.params.jsonl);
+      scheduleSave();
+    } else if (action === "a2ui_reset") {
+      for (const sid of surfaceStore.keys()) {
+        recordSurfaceEvent(sid, "deleted");
+      }
+      surfaceStore.clear();
+      transientSurfaces.clear();
+      scheduleSave();
+    }
+  });
+
+  // -- Gateway method: serve persisted surfaces to any device -----------------
+  api.registerGatewayMethod("agentlife.surfaces", ({ respond }: any) => {
+    const now = Date.now();
+    const surfaces: { surfaceId: string; dsl: string }[] = [];
+    for (const [surfaceId, meta] of surfaceStore.entries()) {
+      // Filter out expired surfaces — client doesn't get stale cards
+      if (isExpired(meta, now)) continue;
+      if (meta.lines.length > 0) {
+        surfaces.push({ surfaceId, dsl: meta.lines.join("\n") });
+      }
+    }
+    respond(true, { surfaces });
+  });
+
+  // -- Gateway method: dismiss a surface (user-initiated) ----------------------
+  api.registerGatewayMethod("agentlife.dismiss", ({ params, respond }: any) => {
+    const surfaceId = params?.surfaceId;
+    if (!surfaceId || typeof surfaceId !== "string") {
+      respond(false, { error: "missing surfaceId" });
+      return;
+    }
+    const meta = surfaceStore.get(surfaceId);
+    if (meta) {
+      surfaceStore.delete(surfaceId);
+      transientSurfaces.delete(surfaceId);
+      recordSurfaceEvent(surfaceId, "dismissed");
+      scheduleSave();
+      console.log("[agentlife] surface dismissed by user: %s (age: %s)", surfaceId, formatAge(Date.now() - meta.createdAt));
+    }
+    respond(true, { surfaceId, dismissed: !!meta });
+  });
+
+  // -- Debug: return the last bootstrap snapshot via gateway method ------------
+  api.registerGatewayMethod("agentlife.bootstrap", ({ respond }: any) => {
+    if (lastBootstrapSnapshot.length === 0) {
+      respond(true, { status: "no session bootstrapped yet", files: [] });
+      return;
+    }
+    respond(true, {
+      files: lastBootstrapSnapshot.map((f) => ({
+        name: f.name,
+        path: f.path,
+        missing: f.missing,
+        bytes: (f.content ?? "").length,
+        content: f.content ?? "",
+      })),
+    });
+  });
+}