@johpaz/hive-sdk 0.2.0 → 0.3.1

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

@@ -0,0 +1,179 @@
+/**
+ * Modelos — la API, no la ruta.
+ *
+ * Dos operaciones tienen trampa y por eso están acá y no en una consulta suelta:
+ *
+ *  - **Borrar** un modelo que algún agente usa lo dejaría apuntando a la nada,
+ *    y el fallo aparecería en el próximo turno de ese agente. Se bloquea con el
+ *    nombre de quiénes lo usan.
+ *  - **Renombrar** significa cambiar el id, así que hay que mover la fila *y*
+ *    re-apuntar a cada agente que la referenciaba, en un solo `batch()`. A
+ *    medias dejaría agentes huérfanos.
+ *
+ * El id de catálogo no es el id del wire: los revendedores (openrouter, nvidia,
+ * groq…) sirven modelos de terceros y colisionan entre sí, así que `catalogModelKey`
+ * prefija y `wireModelId` deshace el prefijo antes de salir a la API.
+ */
+
+import { col, toIndexable, fromIndexable } from "../storage/hive.ts";
+import { getHiveDb } from "../storage/hivedb.ts";
+import type { BatchOp } from "@johpaz/hive-db";
+import type { ModelDoc, AgentDoc } from "../storage/collections.ts";
+import { catalogModelKey, wireModelId } from "../storage/model-id.ts";
+import { logger } from "../utils/logger.ts";
+
+const log = logger.child("services/models");
+
+export interface ModelSummary {
+  id: string;
+  providerId: string;
+  name: string;
+  modelType: ModelDoc["model_type"];
+  contextWindow: number;
+  enabled: boolean;
+  active: boolean;
+  /** El id tal como lo espera la API del proveedor, sin el prefijo del revendedor. */
+  wireId: string;
+  source: string;
+}
+
+const toSummary = (d: ModelDoc): ModelSummary => ({
+  id: d.id,
+  providerId: d.provider_id,
+  name: d.name,
+  modelType: d.model_type,
+  contextWindow: d.context_window,
+  enabled: d.enabled,
+  active: d.active,
+  wireId: wireModelId(d.provider_id, d.id),
+  source: (d as { source?: string }).source ?? "catalog",
+});
+
+async function modelsCol() {
+  return col<ModelDoc>("models");
+}
+
+export async function listModels(opts?: {
+  providerId?: string;
+  modelType?: ModelDoc["model_type"];
+  includeInactive?: boolean;
+}): Promise<ModelSummary[]> {
+  const rows = await (await modelsCol()).scan({});
+  return rows
+    .map((e) => e.doc)
+    .filter((d) => (opts?.providerId ? d.provider_id === opts.providerId : true))
+    .filter((d) => (opts?.modelType ? d.model_type === opts.modelType : true))
+    .filter((d) => (opts?.includeInactive ? true : d.active))
+    .map(toSummary)
+    .sort((a, b) => a.name.localeCompare(b.name));
+}
+
+export async function getModel(id: string): Promise<ModelSummary | null> {
+  const entry = await (await modelsCol()).get(id);
+  return entry ? toSummary(entry.doc) : null;
+}
+
+/**
+ * Da de alta un modelo propio.
+ *
+ * Se marca `source: "discovered"` a propósito: el reseed del arranque borra y
+ * recrea sólo las filas `"catalog"`, así que un modelo agregado a mano
+ * sobrevive a los reinicios.
+ */
+export async function createModel(input: {
+  name: string;
+  providerId: string;
+  modelType?: ModelDoc["model_type"];
+  contextWindow?: number;
+  active?: boolean;
+}): Promise<ModelSummary> {
+  if (!input.name?.trim()) throw new Error("El modelo necesita un nombre");
+  if (!input.providerId?.trim()) throw new Error("El modelo necesita un proveedor");
+
+  const c = await modelsCol();
+  const id = catalogModelKey(input.providerId, input.name);
+  if (await c.get(id)) throw new Error(`Ya existe el modelo "${id}"`);
+
+  const doc = {
+    id,
+    provider_id: input.providerId,
+    name: input.name,
+    model_type: input.modelType ?? "llm",
+    context_window: input.contextWindow ?? 0,
+    capabilities: null,
+    enabled: true,
+    active: input.active ?? false,
+    source: "discovered",
+  } as ModelDoc;
+
+  await c.put(id, doc, { expectedVersion: 0 });
+  return toSummary(doc);
+}
+
+export async function toggleModel(id: string, active: boolean): Promise<ModelSummary> {
+  const c = await modelsCol();
+  const entry = await c.get(id);
+  if (!entry) throw new Error(`No existe el modelo "${id}"`);
+
+  const doc: ModelDoc = { ...entry.doc, active };
+  await c.put(id, doc, { expectedVersion: entry.version });
+  return toSummary(doc);
+}
+
+/** Los agentes que apuntan a este modelo. Es lo que bloquea un borrado. */
+export async function agentsUsingModel(id: string): Promise<string[]> {
+  const rows = await (await col<AgentDoc>("agents")).findBy("model_id", toIndexable(id));
+  return rows.map((e) => e.doc.name);
+}
+
+export async function deleteModel(id: string): Promise<boolean> {
+  const c = await modelsCol();
+  if (!(await c.get(id))) return false;
+
+  const enUso = await agentsUsingModel(id);
+  if (enUso.length > 0) {
+    throw new Error(`El modelo "${id}" lo usan: ${enUso.join(", ")}. Cámbialos antes de borrarlo`);
+  }
+
+  await c.delete(id);
+  return true;
+}
+
+/**
+ * Renombra un modelo re-apuntando a los agentes que lo usaban.
+ *
+ * Va en un solo `batch()` porque son dos escrituras que deben ocurrir juntas:
+ * si se moviera la fila sin actualizar los agentes, cada uno de ellos quedaría
+ * apuntando a un id inexistente hasta que alguien lo notara.
+ */
+export async function renameModel(id: string, nuevoNombre: string): Promise<ModelSummary> {
+  const c = await modelsCol();
+  const entry = await c.get(id);
+  if (!entry) throw new Error(`No existe el modelo "${id}"`);
+
+  const nuevoId = catalogModelKey(entry.doc.provider_id, nuevoNombre);
+  if (nuevoId !== id && (await c.get(nuevoId))) {
+    throw new Error(`Ya existe un modelo con id "${nuevoId}"`);
+  }
+
+  const doc: ModelDoc = { ...entry.doc, id: nuevoId, name: nuevoNombre };
+  const agentesCol = await col<AgentDoc>("agents");
+  const afectados = await agentesCol.findBy("model_id", toIndexable(id));
+
+  const db = await getHiveDb();
+  const ops: BatchOp[] = [
+    { op: "put", collection: "models", id: nuevoId, doc },
+    ...(nuevoId !== id ? [{ op: "delete" as const, collection: "models", id }] : []),
+    ...afectados.map((a) => ({
+      op: "put" as const,
+      collection: "agents",
+      id: a.id,
+      doc: { ...a.doc, model_id: toIndexable(nuevoId), updated_at: Date.now() },
+      expectedVersion: a.version,
+    })),
+  ];
+  await db.batch(ops);
+
+  log.info(`modelo ${id} → ${nuevoId} (${afectados.length} agente(s) re-apuntados)`);
+  return toSummary(doc);
+}

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

@@ -0,0 +1,152 @@
+/**
+ * Proveedores de modelos — la API, no la ruta.
+ *
+ * Dos cosas que una UI necesita y que en hive viven inline en
+ * `gateway/routes/providers.ts`:
+ *
+ *  1. **La cascada.** Activar o desactivar un proveedor arrastra a todos sus
+ *     modelos. Sin eso quedan modelos "activos" de un proveedor apagado, que el
+ *     selector ofrece y fallan al llamarse.
+ *  2. **La API key nunca se devuelve.** Se guarda cifrada
+ *     (`storage/crypto.ts`) y hacia afuera sólo salen `hasApiKey` y una versión
+ *     enmascarada. Una UI necesita mostrar "hay clave configurada" sin poder
+ *     leerla.
+ */
+
+import { col, updateManyByIndex } from "../storage/hive.ts";
+import type { ProviderDoc, ModelDoc } from "../storage/collections.ts";
+import {
+  storeProviderApiKey, loadProviderApiKey, maskApiKey, deleteProviderSecrets, storeProviderHeaders,
+} from "../storage/crypto.ts";
+import { logger } from "../utils/logger.ts";
+
+const log = logger.child("services/providers");
+
+export interface ProviderSummary {
+  id: string;
+  name: string;
+  baseUrl: string | null;
+  category: ProviderDoc["category"];
+  enabled: boolean;
+  active: boolean;
+  /** Nunca la clave: sólo si existe y su versión enmascarada. */
+  hasApiKey: boolean;
+  maskedApiKey: string | null;
+  numCtx: number | null;
+}
+
+async function providersCol() {
+  return col<ProviderDoc>("providers");
+}
+
+async function toSummary(doc: ProviderDoc): Promise<ProviderSummary> {
+  const key = await loadProviderApiKey(doc.id).catch(() => "");
+  return {
+    id: doc.id,
+    name: doc.name,
+    baseUrl: doc.base_url,
+    category: doc.category,
+    enabled: doc.enabled,
+    active: doc.active,
+    hasApiKey: !!key,
+    maskedApiKey: key ? maskApiKey(key) : null,
+    numCtx: doc.num_ctx,
+  };
+}
+
+export async function listProviders(opts?: { category?: ProviderDoc["category"]; includeInactive?: boolean }): Promise<ProviderSummary[]> {
+  const rows = await (await providersCol()).scan({});
+  const docs = rows
+    .map((e) => e.doc)
+    .filter((d) => (opts?.category ? d.category === opts.category : true))
+    .filter((d) => (opts?.includeInactive ? true : d.active));
+  return Promise.all(docs.map(toSummary));
+}
+
+export async function getProvider(id: string): Promise<ProviderSummary | null> {
+  const entry = await (await providersCol()).get(id);
+  return entry ? toSummary(entry.doc) : null;
+}
+
+export async function createProvider(input: {
+  id: string;
+  name: string;
+  baseUrl?: string | null;
+  category?: ProviderDoc["category"];
+  apiKey?: string;
+  numCtx?: number | null;
+}): Promise<ProviderSummary> {
+  if (!input.id?.trim()) throw new Error("El proveedor necesita un id");
+
+  const c = await providersCol();
+  if (await c.get(input.id)) throw new Error(`Ya existe el proveedor "${input.id}"`);
+
+  const doc: ProviderDoc = {
+    id: input.id,
+    name: input.name,
+    base_url: input.baseUrl ?? null,
+    category: input.category ?? "llm",
+    num_ctx: input.numCtx ?? null,
+    num_gpu: 0,
+    enabled: true,
+    active: false,
+    created_at: Date.now(),
+  };
+  await c.put(input.id, doc, { expectedVersion: 0 });
+  if (input.apiKey) await storeProviderApiKey(input.id, input.apiKey);
+  return toSummary(doc);
+}
+
+export async function updateProvider(
+  id: string,
+  changes: { name?: string; baseUrl?: string | null; apiKey?: string; headers?: Record<string, unknown>; numCtx?: number | null },
+): Promise<ProviderSummary> {
+  const c = await providersCol();
+  const entry = await c.get(id);
+  if (!entry) throw new Error(`No existe el proveedor "${id}"`);
+
+  const doc: ProviderDoc = { ...entry.doc };
+  if (changes.name !== undefined) doc.name = changes.name;
+  if (changes.baseUrl !== undefined) doc.base_url = changes.baseUrl;
+  if (changes.numCtx !== undefined) doc.num_ctx = changes.numCtx;
+  await c.put(id, doc, { expectedVersion: entry.version });
+
+  if (changes.apiKey !== undefined) await storeProviderApiKey(id, changes.apiKey);
+  if (changes.headers !== undefined) await storeProviderHeaders(id, changes.headers);
+  return toSummary(doc);
+}
+
+/**
+ * Activa o desactiva el proveedor **y todos sus modelos**.
+ *
+ * La cascada no es una comodidad: un modelo activo de un proveedor apagado
+ * aparece en el selector y falla al llamarse, porque no hay credencial ni
+ * endpoint que lo atienda.
+ */
+export async function toggleProvider(id: string, active: boolean): Promise<ProviderSummary> {
+  const c = await providersCol();
+  const entry = await c.get(id);
+  if (!entry) throw new Error(`No existe el proveedor "${id}"`);
+
+  const doc: ProviderDoc = { ...entry.doc, active, enabled: active ? true : entry.doc.enabled };
+  await c.put(id, doc, { expectedVersion: entry.version });
+
+  const n = await updateManyByIndex<ModelDoc>("models", "provider_id", id, { active });
+  log.info(`proveedor ${id} ${active ? "activado" : "desactivado"} — ${n} modelo(s) en cascada`);
+  return toSummary(doc);
+}
+
+/** Borra el proveedor y sus secretos. Falla si algún modelo suyo sigue en uso. */
+export async function deleteProvider(id: string): Promise<boolean> {
+  const c = await providersCol();
+  if (!(await c.get(id))) return false;
+
+  const modelos = await (await col<ModelDoc>("models")).findBy("provider_id", id);
+  if (modelos.length > 0) {
+    throw new Error(`El proveedor "${id}" todavía tiene ${modelos.length} modelo(s); bórralos primero`);
+  }
+
+  await c.delete(id);
+  await deleteProviderSecrets(id).catch(() => {});
+  return true;
+}

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

@@ -0,0 +1,222 @@
+/**
+ * Configuración inicial de la colmena — elegir qué agentes se siembran.
+ *
+ * `seedAllData()` es todo o nada: siembra las 8 personas del catálogo en cada
+ * arranque, con sus tools y skills, quiera el usuario o no. Para un producto
+ * donde cada quien arma su enjambre eso es demasiado: alguien que sólo quiere un
+ * investigador web se lleva el ingeniero de software y el operador de navegador.
+ *
+ * Este módulo permite elegir. Y lo que hace no es "sembrar sólo lo de este
+ * agente", que es el error obvio: **las tools se comparten**. `web_fetch` lo
+ * declaran el investigador web y el operador de navegador; `fs_*`, el operador
+ * de archivos y el ingeniero. Se siembra la **unión** de lo que requieren los
+ * agentes elegidos, más las `MINIMAL_TOOLS` que el coordinador necesita siempre.
+ *
+ * Y al revés: **desactivar un agente no borra nada**. Las filas de `tools` y
+ * `skills` son globales y compartidas; borrar las de uno rompería a otro. Se
+ * marca el agente y se recalcula la unión.
+ */
+
+import { col } from "../storage/hive.ts";
+import type { AgentDoc, ToolDoc, SkillDoc } from "../storage/collections.ts";
+import {
+  CATALOG_AGENT_IDS, createSeedCatalogAgents, requiredCapabilitiesFor, listCatalogPersonas,
+} from "../agent/agent-catalog.ts";
+import { MINIMAL_TOOLS } from "../agent/minimal-loadout.ts";
+import { expandToolAllowlist } from "../agent/delegation-runtime.ts";
+import { syncToolCatalogToIndex } from "../agent/tool-selector.ts";
+import { syncSkillsToIndex } from "../agent/skill-selector.ts";
+import { logger } from "../utils/logger.ts";
+
+const log = logger.child("services/setup");
+
+export { listCatalogPersonas, CATALOG_AGENT_IDS };
+
+export interface SeedPlan {
+  /** Agentes de catálogo que quedarán activos. */
+  agents: string[];
+  /** Tools que hacen falta: unión de las de los agentes + las mínimas. */
+  tools: string[];
+  /** Skills que hacen falta: unión de las de los agentes. */
+  skills: string[];
+}
+
+/**
+ * Calcula qué haría falta sembrar para un conjunto de agentes, sin tocar nada.
+ *
+ * Existe separado de `applySeedPlan` para que una UI pueda mostrar "esto es lo
+ * que se va a instalar" antes de que el usuario confirme.
+ */
+export function planSeedFor(agentIds: string[]): SeedPlan {
+  const { toolPatterns, skills } = requiredCapabilitiesFor(agentIds);
+
+  // Los patrones se expanden contra el registro vivo: `fs_*` no es una tool,
+  // son varias, y hay que sembrarlas todas.
+  const delCatalogo = expandToolAllowlist(toolPatterns);
+
+  // Las mínimas van siempre: son la competencia del coordinador —delegar,
+  // buscar, avisar— y sin ellas no hay colmena, haya los agentes que haya.
+  const tools = [...new Set([...MINIMAL_TOOLS, ...delCatalogo])];
+
+  return { agents: [...new Set(agentIds)], tools, skills };
+}
+
+/**
+ * Deja activo exactamente el conjunto de agentes pedido.
+ *
+ * Las tools y skills que no hagan falta se **desactivan**, nunca se borran: otro
+ * agente —o uno que el usuario active mañana— puede necesitarlas, y una fila
+ * borrada habría que volver a sembrarla desde el código.
+ */
+export async function applySeedPlan(agentIds: string[]): Promise<SeedPlan> {
+  const plan = planSeedFor(agentIds);
+  const elegidos = new Set(plan.agents);
+  const necesarias = new Set(plan.tools);
+  const skillsNecesarias = new Set(plan.skills);
+
+  // ── Agentes ────────────────────────────────────────────────────────────────
+  const agentsCol = await col<AgentDoc>("agents");
+  const semillas = createSeedCatalogAgents();
+  for (const semilla of semillas) {
+    const quiere = elegidos.has(semilla.id);
+    const existente = await agentsCol.get(semilla.id);
+
+    if (!existente) {
+      // Los no elegidos no se crean: sembrarlos apagados llenaría la lista de
+      // agentes que el usuario nunca pidió.
+      if (!quiere) continue;
+      await agentsCol.put(semilla.id, semilla, { expectedVersion: 0 });
+      continue;
+    }
+    if (existente.doc.enabled !== quiere) {
+      await agentsCol.put(semilla.id, { ...existente.doc, enabled: quiere, updated_at: Date.now() },
+        { expectedVersion: existente.version });
+    }
+  }
+
+  // ── Tools ──────────────────────────────────────────────────────────────────
+  const toolsCol = await col<ToolDoc>("tools");
+  let encendidas = 0, apagadas = 0;
+  for (const entry of await toolsCol.scan({})) {
+    const debeEstar = necesarias.has(entry.doc.name);
+    if (entry.doc.active === debeEstar) continue;
+    await toolsCol.put(entry.id, { ...entry.doc, active: debeEstar, updated_at: Date.now() },
+      { expectedVersion: entry.version });
+    debeEstar ? encendidas++ : apagadas++;
+  }
+
+  // ── Skills ─────────────────────────────────────────────────────────────────
+  const skillsCol = await col<SkillDoc>("skills");
+  for (const entry of await skillsCol.scan({})) {
+    const debeEstar = skillsNecesarias.has(entry.doc.id) || skillsNecesarias.has(entry.doc.name);
+    if (entry.doc.active === debeEstar) continue;
+    await skillsCol.put(entry.id, { ...entry.doc, active: debeEstar, updated_at: Date.now() },
+      { expectedVersion: entry.version });
+  }
+
+  await syncToolCatalogToIndex().catch((e) => log.warn(`no pude reindexar tools: ${(e as Error).message}`));
+  await syncSkillsToIndex().catch((e) => log.warn(`no pude reindexar skills: ${(e as Error).message}`));
+
+  log.info(
+    `colmena configurada: ${plan.agents.length} agente(s), ` +
+    `${plan.tools.length} tool(s) activas (+${encendidas}/-${apagadas})`,
+  );
+  return plan;
+}
+
+/**
+ * Activa varios agentes del catálogo de una vez y siembra lo que les falte.
+ *
+ * Recalcula la unión con los que ya estaban: activar uno nunca puede apagar las
+ * tools de otro. Existe en plural porque activarlos de a uno recalcularía y
+ * reescribiría el catálogo entero una vez por agente — al armar un enjambre de
+ * cinco especialistas, cinco pasadas sobre todas las tools y skills.
+ */
+export async function enableCatalogAgents(agentIds: string[]): Promise<SeedPlan> {
+  const activos = await listEnabledCatalogAgents();
+  return applySeedPlan([...new Set([...activos, ...agentIds])]);
+}
+
+/**
+ * Activa un agente del catálogo y siembra lo que le falte.
+ */
+export async function enableCatalogAgent(agentId: string): Promise<SeedPlan> {
+  return enableCatalogAgents([agentId]);
+}
+
+/** Lo que falta activar para que un conjunto de agentes pueda trabajar. */
+export interface ActivationGap {
+  /** Agentes de catálogo pedidos que hoy están apagados. */
+  agents: string[];
+  /** Tools que necesitan y hoy están inactivas. */
+  tools: string[];
+  /** Skills que necesitan y hoy están inactivas. */
+  skills: string[];
+  /** Miembros que no son del catálogo: traen sus propias tools, no se siembran. */
+  nonCatalog: string[];
+}
+
+/**
+ * Qué habría que encender para estos agentes, **sin encender nada**.
+ *
+ * Es el `planSeedFor` de un cambio concreto: devuelve el faltante contra lo que
+ * ya está activo, no el conjunto entero. Una UI lo usa para mostrar "esto se va
+ * a activar" antes de que el usuario confirme, que es la diferencia entre que
+ * el usuario decida y que el sistema decida por él.
+ */
+export async function planActivationFor(agentIds: string[]): Promise<ActivationGap> {
+  const catalogo = new Set<string>(CATALOG_AGENT_IDS);
+  const delCatalogo = [...new Set(agentIds.filter((id) => catalogo.has(id)))];
+  const nonCatalog = [...new Set(agentIds.filter((id) => !catalogo.has(id)))];
+
+  const activos = await listEnabledCatalogAgents();
+  const apagados = delCatalogo.filter((id) => !activos.includes(id));
+
+  if (apagados.length === 0) {
+    return { agents: [], tools: [], skills: [], nonCatalog };
+  }
+
+  // El faltante se calcula contra la unión final —los que ya estaban más los
+  // nuevos—, no sólo contra los nuevos: una tool que ya está activa porque otro
+  // agente la usa no es algo que "se vaya a activar", y listarla haría que la
+  // UI le prometa al usuario cambios que no van a ocurrir.
+  const plan = planSeedFor([...new Set([...activos, ...delCatalogo])]);
+
+  const toolsCol = await col<ToolDoc>("tools");
+  const tools: string[] = [];
+  for (const nombre of plan.tools) {
+    const entry = await toolsCol.get(nombre);
+    if (!entry?.doc.active) tools.push(nombre);
+  }
+
+  const skillsCol = await col<SkillDoc>("skills");
+  const activas = new Set<string>();
+  for (const entry of await skillsCol.scan({})) {
+    if (entry.doc.active) { activas.add(entry.doc.id); activas.add(entry.doc.name); }
+  }
+  const skills = plan.skills.filter((s) => !activas.has(s));
+
+  return { agents: apagados, tools, skills, nonCatalog };
+}
+
+/**
+ * Desactiva un agente del catálogo.
+ *
+ * Las tools que compartía con otros siguen activas — es la razón de recalcular
+ * la unión en vez de quitar las suyas.
+ */
+export async function disableCatalogAgent(agentId: string): Promise<SeedPlan> {
+  const activos = await listEnabledCatalogAgents();
+  return applySeedPlan(activos.filter((id) => id !== agentId));
+}
+
+/** Los agentes de catálogo actualmente habilitados. */
+export async function listEnabledCatalogAgents(): Promise<string[]> {
+  const c = await col<AgentDoc>("agents");
+  const ids: string[] = [];
+  for (const id of CATALOG_AGENT_IDS) {
+    const entry = await c.get(id);
+    if (entry?.doc.enabled) ids.push(id);
+  }
+  return ids;
+}