@johpaz/hive-sdk 0.2.0 → 0.3.0

package/packages/core/src/scheduler/cron/zoned-time.ts

@@ -0,0 +1,138 @@
+/**
+ * Reloj de pared ↔ instante, en una zona horaria IANA.
+ *
+ * Es la parte difícil de un cron con zona horaria y la razón por la que no
+ * alcanza con `Bun.cron.parse()`, que sólo trabaja en UTC. "Todos los días a
+ * las 9" significa las 9 **del reloj de la pared en Bogotá**, y ese instante se
+ * corre una hora dos veces al año en las zonas con horario de verano. Calcular
+ * el offset una sola vez y sumarlo produce un cron que se desfasa un día al año
+ * en marzo y otro en octubre — el tipo de error que aparece un domingo a las
+ * 2am y nadie sabe de dónde salió.
+ *
+ * Acá no se guarda ningún offset: se le pregunta a `Intl` en cada conversión,
+ * que es la única fuente que conoce las reglas de cada zona y sus cambios.
+ */
+
+/** Los campos que muestra un reloj colgado en la pared de esa zona. */
+export interface WallClock {
+  year: number
+  /** 1-12, no 0-11: acá no hay meses de base cero. */
+  month: number
+  day: number
+  hour: number
+  minute: number
+  second: number
+}
+
+/** Día de la semana, 0 = domingo. */
+export function wallClockWeekday(wall: WallClock): number {
+  return new Date(Date.UTC(wall.year, wall.month - 1, wall.day)).getUTCDay()
+}
+
+const formatters = new Map<string, Intl.DateTimeFormat>()
+
+function formatter(timeZone: string): Intl.DateTimeFormat {
+  let f = formatters.get(timeZone)
+  if (!f) {
+    f = new Intl.DateTimeFormat("en-US", {
+      timeZone,
+      hourCycle: "h23",
+      year: "numeric",
+      month: "2-digit",
+      day: "2-digit",
+      hour: "2-digit",
+      minute: "2-digit",
+      second: "2-digit",
+    })
+    formatters.set(timeZone, f)
+  }
+  return f
+}
+
+/** Valida una zona IANA. Lanza con un mensaje que dice cuál falló. */
+export function assertTimeZone(timeZone: string): void {
+  try {
+    formatter(timeZone)
+  } catch {
+    throw new Error(`Zona horaria desconocida: "${timeZone}"`)
+  }
+}
+
+/** Qué marca el reloj de esa zona en ese instante. */
+export function toWallClock(instant: Date, timeZone: string): WallClock {
+  const parts = formatter(timeZone).formatToParts(instant)
+  const campo = (tipo: string) => {
+    const p = parts.find((x) => x.type === tipo)
+    return p ? Number(p.value) : 0
+  }
+  return {
+    year: campo("year"),
+    month: campo("month"),
+    day: campo("day"),
+    hour: campo("hour"),
+    minute: campo("minute"),
+    second: campo("second"),
+  }
+}
+
+function asUTCMillis(wall: WallClock): number {
+  return Date.UTC(wall.year, wall.month - 1, wall.day, wall.hour, wall.minute, wall.second)
+}
+
+function mismoReloj(a: WallClock, b: WallClock): boolean {
+  return (
+    a.year === b.year && a.month === b.month && a.day === b.day &&
+    a.hour === b.hour && a.minute === b.minute && a.second === b.second
+  )
+}
+
+/**
+ * El instante en que el reloj de esa zona marca `wall`.
+ *
+ * Devuelve `null` cuando ese momento **no existe**: al adelantar el horario de
+ * verano el reloj salta de 01:59 a 03:00, así que "las 2:30" no ocurre ese día.
+ * Un cron agendado ahí no debe correr a una hora inventada; el que llama decide
+ * si lo salta o lo corre al día siguiente.
+ *
+ * Cuando el reloj se atrasa, la misma hora ocurre dos veces y se devuelve la
+ * primera — correr una vez es lo que espera quien agendó, no dos.
+ */
+export function toInstant(wall: WallClock, timeZone: string): Date | null {
+  const objetivo = asUTCMillis(wall)
+
+  // Punto de partida: tratar el reloj de pared como si fuera UTC y corregir con
+  // la diferencia que reporte la zona. Dos pasadas alcanzan siempre — la primera
+  // acerca al offset correcto, la segunda absorbe el caso en que la corrección
+  // cruzó un cambio de horario y el offset de destino era otro.
+  let ts = objetivo
+  for (let i = 0; i < 3; i++) {
+    const diferencia = objetivo - asUTCMillis(toWallClock(new Date(ts), timeZone))
+    if (diferencia === 0) break
+    ts += diferencia
+  }
+
+  // La comprobación no es defensiva: es cómo se detecta el hueco del cambio de
+  // horario. Si la hora pedida no existe, ninguna corrección converge y el
+  // reloj de `ts` marca otra cosa.
+  if (!mismoReloj(toWallClock(new Date(ts), timeZone), wall)) return null
+
+  // Cuando el reloj se atrasa, ese mismo reloj de pared ocurre dos veces y la
+  // convergencia de arriba aterriza en la segunda. Se busca hacia atrás la
+  // primera: correr al instante más temprano es lo que espera quien agendó "a
+  // las 2:30", y así el job no se corre una hora ese día del año.
+  for (const atras of DESFASES_POSIBLES) {
+    const antes = ts - atras
+    if (mismoReloj(toWallClock(new Date(antes), timeZone), wall)) return new Date(antes)
+  }
+
+  return new Date(ts)
+}
+
+/**
+ * Cuánto puede saltar un reloj al cambiar de horario, de mayor a menor.
+ *
+ * Casi todas las zonas mueven una hora, pero no todas: Lord Howe mueve media, y
+ * hubo zonas con saltos de dos. Se prueban de mayor a menor para quedarse con
+ * la ocurrencia más temprana.
+ */
+const DESFASES_POSIBLES = [2 * 3_600_000, 3_600_000, 1_800_000]

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

@@ -1,11 +1,30 @@
 /**
- * Scheduler — cron con Croner sobre HiveDB.
+ * Scheduler — cron sobre HiveDB, con motor propio y sin dependencias.
  *
  * Soporta jobs recurrentes y de una sola vez. La persistencia pasó de SQLite a
- * las colecciones `cronJobs` / `taskRuns` de HiveDB en 0.1.5.
+ * las colecciones `cronJobs` / `taskRuns` de HiveDB en 0.1.5, y el motor pasó de
+ * `croner` a `./cron` —sólo `setTimeout` e `Intl` del runtime— en 0.3.0.
  */
 
 export { CronScheduler } from "./CronScheduler.ts";
+
+// El motor por separado, para quien quiera calcular o validar sin montar un
+// scheduler: una UI que muestra "próximas corridas" mientras se escribe la
+// expresión, por ejemplo.
+export {
+  Cron,
+  parseCronExpression,
+  isValidCronExpression,
+  nextOccurrence,
+  toWallClock,
+  toInstant,
+  assertTimeZone,
+  type CronOptions,
+  type CronFunction,
+  type CronFields,
+  type NextOccurrenceOptions,
+  type WallClock,
+} from "./cron/index.ts";
 // `executeScheduledTask` dejó de ser público: la ejecución entra por
 // `createTaskHandler()`, que es lo que el scheduler engancha.
 export { createTaskHandler, notifyTaskCompletion, setSchedulerForCleanup } from "./integration.ts";
@@ -20,5 +39,4 @@ export type {
   TaskType,
   TaskStatus,
   TaskRunStatus,
-  CronerOptions,
 } from "./types.ts";

package/packages/core/src/scheduler/integration.ts

@@ -12,6 +12,8 @@ import { resolveAgentId } from "../storage/onboarding.ts";
 import { sendToUserChannel } from "../gateway/channel-notify.ts";
 import { getNarration } from "../events/tool-narration.ts";
 import { addMessage } from "../agent/conversation-store.ts";
+import { makeThreadId, CRON_CHANNEL } from "../agent/thread-id.ts";
+import { threadForChannel } from "../agent/thread-store.ts";
 import { resolveBestChannel } from "../tools/cron/index.ts";
 import { col } from "../storage/hive.ts";
 import type { UserDoc, CronJobDoc } from "../storage/collections.ts";
@@ -123,7 +125,11 @@ ${prompt || `Execute tool: ${job.tool_name}`}`;
     try {
       const agentLoop = buildAgentLoop({ mcpManager: undefined });
       
-      const sessionId = `sched_${job.id}_${Date.now()}`;
+      // Un hilo estable por tarea programada. Antes era
+      // `sched_${job.id}_${Date.now()}`: cada disparo estrenaba un hilo, así que
+      // la tarea nunca recordaba sus ejecuciones anteriores y cada una dejaba
+      // mensajes huérfanos en `conversations` que ya nadie volvía a leer.
+      const sessionId = makeThreadId(user?.id || "default", CRON_CHANNEL, job.id);
 
       const agentChannel = (job.channel && job.channel !== "system")
         ? job.channel
@@ -136,10 +142,10 @@ ${prompt || `Execute tool: ${job.tool_name}`}`;
         if (!agentChannel) return;
         try {
           if (step.type === "tool_call" && step.toolName) {
-            await sendToUserChannel(agentChannel, user?.id || "", getNarration(step.toolName));
+            await sendToUserChannel(agentChannel, user?.id || "", getNarration(step.toolName), { threadId: sessionId });
           } else if (step.type === "text" && step.message) {
             const trimmed = step.message.trim();
-            if (trimmed) await sendToUserChannel(agentChannel, user?.id || "", trimmed);
+            if (trimmed) await sendToUserChannel(agentChannel, user?.id || "", trimmed, { threadId: sessionId });
           }
         } catch (err) {
           log.warn(`[execute] Narration send failed: ${(err as Error).message}`);
@@ -239,13 +245,18 @@ export async function notifyTaskCompletion(
 
   log.info(`[notify] Sending notification to ${notifyChannel}: "${message.slice(0, 50)}..."`);
 
+  // El aviso se guarda en el hilo donde el usuario lo va a leer —su conversación
+  // activa en la web, o el chat del canal— y no en el hilo del usuario, que desde
+  // la separación por canal ya no es donde mira nadie.
+  const notifyThreadId = (await threadForChannel(userId, notifyChannel)) ?? userId;
+
   try {
-    await addMessage(userId, "assistant", message, { channel: notifyChannel });
+    await addMessage(notifyThreadId, "assistant", message, { channel: notifyChannel });
   } catch (e) {
     log.warn(`[notify] Failed to persist notification to DB: ${(e as Error).message}`);
   }
 
-  await sendToUserChannel(notifyChannel, userId, message);
+  await sendToUserChannel(notifyChannel, userId, message, { threadId: notifyThreadId });
   log.info(`[notify] Notification sent to ${notifyChannel}`);
 }
 

package/packages/core/src/scheduler/types.ts

@@ -1,11 +1,11 @@
 /**
  * Hive Scheduler - Type Definitions
  * 
- * Type interfaces for the Croner-based scheduling system.
+ * Type interfaces for the scheduling system.
  * All names use "CronJob" terminology (formerly ScheduledTask).
  */
 
-import type { Cron } from "croner";
+import type { Cron } from "./cron/index.ts";
 
 /**
  * Task type: recurring uses cron expression, one_shot uses fire_at
@@ -146,24 +146,9 @@ export interface CronJobExecutionResult {
 }
 
 /**
- * Internal job wrapper holding Croner instance and metadata
+ * Internal job wrapper holding the scheduled job and its metadata
  */
 export interface CronJobEntry {
   job: CronJob;
   cron: Cron;
 }
-
-/**
- * Options for Croner job creation
- */
-export interface CronerOptions {
-  timezone: string;
-  protect: boolean;
-  catch: boolean | ((error: Error) => void);
-  name: string;
-  maxRuns?: number;
-  interval?: number;
-  startAt?: string;
-  stopAt?: string;
-  domAndDow?: boolean;
-}

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

@@ -0,0 +1,268 @@
+/**
+ * Agentes — la API, no la tool.
+ *
+ * Crear y editar agentes sólo se podía por dos caminos, y ninguno servía para
+ * una UI: `agentCreateTool` (argumentos con forma de LLM) o consultas crudas a
+ * la colección `agents`. En hive el CRUD vive inline en `gateway/routes/agents.ts`.
+ *
+ * Una diferencia deliberada con hive: **acá se valida que las referencias
+ * existan**. Su ruta guarda `tools_json`, `skills_json` y `mcp_server_ids_json`
+ * tal cual llegan, sin comprobar nada, así que un id mal escrito no falla al
+ * guardar sino más tarde, cuando el agente intenta usar una capacidad que no
+ * existe — lejos de donde está el error. Validar al escribir cuesta tres
+ * consultas y ahorra ese viaje.
+ *
+ * Lo que NO hace, a propósito: tocar las filas de `tools`/`skills` al crear o
+ * borrar un agente. Son colecciones globales compartidas entre todos los
+ * agentes; borrar las de uno rompería a otro que las usa.
+ */
+
+import { col, toIndexable, fromIndexable, NO_PARENT } from "../storage/hive.ts";
+import type { AgentDoc, ToolDoc, SkillDoc, McpServerDoc } from "../storage/collections.ts";
+import { deleteAgentSecrets } from "../storage/crypto.ts";
+import { expandToolAllowlist } from "../agent/delegation-runtime.ts";
+import { logger } from "../utils/logger.ts";
+
+const log = logger.child("services/agents");
+
+export interface AgentSummary {
+  id: string;
+  name: string;
+  description: string | null;
+  role: AgentDoc["role"];
+  status: string;
+  enabled: boolean;
+  providerId: string | null;
+  modelId: string | null;
+  /** Patrones declarados (`fs_*`), no la expansión. */
+  toolPatterns: string[];
+  skills: string[];
+  mcpServerIds: string[];
+  /** `"catalog"` = persona sembrada; `"user"` = creada por alguien. */
+  source: "user" | "catalog";
+  systemPrompt: string | null;
+  createdAt: number;
+  updatedAt: number;
+}
+
+export interface CreateAgentInput {
+  id?: string;
+  name: string;
+  description?: string | null;
+  systemPrompt?: string | null;
+  role?: AgentDoc["role"];
+  providerId?: string | null;
+  modelId?: string | null;
+  /** Acepta globs (`fs_*`); se validan tras expandir. */
+  toolPatterns?: string[];
+  skills?: string[];
+  mcpServerIds?: string[];
+  userId?: string;
+  maxIterations?: number;
+  enabled?: boolean;
+}
+
+export type UpdateAgentInput = Partial<Omit<CreateAgentInput, "id">>;
+
+/**
+ * Convierte un nombre en id.
+ *
+ * Normaliza los acentos antes de filtrar: sin eso "Efímero" queda como
+ * `ef_mero` y "Diseño" como `dise_o`, porque la í y la ñ no son `[a-z0-9]`.
+ * Para un producto en español eso no es un detalle cosmético.
+ */
+export function slugify(name: string): string {
+  return name
+    .normalize("NFD")
+    .replace(/[\u0300-\u036f]/g, "")
+    .toLowerCase()
+    .replace(/[^a-z0-9]+/g, "_")
+    .replace(/^_|_$/g, "");
+}
+
+function parseList(json: string | null | undefined): string[] {
+  try {
+    const v = json ? JSON.parse(json) : [];
+    return Array.isArray(v) ? v.filter((x): x is string => typeof x === "string") : [];
+  } catch {
+    return [];
+  }
+}
+
+function toSummary(doc: AgentDoc): AgentSummary {
+  return {
+    id: doc.id,
+    name: doc.name,
+    description: doc.description,
+    role: doc.role,
+    status: doc.status,
+    enabled: doc.enabled,
+    providerId: fromIndexable(doc.provider_id),
+    modelId: fromIndexable(doc.model_id),
+    toolPatterns: parseList(doc.tool_allowlist_json ?? doc.tools_json),
+    skills: parseList(doc.skills_json),
+    mcpServerIds: parseList(doc.mcp_server_ids_json),
+    source: doc.source ?? "user",
+    systemPrompt: doc.system_prompt,
+    createdAt: doc.created_at,
+    updatedAt: doc.updated_at,
+  };
+}
+
+async function agentsCol() {
+  return col<AgentDoc>("agents");
+}
+
+/**
+ * Comprueba que lo que se le asigna al agente exista de verdad.
+ *
+ * Los patrones de tools se expanden primero contra el registro vivo
+ * (`expandToolAllowlist`): un `fs_*` que no case con ninguna tool es un error
+ * de quien lo escribió, no una lista vacía silenciosa.
+ */
+async function validateReferences(input: {
+  toolPatterns?: string[];
+  skills?: string[];
+  mcpServerIds?: string[];
+}): Promise<void> {
+  const problemas: string[] = [];
+
+  if (input.toolPatterns?.length) {
+    const expandidas = expandToolAllowlist(input.toolPatterns);
+    if (expandidas.length === 0) {
+      problemas.push(`ninguna tool coincide con ${JSON.stringify(input.toolPatterns)}`);
+    } else {
+      const c = await col<ToolDoc>("tools");
+      const faltan: string[] = [];
+      for (const name of expandidas) if (!(await c.get(name))) faltan.push(name);
+      if (faltan.length) problemas.push(`tools inexistentes: ${faltan.join(", ")}`);
+    }
+  }
+
+  if (input.skills?.length) {
+    const c = await col<SkillDoc>("skills");
+    const faltan: string[] = [];
+    for (const id of input.skills) if (!(await c.get(id))) faltan.push(id);
+    if (faltan.length) problemas.push(`skills inexistentes: ${faltan.join(", ")}`);
+  }
+
+  if (input.mcpServerIds?.length) {
+    const c = await col<McpServerDoc>("mcpServers");
+    const faltan: string[] = [];
+    for (const id of input.mcpServerIds) if (!(await c.get(id))) faltan.push(id);
+    if (faltan.length) problemas.push(`servidores MCP inexistentes: ${faltan.join(", ")}`);
+  }
+
+  if (problemas.length) throw new Error(problemas.join("; "));
+}
+
+export async function createAgent(input: CreateAgentInput): Promise<AgentSummary> {
+  if (!input.name?.trim()) throw new Error("El agente necesita un nombre");
+  await validateReferences(input);
+
+  const c = await agentsCol();
+  const id = input.id ?? slugify(input.name);
+  if (await c.get(id)) throw new Error(`Ya existe un agente con id "${id}"`);
+
+  const now = Date.now();
+  const doc: AgentDoc = {
+    id,
+    user_id: input.userId ?? "",
+    name: input.name,
+    description: input.description ?? null,
+    system_prompt: input.systemPrompt ?? null,
+    tone: null,
+    role: input.role ?? "worker",
+    status: "idle",
+    enabled: input.enabled ?? true,
+    provider_id: toIndexable(input.providerId ?? null),
+    model_id: toIndexable(input.modelId ?? null),
+    tools_json: input.toolPatterns ? JSON.stringify(expandToolAllowlist(input.toolPatterns)) : null,
+    skills_json: input.skills ? JSON.stringify(input.skills) : null,
+    parent_id: NO_PARENT,
+    max_iterations: input.maxIterations ?? 10,
+    workspace: null,
+    lastTraceAt: null,
+    created_at: now,
+    updated_at: now,
+    source: "user",
+    // Los patrones se guardan sin expandir: `task_delegate` los vuelve a
+    // expandir en cada delegación, así una tool registrada después igual entra.
+    tool_allowlist_json: input.toolPatterns ? JSON.stringify(input.toolPatterns) : null,
+    mcp_server_ids_json: input.mcpServerIds ? JSON.stringify(input.mcpServerIds) : null,
+  };
+
+  await c.put(id, doc, { expectedVersion: 0 });
+  log.info(`agente "${input.name}" creado (${id})`);
+  return toSummary(doc);
+}
+
+export async function getAgent(id: string): Promise<AgentSummary | null> {
+  const entry = await (await agentsCol()).get(id);
+  return entry ? toSummary(entry.doc) : null;
+}
+
+export interface ListAgentsOptions {
+  role?: AgentDoc["role"];
+  source?: "user" | "catalog";
+  includeDisabled?: boolean;
+}
+
+export async function listAgents(opts?: ListAgentsOptions): Promise<AgentSummary[]> {
+  const rows = await (await agentsCol()).scan({});
+  return rows
+    .map((e) => e.doc)
+    .filter((d) => (opts?.role ? d.role === opts.role : true))
+    .filter((d) => (opts?.source ? (d.source ?? "user") === opts.source : true))
+    .filter((d) => (opts?.includeDisabled ? true : d.enabled))
+    .map(toSummary)
+    .sort((a, b) => a.name.localeCompare(b.name));
+}
+
+export async function updateAgent(id: string, changes: UpdateAgentInput): Promise<AgentSummary> {
+  await validateReferences(changes);
+
+  const c = await agentsCol();
+  const entry = await c.get(id);
+  if (!entry) throw new Error(`No existe el agente "${id}"`);
+
+  const doc: AgentDoc = { ...entry.doc, updated_at: Date.now() };
+  if (changes.name !== undefined) doc.name = changes.name;
+  if (changes.description !== undefined) doc.description = changes.description;
+  if (changes.systemPrompt !== undefined) doc.system_prompt = changes.systemPrompt;
+  if (changes.role !== undefined) doc.role = changes.role;
+  if (changes.enabled !== undefined) doc.enabled = changes.enabled;
+  if (changes.maxIterations !== undefined) doc.max_iterations = changes.maxIterations;
+  if (changes.providerId !== undefined) doc.provider_id = toIndexable(changes.providerId);
+  if (changes.modelId !== undefined) doc.model_id = toIndexable(changes.modelId);
+  if (changes.toolPatterns !== undefined) {
+    doc.tool_allowlist_json = JSON.stringify(changes.toolPatterns);
+    doc.tools_json = JSON.stringify(expandToolAllowlist(changes.toolPatterns));
+  }
+  if (changes.skills !== undefined) doc.skills_json = JSON.stringify(changes.skills);
+  if (changes.mcpServerIds !== undefined) doc.mcp_server_ids_json = JSON.stringify(changes.mcpServerIds);
+
+  await c.put(id, doc, { expectedVersion: entry.version });
+  return toSummary(doc);
+}
+
+/** Atajos legibles sobre `updateAgent`, que es lo que una UI llama al editar. */
+export const assignTools = (id: string, toolPatterns: string[]) => updateAgent(id, { toolPatterns });
+export const assignSkills = (id: string, skills: string[]) => updateAgent(id, { skills });
+export const assignMcpServers = (id: string, mcpServerIds: string[]) => updateAgent(id, { mcpServerIds });
+
+export const enableAgent = (id: string) => updateAgent(id, { enabled: true });
+export const disableAgent = (id: string) => updateAgent(id, { enabled: false });
+
+/**
+ * Borra el agente y sus secretos. **No toca sus tools ni sus skills**: son
+ * filas globales que otros agentes comparten.
+ */
+export async function deleteAgent(id: string): Promise<boolean> {
+  const c = await agentsCol();
+  if (!(await c.get(id))) return false;
+  await c.delete(id);
+  await deleteAgentSecrets(id).catch(() => {});
+  log.info(`agente ${id} borrado (sus tools y skills quedan: son compartidas)`);
+  return true;
+}