@huyuan-ai/cli 1.0.0 → 1.0.2

package/package.json

@@ -1,22 +1,29 @@
 {
   "name": "@huyuan-ai/cli",
-  "version": "1.0.0",
+  "version": "1.0.2",
   "publishConfig": {
     "access": "public"
   },
-  "description": "",
+  "description": "企业场景下的 AI 助手与技能管理命令行工具（@huyuan-ai/cli，命令 huyuan-ai-cli）。集成 OpenCLI 与私有技能安装。",
   "type": "module",
   "main": "dist/index.js",
   "bin": {
     "huyuan-ai-cli": "./dist/index.js"
   },
   "scripts": {
-    "build": "npm install --prefix vendor/opencli && npm run build --prefix vendor/opencli && tsc",
+    "build": "node scripts/write-opencli-npmignore.mjs && npm install --prefix vendor/opencli && npm run build --prefix vendor/opencli && tsc",
     "build:tsc": "tsc",
     "typecheck": "tsc --noEmit",
+    "prepublishOnly": "node scripts/publish-prepare-readme.mjs && npm run build",
+    "postpublish": "node scripts/publish-restore-package-json.mjs",
     "test": "echo \"Error: no test specified\" && exit 1"
   },
-  "keywords": [],
+  "keywords": [
+    "cli",
+    "ai",
+    "huyuan",
+    "skills"
+  ],
   "author": "",
   "license": "ISC",
   "files": [
@@ -36,5 +43,6 @@
     "commander": "^14.0.3",
     "conf": "^15.1.0",
     "execa": "^9.6.1"
-  }
-}
+  },
+  "readme": "# `@huyuan-ai/cli`\n\n企业场景下的 AI 助手与技能管理命令行工具。**npm 包名**为 **`@huyuan-ai/cli`**，安装后**命令行入口**为 **`huyuan-ai-cli`**（见 `package.json` 的 `bin`）。集成 [OpenCLI](https://github.com/jackwener/opencli)（Git Submodule）用于浏览器侧能力（如豆包对话），并通过自研 **Token Gateway** 与 **`npx skills`** 安装私有技能。\n\n## 从 npm 全局安装\n\n```bash\nnpm install -g @huyuan-ai/cli\nhuyuan-ai-cli --help\n```\n\n## 功能概览\n\n- **登录**：将企业授权 Key 写入 `~/.huyuan-ai/config.json`\n- **安装技能**：用 Key 向网关换取短期令牌后，执行 `npx skills add` 拉取私有仓库技能\n- **豆包对话**：`doubao ask` 在 OpenCLI 已加载的 registry 上执行 `doubao/ask`（需已登录，且依赖 OpenCLI 浏览器/Bridge 环境）\n\n更细的架构、目录约定与开发约束见 **[AGENTS.md](./AGENTS.md)**。\n\n## 环境要求\n\n- **Node.js**：建议 ≥ 20（与 OpenCLI 子模块一致）\n- **包管理**：推荐 **pnpm**（仓库已声明 `packageManager`）\n\n## 从源码构建与运行\n\n1. 克隆并初始化子模块：\n\n   ```bash\n   git clone --recurse-submodules <repo-url>\n   cd huyuan-ai-cli\n   ```\n\n   若已克隆未带子模块：`git submodule update --init --recursive`\n\n2. 安装主项目依赖：\n\n   ```bash\n   pnpm install\n   ```\n\n3. **一键构建**（先安装并构建 `vendor/opencli`，再 `tsc` 编译本仓库；发布前也请执行此步）：\n\n   ```bash\n   pnpm run build\n   ```\n\n   若仅改本仓库 `src/`、且子模块 `dist/` 已是最新，可改用 `pnpm run build:tsc` 只跑 TypeScript，加快迭代。\n\n4. 运行 CLI：\n\n   ```bash\n   node dist/index.js --help\n   ```\n\n   全局链接（可选）：`pnpm link --global`，之后可直接使用 `huyuan-ai-cli`。\n\n## 常用命令\n\n| 命令 | 说明 |\n|------|------|\n| `huyuan-ai-cli login <key>` | 保存企业授权 Key |\n| `huyuan-ai-cli install <skill>` | 从私有技能库安装（需配置网关环境变量） |\n| `huyuan-ai-cli doubao ask <prompt>` | 豆包对话（需已 `login`） |\n\n查看子命令帮助：`huyuan-ai-cli doubao ask --help`\n\n## 环境变量（安装技能）\n\n| 变量 | 说明 |\n|------|------|\n| `HUYUAN_TOKEN_GATEWAY_URL` | Token Gateway 根地址（如 `https://your-app.vercel.app`），详见 [src/constants.ts](src/constants.ts) |\n| `HUYUAN_SKILL_GITHUB_ORG` | 可选，默认 `WeDAOLabs` |\n\n## 脚本\n\n| 脚本 | 说明 |\n|------|------|\n| `pnpm run build` | 构建 `vendor/opencli`（`npm install` + `npm run build`）后 `tsc` 编译到 `dist/` |\n| `pnpm run build:tsc` | 仅 `tsc`（子模块已有 `dist/` 时用） |\n| `pnpm run typecheck` | `tsc --noEmit` |\n\n## 仓库结构（摘要）\n\n```\nsrc/\n  index.ts                 # 入口\n  cli/program.ts           # Commander 装配\n  core/                    # 登录、安装等平台能力\n  sites/doubao/            # 豆包子命令（可扩展其他 sites）\n  integrations/opencli/    # OpenCLI bootstrap 与 registry 执行封装\n  utils/config.ts          # 本地配置\n  constants.ts             # 网关等常量与环境变量\nvendor/opencli/            # OpenCLI 子模块（需单独 build）\n```\n\n## 许可证\n\nISC（见 [package.json](package.json)）。\n"
+}

package/vendor/opencli/dist/analysis.d.ts

@@ -0,0 +1,38 @@
+/**
+ * Shared API analysis helpers used by both explore.ts and record.ts.
+ *
+ * Extracts common logic for:
+ *   - URL pattern normalization
+ *   - Array path discovery in JSON responses
+ *   - Field role detection
+ *   - Auth indicator inference
+ *   - Capability name inference
+ *   - Strategy inference
+ */
+/** Normalize a full URL into a pattern (replace IDs, strip volatile params). */
+export declare function urlToPattern(url: string): string;
+export interface ArrayDiscovery {
+    path: string;
+    items: unknown[];
+}
+/** Find the best (largest) array of objects in a JSON response body. */
+export declare function findArrayPath(obj: unknown, depth?: number): ArrayDiscovery | null;
+/** Flatten nested object keys up to maxDepth. */
+export declare function flattenFields(obj: unknown, prefix: string, maxDepth: number): string[];
+/** Detect semantic field roles (title, url, author, etc.) from sample fields. */
+export declare function detectFieldRoles(sampleFields: string[]): Record<string, string>;
+/** Infer a CLI capability name from a URL. */
+export declare function inferCapabilityName(url: string, goal?: string): string;
+/** Infer auth strategy from detected indicators. */
+export declare function inferStrategy(authIndicators: string[]): string;
+/** Detect auth indicators from HTTP headers. */
+export declare function detectAuthFromHeaders(headers?: Record<string, string>): string[];
+/** Detect auth indicators from URL and response body (heuristic). */
+export declare function detectAuthFromContent(url: string, body: unknown): string[];
+/** Extract non-volatile query params and classify them. */
+export declare function classifyQueryParams(url: string): {
+    params: string[];
+    hasSearch: boolean;
+    hasPagination: boolean;
+    hasLimit: boolean;
+};

package/vendor/opencli/dist/analysis.js

@@ -0,0 +1,166 @@
+/**
+ * Shared API analysis helpers used by both explore.ts and record.ts.
+ *
+ * Extracts common logic for:
+ *   - URL pattern normalization
+ *   - Array path discovery in JSON responses
+ *   - Field role detection
+ *   - Auth indicator inference
+ *   - Capability name inference
+ *   - Strategy inference
+ */
+import { VOLATILE_PARAMS, SEARCH_PARAMS, PAGINATION_PARAMS, LIMIT_PARAMS, FIELD_ROLES, } from './constants.js';
+// ── URL pattern normalization ───────────────────────────────────────────────
+/** Normalize a full URL into a pattern (replace IDs, strip volatile params). */
+export function urlToPattern(url) {
+    try {
+        const p = new URL(url);
+        const pathNorm = p.pathname
+            .replace(/\/\d+/g, '/{id}')
+            .replace(/\/[0-9a-fA-F]{8,}/g, '/{hex}')
+            .replace(/\/BV[a-zA-Z0-9]{10}/g, '/{bvid}');
+        const params = [];
+        p.searchParams.forEach((_v, k) => { if (!VOLATILE_PARAMS.has(k))
+            params.push(k); });
+        return `${p.host}${pathNorm}${params.length ? '?' + params.sort().map(k => `${k}={}`).join('&') : ''}`;
+    }
+    catch {
+        return url;
+    }
+}
+/** Find the best (largest) array of objects in a JSON response body. */
+export function findArrayPath(obj, depth = 0) {
+    if (depth > 5 || !obj || typeof obj !== 'object')
+        return null;
+    if (Array.isArray(obj)) {
+        if (obj.length >= 2 && obj.some(i => i && typeof i === 'object' && !Array.isArray(i))) {
+            return { path: '', items: obj };
+        }
+        return null;
+    }
+    let best = null;
+    for (const [key, val] of Object.entries(obj)) {
+        const found = findArrayPath(val, depth + 1);
+        if (found) {
+            const fullPath = found.path ? `${key}.${found.path}` : key;
+            const candidate = { path: fullPath, items: found.items };
+            if (!best || candidate.items.length > best.items.length)
+                best = candidate;
+        }
+    }
+    return best;
+}
+// ── Field flattening & role detection ───────────────────────────────────────
+/** Flatten nested object keys up to maxDepth. */
+export function flattenFields(obj, prefix, maxDepth) {
+    if (maxDepth <= 0 || !obj || typeof obj !== 'object')
+        return [];
+    const names = [];
+    const record = obj;
+    for (const key of Object.keys(record)) {
+        const full = prefix ? `${prefix}.${key}` : key;
+        names.push(full);
+        const val = record[key];
+        if (val && typeof val === 'object' && !Array.isArray(val))
+            names.push(...flattenFields(val, full, maxDepth - 1));
+    }
+    return names;
+}
+/** Detect semantic field roles (title, url, author, etc.) from sample fields. */
+export function detectFieldRoles(sampleFields) {
+    const detectedFields = {};
+    for (const [role, aliases] of Object.entries(FIELD_ROLES)) {
+        for (const f of sampleFields) {
+            if (aliases.includes(f.split('.').pop()?.toLowerCase() ?? '')) {
+                detectedFields[role] = f;
+                break;
+            }
+        }
+    }
+    return detectedFields;
+}
+// ── Capability name inference ───────────────────────────────────────────────
+/** Infer a CLI capability name from a URL. */
+export function inferCapabilityName(url, goal) {
+    if (goal)
+        return goal;
+    const u = url.toLowerCase();
+    if (u.includes('hot') || u.includes('popular') || u.includes('ranking') || u.includes('trending'))
+        return 'hot';
+    if (u.includes('search'))
+        return 'search';
+    if (u.includes('feed') || u.includes('timeline') || u.includes('dynamic'))
+        return 'feed';
+    if (u.includes('comment') || u.includes('reply'))
+        return 'comments';
+    if (u.includes('history'))
+        return 'history';
+    if (u.includes('profile') || u.includes('userinfo') || u.includes('/me'))
+        return 'me';
+    if (u.includes('favorite') || u.includes('collect') || u.includes('bookmark'))
+        return 'favorite';
+    try {
+        const segs = new URL(url).pathname
+            .split('/')
+            .filter(s => s && !s.match(/^\d+$/) && !s.match(/^[0-9a-f]{8,}$/i) && !s.match(/^v\d+$/));
+        if (segs.length)
+            return segs[segs.length - 1].replace(/[^a-z0-9]/gi, '_').toLowerCase();
+    }
+    catch { }
+    return 'data';
+}
+// ── Strategy inference ──────────────────────────────────────────────────────
+/** Infer auth strategy from detected indicators. */
+export function inferStrategy(authIndicators) {
+    if (authIndicators.includes('signature'))
+        return 'intercept';
+    if (authIndicators.includes('bearer') || authIndicators.includes('csrf'))
+        return 'header';
+    return 'cookie';
+}
+// ── Auth indicator detection ────────────────────────────────────────────────
+/** Detect auth indicators from HTTP headers. */
+export function detectAuthFromHeaders(headers) {
+    if (!headers)
+        return [];
+    const indicators = [];
+    const keys = Object.keys(headers).map(k => k.toLowerCase());
+    if (keys.some(k => k === 'authorization'))
+        indicators.push('bearer');
+    if (keys.some(k => k.startsWith('x-csrf') || k.startsWith('x-xsrf')))
+        indicators.push('csrf');
+    if (keys.some(k => k.startsWith('x-s') || k === 'x-t' || k === 'x-s-common'))
+        indicators.push('signature');
+    return indicators;
+}
+/** Detect auth indicators from URL and response body (heuristic). */
+export function detectAuthFromContent(url, body) {
+    const indicators = [];
+    if (body && typeof body === 'object') {
+        const keys = Object.keys(body).map(k => k.toLowerCase());
+        if (keys.some(k => k.includes('sign') || k === 'w_rid' || k.includes('token'))) {
+            indicators.push('signature');
+        }
+    }
+    if (url.includes('/wbi/') || url.includes('w_rid='))
+        indicators.push('signature');
+    if (url.includes('bearer') || url.includes('access_token'))
+        indicators.push('bearer');
+    return indicators;
+}
+// ── Query param classification ──────────────────────────────────────────────
+/** Extract non-volatile query params and classify them. */
+export function classifyQueryParams(url) {
+    const params = [];
+    try {
+        new URL(url).searchParams.forEach((_v, k) => { if (!VOLATILE_PARAMS.has(k))
+            params.push(k); });
+    }
+    catch { }
+    return {
+        params,
+        hasSearch: params.some(p => SEARCH_PARAMS.has(p)),
+        hasPagination: params.some(p => PAGINATION_PARAMS.has(p)),
+        hasLimit: params.some(p => LIMIT_PARAMS.has(p)),
+    };
+}

package/vendor/opencli/dist/browser/base-page.d.ts

@@ -0,0 +1,50 @@
+/**
+ * BasePage — shared IPage method implementations for DOM helpers.
+ *
+ * Both Page (daemon-backed) and CDPPage (direct CDP) execute JS the same way
+ * for DOM operations. This base class deduplicates ~200 lines of identical
+ * click/type/scroll/wait/snapshot/interceptor methods.
+ *
+ * Subclasses implement the transport-specific methods: goto, evaluate,
+ * getCookies, screenshot, tabs, etc.
+ */
+import type { BrowserCookie, IPage, ScreenshotOptions, SnapshotOptions, WaitOptions } from '../types.js';
+export declare abstract class BasePage implements IPage {
+    protected _lastUrl: string | null;
+    /** Cached previous snapshot hashes for incremental diff marking */
+    private _prevSnapshotHashes;
+    abstract goto(url: string, options?: {
+        waitUntil?: 'load' | 'none';
+        settleMs?: number;
+    }): Promise<void>;
+    abstract evaluate(js: string): Promise<unknown>;
+    abstract getCookies(opts?: {
+        domain?: string;
+        url?: string;
+    }): Promise<BrowserCookie[]>;
+    abstract screenshot(options?: ScreenshotOptions): Promise<string>;
+    abstract tabs(): Promise<unknown[]>;
+    abstract selectTab(index: number): Promise<void>;
+    click(ref: string): Promise<void>;
+    /** Override in subclasses with CDP native click support */
+    protected tryNativeClick(_x: number, _y: number): Promise<boolean>;
+    typeText(ref: string, text: string): Promise<void>;
+    pressKey(key: string): Promise<void>;
+    scrollTo(ref: string): Promise<unknown>;
+    getFormState(): Promise<Record<string, unknown>>;
+    scroll(direction?: string, amount?: number): Promise<void>;
+    autoScroll(options?: {
+        times?: number;
+        delayMs?: number;
+    }): Promise<void>;
+    networkRequests(includeStatic?: boolean): Promise<unknown[]>;
+    consoleMessages(_level?: string): Promise<unknown[]>;
+    wait(options: number | WaitOptions): Promise<void>;
+    snapshot(opts?: SnapshotOptions): Promise<unknown>;
+    getCurrentUrl(): Promise<string | null>;
+    installInterceptor(pattern: string): Promise<void>;
+    getInterceptedRequests(): Promise<unknown[]>;
+    waitForCapture(timeout?: number): Promise<void>;
+    /** Fallback basic snapshot */
+    protected _basicSnapshot(opts?: Pick<SnapshotOptions, 'interactive' | 'compact' | 'maxDepth' | 'raw'>): Promise<unknown>;
+}

package/vendor/opencli/dist/browser/base-page.js

@@ -0,0 +1,193 @@
+/**
+ * BasePage — shared IPage method implementations for DOM helpers.
+ *
+ * Both Page (daemon-backed) and CDPPage (direct CDP) execute JS the same way
+ * for DOM operations. This base class deduplicates ~200 lines of identical
+ * click/type/scroll/wait/snapshot/interceptor methods.
+ *
+ * Subclasses implement the transport-specific methods: goto, evaluate,
+ * getCookies, screenshot, tabs, etc.
+ */
+import { generateSnapshotJs, scrollToRefJs, getFormStateJs } from './dom-snapshot.js';
+import { clickJs, typeTextJs, pressKeyJs, waitForTextJs, waitForCaptureJs, waitForSelectorJs, scrollJs, autoScrollJs, networkRequestsJs, waitForDomStableJs, } from './dom-helpers.js';
+import { formatSnapshot } from '../snapshotFormatter.js';
+export class BasePage {
+    _lastUrl = null;
+    /** Cached previous snapshot hashes for incremental diff marking */
+    _prevSnapshotHashes = null;
+    // ── Shared DOM helper implementations ──
+    async click(ref) {
+        const result = await this.evaluate(clickJs(ref));
+        // Backwards compat: old format returned 'clicked' string
+        if (typeof result === 'string' || result == null)
+            return;
+        // JS click succeeded
+        if (result.status === 'clicked')
+            return;
+        // JS click failed — try CDP native click if coordinates available
+        if (result.x != null && result.y != null) {
+            const success = await this.tryNativeClick(result.x, result.y);
+            if (success)
+                return;
+        }
+        throw new Error(`Click failed: ${result.error ?? 'JS click and CDP fallback both failed'}`);
+    }
+    /** Override in subclasses with CDP native click support */
+    async tryNativeClick(_x, _y) {
+        return false;
+    }
+    async typeText(ref, text) {
+        await this.evaluate(typeTextJs(ref, text));
+    }
+    async pressKey(key) {
+        await this.evaluate(pressKeyJs(key));
+    }
+    async scrollTo(ref) {
+        return this.evaluate(scrollToRefJs(ref));
+    }
+    async getFormState() {
+        return (await this.evaluate(getFormStateJs()));
+    }
+    async scroll(direction = 'down', amount = 500) {
+        await this.evaluate(scrollJs(direction, amount));
+    }
+    async autoScroll(options) {
+        const times = options?.times ?? 3;
+        const delayMs = options?.delayMs ?? 2000;
+        await this.evaluate(autoScrollJs(times, delayMs));
+    }
+    async networkRequests(includeStatic = false) {
+        const result = await this.evaluate(networkRequestsJs(includeStatic));
+        return Array.isArray(result) ? result : [];
+    }
+    async consoleMessages(_level = 'info') {
+        return [];
+    }
+    async wait(options) {
+        if (typeof options === 'number') {
+            if (options >= 1) {
+                try {
+                    const maxMs = options * 1000;
+                    await this.evaluate(waitForDomStableJs(maxMs, Math.min(500, maxMs)));
+                    return;
+                }
+                catch {
+                    // Fallback: fixed sleep
+                }
+            }
+            await new Promise(resolve => setTimeout(resolve, options * 1000));
+            return;
+        }
+        if (typeof options.time === 'number') {
+            await new Promise(resolve => setTimeout(resolve, options.time * 1000));
+            return;
+        }
+        if (options.selector) {
+            const timeout = (options.timeout ?? 10) * 1000;
+            await this.evaluate(waitForSelectorJs(options.selector, timeout));
+            return;
+        }
+        if (options.text) {
+            const timeout = (options.timeout ?? 30) * 1000;
+            await this.evaluate(waitForTextJs(options.text, timeout));
+        }
+    }
+    async snapshot(opts = {}) {
+        const snapshotJs = generateSnapshotJs({
+            viewportExpand: opts.viewportExpand ?? 2000,
+            maxDepth: Math.max(1, Math.min(Number(opts.maxDepth) || 50, 200)),
+            interactiveOnly: opts.interactive ?? false,
+            maxTextLength: opts.maxTextLength ?? 120,
+            includeScrollInfo: true,
+            bboxDedup: true,
+            previousHashes: this._prevSnapshotHashes,
+        });
+        try {
+            const result = await this.evaluate(snapshotJs);
+            // Read back the hashes stored by the snapshot for next diff
+            try {
+                const hashes = await this.evaluate('window.__opencli_prev_hashes');
+                this._prevSnapshotHashes = typeof hashes === 'string' ? hashes : null;
+            }
+            catch {
+                // Non-fatal: diff is best-effort
+            }
+            return result;
+        }
+        catch (err) {
+            // Log snapshot failure for debugging, then fallback to basic accessibility tree
+            if (process.env.DEBUG_SNAPSHOT) {
+                console.error('[snapshot] DOM snapshot failed, falling back to accessibility tree:', err?.message?.slice(0, 200));
+            }
+            return this._basicSnapshot(opts);
+        }
+    }
+    async getCurrentUrl() {
+        if (this._lastUrl)
+            return this._lastUrl;
+        try {
+            const current = await this.evaluate('window.location.href');
+            if (typeof current === 'string' && current) {
+                this._lastUrl = current;
+                return current;
+            }
+        }
+        catch {
+            // Best-effort
+        }
+        return null;
+    }
+    async installInterceptor(pattern) {
+        const { generateInterceptorJs } = await import('../interceptor.js');
+        await this.evaluate(generateInterceptorJs(JSON.stringify(pattern), {
+            arrayName: '__opencli_xhr',
+            patchGuard: '__opencli_interceptor_patched',
+        }));
+    }
+    async getInterceptedRequests() {
+        const { generateReadInterceptedJs } = await import('../interceptor.js');
+        const result = await this.evaluate(generateReadInterceptedJs('__opencli_xhr'));
+        return Array.isArray(result) ? result : [];
+    }
+    async waitForCapture(timeout = 10) {
+        const maxMs = timeout * 1000;
+        await this.evaluate(waitForCaptureJs(maxMs));
+    }
+    /** Fallback basic snapshot */
+    async _basicSnapshot(opts = {}) {
+        const maxDepth = Math.max(1, Math.min(Number(opts.maxDepth) || 50, 200));
+        const code = `
+      (async () => {
+        function buildTree(node, depth) {
+          if (depth > ${maxDepth}) return '';
+          const role = node.getAttribute?.('role') || node.tagName?.toLowerCase() || 'generic';
+          const name = node.getAttribute?.('aria-label') || node.getAttribute?.('alt') || node.textContent?.trim().slice(0, 80) || '';
+          const isInteractive = ['a', 'button', 'input', 'select', 'textarea'].includes(node.tagName?.toLowerCase()) || node.getAttribute?.('tabindex') != null;
+
+          ${opts.interactive ? 'if (!isInteractive && !node.children?.length) return "";' : ''}
+
+          let indent = '  '.repeat(depth);
+          let line = indent + role;
+          if (name) line += ' "' + name.replace(/"/g, '\\\\\\"') + '"';
+          if (node.tagName?.toLowerCase() === 'a' && node.href) line += ' [' + node.href + ']';
+          if (node.tagName?.toLowerCase() === 'input') line += ' [' + (node.type || 'text') + ']';
+
+          let result = line + '\\n';
+          if (node.children) {
+            for (const child of node.children) {
+              result += buildTree(child, depth + 1);
+            }
+          }
+          return result;
+        }
+        return buildTree(document.body, 0);
+      })()
+    `;
+        const raw = await this.evaluate(code);
+        if (opts.raw)
+            return raw;
+        if (typeof raw === 'string')
+            return formatSnapshot(raw, opts);
+        return raw;
+    }
+}

package/vendor/opencli/dist/browser/bridge.d.ts

@@ -0,0 +1,21 @@
+/**
+ * Browser session manager — auto-spawns daemon and provides IPage.
+ */
+import type { IPage } from '../types.js';
+import type { IBrowserFactory } from '../runtime.js';
+export type BrowserBridgeState = 'idle' | 'connecting' | 'connected' | 'closing' | 'closed';
+/**
+ * Browser factory: manages daemon lifecycle and provides IPage instances.
+ */
+export declare class BrowserBridge implements IBrowserFactory {
+    private _state;
+    private _page;
+    private _daemonProc;
+    get state(): BrowserBridgeState;
+    connect(opts?: {
+        timeout?: number;
+        workspace?: string;
+    }): Promise<IPage>;
+    close(): Promise<void>;
+    private _ensureDaemon;
+}

package/vendor/opencli/dist/browser/bridge.js

@@ -0,0 +1,109 @@
+/**
+ * Browser session manager — auto-spawns daemon and provides IPage.
+ */
+import { spawn } from 'node:child_process';
+import { fileURLToPath } from 'node:url';
+import * as path from 'node:path';
+import * as fs from 'node:fs';
+import { Page } from './page.js';
+import { fetchDaemonStatus, isExtensionConnected } from './daemon-client.js';
+import { DEFAULT_DAEMON_PORT } from '../constants.js';
+const DAEMON_SPAWN_TIMEOUT = 10000; // 10s to wait for daemon + extension
+/**
+ * Browser factory: manages daemon lifecycle and provides IPage instances.
+ */
+export class BrowserBridge {
+    _state = 'idle';
+    _page = null;
+    _daemonProc = null;
+    get state() {
+        return this._state;
+    }
+    async connect(opts = {}) {
+        if (this._state === 'connected' && this._page)
+            return this._page;
+        if (this._state === 'connecting')
+            throw new Error('Already connecting');
+        if (this._state === 'closing')
+            throw new Error('Session is closing');
+        if (this._state === 'closed')
+            throw new Error('Session is closed');
+        this._state = 'connecting';
+        try {
+            await this._ensureDaemon(opts.timeout);
+            this._page = new Page(opts.workspace);
+            this._state = 'connected';
+            return this._page;
+        }
+        catch (err) {
+            this._state = 'idle';
+            throw err;
+        }
+    }
+    async close() {
+        if (this._state === 'closed')
+            return;
+        this._state = 'closing';
+        // We don't kill the daemon — it auto-exits on idle.
+        // Just clean up our reference.
+        this._page = null;
+        this._state = 'closed';
+    }
+    async _ensureDaemon(timeoutSeconds) {
+        const effectiveSeconds = (timeoutSeconds && timeoutSeconds > 0) ? timeoutSeconds : Math.ceil(DAEMON_SPAWN_TIMEOUT / 1000);
+        const timeoutMs = effectiveSeconds * 1000;
+        // Single status check instead of two separate fetchDaemonStatus() calls
+        const status = await fetchDaemonStatus();
+        // Fast path: extension already connected
+        if (status?.extensionConnected)
+            return;
+        // Daemon running but no extension — wait for extension with progress
+        if (status !== null) {
+            if (process.env.OPENCLI_VERBOSE || process.stderr.isTTY) {
+                process.stderr.write('⏳ Waiting for Chrome/Chromium extension to connect...\n');
+                process.stderr.write('   Make sure Chrome or Chromium is open and the OpenCLI extension is enabled.\n');
+            }
+            const deadline = Date.now() + timeoutMs;
+            while (Date.now() < deadline) {
+                await new Promise(resolve => setTimeout(resolve, 200));
+                if (await isExtensionConnected())
+                    return;
+            }
+            throw new Error('Daemon is running but the Browser Extension is not connected.\n' +
+                'Please install and enable the opencli Browser Bridge extension in Chrome or Chromium.');
+        }
+        // No daemon — spawn one
+        const __dirname = path.dirname(fileURLToPath(import.meta.url));
+        const parentDir = path.resolve(__dirname, '..');
+        const daemonTs = path.join(parentDir, 'daemon.ts');
+        const daemonJs = path.join(parentDir, 'daemon.js');
+        const isTs = fs.existsSync(daemonTs);
+        const daemonPath = isTs ? daemonTs : daemonJs;
+        if (process.env.OPENCLI_VERBOSE || process.stderr.isTTY) {
+            process.stderr.write('⏳ Starting daemon...\n');
+        }
+        const spawnArgs = isTs
+            ? [process.execPath, '--import', 'tsx/esm', daemonPath]
+            : [process.execPath, daemonPath];
+        this._daemonProc = spawn(spawnArgs[0], spawnArgs.slice(1), {
+            detached: true,
+            stdio: 'ignore',
+            env: { ...process.env },
+        });
+        this._daemonProc.unref();
+        // Wait for daemon + extension with faster polling
+        const deadline = Date.now() + timeoutMs;
+        while (Date.now() < deadline) {
+            await new Promise(resolve => setTimeout(resolve, 200));
+            if (await isExtensionConnected())
+                return;
+        }
+        if ((await fetchDaemonStatus()) !== null) {
+            throw new Error('Daemon is running but the Browser Extension is not connected.\n' +
+                'Please install and enable the opencli Browser Bridge extension in Chrome or Chromium.');
+        }
+        throw new Error('Failed to start opencli daemon. Try running manually:\n' +
+            `  node ${daemonPath}\n` +
+            `Make sure port ${DEFAULT_DAEMON_PORT} is available.`);
+    }
+}

package/vendor/opencli/dist/browser/cdp.d.ts

@@ -0,0 +1,40 @@
+/**
+ * CDP client — implements IPage by connecting directly to a Chrome/Electron CDP WebSocket.
+ *
+ * Fixes applied:
+ * - send() now has a 30s timeout guard (P0 #4)
+ * - goto() waits for Page.loadEventFired instead of hardcoded 1s sleep (P1 #3)
+ * - Implemented scroll, autoScroll, screenshot, networkRequests (P1 #2)
+ * - Shared DOM helper methods extracted to reduce duplication with Page (P1 #5)
+ */
+import type { IPage } from '../types.js';
+import type { IBrowserFactory } from '../runtime.js';
+export interface CDPTarget {
+    type?: string;
+    url?: string;
+    title?: string;
+    webSocketDebuggerUrl?: string;
+}
+export declare class CDPBridge implements IBrowserFactory {
+    private _ws;
+    private _idCounter;
+    private _pending;
+    private _eventListeners;
+    connect(opts?: {
+        timeout?: number;
+        workspace?: string;
+        cdpEndpoint?: string;
+    }): Promise<IPage>;
+    close(): Promise<void>;
+    send(method: string, params?: Record<string, unknown>, timeoutMs?: number): Promise<unknown>;
+    on(event: string, handler: (params: unknown) => void): void;
+    off(event: string, handler: (params: unknown) => void): void;
+    waitForEvent(event: string, timeoutMs?: number): Promise<unknown>;
+}
+declare function selectCDPTarget(targets: CDPTarget[]): CDPTarget | undefined;
+declare function scoreCDPTarget(target: CDPTarget, preferredPattern?: RegExp): number;
+export declare const __test__: {
+    selectCDPTarget: typeof selectCDPTarget;
+    scoreCDPTarget: typeof scoreCDPTarget;
+};
+export {};