amalgm 0.0.1 → 0.0.33

package/runtime/scripts/amalgm-mcp/agents/store.js

@@ -1,12 +1,21 @@
 /**
- * Agents storage — ~/.amalgm/agents.json + built-in defaults.
+ * Agents storage — SQLite-backed local agent registry + conversation logs.
  *
- * Built-ins are compile-time (claude_code, codex, opencode, pi, amp, cursor). Custom agents
- * persist to agents.json with id prefix "custom-".
+ * The registry is the Local Live Store source of truth for agent capabilities.
+ * Built-in harnesses are seeded as non-deletable rows. Custom agents are rows
+ * in the same table, so discovery, snapshots, and agent-to-agent lookup use one
+ * shape.
  */
 
+const crypto = require('crypto');
+const os = require('os');
 const path = require('path');
-const { AGENTS_FILE, AGENT_CONVOS_DIR, STORAGE_DIR } = require('../config');
+const {
+  AGENTS_FILE,
+  AGENT_CONVOS_DIR,
+  STORAGE_DIR,
+  COMPUTER_RECORD_FILE,
+} = require('../config');
 const {
   ensureDir,
   readJson,
@@ -14,108 +23,610 @@ const {
   appendJsonl,
   tailJsonl,
 } = require('../lib/storage');
+const { openLocalDb } = require('../state/db');
+const { insertStateEvent, publishStateEvent } = require('../state/events');
+
+const DEFAULT_AGENT_STATUS = 'unknown';
+const CUSTOM_AGENT_STATUS = 'ready';
+const BUILTIN_AGENT_IDS = ['claude_code', 'codex', 'opencode', 'pi'];
+const AMALGM_COMPUTER_ID = process.env.AMALGM_COMPUTER_ID || '';
 
-const BUILTIN_AGENTS = [
+const BUILTIN_AGENT_BLUEPRINTS = [
   {
     id: 'claude_code',
     name: 'Claude Code',
     description:
       'Anthropic Claude agent — general-purpose coding, research, and reasoning',
+    adapter: 'claude_code',
     baseHarnessId: 'claude_code',
     baseModelId: 'anthropic/claude-opus-4.7',
-    systemPrompt: '',
-    mcp: { inheritAll: true, customServers: [] },
-    builtin: true,
   },
   {
     id: 'codex',
     name: 'Codex',
     description: 'OpenAI Codex agent — code generation and analysis',
+    adapter: 'codex',
     baseHarnessId: 'codex',
-    baseModelId: 'openai/gpt-5.4-thinking-xhigh',
-    systemPrompt: '',
-    mcp: { inheritAll: true, customServers: [] },
-    builtin: true,
+    baseModelId: 'openai/gpt-5.4',
   },
   {
     id: 'opencode',
     name: 'OpenCode',
     description: 'Open-source agent — multi-provider coding assistant',
+    adapter: 'opencode',
     baseHarnessId: 'opencode',
-    baseModelId: 'opencode-moonshotai-kimi-k2.5',
-    systemPrompt: '',
-    mcp: { inheritAll: true, customServers: [] },
-    builtin: true,
+    baseModelId: 'opencode-anthropic-claude-sonnet-4-6',
   },
   {
     id: 'pi',
     name: 'Pi',
     description: 'Pi agent — multi-provider coding assistant',
+    adapter: 'pi',
     baseHarnessId: 'pi',
     baseModelId: 'pi-anthropic-claude-sonnet-4.6',
-    systemPrompt: '',
-    mcp: { inheritAll: true, customServers: [] },
-    builtin: true,
-  },
-  {
-    id: 'amp',
-    name: 'Amp',
-    description: 'Sourcegraph Amp agent — terminal-auth coding assistant',
-    baseHarnessId: 'amp',
-    baseModelId: 'amp-default',
-    systemPrompt: '',
-    mcp: { inheritAll: true, customServers: [] },
-    builtin: true,
-  },
-  {
-    id: 'cursor',
-    name: 'Cursor',
-    description: 'Cursor Agent CLI — account-auth coding assistant',
-    baseHarnessId: 'cursor',
-    baseModelId: 'cursor/composer-2-fast',
-    systemPrompt: '',
-    mcp: { inheritAll: true, customServers: [] },
-    builtin: true,
   },
 ];
 
-const UUID_RE = /^[0-9a-f]{8}-[0-9a-f]{4}-[1-5][0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$/i;
+const BUILTIN_AGENTS = BUILTIN_AGENT_BLUEPRINTS.map((agent) => ({
+  ...agent,
+  systemPrompt: '',
+  files: [],
+  skills: [],
+  mcpAppIds: [],
+  nativeMcps: [],
+  tools: { mode: 'all', selectedToolIds: [] },
+  mcp: { inheritAll: true, customServers: [], appIds: [], nativeMcps: [] },
+  builtin: true,
+  deletable: false,
+  editable: false,
+  status: DEFAULT_AGENT_STATUS,
+}));
 
-function normalizeConversationId(value) {
-  const clean = String(value || '').trim();
-  return UUID_RE.test(clean) ? clean : null;
+const UUID_RE = /^[0-9a-f]{8}-[0-9a-f]{4}-[1-5][0-9a-f]{3}-[89ab][0-9a-f]{12}$/i;
+
+function nowIso() {
+  return new Date().toISOString();
 }
 
-function conversationLogPath(sessionId) {
-  const conversationId = normalizeConversationId(sessionId);
-  if (!conversationId) throw new Error('conversation_id must be a UUID');
-  return path.join(AGENT_CONVOS_DIR, `${conversationId}.jsonl`);
+function isObject(value) {
+  return !!value && typeof value === 'object' && !Array.isArray(value);
 }
 
-function ensureAgentsDirs() {
+function safeJsonParse(value, fallback = null) {
+  if (typeof value !== 'string' || !value) return fallback;
+  try {
+    return JSON.parse(value);
+  } catch {
+    return fallback;
+  }
+}
+
+function nonEmptyString(value) {
+  return typeof value === 'string' && value.trim() ? value.trim() : null;
+}
+
+function normalizeStringList(values) {
+  if (!Array.isArray(values)) return [];
+  return [...new Set(values
+    .filter((value) => typeof value === 'string')
+    .map((value) => value.trim())
+    .filter(Boolean))];
+}
+
+function readComputerRecord() {
+  return readJson(COMPUTER_RECORD_FILE, {}) || {};
+}
+
+function computerId() {
+  const record = readComputerRecord();
+  return nonEmptyString(AMALGM_COMPUTER_ID)
+    || nonEmptyString(record.computer_id)
+    || nonEmptyString(process.env.AMALGM_CONTAINER_ID)
+    || '';
+}
+
+function computerName() {
+  const record = readComputerRecord();
+  return nonEmptyString(record.name)
+    || nonEmptyString(process.env.AMALGM_COMPUTER_NAME)
+    || os.hostname()
+    || 'This computer';
+}
+
+function normalizeLocation(inputLocation, fallback = {}) {
+  const id = nonEmptyString(fallback.ownerComputerId) || computerId();
+  const name = nonEmptyString(fallback.locationName) || computerName();
+  const raw = isObject(inputLocation) ? inputLocation : {};
+  const type = nonEmptyString(raw.type) || 'computer';
+  return {
+    type,
+    ...(nonEmptyString(raw.computerId) || id ? { computerId: nonEmptyString(raw.computerId) || id } : {}),
+    name: nonEmptyString(raw.name) || nonEmptyString(raw.computerName) || name,
+    ...(nonEmptyString(raw.endpoint) ? { endpoint: raw.endpoint.trim() } : {}),
+    ...(nonEmptyString(raw.localUrl) ? { localUrl: raw.localUrl.trim() } : {}),
+  };
+}
+
+function locationLabel(location) {
+  if (isObject(location)) {
+    return nonEmptyString(location.name)
+      || nonEmptyString(location.computerName)
+      || nonEmptyString(location.endpoint)
+      || nonEmptyString(location.localUrl)
+      || 'This computer';
+  }
+  return nonEmptyString(location) || 'This computer';
+}
+
+function defaultCapabilities(agent) {
+  return {
+    streaming: true,
+    resume: true,
+    cancel: true,
+    tools: agent?.tools?.mode === 'selected' ? 'selected' : 'all',
+  };
+}
+
+function normalizeMcpConfig(mcp, mcpAppIds, nativeMcps) {
+  return {
+    inheritAll: mcp?.inheritAll !== false,
+    customServers: Array.isArray(mcp?.customServers) ? mcp.customServers : [],
+    appIds: normalizeStringList(mcpAppIds !== undefined ? mcpAppIds : mcp?.appIds),
+    nativeMcps: normalizeStringList(nativeMcps !== undefined ? nativeMcps : mcp?.nativeMcps),
+  };
+}
+
+function normalizeToolConfig(tools, legacyMcp) {
+  const raw = isObject(tools) ? tools : null;
+  const selectedToolIds = normalizeStringList(
+    raw?.selectedToolIds
+    ?? raw?.selected
+    ?? [
+      ...normalizeStringList(legacyMcp?.appIds),
+      ...normalizeStringList(legacyMcp?.nativeMcps),
+    ],
+  );
+  return {
+    mode: raw?.mode === 'selected' || (!raw && legacyMcp?.inheritAll === false) ? 'selected' : 'all',
+    selectedToolIds,
+  };
+}
+
+function normalizeAgent(input, existing) {
+  if (!isObject(input)) throw new Error('agent must be an object');
+  const id = nonEmptyString(input.id) || `custom-${crypto.randomUUID()}`;
+  const builtin = input.builtin === true || BUILTIN_AGENT_IDS.includes(id);
+  const baseHarnessId = nonEmptyString(input.baseHarnessId || input.base_harness_id) || id;
+  const adapter = nonEmptyString(input.adapter) || baseHarnessId;
+  const mcpConfig = normalizeMcpConfig(input.mcp, input.mcpAppIds, input.nativeMcps);
+  const toolConfig = normalizeToolConfig(input.tools, mcpConfig);
+  const ownerComputerId = nonEmptyString(input.ownerComputerId || input.owner_computer_id)
+    || nonEmptyString(existing?.ownerComputerId)
+    || computerId();
+  const location = normalizeLocation(input.location, {
+    ownerComputerId,
+    locationName: input.locationName || existing?.locationName,
+  });
+  const createdAt = input.createdAt || existing?.createdAt || nowIso();
+  const updatedAt = input.updatedAt || nowIso();
+
+  return {
+    id,
+    name: nonEmptyString(input.name) || id,
+    description: input.description || '',
+    adapter,
+    baseHarnessId,
+    baseModelId: input.baseModelId || existing?.baseModelId || '',
+    systemPrompt: input.systemPrompt || '',
+    files: normalizeStringList(input.files),
+    skills: normalizeStringList(input.skills),
+    mcpAppIds: normalizeStringList(mcpConfig.appIds),
+    nativeMcps: normalizeStringList(mcpConfig.nativeMcps),
+    tools: toolConfig,
+    mcp: {
+      ...mcpConfig,
+      inheritAll: toolConfig.mode !== 'selected',
+    },
+    authMethod: input.authMethod || existing?.authMethod || 'amalgm',
+    location,
+    locationName: locationLabel(location),
+    ownerComputerId,
+    status: input.status || existing?.status || (builtin ? DEFAULT_AGENT_STATUS : CUSTOM_AGENT_STATUS),
+    installStatus: input.installStatus || existing?.installStatus || (builtin ? 'unknown' : 'external'),
+    authStatus: input.authStatus || existing?.authStatus || 'unknown',
+    capabilities: isObject(input.capabilities)
+      ? { ...defaultCapabilities({ tools: toolConfig }), ...input.capabilities }
+      : defaultCapabilities({ tools: toolConfig }),
+    builtin,
+    deletable: input.deletable === false || builtin ? false : true,
+    editable: input.editable === false || builtin ? false : true,
+    createdAt,
+    updatedAt,
+    ...(input.configDir ? { configDir: input.configDir } : existing?.configDir ? { configDir: existing.configDir } : {}),
+    ...(input.authDetails ? { authDetails: input.authDetails } : existing?.authDetails ? { authDetails: existing.authDetails } : {}),
+  };
+}
+
+function semanticAgent(agent) {
+  const { updatedAt, ...rest } = agent || {};
+  return rest;
+}
+
+function agentsEqualForWrite(left, right) {
+  return JSON.stringify(semanticAgent(left)) === JSON.stringify(semanticAgent(right));
+}
+
+function rowToAgent(row) {
+  if (!row) return null;
+  const parsed = safeJsonParse(row.agent_json, null);
+  if (!isObject(parsed)) return null;
+  return normalizeAgent({
+    ...parsed,
+    builtin: row.builtin === 1 || parsed.builtin === true,
+    deletable: row.deletable === 1 && parsed.deletable !== false,
+  }, null);
+}
+
+function readAgentRow(db, id) {
+  return rowToAgent(db.prepare('SELECT * FROM agents WHERE id = ?').get(id));
+}
+
+function upsertAgentRow(db, agent) {
+  db.prepare(`
+    INSERT INTO agents (
+      id,
+      name,
+      adapter,
+      base_harness_id,
+      location,
+      owner_computer_id,
+      builtin,
+      deletable,
+      status,
+      updated_at,
+      agent_json
+    )
+    VALUES (
+      @id,
+      @name,
+      @adapter,
+      @base_harness_id,
+      @location,
+      @owner_computer_id,
+      @builtin,
+      @deletable,
+      @status,
+      @updated_at,
+      @agent_json
+    )
+    ON CONFLICT(id) DO UPDATE SET
+      name = excluded.name,
+      adapter = excluded.adapter,
+      base_harness_id = excluded.base_harness_id,
+      location = excluded.location,
+      owner_computer_id = excluded.owner_computer_id,
+      builtin = excluded.builtin,
+      deletable = excluded.deletable,
+      status = excluded.status,
+      updated_at = excluded.updated_at,
+      agent_json = excluded.agent_json
+  `).run({
+    id: agent.id,
+    name: agent.name,
+    adapter: agent.adapter,
+    base_harness_id: agent.baseHarnessId,
+    location: agent.locationName || locationLabel(agent.location),
+    owner_computer_id: agent.ownerComputerId || null,
+    builtin: agent.builtin ? 1 : 0,
+    deletable: agent.deletable === false ? 0 : 1,
+    status: agent.status || DEFAULT_AGENT_STATUS,
+    updated_at: agent.updatedAt || nowIso(),
+    agent_json: JSON.stringify(agent),
+  });
+}
+
+function insertAgentEvent(db, op, agent, options = {}) {
+  return insertStateEvent(db, {
+    resource: 'agents',
+    op,
+    id: agent.id,
+    value: op === 'delete' ? undefined : agent,
+    clientMutationId: options.clientMutationId,
+    source: options.source || 'agents',
+  });
+}
+
+function publishEvents(events) {
+  for (const event of events) publishStateEvent(event);
+}
+
+function writeAgentsJson(customAgents) {
+  ensureDir(STORAGE_DIR);
+  writeJsonAtomic(AGENTS_FILE, {
+    version: 1,
+    agents: customAgents,
+  });
+}
+
+function readCustomAgentsFromDb(db = openLocalDb()) {
+  return db.prepare(`
+    SELECT * FROM agents
+    WHERE builtin = 0
+    ORDER BY updated_at DESC, id ASC
+  `).all()
+    .map(rowToAgent)
+    .filter(Boolean);
+}
+
+function readAllAgentsFromDb(db = openLocalDb()) {
+  return db.prepare('SELECT * FROM agents ORDER BY builtin DESC, updated_at DESC, id ASC')
+    .all()
+    .map(rowToAgent)
+    .filter(Boolean);
+}
+
+function customAgentRowCount(db = openLocalDb()) {
+  const row = db.prepare('SELECT COUNT(*) AS count FROM agents WHERE builtin = 0').get();
+  return Number(row?.count || 0);
+}
+
+function seedBuiltinAgents(options = {}) {
+  const db = openLocalDb();
+  const events = db.transaction(() => {
+    const inserted = [];
+    for (const blueprint of BUILTIN_AGENT_BLUEPRINTS) {
+      const existing = readAgentRow(db, blueprint.id);
+      const next = normalizeAgent({
+        ...blueprint,
+        systemPrompt: '',
+        files: [],
+        skills: [],
+        mcpAppIds: [],
+        nativeMcps: [],
+        tools: { mode: 'all', selectedToolIds: [] },
+        mcp: { inheritAll: true, customServers: [], appIds: [], nativeMcps: [] },
+        builtin: true,
+        deletable: false,
+        editable: false,
+        status: existing?.status || DEFAULT_AGENT_STATUS,
+        installStatus: existing?.installStatus || 'unknown',
+        authStatus: existing?.authStatus || 'unknown',
+        authDetails: existing?.authDetails,
+        configDir: existing?.configDir,
+        createdAt: existing?.createdAt,
+        authMethod: existing?.authMethod || 'amalgm',
+      }, existing);
+      if (existing && agentsEqualForWrite(existing, next)) continue;
+      upsertAgentRow(db, next);
+      if (options.emit) {
+        inserted.push(insertAgentEvent(db, existing ? 'update' : 'insert', next, {
+          source: options.source || 'agents:seed-defaults',
+        }));
+      }
+    }
+    return inserted;
+  })();
+  publishEvents(events);
+}
+
+function migrateLegacyAgentsJsonIfNeeded() {
+  const db = openLocalDb();
+  if (customAgentRowCount(db) > 0) return;
+
+  const legacy = readJson(AGENTS_FILE, { version: 1, agents: [] });
+  const legacyAgents = Array.isArray(legacy?.agents) ? legacy.agents : [];
+  if (legacyAgents.length === 0) return;
+
+  db.transaction(() => {
+    for (const agent of legacyAgents) {
+      const normalized = normalizeAgent(agent, null);
+      if (normalized.builtin) continue;
+      upsertAgentRow(db, normalized);
+    }
+  })();
+}
+
+function ensureAgentRegistry() {
   ensureDir(STORAGE_DIR);
   ensureDir(AGENT_CONVOS_DIR);
-  if (!readJson(AGENTS_FILE, null)) writeJsonAtomic(AGENTS_FILE, { version: 1, agents: [] });
+  seedBuiltinAgents();
+  migrateLegacyAgentsJsonIfNeeded();
+  if (!readJson(AGENTS_FILE, null)) writeAgentsJson(readCustomAgentsFromDb());
 }
 
 function loadAgents() {
-  return readJson(AGENTS_FILE, { version: 1, agents: [] });
+  ensureAgentRegistry();
+  const agents = readCustomAgentsFromDb();
+  writeAgentsJson(agents);
+  return { version: 1, agents };
 }
 
-function saveAgents(data) {
-  writeJsonAtomic(AGENTS_FILE, data);
+function saveAgents(data, options = {}) {
+  ensureAgentRegistry();
+  const inputAgents = Array.isArray(data?.agents) ? data.agents : [];
+  const db = openLocalDb();
+  const events = db.transaction(() => {
+    const inserted = [];
+    const keepIds = new Set();
+    const existing = new Map(readCustomAgentsFromDb(db).map((agent) => [agent.id, agent]));
+    for (const input of inputAgents) {
+      const normalized = normalizeAgent(input, input?.id ? existing.get(input.id) : null);
+      if (normalized.builtin) continue;
+      keepIds.add(normalized.id);
+      const previous = existing.get(normalized.id);
+      if (!previous || !agentsEqualForWrite(previous, normalized)) {
+        upsertAgentRow(db, normalized);
+        inserted.push(insertAgentEvent(db, previous ? 'update' : 'insert', normalized, {
+          source: options.source || 'agents:save',
+        }));
+      }
+    }
+    for (const previous of existing.values()) {
+      if (keepIds.has(previous.id)) continue;
+      db.prepare('DELETE FROM agents WHERE id = ? AND builtin = 0').run(previous.id);
+      inserted.push(insertAgentEvent(db, 'delete', previous, {
+        source: options.source || 'agents:save',
+      }));
+    }
+    return inserted;
+  })();
+  const agents = readCustomAgentsFromDb(db);
+  writeAgentsJson(agents);
+  publishEvents(events);
+  return { version: 1, agents };
 }
 
 function getAllAgentsWithBuiltins() {
-  const data = loadAgents();
-  return [...BUILTIN_AGENTS, ...data.agents];
+  ensureAgentRegistry();
+  const agents = readAllAgentsFromDb();
+  const builtinOrder = new Map(BUILTIN_AGENT_IDS.map((id, index) => [id, index]));
+  return [
+    ...agents
+      .filter((agent) => agent.builtin)
+      .sort((a, b) => (builtinOrder.get(a.id) ?? 999) - (builtinOrder.get(b.id) ?? 999)),
+    ...agents.filter((agent) => !agent.builtin),
+  ];
+}
+
+function createAgent(input, options = {}) {
+  ensureAgentRegistry();
+  const db = openLocalDb();
+  const agent = normalizeAgent({
+    ...input,
+    id: input?.id || `custom-${crypto.randomUUID()}`,
+    builtin: false,
+    deletable: true,
+    editable: true,
+    status: input?.status || CUSTOM_AGENT_STATUS,
+  }, null);
+  if (!agent.name || !agent.name.trim()) throw new Error('name is required');
+  if (!agent.baseHarnessId) throw new Error('baseHarnessId is required');
+
+  const duplicate = getAllAgentsWithBuiltins()
+    .find((candidate) => candidate.id !== agent.id && candidate.name.toLowerCase() === agent.name.toLowerCase());
+  if (duplicate) throw new Error(`An agent named "${agent.name}" already exists`);
+
+  const event = db.transaction(() => {
+    upsertAgentRow(db, agent);
+    return insertAgentEvent(db, 'insert', agent, {
+      clientMutationId: input?.clientMutationId,
+      source: options.source || 'agents:create',
+    });
+  })();
+  writeAgentsJson(readCustomAgentsFromDb(db));
+  publishStateEvent(event);
+  return agent;
+}
+
+function updateAgent(agentId, updates, options = {}) {
+  ensureAgentRegistry();
+  const db = openLocalDb();
+  const existing = readAgentRow(db, agentId);
+  if (!existing) throw new Error(`Agent not found: ${agentId}`);
+  if (existing.builtin && options.allowBuiltinUpdate !== true) {
+    throw new Error(`Built-in agent "${existing.name}" cannot be edited`);
+  }
+
+  const requestedName = nonEmptyString(updates?.name);
+  if (requestedName) {
+    const duplicate = getAllAgentsWithBuiltins()
+      .find((candidate) => candidate.id !== agentId && candidate.name.toLowerCase() === requestedName.toLowerCase());
+    if (duplicate) throw new Error(`An agent named "${requestedName}" already exists`);
+  }
+
+  const hasOwn = (key) => Object.prototype.hasOwnProperty.call(updates || {}, key);
+  const merged = {
+    ...existing,
+    ...updates,
+    id: existing.id,
+    builtin: existing.builtin,
+    deletable: existing.deletable,
+    editable: existing.editable,
+    updatedAt: nowIso(),
+  };
+  if (!hasOwn('tools') && (hasOwn('mcp') || hasOwn('mcpAppIds') || hasOwn('nativeMcps'))) {
+    delete merged.tools;
+  }
+
+  const next = normalizeAgent(merged, existing);
+
+  if (agentsEqualForWrite(existing, next)) return existing;
+
+  const event = db.transaction(() => {
+    upsertAgentRow(db, next);
+    return insertAgentEvent(db, 'update', next, {
+      clientMutationId: updates?.clientMutationId,
+      source: options.source || 'agents:update',
+    });
+  })();
+  writeAgentsJson(readCustomAgentsFromDb(db));
+  publishStateEvent(event);
+  return next;
+}
+
+function deleteAgent(agentId, options = {}) {
+  ensureAgentRegistry();
+  const db = openLocalDb();
+  const existing = readAgentRow(db, agentId);
+  if (!existing) throw new Error(`Agent not found: ${agentId}`);
+  if (existing.builtin || existing.deletable === false) {
+    throw new Error(`Built-in agent "${existing.name}" cannot be deleted`);
+  }
+
+  const event = db.transaction(() => {
+    db.prepare('DELETE FROM agents WHERE id = ? AND builtin = 0').run(agentId);
+    return insertAgentEvent(db, 'delete', existing, {
+      source: options.source || 'agents:delete',
+    });
+  })();
+  writeAgentsJson(readCustomAgentsFromDb(db));
+  publishStateEvent(event);
+  return existing;
+}
+
+function syncDiscoveredAgents(discoveredAgents = [], options = {}) {
+  ensureAgentRegistry();
+  const discoveredById = new Map(
+    (Array.isArray(discoveredAgents) ? discoveredAgents : [])
+      .filter((agent) => agent && typeof agent.id === 'string')
+      .map((agent) => [agent.id, agent]),
+  );
+  const db = openLocalDb();
+  const events = db.transaction(() => {
+    const inserted = [];
+    for (const blueprint of BUILTIN_AGENT_BLUEPRINTS) {
+      const existing = readAgentRow(db, blueprint.id);
+      if (!existing) continue;
+      const discovered = discoveredById.get(blueprint.id);
+      const next = normalizeAgent({
+        ...existing,
+        status: discovered
+          ? discovered.hasAuth ? 'ready' : 'auth_needed'
+          : 'install_needed',
+        installStatus: discovered ? 'installed' : 'missing',
+        authStatus: discovered
+          ? discovered.hasAuth ? 'ready' : 'auth_needed'
+          : 'unknown',
+        configDir: discovered?.configDir || existing.configDir,
+        authDetails: discovered?.authDetails || existing.authDetails,
+        updatedAt: nowIso(),
+      }, existing);
+      if (agentsEqualForWrite(existing, next)) continue;
+      upsertAgentRow(db, next);
+      inserted.push(insertAgentEvent(db, 'update', next, {
+        source: options.source || 'agents:discovery',
+      }));
+    }
+    return inserted;
+  })();
+  publishEvents(events);
+  return getAllAgentsWithBuiltins();
 }
 
 function resolveAgent(agentId) {
-  const builtin = BUILTIN_AGENTS.find((a) => a.id === agentId);
-  if (builtin) return builtin;
-  const data = loadAgents();
-  return data.agents.find((a) => a.id === agentId) || null;
+  ensureAgentRegistry();
+  const db = openLocalDb();
+  return readAgentRow(db, agentId);
 }
 
 function normalizeAgentLookup(value) {
@@ -131,6 +642,21 @@ function resolveAgentByNameOrId(value) {
   )) || null;
 }
 
+function normalizeConversationId(value) {
+  const clean = String(value || '').trim();
+  return UUID_RE.test(clean) ? clean : null;
+}
+
+function conversationLogPath(sessionId) {
+  const conversationId = normalizeConversationId(sessionId);
+  if (!conversationId) throw new Error('conversation_id must be a UUID');
+  return path.join(AGENT_CONVOS_DIR, `${conversationId}.jsonl`);
+}
+
+function ensureAgentsDirs() {
+  ensureAgentRegistry();
+}
+
 function appendAgentConvoLog(sessionId, entry) {
   appendJsonl(conversationLogPath(sessionId), entry);
 }
@@ -141,10 +667,15 @@ function readAgentConvoLog(sessionId, limit = 50) {
 
 module.exports = {
   BUILTIN_AGENTS,
+  BUILTIN_AGENT_IDS,
   ensureAgentsDirs,
   loadAgents,
   saveAgents,
   getAllAgentsWithBuiltins,
+  createAgent,
+  updateAgent,
+  deleteAgent,
+  syncDiscoveredAgents,
   resolveAgent,
   resolveAgentByNameOrId,
   normalizeConversationId,