loom-agent 1.2.36 → 1.3.2

package/src/core/session.js

@@ -23,6 +23,31 @@ const COMPACT_DEFAULT_THRESHOLD = 0.75;
 const COMPACT_KEEP_MESSAGES = 8;
 // Never compact conversations shorter than this.
 const COMPACT_MIN_MESSAGES = 6;
+// Drive-to-completion: how many continuation nudges one turn may spend when
+// the model stops with todos still unfinished (the "stops between tasks"
+// failure). Capped so a model that refuses to update its todos cannot spin.
+const MAX_DRIVE_NUDGES = 8;
+// Empty-reply nudges per turn (provider hiccup / reasoning-only stop).
+const MAX_EMPTY_NUDGES = 3;
+// finish_reason=length (output budget exhausted) auto-continues the turn
+// this many times before surfacing the truncation placeholder. This is the
+// #1 cause of "stops in the middle" with reasoning models: thinking eats
+// the whole max_tokens budget and the answer never streams.
+const MAX_TRUNCATION_CONTINUES = 5;
+// Transient provider failures (network blip, 5xx, stream reset) retry the
+// model call this many times before the turn surfaces an error.
+const PROVIDER_RETRIES = 2;
+
+// Does this reply sound like the model stopped in the MIDDLE of working?
+// Used when todos exist but weren't touched this turn: a short reply, or a
+// long one that ends on a continuation promise ("Now I will…", "Next, …"),
+// an open colon, or an ellipsis is unfinished. A full explanation is not.
+function looksUnfinished(text) {
+  const t = String(text || '').trim();
+  if (!t) return true;
+  if (t.length < 320) return true;
+  return /(?:\b(?:now|next|then|let me|i'?ll|going to|proceeding)\b[^.!?]*[.!]?\s*$)|[:…]$|\.\.\.\s*$/i.test(t);
+}
 
 /**
  * @typedef {Object} SpeedStats
@@ -244,6 +269,19 @@ ${this.mode === 'build' ? `- You have all tools available: read, write, edit, ba
 - If the user wants code changes, tell them to switch to Build mode (Tab or /build) and resend.` : ''}${this.config.outputStyle ? `\n\n## Output style\n${this.config.outputStyle}` : ''}`;
   }
 
+  // System-prompt suffix for the active PRIMARY agent (build/plan/chat): each
+  // primary can carry a role prompt (the Build orchestrator instructions, the
+  // Plan agent role, …) that appends after the base prompt. Child sessions and
+  // @agent turns already use _agentBlock, and primaries never set this.agent,
+  // so the two cannot stack. Resolved lazily so per-turn config changes apply.
+  _primaryBlock() {
+    if (this._isChild || this.agent) return '';
+    let agent = null;
+    try { agent = require('./agents').resolveAgent(this.mode); } catch { return ''; }
+    if (!agent || !agent.prompt) return '';
+    return '\n\n## Acting as the "' + agent.name + '" agent\n' + agent.prompt + '\n';
+  }
+
   // Create ./LOOM.md with a template when missing, so memory exists from the
   // first turn (Claude Code behavior). Disable with LOOM_MEM_AUTO=0 (tests).
   ensureMemoryFile() {
@@ -385,6 +423,19 @@ ${this.mode === 'build' ? `- You have all tools available: read, write, edit, ba
     this.messages.push(msg);
   }
 
+  // Remove a trailing empty assistant row (no text, no toolCalls). getResponse
+  // appends the assistant message even when the provider returned nothing —
+  // Anthropic rejects empty assistant content with a 400 on the next call, so
+  // continuation paths drop the row before adding their user nudge.
+  _dropTrailingEmptyAssistant() {
+    const last = this.messages[this.messages.length - 1];
+    if (last && last.role === 'assistant' && !(last.toolCalls || []).length && !String(last.content || '').trim()) {
+      this.messages.pop();
+      return true;
+    }
+    return false;
+  }
+
   // ─── Todo state ───
   // The todowrite tool persists into the session so the sidebar shows the
   // real, up-to-date task list instead of regex-scanning replies.
@@ -542,13 +593,20 @@ ${this.mode === 'build' ? `- You have all tools available: read, write, edit, ba
           interrupted: true,
         });
       }
-      return { type: 'text', content: streamed || '(interrupted)', interrupted: true };
+      return { type: 'text', content: streamed || '(interrupted before any text was streamed)', interrupted: true };
     };
 
     // No tool-use cap: the model decides when a turn is finished; the user can
     // always Esc-interrupt a runaway loop.
     let ranTools = false;
-    let nudged = false;
+    let emptyNudges = 0;
+    let toolCallsThisTurn = 0;
+    // Drive-to-completion state (see the no-toolCalls branch below).
+    let driveNudges = 0;
+    let truncContinues = 0;
+    let todowroteThisTurn = false;
+    // Transient provider-error retry state.
+    let providerRetries = 0;
     while (true) {
       if (this.interrupted) {
         return finishInterrupted();
@@ -575,6 +633,16 @@ ${this.mode === 'build' ? `- You have all tools available: read, write, edit, ba
             continue;
           }
         }
+        // Transient provider failure (network blip, 5xx, stream reset): retry
+        // the model call a couple of times instead of killing the turn
+        // mid-task. No tools ran for this iteration, so a retry is side-effect
+        // free.
+        if (providerRetries < PROVIDER_RETRIES) {
+          providerRetries++;
+          await new Promise((resolve) => setTimeout(resolve, 400 * providerRetries));
+          if (this.interrupted) return finishInterrupted();
+          continue;
+        }
         return { type: 'error', content: err.message };
       }
 
@@ -608,18 +676,95 @@ ${this.mode === 'build' ? `- You have all tools available: read, write, edit, ba
 
       if (!toolCalls.length) {
         const text = String(resp.content || '');
+
+        // Truncation auto-continue: finish_reason=length means the reply was
+        // CUT OFF by maxTokens — common with reasoning models (thinking eats
+        // the budget, the final answer never streams). Instead of dead-ending
+        // with a placeholder (the classic "stops in the middle"), continue the
+        // turn. Empty-content truncations also drop the empty assistant row
+        // from history — Anthropic 400s on empty assistant messages.
+        if (!this.interrupted && resp.finishReason === 'length' && truncContinues < MAX_TRUNCATION_CONTINUES) {
+          truncContinues++;
+          if (!text.trim()) this._dropTrailingEmptyAssistant();
+          const at = text.trim() ? text.replace(/\s+/g, ' ').trim().slice(-160) : null;
+          this.addMessage({
+            role: 'user',
+            content: '(your reply was cut off by the output-token limit' +
+              (at ? ' right after: \u2026' + at : ' before any text streamed') +
+              ' \u2014 continue exactly from there and finish the task. Keep the remaining reply compact so it fits.)',
+          });
+          continue;
+        }
+
         // Silent-stop guard: models occasionally end a turn with an EMPTY
-        // reply right after running tools (truncation / provider hiccup),
-        // which reads to the user like "the agent just stopped". One
-        // automatic continuation instead of dead-ending with '(no response)'.
-        if (!text.trim() && ranTools && !nudged && !this.interrupted) {
-          nudged = true;
-          this.addMessage({ role: 'user', content: '(your last reply was empty — continue where you left off and finish the task)' });
+        // reply — right after running tools (truncation / provider hiccup)
+        // or even on a plain first reply (reasoning-only stop, content
+        // filter). Automatic continuation instead of dead-ending with a
+        // placeholder — up to MAX_EMPTY_NUDGES per turn (hiccups repeat).
+        // finish_reason=length skips this: the truncation block above already
+        // spent its budget, and the placeholder below explains why.
+        if (!text.trim() && emptyNudges < MAX_EMPTY_NUDGES && !this.interrupted && resp.finishReason !== 'length') {
+          emptyNudges++;
+          this._dropTrailingEmptyAssistant();
+          this.addMessage({
+            role: 'user',
+            content: ranTools
+              ? '(the model returned an empty reply after ' + toolCallsThisTurn +
+                ' tool call(s) — continue where you left off and finish the task)'
+              : '(your last reply was empty — respond to the user with text, or use tools to do the work)',
+          });
           continue;
         }
-        return { type: 'text', content: text || '(no response)' };
+        // Drive-to-completion guard: the model stopped calling tools in the
+        // middle of tracked work. Two triggers:
+        //  1. todos written THIS turn are still pending/in_progress (the
+        //     strong signal — always nudge), or
+        //  2. tools ran this turn, todos exist, and the reply LOOKS
+        //     unfinished (short / ends on a promise) — catches premature
+        //     wrap-ups from models that never call todowrite.
+        // Up to MAX_DRIVE_NUDGES continuations. Plan/chat modes are excluded
+        // (plan drafts are meant to end with pending steps).
+        if (!this.interrupted && this.mode === 'build' && ranTools && driveNudges < MAX_DRIVE_NUDGES) {
+          const unfinished = (this.todos || []).filter((t) => t.status === 'pending' || t.status === 'in_progress');
+          const gated = todowroteThisTurn || looksUnfinished(text);
+          if (unfinished.length && gated) {
+            driveNudges++;
+            const list = unfinished.slice(0, 20).map((t) => '- [' + t.status + '] ' + t.content).join('\n');
+            // Quote what the model actually said — a canned nudge alone gives
+            // the user (and the model) no clue WHERE the turn went off the rails.
+            const lastReply = text.replace(/\s+/g, ' ').trim();
+            const snippet = lastReply
+              ? '\nYour last message was: "' + (lastReply.length > 240 ? lastReply.slice(0, 240) + '…' : lastReply) + '"'
+              : '';
+            this.addMessage({
+              role: 'user',
+              content: '(unfinished work detected: ' + unfinished.length + ' todo(s) still open:\n' + list + snippet +
+                '\nYour reply stopped the turn, but the work above is not done — continue exactly where you left off and finish it. ' +
+                'Only stop when every item is completed or cancelled via todowrite, or when something concrete blocks you — then name the blocker.)',
+            });
+            continue;
+          }
+        }
+        // Surface WHAT is still open when a build-mode turn engaged the drive
+        // guard (or wrote todos) and ends with work remaining, so the UI can
+        // show the real leftovers instead of a generic "stopped" placeholder.
+        const openTodos = (this.mode === 'build' && (todowroteThisTurn || driveNudges > 0))
+          ? (this.todos || []).filter((t) => t.status === 'pending' || t.status === 'in_progress')
+          : [];
+        // Safety net: after all continuation budgets are spent, a
+        // finish_reason=length reply still gets the explanatory placeholder
+        // instead of mystery silence.
+        const truncHint = resp.finishReason === 'length'
+          ? '(the reply hit the max-tokens limit mid-stream — the model ran out of output budget before writing any text. Raise maxTokens in config, or /think off to free the thinking budget)'
+          : '(the model ended the turn without any text)';
+        return {
+          type: 'text',
+          content: text || truncHint,
+          openTodos: openTodos.length ? openTodos : undefined,
+        };
       }
       ranTools = true;
+      toolCallsThisTurn += toolCalls.length;
 
       // Execute independent tool calls in parallel; results are appended in the
       // original call order so the conversation history stays deterministic.
@@ -659,7 +804,7 @@ ${this.mode === 'build' ? `- You have all tools available: read, write, edit, ba
         // are checked separately where they apply.
         const permKey = { read:'read', edit:'edit', write:'edit', glob:'glob', grep:'grep', bash:'bash',
                           task:'task', skill:'skill', lsp:'lsp', question:'question', ask:'question', webfetch:'webfetch',
-                          websearch:'websearch' }[tc.name];
+                          websearch:'websearch', browser:'browser' }[tc.name];
         const isMcpAdd = tc.name === 'mcp' && tc.input && tc.input.action === 'add';
         if (permKey || isMcpAdd) {
           const arg = this.permissions.permissionArg(tc.name, tc.input || {});
@@ -734,6 +879,7 @@ ${this.mode === 'build' ? `- You have all tools available: read, write, edit, ba
         this.addMessage({ role: 'tool', toolCallId: tc.id, content: text });
         // Persist real todo state when the model uses the todowrite tool.
         if (tc.name === 'todowrite' && !outcome.error) {
+          todowroteThisTurn = true;
           this.setTodos(tc.input && tc.input.todos);
           // Notify observers (sidebar, etc.) over the tiny event bus — the TUI
           // subscribes once and the panel updates without a re-render cycle.
@@ -805,7 +951,7 @@ ${this.mode === 'build' ? `- You have all tools available: read, write, edit, ba
       maxTokens: this.config.maxTokens || 8192,
       temperature: this.config.temperature ?? 0.7,
       tools: toolDefs,
-      system: this.systemPrompt + (this._skillBlock || '') + (this._agentBlock || ''),
+      system: this.systemPrompt + (this._skillBlock || '') + (this._agentBlock || '') + this._primaryBlock(),
       signal: this.abortController?.signal,
       // Extended thinking: models tagged 'reasoning' reason BEFORE every
       // reply — including after each tool result — so complex tasks get

package/src/providers/anthropic.js

@@ -50,10 +50,15 @@ function buildBody(messages, options) {
       continue;
     }
     if (m.role === 'tool') {
-      out.push({
-        role: 'user',
-        content: [{ type: 'tool_result', tool_use_id: m.toolCallId, content: String(m.content) }],
-      });
+      // tool_use_id is required by the API — skip orphaned tool rows from
+      // resumed/hand-edited sessions rather than failing the whole turn.
+      const tcid = m.toolCallId || m.tool_call_id;
+      if (tcid) {
+        out.push({
+          role: 'user',
+          content: [{ type: 'tool_result', tool_use_id: tcid, content: String(m.content) }],
+        });
+      }
       continue;
     }
     if (m.role === 'assistant') {
@@ -70,7 +75,7 @@ function buildBody(messages, options) {
       } else if (m.content) {
         blocks.push({ type: 'text', text: m.content });
       }
-      for (const tc of m.toolCalls || []) {
+      for (const tc of (m.toolCalls || m.tool_calls) || []) {
         blocks.push({ type: 'tool_use', id: tc.id, name: tc.name, input: tc.input || {} });
       }
       out.push({ role: 'assistant', content: blocks });

package/src/providers/openai-compat.js

@@ -9,12 +9,17 @@ function formatMessages(messages, options) {
   for (const m of messages) {
     if (m.role === 'system') continue;
     if (m.role === 'tool') {
-      out.push({ role: 'tool', tool_call_id: m.toolCallId, content: String(m.content) });
+      // A tool row without its id would be rejected by the API ("missing
+      // field tool_call_id" — NVIDIA is strict about this). Skip orphans
+      // from hand-edited/resumed sessions instead of failing the turn.
+      const tcid = m.toolCallId || m.tool_call_id;
+      if (tcid) out.push({ role: 'tool', tool_call_id: tcid, content: String(m.content) });
       continue;
     }
     const msg = { role: m.role, content: m.content || '' };
-    if (m.toolCalls && m.toolCalls.length) {
-      msg.tool_calls = m.toolCalls.map(tc => ({
+    const calls = m.toolCalls || m.tool_calls;
+    if (calls && calls.length) {
+      msg.tool_calls = calls.map(tc => ({
         id: tc.id,
         type: 'function',
         function: { name: tc.name, arguments: typeof tc.input === 'string' ? tc.input : JSON.stringify(tc.input || {}) },
@@ -80,6 +85,7 @@ function normalize(resp) {
     content: message.content || '',
     toolCalls,
     usage: resp.usage,
+    finishReason: choice?.finish_reason || undefined,
   };
 }
 
@@ -208,10 +214,12 @@ function createOpenAICompatProvider({ getKey, providerId, envKeyHint, clientFact
       let content = '';
       let reasoning = '';
       let usage = null;
+      let finishReason = null;
       const toolAcc = new Map();
 
       for await (const chunk of s) {
         if (chunk.usage) usage = chunk.usage;
+        if (chunk.choices?.[0]?.finish_reason) finishReason = chunk.choices[0].finish_reason;
         const delta = chunk.choices?.[0]?.delta || {};
         // DeepSeek-style reasoning_content / OpenRouter reasoning deltas.
         const rt = delta.reasoning_content || delta.reasoning;
@@ -243,7 +251,7 @@ function createOpenAICompatProvider({ getKey, providerId, envKeyHint, clientFact
         toolCalls.push({ id: acc.id, name: acc.name, input });
       }
 
-      return { content, reasoning, toolCalls, usage };
+      return { content, reasoning, toolCalls, usage, finishReason: finishReason || undefined };
     } catch (err) {
       if (isAbortError(err)) throw err;
       throw wrapErr(err, options.model || '?', envKeyHint, getBaseUrl(providerId));

package/src/tools/browser.js

@@ -0,0 +1,204 @@
+// Headless browser control for the Web agent (and any build-mode session).
+// Wraps Playwright behind a single-page singleton: the first action launches
+// a headless Chromium and every later action reuses it, so "open a page, click
+// around, read the DOM" works across tool calls without re-launching.
+//
+// Engine resolution order:
+//   1. `playwright` (bundled chromium download, if the user installed it)
+//   2. `playwright-core` + a system Chrome / Edge channel (zero download)
+// Everything runs in the page context only — no filesystem access beyond the
+// screenshot path the caller passes (enforced by the tool-layer sandbox for
+// writes is intentionally NOT applied here: screenshots land in the OS temp
+// dir by default and the tool returns the absolute path).
+const fs = require('fs');
+const os = require('os');
+const path = require('path');
+
+const INSTALL_HINT = 'Install a browser engine:  npm i playwright  then  npx playwright install chromium  (or install playwright-core and have Chrome/Edge available)';
+const ACTION_TIMEOUT_MS = 30000;
+
+/** @type {{ browser: any, page: any }|null} */
+let _engine = null;
+let _playwright = null; // null = not tried, false = unavailable, else module
+
+const ACTIONS = ['goto', 'click', 'fill', 'press', 'text', 'eval', 'links', 'screenshot', 'close'];
+
+function loadPlaywright() {
+  if (_playwright !== null) return _playwright || null;
+  for (const mod of ['playwright', 'playwright-core']) {
+    try { _playwright = require(mod); return _playwright; } catch {}
+  }
+  _playwright = false;
+  return null;
+}
+
+function withTimeout(promise, ms) {
+  let timer;
+  const timeout = new Promise((_, reject) => {
+    timer = setTimeout(() => reject(new Error('browser action timed out after ' + ms + 'ms')), ms);
+  });
+  return Promise.race([promise, timeout]).finally(() => clearTimeout(timer));
+}
+
+function checkUrl(url) {
+  const u = String(url || '').trim();
+  if (!u) return { error: 'goto needs a url.' };
+  let parsed;
+  try { parsed = new URL(u); } catch { return { error: 'Invalid url: ' + u }; }
+  if (parsed.protocol !== 'http:' && parsed.protocol !== 'https:') {
+    return { error: 'Only http/https urls are allowed (got ' + parsed.protocol + ').' };
+  }
+  return { url: parsed.href };
+}
+
+async function pageSnapshot(page) {
+  const title = await page.title().catch(() => '');
+  return 'URL: ' + page.url() + (title ? '\nTitle: ' + title : '');
+}
+
+/** Launch (or reuse) the headless browser. Returns the page or {error}. */
+async function ensurePage() {
+  if (_engine && _engine.page && !_engine.page.isClosed()) return _engine.page;
+  const pw = loadPlaywright();
+  if (!pw) {
+    return { error: 'No browser engine found. ' + INSTALL_HINT };
+  }
+  const attempts = [
+    () => pw.chromium.launch({ headless: true }),
+    () => pw.chromium.launch({ headless: true, channel: 'chrome' }),
+    () => pw.chromium.launch({ headless: true, channel: 'msedge' }),
+  ];
+  let lastErr = null;
+  for (const attempt of attempts) {
+    try {
+      const browser = await withTimeout(attempt(), 20000);
+      const context = await browser.newContext({ viewport: { width: 1280, height: 800 } });
+      const page = await context.newPage();
+      _engine = { browser, page };
+      return page;
+    } catch (err) { lastErr = err; }
+  }
+  return { error: 'Failed to launch a browser: ' + (lastErr && lastErr.message) + '. ' + INSTALL_HINT };
+}
+
+/** Close the singleton browser (also used as the `close` action). */
+async function closeBrowser() {
+  if (!_engine) return 'No browser is running.';
+  try { await _engine.browser.close(); } catch {}
+  _engine = null;
+  return 'Browser closed.';
+}
+
+/**
+ * Execute one browser action. `params` comes straight from the tool call:
+ *   action, url, selector, text, key, script, path
+ * @param {Record<string, any>} params
+ * @returns {Promise<string|{error: string}>}
+ */
+async function run(params) {
+  const action = String(params.action || '').toLowerCase().trim();
+  if (!ACTIONS.includes(action)) {
+    return { error: 'Unknown action "' + action + '". Use one of: ' + ACTIONS.join(' | ') };
+  }
+  if (action === 'close') return closeBrowser();
+
+  // Validate inputs BEFORE launching a browser so bad calls fail fast and
+  // never spawn a headless process.
+  if (action === 'goto') {
+    const u = checkUrl(params.url);
+    if (u.error) return u;
+  }
+  if ((action === 'click' || action === 'fill') && !String(params.selector || '').trim()) {
+    return { error: action + ' needs a CSS selector.' };
+  }
+  if (action === 'press' && !String(params.key || '').trim()) {
+    return { error: 'press needs a key (e.g. Enter, Tab, Escape, Control+A).' };
+  }
+  if (action === 'eval' && !String(params.script || '').trim()) {
+    return { error: 'eval needs a JavaScript expression (runs in the page context).' };
+  }
+
+  const page = await ensurePage();
+  if (page && typeof page === 'object' && 'error' in page) return page;
+
+  try {
+    switch (action) {
+      case 'goto': {
+        const u = checkUrl(params.url);
+        if (u.error) return u;
+        await withTimeout(page.goto(u.url, { waitUntil: 'domcontentloaded', timeout: ACTION_TIMEOUT_MS }), ACTION_TIMEOUT_MS + 2000);
+        await page.waitForLoadState('load', { timeout: 10000 }).catch(() => {});
+        return 'Opened ' + (await pageSnapshot(page));
+      }
+      case 'click': {
+        const sel = String(params.selector || '').trim();
+        if (!sel) return { error: 'click needs a CSS selector.' };
+        await withTimeout(page.click(sel, { timeout: 10000 }), 12000);
+        await page.waitForLoadState('domcontentloaded', { timeout: 5000 }).catch(() => {});
+        return 'Clicked "' + sel + '".\n' + (await pageSnapshot(page));
+      }
+      case 'fill': {
+        const sel = String(params.selector || '').trim();
+        if (!sel) return { error: 'fill needs a CSS selector.' };
+        await withTimeout(page.fill(sel, String(params.text ?? ''), { timeout: 10000 }), 12000);
+        return 'Filled "' + sel + '" with ' + String(params.text ?? '').length + ' chars.';
+      }
+      case 'press': {
+        const key = String(params.key || '').trim();
+        if (!key) return { error: 'press needs a key (e.g. Enter, Tab, Escape, Control+A).' };
+        await page.keyboard.press(key);
+        await page.waitForLoadState('domcontentloaded', { timeout: 5000 }).catch(() => {});
+        return 'Pressed ' + key + '.\n' + (await pageSnapshot(page));
+      }
+      case 'text': {
+        const body = await withTimeout(page.innerText('body').catch(() => ''), 10000);
+        const text = String(body || '').replace(/\n{3,}/g, '\n\n').trim();
+        const head = await pageSnapshot(page);
+        return head + '\n\n' + (text ? text.slice(0, 10000) : '(page has no visible text — try action="eval" or action="links")');
+      }
+      case 'eval': {
+        const script = String(params.script || '').trim();
+        if (!script) return { error: 'eval needs a JavaScript expression (runs in the page context).' };
+        // Function-body form keeps multi-statement scripts working.
+        const result = await withTimeout(page.evaluate((src) => {
+          try { return JSON.stringify({ ok: true, value: new Function('return (' + src + ')')() }); }
+          catch (e) { return JSON.stringify({ ok: false, error: String(e && e.message || e) }); }
+        }, script), 10000);
+        const parsed = JSON.parse(String(result));
+        if (!parsed.ok) return { error: 'eval failed: ' + parsed.error };
+        const out = typeof parsed.value === 'string' ? parsed.value : JSON.stringify(parsed.value, null, 2);
+        return String(out == null ? 'null' : out).slice(0, 10000);
+      }
+      case 'links': {
+        const links = await withTimeout(
+          page.$$eval('a[href]', (els) => els.slice(0, 100).map((a) => ({
+            href: a.getAttribute('href') || '',
+            text: (a.textContent || '').trim().replace(/\s+/g, ' ').slice(0, 120),
+          }))),
+          10000,
+        );
+        if (!links.length) return (await pageSnapshot(page)) + '\n\n(no links found)';
+        return links.map((l, i) => (i + 1) + '. ' + l.text + ' — ' + l.href).join('\n').slice(0, 10000);
+      }
+      case 'screenshot': {
+        const dest = params.path
+          ? path.resolve(String(params.path))
+          : path.join(os.tmpdir(), 'loom-browser-' + Date.now() + '.png');
+        fs.mkdirSync(path.dirname(dest), { recursive: true });
+        await withTimeout(page.screenshot({ path: dest, fullPage: false }), 15000);
+        return 'Screenshot saved: ' + dest + '\n' + (await pageSnapshot(page));
+      }
+      default:
+        return { error: 'Unknown action "' + action + '".' };
+    }
+  } catch (err) {
+    return { error: 'browser ' + action + ' failed: ' + (err && err.message || err) };
+  }
+}
+
+// Test/diagnostic hook — true when a browser page is live.
+function isRunning() {
+  return !!( _engine && _engine.page && !_engine.page.isClosed() );
+}
+
+module.exports = { run, closeBrowser, isRunning, ACTIONS };

package/src/tools/index.js

@@ -193,6 +193,24 @@ const TOOLS = {
       background: { type: 'boolean', required: false, description: 'Run without waiting (dev servers, long builds). Returns a task id immediately; check with the /tasks panel.' },
     },
     async execute(params, ctx) {
+      // Docker sandbox: when enabled (/sandbox setup), every command runs
+      // inside the loom-sandbox container instead of the host shell.
+      // Background tasks stay on the host (they outlive tool timeouts).
+      const sandbox = require('../core/sandbox');
+      if (!params.background && sandbox.shouldUseSandbox()) {
+        if (!pathAllowed(params.workdir || cwd)) return { error: sandboxDenied('bash', params.workdir || cwd) };
+        const risk = params._approved ? null : commandRiskLabel(params.command);
+        if (risk) return { error: `Blocked by safety filter: ${risk}. Approve it via the permission prompt to run it anyway.` };
+        const stream = ctx && typeof ctx.stream === 'function' ? ctx.stream : null;
+        const res = await sandbox.runInSandbox(params.command, {
+          workdir: params.workdir || cwd,
+          onChunk: stream ? (text, which) => stream(text, which) : undefined,
+        });
+        if ('error' in res) return { error: res.error };
+        let out = res.output;
+        if (res.code !== 0) out += `\n[exit code: ${res.code}]`;
+        return out || 'command completed';
+      }
       // Background mode: fire-and-forget via the task registry.
       if (params.background) {
         const bt = require('../core/background-tasks');
@@ -440,7 +458,7 @@ const TOOLS = {
   },
   task: {
     name: 'task',
-    description: 'Delegate a self-contained subtask to a subagent that runs fully autonomously and returns its final answer. Use when a piece of work can run independently (parallelizable), needs a focused toolset, or benefits from a different model. Pick the smallest suitable agent: explore (fast read-only code search), scout (web/docs research), general (full toolset except delegation). Pass the agent a COMPLETE, self-contained instruction: the goal, relevant file paths, and exactly what to return. The subagent may run tools autonomously; fold its findings into your own answer afterwards.',
+    description: 'Delegate a self-contained subtask to a subagent that runs fully autonomously and returns its final answer. Use when a piece of work can run independently (parallelizable), needs a focused toolset, or benefits from a different model. Agents: general (full toolset, default), explore (fast read-only code search), scout (quick docs lookups), research (deep multi-source investigation with a sourced report), coder (isolated implementation packages), reviewer (severity-ranked code review), tester (write/run tests until green), web (headless-browser work on live pages). Pick the smallest suitable agent. Pass a COMPLETE, self-contained instruction: the goal, relevant file paths, and exactly what to return. The subagent may run tools autonomously; fold its findings into your own answer afterwards.',
     parameters: {
       prompt: { type: 'string', required: true, description: 'Complete instructions for the subagent — goal, relevant file paths, and the exact output to return' },
       agent: { type: 'string', required: false, description: 'Subagent id: general (default), explore, scout, or a custom one from config.agents' },
@@ -462,6 +480,22 @@ const TOOLS = {
       return usage + '\n\n' + res.content;
     }
   },
+  browser: {
+    name: 'browser',
+    description: 'Drive a real headless browser (Playwright). Actions: goto (open an http/https url), click (CSS selector), fill (selector + text), press (key like Enter), text (visible page text + title/url), eval (JS expression in the page context), links (list page links), screenshot (save PNG, returns the file path), close. The browser stays open between calls so you can navigate, interact, and re-read the page. Prefer this over webfetch when the page needs JavaScript rendering or interaction.',
+    parameters: {
+      action: { type: 'string', required: true, description: '"goto" | "click" | "fill" | "press" | "text" | "eval" | "links" | "screenshot" | "close"' },
+      url: { type: 'string', required: false, description: 'Page url (action=goto)' },
+      selector: { type: 'string', required: false, description: 'CSS selector (action=click or fill)' },
+      text: { type: 'string', required: false, description: 'Text to type into the selector (action=fill)' },
+      key: { type: 'string', required: false, description: 'Key to press, e.g. Enter (action=press)' },
+      script: { type: 'string', required: false, description: 'JS expression evaluated in the page (action=eval)' },
+      path: { type: 'string', required: false, description: 'Screenshot destination path (action=screenshot; default: OS temp dir)' },
+    },
+    async execute(params) {
+      return require('./browser').run(params);
+    }
+  },
   mcp: {
     name: 'mcp',
     description: 'Manage MCP (tool) servers for this workspace. Use when the user asks to add/remove/enable/disable an MCP server or connector (e.g. github, filesystem, gmail) or when a task requires tools the session does not have yet. In the TUI, hosting/cloud services (supabase, vercel, nextjs, railway, netlify, cloudflare) live under /connectors; dev-tool MCP servers (playwright, github, sentry, figma, postgres, mongodb, linear, slack, brave-search, exa, context7, filesystem, sqlite, puppeteer) live under /mcp. Common packages: Playwright=@playwright/mcp, Sentry=@sentry/mcp-server (needs --access-token TOKEN), Figma=figma-developer-mcp (env FIGMA_API_KEY), Postgres=@modelcontextprotocol/server-postgres (env DATABASE_URL), MongoDB=mongodb-mcp-server (env MONGODB_CONNECTION_STRING), Linear=linear-mcp-server (env LINEAR_API_KEY), Slack=@modelcontextprotocol/server-slack (env SLACK_BOT_TOKEN + SLACK_TEAM_ID), Brave=@modelcontextprotocol/server-brave-search (env BRAVE_API_KEY), Exa=exa-mcp-server (env EXA_API_KEY), Context7=@upstash/context7-mcp, Vercel=vercel-mcp-server (env VERCEL_TOKEN), Railway=@railway/mcp-server (env RAILWAY_API_TOKEN), Netlify=netlify-mcp-server (env NETLIFY_AUTH_TOKEN), Cloudflare=@cloudflare/mcp-server-cloudflare (env CLOUDFLARE_API_TOKEN + CLOUDFLARE_ACCOUNT_ID), Supabase=@supabase/mcp-server-supabase (needs --access-token TOKEN), GitHub=ghcr.io/github/github-mcp-server (docker). If unsure about an MCP package, verify it exists first with webfetch (e.g. https://registry.npmjs.org/<pkg>) or web search (fetch or bash curl) — never trust an unverified npm package.',