synabun 1.3.0 → 2.0.0

package/mcp-server/src/tools/browser-interact.ts

@@ -1,255 +1,362 @@
-import { z } from 'zod';
-import * as ni from '../services/neural-interface.js';
-import { text } from './response.js';
-
-function formatClickHints(result: Record<string, unknown>): string {
-  const hints = result.hints as Array<{ role: string; text: string; ariaLabel: string; placeholder: string }> | undefined;
-  if (!hints?.length) return '';
-  let msg = '\n\nVisible interactive elements on page:';
-  for (const h of hints) {
-    const label = h.ariaLabel || h.text || h.placeholder || '(unnamed)';
-    msg += `\n- ${h.role}: "${label.substring(0, 60)}"`;
-  }
-  msg += '\n\nUse browser_snapshot for full page structure.';
-  return msg;
-}
-
-// ── browser_click ──
-
-export const browserClickSchema = {
-  selector: z.string().describe('Playwright selector for the element to click. Use CSS selectors (e.g. "button.submit", "#login"), text selectors (e.g. \'text="Sign in"\'), or Playwright extensions like \'button:has-text("Retry")\'. NEVER use :contains() — use :has-text() instead.'),
-  nthMatch: z.coerce.number().int().min(0).optional().describe('If the selector matches multiple elements, click the Nth one (0-indexed). Facebook: composer trigger appears in sidebar + main — use nthMatch: 0 to click the first match.'),
-  sessionId: z.string().optional().describe('Browser session ID. If omitted, auto-selects the only open session.'),
-};
-
-export const browserClickDescription =
-  'Click an element on the page. Accepts Playwright selectors: CSS selectors, text="...", :has-text("..."), role=button[name="..."], or [data-testid="..."]. Use browser_snapshot first to identify interactive elements. ' +
-  'Twitter/X stable selectors: [data-testid="tweetButton"] (post), [data-testid="like"], [data-testid="retweet"], [data-testid="reply"], [data-testid="SideNav_NewTweet_Button"] (compose FAB). ' +
-  'Facebook: [role="button"][aria-label="Curtir"] (PT like), [role="button"][aria-label="Like"] (EN), [role="button"][aria-label="Beğen"] (TR), [role="button"][aria-label*="Compartilhar"] (PT share), [role="button"][aria-label*="Share"] (EN share). ' +
-  'Facebook composer trigger: scope to [role="main"] div[role="button"]:has-text("Escreva algo") (PT) / :has-text("Write something") (EN) / :has-text("Bir şeyler yaz") (TR), or pass nthMatch: 0 on the unscoped selector. ' +
-  'Facebook post submit: [role="dialog"] [role="button"]:has-text("Publicar") (PT) / :has-text("Post") (EN) / :has-text("Paylaş") (TR). ' +
-  'TikTok main app — Like: button[aria-label*="Curtir vídeo"] (PT) / button[aria-label*="Like video"] (EN). ' +
-  'Comments: button[aria-label*="comentário"] (PT) / button[aria-label*="Read or add comments"] (EN) / button[aria-label*="comment"] (EN fallback). NOTE: On For You feed multiple articles are loaded — use nthMatch: 0 to target the first visible video. Prefer navigating directly to tiktok.com/@user/video/ID to avoid CAPTCHA. ' +
-  'Share: button[aria-label*="Compartilhar vídeo"] (PT) / button[aria-label*="Share video"] (EN). ' +
-  'Upload nav: [data-e2e="nav-upload"]. ' +
-  'Follow from For You feed: [data-e2e="feed-follow"] (the + icon on avatar — no nthMatch needed). ' +
-  'Follow from profile page: button:has-text("Seguir") nthMatch:0 (matches many sidebar items — always use nthMatch:0). ' +
-  'NOTE: button[data-e2e="follow-button"] does NOT work on video pages — use feed-follow or navigate to profile. ' +
-  'Like a comment: use browser_evaluate to call row.querySelector("[class*=DivLikeContainer]").click() — standard browser_click on [data-e2e="like-icon"] targets video likes and may navigate away. ' +
-  'TikTok Studio — edit post: [data-tt="components_ActionCell_Clickable"] (first in row = edit pencil). ' +
-  'Privacy dropdown: [data-tt="components_PrivacyCell_TUXButton"]. ' +
-  'Studio upload: button:has-text("Selecionar vídeo") then use browser_upload for file. ' +
-  'TikTok open comment panel: click [data-e2e="comment-input"] (outer container — activates the panel). Comment submit: [data-e2e="comment-post"]. Notifications: [data-e2e="nav-activity"]. Profile nav: [data-e2e="nav-profile"]. ' +
-  'WhatsApp Web — open chat: click span[title="Chat Name"] in the sidebar. Send message: button[aria-label="Enviar"] (appears after typing). ' +
-  'Attach menu: button[aria-label="Anexar"] → then [role="menuitem"][aria-label="Documento"] / [aria-label="Fotos e vídeos"] / [aria-label="Câmera"] / [aria-label="Contato"] / [aria-label="Enquete"]. ' +
-  'Emoji: button[aria-label="Emojis, GIFs, figurinhas"]. Voice: button[aria-label="Mensagem de voz"]. Search in chat: button[aria-label="Pesquisar"]. ' +
-  'Nav: button[aria-label="Conversas"] / button[aria-label="Atualizações no status"] / button[aria-label="Canais"] / button[aria-label="Configurações"]. ' +
-  'New chat: button[aria-label="Nova conversa"]. Header more options: button[aria-label="Mais opções"][data-tab="6"]. ' +
-  'Status — add text: button[aria-label="Add Status"] → [role="menuitem"][aria-label="Texto"]. Status send: [aria-label="Enviar"]. Close status: button[aria-label="Fechar janela de post de status"]. ' +
-  'Instagram — Like: [role="button"]:has(svg[aria-label="Curtir"]) (PT) / [role="button"]:has(svg[aria-label="Like"]) (EN). ' +
-  'Comment button: [role="button"]:has(svg[aria-label="Comentar"]) (PT) / [role="button"]:has(svg[aria-label="Comment"]) (EN). ' +
-  'Share: [role="button"]:has(svg[aria-label="Compartilhar"]) (PT) / [role="button"]:has(svg[aria-label="Share"]) (EN). ' +
-  'Save: [role="button"]:has(svg[aria-label="Salvar"]) (PT) / [role="button"]:has(svg[aria-label="Save"]) (EN). ' +
-  'Follow: div:has-text("Seguir") (PT) / div:has-text("Follow") (EN) — use nthMatch:0 as multiple matches exist. ' +
-  'More options: [role="button"]:has(svg[aria-label="Mais opções"]) (PT) / [role="button"]:has(svg[aria-label="More options"]) (EN). ' +
-  'Sidebar nav: svg[aria-label="Pesquisa"] (search), svg[aria-label="Novo post"] (new post), svg[aria-label="Notificações"] (notifications), svg[aria-label="Mensagens"] (DM). ' +
-  'On single post pages: comment input is a textarea inside form, not contenteditable — submit comment by pressing Enter after typing. ' +
-  'Reels: scroll down to advance to next reel. Engagement buttons on the right sidebar. ' +
-  'Emoji picker: [role="button"]:has(svg[aria-label="Emoji"]). ' +
-  'LinkedIn — Like: button[aria-label="Reagir com gostei"] (PT) / button[aria-label="React with Like"] (EN). ' +
-  'Reactions menu: button[aria-label="Abrir menu de reações"] (PT) / button[aria-label="Open reactions menu"] (EN). ' +
-  'Comment: button[aria-label="Comentar"] (PT) / button[aria-label="Comment"] (EN). ' +
-  'Share dropdown: the Compartilhar/Share button is an artdeco-dropdown trigger. ' +
-  'Send via DM: button[aria-label="Enviar em mensagem privada"] (PT) / button[aria-label="Send in private message"] (EN). ' +
-  'Post composer trigger: button:has-text("Comece uma publicação") (PT) / button:has-text("Start a post") (EN). ' +
-  'Post composer editor: [role="dialog"] .ql-editor[role="textbox"] — use browser_fill to enter text. ' +
-  'Post submit: [role="dialog"] .share-actions__primary-action (Publicar/Post button — disabled until text entered). ' +
-  'Schedule post: [role="dialog"] button[aria-label="Agendar publicação"] (PT) / button[aria-label="Schedule post"] (EN). ' +
-  'Add media: [role="dialog"] button[aria-label="Adicionar mídia"] (PT) / button[aria-label="Add media"] (EN). ' +
-  'Close dialog: button[aria-label="Fechar"] nthMatch:0. ' +
-  'Comment input on post page: .ql-editor[role="textbox"] — use browser_fill then browser_press Enter to submit. ' +
-  'Follow: button:has-text("+ Seguir") (PT) / button:has-text("+ Follow") (EN) — use nthMatch:0. ' +
-  'Connect: button:has-text("Conectar") (PT) / button:has-text("Connect") (EN). ' +
-  'Messaging compose: .msg-form__contenteditable — use browser_fill to type, then click .msg-form__send-button to send. ' +
-  'Nav: a[href*="/feed/"] (Home), a[href*="/mynetwork/"] (Network), a[href*="/jobs/"] (Jobs), a[href*="/messaging/"] (Messages), a[href*="/notifications/"] (Notifications).'
-
-export async function handleBrowserClick(args: { selector: string; nthMatch?: number; sessionId?: string }) {
-  const resolved = await ni.resolveSession(args.sessionId);
-  if ('error' in resolved) return text(resolved.error);
-
-  const result = await ni.click(resolved.sessionId, args.selector, args.nthMatch);
-  if (result.error) return text(`Click failed: ${result.error}${formatClickHints(result)}`);
-
-  return text(`Clicked "${args.selector}" — now at ${result.url} "${result.title}"`);
-}
-
-// ── browser_fill ──
-
-export const browserFillSchema = {
-  selector: z.string().describe('Playwright selector for the input/textarea to fill (e.g. "input[name=\'email\']", "#search-box", \'input:has-text("Search")\').'),
-  value: z.string().describe('The text value to fill into the element. Clears existing content first.'),
-  nthMatch: z.coerce.number().int().min(0).optional().describe('If the selector matches multiple elements, fill the Nth one (0-indexed).'),
-  sessionId: z.string().optional().describe('Browser session ID. If omitted, auto-selects the only open session.'),
-};
-
-export const browserFillDescription =
-  'Clear an input field and fill it with new text. Accepts Playwright selectors: CSS, text="...", :has-text("..."), [data-testid="..."]. Twitter/X: compose box is [data-testid="tweetTextarea_0"], search is [data-testid="SearchBox_Search_Input"]. TikTok search: [data-e2e="search-user-input"]. WhatsApp search: input[aria-label="Pesquisar ou começar uma nova conversa"]. ' +
-  'Instagram: comment box is textarea[aria-label="Adicione um comentário..."] (PT) / textarea[aria-label="Add a comment…"] (EN). Use browser_fill for comment text, then press Enter to submit.';
-
-export async function handleBrowserFill(args: { selector: string; value: string; nthMatch?: number; sessionId?: string }) {
-  const resolved = await ni.resolveSession(args.sessionId);
-  if ('error' in resolved) return text(resolved.error);
-
-  const result = await ni.fill(resolved.sessionId, args.selector, args.value, args.nthMatch);
-  if (result.error) return text(`Fill failed: ${result.error}${formatClickHints(result)}`);
-
-  const location = result.url ? ` — ${result.url} "${result.title}"` : '';
-  return text(`Filled "${args.selector}" with "${args.value.slice(0, 100)}"${location}`);
-}
-
-// ── browser_type ──
-
-export const browserTypeSchema = {
-  selector: z.string().optional().describe('Playwright selector for the element to type into. If omitted, types into the currently focused element using keyboard events.'),
-  text: z.string().describe('The text to type character by character (appends to existing content).'),
-  nthMatch: z.coerce.number().int().min(0).optional().describe('If the selector matches multiple elements, type into the Nth one (0-indexed). Twitter/X reply dialog has 2 tweetTextarea_0 elements — use nthMatch to disambiguate.'),
-  sessionId: z.string().optional().describe('Browser session ID. If omitted, auto-selects the only open session.'),
-};
-
-export const browserTypeDescription =
-  'Type text character by character (simulates real keystrokes, appends to existing content). Provide a selector to target an element, or omit to type into whatever is currently focused. ' +
-  'Prefer browser_type over browser_fill for contenteditable editors — both Twitter/X ([data-testid="tweetTextarea_0"]) and Facebook use them. ' +
-  'Facebook post composer (after opening dialog): [role="dialog"] [role="textbox"]. ' +
-  'Facebook comment boxes: [contenteditable][aria-label*="Comente como"] (PT), [contenteditable][aria-label*="Comment as"] (EN), [contenteditable][aria-label*="Yorum yap"] (TR). ' +
-  'TikTok comment flow: 1) Navigate directly to tiktok.com/@user/video/ID (avoids CAPTCHA from feed). 2) Click [data-e2e="comment-input"] to open/activate the comment panel. 3) Type into [data-e2e="comment-text"] div[contenteditable="true"] (DraftJS editor — NOT [data-e2e="comment-input"] which is a non-editable wrapper; use browser_evaluate with execCommand for longer text). 4) Submit with [data-e2e="comment-post"]. ' +
-  'From For You feed: comment button needs nthMatch: 0 (multiple articles loaded). Direct video URL is safer to avoid CAPTCHA. ' +
-  'WhatsApp message compose: div[role="textbox"][contenteditable="true"] (aria-label is "Digitar na conversa com [Name]" or "Digitar no grupo [Name]"). ' +
-  'WhatsApp status text composer: .lexical-rich-text-input div[contenteditable="true"]. ' +
-  'Instagram: Comment on post pages uses a native textarea (NOT contenteditable) — use browser_fill instead of browser_type. For DMs, navigate to instagram.com/direct/inbox/ first. Search: click svg[aria-label="Pesquisa"] in sidebar to open search panel, then type in the input that appears.';
-
-export async function handleBrowserType(args: { selector?: string; text: string; nthMatch?: number; sessionId?: string }) {
-  const resolved = await ni.resolveSession(args.sessionId);
-  if ('error' in resolved) return text(resolved.error);
-
-  const result = await ni.type(resolved.sessionId, args.selector ?? null, args.text, args.nthMatch);
-  if (result.error) return text(`Type failed: ${result.error}${formatClickHints(result)}`);
-
-  const target = args.selector ? `"${args.selector}"` : 'focused element';
-  const location = result.url ? ` — ${result.url} "${result.title}"` : '';
-  return text(`Typed "${args.text.slice(0, 100)}" into ${target}${location}`);
-}
-
-// ── browser_hover ──
-
-export const browserHoverSchema = {
-  selector: z.string().describe('Playwright selector for the element to hover over (CSS, text="...", :has-text("...")).'),
-  nthMatch: z.coerce.number().int().min(0).optional().describe('If the selector matches multiple elements, hover over the Nth one (0-indexed).'),
-  sessionId: z.string().optional().describe('Browser session ID. If omitted, auto-selects the only open session.'),
-};
-
-export const browserHoverDescription =
-  'Hover over an element. Useful for revealing dropdowns, tooltips, or hover-triggered content. Accepts Playwright selectors.';
-
-export async function handleBrowserHover(args: { selector: string; nthMatch?: number; sessionId?: string }) {
-  const resolved = await ni.resolveSession(args.sessionId);
-  if ('error' in resolved) return text(resolved.error);
-
-  const result = await ni.hover(resolved.sessionId, args.selector, args.nthMatch);
-  if (result.error) return text(`Hover failed: ${result.error}${formatClickHints(result)}`);
-
-  const location = result.url ? ` — ${result.url} "${result.title}"` : '';
-  return text(`Hovered over "${args.selector}"${location}`);
-}
-
-// ── browser_select ──
-
-export const browserSelectSchema = {
-  selector: z.string().describe('Playwright selector for the <select> element.'),
-  value: z.string().describe('The option value to select.'),
-  nthMatch: z.coerce.number().int().min(0).optional().describe('If the selector matches multiple elements, select from the Nth one (0-indexed).'),
-  sessionId: z.string().optional().describe('Browser session ID. If omitted, auto-selects the only open session.'),
-};
-
-export const browserSelectDescription =
-  'Select an option from a <select> dropdown by CSS selector and option value.';
-
-export async function handleBrowserSelect(args: { selector: string; value: string; nthMatch?: number; sessionId?: string }) {
-  const resolved = await ni.resolveSession(args.sessionId);
-  if ('error' in resolved) return text(resolved.error);
-
-  const result = await ni.selectOption(resolved.sessionId, args.selector, args.value, args.nthMatch);
-  if (result.error) return text(`Select failed: ${result.error}${formatClickHints(result)}`);
-
-  const location = result.url ? ` — ${result.url} "${result.title}"` : '';
-  return text(`Selected "${args.value}" in "${args.selector}"${location}`);
-}
-
-// ── browser_press ──
-
-export const browserPressSchema = {
-  key: z.string().describe('Key or key combo to press (e.g. "Enter", "Tab", "Control+A", "Escape", "ArrowDown").'),
-  sessionId: z.string().optional().describe('Browser session ID. If omitted, auto-selects the only open session.'),
-};
-
-export const browserPressDescription =
-  'Press a keyboard key or key combination. Supports modifiers like Control+A, Shift+Enter, etc.';
-
-export async function handleBrowserPress(args: { key: string; sessionId?: string }) {
-  const resolved = await ni.resolveSession(args.sessionId);
-  if ('error' in resolved) return text(resolved.error);
-
-  const result = await ni.pressKey(resolved.sessionId, args.key);
-  if (result.error) return text(`Press failed: ${result.error}`);
-
-  const location = result.url ? ` — ${result.url} "${result.title}"` : '';
-  return text(`Pressed "${args.key}"${location}`);
-}
-
-// ── browser_scroll ──
-
-export const browserScrollSchema = {
-  direction: z.enum(['up', 'down', 'left', 'right']).describe('Direction to scroll.'),
-  distance: z.coerce.number().optional().describe('Pixels to scroll (default: 500).'),
-  selector: z.string().optional().describe('Scroll within a specific element instead of the page. Twitter: [data-testid="primaryColumn"] for main feed. Facebook: [role="feed"] for group/page post feed. TikTok: [data-e2e="comment-list"] for comment panel, [data-tt="components_PostTable_Container"] for Studio content table. WhatsApp: [aria-label="Lista de conversas"] for chat list sidebar, [role="application"] or the main chat panel for message history.'),
-  sessionId: z.string().optional().describe('Browser session ID. If omitted, auto-selects the only open session.'),
-};
-
-export const browserScrollDescription =
-  'Scroll the page or a specific element. Essential for infinite scroll feeds. Twitter/X: direction "down" with distance 800–1500 to load more tweets. Facebook: use selector "[role=\\"feed\\"]" to scroll within the post feed. TikTok feed: scroll "down" 800–1000px to advance to the next video. TikTok comment panel: use selector "[data-e2e=\\"comment-list\\"]". TikTok Studio table: use selector "[data-tt=\\"components_PostTable_Container\\"]". WhatsApp chat list: use selector "[aria-label=\\"Lista de conversas\\"]". WhatsApp message history: scroll "up" to load older messages. ' +
-  'Instagram: Home feed — scroll down 800–1200px to load more posts. Profile grid — scroll down to load more posts. Reels — scroll down 800px to advance to next reel. Post page comments — scroll within the comment panel to load older comments. Explore page — scroll down to load more grid posts. ' +
-  'LinkedIn: Feed — scroll down 800–1200px to load more posts. Profile — scroll down to load more sections. Notifications — scroll down for older notifications. Messaging conversations sidebar — scroll within .msg-conversations-container. Search results — scroll down for more results. My Network suggestions — scroll down for more people to follow/connect.';
-
-export async function handleBrowserScroll(args: { direction: string; distance?: number; selector?: string; sessionId?: string }) {
-  const resolved = await ni.resolveSession(args.sessionId);
-  if ('error' in resolved) return text(resolved.error);
-
-  const result = await ni.scroll(resolved.sessionId, { direction: args.direction, distance: args.distance, selector: args.selector });
-  if (result.error) return text(`Scroll failed: ${result.error}`);
-
-  const target = args.selector ? `"${args.selector}"` : 'page';
-  return text(`Scrolled ${args.direction} ${args.distance ?? 500}px in ${target} — now at ${result.url} "${result.title}"`);
-}
-
-// ── browser_upload ──
-
-export const browserUploadSchema = {
-  selector: z.string().describe('Playwright selector for the file input element. Twitter: \'input[data-testid="fileInput"]\'.'),
-  filePaths: z.array(z.string()).describe('Absolute file paths to upload. Twitter supports up to 4 images or 1 video per tweet.'),
-  nthMatch: z.coerce.number().int().min(0).optional().describe('If the selector matches multiple file inputs, upload to the Nth one (0-indexed).'),
-  sessionId: z.string().optional().describe('Browser session ID. If omitted, auto-selects the only open session.'),
-};
-
-export const browserUploadDescription =
-  'Upload one or more files via a file input element. For Twitter/X: click the media button first to reveal the hidden file input, then use selector \'input[data-testid="fileInput"]\'. ' +
-  'TikTok Studio: click button:has-text("Selecionar vídeo") first, then use selector \'input[type="file"]\' — supports a single video file. ' +
-  'Instagram: Click svg[aria-label="Novo post"] in sidebar to open the create dialog, then use browser_upload on the file input that appears. Supports images and videos.';
-
-export async function handleBrowserUpload(args: { selector: string; filePaths: string[]; nthMatch?: number; sessionId?: string }) {
-  const resolved = await ni.resolveSession(args.sessionId);
-  if ('error' in resolved) return text(resolved.error);
-
-  const result = await ni.upload(resolved.sessionId, args.selector, args.filePaths, args.nthMatch);
-  if (result.error) return text(`Upload failed: ${result.error}${formatClickHints(result)}`);
-
-  return text(`Uploaded ${args.filePaths.length} file(s) via "${args.selector}" — now at ${result.url} "${result.title}"`);
-}
+import { z } from 'zod';
+import * as ni from '../services/neural-interface.js';
+import { text } from './response.js';
+import { formatInlineSnapshot, formatAiSnapshotBody } from './browser-observe.js';
+import * as assist from '../services/browser-assist.js';
+
+const returnSnapshotField = z.object({
+  mode: z.enum(['full', 'interactive', 'landmarks']).optional(),
+  selector: z.string().optional(),
+  viewport: z.boolean().optional(),
+  maxChars: z.number().int().positive().optional(),
+  format: z.enum(['text', 'json']).optional(),
+}).optional().describe('Legacy inline snapshot (tree modes). Prefer the "snapshot" param, which returns ref-based AI snapshots.');
+
+const tabIdField = z.string().optional().describe('Target a specific tab within the session. Auto-resolved from environment if omitted.');
+
+const refField = z.string().optional().describe('Element ref from browser_snapshot, e.g. "e12". Preferred over selector — exact match, no guessing.');
+
+const selectorField = (what: string) => z.string().optional().describe(
+  `Playwright selector for ${what} (CSS, text="...", :has-text("..."), role=..., [data-testid="..."]). Fallback when you have no ref. NEVER use :contains().`
+);
+
+// Auto inline AI snapshots after click/navigate can be disabled globally for
+// legacy loop automations that expect terse action responses.
+export function autosnapshotEnabled(): boolean {
+  return process.env.SYNABUN_BROWSER_AUTOSNAPSHOT !== '0';
+}
+
+const CLICK_SNAPSHOT_MAX_CHARS = 6000;
+
+function formatClickHints(result: Record<string, unknown>): string {
+  const hints = result.hints as Array<{ role: string; text: string; ariaLabel: string; placeholder: string; selector?: string; nth?: number }> | undefined;
+  if (!hints?.length) return '';
+  const heading = result.hintsLabel as string | undefined;
+  let msg = `\n\n${heading || 'Visible interactive elements on page'}:`;
+  for (const h of hints) {
+    const label = h.ariaLabel || h.text || h.placeholder || '(unnamed)';
+    const sel = h.selector ? ` → ${h.selector}${h.nth !== undefined ? ` [nth:${h.nth}]` : ''}` : '';
+    msg += `\n- ${h.role}: "${label.substring(0, 60)}"${sel}`;
+  }
+  msg += '\n\nRetry with one of the selectors above, or browser_snapshot for fresh refs.';
+  return msg;
+}
+
+/**
+ * Hints, then — when the server stamped this as a pre-action resolution failure and attached
+ * `assist` — Jev's ranking of the candidates against what the caller was aiming at. Shadow by
+ * default: the hint list is reordered and annotated, and nothing else happens.
+ */
+async function describeFailure(result: Record<string, unknown>, request: { action: string; selector?: string; textHint?: string; asked: boolean }): Promise<{ text: string; recovery: assist.Recovery }> {
+  // Only when this handler asked for it: an `assist` block that arrives unrequested (a batch step, Jev off) is ignored, not judged.
+  const recovery = request.asked && result.assist ? await assist.recoverFailedTarget(result, request) : { annotation: '' };
+  return { text: `${formatClickHints(recovery.hints ? { ...result, hints: recovery.hints } : result)}${recovery.annotation}`, recovery };
+}
+
+/** Ask for candidates only for selector targets: a stale ref has no hint list to rank, and a fresh snapshot is the fix. */
+const wantsTargetAssist = (args: { ref?: string; selector?: string | null }) => Boolean(args.selector) && !args.ref && assist.assistAvailable('browser-target');
+
+function locationSuffix(result: Record<string, unknown>): string {
+  if (ni.isBrowserCompactMode()) return '';
+  return result.url ? ` — ${result.url} "${result.title}"` : '';
+}
+
+function describeTarget(ref?: string, selector?: string): string {
+  return ref ? `ref "${ref}"` : `"${selector}"`;
+}
+
+// Appends the inline snapshot section for the new-style snapshot param ('diff'|'full').
+function appendAiSnapshot(msg: string, result: Record<string, unknown>): string {
+  return msg + `\n\n--- Snapshot ---\n${formatAiSnapshotBody(result, CLICK_SNAPSHOT_MAX_CHARS)}`;
+}
+
+// ── browser_click ──
+
+export const browserClickSchema = {
+  ref: refField,
+  selector: selectorField('the element to click'),
+  nthMatch: z.coerce.number().int().min(0).optional().describe('If the selector matches multiple elements, target the Nth (0-indexed).'),
+  textHint: z.string().optional().describe('What you meant to click, in words (e.g. "Account settings"). If the selector matches nothing the server first tries an exact role+name match; failing that, the visible candidates are ranked against this phrase and the best one is named in the error. Advisory unless safe auto-heal is switched on.'),
+  snapshot: z.enum(['diff', 'full', 'none']).optional().describe('Inline AI snapshot after the click. Default "diff" = only the changed region vs your last snapshot. "none" = terse response.'),
+  returnSnapshot: returnSnapshotField,
+  sessionId: z.string().optional().describe('Browser session ID. If omitted, auto-selects the only open session.'),
+  tabId: tabIdField,
+};
+
+export const browserClickDescription =
+  'Click an element. Pass ref (e.g. "e12") from browser_snapshot — exact, no guessing. Selector is the fallback (CSS, text="...", :has-text(...), role=...; never :contains()). By default the response includes an AI snapshot diff of what changed, so you usually do NOT need a follow-up browser_snapshot.';
+
+export async function handleBrowserClick(args: {
+  ref?: string;
+  selector?: string;
+  nthMatch?: number;
+  textHint?: string;
+  snapshot?: 'diff' | 'full' | 'none';
+  returnSnapshot?: { mode?: 'full' | 'interactive' | 'landmarks'; selector?: string; viewport?: boolean; maxChars?: number; format?: 'text' | 'json' };
+  sessionId?: string;
+  tabId?: string;
+}) {
+  if (!args.ref && !args.selector) return text('Provide ref (from browser_snapshot) or selector.');
+  const resolved = await ni.resolveSession(args.sessionId, undefined, args.tabId);
+  if ('error' in resolved) return text(resolved.error);
+
+  const rs = args.returnSnapshot ? {
+    mode: args.returnSnapshot.mode,
+    selector: args.returnSnapshot.selector,
+    viewport: args.returnSnapshot.viewport,
+  } : undefined;
+  // New-style inline AI snapshot: default 'diff' unless legacy returnSnapshot was
+  // passed or auto-snapshot is globally disabled.
+  const snapshot = args.snapshot ?? (rs || !autosnapshotEnabled() ? undefined : 'diff');
+  const asked = wantsTargetAssist(args);
+  let result = await ni.click(resolved.sessionId, args.selector, args.nthMatch, resolved.tabId, args.textHint, rs, args.ref, snapshot, undefined, asked);
+  let healedBy = '';
+  if (result.error) {
+    const failure = await describeFailure(result, { action: 'click', selector: args.selector, textHint: args.textHint, asked });
+    // Safe auto-heal: off unless a recorded benchmark vouches for the running configuration, and then
+    // exactly one retry, of a plain navigation link, through a context the server minted for this
+    // failure. attemptAutoHeal is a direct transport call; this handler is never re-entered.
+    const outcome = failure.recovery.heal
+      ? await assist.attemptAutoHeal(failure.recovery.heal, { sessionId: resolved.sessionId, tabId: resolved.tabId, snapshot })
+      : null;
+    if (outcome?.status === 'uncertain') {
+      return text(`Click failed: ${result.error}\n\nJev auto-heal was then attempted once and its outcome is uncertain: ${outcome.error}\nInspect the page before doing anything else; nothing is retried.`);
+    }
+    if (outcome?.status !== 'healed') return text(`Click failed: ${result.error}${failure.text}${outcome?.note ?? ''}`);
+    healedBy = ` (auto-healed via Jev to "${outcome.label}": ${outcome.verdict}; ${describeTarget(args.ref, args.selector)} matched nothing)`;
+    result = outcome.result;
+  }
+
+  const healed = healedBy || (result.healed ? ' (auto-healed via textHint)' : '');
+  let msg = `Clicked ${describeTarget(args.ref, args.selector)}${healed}${locationSuffix(result)}`;
+  if (snapshot && snapshot !== 'none') {
+    msg = appendAiSnapshot(msg, result);
+  } else if (args.returnSnapshot && !healedBy) {
+    const snap = formatInlineSnapshot(result, {
+      mode: args.returnSnapshot.mode,
+      format: args.returnSnapshot.format,
+      maxChars: args.returnSnapshot.maxChars,
+    });
+    msg += `\n\n--- Snapshot (${args.returnSnapshot.mode || 'full'}) ---\n${snap}`;
+  }
+  return text(msg);
+}
+
+// ── browser_fill ──
+
+export const browserFillSchema = {
+  ref: refField,
+  selector: selectorField('the input/textarea to fill'),
+  value: z.string().describe('The text value to fill. Clears existing content first.'),
+  nthMatch: z.coerce.number().int().min(0).optional().describe('If the selector matches multiple elements, fill the Nth (0-indexed).'),
+  textHint: z.string().optional().describe('Auto-heal: if the selector matches 0 elements, server retries with role=*[name~="<textHint>"].'),
+  sessionId: z.string().optional().describe('Browser session ID. If omitted, auto-selects the only open session.'),
+  tabId: tabIdField,
+};
+
+export const browserFillDescription =
+  'Clear an input/textarea and fill it with new text. Pass ref from browser_snapshot (preferred) or a selector. For contenteditable editors prefer browser_type.';
+
+export async function handleBrowserFill(args: { ref?: string; selector?: string; value: string; nthMatch?: number; textHint?: string; sessionId?: string; tabId?: string }) {
+  if (!args.ref && !args.selector) return text('Provide ref (from browser_snapshot) or selector.');
+  const resolved = await ni.resolveSession(args.sessionId, undefined, args.tabId);
+  if ('error' in resolved) return text(resolved.error);
+
+  const asked = wantsTargetAssist(args);
+  const result = await ni.fill(resolved.sessionId, args.selector, args.value, args.nthMatch, resolved.tabId, args.textHint, args.ref, asked);
+  // The value being filled is never part of what is judged: only the target phrase and the page's candidates are.
+  if (result.error) return text(`Fill failed: ${result.error}${(await describeFailure(result, { action: 'fill', selector: args.selector, textHint: args.textHint, asked })).text}`);
+
+  const healed = result.healed ? ' (auto-healed via textHint)' : '';
+  return text(`Filled ${describeTarget(args.ref, args.selector)}${healed} with "${args.value.slice(0, 100)}"${locationSuffix(result)}`);
+}
+
+// ── browser_type ──
+
+export const browserTypeSchema = {
+  ref: refField,
+  selector: z.string().optional().describe('Playwright selector for the element to type into. If both ref and selector are omitted, types into the focused element.'),
+  text: z.string().describe('The text to type character by character (appends to existing content).'),
+  nthMatch: z.coerce.number().int().min(0).optional().describe('If the selector matches multiple elements, type into the Nth (0-indexed).'),
+  textHint: z.string().optional().describe('Auto-heal: if the selector matches 0 elements, server retries with role=*[name~="<textHint>"].'),
+  mode: z.enum(['sequential', 'insert', 'paragraphs']).optional().describe('"sequential" = per-key events. "insert" = bulk insertText, fast, safe for modal composers. "paragraphs" = Escape+Enter between paragraphs (never on modals — Escape closes them). See browser_cheatsheet for platform guidance.'),
+  sessionId: z.string().optional().describe('Browser session ID. If omitted, auto-selects the only open session.'),
+  tabId: tabIdField,
+};
+
+export const browserTypeDescription =
+  'Type text (simulates keystrokes; appends). Target by ref from browser_snapshot (preferred), selector, or omit both to type into the focused element. Prefer over browser_fill for contenteditable/rich-text editors.';
+
+export async function handleBrowserType(args: { ref?: string; selector?: string; text: string; nthMatch?: number; textHint?: string; mode?: 'sequential' | 'insert' | 'paragraphs'; sessionId?: string; tabId?: string }) {
+  const resolved = await ni.resolveSession(args.sessionId, undefined, args.tabId);
+  if ('error' in resolved) return text(resolved.error);
+
+  const asked = wantsTargetAssist(args);
+  const result = await ni.type(resolved.sessionId, args.selector ?? null, args.text, args.nthMatch, resolved.tabId, args.textHint, args.mode, args.ref, asked);
+  if (result.error) return text(`Type failed: ${result.error}${(await describeFailure(result, { action: 'type', selector: args.selector, textHint: args.textHint, asked })).text}`);
+
+  const target = args.ref ? `ref "${args.ref}"` : args.selector ? `"${args.selector}"` : 'focused element';
+  const healed = result.healed ? ' (auto-healed via textHint)' : '';
+  return text(`Typed "${args.text.slice(0, 100)}" into ${target}${healed}${locationSuffix(result)}`);
+}
+
+// ── browser_hover ──
+
+export const browserHoverSchema = {
+  ref: refField,
+  selector: selectorField('the element to hover over'),
+  nthMatch: z.coerce.number().int().min(0).optional().describe('If the selector matches multiple elements, hover over the Nth (0-indexed).'),
+  textHint: z.string().optional().describe('Auto-heal: if the selector matches 0 elements, server retries with role=*[name~="<textHint>"].'),
+  sessionId: z.string().optional().describe('Browser session ID. If omitted, auto-selects the only open session.'),
+  tabId: tabIdField,
+};
+
+export const browserHoverDescription =
+  'Hover over an element (reveals dropdowns, tooltips, hover-triggered content). Pass ref from browser_snapshot (preferred) or a selector.';
+
+export async function handleBrowserHover(args: { ref?: string; selector?: string; nthMatch?: number; textHint?: string; sessionId?: string; tabId?: string }) {
+  if (!args.ref && !args.selector) return text('Provide ref (from browser_snapshot) or selector.');
+  const resolved = await ni.resolveSession(args.sessionId, undefined, args.tabId);
+  if ('error' in resolved) return text(resolved.error);
+
+  const asked = wantsTargetAssist(args);
+  const result = await ni.hover(resolved.sessionId, args.selector, args.nthMatch, resolved.tabId, args.textHint, args.ref, asked);
+  if (result.error) return text(`Hover failed: ${result.error}${(await describeFailure(result, { action: 'hover', selector: args.selector, textHint: args.textHint, asked })).text}`);
+
+  const healed = result.healed ? ' (auto-healed via textHint)' : '';
+  return text(`Hovered over ${describeTarget(args.ref, args.selector)}${healed}${locationSuffix(result)}`);
+}
+
+// ── browser_select ──
+
+export const browserSelectSchema = {
+  ref: refField,
+  selector: selectorField('the <select> element'),
+  value: z.string().describe('The option value to select.'),
+  nthMatch: z.coerce.number().int().min(0).optional().describe('If the selector matches multiple elements, select from the Nth one (0-indexed).'),
+  textHint: z.string().optional().describe('What the dropdown is for, in words (e.g. "Country"). If the selector matches nothing, the server tries an exact role+name match and the visible candidates are ranked against this phrase. Advisory.'),
+  sessionId: z.string().optional().describe('Browser session ID. If omitted, auto-selects the only open session.'),
+  tabId: tabIdField,
+};
+
+export const browserSelectDescription =
+  'Select an option from a <select> dropdown by ref or selector, and option value.';
+
+export async function handleBrowserSelect(args: { ref?: string; selector?: string; value: string; nthMatch?: number; textHint?: string; sessionId?: string; tabId?: string }) {
+  if (!args.ref && !args.selector) return text('Provide ref (from browser_snapshot) or selector.');
+  const resolved = await ni.resolveSession(args.sessionId, undefined, args.tabId);
+  if ('error' in resolved) return text(resolved.error);
+
+  const asked = wantsTargetAssist(args);
+  const result = await ni.selectOption(resolved.sessionId, args.selector, args.value, args.nthMatch, resolved.tabId, args.ref, args.textHint, asked);
+  if (result.error) return text(`Select failed: ${result.error}${(await describeFailure(result, { action: 'select', selector: args.selector, textHint: args.textHint, asked })).text}`);
+
+  return text(`Selected "${args.value}" in ${describeTarget(args.ref, args.selector)}${locationSuffix(result)}`);
+}
+
+// ── browser_press ──
+
+export const browserPressSchema = {
+  key: z.string().describe('Key or key combo to press (e.g. "Enter", "Tab", "Control+A", "Escape", "ArrowDown").'),
+  sessionId: z.string().optional().describe('Browser session ID. If omitted, auto-selects the only open session.'),
+  tabId: tabIdField,
+};
+
+export const browserPressDescription =
+  'Press a keyboard key or key combination. Supports modifiers like Control+A, Shift+Enter, etc.';
+
+export async function handleBrowserPress(args: { key: string; sessionId?: string; tabId?: string }) {
+  const resolved = await ni.resolveSession(args.sessionId, undefined, args.tabId);
+  if ('error' in resolved) return text(resolved.error);
+
+  const result = await ni.pressKey(resolved.sessionId, args.key, resolved.tabId);
+  if (result.error) return text(`Press failed: ${result.error}`);
+
+  return text(`Pressed "${args.key}"${locationSuffix(result)}`);
+}
+
+// ── browser_scroll ──
+
+export const browserScrollSchema = {
+  direction: z.enum(['up', 'down', 'left', 'right']).describe('Direction to scroll.'),
+  distance: z.coerce.number().optional().describe('Pixels to scroll (default: 500).'),
+  ref: z.string().optional().describe('Scroll within the container with this ref from browser_snapshot.'),
+  selector: z.string().optional().describe('Scroll within a specific scrollable element instead of the window.'),
+  snapshot: z.enum(['diff', 'full', 'none']).optional().describe('Optionally include an AI snapshot after scrolling ("diff" = only what changed).'),
+  returnSnapshot: returnSnapshotField,
+  sessionId: z.string().optional().describe('Browser session ID. If omitted, auto-selects the only open session.'),
+  tabId: tabIdField,
+};
+
+export const browserScrollDescription =
+  'Scroll the page or a scrollable container (by ref or selector). Essential for infinite-scroll feeds — but for harvesting feed data, prefer the browser_extract_* tools with their scrolls param, which scroll+extract+dedupe in one call.';
+
+export async function handleBrowserScroll(args: {
+  direction: string;
+  distance?: number;
+  ref?: string;
+  selector?: string;
+  snapshot?: 'diff' | 'full' | 'none';
+  returnSnapshot?: { mode?: 'full' | 'interactive' | 'landmarks'; selector?: string; viewport?: boolean; maxChars?: number; format?: 'text' | 'json' };
+  sessionId?: string;
+  tabId?: string;
+}) {
+  const resolved = await ni.resolveSession(args.sessionId, undefined, args.tabId);
+  if ('error' in resolved) return text(resolved.error);
+
+  const rs = args.returnSnapshot ? {
+    mode: args.returnSnapshot.mode,
+    selector: args.returnSnapshot.selector,
+    viewport: args.returnSnapshot.viewport,
+  } : undefined;
+  const result = await ni.scroll(resolved.sessionId, {
+    direction: args.direction,
+    distance: args.distance,
+    selector: args.selector,
+    ref: args.ref,
+    snapshot: args.snapshot,
+    returnSnapshot: rs,
+  }, resolved.tabId);
+  if (result.error) return text(`Scroll failed: ${result.error}`);
+
+  const target = args.ref ? `ref "${args.ref}"` : args.selector ? `"${args.selector}"` : 'page';
+  let msg = `Scrolled ${args.direction} ${args.distance ?? 500}px in ${target}${locationSuffix(result)}`;
+  if (args.snapshot && args.snapshot !== 'none') {
+    msg = appendAiSnapshot(msg, result);
+  } else if (args.returnSnapshot) {
+    const snap = formatInlineSnapshot(result, {
+      mode: args.returnSnapshot.mode,
+      format: args.returnSnapshot.format,
+      maxChars: args.returnSnapshot.maxChars,
+    });
+    msg += `\n\n--- Snapshot (${args.returnSnapshot.mode || 'full'}) ---\n${snap}`;
+  }
+  return text(msg);
+}
+
+// ── browser_upload ──
+
+export const browserUploadSchema = {
+  ref: refField,
+  selector: selectorField('the file input element'),
+  filePaths: z.array(z.string()).describe('Absolute file paths to upload.'),
+  nthMatch: z.coerce.number().int().min(0).optional().describe('If the selector matches multiple file inputs, upload to the Nth (0-indexed).'),
+  textHint: z.string().optional().describe('What the upload control is, in words (e.g. "Add photo"). If the file input is not found, the visible controls are ranked against this phrase — usually the button that reveals the hidden input. Advisory.'),
+  sessionId: z.string().optional().describe('Browser session ID. If omitted, auto-selects the only open session.'),
+  tabId: tabIdField,
+};
+
+export const browserUploadDescription =
+  'Upload files via a file input element (by ref or selector). For hidden/gated inputs, click the visible upload button first to reveal the input. See browser_cheatsheet for per-platform upload flows.';
+
+export async function handleBrowserUpload(args: { ref?: string; selector?: string; filePaths: string[]; nthMatch?: number; textHint?: string; sessionId?: string; tabId?: string }) {
+  if (!args.ref && !args.selector) return text('Provide ref (from browser_snapshot) or selector.');
+  const resolved = await ni.resolveSession(args.sessionId, undefined, args.tabId);
+  if ('error' in resolved) return text(resolved.error);
+
+  const asked = wantsTargetAssist(args);
+  const result = await ni.upload(resolved.sessionId, args.selector, args.filePaths, args.nthMatch, resolved.tabId, args.ref, args.textHint, asked);
+  if (result.error) return text(`Upload failed: ${result.error}${(await describeFailure(result, { action: 'upload', selector: args.selector, textHint: args.textHint, asked })).text}`);
+
+  return text(`Uploaded ${args.filePaths.length} file(s) via ${describeTarget(args.ref, args.selector)}${locationSuffix(result)}`);
+}