@danieltmn/tamnora 0.9.3 → 0.9.5

package/harness/packages/core/src/browser/index.js

@@ -0,0 +1,289 @@
+// Navegador headless sin dependencias: usa el Chrome/Edge/Chromium del sistema y
+// lo maneja por el protocolo DevTools (CDP) sobre el WebSocket global de Node
+// 22+ (el mismo recurso que usa el cliente de TTS de Edge). Permite sacar una
+// captura de una pagina y leer los errores de consola, que es lo que un
+// `fetch_url` (GET crudo, sin JS) no puede hacer.
+
+import { spawn } from 'node:child_process';
+import { existsSync, mkdtempSync, rmSync } from 'node:fs';
+import { tmpdir } from 'node:os';
+import path from 'node:path';
+
+const LAUNCH_TIMEOUT_MS = 15000;
+
+function winPaths() {
+  const roots = [process.env['ProgramFiles'], process.env['ProgramFiles(x86)'], process.env.LOCALAPPDATA].filter(Boolean);
+  const out = [];
+  for (const root of roots) {
+    out.push(path.join(root, 'Google', 'Chrome', 'Application', 'chrome.exe'));
+    out.push(path.join(root, 'Microsoft', 'Edge', 'Application', 'msedge.exe'));
+  }
+  return out;
+}
+
+const CANDIDATES = {
+  win32: winPaths(),
+  darwin: [
+    '/Applications/Google Chrome.app/Contents/MacOS/Google Chrome',
+    '/Applications/Chromium.app/Contents/MacOS/Chromium',
+    '/Applications/Microsoft Edge.app/Contents/MacOS/Microsoft Edge',
+  ],
+  linux: [
+    '/usr/bin/google-chrome',
+    '/usr/bin/google-chrome-stable',
+    '/usr/bin/chromium',
+    '/usr/bin/chromium-browser',
+    '/usr/bin/microsoft-edge',
+    '/snap/bin/chromium',
+  ],
+};
+
+/** Ruta al navegador headless, o null. `TAMNORA_BROWSER` la forca. */
+export function findBrowserPath() {
+  const override = process.env.TAMNORA_BROWSER;
+  if (override && existsSync(override)) return override;
+  for (const candidate of CANDIDATES[process.platform] ?? []) {
+    if (existsSync(candidate)) return candidate;
+  }
+  return null;
+}
+
+function delay(ms) {
+  return new Promise((resolve) => setTimeout(resolve, ms));
+}
+
+function launchBrowser(bin) {
+  return new Promise((resolve, reject) => {
+    const profile = mkdtempSync(path.join(tmpdir(), 'tamnora-browser-'));
+    const args = [
+      '--headless=new',
+      '--disable-gpu',
+      '--hide-scrollbars',
+      '--no-first-run',
+      '--no-default-browser-check',
+      '--disable-extensions',
+      '--disable-background-networking',
+      '--remote-debugging-port=0',
+      `--user-data-dir=${profile}`,
+      'about:blank',
+    ];
+    let child;
+    try {
+      child = spawn(bin, args, { stdio: ['ignore', 'ignore', 'pipe'], windowsHide: true });
+    } catch (error) {
+      reject(new Error(`no se pudo ejecutar el navegador: ${error.message}`));
+      return;
+    }
+
+    let settled = false;
+    let stderr = '';
+    const finish = (fn) => {
+      if (settled) return;
+      settled = true;
+      clearTimeout(timer);
+      fn();
+    };
+    const timer = setTimeout(
+      () => finish(() => reject(new Error('el navegador no arrancó (timeout de DevTools)'))),
+      LAUNCH_TIMEOUT_MS
+    );
+
+    child.stderr.on('data', (chunk) => {
+      stderr += chunk.toString();
+      const match = /DevTools listening on (ws:\/\/\S+)/.exec(stderr);
+      if (match) finish(() => resolve({ child, wsUrl: match[1], profile }));
+    });
+    child.on('error', (error) => finish(() => reject(new Error(`no se pudo ejecutar el navegador: ${error.message}`))));
+    child.on('exit', () => finish(() => reject(new Error('el navegador se cerró antes de estar listo'))));
+  });
+}
+
+class CdpConnection {
+  constructor(ws) {
+    this.ws = ws;
+    this.seq = 0;
+    this.pending = new Map();
+    this.listeners = new Set();
+    ws.addEventListener('message', (event) => {
+      let message;
+      try {
+        message = JSON.parse(typeof event.data === 'string' ? event.data : String(event.data));
+      } catch {
+        return;
+      }
+      if (message.id && this.pending.has(message.id)) {
+        const { resolve, reject } = this.pending.get(message.id);
+        this.pending.delete(message.id);
+        if (message.error) reject(new Error(message.error.message || 'error de CDP'));
+        else resolve(message.result ?? {});
+      } else {
+        for (const listener of this.listeners) listener(message);
+      }
+    });
+  }
+
+  open() {
+    return new Promise((resolve, reject) => {
+      const timer = setTimeout(() => reject(new Error('timeout conectando al navegador')), 10000);
+      this.ws.addEventListener('open', () => {
+        clearTimeout(timer);
+        resolve();
+      }, { once: true });
+      this.ws.addEventListener('error', () => {
+        clearTimeout(timer);
+        reject(new Error('no se pudo conectar al navegador'));
+      }, { once: true });
+    });
+  }
+
+  send(method, params = {}, sessionId) {
+    const id = ++this.seq;
+    return new Promise((resolve, reject) => {
+      this.pending.set(id, { resolve, reject });
+      this.ws.send(JSON.stringify({ id, method, params, ...(sessionId ? { sessionId } : {}) }));
+    });
+  }
+
+  on(listener) {
+    this.listeners.add(listener);
+    return () => this.listeners.delete(listener);
+  }
+
+  close() {
+    try {
+      this.ws.close();
+    } catch {
+      /* nada */
+    }
+  }
+}
+
+function describeArg(arg) {
+  if (!arg) return '';
+  if ('value' in arg) {
+    return typeof arg.value === 'string' ? arg.value : JSON.stringify(arg.value);
+  }
+  if (arg.description) return arg.description;
+  if (arg.preview?.properties?.length) {
+    return arg.preview.properties.map((p) => `${p.name}: ${p.value}`).join(', ');
+  }
+  return String(arg.type ?? '');
+}
+
+async function openPage(wsUrl, url, { timeoutMs = 20000, collectMessages = true } = {}) {
+  const cdp = new CdpConnection(new WebSocket(wsUrl));
+  await cdp.open();
+  const { targetId } = await cdp.send('Target.createTarget', { url: 'about:blank' });
+  const { sessionId } = await cdp.send('Target.attachToTarget', { targetId, flatten: true });
+
+  const messages = [];
+  const push = (level, text) => {
+    const value = String(text ?? '').replace(/\s+/g, ' ').trim();
+    if (value) messages.push({ level, text: value });
+  };
+  if (collectMessages) {
+    cdp.on((message) => {
+      if (message.sessionId && message.sessionId !== sessionId) return;
+      if (message.method === 'Runtime.consoleAPICalled') {
+        const level = message.params.type === 'warning' ? 'warning' : message.params.type;
+        push(level, (message.params.args ?? []).map(describeArg).join(' '));
+      } else if (message.method === 'Runtime.exceptionThrown') {
+        const details = message.params.exceptionDetails ?? {};
+        push('error', details.exception?.description || details.text || 'excepción');
+      } else if (message.method === 'Log.entryAdded') {
+        const entry = message.params.entry ?? {};
+        if (entry.level === 'error' || entry.level === 'warning') push(entry.level, entry.text);
+      }
+    });
+  }
+
+  await cdp.send('Page.enable', {}, sessionId);
+  await cdp.send('Runtime.enable', {}, sessionId);
+  await cdp.send('Log.enable', {}, sessionId).catch(() => {});
+
+  const loaded = new Promise((resolve) => {
+    const off = cdp.on((message) => {
+      if (message.method === 'Page.loadEventFired' && message.sessionId === sessionId) {
+        off();
+        resolve();
+      }
+    });
+  });
+  await cdp.send('Page.navigate', { url }, sessionId);
+  await Promise.race([loaded, delay(timeoutMs)]);
+
+  return { cdp, sessionId, targetId, messages };
+}
+
+/** Cierra el navegador y sus hijos. En Windows `child.kill` no mata el arbol. */
+function killBrowser(child) {
+  if (!child || child.killed) return;
+  if (process.platform === 'win32') {
+    try {
+      spawn('taskkill', ['/pid', String(child.pid), '/T', '/F'], { stdio: 'ignore', windowsHide: true });
+    } catch {
+      /* nada */
+    }
+  } else {
+    try {
+      child.kill('SIGKILL');
+    } catch {
+      /* nada */
+    }
+  }
+}
+
+async function withBrowser(url, options, run) {
+  const bin = findBrowserPath();
+  if (!bin) {
+    throw new Error('no encontré Chrome/Edge/Chromium; definí TAMNORA_BROWSER con la ruta al ejecutable');
+  }
+  const { child, wsUrl, profile } = await launchBrowser(bin);
+  try {
+    const page = await openPage(wsUrl, url, options);
+    try {
+      return await run(page);
+    } finally {
+      page.cdp.close();
+    }
+  } finally {
+    killBrowser(child);
+    // Chrome tarda en soltar el profile: darle un respiro y no fallar si queda.
+    await delay(200);
+    try {
+      rmSync(profile, { recursive: true, force: true });
+    } catch {
+      /* profile bloqueado: queda en temp, no es fatal */
+    }
+  }
+}
+
+/**
+ * Captura PNG de una URL. Devuelve `{ buffer, width, height, consoleErrors }`.
+ */
+export async function captureScreenshot(url, { fullPage = false, width = 1280, height = 720, waitMs = 800, timeoutMs } = {}) {
+  return withBrowser(url, { timeoutMs, collectMessages: true }, async ({ cdp, sessionId, messages }) => {
+    await cdp
+      .send('Emulation.setDeviceMetricsOverride', { width, height, deviceScaleFactor: 1, mobile: false }, sessionId)
+      .catch(() => {});
+    if (waitMs > 0) await delay(waitMs);
+    const shot = await cdp.send(
+      'Page.captureScreenshot',
+      { format: 'png', captureBeyondViewport: Boolean(fullPage) },
+      sessionId
+    );
+    const errors = messages.filter((m) => m.level === 'error');
+    return { buffer: Buffer.from(shot.data, 'base64'), width, height, consoleErrors: errors };
+  });
+}
+
+/**
+ * Abre una URL y devuelve los mensajes de consola. `{ messages, errors }`.
+ */
+export async function readConsole(url, { waitMs = 1500, timeoutMs } = {}) {
+  return withBrowser(url, { timeoutMs, collectMessages: true }, async ({ messages }) => {
+    if (waitMs > 0) await delay(waitMs);
+    const errors = messages.filter((m) => m.level === 'error');
+    return { messages, errors };
+  });
+}

package/harness/packages/core/src/config/home.js

@@ -39,6 +39,11 @@ export function homePath(...parts) {
   return path.join(homeDir(), ...parts);
 }
 
+/** Carpeta de capturas del navegador (la sirve la consola y la usa Telegram). */
+export function screenshotsDir() {
+  return homePath('screenshots');
+}
+
 export function appConfigPath() {
   return homePath('app.json');
 }

package/harness/packages/core/src/index.js

@@ -10,7 +10,7 @@ export {
 } from './redact.js';
 export { resolveApiKey, resolveEnvMap } from './config/secrets.js';
 export { ensureUtf8Console } from './console.js';
-export { MAX_TOOL_ROUNDS, runAgent, parseToolArguments } from './agent/runAgent.js';
+export { MAX_TOOL_ROUNDS, runAgent, parseToolArguments, normalizeToolOutput } from './agent/runAgent.js';
 export { estimateTokens, trimContext } from './agent/context.js';
 export { diffLines, diffRows } from './tools/diff.js';
 export { isGitRepo, gitStatus, gitDiff } from './git/index.js';
@@ -52,6 +52,7 @@ export {
   setHome,
   homeDir,
   homePath,
+  screenshotsDir,
   appConfigPath,
   databaseFile,
   runtimePath,
@@ -110,4 +111,10 @@ export { pidAlive, killPidTree } from './pid.js';
 export { openBrowser, openerFor } from './open.js';
 export { detectProcs, packageManager, DEFAULT_PROCESS_ALLOW, staticServerChip } from './procs/detect.js';
 export { killPort } from './procs/kill.js';
-export { readPackageVersion } from './version.js';
+export {
+  ROOT_PACKAGE_NAME,
+  readPackageVersion,
+  packageRoot,
+  compareVersions,
+  fetchLatestVersion,
+} from './version.js';

package/harness/packages/core/src/tools/executors.js

@@ -4,6 +4,8 @@ import path from 'node:path';
 import { resolveInRoot, toRel } from './paths.js';
 import { globToRegExp, walkFiles } from './glob.js';
 import { diffLines } from './diff.js';
+import { captureScreenshot, readConsole } from '../browser/index.js';
+import { screenshotsDir } from '../config/home.js';
 
 const MAX_READ_LINES = 2000;
 const MAX_LIST = 500;
@@ -419,6 +421,97 @@ export function speakTool(_root, { texto, voice, rate } = {}) {
   return `Audio pedido${opciones ? ` (${opciones})` : ''}: "${recortado}". El cliente lo reproduce o lo envía como nota de voz.`;
 }
 
+function normalizeHttpUrl(value) {
+  const raw = String(value ?? '').trim();
+  if (!raw) return { error: 'falta "url".' };
+  let parsed;
+  try {
+    parsed = new URL(raw);
+  } catch {
+    return { error: `URL inválida: "${raw}".` };
+  }
+  if (parsed.protocol !== 'http:' && parsed.protocol !== 'https:') return { error: 'Solo se admite http(s).' };
+  return { url: parsed.toString() };
+}
+
+function clampInt(value, fallback, min, max) {
+  const n = Math.round(Number(value));
+  if (!Number.isFinite(n)) return fallback;
+  return Math.min(Math.max(n, min), max);
+}
+
+/**
+ * Pide abrir una URL en el panel de vista previa de la consola. La entrega es
+ * del cliente (igual que `speak`): aca solo se valida la URL.
+ */
+export function previewUrlTool(_root, { url } = {}) {
+  const parsed = normalizeHttpUrl(url);
+  if (parsed.error) return `Error: ${parsed.error}`;
+  return `Vista previa pedida: ${parsed.url}. La consola la abre en el panel de vista previa.`;
+}
+
+/**
+ * Captura de pantalla con el navegador headless del sistema. La guarda en la
+ * casa (`screenshots/`) y devuelve un `meta.screenshot` para que la consola la
+ * muestre y Telegram la mande como foto.
+ */
+export async function screenshotTool(_root, { url, fullPage, width, height } = {}) {
+  const parsed = normalizeHttpUrl(url);
+  if (parsed.error) return `Error: ${parsed.error}`;
+  const size = {
+    width: clampInt(width, 1280, 320, 3840),
+    height: clampInt(height, 720, 240, 2160),
+  };
+
+  let shot;
+  try {
+    shot = await captureScreenshot(parsed.url, { fullPage: Boolean(fullPage), ...size });
+  } catch (error) {
+    return `Error capturando ${parsed.url}: ${error?.message ?? error}`;
+  }
+
+  let name;
+  try {
+    const dir = screenshotsDir();
+    await mkdir(dir, { recursive: true });
+    name = `${Date.now()}-${Math.random().toString(36).slice(2, 8)}.png`;
+    await writeFile(path.join(dir, name), shot.buffer);
+  } catch (error) {
+    return `Error guardando la captura: ${error?.message ?? error}`;
+  }
+
+  const errors = shot.consoleErrors ?? [];
+  const head = `Captura de ${parsed.url} → capturas/${name} (${size.width}x${size.height}, ${Math.round(shot.buffer.length / 1024)} KB)`;
+  const detail = errors.length
+    ? `Errores de consola al cargar (${errors.length}):\n${errors.slice(0, 10).map((e) => `- ${e.text}`).join('\n')}`
+    : 'Sin errores de consola al cargar.';
+  return {
+    content: `${head}\n${detail}`,
+    meta: { screenshot: { name, url: parsed.url, width: size.width, height: size.height } },
+  };
+}
+
+/** Errores y mensajes de consola de una pagina (ejecutando su JS). */
+export async function consoleTool(_root, { url, waitMs } = {}) {
+  const parsed = normalizeHttpUrl(url);
+  if (parsed.error) return `Error: ${parsed.error}`;
+
+  let result;
+  try {
+    result = await readConsole(parsed.url, { waitMs: clampInt(waitMs, 1500, 0, 15000) });
+  } catch (error) {
+    return `Error leyendo la consola de ${parsed.url}: ${error?.message ?? error}`;
+  }
+
+  const { errors, messages } = result;
+  const head = errors.length
+    ? `Consola de ${parsed.url}: ${errors.length} error(es), ${messages.length} mensaje(s).`
+    : `Consola de ${parsed.url}: sin errores (${messages.length} mensaje(s)).`;
+  if (!messages.length) return head;
+  const shown = messages.slice(0, 100).map((m) => `[${m.level}] ${m.text}`);
+  return [head, ...shown].join('\n');
+}
+
 export const EXECUTORS = {
   read: readTool,
   write: writeTool,
@@ -433,4 +526,7 @@ export const EXECUTORS = {
   git_log: gitLogTool,
   git_commit: gitCommitTool,
   speak: speakTool,
+  preview_url: previewUrlTool,
+  screenshot: screenshotTool,
+  console_errors: consoleTool,
 };

package/harness/packages/core/src/tools/labels.js

@@ -50,6 +50,10 @@ export function summarizeToolCall(name, args = {}) {
     }
     case 'fetch_url':
       return shorten(a.url, 90);
+    case 'screenshot':
+    case 'console_errors':
+    case 'preview_url':
+      return shorten(a.url, 90);
     case 'speak':
       return shorten(a.texto, 90);
     case 'git_diff':

package/harness/packages/core/src/tools/permissions.js

@@ -14,6 +14,9 @@ export const DEFAULT_PERMISSIONS = {
   git_log: 'allow',
   fetch_url: 'allow',
   speak: 'allow',
+  screenshot: 'allow',
+  console_errors: 'allow',
+  preview_url: 'allow',
   write: 'ask',
   edit: 'ask',
   bash: 'ask',
@@ -43,6 +46,7 @@ function subjectFor(name, args) {
   if (name === 'bash') return args?.command ?? '';
   if (name === 'git_commit') return args?.message ?? '';
   if (name === 'fetch_url') return args?.url ?? '';
+  if (name === 'screenshot' || name === 'console_errors' || name === 'preview_url') return args?.url ?? '';
   return args?.path ?? '';
 }
 

package/harness/packages/core/src/tools/schema.js

@@ -150,6 +150,53 @@ export const TOOL_DEFINITIONS = [
       },
     },
   },
+  {
+    type: 'function',
+    function: {
+      name: 'screenshot',
+      description:
+        'Take a screenshot of a web page with a headless browser (renders JavaScript). Use it to show the user a preview of a page (e.g. a local dev server like http://127.0.0.1:5173) or to inspect it visually. Returns the console errors seen while loading.',
+      parameters: {
+        type: 'object',
+        properties: {
+          url: { type: 'string', description: 'Absolute http(s) URL to capture' },
+          fullPage: { type: 'boolean', description: 'Capture the full scrollable page (default: viewport)' },
+          width: { type: 'integer', description: 'Viewport width in px (default 1280)' },
+          height: { type: 'integer', description: 'Viewport height in px (default 720)' },
+        },
+        required: ['url'],
+      },
+    },
+  },
+  {
+    type: 'function',
+    function: {
+      name: 'console_errors',
+      description:
+        'Open a web page with a headless browser (executes JavaScript) and return its console messages and errors. Use it to check a page for runtime errors.',
+      parameters: {
+        type: 'object',
+        properties: {
+          url: { type: 'string', description: 'Absolute http(s) URL' },
+          waitMs: { type: 'integer', description: 'Extra ms to wait after load for async errors (default 1500)' },
+        },
+        required: ['url'],
+      },
+    },
+  },
+  {
+    type: 'function',
+    function: {
+      name: 'preview_url',
+      description:
+        'Open a URL in the console preview panel for the user. Use it to show a page or dev server without leaving the chat.',
+      parameters: {
+        type: 'object',
+        properties: { url: { type: 'string', description: 'Absolute http(s) URL to preview' } },
+        required: ['url'],
+      },
+    },
+  },
   {
     type: 'function',
     function: {

package/harness/packages/core/src/version.js

@@ -2,19 +2,20 @@ import { readFileSync } from 'node:fs';
 import { fileURLToPath } from 'node:url';
 import path from 'node:path';
 
-const ROOT_PACKAGE_NAME = '@danieltmn/tamnora';
+export const ROOT_PACKAGE_NAME = '@danieltmn/tamnora';
+
+const DEFAULT_REGISTRY = 'https://registry.npmjs.org';
 
 /**
- * Resolve the published package version by walking up from `startUrl` until a
- * package.json named `@danieltmn/tamnora` is found. Robust to file depth so
- * callers don't have to count `../` levels.
+ * Resolve the harness package dir (where its package.json lives) by walking up
+ * from `startUrl`. Robust to file depth so callers don't count `../`.
  */
-export function readPackageVersion(startUrl = import.meta.url) {
+export function packageRoot(startUrl = import.meta.url) {
   let dir = path.dirname(fileURLToPath(startUrl));
   for (let i = 0; i < 10; i++) {
     try {
       const pkg = JSON.parse(readFileSync(path.join(dir, 'package.json'), 'utf8'));
-      if (pkg.name === ROOT_PACKAGE_NAME && pkg.version) return pkg.version;
+      if (pkg.name === ROOT_PACKAGE_NAME) return dir;
     } catch {
       /* no hay package.json acá: seguir subiendo */
     }
@@ -22,5 +23,78 @@ export function readPackageVersion(startUrl = import.meta.url) {
     if (parent === dir) break;
     dir = parent;
   }
-  return '0.0.0';
+  return null;
+}
+
+/** Version publicada del harness (`0.0.0` si no se puede leer). */
+export function readPackageVersion(startUrl = import.meta.url) {
+  const root = packageRoot(startUrl);
+  if (!root) return '0.0.0';
+  try {
+    const pkg = JSON.parse(readFileSync(path.join(root, 'package.json'), 'utf8'));
+    return pkg.version || '0.0.0';
+  } catch {
+    return '0.0.0';
+  }
+}
+
+function parseVersion(value) {
+  const match = /^v?(\d+)\.(\d+)\.(\d+)(?:-([0-9A-Za-z.-]+))?(?:\+[0-9A-Za-z.-]+)?$/.exec(
+    String(value ?? '').trim()
+  );
+  if (!match) return null;
+  return { nums: [Number(match[1]), Number(match[2]), Number(match[3])], pre: match[4] ?? '' };
+}
+
+/**
+ * Semver minimo: devuelve -1 / 0 / 1. Una version sin prerelease ordena por
+ * encima de una con prerelease (1.0.0 > 1.0.0-beta). Si alguna no se entiende,
+ * las trata como iguales (no queremos gritar "actualizacion disponible" por un
+ * formato raro).
+ */
+export function compareVersions(a, b) {
+  const va = parseVersion(a);
+  const vb = parseVersion(b);
+  if (!va || !vb) return 0;
+  for (let i = 0; i < 3; i++) {
+    if (va.nums[i] > vb.nums[i]) return 1;
+    if (va.nums[i] < vb.nums[i]) return -1;
+  }
+  if (va.pre === vb.pre) return 0;
+  if (!va.pre) return 1;
+  if (!vb.pre) return -1;
+  return va.pre < vb.pre ? -1 : 1;
+}
+
+/**
+ * Ultima version publicada en el registro npm, sin depender de `npm` en el
+ * PATH. `fetchImpl` es inyectable para tests.
+ */
+export async function fetchLatestVersion({
+  pkg = ROOT_PACKAGE_NAME,
+  tag = 'latest',
+  registry = DEFAULT_REGISTRY,
+  fetchImpl = globalThis.fetch,
+  timeoutMs = 8000,
+} = {}) {
+  if (typeof fetchImpl !== 'function') throw new Error('fetch no disponible');
+  const controller = new AbortController();
+  const timer = setTimeout(() => controller.abort(), timeoutMs);
+  timer.unref?.();
+  try {
+    const res = await fetchImpl(`${registry}/${pkg}`, {
+      headers: { accept: 'application/json' },
+      signal: controller.signal,
+    });
+    if (!res.ok) throw new Error(`HTTP ${res.status}`);
+    const data = await res.json();
+    const distTags = data?.['dist-tags'] ?? {};
+    const version = distTags[tag] || distTags.latest;
+    if (!version || !/^\d+\.\d+\.\d+/.test(String(version))) {
+      throw new Error('respuesta sin version valida');
+    }
+    return String(version);
+  } finally {
+    clearTimeout(timer);
+  }
 }

package/harness/packages/core/test/agent.test.js

@@ -3,7 +3,7 @@ import assert from 'node:assert/strict';
 import { mkdtemp, readFile } from 'node:fs/promises';
 import { tmpdir } from 'node:os';
 import path from 'node:path';
-import { runAgent, parseToolArguments } from '../src/agent/runAgent.js';
+import { runAgent, parseToolArguments, normalizeToolOutput } from '../src/agent/runAgent.js';
 import { createTools } from '../src/tools/index.js';
 
 test('agent executes tool calls then returns the final answer', async () => {
@@ -328,3 +328,32 @@ test('agent respeta el presupuesto de tokens y cierra con resumen', async () =>
   assert.equal(result.stopReason, 'budget');
   assert.equal(result.content, 'cierre');
 });
+
+test('normalizeToolOutput acepta string y { content, meta }', () => {
+  assert.deepEqual(normalizeToolOutput('hola'), { content: 'hola' });
+  assert.deepEqual(normalizeToolOutput({ content: 'ok', meta: { a: 1 } }), { content: 'ok', meta: { a: 1 } });
+  assert.deepEqual(normalizeToolOutput({ x: 1 }), { content: '{"x":1}' });
+  assert.deepEqual(normalizeToolOutput(undefined), { content: '' });
+});
+
+test('tool_result propaga el meta del executor sin ensuciar el contenido', async () => {
+  const events = [];
+  const provider = {
+    async streamChat(_config, { messages }) {
+      if (messages.some((m) => m.role === 'tool')) return { content: 'listo', reasoning: '', toolCalls: [] };
+      return { content: '', reasoning: '', toolCalls: [{ id: 'c1', function: { name: 'shot', arguments: '{}' } }] };
+    },
+  };
+  await runAgent({
+    provider,
+    config: {},
+    model: 'm',
+    messages: [{ role: 'user', content: 'x' }],
+    tools: [{ type: 'function', function: { name: 'shot', parameters: {} } }],
+    execute: async () => ({ content: 'captura', meta: { screenshot: { name: 'a.png' } } }),
+    onEvent: (e) => events.push(e),
+  });
+  const result = events.find((e) => e.type === 'tool_result');
+  assert.equal(result.result, 'captura');
+  assert.deepEqual(result.meta, { screenshot: { name: 'a.png' } });
+});