unbrowse 6.0.0 → 6.1.0

package/dist/cli.js

@@ -31,7 +31,7 @@ var __promiseAll = (args) => Promise.all(args);
 var __require = /* @__PURE__ */ createRequire(import.meta.url);
 
 // ../../src/build-info.generated.ts
-var BUILD_RELEASE_VERSION = "6.0.0", BUILD_GIT_SHA = "8fcfc70b7c85", BUILD_CODE_HASH = "5d9ebf619c61", BUILD_RELEASE_MANIFEST_BASE64 = "eyJzY2hlbWFfdmVyc2lvbiI6MSwicmVsZWFzZV92ZXJzaW9uIjoiNi4wLjAiLCJnaXRfc2hhIjoiOGZjZmM3MGI3Yzg1IiwiY29kZV9oYXNoIjoiNWQ5ZWJmNjE5YzYxIiwidHJhY2VfdmVyc2lvbiI6IjVkOWViZjYxOWM2MUA4ZmNmYzcwYjdjODUiLCJpc3N1ZWRfYXQiOiIyMDI2LTA0LTI1VDA3OjEzOjM5LjA4OVoifQ", BUILD_RELEASE_MANIFEST_SIGNATURE = "Q1wr0wTssyMdAzr8NiQQCthMcYPK3d1HYGqnlqq01L0", BUILD_DEFAULT_BACKEND_URL = "https://beta-api.unbrowse.ai";
+var BUILD_RELEASE_VERSION = "6.1.0", BUILD_GIT_SHA = "82d14e507af6", BUILD_CODE_HASH = "5d9ebf619c61", BUILD_RELEASE_MANIFEST_BASE64 = "eyJzY2hlbWFfdmVyc2lvbiI6MSwicmVsZWFzZV92ZXJzaW9uIjoiNi4xLjAiLCJnaXRfc2hhIjoiODJkMTRlNTA3YWY2IiwiY29kZV9oYXNoIjoiNWQ5ZWJmNjE5YzYxIiwidHJhY2VfdmVyc2lvbiI6IjVkOWViZjYxOWM2MUA4MmQxNGU1MDdhZjYiLCJpc3N1ZWRfYXQiOiIyMDI2LTA1LTAxVDAwOjI1OjUwLjExMFoifQ", BUILD_RELEASE_MANIFEST_SIGNATURE = "gOz02sMxkYuLKvc24oN5EVm8VEQo2dftkUpMS5RMjiE", BUILD_DEFAULT_BACKEND_URL = "https://beta-api.unbrowse.ai";
 
 // ../../src/version.ts
 import { createHash } from "crypto";
@@ -3109,6 +3109,10 @@ The Unbrowse Terms of Service have been updated.`);
 async function ensureRegistered(options) {
   if (LOCAL_ONLY)
     return;
+  if (process.env.UNBROWSE_SKIP_TOS_CHECK === "1") {
+    console.log("[unbrowse] ToS check skipped (non-interactive/server mode)");
+    return;
+  }
   const exitOnFailure = options?.exitOnFailure ?? true;
   const usableKey = await findUsableApiKey();
   if (usableKey) {
@@ -4428,12 +4432,22 @@ function parseArgs(argv) {
   const rest = command === "help" ? raw : raw.slice(1);
   const positional = [];
   const flags = {};
+  const params = {};
   for (let i = 0;i < rest.length; i++) {
     const a = rest[i];
-    if (a.startsWith("--")) {
+    if (a === "-p" || a === "--param") {
+      const next = rest[i + 1];
+      if (next && next.includes("=")) {
+        const eq = next.indexOf("=");
+        params[next.slice(0, eq)] = next.slice(eq + 1);
+        i++;
+      } else {
+        die(`-p requires key=value, got: ${next ?? "<end of args>"}`);
+      }
+    } else if (a.startsWith("--")) {
       const key = a.slice(2);
       const next = rest[i + 1];
-      if (!next || next.startsWith("--")) {
+      if (!next || next.startsWith("--") || next === "-p" || next === "--param") {
         flags[key] = true;
       } else {
         flags[key] = next;
@@ -4443,7 +4457,7 @@ function parseArgs(argv) {
       positional.push(a);
     }
   }
-  return { command, args: positional, flags };
+  return { command, args: positional, flags, params };
 }
 async function api2(method, path9, body) {
   let target = `${BASE_URL}${path9}`;
@@ -4625,6 +4639,62 @@ function telemetryDomainFromInput(domain, url) {
     return null;
   }
 }
+async function cmdExplain(flags) {
+  const intent = flags.intent;
+  const url = flags.url;
+  const top = parseInt(flags.top ?? "5", 10) || 5;
+  if (!intent || !url) {
+    process.stderr.write(`usage: unbrowse explain --intent "..." --url "..." [--top N]
+`);
+    process.exit(2);
+  }
+  const body = {
+    intent,
+    params: { url },
+    context: { url },
+    projection: { raw: true }
+  };
+  let result;
+  try {
+    result = await api2("POST", "/v1/intent/resolve", body);
+  } catch (err) {
+    process.stderr.write(`explain failed: ${err.message}
+`);
+    process.exit(1);
+  }
+  const r = result.result ?? result;
+  const ae = r.available_endpoints ?? [];
+  const ao = r.available_operations ?? [];
+  const out = {
+    intent,
+    context_url: url,
+    diagnostic: r.diagnostic,
+    shortlist_for_judgment: ae.slice(0, top).map((ep, i) => ({
+      rank: i,
+      endpoint_id: ep.endpoint_id,
+      method: ep.method,
+      url: ep.url,
+      score: ep.score,
+      description: ep.description,
+      input_params: ep.input_params,
+      schema_summary: ep.schema_summary,
+      example_fields: ep.example_fields,
+      sample_values: ep.sample_values,
+      needs_params: ep.needs_params,
+      trigger_url: ep.trigger_url
+    })),
+    agent_facing_shortlist: ao.slice(0, top).map((op, i) => ({
+      rank: i,
+      endpoint_id: op.endpoint_id,
+      method: op.method,
+      url_template: op.url_template ?? op.url,
+      description: op.description_out ?? op.description
+    })),
+    judgment_question: `Given the intent ${JSON.stringify(intent)} on ${JSON.stringify(url)}, ` + `which of the candidate endpoints in shortlist_for_judgment best satisfies the intent? ` + `Reply with the endpoint_id of the best match and a one-line reason. ` + `If none match, say defer_to_capture.`
+  };
+  process.stdout.write(JSON.stringify(out, null, 2) + `
+`);
+}
 async function cmdResolve(flags) {
   const intent = flags.intent;
   if (!intent)
@@ -4886,6 +4956,10 @@ async function cmdExecute(flags) {
     if (flags.params) {
       body.params = { ...body.params, ...JSON.parse(flags.params) };
     }
+    const cliKv = flags._params;
+    if (cliKv && Object.keys(cliKv).length > 0) {
+      body.params = { ...body.params, ...cliKv };
+    }
     if (flags.url) {
       body.context_url = flags.url;
       body.params.url = flags.url;
@@ -4961,16 +5035,17 @@ async function cmdExecute(flags) {
       output(out, !!flags.pretty);
       return;
     }
+    const AUTOEXTRACT_HINT_THRESHOLD = 65536;
     if (!rawFlag && !pathFlag && !extractFlag && !schemaFlag) {
       const raw = JSON.stringify(result.result);
-      if (raw && raw.length > 2048) {
+      if (raw && raw.length > AUTOEXTRACT_HINT_THRESHOLD) {
         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.",
+            message: `Response is ${Math.round(raw.length / 1024)}KB (over ${AUTOEXTRACT_HINT_THRESHOLD / 1024}KB). Use --path/--extract/--limit to filter, --schema for structure, or --raw for full response.`,
             schema_tree: schema,
             response_bytes: raw.length
           }
@@ -5297,8 +5372,9 @@ var CLI_REFERENCE = {
     { 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: "upgrade", usage: "", desc: "Check latest release and print the right upgrade command" },
-    { name: "resolve", usage: '--intent "..." [--domain "..."] [--url "..."] [opts]', desc: "Search cached indexed/published routes and optionally execute the top trusted endpoint" },
-    { name: "execute", usage: "--skill ID --endpoint ID [opts]", desc: "Execute a specific endpoint" },
+    { name: "resolve", usage: '--intent "..." [--domain "..."] [--url "..."] [opts]', desc: "Returns ranked shortlist of endpoints for an intent. Pick one and call execute. (Two tool calls is the contract \u2014 autoexec is opt-in via --execute, not the default.)" },
+    { name: "explain", usage: '--intent "..." --url "..." [--top N]', desc: "Emit top-N candidate endpoints + evidence for an LLM judge to pick from (no heuristic verdict \u2014 primitives + agent judgment)" },
+    { name: "execute", usage: "--skill ID --endpoint ID [-p key=val ...] [--params '{json}'] [opts]", desc: "Execute a specific endpoint. Pass replay params via repeated -p key=val flags or --params with a JSON object" },
     { name: "feedback", usage: "--skill ID --endpoint ID --rating N", desc: "Submit feedback (mandatory after resolve)" },
     { name: "annotate", usage: "--skill ID --endpoint ID --text 'tip' [--constraint 'param:rule:message']", desc: "Contribute best practices or constraints for an endpoint" },
     { name: "review", usage: "--skill ID --endpoints '[...]'", desc: "Push reviewed descriptions/schema metadata back to a captured skill before publish" },
@@ -6206,7 +6282,10 @@ async function cmdConnectChrome() {
   console.error("Could not connect to Chrome. Make sure all Chrome windows are closed and try again.");
 }
 async function main() {
-  const { command, args, flags } = parseArgs(process.argv);
+  const { command, args, flags, params: cliParams } = parseArgs(process.argv);
+  if (Object.keys(cliParams).length > 0) {
+    flags._params = cliParams;
+  }
   const noAutoStart = !!flags["no-auto-start"];
   if (command === "help" || flags.help) {
     printHelp();
@@ -6322,6 +6401,8 @@ async function main() {
       return cmdSetup(flags);
     case "resolve":
       return cmdResolve(flags);
+    case "explain":
+      return cmdExplain(flags);
     case "execute":
     case "exec":
       return cmdExecute(flags);

package/dist/mcp.js

@@ -226,11 +226,11 @@ import { dirname, join, parse } from "path";
 import { fileURLToPath as fileURLToPath2 } from "url";
 
 // ../../src/build-info.generated.ts
-var BUILD_RELEASE_VERSION = "6.0.0";
-var BUILD_GIT_SHA = "8fcfc70b7c85";
+var BUILD_RELEASE_VERSION = "6.1.0";
+var BUILD_GIT_SHA = "82d14e507af6";
 var BUILD_CODE_HASH = "5d9ebf619c61";
-var BUILD_RELEASE_MANIFEST_BASE64 = "eyJzY2hlbWFfdmVyc2lvbiI6MSwicmVsZWFzZV92ZXJzaW9uIjoiNi4wLjAiLCJnaXRfc2hhIjoiOGZjZmM3MGI3Yzg1IiwiY29kZV9oYXNoIjoiNWQ5ZWJmNjE5YzYxIiwidHJhY2VfdmVyc2lvbiI6IjVkOWViZjYxOWM2MUA4ZmNmYzcwYjdjODUiLCJpc3N1ZWRfYXQiOiIyMDI2LTA0LTI1VDA3OjEzOjM5LjA4OVoifQ";
-var BUILD_RELEASE_MANIFEST_SIGNATURE = "Q1wr0wTssyMdAzr8NiQQCthMcYPK3d1HYGqnlqq01L0";
+var BUILD_RELEASE_MANIFEST_BASE64 = "eyJzY2hlbWFfdmVyc2lvbiI6MSwicmVsZWFzZV92ZXJzaW9uIjoiNi4xLjAiLCJnaXRfc2hhIjoiODJkMTRlNTA3YWY2IiwiY29kZV9oYXNoIjoiNWQ5ZWJmNjE5YzYxIiwidHJhY2VfdmVyc2lvbiI6IjVkOWViZjYxOWM2MUA4MmQxNGU1MDdhZjYiLCJpc3N1ZWRfYXQiOiIyMDI2LTA1LTAxVDAwOjI1OjUwLjExMFoifQ";
+var BUILD_RELEASE_MANIFEST_SIGNATURE = "gOz02sMxkYuLKvc24oN5EVm8VEQo2dftkUpMS5RMjiE";
 var BUILD_DEFAULT_BACKEND_URL = "https://beta-api.unbrowse.ai";
 
 // ../../src/version.ts
@@ -1665,7 +1665,7 @@ var tools = [
   },
   {
     name: "unbrowse_resolve",
-    description: "START HERE for every website task. Resolves an intent against cached/published routes. If endpoints are returned, pick one and call unbrowse_execute. If no_cached_match, proceed to unbrowse_go to browse and index the site. Do not call unbrowse_go or unbrowse_execute without calling this first.",
+    description: "START HERE for every website task. Returns ranked shortlist of cached endpoints. Read the shortlist, pick the one that matches your intent (use the example_response_compact and requires fields as evidence), then call unbrowse_execute with that endpoint_id. Two tool calls is the contract \u2014 there is no auto-exec. If no_cached_match, fall through to unbrowse_go to capture fresh.",
     inputSchema: {
       type: "object",
       properties: {
@@ -2525,6 +2525,67 @@ var tools = [
       const result = await api2("POST", `/v1/skills/${skillId}/endpoints/${endpointId}/annotate`, body);
       return successResult(result, "Annotation saved. Other agents will see your contribution when using this endpoint.");
     }
+  },
+  {
+    name: "unbrowse_diagnose",
+    description: "Capture visual + structured context for diagnosing an unbrowse failure. Takes a screenshot of the current page and returns it alongside the current resolve diagnostic. Use when resolve/execute fails and you need to see what the page actually looks like (auth wall, loading spinner, empty state).",
+    inputSchema: {
+      type: "object",
+      properties: {
+        session_id: { type: "string", description: "Optional browse session id." },
+        context: { type: "string", description: "Description of what was being attempted when it failed." }
+      },
+      additionalProperties: false
+    },
+    annotations: { readOnlyHint: true },
+    handler: async (args) => {
+      await ensureServerReady();
+      const sessionId = typeof args.session_id === "string" ? args.session_id : undefined;
+      const screenshot = await api2("GET", "/v1/browse/screenshot", sessionId ? { session_id: sessionId } : undefined);
+      const diagnostic = await api2("GET", "/v1/stats/health", undefined);
+      return successResult({
+        screenshot: typeof screenshot.screenshot === "string" ? screenshot.screenshot : null,
+        tab_id: screenshot.tab_id ?? null,
+        diagnosis_context: args.context ?? null,
+        status: diagnostic
+      }, "Diagnosis capture complete. Screenshot + context returned.");
+    }
+  },
+  {
+    name: "unbrowse_trace",
+    description: "Get the full execution trace for the most recent resolve/execute call, including diagnostic confidence scores, endpoint scores, and visual context. Use to understand WHY a specific endpoint was or wasn't selected.",
+    inputSchema: {
+      type: "object",
+      properties: {
+        trace_id: { type: "string", description: "Optional specific trace ID. Defaults to most recent." }
+      },
+      additionalProperties: false
+    },
+    annotations: { readOnlyHint: true },
+    handler: async (args) => {
+      await ensureServerReady();
+      const result = await api2("GET", `/v1/trace/${args.trace_id ?? "latest"}`, undefined);
+      return successResult(result, "Execution trace with diagnostic context.");
+    }
+  },
+  {
+    name: "unbrowse_validate",
+    description: "Validate a captured skill's quality by taking screenshots of the page while exercising its endpoints. Helps diagnose if a skill's endpoints actually match the live page. Returns screenshots at key interaction points alongside endpoint response data.",
+    inputSchema: {
+      type: "object",
+      properties: {
+        skill_id: { type: "string", description: "Skill ID to validate." },
+        url: { type: "string", description: "Page URL to validate against." }
+      },
+      required: ["skill_id"],
+      additionalProperties: false
+    },
+    annotations: { openWorldHint: true },
+    handler: async (args) => {
+      await ensureServerReady();
+      const result = await api2("GET", `/v1/skills/${args.skill_id}/validate`, args.url ? { url: args.url } : undefined);
+      return successResult(result, "Skill validation complete. Returns screenshots + endpoint match quality.");
+    }
   }
 ];
 var toolMap = new Map(tools.map((tool) => [tool.name, tool]));