@johpaz/hive-sdk 0.1.6 → 0.2.0

package/packages/core/src/agent/reflector.ts

@@ -11,12 +11,12 @@
  * trick the SQLite version used — HiveDB has no equivalent primitive.
  */
 
-import { logger } from "../utils/logger"
-import { col, nextId } from "../storage/hive"
-import { getHiveDb } from "../storage/hivedb"
-import { loadConfig } from "../config/loader"
+import { logger } from "../utils/logger.ts"
+import { col, nextId } from "../storage/hive.ts"
+import { getHiveDb } from "../storage/hivedb.ts"
+import { loadConfig } from "../config/loader.ts"
 import type { HiveDB, ToolStats } from "@johpaz/hive-db"
-import type { TraceDoc, ReflectionDoc, CursorDoc } from "../storage/collections"
+import type { TraceDoc, ReflectionDoc, CursorDoc } from "../storage/collections.ts"
 
 const log = logger.child("reflector")
 
@@ -88,7 +88,7 @@ export async function runReflector(): Promise<void> {
     await cursorsCol.put(CURSOR_ID, { value: newCursor }, cursorEntry ? { expectedVersion: cursorEntry.version } : { expectedVersion: 0 })
 
     // Trigger curator
-    const { runCurator } = await import("./curator")
+    const { runCurator } = await import("./curator.ts")
     await runCurator()
 
     log.info(`[reflector] Reflection cycle completed successfully`)

package/packages/core/src/agent/run-store.ts

@@ -10,14 +10,14 @@
  * should write to a run; single-writer pattern keeps contention minimal.
  */
 
-import { col, updateDoc, nextId, toIndexable } from "../storage/hive";
-import type { AgentRunDoc } from "../storage/collections";
-import { getBootId } from "../storage/boot-id";
-import { logger } from "../utils/logger";
-import { loadConfig } from "../config/loader";
-import type { LLMMessage } from "./llm-client";
-import type { RunEpoch } from "./run-epoch";
-import { formatInternalEvent } from "./conversation-store";
+import { col, updateDoc, nextId, toIndexable } from "../storage/hive.ts";
+import type { AgentRunDoc } from "../storage/collections.ts";
+import { getBootId } from "../storage/boot-id.ts";
+import { logger } from "../utils/logger.ts";
+import { loadConfig } from "../config/loader.ts";
+import type { LLMMessage } from "./llm-client.ts";
+import type { RunEpoch } from "./run-epoch.ts";
+import { formatInternalEvent } from "./conversation-store.ts";
 
 const log = logger.child("run-store");
 

package/packages/core/src/agent/service.ts

@@ -12,15 +12,15 @@
  * - Eventos (cron, etc.)
  */
 
-import { logger } from "../utils/logger"
-import { buildSystemPromptWithProjects } from "./prompt-builder"
-import { getAgentLoop, rebuildAgentLoop } from "./agent-loop"
+import { logger } from "../utils/logger.ts"
+import { buildSystemPromptWithProjects } from "./prompt-builder.ts"
+import { getAgentLoop, rebuildAgentLoop } from "./agent-loop.ts"
 import type { MCPClientManager } from "../mcp/index.ts"
-import { resolveAgentId, resolveUserId } from "../storage/onboarding"
-import { getMCPManager as getSingletonMCPManager } from "../mcp/singleton"
-import type { ContentPart } from "./llm-client"
-import { col, fromIndexable } from "../storage/hive"
-import type { AgentDoc, EthicsDoc } from "../storage/collections"
+import { resolveAgentId, resolveUserId } from "../storage/onboarding.ts"
+import { getMCPManager as getSingletonMCPManager } from "../mcp/singleton.ts"
+import type { ContentPart } from "./llm-client.ts"
+import { col, fromIndexable } from "../storage/hive.ts"
+import type { AgentDoc, EthicsDoc } from "../storage/collections.ts"
 
 const log = logger.child("agent-service")
 
@@ -161,7 +161,7 @@ export class AgentService {
    */
   async reloadSkills(): Promise<void> {
     log.info("Reloading skills...")
-    const { syncSkillsToIndex } = await import("./context-compiler")
+    const { syncSkillsToIndex } = await import("./context-compiler.ts")
     await syncSkillsToIndex()
     log.info("Skills reloaded")
   }
@@ -252,7 +252,7 @@ export class AgentService {
    * Ejecuta un agente con un mensaje
    */
   async runAgent(message: string | ContentPart[], threadId: string, userId?: string): Promise<string> {
-    const { runAgentIsolated } = await import("./agent-loop")
+    const { runAgentIsolated } = await import("./agent-loop.ts")
     const result = await runAgentIsolated({
       agentId: this.agentId,
       taskDescription: message,

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

@@ -16,17 +16,17 @@
  * 5. Returns skill content for injection into system prompt
  */
 
-import { col } from "../storage/hive"
-import type { SkillDoc } from "../storage/collections"
-import { logger } from "../utils/logger"
-import { isMinimalSkill } from "./minimal-loadout"
-import { isCalendarOperation } from "./routing-intent"
+import { col } from "../storage/hive.ts"
+import type { SkillDoc } from "../storage/collections.ts"
+import { logger } from "../utils/logger.ts"
+import { isMinimalSkill } from "./minimal-loadout.ts"
+import { isCalendarOperation } from "./routing-intent.ts"
 import {
     searchCapabilities,
     applyRelativeCutoff,
     replaceCapabilityDocs,
     type CapabilityDoc,
-} from "./capability-search"
+} from "./capability-search.ts"
 
 const log = logger.child("skill-selector")
 

package/packages/core/src/agent/thread-id.ts

@@ -0,0 +1,71 @@
+/**
+ * Thread identity — `${userId}/${channel}/${peerId}`.
+ *
+ * Un hilo por canal Y por contacto: el chat privado de Telegram, cada grupo de
+ * WhatsApp y cada conversación de la web tienen historial propio. Antes había un
+ * único hilo por usuario (`threadId = userId`) compartido por todos los canales.
+ *
+ * Dos reglas de formato que no son cosméticas:
+ *
+ * 1. El separador es "/" y NO ":". Los mensajes viven en `conversations` con id
+ *    `${threadId}:${seq}` y se leen por prefijo (`scan({ prefix: "${threadId}:" })`),
+ *    sin índice secundario. El hilo legacy (id = userId pelado) se lee con prefijo
+ *    `${userId}:`; si los hilos nuevos fueran `${userId}:webchat:...` ese scan se los
+ *    tragaría enteros. Con "/" el historial viejo queda aislado sin migrar una fila.
+ *
+ * 2. Ningún segmento puede contener ":" — se sustituye por "_". Sin esto los peerIds
+ *    compuestos rompen el aislamiento por prefijo: el DM de Telegram `12345` y el grupo
+ *    `12345:678` (telegram.ts arma así el peerId de grupo) producirían los prefijos
+ *    `.../12345:` y `.../12345:678:`, y el primero es prefijo del segundo — el DM leería
+ *    los mensajes del grupo. Colapsar ":" hace que `${threadId}:` sea siempre un
+ *    separador inequívoco, y mantiene válido el `lastIndexOf(":")` con que
+ *    conversation-store extrae el número de secuencia.
+ */
+
+export const THREAD_SEP = "/"
+
+/** Canal sintético de las tareas programadas: un hilo estable por cron job. */
+export const CRON_CHANNEL = "cron"
+
+export interface ThreadParts {
+  userId: string
+  channel: string
+  peerId: string
+}
+
+/**
+ * Deja un segmento apto para formar parte de un threadId: sin "/" (rompería el
+ * parseo) y sin ":" (rompería el aislamiento por prefijo — ver cabecera).
+ */
+export function sanitizeSegment(value: string): string {
+  return value.replace(/[/:]/g, "_").trim()
+}
+
+export function makeThreadId(userId: string, channel: string, peerId: string): string {
+  const parts = [userId, channel, peerId].map((p) => sanitizeSegment(p || "") || "default")
+  return parts.join(THREAD_SEP)
+}
+
+/**
+ * Descompone un threadId con formato. Devuelve null para todo lo que no lo tenga:
+ * el hilo legacy (`userId` pelado), los hilos aislados de los workers
+ * (`task-<id>-<agente>`) y cualquier id heredado. Quien llame debe conservar su
+ * comportamiento anterior ante un null, nunca inventar partes.
+ */
+export function parseThreadId(threadId: string): ThreadParts | null {
+  if (!threadId) return null
+  const parts = threadId.split(THREAD_SEP)
+  if (parts.length !== 3) return null
+  const [userId, channel, peerId] = parts
+  if (!userId || !channel || !peerId) return null
+  return { userId, channel, peerId }
+}
+
+export function isStructuredThreadId(threadId: string): boolean {
+  return parseThreadId(threadId) !== null
+}
+
+/** Id de una conversación nueva de la web. No lo elige el cliente. */
+export function newWebConversationId(): string {
+  return `conv-${crypto.randomUUID().replace(/-/g, "").slice(0, 12)}`
+}

package/packages/core/src/agent/thread-store.ts

@@ -0,0 +1,250 @@
+/**
+ * Thread store — el registro de conversaciones (`conversationThreads`).
+ *
+ * `conversations` no tiene índice secundario: los mensajes se leen por prefijo del
+ * threadId. Esta colección es el catálogo que permite listar las conversaciones de
+ * un usuario, ponerles título y borrarlas sin escanear todos los mensajes.
+ *
+ * El id de cada fila ES el threadId. La única fila cuyo id no tiene formato
+ * `${user}/${canal}/${peer}` es la del hilo legacy anterior a la separación por
+ * canal (ver ensureLegacyThread).
+ */
+
+import { col, updateDoc } from "../storage/hive.ts"
+import { logger } from "../utils/logger.ts"
+import type { ConversationThreadDoc, ConversationDoc, SummaryDoc } from "../storage/collections.ts"
+import { makeThreadId, parseThreadId, newWebConversationId } from "./thread-id.ts"
+
+const log = logger.child("thread-store")
+
+const TITLE_MAX_CHARS = 60
+
+/** Reintentos del contador ante mensajes concurrentes del mismo hilo. */
+const TOUCH_MAX_RETRIES = 5
+
+export interface EnsureThreadInput {
+  userId: string
+  channel: string
+  peerId: string
+  peerKind?: "direct" | "group"
+}
+
+async function threadsCol() {
+  return col<ConversationThreadDoc>("conversationThreads")
+}
+
+export async function getThread(threadId: string): Promise<ConversationThreadDoc | null> {
+  const c = await threadsCol()
+  const entry = await c.get(threadId)
+  return entry?.doc ?? null
+}
+
+/**
+ * Crea la fila de la conversación si aún no existe y devuelve su threadId.
+ * Idempotente: se llama en cada turno desde resolveContext.
+ */
+export async function ensureThread(input: EnsureThreadInput): Promise<string> {
+  const threadId = makeThreadId(input.userId, input.channel, input.peerId)
+  const c = await threadsCol()
+  const existing = await c.get(threadId)
+  if (existing) return threadId
+
+  const now = Date.now()
+  try {
+    await c.put(threadId, {
+      id: threadId,
+      user_id: input.userId,
+      channel: input.channel,
+      peer_id: input.peerId,
+      peer_kind: input.peerKind ?? "direct",
+      title: null,
+      archived: false,
+      created_at: now,
+      last_message_at: now,
+      message_count: 0,
+    }, { expectedVersion: 0 })
+  } catch {
+    // Otro turno del mismo canal la creó primero — ambos quieren lo mismo.
+  }
+  return threadId
+}
+
+/** Conversación nueva de la web. El id lo elige el servidor, nunca el cliente. */
+export async function createWebConversation(userId: string, title?: string): Promise<ConversationThreadDoc> {
+  const peerId = newWebConversationId()
+  const threadId = await ensureThread({ userId, channel: "webchat", peerId, peerKind: "direct" })
+  if (title?.trim()) await renameThread(threadId, title)
+  const doc = await getThread(threadId)
+  if (!doc) throw new Error(`No pude crear la conversación ${threadId}`)
+  return doc
+}
+
+/**
+ * Título derivado del primer mensaje del usuario. El contenido llega con el
+ * prefijo `[Timestamp: ...]` que le añaden el gateway y las rutas REST: esa línea
+ * no describe nada, así que se descarta antes de recortar.
+ */
+export function deriveTitle(text: string): string | null {
+  const withoutTimestamp = text.replace(/^\[Timestamp:[^\]]*\]\s*/, "").trim()
+  const firstLine = withoutTimestamp.split("\n").find((l) => l.trim().length > 0)?.trim()
+  if (!firstLine) return null
+  return firstLine.length > TITLE_MAX_CHARS
+    ? `${firstLine.slice(0, TITLE_MAX_CHARS - 1)}…`
+    : firstLine
+}
+
+/**
+ * Registra actividad en el hilo: contador, fecha del último mensaje y —la primera
+ * vez que habla el usuario— el título.
+ *
+ * Si el hilo tiene formato y no existe la fila, la crea (es el caso de un hilo que
+ * nació fuera de resolveContext, como el de una tarea programada). Si no lo tiene
+ * —hilo legacy, hilos aislados `task-*`— solo actualiza una fila ya existente:
+ * nunca inventa conversaciones para los hilos internos de los workers.
+ */
+export async function touchThread(
+  threadId: string,
+  opts: { role: "user" | "assistant" | "tool"; text?: string; internal?: boolean }
+): Promise<void> {
+  try {
+    const c = await threadsCol()
+    let existing = await c.get(threadId)
+
+    if (!existing) {
+      const parts = parseThreadId(threadId)
+      if (!parts) return
+      await ensureThread({ userId: parts.userId, channel: parts.channel, peerId: parts.peerId })
+      existing = await c.get(threadId)
+      if (!existing) return
+    }
+
+    // El contador se recalcula DENTRO del reintento, no fuera. `addMessage` llama
+    // acá sin esperar el resultado, así que dos mensajes seguidos se solapan: con
+    // el incremento calculado una sola vez, el reintento por conflicto de versión
+    // vuelve a escribir el valor viejo y el conteo se queda corto para siempre.
+    for (let attempt = 0; attempt < TOUCH_MAX_RETRIES; attempt++) {
+      const fresh = attempt === 0 ? existing : await c.get(threadId)
+      if (!fresh) return
+
+      const next: ConversationThreadDoc = {
+        ...fresh.doc,
+        last_message_at: Date.now(),
+        message_count: fresh.doc.message_count + 1,
+      }
+      // El título sale del primer mensaje humano: ni de la respuesta del agente ni
+      // de un evento interno (fan-in de delegación), que no describen el tema.
+      if (!fresh.doc.title && opts.role === "user" && !opts.internal && opts.text) {
+        const title = deriveTitle(opts.text)
+        if (title) next.title = title
+      }
+
+      try {
+        await c.put(threadId, next, { expectedVersion: fresh.version })
+        return
+      } catch {
+        // Conflicto de versión: otro mensaje del mismo hilo llegó primero.
+      }
+    }
+    log.warn(`demasiada contención actualizando el hilo ${threadId}`)
+  } catch (err) {
+    // El registro es un catálogo, no la fuente de verdad: nunca debe tumbar un turno.
+    log.warn(`no pude actualizar el hilo ${threadId}: ${(err as Error).message}`)
+  }
+}
+
+export async function listThreads(
+  userId: string,
+  opts?: { channel?: string; includeArchived?: boolean }
+): Promise<ConversationThreadDoc[]> {
+  const c = await threadsCol()
+  const rows = await c.findBy("user_id", userId)
+  return rows
+    .map((r) => r.doc)
+    .filter((d) => (opts?.channel ? d.channel === opts.channel : true))
+    .filter((d) => (opts?.includeArchived ? true : !d.archived))
+    .sort((a, b) => b.last_message_at - a.last_message_at)
+}
+
+/** La conversación de webchat en la que seguiría escribiendo el usuario. */
+export async function mostRecentWebThread(userId: string): Promise<ConversationThreadDoc | null> {
+  const threads = await listThreads(userId, { channel: "webchat" })
+  return threads[0] ?? null
+}
+
+export async function renameThread(threadId: string, title: string): Promise<void> {
+  const clean = title.trim().slice(0, 200)
+  await updateDoc<ConversationThreadDoc>("conversationThreads", threadId, { title: clean || null })
+}
+
+/**
+ * Borra la conversación entera: mensajes, resumen, notas y la fila del registro.
+ * Los mensajes se localizan por prefijo, igual que los lee conversation-store.
+ */
+export async function deleteThread(threadId: string): Promise<void> {
+  const conversations = await col<ConversationDoc>("conversations")
+  const messages = await conversations.scan({ prefix: `${threadId}:` })
+  for (const m of messages) await conversations.delete(m.id)
+
+  const summaries = await col<SummaryDoc>("summaries")
+  await summaries.delete(threadId).catch(() => {})
+
+  const scratchpad = await col<{ threadId: string }>("scratchpad")
+  const notes = await scratchpad.scan({ prefix: `${threadId}:` })
+  for (const n of notes) await scratchpad.delete(n.id)
+
+  const c = await threadsCol()
+  await c.delete(threadId).catch(() => {})
+
+  log.info(`conversación ${threadId} borrada (${messages.length} mensajes)`)
+}
+
+/**
+ * El hilo por el que hablarle a alguien en un canal cuando no venimos de un
+ * mensaje suyo (avisos de tareas programadas, por ejemplo).
+ *
+ * En la web es la conversación activa; en los demás canales, el contacto al que
+ * apunta `userIdentities`. Devuelve null si no hay ninguno, y quien llame decide
+ * el fallback.
+ */
+export async function threadForChannel(userId: string, channel: string): Promise<string | null> {
+  if (channel === "webchat") return (await mostRecentWebThread(userId))?.id ?? null
+
+  const identities = await col<{ channel_user_id?: string }>("userIdentities")
+  const identity = await identities.get(`${userId}:${channel}`)
+  const peerId = identity?.doc.channel_user_id
+  return peerId ? makeThreadId(userId, channel, peerId) : null
+}
+
+/**
+ * Registra el hilo anterior a la separación por canal —`thread_id = userId`, un
+ * único hilo compartido por todos los canales— como una conversación más de la
+ * web, para que su historial siga siendo accesible. No mueve ni reescribe ningún
+ * mensaje: la fila apunta al mismo prefijo de siempre.
+ */
+export async function ensureLegacyThread(userId: string): Promise<boolean> {
+  const c = await threadsCol()
+  if (await c.get(userId)) return false
+
+  const conversations = await col<ConversationDoc>("conversations")
+  const sample = await conversations.scan({ prefix: `${userId}:`, limit: 1 })
+  if (sample.length === 0) return false
+
+  const all = await conversations.scan({ prefix: `${userId}:` })
+  const lastAt = all.reduce((max, e) => Math.max(max, e.doc.created_at), 0)
+
+  await c.put(userId, {
+    id: userId,
+    user_id: userId,
+    channel: "webchat",
+    peer_id: "legacy",
+    peer_kind: "direct",
+    title: "Conversación anterior",
+    archived: false,
+    created_at: all[0]?.doc.created_at ?? Date.now(),
+    last_message_at: lastAt || Date.now(),
+    message_count: all.length,
+  }, { expectedVersion: 0 }).catch(() => {})
+
+  log.info(`hilo legacy ${userId} registrado como conversación (${all.length} mensajes)`)
+  return true
+}

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

@@ -40,16 +40,16 @@
  *    - core (notify, report_progress, save_note)
  */
 
-import { col } from "../storage/hive"
-import type { ToolDoc } from "../storage/collections"
-import { logger } from "../utils/logger"
+import { col } from "../storage/hive.ts"
+import type { ToolDoc } from "../storage/collections.ts"
+import { logger } from "../utils/logger.ts"
 import {
     searchCapabilities,
     applyRelativeCutoff,
     replaceCapabilityDocs,
     type CapabilityDoc,
-} from "./capability-search"
-import { isCalendarOperation } from "./routing-intent"
+} from "./capability-search.ts"
+import { isCalendarOperation } from "./routing-intent.ts"
 
 const log = logger.child("tool-selector")
 
@@ -200,7 +200,9 @@ export const CORE_TOOL_CATALOG: ToolDescriptor[] = [
     { name: "api_request", description: "Perform an authorized HTTP request against a REST endpoint and validate the response. Spanish keywords: llamar api, request rest, consumir endpoint, petición http, hacer get, hacer post", category: "api", abstractionLevel: "atomic" },
 
     // Artifacts
+    { name: "computer_use_task", description: "Operate the browser by looking at the screen: click by coordinates, type and navigate when no stable CSS selector exists (canvas, generated UIs, embedded viewers). Acts on Hive's own browser, never on the user screen. Spanish keywords: usar el navegador, hacer clic donde veas, operar una página, rellenar formulario, computer use, mirar la pantalla", category: "browser", abstractionLevel: "orchestration" },
     { name: "artifact_inspect", description: "Inspect a managed artifact's integrity and metadata without modifying it. Spanish keywords: inspeccionar artefacto, verificar archivo generado, metadatos artefacto, comprobar entrega", category: "web", abstractionLevel: "atomic" },
+    { name: "artifact_read", description: "Read a managed artifact's text content in slices, or search inside it — the way to open any artifact_ref a tool returned. Spanish keywords: leer artefacto, ver contenido del artefacto, abrir resultado grande, buscar dentro del artefacto", category: "web", abstractionLevel: "atomic" },
 
     // Office documents — read
     { name: "office_leer_pdf", description: "Read and extract text from a PDF document. Spanish keywords: leer pdf, extraer texto pdf, abrir pdf, contenido pdf", category: "office", abstractionLevel: "atomic" },

package/packages/core/src/agent/tracer.ts

@@ -6,9 +6,9 @@
  * `agents.lastTraceAt` field used by the Curator's stale-worker detection.
  */
 
-import { logger } from "../utils/logger"
-import { col, nextId, updateDoc } from "../storage/hive"
-import type { TraceDoc, AgentDoc } from "../storage/collections"
+import { logger } from "../utils/logger.ts"
+import { col, nextId, updateDoc } from "../storage/hive.ts"
+import type { TraceDoc, AgentDoc } from "../storage/collections.ts"
 
 const log = logger.child("tracer")
 
@@ -82,7 +82,7 @@ async function checkReflectorTrigger(): Promise<void> {
   _tracesSinceLastReflection = 0
 
   // Lazy import to avoid circular deps
-  const { runReflector } = await import("./reflector")
+  const { runReflector } = await import("./reflector.ts")
   runReflector().catch((err) => {
     log.warn("[tracer] Reflector run failed:", err)
   })
@@ -98,7 +98,7 @@ export function recordLLMUsage(opts: {
 }): void {
   Promise.resolve().then(async () => {
     try {
-      const { recordUsage } = await import("../storage/usage")
+      const { recordUsage } = await import("../storage/usage.ts")
       recordUsage({
         provider: opts.provider,
         model: opts.model,

package/packages/core/src/api/createAgent.ts

@@ -92,7 +92,7 @@ export async function createAgent(config: AgentConfig): Promise<Agent> {
 
 	const coreConfig = await loadConfig();
 
-	// Browser automation (agent-browser) si está habilitado.
+	// Browser automation (Bun.WebView) si está habilitado.
 	try {
 		const { initializeBrowserService } = await import("../tools/web/browser-service.ts");
 		const browserService = initializeBrowserService(coreConfig);

package/packages/core/src/artifacts/store.ts

@@ -8,9 +8,9 @@ import {
   writeFileSync,
 } from "node:fs";
 import { extname, join } from "node:path";
-import { getHiveDir } from "../config/loader";
-import { col, updateDoc } from "../storage/hive";
-import type { ArtifactDoc } from "../storage/collections";
+import { getHiveDir } from "../config/loader.ts";
+import { col, updateDoc } from "../storage/hive.ts";
+import type { ArtifactDoc } from "../storage/collections.ts";
 
 const ARTIFACT_RETENTION_MS = 7 * 24 * 60 * 60 * 1000;
 
@@ -91,6 +91,87 @@ export async function createArtifact(input: {
   }
 }
 
+/**
+ * Reads an artifact's bytes straight off disk — for server-side consumers
+ * that don't need an HTTP round trip (routes/artifacts.ts is for the
+ * browser; channels/*.ts send()s use this directly to build a Telegram/
+ * Discord/Slack/WhatsApp photo attachment from the same file).
+ */
+export async function readArtifactBytes(
+  artifactId: string,
+): Promise<{ bytes: Buffer; mimeType: string } | null> {
+  const artifacts = await col<ArtifactDoc>("artifacts");
+  const entry = await artifacts.get(artifactId);
+  if (!entry || entry.doc.status !== "active") return null;
+  if (!existsSync(entry.doc.path)) return null;
+  return { bytes: readFileSync(entry.doc.path), mimeType: entry.doc.mime_type };
+}
+
+/** Beyond this an artifact stops being something an agent can read into a context window. */
+const MAX_TEXT_ARTIFACT_BYTES = 25 * 1024 * 1024;
+
+function looksBinary(mimeType: string, bytes: Buffer): boolean {
+  if (/^(image|audio|video)\//.test(mimeType)) return true;
+  if (mimeType === "application/octet-stream") return true;
+  // A NUL byte in the first KB is the classic "this is not text" tell — a
+  // mislabelled text/plain artifact would otherwise decode to garbage.
+  return bytes.subarray(0, 1024).includes(0x00);
+}
+
+export type ArtifactTextResult = {
+  ok: boolean;
+  text?: string;
+  artifact?: ArtifactDoc;
+  error?: string;
+  status?: string;
+};
+
+/**
+ * Decodes a text artifact for in-process consumers that need its *content*,
+ * not just its metadata (inspectArtifact) or its raw bytes (readArtifactBytes).
+ *
+ * This exists because mcp-result-normalizer.ts moves oversized MCP text results
+ * out of the context window and hands the model an `artifact_ref` instead. Until
+ * this, nothing could read that reference back: the agent held a receipt it
+ * could not cash, burned its iterations guessing, and the turn died on an empty
+ * synthesis. Ownership and status checks mirror inspectArtifact's.
+ */
+export async function readArtifactText(
+  artifactId: string,
+  options: { userId?: string } = {},
+): Promise<ArtifactTextResult> {
+  const artifacts = await col<ArtifactDoc>("artifacts");
+  const entry = await artifacts.get(artifactId);
+  if (!entry) return { ok: false, error: "Artifact not found" };
+  const artifact = entry.doc;
+
+  if (options.userId && artifact.user_id && artifact.user_id !== options.userId) {
+    return { ok: false, error: "Artifact not accessible" };
+  }
+  if (artifact.status !== "active") {
+    return { ok: false, error: "Artifact binary has expired", status: artifact.status };
+  }
+  if (!existsSync(artifact.path)) {
+    return { ok: false, error: "Artifact binary is missing", status: "missing" };
+  }
+  if (artifact.size > MAX_TEXT_ARTIFACT_BYTES) {
+    return {
+      ok: false,
+      error: `Artifact is too large to read as text (${artifact.size} bytes, limit ${MAX_TEXT_ARTIFACT_BYTES})`,
+    };
+  }
+
+  const bytes = readFileSync(artifact.path);
+  if (looksBinary(detectedMime(bytes, artifact.mime_type), bytes)) {
+    return {
+      ok: false,
+      error: `Artifact is binary (${detectedMime(bytes, artifact.mime_type)}) — use artifact_inspect for its metadata`,
+    };
+  }
+
+  return { ok: true, text: bytes.toString("utf-8"), artifact };
+}
+
 export async function inspectArtifact(
   artifactId: string,
   options: { userId?: string } = {},

package/packages/core/src/canvas/emitter.ts

@@ -1,5 +1,5 @@
-import { col, fromIndexable } from "../storage/hive"
-import type { AgentDoc, McpServerDoc } from "../storage/collections"
+import { col, fromIndexable } from "../storage/hive.ts"
+import type { AgentDoc, McpServerDoc } from "../storage/collections.ts"
 
 export interface CanvasEvent {
   type: CanvasEventType

package/packages/core/src/channels/telegram.ts

@@ -3,7 +3,7 @@ import { BaseChannel, type ChannelConfig, type IncomingMessage, type OutboundMes
 import { logger } from "../utils/logger.ts";
 import { col, updateDoc } from "../storage/hive.ts";
 import type { ChannelDoc, UserIdentityDoc } from "../storage/collections.ts";
-import { resolveUserId } from "../storage/onboarding";
+import { resolveUserId } from "../storage/onboarding.ts";
 
 export interface TelegramConfig extends ChannelConfig {
   botToken: string;

package/packages/core/src/channels/webchat.ts

@@ -1,7 +1,7 @@
 import type { ServerWebSocket } from "bun";
 import { BaseChannel, type ChannelConfig, type IncomingMessage, type OutboundMessage } from "./base.ts";
 import { logger } from "../utils/logger.ts";
-import { resolveUserId } from "../storage/onboarding";
+import { resolveUserId } from "../storage/onboarding.ts";
 
 export interface WebChatConfig extends ChannelConfig {
   accountId?: string;