@johpaz/hive-sdk 0.1.5 → 0.2.0

package/packages/core/src/agent/llm-providers/opencode-go.ts

@@ -1,4 +1,4 @@
-import { OpenAICompatBase } from "./openai-compat-base"
+import { OpenAICompatBase } from "./openai-compat-base.ts"
 
 export class OpenCodeGoProvider extends OpenAICompatBase {
   static readonly secretKey = "OPENCODE_GO_API_KEY"

package/packages/core/src/agent/llm-providers/openrouter.ts

@@ -1,4 +1,4 @@
-import { OpenAICompatBase } from "./openai-compat-base"
+import { OpenAICompatBase } from "./openai-compat-base.ts"
 
 export class OpenRouterProvider extends OpenAICompatBase {
   constructor() { super("openrouter") }

package/packages/core/src/agent/llm-providers/qwen.ts

@@ -1,4 +1,4 @@
-import { OpenAICompatBase } from "./openai-compat-base"
+import { OpenAICompatBase } from "./openai-compat-base.ts"
 
 export class QwenProvider extends OpenAICompatBase {
   constructor() { super("qwen") }

package/packages/core/src/agent/llm-providers/z-ai.ts

@@ -1,4 +1,4 @@
-import { OpenAICompatBase } from "./openai-compat-base"
+import { OpenAICompatBase } from "./openai-compat-base.ts"
 
 export class ZaiProvider extends OpenAICompatBase {
   constructor() { super("z-ai") }

package/packages/core/src/agent/mcp-result-normalizer.ts

@@ -0,0 +1,192 @@
+/**
+ * mcp-result-normalizer — keeps large/binary MCP tool results out of the LLM
+ * context window.
+ *
+ * `MCPClientManager.callTool()` (packages/mcp/src/manager.ts) returns the raw
+ * `content` array from the MCP SDK's CallToolResult. Per the MCP spec that
+ * array can contain `image`/`audio` blocks (base64 `data`) or `resource`
+ * blocks (base64 `blob`) alongside plain `text` blocks. Nothing downstream
+ * (agent-loop.ts's formatToolResult) inspects those blocks — a base64 image
+ * would be serialized whole into a `role:"tool"` message and sent to the
+ * model, which is exactly what filled the context window and hung the agent
+ * in the incident this module fixes.
+ *
+ * This mirrors the pattern already used by browser-screenshot.ts: binary
+ * content gets persisted via createArtifact() (artifacts/store.ts) and the
+ * model only ever sees a lightweight { type: "artifact_ref", ... } reference.
+ */
+
+import { createArtifact } from "../artifacts/store.ts";
+import { logger } from "../utils/logger.ts";
+
+const log = logger.child("mcp-result-normalizer");
+
+/** Blocks longer than this (in chars) get materialized as a text artifact instead of inlined. Override via HIVE_MCP_INLINE_MAX_CHARS. */
+const MCP_INLINE_MAX_CHARS = Number(process.env.HIVE_MCP_INLINE_MAX_CHARS) || 20_000;
+
+export interface McpNormalizeContext {
+  userId?: string;
+  runId?: string | null;
+  taskId?: string | null;
+}
+
+type McpContentBlock = Record<string, unknown> & { type?: unknown };
+
+function isBinaryBlock(block: McpContentBlock): block is McpContentBlock & { type: "image" | "audio"; data: string; mimeType: string } {
+  return (block.type === "image" || block.type === "audio") && typeof block.data === "string";
+}
+
+function isBlobResourceBlock(block: McpContentBlock): block is McpContentBlock & { type: "resource"; resource: { blob: string; mimeType?: string; uri?: string } } {
+  if (block.type !== "resource") return false;
+  const resource = block.resource as Record<string, unknown> | undefined;
+  return !!resource && typeof resource.blob === "string";
+}
+
+function isOversizedTextBlock(block: McpContentBlock): block is McpContentBlock & { type: "text"; text: string } {
+  return block.type === "text" && typeof block.text === "string" && block.text.length > MCP_INLINE_MAX_CHARS;
+}
+
+async function materializeBinary(
+  bytesBase64: string,
+  mimeType: string,
+  kind: string,
+  ctx: McpNormalizeContext,
+): Promise<Record<string, unknown>> {
+  if (!ctx.userId) {
+    // Without a user_id we can't set ownership on the artifact (inspectArtifact
+    // would reject any read against it later) — never let raw base64 through,
+    // just describe what was omitted.
+    const approxBytes = Math.floor((bytesBase64.length * 3) / 4);
+    log.warn(`[materializeBinary] No user_id in tool context — omitting ${mimeType} block (${approxBytes} bytes) instead of creating an artifact`);
+    return { type: "artifact_omitted", mime_type: mimeType, approx_size: approxBytes, reason: "no user_id in tool context" };
+  }
+
+  const bytes = Buffer.from(bytesBase64, "base64");
+  const artifact = await createArtifact({
+    bytes,
+    mimeType,
+    kind,
+    userId: ctx.userId,
+    runId: ctx.runId ?? null,
+    taskId: ctx.taskId ?? null,
+  });
+  log.info(`[materializeBinary] Stored ${kind} as artifact ${artifact.id} (${artifact.size} bytes, ${artifact.mime_type})`);
+  return {
+    type: "artifact_ref",
+    artifact_id: artifact.id,
+    mime_type: artifact.mime_type,
+    size: artifact.size,
+    sha256: artifact.sha256,
+    expires_at: artifact.expires_at,
+  };
+}
+
+/** Above this, parsing the text just to describe it costs more than it explains. */
+const MAX_SHAPE_PROBE_CHARS = 5_000_000;
+
+/**
+ * Describes the shape of a JSON payload so the model can aim `artifact_read`
+ * instead of paging blind.
+ *
+ * The 500-char preview alone is close to useless on the payload this was
+ * written for — a Gmail MCP result where the first message's `received`
+ * headers eat the whole window before a single subject line appears. Knowing
+ * "12 items, keyed id/threadId/labelIds/headers" is what turns a search into
+ * one call.
+ */
+function describeJsonShape(text: string): Record<string, unknown> {
+  if (text.length > MAX_SHAPE_PROBE_CHARS) return {};
+  const trimmed = text.trimStart();
+  if (!trimmed.startsWith("[") && !trimmed.startsWith("{")) return {};
+
+  try {
+    const parsed = JSON.parse(text);
+    if (Array.isArray(parsed)) {
+      const first = parsed.find((item) => item && typeof item === "object" && !Array.isArray(item));
+      return {
+        json_items: parsed.length,
+        ...(first ? { json_item_keys: Object.keys(first as Record<string, unknown>).slice(0, 25) } : {}),
+      };
+    }
+    if (parsed && typeof parsed === "object") {
+      return { json_keys: Object.keys(parsed as Record<string, unknown>).slice(0, 25) };
+    }
+  } catch {
+    // Not JSON, or truncated JSON — the plain preview still stands.
+  }
+  return {};
+}
+
+async function materializeText(text: string, ctx: McpNormalizeContext): Promise<Record<string, unknown>> {
+  if (!ctx.userId) {
+    log.warn(`[materializeText] No user_id in tool context — truncating oversized text block (${text.length} chars) instead of creating an artifact`);
+    return { type: "text", text: `${text.slice(0, 500)}… [truncated: ${text.length} chars total, no user_id to persist full text as artifact]` };
+  }
+
+  const artifact = await createArtifact({
+    bytes: Buffer.from(text, "utf-8"),
+    mimeType: "text/plain",
+    kind: "mcp_text_result",
+    userId: ctx.userId,
+    runId: ctx.runId ?? null,
+    taskId: ctx.taskId ?? null,
+  });
+  log.info(`[materializeText] Stored oversized text result as artifact ${artifact.id} (${artifact.size} bytes)`);
+  return {
+    type: "artifact_ref",
+    artifact_id: artifact.id,
+    mime_type: "text/plain",
+    size: artifact.size,
+    chars: text.length,
+    preview: text.length > 500 ? `${text.slice(0, 500)}…` : text,
+    ...describeJsonShape(text),
+    // Without this the model only knows the data exists somewhere. It used to
+    // reach for artifact_inspect (metadata only), find nothing usable, and
+    // spend its remaining iterations guessing.
+    hint: "Full content is available via artifact_read (artifactId + offset/limit, or search).",
+  };
+}
+
+/**
+ * Normalizes a raw MCP CallToolResult.content array: binary blocks (image,
+ * audio, resource-with-blob) become { type: "artifact_ref", ... }, oversized
+ * text blocks are persisted the same way with a short preview kept inline,
+ * everything else (text, resource_link) passes through unchanged.
+ *
+ * Never pre-stringifies — returns JS values so formatToolResult (toon.ts)
+ * keeps doing the actual TOON/JSON encoding, same contract context-compiler.ts
+ * already documents for MCP tool executors.
+ */
+export async function normalizeMcpResult(content: unknown, ctx: McpNormalizeContext): Promise<unknown> {
+  if (!Array.isArray(content)) return content;
+
+  const out: unknown[] = [];
+  for (const raw of content) {
+    if (!raw || typeof raw !== "object") {
+      out.push(raw);
+      continue;
+    }
+    const block = raw as McpContentBlock;
+    try {
+      if (isBinaryBlock(block)) {
+        out.push(await materializeBinary(block.data, block.mimeType, "mcp_result", ctx));
+        continue;
+      }
+      if (isBlobResourceBlock(block)) {
+        const mimeType = block.resource.mimeType || "application/octet-stream";
+        out.push(await materializeBinary(block.resource.blob, mimeType, "mcp_result", ctx));
+        continue;
+      }
+      if (isOversizedTextBlock(block)) {
+        out.push(await materializeText(block.text, ctx));
+        continue;
+      }
+    } catch (err) {
+      log.error(`[normalizeMcpResult] Failed to materialize block (type=${String(block.type)}): ${(err as Error).message}`);
+      out.push({ type: "artifact_error", mime_type: (block as { mimeType?: string }).mimeType, error: (err as Error).message });
+      continue;
+    }
+    out.push(block);
+  }
+  return out;
+}

package/packages/core/src/agent/playbook-selector.ts

@@ -7,15 +7,15 @@
  * folding, lenient parsing — raw user text never throws).
  */
 
-import { col } from "../storage/hive"
-import type { PlaybookDoc } from "../storage/collections"
-import { logger } from "../utils/logger"
+import { col } from "../storage/hive.ts"
+import type { PlaybookDoc } from "../storage/collections.ts"
+import { logger } from "../utils/logger.ts"
 import {
     searchCapabilities,
     applyRelativeCutoff,
     replaceCapabilityDocs,
     type CapabilityDoc,
-} from "./capability-search"
+} from "./capability-search.ts"
 
 const log = logger.child("playbook-selector")
 

package/packages/core/src/agent/prompt-builder.ts

@@ -13,11 +13,11 @@
  * - Skills activos
  */
 
-import { col } from "../storage/hive"
-import type { EthicsDoc, AgentDoc, UserDoc } from "../storage/collections"
-import { logger } from "../utils/logger"
-import { formatContext } from "../utils/toon"
-import { resolveUserId } from "../storage/onboarding"
+import { col } from "../storage/hive.ts"
+import type { EthicsDoc, AgentDoc, UserDoc } from "../storage/collections.ts"
+import { logger } from "../utils/logger.ts"
+import { formatContext } from "../utils/toon.ts"
+import { resolveUserId } from "../storage/onboarding.ts"
 
 const log = logger.child("prompt-builder")
 

package/packages/core/src/agent/proof-packet.ts

@@ -6,11 +6,11 @@
  * reviewer doesn't have to replay the whole run to trust its outcome.
  */
 
-import { col, nextId, toIndexable } from "../storage/hive";
-import type { ProofPacketDoc } from "../storage/collections";
-import type { AcceptanceResult } from "./goal-runner";
-import type { RunEpoch } from "./run-epoch";
-import { logger } from "../utils/logger";
+import { col, nextId, toIndexable } from "../storage/hive.ts";
+import type { ProofPacketDoc } from "../storage/collections.ts";
+import type { AcceptanceResult } from "./goal-runner.ts";
+import type { RunEpoch } from "./run-epoch.ts";
+import { logger } from "../utils/logger.ts";
 
 const log = logger.child("proof-packet");
 

package/packages/core/src/agent/providers/index.ts

@@ -7,10 +7,10 @@
 
 import type { Config } from "../../config/loader.ts"
 import { logger } from "../../utils/logger.ts"
-import { getAgentLoop } from "../agent-loop"
-import { resolveUserId, resolveAgentId } from "../../storage/onboarding"
-import type { ContentPart } from "../../multimodal/types"
-import type { TurnSource } from "../../storage/collections"
+import { getAgentLoop } from "../agent-loop.ts"
+import { resolveUserId, resolveAgentId } from "../../storage/onboarding.ts"
+import type { ContentPart } from "../../multimodal/types.ts"
+import type { TurnSource } from "../../storage/collections.ts"
 
 export type Provider = "openai" | "anthropic" | "gemini" | "mistral" | "kimi" | "ollama" | "openrouter" | "deepseek" | "nvidia" | "hiveagents" | "z-ai" | "modelscope" | "minimax" | "qwen" | "groq" | "opencode-go"
 

package/packages/core/src/agent/realtime-providers/gemini-live.ts

@@ -0,0 +1,238 @@
+/**
+ * Adaptador de la Live API de Gemini (`bidiGenerateContent`).
+ *
+ * Sobre `ai.live.connect()` de @google/genai. El import es dinámico igual que en
+ * ../llm-providers/gemini.ts: el SDK arrastra dependencias de Vertex que no hacen
+ * falta con API key, y cargarlo perezosamente evita pagarlas en el arranque.
+ *
+ * Verificado contra gemini-3.1-flash-live-preview (2026-08): la inyección de
+ * texto va por `sendRealtimeInput({text})`; `sendClientContent` quedó restringido
+ * al contexto inicial en 3.x, así que no se usa acá.
+ */
+
+import { logger } from "../../utils/logger.ts";
+import { ensureArrayItems } from "../llm-providers/interface.ts";
+import type {
+  RealtimeProvider,
+  RealtimeSession,
+  RealtimeSessionOptions,
+  RealtimeToolCall,
+} from "./interface.ts";
+
+const log = logger.child("realtime:gemini");
+
+/** Modelos con `bidiGenerateContent`. El id vive en la BD; esto es sólo el fallback. */
+export const DEFAULT_GEMINI_LIVE_MODEL = "gemini-3.1-flash-live-preview";
+
+class GeminiLiveSession implements RealtimeSession {
+  closed = false;
+
+  readonly model: string;
+  private readonly session: any;
+  private readonly callbacks: RealtimeSessionOptions["callbacks"];
+
+  constructor(
+    model: string,
+    session: any,
+    callbacks: RealtimeSessionOptions["callbacks"],
+  ) {
+    this.model = model;
+    this.session = session;
+    this.callbacks = callbacks;
+  }
+
+  sendAudio(pcm: ArrayBufferLike): void {
+    if (this.closed) return;
+    try {
+      this.session.sendRealtimeInput({
+        audio: {
+          data: Buffer.from(pcm as ArrayBuffer).toString("base64"),
+          mimeType: "audio/pcm;rate=16000",
+        },
+      });
+    } catch (error) {
+      this.fail(error, "sendAudio");
+    }
+  }
+
+  sendVideoFrame(base64: string, mimeType: string): void {
+    if (this.closed) return;
+    try {
+      this.session.sendRealtimeInput({ video: { data: base64, mimeType } });
+    } catch (error) {
+      this.fail(error, "sendVideoFrame");
+    }
+  }
+
+  sendText(text: string): void {
+    if (this.closed || !text.trim()) return;
+    try {
+      this.session.sendRealtimeInput({ text });
+    } catch (error) {
+      this.fail(error, "sendText");
+    }
+  }
+
+  sendToolResult(id: string, name: string, result: Record<string, unknown>): void {
+    if (this.closed) return;
+    try {
+      this.session.sendToolResponse({ functionResponses: [{ id, name, response: result }] });
+    } catch (error) {
+      this.fail(error, "sendToolResult");
+    }
+  }
+
+  close(): void {
+    if (this.closed) return;
+    this.closed = true;
+    try {
+      this.session.close();
+    } catch {
+      /* el socket ya estaba cerrado */
+    }
+  }
+
+  /** Marca la sesión como muerta: seguir escribiendo en un socket roto sólo genera ruido. */
+  private fail(error: unknown, op: string): void {
+    this.closed = true;
+    const err = error instanceof Error ? error : new Error(String(error));
+    log.warn(`${op} falló: ${err.message}`);
+    this.callbacks.onError?.(err);
+  }
+}
+
+export class GeminiLiveProvider implements RealtimeProvider {
+  readonly id = "gemini";
+
+  async connect(options: RealtimeSessionOptions): Promise<RealtimeSession> {
+    const { GoogleGenAI } = await import("@google/genai");
+    const ai = new GoogleGenAI({ apiKey: options.apiKey });
+    const cb = options.callbacks;
+
+    const config: Record<string, unknown> = {
+      responseModalities: ["AUDIO"],
+      systemInstruction: options.systemInstruction,
+      // Necesarias para persistir el hilo y pintarlo en el chat: sin esto sólo
+      // llegan bytes de audio y la conversación hablada no deja rastro escrito.
+      inputAudioTranscription: {},
+      outputAudioTranscription: {},
+      // Sin compresión la sesión muere a los 15 min de audio.
+      contextWindowCompression: { slidingWindow: {} },
+      // Handle para reanudar tras un goAway sin perder el hilo.
+      sessionResumption: options.resumptionHandle ? { handle: options.resumptionHandle } : {},
+    };
+
+    if (options.voice || options.language) {
+      const speechConfig: Record<string, unknown> = {};
+      if (options.voice) {
+        speechConfig.voiceConfig = { prebuiltVoiceConfig: { voiceName: options.voice } };
+      }
+      if (options.language) speechConfig.languageCode = options.language;
+      config.speechConfig = speechConfig;
+    }
+    if (options.silenceDurationMs || options.startOfSpeechSensitivity) {
+      const deteccion: Record<string, unknown> = {};
+      if (options.silenceDurationMs) deteccion.silenceDurationMs = options.silenceDurationMs;
+      if (options.startOfSpeechSensitivity) {
+        deteccion.startOfSpeechSensitivity = options.startOfSpeechSensitivity;
+      }
+      config.realtimeInputConfig = { automaticActivityDetection: deteccion };
+    }
+    if (options.tools?.length) {
+      config.tools = [
+        {
+          functionDeclarations: options.tools.map((t) => ({
+            name: t.function.name,
+            description: t.function.description,
+            parameters: ensureArrayItems(t.function.parameters),
+          })),
+        },
+      ];
+    }
+
+    let wrapper: GeminiLiveSession | null = null;
+
+    const session = await ai.live.connect({
+      model: options.model,
+      config: config as any,
+      callbacks: {
+        onopen: () => log.info(`sesión abierta (${options.model})`),
+        onmessage: (msg: any) => {
+          try {
+            handleMessage(msg, cb);
+          } catch (error) {
+            cb.onError?.(error instanceof Error ? error : new Error(String(error)));
+          }
+        },
+        onerror: (e: any) => {
+          cb.onError?.(new Error(e?.message ?? String(e)));
+        },
+        onclose: (e: any) => {
+          if (wrapper) wrapper.closed = true;
+          cb.onClose?.(e?.reason || "");
+        },
+      },
+    });
+
+    wrapper = new GeminiLiveSession(options.model, session, cb);
+    return wrapper;
+  }
+}
+
+function handleMessage(msg: any, cb: RealtimeSessionOptions["callbacks"]): void {
+  const content = msg.serverContent;
+  if (content) {
+    for (const part of content.modelTurn?.parts ?? []) {
+      const data = part.inlineData?.data;
+      if (data) cb.onAudio?.(Buffer.from(data, "base64"));
+    }
+    if (content.inputTranscription?.text) cb.onInputTranscript?.(content.inputTranscription.text);
+    if (content.outputTranscription?.text) cb.onOutputTranscript?.(content.outputTranscription.text);
+    if (content.interrupted) cb.onInterrupted?.();
+    if (content.turnComplete) cb.onTurnComplete?.();
+  }
+
+  if (msg.toolCall?.functionCalls?.length) {
+    const calls: RealtimeToolCall[] = msg.toolCall.functionCalls.map((fc: any) => ({
+      id: fc.id ?? "",
+      name: fc.name ?? "",
+      args: (fc.args ?? {}) as Record<string, unknown>,
+    }));
+    cb.onToolCall?.(calls);
+  }
+
+  if (msg.toolCallCancellation?.ids?.length) {
+    cb.onToolCallCancellation?.(msg.toolCallCancellation.ids);
+  }
+
+  if (msg.usageMetadata) {
+    const u = msg.usageMetadata;
+    cb.onUsage?.({
+      inputTokens: Number(u.promptTokenCount ?? 0),
+      outputTokens: Number(u.responseTokenCount ?? 0),
+      totalTokens: Number(u.totalTokenCount ?? 0),
+    });
+  }
+
+  if (msg.sessionResumptionUpdate?.newHandle) {
+    cb.onResumptionHandle?.(msg.sessionResumptionUpdate.newHandle);
+  }
+
+  if (msg.goAway) {
+    cb.onGoAway?.(parseDuration(msg.goAway.timeLeft));
+  }
+}
+
+/** `timeLeft` llega como duración protobuf ("9.5s") o como objeto {seconds,nanos}. */
+function parseDuration(value: unknown): number {
+  if (typeof value === "string") {
+    const seconds = parseFloat(value.replace(/s$/, ""));
+    return Number.isFinite(seconds) ? Math.round(seconds * 1000) : 0;
+  }
+  if (value && typeof value === "object") {
+    const v = value as { seconds?: number | string; nanos?: number };
+    const seconds = Number(v.seconds ?? 0);
+    return Math.round(seconds * 1000 + (v.nanos ?? 0) / 1e6);
+  }
+  return 0;
+}

package/packages/core/src/agent/realtime-providers/index.ts

@@ -0,0 +1,29 @@
+/**
+ * Registro de proveedores de voz en tiempo real.
+ *
+ * Hoy sólo Gemini Live. La interfaz existe desacoplada para que añadir OpenAI
+ * Realtime o Nova Sonic no obligue a tocar el gateway ni el cliente: cambia el
+ * adaptador, no el transporte.
+ */
+
+import { GeminiLiveProvider } from "./gemini-live.ts";
+import type { RealtimeProvider } from "./interface.ts";
+
+export * from "./interface.ts";
+export { DEFAULT_GEMINI_LIVE_MODEL } from "./gemini-live.ts";
+
+const providers = new Map<string, RealtimeProvider>([["gemini", new GeminiLiveProvider()]]);
+
+export function getRealtimeProvider(providerId: string): RealtimeProvider {
+  const provider = providers.get(providerId);
+  if (!provider) {
+    throw new Error(
+      `El proveedor "${providerId}" no soporta voz en tiempo real. Disponibles: ${[...providers.keys()].join(", ")}`,
+    );
+  }
+  return provider;
+}
+
+export function isRealtimeProvider(providerId: string): boolean {
+  return providers.has(providerId);
+}

package/packages/core/src/agent/realtime-providers/interface.ts

@@ -0,0 +1,108 @@
+/**
+ * realtime-providers — sesiones de voz full-duplex (speech-to-speech).
+ *
+ * `LLMProvider` (../llm-providers/interface.ts) es one-shot: `call()` recibe un
+ * historial y devuelve una respuesta. Una sesión Live no encaja ahí — es un
+ * socket que vive minutos, recibe audio continuo y emite audio continuo. De ahí
+ * esta interfaz hermana en vez de una subclase.
+ *
+ * El modelo realtime NO es el cerebro de Hive: sólo oye, habla e interrumpe. El
+ * trabajo real lo hace el agent-loop de siempre (Bee → especialistas → tools).
+ * Por eso las herramientas que se declaran acá son un puñado fijo de funciones
+ * puente (gateway/realtime/bridge-tools.ts) y no el catálogo del agente: la Live
+ * API congela las tools en el `setup` y no admite cambiarlas a mitad de sesión.
+ */
+
+import type { LLMToolDef } from "../llm-client.ts";
+
+/** Lo que el micrófono debe entregar: PCM16 mono little-endian. */
+export const REALTIME_INPUT_SAMPLE_RATE = 16_000;
+/** Lo que el modelo devuelve: PCM16 mono. */
+export const REALTIME_OUTPUT_SAMPLE_RATE = 24_000;
+
+export interface RealtimeToolCall {
+  id: string;
+  name: string;
+  args: Record<string, unknown>;
+}
+
+export interface RealtimeCallbacks {
+  /** Audio del modelo, PCM16 mono a REALTIME_OUTPUT_SAMPLE_RATE. */
+  onAudio?: (pcm: Buffer) => void;
+  /** Transcripción de lo que dijo el usuario (fragmentos incrementales). */
+  onInputTranscript?: (text: string) => void;
+  /** Transcripción de lo que dijo el modelo (fragmentos incrementales). */
+  onOutputTranscript?: (text: string) => void;
+  onToolCall?: (calls: RealtimeToolCall[]) => void;
+  /** El modelo canceló tool calls ya emitidas (el usuario cambió de tema). */
+  onToolCallCancellation?: (ids: string[]) => void;
+  /** Barge-in: el usuario habló encima. Hay que vaciar la cola de reproducción YA. */
+  onInterrupted?: () => void;
+  onTurnComplete?: () => void;
+  /** Consumo acumulado que reporta el proveedor. */
+  onUsage?: (usage: { inputTokens: number; outputTokens: number; totalTokens: number }) => void;
+  /** Handle para reanudar la sesión tras un corte (válido ~2 h). */
+  onResumptionHandle?: (handle: string) => void;
+  /** El servidor va a cerrar la conexión; hay que reconectar con el handle. */
+  onGoAway?: (timeLeftMs: number) => void;
+  onError?: (error: Error) => void;
+  onClose?: (reason: string) => void;
+}
+
+export interface RealtimeSessionOptions {
+  model: string;
+  apiKey: string;
+  /** Prompt de la sesión de voz (no es el system prompt del agent-loop). */
+  systemInstruction: string;
+  /** Funciones puente. Congeladas: la Live API no permite cambiarlas después. */
+  tools?: LLMToolDef[];
+  /** Voz del proveedor (ej. "Kore"). Ver voiceService.getGeminiVoices(). */
+  voice?: string;
+  /**
+   * Idioma con acento regional, en BCP-47 (es-CO, es-MX, en-US…).
+   *
+   * Los modelos de audio nativo cambian de idioma solos siguiendo al usuario,
+   * pero sin esto eligen el acento por su cuenta: un usuario colombiano puede
+   * terminar escuchando español rioplatense.
+   */
+  language?: string;
+  /** Silencio en ms que cierra el turno del usuario (VAD automático). */
+  silenceDurationMs?: number;
+  /**
+   * Cuánto cuesta que el modelo dé por empezada una intervención del usuario.
+   * `START_SENSITIVITY_LOW` sube el listón: hace falta voz clara para
+   * interrumpirle, en vez de cualquier ruido. Es lo que salva las manos libres,
+   * donde lo que entra por el micrófono incluye su propia voz rebotando.
+   */
+  startOfSpeechSensitivity?: "START_SENSITIVITY_LOW" | "START_SENSITIVITY_HIGH";
+  /** Handle devuelto por una sesión anterior, para retomar el hilo. */
+  resumptionHandle?: string;
+  callbacks: RealtimeCallbacks;
+}
+
+export interface RealtimeSession {
+  readonly model: string;
+  /** PCM16 mono a REALTIME_INPUT_SAMPLE_RATE. */
+  sendAudio(pcm: ArrayBufferLike): void;
+  /**
+   * Un fotograma de la cámara, ya codificado (JPEG en base64).
+   *
+   * Va a baja cadencia a propósito: con vídeo, la Live API recorta la sesión de
+   * 15 minutos a unos 2 y cada imagen cuesta cientos de tokens frente a los 25
+   * por segundo del audio.
+   */
+  sendVideoFrame(base64: string, mimeType: string): void;
+  /** Inyecta texto en la conversación (narración de la colmena, avisos). */
+  sendText(text: string): void;
+  sendToolResult(id: string, name: string, result: Record<string, unknown>): void;
+  close(): void;
+  readonly closed: boolean;
+}
+
+export interface RealtimeProvider {
+  readonly id: string;
+  connect(options: RealtimeSessionOptions): Promise<RealtimeSession>;
+}
+
+/** Toolset fijo de una sesión de voz, en el formato canónico de Hive. */
+export type RealtimeToolset = LLMToolDef[];