codeam-cli 2.75.25 → 2.75.26

package/CHANGELOG.md

@@ -4,6 +4,13 @@ All notable changes to `codeam-cli` are documented here.
 
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/), and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [2.75.25] — 2026-09-25
+
+### Added
+
+- **cli:** Send every runnable repo script with the preview detection
+- **cli:** Install preview deps in the background at session start; room for monorepo builds
+
 ## [2.75.23] — 2026-09-25
 
 ### Fixed

package/dist/index.js

@@ -3248,6 +3248,9 @@ var USER_EVENTS = {
   PREVIEW_STOPPED: "preview_stopped",
   PREVIEW_ERROR: "preview_error",
   PREVIEW_PROGRESS: "preview_progress",
+  /** The agent points at an element of the running preview (`highlight_element`
+   *  MCP tool) — the inspector client draws the agent's mark over it. */
+  PREVIEW_AGENT_HIGHLIGHT: "preview_agent_highlight",
   BEADS_STATE_CHANGED: "beads_state_changed",
   BEADS_PROVISIONING: "beads_provisioning",
   BEADS_TEAM_MEMORY_CHANGED: "beads_team_memory_changed",
@@ -10509,7 +10512,7 @@ function readAnonId() {
 }
 function superProperties() {
   return {
-    cliVersion: true ? "2.75.25" : "0.0.0-dev",
+    cliVersion: true ? "2.75.26" : "0.0.0-dev",
     nodeVersion: process.version,
     platform: process.platform,
     arch: process.arch,
@@ -10751,7 +10754,7 @@ var http = __toESM(require("http"));
 // package.json
 var package_default = {
   name: "codeam-cli",
-  version: "2.75.25",
+  version: "2.75.26",
   description: "Workflow-continuity bridge for AI coding agents. Wrap Claude Code or Codex in a PTY and supervise, approve, and redirect the session from any device \u2014 async. The terminal companion for CodeAgent Mobile.",
   type: "commonjs",
   main: "dist/index.js",
@@ -12081,7 +12084,7 @@ var CommandRelayService = class _CommandRelayService {
       // fresh + clear the "CLI update available" banner after a self-update
       // (a codespace that reinstalls @latest reconnects via heartbeat, not
       // pair/reconnect). Older backends ignore the extra field.
-      ..."2.75.25" ? { ideVersion: "2.75.25" } : {}
+      ..."2.75.26" ? { ideVersion: "2.75.26" } : {}
     };
     try {
       const res = await _postJson(`${API_BASE2}/api/plugin/heartbeat`, body);
@@ -24628,6 +24631,145 @@ function inspectorClientSource(opts) {
       redrawMarks();
     }
 
+    /**
+     * Las marcas del AGENTE \u2014 la herramienta highlight_element.
+     *
+     * Van aparte de las del usuario a proposito: no se numeran, no se pueden
+     * borrar desde el composer y no dependen de que el modo inspector este
+     * encendido. Son el agente SE\xD1ALANDO algo, y el usuario las ve aunque no
+     * haya tocado nada: un cursor que viaja hasta el elemento, lo centra en
+     * pantalla y deja una caja con su etiqueta.
+     *
+     * Mismo anclaje que las marcas fijadas (coordenadas de documento), asi que
+     * acompa\xF1an al scroll. Un selector que no encuentra nada no pinta nada: el
+     * agente ya sabe por la herramienta que puede fallar.
+     */
+    var AGENT = '#22d3ee';
+    var agentMarks = [];
+    var agentHost = null;
+    var agentCursor = null;
+    var agentStyle = null;
+    var agentListening = false;
+
+    function ensureAgentStyle() {
+      if (agentStyle && agentStyle.parentNode) return;
+      agentStyle = document.createElement('style');
+      agentStyle.setAttribute('data-codeam', 'agent-style');
+      agentStyle.textContent =
+        '@keyframes codeam-agent-pulse{0%{box-shadow:0 0 0 0 rgba(34,211,238,.55)}' +
+        '70%{box-shadow:0 0 0 10px rgba(34,211,238,0)}100%{box-shadow:0 0 0 0 rgba(34,211,238,0)}}' +
+        '@keyframes codeam-agent-in{from{opacity:0;transform:scale(1.06)}to{opacity:1;transform:scale(1)}}';
+      (document.head || document.documentElement).appendChild(agentStyle);
+    }
+
+    function ensureAgentCursor() {
+      if (agentCursor && agentCursor.parentNode) return agentCursor;
+      agentCursor = document.createElement('div');
+      agentCursor.setAttribute('data-codeam', 'agent-cursor');
+      agentCursor.style.cssText = [
+        'position:fixed', 'pointer-events:none', 'z-index:2147483647',
+        'left:' + Math.round(window.innerWidth / 2) + 'px', 'top:' + Math.round(window.innerHeight - 40) + 'px',
+        'transition:left .6s cubic-bezier(.22,1,.36,1),top .6s cubic-bezier(.22,1,.36,1),opacity .3s',
+        'opacity:0'
+      ].join(';');
+      agentCursor.innerHTML =
+        '<svg width="22" height="22" viewBox="0 0 24 24" style="display:block;filter:drop-shadow(0 1px 2px rgba(0,0,0,.5))">' +
+        '<path d="M4 2l15 8.5-6.6 1.6L9 18.5z" fill="' + AGENT + '" stroke="#000" stroke-width="1.2"/></svg>' +
+        '<div style="margin:2px 0 0 14px;background:' + AGENT + ';color:#000;font:700 10px/1.5 ui-monospace,SFMono-Regular,Menlo,monospace;' +
+        'padding:1px 6px;border-radius:8px;white-space:nowrap">Agent</div>';
+      document.body.appendChild(agentCursor);
+      return agentCursor;
+    }
+
+    function redrawAgentMarks() {
+      if (agentMarks.length === 0) {
+        if (agentHost && agentHost.parentNode) agentHost.parentNode.removeChild(agentHost);
+        agentHost = null;
+        return;
+      }
+      if (!agentHost || !agentHost.parentNode) {
+        agentHost = document.createElement('div');
+        agentHost.setAttribute('data-codeam', 'agent-marks');
+        agentHost.style.cssText = 'position:absolute;left:0;top:0;width:0;height:0;z-index:2147483646';
+        document.body.appendChild(agentHost);
+      }
+      agentHost.innerHTML = '';
+      var sx = window.scrollX || window.pageXOffset || 0;
+      var sy = window.scrollY || window.pageYOffset || 0;
+      for (var i = 0; i < agentMarks.length; i++) {
+        var m = agentMarks[i];
+        if (!m.el.isConnected) continue;
+        var r = m.el.getBoundingClientRect();
+        var box = document.createElement('div');
+        box.setAttribute('data-codeam', 'agent-mark');
+        box.style.cssText = [
+          'position:absolute', 'pointer-events:none', 'box-sizing:border-box',
+          'border:2px solid ' + AGENT, 'background:rgba(34,211,238,0.10)', 'border-radius:4px',
+          'left:' + (r.left + sx - 3) + 'px', 'top:' + (r.top + sy - 3) + 'px',
+          'width:' + (r.width + 6) + 'px', 'height:' + (r.height + 6) + 'px',
+          'animation:codeam-agent-in .25s ease-out,codeam-agent-pulse 1.6s ease-out 3'
+        ].join(';');
+        if (m.label) {
+          var tag = document.createElement('div');
+          tag.setAttribute('data-codeam', 'agent-mark-label');
+          tag.style.cssText = [
+            'position:absolute', 'left:-2px', (r.top >= 22 ? 'top:-22px' : 'bottom:-22px'),
+            'background:' + AGENT, 'color:#000', 'font:700 11px/1.6 ui-monospace,SFMono-Regular,Menlo,monospace',
+            'padding:0 6px', 'border-radius:3px', 'white-space:nowrap', 'max-width:260px',
+            'overflow:hidden', 'text-overflow:ellipsis'
+          ].join(';');
+          tag.textContent = m.label;
+          box.appendChild(tag);
+        }
+        agentHost.appendChild(box);
+      }
+    }
+
+    function listenAgentLayout() {
+      if (agentListening) return;
+      agentListening = true;
+      window.addEventListener('scroll', redrawAgentMarks, true);
+      window.addEventListener('resize', redrawAgentMarks);
+    }
+
+    function agentHighlight(selector, labelText) {
+      var el = null;
+      try { el = document.querySelector(String(selector)); } catch (e) { el = null; }
+      if (!el || !el.getBoundingClientRect) return false;
+      ensureAgentStyle();
+      listenAgentLayout();
+      try { el.scrollIntoView({ block: 'center', inline: 'nearest', behavior: 'smooth' }); } catch (e) { /* viejo */ }
+      var cursor = ensureAgentCursor();
+      // Tras el scroll suave: el cursor viaja al centro del elemento y, al
+      // llegar, aparece la caja. El orden es lo que se lee como \xABel agente
+      // lo esta se\xF1alando\xBB y no como un recuadro que salta.
+      setTimeout(function () {
+        var r = el.getBoundingClientRect();
+        cursor.style.opacity = '1';
+        cursor.style.left = Math.round(r.left + Math.min(r.width / 2, 40)) + 'px';
+        cursor.style.top = Math.round(r.top + Math.min(r.height / 2, 24)) + 'px';
+        setTimeout(function () {
+          agentMarks.push({ el: el, label: labelText ? String(labelText).slice(0, 80) : '' });
+          redrawAgentMarks();
+        }, 620);
+      }, 380);
+      return true;
+    }
+
+    function agentClear() {
+      agentMarks = [];
+      redrawAgentMarks();
+      if (agentCursor && agentCursor.parentNode) agentCursor.parentNode.removeChild(agentCursor);
+      agentCursor = null;
+      if (agentStyle && agentStyle.parentNode) agentStyle.parentNode.removeChild(agentStyle);
+      agentStyle = null;
+      if (agentListening) {
+        window.removeEventListener('scroll', redrawAgentMarks, true);
+        window.removeEventListener('resize', redrawAgentMarks);
+        agentListening = false;
+      }
+    }
+
     function enable(origin) {
       if (enabled) return;
       enabled = true;
@@ -24661,6 +24803,8 @@ function inspectorClientSource(opts) {
       if (data.type === 'enable') enable(e.origin);
       else if (data.type === 'disable') disable();
       else if (data.type === 'marks' && data.ids) syncMarks(data.ids);
+      else if (data.type === 'agent-highlight' && data.selector) agentHighlight(data.selector, data.label);
+      else if (data.type === 'agent-clear') agentClear();
     });
 
     /**
@@ -24679,6 +24823,11 @@ function inspectorClientSource(opts) {
       window.__codeamInspector = {
         enable: function () { enable('react-native'); },
         disable: disable,
+        // La app movil ya llamaba \`marks\` al borrar un chip y no existia:
+        // la marca se quedaba pintada en la pagina.
+        marks: function (ids) { if (ids && ids.length !== undefined) syncMarks(ids); },
+        highlight: function (selector, text) { return agentHighlight(selector, text); },
+        clear: agentClear,
       };
     }
   } catch (e) {
@@ -26518,9 +26667,9 @@ async function configureBeads(action, ctx, deps) {
       return { enabled: false, running: false };
     }
     const p3 = await deps.probe();
-    const running2 = p3.serverUp && p3.bdAvailable;
-    deps.emit({ type: "beads_status", state: running2 ? "enabled" : "disabled", running: running2, ...p3 });
-    return { enabled: running2, running: running2, ...p3 };
+    const running3 = p3.serverUp && p3.bdAvailable;
+    deps.emit({ type: "beads_status", state: running3 ? "enabled" : "disabled", running: running3, ...p3 });
+    return { enabled: running3, running: running3, ...p3 };
   }
   if (action === "disable") {
     deps.persist({ enabled: false });
@@ -26537,9 +26686,9 @@ async function configureBeads(action, ctx, deps) {
     return { enabled: false, ...p2 };
   }
   await deps.startWatcher().catch(() => void 0);
-  const running = true;
-  deps.emit({ type: "beads_status", state: "enabled", running, ...p2 });
-  return { enabled: true, running, ...p2 };
+  const running2 = true;
+  deps.emit({ type: "beads_status", state: "enabled", running: running2, ...p2 });
+  return { enabled: true, running: running2, ...p2 };
 }
 
 // src/skills/configure.ts
@@ -27759,105 +27908,88 @@ async function runDetectOneShot(generate, timeoutMs = PREVIEW_DETECT_TIMEOUT_MS)
     if (timer) clearTimeout(timer);
   }
 }
-var requestPreviewDetectH = (ctx) => {
-  if (!ctx.pluginAuthToken) {
-    log.info("preview", "no pluginAuthToken \u2014 skipping detect");
-    return;
-  }
-  if (typeof ctx.runtime.generateOneShot !== "function") {
-    log.info("preview", `runtime ${ctx.runtime.id} has no generateOneShot \u2014 emitting unsupported`);
+function originPayload(payload, origin) {
+  if (origin !== "agent") return payload;
+  return { ...payload ?? {}, origin };
+}
+async function resolvePreviewDetection(args2) {
+  const { ctx, runtime, pluginAuthToken, origin } = args2;
+  const emit2 = (type, payload) => {
     emitPreviewEvent({
       sessionId: ctx.sessionId,
       pluginId: ctx.pluginId,
-      pluginAuthToken: ctx.pluginAuthToken,
-      type: USER_EVENTS.PREVIEW_ERROR,
-      payload: {
-        stage: "detection",
-        message: `Preview detection isn't available on ${ctx.runtime.id} sessions yet \u2014 link a Claude or Codex agent.`
-      }
+      pluginAuthToken,
+      type,
+      payload: originPayload(payload, origin)
     });
-    return;
+  };
+  if (typeof runtime.generateOneShot !== "function") {
+    log.info("preview", `runtime ${runtime.id} has no generateOneShot \u2014 emitting unsupported`);
+    emit2(USER_EVENTS.PREVIEW_ERROR, {
+      stage: "detection",
+      message: `Preview detection isn't available on ${runtime.id} sessions yet \u2014 link a Claude or Codex agent.`
+    });
+    return null;
   }
-  const pluginAuthToken = ctx.pluginAuthToken;
-  const generateOneShot = ctx.runtime.generateOneShot.bind(ctx.runtime);
-  void (async () => {
-    const fromFile = await readPreviewConfig(process.cwd());
-    if (fromFile) {
-      log.info("preview", `detect: using .codeam/preview.json (${fromFile.framework})`);
-      emitPreviewEvent({
-        sessionId: ctx.sessionId,
-        pluginId: ctx.pluginId,
-        pluginAuthToken,
-        type: USER_EVENTS.PREVIEW_DETECTION_READY,
-        payload: { detection: withScriptCandidates(fromFile) }
-      });
-      return;
-    }
-    emitPreviewEvent({
-      sessionId: ctx.sessionId,
-      pluginId: ctx.pluginId,
-      pluginAuthToken,
-      type: USER_EVENTS.PREVIEW_DETECTION_PENDING
+  const generateOneShot = runtime.generateOneShot.bind(runtime);
+  const fromFile = await readPreviewConfig(process.cwd());
+  if (fromFile) {
+    log.info("preview", `detect: using .codeam/preview.json (${fromFile.framework})`);
+    return fromFile;
+  }
+  emit2(USER_EVENTS.PREVIEW_DETECTION_PENDING);
+  log.info("preview", "detect: invoking generateOneShot");
+  const startedAt = Date.now();
+  const { raw, timedOut, stderr } = await runDetectOneShot(generateOneShot);
+  const tookMs = Date.now() - startedAt;
+  if (timedOut) {
+    log.info("preview", `detect: timed out after ${tookMs}ms \u2014 emitting preview_error`);
+    emit2(USER_EVENTS.PREVIEW_ERROR, {
+      stage: "detection",
+      message: `Project detection timed out after ${Math.round(PREVIEW_DETECT_TIMEOUT_MS / 1e3)} s \u2014 the agent did not answer. Try again, or add a .codeam/preview.json override.`
     });
-    log.info("preview", "detect: invoking generateOneShot");
-    const startedAt = Date.now();
-    const { raw, timedOut, stderr } = await runDetectOneShot(generateOneShot);
-    const tookMs = Date.now() - startedAt;
-    if (timedOut) {
-      log.info("preview", `detect: timed out after ${tookMs}ms \u2014 emitting preview_error`);
-      emitPreviewEvent({
-        sessionId: ctx.sessionId,
-        pluginId: ctx.pluginId,
-        pluginAuthToken,
-        type: USER_EVENTS.PREVIEW_ERROR,
-        payload: {
-          stage: "detection",
-          message: `Project detection timed out after ${Math.round(PREVIEW_DETECT_TIMEOUT_MS / 1e3)} s \u2014 the agent did not answer. Try again, or add a .codeam/preview.json override.`
-        }
-      });
-      return;
-    }
-    const detection = safeParseDetection(raw);
-    if (!detection) {
-      const failure = describeDetectionFailure(raw);
-      log.info(
-        "preview",
-        `detect: failed after ${tookMs}ms reason=${failure?.reason ?? "unknown"}` + (failure?.missing ? ` missing=${failure.missing.join(",")}` : "") + `
+    return null;
+  }
+  const detection = safeParseDetection(raw);
+  if (!detection) {
+    const failure = describeDetectionFailure(raw);
+    log.info(
+      "preview",
+      `detect: failed after ${tookMs}ms reason=${failure?.reason ?? "unknown"}` + (failure?.missing ? ` missing=${failure.missing.join(",")}` : "") + `
 --- salida cruda del agente (acotada) ---
 ${failure?.rawExcerpt ?? ""}`
-      );
-      emitPreviewEvent({
-        sessionId: ctx.sessionId,
-        pluginId: ctx.pluginId,
-        pluginAuthToken,
-        type: USER_EVENTS.PREVIEW_ERROR,
-        payload: {
-          stage: "detection",
-          // El mensaje sale del diagnostico: decir "JSON invalido" cuando el
-          // agente no contesto manda al usuario a mirar un JSON que no existe.
-          message: (failure?.reason === "no_output" ? describeOneShotAgentError(stderr) : null) ?? failure?.message ?? "Agent returned invalid JSON. Try again, or add a .codeam/preview.json override."
-        }
-      });
-      return;
-    }
-    if (isUnsupportedDetection(detection)) {
-      log.info("preview", "detect: framework=unsupported");
-      emitPreviewEvent({
-        sessionId: ctx.sessionId,
-        pluginId: ctx.pluginId,
-        pluginAuthToken,
-        type: USER_EVENTS.PREVIEW_ERROR,
-        payload: {
-          stage: "unsupported",
-          message: detection.notes ?? "No dev server applies to this project."
-        }
-      });
-      return;
-    }
-    log.info("preview", `detect: ${detection.framework} on :${detection.port} (took ${tookMs}ms)`);
-    void writePreviewConfig(process.cwd(), detection).catch((err) => {
-      log.info("preview", `detect: writePreviewConfig failed (non-fatal): ${String(err)}`);
+    );
+    emit2(USER_EVENTS.PREVIEW_ERROR, {
+      stage: "detection",
+      // El mensaje sale del diagnostico: decir "JSON invalido" cuando el
+      // agente no contesto manda al usuario a mirar un JSON que no existe.
+      message: (failure?.reason === "no_output" ? describeOneShotAgentError(stderr) : null) ?? failure?.message ?? "Agent returned invalid JSON. Try again, or add a .codeam/preview.json override."
     });
+    return null;
+  }
+  if (isUnsupportedDetection(detection)) {
+    log.info("preview", "detect: framework=unsupported");
+    emit2(USER_EVENTS.PREVIEW_ERROR, {
+      stage: "unsupported",
+      message: detection.notes ?? "No dev server applies to this project."
+    });
+    return null;
+  }
+  log.info("preview", `detect: ${detection.framework} on :${detection.port} (took ${tookMs}ms)`);
+  void writePreviewConfig(process.cwd(), detection).catch((err) => {
+    log.info("preview", `detect: writePreviewConfig failed (non-fatal): ${String(err)}`);
+  });
+  return detection;
+}
+var requestPreviewDetectH = (ctx) => {
+  if (!ctx.pluginAuthToken) {
+    log.info("preview", "no pluginAuthToken \u2014 skipping detect");
+    return;
+  }
+  const pluginAuthToken = ctx.pluginAuthToken;
+  void (async () => {
+    const detection = await resolvePreviewDetection({ ctx, runtime: ctx.runtime, pluginAuthToken });
+    if (!detection) return;
     emitPreviewEvent({
       sessionId: ctx.sessionId,
       pluginId: ctx.pluginId,
@@ -27940,19 +28072,21 @@ var previewStartH = (ctx, _cmd, parsed) => {
     log.info("preview", "start: no detection in payload");
     return;
   }
-  startPreviewFromDetection(ctx, rawDetection, ctx.pluginAuthToken);
+  void startPreviewFromDetection(ctx, rawDetection, ctx.pluginAuthToken);
 };
-function startPreviewFromDetection(ctx, detection, pluginAuthToken) {
+function startPreviewFromDetection(ctx, detection, pluginAuthToken, opts = {}) {
   const emit2 = (type, payload) => {
+    const tagged = originPayload(payload, opts.origin) ?? {};
+    opts.onEvent?.(type, tagged);
     emitPreviewEvent({
       sessionId: ctx.sessionId,
       pluginId: ctx.pluginId,
       pluginAuthToken,
       type,
-      payload
+      payload: tagged
     });
   };
-  runPreviewStart({
+  return runPreviewStart({
     sessionId: ctx.sessionId,
     detection,
     cwd: process.cwd(),
@@ -27983,7 +28117,7 @@ function maybeAttachBuildHeal(ctx, pluginAuthToken) {
         if (!activePreviews.has(ctx.sessionId)) return;
         await killPreview(ctx.sessionId);
         await new Promise((r) => setTimeout(r, 150));
-        startPreviewFromDetection(ctx, preview.detection, pluginAuthToken);
+        void startPreviewFromDetection(ctx, preview.detection, pluginAuthToken);
       })();
     },
     notify: (message) => {
@@ -28029,7 +28163,7 @@ var previewRestartH = async (ctx, cmd) => {
   }
   await killPreview(ctx.sessionId);
   await new Promise((r) => setTimeout(r, 150));
-  startPreviewFromDetection(ctx, preview.detection, ctx.pluginAuthToken);
+  void startPreviewFromDetection(ctx, preview.detection, ctx.pluginAuthToken);
   await ctx.relay.sendResult(cmd.id, "completed", { restarted: true });
 };
 var savePreviewConfigH = (_ctx, _cmd, parsed) => {
@@ -29339,7 +29473,7 @@ async function resolveAcpAdapterWithRetry(agent, opts = {}) {
 }
 
 // src/agents/acp/runner.ts
-var import_node_crypto10 = require("crypto");
+var import_node_crypto11 = require("crypto");
 var fs69 = __toESM(require("fs"));
 var os53 = __toESM(require("os"));
 var path80 = __toESM(require("path"));
@@ -39345,8 +39479,175 @@ async function mcpRouter() {
   });
 }
 
+// src/commands/preview-mcp.ts
+var PREVIEW_MCP_SERVER_NAME = "codeagent_preview";
+var PREVIEW_IPC_URL_ENV = "CODEAM_PREVIEW_IPC_URL";
+var PREVIEW_IPC_TOKEN_ENV = "CODEAM_PREVIEW_IPC_TOKEN";
+var START_TIMEOUT_MS = 27e4;
+var SHORT_TIMEOUT_MS = 2e4;
+var PREVIEW_TOOLS = [
+  {
+    name: "start_preview",
+    description: "Open this project's live Preview in the user's CodeAgent app \u2014 the same thing as their Preview button: it installs dependencies if needed, starts the dev server, publishes it on a public URL and switches the user's screen to it. Use it after you change anything visual (UI, styles, layout, copy) so you and the user can check the result, or whenever the user asks to see the app. Returns the public URL (you can curl it) or the exact error. Reuses a preview that is already running. Usually leave the arguments out: the project is detected automatically. Pass command/args/port only if you know the exact dev command.",
+    inputSchema: {
+      type: "object",
+      properties: {
+        command: { type: "string", description: 'Dev server executable, e.g. "npm". Optional.' },
+        args: { type: "array", items: { type: "string" }, description: 'e.g. ["run","dev"]. Optional.' },
+        port: { type: "number", description: "Port the dev server listens on. Required with command." },
+        framework: { type: "string", description: 'Label shown to the user, e.g. "next". Optional.' }
+      },
+      additionalProperties: false
+    }
+  },
+  {
+    name: "preview_status",
+    description: "Current state of the Preview: running (with its URL), starting, error (with the reason) or idle. Use it when start_preview answered that the preview is still starting.",
+    inputSchema: { type: "object", properties: {}, additionalProperties: false }
+  },
+  {
+    name: "highlight_element",
+    description: 'Point at an element in the running Preview: the user sees your cursor move to it and a labelled box drawn around it, scrolled into view. Use it to show the user exactly what you changed or what you are talking about ("this button", "the header spacing"). Takes a CSS selector (prefer ids, data-testid or specific classes you saw in the code). Several calls add several marks; clear_highlights removes them.',
+    inputSchema: {
+      type: "object",
+      properties: {
+        selector: { type: "string", description: 'CSS selector, e.g. "#checkout" or "[data-testid=hero-cta]".' },
+        label: { type: "string", description: 'Short caption on the mark, e.g. "New CTA". Optional.' }
+      },
+      required: ["selector"],
+      additionalProperties: false
+    }
+  },
+  {
+    name: "clear_highlights",
+    description: "Remove every mark you drew in the Preview with highlight_element.",
+    inputSchema: { type: "object", properties: {}, additionalProperties: false }
+  },
+  {
+    name: "stop_preview",
+    description: "Stop the Preview (dev server + public URL). Only when the user asks, or to restart it cleanly.",
+    inputSchema: { type: "object", properties: {}, additionalProperties: false }
+  }
+];
+function previewMcpServer(bridge) {
+  if (!bridge) return null;
+  return {
+    name: PREVIEW_MCP_SERVER_NAME,
+    // Same runtime + entrypoint as this CLI — never trust the agent's PATH.
+    command: process.execPath,
+    args: [process.argv[1], "preview-mcp"],
+    env: [
+      { name: PREVIEW_IPC_URL_ENV, value: bridge.url },
+      { name: PREVIEW_IPC_TOKEN_ENV, value: bridge.token }
+    ]
+  };
+}
+function httpCall(baseUrl, token) {
+  return async (path96, method, body, timeoutMs) => {
+    const ac = new AbortController();
+    const timer = setTimeout(() => ac.abort(), timeoutMs);
+    try {
+      const res = await fetch(`${baseUrl}${path96}`, {
+        method,
+        headers: { authorization: `Bearer ${token}`, "content-type": "application/json" },
+        ...method === "POST" ? { body: JSON.stringify(body ?? {}) } : {},
+        signal: ac.signal
+      });
+      return await res.json();
+    } finally {
+      clearTimeout(timer);
+    }
+  };
+}
+async function runPreviewTool(name, args2, call) {
+  switch (name) {
+    case "start_preview":
+      return describeResult(await call("/preview/start", "POST", args2, START_TIMEOUT_MS));
+    case "preview_status":
+      return describeResult(await call("/preview/status", "GET", void 0, SHORT_TIMEOUT_MS));
+    case "highlight_element":
+      return describeAck(await call("/preview/highlight", "POST", args2, SHORT_TIMEOUT_MS));
+    case "clear_highlights":
+      return describeAck(await call("/preview/highlight", "POST", { clear: true }, SHORT_TIMEOUT_MS));
+    case "stop_preview":
+      return describeAck(await call("/preview/stop", "POST", {}, SHORT_TIMEOUT_MS));
+    default:
+      return { text: `Unknown tool: ${name}`, isError: true };
+  }
+}
+function describeResult(raw) {
+  const r = raw && typeof raw === "object" ? raw : {};
+  switch (r.status) {
+    case "running": {
+      const inspector = r.inspector ? " You can point at elements with highlight_element." : " (No element highlighting for this framework.)";
+      return {
+        text: `Preview ${r.reused ? "already running" : "is live"}: ${String(r.url)} (${String(r.framework)}). The user's app is showing it now.${inspector}`,
+        isError: false
+      };
+    }
+    case "starting":
+      return { text: String(r.message ?? "The preview is starting."), isError: false };
+    case "idle":
+      return { text: "No preview is running.", isError: false };
+    case "error":
+      return {
+        text: `Preview failed at ${String(r.stage)}: ${String(r.message)}`,
+        isError: true
+      };
+    default:
+      return { text: `Unexpected answer from the preview bridge: ${JSON.stringify(raw)}`, isError: true };
+  }
+}
+function describeAck(raw) {
+  const r = raw && typeof raw === "object" ? raw : {};
+  return { text: String(r.message ?? r.error ?? "done"), isError: r.ok !== true };
+}
+async function previewMcp() {
+  const url2 = process.env[PREVIEW_IPC_URL_ENV];
+  const token = process.env[PREVIEW_IPC_TOKEN_ENV];
+  const { Server } = await import("@modelcontextprotocol/sdk/server/index.js");
+  const { StdioServerTransport } = await import("@modelcontextprotocol/sdk/server/stdio.js");
+  const { ListToolsRequestSchema, CallToolRequestSchema } = await import("@modelcontextprotocol/sdk/types.js");
+  const call = url2 && token ? httpCall(url2, token) : null;
+  const server = new Server({ name: PREVIEW_MCP_SERVER_NAME, version: "1.0.0" }, { capabilities: { tools: {} } });
+  server.setRequestHandler(ListToolsRequestSchema, async () => ({ tools: PREVIEW_TOOLS }));
+  server.setRequestHandler(CallToolRequestSchema, async (req) => {
+    if (!call) {
+      return {
+        content: [{ type: "text", text: "Preview is not available in this session." }],
+        isError: true
+      };
+    }
+    try {
+      const { text, isError: isError2 } = await runPreviewTool(
+        req.params.name,
+        req.params.arguments ?? {},
+        call
+      );
+      return { content: [{ type: "text", text }], isError: isError2 };
+    } catch (err) {
+      const aborted = err instanceof Error && err.name === "AbortError";
+      return {
+        content: [
+          {
+            type: "text",
+            text: aborted ? "The preview is taking long \u2014 it keeps going in the background; call preview_status shortly." : `Preview bridge unreachable: ${err instanceof Error ? err.message : String(err)}`
+          }
+        ],
+        isError: !aborted
+      };
+    }
+  });
+  await server.connect(new StdioServerTransport());
+}
+
 // src/integrations/provision.ts
 function buildMcpServersForStart(ctx) {
+  const servers = buildIntegrationMcpServers(ctx);
+  const preview = previewMcpServer(ctx.preview ?? null);
+  return preview ? [...servers, preview] : servers;
+}
+function buildIntegrationMcpServers(ctx) {
   const manifest = readIntegrationsManifest();
   if (!manifest || manifest.integrations.length === 0) return [];
   if (!ctx.pluginAuthToken) {
@@ -39518,6 +39819,299 @@ function mergeWithLocalMcpServers(integrationServers) {
   return merged;
 }
 
+// src/commands/start/agent-preview-bridge.ts
+var http11 = __toESM(require("http"));
+var import_node_crypto10 = require("crypto");
+var START_WAIT_MS = 24e4;
+var MAX_SELECTOR = 500;
+var MAX_LABEL = 80;
+var AgentPreviewBridge = class {
+  server = null;
+  listening = null;
+  token = (0, import_node_crypto10.randomBytes)(24).toString("hex");
+  ctx = null;
+  /** The bring-up in flight, so two tool calls never start two dev servers. */
+  inflight = null;
+  lastError = null;
+  bound = null;
+  /** Start the loopback server once. `null` when it could not bind — the
+   *  preview tools are then simply absent, never a failed session. */
+  listen() {
+    if (this.listening) return this.listening;
+    this.listening = new Promise((resolve12) => {
+      const server = http11.createServer((req, res) => {
+        void this.handle(req, res);
+      });
+      server.on("error", (err) => {
+        log.warn("agent-preview", `bridge failed to listen: ${String(err)}`);
+        resolve12(null);
+      });
+      server.listen(0, "127.0.0.1", () => {
+        const addr = server.address();
+        if (!addr || typeof addr === "string") {
+          resolve12(null);
+          return;
+        }
+        server.unref();
+        this.server = server;
+        this.bound = { url: `http://127.0.0.1:${addr.port}`, token: this.token };
+        resolve12(this.bound);
+      });
+    });
+    return this.listening;
+  }
+  /** The bound address once {@link listen} resolved, else null (sync, for
+   *  the MCP list rebuilds that happen mid-session). */
+  address() {
+    return this.bound;
+  }
+  /** Bind the live session. Tool calls before this answer "still starting". */
+  attach(ctx) {
+    this.ctx = ctx;
+  }
+  close() {
+    this.server?.close();
+    this.server = null;
+  }
+  // ─── Operations (public for tests) ─────────────────────────────────────
+  async start(override, waitMs = START_WAIT_MS) {
+    const ctx = this.ctx;
+    if (!ctx?.pluginAuthToken) {
+      return {
+        status: "error",
+        stage: "session",
+        message: "The session is still starting (or has no pairing token) \u2014 try again in a few seconds."
+      };
+    }
+    if (!this.inflight) {
+      const run = this.launch(ctx, ctx.pluginAuthToken, override);
+      this.inflight = run;
+      void run.finally(() => {
+        if (this.inflight === run) this.inflight = null;
+      });
+    }
+    const inflight = this.inflight;
+    let timer;
+    const pending = new Promise((resolve12) => {
+      timer = setTimeout(
+        () => resolve12({
+          status: "starting",
+          message: "The preview is still coming up (dependencies or a slow dev server). It keeps going in the background \u2014 call preview_status in a minute."
+        }),
+        waitMs
+      );
+      timer.unref?.();
+    });
+    try {
+      return await Promise.race([inflight, pending]);
+    } finally {
+      if (timer) clearTimeout(timer);
+    }
+  }
+  status() {
+    const ctx = this.ctx;
+    if (!ctx) return { status: "idle" };
+    const active2 = serving(ctx.sessionId);
+    if (active2) return running(active2, true);
+    if (this.inflight) return { status: "starting", message: "The preview is starting." };
+    if (this.lastError) return { status: "error", ...this.lastError };
+    return { status: "idle" };
+  }
+  async highlight(input) {
+    const ctx = this.ctx;
+    if (!ctx?.pluginAuthToken) return { ok: false, message: "The session is still starting." };
+    const active2 = serving(ctx.sessionId);
+    if (!active2) {
+      return { ok: false, message: "No preview is running \u2014 call start_preview first." };
+    }
+    if (!active2.inspector) {
+      return {
+        ok: false,
+        message: `Element highlighting needs the web inspector, which ${active2.framework} previews don't have.`
+      };
+    }
+    let payload;
+    if (input.clear === true) {
+      payload = { clear: true };
+    } else {
+      const selector = typeof input.selector === "string" ? input.selector.trim() : "";
+      if (!selector || selector.length > MAX_SELECTOR) {
+        return { ok: false, message: `selector must be a CSS selector of 1-${MAX_SELECTOR} characters.` };
+      }
+      const label = typeof input.label === "string" ? input.label.trim().slice(0, MAX_LABEL) : "";
+      payload = label ? { selector, label } : { selector };
+    }
+    const res = await postPreviewEvent({
+      sessionId: ctx.sessionId,
+      pluginId: ctx.pluginId,
+      pluginAuthToken: ctx.pluginAuthToken,
+      type: USER_EVENTS.PREVIEW_AGENT_HIGHLIGHT,
+      payload
+    });
+    if (!res.ok) {
+      return { ok: false, message: `Could not reach the app (${res.status}): ${res.message}` };
+    }
+    return {
+      ok: true,
+      message: payload.clear === true ? "Cleared your marks from the preview." : `Marked ${String(payload.selector)} in the user's preview. If the selector matches nothing, no mark appears.`
+    };
+  }
+  async stop() {
+    const ctx = this.ctx;
+    if (!ctx?.pluginAuthToken) return { ok: false, message: "The session is still starting." };
+    if (!activePreviews.has(ctx.sessionId)) return { ok: true, message: "No preview was running." };
+    await killPreview(ctx.sessionId);
+    resetBuildHealState(ctx.sessionId);
+    await postPreviewEvent({
+      sessionId: ctx.sessionId,
+      pluginId: ctx.pluginId,
+      pluginAuthToken: ctx.pluginAuthToken,
+      type: USER_EVENTS.PREVIEW_STOPPED,
+      payload: { reason: "user", origin: "agent" }
+    });
+    return { ok: true, message: "Preview stopped." };
+  }
+  // ─── Internals ─────────────────────────────────────────────────────────
+  async launch(ctx, pluginAuthToken, override) {
+    this.lastError = null;
+    const already = serving(ctx.sessionId);
+    if (already) {
+      await postPreviewEvent({
+        sessionId: ctx.sessionId,
+        pluginId: ctx.pluginId,
+        pluginAuthToken,
+        type: USER_EVENTS.PREVIEW_READY,
+        payload: {
+          url: already.url,
+          framework: already.framework,
+          port: already.detection.port,
+          origin: "agent"
+        }
+      });
+      return running(already, true);
+    }
+    void postPreviewEvent({
+      sessionId: ctx.sessionId,
+      pluginId: ctx.pluginId,
+      pluginAuthToken,
+      type: USER_EVENTS.PREVIEW_DETECTION_PENDING,
+      payload: { origin: "agent" }
+    });
+    const detection = (override && detectionFromOverride(override)) ?? await resolvePreviewDetection({ ctx, runtime: ctx.getRuntime(), pluginAuthToken, origin: "agent" });
+    if (!detection) {
+      const err2 = { stage: "detection", message: "Could not work out how to start this project." };
+      this.lastError = err2;
+      return { status: "error", ...err2 };
+    }
+    let failure = null;
+    await startPreviewFromDetection(ctx, detection, pluginAuthToken, {
+      origin: "agent",
+      onEvent: (type, payload) => {
+        if (type === USER_EVENTS.PREVIEW_ERROR) {
+          failure = {
+            stage: String(payload.stage ?? "spawn"),
+            message: String(payload.message ?? "The preview failed to start.")
+          };
+        }
+      }
+    });
+    const up = serving(ctx.sessionId);
+    if (up) return running(up, false);
+    const err = failure ?? { stage: "spawn", message: "The preview did not come up." };
+    this.lastError = err;
+    return { status: "error", ...err };
+  }
+  async handle(req, res) {
+    const reply = (code, body) => {
+      res.writeHead(code, { "content-type": "application/json" });
+      res.end(JSON.stringify(body));
+    };
+    if (!authorized(req.headers.authorization, this.token)) return reply(401, { error: "unauthorized" });
+    try {
+      const body = req.method === "POST" ? await readJson(req) : {};
+      switch (`${req.method} ${req.url}`) {
+        case "POST /preview/start":
+          return reply(200, await this.start(overrideFrom(body)));
+        case "GET /preview/status":
+          return reply(200, this.status());
+        case "POST /preview/highlight":
+          return reply(200, await this.highlight(body));
+        case "POST /preview/stop":
+          return reply(200, await this.stop());
+        default:
+          return reply(404, { error: "not found" });
+      }
+    } catch (err) {
+      log.warn("agent-preview", `bridge request failed: ${String(err)}`);
+      return reply(500, { error: err instanceof Error ? err.message : String(err) });
+    }
+  }
+};
+function serving(sessionId) {
+  const active2 = activePreviews.get(sessionId);
+  if (!active2 || active2.devServer && active2.devServer.exitCode !== null) return null;
+  return active2;
+}
+function running(active2, reused) {
+  return {
+    status: "running",
+    url: active2.url,
+    framework: active2.framework,
+    ...reused ? { reused: true } : {},
+    inspector: Boolean(active2.inspector)
+  };
+}
+function detectionFromOverride(o) {
+  if (!o.command || !Number.isInteger(o.port) || o.port <= 0 || o.port > 65535) return null;
+  return {
+    framework: o.framework?.trim() || "custom",
+    command: o.command,
+    args: Array.isArray(o.args) ? o.args.map(String) : [],
+    port: o.port,
+    // Any Local/ready/listening line; the TCP probe is the real fallback.
+    ready_pattern: o.ready_pattern?.trim() || "(ready|local:|listening|started server|compiled)"
+  };
+}
+function overrideFrom(body) {
+  if (typeof body.command !== "string" || typeof body.port !== "number") return void 0;
+  return {
+    command: body.command,
+    args: Array.isArray(body.args) ? body.args.map(String) : void 0,
+    port: body.port,
+    framework: typeof body.framework === "string" ? body.framework : void 0,
+    ready_pattern: typeof body.ready_pattern === "string" ? body.ready_pattern : void 0
+  };
+}
+function authorized(header, token) {
+  const presented = Buffer.from((header ?? "").replace(/^Bearer\s+/i, ""));
+  const expected = Buffer.from(token);
+  return presented.length === expected.length && (0, import_node_crypto10.timingSafeEqual)(presented, expected);
+}
+function readJson(req) {
+  return new Promise((resolve12, reject) => {
+    let raw = "";
+    req.setEncoding("utf8");
+    req.on("data", (chunk) => {
+      raw += chunk;
+      if (raw.length > 64e3) {
+        reject(new Error("body too large"));
+        req.destroy();
+      }
+    });
+    req.on("end", () => {
+      if (!raw) return resolve12({});
+      try {
+        const parsed = JSON.parse(raw);
+        resolve12(parsed && typeof parsed === "object" ? parsed : {});
+      } catch {
+        reject(new Error("invalid JSON"));
+      }
+    });
+    req.on("error", reject);
+  });
+}
+var agentPreviewBridge = new AgentPreviewBridge();
+
 // src/integrations/detect-stack.ts
 var import_node_fs13 = __toESM(require("fs"));
 var import_node_path13 = __toESM(require("path"));
@@ -40658,7 +41252,8 @@ async function integrationsSyncH(ctx) {
         sessionId: opts.sessionId,
         pluginId: opts.pluginId,
         pluginAuthToken: opts.pluginAuthToken,
-        pollSecret: opts.pollSecret
+        pollSecret: opts.pollSecret,
+        preview: agentPreviewBridge.address()
       })
     );
     const applied = await client3.reprovisionMcp(servers);
@@ -41295,7 +41890,7 @@ var AcpHistory = class {
       this.summary = trimmed.length > 120 ? trimmed.slice(0, 117) + "\u2026" : trimmed;
     }
     this.messages.push({
-      id: (0, import_node_crypto10.randomUUID)(),
+      id: (0, import_node_crypto11.randomUUID)(),
       role: "user",
       text,
       timestamp: Date.now(),
@@ -41311,7 +41906,7 @@ var AcpHistory = class {
   appendAgentReply(text, agentId = this.opts.agent) {
     if (text.length === 0) return;
     this.messages.push({
-      id: (0, import_node_crypto10.randomUUID)(),
+      id: (0, import_node_crypto11.randomUUID)(),
       role: "agent",
       text,
       timestamp: Date.now(),
@@ -44265,12 +44860,20 @@ async function start(requestedAgent, presetSession) {
       agent: isHouseProxyEnv(process.env) ? houseRailWireId(process.env) : session.agent
     });
   }
+  const previewBridge = await agentPreviewBridge.listen();
+  agentPreviewBridge.attach({
+    sessionId: session.id,
+    pluginId,
+    pluginAuthToken: session.pluginAuthToken ?? void 0,
+    getRuntime: () => createInteractiveAgentStrategy(session.agent, createOsStrategy())
+  });
   const mcpServers = mergeWithLocalMcpServers(
     buildMcpServersForStart({
       sessionId: session.id,
       pluginId,
       pluginAuthToken: session.pluginAuthToken ?? void 0,
-      pollSecret: session.pollSecret
+      pollSecret: session.pollSecret,
+      preview: previewBridge
     })
   );
   provisionSkillsForStart();
@@ -46853,7 +47456,7 @@ async function stopWorkspaceFromLocal(target) {
 var fs73 = __toESM(require("fs"));
 var os57 = __toESM(require("os"));
 var path87 = __toESM(require("path"));
-var import_node_crypto11 = require("crypto");
+var import_node_crypto12 = require("crypto");
 function sampleCpuTimes() {
   let idle = 0;
   let total = 0;
@@ -47005,8 +47608,8 @@ function resolveHostLabel(label) {
   return resolved.slice(0, 80);
 }
 async function redeemEnrollToken(token, label) {
-  const controlPollSecret = (0, import_node_crypto11.randomBytes)(32).toString("base64url");
-  const pluginSecretHash = (0, import_node_crypto11.createHash)("sha256").update(controlPollSecret).digest("hex");
+  const controlPollSecret = (0, import_node_crypto12.randomBytes)(32).toString("base64url");
+  const pluginSecretHash = (0, import_node_crypto12.createHash)("sha256").update(controlPollSecret).digest("hex");
   const data = await postJson("/api/self-hosted/redeem", {
     token,
     label: resolveHostLabel(label),
@@ -47865,7 +48468,7 @@ async function autoUpgradeBeforeCriticalCommand() {
   if (process.env.NODE_ENV === "test") return;
   if (process.env.CODEAM_DISABLE_UPDATE_CHECK === "1") return;
   if (process.env.CI) return;
-  const current2 = true ? "2.75.25" : null;
+  const current2 = true ? "2.75.26" : null;
   if (!current2) return;
   const cache = readCache();
   const fresh = cache && Date.now() - cache.fetchedAt < TTL_MS;
@@ -47882,7 +48485,7 @@ function checkForUpdates() {
   if (process.env.CODEAM_DISABLE_UPDATE_CHECK === "1") return;
   if (process.env.CI) return;
   if (!process.stdout.isTTY) return;
-  const current2 = true ? "2.75.25" : null;
+  const current2 = true ? "2.75.26" : null;
   if (!current2) return;
   const cache = readCache();
   const fresh = cache && Date.now() - cache.fetchedAt < TTL_MS;
@@ -47905,7 +48508,7 @@ var SELF_UPDATE_INSTALL_TIMEOUT_MS = 18e4;
 var SELF_UPDATE_LS_TIMEOUT_MS = 15e3;
 var SUDO_PREFLIGHT_TIMEOUT_MS = 5e3;
 function currentCliVersion() {
-  return true ? "2.75.25" : null;
+  return true ? "2.75.26" : null;
 }
 async function installedVersion(deps) {
   const ls = await deps.run(
@@ -49621,7 +50224,7 @@ async function invite() {
 // src/commands/doctor.ts
 var import_node_dns = require("dns");
 var import_node_util6 = require("util");
-var import_node_crypto12 = require("crypto");
+var import_node_crypto13 = require("crypto");
 var fs79 = __toESM(require("fs"));
 var path93 = __toESM(require("path"));
 var import_picocolors14 = __toESM(require("picocolors"));
@@ -49791,9 +50394,9 @@ function checkChokidar() {
 }
 async function doctor(args2 = []) {
   const json = args2.includes("--json");
-  const cliVersion = true ? "2.75.25" : "0.0.0-dev";
+  const cliVersion = true ? "2.75.26" : "0.0.0-dev";
   const apiBase2 = resolveApiBaseUrl();
-  const diagnosticId = (0, import_node_crypto12.randomUUID)();
+  const diagnosticId = (0, import_node_crypto13.randomUUID)();
   log.info("doctor", `run id=${diagnosticId} cli=${cliVersion}`);
   const [dns, health] = await Promise.all([
     checkDns(apiBase2),
@@ -50315,7 +50918,7 @@ async function mcpWarm(argv = [], opts = {}) {
 // src/commands/version.ts
 var import_picocolors15 = __toESM(require("picocolors"));
 function version2() {
-  const v = true ? "2.75.25" : "unknown";
+  const v = true ? "2.75.26" : "unknown";
   console.log(`${import_picocolors15.default.bold("codeam-cli")} ${import_picocolors15.default.cyan(v)}`);
 }
 
@@ -50516,6 +51119,9 @@ async function main() {
   if (command === "mcp-run") {
     return mcpRun(args);
   }
+  if (command === "preview-mcp") {
+    return previewMcp();
+  }
   if (command === "mcp-warm") {
     await mcpWarm(args);
     return;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "codeam-cli",
-  "version": "2.75.25",
+  "version": "2.75.26",
   "description": "Workflow-continuity bridge for AI coding agents. Wrap Claude Code or Codex in a PTY and supervise, approve, and redirect the session from any device — async. The terminal companion for CodeAgent Mobile.",
   "type": "commonjs",
   "main": "dist/index.js",