@notis_ai/cli 0.2.5 → 0.2.7

package/src/command-specs/tools.js

@@ -17,7 +17,7 @@ import {
   validateArguments,
 } from './helpers.js';
 
-async function resolveJsonInput(value, label) {
+export async function resolveJsonInput(value, label) {
   if (!value) return undefined;
 
   if (value === '-') {
@@ -39,6 +39,159 @@ async function resolveJsonInput(value, label) {
   return parseJson(value, label);
 }
 
+const READ_ACTIONS = new Set([
+  'CHECK',
+  'DESCRIBE',
+  'DOWNLOAD',
+  'FETCH',
+  'FIND',
+  'GET',
+  'INSPECT',
+  'LIST',
+  'LOOKUP',
+  'PREVIEW',
+  'QUERY',
+  'READ',
+  'SEARCH',
+  'STATUS',
+  'VERIFY',
+]);
+const WRITE_ACTIONS = new Set([
+  'AUTHENTIFY',
+  'CANCEL',
+  'CONNECT',
+  'COPY',
+  'CREATE',
+  'DELETE',
+  'DEPLOY',
+  'DISCARD',
+  'EDIT',
+  'GRANT',
+  'INCREMENT',
+  'INSERT',
+  'LINK',
+  'MOVE',
+  'POST',
+  'PUBLISH',
+  'REFUND',
+  'REMOVE',
+  'RENAME',
+  'SAVE',
+  'SEND',
+  'SUBMIT',
+  'UPDATE',
+  'UPLOAD',
+  'UPSERT',
+]);
+
+function splitSqlStatements(query) {
+  const statements = [];
+  let current = '';
+  let quote = null;
+  let dollarTag = null;
+  for (let index = 0; index < query.length; index += 1) {
+    const char = query[index];
+    if (dollarTag) {
+      if (query.startsWith(dollarTag, index)) {
+        current += dollarTag;
+        index += dollarTag.length - 1;
+        dollarTag = null;
+      } else {
+        current += char;
+      }
+      continue;
+    }
+    if (quote) {
+      current += char;
+      if (char === quote) {
+        if (query[index + 1] === quote) {
+          current += query[index + 1];
+          index += 1;
+        } else {
+          quote = null;
+        }
+      }
+      continue;
+    }
+    if (char === "'" || char === '"') {
+      quote = char;
+      current += char;
+      continue;
+    }
+    if (char === '$') {
+      const match = query.slice(index).match(/^\$(?:[A-Za-z_][A-Za-z0-9_]*)?\$/);
+      if (match) {
+        dollarTag = match[0];
+        current += dollarTag;
+        index += dollarTag.length - 1;
+        continue;
+      }
+    }
+    if (char === ';') {
+      if (current.trim()) statements.push(current.trim());
+      current = '';
+      continue;
+    }
+    current += char;
+  }
+  if (current.trim()) statements.push(current.trim());
+  return statements;
+}
+
+function classifySqlMutation(query) {
+  const statements = splitSqlStatements(query);
+  if (statements.length > 1) {
+    const classifications = statements.map(classifySqlMutation);
+    if (classifications.includes(true)) return true;
+    if (classifications.every((classification) => classification === false)) return false;
+    return null;
+  }
+  const statement = statements[0] || '';
+  if (statement) {
+    const normalizedStatement = statement.toUpperCase();
+    if (/^EXPLAIN\b/.test(normalizedStatement)) {
+      const executes = /^EXPLAIN\s+(?:\([^)]*\bANALYZE\b[^)]*\)\s*|ANALYZE\s+)/.test(normalizedStatement);
+      if (!executes) return false;
+      return /\b(ALTER|CREATE|DELETE|DROP|GRANT|INSERT|MERGE|REVOKE|TRUNCATE|UPDATE)\b/.test(normalizedStatement);
+    }
+    if (/^SHOW\b/.test(normalizedStatement)) return false;
+    // PostgreSQL SELECT can call side-effecting functions. Without catalog
+    // knowledge it is not provably read-only, so preserve idempotency and report
+    // an unknown classification instead of claiming mutating=false.
+    if (/^SELECT\b/.test(normalizedStatement)) return null;
+    if (/^WITH\b/.test(normalizedStatement)) {
+      return /\b(ALTER|CREATE|DELETE|DROP|GRANT|INSERT|MERGE|REVOKE|TRUNCATE|UPDATE)\b/.test(normalizedStatement)
+        ? true
+        : null;
+    }
+    if (/^(ALTER|CREATE|DELETE|DROP|GRANT|INSERT|MERGE|REVOKE|TRUNCATE|UPDATE)\b/.test(normalizedStatement)) {
+      return true;
+    }
+  }
+  return null;
+}
+
+export function classifyToolMutation(toolName, args = {}) {
+  const normalized = localNotisToolSlug(toolName).toUpperCase();
+  if (normalized.includes('EXECUTE_SQL') && typeof args.query === 'string') {
+    const query = args.query
+      .replace(/\/\*[\s\S]*?\*\//g, ' ')
+      .replace(/--[^\n]*/g, ' ')
+      .trim();
+    const sqlClassification = classifySqlMutation(query);
+    if (sqlClassification !== null) return sqlClassification;
+  }
+  if (/(?:^|_)(?:FIND|GET|LOOKUP|SEARCH)_OR_(?:CREATE|INSERT|SAVE|UPDATE|UPSERT)(?:_|$)/.test(normalized)) {
+    return true;
+  }
+  const tokens = normalized.split(/[^A-Z0-9]+/).filter(Boolean);
+  for (const token of tokens) {
+    if (WRITE_ACTIONS.has(token)) return true;
+    if (READ_ACTIONS.has(token)) return false;
+  }
+  return null;
+}
+
 const LONG_RUNNING_TOOL_TIMEOUT_MS = 600000;
 const LONG_RUNNING_TOOL_NAMES = new Set([
   'LOCAL_NOTIS_GENERATE_IMAGE_OPENAI',
@@ -67,7 +220,7 @@ function guessContentType(filePath) {
   return EXTENSION_CONTENT_TYPES.get(lower.slice(dotIndex)) || 'application/octet-stream';
 }
 
-async function hashFileSha256(localPath) {
+export async function hashFileSha256(localPath) {
   const hash = createHash('sha256');
   for await (const chunk of createReadStream(localPath)) {
     hash.update(chunk);
@@ -123,7 +276,7 @@ async function parseFileBindingSpec(spec, index) {
   };
 }
 
-async function parseFileBindings(rawFileOptions) {
+export async function parseFileBindings(rawFileOptions) {
   const values = Array.isArray(rawFileOptions)
     ? rawFileOptions
     : (rawFileOptions ? [rawFileOptions] : []);
@@ -227,7 +380,12 @@ async function toolsDescribeHandler(ctx) {
 
 async function toolsExecHandler(ctx) {
   const requestedToolName = localNotisToolSlug(ctx.args.toolName);
+  let targetMutating = classifyToolMutation(requestedToolName);
   ensureLongRunningToolTimeout(ctx, requestedToolName);
+  ctx.output.emitProgress({
+    phase: 'prepare',
+    message: `Resolving ${requestedToolName}`,
+  });
   const fileBindings = await parseFileBindings(ctx.options.file);
 
   if (ctx.options.getSchema) {
@@ -243,10 +401,16 @@ async function toolsExecHandler(ctx) {
     });
   }
 
-  const rawArguments = ctx.options.arguments || '{}';
+  if (ctx.options.argumentsFile && ctx.options.arguments) {
+    throw usageError('Use either --arguments or --arguments-file, not both.');
+  }
+  const rawArguments = ctx.options.argumentsFile
+    ? `@${ctx.options.argumentsFile}`
+    : (ctx.options.arguments || '{}');
   const args = rawArguments === '-' || rawArguments.startsWith('@')
     ? await resolveJsonInput(rawArguments, 'arguments') || {}
     : parseMaybeJson(rawArguments, 'arguments') || {};
+  targetMutating = classifyToolMutation(requestedToolName, args);
 
   if (ctx.options.dryRun) {
     if (fileBindings.length) {
@@ -278,6 +442,10 @@ async function toolsExecHandler(ctx) {
   }
 
   const idempotencyKey = nextIdempotencyKey(ctx.globalOptions);
+  ctx.output.emitProgress({
+    phase: 'execute',
+    message: `Calling ${requestedToolName}`,
+  });
 
   const result = await runToolCommand({
     runtime: ctx.runtime,
@@ -285,16 +453,26 @@ async function toolsExecHandler(ctx) {
     arguments_: {
       tools: [{ tool_slug: requestedToolName, arguments: args }],
     },
-    mutating: true,
-    idempotencyKey,
+    mutating: targetMutating !== false,
+    idempotencyKey: targetMutating === false ? null : idempotencyKey,
     fileBindings,
   });
+  ctx.output.emitProgress({
+    phase: 'complete',
+    message: `Finished ${requestedToolName}`,
+    requestId: result.requestId,
+  });
 
   return ctx.output.emitSuccess({
     command: ctx.spec.command_path.join(' '),
     data: result.payload,
     humanSummary: `Executed tool ${requestedToolName}`,
-    meta: { mutating: true, idempotency_key: idempotencyKey },
+    requestId: result.requestId,
+    meta: {
+      mutating: targetMutating,
+      mutation_classification: targetMutating === null ? 'unknown' : 'inferred',
+      idempotency_key: targetMutating === false ? null : idempotencyKey,
+    },
     renderHuman: () => JSON.stringify(result.payload, null, 2),
   });
 }
@@ -342,43 +520,48 @@ async function toolsExecParallelHandler(ctx) {
 }
 
 async function toolsLinkHandler(ctx) {
-  const apiBase = ctx.runtime.apiBase.replace(/\/+$/, '');
-  let portalBase;
-  try {
-    const parsed = new URL(apiBase);
-    if (parsed.hostname.startsWith('api.')) {
-      parsed.hostname = parsed.hostname.replace(/^api\./, 'app.');
-      portalBase = parsed.origin;
-    } else if (parsed.hostname === 'localhost' || parsed.hostname === '127.0.0.1') {
-      const apiPort = parseInt(parsed.port, 10) || 80;
-      parsed.port = String(apiPort === 3001 ? 3000 : apiPort);
-      portalBase = parsed.origin;
-    } else {
-      portalBase = apiBase;
-    }
-  } catch {
-    portalBase = apiBase.replace('api.', 'app.');
+  const credentials = ctx.options.credentials
+    ? await resolveJsonInput(ctx.options.credentials, 'credentials')
+    : undefined;
+  if (credentials !== undefined && (typeof credentials !== 'object' || credentials === null || Array.isArray(credentials))) {
+    throw usageError('credentials must be a JSON object');
+  }
+
+  const arguments_ = {
+    toolkit: ctx.args.toolkit,
+    ...(ctx.options.reconnect ? { reconnect: true } : {}),
+    ...(ctx.options.connectionId ? { reconnect_connection_id: ctx.options.connectionId } : {}),
+    ...(ctx.options.label ? { label: ctx.options.label } : {}),
+    ...(credentials ? { credentials } : {}),
+  };
+  const idempotencyKey = nextIdempotencyKey(ctx.globalOptions);
+  const result = await runToolCommand({
+    runtime: ctx.runtime,
+    toolName: 'LOCAL_NOTIS_AUTHENTIFY',
+    arguments_,
+    mutating: true,
+    idempotencyKey,
+  });
+  const payload = result.payload || {};
+  if (payload.status === 'error') {
+    throw usageError(payload.message || `Failed to connect ${ctx.args.toolkit}`, payload);
   }
-  const portalUrl = `${portalBase}/integrations?connect=${encodeURIComponent(ctx.args.toolkit)}`;
+  const authUrl = payload.redirect_url || payload.integrations_url || payload.url || null;
 
   return ctx.output.emitSuccess({
     command: ctx.spec.command_path.join(' '),
     data: {
-      toolkit: ctx.args.toolkit,
-      auth_url: portalUrl,
+      ...payload,
+      auth_url: authUrl,
     },
-    humanSummary: `Open this URL to connect ${ctx.args.toolkit}`,
+    humanSummary: ctx.options.reconnect
+      ? `Reconnected ${ctx.args.toolkit}`
+      : `Started connection for ${ctx.args.toolkit}`,
     hints: [
       { command: 'notis tools toolkits', reason: 'Verify the toolkit is connected after setup' },
     ],
-    renderHuman: () =>
-      [
-        `Connect ${ctx.args.toolkit}:`,
-        `  ${portalUrl}`,
-        '',
-        'After connecting, verify with:',
-        '  notis tools toolkits',
-      ].join('\n'),
+    meta: { mutating: true, idempotency_key: idempotencyKey },
+    renderHuman: () => JSON.stringify({ ...payload, auth_url: authUrl }, null, 2),
   });
 }
 
@@ -436,6 +619,7 @@ export const toolsCommandSpecs = [
       arguments: [{ token: '<tool-name>', description: 'Tool name returned by `notis tools search`.' }],
       options: [
         { flags: '--arguments <json>', description: 'JSON object, @file path, or - for stdin.' },
+        { flags: '--arguments-file <path>', description: 'Read the JSON arguments object from a file.' },
         { flags: '--file <argument-path=local-path>', description: 'Upload a local file into a file-uploadable tool argument. Repeatable.', collect: true },
         { flags: '--get-schema', description: 'Display the tool parameter schema without executing.' },
         { flags: '--dry-run', description: 'Validate arguments against the tool schema without executing.' },
@@ -447,6 +631,7 @@ export const toolsCommandSpecs = [
       'notis tools exec LOCAL_NOTIS_DATABASE_QUERY --get-schema',
       'notis tools exec LOCAL_NOTIS_DATABASE_QUERY --dry-run --arguments \'{"database_slug":"tasks","query":{}}\'',
       'notis tools exec LOCAL_NOTIS_DATABASE_QUERY --arguments @query.json',
+      'notis tools exec LOCAL_NOTIS_DATABASE_QUERY --arguments-file query.json',
       'notis tools exec LOCAL_NOTIS_DATABASE_QUERY --arguments - < query.json',
       'notis tools exec composio-dropbox-upload_file --arguments \'{"path":"/target/in/dropbox.pdf"}\' --file content=./Invoice.pdf',
     ],
@@ -481,19 +666,27 @@ export const toolsCommandSpecs = [
   },
   {
     command_path: ['tools', 'link'],
-    summary: 'Get the URL to connect an integration toolkit.',
-    when_to_use: 'Use this when a tool requires authentication with an external service.',
+    summary: 'Connect or reconnect an integration toolkit.',
+    when_to_use: 'Use this when a tool requires authentication or an active connection must be replaced.',
     args_schema: {
       arguments: [{ token: '<toolkit>', description: 'Toolkit name to connect (e.g. github, gmail, slack).' }],
-      options: [],
+      options: [
+        { flags: '--reconnect', description: 'Replace the existing account instead of adding another connection.' },
+        { flags: '--connection-id <id>', key: 'connectionId', description: 'Exact connection id to replace when multiple accounts exist.' },
+        { flags: '--label <label>', description: 'Account label for a new or replacement connection.' },
+        { flags: '--credentials <json>', description: 'Credential JSON object, @file path, or - for stdin. Prefer stdin so secrets do not enter shell history.' },
+      ],
     },
-    examples: ['notis tools link github', 'notis tools link gmail --json'],
-    output_schema: 'Returns the authentication URL for the specified toolkit.',
-    mutates: false,
-    idempotent: true,
-    require_auth: false,
+    examples: [
+      'notis tools link github',
+      'notis tools link dataforseo --reconnect --credentials - < credentials.json',
+    ],
+    output_schema: 'Returns the connection result and an authentication URL when provider authorization is still required.',
+    mutates: true,
+    idempotent: false,
+    require_auth: true,
     related_commands: ['notis tools toolkits', 'notis tools search <query>'],
-    backend_call: { type: 'local' },
+    backend_call: { type: 'tool', name: 'LOCAL_NOTIS_AUTHENTIFY' },
     handler: toolsLinkHandler,
   },
 ];

package/src/runtime/agent-browser.js

@@ -1,7 +1,118 @@
 import { spawn, spawnSync } from 'node:child_process';
-import { mkdirSync, writeFileSync } from 'node:fs';
+import { mkdirSync, readFileSync, writeFileSync } from 'node:fs';
 import { dirname } from 'node:path';
 
+export const HIDE_HARNESS_STATUS_SCRIPT =
+  "(() => { const el = document.getElementById('harness-status'); if (el) el.style.opacity = '0'; return true; })()";
+
+/**
+ * Prepare the mounted harness page for a listing capture: remove the debug
+ * banner and the layout the harness adds around the app (top padding for the
+ * banner, 100vh min-height) so content height can be measured and framed
+ * without artificial whitespace.
+ */
+const PREPARE_CAPTURE_SCRIPT =
+  "(() => { const s = document.getElementById('harness-status'); if (s) s.style.display = 'none';" +
+  " const r = document.getElementById('root'); if (r) { r.style.paddingTop = '0'; r.style.minHeight = '0'; }" +
+  " document.body.style.minHeight = '0'; document.documentElement.style.minHeight = '0'; return true; })()";
+
+const FONTS_STATUS_SCRIPT =
+  "(() => (document.fonts ? document.fonts.status : 'loaded'))()";
+
+const CONTENT_HEIGHT_SCRIPT =
+  '(() => { const r = document.getElementById(\'root\');' +
+  ' if (!r) return Math.ceil(document.documentElement.scrollHeight);' +
+  ' return Math.ceil(Math.max(r.scrollHeight, r.getBoundingClientRect().height)); })()';
+
+// CSS viewport bounds for content-aware framing. Content shorter than the
+// minimum gets a little breathing room; content taller than the maximum is
+// cropped at the frame rather than shrunk into unreadably small text.
+const MIN_CSS_VIEWPORT_HEIGHT = 720;
+const MAX_CSS_VIEWPORT_HEIGHT = 1500;
+
+function pngDimensions(path) {
+  try {
+    const buffer = readFileSync(path);
+    if (buffer.length < 24 || buffer.readUInt32BE(12) !== 0x49484452) {
+      return null;
+    }
+    return { width: buffer.readUInt32BE(16), height: buffer.readUInt32BE(20) };
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * Pick a CSS viewport that frames `contentHeight` at the output aspect ratio,
+ * with a deviceScaleFactor that maps it back to exactly outputWidth x
+ * outputHeight physical pixels. Width snaps to a multiple of 8 so the height
+ * stays integral for the common 16:10 target.
+ */
+function fitCssViewport(contentHeight, outputWidth, outputHeight) {
+  const aspect = outputWidth / outputHeight;
+  const cssH = Math.min(
+    MAX_CSS_VIEWPORT_HEIGHT,
+    Math.max(MIN_CSS_VIEWPORT_HEIGHT, Math.round(contentHeight)),
+  );
+  const cssW = Math.round((cssH * aspect) / 8) * 8;
+  return {
+    width: cssW,
+    height: Math.round(cssW / aspect),
+    scale: outputWidth / cssW,
+  };
+}
+
+async function evalNumber(sessionName, script, fallback = null) {
+  const result = await runAgentBrowser(
+    ['--session', sessionName, '--json', 'eval', script],
+    { timeoutMs: 5000 },
+  );
+  if (result.exitCode !== 0) {
+    return fallback;
+  }
+  try {
+    const payload = parseAgentBrowserJson(result.stdout);
+    const raw = payload?.data?.result ?? payload?.result ?? payload?.data ?? null;
+    const value = typeof raw === 'string' ? JSON.parse(raw) : raw;
+    return Number.isFinite(value) ? value : fallback;
+  } catch {
+    return fallback;
+  }
+}
+
+async function waitForFonts(sessionName, timeoutMs = 3000) {
+  const deadline = Date.now() + timeoutMs;
+  while (Date.now() < deadline) {
+    const result = await runAgentBrowser(
+      ['--session', sessionName, '--json', 'eval', FONTS_STATUS_SCRIPT],
+      { timeoutMs: 5000 },
+    );
+    if (result.exitCode !== 0) {
+      return;
+    }
+    try {
+      const payload = parseAgentBrowserJson(result.stdout);
+      const raw = payload?.data?.result ?? payload?.result ?? payload?.data ?? null;
+      const status = typeof raw === 'string' && raw.startsWith('"') ? JSON.parse(raw) : raw;
+      if (status !== 'loading') {
+        return;
+      }
+    } catch {
+      return;
+    }
+    await delay(150);
+  }
+}
+
+async function setViewport(sessionName, width, height, scale = null) {
+  const args = ['--session', sessionName, 'set', 'viewport', String(width), String(height)];
+  if (scale != null) {
+    args.push(String(scale));
+  }
+  const result = await runAgentBrowser(args, { timeoutMs: 5000 });
+  return result.exitCode === 0;
+}
+
 function delay(ms) {
   return new Promise((resolvePromise) => setTimeout(resolvePromise, ms));
 }
@@ -186,13 +297,18 @@ export async function runHarnessRoute({
 
 /**
  * Open a harness route, wait for it to mount, then capture a PNG screenshot of
- * the rendered app at a fixed viewport (default 2000x1250, the 16:10 the
- * listing validator expects). Used by `notis apps screenshot`.
+ * the rendered app. Output is always exactly `width` x `height` physical
+ * pixels (default 2000x1250, the 16:10 the listing validator expects), but the
+ * CSS viewport is fitted to the rendered content height: short pages render
+ * larger (no dead whitespace below the app), tall pages get more room before
+ * cropping. The deviceScaleFactor maps the fitted CSS viewport back onto the
+ * fixed output frame. Used by `notis apps screenshot`.
  */
 export async function captureHarnessScreenshot({
   url,
   sessionName,
   screenshotPath,
+  focusSelector = null,
   width = 2000,
   height = 1250,
   timeoutMs = 15_000,
@@ -204,12 +320,20 @@ export async function captureHarnessScreenshot({
     return { ok: false, mounted: false, screenshotPath: null, tool_error: commandError('open', opened) };
   }
 
-  // Fixed viewport so every screenshot is the same frame, regardless of the
-  // operator's screen. React re-layouts on the resize before we capture.
-  await runAgentBrowser(
-    ['--session', sessionName, 'set', 'viewport', String(width), String(height)],
-    { timeoutMs: 5000 },
+  // Initial fixed frame so mount/layout happen at a deterministic size; the
+  // scale keeps physical output at width x height from the very first paint.
+  const initial = fitCssViewport(900, width, height);
+  let scaledViewport = await setViewport(
+    sessionName,
+    initial.width,
+    initial.height,
+    initial.scale,
   );
+  if (!scaledViewport) {
+    // Older agent-browser without deviceScaleFactor support: fall back to a
+    // plain fixed viewport at output size.
+    await setViewport(sessionName, width, height);
+  }
 
   const deadline = Date.now() + timeoutMs;
   let lastErrors = [];
@@ -247,30 +371,89 @@ export async function captureHarnessScreenshot({
     };
   }
 
-  // Hide the harness debug banner so it never appears in the listing image.
+  // Strip harness chrome (debug banner, banner padding, 100vh min-height) so
+  // the frame contains only the app, then wait for webfonts before measuring.
   await runAgentBrowser(
-    [
-      '--session',
-      sessionName,
-      'eval',
-      "(() => { const el = document.getElementById('harness-status'); if (el) el.style.display = 'none'; return true; })()",
-    ],
+    ['--session', sessionName, 'eval', PREPARE_CAPTURE_SCRIPT],
     { timeoutMs: 5000 },
   );
+  await waitForFonts(sessionName);
+
+  // Fit the CSS viewport to the rendered content. Content height depends on
+  // viewport width, so refine once after the first resize reflows the page.
+  let framing = null;
+  if (scaledViewport) {
+    let contentHeight = await evalNumber(sessionName, CONTENT_HEIGHT_SCRIPT);
+    for (let pass = 0; contentHeight != null && pass < 2; pass += 1) {
+      const fitted = fitCssViewport(contentHeight, width, height);
+      if (framing && fitted.width === framing.width) {
+        break;
+      }
+      scaledViewport = await setViewport(sessionName, fitted.width, fitted.height, fitted.scale);
+      if (!scaledViewport) {
+        framing = null;
+        await setViewport(sessionName, width, height);
+        break;
+      }
+      framing = { ...fitted, content_height: contentHeight };
+      await delay(150);
+      const remeasured = await evalNumber(sessionName, CONTENT_HEIGHT_SCRIPT);
+      if (remeasured == null || Math.abs(remeasured - contentHeight) <= 32) {
+        framing.content_height = remeasured ?? contentHeight;
+        break;
+      }
+      contentHeight = remeasured;
+    }
+  }
 
-  // Let the route settle (fonts, async data) before the capture.
+  // Let the route settle (async data, resize transitions) before the capture.
   await delay(500);
 
   mkdirSync(dirname(screenshotPath), { recursive: true });
-  const shot = await runAgentBrowser(
-    ['--session', sessionName, 'screenshot', screenshotPath, '--screenshot-format', 'png'],
-    { timeoutMs: 15_000 },
-  );
+  const screenshotArgs = ['--session', sessionName, 'screenshot'];
+  if (focusSelector) {
+    screenshotArgs.push(focusSelector);
+  }
+  screenshotArgs.push(screenshotPath, '--screenshot-format', 'png');
+  const shot = await runAgentBrowser(screenshotArgs, { timeoutMs: 15_000 });
   if (shot.exitCode !== 0) {
     return { ok: false, mounted: true, screenshotPath: null, errors: lastErrors, timed_out: false, tool_error: commandError('screenshot', shot) };
   }
 
-  return { ok: true, mounted: true, screenshotPath, errors: lastErrors, timed_out: false, tool_error: null };
+  // The listing validator requires exact output dimensions. If the fitted
+  // capture came out wrong (e.g. the browser ignored the scale factor),
+  // recapture once at a plain fixed viewport.
+  const dimensions = pngDimensions(screenshotPath);
+  if (!focusSelector && framing && (!dimensions || dimensions.width !== width || dimensions.height !== height)) {
+    await setViewport(sessionName, width, height);
+    await delay(300);
+    const retry = await runAgentBrowser(
+      ['--session', sessionName, 'screenshot', screenshotPath, '--screenshot-format', 'png'],
+      { timeoutMs: 15_000 },
+    );
+    if (retry.exitCode !== 0) {
+      return { ok: false, mounted: true, screenshotPath: null, errors: lastErrors, timed_out: false, tool_error: commandError('screenshot', retry) };
+    }
+    framing = null;
+  }
+
+  if (focusSelector) {
+    framing = {
+      ...(framing || {}),
+      focus_selector: focusSelector,
+      source_dimensions: dimensions,
+    };
+  }
+
+  return {
+    ok: true,
+    mounted: true,
+    screenshotPath,
+    errors: lastErrors,
+    timed_out: false,
+    tool_error: null,
+    framing,
+  };
 }
 
 export async function closeAgentBrowserSession(sessionName) {