@johpaz/hive-sdk 0.1.5 → 0.2.0

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

@@ -0,0 +1,266 @@
+/**
+ * Sessions — la conversación de un usuario, como una sola cosa.
+ *
+ * Hasta acá "sesión" estaba repartida en cuatro capas que nadie unía:
+ *
+ *  - `agent/thread-store.ts`      — identidad y catálogo (`conversationThreads`)
+ *  - `agent/conversation-store.ts`— los mensajes (`conversations`, por prefijo)
+ *  - `agent/run-store.ts`         — la ejecución: checkpoint, lease, resume
+ *  - `state/store.ts`             — un `Map` en memoria que muere con el proceso
+ *
+ * El resultado eran dos identificadores para lo mismo —`thread_id` para la
+ * conversación y `run_id` para la ejecución— y ninguna forma de preguntar "qué
+ * sesiones tiene este usuario" sin escanear mensajes.
+ *
+ * Este módulo **no agrega una tercera persistencia**: `Session` es una vista
+ * compuesta sobre las colecciones que ya existen. `Session.id` ES el `threadId`.
+ * Agregar una colección propia habría recreado exactamente la duplicación que
+ * este módulo viene a cerrar.
+ *
+ * `state/store.ts` queda para métricas efímeras; no es la sesión.
+ */
+
+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 {
+  createWebConversation,
+  deleteThread,
+  ensureThread,
+  getThread,
+  listThreads,
+  mostRecentWebThread,
+  renameThread,
+  threadForChannel,
+} from "../agent/thread-store.ts"
+import {
+  deserializeCheckpoint,
+  findRunsByThread,
+  type RunCheckpointState,
+} from "../agent/run-store.ts"
+
+export * from "../agent/thread-id.ts"
+
+/** El estado de ejecución más reciente del hilo, si alguna vez corrió. */
+export interface SessionRun {
+  runId: string
+  agentId: string
+  status: AgentRunDoc["status"]
+  kind: AgentRunDoc["kind"]
+  updatedAt: number
+  /** true cuando quedó a medias y `resumeSession` puede retomarla. */
+  resumable: boolean
+}
+
+/**
+ * Una sesión: la identidad del hilo más, opcionalmente, su última ejecución.
+ * Es una vista, no una fila: se compone de `conversationThreads` + `agentRuns`.
+ */
+export interface Session {
+  /** ES el threadId (`${user}/${canal}/${peer}`). */
+  id: string
+  userId: string
+  channel: string
+  peerId: string
+  peerKind: "direct" | "group"
+  title: string | null
+  archived: boolean
+  createdAt: number
+  lastMessageAt: number
+  messageCount: number
+  lastRun?: SessionRun
+}
+
+/** Una ejecución interrumpida sigue siendo retomable; una terminada no. */
+const RESUMABLE_STATUSES: ReadonlySet<AgentRunDoc["status"]> = new Set([
+  "interrupted",
+  "running",
+])
+
+function toSessionRun(run: AgentRunDoc): SessionRun {
+  return {
+    runId: run.id,
+    agentId: run.agent_id,
+    status: run.status,
+    kind: run.kind,
+    updatedAt: run.updated_at ?? run.created_at,
+    resumable: RESUMABLE_STATUSES.has(run.status),
+  }
+}
+
+function toSession(doc: ConversationThreadDoc, lastRun?: SessionRun): Session {
+  return {
+    id: doc.id,
+    userId: doc.user_id,
+    channel: doc.channel,
+    peerId: doc.peer_id,
+    peerKind: doc.peer_kind,
+    title: doc.title,
+    archived: doc.archived,
+    createdAt: doc.created_at,
+    lastMessageAt: doc.last_message_at,
+    messageCount: doc.message_count,
+    ...(lastRun ? { lastRun } : {}),
+  }
+}
+
+/** La ejecución más reciente del hilo, o undefined si nunca corrió. */
+async function latestRun(threadId: string): Promise<SessionRun | undefined> {
+  const runs = await findRunsByThread(threadId)
+  if (runs.length === 0) return undefined
+  const newest = runs.reduce((a, b) =>
+    (b.updated_at ?? b.created_at) > (a.updated_at ?? a.created_at) ? b : a,
+  )
+  return toSessionRun(newest)
+}
+
+export interface CreateSessionInput {
+  userId: string
+  channel: string
+  peerId: string
+  peerKind?: "direct" | "group"
+}
+
+/**
+ * Abre la sesión de un usuario en un canal, o devuelve la que ya existía.
+ * Idempotente: se puede llamar en cada turno.
+ */
+export async function createSession(input: CreateSessionInput): Promise<Session> {
+  const threadId = await ensureThread(input)
+  const doc = await getThread(threadId)
+  if (!doc) throw new Error(`No se pudo abrir la sesión ${threadId}`)
+  return toSession(doc)
+}
+
+/** Una conversación nueva de la web, con su propio id (no reusa la anterior). */
+export async function createWebSession(userId: string, title?: string): Promise<Session> {
+  return toSession(await createWebConversation(userId, title))
+}
+
+export async function getSession(sessionId: string): Promise<Session | null> {
+  const doc = await getThread(sessionId)
+  if (!doc) return null
+  return toSession(doc, await latestRun(sessionId))
+}
+
+export interface ListSessionsOptions {
+  channel?: string
+  includeArchived?: boolean
+  /**
+   * Adjunta la última ejecución de cada sesión. Cuesta una consulta por sesión,
+   * así que está apagado por defecto: la lista de conversaciones no lo necesita.
+   */
+  withRuns?: boolean
+}
+
+/**
+ * Las sesiones de un usuario, de la más reciente a la más vieja.
+ *
+ * Es la consulta que antes no existía: el estado en memoria se perdía en cada
+ * reinicio y los mensajes sólo se podían leer por prefijo de un hilo conocido.
+ */
+export async function listSessions(
+  userId: string,
+  opts?: ListSessionsOptions,
+): Promise<Session[]> {
+  const docs = await listThreads(userId, {
+    channel: opts?.channel,
+    includeArchived: opts?.includeArchived,
+  })
+  if (!opts?.withRuns) return docs.map((d) => toSession(d))
+  return Promise.all(docs.map(async (d) => toSession(d, await latestRun(d.id))))
+}
+
+/** La sesión de webchat en la que el usuario seguiría escribiendo. */
+export async function mostRecentWebSession(userId: string): Promise<Session | null> {
+  const doc = await mostRecentWebThread(userId)
+  return doc ? toSession(doc) : null
+}
+
+/**
+ * La sesión por la que hablarle a alguien en un canal cuando no venimos de un
+ * mensaje suyo (un aviso de tarea programada, por ejemplo). null si no hay.
+ */
+export async function sessionForChannel(
+  userId: string,
+  channel: string,
+): Promise<string | null> {
+  return threadForChannel(userId, channel)
+}
+
+/**
+ * Agrega un mensaje y mantiene al día el catálogo (título, orden, contador):
+ * `addMessage` ya llama a `touchThread`, así que no hay que hacerlo acá.
+ *
+ * Ojo: esa actualización del catálogo es deliberadamente *fire-and-forget* —
+ * persistir el mensaje nunca se bloquea por el contador. En la práctica eso
+ * significa que `messageCount` y `title` son de consistencia eventual: leer la
+ * sesión inmediatamente después de escribir puede devolver el valor anterior.
+ * El historial (`getSessionHistory`) sí es consistente al instante.
+ */
+export async function appendMessage(
+  sessionId: string,
+  role: StoredMessage["role"],
+  content: string | ContentPart[],
+  opts?: Parameters<typeof addMessage>[3],
+): Promise<number> {
+  return addMessage(sessionId, role, content, opts)
+}
+
+export async function getSessionHistory(
+  sessionId: string,
+  limit?: number,
+): Promise<StoredMessage[]> {
+  return getHistory(sessionId, limit)
+}
+
+export interface ResumableSession {
+  run: SessionRun
+  checkpoint: RunCheckpointState
+}
+
+/**
+ * El trabajo a medias de una sesión, listo para retomar.
+ *
+ * Devuelve null cuando no hay nada que retomar — que es el caso normal. Un run
+ * `running` sin checkpoint tampoco sirve: murió antes de guardar estado.
+ */
+export async function resumeSession(sessionId: string): Promise<ResumableSession | null> {
+  const runs = await findRunsByThread(sessionId)
+  const candidates = runs
+    .filter((r) => RESUMABLE_STATUSES.has(r.status))
+    .sort((a, b) => (b.updated_at ?? b.created_at) - (a.updated_at ?? a.created_at))
+
+  for (const run of candidates) {
+    const checkpoint = deserializeCheckpoint(run)
+    if (checkpoint) return { run: toSessionRun(run), checkpoint }
+  }
+  return null
+}
+
+export async function renameSession(sessionId: string, title: string): Promise<void> {
+  return renameThread(sessionId, title)
+}
+
+/**
+ * Cierra la sesión sin perder nada: sale de la lista pero el historial queda.
+ * Para borrarla de verdad, `deleteSession`.
+ */
+export async function closeSession(sessionId: string): Promise<void> {
+  await updateDoc<ConversationThreadDoc>("conversationThreads", sessionId, { archived: true })
+}
+
+/** Reabre una sesión archivada. */
+export async function reopenSession(sessionId: string): Promise<void> {
+  await updateDoc<ConversationThreadDoc>("conversationThreads", sessionId, { archived: false })
+}
+
+/** Borra la sesión entera: mensajes, resumen, notas y su fila del catálogo. */
+export async function deleteSession(sessionId: string): Promise<void> {
+  return deleteThread(sessionId)
+}

package/packages/core/src/storage/bootstrap.ts

@@ -11,10 +11,11 @@
  * instead of `DELETE`+`INSERT`.
  */
 
-import { getHiveDb } from "./hivedb";
-import { col } from "./hive";
-import { seedAllData } from "./seed";
-import { ensureSecretsBackend } from "./crypto";
+import { getHiveDb, getOpenHiveDb } from "./hivedb.ts";
+import { col } from "./hive.ts";
+import { seedAllData } from "./seed.ts";
+import { ensureSecretsBackend } from "./crypto.ts";
+import { ensureLegacyThread } from "../agent/thread-store.ts";
 
 interface IndexSpec {
   collection: string;
@@ -102,6 +103,9 @@ const INDEXES: IndexSpec[] = [
   // Stage 7 — meeting
   { collection: "meetingSessions", field: "user_id" },
   { collection: "meetingSessions", field: "status" },
+  { collection: "conversationThreads", field: "user_id" },
+  { collection: "conversationThreads", field: "channel" },
+  { collection: "conversationThreads", field: "archived" },
 ];
 
 async function ensureIndexes(): Promise<void> {
@@ -123,7 +127,27 @@ async function ensureSeedData(): Promise<void> {
   await seedAllData();
 }
 
-let bootstrapped = false;
+// Bootstrap state belongs to a specific database instance. A boolean that
+// survives closeHiveDb() can report a closed/replaced database as ready when
+// tests or long-running processes open a fresh instance in the same runtime.
+let bootstrappedDb: Awaited<ReturnType<typeof getHiveDb>> | null = null;
+
+/**
+ * Antes de la separación por canal todos los canales compartían un solo hilo cuyo
+ * `thread_id` era el `userId`. Esa conversación se registra —sin mover un solo
+ * mensaje— como una conversación más de la web, para que siga siendo legible desde
+ * la lista. Idempotente: no hace nada si ya está registrada o si no hay historial.
+ */
+async function ensureLegacyThreads(): Promise<void> {
+  try {
+    const users = await col<{ id: string }>("users");
+    for (const user of await users.scan({})) {
+      await ensureLegacyThread(user.id);
+    }
+  } catch {
+    // Base sin usuarios todavía (onboarding pendiente) — nada que registrar.
+  }
+}
 
 /**
  * Idempotent entry point: opens the database, ensures indexes, reseeds the
@@ -131,7 +155,7 @@ let bootstrapped = false;
  * gateway boot.
  */
 export async function ensureHiveDb(): Promise<void> {
-  await getHiveDb();
+  const db = await getHiveDb();
   await ensureIndexes();
   // Mint the master key before anything can save an API key, so a fresh
   // install is durable from the first keystroke rather than after a restart
@@ -139,13 +163,15 @@ export async function ensureHiveDb(): Promise<void> {
   ensureSecretsBackend();
   await ensureSeedData();
 
+  await ensureLegacyThreads();
+
   const meta = await col<{ value: number }>("meta");
   const existing = await meta.get("schemaVersion");
   if (!existing) await meta.put("schemaVersion", { value: 1 }, { expectedVersion: 0 });
 
-  bootstrapped = true;
+  bootstrappedDb = db;
 }
 
 export function isBootstrapped(): boolean {
-  return bootstrapped;
+  return bootstrappedDb !== null && bootstrappedDb === getOpenHiveDb();
 }

package/packages/core/src/storage/causal-events.ts

@@ -6,7 +6,7 @@
  * co-located with the DB singleton accessor.
  */
 
-import { getHiveDb } from "./hivedb"
+import { getHiveDb } from "./hivedb.ts"
 import type { Event, EventPattern } from "@johpaz/hive-db"
 
 export type { Event as CausalEvent, EventPattern as CausalEventPattern }

package/packages/core/src/storage/collections.ts

@@ -40,7 +40,8 @@ export interface ModelDoc {
   id: string
   provider_id: string
   name: string
-  model_type: "llm" | "stt" | "tts" | "vision" | "embedding"
+  /** "realtime": voz full-duplex (Live API), no confundir con stt+tts encadenados. */
+  model_type: "llm" | "stt" | "tts" | "vision" | "embedding" | "realtime"
   context_window: number
   capabilities: string | null
   enabled: boolean
@@ -269,6 +270,14 @@ export interface RefreshTokenDoc {
 export type TurnSource =
   | "message" | "audio" | "a2ui" | "canvas" | "api"
   | "task_complete" | "delegation_summary"
+  /** Turno hablado en una sesión de voz en tiempo real. A diferencia de "audio"
+   *  (nota de voz: STT → turno → TTS) la voz la pone el modelo realtime, así que
+   *  el turno nunca sintetiza audio al final. */
+  | "realtime"
+  /** Charla hablada que la voz YA resolvió sin tocar la colmena. Se guarda como
+   *  contexto del hilo, nunca como pedido pendiente: tratarla como accionable
+   *  hacía que el coordinador re-delegara todo lo que se había dicho en voz. */
+  | "realtime_chat"
 
 /** What gets persisted — adds the synthetic marker for rows written before `source` existed. */
 export type MessageSource = TurnSource | "legacy_internal"
@@ -298,6 +307,28 @@ export interface SummaryDoc {
   last_message_id: string | null
 }
 
+/**
+ * Una conversación: el registro de un `conversations.thread_id`, con lo necesario
+ * para listarla en la web sin escanear los mensajes. `id` ES el threadId
+ * (`${user}/${canal}/${peer}` — ver agent/thread-id.ts), salvo la fila del hilo
+ * legacy anterior a la separación por canal, cuyo id es el userId pelado.
+ */
+export interface ConversationThreadDoc {
+  id: string
+  user_id: string
+  channel: string
+  /** Contacto/grupo del canal, o el id de conversación en la web. */
+  peer_id: string
+  peer_kind: "direct" | "group"
+  /** null hasta el primer mensaje del usuario, de donde se deriva. */
+  title: string | null
+  /** Borrado suave: sigue en la base pero no se lista ni se reabre. */
+  archived: boolean
+  created_at: number
+  last_message_at: number
+  message_count: number
+}
+
 export interface TraceDoc {
   id: string
   thread_id: string

package/packages/core/src/storage/crypto.ts

@@ -2,8 +2,8 @@ import { createCipheriv, createDecipheriv, randomBytes } from "node:crypto"
 import { existsSync, mkdirSync, readFileSync, writeFileSync } from "node:fs"
 import * as path from "node:path"
 import { getHiveDir } from "../config/loader.ts"
-import { logger } from "../utils/logger"
-import { col } from "./hive"
+import { logger } from "../utils/logger.ts"
+import { col } from "./hive.ts"
 
 const log = logger.child("crypto")
 const SERVICE = "hive"
@@ -79,6 +79,20 @@ async function _readCollectionSecret(name: string): Promise<string | null> {
   }
 }
 
+/**
+ * Olvida si el keychain del SO respondió o no.
+ *
+ * `_keychainOk` se cachea a nivel de módulo a propósito: en un servidor sin
+ * libsecret cada lectura tiraría y no tiene sentido reintentarlo. El costo es
+ * que el resultado del primer sondeo vale para todo el proceso, y un test que
+ * sustituya `Bun.secrets` por un doble queda cortocircuitado si algo ya sondeó
+ * antes y falló. Resetear acá lo vuelve a dejar sin probar.
+ */
+export function resetKeychainProbe(): void {
+  _keychainOk = null
+  _mem.clear()
+}
+
 async function _keychainGet(name: string): Promise<string | null> {
   if (_keychainOk === false) return null
   try {

package/packages/core/src/storage/hive.ts

@@ -7,7 +7,7 @@
  * SUM/AVG/GROUP BY (`bumpRollup`).
  */
 
-import { getHiveDb } from "./hivedb";
+import { getHiveDb } from "./hivedb.ts";
 
 const MAX_RETRIES = 5;
 

package/packages/core/src/storage/hivedb.ts

@@ -15,7 +15,7 @@
 import path from "node:path";
 import { HiveDB } from "@johpaz/hive-db";
 import { getHiveDir } from "../config/loader.ts";
-import { logger } from "../utils/logger";
+import { logger } from "../utils/logger.ts";
 
 const log = logger.child("hivedb");
 
@@ -48,6 +48,15 @@ export async function getHiveDb(): Promise<HiveDB> {
   return opening;
 }
 
+/**
+ * Return the currently open database without opening one.
+ * Used by lifecycle-aware consumers that need to invalidate state after a
+ * close/reopen cycle.
+ */
+export function getOpenHiveDb(): HiveDB | null {
+  return db;
+}
+
 export function closeHiveDb(): void {
   if (db) {
     try {

package/packages/core/src/storage/onboarding.ts

@@ -1,19 +1,19 @@
 import { logger } from "../utils/logger.ts";
-import { ensureHiveDb } from "./bootstrap";
-import { col, toIndexable, fromIndexable } from "./hive";
+import { ensureHiveDb } from "./bootstrap.ts";
+import { col, toIndexable, fromIndexable } from "./hive.ts";
 import {
   storeProviderApiKey,
   storeChannelConfig,
   storeMcpEnv,
   loadProviderApiKey,
   loadChannelConfig,
-} from "./crypto";
+} from "./crypto.ts";
 import { SkillLoader } from "../skills/index.ts";
 import type {
   UserDoc, ProviderDoc, ModelDoc, AgentDoc, ChannelDoc, McpServerDoc,
   UserIdentityDoc, OnboardingProgressDoc, EthicsDoc, SkillDoc, ToolDoc,
-} from "./collections";
-import { normalizeUserEmail } from "./user-email";
+} from "./collections.ts";
+import { normalizeUserEmail } from "./user-email.ts";
 
 export interface OnboardingSection {
   step: "user" | "skills" | "ethics" | "tools" | "provider" | "model" | "channel" | "mcp" | "agent" | "complete";
@@ -423,7 +423,7 @@ export async function propagateCoordinatorModel(
   providerId: string,
   modelId: string,
 ): Promise<number> {
-  const { applyCoordinatorModel } = await import("../agent/agent-catalog");
+  const { applyCoordinatorModel } = await import("../agent/agent-catalog.ts");
   const updated = await applyCoordinatorModel({ userId, providerId, modelId, overwrite: true });
   if (updated > 0) {
     log.info(`✅ ${updated} agente(s) sincronizados con el modelo del coordinador`, { providerId, modelId });

package/packages/core/src/storage/reconcile.ts

@@ -12,12 +12,12 @@
  * durable queue are activated.
  */
 
-import { col, updateDoc } from "./hive";
-import type { TaskRunDoc, MeetingSessionDoc, AgentRunDoc, JobDoc, TaskDoc } from "./collections";
-import { logger } from "../utils/logger";
+import { col, updateDoc } from "./hive.ts";
+import type { TaskRunDoc, MeetingSessionDoc, AgentRunDoc, JobDoc, TaskDoc } from "./collections.ts";
+import { logger } from "../utils/logger.ts";
 import { reclaimOrInterrupt } from "../gateway/job-store.ts";
-import { interruptRun } from "../agent/run-store";
-import { sendToUserChannel } from "../gateway/channel-notify";
+import { interruptRun } from "../agent/run-store.ts";
+import { sendToUserChannel } from "../gateway/channel-notify.ts";
 
 const log = logger.child("reconcile");