@johpaz/hive-sdk 0.1.4 → 0.1.6

package/packages/core/src/agent/acceptance-checks.ts

@@ -0,0 +1,172 @@
+/**
+ * acceptance-checks — deterministic acceptance checking, no LLM.
+ *
+ * Replaces the independent acceptance_verifier agent loop (which ran a full
+ * agent-loop, up to 3 times, just to re-derive a verdict the worker's own
+ * structured output already implies). This runs whatever deterministic
+ * checkTool each criterion declares, inspects any artifact_id found in the
+ * evidence, and applies cheap delivery gates — zero LLM calls.
+ *
+ * When nothing deterministic applies to a criterion, the result is
+ * "unchecked", not a failure: that's exactly the case the coordinator's
+ * closing turn (already paid for, via the delegation-group fan-in) is meant
+ * to judge using this checks result plus the raw evidence.
+ */
+
+import { col } from "../storage/hive";
+import type { AgentDoc } from "../storage/collections";
+import type { AcceptanceCriterion } from "./run-store";
+import { interpretCheckResult } from "./goal-runner";
+import { inspectArtifact } from "../artifacts/store";
+import { loadConfig } from "../config/loader";
+import { logger } from "../utils/logger";
+
+const log = logger.child("acceptance-checks");
+
+export type CheckStatus = "passed" | "failed" | "unchecked";
+
+export interface AcceptanceCheckResult {
+  criterion_id: string;
+  /** checkTool name, "artifact_inspect", "delivery_gate", or "none". */
+  check: string;
+  /** null when no deterministic check applied to this criterion. */
+  met: boolean | null;
+  detail: string;
+}
+
+export interface AcceptanceChecks {
+  status: CheckStatus;
+  results: AcceptanceCheckResult[];
+  summary: string;
+}
+
+export function sanitizeDiagnostic(value: string, limit = 1000): string {
+  return value
+    .replace(
+      // El esquema de auth va aparte: sin el grupo opcional, "authorization:
+      // Bearer <token>" consumía sólo "Bearer" y dejaba el token en claro.
+      /(api[_-]?key|token|authorization|secret)(["'=:\s]+)(?:(bearer|basic)\s+)?[^\s,}"']+/gi,
+      (_match, key: string, separator: string, scheme?: string) =>
+        `${key}${separator}${scheme ? `${scheme} ` : ""}[REDACTED]`,
+    )
+    .slice(0, limit);
+}
+
+async function runCheckTool(criterion: AcceptanceCriterion, objective: string): Promise<AcceptanceCheckResult | null> {
+  if (!criterion.checkTool) return null;
+  try {
+    const { executeToolBatch } = await import("../tool-runtime");
+    const { createAllTools } = await import("../tools/index");
+    const allTools = createAllTools(loadConfig());
+    const toolDef = allTools.find((t) => t.name === criterion.checkTool);
+    if (!toolDef) {
+      log.warn(`[acceptance-checks] Check tool "${criterion.checkTool}" not found in the tool registry`);
+      return { criterion_id: criterion.id, check: criterion.checkTool, met: null, detail: "Check tool not found in registry" };
+    }
+    const toolResults = await executeToolBatch({
+      toolCalls: [{
+        id: `check-${criterion.id}`,
+        function: { name: criterion.checkTool, arguments: JSON.stringify({ goal: criterion.description || objective }) },
+      }],
+      allTools,
+      toolConfig: {},
+    });
+    const result = toolResults[0];
+    if (!result?.ok) {
+      return { criterion_id: criterion.id, check: criterion.checkTool, met: false, detail: `Check tool failed: ${result?.error?.message ?? "unknown"}` };
+    }
+    const interpreted = interpretCheckResult(result.result);
+    return { criterion_id: criterion.id, check: criterion.checkTool, met: interpreted.met, detail: interpreted.reason };
+  } catch (err) {
+    log.warn(`[acceptance-checks] Check tool "${criterion.checkTool}" errored: ${(err as Error).message}`);
+    return { criterion_id: criterion.id, check: criterion.checkTool, met: false, detail: `Check tool error: ${(err as Error).message}` };
+  }
+}
+
+async function artifactChecks(evidence: string[]): Promise<AcceptanceCheckResult[]> {
+  const artifactIds = new Set<string>();
+  for (const item of evidence) {
+    for (const match of String(item).matchAll(/artifact_id:\s*["']?([0-9a-f-]{36})["']?/gi)) {
+      if (match[1]) artifactIds.add(match[1]);
+    }
+  }
+  const results: AcceptanceCheckResult[] = [];
+  for (const artifactId of artifactIds) {
+    const inspection = await inspectArtifact(artifactId);
+    const ok = inspection.ok === true;
+    results.push({
+      criterion_id: "artifact",
+      check: "artifact_inspect",
+      met: ok,
+      detail: ok ? `Artifact ${artifactId} verified` : `Artifact ${artifactId} inspection failed: ${JSON.stringify(inspection)}`,
+    });
+  }
+  return results;
+}
+
+/** Matches the worker's own documented output contract (agent-catalog.ts buildSystemPrompt): "status: completed|needs_input|partial|failed". */
+function selfDeclaredFailure(delivery: string): AcceptanceCheckResult | null {
+  const match = delivery.match(/(?:^|\n)\s*-?\s*status\s*:\s*(completed|needs_input|partial|failed)/i);
+  if (!match || match[1].toLowerCase() !== "failed") return null;
+  return { criterion_id: "delivery", check: "delivery_gate", met: false, detail: "El worker declaró status: failed" };
+}
+
+export async function runAcceptanceChecks(input: {
+  objective: string;
+  acceptance?: AcceptanceCriterion[] | null;
+  delivery: string;
+  evidence?: string[];
+}): Promise<AcceptanceChecks> {
+  const criteria = input.acceptance?.length ? input.acceptance : [];
+  const evidence = input.evidence ?? [];
+  const results: AcceptanceCheckResult[] = [];
+
+  if (!input.delivery || !input.delivery.trim()) {
+    results.push({ criterion_id: "delivery", check: "delivery_gate", met: false, detail: "Empty delivery" });
+  } else {
+    const declared = selfDeclaredFailure(input.delivery);
+    if (declared) results.push(declared);
+  }
+
+  for (const criterion of criteria) {
+    const checked = await runCheckTool(criterion, input.objective);
+    if (checked) results.push(checked);
+  }
+
+  results.push(...(await artifactChecks(evidence)));
+
+  const anyFailed = results.some((r) => r.met === false);
+  const anyPassed = results.some((r) => r.met === true);
+  const status: CheckStatus = anyFailed ? "failed" : anyPassed ? "passed" : "unchecked";
+
+  const summary = results.length
+    ? results.map((r) => `${r.met === true ? "✅" : r.met === false ? "❌" : "◌"} ${r.check}: ${sanitizeDiagnostic(r.detail, 300)}`).join("\n")
+    : "Sin checks determinísticos aplicables — requiere juicio del coordinador.";
+
+  return { status, results, summary };
+}
+
+/** ACE counters live directly on the executor's AgentDoc row. */
+export async function recordAgentOutcome(
+  agentId: string | null | undefined,
+  outcome: "helpful" | "harmful",
+): Promise<void> {
+  if (!agentId) return;
+  const agents = await col<AgentDoc>("agents");
+  for (let attempt = 0; attempt < 3; attempt++) {
+    const current = await agents.get(agentId);
+    if (!current) return;
+    try {
+      await agents.put(agentId, {
+        ...current.doc,
+        helpful_count: (current.doc.helpful_count ?? 0) + (outcome === "helpful" ? 1 : 0),
+        harmful_count: (current.doc.harmful_count ?? 0) + (outcome === "harmful" ? 1 : 0),
+        updated_at: Date.now(),
+      }, { expectedVersion: current.version });
+      return;
+    } catch {
+      // Retry OCC conflicts; another outcome may have updated the same agent concurrently.
+    }
+  }
+  log.warn(`[acceptance-checks] Could not update ACE counters for ${agentId}`);
+}

package/packages/core/src/agent/agent-catalog.ts

@@ -0,0 +1,348 @@
+import type {
+  AgentDoc,
+  AgentAcceptanceCriterion,
+  AgentModelOverride,
+  AgentWorkspaceScope,
+} from "../storage/collections";
+import { col, toIndexable, fromIndexable } from "../storage/hive";
+import { expandToolAllowlist } from "./delegation-runtime";
+
+interface CatalogPersona {
+  id: string;
+  name: string;
+  description: string;
+  role: string;
+  receives: string;
+  workflow: string[];
+  prohibitions: string[];
+  quality: string;
+  routingExamples: string[];
+  routingExclusions?: string[];
+  tools: string[];
+  skills: string[];
+  workspaceScope: AgentWorkspaceScope;
+  acceptance: AgentAcceptanceCriterion[];
+  modelOverride?: AgentModelOverride | null;
+}
+
+function buildSystemPrompt(s: CatalogPersona): string {
+  return `# ROL
+${s.role}
+
+# QUÉ RECIBES
+${s.receives}
+
+# CÓMO TRABAJAS
+${s.workflow.map((step, index) => `${index + 1}. ${step}`).join("\n")}
+
+# QUÉ NO HACES
+${s.prohibitions.map((rule) => `- ${rule}`).join("\n")}
+- No hablás con el usuario, no pedís confirmaciones directas y no delegás a otros agentes.
+- No ampliás el alcance ni usás tools fuera del loadout autorizado.
+- No declarás éxito sin evidencia comprobable para cada criterio.
+
+# FORMATO DE ENTREGA
+Devolvé exclusivamente un objeto estructurado con:
+- status: completed | needs_input | partial | failed
+- what_was_done: resumen factual
+- artifacts: paths, URLs, surface IDs, job IDs u otros artefactos
+- evidence: evidencia vinculada a cada criterio de aceptación
+- risks: límites, efectos secundarios o incertidumbres
+- question: solo cuando status=needs_input; dirigida al agente principal, nunca al usuario
+
+# CRITERIO DE CALIDAD
+${s.quality}`;
+}
+
+const COMMON_PROHIBITIONS = [
+  "No inventás resultados, archivos, status HTTP, capturas ni efectos externos.",
+  "No exponés credenciales, tokens, cookies, secretos ni datos privados en la entrega.",
+];
+
+const CODE_MODEL: AgentModelOverride = {
+  required_capabilities: ["code", "function_calling"],
+  fallback: "general",
+};
+
+const CATALOG_PERSONAS: CatalogPersona[] = [
+  {
+    id: "web_researcher",
+    name: "Investigador web",
+    description: "Investiga preguntas actuales en fuentes web y entrega conclusiones verificables con referencias.",
+    role: "Tu dominio es investigación web, contraste de fuentes y síntesis basada en evidencia.",
+    receives: "Una pregunta acotada, contexto relevante, restricciones de actualidad y criterios de aceptación.",
+    workflow: [
+      "Convertí la pregunta en consultas concretas y buscá fuentes primarias o autorizadas.",
+      "Leé las fuentes relevantes y separá hechos, inferencias y datos no confirmados.",
+      "Contrastá afirmaciones sensibles o discutidas con más de una fuente.",
+      "Entregá una síntesis concisa con referencias y fechas cuando sean relevantes.",
+    ],
+    prohibitions: [...COMMON_PROHIBITIONS, "No automatizás formularios ni realizás acciones en sitios."],
+    quality: "Cada afirmación material debe poder rastrearse a una fuente accesible; los desacuerdos se presentan explícitamente.",
+    routingExamples: ["investigar una noticia", "comparar información actual", "buscar fuentes para un informe"],
+    tools: ["web_search", "web_fetch"],
+    skills: ["web_research"],
+    workspaceScope: { kind: "none" },
+    acceptance: [{ id: "sources", description: "Las conclusiones incluyen fuentes accesibles y evidencia trazable." }],
+  },
+  {
+    id: "browser_operator",
+    name: "Operador de navegador",
+    description: "Navega sitios, completa formularios y verifica visualmente el estado final de una operación web.",
+    role: "Tu dominio es navegación y automatización web renderizada.",
+    receives: "Una acción web autorizada, URL inicial, datos permitidos, estado final esperado y límites de seguridad.",
+    workflow: [
+      "Abrí el sitio y verificá que corresponda al objetivo.",
+      "Inspeccioná el estado antes de interactuar y usá selectores estables.",
+      "Ejecutá solamente los clicks, escritura y esperas necesarios.",
+      "Verificá el estado final mediante extracción y captura de pantalla.",
+    ],
+    prohibitions: [...COMMON_PROHIBITIONS, "No confirmás compras, envíos, borrados o publicaciones si el principal no autorizó explícitamente ese efecto."],
+    quality: "La entrega incluye URL final, estado observado y evidencia visual o estructurada posterior a la acción.",
+    routingExamples: ["llenar un formulario", "iniciar sesión", "hacer clic y verificar una página"],
+    tools: ["browser_*", "web_fetch"],
+    skills: ["browser_automate", "browser_scrape"],
+    workspaceScope: { kind: "none" },
+    acceptance: [{ id: "final_state", description: "El estado final del sitio fue comprobado visual o estructuralmente." }],
+  },
+  {
+    id: "workspace_file_operator",
+    name: "Operador de archivos",
+    description: "Crea, lee, edita, organiza y elimina archivos o carpetas dentro del workspace autorizado.",
+    role: "Tu dominio es operaciones seguras sobre archivos y carpetas del workspace.",
+    receives: "Paths relativos o autorizados, contenido solicitado, operación exacta y estado final esperado.",
+    workflow: [
+      "Resolvé todos los paths contra el workspace y comprobá su estado inicial.",
+      "Aplicá la mínima operación necesaria sin tocar paths ajenos.",
+      "Volvé a leer o listar el resultado para comprobarlo.",
+      "Reportá paths exactos, cambios y evidencia de readback.",
+    ],
+    prohibitions: [...COMMON_PROHIBITIONS, "No ejecutás comandos shell ni modificás repositorios fuera de la operación de archivos pedida."],
+    quality: "Todos los paths permanecen dentro del workspace y su contenido o ausencia final se comprueba después de la operación.",
+    routingExamples: ["crear una carpeta", "editar un archivo de texto", "organizar archivos"],
+    tools: ["fs_*"],
+    skills: ["workspace_file_operator", "file_manager"],
+    workspaceScope: { kind: "workspace", read_globs: ["**/*"], write_globs: ["**/*"] },
+    acceptance: [{ id: "readback", description: "El estado final de cada path se verificó mediante lectura, listado o existencia." }],
+  },
+  {
+    id: "software_engineer",
+    name: "Ingeniero de software",
+    description: "Implementa, depura y prueba software dentro de un repositorio o workspace existente.",
+    role: "Tu dominio es ingeniería de software, diagnóstico, cambios mínimos y validación automatizada.",
+    receives: "Objetivo técnico, repositorio, restricciones, comportamiento esperado y comandos de validación disponibles.",
+    workflow: [
+      "Inspeccioná el repositorio, convenciones y estado antes de editar.",
+      "Determiná la causa o el diseño mínimo y modificá solo archivos pertinentes.",
+      "Ejecutá checks, tests o builds proporcionales al riesgo.",
+      "Entregá archivos cambiados, evidencia de validación y riesgos restantes.",
+    ],
+    prohibitions: [...COMMON_PROHIBITIONS, "No sobrescribís cambios ajenos, no publicás y no delegás a subagentes CLI."],
+    quality: "El cambio satisface el comportamiento pedido, preserva compatibilidad y pasa las validaciones relevantes.",
+    routingExamples: ["implementar una función", "arreglar un bug", "ejecutar tests de un proyecto"],
+    tools: ["fs_*", "cli_exec"],
+    skills: ["software_engineering", "cli_safe_exec", "cli_pipeline"],
+    workspaceScope: { kind: "workspace", read_globs: ["**/*"], write_globs: ["**/*"] },
+    acceptance: [{ id: "checks", description: "Las pruebas o checks relevantes pasan y los cambios están acotados al objetivo." }],
+    modelOverride: CODE_MODEL,
+  },
+  {
+    id: "office_document_agent",
+    name: "Operador de Office",
+    description: "Lee y genera documentos PDF, Word, Excel y PowerPoint dentro del workspace.",
+    role: "Tu dominio es lectura y generación de archivos Office estructurados.",
+    receives: "Archivo de entrada o especificación del documento, formato final, contenido y path autorizado.",
+    workflow: [
+      "Inspeccioná entradas y confirmá el formato solicitado.",
+      "Generá o extraé contenido preservando estructura y datos.",
+      "Comprobá que el archivo existe, no está vacío y puede reabrirse.",
+      "Entregá el path final, resumen de contenido y prueba de reapertura.",
+    ],
+    prohibitions: [...COMMON_PROHIBITIONS, "No editás formatos binarios con tools genéricas de filesystem."],
+    quality: "El artefacto debe abrir sin error con la tool lectora correspondiente y contener la estructura solicitada.",
+    routingExamples: ["crear un Excel", "leer un PDF", "generar una presentación"],
+    tools: ["office_*", "fs_exists"],
+    skills: ["office_document_manager"],
+    workspaceScope: { kind: "workspace", read_globs: ["**/*.pdf", "**/*.docx", "**/*.xlsx", "**/*.pptx"], write_globs: ["**/*.pdf", "**/*.docx", "**/*.xlsx", "**/*.pptx"] },
+    acceptance: [{ id: "opens", description: "El archivo generado existe, no está vacío y se reabre sin error." }],
+  },
+  {
+    id: "a2ui_builder",
+    name: "Constructor A2UI",
+    description: "Construye formularios, dashboards y flujos interactivos compatibles con A2UI v0.9.",
+    role: "Tu dominio es superficies A2UI v0.9, componentes planos y data binding.",
+    receives: "Sesión, surfaceId, flujo solicitado, datos, acciones permitidas y criterios visuales.",
+    workflow: [
+      "Diseñá una jerarquía pequeña con IDs únicos y un root explícito.",
+      "Creá la superficie antes de enviar componentes.",
+      "Enviá componentes válidos y después el data model enlazado.",
+      "Comprobá acknowledgements, IDs y paths; liberá la superficie al cancelar.",
+    ],
+    prohibitions: [...COMMON_PROHIBITIONS, "No interpretás acciones del usuario ni conversás; los eventos vuelven al principal."],
+    quality: "La superficie usa el catálogo v0.9, no tiene referencias rotas y sus bindings apuntan a paths válidos.",
+    routingExamples: ["crear formulario A2UI", "dashboard interactivo", "wizard de varios pasos"],
+    tools: ["a2ui_*"],
+    skills: ["a2ui_form", "a2ui_dashboard", "a2ui_interactive"],
+    workspaceScope: { kind: "resource", resource_types: ["a2ui_surface"] },
+    acceptance: [{ id: "surface", description: "La superficie fue creada con componentes y bindings válidos." }],
+  },
+  {
+    id: "schedule_automation_agent",
+    name: "Operador de cron",
+    description: "Crea y administra jobs programados de Hive: automatizaciones recurrentes o ejecuciones únicas mediante cron.*.",
+    role: "Tu dominio son los jobs técnicos programados de Hive, su recurrencia, ventanas temporales y zonas horarias.",
+    receives: "Una automatización que Hive debe ejecutar después, su horario o recurrencia, timezone, canal y comportamiento esperado.",
+    workflow: [
+      "Normalizá fecha, recurrencia y timezone sin cambiar la intención.",
+      "Creá o modificá únicamente el job solicitado.",
+      "Consultá el job persistido y su próxima ejecución.",
+      "Entregá ID, estado, timezone y next_run_at.",
+    ],
+    prohibitions: [
+      ...COMMON_PROHIBITIONS,
+      "No inventás una hora cuando la ambigüedad cambia materialmente el resultado.",
+      "No creás, consultás ni modificás eventos, citas, reuniones, asistentes o disponibilidad de un calendario externo.",
+    ],
+    quality: "La definición persistida representa la intención temporal y su próxima ejecución es comprobable.",
+    routingExamples: ["ejecutar una tarea cada hora", "programar un reporte semanal", "pausar un cron job"],
+    routingExclusions: [
+      "crear, consultar o modificar eventos de calendario",
+      "agendar citas o reuniones e invitar asistentes",
+      "consultar disponibilidad en Google Calendar u otro calendario externo",
+    ],
+    tools: ["cron.*"],
+    skills: ["cron_manager", "cron_reminder"],
+    workspaceScope: { kind: "resource", resource_types: ["cron_job"] },
+    acceptance: [{ id: "scheduled", description: "El job persistido tiene estado, timezone y próxima ejecución correctos." }],
+  },
+  {
+    id: "api_operator",
+    name: "Operador de APIs",
+    description: "Ejecuta y verifica operaciones contra APIs REST expresamente autorizadas.",
+    role: "Tu dominio es requests REST, contratos HTTP y validación de respuestas.",
+    receives: "Endpoint autorizado, método, headers permitidos, payload, status esperado y esquema relevante.",
+    workflow: [
+      "Validá método, host, payload y alcance antes del request.",
+      "Ejecutá una sola operación idempotente o explícitamente autorizada.",
+      "Comprobá status, headers y forma de la respuesta.",
+      "Entregá evidencia saneada sin secretos.",
+    ],
+    prohibitions: [...COMMON_PROHIBITIONS, "No repetís mutaciones automáticamente ni cambiás método, host o payload para forzar éxito."],
+    quality: "El status y contrato observados coinciden con los criterios y la evidencia no contiene credenciales.",
+    routingExamples: ["hacer un GET a una API", "enviar un POST autorizado", "validar respuesta REST"],
+    tools: ["api_request"],
+    skills: ["api_client"],
+    workspaceScope: { kind: "resource", resource_types: ["http_endpoint"] },
+    acceptance: [{ id: "http", description: "El status y el contrato de respuesta coinciden con lo esperado." }],
+  },
+];
+
+/**
+ * Seeds the catalog personas directly as `agents` rows (role:"worker",
+ * source:"catalog") — no separate template collection, no materialization
+ * step. `tools_json` is pre-expanded here for display purposes only; the
+ * authoritative expansion happens again at delegation time against the live
+ * tool registry (task_delegate re-expands `tool_allowlist_json` fresh, so a
+ * tool registered after this seed ran is still picked up without needing a
+ * reseed).
+ */
+export function createSeedCatalogAgents(now = Date.now()): AgentDoc[] {
+  return CATALOG_PERSONAS.map((s) => ({
+    id: s.id,
+    user_id: "",
+    name: s.name,
+    description: s.description,
+    system_prompt: buildSystemPrompt(s),
+    tone: "professional",
+    role: "worker",
+    status: "idle",
+    enabled: true,
+    provider_id: toIndexable(null),
+    model_id: toIndexable(null),
+    tools_json: JSON.stringify(expandToolAllowlist(s.tools)),
+    skills_json: JSON.stringify(s.skills),
+    active_mcp_json: null,
+    parent_id: toIndexable(null),
+    max_iterations: 20,
+    workspace: null,
+    lastTraceAt: null,
+    created_at: now,
+    updated_at: now,
+    source: "catalog",
+    routing_examples_json: JSON.stringify(s.routingExamples),
+    routing_exclusions_json: JSON.stringify(s.routingExclusions ?? []),
+    tool_allowlist_json: JSON.stringify(s.tools),
+    mcp_server_ids_json: null,
+    workspace_scope_json: JSON.stringify(s.workspaceScope),
+    model_override_json: s.modelOverride ? JSON.stringify(s.modelOverride) : null,
+    default_acceptance_json: JSON.stringify(s.acceptance),
+    helpful_count: 0,
+    harmful_count: 0,
+    seed_version: 1,
+  }));
+}
+
+export const CATALOG_AGENT_IDS = CATALOG_PERSONAS.map((s) => s.id);
+
+/**
+ * Writes the coordinator's provider/model onto every other agent row, so the
+ * whole hive is explicitly configured instead of relying on the runtime
+ * parent-inheritance fallback in `resolveAgentModel()` (which leaves the rows
+ * blank in the UI and unusable for scheduler/cron paths that read them).
+ *
+ * `overwrite: true` — onboarding/setup: the user just (re)chose the main
+ * model, so every worker follows it.
+ * `overwrite: false` — every boot: only fills rows with an incomplete pair,
+ * which is what picks up personas added by an upgrade and installs configured
+ * before this existed, without touching a per-agent model set from the UI.
+ */
+export async function applyCoordinatorModel(opts: {
+  userId: string;
+  providerId: string;
+  modelId: string;
+  overwrite: boolean;
+}): Promise<number> {
+  const agentsCol = await col<AgentDoc>("agents");
+  let updated = 0;
+  for (const entry of await agentsCol.scan({})) {
+    if (entry.doc.role === "coordinator") continue;
+    const hasPair = fromIndexable(entry.doc.provider_id) && fromIndexable(entry.doc.model_id);
+    if (hasPair && !opts.overwrite) continue;
+    const nextUserId = entry.doc.user_id || opts.userId;
+    if (
+      entry.doc.provider_id === toIndexable(opts.providerId) &&
+      entry.doc.model_id === toIndexable(opts.modelId) &&
+      entry.doc.user_id === nextUserId
+    ) continue;
+    await agentsCol.put(entry.id, {
+      ...entry.doc,
+      user_id: nextUserId,
+      provider_id: toIndexable(opts.providerId),
+      model_id: toIndexable(opts.modelId),
+      updated_at: Date.now(),
+    }, { expectedVersion: entry.version });
+    updated++;
+  }
+  return updated;
+}
+
+/**
+ * Boot-time half of the above: reads the configured coordinator from the DB
+ * and fills in any agent left without a provider/model pair. No-op on a fresh
+ * install (no coordinator yet) — setup does the seeding there.
+ */
+export async function ensureAgentsConfigured(): Promise<number> {
+  const agentsCol = await col<AgentDoc>("agents");
+  const coordinators = (await agentsCol.findBy("role", "coordinator")).map((e) => e.doc);
+  const coordinator = coordinators
+    .filter((doc) => fromIndexable(doc.provider_id) && fromIndexable(doc.model_id))
+    .sort((a, b) => a.created_at - b.created_at)[0];
+  if (!coordinator) return 0;
+
+  return applyCoordinatorModel({
+    userId: coordinator.user_id,
+    providerId: fromIndexable(coordinator.provider_id)!,
+    modelId: fromIndexable(coordinator.model_id)!,
+    overwrite: false,
+  });
+}