agents 0.26.0 → 0.28.0

package/dist/{browser-DE3d-RLk.d.ts → browser-D30VlpcA.d.ts}

@@ -1,12 +1,12 @@
-import { s as LifecycleCapability } from "./capability-runner-DBAnGr6L.js";
+import { s as LifecycleCapability } from "./capability-runner-BiVUtjqC.js";
 import {
-  $ as CdpConnection,
-  F as LiveViewMode,
-  I as BrowserBinding,
-  M as BrowserLiveView,
-  O as BrowserSessionStore,
-  z as BrowserSessionGuardrails
-} from "./connector-Cl-VqPmA.js";
+  O as CdpConnection,
+  a as ListableBrowserSessionStore,
+  d as BrowserBinding,
+  m as BrowserSessionGuardrails,
+  s as BrowserLiveView,
+  u as LiveViewMode
+} from "./session-store-DoPY12xM.js";
 
 //#region src/browser/spec.d.ts
 /**
@@ -87,6 +87,16 @@ interface CdpSpecSource {
 declare function loadCdpSpec(source: CdpSpecSource): Promise<SearchableCdpSpec>;
 //#endregion
 //#region src/browser/browser.d.ts
+/**
+ * The scope used when a caller doesn't pick one: every caller that leaves
+ * `scope` out shares this one active tab. See {@link BrowserConnectOptions}.
+ */
+declare const DEFAULT_BROWSER_SCOPE = "shared";
+/**
+ * Scope records kept per browser. Writing a new one past the cap deletes the
+ * least recently used; a scope that comes back afterwards starts fresh.
+ */
+declare const MAX_BROWSER_SCOPES = 100;
 /**
  * Browser Run settings applied every time a browser is created — including
  * when a lost browser is replaced — so options like guardrails survive a
@@ -136,9 +146,9 @@ interface BrowserOptions {
    * Where the browser's record lives. Defaults to a
    * {@link DurableBrowserSessionStore} over the host object's storage, which
    * requires installing the `Browser` with `Lifecycle.use()`. Passing a store
-   * lets the `Browser` work without Lifecycle.
+   * lets the `Browser` work without Lifecycle. It must implement `list`.
    */
-  store?: BrowserSessionStore;
+  store?: ListableBrowserSessionStore;
   /** Default CDP command timeout for {@link Browser.connect}. */
   timeoutMs?: number;
   /**
@@ -163,32 +173,45 @@ interface ResolvedBrowser {
   restarted: boolean;
   createdAt: number;
   updatedAt: number;
+}
+interface BrowserConnectOptions {
   /**
-   * The tab the agent last worked in, when one was recorded for this
-   * browser. Absent on a browser this resolution created; a replacement a
-   * concurrent caller already created and used may carry one.
+   * Who is driving. Connections with the same scope share an active tab, and
+   * each scope keeps its own, so two conversations on one browser don't
+   * drive each other's page. Cookies, logins, and the tabs themselves are
+   * shared by every scope: a scope splits "which tab is mine", not the
+   * browser. Defaults to {@link DEFAULT_BROWSER_SCOPE}.
    */
-  activeTargetId?: string;
+  scope?: string;
 }
 interface BrowserConnection {
   name: string;
   sessionId: string;
+  /** The scope this connection works in; see {@link BrowserConnectOptions}. */
+  scope: string;
   /**
-   * `true` when the browser this caller resolved is gone, even if a
-   * concurrent caller already replaced it. See
-   * {@link ResolvedBrowser.restarted}.
+   * `true` when this scope worked in an earlier browser that has since been
+   * replaced, whichever scope's connection replaced it. Its tabs and page
+   * state are gone; surface this loudly to the model. `false` on a scope's
+   * first connection, even one that replaced a lost browser: the scope had
+   * nothing to lose. This is per scope, not a browser-wide signal.
    */
   restarted: boolean;
-  /** See {@link ResolvedBrowser.activeTargetId}. */
+  /**
+   * The tab this scope last worked in, when it recorded one in this
+   * browser.
+   */
   activeTargetId?: string;
   /** Closing this connection does NOT close the browser. */
   cdp: CdpConnection;
   /**
-   * Record the tab the agent is working in (or clear it with `undefined`).
+   * Record the tab this scope is working in (or clear it with `undefined`).
    * Never resurrects: returns `false` when the browser was closed or
    * replaced since this connection resolved it.
    */
   setActiveTarget(targetId: string | undefined): Promise<boolean>;
+  /** The tabs other scopes are working in, in this browser. */
+  targetsInOtherScopes(): Promise<Set<string>>;
   /**
    * The Chrome DevTools Protocol description this browser serves, read from
    * the browser itself (cached per binding).
@@ -224,17 +247,17 @@ declare class Browser extends LifecycleCapability {
    */
   resolve(): Promise<ResolvedBrowser>;
   /**
-   * Resolve the browser and open a CDP connection to it. Commands sent over
-   * the connection refresh the record's `updatedAt` (throttled to
+   * Resolve the browser and open a CDP connection to it for one scope (see
+   * {@link BrowserConnectOptions.scope}). Commands sent over the connection
+   * refresh the record's `updatedAt` (throttled to
    * {@link SESSION_TOUCH_INTERVAL_MS}), so hosts can tell an actively used
    * browser from one the platform has likely reclaimed.
    *
    * If the browser expires between the liveness probe and the WebSocket
    * upgrade, the record is retired and the browser resolved once more, so
-   * the caller gets a fresh browser with `restarted: true` instead of an
-   * error.
+   * the caller gets a fresh browser instead of an error.
    */
-  connect(): Promise<BrowserConnection>;
+  connect(options?: BrowserConnectOptions): Promise<BrowserConnection>;
   /**
    * Close the browser: retire the record (so the next resolve reports
    * `restarted: true`) and delete its Browser Run session. Returns `false`
@@ -258,18 +281,21 @@ declare class Browser extends LifecycleCapability {
 }
 //#endregion
 export {
-  BrowserRunOptions as a,
-  browserRun as c,
-  CdpSpecSource as d,
-  SearchableCdpSpec as f,
-  BrowserProvider as i,
-  CdpField as l,
-  BrowserConnection as n,
-  BrowserRunProvider as o,
-  loadCdpSpec as p,
-  BrowserOptions as r,
-  ResolvedBrowser as s,
+  BrowserProvider as a,
+  DEFAULT_BROWSER_SCOPE as c,
+  browserRun as d,
+  CdpField as f,
+  loadCdpSpec as g,
+  SearchableCdpSpec as h,
+  BrowserOptions as i,
+  MAX_BROWSER_SCOPES as l,
+  CdpSpecSource as m,
+  BrowserConnectOptions as n,
+  BrowserRunOptions as o,
+  CdpItems as p,
+  BrowserConnection as r,
+  BrowserRunProvider as s,
   Browser as t,
-  CdpItems as u
+  ResolvedBrowser as u
 };
-//# sourceMappingURL=browser-DE3d-RLk.d.ts.map
+//# sourceMappingURL=browser-D30VlpcA.d.ts.map

package/dist/{browser-tool-CQ10e6Kj.js → browser-tool-4iomavs_.js}

@@ -1,8 +1,9 @@
 import { i as _classPrivateFieldInitSpec, n as _classPrivateFieldSet2, r as _assertClassBrand, t as _classPrivateFieldGet2 } from "./classPrivateFieldGet2-DZBYAB34.js";
 import { t as _classPrivateMethodInitSpec } from "./classPrivateMethodInitSpec-qMjJ6sHQ.js";
-import { E as CdpProtocolError, k as validateConnectorArgs } from "./connector-58XDGvc3.js";
-import { o as resolveCtx, s as transformBrowserResult } from "./ai-fm7xx1BK.js";
-import { CodemodeConnector, DynamicWorkerExecutor, createCodemodeRuntime } from "@cloudflare/codemode";
+import { s as validateConnectorArgs, v as CdpProtocolError } from "./session-store-Do4xkDcf.js";
+import { i as transformBrowserResult, r as resolveCtx } from "./tool-helpers-O5BDVEAY.js";
+import "./browser-CEdNlsaD.js";
+import { CodemodeConnector, DynamicWorkerExecutor, MAX_DURABLE_VALUE_BYTES, createCodemodeRuntime } from "@cloudflare/codemode";
 /**
 * `cdp.attachToTarget` returns `{ sessionId: "target:<targetId>" }` — a
 * stable handle rather than a connection-scoped CDP session id, so replayed
@@ -11,6 +12,18 @@ import { CodemodeConnector, DynamicWorkerExecutor, createCodemodeRuntime } from
 const ATTACH_HANDLE_PREFIX = "target:";
 /** Chrome's JSON-RPC code for a CDP session id it doesn't know. */
 const CDP_SESSION_NOT_FOUND = -32001;
+/**
+* Codemode records every `send` result for replay and fails the run when one
+* is over {@link MAX_DURABLE_VALUE_BYTES}, telling the model to write to a
+* file, which this sandbox can't. A full-page screenshot is the usual
+* culprit, so say how to take a smaller one instead.
+*/
+function assertScreenshotFits(result) {
+	const size = JSON.stringify(result ?? null).length;
+	if (size <= MAX_DURABLE_VALUE_BYTES) return;
+	const megabytes = (size / 1e6).toFixed(1);
+	throw new Error(`The screenshot result is ${megabytes} MB, over the 1 MB limit on a cdp.send result. Capture just the viewport (no captureBeyondViewport or clip larger than the window), or pass format: "jpeg" with quality: 60.`);
+}
 /** {@link BrowserSessionConnector} `#liveParams`: nothing to detach. */
 const DETACHED = Symbol("detached");
 /** Reports awaiting their tool call; bounded in case a caller never reads. */
@@ -24,20 +37,25 @@ const BROWSER_LIFETIME_COMMANDS = /* @__PURE__ */ new Set([
 	"Browser.crash",
 	"Browser.crashGpuProcess"
 ]);
-const INSTRUCTIONS = [
-	"This browser persists between executions: tabs, cookies, and logins you leave behind are still there next time. It is managed for you — there is nothing to start, close, or reset.",
-	"The browser can still be replaced between runs (idle timeout, crash) — even between the passes of a run that paused for approval. The tool result then says restarted: true, and earlier tabs, cookies, and logins are gone. Don't assume a page from an earlier run is still there: check where you are before an action that matters (submitting a form, making a purchase).",
-	"Page-scoped commands (Page.*, Runtime.*, DOM.*, Input.*, Network.*, Emulation.*) need sessionId: \"active\" — the tab you are working in, which stays the same across executions. Example: await cdp.send({ method: \"Page.navigate\", params: { url }, sessionId: \"active\" }).",
-	"Browser- and Target-scoped commands (Target.getTargets, Target.createTarget, Browser.getVersion) take no sessionId.",
-	"Opening a tab with Target.createTarget makes it the active tab. To switch to another open tab, call cdp.attachToTarget({ targetId }): it becomes active, and the returned sessionId works like \"active\" for that tab, in this run and later ones. A raw Target.attachToTarget sent through cdp.send returns Chrome's own sessionId, which only lasts for the current run.",
-	"Tabs a page opens on its own (popups, target=_blank links) do not become active; the tool result lists them as newTabs.",
-	"cdp.send returns the CDP method result directly, not the JSON-RPC envelope: Target.createTarget returns { targetId }, Runtime.evaluate returns { result: { value } }, Page.captureScreenshot returns { data }.",
-	"Issue CDP calls sequentially — never in parallel (no Promise.all): call order is recorded for durable replay.",
-	"Page.navigate resolves before the page finishes loading. Poll Runtime.evaluate of document.readyState until it is 'complete' before reading the page.",
-	"Use cdp.spec() to discover commands, events, and types when unsure. If a command fails or times out, check cdp.getDebugLog() for recent protocol traffic.",
-	"Return small results. Write large page dumps to a file or workspace and pass references around."
+/**
+* How to use the `cdp` connector, one rule per line. `codemode.describe("cdp")`
+* returns these, and `browserTool` puts them in its description. Each rule
+* fixes a mistake models make with CDP, or states something about this
+* browser they can't know; leave out what a model knows already.
+*/
+const BROWSER_INSTRUCTIONS = [
+	"The browser persists between runs: tabs, cookies, and logins are still there next time. You never start or close it.",
+	"If the browser was replaced (idle timeout, crash), the result says restarted: true and earlier tabs and logins are gone. Before an action that matters (submitting a form, a purchase), check you're on the page you expect.",
+	"Page-scoped commands (Page.*, Runtime.*, DOM.*, Input.*, Network.*, Emulation.*) need sessionId: \"active\", your tab, which is remembered between runs. Browser.* and Target.* commands take no sessionId.",
+	"Other open tabs (Target.getTargets) may belong to other conversations using this browser: don't close, navigate, or attach to a tab you didn't open unless the user asks.",
+	"Target.createTarget opens a tab and makes it active. To switch to another open tab, call cdp.attachToTarget({ targetId }); the sessionId it returns keeps working in later runs, while one from a raw Target.attachToTarget only works in the current run.",
+	"Tabs a page opens itself (popups, target=_blank links) don't become active; the result lists them as newTabs.",
+	"Runtime.evaluate: pass returnByValue: true, or objects come back as a remote reference with no value, and awaitPromise: true for async expressions. The value is at result.value. A thrown error doesn't reject: check exceptionDetails.",
+	"Page.navigate returns before the page loads and doesn't throw when it fails: check errorText, then poll document.readyState with Runtime.evaluate until it is 'complete'.",
+	"Pick out what you need inside Runtime.evaluate and return only that. Results over about 24,000 characters are cut short, and a single cdp.send result over 1 MB (a full-page screenshot, say) fails the run."
 ].join("\n");
 var _browser = /* @__PURE__ */ new WeakMap();
+var _scope = /* @__PURE__ */ new WeakMap();
 var _states = /* @__PURE__ */ new WeakMap();
 var _connecting = /* @__PURE__ */ new WeakMap();
 var _reports = /* @__PURE__ */ new WeakMap();
@@ -49,8 +67,10 @@ var _BrowserSessionConnector_brand = /* @__PURE__ */ new WeakSet();
 * The model never manages sessions: every execution reattaches to the
 * browser (or gets a replacement, reported as `restarted`), and
 * `sessionId: "active"` addresses the tab it last worked in. The active tab
-* is stored on the browser's record, so it survives between executions for as
-* long as the tab does.
+* is stored per scope (see {@link BrowserSessionConnectorOptions.scope}), so
+* it survives between executions for as long as the tab does, and one
+* scope's executions never land in another scope's tab unless the model
+* attaches to it.
 *
 * The CDP socket is per pass: opened on the first call, closed when the pass
 * ends. The browser itself outlives the execution.
@@ -60,16 +80,18 @@ var BrowserSessionConnector = class extends CodemodeConnector {
 		super(ctx, {});
 		_classPrivateMethodInitSpec(this, _BrowserSessionConnector_brand);
 		_classPrivateFieldInitSpec(this, _browser, void 0);
+		_classPrivateFieldInitSpec(this, _scope, void 0);
 		_classPrivateFieldInitSpec(this, _states, /* @__PURE__ */ new Map());
 		_classPrivateFieldInitSpec(this, _connecting, /* @__PURE__ */ new Map());
 		_classPrivateFieldInitSpec(this, _reports, /* @__PURE__ */ new Map());
 		_classPrivateFieldSet2(_browser, this, options.browser);
+		_classPrivateFieldSet2(_scope, this, options.scope);
 	}
 	name() {
 		return "cdp";
 	}
 	instructions() {
-		return INSTRUCTIONS;
+		return BROWSER_INSTRUCTIONS;
 	}
 	tool(name, tool) {
 		return validateConnectorArgs(this.name(), name, tool);
@@ -117,6 +139,7 @@ var BrowserSessionConnector = class extends CodemodeConnector {
 						throw await _assertClassBrand(_BrowserSessionConnector_brand, this, _teach).call(this, state, error, method, sessionId);
 					}
 					_assertClassBrand(_BrowserSessionConnector_brand, this, _observe).call(this, state, method, liveParams, result);
+					if (method === "Page.captureScreenshot") assertScreenshotFits(result);
 					return result;
 				}
 			},
@@ -190,8 +213,9 @@ var BrowserSessionConnector = class extends CodemodeConnector {
 		};
 	}
 	/**
-	* The pass is over: note tabs the page opened, save the active tab on the
-	* browser's record, and drop the socket. The browser stays alive.
+	* The pass is over: note tabs the page opened, save the scope's active
+	* tab, note whether another scope shares it, and drop the socket. The
+	* browser stays alive.
 	*/
 	async onPassEnd(executionId) {
 		const state = _classPrivateFieldGet2(_states, this).get(executionId);
@@ -199,7 +223,8 @@ var BrowserSessionConnector = class extends CodemodeConnector {
 		_classPrivateFieldGet2(_states, this).delete(executionId);
 		try {
 			const open = await _assertClassBrand(_BrowserSessionConnector_brand, this, _recordNewTabs).call(this, executionId, state);
-			await _assertClassBrand(_BrowserSessionConnector_brand, this, _saveActiveTarget).call(this, state, open);
+			const active = await _assertClassBrand(_BrowserSessionConnector_brand, this, _saveActiveTarget).call(this, state, open);
+			if (active && state.activeResolved) await _assertClassBrand(_BrowserSessionConnector_brand, this, _recordSharedTab).call(this, state, active);
 		} finally {
 			state.connected.cdp.disconnect();
 		}
@@ -242,7 +267,7 @@ function _state(executionId) {
 	return promise;
 }
 async function _connect(executionId) {
-	const connected = await _classPrivateFieldGet2(_browser, this).connect();
+	const connected = await _classPrivateFieldGet2(_browser, this).connect(_classPrivateFieldGet2(_scope, this) === void 0 ? void 0 : { scope: _classPrivateFieldGet2(_scope, this) });
 	let initialPages;
 	try {
 		initialPages = await _assertClassBrand(_BrowserSessionConnector_brand, this, _pages).call(this, connected.cdp);
@@ -251,10 +276,13 @@ async function _connect(executionId) {
 		throw error;
 	}
 	const state = {
+		executionId,
 		connected,
 		attached: /* @__PURE__ */ new Map(),
+		workedIn: /* @__PURE__ */ new Set(),
 		initialPages: new Set(initialPages.map((page) => page.targetId)),
-		activeResolved: false
+		activeResolved: false,
+		closed: /* @__PURE__ */ new Set()
 	};
 	_classPrivateFieldGet2(_states, this).set(executionId, state);
 	_assertClassBrand(_BrowserSessionConnector_brand, this, _report).call(this, executionId, connected.restarted);
@@ -265,7 +293,9 @@ function _report(executionId, restarted) {
 	if (!report) {
 		report = {
 			restarted,
-			newTabs: []
+			newTabs: [],
+			tabClosed: false,
+			tabShared: false
 		};
 		_classPrivateFieldGet2(_reports, this).set(executionId, report);
 		if (_classPrivateFieldGet2(_reports, this).size > MAX_PENDING_REPORTS) {
@@ -292,7 +322,18 @@ async function _recordNewTabs(executionId, state) {
 	}
 	const report = _assertClassBrand(_BrowserSessionConnector_brand, this, _report).call(this, executionId, state.connected.restarted);
 	const opened = new Set(report.newTabs.map((tab) => tab.targetId));
-	for (const page of pages) if (!state.initialPages.has(page.targetId) && page.openerId) opened.add(page.targetId);
+	let grew = true;
+	while (grew) {
+		grew = false;
+		for (const page of pages) {
+			const opener = page.openerId;
+			if (!opener || opened.has(page.targetId) || state.initialPages.has(page.targetId)) continue;
+			if (state.workedIn.has(opener) || opened.has(opener)) {
+				opened.add(page.targetId);
+				grew = true;
+			}
+		}
+	}
 	report.newTabs = pages.filter((page) => opened.has(page.targetId)).map(({ targetId, url, title }) => ({
 		targetId,
 		url,
@@ -301,20 +342,31 @@ async function _recordNewTabs(executionId, state) {
 	return new Set(pages.map((page) => page.targetId));
 }
 /**
-* Save the tab this pass settled on, forgetting one that has since closed.
-* Without the list of open tabs, save the choice unchecked: the next
-* execution checks the stored tab is still open before using it.
+* Save the tab this pass settled on, forgetting one that has since closed,
+* and return it. Without the list of open tabs, save the choice
+* unchecked: the next execution checks the stored tab is still open
+* before using it.
 */
 async function _saveActiveTarget(state, open) {
 	const stored = state.connected.activeTargetId;
+	if (!state.activeResolved && stored && open && !open.has(stored) && !state.closed.has(stored)) _assertClassBrand(_BrowserSessionConnector_brand, this, _report).call(this, state.executionId, state.connected.restarted).tabClosed = true;
 	const candidate = state.activeResolved ? state.activeTargetId : stored;
 	const active = candidate && (!open || open.has(candidate)) ? candidate : void 0;
-	if (active === stored) return;
+	if (active === stored) return active;
 	try {
 		await state.connected.setActiveTarget(active);
 	} catch (error) {
 		_assertClassBrand(_BrowserSessionConnector_brand, this, _warn).call(this, "save the active tab", error);
 	}
+	return active;
+}
+/** Report when another scope is working in this pass's tab too. */
+async function _recordSharedTab(state, active) {
+	try {
+		if ((await state.connected.targetsInOtherScopes()).has(active)) _assertClassBrand(_BrowserSessionConnector_brand, this, _report).call(this, state.executionId, state.connected.restarted).tabShared = true;
+	} catch (error) {
+		_assertClassBrand(_BrowserSessionConnector_brand, this, _warn).call(this, "check whether the active tab is shared", error);
+	}
 }
 function _warn(action, error) {
 	console.warn(`[agents/browser] Failed to ${action} for browser "${_classPrivateFieldGet2(_browser, this).name}"`, error);
@@ -328,17 +380,18 @@ async function _resolveSessionId(state, sessionId) {
 	return sessionId;
 }
 /**
-* Decide which tab `"active"` means, once per pass: the stored tab if it
-* is still open, else the only open tab, else a new blank tab when none
-* are open, else the first listed tab.
+* Decide which tab `"active"` means, once per pass: the scope's stored tab
+* if it is still open, else a new blank tab. Never a tab the scope didn't
+* open, even a blank one: it may be another scope's, or a popup.
 */
 async function _activeTarget(state) {
 	if (state.activeTargetId) return state.activeTargetId;
-	const pages = await _assertClassBrand(_BrowserSessionConnector_brand, this, _pages).call(this, state.connected.cdp);
-	const stored = state.connected.activeTargetId;
+	const { connected } = state;
+	const pages = await _assertClassBrand(_BrowserSessionConnector_brand, this, _pages).call(this, connected.cdp);
+	const stored = connected.activeTargetId;
 	let targetId = pages.find((page) => page.targetId === stored)?.targetId;
-	if (!targetId && pages.length === 0) targetId = (await state.connected.cdp.send("Target.createTarget", { url: "about:blank" })).targetId;
-	targetId ??= pages[0].targetId;
+	if (!targetId && stored && !state.closed.has(stored)) _assertClassBrand(_BrowserSessionConnector_brand, this, _report).call(this, state.executionId, connected.restarted).tabClosed = true;
+	if (!targetId) targetId = (await connected.cdp.send("Target.createTarget", { url: "about:blank" })).targetId;
 	_assertClassBrand(_BrowserSessionConnector_brand, this, _setActive).call(this, state, targetId);
 	return targetId;
 }
@@ -351,6 +404,7 @@ async function _attach(state, targetId, timeoutMs) {
 	if (existing) return existing;
 	const live = await state.connected.cdp.attachToTarget(targetId, { timeoutMs });
 	state.attached.set(targetId, live);
+	state.workedIn.add(targetId);
 	return live;
 }
 /** Track tab changes the model makes through raw Target commands. */
@@ -359,9 +413,12 @@ function _observe(state, method, params, result) {
 	if (method === "Target.createTarget") {
 		const created = result?.targetId;
 		if (typeof created === "string") _assertClassBrand(_BrowserSessionConnector_brand, this, _setActive).call(this, state, created);
-	} else if (method === "Target.attachToTarget" && targetId) _assertClassBrand(_BrowserSessionConnector_brand, this, _setActive).call(this, state, targetId);
-	else if (method === "Target.closeTarget" && targetId) {
+	} else if (method === "Target.attachToTarget" && targetId) {
+		_assertClassBrand(_BrowserSessionConnector_brand, this, _setActive).call(this, state, targetId);
+		state.workedIn.add(targetId);
+	} else if (method === "Target.closeTarget" && targetId) {
 		state.attached.delete(targetId);
+		state.closed.add(targetId);
 		if (state.activeTargetId === targetId) state.activeTargetId = void 0;
 	} else if (method === "Target.detachFromTarget") {
 		for (const [target, live] of state.attached) if (target === targetId || live === params?.sessionId) state.attached.delete(target);
@@ -415,11 +472,17 @@ function targetOfHandle(handle) {
 //#endregion
 //#region src/browser/browser-tool.ts
 /**
-* The harness-neutral core of `browserTool`, shared by the AI SDK
-* (`agents/browser/ai-sdk`) and TanStack AI (`agents/browser/tanstack-ai`)
-* adapters. Internal — not an entry point.
+* The harness-neutral core of `browserTool`, shared by the adapters in
+* `tools/` (`agents/browser/ai-sdk`, `agents/browser/tanstack-ai`,
+* `agents/browser/pi`).
+* Internal — not an entry point.
 */
+const DEFAULT_TIMEOUT_MS = 6e4;
 const RESTARTED_NOTICE = "The browser was restarted before this run (it expired or was closed): earlier tabs, logins, and page state are gone. Your code ran in a fresh browser — navigate again before relying on page state.";
+const TAB_CLOSED_NOTICE = "The tab you were working in was closed (by another conversation using this browser, or a person). `sessionId: \"active\"` now opens a blank tab — navigate again before relying on page state.";
+const TAB_SHARED_NOTICE = "Another conversation using this browser is also working in your tab, so its page may change between your runs. Open a tab of your own with Target.createTarget if you need one.";
+/** Scopes whose runtime and connector stay built; older ones are rebuilt. */
+const MAX_CACHED_SCOPES = 32;
 /**
 * A codemode runtime name per browser. Browser names are host-chosen and
 * unrestricted; runtime names allow only `[a-zA-Z0-9_.-]`, so anything else
@@ -428,15 +491,35 @@ const RESTARTED_NOTICE = "The browser was restarted before this run (it expired
 function browserRuntimeName(name) {
 	return `browser-tool_${name.replace(/[^a-zA-Z0-9_-]/g, (char) => `.${char.codePointAt(0)?.toString(16)}.`)}`;
 }
+/**
+* The latest run queued per browser and scope, so runs in one scope go one
+* at a time, even from tools built separately (one per turn, say). Per
+* isolate, which is per Durable Object.
+*/
+const runQueues = /* @__PURE__ */ new WeakMap();
+function queued(browser, scope, run) {
+	let queues = runQueues.get(browser);
+	if (!queues) runQueues.set(browser, queues = /* @__PURE__ */ new Map());
+	const next = (queues.get(scope) ?? Promise.resolve()).then(run, run);
+	const settled = next.catch(() => void 0);
+	queues.set(scope, settled);
+	settled.then(() => {
+		if (queues.get(scope) === settled) queues.delete(scope);
+	});
+	return next;
+}
 /** Add what happened to the browser to the codemode result. */
 function withBrowserReport(output, report) {
 	if (!report) return output;
+	const notices = [
+		report.restarted && RESTARTED_NOTICE,
+		report.tabClosed && !report.restarted && TAB_CLOSED_NOTICE,
+		report.tabShared && TAB_SHARED_NOTICE
+	].filter((notice) => typeof notice === "string");
 	return {
 		...output,
-		...report.restarted ? {
-			restarted: true,
-			notice: RESTARTED_NOTICE
-		} : {},
+		...report.restarted ? { restarted: true } : {},
+		...notices.length > 0 ? { notice: notices.join(" ") } : {},
 		...report.newTabs.length > 0 ? { newTabs: report.newTabs } : {}
 	};
 }
@@ -450,31 +533,84 @@ function browserReportNotes(output) {
 /**
 * Build the codemode runtime and connector for one `browserTool`, and wrap
 * `execute` so each result carries the browser report.
+*
+* Each scope gets its own connector (which knows its scope) on the same
+* codemode runtime, built on first use. Runs in one scope wait for each
+* other, since they drive one tab; runs in different scopes go in parallel.
 */
 function createBrowserToolCore(options, adapter) {
 	const ctx = resolveCtx(options);
 	if (!ctx) throw new Error("browserTool requires a Durable Object 'ctx' — pass it explicitly, or call from within an Agent so it can be resolved via getCurrentAgent()");
-	const connector = new BrowserSessionConnector(ctx, { browser: options.browser });
-	const codemodeTool = createCodemodeRuntime({
-		ctx,
-		executor: new DynamicWorkerExecutor({
-			loader: options.loader,
-			timeout: options.timeoutMs
-		}),
-		connectors: [connector],
-		name: browserRuntimeName(options.browser.name),
-		transformResult: transformBrowserResult
-	}).tool({ connectorHints: { cdp: `A persistent browser over CDP — tabs and logins carry over between runs. Use sessionId: "active" for page commands. ${adapter.screenshotHint}` } });
+	const timeout = options.timeoutMs ?? DEFAULT_TIMEOUT_MS;
+	const executor = new DynamicWorkerExecutor({
+		loader: options.loader,
+		timeout
+	});
+	const description = [
+		"Run JavaScript that drives a persistent Chrome browser over the Chrome DevTools Protocol (CDP).",
+		"",
+		"Write an async arrow function, `async () => { ... }`, and return a small JSON value. Use the `cdp` global to reach the browser. `fetch` is blocked and there is no file system or Node.js API.",
+		"",
+		"## cdp",
+		"",
+		"- `cdp.send({ method, params?, sessionId?, timeoutMs? })` sends a CDP command and returns its result without the JSON-RPC envelope: `Page.navigate` returns `{ frameId, errorText? }`, `Runtime.evaluate` returns `{ result: { value }, exceptionDetails? }`.",
+		"- `cdp.attachToTarget({ targetId })` makes an open tab active and returns `{ sessionId }`.",
+		"- `cdp.spec()` returns the whole protocol (about 650 KB) as `{ domains: [{ name, commands, events, types }] }`. Filter it in code, for example `spec.domains.find((d) => d.name === \"Page\").commands.find((c) => c.name === \"navigate\")`.",
+		"- `cdp.getDebugLog()` returns recent protocol traffic, for when a command fails or times out.",
+		"",
+		"## Rules",
+		"",
+		[
+			BROWSER_INSTRUCTIONS,
+			`Each run times out after ${Math.round(timeout / 1e3)}s, so split long jobs (crawling a site, say) across runs.`,
+			adapter.screenshotHint
+		].join("\n").split("\n").map((rule) => `- ${rule}`).join("\n"),
+		"- A `SyntaxError` from \"Failed to start Worker\" means your code didn't parse; its line number points into wrapper code, not yours. Check regex literals and escapes."
+	].join("\n");
+	const durableCtx = ctx;
+	const scopes = /* @__PURE__ */ new Map();
+	function scoped(scope) {
+		const cached = scopes.get(scope);
+		if (cached) {
+			scopes.delete(scope);
+			scopes.set(scope, cached);
+			return cached;
+		}
+		const connector = new BrowserSessionConnector(durableCtx, {
+			browser: options.browser,
+			scope
+		});
+		const built = {
+			connector,
+			tool: createCodemodeRuntime({
+				ctx: durableCtx,
+				executor,
+				connectors: [connector],
+				name: browserRuntimeName(options.browser.name),
+				transformResult: transformBrowserResult
+			}).tool({ description })
+		};
+		scopes.set(scope, built);
+		if (scopes.size > MAX_CACHED_SCOPES) {
+			const oldest = scopes.keys().next().value;
+			if (oldest !== void 0) scopes.delete(oldest);
+		}
+		return built;
+	}
+	const defaultScope = options.scope ?? "shared";
+	const { inputSchema } = scoped(defaultScope).tool;
 	return {
-		description: codemodeTool.description,
-		inputSchema: codemodeTool.inputSchema,
-		execute: async (input, executeOptions) => {
-			const output = await codemodeTool.execute(input, executeOptions);
+		description,
+		inputSchema,
+		/** Run `input` in `scope`, which defaults to the tool's `scope`. */
+		execute: (input, scope = defaultScope) => queued(options.browser, scope, async () => {
+			const { connector, tool } = scoped(scope);
+			const output = await tool.execute(input, void 0);
 			return withBrowserReport(output, connector.takeReport(output.executionId));
-		}
+		})
 	};
 }
 //#endregion
 export { createBrowserToolCore as n, browserReportNotes as t };
 
-//# sourceMappingURL=browser-tool-CQ10e6Kj.js.map
+//# sourceMappingURL=browser-tool-4iomavs_.js.map