@johpaz/hive-sdk 0.1.4 → 0.1.5

package/test/hive-helpers.test.ts

@@ -0,0 +1,130 @@
+/**
+ * Unit tests for the HiveDB collection helpers (storage/hive.ts) and the
+ * bootstrap entry point (storage/bootstrap.ts). Uses an in-memory database
+ * (HIVE_DB_PATH=":memory:") so no state persists between runs.
+ */
+
+process.env.HIVE_DB_PATH = ":memory:";
+
+import { describe, test, expect, beforeEach } from "bun:test";
+import { closeHiveDb } from "../packages/core/src/storage/hivedb";
+import { col, nextId, updateDoc, updateManyByIndex, findByAny, bumpRollup } from "../packages/core/src/storage/hive";
+import { ensureHiveDb, isBootstrapped } from "../packages/core/src/storage/bootstrap";
+import {
+  acknowledgeNotification,
+  createNotification,
+  listPendingNotifications,
+} from "../packages/core/src/gateway/notification-inbox";
+
+beforeEach(() => {
+  closeHiveDb();
+});
+
+describe("storage/hive.ts helpers", () => {
+  test("nextId produces a monotonically increasing, lexicographically sortable sequence", async () => {
+    const a = await nextId("test-counter");
+    const b = await nextId("test-counter");
+    const c = await nextId("test-counter");
+    expect(a < b).toBe(true);
+    expect(b < c).toBe(true);
+    expect(a).toBe("000000000000001");
+    expect(c).toBe("000000000000003");
+  });
+
+  test("nextId keeps separate counters independent", async () => {
+    const a1 = await nextId("counter-a");
+    const b1 = await nextId("counter-b");
+    const a2 = await nextId("counter-a");
+    expect(a1).toBe("000000000000001");
+    expect(b1).toBe("000000000000001");
+    expect(a2).toBe("000000000000002");
+  });
+
+  test("updateDoc merges a patch into an existing document", async () => {
+    const c = await col<{ name: string; active: boolean }>("widgets");
+    await c.put("w1", { name: "Widget", active: false });
+    const updated = await updateDoc<{ name: string; active: boolean }>("widgets", "w1", { active: true });
+    expect(updated).toEqual({ name: "Widget", active: true });
+    const fromDb = await c.get("w1");
+    expect(fromDb?.doc).toEqual({ name: "Widget", active: true });
+  });
+
+  test("updateDoc throws for a missing document", async () => {
+    await expect(updateDoc("widgets", "missing", { active: true })).rejects.toThrow("not found");
+  });
+
+  test("updateManyByIndex patches every doc matching an indexed field", async () => {
+    const c = await col<{ provider_id: string; active: boolean }>("models_test");
+    await c.createIndex("provider_id");
+    await c.put("m1", { provider_id: "openai", active: true });
+    await c.put("m2", { provider_id: "openai", active: true });
+    await c.put("m3", { provider_id: "anthropic", active: true });
+
+    const count = await updateManyByIndex<{ provider_id: string; active: boolean }>(
+      "models_test", "provider_id", "openai", { active: false }
+    );
+    expect(count).toBe(2);
+    expect((await c.get("m1"))?.doc.active).toBe(false);
+    expect((await c.get("m2"))?.doc.active).toBe(false);
+    expect((await c.get("m3"))?.doc.active).toBe(true);
+  });
+
+  test("findByAny emulates WHERE field IN (...)", async () => {
+    const c = await col<{ agent_id: string }>("bus_test");
+    await c.createIndex("agent_id");
+    await c.put("msg1", { agent_id: "a1" });
+    await c.put("msg2", { agent_id: "a2" });
+    await c.put("msg3", { agent_id: "a3" });
+
+    const rows = await findByAny<{ agent_id: string }>("bus_test", "agent_id", ["a1", "a3", "a3"]);
+    expect(rows.length).toBe(2);
+    expect(rows.map((r) => r.id).sort()).toEqual(["msg1", "msg3"]);
+  });
+
+  test("bumpRollup accumulates deltas and nested breakdowns across calls", async () => {
+    await bumpRollup("usageRollups_test", "hour:2026-07-08T10", { inputTokens: 100, costUsd: 0.5 }, { field: "byProvider", key: "openai" });
+    await bumpRollup("usageRollups_test", "hour:2026-07-08T10", { inputTokens: 50, costUsd: 0.2 }, { field: "byProvider", key: "openai" });
+    await bumpRollup("usageRollups_test", "hour:2026-07-08T10", { inputTokens: 10, costUsd: 0.1 }, { field: "byProvider", key: "anthropic" });
+
+    const c = await col<any>("usageRollups_test");
+    const doc = (await c.get("hour:2026-07-08T10"))?.doc;
+    expect(doc.inputTokens).toBe(160);
+    expect(doc.costUsd).toBeCloseTo(0.8);
+    expect(doc.byProvider.openai.inputTokens).toBe(150);
+    expect(doc.byProvider.anthropic.inputTokens).toBe(10);
+  });
+});
+
+describe("durable WebChat notification inbox", () => {
+  test("keeps a notification pending until its owner acknowledges it", async () => {
+    const notifications = await col("notifications");
+    await notifications.createIndex("user_id");
+    const notification = await createNotification({
+      userId: "user-a",
+      channel: "webchat",
+      message: "Trabajo terminado",
+    });
+
+    expect(await listPendingNotifications("user-a", "webchat")).toHaveLength(1);
+    expect(await acknowledgeNotification(notification.id, "user-b")).toBe(false);
+    expect(await listPendingNotifications("user-a", "webchat")).toHaveLength(1);
+
+    expect(await acknowledgeNotification(notification.id, "user-a")).toBe(true);
+    expect(await listPendingNotifications("user-a", "webchat")).toHaveLength(0);
+  });
+});
+
+describe("storage/bootstrap.ts", () => {
+  test("ensureHiveDb is idempotent and marks bootstrapped", async () => {
+    // Sin aserción sobre el estado inicial: `bootstrapped` es un flag de módulo
+    // que `closeHiveDb()` no resetea, así que su valor de entrada depende de si
+    // otro archivo de test ya llamó a ensureHiveDb en este mismo proceso.
+    await ensureHiveDb();
+    expect(isBootstrapped()).toBe(true);
+    await ensureHiveDb(); // second call must not throw (idempotent indexes + schemaVersion put)
+
+    const meta = await col<{ value: number }>("meta");
+    const version = await meta.get("schemaVersion");
+    expect(version?.doc.value).toBe(1);
+  });
+});

package/test/hivedb-search.test.ts

@@ -0,0 +1,189 @@
+/**
+ * HiveDB capability search — integration tests
+ *
+ * Covers the capability search layer:
+ * packages/core/src/agent/capability-search.ts on top of @johpaz/hive-db.
+ *
+ * Uses an in-memory index (HIVE_DB_PATH=":memory:") so no state
+ * touches ~/.hive.
+ */
+
+process.env.HIVE_DB_PATH = ":memory:";
+
+import { describe, test, expect, beforeAll, afterAll } from "bun:test";
+import {
+  searchCapabilities,
+  applyRelativeCutoff,
+  replaceCapabilityDocs,
+  upsertCapabilityDocs,
+  deleteCapabilitiesByServer,
+} from "../packages/core/src/agent/capability-search";
+import { closeHiveDb } from "../packages/core/src/storage/hivedb";
+
+beforeAll(async () => {
+  await replaceCapabilityDocs("tool", [
+    {
+      type: "tool",
+      rawId: "web_search",
+      name: "web_search",
+      body: "Busca en internet información actualizada, noticias e investigación",
+      tags: "web",
+    },
+    {
+      type: "tool",
+      rawId: "cron.create",
+      name: "cron.create",
+      body: "Programar tareas recurrentes, crear recordatorios y automatizar horarios",
+      tags: "scheduling",
+    },
+  ]);
+  await replaceCapabilityDocs("skill", [
+    {
+      type: "skill",
+      rawId: "reportes",
+      name: "generación de reportes",
+      body: "Genera reportes mensuales de transacciones y métricas",
+      tags: "reportes análisis",
+    },
+  ]);
+  await replaceCapabilityDocs("mcp", [
+    {
+      type: "mcp",
+      rawId: "gmail__send_email",
+      name: "send_email",
+      body: "Send an email to a recipient",
+      tags: "mcp gmail",
+      extraFilters: [{ field: "server_id", value: "gmail" }],
+    },
+    {
+      type: "mcp",
+      rawId: "github__create_issue",
+      name: "create_issue",
+      body: "Create a GitHub issue",
+      tags: "mcp github",
+      extraFilters: [{ field: "server_id", value: "github" }],
+    },
+  ]);
+});
+
+afterAll(() => {
+  closeHiveDb();
+});
+
+describe("HiveDB capability search", () => {
+  test("Spanish stemming: 'reporte' finds 'reportes'", async () => {
+    const hits = await searchCapabilities("reporte", { types: ["skill"] });
+    expect(hits.length).toBe(1);
+    expect(hits[0].rawId).toBe("reportes");
+    expect(hits[0].score).toBeGreaterThan(0);
+  });
+
+  test("accent folding: 'transaccion' finds 'transacciones'", async () => {
+    const hits = await searchCapabilities("transaccion", { types: ["skill"] });
+    expect(hits.length).toBe(1);
+    expect(hits[0].rawId).toBe("reportes");
+  });
+
+  test("raw user input with operators and punctuation never throws", async () => {
+    for (const q of [
+      '"comillas sin cerrar',
+      "¿puedes buscar (noticias) OR NOT?",
+      "a:b* ~^",
+      "***",
+    ]) {
+      const hits = await searchCapabilities(q, {});
+      expect(Array.isArray(hits)).toBe(true);
+    }
+    // And the natural-language version still matches
+    const hits = await searchCapabilities("¿puedes buscar noticias en internet?", {
+      types: ["tool"],
+    });
+    expect(hits.map((h) => h.rawId)).toContain("web_search");
+  });
+
+  test("type filter isolates result sets", async () => {
+    // "email" only exists in MCP docs
+    const mcpHits = await searchCapabilities("email", { types: ["mcp"] });
+    expect(mcpHits.length).toBe(1);
+    expect(mcpHits[0].type).toBe("mcp");
+
+    const toolHits = await searchCapabilities("email", { types: ["tool"] });
+    expect(toolHits.length).toBe(0);
+  });
+
+  test("all-types search returns namespaced hits", async () => {
+    const hits = await searchCapabilities("reportes internet email");
+    const types = new Set(hits.map((h) => h.type));
+    expect(types.has("tool")).toBe(true);
+    expect(types.has("skill")).toBe(true);
+    expect(types.has("mcp")).toBe(true);
+    for (const hit of hits) {
+      expect(hit.id).toBe(`${hit.type}:${hit.rawId}`);
+    }
+  });
+
+  test("replaceCapabilityDocs does not duplicate on re-sync", async () => {
+    // Simulate the startup sync running twice
+    await replaceCapabilityDocs("tool", [
+      {
+        type: "tool",
+        rawId: "web_search",
+        name: "web_search",
+        body: "Busca en internet información actualizada, noticias e investigación",
+        tags: "web",
+      },
+      {
+        type: "tool",
+        rawId: "cron.create",
+        name: "cron.create",
+        body: "Programar tareas recurrentes, crear recordatorios y automatizar horarios",
+        tags: "scheduling",
+      },
+    ]);
+    const hits = await searchCapabilities("internet noticias", { types: ["tool"], k: 20 });
+    const ids = hits.map((h) => h.rawId);
+    expect(new Set(ids).size).toBe(ids.length);
+    expect(ids.filter((id) => id === "web_search").length).toBe(1);
+  });
+
+  test("MCP server disconnect removes only that server's docs", async () => {
+    await deleteCapabilitiesByServer("gmail");
+
+    const emailHits = await searchCapabilities("email", { types: ["mcp"] });
+    expect(emailHits.length).toBe(0);
+
+    const githubHits = await searchCapabilities("github issue", { types: ["mcp"] });
+    expect(githubHits.map((h) => h.rawId)).toContain("github__create_issue");
+
+    // Restore for other tests
+    await upsertCapabilityDocs([
+      {
+        type: "mcp",
+        rawId: "gmail__send_email",
+        name: "send_email",
+        body: "Send an email to a recipient",
+        tags: "mcp gmail",
+        extraFilters: [{ field: "server_id", value: "gmail" }],
+      },
+    ]);
+  });
+
+  test("applyRelativeCutoff drops weak hits, keeps strong ones", () => {
+    const hits = [
+      { id: "tool:a", type: "tool" as const, rawId: "a", score: 10 },
+      { id: "tool:b", type: "tool" as const, rawId: "b", score: 5 },
+      { id: "tool:c", type: "tool" as const, rawId: "c", score: 1 },
+    ];
+    const kept = applyRelativeCutoff(hits, 0.3);
+    expect(kept.map((h) => h.rawId)).toEqual(["a", "b"]);
+    expect(applyRelativeCutoff([], 0.3)).toEqual([]);
+  });
+
+  test("selector-path latency stays under 50ms warm", async () => {
+    await searchCapabilities("warmup", { types: ["tool"] });
+    const start = performance.now();
+    await searchCapabilities("programar recordatorio diario", { types: ["tool"] });
+    const elapsed = performance.now() - start;
+    expect(elapsed).toBeLessThan(50);
+  });
+});

package/test/internal-turns.test.ts

@@ -0,0 +1,166 @@
+/**
+ * Internal-event turns (delegation fan-in) must persist as role:"user" + a
+ * `source` tag — never role:"system" — so every LLM provider that hoists
+ * ALL role:"system" messages into a single system instruction (Gemini,
+ * Anthropic) can't accidentally promote a transient delegation notice into a
+ * permanent standing instruction. See conversation-store.ts's
+ * isInternalSource/formatInternalEvent and routes/chat.ts's history filter.
+ */
+
+process.env.HIVE_DB_PATH = ":memory:";
+
+import { describe, test, expect, beforeEach, afterEach } from "bun:test";
+import { closeHiveDb } from "../packages/core/src/storage/hivedb";
+import { ensureHiveDb } from "../packages/core/src/storage/bootstrap";
+import { resetBootId } from "../packages/core/src/storage/boot-id";
+import { col } from "../packages/core/src/storage/hive";
+import {
+  addMessage,
+  getRecentMessages,
+  toAPIMessages,
+  isInternalSource,
+  formatInternalEvent,
+} from "../packages/core/src/agent/conversation-store";
+import type { ConversationDoc } from "../packages/core/src/storage/collections";
+
+beforeEach(async () => {
+  closeHiveDb();
+  resetBootId();
+  await ensureHiveDb();
+});
+
+afterEach(() => {
+  closeHiveDb();
+});
+
+describe("internal turns: persistence", () => {
+  test("addMessage with source persists role:user + the given source", async () => {
+    await addMessage("thread-a", "user", "El agente completó la tarea X.", {
+      source: "task_complete",
+    });
+
+    const conversationsCol = await col<ConversationDoc>("conversations");
+    const entries = await conversationsCol.scan({ prefix: "thread-a:" });
+    expect(entries).toHaveLength(1);
+    expect(entries[0].doc.role).toBe("user");
+    expect(entries[0].doc.source).toBe("task_complete");
+  });
+
+  test("normal messages persist source:message by default", async () => {
+    await addMessage("thread-b", "user", "hola");
+
+    const conversationsCol = await col<ConversationDoc>("conversations");
+    const entries = await conversationsCol.scan({ prefix: "thread-b:" });
+    expect(entries[0].doc.source).toBe("message");
+  });
+});
+
+describe("internal turns: serialization (toAPIMessages)", () => {
+  test("wraps internal-source content in the <hive:internal_event> marker", async () => {
+    await addMessage("thread-c", "user", "El agente completó la tarea X.", {
+      source: "task_complete",
+    });
+
+    const rows = await getRecentMessages("thread-c", 10);
+    const apiMessages = toAPIMessages(rows);
+
+    expect(apiMessages).toHaveLength(1);
+    expect(apiMessages[0].role).toBe("user");
+    expect(apiMessages[0].content).toContain('<hive:internal_event source="task_complete">');
+    expect(apiMessages[0].content).toContain("El agente completó la tarea X.");
+  });
+
+  test("leaves normal user/assistant content untouched", async () => {
+    await addMessage("thread-d", "user", "hola");
+    await addMessage("thread-d", "assistant", "¿en qué te ayudo?");
+
+    const rows = await getRecentMessages("thread-d", 10);
+    const apiMessages = toAPIMessages(rows);
+
+    expect(apiMessages[0].content).toBe("hola");
+    expect(apiMessages[1].content).toBe("¿en qué te ayudo?");
+  });
+
+  test("regression guard: a mix of user/assistant/internal rows never yields role:system", async () => {
+    await addMessage("thread-e", "user", "Delegá esto");
+    await addMessage("thread-e", "assistant", "Listo, delegado.");
+    await addMessage("thread-e", "user", "El agente completó la tarea X.", {
+      source: "task_complete",
+    });
+    await addMessage("thread-e", "assistant", "El worker terminó la tarea X.");
+
+    const rows = await getRecentMessages("thread-e", 10);
+    const apiMessages = toAPIMessages(rows);
+
+    expect(apiMessages).toHaveLength(4);
+    expect(apiMessages.every((m) => m.role !== "system")).toBe(true);
+  });
+});
+
+// El bloque "public history endpoint" de hive quedó fuera: cubre
+// `handleGetChatHistory` de gateway/routes/chat.ts, y el gateway del SDK no
+// incluye esas rutas. Lo que sí viaja es el filtro que consume la ruta —
+// `isInternalSource` / `getRecentMessages` — que se verifica más abajo.
+
+describe("internal turns: legacy role:system compat", () => {
+  async function writeLegacySystemRow(threadId: string, content: string) {
+    // Pre-`source` rows used role:"system" as the sole marker for internal
+    // events; source didn't exist yet (persisted as absent/null).
+    await addMessage(threadId, "user", content); // reserves the id/seq
+    const conversationsCol = await col<ConversationDoc>("conversations");
+    const entries = await conversationsCol.scan({ prefix: `${threadId}:` });
+    // Target the row just added, not the thread's first row — a thread may
+    // already have earlier messages when this helper runs.
+    const { id, version, doc } = entries[entries.length - 1];
+    await conversationsCol.put(id, { ...doc, role: "system", source: null }, { expectedVersion: version });
+  }
+
+  test("getRecentMessages normalizes legacy role:system rows to user/legacy_internal", async () => {
+    await writeLegacySystemRow("thread-g", "[Sistema] aviso viejo");
+
+    const rows = await getRecentMessages("thread-g", 10);
+    expect(rows).toHaveLength(1);
+    expect(rows[0].role).toBe("user");
+    expect(rows[0].source).toBe("legacy_internal");
+  });
+
+  test("toAPIMessages wraps legacy rows the same as current internal events", async () => {
+    await writeLegacySystemRow("thread-h", "[Sistema] aviso viejo");
+
+    const rows = await getRecentMessages("thread-h", 10);
+    const apiMessages = toAPIMessages(rows);
+
+    expect(apiMessages[0].role).toBe("user");
+    expect(apiMessages[0].content).toContain('<hive:internal_event source="legacy_internal">');
+  });
+
+  test("una fila legacy queda marcada como interna, así el historial público puede filtrarla", async () => {
+    await addMessage("thread-i", "user", "hola");
+    await writeLegacySystemRow("thread-i", "[Sistema] aviso viejo");
+
+    const rows = await getRecentMessages("thread-i", 10);
+    const visible = rows.filter((r) => !isInternalSource(r.source));
+
+    expect(visible).toHaveLength(1);
+    expect(visible[0].content).toBe("hola");
+  });
+});
+
+describe("isInternalSource / formatInternalEvent", () => {
+  test("recognizes task_complete, delegation_summary, legacy_internal — nothing else", () => {
+    expect(isInternalSource("task_complete")).toBe(true);
+    expect(isInternalSource("delegation_summary")).toBe(true);
+    expect(isInternalSource("legacy_internal")).toBe(true);
+    expect(isInternalSource("message")).toBe(false);
+    expect(isInternalSource("api")).toBe(false);
+    expect(isInternalSource(null)).toBe(false);
+    expect(isInternalSource(undefined)).toBe(false);
+  });
+
+  test("formatInternalEvent frames content with the source and a non-citation instruction", () => {
+    const wrapped = formatInternalEvent("task_complete", "resultado X");
+    expect(wrapped).toContain('source="task_complete"');
+    expect(wrapped).toContain("resultado X");
+    expect(wrapped).toContain("NO es un mensaje del usuario");
+  });
+});

package/test/job-idempotency.test.ts

@@ -0,0 +1,68 @@
+/**
+ * Tests for gateway/job-store.ts — idempotency_key dedup on createJob:
+ * a repeated key returns the existing job (whatever its status) instead of
+ * creating a duplicate.
+ */
+
+process.env.HIVE_DB_PATH = ":memory:";
+
+import { describe, test, expect, beforeEach, afterEach } from "bun:test";
+import { closeHiveDb } from "../packages/core/src/storage/hivedb";
+import { ensureHiveDb } from "../packages/core/src/storage/bootstrap";
+import { resetBootId } from "../packages/core/src/storage/boot-id";
+import { createJob, claimJob, completeJob, findByIdempotencyKey } from "../packages/core/src/gateway/job-store";
+import { col } from "../packages/core/src/storage/hive";
+import type { JobDoc } from "../packages/core/src/storage/collections";
+
+beforeEach(async () => {
+  closeHiveDb();
+  resetBootId();
+  await ensureHiveDb();
+});
+
+afterEach(() => {
+  closeHiveDb();
+});
+
+describe("job-store: idempotency_key", () => {
+  test("two createJob calls with the same key return the same job", async () => {
+    const first = await createJob({ lane: "s1", type: "worker_task", payload: { n: 1 }, run_id: "r1", idempotency_key: "dedupe-me" });
+    const second = await createJob({ lane: "s1", type: "worker_task", payload: { n: 2 }, run_id: "r1", idempotency_key: "dedupe-me" });
+
+    expect(second.id).toBe(first.id);
+    // Second call's payload never gets persisted — the original wins.
+    expect(JSON.parse(second.payload_json).n).toBe(1);
+
+    const c = await col<JobDoc>("jobQueue");
+    const all = await c.scan();
+    expect(all.filter((e) => e.doc.type === "worker_task").length).toBe(1);
+  });
+
+  test("returns the cached result once the original job has completed", async () => {
+    const job = await createJob({ lane: "s1", type: "worker_task", payload: {}, run_id: "r1", idempotency_key: "k1" });
+    await claimJob(job.id);
+    await completeJob(job.id, { done: true });
+
+    const repeat = await createJob({ lane: "s1", type: "worker_task", payload: {}, run_id: "r1", idempotency_key: "k1" });
+    expect(repeat.id).toBe(job.id);
+    expect(repeat.status).toBe("completed");
+    expect(JSON.parse(repeat.result_json!)).toEqual({ done: true });
+  });
+
+  test("jobs without an idempotency_key are never deduped against each other", async () => {
+    const a = await createJob({ lane: "s1", type: "worker_task", payload: {}, run_id: "r1" });
+    const b = await createJob({ lane: "s1", type: "worker_task", payload: {}, run_id: "r2" });
+    expect(a.id).not.toBe(b.id);
+  });
+
+  test("findByIdempotencyKey returns null for an unknown key", async () => {
+    const result = await findByIdempotencyKey("does-not-exist");
+    expect(result).toBeNull();
+  });
+
+  test("different keys create distinct jobs", async () => {
+    const a = await createJob({ lane: "s1", type: "worker_task", payload: {}, run_id: "r1", idempotency_key: "key-a" });
+    const b = await createJob({ lane: "s1", type: "worker_task", payload: {}, run_id: "r2", idempotency_key: "key-b" });
+    expect(a.id).not.toBe(b.id);
+  });
+});