minimal-agent 0.12.0 → 0.14.0

package/src/tools/webbrowser/browserRecovery.js

@@ -0,0 +1,58 @@
+export function classifyBrowserFailure(error) {
+    const message = error instanceof Error ? error.message : String(error);
+    // Do not treat a generic "element not found" / selector miss as a stale
+    // browser target. Those are normal locator failures and must return the
+    // page evidence to the model instead of replaying the same action.
+    if (/\b(?:tab|target|frame)\b.*(?:closed|crashed|detached|destroyed|not found|invalid)/i.test(message) ||
+        /execution context.*(?:destroyed|not found|closed)/i.test(message) ||
+        /(?:page|window).*closed/i.test(message))
+        return 'stale-tab';
+    if (/cdp|socket|websocket|daemon|connection|disconnected|closed/i.test(message))
+        return 'browser-disconnected';
+    return 'unknown';
+}
+/**
+ * agent-browser reports many daemon/target failures as an exit code instead
+ * of rejecting the runner promise. Convert only those known recoverable
+ * failures into exceptions so the runtime recovery wrapper can see them;
+ * ordinary selector/business errors must remain normal tool results.
+ */
+export function recoverableAgentBrowserRunFailure(result) {
+    if (result.code === 0)
+        return undefined;
+    const message = result.stderr?.trim() || result.stdout?.trim() || `exit ${result.code}`;
+    const error = new Error(message);
+    return classifyBrowserFailure(error) === 'unknown' ? undefined : error;
+}
+/** Retry only recoverable browser failures, rebuilding the connection/tab before retrying. */
+export async function withBrowserRecovery(operation, hooks = {}) {
+    const maxAttempts = Math.max(1, Math.min(hooks.maxAttempts ?? 3, 4));
+    let attempt = 0;
+    let recoveredConnection = false;
+    let reboundTab = false;
+    while (true) {
+        if (hooks.signal?.aborted)
+            throw hooks.signal.reason ?? new Error('浏览器任务已中断');
+        try {
+            return await operation();
+        }
+        catch (error) {
+            attempt += 1;
+            const kind = classifyBrowserFailure(error);
+            if (kind === 'unknown' || attempt >= maxAttempts)
+                throw error;
+            if (kind === 'browser-disconnected' && !recoveredConnection) {
+                await hooks.reconnect?.();
+                recoveredConnection = true;
+                reboundTab = false;
+                continue;
+            }
+            if (kind === 'stale-tab' && !reboundTab) {
+                await hooks.rebindTab?.();
+                reboundTab = true;
+                continue;
+            }
+            throw error;
+        }
+    }
+}

package/src/tools/webbrowser/browserRecovery.ts

@@ -0,0 +1,83 @@
+export type BrowserRecoveryKind =
+  | 'stale-tab'
+  | 'browser-disconnected'
+  | 'unknown';
+
+export function classifyBrowserFailure(error: unknown): BrowserRecoveryKind {
+  const message = error instanceof Error ? error.message : String(error);
+  // Do not treat a generic "element not found" / selector miss as a stale
+  // browser target. Those are normal locator failures and must return the
+  // page evidence to the model instead of replaying the same action.
+  if (
+    /\b(?:tab|target|frame)\b.*(?:closed|crashed|detached|destroyed|not found|invalid)/i.test(
+      message,
+    ) ||
+    /execution context.*(?:destroyed|not found|closed)/i.test(message) ||
+    /(?:page|window).*closed/i.test(message)
+  )
+    return 'stale-tab';
+  if (
+    /cdp|socket|websocket|daemon|connection|disconnected|closed/i.test(message)
+  )
+    return 'browser-disconnected';
+  return 'unknown';
+}
+
+/**
+ * agent-browser reports many daemon/target failures as an exit code instead
+ * of rejecting the runner promise. Convert only those known recoverable
+ * failures into exceptions so the runtime recovery wrapper can see them;
+ * ordinary selector/business errors must remain normal tool results.
+ */
+export function recoverableAgentBrowserRunFailure(result: {
+  code: number;
+  stdout?: string;
+  stderr?: string;
+}): Error | undefined {
+  if (result.code === 0) return undefined;
+  const message =
+    result.stderr?.trim() || result.stdout?.trim() || `exit ${result.code}`;
+  const error = new Error(message);
+  return classifyBrowserFailure(error) === 'unknown' ? undefined : error;
+}
+
+export type BrowserRecoveryHooks<T> = {
+  reconnect?: () => Promise<void>;
+  rebindTab?: () => Promise<void>;
+  maxAttempts?: number;
+  signal?: AbortSignal;
+};
+
+/** Retry only recoverable browser failures, rebuilding the connection/tab before retrying. */
+export async function withBrowserRecovery<T>(
+  operation: () => Promise<T>,
+  hooks: BrowserRecoveryHooks<T> = {},
+): Promise<T> {
+  const maxAttempts = Math.max(1, Math.min(hooks.maxAttempts ?? 3, 4));
+  let attempt = 0;
+  let recoveredConnection = false;
+  let reboundTab = false;
+  while (true) {
+    if (hooks.signal?.aborted)
+      throw hooks.signal.reason ?? new Error('浏览器任务已中断');
+    try {
+      return await operation();
+    } catch (error) {
+      attempt += 1;
+      const kind = classifyBrowserFailure(error);
+      if (kind === 'unknown' || attempt >= maxAttempts) throw error;
+      if (kind === 'browser-disconnected' && !recoveredConnection) {
+        await hooks.reconnect?.();
+        recoveredConnection = true;
+        reboundTab = false;
+        continue;
+      }
+      if (kind === 'stale-tab' && !reboundTab) {
+        await hooks.rebindTab?.();
+        reboundTab = true;
+        continue;
+      }
+      throw error;
+    }
+  }
+}

package/src/tools/webbrowser/browserRunRegistry.js

@@ -26,8 +26,8 @@ export function isLikelyIrreversibleBrowserTarget(label) {
     const normalized = label.replace(/\s+/g, ' ').trim();
     if (!normalized)
         return false;
-    return /(?:^|[\s"'=:_-])(?:publish|submit|purchase|buy now|place order|delete|confirm delete|send)(?:$|[\s"'=:_-])/i.test(normalized)
-        || /(?:发布|发表|提交|立即购买|确认购买|确认下单|删除|确认删除|发送)(?:$|[\s：:）)】\]])/.test(normalized);
+    return (/(?:^|[\s"'=:_-])(?:publish|submit|purchase|buy now|place order|delete|confirm delete|send)(?:$|[\s"'=:_-])/i.test(normalized) ||
+        /(?:发布|发表|提交|立即购买|确认购买|确认下单|删除|确认删除|发送)(?:$|[\s：:）)】\]])/.test(normalized));
 }
 /**
  * Process-wide ownership registry for the shared browser profile.
@@ -40,6 +40,7 @@ export class BrowserRunRegistry {
     runs = new Map();
     conversationTabs = new Map();
     tabOwners = new Map();
+    tabMetadata = new Map();
     ensure(input) {
         const key = this.key(input.conversationKey, input.runId ?? 'workbench');
         const existing = this.runs.get(key);
@@ -57,7 +58,9 @@ export class BrowserRunRegistry {
             runId: input.runId ?? randomUUID(),
             profileId: input.profileId ?? 'default',
             claimedTabIds: [],
-            grants: [...new Set(input.grants ?? ['observe', 'interact'])],
+            grants: [
+                ...new Set(input.grants ?? ['observe', 'interact']),
+            ],
             allowedUploadRoots: [...new Set(input.allowedUploadRoots ?? [])],
             ...(input.taskGrantId ? { taskGrantId: input.taskGrantId } : {}),
         };
@@ -75,6 +78,19 @@ export class BrowserRunRegistry {
     ownerOf(tabId) {
         return this.tabOwners.get(tabId);
     }
+    markTab(context, tabId, metadata) {
+        this.assertTab(context, tabId);
+        const next = {
+            tabId,
+            ...metadata,
+            updatedAt: Date.now(),
+        };
+        this.tabMetadata.set(tabId, next);
+        return next;
+    }
+    tabInfo(tabId) {
+        return this.tabMetadata.get(tabId);
+    }
     claimTab(context, tabId) {
         const owner = this.tabOwners.get(tabId);
         if (owner && owner !== context.conversationKey) {
@@ -103,10 +119,26 @@ export class BrowserRunRegistry {
                 this.runs.delete(key);
         }
     }
+    /**
+     * Invalidate every tab lease after the browser process is rebuilt. Tab ids
+     * are process-local and can be reused by the replacement daemon; retaining
+     * old owners would either block the new owner or route it across sessions.
+     * Run contexts remain alive so the active task can claim a replacement tab.
+     */
+    invalidateAllTabs() {
+        this.tabOwners.clear();
+        this.conversationTabs.clear();
+        this.tabMetadata.clear();
+        for (const context of this.runs.values()) {
+            context.claimedTabIds = [];
+            context.activeTabId = undefined;
+        }
+    }
     releaseTab(conversationKey, tabId) {
         if (this.tabOwners.get(tabId) !== conversationKey)
             return;
         this.tabOwners.delete(tabId);
+        this.tabMetadata.delete(tabId);
         const claimed = this.conversationTabs.get(conversationKey);
         claimed?.delete(tabId);
         if (claimed?.size === 0)

package/src/tools/webbrowser/browserRunRegistry.ts

@@ -1,12 +1,21 @@
 import { randomUUID } from 'node:crypto';
 
 export type BrowserActionGrant = 'observe' | 'interact' | 'upload' | 'submit';
+export type TabRetention =
+  | 'ephemeral'
+  | 'conversation'
+  | 'handoff'
+  | 'deliverable';
 
-const NEGATED_ACTION_PREFIX = /(?:不要|不需(?:要)?|不能|不可|别|禁止|避免|无需|切勿)(?:再|自动|直接|帮我|替我|进行)?[\s\S]{0,8}$|(?:do\s+not|don't|never|must\s+not|should\s+not|without)(?:\s+\w+){0,4}\s*$/i;
+const NEGATED_ACTION_PREFIX =
+  /(?:不要|不需(?:要)?|不能|不可|别|禁止|避免|无需|切勿)(?:再|自动|直接|帮我|替我|进行)?[\s\S]{0,8}$|(?:do\s+not|don't|never|must\s+not|should\s+not|without)(?:\s+\w+){0,4}\s*$/i;
 
 function hasUnnegatedAction(text: string, pattern: RegExp): boolean {
   for (const match of text.matchAll(pattern)) {
-    const prefix = text.slice(Math.max(0, (match.index ?? 0) - 32), match.index);
+    const prefix = text.slice(
+      Math.max(0, (match.index ?? 0) - 32),
+      match.index,
+    );
     if (!NEGATED_ACTION_PREFIX.test(prefix)) return true;
   }
   return false;
@@ -19,11 +28,20 @@ function hasUnnegatedAction(text: string, pattern: RegExp): boolean {
  */
 export function inferBrowserTaskGrants(text: string): BrowserActionGrant[] {
   const grants: BrowserActionGrant[] = ['observe', 'interact'];
-  if (hasUnnegatedAction(text, /\b(?:upload|attach)\b(?!\s+(?:page|button|history|settings))|上传(?!页|页面|按钮|记录|历史|设置)|选择文件|添加文件/giu)) grants.push('upload');
-  if (hasUnnegatedAction(
-    text,
-    /\b(?:publish|submit|purchase|buy|delete|place\s+(?:an?\s+)?order|send)\b(?!\s+(?:page|button|history|record|settings))|发布(?!页|页面|按钮|记录|历史|设置)|发表(?!页|页面|按钮|记录|历史|设置)|提交(?!页|页面|按钮|记录|历史|设置)|购买|下单|删除|发送/giu,
-  )) grants.push('submit');
+  if (
+    hasUnnegatedAction(
+      text,
+      /\b(?:upload|attach)\b(?!\s+(?:page|button|history|settings))|上传(?!页|页面|按钮|记录|历史|设置)|选择文件|添加文件/giu,
+    )
+  )
+    grants.push('upload');
+  if (
+    hasUnnegatedAction(
+      text,
+      /\b(?:publish|submit|purchase|buy|delete|place\s+(?:an?\s+)?order|send)\b(?!\s+(?:page|button|history|record|settings))|发布(?!页|页面|按钮|记录|历史|设置)|发表(?!页|页面|按钮|记录|历史|设置)|提交(?!页|页面|按钮|记录|历史|设置)|购买|下单|删除|发送/giu,
+    )
+  )
+    grants.push('submit');
   return grants;
 }
 
@@ -31,8 +49,14 @@ export function inferBrowserTaskGrants(text: string): BrowserActionGrant[] {
 export function isLikelyIrreversibleBrowserTarget(label: string): boolean {
   const normalized = label.replace(/\s+/g, ' ').trim();
   if (!normalized) return false;
-  return /(?:^|[\s"'=:_-])(?:publish|submit|purchase|buy now|place order|delete|confirm delete|send)(?:$|[\s"'=:_-])/i.test(normalized)
-    || /(?:发布|发表|提交|立即购买|确认购买|确认下单|删除|确认删除|发送)(?:$|[\s：:）)】\]])/.test(normalized);
+  return (
+    /(?:^|[\s"'=:_-])(?:publish|submit|purchase|buy now|place order|delete|confirm delete|send)(?:$|[\s"'=:_-])/i.test(
+      normalized,
+    ) ||
+    /(?:发布|发表|提交|立即购买|确认购买|确认下单|删除|确认删除|发送)(?:$|[\s：:）)】\]])/.test(
+      normalized,
+    )
+  );
 }
 
 export interface BrowserRunContext {
@@ -47,6 +71,13 @@ export interface BrowserRunContext {
   allowedUploadRoots: string[];
 }
 
+export interface BrowserTabMetadata {
+  tabId: string;
+  retention: TabRetention;
+  title?: string;
+  updatedAt: number;
+}
+
 type BrowserRunInput = {
   conversationKey: string;
   runId?: string;
@@ -67,14 +98,17 @@ export class BrowserRunRegistry {
   private readonly runs = new Map<string, BrowserRunContext>();
   private readonly conversationTabs = new Map<string, Set<string>>();
   private readonly tabOwners = new Map<string, string>();
+  private readonly tabMetadata = new Map<string, BrowserTabMetadata>();
 
   ensure(input: BrowserRunInput): BrowserRunContext {
     const key = this.key(input.conversationKey, input.runId ?? 'workbench');
     const existing = this.runs.get(key);
     if (existing) {
       if (input.grants) existing.grants = [...new Set(input.grants)];
-      if (input.taskGrantId !== undefined) existing.taskGrantId = input.taskGrantId;
-      if (input.allowedUploadRoots) existing.allowedUploadRoots = [...new Set(input.allowedUploadRoots)];
+      if (input.taskGrantId !== undefined)
+        existing.taskGrantId = input.taskGrantId;
+      if (input.allowedUploadRoots)
+        existing.allowedUploadRoots = [...new Set(input.allowedUploadRoots)];
       return existing;
     }
     const context: BrowserRunContext = {
@@ -82,7 +116,9 @@ export class BrowserRunRegistry {
       runId: input.runId ?? randomUUID(),
       profileId: input.profileId ?? 'default',
       claimedTabIds: [],
-      grants: [...new Set<BrowserActionGrant>(input.grants ?? ['observe', 'interact'])],
+      grants: [
+        ...new Set<BrowserActionGrant>(input.grants ?? ['observe', 'interact']),
+      ],
       allowedUploadRoots: [...new Set(input.allowedUploadRoots ?? [])],
       ...(input.taskGrantId ? { taskGrantId: input.taskGrantId } : {}),
     };
@@ -92,7 +128,9 @@ export class BrowserRunRegistry {
 
   find(conversationKey: string, runId?: string): BrowserRunContext | undefined {
     if (runId) return this.runs.get(this.key(conversationKey, runId));
-    return [...this.runs.values()].find((item) => item.conversationKey === conversationKey);
+    return [...this.runs.values()].find(
+      (item) => item.conversationKey === conversationKey,
+    );
   }
 
   claimedTabs(conversationKey: string): string[] {
@@ -103,13 +141,33 @@ export class BrowserRunRegistry {
     return this.tabOwners.get(tabId);
   }
 
+  markTab(
+    context: BrowserRunContext,
+    tabId: string,
+    metadata: Pick<BrowserTabMetadata, 'retention' | 'title'>,
+  ): BrowserTabMetadata {
+    this.assertTab(context, tabId);
+    const next: BrowserTabMetadata = {
+      tabId,
+      ...metadata,
+      updatedAt: Date.now(),
+    };
+    this.tabMetadata.set(tabId, next);
+    return next;
+  }
+
+  tabInfo(tabId: string): BrowserTabMetadata | undefined {
+    return this.tabMetadata.get(tabId);
+  }
+
   claimTab(context: BrowserRunContext, tabId: string): void {
     const owner = this.tabOwners.get(tabId);
     if (owner && owner !== context.conversationKey) {
       throw new Error('该浏览器标签属于另一个会话，已阻止跨会话操作');
     }
     this.tabOwners.set(tabId, context.conversationKey);
-    const claimed = this.conversationTabs.get(context.conversationKey) ?? new Set<string>();
+    const claimed =
+      this.conversationTabs.get(context.conversationKey) ?? new Set<string>();
     claimed.add(tabId);
     this.conversationTabs.set(context.conversationKey, claimed);
     context.claimedTabIds = [...claimed];
@@ -124,16 +182,34 @@ export class BrowserRunRegistry {
    * 测试里先撞上（基准集跑完不清理，把 browserTabs 的用例挤挂了），但这是生产同款问题。
    */
   forgetConversation(conversationKey: string): void {
-    for (const tabId of this.claimedTabs(conversationKey)) this.releaseTab(conversationKey, tabId);
+    for (const tabId of this.claimedTabs(conversationKey))
+      this.releaseTab(conversationKey, tabId);
     this.conversationTabs.delete(conversationKey);
     for (const [key, run] of [...this.runs.entries()]) {
       if (run.conversationKey === conversationKey) this.runs.delete(key);
     }
   }
 
+  /**
+   * Invalidate every tab lease after the browser process is rebuilt. Tab ids
+   * are process-local and can be reused by the replacement daemon; retaining
+   * old owners would either block the new owner or route it across sessions.
+   * Run contexts remain alive so the active task can claim a replacement tab.
+   */
+  invalidateAllTabs(): void {
+    this.tabOwners.clear();
+    this.conversationTabs.clear();
+    this.tabMetadata.clear();
+    for (const context of this.runs.values()) {
+      context.claimedTabIds = [];
+      context.activeTabId = undefined;
+    }
+  }
+
   releaseTab(conversationKey: string, tabId: string): void {
     if (this.tabOwners.get(tabId) !== conversationKey) return;
     this.tabOwners.delete(tabId);
+    this.tabMetadata.delete(tabId);
     const claimed = this.conversationTabs.get(conversationKey);
     claimed?.delete(tabId);
     if (claimed?.size === 0) this.conversationTabs.delete(conversationKey);

package/src/tools/webbrowser/browserService.js

@@ -5,10 +5,36 @@
  */
 export class BrowserService {
     tails = new Map();
+    async waitForPrevious(previous, signal) {
+        if (!signal)
+            return previous.catch(() => undefined);
+        if (signal.aborted)
+            throw signal.reason instanceof Error
+                ? signal.reason
+                : new Error('Browser action cancelled');
+        await new Promise((resolve, reject) => {
+            let settled = false;
+            const cleanup = () => signal.removeEventListener('abort', onAbort);
+            const finish = (fn) => {
+                if (settled)
+                    return;
+                settled = true;
+                cleanup();
+                fn();
+            };
+            const onAbort = () => finish(() => reject(signal.reason instanceof Error
+                ? signal.reason
+                : new Error('Browser action cancelled')));
+            signal.addEventListener('abort', onAbort, { once: true });
+            void previous.then(() => finish(resolve), () => finish(resolve));
+        });
+    }
     async exclusive(input, task) {
         const previous = this.tails.get(input.sessionName) ?? Promise.resolve();
         let release;
-        const current = new Promise((resolve) => { release = resolve; });
+        const current = new Promise((resolve) => {
+            release = resolve;
+        });
         // 链上永远接一个已消化的 previous：任何一环 reject 都不能顺着队列传下去，
         // 否则后来者在 `await previous` 处抛出。
         const tail = previous.catch(() => undefined).then(() => current);
@@ -19,7 +45,7 @@ export class BrowserService {
         // 当前 current 只 resolve 不 reject，所以实际安全 —— 但那是一条没写下来的不变量，
         // 谁往链上加一个 .then 都可能打破它。把 await 挪进来，安全性就不再依赖它。
         try {
-            await previous.catch(() => undefined);
+            await this.waitForPrevious(previous, input.signal);
             const run = async (args) => {
                 if (input.signal?.aborted) {
                     return { code: -1, stdout: '', stderr: 'Browser action cancelled' };

package/src/tools/webbrowser/browserService.ts

@@ -8,15 +8,54 @@ import type { AgentBrowserRun, AgentBrowserRunner } from './browser.js';
 export class BrowserService {
   private tails = new Map<string, Promise<void>>();
 
-  async exclusive<T>(input: {
-    sessionName: string;
-    bin: string;
-    runner: AgentBrowserRunner;
-    signal?: AbortSignal;
-  }, task: (run: (args: string[]) => Promise<AgentBrowserRun>) => Promise<T>): Promise<T> {
+  private async waitForPrevious(
+    previous: Promise<void>,
+    signal?: AbortSignal,
+  ): Promise<void> {
+    if (!signal) return previous.catch(() => undefined);
+    if (signal.aborted)
+      throw signal.reason instanceof Error
+        ? signal.reason
+        : new Error('Browser action cancelled');
+    await new Promise<void>((resolve, reject) => {
+      let settled = false;
+      const cleanup = () => signal.removeEventListener('abort', onAbort);
+      const finish = (fn: () => void) => {
+        if (settled) return;
+        settled = true;
+        cleanup();
+        fn();
+      };
+      const onAbort = () =>
+        finish(() =>
+          reject(
+            signal.reason instanceof Error
+              ? signal.reason
+              : new Error('Browser action cancelled'),
+          ),
+        );
+      signal.addEventListener('abort', onAbort, { once: true });
+      void previous.then(
+        () => finish(resolve),
+        () => finish(resolve),
+      );
+    });
+  }
+
+  async exclusive<T>(
+    input: {
+      sessionName: string;
+      bin: string;
+      runner: AgentBrowserRunner;
+      signal?: AbortSignal;
+    },
+    task: (run: (args: string[]) => Promise<AgentBrowserRun>) => Promise<T>,
+  ): Promise<T> {
     const previous = this.tails.get(input.sessionName) ?? Promise.resolve();
     let release!: () => void;
-    const current = new Promise<void>((resolve) => { release = resolve; });
+    const current = new Promise<void>((resolve) => {
+      release = resolve;
+    });
     // 链上永远接一个已消化的 previous：任何一环 reject 都不能顺着队列传下去，
     // 否则后来者在 `await previous` 处抛出。
     const tail = previous.catch(() => undefined).then(() => current);
@@ -28,7 +67,7 @@ export class BrowserService {
     // 当前 current 只 resolve 不 reject，所以实际安全 —— 但那是一条没写下来的不变量，
     // 谁往链上加一个 .then 都可能打破它。把 await 挪进来，安全性就不再依赖它。
     try {
-      await previous.catch(() => undefined);
+      await this.waitForPrevious(previous, input.signal);
       const run = async (args: string[]): Promise<AgentBrowserRun> => {
         if (input.signal?.aborted) {
           return { code: -1, stdout: '', stderr: 'Browser action cancelled' };
@@ -38,7 +77,8 @@ export class BrowserService {
       return await task(run);
     } finally {
       release();
-      if (this.tails.get(input.sessionName) === tail) this.tails.delete(input.sessionName);
+      if (this.tails.get(input.sessionName) === tail)
+        this.tails.delete(input.sessionName);
     }
   }