unbrowse 8.0.0 → 8.1.1

package/bin/unbrowse-wrapper.mjs

@@ -1,12 +1,13 @@
 #!/usr/bin/env node
 
 /**
- * Thin wrapper — execs the compiled binary if available,
- * falls back to the package-managed Node launcher if not.
+ * Thin wrapper — runs an explicitly-provided compiled binary if present (the
+ * UNBROWSE_INSTALL_BINARY_PATH opt-in, used by CI smoke tests), else the package's
+ * readable, unsigned runtime via the launcher. There is NO auto-download fallback —
+ * the readable runtime is the default; the runtime IS the client.
  */
 
 import { existsSync, readFileSync } from "node:fs";
-import { createRequire } from "node:module";
 import { join, dirname } from "node:path";
 import { fileURLToPath } from "node:url";
 import { spawn } from "node:child_process";
@@ -14,21 +15,8 @@ import { unbrowseBinaryName } from "../scripts/release-assets.mjs";
 
 const __dirname = dirname(fileURLToPath(import.meta.url));
 const packageRoot = join(__dirname, "..");
-// Windows ships `unbrowse.exe`; postinstall installs it under that name, so the
-// wrapper must look for the same name (a plain `unbrowse` never exists on win).
 const binaryPath = join(__dirname, unbrowseBinaryName(process.platform));
 const launcherPath = join(__dirname, "unbrowse.js");
-const require = createRequire(import.meta.url);
-
-const REQUIRED_FALLBACK_PACKAGES = [
-  "tsx",
-  "bs58",
-  "@solana/kit",
-];
-
-const KNOWN_BAD_FALLBACK_VERSIONS = new Set([
-  "2.10.2",
-]);
 
 function readInstalledVersion() {
   try {
@@ -54,18 +42,6 @@ function failInstall(reason, exitCode = 1) {
   process.exit(exitCode);
 }
 
-function missingFallbackPackages() {
-  const missing = [];
-  for (const specifier of REQUIRED_FALLBACK_PACKAGES) {
-    try {
-      require.resolve(specifier);
-    } catch {
-      missing.push(specifier);
-    }
-  }
-  return missing;
-}
-
 function spawnEntrypoint(command, args) {
   const child = spawn(command, args, {
     stdio: "inherit",
@@ -91,19 +67,11 @@ if (process.argv.includes("--version") || process.argv.includes("-v")) {
 }
 
 if (existsSync(binaryPath)) {
+  // an explicitly-injected binary (UNBROWSE_INSTALL_BINARY_PATH) — not a fallback
   spawnEntrypoint(binaryPath, process.argv.slice(2));
 } else {
-  const installedVersion = readInstalledVersion();
-  if (KNOWN_BAD_FALLBACK_VERSIONS.has(installedVersion)) {
-    failInstall(
-      `Installed package version ${installedVersion} is known-bad in source fallback mode and shipped an incomplete runtime dependency set.`,
-    );
-  }
-
-  const missing = missingFallbackPackages();
-  if (missing.length > 0) {
-    failInstall(`Fallback runtime is missing required packages: ${missing.join(", ")}.`);
-  }
-
+  // the default: the readable, unsigned runtime via the launcher. The source IS the
+  // runtime, so the client is auditable on disk — security lives in the wallet-sealed
+  // crypto, not in hiding the client. The hole fills any internet gap.
   spawnEntrypoint(process.execPath, [launcherPath, ...process.argv.slice(2)]);
 }

package/bin/unbrowse.js

@@ -1,50 +1,63 @@
 #!/usr/bin/env node
 
-// Fallback stub. The real runtime is the native binary at bin/unbrowse,
-// downloaded by scripts/postinstall.mjs from the GitHub release. This file
-// only runs if the wrapper could not find that binary, which means either:
-//   1. The postinstall download was skipped (CI / UNBROWSE_SKIP_BINARY_DOWNLOAD).
-//   2. The download failed (network issue, GH release unavailable).
-//   3. The platform is not in SUPPORTED_TARGETS (rare).
-//
-// In all three cases, the npm tarball intentionally does NOT ship the JS
-// runtime, so there is nothing to fall back to. Print a clear repair message
-// and exit; users should re-run install or build from source.
-
-import { readFileSync } from "node:fs";
+/**
+ * Auditable runtime launcher.
+ *
+ * The package ships a READABLE, UNSIGNED runtime at `runtime/cli.js` (an
+ * unminified Bun bundle of the source) and runs it here. The source IS the
+ * runtime, so the client — including the zk/crypto verification path — is fully
+ * auditable on disk. There is nothing to hide: every secret is wallet-sealed
+ * (AES-GCM under a key only the holder derives), so reverse-engineering the
+ * client yields nothing. Security lives in the wallet, not in obfuscation.
+ *
+ * The runtime requires Bun. If a compiled binary was downloaded post-install,
+ * the wrapper runs that instead and never reaches this launcher.
+ */
+
+import { existsSync } from "node:fs";
 import { dirname, join } from "node:path";
 import { fileURLToPath } from "node:url";
+import { spawnSync } from "node:child_process";
+
+const here = dirname(fileURLToPath(import.meta.url));
+const runtime = join(here, "..", "runtime", "cli.js");
 
-const packageRoot = dirname(dirname(fileURLToPath(import.meta.url)));
+function fail(msg, code = 1) {
+  process.stderr.write(`[unbrowse] ${msg}\n`);
+  process.exit(code);
+}
 
-function readVersion() {
-  try {
-    const pkg = JSON.parse(readFileSync(join(packageRoot, "package.json"), "utf8"));
-    return typeof pkg.version === "string" ? pkg.version : "unknown";
-  } catch {
-    return "unknown";
+function findBun() {
+  const candidates = [
+    process.env.UNBROWSE_BUN_BIN,
+    "bun",
+    join(process.env.HOME || "", ".bun", "bin", "bun"),
+  ].filter(Boolean);
+  for (const candidate of candidates) {
+    try {
+      const probe = spawnSync(candidate, ["--version"], { stdio: "ignore" });
+      if (probe.status === 0) return candidate;
+    } catch {
+      /* try the next candidate */
+    }
   }
+  return null;
+}
+
+if (!existsSync(runtime)) {
+  fail("readable runtime missing (runtime/cli.js). Reinstall: npm install -g unbrowse@latest");
+}
+
+const bun = findBun();
+if (!bun) {
+  fail("this build runs on Bun. Install it from https://bun.sh, then re-run (or set UNBROWSE_BUN_BIN).");
 }
 
-const version = readVersion();
-const target = `${process.platform}-${process.arch}`;
-
-process.stderr.write(
-  [
-    "[unbrowse] native binary not installed",
-    `[unbrowse] package version: ${version}`,
-    `[unbrowse] platform: ${target}`,
-    "",
-    "[unbrowse] The npm package ships only the native binary downloaded on",
-    "[unbrowse] postinstall. Possible causes:",
-    "[unbrowse]   - postinstall was skipped (CI / UNBROWSE_SKIP_BINARY_DOWNLOAD)",
-    "[unbrowse]   - download failed (check stderr from `npm install`)",
-    "[unbrowse]   - platform is not in the prebuilt set",
-    "",
-    "[unbrowse] Repair:",
-    "[unbrowse]   node packages/skill/scripts/postinstall.mjs   # retry download",
-    "[unbrowse]   npm uninstall -g unbrowse && npm install -g unbrowse@latest",
-    "[unbrowse]   build from source: https://github.com/unbrowse-ai/unbrowse",
-  ].join("\n") + "\n",
-);
-process.exit(1);
+const child = spawnSync(bun, [runtime, ...process.argv.slice(2)], {
+  stdio: "inherit",
+  cwd: process.cwd(),
+  env: process.env,
+});
+if (child.error) fail(`failed to launch runtime: ${child.error.message}`);
+if (child.signal) process.kill(process.pid, child.signal);
+process.exit(child.status ?? 1);

package/dist-sdk/adapters/browser-use.d.ts

@@ -0,0 +1,28 @@
+/**
+ * src/sdk/adapters/browser-use.ts — drop-in shape for the `browser-use` Agent.
+ *
+ * Same construction (`new Agent({ task, llm })`) and `.run()` — but the task is filled
+ * through the wallet-sealed unbrowse hole (resolve → execute → capture) instead of a
+ * driven headful browser. `llm` is accepted for signature compatibility; the hole
+ * decides when a real browser is actually needed (browser-open is the fallback, not the
+ * substrate).
+ */
+import { type HoleItem, type HoleOptions } from "../hole.js";
+export interface AgentOptions extends HoleOptions {
+    task: string;
+    llm?: unknown;
+    maxSteps?: number;
+}
+export interface AgentResult {
+    task: string;
+    done: boolean;
+    result: string;
+    items: HoleItem[];
+}
+export declare class Agent {
+    private readonly hole;
+    private readonly task;
+    constructor(options: AgentOptions);
+    run(): Promise<AgentResult>;
+}
+export default Agent;

package/dist-sdk/adapters/browser-use.js

@@ -0,0 +1,28 @@
+/**
+ * src/sdk/adapters/browser-use.ts — drop-in shape for the `browser-use` Agent.
+ *
+ * Same construction (`new Agent({ task, llm })`) and `.run()` — but the task is filled
+ * through the wallet-sealed unbrowse hole (resolve → execute → capture) instead of a
+ * driven headful browser. `llm` is accepted for signature compatibility; the hole
+ * decides when a real browser is actually needed (browser-open is the fallback, not the
+ * substrate).
+ */
+import { createHole } from "../hole.js";
+export class Agent {
+    hole;
+    task;
+    constructor(options) {
+        this.task = options.task;
+        this.hole = createHole(options);
+    }
+    async run() {
+        const r = await this.hole.fill({ intent: this.task });
+        return {
+            task: this.task,
+            done: r.ok,
+            result: r.answer ?? r.items[0]?.text ?? "",
+            items: r.items,
+        };
+    }
+}
+export default Agent;

package/dist-sdk/adapters/exa.d.ts

@@ -0,0 +1,49 @@
+/**
+ * src/sdk/adapters/exa.ts — drop-in replacement for the `exa-js` client.
+ *
+ * Same construction (`new Exa(apiKey)`) and the same method shapes (`search`,
+ * `searchAndContents`, `getContents`, `answer`) returning exa-shaped results — but every
+ * call routes through the wallet-sealed unbrowse hole instead of Exa's API. Swap the
+ * import, keep your code. Inject a `transport`/`wallet` (HoleOptions) for tests or to
+ * bind the hole to a wallet.
+ */
+import { type HoleOptions } from "../hole.js";
+export interface ExaSearchOptions {
+    numResults?: number;
+    type?: string;
+    includeDomains?: string[];
+    startPublishedDate?: string;
+    contents?: {
+        text?: boolean;
+        highlights?: boolean;
+        summary?: boolean;
+    };
+    [key: string]: unknown;
+}
+export interface ExaResult {
+    title: string | null;
+    url: string;
+    publishedDate?: string;
+    score?: number;
+    text?: string;
+    highlights?: string[];
+    summary?: string;
+}
+export interface ExaSearchResponse {
+    results: ExaResult[];
+    autopromptString?: string;
+}
+export declare class Exa {
+    private readonly hole;
+    constructor(_apiKey?: string, opts?: HoleOptions);
+    search(query: string, options?: ExaSearchOptions): Promise<ExaSearchResponse>;
+    searchAndContents(query: string, options?: ExaSearchOptions): Promise<ExaSearchResponse>;
+    getContents(urls: string[], _options?: {
+        text?: boolean;
+        highlights?: boolean;
+    }): Promise<ExaSearchResponse>;
+    answer(question: string): Promise<{
+        answer: string;
+    }>;
+}
+export default Exa;

package/dist-sdk/adapters/exa.js

@@ -0,0 +1,50 @@
+/**
+ * src/sdk/adapters/exa.ts — drop-in replacement for the `exa-js` client.
+ *
+ * Same construction (`new Exa(apiKey)`) and the same method shapes (`search`,
+ * `searchAndContents`, `getContents`, `answer`) returning exa-shaped results — but every
+ * call routes through the wallet-sealed unbrowse hole instead of Exa's API. Swap the
+ * import, keep your code. Inject a `transport`/`wallet` (HoleOptions) for tests or to
+ * bind the hole to a wallet.
+ */
+import { createHole } from "../hole.js";
+function toExa(it) {
+    return {
+        title: it.title ?? null,
+        url: it.url ?? "",
+        publishedDate: it.publishedDate,
+        score: it.score,
+        text: typeof it.text === "string" ? it.text : undefined,
+        highlights: Array.isArray(it.highlights) ? it.highlights : undefined,
+        summary: typeof it.summary === "string" ? it.summary : undefined,
+    };
+}
+export class Exa {
+    hole;
+    constructor(_apiKey, opts = {}) {
+        this.hole = createHole(opts);
+    }
+    async search(query, options = {}) {
+        const r = await this.hole.fill({ intent: query, params: options });
+        const n = options.numResults ?? r.items.length;
+        return { results: r.items.slice(0, n).map(toExa) };
+    }
+    async searchAndContents(query, options = {}) {
+        return this.search(query, { ...options, contents: { text: true, ...(options.contents ?? {}) } });
+    }
+    async getContents(urls, _options = {}) {
+        const results = [];
+        for (const url of urls) {
+            const r = await this.hole.fill({ intent: `contents of ${url}`, url });
+            const first = r.items[0];
+            if (first)
+                results.push(toExa({ ...first, url }));
+        }
+        return { results };
+    }
+    async answer(question) {
+        const r = await this.hole.fill({ intent: question });
+        return { answer: r.answer ?? r.items[0]?.text ?? "" };
+    }
+}
+export default Exa;

package/dist-sdk/adapters/index.d.ts

@@ -0,0 +1,16 @@
+/**
+ * src/sdk/adapters/index.ts — drop-in client adapters over the unbrowse hole.
+ *
+ * Each adapter mirrors a popular client's construction + method shapes, so swapping the
+ * import is the only change needed:
+ *
+ *   import Exa from "@unbrowse/sdk/adapters/exa";          // was: import Exa from "exa-js"
+ *   import { tavily } from "@unbrowse/sdk/adapters/tavily"; // was: from "@tavily/core"
+ *   import { Agent } from "@unbrowse/sdk/adapters/browser-use";
+ *
+ * All of them wrap the same wallet-sealed streaming hole (`../hole.ts`).
+ */
+export { Exa, type ExaResult, type ExaSearchResponse, type ExaSearchOptions } from "./exa.js";
+export { tavily, type TavilyClient, type TavilyResult, type TavilySearchResponse } from "./tavily.js";
+export { Agent, type AgentOptions, type AgentResult } from "./browser-use.js";
+export { createHole, Hole, type HoleRequest, type HoleResult, type HoleItem, type HoleOptions, type HoleTransport, type WalletSeal, } from "../hole.js";

package/dist-sdk/adapters/index.js

@@ -0,0 +1,16 @@
+/**
+ * src/sdk/adapters/index.ts — drop-in client adapters over the unbrowse hole.
+ *
+ * Each adapter mirrors a popular client's construction + method shapes, so swapping the
+ * import is the only change needed:
+ *
+ *   import Exa from "@unbrowse/sdk/adapters/exa";          // was: import Exa from "exa-js"
+ *   import { tavily } from "@unbrowse/sdk/adapters/tavily"; // was: from "@tavily/core"
+ *   import { Agent } from "@unbrowse/sdk/adapters/browser-use";
+ *
+ * All of them wrap the same wallet-sealed streaming hole (`../hole.ts`).
+ */
+export { Exa } from "./exa.js";
+export { tavily } from "./tavily.js";
+export { Agent } from "./browser-use.js";
+export { createHole, Hole, } from "../hole.js";

package/dist-sdk/adapters/tavily.d.ts

@@ -0,0 +1,36 @@
+/**
+ * src/sdk/adapters/tavily.ts — drop-in replacement for the `@tavily/core` client.
+ *
+ * Same construction (`tavily({ apiKey })`) and the same methods (`search`, `extract`)
+ * returning tavily-shaped responses — routed through the wallet-sealed unbrowse hole.
+ */
+import { type HoleOptions } from "../hole.js";
+export interface TavilyResult {
+    title: string;
+    url: string;
+    content: string;
+    score: number;
+    rawContent?: string;
+}
+export interface TavilySearchResponse {
+    query: string;
+    answer?: string;
+    results: TavilyResult[];
+    responseTime?: number;
+}
+export interface TavilyExtractResponse {
+    results: Array<{
+        url: string;
+        rawContent: string;
+    }>;
+    failedResults: string[];
+}
+export interface TavilyOptions extends HoleOptions {
+    apiKey?: string;
+}
+export interface TavilyClient {
+    search(query: string, options?: Record<string, unknown>): Promise<TavilySearchResponse>;
+    extract(urls: string[]): Promise<TavilyExtractResponse>;
+}
+export declare function tavily(options?: TavilyOptions): TavilyClient;
+export default tavily;

package/dist-sdk/adapters/tavily.js

@@ -0,0 +1,39 @@
+/**
+ * src/sdk/adapters/tavily.ts — drop-in replacement for the `@tavily/core` client.
+ *
+ * Same construction (`tavily({ apiKey })`) and the same methods (`search`, `extract`)
+ * returning tavily-shaped responses — routed through the wallet-sealed unbrowse hole.
+ */
+import { createHole } from "../hole.js";
+function toTavily(it) {
+    return {
+        title: it.title ?? "",
+        url: it.url ?? "",
+        content: typeof it.text === "string" ? it.text : "",
+        score: typeof it.score === "number" ? it.score : 0,
+        rawContent: typeof it.rawContent === "string" ? it.rawContent : undefined,
+    };
+}
+export function tavily(options = {}) {
+    const hole = createHole(options);
+    return {
+        async search(query, opts = {}) {
+            const r = await hole.fill({ intent: query, params: opts });
+            return { query, answer: r.answer, results: r.items.map(toTavily) };
+        },
+        async extract(urls) {
+            const results = [];
+            const failedResults = [];
+            for (const url of urls) {
+                const r = await hole.fill({ intent: `extract ${url}`, url });
+                const text = r.items[0]?.text;
+                if (typeof text === "string" && text)
+                    results.push({ url, rawContent: text });
+                else
+                    failedResults.push(url);
+            }
+            return { results, failedResults };
+        },
+    };
+}
+export default tavily;

package/dist-sdk/hole.d.ts

@@ -0,0 +1,119 @@
+import type { UnbrowseClientOptions } from "./types.js";
+/** What the caller hands the hole: an intent, optionally scoped to a URL. */
+export interface HoleRequest {
+    intent: string;
+    url?: string;
+    params?: Record<string, unknown>;
+    /** Perform an ACTION (execute / fill / submit) rather than just read/search. */
+    act?: boolean;
+    /** Override the hole's auto-index default for this one request. */
+    autoIndex?: boolean;
+}
+/** A reusable route the hole learned while filling a gap (what gets indexed). */
+export interface HoleSkill {
+    domain?: string;
+    name?: string;
+    description?: string;
+}
+/** Payload handed to the index hook when a captured route is auto-indexed. */
+export interface IndexInfo {
+    intent: string;
+    skill: HoleSkill;
+    items: HoleItem[];
+}
+/** One normalized result item — the lingua franca every adapter reshapes from. */
+export interface HoleItem {
+    title?: string;
+    url?: string;
+    text?: string;
+    score?: number;
+    publishedDate?: string;
+    [key: string]: unknown;
+}
+/** A wallet attestation attached when the hole is sealed (the zk'd hole). */
+export interface HoleSeal {
+    walletPubkey: string;
+    signature: string;
+}
+export interface HoleResult {
+    ok: boolean;
+    intent: string;
+    items: HoleItem[];
+    answer?: string;
+    source?: string;
+    raw?: unknown;
+    seal?: HoleSeal;
+    /** True when filling required a fresh capture (a new route was learned). */
+    captured?: boolean;
+    /** The learned route, when captured — what the auto-index hook receives. */
+    skill?: HoleSkill;
+    /** True when this fill auto-indexed the captured route. */
+    indexed?: boolean;
+}
+/** The pluggable backend: turn a request into normalized items. */
+export type HoleTransport = (req: HoleRequest) => Promise<Omit<HoleResult, "seal">>;
+/** Minimal wallet signer the hole seals to (any Ed25519-style signer fits). */
+export interface WalletSeal {
+    sign(message: Uint8Array): Promise<{
+        signature: Uint8Array;
+        walletPubkey: Uint8Array;
+    }>;
+}
+export interface HoleOptions {
+    transport?: HoleTransport;
+    wallet?: WalletSeal;
+    client?: UnbrowseClientOptions;
+    /** Auto-index captured routes after a fill (default true). */
+    autoIndex?: boolean;
+    /**
+     * Generate a name + description for a captured route (default true). We generate
+     * descriptions for the user, not the other way round — a zero-cost deterministic
+     * baseline always, enriched by the `generate` hook (a cheap model) when provided.
+     * Set false only if you truly want routes indexed with no description.
+     */
+    describe?: boolean;
+    /**
+     * Where a captured route is sent to be indexed — the discover → publish loop.
+     * Wire this to the CLI's `queueBackgroundIndex`; left unset, fills still work but
+     * nothing is indexed (result.indexed = false).
+     */
+    index?: (info: IndexInfo) => Promise<void> | void;
+    /**
+     * Client-side LLM used to "index it nicely" — name + describe a captured route.
+     * Keeps generation ON THE CLIENT (the agent's own model); no server round-trip.
+     * Given the captured route, return a short "<name> — <description>".
+     */
+    generate?: (prompt: string) => Promise<string> | string;
+}
+/**
+ * Zero-cost deterministic name + description for a captured route. The always-on baseline
+ * so a learned route is never left undescribed and the USER never has to write one; the
+ * optional `generate` hook (a cheap model) enriches this when present.
+ */
+export declare function defaultDescribe(intent: string, skill: HoleSkill, items: HoleItem[]): {
+    name: string;
+    description: string;
+};
+/** Stable bytes to sign — key order fixed so client and verifier agree. */
+export declare function canonicalRequest(req: HoleRequest): Uint8Array;
+/** The hole. One method that matters: `fill`. Stream with `stream`. */
+export declare class Hole {
+    private readonly transport;
+    private readonly wallet?;
+    private readonly autoIndex;
+    private readonly describe;
+    private readonly index?;
+    private readonly generate?;
+    constructor(opts?: HoleOptions);
+    /**
+     * Fill the gap — READ (search) or ACT (execute/fill/submit, when `req.act`). When the
+     * hole is wallet-bound the result carries a seal. When the fill required a fresh
+     * capture, the route is auto-indexed (named/described by the client-side `generate`
+     * hook, then handed to `index`) — the discover → publish loop, on the client.
+     */
+    fill(req: HoleRequest): Promise<HoleResult>;
+    /** Stream the filled items one at a time (the "streaming shit into it" surface). */
+    stream(req: HoleRequest): AsyncIterable<HoleItem>;
+}
+/** Construct a hole. With `wallet`, it is the zk'd, wallet-protected hole. */
+export declare function createHole(opts?: HoleOptions): Hole;