unbrowse 2.10.2 → 2.12.0

package/runtime-src/cli.ts

@@ -8,10 +8,18 @@
  */
 
 import { config as loadEnv } from "dotenv";
-import { ensureRegistered, getApiKey } from "./client/index.js";
+import { spawn } from "node:child_process";
+import {
+  detectTelemetryHostType,
+  ensureCliInstallTracked,
+  ensureRegistered,
+  getApiKey,
+  recordFunnelTelemetryEvent,
+  recordInstallTelemetryEvent,
+} from "./client/index.js";
 import { findSitePack, findTask, allSitePacks, buildDepsGraph, planExecution, buildDepsMetadata, type SitePack } from "./cli/shortcuts.js";
 import { ensureLocalServer, checkServerVersion, stopServer, restartServer } from "./runtime/local-server.js";
-import { isMainModule } from "./runtime/paths.js";
+import { isMainModule, resolveSiblingEntrypoint, runtimeArgsForEntrypoint } from "./runtime/paths.js";
 import { drainPendingIndexJobs } from "./indexer/index.js";
 import { drainPendingPassivePublishes } from "./orchestrator/passive-publish.js";
 import { runSetup, type SetupReport, type SetupScope } from "./runtime/setup.js";
@@ -85,6 +93,28 @@ function info(msg: string): void {
   process.stderr.write(`[unbrowse] ${msg}\n`);
 }
 
+function resolveResultError(result: Record<string, unknown>): string | undefined {
+  return (result.result as Record<string, unknown> | undefined)?.error as string | undefined
+    ?? result.error as string | undefined;
+}
+
+function resolveLoginUrl(result: Record<string, unknown>, fallbackUrl?: string): string {
+  return (result.result as Record<string, unknown> | undefined)?.login_url as string
+    ?? fallbackUrl
+    ?? "";
+}
+
+function hasIndexingFallback(result: Record<string, unknown>): boolean {
+  return (result.result as Record<string, unknown> | undefined)?.indexing_fallback_available === true;
+}
+
+function isResolveSuccessResult(result: Record<string, unknown>): boolean {
+  const resultObj = result.result as Record<string, unknown> | undefined;
+  if (resolveResultError(result)) return false;
+  if (resultObj?.status === "browse_session_open") return false;
+  return !!result.result || Array.isArray(result.available_endpoints);
+}
+
 async function withPendingNotice<T>(promise: Promise<T>, message: string, delayMs = 3_000): Promise<T> {
   let done = false;
   const timer = setTimeout(() => {
@@ -126,130 +156,279 @@ function slimTrace(obj: Record<string, unknown>): Record<string, unknown> {
   };
   if ("result" in obj) out.result = obj.result;
   if (obj.available_endpoints) out.available_endpoints = obj.available_endpoints;
+  if (obj.impact) out.impact = obj.impact;
+  if (obj.next_actions) out.next_actions = obj.next_actions;
+  if (obj.next_step) out.next_step = obj.next_step;
   if (obj.source) out.source = obj.source;
   if (obj.skill) out.skill = obj.skill;
   return out;
 }
 
+function formatSavedDuration(ms: number): string {
+  if (ms >= 60_000) return `${(ms / 60_000).toFixed(1)}m`;
+  if (ms >= 10_000) return `${Math.round(ms / 1000)}s`;
+  if (ms >= 1000) return `${(ms / 1000).toFixed(1)}s`;
+  return `${ms}ms`;
+}
+
+function emitImpactSummary(result: Record<string, unknown>): void {
+  const impact = result.impact as Record<string, unknown> | undefined;
+  if (!impact) return;
+
+  const timeSavedMs = typeof impact.time_saved_ms === "number" ? impact.time_saved_ms : 0;
+  const tokensSaved = typeof impact.tokens_saved === "number" ? impact.tokens_saved : 0;
+  const timeSavedPct = typeof impact.time_saved_pct === "number" ? impact.time_saved_pct : 0;
+  const tokensSavedPct = typeof impact.tokens_saved_pct === "number" ? impact.tokens_saved_pct : 0;
+  const browserAvoided = impact.browser_avoided === true;
+  if (timeSavedMs <= 0 && tokensSaved <= 0 && !browserAvoided) return;
+
+  const parts: string[] = [];
+  if (timeSavedMs > 0) parts.push(`${formatSavedDuration(timeSavedMs)} saved (${timeSavedPct}% faster)`);
+  if (tokensSaved > 0) parts.push(`${tokensSaved.toLocaleString("en-US")} tokens saved (${tokensSavedPct}% less context)`);
+  if (browserAvoided) parts.push("browser avoided");
+  info(parts.join(" • "));
+}
+
+function emitNextActionSummary(result: Record<string, unknown>): void {
+  const nextActions = Array.isArray(result.next_actions)
+    ? result.next_actions as Array<Record<string, unknown>>
+    : [];
+  if (nextActions.length === 0) return;
+  info("Likely next actions:");
+  for (const action of nextActions.slice(0, 3)) {
+    const command = typeof action.command === "string" ? action.command : "";
+    const title = typeof action.title === "string" ? action.title : (action.endpoint_id as string | undefined) ?? "next step";
+    const why = typeof action.why === "string" ? action.why : "";
+    info(`  ${command || title}${why ? `  # ${why}` : ""}`);
+  }
+}
+
 
 async function cmdHealth(flags: Record<string, string | boolean>): Promise<void> {
   output(await api("GET", "/health"), !!flags.pretty);
 }
 
+function telemetryDomainFromInput(domain?: string, url?: string): string | null {
+  if (domain?.trim()) return domain.trim().replace(/^www\./, "");
+  if (!url?.trim()) return null;
+  try {
+    return new URL(url).hostname.replace(/^www\./, "");
+  } catch {
+    return null;
+  }
+}
+
 async function cmdResolve(flags: Record<string, string | boolean>): Promise<void> {
   const intent = flags.intent as string;
   if (!intent) die("--intent is required");
+  const hostType = detectTelemetryHostType();
+  await ensureCliInstallTracked(hostType);
+  await recordFunnelTelemetryEvent("cli_invoked", {
+    source: "cli",
+    hostType,
+    properties: { command: "resolve" },
+  });
+  await recordFunnelTelemetryEvent("resolve_started", {
+    source: "cli",
+    hostType,
+    properties: {
+      command: "resolve",
+      intent,
+      domain: telemetryDomainFromInput(flags.domain as string | undefined, flags.url as string | undefined),
+      url: typeof flags.url === "string" ? flags.url : null,
+      has_url: typeof flags.url === "string",
+      has_domain: typeof flags.domain === "string",
+      auto_execute: !!flags.execute,
+    },
+  });
 
-  const body: Record<string, unknown> = { intent };
-  const url = flags.url as string | undefined;
-  const domain = flags.domain as string | undefined;
-  const explicitEndpointId = flags["endpoint-id"] as string | undefined;
-  const autoExecute = !!flags.execute;
-  const extraParams = flags.params ? JSON.parse(flags.params as string) : {};
+  try {
+    const body: Record<string, unknown> = { intent };
+    const url = flags.url as string | undefined;
+    const domain = flags.domain as string | undefined;
+    const explicitEndpointId = flags["endpoint-id"] as string | undefined;
+    const autoExecute = !!flags.execute;
+    const extraParams = flags.params ? JSON.parse(flags.params as string) : {};
+
+    if (url) {
+      body.params = { url };
+      body.context = { url };
+    }
+    if (domain) {
+      body.context = { ...(body.context as Record<string, unknown> ?? {}), domain };
+    }
+    if (explicitEndpointId) {
+      body.params = { ...(body.params as Record<string, unknown> ?? {}), endpoint_id: explicitEndpointId };
+    }
+    if (flags.params) {
+      body.params = { ...(body.params as Record<string, unknown> ?? {}), ...extraParams };
+    }
+    if (flags["dry-run"]) body.dry_run = true;
+    if (flags["force-capture"]) body.force_capture = true;
+    body.projection = { raw: true };
 
-  if (url) {
-    body.params = { url };
-    body.context = { url };
-  }
-  if (domain) {
-    body.context = { ...(body.context as Record<string, unknown> ?? {}), domain };
-  }
-  if (explicitEndpointId) {
-    body.params = { ...(body.params as Record<string, unknown> ?? {}), endpoint_id: explicitEndpointId };
-  }
-  if (flags.params) {
-    body.params = { ...(body.params as Record<string, unknown> ?? {}), ...extraParams };
-  }
-  if (flags["dry-run"]) body.dry_run = true;
-  if (flags["force-capture"]) body.force_capture = true;
-  body.projection = { raw: true };
+    function execBody(endpointId: string): Record<string, unknown> {
+      return { params: { endpoint_id: endpointId, ...extraParams }, intent, projection: { raw: true } };
+    }
 
-  function execBody(endpointId: string): Record<string, unknown> {
-    return { params: { endpoint_id: endpointId, ...extraParams }, intent, projection: { raw: true } };
-  }
+    function resolveSkillId(): string | undefined {
+      return (result.skill as Record<string, unknown>)?.skill_id as string
+        ?? (result as Record<string, unknown>).skill_id as string;
+    }
 
-  function resolveSkillId(): string | undefined {
-    return (result.skill as Record<string, unknown>)?.skill_id as string
-      ?? (result as Record<string, unknown>).skill_id as string;
-  }
+    const startedAt = Date.now();
+    async function resolveOnce(message = "Still working. First-time capture/indexing for a site can take 20-80s. Waiting is usually better than falling back."): Promise<Record<string, unknown>> {
+      return withPendingNotice(
+        api("POST", "/v1/intent/resolve", body) as Promise<Record<string, unknown>>,
+        message,
+      );
+    }
 
-  const startedAt = Date.now();
-  let result = await withPendingNotice(
-    api("POST", "/v1/intent/resolve", body) as Promise<Record<string, unknown>>,
-    "Still working. First-time capture/indexing for a site can take 20-80s. Waiting is usually better than falling back.",
-  );
+    let result = await resolveOnce();
+    let attemptedForceCapture = !!body.force_capture;
+    let attemptedCookieImport = false;
+    let attemptedInteractiveLogin = false;
+
+    while (true) {
+      const resultError = resolveResultError(result);
+      if (resultError === "payment_required" && hasIndexingFallback(result) && url && !attemptedForceCapture) {
+        attemptedForceCapture = true;
+        body.force_capture = true;
+        info("Marketplace search is paid here. Falling back to free live capture on the exact URL...");
+        result = await resolveOnce("Running free live capture...");
+        continue;
+      }
+
+      if (resultError === "auth_required") {
+        const loginUrl = resolveLoginUrl(result, url);
+        if (!loginUrl) break;
+
+        if (!attemptedCookieImport) {
+          attemptedCookieImport = true;
+          info("Site requires authentication. Trying browser cookie import first...");
+          const stealResult = await api("POST", "/v1/auth/steal", { url: loginUrl }) as Record<string, unknown>;
+          const cookiesStored = typeof stealResult.cookies_stored === "number"
+            ? stealResult.cookies_stored
+            : Number(stealResult.cookies_stored ?? 0);
+          if (stealResult.success === true && cookiesStored > 0) {
+            info(`Imported ${cookiesStored} browser cookies. Retrying...`);
+            result = await resolveOnce("Retrying after browser cookie import...");
+            continue;
+          }
+        }
+
+        if (!attemptedInteractiveLogin) {
+          attemptedInteractiveLogin = true;
+          info("Site requires authentication. Opening browser for login...");
+          const loginResult = await api("POST", "/v1/auth/login", { url: loginUrl }) as Record<string, unknown>;
+          if (loginResult.error || loginResult.success === false) {
+            const message = typeof loginResult.error === "string"
+              ? loginResult.error
+              : "interactive login did not produce a reusable session";
+            throw new Error(`Login failed: ${message}. Run: unbrowse login --url "${loginUrl}"`);
+          }
+          info("Login complete. Retrying...");
+          result = await resolveOnce("Retrying after login...");
+          continue;
+        }
+      }
+
+      break;
+    }
 
-  // Auto-handle auth: if site requires login, trigger interactive login and retry
-  const resultError = (result.result as Record<string, unknown>)?.error
-    ?? (result as Record<string, unknown>).error;
-  if (resultError === "auth_required") {
-    const loginUrl = (result.result as Record<string, unknown>)?.login_url as string
-      ?? url ?? "";
-    if (loginUrl) {
-      info("Site requires authentication. Opening browser for login...");
-      try {
-        await api("POST", "/v1/auth/login", { url: loginUrl });
-        info("Login complete. Retrying...");
+    // When agent explicitly picked an endpoint but resolve deferred, execute it directly
+    if (explicitEndpointId && result.available_endpoints) {
+      const skillId = resolveSkillId();
+      if (skillId) {
         result = await withPendingNotice(
-          api("POST", "/v1/intent/resolve", body) as Promise<Record<string, unknown>>,
-          "Retrying after login...",
+          api("POST", `/v1/skills/${skillId}/execute`, execBody(explicitEndpointId)) as Promise<Record<string, unknown>>,
+          "Executing selected endpoint...",
         );
-      } catch (err) {
-        die(`Login failed: ${(err as Error).message}. Run: unbrowse login --url "${loginUrl}"`);
       }
     }
-  }
 
-  // When agent explicitly picked an endpoint but resolve deferred, execute it directly
-  if (explicitEndpointId && result.available_endpoints) {
-    const skillId = resolveSkillId();
-    if (skillId) {
-      result = await withPendingNotice(
-        api("POST", `/v1/skills/${skillId}/execute`, execBody(explicitEndpointId)) as Promise<Record<string, unknown>>,
-        "Executing selected endpoint...",
-      );
+    // --execute: auto-pick best endpoint and return data in one step
+    if (autoExecute && result.available_endpoints && !result.result) {
+      const endpoints = result.available_endpoints as Array<Record<string, unknown>>;
+      const skillId = resolveSkillId();
+      if (skillId && endpoints.length > 0) {
+        const bestEndpoint = endpoints[0];
+        info(`Auto-executing endpoint: ${bestEndpoint.description ?? bestEndpoint.endpoint_id}`);
+        result = await withPendingNotice(
+          api("POST", `/v1/skills/${skillId}/execute`, execBody(bestEndpoint.endpoint_id as string)) as Promise<Record<string, unknown>>,
+          "Executing best endpoint...",
+        );
+      }
     }
-  }
 
-  // --execute: auto-pick best endpoint and return data in one step
-  if (autoExecute && result.available_endpoints && !result.result) {
-    const endpoints = result.available_endpoints as Array<Record<string, unknown>>;
-    const skillId = resolveSkillId();
-    if (skillId && endpoints.length > 0) {
-      const bestEndpoint = endpoints[0];
-      info(`Auto-executing endpoint: ${bestEndpoint.description ?? bestEndpoint.endpoint_id}`);
-      result = await withPendingNotice(
-        api("POST", `/v1/skills/${skillId}/execute`, execBody(bestEndpoint.endpoint_id as string)) as Promise<Record<string, unknown>>,
-        "Executing best endpoint...",
-      );
+    // Browse session handoff
+    const resultObj = result.result as Record<string, unknown> | undefined;
+    if (resultObj?.status === "browse_session_open") {
+      info(`No cached API. Browser session open on ${resultObj.domain ?? resultObj.url}.`);
+      info(`Preferred flow: snap -> click/fill/eval -> submit -> sync -> close.`);
+      info(`Use these commands to get your data:`);
+      const commands = resultObj.commands as string[] ?? [
+        "unbrowse snap --filter interactive",
+        "unbrowse click <ref>",
+        "unbrowse fill <ref> <value>",
+        "unbrowse submit --wait-for \"/next-step\"",
+        "unbrowse sync",
+        "unbrowse close",
+      ];
+      for (const cmd of commands) info(`  ${cmd}`);
+      info(`For JS-heavy forms: prefer real date/time clicks first, inspect hidden inputs with eval when needed, then submit.`);
+      info(`All traffic is being passively captured. Run "unbrowse close" when done.`);
+      output(slimTrace(result), !!flags.pretty);
+      return;
     }
-  }
 
-  // Browse session handoff
-  const resultObj = result.result as Record<string, unknown> | undefined;
-  if (resultObj?.status === "browse_session_open") {
-    info(`No cached API. Browser session open on ${resultObj.domain ?? resultObj.url}.`);
-    info(`Use these commands to get your data:`);
-    const commands = resultObj.commands as string[] ?? ["unbrowse snap --filter interactive", "unbrowse click <ref>", "unbrowse close"];
-    for (const cmd of commands) info(`  ${cmd}`);
-    info(`All traffic is being passively captured. Run "unbrowse close" when done.`);
-    output(slimTrace(result), !!flags.pretty);
-    return;
-  }
+    if (Date.now() - startedAt > 3_000 && result.source === "live-capture") {
+      info("Live capture finished. Future runs against this site should be much faster.");
+    }
 
-  if (Date.now() - startedAt > 3_000 && result.source === "live-capture") {
-    info("Live capture finished. Future runs against this site should be much faster.");
-  }
+    if (isResolveSuccessResult(result)) {
+      await recordFunnelTelemetryEvent("resolve_completed", {
+        source: "cli",
+        hostType,
+        properties: {
+          command: "resolve",
+          intent,
+          domain: telemetryDomainFromInput(domain, url),
+          url: url ?? null,
+          source: result.source,
+          auto_execute: autoExecute,
+          explicit_endpoint: explicitEndpointId ?? null,
+        },
+      });
+    }
 
-  result = slimTrace(result);
+    result = slimTrace(result);
+    emitImpactSummary(result);
+    emitNextActionSummary(result);
 
-  const skill = result.skill as Record<string, unknown> | undefined;
-  const trace = result.trace as Record<string, unknown> | undefined;
-  if (skill?.skill_id && trace) {
-    (result as Record<string, unknown>)._feedback = `unbrowse feedback --skill ${skill.skill_id} --endpoint ${trace.endpoint_id || "?"} --rating <1-5>`;
-  }
+    const skill = result.skill as Record<string, unknown> | undefined;
+    const trace = result.trace as Record<string, unknown> | undefined;
+    if (skill?.skill_id && trace) {
+      (result as Record<string, unknown>)._feedback = `unbrowse feedback --skill ${skill.skill_id} --endpoint ${trace.endpoint_id || "?"} --rating <1-5>`;
+    }
 
-  output(result, !!flags.pretty);
+    output(result, !!flags.pretty);
+  } catch (error) {
+    const message = error instanceof Error ? error.message : String(error);
+    await recordFunnelTelemetryEvent("resolve_failed", {
+      source: "cli",
+      hostType,
+      properties: {
+        command: "resolve",
+        intent,
+        domain: telemetryDomainFromInput(flags.domain as string | undefined, flags.url as string | undefined),
+        url: typeof flags.url === "string" ? flags.url : null,
+        failure_stage: "resolve",
+        failure_reason: message,
+      },
+    });
+    throw error;
+  }
 }
 
 // ---------------------------------------------------------------------------
@@ -342,87 +521,154 @@ function schemaOf(value: unknown, depth = 4): unknown {
 async function cmdExecute(flags: Record<string, string | boolean>): Promise<void> {
   const skillId = flags.skill as string;
   if (!skillId) die("--skill is required");
+  const hostType = detectTelemetryHostType();
+  await ensureCliInstallTracked(hostType);
+  await recordFunnelTelemetryEvent("cli_invoked", {
+    source: "cli",
+    hostType,
+    properties: { command: "execute" },
+  });
+  await recordFunnelTelemetryEvent("resolve_started", {
+    source: "cli",
+    hostType,
+    properties: {
+      command: "execute",
+      intent: typeof flags.intent === "string" ? flags.intent : null,
+      domain: telemetryDomainFromInput(undefined, flags.url as string | undefined),
+      url: typeof flags.url === "string" ? flags.url : null,
+      skill_id: skillId,
+      endpoint_id: typeof flags.endpoint === "string" ? flags.endpoint : null,
+    },
+  });
 
-  const body: Record<string, unknown> = { params: {} };
-  if (flags.endpoint) {
-    (body.params as Record<string, unknown>).endpoint_id = flags.endpoint;
-  }
-  if (flags.params) {
-    body.params = { ...(body.params as Record<string, unknown>), ...JSON.parse(flags.params as string) };
-  }
-  if (flags.url) {
-    body.context_url = flags.url;
-    (body.params as Record<string, unknown>).url = flags.url;
-  }
-  if (flags.intent) body.intent = flags.intent;
-  if (flags["dry-run"]) body.dry_run = true;
-  if (flags["confirm-unsafe"]) body.confirm_unsafe = true;
-  body.projection = { raw: true };
+  try {
+    const body: Record<string, unknown> = { params: {} };
+    if (flags.endpoint) {
+      (body.params as Record<string, unknown>).endpoint_id = flags.endpoint;
+    }
+    if (flags.params) {
+      body.params = { ...(body.params as Record<string, unknown>), ...JSON.parse(flags.params as string) };
+    }
+    if (flags.url) {
+      body.context_url = flags.url;
+      (body.params as Record<string, unknown>).url = flags.url;
+    }
+    if (flags.intent) body.intent = flags.intent;
+    if (flags["dry-run"]) body.dry_run = true;
+    if (flags["confirm-unsafe"]) body.confirm_unsafe = true;
+    body.projection = { raw: true };
+
+    let result = await withPendingNotice(
+      api("POST", `/v1/skills/${skillId}/execute`, body) as Promise<Record<string, unknown>>,
+      "Still working. This endpoint may require browser replay or first-time auth/capture setup.",
+    );
+
+    if (isResolveSuccessResult(result)) {
+      await recordFunnelTelemetryEvent("resolve_completed", {
+        source: "cli",
+        hostType,
+        properties: {
+          command: "execute",
+          intent: typeof flags.intent === "string" ? flags.intent : null,
+          domain: telemetryDomainFromInput(undefined, flags.url as string | undefined),
+          url: typeof flags.url === "string" ? flags.url : null,
+          skill_id: skillId,
+          endpoint_id: typeof flags.endpoint === "string" ? flags.endpoint : null,
+        },
+      });
+    }
 
-  let result = await withPendingNotice(
-    api("POST", `/v1/skills/${skillId}/execute`, body) as Promise<Record<string, unknown>>,
-    "Still working. This endpoint may require browser replay or first-time auth/capture setup.",
-  );
+    // Strip metadata bloat
+    result = slimTrace(result);
+    emitImpactSummary(result);
+    emitNextActionSummary(result);
 
-  // Strip metadata bloat
-  result = slimTrace(result);
+    const pathFlag = flags.path as string | undefined;
+    const extractFlag = flags.extract as string | undefined;
+    const limitFlag = flags.limit ? Number(flags.limit) : undefined;
+    const schemaFlag = !!flags.schema;
+    const rawFlag = !!flags.raw;
 
-  const pathFlag = flags.path as string | undefined;
-  const extractFlag = flags.extract as string | undefined;
-  const limitFlag = flags.limit ? Number(flags.limit) : undefined;
-  const schemaFlag = !!flags.schema;
-  const rawFlag = !!flags.raw;
+    // --schema: show response structure without data
+    if (schemaFlag && !rawFlag) {
+      const data = result.result;
+      output({
+        trace: result.trace,
+        schema: schemaOf(data),
+        ...(result.impact ? { impact: result.impact } : {}),
+        ...(result.next_actions ? { next_actions: result.next_actions } : {}),
+      }, !!flags.pretty);
+      return;
+    }
 
-  // --schema: show response structure without data
-  if (schemaFlag && !rawFlag) {
-    const data = result.result;
-    output({ trace: result.trace, schema: schemaOf(data) }, !!flags.pretty);
-    return;
-  }
+    // Apply --path, --extract, --limit when not --raw
+    if (!rawFlag && (pathFlag || extractFlag || limitFlag)) {
+      const data = pathFlag ? drillPath(result.result, pathFlag) : result.result;
 
-  // Apply --path, --extract, --limit when not --raw
-  if (!rawFlag && (pathFlag || extractFlag || limitFlag)) {
-    let data = pathFlag ? drillPath(result.result, pathFlag) : result.result;
+      // Ensure array for extract/limit
+      const items = Array.isArray(data) ? data : data != null ? [data] : [];
 
-    // Ensure array for extract/limit
-    const items = Array.isArray(data) ? data : data != null ? [data] : [];
+      // Apply --extract
+      const extracted = extractFlag ? applyExtract(items, extractFlag) : items;
 
-    // Apply --extract
-    const extracted = extractFlag ? applyExtract(items, extractFlag) : items;
+      // Apply --limit
+      const limited = limitFlag ? extracted.slice(0, limitFlag) : extracted;
 
-    // Apply --limit
-    const limited = limitFlag ? extracted.slice(0, limitFlag) : extracted;
+      const trace = result.trace as Record<string, unknown> | undefined;
+      const out: Record<string, unknown> = {
+        trace: result.trace,
+        data: limited,
+        count: limited.length,
+        ...(result.impact ? { impact: result.impact } : {}),
+        ...(result.next_actions ? { next_actions: result.next_actions } : {}),
+      };
 
-    const trace = result.trace as Record<string, unknown> | undefined;
-    const out: Record<string, unknown> = { trace: result.trace, data: limited, count: limited.length };
+      // Prompt agent to review when this is likely a first-time execute
+      if (trace?.skill_id && trace?.endpoint_id && limited.length > 0) {
+        out._review_hint = `After presenting results, improve this endpoint's description: unbrowse review --skill ${trace.skill_id} --endpoints '[{"endpoint_id":"${trace.endpoint_id}","description":"DESCRIBE WHAT THIS RETURNS","action_kind":"ACTION","resource_kind":"RESOURCE"}]'`;
+      }
 
-    // Prompt agent to review when this is likely a first-time execute
-    if (trace?.skill_id && trace?.endpoint_id && limited.length > 0) {
-      out._review_hint = `After presenting results, improve this endpoint's description: unbrowse review --skill ${trace.skill_id} --endpoints '[{"endpoint_id":"${trace.endpoint_id}","description":"DESCRIBE WHAT THIS RETURNS","action_kind":"ACTION","resource_kind":"RESOURCE"}]'`;
+      output(out, !!flags.pretty);
+      return;
     }
 
-    output(out, !!flags.pretty);
-    return;
-  }
-
-  // Auto-wrap large responses with extraction_hints when no flags given
-  if (!rawFlag && !pathFlag && !extractFlag && !schemaFlag) {
-    const raw = JSON.stringify(result.result);
-    if (raw && raw.length > 2048) {
-      const schema = schemaOf(result.result);
-      output({
-        trace: result.trace,
-        extraction_hints: {
-          message: "Response is large. Use --path/--extract/--limit to filter, or --schema to see structure, or --raw for full response.",
-          schema_tree: schema,
-          response_bytes: raw.length,
-        },
-      }, !!flags.pretty);
-      return;
+    // Auto-wrap large responses with extraction_hints when no flags given
+    if (!rawFlag && !pathFlag && !extractFlag && !schemaFlag) {
+      const raw = JSON.stringify(result.result);
+      if (raw && raw.length > 2048) {
+        const schema = schemaOf(result.result);
+        output({
+          trace: result.trace,
+          ...(result.impact ? { impact: result.impact } : {}),
+          ...(result.next_actions ? { next_actions: result.next_actions } : {}),
+          extraction_hints: {
+            message: "Response is large. Use --path/--extract/--limit to filter, or --schema to see structure, or --raw for full response.",
+            schema_tree: schema,
+            response_bytes: raw.length,
+          },
+        }, !!flags.pretty);
+        return;
+      }
     }
-  }
 
-  output(result, !!flags.pretty);
+    output(result, !!flags.pretty);
+  } catch (error) {
+    const message = error instanceof Error ? error.message : String(error);
+    await recordFunnelTelemetryEvent("resolve_failed", {
+      source: "cli",
+      hostType,
+      properties: {
+        command: "execute",
+        intent: typeof flags.intent === "string" ? flags.intent : null,
+        domain: telemetryDomainFromInput(undefined, flags.url as string | undefined),
+        url: typeof flags.url === "string" ? flags.url : null,
+        skill_id: skillId,
+        failure_stage: "execute",
+        failure_reason: message,
+      },
+    });
+    throw error;
+  }
 }
 
 async function cmdFeedback(flags: Record<string, string | boolean>): Promise<void> {
@@ -490,7 +736,53 @@ async function cmdSearch(flags: Record<string, string | boolean>): Promise<void>
   const path = domain ? "/v1/search/domain" : "/v1/search";
   const body: Record<string, unknown> = { intent, k: Number(flags.k) || 5 };
   if (domain) body.domain = domain;
-  output(await api("POST", path, body), !!flags.pretty);
+  const hostType = detectTelemetryHostType();
+  await ensureCliInstallTracked(hostType);
+  await recordFunnelTelemetryEvent("cli_invoked", {
+    source: "cli",
+    hostType,
+    properties: { command: "search" },
+  });
+  await recordFunnelTelemetryEvent("search_started", {
+    source: "cli",
+    hostType,
+    properties: {
+      command: "search",
+      intent,
+      domain: domain ?? null,
+      k: body.k,
+    },
+  });
+  try {
+    const result = await api("POST", path, body) as Record<string, unknown>;
+    const results = Array.isArray(result.results) ? result.results : [];
+    await recordFunnelTelemetryEvent("search_completed", {
+      source: "cli",
+      hostType,
+      properties: {
+        command: "search",
+        intent,
+        domain: domain ?? null,
+        k: body.k,
+        result_count: results.length,
+      },
+    });
+    output(result, !!flags.pretty);
+  } catch (error) {
+    const message = error instanceof Error ? error.message : String(error);
+    await recordFunnelTelemetryEvent("search_failed", {
+      source: "cli",
+      hostType,
+      properties: {
+        command: "search",
+        intent,
+        domain: domain ?? null,
+        failure_stage: "search",
+        failure_reason: message,
+      },
+    });
+    throw error;
+  }
 }
 
 async function cmdSessions(flags: Record<string, string | boolean>): Promise<void> {
@@ -501,6 +793,13 @@ async function cmdSessions(flags: Record<string, string | boolean>): Promise<voi
 }
 
 async function cmdSetup(flags: Record<string, string | boolean>): Promise<void> {
+  const hostType = detectTelemetryHostType();
+  await ensureCliInstallTracked(hostType);
+  await recordFunnelTelemetryEvent("cli_invoked", {
+    source: "setup",
+    hostType,
+    properties: { command: "setup" },
+  });
   info("Running setup checks");
   const report = await runSetup({
     cwd: process.cwd(),
@@ -525,6 +824,26 @@ async function cmdSetup(flags: Record<string, string | boolean>): Promise<void>
     info(`Open Code command installed at ${report.opencode.command_file}`);
   }
 
+  await recordInstallTelemetryEvent("setup", {
+    hostType,
+    status: report.browser_engine.action === "failed" ? "failed" : "installed",
+    properties: {
+      browser_engine_action: report.browser_engine.action,
+      opencode_action: report.opencode.action,
+      no_start: !!flags["no-start"],
+      skip_browser: !!flags["skip-browser"],
+    },
+  });
+  await recordFunnelTelemetryEvent("setup_completed", {
+    source: "setup",
+    hostType,
+    properties: {
+      browser_engine_action: report.browser_engine.action,
+      opencode_action: report.opencode.action,
+      no_start: !!flags["no-start"],
+    },
+  });
+
   if (flags["no-start"]) {
     report.server = { started: false, skipped: true, base_url: BASE_URL };
     output(report, true);
@@ -539,8 +858,23 @@ async function cmdSetup(flags: Record<string, string | boolean>): Promise<void>
   try {
     await ensureLocalServer(BASE_URL, false, import.meta.url);
     report.server = { started: true, base_url: BASE_URL };
+    await recordFunnelTelemetryEvent("server_autostart_succeeded", {
+      source: "setup",
+      hostType,
+      properties: {
+        base_url: BASE_URL,
+      },
+    });
   } catch (error) {
     const message = error instanceof Error ? error.message : String(error);
+    await recordFunnelTelemetryEvent("server_autostart_failed", {
+      source: "setup",
+      hostType,
+      properties: {
+        failure_stage: "server_autostart",
+        failure_reason: message,
+      },
+    });
     report.server = { started: false, error: message, base_url: BASE_URL };
     output(report, true);
     process.exit(1);
@@ -557,6 +891,7 @@ async function cmdSetup(flags: Record<string, string | boolean>): Promise<void>
 export const CLI_REFERENCE = {
   commands: [
     { name: "health", usage: "", desc: "Server health check" },
+    { name: "mcp", usage: "[--no-auto-start]", desc: "Run the stdio MCP server" },
     { name: "setup", usage: "[--opencode auto|global|project|off] [--no-start]", desc: "Bootstrap browser deps + Open Code command" },
     { name: "resolve", usage: '--intent "..." --url "..." [opts]', desc: "Resolve intent → search/capture/execute" },
     { name: "execute", usage: "--skill ID --endpoint ID [opts]", desc: "Execute a specific endpoint" },
@@ -568,7 +903,8 @@ export const CLI_REFERENCE = {
     { name: "skill", usage: "<id>", desc: "Get skill details" },
     { name: "search", usage: '--intent "..." [--domain "..."]', desc: "Search marketplace" },
     { name: "sessions", usage: '--domain "..." [--limit N]', desc: "Debug session logs" },
-    { name: "go", usage: '<url>', desc: "Navigate browser to URL (passive indexing)" },
+    { name: "go", usage: '<url>', desc: "Open a live Kuri browser tab for capture-first workflows" },
+    { name: "submit", usage: "[--form-selector sel] [--submit-selector sel] [--wait-for hint]", desc: "Submit current form, auto-flush current capture, and fall back to same-origin rehydrate for JS-heavy flows" },
     { name: "snap", usage: "[--filter interactive]", desc: "A11y snapshot with @eN refs" },
     { name: "click", usage: "<ref>", desc: "Click element by ref (e.g. e5)" },
     { name: "fill", usage: "<ref> <value>", desc: "Fill input by ref" },
@@ -583,6 +919,7 @@ export const CLI_REFERENCE = {
     { name: "eval", usage: "<expression>", desc: "Evaluate JavaScript" },
     { name: "back", usage: "", desc: "Navigate back" },
     { name: "forward", usage: "", desc: "Navigate forward" },
+    { name: "sync", usage: "", desc: "Flush the current step's captured traffic into route cache without closing tab" },
     { name: "close", usage: "", desc: "Close browse session, flush + index traffic" },
   ],
   globalFlags: [
@@ -604,8 +941,13 @@ export const CLI_REFERENCE = {
   ],
   examples: [
     "unbrowse setup",
+    "unbrowse mcp",
     'unbrowse resolve --intent "top stories" --url "https://news.ycombinator.com" --execute',
     'unbrowse resolve --intent "get timeline" --url "https://x.com"',
+    'unbrowse go "https://www.mandai.com/en/ticketing/admission-and-rides/parks-selection.html"',
+    'unbrowse snap --filter interactive',
+    'unbrowse submit --wait-for "/time-selection.html"',
+    'unbrowse sync',
     "unbrowse execute --skill abc --endpoint def --pretty",
     "unbrowse execute --skill abc --endpoint def --schema --pretty",
     'unbrowse execute --skill abc --endpoint def --path "data.items[]" --extract "name,url" --limit 10 --pretty',
@@ -648,6 +990,24 @@ function printHelp(): void {
     lines.push(`  ${e}`);
   }
 
+  lines.push(
+    "",
+    "Browser workflow:",
+    "  1. go -> open the live tab you want to work in",
+    "  2. snap -> inspect refs and confirm the page state",
+    "  3. click/fill/eval -> set real page state",
+    "  4. submit -> prefer DOM submit; auto-flush current capture; fall back to same-origin rehydrate",
+    "  5. sync -> flush any additional captured routes after a successful step",
+    "  6. close -> finish capture + indexing",
+  );
+
+  lines.push(
+    "",
+    "JS-heavy forms:",
+    "  Prefer real calendar/time clicks before submit.",
+    "  If the UI is flaky, inspect hidden inputs/cookies with eval, then submit the real form.",
+  );
+
   lines.push("");
   process.stderr.write(lines.join("\n"));
 }
@@ -699,6 +1059,35 @@ async function cmdUpgrade(flags: Record<string, string | boolean>): Promise<void
   }
 }
 
+async function cmdMcp(flags: Record<string, string | boolean>): Promise<void> {
+  const entrypoint = resolveSiblingEntrypoint(import.meta.url, "mcp");
+  const child = spawn(
+    process.execPath,
+    [...runtimeArgsForEntrypoint(import.meta.url, entrypoint), ...(flags["no-auto-start"] ? ["--no-auto-start"] : [])],
+    {
+      cwd: process.cwd(),
+      stdio: "inherit",
+      env: {
+        ...process.env,
+        MCP_SERVER_MODE: "1",
+      },
+    },
+  );
+
+  const code = await new Promise<number>((resolve, reject) => {
+    child.once("error", reject);
+    child.once("exit", (exitCode, signal) => {
+      if (signal) {
+        process.kill(process.pid, signal);
+        return;
+      }
+      resolve(exitCode ?? 1);
+    });
+  });
+
+  if (code !== 0) process.exit(code);
+}
+
 // ---------------------------------------------------------------------------
 // Site/task shortcut commands
 // ---------------------------------------------------------------------------
@@ -851,6 +1240,18 @@ async function cmdGo(args: string[], flags: Record<string, string | boolean>): P
   output(await api("POST", "/v1/browse/go", { url }), !!flags.pretty);
 }
 
+async function cmdSubmit(flags: Record<string, string | boolean>): Promise<void> {
+  const body: Record<string, unknown> = {};
+  if (typeof flags["form-selector"] === "string") body.form_selector = flags["form-selector"];
+  if (typeof flags["submit-selector"] === "string") body.submit_selector = flags["submit-selector"];
+  if (typeof flags["wait-for"] === "string") body.wait_for = flags["wait-for"];
+  if (typeof flags["timeout-ms"] === "string") body.timeout_ms = Number(flags["timeout-ms"]);
+  if (flags["same-origin-fetch-fallback"] !== undefined) {
+    body.same_origin_fetch_fallback = flags["same-origin-fetch-fallback"] !== "false";
+  }
+  output(await api("POST", "/v1/browse/submit", body), !!flags.pretty);
+}
+
 async function cmdSnap(flags: Record<string, string | boolean>): Promise<void> {
   const filter = flags.filter as string | undefined;
   const result = await api("POST", "/v1/browse/snap", { filter }) as { snapshot?: string };
@@ -938,6 +1339,10 @@ async function cmdForward(): Promise<void> {
   output(await api("POST", "/v1/browse/forward"), false);
 }
 
+async function cmdSync(flags: Record<string, string | boolean>): Promise<void> {
+  output(await api("POST", "/v1/browse/sync"), !!flags.pretty);
+}
+
 async function cmdClose(): Promise<void> {
   output(await api("POST", "/v1/browse/close"), false);
 }
@@ -1010,6 +1415,7 @@ async function main(): Promise<void> {
   }
 
   // Server lifecycle commands (don't need ensureLocalServer)
+  if (command === "mcp") return cmdMcp(flags);
   if (command === "status") return cmdStatus(flags);
   if (command === "stop") { cmdStop(flags); return; }
   if (command === "restart") return cmdRestart(flags);
@@ -1018,11 +1424,11 @@ async function main(): Promise<void> {
 
   // --- Shortcut resolution: unbrowse <site> [task] [flags] ---
   const KNOWN_COMMANDS = new Set([
-    "health", "setup", "resolve", "execute", "exec",
+    "health", "mcp", "setup", "resolve", "execute", "exec",
     "feedback", "fb", "review", "publish", "login", "skills", "skill", "search", "sessions",
     "status", "stop", "restart", "upgrade", "update",
-    "go", "snap", "click", "fill", "type", "press", "select", "scroll",
-    "screenshot", "text", "markdown", "cookies", "eval", "back", "forward", "close",
+    "go", "submit", "snap", "click", "fill", "type", "press", "select", "scroll",
+    "screenshot", "text", "markdown", "cookies", "eval", "back", "forward", "sync", "close",
     "connect-chrome",
   ]);
 
@@ -1049,6 +1455,7 @@ async function main(): Promise<void> {
 
   switch (command) {
     case "health": return cmdHealth(flags);
+    case "mcp": return cmdMcp(flags);
     case "setup": return cmdSetup(flags);
     case "resolve": return cmdResolve(flags);
     case "execute": case "exec": return cmdExecute(flags);
@@ -1062,6 +1469,7 @@ async function main(): Promise<void> {
     case "sessions": return cmdSessions(flags);
     // Browse commands — Kuri browser actions with passive indexing
     case "go": return cmdGo(args, flags);
+    case "submit": return cmdSubmit(flags);
     case "snap": return cmdSnap(flags);
     case "click": return cmdClick(args);
     case "fill": return cmdFill(args);
@@ -1076,6 +1484,7 @@ async function main(): Promise<void> {
     case "eval": return cmdEval(args, flags);
     case "back": return cmdBack();
     case "forward": return cmdForward();
+    case "sync": return cmdSync(flags);
     case "close": return cmdClose();
     case "connect-chrome": return cmdConnectChrome();
     default: info(`Unknown command: ${command}`); printHelp(); process.exit(1);