@johpaz/hive-sdk 0.2.0 → 0.3.1

package/packages/core/src/services/skills.ts

@@ -0,0 +1,241 @@
+/**
+ * Skills — la API, no la tool.
+ *
+ * Una skill es instruccional: metadatos más un cuerpo markdown que se le inyecta
+ * al agente. No tiene `execute`, y por eso —a diferencia de una tool— **sí puede
+ * crearla un usuario desde una UI** sin abrir la puerta a ejecutar código
+ * arbitrario. hive ya lo permite por HTTP; acá esa lógica deja de estar inline
+ * en una ruta y pasa a ser una función que cualquier interfaz puede llamar.
+ *
+ * Conviven dos orígenes y no compiten:
+ *
+ *  - **Disco** — `SkillLoader` lee carpetas con `SKILL.md` desde el bundle,
+ *    `~/.hive/skills`, `extraDirs` y el workspace. Es la vía de `hives add-skill`,
+ *    versionable con git.
+ *  - **Base de datos** — la colección `skills`, que es lo que el runtime
+ *    consulta y lo que una UI edita.
+ *
+ * `importSkillFromDisk()` es el puente: materializa una skill de disco como fila
+ * editable. La BD es la fuente de verdad en runtime; el disco es de dónde vino.
+ *
+ * Cada alta, edición o borrado re-sincroniza el índice BM25: una skill que no
+ * está indexada es una skill que el modelo no encuentra.
+ */
+
+import { readFileSync, existsSync, statSync } from "node:fs";
+import { join } from "node:path";
+import { col } from "../storage/hive.ts";
+import type { SkillDoc } from "../storage/collections.ts";
+import { parseFrontmatter } from "../skills/SkillLoader.ts";
+import { syncSkillsToIndex } from "../agent/skill-selector.ts";
+import { slugify } from "./agents.ts";
+import { logger } from "../utils/logger.ts";
+
+const log = logger.child("services/skills");
+
+export interface SkillSummary {
+  id: string;
+  name: string;
+  description: string | null;
+  version: string;
+  author: string;
+  icon: string;
+  category: string;
+  /** Tools que la skill espera tener disponibles. */
+  tools: string[];
+  triggers: string[];
+  preferredAgents: string[];
+  /** El contenido markdown que se le inyecta al agente. */
+  body: string;
+  active: boolean;
+  createdAt: number;
+  updatedAt: number;
+}
+
+export interface CreateSkillInput {
+  id?: string;
+  name: string;
+  description?: string | null;
+  category?: string;
+  body: string;
+  tools?: string[];
+  triggers?: string[];
+  preferredAgents?: string[];
+  version?: string;
+  author?: string;
+  icon?: string;
+  active?: boolean;
+}
+
+export type UpdateSkillInput = Partial<Omit<CreateSkillInput, "id">>;
+
+/** Los mismos defaults que usa hive al crear una skill desde su UI. */
+const DEFAULTS = { version: "0.0.1", author: "Anonymous", icon: "🧩", category: "general" };
+
+function parseList(raw: string | null | undefined): string[] {
+  if (!raw) return [];
+  try {
+    const v = JSON.parse(raw);
+    if (Array.isArray(v)) return v.filter((x): x is string => typeof x === "string");
+  } catch {
+    // Campo legacy en texto plano separado por comas.
+  }
+  return raw.split(",").map((s) => s.trim()).filter(Boolean);
+}
+
+function toSummary(doc: SkillDoc): SkillSummary {
+  return {
+    id: doc.id,
+    name: doc.name,
+    description: doc.description,
+    version: doc.version,
+    author: doc.author,
+    icon: doc.icon,
+    category: doc.category,
+    tools: parseList(doc.tools),
+    triggers: parseList(doc.triggers),
+    preferredAgents: parseList(doc.preferred_agents),
+    body: doc.body,
+    active: doc.active,
+    createdAt: doc.created_at,
+    updatedAt: doc.updated_at,
+  };
+}
+
+async function skillsCol() {
+  return col<SkillDoc>("skills");
+}
+
+export async function createSkill(input: CreateSkillInput): Promise<SkillSummary> {
+  if (!input.name?.trim()) throw new Error("La skill necesita un nombre");
+  if (!input.body?.trim()) throw new Error("La skill necesita un cuerpo: es lo que lee el agente");
+
+  const c = await skillsCol();
+  const id = input.id ?? crypto.randomUUID();
+  if (await c.get(id)) throw new Error(`Ya existe una skill con id "${id}"`);
+
+  const now = Date.now();
+  const doc: SkillDoc = {
+    id,
+    name: input.name,
+    description: input.description ?? null,
+    version: input.version ?? DEFAULTS.version,
+    author: input.author ?? DEFAULTS.author,
+    icon: input.icon ?? DEFAULTS.icon,
+    category: input.category ?? DEFAULTS.category,
+    permissions: "[]",
+    dependencies: "[]",
+    tools: JSON.stringify(input.tools ?? []),
+    triggers: JSON.stringify(input.triggers ?? []),
+    preferred_agents: JSON.stringify(input.preferredAgents ?? []),
+    body: input.body,
+    version_num: 1,
+    active: input.active ?? true,
+    created_at: now,
+    updated_at: now,
+  };
+
+  await c.put(id, doc, { expectedVersion: 0 });
+  await syncSkillsToIndex().catch((e) => log.warn(`no pude reindexar: ${(e as Error).message}`));
+  log.info(`skill "${input.name}" creada (${id})`);
+  return toSummary(doc);
+}
+
+export async function getSkill(id: string): Promise<SkillSummary | null> {
+  const entry = await (await skillsCol()).get(id);
+  return entry ? toSummary(entry.doc) : null;
+}
+
+export async function listSkills(opts?: { includeInactive?: boolean; category?: string }): Promise<SkillSummary[]> {
+  const rows = await (await skillsCol()).scan({});
+  return rows
+    .map((e) => e.doc)
+    .filter((d) => (opts?.includeInactive ? true : d.active))
+    .filter((d) => (opts?.category ? d.category === opts.category : true))
+    .map(toSummary)
+    .sort((a, b) => a.name.localeCompare(b.name));
+}
+
+export async function updateSkill(id: string, changes: UpdateSkillInput): Promise<SkillSummary> {
+  const c = await skillsCol();
+  const entry = await c.get(id);
+  if (!entry) throw new Error(`No existe la skill "${id}"`);
+
+  const doc: SkillDoc = { ...entry.doc, updated_at: Date.now() };
+  if (changes.name !== undefined) doc.name = changes.name;
+  if (changes.description !== undefined) doc.description = changes.description;
+  if (changes.category !== undefined) doc.category = changes.category;
+  if (changes.version !== undefined) doc.version = changes.version;
+  if (changes.author !== undefined) doc.author = changes.author;
+  if (changes.icon !== undefined) doc.icon = changes.icon;
+  if (changes.active !== undefined) doc.active = changes.active;
+  if (changes.tools !== undefined) doc.tools = JSON.stringify(changes.tools);
+  if (changes.triggers !== undefined) doc.triggers = JSON.stringify(changes.triggers);
+  if (changes.preferredAgents !== undefined) doc.preferred_agents = JSON.stringify(changes.preferredAgents);
+  if (changes.body !== undefined) {
+    doc.body = changes.body;
+    // Editar el contenido es una versión nueva: es lo que cambia el comportamiento.
+    doc.version_num = (entry.doc.version_num ?? 1) + 1;
+  }
+
+  await c.put(id, doc, { expectedVersion: entry.version });
+  await syncSkillsToIndex().catch((e) => log.warn(`no pude reindexar: ${(e as Error).message}`));
+  return toSummary(doc);
+}
+
+export const toggleSkill = (id: string, active: boolean) => updateSkill(id, { active });
+
+export async function deleteSkill(id: string): Promise<boolean> {
+  const c = await skillsCol();
+  if (!(await c.get(id))) return false;
+  await c.delete(id);
+  await syncSkillsToIndex().catch((e) => log.warn(`no pude reindexar: ${(e as Error).message}`));
+  return true;
+}
+
+/**
+ * Importa una skill del disco a la base.
+ *
+ * Acepta la ruta de un `SKILL.md` o la de la carpeta que lo contiene — que es
+ * lo que produce `hives add-skill` y lo que el usuario escribe a mano. El
+ * frontmatter se parsea con el mismo `parseFrontmatter` que usa `SkillLoader`,
+ * para que disco y BD no puedan divergir en qué consideran válido.
+ *
+ * Es idempotente por id: reimportar actualiza en vez de duplicar, así se puede
+ * editar el archivo y volver a importarlo.
+ */
+export async function importSkillFromDisk(path: string): Promise<SkillSummary> {
+  const file = existsSync(path) && statSync(path).isDirectory() ? join(path, "SKILL.md") : path;
+  if (!existsSync(file)) throw new Error(`No encuentro ${file}`);
+
+  const { frontmatter, body } = parseFrontmatter(readFileSync(file, "utf-8"));
+  const fm = frontmatter as Record<string, any>;
+
+  const name = String(fm.name ?? "").trim();
+  if (!name) throw new Error(`${file} no declara \`name\` en su frontmatter`);
+  if (!body.trim()) throw new Error(`${file} no tiene cuerpo: no hay nada que inyectarle al agente`);
+
+  const id = slugify(String(fm.id ?? name));
+  const asList = (v: unknown): string[] =>
+    Array.isArray(v) ? v.map(String) : typeof v === "string" ? v.split(",").map((x) => x.trim()).filter(Boolean) : [];
+
+  const campos = {
+    name,
+    description: fm.description ? String(fm.description) : null,
+    category: fm.category ? String(fm.category) : DEFAULTS.category,
+    body,
+    tools: asList(fm.tools),
+    triggers: asList(fm.triggers),
+    preferredAgents: asList(fm.preferred_agents),
+    version: fm.version ? String(fm.version) : DEFAULTS.version,
+    author: fm.author ? String(fm.author) : DEFAULTS.author,
+    icon: fm.icon ? String(fm.icon) : DEFAULTS.icon,
+  };
+
+  const existente = await getSkill(id);
+  if (existente) {
+    log.info(`skill "${name}" reimportada desde ${file}`);
+    return updateSkill(id, campos);
+  }
+  return createSkill({ id, ...campos });
+}

package/packages/core/src/services/swarms.ts

@@ -0,0 +1,307 @@
+/**
+ * Enjambres — guardarlos, no sólo correrlos.
+ *
+ * `runRoleSwarm()` (swarm/RoleSwarm.ts) recibe los agentes en la llamada y no
+ * persiste nada: un enjambre existía sólo mientras se ejecutaba. Quien armara
+ * uno desde una interfaz lo perdía al cerrar la ventana. Ese era el bloqueador
+ * real para poner una UI encima del SDK — más que cualquier CRUD faltante.
+ *
+ * Este servicio guarda la definición y `runSwarm()` la carga y la ejecuta. La
+ * ejecución en sí no cambia: sigue siendo `runRoleSwarm`.
+ *
+ * Se valida al guardar, no al correr. Un enjambre jerárquico sin orquestador, o
+ * con un agente que ya no existe, es un error de configuración: descubrirlo
+ * cuando alguien lo ejecuta —posiblemente semanas después— es descubrirlo tarde.
+ */
+
+import { col } from "../storage/hive.ts";
+import type { SwarmDoc, SwarmMemberSpec, AgentDoc } from "../storage/collections.ts";
+import { runRoleSwarm, type RoleSwarmResult, type SwarmMessage } from "../swarm/RoleSwarm.ts";
+import type { ProviderCredentials } from "../agent/llm-client.ts";
+import { slugify } from "./agents.ts";
+import { logger } from "../utils/logger.ts";
+import { enableCatalogAgents, planActivationFor, CATALOG_AGENT_IDS, type ActivationGap } from "./setup.ts";
+
+const log = logger.child("services/swarms");
+
+export interface SwarmMember {
+  agentId: string;
+  role: "orchestrator" | "worker";
+  orderIndex: number;
+}
+
+export interface SwarmSummary {
+  id: string;
+  name: string;
+  description: string | null;
+  strategy: SwarmDoc["strategy"];
+  orchestratorAgentId: string | null;
+  members: SwarmMember[];
+  enabled: boolean;
+  maxDelegations: number | null;
+  createdAt: number;
+  updatedAt: number;
+  /**
+   * Lo que hace falta encender para que este enjambre pueda trabajar.
+   *
+   * Un enjambre puede nombrar especialistas que el usuario no activó al
+   * instalar: la fila del agente existe igual (el seed las crea todas y sólo
+   * cambia `enabled`), así que sin esto el enjambre se guardaría sin una queja
+   * y correría con agentes apagados y sus tools inactivas. Vacío = listo para
+   * correr. Sólo lo traen `createSwarm` y `updateSwarm`.
+   */
+  pendingActivation?: ActivationGap;
+}
+
+export interface CreateSwarmInput {
+  id?: string;
+  name: string;
+  description?: string | null;
+  strategy: SwarmDoc["strategy"];
+  members: Array<{ agentId: string; role?: "orchestrator" | "worker"; orderIndex?: number }>;
+  orchestratorAgentId?: string | null;
+  maxDelegations?: number | null;
+  enabled?: boolean;
+  /**
+   * Encender los especialistas del enjambre y sembrar sus tools y skills.
+   *
+   * `false` por defecto **a propósito**: crear un enjambre no debería cambiar
+   * en silencio qué capacidades tiene la instalación entera. Con `false` el
+   * enjambre se crea igual y el faltante vuelve en `pendingActivation`, para
+   * que la UI lo muestre y el usuario decida. Con `true` se activa la unión con
+   * lo que ya estaba: encender un especialista nunca apaga los de otro enjambre.
+   */
+  activateMembers?: boolean;
+}
+
+export type UpdateSwarmInput = Partial<Omit<CreateSwarmInput, "id">>;
+
+function parseMembers(json: string): SwarmMember[] {
+  try {
+    const v = JSON.parse(json);
+    return Array.isArray(v) ? (v as SwarmMemberSpec[]) : [];
+  } catch {
+    return [];
+  }
+}
+
+function toSummary(doc: SwarmDoc): SwarmSummary {
+  return {
+    id: doc.id,
+    name: doc.name,
+    description: doc.description,
+    strategy: doc.strategy,
+    orchestratorAgentId: doc.orchestrator_agent_id,
+    members: parseMembers(doc.agents_json),
+    enabled: doc.enabled,
+    maxDelegations: doc.max_delegations,
+    createdAt: doc.created_at,
+    updatedAt: doc.updated_at,
+  };
+}
+
+async function swarmsCol() {
+  return col<SwarmDoc>("swarms");
+}
+
+/**
+ * Normaliza y valida los integrantes.
+ *
+ * Un enjambre jerárquico necesita un orquestador y al menos un trabajador; los
+ * otros dos modos no admiten orquestador, porque no hay a quién delegar.
+ */
+async function normalizeMembers(
+  input: CreateSwarmInput | UpdateSwarmInput,
+  strategy: SwarmDoc["strategy"],
+): Promise<{ members: SwarmMember[]; orchestratorId: string | null }> {
+  const raw = input.members ?? [];
+  if (raw.length === 0) throw new Error("Un enjambre necesita al menos un agente");
+
+  // Un id del catálogo es válido aunque todavía no tenga fila: con el seed en
+  // `"none"` los especialistas no se crean hasta que alguien los pide, y este
+  // enjambre es justamente el pedido. La fila la crea `withActivation`.
+  // Rechazarlos acá haría imposible armar un enjambre en una instalación limpia.
+  const delCatalogo = new Set<string>(CATALOG_AGENT_IDS);
+  const agentsCol = await col<AgentDoc>("agents");
+  const faltan: string[] = [];
+  for (const m of raw) {
+    if (delCatalogo.has(m.agentId)) continue;
+    if (!(await agentsCol.get(m.agentId))) faltan.push(m.agentId);
+  }
+  if (faltan.length) throw new Error(`agentes inexistentes: ${faltan.join(", ")}`);
+
+  const members: SwarmMember[] = raw.map((m, i) => ({
+    agentId: m.agentId,
+    role: m.role ?? "worker",
+    orderIndex: m.orderIndex ?? i,
+  }));
+
+  const declarado = input.orchestratorAgentId ?? null;
+  const porRol = members.find((m) => m.role === "orchestrator")?.agentId ?? null;
+  const orchestratorId = declarado ?? porRol;
+
+  if (strategy === "hierarchical") {
+    if (!orchestratorId) throw new Error("La estrategia jerárquica necesita un orquestador");
+    if (!members.some((m) => m.role === "worker")) {
+      throw new Error("La estrategia jerárquica necesita al menos un agente con rol worker");
+    }
+    if (!members.some((m) => m.agentId === orchestratorId)) {
+      members.push({ agentId: orchestratorId, role: "orchestrator", orderIndex: -1 });
+    }
+  }
+
+  return { members, orchestratorId: strategy === "hierarchical" ? orchestratorId : null };
+}
+
+export async function createSwarm(input: CreateSwarmInput): Promise<SwarmSummary> {
+  if (!input.name?.trim()) throw new Error("El enjambre necesita un nombre");
+
+  const c = await swarmsCol();
+  const id = input.id ?? slugify(input.name);
+  if (await c.get(id)) throw new Error(`Ya existe un enjambre con id "${id}"`);
+
+  const { members, orchestratorId } = await normalizeMembers(input, input.strategy);
+  const now = Date.now();
+  const doc: SwarmDoc = {
+    id,
+    name: input.name,
+    description: input.description ?? null,
+    strategy: input.strategy,
+    orchestrator_agent_id: orchestratorId,
+    agents_json: JSON.stringify(members),
+    enabled: input.enabled ?? true,
+    max_delegations: input.maxDelegations ?? null,
+    created_at: now,
+    updated_at: now,
+  };
+
+  await c.put(id, doc, { expectedVersion: 0 });
+  log.info(`enjambre "${input.name}" guardado (${id}, ${input.strategy}, ${members.length} agentes)`);
+  return withActivation(doc, members, input.activateMembers);
+}
+
+/**
+ * Resuelve la activación de los especialistas del enjambre y adjunta el
+ * faltante al resumen.
+ *
+ * Corre DESPUÉS de guardar la fila: si el sembrado fallara a mitad, el enjambre
+ * ya está persistido y el usuario puede reintentar la activación desde la UI.
+ * Al revés perdería la definición del enjambre por un problema del catálogo.
+ */
+async function withActivation(
+  doc: SwarmDoc,
+  members: SwarmMember[],
+  activar: boolean | undefined,
+): Promise<SwarmSummary> {
+  const ids = members.map((m) => m.agentId);
+  if (activar) {
+    const gap = await planActivationFor(ids);
+    if (gap.agents.length > 0) {
+      await enableCatalogAgents(gap.agents);
+      log.info(`enjambre "${doc.id}": activados ${gap.agents.join(", ")}`);
+    }
+  }
+  // Se recalcula después de activar: así `pendingActivation` refleja lo que
+  // quedó pendiente de verdad, no lo que faltaba antes de encender nada.
+  return { ...toSummary(doc), pendingActivation: await planActivationFor(ids) };
+}
+
+export async function getSwarm(id: string): Promise<SwarmSummary | null> {
+  const entry = await (await swarmsCol()).get(id);
+  return entry ? toSummary(entry.doc) : null;
+}
+
+export async function listSwarms(opts?: { includeDisabled?: boolean }): Promise<SwarmSummary[]> {
+  const rows = await (await swarmsCol()).scan({});
+  return rows
+    .map((e) => e.doc)
+    .filter((d) => (opts?.includeDisabled ? true : d.enabled))
+    .map(toSummary)
+    .sort((a, b) => a.name.localeCompare(b.name));
+}
+
+export async function updateSwarm(id: string, changes: UpdateSwarmInput): Promise<SwarmSummary> {
+  const c = await swarmsCol();
+  const entry = await c.get(id);
+  if (!entry) throw new Error(`No existe el enjambre "${id}"`);
+
+  const doc: SwarmDoc = { ...entry.doc, updated_at: Date.now() };
+  if (changes.name !== undefined) doc.name = changes.name;
+  if (changes.description !== undefined) doc.description = changes.description;
+  if (changes.enabled !== undefined) doc.enabled = changes.enabled;
+  if (changes.maxDelegations !== undefined) doc.max_delegations = changes.maxDelegations;
+
+  const estrategia = changes.strategy ?? entry.doc.strategy;
+  if (changes.strategy !== undefined) doc.strategy = changes.strategy;
+
+  // Cambiar la estrategia revalida los integrantes: pasar a jerárquico sin
+  // orquestador tiene que fallar acá, no al ejecutarlo.
+  if (changes.members !== undefined || changes.strategy !== undefined || changes.orchestratorAgentId !== undefined) {
+    const { members, orchestratorId } = await normalizeMembers(
+      { ...changes, members: changes.members ?? parseMembers(entry.doc.agents_json) },
+      estrategia,
+    );
+    doc.agents_json = JSON.stringify(members);
+    doc.orchestrator_agent_id = orchestratorId;
+  }
+
+  await c.put(id, doc, { expectedVersion: entry.version });
+  // Agregar un especialista a un enjambre que ya existe pasa por el mismo
+  // camino que crearlo: si no, el enjambre editado quedaría con un miembro
+  // apagado y nadie se enteraría.
+  return withActivation(doc, parseMembers(doc.agents_json), changes.activateMembers);
+}
+
+export const toggleSwarm = (id: string, enabled: boolean) => updateSwarm(id, { enabled });
+
+export async function deleteSwarm(id: string): Promise<boolean> {
+  const c = await swarmsCol();
+  if (!(await c.get(id))) return false;
+  await c.delete(id);
+  // Los agentes no se tocan: pertenecen a la colmena, no al enjambre.
+  return true;
+}
+
+export interface RunSwarmOptions {
+  /** Identifica la corrida; por defecto se genera uno. */
+  runId?: string;
+  channel?: string;
+  /** Credenciales del inquilino, propagadas a cada agente. */
+  credentials?: ProviderCredentials;
+  signal?: AbortSignal;
+  /** Se llama en cada paso; acá persiste el consumidor si quiere. */
+  onMessage?: (message: SwarmMessage) => void | Promise<void>;
+}
+
+/**
+ * Carga un enjambre guardado y lo ejecuta.
+ *
+ * Un enjambre deshabilitado no corre: apagarlo tiene que significar algo, o el
+ * interruptor de la UI es decorativo.
+ */
+export async function runSwarm(
+  swarmId: string,
+  input: string,
+  opts?: RunSwarmOptions,
+): Promise<RoleSwarmResult> {
+  const swarm = await getSwarm(swarmId);
+  if (!swarm) throw new Error(`No existe el enjambre "${swarmId}"`);
+  if (!swarm.enabled) throw new Error(`El enjambre "${swarmId}" está deshabilitado`);
+
+  return runRoleSwarm({
+    agents: swarm.members.map((m) => ({
+      agentId: m.agentId,
+      role: m.role,
+      orderIndex: m.orderIndex,
+    })),
+    strategy: swarm.strategy,
+    input,
+    runId: opts?.runId ?? `swarm-${swarmId}-${Date.now()}`,
+    channel: opts?.channel,
+    orchestratorAgentId: swarm.orchestratorAgentId ?? undefined,
+    maxDelegations: swarm.maxDelegations ?? undefined,
+    credentials: opts?.credentials,
+    signal: opts?.signal,
+    onMessage: opts?.onMessage,
+  });
+}

package/packages/core/src/services/tools.ts

@@ -0,0 +1,106 @@
+/**
+ * Tools — la API, no la tool (valga la redundancia).
+ *
+ * Una tool es código con un `execute`, así que a diferencia de las skills **no
+ * se puede dar de alta una desde una UI**: no hay dónde poner el código. hive
+ * lo refleja exactamente así — su ruta expone listar, activar/desactivar y
+ * editar metadatos, pero no tiene `POST /api/tools`.
+ *
+ * Las tres vías reales para sumar capacidades son otras, y ninguna pasa por acá:
+ *  - `registerAppTool()` — código propio, para quien construye sobre el SDK.
+ *  - Un servidor MCP — proceso externo que expone sus tools (`services/mcp.ts`).
+ *  - Un endpoint HTTP declarativo (`services/endpoints.ts`), donde el ejecutor
+ *    es genérico y lo que el usuario aporta son datos, no código.
+ *
+ * Lo que este servicio sí resuelve es lo que una UI necesita a diario: ver el
+ * catálogo, encender y apagar, y corregir un nombre o una descripción.
+ */
+
+import { col } from "../storage/hive.ts";
+import type { ToolDoc } from "../storage/collections.ts";
+import { syncToolCatalogToIndex } from "../agent/tool-selector.ts";
+import { logger } from "../utils/logger.ts";
+
+const log = logger.child("services/tools");
+
+export interface ToolSummary {
+  id: string;
+  name: string;
+  description: string | null;
+  category: string | null;
+  /** `enabled` = disponible en la instalación; `active` = ofrecida ahora. */
+  enabled: boolean;
+  active: boolean;
+}
+
+function toSummary(doc: ToolDoc): ToolSummary {
+  return {
+    id: doc.id,
+    name: doc.name,
+    description: doc.description,
+    category: doc.category,
+    enabled: doc.enabled,
+    active: doc.active,
+  };
+}
+
+async function toolsCol() {
+  return col<ToolDoc>("tools");
+}
+
+export async function listTools(opts?: { category?: string; includeInactive?: boolean }): Promise<ToolSummary[]> {
+  const rows = await (await toolsCol()).scan({});
+  return rows
+    .map((e) => e.doc)
+    .filter((d) => (opts?.category ? d.category === opts.category : true))
+    .filter((d) => (opts?.includeInactive ? true : d.active))
+    .map(toSummary)
+    .sort((a, b) => a.name.localeCompare(b.name));
+}
+
+export async function getTool(id: string): Promise<ToolSummary | null> {
+  const entry = await (await toolsCol()).get(id);
+  return entry ? toSummary(entry.doc) : null;
+}
+
+/**
+ * Enciende o apaga una tool.
+ *
+ * Reindexa después: el índice BM25 es lo que consulta `search_knowledge`, y una
+ * tool apagada que siga indexada es una que el modelo encuentra y no puede usar.
+ */
+export async function toggleTool(id: string, active: boolean): Promise<ToolSummary> {
+  const c = await toolsCol();
+  const entry = await c.get(id);
+  if (!entry) throw new Error(`No existe la tool "${id}"`);
+
+  const doc: ToolDoc = { ...entry.doc, active, updated_at: Date.now() };
+  await c.put(id, doc, { expectedVersion: entry.version });
+  await syncToolCatalogToIndex().catch((e) => log.warn(`no pude reindexar: ${(e as Error).message}`));
+  return toSummary(doc);
+}
+
+/**
+ * Corrige nombre, descripción o categoría.
+ *
+ * No toca `execute`: la implementación vive en el código, no en la fila. La
+ * descripción sí importa — es lo que el modelo lee para decidir si la tool le
+ * sirve, así que cambiarla cambia el comportamiento y por eso se reindexa.
+ */
+export async function updateToolMetadata(
+  id: string,
+  changes: { name?: string; description?: string | null; category?: string | null },
+): Promise<ToolSummary> {
+  const c = await toolsCol();
+  const entry = await c.get(id);
+  if (!entry) throw new Error(`No existe la tool "${id}"`);
+
+  const doc: ToolDoc = { ...entry.doc, updated_at: Date.now() };
+  if (changes.name !== undefined) doc.name = changes.name;
+  if (changes.description !== undefined) doc.description = changes.description;
+  if (changes.category !== undefined) doc.category = changes.category;
+
+  await c.put(id, doc, { expectedVersion: entry.version });
+  await syncToolCatalogToIndex().catch((e) => log.warn(`no pude reindexar: ${(e as Error).message}`));
+  return toSummary(doc);
+}

package/packages/core/src/sessions/index.ts

@@ -22,13 +22,13 @@
 
 import type { ContentPart } from "../multimodal/types.ts"
 import type { AgentRunDoc, ConversationThreadDoc } from "../storage/collections.ts"
-import { updateDoc } from "../storage/hive.ts"
 import {
   addMessage,
   getHistory,
   type StoredMessage,
 } from "../agent/conversation-store.ts"
 import {
+  archiveThread,
   createWebConversation,
   deleteThread,
   ensureThread,
@@ -37,6 +37,7 @@ import {
   mostRecentWebThread,
   renameThread,
   threadForChannel,
+  unarchiveThread,
 } from "../agent/thread-store.ts"
 import {
   deserializeCheckpoint,
@@ -45,6 +46,7 @@ import {
 } from "../agent/run-store.ts"
 
 export * from "../agent/thread-id.ts"
+export * from "./resolve.ts"
 
 /** El estado de ejecución más reciente del hilo, si alguna vez corrió. */
 export interface SessionRun {
@@ -252,12 +254,12 @@ export async function renameSession(sessionId: string, title: string): Promise<v
  * Para borrarla de verdad, `deleteSession`.
  */
 export async function closeSession(sessionId: string): Promise<void> {
-  await updateDoc<ConversationThreadDoc>("conversationThreads", sessionId, { archived: true })
+  return archiveThread(sessionId)
 }
 
 /** Reabre una sesión archivada. */
 export async function reopenSession(sessionId: string): Promise<void> {
-  await updateDoc<ConversationThreadDoc>("conversationThreads", sessionId, { archived: false })
+  return unarchiveThread(sessionId)
 }
 
 /** Borra la sesión entera: mensajes, resumen, notas y su fila del catálogo. */