@johpaz/hive-sdk 0.1.4 → 0.1.5

package/packages/core/src/events/channel-narration.ts

@@ -0,0 +1,150 @@
+// ─── Narration delivery policy for messaging channels ─────────────────────────
+// WebChat renders narration as ephemeral, collapsible "process" widgets. A
+// messaging channel (WhatsApp, Telegram, Slack, Discord) has no such surface:
+// every narration event becomes a permanent chat message. Without a filter a
+// single turn with a few tools and two delegated workers produces dozens of
+// messages before the actual answer — noise for the user and a rate-limit /
+// ban risk on WhatsApp. This module decides what reaches those channels.
+
+import { col } from "../storage/hive";
+import type { ChannelDoc, NarrationEventDoc } from "../storage/collections";
+import { logger } from "../utils/logger";
+
+const log = logger.child("narration:channel");
+
+/** `off` = silent, `milestones` = delegation lifecycle only, `all` = + per-tool steps. */
+export type NarrationMode = "off" | "milestones" | "all";
+
+export const DEFAULT_NARRATION_MODE: NarrationMode = "milestones";
+
+/** Legacy `step_delivery_mode` values predate this feature — map them forward. */
+function coerceMode(raw: string | null | undefined): NarrationMode {
+  switch (raw) {
+    case "off":
+    case "milestones":
+    case "all":
+      return raw;
+    // "new_messages" was the original (never-read) default.
+    case "new_messages":
+      return DEFAULT_NARRATION_MODE;
+    default:
+      return DEFAULT_NARRATION_MODE;
+  }
+}
+
+/** High-level events: what the user actually cares about seeing in a chat. */
+const MILESTONE_KINDS = new Set<NarrationEventDoc["kind"]>([
+  "delegated",
+  "worker_started",
+  "verified",
+  "failed",
+  "group_ready",
+]);
+
+const KIND_PREFIX: Record<NarrationEventDoc["kind"], string> = {
+  delegated: "📋",
+  worker_started: "▶️",
+  tool_call: "⚙️",
+  tool_result: "⚠️",
+  verified: "✅",
+  failed: "❌",
+  group_ready: "📝",
+};
+
+const DETAIL_MAX_CHARS = 200;
+
+// ─── Mode lookup (cached) ─────────────────────────────────────────────────────
+// Resolved per channel *type* because narration events only carry the type, not
+// the account id. Short TTL so a settings change takes effect without a restart.
+
+const MODE_CACHE_TTL_MS = 30_000;
+const modeCache = new Map<string, { mode: NarrationMode; expiresAt: number }>();
+
+export function invalidateNarrationModeCache(channelType?: string): void {
+  if (channelType) modeCache.delete(channelType);
+  else modeCache.clear();
+}
+
+export async function resolveNarrationMode(channelType: string): Promise<NarrationMode> {
+  const cached = modeCache.get(channelType);
+  if (cached && cached.expiresAt > Date.now()) return cached.mode;
+
+  let mode = DEFAULT_NARRATION_MODE;
+  try {
+    const channels = await col<ChannelDoc>("channels");
+    const row = (await channels.scan({})).find((e) => e.doc.type === channelType);
+    mode = coerceMode(row?.doc.step_delivery_mode);
+  } catch (error) {
+    log.debug(`Could not resolve narration mode for ${channelType}: ${(error as Error).message}`);
+  }
+
+  modeCache.set(channelType, { mode, expiresAt: Date.now() + MODE_CACHE_TTL_MS });
+  return mode;
+}
+
+// ─── Filtering ────────────────────────────────────────────────────────────────
+
+export function shouldDeliverToChannel(event: NarrationEventDoc, mode: NarrationMode): boolean {
+  if (mode === "off") return false;
+  if (MILESTONE_KINDS.has(event.kind)) return true;
+  if (mode !== "all") return false;
+  // Even in `all`, a successful tool_result only restates the tool_call that
+  // preceded it. Errors are the part worth surfacing.
+  if (event.kind === "tool_result") return event.status === "error";
+  return true;
+}
+
+// ─── Formatting ───────────────────────────────────────────────────────────────
+
+/** Collapses whitespace and trims — raw error details carry stacks and paths. */
+function compactDetail(detail: string): string {
+  const flat = detail.replace(/\s+/g, " ").trim();
+  if (flat.length <= DETAIL_MAX_CHARS) return flat;
+  return `${flat.slice(0, DETAIL_MAX_CHARS - 1)}…`;
+}
+
+export function formatNarrationForChannel(event: NarrationEventDoc): string {
+  const prefix = KIND_PREFIX[event.kind] ?? "•";
+  const detail = event.detail ? compactDetail(event.detail) : "";
+  return detail ? `${prefix} ${event.label}\n${detail}` : `${prefix} ${event.label}`;
+}
+
+// ─── Ordered, off-critical-path delivery ──────────────────────────────────────
+// `publishNarration` awaits the delivery adapter, so sending inline would put a
+// round-trip to the channel's servers inside the agent loop for every event.
+// Each conversation gets its own promise chain: the agent loop is never blocked,
+// and messages still arrive in the order they were produced.
+
+const sendQueues = new Map<string, Promise<void>>();
+
+export function enqueueChannelNarration(
+  key: string,
+  send: () => Promise<void>,
+): void {
+  const previous = sendQueues.get(key) ?? Promise.resolve();
+  const next = previous
+    .then(send)
+    .catch((error: Error) => {
+      log.warn(`Narration delivery failed for ${key}: ${error.message}`);
+    })
+    .finally(() => {
+      // Drop the entry once this send is the last one queued, so the map does
+      // not grow with one retained promise per conversation seen.
+      if (sendQueues.get(key) === next) sendQueues.delete(key);
+    });
+  sendQueues.set(key, next);
+}
+
+/**
+ * Resolves once the narration queued for one conversation has been sent. Call
+ * before sending a turn's final answer so it cannot overtake pending progress
+ * messages, which would show the user the outcome before the steps.
+ */
+export async function awaitChannelNarration(key: string): Promise<void> {
+  await (sendQueues.get(key) ?? Promise.resolve());
+}
+
+/** Test/shutdown helper: resolves once every queued narration has been sent. */
+export async function flushChannelNarration(): Promise<void> {
+  await Promise.allSettled([...sendQueues.values()]);
+}

package/packages/core/src/events/narration.ts

@@ -0,0 +1,82 @@
+import { createHash } from "node:crypto";
+import { col } from "../storage/hive";
+import type { NarrationEventDoc } from "../storage/collections";
+import { logger } from "../utils/logger";
+
+const log = logger.child("narration");
+
+export type NarrationDelivery = (event: NarrationEventDoc) => Promise<void>;
+const STATE_KEY = Symbol.for("hive.narration.delivery");
+type NarrationState = { delivery: NarrationDelivery | null };
+
+function state(): NarrationState {
+  const root = globalThis as any;
+  root[STATE_KEY] ??= { delivery: null };
+  return root[STATE_KEY];
+}
+
+export function setNarrationDelivery(next: NarrationDelivery | null): void {
+  state().delivery = next;
+  log.info(`Delivery adapter ${next ? "registered" : "cleared"}`);
+}
+
+function eventId(turnId: string, dedupeKey: string): string {
+  return createHash("sha256").update(`${turnId}\0${dedupeKey}`).digest("hex");
+}
+
+export async function publishNarration(input: {
+  turnId: string;
+  threadId: string;
+  channel?: string | null;
+  userId?: string | null;
+  sessionId?: string | null;
+  agentId?: string | null;
+  agentName?: string | null;
+  kind: NarrationEventDoc["kind"];
+  status: NarrationEventDoc["status"];
+  label: string;
+  detail?: string | null;
+  dedupeKey: string;
+}): Promise<NarrationEventDoc> {
+  const id = eventId(input.turnId, input.dedupeKey);
+  const events = await col<NarrationEventDoc>("narrationEvents");
+  const existing = await events.get(id);
+  if (existing) return existing.doc;
+
+  const event: NarrationEventDoc = {
+    id,
+    turn_id: input.turnId,
+    thread_id: input.threadId,
+    channel: input.channel ?? "",
+    user_id: input.userId ?? "",
+    session_id: input.sessionId ?? "",
+    agent_id: input.agentId ?? "",
+    agent_name: input.agentName ?? "",
+    kind: input.kind,
+    status: input.status,
+    label: input.label,
+    detail: input.detail ?? null,
+    dedupe_key: input.dedupeKey,
+    created_at: Date.now(),
+  };
+
+  try {
+    await events.put(id, event, { expectedVersion: 0 });
+  } catch {
+    const raced = await events.get(id);
+    if (raced) return raced.doc;
+    throw new Error(`Could not persist narration event ${id}`);
+  }
+  log.info(`Persisted ${event.kind} for turn=${event.turn_id} agent=${event.agent_id || "coordinator"}`);
+
+  const delivery = state().delivery;
+  if (delivery) {
+    try {
+      await delivery(event);
+      log.info(`Delivered ${event.kind} for turn=${event.turn_id} channel=${event.channel || "none"}`);
+    } catch (error) {
+      log.warn(`Delivery failed for narration ${id}: ${(error as Error).message}`);
+    }
+  }
+  return event;
+}

package/packages/core/src/events/tool-narration.ts

@@ -0,0 +1,62 @@
+// ─── Tool narration map ───────────────────────────────────────────────────────
+// Maps tool name prefixes/exact names to human-readable Spanish narrations.
+// Shown to the user while the agent executes a tool.
+const TOOL_NARRATIONS: Record<string, string> = {
+  // Web
+  web_search: "Buscando en la web...",
+  web_fetch: "Leyendo página web...",
+  // Files
+  read: "Leyendo archivo...",
+  write: "Escribiendo archivo...",
+  edit: "Editando archivo...",
+  exec: "Ejecutando comando...",
+  // Cron
+  "cron.create": "Programando tarea...",
+  "cron.list": "Consultando tareas programadas...",
+  "cron.update": "Actualizando tarea programada...",
+  "cron.delete": "Eliminando tarea programada...",
+  "cron.pause": "Pausando tarea programada...",
+  "cron.resume": "Reanudando tarea programada...",
+  "cron.trigger": "Ejecutando tarea ahora...",
+  "cron.history": "Consultando historial...",
+  // Agents
+  agent_create: "Creando agente worker...",
+  agent_find: "Buscando agente disponible...",
+  agent_archive: "Archivando agente...",
+  get_available_models: "Consultando modelos disponibles...",
+  task_delegate: "Delegando tarea a un agente...",
+  task_list: "Listando tareas en ejecución...",
+  task_status: "Consultando estado de la tarea...",
+  bus_publish: "Coordinando con otro agente...",
+  bus_read: "Leyendo mensajes de los agentes...",
+  // Discovery
+  search_knowledge: "Buscando capacidades disponibles...",
+  // Memory
+  save_note: "Guardando nota...",
+  memory_write: "Guardando en memoria...",
+  memory_read: "Leyendo memoria...",
+  memory_search: "Buscando en memoria...",
+  memory_delete: "Eliminando de memoria...",
+  memory_list: "Listando notas...",
+  // Browser
+  browser_navigate: "Navegando a la página...",
+  browser_click: "Haciendo clic...",
+  browser_type: "Escribiendo en la página...",
+  browser_screenshot: "Tomando captura de pantalla...",
+  browser_extract: "Extrayendo información de la página...",
+  // Canvas
+  canvas_add_node: "Actualizando canvas...",
+  canvas_update: "Actualizando canvas...",
+  // Notify
+  notify: "Enviando notificación...",
+  report_progress: "Reportando progreso...",
+}
+
+export function getNarration(toolName: string): string {
+  if (TOOL_NARRATIONS[toolName]) return TOOL_NARRATIONS[toolName]
+  // Prefix matching for MCP tools like "github__create_pr" → "Ejecutando github..."
+  const prefix = toolName.split("__")[0]
+  if (prefix && prefix !== toolName) return `Ejecutando ${prefix}...`
+  // Fallback
+  return `Ejecutando ${toolName.replace(/_/g, " ")}...`
+}

package/packages/core/src/gateway/delegation-groups.ts

@@ -0,0 +1,258 @@
+import { col } from "../storage/hive";
+import type {
+  DelegationGroupDoc,
+  DelegationGroupOutcome,
+} from "../storage/collections";
+import { logger } from "../utils/logger";
+import { publishNarration } from "../events/narration";
+
+const log = logger.child("delegation-groups");
+const MAX_RETRIES = 8;
+
+export type DelegationSummaryEnqueuer = (
+  group: DelegationGroupDoc,
+  content: string,
+  idempotencyKey: string,
+) => Promise<{ id: string }>;
+
+let summaryEnqueuer: DelegationSummaryEnqueuer | null = null;
+
+export function setDelegationSummaryEnqueuer(enqueuer: DelegationSummaryEnqueuer | null): void {
+  summaryEnqueuer = enqueuer;
+}
+
+function taskIds(group: DelegationGroupDoc): string[] {
+  return JSON.parse(group.task_ids_json || "[]");
+}
+
+function outcomes(group: DelegationGroupDoc): DelegationGroupOutcome[] {
+  return JSON.parse(group.outcomes_json || "[]");
+}
+
+async function mutate(
+  groupId: string,
+  fn: (doc: DelegationGroupDoc) => DelegationGroupDoc,
+): Promise<DelegationGroupDoc> {
+  const groups = await col<DelegationGroupDoc>("delegationGroups");
+  for (let attempt = 0; attempt < MAX_RETRIES; attempt++) {
+    const current = await groups.get(groupId);
+    if (!current) throw new Error(`Delegation group not found: ${groupId}`);
+    const next = fn(current.doc);
+    try {
+      await groups.put(groupId, next, { expectedVersion: current.version });
+      return next;
+    } catch {
+      // optimistic concurrency conflict
+    }
+  }
+  throw new Error(`Delegation group contention: ${groupId}`);
+}
+
+export async function registerDelegatedTask(input: {
+  turnId: string;
+  taskId: string;
+  threadId: string;
+  channel?: string | null;
+  userId?: string | null;
+  sessionId?: string | null;
+  coordinatorAgentId?: string | null;
+}): Promise<DelegationGroupDoc> {
+  const groups = await col<DelegationGroupDoc>("delegationGroups");
+  const existing = await groups.get(input.turnId);
+  if (!existing) {
+    const now = Date.now();
+    const created: DelegationGroupDoc = {
+      id: input.turnId,
+      turn_id: input.turnId,
+      thread_id: input.threadId,
+      channel: input.channel ?? "",
+      user_id: input.userId ?? "",
+      session_id: input.sessionId ?? "",
+      coordinator_agent_id: input.coordinatorAgentId ?? "",
+      status: "open",
+      task_ids_json: JSON.stringify([input.taskId]),
+      outcomes_json: "[]",
+      summary_job_id: null,
+      created_at: now,
+      sealed_at: null,
+      ready_at: null,
+      notified_at: null,
+    };
+    try {
+      await groups.put(input.turnId, created, { expectedVersion: 0 });
+      return created;
+    } catch {
+      // Another parallel task created the group; append below.
+    }
+  }
+
+  return mutate(input.turnId, (group) => {
+    if (group.status !== "open") {
+      throw new Error(`Delegation group ${input.turnId} is already sealed`);
+    }
+    const ids = taskIds(group);
+    if (!ids.includes(input.taskId)) ids.push(input.taskId);
+    return { ...group, task_ids_json: JSON.stringify(ids) };
+  });
+}
+
+export async function getDelegationGroup(turnId: string): Promise<DelegationGroupDoc | null> {
+  return (await (await col<DelegationGroupDoc>("delegationGroups")).get(turnId))?.doc ?? null;
+}
+
+function isComplete(group: DelegationGroupDoc): boolean {
+  const expected = new Set(taskIds(group));
+  const completed = new Set(outcomes(group).map((outcome) => outcome.task_id));
+  return expected.size > 0 && [...expected].every((id) => completed.has(id));
+}
+
+function summarize(value: unknown, maxLen = 800): unknown {
+  if (typeof value !== "string") return value;
+  return value.length > maxLen ? `${value.slice(0, maxLen)}…` : value;
+}
+
+function summaryPrompt(group: DelegationGroupDoc): string {
+  const factual = outcomes(group).map((outcome) => {
+    const result = outcome.result as { content?: unknown; acceptance?: unknown; checks?: { status?: string; summary?: string } } | null;
+    return {
+      task_id: outcome.task_id,
+      worker_id: outcome.worker_id,
+      task: outcome.task_name,
+      ok: outcome.ok,
+      content: summarize(result?.content ?? outcome.result),
+      acceptance: result?.acceptance ?? null,
+      checks: result?.checks ? { status: result.checks.status, summary: summarize(result.checks.summary) } : null,
+      error: outcome.error,
+    };
+  });
+  // No manual framing here — persisted with source:"delegation_summary" and
+  // framed at serialization time by formatInternalEvent (conversation-store.ts).
+  return [
+    "Todas las tareas delegadas de este turno alcanzaron estado terminal.",
+    "Para cada una, comprobá la entrega contra sus criterios de aceptación (`acceptance`):",
+    '- checks.status="passed" → verificado determinísticamente, aceptá.',
+    '- checks.status="failed" → NO cumplió (ok=false). No lo reportes como éxito.',
+    '- checks.status="unchecked" o ausente → juzgalo vos con el contenido y la evidencia adjunta.',
+    "Si una entrega no cumple sus criterios: usá `task_revise` con el task_id y un feedback concreto, o arreglala vos si es trivial y tenés las tools. No inventes trabajo ni evidencia, y no declares éxito para ok=false.",
+    "Si todas cumplen, escribí UNA sola respuesta final para el usuario, en lenguaje natural: nunca expongas task_id, worker_id, nombres de tools ni JSON crudo.",
+    JSON.stringify(factual),
+  ].join("\n\n");
+}
+
+async function finalizeIfReady(groupId: string): Promise<DelegationGroupDoc> {
+  let group = await getDelegationGroup(groupId);
+  if (!group || group.status === "open" || group.status === "notified" || !isComplete(group)) {
+    return group!;
+  }
+  if (group.status === "sealed") {
+    group = await mutate(groupId, (current) => {
+      if (current.status !== "sealed" || !isComplete(current)) return current;
+      return { ...current, status: "ready", ready_at: Date.now() };
+    });
+  }
+  if (group.status !== "ready") return group;
+  if (!summaryEnqueuer) {
+    log.warn(`Group ${groupId} is ready but no summary enqueuer is registered`);
+    return group;
+  }
+
+  const groups = await col<DelegationGroupDoc>("delegationGroups");
+  let claimed = false;
+  for (let attempt = 0; attempt < MAX_RETRIES; attempt++) {
+    const current = await groups.get(groupId);
+    if (!current) return group;
+    if (current.doc.status !== "ready" || current.doc.summary_job_id !== null) {
+      return current.doc;
+    }
+    try {
+      await groups.put(groupId, {
+        ...current.doc,
+        summary_job_id: "__claim__",
+      }, { expectedVersion: current.version });
+      group = { ...current.doc, summary_job_id: "__claim__" };
+      claimed = true;
+      break;
+    } catch {
+      // another terminal hook is racing us
+    }
+  }
+  if (!claimed) return (await getDelegationGroup(groupId))!;
+
+  let job: { id: string };
+  try {
+    job = await summaryEnqueuer(
+      group,
+      summaryPrompt(group),
+      `delegation-summary:${group.id}`,
+    );
+  } catch (error) {
+    await mutate(groupId, (current) => current.summary_job_id === "__claim__"
+      ? { ...current, summary_job_id: null }
+      : current);
+    throw error;
+  }
+  group = await mutate(groupId, (current) => {
+    if (current.status === "notified") return current;
+    return {
+      ...current,
+      status: "notified",
+      summary_job_id: job.id,
+      notified_at: Date.now(),
+    };
+  });
+  await publishNarration({
+    turnId: group.turn_id,
+    threadId: group.thread_id,
+    channel: group.channel,
+    userId: group.user_id,
+    sessionId: group.session_id,
+    agentId: group.coordinator_agent_id,
+    agentName: "Coordinador",
+    kind: "group_ready",
+    status: "done",
+    label: "Todas las entregas fueron revisadas; el coordinador prepara una única respuesta final",
+    dedupeKey: "delegation_group_ready",
+  });
+  return group;
+}
+
+export async function sealDelegationGroup(turnId: string): Promise<DelegationGroupDoc | null> {
+  const existing = await getDelegationGroup(turnId);
+  if (!existing) return null;
+  if (existing.status === "open") {
+    await mutate(turnId, (group) => group.status === "open"
+      ? { ...group, status: "sealed", sealed_at: Date.now() }
+      : group);
+  }
+  return finalizeIfReady(turnId);
+}
+
+export async function recordDelegationOutcome(input: {
+  turnId: string;
+  taskId: string;
+  jobId: string;
+  workerId: string;
+  taskName: string;
+  ok: boolean;
+  result?: unknown;
+  error?: string | null;
+}): Promise<DelegationGroupDoc | null> {
+  const existing = await getDelegationGroup(input.turnId);
+  if (!existing) return null;
+  await mutate(input.turnId, (group) => {
+    const current = outcomes(group);
+    if (current.some((outcome) => outcome.task_id === input.taskId)) return group;
+    current.push({
+      task_id: input.taskId,
+      job_id: input.jobId,
+      worker_id: input.workerId,
+      task_name: input.taskName,
+      ok: input.ok,
+      result: input.result ?? null,
+      error: input.error ?? null,
+      finished_at: Date.now(),
+    });
+    return { ...group, outcomes_json: JSON.stringify(current) };
+  });
+  return finalizeIfReady(input.turnId);
+}