@johpaz/hive-sdk 0.1.3 → 0.1.5

package/packages/core/src/{ace/Tracer.ts → agent/tracer.ts}

@@ -1,12 +1,14 @@
 /**
  * Tracer — ACE Generator output.
  *
- * Records every agent execution to the `traces` table.
- * Fire-and-forget (non-blocking). Also updates playbook helpful/harmful counts
- * based on execution outcome.
+ * Records every agent execution to the `traces` collection.
+ * Fire-and-forget (non-blocking). Also updates the denormalized
+ * `agents.lastTraceAt` field used by the Curator's stale-worker detection.
  */
 
-import { logger } from "../utils/logger.ts"
+import { logger } from "../utils/logger"
+import { col, nextId, updateDoc } from "../storage/hive"
+import type { TraceDoc, AgentDoc } from "../storage/collections"
 
 const log = logger.child("tracer")
 
@@ -21,6 +23,9 @@ export interface TraceInput {
   errorMessage?: string | null
   durationMs?: number
   tokensUsed?: number
+  /** G9 causal stream id for this run, when the causal log is enabled. */
+  causalStreamId?: string | null
+  catalogAgentId?: string | null
 }
 
 /**
@@ -31,27 +36,32 @@ export function saveTrace(trace: TraceInput): void {
   // Run asynchronously so it never blocks the caller
   Promise.resolve().then(async () => {
     try {
-      const { getDb } = await import("../storage/SQLiteStorage.ts")
-      const db = getDb()
-
-      db.query(`
-        INSERT INTO traces
-          (thread_id, agent_id, agent_name, tool_used, input_summary,
-           output_summary, success, error_message, duration_ms, tokens_used)
-        VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?)
-      `).run(
-        trace.threadId,
-        trace.agentId,
-        trace.agentName,
-        trace.toolUsed ?? null,
-        trace.inputSummary.substring(0, 500),
-        trace.outputSummary.substring(0, 500),
-        trace.success ? 1 : 0,
-        trace.errorMessage ?? null,
-        trace.durationMs ?? null,
-        trace.tokensUsed ?? null,
-      )
+      const tracesCol = await col<TraceDoc>("traces")
+      const id = await nextId("traces")
+      const now = Date.now()
+      const agentsCol = await col<AgentDoc>("agents")
+      const agentEntry = await agentsCol.get(trace.agentId)
+      const catalogAgentId = trace.catalogAgentId ?? (agentEntry?.doc.source === "catalog" ? agentEntry.doc.id : null)
+      await tracesCol.put(id, {
+        id,
+        thread_id: trace.threadId,
+        agent_id: trace.agentId,
+        agent_name: trace.agentName,
+        tool_used: trace.toolUsed ?? null,
+        input_summary: trace.inputSummary.substring(0, 500),
+        output_summary: trace.outputSummary.substring(0, 500),
+        success: trace.success,
+        error_message: trace.errorMessage ?? null,
+        duration_ms: trace.durationMs ?? null,
+        tokens_used: trace.tokensUsed ?? null,
+        created_at: now,
+        causal_stream_id: trace.causalStreamId ?? null,
+        catalog_agent_id: catalogAgentId ?? undefined,
+      })
 
+      // Denormalized field the Curator scans for stale-worker detection,
+      // avoiding a correlated MAX(created_at) query HiveDB has no primitive for.
+      await updateDoc<AgentDoc>("agents", trace.agentId, { lastTraceAt: now }).catch(() => { /* agent may not exist */ })
       // Trigger reflector check in background
       checkReflectorTrigger().catch(() => { /* ignore */ })
     } catch (err) {
@@ -72,7 +82,7 @@ async function checkReflectorTrigger(): Promise<void> {
   _tracesSinceLastReflection = 0
 
   // Lazy import to avoid circular deps
-  const { runReflector } = await import("./Reflector.ts")
+  const { runReflector } = await import("./reflector")
   runReflector().catch((err) => {
     log.warn("[tracer] Reflector run failed:", err)
   })
@@ -88,8 +98,8 @@ export function recordLLMUsage(opts: {
 }): void {
   Promise.resolve().then(async () => {
     try {
-      const { recordUsage } = await import("../storage/usage.ts")
-      await recordUsage({
+      const { recordUsage } = await import("../storage/usage")
+      recordUsage({
         provider: opts.provider,
         model: opts.model,
         inputTokens: opts.inputTokens,

package/packages/core/src/api/createAgent.test.ts

@@ -1,19 +1,148 @@
-import { describe, it, expect, beforeAll, afterAll } from "bun:test";
-import { getDb, initializeDatabase, dbService } from "../storage/SQLiteStorage.ts";
+/**
+ * `createAgent` persiste su configuración en la fila del agente.
+ *
+ * Hasta 0.1.5 aceptaba `provider`, `model`, `maxIterations`, `workspace` y
+ * `systemPrompt` y los descartaba: construía el loop global y corría con lo que
+ * hubiera en la base. Estos tests fijan que ahora sí lleguen.
+ */
 
-describe("createAgent API", () => {
-	beforeAll(async () => {
-		await initializeDatabase();
+process.env.HIVE_DB_PATH = ":memory:";
+
+import { describe, it, expect, beforeEach, afterEach } from "bun:test";
+import { z } from "zod";
+import { closeHiveDb } from "../storage/hivedb.ts";
+import { ensureHiveDb } from "../storage/bootstrap.ts";
+import { col, fromIndexable } from "../storage/hive.ts";
+import { clearAppTools, createAllTools } from "../tools/index.ts";
+import { selectTools } from "../agent/tool-selector.ts";
+import { loadConfig } from "../config/loader.ts";
+import type { AgentDoc, ModelDoc } from "../storage/collections.ts";
+import { createAgent } from "./createAgent.ts";
+import { defineTool } from "../tools/ToolRegistry.ts";
+import { defineSkill } from "../skills/defineSkill.ts";
+
+beforeEach(async () => {
+	closeHiveDb();
+	clearAppTools();
+	await ensureHiveDb();
+});
+
+afterEach(() => {
+	clearAppTools();
+	closeHiveDb();
+});
+
+describe("createAgent", () => {
+	it("persiste provider, modelo, prompt e iteraciones en la fila del agente", async () => {
+		const agent = await createAgent({
+			name: "Test Agent",
+			provider: "anthropic",
+			model: "claude-opus-5",
+			systemPrompt: "Sos un asistente de prueba.",
+			maxIterations: 7,
+			workspace: "/tmp/ws",
+		});
+
+		expect(agent.name).toBe("Test Agent");
+		expect(agent.id).toBe("test_agent");
+
+		const agentsCol = await col<AgentDoc>("agents");
+		const row = (await agentsCol.get("test_agent"))!.doc;
+
+		expect(fromIndexable(row.provider_id)).toBe("anthropic");
+		expect(fromIndexable(row.model_id)).toBe("claude-opus-5");
+		expect(row.system_prompt).toBe("Sos un asistente de prueba.");
+		expect(row.max_iterations).toBe(7);
+		expect(row.workspace).toBe("/tmp/ws");
+	});
+
+	it("prefija el id del modelo cuando el provider es revendedor", async () => {
+		await createAgent({
+			name: "reseller",
+			provider: "modelscope",
+			model: "Qwen-Ambassador/Qwen3.8-Max",
+		});
+
+		const agentsCol = await col<AgentDoc>("agents");
+		const row = (await agentsCol.get("reseller"))!.doc;
+
+		expect(fromIndexable(row.model_id)).toBe("modelscope/Qwen-Ambassador/Qwen3.8-Max");
+	});
+
+	it("activa el modelo elegido, o resolveProviderConfig no encuentra su base_url", async () => {
+		await createAgent({ name: "activador", provider: "anthropic", model: "claude-opus-5" });
+
+		const modelsCol = await col<ModelDoc>("models");
+		const model = (await modelsCol.get("claude-opus-5"))!.doc;
+
+		expect(model.active).toBe(true);
+		expect(model.enabled).toBe(true);
+	});
+
+	it("rechaza un modelo que no está en el catálogo", async () => {
+		await expect(
+			createAgent({ name: "fantasma", provider: "anthropic", model: "claude-que-no-existe" })
+		).rejects.toThrow(/no está en el catálogo/);
+	});
+
+	it("pide provider cuando se especifica un modelo", async () => {
+		// El mismo modelo lo sirven varios providers y la clave del catálogo
+		// depende de cuál, así que adivinarlo sería elegir por el usuario.
+		await expect(createAgent({ name: "sin-provider", model: "claude-opus-5" })).rejects.toThrow(
+			/necesita también `provider`/
+		);
 	});
 
-	afterAll(() => {
-		dbService.close();
+	it("registra las tools de la app con su ejecutor, no sólo la declaración", async () => {
+		const greet = defineTool({
+			name: "greet_person",
+			description: "Saluda a alguien",
+			schema: z.object({ name: z.string().describe("a quién saludar") }),
+			execute: async (args: { name: string }) => `Hola ${args.name}`,
+		});
+
+		await createAgent({ name: "con-tools", tools: [greet] });
+
+		const registered = createAllTools(await loadConfig()).find((t) => t.name === "greet_person");
+		expect(registered, "la tool no llegó al registry que lee el context compiler").toBeDefined();
+		expect(registered!.parameters.properties).toHaveProperty("name");
+		expect(registered!.parameters.required).toEqual(["name"]);
+		expect(await registered!.execute({ name: "Ana" })).toBe("Hola Ana");
+	});
+
+	it("deja la tool de la app descubrible por búsqueda de capacidad", async () => {
+		// El loadout inicial es mínimo a propósito; el resto se encuentra vía
+		// `search_knowledge`, que corre sobre el índice BM25. Si createAgent no
+		// siembra la fila en `tools` y no reindexa, la tool tiene ejecutor pero el
+		// modelo no se entera de que existe.
+		const weather = defineTool({
+			name: "get_weather",
+			description: "Consulta el clima actual de una ciudad. Sinónimos: tiempo, temperatura, pronóstico",
+			schema: z.object({ city: z.string() }),
+			execute: async (a: { city: string }) => `Soleado en ${a.city}`,
+		});
+
+		await createAgent({ name: "descubrible", tools: [weather] });
+
+		const found = await selectTools("clima de una ciudad", undefined, 5);
+		expect(found.map((t) => t.name)).toContain("get_weather");
 	});
 
-	it("defineTool and defineSkill exports are available", async () => {
-		const { defineTool } = await import("../tools/ToolRegistry.ts");
-		const { defineSkill } = await import("../skills/defineSkill.ts");
+	it("reusa la fila al recrear un agente con el mismo nombre", async () => {
+		const first = await createAgent({ name: "estable", provider: "anthropic", model: "claude-opus-5" });
+		const second = await createAgent({ name: "estable", provider: "anthropic", model: "claude-sonnet-5" });
 
+		expect(second.id).toBe(first.id);
+
+		const agentsCol = await col<AgentDoc>("agents");
+		const all = (await agentsCol.scan({})).filter((e) => e.id === "estable");
+		expect(all).toHaveLength(1);
+		expect(fromIndexable(all[0].doc.model_id)).toBe("claude-sonnet-5");
+	});
+});
+
+describe("defineTool / defineSkill", () => {
+	it("siguen siendo funciones de declaración puras", () => {
 		const tool = defineTool({
 			name: "greet",
 			description: "Says hello",
@@ -28,21 +157,4 @@ describe("createAgent API", () => {
 		});
 		expect(skill.name).toBe("greeting-skill");
 	});
-
-	it("createAgent builds an agent instance", async () => {
-		const { createAgent } = await import("./createAgent.ts");
-		const agent = await createAgent({
-			name: "test-agent",
-			provider: "openai",
-			model: "gpt-4o-mini",
-		});
-		expect(agent.name).toBe("test-agent");
-		expect(agent.config).toBeDefined();
-	});
-
-	it("ToolRegistry can be used standalone", async () => {
-		const { ToolRegistry } = await import("../tools/ToolRegistry.ts");
-		const reg = new ToolRegistry();
-		expect(reg.size()).toBe(0);
-	});
 });

package/packages/core/src/api/createAgent.ts

@@ -1,13 +1,28 @@
+/**
+ * createAgent — la puerta de entrada del SDK.
+ *
+ * Hasta 0.1.5 esta función aceptaba `provider`, `model`, `maxIterations`,
+ * `skills` y `workspace` y los descartaba: construía el agent loop global y
+ * corría con lo que hubiera en la base. El agente terminaba respondiendo con un
+ * modelo que el llamador nunca eligió. Ahora la config se persiste en la fila
+ * del agente, que es de donde el loop resuelve provider y modelo.
+ */
+
+import { z } from "zod";
 import type { ToolDefinition } from "../tools/ToolRegistry.ts";
 import type { SkillDefinition } from "../skills/defineSkill.ts";
+import type { Tool, ToolParameter } from "../tools/types.ts";
+import type { Provider } from "../agent/providers/index.ts";
 import { logger } from "../utils/logger.ts";
 
 const log = logger.child("api");
 
 export interface AgentConfig {
 	name: string;
+	/** Id del modelo tal como lo nombra su dueño (ej. "claude-opus-5", "Qwen-Ambassador/Qwen3.8-Max"). */
 	model?: string;
-	provider?: "openai" | "anthropic" | "gemini" | "ollama";
+	/** Cualquiera de los 16 providers del catálogo. */
+	provider?: Provider;
 	systemPrompt?: string;
 	tools?: ToolDefinition[];
 	skills?: SkillDefinition[];
@@ -18,6 +33,7 @@ export interface AgentConfig {
 
 export interface Agent {
 	readonly name: string;
+	readonly id: string;
 	readonly config: AgentConfig;
 	chat(message: string, opts?: { threadId?: string; channel?: string }): AsyncGenerator<AgentEvent>;
 	run(task: string, opts?: { threadId?: string; channel?: string }): Promise<string>;
@@ -29,16 +45,54 @@ export type AgentEvent =
 	| { type: "tool_result"; name: string; result: unknown }
 	| { type: "done"; response: string };
 
+/** Id estable derivado del nombre, para que dos `createAgent` con el mismo nombre compartan historial. */
+function agentIdFrom(name: string): string {
+	const slug = name.trim().toLowerCase().replace(/[^a-z0-9]+/g, "_").replace(/^_+|_+$/g, "");
+	return slug || "agent";
+}
+
+/**
+ * Convierte una tool declarada con `defineTool` (schema de Zod) al shape que
+ * espera el runtime (JSON Schema). Sin `schema` queda sin parámetros.
+ */
+function toRuntimeTool(def: ToolDefinition): Tool {
+	let properties: Record<string, ToolParameter> = {};
+	let required: string[] = [];
+
+	if (def.schema) {
+		const json = z.toJSONSchema(def.schema) as {
+			properties?: Record<string, ToolParameter>;
+			required?: string[];
+		};
+		properties = json.properties ?? {};
+		required = json.required ?? [];
+	}
+
+	return {
+		name: def.name,
+		description: def.description,
+		parameters: { type: "object", properties, required },
+		execute: async (params, config) => def.execute(params, config),
+	};
+}
+
 export async function createAgent(config: AgentConfig): Promise<Agent> {
-	const { initializeDatabase } = await import("../storage/SQLiteStorage.ts");
-	const { createAllTools } = await import("../tools/index.ts");
+	const { ensureHiveDb } = await import("../storage/bootstrap.ts");
+	const { col, toIndexable } = await import("../storage/hive.ts");
+	const { catalogModelKey } = await import("../storage/model-id.ts");
+	const { registerAppTool } = await import("../tools/index.ts");
 	const { loadConfig } = await import("../config/loader.ts");
+	const { resolveUserId } = await import("../storage/onboarding.ts");
+	type AgentDoc = import("../storage/collections.ts").AgentDoc;
+	type ModelDoc = import("../storage/collections.ts").ModelDoc;
+	type ProviderDoc = import("../storage/collections.ts").ProviderDoc;
 
-	await initializeDatabase();
+	// Abre HiveDB, crea los índices y siembra el catálogo de providers/modelos.
+	await ensureHiveDb();
 
 	const coreConfig = await loadConfig();
 
-	// Initialize browser automation (agent-browser) if enabled
+	// Browser automation (agent-browser) si está habilitado.
 	try {
 		const { initializeBrowserService } = await import("../tools/web/browser-service.ts");
 		const browserService = initializeBrowserService(coreConfig);
@@ -47,16 +101,114 @@ export async function createAgent(config: AgentConfig): Promise<Agent> {
 		log.warn(`Browser service initialization skipped: ${(err as Error).message}`);
 	}
 
-	const allBuiltInTools = createAllTools(coreConfig);
+	// Las tools de la app necesitan dos cosas para ser usables, y hasta 0.1.5 no
+	// tenían ninguna:
+	//   1. un ejecutor en el registry que arma el context compiler, y
+	//   2. una fila en la colección `tools`, que es sobre la que corre la
+	//      búsqueda por capacidad.
+	// Sin (2) la tool existe pero el modelo no la descubre nunca: el loadout
+	// inicial es mínimo a propósito y el resto se encuentra vía `search_knowledge`.
+	if (config.tools?.length) {
+		type ToolDoc = import("../storage/collections.ts").ToolDoc;
+		const toolsCol = await col<ToolDoc>("tools");
+		const ts = Date.now();
+
+		for (const tool of config.tools) {
+			registerAppTool(toRuntimeTool(tool));
+			await toolsCol.put(tool.name, {
+				id: tool.name,
+				name: tool.name,
+				description: tool.description,
+				category: tool.category ?? "app",
+				enabled: true,
+				active: true,
+				created_at: ts,
+				updated_at: ts,
+			});
+		}
+	}
+
+	// ─── Provider y modelo ────────────────────────────────────────────────────
+	// El loop los lee de la fila del agente, así que hay que dejarlos escritos.
+	const providerId = config.provider ?? "";
+	let modelKey = "";
+
+	if (config.model) {
+		if (!providerId) {
+			throw new Error(
+				`createAgent({ model: "${config.model}" }) necesita también \`provider\`: el mismo modelo lo sirven varios providers y la clave del catálogo depende de cuál.`
+			);
+		}
+		modelKey = catalogModelKey(providerId, config.model);
+
+		const modelsCol = await col<ModelDoc>("models");
+		const modelEntry = await modelsCol.get(modelKey);
+		if (!modelEntry) {
+			throw new Error(
+				`El modelo "${config.model}" no está en el catálogo de ${providerId}. `
+				+ `Agregalo a SEED_DATA.models o elegí uno de los sembrados.`
+			);
+		}
+		// Activarlo, o `resolveProviderConfig` no encuentra base_url ni la key.
+		await modelsCol.put(
+			modelKey,
+			{ ...modelEntry.doc, enabled: true, active: true },
+			{ expectedVersion: modelEntry.version }
+		);
 
-	const customTools = (config.tools ?? []).map(t => ({
-		name: t.name,
-		description: t.description,
-		execute: t.execute,
-	}));
+		const providersCol = await col<ProviderDoc>("providers");
+		const providerEntry = await providersCol.get(providerId);
+		if (providerEntry) {
+			await providersCol.put(
+				providerId,
+				{ ...providerEntry.doc, enabled: true, active: true },
+				{ expectedVersion: providerEntry.version }
+			);
+		}
+	}
 
-	const mergedTools = [...allBuiltInTools, ...customTools];
+	// ─── Fila del agente ──────────────────────────────────────────────────────
+	const agentId = agentIdFrom(config.name);
+	const agentsCol = await col<AgentDoc>("agents");
+	const existing = await agentsCol.get(agentId);
+	const now = Date.now();
+	const userId = (await resolveUserId({})) || "default";
 
+	await agentsCol.put(
+		agentId,
+		{
+			...(existing?.doc ?? {}),
+			id: agentId,
+			user_id: existing?.doc.user_id ?? userId,
+			name: config.name,
+			description: existing?.doc.description ?? null,
+			system_prompt: config.systemPrompt ?? existing?.doc.system_prompt ?? null,
+			tone: existing?.doc.tone ?? null,
+			role: existing?.doc.role ?? "coordinator",
+			status: "idle",
+			enabled: true,
+			provider_id: toIndexable(providerId || null),
+			model_id: toIndexable(modelKey || null),
+			tools_json: existing?.doc.tools_json ?? null,
+			skills_json: existing?.doc.skills_json ?? null,
+			parent_id: toIndexable(null),
+			max_iterations: config.maxIterations ?? existing?.doc.max_iterations ?? 25,
+			workspace: config.workspace ?? existing?.doc.workspace ?? null,
+			lastTraceAt: existing?.doc.lastTraceAt ?? null,
+			created_at: existing?.doc.created_at ?? now,
+			updated_at: now,
+		} as AgentDoc,
+		existing ? { expectedVersion: existing.version } : undefined
+	);
+
+	// ─── Índice de capacidades ────────────────────────────────────────────────
+	// Sin esto el agente queda limitado al loadout mínimo para siempre: el resto
+	// de las tools y skills se descubren con `search_knowledge`, que corre sobre
+	// el índice BM25, y ese índice no se llena solo. En hive lo hace
+	// `gateway/initializer.ts` al arrancar; por la vía del SDK nadie lo llamaba.
+	await syncCapabilityIndexes();
+
+	// ─── MCP ──────────────────────────────────────────────────────────────────
 	let mcpManager = null;
 	if (config.mcpServers && Object.keys(config.mcpServers).length > 0) {
 		const { MCPClientManager } = await import("../mcp/index.ts");
@@ -79,54 +231,90 @@ export async function createAgent(config: AgentConfig): Promise<Agent> {
 		await mcpManager.initialize();
 	}
 
-	const loop = await (async () => {
-		const { buildAgentLoop } = await import("../agent/AgentRunner.ts");
-		const agentLoop = buildAgentLoop({ mcpManager });
-		return agentLoop;
-	})();
+	const { runAgent } = await import("../agent/agent-loop.ts");
 
 	return {
 		name: config.name,
+		id: agentId,
 		config,
 		async *chat(message, opts) {
 			const threadId = opts?.threadId ?? crypto.randomUUID();
-			const iter = loop.stream(
-				{ messages: [{ role: "user", content: message }] },
-				{
-					configurable: {
-						thread_id: threadId,
-						channel: opts?.channel ?? "cli",
-						system_prompt: config.systemPrompt,
-					},
-				}
-			);
-			for await (const chunk of iter) {
-				if (chunk.agent?.messages) {
-					for (const msg of chunk.agent.messages) {
-						if (msg.content && typeof msg.content === "string") {
-							yield { type: "text" as const, content: msg.content };
-						}
-						if (msg.tool_calls) {
-							for (const tc of msg.tool_calls) {
-								yield { type: "tool_call" as const, name: tc.function?.name ?? tc.name ?? "unknown", args: typeof tc.function?.arguments === "string" ? JSON.parse(tc.function.arguments) : tc.function?.arguments ?? {} };
-							}
-						}
+			let response = "";
+
+			for await (const chunk of runAgent({
+				agentId,
+				userMessage: message,
+				threadId,
+				channel: opts?.channel ?? "cli",
+				mcpManager,
+				userId,
+			})) {
+				for (const msg of chunk.agent?.messages ?? []) {
+					if (typeof msg.content === "string" && msg.content) {
+						response = msg.content;
+						yield { type: "text" as const, content: msg.content };
 					}
-				}
-				if (chunk.tools?.messages) {
-					for (const msg of chunk.tools.messages) {
-						yield { type: "tool_result" as const, name: msg.name ?? msg.tool_name ?? "unknown", result: msg.content };
+					for (const tc of msg.tool_calls ?? []) {
+						const raw = tc.function?.arguments;
+						yield {
+							type: "tool_call" as const,
+							name: tc.function?.name ?? "unknown",
+							args: typeof raw === "string" ? safeParse(raw) : (raw ?? {}),
+						};
 					}
 				}
+				for (const msg of chunk.tools?.messages ?? []) {
+					yield { type: "tool_result" as const, name: msg.name ?? "unknown", result: msg.content };
+				}
 			}
-			yield { type: "done" as const, response: "" };
+
+			yield { type: "done" as const, response };
 		},
 		async run(task, opts) {
+			// El loop emite el texto acumulado del turno, no deltas: quedarse con el
+			// último evento evita duplicar la respuesta al concatenar.
 			let response = "";
 			for await (const event of this.chat(task, opts)) {
-				if (event.type === "text") response += event.content;
+				if (event.type === "text") response = event.content;
+				if (event.type === "done" && event.response) response = event.response;
 			}
 			return response;
 		},
 	};
 }
+
+function safeParse(raw: string): Record<string, unknown> {
+	try {
+		return JSON.parse(raw);
+	} catch {
+		return {};
+	}
+}
+
+/**
+ * Llena el índice BM25 de capacidades (tools, skills, reglas de playbook,
+ * agentes del catálogo) sobre el que corre `search_knowledge`.
+ *
+ * Es el equivalente de lo que hace `gateway/initializer.ts` en hive al arrancar.
+ * Los errores no se propagan: sin índice el agente sigue funcionando con el
+ * loadout mínimo, y romper `createAgent` por una reindexación sería peor.
+ */
+export async function syncCapabilityIndexes(): Promise<void> {
+	const { syncToolsToIndex, syncSkillsToIndex, syncPlaybookToIndex } = await import(
+		"../agent/context-compiler.ts"
+	);
+	const { syncCatalogAgentsToIndex } = await import("../agent/catalog-selector.ts");
+
+	const results = await Promise.allSettled([
+		syncToolsToIndex(),
+		syncSkillsToIndex(),
+		syncPlaybookToIndex(),
+		syncCatalogAgentsToIndex(),
+	]);
+
+	for (const result of results) {
+		if (result.status === "rejected") {
+			log.warn(`Capability index sync failed: ${result.reason}`);
+		}
+	}
+}