@mearl/native-host 2.0.0

package/README.md

@@ -0,0 +1,99 @@
+# @mearl/native-host
+
+Mearl 的 Native Messaging Host —— 桥接 Chrome 扩展与本地 socket 服务。
+
+浏览器扩展通过 `chrome.runtime.connectNative()` 拉起本进程；进程对内通过 CDP（Chrome DevTools Protocol）与浏览器交互，对外通过 **Unix Socket** 暴露给 `@mearl/client` 等本地调用方，并可作为云端链路的本地落点。
+
+## 安装与注册
+
+注册 Native Messaging Host manifest（让浏览器能够拉起本进程）：
+
+```bash
+# 同时注册 Skills 与 MCP 两种集成模式（默认）
+mearl-native-host --init
+
+# 仅注册某一种模式
+mearl-native-host --init --mode skills
+mearl-native-host --init --mode mcp
+
+# 指定自定义扩展 ID（开发版）
+mearl-native-host --init --extension-id <your-extension-id>
+```
+
+> Skills 与 MCP 两个 host 运行同一份二进制、共享同一个 Unix socket，因此可同时启用。
+
+也可在代码中调用安装入口：
+
+```typescript
+import { installNativeHost } from '@mearl/native-host';
+
+await installNativeHost(); // 默认注册两种模式
+```
+
+运行时入口（被浏览器拉起、或手动启动）通过子路径导出：
+
+```typescript
+import '@mearl/native-host/runtime';
+```
+
+## CLI 选项
+
+```bash
+mearl-native-host [options]
+
+  --init [--mode <skills|mcp|both>] [--extension-id <id>]   注册 host manifest
+  --daemon                                                   独立 CDP daemon
+  --cdp-port <port>                                          指定 CDP 端口
+  --cdp-user-data-dir <dir>                                  指定 Chrome Profile
+  --browser-id <id>                                          指定浏览器注册 ID
+  --browser-name <name>                                      指定浏览器显示名称
+  --version, -v                                             查看版本
+  --help, -h                                               查看帮助
+```
+
+## 架构
+
+```
+Chrome Extension
+  ↓ (Native Messaging)
+@mearl/native-host  ← CDP →  Chrome
+  ↓ (Unix Socket)
+@mearl/client  /  @mearl/cloud-connector
+```
+
+`browser_launch` 会为每个托管 Chrome 启动一个带独立 CDP 配置的 native-host 子进程，使多个 headless/Profile/TDBank 账号实例可以同时被现有浏览器注册表寻址。设计细节见 [托管浏览器与 TDBank 多账号设计](../../docs/managed-browsers.md)。
+
+## 侧边栏 Agent Chat
+
+扩展侧边栏通过 Native Messaging 调用 native-host，再按用户选择启动持久的 Codex app-server 或 Qoder ACP 进程。两种 Provider 都支持流式消息、思考与工具进度、中断和审批，并复用各自 CLI 已保存的本地登录态。
+
+需要先安装并登录支持 `app-server` 的 Codex CLI。若事件中的模型错误提示需要更新版本，应先升级本机 Codex CLI。native-host 会依次从安装时的 Node 可执行文件目录、常见全局安装目录和 `PATH` 查找 `codex`；自定义路径可通过环境变量指定：
+
+```bash
+MEARL_CODEX_PATH=/absolute/path/to/codex
+```
+
+Qoder 使用官方 ACP 接口，需要先安装 Qoder CLI 并完成登录：
+
+```bash
+# macOS / Linux
+curl -fsSL https://qoder.com/install | bash
+qodercli
+# 进入交互界面后输入 /login
+
+# 可选：指定非标准安装位置
+MEARL_QODER_PATH=/absolute/path/to/qodercli
+```
+
+侧边栏中未选择本地目录时，Codex 对话使用只读沙箱且不允许提权，Qoder 对话通过首条提示词约束为只读模式；选择后才使用该目录作为可写工作区。`MEARL_AGENT_CWD` 仅用于 Codex 只读对话的默认浏览目录，不会开启写权限；Qoder 未选目录时从用户主目录开始浏览。Agent 接入由统一 Provider 接口承载，后续可新增 Claude 等实现而无需修改扩展与 native-host 之间的 Chat 协议。只安装 ChatGPT 等桌面聊天客户端不能替代 Provider CLI；侧边栏会在 CLI 缺失时展示安装与登录指引。
+
+## 构建
+
+```bash
+pnpm build      # esbuild 打包到 dist/（内联 browser-core / daemon-core）
+pnpm typecheck  # 仅类型检查
+```
+
+## License
+
+ISC

package/dist/agent/codex-provider.d.ts

@@ -0,0 +1,45 @@
+import type { AgentChatImageInput, AgentChatProviderDescriptor, AgentInstalledSkill } from '@mearl/browser-core';
+import type { AgentProvider, AgentProviderEvent, AgentProviderListSessionsOptions, AgentProviderListSessionsResult, AgentProviderResumeResult, AgentProviderSessionOptions } from './provider.js';
+export declare function codexThreadUrl(providerSessionId: string): string;
+export declare function externalOpenCommand(url: string, platform?: NodeJS.Platform): {
+    command: string;
+    args: string[];
+};
+export declare class CodexAgentProvider implements AgentProvider {
+    private readonly log;
+    private readonly clientVersion;
+    readonly id = "codex";
+    private process;
+    private initialized;
+    private startPromise;
+    private nextRequestId;
+    private pendingRequests;
+    private listeners;
+    private knownThreadIds;
+    constructor(log: (...args: any[]) => void, clientVersion: string);
+    getDescriptor(): Promise<AgentChatProviderDescriptor>;
+    onEvent(listener: (event: AgentProviderEvent) => void): () => void;
+    listSessions(options: AgentProviderListSessionsOptions): Promise<AgentProviderListSessionsResult>;
+    listSkills(cwd?: string): Promise<AgentInstalledSkill[]>;
+    startSession(options: AgentProviderSessionOptions): Promise<string>;
+    resumeSession(providerSessionId: string, options: AgentProviderSessionOptions): Promise<AgentProviderResumeResult>;
+    sendMessage(providerSessionId: string, message: string, images?: AgentChatImageInput[]): Promise<{
+        turnId: string;
+    }>;
+    interrupt(providerSessionId: string, turnId: string): Promise<void>;
+    closeSession(providerSessionId: string): Promise<void>;
+    openSession(providerSessionId: string): Promise<void>;
+    respondToRequest(requestId: string | number, result: unknown): void;
+    dispose(): void;
+    private ensureStarted;
+    private start;
+    private handleLine;
+    private request;
+    private write;
+    private handleExit;
+    private rejectPending;
+    private emit;
+    private extractThreadId;
+    private probeExecutable;
+    private resolveExecutable;
+}

package/dist/agent/event-transport.d.ts

@@ -0,0 +1,3 @@
+import type { AgentChatEvent } from '@mearl/browser-core';
+export declare const MAX_AGENT_EVENT_BYTES: number;
+export declare function sanitizeAgentChatEvent(event: AgentChatEvent): AgentChatEvent;

package/dist/agent/instructions.d.ts

@@ -0,0 +1 @@
+export declare function createBrowserDeveloperInstructions(tabId: number): string;

package/dist/agent/manager.d.ts

@@ -0,0 +1,44 @@
+import type { AgentChatEvent, AgentChatCloseOptions, AgentChatEventsOptions, AgentChatEventsResult, AgentChatInterruptOptions, AgentChatListSessionsOptions, AgentChatListSessionsResult, AgentChatOpenOptions, AgentChatRefreshResult, AgentChatRespondOptions, AgentChatSendOptions, AgentChatSession, AgentChatStartOptions, AgentChatStatus, AgentInstalledSkill, AgentSkillReadResult } from '@mearl/browser-core';
+import type { AgentProvider } from './provider.js';
+export declare class AgentChatManager {
+    private readonly emit;
+    private readonly providers;
+    private readonly sessions;
+    private readonly sessionByProviderThread;
+    private readonly pendingRequests;
+    private readonly completedTurns;
+    private readonly recentEvents;
+    private readonly recentEventBytes;
+    private readonly unsubscribe;
+    constructor(providers: AgentProvider[], emit: (event: AgentChatEvent) => void);
+    getStatus(): Promise<AgentChatStatus>;
+    listSkills(options: {
+        providerId?: unknown;
+        cwd?: unknown;
+    }): Promise<AgentInstalledSkill[]>;
+    readSkill(options: {
+        providerId?: unknown;
+        path?: unknown;
+        cwd?: unknown;
+    }): Promise<AgentSkillReadResult>;
+    listSessions(options: AgentChatListSessionsOptions): Promise<AgentChatListSessionsResult>;
+    startSession(options: AgentChatStartOptions): Promise<AgentChatSession>;
+    sendMessage(options: AgentChatSendOptions): Promise<{
+        turnId: string;
+    }>;
+    interrupt(options: AgentChatInterruptOptions): Promise<void>;
+    openSession(options: AgentChatOpenOptions): Promise<void>;
+    closeSession(options: AgentChatCloseOptions): Promise<void>;
+    getEvents(options: AgentChatEventsOptions): AgentChatEventsResult;
+    refreshSession(options: AgentChatEventsOptions): Promise<AgentChatRefreshResult>;
+    respondToRequest(options: AgentChatRespondOptions): void;
+    dispose(): void;
+    private handleProviderEvent;
+    private emitEvent;
+    private recordEvent;
+    private getProvider;
+    private getSession;
+    private providerThreadKey;
+    private providerRequestKey;
+    private sessionTurnKey;
+}

package/dist/agent/process-env.d.ts

@@ -0,0 +1,6 @@
+export interface AgentSpawnCommand {
+    command: string;
+    args: string[];
+}
+export declare function agentSpawnCommand(executable: string, args: string[], platform?: NodeJS.Platform, commandInterpreter?: string | undefined): AgentSpawnCommand;
+export declare function createAgentChildEnv(sourceEnv?: NodeJS.ProcessEnv, nodeExecutable?: string): NodeJS.ProcessEnv;

package/dist/agent/provider.d.ts

@@ -0,0 +1,53 @@
+import type { AgentChatEventKind, AgentChatImageInput, AgentChatProviderDescriptor, AgentInstalledSkill } from '@mearl/browser-core';
+export interface AgentProviderEvent {
+    providerSessionId?: string;
+    kind: AgentChatEventKind;
+    method: string;
+    params: unknown;
+    timestamp?: number;
+    requestId?: string | number;
+}
+export interface AgentProviderSessionOptions {
+    cwd?: string;
+    developerInstructions?: string;
+    ephemeral?: boolean;
+}
+export interface AgentProviderSessionSummary {
+    providerSessionId: string;
+    title?: string;
+    cwd?: string;
+    updatedAt?: number;
+    ephemeral?: boolean;
+}
+export interface AgentProviderListSessionsOptions {
+    cwd?: string;
+    cursor?: string;
+    limit: number;
+}
+export interface AgentProviderListSessionsResult {
+    sessions: AgentProviderSessionSummary[];
+    nextCursor?: string;
+}
+export interface AgentProviderResumeResult {
+    providerSessionId: string;
+    history?: AgentProviderEvent[];
+    historyComplete?: boolean;
+}
+export interface AgentProvider {
+    readonly id: string;
+    getDescriptor(): Promise<AgentChatProviderDescriptor>;
+    onEvent(listener: (event: AgentProviderEvent) => void): () => void;
+    listSessions?(options: AgentProviderListSessionsOptions): Promise<AgentProviderListSessionsResult>;
+    listSkills?(cwd?: string): Promise<AgentInstalledSkill[]>;
+    startSession(options: AgentProviderSessionOptions): Promise<string>;
+    resumeSession(providerSessionId: string, options: AgentProviderSessionOptions): Promise<AgentProviderResumeResult>;
+    validateMessageInput?(images: AgentChatImageInput[]): Promise<void>;
+    sendMessage(providerSessionId: string, message: string, images?: AgentChatImageInput[]): Promise<{
+        turnId: string;
+    }>;
+    interrupt(providerSessionId: string, turnId: string): Promise<void>;
+    closeSession(providerSessionId: string): Promise<void>;
+    openSession?(providerSessionId: string): Promise<void>;
+    respondToRequest(requestId: string | number, result: unknown): void;
+    dispose(): void;
+}

package/dist/agent/qoder-provider.d.ts

@@ -0,0 +1,49 @@
+import type { AgentChatImageInput, AgentChatProviderDescriptor, AgentInstalledSkill } from '@mearl/browser-core';
+import type { AgentProvider, AgentProviderEvent, AgentProviderListSessionsOptions, AgentProviderListSessionsResult, AgentProviderResumeResult, AgentProviderSessionOptions } from './provider.js';
+export declare function parseQoderSkillsList(output: string, cwd: string, home?: string): AgentInstalledSkill[];
+export declare function qoderInstallCommand(platform?: NodeJS.Platform): string;
+export declare class QoderAgentProvider implements AgentProvider {
+    private readonly log;
+    private readonly clientVersion;
+    readonly id = "qoder";
+    private process;
+    private connection;
+    private context;
+    private initializeResponse;
+    private startPromise;
+    private listeners;
+    private sessions;
+    private pendingPermissions;
+    private historyCaptures;
+    private nextTurnId;
+    constructor(log: (...args: any[]) => void, clientVersion: string);
+    getDescriptor(): Promise<AgentChatProviderDescriptor>;
+    onEvent(listener: (event: AgentProviderEvent) => void): () => void;
+    listSessions(options: AgentProviderListSessionsOptions): Promise<AgentProviderListSessionsResult>;
+    listSkills(cwd?: string): Promise<AgentInstalledSkill[]>;
+    startSession(options: AgentProviderSessionOptions): Promise<string>;
+    resumeSession(providerSessionId: string, options: AgentProviderSessionOptions): Promise<AgentProviderResumeResult>;
+    validateMessageInput(images: AgentChatImageInput[]): Promise<void>;
+    sendMessage(providerSessionId: string, message: string, images?: AgentChatImageInput[]): Promise<{
+        turnId: string;
+    }>;
+    interrupt(providerSessionId: string, _turnId: string): Promise<void>;
+    closeSession(providerSessionId: string): Promise<void>;
+    respondToRequest(requestId: string | number, result: unknown): void;
+    dispose(): void;
+    private ensureStarted;
+    private start;
+    private runPrompt;
+    private handleSessionUpdate;
+    private emitToolUpdate;
+    private handlePermissionRequest;
+    private cancelPermissions;
+    private handleExit;
+    private getContext;
+    private assertImageInputSupported;
+    private withTimeout;
+    private probeExecutable;
+    private runSkillsList;
+    private resolveExecutable;
+    private emit;
+}

package/dist/agent/skill-manager.d.ts

@@ -0,0 +1,28 @@
+import type { AgentSkillCheckUpdatesResult, AgentSkillCliStatus, AgentSkillInstallOptions, AgentSkillMutationOptions, AgentSkillMutationResult, AgentSkillScope, AgentSkillUpdate } from '@mearl/browser-core';
+interface SkillCliOutput {
+    stdout: string;
+    stderr: string;
+}
+export type SkillCliRunner = (executable: string, args: string[], cwd?: string) => Promise<SkillCliOutput>;
+export interface AgentSkillManagerOptions {
+    resolveExecutable?: () => string | null;
+    run?: SkillCliRunner;
+}
+export declare function resolveAliSkillsExecutable(): string | null;
+export declare const runSkillCli: SkillCliRunner;
+export declare function parseSkillUpdates(stdout: string, scope: AgentSkillScope): AgentSkillUpdate[];
+export declare class AgentSkillManager {
+    private readonly executableResolver;
+    private readonly run;
+    constructor(options?: AgentSkillManagerOptions);
+    getStatus(): Promise<AgentSkillCliStatus>;
+    install(data: AgentSkillInstallOptions): Promise<AgentSkillMutationResult>;
+    checkUpdates(data: {
+        providerId?: unknown;
+        cwd?: unknown;
+    }): Promise<AgentSkillCheckUpdatesResult>;
+    update(data: AgentSkillMutationOptions): Promise<AgentSkillMutationResult>;
+    uninstall(data: AgentSkillMutationOptions): Promise<AgentSkillMutationResult>;
+    private mutationContext;
+}
+export {};

package/dist/agent/workspace-directory.d.ts

@@ -0,0 +1,4 @@
+export type DirectoryPickerRunner = (command: string, args: string[]) => Promise<string | null>;
+export declare const runDirectoryPickerCommand: DirectoryPickerRunner;
+export declare function pickWorkspaceDirectory(platform?: NodeJS.Platform, run?: DirectoryPickerRunner): Promise<string | null>;
+export declare function resolveWorkspaceDirectory(directory: unknown): string;

package/dist/analytics.d.ts

@@ -0,0 +1 @@
+export declare function trackAction(action: string, params?: Record<string, string | number | boolean>): void;

package/dist/browser-inventory.d.ts

@@ -0,0 +1,33 @@
+import { type BrowserRecord } from './browser-registry.js';
+import { type ManagedBrowserSummary } from './managed-browser.js';
+export type BrowserStatus = 'connected' | 'running_disconnected' | 'stopped';
+interface BrowserInventoryBase {
+    browserId: string;
+    name: string;
+    status: BrowserStatus;
+    extensionVersion?: string;
+    nativeHostVersion?: string;
+    transport?: 'extension' | 'cdp';
+}
+export interface RegularBrowserInventoryItem extends BrowserInventoryBase {
+    type: 'regular';
+    status: 'connected';
+}
+export interface ManagedBrowserInventoryItem extends BrowserInventoryBase {
+    type: 'managed';
+    headless: boolean;
+    persistent: boolean;
+    cdpPort: number;
+    createdAt: string;
+    account?: ManagedBrowserSummary['account'];
+    copiedCookies?: ManagedBrowserSummary['copiedCookies'];
+}
+export type BrowserInventoryItem = RegularBrowserInventoryItem | ManagedBrowserInventoryItem;
+export interface BrowserInventoryResult {
+    count: number;
+    connectedCount: number;
+    browsers: BrowserInventoryItem[];
+}
+export declare function mergeBrowserInventory(connected: BrowserRecord[], managed: ManagedBrowserSummary[]): BrowserInventoryResult;
+export declare function listBrowserInventory(): BrowserInventoryResult;
+export {};

package/dist/browser-registry.d.ts

@@ -0,0 +1,78 @@
+/**
+ * Browser registry — advertises this native-host's connection in a shared,
+ * on-disk registry so clients can discover and address multiple browsers at
+ * once (multiple Chrome profiles / Chromium-based browsers, each with the
+ * extension, each launching its own native-host).
+ *
+ * Why a registry instead of the old single well-known socket
+ * ----------------------------------------------------------
+ * Historically every native-host fought over one fixed socket; the last one to
+ * start kicked the others off, so at most one browser was reachable and the two
+ * flapped on every reconnect. Here each native-host listens on its own unique
+ * per-process socket and publishes a record; the client reads the registry and
+ * connects to the socket of whichever browser it wants (default: most-recently
+ * focused). No contention, N browsers reachable simultaneously.
+ *
+ * Ownership
+ * ---------
+ * The record is keyed by the browser's stable installation id, so a browser
+ * that reconnects (extension reload → new native-host pid → new socket) simply
+ * overwrites its own record. To avoid a briefly-overlapping predecessor wiping
+ * the successor's record during a reload, every mutation first checks that the
+ * on-disk record still belongs to this process (or is stale) before writing.
+ */
+import { type DaemonRecord } from '@mearl/daemon-core';
+export interface BrowserRecord extends DaemonRecord {
+    /** native-host pid — used for liveness pruning. */
+    pid: number;
+    /** Stable per-installation id reported by the extension (or 'cdp' for daemon mode). */
+    browserId: string;
+    /** Absolute path of the per-process socket this native-host listens on. */
+    socketPath: string;
+    /** Human-readable browser name, e.g. "Chrome", "Edge". */
+    browserName: string;
+    extensionVersion?: string;
+    nativeHostVersion: string;
+    transport: 'extension' | 'cdp';
+    /** Epoch ms when this browser window last gained focus; drives default target selection. */
+    lastFocusedAt?: number;
+    startedAt: string;
+    /** Epoch ms of the last record write; latest-wins tiebreak. */
+    updatedAt: number;
+}
+export declare function initBrowserRegistry(deps: {
+    log: (...args: any[]) => void;
+}): void;
+/**
+ * Publish (or refresh) this native-host's registry record. Called once the
+ * browser identity is known — from the extension handshake, or immediately with
+ * a synthetic identity in CDP daemon mode.
+ */
+export declare function registerBrowser(info: {
+    browserId: string;
+    socketPath: string;
+    browserName: string;
+    nativeHostVersion: string;
+    transport: 'extension' | 'cdp';
+    extensionVersion?: string;
+    /** Initial focus rank. Managed headless browsers use 0 so they do not steal the default target. */
+    lastFocusedAt?: number;
+}): void;
+/**
+ * Mark this browser as most-recently focused, so it becomes the default target.
+ * Focus can change in rapid bursts (fast window switching), so writes are
+ * throttled: the first change in an interval writes immediately, further changes
+ * schedule a single trailing write rather than one write each.
+ */
+export declare function touchFocus(): void;
+/** Remove our record on shutdown — but only if it is still ours. */
+export declare function unregisterBrowser(): void;
+/**
+ * Reap registry records left behind by native-hosts that exited without
+ * cleanup (crashes). Live records are kept; a dead record is kept until it is
+ * older than STALE_RECORD_TTL_MS so a quickly-reconnecting browser can still
+ * inherit its own last-focus time. Meant to run once at startup.
+ */
+export declare function pruneDeadBrowsers(): void;
+/** Live browser connections, ordered by the same focus rank used for default routing. */
+export declare function listRegisteredBrowsers(): BrowserRecord[];

package/dist/cdp-backend/action-registry.d.ts

@@ -0,0 +1,35 @@
+/**
+ * CDP action registry.
+ *
+ * Each handler sub-module registers its actions here. The registry replaces
+ * the giant switch/case in handleViaCdp with a data-driven lookup.
+ *
+ * Two session levels:
+ * - `browser`: handler receives CdpSession (for tab management, tdbank, etc.)
+ * - `page`:    handler receives PageSession (for most page-level actions)
+ */
+import type { CdpSession, PageSession } from './cdp-session.js';
+export interface BrowserAction {
+    name: string;
+    session: 'browser';
+    handler: (session: CdpSession, data: any) => Promise<any>;
+}
+export interface PageAction {
+    name: string;
+    session: 'page';
+    handler: (session: PageSession, data: any) => Promise<any>;
+}
+export type CdpAction = BrowserAction | PageAction;
+/** Register one or more CDP actions. Called by each handler sub-module. */
+export declare function registerActions(actions: CdpAction[]): void;
+/** Look up a registered action by name. Returns undefined if not found. */
+export declare function getAction(name: string): CdpAction | undefined;
+/** Get all registered action names (useful for diagnostics). */
+export declare function getRegisteredActionNames(): string[];
+/**
+ * Dispatch an action by name.
+ *
+ * Resolves the appropriate session level and calls the handler.
+ * Throws if the action is unknown or CDP is not available.
+ */
+export declare function dispatchCdpAction(cdpSession: CdpSession, action: string, data: any): Promise<any>;

package/dist/cdp-backend/browser-handlers.d.ts

@@ -0,0 +1,7 @@
+/**
+ * CDP browser-level handlers: screenshot, selected element, user info.
+ */
+import type { PageSession } from './cdp-session.js';
+export declare function cdpPageScreenshot(session: PageSession, data: any): Promise<any>;
+export declare function cdpPageSelectedElement(session: PageSession, _data: any): Promise<any>;
+export declare function cdpGetUserInfo(session: PageSession, data: any): Promise<any>;

package/dist/cdp-backend/buffers.d.ts

@@ -0,0 +1,46 @@
+/**
+ * In-memory circular buffers for CDP network requests, console logs, and
+ * RUM/tracking events. A single CdpSession subscribes to CDP events and
+ * fills these buffers; callers read from them without CDP interaction.
+ */
+import type { MtopRequest, RumEvent, ConsoleLog } from '@mearl/browser-core';
+import type { CdpClient, CdpChildSession } from './client.js';
+interface PartialRequest {
+    id: number;
+    requestId: string;
+    timestamp: string;
+    timestampMs: number;
+    method: string;
+    url: string;
+    apiName: string;
+    headers: Array<{
+        name: string;
+        value: string;
+    }>;
+    postData: any;
+    queryString: Array<{
+        name: string;
+        value: string;
+    }>;
+    status: number;
+    statusText: string;
+    responseHeaders: Array<{
+        name: string;
+        value: string;
+    }>;
+    responseBody: any;
+    isProxy: boolean;
+    proxyRequestUrl: string | null;
+    proxyData: any;
+    startTs: number;
+}
+export interface CdpBuffers {
+    requests: MtopRequest[];
+    logs: ConsoleLog[];
+    events: RumEvent[];
+    pending: Map<string, PartialRequest>;
+    requestCounter: number;
+}
+export declare function createBuffers(): CdpBuffers;
+export declare function setupBufferListeners(client: CdpClient | CdpChildSession, buffers: CdpBuffers): void;
+export {};

package/dist/cdp-backend/cdp-session.d.ts

@@ -0,0 +1,60 @@
+/**
+ * CDP session manager — maintains browser-level and page-level CDP connections.
+ *
+ * - Browser client: connected to the browser's top-level WebSocket endpoint.
+ *   Used for Target.* commands (list/open/close tabs).
+ * - Page sessions: per-target connections used for page interaction, screenshots,
+ *   and buffered network/log/event collection.
+ */
+import { CdpClient, CdpChildSession } from './client.js';
+import { type CdpBuffers } from './buffers.js';
+export interface PageSession {
+    client: CdpClient | CdpChildSession;
+    buffers: CdpBuffers;
+    targetId: string;
+    url: string;
+}
+export declare class CdpSession {
+    readonly port: number;
+    readonly userDataDir?: string;
+    private browserClient;
+    private pageSessions;
+    /** Virtual tabId counter → CDP targetId */
+    private tabIdMap;
+    private nextTabId;
+    constructor(options?: number | {
+        port?: number;
+        userDataDir?: string;
+    });
+    getBrowserClient(): Promise<CdpClient>;
+    /**
+     * Get (or create) a page session.
+     *
+     * @param virtualTabId  Numeric tabId returned by `tab_open` (optional).
+     *                      If omitted, connects to the first available page target.
+     */
+    getPageSession(virtualTabId?: number): Promise<PageSession>;
+    /** Register a newly opened target as a virtual tabId and return the numeric ID. */
+    registerTarget(targetId: string): Promise<number>;
+    /** Return the existing virtual tabId for a target, registering it when first discovered. */
+    ensureTargetRegistered(targetId: string): Promise<number>;
+    private createPageSession;
+    private findTargetById;
+    private findDefaultPageTarget;
+    /** Effective port: from DevToolsActivePort file if present, else this.port */
+    private effectivePort;
+    /**
+     * Resolve the browser-level WebSocket URL.
+     * Priority: DevToolsActivePort file → HTTP /json/version
+     */
+    private resolveBrowserWsUrl;
+    /**
+     * Build a page-level WebSocket URL from a target ID.
+     * Used when HTTP /json is unavailable.
+     */
+    private pageWsUrl;
+    private findTargetByIdViaCdp;
+    private findDefaultPageTargetViaCdp;
+    private fetchVersionInfo;
+    close(): void;
+}