@mearl/native-host 2.0.2 → 2.1.0

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

@@ -8,6 +8,7 @@ export declare function externalOpenCommand(url: string, platform?: NodeJS.Platf
 export declare class CodexAgentProvider implements AgentProvider {
     private readonly log;
     private readonly clientVersion;
+    private readonly mearlSocketPath?;
     readonly id = "codex";
     private process;
     private initialized;
@@ -17,7 +18,8 @@ export declare class CodexAgentProvider implements AgentProvider {
     private listeners;
     private knownThreadIds;
     private sessionModels;
-    constructor(log: (...args: any[]) => void, clientVersion: string);
+    private readonly executableResolver;
+    constructor(log: (...args: any[]) => void, clientVersion: string, mearlSocketPath?: string | undefined);
     getDescriptor(): Promise<AgentChatProviderDescriptor>;
     onEvent(listener: (event: AgentProviderEvent) => void): () => void;
     listSessions(options: AgentProviderListSessionsOptions): Promise<AgentProviderListSessionsResult>;
@@ -44,4 +46,5 @@ export declare class CodexAgentProvider implements AgentProvider {
     private extractThreadId;
     private probeExecutable;
     private resolveExecutable;
+    private resolveExecutableCandidates;
 }

package/dist/agent/executable-resolver.d.ts

@@ -0,0 +1,34 @@
+export type AgentExecutableResolution = {
+    executable: string;
+    error: null;
+} | {
+    executable: null;
+    error: string;
+};
+interface AgentExecutableResolverOptions {
+    candidates: () => string[];
+    probe: (executable: string) => Promise<string | null>;
+    notFoundError: string;
+    unusableError: string;
+    onFailure?: (executable: string, error: string) => void;
+}
+interface AgentExecutableProbeOptions {
+    args: string[];
+    timeoutMs: number;
+    timeoutError: string;
+    startError: (error: Error) => string;
+    exitError: (code: number | null) => string;
+}
+export declare class AgentExecutableResolver {
+    private readonly options;
+    private resolvedExecutable;
+    private resolutionPromise;
+    private generation;
+    constructor(options: AgentExecutableResolverOptions);
+    resolve(): Promise<AgentExecutableResolution>;
+    reset(): void;
+    private probeCandidates;
+}
+export declare function executableFileCandidates(candidates: Array<string | null | undefined>): string[];
+export declare function probeAgentExecutable(executable: string, options: AgentExecutableProbeOptions): Promise<string | null>;
+export {};

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

@@ -18,6 +18,7 @@ export declare class QoderAgentProvider implements AgentProvider {
     private pendingPermissions;
     private historyCaptures;
     private nextTurnId;
+    private readonly executableResolver;
     constructor(log: (...args: any[]) => void, clientVersion: string);
     getDescriptor(): Promise<AgentChatProviderDescriptor>;
     onEvent(listener: (event: AgentProviderEvent) => void): () => void;
@@ -48,5 +49,6 @@ export declare class QoderAgentProvider implements AgentProvider {
     private probeExecutable;
     private runSkillsList;
     private resolveExecutable;
+    private resolveExecutableCandidates;
     private emit;
 }

package/dist/analytics.d.ts

@@ -1 +1,3 @@
+export declare function setAnalyticsClientId(value: unknown): boolean;
+export declare function classifyAnalyticsError(error: unknown): string;
 export declare function trackAction(action: string, params?: Record<string, string | number | boolean>): void;

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

@@ -8,16 +8,17 @@
  * - `browser`: handler receives CdpSession (for tab management, tdbank, etc.)
  * - `page`:    handler receives PageSession (for most page-level actions)
  */
+import type { ControlSource } from '@mearl/browser-core';
 import type { CdpSession, PageSession } from './cdp-session.js';
 export interface BrowserAction {
     name: string;
     session: 'browser';
-    handler: (session: CdpSession, data: any) => Promise<any>;
+    handler: (session: CdpSession, data: any, controlSource: ControlSource) => Promise<any>;
 }
 export interface PageAction {
     name: string;
     session: 'page';
-    handler: (session: PageSession, data: any) => Promise<any>;
+    handler: (session: PageSession, data: any, controlSource: ControlSource) => Promise<any>;
 }
 export type CdpAction = BrowserAction | PageAction;
 /** Register one or more CDP actions. Called by each handler sub-module. */
@@ -32,4 +33,4 @@ export declare function getRegisteredActionNames(): string[];
  * 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>;
+export declare function dispatchCdpAction(cdpSession: CdpSession, action: string, data: any, controlSource?: ControlSource): Promise<any>;

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

@@ -3,7 +3,7 @@
  * 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 { MtopRequest, RumEvent, ConsoleLog, RequestBufferAccounting } from '@mearl/browser-core';
 import type { CdpClient, CdpChildSession } from './client.js';
 interface PartialRequest {
     id: number;
@@ -40,6 +40,7 @@ export interface CdpBuffers {
     events: RumEvent[];
     pending: Map<string, PartialRequest>;
     requestCounter: number;
+    requestBufferAccounting: RequestBufferAccounting;
 }
 export declare function createBuffers(): CdpBuffers;
 export declare function setupBufferListeners(client: CdpClient | CdpChildSession, buffers: CdpBuffers): void;

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

@@ -60,5 +60,8 @@ export declare class CdpSession {
     private findTargetByIdViaCdp;
     private findDefaultPageTargetViaCdp;
     private fetchVersionInfo;
+    hasActiveConnections(): boolean;
+    listOpenPageSessions(): PageSession[];
+    listRegisteredTabIds(targetIds?: ReadonlySet<string>): number[];
     close(): void;
 }

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

@@ -7,8 +7,8 @@
  * built-in observation.
  */
 import type { CdpSession } from './cdp-session.js';
-import { type PageActAction } from '@mearl/browser-core';
-export declare function cdpRunActions(session: CdpSession, data: any): Promise<any>;
+import { type ControlSource, type PageActAction } from '@mearl/browser-core';
+export declare function cdpRunActions(session: CdpSession, data: any, controlSource?: ControlSource): Promise<any>;
 /**
  * Runs a page interaction action with built-in observation: executes the raw
  * handler inside `runPageAct` and reports resulting page changes / navigation
@@ -16,4 +16,4 @@ export declare function cdpRunActions(session: CdpSession, data: any): Promise<a
  * dispatches the raw handler directly. `run_actions` steps never go through
  * this wrapper — they use dispatchCdpAction and stay lightweight.
  */
-export declare function cdpObservedPageAction(session: CdpSession, action: PageActAction, data: any): Promise<any>;
+export declare function cdpObservedPageAction(session: CdpSession, action: PageActAction, data: any, controlSource?: ControlSource): Promise<any>;

package/dist/cdp-backend/controlled-indicator.d.ts

@@ -1,17 +1,18 @@
 /**
  * CDP 模式的受控页面视觉标识。
  *
- * 与扩展模式的 favicon 替换保持一致：agent 操作过的页面把 favicon 换成 Mearl
- * 图标。CDP 模式拿不到扩展资源，图标以 data URL 内联在注入脚本里，不依赖任何
- * 网络请求。
+ * 与扩展模式共享同一套 Mearl favicon 变体，本地操作显示绿色圆点角标，云端操作
+ * 显示紫色云朵角标。图标通过 data URL 内联到新文档脚本，不依赖扩展资源或网络。
  *
- * 注入通过 Page.addScriptToEvaluateOnNewDocument + runImmediately 完成：每个
- * PageSession 只注册一次，注册的脚本在 session 存续期内跨导航自动生效；
- * session 断开重建后由下一次动作重新注册。
+ * 注入通过 Page.addScriptToEvaluateOnNewDocument + runImmediately 完成：脚本在
+ * PageSession 存续期内跨导航生效；控制来源变化时替换脚本并立即更新当前文档。
  */
+import { type ControlSource } from '@mearl/browser-core';
 import type { PageSession } from './cdp-session.js';
 /**
- * 确保受控标识已注入到该 page session。幂等且 best-effort：
- * 失败时撤销标记，下一次动作重试；任何异常都不阻断 agent 动作本身。
+ * 确保受控标识已注入到该 page session。相同来源幂等；来源变化时替换跨导航脚本，
+ * runImmediately 同步更新当前文档。任何异常都不阻断 agent 动作本身。
  */
-export declare function ensureControlledIndicator(session: PageSession): Promise<void>;
+export declare function ensureControlledIndicator(session: PageSession, controlSource?: ControlSource): Promise<void>;
+/** browser_release 使用：停止跨导航注入并恢复当前文档的 favicon。 */
+export declare function releaseControlledIndicator(session: PageSession): Promise<void>;

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

@@ -0,0 +1,4 @@
+/** CDP handler for changing one named cookie in the current page scope. */
+import type { PageSession } from './cdp-session.js';
+export declare function cdpSetCookie(session: PageSession, data: any): Promise<any>;
+export declare function cdpGetCookie(session: PageSession, data: any): Promise<any>;

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

@@ -12,6 +12,7 @@ import './tdbank-handlers.js';
 import './tab-handlers.js';
 import './interaction-handlers.js';
 import './timezone-handlers.js';
+import './cookie-handlers.js';
 import './snapshot-handlers.js';
 import './recording-handlers.js';
 import './composite-handlers.js';
@@ -27,3 +28,4 @@ export { cdpPageSnapshot, cdpPageFrames } from './snapshot-handlers.js';
 export { cdpRecordStart, cdpRecordStop } from './recording-handlers.js';
 export { cdpRunActions, cdpObservedPageAction } from './composite-handlers.js';
 export { cdpSetTimezone } from './timezone-handlers.js';
+export { cdpGetCookie, cdpSetCookie } from './cookie-handlers.js';

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

@@ -2,5 +2,7 @@
  * CDP mock interception handlers.
  */
 import type { PageSession } from './cdp-session.js';
+/** browser_release 使用：丢弃所有依赖当前 CDP 会话的 mock 状态。 */
+export declare function clearCdpMockState(): void;
 export declare function cdpSetMock(session: PageSession, data: any): Promise<any>;
 export declare function cdpGetMocks(_session: PageSession, _data: any): any;

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

@@ -7,3 +7,5 @@
 import type { PageSession } from './cdp-session.js';
 export declare function cdpRecordStart(session: PageSession, _data: any): Promise<any>;
 export declare function cdpRecordStop(session: PageSession, _data: any): Promise<any>;
+/** browser_release 使用：停止仍存活页面的录制，并丢弃已失效 target 的残留状态。 */
+export declare function releaseCdpRecordings(sessions: PageSession[]): Promise<void>;

package/dist/cdp-backend/release-control.d.ts

@@ -0,0 +1,13 @@
+/**
+ * Browser-level CDP control release.
+ *
+ * Closes Mearl's browser/page WebSocket sessions while keeping Chrome and all
+ * targets alive. A later browser action may create a fresh CdpSession.
+ */
+import type { CdpSession } from './cdp-session.js';
+export interface CdpReleaseResult {
+    released: boolean;
+    hadActiveControl: boolean;
+    affectedTabIds: number[];
+}
+export declare function releaseCdpControl(session: CdpSession): Promise<CdpReleaseResult>;

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

@@ -1,7 +1,8 @@
 /**
  * CDP tab management handlers.
  */
+import { type ControlSource } from '@mearl/browser-core';
 import type { CdpSession } from './cdp-session.js';
-export declare function cdpTabOpen(session: CdpSession, data: any): Promise<any>;
+export declare function cdpTabOpen(session: CdpSession, data: any, controlSource?: ControlSource): Promise<any>;
 export declare function cdpTabClose(session: CdpSession, data: any): Promise<any>;
 export declare function cdpTabList(session: CdpSession, _data: any): Promise<any>;