@danieltmn/tamnora 0.1.0

package/harness/packages/cli/src/tui/layout.js

@@ -0,0 +1,130 @@
+// Pure renderer for the full-screen console. Returns a frame string plus the
+// cursor position so the app can draw it in one write (no deps).
+
+import { color } from '../ui/color.js';
+import { moveTo } from './screen.js';
+
+const CURSOR = '▋';
+
+const THEME = {
+  head: color.bold,
+  user: color.green,
+  assistant: (t) => t,
+  dim: color.dim,
+  tool: color.cyan,
+  error: color.red,
+};
+
+const chars = (text) => Array.from(String(text ?? ''));
+
+export function wrapText(text, width) {
+  const lines = [];
+  for (const paragraph of String(text ?? '').split('\n')) {
+    if (!paragraph) {
+      lines.push('');
+      continue;
+    }
+    let current = [];
+    for (const word of paragraph.split(' ')) {
+      const wordChars = chars(word);
+      if (current.length === 0) current = wordChars;
+      else if (current.length + 1 + wordChars.length <= width) current = current.concat([' '], wordChars);
+      else {
+        lines.push(current.join(''));
+        current = wordChars;
+      }
+      while (current.length > width) {
+        lines.push(current.slice(0, width).join(''));
+        current = current.slice(width);
+      }
+    }
+    lines.push(current.join(''));
+  }
+  return lines;
+}
+
+function clip(text, width) {
+  const arr = chars(text);
+  return arr.length <= width ? text : arr.slice(0, width).join('');
+}
+
+function buildBody(state, width) {
+  const out = [];
+  for (const message of state.messages) {
+    if (message.role === 'user') {
+      for (const line of wrapText(message.text, width - 2)) out.push({ text: `  ${line}`, style: 'user' });
+      continue;
+    }
+    if (message.reasoning) {
+      for (const line of wrapText(message.reasoning, width - 4)) out.push({ text: `  · ${line}`, style: 'dim' });
+    }
+    if (message.text) {
+      for (const line of wrapText(message.text, width - 2)) out.push({ text: `  ${line}`, style: 'assistant' });
+    }
+    for (const tool of message.tools ?? []) {
+      out.push({ text: `  ⚙ ${tool.name} ${clip(tool.args ?? '', width - 8)}`, style: 'tool' });
+      if (tool.result !== undefined) {
+        for (const line of wrapText(tool.result, width - 6)) out.push({ text: `    → ${line}`, style: 'dim' });
+      }
+    }
+  }
+  return out;
+}
+
+function headerText(state, width) {
+  const left = `  ❯ tamnora`;
+  const middle = `  ${state.header.provider}/${state.header.model}`;
+  const tokens = state.tokens?.prompt ? `  ctx ${formatK(state.tokens.prompt)}` : '';
+  const right = state.streaming ? `generando…${tokens} ` : `${state.header.cwd ?? ''}${tokens} `;
+  const pad = Math.max(0, width - chars(left).length - chars(middle).length - chars(right).length);
+  return clip(`${left}${middle}${' '.repeat(pad)}${right}`, width);
+}
+
+function formatK(n) {
+  const value = Number(n) || 0;
+  return value >= 1000 ? `${(value / 1000).toFixed(1)}k` : String(value);
+}
+
+function statusText(state) {
+  if (state.pendingAsk) return '  y = permitir  ·  n = denegar';
+  if (state.streaming) return '  generando…  ·  ctrl+c cancelar';
+  return '  enter enviar  ·  ↑↓ historial  ·  ←→ editar  ·  pgup/pgdn scroll  ·  ctrl+l limpiar  ·  ctrl+c salir';
+}
+
+export function render(state, { cols = 80, rows = 24 } = {}) {
+  const width = Math.max(30, cols);
+  const viewportRows = Math.max(3, rows - 5);
+
+  const body = buildBody(state, width);
+  const scroll = Math.max(0, state.scroll ?? 0);
+  const end = Math.max(0, body.length - scroll);
+  const start = Math.max(0, end - viewportRows);
+  const viewport = body.slice(start, end);
+  while (viewport.length < viewportRows) viewport.push({ text: '', style: 'assistant' });
+
+  const lines = [{ text: headerText(state, width), style: 'head' }, { text: '', style: 'dim' }];
+  for (const entry of viewport) lines.push(entry);
+  lines.push({ text: '', style: 'dim' });
+
+  const inputIndex = lines.length;
+  const inputChars = chars(state.input ?? '');
+  const cursorPos = Math.max(0, Math.min(state.inputCursor ?? inputChars.length, inputChars.length));
+  const before = inputChars.slice(0, cursorPos).join('');
+  const after = inputChars.slice(cursorPos).join('');
+  if (state.pendingAsk) {
+    lines.push({ text: `  permitir ${state.pendingAsk.name} (${state.pendingAsk.detail})? [y/N] `, style: 'error' });
+  } else {
+    lines.push({ text: `  ❯ ${before}${CURSOR}${after}`, style: 'user' });
+  }
+  lines.push({ text: statusText(state), style: 'dim' });
+
+  const parts = [];
+  for (let i = 0; i < rows; i++) {
+    const entry = lines[i] ?? { text: '', style: 'dim' };
+    const style = THEME[entry.style] ?? THEME.assistant;
+    parts.push(moveTo(i + 1, 1), '\x1b[2K', style(clip(entry.text, width)));
+  }
+
+  const cursorCol = state.pendingAsk ? 2 : Math.min(width, chars(`  ❯ ${before}`).length + 1);
+  return { frame: parts.join(''), cursor: { row: Math.min(inputIndex + 1, rows), col: cursorCol } };
+}

package/harness/packages/cli/src/tui/screen.js

@@ -0,0 +1,13 @@
+// ANSI helpers for the full-screen console.
+
+export const enterAltScreen = '\x1b[?1049h';
+export const leaveAltScreen = '\x1b[?1049l';
+export const hideCursor = '\x1b[?25l';
+export const showCursor = '\x1b[?25h';
+export const enableBracketedPaste = '\x1b[?2004h';
+export const disableBracketedPaste = '\x1b[?2004l';
+export const reset = '\x1b[0m';
+
+export function moveTo(row, col = 1) {
+  return `\x1b[${row};${col}H`;
+}

package/harness/packages/cli/src/ui/color.js

@@ -0,0 +1,15 @@
+const enabled = Boolean(process.stdout.isTTY) && !process.env.NO_COLOR;
+
+const wrap = (code) => (text) => (enabled ? `\x1b[${code}m${text}\x1b[0m` : String(text));
+
+export const color = {
+  bold: wrap('1'),
+  dim: wrap('2'),
+  red: wrap('31'),
+  green: wrap('32'),
+  yellow: wrap('33'),
+  magenta: wrap('35'),
+  cyan: wrap('36'),
+};
+
+export const colorsEnabled = enabled;

package/harness/packages/cli/test/release.test.js

@@ -0,0 +1,34 @@
+import { test } from 'node:test';
+import assert from 'node:assert/strict';
+import { computeVersion, distTagFor, parseVersion, renderChangelog } from '../../../../scripts/release.mjs';
+
+test('computeVersion handles patch/minor/major and explicit versions', () => {
+  assert.equal(computeVersion('1.2.3', 'patch'), '1.2.4');
+  assert.equal(computeVersion('1.2.3', 'minor'), '1.3.0');
+  assert.equal(computeVersion('1.2.3', 'major'), '2.0.0');
+  assert.equal(computeVersion('1.2.3', '0.5.0'), '0.5.0');
+});
+
+test('computeVersion builds prereleases', () => {
+  assert.equal(computeVersion('1.2.3', 'prerelease', 'beta'), '1.2.4-beta.0');
+  assert.equal(computeVersion('1.2.4-beta.0', 'prerelease', 'beta'), '1.2.4-beta.1');
+});
+
+test('distTagFor picks beta for prereleases and latest otherwise', () => {
+  assert.equal(distTagFor('1.2.4-beta.0'), 'beta');
+  assert.equal(distTagFor('1.2.4'), 'latest');
+  assert.equal(distTagFor('1.2.4', 'next'), 'next');
+});
+
+test('parseVersion rejects invalid input', () => {
+  assert.equal(parseVersion('nope'), null);
+});
+
+test('renderChangelog promotes the Unreleased section', () => {
+  const cl = '# Changelog\n\n## [Unreleased]\n\n### Agregado\n\n- algo\n\n## [1.0.0] - 2026-01-01\n\n- viejo\n';
+  const out = renderChangelog(cl, '1.1.0', '- nota', '2026-02-02');
+  assert.match(out, /## \[1\.1\.0\] - 2026-02-02/);
+  assert.match(out, /- algo/);
+  assert.doesNotMatch(out, /## \[Unreleased\]/);
+  assert.match(out, /## \[1\.0\.0\]/);
+});

package/harness/packages/cli/test/tui.test.js

@@ -0,0 +1,99 @@
+import { test } from 'node:test';
+import assert from 'node:assert/strict';
+import { parseKeys } from '../src/tui/keys.js';
+import { wrapText, render } from '../src/tui/layout.js';
+
+test('parseKeys maps raw input to actions', () => {
+  assert.deepEqual(parseKeys('a'), [{ type: 'char', value: 'a' }]);
+  assert.deepEqual(parseKeys('\r'), [{ type: 'enter' }]);
+  assert.deepEqual(parseKeys('\x7f'), [{ type: 'backspace' }]);
+  assert.deepEqual(parseKeys('\x03'), [{ type: 'interrupt' }]);
+  assert.deepEqual(parseKeys('\x0c'), [{ type: 'clear' }]);
+  assert.deepEqual(parseKeys('\x1b[A'), [{ type: 'up' }]);
+  assert.deepEqual(parseKeys('\x1b[B'), [{ type: 'down' }]);
+  assert.deepEqual(parseKeys('ok!'), [
+    { type: 'char', value: 'o' },
+    { type: 'char', value: 'k' },
+    { type: 'char', value: '!' },
+  ]);
+});
+
+test('parseKeys handles editing and navigation keys', () => {
+  assert.deepEqual(parseKeys('\x1b[C'), [{ type: 'right' }]);
+  assert.deepEqual(parseKeys('\x1b[D'), [{ type: 'left' }]);
+  assert.deepEqual(parseKeys('\x1b[H'), [{ type: 'home' }]);
+  assert.deepEqual(parseKeys('\x1b[F'), [{ type: 'end' }]);
+  assert.deepEqual(parseKeys('\x1b[3~'), [{ type: 'delete' }]);
+  assert.deepEqual(parseKeys('\x1b[5~'), [{ type: 'pageup' }]);
+  assert.deepEqual(parseKeys('\x1b[6~'), [{ type: 'pagedown' }]);
+  assert.deepEqual(parseKeys('\x01'), [{ type: 'home' }]);
+  assert.deepEqual(parseKeys('\x05'), [{ type: 'end' }]);
+});
+
+test('parseKeys reads bracketed paste as a single action', () => {
+  assert.deepEqual(parseKeys('\x1b[200~hola mundo\x1b[201~'), [{ type: 'paste', value: 'hola mundo' }]);
+  assert.deepEqual(parseKeys('\x1b[200~a\nb\x1b[201~'), [{ type: 'paste', value: 'a\nb' }]);
+});
+
+test('wrapText wraps paragraphs to the width', () => {
+  assert.deepEqual(wrapText('hola mundo', 20), ['hola mundo']);
+  assert.deepEqual(wrapText('uno dos tres cuatro', 7), ['uno dos', 'tres', 'cuatro']);
+  assert.deepEqual(wrapText('a\nb', 10), ['a', 'b']);
+});
+
+test('render composes header, body and input', () => {
+  const state = {
+    header: { provider: 'ollama', model: 'llama', cwd: '/tmp/x' },
+    messages: [
+      { role: 'user', text: 'hola', tools: [] },
+      { role: 'assistant', text: 'buenas', tools: [{ name: 'read', args: '{"path":"a"}', result: 'ok' }] },
+    ],
+    input: 'escribiendo',
+    streaming: false,
+    pendingAsk: null,
+  };
+  const { frame, cursor } = render(state, { cols: 80, rows: 24 });
+  assert.match(frame, /tamnora/);
+  assert.match(frame, /ollama\/llama/);
+  assert.match(frame, /hola/);
+  assert.match(frame, /buenas/);
+  assert.match(frame, /read/);
+  assert.match(frame, /escribiendo/);
+  assert.ok(cursor.col > 1);
+});
+
+test('render places the cursor at inputCursor', () => {
+  const state = {
+    header: { provider: 'p', model: 'm', cwd: '/x' },
+    messages: [],
+    input: 'abc',
+    inputCursor: 1,
+    streaming: false,
+    pendingAsk: null,
+  };
+  const { frame, cursor } = render(state, { cols: 80, rows: 20 });
+  assert.match(frame, /a▋bc/);
+  assert.equal(cursor.col, 6);
+});
+
+test('render scrolls the viewport', () => {
+  const messages = Array.from({ length: 40 }, (_, i) => ({ role: 'assistant', text: `linea ${i}`, tools: [] }));
+  const base = { header: { provider: 'p', model: 'm', cwd: '/x' }, input: '', streaming: false, pendingAsk: null };
+  const bottom = render({ ...base, messages, scroll: 0 }, { cols: 40, rows: 12 }).frame;
+  const up = render({ ...base, messages, scroll: 20 }, { cols: 40, rows: 12 }).frame;
+  assert.match(bottom, /linea 39/);
+  assert.doesNotMatch(up, /linea 39/);
+});
+
+test('render shows the permission prompt while asking', () => {
+  const state = {
+    header: { provider: 'p', model: 'm', cwd: '/x' },
+    messages: [],
+    input: '',
+    streaming: false,
+    pendingAsk: { name: 'write', detail: 'out.txt' },
+  };
+  const { frame } = render(state, { cols: 80, rows: 20 });
+  assert.match(frame, /permitir write/);
+  assert.match(frame, /\[y\/N\]/);
+});

package/harness/packages/cli/test/tunnel.test.js

@@ -0,0 +1,20 @@
+import { test } from 'node:test';
+import assert from 'node:assert/strict';
+import { parseTunnelmoleUrls } from '../src/lib/tunnel.js';
+import { qrTerminal } from '../src/lib/qr.js';
+
+test('parseTunnelmoleUrls extracts the https URL', () => {
+  const out = parseTunnelmoleUrls('Listening at https://abc-123.tunnelmole.net (forwarding to 4517)');
+  assert.equal(out.https, 'https://abc-123.tunnelmole.net');
+  assert.equal(out.http, '');
+});
+
+test('parseTunnelmoleUrls ignores unrelated output', () => {
+  assert.deepEqual(parseTunnelmoleUrls('starting tunnelmole...'), { https: '', http: '' });
+});
+
+test('qrTerminal renders a block matrix for a URL', () => {
+  const art = qrTerminal('https://abc-123.tunnelmole.net', 1);
+  assert.ok(art.length > 0);
+  assert.match(art, /[\u2580\u2584\u2588]/);
+});

package/harness/packages/core/package.json

@@ -0,0 +1,14 @@
+{
+  "name": "@tamnora/core",
+  "version": "0.0.0",
+  "private": true,
+  "type": "module",
+  "description": "Tamnora harness core: agent engine, providers, tools, MCP, sessions and storage (Node-only).",
+  "main": "src/index.js",
+  "exports": {
+    ".": "./src/index.js"
+  },
+  "scripts": {
+    "test": "node --test test"
+  }
+}

package/harness/packages/core/src/agent/context.js

@@ -0,0 +1,66 @@
+/**
+ * Estimacion y recorte de contexto. Sin tokenizador real: aproximacion por
+ * caracteres (4 por token), suficiente para mantener las sesiones dentro del
+ * limite del modelo.
+ */
+
+const CHARS_PER_TOKEN = 4;
+const TOOL_KEEP_CHARS = 800;
+
+function contentLength(content) {
+  if (typeof content === 'string') return content.length;
+  if (Array.isArray(content)) {
+    return content.reduce((sum, part) => sum + (typeof part?.text === 'string' ? part.text.length : 200), 0);
+  }
+  return 0;
+}
+
+export function estimateTokens(messages) {
+  let chars = 0;
+  for (const message of messages) {
+    chars += contentLength(message.content);
+    if (message.tool_calls) chars += JSON.stringify(message.tool_calls).length;
+    if (message.name) chars += message.name.length;
+  }
+  return Math.ceil(chars / CHARS_PER_TOKEN);
+}
+
+/**
+ * Devuelve una copia recortada de `messages` que entra en `maxTokens`:
+ *  1. acorta el contenido de tool-results viejos;
+ *  2. si hace falta, descarta los grupos mas antiguos (assistant + sus tools),
+ *     sin tocar el primer mensaje (system) ni los ultimos `keepLast`.
+ *
+ * @returns {{messages: object[], trimmed: number, dropped: number}}
+ */
+export function trimContext(messages, { maxTokens, keepLast = 8 } = {}) {
+  if (!(maxTokens > 0) || !Array.isArray(messages) || messages.length === 0) {
+    return { messages, trimmed: 0, dropped: 0 };
+  }
+  if (estimateTokens(messages) <= maxTokens) return { messages, trimmed: 0, dropped: 0 };
+
+  const out = messages.map((message) => ({ ...message }));
+  let trimmed = 0;
+  const cutoff = Math.max(1, out.length - keepLast);
+  for (let i = 1; i < cutoff; i++) {
+    const message = out[i];
+    if (message.role === 'tool' && typeof message.content === 'string' && message.content.length > TOOL_KEEP_CHARS) {
+      out[i] = { ...message, content: `${message.content.slice(0, TOOL_KEEP_CHARS)}\n…[recortado por contexto]` };
+      trimmed += 1;
+    }
+  }
+  if (estimateTokens(out) <= maxTokens) return { messages: out, trimmed, dropped: 0 };
+
+  let dropped = 0;
+  while (estimateTokens(out) > maxTokens && out.length > keepLast + 1) {
+    const first = out[1];
+    let end = 2;
+    if (first.role === 'assistant' && Array.isArray(first.tool_calls)) {
+      while (end < out.length && out[end].role === 'tool') end += 1;
+    }
+    if (out.length - (end - 1) < keepLast) break;
+    out.splice(1, end - 1);
+    dropped += end - 1;
+  }
+  return { messages: out, trimmed, dropped };
+}

package/harness/packages/core/src/agent/modes.js

@@ -0,0 +1,26 @@
+// Agent modes: preset tool sets + system-prompt guidance. `agent` can change
+// the workspace; `plan` is read-only and answers with a plan.
+
+export const MODES = {
+  agent: {
+    id: 'agent',
+    label: 'Agent',
+    description: 'Lee, escribe y ejecuta comandos en el workspace.',
+    tools: null,
+    systemPrompt: '',
+  },
+  plan: {
+    id: 'plan',
+    label: 'Plan',
+    description: 'Solo lectura: investiga y propone un plan, sin modificar nada.',
+    tools: ['read', 'list', 'glob', 'grep', 'git_status', 'git_diff', 'git_log'],
+    systemPrompt:
+      'Estás en modo PLAN: no modifiques archivos ni ejecutes comandos. Investigá el proyecto con las herramientas de solo lectura y respondé con un plan concreto y accionable.',
+  },
+};
+
+export const MODE_IDS = Object.keys(MODES);
+
+export function resolveMode(id) {
+  return MODES[id] ?? MODES.agent;
+}

package/harness/packages/core/src/agent/runAgent.js

@@ -0,0 +1,257 @@
+import { withRetry, isRetryableError } from '../providers/resilience.js';
+import { trimContext, estimateTokens } from './context.js';
+
+export const MAX_TOOL_ROUNDS = 8;
+
+/**
+ * Provider-agnostic agent loop. Runs the model, executes any tool calls it
+ * requests, feeds the results back, and repeats until the model answers
+ * without tools (or `maxRounds` is reached).
+ *
+ * Free of React and browser APIs so it can run headless in Node.
+ *
+ * @param {object} opts
+ * @param {object} opts.provider - provider adapter (from core/providers)
+ * @param {object} opts.config - resolved provider config
+ * @param {string} opts.model - model id
+ * @param {object[]} opts.messages - full history (including the system message)
+ * @param {object[]} [opts.tools] - OpenAI-schema tool definitions
+ * @param {Function} [opts.execute] - (name, args, context) => Promise<string>
+ * @param {object} [opts.toolContext] - passed through to `execute`
+ * @param {AbortSignal} [opts.signal]
+ * @param {Function} [opts.onEvent] - streaming/lifecycle callback
+ * @param {number} [opts.maxRounds]
+ * @param {number} [opts.stallWarnMs] - warn once if the model emits nothing for
+ *   this long (0 disables; default 90000)
+ * @param {number} [opts.retries] - reintentos por ronda ante error transitorio
+ *   (default 2; solo si la ronda no emitio contenido todavia)
+ * @param {number} [opts.retryDelayMs] - base del backoff (default 500)
+ * @returns {Promise<{content, reasoning, toolCalls, messages, rounds, stopReason, usage}>}
+ */
+export async function runAgent({
+  provider,
+  config,
+  model,
+  messages,
+  tools = [],
+  execute = defaultExecute,
+  toolContext = {},
+  signal,
+  onEvent,
+  maxRounds = MAX_TOOL_ROUNDS,
+  stallWarnMs = 90000,
+  retries = 2,
+  retryDelayMs = 500,
+  contextTokens = 0,
+}) {
+  const working = [...messages];
+  let usageTotal = null;
+
+  for (let round = 1; round <= maxRounds; round++) {
+    if (signal?.aborted) {
+      return {
+        content: '',
+        reasoning: '',
+        toolCalls: [],
+        messages: working,
+        rounds: Math.max(0, round - 1),
+        stopReason: 'aborted',
+        usage: usageTotal,
+      };
+    }
+
+    const stall = createStallGuard(onEvent, stallWarnMs);
+    let emitted = false;
+
+    // Presupuesto de contexto: el recorte va sobre una copia; `working` sigue
+    // completo para persistir el historial con indices estables.
+    let contextMessages = working;
+    if (contextTokens > 0) {
+      const trimmedResult = trimContext(working, { maxTokens: contextTokens });
+      contextMessages = trimmedResult.messages;
+      if (trimmedResult.trimmed || trimmedResult.dropped) {
+        onEvent?.({
+          type: 'trim',
+          trimmed: trimmedResult.trimmed,
+          dropped: trimmedResult.dropped,
+          tokens: estimateTokens(contextMessages),
+        });
+      }
+    }
+
+    let result;
+    try {
+      result = await withRetry(
+        (attempt) => {
+          if (attempt > 0) emitted = false;
+          return provider.streamChat(config, {
+            model,
+            messages: contextMessages,
+            tools,
+            signal,
+            onEvent: (event) => {
+              if (event && (event.type === 'reasoning' || event.type === 'tool_calls')) emitted = true;
+              if (event?.type === 'text' && event.delta) emitted = true;
+              stall.onEvent(event);
+            },
+          });
+        },
+        {
+          retries,
+          baseDelayMs: retryDelayMs,
+          signal,
+          shouldRetry: (err) => !emitted && isRetryableError(err),
+          onRetry: (attempt, delay, err) =>
+            onEvent?.({ type: 'retry', attempt, delayMs: Math.round(delay), message: err?.message ?? String(err) }),
+        }
+      );
+    } finally {
+      stall.dispose();
+    }
+
+    const roundUsage = result.usage ?? null;
+    if (roundUsage) {
+      usageTotal = {
+        prompt_tokens: (usageTotal?.prompt_tokens ?? 0) + roundUsage.prompt_tokens,
+        completion_tokens: (usageTotal?.completion_tokens ?? 0) + roundUsage.completion_tokens,
+        total_tokens: (usageTotal?.total_tokens ?? 0) + roundUsage.total_tokens,
+        // last round = current context footprint (for context meters)
+        last_prompt_tokens: roundUsage.prompt_tokens,
+        last_completion_tokens: roundUsage.completion_tokens,
+      };
+    }
+    const tokens = roundUsage
+      ? { tokens_in: roundUsage.prompt_tokens, tokens_out: roundUsage.completion_tokens }
+      : {};
+
+    const calls = result.toolCalls ?? [];
+    if (calls.length === 0) {
+      working.push({ role: 'assistant', content: result.content ?? '', ...tokens });
+      return {
+        content: result.content,
+        reasoning: result.reasoning ?? '',
+        toolCalls: [],
+        messages: working,
+        rounds: round,
+        stopReason: 'end_turn',
+        usage: usageTotal,
+      };
+    }
+
+    working.push({ role: 'assistant', content: result.content || null, tool_calls: calls, ...tokens });
+    onEvent?.({ type: 'tool_round', round, toolCalls: calls, content: result.content });
+
+    for (let index = 0; index < calls.length; index++) {
+      const call = calls[index];
+      const name = call.function?.name ?? call.name;
+
+      // Cancelacion entre tools: rellena los tool_calls pendientes para que el
+      // historial quede consistente y corta.
+      if (signal?.aborted) {
+        for (let rest = index; rest < calls.length; rest++) {
+          const pending = calls[rest];
+          working.push({
+            role: 'tool',
+            tool_call_id: pending.id,
+            name: pending.function?.name ?? pending.name,
+            content: 'Cancelado por el usuario.',
+          });
+        }
+        return {
+          content: result.content ?? '',
+          reasoning: result.reasoning ?? '',
+          toolCalls: calls,
+          messages: working,
+          rounds: round,
+          stopReason: 'aborted',
+          usage: usageTotal,
+        };
+      }
+
+      const args = parseToolArguments(call);
+      onEvent?.({ type: 'tool_call', id: call.id, name, args });
+
+      let output;
+      try {
+        output = await execute(name, args, toolContext);
+      } catch (err) {
+        output = `Error ejecutando ${name}: ${err?.message ?? err}`;
+      }
+
+      onEvent?.({ type: 'tool_result', id: call.id, name, result: output });
+      working.push({
+        role: 'tool',
+        tool_call_id: call.id,
+        name,
+        content: typeof output === 'string' ? output : JSON.stringify(output),
+      });
+    }
+  }
+
+  return {
+    content: '',
+    reasoning: '',
+    toolCalls: [],
+    messages: working,
+    rounds: maxRounds,
+    stopReason: 'max_rounds',
+    usage: usageTotal,
+  };
+}
+
+/**
+ * Emit a single warning event when the model emits nothing for `stallWarnMs`
+ * during one stream (openbridge's stall watchdog port). Any provider event
+ * resets the window; the guard is scoped to a single streamChat call so long
+ * tool executions do not trigger false alarms.
+ */
+function createStallGuard(onEvent, stallWarnMs) {
+  if (!onEvent || !(stallWarnMs > 0)) return { onEvent: onEvent ?? (() => {}), dispose() {} };
+
+  let lastActivity = Date.now();
+  let warned = false;
+  const timer = setInterval(() => {
+    if (warned || Date.now() - lastActivity < stallWarnMs) return;
+    warned = true;
+    onEvent({ type: 'stall', seconds: Math.max(1, Math.round(stallWarnMs / 1000)) });
+  }, Math.min(stallWarnMs, 15000));
+  timer.unref?.();
+
+  return {
+    onEvent(event) {
+      lastActivity = Date.now();
+      onEvent(event);
+    },
+    dispose() {
+      clearInterval(timer);
+    },
+  };
+}
+
+async function defaultExecute(name) {
+  return `Error: la herramienta "${name}" no está disponible todavía (se agrega en la Fase 1).`;
+}
+
+/**
+ * Parse tool-call arguments, which may arrive as an object (Ollama) or a
+ * (possibly malformed) JSON string (OpenAI-compatible streams).
+ */
+export function parseToolArguments(call) {
+  const raw = call.function?.arguments ?? call.arguments;
+  if (raw && typeof raw === 'object') return raw;
+  if (typeof raw !== 'string') return {};
+
+  try {
+    return JSON.parse(raw);
+  } catch {
+    try {
+      const fixed = raw
+        // eslint-disable-next-line no-control-regex -- limpia caracteres de control del stream
+        .replace(/[\x00-\x1F\x7F]/g, '')
+        .replace(/,\s*([}\]])/g, '$1');
+      return JSON.parse(fixed);
+    } catch {
+      return {};
+    }
+  }
+}