@mearl/native-host 2.0.1 → 2.1.0

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

@@ -1,4 +1,4 @@
-import type { AgentChatImageInput, AgentChatProviderDescriptor, AgentInstalledSkill } from '@mearl/browser-core';
+import type { AgentChatImageInput, AgentChatModelInfo, 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): {
@@ -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;
@@ -16,13 +17,16 @@ export declare class CodexAgentProvider implements AgentProvider {
     private pendingRequests;
     private listeners;
     private knownThreadIds;
-    constructor(log: (...args: any[]) => void, clientVersion: string);
+    private sessionModels;
+    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>;
     listSkills(cwd?: string): Promise<AgentInstalledSkill[]>;
     startSession(options: AgentProviderSessionOptions): Promise<string>;
     resumeSession(providerSessionId: string, options: AgentProviderSessionOptions): Promise<AgentProviderResumeResult>;
+    getSessionModel(providerSessionId: string): AgentChatModelInfo | undefined;
     sendMessage(providerSessionId: string, message: string, images?: AgentChatImageInput[]): Promise<{
         turnId: string;
     }>;
@@ -42,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/manager.d.ts

@@ -9,6 +9,8 @@ export declare class AgentChatManager {
     private readonly completedTurns;
     private readonly recentEvents;
     private readonly recentEventBytes;
+    private readonly compactedEventCounts;
+    private readonly truncatedEventSessions;
     private readonly unsubscribe;
     constructor(providers: AgentProvider[], emit: (event: AgentChatEvent) => void);
     getStatus(): Promise<AgentChatStatus>;
@@ -36,6 +38,7 @@ export declare class AgentChatManager {
     private handleProviderEvent;
     private emitEvent;
     private recordEvent;
+    private trimReplayBuffer;
     private getProvider;
     private getSession;
     private providerThreadKey;

package/dist/agent/provider.d.ts

@@ -1,4 +1,4 @@
-import type { AgentChatEventKind, AgentChatImageInput, AgentChatProviderDescriptor, AgentInstalledSkill } from '@mearl/browser-core';
+import type { AgentChatEventKind, AgentChatImageInput, AgentChatModelInfo, AgentChatProviderDescriptor, AgentInstalledSkill } from '@mearl/browser-core';
 export interface AgentProviderEvent {
     providerSessionId?: string;
     kind: AgentChatEventKind;
@@ -41,6 +41,7 @@ export interface AgentProvider {
     listSkills?(cwd?: string): Promise<AgentInstalledSkill[]>;
     startSession(options: AgentProviderSessionOptions): Promise<string>;
     resumeSession(providerSessionId: string, options: AgentProviderSessionOptions): Promise<AgentProviderResumeResult>;
+    getSessionModel?(providerSessionId: string): AgentChatModelInfo | undefined;
     validateMessageInput?(images: AgentChatImageInput[]): Promise<void>;
     sendMessage(providerSessionId: string, message: string, images?: AgentChatImageInput[]): Promise<{
         turnId: string;

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

@@ -1,5 +1,7 @@
-import type { AgentChatImageInput, AgentChatProviderDescriptor, AgentInstalledSkill } from '@mearl/browser-core';
+import * as acp from '@agentclientprotocol/sdk';
+import type { AgentChatImageInput, AgentChatModelInfo, AgentChatProviderDescriptor, AgentInstalledSkill } from '@mearl/browser-core';
 import type { AgentProvider, AgentProviderEvent, AgentProviderListSessionsOptions, AgentProviderListSessionsResult, AgentProviderResumeResult, AgentProviderSessionOptions } from './provider.js';
+export declare function qoderModelInfo(configOptions: acp.SessionConfigOption[] | null | undefined): AgentChatModelInfo | undefined;
 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 {
@@ -16,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;
@@ -23,6 +26,7 @@ export declare class QoderAgentProvider implements AgentProvider {
     listSkills(cwd?: string): Promise<AgentInstalledSkill[]>;
     startSession(options: AgentProviderSessionOptions): Promise<string>;
     resumeSession(providerSessionId: string, options: AgentProviderSessionOptions): Promise<AgentProviderResumeResult>;
+    getSessionModel(providerSessionId: string): AgentChatModelInfo | undefined;
     validateMessageInput(images: AgentChatImageInput[]): Promise<void>;
     sendMessage(providerSessionId: string, message: string, images?: AgentChatImageInput[]): Promise<{
         turnId: string;
@@ -45,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

@@ -13,6 +13,10 @@ export interface PageSession {
     buffers: CdpBuffers;
     targetId: string;
     url: string;
+    emulation?: {
+        mobile: boolean;
+        touch: boolean;
+    };
 }
 export declare class CdpSession {
     readonly port: number;
@@ -56,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/cdp-utils.d.ts

@@ -4,8 +4,8 @@
  * Contains: HTTP helper (nodeFetch), cookie utilities, page-load waiters,
  * viewport helpers, and serialized function sources for page injection.
  */
+import { type PageClickPointerType } from '@mearl/browser-core';
 import type { PageSession } from './cdp-session.js';
-import { type CdpTarget } from './discover.js';
 export declare const TYPE_INTO_ELEMENT_SRC: string;
 export declare const CLICK_ELEMENT_VIA_JS_SRC: string;
 export declare const GET_CLICK_COORDS_FROM_NODE_SRC: string;
@@ -47,9 +47,6 @@ export declare function buildMultipartFormBody(fields: Record<string, string>):
     body: string;
 };
 export declare function waitForPageLoad(session: PageSession, timeoutMs: number): Promise<void>;
-export declare function waitForTargetLoad(session: {
-    port: number;
-}, targetId: string, timeoutMs: number): Promise<CdpTarget | null>;
 export declare function getPageViewportSize(session: PageSession): Promise<{
     width: number;
     height: number;
@@ -62,5 +59,5 @@ export declare function toCdpInputPoint(session: PageSession, x: number, y: numb
     x: number;
     y: number;
 }>;
-export declare function dispatchCdpClick(session: PageSession, x: number, y: number): Promise<void>;
+export declare function dispatchCdpClick(session: PageSession, x: number, y: number, pointerType: PageClickPointerType): Promise<void>;
 export declare function resolveBackendNodeObjectId(session: PageSession, backendNodeId: number): Promise<string>;

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/page-refs.d.ts

@@ -0,0 +1,9 @@
+import { BackendNodeRefRegistry, type BackendNodeSnapshotRefAllocator, type PageChangeSet, type PageEffectRefEntry } from '@mearl/browser-core';
+import type { PageSession } from './cdp-session.js';
+export type PageRefEntry = PageEffectRefEntry;
+export declare function getPageRefRegistry(session: PageSession): BackendNodeRefRegistry<PageRefEntry>;
+export declare function beginPageSnapshotRefs(session: PageSession): BackendNodeSnapshotRefAllocator<PageRefEntry>;
+export declare function resolvePageRef(session: PageSession, ref: string): PageRefEntry | undefined;
+export declare function deletePageRef(session: PageSession, ref: string): void;
+export declare function clearPageRefsForNavigation(session: PageSession): void;
+export declare function enrichCdpPageChangeSetWithRefs(session: PageSession, observation: PageChangeSet): Promise<PageChangeSet>;

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>;