agentic-browser 2.8.0 → 2.8.1

package/README.md

@@ -144,7 +144,7 @@ agentic-browser agent elements --roles button,link,input --visible-only --limit
 agentic-browser agent elements --selector "#main-content"
 ```
 
-Returns a JSON array of elements with selectors and fallback selectors usable in the typed agent commands like `agent click`, `agent type`, and `agent select`. Main-content elements come first; header, nav and footer links come last. Each element also gets a short ref (`e1`, `e2`, ...): `agent click e3` resolves it to the stored selector. Refs are valid until the next `agent navigate`:
+Returns a JSON array of elements with selectors and fallback selectors usable in the typed agent commands like `agent click`, `agent type`, and `agent select`. Main-content elements come first; header, nav and footer links come last. Each element also gets a short ref (`e1`, `e2`, ...): `agent click e3` resolves it to the stored selector. Refs stay valid while the page URL is unchanged; after navigating, run `agent elements` again:
 
 ```json
 {
@@ -275,7 +275,7 @@ agentic-browser memory:stats
 
 1. `agent start` — launch Chrome and persist session.
 2. `agent elements` — discover what's on the page.
-3. `agent navigate`, `agent click`, `agent type`, `agent select`, and related typed commands — execute actions using element refs or selectors. Pass `--intent "<task>"` to group the steps of one task in memory.
+3. `agent navigate`, `agent click`, `agent type`, `agent select`, and related typed commands — execute actions using element refs or selectors. Pass `--intent "<task>"` (an `agent`-level option, accepted before or after the subcommand) to group the steps of one task in memory. Consecutive steps with the same intent form one run; a new run replaces the stored recipe, so it always holds the latest run's steps in order.
 4. `agent content` — read page content after actions.
 5. `agent memory-search "<task>"` — matching is fuzzy; results include a `recipe` with the steps that worked last time (`needsInput` marks typed text that was redacted).
 6. `agent stop` — terminate when done.

package/dist/cli/index.mjs

@@ -1,35 +1,11 @@
 #!/usr/bin/env node
-import { a as isConnectionError, o as ensurePrivateDir, r as createCliRuntime, s as writePrivateFileSync } from "../runtime-DdEXOpiU.mjs";
+import { c as writePrivateFileSync, o as isConnectionError, r as createCliRuntime, s as ensurePrivateDir } from "../runtime-CgX6XW9u.mjs";
 import fs from "node:fs";
 import path from "node:path";
 import crypto from "node:crypto";
 import { Command } from "commander";
 // src/cli/commands/agent.ts
 const STATE_FILE_NAME = "agent-state.json";
-const REF_PATTERN = /^@?(e\d+)$/;
-function storeRefs(runtime, refs) {
-	saveState(runtime, {
-		...loadState(runtime),
-		refs
-	});
-}
-/**
-* Swap a short ref ("e3" or "@e3") from the last `agent elements` call for the
-* selector it stands for. Plain selectors pass through untouched.
-*/
-function resolveRef(runtime, sessionId, input) {
-	const match = input.selector ? REF_PATTERN.exec(input.selector) : null;
-	if (!match) return input;
-	const state = loadState(runtime);
-	const stored = state.refs?.sessionId === sessionId ? state.refs.byRef[match[1]] : void 0;
-	if (!stored) throw new Error(`Unknown or stale ref "${input.selector}". Run "agent elements" to refresh element refs.`);
-	return {
-		...input,
-		selector: stored.selector,
-		fallbackSelectors: [...stored.fallbackSelectors ?? [], ...input.fallbackSelectors ?? []],
-		frame: input.frame ?? stored.frame
-	};
-}
 function stateFilePath(runtime) {
 	return path.join(runtime.context.config.dataDir, STATE_FILE_NAME);
 }
@@ -111,7 +87,8 @@ async function executeAgentCommand(runtime, input) {
 	const attempt = () => runtime.api.executeCommand(sessionId, {
 		commandId: nextCommandId(),
 		type: input.type,
-		payload: input.payload
+		payload: input.payload,
+		intent: input.intent
 	});
 	const retryAfterRestart = async () => {
 		await runtime.api.restartSession(sessionId);
@@ -135,16 +112,12 @@ async function executeAgentCommand(runtime, input) {
 async function agentNavigate(runtime, input) {
 	const result = await executeAgentCommand(runtime, {
 		type: "navigate",
-		payload: input.intent ? {
-			url: input.url,
-			intent: input.intent
-		} : { url: input.url }
+		payload: { url: input.url },
+		intent: input.intent
 	});
-	storeRefs(runtime, void 0);
 	let cookieBanner;
 	if (result.resultStatus === "success") try {
-		const sessionId = requireSessionId(runtime);
-		const dismissed = await runtime.api.dismissCookieBanner(sessionId);
+		const dismissed = await runtime.api.dismissCookieBanner(result.sessionId);
 		if (dismissed.dismissed) cookieBanner = dismissed;
 	} catch {}
 	const page = await tryPageState(runtime, result.sessionId);
@@ -156,10 +129,13 @@ async function agentNavigate(runtime, input) {
 		cookieBanner
 	};
 }
+/** `selector` may be a ref ("e3") from `agent elements`; the core resolves it. */
 async function agentInteract(runtime, input) {
+	const { intent, ...payload } = input;
 	const result = await executeAgentCommand(runtime, {
 		type: "interact",
-		payload: resolveRef(runtime, requireSessionId(runtime), input)
+		payload,
+		intent
 	});
 	const page = await tryPageState(runtime, result.sessionId);
 	return {
@@ -390,37 +366,18 @@ async function agentScreenshot(runtime, input) {
 async function agentElements(runtime, input) {
 	const sessionId = requireSessionId(runtime);
 	await ensureReady(runtime, sessionId);
-	const result = await runtime.api.getInteractiveElements(sessionId, {
-		roles: input.roles,
-		visibleOnly: input.visibleOnly,
-		limit: input.limit,
-		selector: input.selector,
-		href: input.href,
-		text: input.text,
-		frame: input.frame
-	});
-	const byRef = {};
-	const elements = result.elements.map((element, index) => {
-		const ref = `e${index + 1}`;
-		byRef[ref] = {
-			selector: element.selector,
-			fallbackSelectors: element.fallbackSelectors,
-			frame: input.frame
-		};
-		return {
-			ref,
-			...element
-		};
-	});
-	storeRefs(runtime, {
-		sessionId,
-		byRef
-	});
 	return {
 		ok: true,
 		action: "elements",
-		...result,
-		elements
+		...await runtime.api.getInteractiveElements(sessionId, {
+			roles: input.roles,
+			visibleOnly: input.visibleOnly,
+			limit: input.limit,
+			selector: input.selector,
+			href: input.href,
+			text: input.text,
+			frame: input.frame
+		})
 	};
 }
 async function agentMemorySearch(runtime, input) {
@@ -602,7 +559,9 @@ async function main() {
 		const result = await runMemoryStats(runtime);
 		console.log(JSON.stringify(result));
 	});
-	const agent = program.command("agent").description("Stateful agent wrapper with session persistence and auto-retry");
+	const agent = program.command("agent").description("Stateful agent wrapper with session persistence and auto-retry").option("--intent <task>", INTENT_HELP);
+	/** --intent of the current agent step command; memory groups steps by it. */
+	const stepIntent = () => agent.opts().intent;
 	agent.command("start").option("--cdp-url <url>", "connect to existing Chrome via CDP endpoint URL").option("--user-profile <path>", "use 'default' for system Chrome profile or an absolute path").option("--headless", "run Chrome in headless mode (no visible window)").option("--user-agent <string>", "override the browser user-agent string").action(async (options) => {
 		if (options.cdpUrl) runtime.context.config.cdpUrl = options.cdpUrl;
 		if (options.userProfile) runtime.context.config.userProfileDir = options.userProfile === "true" || options.userProfile === "default" ? "default" : options.userProfile;
@@ -619,24 +578,24 @@ async function main() {
 		const result = await agentStop(runtime);
 		console.log(JSON.stringify(result));
 	});
-	agent.command("navigate").argument("<url>").option("--intent <task>", INTENT_HELP).action(async (url, options) => {
+	agent.command("navigate").argument("<url>").action(async (url) => {
 		const result = await agentNavigate(runtime, {
 			url,
-			intent: options.intent
+			intent: stepIntent()
 		});
 		console.log(JSON.stringify(result));
 	});
-	agent.command("click").argument("[selector]", "element ref (e3) from agent elements, CSS selector, or composed locator (a >>> b)").option("--text <text>", "click the element with this visible text instead of a selector").option("--exact", "with --text: require an exact text match").option("--frame <selector>", FRAME_HELP).option("--fallback <selector>", "backup CSS selector", collect, []).option("--intent <task>", INTENT_HELP).action(async (selector, options) => {
+	agent.command("click").argument("[selector]", "element ref (e3) from agent elements, CSS selector, or composed locator (a >>> b)").option("--text <text>", "click the element with this visible text instead of a selector").option("--exact", "with --text: require an exact text match").option("--frame <selector>", FRAME_HELP).option("--fallback <selector>", "backup CSS selector", collect, []).action(async (selector, options) => {
 		const result = await agentInteract(runtime, {
 			action: "click",
 			selector: resolveTarget(selector, options),
 			frame: options.frame,
 			fallbackSelectors: options.fallback,
-			intent: options.intent
+			intent: stepIntent()
 		});
 		console.log(JSON.stringify(result));
 	});
-	agent.command("type").argument("<selectorOrText>", "element ref (e3), CSS selector, or the text to type when --into-text is used").argument("[text]").option("--into-text <label>", "target the field by its visible text/label/placeholder").option("--frame <selector>", FRAME_HELP).option("--fallback <selector>", "backup CSS selector", collect, []).option("--intent <task>", INTENT_HELP).action(async (first, second, options) => {
+	agent.command("type").argument("<selectorOrText>", "element ref (e3), CSS selector, or the text to type when --into-text is used").argument("[text]").option("--into-text <label>", "target the field by its visible text/label/placeholder").option("--frame <selector>", FRAME_HELP).option("--fallback <selector>", "backup CSS selector", collect, []).action(async (first, second, options) => {
 		const selector = options.intoText ? `text=${options.intoText}` : first;
 		const text = options.intoText ? first : second;
 		if (text === void 0) throw new Error("Missing text to type");
@@ -646,15 +605,15 @@ async function main() {
 			text,
 			frame: options.frame,
 			fallbackSelectors: options.fallback,
-			intent: options.intent
+			intent: stepIntent()
 		});
 		console.log(JSON.stringify(result));
 	});
-	agent.command("press").argument("<key>").option("--intent <task>", INTENT_HELP).action(async (key, options) => {
+	agent.command("press").argument("<key>").action(async (key) => {
 		const result = await agentInteract(runtime, {
 			action: "press",
 			key,
-			intent: options.intent
+			intent: stepIntent()
 		});
 		console.log(JSON.stringify(result));
 	});
@@ -669,43 +628,43 @@ async function main() {
 		});
 		console.log(JSON.stringify(result));
 	});
-	agent.command("hover").argument("[selector]").option("--text <text>", "hover the element with this visible text").option("--exact", "with --text: require an exact text match").option("--frame <selector>", FRAME_HELP).option("--fallback <selector>", "backup CSS selector", collect, []).option("--intent <task>", INTENT_HELP).action(async (selector, options) => {
+	agent.command("hover").argument("[selector]").option("--text <text>", "hover the element with this visible text").option("--exact", "with --text: require an exact text match").option("--frame <selector>", FRAME_HELP).option("--fallback <selector>", "backup CSS selector", collect, []).action(async (selector, options) => {
 		const result = await agentInteract(runtime, {
 			action: "hover",
 			selector: resolveTarget(selector, options),
 			frame: options.frame,
 			fallbackSelectors: options.fallback,
-			intent: options.intent
+			intent: stepIntent()
 		});
 		console.log(JSON.stringify(result));
 	});
-	agent.command("select").argument("<selector>").argument("<value>").option("--frame <selector>", FRAME_HELP).option("--fallback <selector>", "backup CSS selector", collect, []).option("--intent <task>", INTENT_HELP).action(async (selector, value, options) => {
+	agent.command("select").argument("<selector>").argument("<value>").option("--frame <selector>", FRAME_HELP).option("--fallback <selector>", "backup CSS selector", collect, []).action(async (selector, value, options) => {
 		const result = await agentInteract(runtime, {
 			action: "select",
 			selector,
 			value,
 			frame: options.frame,
 			fallbackSelectors: options.fallback,
-			intent: options.intent
+			intent: stepIntent()
 		});
 		console.log(JSON.stringify(result));
 	});
-	agent.command("toggle").argument("<selector>").option("--frame <selector>", FRAME_HELP).option("--fallback <selector>", "backup CSS selector", collect, []).option("--intent <task>", INTENT_HELP).action(async (selector, options) => {
+	agent.command("toggle").argument("<selector>").option("--frame <selector>", FRAME_HELP).option("--fallback <selector>", "backup CSS selector", collect, []).action(async (selector, options) => {
 		const result = await agentInteract(runtime, {
 			action: "toggle",
 			selector,
 			frame: options.frame,
 			fallbackSelectors: options.fallback,
-			intent: options.intent
+			intent: stepIntent()
 		});
 		console.log(JSON.stringify(result));
 	});
-	agent.command("scroll").option("--x <pixels>", "horizontal scroll delta", "0").option("--y <pixels>", "vertical scroll delta", "0").option("--selector <selector>", "scroll a specific element instead of the page").option("--fallback <selector>", "backup CSS selector", collect, []).option("--intent <task>", INTENT_HELP).action(async (options) => {
+	agent.command("scroll").option("--x <pixels>", "horizontal scroll delta", "0").option("--y <pixels>", "vertical scroll delta", "0").option("--selector <selector>", "scroll a specific element instead of the page").option("--fallback <selector>", "backup CSS selector", collect, []).action(async (options) => {
 		const result = await agentInteract(runtime, {
 			action: "scroll",
 			selector: options.selector,
 			fallbackSelectors: options.fallback,
-			intent: options.intent,
+			intent: stepIntent(),
 			scrollX: Number.parseInt(options.x, 10),
 			scrollY: Number.parseInt(options.y, 10)
 		});

package/dist/index.d.mts

@@ -49,6 +49,8 @@ interface InteractiveElement {
   ariaLabel?: string;
   placeholder?: string;
   currentValue?: string;
+  /** Short handle ("e3") usable in place of the selector until the page changes. */
+  ref?: string;
 }
 interface InteractiveElementsOptions {
   roles?: InteractiveElementRole[];
@@ -171,6 +173,7 @@ declare const TaskInsightSchema: z.ZodObject<{
     selector: z.ZodOptional<z.ZodString>;
     payload: z.ZodDefault<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
   }, z.core.$strip>>;
+  recipeRunId: z.ZodOptional<z.ZodString>;
   expectedOutcome: z.ZodString;
   confidence: z.ZodNumber;
   successCount: z.ZodNumber;
@@ -408,6 +411,11 @@ interface RecordExecutionInput {
   expectedOutcome: string;
   url?: string;
   selector?: string;
+  /**
+   * Run this step belongs to. A step from a new run starts the recipe over, so
+   * the recipe is always the latest run's steps in order. Defaults to commandId.
+   */
+  runId?: string;
 }
 declare class MemoryService {
   private readonly store;
@@ -461,6 +469,7 @@ declare class MemoryService {
   private createEvidence;
   private maybeGenerateAliases;
   private deriveAliasName;
+  /** Same run: append the step. New run: its first step replaces the old recipe. */
   private mergeRecipe;
 }
 interface AppContext {
@@ -470,12 +479,43 @@ interface AppContext {
   tokenService: SessionTokenService;
   memoryService: MemoryService;
 }
+/**
+ * Short, stable handles ("e1", "e2", …) an agent can point at instead of
+ * authoring CSS selectors — the way a human points at what they see rather
+ * than reasoning about the DOM.
+ *
+ * Refs are ephemeral per "look": each element listing replaces the session's
+ * ref set, and a ref only resolves while the page URL is the one it was taken
+ * on. SessionManager persists them on the session record, so the CLI (one
+ * process per command) and the MCP server share the same mechanism.
+ */
+interface ResolvedRef {
+  selector: string;
+  fallbackSelectors?: string[];
+  /** Iframe the element was discovered in, so the ref acts inside it. */
+  frame?: string;
+}
+interface StoredRefs {
+  /** Page the refs were taken on; on any other page they are stale. */
+  url?: string;
+  byRef: Record<string, ResolvedRef>;
+}
 interface StoredSessionRecord {
   session: Session;
   cdpUrl: string;
   targetWsUrl: string;
   pid: number;
   lastUrl?: string;
+  /** Element refs from the last element listing. */
+  refs?: StoredRefs;
+  /**
+   * The task run in progress: consecutive commands with the same explicit
+   * intent share `runId`, so memory can rebuild that task's recipe per run.
+   */
+  intentRun?: {
+    intent: string;
+    runId: string;
+  };
 }
 interface CreateSessionInput {
   browser: "chrome";
@@ -484,6 +524,8 @@ interface ExecuteCommandInput$1 {
   commandId: string;
   type: CommandType;
   payload: Record<string, unknown>;
+  /** Task this step belongs to (e.g. "log in"); memory groups steps by it. */
+  intent?: string;
 }
 interface CleanupInput {
   maxAgeDays?: number;
@@ -504,9 +546,15 @@ declare class SessionManager {
   getSession(sessionId: string): Session;
   /** Return a healthy session, recovering automatically if needed. */
   ensureSession(sessionId: string): Promise<StoredSessionRecord>;
-  executeCommand(sessionId: string, input: ExecuteCommandInput$1): Promise<Command>;
+  executeCommand(sessionId: string, rawInput: ExecuteCommandInput$1): Promise<Command>;
   getContent(sessionId: string, options: PageContentOptions): Promise<PageContentResult>;
-  getInteractiveElements(sessionId: string, options: InteractiveElementsOptions): Promise<InteractiveElementsResult>;
+  /** Lists interactive elements and assigns fresh refs (e1, e2, …) for this page. */
+  getInteractiveElements(sessionId: string, options: InteractiveElementsOptions): Promise<{
+    totalFound: number;
+    truncated: boolean;
+    crossOriginFrames?: CrossOriginFrameInfo[];
+    elements: InteractiveElement[];
+  }>;
   screenshot(sessionId: string, options?: ScreenshotOptions): Promise<ScreenshotResult>;
   getCurrentUrl(sessionId: string): Promise<string>;
   getPageState(sessionId: string): Promise<PageState>;
@@ -544,6 +592,7 @@ declare class SessionManager {
       selector?: string | undefined;
       payload: Record<string, unknown>;
     }[];
+    recipeRunId?: string | undefined;
     expectedOutcome: string;
     confidence: number;
     successCount: number;
@@ -581,6 +630,7 @@ declare class SessionManager {
       selector?: string | undefined;
       payload: Record<string, unknown>;
     }[];
+    recipeRunId?: string | undefined;
     expectedOutcome: string;
     confidence: number;
     successCount: number;
@@ -625,6 +675,12 @@ declare class SessionManager {
   private mustGetRecord;
   private recordEvent;
   private buildMemoryContext;
+  private resolveRef;
+  /**
+   * Consecutive commands with the same explicit intent form one run; any other
+   * command ends it. Commands without an intent are each their own run.
+   */
+  private trackIntentRun;
   private parseUrl;
 }
 declare class ControlApi {
@@ -653,6 +709,7 @@ declare class ControlApi {
     commandId: string;
     type: "navigate" | "interact" | "restart" | "terminate";
     payload: Record<string, unknown>;
+    intent?: string;
   }): Promise<{
     commandId: string;
     sessionId: string;
@@ -677,7 +734,12 @@ declare class ControlApi {
     selector?: string;
     maxChars?: number;
   }): Promise<PageContentResult>;
-  getInteractiveElements(sessionId: string, options: InteractiveElementsOptions): Promise<InteractiveElementsResult>;
+  getInteractiveElements(sessionId: string, options: InteractiveElementsOptions): Promise<{
+    totalFound: number;
+    truncated: boolean;
+    crossOriginFrames?: CrossOriginFrameInfo[];
+    elements: InteractiveElement[];
+  }>;
   dismissCookieBanner(sessionId: string): Promise<DismissCookieBannerResult>;
   screenshot(sessionId: string, options?: ScreenshotOptions): Promise<ScreenshotResult>;
   getCurrentUrl(sessionId: string): Promise<string>;
@@ -719,6 +781,7 @@ declare class ControlApi {
       selector?: string | undefined;
       payload: Record<string, unknown>;
     }[];
+    recipeRunId?: string | undefined;
     expectedOutcome: string;
     confidence: number;
     successCount: number;
@@ -756,6 +819,7 @@ declare class ControlApi {
       selector?: string | undefined;
       payload: Record<string, unknown>;
     }[];
+    recipeRunId?: string | undefined;
     expectedOutcome: string;
     confidence: number;
     successCount: number;
@@ -806,6 +870,8 @@ interface ExecuteCommandInput {
   commandId?: string;
   type: CommandType;
   payload: Record<string, unknown>;
+  /** Task this step belongs to (e.g. "log in"); memory groups steps by it. */
+  intent?: string;
 }
 export declare class AgenticBrowserCore {
   readonly context: AppContext;
@@ -863,7 +929,12 @@ export declare class AgenticBrowserCore {
     href?: string;
     text?: string;
     frame?: string;
-  }): Promise<InteractiveElementsResult>;
+  }): Promise<{
+    totalFound: number;
+    truncated: boolean;
+    crossOriginFrames?: CrossOriginFrameInfo[];
+    elements: InteractiveElement[];
+  }>;
   dismissCookieBanner(sessionId: string): Promise<DismissCookieBannerResult>;
   screenshot(sessionId: string, options?: ScreenshotOptions): Promise<ScreenshotResult>;
   getCurrentUrl(sessionId: string): Promise<string>;
@@ -905,6 +976,7 @@ export declare class AgenticBrowserCore {
       selector?: string | undefined;
       payload: Record<string, unknown>;
     }[];
+    recipeRunId?: string | undefined;
     expectedOutcome: string;
     confidence: number;
     successCount: number;
@@ -942,6 +1014,7 @@ export declare class AgenticBrowserCore {
       selector?: string | undefined;
       payload: Record<string, unknown>;
     }[];
+    recipeRunId?: string | undefined;
     expectedOutcome: string;
     confidence: number;
     successCount: number;

package/dist/index.mjs

@@ -1,2 +1,2 @@
 #!/usr/bin/env node
-export { t as AgenticBrowserCore, n as createAgenticBrowserCore, i as createMockAgenticBrowserCore } from "./runtime-DdEXOpiU.mjs";
+export { t as AgenticBrowserCore, n as createAgenticBrowserCore, i as createMockAgenticBrowserCore } from "./runtime-CgX6XW9u.mjs";

package/dist/mcp/index.mjs

@@ -1,5 +1,5 @@
 #!/usr/bin/env node
-import { n as createAgenticBrowserCore } from "../runtime-DdEXOpiU.mjs";
+import { a as StaleRefError, n as createAgenticBrowserCore } from "../runtime-CgX6XW9u.mjs";
 import { readFileSync } from "node:fs";
 import { dirname, join } from "node:path";
 import { fileURLToPath } from "node:url";
@@ -204,46 +204,6 @@ function compactMemoryResults(results) {
 		return compact;
 	}) };
 }
-// src/mcp/element-refs.ts
-var ElementRefRegistry = class {
-	bySession = /* @__PURE__ */ new Map();
-	/**
-	* Assign fresh refs to a freshly-discovered element list, replacing any prior
-	* refs for the session. Elements without a selector (nothing to act on) are
-	* still returned but get no ref.
-	*/
-	assign(sessionId, elements) {
-		const map = /* @__PURE__ */ new Map();
-		let n = 0;
-		const annotated = elements.map((el) => {
-			if (!el.selector) return {
-				...el,
-				ref: ""
-			};
-			const ref = `e${++n}`;
-			map.set(ref, {
-				selector: el.selector,
-				fallbackSelectors: el.fallbackSelectors,
-				text: el.text,
-				role: el.role
-			});
-			return {
-				...el,
-				ref
-			};
-		});
-		this.bySession.set(sessionId, map);
-		return { elements: annotated };
-	}
-	/** Resolve a ref to its selector target, or undefined if unknown/stale. */
-	resolve(sessionId, ref) {
-		return this.bySession.get(sessionId)?.get(ref);
-	}
-	/** Drop a session's refs (on stop/restart) so stale handles can't resolve. */
-	clear(sessionId) {
-		this.bySession.delete(sessionId);
-	}
-};
 // src/mcp/session-resolver.ts
 /**
 * Tracks the active session and auto-starts one on demand. Concurrent callers
@@ -318,7 +278,6 @@ function getCore() {
 function genId(prefix) {
 	return `${prefix}-${Date.now()}-${Math.random().toString(36).slice(2, 8)}`;
 }
-const refs = new ElementRefRegistry();
 /**
 * Discover interactive elements, assign fresh refs for the session, and return
 * the compact agent-facing view (refs + role/text, no raw selectors). This is
@@ -334,8 +293,7 @@ async function snapshotElements(sessionId, opts = {}) {
 		selector: opts.selector,
 		roles: opts.roles
 	});
-	const { elements } = refs.assign(sessionId, result.elements);
-	return compactInteractiveElementsResult(elements, {
+	return compactInteractiveElementsResult(result.elements, {
 		totalFound: result.totalFound,
 		truncated: result.truncated
 	}, visibleOnly);
@@ -347,6 +305,7 @@ async function snapshotElements(sessionId, opts = {}) {
 async function resolveSession(sessionId) {
 	return sessionResolver.resolve(sessionId);
 }
+const intentParam = z.string().optional().describe("Task this step belongs to, in your own words (e.g. \"log in\", \"search products\"). Steps sharing an intent are remembered together and returned as a recipe by browser_search_memory");
 const server = new McpServer({
 	name: "agentic-browser",
 	version: readPackageVersion()
@@ -362,7 +321,7 @@ server.tool("browser_start_session", "Start a new Chrome browser session (or ret
 });
 server.tool("browser_navigate", "Navigate the browser to a URL. A session is auto-started if needed.", {
 	url: z.string().describe("The URL to navigate to"),
-	intent: z.string().optional().describe("Task this step belongs to, in your own words (e.g. \"log in\", \"search products\"). Steps sharing an intent are remembered together and returned as a recipe by browser_search_memory"),
+	intent: intentParam,
 	sessionId: z.string().optional().describe("Session ID (auto-resolved if omitted)")
 }, async ({ url, intent, sessionId }) => {
 	const sid = await resolveSession(sessionId);
@@ -370,10 +329,8 @@ server.tool("browser_navigate", "Navigate the browser to a URL. A session is aut
 		sessionId: sid,
 		commandId: genId("nav"),
 		type: "navigate",
-		payload: intent ? {
-			url,
-			intent
-		} : { url }
+		payload: { url },
+		intent
 	});
 	let cookieBanner;
 	if (result.resultStatus === "success") try {
@@ -420,40 +377,40 @@ server.tool("browser_interact", "Interact with a page element or perform browser
 	scrollX: z.number().optional().describe("Horizontal scroll delta in pixels (for \"scroll\" action)"),
 	scrollY: z.number().optional().describe("Vertical scroll delta in pixels (for \"scroll\" action, positive = down)"),
 	timeoutMs: z.number().optional().describe("Timeout in milliseconds (for \"waitFor\" action, default 4000)"),
-	intent: z.string().optional().describe("Task this step belongs to, in your own words (e.g. \"log in\", \"search products\"). Steps sharing an intent are remembered together and returned as a recipe by browser_search_memory"),
+	intent: intentParam,
 	sessionId: z.string().optional().describe("Session ID (auto-resolved if omitted)")
 }, async ({ action, ref, selector, fallbackSelectors, text, key, value, scrollX, scrollY, timeoutMs, intent, sessionId }) => {
 	const sid = await resolveSession(sessionId);
 	const payload = { action };
-	if (intent) payload.intent = intent;
-	if (!selector && ref) {
-		const resolved = refs.resolve(sid, ref);
-		if (!resolved) return { content: [{
+	const target = selector ?? ref;
+	if (target) payload.selector = target;
+	if (fallbackSelectors) payload.fallbackSelectors = fallbackSelectors;
+	if (text) payload.text = text;
+	if (key) payload.key = key;
+	if (value) payload.value = value;
+	if (scrollX !== void 0) payload.scrollX = scrollX;
+	if (scrollY !== void 0) payload.scrollY = scrollY;
+	if (timeoutMs) payload.timeoutMs = timeoutMs;
+	let result;
+	try {
+		result = await getCore().runCommand({
+			sessionId: sid,
+			commandId: genId("int"),
+			type: "interact",
+			payload,
+			intent
+		});
+	} catch (error) {
+		if (!(error instanceof StaleRefError)) throw error;
+		return { content: [{
 			type: "text",
 			text: JSON.stringify({
 				resultStatus: "failed",
-				resultMessage: `Unknown or stale ref "${ref}". Call browser_get_elements to refresh element refs.`,
+				resultMessage: error.message,
 				errorCode: "SELECTOR_NOT_FOUND"
 			})
 		}] };
-		payload.selector = resolved.selector;
-		if (resolved.fallbackSelectors) payload.fallbackSelectors = resolved.fallbackSelectors;
-	} else {
-		if (selector) payload.selector = selector;
-		if (fallbackSelectors) payload.fallbackSelectors = fallbackSelectors;
 	}
-	if (text) payload.text = text;
-	if (key) payload.key = key;
-	if (value) payload.value = value;
-	if (scrollX !== void 0) payload.scrollX = scrollX;
-	if (scrollY !== void 0) payload.scrollY = scrollY;
-	if (timeoutMs) payload.timeoutMs = timeoutMs;
-	const result = await getCore().runCommand({
-		sessionId: sid,
-		commandId: genId("int"),
-		type: "interact",
-		payload
-	});
 	let currentUrl;
 	try {
 		currentUrl = await getCore().getCurrentUrl(sid);
@@ -580,7 +537,6 @@ server.tool("browser_stop_session", "Stop the browser session and terminate Chro
 		})
 	}] };
 	await getCore().stopSession(sid);
-	refs.clear(sid);
 	if (sessionResolver.current() === sid) sessionResolver.clear();
 	return { content: [{
 		type: "text",

package/dist/{runtime-DdEXOpiU.mjs → runtime-CgX6XW9u.mjs}

@@ -454,6 +454,22 @@ function resolveDefaultProfileDir() {
 	return path.join(home, ".config", "google-chrome");
 }
 const CONTENT_TRUNCATION_HINT = "Use a CSS selector to scope the content, or use mode=\"summary\" for a lower-token overview.";
+/**
+* In-page visibility check shared by element discovery and cookie dismissal.
+* Uses the element's own window so it also works inside same-origin iframes.
+*/
+const IN_PAGE_IS_VISIBLE = String.raw`
+      function isVisible(el) {
+        if (!el) return false;
+        const view = (el.ownerDocument && el.ownerDocument.defaultView) || window;
+        const style = view.getComputedStyle(el);
+        if (style.display === 'none' || style.visibility === 'hidden' || style.opacity === '0') {
+          return false;
+        }
+        const rect = el.getBoundingClientRect();
+        return rect.width > 0 && rect.height > 0;
+      }
+`;
 const LOCATOR_RUNTIME_HELPERS = String.raw`
       const LOCATOR_SEPARATOR = ' >>> ';
 
@@ -2235,12 +2251,23 @@ var ChromeCdpBrowserController = class {
           current = parent;
         }
         // Prefer the shortest unique tail of the path: long nth-of-type chains
-        // cost tokens and break on the slightest layout change.
-        for (let size = 1; size < parts.length; size += 1) {
+        // cost tokens and break on the slightest layout change. A longer tail
+        // matches a subset of a shorter one, so uniqueness is monotonic in the
+        // tail length and a binary search finds the shortest unique tail.
+        let best = parts.join(' > ');
+        let lo = 1;
+        let hi = parts.length - 1;
+        while (lo <= hi) {
+          const size = (lo + hi) >> 1;
           const candidate = tryUniqueSelector(root, parts.slice(-size).join(' > '));
-          if (candidate) return candidate;
+          if (candidate) {
+            best = candidate;
+            hi = size - 1;
+          } else {
+            lo = size + 1;
+          }
         }
-        return parts.join(' > ');
+        return best;
       }
 
       function buildFallbackSelectors(root, path, el, primarySelector) {
@@ -2334,18 +2361,7 @@ var ChromeCdpBrowserController = class {
         }
       }
 
-      function viewForElement(el) {
-        return el.ownerDocument && el.ownerDocument.defaultView ? el.ownerDocument.defaultView : window;
-      }
-
-      function isVisible(el) {
-        const style = viewForElement(el).getComputedStyle(el);
-        if (style.display === 'none' || style.visibility === 'hidden' || style.opacity === '0') {
-          return false;
-        }
-        const rect = el.getBoundingClientRect();
-        return rect.width > 0 && rect.height > 0;
-      }
+${IN_PAGE_IS_VISIBLE}
 
       function getText(el) {
         const ariaLabel = el.getAttribute('aria-label');
@@ -2437,17 +2453,33 @@ var ChromeCdpBrowserController = class {
         }
 
         totalFound += 1;
-        candidates.push({ root, path, el, role, visible, rank: rankElement(el, visible), order: candidates.length });
+        candidates.push({ root, path, el, role, visible, rank: rankElement(el, visible) });
       }
 
       // Lower rank sorts first: main content, then the rest of the page, then
       // site chrome (header, nav, footer), then hidden elements. Ties keep
       // document order.
+      // Region flags per ancestor, memoized so siblings share the walk up the
+      // tree instead of each element running three closest() scans.
+      const FOOTER = 1, MAIN = 2, CHROME = 4;
+      const regionMemo = new Map();
+      function regionFlags(el) {
+        if (!el) return 0;
+        let flags = regionMemo.get(el);
+        if (flags !== undefined) return flags;
+        flags = regionFlags(el.parentElement);
+        if (el.matches('footer, [role="contentinfo"]')) flags |= FOOTER;
+        if (el.matches('main, [role="main"], article')) flags |= MAIN;
+        if (el.matches('header, nav, [role="banner"], [role="navigation"]')) flags |= CHROME;
+        regionMemo.set(el, flags);
+        return flags;
+      }
       function rankElement(el, visible) {
         if (!visible) return 3;
-        if (el.closest('footer, [role="contentinfo"]')) return 2;
-        if (el.closest('main, [role="main"], article')) return 0;
-        if (el.closest('header, nav, [role="banner"], [role="navigation"]')) return 2;
+        const flags = regionFlags(el);
+        if (flags & FOOTER) return 2;
+        if (flags & MAIN) return 0;
+        if (flags & CHROME) return 2;
         return 1;
       }
 
@@ -2521,7 +2553,8 @@ var ChromeCdpBrowserController = class {
       }
 
       walkRoot(document, []);
-      candidates.sort((a, b) => a.rank - b.rank || a.order - b.order);
+      // Array sort is stable, so ties keep document order.
+      candidates.sort((a, b) => a.rank - b.rank);
       const results = candidates.slice(0, limit).map(buildEntry);
       const output = { elements: results, totalFound, truncated: totalFound > results.length };
       if (crossOriginFrames.length) output.crossOriginFrames = crossOriginFrames;
@@ -2607,11 +2640,7 @@ var ChromeCdpBrowserController = class {
 	}
 	async dismissViaDom(targetWsUrl) {
 		const expression = `(() => {
-      function isVisible(el) {
-        if (!el) return false;
-        const style = getComputedStyle(el);
-        return style.display !== 'none' && style.visibility !== 'hidden' && style.opacity !== '0' && el.offsetWidth > 0;
-      }
+${IN_PAGE_IS_VISIBLE}
 
       // Comprehensive CMP selectors (ordered by specificity/popularity)
       const selectors = [
@@ -2914,12 +2943,17 @@ var ChromeCdpBrowserController = class {
         'iframe[src*="consentmanager"]',
       ];
 
-      const AD_HOSTS = ['doubleclick.net', 'googlesyndication.com', 'googleadservices.com', 'adservice.google.'];
-      function isAdFrame(iframe) {
-        const id = iframe.id || '';
-        if (id.startsWith('goog_') || id.startsWith('google_ads_iframe')) return true;
-        const src = iframe.src || '';
-        return AD_HOSTS.some((host) => src.includes(host));
+      // Consent prompts overlay the page: the frame or a close ancestor is
+      // fixed/sticky or stacked high. In-flow frames (ads, embeds) are skipped.
+      function isOverlay(iframe) {
+        let el = iframe;
+        for (let depth = 0; el && el !== document.body && depth < 10; depth++) {
+          const style = getComputedStyle(el);
+          if (style.position === 'fixed' || style.position === 'sticky') return true;
+          if ((parseInt(style.zIndex, 10) || 0) >= 1000) return true;
+          el = el.parentElement;
+        }
+        return false;
       }
       function isShown(iframe) {
         const rect = iframe.getBoundingClientRect();
@@ -2942,7 +2976,7 @@ var ChromeCdpBrowserController = class {
       }
       function findFrame(sel) {
         for (const iframe of document.querySelectorAll(sel)) {
-          if (isAdFrame(iframe) || !isShown(iframe) || !srcKeywordMatches(iframe, sel)) continue;
+          if (!isShown(iframe) || !srcKeywordMatches(iframe, sel) || !isOverlay(iframe)) continue;
           return iframe;
         }
         return null;
@@ -3413,6 +3447,40 @@ z.object({
 	createdAt: z.string().datetime(),
 	severity: EventSeveritySchema
 });
+// src/session/element-refs.ts
+/** Matches "e3" or "@e3"; group 1 is the bare ref. */
+const REF_PATTERN = /^@?(e\d+)$/;
+/**
+* Number elements e1, e2, … Elements without a selector (nothing to act on)
+* are still returned but get no ref.
+*/
+function assignRefs(elements, frame) {
+	const byRef = {};
+	let n = 0;
+	return {
+		elements: elements.map((el) => {
+			if (!el.selector) return el;
+			const ref = `e${++n}`;
+			byRef[ref] = {
+				selector: el.selector,
+				fallbackSelectors: el.fallbackSelectors,
+				frame
+			};
+			return {
+				...el,
+				ref
+			};
+		}),
+		byRef
+	};
+}
+/** A ref that was never assigned, or was taken on a different page. */
+var StaleRefError = class extends Error {
+	constructor(ref) {
+		super(`Unknown or stale ref "${ref}". List the page's elements again (agent elements / browser_get_elements) to get fresh refs.`);
+		this.name = "StaleRefError";
+	}
+};
 // src/session/session-store.ts
 var SessionStore = class {
 	filePath;
@@ -3457,12 +3525,16 @@ var SessionStore = class {
 		}
 	}
 	setLastUrl(sessionId, lastUrl) {
+		this.update(sessionId, { lastUrl });
+	}
+	/** Merge fields into a stored record; `undefined` values clear the field. */
+	update(sessionId, patch) {
 		const state = this.read();
 		const existing = state.sessions[sessionId];
 		if (!existing) throw new Error("Session not found in store");
 		state.sessions[sessionId] = {
 			...existing,
-			lastUrl
+			...patch
 		};
 		this.write(state);
 	}
@@ -3625,8 +3697,13 @@ var SessionManager = class {
 		}
 		throw new Error("Session is terminated. Start a new session.");
 	}
-	async executeCommand(sessionId, input) {
+	async executeCommand(sessionId, rawInput) {
 		const record = await this.ensureSession(sessionId);
+		const input = rawInput.type === "interact" ? {
+			...rawInput,
+			payload: await this.resolveRef(record, rawInput.payload)
+		} : rawInput;
+		const runId = this.trackIntentRun(sessionId, record, input);
 		const command = {
 			commandId: input.commandId,
 			sessionId,
@@ -3655,6 +3732,8 @@ var SessionManager = class {
 				const parsedPayload = InteractPayloadSchema.safeParse(input.payload);
 				if (!parsedPayload.success) throw new Error(`Invalid interact payload: ${parsedPayload.error.message}`);
 				resultMessage = `Interaction result: ${await this.browser.interact(record.targetWsUrl, parsedPayload.data)}`;
+				const currentUrl = await this.browser.getCurrentUrl(record.targetWsUrl).catch(() => void 0);
+				if (currentUrl) this.store.setLastUrl(sessionId, currentUrl);
 			} else if (input.type === "restart") {
 				await this.restartSession(sessionId);
 				resultMessage = "Session restarted";
@@ -3681,7 +3760,8 @@ var SessionManager = class {
 			expectedOutcome: resultMessage,
 			step: memoryContext.step,
 			selector: memoryContext.selector,
-			url: memoryContext.url
+			url: memoryContext.url,
+			runId
 		});
 		else this.ctx.memoryService.recordFailure({
 			commandId: input.commandId,
@@ -3711,9 +3791,20 @@ var SessionManager = class {
 		}
 		return result;
 	}
+	/** Lists interactive elements and assigns fresh refs (e1, e2, …) for this page. */
 	async getInteractiveElements(sessionId, options) {
 		const record = await this.ensureSession(sessionId);
-		return await this.browser.getInteractiveElements(record.targetWsUrl, options);
+		const result = await this.browser.getInteractiveElements(record.targetWsUrl, options);
+		const { elements, byRef } = assignRefs(result.elements, options.frame);
+		const url = await this.browser.getCurrentUrl(record.targetWsUrl).catch(() => void 0);
+		this.store.update(sessionId, { refs: {
+			url,
+			byRef
+		} });
+		return {
+			...result,
+			elements
+		};
 	}
 	async screenshot(sessionId, options) {
 		const record = await this.ensureSession(sessionId);
@@ -3848,7 +3939,8 @@ var SessionManager = class {
 			session: restarted,
 			cdpUrl: relaunched.cdpUrl,
 			targetWsUrl: relaunched.targetWsUrl,
-			pid: relaunched.pid
+			pid: relaunched.pid,
+			intentRun: record.intentRun
 		});
 		this.recordEvent(sessionId, "lifecycle", "info", "Session restarted");
 		return restarted;
@@ -3992,7 +4084,7 @@ var SessionManager = class {
 		const parsed = this.parseUrl(inputUrl);
 		const action = typeof input.payload.action === "string" ? input.payload.action : void 0;
 		const defaultIntent = input.type === "navigate" ? `navigate:${parsed.domain}` : input.type === "interact" ? `interact:${action ?? "action"}:${parsed.domain}` : `${input.type}:${parsed.domain}`;
-		const taskIntent = typeof input.payload.intent === "string" && input.payload.intent.trim() ? input.payload.intent : defaultIntent;
+		const taskIntent = explicitIntent(input) ?? defaultIntent;
 		const expectedOutcome = typeof input.payload.expectedOutcome === "string" && input.payload.expectedOutcome.trim() ? input.payload.expectedOutcome : `${input.type} command succeeds`;
 		return {
 			taskIntent,
@@ -4009,6 +4101,36 @@ var SessionManager = class {
 			url: inputUrl
 		};
 	}
+	async resolveRef(record, payload) {
+		const selector = typeof payload.selector === "string" ? payload.selector : void 0;
+		const ref = selector ? REF_PATTERN.exec(selector)?.[1] : void 0;
+		if (!selector || !ref) return payload;
+		const { refs } = record;
+		const stored = refs?.byRef[ref];
+		const onSamePage = !refs?.url || await this.browser.getCurrentUrl(record.targetWsUrl).catch(() => void 0) === refs.url;
+		if (!stored || !onSamePage) throw new StaleRefError(selector);
+		const extra = Array.isArray(payload.fallbackSelectors) ? payload.fallbackSelectors : [];
+		return {
+			...payload,
+			selector: stored.selector,
+			fallbackSelectors: [...stored.fallbackSelectors ?? [], ...extra],
+			frame: payload.frame ?? stored.frame
+		};
+	}
+	/**
+	* Consecutive commands with the same explicit intent form one run; any other
+	* command ends it. Commands without an intent are each their own run.
+	*/
+	trackIntentRun(sessionId, record, input) {
+		const intent = explicitIntent(input);
+		if (intent && record.intentRun?.intent === intent) return record.intentRun.runId;
+		const intentRun = intent ? {
+			intent,
+			runId: input.commandId
+		} : void 0;
+		if (intentRun || record.intentRun) this.store.update(sessionId, { intentRun });
+		return input.commandId;
+	}
 	parseUrl(rawUrl) {
 		if (!rawUrl) return {
 			domain: "unknown",
@@ -4019,7 +4141,7 @@ var SessionManager = class {
 			const firstSegment = parsed.pathname.split("/").filter(Boolean)[0];
 			const pathPattern = firstSegment ? `/${firstSegment}/*` : "/";
 			return {
-				domain: parsed.hostname.toLowerCase(),
+				domain: parsed.hostname.toLowerCase() || parsed.protocol.replace(/:$/, ""),
 				pathPattern
 			};
 		} catch {
@@ -4030,6 +4152,11 @@ var SessionManager = class {
 		}
 	}
 };
+/** The caller's task intent, if any. payload.intent is the older spelling, still honored. */
+function explicitIntent(input) {
+	const raw = input.intent ?? input.payload.intent;
+	return typeof raw === "string" && raw.trim() ? raw.trim() : void 0;
+}
 // src/transport/control-api.ts
 var ControlApi = class {
 	sessions;
@@ -4303,11 +4430,10 @@ function intentTokens(value, domain) {
 	return tokens;
 }
 /** 0 = unrelated; 1 = identical intent. Word overlap covers rephrased queries. */
-function intentSimilarity(insight, normalizedIntent) {
+function intentSimilarity(insight, normalizedIntent, query) {
 	const insightIntent = normalize(insight.taskIntent);
 	if (insightIntent === normalizedIntent) return 1;
 	if (insightIntent.includes(normalizedIntent) || normalizedIntent.includes(insightIntent)) return .65;
-	const query = intentTokens(normalizedIntent);
 	if (!query.size) return 0;
 	const stored = intentTokens(insightIntent, insight.siteDomain);
 	let shared = 0;
@@ -4357,12 +4483,19 @@ function selectorSignal(insight) {
 	const evidenceStrength = Math.min(selectorEvidence / 5, 1);
 	return .7 * recipeCoverage + .3 * evidenceStrength;
 }
-function scoreInsight(insight, normalizedIntent, normalizedDomain, profileLookup) {
-	const intentSignal = intentSimilarity(insight, normalizedIntent);
+function scoreInsight(insight, normalizedIntent, queryTokens, normalizedDomain) {
+	const intentSignal = intentSimilarity(insight, normalizedIntent, queryTokens);
 	const domainMatch = normalizedDomain && normalize(insight.siteDomain) === normalizedDomain ? 1 : normalizedDomain ? 0 : .6;
 	const reliability = .6 * confidenceFromCounts(insight.successCount, insight.failureCount) + .4 * freshnessWeight(insight.freshness);
 	const selectorQuality = selectorSignal(insight);
-	const score = .5 * intentSignal + .2 * domainMatch + .15 * reliability + .15 * selectorQuality;
+	return {
+		insight,
+		score: .5 * intentSignal + .2 * domainMatch + .15 * reliability + .15 * selectorQuality,
+		intentSignal
+	};
+}
+/** Builds the full result (recipe, hints, profile) — only for insights that are returned. */
+function toSearchResult({ insight, score }, profileLookup) {
 	const result = {
 		insightId: insight.insightId,
 		taskIntent: insight.taskIntent,
@@ -4382,10 +4515,7 @@ function scoreInsight(insight, normalizedIntent, normalizedDomain, profileLookup
 		cookieBanner: profile.cookieBanner,
 		visitCount: profile.visitCount
 	};
-	return {
-		result,
-		intentSignal
-	};
+	return result;
 }
 var MemoryIndex = class {
 	/** Domain → insights index, rebuilt lazily when insight list changes. */
@@ -4408,6 +4538,7 @@ var MemoryIndex = class {
 	}
 	search(insights, input, profileLookup) {
 		const normalizedIntent = normalize(input.taskIntent);
+		const queryTokens = intentTokens(normalizedIntent);
 		const normalizedDomain = input.siteDomain ? normalize(input.siteDomain) : void 0;
 		const limit = input.limit ?? 10;
 		this.ensureIndex(insights);
@@ -4416,16 +4547,16 @@ var MemoryIndex = class {
 		if (limit === 1 && normalizedDomain) {
 			let best;
 			for (const insight of candidates) {
-				const scored = scoreInsight(insight, normalizedIntent, normalizedDomain, profileLookup);
+				const scored = scoreInsight(insight, normalizedIntent, queryTokens, normalizedDomain);
 				if (!relevant(scored)) continue;
-				if (!best || scored.result.score > best.result.score) {
+				if (!best || scored.score > best.score) {
 					best = scored;
-					if (best.result.score >= 1) break;
+					if (best.score >= 1) break;
 				}
 			}
-			return best ? [best.result] : [];
+			return best ? [toSearchResult(best, profileLookup)] : [];
 		}
-		return candidates.map((insight) => scoreInsight(insight, normalizedIntent, normalizedDomain, profileLookup)).filter(relevant).toSorted((a, b) => b.result.score - a.result.score).slice(0, limit).map((scored) => scored.result);
+		return candidates.map((insight) => scoreInsight(insight, normalizedIntent, queryTokens, normalizedDomain)).filter(relevant).toSorted((a, b) => b.score - a.score).slice(0, limit).map((scored) => toSearchResult(scored, profileLookup));
 	}
 };
 // src/memory/staleness-detector.ts
@@ -4569,6 +4700,8 @@ const TaskInsightSchema = z.object({
 	siteDomain: z.string().min(1),
 	sitePathPattern: z.string().min(1),
 	actionRecipe: z.array(TaskStepSchema),
+	/** Run that produced actionRecipe; steps from another run start it over. */
+	recipeRunId: z.string().optional(),
 	expectedOutcome: z.string().min(1),
 	confidence: z.number().min(0).max(1),
 	successCount: z.number().int().nonnegative(),
@@ -4983,6 +5116,7 @@ var MemoryService = class {
 				siteDomain: input.siteDomain,
 				sitePathPattern: input.sitePathPattern,
 				actionRecipe: [input.step],
+				recipeRunId: input.runId ?? input.commandId,
 				expectedOutcome: input.expectedOutcome,
 				confidence: 1,
 				successCount: 1,
@@ -5005,7 +5139,7 @@ var MemoryService = class {
 			...matched,
 			useCount: matched.useCount + 1,
 			evidence: [...matched.evidence.slice(-49), evidence],
-			actionRecipe: this.mergeRecipe(matched.actionRecipe, input.step),
+			...this.mergeRecipe(matched, input.step, input.runId ?? input.commandId),
 			expectedOutcome: input.expectedOutcome
 		});
 		if (matched.freshness === "suspect" || matched.freshness === "stale") {
@@ -5214,9 +5348,16 @@ var MemoryService = class {
 		const testMatch = selector.match(/\[data-test="([^"]+)"\]/);
 		if (testMatch) return testMatch[1];
 	}
-	mergeRecipe(recipe, step) {
-		if (recipe.find((existing) => existing.summary === step.summary && existing.selector === step.selector)) return recipe;
-		return [...recipe, step].slice(-8);
+	/** Same run: append the step. New run: its first step replaces the old recipe. */
+	mergeRecipe(insight, step, runId) {
+		if (insight.recipeRunId !== runId) return {
+			actionRecipe: [step],
+			recipeRunId: runId
+		};
+		return {
+			actionRecipe: [...insight.actionRecipe, step].slice(-8),
+			recipeRunId: runId
+		};
 	}
 };
 // src/cli/app.ts
@@ -5266,7 +5407,8 @@ var AgenticBrowserCore = class {
 		return await this.api.executeCommand(input.sessionId, {
 			commandId,
 			type: input.type,
-			payload: input.payload
+			payload: input.payload,
+			intent: input.intent
 		});
 	}
 	async getPageContent(input) {
@@ -5343,4 +5485,4 @@ function createMockAgenticBrowserCore(env) {
 function createCliRuntime() {
 	return createAgenticBrowserCore();
 }
-export { isConnectionError as a, createMockAgenticBrowserCore as i, createAgenticBrowserCore as n, ensurePrivateDir as o, createCliRuntime as r, writePrivateFileSync as s, AgenticBrowserCore as t };
+export { StaleRefError as a, writePrivateFileSync as c, createMockAgenticBrowserCore as i, createAgenticBrowserCore as n, isConnectionError as o, createCliRuntime as r, ensurePrivateDir as s, AgenticBrowserCore as t };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "agentic-browser",
-  "version": "2.8.0",
+  "version": "2.8.1",
   "description": "CLI and MCP server for AI agents to control Chrome via CDP",
   "keywords": [
     "agent",