minimal-agent 0.12.0 → 0.14.0

package/src/tools/webbrowser/browser.js

@@ -15,7 +15,7 @@ import { chmod, mkdir, readdir, realpath, rm, stat } from 'node:fs/promises';
 import os from 'node:os';
 import path from 'node:path';
 import { sanitizeCredentialEnv } from '../../config/configService.js';
-import { pathContains, pathContainedByAny } from '../../utils/pathContains.js';
+import { pathContainedByAny, pathContains } from '../../utils/pathContains.js';
 /**
  * minimal-agent 进程级固定 session 名：隔离机器上其它 agent-browser 用法，
  * 同时让本进程多次调用复用同一浏览器（与原 playwright「一 session 一 page」语义一致）。
@@ -38,7 +38,11 @@ export async function ensureBrowserProfile(profileId = 'default') {
     return profile;
 }
 export async function browserGlobalArgs(sessionName = BROWSER_SESSION, profileId = 'default') {
-    return [...sessionArgs(sessionName), '--profile', await ensureBrowserProfile(profileId)];
+    return [
+        ...sessionArgs(sessionName),
+        '--profile',
+        await ensureBrowserProfile(profileId),
+    ];
 }
 /**
  * 默认 spawn 运行器：收集 stdout/stderr 后结算；spawn 抛错也 resolve 成失败。
@@ -83,13 +87,21 @@ export const spawnRunner = (bin, args, signal) => new Promise((resolveP) => {
         });
     }
     catch (e) {
-        resolveP({ code: -1, stdout: '', stderr: e instanceof Error ? e.message : String(e) });
+        resolveP({
+            code: -1,
+            stdout: '',
+            stderr: e instanceof Error ? e.message : String(e),
+        });
         return;
     }
     child.stdout?.setEncoding('utf8');
-    child.stdout?.on('data', (c) => (stdout += c));
+    child.stdout?.on('data', (c) => {
+        stdout += c;
+    });
     child.stderr?.setEncoding('utf8');
-    child.stderr?.on('data', (c) => (stderr += c));
+    child.stderr?.on('data', (c) => {
+        stderr += c;
+    });
     child.on('error', (e) => finish(-1, e instanceof Error ? e.message : String(e)));
     // 正常路径：'close' 紧随 'exit'（pipe 关闭）→ 以完整输出立即结算，并清掉宽限计时器。
     child.on('close', (code) => finish(code));
@@ -169,10 +181,14 @@ async function pruneStaleArtifacts(dir) {
                 if (info.mtimeMs < cutoff)
                     await rm(target, { force: true, recursive: true });
             }
-            catch { /* 单个文件清不掉不影响其它 */ }
+            catch {
+                /* 单个文件清不掉不影响其它 */
+            }
         }));
     }
-    catch { /* 目录不存在或不可读：没什么可清的 */ }
+    catch {
+        /* 目录不存在或不可读：没什么可清的 */
+    }
 }
 /**
  * 生成一个托管的产物输出路径，并确保目录存在、旧产物已清理。
@@ -216,7 +232,9 @@ const ALLOWED_URL_SCHEMES = new Set(['http', 'https', 'about', 'file']);
  * 而不是替调用方创建——凭一个路径参数就造目录树同样是越权。
  */
 export async function validateArtifactOutputPath(candidate, allowedRoots) {
-    const absolute = path.isAbsolute(candidate) ? candidate : path.resolve(candidate);
+    const absolute = path.isAbsolute(candidate)
+        ? candidate
+        : path.resolve(candidate);
     const parent = path.dirname(absolute);
     let realParent;
     try {
@@ -236,9 +254,7 @@ export async function validateArtifactOutputPath(candidate, allowedRoots) {
     if (!pathContainedByAny(roots, realParent)) {
         return {
             ok: false,
-            error: `输出路径超出允许范围：${absolute}\n`
-                + `允许写入：${roots.join('、')}\n`
-                + '省略 path 参数即可写到托管的临时目录。',
+            error: `输出路径超出允许范围：${absolute}\n允许写入：${roots.join('、')}\n省略 path 参数即可写到托管的临时目录。`,
         };
     }
     const managed = await realpath(browserArtifactDir()).catch(() => browserArtifactDir());

package/src/tools/webbrowser/browser.ts

@@ -17,7 +17,7 @@ import os from 'node:os';
 import path from 'node:path';
 
 import { sanitizeCredentialEnv } from '../../config/configService.js';
-import { pathContains, pathContainedByAny } from '../../utils/pathContains.js';
+import { pathContainedByAny, pathContains } from '../../utils/pathContains.js';
 
 export interface AgentBrowserRun {
   code: number;
@@ -46,18 +46,34 @@ export function sessionArgs(sessionName = BROWSER_SESSION): string[] {
 /** KakadeAI-owned persistent browser profile. It is never the user's system Chrome profile. */
 export function browserProfilePath(profileId = 'default'): string {
   const safe = /^[a-zA-Z0-9._-]+$/.test(profileId) ? profileId : 'default';
-  return path.join(process.env.MINIMAL_AGENT_HOME ?? os.homedir(), '.minimal-agent', 'browser', 'profiles', safe);
+  return path.join(
+    process.env.MINIMAL_AGENT_HOME ?? os.homedir(),
+    '.minimal-agent',
+    'browser',
+    'profiles',
+    safe,
+  );
 }
 
-export async function ensureBrowserProfile(profileId = 'default'): Promise<string> {
+export async function ensureBrowserProfile(
+  profileId = 'default',
+): Promise<string> {
   const profile = browserProfilePath(profileId);
   await mkdir(profile, { recursive: true, mode: 0o700 });
-  if (process.platform !== 'win32') await chmod(profile, 0o700).catch(() => undefined);
+  if (process.platform !== 'win32')
+    await chmod(profile, 0o700).catch(() => undefined);
   return profile;
 }
 
-export async function browserGlobalArgs(sessionName = BROWSER_SESSION, profileId = 'default'): Promise<string[]> {
-  return [...sessionArgs(sessionName), '--profile', await ensureBrowserProfile(profileId)];
+export async function browserGlobalArgs(
+  sessionName = BROWSER_SESSION,
+  profileId = 'default',
+): Promise<string[]> {
+  return [
+    ...sessionArgs(sessionName),
+    '--profile',
+    await ensureBrowserProfile(profileId),
+  ];
 }
 
 /**
@@ -83,8 +99,12 @@ export const spawnRunner: AgentBrowserRunner = (bin, args, signal) =>
       settled = true;
       if (graceTimer) clearTimeout(graceTimer);
       // 主动释放父侧 pipe 读端（daemon 攥着写端、我们已拿到结果，不再依赖它关闭）。
-      try { child?.stdout?.destroy(); } catch {}
-      try { child?.stderr?.destroy(); } catch {}
+      try {
+        child?.stdout?.destroy();
+      } catch {}
+      try {
+        child?.stderr?.destroy();
+      } catch {}
       resolveP({ code: code ?? -1, stdout, stderr: stderr || errMsg || '' });
     };
     try {
@@ -95,14 +115,24 @@ export const spawnRunner: AgentBrowserRunner = (bin, args, signal) =>
         signal,
       });
     } catch (e) {
-      resolveP({ code: -1, stdout: '', stderr: e instanceof Error ? e.message : String(e) });
+      resolveP({
+        code: -1,
+        stdout: '',
+        stderr: e instanceof Error ? e.message : String(e),
+      });
       return;
     }
     child.stdout?.setEncoding('utf8');
-    child.stdout?.on('data', (c) => (stdout += c));
+    child.stdout?.on('data', (c) => {
+      stdout += c;
+    });
     child.stderr?.setEncoding('utf8');
-    child.stderr?.on('data', (c) => (stderr += c));
-    child.on('error', (e) => finish(-1, e instanceof Error ? e.message : String(e)));
+    child.stderr?.on('data', (c) => {
+      stderr += c;
+    });
+    child.on('error', (e) =>
+      finish(-1, e instanceof Error ? e.message : String(e)),
+    );
     // 正常路径：'close' 紧随 'exit'（pipe 关闭）→ 以完整输出立即结算，并清掉宽限计时器。
     child.on('close', (code) => finish(code));
     // 拉 daemon 的命令：daemon 继承 pipe → 'close' 永不来。以 'exit' 为准，给一小段宽限等 'close'
@@ -184,11 +214,16 @@ async function pruneStaleArtifacts(dir: string): Promise<void> {
         const target = path.join(dir, name);
         try {
           const info = await stat(target);
-          if (info.mtimeMs < cutoff) await rm(target, { force: true, recursive: true });
-        } catch { /* 单个文件清不掉不影响其它 */ }
+          if (info.mtimeMs < cutoff)
+            await rm(target, { force: true, recursive: true });
+        } catch {
+          /* 单个文件清不掉不影响其它 */
+        }
       }),
     );
-  } catch { /* 目录不存在或不可读：没什么可清的 */ }
+  } catch {
+    /* 目录不存在或不可读：没什么可清的 */
+  }
 }
 
 /**
@@ -197,10 +232,14 @@ async function pruneStaleArtifacts(dir: string): Promise<void> {
  * 文件名带 pid + 随机数：`Date.now()` 单独用会在同一毫秒内两次调用时撞名
  * （两个并发截图互相覆盖，症状是「截出来的图不是那一刻的画面」）。
  */
-export async function createArtifactPath(prefix = 'browser', ext = 'png'): Promise<string> {
+export async function createArtifactPath(
+  prefix = 'browser',
+  ext = 'png',
+): Promise<string> {
   const dir = browserArtifactDir();
   await mkdir(dir, { recursive: true, mode: 0o700 });
-  if (process.platform !== 'win32') await chmod(dir, 0o700).catch(() => undefined);
+  if (process.platform !== 'win32')
+    await chmod(dir, 0o700).catch(() => undefined);
   await pruneStaleArtifacts(dir);
   const unique = `${Date.now()}-${process.pid}-${randomUUID().slice(0, 8)}`;
   return path.join(dir, `${prefix}-${unique}.${ext}`);
@@ -237,7 +276,9 @@ export async function validateArtifactOutputPath(
   candidate: string,
   allowedRoots: string[],
 ): Promise<{ ok: true; path: string } | { ok: false; error: string }> {
-  const absolute = path.isAbsolute(candidate) ? candidate : path.resolve(candidate);
+  const absolute = path.isAbsolute(candidate)
+    ? candidate
+    : path.resolve(candidate);
   const parent = path.dirname(absolute);
   let realParent: string;
   try {
@@ -247,19 +288,22 @@ export async function validateArtifactOutputPath(
   }
   const roots = await Promise.all(
     allowedRoots.map(async (root) => {
-      try { return await realpath(root); } catch { return path.resolve(root); }
+      try {
+        return await realpath(root);
+      } catch {
+        return path.resolve(root);
+      }
     }),
   );
   if (!pathContainedByAny(roots, realParent)) {
     return {
       ok: false,
-      error:
-        `输出路径超出允许范围：${absolute}\n`
-        + `允许写入：${roots.join('、')}\n`
-        + '省略 path 参数即可写到托管的临时目录。',
+      error: `输出路径超出允许范围：${absolute}\n允许写入：${roots.join('、')}\n省略 path 参数即可写到托管的临时目录。`,
     };
   }
-  const managed = await realpath(browserArtifactDir()).catch(() => browserArtifactDir());
+  const managed = await realpath(browserArtifactDir()).catch(() =>
+    browserArtifactDir(),
+  );
   if (!pathContains(managed, realParent)) {
     const exists = await stat(path.join(realParent, path.basename(absolute)))
       .then(() => true)

package/src/tools/webbrowser/browserAutomation.js

@@ -0,0 +1,329 @@
+/**
+ * Persistent CDP transport used by BrowserBatch and BrowserCDP.
+ *
+ * The browser daemon is deliberately still owned by agent-browser; this module
+ * only replaces the short lived command clients used for each automation step.
+ */
+import { mkdir, stat } from 'node:fs/promises';
+import os from 'node:os';
+import path from 'node:path';
+import { sessionArgs } from './browser.js';
+import { ensureDaemon } from './browserDaemon.js';
+export const BROWSER_TAB_MARKER_KEY = '__minimalAgentTabMarker';
+class CdpConnection {
+    url;
+    socket = null;
+    opening = null;
+    pageTargetId;
+    pageSessionId;
+    id = 0;
+    pending = new Map();
+    events = [];
+    sequence = 0;
+    listeners = new Set();
+    constructor(url) {
+        this.url = url;
+    }
+    /**
+     * A connection is page-scoped.  It must not be put back in a process-wide
+     * pool and rebound by another conversation while this caller still holds it.
+     */
+    close() {
+        const socket = this.socket;
+        this.socket = null;
+        this.pageTargetId = undefined;
+        this.pageSessionId = undefined;
+        socket?.close();
+    }
+    get attachedPageSessionId() {
+        return this.pageSessionId;
+    }
+    get attachedPageTargetId() {
+        return this.pageTargetId;
+    }
+    async evaluateInFrame(frameId, expression, signal) {
+        const isolated = (await this.send('Page.createIsolatedWorld', {
+            frameId,
+            worldName: 'minimal-agent-browser',
+            grantUniveralAccess: false,
+        }, undefined, 30_000, signal));
+        if (typeof isolated.executionContextId !== 'number')
+            throw new Error(`无法创建 frame execution context：${frameId}`);
+        return this.send('Runtime.evaluate', {
+            expression,
+            contextId: isolated.executionContextId,
+            returnByValue: true,
+            awaitPromise: true,
+        }, undefined, 30_000, signal);
+    }
+    async frameOwnerOffset(frameId, signal) {
+        // CDP returns the owner quad in top-level viewport coordinates, including
+        // nested cross-origin frames. Do not add ancestor offsets a second time.
+        const owner = (await this.send('DOM.getFrameOwner', { frameId }, undefined, 30_000, signal));
+        if (typeof owner.backendNodeId !== 'number')
+            throw new Error(`无法取得 frame owner：${frameId}`);
+        const box = (await this.send('DOM.getBoxModel', { backendNodeId: owner.backendNodeId }, undefined, 30_000, signal));
+        const border = box.model?.border;
+        if (!Array.isArray(border) || border.length < 2)
+            throw new Error(`无法取得 frame owner 坐标：${frameId}`);
+        const numbers = border.filter((value) => typeof value === 'number');
+        if (numbers.length < 2)
+            throw new Error(`frame owner 坐标无效：${frameId}`);
+        return { x: numbers[0], y: numbers[1] };
+    }
+    async open() {
+        if (this.socket?.readyState === WebSocket.OPEN)
+            return;
+        if (this.opening)
+            return this.opening;
+        this.opening = new Promise((resolve, reject) => {
+            const socket = new WebSocket(this.url);
+            const timer = setTimeout(() => {
+                socket.close();
+                reject(new Error('CDP connection timed out'));
+            }, 10_000);
+            socket.onopen = () => {
+                clearTimeout(timer);
+                this.socket = socket;
+                resolve();
+            };
+            socket.onerror = () => {
+                clearTimeout(timer);
+                reject(new Error('Unable to connect to browser CDP'));
+            };
+            socket.onclose = () => {
+                if (this.socket === socket)
+                    this.socket = null;
+                this.pageTargetId = undefined;
+                this.pageSessionId = undefined;
+                for (const [id, request] of this.pending) {
+                    clearTimeout(request.timer);
+                    if (request.signal && request.onAbort)
+                        request.signal.removeEventListener('abort', request.onAbort);
+                    request.reject(new Error('CDP connection closed'));
+                    this.pending.delete(id);
+                }
+            };
+            socket.onmessage = (message) => this.onMessage(String(message.data));
+        }).finally(() => {
+            this.opening = null;
+        });
+        return this.opening;
+    }
+    onMessage(raw) {
+        let data;
+        try {
+            data = JSON.parse(raw);
+        }
+        catch {
+            return;
+        }
+        if (typeof data.id === 'number') {
+            const request = this.pending.get(data.id);
+            if (!request)
+                return;
+            this.pending.delete(data.id);
+            clearTimeout(request.timer);
+            if (request.signal && request.onAbort)
+                request.signal.removeEventListener('abort', request.onAbort);
+            if (data.error)
+                request.reject(new Error(JSON.stringify(data.error)));
+            else
+                request.resolve(data.result ?? {});
+            return;
+        }
+        if (typeof data.method !== 'string')
+            return;
+        const event = {
+            sequence: ++this.sequence,
+            method: data.method,
+            params: (data.params ?? {}),
+            sessionId: typeof data.sessionId === 'string' ? data.sessionId : undefined,
+            at: Date.now(),
+        };
+        if (event.method === 'Target.detachedFromTarget' &&
+            String(event.params.sessionId ?? '') === this.pageSessionId) {
+            this.pageTargetId = undefined;
+            this.pageSessionId = undefined;
+        }
+        if ((event.method === 'Target.targetDestroyed' ||
+            event.method === 'Target.targetCrashed') &&
+            String(event.params.targetId ?? '') === this.pageTargetId) {
+            this.pageTargetId = undefined;
+            this.pageSessionId = undefined;
+        }
+        this.events.push(event);
+        if (this.events.length > 500)
+            this.events.splice(0, this.events.length - 500);
+        for (const listener of this.listeners) {
+            try {
+                listener(event);
+            }
+            catch {
+                // One observer must not break delivery to the remaining CDP consumers.
+            }
+        }
+    }
+    async send(method, params = {}, target, timeoutMs = 30_000, signal) {
+        await this.open();
+        const socket = this.socket;
+        if (!socket || socket.readyState !== WebSocket.OPEN)
+            throw new Error('CDP connection is unavailable');
+        const id = ++this.id;
+        const pageDomain = /^(Accessibility|DOM|Input|Log|Network|Page|Performance|Runtime|Security)\./.test(method);
+        const effectiveTarget = target ?? (pageDomain ? this.pageSessionId : undefined);
+        return new Promise((resolve, reject) => {
+            const abortError = () => signal?.reason instanceof Error
+                ? signal.reason
+                : new Error(`CDP ${method} aborted`);
+            const cleanup = () => {
+                const request = this.pending.get(id);
+                if (!request)
+                    return false;
+                this.pending.delete(id);
+                clearTimeout(request.timer);
+                if (request.signal && request.onAbort)
+                    request.signal.removeEventListener('abort', request.onAbort);
+                return true;
+            };
+            const onAbort = () => {
+                if (cleanup())
+                    reject(abortError());
+            };
+            const timer = setTimeout(() => {
+                if (cleanup())
+                    reject(new Error(`CDP ${method} timed out`));
+            }, timeoutMs);
+            this.pending.set(id, { resolve, reject, timer, onAbort, signal });
+            if (signal?.aborted) {
+                onAbort();
+                return;
+            }
+            signal?.addEventListener('abort', onAbort, { once: true });
+            try {
+                socket.send(JSON.stringify({
+                    id,
+                    method,
+                    params,
+                    ...(effectiveTarget ? { sessionId: effectiveTarget } : {}),
+                }));
+            }
+            catch (error) {
+                if (cleanup())
+                    reject(error instanceof Error ? error : new Error(String(error)));
+            }
+        });
+    }
+    async attachToPage(preferredUrl, force = false, preferredMarker) {
+        if (this.pageSessionId && !force)
+            return;
+        if (force && this.pageSessionId) {
+            const previousSession = this.pageSessionId;
+            this.pageSessionId = undefined;
+            this.pageTargetId = undefined;
+            await this.send('Target.detachFromTarget', {
+                sessionId: previousSession,
+            }).catch(() => undefined);
+        }
+        const targets = (await this.send('Target.getTargets'));
+        const pages = (targets.targetInfos ?? []).filter((target) => target.type === 'page' && typeof target.targetId === 'string');
+        if (!pages.length)
+            throw new Error('浏览器没有可绑定的页面标签');
+        let selected = preferredMarker
+            ? undefined
+            : preferredUrl
+                ? pages.find((target) => target.url === preferredUrl)
+                : undefined;
+        if (preferredMarker) {
+            const marker = JSON.stringify(preferredMarker);
+            for (const candidate of pages) {
+                const attached = (await this.send('Target.attachToTarget', {
+                    targetId: candidate.targetId,
+                    flatten: true,
+                }));
+                const sessionId = attached.sessionId;
+                if (typeof sessionId !== 'string')
+                    continue;
+                const probe = await this.send('Runtime.evaluate', {
+                    expression: `globalThis[${JSON.stringify(BROWSER_TAB_MARKER_KEY)}] === ${marker}`,
+                    returnByValue: true,
+                }, sessionId).catch(() => undefined);
+                if (probe?.result
+                    ?.value === true) {
+                    selected = candidate;
+                    this.pageTargetId = String(candidate.targetId);
+                    this.pageSessionId = sessionId;
+                    break;
+                }
+                await this.send('Target.detachFromTarget', { sessionId }).catch(() => undefined);
+            }
+        }
+        if (preferredMarker) {
+            if (!selected)
+                throw new Error('无法通过会话标记绑定到当前浏览器标签');
+            return;
+        }
+        selected ??= pages[pages.length - 1];
+        const attached = (await this.send('Target.attachToTarget', {
+            targetId: selected.targetId,
+            flatten: true,
+        }));
+        if (typeof attached.sessionId !== 'string')
+            throw new Error('浏览器未返回页面 target session');
+        this.pageTargetId = selected.targetId;
+        this.pageSessionId = attached.sessionId;
+    }
+    read(after = 0, methods, limit = 100) {
+        return this.events
+            .filter((event) => event.sequence > after &&
+            (!methods?.length || methods.includes(event.method)))
+            .slice(-Math.max(1, Math.min(limit, 500)));
+    }
+    subscribe(listener) {
+        this.listeners.add(listener);
+        return () => this.listeners.delete(listener);
+    }
+}
+async function cdpUrl(sessionName, bin, run, signal) {
+    await ensureDaemon(sessionName, { signal });
+    const output = await run(bin, [...sessionArgs(sessionName), 'get', 'cdp-url'], signal);
+    const url = `${output.stdout}\n${output.stderr}`.match(/ws:\/\/[^\s"']+/)?.[0];
+    if (output.code !== 0 || !url)
+        throw new Error('无法取得浏览器 CDP 地址');
+    return url;
+}
+export async function getBrowserAutomation(sessionName, bin, run, signal, preferredUrl, preferredMarker) {
+    const url = await cdpUrl(sessionName, bin, run, signal);
+    // The browser endpoint is shared, but the attached page is not.  Returning
+    // a fresh connection prevents a later conversation from changing the
+    // mutable page session underneath an in-flight batch.
+    const conn = new CdpConnection(url);
+    await conn.open();
+    await conn.attachToPage(preferredUrl, true, preferredMarker);
+    return conn;
+}
+export function browserDownloadDir(conversationKey = 'local', runId = 'default') {
+    const safe = (value) => value.replace(/[^a-zA-Z0-9._-]/g, '_').slice(0, 100) || 'default';
+    const root = process.env.MINIMAL_AGENT_HOME ?? path.join(os.homedir(), '.minimal-agent');
+    return path.join(root, 'browser', 'downloads', safe(conversationKey), safe(runId));
+}
+export async function configureDownloads(cdp, conversationKey, runId) {
+    const dir = browserDownloadDir(conversationKey, runId);
+    await mkdir(dir, { recursive: true, mode: 0o700 });
+    // Browser domain is current Chrome; Page fallback keeps older Chromium usable.
+    await cdp
+        .send('Browser.setDownloadBehavior', {
+        behavior: 'allow',
+        downloadPath: dir,
+        eventsEnabled: true,
+    })
+        .catch(() => cdp.send('Page.setDownloadBehavior', {
+        behavior: 'allow',
+        downloadPath: dir,
+    }));
+    return dir;
+}
+export async function finalDownload(pathname) {
+    const info = await stat(pathname);
+    return { path: pathname, receivedBytes: info.size };
+}