minimal-agent 0.13.0 → 0.14.0

package/src/tools/webbrowser/browserCdp.js

@@ -0,0 +1,208 @@
+import { randomUUID } from 'node:crypto';
+import { z } from 'zod';
+import { toToolParameters } from '../../utils/zodToJson.js';
+import { resolveAgentBrowserPath } from './agentBrowserPath.js';
+import { BROWSER_SESSION, sessionArgs, spawnRunner } from './browser.js';
+import { BROWSER_TAB_MARKER_KEY, getBrowserAutomation, } from './browserAutomation.js';
+import { ensureDaemon } from './browserDaemon.js';
+import { withBrowserRecovery } from './browserRecovery.js';
+import { browserRunRegistry } from './browserRunRegistry.js';
+import { browserService } from './browserService.js';
+import { ensureConversationTab } from './browserTabs.js';
+const inputSchema = z.object({
+    operation: z.enum(['send', 'read_events']),
+    method: z.string().optional(),
+    params: z.record(z.unknown()).optional(),
+    target: z
+        .string()
+        .optional()
+        .describe('Optional CDP session id for the currently claimed page target'),
+    after_sequence: z.number().int().nonnegative().optional(),
+    methods: z.array(z.string()).optional(),
+    limit: z.number().int().min(1).max(500).optional(),
+    timeout_ms: z.number().int().min(100).max(120_000).optional(),
+});
+const SAFE_BROWSER_CDP_METHODS = new Set([
+    'Browser.getVersion',
+    'Target.getTargets',
+    'Target.getTargetInfo',
+]);
+export function validateBrowserCdpMethod(method, params, pageTargetId) {
+    const domain = method.split('.', 1)[0];
+    const pageScoped = /^(Accessibility|DOM|Input|Log|Network|Page|Performance|Runtime|Security)\./.test(method);
+    if (!pageScoped && !SAFE_BROWSER_CDP_METHODS.has(method))
+        throw new Error(`BrowserCDP 不允许调用未授权的 CDP 方法：${method}`);
+    const targetId = params?.targetId;
+    if (targetId !== undefined && targetId !== pageTargetId)
+        throw new Error('BrowserCDP 只能访问当前会话认领的浏览器标签');
+    if (domain === 'Target' && targetId !== undefined && !pageTargetId)
+        throw new Error('BrowserCDP 缺少当前会话标签归属信息');
+}
+async function call(input, signal, _ctx = {}) {
+    const ctx = _ctx;
+    if (ctx.browserRun?.supervised !== true)
+        return {
+            ok: false,
+            error: 'BrowserCDP 仅可在 Desktop 的受监督浏览器会话中使用',
+        };
+    const conversationKey = ctx.browserRun.conversationKey ?? `headless:${process.pid}`;
+    const runId = ctx.browserRun.runId ?? ctx.toolCallId ?? randomUUID();
+    const run = browserRunRegistry.ensure({
+        conversationKey,
+        runId,
+        grants: ctx.browserRun.grants,
+    });
+    let cdp;
+    try {
+        try {
+            browserRunRegistry.requireGrant(run, 'interact');
+        }
+        catch (error) {
+            return {
+                ok: false,
+                error: error instanceof Error ? error.message : String(error),
+            };
+        }
+        const bin = await resolveAgentBrowserPath();
+        if (!bin)
+            return { ok: false, error: '内置浏览器不可用：未找到 agent-browser' };
+        let claimedTabId = run.activeTabId;
+        const tabMarker = `${conversationKey}:${run.runId}:${randomUUID()}`;
+        if (!claimedTabId) {
+            claimedTabId = await ensureConversationTab({
+                context: run,
+                sessionName: BROWSER_SESSION,
+                bin,
+                globals: sessionArgs(BROWSER_SESSION),
+                runner: spawnRunner,
+                signal,
+            });
+        }
+        else {
+            browserRunRegistry.assertTab(run, claimedTabId);
+        }
+        const serviceInput = {
+            sessionName: BROWSER_SESSION,
+            bin,
+            runner: spawnRunner,
+            signal,
+        };
+        let preferredUrl;
+        cdp = await browserService.exclusive(serviceInput, async (runCommand) => {
+            const switched = await runCommand([
+                ...sessionArgs(BROWSER_SESSION),
+                'tab',
+                claimedTabId,
+            ]);
+            if (switched.code !== 0)
+                throw new Error(switched.stderr || '无法切换到本会话认领的浏览器标签');
+            const marked = await runCommand([
+                ...sessionArgs(BROWSER_SESSION),
+                'eval',
+                `globalThis[${JSON.stringify(BROWSER_TAB_MARKER_KEY)}]=${JSON.stringify(tabMarker)}`,
+            ]);
+            if (marked.code !== 0)
+                throw new Error(marked.stderr || '无法标记当前浏览器会话标签');
+            const currentPage = await runCommand([
+                ...sessionArgs(BROWSER_SESSION),
+                'get',
+                'url',
+            ]);
+            preferredUrl =
+                currentPage.code === 0 ? currentPage.stdout.trim() : undefined;
+            return getBrowserAutomation(BROWSER_SESSION, bin, spawnRunner, signal, preferredUrl, tabMarker);
+        });
+        if (!cdp)
+            throw new Error('BrowserCDP 未能建立页面连接');
+        const currentCdp = () => {
+            if (!cdp)
+                throw new Error('BrowserCDP 页面连接不可用');
+            return cdp;
+        };
+        const runOperation = () => browserService.exclusive(serviceInput, async (runCommand) => {
+            const pageCdp = currentCdp();
+            const switched = await runCommand([
+                ...sessionArgs(BROWSER_SESSION),
+                'tab',
+                claimedTabId,
+            ]);
+            if (switched.code !== 0)
+                throw new Error(switched.stderr || '当前浏览器标签已失效');
+            if (input.operation === 'read_events') {
+                const events = pageCdp.read(input.after_sequence, input.methods, input.limit);
+                return {
+                    events,
+                    next_sequence: events.at(-1)?.sequence ?? input.after_sequence ?? 0,
+                };
+            }
+            if (!input.method)
+                throw new Error('send requires method');
+            validateBrowserCdpMethod(input.method, input.params, pageCdp.attachedPageTargetId);
+            if (input.target && input.target !== pageCdp.attachedPageSessionId) {
+                throw new Error('BrowserCDP 只能操作当前会话认领页面；跨页面 target 已拒绝');
+            }
+            return pageCdp.send(input.method, input.params, input.target, input.timeout_ms ?? 30_000, signal);
+        });
+        const result = await withBrowserRecovery(runOperation, {
+            signal,
+            reconnect: async () => {
+                await ensureDaemon(BROWSER_SESSION, {
+                    signal,
+                    forceRestart: true,
+                });
+            },
+            rebindTab: async () => {
+                await browserService.exclusive(serviceInput, async (runCommand) => {
+                    const switched = await runCommand([
+                        ...sessionArgs(BROWSER_SESSION),
+                        'tab',
+                        claimedTabId,
+                    ]);
+                    if (switched.code !== 0)
+                        throw new Error('浏览器重启后当前会话标签不可恢复');
+                    const marked = await runCommand([
+                        ...sessionArgs(BROWSER_SESSION),
+                        'eval',
+                        `globalThis[${JSON.stringify(BROWSER_TAB_MARKER_KEY)}]=${JSON.stringify(tabMarker)}`,
+                    ]);
+                    if (marked.code !== 0)
+                        throw new Error('浏览器重启后无法标记当前会话标签');
+                    const currentPage = await runCommand([
+                        ...sessionArgs(BROWSER_SESSION),
+                        'get',
+                        'url',
+                    ]);
+                    preferredUrl =
+                        currentPage.code === 0 ? currentPage.stdout.trim() : preferredUrl;
+                    const previousCdp = currentCdp();
+                    cdp = await getBrowserAutomation(BROWSER_SESSION, bin, spawnRunner, signal, preferredUrl, tabMarker);
+                    previousCdp.close();
+                });
+            },
+        });
+        return {
+            ok: true,
+            content: JSON.stringify({ result, tab_id: claimedTabId }),
+        };
+    }
+    catch (error) {
+        return {
+            ok: false,
+            error: error instanceof Error ? error.message : String(error),
+        };
+    }
+    finally {
+        cdp?.close();
+        browserRunRegistry.finish(conversationKey, runId);
+    }
+}
+export const browserCdpTool = {
+    name: 'BrowserCDP',
+    description: 'Advanced raw CDP access for the visible supervised browser. Use only when BrowserBatch/WebBrowser cannot express the operation.',
+    inputSchema,
+    parameters: toToolParameters(inputSchema),
+    isReadOnly: false,
+    isConcurrencySafe: false,
+    call,
+    callWithContext: call,
+};

package/src/tools/webbrowser/browserCdp.ts

@@ -0,0 +1,255 @@
+import { randomUUID } from 'node:crypto';
+import { z } from 'zod';
+import type { Tool, ToolCallContext, ToolResult } from '../../types.js';
+import { toToolParameters } from '../../utils/zodToJson.js';
+import { resolveAgentBrowserPath } from './agentBrowserPath.js';
+import { BROWSER_SESSION, sessionArgs, spawnRunner } from './browser.js';
+import {
+  BROWSER_TAB_MARKER_KEY,
+  getBrowserAutomation,
+} from './browserAutomation.js';
+import { ensureDaemon } from './browserDaemon.js';
+import { withBrowserRecovery } from './browserRecovery.js';
+import { browserRunRegistry } from './browserRunRegistry.js';
+import { browserService } from './browserService.js';
+import { ensureConversationTab } from './browserTabs.js';
+
+const inputSchema = z.object({
+  operation: z.enum(['send', 'read_events']),
+  method: z.string().optional(),
+  params: z.record(z.unknown()).optional(),
+  target: z
+    .string()
+    .optional()
+    .describe('Optional CDP session id for the currently claimed page target'),
+  after_sequence: z.number().int().nonnegative().optional(),
+  methods: z.array(z.string()).optional(),
+  limit: z.number().int().min(1).max(500).optional(),
+  timeout_ms: z.number().int().min(100).max(120_000).optional(),
+});
+type Input = z.infer<typeof inputSchema>;
+
+const SAFE_BROWSER_CDP_METHODS = new Set([
+  'Browser.getVersion',
+  'Target.getTargets',
+  'Target.getTargetInfo',
+]);
+
+export function validateBrowserCdpMethod(
+  method: string,
+  params: Record<string, unknown> | undefined,
+  pageTargetId: string | undefined,
+): void {
+  const domain = method.split('.', 1)[0];
+  const pageScoped =
+    /^(Accessibility|DOM|Input|Log|Network|Page|Performance|Runtime|Security)\./.test(
+      method,
+    );
+  if (!pageScoped && !SAFE_BROWSER_CDP_METHODS.has(method))
+    throw new Error(`BrowserCDP 不允许调用未授权的 CDP 方法：${method}`);
+  const targetId = params?.targetId;
+  if (targetId !== undefined && targetId !== pageTargetId)
+    throw new Error('BrowserCDP 只能访问当前会话认领的浏览器标签');
+  if (domain === 'Target' && targetId !== undefined && !pageTargetId)
+    throw new Error('BrowserCDP 缺少当前会话标签归属信息');
+}
+
+async function call(
+  input: Input,
+  signal?: AbortSignal,
+  _ctx: ToolCallContext = {},
+): Promise<ToolResult> {
+  const ctx = _ctx;
+  if (ctx.browserRun?.supervised !== true)
+    return {
+      ok: false,
+      error: 'BrowserCDP 仅可在 Desktop 的受监督浏览器会话中使用',
+    };
+  const conversationKey =
+    ctx.browserRun.conversationKey ?? `headless:${process.pid}`;
+  const runId = ctx.browserRun.runId ?? ctx.toolCallId ?? randomUUID();
+  const run = browserRunRegistry.ensure({
+    conversationKey,
+    runId,
+    grants: ctx.browserRun.grants,
+  });
+  let cdp: Awaited<ReturnType<typeof getBrowserAutomation>> | undefined;
+  try {
+    try {
+      browserRunRegistry.requireGrant(run, 'interact');
+    } catch (error) {
+      return {
+        ok: false,
+        error: error instanceof Error ? error.message : String(error),
+      };
+    }
+    const bin = await resolveAgentBrowserPath();
+    if (!bin)
+      return { ok: false, error: '内置浏览器不可用：未找到 agent-browser' };
+    let claimedTabId = run.activeTabId;
+    const tabMarker = `${conversationKey}:${run.runId}:${randomUUID()}`;
+    if (!claimedTabId) {
+      claimedTabId = await ensureConversationTab({
+        context: run,
+        sessionName: BROWSER_SESSION,
+        bin,
+        globals: sessionArgs(BROWSER_SESSION),
+        runner: spawnRunner,
+        signal,
+      });
+    } else {
+      browserRunRegistry.assertTab(run, claimedTabId);
+    }
+    const serviceInput = {
+      sessionName: BROWSER_SESSION,
+      bin,
+      runner: spawnRunner,
+      signal,
+    };
+    let preferredUrl: string | undefined;
+    cdp = await browserService.exclusive(serviceInput, async (runCommand) => {
+      const switched = await runCommand([
+        ...sessionArgs(BROWSER_SESSION),
+        'tab',
+        claimedTabId!,
+      ]);
+      if (switched.code !== 0)
+        throw new Error(switched.stderr || '无法切换到本会话认领的浏览器标签');
+      const marked = await runCommand([
+        ...sessionArgs(BROWSER_SESSION),
+        'eval',
+        `globalThis[${JSON.stringify(BROWSER_TAB_MARKER_KEY)}]=${JSON.stringify(tabMarker)}`,
+      ]);
+      if (marked.code !== 0)
+        throw new Error(marked.stderr || '无法标记当前浏览器会话标签');
+      const currentPage = await runCommand([
+        ...sessionArgs(BROWSER_SESSION),
+        'get',
+        'url',
+      ]);
+      preferredUrl =
+        currentPage.code === 0 ? currentPage.stdout.trim() : undefined;
+      return getBrowserAutomation(
+        BROWSER_SESSION,
+        bin,
+        spawnRunner,
+        signal,
+        preferredUrl,
+        tabMarker,
+      );
+    });
+    if (!cdp) throw new Error('BrowserCDP 未能建立页面连接');
+    const currentCdp = () => {
+      if (!cdp) throw new Error('BrowserCDP 页面连接不可用');
+      return cdp;
+    };
+    const runOperation = () =>
+      browserService.exclusive(serviceInput, async (runCommand) => {
+        const pageCdp = currentCdp();
+        const switched = await runCommand([
+          ...sessionArgs(BROWSER_SESSION),
+          'tab',
+          claimedTabId!,
+        ]);
+        if (switched.code !== 0)
+          throw new Error(switched.stderr || '当前浏览器标签已失效');
+        if (input.operation === 'read_events') {
+          const events = pageCdp.read(
+            input.after_sequence,
+            input.methods,
+            input.limit,
+          );
+          return {
+            events,
+            next_sequence: events.at(-1)?.sequence ?? input.after_sequence ?? 0,
+          };
+        }
+        if (!input.method) throw new Error('send requires method');
+        validateBrowserCdpMethod(
+          input.method,
+          input.params,
+          pageCdp.attachedPageTargetId,
+        );
+        if (input.target && input.target !== pageCdp.attachedPageSessionId) {
+          throw new Error(
+            'BrowserCDP 只能操作当前会话认领页面；跨页面 target 已拒绝',
+          );
+        }
+        return pageCdp.send(
+          input.method,
+          input.params,
+          input.target,
+          input.timeout_ms ?? 30_000,
+          signal,
+        );
+      });
+    const result = await withBrowserRecovery(runOperation, {
+      signal,
+      reconnect: async () => {
+        await ensureDaemon(BROWSER_SESSION, {
+          signal,
+          forceRestart: true,
+        });
+      },
+      rebindTab: async () => {
+        await browserService.exclusive(serviceInput, async (runCommand) => {
+          const switched = await runCommand([
+            ...sessionArgs(BROWSER_SESSION),
+            'tab',
+            claimedTabId!,
+          ]);
+          if (switched.code !== 0)
+            throw new Error('浏览器重启后当前会话标签不可恢复');
+          const marked = await runCommand([
+            ...sessionArgs(BROWSER_SESSION),
+            'eval',
+            `globalThis[${JSON.stringify(BROWSER_TAB_MARKER_KEY)}]=${JSON.stringify(tabMarker)}`,
+          ]);
+          if (marked.code !== 0)
+            throw new Error('浏览器重启后无法标记当前会话标签');
+          const currentPage = await runCommand([
+            ...sessionArgs(BROWSER_SESSION),
+            'get',
+            'url',
+          ]);
+          preferredUrl =
+            currentPage.code === 0 ? currentPage.stdout.trim() : preferredUrl;
+          const previousCdp = currentCdp();
+          cdp = await getBrowserAutomation(
+            BROWSER_SESSION,
+            bin,
+            spawnRunner,
+            signal,
+            preferredUrl,
+            tabMarker,
+          );
+          previousCdp.close();
+        });
+      },
+    });
+    return {
+      ok: true,
+      content: JSON.stringify({ result, tab_id: claimedTabId }),
+    };
+  } catch (error) {
+    return {
+      ok: false,
+      error: error instanceof Error ? error.message : String(error),
+    };
+  } finally {
+    cdp?.close();
+    browserRunRegistry.finish(conversationKey, runId);
+  }
+}
+
+export const browserCdpTool: Tool<Input> = {
+  name: 'BrowserCDP',
+  description:
+    'Advanced raw CDP access for the visible supervised browser. Use only when BrowserBatch/WebBrowser cannot express the operation.',
+  inputSchema,
+  parameters: toToolParameters(inputSchema),
+  isReadOnly: false,
+  isConcurrencySafe: false,
+  call,
+  callWithContext: call,
+};

package/src/tools/webbrowser/browserConditions.js

@@ -0,0 +1,24 @@
+export function conditionToScript(condition, targetExpression) {
+    switch (condition.type) {
+        case 'url':
+            return `(() => { const u = location.href; const p = ${JSON.stringify(condition.pattern)}; const parts = p.split('*'); if (parts.length === 1) return u === p; let at = 0; for (const [i, part] of parts.entries()) { if (!part) continue; const next = u.indexOf(part, at); if (next < 0 || (i === 0 && next !== 0) || (i === parts.length - 1 && next + part.length !== u.length)) return false; at = next + part.length; } return true; })()`;
+        case 'text':
+            return `(() => { const text = document.body?.innerText || ''; const expected = ${JSON.stringify(condition.value)}; return ${condition.exact === true ? 'text.trim()===expected' : 'text.includes(expected)'}; })()`;
+        case 'element-visible':
+            return `(() => { try { ${targetExpression(condition.locator, condition.selector)}; return true; } catch { return false; } })()`;
+        case 'element-hidden':
+            return `(() => { try { const e = ${targetExpression(condition.locator, condition.selector)}; return !e; } catch { return true; } })()`;
+        case 'load-state':
+            return condition.state === 'domcontentloaded'
+                ? `document.readyState !== 'loading'`
+                : condition.state === 'load'
+                    ? `document.readyState === 'complete'`
+                    : `document.readyState === 'complete' && performance.getEntriesByType('resource').every((entry) => (performance.now() - entry.startTime) > 250)`;
+        case 'download':
+        case 'new-tab':
+        case 'dialog':
+            throw new Error(`${condition.type} is an event condition and must be armed before the action`);
+        case 'page-change':
+            return `location.href + '|' + (document.body?.innerText || '').slice(0, 4000)`;
+    }
+}

package/src/tools/webbrowser/browserConditions.ts

@@ -0,0 +1,45 @@
+import type { BrowserLocator } from './browserLocator.js';
+
+export type BrowserCondition =
+  | { type: 'url'; pattern: string }
+  | { type: 'text'; value: string; exact?: boolean }
+  | { type: 'element-visible'; locator?: BrowserLocator; selector?: string }
+  | { type: 'element-hidden'; locator?: BrowserLocator; selector?: string }
+  | { type: 'load-state'; state: 'domcontentloaded' | 'load' | 'networkidle' }
+  | { type: 'download'; filename?: string }
+  | { type: 'new-tab'; url?: string }
+  | {
+      type: 'dialog';
+      dialogType?: 'alert' | 'confirm' | 'prompt' | 'beforeunload';
+    }
+  | { type: 'page-change' };
+
+export function conditionToScript(
+  condition: BrowserCondition,
+  targetExpression: (locator?: BrowserLocator, selector?: string) => string,
+): string {
+  switch (condition.type) {
+    case 'url':
+      return `(() => { const u = location.href; const p = ${JSON.stringify(condition.pattern)}; const parts = p.split('*'); if (parts.length === 1) return u === p; let at = 0; for (const [i, part] of parts.entries()) { if (!part) continue; const next = u.indexOf(part, at); if (next < 0 || (i === 0 && next !== 0) || (i === parts.length - 1 && next + part.length !== u.length)) return false; at = next + part.length; } return true; })()`;
+    case 'text':
+      return `(() => { const text = document.body?.innerText || ''; const expected = ${JSON.stringify(condition.value)}; return ${condition.exact === true ? 'text.trim()===expected' : 'text.includes(expected)'}; })()`;
+    case 'element-visible':
+      return `(() => { try { ${targetExpression(condition.locator, condition.selector)}; return true; } catch { return false; } })()`;
+    case 'element-hidden':
+      return `(() => { try { const e = ${targetExpression(condition.locator, condition.selector)}; return !e; } catch { return true; } })()`;
+    case 'load-state':
+      return condition.state === 'domcontentloaded'
+        ? `document.readyState !== 'loading'`
+        : condition.state === 'load'
+          ? `document.readyState === 'complete'`
+          : `document.readyState === 'complete' && performance.getEntriesByType('resource').every((entry) => (performance.now() - entry.startTime) > 250)`;
+    case 'download':
+    case 'new-tab':
+    case 'dialog':
+      throw new Error(
+        `${condition.type} is an event condition and must be armed before the action`,
+      );
+    case 'page-change':
+      return `location.href + '|' + (document.body?.innerText || '').slice(0, 4000)`;
+  }
+}