diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml
new file mode 100644
index 00000000..53ce5c3e
--- /dev/null
+++ b/.github/workflows/ci.yml
@@ -0,0 +1,34 @@
+name: CI
+
+on:
+  pull_request:
+  push:
+    branches:
+      - main
+      - master
+      - "cursor/**"
+
+jobs:
+  quality:
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v4
+
+      - name: Setup Node
+        uses: actions/setup-node@v4
+        with:
+          node-version: 20
+          cache: yarn
+
+      - name: Install dependencies
+        run: yarn install --frozen-lockfile
+
+      - name: Lint
+        run: yarn lint
+
+      - name: Build
+        run: yarn build
+
+      - name: Test
+        run: yarn test --runInBand
diff --git a/AGENTS.md b/AGENTS.md
index 1c981ec5..0dea3910 100644
--- a/AGENTS.md
+++ b/AGENTS.md
@@ -25,7 +25,7 @@
 - `yarn test` launches Jest; set `CI=true` for coverage and deterministic snapshots.
 - `yarn cli -c "..." [--debug --hyperbrowser --mcp <path>]` runs the agent; `--hyperbrowser` switches to the remote provider and `--debug` drops artifacts into `debug/`.
 - `yarn example <path>` (backed by `ts-node -r tsconfig-paths/register`) is the quickest way to execute flows in `examples/` or `scripts/`.
-- DOM metadata builds at runtime via the a11y provider; the legacy `build-dom-tree-script` entry points at a removed file—avoid relying on it until refreshed.
+- DOM metadata builds at runtime via the a11y provider; use runtime capture flows and `yarn example` probes rather than any removed legacy DOM-builder entrypoint.
 
 ## Agent Runtime & Integrations
 - The agent loop (`agent/tools/agent.ts`) captures the accessibility tree via `captureDOMState` (text-first, optional streaming and snapshot cache). Visual overlays/screenshots are opt-in (`enableVisualMode`) and composited with CDP screenshots for `page.ai`.
diff --git a/README.md b/README.md
index e1d0705a..ad1cf5d8 100644
--- a/README.md
+++ b/README.md
@@ -110,6 +110,56 @@ console.log(res);
 await agent.closeAgent();
 ```
 
+### Async Task Controls
+
+`executeTaskAsync()` returns a control handle you can pause/resume/cancel, plus a `result` promise you can await when you need the final output.
+
+```typescript
+const task = await agent.executeTaskAsync("Sign in and fetch account details");
+
+// Optional runtime control
+task.pause();
+task.resume();
+
+// Await final outcome at any time
+const final = await task.result;
+console.log(final.status, final.output);
+
+// Task failures reject with HyperagentTaskError (includes taskId + cause)
+task.result.catch((error) => {
+  console.error(error.taskId, error.cause?.message);
+});
+```
+
+### Migration Notes (Current Runtime Contract)
+
+- **`page.perform()` is the canonical single-action API.**
+  - `page.aiAction()` is still available as a compatibility alias.
+  - Calling `page.aiAction()` emits a one-time deprecation warning per agent instance.
+  - Prefer `perform` for all new code and docs.
+- **`executeTaskAsync()` now has a first-class completion promise.**
+  - Use `task.result` to await the final output deterministically.
+- **Top-level type exports are available from `@hyperbrowser/agent`.**
+  - You can import common task/cache/config types from the package root instead of internal paths.
+- **CDP remains configurable per agent.**
+  - If needed for a workflow, disable CDP with `cdpActions: false` to force Playwright fallback.
+- **Single-action debug artifacts use canonical perform naming.**
+  - `executeSingleAction` debug output is written under `debug/perform/...`.
+
+### Importing Public Types
+
+Core workflow types are available directly from the package entrypoint:
+
+```typescript
+import type {
+  ActionCacheOutput,
+  AgentTaskOutput,
+  HyperAgentConfig,
+  PerformTaskParams,
+  TaskOutput,
+} from "@hyperbrowser/agent";
+```
+
 ## Two Modes of Operation
 
 HyperAgent provides two complementary APIs optimized for different use cases:
@@ -135,8 +185,26 @@ await page.goto("https://example.com/login");
 await page.perform("fill email with user@example.com");
 await page.perform("fill password with mypassword");
 await page.perform("click the login button");
+
+// Optional retries tuning for single-action mode
+await page.perform("click the login button", {
+  maxElementRetries: 5,
+  retryDelayMs: 250,
+  maxContextSwitchRetries: 4,
+  contextSwitchRetryDelayMs: 500,
+});
 ```
 
+**Perform retry options**:
+- `maxElementRetries`: attempts to refetch/find a target element before failing.
+- `retryDelayMs`: delay between element-refetch retries.
+- `maxContextSwitchRetries`: retries when a tab/context switch interrupts an in-flight action.
+- `contextSwitchRetryDelayMs`: delay between context-switch retries (defaults to 500ms, capped for safety).
+- `cdpActions`: override CDP usage for this call (`true` by default from agent config).
+- `filterAdTrackingFrames`: override iframe filtering for this action (`true` by default). Set to `false` when you intentionally need ad/tracking iframes in scope.
+- `maxSteps` (**deprecated**): compatibility alias for `maxElementRetries`.
+  - Using `maxSteps` emits a one-time deprecation warning per agent instance.
+
 ### 🧠 `page.ai()` - Complex Multi-Step Tasks
 
 **Best for**: Complex workflows requiring multiple steps and visual context
@@ -152,6 +220,8 @@ await page.perform("click the login button");
 
 - `useDomCache` (boolean): Reuse DOM snapshots for speed
 - `enableVisualMode` (boolean): Enable screenshots and overlays (default: false)
+- `cdpActions` (boolean): override CDP usage for this task (inherits agent-level default when omitted)
+- `filterAdTrackingFrames` (boolean): override ad/tracking iframe filtering for this task (inherits agent-level default when omitted)
 
 **Example**:
 
@@ -301,6 +371,12 @@ const agent = new HyperAgent({
 });
 ```
 
+`llm` must be either:
+- a provider config object (`{ provider, model, ... }`), or
+- an object implementing the HyperAgent LLM client interface (`invoke`, `invokeStructured`, `getProviderId`, `getModelId`, `getCapabilities`).
+
+Invalid/malformed `llm` payloads fail fast with a configuration error.
+
 ### MCP Support
 
 HyperAgent functions as a fully functional MCP client. For best results, we recommend using
@@ -339,6 +415,17 @@ console.log(response);
 await agent.closeAgent();
 ```
 
+You can dynamically disconnect MCP servers later:
+
+```typescript
+// Fire-and-forget disconnect
+agent.disconnectFromMCPServer("server-id");
+
+// Awaited disconnect with success/failure result
+const didDisconnect = await agent.disconnectFromMCPServerAsync("server-id");
+console.log({ didDisconnect });
+```
+
 ### Custom Actions
 
 HyperAgent's capabilities can be extended with custom actions. Custom actions require 3 things:
@@ -448,6 +535,8 @@ const page = await agent.newPage();
 const replay = await page.runFromActionCache(cache, {
   maxXPathRetries: 3,  // Retry XPath resolution up to 3 times before LLM fallback
   debug: true,
+  cdpActions: true, // Optional: override CDP usage for this replay
+  filterAdTrackingFrames: false, // Optional: include ad/tracking iframes during replay resolution
 });
 
 console.log(replay);
@@ -494,7 +583,11 @@ HyperAgent integrates seamlessly with Playwright, so you can still use familiar
 - **Deep Iframe Support**: Tracking across nested and cross-origin iframes (OOPIFs)
 - **Exact Coordinates**: Actions use precise CDP coordinates for reliability
 
+Frame filtering normalizes protocol-relative and scheme-less iframe URLs for host-based matching, while intentionally avoiding host-based ad matches for path-only URLs.
+
 Keep in mind that CDP is still experimental, and stability is not guaranteed. If you'd like the agent to use Playwright's native locators/actions instead, set `cdpActions: false` when you create the agent and it will fall back automatically.
+If you need to inspect ad/tracking iframes for a specific workflow, keep CDP enabled and set `filterAdTrackingFrames: false` in `new HyperAgent({ ... })`.
+You can also override this per invocation using `page.ai(..., { filterAdTrackingFrames: false })` or `page.perform(..., { filterAdTrackingFrames: false })`.
 
 The CDP layer is still evolving—expect rapid polish (and the occasional sharp edge). If you hit something quirky you can toggle CDP off for that workflow and drop us a bug report.
 
diff --git a/currentState.md b/currentState.md
index 09fb7991..a8439bb3 100644
--- a/currentState.md
+++ b/currentState.md
@@ -1,499 +1,251 @@
-# HyperAgent Current State Analysis
-
-## Overview
-HyperAgent is a browser automation SDK that uses LLM-powered agents to execute tasks on web pages. It provides both imperative page methods (`page.ai()`, `page.extract()`) and a programmatic task execution API.
-
----
-
-## Core Architecture
-
-### 1. Entry Points & Public API
-
-#### **HyperAgent Class** ([src/agent/index.ts](src/agent/index.ts))
-
-The main class that orchestrates everything:
-
-```typescript
-class HyperAgent<T extends BrowserProviders = "Local"> {
-  // Core methods
-  async executeTask(task: string, params?: TaskParams, initPage?: Page): Promise<TaskOutput>
-  async executeTaskAsync(task: string, params?: TaskParams, initPage?: Page): Promise<Task>
-
-  // Page management
-  async getCurrentPage(): Promise<Page>
-  async newPage(): Promise<HyperPage>
-  async getPages(): Promise<HyperPage[]>
-
-  // Browser lifecycle
-  async initBrowser(): Promise<Browser>
-  async closeAgent(): Promise<void>
-}
-```
-
-#### **HyperPage Interface** ([src/agent/index.ts:567-605](src/agent/index.ts#L567-L605))
-
-Enhanced Playwright `Page` with AI methods:
-
-```typescript
-interface HyperPage extends Page {
-  // Execute a task on this page
-  ai(task: string, params?: TaskParams): Promise<TaskOutput>
-
-  // Execute task asynchronously (non-blocking)
-  aiAsync(task: string, params?: TaskParams): Promise<Task>
-
-  // Extract structured data
-  extract<T>(
-    task?: string,
-    outputSchema?: z.AnyZodObject,
-    params?: TaskParams
-  ): Promise<T | string>
-}
-```
-
-**Key Implementation Details:**
-- `page.ai()` → calls `agent.executeTask(task, params, page)` ([line 569-570](src/agent/index.ts#L569-L570))
-- `page.extract()` → wraps `executeTask()` with extraction-specific prompts ([lines 573-603](src/agent/index.ts#L573-L603))
-  - Adds `maxSteps: 2` by default for extractions
-  - Prepends extraction instructions to the task
-  - Parses JSON output if outputSchema provided
-
----
-
-## 2. Task Execution Flow
-
-### **Main Task Loop** ([src/agent/tools/agent.ts:105-306](src/agent/tools/agent.ts#L105-L306))
-
-```
-runAgentTask()
-  ├── 1. Get DOM State (getDom)
-  │   ├── Inject JavaScript into page
-  │   ├── Find interactive elements
-  │   ├── Draw numbered overlay (canvas)
-  │   └── Capture screenshot with overlay
-  │
-  ├── 2. Build Agent Messages (buildAgentStepMessages)
-  │   ├── System prompt
-  │   ├── Task description
-  │   ├── Previous steps context
-  │   ├── DOM representation (text)
-  │   └── Screenshot (base64 image)
-  │
-  ├── 3. Invoke LLM (llm.invokeStructured)
-  │   ├── Request structured output (Zod schema)
-  │   └── Get list of actions to execute
-  │
-  ├── 4. Execute Actions (runAction)
-  │   ├── For each action in list
-  │   ├── Run action handler
-  │   └── Wait 2 seconds between actions
-  │
-  └── 5. Repeat until complete/cancelled/maxSteps
-```
-
-**Location:** [src/agent/tools/agent.ts:132-291](src/agent/tools/agent.ts#L132-L291)
-
----
-
-## 3. DOM State Extraction
-
-### **Current Implementation: Visual DOM with Canvas Overlay**
-
-#### **Entry Point:** `getDom(page)` ([src/context-providers/dom/index.ts:5-18](src/context-providers/dom/index.ts#L5-L18))
-
-```typescript
-export const getDom = async (page: Page): Promise<DOMState | null> => {
-  const result = await page.evaluate(buildDomViewJs) as DOMStateRaw;
-  return {
-    elements: Map<number, InteractiveElement>,
-    domState: string,  // Text representation
-    screenshot: string // Base64 PNG with overlays
-  };
-};
-```
-
-#### **Build DOM View** ([src/context-providers/dom/build-dom-view.ts:54-130](src/context-providers/dom/build-dom-view.ts#L54-L130))
-
-**Process:**
-1. **Find Interactive Elements** ([find-interactive-elements.ts:4-63](src/context-providers/dom/find-interactive-elements.ts#L4-L63))
-   - Traverse entire DOM including Shadow DOM and iframes
-   - Check each element with `isInteractiveElem(element)`
-   - Returns `InteractiveElement[]` with metadata
-
-2. **Render Highlights Offscreen** ([highlight.ts:105-222](src/context-providers/dom/highlight.ts#L105-L222))
-   - Create `OffscreenCanvas` with viewport dimensions
-   - Draw colored rectangles around each interactive element
-   - Draw numbered labels (1, 2, 3...) on each element
-   - Return `ImageBitmap`
-
-3. **Composite Screenshot** ([agent.ts:33-42](src/agent/tools/agent.ts#L33-L42))
-   ```typescript
-   const compositeScreenshot = async (page: Page, overlay: string) => {
-     const screenshot = await page.screenshot({ type: "png" });
-     // Overlay numbered boxes onto base screenshot using Jimp
-     baseImage.composite(overlayImage, 0, 0);
-     return buffer.toString("base64");
-   };
-   ```
-
-4. **Build Text Representation** ([build-dom-view.ts:78-123](src/context-providers/dom/build-dom-view.ts#L78-L123))
-   ```
-   [1]<button id="submit" class="btn-primary">Submit Form</button>
-   [2]<input type="text" name="email" placeholder="Enter email">
-   Some text between elements
-   [3]<a href="/pricing">View Pricing</a>
-   ```
-
-**Output Structure:**
-```typescript
-interface DOMState {
-  elements: Map<number, InteractiveElement>  // index → element mapping
-  domState: string                          // [idx]<tag>text</tag> format
-  screenshot: string                        // base64 PNG with overlays
-}
-```
-
----
-
-## 4. Action System
-
-### **Available Actions** ([src/agent/actions/](src/agent/actions/))
-
-| Action | Purpose | Key Parameters | Location |
-|--------|---------|----------------|----------|
-| `clickElement` | Click an element | `index: number` | [click-element.ts](src/agent/actions/click-element.ts) |
-| `inputText` | Fill input field | `index: number, text: string` | [input-text.ts](src/agent/actions/input-text.ts) |
-| `extract` | Extract data | `objective: string` | [extract.ts](src/agent/actions/extract.ts) |
-| `goToUrl` | Navigate to URL | `url: string` | [go-to-url.ts](src/agent/actions/go-to-url.ts) |
-| `selectOption` | Select dropdown | `index: number, option: string` | [select-option.ts](src/agent/actions/select-option.ts) |
-| `scroll` | Scroll page | `direction: "up"\|"down"` | [scroll.ts](src/agent/actions/scroll.ts) |
-| `keyPress` | Press keyboard key | `key: string` | [key-press.ts](src/agent/actions/key-press.ts) |
-| `complete` | End task | `output?: string` | [complete.ts](src/agent/actions/complete.ts) |
-
-### **Action Execution** ([src/agent/tools/agent.ts:71-103](src/agent/tools/agent.ts#L71-L103))
-
-#### **Click Element Example** ([click-element.ts:18-57](src/agent/actions/click-element.ts#L18-L57))
-
-```typescript
-run: async function (ctx: ActionContext, action: ClickElementActionType) {
-  const { index } = action;
-  const locator = getLocator(ctx, index);  // Get element by index
-
-  await locator.scrollIntoViewIfNeeded({ timeout: 2500 });
-  await locator.waitFor({ state: "visible", timeout: 2500 });
-  await waitForElementToBeEnabled(locator, 2500);
-  await waitForElementToBeStable(locator, 2500);
-
-  await locator.click({ force: true });
-  return { success: true, message: `Clicked element with index ${index}` };
-}
-```
-
-**Element Selection:** ([actions/utils.ts](src/agent/actions/utils.ts))
-```typescript
-export const getLocator = (ctx: ActionContext, index: number): Locator | null => {
-  const element = ctx.domState.elements.get(index);
-  if (!element) return null;
-  return ctx.page.locator(element.cssPath);  // Use CSS path selector
-};
-```
-
----
-
-## 5. Key Workflows
-
-### **Workflow 1: `page.ai("click the login button")`**
-
-1. User calls `page.ai("click the login button")`
-2. → `agent.executeTask(task, params, page)` ([index.ts:569](src/agent/index.ts#L569))
-3. → `runAgentTask()` starts task loop ([agent.ts:105](src/agent/tools/agent.ts#L105))
-4. → `getDom(page)` extracts DOM + screenshot ([agent.ts:155](src/agent/tools/agent.ts#L155))
-   - Injects JS to find interactive elements
-   - Draws numbered overlays
-   - Composites screenshot
-5. → `buildAgentStepMessages()` creates LLM prompt ([agent.ts:201](src/agent/tools/agent.ts#L201))
-6. → `llm.invokeStructured()` gets action plan ([agent.ts:220](src/agent/tools/agent.ts#L220))
-7. → Execute actions ([agent.ts:253-275](src/agent/tools/agent.ts#L253-L275))
-   - LLM returns: `{ type: "clickElement", params: { index: 5 } }`
-   - `runAction()` calls `ClickElementActionDefinition.run()`
-   - Gets locator for element 5
-   - Clicks element via Playwright
-8. → Repeat loop or mark complete
-
-### **Workflow 2: `page.extract("product prices", schema)`**
-
-1. User calls `page.extract("product prices", PriceSchema)`
-2. → Wraps task: "You have to perform an extraction on the current page..." ([index.ts:586-590](src/agent/index.ts#L586-L590))
-3. → Sets `maxSteps: 2` (extractions are quick) ([index.ts:581](src/agent/index.ts#L581))
-4. → Adds `outputSchema` to actions ([index.ts:584](src/agent/index.ts#L584))
-5. → `executeTask()` runs normal agent loop
-6. → LLM returns structured output matching schema
-7. → Parse JSON and return typed result ([index.ts:592](src/agent/index.ts#L592))
-
-### **Workflow 3: Extract Action (Internal)**
-
-The `extract` action is **different** from `page.extract()`:
-
-**Location:** [src/agent/actions/extract.ts](src/agent/actions/extract.ts)
-
-```typescript
-run: async (ctx: ActionContext, action: ExtractActionType) => {
-  // Get page HTML
-  const content = await ctx.page.content();
-  const markdown = await parseMarkdown(content);
-
-  // Take screenshot via CDP
-  const cdpSession = await ctx.page.context().newCDPSession(ctx.page);
-  const screenshot = await cdpSession.send("Page.captureScreenshot");
-
-  // Call LLM with markdown + screenshot
-  const response = await ctx.llm.invoke([{
-    role: "user",
-    content: [
-      { type: "text", text: `Extract: "${objective}"\n\n${markdown}` },
-      { type: "image", url: `data:image/png;base64,${screenshot.data}` }
-    ]
-  }]);
-
-  return { success: true, message: `Extracted: ${content}` };
-}
-```
-
-**This is an action the agent can choose** during task execution, not the page-level method.
-
----
-
-## 6. DOM State Representation
-
-### **Current Approach: Visual DOM + Numbered Overlay**
-
-**Strengths:**
-- ✅ Simple index-based selection (LLM just says "5")
-- ✅ Visual feedback in screenshots
-- ✅ Works well with vision models
-
-**Weaknesses:**
-- ❌ Screenshot required every step (slow)
-- ❌ Screenshot → LLM → token cost is high
-- ❌ Numbered overlay can occlude important UI
-- ❌ Full DOM traversal every step (no caching)
-- ❌ Large token counts (screenshot + DOM text)
-
-**Performance:**
-- ~8,000-15,000 tokens per step
-- ~1,500-3,000ms per action
-- No caching mechanism
-
----
-
-## 7. Element Discovery
-
-### **Interactive Element Detection** ([src/context-providers/dom/elem-interactive.ts](src/context-providers/dom/elem-interactive.ts))
-
-**Current Rules:**
-```typescript
-isInteractiveElem(element: HTMLElement): { isInteractive: boolean, reason?: string }
-```
-
-**Checks (in order):**
-1. Native interactive tags: `button`, `a[href]`, `input`, `select`, `textarea`
-2. ARIA roles: `button`, `link`, `tab`, `checkbox`, `menuitem`
-3. Event listeners: `data-has-interactive-listener="true"` (injected)
-4. Contenteditable elements
-5. Elements with `onclick` attribute
-6. Cursor style: `cursor: pointer`
-7. Custom detection for common patterns
-
-**Ignored Elements:**
-- Hidden elements (`display: none`, `visibility: hidden`)
-- Zero-dimension elements
-- Disabled elements
-- Script and style tags
-
----
-
-## 8. Message Building
-
-### **Prompt Construction** ([src/agent/messages/builder.ts](src/agent/messages/builder.ts))
-
-**Message Structure:**
-```typescript
-[
-  { role: "system", content: SYSTEM_PROMPT },
-  { role: "user", content: [
-    { type: "text", text: "Task: click login button\n\nDOMState:\n[1]<button>..." },
-    { type: "image", url: "data:image/png;base64,..." }
-  ]},
-  { role: "assistant", content: "..." },  // Previous step
-  { role: "user", content: "..." },       // Previous action results
-  // ... more history ...
-  { role: "user", content: [             // Current step
-    { type: "text", text: "Current DOM:\n..." },
-    { type: "image", url: "..." }
-  ]}
-]
-```
-
----
-
-## 9. Variable System
-
-### **Variable Management** ([src/agent/index.ts:174-202](src/agent/index.ts#L174-L202))
-
-```typescript
-interface HyperVariable {
-  key: string;
-  value: string;
-  description?: string;
-}
-
-// API
-agent.addVariable({ key: "email", value: "user@example.com" })
-agent.getVariable("email")
-agent.deleteVariable("email")
-```
-
-**Usage in Actions:**
-```typescript
-// In inputText action:
-text = text.replace(`<<${variable.key}>>`, variable.value);
-// Agent can use: inputText(5, "<<email>>") → "user@example.com"
-```
-
----
-
-## 10. Browser Provider Architecture
-
-### **Supported Providers:**
-
-1. **LocalBrowserProvider** (default)
-   - Uses `patchright` (Playwright fork with anti-detection)
-   - Runs locally
-
-2. **HyperbrowserProvider**
-   - Cloud-based browser service
-   - Remote CDP connection
-
-**Selection:** ([index.ts:85-94](src/agent/index.ts#L85-L94))
-```typescript
-new HyperAgent({
-  browserProvider: "Local" | "Hyperbrowser",
-  localConfig: { ... },
-  hyperbrowserConfig: { ... }
-})
-```
-
----
-
-## 11. MCP Integration
-
-### **Model Context Protocol Support** ([src/agent/mcp/](src/agent/mcp/))
-
-**Purpose:** Connect external tools as custom actions
-
-```typescript
-await agent.initializeMCPClient({
-  servers: [{
-    id: "filesystem",
-    command: "npx",
-    args: ["-y", "@modelcontextprotocol/server-filesystem"]
-  }]
-});
-```
-
-**How it works:**
-1. MCP server exposes tools
-2. Tools converted to `AgentActionDefinition`
-3. Registered with agent
-4. LLM can invoke MCP tools as actions
-
----
-
-## 12. Debug Mode
-
-### **Debug Output** ([src/agent/tools/agent.ts:112-148](src/agent/tools/agent.ts#L112-L148))
-
-When `debug: true`:
-
-```
-debug/
-  └── {taskId}/
-      ├── step-0/
-      │   ├── elems.txt              # DOM text representation
-      │   ├── screenshot.png         # Composite screenshot
-      │   ├── msgs.json              # LLM messages
-      │   └── stepOutput.json        # Action results
-      ├── step-1/
-      └── taskOutput.json            # Final output
-```
-
----
-
-## 13. Summary: Current vs Desired State
-
-### **What Works Well:**
-- ✅ Simple API (`page.ai()`, `page.extract()`)
-- ✅ Flexible action system
-- ✅ Multi-step task execution
-- ✅ MCP integration
-- ✅ Variable substitution
-
-### **Performance Bottlenecks:**
-- ❌ Screenshot required every step
-- ❌ No DOM caching
-- ❌ No action caching
-- ❌ High token usage (8K-15K per step)
-- ❌ Slow actions (1.5-3s each)
-
-### **Accuracy Issues:**
-- ❌ Numbered overlay can be occluded
-- ❌ Full DOM may miss semantic meaning
-- ❌ No accessibility tree
-- ❌ No self-healing on failure
-- ❌ Single-attempt actions (no retry logic)
-
----
-
-## 14. File Reference Map
-
-| Component | File Path | Key Lines |
-|-----------|-----------|-----------|
-| **Main Agent Class** | `src/agent/index.ts` | 37-606 |
-| **Task Execution Loop** | `src/agent/tools/agent.ts` | 105-306 |
-| **DOM Extraction** | `src/context-providers/dom/index.ts` | 5-18 |
-| **Build DOM View** | `src/context-providers/dom/build-dom-view.ts` | 54-130 |
-| **Find Elements** | `src/context-providers/dom/find-interactive-elements.ts` | 4-63 |
-| **Canvas Overlay** | `src/context-providers/dom/highlight.ts` | 105-222 |
-| **Click Action** | `src/agent/actions/click-element.ts` | 18-57 |
-| **Input Text Action** | `src/agent/actions/input-text.ts` | 16-37 |
-| **Extract Action** | `src/agent/actions/extract.ts` | 16-104 |
-| **System Prompt** | `src/agent/messages/system-prompt.ts` | - |
-| **Message Builder** | `src/agent/messages/builder.ts` | - |
-
----
-
-## Next Steps: Performance & Accuracy Improvements
-
-Based on Stagehand and Skyvern analysis, key opportunities:
-
-1. **Adopt Accessibility Tree** (Stagehand approach)
-   - 3-4x token reduction
-   - Better semantic understanding
-   - No screenshot required for actions
-
-2. **Implement Caching** (Stagehand approach)
-   - Action cache (instruction+URL → selector)
-   - LLM cache (prompt → response)
-   - 20-30x speed improvement for cached actions
-
-3. **Hybrid Visual Approach** (Skyvern approach)
-   - DOM injection for element IDs (no overlay)
-   - Bounding boxes only when needed
-   - Keep visual feedback but reduce occlusion
-
-4. **Self-Healing** (Stagehand approach)
-   - Re-observe on failure
-   - Multiple selector strategies
-   - Retry logic with different approaches
-
-See `improvement-plan.md` for detailed implementation strategy.
+# HyperAgent Current State (2026-02)
+
+This file summarizes the implementation as it exists today.
+
+## Product surface
+
+HyperAgent exposes a TypeScript SDK for browser automation with three primary page APIs:
+
+- `page.ai(task, params?)` → multi-step autonomous workflow loop
+- `page.perform(instruction, params?)` → single granular action (a11y-first)
+- `page.extract(task?, schema?, params?)` → extraction helper layered on top of the loop
+
+`page.aiAction()` remains as a deprecated alias to `page.perform()`.
+
+## Runtime architecture
+
+### Main orchestrator
+- `src/agent/index.ts` (`HyperAgent`)
+  - Browser/context lifecycle
+  - Task lifecycle (`executeTask`, `executeTaskAsync`)
+  - Page scoping and tab-following behavior
+  - Action registration and MCP integration
+  - Action-cache replay support
+
+### Agent loop
+- `src/agent/tools/agent.ts` (`runAgentTask`)
+  - Repeated cycle: DOM capture → message building → structured LLM action → action execution
+  - Supports debug artifacts, bounded retry behavior, and cache recording
+  - Includes stuck protection for repeated failures/waits and repeated successful no-progress actions
+  - `complete` action now determines final success/failure semantics deterministically
+
+### Single-action path
+- `executeSingleAction` in `src/agent/index.ts`
+  - Uses `findElementWithInstruction` (a11y analyze + retry)
+  - Executes through shared `performAction`
+  - Supports dedicated perform retry controls (`maxElementRetries`, `retryDelayMs`, `maxContextSwitchRetries`, `contextSwitchRetryDelayMs`)
+  - Emits a one-time deprecation warning when compatibility alias `page.aiAction()` is used
+  - Writes debug artifacts to `debug/perform/...` via canonical `writePerformDebug`
+
+## DOM context pipeline
+
+- Primary provider: `src/context-providers/a11y-dom/*`
+- Produces:
+  - Encoded element IDs (`frameIndex-backendNodeId`)
+  - `elements` map, `xpathMap`, `backendNodeMap`, `frameMap`
+  - Optional bounding boxes and visual overlay in visual mode
+- Includes short-lived snapshot caching with explicit invalidation (`dom-cache.ts`)
+
+## CDP integration model
+
+- CDP-first execution and resolution in `src/cdp/*`
+- Key modules:
+  - `playwright-adapter.ts` → CDP client/session abstraction
+  - `frame-context-manager.ts` / `frame-graph.ts` → frame/session/context tracking
+  - `element-resolver.ts` → encoded-id to executable CDP element resolution
+  - `interactions.ts` → click/type/fill/scroll/etc CDP action dispatch
+- Playwright fallback still exists where CDP is unavailable or disabled (`cdpActions: false`)
+
+## LLM layer
+
+- Provider adapters in `src/llm/providers/*`
+  - OpenAI, Anthropic, Gemini, DeepSeek
+- Unified interfaces in `src/llm/types.ts`
+- Structured output path is schema-driven (Zod-first)
+
+## Quality gates and testing
+
+### Automation
+- CI workflow: `.github/workflows/ci.yml`
+  - Runs lint, build, and test on push/PR
+
+### Local checks
+- `yarn lint`
+- `yarn build`
+- `yarn test`
+
+### Test harness
+- Jest + ts-jest configured via `jest.config.cjs`
+- Current regression/unit coverage includes:
+  - constructor/debug wiring and action registration behavior
+  - async task control result promise
+  - agent loop complete semantics
+  - perform variable interpolation path
+  - perform retry option propagation
+  - frame listener cleanup lifecycle
+  - prompt/message contract checks (open tabs, naming consistency, bounded history)
+
+## Notable recent hardening
+
+- Added async task handle `task.result` for `executeTaskAsync`.
+- Fixed debug options initialization ordering.
+- Made action registration fail-fast and synchronous.
+- Added dedicated perform option typing and handling.
+- Added configurable context-switch retry delay for `page.perform`.
+- Aligned prompt text with actual registered action names.
+- Fixed frame listener bookkeeping to avoid session listener overwrite drift.
+- Added compact omitted-history summaries in prompt building to preserve context while respecting prompt budgets.
+- Made repeated-success stuck detection progress-aware by incorporating bounded DOM-state signatures.
+- Reduced first-party frame false positives in ad/tracking filtering with same-site weak-signal safeguards.
+- Centralized page URL normalization into shared utility (`normalizePageUrl`) and reused it across agent loop, perform, and prompt-builder paths.
+- Hardened frame metadata normalization in `FrameContextManager` (sanitized/bounded frame URLs and names, trap-safe OOPIF metadata reads).
+- Hardened a11y frame resolution fallback logic to keep XPath traversal working when frame enumeration is trap-prone.
+- Hardened a11y context-provider diagnostics for build-map, scrollable-detection, and batch bounding-box collection failure paths (sanitized/truncated warnings and bounded identifiers).
+- Hardened CDP script-injector diagnostics for script registration/runtime evaluation failures with bounded key/context identifier formatting.
+- Hardened CDP element-resolver diagnostics by sanitizing/truncating encoded IDs and frame IDs in failure/warning paths.
+- Hardened `PerformanceTracker` warning paths in a11y DOM capture utilities and tightened metadata typing (`unknown` + safe readers) to reduce unsafe runtime assumptions.
+- Hardened CLI diagnostics in task-input/stdin/mcp-config flows with consistent control-character stripping and truncation in file-read/raw-mode/config-parse errors.
+- Hardened agent-side DOM streaming callback warnings (`dom-capture`) to avoid noisy unbounded callback failure logs.
+- Hardened retry helper warning diagnostics for callback/sleep failure paths, preventing control-character and oversized diagnostic leakage.
+- Hardened `examineDom` and HTML→Markdown utilities with bounded diagnostic formatting for LLM/tooling conversion failures.
+- Hardened perform-action failure formatting with explicit bounded diagnostics, including trap-prone DOM element lookup failures.
+- Hardened Anthropic provider structured-output warning diagnostics in schema validation fallback branches.
+- Hardened network-settle waiting (`waitForSettledDOM`) with safe listener attach/detach handling, timeout fallback when listener registration fails, and bounded stalled-request diagnostics.
+- Added bounded timeout normalization in `waitForSettledDOM` so invalid/non-finite/non-positive waits no longer resolve immediately and oversized values are capped.
+- Hardened replay-step diagnostics in `runFromActionCache` to strip control characters in cached-step/page getter failure messages.
+- Sanitized control characters in prompt-builder task/step/DOM payload serialization before truncation to keep LLM context inputs clean under malformed runtime values.
+- Tightened agent-loop action/output typing by normalizing parsed structured outputs into explicit `AgentOutput`/`ActionType` shapes before runtime dispatch and cache recording.
+- Removed direct `as any` casts in OpenAI/Anthropic/DeepSeek/Gemini provider request payload assembly in favor of SDK-derived parameter field typing.
+- Added `filterAdTrackingFrames` configuration in `HyperAgent` so CDP frame discovery can optionally include ad/tracking iframes for workflows that require them.
+- Propagated frame-filter policy through DOM-settle/replay/wait paths so `waitForSettledDOM` and special replay actions honor per-agent ad/tracking frame filtering settings.
+- Added per-invocation frame-filter overrides on `page.ai`, `page.perform`, and replay params so workflows can opt in/out of ad/tracking iframe filtering without constructing a new agent.
+- Added per-invocation `cdpActions` overrides on task/perform/replay params so workflows can force CDP on/off without rebuilding the agent.
+- Synced frame-filter policy into a11y DOM capture setup (`getA11yDOM`/`captureDOMState`) so first-attempt frame discovery uses the active task/action override instead of stale manager state.
+- Hardened per-call frame-filter option reads against trap-prone parameter objects in `executeTask`, `executeTaskAsync`, and `executeSingleAction` (falls back to agent default instead of throwing).
+- Hardened `waitForSettledDOM` frame-manager option setup so debug/filter configuration setter failures are isolated to sanitized warnings instead of aborting settle behavior.
+- Hardened `getA11yDOM` frame-manager configuration so trap-prone `setDebug` / `setFrameFilteringEnabled` calls degrade to sanitized warnings instead of failing DOM extraction setup.
+- Hardened shared runtime-context initialization so trap-prone frame-manager config setters (`setDebug`, `setFrameFilteringEnabled`) no longer abort action/task setup.
+- Hardened element-locator debug logging payloads to avoid trap-prone second lookups and unbounded object dumps when frame resolution fails.
+- Aligned examine-dom action instruction prompt with the actual supported method set (removed guidance implying arbitrary Playwright methods are valid).
+- Replay cached-step execution now honors `cdpActions: false` by skipping CDP XPath resolution/runtime initialization and using Playwright-path action execution for that attempt.
+- Normalized CLI shutdown failure logging in `cli/index.ts` to use `formatCliError`, avoiding raw unsanitized shutdown diagnostics.
+- Normalized CLI per-step failure rendering in `cli/index.ts` so action error messages are sanitized/truncated via `formatCliError` before display.
+- Added Anthropic structured-output regression coverage confirming multi-action calls enforce deterministic `tool_choice: { type: "any", disable_parallel_tool_use: true }`.
+- Hardened CDP frame-filter host/path matching to avoid query-text false positives (e.g. unrelated URLs containing `https://yahoo.com/pixel` in query params) while preserving legitimate host-suffix + path rule matching.
+- Hardened prompt token budgeting for variables by capping serialized variable entries per step-message build and emitting omitted-count context instead of unbounded variable dumps.
+- Expanded trap-safe per-call override regression coverage for sync task execution and replay params to ensure `cdpActions` / `filterAdTrackingFrames` reliably fall back to agent defaults when option getters throw.
+- Hardened prompt-step history materialization with trap-safe step-array reads so malformed/trap-prone `steps` payloads degrade gracefully instead of crashing message assembly.
+- Hardened constructor config reads for `cdpActions` and `filterAdTrackingFrames` using trap-safe field access/fallback defaults, preventing initialization crashes from trap-prone config objects.
+- Expanded cached-action helper regression coverage to validate trap-safe option access (`cdpActions`, `filterAdTrackingFrames`, `maxSteps`) with deterministic fallback to agent/default settings.
+- Hardened constructor-wide config ingestion (LLM/provider/debug/options/custom-actions/local/hyper configs) with trap-safe reads and sane defaults so malformed/trap-prone config objects no longer crash initialization.
+- Hardened open-tab prompt materialization with trap-safe tab-array reads so unreadable tab entries are skipped and summarized instead of collapsing to unavailable output.
+- Added an additional open-tab fallback path: when the tab array becomes unreadable (e.g. trapped `length`), prompt assembly now still emits the current tab line instead of a blank/no-tabs summary.
+- Added constructor regression coverage for trap-prone `llm` config getters, ensuring fallback failure paths stay deterministic and readable.
+- Hardened CDP frame-filter URL normalization to support protocol-relative and scheme-less frame URLs while avoiding path-only false positives in host-based ad-domain detection.
+- Refined CDP frame-filter URL normalization to correctly handle scheme-less `host:port` URLs (without misclassifying them as custom schemes), preserving ad-domain detection coverage in those cases.
+- Tightened frame-filter query-signal policy so tracking query parameters are treated as strong signals only for parseable URL contexts, preventing path-only query strings from being over-filtered.
+- Hardened global debug-option storage by normalizing option payloads to plain boolean fields at set-time, preventing trap-prone debug option getters from leaking into runtime reads.
+- Hardened page-URL normalization option reads (fallback/maxChars) against trap-prone option objects, ensuring deterministic URL fallback/truncation behavior under malformed option payloads.
+- Hardened `waitForSettledDOM` option reads for frame filtering with trap-safe accessors, so malformed/trap-prone option objects no longer break settle flow or frame-manager configuration.
+- Hardened wait-listener lifecycle cleanup against trap-prone session listener-method getters, preserving settle completion while emitting sanitized detach diagnostics.
+- Expanded settle-flow listener regressions to cover trap-prone `session.on` getters, ensuring timeout-based fallback remains deterministic under unreadable listener APIs.
+- Aligned settle network-tracing behavior so recording-video sessions now propagate trace mode into network-idle diagnostics (including stalled-request warnings) even when debug flags are off.
+- Expanded settle trace regressions with cleaner log-capture coverage to ensure recording-video trace diagnostics remain validated without noisy test output.
+- Hardened settle debug-option lookup against trap-prone `getDebugOptions()` reads, with deterministic fallback trace defaults and sanitized warning diagnostics.
+- Refined settle context probing to avoid noisy warnings when `page.context` is unavailable while still surfacing sanitized diagnostics for trap-prone context method/getter failures.
+- Hardened Playwright CDP session initialization flow:
+  - `createSession` now guards context acquisition, `newCDPSession` method reads, and session creation with bounded/sanitized diagnostics.
+  - `getCDPClientForPage` now always clears pending init promises (including failed init paths) and tolerates trap-prone `page.once` close-listener attachment with sanitized warnings.
+- Removed stale inline TODO/commented dead code in markdown conversion utility to keep cleanup pass consistent.
+- Replaced remaining TODO-style OOPIF note in a11y DOM extraction with an accurate non-actionable implementation constraint note; `src/` now has no lingering TODO/FIXME/HACK markers.
+- Hardened prompt open-tab summary fallback behavior: when context/tab enumeration is unavailable or trap-prone, prompts now fall back to the current tab line rather than opaque "Open tabs unavailable" text.
+- Hardened OOPIF discovery context reads in `FrameContextManager.captureOOPIFs()`:
+  - guard trap-prone `page.context`, `context.newCDPSession`, `page.frames`, and `page.mainFrame` reads,
+  - short-circuit gracefully when required APIs are unavailable,
+  - emit sanitized diagnostics in debug logs for getter/method trap failures.
+- Refreshed stale CDP deep-dive flow notes that previously described OOPIF capture as incomplete; docs now reflect the current runtime OOPIF discovery + map-sync + multi-frame accessibility capture flow.
+- Hardened HyperPage scope/context handling in `agent/index.ts`:
+  - setup now uses trap-safe context/pages materialization when resolving active pages,
+  - context page-listener attach/detach paths now use guarded method reads instead of direct calls,
+  - preserves child-tab tracking even when context page listing getters are trap-prone.
+- Hardened element-locator debug frame listing:
+  - trap-prone frame arrays no longer collapse the entire debug "Available frames" payload,
+  - readable frame entries are preserved even when individual frame getters/indexes trap.
+- Bound CDP session creation to context receivers in both discovery paths:
+  - `PlaywrightCDPClient.createSession()` now calls `newCDPSession` with the browser context receiver explicitly.
+  - `FrameContextManager.captureOOPIFs()` now calls `newCDPSession` with the discovered context receiver explicitly.
+  - Added regressions proving receiver-sensitive `newCDPSession` implementations continue to work.
+- Hardened frame-context listener lifecycle against trap-prone session listener methods:
+  - added guarded session listener attach/detach helpers in `frame-context-manager.ts` with sanitized diagnostics,
+  - `ensureInitialized`, OOPIF detach wiring, `removeFrame`, and `clear` now tolerate `session.on`/`session.off` getter traps without crashing.
+- Fixed frame-metadata receiver handling in element locator diagnostics:
+  - `safeReadFrameText` now invokes frame `url`/`name` methods with the frame object receiver,
+  - debug payloads now preserve receiver-sensitive frame metadata values instead of falling back to placeholders.
+- Hardened pooled CDP listener wiring in Playwright adapter:
+  - pooled-session detach listener attach/detach now uses guarded method resolution with sanitized diagnostics,
+  - adapter disposal now guards pooled cleanup callbacks so listener-cleanup traps cannot abort disposal.
+- Tightened FrameContextManager listener bookkeeping:
+  - session listeners are now recorded only when registration succeeds,
+  - avoids stale listener bookkeeping entries when `session.on` registration traps/fails, reducing noisy/double cleanup warnings.
+- Hardened a11y frame URL matching iteration:
+  - `resolveFrameByXPath` now uses trap-safe frame-array materialization for `page.frames()` URL matching,
+  - preserves URL matching on readable frame entries even when some frame-array indexes trap.
+- Hardened task-scoped context page-listener wiring in `HyperAgent`:
+  - task listener attach/detach now resolves `context.on/off` methods safely before invocation,
+  - `executeTask`/`executeTaskAsync` now tolerate trap-prone `context.on`/`context.off` getter access without aborting task execution.
+  - debug mode now emits explicit unavailable-method diagnostics when task listener attach/detach methods cannot be resolved.
+- Clarified CDP deep-dive OOPIF notes to distinguish main-frame limitations from full runtime behavior (main-frame traversal alone cannot see OOPIF content; dedicated OOPIF session pass supplies it).
+- Hardened a11y runtime-context collection listener wiring:
+  - `collectExecutionContexts()` now guards `session.on`/`session.off` method reads and listener attach/detach calls,
+  - context collection now tolerates trap-prone runtime listener method getters while preserving sanitized diagnostics in debug mode.
+  - `collectExecutionContexts()` now also guards trap-prone `session.send` reads for `Runtime.enable`, preventing getter traps from aborting the context collection path.
+- Hardened frame-sync debug handling in a11y context provider:
+  - `syncFrameContextManager()` now guards trap-prone frame-manager `setDebug` calls, preserving sync flow with sanitized debug warnings.
+- Hardened cache-hydration debug handling in a11y context provider:
+  - `hydrateFrameContextFromSnapshot()` now guards trap-prone frame-manager `setDebug` calls so cache hydration continues instead of aborting early.
+- Hardened frame-graph debug artifact capture in agent loop:
+  - `writeFrameGraphSnapshot()` now guards trap-prone frame-manager `setDebug` calls and still proceeds with frame graph serialization.
+  - Added regression coverage to ensure debug-setter traps do not downgrade into "Failed to write frame graph" failures.
+- Hardened task error-forwarder listener registration:
+  - `HyperAgent` now resolves `errorEmitter.on`/`off` methods through trap-safe, receiver-bound helpers before invoking task-scoped forwarding hooks.
+  - Added regression coverage proving async task execution still succeeds (with sanitized warnings) when `errorEmitter.on` getter traps.
+- Hardened task error-forwarder listener detach fallback:
+  - `HyperAgent` now falls back to `errorEmitter.removeListener` when `errorEmitter.off` is unavailable/trap-prone during task-forwarder cleanup.
+  - Added regression coverage proving settled task cleanup still detaches listeners when `off` getter traps.
+- Hardened task error-forwarder listener attach fallback:
+  - `HyperAgent` now falls back to `errorEmitter.addListener` when `errorEmitter.on` is unavailable/trap-prone during task-forwarder registration.
+  - Added regression coverage proving in-flight listener wiring still succeeds when `on` getter traps, plus retained warning-path coverage when both `on` and `addListener` getters trap.
+- Hardened Playwright CDP session detach method access:
+  - `PlaywrightSessionAdapter.detach()` now performs trap-safe, receiver-bound `session.detach` method reads/invocation and emits deterministic diagnostics when unavailable.
+  - Added regressions for `session.detach` getter traps and unavailable detach methods during client disposal.
+- Refreshed remaining staged-flow wording in the CDP deep dive around OOPIF discovery to describe current execution-context sync progression without stale "Need Phase 4" phrasing.
+- Hardened CDP command dispatch in Playwright session adapter:
+  - `PlaywrightSessionAdapter.send()` now guards trap-prone `session.send` method reads and wraps sync send failures with sanitized/diagnostic context.
+- Hardened Playwright session listener wrappers:
+  - `PlaywrightSessionAdapter.on()` and `.off()` now guard trap-prone listener method reads and wrap listener registration/removal failures with sanitized diagnostics.
+  - Added adapter regressions for trap-prone `session.on`/`session.off` getter diagnostics to lock the listener-wrapper hardening behavior.
+  - Added adapter regressions for thrown listener method calls (`on`/`off`) to lock sanitized diagnostics for registration/removal failures beyond getter traps.
+- Added initBrowser regression coverage for trap-prone browser-context listener getters:
+  - debug mode now asserts deterministic "context.on is unavailable" diagnostics when context listener methods cannot be read during browser initialization.
+- Hardened context page materialization in `HyperAgent`:
+  - introduced shared context-page readers (`getContextPagesOrThrow` / `getContextPagesSafe`) using trap-safe array materialization,
+  - `getPages()` now preserves readable page entries even when some context page-array indexes trap,
+  - `getCurrentPage()` polling now reuses the same trap-safe context page read path.
+  - context page-method getter traps now surface explicit lifecycle diagnostics in `getPages()` failures (`failed to read context.pages: ...`) instead of generic unavailable-method fallbacks.
+- Hardened context.newPage creation path in `HyperAgent`:
+  - introduced `createContextPageOrThrow()` for trap-safe `context.newPage` method reads and invocation,
+  - `newPage()` and `getCurrentPage()` now share deterministic diagnostics for unavailable/trap-prone `context.newPage` access.
+  - added explicit regression coverage for `getCurrentPage()` when `context.newPage` getter traps or is unavailable.
+- Hardened A11y DOM option ingestion (`useCache`, `onFrameChunk`, `filterAdTrackingFrames`) with trap-safe reads, so malformed option objects no longer break extraction setup.
+- Hardened A11y DOM debug-option lookup (`getDebugOptions`) with trap-safe fallback defaults and sanitized warning diagnostics.
+- Hardened OpenAI/Anthropic structured-schema debug-option reads so trap-prone debug-option access no longer interrupts structured invocation paths.
+- Hardened CDP Playwright adapter debug-option reads (`sessionLogging`) so trap-prone debug-option lookups degrade to sanitized warnings and safe non-logging defaults.
+- Performed focused code-cleanup pass by replacing stale phase-specific TODO wording in constructor provider-selection comments with current-state guidance.
+- Hardened constructor LLM validation to reject malformed non-provider/non-client `llm` payloads instead of accepting invalid runtime objects, while preserving trap-safe config reads.
+- Added explicit constructor regression coverage for malformed partial `llm` objects to lock in fail-fast configuration behavior.
+- Hardened prompt final-goal rendering against malformed/trap-prone task inputs by normalizing non-string goals into bounded readable diagnostics instead of throwing.
+- Hardened prompt base-message materialization with trap-safe array reads so malformed/trap-prone seed message arrays no longer crash message assembly and readable entries are preserved.
+- Hardened constructor custom-action ingestion with trap-safe array reads so unreadable custom-action entries are skipped while valid entries continue to register.
+- Expanded top-level package exports for key workflow/config types at `@hyperbrowser/agent`.
+- Removed stale script entry (`build-dom-tree-script`) and improved README usage docs.
+- Added canonical single-action debug writer helper (`writePerformDebug`) while preserving deprecated alias compatibility.
diff --git a/docs/cdp-overview.md b/docs/cdp-overview.md
index cb27a434..9e81aa38 100644
--- a/docs/cdp-overview.md
+++ b/docs/cdp-overview.md
@@ -5,13 +5,64 @@ This document explains every relevant function added or changed since commit `f3
 1. Frame/session infrastructure and why it exists.
 2. How the accessibility DOM (A11yDOM) pipeline gathers full-frame data.
 3. How bounding boxes/visual overlays work without Playwright.
-4. How `page.aiAction()` (`executeAction`/`runAgentTask`) and `page.ai()` (`executeSingleAction`) flow through CDP.
+4. How `page.perform()` (`executeSingleAction`) and `page.ai()` (`runAgentTask`) flow through CDP.
 5. What each CDP runtime action does under the hood.
 6. **THE BIG PICTURE: Why we have so many maps and events**
 7. Areas that still need abstraction or cleanup.
 
 ---
 
+## Runtime Frame-Filtering Policy (Current Behavior)
+
+By default, HyperAgent filters likely ad/tracking iframes during CDP frame discovery to reduce noise in the frame graph. This is now configurable per agent:
+
+```ts
+const agent = new HyperAgent({
+  // default is true
+  filterAdTrackingFrames: false,
+});
+```
+
+- `true` (default): skip likely ad/tracking frames during OOPIF/session discovery.
+- `false`: include those frames, which is useful for workflows that intentionally interact with ad-tech, analytics tags, or embedded consent/tracking widgets.
+
+Override scopes:
+- agent-level default via `new HyperAgent({ filterAdTrackingFrames: ... })`,
+- per-task override via `page.ai(task, { filterAdTrackingFrames: ... })`,
+- per-single-action override via `page.perform(instruction, { filterAdTrackingFrames: ... })`,
+- replay override via `runFromActionCache(..., { filterAdTrackingFrames: ... })`.
+
+The same setting is propagated through:
+- task loop runtime context initialization (`page.ai()` flow),
+- single-action execution (`page.perform()` flow),
+- cached replay + special replay actions,
+- DOM settle/wait paths (`waitForSettledDOM`).
+
+Frame-filter URL matching behavior notes:
+- protocol-relative (`//host/path`) and scheme-less host URLs (`host/path`, `host:port/path`) are normalized for host-based matching.
+- path-only inputs (for example `/widget?prebid=1`) are intentionally not treated as host-based ad-domain matches.
+- weak same-site signals are tolerated, while strong tracking/ad signals still filter aggressively.
+
+## Runtime CDP Toggle Policy (Current Behavior)
+
+CDP execution is enabled by default and configurable at both agent and per-call scope.
+
+```ts
+const agent = new HyperAgent({
+  cdpActions: true, // default
+});
+```
+
+Override scopes:
+- agent-level default via `new HyperAgent({ cdpActions: ... })`,
+- per-task override via `page.ai(task, { cdpActions: ... })`,
+- per-single-action override via `page.perform(instruction, { cdpActions: ... })`,
+- replay override via `runFromActionCache(..., { cdpActions: ... })`.
+
+When disabled for a given run, execution paths skip CDP-specific action dispatch and rely on Playwright fallback behavior for that invocation.
+
+---
+
 ## 0. THE BIG PICTURE: The Map Problem & Why We Need Multiple Event Listeners
 
 ### Why So Many Maps?
@@ -233,7 +284,7 @@ Map {
 
 ### The Data Flow: From LLM Instruction to CDP Command
 
-Here's the complete flow when the agent executes `page.aiAction("click the button in the iframe")`:
+Here's the complete flow when the agent executes `page.perform("click the button in the iframe")`:
 
 ```
 1. [LLM Input] "click the button in the iframe"
@@ -1014,11 +1065,13 @@ frameMap.set(1, {
 
 ---
 
-## 0.7. Entry Points: `page.ai()` vs `page.aiAction()`
+## 0.7. Entry Points: `page.ai()` vs `page.perform()` (with `page.aiAction()` alias)
+
+> `page.aiAction()` remains available as a deprecated alias to `page.perform()`. This section uses `page.perform()` as the canonical single-action API name.
 
 ### Quick Reference Table
 
-| Feature | `page.ai(task)` | `page.aiAction(instruction)` |
+| Feature | `page.ai(task)` | `page.perform(instruction)` |
 |---------|-----------------|------------------------------|
 | **Use Case** | Multi-step complex workflows | Single granular action |
 | **Mode** | Visual (screenshot + overlay) | A11y tree (text-based) |
@@ -1057,16 +1110,16 @@ Loop until complete or maxSteps:
   7. Check if task complete
 ```
 
-### Code Flow: `page.aiAction()`
+### Code Flow: `page.perform()`
 
 ```typescript
-page.aiAction("click the login button")
+page.perform("click the login button")
   ↓
 HyperAgent.executeSingleAction(instruction, page, params)
   ↓
 findElementWithRetry(instruction, page, llm, options)
   ↓
-Loop up to 10 retries:
+Loop up to maxElementRetries (default 10, capped):
   1. getA11yDOM(page, { mode: "a11y" })
      - Builds all maps (same as page.ai)
      - NO screenshot
@@ -1087,16 +1140,32 @@ Loop up to 10 retries:
      - Retry with fresh DOM capture (page may have changed)
 ```
 
+`page.perform()` retry options are configurable per call:
+
+```typescript
+await page.perform("click the login button", {
+  maxElementRetries: 5,
+  retryDelayMs: 250,
+  maxContextSwitchRetries: 4,
+  contextSwitchRetryDelayMs: 500,
+});
+
+// Deprecated compatibility alias (warns once per agent instance):
+await page.perform("click the login button", {
+  maxSteps: 5,
+});
+```
+
 ### Key Implementation Differences
 
-| Aspect | `page.ai()` | `page.aiAction()` |
+| Aspect | `page.ai()` | `page.perform()` |
 |--------|-------------|-------------------|
 | **DOM Mode** | `mode: "visual-debug"` with screenshot | `mode: "a11y"` text-only |
 | **LLM Prompt** | Full agent system prompt with action schema | Minimal "find element" prompt |
-| **Retry Logic** | Agent loop handles retries via actions | Built-in 10x retry with DOM refresh |
+| **Retry Logic** | Agent loop handles retries via actions | Built-in retry loop with configurable bounds/delays |
 | **State Management** | TaskState tracks multi-step history | Stateless single execution |
 | **Error Handling** | Can recover via `thinking` action | Fails after max retries |
-| **Debug Output** | Per-step debug directories | Single aiAction/ directory |
+| **Debug Output** | Per-step debug directories | Single perform/ directory |
 
 ### When Each Entry Point Calls getA11yDOM
 
@@ -1112,12 +1181,12 @@ await getA11yDOM(page, {
 });
 ```
 
-**`page.aiAction()` calls:**
+**`page.perform()` calls:**
 ```typescript
 await getA11yDOM(page, {
   mode: "a11y",                // Text-only
   drawBoundingBoxes: false,    // No visual processing
-  debugDir: "debug/aiAction",
+  debugDir: "debug/perform",
   debug: true
 });
 ```
@@ -1163,18 +1232,18 @@ await page.ai("Login with email 'test@example.com' and password 'pass123'");
 // Step 6: complete
 ```
 
-**Using `page.aiAction()` (explicit steps):**
+**Using `page.perform()` (explicit steps):**
 ```typescript
-await page.aiAction("click the email field");
-await page.aiAction("type 'test@example.com' into the email field");
-await page.aiAction("click the password field");
-await page.aiAction("type 'pass123' into the password field");
-await page.aiAction("click the login button");
+await page.perform("click the email field");
+await page.perform("type 'test@example.com' into the email field");
+await page.perform("click the password field");
+await page.perform("type 'pass123' into the password field");
+await page.perform("click the login button");
 ```
 
 **Trade-off:**
 - `page.ai()`: More autonomous, but slower and more expensive
-- `page.aiAction()`: More control, faster, cheaper, but requires explicit sequencing
+- `page.perform()`: More control, faster, cheaper, but requires explicit sequencing
 
 ---
 
@@ -1196,7 +1265,7 @@ await page.aiAction("click the login button");
 
 **Entry Point:** `getA11yDOM(page, params)` in `src/context-providers/a11y-dom/index.ts`
 
-This is the core function that builds all the maps we discussed in Section 0. Both `page.ai()` and `page.aiAction()` call this function.
+This is the core function that builds all the maps we discussed in Section 0. Both `page.ai()` and `page.perform()` call this function.
 
 ### Complete Data Flow with Examples
 
@@ -1650,7 +1719,7 @@ We have to call each domain separately and stitch the results together using sha
 
 ## 3. Bounding Box Collection: How We Get Element Coordinates
 
-**Used by:** `page.ai()` visual mode only (not `page.aiAction()`)
+**Used by:** `page.ai()` visual mode only (not `page.perform()`)
 
 ### The Challenge
 
@@ -1849,7 +1918,7 @@ Result: Screenshot with red boxes and labels showing `"0-15"`, `"1-42"`, etc.
 
 ## 4. Element Resolution & Action Dispatch
 
-**Note:** For a high-level comparison of `page.ai()` vs `page.aiAction()`, see **Section 0.7**.
+**Note:** For a high-level comparison of `page.ai()` vs `page.perform()`, see **Section 0.7**.
 
 This section covers the implementation details of how we go from `encodedId` to actual CDP commands.
 
@@ -2531,7 +2600,7 @@ This diagram shows the complete data collection pipeline, including frame handli
 ```
 ┌─────────────────────────────────────────────────────────────────────────┐
 │                        Agent Task Starts                                 │
-│                    (page.ai() or page.aiAction())                       │
+│                    (page.ai() or page.perform())                        │
 └────────────────────────────────┬────────────────────────────────────────┘
                                  │
                                  ▼
@@ -2809,21 +2878,21 @@ OOPIF IFRAME (index 3):
 From buildBackendIdMaps (main frame):
   [frameMap]        { iframeBackendNodeId: 123,
                       contentDocBackendNodeId: undefined }  
-                    ❌ NO content (cross-origin blocked!)
+                    ❌ NO content in main-frame pass (cross-origin blocked here)
 
 From ensureInitialized (Phase 1):
   [FrameGraph]      { frameId: "XYZ789",
                       backendNodeId: 123,
                       sessionId: "oopif-sess" }  ✅ Has separate session
 
-Status: ❌ INCOMPLETE - Need Phase 3 to get OOPIF content
-        → captureOOPIFs will call buildBackendIdMaps(oopifSession)
+Status: ✅ COMPLETE - OOPIF content is captured in runtime flow
+        → captureOOPIFs discovers per-frame sessions, then buildBackendIdMaps(oopifSession, pierce: false) materializes OOPIF maps
 
 ────────────────────────────────────────────────────────────────
-NEXT STEPS:
-1. Phase 3: Fetch OOPIF content via their separate CDP sessions
-2. Phase 4: syncFrameContextManager to populate missing frameIds
-3. Phase 5: Fetch accessibility trees for all frames
+CURRENT FLOW:
+1. OOPIF discovery creates/refreshes per-frame sessions (with optional ad/tracking filtering).
+2. Frame graph sync backfills frame IDs/execution-context state from discovered sessions.
+3. Accessibility tree + map capture runs across main frame, same-origin iframes, and discovered OOPIF sessions.
 ```
 
 ---
@@ -2883,10 +2952,10 @@ Data After OOPIF Discovery:
 ═══════════════════════════════════════════════════════════════
 ├─ [backendNodeMap]    ✅ Complete (all frames)
 ├─ [xpathMap]          ✅ Complete (all frames)
-├─ [frameMap]          ⚠️  Still incomplete:
-│                          • frameId: ✅ Now complete
-│                          • executionContextId: ❌ Still missing!
-└─ Need Phase 4 for execution contexts
+├─ [frameMap]          ⚠️  Partially enriched:
+│                          • frameId: ✅ Populated
+│                          • executionContextId: ⏳ Populated in the sync pass below
+└─ Next: run syncFrameContextManager() to merge execution-context metadata
 ```
 
 ---
@@ -3417,7 +3486,7 @@ OOPIF / CROSS-ORIGIN IFRAME (frameIndex 3):
 ──────────────────────────────────────────────────────────────
 {
   // From buildBackendIdMaps (main frame):
-  // ❌ OOPIF content NOT captured (cross-origin blocked)
+  // ❌ Main-frame pass does NOT capture OOPIF content (cross-origin blocked here)
   
   // From captureOOPIFs → buildBackendIdMaps(oopifSession, pierce: false):
   backendNodeMap: { "3-89": 89, "3-90": 90, ... },
diff --git a/jest.config.cjs b/jest.config.cjs
new file mode 100644
index 00000000..3d9b8ec3
--- /dev/null
+++ b/jest.config.cjs
@@ -0,0 +1,14 @@
+/** @type {import('jest').Config} */
+module.exports = {
+  preset: "ts-jest",
+  testEnvironment: "node",
+  roots: ["<rootDir>/src"],
+  testMatch: ["**/*.test.ts"],
+  moduleNameMapper: {
+    "^@/(.*)$": "<rootDir>/src/$1",
+    "^@hyperbrowser/agent/types$": "<rootDir>/src/types/index.ts",
+    "^@hyperbrowser/agent$": "<rootDir>/src/index.ts",
+  },
+  clearMocks: true,
+  collectCoverageFrom: ["src/**/*.ts", "!src/**/*.d.ts"],
+};
diff --git a/package.json b/package.json
index 4e80fcb3..a8948e28 100644
--- a/package.json
+++ b/package.json
@@ -9,7 +9,6 @@
   "license": "AGPL-3.0",
   "scripts": {
     "build": "rm -rf dist && tsc && tsc-alias && node -e \"require('fs').chmodSync('dist/cli/index.js', '755')\" && node -e \"require('fs').chmodSync('cli.sh', '755')\"",
-    "build-dom-tree-script": "ts-node src/context-providers/dom/builder.ts",
     "lint": "eslint src/**/*.ts",
     "prepare": "yarn build",
     "test": "jest",
@@ -62,6 +61,7 @@
     "zod": "^4.1.8"
   },
   "devDependencies": {
+    "@types/jest": "^30.0.0",
     "@types/lodash": "^4.17.16",
     "@types/node": "^22.9.1",
     "@types/turndown": "^5.0.5",
@@ -73,7 +73,9 @@
     "eslint": "^9.15.0",
     "eslint-config-prettier": "^9.1.0",
     "exa-js": "^1.5.13",
+    "jest": "^30.2.0",
     "prettier": "^3.3.3",
+    "ts-jest": "^29.4.6",
     "ts-node": "^10.9.2",
     "tsc-alias": "^1.8.15",
     "tsconfig-paths": "^4.2.0",
diff --git a/scripts/dogcat.ts b/scripts/dogcat.ts
index 984a9efe..4e2f4188 100644
--- a/scripts/dogcat.ts
+++ b/scripts/dogcat.ts
@@ -40,41 +40,41 @@ async function runWorkflow() {
     console.log("Navigating to: https://www.bing.com/");
     await page.goto("https://www.bing.com/");
 
-    // Step 2: Perform action using aiAction (single granular action, a11y mode)
+    // Step 2: Perform action using perform() (single granular action, a11y mode)
     console.log(
       `Performing action: type ${variables.input1} into the search box`
     );
-    await page.aiAction(`type ${variables.input1} into the search box`);
+    await page.perform(`type ${variables.input1} into the search box`);
 
-    // Step 3: Perform action using aiAction
+    // Step 3: Perform action using perform()
     console.log(`Performing action: click the first search suggestion 'cats'`);
-    await page.aiAction(`click the first search suggestion 'cats'`);
+    await page.perform(`click the first search suggestion 'cats'`);
 
-    // Step 4: Perform action using aiAction
+    // Step 4: Perform action using perform()
     console.log(`Performing action: click the search box with 'cats' text`);
-    await page.aiAction(`click the search box with 'cats' text`);
+    await page.perform(`click the search box with 'cats' text`);
 
-    // Step 5: Perform action using aiAction
+    // Step 5: Perform action using perform()
     console.log(
       `Performing action: click the X button to clear the search box`
     );
-    await page.aiAction(`click the X button to clear the search box`);
+    await page.perform(`click the X button to clear the search box`);
 
-    // Step 6: Perform action using aiAction
+    // Step 6: Perform action using perform()
     console.log(
       `Performing action: type ${variables.input2} into the search box`
     );
-    await page.aiAction(`type ${variables.input2} into the search box`);
+    await page.perform(`type ${variables.input2} into the search box`);
 
-    // Step 7: Perform action using aiAction
+    // Step 7: Perform action using perform()
     console.log(`Performing action: click the first search suggestion 'dogs'`);
-    await page.aiAction(`click the first search suggestion 'dogs'`);
+    await page.perform(`click the first search suggestion 'dogs'`);
 
-    // Step 8: Perform action using aiAction
+    // Step 8: Perform action using perform()
     console.log(
       `Performing action: click the first search result 'Dog - Wikipedia'`
     );
-    await page.aiAction(`click the first search result 'Dog - Wikipedia'`);
+    await page.perform(`click the first search result 'Dog - Wikipedia'`);
 
     console.log("Workflow completed successfully");
     await new Promise((resolve) => setTimeout(resolve, 5000));
diff --git a/scripts/gasPrice.ts b/scripts/gasPrice.ts
index 6d2615b9..d2f2d4b5 100644
--- a/scripts/gasPrice.ts
+++ b/scripts/gasPrice.ts
@@ -43,40 +43,40 @@ async function runWorkflow() {
 
     // Step 2: Perform action
     console.log(`Performing action: click the search box`);
-    await page.aiAction(`click the search box`);
+    await page.perform(`click the search box`);
 
     // Step 3: Perform action
     console.log(`Performing action: click the directions button`);
-    await page.aiAction(`click the directions button`);
+    await page.perform(`click the directions button`);
 
     // Step 4: Perform action
     console.log(
       `Performing action: type 'San Francisco' into the starting point field`
     );
-    await page.aiAction(`type 'San Francisco' into the starting point field`);
+    await page.perform(`type 'San Francisco' into the starting point field`);
 
     // Step 5: Perform action
     console.log(
       `Performing action: type 'Los Angeles' into the destination field`
     );
-    await page.aiAction(`type 'Los Angeles' into the destination field`);
+    await page.perform(`type 'Los Angeles' into the destination field`);
 
     // Step 6: Perform action
     console.log(`Performing action: click the 'Los Angeles CA' option`);
-    await page.aiAction(`click the 'Los Angeles CA' option`);
+    await page.perform(`click the 'Los Angeles CA' option`);
 
     // Step 7: Perform action
     console.log(`Performing action: click the Gas button`);
-    await page.aiAction(`click the Gas button`);
+    await page.perform(`click the Gas button`);
 
     // Scroll: Scrolled down 300 pixels
-    await page.aiAction(`Scroll down to bottom`);
+    await page.perform(`Scroll down to bottom`);
 
     // Scroll: Scrolled down 500 pixels
-    await page.aiAction(`Scroll down to bottom`);
+    await page.perform(`Scroll down to bottom`);
 
     // Scroll: Scrolled down 800 pixels
-    await page.aiAction(`Scroll down to bottom`);
+    await page.perform(`Scroll down to bottom`);
 
     // Step 11: Extract data
     // console.log(
diff --git a/scripts/hotelInvoice.ts b/scripts/hotelInvoice.ts
index e1e5320b..5f5e37b1 100644
--- a/scripts/hotelInvoice.ts
+++ b/scripts/hotelInvoice.ts
@@ -39,34 +39,34 @@ async function runWorkflow() {
 
     // Step 2: Perform action
     console.log(`Performing action: click the Sign In or Join button`);
-    await page.aiAction(`click the Sign In or Join button`);
+    await page.perform(`click the Sign In or Join button`);
 
     // Step 3: Perform action
     console.log(`Performing action: click the Trips (1) link`);
-    await page.aiAction(`click the Trips (1) link`);
+    await page.perform(`click the Trips (1) link`);
 
     // Step 4: Perform action
     console.log(`Performing action: click the View/Modify Room link`);
-    await page.aiAction(`click the View/Modify Room link`);
+    await page.perform(`click the View/Modify Room link`);
 
     // Step 5: Perform action
     console.log(
       `Performing action: click the Summary of Charges 344.85 USD Total button`
     );
-    await page.aiAction(`click the Summary of Charges 344.85 USD Total button`);
+    await page.perform(`click the Summary of Charges 344.85 USD Total button`);
 
     // Scroll: Scrolled down 300 pixels
-    await page.aiAction(`Scrolled down 300 pixels`);
+    await page.perform(`Scrolled down 300 pixels`);
 
     // Scroll: Scrolled up 500 pixels
-    await page.aiAction(`Scrolled up 500 pixels`);
+    await page.perform(`Scrolled up 500 pixels`);
 
     // Scroll: Scrolled up 300 pixels
-    await page.aiAction(`Scrolled up 300 pixels`);
+    await page.perform(`Scrolled up 300 pixels`);
 
     // Step 9: Perform action
     console.log(`Performing action: click the Print button`);
-    await page.aiAction(`click the Print button`);
+    await page.perform(`click the Print button`);
 
     // Step 10: Extract data
     console.log(
@@ -99,19 +99,19 @@ async function runWorkflow() {
     console.log("Extracted:", extractedData10);
 
     // Scroll: Scrolled down 400 pixels
-    await page.aiAction(`Scrolled down 400 pixels`);
+    await page.perform(`Scrolled down 400 pixels`);
 
     // Scroll: Scrolled down 300 pixels
-    await page.aiAction(`Scrolled down 300 pixels`);
+    await page.perform(`Scrolled down 300 pixels`);
 
     // Scroll: Scrolled down 200 pixels
-    await page.aiAction(`Scrolled down 200 pixels`);
+    await page.perform(`Scrolled down 200 pixels`);
 
     // Scroll: Scrolled up 800 pixels
-    await page.aiAction(`Scrolled up 800 pixels`);
+    await page.perform(`Scrolled up 800 pixels`);
 
     // Scroll: Scrolled up 200 pixels
-    await page.aiAction(`Scrolled up 200 pixels`);
+    await page.perform(`Scrolled up 200 pixels`);
 
     // Step 16: Extract data
     console.log(
diff --git a/scripts/test-page-ai.ts b/scripts/test-page-ai.ts
index 48a9ba19..bdbd5721 100644
--- a/scripts/test-page-ai.ts
+++ b/scripts/test-page-ai.ts
@@ -52,20 +52,20 @@ dotenv.config();
 //   });
 //   const page = await agent.newPage();
 //   page.goto("https://flights.google.com");
-//   await page.aiAction("click source location box");
-//   await page.aiAction("type 'Rio de Janeiro' into the source location box");
-//   await page.aiAction("press enter");
-//   await page.aiAction("click destination location box");
-//   await page.aiAction("type 'Los Angeles' into the destination location box");
-//   await page.aiAction("press enter");
-//   await page.aiAction("click the departure date box");
-//   await page.aiAction(
+//   await page.perform("click source location box");
+//   await page.perform("type 'Rio de Janeiro' into the source location box");
+//   await page.perform("press enter");
+//   await page.perform("click destination location box");
+//   await page.perform("type 'Los Angeles' into the destination location box");
+//   await page.perform("press enter");
+//   await page.perform("click the departure date box");
+//   await page.perform(
 //     "fill 12/01/2025 into the departure date box"
 //   );
-//   await page.aiAction("click the return date box");
-//   await page.aiAction("fill 12/22/2025 into the return date box");
-//   await page.aiAction("click the search button");
-//   await page.aiAction("click the first flight option");
+//   await page.perform("click the return date box");
+//   await page.perform("fill 12/22/2025 into the return date box");
+//   await page.perform("click the search button");
+//   await page.perform("click the first flight option");
 
 //   // const page2 = await agent.newPage();
 //   // await page2.goto("https://maps.google.com");
diff --git a/src/__tests__/public-api.test.ts b/src/__tests__/public-api.test.ts
new file mode 100644
index 00000000..73792754
--- /dev/null
+++ b/src/__tests__/public-api.test.ts
@@ -0,0 +1,98 @@
+import HyperAgentDefault, {
+  HyperAgent,
+  HyperagentError,
+  HyperagentTaskError,
+  TaskStatus,
+} from "@/index";
+import type {
+  ActionCacheOutput,
+  ActionCacheReplayResult,
+  ActionCacheReplayStepResult,
+  AgentActionDefinition,
+  AgentTaskOutput,
+  HyperAgentConfig,
+  HyperPage,
+  HyperVariable,
+  MCPConfig,
+  MCPServerConfig,
+  PerformOptions,
+  PerformTaskParams,
+  RunFromActionCacheParams,
+  Task,
+  TaskOutput,
+  TaskParams,
+} from "@/index";
+
+describe("public API exports", () => {
+  it("exposes runtime entrypoint symbols", () => {
+    expect(HyperAgentDefault).toBe(HyperAgent);
+    expect(TaskStatus.COMPLETED).toBe("completed");
+    expect(new HyperagentError("boom")).toBeInstanceOf(Error);
+    expect(
+      new HyperagentTaskError("task-1", new Error("failed"))
+    ).toBeInstanceOf(HyperagentError);
+  });
+
+  it("keeps core public types importable from the package entrypoint", () => {
+    type PublicTypeSmoke = {
+      actionCacheOutput: ActionCacheOutput;
+      actionCacheReplayResult: ActionCacheReplayResult;
+      actionCacheReplayStepResult: ActionCacheReplayStepResult;
+      actionDefinition: AgentActionDefinition;
+      agentTaskOutput: AgentTaskOutput;
+      config: HyperAgentConfig;
+      hyperPage: HyperPage;
+      hyperVariable: HyperVariable;
+      mcpConfig: MCPConfig;
+      mcpServerConfig: MCPServerConfig;
+      performOptions: PerformOptions;
+      performTaskParams: PerformTaskParams;
+      replayParams: RunFromActionCacheParams;
+      task: Task;
+      taskOutput: TaskOutput;
+      taskParams: TaskParams;
+    };
+
+    const typeSmoke: PublicTypeSmoke | null = null;
+    expect(typeSmoke).toBeNull();
+  });
+
+  it("keeps perform retry option fields available on public PerformTaskParams", () => {
+    const performParams: PerformTaskParams = {
+      maxElementRetries: 5,
+      retryDelayMs: 250,
+      maxContextSwitchRetries: 4,
+      contextSwitchRetryDelayMs: 500,
+      cdpActions: false,
+      filterAdTrackingFrames: false,
+    };
+
+    expect(performParams.contextSwitchRetryDelayMs).toBe(500);
+    expect(performParams.cdpActions).toBe(false);
+    expect(performParams.filterAdTrackingFrames).toBe(false);
+  });
+
+  it("exposes frame-filter configuration on public HyperAgentConfig", () => {
+    const config: HyperAgentConfig = {
+      filterAdTrackingFrames: false,
+    };
+
+    expect(config.filterAdTrackingFrames).toBe(false);
+  });
+
+  it("exposes frame-filter overrides on task and replay params", () => {
+    const taskParams: TaskParams = {
+      cdpActions: false,
+      filterAdTrackingFrames: false,
+    };
+    const replayParams: RunFromActionCacheParams = {
+      cdpActions: false,
+      filterAdTrackingFrames: false,
+    };
+
+    expect(taskParams.cdpActions).toBe(false);
+    expect(taskParams.filterAdTrackingFrames).toBe(false);
+    expect(replayParams.cdpActions).toBe(false);
+    expect(replayParams.filterAdTrackingFrames).toBe(false);
+  });
+});
diff --git a/src/agent/__tests__/execute-single-action.test.ts b/src/agent/__tests__/execute-single-action.test.ts
new file mode 100644
index 00000000..f8d865e5
--- /dev/null
+++ b/src/agent/__tests__/execute-single-action.test.ts
@@ -0,0 +1,814 @@
+import type { Page } from "playwright-core";
+import { HyperAgent } from "@/agent";
+import type { HyperAgentLLM } from "@/llm/types";
+import type { PerformTaskParams } from "@/types";
+import { TaskStatus } from "@/types";
+
+jest.mock("@/agent/shared/find-element", () => ({
+  findElementWithInstruction: jest.fn(),
+}));
+
+jest.mock("@/agent/actions/shared/perform-action", () => ({
+  performAction: jest.fn(),
+}));
+
+jest.mock("@/agent/shared/runtime-context", () => ({
+  initializeRuntimeContext: jest.fn(),
+}));
+
+jest.mock("@/utils/waitForSettledDOM", () => ({
+  waitForSettledDOM: jest.fn(),
+}));
+
+jest.mock("@/utils/debugWriter", () => ({
+  writePerformDebug: jest.fn(),
+}));
+
+jest.mock("@/context-providers/a11y-dom/dom-cache", () => ({
+  markDomSnapshotDirty: jest.fn(),
+}));
+
+const { findElementWithInstruction } = jest.requireMock(
+  "@/agent/shared/find-element"
+) as {
+  findElementWithInstruction: jest.Mock;
+};
+
+const { performAction } = jest.requireMock(
+  "@/agent/actions/shared/perform-action"
+) as {
+  performAction: jest.Mock;
+};
+
+const { initializeRuntimeContext } = jest.requireMock(
+  "@/agent/shared/runtime-context"
+) as {
+  initializeRuntimeContext: jest.Mock;
+};
+
+const { waitForSettledDOM } = jest.requireMock(
+  "@/utils/waitForSettledDOM"
+) as {
+  waitForSettledDOM: jest.Mock;
+};
+
+const { writePerformDebug } = jest.requireMock(
+  "@/utils/debugWriter"
+) as {
+  writePerformDebug: jest.Mock;
+};
+
+function createMockLLM(): HyperAgentLLM {
+  return {
+    invoke: async () => ({ role: "assistant", content: "ok" }),
+    invokeStructured: async () => ({ rawText: "{}", parsed: null }),
+    getProviderId: () => "mock",
+    getModelId: () => "mock-model",
+    getCapabilities: () => ({
+      multimodal: false,
+      toolCalling: true,
+      jsonMode: true,
+    }),
+  };
+}
+
+describe("HyperAgent.executeSingleAction retry options", () => {
+  beforeEach(() => {
+    jest.clearAllMocks();
+
+    findElementWithInstruction.mockResolvedValue({
+      success: true,
+      element: {
+        elementId: "0-1",
+        method: "click",
+        arguments: [],
+        confidence: 1,
+        description: "button",
+      },
+      domState: {
+        elements: new Map([["0-1", { role: "button" }]]),
+        domState: "dom",
+        xpathMap: { "0-1": "//button[1]" },
+        backendNodeMap: {},
+      },
+      elementMap: new Map([["0-1", { role: "button" }]]),
+      llmResponse: {
+        rawText: "{}",
+        parsed: {},
+      },
+    });
+    initializeRuntimeContext.mockResolvedValue({
+      cdpClient: {},
+      frameContextManager: {},
+    });
+    performAction.mockResolvedValue({
+      success: true,
+      message: "ok",
+    });
+    waitForSettledDOM.mockResolvedValue({
+      durationMs: 1,
+      lifecycleMs: 0,
+      networkMs: 1,
+      requestsSeen: 0,
+      peakInflight: 0,
+      resolvedByTimeout: false,
+      forcedDrops: 0,
+    });
+    writePerformDebug.mockResolvedValue(undefined);
+  });
+
+  it("passes maxElementRetries and retryDelayMs to findElementWithInstruction", async () => {
+    const agent = new HyperAgent({
+      llm: createMockLLM(),
+      debug: false,
+      cdpActions: false,
+    });
+    const page = {
+      url: () => "https://example.com",
+    } as unknown as Page;
+
+    await agent.executeSingleAction("click login", page, {
+      maxElementRetries: 7,
+      retryDelayMs: 42,
+      maxContextSwitchRetries: 2,
+    });
+
+    expect(findElementWithInstruction).toHaveBeenCalledWith(
+      "click login",
+      page,
+      expect.any(Object),
+      expect.objectContaining({
+        maxRetries: 7,
+        retryDelayMs: 42,
+        filterAdTrackingFrames: true,
+      })
+    );
+  });
+
+  it("passes filterAdTrackingFrames=false to findElementWithInstruction when configured", async () => {
+    const agent = new HyperAgent({
+      llm: createMockLLM(),
+      debug: false,
+      cdpActions: false,
+      filterAdTrackingFrames: false,
+    });
+    const page = {
+      url: () => "https://example.com",
+    } as unknown as Page;
+
+    await agent.executeSingleAction("click login", page);
+
+    expect(findElementWithInstruction).toHaveBeenCalledWith(
+      "click login",
+      page,
+      expect.any(Object),
+      expect.objectContaining({
+        filterAdTrackingFrames: false,
+      })
+    );
+  });
+
+  it("prefers per-call filterAdTrackingFrames override over agent default", async () => {
+    const agent = new HyperAgent({
+      llm: createMockLLM(),
+      debug: false,
+      cdpActions: false,
+      filterAdTrackingFrames: true,
+    });
+    const page = {
+      url: () => "https://example.com",
+    } as unknown as Page;
+
+    await agent.executeSingleAction("click login", page, {
+      filterAdTrackingFrames: false,
+    });
+
+    expect(findElementWithInstruction).toHaveBeenCalledWith(
+      "click login",
+      page,
+      expect.any(Object),
+      expect.objectContaining({
+        filterAdTrackingFrames: false,
+      })
+    );
+  });
+
+  it("allows per-call cdpActions override to disable CDP runtime setup", async () => {
+    const agent = new HyperAgent({
+      llm: createMockLLM(),
+      debug: false,
+      cdpActions: true,
+    });
+    const page = {
+      url: () => "https://example.com",
+    } as unknown as Page;
+
+    await agent.executeSingleAction("click login", page, {
+      cdpActions: false,
+    });
+
+    expect(initializeRuntimeContext).not.toHaveBeenCalled();
+    const actionContext = performAction.mock.calls[0]?.[0] as {
+      cdpActions?: boolean;
+      cdp?: unknown;
+    };
+    expect(actionContext?.cdpActions).toBe(false);
+    expect(actionContext?.cdp).toBeUndefined();
+  });
+
+  it("allows per-call cdpActions override to enable CDP runtime setup", async () => {
+    const agent = new HyperAgent({
+      llm: createMockLLM(),
+      debug: false,
+      cdpActions: false,
+    });
+    const page = {
+      url: () => "https://example.com",
+    } as unknown as Page;
+
+    await agent.executeSingleAction("click login", page, {
+      cdpActions: true,
+    });
+
+    expect(initializeRuntimeContext).toHaveBeenCalledTimes(1);
+    const actionContext = performAction.mock.calls[0]?.[0] as {
+      cdpActions?: boolean;
+      cdp?: unknown;
+    };
+    expect(actionContext?.cdpActions).toBe(true);
+    expect(actionContext?.cdp).toBeTruthy();
+  });
+
+  it("falls back to agent cdpActions when perform params cdp getter traps", async () => {
+    const agent = new HyperAgent({
+      llm: createMockLLM(),
+      debug: false,
+      cdpActions: false,
+    });
+    const page = {
+      url: () => "https://example.com",
+    } as unknown as Page;
+    const trappedParams = new Proxy(
+      {},
+      {
+        get: (_target, prop: string | symbol) => {
+          if (prop === "cdpActions") {
+            throw new Error("perform cdp trap");
+          }
+          return undefined;
+        },
+      }
+    ) as PerformTaskParams;
+
+    await agent.executeSingleAction("click login", page, trappedParams);
+
+    expect(initializeRuntimeContext).not.toHaveBeenCalled();
+    const actionContext = performAction.mock.calls[0]?.[0] as {
+      cdpActions?: boolean;
+    };
+    expect(actionContext?.cdpActions).toBe(false);
+  });
+
+  it("falls back to agent filter setting when perform params getter traps", async () => {
+    const agent = new HyperAgent({
+      llm: createMockLLM(),
+      debug: false,
+      cdpActions: false,
+      filterAdTrackingFrames: false,
+    });
+    const page = {
+      url: () => "https://example.com",
+    } as unknown as Page;
+    const trappedParams = new Proxy(
+      {},
+      {
+        get: (_target, prop: string | symbol) => {
+          if (prop === "filterAdTrackingFrames") {
+            throw new Error("perform filter trap");
+          }
+          return undefined;
+        },
+      }
+    ) as PerformTaskParams;
+
+    await agent.executeSingleAction("click login", page, trappedParams);
+
+    expect(findElementWithInstruction).toHaveBeenCalledWith(
+      "click login",
+      page,
+      expect.any(Object),
+      expect.objectContaining({
+        filterAdTrackingFrames: false,
+      })
+    );
+  });
+
+  it("uses deprecated maxSteps as fallback for single-action retries", async () => {
+    const agent = new HyperAgent({
+      llm: createMockLLM(),
+      debug: false,
+      cdpActions: false,
+    });
+    const page = {
+      url: () => "https://example.com",
+    } as unknown as Page;
+    const warnSpy = jest.spyOn(console, "warn").mockImplementation(() => {});
+
+    try {
+      await agent.executeSingleAction("click login", page, {
+        maxSteps: 4,
+        retryDelayMs: 33,
+      });
+
+      expect(findElementWithInstruction).toHaveBeenCalledWith(
+        "click login",
+        page,
+        expect.any(Object),
+        expect.objectContaining({
+          maxRetries: 4,
+          retryDelayMs: 33,
+        })
+      );
+    } finally {
+      warnSpy.mockRestore();
+    }
+  });
+
+  it("prefers maxElementRetries over deprecated maxSteps when both are set", async () => {
+    const agent = new HyperAgent({
+      llm: createMockLLM(),
+      debug: false,
+      cdpActions: false,
+    });
+    const page = {
+      url: () => "https://example.com",
+    } as unknown as Page;
+
+    await agent.executeSingleAction("click login", page, {
+      maxElementRetries: 6,
+      maxSteps: 2,
+    });
+
+    expect(findElementWithInstruction).toHaveBeenCalledWith(
+      "click login",
+      page,
+      expect.any(Object),
+      expect.objectContaining({
+        maxRetries: 6,
+      })
+    );
+  });
+
+  it("warns once when deprecated maxSteps perform option is used", async () => {
+    const agent = new HyperAgent({
+      llm: createMockLLM(),
+      debug: false,
+      cdpActions: false,
+    });
+    const page = {
+      url: () => "https://example.com",
+    } as unknown as Page;
+    const warnSpy = jest.spyOn(console, "warn").mockImplementation(() => {});
+
+    try {
+      await agent.executeSingleAction("click login", page, {
+        maxSteps: 2,
+      });
+      await agent.executeSingleAction("click continue", page, {
+        maxSteps: 3,
+      });
+
+      expect(warnSpy).toHaveBeenCalledTimes(1);
+      expect(warnSpy).toHaveBeenCalledWith(
+        expect.stringContaining("perform({ maxSteps }) is deprecated")
+      );
+    } finally {
+      warnSpy.mockRestore();
+    }
+  });
+
+  it("does not warn about maxSteps deprecation when maxElementRetries is used", async () => {
+    const agent = new HyperAgent({
+      llm: createMockLLM(),
+      debug: false,
+      cdpActions: false,
+    });
+    const page = {
+      url: () => "https://example.com",
+    } as unknown as Page;
+    const warnSpy = jest.spyOn(console, "warn").mockImplementation(() => {});
+
+    try {
+      await agent.executeSingleAction("click login", page, {
+        maxElementRetries: 4,
+      });
+
+      const deprecationWarnings = warnSpy.mock.calls.filter((call) =>
+        String(call[0] ?? "").includes("perform({ maxSteps }) is deprecated")
+      );
+      expect(deprecationWarnings).toHaveLength(0);
+    } finally {
+      warnSpy.mockRestore();
+    }
+  });
+
+  it("formats non-Error execution failures with readable messages", async () => {
+    const agent = new HyperAgent({
+      llm: createMockLLM(),
+      debug: false,
+      cdpActions: false,
+    });
+    const page = {
+      url: () => "https://example.com",
+    } as unknown as Page;
+    performAction.mockRejectedValue({ reason: "perform crashed" });
+
+    await expect(
+      agent.executeSingleAction("click login", page, {
+        maxElementRetries: 1,
+      })
+    ).rejects.toThrow(
+      'Failed to execute action: {"reason":"perform crashed"}'
+    );
+  });
+
+  it("truncates oversized execution failures with bounded diagnostics", async () => {
+    const agent = new HyperAgent({
+      llm: createMockLLM(),
+      debug: false,
+      cdpActions: false,
+    });
+    const page = {
+      url: () => "https://example.com",
+    } as unknown as Page;
+    performAction.mockRejectedValue(new Error("x".repeat(2_000)));
+
+    await expect(
+      agent.executeSingleAction("click login", page, {
+        maxElementRetries: 1,
+      })
+    ).rejects.toThrow(/\[truncated/);
+  });
+
+  it("formats non-Error failure payloads written to perform debug artifacts", async () => {
+    const agent = new HyperAgent({
+      llm: createMockLLM(),
+      debug: true,
+      cdpActions: false,
+    });
+    const page = {
+      url: () => "https://example.com",
+      screenshot: jest.fn().mockResolvedValue(Buffer.from("screenshot")),
+    } as unknown as Page;
+    performAction.mockRejectedValue({ reason: "perform crashed" });
+    writePerformDebug.mockResolvedValue(undefined);
+    const logSpy = jest.spyOn(console, "log").mockImplementation(() => {});
+
+    try {
+      await expect(
+        agent.executeSingleAction("click login", page, {
+          maxElementRetries: 1,
+        })
+      ).rejects.toThrow(
+        'Failed to execute action: {"reason":"perform crashed"}'
+      );
+
+      expect(writePerformDebug).toHaveBeenCalledWith(
+        expect.objectContaining({
+          success: false,
+          error: expect.objectContaining({
+            message: '{"reason":"perform crashed"}',
+          }),
+        }),
+        "debug/perform"
+      );
+    } finally {
+      logSpy.mockRestore();
+    }
+  });
+
+  it("truncates oversized failure payloads written to perform debug artifacts", async () => {
+    const agent = new HyperAgent({
+      llm: createMockLLM(),
+      debug: true,
+      cdpActions: false,
+    });
+    const page = {
+      url: () => "https://example.com",
+      screenshot: jest.fn().mockResolvedValue(Buffer.from("screenshot")),
+    } as unknown as Page;
+    performAction.mockRejectedValue(new Error("x".repeat(2_000)));
+    writePerformDebug.mockResolvedValue(undefined);
+    const logSpy = jest.spyOn(console, "log").mockImplementation(() => {});
+
+    try {
+      await expect(
+        agent.executeSingleAction("click login", page, {
+          maxElementRetries: 1,
+        })
+      ).rejects.toThrow(/\[truncated/);
+
+      expect(writePerformDebug).toHaveBeenCalledWith(
+        expect.objectContaining({
+          success: false,
+          error: expect.objectContaining({
+            message: expect.stringContaining("[truncated"),
+          }),
+        }),
+        "debug/perform"
+      );
+    } finally {
+      logSpy.mockRestore();
+    }
+  });
+
+  it("formats non-Error perform debug writer failures", async () => {
+    const agent = new HyperAgent({
+      llm: createMockLLM(),
+      debug: true,
+      cdpActions: false,
+    });
+    const page = {
+      url: () => "https://example.com",
+      screenshot: jest.fn().mockResolvedValue(Buffer.from("screenshot")),
+    } as unknown as Page;
+    writePerformDebug.mockRejectedValue({ reason: "debug writer crashed" });
+    const errorSpy = jest.spyOn(console, "error").mockImplementation(() => {});
+    const logSpy = jest.spyOn(console, "log").mockImplementation(() => {});
+
+    try {
+      const result = await agent.executeSingleAction("click login", page, {
+        maxElementRetries: 1,
+      });
+
+      expect(result.status).toBe(TaskStatus.COMPLETED);
+      expect(errorSpy).toHaveBeenCalledWith(
+        '[perform] Failed to write debug data: {"reason":"debug writer crashed"}'
+      );
+    } finally {
+      errorSpy.mockRestore();
+      logSpy.mockRestore();
+    }
+  });
+
+  it("truncates oversized perform debug writer diagnostics", async () => {
+    const agent = new HyperAgent({
+      llm: createMockLLM(),
+      debug: true,
+      cdpActions: false,
+    });
+    const page = {
+      url: () => "https://example.com",
+      screenshot: jest.fn().mockResolvedValue(Buffer.from("screenshot")),
+    } as unknown as Page;
+    writePerformDebug.mockRejectedValue(new Error("x".repeat(2_000)));
+    const errorSpy = jest.spyOn(console, "error").mockImplementation(() => {});
+    const logSpy = jest.spyOn(console, "log").mockImplementation(() => {});
+
+    try {
+      const result = await agent.executeSingleAction("click login", page, {
+        maxElementRetries: 1,
+      });
+
+      expect(result.status).toBe(TaskStatus.COMPLETED);
+      const errorMessage = String(errorSpy.mock.calls[0]?.[0] ?? "");
+      expect(errorMessage).toContain("[truncated");
+    } finally {
+      errorSpy.mockRestore();
+      logSpy.mockRestore();
+    }
+  });
+
+  it("preserves not-found diagnostics when page.url getter throws in debug mode", async () => {
+    const agent = new HyperAgent({
+      llm: createMockLLM(),
+      debug: true,
+      cdpActions: false,
+    });
+    const page = {
+      url: () => {
+        throw new Error("url trap");
+      },
+      screenshot: jest.fn().mockResolvedValue(Buffer.from("screenshot")),
+    } as unknown as Page;
+    const logSpy = jest.spyOn(console, "log").mockImplementation(() => {});
+    const errorSpy = jest.spyOn(console, "error").mockImplementation(() => {});
+    findElementWithInstruction.mockResolvedValueOnce({
+      success: false,
+      domState: {
+        elements: new Map(),
+        domState: "dom",
+        xpathMap: {},
+        backendNodeMap: {},
+      },
+      elementMap: new Map(),
+      llmResponse: {
+        rawText: "{}",
+        parsed: {},
+      },
+    });
+
+    try {
+      await expect(
+        agent.executeSingleAction("click login", page, {
+          maxElementRetries: 1,
+        })
+      ).rejects.toThrow("No elements found for instruction");
+
+      expect(writePerformDebug).toHaveBeenCalledWith(
+        expect.objectContaining({
+          url: "about:blank",
+        }),
+        "debug/perform"
+      );
+    } finally {
+      logSpy.mockRestore();
+      errorSpy.mockRestore();
+    }
+  });
+
+  it("sanitizes control characters in debug URL metadata", async () => {
+    const agent = new HyperAgent({
+      llm: createMockLLM(),
+      debug: true,
+      cdpActions: false,
+    });
+    const page = {
+      url: () => "https://example.com/\u0000debug\npath",
+      screenshot: jest.fn().mockResolvedValue(Buffer.from("screenshot")),
+    } as unknown as Page;
+    performAction.mockRejectedValueOnce({ reason: "perform crashed" });
+    writePerformDebug.mockResolvedValue(undefined);
+    const logSpy = jest.spyOn(console, "log").mockImplementation(() => {});
+    const errorSpy = jest.spyOn(console, "error").mockImplementation(() => {});
+
+    try {
+      await expect(
+        agent.executeSingleAction("click login", page, {
+          maxElementRetries: 1,
+        })
+      ).rejects.toThrow('Failed to execute action: {"reason":"perform crashed"}');
+
+      expect(writePerformDebug).toHaveBeenCalledWith(
+        expect.objectContaining({
+          url: "https://example.com/ debug path",
+        }),
+        "debug/perform"
+      );
+    } finally {
+      logSpy.mockRestore();
+      errorSpy.mockRestore();
+    }
+  });
+
+  it("truncates oversized debug URL metadata", async () => {
+    const agent = new HyperAgent({
+      llm: createMockLLM(),
+      debug: true,
+      cdpActions: false,
+    });
+    const page = {
+      url: () => `https://example.com/${"x".repeat(4_000)}`,
+      screenshot: jest.fn().mockResolvedValue(Buffer.from("screenshot")),
+    } as unknown as Page;
+    performAction.mockRejectedValueOnce({ reason: "perform crashed" });
+    writePerformDebug.mockResolvedValue(undefined);
+    const logSpy = jest.spyOn(console, "log").mockImplementation(() => {});
+    const errorSpy = jest.spyOn(console, "error").mockImplementation(() => {});
+
+    try {
+      await expect(
+        agent.executeSingleAction("click login", page, {
+          maxElementRetries: 1,
+        })
+      ).rejects.toThrow('Failed to execute action: {"reason":"perform crashed"}');
+
+      expect(writePerformDebug).toHaveBeenCalledWith(
+        expect.objectContaining({
+          url: expect.stringContaining("[truncated"),
+        }),
+        "debug/perform"
+      );
+    } finally {
+      logSpy.mockRestore();
+      errorSpy.mockRestore();
+    }
+  });
+
+  it("continues debug-data writes when screenshot accessor traps throw", async () => {
+    const agent = new HyperAgent({
+      llm: createMockLLM(),
+      debug: true,
+      cdpActions: false,
+    });
+    const page = {
+      url: () => "https://example.com",
+      get screenshot(): never {
+        throw new Error("screenshot trap");
+      },
+    } as unknown as Page;
+    performAction.mockRejectedValueOnce(new Error("perform failed"));
+    const logSpy = jest.spyOn(console, "log").mockImplementation(() => {});
+
+    try {
+      await expect(
+        agent.executeSingleAction("click login", page, {
+          maxElementRetries: 1,
+        })
+      ).rejects.toThrow("perform failed");
+
+      expect(writePerformDebug).toHaveBeenCalledWith(
+        expect.objectContaining({
+          success: false,
+        }),
+        "debug/perform"
+      );
+    } finally {
+      logSpy.mockRestore();
+    }
+  });
+
+  it("keeps element-not-found errors readable when page.url getter traps", async () => {
+    const agent = new HyperAgent({
+      llm: createMockLLM(),
+      debug: true,
+      cdpActions: false,
+    });
+    findElementWithInstruction.mockResolvedValueOnce({
+      success: false,
+      domState: {
+        elements: new Map(),
+        domState: "dom",
+        xpathMap: {},
+        backendNodeMap: {},
+      },
+      elementMap: new Map(),
+      llmResponse: {
+        rawText: "{}",
+        parsed: {},
+      },
+    });
+    const page = {
+      url: () => {
+        throw new Error("url trap");
+      },
+      screenshot: jest.fn().mockResolvedValue(Buffer.from("screenshot")),
+    } as unknown as Page;
+    const errorSpy = jest.spyOn(console, "error").mockImplementation(() => {});
+    const logSpy = jest.spyOn(console, "log").mockImplementation(() => {});
+
+    try {
+      await expect(
+        agent.executeSingleAction("click missing", page, {
+          maxElementRetries: 1,
+        })
+      ).rejects.toThrow("No elements found for instruction");
+      expect(writePerformDebug).toHaveBeenCalledWith(
+        expect.objectContaining({
+          url: "about:blank",
+        }),
+        "debug/perform"
+      );
+    } finally {
+      errorSpy.mockRestore();
+      logSpy.mockRestore();
+    }
+  });
+
+  it("continues debug writing when screenshot accessor traps throw", async () => {
+    const agent = new HyperAgent({
+      llm: createMockLLM(),
+      debug: true,
+      cdpActions: false,
+    });
+    performAction.mockRejectedValueOnce({ reason: "perform crashed" });
+    writePerformDebug.mockResolvedValue(undefined);
+    const page = {
+      url: () => "https://example.com",
+      get screenshot(): unknown {
+        throw new Error("screenshot trap");
+      },
+    } as unknown as Page;
+    const errorSpy = jest.spyOn(console, "error").mockImplementation(() => {});
+    const logSpy = jest.spyOn(console, "log").mockImplementation(() => {});
+
+    try {
+      await expect(
+        agent.executeSingleAction("click login", page, {
+          maxElementRetries: 1,
+        })
+      ).rejects.toThrow('Failed to execute action: {"reason":"perform crashed"}');
+
+      expect(writePerformDebug).toHaveBeenCalledWith(
+        expect.objectContaining({
+          success: false,
+          screenshot: undefined,
+        }),
+        "debug/perform"
+      );
+    } finally {
+      errorSpy.mockRestore();
+      logSpy.mockRestore();
+    }
+  });
+});
diff --git a/src/agent/__tests__/hyperagent-constructor.test.ts b/src/agent/__tests__/hyperagent-constructor.test.ts
new file mode 100644
index 00000000..fa920ddb
--- /dev/null
+++ b/src/agent/__tests__/hyperagent-constructor.test.ts
@@ -0,0 +1,4876 @@
+import { z } from "zod";
+import type { Page } from "playwright-core";
+import { HyperAgent } from "@/agent";
+import { getDebugOptions, setDebugOptions } from "@/debug/options";
+import type { AgentActionDefinition, TaskParams, TaskState } from "@/types";
+import type { HyperAgentLLM } from "@/llm/types";
+import { runAgentTask } from "@/agent/tools/agent";
+import { TaskStatus, type AgentTaskOutput } from "@/types/agent/types";
+import { HyperagentError, HyperagentTaskError } from "@/agent/error";
+import type { ActionCacheEntry } from "@/types/agent/types";
+
+jest.mock("@/agent/tools/agent", () => ({
+  runAgentTask: jest.fn(),
+}));
+
+function createMockLLM(): HyperAgentLLM {
+  return {
+    invoke: async () => ({
+      role: "assistant",
+      content: "ok",
+    }),
+    invokeStructured: async () => ({
+      rawText: "{}",
+      parsed: null,
+    }),
+    getProviderId: () => "mock",
+    getModelId: () => "mock-model",
+    getCapabilities: () => ({
+      multimodal: false,
+      toolCalling: true,
+      jsonMode: true,
+    }),
+  };
+}
+
+describe("HyperAgent constructor and task controls", () => {
+  beforeEach(() => {
+    setDebugOptions(undefined, false);
+    jest.clearAllMocks();
+  });
+
+  it("enables debug options when debug mode is true", () => {
+    const agent = new HyperAgent({
+      llm: createMockLLM(),
+      debug: true,
+      debugOptions: { traceWait: true },
+    });
+
+    expect(agent).toBeInstanceOf(HyperAgent);
+    expect(getDebugOptions().enabled).toBe(true);
+    expect(getDebugOptions().traceWait).toBe(true);
+  });
+
+  it("falls back to default constructor toggles when config getters trap", async () => {
+    const mockedRunAgentTask = jest.mocked(runAgentTask);
+    mockedRunAgentTask.mockResolvedValue({
+      taskId: "task-id-constructor-trap",
+      status: TaskStatus.COMPLETED,
+      steps: [],
+      output: "done",
+      actionCache: {
+        taskId: "task-id-constructor-trap",
+        createdAt: new Date().toISOString(),
+        status: TaskStatus.COMPLETED,
+        steps: [],
+      },
+    });
+
+    const trappedConfig = new Proxy(
+      {
+        llm: createMockLLM(),
+      },
+      {
+        get: (target, prop: string | symbol, receiver) => {
+          if (
+            prop === "cdpActions" ||
+            prop === "filterAdTrackingFrames" ||
+            prop === "debug" ||
+            prop === "debugOptions" ||
+            prop === "browserProvider" ||
+            prop === "customActions" ||
+            prop === "hyperbrowserConfig" ||
+            prop === "localConfig"
+          ) {
+            throw new Error("constructor option trap");
+          }
+          return Reflect.get(target, prop, receiver);
+        },
+      }
+    ) as unknown as ConstructorParameters<typeof HyperAgent>[0];
+
+    const agent = new HyperAgent(trappedConfig);
+    const fakePage = {} as unknown as Page;
+    await agent.executeTask("test task", undefined, fakePage);
+
+    const runtimeCtx = mockedRunAgentTask.mock.calls[0]?.[0] as {
+      cdpActions?: boolean;
+      filterAdTrackingFrames?: boolean;
+    };
+    const internalAgent = agent as unknown as {
+      browserProviderType?: string;
+    };
+    expect(runtimeCtx?.cdpActions).toBe(true);
+    expect(runtimeCtx?.filterAdTrackingFrames).toBe(true);
+    expect(internalAgent.browserProviderType).toBe("Local");
+    expect(getDebugOptions().enabled).toBe(false);
+  });
+
+  it("throws readable missing-provider error when llm getter traps", () => {
+    const previousKey = process.env.OPENAI_API_KEY;
+    delete process.env.OPENAI_API_KEY;
+    try {
+      const trappedConfig = new Proxy(
+        {},
+        {
+          get: (_target, prop: string | symbol) => {
+            if (prop === "llm") {
+              throw new Error("llm getter trap");
+            }
+            return undefined;
+          },
+        }
+      ) as unknown as ConstructorParameters<typeof HyperAgent>[0];
+
+      expect(() => new HyperAgent(trappedConfig)).toThrow(
+        "No LLM provider provided"
+      );
+    } finally {
+      if (typeof previousKey === "undefined") {
+        delete process.env.OPENAI_API_KEY;
+      } else {
+        process.env.OPENAI_API_KEY = previousKey;
+      }
+    }
+  });
+
+  it("throws readable error for malformed llm payloads", () => {
+    expect(
+      () =>
+        new HyperAgent({
+          llm: {
+            invoke: async () => ({ role: "assistant", content: "ok" }),
+          } as unknown as HyperAgentLLM,
+        })
+    ).toThrow(
+      "Invalid llm configuration: expected provider config or HyperAgentLLM client"
+    );
+  });
+
+  it("continues constructor when customActions length getter traps", () => {
+    const trappedCustomActions = new Proxy(
+      [
+        {
+          type: "trappedAction",
+          actionParams: z.object({}),
+          run: async () => ({ success: true, message: "noop" }),
+        },
+      ],
+      {
+        get: (target, prop, receiver) => {
+          if (prop === "length") {
+            throw new Error("customActions length trap");
+          }
+          return Reflect.get(target, prop, receiver);
+        },
+      }
+    );
+
+    expect(
+      () =>
+        new HyperAgent({
+          llm: createMockLLM(),
+          customActions: trappedCustomActions as unknown as AgentActionDefinition[],
+        })
+    ).not.toThrow();
+  });
+
+  it("registers readable custom actions when some customActions entries trap", () => {
+    const safeAction: AgentActionDefinition = {
+      type: "safeAction",
+      actionParams: z.object({}),
+      run: async () => ({ success: true, message: "ok" }),
+    };
+    const trappedCustomActions = new Proxy([{}, safeAction], {
+      get: (target, prop, receiver) => {
+        if (prop === "0") {
+          throw new Error("customActions item trap");
+        }
+        return Reflect.get(target, prop, receiver);
+      },
+    });
+
+    const agent = new HyperAgent({
+      llm: createMockLLM(),
+      customActions: trappedCustomActions as unknown as AgentActionDefinition[],
+    });
+    const internalAgent = agent as unknown as {
+      actions: Array<{ type?: string }>;
+    };
+
+    expect(
+      internalAgent.actions.some((action) => action.type === "safeAction")
+    ).toBe(true);
+  });
+
+  it("throws synchronously for reserved custom action names", () => {
+    const reservedAction: AgentActionDefinition = {
+      type: "complete",
+      actionParams: z.object({}),
+      run: async () => ({ success: true, message: "noop" }),
+    };
+
+    expect(
+      () =>
+        new HyperAgent({
+          llm: createMockLLM(),
+          customActions: [reservedAction],
+        })
+    ).toThrow("reserved action");
+  });
+
+  it("throws synchronously for duplicate custom action names", () => {
+    const duplicateAction: AgentActionDefinition = {
+      type: "goToUrl",
+      actionParams: z.object({}),
+      run: async () => ({ success: true, message: "noop" }),
+    };
+
+    expect(
+      () =>
+        new HyperAgent({
+          llm: createMockLLM(),
+          customActions: [duplicateAction],
+        })
+    ).toThrow("already registered");
+  });
+
+  it("returns async task controls with awaitable result promise", async () => {
+    const mockedRunAgentTask = jest.mocked(runAgentTask);
+    mockedRunAgentTask.mockResolvedValue({
+      taskId: "task-id",
+      status: TaskStatus.COMPLETED,
+      steps: [],
+      output: "done",
+      actionCache: {
+        taskId: "task-id",
+        createdAt: new Date().toISOString(),
+        status: TaskStatus.COMPLETED,
+        steps: [],
+      },
+    });
+
+    const agent = new HyperAgent({
+      llm: createMockLLM(),
+    });
+    const fakePage = {} as unknown as Page;
+    const task = await agent.executeTaskAsync("test task", undefined, fakePage);
+
+    expect(task.id).toBeDefined();
+    await expect(task.result).resolves.toMatchObject({
+      status: TaskStatus.COMPLETED,
+      output: "done",
+    });
+    const internalAgent = agent as unknown as {
+      tasks: Record<string, unknown>;
+      taskResults: Record<string, unknown>;
+    };
+    expect(Object.keys(internalAgent.tasks)).toHaveLength(0);
+    expect(Object.keys(internalAgent.taskResults)).toHaveLength(0);
+  });
+
+  it("forwards filterAdTrackingFrames configuration into runAgentTask context", async () => {
+    const mockedRunAgentTask = jest.mocked(runAgentTask);
+    mockedRunAgentTask.mockResolvedValue({
+      taskId: "task-id-filter",
+      status: TaskStatus.COMPLETED,
+      steps: [],
+      output: "done",
+      actionCache: {
+        taskId: "task-id-filter",
+        createdAt: new Date().toISOString(),
+        status: TaskStatus.COMPLETED,
+        steps: [],
+      },
+    });
+
+    const agent = new HyperAgent({
+      llm: createMockLLM(),
+      filterAdTrackingFrames: false,
+    });
+    const fakePage = {} as unknown as Page;
+
+    await agent.executeTask("test task", undefined, fakePage);
+
+    const runtimeCtx = mockedRunAgentTask.mock.calls[0]?.[0] as {
+      filterAdTrackingFrames?: boolean;
+    };
+    expect(runtimeCtx?.filterAdTrackingFrames).toBe(false);
+  });
+
+  it("forwards per-task cdpActions override into runAgentTask context", async () => {
+    const mockedRunAgentTask = jest.mocked(runAgentTask);
+    mockedRunAgentTask.mockResolvedValue({
+      taskId: "task-id-cdp-override",
+      status: TaskStatus.COMPLETED,
+      steps: [],
+      output: "done",
+      actionCache: {
+        taskId: "task-id-cdp-override",
+        createdAt: new Date().toISOString(),
+        status: TaskStatus.COMPLETED,
+        steps: [],
+      },
+    });
+
+    const agent = new HyperAgent({
+      llm: createMockLLM(),
+      cdpActions: true,
+    });
+    const fakePage = {} as unknown as Page;
+    await agent.executeTask("test task", { cdpActions: false }, fakePage);
+
+    const runtimeCtx = mockedRunAgentTask.mock.calls[0]?.[0] as {
+      cdpActions?: boolean;
+    };
+    expect(runtimeCtx?.cdpActions).toBe(false);
+  });
+
+  it("forwards async task cdpActions override into runAgentTask context", async () => {
+    const mockedRunAgentTask = jest.mocked(runAgentTask);
+    mockedRunAgentTask.mockResolvedValue({
+      taskId: "task-id-cdp-async-override",
+      status: TaskStatus.COMPLETED,
+      steps: [],
+      output: "done",
+      actionCache: {
+        taskId: "task-id-cdp-async-override",
+        createdAt: new Date().toISOString(),
+        status: TaskStatus.COMPLETED,
+        steps: [],
+      },
+    });
+
+    const agent = new HyperAgent({
+      llm: createMockLLM(),
+      cdpActions: false,
+    });
+    const fakePage = {} as unknown as Page;
+    const task = await agent.executeTaskAsync(
+      "test task",
+      { cdpActions: true },
+      fakePage
+    );
+    await task.result;
+
+    const runtimeCtx = mockedRunAgentTask.mock.calls[0]?.[0] as {
+      cdpActions?: boolean;
+    };
+    expect(runtimeCtx?.cdpActions).toBe(true);
+  });
+
+  it("prefers per-task filterAdTrackingFrames override over agent default", async () => {
+    const mockedRunAgentTask = jest.mocked(runAgentTask);
+    mockedRunAgentTask.mockResolvedValue({
+      taskId: "task-id-filter-override",
+      status: TaskStatus.COMPLETED,
+      steps: [],
+      output: "done",
+      actionCache: {
+        taskId: "task-id-filter-override",
+        createdAt: new Date().toISOString(),
+        status: TaskStatus.COMPLETED,
+        steps: [],
+      },
+    });
+
+    const agent = new HyperAgent({
+      llm: createMockLLM(),
+      filterAdTrackingFrames: true,
+    });
+    const fakePage = {} as unknown as Page;
+
+    await agent.executeTask(
+      "test task",
+      { filterAdTrackingFrames: false },
+      fakePage
+    );
+
+    const runtimeCtx = mockedRunAgentTask.mock.calls[0]?.[0] as {
+      filterAdTrackingFrames?: boolean;
+    };
+    expect(runtimeCtx?.filterAdTrackingFrames).toBe(false);
+  });
+
+  it("applies filter override for executeTaskAsync context", async () => {
+    const mockedRunAgentTask = jest.mocked(runAgentTask);
+    mockedRunAgentTask.mockResolvedValue({
+      taskId: "task-id-filter-async-override",
+      status: TaskStatus.COMPLETED,
+      steps: [],
+      output: "done",
+      actionCache: {
+        taskId: "task-id-filter-async-override",
+        createdAt: new Date().toISOString(),
+        status: TaskStatus.COMPLETED,
+        steps: [],
+      },
+    });
+
+    const agent = new HyperAgent({
+      llm: createMockLLM(),
+      filterAdTrackingFrames: true,
+    });
+    const fakePage = {} as unknown as Page;
+    const task = await agent.executeTaskAsync(
+      "test task",
+      { filterAdTrackingFrames: false },
+      fakePage
+    );
+    await task.result;
+
+    const runtimeCtx = mockedRunAgentTask.mock.calls[0]?.[0] as {
+      filterAdTrackingFrames?: boolean;
+    };
+    expect(runtimeCtx?.filterAdTrackingFrames).toBe(false);
+  });
+
+  it("falls back to agent frame-filter setting when task params getter traps", async () => {
+    const mockedRunAgentTask = jest.mocked(runAgentTask);
+    mockedRunAgentTask.mockResolvedValue({
+      taskId: "task-id-filter-trap",
+      status: TaskStatus.COMPLETED,
+      steps: [],
+      output: "done",
+      actionCache: {
+        taskId: "task-id-filter-trap",
+        createdAt: new Date().toISOString(),
+        status: TaskStatus.COMPLETED,
+        steps: [],
+      },
+    });
+
+    const agent = new HyperAgent({
+      llm: createMockLLM(),
+      filterAdTrackingFrames: false,
+    });
+    const trappedParams = new Proxy(
+      {},
+      {
+        get: (_target, prop: string | symbol) => {
+          if (prop === "filterAdTrackingFrames") {
+            throw new Error("filter option trap");
+          }
+          return undefined;
+        },
+      }
+    ) as TaskParams;
+    const fakePage = {} as unknown as Page;
+    const task = await agent.executeTaskAsync("test task", trappedParams, fakePage);
+    await task.result;
+
+    const runtimeCtx = mockedRunAgentTask.mock.calls[0]?.[0] as {
+      filterAdTrackingFrames?: boolean;
+    };
+    expect(runtimeCtx?.filterAdTrackingFrames).toBe(false);
+  });
+
+  it("falls back to agent frame-filter setting for sync executeTask when params getter traps", async () => {
+    const mockedRunAgentTask = jest.mocked(runAgentTask);
+    mockedRunAgentTask.mockResolvedValue({
+      taskId: "task-id-filter-sync-trap",
+      status: TaskStatus.COMPLETED,
+      steps: [],
+      output: "done",
+      actionCache: {
+        taskId: "task-id-filter-sync-trap",
+        createdAt: new Date().toISOString(),
+        status: TaskStatus.COMPLETED,
+        steps: [],
+      },
+    });
+
+    const agent = new HyperAgent({
+      llm: createMockLLM(),
+      filterAdTrackingFrames: false,
+    });
+    const trappedParams = new Proxy(
+      {},
+      {
+        get: (_target, prop: string | symbol) => {
+          if (prop === "filterAdTrackingFrames") {
+            throw new Error("sync filter option trap");
+          }
+          return undefined;
+        },
+      }
+    ) as TaskParams;
+    const fakePage = {} as unknown as Page;
+    await agent.executeTask("test task", trappedParams, fakePage);
+
+    const runtimeCtx = mockedRunAgentTask.mock.calls[0]?.[0] as {
+      filterAdTrackingFrames?: boolean;
+    };
+    expect(runtimeCtx?.filterAdTrackingFrames).toBe(false);
+  });
+
+  it("falls back to agent cdpActions setting when task params cdp getter traps", async () => {
+    const mockedRunAgentTask = jest.mocked(runAgentTask);
+    mockedRunAgentTask.mockResolvedValue({
+      taskId: "task-id-cdp-trap",
+      status: TaskStatus.COMPLETED,
+      steps: [],
+      output: "done",
+      actionCache: {
+        taskId: "task-id-cdp-trap",
+        createdAt: new Date().toISOString(),
+        status: TaskStatus.COMPLETED,
+        steps: [],
+      },
+    });
+
+    const agent = new HyperAgent({
+      llm: createMockLLM(),
+      cdpActions: false,
+    });
+    const trappedParams = new Proxy(
+      {},
+      {
+        get: (_target, prop: string | symbol) => {
+          if (prop === "cdpActions") {
+            throw new Error("cdp option trap");
+          }
+          return undefined;
+        },
+      }
+    ) as TaskParams;
+    const fakePage = {} as unknown as Page;
+    const task = await agent.executeTaskAsync("test task", trappedParams, fakePage);
+    await task.result;
+
+    const runtimeCtx = mockedRunAgentTask.mock.calls[0]?.[0] as {
+      cdpActions?: boolean;
+    };
+    expect(runtimeCtx?.cdpActions).toBe(false);
+  });
+
+  it("falls back to agent cdpActions setting for sync executeTask when params getter traps", async () => {
+    const mockedRunAgentTask = jest.mocked(runAgentTask);
+    mockedRunAgentTask.mockResolvedValue({
+      taskId: "task-id-cdp-sync-trap",
+      status: TaskStatus.COMPLETED,
+      steps: [],
+      output: "done",
+      actionCache: {
+        taskId: "task-id-cdp-sync-trap",
+        createdAt: new Date().toISOString(),
+        status: TaskStatus.COMPLETED,
+        steps: [],
+      },
+    });
+
+    const agent = new HyperAgent({
+      llm: createMockLLM(),
+      cdpActions: false,
+    });
+    const trappedParams = new Proxy(
+      {},
+      {
+        get: (_target, prop: string | symbol) => {
+          if (prop === "cdpActions") {
+            throw new Error("sync cdp option trap");
+          }
+          return undefined;
+        },
+      }
+    ) as TaskParams;
+    const fakePage = {} as unknown as Page;
+    await agent.executeTask("test task", trappedParams, fakePage);
+
+    const runtimeCtx = mockedRunAgentTask.mock.calls[0]?.[0] as {
+      cdpActions?: boolean;
+    };
+    expect(runtimeCtx?.cdpActions).toBe(false);
+  });
+
+  it("executeTaskAsync cleans up state when setup throws before run starts", async () => {
+    const agent = new HyperAgent({
+      llm: createMockLLM(),
+    });
+    const on = jest.fn();
+    const off = jest.fn();
+    const internalAgent = agent as unknown as {
+      context: {
+        on: typeof on;
+        off: typeof off;
+      } | null;
+      tasks: Record<string, unknown>;
+      taskResults: Record<string, unknown>;
+    };
+    internalAgent.context = { on, off };
+
+    const params = {} as TaskParams;
+    Object.defineProperty(params, "outputSchema", {
+      configurable: true,
+      get: () => {
+        throw new Error("output schema trap");
+      },
+    });
+
+    const fakePage = {} as unknown as Page;
+    await expect(agent.executeTaskAsync("test task", params, fakePage)).rejects
+      .toThrow("output schema trap");
+    expect(off).toHaveBeenCalledWith("page", expect.any(Function));
+    expect(Object.keys(internalAgent.tasks)).toHaveLength(0);
+    expect(Object.keys(internalAgent.taskResults)).toHaveLength(0);
+  });
+
+  it("executeTaskAsync cleans up state when runAgentTask throws synchronously", async () => {
+    const mockedRunAgentTask = jest.mocked(runAgentTask);
+    mockedRunAgentTask.mockImplementation(() => {
+      throw new Error("sync run trap");
+    });
+
+    const agent = new HyperAgent({
+      llm: createMockLLM(),
+    });
+    const on = jest.fn();
+    const off = jest.fn();
+    const internalAgent = agent as unknown as {
+      context: {
+        on: typeof on;
+        off: typeof off;
+      } | null;
+      tasks: Record<string, unknown>;
+      taskResults: Record<string, unknown>;
+    };
+    internalAgent.context = { on, off };
+
+    const fakePage = {} as unknown as Page;
+    await expect(agent.executeTaskAsync("test task", undefined, fakePage)).rejects
+      .toThrow("sync run trap");
+    expect(off).toHaveBeenCalledWith("page", expect.any(Function));
+    expect(Object.keys(internalAgent.tasks)).toHaveLength(0);
+    expect(Object.keys(internalAgent.taskResults)).toHaveLength(0);
+  });
+
+  it("executeTaskAsync cleans up listener when task-state registration throws", async () => {
+    const agent = new HyperAgent({
+      llm: createMockLLM(),
+    });
+    const on = jest.fn();
+    const off = jest.fn();
+    const internalAgent = agent as unknown as {
+      context: {
+        on: typeof on;
+        off: typeof off;
+      } | null;
+      tasks: Record<string, unknown>;
+    };
+    internalAgent.context = { on, off };
+    internalAgent.tasks = new Proxy(
+      {},
+      {
+        set: () => {
+          throw new Error("task register trap");
+        },
+      }
+    );
+
+    const fakePage = {} as unknown as Page;
+    await expect(agent.executeTaskAsync("test task", undefined, fakePage)).rejects
+      .toThrow("Failed to register task state");
+    expect(off).toHaveBeenCalledWith("page", expect.any(Function));
+  });
+
+  it("executeTask cleans up listener when task-state registration throws", async () => {
+    const agent = new HyperAgent({
+      llm: createMockLLM(),
+    });
+    const on = jest.fn();
+    const off = jest.fn();
+    const internalAgent = agent as unknown as {
+      context: {
+        on: typeof on;
+        off: typeof off;
+      } | null;
+      tasks: Record<string, unknown>;
+    };
+    internalAgent.context = { on, off };
+    internalAgent.tasks = new Proxy(
+      {},
+      {
+        set: () => {
+          throw new Error("task register trap");
+        },
+      }
+    );
+
+    const fakePage = {} as unknown as Page;
+    await expect(agent.executeTask("test task", undefined, fakePage)).rejects.toThrow(
+      "Failed to register task state"
+    );
+    expect(off).toHaveBeenCalledWith("page", expect.any(Function));
+  });
+
+  it("executeTaskAsync tolerates task-result promise assignment traps", async () => {
+    const mockedRunAgentTask = jest.mocked(runAgentTask);
+    mockedRunAgentTask.mockResolvedValue({
+      taskId: "task-id",
+      status: TaskStatus.COMPLETED,
+      steps: [],
+      output: "done",
+      actionCache: {
+        taskId: "task-id",
+        createdAt: new Date().toISOString(),
+        status: TaskStatus.COMPLETED,
+        steps: [],
+      },
+    });
+
+    const agent = new HyperAgent({
+      llm: createMockLLM(),
+      debug: true,
+    });
+    const warnSpy = jest.spyOn(console, "warn").mockImplementation(() => {});
+    const internalAgent = agent as unknown as {
+      taskResults: Record<string, Promise<AgentTaskOutput>>;
+    };
+    internalAgent.taskResults = new Proxy(
+      {},
+      {
+        set: () => {
+          throw new Error("task result set trap");
+        },
+      }
+    ) as Record<string, Promise<AgentTaskOutput>>;
+
+    const fakePage = {} as unknown as Page;
+    try {
+      const task = await agent.executeTaskAsync("test task", undefined, fakePage);
+      await expect(task.result).resolves.toMatchObject({
+        status: TaskStatus.COMPLETED,
+      });
+      expect(warnSpy).toHaveBeenCalledWith(
+        expect.stringContaining("Failed to track task result promise")
+      );
+    } finally {
+      warnSpy.mockRestore();
+    }
+  });
+
+  it("executeTaskAsync succeeds when task-state reads trap during task-control creation", async () => {
+    const mockedRunAgentTask = jest.mocked(runAgentTask);
+    mockedRunAgentTask.mockResolvedValue({
+      taskId: "task-id",
+      status: TaskStatus.COMPLETED,
+      steps: [],
+      output: "done",
+      actionCache: {
+        taskId: "task-id",
+        createdAt: new Date().toISOString(),
+        status: TaskStatus.COMPLETED,
+        steps: [],
+      },
+    });
+
+    const agent = new HyperAgent({
+      llm: createMockLLM(),
+    });
+    const internalAgent = agent as unknown as {
+      tasks: Record<string, TaskState>;
+    };
+    const taskRegistryStore: Record<string, TaskState> = {};
+    internalAgent.tasks = new Proxy(taskRegistryStore, {
+      set: (target, property, value) => {
+        target[String(property)] = value as TaskState;
+        return true;
+      },
+      get: () => {
+        throw new Error("task get trap");
+      },
+      deleteProperty: (target, property) => {
+        delete target[String(property)];
+        return true;
+      },
+    }) as Record<string, TaskState>;
+
+    const fakePage = {} as unknown as Page;
+    const task = await agent.executeTaskAsync("test task", undefined, fakePage);
+    await expect(task.result).resolves.toMatchObject({
+      status: TaskStatus.COMPLETED,
+    });
+  });
+
+  it("preserves failed async task result when task-state reads trap during error handling", async () => {
+    const mockedRunAgentTask = jest.mocked(runAgentTask);
+    mockedRunAgentTask.mockRejectedValue(new Error("trapped read failure"));
+
+    const agent = new HyperAgent({
+      llm: createMockLLM(),
+      debug: true,
+    });
+    const warnSpy = jest.spyOn(console, "warn").mockImplementation(() => {});
+    const internalAgent = agent as unknown as {
+      tasks: Record<string, TaskState>;
+    };
+    const taskRegistryStore: Record<string, TaskState> = {};
+    internalAgent.tasks = new Proxy(taskRegistryStore, {
+      set: (target, property, value) => {
+        target[String(property)] = value as TaskState;
+        return true;
+      },
+      get: () => {
+        throw new Error("task get trap");
+      },
+      deleteProperty: (target, property) => {
+        delete target[String(property)];
+        return true;
+      },
+    }) as Record<string, TaskState>;
+
+    const fakePage = {} as unknown as Page;
+    try {
+      const task = await agent.executeTaskAsync("test task", undefined, fakePage);
+      await expect(task.result).rejects.toBeInstanceOf(HyperagentTaskError);
+      expect(task.getStatus()).toBe(TaskStatus.FAILED);
+      expect(warnSpy).toHaveBeenCalledWith(
+        expect.stringContaining("Failed to read task state")
+      );
+    } finally {
+      warnSpy.mockRestore();
+    }
+  });
+
+  it("emits and surfaces task-scoped errors from async execution", async () => {
+    const mockedRunAgentTask = jest.mocked(runAgentTask);
+    mockedRunAgentTask.mockRejectedValue(new Error("boom"));
+
+    const agent = new HyperAgent({
+      llm: createMockLLM(),
+    });
+    const fakePage = {} as unknown as Page;
+    const task = await agent.executeTaskAsync("test task", undefined, fakePage);
+    const emittedErrorPromise = new Promise<Error>((resolve) => {
+      task.emitter.once("error", resolve);
+    });
+
+    await expect(task.result).rejects.toBeInstanceOf(HyperagentTaskError);
+    const emittedError = await emittedErrorPromise;
+
+    expect(emittedError).toBeInstanceOf(HyperagentTaskError);
+    expect((emittedError as HyperagentTaskError).taskId).toBe(task.id);
+    expect((emittedError as HyperagentTaskError).cause.message).toBe("boom");
+    const internalAgent = agent as unknown as {
+      tasks: Record<string, unknown>;
+      taskResults: Record<string, unknown>;
+    };
+    expect(Object.keys(internalAgent.tasks)).toHaveLength(0);
+    expect(Object.keys(internalAgent.taskResults)).toHaveLength(0);
+  });
+
+  it("isolates task-scoped emitters across concurrent tasks", async () => {
+    const mockedRunAgentTask = jest.mocked(runAgentTask);
+    let resolveSecondTask!: (value: AgentTaskOutput) => void;
+    mockedRunAgentTask.mockImplementation((_, state) => {
+      if (state.task === "first task") {
+        return Promise.reject(new Error("first task failure"));
+      }
+      return new Promise<AgentTaskOutput>((resolve) => {
+        resolveSecondTask = resolve;
+      });
+    });
+
+    const agent = new HyperAgent({
+      llm: createMockLLM(),
+    });
+    const fakePage = {} as unknown as Page;
+    const firstTask = await agent.executeTaskAsync(
+      "first task",
+      undefined,
+      fakePage
+    );
+    const secondTask = await agent.executeTaskAsync(
+      "second task",
+      undefined,
+      fakePage
+    );
+    const secondErrorSpy = jest.fn();
+    secondTask.emitter.on("error", secondErrorSpy);
+
+    await expect(firstTask.result).rejects.toBeInstanceOf(HyperagentTaskError);
+    expect(secondErrorSpy).not.toHaveBeenCalled();
+
+    resolveSecondTask({
+      taskId: secondTask.id,
+      status: TaskStatus.COMPLETED,
+      steps: [],
+      output: "done",
+      actionCache: {
+        taskId: secondTask.id,
+        createdAt: new Date().toISOString(),
+        status: TaskStatus.COMPLETED,
+        steps: [],
+      },
+    });
+    await expect(secondTask.result).resolves.toMatchObject({
+      status: TaskStatus.COMPLETED,
+    });
+  });
+
+  it("removes task-scoped error forwarding listeners after task settles", async () => {
+    const mockedRunAgentTask = jest.mocked(runAgentTask);
+    let resolveTask!: (value: AgentTaskOutput) => void;
+    mockedRunAgentTask.mockImplementation(
+      () =>
+        new Promise<AgentTaskOutput>((resolve) => {
+          resolveTask = resolve;
+        })
+    );
+
+    const agent = new HyperAgent({
+      llm: createMockLLM(),
+    });
+    const internalAgent = agent as unknown as {
+      errorEmitter: { listenerCount: (event: string) => number };
+    };
+    const fakePage = {} as unknown as Page;
+    const task = await agent.executeTaskAsync("listener cleanup", undefined, fakePage);
+    expect(internalAgent.errorEmitter.listenerCount("error")).toBeGreaterThan(0);
+
+    resolveTask({
+      taskId: task.id,
+      status: TaskStatus.COMPLETED,
+      steps: [],
+      output: "done",
+      actionCache: {
+        taskId: task.id,
+        createdAt: new Date().toISOString(),
+        status: TaskStatus.COMPLETED,
+        steps: [],
+      },
+    });
+    await expect(task.result).resolves.toMatchObject({
+      status: TaskStatus.COMPLETED,
+    });
+    await Promise.resolve();
+    expect(internalAgent.errorEmitter.listenerCount("error")).toBe(0);
+  });
+
+  it("closeAgent removes task-scoped error forwarders for in-flight tasks", async () => {
+    const mockedRunAgentTask = jest.mocked(runAgentTask);
+    mockedRunAgentTask.mockImplementation(
+      () => new Promise<AgentTaskOutput>(() => undefined)
+    );
+
+    const agent = new HyperAgent({
+      llm: createMockLLM(),
+    });
+    const internalAgent = agent as unknown as {
+      errorEmitter: { listenerCount: (event: string) => number };
+    };
+    const fakePage = {} as unknown as Page;
+    await agent.executeTaskAsync("never settles", undefined, fakePage);
+    expect(internalAgent.errorEmitter.listenerCount("error")).toBeGreaterThan(0);
+
+    await expect(agent.closeAgent()).resolves.toBeUndefined();
+    expect(internalAgent.errorEmitter.listenerCount("error")).toBe(0);
+  });
+
+  it("falls back to removeListener when errorEmitter.off getter traps during task cleanup", async () => {
+    const mockedRunAgentTask = jest.mocked(runAgentTask);
+    let resolveTask!: (value: AgentTaskOutput) => void;
+    mockedRunAgentTask.mockImplementation(
+      () =>
+        new Promise<AgentTaskOutput>((resolve) => {
+          resolveTask = resolve;
+        })
+    );
+
+    const agent = new HyperAgent({
+      llm: createMockLLM(),
+    });
+    const internalAgent = agent as unknown as {
+      errorEmitter: {
+        listenerCount: (event: string) => number;
+      };
+      taskErrorForwarders: Map<string, (error: Error) => void>;
+    };
+    const baseEmitter = internalAgent.errorEmitter;
+    internalAgent.errorEmitter = new Proxy(baseEmitter as object, {
+      get: (target, property, receiver) => {
+        if (property === "off") {
+          throw new Error("errorEmitter off getter trap");
+        }
+        const value = Reflect.get(target, property, receiver);
+        if (typeof value === "function") {
+          return value.bind(target);
+        }
+        return value;
+      },
+    }) as unknown as typeof internalAgent.errorEmitter;
+
+    const fakePage = {} as unknown as Page;
+    const task = await agent.executeTaskAsync(
+      "listener cleanup fallback",
+      undefined,
+      fakePage
+    );
+    expect(internalAgent.errorEmitter.listenerCount("error")).toBeGreaterThan(0);
+
+    resolveTask({
+      taskId: task.id,
+      status: TaskStatus.COMPLETED,
+      steps: [],
+      output: "done",
+      actionCache: {
+        taskId: task.id,
+        createdAt: new Date().toISOString(),
+        status: TaskStatus.COMPLETED,
+        steps: [],
+      },
+    });
+    await expect(task.result).resolves.toMatchObject({
+      status: TaskStatus.COMPLETED,
+    });
+    await Promise.resolve();
+    expect(internalAgent.taskErrorForwarders.size).toBe(0);
+    expect(internalAgent.errorEmitter.listenerCount("error")).toBe(0);
+  });
+
+  it("avoids task error-listener leaks when forwarder registry set traps throw", async () => {
+    const mockedRunAgentTask = jest.mocked(runAgentTask);
+    mockedRunAgentTask.mockImplementation(
+      () => new Promise<AgentTaskOutput>(() => undefined)
+    );
+
+    const agent = new HyperAgent({
+      llm: createMockLLM(),
+      debug: true,
+    });
+    const warnSpy = jest.spyOn(console, "warn").mockImplementation(() => {});
+    const internalAgent = agent as unknown as {
+      errorEmitter: { listenerCount: (event: string) => number };
+      taskErrorForwarders: Map<string, (error: Error) => void>;
+    };
+    const forwarders = new Proxy(new Map<string, (error: Error) => void>(), {
+      get: (target, property, receiver) => {
+        if (property === "set") {
+          return () => {
+            throw new Error("forwarder set trap");
+          };
+        }
+        const value = Reflect.get(target, property, receiver);
+        if (typeof value === "function") {
+          return value.bind(target);
+        }
+        return value;
+      },
+    });
+    internalAgent.taskErrorForwarders =
+      forwarders as unknown as Map<string, (error: Error) => void>;
+
+    const fakePage = {} as unknown as Page;
+    try {
+      await agent.executeTaskAsync("forwarder trap", undefined, fakePage);
+      expect(internalAgent.errorEmitter.listenerCount("error")).toBe(0);
+      expect(warnSpy).toHaveBeenCalledWith(
+        expect.stringContaining("Failed to register task-scoped error listener")
+      );
+    } finally {
+      warnSpy.mockRestore();
+    }
+  });
+
+  it("falls back to addListener when errorEmitter.on getter traps during task registration", async () => {
+    const mockedRunAgentTask = jest.mocked(runAgentTask);
+    let resolveTask!: (value: AgentTaskOutput) => void;
+    mockedRunAgentTask.mockImplementation(
+      () =>
+        new Promise<AgentTaskOutput>((resolve) => {
+          resolveTask = resolve;
+        })
+    );
+
+    const agent = new HyperAgent({
+      llm: createMockLLM(),
+      debug: true,
+    });
+    const warnSpy = jest.spyOn(console, "warn").mockImplementation(() => {});
+    const internalAgent = agent as unknown as {
+      errorEmitter: {
+        listenerCount: (event: string) => number;
+      };
+      taskErrorForwarders: Map<string, (error: Error) => void>;
+    };
+    const baseEmitter = internalAgent.errorEmitter;
+    internalAgent.errorEmitter = new Proxy(baseEmitter as object, {
+      get: (target, property, receiver) => {
+        if (property === "on") {
+          throw new Error("errorEmitter on getter trap");
+        }
+        const value = Reflect.get(target, property, receiver);
+        if (typeof value === "function") {
+          return value.bind(target);
+        }
+        return value;
+      },
+    }) as unknown as typeof internalAgent.errorEmitter;
+
+    const fakePage = {} as unknown as Page;
+    try {
+      const task = await agent.executeTaskAsync(
+        "on getter fallback task",
+        undefined,
+        fakePage
+      );
+      expect(internalAgent.errorEmitter.listenerCount("error")).toBeGreaterThan(0);
+
+      resolveTask({
+        taskId: task.id,
+        status: TaskStatus.COMPLETED,
+        steps: [],
+        output: "done",
+        actionCache: {
+          taskId: task.id,
+          createdAt: new Date().toISOString(),
+          status: TaskStatus.COMPLETED,
+          steps: [],
+        },
+      });
+      await expect(task.result).resolves.toMatchObject({
+        status: TaskStatus.COMPLETED,
+      });
+      await Promise.resolve();
+      expect(internalAgent.taskErrorForwarders.size).toBe(0);
+      expect(internalAgent.errorEmitter.listenerCount("error")).toBe(0);
+      expect(
+        warnSpy.mock.calls.some((call) =>
+          String(call[0] ?? "").includes(
+            "Failed to register task-scoped error listener"
+          )
+        )
+      ).toBe(false);
+    } finally {
+      warnSpy.mockRestore();
+    }
+  });
+
+  it("continues async task execution when errorEmitter.on/addListener getters trap", async () => {
+    const mockedRunAgentTask = jest.mocked(runAgentTask);
+    mockedRunAgentTask.mockImplementation(async (_, state) => ({
+      taskId: state.id,
+      status: TaskStatus.COMPLETED,
+      steps: [],
+      output: "done",
+      actionCache: {
+        taskId: state.id,
+        createdAt: new Date().toISOString(),
+        status: TaskStatus.COMPLETED,
+        steps: [],
+      },
+    }));
+
+    const agent = new HyperAgent({
+      llm: createMockLLM(),
+      debug: true,
+    });
+    const warnSpy = jest.spyOn(console, "warn").mockImplementation(() => {});
+    const internalAgent = agent as unknown as {
+      errorEmitter: {
+        listenerCount: (event: string) => number;
+      };
+      taskErrorForwarders: Map<string, (error: Error) => void>;
+    };
+    const baseEmitter = internalAgent.errorEmitter;
+    internalAgent.errorEmitter = new Proxy(baseEmitter as object, {
+      get: (target, property, receiver) => {
+        if (property === "on" || property === "addListener") {
+          throw new Error(`errorEmitter on trap\u0000\n${"x".repeat(10_000)}`);
+        }
+        const value = Reflect.get(target, property, receiver);
+        if (typeof value === "function") {
+          return value.bind(target);
+        }
+        return value;
+      },
+    }) as unknown as typeof internalAgent.errorEmitter;
+
+    const fakePage = {} as unknown as Page;
+    try {
+      const task = await agent.executeTaskAsync(
+        "on getter trap task",
+        undefined,
+        fakePage
+      );
+      await expect(task.result).resolves.toMatchObject({
+        status: TaskStatus.COMPLETED,
+      });
+      expect(internalAgent.taskErrorForwarders.size).toBe(0);
+
+      const warningLine = warnSpy.mock.calls
+        .map((call) => String(call[0] ?? ""))
+        .find((line) =>
+          line.includes("Failed to register task-scoped error listener")
+        );
+      expect(warningLine).toBeDefined();
+      expect(warningLine).toContain("[truncated");
+      expect(warningLine).not.toContain("\u0000");
+      expect(warningLine).not.toContain("\n");
+    } finally {
+      warnSpy.mockRestore();
+    }
+  });
+
+  it("surfaces HyperagentTaskError without requiring error listeners", async () => {
+    const mockedRunAgentTask = jest.mocked(runAgentTask);
+    mockedRunAgentTask.mockRejectedValue(new Error("boom without listeners"));
+
+    const agent = new HyperAgent({
+      llm: createMockLLM(),
+    });
+    const fakePage = {} as unknown as Page;
+    const task = await agent.executeTaskAsync("test task", undefined, fakePage);
+
+    await expect(task.result).rejects.toBeInstanceOf(HyperagentTaskError);
+  });
+
+  it("cancel does not override terminal failed task status", async () => {
+    const mockedRunAgentTask = jest.mocked(runAgentTask);
+    mockedRunAgentTask.mockRejectedValue(new Error("boom"));
+
+    const agent = new HyperAgent({
+      llm: createMockLLM(),
+    });
+    const fakePage = {} as unknown as Page;
+    const task = await agent.executeTaskAsync("test task", undefined, fakePage);
+
+    await expect(task.result).rejects.toBeInstanceOf(HyperagentTaskError);
+    expect(task.getStatus()).toBe(TaskStatus.FAILED);
+    expect(task.cancel()).toBe(TaskStatus.FAILED);
+    expect(task.getStatus()).toBe(TaskStatus.FAILED);
+  });
+
+  it("serializes non-Error async task failures with readable cause", async () => {
+    const mockedRunAgentTask = jest.mocked(runAgentTask);
+    mockedRunAgentTask.mockRejectedValue({ reason: "object boom" });
+
+    const agent = new HyperAgent({
+      llm: createMockLLM(),
+    });
+    const fakePage = {} as unknown as Page;
+    const task = await agent.executeTaskAsync("test task", undefined, fakePage);
+    const emittedErrorPromise = new Promise<Error>((resolve) => {
+      task.emitter.once("error", resolve);
+    });
+
+    await expect(task.result).rejects.toBeInstanceOf(HyperagentTaskError);
+    const emittedError = await emittedErrorPromise;
+
+    expect(emittedError).toBeInstanceOf(HyperagentTaskError);
+    expect((emittedError as HyperagentTaskError).taskId).toBe(task.id);
+    expect((emittedError as HyperagentTaskError).cause.message).toBe(
+      '{"reason":"object boom"}'
+    );
+  });
+
+  it("truncates oversized non-Error async task failures", async () => {
+    const mockedRunAgentTask = jest.mocked(runAgentTask);
+    mockedRunAgentTask.mockRejectedValue({
+      reason: "x".repeat(2_000),
+    });
+
+    const agent = new HyperAgent({
+      llm: createMockLLM(),
+    });
+    const fakePage = {} as unknown as Page;
+    const task = await agent.executeTaskAsync("test task", undefined, fakePage);
+    const emittedErrorPromise = new Promise<Error>((resolve) => {
+      task.emitter.once("error", resolve);
+    });
+
+    await expect(task.result).rejects.toBeInstanceOf(HyperagentTaskError);
+    const emittedError = await emittedErrorPromise;
+    expect((emittedError as HyperagentTaskError).cause.message).toContain(
+      "[truncated"
+    );
+  });
+
+  it("serializes non-Error sync task failures with readable cause", async () => {
+    const mockedRunAgentTask = jest.mocked(runAgentTask);
+    mockedRunAgentTask.mockRejectedValue({ reason: "sync object boom" });
+
+    const agent = new HyperAgent({
+      llm: createMockLLM(),
+    });
+    const fakePage = {} as unknown as Page;
+
+    await expect(agent.executeTask("sync task", undefined, fakePage)).rejects.toThrow(
+      '{"reason":"sync object boom"}'
+    );
+  });
+
+  it("preserves cancelled status when async task rejects after cancel", async () => {
+    const mockedRunAgentTask = jest.mocked(runAgentTask);
+    let rejectTask!: (error: unknown) => void;
+    mockedRunAgentTask.mockImplementation(
+      () =>
+        new Promise<AgentTaskOutput>((_, reject) => {
+          rejectTask = reject;
+        })
+    );
+
+    const agent = new HyperAgent({
+      llm: createMockLLM(),
+    });
+    const fakePage = {} as unknown as Page;
+    const task = await agent.executeTaskAsync("cancel me", undefined, fakePage);
+    const emitterSpy = jest.spyOn(task.emitter, "emit");
+
+    expect(task.cancel()).toBe(TaskStatus.CANCELLED);
+    rejectTask(new Error("async cancel rejection"));
+
+    await expect(task.result).resolves.toMatchObject({
+      status: TaskStatus.CANCELLED,
+      output: "Task was cancelled",
+      actionCache: { status: TaskStatus.CANCELLED },
+    });
+    expect(task.getStatus()).toBe(TaskStatus.CANCELLED);
+    expect(emitterSpy).not.toHaveBeenCalledWith(
+      "error",
+      expect.any(HyperagentTaskError)
+    );
+  });
+
+  it("preserves cancelled status when executeTask rejects after external cancellation", async () => {
+    const mockedRunAgentTask = jest.mocked(runAgentTask);
+    let rejectTask!: (error: unknown) => void;
+    mockedRunAgentTask.mockImplementation(
+      () =>
+        new Promise<AgentTaskOutput>((_, reject) => {
+          rejectTask = reject;
+        })
+    );
+
+    const agent = new HyperAgent({
+      llm: createMockLLM(),
+    });
+    const fakePage = {} as unknown as Page;
+    const execution = agent.executeTask("sync cancel", undefined, fakePage);
+    const internalAgent = agent as unknown as {
+      tasks: Record<string, TaskState>;
+    };
+    const activeTaskState = Object.values(internalAgent.tasks)[0];
+    expect(activeTaskState).toBeDefined();
+    activeTaskState.status = TaskStatus.CANCELLED;
+
+    rejectTask(new Error("sync cancel rejection"));
+
+    await expect(execution).resolves.toMatchObject({
+      status: TaskStatus.CANCELLED,
+      output: "Task was cancelled",
+      actionCache: { status: TaskStatus.CANCELLED },
+    });
+    expect(activeTaskState.status).toBe(TaskStatus.CANCELLED);
+  });
+
+  it("returns cancelled output when async task resolves after manual cancel", async () => {
+    const mockedRunAgentTask = jest.mocked(runAgentTask);
+    let resolveTask!: (value: AgentTaskOutput) => void;
+    mockedRunAgentTask.mockImplementation(
+      () =>
+        new Promise<AgentTaskOutput>((resolve) => {
+          resolveTask = resolve;
+        })
+    );
+
+    const agent = new HyperAgent({
+      llm: createMockLLM(),
+    });
+    const fakePage = {} as unknown as Page;
+    const task = await agent.executeTaskAsync("cancel me", undefined, fakePage);
+
+    expect(task.cancel()).toBe(TaskStatus.CANCELLED);
+    resolveTask({
+      taskId: task.id,
+      status: TaskStatus.COMPLETED,
+      steps: [],
+      output: "done",
+      actionCache: {
+        taskId: task.id,
+        createdAt: new Date().toISOString(),
+        status: TaskStatus.COMPLETED,
+        steps: [],
+      },
+    });
+
+    await expect(task.result).resolves.toMatchObject({
+      status: TaskStatus.CANCELLED,
+      output: "Task was cancelled",
+      actionCache: { status: TaskStatus.CANCELLED },
+    });
+  });
+
+  it("returns cancelled output when sync task resolves after manual cancellation", async () => {
+    const mockedRunAgentTask = jest.mocked(runAgentTask);
+    let resolveTask!: (value: AgentTaskOutput) => void;
+    mockedRunAgentTask.mockImplementation(
+      () =>
+        new Promise<AgentTaskOutput>((resolve) => {
+          resolveTask = resolve;
+        })
+    );
+
+    const agent = new HyperAgent({
+      llm: createMockLLM(),
+    });
+    const fakePage = {} as unknown as Page;
+    const execution = agent.executeTask("sync cancel", undefined, fakePage);
+    const internalAgent = agent as unknown as {
+      tasks: Record<string, TaskState>;
+    };
+    const activeTaskState = Object.values(internalAgent.tasks)[0];
+    expect(activeTaskState).toBeDefined();
+    activeTaskState.status = TaskStatus.CANCELLED;
+
+    resolveTask({
+      taskId: "sync-cancel",
+      status: TaskStatus.COMPLETED,
+      steps: [],
+      output: "done",
+      actionCache: {
+        taskId: "sync-cancel",
+        createdAt: new Date().toISOString(),
+        status: TaskStatus.COMPLETED,
+        steps: [],
+      },
+    });
+
+    await expect(execution).resolves.toMatchObject({
+      status: TaskStatus.CANCELLED,
+      output: "Task was cancelled",
+      actionCache: { status: TaskStatus.CANCELLED },
+    });
+  });
+
+  it("cleans internal task state after synchronous executeTask completion", async () => {
+    const mockedRunAgentTask = jest.mocked(runAgentTask);
+    mockedRunAgentTask.mockResolvedValue({
+      taskId: "task-id",
+      status: TaskStatus.COMPLETED,
+      steps: [],
+      output: "done",
+      actionCache: {
+        taskId: "task-id",
+        createdAt: new Date().toISOString(),
+        status: TaskStatus.COMPLETED,
+        steps: [],
+      },
+    });
+
+    const agent = new HyperAgent({
+      llm: createMockLLM(),
+    });
+    const fakePage = {} as unknown as Page;
+
+    await agent.executeTask("sync task", undefined, fakePage);
+
+    const internalAgent = agent as unknown as {
+      tasks: Record<string, unknown>;
+    };
+    expect(Object.keys(internalAgent.tasks)).toHaveLength(0);
+  });
+
+  it("executeTaskAsync succeeds when action-cache assignment traps throw", async () => {
+    const mockedRunAgentTask = jest.mocked(runAgentTask);
+    mockedRunAgentTask.mockResolvedValue({
+      taskId: "task-id",
+      status: TaskStatus.COMPLETED,
+      steps: [],
+      output: "done",
+      actionCache: {
+        taskId: "task-id",
+        createdAt: new Date().toISOString(),
+        status: TaskStatus.COMPLETED,
+        steps: [],
+      },
+    });
+
+    const agent = new HyperAgent({
+      llm: createMockLLM(),
+      debug: true,
+    });
+    const warnSpy = jest.spyOn(console, "warn").mockImplementation(() => {});
+    const internalAgent = agent as unknown as {
+      actionCacheByTaskId: Record<string, unknown>;
+    };
+    internalAgent.actionCacheByTaskId = new Proxy(
+      {},
+      {
+        set: () => {
+          throw new Error("cache set trap");
+        },
+      }
+    );
+
+    const fakePage = {} as unknown as Page;
+    try {
+      const task = await agent.executeTaskAsync("test task", undefined, fakePage);
+      await expect(task.result).resolves.toMatchObject({
+        status: TaskStatus.COMPLETED,
+      });
+      expect(warnSpy).toHaveBeenCalledWith(
+        expect.stringContaining("Failed to store action cache")
+      );
+    } finally {
+      warnSpy.mockRestore();
+    }
+  });
+
+  it("executeTask succeeds when action-cache assignment traps throw", async () => {
+    const mockedRunAgentTask = jest.mocked(runAgentTask);
+    mockedRunAgentTask.mockResolvedValue({
+      taskId: "task-id",
+      status: TaskStatus.COMPLETED,
+      steps: [],
+      output: "done",
+      actionCache: {
+        taskId: "task-id",
+        createdAt: new Date().toISOString(),
+        status: TaskStatus.COMPLETED,
+        steps: [],
+      },
+    });
+
+    const agent = new HyperAgent({
+      llm: createMockLLM(),
+      debug: true,
+    });
+    const warnSpy = jest.spyOn(console, "warn").mockImplementation(() => {});
+    const internalAgent = agent as unknown as {
+      actionCacheByTaskId: Record<string, unknown>;
+    };
+    internalAgent.actionCacheByTaskId = new Proxy(
+      {},
+      {
+        set: () => {
+          throw new Error("cache set trap");
+        },
+      }
+    );
+
+    const fakePage = {} as unknown as Page;
+    try {
+      await expect(agent.executeTask("sync task", undefined, fakePage)).resolves
+        .toMatchObject({
+          status: TaskStatus.COMPLETED,
+        });
+      expect(warnSpy).toHaveBeenCalledWith(
+        expect.stringContaining("Failed to store action cache")
+      );
+    } finally {
+      warnSpy.mockRestore();
+    }
+  });
+
+  it("executeTaskAsync succeeds when action-cache order access traps throw", async () => {
+    const mockedRunAgentTask = jest.mocked(runAgentTask);
+    mockedRunAgentTask.mockResolvedValue({
+      taskId: "task-id",
+      status: TaskStatus.COMPLETED,
+      steps: [],
+      output: "done",
+      actionCache: {
+        taskId: "task-id",
+        createdAt: new Date().toISOString(),
+        status: TaskStatus.COMPLETED,
+        steps: [],
+      },
+    });
+
+    const agent = new HyperAgent({
+      llm: createMockLLM(),
+      debug: true,
+    });
+    const warnSpy = jest.spyOn(console, "warn").mockImplementation(() => {});
+    const internalAgent = agent as unknown as {
+      actionCacheTaskOrder: string[];
+    };
+    Object.defineProperty(internalAgent, "actionCacheTaskOrder", {
+      configurable: true,
+      get: () => {
+        throw new Error("cache order get trap");
+      },
+      set: () => {
+        throw new Error("cache order set trap");
+      },
+    });
+
+    const fakePage = {} as unknown as Page;
+    try {
+      const task = await agent.executeTaskAsync("test task", undefined, fakePage);
+      await expect(task.result).resolves.toMatchObject({
+        status: TaskStatus.COMPLETED,
+      });
+      expect(warnSpy).toHaveBeenCalledWith(
+        expect.stringContaining("Failed to update action-cache order")
+      );
+    } finally {
+      warnSpy.mockRestore();
+    }
+  });
+
+  it("executeTask succeeds when action-cache order access traps throw", async () => {
+    const mockedRunAgentTask = jest.mocked(runAgentTask);
+    mockedRunAgentTask.mockResolvedValue({
+      taskId: "task-id",
+      status: TaskStatus.COMPLETED,
+      steps: [],
+      output: "done",
+      actionCache: {
+        taskId: "task-id",
+        createdAt: new Date().toISOString(),
+        status: TaskStatus.COMPLETED,
+        steps: [],
+      },
+    });
+
+    const agent = new HyperAgent({
+      llm: createMockLLM(),
+      debug: true,
+    });
+    const warnSpy = jest.spyOn(console, "warn").mockImplementation(() => {});
+    const internalAgent = agent as unknown as {
+      actionCacheTaskOrder: string[];
+    };
+    Object.defineProperty(internalAgent, "actionCacheTaskOrder", {
+      configurable: true,
+      get: () => {
+        throw new Error("cache order get trap");
+      },
+      set: () => {
+        throw new Error("cache order set trap");
+      },
+    });
+
+    const fakePage = {} as unknown as Page;
+    try {
+      await expect(agent.executeTask("sync task", undefined, fakePage)).resolves
+        .toMatchObject({
+          status: TaskStatus.COMPLETED,
+        });
+      expect(warnSpy).toHaveBeenCalledWith(
+        expect.stringContaining("Failed to update action-cache order")
+      );
+    } finally {
+      warnSpy.mockRestore();
+    }
+  });
+
+  it("evicts oldest action caches when cache history exceeds limit", async () => {
+    const mockedRunAgentTask = jest.mocked(runAgentTask);
+    mockedRunAgentTask.mockImplementation((_, taskState) =>
+      Promise.resolve({
+        taskId: taskState.id,
+        status: TaskStatus.COMPLETED,
+        steps: [],
+        output: "done",
+        actionCache: {
+          taskId: taskState.id,
+          createdAt: new Date().toISOString(),
+          status: TaskStatus.COMPLETED,
+          steps: [],
+        },
+      })
+    );
+
+    const maxEntries = (
+      HyperAgent as unknown as { MAX_ACTION_CACHE_ENTRIES: number }
+    ).MAX_ACTION_CACHE_ENTRIES;
+    const taskCount = maxEntries + 2;
+    const agent = new HyperAgent({
+      llm: createMockLLM(),
+    });
+    const fakePage = {} as unknown as Page;
+    const taskIds: string[] = [];
+
+    for (let i = 0; i < taskCount; i++) {
+      const task = await agent.executeTaskAsync(
+        `cache task ${i}`,
+        undefined,
+        fakePage
+      );
+      taskIds.push(task.id);
+      await task.result;
+    }
+
+    expect(agent.getActionCache(taskIds[0] ?? "")).toBeNull();
+    expect(agent.getActionCache(taskIds[1] ?? "")).toBeNull();
+    const latestTaskId = taskIds[taskIds.length - 1] ?? "";
+    expect(agent.getActionCache(latestTaskId)).not.toBeNull();
+  });
+
+  it("executeTaskAsync tolerates task-lifecycle cleanup deletion traps", async () => {
+    const mockedRunAgentTask = jest.mocked(runAgentTask);
+    mockedRunAgentTask.mockResolvedValue({
+      taskId: "task-id",
+      status: TaskStatus.COMPLETED,
+      steps: [],
+      output: "done",
+      actionCache: {
+        taskId: "task-id",
+        createdAt: new Date().toISOString(),
+        status: TaskStatus.COMPLETED,
+        steps: [],
+      },
+    });
+
+    const agent = new HyperAgent({
+      llm: createMockLLM(),
+      debug: true,
+    });
+    const warnSpy = jest.spyOn(console, "warn").mockImplementation(() => {});
+    const internalAgent = agent as unknown as {
+      taskResults: Record<string, Promise<AgentTaskOutput>>;
+      tasks: Record<string, unknown>;
+    };
+    internalAgent.taskResults = new Proxy(
+      {},
+      {
+        deleteProperty: () => {
+          throw new Error("taskResults delete trap");
+        },
+      }
+    ) as Record<string, Promise<AgentTaskOutput>>;
+    internalAgent.tasks = new Proxy(
+      {},
+      {
+        deleteProperty: () => {
+          throw new Error("tasks delete trap");
+        },
+      }
+    );
+
+    const fakePage = {} as unknown as Page;
+    try {
+      const task = await agent.executeTaskAsync("test task", undefined, fakePage);
+      await expect(task.result).resolves.toMatchObject({
+        status: TaskStatus.COMPLETED,
+      });
+      expect(warnSpy).toHaveBeenCalledWith(
+        expect.stringContaining("Failed to clear task result")
+      );
+      expect(warnSpy).toHaveBeenCalledWith(
+        expect.stringContaining("Failed to clear task state")
+      );
+    } finally {
+      warnSpy.mockRestore();
+    }
+  });
+
+  it("executeTask tolerates task-state cleanup deletion traps", async () => {
+    const mockedRunAgentTask = jest.mocked(runAgentTask);
+    mockedRunAgentTask.mockResolvedValue({
+      taskId: "task-id",
+      status: TaskStatus.COMPLETED,
+      steps: [],
+      output: "done",
+      actionCache: {
+        taskId: "task-id",
+        createdAt: new Date().toISOString(),
+        status: TaskStatus.COMPLETED,
+        steps: [],
+      },
+    });
+
+    const agent = new HyperAgent({
+      llm: createMockLLM(),
+      debug: true,
+    });
+    const warnSpy = jest.spyOn(console, "warn").mockImplementation(() => {});
+    const internalAgent = agent as unknown as {
+      tasks: Record<string, unknown>;
+    };
+    internalAgent.tasks = new Proxy(
+      {},
+      {
+        deleteProperty: () => {
+          throw new Error("tasks delete trap");
+        },
+      }
+    );
+
+    const fakePage = {} as unknown as Page;
+    try {
+      await expect(agent.executeTask("sync task", undefined, fakePage)).resolves
+        .toMatchObject({
+          status: TaskStatus.COMPLETED,
+        });
+      expect(warnSpy).toHaveBeenCalledWith(
+        expect.stringContaining("Failed to clear task state")
+      );
+    } finally {
+      warnSpy.mockRestore();
+    }
+  });
+
+  it("returns variable snapshots without exposing internal mutable store", () => {
+    const agent = new HyperAgent({
+      llm: createMockLLM(),
+    });
+    agent.addVariable({
+      key: "email",
+      value: "person@example.com",
+      description: "Email",
+    });
+
+    const variables = agent.getVariables();
+    variables.email = {
+      key: "email",
+      value: "mutated@example.com",
+      description: "mutated",
+    };
+
+    expect(agent.getVariable("email")?.value).toBe("person@example.com");
+  });
+
+  it("rejects variables with invalid keys", () => {
+    const agent = new HyperAgent({
+      llm: createMockLLM(),
+    });
+
+    expect(() =>
+      agent.addVariable({
+        key: "   ",
+        value: "value",
+        description: "desc",
+      })
+    ).toThrow("Variable key must be a non-empty string");
+  });
+
+  it("truncates oversized variable-set diagnostics", () => {
+    const agent = new HyperAgent({
+      llm: createMockLLM(),
+    });
+    const internalAgent = agent as unknown as {
+      _variables: Record<string, unknown>;
+    };
+    internalAgent._variables = new Proxy(
+      {},
+      {
+        set: () => {
+          throw new Error("x".repeat(2_000));
+        },
+      }
+    );
+
+    expect(() =>
+      agent.addVariable({
+        key: "email",
+        value: "person@example.com",
+        description: "Email",
+      })
+    ).toThrow(/\[truncated/);
+  });
+
+  it("returns null action cache for invalid cache identifiers", () => {
+    const agent = new HyperAgent({
+      llm: createMockLLM(),
+    });
+
+    const result = agent.getActionCache("   ");
+    expect(result).toBeNull();
+  });
+
+  it("returns empty cache steps when cache step iteration traps throw", () => {
+    const agent = new HyperAgent({
+      llm: createMockLLM(),
+    });
+    const internalAgent = agent as unknown as {
+      actionCacheByTaskId: Record<string, unknown>;
+    };
+    internalAgent.actionCacheByTaskId["task-id"] = {
+      taskId: "task-id",
+      createdAt: new Date().toISOString(),
+      status: TaskStatus.COMPLETED,
+      steps: new Proxy(
+        [],
+        {
+          get: (target, prop, receiver) => {
+            if (prop === Symbol.iterator) {
+              throw new Error("steps iterator trap");
+            }
+            return Reflect.get(target, prop, receiver);
+          },
+        }
+      ),
+    };
+
+    const cache = agent.getActionCache("task-id");
+    expect(cache?.steps).toEqual([]);
+  });
+
+  it("returns null when cached action-cache entry is not an object", () => {
+    const agent = new HyperAgent({
+      llm: createMockLLM(),
+    });
+    const internalAgent = agent as unknown as {
+      actionCacheByTaskId: Record<string, unknown>;
+    };
+    internalAgent.actionCacheByTaskId["task-id"] = 42;
+
+    expect(agent.getActionCache("task-id")).toBeNull();
+  });
+
+  it("normalizes trap-prone cache metadata fields safely", () => {
+    const agent = new HyperAgent({
+      llm: createMockLLM(),
+    });
+    const internalAgent = agent as unknown as {
+      actionCacheByTaskId: Record<string, unknown>;
+    };
+    internalAgent.actionCacheByTaskId["task-id"] = {
+      get taskId(): string {
+        throw new Error("taskId trap");
+      },
+      get createdAt(): string {
+        throw new Error("createdAt trap");
+      },
+      get status(): TaskStatus {
+        throw new Error("status trap");
+      },
+      steps: [],
+    };
+
+    const cache = agent.getActionCache("task-id");
+
+    expect(cache?.taskId).toBe("task-id");
+    expect(cache?.createdAt).toBe("1970-01-01T00:00:00.000Z");
+    expect(cache?.status).toBeUndefined();
+    expect(cache?.steps).toEqual([]);
+  });
+
+  it("surfaces readable errors when getPages cannot enumerate context pages", async () => {
+    const agent = new HyperAgent({
+      llm: createMockLLM(),
+    });
+    const internalAgent = agent as unknown as {
+      browser: object | null;
+      context: { pages: () => Page[] } | null;
+    };
+    internalAgent.browser = {};
+    internalAgent.context = {
+      pages: () => {
+        throw new Error("pages trap");
+      },
+    };
+
+    await expect(agent.getPages()).rejects.toThrow(
+      "Failed to list pages from context: pages trap"
+    );
+  });
+
+  it("truncates oversized getPages context diagnostics", async () => {
+    const agent = new HyperAgent({
+      llm: createMockLLM(),
+    });
+    const internalAgent = agent as unknown as {
+      browser: object | null;
+      context: { pages: () => Page[] } | null;
+    };
+    internalAgent.browser = {};
+    internalAgent.context = {
+      pages: () => {
+        throw new Error("x".repeat(2_000));
+      },
+    };
+
+    await expect(agent.getPages()).rejects.toThrow(/\[truncated/);
+  });
+
+  it("surfaces readable diagnostics when context.pages getter traps", async () => {
+    const agent = new HyperAgent({
+      llm: createMockLLM(),
+    });
+    const internalAgent = agent as unknown as {
+      browser: object | null;
+      context: unknown;
+    };
+    internalAgent.browser = {};
+    internalAgent.context = new Proxy(
+      {},
+      {
+        get: (_target, prop) => {
+          if (prop === "pages") {
+            throw new Error("pages getter trap");
+          }
+          return undefined;
+        },
+      }
+    );
+
+    await expect(agent.getPages()).rejects.toThrow(
+      "Failed to list pages from context: failed to read context.pages: pages getter trap"
+    );
+  });
+
+  it("returns readable pages when context page entries are partially trap-prone", async () => {
+    let goodPage: Page;
+    const contextOn = jest.fn();
+    const contextOff = jest.fn();
+    const pageOn = jest.fn();
+    const pageOff = jest.fn();
+    goodPage = {
+      on: pageOn,
+      off: pageOff,
+      context: () => ({
+        on: contextOn,
+        off: contextOff,
+        pages: () => [goodPage],
+      }),
+      isClosed: () => false,
+    } as unknown as Page;
+    const trappedPages = new Proxy([{}, goodPage], {
+      get: (target, property, receiver) => {
+        if (property === "0") {
+          throw new Error("page entry trap");
+        }
+        return Reflect.get(target, property, receiver);
+      },
+    });
+
+    const agent = new HyperAgent({
+      llm: createMockLLM(),
+    });
+    const internalAgent = agent as unknown as {
+      browser: object | null;
+      context: { pages: () => unknown } | null;
+    };
+    internalAgent.browser = {};
+    internalAgent.context = {
+      pages: () => trappedPages,
+    };
+
+    await expect(agent.getPages()).resolves.toHaveLength(1);
+  });
+
+  it("surfaces readable errors when newPage creation fails", async () => {
+    const agent = new HyperAgent({
+      llm: createMockLLM(),
+    });
+    const internalAgent = agent as unknown as {
+      browser: object | null;
+      context: { newPage: () => Promise<Page> } | null;
+    };
+    internalAgent.browser = {};
+    internalAgent.context = {
+      newPage: async () => {
+        throw new Error("newPage trap");
+      },
+    };
+
+    await expect(agent.newPage()).rejects.toThrow(
+      "Failed to create new page: newPage trap"
+    );
+  });
+
+  it("surfaces readable errors when context.newPage getter traps", async () => {
+    const agent = new HyperAgent({
+      llm: createMockLLM(),
+    });
+    const internalAgent = agent as unknown as {
+      browser: object | null;
+      context: unknown;
+    };
+    internalAgent.browser = {};
+    internalAgent.context = new Proxy(
+      {},
+      {
+        get: (_target, prop) => {
+          if (prop === "newPage") {
+            throw new Error("newPage getter trap");
+          }
+          return undefined;
+        },
+      }
+    );
+
+    await expect(agent.newPage()).rejects.toThrow(
+      "Failed to create new page: failed to read context.newPage: newPage getter trap"
+    );
+  });
+
+  it("surfaces explicit error when context.newPage is unavailable", async () => {
+    const agent = new HyperAgent({
+      llm: createMockLLM(),
+    });
+    const internalAgent = agent as unknown as {
+      browser: object | null;
+      context: Record<string, unknown> | null;
+    };
+    internalAgent.browser = {};
+    internalAgent.context = {};
+
+    await expect(agent.newPage()).rejects.toThrow(
+      "Failed to create new page: context.newPage is unavailable"
+    );
+  });
+
+  it("initBrowser surfaces readable errors when browser provider start fails", async () => {
+    const agent = new HyperAgent({
+      llm: createMockLLM(),
+    });
+    const internalAgent = agent as unknown as {
+      browserProvider: {
+        start: () => Promise<unknown>;
+        close: () => Promise<void>;
+        getSession: () => unknown;
+      };
+      browser: unknown;
+      context: unknown;
+    };
+    internalAgent.browserProvider = {
+      start: async () => {
+        throw new Error("start trap");
+      },
+      close: async () => undefined,
+      getSession: () => null,
+    };
+
+    await expect(agent.initBrowser()).rejects.toThrow(
+      "Failed to start browser provider: start trap"
+    );
+    expect(internalAgent.browser).toBeNull();
+    expect(internalAgent.context).toBeNull();
+  });
+
+  it("initBrowser truncates oversized browser-provider start diagnostics", async () => {
+    const agent = new HyperAgent({
+      llm: createMockLLM(),
+    });
+    const internalAgent = agent as unknown as {
+      browserProvider: {
+        start: () => Promise<unknown>;
+        close: () => Promise<void>;
+        getSession: () => unknown;
+      };
+      browser: unknown;
+      context: unknown;
+    };
+    internalAgent.browserProvider = {
+      start: async () => {
+        throw new Error("x".repeat(2_000));
+      },
+      close: async () => undefined,
+      getSession: () => null,
+    };
+
+    await expect(agent.initBrowser()).rejects.toThrow(/\[truncated/);
+    expect(internalAgent.browser).toBeNull();
+    expect(internalAgent.context).toBeNull();
+  });
+
+  it("initBrowser closes provider when Hyperbrowser context enumeration fails", async () => {
+    const close = jest.fn(async () => undefined);
+    const agent = new HyperAgent({
+      llm: createMockLLM(),
+    });
+    const internalAgent = agent as unknown as {
+      browserProviderType: "Hyperbrowser";
+      browserProvider: {
+        start: () => Promise<unknown>;
+        close: typeof close;
+        getSession: () => unknown;
+      };
+      browser: unknown;
+      context: unknown;
+    };
+    internalAgent.browserProviderType = "Hyperbrowser";
+    internalAgent.browserProvider = {
+      start: async () => ({
+        contexts: () => {
+          throw new Error("contexts trap");
+        },
+      }),
+      close,
+      getSession: () => ({ id: "session-1" }),
+    };
+
+    await expect(agent.initBrowser()).rejects.toThrow(
+      "Failed to list browser contexts: contexts trap"
+    );
+    expect(close).toHaveBeenCalledTimes(1);
+    expect(internalAgent.browser).toBeNull();
+    expect(internalAgent.context).toBeNull();
+  });
+
+  it("initBrowser tolerates context page-listener registration failures", async () => {
+    const warnSpy = jest.spyOn(console, "warn").mockImplementation(() => {});
+    const context = {
+      on: () => {
+        throw new Error("context.on trap");
+      },
+    };
+    const browser = {
+      newContext: async () => context,
+    };
+    const agent = new HyperAgent({
+      llm: createMockLLM(),
+      debug: true,
+    });
+    const internalAgent = agent as unknown as {
+      browserProvider: {
+        start: () => Promise<unknown>;
+        close: () => Promise<void>;
+        getSession: () => unknown;
+      };
+    };
+    internalAgent.browserProvider = {
+      start: async () => browser,
+      close: async () => undefined,
+      getSession: () => ({ id: "session-1" }),
+    };
+
+    try {
+      await expect(agent.initBrowser()).resolves.toBe(browser);
+      expect(warnSpy).toHaveBeenCalledWith(
+        "[HyperAgent] Failed to attach browser page listener: context.on trap"
+      );
+    } finally {
+      warnSpy.mockRestore();
+    }
+  });
+
+  it("initBrowser logs unavailable context page-listener methods in debug mode", async () => {
+    const warnSpy = jest.spyOn(console, "warn").mockImplementation(() => {});
+    const context = new Proxy(
+      {},
+      {
+        get: (_target, prop) => {
+          if (prop === "on") {
+            throw new Error("context.on getter trap");
+          }
+          return undefined;
+        },
+      }
+    ) as unknown as { on: () => void };
+    const browser = {
+      newContext: async () => context,
+    };
+    const agent = new HyperAgent({
+      llm: createMockLLM(),
+      debug: true,
+    });
+    const internalAgent = agent as unknown as {
+      browserProvider: {
+        start: () => Promise<unknown>;
+        close: () => Promise<void>;
+        getSession: () => unknown;
+      };
+    };
+    internalAgent.browserProvider = {
+      start: async () => browser,
+      close: async () => undefined,
+      getSession: () => ({ id: "session-1" }),
+    };
+
+    try {
+      await expect(agent.initBrowser()).resolves.toBe(browser);
+      expect(warnSpy).toHaveBeenCalledWith(
+        "[HyperAgent] Failed to attach browser page listener: context.on is unavailable"
+      );
+    } finally {
+      warnSpy.mockRestore();
+    }
+  });
+
+  it("initBrowser aborts stale provider starts after closeAgent generation changes", async () => {
+    const close = jest.fn(async () => undefined);
+    let resolveStart!: (browser: unknown) => void;
+    const startPromise = new Promise<unknown>((resolve) => {
+      resolveStart = resolve;
+    });
+    const agent = new HyperAgent({
+      llm: createMockLLM(),
+    });
+    const internalAgent = agent as unknown as {
+      browserProvider: {
+        start: () => Promise<unknown>;
+        close: typeof close;
+        getSession: () => unknown;
+      };
+      browser: unknown;
+      context: unknown;
+    };
+    internalAgent.browserProvider = {
+      start: () => startPromise,
+      close,
+      getSession: () => ({ id: "session-1" }),
+    };
+
+    const initPromise = agent.initBrowser();
+    await expect(agent.closeAgent()).resolves.toBeUndefined();
+    resolveStart({});
+
+    await expect(initPromise).rejects.toThrow(
+      "Browser initialization cancelled because agent was closed"
+    );
+    expect(close).toHaveBeenCalled();
+    expect(internalAgent.browser).toBeNull();
+    expect(internalAgent.context).toBeNull();
+  });
+
+  it("initBrowser recreates missing context for existing browser instances", async () => {
+    const on = jest.fn();
+    const context = { on };
+    const browser = {
+      newContext: async () => context,
+    };
+    const agent = new HyperAgent({
+      llm: createMockLLM(),
+    });
+    const internalAgent = agent as unknown as {
+      browser: unknown;
+      context: unknown;
+    };
+    internalAgent.browser = browser;
+    internalAgent.context = null;
+
+    await expect(agent.initBrowser()).resolves.toBe(browser);
+    expect(internalAgent.context).toBe(context);
+    expect(on).toHaveBeenCalledWith("page", expect.any(Function));
+  });
+
+  it("initBrowser resets browser state when context recreation fails", async () => {
+    const close = jest.fn(async () => undefined);
+    const stalePage = {} as unknown as Page;
+    const browser = {
+      newContext: async () => {
+        throw new Error("context rebuild trap");
+      },
+    };
+    const agent = new HyperAgent({
+      llm: createMockLLM(),
+    });
+    const internalAgent = agent as unknown as {
+      browser: unknown;
+      context: unknown;
+      _currentPage: Page | null;
+      browserProvider: {
+        close: typeof close;
+        getSession: () => unknown;
+      };
+    };
+    internalAgent.browser = browser;
+    internalAgent.context = null;
+    internalAgent._currentPage = stalePage;
+    internalAgent.browserProvider = {
+      close,
+      getSession: () => ({ id: "session-1" }),
+    };
+
+    await expect(agent.initBrowser()).rejects.toThrow(
+      "Failed to create browser context: context rebuild trap"
+    );
+    expect(close).toHaveBeenCalledTimes(1);
+    expect(internalAgent.browser).toBeNull();
+    expect(internalAgent.context).toBeNull();
+    expect(internalAgent._currentPage).toBeNull();
+  });
+
+  it("continues getPages when hyperpage context listener attachment fails", async () => {
+    const page = {
+      on: jest.fn(),
+      context: () => ({
+        on: () => {
+          throw new Error("context listener trap");
+        },
+        off: jest.fn(),
+      }),
+      isClosed: () => false,
+    } as unknown as Page;
+    const agent = new HyperAgent({
+      llm: createMockLLM(),
+      debug: true,
+    });
+    const logSpy = jest.spyOn(console, "warn").mockImplementation(() => {});
+    const internalAgent = agent as unknown as {
+      browser: object | null;
+      context: { pages: () => Page[] } | null;
+    };
+    internalAgent.browser = {};
+    internalAgent.context = {
+      pages: () => [page],
+    };
+
+    try {
+      const pages = await agent.getPages();
+      expect(pages).toHaveLength(1);
+      expect(logSpy).toHaveBeenCalledWith(
+        expect.stringContaining("Failed to attach context page listener")
+      );
+    } finally {
+      logSpy.mockRestore();
+    }
+  });
+
+  it("truncates oversized hyperpage context-listener diagnostics", async () => {
+    const page = {
+      on: jest.fn(),
+      context: () => ({
+        on: () => {
+          throw new Error("x".repeat(2_000));
+        },
+        off: jest.fn(),
+      }),
+      isClosed: () => false,
+    } as unknown as Page;
+    const agent = new HyperAgent({
+      llm: createMockLLM(),
+      debug: true,
+    });
+    const warnSpy = jest.spyOn(console, "warn").mockImplementation(() => {});
+    const internalAgent = agent as unknown as {
+      browser: object | null;
+      context: { pages: () => Page[] } | null;
+    };
+    internalAgent.browser = {};
+    internalAgent.context = {
+      pages: () => [page],
+    };
+
+    try {
+      const pages = await agent.getPages();
+      expect(pages).toHaveLength(1);
+      const warnedMessage = String(warnSpy.mock.calls[0]?.[0] ?? "");
+      expect(warnedMessage).toContain("[truncated");
+    } finally {
+      warnSpy.mockRestore();
+    }
+  });
+
+  it("continues getPages when hyperpage context getter traps", async () => {
+    const basePage = {
+      on: jest.fn(),
+      off: jest.fn(),
+      isClosed: () => false,
+    };
+    const trappedPage = new Proxy(basePage, {
+      get: (target, property, receiver) => {
+        if (property === "context") {
+          throw new Error("context getter trap");
+        }
+        const value = Reflect.get(target, property, receiver);
+        if (typeof value === "function") {
+          return value.bind(target);
+        }
+        return value;
+      },
+    }) as unknown as Page;
+    const agent = new HyperAgent({
+      llm: createMockLLM(),
+    });
+    const internalAgent = agent as unknown as {
+      browser: object | null;
+      context: { pages: () => Page[] } | null;
+    };
+    internalAgent.browser = {};
+    internalAgent.context = {
+      pages: () => [trappedPage],
+    };
+
+    await expect(agent.getPages()).resolves.toHaveLength(1);
+    await expect(agent.getPages()).resolves.toHaveLength(1);
+  });
+
+  it("keeps child tab tracking when context pages getter traps", async () => {
+    let contextPageListener: ((newPage: Page) => Promise<void>) | undefined;
+    const contextOff = jest.fn();
+    const context = {
+      on: jest.fn(
+        (event: "page", listener: (newPage: Page) => Promise<void>) => {
+          if (event === "page") {
+            contextPageListener = listener;
+          }
+        }
+      ),
+      off: contextOff,
+      get pages() {
+        throw new Error("context pages getter trap");
+      },
+    };
+    const page = {
+      on: jest.fn(),
+      off: jest.fn(),
+      context: () => context,
+      isClosed: () => false,
+    } as unknown as Page;
+    const newPageOn = jest.fn();
+    const newPage = {
+      on: newPageOn,
+      off: jest.fn(),
+      opener: async () => page,
+      isClosed: () => false,
+    } as unknown as Page;
+    const agent = new HyperAgent({
+      llm: createMockLLM(),
+    });
+    const internalAgent = agent as unknown as {
+      browser: object | null;
+      context: { pages: () => Page[] } | null;
+    };
+    internalAgent.browser = {};
+    internalAgent.context = {
+      pages: () => [page],
+    };
+
+    await expect(agent.getPages()).resolves.toHaveLength(1);
+    expect(contextPageListener).toBeDefined();
+    await contextPageListener?.(newPage);
+
+    expect(newPageOn).toHaveBeenCalledWith("close", expect.any(Function));
+  });
+
+  it("continues getPages when scoped listener cleanup getter traps", async () => {
+    let trappedPage: Page;
+    const basePage = {
+      on: jest.fn(),
+      off: jest.fn(),
+      context: () => ({
+        on: jest.fn(),
+        off: jest.fn(),
+        pages: () => [trappedPage],
+      }),
+      isClosed: () => false,
+    } as unknown as Page;
+    trappedPage = new Proxy(basePage, {
+      get: (target, property, receiver) => {
+        if (property === "_scopeListenerCleanup") {
+          throw new Error("scope cleanup getter trap");
+        }
+        const value = Reflect.get(target, property, receiver);
+        if (typeof value === "function") {
+          return value.bind(target);
+        }
+        return value;
+      },
+    }) as unknown as Page;
+
+    const agent = new HyperAgent({
+      llm: createMockLLM(),
+    });
+    const internalAgent = agent as unknown as {
+      browser: object | null;
+      context: { pages: () => Page[] } | null;
+    };
+    internalAgent.browser = {};
+    internalAgent.context = {
+      pages: () => [trappedPage],
+    };
+
+    await expect(agent.getPages()).resolves.toHaveLength(1);
+    await expect(agent.getPages()).resolves.toHaveLength(1);
+  });
+
+  it("continues getPages when scoped listener cleanup setter traps", async () => {
+    let trappedPage: Page;
+    const contextOn = jest.fn();
+    const contextOff = jest.fn();
+    const pageOn = jest.fn();
+    const pageOff = jest.fn();
+    const basePage = {
+      on: pageOn,
+      off: pageOff,
+      context: () => ({
+        on: contextOn,
+        off: contextOff,
+        pages: () => [trappedPage],
+      }),
+      isClosed: () => false,
+    } as unknown as Page;
+    trappedPage = new Proxy(basePage, {
+      get: (target, property, receiver) => {
+        const value = Reflect.get(target, property, receiver);
+        if (typeof value === "function") {
+          return value.bind(target);
+        }
+        return value;
+      },
+      set: (target, property, value, receiver) => {
+        if (property === "_scopeListenerCleanup") {
+          throw new Error("scope cleanup setter trap");
+        }
+        return Reflect.set(target, property, value, receiver);
+      },
+    }) as unknown as Page;
+
+    const agent = new HyperAgent({
+      llm: createMockLLM(),
+      debug: true,
+    });
+    const warnSpy = jest.spyOn(console, "warn").mockImplementation(() => {});
+    const internalAgent = agent as unknown as {
+      browser: object | null;
+      context: { pages: () => Page[] } | null;
+    };
+    internalAgent.browser = {};
+    internalAgent.context = {
+      pages: () => [trappedPage],
+    };
+
+    try {
+      await expect(agent.getPages()).resolves.toHaveLength(1);
+      await expect(agent.getPages()).resolves.toHaveLength(1);
+      expect(warnSpy).toHaveBeenCalledWith(
+        expect.stringContaining("Failed to store scope listener cleanup callback")
+      );
+      expect(contextOff).toHaveBeenCalledWith("page", expect.any(Function));
+      expect(pageOff).toHaveBeenCalledWith("close", expect.any(Function));
+    } finally {
+      warnSpy.mockRestore();
+    }
+  });
+
+  it("cleans previous HyperPage root listeners when re-wrapping same page", async () => {
+    const contextOn = jest.fn();
+    const contextOff = jest.fn();
+    const pageOn = jest.fn();
+    const pageOff = jest.fn();
+    const page = {
+      on: pageOn,
+      off: pageOff,
+      context: () => ({
+        on: contextOn,
+        off: contextOff,
+        pages: () => [page],
+      }),
+      isClosed: () => false,
+    } as unknown as Page;
+    const agent = new HyperAgent({
+      llm: createMockLLM(),
+    });
+    const internalAgent = agent as unknown as {
+      browser: object | null;
+      context: { pages: () => Page[] } | null;
+    };
+    internalAgent.browser = {};
+    internalAgent.context = {
+      pages: () => [page],
+    };
+
+    await expect(agent.getPages()).resolves.toHaveLength(1);
+    await expect(agent.getPages()).resolves.toHaveLength(1);
+
+    expect(pageOff).toHaveBeenCalledWith("close", expect.any(Function));
+    expect(contextOff).toHaveBeenCalledWith("page", expect.any(Function));
+  });
+
+  it("cleans tracked child-tab close listeners during HyperPage re-wrap", async () => {
+    let contextPageListener: ((newPage: Page) => Promise<void>) | undefined;
+    const contextOn = jest.fn(
+      (event: "page", listener: (newPage: Page) => Promise<void>) => {
+        if (event === "page") {
+          contextPageListener = listener;
+        }
+      }
+    );
+    const contextOff = jest.fn();
+    const pageOn = jest.fn();
+    const pageOff = jest.fn();
+    const page = {
+      on: pageOn,
+      off: pageOff,
+      context: () => ({
+        on: contextOn,
+        off: contextOff,
+        pages: () => [page],
+      }),
+      isClosed: () => false,
+    } as unknown as Page;
+    const newPageOff = jest.fn();
+    const newPage = {
+      on: jest.fn(),
+      off: newPageOff,
+      opener: async () => page,
+      isClosed: () => false,
+    } as unknown as Page;
+    const agent = new HyperAgent({
+      llm: createMockLLM(),
+    });
+    const internalAgent = agent as unknown as {
+      browser: object | null;
+      context: { pages: () => Page[] } | null;
+    };
+    internalAgent.browser = {};
+    internalAgent.context = {
+      pages: () => [page],
+    };
+
+    await expect(agent.getPages()).resolves.toHaveLength(1);
+    expect(contextPageListener).toBeDefined();
+    await contextPageListener?.(newPage);
+    await expect(agent.getPages()).resolves.toHaveLength(1);
+
+    expect(newPageOff).toHaveBeenCalledWith("close", expect.any(Function));
+  });
+
+  it("does not duplicate child close listeners for repeated page events", async () => {
+    let contextPageListener: ((newPage: Page) => Promise<void>) | undefined;
+    const contextOn = jest.fn(
+      (event: "page", listener: (newPage: Page) => Promise<void>) => {
+        if (event === "page") {
+          contextPageListener = listener;
+        }
+      }
+    );
+    const contextOff = jest.fn();
+    const page = {
+      on: jest.fn(),
+      off: jest.fn(),
+      context: () => ({
+        on: contextOn,
+        off: contextOff,
+        pages: () => [page],
+      }),
+      isClosed: () => false,
+    } as unknown as Page;
+    const newPageOn = jest.fn();
+    const newPageOff = jest.fn();
+    const newPage = {
+      on: newPageOn,
+      off: newPageOff,
+      opener: async () => page,
+      isClosed: () => false,
+    } as unknown as Page;
+    const agent = new HyperAgent({
+      llm: createMockLLM(),
+    });
+    const internalAgent = agent as unknown as {
+      browser: object | null;
+      context: { pages: () => Page[] } | null;
+    };
+    internalAgent.browser = {};
+    internalAgent.context = {
+      pages: () => [page],
+    };
+
+    await expect(agent.getPages()).resolves.toHaveLength(1);
+    expect(contextPageListener).toBeDefined();
+    await contextPageListener?.(newPage);
+    await contextPageListener?.(newPage);
+    await expect(agent.getPages()).resolves.toHaveLength(1);
+
+    expect(newPageOn).toHaveBeenCalledTimes(1);
+    expect(newPageOff).toHaveBeenCalledTimes(1);
+    expect(newPageOn).toHaveBeenCalledWith("close", expect.any(Function));
+    expect(newPageOff).toHaveBeenCalledWith("close", expect.any(Function));
+  });
+
+  it("returns null session when browser provider getSession throws", () => {
+    const agent = new HyperAgent({
+      llm: createMockLLM(),
+      debug: true,
+    });
+    const warnSpy = jest.spyOn(console, "warn").mockImplementation(() => {});
+    const internalAgent = agent as unknown as {
+      browserProvider: { getSession: () => unknown };
+    };
+    internalAgent.browserProvider = {
+      getSession: () => {
+        throw new Error("session trap");
+      },
+    };
+
+    try {
+      expect(agent.getSession()).toBeNull();
+      expect(warnSpy).toHaveBeenCalledWith(
+        "[HyperAgent] Failed to read browser session: session trap"
+      );
+    } finally {
+      warnSpy.mockRestore();
+    }
+  });
+
+  it("truncates oversized session-read diagnostics", () => {
+    const agent = new HyperAgent({
+      llm: createMockLLM(),
+      debug: true,
+    });
+    const warnSpy = jest.spyOn(console, "warn").mockImplementation(() => {});
+    const internalAgent = agent as unknown as {
+      browserProvider: { getSession: () => unknown };
+    };
+    internalAgent.browserProvider = {
+      getSession: () => {
+        throw new Error("x".repeat(2_000));
+      },
+    };
+
+    try {
+      expect(agent.getSession()).toBeNull();
+      const warnedMessage = String(warnSpy.mock.calls[0]?.[0] ?? "");
+      expect(warnedMessage).toContain("[truncated");
+    } finally {
+      warnSpy.mockRestore();
+    }
+  });
+
+  it("sanitizes control characters in session-read diagnostics", () => {
+    const warnSpy = jest.spyOn(console, "warn").mockImplementation(() => {});
+    const agent = new HyperAgent({
+      llm: createMockLLM(),
+      debug: true,
+    });
+    const internalAgent = agent as unknown as {
+      browserProvider: { getSession: () => unknown };
+    };
+    internalAgent.browserProvider = {
+      getSession: () => {
+        throw new Error("session\u0000\ntrap");
+      },
+    };
+
+    try {
+      expect(agent.getSession()).toBeNull();
+      const warnedMessage = String(warnSpy.mock.calls[0]?.[0] ?? "");
+      expect(warnedMessage).toContain("session trap");
+      expect(warnedMessage).not.toContain("\u0000");
+      expect(warnedMessage).not.toContain("\n");
+    } finally {
+      warnSpy.mockRestore();
+    }
+  });
+
+  it("normalizes MCP server ids and handles invalid values", () => {
+    const agent = new HyperAgent({
+      llm: createMockLLM(),
+    });
+    const internalAgent = agent as unknown as {
+      mcpClient: {
+        getServerIds: () => string[];
+      } | null;
+    };
+    internalAgent.mcpClient = {
+      getServerIds: () => ["server-a"],
+    };
+
+    expect(agent.isMCPServerConnected("  server-a  ")).toBe(true);
+    expect(agent.isMCPServerConnected("   ")).toBe(false);
+  });
+
+  it("returns safe MCP server ids/info when MCP client access throws", () => {
+    const agent = new HyperAgent({
+      llm: createMockLLM(),
+    });
+    const internalAgent = agent as unknown as {
+      mcpClient:
+        | {
+            getServerIds: () => string[];
+            getServerInfo: () => Array<{
+              id: string;
+              toolCount: number;
+              toolNames: string[];
+            }>;
+          }
+        | null;
+    };
+    internalAgent.mcpClient = {
+      getServerIds: () => {
+        throw new Error("serverIds trap");
+      },
+      getServerInfo: () => {
+        throw new Error("serverInfo trap");
+      },
+    };
+
+    expect(agent.getMCPServerIds()).toEqual([]);
+    expect(agent.getMCPServerInfo()).toEqual([]);
+  });
+
+  it("sanitizes and bounds MCP server ids from client accessors", () => {
+    const agent = new HyperAgent({
+      llm: createMockLLM(),
+    });
+    const oversizedServerId = `server-${"x".repeat(300)}\nunsafe`;
+    const internalAgent = agent as unknown as {
+      mcpClient:
+        | {
+            getServerIds: () => unknown[];
+            getServerInfo: () => unknown[];
+          }
+        | null;
+    };
+    internalAgent.mcpClient = {
+      getServerIds: () => [" server-a ", "server-b\nunsafe", oversizedServerId, 42],
+      getServerInfo: () => [],
+    };
+
+    const serverIds = agent.getMCPServerIds();
+    expect(serverIds).toContain("server-a");
+    expect(serverIds).toContain("server-b unsafe");
+    const truncatedId = serverIds.find((id) => id.includes("[truncated")) ?? "";
+    expect(truncatedId).toContain("[truncated");
+    expect(truncatedId).not.toContain("\n");
+  });
+
+  it("sanitizes malformed MCP server info entries from client accessors", () => {
+    const agent = new HyperAgent({
+      llm: createMockLLM(),
+    });
+    const trapEntry = {};
+    Object.defineProperty(trapEntry, "id", {
+      get(): never {
+        throw new Error("id trap");
+      },
+    });
+    Object.defineProperty(trapEntry, "toolCount", {
+      get(): never {
+        throw new Error("count trap");
+      },
+    });
+    Object.defineProperty(trapEntry, "toolNames", {
+      get(): never {
+        throw new Error("toolNames trap");
+      },
+    });
+    const internalAgent = agent as unknown as {
+      mcpClient:
+        | {
+            getServerIds: () => string[];
+            getServerInfo: () => unknown[];
+          }
+        | null;
+    };
+    internalAgent.mcpClient = {
+      getServerIds: () => [],
+      getServerInfo: () => [
+        {
+          id: " server-a\nunsafe ",
+          toolCount: -1,
+          toolNames: [" search ", "search", "notes\nunsafe", 42],
+        },
+        trapEntry,
+      ],
+    };
+
+    expect(agent.getMCPServerInfo()).toEqual([
+      {
+        id: "server-a unsafe",
+        toolCount: 2,
+        toolNames: ["search", "notes unsafe"],
+      },
+      {
+        id: "unknown-server",
+        toolCount: 0,
+        toolNames: [],
+      },
+    ]);
+  });
+
+  it("disconnectFromMCPServer handles invalid IDs and server list traps", () => {
+    const disconnectServer = jest.fn(async () => undefined);
+    const agent = new HyperAgent({
+      llm: createMockLLM(),
+    });
+    const internalAgent = agent as unknown as {
+      mcpClient:
+        | {
+            getServerIds: () => string[];
+            disconnectServer: typeof disconnectServer;
+          }
+        | null;
+    };
+    internalAgent.mcpClient = {
+      getServerIds: () => {
+        throw new Error("disconnect ids trap");
+      },
+      disconnectServer,
+    };
+
+    expect(agent.disconnectFromMCPServer("   ")).toBe(false);
+    expect(agent.disconnectFromMCPServer("server-a")).toBe(false);
+    expect(disconnectServer).not.toHaveBeenCalled();
+  });
+
+  it("disconnectFromMCPServerAsync handles invalid IDs and missing connections", async () => {
+    const disconnectServer = jest.fn(async () => undefined);
+    const agent = new HyperAgent({
+      llm: createMockLLM(),
+    });
+    const internalAgent = agent as unknown as {
+      mcpClient:
+        | {
+            getServerIds: () => string[];
+            disconnectServer: typeof disconnectServer;
+          }
+        | null;
+    };
+    internalAgent.mcpClient = {
+      getServerIds: () => ["server-a"],
+      disconnectServer,
+    };
+
+    await expect(agent.disconnectFromMCPServerAsync("  ")).resolves.toBe(false);
+    await expect(agent.disconnectFromMCPServerAsync("server-b")).resolves.toBe(
+      false
+    );
+    await expect(agent.disconnectFromMCPServerAsync(" server-a ")).resolves.toBe(
+      true
+    );
+    expect(disconnectServer).toHaveBeenCalledWith("server-a");
+  });
+
+  it("connectToMCPServer rejects non-object server configs", async () => {
+    const agent = new HyperAgent({
+      llm: createMockLLM(),
+    });
+
+    await expect(
+      agent.connectToMCPServer(null as unknown as never)
+    ).resolves.toBeNull();
+  });
+
+  it("rejects blank task descriptions for async and sync task execution", async () => {
+    const agent = new HyperAgent({
+      llm: createMockLLM(),
+    });
+    const fakePage = {} as unknown as Page;
+
+    await expect(
+      agent.executeTaskAsync("   ", undefined, fakePage)
+    ).rejects.toThrow("Action instruction must be a non-empty string");
+    await expect(
+      agent.executeTask("   ", undefined, fakePage)
+    ).rejects.toThrow("Action instruction must be a non-empty string");
+  });
+
+  it("rejects invalid single-action instruction inputs", async () => {
+    const agent = new HyperAgent({
+      llm: createMockLLM(),
+    });
+    const fakePage = {} as unknown as Page;
+
+    await expect(
+      agent.executeSingleAction("   ", fakePage)
+    ).rejects.toThrow("Action instruction must be a non-empty string");
+  });
+
+  it("surfaces readable errors when single-action page getter traps throw", async () => {
+    const agent = new HyperAgent({
+      llm: createMockLLM(),
+    });
+
+    await expect(
+      agent.executeSingleAction("click submit", () => {
+        throw new Error("page getter trap");
+      })
+    ).rejects.toThrow("Failed to resolve action page: page getter trap");
+  });
+
+  it("normalizes invalid maxContextSwitchRetries for hyperPage.perform retries", async () => {
+    const page = {
+      on: jest.fn(),
+      off: jest.fn(),
+      context: () => ({
+        on: jest.fn(),
+        off: jest.fn(),
+        pages: () => [page],
+      }),
+      isClosed: () => false,
+    } as unknown as Page;
+    const agent = new HyperAgent({
+      llm: createMockLLM(),
+    });
+    const internalAgent = agent as unknown as {
+      browser: object | null;
+      context: { pages: () => Page[] } | null;
+      executeSingleAction: jest.Mock;
+    };
+    internalAgent.browser = {};
+    internalAgent.context = {
+      pages: () => [page],
+    };
+    internalAgent.executeSingleAction = jest
+      .fn()
+      .mockRejectedValueOnce(
+        new HyperagentError("Page context switched during execution", 409)
+      )
+      .mockResolvedValue({
+        taskId: "task-id",
+        status: TaskStatus.COMPLETED,
+        steps: [],
+        output: "done",
+      });
+
+    const [hyperPage] = await agent.getPages();
+    const result = await hyperPage.perform("click submit", {
+      maxContextSwitchRetries: 0,
+    });
+
+    expect(result.status).toBe(TaskStatus.COMPLETED);
+    expect(internalAgent.executeSingleAction).toHaveBeenCalledTimes(2);
+  });
+
+  it("warns once when deprecated maxSteps perform option is used via hyperPage.perform", async () => {
+    const page = {
+      on: jest.fn(),
+      off: jest.fn(),
+      context: () => ({
+        on: jest.fn(),
+        off: jest.fn(),
+        pages: () => [page],
+      }),
+      isClosed: () => false,
+    } as unknown as Page;
+    const agent = new HyperAgent({
+      llm: createMockLLM(),
+    });
+    const internalAgent = agent as unknown as {
+      browser: object | null;
+      context: { pages: () => Page[] } | null;
+      executeSingleAction: jest.Mock;
+    };
+    internalAgent.browser = {};
+    internalAgent.context = {
+      pages: () => [page],
+    };
+    internalAgent.executeSingleAction = jest.fn().mockResolvedValue({
+      taskId: "task-id",
+      status: TaskStatus.COMPLETED,
+      steps: [],
+      output: "done",
+    });
+    const warnSpy = jest.spyOn(console, "warn").mockImplementation(() => {});
+
+    try {
+      const [hyperPage] = await agent.getPages();
+      await hyperPage.perform("click submit", {
+        maxSteps: 2,
+      });
+      await hyperPage.perform("click continue", {
+        maxSteps: 3,
+      });
+
+      const deprecationWarnings = warnSpy.mock.calls.filter((call) =>
+        String(call[0] ?? "").includes("perform({ maxSteps }) is deprecated")
+      );
+      expect(deprecationWarnings).toHaveLength(1);
+      expect(internalAgent.executeSingleAction).toHaveBeenCalledTimes(2);
+    } finally {
+      warnSpy.mockRestore();
+    }
+  });
+
+  it("normalizes invalid contextSwitchRetryDelayMs for hyperPage.perform retries", async () => {
+    const page = {
+      on: jest.fn(),
+      off: jest.fn(),
+      context: () => ({
+        on: jest.fn(),
+        off: jest.fn(),
+        pages: () => [page],
+      }),
+      isClosed: () => false,
+    } as unknown as Page;
+    const agent = new HyperAgent({
+      llm: createMockLLM(),
+    });
+    const internalAgent = agent as unknown as {
+      browser: object | null;
+      context: { pages: () => Page[] } | null;
+      executeSingleAction: jest.Mock;
+    };
+    internalAgent.browser = {};
+    internalAgent.context = {
+      pages: () => [page],
+    };
+    internalAgent.executeSingleAction = jest
+      .fn()
+      .mockRejectedValueOnce(
+        new HyperagentError("Page context switched during execution", 409)
+      )
+      .mockResolvedValue({
+        taskId: "task-id",
+        status: TaskStatus.COMPLETED,
+        steps: [],
+        output: "done",
+      });
+    const setTimeoutSpy = jest
+      .spyOn(global, "setTimeout")
+      .mockImplementation(
+        ((handler: TimerHandler) => {
+          if (typeof handler === "function") {
+            handler();
+          }
+          return 0 as unknown as NodeJS.Timeout;
+        }) as unknown as typeof setTimeout
+      );
+
+    try {
+      const [hyperPage] = await agent.getPages();
+      const result = await hyperPage.perform("click submit", {
+        maxContextSwitchRetries: 2,
+        contextSwitchRetryDelayMs: -1,
+      });
+
+      expect(result.status).toBe(TaskStatus.COMPLETED);
+      expect(internalAgent.executeSingleAction).toHaveBeenCalledTimes(2);
+      expect(setTimeoutSpy).toHaveBeenCalledWith(expect.any(Function), 500);
+    } finally {
+      setTimeoutSpy.mockRestore();
+    }
+  });
+
+  it("uses custom contextSwitchRetryDelayMs for hyperPage.perform retries", async () => {
+    const page = {
+      on: jest.fn(),
+      off: jest.fn(),
+      context: () => ({
+        on: jest.fn(),
+        off: jest.fn(),
+        pages: () => [page],
+      }),
+      isClosed: () => false,
+    } as unknown as Page;
+    const agent = new HyperAgent({
+      llm: createMockLLM(),
+    });
+    const internalAgent = agent as unknown as {
+      browser: object | null;
+      context: { pages: () => Page[] } | null;
+      executeSingleAction: jest.Mock;
+    };
+    internalAgent.browser = {};
+    internalAgent.context = {
+      pages: () => [page],
+    };
+    internalAgent.executeSingleAction = jest
+      .fn()
+      .mockRejectedValueOnce(
+        new HyperagentError("Page context switched during execution", 409)
+      )
+      .mockResolvedValue({
+        taskId: "task-id",
+        status: TaskStatus.COMPLETED,
+        steps: [],
+        output: "done",
+      });
+    const setTimeoutSpy = jest
+      .spyOn(global, "setTimeout")
+      .mockImplementation(
+        ((handler: TimerHandler) => {
+          if (typeof handler === "function") {
+            handler();
+          }
+          return 0 as unknown as NodeJS.Timeout;
+        }) as unknown as typeof setTimeout
+      );
+
+    try {
+      const [hyperPage] = await agent.getPages();
+      const result = await hyperPage.perform("click submit", {
+        maxContextSwitchRetries: 2,
+        contextSwitchRetryDelayMs: 1234,
+      });
+
+      expect(result.status).toBe(TaskStatus.COMPLETED);
+      expect(internalAgent.executeSingleAction).toHaveBeenCalledTimes(2);
+      expect(setTimeoutSpy).toHaveBeenCalledWith(expect.any(Function), 1234);
+    } finally {
+      setTimeoutSpy.mockRestore();
+    }
+  });
+
+  it("caps oversized contextSwitchRetryDelayMs for hyperPage.perform retries", async () => {
+    const page = {
+      on: jest.fn(),
+      off: jest.fn(),
+      context: () => ({
+        on: jest.fn(),
+        off: jest.fn(),
+        pages: () => [page],
+      }),
+      isClosed: () => false,
+    } as unknown as Page;
+    const agent = new HyperAgent({
+      llm: createMockLLM(),
+    });
+    const internalAgent = agent as unknown as {
+      browser: object | null;
+      context: { pages: () => Page[] } | null;
+      executeSingleAction: jest.Mock;
+    };
+    internalAgent.browser = {};
+    internalAgent.context = {
+      pages: () => [page],
+    };
+    internalAgent.executeSingleAction = jest
+      .fn()
+      .mockRejectedValueOnce(
+        new HyperagentError("Page context switched during execution", 409)
+      )
+      .mockResolvedValue({
+        taskId: "task-id",
+        status: TaskStatus.COMPLETED,
+        steps: [],
+        output: "done",
+      });
+    const setTimeoutSpy = jest
+      .spyOn(global, "setTimeout")
+      .mockImplementation(
+        ((handler: TimerHandler) => {
+          if (typeof handler === "function") {
+            handler();
+          }
+          return 0 as unknown as NodeJS.Timeout;
+        }) as unknown as typeof setTimeout
+      );
+
+    try {
+      const [hyperPage] = await agent.getPages();
+      const result = await hyperPage.perform("click submit", {
+        maxContextSwitchRetries: 2,
+        contextSwitchRetryDelayMs: 500_000,
+      });
+
+      expect(result.status).toBe(TaskStatus.COMPLETED);
+      expect(internalAgent.executeSingleAction).toHaveBeenCalledTimes(2);
+      expect(setTimeoutSpy).toHaveBeenCalledWith(expect.any(Function), 30_000);
+    } finally {
+      setTimeoutSpy.mockRestore();
+    }
+  });
+
+  it("warns once when deprecated hyperPage.aiAction alias is used", async () => {
+    const page = {
+      on: jest.fn(),
+      off: jest.fn(),
+      context: () => ({
+        on: jest.fn(),
+        off: jest.fn(),
+        pages: () => [page],
+      }),
+      isClosed: () => false,
+    } as unknown as Page;
+    const agent = new HyperAgent({
+      llm: createMockLLM(),
+    });
+    const internalAgent = agent as unknown as {
+      browser: object | null;
+      context: { pages: () => Page[] } | null;
+      executeSingleAction: jest.Mock;
+    };
+    internalAgent.browser = {};
+    internalAgent.context = {
+      pages: () => [page],
+    };
+    internalAgent.executeSingleAction = jest.fn().mockResolvedValue({
+      taskId: "task-id",
+      status: TaskStatus.COMPLETED,
+      steps: [],
+      output: "done",
+    });
+    const warnSpy = jest.spyOn(console, "warn").mockImplementation(() => {});
+
+    try {
+      const [hyperPage] = await agent.getPages();
+      await hyperPage.aiAction("click submit", {
+        maxContextSwitchRetries: 1,
+      });
+      await hyperPage.aiAction("click continue", {
+        maxContextSwitchRetries: 1,
+      });
+
+      expect(internalAgent.executeSingleAction).toHaveBeenCalledTimes(2);
+      expect(warnSpy).toHaveBeenCalledTimes(1);
+      expect(warnSpy).toHaveBeenCalledWith(
+        expect.stringContaining("page.aiAction() is deprecated")
+      );
+    } finally {
+      warnSpy.mockRestore();
+    }
+  });
+
+  it("does not emit aiAction deprecation warning for hyperPage.perform", async () => {
+    const page = {
+      on: jest.fn(),
+      off: jest.fn(),
+      context: () => ({
+        on: jest.fn(),
+        off: jest.fn(),
+        pages: () => [page],
+      }),
+      isClosed: () => false,
+    } as unknown as Page;
+    const agent = new HyperAgent({
+      llm: createMockLLM(),
+    });
+    const internalAgent = agent as unknown as {
+      browser: object | null;
+      context: { pages: () => Page[] } | null;
+      executeSingleAction: jest.Mock;
+    };
+    internalAgent.browser = {};
+    internalAgent.context = {
+      pages: () => [page],
+    };
+    internalAgent.executeSingleAction = jest.fn().mockResolvedValue({
+      taskId: "task-id",
+      status: TaskStatus.COMPLETED,
+      steps: [],
+      output: "done",
+    });
+    const warnSpy = jest.spyOn(console, "warn").mockImplementation(() => {});
+
+    try {
+      const [hyperPage] = await agent.getPages();
+      await hyperPage.perform("click submit");
+      await hyperPage.perform("click continue");
+
+      const deprecationWarnings = warnSpy.mock.calls.filter((call) =>
+        String(call[0] ?? "").includes("page.aiAction() is deprecated")
+      );
+      expect(deprecationWarnings).toHaveLength(0);
+      expect(internalAgent.executeSingleAction).toHaveBeenCalledTimes(2);
+    } finally {
+      warnSpy.mockRestore();
+    }
+  });
+
+  it("hyperPage.extract rejects blank task descriptions when provided", async () => {
+    const mockedRunAgentTask = jest.mocked(runAgentTask);
+    mockedRunAgentTask.mockResolvedValue({
+      taskId: "task-id",
+      status: TaskStatus.COMPLETED,
+      steps: [],
+      output: "done",
+      actionCache: {
+        taskId: "task-id",
+        createdAt: new Date().toISOString(),
+        status: TaskStatus.COMPLETED,
+        steps: [],
+      },
+    });
+
+    const page = {
+      on: jest.fn(),
+      off: jest.fn(),
+      context: () => ({
+        on: jest.fn(),
+        off: jest.fn(),
+        pages: () => [page],
+      }),
+      isClosed: () => false,
+      url: () => "https://example.com",
+    } as unknown as Page;
+    const agent = new HyperAgent({
+      llm: createMockLLM(),
+    });
+    const internalAgent = agent as unknown as {
+      browser: object | null;
+      context: { pages: () => Page[] } | null;
+    };
+    internalAgent.browser = {};
+    internalAgent.context = {
+      pages: () => [page],
+    };
+
+    const [hyperPage] = await agent.getPages();
+    await expect(
+      hyperPage.extract("   ")
+    ).rejects.toThrow("Task description must be non-empty when provided");
+    expect(mockedRunAgentTask).not.toHaveBeenCalled();
+  });
+
+  it("hyperPage.extract normalizes maxSteps and task prompt input", async () => {
+    const mockedRunAgentTask = jest.mocked(runAgentTask);
+    mockedRunAgentTask.mockResolvedValue({
+      taskId: "task-id",
+      status: TaskStatus.COMPLETED,
+      steps: [],
+      output: "done",
+      actionCache: {
+        taskId: "task-id",
+        createdAt: new Date().toISOString(),
+        status: TaskStatus.COMPLETED,
+        steps: [],
+      },
+    });
+
+    const page = {
+      on: jest.fn(),
+      off: jest.fn(),
+      context: () => ({
+        on: jest.fn(),
+        off: jest.fn(),
+        pages: () => [page],
+      }),
+      isClosed: () => false,
+      url: () => "https://example.com",
+    } as unknown as Page;
+    const agent = new HyperAgent({
+      llm: createMockLLM(),
+    });
+    const internalAgent = agent as unknown as {
+      browser: object | null;
+      context: { pages: () => Page[] } | null;
+    };
+    internalAgent.browser = {};
+    internalAgent.context = {
+      pages: () => [page],
+    };
+
+    const [hyperPage] = await agent.getPages();
+    await hyperPage.extract("  summarize inventory  ", undefined, {
+      maxSteps: Number.NaN,
+    });
+
+    const taskStateArg = mockedRunAgentTask.mock.calls[0]?.[1] as {
+      task: string;
+    };
+    const paramsArg = mockedRunAgentTask.mock.calls[0]?.[2] as {
+      maxSteps?: number;
+    };
+    expect(taskStateArg.task).toContain("summarize inventory");
+    expect(taskStateArg.task).not.toContain("  summarize inventory  ");
+    expect(paramsArg.maxSteps).toBe(2);
+  });
+
+  it("returns empty pprint output for malformed action payloads", () => {
+    const agent = new HyperAgent({
+      llm: createMockLLM(),
+    });
+    const badAction = {
+      get type(): string {
+        throw new Error("type trap");
+      },
+      params: {},
+    };
+
+    expect(agent.pprintAction(badAction as never)).toBe("");
+  });
+
+  it("returns empty pprint output when custom pprintAction throws", () => {
+    const warnSpy = jest.spyOn(console, "warn").mockImplementation(() => {});
+    const throwingAction: AgentActionDefinition = {
+      type: "customPprint",
+      actionParams: z.object({}),
+      run: async () => ({ success: true, message: "ok" }),
+      pprintAction: () => {
+        throw new Error("pprint failed");
+      },
+    };
+    const agent = new HyperAgent({
+      llm: createMockLLM(),
+      debug: true,
+      customActions: [throwingAction],
+    });
+
+    try {
+      expect(
+        agent.pprintAction({
+          type: "customPprint",
+          params: {},
+        } as never)
+      ).toBe("");
+      expect(warnSpy).toHaveBeenCalledWith(
+        '[HyperAgent] Failed to pprint action "customPprint": pprint failed'
+      );
+    } finally {
+      warnSpy.mockRestore();
+    }
+  });
+
+  it("truncates oversized pprint diagnostics", () => {
+    const throwingAction: AgentActionDefinition = {
+      type: "customPprint",
+      actionParams: z.object({}),
+      run: async () => ({ success: true, message: "ok" }),
+      pprintAction: () => {
+        throw new Error("x".repeat(2_000));
+      },
+    };
+    const warnSpy = jest.spyOn(console, "warn").mockImplementation(() => {});
+    const agent = new HyperAgent({
+      llm: createMockLLM(),
+      debug: true,
+      customActions: [throwingAction],
+    });
+
+    try {
+      expect(
+        agent.pprintAction({
+          type: "customPprint",
+          params: {},
+        } as never)
+      ).toBe("");
+      const firstMessage = String(warnSpy.mock.calls[0]?.[0] ?? "");
+      expect(firstMessage).toContain("[truncated");
+    } finally {
+      warnSpy.mockRestore();
+    }
+  });
+
+  it("creates scripts from iterable action-cache steps", () => {
+    const agent = new HyperAgent({
+      llm: createMockLLM(),
+    });
+    const step: ActionCacheEntry = {
+      stepIndex: 0,
+      instruction: "click login",
+      elementId: "0-1",
+      method: "click",
+      arguments: [],
+      frameIndex: 0,
+      xpath: "//button[1]",
+      actionType: "actElement",
+      success: true,
+      message: "cached",
+    };
+    const script = agent.createScriptFromActionCache(
+      new Set([step]) as unknown as ActionCacheEntry[],
+      "  task-id  "
+    );
+
+    expect(script).toContain("performClick");
+  });
+
+  it("throws readable errors when action-cache steps are unreadable", () => {
+    const agent = new HyperAgent({
+      llm: createMockLLM(),
+    });
+    const trappedSteps = new Proxy(
+      {},
+      {
+        get: (_target, prop) => {
+          if (prop === Symbol.iterator) {
+            throw new Error("steps iterator trap");
+          }
+          return undefined;
+        },
+      }
+    ) as unknown as ActionCacheEntry[];
+
+    expect(() => agent.createScriptFromActionCache(trappedSteps)).toThrow(
+      "Failed to read action cache steps: steps iterator trap"
+    );
+  });
+
+  it("truncates oversized createScriptFromActionCache diagnostics", () => {
+    const agent = new HyperAgent({
+      llm: createMockLLM(),
+    });
+    const trappedSteps = new Proxy(
+      {},
+      {
+        get: (_target, prop) => {
+          if (prop === Symbol.iterator) {
+            throw new Error("x".repeat(2_000));
+          }
+          return undefined;
+        },
+      }
+    ) as unknown as ActionCacheEntry[];
+
+    expect(() => agent.createScriptFromActionCache(trappedSteps)).toThrow(
+      /\[truncated/
+    );
+  });
+
+  it("executeTaskAsync tolerates context listener attachment failures", async () => {
+    const mockedRunAgentTask = jest.mocked(runAgentTask);
+    mockedRunAgentTask.mockResolvedValue({
+      taskId: "task-id",
+      status: TaskStatus.COMPLETED,
+      steps: [],
+      output: "done",
+      actionCache: {
+        taskId: "task-id",
+        createdAt: new Date().toISOString(),
+        status: TaskStatus.COMPLETED,
+        steps: [],
+      },
+    });
+
+    const agent = new HyperAgent({
+      llm: createMockLLM(),
+    });
+    const internalAgent = agent as unknown as {
+      context: { on: (event: string, handler: unknown) => void } | null;
+    };
+    internalAgent.context = {
+      on: () => {
+        throw new Error("context on trap");
+      },
+    };
+
+    const fakePage = {} as unknown as Page;
+    const task = await agent.executeTaskAsync("test task", undefined, fakePage);
+
+    await expect(task.result).resolves.toMatchObject({
+      status: TaskStatus.COMPLETED,
+      output: "done",
+    });
+  });
+
+  it("executeTaskAsync tolerates context listener getter traps", async () => {
+    const mockedRunAgentTask = jest.mocked(runAgentTask);
+    mockedRunAgentTask.mockResolvedValue({
+      taskId: "task-id",
+      status: TaskStatus.COMPLETED,
+      steps: [],
+      output: "done",
+      actionCache: {
+        taskId: "task-id",
+        createdAt: new Date().toISOString(),
+        status: TaskStatus.COMPLETED,
+        steps: [],
+      },
+    });
+
+    const agent = new HyperAgent({
+      llm: createMockLLM(),
+    });
+    const internalAgent = agent as unknown as {
+      context: { on: (event: string, handler: unknown) => void } | null;
+    };
+    internalAgent.context = new Proxy(
+      {},
+      {
+        get: (_target, prop) => {
+          if (prop === "on") {
+            throw new Error("context on getter trap");
+          }
+          return undefined;
+        },
+      }
+    ) as { on: (event: string, handler: unknown) => void };
+
+    const fakePage = {} as unknown as Page;
+    const task = await agent.executeTaskAsync("test task", undefined, fakePage);
+
+    await expect(task.result).resolves.toMatchObject({
+      status: TaskStatus.COMPLETED,
+      output: "done",
+    });
+  });
+
+  it("logs unavailable task-listener attach method in debug mode", async () => {
+    const mockedRunAgentTask = jest.mocked(runAgentTask);
+    mockedRunAgentTask.mockResolvedValue({
+      taskId: "task-id",
+      status: TaskStatus.COMPLETED,
+      steps: [],
+      output: "done",
+      actionCache: {
+        taskId: "task-id",
+        createdAt: new Date().toISOString(),
+        status: TaskStatus.COMPLETED,
+        steps: [],
+      },
+    });
+
+    const warnSpy = jest.spyOn(console, "warn").mockImplementation(() => {});
+    const agent = new HyperAgent({
+      llm: createMockLLM(),
+      debug: true,
+    });
+    const internalAgent = agent as unknown as {
+      context: { on: (event: string, handler: unknown) => void } | null;
+    };
+    internalAgent.context = new Proxy(
+      {},
+      {
+        get: (_target, prop) => {
+          if (prop === "on") {
+            throw new Error("context on getter trap");
+          }
+          return undefined;
+        },
+      }
+    ) as { on: (event: string, handler: unknown) => void };
+
+    try {
+      const fakePage = {} as unknown as Page;
+      const task = await agent.executeTaskAsync("test task", undefined, fakePage);
+      await expect(task.result).resolves.toMatchObject({
+        status: TaskStatus.COMPLETED,
+      });
+      expect(warnSpy).toHaveBeenCalledWith(
+        "[HyperAgent] Failed to attach task page listener: context.on is unavailable"
+      );
+    } finally {
+      warnSpy.mockRestore();
+    }
+  });
+
+  it("truncates oversized context-listener attach diagnostics", async () => {
+    const mockedRunAgentTask = jest.mocked(runAgentTask);
+    mockedRunAgentTask.mockResolvedValue({
+      taskId: "task-id",
+      status: TaskStatus.COMPLETED,
+      steps: [],
+      output: "done",
+      actionCache: {
+        taskId: "task-id",
+        createdAt: new Date().toISOString(),
+        status: TaskStatus.COMPLETED,
+        steps: [],
+      },
+    });
+
+    const agent = new HyperAgent({
+      llm: createMockLLM(),
+      debug: true,
+    });
+    const warnSpy = jest.spyOn(console, "warn").mockImplementation(() => {});
+    const internalAgent = agent as unknown as {
+      context: { on: (event: string, handler: unknown) => void } | null;
+    };
+    internalAgent.context = {
+      on: () => {
+        throw new Error("x".repeat(2_000));
+      },
+    };
+
+    const fakePage = {} as unknown as Page;
+    try {
+      const task = await agent.executeTaskAsync("test task", undefined, fakePage);
+      await expect(task.result).resolves.toMatchObject({
+        status: TaskStatus.COMPLETED,
+      });
+      const warnedMessage = String(warnSpy.mock.calls[0]?.[0] ?? "");
+      expect(warnedMessage).toContain("[truncated");
+    } finally {
+      warnSpy.mockRestore();
+    }
+  });
+
+  it("executeTask tolerates context listener detach failures", async () => {
+    const mockedRunAgentTask = jest.mocked(runAgentTask);
+    mockedRunAgentTask.mockResolvedValue({
+      taskId: "task-id",
+      status: TaskStatus.COMPLETED,
+      steps: [],
+      output: "done",
+      actionCache: {
+        taskId: "task-id",
+        createdAt: new Date().toISOString(),
+        status: TaskStatus.COMPLETED,
+        steps: [],
+      },
+    });
+
+    const on = jest.fn();
+    const off = jest.fn(() => {
+      throw new Error("context off trap");
+    });
+    const agent = new HyperAgent({
+      llm: createMockLLM(),
+    });
+    const internalAgent = agent as unknown as {
+      context: {
+        on: typeof on;
+        off: typeof off;
+      } | null;
+    };
+    internalAgent.context = { on, off };
+
+    const fakePage = {} as unknown as Page;
+    const result = await agent.executeTask("test task", undefined, fakePage);
+
+    expect(result.status).toBe(TaskStatus.COMPLETED);
+    expect(off).toHaveBeenCalledWith("page", expect.any(Function));
+  });
+
+  it("executeTask tolerates context listener detach getter traps", async () => {
+    const mockedRunAgentTask = jest.mocked(runAgentTask);
+    mockedRunAgentTask.mockResolvedValue({
+      taskId: "task-id",
+      status: TaskStatus.COMPLETED,
+      steps: [],
+      output: "done",
+      actionCache: {
+        taskId: "task-id",
+        createdAt: new Date().toISOString(),
+        status: TaskStatus.COMPLETED,
+        steps: [],
+      },
+    });
+
+    const on = jest.fn();
+    const agent = new HyperAgent({
+      llm: createMockLLM(),
+    });
+    const internalAgent = agent as unknown as {
+      context: {
+        on: typeof on;
+        off?: () => void;
+      } | null;
+    };
+    internalAgent.context = new Proxy(
+      { on },
+      {
+        get: (target, prop, receiver) => {
+          if (prop === "off") {
+            throw new Error("context off getter trap");
+          }
+          return Reflect.get(target, prop, receiver);
+        },
+      }
+    ) as {
+      on: typeof on;
+      off?: () => void;
+    };
+
+    const fakePage = {} as unknown as Page;
+    const result = await agent.executeTask("test task", undefined, fakePage);
+
+    expect(result.status).toBe(TaskStatus.COMPLETED);
+  });
+
+  it("logs unavailable task-listener detach method in debug mode", async () => {
+    const mockedRunAgentTask = jest.mocked(runAgentTask);
+    mockedRunAgentTask.mockResolvedValue({
+      taskId: "task-id",
+      status: TaskStatus.COMPLETED,
+      steps: [],
+      output: "done",
+      actionCache: {
+        taskId: "task-id",
+        createdAt: new Date().toISOString(),
+        status: TaskStatus.COMPLETED,
+        steps: [],
+      },
+    });
+
+    const on = jest.fn();
+    const warnSpy = jest.spyOn(console, "warn").mockImplementation(() => {});
+    const agent = new HyperAgent({
+      llm: createMockLLM(),
+      debug: true,
+    });
+    const internalAgent = agent as unknown as {
+      context: {
+        on: typeof on;
+        off?: () => void;
+      } | null;
+    };
+    internalAgent.context = new Proxy(
+      { on },
+      {
+        get: (target, prop, receiver) => {
+          if (prop === "off") {
+            throw new Error("context off getter trap");
+          }
+          return Reflect.get(target, prop, receiver);
+        },
+      }
+    ) as {
+      on: typeof on;
+      off?: () => void;
+    };
+
+    try {
+      const fakePage = {} as unknown as Page;
+      const result = await agent.executeTask("test task", undefined, fakePage);
+      expect(result.status).toBe(TaskStatus.COMPLETED);
+      expect(warnSpy).toHaveBeenCalledWith(
+        "[HyperAgent] Failed to detach task page listener: context.off is unavailable"
+      );
+    } finally {
+      warnSpy.mockRestore();
+    }
+  });
+
+  it("handles trap-prone tab URL reads in task page-follow callback", async () => {
+    const mockedRunAgentTask = jest.mocked(runAgentTask);
+    mockedRunAgentTask.mockResolvedValue({
+      taskId: "task-id",
+      status: TaskStatus.COMPLETED,
+      steps: [],
+      output: "done",
+      actionCache: {
+        taskId: "task-id",
+        createdAt: new Date().toISOString(),
+        status: TaskStatus.COMPLETED,
+        steps: [],
+      },
+    });
+
+    const on = jest.fn();
+    const off = jest.fn();
+    const logSpy = jest.spyOn(console, "log").mockImplementation(() => {});
+    const agent = new HyperAgent({
+      llm: createMockLLM(),
+      debug: true,
+    });
+    const internalAgent = agent as unknown as {
+      context: {
+        on: typeof on;
+        off: typeof off;
+      } | null;
+    };
+    internalAgent.context = { on, off };
+
+    const fakePage = {} as unknown as Page;
+    const task = await agent.executeTaskAsync("test task", undefined, fakePage);
+    const onPageHandler = on.mock.calls[0]?.[1] as (page: Page) => Promise<void>;
+    const popupPage = {
+      opener: async () => fakePage,
+      url: () => {
+        throw new Error("url trap");
+      },
+    } as unknown as Page;
+
+    try {
+      await expect(onPageHandler(popupPage)).resolves.toBeUndefined();
+      await expect(task.result).resolves.toMatchObject({
+        status: TaskStatus.COMPLETED,
+      });
+    } finally {
+      logSpy.mockRestore();
+    }
+  });
+
+  it("getCurrentPage tolerates context.pages traps when current page exists", async () => {
+    const page = {
+      on: jest.fn(),
+      off: jest.fn(),
+      context: () => ({
+        on: jest.fn(),
+        off: jest.fn(),
+        pages: () => [page],
+      }),
+      isClosed: () => false,
+      url: () => "https://example.com",
+    } as unknown as Page;
+    const newPage = jest.fn();
+    const agent = new HyperAgent({
+      llm: createMockLLM(),
+    });
+    const internalAgent = agent as unknown as {
+      browser: object | null;
+      context: { pages: () => Page[]; newPage: typeof newPage } | null;
+      _currentPage: Page | null;
+    };
+    internalAgent.browser = {};
+    internalAgent.context = {
+      pages: () => {
+        throw new Error("pages trap");
+      },
+      newPage,
+    };
+    internalAgent._currentPage = page;
+
+    const currentPage = await agent.getCurrentPage();
+
+    expect(currentPage).toBe(page);
+    expect(newPage).not.toHaveBeenCalled();
+  });
+
+  it("getCurrentPage surfaces readable errors when newPage creation fails", async () => {
+    const agent = new HyperAgent({
+      llm: createMockLLM(),
+    });
+    const internalAgent = agent as unknown as {
+      browser: object | null;
+      context: {
+        pages: () => Page[];
+        newPage: () => Promise<Page>;
+      } | null;
+    };
+    internalAgent.browser = {};
+    internalAgent.context = {
+      pages: () => [],
+      newPage: async () => {
+        throw new Error("new current page trap");
+      },
+    };
+
+    await expect(agent.getCurrentPage()).rejects.toThrow(
+      "Failed to create current page: new current page trap"
+    );
+  });
+
+  it("getCurrentPage surfaces readable errors when context.newPage getter traps", async () => {
+    const agent = new HyperAgent({
+      llm: createMockLLM(),
+    });
+    const internalAgent = agent as unknown as {
+      browser: object | null;
+      context: unknown;
+    };
+    internalAgent.browser = {};
+    internalAgent.context = new Proxy(
+      {
+        pages: () => [],
+      },
+      {
+        get: (target, prop, receiver) => {
+          if (prop === "newPage") {
+            throw new Error("new current page getter trap");
+          }
+          return Reflect.get(target, prop, receiver);
+        },
+      }
+    );
+
+    await expect(agent.getCurrentPage()).rejects.toThrow(
+      "Failed to create current page: failed to read context.newPage: new current page getter trap"
+    );
+  });
+
+  it("getCurrentPage surfaces explicit error when context.newPage is unavailable", async () => {
+    const agent = new HyperAgent({
+      llm: createMockLLM(),
+    });
+    const internalAgent = agent as unknown as {
+      browser: object | null;
+      context: {
+        pages: () => Page[];
+      } | null;
+    };
+    internalAgent.browser = {};
+    internalAgent.context = {
+      pages: () => [],
+    };
+
+    await expect(agent.getCurrentPage()).rejects.toThrow(
+      "Failed to create current page: context.newPage is unavailable"
+    );
+  });
+
+  it("task controls return safe status when task state traps throw", async () => {
+    const mockedRunAgentTask = jest.mocked(runAgentTask);
+    let resolveTaskResult!: (value: AgentTaskOutput) => void;
+    const pendingResult = new Promise<AgentTaskOutput>((resolve) => {
+      resolveTaskResult = resolve;
+    });
+    mockedRunAgentTask.mockReturnValue(pendingResult);
+
+    const agent = new HyperAgent({
+      llm: createMockLLM(),
+    });
+    const fakePage = {} as unknown as Page;
+    const task = await agent.executeTaskAsync("test task", undefined, fakePage);
+    const internalAgent = agent as unknown as {
+      tasks: Record<string, { status: TaskStatus }>;
+    };
+    const trappedTaskState = internalAgent.tasks[task.id];
+    Object.defineProperty(trappedTaskState, "status", {
+      configurable: true,
+      get: () => {
+        throw new Error("status trap");
+      },
+      set: () => {
+        throw new Error("status set trap");
+      },
+    });
+
+    expect(task.getStatus()).toBe(TaskStatus.FAILED);
+    expect(task.pause()).toBe(TaskStatus.FAILED);
+    expect(task.resume()).toBe(TaskStatus.FAILED);
+    expect(task.cancel()).toBe(TaskStatus.FAILED);
+
+    resolveTaskResult({
+      taskId: task.id,
+      status: TaskStatus.COMPLETED,
+      steps: [],
+      output: "done",
+      actionCache: {
+        taskId: task.id,
+        createdAt: new Date().toISOString(),
+        status: TaskStatus.COMPLETED,
+        steps: [],
+      },
+    });
+    await expect(task.result).resolves.toMatchObject({
+      status: TaskStatus.COMPLETED,
+    });
+  });
+
+  it("closeAgent tolerates trap-prone task status fields", async () => {
+    const agent = new HyperAgent({
+      llm: createMockLLM(),
+    });
+    const taskA = {
+      status: TaskStatus.RUNNING,
+    };
+    const internalAgent = agent as unknown as {
+      tasks: Record<string, { status: TaskStatus }>;
+    };
+    internalAgent.tasks["task-a"] = taskA;
+    const trappedTask = {};
+    Object.defineProperty(trappedTask, "status", {
+      configurable: true,
+      get: () => {
+        throw new Error("close status trap");
+      },
+      set: () => {
+        throw new Error("close status trap");
+      },
+    });
+    internalAgent.tasks["task-b"] = trappedTask as { status: TaskStatus };
+
+    await expect(agent.closeAgent()).resolves.toBeUndefined();
+    expect(taskA.status).toBe(TaskStatus.CANCELLED);
+    expect(internalAgent.tasks).toEqual({});
+  });
+
+  it("closeAgent closes browser provider when session exists without browser", async () => {
+    const close = jest.fn(async () => undefined);
+    const agent = new HyperAgent({
+      llm: createMockLLM(),
+    });
+    const internalAgent = agent as unknown as {
+      browser: null;
+      context: null;
+      browserProvider: {
+        close: typeof close;
+        getSession: () => unknown;
+      };
+    };
+    internalAgent.browser = null;
+    internalAgent.context = null;
+    internalAgent.browserProvider = {
+      close,
+      getSession: () => ({ id: "session-1" }),
+    };
+
+    await expect(agent.closeAgent()).resolves.toBeUndefined();
+    expect(close).toHaveBeenCalledTimes(1);
+  });
+
+  it("closeAgent clears stale current-page references", async () => {
+    const close = jest.fn(async () => undefined);
+    const stalePage = {} as unknown as Page;
+    const agent = new HyperAgent({
+      llm: createMockLLM(),
+    });
+    const internalAgent = agent as unknown as {
+      browser: object | null;
+      context: object | null;
+      _currentPage: Page | null;
+      browserProvider: {
+        close: typeof close;
+        getSession: () => unknown;
+      };
+    };
+    internalAgent.browser = {};
+    internalAgent.context = {};
+    internalAgent._currentPage = stalePage;
+    internalAgent.browserProvider = {
+      close,
+      getSession: () => ({ id: "session-1" }),
+    };
+
+    await expect(agent.closeAgent()).resolves.toBeUndefined();
+    expect(close).toHaveBeenCalledTimes(1);
+    expect(internalAgent._currentPage).toBeNull();
+  });
+
+  it("closeAgent clears internal async task-result cache", async () => {
+    const agent = new HyperAgent({
+      llm: createMockLLM(),
+    });
+    const internalAgent = agent as unknown as {
+      taskResults: Record<string, Promise<AgentTaskOutput>>;
+      actionCacheByTaskId: Record<string, unknown>;
+    };
+    internalAgent.taskResults = {
+      "task-a": Promise.resolve({
+        taskId: "task-a",
+        status: TaskStatus.COMPLETED,
+        steps: [],
+        output: "done",
+        actionCache: {
+          taskId: "task-a",
+          createdAt: new Date().toISOString(),
+          status: TaskStatus.COMPLETED,
+          steps: [],
+        },
+      }),
+    };
+    internalAgent.actionCacheByTaskId = {
+      "task-a": {
+        taskId: "task-a",
+        createdAt: new Date().toISOString(),
+        status: TaskStatus.COMPLETED,
+        steps: [],
+      },
+    };
+
+    await expect(agent.closeAgent()).resolves.toBeUndefined();
+    expect(internalAgent.taskResults).toEqual({});
+    expect(internalAgent.actionCacheByTaskId).toEqual({});
+  });
+
+  it("closeAgent tolerates trapped cache-registry reset assignments", async () => {
+    const warnSpy = jest.spyOn(console, "warn").mockImplementation(() => {});
+    const agent = new HyperAgent({
+      llm: createMockLLM(),
+      debug: true,
+    });
+    const internalAgent = agent as unknown as {
+      tasks: Record<string, TaskState>;
+      taskResults: Record<string, Promise<AgentTaskOutput>>;
+      actionCacheByTaskId: Record<string, unknown>;
+      actionCacheTaskOrder: string[];
+    };
+    const taskStore: Record<string, TaskState> = {
+      "task-a": {
+        id: "task-a",
+        task: "example",
+        status: TaskStatus.RUNNING,
+        startingPage: {} as Page,
+        steps: [],
+      },
+    };
+    const taskResultsStore: Record<string, Promise<AgentTaskOutput>> = {
+      "task-a": Promise.resolve({
+        taskId: "task-a",
+        status: TaskStatus.COMPLETED,
+        steps: [],
+        output: "done",
+        actionCache: {
+          taskId: "task-a",
+          createdAt: new Date().toISOString(),
+          status: TaskStatus.COMPLETED,
+          steps: [],
+        },
+      }),
+    };
+    const actionCacheStore: Record<string, unknown> = {
+      "task-a": {
+        taskId: "task-a",
+        createdAt: new Date().toISOString(),
+        status: TaskStatus.COMPLETED,
+        steps: [],
+      },
+    };
+    const actionCacheOrderStore: string[] = ["task-a"];
+
+    Object.defineProperty(internalAgent, "tasks", {
+      configurable: true,
+      get: () => taskStore,
+      set: () => {
+        throw new Error("task reset trap");
+      },
+    });
+    Object.defineProperty(internalAgent, "taskResults", {
+      configurable: true,
+      get: () => taskResultsStore,
+      set: () => {
+        throw new Error("task results reset trap");
+      },
+    });
+    Object.defineProperty(internalAgent, "actionCacheByTaskId", {
+      configurable: true,
+      get: () => actionCacheStore,
+      set: () => {
+        throw new Error("action cache reset trap");
+      },
+    });
+    Object.defineProperty(internalAgent, "actionCacheTaskOrder", {
+      configurable: true,
+      get: () => actionCacheOrderStore,
+      set: () => {
+        throw new Error("action cache order reset trap");
+      },
+    });
+
+    try {
+      await expect(agent.closeAgent()).resolves.toBeUndefined();
+      expect(taskStore).toEqual({});
+      expect(taskResultsStore).toEqual({});
+      expect(actionCacheStore).toEqual({});
+      expect(actionCacheOrderStore).toEqual([]);
+      expect(warnSpy).toHaveBeenCalledWith(
+        expect.stringContaining("Failed to reset task registry during close")
+      );
+      expect(warnSpy).toHaveBeenCalledWith(
+        expect.stringContaining(
+          "Failed to reset task-result registry during close"
+        )
+      );
+      expect(warnSpy).toHaveBeenCalledWith(
+        expect.stringContaining(
+          "Failed to reset action-cache registry during close"
+        )
+      );
+      expect(warnSpy).toHaveBeenCalledWith(
+        expect.stringContaining("Failed to reset action-cache order during close")
+      );
+    } finally {
+      warnSpy.mockRestore();
+    }
+  });
+
+  it("closeAgent tolerates trapped task-registry enumeration", async () => {
+    const close = jest.fn(async () => undefined);
+    const warnSpy = jest.spyOn(console, "warn").mockImplementation(() => {});
+    const agent = new HyperAgent({
+      llm: createMockLLM(),
+      debug: true,
+    });
+    const internalAgent = agent as unknown as {
+      tasks: Record<string, { status: TaskStatus }>;
+      browserProvider: {
+        close: typeof close;
+        getSession: () => unknown;
+      };
+      browser: null;
+      context: null;
+    };
+    internalAgent.tasks = new Proxy(
+      {
+        "task-a": { status: TaskStatus.RUNNING },
+      },
+      {
+        ownKeys: () => {
+          throw new Error("task entries trap");
+        },
+      }
+    ) as unknown as Record<string, { status: TaskStatus }>;
+    internalAgent.browserProvider = {
+      close,
+      getSession: () => ({ id: "session-1" }),
+    };
+    internalAgent.browser = null;
+    internalAgent.context = null;
+
+    try {
+      await expect(agent.closeAgent()).resolves.toBeUndefined();
+      expect(close).toHaveBeenCalledTimes(1);
+      expect(warnSpy).toHaveBeenCalledWith(
+        expect.stringContaining("Failed to enumerate tasks during close")
+      );
+    } finally {
+      warnSpy.mockRestore();
+    }
+  });
+
+  it("closeAgent truncates oversized lifecycle diagnostics", async () => {
+    const warnSpy = jest.spyOn(console, "warn").mockImplementation(() => {});
+    const agent = new HyperAgent({
+      llm: createMockLLM(),
+    });
+    const internalAgent = agent as unknown as {
+      browserProvider: {
+        close: () => Promise<void>;
+        getSession: () => unknown;
+      };
+      browser: null;
+      context: null;
+    };
+    internalAgent.browserProvider = {
+      close: async () => {
+        throw new Error("x".repeat(2_000));
+      },
+      getSession: () => ({ id: "session-1" }),
+    };
+    internalAgent.browser = null;
+    internalAgent.context = null;
+
+    try {
+      await expect(agent.closeAgent()).resolves.toBeUndefined();
+      const warnedMessages = warnSpy.mock.calls.map((call) => String(call[0] ?? ""));
+      expect(warnedMessages.some((message) => message.includes("[truncated"))).toBe(
+        true
+      );
+    } finally {
+      warnSpy.mockRestore();
+    }
+  });
+
+  it("closeAgent sanitizes control characters in lifecycle diagnostics", async () => {
+    const warnSpy = jest.spyOn(console, "warn").mockImplementation(() => {});
+    const agent = new HyperAgent({
+      llm: createMockLLM(),
+    });
+    const internalAgent = agent as unknown as {
+      browserProvider: {
+        close: () => Promise<void>;
+        getSession: () => unknown;
+      };
+      browser: null;
+      context: null;
+    };
+    internalAgent.browserProvider = {
+      close: async () => {
+        throw new Error("close\u0000\ntrap");
+      },
+      getSession: () => ({ id: "session-1" }),
+    };
+    internalAgent.browser = null;
+    internalAgent.context = null;
+
+    try {
+      await expect(agent.closeAgent()).resolves.toBeUndefined();
+      const warnedMessages = warnSpy.mock.calls.map((call) => String(call[0] ?? ""));
+      expect(
+        warnedMessages.some(
+          (message) =>
+            message.includes("close trap") &&
+            !message.includes("\u0000") &&
+            !message.includes("\n")
+        )
+      ).toBe(true);
+    } finally {
+      warnSpy.mockRestore();
+    }
+  });
+
+  it("task controls stay cancelled after close despite late task-state mutations", async () => {
+    const mockedRunAgentTask = jest.mocked(runAgentTask);
+    let resolveTask!: (value: AgentTaskOutput) => void;
+    let capturedTaskState: TaskState | undefined;
+    mockedRunAgentTask.mockImplementation((_, taskState) => {
+      capturedTaskState = taskState;
+      return new Promise<AgentTaskOutput>((resolve) => {
+        resolveTask = resolve;
+      });
+    });
+
+    const agent = new HyperAgent({
+      llm: createMockLLM(),
+    });
+    const fakePage = {} as unknown as Page;
+    const task = await agent.executeTaskAsync("shutdown control", undefined, fakePage);
+
+    await expect(agent.closeAgent()).resolves.toBeUndefined();
+    expect(task.getStatus()).toBe(TaskStatus.CANCELLED);
+    if (capturedTaskState) {
+      capturedTaskState.status = TaskStatus.RUNNING;
+    }
+    expect(task.getStatus()).toBe(TaskStatus.CANCELLED);
+    expect(task.pause()).toBe(TaskStatus.CANCELLED);
+    expect(task.resume()).toBe(TaskStatus.CANCELLED);
+    expect(task.cancel()).toBe(TaskStatus.CANCELLED);
+
+    resolveTask({
+      taskId: task.id,
+      status: TaskStatus.COMPLETED,
+      steps: [],
+      output: "done",
+      actionCache: {
+        taskId: task.id,
+        createdAt: new Date().toISOString(),
+        status: TaskStatus.COMPLETED,
+        steps: [],
+      },
+    });
+    await expect(task.result).resolves.toMatchObject({
+      status: TaskStatus.CANCELLED,
+    });
+  });
+
+  it("task controls keep completed status after settlement despite late mutations", async () => {
+    const mockedRunAgentTask = jest.mocked(runAgentTask);
+    let resolveTask!: (value: AgentTaskOutput) => void;
+    let capturedTaskState: TaskState | undefined;
+    mockedRunAgentTask.mockImplementation((_, taskState) => {
+      capturedTaskState = taskState;
+      return new Promise<AgentTaskOutput>((resolve) => {
+        resolveTask = resolve;
+      });
+    });
+
+    const agent = new HyperAgent({
+      llm: createMockLLM(),
+    });
+    const fakePage = {} as unknown as Page;
+    const task = await agent.executeTaskAsync("complete control", undefined, fakePage);
+
+    resolveTask({
+      taskId: task.id,
+      status: TaskStatus.COMPLETED,
+      steps: [],
+      output: "done",
+      actionCache: {
+        taskId: task.id,
+        createdAt: new Date().toISOString(),
+        status: TaskStatus.COMPLETED,
+        steps: [],
+      },
+    });
+
+    await expect(task.result).resolves.toMatchObject({
+      status: TaskStatus.COMPLETED,
+    });
+    expect(task.getStatus()).toBe(TaskStatus.COMPLETED);
+    if (capturedTaskState) {
+      capturedTaskState.status = TaskStatus.RUNNING;
+    }
+    expect(task.getStatus()).toBe(TaskStatus.COMPLETED);
+    expect(task.cancel()).toBe(TaskStatus.COMPLETED);
+    expect(task.pause()).toBe(TaskStatus.COMPLETED);
+    expect(task.resume()).toBe(TaskStatus.COMPLETED);
+
+    await expect(agent.closeAgent()).resolves.toBeUndefined();
+    expect(task.getStatus()).toBe(TaskStatus.COMPLETED);
+    expect(task.cancel()).toBe(TaskStatus.COMPLETED);
+    expect(task.pause()).toBe(TaskStatus.COMPLETED);
+    expect(task.resume()).toBe(TaskStatus.COMPLETED);
+  });
+
+  it("task controls keep failed status after settlement despite late mutations", async () => {
+    const mockedRunAgentTask = jest.mocked(runAgentTask);
+    let rejectTask!: (error: unknown) => void;
+    let capturedTaskState: TaskState | undefined;
+    mockedRunAgentTask.mockImplementation((_, taskState) => {
+      capturedTaskState = taskState;
+      return new Promise<AgentTaskOutput>((_, reject) => {
+        rejectTask = reject;
+      });
+    });
+
+    const agent = new HyperAgent({
+      llm: createMockLLM(),
+    });
+    const fakePage = {} as unknown as Page;
+    const task = await agent.executeTaskAsync("fail control", undefined, fakePage);
+
+    rejectTask(new Error("control failure"));
+    await expect(task.result).rejects.toBeInstanceOf(HyperagentTaskError);
+    expect(task.getStatus()).toBe(TaskStatus.FAILED);
+    if (capturedTaskState) {
+      capturedTaskState.status = TaskStatus.RUNNING;
+    }
+    expect(task.getStatus()).toBe(TaskStatus.FAILED);
+    expect(task.cancel()).toBe(TaskStatus.FAILED);
+    expect(task.pause()).toBe(TaskStatus.FAILED);
+    expect(task.resume()).toBe(TaskStatus.FAILED);
+
+    await expect(agent.closeAgent()).resolves.toBeUndefined();
+    expect(task.getStatus()).toBe(TaskStatus.FAILED);
+    expect(task.cancel()).toBe(TaskStatus.FAILED);
+    expect(task.pause()).toBe(TaskStatus.FAILED);
+    expect(task.resume()).toBe(TaskStatus.FAILED);
+  });
+
+  it("task controls keep cancelled status after manual cancellation settles", async () => {
+    const mockedRunAgentTask = jest.mocked(runAgentTask);
+    let resolveTask!: (value: AgentTaskOutput) => void;
+    let capturedTaskState: TaskState | undefined;
+    mockedRunAgentTask.mockImplementation((_, taskState) => {
+      capturedTaskState = taskState;
+      return new Promise<AgentTaskOutput>((resolve) => {
+        resolveTask = resolve;
+      });
+    });
+
+    const agent = new HyperAgent({
+      llm: createMockLLM(),
+    });
+    const fakePage = {} as unknown as Page;
+    const task = await agent.executeTaskAsync("cancel control", undefined, fakePage);
+
+    expect(task.cancel()).toBe(TaskStatus.CANCELLED);
+    resolveTask({
+      taskId: task.id,
+      status: TaskStatus.COMPLETED,
+      steps: [],
+      output: "done",
+      actionCache: {
+        taskId: task.id,
+        createdAt: new Date().toISOString(),
+        status: TaskStatus.COMPLETED,
+        steps: [],
+      },
+    });
+
+    await expect(task.result).resolves.toMatchObject({
+      status: TaskStatus.CANCELLED,
+      output: "Task was cancelled",
+    });
+    expect(task.getStatus()).toBe(TaskStatus.CANCELLED);
+    if (capturedTaskState) {
+      capturedTaskState.status = TaskStatus.RUNNING;
+    }
+    expect(task.getStatus()).toBe(TaskStatus.CANCELLED);
+    expect(task.cancel()).toBe(TaskStatus.CANCELLED);
+    expect(task.pause()).toBe(TaskStatus.CANCELLED);
+    expect(task.resume()).toBe(TaskStatus.CANCELLED);
+  });
+
+  it("closeAgent prevents in-flight async tasks from repopulating action cache", async () => {
+    const mockedRunAgentTask = jest.mocked(runAgentTask);
+    let resolveTask!: (value: AgentTaskOutput) => void;
+    mockedRunAgentTask.mockImplementation(
+      () =>
+        new Promise<AgentTaskOutput>((resolve) => {
+          resolveTask = resolve;
+        })
+    );
+
+    const agent = new HyperAgent({
+      llm: createMockLLM(),
+    });
+    const fakePage = {} as unknown as Page;
+    const task = await agent.executeTaskAsync("long running", undefined, fakePage);
+    const internalAgent = agent as unknown as {
+      actionCacheByTaskId: Record<string, unknown>;
+    };
+
+    await expect(agent.closeAgent()).resolves.toBeUndefined();
+    resolveTask({
+      taskId: task.id,
+      status: TaskStatus.COMPLETED,
+      steps: [],
+      output: "done",
+      actionCache: {
+        taskId: task.id,
+        createdAt: new Date().toISOString(),
+        status: TaskStatus.COMPLETED,
+        steps: [],
+      },
+    });
+    await expect(task.result).resolves.toMatchObject({
+      status: TaskStatus.CANCELLED,
+      output: "Task cancelled because agent was closed",
+      actionCache: { status: TaskStatus.CANCELLED },
+    });
+    expect(task.getStatus()).toBe(TaskStatus.CANCELLED);
+    expect(internalAgent.actionCacheByTaskId).toEqual({});
+  });
+
+  it("executeTask returns cancelled output when closeAgent occurs mid-run", async () => {
+    const mockedRunAgentTask = jest.mocked(runAgentTask);
+    let resolveTask!: (value: AgentTaskOutput) => void;
+    mockedRunAgentTask.mockImplementation(
+      () =>
+        new Promise<AgentTaskOutput>((resolve) => {
+          resolveTask = resolve;
+        })
+    );
+
+    const agent = new HyperAgent({
+      llm: createMockLLM(),
+    });
+    const fakePage = {} as unknown as Page;
+    const execution = agent.executeTask("sync long running", undefined, fakePage);
+
+    await expect(agent.closeAgent()).resolves.toBeUndefined();
+    resolveTask({
+      taskId: "sync-task",
+      status: TaskStatus.COMPLETED,
+      steps: [],
+      output: "done",
+      actionCache: {
+        taskId: "sync-task",
+        createdAt: new Date().toISOString(),
+        status: TaskStatus.COMPLETED,
+        steps: [],
+      },
+    });
+
+    await expect(execution).resolves.toMatchObject({
+      status: TaskStatus.CANCELLED,
+      output: "Task cancelled because agent was closed",
+      actionCache: { status: TaskStatus.CANCELLED },
+    });
+  });
+
+  it("uses default cancelled output for async tasks closed before completion", async () => {
+    const mockedRunAgentTask = jest.mocked(runAgentTask);
+    let resolveTask!: (value: AgentTaskOutput) => void;
+    mockedRunAgentTask.mockImplementation(
+      () =>
+        new Promise<AgentTaskOutput>((resolve) => {
+          resolveTask = resolve;
+        })
+    );
+
+    const agent = new HyperAgent({
+      llm: createMockLLM(),
+    });
+    const fakePage = {} as unknown as Page;
+    const task = await agent.executeTaskAsync(
+      "async no output",
+      undefined,
+      fakePage
+    );
+    await expect(agent.closeAgent()).resolves.toBeUndefined();
+
+    resolveTask({
+      taskId: task.id,
+      status: TaskStatus.COMPLETED,
+      steps: [],
+      output: undefined,
+      actionCache: {
+        taskId: task.id,
+        createdAt: new Date().toISOString(),
+        status: TaskStatus.COMPLETED,
+        steps: [],
+      },
+    });
+
+    await expect(task.result).resolves.toMatchObject({
+      status: TaskStatus.CANCELLED,
+      output: "Task cancelled because agent was closed",
+      actionCache: { status: TaskStatus.CANCELLED },
+    });
+  });
+
+  it("uses default cancelled output for sync tasks closed before completion", async () => {
+    const mockedRunAgentTask = jest.mocked(runAgentTask);
+    let resolveTask!: (value: AgentTaskOutput) => void;
+    mockedRunAgentTask.mockImplementation(
+      () =>
+        new Promise<AgentTaskOutput>((resolve) => {
+          resolveTask = resolve;
+        })
+    );
+
+    const agent = new HyperAgent({
+      llm: createMockLLM(),
+    });
+    const fakePage = {} as unknown as Page;
+    const execution = agent.executeTask("sync no output", undefined, fakePage);
+    await expect(agent.closeAgent()).resolves.toBeUndefined();
+
+    resolveTask({
+      taskId: "sync-no-output",
+      status: TaskStatus.COMPLETED,
+      steps: [],
+      output: undefined,
+      actionCache: {
+        taskId: "sync-no-output",
+        createdAt: new Date().toISOString(),
+        status: TaskStatus.COMPLETED,
+        steps: [],
+      },
+    });
+
+    await expect(execution).resolves.toMatchObject({
+      status: TaskStatus.CANCELLED,
+      output: "Task cancelled because agent was closed",
+      actionCache: { status: TaskStatus.CANCELLED },
+    });
+  });
+
+  it("closeAgent avoids noisy missing-task logs for late async failures", async () => {
+    const mockedRunAgentTask = jest.mocked(runAgentTask);
+    let rejectTask!: (error: unknown) => void;
+    mockedRunAgentTask.mockImplementation(
+      () =>
+        new Promise<AgentTaskOutput>((_, reject) => {
+          rejectTask = reject;
+        })
+    );
+
+    const errorSpy = jest.spyOn(console, "error").mockImplementation(() => {});
+    const agent = new HyperAgent({
+      llm: createMockLLM(),
+    });
+    const fakePage = {} as unknown as Page;
+    const task = await agent.executeTaskAsync("late failure", undefined, fakePage);
+
+    try {
+      await expect(agent.closeAgent()).resolves.toBeUndefined();
+      rejectTask(new Error("late boom"));
+      await expect(task.result).resolves.toMatchObject({
+        status: TaskStatus.CANCELLED,
+        output: "Task cancelled because agent was closed",
+        actionCache: { status: TaskStatus.CANCELLED },
+      });
+      expect(errorSpy).not.toHaveBeenCalledWith(
+        expect.stringContaining("Task state")
+      );
+    } finally {
+      errorSpy.mockRestore();
+    }
+  });
+});
diff --git a/src/agent/__tests__/mcp-lifecycle.test.ts b/src/agent/__tests__/mcp-lifecycle.test.ts
new file mode 100644
index 00000000..642cdc0e
--- /dev/null
+++ b/src/agent/__tests__/mcp-lifecycle.test.ts
@@ -0,0 +1,527 @@
+import { z } from "zod";
+import { HyperAgent } from "@/agent";
+import type { ActionType, AgentActionDefinition } from "@/types";
+import type { HyperAgentLLM } from "@/llm/types";
+
+const connectToServerMock = jest.fn();
+const disconnectServerMock = jest.fn();
+const disconnectMock = jest.fn();
+const getServerIdsMock: jest.Mock<string[], []> = jest.fn(() => []);
+const getServerInfoMock: jest.Mock<
+  Array<{ id: string; toolCount: number; toolNames: string[] }>,
+  []
+> = jest.fn(() => []);
+
+jest.mock("@/agent/mcp/client", () => ({
+  MCPClient: jest.fn().mockImplementation(() => ({
+    connectToServer: connectToServerMock,
+    disconnectServer: disconnectServerMock,
+    disconnect: disconnectMock,
+    getServerIds: getServerIdsMock,
+    getServerInfo: getServerInfoMock,
+  })),
+}));
+
+function createMockLLM(): HyperAgentLLM {
+  return {
+    invoke: async () => ({
+      role: "assistant",
+      content: "ok",
+    }),
+    invokeStructured: async () => ({
+      rawText: "{}",
+      parsed: null,
+    }),
+    getProviderId: () => "mock",
+    getModelId: () => "mock-model",
+    getCapabilities: () => ({
+      multimodal: false,
+      toolCalling: true,
+      jsonMode: true,
+    }),
+  };
+}
+
+function createAction(
+  type: string,
+  label: string
+): AgentActionDefinition<z.ZodObject<{}>> {
+  return {
+    type,
+    actionParams: z.object({}),
+    run: async () => ({
+      success: true,
+      message: "ok",
+    }),
+    pprintAction: () => label,
+  };
+}
+
+describe("MCP lifecycle action registration", () => {
+  beforeEach(() => {
+    jest.clearAllMocks();
+    connectToServerMock.mockReset();
+    disconnectServerMock.mockReset();
+    disconnectMock.mockReset();
+    getServerIdsMock.mockReset();
+    getServerInfoMock.mockReset();
+    getServerIdsMock.mockReturnValue([]);
+    getServerInfoMock.mockReturnValue([]);
+    disconnectServerMock.mockResolvedValue(undefined);
+    disconnectMock.mockResolvedValue(undefined);
+  });
+
+  it("registers MCP actions and removes them when server disconnects", async () => {
+    const mcpAction = createAction("mcp_custom_action", "custom");
+    connectToServerMock.mockResolvedValue({
+      serverId: "server-1",
+      actions: [mcpAction],
+    });
+
+    const agent = new HyperAgent({ llm: createMockLLM() });
+    const serverId = await agent.connectToMCPServer({
+      command: "echo",
+    });
+
+    expect(serverId).toBe("server-1");
+    expect(
+      agent.pprintAction({
+        type: "mcp_custom_action",
+        params: {},
+      } as ActionType)
+    ).toBe("custom");
+
+    getServerIdsMock.mockReturnValue(["server-1"]);
+    const disconnected = agent.disconnectFromMCPServer("server-1");
+    expect(disconnected).toBe(true);
+    expect(disconnectServerMock).toHaveBeenCalledWith("server-1");
+    expect(
+      agent.pprintAction({
+        type: "mcp_custom_action",
+        params: {},
+      } as ActionType)
+    ).toBe("");
+  });
+
+  it("rolls back partially registered MCP actions on registration failure", async () => {
+    const consoleErrorSpy = jest
+      .spyOn(console, "error")
+      .mockImplementation(() => {});
+    try {
+      const uniqueAction = createAction("mcp_unique_action", "unique");
+      const duplicateAction = createAction("goToUrl", "duplicate");
+      connectToServerMock.mockResolvedValue({
+        serverId: "server-2",
+        actions: [uniqueAction, duplicateAction],
+      });
+
+      const agent = new HyperAgent({ llm: createMockLLM() });
+      const connected = await agent.connectToMCPServer({
+        command: "echo",
+      });
+
+      expect(connected).toBeNull();
+      expect(disconnectServerMock).toHaveBeenCalledWith("server-2");
+      expect(
+        agent.pprintAction({
+          type: "mcp_unique_action",
+          params: {},
+        } as ActionType)
+      ).toBe("");
+      expect(consoleErrorSpy).toHaveBeenCalled();
+    } finally {
+      consoleErrorSpy.mockRestore();
+    }
+  });
+
+  it("returns false when disconnect is requested for unknown MCP server", async () => {
+    connectToServerMock.mockResolvedValue({
+      serverId: "server-a",
+      actions: [],
+    });
+    const agent = new HyperAgent({ llm: createMockLLM() });
+    await agent.connectToMCPServer({ command: "echo" });
+
+    getServerIdsMock.mockReturnValue(["server-a"]);
+    const disconnected = agent.disconnectFromMCPServer("missing-server");
+
+    expect(disconnected).toBe(false);
+    expect(disconnectServerMock).not.toHaveBeenCalled();
+  });
+
+  it("supports awaited MCP disconnect with async API", async () => {
+    const action = createAction("mcp_async_action", "async");
+    connectToServerMock.mockResolvedValue({
+      serverId: "server-async",
+      actions: [action],
+    });
+    const agent = new HyperAgent({ llm: createMockLLM() });
+    await agent.connectToMCPServer({ command: "echo" });
+
+    getServerIdsMock.mockReturnValue(["server-async"]);
+    const disconnected = await agent.disconnectFromMCPServerAsync(
+      "server-async"
+    );
+
+    expect(disconnected).toBe(true);
+    expect(disconnectServerMock).toHaveBeenCalledWith("server-async");
+    expect(
+      agent.pprintAction({ type: "mcp_async_action", params: {} } as ActionType)
+    ).toBe("");
+  });
+
+  it("returns false from async disconnect when transport cleanup fails", async () => {
+    const consoleErrorSpy = jest
+      .spyOn(console, "error")
+      .mockImplementation(() => {});
+    try {
+      const action = createAction("mcp_async_fail_action", "async-fail");
+      connectToServerMock.mockResolvedValue({
+        serverId: "server-async-fail",
+        actions: [action],
+      });
+      disconnectServerMock.mockRejectedValueOnce(new Error("disconnect failed"));
+
+      const agent = new HyperAgent({ llm: createMockLLM() });
+      await agent.connectToMCPServer({ command: "echo" });
+      getServerIdsMock.mockReturnValue(["server-async-fail"]);
+
+      const disconnected = await agent.disconnectFromMCPServerAsync(
+        "server-async-fail"
+      );
+
+      expect(disconnected).toBe(false);
+      expect(consoleErrorSpy).toHaveBeenCalled();
+      expect(
+        agent.pprintAction({
+          type: "mcp_async_fail_action",
+          params: {},
+        } as ActionType)
+      ).toBe("");
+    } finally {
+      consoleErrorSpy.mockRestore();
+    }
+  });
+
+  it("reinitializing MCP client removes previous MCP action registrations", async () => {
+    const actionA = createAction("mcp_action_a", "a");
+    const actionB = createAction("mcp_action_b", "b");
+
+    connectToServerMock
+      .mockResolvedValueOnce({
+        serverId: "server-a",
+        actions: [actionA],
+      })
+      .mockResolvedValueOnce({
+        serverId: "server-b",
+        actions: [actionB],
+      });
+
+    const agent = new HyperAgent({ llm: createMockLLM() });
+    await agent.connectToMCPServer({ command: "echo" });
+    expect(
+      agent.pprintAction({ type: "mcp_action_a", params: {} } as ActionType)
+    ).toBe("a");
+
+    await agent.initializeMCPClient({
+      servers: [{ command: "echo", id: "server-b" }],
+    });
+
+    expect(disconnectMock).toHaveBeenCalledTimes(1);
+    expect(
+      agent.pprintAction({ type: "mcp_action_a", params: {} } as ActionType)
+    ).toBe("");
+    expect(
+      agent.pprintAction({ type: "mcp_action_b", params: {} } as ActionType)
+    ).toBe("b");
+  });
+
+  it("closeAgent tolerates MCP disconnect failures and clears MCP actions", async () => {
+    const consoleWarnSpy = jest
+      .spyOn(console, "warn")
+      .mockImplementation(() => {});
+    try {
+      const action = createAction("mcp_close_action", "close");
+      connectToServerMock.mockResolvedValue({
+        serverId: "server-close",
+        actions: [action],
+      });
+      disconnectMock.mockRejectedValueOnce(new Error("close disconnect failed"));
+
+      const agent = new HyperAgent({ llm: createMockLLM() });
+      await agent.connectToMCPServer({ command: "echo" });
+      expect(
+        agent.pprintAction({ type: "mcp_close_action", params: {} } as ActionType)
+      ).toBe("close");
+
+      await expect(agent.closeAgent()).resolves.toBeUndefined();
+
+      expect(consoleWarnSpy).toHaveBeenCalled();
+      expect(
+        agent.pprintAction({ type: "mcp_close_action", params: {} } as ActionType)
+      ).toBe("");
+    } finally {
+      consoleWarnSpy.mockRestore();
+    }
+  });
+
+  it("closeAgent tolerates trapped MCP action-type registry iteration", async () => {
+    const agent = new HyperAgent({ llm: createMockLLM() });
+    const internalAgent = agent as unknown as {
+      mcpActionTypesByServer: Map<string, Set<string>>;
+    };
+    internalAgent.mcpActionTypesByServer = new Proxy(
+      new Map<string, Set<string>>([
+        ["server-1", new Set<string>(["mcp_action_a"])],
+      ]),
+      {
+        get: (target, prop, receiver) => {
+          if (prop === "values" || prop === "clear") {
+            throw new Error("registry trap");
+          }
+          const value = Reflect.get(target, prop, receiver);
+          return typeof value === "function" ? value.bind(target) : value;
+        },
+      }
+    ) as unknown as Map<string, Set<string>>;
+
+    await expect(agent.closeAgent()).resolves.toBeUndefined();
+  });
+
+  it("initializeMCPClient tolerates trapped action-type registry during reset", async () => {
+    const action = createAction("mcp_reinit_action", "reinit");
+    connectToServerMock.mockResolvedValue({
+      serverId: "server-reinit",
+      actions: [action],
+    });
+
+    const agent = new HyperAgent({ llm: createMockLLM() });
+    const internalAgent = agent as unknown as {
+      mcpClient: { disconnect: () => Promise<void> } | undefined;
+      mcpActionTypesByServer: Map<string, Set<string>>;
+    };
+    internalAgent.mcpClient = {
+      disconnect: async () => undefined,
+    };
+    internalAgent.mcpActionTypesByServer = new Proxy(
+      new Map<string, Set<string>>([
+        ["server-legacy", new Set<string>(["mcp_legacy_action"])],
+      ]),
+      {
+        get: (target, prop, receiver) => {
+          if (prop === "values" || prop === "clear") {
+            throw new Error("registry trap");
+          }
+          const value = Reflect.get(target, prop, receiver);
+          return typeof value === "function" ? value.bind(target) : value;
+        },
+      }
+    ) as unknown as Map<string, Set<string>>;
+
+    await expect(
+      agent.initializeMCPClient({
+        servers: [{ id: "server-reinit", command: "echo" }],
+      })
+    ).resolves.toBeUndefined();
+    expect(
+      agent.pprintAction({ type: "mcp_reinit_action", params: {} } as ActionType)
+    ).toBe("reinit");
+  });
+
+  it("initializeMCPClient ignores trap-prone servers config getters", async () => {
+    const agent = new HyperAgent({ llm: createMockLLM() });
+    const trappedConfig = new Proxy(
+      {},
+      {
+        get: (_target, prop) => {
+          if (prop === "servers") {
+            throw new Error("servers trap");
+          }
+          return undefined;
+        },
+      }
+    ) as unknown as { servers: Array<{ command: string }> };
+
+    await expect(
+      agent.initializeMCPClient(trappedConfig)
+    ).resolves.toBeUndefined();
+    expect(connectToServerMock).not.toHaveBeenCalled();
+  });
+
+  it("formats non-Error MCP connection failures consistently", async () => {
+    const consoleErrorSpy = jest
+      .spyOn(console, "error")
+      .mockImplementation(() => {});
+    try {
+      connectToServerMock.mockRejectedValueOnce({ reason: "connect exploded" });
+      const agent = new HyperAgent({ llm: createMockLLM() });
+
+      const serverId = await agent.connectToMCPServer({
+        command: "echo",
+      });
+
+      expect(serverId).toBeNull();
+      expect(consoleErrorSpy).toHaveBeenCalledWith(
+        'Failed to connect to MCP server: {"reason":"connect exploded"}'
+      );
+    } finally {
+      consoleErrorSpy.mockRestore();
+    }
+  });
+
+  it("handles trap-prone MCP server id diagnostics during initialization", async () => {
+    const consoleErrorSpy = jest
+      .spyOn(console, "error")
+      .mockImplementation(() => {});
+    const serverConfig = new Proxy(
+      { command: "echo" },
+      {
+        get: (target, prop, receiver) => {
+          if (prop === "id") {
+            throw new Error("id trap");
+          }
+          return Reflect.get(target, prop, receiver);
+        },
+      }
+    ) as unknown as { command: string; id: string };
+    connectToServerMock.mockRejectedValueOnce(new Error("connect fail"));
+    const agent = new HyperAgent({ llm: createMockLLM() });
+
+    try {
+      await expect(
+        agent.initializeMCPClient({
+          servers: [serverConfig],
+        })
+      ).resolves.toBeUndefined();
+      expect(consoleErrorSpy).toHaveBeenCalledWith(
+        expect.stringContaining("Failed to initialize MCP server unknown:")
+      );
+    } finally {
+      consoleErrorSpy.mockRestore();
+    }
+  });
+
+  it("truncates oversized MCP connection diagnostics", async () => {
+    const consoleErrorSpy = jest
+      .spyOn(console, "error")
+      .mockImplementation(() => {});
+    try {
+      connectToServerMock.mockRejectedValueOnce(new Error("x".repeat(2_000)));
+      const agent = new HyperAgent({ llm: createMockLLM() });
+
+      const serverId = await agent.connectToMCPServer({
+        command: "echo",
+      });
+
+      expect(serverId).toBeNull();
+      const errorMessage = String(consoleErrorSpy.mock.calls[0]?.[0] ?? "");
+      expect(errorMessage).toContain("[truncated");
+    } finally {
+      consoleErrorSpy.mockRestore();
+    }
+  });
+
+  it("truncates oversized MCP initialize-server diagnostics", async () => {
+    const consoleErrorSpy = jest
+      .spyOn(console, "error")
+      .mockImplementation(() => {});
+    try {
+      connectToServerMock.mockRejectedValueOnce(new Error("x".repeat(2_000)));
+      const agent = new HyperAgent({ llm: createMockLLM() });
+
+      await expect(
+        agent.initializeMCPClient({
+          servers: [{ id: "server-a", command: "echo" }],
+        })
+      ).resolves.toBeUndefined();
+
+      const errorMessage = String(consoleErrorSpy.mock.calls[0]?.[0] ?? "");
+      expect(errorMessage).toContain("[truncated");
+    } finally {
+      consoleErrorSpy.mockRestore();
+    }
+  });
+
+  it("returns early when MCP client construction fails during initialize", async () => {
+    const consoleErrorSpy = jest
+      .spyOn(console, "error")
+      .mockImplementation(() => {});
+    const { MCPClient } = jest.requireMock("@/agent/mcp/client") as {
+      MCPClient: jest.Mock;
+    };
+    MCPClient.mockImplementationOnce(() => {
+      throw new Error("client constructor trap");
+    });
+    const agent = new HyperAgent({ llm: createMockLLM() });
+
+    try {
+      await expect(
+        agent.initializeMCPClient({
+          servers: [{ id: "server-1", command: "echo" }],
+        })
+      ).resolves.toBeUndefined();
+      expect(connectToServerMock).not.toHaveBeenCalled();
+      expect(consoleErrorSpy).toHaveBeenCalledWith(
+        "Failed to initialize MCP client: client constructor trap"
+      );
+    } finally {
+      consoleErrorSpy.mockRestore();
+    }
+  });
+
+  it("returns null when MCP client construction fails during connect", async () => {
+    const consoleErrorSpy = jest
+      .spyOn(console, "error")
+      .mockImplementation(() => {});
+    const { MCPClient } = jest.requireMock("@/agent/mcp/client") as {
+      MCPClient: jest.Mock;
+    };
+    MCPClient.mockImplementationOnce(() => {
+      throw new Error("connect constructor trap");
+    });
+    const agent = new HyperAgent({ llm: createMockLLM() });
+
+    try {
+      const serverId = await agent.connectToMCPServer({
+        command: "echo",
+      });
+      expect(serverId).toBeNull();
+      expect(connectToServerMock).not.toHaveBeenCalled();
+      expect(consoleErrorSpy).toHaveBeenCalledWith(
+        "Failed to connect to MCP server: connect constructor trap"
+      );
+    } finally {
+      consoleErrorSpy.mockRestore();
+    }
+  });
+
+  it("connects MCP actions with trap-prone type getters when first read succeeds", async () => {
+    let typeReads = 0;
+    const flakyTypeAction = {
+      get type(): string {
+        typeReads += 1;
+        if (typeReads === 1) {
+          return "mcp_flaky_action";
+        }
+        throw new Error("flaky type trap");
+      },
+      actionParams: z.object({}),
+      run: async () => ({
+        success: true,
+        message: "ok",
+      }),
+    } as unknown as AgentActionDefinition<z.ZodObject<{}>>;
+    connectToServerMock.mockResolvedValue({
+      serverId: "server-flaky",
+      actions: [flakyTypeAction],
+    });
+
+    const agent = new HyperAgent({ llm: createMockLLM() });
+    const serverId = await agent.connectToMCPServer({
+      command: "echo",
+    });
+
+    expect(serverId).toBe("server-flaky");
+    expect(disconnectServerMock).not.toHaveBeenCalled();
+  });
+});
diff --git a/src/agent/__tests__/run-from-action-cache.test.ts b/src/agent/__tests__/run-from-action-cache.test.ts
new file mode 100644
index 00000000..bd0af1ac
--- /dev/null
+++ b/src/agent/__tests__/run-from-action-cache.test.ts
@@ -0,0 +1,1812 @@
+import { HyperAgent } from "@/agent";
+import { TaskStatus, type ActionCacheOutput } from "@/types/agent/types";
+import type { HyperAgentLLM } from "@/llm/types";
+import fs from "fs";
+
+function createMockLLM(): HyperAgentLLM {
+  return {
+    invoke: async () => ({ role: "assistant", content: "ok" }),
+    invokeStructured: async () => ({ rawText: "{}", parsed: null }),
+    getProviderId: () => "mock",
+    getModelId: () => "mock-model",
+    getCapabilities: () => ({
+      multimodal: false,
+      toolCalling: true,
+      jsonMode: true,
+    }),
+  };
+}
+
+describe("runFromActionCache hardening", () => {
+  it("falls back to instruction perform when helper method cache lacks xpath", async () => {
+    const agent = new HyperAgent({
+      llm: createMockLLM(),
+      cdpActions: false,
+    });
+    const perform = jest.fn().mockResolvedValue({
+      taskId: "perform-task",
+      status: TaskStatus.COMPLETED,
+      steps: [],
+      output: "performed via instruction",
+      replayStepMeta: {
+        usedCachedAction: false,
+        fallbackUsed: true,
+        retries: 1,
+        cachedXPath: null,
+        fallbackXPath: "/html/body/button[1]",
+        fallbackElementId: "0-1",
+      },
+    });
+    const performClick = jest.fn();
+
+    const page = {
+      perform,
+      performClick,
+    } as unknown as import("@/types/agent/types").HyperPage;
+
+    const cache: ActionCacheOutput = {
+      taskId: "cache-task",
+      createdAt: new Date().toISOString(),
+      status: TaskStatus.COMPLETED,
+      steps: [
+        {
+          stepIndex: 0,
+          instruction: "click login",
+          elementId: "0-1",
+          method: "click",
+          arguments: [],
+          frameIndex: 0,
+          xpath: null,
+          actionType: "actElement",
+          success: true,
+          message: "cached",
+        },
+      ],
+    };
+
+    const replay = await agent.runFromActionCache(cache, page);
+
+    expect(perform).toHaveBeenCalledWith(
+      "click login",
+      expect.objectContaining({
+        filterAdTrackingFrames: true,
+      })
+    );
+    expect(performClick).not.toHaveBeenCalled();
+    expect(replay.status).toBe(TaskStatus.COMPLETED);
+    expect(replay.steps[0]?.usedXPath).toBe(false);
+  });
+
+  it("trims cached helper method and xpath before dispatch", async () => {
+    const agent = new HyperAgent({
+      llm: createMockLLM(),
+      cdpActions: false,
+    });
+    const performClick = jest.fn().mockResolvedValue({
+      taskId: "click-task",
+      status: TaskStatus.COMPLETED,
+      steps: [],
+      output: "clicked via helper",
+      replayStepMeta: {
+        usedCachedAction: true,
+        fallbackUsed: false,
+        retries: 1,
+      },
+    });
+    const page = {
+      performClick,
+    } as unknown as import("@/types/agent/types").HyperPage;
+    const cache: ActionCacheOutput = {
+      taskId: "cache-task",
+      createdAt: new Date().toISOString(),
+      status: TaskStatus.COMPLETED,
+      steps: [
+        {
+          stepIndex: 0,
+          instruction: "  click login  ",
+          elementId: "0-1",
+          method: " CLICK ",
+          arguments: [],
+          frameIndex: 0,
+          xpath: "  //button[1]  ",
+          actionType: "actElement",
+          success: true,
+          message: "cached",
+        },
+      ],
+    };
+
+    const replay = await agent.runFromActionCache(cache, page);
+
+    expect(performClick).toHaveBeenCalledWith(
+      "//button[1]",
+      expect.objectContaining({
+        cdpActions: false,
+        performInstruction: "click login",
+      })
+    );
+    expect(replay.status).toBe(TaskStatus.COMPLETED);
+  });
+
+  it("forwards replay-level filter override to helper dispatch options", async () => {
+    const agent = new HyperAgent({
+      llm: createMockLLM(),
+      cdpActions: false,
+    });
+    const performClick = jest.fn().mockResolvedValue({
+      taskId: "click-task",
+      status: TaskStatus.COMPLETED,
+      steps: [],
+      output: "clicked via helper",
+      replayStepMeta: {
+        usedCachedAction: true,
+        fallbackUsed: false,
+        retries: 1,
+      },
+    });
+    const page = {
+      performClick,
+    } as unknown as import("@/types/agent/types").HyperPage;
+    const cache: ActionCacheOutput = {
+      taskId: "cache-task",
+      createdAt: new Date().toISOString(),
+      status: TaskStatus.COMPLETED,
+      steps: [
+        {
+          stepIndex: 0,
+          instruction: "click ad CTA",
+          elementId: "0-1",
+          method: "click",
+          arguments: [],
+          frameIndex: 0,
+          xpath: "//button[1]",
+          actionType: "actElement",
+          success: true,
+          message: "cached",
+        },
+      ],
+    };
+
+    await agent.runFromActionCache(cache, page, {
+      cdpActions: true,
+      filterAdTrackingFrames: false,
+    });
+
+    expect(performClick).toHaveBeenCalledWith(
+      "//button[1]",
+      expect.objectContaining({
+        cdpActions: true,
+        filterAdTrackingFrames: false,
+      })
+    );
+  });
+
+  it("fails fast when method cache lacks both xpath and instruction", async () => {
+    const agent = new HyperAgent({
+      llm: createMockLLM(),
+      cdpActions: false,
+    });
+    const page = {} as import("@/types/agent/types").HyperPage;
+    const cache: ActionCacheOutput = {
+      taskId: "cache-task",
+      createdAt: new Date().toISOString(),
+      status: TaskStatus.COMPLETED,
+      steps: [
+        {
+          stepIndex: 0,
+          instruction: undefined,
+          elementId: "0-1",
+          method: "click",
+          arguments: [],
+          frameIndex: 0,
+          xpath: null,
+          actionType: "actElement",
+          success: true,
+          message: "cached",
+        },
+      ],
+    };
+
+    const replay = await agent.runFromActionCache(cache, page);
+
+    expect(replay.status).toBe(TaskStatus.FAILED);
+    expect(replay.steps[0]?.message).toContain("without XPath or instruction");
+  });
+
+  it("sanitizes oversized replay action types in failure output", async () => {
+    const agent = new HyperAgent({
+      llm: createMockLLM(),
+      cdpActions: false,
+    });
+    const page = {} as import("@/types/agent/types").HyperPage;
+    const oversizedActionType = `action-${"x".repeat(500)}\nunsafe`;
+    const cache: ActionCacheOutput = {
+      taskId: "cache-task",
+      createdAt: new Date().toISOString(),
+      status: TaskStatus.COMPLETED,
+      steps: [
+        {
+          stepIndex: 0,
+          instruction: undefined,
+          elementId: null,
+          method: null,
+          arguments: [],
+          frameIndex: null,
+          xpath: null,
+          actionType: oversizedActionType,
+          success: true,
+          message: "cached",
+        },
+      ],
+    };
+
+    const replay = await agent.runFromActionCache(cache, page);
+
+    expect(replay.status).toBe(TaskStatus.FAILED);
+    expect(replay.steps[0]?.actionType).toContain("[truncated");
+    expect(replay.steps[0]?.actionType).not.toContain("\n");
+    expect(replay.steps[0]?.message).toContain("[truncated");
+    expect(replay.steps[0]?.message).not.toContain("\n");
+  });
+
+  it("treats whitespace instruction as missing when xpath is unavailable", async () => {
+    const agent = new HyperAgent({
+      llm: createMockLLM(),
+      cdpActions: false,
+    });
+    const perform = jest.fn();
+    const page = {
+      perform,
+    } as unknown as import("@/types/agent/types").HyperPage;
+    const cache: ActionCacheOutput = {
+      taskId: "cache-task",
+      createdAt: new Date().toISOString(),
+      status: TaskStatus.COMPLETED,
+      steps: [
+        {
+          stepIndex: 0,
+          instruction: "   ",
+          elementId: "0-1",
+          method: "click",
+          arguments: [],
+          frameIndex: 0,
+          xpath: null,
+          actionType: "actElement",
+          success: true,
+          message: "cached",
+        },
+      ],
+    };
+
+    const replay = await agent.runFromActionCache(cache, page);
+
+    expect(replay.status).toBe(TaskStatus.FAILED);
+    expect(replay.steps[0]?.message).toContain("without XPath or instruction");
+    expect(perform).not.toHaveBeenCalled();
+  });
+
+  it("replays special wait action using actionParams duration", async () => {
+    const agent = new HyperAgent({
+      llm: createMockLLM(),
+      cdpActions: false,
+    });
+    const waitForTimeout = jest.fn().mockResolvedValue(undefined);
+    const page = {
+      waitForTimeout,
+    } as unknown as import("@/types/agent/types").HyperPage;
+    const cache: ActionCacheOutput = {
+      taskId: "cache-task",
+      createdAt: new Date().toISOString(),
+      status: TaskStatus.COMPLETED,
+      steps: [
+        {
+          stepIndex: 0,
+          instruction: "wait before next action",
+          elementId: null,
+          method: null,
+          arguments: [],
+          actionParams: { duration: "750" },
+          frameIndex: null,
+          xpath: null,
+          actionType: "wait",
+          success: true,
+          message: "cached",
+        },
+      ],
+    };
+
+    const replay = await agent.runFromActionCache(cache, page);
+
+    expect(waitForTimeout).toHaveBeenCalledWith(750);
+    expect(replay.status).toBe(TaskStatus.COMPLETED);
+    expect(replay.steps[0]?.success).toBe(true);
+    expect(replay.steps[0]?.message).toContain("Waited 750ms");
+    expect(replay.steps[0]?.retries).toBe(1);
+  });
+
+  it("replays special waitForLoadState action", async () => {
+    const agent = new HyperAgent({
+      llm: createMockLLM(),
+      cdpActions: false,
+    });
+    const waitForLoadState = jest.fn().mockResolvedValue(undefined);
+    const page = {
+      waitForLoadState,
+    } as unknown as import("@/types/agent/types").HyperPage;
+    const cache: ActionCacheOutput = {
+      taskId: "cache-task",
+      createdAt: new Date().toISOString(),
+      status: TaskStatus.COMPLETED,
+      steps: [
+        {
+          stepIndex: 0,
+          instruction: "wait loadstate",
+          elementId: null,
+          method: null,
+          arguments: ["NETWORKIDLE", "1200"],
+          frameIndex: null,
+          xpath: null,
+          actionType: "waitForLoadState",
+          success: true,
+          message: "cached",
+        },
+      ],
+    };
+
+    const replay = await agent.runFromActionCache(cache, page);
+
+    expect(waitForLoadState).toHaveBeenCalledWith("networkidle", {
+      timeout: 1200,
+    });
+    expect(replay.status).toBe(TaskStatus.COMPLETED);
+    expect(replay.steps[0]?.message).toContain("Waited for load state: networkidle");
+  });
+
+  it("stops replay side-effects after closeAgent is called mid-run", async () => {
+    const agent = new HyperAgent({
+      llm: createMockLLM(),
+      cdpActions: false,
+    });
+    let resolveWait!: () => void;
+    const waitForTimeout = jest.fn(
+      () =>
+        new Promise<void>((resolve) => {
+          resolveWait = resolve;
+        })
+    );
+    const performClick = jest.fn().mockResolvedValue({
+      taskId: "click-task",
+      status: TaskStatus.COMPLETED,
+      steps: [],
+      output: "clicked",
+      replayStepMeta: {
+        usedCachedAction: true,
+        fallbackUsed: false,
+        retries: 1,
+      },
+    });
+    const page = {
+      waitForTimeout,
+      performClick,
+    } as unknown as import("@/types/agent/types").HyperPage;
+    const cache: ActionCacheOutput = {
+      taskId: "cache-task",
+      createdAt: new Date().toISOString(),
+      status: TaskStatus.COMPLETED,
+      steps: [
+        {
+          stepIndex: 0,
+          instruction: "wait",
+          elementId: null,
+          method: null,
+          arguments: [],
+          actionParams: { duration: 10 },
+          frameIndex: null,
+          xpath: null,
+          actionType: "wait",
+          success: true,
+          message: "cached wait",
+        },
+        {
+          stepIndex: 1,
+          instruction: "click submit",
+          elementId: "0-1",
+          method: "click",
+          arguments: [],
+          frameIndex: 0,
+          xpath: "//button[1]",
+          actionType: "actElement",
+          success: true,
+          message: "cached click",
+        },
+      ],
+    };
+
+    const replayPromise = agent.runFromActionCache(cache, page);
+    expect(waitForTimeout).toHaveBeenCalledTimes(1);
+    await expect(agent.closeAgent()).resolves.toBeUndefined();
+    resolveWait();
+
+    const replay = await replayPromise;
+
+    expect(replay.status).toBe(TaskStatus.FAILED);
+    expect(performClick).not.toHaveBeenCalled();
+    expect(replay.steps[1]?.message).toBe(
+      "Replay stopped because agent was closed"
+    );
+  });
+
+  it("skips replay debug artifact writes after closeAgent generation changes", async () => {
+    const agent = new HyperAgent({
+      llm: createMockLLM(),
+      cdpActions: false,
+      debug: true,
+    });
+    let resolveWait!: () => void;
+    const waitForTimeout = jest.fn(
+      () =>
+        new Promise<void>((resolve) => {
+          resolveWait = resolve;
+        })
+    );
+    const page = {
+      waitForTimeout,
+    } as unknown as import("@/types/agent/types").HyperPage;
+    const cache: ActionCacheOutput = {
+      taskId: "cache-task",
+      createdAt: new Date().toISOString(),
+      status: TaskStatus.COMPLETED,
+      steps: [
+        {
+          stepIndex: 0,
+          instruction: "wait",
+          elementId: null,
+          method: null,
+          arguments: [],
+          actionParams: { duration: 10 },
+          frameIndex: null,
+          xpath: null,
+          actionType: "wait",
+          success: true,
+          message: "cached wait",
+        },
+        {
+          stepIndex: 1,
+          instruction: "wait again",
+          elementId: null,
+          method: null,
+          arguments: [],
+          actionParams: { duration: 10 },
+          frameIndex: null,
+          xpath: null,
+          actionType: "wait",
+          success: true,
+          message: "cached wait 2",
+        },
+      ],
+    };
+    const writeSpy = jest.spyOn(fs, "writeFileSync").mockImplementation(() => {
+      return undefined;
+    });
+
+    try {
+      const replayPromise = agent.runFromActionCache(cache, page, { debug: true });
+      await expect(agent.closeAgent()).resolves.toBeUndefined();
+      resolveWait();
+
+      const replay = await replayPromise;
+      expect(replay.status).toBe(TaskStatus.FAILED);
+      expect(writeSpy).not.toHaveBeenCalled();
+    } finally {
+      writeSpy.mockRestore();
+    }
+  });
+
+  it("prioritizes shutdown-stop diagnostics over replay-limit diagnostics", async () => {
+    const agent = new HyperAgent({
+      llm: createMockLLM(),
+      cdpActions: false,
+    });
+    let resolveWait!: () => void;
+    const waitForTimeout = jest.fn(
+      () =>
+        new Promise<void>((resolve) => {
+          resolveWait = resolve;
+        })
+    );
+    const perform = jest.fn();
+    const page = {
+      waitForTimeout,
+      perform,
+    } as unknown as import("@/types/agent/types").HyperPage;
+    const maxReplaySteps = (
+      HyperAgent as unknown as { MAX_REPLAY_STEPS: number }
+    ).MAX_REPLAY_STEPS;
+    const steps: ActionCacheOutput["steps"] = [
+      {
+        stepIndex: 0,
+        instruction: "wait",
+        elementId: null,
+        method: null,
+        arguments: [],
+        actionParams: { duration: 10 },
+        frameIndex: null,
+        xpath: null,
+        actionType: "wait",
+        success: true,
+        message: "cached wait",
+      },
+      ...Array.from({ length: maxReplaySteps + 5 }, (_, index) => ({
+        stepIndex: index + 1,
+        instruction: `step ${index + 1}`,
+        elementId: null,
+        method: null,
+        arguments: [],
+        frameIndex: null,
+        xpath: null,
+        actionType: "unknown-action",
+        success: true,
+        message: "cached",
+      })),
+    ];
+    const cache: ActionCacheOutput = {
+      taskId: "cache-task",
+      createdAt: new Date().toISOString(),
+      status: TaskStatus.COMPLETED,
+      steps,
+    };
+
+    const replayPromise = agent.runFromActionCache(cache, page);
+    await expect(agent.closeAgent()).resolves.toBeUndefined();
+    resolveWait();
+
+    const replay = await replayPromise;
+    expect(replay.status).toBe(TaskStatus.FAILED);
+    expect(perform).not.toHaveBeenCalled();
+    expect(replay.steps.some((step) => step.actionType === "replay-limit")).toBe(
+      false
+    );
+    expect(replay.steps[replay.steps.length - 1]?.message).toBe(
+      "Replay stopped because agent was closed"
+    );
+  });
+
+  it("fails replay step cleanly when special action execution throws", async () => {
+    const agent = new HyperAgent({
+      llm: createMockLLM(),
+      cdpActions: false,
+    });
+    const waitForTimeout = jest
+      .fn()
+      .mockRejectedValue(new Error("timeout call failed"));
+    const page = {
+      waitForTimeout,
+    } as unknown as import("@/types/agent/types").HyperPage;
+    const cache: ActionCacheOutput = {
+      taskId: "cache-task",
+      createdAt: new Date().toISOString(),
+      status: TaskStatus.COMPLETED,
+      steps: [
+        {
+          stepIndex: 0,
+          instruction: "wait before next action",
+          elementId: null,
+          method: null,
+          arguments: [],
+          actionParams: { duration: 100 },
+          frameIndex: null,
+          xpath: null,
+          actionType: "wait",
+          success: true,
+          message: "cached",
+        },
+      ],
+    };
+
+    const replay = await agent.runFromActionCache(cache, page);
+
+    expect(replay.status).toBe(TaskStatus.FAILED);
+    expect(replay.steps[0]?.message).toContain("Replay step 0 failed");
+    expect(replay.steps[0]?.message).toContain("timeout call failed");
+    expect(replay.steps[0]?.usedXPath).toBe(true);
+  });
+
+  it("fails replay step cleanly when helper dispatch throws", async () => {
+    const agent = new HyperAgent({
+      llm: createMockLLM(),
+      cdpActions: false,
+    });
+    const performClick = jest
+      .fn()
+      .mockRejectedValue(new Error("helper click failed"));
+    const page = {
+      performClick,
+    } as unknown as import("@/types/agent/types").HyperPage;
+    const cache: ActionCacheOutput = {
+      taskId: "cache-task",
+      createdAt: new Date().toISOString(),
+      status: TaskStatus.COMPLETED,
+      steps: [
+        {
+          stepIndex: 0,
+          instruction: "click login",
+          elementId: "0-1",
+          method: "click",
+          arguments: [],
+          frameIndex: 0,
+          xpath: "//button[1]",
+          actionType: "actElement",
+          success: true,
+          message: "cached",
+        },
+      ],
+    };
+
+    const replay = await agent.runFromActionCache(cache, page);
+
+    expect(replay.status).toBe(TaskStatus.FAILED);
+    expect(replay.steps[0]?.message).toContain("Replay step 0 failed");
+    expect(replay.steps[0]?.message).toContain("helper click failed");
+    expect(replay.steps[0]?.usedXPath).toBe(true);
+  });
+
+  it("does not mark cached XPath usage when perform fallback path throws", async () => {
+    const agent = new HyperAgent({
+      llm: createMockLLM(),
+      cdpActions: false,
+    });
+    const perform = jest.fn().mockRejectedValue(new Error("perform failed"));
+    const page = {
+      perform,
+    } as unknown as import("@/types/agent/types").HyperPage;
+    const cache: ActionCacheOutput = {
+      taskId: "cache-task",
+      createdAt: new Date().toISOString(),
+      status: TaskStatus.COMPLETED,
+      steps: [
+        {
+          stepIndex: 0,
+          instruction: "try fallback perform",
+          elementId: null,
+          method: null,
+          arguments: [],
+          frameIndex: null,
+          xpath: null,
+          actionType: "unknown-action",
+          success: true,
+          message: "cached",
+        },
+      ],
+    };
+
+    const replay = await agent.runFromActionCache(cache, page);
+
+    expect(replay.status).toBe(TaskStatus.FAILED);
+    expect(replay.steps[0]?.message).toContain("perform failed");
+    expect(replay.steps[0]?.usedXPath).toBe(false);
+  });
+
+  it("serializes non-Error replay failures from perform path", async () => {
+    const agent = new HyperAgent({
+      llm: createMockLLM(),
+      cdpActions: false,
+    });
+    const perform = jest.fn().mockRejectedValue({ reason: "perform exploded" });
+    const page = {
+      perform,
+    } as unknown as import("@/types/agent/types").HyperPage;
+    const cache: ActionCacheOutput = {
+      taskId: "cache-task",
+      createdAt: new Date().toISOString(),
+      status: TaskStatus.COMPLETED,
+      steps: [
+        {
+          stepIndex: 0,
+          instruction: "trigger perform",
+          elementId: null,
+          method: null,
+          arguments: [],
+          frameIndex: null,
+          xpath: null,
+          actionType: "unknown-action",
+          success: true,
+          message: "cached",
+        },
+      ],
+    };
+
+    const replay = await agent.runFromActionCache(cache, page);
+
+    expect(replay.status).toBe(TaskStatus.FAILED);
+    expect(replay.steps[0]?.message).toContain(
+      'Replay step 0 failed: {"reason":"perform exploded"}'
+    );
+  });
+
+  it("does not fail replay when debug file write throws", async () => {
+    const agent = new HyperAgent({
+      llm: createMockLLM(),
+      cdpActions: false,
+      debug: true,
+    });
+    const waitForTimeout = jest.fn().mockResolvedValue(undefined);
+    const page = {
+      waitForTimeout,
+    } as unknown as import("@/types/agent/types").HyperPage;
+    const cache: ActionCacheOutput = {
+      taskId: "cache-task",
+      createdAt: new Date().toISOString(),
+      status: TaskStatus.COMPLETED,
+      steps: [
+        {
+          stepIndex: 0,
+          instruction: "wait",
+          elementId: null,
+          method: null,
+          arguments: [],
+          actionParams: { duration: 10 },
+          frameIndex: null,
+          xpath: null,
+          actionType: "wait",
+          success: true,
+          message: "cached",
+        },
+      ],
+    };
+    const writeSpy = jest
+      .spyOn(fs, "writeFileSync")
+      .mockImplementation(() => {
+        throw new Error("disk full");
+      });
+    const errorSpy = jest.spyOn(console, "error").mockImplementation(() => {});
+
+    try {
+      const replay = await agent.runFromActionCache(cache, page, { debug: true });
+
+      expect(replay.status).toBe(TaskStatus.COMPLETED);
+      expect(errorSpy).toHaveBeenCalled();
+    } finally {
+      writeSpy.mockRestore();
+      errorSpy.mockRestore();
+    }
+  });
+
+  it("truncates oversized replay debug write diagnostics", async () => {
+    const agent = new HyperAgent({
+      llm: createMockLLM(),
+      cdpActions: false,
+      debug: true,
+    });
+    const waitForTimeout = jest.fn().mockResolvedValue(undefined);
+    const page = {
+      waitForTimeout,
+    } as unknown as import("@/types/agent/types").HyperPage;
+    const cache: ActionCacheOutput = {
+      taskId: "cache-task",
+      createdAt: new Date().toISOString(),
+      status: TaskStatus.COMPLETED,
+      steps: [
+        {
+          stepIndex: 0,
+          instruction: "wait",
+          elementId: null,
+          method: null,
+          arguments: [],
+          actionParams: { duration: 10 },
+          frameIndex: null,
+          xpath: null,
+          actionType: "wait",
+          success: true,
+          message: "cached",
+        },
+      ],
+    };
+    const writeSpy = jest
+      .spyOn(fs, "writeFileSync")
+      .mockImplementation(() => {
+        throw new Error("x".repeat(2_000));
+      });
+    const errorSpy = jest.spyOn(console, "error").mockImplementation(() => {});
+
+    try {
+      const replay = await agent.runFromActionCache(cache, page, { debug: true });
+
+      expect(replay.status).toBe(TaskStatus.COMPLETED);
+      const firstMessage = String(errorSpy.mock.calls[0]?.[0] ?? "");
+      expect(firstMessage).toContain("[truncated");
+    } finally {
+      writeSpy.mockRestore();
+      errorSpy.mockRestore();
+    }
+  });
+
+  it("preserves empty replay output messages instead of replacing them", async () => {
+    const agent = new HyperAgent({
+      llm: createMockLLM(),
+      cdpActions: false,
+    });
+    const perform = jest.fn().mockResolvedValue({
+      taskId: "perform-task",
+      status: TaskStatus.COMPLETED,
+      steps: [],
+      output: "",
+      replayStepMeta: {
+        usedCachedAction: false,
+        fallbackUsed: false,
+        retries: 1,
+      },
+    });
+    const page = {
+      perform,
+    } as unknown as import("@/types/agent/types").HyperPage;
+    const cache: ActionCacheOutput = {
+      taskId: "cache-task",
+      createdAt: new Date().toISOString(),
+      status: TaskStatus.COMPLETED,
+      steps: [
+        {
+          stepIndex: 0,
+          instruction: "empty output path",
+          elementId: null,
+          method: null,
+          arguments: [],
+          frameIndex: null,
+          xpath: null,
+          actionType: "unknown-action",
+          success: true,
+          message: "cached",
+        },
+      ],
+    };
+
+    const replay = await agent.runFromActionCache(cache, page);
+
+    expect(replay.status).toBe(TaskStatus.COMPLETED);
+    expect(replay.steps[0]?.message).toBe("");
+  });
+
+  it("sanitizes replay output control characters", async () => {
+    const agent = new HyperAgent({
+      llm: createMockLLM(),
+      cdpActions: false,
+    });
+    const perform = jest.fn().mockResolvedValue({
+      taskId: "perform-task",
+      status: TaskStatus.COMPLETED,
+      steps: [],
+      output: "line-1\nline-2\u0007",
+      replayStepMeta: {
+        usedCachedAction: false,
+        fallbackUsed: false,
+        retries: 1,
+      },
+    });
+    const page = {
+      perform,
+    } as unknown as import("@/types/agent/types").HyperPage;
+    const cache: ActionCacheOutput = {
+      taskId: "cache-task",
+      createdAt: new Date().toISOString(),
+      status: TaskStatus.COMPLETED,
+      steps: [
+        {
+          stepIndex: 0,
+          instruction: "sanitize output",
+          elementId: null,
+          method: null,
+          arguments: [],
+          frameIndex: null,
+          xpath: null,
+          actionType: "unknown-action",
+          success: true,
+          message: "cached",
+        },
+      ],
+    };
+
+    const replay = await agent.runFromActionCache(cache, page);
+
+    expect(replay.status).toBe(TaskStatus.COMPLETED);
+    expect(replay.steps[0]?.message).toBe("line-1 line-2");
+  });
+
+  it("formats non-string replay outputs into readable diagnostics", async () => {
+    const agent = new HyperAgent({
+      llm: createMockLLM(),
+      cdpActions: false,
+    });
+    const perform = jest.fn().mockResolvedValue({
+      taskId: "perform-task",
+      status: TaskStatus.COMPLETED,
+      steps: [],
+      output: { reason: "object output" } as unknown as string,
+      replayStepMeta: {
+        usedCachedAction: false,
+        fallbackUsed: false,
+        retries: 1,
+      },
+    });
+    const page = {
+      perform,
+    } as unknown as import("@/types/agent/types").HyperPage;
+    const cache: ActionCacheOutput = {
+      taskId: "cache-task",
+      createdAt: new Date().toISOString(),
+      status: TaskStatus.COMPLETED,
+      steps: [
+        {
+          stepIndex: 0,
+          instruction: "non string output path",
+          elementId: null,
+          method: null,
+          arguments: [],
+          frameIndex: null,
+          xpath: null,
+          actionType: "unknown-action",
+          success: true,
+          message: "cached",
+        },
+      ],
+    };
+
+    const replay = await agent.runFromActionCache(cache, page);
+
+    expect(replay.status).toBe(TaskStatus.COMPLETED);
+    expect(replay.steps[0]?.message).toBe('{"reason":"object output"}');
+  });
+
+  it("handles trap-prone replay step metadata without failing replay", async () => {
+    const agent = new HyperAgent({
+      llm: createMockLLM(),
+      cdpActions: false,
+    });
+    const perform = jest.fn().mockResolvedValue({
+      get status(): TaskStatus {
+        return TaskStatus.COMPLETED;
+      },
+      get output(): string {
+        return "done";
+      },
+      get replayStepMeta(): never {
+        throw new Error("meta trap");
+      },
+    });
+    const page = {
+      perform,
+    } as unknown as import("@/types/agent/types").HyperPage;
+    const cache: ActionCacheOutput = {
+      taskId: "cache-task",
+      createdAt: new Date().toISOString(),
+      status: TaskStatus.COMPLETED,
+      steps: [
+        {
+          stepIndex: 0,
+          instruction: "meta trap path",
+          elementId: null,
+          method: null,
+          arguments: [],
+          frameIndex: null,
+          xpath: null,
+          actionType: "unknown-action",
+          success: true,
+          message: "cached",
+        },
+      ],
+    };
+
+    const replay = await agent.runFromActionCache(cache, page);
+
+    expect(replay.status).toBe(TaskStatus.COMPLETED);
+    expect(replay.steps[0]).toMatchObject({
+      success: true,
+      usedXPath: false,
+      fallbackUsed: false,
+      retries: 0,
+      message: "done",
+    });
+  });
+
+  it("fails replay step deterministically when replay result status/output getters trap", async () => {
+    const agent = new HyperAgent({
+      llm: createMockLLM(),
+      cdpActions: false,
+    });
+    const perform = jest.fn().mockResolvedValue({
+      get status(): never {
+        throw new Error("status trap");
+      },
+      get output(): never {
+        throw new Error("output trap");
+      },
+      replayStepMeta: {
+        usedCachedAction: true,
+        fallbackUsed: false,
+        retries: 2,
+      },
+    });
+    const page = {
+      perform,
+    } as unknown as import("@/types/agent/types").HyperPage;
+    const cache: ActionCacheOutput = {
+      taskId: "cache-task",
+      createdAt: new Date().toISOString(),
+      status: TaskStatus.COMPLETED,
+      steps: [
+        {
+          stepIndex: 0,
+          instruction: "status trap path",
+          elementId: null,
+          method: null,
+          arguments: [],
+          frameIndex: null,
+          xpath: null,
+          actionType: "unknown-action",
+          success: true,
+          message: "cached",
+        },
+      ],
+    };
+
+    const replay = await agent.runFromActionCache(cache, page);
+
+    expect(replay.status).toBe(TaskStatus.FAILED);
+    expect(replay.steps[0]).toMatchObject({
+      success: false,
+      usedXPath: true,
+      retries: 2,
+      message: "Failed to execute cached action",
+    });
+  });
+
+  it("truncates oversized replay output diagnostics", async () => {
+    const agent = new HyperAgent({
+      llm: createMockLLM(),
+      cdpActions: false,
+    });
+    const perform = jest.fn().mockResolvedValue({
+      taskId: "perform-task",
+      status: TaskStatus.COMPLETED,
+      steps: [],
+      output: "x".repeat(9_000),
+      replayStepMeta: {
+        usedCachedAction: false,
+        fallbackUsed: false,
+        retries: 1,
+      },
+    });
+    const page = {
+      perform,
+    } as unknown as import("@/types/agent/types").HyperPage;
+    const cache: ActionCacheOutput = {
+      taskId: "cache-task",
+      createdAt: new Date().toISOString(),
+      status: TaskStatus.COMPLETED,
+      steps: [
+        {
+          stepIndex: 0,
+          instruction: "oversized output path",
+          elementId: null,
+          method: null,
+          arguments: [],
+          frameIndex: null,
+          xpath: null,
+          actionType: "unknown-action",
+          success: true,
+          message: "cached",
+        },
+      ],
+    };
+
+    const replay = await agent.runFromActionCache(cache, page);
+    const message = replay.steps[0]?.message ?? "";
+
+    expect(message).toContain("[truncated");
+    expect(message.length).toBeLessThanOrEqual(4_100);
+  });
+
+  it("truncates oversized replay step lists to bounded limits", async () => {
+    const agent = new HyperAgent({
+      llm: createMockLLM(),
+      cdpActions: false,
+    });
+    const perform = jest.fn().mockResolvedValue({
+      taskId: "perform-task",
+      status: TaskStatus.COMPLETED,
+      steps: [],
+      output: "ok",
+      replayStepMeta: {
+        usedCachedAction: false,
+        fallbackUsed: false,
+        retries: 1,
+      },
+    });
+    const page = {
+      perform,
+    } as unknown as import("@/types/agent/types").HyperPage;
+    const maxReplaySteps = (
+      HyperAgent as unknown as { MAX_REPLAY_STEPS: number }
+    ).MAX_REPLAY_STEPS;
+    const cache: ActionCacheOutput = {
+      taskId: "cache-task",
+      createdAt: new Date().toISOString(),
+      status: TaskStatus.COMPLETED,
+      steps: Array.from({ length: maxReplaySteps + 1 }, (_, index) => ({
+        stepIndex: index,
+        instruction: `step ${index}`,
+        elementId: null,
+        method: null,
+        arguments: [],
+        frameIndex: null,
+        xpath: null,
+        actionType: "unknown-action",
+        success: true,
+        message: "cached",
+      })),
+    };
+
+    const replay = await agent.runFromActionCache(cache, page);
+
+    expect(perform).toHaveBeenCalledTimes(maxReplaySteps);
+    expect(replay.status).toBe(TaskStatus.FAILED);
+    const finalStep = replay.steps[replay.steps.length - 1];
+    expect(finalStep?.actionType).toBe("replay-limit");
+    expect(finalStep?.message).toContain("Replay truncated after");
+  });
+
+  it("reports lower-bound replay truncation for oversized iterable step sources", async () => {
+    const agent = new HyperAgent({
+      llm: createMockLLM(),
+      cdpActions: false,
+    });
+    const perform = jest.fn().mockResolvedValue({
+      taskId: "perform-task",
+      status: TaskStatus.COMPLETED,
+      steps: [],
+      output: "ok",
+      replayStepMeta: {
+        usedCachedAction: false,
+        fallbackUsed: false,
+        retries: 1,
+      },
+    });
+    const page = {
+      perform,
+    } as unknown as import("@/types/agent/types").HyperPage;
+    const maxReplaySteps = (
+      HyperAgent as unknown as { MAX_REPLAY_STEPS: number }
+    ).MAX_REPLAY_STEPS;
+    const iterableSteps = {
+      *[Symbol.iterator](): IterableIterator<{
+        stepIndex: number;
+        instruction: string;
+        elementId: null;
+        method: null;
+        arguments: [];
+        frameIndex: null;
+        xpath: null;
+        actionType: string;
+        success: true;
+        message: string;
+      }> {
+        for (let index = 0; index < maxReplaySteps + 50; index += 1) {
+          yield {
+            stepIndex: index,
+            instruction: `iterable-step-${index}`,
+            elementId: null,
+            method: null,
+            arguments: [],
+            frameIndex: null,
+            xpath: null,
+            actionType: "unknown-action",
+            success: true,
+            message: "cached",
+          };
+        }
+      },
+    };
+    const cache = {
+      taskId: "cache-task",
+      createdAt: new Date().toISOString(),
+      status: TaskStatus.COMPLETED,
+      steps: iterableSteps,
+    } as unknown as ActionCacheOutput;
+
+    const replay = await agent.runFromActionCache(cache, page);
+
+    expect(perform).toHaveBeenCalledTimes(maxReplaySteps);
+    expect(replay.status).toBe(TaskStatus.FAILED);
+    const finalStep = replay.steps[replay.steps.length - 1];
+    expect(finalStep?.actionType).toBe("replay-limit");
+    expect(finalStep?.message).toContain("at least");
+  });
+
+  it("handles malformed non-finite step indices safely", async () => {
+    const agent = new HyperAgent({
+      llm: createMockLLM(),
+      cdpActions: false,
+    });
+    const perform = jest
+      .fn()
+      .mockResolvedValue({
+        taskId: "perform-task-1",
+        status: TaskStatus.COMPLETED,
+        steps: [],
+        output: "first",
+      })
+      .mockResolvedValueOnce({
+        taskId: "perform-task-0",
+        status: TaskStatus.COMPLETED,
+        steps: [],
+        output: "second",
+      });
+    const page = {
+      perform,
+    } as unknown as import("@/types/agent/types").HyperPage;
+    const cache: ActionCacheOutput = {
+      taskId: "cache-task",
+      createdAt: new Date().toISOString(),
+      status: TaskStatus.COMPLETED,
+      steps: [
+        {
+          stepIndex: Number.NaN,
+          instruction: "nan index step",
+          elementId: null,
+          method: null,
+          arguments: [],
+          frameIndex: null,
+          xpath: null,
+          actionType: "unknown-action",
+          success: true,
+          message: "cached",
+        },
+        {
+          stepIndex: 0,
+          instruction: "normal step",
+          elementId: null,
+          method: null,
+          arguments: [],
+          frameIndex: null,
+          xpath: null,
+          actionType: "unknown-action",
+          success: true,
+          message: "cached",
+        },
+      ],
+    };
+
+    const replay = await agent.runFromActionCache(cache, page);
+
+    expect(replay.status).toBe(TaskStatus.COMPLETED);
+    expect(perform).toHaveBeenNthCalledWith(
+      1,
+      "normal step",
+      expect.objectContaining({
+        filterAdTrackingFrames: true,
+      })
+    );
+    expect(perform).toHaveBeenNthCalledWith(
+      2,
+      "nan index step",
+      expect.objectContaining({
+        filterAdTrackingFrames: true,
+      })
+    );
+    expect(replay.steps[0]?.stepIndex).toBe(0);
+    expect(replay.steps[1]?.stepIndex).toBe(-1);
+  });
+
+  it("fails gracefully when cached steps are unreadable", async () => {
+    const agent = new HyperAgent({
+      llm: createMockLLM(),
+      cdpActions: false,
+    });
+    const page = {} as import("@/types/agent/types").HyperPage;
+    const cache = {
+      taskId: "cache-task",
+      createdAt: new Date().toISOString(),
+      status: TaskStatus.COMPLETED,
+      get steps(): unknown[] {
+        throw new Error("steps trap");
+      },
+    } as unknown as ActionCacheOutput;
+
+    const replay = await agent.runFromActionCache(cache, page);
+
+    expect(replay.status).toBe(TaskStatus.FAILED);
+    expect(replay.steps[0]?.message).toContain("Failed to read cached steps");
+    expect(replay.steps[0]?.message).toContain("steps trap");
+  });
+
+  it("falls back to unknown source task id when cache taskId getter traps", async () => {
+    const agent = new HyperAgent({
+      llm: createMockLLM(),
+      cdpActions: false,
+    });
+    const perform = jest.fn().mockResolvedValue({
+      taskId: "perform-task",
+      status: TaskStatus.COMPLETED,
+      steps: [],
+      output: "performed",
+      replayStepMeta: {
+        usedCachedAction: false,
+        fallbackUsed: false,
+        retries: 1,
+      },
+    });
+    const page = {
+      perform,
+    } as unknown as import("@/types/agent/types").HyperPage;
+    const cache = {
+      get taskId(): string {
+        throw new Error("taskId trap");
+      },
+      createdAt: new Date().toISOString(),
+      status: TaskStatus.COMPLETED,
+      steps: [
+        {
+          stepIndex: 0,
+          instruction: "fallback source id",
+          elementId: null,
+          method: null,
+          arguments: [],
+          frameIndex: null,
+          xpath: null,
+          actionType: "unknown-action",
+          success: true,
+          message: "cached",
+        },
+      ],
+    } as unknown as ActionCacheOutput;
+
+    const replay = await agent.runFromActionCache(cache, page);
+
+    expect(replay.sourceTaskId).toBe("unknown-task");
+    expect(replay.status).toBe(TaskStatus.COMPLETED);
+    expect(perform).toHaveBeenCalledWith(
+      "fallback source id",
+      expect.objectContaining({
+        cdpActions: false,
+        filterAdTrackingFrames: true,
+      })
+    );
+  });
+
+  it("applies runFromActionCache filter override to perform fallback calls", async () => {
+    const agent = new HyperAgent({
+      llm: createMockLLM(),
+      cdpActions: false,
+    });
+    const perform = jest.fn().mockResolvedValue({
+      taskId: "perform-task",
+      status: TaskStatus.COMPLETED,
+      steps: [],
+      output: "performed via instruction",
+      replayStepMeta: {
+        usedCachedAction: false,
+        fallbackUsed: true,
+        retries: 1,
+      },
+    });
+    const page = {
+      perform,
+    } as unknown as import("@/types/agent/types").HyperPage;
+    const cache: ActionCacheOutput = {
+      taskId: "cache-task",
+      createdAt: new Date().toISOString(),
+      status: TaskStatus.COMPLETED,
+      steps: [
+        {
+          stepIndex: 0,
+          instruction: "click ad iframe CTA",
+          elementId: "0-1",
+          method: "click",
+          arguments: [],
+          frameIndex: 0,
+          xpath: null,
+          actionType: "actElement",
+          success: true,
+          message: "cached",
+        },
+      ],
+    };
+
+    await agent.runFromActionCache(cache, page, {
+      cdpActions: true,
+      filterAdTrackingFrames: false,
+    });
+
+    expect(perform).toHaveBeenCalledWith(
+      "click ad iframe CTA",
+      expect.objectContaining({
+        cdpActions: true,
+        filterAdTrackingFrames: false,
+      })
+    );
+  });
+
+  it("falls back to agent cdpActions for replay when params getter traps", async () => {
+    const agent = new HyperAgent({
+      llm: createMockLLM(),
+      cdpActions: false,
+    });
+    const perform = jest.fn().mockResolvedValue({
+      taskId: "perform-task",
+      status: TaskStatus.COMPLETED,
+      steps: [],
+      output: "performed via instruction",
+      replayStepMeta: {
+        usedCachedAction: false,
+        fallbackUsed: true,
+        retries: 1,
+      },
+    });
+    const page = {
+      perform,
+    } as unknown as import("@/types/agent/types").HyperPage;
+    const cache: ActionCacheOutput = {
+      taskId: "cache-task",
+      createdAt: new Date().toISOString(),
+      status: TaskStatus.COMPLETED,
+      steps: [
+        {
+          stepIndex: 0,
+          instruction: "click fallback target",
+          elementId: "0-1",
+          method: "click",
+          arguments: [],
+          frameIndex: 0,
+          xpath: null,
+          actionType: "actElement",
+          success: true,
+          message: "cached",
+        },
+      ],
+    };
+    const trappedParams = new Proxy(
+      {},
+      {
+        get: (_target, prop: string | symbol) => {
+          if (prop === "cdpActions") {
+            throw new Error("replay cdp trap");
+          }
+          return undefined;
+        },
+      }
+    ) as import("@/types/agent/types").RunFromActionCacheParams;
+
+    await agent.runFromActionCache(cache, page, trappedParams);
+
+    expect(perform).toHaveBeenCalledWith(
+      "click fallback target",
+      expect.objectContaining({
+        cdpActions: false,
+      })
+    );
+  });
+
+  it("falls back to agent filter setting for replay when params getter traps", async () => {
+    const agent = new HyperAgent({
+      llm: createMockLLM(),
+      cdpActions: false,
+      filterAdTrackingFrames: false,
+    });
+    const perform = jest.fn().mockResolvedValue({
+      taskId: "perform-task",
+      status: TaskStatus.COMPLETED,
+      steps: [],
+      output: "performed via instruction",
+      replayStepMeta: {
+        usedCachedAction: false,
+        fallbackUsed: true,
+        retries: 1,
+      },
+    });
+    const page = {
+      perform,
+    } as unknown as import("@/types/agent/types").HyperPage;
+    const cache: ActionCacheOutput = {
+      taskId: "cache-task",
+      createdAt: new Date().toISOString(),
+      status: TaskStatus.COMPLETED,
+      steps: [
+        {
+          stepIndex: 0,
+          instruction: "click fallback target",
+          elementId: "0-1",
+          method: "click",
+          arguments: [],
+          frameIndex: 0,
+          xpath: null,
+          actionType: "actElement",
+          success: true,
+          message: "cached",
+        },
+      ],
+    };
+    const trappedParams = new Proxy(
+      {},
+      {
+        get: (_target, prop: string | symbol) => {
+          if (prop === "filterAdTrackingFrames") {
+            throw new Error("replay frame-filter trap");
+          }
+          return undefined;
+        },
+      }
+    ) as import("@/types/agent/types").RunFromActionCacheParams;
+
+    await agent.runFromActionCache(cache, page, trappedParams);
+
+    expect(perform).toHaveBeenCalledWith(
+      "click fallback target",
+      expect.objectContaining({
+        filterAdTrackingFrames: false,
+      })
+    );
+  });
+
+  it("truncates oversized cached-step read diagnostics", async () => {
+    const agent = new HyperAgent({
+      llm: createMockLLM(),
+      cdpActions: false,
+    });
+    const page = {} as import("@/types/agent/types").HyperPage;
+    const cache = {
+      taskId: "cache-task",
+      createdAt: new Date().toISOString(),
+      status: TaskStatus.COMPLETED,
+      get steps(): unknown[] {
+        throw new Error("x".repeat(2_000));
+      },
+    } as unknown as ActionCacheOutput;
+
+    const replay = await agent.runFromActionCache(cache, page);
+
+    expect(replay.status).toBe(TaskStatus.FAILED);
+    expect(replay.steps[0]?.message).toContain("Failed to read cached steps");
+    expect(replay.steps[0]?.message).toContain("[truncated");
+  });
+
+  it("sanitizes control characters in cached-step read diagnostics", async () => {
+    const agent = new HyperAgent({
+      llm: createMockLLM(),
+      cdpActions: false,
+    });
+    const page = {} as import("@/types/agent/types").HyperPage;
+    const cache = {
+      taskId: "cache-task",
+      createdAt: new Date().toISOString(),
+      status: TaskStatus.COMPLETED,
+      get steps(): unknown[] {
+        throw new Error(`steps\u0000\n${"x".repeat(2_000)}`);
+      },
+    } as unknown as ActionCacheOutput;
+
+    const replay = await agent.runFromActionCache(cache, page);
+
+    expect(replay.status).toBe(TaskStatus.FAILED);
+    const message = replay.steps[0]?.message ?? "";
+    expect(message).toContain("Failed to read cached steps");
+    expect(message).toContain("[truncated");
+    expect(message).not.toContain("\u0000");
+    expect(message).not.toContain("\n");
+  });
+
+  it("fails replay step cleanly when page getter throws", async () => {
+    const agent = new HyperAgent({
+      llm: createMockLLM(),
+      cdpActions: false,
+    });
+    const cache: ActionCacheOutput = {
+      taskId: "cache-task",
+      createdAt: new Date().toISOString(),
+      status: TaskStatus.COMPLETED,
+      steps: [
+        {
+          stepIndex: 0,
+          instruction: "click login",
+          elementId: "0-1",
+          method: "click",
+          arguments: [],
+          frameIndex: 0,
+          xpath: "//button[1]",
+          actionType: "actElement",
+          success: true,
+          message: "cached",
+        },
+      ],
+    };
+
+    const replay = await agent.runFromActionCache(cache, () => {
+      throw new Error("page getter trap");
+    });
+
+    expect(replay.status).toBe(TaskStatus.FAILED);
+    expect(replay.steps[0]?.message).toContain("page getter trap");
+  });
+
+  it("truncates oversized page-getter replay diagnostics", async () => {
+    const agent = new HyperAgent({
+      llm: createMockLLM(),
+      cdpActions: false,
+    });
+    const cache: ActionCacheOutput = {
+      taskId: "cache-task",
+      createdAt: new Date().toISOString(),
+      status: TaskStatus.COMPLETED,
+      steps: [
+        {
+          stepIndex: 0,
+          instruction: "click login",
+          elementId: "0-1",
+          method: "click",
+          arguments: [],
+          frameIndex: 0,
+          xpath: "//button[1]",
+          actionType: "actElement",
+          success: true,
+          message: "cached",
+        },
+      ],
+    };
+
+    const replay = await agent.runFromActionCache(cache, () => {
+      throw new Error(`x${"y".repeat(2_000)}\npage getter trap`);
+    });
+
+    expect(replay.status).toBe(TaskStatus.FAILED);
+    expect(replay.steps[0]?.message).toContain("[truncated");
+    expect(replay.steps[0]?.message).not.toContain("\n");
+  });
+
+  it("truncates oversized perform-path replay diagnostics", async () => {
+    const agent = new HyperAgent({
+      llm: createMockLLM(),
+      cdpActions: false,
+    });
+    const perform = jest
+      .fn()
+      .mockRejectedValue(new Error(`x${"y".repeat(2_000)}\nperform failed`));
+    const page = {
+      perform,
+    } as unknown as import("@/types/agent/types").HyperPage;
+    const cache: ActionCacheOutput = {
+      taskId: "cache-task",
+      createdAt: new Date().toISOString(),
+      status: TaskStatus.COMPLETED,
+      steps: [
+        {
+          stepIndex: 0,
+          instruction: "trigger perform",
+          elementId: null,
+          method: null,
+          arguments: [],
+          frameIndex: null,
+          xpath: null,
+          actionType: "unknown-action",
+          success: true,
+          message: "cached",
+        },
+      ],
+    };
+
+    const replay = await agent.runFromActionCache(cache, page);
+
+    expect(replay.status).toBe(TaskStatus.FAILED);
+    expect(replay.steps[0]?.message).toContain("[truncated");
+    expect(replay.steps[0]?.message).not.toContain("\n");
+  });
+
+  it("normalizes invalid maxXPathRetries to default replay retries", async () => {
+    const agent = new HyperAgent({
+      llm: createMockLLM(),
+      cdpActions: false,
+    });
+    const performClick = jest.fn().mockResolvedValue({
+      taskId: "click-task",
+      status: TaskStatus.COMPLETED,
+      steps: [],
+      output: "clicked via helper",
+      replayStepMeta: {
+        usedCachedAction: true,
+        fallbackUsed: false,
+        retries: 1,
+      },
+    });
+    const page = {
+      performClick,
+    } as unknown as import("@/types/agent/types").HyperPage;
+    const cache: ActionCacheOutput = {
+      taskId: "cache-task",
+      createdAt: new Date().toISOString(),
+      status: TaskStatus.COMPLETED,
+      steps: [
+        {
+          stepIndex: 0,
+          instruction: "click login",
+          elementId: "0-1",
+          method: "click",
+          arguments: [],
+          frameIndex: 0,
+          xpath: "//button[1]",
+          actionType: "actElement",
+          success: true,
+          message: "cached",
+        },
+      ],
+    };
+
+    await agent.runFromActionCache(cache, page, {
+      maxXPathRetries: 0,
+    });
+
+    expect(performClick).toHaveBeenCalledWith(
+      "//button[1]",
+      expect.objectContaining({
+        maxSteps: 3,
+      })
+    );
+  });
+
+  it("falls back to default replay params when param getters trap", async () => {
+    const agent = new HyperAgent({
+      llm: createMockLLM(),
+      cdpActions: false,
+    });
+    const performClick = jest.fn().mockResolvedValue({
+      taskId: "click-task",
+      status: TaskStatus.COMPLETED,
+      steps: [],
+      output: "clicked via helper",
+      replayStepMeta: {
+        usedCachedAction: true,
+        fallbackUsed: false,
+        retries: 1,
+      },
+    });
+    const page = {
+      performClick,
+    } as unknown as import("@/types/agent/types").HyperPage;
+    const cache: ActionCacheOutput = {
+      taskId: "cache-task",
+      createdAt: new Date().toISOString(),
+      status: TaskStatus.COMPLETED,
+      steps: [
+        {
+          stepIndex: 0,
+          instruction: "click login",
+          elementId: "0-1",
+          method: "click",
+          arguments: [],
+          frameIndex: 0,
+          xpath: "//button[1]",
+          actionType: "actElement",
+          success: true,
+          message: "cached",
+        },
+      ],
+    };
+    const trapParams = {
+      get maxXPathRetries(): number {
+        throw new Error("max retry getter trap");
+      },
+      get debug(): boolean {
+        throw new Error("debug getter trap");
+      },
+    };
+
+    const replay = await agent.runFromActionCache(
+      cache,
+      page,
+      trapParams as unknown as import("@/types/agent/types").RunFromActionCacheParams
+    );
+
+    expect(replay.status).toBe(TaskStatus.COMPLETED);
+    expect(performClick).toHaveBeenCalledWith(
+      "//button[1]",
+      expect.objectContaining({
+        maxSteps: 3,
+      })
+    );
+  });
+});
diff --git a/src/agent/actions/act-element.ts b/src/agent/actions/act-element.ts
index a961565e..01c9df85 100644
--- a/src/agent/actions/act-element.ts
+++ b/src/agent/actions/act-element.ts
@@ -3,10 +3,12 @@ import { ActionContext, ActionOutput, AgentActionDefinition } from "@/types";
 import { AGENT_ELEMENT_ACTIONS } from "../shared/action-restrictions";
 import { performAction } from "./shared/perform-action";
 
+const SUPPORTED_METHODS_TEXT = AGENT_ELEMENT_ACTIONS.join(", ");
+
 const methodSchema = z
   .enum(AGENT_ELEMENT_ACTIONS)
   .describe(
-    "Method to execute (click, fill, type, press, selectOptionFromDropdown, check, uncheck, hover, scrollToElement, scrollToPercentage, nextChunk, prevChunk)."
+    `Method to execute (${SUPPORTED_METHODS_TEXT}).`
   );
 
 const ActElementAction = z
@@ -21,7 +23,7 @@ const ActElementAction = z
         'Encoded element identifier from the DOM listing (format "frameIndex-backendNodeId", e.g., "0-5125").'
       ),
     method: methodSchema.describe(
-      "CDP/Playwright method to invoke (click, fill, type, press, selectOptionFromDropdown, check, uncheck, hover, scrollToElement, scrollToPercentage, nextChunk, prevChunk)."
+      `CDP/Playwright method to invoke (${SUPPORTED_METHODS_TEXT}).`
     ),
     arguments: z
       .array(z.string())
diff --git a/src/agent/actions/complete-with-output-schema.test.ts b/src/agent/actions/complete-with-output-schema.test.ts
new file mode 100644
index 00000000..ed355b7d
--- /dev/null
+++ b/src/agent/actions/complete-with-output-schema.test.ts
@@ -0,0 +1,156 @@
+import { z } from "zod";
+import { generateCompleteActionWithOutputDefinition } from "@/agent/actions/complete-with-output-schema";
+import type { ActionContext } from "@/types";
+
+describe("generateCompleteActionWithOutputDefinition", () => {
+  const ctx = {} as ActionContext;
+
+  it("returns success output when completion is successful with schema payload", async () => {
+    const definition = generateCompleteActionWithOutputDefinition(
+      z.object({
+        title: z.string(),
+      })
+    );
+
+    const result = await definition.run(ctx, {
+      success: true,
+      outputSchema: {
+        title: "done",
+      },
+    });
+
+    expect(result.success).toBe(true);
+    expect(result.extract).toEqual({ title: "done" });
+  });
+
+  it("returns failure output when completion flag is false", async () => {
+    const definition = generateCompleteActionWithOutputDefinition(
+      z.object({
+        title: z.string(),
+      })
+    );
+
+    const result = await definition.run(ctx, {
+      success: false,
+      outputSchema: {
+        title: "done",
+      },
+    });
+
+    expect(result.success).toBe(false);
+    expect(result.message).toContain("Could not complete task");
+  });
+
+  it("stringifies completion output schema payload", async () => {
+    const definition = generateCompleteActionWithOutputDefinition(
+      z.object({
+        title: z.string(),
+      })
+    );
+
+    const output = await definition.completeAction?.({
+      success: true,
+      outputSchema: {
+        title: "done",
+      },
+    });
+
+    expect(output).toContain('"title": "done"');
+  });
+
+  it("returns failure when success is truthy but not boolean true", async () => {
+    const definition = generateCompleteActionWithOutputDefinition(
+      z.object({
+        title: z.string(),
+      })
+    );
+
+    const result = await definition.run(ctx, {
+      success: "true" as unknown as boolean,
+      outputSchema: {
+        title: "done",
+      },
+    });
+
+    expect(result.success).toBe(false);
+    expect(result.message).toContain("Could not complete task");
+  });
+
+  it("handles trap-prone outputSchema getters gracefully", async () => {
+    const definition = generateCompleteActionWithOutputDefinition(
+      z.object({
+        title: z.string(),
+      })
+    );
+
+    const result = await definition.run(ctx, {
+      success: true,
+      get outputSchema() {
+        throw new Error("output schema trap");
+      },
+    } as unknown as Parameters<typeof definition.run>[1]);
+
+    expect(result.success).toBe(false);
+    expect(result.message).toContain("Could not complete task");
+  });
+
+  it("serializes circular completion payloads safely", async () => {
+    const definition = generateCompleteActionWithOutputDefinition(
+      z.object({
+        title: z.string(),
+      })
+    );
+
+    const circular: Record<string, unknown> = { title: "done" };
+    circular.self = circular;
+
+    const output = await definition.completeAction?.({
+      success: true,
+      outputSchema: circular,
+    });
+
+    expect(output).toContain("[Circular]");
+  });
+
+  it("truncates oversized completion payload output", async () => {
+    const definition = generateCompleteActionWithOutputDefinition(
+      z.object({
+        title: z.string(),
+      })
+    );
+
+    const output = await definition.completeAction?.({
+      success: true,
+      outputSchema: {
+        title: "x".repeat(30_000),
+      },
+    });
+
+    expect(output).toContain("[truncated");
+    expect(output?.length ?? 0).toBeLessThan(21_000);
+  });
+
+  it("sanitizes and truncates non-serializable payload diagnostics", async () => {
+    const definition = generateCompleteActionWithOutputDefinition(
+      z.object({
+        title: z.string(),
+      })
+    );
+
+    const trap = {
+      toJSON: () => {
+        throw new Error(`bad\u0000\n${"x".repeat(10_000)}`);
+      },
+    };
+
+    const output = await definition.completeAction?.({
+      success: true,
+      outputSchema: trap as unknown as Record<string, unknown>,
+    });
+
+    expect(output).toContain("__nonSerializable");
+    expect(output).toContain("[truncated");
+    expect(output).not.toContain("\u0000");
+    expect(output?.length ?? 0).toBeLessThan(900);
+  });
+});
diff --git a/src/agent/actions/complete-with-output-schema.ts b/src/agent/actions/complete-with-output-schema.ts
index 98bbae74..a70b8ea9 100644
--- a/src/agent/actions/complete-with-output-schema.ts
+++ b/src/agent/actions/complete-with-output-schema.ts
@@ -1,8 +1,81 @@
 import { z } from "zod";
 import { ActionContext, ActionOutput, AgentActionDefinition } from "@/types";
+import { formatUnknownError } from "@/utils";
+
+const MAX_COMPLETE_OUTPUT_CHARS = 20_000;
+const MAX_COMPLETE_DIAGNOSTIC_CHARS = 600;
+
+function formatCompleteDiagnostic(value: unknown): string {
+  const raw = typeof value === "string" ? value : formatUnknownError(value);
+  const normalized = Array.from(raw, (char) => {
+    const code = char.charCodeAt(0);
+    return (code >= 0 && code < 32 && code !== 9 && code !== 10) || code === 127
+      ? " "
+      : char;
+  })
+    .join("")
+    .replace(/\s+/g, " ")
+    .trim();
+  const fallback = normalized.length > 0 ? normalized : "unknown error";
+  if (fallback.length <= MAX_COMPLETE_DIAGNOSTIC_CHARS) {
+    return fallback;
+  }
+  const omitted = fallback.length - MAX_COMPLETE_DIAGNOSTIC_CHARS;
+  return `${fallback.slice(0, MAX_COMPLETE_DIAGNOSTIC_CHARS)}... [truncated ${omitted} chars]`;
+}
+
+function safeReadRecordField(value: unknown, key: string): unknown {
+  if (!value || (typeof value !== "object" && typeof value !== "function")) {
+    return undefined;
+  }
+  try {
+    return (value as Record<string, unknown>)[key];
+  } catch {
+    return undefined;
+  }
+}
+
+function safeJsonStringify(value: unknown): string {
+  const seen = new WeakSet<object>();
+  try {
+    const serialized = JSON.stringify(
+      value,
+      (_key, candidate: unknown) => {
+        if (typeof candidate === "bigint") {
+          return `${candidate.toString()}n`;
+        }
+        if (candidate && typeof candidate === "object") {
+          if (seen.has(candidate)) {
+            return "[Circular]";
+          }
+          seen.add(candidate);
+        }
+        return candidate;
+      },
+      2
+    );
+    return typeof serialized === "string"
+      ? serialized
+      : JSON.stringify({ value: serialized }, null, 2);
+  } catch (error) {
+    return JSON.stringify(
+      { __nonSerializable: formatCompleteDiagnostic(error) },
+      null,
+      2
+    );
+  }
+}
+
+function truncateOutput(value: string): string {
+  if (value.length <= MAX_COMPLETE_OUTPUT_CHARS) {
+    return value;
+  }
+  const omitted = value.length - MAX_COMPLETE_OUTPUT_CHARS;
+  return `${value.slice(0, MAX_COMPLETE_OUTPUT_CHARS)}\n... [truncated ${omitted} chars]`;
+}
 
 export const generateCompleteActionWithOutputDefinition = (
-  outputSchema: z.ZodType<any>
+  outputSchema: z.ZodType<unknown>
 ): AgentActionDefinition => {
   const actionParamsSchema = z
     .object({
@@ -19,20 +92,22 @@ export const generateCompleteActionWithOutputDefinition = (
       "Complete the task. An output schema has been provided to you. Try your best to provide your response so that it fits the output schema provided."
     );
 
-  type CompeleteActionWithOutputSchema = z.infer<typeof actionParamsSchema>;
+  type CompleteActionWithOutputSchema = z.infer<typeof actionParamsSchema>;
 
   return {
     type: "complete" as const,
     actionParams: actionParamsSchema,
     run: async (
       ctx: ActionContext,
-      actionParams: CompeleteActionWithOutputSchema
+      actionParams: CompleteActionWithOutputSchema
     ): Promise<ActionOutput> => {
-      if (actionParams.success && actionParams.outputSchema) {
+      const success = safeReadRecordField(actionParams, "success") === true;
+      const extracted = safeReadRecordField(actionParams, "outputSchema");
+      if (success && extracted != null) {
         return {
           success: true,
           message: "The action generated an object",
-          extract: actionParams.outputSchema,
+          extract: extracted as object,
         };
       } else {
         return {
@@ -42,8 +117,9 @@ export const generateCompleteActionWithOutputDefinition = (
         };
       }
     },
-    completeAction: async (params: CompeleteActionWithOutputSchema) => {
-      return JSON.stringify(params.outputSchema, null, 2);
+    completeAction: async (params: CompleteActionWithOutputSchema) => {
+      const outputSchemaValue = safeReadRecordField(params, "outputSchema");
+      return truncateOutput(safeJsonStringify(outputSchemaValue));
     },
   };
 };
diff --git a/src/agent/actions/complete.test.ts b/src/agent/actions/complete.test.ts
new file mode 100644
index 00000000..6a7754dd
--- /dev/null
+++ b/src/agent/actions/complete.test.ts
@@ -0,0 +1,77 @@
+import { CompleteActionDefinition } from "@/agent/actions/complete";
+import type { ActionContext } from "@/types";
+
+describe("CompleteActionDefinition", () => {
+  const ctx = {} as ActionContext;
+
+  it("returns success output when params.success is true", async () => {
+    const result = await CompleteActionDefinition.run(ctx, {
+      success: true,
+      text: "final answer",
+    });
+
+    expect(result.success).toBe(true);
+    expect(result.message).toBe("Task Complete");
+  });
+
+  it("returns failed output when params.success is false", async () => {
+    const result = await CompleteActionDefinition.run(ctx, {
+      success: false,
+      text: "final answer",
+    });
+
+    expect(result.success).toBe(false);
+    expect(result.message).toBe("Task marked as failed");
+  });
+
+  it("normalizes non-boolean success values to false", async () => {
+    const result = await CompleteActionDefinition.run(ctx, {
+      success: "yes" as unknown as boolean,
+      text: "final answer",
+    });
+
+    expect(result.success).toBe(false);
+    expect(result.message).toBe("Task marked as failed");
+  });
+
+  it("returns fallback text when response text is null", async () => {
+    const output = await CompleteActionDefinition.completeAction?.({
+      success: true,
+      text: null,
+    });
+
+    expect(output).toBe("No response text found");
+  });
+
+  it("handles trap-prone text getters safely", async () => {
+    const output = await CompleteActionDefinition.completeAction?.({
+      success: true,
+      get text(): string | null {
+        throw new Error("text getter trap");
+      },
+    } as unknown as Parameters<NonNullable<typeof CompleteActionDefinition.completeAction>>[0]);
+
+    expect(output).toContain("No response text found");
+  });
+
+  it("truncates oversized completion text output", async () => {
+    const output = await CompleteActionDefinition.completeAction?.({
+      success: true,
+      text: "x".repeat(30_000),
+    });
+
+    expect(output).toContain("[truncated");
+    expect((output ?? "").length).toBeLessThan(20_500);
+  });
+
+  it("sanitizes unsupported control characters in completion text", async () => {
+    const output = await CompleteActionDefinition.completeAction?.({
+      success: true,
+      text: "line\u0000 one\nline\u0007 two",
+    });
+
+    expect(output).toBe("line  one\nline  two");
+    expect(output).not.toContain("\u0000");
+    expect(output).not.toContain("\u0007");
+  });
+});
diff --git a/src/agent/actions/complete.ts b/src/agent/actions/complete.ts
index 6dcd84c8..bc565603 100644
--- a/src/agent/actions/complete.ts
+++ b/src/agent/actions/complete.ts
@@ -1,5 +1,53 @@
 import { z } from "zod";
 import { ActionOutput, AgentActionDefinition } from "@/types";
+import { formatUnknownError } from "@/utils";
+
+const MAX_COMPLETE_TEXT_CHARS = 20_000;
+
+function sanitizeCompleteText(value: string): string {
+  if (value.length === 0) {
+    return value;
+  }
+  return Array.from(value, (char) => {
+    const code = char.charCodeAt(0);
+    if (code === 9 || code === 10) {
+      return char;
+    }
+    return (code >= 0 && code < 32) || code === 127 ? " " : char;
+  }).join("");
+}
+
+function safeReadRecordField(value: unknown, key: string): unknown {
+  if (!value || (typeof value !== "object" && typeof value !== "function")) {
+    return undefined;
+  }
+  try {
+    return (value as Record<string, unknown>)[key];
+  } catch {
+    return undefined;
+  }
+}
+
+function normalizeCompleteText(value: unknown, fallback: string): string {
+  const raw =
+    typeof value === "string"
+      ? value
+      : value == null
+        ? fallback
+        : formatUnknownError(value);
+  const normalized = sanitizeCompleteText(raw).replace(/\r\n?/g, "\n").trim();
+  if (normalized.length === 0) {
+    return fallback;
+  }
+  if (normalized.length <= MAX_COMPLETE_TEXT_CHARS) {
+    return normalized;
+  }
+  const omitted = normalized.length - MAX_COMPLETE_TEXT_CHARS;
+  return `${normalized.slice(
+    0,
+    MAX_COMPLETE_TEXT_CHARS
+  )}\n... [truncated ${omitted} chars]`;
+}
 
 export const CompleteAction = z
   .object({
@@ -20,11 +68,18 @@ export type CompleteActionType = z.infer<typeof CompleteAction>;
 export const CompleteActionDefinition: AgentActionDefinition = {
   type: "complete" as const,
   actionParams: CompleteAction,
-  run: async (): Promise<ActionOutput> => {
-    return { success: true, message: "Task Complete" };
+  run: async (_ctx, params): Promise<ActionOutput> => {
+    const success = safeReadRecordField(params, "success") === true;
+    return {
+      success,
+      message: success ? "Task Complete" : "Task marked as failed",
+    };
   },
   completeAction: async (params: CompleteActionType) => {
-    return params.text ?? "No response text found";
+    return normalizeCompleteText(
+      safeReadRecordField(params, "text"),
+      "No response text found"
+    );
   },
   pprintAction: function (params: CompleteActionType): string {
     return `Complete task with ${params.success ? "success" : "failure"}`;
diff --git a/src/agent/actions/extract.test.ts b/src/agent/actions/extract.test.ts
new file mode 100644
index 00000000..e4a8804b
--- /dev/null
+++ b/src/agent/actions/extract.test.ts
@@ -0,0 +1,602 @@
+import fs from "fs";
+import {
+  ExtractActionDefinition,
+  estimateTextTokenCount,
+  trimMarkdownToTokenLimit,
+} from "@/agent/actions/extract";
+import type { ActionContext } from "@/types";
+import type { HyperAgentLLM } from "@/llm/types";
+
+jest.mock("@/utils/html-to-markdown", () => ({
+  parseMarkdown: jest.fn(),
+}));
+
+jest.mock("@/cdp", () => ({
+  getCDPClient: jest.fn(),
+}));
+
+const { parseMarkdown } = jest.requireMock("@/utils/html-to-markdown") as {
+  parseMarkdown: jest.Mock;
+};
+
+const { getCDPClient } = jest.requireMock("@/cdp") as {
+  getCDPClient: jest.Mock;
+};
+
+function createMockLLM(
+  invokeMock?: jest.Mock,
+  options?: { multimodal?: boolean }
+): HyperAgentLLM {
+  return {
+    invoke: invokeMock
+      ? (async (messages) => invokeMock(messages))
+      : async () => ({
+        role: "assistant",
+        content: "extracted output",
+        }),
+    invokeStructured: async () => ({ rawText: "{}", parsed: null }),
+    getProviderId: () => "mock",
+    getModelId: () => "mock-model",
+    getCapabilities: () => ({
+      multimodal: options?.multimodal ?? true,
+      toolCalling: true,
+      jsonMode: true,
+    }),
+  };
+}
+
+function createContext(
+  llm?: HyperAgentLLM,
+  overrides?: Partial<ActionContext>
+): ActionContext {
+  return {
+    page: {
+      content: jest.fn().mockResolvedValue("<html>demo</html>"),
+    } as unknown as ActionContext["page"],
+    domState: {
+      elements: new Map(),
+      domState: "",
+      xpathMap: {},
+      backendNodeMap: {},
+    },
+    llm: llm ?? createMockLLM(),
+    tokenLimit: 200,
+    variables: [],
+    invalidateDomCache: jest.fn(),
+    ...overrides,
+  } as ActionContext;
+}
+
+describe("extract action token helpers", () => {
+  it("returns zero tokens for empty or whitespace-only content", () => {
+    expect(estimateTextTokenCount("")).toBe(0);
+    expect(estimateTextTokenCount("   \n\t")).toBe(0);
+  });
+
+  it("estimates token count as positive non-zero", () => {
+    expect(estimateTextTokenCount("hello world")).toBeGreaterThan(0);
+  });
+
+  it("trims markdown and appends truncation notice when over limit", () => {
+    const markdown = "a".repeat(2000);
+    const trimmed = trimMarkdownToTokenLimit(markdown, 20);
+
+    expect(trimmed).toContain("[Content truncated due to token limit]");
+    expect(trimmed.length).toBeLessThan(markdown.length);
+  });
+});
+
+describe("ExtractActionDefinition.run", () => {
+  beforeEach(() => {
+    jest.clearAllMocks();
+    parseMarkdown.mockResolvedValue("page markdown content");
+    getCDPClient.mockResolvedValue({
+      acquireSession: jest.fn().mockResolvedValue({
+        send: jest.fn().mockResolvedValue({ data: "abc" }),
+      }),
+    });
+  });
+
+  it("falls back to markdown-only extraction when screenshot capture fails", async () => {
+    getCDPClient.mockRejectedValue(new Error("cdp unavailable"));
+    const invoke = jest.fn().mockResolvedValue({
+      role: "assistant",
+      content: "fallback extraction",
+    });
+    const ctx = createContext(createMockLLM(invoke));
+
+    const result = await ExtractActionDefinition.run(ctx, {
+      objective: "Extract price",
+    });
+
+    expect(result.success).toBe(true);
+    expect(invoke).toHaveBeenCalled();
+    const messagesArg = invoke.mock.calls[0]?.[0];
+    const contentParts = messagesArg?.[0]?.content as Array<{
+      type: string;
+      url?: string;
+    }>;
+    expect(contentParts).toHaveLength(1);
+    expect(contentParts[0]?.type).toBe("text");
+  });
+
+  it("fails fast when extraction objective is empty", async () => {
+    const invoke = jest.fn().mockResolvedValue({
+      role: "assistant",
+      content: "should not be called",
+    });
+    const pageContent = jest.fn().mockResolvedValue("<html>unused</html>");
+    const ctx = createContext(createMockLLM(invoke), {
+      page: {
+        content: pageContent,
+      } as unknown as ActionContext["page"],
+    });
+
+    const result = await ExtractActionDefinition.run(ctx, {
+      objective: "   ",
+    });
+
+    expect(result.success).toBe(false);
+    expect(result.message).toContain("objective cannot be empty");
+    expect(pageContent).not.toHaveBeenCalled();
+    expect(invoke).not.toHaveBeenCalled();
+  });
+
+  it("does not fail when debug file writes throw", async () => {
+    const writeSpy = jest.spyOn(fs, "writeFileSync").mockImplementation(() => {
+      throw new Error("disk full");
+    });
+    const errorSpy = jest.spyOn(console, "error").mockImplementation(() => {});
+    const ctx = createContext(undefined, { debugDir: "debug", debug: true });
+
+    try {
+      const result = await ExtractActionDefinition.run(ctx, {
+        objective: "Extract title",
+      });
+      expect(result.success).toBe(true);
+      expect(errorSpy).toHaveBeenCalled();
+    } finally {
+      writeSpy.mockRestore();
+      errorSpy.mockRestore();
+    }
+  });
+
+  it("prepares debug directory before writing artifacts", async () => {
+    const mkdirSpy = jest
+      .spyOn(fs, "mkdirSync")
+      .mockImplementation(() => undefined);
+    const ctx = createContext(undefined, { debugDir: "debug", debug: true });
+
+    try {
+      const result = await ExtractActionDefinition.run(ctx, {
+        objective: "Extract title",
+      });
+      expect(result.success).toBe(true);
+      expect(mkdirSpy).toHaveBeenCalledWith("debug", { recursive: true });
+    } finally {
+      mkdirSpy.mockRestore();
+    }
+  });
+
+  it("continues extraction when debug directory creation fails", async () => {
+    const mkdirSpy = jest.spyOn(fs, "mkdirSync").mockImplementation(() => {
+      throw new Error("mkdir failed");
+    });
+    const errorSpy = jest.spyOn(console, "error").mockImplementation(() => {});
+    const ctx = createContext(undefined, { debugDir: "debug", debug: true });
+
+    try {
+      const result = await ExtractActionDefinition.run(ctx, {
+        objective: "Extract title",
+      });
+
+      expect(result.success).toBe(true);
+      expect(errorSpy).toHaveBeenCalled();
+    } finally {
+      mkdirSpy.mockRestore();
+      errorSpy.mockRestore();
+    }
+  });
+
+  it("formats non-Error debug directory creation failures", async () => {
+    const mkdirSpy = jest.spyOn(fs, "mkdirSync").mockImplementation(() => {
+      throw { reason: "mkdir object failure" };
+    });
+    const errorSpy = jest.spyOn(console, "error").mockImplementation(() => {});
+    const ctx = createContext(undefined, { debugDir: "debug", debug: true });
+
+    try {
+      const result = await ExtractActionDefinition.run(ctx, {
+        objective: "Extract title",
+      });
+
+      expect(result.success).toBe(true);
+      expect(errorSpy).toHaveBeenCalledWith(
+        '[extract] Failed to prepare debug directory "debug": {"reason":"mkdir object failure"}'
+      );
+    } finally {
+      mkdirSpy.mockRestore();
+      errorSpy.mockRestore();
+    }
+  });
+
+  it("truncates oversized debug directory diagnostics", async () => {
+    const mkdirSpy = jest.spyOn(fs, "mkdirSync").mockImplementation(() => {
+      throw new Error(`mkdir\n${"x".repeat(10_000)}`);
+    });
+    const errorSpy = jest.spyOn(console, "error").mockImplementation(() => {});
+    const ctx = createContext(undefined, { debugDir: "debug", debug: true });
+
+    try {
+      const result = await ExtractActionDefinition.run(ctx, {
+        objective: "Extract title",
+      });
+
+      expect(result.success).toBe(true);
+      const debugError = errorSpy.mock.calls
+        .map((call) => String(call[0]))
+        .find((line) =>
+          line.includes('[extract] Failed to prepare debug directory')
+        );
+      expect(debugError).toBeDefined();
+      expect(debugError).toContain("[truncated");
+      expect(debugError).not.toContain("\n");
+      expect(debugError?.length ?? 0).toBeLessThan(700);
+    } finally {
+      mkdirSpy.mockRestore();
+      errorSpy.mockRestore();
+    }
+  });
+
+  it("formats non-Error debug write failures", async () => {
+    const mkdirSpy = jest
+      .spyOn(fs, "mkdirSync")
+      .mockImplementation(() => undefined);
+    const writeSpy = jest.spyOn(fs, "writeFileSync").mockImplementation(() => {
+      throw { reason: "disk object failure" };
+    });
+    const errorSpy = jest.spyOn(console, "error").mockImplementation(() => {});
+    const ctx = createContext(undefined, { debugDir: "debug", debug: true });
+
+    try {
+      const result = await ExtractActionDefinition.run(ctx, {
+        objective: "Extract title",
+      });
+
+      expect(result.success).toBe(true);
+      expect(errorSpy).toHaveBeenCalledWith(
+        expect.stringContaining('{"reason":"disk object failure"}')
+      );
+    } finally {
+      mkdirSpy.mockRestore();
+      writeSpy.mockRestore();
+      errorSpy.mockRestore();
+    }
+  });
+
+  it("returns failure when llm responds without text content", async () => {
+    const emptyTextLlm = createMockLLM(
+      jest.fn().mockResolvedValue({
+      role: "assistant",
+      content: [{ type: "tool_call", toolName: "noop", arguments: {} }],
+      })
+    );
+    const ctx = createContext(emptyTextLlm);
+
+    const result = await ExtractActionDefinition.run(ctx, {
+      objective: "Extract content",
+    });
+
+    expect(result.success).toBe(false);
+    expect(result.message).toContain("No content extracted");
+  });
+
+  it("returns failure when page.content is unavailable", async () => {
+    const ctx = createContext(undefined, {
+      page: {} as unknown as ActionContext["page"],
+    });
+
+    const result = await ExtractActionDefinition.run(ctx, {
+      objective: "Extract content",
+    });
+
+    expect(result.success).toBe(false);
+    expect(result.message).toContain("page content method is unavailable");
+  });
+
+  it("handles page.content getter traps gracefully", async () => {
+    const trappedPage = new Proxy(
+      {},
+      {
+        get: (_target, prop) => {
+          if (prop === "content") {
+            throw new Error("content getter trap");
+          }
+          return undefined;
+        },
+      }
+    ) as unknown as ActionContext["page"];
+    const ctx = createContext(undefined, {
+      page: trappedPage,
+    });
+
+    const result = await ExtractActionDefinition.run(ctx, {
+      objective: "Extract content",
+    });
+
+    expect(result.success).toBe(false);
+    expect(result.message).toContain("content getter trap");
+  });
+
+  it("returns failure when llm text content is only whitespace", async () => {
+    const whitespaceLlm = createMockLLM(
+      jest.fn().mockResolvedValue({
+        role: "assistant",
+        content: "   \n\t  ",
+      })
+    );
+    const ctx = createContext(whitespaceLlm);
+
+    const result = await ExtractActionDefinition.run(ctx, {
+      objective: "Extract content",
+    });
+
+    expect(result.success).toBe(false);
+    expect(result.message).toContain("No content extracted");
+  });
+
+  it("truncates oversized extracted text outputs", async () => {
+    const largeOutput = "x".repeat(15_000);
+    const oversizedLlm = createMockLLM(
+      jest.fn().mockResolvedValue({
+        role: "assistant",
+        content: largeOutput,
+      })
+    );
+    const ctx = createContext(oversizedLlm);
+
+    const result = await ExtractActionDefinition.run(ctx, {
+      objective: "Extract content",
+    });
+
+    expect(result.success).toBe(true);
+    expect(result.message).toContain("[Extraction output truncated]");
+    expect(result.message.length).toBeLessThan(13_000);
+  });
+
+  it("handles response content arrays with getter traps safely", async () => {
+    const trapContentPart = {
+      type: "text",
+      get text(): string {
+        throw new Error("text getter trap");
+      },
+    };
+    const trapLlm = createMockLLM(
+      jest.fn().mockResolvedValue({
+        role: "assistant",
+        content: [trapContentPart],
+      })
+    );
+    const ctx = createContext(trapLlm);
+
+    const result = await ExtractActionDefinition.run(ctx, {
+      objective: "Extract content",
+    });
+
+    expect(result.success).toBe(false);
+    expect(result.message).toContain("No content extracted");
+  });
+
+  it("returns formatted root error messages", async () => {
+    const pageContent = jest
+      .fn()
+      .mockRejectedValue(new Error("page content unavailable"));
+    const ctx = createContext(undefined, {
+      page: {
+        content: pageContent,
+      } as unknown as ActionContext["page"],
+    });
+
+    const result = await ExtractActionDefinition.run(ctx, {
+      objective: "Extract content",
+    });
+
+    expect(result.success).toBe(false);
+    expect(result.message).toContain("page content unavailable");
+  });
+
+  it("truncates oversized root extraction errors", async () => {
+    const pageContent = jest
+      .fn()
+      .mockRejectedValue(new Error(`boom\n${"x".repeat(10_000)}`));
+    const ctx = createContext(undefined, {
+      page: {
+        content: pageContent,
+      } as unknown as ActionContext["page"],
+    });
+
+    const result = await ExtractActionDefinition.run(ctx, {
+      objective: "Extract content",
+    });
+
+    expect(result.success).toBe(false);
+    expect(result.message).toContain("[truncated");
+    expect(result.message).not.toContain("\n");
+    expect(result.message.length).toBeLessThan(700);
+  });
+
+  it("applies markdown token budget based on overall token limit", async () => {
+    getCDPClient.mockRejectedValue(new Error("cdp unavailable"));
+    parseMarkdown.mockResolvedValue("token ".repeat(3000));
+    const invoke = jest.fn().mockResolvedValue({
+      role: "assistant",
+      content: "budgeted extraction",
+    });
+    const ctx = createContext(createMockLLM(invoke), { tokenLimit: 120 });
+
+    await ExtractActionDefinition.run(ctx, {
+      objective: "Extract concise summary",
+    });
+
+    const messages = invoke.mock.calls[0]?.[0] as Array<{
+      role: string;
+      content: Array<{ type: string; text?: string }>;
+    }>;
+    const promptText = messages[0]?.content?.[0]?.text ?? "";
+    expect(promptText).toContain("[Content truncated due to token limit]");
+    expect(estimateTextTokenCount(promptText)).toBeLessThanOrEqual(120);
+  });
+
+  it("uses default token limit when provided limit is invalid", async () => {
+    getCDPClient.mockRejectedValue(new Error("cdp unavailable"));
+    parseMarkdown.mockResolvedValue("token ".repeat(6000));
+    const invoke = jest.fn().mockResolvedValue({
+      role: "assistant",
+      content: "default budget extraction",
+    });
+    const ctx = createContext(createMockLLM(invoke), { tokenLimit: NaN });
+
+    const result = await ExtractActionDefinition.run(ctx, {
+      objective: "Extract summary",
+    });
+
+    expect(result.success).toBe(true);
+    const messages = invoke.mock.calls[0]?.[0] as Array<{
+      role: string;
+      content: Array<{ type: string; text?: string }>;
+    }>;
+    const promptText = messages[0]?.content?.[0]?.text ?? "";
+    expect(promptText).toContain("[Content truncated due to token limit]");
+    expect(estimateTextTokenCount(promptText)).toBeLessThanOrEqual(4000);
+  });
+
+  it("handles extremely small token limits without oversized markdown payload", async () => {
+    getCDPClient.mockRejectedValue(new Error("cdp unavailable"));
+    parseMarkdown.mockResolvedValue("token ".repeat(3000));
+    const invoke = jest.fn().mockResolvedValue({
+      role: "assistant",
+      content: "small-limit extraction",
+    });
+    const ctx = createContext(createMockLLM(invoke), { tokenLimit: 10 });
+
+    const result = await ExtractActionDefinition.run(ctx, {
+      objective: "x",
+    });
+
+    expect(result.success).toBe(true);
+    const messages = invoke.mock.calls[0]?.[0] as Array<{
+      role: string;
+      content: Array<{ type: string; text?: string }>;
+    }>;
+    const promptText = messages[0]?.content?.[0]?.text ?? "";
+    expect(promptText).toContain("[Content truncated due to token limit]");
+    expect(promptText.length).toBeLessThan(500);
+  });
+
+  it("falls back to plain text extraction when markdown conversion fails", async () => {
+    parseMarkdown.mockRejectedValue(new Error("markdown parse failed"));
+    const invoke = jest.fn().mockResolvedValue({
+      role: "assistant",
+      content: "fallback markdown extraction",
+    });
+    const warnSpy = jest.spyOn(console, "warn").mockImplementation(() => {});
+    const ctx = createContext(createMockLLM(invoke), { debug: true });
+
+    try {
+      const result = await ExtractActionDefinition.run(ctx, {
+        objective: "Extract content",
+      });
+
+      expect(result.success).toBe(true);
+      expect(warnSpy).toHaveBeenCalled();
+      const messages = invoke.mock.calls[0]?.[0] as Array<{
+        content: Array<{ type: string; text?: string }>;
+      }>;
+      const promptText = messages[0]?.content?.[0]?.text ?? "";
+      expect(promptText).toContain("demo");
+    } finally {
+      warnSpy.mockRestore();
+    }
+  });
+
+  it("falls back to plain text extraction when markdown output is empty", async () => {
+    parseMarkdown.mockResolvedValue("");
+    const invoke = jest.fn().mockResolvedValue({
+      role: "assistant",
+      content: "empty-markdown fallback extraction",
+    });
+    const ctx = createContext(createMockLLM(invoke));
+
+    const result = await ExtractActionDefinition.run(ctx, {
+      objective: "Extract content",
+    });
+
+    expect(result.success).toBe(true);
+    const messages = invoke.mock.calls[0]?.[0] as Array<{
+      content: Array<{ type: string; text?: string }>;
+    }>;
+    const promptText = messages[0]?.content?.[0]?.text ?? "";
+    expect(promptText).toContain("demo");
+  });
+
+  it("skips screenshot content when model is not multimodal", async () => {
+    const invoke = jest.fn().mockResolvedValue({
+      role: "assistant",
+      content: "non multimodal extraction",
+    });
+    const warnSpy = jest.spyOn(console, "warn").mockImplementation(() => {});
+    const ctx = createContext(createMockLLM(invoke, { multimodal: false }), {
+      debug: true,
+    });
+
+    try {
+      const result = await ExtractActionDefinition.run(ctx, {
+        objective: "Extract content",
+      });
+
+      expect(result.success).toBe(true);
+      expect(warnSpy).toHaveBeenCalledWith(
+        "[extract] LLM does not support multimodal input; proceeding without screenshot."
+      );
+
+      const messages = invoke.mock.calls[0]?.[0] as Array<{
+        content: Array<{ type: string }>;
+      }>;
+      expect(messages[0]?.content).toHaveLength(1);
+      expect(messages[0]?.content?.[0]?.type).toBe("text");
+      expect(getCDPClient).not.toHaveBeenCalled();
+    } finally {
+      warnSpy.mockRestore();
+    }
+  });
+
+  it("falls back to markdown-only mode when capabilities getter throws", async () => {
+    const invoke = jest.fn().mockResolvedValue({
+      role: "assistant",
+      content: "capability trap fallback",
+    });
+    const llm = createMockLLM(invoke);
+    const trappedLlm = {
+      ...llm,
+      getCapabilities: () => {
+        throw new Error("capability getter trap");
+      },
+    };
+    const warnSpy = jest.spyOn(console, "warn").mockImplementation(() => {});
+    const ctx = createContext(trappedLlm, { debug: true });
+
+    try {
+      const result = await ExtractActionDefinition.run(ctx, {
+        objective: "Extract content",
+      });
+
+      expect(result.success).toBe(true);
+      expect(warnSpy).toHaveBeenCalledWith(
+        "[extract] LLM does not support multimodal input; proceeding without screenshot."
+      );
+      expect(getCDPClient).not.toHaveBeenCalled();
+    } finally {
+      warnSpy.mockRestore();
+    }
+  });
+});
diff --git a/src/agent/actions/extract.ts b/src/agent/actions/extract.ts
index 8fb366f9..b05dc374 100644
--- a/src/agent/actions/extract.ts
+++ b/src/agent/actions/extract.ts
@@ -3,6 +3,8 @@ import { ActionContext, ActionOutput, AgentActionDefinition } from "@/types";
 import { parseMarkdown } from "@/utils/html-to-markdown";
 import fs from "fs";
 import { getCDPClient } from "@/cdp";
+import type { HyperAgentContentPart } from "@/llm/types";
+import { formatUnknownError } from "@/utils";
 
 export const ExtractAction = z
   .object({
@@ -14,6 +16,219 @@ export const ExtractAction = z
 
 export type ExtractActionType = z.infer<typeof ExtractAction>;
 
+const EXTRACT_TRUNCATION_NOTICE = "\n[Content truncated due to token limit]";
+const MAX_EXTRACT_OBJECTIVE_CHARS = 1_000;
+const MAX_EXTRACT_RESPONSE_CHARS = 12_000;
+const EXTRACT_RESPONSE_TRUNCATION_NOTICE = "\n[Extraction output truncated]";
+const MAX_EXTRACT_HTML_CHARS = 1_000_000;
+const MAX_EXTRACT_DIAGNOSTIC_CHARS = 400;
+
+function truncateExtractDiagnostic(value: string): string {
+  if (value.length <= MAX_EXTRACT_DIAGNOSTIC_CHARS) {
+    return value;
+  }
+  const omittedChars = value.length - MAX_EXTRACT_DIAGNOSTIC_CHARS;
+  return `${value.slice(0, MAX_EXTRACT_DIAGNOSTIC_CHARS)}... [truncated ${omittedChars} chars]`;
+}
+
+function sanitizeExtractDiagnostic(value: string): string {
+  if (value.length === 0) {
+    return value;
+  }
+  const withoutControlChars = Array.from(value, (char) => {
+    const code = char.charCodeAt(0);
+    return (code >= 0 && code < 32) || code === 127 ? " " : char;
+  }).join("");
+  return withoutControlChars.replace(/\s+/g, " ").trim();
+}
+
+function formatExtractDiagnostic(value: unknown): string {
+  const raw = typeof value === "string" ? value : formatUnknownError(value);
+  const normalized = sanitizeExtractDiagnostic(raw);
+  if (normalized.length === 0) {
+    return "unknown error";
+  }
+  return truncateExtractDiagnostic(normalized);
+}
+
+export function estimateTextTokenCount(text: string): number {
+  if (text.trim().length === 0) {
+    return 0;
+  }
+  const wordCount = text.match(/[A-Za-z0-9_]+/g)?.length ?? 0;
+  const cjkCount =
+    text.match(/[\u3040-\u30ff\u3400-\u4dbf\u4e00-\u9fff\uf900-\ufaff]/g)
+      ?.length ?? 0;
+  const symbolCount = text.match(/[^\sA-Za-z0-9_]/g)?.length ?? 0;
+  const characterEstimate = Math.ceil(text.length / 3.8);
+  const lexicalEstimate = Math.ceil(
+    wordCount * 1.1 + cjkCount + symbolCount * 0.3
+  );
+  return Math.max(characterEstimate, lexicalEstimate);
+}
+
+export function trimMarkdownToTokenLimit(
+  markdown: string,
+  tokenLimit: number
+): string {
+  if (estimateTextTokenCount(markdown) <= tokenLimit) {
+    return markdown;
+  }
+
+  const suffixTokens = estimateTextTokenCount(EXTRACT_TRUNCATION_NOTICE);
+  if (tokenLimit <= suffixTokens) {
+    return EXTRACT_TRUNCATION_NOTICE;
+  }
+
+  const targetPrefixTokens = tokenLimit - suffixTokens;
+  let low = 0;
+  let high = markdown.length;
+  let best = 0;
+
+  while (low <= high) {
+    const mid = Math.floor((low + high) / 2);
+    const prefix = markdown.slice(0, mid);
+    if (estimateTextTokenCount(prefix) <= targetPrefixTokens) {
+      best = mid;
+      low = mid + 1;
+    } else {
+      high = mid - 1;
+    }
+  }
+
+  return markdown.slice(0, best) + EXTRACT_TRUNCATION_NOTICE;
+}
+
+function writeDebugFileSafe(
+  filePath: string,
+  content: Buffer | string,
+  debug?: boolean
+): void {
+  try {
+    fs.writeFileSync(filePath, content);
+  } catch (error) {
+    if (debug) {
+      console.error(
+        `[extract] Failed to write debug file "${filePath}": ${formatExtractDiagnostic(
+          error
+        )}`
+      );
+    }
+  }
+}
+
+function ensureDebugDirSafe(debugDir: string, debug?: boolean): string | null {
+  try {
+    fs.mkdirSync(debugDir, { recursive: true });
+    return debugDir;
+  } catch (error) {
+    if (debug) {
+      console.error(
+        `[extract] Failed to prepare debug directory "${debugDir}": ${formatExtractDiagnostic(
+          error
+        )}`
+      );
+    }
+    return null;
+  }
+}
+
+function fallbackMarkdownFromHtml(html: string): string {
+  return html
+    .replace(/<script[\s\S]*?<\/script>/gi, " ")
+    .replace(/<style[\s\S]*?<\/style>/gi, " ")
+    .replace(/<[^>]+>/g, " ")
+    .replace(/\s+/g, " ")
+    .trim();
+}
+
+function computeMarkdownTokenBudget(params: {
+  tokenLimit: number;
+  objective: string;
+  hasScreenshot: boolean;
+}): number {
+  const { tokenLimit, objective, hasScreenshot } = params;
+  const templateText = hasScreenshot
+    ? `Extract the following information from the page according to this objective: "${objective}"\n\nPage content:\n\nHere is a screenshot of the page:\n`
+    : `Extract the following information from the page according to this objective: "${objective}"\n\nPage content:\n\nNo screenshot was available. Use the page content to extract the answer.`;
+  const templateTokens = estimateTextTokenCount(templateText);
+  const available = Math.floor(tokenLimit * 0.9) - templateTokens;
+  return Math.max(0, available);
+}
+
+function normalizeTokenLimit(value: number): number {
+  if (!Number.isFinite(value) || value <= 0) {
+    return 4000;
+  }
+  return Math.floor(value);
+}
+
+function safeReadRecordField(value: unknown, key: string): unknown {
+  if (!value || (typeof value !== "object" && typeof value !== "function")) {
+    return undefined;
+  }
+  try {
+    return (value as Record<string, unknown>)[key];
+  } catch {
+    return undefined;
+  }
+}
+
+function normalizeObjective(value: unknown): string {
+  if (typeof value !== "string") {
+    return "";
+  }
+  const normalized = value.replace(/\s+/g, " ").trim();
+  if (normalized.length <= MAX_EXTRACT_OBJECTIVE_CHARS) {
+    return normalized;
+  }
+  return `${normalized.slice(0, MAX_EXTRACT_OBJECTIVE_CHARS)}…`;
+}
+
+function normalizeExtractedContent(value: string): string {
+  const normalized = value.trim();
+  if (normalized.length <= MAX_EXTRACT_RESPONSE_CHARS) {
+    return normalized;
+  }
+  return `${normalized.slice(0, MAX_EXTRACT_RESPONSE_CHARS)}${EXTRACT_RESPONSE_TRUNCATION_NOTICE}`;
+}
+
+function extractTextResponse(content: unknown): string {
+  if (typeof content === "string") {
+    return normalizeExtractedContent(content);
+  }
+  if (!Array.isArray(content)) {
+    return "";
+  }
+  let parts: unknown[] = [];
+  try {
+    parts = Array.from(content);
+  } catch {
+    return "";
+  }
+
+  const textParts: string[] = [];
+  for (const part of parts) {
+    const type = safeReadRecordField(part, "type");
+    if (type !== "text") {
+      continue;
+    }
+    const text = safeReadRecordField(part, "text");
+    if (typeof text === "string" && text.length > 0) {
+      textParts.push(text);
+    }
+  }
+  return normalizeExtractedContent(textParts.join(""));
+}
+
+function supportsMultimodalInput(ctx: ActionContext): boolean {
+  try {
+    return ctx.llm.getCapabilities().multimodal === true;
+  } catch {
+    return false;
+  }
+}
+
 export const ExtractActionDefinition: AgentActionDefinition = {
   type: "extract" as const,
   actionParams: ExtractAction,
@@ -22,69 +237,143 @@ export const ExtractActionDefinition: AgentActionDefinition = {
     action: ExtractActionType
   ): Promise<ActionOutput> => {
     try {
-      const content = await ctx.page.content();
-      const markdown = await parseMarkdown(content);
-      const objective = action.objective;
-
-      // Take a screenshot of the page
-      const cdpClient = await getCDPClient(ctx.page);
-      const cdpSession = await cdpClient.acquireSession("screenshot");
-      const screenshot = await cdpSession.send<{ data: string }>(
-        "Page.captureScreenshot"
+      const objective = normalizeObjective(
+        safeReadRecordField(action, "objective")
       );
+      if (objective.length === 0) {
+        return {
+          success: false,
+          message: "Extraction objective cannot be empty.",
+        };
+      }
+
+      let contentMethod: unknown;
+      try {
+        contentMethod = ctx.page.content;
+      } catch (error) {
+        return {
+          success: false,
+          message: `Failed to extract content: unable to access page content method (${formatExtractDiagnostic(
+            error
+          )})`,
+        };
+      }
+      if (typeof contentMethod !== "function") {
+        return {
+          success: false,
+          message: "Failed to extract content: page content method is unavailable.",
+        };
+      }
+
+      const rawContent = await contentMethod.call(ctx.page);
+      const normalizedHtmlSource =
+        typeof rawContent === "string"
+          ? rawContent
+          : formatUnknownError(rawContent);
+      const content = normalizedHtmlSource.slice(0, MAX_EXTRACT_HTML_CHARS);
+      const normalizedTokenLimit = normalizeTokenLimit(ctx.tokenLimit);
+      const debugDir = ctx.debugDir
+        ? ensureDebugDirSafe(ctx.debugDir, ctx.debug)
+        : null;
+      let markdown: string;
+      try {
+        markdown = await parseMarkdown(content);
+      } catch (error) {
+        if (ctx.debug) {
+          console.warn(
+            "[extract] Markdown conversion failed, falling back to HTML text extraction:",
+            formatExtractDiagnostic(error)
+          );
+        }
+        markdown = fallbackMarkdownFromHtml(content);
+      }
+      if (markdown.trim().length === 0) {
+        markdown = fallbackMarkdownFromHtml(content);
+      }
+
+      const supportsMultimodal = supportsMultimodalInput(ctx);
+      if (!supportsMultimodal && ctx.debug) {
+        console.warn(
+          "[extract] LLM does not support multimodal input; proceeding without screenshot."
+        );
+      }
+
+      // Try to take a screenshot of the page only for multimodal models; continue with text-only extraction if unavailable
+      let screenshotData: string | null = null;
+      if (supportsMultimodal) {
+        try {
+          const cdpClient = await getCDPClient(ctx.page);
+          const cdpSession = await cdpClient.acquireSession("screenshot");
+          const screenshot = await cdpSession.send<{ data: string }>(
+            "Page.captureScreenshot"
+          );
+          screenshotData = screenshot.data;
+        } catch (error) {
+          if (ctx.debug) {
+            console.warn(
+              "[extract] Screenshot capture unavailable, falling back to markdown-only extraction:",
+              formatExtractDiagnostic(error)
+            );
+          }
+        }
+      }
 
       // Save screenshot to debug dir if exists
-      if (ctx.debugDir) {
-        fs.writeFileSync(
-          `${ctx.debugDir}/extract-screenshot.png`,
-          Buffer.from(screenshot.data, "base64")
+      if (debugDir && screenshotData) {
+        writeDebugFileSafe(
+          `${debugDir}/extract-screenshot.png`,
+          Buffer.from(screenshotData, "base64"),
+          ctx.debug
         );
       }
 
-      // Trim markdown to stay within token limit
-      // TODO: this is a hack, we should use a better token counting method
-      const avgTokensPerChar = 0.75; // Conservative estimate of tokens per character
-      const maxChars = Math.floor(ctx.tokenLimit / avgTokensPerChar);
-      const trimmedMarkdown =
-        markdown.length > maxChars
-          ? markdown.slice(0, maxChars) + "\n[Content truncated due to length]"
-          : markdown;
-      if (ctx.debugDir) {
-        fs.writeFileSync(
-          `${ctx.debugDir}/extract-markdown-content.md`,
-          trimmedMarkdown
+      const includeScreenshot = Boolean(screenshotData && supportsMultimodal);
+
+      const markdownTokenBudget = computeMarkdownTokenBudget({
+        tokenLimit: normalizedTokenLimit,
+        objective,
+        hasScreenshot: includeScreenshot,
+      });
+      const trimmedMarkdown = trimMarkdownToTokenLimit(
+        markdown,
+        markdownTokenBudget
+      );
+      if (debugDir) {
+        writeDebugFileSafe(
+          `${debugDir}/extract-markdown-content.md`,
+          trimmedMarkdown,
+          ctx.debug
         );
       }
 
+      const textPrompt = includeScreenshot
+        ? `Extract the following information from the page according to this objective: "${objective}"\n\nPage content:\n${trimmedMarkdown}\nHere is a screenshot of the page:\n`
+        : `Extract the following information from the page according to this objective: "${objective}"\n\nPage content:\n${trimmedMarkdown}\nNo screenshot was available. Use the page content to extract the answer.`;
+      const contentParts: HyperAgentContentPart[] = [
+        {
+          type: "text",
+          text: textPrompt,
+        },
+      ];
+      if (includeScreenshot && screenshotData) {
+        contentParts.push({
+          type: "image",
+          url: `data:image/png;base64,${screenshotData}`,
+          mimeType: "image/png",
+        });
+      }
+
       const response = await ctx.llm.invoke([
         {
           role: "user",
-          content: [
-            {
-              type: "text",
-              text: `Extract the following information from the page according to this objective: "${objective}"\n\nPage content:\n${trimmedMarkdown}\nHere is a screenshot of the page:\n`,
-            },
-            {
-              type: "image",
-              url: `data:image/png;base64,${screenshot.data}`,
-              mimeType: "image/png",
-            },
-          ],
+          content: contentParts,
         },
       ]);
-      // Handle both string and HyperAgentContentPart[] responses
-      let extractedContent = "";
-      if (typeof response.content === "string") {
-        extractedContent = response.content;
-      } else if (Array.isArray(response.content)) {
-        // Extract text from content parts
-        extractedContent = response.content
-          .filter((part) => part.type === "text")
-          .map((part) => part.text)
-          .join("");
-      }
+      const extractedContent = extractTextResponse(
+        safeReadRecordField(response, "content")
+      );
 
-      if (extractedContent.length === 0) {
+      if (extractedContent.trim().length === 0) {
         return {
           success: false,
           message: `No content extracted from page.`,
@@ -97,7 +386,7 @@ export const ExtractActionDefinition: AgentActionDefinition = {
     } catch (error) {
       return {
         success: false,
-        message: `Failed to extract content: ${error}`,
+        message: `Failed to extract content: ${formatExtractDiagnostic(error)}`,
       };
     }
   },
diff --git a/src/agent/actions/go-to-url.ts b/src/agent/actions/go-to-url.ts
index ed6f6008..84db9706 100644
--- a/src/agent/actions/go-to-url.ts
+++ b/src/agent/actions/go-to-url.ts
@@ -1,5 +1,11 @@
 import { z } from "zod";
 import { ActionContext, AgentActionDefinition } from "@/types";
+import {
+  buildActionFailureMessage,
+  getPageMethod,
+  invalidateDomCacheSafely,
+  normalizeActionText,
+} from "./shared/action-runtime";
 
 export const GoToUrlAction = z
   .object({
@@ -13,9 +19,32 @@ export const GoToURLActionDefinition: AgentActionDefinition = {
   type: "goToUrl" as const,
   actionParams: GoToUrlAction,
   run: async (ctx: ActionContext, action: GoToUrlActionType) => {
-    const { url } = action;
-    await ctx.page.goto(url);
-    return { success: true, message: `Navigated to ${url}` };
+    const url = normalizeActionText(action?.url, "", 4_000);
+    if (url.length === 0) {
+      return {
+        success: false,
+        message: "Failed to navigate: URL must be a non-empty string.",
+      };
+    }
+
+    const goto = getPageMethod(ctx, "goto");
+    if (!goto) {
+      return {
+        success: false,
+        message: "Failed to navigate: page.goto is unavailable.",
+      };
+    }
+
+    try {
+      await goto(url);
+      invalidateDomCacheSafely(ctx);
+      return { success: true, message: `Navigated to ${url}` };
+    } catch (error) {
+      return {
+        success: false,
+        message: buildActionFailureMessage("navigate", error),
+      };
+    }
   },
   pprintAction: function(params: GoToUrlActionType): string {
     return `Navigate to URL: ${params.url}`;
diff --git a/src/agent/actions/navigation-actions.test.ts b/src/agent/actions/navigation-actions.test.ts
new file mode 100644
index 00000000..de7b1aa5
--- /dev/null
+++ b/src/agent/actions/navigation-actions.test.ts
@@ -0,0 +1,199 @@
+import type { Page } from "playwright-core";
+import type { ActionContext } from "@/types";
+import { GoToURLActionDefinition } from "@/agent/actions/go-to-url";
+import { WaitActionDefinition } from "@/agent/actions/wait";
+import { RefreshPageActionDefinition } from "@/agent/actions/refresh-page";
+import { ScrollActionDefinition } from "@/agent/actions/scroll";
+import { PageBackActionDefinition } from "@/agent/actions/page-back";
+import { PageForwardActionDefinition } from "@/agent/actions/page-forward";
+
+jest.mock("@/utils/waitForSettledDOM", () => ({
+  waitForSettledDOM: jest.fn(),
+}));
+
+const { waitForSettledDOM } = jest.requireMock("@/utils/waitForSettledDOM") as {
+  waitForSettledDOM: jest.Mock;
+};
+
+function createContext(overrides?: Partial<ActionContext>): ActionContext {
+  const page = {
+    goto: jest.fn().mockResolvedValue(undefined),
+    reload: jest.fn().mockResolvedValue(undefined),
+    evaluate: jest.fn().mockResolvedValue(undefined),
+    goBack: jest.fn().mockResolvedValue({}),
+    goForward: jest.fn().mockResolvedValue({}),
+  } as unknown as Page;
+
+  return {
+    page,
+    domState: {
+      elements: new Map(),
+      domState: "",
+      xpathMap: {},
+      backendNodeMap: {},
+    },
+    llm: {
+      invoke: async () => ({ role: "assistant", content: "ok" }),
+      invokeStructured: async () => ({ rawText: "{}", parsed: null }),
+      getProviderId: () => "mock",
+      getModelId: () => "mock-model",
+      getCapabilities: () => ({
+        multimodal: false,
+        toolCalling: true,
+        jsonMode: true,
+      }),
+    },
+    tokenLimit: 10000,
+    variables: [],
+    invalidateDomCache: jest.fn(),
+    ...overrides,
+  };
+}
+
+describe("navigation and wait actions", () => {
+  beforeEach(() => {
+    jest.clearAllMocks();
+    waitForSettledDOM.mockResolvedValue(undefined);
+  });
+
+  afterEach(() => {
+    jest.useRealTimers();
+  });
+
+  it("navigates to URL and invalidates DOM cache", async () => {
+    const ctx = createContext();
+
+    const result = await GoToURLActionDefinition.run(ctx, {
+      url: "  https://example.com/app  ",
+    });
+
+    expect(result.success).toBe(true);
+    expect((ctx.page.goto as jest.Mock)).toHaveBeenCalledWith(
+      "https://example.com/app"
+    );
+    expect(ctx.invalidateDomCache).toHaveBeenCalledTimes(1);
+  });
+
+  it("returns failure when page.goto is unavailable", async () => {
+    const ctx = createContext({
+      page: {
+        goto: undefined,
+      } as unknown as Page,
+    });
+
+    const result = await GoToURLActionDefinition.run(ctx, {
+      url: "https://example.com",
+    });
+
+    expect(result.success).toBe(false);
+    expect(result.message).toContain("page.goto is unavailable");
+  });
+
+  it("waits for settled DOM and preserves normalized reason", async () => {
+    jest.useFakeTimers();
+    const ctx = createContext();
+
+    const runPromise = WaitActionDefinition.run(ctx, {
+      reason: "  waiting for content   to appear ",
+    });
+
+    await jest.advanceTimersByTimeAsync(1_000);
+    const result = await runPromise;
+
+    expect(waitForSettledDOM).toHaveBeenCalledWith(
+      ctx.page,
+      undefined,
+      expect.objectContaining({
+        filterAdTrackingFrames: undefined,
+      })
+    );
+    expect(result.success).toBe(true);
+    expect(result.message).toContain("waiting for content to appear");
+    expect(ctx.invalidateDomCache).toHaveBeenCalledTimes(1);
+  });
+
+  it("forwards frame-filter option to wait action settle helper", async () => {
+    const ctx = createContext({
+      filterAdTrackingFrames: false,
+    });
+
+    await WaitActionDefinition.run(ctx, {
+      reason: "checking embedded ad iframe",
+    });
+
+    expect(waitForSettledDOM).toHaveBeenCalledWith(
+      ctx.page,
+      undefined,
+      expect.objectContaining({
+        filterAdTrackingFrames: false,
+      })
+    );
+  });
+
+  it("returns failure when waitForSettledDOM fails", async () => {
+    waitForSettledDOM.mockRejectedValue(new Error("settle failed"));
+    const ctx = createContext();
+
+    const result = await WaitActionDefinition.run(ctx, {
+      reason: "loading",
+    });
+
+    expect(result.success).toBe(false);
+    expect(result.message).toContain("settle failed");
+  });
+
+  it("refreshes page and reports unavailable reload method", async () => {
+    const okCtx = createContext();
+    const okResult = await RefreshPageActionDefinition.run(okCtx, {});
+    expect(okResult.success).toBe(true);
+    expect(okResult.message).toContain("Successfully refreshed the page");
+
+    const badCtx = createContext({
+      page: { reload: null } as unknown as Page,
+    });
+    const badResult = await RefreshPageActionDefinition.run(badCtx, {});
+    expect(badResult.success).toBe(false);
+    expect(badResult.message).toContain("page.reload is unavailable");
+  });
+
+  it("handles history navigation null responses gracefully", async () => {
+    const backCtx = createContext({
+      page: {
+        goBack: jest.fn().mockResolvedValue(null),
+      } as unknown as Page,
+    });
+    const backResult = await PageBackActionDefinition.run(backCtx, {});
+    expect(backResult.success).toBe(true);
+    expect(backResult.message).toContain("No previous page in browser history");
+
+    const forwardCtx = createContext({
+      page: {
+        goForward: jest.fn().mockResolvedValue(null),
+      } as unknown as Page,
+    });
+    const forwardResult = await PageForwardActionDefinition.run(forwardCtx, {});
+    expect(forwardResult.success).toBe(true);
+    expect(forwardResult.message).toContain("No next page in browser history");
+  });
+
+  it("returns failure for unsupported scroll directions and evaluate errors", async () => {
+    const unsupportedCtx = createContext();
+    const unsupported = await ScrollActionDefinition.run(
+      unsupportedCtx,
+      { direction: "diagonal" as unknown as "up" }
+    );
+    expect(unsupported.success).toBe(false);
+    expect(unsupported.message).toContain("unsupported direction");
+
+    const failingCtx = createContext({
+      page: {
+        evaluate: jest.fn().mockRejectedValue(new Error("scroll failed")),
+      } as unknown as Page,
+    });
+    const failing = await ScrollActionDefinition.run(failingCtx, {
+      direction: "down",
+    });
+    expect(failing.success).toBe(false);
+    expect(failing.message).toContain("scroll failed");
+  });
+});
diff --git a/src/agent/actions/page-back.ts b/src/agent/actions/page-back.ts
index ba6f65f7..b7e8d458 100644
--- a/src/agent/actions/page-back.ts
+++ b/src/agent/actions/page-back.ts
@@ -1,5 +1,10 @@
 import { z } from "zod";
 import { ActionContext, AgentActionDefinition } from "@/types";
+import {
+  buildActionFailureMessage,
+  getPageMethod,
+  invalidateDomCacheSafely,
+} from "./shared/action-runtime";
 
 export const PageBackAction = z
   .object({})
@@ -11,8 +16,29 @@ export const PageBackActionDefinition: AgentActionDefinition = {
   type: "pageBack" as const,
   actionParams: PageBackAction,
   run: async (ctx: ActionContext) => {
-    await ctx.page.goBack();
-    return { success: true, message: "Navigated back to the previous page" };
+    const goBack = getPageMethod(ctx, "goBack");
+    if (!goBack) {
+      return {
+        success: false,
+        message: "Failed to navigate back: page.goBack is unavailable.",
+      };
+    }
+    try {
+      const response = await goBack();
+      invalidateDomCacheSafely(ctx);
+      if (!response) {
+        return {
+          success: true,
+          message: "No previous page in browser history.",
+        };
+      }
+      return { success: true, message: "Navigated back to the previous page" };
+    } catch (error) {
+      return {
+        success: false,
+        message: buildActionFailureMessage("navigate back", error),
+      };
+    }
   },
   pprintAction: function(): string {
     return "Navigate back to previous page";
diff --git a/src/agent/actions/page-forward.ts b/src/agent/actions/page-forward.ts
index 86da8413..0c28681d 100644
--- a/src/agent/actions/page-forward.ts
+++ b/src/agent/actions/page-forward.ts
@@ -1,5 +1,10 @@
 import { z } from "zod";
 import { ActionContext, AgentActionDefinition } from "@/types";
+import {
+  buildActionFailureMessage,
+  getPageMethod,
+  invalidateDomCacheSafely,
+} from "./shared/action-runtime";
 
 export const PageForwardAction = z
   .object({})
@@ -11,8 +16,29 @@ export const PageForwardActionDefinition: AgentActionDefinition = {
   type: "pageForward" as const,
   actionParams: PageForwardAction,
   run: async (ctx: ActionContext) => {
-    await ctx.page.goForward();
-    return { success: true, message: "Navigated forward to the next page" };
+    const goForward = getPageMethod(ctx, "goForward");
+    if (!goForward) {
+      return {
+        success: false,
+        message: "Failed to navigate forward: page.goForward is unavailable.",
+      };
+    }
+    try {
+      const response = await goForward();
+      invalidateDomCacheSafely(ctx);
+      if (!response) {
+        return {
+          success: true,
+          message: "No next page in browser history.",
+        };
+      }
+      return { success: true, message: "Navigated forward to the next page" };
+    } catch (error) {
+      return {
+        success: false,
+        message: buildActionFailureMessage("navigate forward", error),
+      };
+    }
   },
   pprintAction: function(): string {
     return "Navigate forward to next page";
diff --git a/src/agent/actions/pdf.test.ts b/src/agent/actions/pdf.test.ts
new file mode 100644
index 00000000..086af521
--- /dev/null
+++ b/src/agent/actions/pdf.test.ts
@@ -0,0 +1,251 @@
+import { PDFActionDefinition } from "@/agent/actions/pdf";
+import type { ActionContext } from "@/types";
+import type { Page } from "playwright-core";
+
+const generateContentMock = jest.fn();
+const googleGenAIConstructorMock = jest.fn().mockImplementation(() => ({
+  models: {
+    generateContent: generateContentMock,
+  },
+}));
+
+jest.mock("@google/genai", () => ({
+  GoogleGenAI: function (...args: unknown[]) {
+    return googleGenAIConstructorMock(...args);
+  },
+}));
+
+function createResponse(options?: {
+  ok?: boolean;
+  contentType?: string;
+  body?: Buffer;
+}) {
+  return {
+    ok: jest.fn(() => options?.ok ?? true),
+    headers: jest.fn(() => ({
+      "content-type": options?.contentType ?? "application/pdf",
+    })),
+    body: jest.fn(async () => options?.body ?? Buffer.from("pdf")),
+  };
+}
+
+function createContext(overrides?: Partial<ActionContext>): ActionContext {
+  return {
+    page: {
+      request: {
+        get: jest.fn(async () => createResponse()),
+      },
+      waitForResponse: jest.fn(async () => createResponse()),
+      goto: jest.fn(async () => undefined),
+    } as unknown as Page,
+    domState: {
+      elements: new Map(),
+      domState: "",
+      xpathMap: {},
+      backendNodeMap: {},
+    },
+    llm: {
+      invoke: async () => ({ role: "assistant", content: "ok" }),
+      invokeStructured: async () => ({ rawText: "{}", parsed: null }),
+      getProviderId: () => "mock",
+      getModelId: () => "mock-model",
+      getCapabilities: () => ({
+        multimodal: false,
+        toolCalling: true,
+        jsonMode: true,
+      }),
+    },
+    tokenLimit: 1000,
+    variables: [],
+    invalidateDomCache: jest.fn(),
+    ...overrides,
+  } as ActionContext;
+}
+
+describe("PDFActionDefinition", () => {
+  const originalGeminiApiKey = process.env.GEMINI_API_KEY;
+
+  beforeEach(() => {
+    jest.clearAllMocks();
+    process.env.GEMINI_API_KEY = "test-gemini-key";
+    generateContentMock.mockResolvedValue({ text: "PDF summary" });
+  });
+
+  afterAll(() => {
+    process.env.GEMINI_API_KEY = originalGeminiApiKey;
+  });
+
+  it("returns failure when GEMINI_API_KEY is missing", async () => {
+    delete process.env.GEMINI_API_KEY;
+    const ctx = createContext();
+
+    const result = await PDFActionDefinition.run(ctx, {
+      pdfUrl: "https://example.com/file.pdf",
+      prompt: "Summarize",
+    });
+
+    expect(result.success).toBe(false);
+    expect(result.message).toContain("GEMINI_API_KEY is not configured");
+  });
+
+  it("rejects unsupported URL protocols", async () => {
+    const ctx = createContext();
+
+    const result = await PDFActionDefinition.run(ctx, {
+      pdfUrl: "file:///tmp/file.pdf",
+      prompt: "Summarize",
+    });
+
+    expect(result.success).toBe(false);
+    expect(result.message).toContain('unsupported URL protocol "file:"');
+  });
+
+  it("uses direct PDF request when content-type is PDF", async () => {
+    const requestGet = jest.fn(async () =>
+      createResponse({
+        ok: true,
+        contentType: "application/pdf",
+        body: Buffer.from("direct-pdf"),
+      })
+    );
+    const ctx = createContext({
+      page: {
+        request: { get: requestGet },
+        waitForResponse: jest.fn(),
+        goto: jest.fn(),
+      } as unknown as Page,
+    });
+
+    const result = await PDFActionDefinition.run(ctx, {
+      pdfUrl: "https://example.com/file.pdf",
+      prompt: "Summarize",
+    });
+
+    expect(result.success).toBe(true);
+    expect(result.message).toBe("PDF summary");
+    expect(requestGet).toHaveBeenCalledWith("https://example.com/file.pdf");
+    expect(googleGenAIConstructorMock).toHaveBeenCalledWith({
+      apiKey: "test-gemini-key",
+    });
+    expect(generateContentMock).toHaveBeenCalledWith(
+      expect.objectContaining({
+        contents: expect.arrayContaining([
+          expect.objectContaining({ text: "Summarize" }),
+          expect.objectContaining({
+            inlineData: expect.objectContaining({
+              mimeType: "application/pdf",
+            }),
+          }),
+        ]),
+      })
+    );
+  });
+
+  it("falls back to waitForResponse/goto for non-direct PDF content", async () => {
+    const requestGet = jest.fn(async () =>
+      createResponse({
+        ok: true,
+        contentType: "text/html",
+      })
+    );
+    const waitForResponse = jest.fn(async () =>
+      createResponse({
+        ok: true,
+        contentType: "application/pdf",
+        body: Buffer.from("fallback-pdf"),
+      })
+    );
+    const goto = jest.fn(async () => undefined);
+    const ctx = createContext({
+      page: {
+        request: { get: requestGet },
+        waitForResponse,
+        goto,
+      } as unknown as Page,
+    });
+
+    const result = await PDFActionDefinition.run(ctx, {
+      pdfUrl: "https://example.com/file.pdf",
+      prompt: "Summarize",
+    });
+
+    expect(result.success).toBe(true);
+    expect(waitForResponse).toHaveBeenCalledTimes(1);
+    expect(goto).toHaveBeenCalledWith("https://example.com/file.pdf", {
+      waitUntil: "networkidle",
+    });
+  });
+
+  it("fails when page.request.get is unavailable", async () => {
+    const ctx = createContext({
+      page: {} as unknown as Page,
+    });
+
+    const result = await PDFActionDefinition.run(ctx, {
+      pdfUrl: "https://example.com/file.pdf",
+      prompt: "Summarize",
+    });
+
+    expect(result.success).toBe(false);
+    expect(result.message).toContain("page.request.get is unavailable");
+  });
+
+  it("rejects oversized PDF payloads", async () => {
+    const requestGet = jest.fn(async () =>
+      createResponse({
+        ok: true,
+        contentType: "application/pdf",
+        body: Buffer.alloc(21 * 1024 * 1024, 1),
+      })
+    );
+    const ctx = createContext({
+      page: {
+        request: { get: requestGet },
+      } as unknown as Page,
+    });
+
+    const result = await PDFActionDefinition.run(ctx, {
+      pdfUrl: "https://example.com/file.pdf",
+      prompt: "Summarize",
+    });
+
+    expect(result.success).toBe(false);
+    expect(result.message).toContain("file exceeds");
+  });
+
+  it("returns readable failure when Gemini generation throws", async () => {
+    generateContentMock.mockRejectedValue(new Error("gemini unavailable"));
+    const ctx = createContext();
+
+    const result = await PDFActionDefinition.run(ctx, {
+      pdfUrl: "https://example.com/file.pdf",
+      prompt: "Summarize",
+    });
+
+    expect(result.success).toBe(false);
+    expect(result.message).toContain("gemini unavailable");
+  });
+
+  it("sanitizes and truncates oversized PDF download failures", async () => {
+    const requestGet = jest
+      .fn()
+      .mockRejectedValue(new Error(`download\u0000\n${"x".repeat(10_000)}`));
+    const ctx = createContext({
+      page: {
+        request: { get: requestGet },
+      } as unknown as Page,
+    });
+
+    const result = await PDFActionDefinition.run(ctx, {
+      pdfUrl: "https://example.com/file.pdf",
+      prompt: "Summarize",
+    });
+
+    expect(result.success).toBe(false);
+    expect(result.message).toContain("Failed to download PDF:");
+    expect(result.message).toContain("…");
+    expect(result.message).not.toContain("\u0000");
+    expect(result.message).not.toContain("\n");
+    expect(result.message.length).toBeLessThan(750);
+  });
+});
diff --git a/src/agent/actions/pdf.ts b/src/agent/actions/pdf.ts
index 8d40e626..607c6dd1 100644
--- a/src/agent/actions/pdf.ts
+++ b/src/agent/actions/pdf.ts
@@ -2,9 +2,81 @@ import { z } from "zod";
 import { ActionContext, AgentActionDefinition } from "@/types";
 import { config } from "dotenv";
 import { GoogleGenAI } from "@google/genai";
+import {
+  buildActionFailureMessage,
+  getPageMethod,
+  normalizeActionText,
+} from "./shared/action-runtime";
 
 config();
 
+const MAX_PDF_URL_CHARS = 4_000;
+const MAX_PDF_PROMPT_CHARS = 8_000;
+const MAX_PDF_FILE_BYTES = 20 * 1024 * 1024;
+
+function isPdfContentType(value: unknown): boolean {
+  return typeof value === "string" && value.toLowerCase().includes("pdf");
+}
+
+function safeReadRecordField(value: unknown, key: string): unknown {
+  if (!value || (typeof value !== "object" && typeof value !== "function")) {
+    return undefined;
+  }
+  try {
+    return (value as Record<string, unknown>)[key];
+  } catch {
+    return undefined;
+  }
+}
+
+function safeReadContentTypeHeader(response: unknown): string {
+  if (!response || (typeof response !== "object" && typeof response !== "function")) {
+    return "";
+  }
+  const headers = (response as { headers?: () => Record<string, string> }).headers;
+  if (typeof headers !== "function") {
+    return "";
+  }
+  try {
+    const rawHeaders = headers();
+    return typeof rawHeaders?.["content-type"] === "string"
+      ? rawHeaders["content-type"]
+      : "";
+  } catch {
+    return "";
+  }
+}
+
+function normalizePdfUrl(value: unknown): string {
+  return normalizeActionText(value, "", MAX_PDF_URL_CHARS);
+}
+
+function normalizePdfPrompt(value: unknown): string {
+  return normalizeActionText(value, "", MAX_PDF_PROMPT_CHARS);
+}
+
+async function readResponseBodyAsBuffer(response: unknown): Promise<Buffer | null> {
+  if (!response || (typeof response !== "object" && typeof response !== "function")) {
+    return null;
+  }
+  const body = (response as { body?: () => Promise<Buffer | Uint8Array | ArrayBuffer> })
+    .body;
+  if (typeof body !== "function") {
+    return null;
+  }
+  const payload = await body.call(response);
+  if (payload instanceof Buffer) {
+    return payload;
+  }
+  if (payload instanceof Uint8Array) {
+    return Buffer.from(payload);
+  }
+  if (payload instanceof ArrayBuffer) {
+    return Buffer.from(payload);
+  }
+  return null;
+}
+
 export const PDFAction = z
   .object({
     pdfUrl: z.string().describe("The URL of the PDF to analyze."),
@@ -18,33 +90,102 @@ export const PDFActionDefinition: AgentActionDefinition = {
   type: "analyzePdf" as const,
   actionParams: PDFAction,
   run: async (ctx: ActionContext, action: PDFActionType) => {
-    const goog = new GoogleGenAI({ apiKey: process.env.GEMINI_API_KEY! });
-    const { pdfUrl, prompt } = action;
+    const apiKey = normalizeActionText(process.env.GEMINI_API_KEY, "", 256);
+    if (apiKey.length === 0) {
+      return {
+        success: false,
+        message: "Failed to analyze PDF: GEMINI_API_KEY is not configured.",
+      };
+    }
+
+    const pdfUrl = normalizePdfUrl(action?.pdfUrl);
+    const prompt = normalizePdfPrompt(action?.prompt);
+    if (pdfUrl.length === 0) {
+      return {
+        success: false,
+        message: "Failed to analyze PDF: pdfUrl must be a non-empty string.",
+      };
+    }
+    if (prompt.length === 0) {
+      return {
+        success: false,
+        message: "Failed to analyze PDF: prompt must be a non-empty string.",
+      };
+    }
+
+    let parsedUrl: URL;
+    try {
+      parsedUrl = new URL(pdfUrl);
+    } catch {
+      return {
+        success: false,
+        message: "Failed to analyze PDF: pdfUrl must be a valid URL.",
+      };
+    }
+    if (!["http:", "https:"].includes(parsedUrl.protocol)) {
+      return {
+        success: false,
+        message: `Failed to analyze PDF: unsupported URL protocol "${parsedUrl.protocol}".`,
+      };
+    }
+
+    const request = (ctx.page as unknown as { request?: { get?: (url: string) => Promise<unknown> } })
+      .request;
+    if (!request || typeof request.get !== "function") {
+      return {
+        success: false,
+        message: "Failed to analyze PDF: page.request.get is unavailable.",
+      };
+    }
+
+    const goog = new GoogleGenAI({ apiKey });
     let pdfBuffer: Buffer | null = null;
     try {
       // Try direct request first (works for direct PDF links)
-      const response = await ctx.page.request.get(pdfUrl);
-      if (
-        response.ok() &&
-        response.headers()["content-type"]?.includes("pdf")
-      ) {
-        pdfBuffer = Buffer.from(await response.body());
+      const response = await request.get(pdfUrl);
+      const contentType = safeReadContentTypeHeader(response);
+      const isOk =
+        typeof (response as { ok?: () => boolean }).ok === "function"
+          ? (response as { ok: () => boolean }).ok()
+          : false;
+      if (isOk && isPdfContentType(contentType)) {
+        pdfBuffer = await readResponseBodyAsBuffer(response);
       } else {
         // Fallback: navigate and intercept response
-
+        const waitForResponse = getPageMethod(ctx, "waitForResponse");
+        const goto = getPageMethod(ctx, "goto");
+        if (!waitForResponse || !goto) {
+          return {
+            success: false,
+            message:
+              "Failed to analyze PDF: page.waitForResponse/page.goto are unavailable for fallback download.",
+          };
+        }
         const [resp] = await Promise.all([
-          ctx.page.waitForResponse(
-            (r) =>
-              r.url() === pdfUrl && r.headers()["content-type"]?.includes("pdf")
+          waitForResponse(
+            (r: unknown) => {
+              const urlFn = safeReadRecordField(r, "url");
+              if (typeof urlFn !== "function") {
+                return false;
+              }
+              try {
+                return (
+                  (urlFn as () => string)() === pdfUrl &&
+                  isPdfContentType(safeReadContentTypeHeader(r))
+                );
+              } catch {
+                return false;
+              }
+            }
           ),
-          ctx.page.goto(pdfUrl, { waitUntil: "networkidle" }),
+          goto(pdfUrl, { waitUntil: "networkidle" }),
         ]);
-        pdfBuffer = Buffer.from(await resp.body());
+        pdfBuffer = await readResponseBodyAsBuffer(resp);
       }
     } catch (err) {
       return {
         success: false,
-        message: `Failed to download PDF: ${err}`,
+        message: buildActionFailureMessage("download PDF", err),
       };
     }
     if (!pdfBuffer) {
@@ -53,21 +194,40 @@ export const PDFActionDefinition: AgentActionDefinition = {
         message: "Could not retrieve PDF file.",
       };
     }
-    const geminiResponse = await goog.models.generateContent({
-      model: "gemini-2.5-pro-preview-03-25",
-      contents: [
-        { text: prompt },
-        {
-          inlineData: {
-            mimeType: "application/pdf",
-            data: pdfBuffer.toString("base64"),
+    if (pdfBuffer.length > MAX_PDF_FILE_BYTES) {
+      return {
+        success: false,
+        message: `Failed to analyze PDF: file exceeds ${MAX_PDF_FILE_BYTES} bytes.`,
+      };
+    }
+
+    let geminiResponse: unknown;
+    try {
+      geminiResponse = await goog.models.generateContent({
+        model: "gemini-2.5-pro-preview-03-25",
+        contents: [
+          { text: prompt },
+          {
+            inlineData: {
+              mimeType: "application/pdf",
+              data: pdfBuffer.toString("base64"),
+            },
           },
-        },
-      ],
-    });
+        ],
+      });
+    } catch (error) {
+      return {
+        success: false,
+        message: buildActionFailureMessage("analyze PDF with Gemini", error),
+      };
+    }
+
+    const text = (geminiResponse as { text?: unknown })?.text;
     return {
       success: true,
-      message: geminiResponse.text || "No response text returned.",
+      message: typeof text === "string" && text.trim().length > 0
+        ? text.trim()
+        : "No response text returned.",
     };
   },
   pprintAction: function (params: PDFActionType): string {
diff --git a/src/agent/actions/refresh-page.ts b/src/agent/actions/refresh-page.ts
index ce87e580..d0d8ef3a 100644
--- a/src/agent/actions/refresh-page.ts
+++ b/src/agent/actions/refresh-page.ts
@@ -1,5 +1,10 @@
 import { z } from "zod";
 import { ActionContext, AgentActionDefinition } from "@/types";
+import {
+  buildActionFailureMessage,
+  getPageMethod,
+  invalidateDomCacheSafely,
+} from "./shared/action-runtime";
 
 export const RefreshPageAction = z
   .object({})
@@ -13,8 +18,23 @@ export const RefreshPageActionDefinition: AgentActionDefinition = {
   type: "refreshPage" as const,
   actionParams: RefreshPageAction,
   run: async (ctx: ActionContext) => {
-    await ctx.page.reload();
-    return { success: true, message: "Succesfully refreshed a page." };
+    const reload = getPageMethod(ctx, "reload");
+    if (!reload) {
+      return {
+        success: false,
+        message: "Failed to refresh page: page.reload is unavailable.",
+      };
+    }
+    try {
+      await reload();
+      invalidateDomCacheSafely(ctx);
+      return { success: true, message: "Successfully refreshed the page." };
+    } catch (error) {
+      return {
+        success: false,
+        message: buildActionFailureMessage("refresh page", error),
+      };
+    }
   },
   pprintAction: function(): string {
     return "Refresh current page";
diff --git a/src/agent/actions/scroll.ts b/src/agent/actions/scroll.ts
index b3064993..4f58d7e6 100644
--- a/src/agent/actions/scroll.ts
+++ b/src/agent/actions/scroll.ts
@@ -1,5 +1,11 @@
 import { z } from "zod";
 import { ActionContext, AgentActionDefinition } from "@/types";
+import {
+  buildActionFailureMessage,
+  getPageMethod,
+  invalidateDomCacheSafely,
+  normalizeActionText,
+} from "./shared/action-runtime";
 
 export const ScrollAction = z
   .object({
@@ -15,22 +21,43 @@ export const ScrollActionDefinition: AgentActionDefinition = {
   type: "scroll" as const,
   actionParams: ScrollAction,
   run: async (ctx: ActionContext, action: ScrollActionType) => {
-    const { direction } = action;
-    switch (direction) {
-      case "up":
-        await ctx.page.evaluate(() => window.scrollBy(0, -window.innerHeight));
-        break;
-      case "down":
-        await ctx.page.evaluate(() => window.scrollBy(0, window.innerHeight));
-        break;
-      case "left":
-        await ctx.page.evaluate(() => window.scrollBy(-window.innerWidth, 0));
-        break;
-      case "right":
-        await ctx.page.evaluate(() => window.scrollBy(window.innerWidth, 0));
-        break;
+    const direction = normalizeActionText(action?.direction, "down", 16).toLowerCase();
+    const evaluate = getPageMethod(ctx, "evaluate");
+    if (!evaluate) {
+      return {
+        success: false,
+        message: "Failed to scroll: page.evaluate is unavailable.",
+      };
+    }
+
+    try {
+      switch (direction) {
+        case "up":
+          await evaluate(() => window.scrollBy(0, -window.innerHeight));
+          break;
+        case "down":
+          await evaluate(() => window.scrollBy(0, window.innerHeight));
+          break;
+        case "left":
+          await evaluate(() => window.scrollBy(-window.innerWidth, 0));
+          break;
+        case "right":
+          await evaluate(() => window.scrollBy(window.innerWidth, 0));
+          break;
+        default:
+          return {
+            success: false,
+            message: `Failed to scroll: unsupported direction "${direction}".`,
+          };
+      }
+      invalidateDomCacheSafely(ctx);
+      return { success: true, message: `Scrolled ${direction}` };
+    } catch (error) {
+      return {
+        success: false,
+        message: buildActionFailureMessage("scroll page", error),
+      };
     }
-    return { success: true, message: `Scrolled ${direction}` };
   },
   pprintAction: function(params: ScrollActionType): string {
     return `Scroll ${params.direction}`;
diff --git a/src/agent/actions/shared/action-runtime.test.ts b/src/agent/actions/shared/action-runtime.test.ts
new file mode 100644
index 00000000..227c760a
--- /dev/null
+++ b/src/agent/actions/shared/action-runtime.test.ts
@@ -0,0 +1,51 @@
+import {
+  buildActionFailureMessage,
+  getPageMethod,
+  normalizeActionText,
+} from "@/agent/actions/shared/action-runtime";
+
+describe("action-runtime helpers", () => {
+  it("normalizes control characters in action text inputs", () => {
+    const normalized = normalizeActionText("hello\u0000\nworld", "fallback", 100);
+    expect(normalized).toBe("hello world");
+  });
+
+  it("truncates oversized normalized action text inputs", () => {
+    const normalized = normalizeActionText(`x${"y".repeat(1_000)}`, "fallback", 20);
+    expect(normalized).toContain("…");
+    expect(normalized.length).toBe(21);
+  });
+
+  it("formats action failure messages with sanitized diagnostics", () => {
+    const message = buildActionFailureMessage(
+      "run\u0000 action",
+      new Error(`failed\n${"x".repeat(2_000)}`)
+    );
+
+    expect(message).toContain("Failed to run action:");
+    expect(message).toContain("…");
+    expect(message).not.toContain("\u0000");
+    expect(message).not.toContain("\n");
+  });
+
+  it("returns null when page method is unavailable", () => {
+    const method = getPageMethod({} as never, "goto");
+    expect(method).toBeNull();
+  });
+
+  it("returns bound page methods when available", async () => {
+    const page = {
+      callCount: 0,
+      goto(this: { callCount: number }, url: string): string {
+        this.callCount += 1;
+        return `navigated:${url}`;
+      },
+    };
+    const method = getPageMethod({ page } as never, "goto");
+    expect(typeof method).toBe("function");
+
+    const result = await method?.("https://example.com");
+    expect(result).toBe("navigated:https://example.com");
+    expect(page.callCount).toBe(1);
+  });
+});
diff --git a/src/agent/actions/shared/action-runtime.ts b/src/agent/actions/shared/action-runtime.ts
new file mode 100644
index 00000000..a7b7144b
--- /dev/null
+++ b/src/agent/actions/shared/action-runtime.ts
@@ -0,0 +1,96 @@
+import type { ActionContext } from "@/types";
+import { formatUnknownError } from "@/utils";
+
+const MAX_ACTION_TEXT_CHARS = 400;
+const MAX_ACTION_ERROR_CHARS = 600;
+
+function sanitizeActionRuntimeText(value: string): string {
+  if (value.length === 0) {
+    return value;
+  }
+  const withoutControlChars = Array.from(value, (char) => {
+    const code = char.charCodeAt(0);
+    return (code >= 0 && code < 32) || code === 127 ? " " : char;
+  }).join("");
+  return withoutControlChars.replace(/\s+/g, " ").trim();
+}
+
+function truncateText(value: string, maxChars: number): string {
+  if (value.length <= maxChars) {
+    return value;
+  }
+  return `${value.slice(0, maxChars)}…`;
+}
+
+export function normalizeActionText(
+  value: unknown,
+  fallback: string,
+  maxChars: number = MAX_ACTION_TEXT_CHARS
+): string {
+  const source =
+    typeof value === "string"
+      ? value
+      : value == null
+        ? fallback
+        : formatUnknownError(value);
+  const normalized = sanitizeActionRuntimeText(source);
+  if (normalized.length === 0) {
+    return fallback;
+  }
+  return truncateText(normalized, maxChars);
+}
+
+export function buildActionFailureMessage(
+  actionLabel: string,
+  error: unknown
+): string {
+  const normalizedLabel = normalizeActionText(actionLabel, "action");
+  const diagnostic = truncateText(
+    normalizeActionText(error, "unknown error", MAX_ACTION_ERROR_CHARS),
+    MAX_ACTION_ERROR_CHARS
+  );
+  return `Failed to ${normalizedLabel}: ${diagnostic}`;
+}
+
+export function safeReadContextField(
+  ctx: ActionContext,
+  key: string
+): unknown {
+  try {
+    return (ctx as unknown as Record<string, unknown>)[key];
+  } catch {
+    return undefined;
+  }
+}
+
+export function getPageMethod(
+  ctx: ActionContext,
+  methodName: string
+): ((...args: unknown[]) => unknown | Promise<unknown>) | null {
+  const page = safeReadContextField(ctx, "page");
+  if (!page || (typeof page !== "object" && typeof page !== "function")) {
+    return null;
+  }
+  let value: unknown;
+  try {
+    value = (page as Record<string, unknown>)[methodName];
+  } catch {
+    return null;
+  }
+  if (typeof value !== "function") {
+    return null;
+  }
+  return value.bind(page) as (...args: unknown[]) => unknown | Promise<unknown>;
+}
+
+export function invalidateDomCacheSafely(ctx: ActionContext): void {
+  const invalidateDomCache = safeReadContextField(ctx, "invalidateDomCache");
+  if (typeof invalidateDomCache !== "function") {
+    return;
+  }
+  try {
+    invalidateDomCache();
+  } catch {
+    // best effort only
+  }
+}
diff --git a/src/agent/actions/shared/perform-action.test.ts b/src/agent/actions/shared/perform-action.test.ts
new file mode 100644
index 00000000..d716e050
--- /dev/null
+++ b/src/agent/actions/shared/perform-action.test.ts
@@ -0,0 +1,285 @@
+import type { Page } from "playwright-core";
+import { performAction } from "@/agent/actions/shared/perform-action";
+import type { ActionContext } from "@/types";
+
+jest.mock("../../shared/element-locator", () => ({
+  getElementLocator: jest.fn(),
+}));
+
+jest.mock("../../shared/execute-playwright-method", () => ({
+  executePlaywrightMethod: jest.fn(),
+}));
+
+const { getElementLocator } = jest.requireMock(
+  "../../shared/element-locator"
+) as {
+  getElementLocator: jest.Mock;
+};
+const { executePlaywrightMethod } = jest.requireMock(
+  "../../shared/execute-playwright-method"
+) as {
+  executePlaywrightMethod: jest.Mock;
+};
+
+describe("performAction variable interpolation", () => {
+  const createContext = (overrides?: Partial<ActionContext>): ActionContext => ({
+    page: {} as Page,
+    domState: {
+      elements: new Map([
+        [
+          "0-1",
+          {
+            role: "textbox",
+          },
+        ],
+      ]),
+      domState: "",
+      xpathMap: { "0-1": "//input[1]" },
+      backendNodeMap: {},
+    },
+    llm: {
+      invoke: async () => ({ role: "assistant", content: "ok" }),
+      invokeStructured: async () => ({ rawText: "{}", parsed: null }),
+      getProviderId: () => "mock",
+      getModelId: () => "mock-model",
+      getCapabilities: () => ({
+        multimodal: false,
+        toolCalling: true,
+        jsonMode: true,
+      }),
+    },
+    tokenLimit: 10000,
+    variables: [],
+    cdpActions: false,
+    invalidateDomCache: jest.fn(),
+    ...overrides,
+  });
+
+  beforeEach(() => {
+    jest.clearAllMocks();
+    getElementLocator.mockResolvedValue({
+      locator: {},
+      xpath: "//input[1]",
+    });
+    executePlaywrightMethod.mockResolvedValue(undefined);
+  });
+
+  it("interpolates variables in instruction and method arguments", async () => {
+    const context = createContext({
+      variables: [
+        {
+          key: "email",
+          value: "person@example.com",
+          description: "Email address",
+        },
+      ],
+    });
+
+    const result = await performAction(context, {
+      elementId: "0-1",
+      method: "fill",
+      arguments: ["<<email>>"],
+      instruction: "Fill input with <<email>>",
+    });
+
+    expect(result.success).toBe(true);
+    expect(result.message).toContain("person@example.com");
+    expect(executePlaywrightMethod).toHaveBeenCalledWith(
+      "fill",
+      ["person@example.com"],
+      {},
+      expect.objectContaining({ clickTimeout: 3500 })
+    );
+  });
+
+  it("interpolates variables when token keys include surrounding whitespace", async () => {
+    const context = createContext({
+      variables: [
+        {
+          key: "email",
+          value: "person@example.com",
+          description: "Email address",
+        },
+      ],
+    });
+
+    const result = await performAction(context, {
+      elementId: "0-1",
+      method: "fill",
+      arguments: ["<< email >>"],
+      instruction: "Fill input with << email >>",
+    });
+
+    expect(result.success).toBe(true);
+    expect(result.message).toContain("person@example.com");
+    expect(executePlaywrightMethod).toHaveBeenCalledWith(
+      "fill",
+      ["person@example.com"],
+      {},
+      expect.objectContaining({ clickTimeout: 3500 })
+    );
+  });
+
+  it("formats non-Error failures from Playwright execution", async () => {
+    executePlaywrightMethod.mockRejectedValue({ reason: "playwright failed" });
+
+    const context = createContext();
+
+    const result = await performAction(context, {
+      elementId: "0-1",
+      method: "fill",
+      arguments: ["value"],
+      instruction: "Fill input",
+    });
+
+    expect(result.success).toBe(false);
+    expect(result.message).toContain('{"reason":"playwright failed"}');
+  });
+
+  it("sanitizes and truncates oversized Playwright failure diagnostics", async () => {
+    const hugeFailure = `playwright\u0000\n${"x".repeat(5_000)}`;
+    executePlaywrightMethod.mockRejectedValue(new Error(hugeFailure));
+
+    const context = createContext();
+
+    const result = await performAction(context, {
+      elementId: "0-1",
+      method: "fill",
+      arguments: ["value"],
+      instruction: "Fill input",
+    });
+
+    expect(result.success).toBe(false);
+    expect(result.message).not.toContain("\u0000");
+    expect(result.message).not.toContain("\n");
+    expect(result.message).toContain("[truncated");
+    expect(result.message.length).toBeLessThan(1_200);
+  });
+
+  it("defaults to empty method arguments when params.arguments is invalid", async () => {
+    const context = createContext();
+
+    const result = await performAction(context, {
+      elementId: "0-1",
+      method: "click",
+      arguments: "not-an-array" as unknown as string[],
+      instruction: "Click submit",
+    });
+
+    expect(result.success).toBe(true);
+    expect(executePlaywrightMethod).toHaveBeenCalledWith(
+      "click",
+      [],
+      {},
+      expect.objectContaining({ clickTimeout: 3500 })
+    );
+  });
+
+  it("handles unreadable variables without crashing interpolation", async () => {
+    const variable = {
+      description: "bad var",
+      get key(): string {
+        throw new Error("key trap");
+      },
+      get value(): string {
+        throw new Error("value trap");
+      },
+    };
+    const context = createContext({
+      variables: [variable as unknown as ActionContext["variables"][number]],
+    });
+
+    const result = await performAction(context, {
+      elementId: "0-1",
+      method: "fill",
+      arguments: ["<<email>>"],
+      instruction: "Fill input with <<email>>",
+    });
+
+    expect(result.success).toBe(true);
+    expect(executePlaywrightMethod).toHaveBeenCalledWith(
+      "fill",
+      ["<<email>>"],
+      {},
+      expect.objectContaining({ clickTimeout: 3500 })
+    );
+  });
+
+  it("returns readable failure when DOM elements map is unavailable", async () => {
+    const baseContext = createContext();
+    const context = createContext({
+      domState: {
+        ...baseContext.domState,
+        elements:
+          undefined as unknown as ActionContext["domState"]["elements"],
+      } as ActionContext["domState"],
+    });
+
+    const result = await performAction(context, {
+      elementId: "0-1",
+      method: "click",
+      arguments: [],
+      instruction: "Click submit",
+    });
+
+    expect(result.success).toBe(false);
+    expect(result.message).toContain("current DOM elements are unavailable");
+  });
+
+  it("sanitizes and truncates DOM lookup trap diagnostics", async () => {
+    const trappedElements = new Proxy(new Map(), {
+      get: (target, prop, receiver) => {
+        if (prop === "get") {
+          return () => {
+            throw new Error(`lookup\u0000\n${"x".repeat(10_000)}`);
+          };
+        }
+        return Reflect.get(target, prop, receiver);
+      },
+    }) as unknown as Map<string, unknown>;
+    const baseContext = createContext();
+    const context = createContext({
+      domState: {
+        ...baseContext.domState,
+        elements:
+          trappedElements as unknown as ActionContext["domState"]["elements"],
+      } as ActionContext["domState"],
+    });
+
+    const result = await performAction(context, {
+      elementId: "0-1",
+      method: "click",
+      arguments: [],
+      instruction: "Click submit",
+    });
+
+    expect(result.success).toBe(false);
+    expect(result.message).toContain("DOM element lookup failed");
+    expect(result.message).toContain("[truncated");
+    expect(result.message).not.toContain("\u0000");
+    expect(result.message).not.toContain("\n");
+    expect(result.message.length).toBeLessThan(700);
+  });
+
+  it("falls back to Playwright when CDP hooks are invalid", async () => {
+    const invalidCdp = {
+      client: {} as unknown,
+      resolveElement: "invalid",
+      dispatchCDPAction: "invalid",
+    } as unknown as NonNullable<ActionContext["cdp"]>;
+    const context = createContext({
+      cdpActions: true,
+      cdp: invalidCdp,
+    });
+
+    const result = await performAction(context, {
+      elementId: "0-1",
+      method: "click",
+      arguments: [],
+      instruction: "Click submit",
+    });
+
+    expect(result.success).toBe(true);
+    expect(executePlaywrightMethod).toHaveBeenCalledTimes(1);
+  });
+});
diff --git a/src/agent/actions/shared/perform-action.ts b/src/agent/actions/shared/perform-action.ts
index 91892308..60850f02 100644
--- a/src/agent/actions/shared/perform-action.ts
+++ b/src/agent/actions/shared/perform-action.ts
@@ -2,6 +2,7 @@ import { performance } from "perf_hooks";
 import { ActionContext, ActionOutput } from "@/types";
 import type { ResolvedCDPElement, CDPActionMethod } from "@/cdp";
 import { isEncodedId, type EncodedId } from "@/context-providers/a11y-dom/types";
+import { formatUnknownError } from "@/utils";
 import { getElementLocator } from "../../shared/element-locator";
 import { executePlaywrightMethod } from "../../shared/execute-playwright-method";
 
@@ -13,6 +14,122 @@ export interface PerformActionParams {
   confidence?: number;
 }
 
+const VARIABLE_TOKEN_PATTERN = /<<([^>]+)>>/g;
+const MAX_ACTION_ARGS = 50;
+const MAX_ACTION_ARG_CHARS = 20_000;
+const MAX_ACTION_METHOD_CHARS = 128;
+const MAX_ACTION_TEXT_CHARS = 1_000;
+const MAX_ACTION_DIAGNOSTIC_CHARS = 400;
+
+function sanitizeActionText(value: string): string {
+  if (value.length === 0) {
+    return value;
+  }
+  const withoutControlChars = Array.from(value, (char) => {
+    const code = char.charCodeAt(0);
+    return (code >= 0 && code < 32) || code === 127 ? " " : char;
+  }).join("");
+  return withoutControlChars.replace(/\s+/g, " ").trim();
+}
+
+function safeReadRecordField(
+  value: unknown,
+  key: string
+): unknown {
+  if (!value || (typeof value !== "object" && typeof value !== "function")) {
+    return undefined;
+  }
+  try {
+    return (value as Record<string, unknown>)[key];
+  } catch {
+    return undefined;
+  }
+}
+
+function normalizeTextInput(
+  value: unknown,
+  fallback: string,
+  maxChars: number
+): string {
+  const source =
+    typeof value === "string" ? value : value == null ? fallback : formatUnknownError(value);
+  const normalized = sanitizeActionText(source);
+  if (normalized.length === 0) {
+    return fallback;
+  }
+  if (normalized.length <= maxChars) {
+    return normalized;
+  }
+  return `${normalized.slice(0, maxChars)}…`;
+}
+
+function normalizeMethodInput(value: unknown): string {
+  return normalizeTextInput(value, "click", MAX_ACTION_METHOD_CHARS);
+}
+
+function formatPerformActionDiagnostic(value: unknown): string {
+  const normalized = sanitizeActionText(formatUnknownError(value));
+  if (normalized.length === 0) {
+    return "unknown error";
+  }
+  if (normalized.length <= MAX_ACTION_DIAGNOSTIC_CHARS) {
+    return normalized;
+  }
+  const omittedChars = normalized.length - MAX_ACTION_DIAGNOSTIC_CHARS;
+  return `${normalized.slice(0, MAX_ACTION_DIAGNOSTIC_CHARS)}... [truncated ${omittedChars} chars]`;
+}
+
+function normalizeActionArguments(value: unknown): string[] {
+  if (!Array.isArray(value)) return [];
+  return value.slice(0, MAX_ACTION_ARGS).map((arg) =>
+    normalizeTextInput(arg, "", MAX_ACTION_ARG_CHARS)
+  );
+}
+
+function readVariables(ctx: ActionContext): Array<{ key: string; value: string }> {
+  const rawVariables = safeReadRecordField(ctx, "variables");
+  if (!Array.isArray(rawVariables)) {
+    return [];
+  }
+  const normalized: Array<{ key: string; value: string }> = [];
+  for (const entry of rawVariables) {
+    const key = normalizeTextInput(
+      safeReadRecordField(entry, "key"),
+      "",
+      MAX_ACTION_METHOD_CHARS
+    );
+    if (key.length === 0) {
+      continue;
+    }
+    const value = normalizeTextInput(safeReadRecordField(entry, "value"), "", MAX_ACTION_ARG_CHARS);
+    normalized.push({ key, value });
+  }
+  return normalized;
+}
+
+function buildFailureMessage(
+  instruction: string,
+  error: unknown,
+  details?: string
+): string {
+  const diagnostic = formatPerformActionDiagnostic(error);
+  const suffix = details ? `${details}: ${diagnostic}` : diagnostic;
+  return `Failed to execute "${normalizeTextInput(
+    instruction,
+    "task",
+    MAX_ACTION_TEXT_CHARS
+  )}": ${suffix}`;
+}
+
+function interpolateVariables(value: string, ctx: ActionContext): string {
+  const variables = readVariables(ctx);
+  return value.replace(VARIABLE_TOKEN_PATTERN, (match, key) => {
+    const normalizedKey = key.trim();
+    const variable = variables.find((entry) => entry.key === normalizedKey);
+    return variable ? variable.value : match;
+  });
+}
+
 /**
  * Performs a single action on an element
  * Consolidates logic for choosing between CDP and Playwright execution paths
@@ -21,62 +138,113 @@ export async function performAction(
   ctx: ActionContext,
   params: PerformActionParams
 ): Promise<ActionOutput> {
-  const {
-    instruction,
-    elementId,
-    method,
-    arguments: methodArgs = [],
-    confidence,
-  } = params;
+  const instruction = normalizeTextInput(
+    safeReadRecordField(params, "instruction"),
+    "Execute action",
+    MAX_ACTION_TEXT_CHARS
+  );
+  const elementId = normalizeTextInput(
+    safeReadRecordField(params, "elementId"),
+    "",
+    MAX_ACTION_METHOD_CHARS
+  );
+  const method = normalizeMethodInput(safeReadRecordField(params, "method"));
+  const confidence = safeReadRecordField(params, "confidence");
+  const methodArgs = normalizeActionArguments(safeReadRecordField(params, "arguments"));
+  const resolvedInstruction = interpolateVariables(instruction, ctx);
+  const resolvedMethodArgs = methodArgs.map((arg) => interpolateVariables(arg, ctx));
 
   if (!isEncodedId(elementId)) {
     return {
       success: false,
-      message: `Failed to execute "${instruction}": elementId "${elementId}" is not in encoded format (frameIndex-backendNodeId).`,
+      message: `Failed to execute "${resolvedInstruction}": elementId "${elementId}" is not in encoded format (frameIndex-backendNodeId).`,
+    };
+  }
+
+  const domState = safeReadRecordField(ctx, "domState");
+  const elements = safeReadRecordField(domState, "elements");
+  if (!(elements instanceof Map)) {
+    return {
+      success: false,
+      message: `Failed to execute "${resolvedInstruction}": current DOM elements are unavailable.`,
     };
   }
 
   const encodedId = elementId;
-  const elementMetadata = ctx.domState.elements.get(encodedId);
+  let elementMetadata: unknown;
+  try {
+    elementMetadata = elements.get(encodedId);
+  } catch (error) {
+    return {
+      success: false,
+      message: buildFailureMessage(resolvedInstruction, error, "DOM element lookup failed"),
+    };
+  }
   if (!elementMetadata) {
     return {
       success: false,
-      message: `Failed to execute "${instruction}": elementId "${elementId}" not present in current DOM.`,
+      message: `Failed to execute "${resolvedInstruction}": elementId "${elementId}" not present in current DOM.`,
     };
   }
 
-  const timings: Record<string, number> | undefined = ctx.debug ? {} : undefined;
+  const isDebug = safeReadRecordField(ctx, "debug") === true;
+  const debugDir = safeReadRecordField(ctx, "debugDir");
+  const timings: Record<string, number> | undefined = isDebug ? {} : undefined;
   const debugInfo =
-    ctx.debug && elementMetadata
+    isDebug && elementMetadata
       ? {
           requestedAction: {
             elementId,
             method,
-            arguments: methodArgs,
+            arguments: resolvedMethodArgs,
             confidence,
-            instruction,
+            instruction: resolvedInstruction,
           },
           elementMetadata,
           ...(timings ? { timings } : {}),
         }
       : undefined;
 
+  const cdp = safeReadRecordField(ctx, "cdp");
+  const cdpClient = safeReadRecordField(cdp, "client");
+  const resolveElement = safeReadRecordField(cdp, "resolveElement");
+  const dispatchCDPAction = safeReadRecordField(cdp, "dispatchCDPAction");
+  const backendNodeMap = safeReadRecordField(domState, "backendNodeMap");
+  const xpathMap = safeReadRecordField(domState, "xpathMap");
+  const frameMap = safeReadRecordField(domState, "frameMap");
+  const boundingBoxMap = safeReadRecordField(domState, "boundingBoxMap");
+  const frameContextManager = safeReadRecordField(cdp, "frameContextManager");
+  const preferScriptBoundingBox = safeReadRecordField(cdp, "preferScriptBoundingBox");
+  const normalizedBackendNodeMap =
+    backendNodeMap && typeof backendNodeMap === "object"
+      ? (backendNodeMap as Record<string, number>)
+      : undefined;
+  const normalizedXpathMap =
+    xpathMap && typeof xpathMap === "object"
+      ? (xpathMap as Record<string, string>)
+      : {};
+  const normalizedFrameMap = frameMap instanceof Map ? frameMap : undefined;
+
   const shouldUseCDP =
-    !!ctx.cdp && ctx.cdpActions !== false && !!ctx.domState.backendNodeMap;
+    ctx.cdpActions !== false &&
+    !!cdpClient &&
+    typeof resolveElement === "function" &&
+    typeof dispatchCDPAction === "function" &&
+    !!normalizedBackendNodeMap;
 
   if (shouldUseCDP) {
     const resolvedElementsCache = new Map<EncodedId, ResolvedCDPElement>();
     try {
       const resolveStart = performance.now();
-      const resolved = await ctx.cdp!.resolveElement(encodedId, {
+      const resolved = await resolveElement(encodedId, {
         page: ctx.page,
-        cdpClient: ctx.cdp!.client,
-        backendNodeMap: ctx.domState.backendNodeMap,
-        xpathMap: ctx.domState.xpathMap,
-        frameMap: ctx.domState.frameMap,
+        cdpClient,
+        backendNodeMap: normalizedBackendNodeMap,
+        xpathMap: normalizedXpathMap,
+        frameMap: normalizedFrameMap,
         resolvedElementsCache,
-        frameContextManager: ctx.cdp!.frameContextManager,
-        debug: ctx.debug,
+        frameContextManager: frameContextManager as unknown,
+        debug: isDebug,
         strictFrameValidation: true,
       });
       if (timings) {
@@ -84,14 +252,17 @@ export async function performAction(
       }
 
       const dispatchStart = performance.now();
-      await ctx.cdp!.dispatchCDPAction(method as CDPActionMethod, methodArgs, {
+      await dispatchCDPAction(method as CDPActionMethod, resolvedMethodArgs, {
         element: {
           ...resolved,
-          xpath: ctx.domState.xpathMap?.[encodedId],
+          xpath: normalizedXpathMap[encodedId],
         },
-        boundingBox: ctx.domState.boundingBoxMap?.get(encodedId) ?? undefined,
-        preferScriptBoundingBox: ctx.cdp!.preferScriptBoundingBox,
-        debug: ctx.cdp?.debug ?? ctx.debug,
+        boundingBox:
+          boundingBoxMap instanceof Map
+            ? boundingBoxMap.get(encodedId) ?? undefined
+            : undefined,
+        preferScriptBoundingBox: preferScriptBoundingBox as boolean | undefined,
+        debug: safeReadRecordField(cdp, "debug") ?? isDebug,
       });
       if (timings) {
         timings.dispatchMs = Math.round(performance.now() - dispatchStart);
@@ -99,15 +270,13 @@ export async function performAction(
 
       return {
         success: true,
-        message: `Successfully executed: ${instruction}`,
+        message: `Successfully executed: ${resolvedInstruction}`,
         debug: debugInfo,
       };
     } catch (error) {
-      const errorMessage =
-        error instanceof Error ? error.message : String(error);
       return {
         success: false,
-        message: `Failed to execute "${instruction}": ${errorMessage}`,
+        message: buildFailureMessage(resolvedInstruction, error),
         debug: debugInfo,
       };
     }
@@ -118,10 +287,10 @@ export async function performAction(
     const locatorStart = performance.now();
     const { locator } = await getElementLocator(
       elementId,
-      ctx.domState.xpathMap,
+      normalizedXpathMap,
       ctx.page,
-      ctx.domState.frameMap,
-      !!ctx.debugDir
+      normalizedFrameMap,
+      typeof debugDir === "string" && debugDir.trim().length > 0
     );
     if (timings) {
       timings.locatorMs = Math.round(performance.now() - locatorStart);
@@ -129,9 +298,9 @@ export async function performAction(
 
     // Execute Playwright method using shared utility
     const pwStart = performance.now();
-    await executePlaywrightMethod(method, methodArgs, locator, {
+    await executePlaywrightMethod(method, resolvedMethodArgs, locator, {
       clickTimeout: 3500,
-      debug: !!ctx.debugDir,
+      debug: typeof debugDir === "string" && debugDir.trim().length > 0,
     });
     if (timings) {
       timings.playwrightActionMs = Math.round(performance.now() - pwStart);
@@ -139,15 +308,13 @@ export async function performAction(
 
     return {
       success: true,
-      message: `Successfully executed: ${instruction}`,
+      message: `Successfully executed: ${resolvedInstruction}`,
       debug: debugInfo,
     };
   } catch (error) {
-    const errorMessage =
-      error instanceof Error ? error.message : String(error);
     return {
       success: false,
-      message: `Failed to execute "${instruction}": ${errorMessage}`,
+      message: buildFailureMessage(resolvedInstruction, error),
       debug: debugInfo,
     };
   }
diff --git a/src/agent/actions/wait.ts b/src/agent/actions/wait.ts
index db87e2f2..8adf3b4c 100644
--- a/src/agent/actions/wait.ts
+++ b/src/agent/actions/wait.ts
@@ -1,6 +1,11 @@
 import { z } from "zod";
 import { ActionContext, ActionOutput, AgentActionDefinition } from "@/types";
 import { waitForSettledDOM } from "@/utils/waitForSettledDOM";
+import {
+  buildActionFailureMessage,
+  invalidateDomCacheSafely,
+  normalizeActionText,
+} from "./shared/action-runtime";
 
 const WaitAction = z
   .object({
@@ -13,6 +18,7 @@ const WaitAction = z
   .describe("Use this action when you are not confident enough to take a meaningful action. The page may still be loading, elements may not be visible yet, or the page state may be unclear. The system will wait for the DOM to settle and give you a fresh view.");
 
 type WaitActionType = z.infer<typeof WaitAction>;
+const WAIT_POST_SETTLE_DELAY_MS = 1_000;
 
 export const WaitActionDefinition: AgentActionDefinition = {
   type: "wait" as const,
@@ -21,18 +27,27 @@ export const WaitActionDefinition: AgentActionDefinition = {
     ctx: ActionContext,
     action: WaitActionType
   ): Promise<ActionOutput> {
-    const { reason } = action;
+    const reason = normalizeActionText(action?.reason, "waiting for page stability");
+    try {
+      // Wait for DOM to settle (page to finish loading/transitioning)
+      await waitForSettledDOM(ctx.page, undefined, {
+        filterAdTrackingFrames: ctx.filterAdTrackingFrames,
+      });
 
-    // Wait for DOM to settle (page to finish loading/transitioning)
-    await waitForSettledDOM(ctx.page);
+      // Additional brief wait to allow any animations/transitions to complete
+      await new Promise((resolve) => setTimeout(resolve, WAIT_POST_SETTLE_DELAY_MS));
+      invalidateDomCacheSafely(ctx);
 
-    // Additional brief wait to allow any animations/transitions to complete
-    await new Promise((resolve) => setTimeout(resolve, 1000));
-
-    return {
-      success: true,
-      message: `Waiting for page to stabilize: ${reason}`,
-    };
+      return {
+        success: true,
+        message: `Waiting for page to stabilize: ${reason}`,
+      };
+    } catch (error) {
+      return {
+        success: false,
+        message: buildActionFailureMessage("wait for page stabilization", error),
+      };
+    }
   },
   pprintAction: function (params: WaitActionType): string {
     return `Wait: ${params.reason}`;
diff --git a/src/agent/error.ts b/src/agent/error.ts
index b7a85b57..328955d1 100644
--- a/src/agent/error.ts
+++ b/src/agent/error.ts
@@ -7,3 +7,15 @@ export class HyperagentError extends Error {
     this.name = "HyperagentError";
   }
 }
+
+export class HyperagentTaskError extends HyperagentError {
+  public readonly taskId: string;
+  public readonly cause: Error;
+
+  constructor(taskId: string, cause: Error) {
+    super(`Task ${taskId} failed: ${cause.message}`, 500);
+    this.name = "HyperagentTaskError";
+    this.taskId = taskId;
+    this.cause = cause;
+  }
+}
diff --git a/src/agent/examine-dom/index.test.ts b/src/agent/examine-dom/index.test.ts
new file mode 100644
index 00000000..164347dd
--- /dev/null
+++ b/src/agent/examine-dom/index.test.ts
@@ -0,0 +1,241 @@
+import { examineDom, extractValueFromInstruction } from "@/agent/examine-dom";
+import type { ExamineDomContext } from "@/agent/examine-dom/types";
+import type { HyperAgentLLM } from "@/llm/types";
+
+const createContext = (): ExamineDomContext => ({
+  tree: "[0-1] button: Submit\n[0-2] textbox: Email",
+  xpathMap: {
+    "0-1": "//button[1]",
+  },
+  elements: new Map([
+    [
+      "0-2",
+      {
+        role: "textbox",
+      },
+    ],
+  ]),
+  url: "https://example.com",
+});
+
+const createLLM = (
+  invokeStructured: jest.Mock
+): HyperAgentLLM =>
+  ({
+    invoke: jest.fn(async () => ({ role: "assistant", content: "ok" })),
+    invokeStructured,
+    getProviderId: () => "mock",
+    getModelId: () => "mock-model",
+    getCapabilities: () => ({
+      multimodal: false,
+      toolCalling: true,
+      jsonMode: true,
+    }),
+  }) as HyperAgentLLM;
+
+describe("examineDom", () => {
+  it("sorts by confidence and filters unknown element IDs", async () => {
+    const warnSpy = jest.spyOn(console, "warn").mockImplementation(() => {});
+    try {
+      const invokeStructured = jest.fn().mockResolvedValue({
+        rawText: "{}",
+        parsed: {
+          elements: [
+            { elementId: "0-missing", confidence: 0.99, reason: "nope" },
+            { elementId: "0-1", confidence: 0.3, reason: "button" },
+            { elementId: "0-2", confidence: 0.8, reason: "textbox" },
+          ],
+        },
+      });
+
+      const result = await examineDom(
+        "click submit",
+        createContext(),
+        createLLM(invokeStructured)
+      );
+
+      expect(result.elements.map((entry) => entry.elementId)).toEqual([
+        "0-2",
+        "0-1",
+      ]);
+      expect(warnSpy).toHaveBeenCalledWith(
+        "[examineDom] Element 0-missing not found in context, skipping"
+      );
+    } finally {
+      warnSpy.mockRestore();
+    }
+  });
+
+  it("returns empty elements when parsed payload is missing", async () => {
+    const invokeStructured = jest.fn().mockResolvedValue({
+      rawText: "raw",
+      parsed: null,
+    });
+
+    const result = await examineDom(
+      "find element",
+      createContext(),
+      createLLM(invokeStructured)
+    );
+
+    expect(result.elements).toEqual([]);
+    expect(result.llmResponse).toEqual({
+      rawText: "raw",
+      parsed: null,
+    });
+  });
+
+  it("returns empty elements when parsed element iteration traps", async () => {
+    const trappedElements = new Proxy([], {
+      get: (target, prop, receiver) => {
+        if (prop === Symbol.iterator) {
+          throw new Error("iterator trap");
+        }
+        return Reflect.get(target, prop, receiver);
+      },
+    });
+    const invokeStructured = jest.fn().mockResolvedValue({
+      rawText: "raw",
+      parsed: {
+        elements: trappedElements,
+      },
+    });
+
+    const result = await examineDom(
+      "find element",
+      createContext(),
+      createLLM(invokeStructured)
+    );
+
+    expect(result.elements).toEqual([]);
+    expect(result.llmResponse.rawText).toBe("raw");
+  });
+
+  it("normalizes malformed parsed element entries safely", async () => {
+    const invokeStructured = jest.fn().mockResolvedValue({
+      rawText: "raw",
+      parsed: {
+        elements: [
+          { elementId: " 0-2 ", confidence: "high", reason: 1 },
+          { elementId: "", confidence: 1 },
+          { confidence: 0.8 },
+        ],
+      },
+    });
+
+    const result = await examineDom(
+      "find element",
+      createContext(),
+      createLLM(invokeStructured)
+    );
+
+    expect(result.elements).toEqual([
+      {
+        elementId: "0-2",
+        description: "",
+        confidence: 0,
+        method: "click",
+        arguments: [],
+      },
+    ]);
+  });
+
+  it("formats non-Error thrown values from invokeStructured", async () => {
+    const errorSpy = jest.spyOn(console, "error").mockImplementation(() => {});
+    try {
+      const invokeStructured = jest
+        .fn()
+        .mockRejectedValue({ reason: "llm exploded" });
+
+      const result = await examineDom(
+        "find element",
+        createContext(),
+        createLLM(invokeStructured)
+      );
+
+      expect(result.elements).toEqual([]);
+      expect(result.llmResponse).toEqual({ rawText: "", parsed: null });
+      expect(errorSpy).toHaveBeenCalledWith(
+        '[examineDom] Error finding elements: {"reason":"llm exploded"}'
+      );
+    } finally {
+      errorSpy.mockRestore();
+    }
+  });
+
+  it("sanitizes and truncates oversized examineDom diagnostics", async () => {
+    const errorSpy = jest.spyOn(console, "error").mockImplementation(() => {});
+    try {
+      const invokeStructured = jest
+        .fn()
+        .mockRejectedValue(new Error(`llm\u0000\n${"x".repeat(10_000)}`));
+
+      const result = await examineDom(
+        "find element",
+        createContext(),
+        createLLM(invokeStructured)
+      );
+
+      expect(result.elements).toEqual([]);
+      const diagnostic = String(errorSpy.mock.calls[0]?.[0] ?? "");
+      expect(diagnostic).toContain("[truncated");
+      expect(diagnostic).not.toContain("\u0000");
+      expect(diagnostic).not.toContain("\n");
+      expect(diagnostic.length).toBeLessThan(700);
+    } finally {
+      errorSpy.mockRestore();
+    }
+  });
+
+  it("sanitizes and truncates missing-element warning identifiers", async () => {
+    const warnSpy = jest.spyOn(console, "warn").mockImplementation(() => {});
+    try {
+      const invokeStructured = jest.fn().mockResolvedValue({
+        rawText: "{}",
+        parsed: {
+          elements: [
+            {
+              elementId: `missing\u0000\n${"x".repeat(400)}`,
+              confidence: 0.99,
+              reason: "nope",
+            },
+          ],
+        },
+      });
+
+      const result = await examineDom(
+        "click submit",
+        createContext(),
+        createLLM(invokeStructured)
+      );
+
+      expect(result.elements).toEqual([]);
+      const warning = String(warnSpy.mock.calls[0]?.[0] ?? "");
+      expect(warning).toContain("[truncated");
+      expect(warning).not.toContain("\u0000");
+      expect(warning).not.toContain("\n");
+      expect(warning.length).toBeLessThan(500);
+    } finally {
+      warnSpy.mockRestore();
+    }
+  });
+});
+
+describe("extractValueFromInstruction", () => {
+  it("extracts value from supported prepositions", () => {
+    expect(extractValueFromInstruction("fill email with test@example.com")).toBe(
+      "test@example.com"
+    );
+    expect(extractValueFromInstruction("type hello into search box")).toBe(
+      "hello"
+    );
+    expect(extractValueFromInstruction("enter password123 in password field")).toBe(
+      "password123"
+    );
+  });
+
+  it("returns empty string when no value can be inferred", () => {
+    expect(extractValueFromInstruction("click submit button")).toBe("");
+    expect(extractValueFromInstruction("   ")).toBe("");
+  });
+});
diff --git a/src/agent/examine-dom/index.ts b/src/agent/examine-dom/index.ts
index bb8a6943..ac16fd0f 100644
--- a/src/agent/examine-dom/index.ts
+++ b/src/agent/examine-dom/index.ts
@@ -12,6 +12,120 @@ import {
   buildExamineDomUserPrompt,
 } from "./prompts";
 import { ExamineDomResultsSchema, ExamineDomResultsType } from "./schema";
+import {
+  AGENT_ELEMENT_ACTIONS,
+  type AgentElementAction,
+} from "../shared/action-restrictions";
+import { formatUnknownError } from "@/utils";
+
+const MAX_EXAMINE_DOM_DIAGNOSTIC_CHARS = 400;
+const MAX_EXAMINE_DOM_IDENTIFIER_CHARS = 128;
+
+function sanitizeExamineDomText(value: string): string {
+  if (value.length === 0) {
+    return value;
+  }
+  const withoutControlChars = Array.from(value, (char) => {
+    const code = char.charCodeAt(0);
+    return (code >= 0 && code < 32) || code === 127 ? " " : char;
+  }).join("");
+  return withoutControlChars.replace(/\s+/g, " ").trim();
+}
+
+function truncateExamineDomText(value: string, maxChars: number): string {
+  if (value.length <= maxChars) {
+    return value;
+  }
+  const omittedChars = value.length - maxChars;
+  return `${value.slice(0, maxChars)}... [truncated ${omittedChars} chars]`;
+}
+
+function formatExamineDomDiagnostic(value: unknown): string {
+  const normalized = sanitizeExamineDomText(formatUnknownError(value));
+  if (normalized.length === 0) {
+    return "unknown error";
+  }
+  return truncateExamineDomText(normalized, MAX_EXAMINE_DOM_DIAGNOSTIC_CHARS);
+}
+
+function formatExamineDomIdentifier(value: unknown): string {
+  if (typeof value !== "string") {
+    return "unknown";
+  }
+  const normalized = sanitizeExamineDomText(value);
+  if (normalized.length === 0) {
+    return "unknown";
+  }
+  return truncateExamineDomText(normalized, MAX_EXAMINE_DOM_IDENTIFIER_CHARS);
+}
+
+function isRecord(value: unknown): value is Record<string, unknown> {
+  return typeof value === "object" && value !== null;
+}
+
+function safeReadRecordField(source: unknown, key: string): unknown {
+  if (!isRecord(source)) {
+    return undefined;
+  }
+  try {
+    return source[key];
+  } catch {
+    return undefined;
+  }
+}
+
+function normalizeParsedElements(parsed: unknown): ExamineDomResult[] {
+  const rawElements = safeReadRecordField(parsed, "elements");
+  if (!Array.isArray(rawElements)) {
+    return [];
+  }
+  let entries: unknown[];
+  try {
+    entries = Array.from(rawElements);
+  } catch {
+    return [];
+  }
+
+  const normalized: ExamineDomResult[] = [];
+  const supportedMethods = new Set<string>(AGENT_ELEMENT_ACTIONS);
+  for (const entry of entries) {
+    const elementIdValue = safeReadRecordField(entry, "elementId");
+    if (typeof elementIdValue !== "string") {
+      continue;
+    }
+    const elementId = elementIdValue.trim();
+    if (elementId.length === 0) {
+      continue;
+    }
+    const confidenceValue = safeReadRecordField(entry, "confidence");
+    const confidence =
+      typeof confidenceValue === "number" && Number.isFinite(confidenceValue)
+        ? confidenceValue
+        : 0;
+    const descriptionValue = safeReadRecordField(entry, "description");
+    const description =
+      typeof descriptionValue === "string" ? descriptionValue : "";
+    const methodValue = safeReadRecordField(entry, "method");
+    let method: AgentElementAction = "click";
+    if (typeof methodValue === "string" && supportedMethods.has(methodValue)) {
+      method = methodValue as AgentElementAction;
+    }
+    const argumentsValue = safeReadRecordField(entry, "arguments");
+    const argumentsList = Array.isArray(argumentsValue)
+      ? argumentsValue
+          .map((argument) => (typeof argument === "string" ? argument : ""))
+          .filter((argument) => argument.length > 0)
+      : [];
+    normalized.push({
+      elementId,
+      confidence,
+      description,
+      method,
+      arguments: argumentsList,
+    });
+  }
+  return normalized;
+}
 
 /**
  * Find elements in the accessibility tree that match the given instruction
@@ -69,13 +183,14 @@ export async function examineDom(
       parsed: response.parsed,
     };
 
-    if (!response.parsed || !response.parsed.elements) {
+    const parsedElements = normalizeParsedElements(response.parsed);
+    if (parsedElements.length === 0) {
       // No elements found or parsing failed
       return { elements: [], llmResponse };
     }
 
     // Sort by confidence descending (highest confidence first)
-    const results = response.parsed.elements.sort(
+    const results = parsedElements.sort(
       (a: ExamineDomResult, b: ExamineDomResult) => b.confidence - a.confidence
     );
 
@@ -87,7 +202,9 @@ export async function examineDom(
 
       if (!existsInElements && !existsInXpathMap) {
         console.warn(
-          `[examineDom] Element ${result.elementId} not found in context, skipping`
+          `[examineDom] Element ${formatExamineDomIdentifier(
+            result.elementId
+          )} not found in context, skipping`
         );
         return false;
       }
@@ -97,7 +214,11 @@ export async function examineDom(
 
     return { elements: validatedResults, llmResponse };
   } catch (error) {
-    console.error("[examineDom] Error finding elements:", error);
+    console.error(
+      `[examineDom] Error finding elements: ${formatExamineDomDiagnostic(
+        error
+      )}`
+    );
     // Return empty result on error (graceful degradation)
     return {
       elements: [],
@@ -121,14 +242,28 @@ export async function examineDom(
  * @returns The extracted value or empty string if no value found
  */
 export function extractValueFromInstruction(instruction: string): string {
-  // Pattern: "with X", "into X", "in X"
-  const patterns = [/with\s+(.+)$/i, /into\s+(.+)$/i, /in\s+(.+)$/i];
+  const normalizedInstruction = instruction.trim();
+  if (normalizedInstruction.length === 0) {
+    return "";
+  }
 
-  for (const pattern of patterns) {
-    const match = instruction.match(pattern);
-    if (match) {
-      return match[1].trim();
-    }
+  const withMatch = normalizedInstruction.match(/\bwith\s+(.+)$/i);
+  if (withMatch) {
+    return withMatch[1].trim();
+  }
+
+  const intoMatch = normalizedInstruction.match(
+    /^(?:fill|type|enter)\s+(.+?)\s+\binto\b/i
+  );
+  if (intoMatch) {
+    return intoMatch[1].trim();
+  }
+
+  const inMatch = normalizedInstruction.match(
+    /^(?:fill|type|enter)\s+(.+?)\s+\bin\b/i
+  );
+  if (inMatch) {
+    return inMatch[1].trim();
   }
 
   return "";
diff --git a/src/agent/examine-dom/prompts.test.ts b/src/agent/examine-dom/prompts.test.ts
new file mode 100644
index 00000000..6745d5d4
--- /dev/null
+++ b/src/agent/examine-dom/prompts.test.ts
@@ -0,0 +1,34 @@
+import {
+  buildActionInstruction,
+  buildExamineDomSystemPrompt,
+  buildExamineDomUserPrompt,
+} from "@/agent/examine-dom/prompts";
+
+describe("examine-dom prompts", () => {
+  it("constrains action instruction to supported methods only", () => {
+    const prompt = buildActionInstruction("click the login button");
+
+    expect(prompt).toContain("using ONLY one of these methods");
+    expect(prompt).toContain("selectOptionFromDropdown");
+    expect(prompt).toContain("Do not use any other Playwright locator/action method.");
+    expect(prompt).not.toContain("or any other playwright locator method");
+  });
+
+  it("builds a user prompt that includes instruction and tree", () => {
+    const prompt = buildExamineDomUserPrompt(
+      "fill email",
+      "[0-1] textbox: Email"
+    );
+
+    expect(prompt).toContain("instruction:");
+    expect(prompt).toContain("Accessibility Tree:");
+    expect(prompt).toContain("[0-1] textbox: Email");
+  });
+
+  it("keeps system prompt focused on matching elements", () => {
+    const prompt = buildExamineDomSystemPrompt();
+
+    expect(prompt).toContain("Return an array of elements");
+    expect(prompt).toContain("hierarchical accessibility tree");
+  });
+});
diff --git a/src/agent/examine-dom/prompts.ts b/src/agent/examine-dom/prompts.ts
index a186332c..f2d3baad 100644
--- a/src/agent/examine-dom/prompts.ts
+++ b/src/agent/examine-dom/prompts.ts
@@ -37,7 +37,8 @@ export function buildActionInstruction(action: string): string {
   ];
 
   const instruction = `Find the most relevant element to perform an action on given the following action: ${action}.
-Provide an action for this element such as ${supportedActions.join(", ")}, or any other playwright locator method. Remember that to users, buttons and links look the same in most cases.
+Provide an action for this element using ONLY one of these methods: ${supportedActions.join(", ")}. Do not use any other Playwright locator/action method.
+Remember that to users, buttons and links look the same in most cases.
 If the action is completely unrelated to a potential action to be taken on the page, return an empty array.
 ONLY return one action. If multiple actions are relevant, return the most relevant one.
 For scroll actions (scrollToElement, scrollToPercentage, nextChunk, prevChunk), prefer elements marked as "scrollable" in their role. These have been automatically detected as scrollable containers. If no scrollable elements are available, choose the html element as a fallback.
diff --git a/src/agent/index.ts b/src/agent/index.ts
index f7bed8e1..f0883783 100644
--- a/src/agent/index.ts
+++ b/src/agent/index.ts
@@ -32,7 +32,7 @@ import {
   HyperbrowserProvider,
   LocalBrowserProvider,
 } from "../browser-providers";
-import { HyperagentError } from "./error";
+import { HyperagentError, HyperagentTaskError } from "./error";
 import { findElementWithInstruction } from "./shared/find-element";
 import {
   A11yDOMState,
@@ -47,9 +47,10 @@ import type {
   ActionCacheEntry,
   AgentTaskOutput,
   PerformOptions,
+  PerformTaskParams,
 } from "../types/agent/types";
 import { z } from "zod";
-import { ErrorEmitter } from "../utils";
+import { ErrorEmitter, formatUnknownError, normalizePageUrl } from "../utils";
 import { waitForSettledDOM } from "@/utils/waitForSettledDOM";
 import { performance } from "perf_hooks";
 import { ExamineDomResult } from "./examine-dom/types";
@@ -59,38 +60,1272 @@ import { setDebugOptions } from "@/debug/options";
 import { initializeRuntimeContext } from "./shared/runtime-context";
 import { performAction } from "./actions/shared/perform-action";
 import { createScriptFromActionCache } from "./shared/action-cache-script";
-import { attachCachedActionHelpers } from "./shared/action-cache-exec";
+import {
+  attachCachedActionHelpers,
+  dispatchPerformHelper,
+  normalizePageActionMethod,
+} from "./shared/action-cache-exec";
 import { AgentDeps } from "@/types/agent/types";
+import { parseExtractOutput } from "./shared/parse-extract-output";
+import {
+  executeReplaySpecialAction,
+  REPLAY_SPECIAL_ACTION_TYPES,
+} from "./shared/replay-special-actions";
+
+export class HyperAgent<T extends BrowserProviders = "Local"> {
+  // page.perform (single-action) configuration constants
+  private static readonly PERFORM_CONFIG = {
+    MAX_RETRIES: 10,
+    RETRY_DELAY_MS: 1000,
+    CLICK_TIMEOUT: 3500,
+    MAX_DEBUG_ELEMENTS_TO_DISPLAY: 20,
+    MAX_DEBUG_ELEMENTS_TO_STORE: 50,
+    MAX_LABEL_LENGTH: 60,
+  };
+  private static readonly MAX_REPLAY_OUTPUT_CHARS = 4_000;
+  private static readonly MAX_REPLAY_DIAGNOSTIC_CHARS = 400;
+  private static readonly MAX_REPLAY_IDENTIFIER_CHARS = 128;
+  private static readonly MAX_MCP_SERVER_ITEMS = 500;
+  private static readonly MAX_MCP_SERVER_TOOL_ITEMS = 500;
+  private static readonly MAX_MCP_SERVER_IDENTIFIER_CHARS = 128;
+  private static readonly MAX_LIFECYCLE_DIAGNOSTIC_CHARS = 400;
+  private static readonly MAX_HELPER_DIAGNOSTIC_CHARS = 400;
+  private static readonly MAX_PAGE_URL_CHARS = 1_000;
+  private static readonly MAX_REPLAY_STEPS = 1_000;
+  private static readonly MAX_ACTION_CACHE_ENTRIES = 200;
+  private static readonly DEFAULT_ACTION_CACHE_CREATED_AT =
+    new Date(0).toISOString();
+  private static readonly AIACTION_DEPRECATION_MESSAGE =
+    "[HyperPage] page.aiAction() is deprecated; use page.perform() instead.";
+  private static readonly PERFORM_MAX_STEPS_DEPRECATION_MESSAGE =
+    "[HyperPage] perform({ maxSteps }) is deprecated; use perform({ maxElementRetries }) instead.";
+  private static readonly PERFORM_DEBUG_DIR = "debug/perform";
+
+  private llm: HyperAgentLLM;
+  private tasks: Record<string, TaskState> = {};
+  private tokenLimit = 128000;
+  private debug = false;
+  private mcpClient: MCPClient | undefined;
+  private browserProvider: T extends "Hyperbrowser"
+    ? HyperbrowserProvider
+    : LocalBrowserProvider;
+  private browserProviderType: T;
+  private actions: Array<AgentActionDefinition> = [...DEFAULT_ACTIONS];
+  private cdpActionsEnabled = true;
+  private filterAdTrackingFrames = true;
+  private actionCacheByTaskId: Record<string, ActionCacheOutput> = {};
+  private actionCacheTaskOrder: string[] = [];
+  private taskResults: Record<string, Promise<AgentTaskOutput>> = {};
+  private taskErrorForwarders: Map<string, (error: Error) => void> = new Map();
+  private mcpActionTypesByServer: Map<string, Set<string>> = new Map();
+  private scopeListenerCleanupByPage: WeakMap<Page, () => void> = new WeakMap();
+  private lifecycleGeneration = 0;
+  private hasWarnedAiActionDeprecation = false;
+  private hasWarnedPerformMaxStepsDeprecation = false;
+
+  public browser: Browser | null = null;
+  public context: BrowserContext | null = null;
+  private _currentPage: Page | null = null;
+  private _variables: Record<string, HyperVariable> = {};
+  private errorEmitter: ErrorEmitter;
+  private static readonly TASK_STATUS_VALUES = new Set<string>(
+    Object.values(TaskStatus)
+  );
+
+  private safeGetPageUrl(page: Page): string {
+    try {
+      return normalizePageUrl(page.url(), {
+        maxChars: HyperAgent.MAX_PAGE_URL_CHARS,
+      });
+    } catch {
+      return "about:blank";
+    }
+  }
+
+  private safeIsPageClosed(page: Page): boolean {
+    try {
+      return page.isClosed();
+    } catch {
+      return false;
+    }
+  }
+
+  private formatLifecycleDiagnostic(value: unknown): string {
+    const normalized = Array.from(formatUnknownError(value), (char) => {
+      const code = char.charCodeAt(0);
+      return (code >= 0 && code < 32) || code === 127 ? " " : char;
+    })
+      .join("")
+      .replace(/\s+/g, " ")
+      .trim();
+    const fallback = normalized.length > 0 ? normalized : "unknown error";
+    if (fallback.length <= HyperAgent.MAX_LIFECYCLE_DIAGNOSTIC_CHARS) {
+      return fallback;
+    }
+    const omitted =
+      fallback.length - HyperAgent.MAX_LIFECYCLE_DIAGNOSTIC_CHARS;
+    return `${fallback.slice(
+      0,
+      HyperAgent.MAX_LIFECYCLE_DIAGNOSTIC_CHARS
+    )}... [truncated ${omitted} chars]`;
+  }
+
+  private formatHelperDiagnostic(value: unknown): string {
+    const normalized = Array.from(formatUnknownError(value), (char) => {
+      const code = char.charCodeAt(0);
+      return (code >= 0 && code < 32) || code === 127 ? " " : char;
+    })
+      .join("")
+      .replace(/\s+/g, " ")
+      .trim();
+    const fallback = normalized.length > 0 ? normalized : "unknown error";
+    if (fallback.length <= HyperAgent.MAX_HELPER_DIAGNOSTIC_CHARS) {
+      return fallback;
+    }
+    const omitted = fallback.length - HyperAgent.MAX_HELPER_DIAGNOSTIC_CHARS;
+    return `${fallback.slice(
+      0,
+      HyperAgent.MAX_HELPER_DIAGNOSTIC_CHARS
+    )}... [truncated ${omitted} chars]`;
+  }
+
+  private formatMCPDiagnostic(value: unknown): string {
+    return this.formatHelperDiagnostic(value);
+  }
+
+  private warnAiActionDeprecation(): void {
+    if (this.hasWarnedAiActionDeprecation) {
+      return;
+    }
+    this.hasWarnedAiActionDeprecation = true;
+    try {
+      console.warn(HyperAgent.AIACTION_DEPRECATION_MESSAGE);
+    } catch {
+      // no-op
+    }
+  }
+
+  private warnPerformMaxStepsDeprecation(): void {
+    if (this.hasWarnedPerformMaxStepsDeprecation) {
+      return;
+    }
+    this.hasWarnedPerformMaxStepsDeprecation = true;
+    try {
+      console.warn(HyperAgent.PERFORM_MAX_STEPS_DEPRECATION_MESSAGE);
+    } catch {
+      // no-op
+    }
+  }
+
+  private shouldWarnPerformMaxStepsDeprecation(
+    params?: PerformTaskParams
+  ): boolean {
+    return (
+      typeof params?.maxElementRetries !== "number" &&
+      typeof params?.maxSteps === "number"
+    );
+  }
+
+  private isHyperAgentLLMClient(value: unknown): value is HyperAgentLLM {
+    const invoke = this.safeReadField(value, "invoke");
+    const invokeStructured = this.safeReadField(value, "invokeStructured");
+    const getProviderId = this.safeReadField(value, "getProviderId");
+    const getModelId = this.safeReadField(value, "getModelId");
+    const getCapabilities = this.safeReadField(value, "getCapabilities");
+
+    return (
+      typeof invoke === "function" &&
+      typeof invokeStructured === "function" &&
+      typeof getProviderId === "function" &&
+      typeof getModelId === "function" &&
+      typeof getCapabilities === "function"
+    );
+  }
+
+  private resolveFilterAdTrackingFrames(value: unknown): boolean {
+    if (typeof value === "boolean") {
+      return value;
+    }
+    return this.filterAdTrackingFrames;
+  }
+
+  private resolveCdpActions(value: unknown): boolean {
+    if (typeof value === "boolean") {
+      return value;
+    }
+    return this.cdpActionsEnabled;
+  }
+
+  private readTaskStatus(
+    taskState: TaskState,
+    fallback: TaskStatus = TaskStatus.FAILED
+  ): TaskStatus {
+    try {
+      const value = taskState.status;
+      if (
+        typeof value === "string" &&
+        HyperAgent.TASK_STATUS_VALUES.has(value)
+      ) {
+        return value as TaskStatus;
+      }
+      return fallback;
+    } catch {
+      return fallback;
+    }
+  }
+
+  private writeTaskStatus(
+    taskState: TaskState,
+    nextStatus: TaskStatus,
+    fallback: TaskStatus = TaskStatus.FAILED
+  ): TaskStatus {
+    try {
+      taskState.status = nextStatus;
+    } catch {
+      return fallback;
+    }
+    return this.readTaskStatus(taskState, fallback);
+  }
+
+  private attachPageListenerForTask(
+    onPage: (newPage: Page) => void | Promise<void>
+  ): () => void {
+    const context = this.context;
+    if (!context) {
+      return () => undefined;
+    }
+
+    const contextOn = this.safeReadField(context, "on");
+    if (typeof contextOn !== "function") {
+      if (this.debug) {
+        console.warn(
+          "[HyperAgent] Failed to attach task page listener: context.on is unavailable"
+        );
+      }
+      return () => undefined;
+    }
+    try {
+      (
+        contextOn as (
+          this: BrowserContext,
+          event: "page",
+          listener: (newPage: Page) => void | Promise<void>
+        ) => void
+      ).call(context, "page", onPage);
+    } catch (error) {
+      if (this.debug) {
+        console.warn(
+          `[HyperAgent] Failed to attach task page listener: ${this.formatLifecycleDiagnostic(
+            error
+          )}`
+        );
+      }
+      return () => undefined;
+    }
+
+    return () => {
+      const contextOff = this.safeReadField(context, "off");
+      if (typeof contextOff !== "function") {
+        if (this.debug) {
+          console.warn(
+            "[HyperAgent] Failed to detach task page listener: context.off is unavailable"
+          );
+        }
+        return;
+      }
+      try {
+        (
+          contextOff as (
+            this: BrowserContext,
+            event: "page",
+            listener: (newPage: Page) => void | Promise<void>
+          ) => void
+        ).call(context, "page", onPage);
+      } catch (error) {
+        if (this.debug) {
+          console.warn(
+            `[HyperAgent] Failed to detach task page listener: ${this.formatLifecycleDiagnostic(
+              error
+            )}`
+          );
+        }
+      }
+    };
+  }
+
+  private getVariableEntries(): Array<[string, HyperVariable]> {
+    const source = this._variables;
+    if (!source || typeof source !== "object") {
+      return [];
+    }
+    try {
+      return Object.entries(source) as Array<[string, HyperVariable]>;
+    } catch {
+      return [];
+    }
+  }
+
+  private getVariableSnapshot(): Record<string, HyperVariable> {
+    return this.getVariableEntries().reduce<Record<string, HyperVariable>>(
+      (acc, [key, value]) => {
+        if (typeof key !== "string" || key.trim().length === 0) {
+          return acc;
+        }
+        acc[key] = value;
+        return acc;
+      },
+      {}
+    );
+  }
+
+  private getVariableValues(): HyperVariable[] {
+    return this.getVariableEntries()
+      .map(([, value]) => value)
+      .filter((value) => value != null);
+  }
+
+  private normalizeVariableKey(value: unknown): string | null {
+    if (typeof value !== "string") {
+      return null;
+    }
+    const normalized = value.trim();
+    return normalized.length > 0 ? normalized : null;
+  }
+
+  private normalizeServerId(value: unknown): string | null {
+    if (typeof value !== "string") {
+      return null;
+    }
+    const normalized = value.trim();
+    return normalized.length > 0 ? normalized : null;
+  }
+
+  private safeReadField(value: unknown, key: string): unknown {
+    if (!value || (typeof value !== "object" && typeof value !== "function")) {
+      return undefined;
+    }
+    try {
+      return (value as Record<string, unknown>)[key];
+    } catch {
+      return undefined;
+    }
+  }
+
+  private safeArrayLength(value: unknown): number {
+    if (!Array.isArray(value)) {
+      return 0;
+    }
+    try {
+      const length = value.length;
+      if (!Number.isFinite(length) || length < 0) {
+        return 0;
+      }
+      return Math.floor(length);
+    } catch {
+      return 0;
+    }
+  }
+
+  private safeArrayValues<T>(value: unknown): T[] {
+    const length = this.safeArrayLength(value);
+    if (length === 0 || !Array.isArray(value)) {
+      return [];
+    }
+    const values: T[] = [];
+    for (let index = 0; index < length; index += 1) {
+      try {
+        const item = value[index] as T | undefined;
+        if (typeof item !== "undefined") {
+          values.push(item);
+        }
+      } catch {
+        continue;
+      }
+    }
+    return values;
+  }
+
+  private getContextPagesOrThrow(context: BrowserContext): Page[] {
+    let pagesMethod: unknown;
+    try {
+      pagesMethod = (context as BrowserContext & { pages?: unknown }).pages;
+    } catch (error) {
+      throw new Error(
+        `failed to read context.pages: ${this.formatLifecycleDiagnostic(error)}`
+      );
+    }
+    if (typeof pagesMethod !== "function") {
+      throw new Error("context.pages is unavailable");
+    }
+
+    const pagesValue = (pagesMethod as (this: BrowserContext) => unknown).call(
+      context
+    );
+    return this.safeArrayValues<Page>(pagesValue);
+  }
+
+  private getContextPagesSafe(context: BrowserContext): Page[] {
+    try {
+      return this.getContextPagesOrThrow(context);
+    } catch {
+      return [];
+    }
+  }
+
+  private async createContextPageOrThrow(context: BrowserContext): Promise<Page> {
+    let newPageMethod: unknown;
+    try {
+      newPageMethod = (context as BrowserContext & { newPage?: unknown }).newPage;
+    } catch (error) {
+      throw new Error(
+        `failed to read context.newPage: ${this.formatLifecycleDiagnostic(error)}`
+      );
+    }
+    if (typeof newPageMethod !== "function") {
+      throw new Error("context.newPage is unavailable");
+    }
+
+    const createdPage = await (
+      newPageMethod as (this: BrowserContext) => Promise<unknown>
+    ).call(context);
+    if (!createdPage || typeof createdPage !== "object") {
+      throw new Error("context.newPage returned an invalid page");
+    }
+    return createdPage as Page;
+  }
+
+  private readErrorEmitterMethodOrThrow(
+    methodName: "on" | "addListener" | "off" | "removeListener"
+  ): (this: ErrorEmitter, eventName: string, listener: (error: Error) => void) => void {
+    let method: unknown;
+    try {
+      method = (
+        this.errorEmitter as ErrorEmitter & {
+          on?: unknown;
+          addListener?: unknown;
+          off?: unknown;
+          removeListener?: unknown;
+        }
+      )[methodName];
+    } catch (error) {
+      throw new Error(
+        `failed to read errorEmitter.${methodName}: ${this.formatLifecycleDiagnostic(
+          error
+        )}`
+      );
+    }
+    if (typeof method !== "function") {
+      throw new Error(`errorEmitter.${methodName} is unavailable`);
+    }
+    return method as (
+      this: ErrorEmitter,
+      eventName: string,
+      listener: (error: Error) => void
+    ) => void;
+  }
+
+  private attachTaskErrorListener(listener: (error: Error) => void): void {
+    let lastError: unknown;
+    const attachMethodNames: Array<"on" | "addListener"> = [
+      "on",
+      "addListener",
+    ];
+    for (const methodName of attachMethodNames) {
+      try {
+        const attachMethod = this.readErrorEmitterMethodOrThrow(methodName);
+        attachMethod.call(this.errorEmitter, "error", listener);
+        return;
+      } catch (error) {
+        lastError = error;
+      }
+    }
+    throw (
+      lastError ??
+      new Error("errorEmitter listener registration methods are unavailable")
+    );
+  }
+
+  private detachTaskErrorListener(listener: (error: Error) => void): void {
+    let lastError: unknown;
+    const detachMethodNames: Array<"off" | "removeListener"> = [
+      "off",
+      "removeListener",
+    ];
+    for (const methodName of detachMethodNames) {
+      try {
+        const detachMethod = this.readErrorEmitterMethodOrThrow(methodName);
+        detachMethod.call(this.errorEmitter, "error", listener);
+        return;
+      } catch (error) {
+        lastError = error;
+      }
+    }
+    if (this.debug && typeof lastError !== "undefined") {
+      console.warn(
+        `[HyperAgent] Failed to detach task-scoped error listener: ${this.formatLifecycleDiagnostic(
+          lastError
+        )}`
+      );
+    }
+  }
+
+  private async startBrowserProvider(): Promise<Browser> {
+    const startMethod = this.safeReadField(this.browserProvider, "start");
+    if (typeof startMethod !== "function") {
+      throw new HyperagentError(
+        "Browser provider is missing start() method",
+        500
+      );
+    }
+
+    let browser: unknown;
+    try {
+      browser = await (
+        startMethod as (this: unknown) => Promise<unknown>
+      ).call(this.browserProvider);
+    } catch (error) {
+      throw new HyperagentError(
+        `Failed to start browser provider: ${this.formatLifecycleDiagnostic(error)}`,
+        500
+      );
+    }
+
+    if (!browser || typeof browser !== "object") {
+      throw new HyperagentError(
+        "Browser provider returned an invalid browser instance",
+        500
+      );
+    }
+    return browser as Browser;
+  }
+
+  private getBrowserContexts(browser: Browser): BrowserContext[] {
+    const contextsMethod = this.safeReadField(browser, "contexts");
+    if (typeof contextsMethod !== "function") {
+      return [];
+    }
+    try {
+      return Array.from(
+        (contextsMethod as (this: Browser) => BrowserContext[]).call(browser)
+      );
+    } catch (error) {
+      throw new HyperagentError(
+        `Failed to list browser contexts: ${this.formatLifecycleDiagnostic(error)}`,
+        500
+      );
+    }
+  }
+
+  private async createBrowserContext(browser: Browser): Promise<BrowserContext> {
+    const newContextMethod = this.safeReadField(browser, "newContext");
+    if (typeof newContextMethod !== "function") {
+      throw new HyperagentError(
+        "Browser instance is missing newContext() method",
+        500
+      );
+    }
+    let context: unknown;
+    try {
+      context = await (
+        newContextMethod as (
+          this: Browser,
+          options: { viewport: null }
+        ) => Promise<unknown>
+      ).call(browser, {
+        viewport: null,
+      });
+    } catch (error) {
+      throw new HyperagentError(
+        `Failed to create browser context: ${this.formatLifecycleDiagnostic(error)}`,
+        500
+      );
+    }
+    if (!context || typeof context !== "object") {
+      throw new HyperagentError(
+        "Browser newContext() returned an invalid context",
+        500
+      );
+    }
+    return context as BrowserContext;
+  }
+
+  private async resolveInitialBrowserContext(
+    browser: Browser
+  ): Promise<BrowserContext> {
+    const existingContexts =
+      this.browserProviderType === "Hyperbrowser"
+        ? this.getBrowserContexts(browser)
+        : [];
+    if (existingContexts.length > 0 && existingContexts[0]) {
+      return existingContexts[0];
+    }
+    return this.createBrowserContext(browser);
+  }
+
+  private async closeBrowserProvider(): Promise<void> {
+    const closeMethod = this.safeReadField(this.browserProvider, "close");
+    if (typeof closeMethod !== "function") {
+      throw new HyperagentError(
+        "Browser provider is missing close() method",
+        500
+      );
+    }
+    try {
+      await (closeMethod as (this: unknown) => Promise<void>).call(
+        this.browserProvider
+      );
+    } catch (error) {
+      throw new HyperagentError(
+        `Failed to close browser provider: ${this.formatLifecycleDiagnostic(error)}`,
+        500
+      );
+    }
+  }
+
+  private hasBrowserProviderSession(): boolean {
+    const getSessionMethod = this.safeReadField(this.browserProvider, "getSession");
+    if (typeof getSessionMethod !== "function") {
+      return false;
+    }
+    try {
+      return (
+        (getSessionMethod as (this: unknown) => unknown).call(
+          this.browserProvider
+        ) != null
+      );
+    } catch {
+      return false;
+    }
+  }
+
+  private storeTaskActionCache(taskId: string, actionCache: ActionCacheOutput): void {
+    const normalizedTaskId = this.normalizeVariableKey(taskId);
+    if (!normalizedTaskId) {
+      return;
+    }
+    try {
+      this.actionCacheByTaskId[normalizedTaskId] = actionCache;
+    } catch (error) {
+      if (this.debug) {
+        console.warn(
+          `[HyperAgent] Failed to store action cache for task ${normalizedTaskId}: ${this.formatLifecycleDiagnostic(
+            error
+          )}`
+        );
+      }
+      return;
+    }
+
+    try {
+      const currentOrder = Array.isArray(this.actionCacheTaskOrder)
+        ? this.actionCacheTaskOrder
+        : [];
+      const nextOrder = currentOrder.filter(
+        (cachedTaskId) => cachedTaskId !== normalizedTaskId
+      );
+      nextOrder.push(normalizedTaskId);
+
+      while (nextOrder.length > HyperAgent.MAX_ACTION_CACHE_ENTRIES) {
+        const evictedTaskId = nextOrder.shift();
+        if (!evictedTaskId) {
+          continue;
+        }
+        try {
+          delete this.actionCacheByTaskId[evictedTaskId];
+        } catch (error) {
+          if (this.debug) {
+            console.warn(
+              `[HyperAgent] Failed to evict action cache for task ${evictedTaskId}: ${this.formatLifecycleDiagnostic(
+                error
+              )}`
+            );
+          }
+        }
+      }
+      this.actionCacheTaskOrder = nextOrder;
+    } catch (error) {
+      if (this.debug) {
+        console.warn(
+          `[HyperAgent] Failed to update action-cache order for task ${normalizedTaskId}: ${this.formatLifecycleDiagnostic(
+            error
+          )}`
+        );
+      }
+    }
+  }
+
+  private emitTaskErrorSafely(taskError: HyperagentTaskError): void {
+    let listenerCount = 0;
+    try {
+      listenerCount = this.errorEmitter.listenerCount("error");
+    } catch {
+      listenerCount = 0;
+    }
+
+    if (listenerCount === 0) {
+      return;
+    }
+
+    try {
+      this.errorEmitter.emit("error", taskError);
+    } catch (error) {
+      if (this.debug) {
+        console.warn(
+          `[HyperAgent] Failed to emit task error event: ${this.formatLifecycleDiagnostic(
+            error
+          )}`
+        );
+      }
+    }
+  }
+
+  private cleanupTaskLifecycle(taskId: string): void {
+    this.removeTaskErrorForwarder(taskId);
+    try {
+      delete this.taskResults[taskId];
+    } catch (error) {
+      if (this.debug) {
+        console.warn(
+          `[HyperAgent] Failed to clear task result for ${taskId}: ${this.formatLifecycleDiagnostic(
+            error
+          )}`
+        );
+      }
+    }
+    try {
+      delete this.tasks[taskId];
+    } catch (error) {
+      if (this.debug) {
+        console.warn(
+          `[HyperAgent] Failed to clear task state for ${taskId}: ${this.formatLifecycleDiagnostic(
+            error
+          )}`
+        );
+      }
+    }
+  }
+
+  private removeTaskErrorForwarder(taskId: string): void {
+    let forwarder: ((error: Error) => void) | undefined;
+    try {
+      forwarder = this.taskErrorForwarders.get(taskId);
+    } catch {
+      forwarder = undefined;
+    }
+    if (!forwarder) {
+      return;
+    }
+    this.detachTaskErrorListener(forwarder);
+    try {
+      this.taskErrorForwarders.delete(taskId);
+    } catch {
+      // no-op
+    }
+  }
+
+  private clearTaskErrorForwarders(): void {
+    let forwarders: Array<[string, (error: Error) => void]> = [];
+    try {
+      forwarders = Array.from(this.taskErrorForwarders.entries());
+    } catch {
+      forwarders = [];
+    }
+    for (const [taskId] of forwarders) {
+      this.removeTaskErrorForwarder(taskId);
+    }
+  }
+
+  private resetTasksForClose(): void {
+    try {
+      this.tasks = {};
+      return;
+    } catch (error) {
+      if (this.debug) {
+        console.warn(
+          `[HyperAgent] Failed to reset task registry during close: ${this.formatLifecycleDiagnostic(
+            error
+          )}`
+        );
+      }
+    }
+    try {
+      const taskKeys = Object.keys(this.tasks);
+      for (const taskKey of taskKeys) {
+        try {
+          delete this.tasks[taskKey];
+        } catch {
+          // no-op
+        }
+      }
+    } catch {
+      // no-op
+    }
+  }
+
+  private resetTaskResultsForClose(): void {
+    try {
+      this.taskResults = {};
+      return;
+    } catch (error) {
+      if (this.debug) {
+        console.warn(
+          `[HyperAgent] Failed to reset task-result registry during close: ${this.formatLifecycleDiagnostic(
+            error
+          )}`
+        );
+      }
+    }
+    try {
+      const taskResultKeys = Object.keys(this.taskResults);
+      for (const taskResultKey of taskResultKeys) {
+        try {
+          delete this.taskResults[taskResultKey];
+        } catch {
+          // no-op
+        }
+      }
+    } catch {
+      // no-op
+    }
+  }
+
+  private resetActionCacheByTaskForClose(): void {
+    try {
+      this.actionCacheByTaskId = {};
+      return;
+    } catch (error) {
+      if (this.debug) {
+        console.warn(
+          `[HyperAgent] Failed to reset action-cache registry during close: ${this.formatLifecycleDiagnostic(
+            error
+          )}`
+        );
+      }
+    }
+    try {
+      const cacheKeys = Object.keys(this.actionCacheByTaskId);
+      for (const cacheKey of cacheKeys) {
+        try {
+          delete this.actionCacheByTaskId[cacheKey];
+        } catch {
+          // no-op
+        }
+      }
+    } catch {
+      // no-op
+    }
+  }
+
+  private resetActionCacheOrderForClose(): void {
+    try {
+      this.actionCacheTaskOrder = [];
+      return;
+    } catch (error) {
+      if (this.debug) {
+        console.warn(
+          `[HyperAgent] Failed to reset action-cache order during close: ${this.formatLifecycleDiagnostic(
+            error
+          )}`
+        );
+      }
+    }
+    try {
+      if (Array.isArray(this.actionCacheTaskOrder)) {
+        this.actionCacheTaskOrder.length = 0;
+      }
+    } catch {
+      // no-op
+    }
+  }
+
+  private storeTaskResultPromise(
+    taskId: string,
+    result: Promise<AgentTaskOutput>
+  ): void {
+    try {
+      this.taskResults[taskId] = result;
+    } catch (error) {
+      if (this.debug) {
+        console.warn(
+          `[HyperAgent] Failed to track task result promise for ${taskId}: ${this.formatLifecycleDiagnostic(
+            error
+          )}`
+        );
+      }
+    }
+  }
+
+  private getTaskEntriesForClose(): Array<[string, TaskState]> {
+    try {
+      return Object.entries(this.tasks) as Array<[string, TaskState]>;
+    } catch (error) {
+      if (this.debug) {
+        console.warn(
+          `[HyperAgent] Failed to enumerate tasks during close: ${this.formatLifecycleDiagnostic(
+            error
+          )}`
+        );
+      }
+      return [];
+    }
+  }
 
-export class HyperAgent<T extends BrowserProviders = "Local"> {
-  // aiAction configuration constants
-  private static readonly AIACTION_CONFIG = {
-    MAX_RETRIES: 10,
-    RETRY_DELAY_MS: 1000,
-    CLICK_TIMEOUT: 3500,
-    MAX_DEBUG_ELEMENTS_TO_DISPLAY: 20,
-    MAX_DEBUG_ELEMENTS_TO_STORE: 50,
-    MAX_LABEL_LENGTH: 60,
-  };
+  private registerTaskState(taskId: string, taskState: TaskState): void {
+    try {
+      this.tasks[taskId] = taskState;
+    } catch (error) {
+      throw new HyperagentError(
+        `Failed to register task state ${taskId}: ${this.formatLifecycleDiagnostic(error)}`,
+        500
+      );
+    }
+  }
 
-  private llm: HyperAgentLLM;
-  private tasks: Record<string, TaskState> = {};
-  private tokenLimit = 128000;
-  private debug = false;
-  private mcpClient: MCPClient | undefined;
-  private browserProvider: T extends "Hyperbrowser"
-    ? HyperbrowserProvider
-    : LocalBrowserProvider;
-  private browserProviderType: T;
-  private actions: Array<AgentActionDefinition> = [...DEFAULT_ACTIONS];
-  private cdpActionsEnabled: boolean;
-  private actionCacheByTaskId: Record<string, ActionCacheOutput> = {};
+  private getTaskStateById(taskId: string): TaskState | undefined {
+    try {
+      return this.tasks[taskId];
+    } catch (error) {
+      if (this.debug) {
+        console.warn(
+          `[HyperAgent] Failed to read task state ${taskId}: ${this.formatLifecycleDiagnostic(
+            error
+          )}`
+        );
+      }
+      return undefined;
+    }
+  }
 
-  public browser: Browser | null = null;
-  public context: BrowserContext | null = null;
-  private _currentPage: Page | null = null;
-  private _variables: Record<string, HyperVariable> = {};
-  private errorEmitter: ErrorEmitter;
+  private isTaskLifecycleGenerationActive(generation: number): boolean {
+    return generation === this.lifecycleGeneration;
+  }
+
+  private normalizeLifecycleCancelledResult(
+    result: AgentTaskOutput
+  ): AgentTaskOutput {
+    return this.normalizeCancelledTaskResult(
+      result,
+      "Task cancelled because agent was closed"
+    );
+  }
+
+  private normalizeCancelledTaskResult(
+    result: AgentTaskOutput,
+    output: string
+  ): AgentTaskOutput {
+    let normalizedActionCache: ActionCacheOutput;
+    try {
+      const actionCache = result.actionCache;
+      const normalizedTaskId =
+        this.normalizeVariableKey(this.safeReadField(actionCache, "taskId")) ??
+        this.normalizeVariableKey(result.taskId) ??
+        "cancelled-task";
+      const rawCreatedAt = this.safeReadField(actionCache, "createdAt");
+      const createdAt =
+        typeof rawCreatedAt === "string" && rawCreatedAt.trim().length > 0
+          ? rawCreatedAt
+          : new Date().toISOString();
+      const rawSteps = this.safeReadField(actionCache, "steps");
+      let steps: ActionCacheEntry[] = [];
+      try {
+        if (Array.isArray(rawSteps)) {
+          steps = Array.from(rawSteps);
+        } else if (rawSteps && typeof rawSteps === "object") {
+          steps = Array.from(rawSteps as Iterable<ActionCacheEntry>);
+        }
+      } catch {
+        steps = [];
+      }
+      normalizedActionCache = {
+        taskId: normalizedTaskId,
+        createdAt,
+        status: TaskStatus.CANCELLED,
+        steps,
+      };
+    } catch {
+      const fallbackTaskId =
+        this.normalizeVariableKey(result.taskId) ?? "cancelled-task";
+      normalizedActionCache = {
+        taskId: fallbackTaskId,
+        createdAt: new Date().toISOString(),
+        status: TaskStatus.CANCELLED,
+        steps: [],
+      };
+    }
+    return {
+      ...result,
+      status: TaskStatus.CANCELLED,
+      output,
+      actionCache: normalizedActionCache,
+    };
+  }
+
+  private buildCancelledTaskOutput(
+    taskId: string,
+    taskState: TaskState,
+    output: string = "Task cancelled because agent was closed"
+  ): AgentTaskOutput {
+    let steps: TaskState["steps"] = [];
+    try {
+      steps = Array.from(taskState.steps ?? []);
+    } catch {
+      steps = [];
+    }
+    return {
+      taskId,
+      status: TaskStatus.CANCELLED,
+      steps,
+      output,
+      actionCache: {
+        taskId,
+        createdAt: new Date().toISOString(),
+        status: TaskStatus.CANCELLED,
+        steps: [],
+      },
+    };
+  }
+
+  private attachBrowserPageListener(context: BrowserContext): void {
+    const contextOn = this.safeReadField(context, "on");
+    if (typeof contextOn !== "function") {
+      if (this.debug) {
+        console.warn(
+          "[HyperAgent] Failed to attach browser page listener: context.on is unavailable"
+        );
+      }
+      return;
+    }
+    try {
+      (
+        contextOn as (
+          this: BrowserContext,
+          event: "page",
+          listener: () => void
+        ) => void
+      ).call(context, "page", () => {
+        if (this.debug) {
+          console.log("New tab/popup detected");
+        }
+
+        // Note: We used to auto-switch this._currentPage here, but that breaks
+        // scoped page interactions. If a user is awaiting pageA.ai(), and a new
+        // tab opens, we don't want pageA to suddenly become pageB.
+        // The user or the specific task logic should handle tab switching if desired.
+      });
+    } catch (error) {
+      if (this.debug) {
+        console.warn(
+          `[HyperAgent] Failed to attach browser page listener: ${this.formatLifecycleDiagnostic(
+            error
+          )}`
+        );
+      }
+    }
+  }
+
+  private normalizeSingleActionInstruction(value: unknown): string {
+    if (typeof value !== "string") {
+      throw new HyperagentError(
+        "Action instruction must be a non-empty string",
+        400
+      );
+    }
+    const normalized = value.trim();
+    if (normalized.length === 0) {
+      throw new HyperagentError(
+        "Action instruction must be a non-empty string",
+        400
+      );
+    }
+    return normalized;
+  }
+
+  private normalizeRetryCount(
+    value: unknown,
+    fallback: number,
+    max: number = 20
+  ): number {
+    if (typeof value !== "number" || !Number.isFinite(value) || value <= 0) {
+      return fallback;
+    }
+    return Math.min(Math.floor(value), max);
+  }
+
+  private normalizeRetryDelayMs(
+    value: unknown,
+    fallback: number,
+    max: number = 30_000
+  ): number {
+    if (typeof value !== "number" || !Number.isFinite(value) || value < 0) {
+      return fallback;
+    }
+    return Math.min(Math.floor(value), max);
+  }
+
+  private resolveActionPageInput(pageOrGetter: Page | (() => Page)): Page {
+    let pageCandidate: unknown;
+    try {
+      pageCandidate =
+        typeof pageOrGetter === "function" ? pageOrGetter() : pageOrGetter;
+    } catch (error) {
+      throw new HyperagentError(
+        `Failed to resolve action page: ${this.formatHelperDiagnostic(error)}`,
+        400
+      );
+    }
+    if (!pageCandidate || typeof pageCandidate !== "object") {
+      throw new HyperagentError("Failed to resolve action page", 400);
+    }
+    return pageCandidate as Page;
+  }
+
+  private async captureDebugScreenshot(page: Page): Promise<Buffer | null> {
+    let screenshotMethod: unknown;
+    try {
+      screenshotMethod = (page as unknown as Record<string, unknown>).screenshot;
+    } catch {
+      return null;
+    }
+    if (typeof screenshotMethod !== "function") {
+      return null;
+    }
+    try {
+      const screenshot = await (screenshotMethod as (options: {
+        type: string;
+      }) => Promise<Buffer | null>)({ type: "png" });
+      return Buffer.isBuffer(screenshot) ? screenshot : null;
+    } catch {
+      return null;
+    }
+  }
+
+  private getSafeMCPServerIds(): string[] {
+    if (!this.mcpClient) {
+      return [];
+    }
+    try {
+      const serverIds: string[] = [];
+      const seenServerIds = new Set<string>();
+      for (const rawServerId of this.mcpClient.getServerIds()) {
+        const normalizedServerId = this.normalizeMCPServerIdentifier(rawServerId);
+        if (!normalizedServerId || seenServerIds.has(normalizedServerId)) {
+          continue;
+        }
+        seenServerIds.add(normalizedServerId);
+        serverIds.push(normalizedServerId);
+        if (serverIds.length >= HyperAgent.MAX_MCP_SERVER_ITEMS) {
+          break;
+        }
+      }
+      return serverIds;
+    } catch {
+      return [];
+    }
+  }
+
+  private normalizeMCPServerIdentifier(value: unknown): string | null {
+    if (typeof value !== "string") {
+      return null;
+    }
+    const withoutControlChars = Array.from(value, (char) => {
+      const code = char.charCodeAt(0);
+      return (code >= 0 && code < 32) || code === 127 ? " " : char;
+    }).join("");
+    const normalized = withoutControlChars.replace(/\s+/g, " ").trim();
+    if (normalized.length === 0) {
+      return null;
+    }
+    if (normalized.length <= HyperAgent.MAX_MCP_SERVER_IDENTIFIER_CHARS) {
+      return normalized;
+    }
+    const omitted =
+      normalized.length - HyperAgent.MAX_MCP_SERVER_IDENTIFIER_CHARS;
+    return `${normalized.slice(
+      0,
+      HyperAgent.MAX_MCP_SERVER_IDENTIFIER_CHARS
+    )}... [truncated ${omitted} chars]`;
+  }
+
+  private normalizeMCPServerInfoToolNames(value: unknown): string[] {
+    if (!value || typeof value !== "object") {
+      return [];
+    }
+    const iterable = value as Iterable<unknown>;
+    if (typeof iterable[Symbol.iterator] !== "function") {
+      return [];
+    }
+
+    const normalizedToolNames: string[] = [];
+    const seenToolNames = new Set<string>();
+    try {
+      for (const toolName of iterable) {
+        const normalizedToolName = this.normalizeMCPServerIdentifier(toolName);
+        if (!normalizedToolName || seenToolNames.has(normalizedToolName)) {
+          continue;
+        }
+        seenToolNames.add(normalizedToolName);
+        normalizedToolNames.push(normalizedToolName);
+        if (
+          normalizedToolNames.length >= HyperAgent.MAX_MCP_SERVER_TOOL_ITEMS
+        ) {
+          break;
+        }
+      }
+    } catch {
+      return [];
+    }
+    return normalizedToolNames;
+  }
+
+  private getSafeMCPServerInfo(): Array<{
+    id: string;
+    toolCount: number;
+    toolNames: string[];
+  }> {
+    if (!this.mcpClient) {
+      return [];
+    }
+    try {
+      const info = this.mcpClient.getServerInfo();
+      if (!Array.isArray(info)) {
+        return [];
+      }
+      const normalizedInfo: Array<{
+        id: string;
+        toolCount: number;
+        toolNames: string[];
+      }> = [];
+      for (const rawEntry of info) {
+        if (!rawEntry || typeof rawEntry !== "object") {
+          continue;
+        }
+        const normalizedId =
+          this.normalizeMCPServerIdentifier(this.safeReadField(rawEntry, "id")) ??
+          "unknown-server";
+        const normalizedToolNames = this.normalizeMCPServerInfoToolNames(
+          this.safeReadField(rawEntry, "toolNames")
+        );
+        const rawToolCount = this.safeReadField(rawEntry, "toolCount");
+        const normalizedToolCount =
+          typeof rawToolCount === "number" &&
+          Number.isFinite(rawToolCount) &&
+          rawToolCount >= 0
+            ? Math.trunc(rawToolCount)
+            : normalizedToolNames.length;
+        normalizedInfo.push({
+          id: normalizedId,
+          toolCount: Math.max(normalizedToolCount, normalizedToolNames.length),
+          toolNames: normalizedToolNames,
+        });
+        if (normalizedInfo.length >= HyperAgent.MAX_MCP_SERVER_ITEMS) {
+          break;
+        }
+      }
+      return normalizedInfo;
+    } catch {
+      return [];
+    }
+  }
 
   public get currentPage(): HyperPage | null {
     if (this._currentPage) {
@@ -104,7 +1339,8 @@ export class HyperAgent<T extends BrowserProviders = "Local"> {
   }
 
   constructor(params: HyperAgentConfig<T> = {}) {
-    if (!params.llm) {
+    const rawLLM = this.safeReadField(params, "llm");
+    if (!rawLLM) {
       if (process.env.OPENAI_API_KEY) {
         this.llm = createLLMClient({
           provider: "openai",
@@ -114,33 +1350,75 @@ export class HyperAgent<T extends BrowserProviders = "Local"> {
       } else {
         throw new HyperagentError("No LLM provider provided", 400);
       }
-    } else if (typeof params.llm === "object" && "provider" in params.llm) {
+    } else if (
+      typeof rawLLM === "object" &&
+      typeof this.safeReadField(rawLLM, "provider") === "string"
+    ) {
       // It's an LLMConfig
-      this.llm = createLLMClient(params.llm);
-    } else {
+      this.llm = createLLMClient(
+        rawLLM as Parameters<typeof createLLMClient>[0]
+      );
+    } else if (this.isHyperAgentLLMClient(rawLLM)) {
       // It's already a HyperAgentLLM instance
-      this.llm = params.llm;
+      this.llm = rawLLM;
+    } else {
+      throw new HyperagentError(
+        "Invalid llm configuration: expected provider config or HyperAgentLLM client",
+        400
+      );
     }
-    this.browserProviderType = (params.browserProvider ?? "Local") as T;
+    const browserProvider =
+      this.safeReadField(params, "browserProvider") === "Hyperbrowser"
+        ? "Hyperbrowser"
+        : "Local";
+    this.browserProviderType = browserProvider as T;
+    this.debug = this.safeReadField(params, "debug") === true;
+
+    const debugOptions = this.safeReadField(params, "debugOptions");
+    setDebugOptions(
+      debugOptions && typeof debugOptions === "object"
+        ? (debugOptions as Parameters<typeof setDebugOptions>[0])
+        : undefined,
+      this.debug
+    );
 
-    setDebugOptions(params.debugOptions, this.debug);
+    const hyperbrowserConfig = this.safeReadField(params, "hyperbrowserConfig");
+    const localConfig = this.safeReadField(params, "localConfig");
 
-    // TODO(Phase4): This legacy provider branch will be replaced by connector configs.
+    // Provider selection currently supports Local/Hyperbrowser directly.
+    // Long-term connector config abstractions may replace this branch.
     this.browserProvider = (
       this.browserProviderType === "Hyperbrowser"
         ? new HyperbrowserProvider({
-            ...(params.hyperbrowserConfig ?? {}),
-            debug: params.debug,
+            ...(hyperbrowserConfig && typeof hyperbrowserConfig === "object"
+              ? hyperbrowserConfig
+              : {}),
+            debug: this.debug,
           })
-        : new LocalBrowserProvider(params.localConfig)
+        : new LocalBrowserProvider(
+            localConfig && typeof localConfig === "object"
+              ? (localConfig as ConstructorParameters<
+                  typeof LocalBrowserProvider
+                >[0])
+              : undefined
+          )
     ) as T extends "Hyperbrowser" ? HyperbrowserProvider : LocalBrowserProvider;
 
-    if (params.customActions) {
-      params.customActions.forEach(this.registerAction, this);
+    const customActions = this.safeArrayValues<AgentActionDefinition>(
+      this.safeReadField(params, "customActions")
+    );
+    if (customActions.length > 0) {
+      customActions.forEach((action) => {
+        this.registerAction(action);
+      });
     }
 
-    this.debug = params.debug ?? false;
-    this.cdpActionsEnabled = params.cdpActions ?? true;
+    this.cdpActionsEnabled = this.resolveCdpActions(
+      this.safeReadField(params, "cdpActions")
+    );
+    this.filterAdTrackingFrames = this.resolveFilterAdTrackingFrames(
+      this.safeReadField(params, "filterAdTrackingFrames")
+    );
     this.errorEmitter = new ErrorEmitter();
   }
 
@@ -149,32 +1427,65 @@ export class HyperAgent<T extends BrowserProviders = "Local"> {
    * @returns A reference to the current rebrowser-playwright browser instance.
    */
   public async initBrowser(): Promise<Browser> {
+    const initGeneration = this.lifecycleGeneration;
     if (!this.browser) {
-      this.browser = await this.browserProvider.start();
-      if (
-        this.browserProviderType === "Hyperbrowser" &&
-        this.browser.contexts().length > 0
-      ) {
-        this.context = this.browser.contexts()[0];
-      } else {
-        this.context = await this.browser.newContext({
-          viewport: null,
-        });
+      const browser = await this.startBrowserProvider();
+      if (!this.isTaskLifecycleGenerationActive(initGeneration)) {
+        try {
+          await this.closeBrowserProvider();
+        } catch (closeError) {
+          if (this.debug) {
+            console.warn(
+              `[HyperAgent] Failed to close browser provider after stale init: ${this.formatLifecycleDiagnostic(
+                closeError
+              )}`
+            );
+          }
+        }
+        throw new HyperagentError(
+          "Browser initialization cancelled because agent was closed",
+          500
+        );
       }
+      this.browser = browser;
+    }
 
-      // Listen for new pages (tabs/popups)
-      this.context.on("page", () => {
-        if (this.debug) {
-          console.log("New tab/popup detected");
+    if (!this.context) {
+      const activeBrowser = this.browser;
+      if (!activeBrowser) {
+        throw new HyperagentError("No browser found after browser init", 500);
+      }
+      try {
+        this.context = await this.resolveInitialBrowserContext(activeBrowser);
+        if (!this.isTaskLifecycleGenerationActive(initGeneration)) {
+          throw new HyperagentError(
+            "Browser initialization cancelled because agent was closed",
+            500
+          );
+        }
+      } catch (error) {
+        this.browser = null;
+        this.context = null;
+        this._currentPage = null;
+        try {
+          await this.closeBrowserProvider();
+        } catch (closeError) {
+          if (this.debug) {
+            console.warn(
+              `[HyperAgent] Failed to close browser provider after init failure: ${this.formatLifecycleDiagnostic(
+                closeError
+              )}`
+            );
+          }
         }
+        throw error;
+      }
 
-        // Note: We used to auto-switch this._currentPage here, but that breaks
-        // scoped page interactions. If a user is awaiting pageA.ai(), and a new
-        // tab opens, we don't want pageA to suddenly become pageB.
-        // The user or the specific task logic should handle tab switching if desired.
-      });
+      if (!this.context) {
+        throw new HyperagentError("No context found after browser init", 500);
+      }
 
-      return this.browser;
+      this.attachBrowserPageListener(this.context);
     }
     return this.browser;
   }
@@ -186,7 +1497,7 @@ export class HyperAgent<T extends BrowserProviders = "Local"> {
    * @returns
    */
   private getActions(
-    outputSchema?: z.ZodType<any>
+    outputSchema?: z.ZodType<unknown>
   ): Array<AgentActionDefinition> {
     if (outputSchema) {
       return [
@@ -203,7 +1514,7 @@ export class HyperAgent<T extends BrowserProviders = "Local"> {
    * @returns Record of variables
    */
   public getVariables(): Record<string, HyperVariable> {
-    return this._variables;
+    return this.getVariableSnapshot();
   }
 
   /**
@@ -212,7 +1523,18 @@ export class HyperAgent<T extends BrowserProviders = "Local"> {
    * @param value Value of the variable
    */
   public addVariable(variable: HyperVariable): void {
-    this._variables[variable.key] = variable;
+    const key = this.normalizeVariableKey((variable as { key?: unknown })?.key);
+    if (!key) {
+      throw new HyperagentError("Variable key must be a non-empty string", 400);
+    }
+    try {
+      this._variables[key] = variable;
+    } catch (error) {
+      throw new HyperagentError(
+        `Failed to set variable "${key}": ${this.formatHelperDiagnostic(error)}`,
+        500
+      );
+    }
   }
 
   /**
@@ -221,7 +1543,15 @@ export class HyperAgent<T extends BrowserProviders = "Local"> {
    * @returns Value of the variable
    */
   public getVariable(key: string): HyperVariable | undefined {
-    return this._variables[key];
+    const normalizedKey = this.normalizeVariableKey(key);
+    if (!normalizedKey) {
+      return undefined;
+    }
+    try {
+      return this._variables[normalizedKey];
+    } catch {
+      return undefined;
+    }
   }
 
   /**
@@ -229,15 +1559,63 @@ export class HyperAgent<T extends BrowserProviders = "Local"> {
    * @param key Key of the variable
    */
   public deleteVariable(key: string): void {
-    delete this._variables[key];
+    const normalizedKey = this.normalizeVariableKey(key);
+    if (!normalizedKey) {
+      return;
+    }
+    try {
+      delete this._variables[normalizedKey];
+    } catch {
+      // no-op
+    }
   }
 
   public getActionCache(taskId: string): ActionCacheOutput | null {
-    const cache = this.actionCacheByTaskId[taskId];
-    if (!cache) return null;
+    const normalizedTaskId = this.normalizeVariableKey(taskId);
+    if (!normalizedTaskId) {
+      return null;
+    }
+    let cache: unknown;
+    try {
+      cache = this.actionCacheByTaskId[normalizedTaskId];
+    } catch {
+      return null;
+    }
+    if (!cache || typeof cache !== "object") {
+      return null;
+    }
+    const cachedTaskId =
+      this.normalizeVariableKey(this.safeReadField(cache, "taskId")) ??
+      normalizedTaskId;
+    const rawCreatedAt = this.safeReadField(cache, "createdAt");
+    const createdAt =
+      typeof rawCreatedAt === "string" && rawCreatedAt.trim().length > 0
+        ? rawCreatedAt
+        : HyperAgent.DEFAULT_ACTION_CACHE_CREATED_AT;
+    const rawStatus = this.safeReadField(cache, "status");
+    const status =
+      typeof rawStatus === "string" &&
+      HyperAgent.TASK_STATUS_VALUES.has(rawStatus)
+        ? (rawStatus as TaskStatus)
+        : undefined;
+    let steps: ActionCacheOutput["steps"] = [];
+    const rawSteps = this.safeReadField(cache, "steps");
+    try {
+      if (Array.isArray(rawSteps)) {
+        steps = Array.from(rawSteps);
+      } else if (rawSteps && typeof rawSteps === "object") {
+        steps = Array.from(rawSteps as Iterable<ActionCacheEntry>);
+      } else {
+        steps = [];
+      }
+    } catch {
+      steps = [];
+    }
     return {
-      ...cache,
-      steps: [...cache.steps],
+      taskId: cachedTaskId,
+      createdAt,
+      status,
+      steps,
     };
   }
 
@@ -252,7 +1630,16 @@ export class HyperAgent<T extends BrowserProviders = "Local"> {
     if (!this.context) {
       throw new HyperagentError("No context found");
     }
-    return this.context.pages().map(this.setupHyperPage.bind(this), this);
+    let pages: Page[] = [];
+    try {
+      pages = this.getContextPagesOrThrow(this.context);
+    } catch (error) {
+      throw new HyperagentError(
+        `Failed to list pages from context: ${this.formatLifecycleDiagnostic(error)}`,
+        500
+      );
+    }
+    return pages.map(this.setupHyperPage.bind(this), this);
   }
 
   /**
@@ -266,7 +1653,15 @@ export class HyperAgent<T extends BrowserProviders = "Local"> {
     if (!this.context) {
       throw new HyperagentError("No context found");
     }
-    const page = await this.context.newPage();
+    let page: Page;
+    try {
+      page = await this.createContextPageOrThrow(this.context);
+    } catch (error) {
+      throw new HyperagentError(
+        `Failed to create new page: ${this.formatLifecycleDiagnostic(error)}`,
+        500
+      );
+    }
     return this.setupHyperPage(page);
   }
 
@@ -274,26 +1669,63 @@ export class HyperAgent<T extends BrowserProviders = "Local"> {
    * Close the agent and all associated resources
    */
   public async closeAgent(): Promise<void> {
+    this.lifecycleGeneration += 1;
+    this.clearTaskErrorForwarders();
     await disposeAllCDPClients().catch((error) => {
-      console.warn("[HyperAgent] Failed to dispose CDP clients:", error);
+      console.warn(
+        `[HyperAgent] Failed to dispose CDP clients: ${this.formatLifecycleDiagnostic(
+          error
+        )}`
+      );
     });
-    for (const taskId in this.tasks) {
-      const task = this.tasks[taskId];
-      if (!endTaskStatuses.has(task.status)) {
-        task.status = TaskStatus.CANCELLED;
+    for (const [, task] of this.getTaskEntriesForClose()) {
+      const currentStatus = this.readTaskStatus(task, TaskStatus.FAILED);
+      if (!endTaskStatuses.has(currentStatus)) {
+        this.writeTaskStatus(task, TaskStatus.CANCELLED, currentStatus);
       }
     }
 
     if (this.mcpClient) {
-      await this.mcpClient.disconnect();
-      this.mcpClient = undefined;
+      this.unregisterActionsByType(
+        this.getRegisteredMCPActionTypes()
+      );
+      this.clearRegisteredMCPActionTypes();
+      try {
+        await this.mcpClient.disconnect();
+      } catch (error) {
+        console.warn(
+          `[HyperAgent] Failed to disconnect MCP client: ${this.formatLifecycleDiagnostic(
+            error
+          )}`
+        );
+      } finally {
+        this.mcpClient = undefined;
+      }
+    } else {
+      this.unregisterActionsByType(
+        this.getRegisteredMCPActionTypes()
+      );
+      this.clearRegisteredMCPActionTypes();
     }
 
-    if (this.browser) {
-      await this.browserProvider.close();
-      this.browser = null;
-      this.context = null;
+    if (this.browser || this.context || this.hasBrowserProviderSession()) {
+      try {
+        await this.closeBrowserProvider();
+      } catch (error) {
+        console.warn(
+          `[HyperAgent] ${this.formatLifecycleDiagnostic(error)}`
+        );
+      } finally {
+        this.browser = null;
+        this.context = null;
+        this._currentPage = null;
+      }
     }
+    this.resetTasksForClose();
+    this.resetTaskResultsForClose();
+    this.resetActionCacheByTaskForClose();
+    this.resetActionCacheOrderForClose();
+    this._currentPage = null;
   }
 
   /**
@@ -311,27 +1743,41 @@ export class HyperAgent<T extends BrowserProviders = "Local"> {
     // Poll context for new pages to catch any that opened since the last check
     // This handles race conditions where the 'page' event might not have fired yet
     // or where we missed it during a heavy operation.
-    const pages = this.context.pages();
+    const pages = this.getContextPagesSafe(this.context);
     if (pages.length > 0) {
       const lastPage = pages[pages.length - 1];
       // If the last page is different and not closed, switch to it
       // We prefer the newest page as it's likely the result of the user's last action
-      if (lastPage && !lastPage.isClosed() && lastPage !== this._currentPage) {
+      if (
+        lastPage &&
+        !this.safeIsPageClosed(lastPage) &&
+        lastPage !== this._currentPage
+      ) {
         if (this.debug) {
           console.log(
-            `[HyperAgent] Polling detected new page, switching focus: ${lastPage.url()}`
+            `[HyperAgent] Polling detected new page, switching focus: ${this.safeGetPageUrl(
+              lastPage
+            )}`
           );
         }
         this._currentPage = lastPage;
       }
     }
 
-    if (!this.currentPage || this.currentPage.isClosed()) {
-      this._currentPage = await this.context.newPage();
+    const currentPage = this.currentPage;
+    if (!currentPage || this.safeIsPageClosed(currentPage)) {
+      try {
+        this._currentPage = await this.createContextPageOrThrow(this.context);
+      } catch (error) {
+        throw new HyperagentError(
+          `Failed to create current page: ${this.formatLifecycleDiagnostic(error)}`,
+          500
+        );
+      }
 
       return this.setupHyperPage(this._currentPage);
     }
-    return this.currentPage;
+    return currentPage;
   }
 
   /**
@@ -339,33 +1785,129 @@ export class HyperAgent<T extends BrowserProviders = "Local"> {
    * @param taskId ID of the task
    * @returns Task control object
    */
-  private getTaskControl(taskId: string): Task {
-    const taskState = this.tasks[taskId];
-    if (!taskState) {
-      throw new HyperagentError(`Task ${taskId} not found`);
+  private getTaskControl(
+    taskId: string,
+    taskState: TaskState,
+    result: Promise<AgentTaskOutput>,
+    taskLifecycleGeneration: number
+  ): Task {
+    const taskEmitter = new ErrorEmitter();
+    let settledStatus: TaskStatus | null = null;
+    const resolveSettledStatus = (value: unknown): TaskStatus => {
+      const rawStatus = this.safeReadField(value, "status");
+      if (
+        typeof rawStatus === "string" &&
+        HyperAgent.TASK_STATUS_VALUES.has(rawStatus)
+      ) {
+        return rawStatus as TaskStatus;
+      }
+      return this.readTaskStatus(taskState, TaskStatus.FAILED);
+    };
+    const readControlStatus = (): TaskStatus => {
+      if (settledStatus !== null) {
+        return settledStatus;
+      }
+      if (!this.isTaskLifecycleGenerationActive(taskLifecycleGeneration)) {
+        return TaskStatus.CANCELLED;
+      }
+      return this.readTaskStatus(taskState, TaskStatus.FAILED);
+    };
+    const onTaskError = (error: Error): void => {
+      if (!(error instanceof HyperagentTaskError) || error.taskId !== taskId) {
+        return;
+      }
+      let listenerCount = 0;
+      try {
+        listenerCount = taskEmitter.listenerCount("error");
+      } catch {
+        listenerCount = 0;
+      }
+      if (listenerCount === 0) {
+        return;
+      }
+      try {
+        taskEmitter.emit("error", error);
+      } catch (emitError) {
+        if (this.debug) {
+          console.warn(
+            `[HyperAgent] Failed to emit task-scoped error for ${taskId}: ${this.formatLifecycleDiagnostic(
+              emitError
+            )}`
+          );
+        }
+      }
+    };
+    let listenerAttached = false;
+    try {
+      this.attachTaskErrorListener(onTaskError);
+      listenerAttached = true;
+      this.taskErrorForwarders.set(taskId, onTaskError);
+    } catch (error) {
+      if (listenerAttached) {
+        this.detachTaskErrorListener(onTaskError);
+      }
+      if (this.debug) {
+        console.warn(
+          `[HyperAgent] Failed to register task-scoped error listener for ${taskId}: ${this.formatLifecycleDiagnostic(
+            error
+          )}`
+        );
+      }
     }
+    void result
+      .then((value) => {
+        settledStatus = resolveSettledStatus(value);
+      })
+      .catch(() => {
+        settledStatus = this.readTaskStatus(taskState, TaskStatus.FAILED);
+      })
+      .finally(() => {
+        if (settledStatus === null) {
+          settledStatus = this.readTaskStatus(taskState, TaskStatus.FAILED);
+        }
+        this.removeTaskErrorForwarder(taskId);
+      })
+      .catch(() => undefined);
+
     return {
       id: taskId,
-      getStatus: () => taskState.status,
+      getStatus: () => readControlStatus(),
       pause: () => {
-        if (taskState.status === TaskStatus.RUNNING) {
-          taskState.status = TaskStatus.PAUSED;
+        const status = readControlStatus();
+        if (settledStatus !== null) {
+          return status;
         }
-        return taskState.status;
+        if (status === TaskStatus.RUNNING) {
+          return this.writeTaskStatus(taskState, TaskStatus.PAUSED, status);
+        }
+        return status;
       },
       resume: () => {
-        if (taskState.status === TaskStatus.PAUSED) {
-          taskState.status = TaskStatus.RUNNING;
+        const status = readControlStatus();
+        if (settledStatus !== null) {
+          return status;
+        }
+        if (status === TaskStatus.PAUSED) {
+          return this.writeTaskStatus(taskState, TaskStatus.RUNNING, status);
         }
-        return taskState.status;
+        return status;
       },
       cancel: () => {
-        if (taskState.status !== TaskStatus.COMPLETED) {
-          taskState.status = TaskStatus.CANCELLED;
+        const status = readControlStatus();
+        if (settledStatus !== null) {
+          return status;
         }
-        return taskState.status;
+        if (
+          status === TaskStatus.PENDING ||
+          status === TaskStatus.RUNNING ||
+          status === TaskStatus.PAUSED
+        ) {
+          return this.writeTaskStatus(taskState, TaskStatus.CANCELLED, status);
+        }
+        return status;
       },
-      emitter: this.errorEmitter,
+      result,
+      emitter: taskEmitter,
     };
   }
 
@@ -381,7 +1923,9 @@ export class HyperAgent<T extends BrowserProviders = "Local"> {
     params?: TaskParams,
     initPage?: Page
   ): Promise<Task> {
+    const normalizedTask = this.normalizeSingleActionInstruction(task);
     const taskId = uuidv4();
+    const taskLifecycleGeneration = this.lifecycleGeneration;
     let activeTaskPage = initPage || (await this.getCurrentPage());
 
     // Follow new tabs opened by the current active page
@@ -391,7 +1935,9 @@ export class HyperAgent<T extends BrowserProviders = "Local"> {
         if (opener === activeTaskPage) {
           if (this.debug) {
             console.log(
-              `[HyperAgent] Task following new tab: ${newPage.url()}`
+              `[HyperAgent] Task following new tab: ${this.safeGetPageUrl(
+                newPage
+              )}`
             );
           }
           activeTaskPage = newPage;
@@ -400,53 +1946,134 @@ export class HyperAgent<T extends BrowserProviders = "Local"> {
         // Ignore
       }
     };
-    this.context?.on("page", onPage);
-    const cleanup = () => this.context?.off("page", onPage);
+    const cleanup = this.attachPageListenerForTask(onPage);
 
     const taskState: TaskState = {
       id: taskId,
-      task: task,
+      task: normalizedTask,
       status: TaskStatus.PENDING,
       startingPage: activeTaskPage,
       steps: [],
     };
-    this.tasks[taskId] = taskState;
+    try {
+      this.registerTaskState(taskId, taskState);
+    } catch (error) {
+      cleanup();
+      throw error;
+    }
     const mergedParams = params ?? {};
-    runAgentTask(
-      {
-        llm: this.llm,
-        actions: this.getActions(mergedParams.outputSchema),
-        tokenLimit: this.tokenLimit,
-        debug: this.debug,
-        mcpClient: this.mcpClient,
-        variables: this._variables,
-        cdpActions: this.cdpActionsEnabled,
-        activePage: async () => activeTaskPage,
-      },
-      taskState,
-      mergedParams
-    )
-      .then((result) => {
-        this.actionCacheByTaskId[taskId] = result.actionCache;
-        cleanup();
-      })
-      .catch((error: Error) => {
-        cleanup();
-        // Retrieve the correct state to update
-        const failedTaskState = this.tasks[taskId];
-        if (failedTaskState) {
-          failedTaskState.status = TaskStatus.FAILED;
-          failedTaskState.error = error.message;
-          // Emit error on the central emitter, including the taskId
-          this.errorEmitter.emit("error", error);
-        } else {
-          // Fallback if task state somehow doesn't exist
-          console.error(
-            `Task state ${taskId} not found during error handling.`
+    const cdpActions = this.resolveCdpActions(
+      this.safeReadField(mergedParams, "cdpActions")
+    );
+    const filterAdTrackingFrames = this.resolveFilterAdTrackingFrames(
+      this.safeReadField(mergedParams, "filterAdTrackingFrames")
+    );
+    let taskResult: Promise<AgentTaskOutput>;
+    try {
+      taskResult = runAgentTask(
+        {
+          llm: this.llm,
+          actions: this.getActions(mergedParams.outputSchema),
+          tokenLimit: this.tokenLimit,
+          debug: this.debug,
+          mcpClient: this.mcpClient,
+          variables: this._variables,
+          cdpActions,
+          filterAdTrackingFrames,
+          activePage: async () => activeTaskPage,
+        },
+        taskState,
+        mergedParams
+      )
+        .then((result) => {
+          cleanup();
+          if (!this.isTaskLifecycleGenerationActive(taskLifecycleGeneration)) {
+            this.writeTaskStatus(taskState, TaskStatus.CANCELLED, TaskStatus.CANCELLED);
+            return this.normalizeLifecycleCancelledResult(result);
+          }
+          const currentStatus = this.readTaskStatus(taskState, TaskStatus.FAILED);
+          if (currentStatus === TaskStatus.CANCELLED) {
+            return this.normalizeCancelledTaskResult(
+              result,
+              "Task was cancelled"
+            );
+          }
+          this.storeTaskActionCache(taskId, result.actionCache);
+          return result;
+        })
+        .catch((error: unknown) => {
+          cleanup();
+          // Retrieve the correct state to update
+          const failedTaskState = this.getTaskStateById(taskId);
+          const normalizedTaskError =
+            error instanceof Error
+              ? error
+              : new Error(this.formatHelperDiagnostic(error));
+          const taskFailureError =
+            new HyperagentTaskError(taskId, normalizedTaskError);
+          const lifecycleActive = this.isTaskLifecycleGenerationActive(
+            taskLifecycleGeneration
           );
-        }
-      });
-    return this.getTaskControl(taskId);
+          if (failedTaskState) {
+            const currentStatus = this.readTaskStatus(
+              failedTaskState,
+              TaskStatus.FAILED
+            );
+            const nextStatus =
+              currentStatus === TaskStatus.CANCELLED
+                ? TaskStatus.CANCELLED
+                : TaskStatus.FAILED;
+            this.writeTaskStatus(failedTaskState, nextStatus);
+            if (nextStatus === TaskStatus.CANCELLED) {
+              return lifecycleActive
+                ? this.buildCancelledTaskOutput(
+                    taskId,
+                    failedTaskState,
+                    "Task was cancelled"
+                  )
+                : this.buildCancelledTaskOutput(taskId, failedTaskState);
+            }
+            failedTaskState.error = taskFailureError.cause.message;
+            // Emit error on the central emitter, including the taskId
+            this.emitTaskErrorSafely(taskFailureError);
+          } else {
+            if (!lifecycleActive) {
+              return this.buildCancelledTaskOutput(taskId, taskState);
+            }
+            this.writeTaskStatus(taskState, TaskStatus.FAILED);
+            taskState.error = taskFailureError.cause.message;
+            this.emitTaskErrorSafely(taskFailureError);
+            if (lifecycleActive) {
+              if (this.debug) {
+                console.warn(
+                  `[HyperAgent] Task state ${taskId} not found during error handling.`
+                );
+              }
+            }
+          }
+          throw taskFailureError;
+        })
+        .finally(() => {
+          this.cleanupTaskLifecycle(taskId);
+        });
+    } catch (error) {
+      cleanup();
+      const currentStatus = this.readTaskStatus(taskState, TaskStatus.FAILED);
+      const nextStatus =
+        currentStatus === TaskStatus.CANCELLED
+          ? TaskStatus.CANCELLED
+          : TaskStatus.FAILED;
+      this.writeTaskStatus(taskState, nextStatus);
+      this.cleanupTaskLifecycle(taskId);
+      throw error;
+    }
+    this.storeTaskResultPromise(taskId, taskResult);
+    return this.getTaskControl(
+      taskId,
+      taskState,
+      taskResult,
+      taskLifecycleGeneration
+    );
   }
 
   /**
@@ -461,7 +2088,9 @@ export class HyperAgent<T extends BrowserProviders = "Local"> {
     params?: TaskParams,
     initPage?: Page
   ): Promise<AgentTaskOutput> {
+    const normalizedTask = this.normalizeSingleActionInstruction(task);
     const taskId = uuidv4();
+    const taskLifecycleGeneration = this.lifecycleGeneration;
     let activeTaskPage = initPage || (await this.getCurrentPage());
 
     // Follow new tabs opened by the current active page
@@ -471,7 +2100,9 @@ export class HyperAgent<T extends BrowserProviders = "Local"> {
         if (opener === activeTaskPage) {
           if (this.debug) {
             console.log(
-              `[HyperAgent] Task following new tab: ${newPage.url()}`
+              `[HyperAgent] Task following new tab: ${this.safeGetPageUrl(
+                newPage
+              )}`
             );
           }
           activeTaskPage = newPage;
@@ -480,19 +2111,30 @@ export class HyperAgent<T extends BrowserProviders = "Local"> {
         // Ignore
       }
     };
-    this.context?.on("page", onPage);
+    const cleanup = this.attachPageListenerForTask(onPage);
 
     const taskState: TaskState = {
       id: taskId,
-      task: task,
+      task: normalizedTask,
       status: TaskStatus.PENDING,
       startingPage: activeTaskPage,
       steps: [],
     };
-    this.tasks[taskId] = taskState;
+    try {
+      this.registerTaskState(taskId, taskState);
+    } catch (error) {
+      cleanup();
+      throw error;
+    }
     try {
       const mergedParams = params ?? {};
-      const result = await runAgentTask(
+      const cdpActions = this.resolveCdpActions(
+        this.safeReadField(mergedParams, "cdpActions")
+      );
+      const filterAdTrackingFrames = this.resolveFilterAdTrackingFrames(
+        this.safeReadField(mergedParams, "filterAdTrackingFrames")
+      );
+      let result = await runAgentTask(
         {
           llm: this.llm,
           actions: this.getActions(mergedParams?.outputSchema),
@@ -500,19 +2142,50 @@ export class HyperAgent<T extends BrowserProviders = "Local"> {
           debug: this.debug,
           mcpClient: this.mcpClient,
           variables: this._variables,
-          cdpActions: this.cdpActionsEnabled,
+          cdpActions,
+          filterAdTrackingFrames,
           activePage: async () => activeTaskPage,
         },
         taskState,
         mergedParams
       );
-      this.context?.off("page", onPage);
-      this.actionCacheByTaskId[taskId] = result.actionCache;
+      cleanup();
+      if (!this.isTaskLifecycleGenerationActive(taskLifecycleGeneration)) {
+        this.writeTaskStatus(taskState, TaskStatus.CANCELLED, TaskStatus.CANCELLED);
+        result = this.normalizeLifecycleCancelledResult(result);
+        this.cleanupTaskLifecycle(taskId);
+        return result;
+      }
+      const currentStatus = this.readTaskStatus(taskState, TaskStatus.FAILED);
+      if (currentStatus === TaskStatus.CANCELLED) {
+        result = this.normalizeCancelledTaskResult(result, "Task was cancelled");
+        this.cleanupTaskLifecycle(taskId);
+        return result;
+      }
+      this.storeTaskActionCache(taskId, result.actionCache);
+      this.cleanupTaskLifecycle(taskId);
       return result;
     } catch (error) {
-      this.context?.off("page", onPage);
-      taskState.status = TaskStatus.FAILED;
-      throw error;
+      cleanup();
+      const currentStatus = this.readTaskStatus(taskState, TaskStatus.FAILED);
+      const nextStatus =
+        currentStatus === TaskStatus.CANCELLED
+          ? TaskStatus.CANCELLED
+          : TaskStatus.FAILED;
+      this.writeTaskStatus(taskState, nextStatus);
+      if (nextStatus === TaskStatus.CANCELLED) {
+        const lifecycleActive = this.isTaskLifecycleGenerationActive(
+          taskLifecycleGeneration
+        );
+        this.cleanupTaskLifecycle(taskId);
+        return lifecycleActive
+          ? this.buildCancelledTaskOutput(taskId, taskState, "Task was cancelled")
+          : this.buildCancelledTaskOutput(taskId, taskState);
+      }
+      this.cleanupTaskLifecycle(taskId);
+      throw error instanceof Error
+        ? error
+        : new Error(this.formatHelperDiagnostic(error));
     }
   }
 
@@ -522,312 +2195,558 @@ export class HyperAgent<T extends BrowserProviders = "Local"> {
     params?: RunFromActionCacheParams
   ): Promise<ActionCacheReplayResult> {
     const replayId = uuidv4();
-    const maxXPathRetries = params?.maxXPathRetries ?? 3;
-    const debug = params?.debug ?? this.debug;
-    const getPage = () =>
-      typeof pageOrGetter === "function" ? pageOrGetter() : pageOrGetter;
+    const replayLifecycleGeneration = this.lifecycleGeneration;
+    const rawMaxXPathRetries = this.safeReadField(params, "maxXPathRetries");
+    const maxXPathRetries = this.normalizeRetryCount(
+      rawMaxXPathRetries,
+      3,
+      20
+    );
+    const filterAdTrackingFrames = this.resolveFilterAdTrackingFrames(
+      this.safeReadField(params, "filterAdTrackingFrames")
+    );
+    const rawDebug = this.safeReadField(params, "debug");
+    const debug = typeof rawDebug === "boolean" ? rawDebug : this.debug;
+    const cdpActions = this.resolveCdpActions(
+      this.safeReadField(params, "cdpActions")
+    );
+    const sourceTaskId =
+      this.normalizeVariableKey(this.safeReadField(cache, "taskId")) ??
+      "unknown-task";
+    const shouldWriteReplayDebug = (): boolean =>
+      debug && this.isTaskLifecycleGenerationActive(replayLifecycleGeneration);
+    const formatReplayDiagnostic = (value: unknown): string => {
+      const normalized = Array.from(formatUnknownError(value), (char) => {
+        const code = char.charCodeAt(0);
+        return (code >= 0 && code < 32) || code === 127 ? " " : char;
+      })
+        .join("")
+        .replace(/\s+/g, " ")
+        .trim();
+      const fallback = normalized.length > 0 ? normalized : "unknown error";
+      if (fallback.length <= HyperAgent.MAX_REPLAY_DIAGNOSTIC_CHARS) {
+        return fallback;
+      }
+      const omitted = fallback.length - HyperAgent.MAX_REPLAY_DIAGNOSTIC_CHARS;
+      return `${fallback.slice(
+        0,
+        HyperAgent.MAX_REPLAY_DIAGNOSTIC_CHARS
+      )}... [truncated ${omitted} chars]`;
+    };
+    const safeReadStepField = (step: unknown, key: string): unknown => {
+      if (!step || (typeof step !== "object" && typeof step !== "function")) {
+        return undefined;
+      }
+      try {
+        return (step as Record<string, unknown>)[key];
+      } catch {
+        return undefined;
+      }
+    };
+    const getStepIndexValue = (step: unknown): number => {
+      const value = safeReadStepField(step, "stepIndex");
+      return typeof value === "number" ? value : Number.NaN;
+    };
+    const sanitizeReplayIdentifier = (
+      value: unknown,
+      fallback: string
+    ): string => {
+      const raw = typeof value === "string" ? value : formatUnknownError(value);
+      const withoutControlChars = Array.from(raw, (char) => {
+        const code = char.charCodeAt(0);
+        return (code >= 0 && code < 32) || code === 127 ? " " : char;
+      }).join("");
+      const normalized = withoutControlChars.replace(/\s+/g, " ").trim();
+      if (normalized.length === 0) {
+        return fallback;
+      }
+      if (normalized.length <= HyperAgent.MAX_REPLAY_IDENTIFIER_CHARS) {
+        return normalized;
+      }
+      const omitted =
+        normalized.length - HyperAgent.MAX_REPLAY_IDENTIFIER_CHARS;
+      return `${normalized.slice(
+        0,
+        HyperAgent.MAX_REPLAY_IDENTIFIER_CHARS
+      )}... [truncated ${omitted} chars]`;
+    };
+    const getActionType = (step: unknown): string => {
+      const value = safeReadStepField(step, "actionType");
+      return sanitizeReplayIdentifier(value, "unknown-action");
+    };
+    const readCacheSteps = (): {
+      steps: unknown[];
+      omittedFromRead: number;
+      omittedIsLowerBound: boolean;
+    } => {
+      const maxReadableSteps = HyperAgent.MAX_REPLAY_STEPS + 1;
+      const steps = (cache as { steps?: unknown })?.steps;
+      if (Array.isArray(steps)) {
+        const totalStepCount = steps.length;
+        const limitedSteps = steps.slice(0, maxReadableSteps);
+        return {
+          steps: [...limitedSteps],
+          omittedFromRead: Math.max(0, totalStepCount - limitedSteps.length),
+          omittedIsLowerBound: false,
+        };
+      }
+      if (!steps) {
+        return {
+          steps: [],
+          omittedFromRead: 0,
+          omittedIsLowerBound: false,
+        };
+      }
+      const limitedSteps: unknown[] = [];
+      let omittedIsLowerBound = false;
+      for (const step of steps as Iterable<unknown>) {
+        if (limitedSteps.length < maxReadableSteps) {
+          limitedSteps.push(step);
+          continue;
+        }
+        omittedIsLowerBound = true;
+        break;
+      }
+      return {
+        steps: limitedSteps,
+        omittedFromRead: omittedIsLowerBound ? 1 : 0,
+        omittedIsLowerBound,
+      };
+    };
 
     const stepsResult: ActionCacheReplayResult["steps"] = [];
     let replayStatus: TaskStatus.COMPLETED | TaskStatus.FAILED =
       TaskStatus.COMPLETED;
+    const getSafeStepIndex = (value: number): number =>
+      Number.isFinite(value) ? value : -1;
+    const getSortStepIndex = (value: number): number =>
+      Number.isFinite(value) ? value : Number.MAX_SAFE_INTEGER;
+    const truncateReplayOutput = (value: string): string => {
+      if (value.length <= HyperAgent.MAX_REPLAY_OUTPUT_CHARS) {
+        return value;
+      }
+      const omitted = value.length - HyperAgent.MAX_REPLAY_OUTPUT_CHARS;
+      return `${value.slice(
+        0,
+        HyperAgent.MAX_REPLAY_OUTPUT_CHARS
+      )}... [truncated ${omitted} chars]`;
+    };
+    const sanitizeReplayOutput = (value: string): string => {
+      if (value.length === 0) {
+        return value;
+      }
+      const withoutControlChars = Array.from(value, (char) => {
+        const code = char.charCodeAt(0);
+        return (code >= 0 && code < 32) || code === 127 ? " " : char;
+      }).join("");
+      return withoutControlChars
+        .replace(/\s+/g, " ")
+        .trim();
+    };
+    const normalizeReplayOutput = (
+      output: unknown,
+      isSuccess: boolean
+    ): string => {
+      if (typeof output === "string") {
+        return truncateReplayOutput(sanitizeReplayOutput(output));
+      }
+      if (typeof output === "undefined") {
+        return isSuccess ? "Completed" : "Failed to execute cached action";
+      }
+      return truncateReplayOutput(sanitizeReplayOutput(formatUnknownError(output)));
+    };
+    const readReplayResultStatus = (result: TaskOutput): TaskStatus => {
+      const rawStatus = this.safeReadField(result, "status");
+      if (
+        typeof rawStatus === "string" &&
+        HyperAgent.TASK_STATUS_VALUES.has(rawStatus)
+      ) {
+        return rawStatus as TaskStatus;
+      }
+      return TaskStatus.FAILED;
+    };
+    const readReplayResultOutput = (result: TaskOutput): unknown =>
+      this.safeReadField(result, "output");
+    const readReplayResultMeta = (
+      result: TaskOutput
+    ): Record<string, unknown> | null => {
+      const rawMeta = this.safeReadField(result, "replayStepMeta");
+      if (!rawMeta || typeof rawMeta !== "object") {
+        return null;
+      }
+      return rawMeta as Record<string, unknown>;
+    };
+    const readReplayMetaField = (meta: unknown, key: string): unknown => {
+      if (!meta || typeof meta !== "object") {
+        return undefined;
+      }
+      try {
+        return (meta as Record<string, unknown>)[key];
+      } catch {
+        return undefined;
+      }
+    };
+    const recordReplayStep = (
+      step: unknown,
+      result: TaskOutput
+    ): boolean => {
+      const finalMeta = readReplayResultMeta(result);
+      const finalStatus = readReplayResultStatus(result);
+      const finalSuccess = finalStatus === TaskStatus.COMPLETED;
+      const safeStepIndex = getSafeStepIndex(getStepIndexValue(step));
+      const usedCachedAction =
+        readReplayMetaField(finalMeta, "usedCachedAction") === true;
+      const fallbackUsed = readReplayMetaField(finalMeta, "fallbackUsed") === true;
+      const rawRetries = readReplayMetaField(finalMeta, "retries");
+      const retries =
+        typeof rawRetries === "number" &&
+        Number.isFinite(rawRetries) &&
+        rawRetries > 0
+          ? rawRetries
+          : 0;
+      const rawCachedXPath = readReplayMetaField(finalMeta, "cachedXPath");
+      const cachedXPath =
+        typeof rawCachedXPath === "string" ? rawCachedXPath : null;
+      const rawFallbackXPath = readReplayMetaField(finalMeta, "fallbackXPath");
+      const fallbackXPath =
+        typeof rawFallbackXPath === "string" ? rawFallbackXPath : null;
+      const rawFallbackElementId = readReplayMetaField(
+        finalMeta,
+        "fallbackElementId"
+      );
+      const fallbackElementId =
+        typeof rawFallbackElementId === "string" ? rawFallbackElementId : null;
+
+      stepsResult.push({
+        stepIndex: safeStepIndex,
+        actionType: getActionType(step),
+        usedXPath: usedCachedAction,
+        fallbackUsed,
+        cachedXPath,
+        fallbackXPath,
+        fallbackElementId,
+        retries,
+        success: finalSuccess,
+        message: normalizeReplayOutput(
+          readReplayResultOutput(result),
+          finalSuccess
+        ),
+      });
 
-    /**
-     * Type-safe dispatch for HyperPage perform* methods.
-     * Explicitly routes to the correct method with proper typing.
-     *
-     * Methods that require a value argument (second param): type, fill, press, selectOptionFromDropdown, scrollToPercentage
-     * Methods with only xpath and options: click, hover, check, uncheck, scrollToElement, nextChunk, prevChunk
-     */
-    const dispatchPerformHelper = (
-      hp: HyperPage,
-      method: string,
-      xpath: string,
-      value: string | undefined,
-      options: PerformOptions
-    ): Promise<TaskOutput> => {
-      switch (method) {
-        case "click":
-          return hp.performClick(xpath, options);
-        case "hover":
-          return hp.performHover(xpath, options);
-        case "type":
-          return hp.performType(xpath, value ?? "", options);
-        case "fill":
-          return hp.performFill(xpath, value ?? "", options);
-        case "press":
-          return hp.performPress(xpath, value ?? "", options);
-        case "selectOptionFromDropdown":
-          return hp.performSelectOption(xpath, value ?? "", options);
-        case "check":
-          return hp.performCheck(xpath, options);
-        case "uncheck":
-          return hp.performUncheck(xpath, options);
-        case "scrollToElement":
-          return hp.performScrollToElement(xpath, options);
-        case "scrollToPercentage":
-          return hp.performScrollToPercentage(xpath, value ?? "", options);
-        case "nextChunk":
-          return hp.performNextChunk(xpath, options);
-        case "prevChunk":
-          return hp.performPrevChunk(xpath, options);
-        default:
-          throw new Error(`Unknown perform helper method: ${method}`);
+      if (!finalSuccess) {
+        replayStatus = TaskStatus.FAILED;
       }
+      return finalSuccess;
     };
 
-    /** Set of valid method names that can be dispatched */
-    const validHelperMethods = new Set([
-      "click",
-      "fill",
-      "type",
-      "press",
-      "selectOptionFromDropdown",
-      "check",
-      "uncheck",
-      "hover",
-      "scrollToElement",
-      "scrollToPercentage",
-      "nextChunk",
-      "prevChunk",
-    ]);
-
-    for (const step of [...cache.steps].sort(
-      (a, b) => a.stepIndex - b.stepIndex
-    )) {
-      const page = getPage();
-      const hyperPage = page as HyperPage;
-      let result: TaskOutput;
+    const getReplayInstruction = (instruction: unknown): string | null => {
+      if (typeof instruction !== "string") {
+        return null;
+      }
+      const trimmed = instruction?.trim();
+      return trimmed && trimmed.length > 0 ? trimmed : null;
+    };
 
-      if (step.actionType === "goToUrl") {
-        const url =
-          (step.arguments && step.arguments[0]) ||
-          (step.actionParams as any)?.url ||
-          "";
-        if (!url || typeof url !== "string") {
-          result = {
-            taskId: cache.taskId,
-            status: TaskStatus.FAILED,
-            steps: [],
-            output: "Missing URL for goToUrl",
-          };
-        } else {
-          await hyperPage.goto(url, { waitUntil: "domcontentloaded" });
-          await waitForSettledDOM(hyperPage);
-          markDomSnapshotDirty(hyperPage);
-          result = {
-            taskId: cache.taskId,
-            status: TaskStatus.COMPLETED,
-            steps: [],
-            output: `Navigated to ${url}`,
-            replayStepMeta: {
-              usedCachedAction: true,
-              fallbackUsed: false,
-              retries: 0,
-              cachedXPath: null,
-              fallbackXPath: null,
-              fallbackElementId: null,
-            },
-          };
-        }
-      } else if (step.actionType === "complete") {
-        result = {
-          taskId: cache.taskId,
-          status: TaskStatus.COMPLETED,
-          steps: [],
-          output: "Task Complete",
-          replayStepMeta: {
-            usedCachedAction: true,
+    let sortedSteps: unknown[] = [];
+    let omittedReplaySteps = 0;
+    let omittedReplayStepsIsLowerBound = false;
+    try {
+      const readResult = readCacheSteps();
+      sortedSteps = readResult.steps.sort(
+        (a, b) =>
+          getSortStepIndex(getStepIndexValue(a)) -
+          getSortStepIndex(getStepIndexValue(b))
+      );
+      omittedReplaySteps = readResult.omittedFromRead;
+      omittedReplayStepsIsLowerBound = readResult.omittedIsLowerBound;
+      if (sortedSteps.length > HyperAgent.MAX_REPLAY_STEPS) {
+        omittedReplaySteps += sortedSteps.length - HyperAgent.MAX_REPLAY_STEPS;
+        sortedSteps = sortedSteps.slice(0, HyperAgent.MAX_REPLAY_STEPS);
+      }
+    } catch (error) {
+      const replayResult: ActionCacheReplayResult = {
+        replayId,
+        sourceTaskId,
+        steps: [
+          {
+            stepIndex: -1,
+            actionType: "unknown-action",
+            usedXPath: false,
             fallbackUsed: false,
-            retries: 0,
             cachedXPath: null,
             fallbackXPath: null,
             fallbackElementId: null,
-          },
-        };
-      } else if (step.actionType === "refreshPage") {
-        await hyperPage.reload({ waitUntil: "domcontentloaded" });
-        await waitForSettledDOM(hyperPage);
-        markDomSnapshotDirty(hyperPage);
-        result = {
-          taskId: cache.taskId,
-          status: TaskStatus.COMPLETED,
-          steps: [],
-          output: "Page refreshed",
-          actionCache: {
-            taskId: cache.taskId,
-            createdAt: cache.createdAt,
-            status: TaskStatus.COMPLETED,
-            steps: [],
-          },
-          replayStepMeta: {
-            usedCachedAction: true,
-            fallbackUsed: false,
             retries: 0,
-            cachedXPath: null,
-            fallbackXPath: null,
-            fallbackElementId: null,
+            success: false,
+            message: `Failed to read cached steps: ${formatReplayDiagnostic(
+              error
+            )}`,
           },
-        };
-      } else if (step.actionType === "wait") {
-        const durationRaw =
-          (step.arguments && step.arguments[0]) ||
-          (step.actionParams as any)?.duration;
-        const durationMs =
-          typeof durationRaw === "number"
-            ? durationRaw
-            : Number.parseInt(String(durationRaw ?? ""), 10);
-        const waitMs = Number.isFinite(durationMs) ? durationMs : 1000;
-        await hyperPage.waitForTimeout(waitMs);
+        ],
+        status: TaskStatus.FAILED,
+      };
+      if (shouldWriteReplayDebug()) {
+        try {
+          const debugDir = "debug/action-cache";
+          fs.mkdirSync(debugDir, { recursive: true });
+          fs.writeFileSync(
+            `${debugDir}/replay-${replayId}.json`,
+            JSON.stringify(replayResult, null, 2)
+          );
+        } catch (debugError) {
+          console.error(
+            `[runFromActionCache] Failed to write replay debug: ${formatReplayDiagnostic(
+              debugError
+            )}`
+          );
+        }
+      }
+      return replayResult;
+    }
+
+    let replayStoppedByLifecycle = false;
+    for (const step of sortedSteps) {
+      if (!this.isTaskLifecycleGenerationActive(replayLifecycleGeneration)) {
+        replayStatus = TaskStatus.FAILED;
+        replayStoppedByLifecycle = true;
+        stepsResult.push({
+          stepIndex: getSafeStepIndex(getStepIndexValue(step)),
+          actionType: getActionType(step),
+          usedXPath: false,
+          fallbackUsed: false,
+          cachedXPath: null,
+          fallbackXPath: null,
+          fallbackElementId: null,
+          retries: 0,
+          success: false,
+          message: "Replay stopped because agent was closed",
+        });
+        break;
+      }
+      let result: TaskOutput;
+      let attemptedCachedAction = false;
+      const actionType = getActionType(step);
+      const instruction = getReplayInstruction(
+        safeReadStepField(step, "instruction")
+      );
+      const rawArguments = safeReadStepField(step, "arguments");
+      const stepArguments =
+        Array.isArray(rawArguments) && rawArguments.length > 0
+          ? rawArguments
+          : [];
+      const normalizedStepArguments: Array<string | number> = stepArguments
+        .filter(
+          (value): value is string | number =>
+            typeof value === "string" || typeof value === "number"
+        )
+        .slice(0, 20);
+      const rawActionParams = safeReadStepField(step, "actionParams");
+      const stepActionParams =
+        rawActionParams && typeof rawActionParams === "object"
+          ? (rawActionParams as Record<string, unknown>)
+          : undefined;
+      const stepXPath =
+        typeof safeReadStepField(step, "xpath") === "string"
+          ? (safeReadStepField(step, "xpath") as string)
+          : null;
+      const stepFrameIndex =
+        typeof safeReadStepField(step, "frameIndex") === "number"
+          ? (safeReadStepField(step, "frameIndex") as number)
+          : null;
+      let hyperPage: HyperPage;
+      try {
+        const page = this.resolveActionPageInput(pageOrGetter);
+        hyperPage = page as HyperPage;
+      } catch (error) {
         result = {
-          taskId: cache.taskId,
-          status: TaskStatus.COMPLETED,
+          taskId: sourceTaskId,
+          status: TaskStatus.FAILED,
           steps: [],
-          output: `Waited ${waitMs}ms`,
-          actionCache: {
-            taskId: cache.taskId,
-            createdAt: cache.createdAt,
-            status: TaskStatus.COMPLETED,
-            steps: [],
-          },
+          output: `Replay step ${getSafeStepIndex(
+            getStepIndexValue(step)
+          )} failed: ${formatReplayDiagnostic(error)}`,
           replayStepMeta: {
-            usedCachedAction: true,
+            usedCachedAction: false,
             fallbackUsed: false,
             retries: 0,
-            cachedXPath: null,
+            cachedXPath: stepXPath,
             fallbackXPath: null,
             fallbackElementId: null,
           },
         };
-      } else if (step.actionType === "extract") {
-        try {
-          if (!step.instruction) {
-            throw new Error("Missing objective/instruction for extract action");
+        if (!recordReplayStep(step, result)) {
+          break;
+        }
+        continue;
+      }
+      try {
+        if (REPLAY_SPECIAL_ACTION_TYPES.has(actionType)) {
+          attemptedCachedAction = true;
+        }
+        const replaySpecialResult = await executeReplaySpecialAction({
+          taskId: sourceTaskId,
+          actionType,
+          instruction: instruction ?? undefined,
+          arguments: normalizedStepArguments,
+          actionParams: stepActionParams,
+          page: hyperPage,
+          retries: 1,
+        });
+
+        if (replaySpecialResult) {
+          attemptedCachedAction = true;
+          result = replaySpecialResult;
+        } else {
+          const rawMethod = safeReadStepField(step, "method");
+          const method = normalizePageActionMethod(
+            typeof rawMethod === "string" ? rawMethod : null
+          );
+          if (method) {
+            const xpath = stepXPath?.trim();
+            const hasXPath = typeof xpath === "string" && xpath.length > 0;
+            const replayInstruction = instruction;
+            if (!hasXPath) {
+              if (replayInstruction) {
+                result = await hyperPage.perform(replayInstruction, {
+                  cdpActions,
+                  filterAdTrackingFrames,
+                });
+              } else {
+                result = {
+                  taskId: sourceTaskId,
+                  status: TaskStatus.FAILED,
+                  steps: [],
+                  output: `Cannot replay action type "${actionType}" with method "${method}" without XPath or instruction`,
+                  replayStepMeta: {
+                    usedCachedAction: false,
+                    fallbackUsed: false,
+                    retries: 0,
+                    cachedXPath: null,
+                    fallbackXPath: null,
+                    fallbackElementId: null,
+                  },
+                };
+              }
+              if (!recordReplayStep(step, result)) {
+                break;
+              }
+              continue;
+            }
+            const options: PerformOptions = {
+              performInstruction: replayInstruction,
+              maxSteps: maxXPathRetries,
+              cdpActions,
+              filterAdTrackingFrames,
+            };
+            if (stepFrameIndex !== null && stepFrameIndex !== undefined) {
+              options.frameIndex = stepFrameIndex;
+            }
+            const firstArgument = normalizedStepArguments[0];
+            const valueArg =
+              typeof firstArgument === "string"
+                ? firstArgument
+                : typeof firstArgument === "number"
+                  ? `${firstArgument}`
+                  : undefined;
+            attemptedCachedAction = true;
+            result = await dispatchPerformHelper(
+              hyperPage,
+              method,
+              xpath,
+              valueArg,
+              options
+            );
+          } else {
+            const replayInstruction = instruction;
+            if (replayInstruction) {
+              result = await hyperPage.perform(replayInstruction, {
+                cdpActions,
+                filterAdTrackingFrames,
+              });
+            } else {
+              result = {
+                taskId: sourceTaskId,
+                status: TaskStatus.FAILED,
+                steps: [],
+                output: `Cannot replay action type "${actionType}" without instruction`,
+                replayStepMeta: {
+                  usedCachedAction: false,
+                  fallbackUsed: false,
+                  retries: 0,
+                  cachedXPath: null,
+                  fallbackXPath: null,
+                  fallbackElementId: null,
+                },
+              };
+            }
           }
-          const extractResult = await hyperPage.extract(step.instruction);
-          result = {
-            taskId: cache.taskId,
-            status: TaskStatus.COMPLETED,
-            steps: [],
-            output:
-              typeof extractResult === "string"
-                ? extractResult
-                : JSON.stringify(extractResult),
-            replayStepMeta: {
-              usedCachedAction: true,
-              fallbackUsed: false,
-              retries: 0,
-              cachedXPath: null,
-              fallbackXPath: null,
-              fallbackElementId: null,
-            },
-          };
-        } catch (err: any) {
-          result = {
-            taskId: cache.taskId,
-            status: TaskStatus.FAILED,
-            steps: [],
-            output: `Extract failed: ${err?.message || String(err)}`,
-            replayStepMeta: {
-              usedCachedAction: true,
-              fallbackUsed: false,
-              retries: 0,
-              cachedXPath: null,
-              fallbackXPath: null,
-              fallbackElementId: null,
-            },
-          };
         }
-      } else if (step.actionType === "analyzePdf") {
+      } catch (error: unknown) {
+        const message = formatReplayDiagnostic(error);
         result = {
-          taskId: cache.taskId,
+          taskId: sourceTaskId,
           status: TaskStatus.FAILED,
           steps: [],
-          output: "analyzePdf replay is not supported in runFromActionCache.",
+          output: `Replay step ${getSafeStepIndex(
+            getStepIndexValue(step)
+          )} failed: ${message}`,
           replayStepMeta: {
-            usedCachedAction: true,
+            usedCachedAction: attemptedCachedAction,
             fallbackUsed: false,
-            retries: 0,
-            cachedXPath: null,
+            retries: 1,
+            cachedXPath: stepXPath ?? null,
             fallbackXPath: null,
             fallbackElementId: null,
           },
         };
-      } else {
-        const method = step.method;
-        if (method && validHelperMethods.has(method)) {
-          const options: PerformOptions = {
-            performInstruction: step.instruction ?? null,
-            maxSteps: maxXPathRetries,
-          };
-          if (step.frameIndex !== null && step.frameIndex !== undefined) {
-            options.frameIndex = step.frameIndex;
-          }
-          const valueArg = step.arguments?.[0];
-          result = await dispatchPerformHelper(
-            hyperPage,
-            method,
-            step.xpath ?? "",
-            valueArg,
-            options
-          );
-        } else if (step.instruction) {
-          result = await hyperPage.perform(step.instruction);
-        } else {
-          result = {
-            taskId: cache.taskId,
-            status: TaskStatus.FAILED,
-            steps: [],
-            output: `Cannot replay action type "${step.actionType}" without instruction`,
-            replayStepMeta: {
-              usedCachedAction: false,
-              fallbackUsed: false,
-              retries: 0,
-              cachedXPath: null,
-              fallbackXPath: null,
-              fallbackElementId: null,
-            },
-          };
-        }
       }
 
-      const finalMeta = result.replayStepMeta;
-      const finalSuccess = result.status === TaskStatus.COMPLETED;
+      if (!recordReplayStep(step, result)) {
+        break;
+      }
+    }
 
+    if (omittedReplaySteps > 0 && !replayStoppedByLifecycle) {
+      replayStatus = TaskStatus.FAILED;
+      const omittedDescriptor = omittedReplayStepsIsLowerBound
+        ? `at least ${omittedReplaySteps}`
+        : `${omittedReplaySteps}`;
       stepsResult.push({
-        stepIndex: step.stepIndex,
-        actionType: step.actionType,
-        usedXPath: finalMeta?.usedCachedAction ?? false,
-        fallbackUsed: finalMeta?.fallbackUsed ?? false,
-        cachedXPath: finalMeta?.cachedXPath ?? null,
-        fallbackXPath: finalMeta?.fallbackXPath ?? null,
-        fallbackElementId: finalMeta?.fallbackElementId ?? null,
-        retries: finalMeta?.retries ?? 0,
-        success: finalSuccess,
-        message:
-          result.output ||
-          (finalSuccess ? "Completed" : "Failed to execute cached action"),
+        stepIndex: -1,
+        actionType: "replay-limit",
+        usedXPath: false,
+        fallbackUsed: false,
+        cachedXPath: null,
+        fallbackXPath: null,
+        fallbackElementId: null,
+        retries: 0,
+        success: false,
+        message: `Replay truncated after ${HyperAgent.MAX_REPLAY_STEPS} steps; ${omittedDescriptor} additional step(s) were skipped`,
       });
-
-      if (!finalSuccess) {
-        replayStatus = TaskStatus.FAILED;
-        break;
-      }
     }
 
     const replayResult: ActionCacheReplayResult = {
       replayId,
-      sourceTaskId: cache.taskId,
+      sourceTaskId,
       steps: stepsResult,
       status: replayStatus,
     };
 
-    if (debug) {
-      const debugDir = "debug/action-cache";
-      fs.mkdirSync(debugDir, { recursive: true });
-      fs.writeFileSync(
-        `${debugDir}/replay-${replayId}.json`,
-        JSON.stringify(replayResult, null, 2)
-      );
+    if (shouldWriteReplayDebug()) {
+      try {
+        const debugDir = "debug/action-cache";
+        fs.mkdirSync(debugDir, { recursive: true });
+        fs.writeFileSync(
+          `${debugDir}/replay-${replayId}.json`,
+          JSON.stringify(replayResult, null, 2)
+        );
+      } catch (error) {
+        console.error(
+          `[runFromActionCache] Failed to write replay debug: ${formatReplayDiagnostic(
+            error
+          )}`
+        );
+      }
     }
 
     return replayResult;
@@ -849,7 +2768,8 @@ export class HyperAgent<T extends BrowserProviders = "Local"> {
     page: Page,
     maxRetries: number,
     retryDelayMs: number,
-    startTime: string
+    startTime: string,
+    filterAdTrackingFrames: boolean
   ): Promise<{
     element: ExamineDomResult;
     domState: A11yDOMState;
@@ -865,6 +2785,7 @@ export class HyperAgent<T extends BrowserProviders = "Local"> {
         maxRetries,
         retryDelayMs,
         debug: this.debug,
+        filterAdTrackingFrames,
       }
     );
 
@@ -882,11 +2803,11 @@ export class HyperAgent<T extends BrowserProviders = "Local"> {
     // Element not found after all retries - handle error case
     if (this.debug) {
       console.error(
-        `[aiAction] No elements found for instruction: "${instruction}" after ${maxRetries} attempts`
+        `[perform] No elements found for instruction: "${instruction}" after ${maxRetries} attempts`
       );
-      console.error(`[aiAction] Current URL: ${page.url()}`);
+      console.error(`[perform] Current URL: ${this.safeGetPageUrl(page)}`);
       console.error(
-        `[aiAction] Total elements in final a11y tree: ${result.domState.elements.size}`
+        `[perform] Total elements in final a11y tree: ${result.domState.elements.size}`
       );
 
       // Write debug data to files before throwing error
@@ -936,18 +2857,17 @@ export class HyperAgent<T extends BrowserProviders = "Local"> {
       return;
     }
 
-    const { writeAiActionDebug } = await import("../utils/debugWriter");
+    const { writePerformDebug } = await import("../utils/debugWriter");
 
     try {
-      const screenshot = await params.page
-        .screenshot({ type: "png" })
-        .catch(() => null);
+      const screenshot = await this.captureDebugScreenshot(params.page);
+      const safeUrl = this.safeGetPageUrl(params.page);
 
       if (params.success && params.element) {
         // Success case - write found element data
-        await writeAiActionDebug({
+        await writePerformDebug({
           instruction: params.instruction,
-          url: params.page.url(),
+          url: safeUrl,
           timestamp: params.startTime,
           domElementCount: params.domState.elements.size,
           domTree: params.domState.domState,
@@ -961,17 +2881,17 @@ export class HyperAgent<T extends BrowserProviders = "Local"> {
           llmResponse: params.llmResponse,
           success: true,
           frameDebugInfo: params.domState.frameDebugInfo,
-        });
+        }, HyperAgent.PERFORM_DEBUG_DIR);
       } else {
         // Error case - write available elements
         const availableElements = this.collectInteractiveElements(
           params.elementMap,
-          HyperAgent.AIACTION_CONFIG.MAX_DEBUG_ELEMENTS_TO_STORE
+          HyperAgent.PERFORM_CONFIG.MAX_DEBUG_ELEMENTS_TO_STORE
         );
 
-        await writeAiActionDebug({
+        await writePerformDebug({
           instruction: params.instruction,
-          url: params.page.url(),
+          url: safeUrl,
           timestamp: params.startTime,
           domElementCount: params.domState.elements.size,
           domTree: params.domState.domState,
@@ -979,19 +2899,20 @@ export class HyperAgent<T extends BrowserProviders = "Local"> {
           availableElements,
           llmResponse: params.llmResponse,
           error: {
-            message:
-              params.error instanceof Error
-                ? params.error.message
-                : String(params.error),
+            message: this.formatHelperDiagnostic(params.error),
             stack:
               params.error instanceof Error ? params.error.stack : undefined,
           },
           success: false,
           frameDebugInfo: params.domState.frameDebugInfo,
-        });
+        }, HyperAgent.PERFORM_DEBUG_DIR);
       }
     } catch (debugError) {
-      console.error(`[aiAction] Failed to write debug data:`, debugError);
+      console.error(
+        `[perform] Failed to write debug data: ${this.formatHelperDiagnostic(
+          debugError
+        )}`
+      );
     }
   }
 
@@ -1079,22 +3000,50 @@ export class HyperAgent<T extends BrowserProviders = "Local"> {
   public async executeSingleAction(
     instruction: string,
     pageOrGetter: Page | (() => Page),
-    _params?: TaskParams
+    params?: PerformTaskParams
   ): Promise<TaskOutput> {
+    const normalizedInstruction = this.normalizeSingleActionInstruction(
+      instruction
+    );
     const taskId = uuidv4();
     const actionStart = performance.now();
     const startTime = new Date().toISOString();
     if (this.debug) {
-      console.log(`[aiAction] Instruction: ${instruction}`);
+      console.log(`[perform] Instruction: ${normalizedInstruction}`);
+    }
+
+    const getPage = (): Page => this.resolveActionPageInput(pageOrGetter);
+    if (this.shouldWarnPerformMaxStepsDeprecation(params)) {
+      this.warnPerformMaxStepsDeprecation();
     }
 
-    const getPage = () =>
-      typeof pageOrGetter === "function" ? pageOrGetter() : pageOrGetter;
     const initialPage = getPage();
+    const hasPageContextSwitched = (): boolean => {
+      try {
+        return getPage() !== initialPage;
+      } catch {
+        return true;
+      }
+    };
 
     let domState: A11yDOMState | null = null;
     let elementMap: Map<string, AccessibilityNode> | null = null;
 
+    const maxRetries = this.normalizeRetryCount(
+      params?.maxElementRetries ?? params?.maxSteps,
+      HyperAgent.PERFORM_CONFIG.MAX_RETRIES
+    );
+    const cdpActions = this.resolveCdpActions(
+      this.safeReadField(params, "cdpActions")
+    );
+    const filterAdTrackingFrames = this.resolveFilterAdTrackingFrames(
+      this.safeReadField(params, "filterAdTrackingFrames")
+    );
+    const retryDelayMs = this.normalizeRetryDelayMs(
+      params?.retryDelayMs,
+      HyperAgent.PERFORM_CONFIG.RETRY_DELAY_MS
+    );
+
     try {
       // Find element with retry logic
       const findStart = performance.now();
@@ -1104,15 +3053,16 @@ export class HyperAgent<T extends BrowserProviders = "Local"> {
         elementMap: foundElementMap,
         llmResponse,
       } = await this.findElementWithRetry(
-        instruction,
+        normalizedInstruction,
         initialPage,
-        HyperAgent.AIACTION_CONFIG.MAX_RETRIES,
-        HyperAgent.AIACTION_CONFIG.RETRY_DELAY_MS,
-        startTime
+        maxRetries,
+        retryDelayMs,
+        startTime,
+        filterAdTrackingFrames
       );
 
       // Check if page context switched during findElement (e.g. new tab opened by previous action)
-      if (getPage() !== initialPage) {
+      if (hasPageContextSwitched()) {
         throw new HyperagentError(
           "Page context switched during execution",
           409
@@ -1128,9 +3078,9 @@ export class HyperAgent<T extends BrowserProviders = "Local"> {
       );
 
       if (this.debug) {
-        console.log(`[aiAction] Found element: ${element.elementId}`);
-        console.log(`[aiAction] Method: ${element.method}`);
-        console.log(`[aiAction] Arguments:`, element.arguments);
+        console.log(`[perform] Found element: ${element.elementId}`);
+        console.log(`[perform] Method: ${element.method}`);
+        console.log(`[perform] Arguments:`, element.arguments);
       }
 
       if (!element.method) {
@@ -1147,17 +3097,30 @@ export class HyperAgent<T extends BrowserProviders = "Local"> {
           400
         );
       }
-      let actionXPath: string | null =
+      const actionXPath: string | null =
         domState?.xpathMap?.[element.elementId] ?? null;
 
       // Use shared runtime context
-      const { cdpClient, frameContextManager } = await initializeRuntimeContext(
-        initialPage,
-        this.debug
-      );
+      let cdpClient: Awaited<
+        ReturnType<typeof initializeRuntimeContext>
+      >["cdpClient"] | null = null;
+      let frameContextManager: Awaited<
+        ReturnType<typeof initializeRuntimeContext>
+      >["frameContextManager"] | null = null;
+      if (cdpActions) {
+        const runtimeContext = await initializeRuntimeContext(
+          initialPage,
+          this.debug,
+          {
+            filterAdTrackingFrames,
+          }
+        );
+        cdpClient = runtimeContext.cdpClient;
+        frameContextManager = runtimeContext.frameContextManager;
+      }
 
       // Check context switch again before action
-      if (getPage() !== initialPage) {
+      if (hasPageContextSwitched()) {
         throw new HyperagentError(
           "Page context switched during execution",
           409
@@ -1174,8 +3137,9 @@ export class HyperAgent<T extends BrowserProviders = "Local"> {
         llm: this.llm,
         debug: this.debug,
         // Only provide CDP if enabled
-        cdpActions: this.cdpActionsEnabled,
-        cdp: this.cdpActionsEnabled
+        cdpActions,
+        filterAdTrackingFrames,
+        cdp: cdpActions && cdpClient && frameContextManager
           ? {
               client: cdpClient,
               frameContextManager,
@@ -1188,7 +3152,7 @@ export class HyperAgent<T extends BrowserProviders = "Local"> {
         // These are required by ActionContext but not used by performAction
         debugDir: undefined,
         mcpClient: this.mcpClient,
-        variables: Object.values(this._variables),
+        variables: this.getVariableValues(),
         invalidateDomCache: () => markDomSnapshotDirty(initialPage),
       };
 
@@ -1197,7 +3161,7 @@ export class HyperAgent<T extends BrowserProviders = "Local"> {
         elementId: element.elementId,
         method,
         arguments: args,
-        instruction,
+        instruction: normalizedInstruction,
         confidence: 1, // Implicit confidence for single action
       });
 
@@ -1207,7 +3171,9 @@ export class HyperAgent<T extends BrowserProviders = "Local"> {
 
       // Wait for DOM to settle after action
       const waitStart = performance.now();
-      await waitForSettledDOM(initialPage);
+      await waitForSettledDOM(initialPage, undefined, {
+        filterAdTrackingFrames,
+      });
       markDomSnapshotDirty(initialPage);
       logPerf(
         this.debug,
@@ -1222,7 +3188,7 @@ export class HyperAgent<T extends BrowserProviders = "Local"> {
 
       // Write debug data on success
       await this.writeDebugData({
-        instruction,
+        instruction: normalizedInstruction,
         page: initialPage,
         startTime,
         domState,
@@ -1242,7 +3208,7 @@ export class HyperAgent<T extends BrowserProviders = "Local"> {
         taskId,
         status: TaskStatus.COMPLETED,
         steps: [],
-        output: `Successfully executed: ${instruction}`,
+        output: `Successfully executed: ${normalizedInstruction}`,
         actionCache: {
           taskId,
           createdAt: startTime,
@@ -1261,7 +3227,7 @@ export class HyperAgent<T extends BrowserProviders = "Local"> {
     } catch (error) {
       // If page switched during execution, prioritize that over the error
       // This catches cases where findElement failed because the old page closed/navigated
-      if (getPage() !== initialPage) {
+      if (hasPageContextSwitched()) {
         throw new HyperagentError(
           "Page context switched during execution",
           409
@@ -1270,7 +3236,7 @@ export class HyperAgent<T extends BrowserProviders = "Local"> {
 
       // Write debug data on error
       await this.writeDebugData({
-        instruction,
+        instruction: normalizedInstruction,
         page: initialPage,
         startTime,
         domState,
@@ -1284,7 +3250,7 @@ export class HyperAgent<T extends BrowserProviders = "Local"> {
         throw error;
       }
       // Wrap other errors
-      const errorMsg = error instanceof Error ? error.message : String(error);
+      const errorMsg = this.formatHelperDiagnostic(error);
       throw new HyperagentError(`Failed to execute action: ${errorMsg}`, 500);
     }
   }
@@ -1293,61 +3259,226 @@ export class HyperAgent<T extends BrowserProviders = "Local"> {
    * Register a new action with the agent
    * @param action The action to register
    */
-  private async registerAction(action: AgentActionDefinition) {
-    if (action.type === "complete") {
+  private registerAction(
+    action: AgentActionDefinition,
+    knownActionType?: string
+  ): void {
+    const actionType =
+      knownActionType ??
+      this.normalizeServerId(this.safeReadField(action, "type"));
+    if (!actionType) {
+      throw new HyperagentError(
+        "Could not register action with an invalid action type.",
+        400
+      );
+    }
+    if (actionType === "complete") {
       throw new HyperagentError(
         "Could not add an action with the name 'complete'. Complete is a reserved action.",
         400
       );
     }
     const actionsList = new Set(
-      this.actions.map((registeredAction) => registeredAction.type)
+      this.actions
+        .map((registeredAction) =>
+          this.normalizeServerId(this.safeReadField(registeredAction, "type"))
+        )
+        .filter((type): type is string => typeof type === "string")
     );
-    if (actionsList.has(action.type)) {
+    if (actionsList.has(actionType)) {
       throw new Error(
-        `Could not register action of type ${action.type}. Action with the same name is already registered`
+        `Could not register action of type ${actionType}. Action with the same name is already registered`
       );
     } else {
       this.actions.push(action);
     }
   }
 
+  private unregisterActionsByType(actionTypes: Iterable<string>): void {
+    const removeTypes = new Set(actionTypes);
+    if (removeTypes.size === 0) {
+      return;
+    }
+    this.actions = this.actions.filter((action) => {
+      const actionType = this.normalizeServerId(this.safeReadField(action, "type"));
+      return !actionType || !removeTypes.has(actionType);
+    });
+  }
+
+  private getRegisteredMCPActionTypes(): string[] {
+    try {
+      return Array.from(this.mcpActionTypesByServer.values()).flatMap(
+        (actionTypes) => {
+          try {
+            return Array.from(actionTypes).filter(
+              (type): type is string =>
+                typeof type === "string" && type.trim().length > 0
+            );
+          } catch {
+            return [];
+          }
+        }
+      );
+    } catch {
+      return [];
+    }
+  }
+
+  private clearRegisteredMCPActionTypes(): void {
+    try {
+      this.mcpActionTypesByServer.clear();
+    } catch {
+      // no-op
+    }
+  }
+
+  private deleteRegisteredMCPActionTypes(serverId: string): void {
+    try {
+      this.mcpActionTypesByServer.delete(serverId);
+    } catch {
+      // no-op
+    }
+  }
+
+  private getMCPActionTypesForServer(serverId: string): Set<string> | null {
+    let actionTypes: unknown;
+    try {
+      actionTypes = this.mcpActionTypesByServer.get(serverId);
+    } catch {
+      return null;
+    }
+    if (!actionTypes) {
+      return null;
+    }
+    if (actionTypes instanceof Set) {
+      return actionTypes;
+    }
+    try {
+      const normalized = new Set<string>();
+      for (const value of actionTypes as Iterable<unknown>) {
+        if (typeof value === "string" && value.trim().length > 0) {
+          normalized.add(value);
+        }
+      }
+      return normalized;
+    } catch {
+      return null;
+    }
+  }
+
+  private registerMCPActions(
+    serverId: string,
+    actions: AgentActionDefinition[]
+  ): void {
+    const registeredActionTypes = new Set<string>();
+    try {
+      for (const action of actions) {
+        const actionType = this.normalizeServerId(
+          this.safeReadField(action, "type")
+        );
+        if (!actionType) {
+          throw new HyperagentError(
+            `Could not register MCP action from server ${serverId}: invalid action type`,
+            400
+          );
+        }
+        this.registerAction(action, actionType);
+        registeredActionTypes.add(actionType);
+      }
+      this.mcpActionTypesByServer.set(serverId, registeredActionTypes);
+    } catch (error) {
+      this.unregisterActionsByType(registeredActionTypes);
+      this.deleteRegisteredMCPActionTypes(serverId);
+      throw error;
+    }
+  }
+
+  private unregisterMCPActionsForServer(serverId: string): void {
+    const actionTypes = this.getMCPActionTypesForServer(serverId);
+    if (!actionTypes) {
+      return;
+    }
+    this.unregisterActionsByType(actionTypes);
+    this.deleteRegisteredMCPActionTypes(serverId);
+  }
+
+  private async resetMCPClient(): Promise<void> {
+    if (this.mcpClient) {
+      await this.mcpClient.disconnect().catch((error) => {
+        if (this.debug) {
+          console.warn(
+            `Failed to reset existing MCP client: ${this.formatMCPDiagnostic(
+              error
+            )}`
+          );
+        }
+      });
+      this.mcpClient = undefined;
+    }
+    this.unregisterActionsByType(
+      this.getRegisteredMCPActionTypes()
+    );
+    this.clearRegisteredMCPActionTypes();
+  }
+
   /**
    * Initialize the MCP client with the given configuration
    * @param config The MCP configuration
    */
   public async initializeMCPClient(config: MCPConfig): Promise<void> {
-    if (!config || config.servers.length === 0) {
+    const rawServers = this.safeReadField(config, "servers");
+    const servers = Array.isArray(rawServers)
+      ? (rawServers as MCPServerConfig[])
+      : [];
+    if (servers.length === 0) {
+      return;
+    }
+    await this.resetMCPClient();
+    try {
+      this.mcpClient = new MCPClient(this.debug);
+    } catch (error) {
+      console.error(
+        `Failed to initialize MCP client: ${this.formatMCPDiagnostic(error)}`
+      );
+      this.mcpClient = undefined;
       return;
     }
-    this.mcpClient = new MCPClient(this.debug);
     try {
-      for (const serverConfig of config.servers) {
+      for (const serverConfig of servers) {
         try {
           const { serverId, actions } =
             await this.mcpClient.connectToServer(serverConfig);
-          for (const action of actions) {
-            this.registerAction(action);
+          try {
+            this.registerMCPActions(serverId, actions);
+          } catch (registrationError) {
+            await this.mcpClient.disconnectServer(serverId).catch(() => {});
+            throw registrationError;
           }
           if (this.debug) {
             console.log(`MCP server ${serverId} initialized successfully`);
           }
         } catch (error) {
+          const serverLabel = this.normalizeServerId(
+            this.safeReadField(serverConfig, "id")
+          );
           console.error(
-            `Failed to initialize MCP server ${serverConfig.id || "unknown"}:`,
-            error
+            `Failed to initialize MCP server ${serverLabel ?? "unknown"}: ${this.formatMCPDiagnostic(
+              error
+            )}`
           );
         }
       }
 
-      const serverIds = this.mcpClient.getServerIds();
+      const serverIds = this.getSafeMCPServerIds();
       if (this.debug) {
         console.log(
           `Successfully connected to ${serverIds.length} MCP servers`
         );
       }
     } catch (error) {
-      console.error("Failed to initialize MCP client:", error);
+      console.error(
+        `Failed to initialize MCP client: ${this.formatMCPDiagnostic(error)}`
+      );
       this.mcpClient = undefined;
     }
   }
@@ -1360,17 +3491,29 @@ export class HyperAgent<T extends BrowserProviders = "Local"> {
   public async connectToMCPServer(
     serverConfig: MCPServerConfig
   ): Promise<string | null> {
+    if (!serverConfig || typeof serverConfig !== "object") {
+      return null;
+    }
     if (!this.mcpClient) {
-      this.mcpClient = new MCPClient(this.debug);
+      try {
+        this.mcpClient = new MCPClient(this.debug);
+      } catch (error) {
+        console.error(
+          `Failed to connect to MCP server: ${this.formatMCPDiagnostic(error)}`
+        );
+        this.mcpClient = undefined;
+        return null;
+      }
     }
 
     try {
       const { serverId, actions } =
         await this.mcpClient.connectToServer(serverConfig);
-
-      // Register the actions from this server
-      for (const action of actions) {
-        this.registerAction(action);
+      try {
+        this.registerMCPActions(serverId, actions);
+      } catch (registrationError) {
+        await this.mcpClient.disconnectServer(serverId).catch(() => {});
+        throw registrationError;
       }
 
       if (this.debug) {
@@ -1378,7 +3521,9 @@ export class HyperAgent<T extends BrowserProviders = "Local"> {
       }
       return serverId;
     } catch (error) {
-      console.error(`Failed to connect to MCP server:`, error);
+      console.error(
+        `Failed to connect to MCP server: ${this.formatMCPDiagnostic(error)}`
+      );
       return null;
     }
   }
@@ -1389,15 +3534,69 @@ export class HyperAgent<T extends BrowserProviders = "Local"> {
    * @returns Boolean indicating if the disconnection was successful
    */
   public disconnectFromMCPServer(serverId: string): boolean {
+    const normalizedServerId = this.normalizeServerId(serverId);
+    if (!normalizedServerId) {
+      return false;
+    }
+    if (!this.mcpClient) {
+      return false;
+    }
+
+    const isConnected = this.getSafeMCPServerIds().includes(normalizedServerId);
+    if (!isConnected) {
+      this.unregisterMCPActionsForServer(normalizedServerId);
+      return false;
+    }
+
+    try {
+      this.unregisterMCPActionsForServer(normalizedServerId);
+      void this.mcpClient.disconnectServer(normalizedServerId).catch((error) => {
+        console.error(
+          `Failed to disconnect from MCP server ${normalizedServerId}: ${this.formatMCPDiagnostic(
+            error
+          )}`
+        );
+      });
+      return true;
+    } catch (error) {
+      console.error(
+        `Failed to disconnect from MCP server ${normalizedServerId}: ${this.formatMCPDiagnostic(
+          error
+        )}`
+      );
+      return false;
+    }
+  }
+
+  /**
+   * Disconnect from a specific MCP server and await transport cleanup.
+   * @param serverId ID of the server to disconnect from
+   * @returns Boolean indicating if disconnection was successful
+   */
+  public async disconnectFromMCPServerAsync(serverId: string): Promise<boolean> {
+    const normalizedServerId = this.normalizeServerId(serverId);
+    if (!normalizedServerId) {
+      return false;
+    }
     if (!this.mcpClient) {
       return false;
     }
+    const isConnected = this.getSafeMCPServerIds().includes(normalizedServerId);
+    if (!isConnected) {
+      this.unregisterMCPActionsForServer(normalizedServerId);
+      return false;
+    }
 
+    this.unregisterMCPActionsForServer(normalizedServerId);
     try {
-      this.mcpClient.disconnectServer(serverId);
+      await this.mcpClient.disconnectServer(normalizedServerId);
       return true;
     } catch (error) {
-      console.error(`Failed to disconnect from MCP server ${serverId}:`, error);
+      console.error(
+        `Failed to disconnect from MCP server ${normalizedServerId}: ${this.formatMCPDiagnostic(
+          error
+        )}`
+      );
       return false;
     }
   }
@@ -1408,10 +3607,14 @@ export class HyperAgent<T extends BrowserProviders = "Local"> {
    * @returns Boolean indicating if the server is connected
    */
   public isMCPServerConnected(serverId: string): boolean {
+    const normalizedServerId = this.normalizeServerId(serverId);
+    if (!normalizedServerId) {
+      return false;
+    }
     if (!this.mcpClient) {
       return false;
     }
-    return this.mcpClient.getServerIds().includes(serverId);
+    return this.getSafeMCPServerIds().includes(normalizedServerId);
   }
 
   /**
@@ -1419,10 +3622,7 @@ export class HyperAgent<T extends BrowserProviders = "Local"> {
    * @returns Array of server IDs
    */
   public getMCPServerIds(): string[] {
-    if (!this.mcpClient) {
-      return [];
-    }
-    return this.mcpClient.getServerIds();
+    return this.getSafeMCPServerIds();
   }
 
   /**
@@ -1437,7 +3637,7 @@ export class HyperAgent<T extends BrowserProviders = "Local"> {
     if (!this.mcpClient) {
       return null;
     }
-    return this.mcpClient.getServerInfo();
+    return this.getSafeMCPServerInfo();
   }
 
   /**
@@ -1446,17 +3646,55 @@ export class HyperAgent<T extends BrowserProviders = "Local"> {
    * @returns Formatted string representation of the action
    */
   public pprintAction(action: ActionType): string {
-    const foundAction = this.actions.find(
-      (actions) => actions.type === action.type
+    const actionType = this.normalizeServerId(
+      (this.safeReadField(action, "type") as string | undefined) ?? ""
     );
-    if (foundAction && foundAction.pprintAction) {
-      return foundAction.pprintAction(action.params);
+    if (!actionType) {
+      return "";
+    }
+    const actionParams = this.safeReadField(action, "params");
+    const foundAction = this.actions.find((candidate) => {
+      const candidateType = this.normalizeServerId(
+        this.safeReadField(candidate, "type") as string | undefined
+      );
+      return candidateType === actionType;
+    });
+    if (!foundAction) {
+      return "";
+    }
+    const pprintAction = this.safeReadField(foundAction, "pprintAction");
+    if (typeof pprintAction !== "function") {
+      return "";
+    }
+    try {
+      const pretty = pprintAction(actionParams);
+      return typeof pretty === "string" ? pretty : "";
+    } catch (error) {
+      if (this.debug) {
+        console.warn(
+          `[HyperAgent] Failed to pprint action "${actionType}": ${this.formatHelperDiagnostic(
+            error
+          )}`
+        );
+      }
+      return "";
     }
-    return "";
   }
 
   public getSession() {
-    const session = this.browserProvider.getSession();
+    let session: unknown;
+    try {
+      session = this.browserProvider.getSession();
+    } catch (error) {
+      if (this.debug) {
+        console.warn(
+          `[HyperAgent] Failed to read browser session: ${this.formatHelperDiagnostic(
+            error
+          )}`
+        );
+      }
+      return null;
+    }
     if (!session) {
       return null;
     }
@@ -1467,33 +3705,185 @@ export class HyperAgent<T extends BrowserProviders = "Local"> {
     steps: ActionCacheEntry[],
     taskId?: string
   ): string {
-    return createScriptFromActionCache({ steps, taskId });
+    let normalizedSteps: ActionCacheEntry[] = [];
+    try {
+      if (Array.isArray(steps)) {
+        normalizedSteps = Array.from(steps);
+      } else if (steps && typeof steps === "object") {
+        normalizedSteps = Array.from(steps as unknown as Iterable<ActionCacheEntry>);
+      }
+    } catch (error) {
+      throw new HyperagentError(
+        `Failed to read action cache steps: ${this.formatHelperDiagnostic(error)}`,
+        400
+      );
+    }
+    try {
+      return createScriptFromActionCache({
+        steps: normalizedSteps,
+        taskId: this.normalizeVariableKey(taskId) ?? undefined,
+      });
+    } catch (error) {
+      throw new HyperagentError(
+        `Failed to create action cache script: ${this.formatHelperDiagnostic(error)}`,
+        500
+      );
+    }
   }
 
   private setupHyperPage(page: Page): HyperPage {
     const hyperPage = page as HyperPage;
+    const scopedPage = hyperPage as HyperPage & {
+      _scopeListenerCleanup?: () => void;
+    };
+    const readPageContext = (targetPage: Page): BrowserContext | null => {
+      const contextMethod = this.safeReadField(targetPage, "context");
+      if (typeof contextMethod !== "function") {
+        return null;
+      }
+      try {
+        const value = (contextMethod as (this: Page) => unknown).call(targetPage);
+        return value && typeof value === "object"
+          ? (value as BrowserContext)
+          : null;
+      } catch {
+        return null;
+      }
+    };
+    const readContextPages = (targetPage: Page): Page[] => {
+      const context = readPageContext(targetPage);
+      if (!context) {
+        return [];
+      }
+      const pagesMethod = this.safeReadField(context, "pages");
+      if (typeof pagesMethod !== "function") {
+        return [];
+      }
+      try {
+        const pagesValue = (
+          pagesMethod as (this: BrowserContext) => unknown
+        ).call(context);
+        return this.safeArrayValues<Page>(pagesValue);
+      } catch {
+        return [];
+      }
+    };
 
     // Clean up existing listener if this page was already setup
-    if ((hyperPage as any)._scopeListenerCleanup) {
-      (hyperPage as any)._scopeListenerCleanup();
+    const existingScopedCleanup = this.scopeListenerCleanupByPage.get(page);
+    if (typeof existingScopedCleanup === "function") {
+      try {
+        existingScopedCleanup();
+      } catch {
+        // no-op
+      }
+      this.scopeListenerCleanupByPage.delete(page);
+    }
+    const existingScopeCleanup = this.safeReadField(
+      scopedPage,
+      "_scopeListenerCleanup"
+    );
+    if (typeof existingScopeCleanup === "function") {
+      try {
+        existingScopeCleanup();
+      } catch {
+        // no-op
+      }
     }
 
     // History Stack: [Root, Tab1, Tab2, ...]
     const pageStack: Page[] = [page];
-    const getActivePage = () => pageStack[pageStack.length - 1];
+    const trackedCloseListenerPages = new WeakSet<object>();
+    const getActivePage = (): Page => {
+      for (let i = pageStack.length - 1; i >= 0; i--) {
+        const candidate = pageStack[i];
+        try {
+          if (candidate && !candidate.isClosed()) {
+            return candidate;
+          }
+        } catch {
+          // keep scanning
+        }
+      }
+
+      const contextPages = readContextPages(page);
+      for (let i = contextPages.length - 1; i >= 0; i--) {
+        const candidate = contextPages[i];
+        try {
+          if (candidate && !candidate.isClosed()) {
+            return candidate;
+          }
+        } catch {
+          // keep scanning
+        }
+      }
+
+      return page;
+    };
 
     // Handle tab closing (Pop)
     const handleClose = (p: Page) => {
-      const idx = pageStack.indexOf(p);
-      if (idx !== -1) {
+      let removed = 0;
+      for (let i = pageStack.length - 1; i >= 0; i--) {
+        if (pageStack[i] === p) {
+          pageStack.splice(i, 1);
+          removed += 1;
+        }
+      }
+      if (removed > 0) {
         if (this.debug) {
           console.log(`[HyperPage] Tab closed, removing from stack`);
         }
-        pageStack.splice(idx, 1);
       }
     };
-    // Listen for close on the root page
-    page.on("close", () => handleClose(page));
+    const closeListenerCleanups: Array<() => void> = [];
+    const attachCloseListener = (targetPage: Page, targetLabel: string): void => {
+      if (trackedCloseListenerPages.has(targetPage)) {
+        return;
+      }
+      const onClose = () => handleClose(targetPage);
+      const pageOn = this.safeReadField(targetPage, "on");
+      if (typeof pageOn !== "function") {
+        return;
+      }
+      try {
+        (
+          pageOn as (
+            this: Page,
+            event: "close",
+            listener: () => void
+          ) => void
+        ).call(targetPage, "close", onClose);
+      } catch (error) {
+        if (this.debug) {
+          console.warn(
+            `[HyperPage] Failed to attach close listener for ${targetLabel}: ${this.formatLifecycleDiagnostic(
+              error
+            )}`
+          );
+        }
+        return;
+      }
+      trackedCloseListenerPages.add(targetPage);
+      closeListenerCleanups.push(() => {
+        const pageOff = this.safeReadField(targetPage, "off");
+        if (typeof pageOff !== "function") {
+          return;
+        }
+        try {
+          (
+            pageOff as (
+              this: Page,
+              event: "close",
+              listener: () => void
+            ) => void
+          ).call(targetPage, "close", onClose);
+        } catch {
+          // no-op
+        }
+      });
+    };
+    attachCloseListener(page, "root page");
 
     // Handle new tabs (Push)
     const onPage = async (newPage: Page) => {
@@ -1503,13 +3893,17 @@ export class HyperAgent<T extends BrowserProviders = "Local"> {
         if (opener === getActivePage()) {
           if (this.debug) {
             console.log(
-              `[HyperPage] Auto-switching to new tab (Push): ${newPage.url()}`
+              `[HyperPage] Auto-switching to new tab (Push): ${this.safeGetPageUrl(
+                newPage
+              )}`
             );
           }
           // Update the scope to follow the new tab
-          pageStack.push(newPage);
+          if (!pageStack.includes(newPage)) {
+            pageStack.push(newPage);
+          }
           // Listen for close on the new page
-          newPage.on("close", () => handleClose(newPage));
+          attachCloseListener(newPage, "new tab");
         }
       } catch {
         // Ignore
@@ -1517,16 +3911,87 @@ export class HyperAgent<T extends BrowserProviders = "Local"> {
     };
 
     // Attach a persistent listener to track page flow for the lifetime of this wrapper
-    page.context().on("page", onPage);
-    (hyperPage as any)._scopeListenerCleanup = () => {
-      page.context().off("page", onPage);
+    const pageContext = readPageContext(page);
+
+    if (pageContext) {
+      const contextOn = this.safeReadField(pageContext, "on");
+      if (typeof contextOn === "function") {
+        try {
+          (
+            contextOn as (
+              this: BrowserContext,
+              event: "page",
+              listener: (newPage: Page) => Promise<void>
+            ) => void
+          ).call(pageContext, "page", onPage);
+        } catch (error) {
+          if (this.debug) {
+            console.warn(
+              `[HyperPage] Failed to attach context page listener: ${this.formatLifecycleDiagnostic(
+                error
+              )}`
+            );
+          }
+        }
+      }
+    }
+    const scopeListenerCleanup = () => {
+      for (const closeCleanup of closeListenerCleanups) {
+        try {
+          closeCleanup();
+        } catch {
+          // no-op
+        }
+      }
+      closeListenerCleanups.length = 0;
+      if (!pageContext) {
+        return;
+      }
+      const contextOff = this.safeReadField(pageContext, "off");
+      if (typeof contextOff !== "function") {
+        return;
+      }
+      try {
+        (
+          contextOff as (
+            this: BrowserContext,
+            event: "page",
+            listener: (newPage: Page) => Promise<void>
+          ) => void
+        ).call(pageContext, "page", onPage);
+      } catch {
+        // no-op
+      }
     };
+    this.scopeListenerCleanupByPage.set(page, scopeListenerCleanup);
+    try {
+      scopedPage._scopeListenerCleanup = scopeListenerCleanup;
+    } catch (error) {
+      if (this.debug) {
+        console.warn(
+          `[HyperPage] Failed to store scope listener cleanup callback: ${this.formatLifecycleDiagnostic(
+            error
+          )}`
+        );
+      }
+    }
 
     const executeSingleActionWithRetry = async (
       instruction: string,
-      params?: TaskParams
+      params?: PerformTaskParams
     ) => {
-      const maxRetries = 3;
+      if (this.shouldWarnPerformMaxStepsDeprecation(params)) {
+        this.warnPerformMaxStepsDeprecation();
+      }
+      const maxRetries = this.normalizeRetryCount(
+        params?.maxContextSwitchRetries,
+        3,
+        10
+      );
+      const contextSwitchRetryDelayMs = this.normalizeRetryDelayMs(
+        params?.contextSwitchRetryDelayMs,
+        500
+      );
       for (let i = 0; i < maxRetries; i++) {
         try {
           return await this.executeSingleAction(
@@ -1534,10 +3999,15 @@ export class HyperAgent<T extends BrowserProviders = "Local"> {
             getActivePage,
             params
           );
-        } catch (err: any) {
+        } catch (err: unknown) {
+          const isPageSwitchError =
+            err instanceof HyperagentError
+              ? err.statusCode === 409
+              : err instanceof Error
+                ? err.message.includes("Page context switched")
+                : false;
           if (
-            err.statusCode === 409 ||
-            (err.message && err.message.includes("Page context switched"))
+            isPageSwitchError
           ) {
             if (this.debug) {
               console.log(
@@ -1545,7 +4015,9 @@ export class HyperAgent<T extends BrowserProviders = "Local"> {
               );
             }
             // Wait briefly for stability
-            await new Promise((resolve) => setTimeout(resolve, 500));
+            await new Promise((resolve) =>
+              setTimeout(resolve, contextSwitchRetryDelayMs)
+            );
             continue;
           }
           throw err;
@@ -1560,10 +4032,11 @@ export class HyperAgent<T extends BrowserProviders = "Local"> {
     hyperPage.ai = (task: string, params?: TaskParams) =>
       this.executeTask(task, params, getActivePage());
 
-    hyperPage.perform = (instruction: string, params?: TaskParams) =>
+    hyperPage.perform = (instruction: string, params?: PerformTaskParams) =>
       executeSingleActionWithRetry(instruction, params);
 
-    hyperPage.aiAction = async (instruction: string, params?: TaskParams) => {
+    hyperPage.aiAction = (instruction: string, params?: PerformTaskParams) => {
+      this.warnAiActionDeprecation();
       return executeSingleActionWithRetry(instruction, params);
     };
 
@@ -1577,8 +4050,9 @@ export class HyperAgent<T extends BrowserProviders = "Local"> {
       tokenLimit: this.tokenLimit,
       llm: this.llm,
       mcpClient: this.mcpClient,
-      variables: Object.values(this._variables),
+      variables: this.getVariableValues(),
       cdpActionsEnabled: this.cdpActionsEnabled,
+      filterAdTrackingFrames: this.filterAdTrackingFrames,
     };
     attachCachedActionHelpers(deps, hyperPage);
 
@@ -1587,7 +4061,21 @@ export class HyperAgent<T extends BrowserProviders = "Local"> {
     hyperPage.aiAsync = (task: string, params?: TaskParams) =>
       this.executeTaskAsync(task, params, getActivePage());
 
-    hyperPage.extract = async (task, outputSchema, params) => {
+    hyperPage.extract = async <
+      T extends z.ZodType<unknown> | undefined = undefined,
+    >(
+      task?: string,
+      outputSchema?: T,
+      params?: Omit<TaskParams, "outputSchema">
+    ): Promise<T extends z.ZodType<unknown> ? z.infer<T> : string> => {
+      const normalizedTask =
+        typeof task === "string" ? task.trim() : undefined;
+      if (typeof task === "string" && (!normalizedTask || normalizedTask.length === 0)) {
+        throw new HyperagentError(
+          "Task description must be non-empty when provided",
+          400
+        );
+      }
       if (!task && !outputSchema) {
         throw new HyperagentError(
           "No task description or output schema specified",
@@ -1595,44 +4083,43 @@ export class HyperAgent<T extends BrowserProviders = "Local"> {
         );
       }
       const taskParams: TaskParams = {
-        maxSteps: params?.maxSteps ?? 2,
         ...params,
+        maxSteps: this.normalizeRetryCount(params?.maxSteps, 2, 20),
         outputSchema,
       };
-      if (task) {
+      if (normalizedTask) {
         const res = await this.executeTask(
-          `You have to perform an extraction on the current page. You have to perform the extraction according to the task: ${task}. Make sure your final response only contains the extracted content`,
+          `You have to perform an extraction on the current page. You have to perform the extraction according to the task: ${normalizedTask}. Make sure your final response only contains the extracted content`,
           taskParams,
           getActivePage()
         );
-        if (outputSchema) {
-          const outputText = res.output;
-          if (typeof outputText !== "string" || outputText === "") {
-            throw new Error(
-              `Extract failed: Agent did not complete with output. Task status: ${res.status}. Check debug output for details.`
-            );
-          }
-          return JSON.parse(outputText);
-        }
-        const outputText = res.output;
-        if (typeof outputText !== "string" || outputText === "") {
-          throw new Error(
-            `Extract failed: Agent did not complete with output. Task status: ${res.status}. Check debug output for details.`
-          );
+        if (!outputSchema) {
+          return parseExtractOutput(res.output, res.status) as T extends z.ZodType<unknown>
+            ? z.infer<T>
+            : string;
         }
-        return outputText;
+        return parseExtractOutput(
+          res.output,
+          res.status,
+          outputSchema as z.ZodType<unknown>
+        ) as T extends z.ZodType<unknown> ? z.infer<T> : string;
       } else {
         const res = await this.executeTask(
           "You have to perform a data extraction on the current page. Make sure your final response only contains the extracted content",
           taskParams,
           getActivePage()
         );
-        if (typeof res.output !== "string" || res.output === "") {
-          throw new Error(
-            `Extract failed: Agent did not complete with output. Task status: ${res.status}. Check debug output for details.`
+        if (!outputSchema) {
+          throw new HyperagentError(
+            "No output schema provided for schema-only extraction",
+            400
           );
         }
-        return JSON.parse(res.output);
+        return parseExtractOutput(
+          res.output,
+          res.status,
+          outputSchema
+        ) as T extends z.ZodType<unknown> ? z.infer<T> : string;
       }
     };
     return hyperPage;
diff --git a/src/agent/mcp/client.test.ts b/src/agent/mcp/client.test.ts
new file mode 100644
index 00000000..d7eb03bb
--- /dev/null
+++ b/src/agent/mcp/client.test.ts
@@ -0,0 +1,3024 @@
+import {
+  MCPClient,
+  normalizeDiscoveredMCPTools,
+  normalizeMCPListToolsPayload,
+  normalizeMCPToolDescription,
+  normalizeMCPToolParams,
+  stringifyMCPPayload,
+} from "@/agent/mcp/client";
+import { MCPServerConfig } from "@/types/config";
+import { Client } from "@modelcontextprotocol/sdk/client/index.js";
+import { StdioClientTransport } from "@modelcontextprotocol/sdk/client/stdio.js";
+import { Tool } from "@modelcontextprotocol/sdk/types";
+
+function setServersForClient(client: MCPClient, servers: Map<string, unknown>): void {
+  (client as unknown as { servers: Map<string, unknown> }).servers = servers;
+}
+
+function createTool(name: string): Tool {
+  return {
+    name,
+    description: `${name} description`,
+    inputSchema: { type: "object", properties: {} },
+  } as Tool;
+}
+
+describe("normalizeDiscoveredMCPTools", () => {
+  it("normalizes discovered tool names and applies include filtering", () => {
+    const normalized = normalizeDiscoveredMCPTools(
+      [createTool(" search "), createTool("notes")],
+      { includeTools: ["search"] }
+    );
+    expect(normalized.map((entry) => entry.normalizedName)).toEqual(["search"]);
+  });
+
+  it("applies include filtering case-insensitively", () => {
+    const normalized = normalizeDiscoveredMCPTools(
+      [createTool("search"), createTool("notes")],
+      { includeTools: ["Search"] }
+    );
+    expect(normalized.map((entry) => entry.normalizedName)).toEqual(["search"]);
+  });
+
+  it("applies exclude filtering after normalization", () => {
+    const normalized = normalizeDiscoveredMCPTools(
+      [createTool("search"), createTool(" notes ")],
+      { excludeTools: ["notes"] }
+    );
+    expect(normalized.map((entry) => entry.normalizedName)).toEqual(["search"]);
+  });
+
+  it("applies exclude filtering case-insensitively", () => {
+    const normalized = normalizeDiscoveredMCPTools(
+      [createTool("Search"), createTool("notes")],
+      { excludeTools: ["search"] }
+    );
+    expect(normalized.map((entry) => entry.normalizedName)).toEqual(["notes"]);
+  });
+
+  it("rejects duplicate discovered tool names after normalization", () => {
+    expect(() =>
+      normalizeDiscoveredMCPTools(
+        [createTool("search"), createTool(" search ")],
+        {}
+      )
+    ).toThrow('MCP server returned duplicate tool name "search"');
+  });
+
+  it("rejects case-variant discovered tool names after normalization", () => {
+    expect(() =>
+      normalizeDiscoveredMCPTools(
+        [createTool("Search"), createTool("search")],
+        {}
+      )
+    ).toThrow(
+      'MCP server returned duplicate tool name "search" after case normalization (conflicts with "Search")'
+    );
+  });
+
+  it("rejects discovered tool names with unsupported control characters", () => {
+    expect(() =>
+      normalizeDiscoveredMCPTools([createTool("sea\nrch")], {})
+    ).toThrow("MCP tool name contains unsupported control characters");
+  });
+
+  it("rejects discovered tools with non-string names", () => {
+    expect(() =>
+      normalizeDiscoveredMCPTools(
+        [
+          {
+            description: "bad tool",
+            inputSchema: { type: "object", properties: {} },
+          } as unknown as Tool,
+        ],
+        {}
+      )
+    ).toThrow("MCP tool name must be a string");
+  });
+
+  it("throws actionable error when includeTools filter matches nothing", () => {
+    expect(() =>
+      normalizeDiscoveredMCPTools([createTool("search"), createTool("notes")], {
+        includeTools: ["calendar"],
+      })
+    ).toThrow(
+      "No MCP tools matched includeTools filter (calendar). Available tools: search, notes."
+    );
+  });
+
+  it("truncates includeTools mismatch diagnostics for large tool sets", () => {
+    const tools = Array.from({ length: 14 }, (_, index) =>
+      createTool(`tool-${index}`)
+    );
+    const includeTools = Array.from({ length: 12 }, (_, index) => `missing-${index}`);
+    expect(() =>
+      normalizeDiscoveredMCPTools(tools, {
+        includeTools,
+      })
+    ).toThrow(
+      "No MCP tools matched includeTools filter (missing-0, missing-1, missing-2, missing-3, missing-4, missing-5, missing-6, missing-7, missing-8, missing-9, ... (+2 more)). Available tools: tool-0, tool-1, tool-2, tool-3, tool-4, tool-5, tool-6, tool-7, tool-8, tool-9, ... (+4 more)."
+    );
+  });
+
+  it("rejects duplicate includeTools entries after normalization", () => {
+    expect(() =>
+      normalizeDiscoveredMCPTools([createTool("search")], {
+        includeTools: ["search", " Search "],
+      })
+    ).toThrow(
+      'MCP includeTools contains duplicate tool name "Search" after normalization'
+    );
+  });
+
+  it("rejects overlapping includeTools and excludeTools entries", () => {
+    expect(() =>
+      normalizeDiscoveredMCPTools([createTool("search"), createTool("notes")], {
+        includeTools: ["search"],
+        excludeTools: [" Search "],
+      })
+    ).toThrow("MCP includeTools and excludeTools overlap on: Search");
+  });
+});
+
+describe("normalizeMCPListToolsPayload", () => {
+  it("returns tools array when payload shape is valid", () => {
+    const tools = [createTool("search"), createTool("notes")];
+    expect(normalizeMCPListToolsPayload({ tools })).toEqual(tools);
+  });
+
+  it("rejects payloads without a tools array", () => {
+    expect(() => normalizeMCPListToolsPayload({})).toThrow(
+      "Invalid MCP listTools response: expected a tools array"
+    );
+  });
+
+  it("rejects payloads when tools own-property checks throw", () => {
+    const payload = new Proxy(
+      {},
+      {
+        getOwnPropertyDescriptor(): PropertyDescriptor {
+          throw new Error("descriptor trap");
+        },
+      }
+    );
+    expect(() =>
+      normalizeMCPListToolsPayload(payload as Record<string, unknown>)
+    ).toThrow("Invalid MCP listTools response: expected a tools array");
+  });
+
+  it("rejects oversized tools payloads", () => {
+    const tools = Array.from({ length: 501 }, (_, index) =>
+      createTool(`tool-${index}`)
+    );
+    expect(() => normalizeMCPListToolsPayload({ tools })).toThrow(
+      "Invalid MCP listTools response: received more than 500 tools"
+    );
+  });
+
+  it("rejects non-object tool entries", () => {
+    expect(() =>
+      normalizeMCPListToolsPayload({
+        tools: [createTool("search"), "bad-entry"],
+      })
+    ).toThrow(
+      "Invalid MCP listTools response: each tool entry must be an object"
+    );
+  });
+
+  it("rejects listTools payloads when tools getter throws", () => {
+    const payload = {};
+    Object.defineProperty(payload, "tools", {
+      get(): unknown {
+        throw new Error("tools read failed");
+      },
+    });
+
+    expect(() => normalizeMCPListToolsPayload(payload)).toThrow(
+      "Invalid MCP listTools response: unable to read tools array"
+    );
+  });
+
+  it("surfaces wrapped listTools payload normalization errors from connectToServer", async () => {
+    const connectSpy = jest
+      .spyOn(Client.prototype, "connect")
+      .mockResolvedValue(undefined);
+    const listToolsSpy = jest.spyOn(Client.prototype, "listTools").mockResolvedValue(
+      {} as unknown as Awaited<ReturnType<Client["listTools"]>>
+    );
+    const closeSpy = jest
+      .spyOn(StdioClientTransport.prototype, "close")
+      .mockResolvedValue(undefined);
+    const errorSpy = jest.spyOn(console, "error").mockImplementation(() => {});
+    const mcpClient = new MCPClient(false);
+
+    try {
+      await expect(
+        mcpClient.connectToServer({
+          command: "npx",
+        })
+      ).rejects.toThrow(
+        "Invalid MCP listTools response: expected a tools array"
+      );
+      expect(closeSpy).toHaveBeenCalledTimes(1);
+    } finally {
+      connectSpy.mockRestore();
+      listToolsSpy.mockRestore();
+      closeSpy.mockRestore();
+      errorSpy.mockRestore();
+    }
+  });
+
+  it("truncates oversized wrapped listTools normalization diagnostics", async () => {
+    const connectSpy = jest
+      .spyOn(Client.prototype, "connect")
+      .mockResolvedValue(undefined);
+    const oversizedTools = new Proxy(
+      [],
+      {
+        get(target, prop, receiver): unknown {
+          if (prop === "length") {
+            throw new Error("x".repeat(2_000));
+          }
+          return Reflect.get(target, prop, receiver);
+        },
+      }
+    );
+    const listToolsSpy = jest.spyOn(Client.prototype, "listTools").mockResolvedValue(
+      {
+        tools: oversizedTools,
+      } as unknown as Awaited<ReturnType<Client["listTools"]>>
+    );
+    const closeSpy = jest
+      .spyOn(StdioClientTransport.prototype, "close")
+      .mockResolvedValue(undefined);
+    const errorSpy = jest.spyOn(console, "error").mockImplementation(() => {});
+    const mcpClient = new MCPClient(false);
+
+    try {
+      await expect(
+        mcpClient.connectToServer({
+          command: "npx",
+        })
+      ).rejects.toThrow(/\[truncated/);
+      expect(closeSpy).toHaveBeenCalledTimes(1);
+    } finally {
+      connectSpy.mockRestore();
+      listToolsSpy.mockRestore();
+      closeSpy.mockRestore();
+      errorSpy.mockRestore();
+    }
+  });
+});
+
+describe("normalizeMCPToolParams", () => {
+  it("returns object inputs unchanged", () => {
+    const input = { query: "laptops", limit: 5 };
+    expect(normalizeMCPToolParams(input)).toEqual(input);
+  });
+
+  it("trims parameter keys before forwarding to tool execution", () => {
+    expect(
+      normalizeMCPToolParams({
+        "  query  ": "weather",
+      })
+    ).toEqual({
+      query: "weather",
+    });
+  });
+
+  it("normalizes internal key whitespace before forwarding params", () => {
+    expect(
+      normalizeMCPToolParams({
+        " user   id ": "42",
+      })
+    ).toEqual({
+      "user id": "42",
+    });
+  });
+
+  it("parses valid JSON object strings", () => {
+    const json = "{\"query\":\"weather\",\"units\":\"metric\"}";
+    expect(normalizeMCPToolParams(json)).toEqual({
+      query: "weather",
+      units: "metric",
+    });
+  });
+
+  it("throws for invalid JSON strings", () => {
+    expect(() => normalizeMCPToolParams("{invalid")).toThrow(
+      "Invalid MCP tool params JSON string"
+    );
+  });
+
+  it("throws clear error for empty JSON strings", () => {
+    expect(() => normalizeMCPToolParams("   ")).toThrow(
+      "Invalid MCP tool params JSON string: input is empty"
+    );
+  });
+
+  it("throws when parsed JSON is not an object", () => {
+    expect(() => normalizeMCPToolParams("[1,2,3]")).toThrow(
+      "must parse to a JSON object"
+    );
+  });
+
+  it("rejects non-object params at the root level for direct inputs", () => {
+    expect(() =>
+      normalizeMCPToolParams(42 as unknown as Record<string, unknown>)
+    ).toThrow("MCP tool params must be a JSON object at the root level");
+  });
+
+  it("rejects array params at the root level for direct inputs", () => {
+    expect(() =>
+      normalizeMCPToolParams([] as unknown as Record<string, unknown>)
+    ).toThrow("MCP tool params must be a JSON object at the root level");
+  });
+
+  it("rejects oversized JSON string params before parsing", () => {
+    const oversized = `{"data":"${"x".repeat(100_010)}"}`;
+    expect(() => normalizeMCPToolParams(oversized)).toThrow(
+      "Invalid MCP tool params JSON string: exceeds 100000 characters"
+    );
+  });
+
+  it("rejects JSON string params with unsupported control characters", () => {
+    expect(() => normalizeMCPToolParams("{\"query\":\"a\u0007b\"}")).toThrow(
+      "Invalid MCP tool params JSON string: contains unsupported control characters"
+    );
+  });
+
+  it("rejects reserved object keys in parsed JSON params", () => {
+    expect(() => normalizeMCPToolParams('{"__proto__":{"x":1}}')).toThrow(
+      'MCP tool params cannot include reserved key "__proto__"'
+    );
+  });
+
+  it("rejects reserved object keys in direct object params", () => {
+    expect(() =>
+      normalizeMCPToolParams({
+        constructor: "bad",
+      })
+    ).toThrow('MCP tool params cannot include reserved key "constructor"');
+  });
+
+  it("rejects reserved object keys nested inside payloads", () => {
+    expect(() =>
+      normalizeMCPToolParams('{"outer":{"__proto__":{"x":1}}}')
+    ).toThrow('MCP tool params cannot include reserved key "__proto__"');
+  });
+
+  it("rejects keys with control characters", () => {
+    expect(() =>
+      normalizeMCPToolParams({
+        "bad\u0007key": "value",
+      })
+    ).toThrow("MCP tool params cannot include keys with control characters");
+  });
+
+  it("rejects keys with newline characters", () => {
+    expect(() =>
+      normalizeMCPToolParams({
+        "bad\nkey": "value",
+      })
+    ).toThrow("MCP tool params cannot include keys with control characters");
+  });
+
+  it("rejects keys that exceed maximum length", () => {
+    expect(() =>
+      normalizeMCPToolParams({
+        [String.raw`${"k".repeat(257)}`]: "value",
+      })
+    ).toThrow("MCP tool params cannot include keys longer than 256 characters");
+  });
+
+  it("rejects oversized object collections", () => {
+    const oversized = Object.fromEntries(
+      Array.from({ length: 501 }, (_, index) => [`k${index}`, index])
+    );
+    expect(() => normalizeMCPToolParams(oversized)).toThrow(
+      "MCP tool params cannot include collections with more than 500 entries"
+    );
+  });
+
+  it("rejects oversized array collections", () => {
+    expect(() =>
+      normalizeMCPToolParams({
+        values: Array.from({ length: 501 }, (_, index) => index),
+      })
+    ).toThrow(
+      "MCP tool params cannot include collections with more than 500 entries"
+    );
+  });
+
+  it("rejects string values with control characters", () => {
+    expect(() =>
+      normalizeMCPToolParams({
+        query: "a\u0007b",
+      })
+    ).toThrow(
+      "MCP tool params cannot include unsupported control characters in string values"
+    );
+  });
+
+  it("rejects non-finite number values in direct object params", () => {
+    expect(() =>
+      normalizeMCPToolParams({
+        score: Number.NaN,
+      })
+    ).toThrow("MCP tool params cannot include non-finite number values");
+  });
+
+  it("rejects escaped control characters after JSON parsing", () => {
+    expect(() =>
+      normalizeMCPToolParams('{"query":"a\\u0007b"}')
+    ).toThrow(
+      "MCP tool params cannot include unsupported control characters in string values"
+    );
+  });
+
+  it("rejects non-finite number values after JSON parsing", () => {
+    expect(() =>
+      normalizeMCPToolParams('{"score":1e309}')
+    ).toThrow("MCP tool params cannot include non-finite number values");
+  });
+
+  it("rejects oversized string values in direct object params", () => {
+    expect(() =>
+      normalizeMCPToolParams({
+        query: "x".repeat(20_001),
+      })
+    ).toThrow(
+      "MCP tool params cannot include string values longer than 20000 characters"
+    );
+  });
+
+  it("rejects oversized string values after JSON parsing", () => {
+    expect(() =>
+      normalizeMCPToolParams(`{"query":"${"x".repeat(20_001)}"}`)
+    ).toThrow(
+      "MCP tool params cannot include string values longer than 20000 characters"
+    );
+  });
+
+  it("normalizes non-JSON primitive values in object params", () => {
+    const token = Symbol("token");
+    const sampleFunction = function sampleFunction(): void {
+      // noop
+    };
+
+    expect(
+      normalizeMCPToolParams({
+        bigintValue: BigInt(42),
+        symbolValue: token,
+        functionValue: sampleFunction,
+      })
+    ).toEqual({
+      bigintValue: "42n",
+      symbolValue: "Symbol(token)",
+      functionValue: "[Function sampleFunction]",
+    });
+  });
+
+  it("normalizes Date, Map, and Set values safely", () => {
+    const date = new Date("2025-01-01T00:00:00.000Z");
+    const map = new Map([["key", "value"]]);
+    const set = new Set(["alpha", 2]);
+
+    expect(
+      normalizeMCPToolParams({
+        createdAt: date,
+        metadata: map as unknown as Record<string, unknown>,
+        tags: set as unknown as Record<string, unknown>,
+      })
+    ).toEqual({
+      createdAt: "2025-01-01T00:00:00.000Z",
+      metadata: { key: "value" },
+      tags: ["alpha", 2],
+    });
+  });
+
+  it("rejects oversized non-plain object diagnostic values", () => {
+    class CustomPayload {
+      payload = "x".repeat(20_500);
+    }
+
+    expect(() =>
+      normalizeMCPToolParams({
+        metadata: new CustomPayload() as unknown as Record<string, unknown>,
+      })
+    ).toThrow(
+      "MCP tool params cannot include string values longer than 20000 characters"
+    );
+  });
+
+  it("rejects duplicate keys when map keys collide after trimming", () => {
+    const map = new Map<unknown, unknown>([
+      [" key ", "first"],
+      ["key", "second"],
+    ]);
+    expect(() =>
+      normalizeMCPToolParams({
+        metadata: map as unknown as Record<string, unknown>,
+      })
+    ).toThrow('MCP tool params cannot include duplicate key after trimming: "key"');
+  });
+
+  it("rejects duplicate map keys after collapsing internal whitespace", () => {
+    const map = new Map<unknown, unknown>([
+      ["user   id", "first"],
+      ["user id", "second"],
+    ]);
+    expect(() =>
+      normalizeMCPToolParams({
+        metadata: map as unknown as Record<string, unknown>,
+      })
+    ).toThrow(
+      'MCP tool params cannot include duplicate key after trimming: "user id"'
+    );
+  });
+
+  it("rejects map keys with newline characters", () => {
+    const map = new Map<unknown, unknown>([["bad\nkey", "value"]]);
+    expect(() =>
+      normalizeMCPToolParams({
+        metadata: map as unknown as Record<string, unknown>,
+      })
+    ).toThrow("MCP tool params cannot include keys with control characters");
+  });
+
+  it("rejects map keys that exceed maximum length", () => {
+    const map = new Map<unknown, unknown>([[`${"k".repeat(257)}`, "value"]]);
+    expect(() =>
+      normalizeMCPToolParams({
+        metadata: map as unknown as Record<string, unknown>,
+      })
+    ).toThrow("MCP tool params cannot include keys longer than 256 characters");
+  });
+
+  it("rejects oversized map and set collections", () => {
+    const oversizedMap = new Map<unknown, unknown>(
+      Array.from({ length: 501 }, (_, index) => [`k${index}`, index])
+    );
+    const oversizedSet = new Set(Array.from({ length: 501 }, (_, index) => index));
+
+    expect(() =>
+      normalizeMCPToolParams({
+        metadata: oversizedMap as unknown as Record<string, unknown>,
+      })
+    ).toThrow(
+      "MCP tool params cannot include collections with more than 500 entries"
+    );
+    expect(() =>
+      normalizeMCPToolParams({
+        values: oversizedSet as unknown as Record<string, unknown>,
+      })
+    ).toThrow(
+      "MCP tool params cannot include collections with more than 500 entries"
+    );
+  });
+
+  it("rejects circular references in direct object params", () => {
+    const circular: { self?: unknown } = {};
+    circular.self = circular;
+    expect(() => normalizeMCPToolParams(circular)).toThrow(
+      "MCP tool params cannot include circular references"
+    );
+  });
+
+  it("rejects circular references in array params", () => {
+    const circularArray: unknown[] = [];
+    circularArray.push(circularArray);
+    expect(() =>
+      normalizeMCPToolParams({
+        items: circularArray,
+      })
+    ).toThrow("MCP tool params cannot include circular references");
+  });
+
+  it("rejects reserved keys case-insensitively after trimming", () => {
+    expect(() =>
+      normalizeMCPToolParams({
+        "  Constructor  ": "bad",
+      })
+    ).toThrow('MCP tool params cannot include reserved key "  Constructor  "');
+  });
+
+  it("rejects empty keys after trimming", () => {
+    expect(() =>
+      normalizeMCPToolParams({
+        "   ": "bad",
+      })
+    ).toThrow("MCP tool params cannot include empty keys");
+  });
+
+  it("rejects duplicate keys after trimming", () => {
+    expect(() =>
+      normalizeMCPToolParams({
+        query: "weather",
+        " query ": "finance",
+      })
+    ).toThrow('MCP tool params cannot include duplicate key after trimming: "query"');
+  });
+
+  it("rejects duplicate keys after collapsing internal whitespace", () => {
+    expect(() =>
+      normalizeMCPToolParams({
+        "user   id": "weather",
+        "user id": "finance",
+      })
+    ).toThrow(
+      'MCP tool params cannot include duplicate key after trimming: "user id"'
+    );
+  });
+
+  it("rejects params that exceed maximum nesting depth", () => {
+    const root: Record<string, unknown> = {};
+    let cursor = root;
+    for (let depth = 0; depth < 35; depth += 1) {
+      cursor.child = {};
+      cursor = cursor.child as Record<string, unknown>;
+    }
+
+    expect(() =>
+      normalizeMCPToolParams({
+        payload: root,
+      })
+    ).toThrow("MCP tool params exceed maximum nesting depth of 25");
+  });
+
+  it("allows repeated shared object references across sibling fields", () => {
+    const shared = { query: "weather" };
+    expect(
+      normalizeMCPToolParams({
+        first: shared,
+        second: shared,
+      })
+    ).toEqual({
+      first: { query: "weather" },
+      second: { query: "weather" },
+    });
+  });
+});
+
+describe("stringifyMCPPayload", () => {
+  it("serializes plain objects to JSON", () => {
+    expect(stringifyMCPPayload({ ok: true })).toBe('{"ok":true}');
+  });
+
+  it("falls back to formatted unknown error for circular payloads", () => {
+    const circular: { self?: unknown } = {};
+    circular.self = circular;
+    expect(stringifyMCPPayload(circular)).toBe('{"self":"[Circular]"}');
+  });
+
+  it("truncates oversized payload strings to bounded length", () => {
+    const payload = { text: "x".repeat(5000) };
+    const output = stringifyMCPPayload(payload);
+    expect(output).toContain("[truncated]");
+    expect(output.length).toBeLessThanOrEqual(4016);
+  });
+});
+
+describe("normalizeMCPToolDescription", () => {
+  it("returns empty description for non-string values", () => {
+    expect(normalizeMCPToolDescription(undefined)).toBe("");
+    expect(normalizeMCPToolDescription(42)).toBe("");
+  });
+
+  it("sanitizes control characters and collapses whitespace", () => {
+    expect(normalizeMCPToolDescription(" hello\n\tworld\u0007 ")).toBe(
+      "hello world"
+    );
+  });
+
+  it("truncates oversized tool descriptions", () => {
+    const normalized = normalizeMCPToolDescription(`tool ${"x".repeat(2_100)}`);
+    expect(normalized).toContain("[truncated");
+    expect(normalized.length).toBeLessThan(2_100);
+  });
+});
+
+describe("MCPClient.connectToServer validation", () => {
+  function getServers(client: MCPClient): Map<string, unknown> {
+    return (client as unknown as { servers: Map<string, unknown> }).servers;
+  }
+
+  it("closes pending transport when connection fails after connect", async () => {
+    const connectSpy = jest
+      .spyOn(Client.prototype, "connect")
+      .mockResolvedValue(undefined);
+    const listToolsSpy = jest
+      .spyOn(Client.prototype, "listTools")
+      .mockRejectedValue(new Error("listTools failed"));
+    const closeSpy = jest
+      .spyOn(StdioClientTransport.prototype, "close")
+      .mockResolvedValue(undefined);
+    const errorSpy = jest.spyOn(console, "error").mockImplementation(() => {});
+    const mcpClient = new MCPClient(false);
+
+    try {
+      await expect(
+        mcpClient.connectToServer({
+          command: "npx",
+        })
+      ).rejects.toThrow("listTools failed");
+      expect(closeSpy).toHaveBeenCalledTimes(1);
+    } finally {
+      connectSpy.mockRestore();
+      listToolsSpy.mockRestore();
+      closeSpy.mockRestore();
+      errorSpy.mockRestore();
+    }
+  });
+
+  it("closes pending transport when server registry write traps", async () => {
+    const connectSpy = jest
+      .spyOn(Client.prototype, "connect")
+      .mockResolvedValue(undefined);
+    const listToolsSpy = jest.spyOn(Client.prototype, "listTools").mockResolvedValue({
+      tools: [createTool("search")],
+    } as unknown as Awaited<ReturnType<Client["listTools"]>>);
+    const closeSpy = jest
+      .spyOn(StdioClientTransport.prototype, "close")
+      .mockResolvedValue(undefined);
+    const errorSpy = jest.spyOn(console, "error").mockImplementation(() => {});
+    const mcpClient = new MCPClient(false);
+    setServersForClient(
+      mcpClient,
+      {
+        has: (): boolean => false,
+        keys: (): IterableIterator<string> => [][Symbol.iterator](),
+        set: (): never => {
+          throw new Error("x".repeat(2_000));
+        },
+      } as unknown as Map<string, unknown>
+    );
+
+    try {
+      await expect(
+        mcpClient.connectToServer({
+          command: "npx",
+        })
+      ).rejects.toThrow(/\[truncated/);
+      expect(closeSpy).toHaveBeenCalledTimes(1);
+    } finally {
+      connectSpy.mockRestore();
+      listToolsSpy.mockRestore();
+      closeSpy.mockRestore();
+      errorSpy.mockRestore();
+    }
+  });
+
+  it("truncates oversized connect failures before rethrowing", async () => {
+    const connectSpy = jest
+      .spyOn(Client.prototype, "connect")
+      .mockRejectedValue(new Error("x".repeat(2_000)));
+    const closeSpy = jest
+      .spyOn(StdioClientTransport.prototype, "close")
+      .mockResolvedValue(undefined);
+    const errorSpy = jest.spyOn(console, "error").mockImplementation(() => {});
+    const mcpClient = new MCPClient(false);
+
+    try {
+      await expect(
+        mcpClient.connectToServer({
+          command: "npx",
+        })
+      ).rejects.toThrow(/\[truncated/);
+      expect(closeSpy).toHaveBeenCalledTimes(1);
+    } finally {
+      connectSpy.mockRestore();
+      closeSpy.mockRestore();
+      errorSpy.mockRestore();
+    }
+  });
+
+  it("sanitizes control characters in connect failure diagnostics", async () => {
+    const connectSpy = jest.spyOn(Client.prototype, "connect").mockRejectedValue(
+      new Error(`connect\u0000\n${"x".repeat(2_000)}`)
+    );
+    const closeSpy = jest
+      .spyOn(StdioClientTransport.prototype, "close")
+      .mockResolvedValue(undefined);
+    const errorSpy = jest.spyOn(console, "error").mockImplementation(() => {});
+    const mcpClient = new MCPClient(false);
+
+    try {
+      await mcpClient
+        .connectToServer({
+          command: "npx",
+        })
+        .then(() => {
+          throw new Error("expected connectToServer to reject");
+        })
+        .catch((error) => {
+          const message = String(error instanceof Error ? error.message : error);
+          expect(message).toContain("[truncated");
+          expect(message).not.toContain("\u0000");
+          expect(message).not.toContain("\n");
+          expect(message.length).toBeLessThan(700);
+        });
+      expect(closeSpy).toHaveBeenCalledTimes(1);
+    } finally {
+      connectSpy.mockRestore();
+      closeSpy.mockRestore();
+      errorSpy.mockRestore();
+    }
+  });
+
+  it("stores normalized stdio config values for connected servers", async () => {
+    const connectSpy = jest
+      .spyOn(Client.prototype, "connect")
+      .mockResolvedValue(undefined);
+    const listToolsSpy = jest.spyOn(Client.prototype, "listTools").mockResolvedValue({
+      tools: [createTool("search")],
+    } as unknown as Awaited<ReturnType<Client["listTools"]>>);
+    const errorSpy = jest.spyOn(console, "error").mockImplementation(() => {});
+    const mcpClient = new MCPClient(false);
+
+    try {
+      const { serverId } = await mcpClient.connectToServer({
+        id: "  server-a  ",
+        command: "  npx  ",
+        args: ["  -y  ", " server "],
+        env: {
+          TOKEN: "value",
+        },
+        includeTools: [" Search "],
+        excludeTools: [" notes "],
+      });
+      const server = getServers(mcpClient).get(serverId) as
+        | { config?: MCPServerConfig }
+        | undefined;
+      expect(server?.config).toEqual({
+        id: "server-a",
+        connectionType: "stdio",
+        command: "npx",
+        args: ["-y", "server"],
+        env: {
+          TOKEN: "value",
+        },
+        includeTools: ["Search"],
+        excludeTools: ["notes"],
+      });
+    } finally {
+      connectSpy.mockRestore();
+      listToolsSpy.mockRestore();
+      errorSpy.mockRestore();
+    }
+  });
+
+  it("stores normalized sse config values for connected servers", async () => {
+    const connectSpy = jest
+      .spyOn(Client.prototype, "connect")
+      .mockResolvedValue(undefined);
+    const listToolsSpy = jest.spyOn(Client.prototype, "listTools").mockResolvedValue({
+      tools: [createTool("search")],
+    } as unknown as Awaited<ReturnType<Client["listTools"]>>);
+    const errorSpy = jest.spyOn(console, "error").mockImplementation(() => {});
+    const mcpClient = new MCPClient(false);
+
+    try {
+      const { serverId } = await mcpClient.connectToServer({
+        id: "server-sse",
+        connectionType: "sse",
+        sseUrl: " https://example.com/events ",
+        sseHeaders: {
+          Authorization: " Bearer token ",
+        },
+      });
+      const server = getServers(mcpClient).get(serverId) as
+        | { config?: MCPServerConfig }
+        | undefined;
+      expect(server?.config).toEqual({
+        id: "server-sse",
+        connectionType: "sse",
+        sseUrl: "https://example.com/events",
+        sseHeaders: {
+          Authorization: "Bearer token",
+        },
+      });
+    } finally {
+      connectSpy.mockRestore();
+      listToolsSpy.mockRestore();
+      errorSpy.mockRestore();
+    }
+  });
+
+  it("rejects non-object server configs", async () => {
+    const mcpClient = new MCPClient(false);
+    const errorSpy = jest.spyOn(console, "error").mockImplementation(() => {});
+    try {
+      await expect(
+        mcpClient.connectToServer(null as unknown as MCPServerConfig)
+      ).rejects.toThrow("MCP server config must be an object");
+      await expect(
+        mcpClient.connectToServer([] as unknown as MCPServerConfig)
+      ).rejects.toThrow("MCP server config must be an object");
+    } finally {
+      errorSpy.mockRestore();
+    }
+  });
+
+  it("rejects proxy server configs that throw during shape checks", async () => {
+    const mcpClient = new MCPClient(false);
+    const errorSpy = jest.spyOn(console, "error").mockImplementation(() => {});
+    const proxyConfig = new Proxy(
+      {},
+      {
+        getPrototypeOf(): object | null {
+          throw new Error("prototype trap");
+        },
+      }
+    );
+
+    try {
+      await expect(
+        mcpClient.connectToServer(proxyConfig as unknown as MCPServerConfig)
+      ).rejects.toThrow("MCP server config must be an object");
+    } finally {
+      errorSpy.mockRestore();
+    }
+  });
+
+  it("throws when connecting with duplicate server id", async () => {
+    const mcpClient = new MCPClient(false);
+    setServersForClient(
+      mcpClient,
+      new Map([
+        [
+          "server-1",
+          {
+            tools: new Map(),
+          },
+        ],
+      ])
+    );
+    const errorSpy = jest.spyOn(console, "error").mockImplementation(() => {});
+
+    try {
+      await expect(
+        mcpClient.connectToServer({
+          id: "server-1",
+          command: "echo",
+        })
+      ).rejects.toThrow('MCP server with ID "server-1" is already connected');
+      expect(errorSpy).toHaveBeenCalledWith(
+        'Failed to connect to MCP server: MCP server with ID "server-1" is already connected'
+      );
+    } finally {
+      errorSpy.mockRestore();
+    }
+  });
+
+  it("rejects duplicate server id matches case-insensitively", async () => {
+    const mcpClient = new MCPClient(false);
+    setServersForClient(
+      mcpClient,
+      new Map([
+        [
+          "Server-1",
+          {
+            tools: new Map(),
+          },
+        ],
+      ])
+    );
+    const errorSpy = jest.spyOn(console, "error").mockImplementation(() => {});
+
+    try {
+      await expect(
+        mcpClient.connectToServer({
+          id: " server-1 ",
+          command: "echo",
+        })
+      ).rejects.toThrow('MCP server with ID "server-1" is already connected');
+    } finally {
+      errorSpy.mockRestore();
+    }
+  });
+
+  it("rejects blank server ids when provided programmatically", async () => {
+    const mcpClient = new MCPClient(false);
+    const errorSpy = jest.spyOn(console, "error").mockImplementation(() => {});
+    try {
+      await expect(
+        mcpClient.connectToServer({
+          id: "   ",
+          command: "echo",
+        })
+      ).rejects.toThrow("MCP server id must be a non-empty string when provided");
+    } finally {
+      errorSpy.mockRestore();
+    }
+  });
+
+  it("rejects non-string server ids when provided programmatically", async () => {
+    const mcpClient = new MCPClient(false);
+    const errorSpy = jest.spyOn(console, "error").mockImplementation(() => {});
+    try {
+      await expect(
+        mcpClient.connectToServer({
+          id: 42 as unknown as string,
+          command: "echo",
+        })
+      ).rejects.toThrow("MCP server id must be a string when provided");
+    } finally {
+      errorSpy.mockRestore();
+    }
+  });
+
+  it("rejects server ids with control characters", async () => {
+    const mcpClient = new MCPClient(false);
+    const errorSpy = jest.spyOn(console, "error").mockImplementation(() => {});
+    try {
+      await expect(
+        mcpClient.connectToServer({
+          id: "server\n1",
+          command: "echo",
+        })
+      ).rejects.toThrow("MCP server id contains unsupported control characters");
+    } finally {
+      errorSpy.mockRestore();
+    }
+  });
+
+  it("rejects oversized server ids", async () => {
+    const mcpClient = new MCPClient(false);
+    const errorSpy = jest.spyOn(console, "error").mockImplementation(() => {});
+    try {
+      await expect(
+        mcpClient.connectToServer({
+          id: `server-${"x".repeat(130)}`,
+          command: "echo",
+        })
+      ).rejects.toThrow("MCP server id exceeds 128 characters");
+    } finally {
+      errorSpy.mockRestore();
+    }
+  });
+
+  it("rejects invalid connectionType values", async () => {
+    const mcpClient = new MCPClient(false);
+    const errorSpy = jest.spyOn(console, "error").mockImplementation(() => {});
+    try {
+      await expect(
+        mcpClient.connectToServer({
+          command: "echo",
+          connectionType: " websocket " as unknown as "stdio",
+        })
+      ).rejects.toThrow(
+        'MCP connectionType must be either "stdio" or "sse" when provided'
+      );
+    } finally {
+      errorSpy.mockRestore();
+    }
+  });
+
+  it("rejects non-string connectionType values", async () => {
+    const mcpClient = new MCPClient(false);
+    const errorSpy = jest.spyOn(console, "error").mockImplementation(() => {});
+    try {
+      await expect(
+        mcpClient.connectToServer({
+          command: "echo",
+          connectionType: 1 as unknown as "stdio",
+        })
+      ).rejects.toThrow(
+        'MCP connectionType must be either "stdio" or "sse" when provided'
+      );
+    } finally {
+      errorSpy.mockRestore();
+    }
+  });
+
+  it("normalizes connectionType casing and spacing before validation", async () => {
+    const mcpClient = new MCPClient(false);
+    const errorSpy = jest.spyOn(console, "error").mockImplementation(() => {});
+    try {
+      await expect(
+        mcpClient.connectToServer({
+          connectionType: "  SsE  " as unknown as "sse",
+        })
+      ).rejects.toThrow("SSE URL is required for SSE connection type");
+    } finally {
+      errorSpy.mockRestore();
+    }
+  });
+
+  it("infers SSE connection type when only sseUrl is provided", async () => {
+    const mcpClient = new MCPClient(false);
+    const errorSpy = jest.spyOn(console, "error").mockImplementation(() => {});
+    try {
+      await expect(
+        mcpClient.connectToServer({
+          sseUrl: "ftp://example.com/events",
+        })
+      ).rejects.toThrow("SSE URL must use http:// or https://");
+    } finally {
+      errorSpy.mockRestore();
+    }
+  });
+
+  it("rejects mixed stdio and SSE fields when connection type is implicit", async () => {
+    const mcpClient = new MCPClient(false);
+    const errorSpy = jest.spyOn(console, "error").mockImplementation(() => {});
+    try {
+      await expect(
+        mcpClient.connectToServer({
+          command: "npx",
+          sseUrl: "https://example.com/events",
+        })
+      ).rejects.toThrow(
+        "MCP config mixes stdio and sse fields. Set connectionType and provide only matching fields."
+      );
+    } finally {
+      errorSpy.mockRestore();
+    }
+  });
+
+  it("rejects stdio connections that include SSE-only fields", async () => {
+    const mcpClient = new MCPClient(false);
+    const errorSpy = jest.spyOn(console, "error").mockImplementation(() => {});
+    try {
+      await expect(
+        mcpClient.connectToServer({
+          connectionType: "stdio",
+          command: "npx",
+          sseHeaders: {
+            Authorization: "Bearer token",
+          },
+        })
+      ).rejects.toThrow(
+        "MCP stdio connection cannot include sse fields: sseHeaders"
+      );
+    } finally {
+      errorSpy.mockRestore();
+    }
+  });
+
+  it("rejects stdio connections that include empty SSE header objects", async () => {
+    const mcpClient = new MCPClient(false);
+    const errorSpy = jest.spyOn(console, "error").mockImplementation(() => {});
+    try {
+      await expect(
+        mcpClient.connectToServer({
+          connectionType: "stdio",
+          command: "npx",
+          sseHeaders: {},
+        })
+      ).rejects.toThrow(
+        "MCP stdio connection cannot include sse fields: sseHeaders"
+      );
+    } finally {
+      errorSpy.mockRestore();
+    }
+  });
+
+  it("rejects SSE connections that include stdio-only fields", async () => {
+    const mcpClient = new MCPClient(false);
+    const errorSpy = jest.spyOn(console, "error").mockImplementation(() => {});
+    try {
+      await expect(
+        mcpClient.connectToServer({
+          connectionType: "sse",
+          sseUrl: "https://example.com/events",
+          command: "npx",
+        })
+      ).rejects.toThrow(
+        "MCP SSE connection cannot include stdio fields: command"
+      );
+    } finally {
+      errorSpy.mockRestore();
+    }
+  });
+
+  it("rejects SSE connections that include empty stdio args", async () => {
+    const mcpClient = new MCPClient(false);
+    const errorSpy = jest.spyOn(console, "error").mockImplementation(() => {});
+    try {
+      await expect(
+        mcpClient.connectToServer({
+          connectionType: "sse",
+          sseUrl: "https://example.com/events",
+          args: [],
+        })
+      ).rejects.toThrow(
+        "MCP SSE connection cannot include stdio fields: args"
+      );
+    } finally {
+      errorSpy.mockRestore();
+    }
+  });
+
+  it("rejects SSE connections that include empty env records", async () => {
+    const mcpClient = new MCPClient(false);
+    const errorSpy = jest.spyOn(console, "error").mockImplementation(() => {});
+    try {
+      await expect(
+        mcpClient.connectToServer({
+          connectionType: "sse",
+          sseUrl: "https://example.com/events",
+          env: {},
+        })
+      ).rejects.toThrow(
+        "MCP SSE connection cannot include stdio fields: env"
+      );
+    } finally {
+      errorSpy.mockRestore();
+    }
+  });
+
+  it("rejects stdio command values that are blank after trimming", async () => {
+    const mcpClient = new MCPClient(false);
+    const errorSpy = jest.spyOn(console, "error").mockImplementation(() => {});
+    try {
+      await expect(
+        mcpClient.connectToServer({
+          command: "   ",
+        })
+      ).rejects.toThrow("Command is required for stdio connection type");
+    } finally {
+      errorSpy.mockRestore();
+    }
+  });
+
+  it("rejects stdio command values with control characters", async () => {
+    const mcpClient = new MCPClient(false);
+    const errorSpy = jest.spyOn(console, "error").mockImplementation(() => {});
+    try {
+      await expect(
+        mcpClient.connectToServer({
+          command: "np\nx",
+        })
+      ).rejects.toThrow("MCP command contains unsupported control characters");
+    } finally {
+      errorSpy.mockRestore();
+    }
+  });
+
+  it("rejects oversized stdio command values", async () => {
+    const mcpClient = new MCPClient(false);
+    const errorSpy = jest.spyOn(console, "error").mockImplementation(() => {});
+    try {
+      await expect(
+        mcpClient.connectToServer({
+          command: `x${"a".repeat(2_100)}`,
+        })
+      ).rejects.toThrow("MCP command exceeds 2048 characters");
+    } finally {
+      errorSpy.mockRestore();
+    }
+  });
+
+  it("rejects non-array command args", async () => {
+    const mcpClient = new MCPClient(false);
+    const errorSpy = jest.spyOn(console, "error").mockImplementation(() => {});
+    try {
+      await expect(
+        mcpClient.connectToServer({
+          command: "npx",
+          args: "invalid" as unknown as string[],
+        })
+      ).rejects.toThrow("MCP command args must be an array of non-empty strings");
+    } finally {
+      errorSpy.mockRestore();
+    }
+  });
+
+  it("rejects command args with blank entries after trimming", async () => {
+    const mcpClient = new MCPClient(false);
+    const errorSpy = jest.spyOn(console, "error").mockImplementation(() => {});
+    try {
+      await expect(
+        mcpClient.connectToServer({
+          command: "npx",
+          args: ["   "],
+        })
+      ).rejects.toThrow("MCP command args must be an array of non-empty strings");
+    } finally {
+      errorSpy.mockRestore();
+    }
+  });
+
+  it("rejects command args with control characters", async () => {
+    const mcpClient = new MCPClient(false);
+    const errorSpy = jest.spyOn(console, "error").mockImplementation(() => {});
+    try {
+      await expect(
+        mcpClient.connectToServer({
+          command: "npx",
+          args: ["bad\narg"],
+        })
+      ).rejects.toThrow("MCP command args contain unsupported control characters");
+    } finally {
+      errorSpy.mockRestore();
+    }
+  });
+
+  it("rejects oversized command args", async () => {
+    const mcpClient = new MCPClient(false);
+    const errorSpy = jest.spyOn(console, "error").mockImplementation(() => {});
+    try {
+      await expect(
+        mcpClient.connectToServer({
+          command: "npx",
+          args: ["x".repeat(4_001)],
+        })
+      ).rejects.toThrow(
+        "MCP command args cannot include entries longer than 4000 characters"
+      );
+    } finally {
+      errorSpy.mockRestore();
+    }
+  });
+
+  it("rejects command args with too many entries", async () => {
+    const mcpClient = new MCPClient(false);
+    const errorSpy = jest.spyOn(console, "error").mockImplementation(() => {});
+    try {
+      await expect(
+        mcpClient.connectToServer({
+          command: "npx",
+          args: Array.from({ length: 101 }, (_, index) => `arg-${index}`),
+        })
+      ).rejects.toThrow(
+        "MCP command args cannot contain more than 100 entries"
+      );
+    } finally {
+      errorSpy.mockRestore();
+    }
+  });
+
+  it("rejects command args when array length access throws", async () => {
+    const mcpClient = new MCPClient(false);
+    const errorSpy = jest.spyOn(console, "error").mockImplementation(() => {});
+    const argsProxy = new Proxy(["-y"], {
+      get(target, prop, receiver) {
+        if (prop === "length") {
+          throw new Error("length trap");
+        }
+        return Reflect.get(target, prop, receiver);
+      },
+    });
+    try {
+      await expect(
+        mcpClient.connectToServer({
+          command: "npx",
+          args: argsProxy as unknown as string[],
+        })
+      ).rejects.toThrow("MCP command args must be an array of non-empty strings");
+    } finally {
+      errorSpy.mockRestore();
+    }
+  });
+
+  it("rejects non-object env records", async () => {
+    const mcpClient = new MCPClient(false);
+    const errorSpy = jest.spyOn(console, "error").mockImplementation(() => {});
+    try {
+      await expect(
+        mcpClient.connectToServer({
+          command: "npx",
+          env: "invalid" as unknown as Record<string, string>,
+        })
+      ).rejects.toThrow("MCP env must be an object of string key/value pairs");
+    } finally {
+      errorSpy.mockRestore();
+    }
+  });
+
+  it("rejects invalid env record entries", async () => {
+    const mcpClient = new MCPClient(false);
+    const errorSpy = jest.spyOn(console, "error").mockImplementation(() => {});
+    try {
+      await expect(
+        mcpClient.connectToServer({
+          command: "npx",
+          env: {
+            constructor: "bad",
+          },
+        })
+      ).rejects.toThrow("MCP env must be an object of string key/value pairs");
+    } finally {
+      errorSpy.mockRestore();
+    }
+  });
+
+  it("rejects env records when entry enumeration throws", async () => {
+    const mcpClient = new MCPClient(false);
+    const errorSpy = jest.spyOn(console, "error").mockImplementation(() => {});
+    const envProxy = new Proxy(
+      {},
+      {
+        ownKeys(): ArrayLike<string | symbol> {
+          throw new Error("ownKeys trap");
+        },
+        getPrototypeOf(): object | null {
+          return Object.prototype;
+        },
+      }
+    );
+    try {
+      await expect(
+        mcpClient.connectToServer({
+          command: "npx",
+          env: envProxy as unknown as Record<string, string>,
+        })
+      ).rejects.toThrow("MCP env must be an object of string key/value pairs");
+    } finally {
+      errorSpy.mockRestore();
+    }
+  });
+
+  it("rejects oversized env records", async () => {
+    const mcpClient = new MCPClient(false);
+    const errorSpy = jest.spyOn(console, "error").mockImplementation(() => {});
+    const env = Object.fromEntries(
+      Array.from({ length: 201 }, (_, index) => [`KEY_${index}`, "value"])
+    );
+    try {
+      await expect(
+        mcpClient.connectToServer({
+          command: "npx",
+          env,
+        })
+      ).rejects.toThrow("MCP env cannot include more than 200 entries");
+    } finally {
+      errorSpy.mockRestore();
+    }
+  });
+
+  it("rejects invalid SSE header records", async () => {
+    const mcpClient = new MCPClient(false);
+    const errorSpy = jest.spyOn(console, "error").mockImplementation(() => {});
+    try {
+      await expect(
+        mcpClient.connectToServer({
+          connectionType: "sse",
+          sseUrl: "https://example.com/stream",
+          sseHeaders: {
+            "Bad Header": "value",
+          },
+        })
+      ).rejects.toThrow(
+        "MCP sseHeaders must be an object of string key/value pairs"
+      );
+    } finally {
+      errorSpy.mockRestore();
+    }
+  });
+
+  it("rejects duplicate SSE header keys after normalization", async () => {
+    const mcpClient = new MCPClient(false);
+    const errorSpy = jest.spyOn(console, "error").mockImplementation(() => {});
+    try {
+      await expect(
+        mcpClient.connectToServer({
+          connectionType: "sse",
+          sseUrl: "https://example.com/stream",
+          sseHeaders: {
+            " X-Test ": "one",
+            "x-test": "two",
+          },
+        })
+      ).rejects.toThrow('MCP sseHeaders contains duplicate key "x-test"');
+    } finally {
+      errorSpy.mockRestore();
+    }
+  });
+
+  it("rejects SSE URLs with unsupported protocols", async () => {
+    const mcpClient = new MCPClient(false);
+    const errorSpy = jest.spyOn(console, "error").mockImplementation(() => {});
+    try {
+      await expect(
+        mcpClient.connectToServer({
+          connectionType: "sse",
+          sseUrl: "ftp://example.com/events",
+        })
+      ).rejects.toThrow("SSE URL must use http:// or https://");
+    } finally {
+      errorSpy.mockRestore();
+    }
+  });
+
+  it("rejects SSE URLs with control characters", async () => {
+    const mcpClient = new MCPClient(false);
+    const errorSpy = jest.spyOn(console, "error").mockImplementation(() => {});
+    try {
+      await expect(
+        mcpClient.connectToServer({
+          connectionType: "sse",
+          sseUrl: "https://example.com/\nstream",
+        })
+      ).rejects.toThrow("SSE URL contains unsupported control characters");
+    } finally {
+      errorSpy.mockRestore();
+    }
+  });
+
+  it("rejects oversized SSE URL values", async () => {
+    const mcpClient = new MCPClient(false);
+    const errorSpy = jest.spyOn(console, "error").mockImplementation(() => {});
+    try {
+      await expect(
+        mcpClient.connectToServer({
+          connectionType: "sse",
+          sseUrl: `https://example.com/${"a".repeat(4_100)}`,
+        })
+      ).rejects.toThrow("SSE URL exceeds 4000 characters");
+    } finally {
+      errorSpy.mockRestore();
+    }
+  });
+});
+
+describe("MCPClient.executeTool server selection", () => {
+  function setServers(
+    client: MCPClient,
+    servers: Map<
+      string,
+      {
+        tools: Map<string, unknown>;
+        client: { callTool: jest.Mock };
+      }
+    >
+  ): void {
+    setServersForClient(
+      client,
+      servers as unknown as Map<string, unknown>
+    );
+  }
+
+  it("uses the only connected server when serverId is omitted", async () => {
+    const mcpClient = new MCPClient(false);
+    const callTool = jest.fn().mockResolvedValue({ content: [] });
+    setServers(
+      mcpClient,
+      new Map([
+        [
+          "server-1",
+          {
+            tools: new Map([["search", {}]]),
+            client: { callTool },
+          },
+        ],
+      ])
+    );
+
+    await mcpClient.executeTool("search", { query: "weather" });
+
+    expect(callTool).toHaveBeenCalledWith({
+      name: "search",
+      arguments: { query: "weather" },
+    });
+  });
+
+  it("normalizes JSON-string executeTool parameters before forwarding", async () => {
+    const mcpClient = new MCPClient(false);
+    const callTool = jest.fn().mockResolvedValue({ content: [] });
+    setServers(
+      mcpClient,
+      new Map([
+        [
+          "server-1",
+          {
+            tools: new Map([["search", {}]]),
+            client: { callTool },
+          },
+        ],
+      ])
+    );
+
+    await mcpClient.executeTool("search", '{"query":"weather"}');
+
+    expect(callTool).toHaveBeenCalledWith({
+      name: "search",
+      arguments: { query: "weather" },
+    });
+  });
+
+  it("rejects invalid executeTool parameter payloads before dispatch", async () => {
+    const mcpClient = new MCPClient(false);
+    const callTool = jest.fn().mockResolvedValue({ content: [] });
+    setServers(
+      mcpClient,
+      new Map([
+        [
+          "server-1",
+          {
+            tools: new Map([["search", {}]]),
+            client: { callTool },
+          },
+        ],
+      ])
+    );
+
+    await expect(
+      mcpClient.executeTool("search", "[1,2,3]")
+    ).rejects.toThrow("must parse to a JSON object");
+    expect(callTool).not.toHaveBeenCalled();
+  });
+
+  it("throws when only connected server lacks requested tool", async () => {
+    const mcpClient = new MCPClient(false);
+    const callTool = jest.fn();
+    setServers(
+      mcpClient,
+      new Map([
+        [
+          "server-1",
+          {
+            tools: new Map([["notes", {}]]),
+            client: { callTool },
+          },
+        ],
+      ])
+    );
+
+    await expect(
+      mcpClient.executeTool("search", { query: "weather" })
+    ).rejects.toThrow('Tool "search" is not registered on server "server-1"');
+    expect(callTool).not.toHaveBeenCalled();
+  });
+
+  it("trims provided serverId before server lookup", async () => {
+    const mcpClient = new MCPClient(false);
+    const callTool = jest.fn().mockResolvedValue({ content: [] });
+    setServers(
+      mcpClient,
+      new Map([
+        [
+          "server-1",
+          {
+            tools: new Map([["search", {}]]),
+            client: { callTool },
+          },
+        ],
+      ])
+    );
+
+    await mcpClient.executeTool("search", { query: "weather" }, "  server-1  ");
+
+    expect(callTool).toHaveBeenCalledWith({
+      name: "search",
+      arguments: { query: "weather" },
+    });
+  });
+
+  it("matches provided serverId case-insensitively", async () => {
+    const mcpClient = new MCPClient(false);
+    const callTool = jest.fn().mockResolvedValue({ content: [] });
+    setServers(
+      mcpClient,
+      new Map([
+        [
+          "Server-1",
+          {
+            tools: new Map([["search", {}]]),
+            client: { callTool },
+          },
+        ],
+      ])
+    );
+
+    await mcpClient.executeTool("search", { query: "weather" }, "server-1");
+
+    expect(callTool).toHaveBeenCalledWith({
+      name: "search",
+      arguments: { query: "weather" },
+    });
+  });
+
+  it("finds matching server by tool name when multiple are connected", async () => {
+    const mcpClient = new MCPClient(false);
+    const searchCallTool = jest.fn().mockResolvedValue({ content: [] });
+    const notesCallTool = jest.fn().mockResolvedValue({ content: [] });
+    setServers(
+      mcpClient,
+      new Map([
+        [
+          "server-a",
+          {
+            tools: new Map([["notes", {}]]),
+            client: { callTool: notesCallTool },
+          },
+        ],
+        [
+          "server-b",
+          {
+            tools: new Map([["search", {}]]),
+            client: { callTool: searchCallTool },
+          },
+        ],
+      ])
+    );
+
+    await mcpClient.executeTool("search", { query: "coffee" });
+
+    expect(searchCallTool).toHaveBeenCalledWith({
+      name: "search",
+      arguments: { query: "coffee" },
+    });
+    expect(notesCallTool).not.toHaveBeenCalled();
+  });
+
+  it("skips trap-prone tool registries when selecting server by tool name", async () => {
+    const mcpClient = new MCPClient(false);
+    const searchCallTool = jest.fn().mockResolvedValue({ content: [] });
+    const throwingTools = new Proxy(new Map(), {
+      get(target, prop, receiver): unknown {
+        if (prop === "has") {
+          return () => {
+            throw new Error("tools getter trap");
+          };
+        }
+        return Reflect.get(target, prop, receiver);
+      },
+    });
+    setServers(
+      mcpClient,
+      new Map([
+        [
+          "server-a",
+          {
+            tools: throwingTools as unknown as Map<string, {}>,
+            client: { callTool: jest.fn() },
+          },
+        ],
+        [
+          "server-b",
+          {
+            tools: new Map([["search", {}]]),
+            client: { callTool: searchCallTool },
+          },
+        ],
+      ])
+    );
+
+    await mcpClient.executeTool("search", { query: "coffee" });
+
+    expect(searchCallTool).toHaveBeenCalledWith({
+      name: "search",
+      arguments: { query: "coffee" },
+    });
+  });
+
+  it("matches tool names case-insensitively within a server", async () => {
+    const mcpClient = new MCPClient(false);
+    const callTool = jest.fn().mockResolvedValue({ content: [] });
+    setServers(
+      mcpClient,
+      new Map([
+        [
+          "server-a",
+          {
+            tools: new Map([["Search", createTool("Search")]]),
+            client: { callTool },
+          },
+        ],
+      ])
+    );
+
+    await mcpClient.executeTool("search", { query: "coffee" }, "server-a");
+
+    expect(callTool).toHaveBeenCalledWith({
+      name: "Search",
+      arguments: { query: "coffee" },
+    });
+  });
+
+  it("rejects case-insensitive tool lookups that are ambiguous on a server", async () => {
+    const mcpClient = new MCPClient(false);
+    const callTool = jest.fn();
+    setServers(
+      mcpClient,
+      new Map([
+        [
+          "server-a",
+          {
+            tools: new Map([
+              ["Search", createTool("Search")],
+              ["search", createTool("search")],
+            ]),
+            client: { callTool },
+          },
+        ],
+      ])
+    );
+
+    await expect(
+      mcpClient.executeTool("SEARCH", { query: "coffee" }, "server-a")
+    ).rejects.toThrow(
+      'Tool "SEARCH" matches multiple tools on server "server-a" (Search, search). Use exact tool name.'
+    );
+    expect(callTool).not.toHaveBeenCalled();
+  });
+
+  it("uses original discovered tool name when calling MCP server", async () => {
+    const mcpClient = new MCPClient(false);
+    const callTool = jest.fn().mockResolvedValue({ content: [] });
+    setServers(
+      mcpClient,
+      new Map([
+        [
+          "server-1",
+          {
+            tools: new Map([["search", createTool(" search ")]]),
+            client: { callTool },
+          },
+        ],
+      ])
+    );
+
+    await mcpClient.executeTool("search", { query: "weather" }, "server-1");
+
+    expect(callTool).toHaveBeenCalledWith({
+      name: " search ",
+      arguments: { query: "weather" },
+    });
+  });
+
+  it("throws clear error when multiple servers expose same tool and serverId is omitted", async () => {
+    const mcpClient = new MCPClient(false);
+    const firstCallTool = jest.fn().mockResolvedValue({ content: [] });
+    const secondCallTool = jest.fn().mockResolvedValue({ content: [] });
+    setServers(
+      mcpClient,
+      new Map([
+        [
+          "server-a",
+          {
+            tools: new Map([["search", {}]]),
+            client: { callTool: firstCallTool },
+          },
+        ],
+        [
+          "server-b",
+          {
+            tools: new Map([["search", {}]]),
+            client: { callTool: secondCallTool },
+          },
+        ],
+      ])
+    );
+
+    await expect(mcpClient.executeTool("search", { query: "coffee" })).rejects
+      .toThrow(
+        'Tool "search" is registered on multiple servers (server-a, server-b). Provide serverId explicitly.'
+      );
+    expect(firstCallTool).not.toHaveBeenCalled();
+    expect(secondCallTool).not.toHaveBeenCalled();
+  });
+
+  it("truncates ambiguous-server diagnostics when many servers match", async () => {
+    const mcpClient = new MCPClient(false);
+    const servers = new Map<
+      string,
+      {
+        tools: Map<string, unknown>;
+        client: { callTool: jest.Mock };
+      }
+    >();
+    for (let index = 0; index < 7; index += 1) {
+      servers.set(`server-${index}`, {
+        tools: new Map([["search", {}]]),
+        client: { callTool: jest.fn().mockResolvedValue({ content: [] }) },
+      });
+    }
+    setServers(mcpClient, servers);
+
+    await expect(mcpClient.executeTool("search", { query: "coffee" })).rejects
+      .toThrow(
+        'Tool "search" is registered on multiple servers (server-0, server-1, server-2, server-3, server-4, ... (+2 more)). Provide serverId explicitly.'
+      );
+  });
+
+  it("throws when provided serverId does not exist", async () => {
+    const mcpClient = new MCPClient(false);
+    setServers(
+      mcpClient,
+      new Map([
+        [
+          "server-a",
+          {
+            tools: new Map([["notes", {}]]),
+            client: { callTool: jest.fn() },
+          },
+        ],
+      ])
+    );
+
+    await expect(
+      mcpClient.executeTool("search", { query: "missing" }, "unknown-server")
+    ).rejects.toThrow("No valid server found for tool search");
+  });
+
+  it("returns deterministic error when server-count reads trap", async () => {
+    const mcpClient = new MCPClient(false);
+    const throwingMap = new Proxy(
+      new Map([
+        [
+          "server-a",
+          {
+            tools: new Map([["search", {}]]),
+            client: { callTool: jest.fn() },
+          },
+        ],
+      ]),
+      {
+        get(target, prop, receiver): unknown {
+          if (prop === "size") {
+            throw new Error("size trap");
+          }
+          return Reflect.get(target, prop, receiver);
+        },
+      }
+    );
+    setServersForClient(mcpClient, throwingMap as unknown as Map<string, unknown>);
+
+    await expect(
+      mcpClient.executeTool("search", { query: "missing" })
+    ).rejects.toThrow("No valid server found for tool search");
+  });
+
+  it("returns deterministic error when server lookup traps", async () => {
+    const mcpClient = new MCPClient(false);
+    const throwingMap = new Proxy(new Map(), {
+      get(target, prop, receiver): unknown {
+        if (prop === "has" || prop === "keys") {
+          return () => {
+            throw new Error("registry trap");
+          };
+        }
+        return Reflect.get(target, prop, receiver);
+      },
+    });
+    setServersForClient(mcpClient, throwingMap as unknown as Map<string, unknown>);
+
+    await expect(
+      mcpClient.executeTool("search", { query: "missing" }, "server-a")
+    ).rejects.toThrow("No valid server found for tool search");
+  });
+
+  it("returns deterministic error when server retrieval traps", async () => {
+    const mcpClient = new MCPClient(false);
+    const throwingMap = new Proxy(new Map(), {
+      get(target, prop, receiver): unknown {
+        if (prop === "has") {
+          return () => true;
+        }
+        if (prop === "get") {
+          return () => {
+            throw new Error("get trap");
+          };
+        }
+        return Reflect.get(target, prop, receiver);
+      },
+    });
+    setServersForClient(mcpClient, throwingMap as unknown as Map<string, unknown>);
+
+    await expect(
+      mcpClient.executeTool("search", { query: "missing" }, "server-a")
+    ).rejects.toThrow("Server with ID server-a not found");
+  });
+
+  it("rejects empty tool names before server lookup", async () => {
+    const mcpClient = new MCPClient(false);
+    await expect(
+      mcpClient.executeTool("   ", { query: "missing" }, "unknown-server")
+    ).rejects.toThrow("MCP tool name must be a non-empty string");
+  });
+
+  it("rejects non-string tool names before server lookup", async () => {
+    const mcpClient = new MCPClient(false);
+    await expect(
+      mcpClient.executeTool(
+        42 as unknown as string,
+        { query: "missing" },
+        "unknown-server"
+      )
+    ).rejects.toThrow("MCP tool name must be a string");
+  });
+
+  it("rejects tool names with control characters", async () => {
+    const mcpClient = new MCPClient(false);
+    await expect(
+      mcpClient.executeTool("sea\nrch", { query: "missing" }, "unknown-server")
+    ).rejects.toThrow("MCP tool name contains unsupported control characters");
+  });
+
+  it("rejects server ids with control characters", async () => {
+    const mcpClient = new MCPClient(false);
+    await expect(
+      mcpClient.executeTool("search", { query: "missing" }, "server\n-a")
+    ).rejects.toThrow("MCP serverId contains unsupported control characters");
+  });
+
+  it("rejects non-string server ids before lookup", async () => {
+    const mcpClient = new MCPClient(false);
+    await expect(
+      mcpClient.executeTool(
+        "search",
+        { query: "missing" },
+        42 as unknown as string
+      )
+    ).rejects.toThrow("MCP serverId must be a string when provided");
+  });
+
+  it("rejects blank server ids before lookup", async () => {
+    const mcpClient = new MCPClient(false);
+    await expect(
+      mcpClient.executeTool("search", { query: "missing" }, "   ")
+    ).rejects.toThrow("MCP serverId must be a non-empty string when provided");
+  });
+
+  it("rejects oversized server ids before lookup", async () => {
+    const mcpClient = new MCPClient(false);
+    await expect(
+      mcpClient.executeTool(
+        "search",
+        { query: "missing" },
+        `server-${"x".repeat(300)}`
+      )
+    ).rejects.toThrow("MCP serverId exceeds 256 characters");
+  });
+
+  it("sanitizes tool identifiers in missing-server errors", async () => {
+    const mcpClient = new MCPClient(false);
+    const noisyToolName = `bad-${"x".repeat(200)}`;
+    expect.assertions(3);
+    try {
+      await mcpClient.executeTool(
+        noisyToolName,
+        { query: "missing" },
+        "unknown-server"
+      );
+      throw new Error("Expected executeTool to throw");
+    } catch (error) {
+      const message = (error as Error).message;
+      expect(message).toContain("No valid server found for tool");
+      expect(message).not.toContain("\n");
+      expect(message).toContain("[truncated]");
+    }
+  });
+
+  it("throws when target server is connected but missing the tool", async () => {
+    const mcpClient = new MCPClient(false);
+    const callTool = jest.fn();
+    setServers(
+      mcpClient,
+      new Map([
+        [
+          "server-a",
+          {
+            tools: new Map([["notes", {}]]),
+            client: { callTool },
+          },
+        ],
+      ])
+    );
+
+    await expect(
+      mcpClient.executeTool("search", { query: "missing" }, "server-a")
+    ).rejects.toThrow('Tool "search" is not registered on server "server-a"');
+    expect(callTool).not.toHaveBeenCalled();
+  });
+
+  it("throws readable errors when tool registry lookups fail", async () => {
+    const mcpClient = new MCPClient(false);
+    const callTool = jest.fn();
+    const throwingTools = new Proxy(new Map([["search", {}]]), {
+      get(target, prop, receiver): unknown {
+        if (prop === "has") {
+          return () => {
+            throw new Error("tool registry unavailable");
+          };
+        }
+        return Reflect.get(target, prop, receiver);
+      },
+    });
+    setServers(
+      mcpClient,
+      new Map([
+        [
+          "server-a",
+          {
+            tools: throwingTools as unknown as Map<string, unknown>,
+            client: { callTool },
+          },
+        ],
+      ])
+    );
+
+    await expect(
+      mcpClient.executeTool("search", { query: "missing" }, "server-a")
+    ).rejects.toThrow("MCP tool registry lookup failed: tool registry unavailable");
+    expect(callTool).not.toHaveBeenCalled();
+  });
+
+  it("throws readable errors when tool registry retrieval traps after lookup", async () => {
+    const mcpClient = new MCPClient(false);
+    const callTool = jest.fn();
+    const throwingTools = new Proxy(new Map([["search", createTool("search")]]), {
+      get(target, prop, receiver): unknown {
+        if (prop === "get") {
+          return () => {
+            throw new Error("tool retrieval unavailable");
+          };
+        }
+        const value = Reflect.get(target, prop, target);
+        if (typeof value === "function") {
+          return value.bind(target);
+        }
+        return value;
+      },
+    });
+    setServers(
+      mcpClient,
+      new Map([
+        [
+          "server-a",
+          {
+            tools: throwingTools as unknown as Map<string, unknown>,
+            client: { callTool },
+          },
+        ],
+      ])
+    );
+
+    await expect(
+      mcpClient.executeTool("search", { query: "missing" }, "server-a")
+    ).rejects.toThrow("MCP tool registry lookup failed: tool retrieval unavailable");
+    expect(callTool).not.toHaveBeenCalled();
+  });
+
+  it("throws readable errors when server tool registry is unavailable", async () => {
+    const mcpClient = new MCPClient(false);
+    const callTool = jest.fn();
+    const trapServer = new Proxy(
+      {
+        client: { callTool },
+      },
+      {
+        get(target, prop, receiver): unknown {
+          if (prop === "tools") {
+            throw new Error("tools access trap");
+          }
+          return Reflect.get(target, prop, receiver);
+        },
+      }
+    );
+    setServersForClient(
+      mcpClient,
+      new Map([["server-a", trapServer]]) as unknown as Map<string, unknown>
+    );
+
+    await expect(
+      mcpClient.executeTool("search", { query: "missing" }, "server-a")
+    ).rejects.toThrow("MCP server tools are unavailable: tools access trap");
+    expect(callTool).not.toHaveBeenCalled();
+  });
+
+  it("throws readable errors when server tool registry shape is invalid", async () => {
+    const mcpClient = new MCPClient(false);
+    const callTool = jest.fn();
+    setServersForClient(
+      mcpClient,
+      new Map([
+        [
+          "server-a",
+          {
+            tools: {},
+            client: { callTool },
+          },
+        ],
+      ]) as unknown as Map<string, unknown>
+    );
+
+    await expect(
+      mcpClient.executeTool("search", { query: "missing" }, "server-a")
+    ).rejects.toThrow("MCP server tools are unavailable: invalid tools registry");
+    expect(callTool).not.toHaveBeenCalled();
+  });
+
+  it("sanitizes tool names in missing-tool diagnostics", async () => {
+    const mcpClient = new MCPClient(false);
+    const callTool = jest.fn();
+    setServers(
+      mcpClient,
+      new Map([
+        [
+          "server-a",
+          {
+            tools: new Map([["notes", {}]]),
+            client: { callTool },
+          },
+        ],
+      ])
+    );
+
+    expect.assertions(4);
+    try {
+      await mcpClient.executeTool(
+        `search-${"x".repeat(200)}`,
+        { query: "missing" },
+        "server-a"
+      );
+      throw new Error("Expected executeTool to throw");
+    } catch (error) {
+      const message = (error as Error).message;
+      expect(message).toContain('Tool "search-');
+      expect(message).toContain('[truncated]" is not registered on server "server-a"');
+      expect(message).not.toContain("\n");
+    }
+    expect(callTool).not.toHaveBeenCalled();
+  });
+
+  it("wraps non-Error callTool failures with readable messages", async () => {
+    const mcpClient = new MCPClient(false);
+    const callTool = jest.fn().mockRejectedValue({ reason: "tool exploded" });
+    const errorSpy = jest.spyOn(console, "error").mockImplementation(() => {});
+    setServers(
+      mcpClient,
+      new Map([
+        [
+          "server-1",
+          {
+            tools: new Map([["search", {}]]),
+            client: { callTool },
+          },
+        ],
+      ])
+    );
+
+    try {
+      await expect(
+        mcpClient.executeTool("search", { query: "weather" })
+      ).rejects.toThrow(
+        'Error executing tool search on server server-1: {"reason":"tool exploded"}'
+      );
+      expect(errorSpy).toHaveBeenCalledWith(
+        'Error executing tool search on server server-1: {"reason":"tool exploded"}'
+      );
+    } finally {
+      errorSpy.mockRestore();
+    }
+  });
+});
+
+describe("MCPClient disconnect lifecycle", () => {
+  function setServers(client: MCPClient, servers: Map<string, unknown>): void {
+    setServersForClient(client, servers);
+  }
+
+  it("disconnectServer closes transport and removes server", async () => {
+    const mcpClient = new MCPClient(false);
+    const close = jest.fn().mockResolvedValue(undefined);
+    setServers(
+      mcpClient,
+      new Map([
+        [
+          "server-1",
+          {
+            transport: { close },
+          },
+        ],
+      ])
+    );
+
+    await mcpClient.disconnectServer("server-1");
+
+    expect(close).toHaveBeenCalledTimes(1);
+    expect(mcpClient.getServerIds()).toEqual([]);
+    expect(mcpClient.hasConnections()).toBe(false);
+  });
+
+  it("disconnectServer resolves server id case-insensitively", async () => {
+    const mcpClient = new MCPClient(false);
+    const close = jest.fn().mockResolvedValue(undefined);
+    setServers(
+      mcpClient,
+      new Map([
+        [
+          "Server-1",
+          {
+            transport: { close },
+          },
+        ],
+      ])
+    );
+
+    await mcpClient.disconnectServer(" server-1 ");
+
+    expect(close).toHaveBeenCalledTimes(1);
+    expect(mcpClient.getServerIds()).toEqual([]);
+  });
+
+  it("disconnectServer ignores invalid server id inputs", async () => {
+    const mcpClient = new MCPClient(false);
+    const close = jest.fn().mockResolvedValue(undefined);
+    setServers(
+      mcpClient,
+      new Map([
+        [
+          "server-1",
+          {
+            transport: { close },
+          },
+        ],
+      ])
+    );
+
+    await mcpClient.disconnectServer("   ");
+    await mcpClient.disconnectServer("bad\nid");
+
+    expect(close).not.toHaveBeenCalled();
+    expect(mcpClient.getServerIds()).toEqual(["server-1"]);
+  });
+
+  it("disconnectServer safely ignores proxy-trapped server maps", async () => {
+    const mcpClient = new MCPClient(false);
+    const throwingMap = new Proxy(new Map(), {
+      has(): boolean {
+        throw new Error("has trap");
+      },
+    });
+    setServersForClient(mcpClient, throwingMap as unknown as Map<string, unknown>);
+
+    await expect(mcpClient.disconnectServer("server-1")).resolves.toBeUndefined();
+  });
+
+  it("disconnectServer safely ignores proxy-trapped server retrieval", async () => {
+    const mcpClient = new MCPClient(false);
+    const throwingMap = new Proxy(new Map(), {
+      get(target, prop, receiver): unknown {
+        if (prop === "has") {
+          return () => true;
+        }
+        if (prop === "get") {
+          return () => {
+            throw new Error("get trap");
+          };
+        }
+        return Reflect.get(target, prop, receiver);
+      },
+    });
+    setServersForClient(mcpClient, throwingMap as unknown as Map<string, unknown>);
+
+    await expect(mcpClient.disconnectServer("server-1")).resolves.toBeUndefined();
+  });
+
+  it("disconnect closes every connected server transport", async () => {
+    const mcpClient = new MCPClient(false);
+    const closeA = jest.fn().mockResolvedValue(undefined);
+    const closeB = jest.fn().mockResolvedValue(undefined);
+    setServers(
+      mcpClient,
+      new Map([
+        [
+          "server-a",
+          {
+            transport: { close: closeA },
+          },
+        ],
+        [
+          "server-b",
+          {
+            transport: { close: closeB },
+          },
+        ],
+      ])
+    );
+
+    await mcpClient.disconnect();
+
+    expect(closeA).toHaveBeenCalledTimes(1);
+    expect(closeB).toHaveBeenCalledTimes(1);
+    expect(mcpClient.hasConnections()).toBe(false);
+  });
+
+  it("disconnectServer removes server even when transport close fails", async () => {
+    const mcpClient = new MCPClient(false);
+    const close = jest.fn().mockRejectedValue(new Error("close failed"));
+    setServers(
+      mcpClient,
+      new Map([
+        [
+          "server-1",
+          {
+            transport: { close },
+          },
+        ],
+      ])
+    );
+
+    await expect(mcpClient.disconnectServer("server-1")).rejects.toThrow(
+      "close failed"
+    );
+    expect(mcpClient.hasConnections()).toBe(false);
+  });
+
+  it("disconnectServer wraps non-Error close failures", async () => {
+    const mcpClient = new MCPClient(false);
+    const close = jest.fn().mockRejectedValue({ reason: "close object failed" });
+    setServers(
+      mcpClient,
+      new Map([
+        [
+          "server-1",
+          {
+            transport: { close },
+          },
+        ],
+      ])
+    );
+
+    await expect(mcpClient.disconnectServer("server-1")).rejects.toThrow(
+      '{"reason":"close object failed"}'
+    );
+    expect(mcpClient.hasConnections()).toBe(false);
+  });
+
+  it("disconnectServer surfaces bounded unregister failures", async () => {
+    const mcpClient = new MCPClient(false);
+    const close = jest.fn().mockResolvedValue(undefined);
+    setServersForClient(
+      mcpClient,
+      {
+        has: (id: string): boolean => id === "server-1",
+        keys: (): IterableIterator<string> => ["server-1"][Symbol.iterator](),
+        get: (id: string): unknown =>
+          id === "server-1"
+            ? {
+                transport: { close },
+              }
+            : undefined,
+        delete: (): never => {
+          throw new Error("x".repeat(2_000));
+        },
+      } as unknown as Map<string, unknown>
+    );
+
+    await expect(mcpClient.disconnectServer("server-1")).rejects.toThrow(
+      /Failed to unregister MCP server server-1: .*\[truncated/
+    );
+    expect(close).toHaveBeenCalledTimes(1);
+  });
+
+  it("disconnect continues closing remaining servers on failure", async () => {
+    const mcpClient = new MCPClient(false);
+    const closeA = jest.fn().mockRejectedValue(new Error("close A failed"));
+    const closeB = jest.fn().mockResolvedValue(undefined);
+    setServers(
+      mcpClient,
+      new Map([
+        [
+          "server-a",
+          {
+            transport: { close: closeA },
+          },
+        ],
+        [
+          "server-b",
+          {
+            transport: { close: closeB },
+          },
+        ],
+      ])
+    );
+    const errorSpy = jest.spyOn(console, "error").mockImplementation(() => {});
+
+    try {
+      await mcpClient.disconnect();
+      expect(closeA).toHaveBeenCalledTimes(1);
+      expect(closeB).toHaveBeenCalledTimes(1);
+      expect(mcpClient.hasConnections()).toBe(false);
+      expect(errorSpy).toHaveBeenCalledWith(
+        "Failed to disconnect MCP server server-a: close A failed"
+      );
+    } finally {
+      errorSpy.mockRestore();
+    }
+  });
+
+  it("disconnect formats non-Error close failures", async () => {
+    const mcpClient = new MCPClient(false);
+    const closeA = jest.fn().mockRejectedValue({ reason: "close object failed" });
+    setServers(
+      mcpClient,
+      new Map([
+        [
+          "server-a",
+          {
+            transport: { close: closeA },
+          },
+        ],
+      ])
+    );
+    const errorSpy = jest.spyOn(console, "error").mockImplementation(() => {});
+
+    try {
+      await mcpClient.disconnect();
+      expect(errorSpy).toHaveBeenCalledWith(
+        'Failed to disconnect MCP server server-a: {"reason":"close object failed"}'
+      );
+    } finally {
+      errorSpy.mockRestore();
+    }
+  });
+
+  it("disconnect truncates oversized server-id diagnostics", async () => {
+    const mcpClient = new MCPClient(false);
+    const closeA = jest.fn().mockRejectedValue(new Error("close failed"));
+    const oversizedServerId = `server-${"x".repeat(400)}`;
+    setServers(
+      mcpClient,
+      new Map([
+        [
+          oversizedServerId,
+          {
+            transport: { close: closeA },
+          },
+        ],
+      ])
+    );
+    const errorSpy = jest.spyOn(console, "error").mockImplementation(() => {});
+
+    try {
+      await mcpClient.disconnect();
+      const errorMessage = String(errorSpy.mock.calls[0]?.[0] ?? "");
+      expect(errorMessage).toContain("Failed to disconnect MCP server");
+      expect(errorMessage).toContain("[truncated]");
+      expect(errorMessage).toContain("close failed");
+    } finally {
+      errorSpy.mockRestore();
+    }
+  });
+});
+
+describe("MCPClient.hasTool", () => {
+  function setServers(
+    client: MCPClient,
+    servers: Map<
+      string,
+      {
+        tools: Map<string, unknown>;
+      }
+    >
+  ): void {
+    setServersForClient(
+      client,
+      servers as unknown as Map<string, unknown>
+    );
+  }
+
+  it("returns normalized lookup result for matching tool names", () => {
+    const mcpClient = new MCPClient(false);
+    setServers(
+      mcpClient,
+      new Map([
+        [
+          "server-a",
+          {
+            tools: new Map([["search", {}]]),
+          },
+        ],
+      ])
+    );
+
+    expect(mcpClient.hasTool("  search  ")).toEqual({
+      exists: true,
+      serverId: "server-a",
+    });
+  });
+
+  it("matches tool names case-insensitively for lookup", () => {
+    const mcpClient = new MCPClient(false);
+    setServers(
+      mcpClient,
+      new Map([
+        [
+          "server-a",
+          {
+            tools: new Map([["Search", {}]]),
+          },
+        ],
+      ])
+    );
+
+    expect(mcpClient.hasTool("search")).toEqual({
+      exists: true,
+      serverId: "server-a",
+    });
+  });
+
+  it("returns ambiguity details when multiple servers expose same tool", () => {
+    const mcpClient = new MCPClient(false);
+    setServers(
+      mcpClient,
+      new Map([
+        [
+          "server-a",
+          {
+            tools: new Map([["search", {}]]),
+          },
+        ],
+        [
+          "server-b",
+          {
+            tools: new Map([["search", {}]]),
+          },
+        ],
+      ])
+    );
+
+    expect(mcpClient.hasTool("search")).toEqual({
+      exists: true,
+      serverId: "server-a",
+      serverIds: ["server-a", "server-b"],
+      isAmbiguous: true,
+    });
+  });
+
+  it("returns ambiguity details for case-insensitive collisions on one server", () => {
+    const mcpClient = new MCPClient(false);
+    setServers(
+      mcpClient,
+      new Map([
+        [
+          "server-a",
+          {
+            tools: new Map([
+              ["Search", {}],
+              ["search", {}],
+            ]),
+          },
+        ],
+      ])
+    );
+
+    expect(mcpClient.hasTool("SEARCH")).toEqual({
+      exists: true,
+      serverId: "server-a",
+      serverIds: ["server-a"],
+      isAmbiguous: true,
+    });
+  });
+
+  it("returns exists false when no matching tool exists", () => {
+    const mcpClient = new MCPClient(false);
+    setServers(
+      mcpClient,
+      new Map([
+        [
+          "server-a",
+          {
+            tools: new Map([["notes", {}]]),
+          },
+        ],
+      ])
+    );
+
+    expect(mcpClient.hasTool("search")).toEqual({ exists: false });
+  });
+
+  it("returns exists false for invalid lookup inputs", () => {
+    const mcpClient = new MCPClient(false);
+    expect(mcpClient.hasTool("   ")).toEqual({ exists: false });
+    expect(mcpClient.hasTool("sea\nrch")).toEqual({ exists: false });
+  });
+
+  it("returns exists false when server map iteration traps throw", () => {
+    const mcpClient = new MCPClient(false);
+    const throwingMap = new Proxy(new Map(), {
+      get(target, prop, receiver): unknown {
+        if (prop === "entries") {
+          throw new Error("entries trap");
+        }
+        return Reflect.get(target, prop, receiver);
+      },
+    });
+    setServersForClient(mcpClient, throwingMap as unknown as Map<string, unknown>);
+
+    expect(mcpClient.hasTool("search")).toEqual({ exists: false });
+  });
+
+  it("returns exists false when tool-registry lookups throw", () => {
+    const mcpClient = new MCPClient(false);
+    const throwingTools = new Proxy(new Map([["search", {}]]), {
+      get(target, prop, receiver): unknown {
+        if (prop === "has") {
+          return () => {
+            throw new Error("tool registry unavailable");
+          };
+        }
+        return Reflect.get(target, prop, receiver);
+      },
+    });
+    setServers(
+      mcpClient,
+      new Map([
+        [
+          "server-a",
+          {
+            tools: throwingTools as unknown as Map<string, unknown>,
+          },
+        ],
+      ])
+    );
+
+    expect(mcpClient.hasTool("search")).toEqual({ exists: false });
+  });
+
+  it("continues hasTool lookup when one server tool registry traps", () => {
+    const mcpClient = new MCPClient(false);
+    const throwingTools = new Proxy(new Map([["search", {}]]), {
+      get(target, prop, receiver): unknown {
+        if (prop === "has") {
+          return () => {
+            throw new Error("tool registry unavailable");
+          };
+        }
+        return Reflect.get(target, prop, receiver);
+      },
+    });
+    setServers(
+      mcpClient,
+      new Map([
+        [
+          "server-a",
+          {
+            tools: throwingTools as unknown as Map<string, unknown>,
+          },
+        ],
+        [
+          "server-b",
+          {
+            tools: new Map([["search", {}]]),
+          },
+        ],
+      ])
+    );
+
+    expect(mcpClient.hasTool("search")).toEqual({
+      exists: true,
+      serverId: "server-b",
+    });
+  });
+
+  it("continues hasTool lookup when one server tools registry getter traps", () => {
+    const mcpClient = new MCPClient(false);
+    const trapServer = new Proxy(
+      {},
+      {
+        get(target, prop, receiver): unknown {
+          if (prop === "tools") {
+            throw new Error("tools getter trap");
+          }
+          return Reflect.get(target, prop, receiver);
+        },
+      }
+    );
+    setServersForClient(
+      mcpClient,
+      new Map([
+        ["server-a", trapServer],
+        [
+          "server-b",
+          {
+            tools: new Map([["search", {}]]),
+          },
+        ],
+      ]) as unknown as Map<string, unknown>
+    );
+
+    expect(mcpClient.hasTool("search")).toEqual({
+      exists: true,
+      serverId: "server-b",
+    });
+  });
+
+  it("sanitizes oversized server ids in hasTool output", () => {
+    const mcpClient = new MCPClient(false);
+    const oversizedServerId = `server-${"x".repeat(300)}\nunsafe`;
+    setServers(
+      mcpClient,
+      new Map([
+        [
+          oversizedServerId,
+          {
+            tools: new Map([["search", {}]]),
+          },
+        ],
+      ])
+    );
+
+    const result = mcpClient.hasTool("search");
+    expect(result.exists).toBe(true);
+    expect(result.serverId).toContain("[truncated]");
+    expect(result.serverId).not.toContain("\n");
+  });
+});
+
+describe("MCPClient server metadata accessors", () => {
+  it("returns all registered actions across connected servers", () => {
+    const mcpClient = new MCPClient(false);
+    setServersForClient(
+      mcpClient,
+      new Map([
+        [
+          "server-a",
+          {
+            actions: [{ type: "search" }],
+            tools: new Map([["search", {}]]),
+          },
+        ],
+        [
+          "server-b",
+          {
+            actions: [{ type: "notes" }],
+            tools: new Map([["notes", {}]]),
+          },
+        ],
+      ])
+    );
+
+    expect(mcpClient.getAllActions().map((action) => action.type)).toEqual([
+      "search",
+      "notes",
+    ]);
+  });
+
+  it("returns server ids and info for connected servers", () => {
+    const mcpClient = new MCPClient(false);
+    setServersForClient(
+      mcpClient,
+      new Map([
+        [
+          "server-a",
+          {
+            tools: new Map([
+              ["search", {}],
+              ["notes", {}],
+            ]),
+          },
+        ],
+      ])
+    );
+
+    expect(mcpClient.getServerIds()).toEqual(["server-a"]);
+    expect(mcpClient.getServerInfo()).toEqual([
+      {
+        id: "server-a",
+        toolCount: 2,
+        toolNames: ["search", "notes"],
+      },
+    ]);
+    expect(mcpClient.hasConnections()).toBe(true);
+  });
+
+  it("returns safe defaults when server map key iteration traps throw", () => {
+    const mcpClient = new MCPClient(false);
+    const throwingMap = new Proxy(new Map(), {
+      get(target, prop, receiver): unknown {
+        if (prop === "keys") {
+          throw new Error("keys trap");
+        }
+        return Reflect.get(target, prop, receiver);
+      },
+    });
+    setServersForClient(mcpClient, throwingMap as unknown as Map<string, unknown>);
+
+    expect(mcpClient.getServerIds()).toEqual([]);
+    expect(mcpClient.hasConnections()).toBe(false);
+  });
+
+  it("returns safe defaults when server map entry iteration traps throw", () => {
+    const mcpClient = new MCPClient(false);
+    const throwingMap = new Proxy(new Map(), {
+      get(target, prop, receiver): unknown {
+        if (prop === "entries") {
+          throw new Error("entries trap");
+        }
+        return Reflect.get(target, prop, receiver);
+      },
+    });
+    setServersForClient(mcpClient, throwingMap as unknown as Map<string, unknown>);
+
+    expect(mcpClient.getServerInfo()).toEqual([]);
+    expect(mcpClient.getAllActions()).toEqual([]);
+  });
+
+  it("returns safe action defaults when server action reads trap", () => {
+    const mcpClient = new MCPClient(false);
+    const trapServer = new Proxy(
+      {
+        tools: new Map([["search", {}]]),
+      },
+      {
+        get(target, prop, receiver): unknown {
+          if (prop === "actions") {
+            throw new Error("actions trap");
+          }
+          return Reflect.get(target, prop, receiver);
+        },
+      }
+    );
+    setServersForClient(
+      mcpClient,
+      new Map([["server-a", trapServer]])
+    );
+
+    expect(mcpClient.getAllActions()).toEqual([]);
+  });
+
+  it("returns safe tool metadata when server tool reads trap", () => {
+    const mcpClient = new MCPClient(false);
+    const trapServer = new Proxy(
+      {
+        actions: [{ type: "search" }],
+      },
+      {
+        get(target, prop, receiver): unknown {
+          if (prop === "tools") {
+            throw new Error("tools trap");
+          }
+          return Reflect.get(target, prop, receiver);
+        },
+      }
+    );
+    setServersForClient(
+      mcpClient,
+      new Map([["server-a", trapServer]])
+    );
+
+    expect(mcpClient.getServerInfo()).toEqual([
+      {
+        id: "server-a",
+        toolCount: 0,
+        toolNames: [],
+      },
+    ]);
+  });
+
+  it("sanitizes oversized server identifiers in server info output", () => {
+    const mcpClient = new MCPClient(false);
+    const oversizedServerId = `server-${"x".repeat(300)}\nunsafe`;
+    setServersForClient(
+      mcpClient,
+      new Map([
+        [
+          oversizedServerId,
+          {
+            tools: new Map([["search", {}]]),
+          },
+        ],
+      ])
+    );
+
+    const info = mcpClient.getServerInfo();
+    expect(info).toHaveLength(1);
+    expect(info[0].id).toContain("[truncated]");
+    expect(info[0].id).not.toContain("\n");
+    expect(info[0].toolCount).toBe(1);
+    expect(info[0].toolNames).toEqual(["search"]);
+  });
+
+  it("sanitizes oversized tool names in server info output", () => {
+    const mcpClient = new MCPClient(false);
+    const oversizedToolName = `tool-${"x".repeat(200)}\nunsafe`;
+    setServersForClient(
+      mcpClient,
+      new Map([
+        [
+          "server-a",
+          {
+            tools: new Map([[oversizedToolName, {}]]),
+          },
+        ],
+      ])
+    );
+
+    const info = mcpClient.getServerInfo();
+    expect(info).toHaveLength(1);
+    expect(info[0].toolCount).toBe(1);
+    expect(info[0].toolNames[0]).toContain("[truncated]");
+    expect(info[0].toolNames[0]).not.toContain("\n");
+  });
+
+  it("sanitizes oversized server identifiers in server id output", () => {
+    const mcpClient = new MCPClient(false);
+    const oversizedServerId = `server-${"x".repeat(300)}\nunsafe`;
+    setServersForClient(
+      mcpClient,
+      new Map([[oversizedServerId, { tools: new Map() }]])
+    );
+
+    const serverIds = mcpClient.getServerIds();
+    expect(serverIds).toHaveLength(1);
+    expect(serverIds[0]).toContain("[truncated]");
+    expect(serverIds[0]).not.toContain("\n");
+  });
+});
diff --git a/src/agent/mcp/client.ts b/src/agent/mcp/client.ts
index 10456ebf..a59ac1ae 100644
--- a/src/agent/mcp/client.ts
+++ b/src/agent/mcp/client.ts
@@ -5,6 +5,7 @@ import { SSEClientTransport } from "@modelcontextprotocol/sdk/client/sse.js";
 import { Tool } from "@modelcontextprotocol/sdk/types";
 import { MCPServerConfig } from "@/types/config";
 import { ActionContext, ActionOutput, AgentActionDefinition } from "@/types";
+import { formatUnknownError } from "@/utils";
 import { v4 as uuidv4 } from "uuid";
 
 interface ServerConnection {
@@ -16,6 +17,1131 @@ interface ServerConnection {
   actions: AgentActionDefinition[];
 }
 
+type MCPToolResult = Awaited<ReturnType<Client["callTool"]>>;
+type MCPToolDiscoveryOptions = Pick<
+  MCPServerConfig,
+  "includeTools" | "excludeTools"
+>;
+type NormalizedDiscoveredMCPTool = {
+  tool: Tool;
+  normalizedName: string;
+};
+const MAX_MCP_PAYLOAD_CHARS = 4000;
+const MAX_MCP_TOOL_PARAMS_JSON_CHARS = 100_000;
+const MAX_MCP_PARAM_DEPTH = 25;
+const MAX_MCP_PARAM_STRING_CHARS = 20_000;
+const MAX_MCP_PARAM_KEY_CHARS = 256;
+const MAX_MCP_PARAM_COLLECTION_SIZE = 500;
+const MAX_MCP_IDENTIFIER_DIAGNOSTIC_CHARS = 128;
+const MAX_MCP_TOOL_NAME_CHARS = 256;
+const MAX_MCP_SERVER_ID_CHARS = 256;
+const MAX_MCP_AMBIGUOUS_SERVER_IDS = 5;
+const MAX_MCP_TOOL_DIAGNOSTIC_ITEMS = 10;
+const MAX_MCP_CONFIG_SERVER_ID_CHARS = 128;
+const MAX_MCP_CONFIG_COMMAND_CHARS = 2_048;
+const MAX_MCP_CONFIG_SSE_URL_CHARS = 4_000;
+const MAX_MCP_CONFIG_ARGS_PER_SERVER = 100;
+const MAX_MCP_CONFIG_ARG_CHARS = 4_000;
+const MAX_MCP_CONFIG_RECORD_ENTRIES = 200;
+const MAX_MCP_CONFIG_RECORD_KEY_CHARS = 256;
+const MAX_MCP_CONFIG_RECORD_VALUE_CHARS = 4_000;
+const MAX_MCP_DISCOVERED_TOOLS = 500;
+const MAX_MCP_TOOL_DESCRIPTION_CHARS = 2_000;
+const MAX_MCP_RUNTIME_DIAGNOSTIC_CHARS = 400;
+const UNSAFE_OBJECT_KEYS = new Set(["__proto__", "prototype", "constructor"]);
+const UNSAFE_MCP_RECORD_KEYS = new Set(["__proto__", "prototype", "constructor"]);
+const HTTP_HEADER_NAME_PATTERN = /^[!#$%&'*+.^_`|~0-9A-Za-z-]+$/u;
+
+function hasUnsupportedControlChars(value: string): boolean {
+  return Array.from(value).some((char) => {
+    const code = char.charCodeAt(0);
+    return (
+      (code >= 0 && code < 32 && code !== 9 && code !== 10 && code !== 13) ||
+      code === 127
+    );
+  });
+}
+
+function hasAnyControlChars(value: string): boolean {
+  return Array.from(value).some((char) => {
+    const code = char.charCodeAt(0);
+    return (code >= 0 && code < 32) || code === 127;
+  });
+}
+
+function isMCPServerConfig(value: unknown): value is MCPServerConfig {
+  try {
+    return isPlainRecord(value);
+  } catch {
+    return false;
+  }
+}
+
+function validateParamStringValue(value: string): string {
+  if (hasUnsupportedControlChars(value)) {
+    throw new Error(
+      "MCP tool params cannot include unsupported control characters in string values"
+    );
+  }
+  if (value.length > MAX_MCP_PARAM_STRING_CHARS) {
+    throw new Error(
+      `MCP tool params cannot include string values longer than ${MAX_MCP_PARAM_STRING_CHARS} characters`
+    );
+  }
+  return value;
+}
+
+function formatMCPIdentifier(value: unknown, fallback: string): string {
+  const raw = typeof value === "string" ? value : formatUnknownError(value);
+  const normalized = raw
+    .replace(/[\u0000-\u001F\u007F]/g, " ")
+    .trim()
+    .replace(/\s+/g, " ");
+  if (normalized.length === 0) {
+    return fallback;
+  }
+  if (normalized.length <= MAX_MCP_IDENTIFIER_DIAGNOSTIC_CHARS) {
+    return normalized;
+  }
+  return `${normalized.slice(
+    0,
+    MAX_MCP_IDENTIFIER_DIAGNOSTIC_CHARS
+  )}... [truncated]`;
+}
+
+function formatMCPRuntimeDiagnostic(value: unknown): string {
+  const normalized = Array.from(formatUnknownError(value), (char) => {
+    const code = char.charCodeAt(0);
+    return (code >= 0 && code < 32) || code === 127 ? " " : char;
+  })
+    .join("")
+    .replace(/\s+/g, " ")
+    .trim();
+  const fallback = normalized.length > 0 ? normalized : "unknown error";
+  if (fallback.length <= MAX_MCP_RUNTIME_DIAGNOSTIC_CHARS) {
+    return fallback;
+  }
+  const omitted = fallback.length - MAX_MCP_RUNTIME_DIAGNOSTIC_CHARS;
+  return `${fallback.slice(0, MAX_MCP_RUNTIME_DIAGNOSTIC_CHARS)}... [truncated ${omitted} chars]`;
+}
+
+function normalizeMCPExecutionToolName(toolName: unknown): string {
+  if (typeof toolName !== "string") {
+    throw new Error("MCP tool name must be a string");
+  }
+  const normalized = toolName.trim();
+  if (normalized.length === 0) {
+    throw new Error("MCP tool name must be a non-empty string");
+  }
+  if (hasAnyControlChars(normalized)) {
+    throw new Error("MCP tool name contains unsupported control characters");
+  }
+  if (normalized.length > MAX_MCP_TOOL_NAME_CHARS) {
+    throw new Error(
+      `MCP tool name exceeds ${MAX_MCP_TOOL_NAME_CHARS} characters`
+    );
+  }
+  return normalized;
+}
+
+function normalizeMCPExecutionServerId(
+  serverId?: string
+): string | undefined {
+  if (typeof serverId === "undefined") {
+    return undefined;
+  }
+  if (typeof serverId !== "string") {
+    throw new Error("MCP serverId must be a string when provided");
+  }
+  const normalized = serverId.trim();
+  if (normalized.length === 0) {
+    throw new Error("MCP serverId must be a non-empty string when provided");
+  }
+  if (hasAnyControlChars(normalized)) {
+    throw new Error("MCP serverId contains unsupported control characters");
+  }
+  if (normalized.length > MAX_MCP_SERVER_ID_CHARS) {
+    throw new Error(
+      `MCP serverId exceeds ${MAX_MCP_SERVER_ID_CHARS} characters`
+    );
+  }
+  return normalized;
+}
+
+function normalizeMCPConnectionServerId(serverId?: string): string | undefined {
+  if (typeof serverId === "undefined") {
+    return undefined;
+  }
+  if (typeof serverId !== "string") {
+    throw new Error("MCP server id must be a string when provided");
+  }
+  const normalized = serverId.trim();
+  if (normalized.length === 0) {
+    throw new Error("MCP server id must be a non-empty string when provided");
+  }
+  if (hasAnyControlChars(normalized)) {
+    throw new Error("MCP server id contains unsupported control characters");
+  }
+  if (normalized.length > MAX_MCP_CONFIG_SERVER_ID_CHARS) {
+    throw new Error(
+      `MCP server id exceeds ${MAX_MCP_CONFIG_SERVER_ID_CHARS} characters`
+    );
+  }
+  return normalized;
+}
+
+function normalizeMCPConnectionType(
+  value?: MCPServerConfig["connectionType"]
+): "stdio" | "sse" {
+  if (typeof value === "undefined") {
+    return "stdio";
+  }
+  if (typeof value !== "string") {
+    throw new Error(
+      'MCP connectionType must be either "stdio" or "sse" when provided'
+    );
+  }
+  const normalized = value.trim().toLowerCase();
+  if (normalized.length === 0 || hasAnyControlChars(normalized)) {
+    throw new Error(
+      'MCP connectionType must be either "stdio" or "sse" when provided'
+    );
+  }
+  if (normalized === "stdio" || normalized === "sse") {
+    return normalized;
+  }
+  throw new Error(
+    'MCP connectionType must be either "stdio" or "sse" when provided'
+  );
+}
+
+function hasNonEmptyString(value: unknown): boolean {
+  return typeof value === "string" && value.trim().length > 0;
+}
+
+function resolveMCPConnectionType(serverConfig: MCPServerConfig): "stdio" | "sse" {
+  if (typeof serverConfig.connectionType !== "undefined") {
+    return normalizeMCPConnectionType(serverConfig.connectionType);
+  }
+  const hasCommand = hasNonEmptyString(serverConfig.command);
+  const hasSSEUrl = hasNonEmptyString(serverConfig.sseUrl);
+  if (hasCommand && hasSSEUrl) {
+    throw new Error(
+      "MCP config mixes stdio and sse fields. Set connectionType and provide only matching fields."
+    );
+  }
+  if (hasSSEUrl) {
+    return "sse";
+  }
+  return "stdio";
+}
+
+function validateMCPConnectionFieldMix(
+  options: {
+    connectionType: "stdio" | "sse";
+    command?: string;
+    sseUrl?: string;
+    args?: string[];
+    env?: Record<string, string>;
+    sseHeaders?: Record<string, string>;
+  }
+): void {
+  const { connectionType, command, sseUrl, args, env, sseHeaders } = options;
+  const stdioFields: string[] = [];
+  if (hasNonEmptyString(command)) {
+    stdioFields.push("command");
+  }
+  if (typeof args !== "undefined") {
+    stdioFields.push("args");
+  }
+  if (typeof env !== "undefined") {
+    stdioFields.push("env");
+  }
+
+  const sseFields: string[] = [];
+  if (hasNonEmptyString(sseUrl)) {
+    sseFields.push("sseUrl");
+  }
+  if (typeof sseHeaders !== "undefined") {
+    sseFields.push("sseHeaders");
+  }
+
+  if (connectionType === "sse" && stdioFields.length > 0) {
+    throw new Error(
+      `MCP SSE connection cannot include stdio fields: ${stdioFields.join(", ")}`
+    );
+  }
+  if (connectionType === "stdio" && sseFields.length > 0) {
+    throw new Error(
+      `MCP stdio connection cannot include sse fields: ${sseFields.join(", ")}`
+    );
+  }
+}
+
+function normalizeMCPConnectionCommand(command?: string): string {
+  if (typeof command !== "string") {
+    throw new Error("Command is required for stdio connection type");
+  }
+  const normalized = command.trim();
+  if (normalized.length === 0) {
+    throw new Error("Command is required for stdio connection type");
+  }
+  if (hasAnyControlChars(normalized)) {
+    throw new Error("MCP command contains unsupported control characters");
+  }
+  if (normalized.length > MAX_MCP_CONFIG_COMMAND_CHARS) {
+    throw new Error(
+      `MCP command exceeds ${MAX_MCP_CONFIG_COMMAND_CHARS} characters`
+    );
+  }
+  return normalized;
+}
+
+function normalizeMCPConnectionSSEUrl(sseUrl?: string): string {
+  if (typeof sseUrl !== "string") {
+    throw new Error("SSE URL is required for SSE connection type");
+  }
+  const normalized = sseUrl.trim();
+  if (normalized.length === 0) {
+    throw new Error("SSE URL is required for SSE connection type");
+  }
+  if (hasAnyControlChars(normalized)) {
+    throw new Error("SSE URL contains unsupported control characters");
+  }
+  if (normalized.length > MAX_MCP_CONFIG_SSE_URL_CHARS) {
+    throw new Error(
+      `SSE URL exceeds ${MAX_MCP_CONFIG_SSE_URL_CHARS} characters`
+    );
+  }
+  let parsedUrl: URL;
+  try {
+    parsedUrl = new URL(normalized);
+  } catch {
+    throw new Error("Invalid SSE URL for SSE connection type");
+  }
+  if (parsedUrl.protocol !== "http:" && parsedUrl.protocol !== "https:") {
+    throw new Error("SSE URL must use http:// or https://");
+  }
+  return parsedUrl.toString();
+}
+
+function normalizeMCPConnectionArgs(args?: string[]): string[] | undefined {
+  if (typeof args === "undefined") {
+    return undefined;
+  }
+  if (!Array.isArray(args)) {
+    throw new Error("MCP command args must be an array of non-empty strings");
+  }
+  let argCount = 0;
+  try {
+    argCount = args.length;
+  } catch {
+    throw new Error("MCP command args must be an array of non-empty strings");
+  }
+  if (argCount > MAX_MCP_CONFIG_ARGS_PER_SERVER) {
+    throw new Error(
+      `MCP command args cannot contain more than ${MAX_MCP_CONFIG_ARGS_PER_SERVER} entries`
+    );
+  }
+  const normalizedArgs: string[] = [];
+  for (let index = 0; index < argCount; index += 1) {
+    let arg: unknown;
+    try {
+      arg = args[index];
+    } catch {
+      throw new Error("MCP command args must be an array of non-empty strings");
+    }
+    if (typeof arg !== "string") {
+      throw new Error("MCP command args must be an array of non-empty strings");
+    }
+    const normalized = arg.trim();
+    if (normalized.length === 0) {
+      throw new Error("MCP command args must be an array of non-empty strings");
+    }
+    if (hasAnyControlChars(normalized)) {
+      throw new Error("MCP command args contain unsupported control characters");
+    }
+    if (normalized.length > MAX_MCP_CONFIG_ARG_CHARS) {
+      throw new Error(
+        `MCP command args cannot include entries longer than ${MAX_MCP_CONFIG_ARG_CHARS} characters`
+      );
+    }
+    normalizedArgs.push(normalized);
+  }
+  return normalizedArgs;
+}
+
+function normalizeMCPConnectionStringRecord(
+  field: "env" | "sseHeaders",
+  value: unknown
+): Record<string, string> | undefined {
+  if (typeof value === "undefined") {
+    return undefined;
+  }
+  if (!isPlainRecord(value)) {
+    throw new Error(
+      `MCP ${field} must be an object of string key/value pairs`
+    );
+  }
+  let entries: Array<[string, unknown]>;
+  try {
+    entries = Object.entries(value);
+  } catch {
+    throw new Error(
+      `MCP ${field} must be an object of string key/value pairs`
+    );
+  }
+  if (entries.length > MAX_MCP_CONFIG_RECORD_ENTRIES) {
+    throw new Error(
+      `MCP ${field} cannot include more than ${MAX_MCP_CONFIG_RECORD_ENTRIES} entries`
+    );
+  }
+  const normalized: Record<string, string> = Object.create(null);
+  const seenKeys = new Set<string>();
+  for (const [rawKey, rawValue] of entries) {
+    const key = rawKey.trim();
+    const lowerKey = key.toLowerCase();
+    if (
+      key.length === 0 ||
+      key.length > MAX_MCP_CONFIG_RECORD_KEY_CHARS ||
+      hasAnyControlChars(key) ||
+      UNSAFE_MCP_RECORD_KEYS.has(lowerKey) ||
+      typeof rawValue !== "string" ||
+      hasAnyControlChars(rawValue)
+    ) {
+      throw new Error(
+        `MCP ${field} must be an object of string key/value pairs`
+      );
+    }
+    if (field === "sseHeaders" && !HTTP_HEADER_NAME_PATTERN.test(key)) {
+      throw new Error(
+        `MCP ${field} must be an object of string key/value pairs`
+      );
+    }
+    const normalizedValue =
+      field === "sseHeaders" ? rawValue.trim() : rawValue;
+    if (
+      normalizedValue.length > MAX_MCP_CONFIG_RECORD_VALUE_CHARS ||
+      (field === "sseHeaders" && normalizedValue.length === 0)
+    ) {
+      throw new Error(
+        `MCP ${field} must be an object of string key/value pairs`
+      );
+    }
+    const duplicateLookup = field === "sseHeaders" ? lowerKey : key;
+    if (seenKeys.has(duplicateLookup)) {
+      throw new Error(`MCP ${field} contains duplicate key "${key}"`);
+    }
+    seenKeys.add(duplicateLookup);
+    normalized[key] = normalizedValue;
+  }
+  return normalized;
+}
+
+function summarizeMCPServerIds(serverIds: string[]): string {
+  const preview = serverIds
+    .slice(0, MAX_MCP_AMBIGUOUS_SERVER_IDS)
+    .map((id) => formatMCPIdentifier(id, "unknown-server"));
+  const omitted = serverIds.length - preview.length;
+  if (omitted > 0) {
+    return `${preview.join(", ")}, ... (+${omitted} more)`;
+  }
+  return preview.join(", ");
+}
+
+function summarizeMCPToolNames(toolNames: string[]): string {
+  const preview = toolNames
+    .slice(0, MAX_MCP_TOOL_DIAGNOSTIC_ITEMS)
+    .map((name) => formatMCPIdentifier(name, "unknown-tool"));
+  const omitted = toolNames.length - preview.length;
+  if (omitted > 0) {
+    return `${preview.join(", ")}, ... (+${omitted} more)`;
+  }
+  return preview.join(", ");
+}
+
+function normalizeMCPToolFilterList(
+  value: string[] | undefined,
+  fieldName: "includeTools" | "excludeTools"
+): Set<string> | undefined {
+  if (typeof value === "undefined") {
+    return undefined;
+  }
+  if (!Array.isArray(value)) {
+    throw new Error(`MCP ${fieldName} must be an array of tool names`);
+  }
+  const normalizedValues = value.map((name) =>
+    normalizeMCPExecutionToolName(name)
+  );
+  const seenNames = new Set<string>();
+  const seenNamesLower = new Set<string>();
+  for (const normalizedName of normalizedValues) {
+    const lower = normalizedName.toLowerCase();
+    if (seenNamesLower.has(lower)) {
+      throw new Error(
+        `MCP ${fieldName} contains duplicate tool name "${formatMCPIdentifier(
+          normalizedName,
+          "unknown-tool"
+        )}" after normalization`
+      );
+    }
+    seenNamesLower.add(lower);
+    seenNames.add(normalizedName);
+  }
+  return seenNames;
+}
+
+function normalizeMCPToolFilterListValues(
+  value: string[] | undefined,
+  fieldName: "includeTools" | "excludeTools"
+): string[] | undefined {
+  const normalizedSet = normalizeMCPToolFilterList(value, fieldName);
+  if (!normalizedSet) {
+    return undefined;
+  }
+  return Array.from(normalizedSet);
+}
+
+function safeHasOwnProperty(value: Record<string, unknown>, key: string): boolean {
+  try {
+    return Object.prototype.hasOwnProperty.call(value, key);
+  } catch {
+    return false;
+  }
+}
+
+export function normalizeDiscoveredMCPTools(
+  tools: Tool[],
+  options: MCPToolDiscoveryOptions
+): NormalizedDiscoveredMCPTool[] {
+  const includeSet = normalizeMCPToolFilterList(
+    options.includeTools,
+    "includeTools"
+  );
+  const excludeSet = normalizeMCPToolFilterList(
+    options.excludeTools,
+    "excludeTools"
+  );
+  const includeLookup = includeSet
+    ? new Set(Array.from(includeSet).map((name) => name.toLowerCase()))
+    : undefined;
+  const excludeLookup = excludeSet
+    ? new Set(Array.from(excludeSet).map((name) => name.toLowerCase()))
+    : undefined;
+  if (includeSet && excludeSet) {
+    const overlap = Array.from(excludeSet).filter((name) =>
+      includeLookup?.has(name.toLowerCase())
+    );
+    if (overlap.length > 0) {
+      throw new Error(
+        `MCP includeTools and excludeTools overlap on: ${summarizeMCPToolNames(
+          overlap
+        )}`
+      );
+    }
+  }
+  const seenToolNames = new Set<string>();
+  const seenToolNamesByLookup = new Map<string, string>();
+  const normalizedTools: NormalizedDiscoveredMCPTool[] = [];
+
+  for (const tool of tools) {
+    const normalizedName = normalizeMCPExecutionToolName(tool.name);
+    const normalizedLookup = normalizedName.toLowerCase();
+    if (seenToolNames.has(normalizedName)) {
+      throw new Error(
+        `MCP server returned duplicate tool name "${formatMCPIdentifier(
+          normalizedName,
+          "unknown-tool"
+        )}"`
+      );
+    }
+    const existingCaseVariant = seenToolNamesByLookup.get(normalizedLookup);
+    if (existingCaseVariant && existingCaseVariant !== normalizedName) {
+      throw new Error(
+        `MCP server returned duplicate tool name "${formatMCPIdentifier(
+          normalizedName,
+          "unknown-tool"
+        )}" after case normalization (conflicts with "${formatMCPIdentifier(
+          existingCaseVariant,
+          "unknown-tool"
+        )}")`
+      );
+    }
+    seenToolNames.add(normalizedName);
+    seenToolNamesByLookup.set(normalizedLookup, normalizedName);
+
+    if (includeLookup && !includeLookup.has(normalizedLookup)) {
+      continue;
+    }
+    if (excludeLookup && excludeLookup.has(normalizedLookup)) {
+      continue;
+    }
+
+    normalizedTools.push({
+      tool,
+      normalizedName,
+    });
+  }
+
+  if (includeSet && normalizedTools.length === 0) {
+    const includeNames = summarizeMCPToolNames(Array.from(includeSet));
+    const availableNames =
+      seenToolNames.size === 0
+        ? "none"
+        : summarizeMCPToolNames(Array.from(seenToolNames));
+    throw new Error(
+      `No MCP tools matched includeTools filter (${includeNames}). Available tools: ${availableNames}.`
+    );
+  }
+
+  return normalizedTools;
+}
+
+export function normalizeMCPListToolsPayload(value: unknown): Tool[] {
+  if (!isPlainRecord(value) || !safeHasOwnProperty(value, "tools")) {
+    throw new Error("Invalid MCP listTools response: expected a tools array");
+  }
+  let toolsValue: unknown;
+  try {
+    toolsValue = value.tools;
+  } catch {
+    throw new Error(
+      "Invalid MCP listTools response: unable to read tools array"
+    );
+  }
+  if (!Array.isArray(toolsValue)) {
+    throw new Error("Invalid MCP listTools response: expected a tools array");
+  }
+  if (toolsValue.length > MAX_MCP_DISCOVERED_TOOLS) {
+    throw new Error(
+      `Invalid MCP listTools response: received more than ${MAX_MCP_DISCOVERED_TOOLS} tools`
+    );
+  }
+  if (
+    toolsValue.some((tool) => typeof tool !== "object" || tool === null)
+  ) {
+    throw new Error(
+      "Invalid MCP listTools response: each tool entry must be an object"
+    );
+  }
+  return toolsValue as Tool[];
+}
+
+function safeGetMCPListToolsPayload(value: unknown): Tool[] {
+  try {
+    return normalizeMCPListToolsPayload(value);
+  } catch (error) {
+    const message = formatMCPRuntimeDiagnostic(error);
+    const prefix = "Invalid MCP listTools response:";
+    if (message.startsWith(prefix)) {
+      throw new Error(message);
+    }
+    throw new Error(`${prefix} ${message}`);
+  }
+}
+
+function findConnectedServerId(
+  servers: Map<string, ServerConnection>,
+  requestedId: string
+): string | undefined {
+  if (servers.has(requestedId)) {
+    return requestedId;
+  }
+  const requestedLookup = requestedId.toLowerCase();
+  for (const existingId of servers.keys()) {
+    if (existingId.toLowerCase() === requestedLookup) {
+      return existingId;
+    }
+  }
+  return undefined;
+}
+
+function resolveConnectedServerIdForManagement(
+  servers: Map<string, ServerConnection>,
+  requestedId: unknown
+): string | undefined {
+  if (typeof requestedId !== "string") {
+    return undefined;
+  }
+  const normalized = requestedId.trim();
+  if (normalized.length === 0 || hasAnyControlChars(normalized)) {
+    return undefined;
+  }
+  try {
+    return findConnectedServerId(servers, normalized);
+  } catch {
+    return undefined;
+  }
+}
+
+function safeGetConnectedServerIds(
+  servers: Map<string, ServerConnection>
+): string[] {
+  try {
+    return Array.from(servers.keys());
+  } catch {
+    return [];
+  }
+}
+
+function sanitizeConnectedServerIdsForOutput(
+  serverIds: string[]
+): string[] {
+  return serverIds
+    .filter((serverId): serverId is string => typeof serverId === "string")
+    .map((serverId) => formatMCPIdentifier(serverId, "unknown-server"));
+}
+
+function safeGetConnectedServerEntries(
+  servers: Map<string, ServerConnection>
+): Array<[string, ServerConnection]> {
+  try {
+    return Array.from(servers.entries());
+  } catch {
+    return [];
+  }
+}
+
+function readServerTools(server: ServerConnection): Map<string, Tool> {
+  let tools: unknown;
+  try {
+    tools = (server as { tools?: unknown }).tools;
+  } catch (error) {
+    throw new Error(
+      `MCP server tools are unavailable: ${formatMCPIdentifier(
+        error,
+        "unknown-error"
+      )}`
+    );
+  }
+  if (!tools || typeof tools !== "object") {
+    throw new Error("MCP server tools are unavailable: invalid tools registry");
+  }
+  const hasMethod = (method: string): boolean => {
+    try {
+      return typeof (tools as Record<string, unknown>)[method] === "function";
+    } catch {
+      return false;
+    }
+  };
+  if (!hasMethod("has") || !hasMethod("get") || !hasMethod("keys")) {
+    throw new Error("MCP server tools are unavailable: invalid tools registry");
+  }
+  return tools as Map<string, Tool>;
+}
+
+function safeReadServerTools(server: ServerConnection): Map<string, Tool> | undefined {
+  try {
+    return readServerTools(server);
+  } catch {
+    return undefined;
+  }
+}
+
+function safeGetServerActions(server: ServerConnection): AgentActionDefinition[] {
+  try {
+    const actions = (server as { actions?: unknown }).actions;
+    if (!Array.isArray(actions)) {
+      return [];
+    }
+    return actions.filter(
+      (action): action is AgentActionDefinition =>
+        typeof action === "object" && action !== null
+    );
+  } catch {
+    return [];
+  }
+}
+
+function safeGetServerToolNames(server: ServerConnection): string[] {
+  const tools = safeReadServerTools(server);
+  if (!tools) {
+    return [];
+  }
+  try {
+    return Array.from(tools.keys())
+      .filter((name): name is string => typeof name === "string")
+      .map((name) => formatMCPIdentifier(name, "unknown-tool"));
+  } catch {
+    return [];
+  }
+}
+
+function safeGetConnectedServerCount(
+  servers: Map<string, ServerConnection>
+): number {
+  try {
+    return servers.size;
+  } catch {
+    return 0;
+  }
+}
+
+function safeFindConnectedServerId(
+  servers: Map<string, ServerConnection>,
+  requestedId: string
+): string | undefined {
+  try {
+    return findConnectedServerId(servers, requestedId);
+  } catch {
+    return undefined;
+  }
+}
+
+function safeHasConnectedServer(
+  servers: Map<string, ServerConnection>,
+  serverId: string
+): boolean {
+  try {
+    return servers.has(serverId);
+  } catch {
+    return false;
+  }
+}
+
+function safeGetConnectedServer(
+  servers: Map<string, ServerConnection>,
+  serverId: string
+): ServerConnection | undefined {
+  try {
+    return servers.get(serverId);
+  } catch {
+    return undefined;
+  }
+}
+
+function resolveMCPToolNameOnServer(
+  tools: Map<string, Tool>,
+  requestedToolName: string
+): { toolName?: string; ambiguousMatches?: string[] } {
+  let hasExactToolMatch = false;
+  try {
+    hasExactToolMatch = tools.has(requestedToolName);
+  } catch (error) {
+    throw new Error(
+      `MCP tool registry lookup failed: ${formatMCPIdentifier(
+        error,
+        "unknown-error"
+      )}`
+    );
+  }
+  if (hasExactToolMatch) {
+    return { toolName: requestedToolName };
+  }
+  const requestedLookup = requestedToolName.toLowerCase();
+  let toolNames: string[];
+  try {
+    toolNames = Array.from(tools.keys());
+  } catch (error) {
+    throw new Error(
+      `MCP tool registry lookup failed: ${formatMCPIdentifier(
+        error,
+        "unknown-error"
+      )}`
+    );
+  }
+  const caseInsensitiveMatches = toolNames.filter(
+    (toolName) => toolName.toLowerCase() === requestedLookup
+  );
+  if (caseInsensitiveMatches.length === 1) {
+    return { toolName: caseInsensitiveMatches[0] };
+  }
+  if (caseInsensitiveMatches.length > 1) {
+    return { ambiguousMatches: caseInsensitiveMatches };
+  }
+  return {};
+}
+
+function safeGetMCPToolByName(
+  tools: Map<string, Tool>,
+  toolName: string
+): Tool | undefined {
+  try {
+    return tools.get(toolName);
+  } catch (error) {
+    throw new Error(
+      `MCP tool registry lookup failed: ${formatMCPIdentifier(
+        error,
+        "unknown-error"
+      )}`
+    );
+  }
+}
+
+function isPlainRecord(value: unknown): value is Record<string, unknown> {
+  if (typeof value !== "object" || value === null || Array.isArray(value)) {
+    return false;
+  }
+  const prototype = Object.getPrototypeOf(value);
+  return prototype === Object.prototype || prototype === null;
+}
+
+const MCPToolActionParams = z.object({
+  params: z
+    .union([z.string(), z.record(z.string(), z.unknown())])
+    .describe(
+      "Parameters for the MCP tool. Provide either a JSON object directly or a JSON string."
+    ),
+});
+
+type MCPToolActionInput = z.infer<typeof MCPToolActionParams>;
+
+export function stringifyMCPPayload(value: unknown): string {
+  const truncate = (content: string): string =>
+    content.length <= MAX_MCP_PAYLOAD_CHARS
+      ? content
+      : `${content.slice(0, MAX_MCP_PAYLOAD_CHARS)}... [truncated]`;
+
+  try {
+    const serialized = JSON.stringify(value);
+    return truncate(
+      typeof serialized === "string"
+        ? serialized
+        : formatUnknownError(value)
+    );
+  } catch {
+    return truncate(formatUnknownError(value));
+  }
+}
+
+export function normalizeMCPToolDescription(value: unknown): string {
+  if (typeof value !== "string") {
+    return "";
+  }
+  const normalized = value
+    .replace(/[\u0000-\u001F\u007F]/g, " ")
+    .replace(/\s+/g, " ")
+    .trim();
+  if (normalized.length <= MAX_MCP_TOOL_DESCRIPTION_CHARS) {
+    return normalized;
+  }
+  const omitted = normalized.length - MAX_MCP_TOOL_DESCRIPTION_CHARS;
+  return `${normalized.slice(
+    0,
+    MAX_MCP_TOOL_DESCRIPTION_CHARS
+  )}... [truncated ${omitted} chars]`;
+}
+
+export function normalizeMCPToolParams(
+  input: MCPToolActionInput["params"]
+): Record<string, unknown> {
+  const normalizeParamKey = (value: string): string => value.trim().toLowerCase();
+
+  const sanitizeParamValue = (
+    value: unknown,
+    seen: WeakSet<object>,
+    depth: number
+  ): unknown => {
+    if (depth > MAX_MCP_PARAM_DEPTH) {
+      throw new Error(
+        `MCP tool params exceed maximum nesting depth of ${MAX_MCP_PARAM_DEPTH}`
+      );
+    }
+
+    if (Array.isArray(value)) {
+      if (seen.has(value)) {
+        throw new Error("MCP tool params cannot include circular references");
+      }
+      if (value.length > MAX_MCP_PARAM_COLLECTION_SIZE) {
+        throw new Error(
+          `MCP tool params cannot include collections with more than ${MAX_MCP_PARAM_COLLECTION_SIZE} entries`
+        );
+      }
+      seen.add(value);
+      try {
+        return value.map((entry) => sanitizeParamValue(entry, seen, depth + 1));
+      } finally {
+        seen.delete(value);
+      }
+    }
+    if (typeof value === "number" && !Number.isFinite(value)) {
+      throw new Error("MCP tool params cannot include non-finite number values");
+    }
+    if (typeof value === "bigint") {
+      return `${value.toString()}n`;
+    }
+    if (typeof value === "symbol") {
+      return value.toString();
+    }
+    if (typeof value === "function") {
+      return `[Function ${value.name || "anonymous"}]`;
+    }
+    if (typeof value === "string") {
+      return validateParamStringValue(value);
+    }
+    if (value instanceof Date) {
+      return Number.isNaN(value.getTime()) ? value.toString() : value.toISOString();
+    }
+    if (value instanceof Set) {
+      if (seen.has(value)) {
+        throw new Error("MCP tool params cannot include circular references");
+      }
+      if (value.size > MAX_MCP_PARAM_COLLECTION_SIZE) {
+        throw new Error(
+          `MCP tool params cannot include collections with more than ${MAX_MCP_PARAM_COLLECTION_SIZE} entries`
+        );
+      }
+      seen.add(value);
+      try {
+        return Array.from(value).map((entry) =>
+          sanitizeParamValue(entry, seen, depth + 1)
+        );
+      } finally {
+        seen.delete(value);
+      }
+    }
+    if (value instanceof Map) {
+      if (seen.has(value)) {
+        throw new Error("MCP tool params cannot include circular references");
+      }
+      if (value.size > MAX_MCP_PARAM_COLLECTION_SIZE) {
+        throw new Error(
+          `MCP tool params cannot include collections with more than ${MAX_MCP_PARAM_COLLECTION_SIZE} entries`
+        );
+      }
+      seen.add(value);
+      try {
+        const sanitizedMap: Record<string, unknown> = Object.create(null);
+        const seenMapKeys = new Set<string>();
+        for (const [rawKey, mapValue] of value.entries()) {
+          const normalizedRawKey =
+            typeof rawKey === "string" ? rawKey : formatUnknownError(rawKey);
+          const trimmedMapKey = normalizedRawKey.trim();
+          if (trimmedMapKey.length === 0) {
+            throw new Error("MCP tool params cannot include empty keys");
+          }
+          if (trimmedMapKey.length > MAX_MCP_PARAM_KEY_CHARS) {
+            throw new Error(
+              `MCP tool params cannot include keys longer than ${MAX_MCP_PARAM_KEY_CHARS} characters`
+            );
+          }
+          if (hasAnyControlChars(trimmedMapKey)) {
+            throw new Error(
+              "MCP tool params cannot include keys with control characters"
+            );
+          }
+          const normalizedMapKey = trimmedMapKey.replace(/\s+/g, " ");
+          if (seenMapKeys.has(normalizedMapKey)) {
+            throw new Error(
+              `MCP tool params cannot include duplicate key after trimming: "${normalizedMapKey}"`
+            );
+          }
+          seenMapKeys.add(normalizedMapKey);
+          sanitizedMap[normalizedMapKey] = sanitizeParamValue(
+            mapValue,
+            seen,
+            depth + 1
+          );
+        }
+        return sanitizedMap;
+      } finally {
+        seen.delete(value);
+      }
+    }
+    if (typeof value === "object" && value !== null) {
+      if (seen.has(value)) {
+        throw new Error("MCP tool params cannot include circular references");
+      }
+      if (!isPlainRecord(value)) {
+        return validateParamStringValue(formatUnknownError(value));
+      }
+      seen.add(value);
+      try {
+        const sanitized: Record<string, unknown> = Object.create(null);
+        const entries = Object.entries(value);
+        if (entries.length > MAX_MCP_PARAM_COLLECTION_SIZE) {
+          throw new Error(
+            `MCP tool params cannot include collections with more than ${MAX_MCP_PARAM_COLLECTION_SIZE} entries`
+          );
+        }
+        const seenKeys = new Set<string>();
+        for (const [key, paramValue] of entries) {
+          const trimmedObjectKey = key.trim();
+          if (trimmedObjectKey.length === 0) {
+            throw new Error("MCP tool params cannot include empty keys");
+          }
+          if (trimmedObjectKey.length > MAX_MCP_PARAM_KEY_CHARS) {
+            throw new Error(
+              `MCP tool params cannot include keys longer than ${MAX_MCP_PARAM_KEY_CHARS} characters`
+            );
+          }
+          if (hasAnyControlChars(trimmedObjectKey)) {
+            throw new Error(
+              "MCP tool params cannot include keys with control characters"
+            );
+          }
+          const normalizedObjectKey = trimmedObjectKey.replace(/\s+/g, " ");
+          const normalizedKey = normalizeParamKey(key);
+          if (UNSAFE_OBJECT_KEYS.has(normalizedKey)) {
+            throw new Error(`MCP tool params cannot include reserved key "${key}"`);
+          }
+          if (seenKeys.has(normalizedObjectKey)) {
+            throw new Error(
+              `MCP tool params cannot include duplicate key after trimming: "${normalizedObjectKey}"`
+            );
+          }
+          seenKeys.add(normalizedObjectKey);
+          sanitized[normalizedObjectKey] = sanitizeParamValue(
+            paramValue,
+            seen,
+            depth + 1
+          );
+        }
+        return sanitized;
+      } finally {
+        seen.delete(value);
+      }
+    }
+    return value;
+  };
+
+  const sanitizeParamInput = (value: unknown): Record<string, unknown> => {
+    const sanitized = sanitizeParamValue(value, new WeakSet<object>(), 0);
+    if (
+      typeof sanitized !== "object" ||
+      sanitized === null ||
+      Array.isArray(sanitized)
+    ) {
+      throw new Error("MCP tool params must be a JSON object at the root level");
+    }
+    return sanitized as Record<string, unknown>;
+  };
+
+  if (typeof input === "string") {
+    const trimmedInput = input.trim();
+    if (trimmedInput.length === 0) {
+      throw new Error(
+        "Invalid MCP tool params JSON string: input is empty"
+      );
+    }
+    if (hasUnsupportedControlChars(trimmedInput)) {
+      throw new Error(
+        "Invalid MCP tool params JSON string: contains unsupported control characters"
+      );
+    }
+    if (trimmedInput.length > MAX_MCP_TOOL_PARAMS_JSON_CHARS) {
+      throw new Error(
+        `Invalid MCP tool params JSON string: exceeds ${MAX_MCP_TOOL_PARAMS_JSON_CHARS} characters`
+      );
+    }
+    let parsed: unknown;
+    try {
+      parsed = JSON.parse(trimmedInput);
+    } catch (error) {
+      const message = formatMCPRuntimeDiagnostic(error);
+      throw new Error(`Invalid MCP tool params JSON string: ${message}`);
+    }
+    if (typeof parsed !== "object" || parsed === null || Array.isArray(parsed)) {
+      throw new Error(
+        "MCP tool params must parse to a JSON object, not an array or primitive"
+      );
+    }
+    return sanitizeParamInput(parsed);
+  }
+
+  return sanitizeParamInput(input);
+}
+
 class MCPClient {
   private servers: Map<string, ServerConnection> = new Map();
   private debug: boolean;
@@ -31,55 +1157,97 @@ class MCPClient {
   async connectToServer(
     serverConfig: MCPServerConfig
   ): Promise<{ serverId: string; actions: AgentActionDefinition[] }> {
+    let pendingTransport: StdioClientTransport | SSEClientTransport | undefined;
+    let pendingServerId: string | undefined;
     try {
+      if (!isMCPServerConfig(serverConfig)) {
+        throw new Error("MCP server config must be an object");
+      }
       // Generate or use provided server ID
-      const serverId = serverConfig.id || uuidv4();
+      const normalizedConfigServerId = normalizeMCPConnectionServerId(
+        serverConfig.id
+      );
+      const serverId = normalizedConfigServerId || uuidv4();
+      const normalizedIncludeTools = normalizeMCPToolFilterListValues(
+        serverConfig.includeTools,
+        "includeTools"
+      );
+      const normalizedExcludeTools = normalizeMCPToolFilterListValues(
+        serverConfig.excludeTools,
+        "excludeTools"
+      );
+      pendingServerId = serverId;
+      const existingServerId = findConnectedServerId(this.servers, serverId);
+      if (existingServerId) {
+        throw new Error(
+          `MCP server with ID "${formatMCPIdentifier(
+            serverId,
+            "unknown-server"
+          )}" is already connected`
+        );
+      }
 
       // Create transport for this server
       let transport;
-      const connectionType = serverConfig?.connectionType || "stdio";
+      const connectionType = resolveMCPConnectionType(serverConfig);
+      const args = normalizeMCPConnectionArgs(serverConfig.args);
+      const env = normalizeMCPConnectionStringRecord("env", serverConfig.env);
+      const sseHeaders = normalizeMCPConnectionStringRecord(
+        "sseHeaders",
+        serverConfig.sseHeaders
+      );
+      let normalizedCommand: string | undefined;
+      let normalizedSSEUrl: string | undefined;
+      validateMCPConnectionFieldMix({
+        connectionType,
+        command: serverConfig.command,
+        sseUrl: serverConfig.sseUrl,
+        args,
+        env,
+        sseHeaders,
+      });
 
       if (connectionType === "sse") {
-        if (!serverConfig.sseUrl) {
-          throw new Error("SSE URL is required for SSE connection type");
-        }
+        const sseUrl = normalizeMCPConnectionSSEUrl(serverConfig.sseUrl);
+        normalizedSSEUrl = sseUrl;
 
         if (this.debug) {
           console.log(
-            `Establishing SSE connection to ${serverConfig.sseUrl}...`
+            `Establishing SSE connection to ${sseUrl}...`
           );
         }
 
         transport = new SSEClientTransport(
-          new URL(serverConfig.sseUrl),
-          serverConfig.sseHeaders
+          new URL(sseUrl),
+          sseHeaders
             ? {
                 requestInit: {
-                  headers: serverConfig.sseHeaders,
+                  headers: sseHeaders,
                 },
               }
             : undefined
         );
 
-        transport.onerror = (error: any) => {
-          console.error(`SSE error: ${error.message}`);
+        transport.onerror = (error: unknown) => {
+          const message = formatMCPRuntimeDiagnostic(error);
+          console.error(`SSE error: ${message}`);
         };
       } else {
-        if (!serverConfig.command) {
-          throw new Error("Command is required for stdio connection type");
-        }
+        const command = normalizeMCPConnectionCommand(serverConfig.command);
+        normalizedCommand = command;
 
         transport = new StdioClientTransport({
-          command: serverConfig.command,
-          args: serverConfig.args,
+          command,
+          args,
           env: {
             ...((process.env ?? {}) as Record<string, string>),
-            ...(serverConfig.env ?? {}),
+            ...(env ?? {}),
           },
           // Pipe stdin/stdout, ignore stderr
           stderr: this.debug ? "inherit" : "ignore",
         });
       }
+      pendingTransport = transport;
 
       const client = new Client({
         name: `hyperagent-mcp-client-${serverId}`,
@@ -89,44 +1257,38 @@ class MCPClient {
       await client.connect(transport);
 
       const toolsResult = await client.listTools();
+      const listedTools = safeGetMCPListToolsPayload(toolsResult);
       const toolsMap = new Map<string, Tool>();
 
+      const discoveredTools = normalizeDiscoveredMCPTools(
+        listedTools,
+        {
+          includeTools: normalizedIncludeTools,
+          excludeTools: normalizedExcludeTools,
+        }
+      );
+
       // Create actions for each tool
-      const actions = toolsResult.tools
-        .filter((tool) => {
-          if (
-            serverConfig.includeTools &&
-            !serverConfig.includeTools.includes(tool.name)
-          ) {
-            return false;
-          }
-          if (
-            serverConfig.excludeTools &&
-            serverConfig.excludeTools.includes(tool.name)
-          ) {
-            return false;
-          }
-          return true;
-        })
-        .map((tool) => {
+      const actions = discoveredTools.map(({ tool, normalizedName }) => {
+          const normalizedToolDescription = normalizeMCPToolDescription(
+            tool.description
+          );
+          const descriptionPrefix =
+            normalizedToolDescription.length > 0
+              ? `${normalizedToolDescription} `
+              : "";
           // Store tool reference for later use
-          toolsMap.set(tool.name, tool);
+          toolsMap.set(normalizedName, tool);
 
           // Create action definition
           return {
-            type: tool.name,
-            actionParams: z
-              .object({
-                params: z
-                  .string()
-                  .describe(
-                    `The stringified parameters to the ${tool.name} MCP tool. Here is the schema: ${JSON.stringify(tool.inputSchema)}`
-                  ),
-              })
-              .describe(tool.description ?? ""),
+            type: normalizedName,
+            actionParams: MCPToolActionParams.describe(
+              `${descriptionPrefix}Tool input schema: ${stringifyMCPPayload(tool.inputSchema)}`
+            ),
             run: async (
               ctx: ActionContext,
-              action: any
+              action: MCPToolActionInput
             ): Promise<ActionOutput> => {
               if (!ctx.mcpClient) {
                 throw new Error(
@@ -134,27 +1296,53 @@ class MCPClient {
                 );
               }
 
-              const params = JSON.parse(action.params);
+              const params = normalizeMCPToolParams(action.params);
               const targetServerId = serverId;
 
               const result = await ctx.mcpClient.executeTool(
-                tool.name,
+                normalizedName,
                 params,
                 targetServerId
               );
 
               return {
                 success: true,
-                message: `MCP tool ${tool.name} execution successful: ${JSON.stringify(result)}`,
+                message: `MCP tool ${normalizedName} execution successful: ${stringifyMCPPayload(result)}`,
               };
             },
           };
         });
 
+      const normalizedServerConfig: MCPServerConfig = {
+        id: serverId,
+        connectionType,
+      };
+      if (normalizedCommand) {
+        normalizedServerConfig.command = normalizedCommand;
+      }
+      if (args) {
+        normalizedServerConfig.args = args;
+      }
+      if (env) {
+        normalizedServerConfig.env = env;
+      }
+      if (normalizedSSEUrl) {
+        normalizedServerConfig.sseUrl = normalizedSSEUrl;
+      }
+      if (sseHeaders) {
+        normalizedServerConfig.sseHeaders = sseHeaders;
+      }
+      if (normalizedIncludeTools) {
+        normalizedServerConfig.includeTools = normalizedIncludeTools;
+      }
+      if (normalizedExcludeTools) {
+        normalizedServerConfig.excludeTools = normalizedExcludeTools;
+      }
+
       // Store server connection
       this.servers.set(serverId, {
         id: serverId,
-        config: serverConfig,
+        config: normalizedServerConfig,
         client,
         transport,
         tools: toolsMap,
@@ -165,9 +1353,30 @@ class MCPClient {
         console.log("Added tools:", Array.from(toolsMap.keys()));
       }
       return { serverId, actions };
-    } catch (e) {
-      console.error("Failed to connect to MCP server: ", e);
-      throw e;
+    } catch (error) {
+      const isPendingServerRegistered =
+        typeof pendingServerId === "string" &&
+        safeHasConnectedServer(this.servers, pendingServerId);
+      if (
+        pendingTransport &&
+        !isPendingServerRegistered
+      ) {
+        try {
+          await pendingTransport.close();
+        } catch (cleanupError) {
+          if (this.debug) {
+            console.warn(
+              `Failed to clean up MCP transport after connect failure: ${formatMCPRuntimeDiagnostic(
+                cleanupError
+              )}`
+            );
+          }
+        }
+      }
+      console.error(
+        `Failed to connect to MCP server: ${formatMCPRuntimeDiagnostic(error)}`
+      );
+      throw new Error(formatMCPRuntimeDiagnostic(error));
     }
   }
 
@@ -180,46 +1389,124 @@ class MCPClient {
    */
   async executeTool(
     toolName: string,
-    parameters: Record<string, any>,
+    parameters: Record<string, unknown> | string,
     serverId?: string
-  ): Promise<any> {
+  ): Promise<MCPToolResult> {
+    const normalizedParameters = normalizeMCPToolParams(parameters);
+    const normalizedToolName = normalizeMCPExecutionToolName(toolName);
+    const normalizedServerId = normalizeMCPExecutionServerId(serverId);
+    const safeToolName = formatMCPIdentifier(normalizedToolName, "unknown-tool");
+    const safeServerId = (): string =>
+      formatMCPIdentifier(serverId, "unknown-server");
+    let resolvedToolNameForServer: string | undefined;
+    const connectedServerCount = safeGetConnectedServerCount(this.servers);
+
     // If no server ID provided and only one server exists, use that one
-    if (!serverId && this.servers.size === 1) {
-      serverId = [...this.servers.keys()][0];
+    if (!normalizedServerId && connectedServerCount === 1) {
+      serverId = safeGetConnectedServerIds(this.servers)[0];
     }
 
     // If no server ID provided and multiple servers exist, try to find one with the tool
-    if (!serverId && this.servers.size > 1) {
-      for (const [id, server] of this.servers.entries()) {
-        if (server.tools.has(toolName)) {
-          serverId = id;
-          break;
+    if (!normalizedServerId && connectedServerCount > 1) {
+      const matchingServers: Array<{ serverId: string; toolName: string }> = [];
+      for (const [id, server] of safeGetConnectedServerEntries(this.servers)) {
+        const serverTools = safeReadServerTools(server);
+        if (!serverTools) {
+          continue;
+        }
+        let resolvedTool: { toolName?: string; ambiguousMatches?: string[] };
+        try {
+          resolvedTool = resolveMCPToolNameOnServer(
+            serverTools,
+            normalizedToolName
+          );
+        } catch {
+          continue;
+        }
+        if (resolvedTool.ambiguousMatches) {
+          throw new Error(
+            `Tool "${safeToolName}" matches multiple tools on server "${formatMCPIdentifier(
+              id,
+              "unknown-server"
+            )}" (${summarizeMCPToolNames(
+              resolvedTool.ambiguousMatches
+            )}). Use exact tool name.`
+          );
         }
+        if (resolvedTool.toolName) {
+          matchingServers.push({
+            serverId: id,
+            toolName: resolvedTool.toolName,
+          });
+        }
+      }
+      if (matchingServers.length === 1) {
+        serverId = matchingServers[0].serverId;
+        resolvedToolNameForServer = matchingServers[0].toolName;
       }
+      if (matchingServers.length > 1) {
+        throw new Error(
+          `Tool "${safeToolName}" is registered on multiple servers (${summarizeMCPServerIds(
+            matchingServers.map((entry) => entry.serverId)
+          )}). Provide serverId explicitly.`
+        );
+      }
+    } else if (normalizedServerId) {
+      serverId = safeFindConnectedServerId(this.servers, normalizedServerId);
     }
 
-    if (!serverId || !this.servers.has(serverId)) {
-      throw new Error(`No valid server found for tool ${toolName}`);
+    if (!serverId || !safeHasConnectedServer(this.servers, serverId)) {
+      throw new Error(`No valid server found for tool ${safeToolName}`);
     }
 
-    const server = this.servers.get(serverId);
+    const server = safeGetConnectedServer(this.servers, serverId);
     if (!server) {
-      throw new Error(`Server with ID ${serverId} not found`);
+      throw new Error(`Server with ID ${safeServerId()} not found`);
+    }
+    const serverTools = readServerTools(server);
+    const resolvedTool = resolvedToolNameForServer
+      ? { toolName: resolvedToolNameForServer }
+      : resolveMCPToolNameOnServer(serverTools, normalizedToolName);
+    if (resolvedTool.ambiguousMatches) {
+      throw new Error(
+        `Tool "${safeToolName}" matches multiple tools on server "${safeServerId()}" (${summarizeMCPToolNames(
+          resolvedTool.ambiguousMatches
+        )}). Use exact tool name.`
+      );
+    }
+    const resolvedToolName = resolvedTool.toolName;
+    if (!resolvedToolName) {
+      throw new Error(
+        `Tool "${safeToolName}" is not registered on server "${safeServerId()}"`
+      );
+    }
+    const registeredTool = safeGetMCPToolByName(serverTools, resolvedToolName);
+    if (!registeredTool) {
+      throw new Error(
+        `Tool "${safeToolName}" is not registered on server "${safeServerId()}"`
+      );
     }
 
     try {
+      const remoteToolName =
+        typeof registeredTool.name === "string" &&
+        registeredTool.name.length > 0
+          ? registeredTool.name
+          : normalizedToolName;
       const result = await server.client.callTool({
-        name: toolName,
-        arguments: parameters,
+        name: remoteToolName,
+        arguments: normalizedParameters,
       });
 
       return result;
-    } catch (e) {
+    } catch (error) {
+      const message = formatMCPRuntimeDiagnostic(error);
       console.error(
-        `Error executing tool ${toolName} on server ${serverId}:`,
-        e
+        `Error executing tool ${safeToolName} on server ${safeServerId()}: ${message}`
+      );
+      throw new Error(
+        `Error executing tool ${safeToolName} on server ${safeServerId()}: ${message}`
       );
-      throw e;
     }
   }
 
@@ -229,8 +1516,8 @@ class MCPClient {
    */
   getAllActions(): AgentActionDefinition[] {
     const allActions: AgentActionDefinition[] = [];
-    for (const server of this.servers.values()) {
-      allActions.push(...server.actions);
+    for (const [, server] of safeGetConnectedServerEntries(this.servers)) {
+      allActions.push(...safeGetServerActions(server));
     }
     return allActions;
   }
@@ -240,7 +1527,9 @@ class MCPClient {
    * @returns Array of server IDs
    */
   getServerIds(): string[] {
-    return [...this.servers.keys()];
+    return sanitizeConnectedServerIdsForOutput(
+      safeGetConnectedServerIds(this.servers)
+    );
   }
 
   /**
@@ -248,12 +1537,41 @@ class MCPClient {
    * @param serverId The ID of the server to disconnect from
    */
   async disconnectServer(serverId: string): Promise<void> {
-    const server = this.servers.get(serverId);
+    const resolvedServerId = resolveConnectedServerIdForManagement(
+      this.servers,
+      serverId
+    );
+    if (!resolvedServerId) {
+      return;
+    }
+    const server = safeGetConnectedServer(this.servers, resolvedServerId);
     if (server) {
-      await server.transport.close();
-      this.servers.delete(serverId);
+      let closeError: unknown;
+      let unregisterError: unknown;
+      try {
+        await server.transport.close();
+      } catch (error) {
+        closeError = error;
+      } finally {
+        try {
+          this.servers.delete(resolvedServerId);
+        } catch (error) {
+          unregisterError = error;
+        }
+      }
+      if (closeError) {
+        throw new Error(formatMCPRuntimeDiagnostic(closeError));
+      }
+      if (unregisterError) {
+        const safeServerId = formatMCPIdentifier(resolvedServerId, "unknown-server");
+        throw new Error(
+          `Failed to unregister MCP server ${safeServerId}: ${formatMCPRuntimeDiagnostic(
+            unregisterError
+          )}`
+        );
+      }
       if (this.debug) {
-        console.log(`Disconnected from MCP server with ID: ${serverId}`);
+        console.log(`Disconnected from MCP server with ID: ${resolvedServerId}`);
       }
     }
   }
@@ -262,8 +1580,15 @@ class MCPClient {
    * Disconnect from all servers
    */
   async disconnect(): Promise<void> {
-    for (const serverId of this.servers.keys()) {
-      await this.disconnectServer(serverId);
+    for (const serverId of safeGetConnectedServerIds(this.servers)) {
+      try {
+        await this.disconnectServer(serverId);
+      } catch (error) {
+        const safeServerId = formatMCPIdentifier(serverId, "unknown-server");
+        console.error(
+          `Failed to disconnect MCP server ${safeServerId}: ${formatMCPRuntimeDiagnostic(error)}`
+        );
+      }
     }
   }
 
@@ -272,13 +1597,58 @@ class MCPClient {
    * @param toolName The name of the tool to check
    * @returns Boolean indicating if the tool exists and the server ID it exists on
    */
-  hasTool(toolName: string): { exists: boolean; serverId?: string } {
-    for (const [serverId, server] of this.servers.entries()) {
-      if (server.tools.has(toolName)) {
-        return { exists: true, serverId };
+  hasTool(toolName: string): {
+    exists: boolean;
+    serverId?: string;
+    serverIds?: string[];
+    isAmbiguous?: boolean;
+  } {
+    let normalizedToolName: string;
+    try {
+      normalizedToolName = normalizeMCPExecutionToolName(toolName);
+    } catch {
+      return { exists: false };
+    }
+    const matchingServerIds: string[] = [];
+    const ambiguousServerIds: string[] = [];
+    for (const [serverId, server] of safeGetConnectedServerEntries(this.servers)) {
+      const serverTools = safeReadServerTools(server);
+      if (!serverTools) {
+        continue;
       }
+      try {
+        const resolvedTool = resolveMCPToolNameOnServer(
+          serverTools,
+          normalizedToolName
+        );
+        if (resolvedTool.ambiguousMatches) {
+          ambiguousServerIds.push(serverId);
+        } else if (resolvedTool.toolName) {
+          matchingServerIds.push(serverId);
+        }
+      } catch {
+        continue;
+      }
+    }
+    const allMatchedServerIds = [...matchingServerIds, ...ambiguousServerIds];
+    if (allMatchedServerIds.length === 0) {
+      return { exists: false };
+    }
+    const sanitizedMatchedServerIds = sanitizeConnectedServerIdsForOutput(
+      allMatchedServerIds
+    );
+    if (
+      sanitizedMatchedServerIds.length === 1 &&
+      ambiguousServerIds.length === 0
+    ) {
+      return { exists: true, serverId: sanitizedMatchedServerIds[0] };
     }
-    return { exists: false };
+    return {
+      exists: true,
+      serverId: sanitizedMatchedServerIds[0],
+      serverIds: sanitizedMatchedServerIds,
+      isAmbiguous: true,
+    };
   }
 
   /**
@@ -290,11 +1660,14 @@ class MCPClient {
     toolCount: number;
     toolNames: string[];
   }> {
-    return Array.from(this.servers.entries()).map(([id, server]) => ({
-      id,
-      toolCount: server.tools.size,
-      toolNames: Array.from(server.tools.keys()),
-    }));
+    return safeGetConnectedServerEntries(this.servers).map(([id, server]) => {
+      const toolNames = safeGetServerToolNames(server);
+      return {
+        id: formatMCPIdentifier(id, "unknown-server"),
+        toolCount: toolNames.length,
+        toolNames,
+      };
+    });
   }
 
   /**
@@ -302,7 +1675,7 @@ class MCPClient {
    * @returns Boolean indicating if any servers are connected
    */
   hasConnections(): boolean {
-    return this.servers.size > 0;
+    return this.getServerIds().length > 0;
   }
 }
 
diff --git a/src/agent/messages/builder.test.ts b/src/agent/messages/builder.test.ts
new file mode 100644
index 00000000..926c16b4
--- /dev/null
+++ b/src/agent/messages/builder.test.ts
@@ -0,0 +1,1203 @@
+import { buildAgentStepMessages } from "@/agent/messages/builder";
+import type { AgentStep } from "@/types/agent/types";
+import type { Page } from "playwright-core";
+
+jest.mock("@/utils/retry", () => ({
+  retry: jest.fn(),
+}));
+
+const { retry } = jest.requireMock("@/utils/retry") as {
+  retry: jest.Mock;
+};
+
+function createFakePage(url: string, urls: string[]): Page {
+  return {
+    url: () => url,
+    evaluate: jest.fn().mockResolvedValue({
+      scrollY: 10,
+      viewportHeight: 100,
+      totalHeight: 500,
+    }),
+    context: () =>
+      ({
+        pages: () =>
+          urls.map((tabUrl) => ({
+            url: () => tabUrl,
+          })),
+      }) as ReturnType<Page["context"]>,
+  } as unknown as Page;
+}
+
+function createStep(idx: number): AgentStep {
+  return {
+    idx,
+    agentOutput: {
+      thoughts: `thought-${idx}`,
+      memory: `memory-${idx}`,
+      action: {
+        type: "wait",
+        params: {
+          reason: "test",
+        },
+      },
+    },
+    actionOutput: {
+      success: true,
+      message: "ok",
+    },
+  };
+}
+
+describe("buildAgentStepMessages", () => {
+  beforeEach(() => {
+    retry.mockImplementation(async ({ func }: { func: () => Promise<unknown> }) =>
+      func()
+    );
+  });
+
+  it("includes open tabs and variable values while trimming old step history", async () => {
+    const steps = Array.from({ length: 12 }, (_, idx) => createStep(idx));
+    const page = createFakePage("https://example.com/current", [
+      "https://example.com/current",
+      "https://example.com/other",
+    ]);
+
+    const messages = await buildAgentStepMessages(
+      [{ role: "system", content: "system" }],
+      steps,
+      "task",
+      page,
+      {
+        elements: new Map(),
+        domState: "dom",
+        xpathMap: {},
+        backendNodeMap: {},
+      },
+      undefined,
+      [
+        {
+          key: "email",
+          value: "person@example.com",
+          description: "User email",
+        },
+      ]
+    );
+
+    const joined = messages
+      .map((message) =>
+        typeof message.content === "string" ? message.content : ""
+      )
+      .join("\n");
+
+    expect(joined).toContain("=== Open Tabs ===");
+    expect(joined).toContain("person@example.com");
+    expect(joined).toContain("older steps omitted");
+    expect(joined).toContain("latest 10 of 12 steps");
+    expect(joined).toContain("=== Earlier Actions Summary ===");
+    expect(joined).toContain("Step 0: action=wait");
+    expect(joined).not.toContain("thought-0");
+    expect(joined).toContain("thought-11");
+  });
+
+  it("bounds omitted-step summary details for oversized histories", async () => {
+    const page = createFakePage("https://example.com/current", [
+      "https://example.com/current",
+    ]);
+    const steps = Array.from({ length: 25 }, (_, idx) => {
+      const step = createStep(idx);
+      step.actionOutput.message = `message-${idx} ${"x".repeat(2_000)}`;
+      step.agentOutput.action.type = `action-${idx}-${"y".repeat(500)}`;
+      return step;
+    });
+
+    const messages = await buildAgentStepMessages(
+      [{ role: "system", content: "system" }],
+      steps,
+      "task",
+      page,
+      {
+        elements: new Map(),
+        domState: "dom",
+        xpathMap: {},
+        backendNodeMap: {},
+      },
+      undefined,
+      []
+    );
+
+    const summaryMessage = messages.find(
+      (message) =>
+        typeof message.content === "string" &&
+        message.content.includes("=== Earlier Actions Summary ===")
+    );
+    expect(summaryMessage).toBeDefined();
+    const summaryContent =
+      typeof summaryMessage?.content === "string" ? summaryMessage.content : "";
+    expect(summaryContent).toContain("[summary truncated");
+    expect(summaryContent).toContain("Step 10");
+    expect(summaryContent).not.toContain("Step 9");
+    expect(summaryContent.length).toBeLessThan(2_200);
+  });
+
+  it("does not crash when step extract payload is circular", async () => {
+    const circular: { self?: unknown } = {};
+    circular.self = circular;
+    const step = createStep(0);
+    step.actionOutput.extract = circular;
+    const page = createFakePage("https://example.com/current", [
+      "https://example.com/current",
+    ]);
+
+    const messages = await buildAgentStepMessages(
+      [{ role: "system", content: "system" }],
+      [step],
+      "task",
+      page,
+      {
+        elements: new Map(),
+        domState: "dom",
+        xpathMap: {},
+        backendNodeMap: {},
+      },
+      undefined,
+      []
+    );
+
+    const joined = messages
+      .map((message) =>
+        typeof message.content === "string" ? message.content : ""
+      )
+      .join("\n");
+
+    expect(joined).toContain('"self":"[Circular]"');
+  });
+
+  it("handles step payloads with throwing getters", async () => {
+    const trappedStep = new Proxy(
+      {},
+      {
+        get: (_target, prop) => {
+          if (prop === "agentOutput" || prop === "actionOutput") {
+            throw new Error("step getter trap");
+          }
+          return undefined;
+        },
+      }
+    );
+    const page = createFakePage("https://example.com/current", [
+      "https://example.com/current",
+    ]);
+
+    const messages = await buildAgentStepMessages(
+      [{ role: "system", content: "system" }],
+      [trappedStep as unknown as AgentStep],
+      "task",
+      page,
+      {
+        elements: new Map(),
+        domState: "dom",
+        xpathMap: {},
+        backendNodeMap: {},
+      },
+      undefined,
+      []
+    );
+
+    const joined = messages
+      .map((message) =>
+        typeof message.content === "string" ? message.content : ""
+      )
+      .join("\n");
+
+    expect(joined).toContain("Thoughts unavailable");
+    expect(joined).toContain("Memory unavailable");
+    expect(joined).toContain("Action output unavailable");
+  });
+
+  it("falls back to no previous-actions section when step array length getter traps", async () => {
+    const page = createFakePage("https://example.com/current", [
+      "https://example.com/current",
+    ]);
+    const trappedSteps = new Proxy([createStep(0)], {
+      get: (target, prop, receiver) => {
+        if (prop === "length") {
+          throw new Error("steps length trap");
+        }
+        return Reflect.get(target, prop, receiver);
+      },
+    });
+
+    const messages = await buildAgentStepMessages(
+      [{ role: "system", content: "system" }],
+      trappedSteps as unknown as AgentStep[],
+      "task",
+      page,
+      {
+        elements: new Map(),
+        domState: "dom",
+        xpathMap: {},
+        backendNodeMap: {},
+      },
+      undefined,
+      []
+    );
+
+    const joined = messages
+      .map((message) =>
+        typeof message.content === "string" ? message.content : ""
+      )
+      .join("\n");
+
+    expect(joined).not.toContain("=== Previous Actions ===");
+    expect(joined).toContain("=== Final Goal ===");
+  });
+
+  it("continues when base message array length getter traps", async () => {
+    const page = createFakePage("https://example.com/current", [
+      "https://example.com/current",
+    ]);
+    const trappedBaseMessages = new Proxy(
+      [{ role: "system", content: "seed message" }],
+      {
+        get: (target, prop, receiver) => {
+          if (prop === "length") {
+            throw new Error("base message length trap");
+          }
+          return Reflect.get(target, prop, receiver);
+        },
+      }
+    ) as unknown as Parameters<typeof buildAgentStepMessages>[0];
+
+    const messages = await buildAgentStepMessages(
+      trappedBaseMessages,
+      [],
+      "task",
+      page,
+      {
+        elements: new Map(),
+        domState: "dom",
+        xpathMap: {},
+        backendNodeMap: {},
+      },
+      undefined,
+      []
+    );
+
+    const joined = messages
+      .map((message) =>
+        typeof message.content === "string" ? message.content : ""
+      )
+      .join("\n");
+    expect(joined).toContain("=== Final Goal ===");
+    expect(joined).not.toContain("seed message");
+  });
+
+  it("keeps readable base messages when base message entry getter traps", async () => {
+    const page = createFakePage("https://example.com/current", [
+      "https://example.com/current",
+    ]);
+    const trappedBaseMessages = new Proxy(
+      [
+        { role: "system", content: "trapped message" },
+        { role: "system", content: "safe message" },
+      ],
+      {
+        get: (target, prop, receiver) => {
+          if (prop === "0") {
+            throw new Error("base message item trap");
+          }
+          return Reflect.get(target, prop, receiver);
+        },
+      }
+    ) as unknown as Parameters<typeof buildAgentStepMessages>[0];
+
+    const messages = await buildAgentStepMessages(
+      trappedBaseMessages,
+      [],
+      "task",
+      page,
+      {
+        elements: new Map(),
+        domState: "dom",
+        xpathMap: {},
+        backendNodeMap: {},
+      },
+      undefined,
+      []
+    );
+
+    expect(messages).toEqual(
+      expect.arrayContaining([
+        expect.objectContaining({
+          role: "system",
+          content: "safe message",
+        }),
+      ])
+    );
+    expect(messages).not.toEqual(
+      expect.arrayContaining([
+        expect.objectContaining({
+          role: "system",
+          content: "trapped message",
+        }),
+      ])
+    );
+  });
+
+  it("ignores unreadable step array entries when index getter traps", async () => {
+    const page = createFakePage("https://example.com/current", [
+      "https://example.com/current",
+    ]);
+    const trappedSteps = new Proxy([createStep(0)], {
+      get: (target, prop, receiver) => {
+        if (prop === "0") {
+          throw new Error("steps item trap");
+        }
+        return Reflect.get(target, prop, receiver);
+      },
+    });
+
+    const messages = await buildAgentStepMessages(
+      [{ role: "system", content: "system" }],
+      trappedSteps as unknown as AgentStep[],
+      "task",
+      page,
+      {
+        elements: new Map(),
+        domState: "dom",
+        xpathMap: {},
+        backendNodeMap: {},
+      },
+      undefined,
+      []
+    );
+
+    const joined = messages
+      .map((message) =>
+        typeof message.content === "string" ? message.content : ""
+      )
+      .join("\n");
+
+    expect(joined).not.toContain("=== Previous Actions ===");
+    expect(joined).not.toContain("thought-0");
+  });
+
+  it("falls back to zeroed page state when scroll info lookup fails", async () => {
+    retry.mockRejectedValue({ reason: "scroll failed" });
+    const page = createFakePage("https://example.com/current", [
+      "https://example.com/current",
+    ]);
+
+    const messages = await buildAgentStepMessages(
+      [{ role: "system", content: "system" }],
+      [],
+      "task",
+      page,
+      {
+        elements: new Map(),
+        domState: "dom",
+        xpathMap: {},
+        backendNodeMap: {},
+      },
+      "abc123",
+      []
+    );
+
+    const screenshotMessage = messages.find(
+      (message) => Array.isArray(message.content)
+    );
+    expect(screenshotMessage).toBeDefined();
+    if (!screenshotMessage || !Array.isArray(screenshotMessage.content)) {
+      return;
+    }
+
+    const textParts = screenshotMessage.content
+      .filter((part): part is { type: "text"; text: string } => part.type === "text")
+      .map((part) => part.text)
+      .join("\n");
+    expect(textParts).toContain("Pixels above: 0");
+    expect(textParts).toContain("Pixels below: 0");
+  });
+
+  it("truncates oversized serialized payloads to protect prompt budget", async () => {
+    const step = createStep(0);
+    step.actionOutput.extract = { payload: "x".repeat(5000) };
+    const page = createFakePage("https://example.com/current", [
+      "https://example.com/current",
+    ]);
+
+    const messages = await buildAgentStepMessages(
+      [{ role: "system", content: "system" }],
+      [step],
+      "task",
+      page,
+      {
+        elements: new Map(),
+        domState: "dom",
+        xpathMap: {},
+        backendNodeMap: {},
+      },
+      undefined,
+      []
+    );
+
+    const joined = messages
+      .map((message) =>
+        typeof message.content === "string" ? message.content : ""
+      )
+      .join("\n");
+
+    expect(joined).toContain("[truncated for prompt budget]");
+    expect(joined.length).toBeLessThan(6000);
+  });
+
+  it("falls back to current-tab line when open tabs cannot be listed", async () => {
+    const page = {
+      url: () => "https://example.com/current",
+      context: () => {
+        throw new Error("context unavailable");
+      },
+    } as unknown as Page;
+
+    const messages = await buildAgentStepMessages(
+      [{ role: "system", content: "system" }],
+      [],
+      "task",
+      page,
+      {
+        elements: new Map(),
+        domState: "dom",
+        xpathMap: {},
+        backendNodeMap: {},
+      },
+      undefined,
+      []
+    );
+
+    const joined = messages
+      .map((message) =>
+        typeof message.content === "string" ? message.content : ""
+      )
+      .join("\n");
+
+    expect(joined).toContain("=== Open Tabs ===");
+    expect(joined).toContain("[0] https://example.com/current (current)");
+    expect(joined).not.toContain("Open tabs unavailable");
+  });
+
+  it("falls back to current-tab line when context pages method getter traps", async () => {
+    const context = {};
+    Object.defineProperty(context, "pages", {
+      get: () => {
+        throw new Error("pages getter trap");
+      },
+      configurable: true,
+    });
+    const page = {
+      url: () => "https://example.com/current",
+      context: () => context as ReturnType<Page["context"]>,
+    } as unknown as Page;
+
+    const messages = await buildAgentStepMessages(
+      [{ role: "system", content: "system" }],
+      [],
+      "task",
+      page,
+      {
+        elements: new Map(),
+        domState: "dom",
+        xpathMap: {},
+        backendNodeMap: {},
+      },
+      undefined,
+      []
+    );
+
+    const joined = messages
+      .map((message) =>
+        typeof message.content === "string" ? message.content : ""
+      )
+      .join("\n");
+
+    expect(joined).toContain("[0] https://example.com/current (current)");
+    expect(joined).not.toContain("Open tabs unavailable");
+  });
+
+  it("falls back to placeholder text when current URL cannot be read", async () => {
+    const page = {
+      url: () => {
+        throw new Error("url unavailable");
+      },
+      context: () =>
+        ({
+          pages: () => [],
+        } as unknown as ReturnType<Page["context"]>),
+    } as unknown as Page;
+
+    const messages = await buildAgentStepMessages(
+      [{ role: "system", content: "system" }],
+      [],
+      "task",
+      page,
+      {
+        elements: new Map(),
+        domState: "dom",
+        xpathMap: {},
+        backendNodeMap: {},
+      },
+      undefined,
+      []
+    );
+
+    const joined = messages
+      .map((message) =>
+        typeof message.content === "string" ? message.content : ""
+      )
+      .join("\n");
+
+    expect(joined).toContain("=== Current URL ===");
+    expect(joined).toContain("Current URL unavailable");
+  });
+
+  it("caps open-tab listing and reports omitted tab count", async () => {
+    const urls = Array.from({ length: 25 }, (_, idx) => `https://example.com/${idx}`);
+    const page = createFakePage("https://example.com/0", urls);
+
+    const messages = await buildAgentStepMessages(
+      [{ role: "system", content: "system" }],
+      [],
+      "task",
+      page,
+      {
+        elements: new Map(),
+        domState: "dom",
+        xpathMap: {},
+        backendNodeMap: {},
+      },
+      undefined,
+      []
+    );
+
+    const joined = messages
+      .map((message) =>
+        typeof message.content === "string" ? message.content : ""
+      )
+      .join("\n");
+
+    expect(joined).toContain("[19] https://example.com/19");
+    expect(joined).toContain("... 5 more tabs omitted");
+    expect(joined).not.toContain("[20] https://example.com/20");
+  });
+
+  it("keeps open-tab summary when a tab URL lookup throws", async () => {
+    const currentTab = { url: () => "https://example.com/current" };
+    const badTab = {
+      url: () => {
+        throw new Error("tab url failure");
+      },
+    };
+    const page = {
+      url: () => "https://example.com/current",
+      context: () =>
+        ({
+          pages: () => [currentTab, badTab],
+        } as unknown as ReturnType<Page["context"]>),
+    } as unknown as Page;
+
+    const messages = await buildAgentStepMessages(
+      [{ role: "system", content: "system" }],
+      [],
+      "task",
+      page,
+      {
+        elements: new Map(),
+        domState: "dom",
+        xpathMap: {},
+        backendNodeMap: {},
+      },
+      undefined,
+      []
+    );
+
+    const joined = messages
+      .map((message) =>
+        typeof message.content === "string" ? message.content : ""
+      )
+      .join("\n");
+
+    expect(joined).toContain("[0] https://example.com/current");
+    expect(joined).toContain("[1] about:blank (url unavailable)");
+  });
+
+  it("keeps open-tab summary when a tab entry getter traps", async () => {
+    const currentTab = { url: () => "https://example.com/current" };
+    const pages = new Proxy([{}, currentTab], {
+      get: (target, prop, receiver) => {
+        if (prop === "0") {
+          throw new Error("tab entry trap");
+        }
+        return Reflect.get(target, prop, receiver);
+      },
+    });
+    const page = {
+      url: () => "https://example.com/current",
+      context: () =>
+        ({
+          pages: () => pages,
+        } as unknown as ReturnType<Page["context"]>),
+    } as unknown as Page;
+
+    const messages = await buildAgentStepMessages(
+      [{ role: "system", content: "system" }],
+      [],
+      "task",
+      page,
+      {
+        elements: new Map(),
+        domState: "dom",
+        xpathMap: {},
+        backendNodeMap: {},
+      },
+      undefined,
+      []
+    );
+
+    const joined = messages
+      .map((message) =>
+        typeof message.content === "string" ? message.content : ""
+      )
+      .join("\n");
+
+    expect(joined).toContain("[1] https://example.com/current");
+    expect(joined).toContain("... 1 more tabs omitted");
+    expect(joined).not.toContain("Open tabs unavailable");
+  });
+
+  it("falls back to current-tab line when open-tab array length getter traps", async () => {
+    const pages = new Proxy([{}], {
+      get: (target, prop, receiver) => {
+        if (prop === "length") {
+          throw new Error("tab length trap");
+        }
+        return Reflect.get(target, prop, receiver);
+      },
+    });
+    const page = {
+      url: () => "https://example.com/current",
+      context: () =>
+        ({
+          pages: () => pages,
+        } as unknown as ReturnType<Page["context"]>),
+    } as unknown as Page;
+
+    const messages = await buildAgentStepMessages(
+      [{ role: "system", content: "system" }],
+      [],
+      "task",
+      page,
+      {
+        elements: new Map(),
+        domState: "dom",
+        xpathMap: {},
+        backendNodeMap: {},
+      },
+      undefined,
+      []
+    );
+
+    const joined = messages
+      .map((message) =>
+        typeof message.content === "string" ? message.content : ""
+      )
+      .join("\n");
+
+    expect(joined).toContain("[0] https://example.com/current (current)");
+    expect(joined).not.toContain("No open tabs");
+  });
+
+  it("truncates oversized tab URLs in open-tab summary", async () => {
+    const longUrl = `https://example.com/${"x".repeat(2000)}`;
+    const page = createFakePage(longUrl, [longUrl]);
+
+    const messages = await buildAgentStepMessages(
+      [{ role: "system", content: "system" }],
+      [],
+      "task",
+      page,
+      {
+        elements: new Map(),
+        domState: "dom",
+        xpathMap: {},
+        backendNodeMap: {},
+      },
+      undefined,
+      []
+    );
+
+    const joined = messages
+      .map((message) =>
+        typeof message.content === "string" ? message.content : ""
+      )
+      .join("\n");
+    const openTabsSection = messages.find(
+      (message) =>
+        typeof message.content === "string" &&
+        message.content.includes("=== Open Tabs ===")
+    );
+    const tabLine =
+      typeof openTabsSection?.content === "string"
+        ? openTabsSection.content
+            .split("\n")
+            .find((line) => line.startsWith("[0]")) ?? ""
+        : "";
+
+    expect(joined).toContain("[tab url truncated]");
+    expect(tabLine.length).toBeLessThanOrEqual(560);
+  });
+
+  it("sanitizes control characters in current URL and open tabs", async () => {
+    const noisyUrl = "https://example.com/\u0007a\nb\tc";
+    const page = createFakePage(noisyUrl, [noisyUrl]);
+
+    const messages = await buildAgentStepMessages(
+      [{ role: "system", content: "system" }],
+      [],
+      "task",
+      page,
+      {
+        elements: new Map(),
+        domState: "dom",
+        xpathMap: {},
+        backendNodeMap: {},
+      },
+      undefined,
+      []
+    );
+
+    const joined = messages
+      .map((message) =>
+        typeof message.content === "string" ? message.content : ""
+      )
+      .join("\n");
+
+    expect(joined).toContain("https://example.com/ a b c");
+    expect(joined).not.toContain("\u0007");
+  });
+
+  it("falls back to placeholder URL when sanitized tab URL is empty", async () => {
+    const page = createFakePage("\u0007\n\t", ["\u0007\n\t"]);
+
+    const messages = await buildAgentStepMessages(
+      [{ role: "system", content: "system" }],
+      [],
+      "task",
+      page,
+      {
+        elements: new Map(),
+        domState: "dom",
+        xpathMap: {},
+        backendNodeMap: {},
+      },
+      undefined,
+      []
+    );
+
+    const joined = messages
+      .map((message) =>
+        typeof message.content === "string" ? message.content : ""
+      )
+      .join("\n");
+
+    expect(joined).toContain("about:blank (url unavailable)");
+  });
+
+  it("includes current tab in summary even when beyond tab cap", async () => {
+    const tabs = Array.from({ length: 25 }, (_, idx) => ({
+      url: () => `https://example.com/${idx}`,
+    }));
+    const currentPage = tabs[24] as {
+      url: () => string;
+      context?: () => ReturnType<Page["context"]>;
+    };
+    currentPage.context = () =>
+      ({
+        pages: () => tabs,
+      } as unknown as ReturnType<Page["context"]>);
+
+    const messages = await buildAgentStepMessages(
+      [{ role: "system", content: "system" }],
+      [],
+      "task",
+      currentPage as unknown as Page,
+      {
+        elements: new Map(),
+        domState: "dom",
+        xpathMap: {},
+        backendNodeMap: {},
+      },
+      undefined,
+      []
+    );
+
+    const joined = messages
+      .map((message) =>
+        typeof message.content === "string" ? message.content : ""
+      )
+      .join("\n");
+
+    expect(joined).toContain("[24] https://example.com/24 (current)");
+    expect(joined).toContain("... 5 more tabs omitted");
+    expect(joined).not.toContain("[19] https://example.com/19");
+  });
+
+  it("truncates oversized thought, memory, and action output messages", async () => {
+    const longText = "x".repeat(5000);
+    const step = createStep(0);
+    step.agentOutput.thoughts = longText;
+    step.agentOutput.memory = longText;
+    step.actionOutput.message = longText;
+    const page = createFakePage("https://example.com/current", [
+      "https://example.com/current",
+    ]);
+
+    const messages = await buildAgentStepMessages(
+      [{ role: "system", content: "system" }],
+      [step],
+      "task",
+      page,
+      {
+        elements: new Map(),
+        domState: "dom",
+        xpathMap: {},
+        backendNodeMap: {},
+      },
+      undefined,
+      []
+    );
+
+    const joined = messages
+      .map((message) =>
+        typeof message.content === "string" ? message.content : ""
+      )
+      .join("\n");
+
+    expect(joined).toContain("[truncated for prompt budget]");
+    expect(joined.length).toBeLessThan(9000);
+  });
+
+  it("sanitizes control characters in step and DOM prompt content", async () => {
+    const step = createStep(0);
+    step.agentOutput.thoughts = "thought\u0000with\u0007control";
+    step.agentOutput.memory = "memory\u0000with\u0007control";
+    step.actionOutput.message = "result\u0000with\u0007control";
+    const page = createFakePage("https://example.com/current", [
+      "https://example.com/current",
+    ]);
+
+    const messages = await buildAgentStepMessages(
+      [{ role: "system", content: "system" }],
+      [step],
+      "task\u0000value",
+      page,
+      {
+        elements: new Map(),
+        domState: "dom\u0000state\u0007payload",
+        xpathMap: {},
+        backendNodeMap: {},
+      },
+      undefined,
+      []
+    );
+
+    const joined = messages
+      .map((message) =>
+        typeof message.content === "string" ? message.content : ""
+      )
+      .join("\n");
+
+    expect(joined).toContain("thought with control");
+    expect(joined).toContain("memory with control");
+    expect(joined).toContain("result with control");
+    expect(joined).toContain("task value");
+    expect(joined).toContain("dom state payload");
+    expect(joined).not.toContain("\u0000");
+    expect(joined).not.toContain("\u0007");
+  });
+
+  it("truncates oversized task goal and variable descriptions", async () => {
+    const page = createFakePage("https://example.com/current", [
+      "https://example.com/current",
+    ]);
+
+    const messages = await buildAgentStepMessages(
+      [{ role: "system", content: "system" }],
+      [],
+      "g".repeat(5000),
+      page,
+      {
+        elements: new Map(),
+        domState: "dom",
+        xpathMap: {},
+        backendNodeMap: {},
+      },
+      undefined,
+      [
+        {
+          key: "token",
+          value: "abc",
+          description: "d".repeat(5000),
+        },
+      ]
+    );
+
+    const joined = messages
+      .map((message) =>
+        typeof message.content === "string" ? message.content : ""
+      )
+      .join("\n");
+
+    expect(joined).toContain("[truncated for prompt budget]");
+    expect(joined).not.toContain("g".repeat(3000));
+    expect(joined).not.toContain("d".repeat(3000));
+  });
+
+  it("falls back to readable task goal text when task input is trap-prone", async () => {
+    const page = createFakePage("https://example.com/current", [
+      "https://example.com/current",
+    ]);
+    const trappedTask = new Proxy(
+      {},
+      {
+        get: (_target, prop: string | symbol) => {
+          if (prop === "toString") {
+            throw new Error("task toString trap");
+          }
+          return undefined;
+        },
+      }
+    );
+
+    const messages = await buildAgentStepMessages(
+      [{ role: "system", content: "system" }],
+      [],
+      trappedTask as unknown as string,
+      page,
+      {
+        elements: new Map(),
+        domState: "dom",
+        xpathMap: {},
+        backendNodeMap: {},
+      },
+      undefined,
+      []
+    );
+
+    const joined = messages
+      .map((message) =>
+        typeof message.content === "string" ? message.content : ""
+      )
+      .join("\n");
+
+    expect(joined).toContain("=== Final Goal ===");
+    expect(joined).toContain("{}");
+  });
+
+  it("handles variables with throwing getters without crashing", async () => {
+    const page = createFakePage("https://example.com/current", [
+      "https://example.com/current",
+    ]);
+    const brokenVariable = new Proxy(
+      {},
+      {
+        get: (_target, prop) => {
+          if (prop === "key" || prop === "description" || prop === "value") {
+            throw new Error("variable getter trap");
+          }
+          return undefined;
+        },
+      }
+    );
+
+    const messages = await buildAgentStepMessages(
+      [{ role: "system", content: "system" }],
+      [],
+      "task",
+      page,
+      {
+        elements: new Map(),
+        domState: "dom",
+        xpathMap: {},
+        backendNodeMap: {},
+      },
+      undefined,
+      [brokenVariable as unknown as { key: string; value: string; description: string }]
+    );
+
+    const joined = messages
+      .map((message) =>
+        typeof message.content === "string" ? message.content : ""
+      )
+      .join("\n");
+
+    expect(joined).toContain("<<variable_1>>");
+    expect(joined).toContain("Variable description unavailable");
+    expect(joined).toContain("[variable value unavailable]");
+  });
+
+  it("caps variable entries for prompt budget and reports omitted count", async () => {
+    const page = createFakePage("https://example.com/current", [
+      "https://example.com/current",
+    ]);
+    const variables = Array.from({ length: 35 }, (_, index) => ({
+      key: `var_${index}`,
+      value: `value_${index}`,
+      description: `description ${index}`,
+    }));
+
+    const messages = await buildAgentStepMessages(
+      [{ role: "system", content: "system" }],
+      [],
+      "task",
+      page,
+      {
+        elements: new Map(),
+        domState: "dom",
+        xpathMap: {},
+        backendNodeMap: {},
+      },
+      undefined,
+      variables
+    );
+
+    const joined = messages
+      .map((message) =>
+        typeof message.content === "string" ? message.content : ""
+      )
+      .join("\n");
+
+    expect(joined).toContain("<<var_0>>");
+    expect(joined).toContain("<<var_24>>");
+    expect(joined).not.toContain("<<var_25>>");
+    expect(joined).toContain("... 10 more variables omitted for context budget");
+  });
+
+  it("falls back to empty variable section when array length getter traps", async () => {
+    const page = createFakePage("https://example.com/current", [
+      "https://example.com/current",
+    ]);
+    const trappedVariables = new Proxy(
+      [
+        {
+          key: "token",
+          value: "abc",
+          description: "desc",
+        },
+      ],
+      {
+        get: (target, prop, receiver) => {
+          if (prop === "length") {
+            throw new Error("length trap");
+          }
+          return Reflect.get(target, prop, receiver);
+        },
+      }
+    );
+
+    const messages = await buildAgentStepMessages(
+      [{ role: "system", content: "system" }],
+      [],
+      "task",
+      page,
+      {
+        elements: new Map(),
+        domState: "dom",
+        xpathMap: {},
+        backendNodeMap: {},
+      },
+      undefined,
+      trappedVariables as unknown as Parameters<typeof buildAgentStepMessages>[6]
+    );
+
+    const joined = messages
+      .map((message) =>
+        typeof message.content === "string" ? message.content : ""
+      )
+      .join("\n");
+
+    expect(joined).toContain("=== Variables ===");
+    expect(joined).toContain("No variables set");
+  });
+
+  it("truncates oversized DOM state payloads", async () => {
+    const page = createFakePage("https://example.com/current", [
+      "https://example.com/current",
+    ]);
+    const hugeDomState = "d".repeat(70_000);
+
+    const messages = await buildAgentStepMessages(
+      [{ role: "system", content: "system" }],
+      [],
+      "task",
+      page,
+      {
+        elements: new Map(),
+        domState: hugeDomState,
+        xpathMap: {},
+        backendNodeMap: {},
+      },
+      undefined,
+      []
+    );
+
+    const elementsMessage = messages.find(
+      (message) =>
+        typeof message.content === "string" &&
+        message.content.includes("=== Elements ===")
+    );
+
+    expect(typeof elementsMessage?.content).toBe("string");
+    const content = elementsMessage?.content as string;
+    expect(content).toContain("[DOM truncated for prompt budget]");
+    expect(content.length).toBeLessThan(51_000);
+  });
+
+  it("falls back when domState payload getter throws", async () => {
+    const page = createFakePage("https://example.com/current", [
+      "https://example.com/current",
+    ]);
+    const trappedDomState = new Proxy(
+      {
+        elements: new Map(),
+        xpathMap: {},
+        backendNodeMap: {},
+      },
+      {
+        get: (target, prop, receiver) => {
+          if (prop === "domState") {
+            throw new Error("domState getter trap");
+          }
+          return Reflect.get(target, prop, receiver);
+        },
+      }
+    );
+
+    const messages = await buildAgentStepMessages(
+      [{ role: "system", content: "system" }],
+      [],
+      "task",
+      page,
+      trappedDomState as unknown as Parameters<typeof buildAgentStepMessages>[4],
+      undefined,
+      []
+    );
+
+    const joined = messages
+      .map((message) =>
+        typeof message.content === "string" ? message.content : ""
+      )
+      .join("\n");
+
+    expect(joined).toContain("=== Elements ===");
+    expect(joined).toContain("DOM state unavailable");
+  });
+});
diff --git a/src/agent/messages/builder.ts b/src/agent/messages/builder.ts
index 852a8580..83583dd6 100644
--- a/src/agent/messages/builder.ts
+++ b/src/agent/messages/builder.ts
@@ -5,6 +5,476 @@ import { getScrollInfo } from "./utils";
 import { retry } from "@/utils/retry";
 import { A11yDOMState } from "@/context-providers/a11y-dom/types";
 import { HyperVariable } from "@/types/agent/types";
+import { formatUnknownError, normalizePageUrl } from "@/utils";
+
+const MAX_HISTORY_STEPS = 10;
+const MAX_SERIALIZED_PROMPT_VALUE_CHARS = 2000;
+const MAX_DOM_STATE_CHARS = 50_000;
+const MAX_OPEN_TAB_ENTRIES = 20;
+const MAX_TAB_URL_CHARS = 500;
+const MAX_VARIABLE_KEY_CHARS = 120;
+const MAX_VARIABLE_ITEMS = 25;
+const MAX_OMITTED_STEP_SUMMARY_STEPS = 5;
+const MAX_OMITTED_STEP_SUMMARY_CHARS = 1_500;
+const MAX_OMITTED_STEP_ACTION_CHARS = 120;
+const MAX_OMITTED_STEP_OUTCOME_CHARS = 220;
+
+function sanitizePromptText(value: string): string {
+  if (value.length === 0) {
+    return value;
+  }
+  return Array.from(value, (char) => {
+    const code = char.charCodeAt(0);
+    if (code === 9 || code === 10 || code === 13) {
+      return char;
+    }
+    return (code >= 0 && code < 32) || code === 127 ? " " : char;
+  }).join("");
+}
+
+function truncatePromptText(value: string): string {
+  const sanitized = sanitizePromptText(value);
+  if (sanitized.length <= MAX_SERIALIZED_PROMPT_VALUE_CHARS) {
+    return sanitized;
+  }
+  return (
+    sanitized.slice(0, MAX_SERIALIZED_PROMPT_VALUE_CHARS) +
+    "... [truncated for prompt budget]"
+  );
+}
+
+function truncateTabUrl(url: string): string {
+  const fallback = "about:blank (url unavailable)";
+  const normalized = normalizePageUrl(url, {
+    fallback,
+  });
+  if (normalized.length === 0) {
+    return fallback;
+  }
+  if (normalized === fallback) {
+    return fallback;
+  }
+
+  if (normalized.length <= MAX_TAB_URL_CHARS) {
+    return normalized;
+  }
+  return `${normalized.slice(0, MAX_TAB_URL_CHARS)}... [tab url truncated]`;
+}
+
+function truncateDomState(domState: string): string {
+  const sanitized = sanitizePromptText(domState);
+  if (sanitized.length <= MAX_DOM_STATE_CHARS) {
+    return sanitized;
+  }
+  return (
+    sanitized.slice(0, MAX_DOM_STATE_CHARS) +
+    "... [DOM truncated for prompt budget]"
+  );
+}
+
+function stripControlChars(value: string): string {
+  return Array.from(value)
+    .map((char) => {
+      const code = char.charCodeAt(0);
+      return (code >= 0 && code < 32) || code === 127 ? " " : char;
+    })
+    .join("");
+}
+
+function normalizeCompactStepText(
+  value: unknown,
+  fallback: string,
+  maxChars: number
+): string {
+  const rawValue = typeof value === "string" ? value : formatUnknownError(value);
+  const normalized = stripControlChars(rawValue).replace(/\s+/g, " ").trim();
+  const safeValue = normalized.length > 0 ? normalized : fallback;
+  if (safeValue.length <= maxChars) {
+    return safeValue;
+  }
+  return `${safeValue.slice(0, maxChars)}... [truncated]`;
+}
+
+function truncateOmittedSummary(value: string): string {
+  if (value.length <= MAX_OMITTED_STEP_SUMMARY_CHARS) {
+    return value;
+  }
+  const omitted = value.length - MAX_OMITTED_STEP_SUMMARY_CHARS;
+  return `${value.slice(0, MAX_OMITTED_STEP_SUMMARY_CHARS)}... [summary truncated ${omitted} chars]`;
+}
+
+function getStepIndexLabel(step: AgentStep, fallback: number): number {
+  const idx = safeReadRecordField(step, "idx");
+  if (typeof idx === "number" && Number.isFinite(idx) && idx >= 0) {
+    return Math.floor(idx);
+  }
+  return fallback;
+}
+
+function buildOmittedStepsSummary(steps: AgentStep[]): string {
+  if (steps.length === 0) {
+    return "";
+  }
+
+  const summarizedSteps = steps.slice(-MAX_OMITTED_STEP_SUMMARY_STEPS);
+  const omittedSummaryCount = steps.length - summarizedSteps.length;
+  const lines = summarizedSteps.map((step, index) => {
+    const { action, message } = getStepPromptData(step);
+    const actionType = normalizeCompactStepText(
+      safeReadRecordField(action, "type"),
+      "unknown",
+      MAX_OMITTED_STEP_ACTION_CHARS
+    );
+    const outcome = normalizeCompactStepText(
+      message,
+      "Action output unavailable",
+      MAX_OMITTED_STEP_OUTCOME_CHARS
+    );
+    const stepIndex = getStepIndexLabel(step, index);
+    return `- Step ${stepIndex}: action=${actionType}; outcome=${outcome}`;
+  });
+
+  const prefix =
+    omittedSummaryCount > 0
+      ? `(${omittedSummaryCount} earlier omitted step${omittedSummaryCount === 1 ? "" : "s"} not summarized)\n`
+      : "";
+  return truncatePromptText(truncateOmittedSummary(`${prefix}${lines.join("\n")}`));
+}
+
+function normalizeVariableKey(value: unknown, index: number): string {
+  const rawValue = typeof value === "string" ? value : formatUnknownError(value);
+  const normalized = stripControlChars(rawValue).replace(/\s+/g, " ").trim();
+  const fallback = normalized.length > 0 ? normalized : `variable_${index + 1}`;
+  if (fallback.length <= MAX_VARIABLE_KEY_CHARS) {
+    return fallback;
+  }
+  return `${fallback.slice(0, MAX_VARIABLE_KEY_CHARS)}... [variable key truncated]`;
+}
+
+function normalizeVariableDescription(value: unknown): string {
+  const rawValue = typeof value === "string" ? value : formatUnknownError(value);
+  const normalized = stripControlChars(rawValue).replace(/\s+/g, " ").trim();
+  return truncatePromptText(
+    normalized.length > 0 ? normalized : "Variable description unavailable"
+  );
+}
+
+function safeReadVariableField(
+  variable: HyperVariable,
+  field: "key" | "description" | "value"
+): unknown {
+  try {
+    return (variable as unknown as Record<string, unknown>)[field];
+  } catch {
+    if (field === "value") {
+      return "[variable value unavailable]";
+    }
+    if (field === "description") {
+      return "Variable description unavailable";
+    }
+    return "";
+  }
+}
+
+function safeReadRecordField(source: unknown, field: string): unknown {
+  if (!source || typeof source !== "object") {
+    return undefined;
+  }
+  try {
+    return (source as Record<string, unknown>)[field];
+  } catch {
+    return undefined;
+  }
+}
+
+function safeArrayLength(value: unknown): number {
+  if (!Array.isArray(value)) {
+    return 0;
+  }
+  try {
+    const length = value.length;
+    if (!Number.isFinite(length) || length < 0) {
+      return 0;
+    }
+    return Math.floor(length);
+  } catch {
+    return 0;
+  }
+}
+
+function safeReadArrayItem<T>(value: unknown, index: number): T | undefined {
+  if (!Array.isArray(value)) {
+    return undefined;
+  }
+  try {
+    return value[index] as T;
+  } catch {
+    return undefined;
+  }
+}
+
+function materializeSafeBaseMessages(
+  baseMessages: HyperAgentMessage[]
+): HyperAgentMessage[] {
+  const total = safeArrayLength(baseMessages);
+  if (total === 0) {
+    return [];
+  }
+
+  const normalizedMessages: HyperAgentMessage[] = [];
+  for (let index = 0; index < total; index += 1) {
+    const message = safeReadArrayItem<HyperAgentMessage>(baseMessages, index);
+    if (typeof message !== "undefined") {
+      normalizedMessages.push(message);
+    }
+  }
+  return normalizedMessages;
+}
+
+function getBoundedVariables(variables: HyperVariable[]): {
+  visibleVariables: HyperVariable[];
+  omittedCount: number;
+} {
+  const total = safeArrayLength(variables);
+  if (total === 0) {
+    return {
+      visibleVariables: [],
+      omittedCount: 0,
+    };
+  }
+
+  const visibleVariables: HyperVariable[] = [];
+  const maxVisible = Math.min(total, MAX_VARIABLE_ITEMS);
+  for (let index = 0; index < maxVisible; index += 1) {
+    const variable = safeReadArrayItem<HyperVariable>(variables, index);
+    if (typeof variable !== "undefined") {
+      visibleVariables.push(variable);
+    }
+  }
+
+  return {
+    visibleVariables,
+    omittedCount: Math.max(0, total - visibleVariables.length),
+  };
+}
+
+function materializeSafeSteps(steps: AgentStep[]): AgentStep[] {
+  const total = safeArrayLength(steps);
+  if (total === 0) {
+    return [];
+  }
+
+  const normalizedSteps: AgentStep[] = [];
+  for (let index = 0; index < total; index += 1) {
+    const step = safeReadArrayItem<AgentStep>(steps, index);
+    if (typeof step !== "undefined") {
+      normalizedSteps.push(step);
+    }
+  }
+  return normalizedSteps;
+}
+
+function materializeSafePages(pages: unknown): Array<{ openPage: Page; index: number }> {
+  const total = safeArrayLength(pages);
+  if (total === 0) {
+    return [];
+  }
+
+  const normalizedPages: Array<{ openPage: Page; index: number }> = [];
+  for (let index = 0; index < total; index += 1) {
+    const openPage = safeReadArrayItem<Page>(pages, index);
+    if (typeof openPage !== "undefined") {
+      normalizedPages.push({ openPage, index });
+    }
+  }
+  return normalizedPages;
+}
+
+function normalizeStepText(value: unknown, fallback: string): string {
+  if (typeof value === "string") {
+    return truncatePromptText(value);
+  }
+  if (typeof value === "undefined") {
+    return fallback;
+  }
+  return truncatePromptText(formatUnknownError(value));
+}
+
+function normalizeTaskGoal(value: unknown): string {
+  if (typeof value === "string") {
+    return truncatePromptText(value);
+  }
+  const fallback = "Task goal unavailable";
+  if (typeof value === "undefined") {
+    return fallback;
+  }
+  return truncatePromptText(formatUnknownError(value)) || fallback;
+}
+
+function buildVariablesContent(variables: HyperVariable[]): string {
+  const { visibleVariables, omittedCount } = getBoundedVariables(variables);
+  if (visibleVariables.length === 0) {
+    return "No variables set";
+  }
+
+  const variableLines = visibleVariables
+    .map((variable, index) => {
+      const key = normalizeVariableKey(safeReadVariableField(variable, "key"), index);
+      const description = normalizeVariableDescription(
+        safeReadVariableField(variable, "description")
+      );
+      const currentValue = safeSerializeForPrompt(
+        safeReadVariableField(variable, "value")
+      );
+      return `<<${key}>> - ${description} | current value: ${currentValue}`;
+    })
+    .join("\n");
+
+  if (omittedCount <= 0) {
+    return variableLines;
+  }
+  const suffix = omittedCount === 1 ? "" : "s";
+  return `${variableLines}\n... ${omittedCount} more variable${suffix} omitted for context budget`;
+}
+
+function getStepPromptData(step: AgentStep): {
+  thoughts: string;
+  memory: string;
+  action: unknown;
+  message: string;
+  extract: unknown;
+  hasExtract: boolean;
+} {
+  const agentOutput = safeReadRecordField(step, "agentOutput");
+  const actionOutput = safeReadRecordField(step, "actionOutput");
+
+  const thoughts = normalizeStepText(
+    safeReadRecordField(agentOutput, "thoughts"),
+    "Thoughts unavailable"
+  );
+  const memory = normalizeStepText(
+    safeReadRecordField(agentOutput, "memory"),
+    "Memory unavailable"
+  );
+  const action = safeReadRecordField(agentOutput, "action");
+  const message = normalizeStepText(
+    safeReadRecordField(actionOutput, "message"),
+    "Action output unavailable"
+  );
+  const extract = safeReadRecordField(actionOutput, "extract");
+
+  return {
+    thoughts,
+    memory,
+    action,
+    message,
+    extract,
+    hasExtract: typeof extract !== "undefined",
+  };
+}
+
+function getDomStateSummary(domState: A11yDOMState): string {
+  try {
+    const value = domState.domState;
+    return typeof value === "string"
+      ? value
+      : formatUnknownError(value);
+  } catch {
+    return "DOM state unavailable";
+  }
+}
+
+function safeSerializeForPrompt(value: unknown): string {
+  try {
+    const serialized = JSON.stringify(value);
+    return truncatePromptText(
+      typeof serialized === "string"
+        ? serialized
+        : formatUnknownError(value)
+    );
+  } catch {
+    return truncatePromptText(formatUnknownError(value));
+  }
+}
+
+function normalizeScrollInfo(value: unknown): [number, number] {
+  if (
+    Array.isArray(value) &&
+    value.length >= 2 &&
+    Number.isFinite(value[0]) &&
+    Number.isFinite(value[1])
+  ) {
+    return [value[0], value[1]];
+  }
+  return [0, 0];
+}
+
+function getOpenTabsSummary(page: Page): string {
+  const currentTabFallback = (() => {
+    try {
+      return `[0] ${truncateTabUrl(page.url() || "about:blank")} (current)`;
+    } catch {
+      return "[0] about:blank (url unavailable) (current)";
+    }
+  })();
+  try {
+    const context = page.context();
+    if (!context || typeof context !== "object") {
+      return currentTabFallback;
+    }
+    const pagesMethod = (context as { pages?: unknown }).pages;
+    if (typeof pagesMethod !== "function") {
+      return currentTabFallback;
+    }
+    const pages = pagesMethod.call(context) as ReturnType<
+      ReturnType<Page["context"]>["pages"]
+    >;
+    const pageEntries = materializeSafePages(pages);
+    if (pageEntries.length === 0) {
+      return currentTabFallback;
+    }
+    let visibleEntries = pageEntries.slice(0, MAX_OPEN_TAB_ENTRIES);
+    const currentEntry = pageEntries.find((entry) => entry.openPage === page);
+    if (
+      currentEntry &&
+      MAX_OPEN_TAB_ENTRIES > 0 &&
+      !visibleEntries.some((entry) => entry.openPage === page)
+    ) {
+      visibleEntries = [
+        ...pageEntries.slice(0, Math.max(0, MAX_OPEN_TAB_ENTRIES - 1)),
+        currentEntry,
+      ];
+    }
+
+    const visibleIndexSet = new Set(visibleEntries.map((entry) => entry.index));
+    const hiddenCount = Math.max(0, safeArrayLength(pages) - visibleIndexSet.size);
+    const tabLines = visibleEntries.map(({ openPage, index }) => {
+      const currentMarker = openPage === page ? " (current)" : "";
+      const tabUrl = (() => {
+        try {
+          return truncateTabUrl(openPage.url() || "about:blank");
+        } catch {
+          return "about:blank (url unavailable)";
+        }
+      })();
+      return `[${index}] ${tabUrl}${currentMarker}`;
+    });
+    if (hiddenCount > 0) {
+      tabLines.push(`... ${hiddenCount} more tabs omitted`);
+    }
+    return tabLines.join("\n");
+  } catch {
+    return currentTabFallback;
+  }
+}
+
+function getCurrentUrlSummary(page: Page): string {
+  try {
+    return truncateTabUrl(page.url() || "about:blank");
+  } catch {
+    return "Current URL unavailable";
+  }
+}
 
 export const buildAgentStepMessages = async (
   baseMessages: HyperAgentMessage[],
@@ -15,46 +485,78 @@ export const buildAgentStepMessages = async (
   screenshot: string | undefined,
   variables: HyperVariable[]
 ): Promise<HyperAgentMessage[]> => {
-  const messages = [...baseMessages];
+  const messages = materializeSafeBaseMessages(baseMessages);
+  const normalizedSteps = materializeSafeSteps(steps);
 
   // Add the final goal section
   messages.push({
     role: "user",
-    content: `=== Final Goal ===\n${task}\n`,
+    content: `=== Final Goal ===\n${normalizeTaskGoal(task)}\n`,
   });
 
   // Add current URL section
   messages.push({
     role: "user",
-    content: `=== Current URL ===\n${page.url()}\n`,
+    content: `=== Current URL ===\n${getCurrentUrlSummary(page)}\n`,
+  });
+
+  const openTabs = getOpenTabsSummary(page);
+  messages.push({
+    role: "user",
+    content: `=== Open Tabs ===\n${openTabs || "No open tabs"}\n`,
   });
 
   // Add variables section
+  const variablesContent = buildVariablesContent(variables);
   messages.push({
     role: "user",
-    content: `=== Variables ===\n${variables.map((v) => `<<${v.key}>> - ${v.description}`).join("\n")}\n`,
+    content: `=== Variables ===\n${variablesContent}\n`,
   });
 
   // Add previous actions section if there are steps
-  if (steps.length > 0) {
+  if (normalizedSteps.length > 0) {
+    const relevantSteps =
+      normalizedSteps.length > MAX_HISTORY_STEPS
+        ? normalizedSteps.slice(-MAX_HISTORY_STEPS)
+        : normalizedSteps;
+    const hiddenStepCount = normalizedSteps.length - relevantSteps.length;
+    const omittedSteps =
+      hiddenStepCount > 0 ? normalizedSteps.slice(0, hiddenStepCount) : [];
+
     messages.push({
       role: "user",
-      content: "=== Previous Actions ===\n",
+      content:
+        hiddenStepCount > 0
+          ? `=== Previous Actions ===\n(Showing latest ${relevantSteps.length} of ${normalizedSteps.length} steps; ${hiddenStepCount} older steps omitted for context budget.)\n`
+          : "=== Previous Actions ===\n",
     });
-    for (const step of steps) {
-      const { thoughts, memory, action } = step.agentOutput;
+    if (hiddenStepCount > 0) {
+      const omittedSummary = buildOmittedStepsSummary(omittedSteps);
+      if (omittedSummary.length > 0) {
+        messages.push({
+          role: "user",
+          content: `=== Earlier Actions Summary ===\n${omittedSummary}\n`,
+        });
+      }
+    }
+    for (const step of relevantSteps) {
+      const {
+        thoughts,
+        memory,
+        action,
+        message,
+        extract,
+        hasExtract,
+      } = getStepPromptData(step);
       messages.push({
         role: "assistant",
-        content: `Thoughts: ${thoughts}\nMemory: ${memory}\nAction: ${JSON.stringify(
-          action
-        )}`,
+        content: `Thoughts: ${thoughts}\nMemory: ${memory}\nAction: ${safeSerializeForPrompt(action)}`,
       });
-      const actionResult = step.actionOutput;
       messages.push({
         role: "user",
-        content: actionResult.extract
-          ? `${actionResult.message} :\n ${JSON.stringify(actionResult.extract)}`
-          : actionResult.message,
+        content: hasExtract
+          ? `${message} :\n ${safeSerializeForPrompt(extract)}`
+          : message,
       });
     }
   }
@@ -62,12 +564,14 @@ export const buildAgentStepMessages = async (
   // Add elements section with DOM tree
   messages.push({
     role: "user",
-    content: `=== Elements ===\n${domState.domState}\n`,
+    content: `=== Elements ===\n${truncateDomState(getDomStateSummary(domState))}\n`,
   });
 
   // Add page screenshot section (only if screenshot is available)
   if (screenshot) {
-    const scrollInfo = await retry({ func: () => getScrollInfo(page) });
+    const scrollInfo = await retry({ func: () => getScrollInfo(page) })
+      .then((value) => normalizeScrollInfo(value))
+      .catch(() => [0, 0] as [number, number]);
     messages.push({
       role: "user",
       content: [
diff --git a/src/agent/messages/input-format.test.ts b/src/agent/messages/input-format.test.ts
new file mode 100644
index 00000000..45b85b6a
--- /dev/null
+++ b/src/agent/messages/input-format.test.ts
@@ -0,0 +1,27 @@
+import { INPUT_FORMAT } from "@/agent/messages/input-format";
+
+describe("INPUT_FORMAT contract", () => {
+  it("lists current URL before open tabs to match runtime message order", () => {
+    const currentUrlIndex = INPUT_FORMAT.indexOf("=== Current URL ===");
+    const openTabsIndex = INPUT_FORMAT.indexOf("=== Open Tabs ===");
+
+    expect(currentUrlIndex).toBeGreaterThan(-1);
+    expect(openTabsIndex).toBeGreaterThan(-1);
+    expect(currentUrlIndex).toBeLessThan(openTabsIndex);
+  });
+
+  it("documents variable current-value payload shape", () => {
+    expect(INPUT_FORMAT).toContain(
+      "Format: <<name>> - {description} | current value: {json serialized value}"
+    );
+  });
+
+  it("documents page state in the same order emitted by runtime", () => {
+    const aboveIndex = INPUT_FORMAT.indexOf("- Pixels above:");
+    const belowIndex = INPUT_FORMAT.indexOf("- Pixels below:");
+
+    expect(aboveIndex).toBeGreaterThan(-1);
+    expect(belowIndex).toBeGreaterThan(-1);
+    expect(aboveIndex).toBeLessThan(belowIndex);
+  });
+});
diff --git a/src/agent/messages/input-format.ts b/src/agent/messages/input-format.ts
index d168d424..93a4cb1e 100644
--- a/src/agent/messages/input-format.ts
+++ b/src/agent/messages/input-format.ts
@@ -1,15 +1,15 @@
 export const INPUT_FORMAT = `=== Final Goal ===
 [The final goal that needs to be accomplished]
-=== Open Tabs ===
-[The open tabs]
 === Current URL ===
 [The current URL]
+=== Open Tabs ===
+[The open tabs]
 === Variables ===
 [Variables that can be used in the task]
 - Variables are referenced using <<name>> syntax
 - Each variable has a name and description
 - Variables persist across actions and can be referenced in subsequent steps
-- Format: <<name>> - {description}
+- Format: <<name>> - {description} | current value: {json serialized value}
 === Elements ===
 [A list of the elements on the page in the following format]
 [encodedId] type: name attributes
@@ -29,5 +29,5 @@ export const INPUT_FORMAT = `=== Final Goal ===
 - A screenshot of the current page
 - In visual-debug mode, interactive elements are highlighted with their encodedId
 === Page State === (only in visual modes)
-- Pixels below: Number of pixels scrolled below current viewport
-- Pixels above: Number of pixels scrolled above current viewport`;
+- Pixels above: Number of pixels scrolled above current viewport
+- Pixels below: Number of pixels scrolled below current viewport`;
diff --git a/src/agent/messages/output-format.test.ts b/src/agent/messages/output-format.test.ts
new file mode 100644
index 00000000..c5d9fe3d
--- /dev/null
+++ b/src/agent/messages/output-format.test.ts
@@ -0,0 +1,15 @@
+import { OUTPUT_FORMAT } from "@/agent/messages/output-format";
+import { AGENT_ELEMENT_ACTIONS } from "@/agent/shared/action-restrictions";
+
+describe("OUTPUT_FORMAT action contract", () => {
+  it("lists every supported actElement method", () => {
+    for (const method of AGENT_ELEMENT_ACTIONS) {
+      expect(OUTPUT_FORMAT).toContain(method);
+    }
+  });
+
+  it("does not mention legacy select method alias", () => {
+    expect(OUTPUT_FORMAT).not.toContain("click, fill, type, press, select,");
+    expect(OUTPUT_FORMAT).toContain("selectOptionFromDropdown");
+  });
+});
diff --git a/src/agent/messages/output-format.ts b/src/agent/messages/output-format.ts
index 2dc6f891..1c395215 100644
--- a/src/agent/messages/output-format.ts
+++ b/src/agent/messages/output-format.ts
@@ -1,3 +1,7 @@
+import { AGENT_ELEMENT_ACTIONS } from "@/agent/shared/action-restrictions";
+
+const SUPPORTED_METHODS_TEXT = AGENT_ELEMENT_ACTIONS.join(", ");
+
 export const OUTPUT_FORMAT = `Your response MUST be in this exact format:
 {
   "thoughts": "Your reasoning about the current state and what needs to be done next based on the task goal and previous actions",
@@ -13,6 +17,6 @@ export const OUTPUT_FORMAT = `Your response MUST be in this exact format:
 For actElement:
 - params.instruction -> short explanation of why the action is needed
 - params.elementId -> encoded ID from the DOM listing (e.g., "0-5125")
-- params.method -> one of click, fill, type, press, selectOptionFromDropdown, check, uncheck, hover, scrollToElement, scrollToPercentage, nextChunk, prevChunk
+- params.method -> one of ${SUPPORTED_METHODS_TEXT}
 - params.arguments -> array of arguments for the method (use [] when none are needed)
 - params.confidence -> number between 0 and 1`;
diff --git a/src/agent/messages/system-prompt.test.ts b/src/agent/messages/system-prompt.test.ts
new file mode 100644
index 00000000..696f8911
--- /dev/null
+++ b/src/agent/messages/system-prompt.test.ts
@@ -0,0 +1,27 @@
+import { SYSTEM_PROMPT } from "@/agent/messages/system-prompt";
+import { AGENT_ELEMENT_ACTIONS } from "@/agent/shared/action-restrictions";
+
+describe("SYSTEM_PROMPT action contract", () => {
+  it("does not advertise disabled navigation actions", () => {
+    expect(SYSTEM_PROMPT).not.toContain("pageBack");
+    expect(SYSTEM_PROMPT).not.toContain("pageForward");
+  });
+
+  it("uses the canonical chunk scrolling method names", () => {
+    expect(SYSTEM_PROMPT).toContain("nextChunk");
+    expect(SYSTEM_PROMPT).toContain("prevChunk");
+    expect(SYSTEM_PROMPT).not.toContain("scrollNextChunk");
+    expect(SYSTEM_PROMPT).not.toContain("scrollPrevChunk");
+  });
+
+  it("references canonical selectOptionFromDropdown interaction name", () => {
+    expect(SYSTEM_PROMPT).toContain("selectOptionFromDropdown");
+    expect(SYSTEM_PROMPT).not.toContain("click, fill, type, press, select,");
+  });
+
+  it("stays aligned with supported element action methods", () => {
+    for (const method of AGENT_ELEMENT_ACTIONS) {
+      expect(SYSTEM_PROMPT).toContain(method);
+    }
+  });
+});
diff --git a/src/agent/messages/system-prompt.ts b/src/agent/messages/system-prompt.ts
index e236199b..86f1781c 100644
--- a/src/agent/messages/system-prompt.ts
+++ b/src/agent/messages/system-prompt.ts
@@ -1,6 +1,7 @@
 import { INPUT_FORMAT } from "./input-format";
 import { OUTPUT_FORMAT } from "./output-format";
 import { EXAMPLE_ACTIONS } from "./examples-actions";
+import { AGENT_ELEMENT_ACTIONS } from "@/agent/shared/action-restrictions";
 
 const DATE_STRING = new Date().toLocaleString(undefined, {
   year: "numeric",
@@ -8,6 +9,15 @@ const DATE_STRING = new Date().toLocaleString(undefined, {
   day: "2-digit",
   weekday: "long",
 });
+const SCROLL_ACTION_SET = new Set([
+  "scrollToElement",
+  "scrollToPercentage",
+  "nextChunk",
+  "prevChunk",
+]);
+const SUPPORTED_INTERACTION_METHODS = AGENT_ELEMENT_ACTIONS.filter(
+  (method) => !SCROLL_ACTION_SET.has(method)
+).join(", ");
 
 export const SYSTEM_PROMPT = `You are a web automation assistant that helps users complete tasks on websites.
 
@@ -26,14 +36,12 @@ ${OUTPUT_FORMAT}
 
 ## Navigation
 - goToUrl: Navigate to a specific URL
-- pageBack: Go back one page
-- pageForward: Go forward one page
 - refreshPage: Refresh current page
 
 ## Element Interaction
 - actElement: Perform action on element using natural language
-  * Supported interactions: click, fill, type, press, select, check, uncheck, hover
-  * Scrolling: scrollToElement (scroll the chosen element into view), scrollToPercentage (scroll the page/container to a %), scrollNextChunk (scroll down one viewport), scrollPrevChunk (scroll up one viewport)
+  * Supported interactions: ${SUPPORTED_INTERACTION_METHODS}
+  * Scrolling: scrollToElement (scroll the chosen element into view), scrollToPercentage (scroll the page/container to a %), nextChunk (scroll down one viewport), prevChunk (scroll up one viewport)
   * Be specific: mention element type and identifying text
   * Examples: "click the Login button", "fill 'text' into search box", "scroll to the pricing section", "scroll to 50% of the page", "scroll down one page"
 
diff --git a/src/agent/shared/action-cache-exec.test.ts b/src/agent/shared/action-cache-exec.test.ts
new file mode 100644
index 00000000..d770b77d
--- /dev/null
+++ b/src/agent/shared/action-cache-exec.test.ts
@@ -0,0 +1,419 @@
+import {
+  attachCachedActionHelpers,
+  dispatchPerformHelper,
+  isPageActionMethod,
+  normalizePageActionMethod,
+} from "@/agent/shared/action-cache-exec";
+import type { AgentDeps, HyperPage, PerformOptions } from "@/types/agent/types";
+import type { HyperAgentLLM } from "@/llm/types";
+
+jest.mock("@/agent/shared/run-cached-action", () => ({
+  runCachedStep: jest.fn().mockResolvedValue({
+    taskId: "task-id",
+    status: "completed",
+    steps: [],
+    output: "ok",
+  }),
+}));
+
+const { runCachedStep } = jest.requireMock("@/agent/shared/run-cached-action") as {
+  runCachedStep: jest.Mock;
+};
+
+function createMockHyperPage(): HyperPage {
+  const ok = Promise.resolve({
+    taskId: "task-id",
+    status: "completed",
+    steps: [],
+    output: "ok",
+  });
+  return {
+    performClick: jest.fn().mockReturnValue(ok),
+    performHover: jest.fn().mockReturnValue(ok),
+    performType: jest.fn().mockReturnValue(ok),
+    performFill: jest.fn().mockReturnValue(ok),
+    performPress: jest.fn().mockReturnValue(ok),
+    performSelectOption: jest.fn().mockReturnValue(ok),
+    performCheck: jest.fn().mockReturnValue(ok),
+    performUncheck: jest.fn().mockReturnValue(ok),
+    performScrollToElement: jest.fn().mockReturnValue(ok),
+    performScrollToPercentage: jest.fn().mockReturnValue(ok),
+    performNextChunk: jest.fn().mockReturnValue(ok),
+    performPrevChunk: jest.fn().mockReturnValue(ok),
+  } as unknown as HyperPage;
+}
+
+function createMockLLM(): HyperAgentLLM {
+  return {
+    invoke: async () => ({ role: "assistant", content: "ok" }),
+    invokeStructured: async () => ({ rawText: "{}", parsed: null }),
+    getProviderId: () => "mock",
+    getModelId: () => "mock-model",
+    getCapabilities: () => ({
+      multimodal: false,
+      toolCalling: true,
+      jsonMode: true,
+    }),
+  };
+}
+
+describe("action-cache perform helper dispatch", () => {
+  beforeEach(() => {
+    jest.clearAllMocks();
+  });
+
+  it("validates known page action methods", () => {
+    expect(isPageActionMethod("click")).toBe(true);
+    expect(isPageActionMethod("not-a-method")).toBe(false);
+  });
+
+  it("normalizes page action methods case-insensitively", () => {
+    expect(normalizePageActionMethod(" CLICK ")).toBe("click");
+    expect(normalizePageActionMethod("SelectOptionFromDropdown")).toBe(
+      "selectOptionFromDropdown"
+    );
+    expect(normalizePageActionMethod("unknown")).toBeNull();
+  });
+
+  it("dispatches fill with value argument", async () => {
+    const page = createMockHyperPage();
+    const options = { maxSteps: 2 };
+
+    await dispatchPerformHelper(page, "fill", "//input[1]", "hello", options);
+
+    expect(page.performFill).toHaveBeenCalledWith("//input[1]", "hello", {
+      maxSteps: 2,
+    });
+  });
+
+  it("dispatches click without value argument", async () => {
+    const page = createMockHyperPage();
+    const options = { maxSteps: 1 };
+
+    await dispatchPerformHelper(page, "click", "//button[1]", undefined, options);
+
+    expect(page.performClick).toHaveBeenCalledWith("//button[1]", {
+      maxSteps: 1,
+    });
+  });
+
+  it("trims whitespace performInstruction when attaching helpers", async () => {
+    const agentDeps: AgentDeps = {
+      llm: createMockLLM(),
+      debug: false,
+      tokenLimit: 1000,
+      variables: [],
+      cdpActionsEnabled: false,
+    };
+    const page = createMockHyperPage();
+    attachCachedActionHelpers(agentDeps, page);
+
+    await page.performClick("//button[1]", {
+      performInstruction: "   ",
+    });
+
+    expect(runCachedStep).toHaveBeenCalledWith(
+      expect.objectContaining({
+        instruction: "Click element",
+      })
+    );
+  });
+
+  it("throws readable error when helper access traps throw", async () => {
+    const page = new Proxy(
+      {},
+      {
+        get: (_target, prop) => {
+          if (prop === "performClick") {
+            throw new Error("helper getter trap");
+          }
+          return undefined;
+        },
+      }
+    ) as unknown as HyperPage;
+
+    await expect(
+      dispatchPerformHelper(page, "click", "//button[1]", undefined, {})
+    ).rejects.toThrow(
+      "[Replay] Failed to access performClick: helper getter trap"
+    );
+  });
+
+  it("truncates oversized helper access diagnostics", async () => {
+    const page = new Proxy(
+      {},
+      {
+        get: (_target, prop) => {
+          if (prop === "performClick") {
+            throw new Error(`x${"y".repeat(2_000)}\nhelper getter trap`);
+          }
+          return undefined;
+        },
+      }
+    ) as unknown as HyperPage;
+
+    await expect(
+      dispatchPerformHelper(page, "click", "//button[1]", undefined, {})
+    ).rejects.toThrow(/\[truncated/);
+  });
+
+  it("throws readable error when helper method is missing", async () => {
+    const page = {} as unknown as HyperPage;
+
+    await expect(
+      dispatchPerformHelper(page, "click", "//button[1]", undefined, {})
+    ).rejects.toThrow("[Replay] Missing perform helper: performClick");
+  });
+
+  it("truncates oversized helper pre-execution diagnostics", async () => {
+    const page = {
+      performClick: (): never => {
+        throw new Error(`x${"y".repeat(2_000)}\nhelper execution trap`);
+      },
+    } as unknown as HyperPage;
+
+    await expect(
+      dispatchPerformHelper(page, "click", "//button[1]", undefined, {})
+    ).rejects.toThrow(/\[truncated/);
+  });
+
+  it("normalizes trap-prone options and large args when attaching helpers", async () => {
+    const agentDeps: AgentDeps = {
+      llm: createMockLLM(),
+      debug: false,
+      tokenLimit: 1000,
+      variables: [],
+      cdpActionsEnabled: false,
+    };
+    const page = createMockHyperPage();
+    attachCachedActionHelpers(agentDeps, page);
+    const trappedOptions = new Proxy(
+      {},
+      {
+        get: (_target, prop) => {
+          if (
+            prop === "performInstruction" ||
+            prop === "maxSteps" ||
+            prop === "frameIndex"
+          ) {
+            throw new Error("options trap");
+          }
+          return undefined;
+        },
+      }
+    );
+    const huge = "x".repeat(25_000);
+
+    await page.performType("//input[1]", huge, trappedOptions as never);
+
+    expect(runCachedStep).toHaveBeenCalledWith(
+      expect.objectContaining({
+        instruction: "Type text",
+        maxSteps: 3,
+        cachedAction: expect.objectContaining({
+          frameIndex: 0,
+          arguments: [expect.stringMatching(/^x+$/)],
+        }),
+      })
+    );
+    const cachedAction = (
+      runCachedStep.mock.calls[0]?.[0] as {
+        cachedAction?: { arguments?: string[] };
+      }
+    ).cachedAction;
+    expect(cachedAction?.arguments?.[0]?.length).toBe(20_000);
+  });
+
+  it("caps oversized maxSteps passed to attached perform helpers", async () => {
+    const agentDeps: AgentDeps = {
+      llm: createMockLLM(),
+      debug: false,
+      tokenLimit: 1000,
+      variables: [],
+      cdpActionsEnabled: false,
+    };
+    const page = createMockHyperPage();
+    attachCachedActionHelpers(agentDeps, page);
+
+    await page.performClick("//button[1]", {
+      maxSteps: 999,
+    });
+
+    expect(runCachedStep).toHaveBeenCalledWith(
+      expect.objectContaining({
+        maxSteps: 20,
+      })
+    );
+  });
+
+  it("caps oversized frameIndex passed to attached perform helpers", async () => {
+    const agentDeps: AgentDeps = {
+      llm: createMockLLM(),
+      debug: false,
+      tokenLimit: 1000,
+      variables: [],
+      cdpActionsEnabled: false,
+    };
+    const page = createMockHyperPage();
+    attachCachedActionHelpers(agentDeps, page);
+
+    await page.performClick("//button[1]", {
+      frameIndex: 50_000,
+      maxSteps: 2,
+    });
+
+    expect(runCachedStep).toHaveBeenCalledWith(
+      expect.objectContaining({
+        cachedAction: expect.objectContaining({
+          frameIndex: 1_000,
+        }),
+      })
+    );
+  });
+
+  it("sanitizes control characters in perform options and text arguments", async () => {
+    const agentDeps: AgentDeps = {
+      llm: createMockLLM(),
+      debug: false,
+      tokenLimit: 1000,
+      variables: [],
+      cdpActionsEnabled: false,
+    };
+    const page = createMockHyperPage();
+    attachCachedActionHelpers(agentDeps, page);
+
+    await page.performType("//input[\u0000 1]", "ab\u0000\ncd", {
+      performInstruction: "  custom\u0000\n instruction  ",
+      maxSteps: 2,
+    });
+
+    expect(runCachedStep).toHaveBeenCalledWith(
+      expect.objectContaining({
+        instruction: "custom instruction",
+        cachedAction: expect.objectContaining({
+          xpath: expect.stringContaining("//input["),
+          arguments: ["ab  cd"],
+        }),
+      })
+    );
+    const cachedAction = (
+      runCachedStep.mock.calls[0]?.[0] as {
+        cachedAction?: { xpath?: string };
+      }
+    ).cachedAction;
+    expect(cachedAction?.xpath).not.toContain("\u0000");
+  });
+
+  it("forwards filterAdTrackingFrames override from helper options", async () => {
+    const agentDeps: AgentDeps = {
+      llm: createMockLLM(),
+      debug: false,
+      tokenLimit: 1000,
+      variables: [],
+      cdpActionsEnabled: false,
+      filterAdTrackingFrames: true,
+    };
+    const page = createMockHyperPage();
+    attachCachedActionHelpers(agentDeps, page);
+
+    await page.performClick("//button[1]", {
+      filterAdTrackingFrames: false,
+    });
+
+    expect(runCachedStep).toHaveBeenCalledWith(
+      expect.objectContaining({
+        filterAdTrackingFrames: false,
+      })
+    );
+  });
+
+  it("forwards cdpActions override from helper options", async () => {
+    const agentDeps: AgentDeps = {
+      llm: createMockLLM(),
+      debug: false,
+      tokenLimit: 1000,
+      variables: [],
+      cdpActionsEnabled: false,
+      filterAdTrackingFrames: true,
+    };
+    const page = createMockHyperPage();
+    attachCachedActionHelpers(agentDeps, page);
+
+    await page.performClick("//button[1]", {
+      cdpActions: true,
+    });
+
+    expect(runCachedStep).toHaveBeenCalledWith(
+      expect.objectContaining({
+        cdpActionsEnabled: true,
+      })
+    );
+  });
+
+  it("falls back to agent defaults when helper options getters trap", async () => {
+    const agentDeps: AgentDeps = {
+      llm: createMockLLM(),
+      debug: false,
+      tokenLimit: 1000,
+      variables: [],
+      cdpActionsEnabled: false,
+      filterAdTrackingFrames: false,
+    };
+    const page = createMockHyperPage();
+    attachCachedActionHelpers(agentDeps, page);
+
+    const trappedOptions = new Proxy(
+      {},
+      {
+        get: (_target, prop: string | symbol) => {
+          if (prop === "cdpActions" || prop === "filterAdTrackingFrames") {
+            throw new Error("helper option trap");
+          }
+          return undefined;
+        },
+      }
+    ) as PerformOptions;
+
+    await page.performClick("//button[1]", trappedOptions);
+
+    expect(runCachedStep).toHaveBeenCalledWith(
+      expect.objectContaining({
+        cdpActionsEnabled: false,
+        filterAdTrackingFrames: false,
+      })
+    );
+  });
+
+  it("uses default maxSteps when helper options maxSteps getter traps", async () => {
+    const agentDeps: AgentDeps = {
+      llm: createMockLLM(),
+      debug: false,
+      tokenLimit: 1000,
+      variables: [],
+      cdpActionsEnabled: false,
+      filterAdTrackingFrames: true,
+    };
+    const page = createMockHyperPage();
+    attachCachedActionHelpers(agentDeps, page);
+
+    const trappedOptions = new Proxy(
+      {},
+      {
+        get: (_target, prop: string | symbol) => {
+          if (prop === "maxSteps") {
+            throw new Error("maxSteps trap");
+          }
+          return undefined;
+        },
+      }
+    ) as PerformOptions;
+
+    await page.performClick("//button[1]", trappedOptions);
+
+    expect(runCachedStep).toHaveBeenCalledWith(
+      expect.objectContaining({
+        maxSteps: 3,
+      })
+    );
+  });
+});
diff --git a/src/agent/shared/action-cache-exec.ts b/src/agent/shared/action-cache-exec.ts
index d8b49efb..2baf08b8 100644
--- a/src/agent/shared/action-cache-exec.ts
+++ b/src/agent/shared/action-cache-exec.ts
@@ -1,26 +1,225 @@
-import { AgentDeps, HyperPage, TaskOutput } from "@/types/agent/types";
+import {
+  AgentDeps,
+  HyperPage,
+  PerformOptions,
+  TaskOutput,
+} from "@/types/agent/types";
 import * as cachedRunner from "./run-cached-action";
+import { formatUnknownError } from "@/utils";
 
 const DEFAULT_MAX_STEPS = 3;
+const MAX_PERFORM_MAX_STEPS = 20;
+const MAX_PERFORM_FRAME_INDEX = 1_000;
+const MAX_PERFORM_VALUE_CHARS = 20_000;
+const MAX_PERFORM_HELPER_DIAGNOSTIC_CHARS = 400;
 
-type PageAction =
-  | "click"
-  | "fill"
-  | "type"
-  | "press"
-  | "selectOptionFromDropdown"
-  | "check"
-  | "uncheck"
-  | "hover"
-  | "scrollToElement"
-  | "scrollToPercentage"
-  | "nextChunk"
-  | "prevChunk";
-
-interface PerformOptions {
-  frameIndex?: number | null;
-  performInstruction?: string | null;
-  maxSteps?: number;
+export const PAGE_ACTION_METHODS = [
+  "click",
+  "fill",
+  "type",
+  "press",
+  "selectOptionFromDropdown",
+  "check",
+  "uncheck",
+  "hover",
+  "scrollToElement",
+  "scrollToPercentage",
+  "nextChunk",
+  "prevChunk",
+] as const;
+
+const pageActionMethodSet: ReadonlySet<string> = new Set(PAGE_ACTION_METHODS);
+const pageActionMethodMap: ReadonlyMap<string, PageAction> = new Map(
+  PAGE_ACTION_METHODS.map((method) => [method.toLowerCase(), method])
+);
+
+export type PageAction = (typeof PAGE_ACTION_METHODS)[number];
+
+export function normalizePageActionMethod(
+  method: string | null | undefined
+): PageAction | null {
+  const normalizedMethod = method?.trim().toLowerCase();
+  if (!normalizedMethod) {
+    return null;
+  }
+  return pageActionMethodMap.get(normalizedMethod) ?? null;
+}
+
+export function isPageActionMethod(method: string): method is PageAction {
+  return pageActionMethodSet.has(method);
+}
+
+export function dispatchPerformHelper(
+  hp: HyperPage,
+  method: PageAction,
+  xpath: string,
+  value: string | undefined,
+  options: PerformOptions
+): Promise<TaskOutput> {
+  const formatPerformHelperDiagnostic = (error: unknown): string => {
+    const normalized = Array.from(formatUnknownError(error), (char) => {
+      const code = char.charCodeAt(0);
+      return (code >= 0 && code < 32) || code === 127 ? " " : char;
+    })
+      .join("")
+      .replace(/\s+/g, " ")
+      .trim();
+    const fallback = normalized.length > 0 ? normalized : "unknown error";
+    if (fallback.length <= MAX_PERFORM_HELPER_DIAGNOSTIC_CHARS) {
+      return fallback;
+    }
+    const omitted = fallback.length - MAX_PERFORM_HELPER_DIAGNOSTIC_CHARS;
+    return `${fallback.slice(
+      0,
+      MAX_PERFORM_HELPER_DIAGNOSTIC_CHARS
+    )}... [truncated ${omitted} chars]`;
+  };
+
+  const invoke = (
+    helperName: string,
+    helperArgs: unknown[]
+  ): Promise<TaskOutput> => {
+    let helper: unknown;
+    try {
+      helper = (hp as unknown as Record<string, unknown>)[helperName];
+    } catch (error) {
+      return Promise.reject(
+        new Error(
+          `[Replay] Failed to access ${helperName}: ${formatPerformHelperDiagnostic(
+            error
+          )}`
+        )
+      );
+    }
+    if (typeof helper !== "function") {
+      return Promise.reject(new Error(`[Replay] Missing perform helper: ${helperName}`));
+    }
+    try {
+      return helper(...helperArgs) as Promise<TaskOutput>;
+    } catch (error) {
+      return Promise.reject(
+        new Error(
+          `[Replay] ${helperName} failed before execution: ${formatPerformHelperDiagnostic(
+            error
+          )}`
+        )
+      );
+    }
+  };
+
+  switch (method) {
+    case "click":
+      return invoke("performClick", [xpath, options]);
+    case "hover":
+      return invoke("performHover", [xpath, options]);
+    case "type":
+      return invoke("performType", [xpath, value ?? "", options]);
+    case "fill":
+      return invoke("performFill", [xpath, value ?? "", options]);
+    case "press":
+      return invoke("performPress", [xpath, value ?? "", options]);
+    case "selectOptionFromDropdown":
+      return invoke("performSelectOption", [xpath, value ?? "", options]);
+    case "check":
+      return invoke("performCheck", [xpath, options]);
+    case "uncheck":
+      return invoke("performUncheck", [xpath, options]);
+    case "scrollToElement":
+      return invoke("performScrollToElement", [xpath, options]);
+    case "scrollToPercentage":
+      return invoke("performScrollToPercentage", [xpath, value ?? "", options]);
+    case "nextChunk":
+      return invoke("performNextChunk", [xpath, options]);
+    case "prevChunk":
+      return invoke("performPrevChunk", [xpath, options]);
+    default:
+      throw new Error(`Unknown perform helper method: ${method}`);
+  }
+}
+
+function safeReadOptionField(
+  options: PerformOptions | undefined,
+  key: keyof PerformOptions
+): unknown {
+  if (!options || typeof options !== "object") {
+    return undefined;
+  }
+  try {
+    return (options as unknown as Record<string, unknown>)[key];
+  } catch {
+    return undefined;
+  }
+}
+
+function normalizeInstruction(value: unknown, fallback: string): string {
+  if (typeof value !== "string") {
+    return fallback;
+  }
+  const normalized = Array.from(value, (char) => {
+    const code = char.charCodeAt(0);
+    return (code >= 0 && code < 32) || code === 127 ? " " : char;
+  })
+    .join("")
+    .replace(/\s+/g, " ")
+    .trim();
+  return normalized.length > 0 ? normalized : fallback;
+}
+
+function normalizeOptionalTextArg(value: string | number): string | number {
+  if (typeof value !== "string") {
+    return value;
+  }
+  const normalized = Array.from(value, (char) => {
+    const code = char.charCodeAt(0);
+    return (code >= 0 && code < 32) || code === 127 ? " " : char;
+  }).join("");
+  if (normalized.length <= MAX_PERFORM_VALUE_CHARS) {
+    return normalized;
+  }
+  return normalized.slice(0, MAX_PERFORM_VALUE_CHARS);
+}
+
+function normalizeMaxSteps(value: unknown): number {
+  if (typeof value !== "number" || !Number.isFinite(value) || value <= 0) {
+    return DEFAULT_MAX_STEPS;
+  }
+  return Math.min(Math.floor(value), MAX_PERFORM_MAX_STEPS);
+}
+
+function normalizeFrameIndex(value: unknown): number | null {
+  if (typeof value !== "number" || !Number.isFinite(value)) {
+    return null;
+  }
+  if (value < 0) {
+    return null;
+  }
+  return Math.min(Math.floor(value), MAX_PERFORM_FRAME_INDEX);
+}
+
+function normalizeFilterAdTrackingFrames(
+  value: unknown,
+  fallback: boolean | undefined
+): boolean | undefined {
+  if (typeof value === "boolean") {
+    return value;
+  }
+  if (typeof fallback === "boolean") {
+    return fallback;
+  }
+  return undefined;
+}
+
+function normalizeCdpActions(
+  value: unknown,
+  fallback: boolean | undefined
+): boolean | undefined {
+  if (typeof value === "boolean") {
+    return value;
+  }
+  if (typeof fallback === "boolean") {
+    return fallback;
+  }
+  return undefined;
 }
 
 function runCachedAction(
@@ -32,32 +231,61 @@ function runCachedAction(
   args: Array<string | number>,
   options?: PerformOptions
 ): Promise<TaskOutput> {
+  const normalizedDefaultInstruction = normalizeInstruction(
+    instruction,
+    "Execute cached action"
+  );
+  const normalizedPerformInstruction = normalizeInstruction(
+    safeReadOptionField(options, "performInstruction"),
+    ""
+  );
   const runInstruction =
-    options?.performInstruction && options.performInstruction.length > 0
-      ? options.performInstruction
-      : instruction;
+    normalizedPerformInstruction.length > 0
+      ? normalizedPerformInstruction
+      : normalizedDefaultInstruction;
+  const normalizedXPath = normalizeInstruction(xpath, "//");
+  const normalizedArgs = args.map(normalizeOptionalTextArg);
+  const normalizedFrameIndex = normalizeFrameIndex(
+    safeReadOptionField(options, "frameIndex")
+  );
+  const normalizedFilterAdTrackingFrames = normalizeFilterAdTrackingFrames(
+    safeReadOptionField(options, "filterAdTrackingFrames"),
+    agent.filterAdTrackingFrames
+  );
+  const normalizedCdpActions = normalizeCdpActions(
+    safeReadOptionField(options, "cdpActions"),
+    agent.cdpActionsEnabled
+  );
+  const normalizedMaxSteps = normalizeMaxSteps(
+    safeReadOptionField(options, "maxSteps")
+  );
   const cachedAction = {
     actionType: "actElement",
     method,
-    arguments: args,
-    frameIndex: options?.frameIndex ?? 0,
-    xpath,
+    arguments: normalizedArgs,
+    frameIndex: normalizedFrameIndex ?? 0,
+    xpath: normalizedXPath,
   };
 
   return cachedRunner.runCachedStep({
     page,
     instruction: runInstruction,
     cachedAction,
-    maxSteps: options?.maxSteps ?? DEFAULT_MAX_STEPS,
+    maxSteps: normalizedMaxSteps,
     debug: agent.debug,
     tokenLimit: agent.tokenLimit,
     llm: agent.llm,
     mcpClient: agent.mcpClient,
     variables: agent.variables ?? [],
     preferScriptBoundingBox: agent.debug,
-    cdpActionsEnabled: agent.cdpActionsEnabled,
-    performFallback: options?.performInstruction
-      ? (instr) => page.perform(instr)
+    cdpActionsEnabled: normalizedCdpActions,
+    filterAdTrackingFrames: normalizedFilterAdTrackingFrames,
+    performFallback: normalizedPerformInstruction
+      ? (instr) =>
+          page.perform(instr, {
+            cdpActions: normalizedCdpActions,
+            filterAdTrackingFrames: normalizedFilterAdTrackingFrames,
+          })
       : undefined,
   });
 }
@@ -70,7 +298,7 @@ export function attachCachedActionHelpers(
     runCachedAction(
       agent,
       page,
-      options?.performInstruction || "Click element",
+      "Click element",
       "click",
       xpath,
       [],
@@ -81,7 +309,7 @@ export function attachCachedActionHelpers(
     runCachedAction(
       agent,
       page,
-      options?.performInstruction || "Hover element",
+      "Hover element",
       "hover",
       xpath,
       [],
@@ -92,7 +320,7 @@ export function attachCachedActionHelpers(
     runCachedAction(
       agent,
       page,
-      options?.performInstruction || "Type text",
+      "Type text",
       "type",
       xpath,
       [text],
@@ -103,7 +331,7 @@ export function attachCachedActionHelpers(
     runCachedAction(
       agent,
       page,
-      options?.performInstruction || "Fill input",
+      "Fill input",
       "fill",
       xpath,
       [text],
@@ -114,7 +342,7 @@ export function attachCachedActionHelpers(
     runCachedAction(
       agent,
       page,
-      options?.performInstruction || "Press key",
+      "Press key",
       "press",
       xpath,
       [key],
@@ -129,7 +357,7 @@ export function attachCachedActionHelpers(
     runCachedAction(
       agent,
       page,
-      options?.performInstruction || "Select option",
+      "Select option",
       "selectOptionFromDropdown",
       xpath,
       [option],
@@ -140,7 +368,7 @@ export function attachCachedActionHelpers(
     runCachedAction(
       agent,
       page,
-      options?.performInstruction || "Check element",
+      "Check element",
       "check",
       xpath,
       [],
@@ -151,7 +379,7 @@ export function attachCachedActionHelpers(
     runCachedAction(
       agent,
       page,
-      options?.performInstruction || "Uncheck element",
+      "Uncheck element",
       "uncheck",
       xpath,
       [],
@@ -162,7 +390,7 @@ export function attachCachedActionHelpers(
     runCachedAction(
       agent,
       page,
-      options?.performInstruction || "Scroll to element",
+      "Scroll to element",
       "scrollToElement",
       xpath,
       [],
@@ -177,7 +405,7 @@ export function attachCachedActionHelpers(
     runCachedAction(
       agent,
       page,
-      options?.performInstruction || "Scroll to percentage",
+      "Scroll to percentage",
       "scrollToPercentage",
       xpath,
       [position],
@@ -188,7 +416,7 @@ export function attachCachedActionHelpers(
     runCachedAction(
       agent,
       page,
-      options?.performInstruction || "Scroll next chunk",
+      "Scroll next chunk",
       "nextChunk",
       xpath,
       [],
@@ -199,7 +427,7 @@ export function attachCachedActionHelpers(
     runCachedAction(
       agent,
       page,
-      options?.performInstruction || "Scroll previous chunk",
+      "Scroll previous chunk",
       "prevChunk",
       xpath,
       [],
diff --git a/src/agent/shared/action-cache-script.test.ts b/src/agent/shared/action-cache-script.test.ts
new file mode 100644
index 00000000..a7782184
--- /dev/null
+++ b/src/agent/shared/action-cache-script.test.ts
@@ -0,0 +1,96 @@
+import { createScriptFromActionCache } from "@/agent/shared/action-cache-script";
+import type { ActionCacheEntry } from "@/types/agent/types";
+
+function createStep(
+  stepIndex: number,
+  overrides: Partial<ActionCacheEntry> = {}
+): ActionCacheEntry {
+  return {
+    stepIndex,
+    instruction: `step-${stepIndex}`,
+    elementId: null,
+    method: null,
+    arguments: [],
+    frameIndex: null,
+    xpath: null,
+    actionType: "unknown-action",
+    success: true,
+    message: "cached",
+    ...overrides,
+  };
+}
+
+describe("createScriptFromActionCache hardening", () => {
+  it("truncates oversized script step lists to bounded limits", () => {
+    const steps = Array.from({ length: 1002 }, (_, index) =>
+      createStep(index, { actionType: "complete" })
+    );
+
+    const script = createScriptFromActionCache({
+      taskId: "task-1",
+      steps,
+    });
+
+    expect(script).toContain(
+      "Script truncated after 1000 steps; 2 additional step(s) were skipped"
+    );
+    expect(script).toContain("// Step 999 (complete skipped in script)");
+    expect(script).not.toContain("// Step 1001 (complete skipped in script)");
+  });
+
+  it("sanitizes oversized unsupported action identifiers", () => {
+    const script = createScriptFromActionCache({
+      taskId: "task-2",
+      steps: [
+        createStep(0, {
+          actionType: `action-${"x".repeat(300)}\u0007`,
+          method: `method-${"y".repeat(300)}\u0007`,
+          xpath: null,
+        }),
+      ],
+    });
+
+    const unsupportedLine = script
+      .split("\n")
+      .find((line) => line.includes("unsupported actionType="));
+    expect(unsupportedLine).toBeDefined();
+    expect(unsupportedLine).toContain("[truncated");
+    expect(unsupportedLine).not.toContain("\u0007");
+  });
+
+  it("sanitizes oversized goToUrl arguments in generated script", () => {
+    const script = createScriptFromActionCache({
+      taskId: "task-3",
+      steps: [
+        createStep(0, {
+          actionType: "goToUrl",
+          arguments: [`https://example.com/${"x".repeat(5_000)}\nunsafe`],
+        }),
+      ],
+    });
+
+    expect(script).toContain("await page.goto(");
+    expect(script).toContain("[truncated");
+    expect(script).not.toContain("\\nunsafe");
+  });
+
+  it("handles trap-prone stepIndex getters when sorting script steps", () => {
+    const trapStep = new Proxy(createStep(99, { actionType: "complete" }), {
+      get(target, prop, receiver): unknown {
+        if (prop === "stepIndex") {
+          throw new Error("stepIndex trap");
+        }
+        return Reflect.get(target, prop, receiver);
+      },
+    });
+
+    const script = createScriptFromActionCache({
+      taskId: "task-4",
+      steps: [trapStep as unknown as ActionCacheEntry, createStep(1, { actionType: "complete" })],
+    });
+
+    expect(script).toContain("// Step 1 (complete skipped in script)");
+    expect(script).toContain("// Step -1 (complete skipped in script)");
+  });
+});
+
diff --git a/src/agent/shared/action-cache-script.ts b/src/agent/shared/action-cache-script.ts
index 61406aa6..7375a466 100644
--- a/src/agent/shared/action-cache-script.ts
+++ b/src/agent/shared/action-cache-script.ts
@@ -5,6 +5,140 @@ interface CreateScriptFromActionCacheParams {
   steps: ActionCacheEntry[];
 }
 
+const getSortStepIndex = (value: number): number =>
+  Number.isFinite(value) ? value : Number.MAX_SAFE_INTEGER;
+
+const MAX_SCRIPT_WAIT_MS = 120_000;
+const MAX_SCRIPT_TIMEOUT_MS = 120_000;
+const MAX_SCRIPT_STEPS = 1_000;
+const MAX_SCRIPT_IDENTIFIER_CHARS = 128;
+const MAX_SCRIPT_TEXT_ARG_CHARS = 4_000;
+
+const isRecord = (value: unknown): value is Record<string, unknown> =>
+  typeof value === "object" && value !== null;
+
+const isNonEmptyString = (value: unknown): value is string =>
+  typeof value === "string" && value.trim().length > 0;
+
+const asNonEmptyTrimmedString = (value: unknown): string | undefined => {
+  if (typeof value !== "string") {
+    return undefined;
+  }
+  const trimmed = value.trim();
+  return trimmed.length > 0 ? trimmed : undefined;
+};
+
+const asNumber = (value: unknown): number | undefined => {
+  if (typeof value === "number" && Number.isFinite(value)) {
+    return value;
+  }
+  if (typeof value === "string") {
+    const parsed = Number.parseInt(value, 10);
+    return Number.isFinite(parsed) ? parsed : undefined;
+  }
+  return undefined;
+};
+
+const sanitizeScriptText = (value: string): string => {
+  if (value.length === 0) {
+    return value;
+  }
+  const withoutControlChars = Array.from(value, (char) => {
+    const code = char.charCodeAt(0);
+    return (code >= 0 && code < 32) || code === 127 ? " " : char;
+  }).join("");
+  return withoutControlChars.replace(/\s+/g, " ").trim();
+};
+
+const truncateScriptText = (value: string, maxChars: number): string => {
+  if (value.length <= maxChars) {
+    return value;
+  }
+  const omitted = value.length - maxChars;
+  return `${value.slice(0, maxChars)}... [truncated ${omitted} chars]`;
+};
+
+const sanitizeScriptIdentifier = (value: unknown, fallback: string): string => {
+  if (typeof value !== "string") {
+    return fallback;
+  }
+  const normalized = sanitizeScriptText(value);
+  if (normalized.length === 0) {
+    return fallback;
+  }
+  return truncateScriptText(normalized, MAX_SCRIPT_IDENTIFIER_CHARS);
+};
+
+const sanitizeScriptArgText = (value: unknown): string | undefined => {
+  if (typeof value !== "string") {
+    return undefined;
+  }
+  const normalized = sanitizeScriptText(value);
+  if (normalized.length === 0) {
+    return undefined;
+  }
+  return truncateScriptText(normalized, MAX_SCRIPT_TEXT_ARG_CHARS);
+};
+
+const safeReadStepField = (
+  step: ActionCacheEntry,
+  field: keyof ActionCacheEntry
+): unknown => {
+  try {
+    return (step as unknown as Record<string, unknown>)[field];
+  } catch {
+    return undefined;
+  }
+};
+
+const safeReadArrayIndex = (value: unknown, index: number): unknown => {
+  if (!Array.isArray(value)) {
+    return undefined;
+  }
+  try {
+    return value[index];
+  } catch {
+    return undefined;
+  }
+};
+
+const getSortStepIndexFromEntry = (step: ActionCacheEntry): number => {
+  const rawStepIndex = safeReadStepField(step, "stepIndex");
+  return typeof rawStepIndex === "number"
+    ? getSortStepIndex(rawStepIndex)
+    : Number.MAX_SAFE_INTEGER;
+};
+
+const normalizeWaitMs = (value: unknown): number => {
+  const parsed = asNumber(value);
+  if (parsed === undefined) {
+    return 1000;
+  }
+  if (parsed < 0) {
+    return 1000;
+  }
+  return Math.min(parsed, MAX_SCRIPT_WAIT_MS);
+};
+
+const normalizeWaitUntil = (value: unknown): "domcontentloaded" | "load" | "networkidle" => {
+  const parsed = asNonEmptyTrimmedString(value)?.toLowerCase();
+  if (parsed === "load" || parsed === "networkidle") {
+    return parsed;
+  }
+  return "domcontentloaded";
+};
+
+const normalizeOptionalTimeoutMs = (value: unknown): number | undefined => {
+  const parsed = asNumber(value);
+  if (parsed === undefined) {
+    return undefined;
+  }
+  if (parsed < 0) {
+    return undefined;
+  }
+  return Math.min(parsed, MAX_SCRIPT_TIMEOUT_MS);
+};
+
 export function createScriptFromActionCache(
   params: CreateScriptFromActionCacheParams
 ): string {
@@ -35,62 +169,121 @@ export function createScriptFromActionCache(
     nextChunk: { fn: "performNextChunk" },
     prevChunk: { fn: "performPrevChunk" },
   };
+  const METHOD_TO_CALL_KEYS = Object.keys(METHOD_TO_CALL);
+  const normalizeHelperMethod = (method: string | null | undefined): string | null => {
+    const normalizedMethod = method?.trim().toLowerCase();
+    if (!normalizedMethod) {
+      return null;
+    }
+    return (
+      METHOD_TO_CALL_KEYS.find(
+        (candidate) => candidate.toLowerCase() === normalizedMethod
+      ) ?? null
+    );
+  };
 
   const formatCall = (step: ActionCacheEntry): string => {
     const indent = "  ";
     const argIndent = `${indent}  `;
+    const stepIndexValue = safeReadStepField(step, "stepIndex");
+    const actionTypeValue = safeReadStepField(step, "actionType");
+    const instructionValue = safeReadStepField(step, "instruction");
+    const methodValue = safeReadStepField(step, "method");
+    const xpathValue = safeReadStepField(step, "xpath");
+    const frameIndexValue = safeReadStepField(step, "frameIndex");
+    const argumentsValue = safeReadStepField(step, "arguments");
+    const actionParamsValue = safeReadStepField(step, "actionParams");
+    const safeStepIndex =
+      typeof stepIndexValue === "number" && Number.isFinite(stepIndexValue)
+        ? stepIndexValue
+        : -1;
+    const actionType = sanitizeScriptIdentifier(actionTypeValue, "unknown");
 
-    if (step.actionType === "complete") {
-      return `${indent}// Step ${step.stepIndex} (complete skipped in script)`;
+    if (actionType === "complete") {
+      return `${indent}// Step ${safeStepIndex} (complete skipped in script)`;
     }
 
-    if (step.actionType === "goToUrl") {
+    if (actionType === "goToUrl") {
+      const actionParams = isRecord(actionParamsValue)
+        ? actionParamsValue
+        : undefined;
+      const argumentUrl =
+        sanitizeScriptArgText(safeReadArrayIndex(argumentsValue, 0)) ?? "";
       const urlArg =
-        (step.arguments && step.arguments[0]) || "https://example.com";
-      return `${indent}// Step ${step.stepIndex}
+        argumentUrl ||
+        (sanitizeScriptArgText(actionParams?.url) ?? "") ||
+        "https://example.com";
+      return `${indent}// Step ${safeStepIndex}
 ${indent}await page.goto(
 ${argIndent}${JSON.stringify(urlArg)},
 ${argIndent}{ waitUntil: "domcontentloaded" }
 ${indent});`;
     }
 
-    if (step.actionType === "refreshPage") {
-      return `${indent}// Step ${step.stepIndex}
+    if (actionType === "refreshPage") {
+      return `${indent}// Step ${safeStepIndex}
 ${indent}await page.reload({ waitUntil: "domcontentloaded" });`;
     }
 
-    if (step.actionType === "wait") {
-      const waitMs =
-        (step.arguments && Number(step.arguments[0])) ||
-        (step.actionParams as any)?.duration ||
-        1000;
-      return `${indent}// Step ${step.stepIndex}
+    if (actionType === "wait") {
+      const actionParams = isRecord(actionParamsValue)
+        ? actionParamsValue
+        : undefined;
+      const waitMs = normalizeWaitMs(
+        safeReadArrayIndex(argumentsValue, 0) ?? actionParams?.duration
+      );
+      return `${indent}// Step ${safeStepIndex}
 ${indent}await page.waitForTimeout(${waitMs});`;
     }
 
-    if (step.actionType === "extract") {
-      return `${indent}// Step ${step.stepIndex}
-${indent}await page.extract("${step.instruction}");`;
+    if (actionType === "waitForLoadState") {
+      const actionParams = isRecord(actionParamsValue)
+        ? actionParamsValue
+        : undefined;
+      const waitUntil = normalizeWaitUntil(
+        safeReadArrayIndex(argumentsValue, 0) ?? actionParams?.waitUntil
+      );
+      const timeoutMs = normalizeOptionalTimeoutMs(
+        safeReadArrayIndex(argumentsValue, 1) ?? actionParams?.timeout
+      );
+      if (typeof timeoutMs === "number" && Number.isFinite(timeoutMs)) {
+        return `${indent}// Step ${safeStepIndex}
+${indent}await page.waitForLoadState(${JSON.stringify(waitUntil)}, { timeout: ${timeoutMs} });`;
+      }
+      return `${indent}// Step ${safeStepIndex}
+${indent}await page.waitForLoadState(${JSON.stringify(waitUntil)});`;
+    }
+
+    if (actionType === "extract") {
+      const extractInstruction = sanitizeScriptArgText(instructionValue);
+      if (!extractInstruction) {
+        return `${indent}// Step ${safeStepIndex} (extract skipped: missing instruction)`;
+      }
+      return `${indent}// Step ${safeStepIndex}
+${indent}await page.extract(${JSON.stringify(extractInstruction)});`;
     }
 
-    const call = step.method ? METHOD_TO_CALL[step.method] : undefined;
+    const normalizedMethod = normalizeHelperMethod(
+      typeof methodValue === "string" ? methodValue : null
+    );
+    const call = normalizedMethod ? METHOD_TO_CALL[normalizedMethod] : undefined;
     if (call) {
-      const args: string[] = [];
-      args.push(JSON.stringify(step.xpath));
-      if (call.needsValue) {
-        const value = step.arguments?.[0] ?? "";
-        args.push(JSON.stringify(value));
+      const normalizedXPath = sanitizeScriptArgText(xpathValue);
+      if (!normalizedXPath) {
+        const methodLabel = sanitizeScriptIdentifier(methodValue, "N/A");
+        return `${indent}// Step ${safeStepIndex} (unsupported actionType=${actionType}, method=${methodLabel}, reason=missing xpath)`;
       }
       const options: Record<string, unknown> = {};
-      if (step.instruction) {
-        options.performInstruction = step.instruction;
+      const performInstruction = sanitizeScriptArgText(instructionValue);
+      if (performInstruction) {
+        options.performInstruction = performInstruction;
       }
       if (
-        step.frameIndex !== null &&
-        step.frameIndex !== undefined &&
-        step.frameIndex !== 0
+        typeof frameIndexValue === "number" &&
+        Number.isFinite(frameIndexValue) &&
+        frameIndexValue !== 0
       ) {
-        options.frameIndex = step.frameIndex;
+        options.frameIndex = frameIndexValue;
       }
 
       const optionEntries = Object.entries(options).map(
@@ -102,25 +295,40 @@ ${indent}await page.extract("${step.instruction}");`;
           : "";
 
       const callArgs = [
-        `${argIndent}${JSON.stringify(step.xpath)},`,
+        `${argIndent}${JSON.stringify(normalizedXPath)},`,
         call.needsValue
-          ? `${argIndent}${JSON.stringify(step.arguments?.[0] ?? "")},`
+          ? `${argIndent}${JSON.stringify(
+              sanitizeScriptArgText(safeReadArrayIndex(argumentsValue, 0)) ?? ""
+            )},`
           : null,
         optionsBlock ? `${optionsBlock},` : null,
       ]
         .filter(Boolean)
         .join("\n");
 
-      return `${indent}// Step ${step.stepIndex}
+      return `${indent}// Step ${safeStepIndex}
 ${indent}await page.${call.fn}(
 ${callArgs}
 ${indent});`;
     }
 
-    return `${indent}// Step ${step.stepIndex} (unsupported actionType=${step.actionType}, method=${step.method ?? "N/A"})`;
+    const methodLabel = sanitizeScriptIdentifier(methodValue, "N/A");
+    return `${indent}// Step ${safeStepIndex} (unsupported actionType=${actionType}, method=${methodLabel})`;
   };
 
-  const stepSnippets = steps.map((step) => formatCall(step)).join("\n\n");
+  let omittedSteps = 0;
+  const sortedSteps = [...steps].sort(
+    (a, b) => getSortStepIndexFromEntry(a) - getSortStepIndexFromEntry(b)
+  );
+  if (sortedSteps.length > MAX_SCRIPT_STEPS) {
+    omittedSteps = sortedSteps.length - MAX_SCRIPT_STEPS;
+    sortedSteps.length = MAX_SCRIPT_STEPS;
+  }
+  const stepSnippets = sortedSteps.map((step) => formatCall(step)).join("\n\n");
+  const truncatedComment =
+    omittedSteps > 0
+      ? `\n\n  // Script truncated after ${MAX_SCRIPT_STEPS} steps; ${omittedSteps} additional step(s) were skipped`
+      : "";
 
   const script = `import { HyperAgent } from "@hyperbrowser/agent";
 async function main() {
@@ -131,6 +339,7 @@ async function main() {
   const page = await agent.newPage();
 
 ${stepSnippets}
+${truncatedComment}
 
   await agent.closeAgent();
 }
diff --git a/src/agent/shared/action-cache.test.ts b/src/agent/shared/action-cache.test.ts
new file mode 100644
index 00000000..b2bc491b
--- /dev/null
+++ b/src/agent/shared/action-cache.test.ts
@@ -0,0 +1,780 @@
+import { buildActionCacheEntry } from "@/agent/shared/action-cache";
+import { createScriptFromActionCache } from "@/agent/shared/action-cache-script";
+import type { ActionOutput, ActionType } from "@/types";
+import type { A11yDOMState } from "@/context-providers/a11y-dom/types";
+import type { ActionCacheEntry } from "@/types/agent/types";
+
+describe("action cache helpers", () => {
+  it("normalizes goToUrl cache arguments from action params", () => {
+    const action = {
+      type: "goToUrl",
+      params: {
+        url: "https://example.com",
+      },
+    } as unknown as ActionType;
+    const actionOutput: ActionOutput = {
+      success: true,
+      message: "ok",
+    };
+    const domState: A11yDOMState = {
+      elements: new Map(),
+      domState: "",
+      xpathMap: {},
+      backendNodeMap: {},
+    };
+
+    const entry = buildActionCacheEntry({
+      stepIndex: 0,
+      action,
+      actionOutput,
+      domState,
+    });
+
+    expect(entry.arguments).toEqual(["https://example.com"]);
+  });
+
+  it("does not throw when required instruction-like params are missing", () => {
+    const domState: A11yDOMState = {
+      elements: new Map(),
+      domState: "",
+      xpathMap: {},
+      backendNodeMap: {},
+    };
+    const actionOutput: ActionOutput = {
+      success: true,
+      message: "ok",
+    };
+
+    const extractEntry = buildActionCacheEntry({
+      stepIndex: 0,
+      action: {
+        type: "extract",
+        params: {},
+      } as unknown as ActionType,
+      actionOutput,
+      domState,
+    });
+
+    const actEntry = buildActionCacheEntry({
+      stepIndex: 1,
+      action: {
+        type: "actElement",
+        params: {
+          elementId: "0-1",
+          method: "click",
+          arguments: [],
+        },
+      } as unknown as ActionType,
+      actionOutput,
+      domState,
+    });
+
+    expect(extractEntry.instruction).toBeUndefined();
+    expect(actEntry.instruction).toBeUndefined();
+    expect(actEntry.method).toBe("click");
+  });
+
+  it("does not throw when action params are nullish", () => {
+    const domState: A11yDOMState = {
+      elements: new Map(),
+      domState: "",
+      xpathMap: {},
+      backendNodeMap: {},
+    };
+    const actionOutput: ActionOutput = {
+      success: true,
+      message: "ok",
+    };
+
+    expect(() =>
+      buildActionCacheEntry({
+        stepIndex: 2,
+        action: {
+          type: "actElement",
+          params: null,
+        } as unknown as ActionType,
+        actionOutput,
+        domState,
+      })
+    ).not.toThrow();
+  });
+
+  it("handles trap-prone action and actionOutput getters safely", () => {
+    const action = new Proxy(
+      {},
+      {
+        get: (_target, prop) => {
+          if (prop === "type" || prop === "params") {
+            throw new Error("action getter trap");
+          }
+          return undefined;
+        },
+      }
+    ) as unknown as ActionType;
+    const actionOutput = new Proxy(
+      {},
+      {
+        get: (_target, prop) => {
+          if (prop === "success" || prop === "message" || prop === "debug") {
+            throw new Error("output getter trap");
+          }
+          return undefined;
+        },
+      }
+    ) as unknown as ActionOutput;
+    const domState: A11yDOMState = {
+      elements: new Map(),
+      domState: "",
+      xpathMap: {},
+      backendNodeMap: {},
+    };
+
+    const entry = buildActionCacheEntry({
+      stepIndex: 99,
+      action,
+      actionOutput,
+      domState,
+    });
+
+    expect(entry.actionType).toBe("unknown");
+    expect(entry.success).toBe(false);
+    expect(entry.message).toBe("undefined");
+    expect(entry.arguments).toEqual([]);
+  });
+
+  it("handles trap-prone domState xpath maps safely", () => {
+    const action = {
+      type: "actElement",
+      params: {
+        elementId: "0-123",
+        method: "click",
+        arguments: [],
+      },
+    } as unknown as ActionType;
+    const actionOutput: ActionOutput = {
+      success: true,
+      message: "ok",
+      debug: {
+        elementMetadata: {
+          xpath: "//button[1]",
+        },
+      },
+    };
+    const domState = new Proxy(
+      {
+        elements: new Map(),
+        domState: "",
+        backendNodeMap: {},
+      },
+      {
+        get: (target, prop, receiver) => {
+          if (prop === "xpathMap") {
+            throw new Error("xpath map trap");
+          }
+          return Reflect.get(target, prop, receiver);
+        },
+      }
+    ) as unknown as A11yDOMState;
+
+    const entry = buildActionCacheEntry({
+      stepIndex: 100,
+      action,
+      actionOutput,
+      domState,
+    });
+
+    expect(entry.xpath).toBe("//button[1]");
+  });
+
+  it("truncates oversized cached action output diagnostics", () => {
+    const action = {
+      type: "actElement",
+      params: {
+        elementId: "0-123",
+        method: "click",
+        arguments: [],
+      },
+    } as unknown as ActionType;
+    const actionOutput: ActionOutput = {
+      success: false,
+      message: `boom\u0000${"x".repeat(5_000)}`,
+    };
+    const domState: A11yDOMState = {
+      elements: new Map(),
+      domState: "",
+      xpathMap: {},
+      backendNodeMap: {},
+    };
+
+    const entry = buildActionCacheEntry({
+      stepIndex: 101,
+      action,
+      actionOutput,
+      domState,
+    });
+
+    expect(entry.message).toContain("[truncated");
+    expect(entry.message).not.toContain("\u0000");
+  });
+
+  it("bounds cached action arguments for replay safety", () => {
+    const action = {
+      type: "actElement",
+      params: {
+        elementId: "0-321",
+        method: "type",
+        arguments: Array.from({ length: 30 }, () => "x".repeat(3_000)),
+      },
+    } as unknown as ActionType;
+    const actionOutput: ActionOutput = {
+      success: true,
+      message: "ok",
+    };
+    const domState: A11yDOMState = {
+      elements: new Map(),
+      domState: "",
+      xpathMap: {},
+      backendNodeMap: {},
+    };
+
+    const entry = buildActionCacheEntry({
+      stepIndex: 102,
+      action,
+      actionOutput,
+      domState,
+    });
+
+    expect(entry.arguments).toHaveLength(20);
+    expect(entry.arguments[0]).toContain("[truncated");
+  });
+
+  it("uses actionParams url when goToUrl argument is whitespace", () => {
+    const goToEntry: ActionCacheEntry = {
+      stepIndex: 1,
+      instruction: "navigate",
+      elementId: null,
+      method: null,
+      arguments: ["   "],
+      actionType: "goToUrl",
+      success: true,
+      message: "ok",
+      frameIndex: null,
+      xpath: null,
+      actionParams: {
+        url: "https://example.org",
+      },
+    };
+
+    const script = createScriptFromActionCache({
+      steps: [goToEntry],
+    });
+
+    expect(script).toContain('"https://example.org"');
+  });
+
+  it("trims goToUrl argument before script generation", () => {
+    const goToEntry: ActionCacheEntry = {
+      stepIndex: 9,
+      instruction: "navigate",
+      elementId: null,
+      method: null,
+      arguments: ["  https://trimmed.example  "],
+      actionType: "goToUrl",
+      success: true,
+      message: "ok",
+      frameIndex: null,
+      xpath: null,
+    };
+
+    const script = createScriptFromActionCache({
+      steps: [goToEntry],
+    });
+
+    expect(script).toContain('"https://trimmed.example"');
+    expect(script).not.toContain('"  https://trimmed.example  "');
+  });
+
+  it("renders wait script timeout from numeric actionParams duration", () => {
+    const waitEntry: ActionCacheEntry = {
+      stepIndex: 2,
+      instruction: "wait a bit",
+      elementId: null,
+      method: null,
+      arguments: [],
+      actionType: "wait",
+      success: true,
+      message: "ok",
+      frameIndex: null,
+      xpath: null,
+      actionParams: {
+        duration: 2500,
+      },
+    };
+
+    const script = createScriptFromActionCache({
+      steps: [waitEntry],
+    });
+
+    expect(script).toContain("waitForTimeout(2500)");
+  });
+
+  it("renders wait script timeout from string duration", () => {
+    const waitEntry: ActionCacheEntry = {
+      stepIndex: 5,
+      instruction: "wait from string",
+      elementId: null,
+      method: null,
+      arguments: [],
+      actionType: "wait",
+      success: true,
+      message: "ok",
+      frameIndex: null,
+      xpath: null,
+      actionParams: {
+        duration: "700",
+      },
+    };
+
+    const script = createScriptFromActionCache({
+      steps: [waitEntry],
+    });
+
+    expect(script).toContain("waitForTimeout(700)");
+  });
+
+  it("preserves zero wait duration when explicitly provided", () => {
+    const waitEntry: ActionCacheEntry = {
+      stepIndex: 6,
+      instruction: "wait zero",
+      elementId: null,
+      method: null,
+      arguments: ["0"],
+      actionType: "wait",
+      success: true,
+      message: "ok",
+      frameIndex: null,
+      xpath: null,
+    };
+
+    const script = createScriptFromActionCache({
+      steps: [waitEntry],
+    });
+
+    expect(script).toContain("waitForTimeout(0)");
+  });
+
+  it("normalizes negative wait durations to default timeout", () => {
+    const waitEntry: ActionCacheEntry = {
+      stepIndex: 8,
+      instruction: "wait negative",
+      elementId: null,
+      method: null,
+      arguments: ["-10"],
+      actionType: "wait",
+      success: true,
+      message: "ok",
+      frameIndex: null,
+      xpath: null,
+    };
+
+    const script = createScriptFromActionCache({
+      steps: [waitEntry],
+    });
+
+    expect(script).toContain("waitForTimeout(1000)");
+  });
+
+  it("caps oversized wait durations in generated script", () => {
+    const waitEntry: ActionCacheEntry = {
+      stepIndex: 9,
+      instruction: "wait oversized",
+      elementId: null,
+      method: null,
+      arguments: ["999999"],
+      actionType: "wait",
+      success: true,
+      message: "ok",
+      frameIndex: null,
+      xpath: null,
+    };
+
+    const script = createScriptFromActionCache({
+      steps: [waitEntry],
+    });
+
+    expect(script).toContain("waitForTimeout(120000)");
+  });
+
+  it("renders waitForLoadState script with timeout when provided", () => {
+    const waitEntry: ActionCacheEntry = {
+      stepIndex: 12,
+      instruction: "wait for network idle",
+      elementId: null,
+      method: null,
+      arguments: ["networkidle", "2500"],
+      actionType: "waitForLoadState",
+      success: true,
+      message: "ok",
+      frameIndex: null,
+      xpath: null,
+    };
+
+    const script = createScriptFromActionCache({
+      steps: [waitEntry],
+    });
+
+    expect(script).toContain(
+      'await page.waitForLoadState("networkidle", { timeout: 2500 });'
+    );
+  });
+
+  it("renders waitForLoadState script defaulting to domcontentloaded", () => {
+    const waitEntry: ActionCacheEntry = {
+      stepIndex: 13,
+      instruction: "wait default",
+      elementId: null,
+      method: null,
+      arguments: [],
+      actionType: "waitForLoadState",
+      success: true,
+      message: "ok",
+      frameIndex: null,
+      xpath: null,
+    };
+
+    const script = createScriptFromActionCache({
+      steps: [waitEntry],
+    });
+
+    expect(script).toContain('await page.waitForLoadState("domcontentloaded");');
+  });
+
+  it("normalizes unsupported waitForLoadState targets to domcontentloaded", () => {
+    const waitEntry: ActionCacheEntry = {
+      stepIndex: 14,
+      instruction: "wait unsupported",
+      elementId: null,
+      method: null,
+      arguments: ["interactive"],
+      actionType: "waitForLoadState",
+      success: true,
+      message: "ok",
+      frameIndex: null,
+      xpath: null,
+    };
+
+    const script = createScriptFromActionCache({
+      steps: [waitEntry],
+    });
+
+    expect(script).toContain('await page.waitForLoadState("domcontentloaded");');
+    expect(script).not.toContain('await page.waitForLoadState("interactive");');
+  });
+
+  it("normalizes waitForLoadState target casing in generated script", () => {
+    const waitEntry: ActionCacheEntry = {
+      stepIndex: 17,
+      instruction: "wait uppercase target",
+      elementId: null,
+      method: null,
+      arguments: ["LOAD"],
+      actionType: "waitForLoadState",
+      success: true,
+      message: "ok",
+      frameIndex: null,
+      xpath: null,
+    };
+
+    const script = createScriptFromActionCache({
+      steps: [waitEntry],
+    });
+
+    expect(script).toContain('await page.waitForLoadState("load");');
+  });
+
+  it("renders waitForLoadState timeout from actionParams fallback", () => {
+    const waitEntry: ActionCacheEntry = {
+      stepIndex: 15,
+      instruction: "wait action params",
+      elementId: null,
+      method: null,
+      arguments: [],
+      actionType: "waitForLoadState",
+      success: true,
+      message: "ok",
+      frameIndex: null,
+      xpath: null,
+      actionParams: {
+        waitUntil: "load",
+        timeout: 900,
+      },
+    };
+
+    const script = createScriptFromActionCache({
+      steps: [waitEntry],
+    });
+
+    expect(script).toContain('await page.waitForLoadState("load", { timeout: 900 });');
+  });
+
+  it("omits negative waitForLoadState timeout in generated script", () => {
+    const waitEntry: ActionCacheEntry = {
+      stepIndex: 16,
+      instruction: "wait negative timeout",
+      elementId: null,
+      method: null,
+      arguments: ["networkidle", "-10"],
+      actionType: "waitForLoadState",
+      success: true,
+      message: "ok",
+      frameIndex: null,
+      xpath: null,
+    };
+
+    const script = createScriptFromActionCache({
+      steps: [waitEntry],
+    });
+
+    expect(script).toContain('await page.waitForLoadState("networkidle");');
+    expect(script).not.toContain("timeout: -10");
+  });
+
+  it("caps oversized waitForLoadState timeout in generated script", () => {
+    const waitEntry: ActionCacheEntry = {
+      stepIndex: 17,
+      instruction: "wait oversized timeout",
+      elementId: null,
+      method: null,
+      arguments: ["load", "999999"],
+      actionType: "waitForLoadState",
+      success: true,
+      message: "ok",
+      frameIndex: null,
+      xpath: null,
+    };
+
+    const script = createScriptFromActionCache({
+      steps: [waitEntry],
+    });
+
+    expect(script).toContain('await page.waitForLoadState("load", { timeout: 120000 });');
+  });
+
+  it("skips helper generation when xpath is missing", () => {
+    const actElementEntry: ActionCacheEntry = {
+      stepIndex: 3,
+      instruction: "click login",
+      elementId: "0-10",
+      method: "click",
+      arguments: [],
+      actionType: "actElement",
+      success: true,
+      message: "ok",
+      frameIndex: 0,
+      xpath: null,
+    };
+
+    const script = createScriptFromActionCache({
+      steps: [actElementEntry],
+    });
+
+    expect(script).toContain("reason=missing xpath");
+    expect(script).not.toContain("await page.performClick(");
+  });
+
+  it("skips extract generation when instruction is missing", () => {
+    const extractEntry: ActionCacheEntry = {
+      stepIndex: 4,
+      instruction: undefined,
+      elementId: null,
+      method: null,
+      arguments: [],
+      actionType: "extract",
+      success: true,
+      message: "ok",
+      frameIndex: null,
+      xpath: null,
+    };
+
+    const script = createScriptFromActionCache({
+      steps: [extractEntry],
+    });
+
+    expect(script).toContain("extract skipped: missing instruction");
+    expect(script).not.toContain("await page.extract(");
+  });
+
+  it("escapes extract instruction content in generated script", () => {
+    const instruction = 'extract "quoted" title\nand subtitle';
+    const normalizedInstruction = 'extract "quoted" title and subtitle';
+    const extractEntry: ActionCacheEntry = {
+      stepIndex: 7,
+      instruction,
+      elementId: null,
+      method: null,
+      arguments: [],
+      actionType: "extract",
+      success: true,
+      message: "ok",
+      frameIndex: null,
+      xpath: null,
+    };
+
+    const script = createScriptFromActionCache({
+      steps: [extractEntry],
+    });
+
+    expect(script).toContain(
+      `await page.extract(${JSON.stringify(normalizedInstruction)});`
+    );
+  });
+
+  it("trims extract instruction before script generation", () => {
+    const extractEntry: ActionCacheEntry = {
+      stepIndex: 10,
+      instruction: "  extract headline  ",
+      elementId: null,
+      method: null,
+      arguments: [],
+      actionType: "extract",
+      success: true,
+      message: "ok",
+      frameIndex: null,
+      xpath: null,
+    };
+
+    const script = createScriptFromActionCache({
+      steps: [extractEntry],
+    });
+
+    expect(script).toContain('await page.extract("extract headline");');
+    expect(script).not.toContain('await page.extract("  extract headline  ");');
+  });
+
+  it("omits performInstruction option when instruction is whitespace", () => {
+    const helperEntry: ActionCacheEntry = {
+      stepIndex: 11,
+      instruction: "   ",
+      elementId: "0-1",
+      method: "click",
+      arguments: [],
+      actionType: "actElement",
+      success: true,
+      message: "ok",
+      frameIndex: 0,
+      xpath: "//button[1]",
+    };
+
+    const script = createScriptFromActionCache({
+      steps: [helperEntry],
+    });
+
+    expect(script).toContain("await page.performClick(");
+    expect(script).not.toContain("performInstruction");
+  });
+
+  it("trims helper method and xpath before script generation", () => {
+    const helperEntry: ActionCacheEntry = {
+      stepIndex: 18,
+      instruction: "click login",
+      elementId: "0-1",
+      method: " CLICK ",
+      arguments: [],
+      actionType: "actElement",
+      success: true,
+      message: "ok",
+      frameIndex: 0,
+      xpath: "  //button[1]  ",
+    };
+
+    const script = createScriptFromActionCache({
+      steps: [helperEntry],
+    });
+
+    expect(script).toContain("await page.performClick(");
+    expect(script).toContain('"//button[1]"');
+    expect(script).not.toContain('"  //button[1]  "');
+  });
+
+  it("sorts generated script steps by finite step index", () => {
+    const unorderedSteps: ActionCacheEntry[] = [
+      {
+        stepIndex: Number.NaN,
+        instruction: "nan step",
+        elementId: null,
+        method: null,
+        arguments: [],
+        actionType: "wait",
+        success: true,
+        message: "ok",
+        frameIndex: null,
+        xpath: null,
+      },
+      {
+        stepIndex: 2,
+        instruction: "third step",
+        elementId: null,
+        method: null,
+        arguments: ["300"],
+        actionType: "wait",
+        success: true,
+        message: "ok",
+        frameIndex: null,
+        xpath: null,
+      },
+      {
+        stepIndex: 0,
+        instruction: "first step",
+        elementId: null,
+        method: null,
+        arguments: ["100"],
+        actionType: "wait",
+        success: true,
+        message: "ok",
+        frameIndex: null,
+        xpath: null,
+      },
+    ];
+
+    const script = createScriptFromActionCache({
+      steps: unorderedSteps,
+    });
+
+    const idx0 = script.indexOf("// Step 0");
+    const idx2 = script.indexOf("// Step 2");
+    const idxNaN = script.indexOf("// Step -1");
+    expect(idx0).toBeGreaterThan(-1);
+    expect(idx2).toBeGreaterThan(idx0);
+    expect(idxNaN).toBeGreaterThan(idx2);
+  });
+
+  it("handles trap-prone step getters without crashing script generation", () => {
+    const trappedStep = new Proxy(
+      {},
+      {
+        get: (_target, prop) => {
+          if (
+            prop === "stepIndex" ||
+            prop === "actionType" ||
+            prop === "instruction" ||
+            prop === "method" ||
+            prop === "xpath" ||
+            prop === "arguments" ||
+            prop === "actionParams" ||
+            prop === "frameIndex"
+          ) {
+            throw new Error("step getter trap");
+          }
+          return undefined;
+        },
+      }
+    ) as unknown as ActionCacheEntry;
+
+    const script = createScriptFromActionCache({
+      steps: [trappedStep],
+    });
+
+    expect(script).toContain("// Step -1");
+    expect(script).toContain("unsupported actionType=unknown");
+  });
+});
diff --git a/src/agent/shared/action-cache.ts b/src/agent/shared/action-cache.ts
index 41f1be57..6eaff5b6 100644
--- a/src/agent/shared/action-cache.ts
+++ b/src/agent/shared/action-cache.ts
@@ -4,17 +4,109 @@ import {
   A11yDOMState,
   asEncodedId,
 } from "@/context-providers/a11y-dom/types";
+import { formatUnknownError } from "@/utils";
 
 const TEXT_NODE_SUFFIX = /\/text\(\)(\[\d+\])?$/iu;
+const MAX_ACTION_CACHE_IDENTIFIER_CHARS = 128;
+const MAX_ACTION_CACHE_INSTRUCTION_CHARS = 2_000;
+const MAX_ACTION_CACHE_XPATH_CHARS = 4_000;
+const MAX_ACTION_CACHE_MESSAGE_CHARS = 4_000;
+const MAX_ACTION_CACHE_ARGUMENTS = 20;
+const MAX_ACTION_CACHE_ARGUMENT_CHARS = 2_000;
 
 const isString = (value: unknown): value is string =>
   typeof value === "string";
 
-const isStringOrNumberArray = (
-  value: unknown
-): value is Array<string | number> =>
-  Array.isArray(value) &&
-  value.every((item) => typeof item === "string" || typeof item === "number");
+const isRecord = (value: unknown): value is Record<string, unknown> =>
+  typeof value === "object" && value !== null;
+
+const safeReadRecordField = (
+  value: Record<string, unknown>,
+  key: string
+): unknown => {
+  try {
+    return value[key];
+  } catch {
+    return undefined;
+  }
+};
+
+const safeReadActionField = (
+  action: ActionType,
+  key: "type" | "params"
+): unknown => {
+  try {
+    return (action as unknown as Record<string, unknown>)[key];
+  } catch {
+    return undefined;
+  }
+};
+
+const safeReadActionOutputField = (
+  actionOutput: ActionOutput,
+  key: keyof ActionOutput
+): unknown => {
+  try {
+    return (actionOutput as unknown as Record<string, unknown>)[key];
+  } catch {
+    return undefined;
+  }
+};
+
+const sanitizeActionCacheIdentifier = (value: string): string => {
+  if (value.length === 0) {
+    return value;
+  }
+  const withoutControlChars = Array.from(value, (char) => {
+    const code = char.charCodeAt(0);
+    return (code >= 0 && code < 32) || code === 127 ? " " : char;
+  }).join("");
+  return withoutControlChars.replace(/\s+/g, " ").trim();
+};
+
+const truncateActionCacheText = (value: string, maxChars: number): string => {
+  if (value.length <= maxChars) {
+    return value;
+  }
+  const omitted = value.length - maxChars;
+  return `${value.slice(0, maxChars)}... [truncated ${omitted} chars]`;
+};
+
+const normalizeActionCacheIdentifier = (
+  value: unknown,
+  fallback: string | null = null
+): string | null => {
+  if (typeof value !== "string") {
+    return fallback;
+  }
+  const normalized = sanitizeActionCacheIdentifier(value);
+  if (normalized.length === 0) {
+    return fallback;
+  }
+  return truncateActionCacheText(normalized, MAX_ACTION_CACHE_IDENTIFIER_CHARS);
+};
+
+const normalizeOptionalActionCacheText = (
+  value: unknown,
+  maxChars: number
+): string | undefined => {
+  if (typeof value !== "string") {
+    return undefined;
+  }
+  if (value.length === 0) {
+    return undefined;
+  }
+  return truncateActionCacheText(value, maxChars);
+};
+
+const formatActionCacheMessage = (value: unknown): string => {
+  const raw = typeof value === "string" ? value : formatUnknownError(value);
+  const normalized = sanitizeActionCacheIdentifier(raw);
+  if (normalized.length === 0) {
+    return "unknown error";
+  }
+  return truncateActionCacheText(normalized, MAX_ACTION_CACHE_MESSAGE_CHARS);
+};
 
 const normalizeXPath = (raw?: string | null): string | null => {
   if (!raw) {
@@ -23,19 +115,19 @@ const normalizeXPath = (raw?: string | null): string | null => {
   return raw.replace(TEXT_NODE_SUFFIX, "");
 };
 
+const getActionParamsRecord = (action: ActionType): Record<string, unknown> =>
+  isRecord(safeReadActionField(action, "params"))
+    ? (safeReadActionField(action, "params") as Record<string, unknown>)
+    : {};
+
 const extractInstruction = (action: ActionType): string | undefined => {
-  const params = action.params as Record<string, unknown>;
-  switch (action.type) {
+  const actionType = safeReadActionField(action, "type");
+  const params = getActionParamsRecord(action);
+  switch (actionType) {
     case "extract":
-      if (isString(params.objective)) {
-        return params.objective;
-      }
-      throw new Error(`Missing objective for extract action`);
+      return isString(params.objective) ? params.objective : undefined;
     case "actElement":
-      if (isString(params.instruction)) {
-        return params.instruction;
-      }
-      throw new Error(`Missing instruction for actElement action`);
+      return isString(params.instruction) ? params.instruction : undefined;
     default:
       // Actions like goToUrl, refreshPage, wait, analyzePdf do not require an instruction
       return isString(params.instruction) ? params.instruction : undefined;
@@ -43,7 +135,7 @@ const extractInstruction = (action: ActionType): string | undefined => {
 };
 
 const extractElementId = (action: ActionType): string | null => {
-  const params = action.params as Record<string, unknown>;
+  const params = getActionParamsRecord(action);
   if (isString(params.elementId)) {
     return params.elementId;
   }
@@ -51,7 +143,7 @@ const extractElementId = (action: ActionType): string | null => {
 };
 
 const extractMethod = (action: ActionType): string | null => {
-  const params = action.params as Record<string, unknown>;
+  const params = getActionParamsRecord(action);
   if (isString(params.method)) {
     return params.method;
   }
@@ -59,11 +151,21 @@ const extractMethod = (action: ActionType): string | null => {
 };
 
 const extractArguments = (action: ActionType): string[] => {
-  const params = action.params as Record<string, unknown>;
-  if (isStringOrNumberArray(params.arguments)) {
-    return params.arguments.map((item) => item.toString());
+  const params = getActionParamsRecord(action);
+  if (!Array.isArray(params.arguments)) {
+    return [];
+  }
+  const normalizedArgs: string[] = [];
+  for (const entry of params.arguments.slice(0, MAX_ACTION_CACHE_ARGUMENTS)) {
+    if (typeof entry !== "string" && typeof entry !== "number") {
+      return [];
+    }
+    const normalizedEntry = String(entry);
+    normalizedArgs.push(
+      truncateActionCacheText(normalizedEntry, MAX_ACTION_CACHE_ARGUMENT_CHARS)
+    );
   }
-  return [];
+  return normalizedArgs;
 };
 
 const extractFrameIndex = (elementId: string | null): number | null => {
@@ -80,18 +182,47 @@ const extractFrameIndex = (elementId: string | null): number | null => {
 };
 
 const extractXPathFromDebug = (actionOutput: ActionOutput): string | null => {
-  const debug = actionOutput.debug as Record<string, unknown> | undefined;
+  const debugValue = safeReadActionOutputField(actionOutput, "debug");
+  const debug = debugValue as Record<string, unknown> | undefined;
   if (!debug || typeof debug !== "object") {
     return null;
   }
 
-  const metadata = debug.elementMetadata as Record<string, unknown> | undefined;
-  if (metadata && isString(metadata.xpath)) {
-    return metadata.xpath;
+  const metadata = safeReadRecordField(
+    debug,
+    "elementMetadata"
+  ) as Record<string, unknown> | undefined;
+  const xpath = metadata ? safeReadRecordField(metadata, "xpath") : undefined;
+  if (isString(xpath)) {
+    return xpath;
   }
   return null;
 };
 
+const extractXPathFromDomState = (
+  domState: A11yDOMState,
+  encodedId: string | undefined
+): string | null => {
+  if (!encodedId) {
+    return null;
+  }
+  let xpathMap: unknown;
+  try {
+    xpathMap = domState.xpathMap;
+  } catch {
+    return null;
+  }
+  if (!xpathMap || typeof xpathMap !== "object") {
+    return null;
+  }
+  try {
+    const xpath = (xpathMap as Record<string, unknown>)[encodedId];
+    return isString(xpath) ? xpath : null;
+  } catch {
+    return null;
+  }
+};
+
 export const buildActionCacheEntry = ({
   stepIndex,
   action,
@@ -103,28 +234,42 @@ export const buildActionCacheEntry = ({
   actionOutput: ActionOutput;
   domState: A11yDOMState;
 }): ActionCacheEntry => {
-  const instruction = extractInstruction(action);
-  const elementId = extractElementId(action);
-  const method = extractMethod(action);
+  const actionTypeValue = safeReadActionField(action, "type");
+  const actionType =
+    normalizeActionCacheIdentifier(actionTypeValue, "unknown") ?? "unknown";
+  const instruction = normalizeOptionalActionCacheText(
+    extractInstruction(action),
+    MAX_ACTION_CACHE_INSTRUCTION_CHARS
+  );
+  const elementId = normalizeActionCacheIdentifier(extractElementId(action));
+  const method = normalizeActionCacheIdentifier(extractMethod(action));
   const args = extractArguments(action);
   const encodedId = elementId ? asEncodedId(elementId) : undefined;
   const frameIndex = extractFrameIndex(elementId);
 
   // Normalize goToUrl to use arguments[0] for URL to simplify replay paths
   let normalizedArgs = args;
+  const actionParamsValue = safeReadActionField(action, "params");
+  const actionParamsRecord = isRecord(actionParamsValue)
+    ? actionParamsValue
+    : undefined;
   if (
-    action.type === "goToUrl" &&
+    actionType === "goToUrl" &&
     (!args || args.length === 0) &&
-    action.params &&
-    typeof (action.params as any).url === "string"
+    typeof actionParamsRecord?.url === "string"
   ) {
-    normalizedArgs = [(action.params as any).url as string];
+    normalizedArgs = [actionParamsRecord.url];
   }
 
-  const xpathFromDom = encodedId ? domState.xpathMap?.[encodedId] || null : null;
+  const xpathFromDom = extractXPathFromDomState(domState, encodedId);
   const xpath = normalizeXPath(
-    xpathFromDom || extractXPathFromDebug(actionOutput)
+    normalizeOptionalActionCacheText(
+      xpathFromDom || extractXPathFromDebug(actionOutput),
+      MAX_ACTION_CACHE_XPATH_CHARS
+    ) ?? null
   );
+  const successValue = safeReadActionOutputField(actionOutput, "success");
+  const messageValue = safeReadActionOutputField(actionOutput, "message");
 
   return {
     stepIndex,
@@ -132,11 +277,11 @@ export const buildActionCacheEntry = ({
     elementId,
     method,
     arguments: normalizedArgs,
-    actionParams: (action.params as Record<string, unknown>) || undefined,
+    actionParams: actionParamsRecord,
     frameIndex,
     xpath,
-    actionType: action.type,
-    success: actionOutput.success,
-    message: actionOutput.message,
+    actionType,
+    success: typeof successValue === "boolean" ? successValue : false,
+    message: formatActionCacheMessage(messageValue),
   };
 };
diff --git a/src/agent/shared/action-restrictions.ts b/src/agent/shared/action-restrictions.ts
index e536d172..c110bf95 100644
--- a/src/agent/shared/action-restrictions.ts
+++ b/src/agent/shared/action-restrictions.ts
@@ -6,6 +6,7 @@ import type { CDPActionMethod } from "@/cdp";
  */
 
 export type AiActionAllowedAction = (typeof AIACTION_ALLOWED_ACTIONS)[number];
+export type PerformAllowedAction = (typeof PERFORM_ALLOWED_ACTIONS)[number];
 
 /**
  * Actions allowed for agent-driven element interactions (actElement)
@@ -14,7 +15,7 @@ export type AiActionAllowedAction = (typeof AIACTION_ALLOWED_ACTIONS)[number];
  * Agent actions use fewer retries (3) because the agent loop itself
  * provides higher-level retry and error recovery logic.
  *
- * Currently uses the same action set as aiAction.
+ * Currently uses the same action set as page.perform.
  */
 export const AGENT_ELEMENT_ACTIONS = [
   // Click actions
@@ -43,10 +44,15 @@ export const AGENT_ELEMENT_ACTIONS = [
 ] as const satisfies readonly CDPActionMethod[];
 
 /**
- * Actions allowed for aiAction (executeSingleAction)
+ * Actions allowed for page.perform (executeSingleAction)
  * Mirrors AGENT_ELEMENT_ACTIONS because both flows support the same action set.
  */
-export const AIACTION_ALLOWED_ACTIONS = AGENT_ELEMENT_ACTIONS;
+export const PERFORM_ALLOWED_ACTIONS = AGENT_ELEMENT_ACTIONS;
+
+/**
+ * @deprecated Use PERFORM_ALLOWED_ACTIONS instead.
+ */
+export const AIACTION_ALLOWED_ACTIONS = PERFORM_ALLOWED_ACTIONS;
 
 export type AgentElementAction = (typeof AGENT_ELEMENT_ACTIONS)[number];
 
diff --git a/src/agent/shared/dom-capture.test.ts b/src/agent/shared/dom-capture.test.ts
new file mode 100644
index 00000000..4585b663
--- /dev/null
+++ b/src/agent/shared/dom-capture.test.ts
@@ -0,0 +1,188 @@
+import type { Page } from "playwright-core";
+import { captureDOMState } from "@/agent/shared/dom-capture";
+
+jest.mock("@/context-providers/a11y-dom", () => ({
+  getA11yDOM: jest.fn(),
+}));
+
+jest.mock("@/utils/waitForSettledDOM", () => ({
+  waitForSettledDOM: jest.fn(),
+}));
+
+const { getA11yDOM } = jest.requireMock(
+  "@/context-providers/a11y-dom"
+) as {
+  getA11yDOM: jest.Mock;
+};
+
+const { waitForSettledDOM } = jest.requireMock(
+  "@/utils/waitForSettledDOM"
+) as {
+  waitForSettledDOM: jest.Mock;
+};
+
+function createPage(): Page {
+  return {} as Page;
+}
+
+function createDomState(overrides?: Partial<Record<string, unknown>>) {
+  return {
+    elements: new Map([["0-1", { name: "button" }]]),
+    domState: "dom tree",
+    xpathMap: { "0-1": "//button[1]" },
+    backendNodeMap: { "0-1": 111 },
+    ...overrides,
+  };
+}
+
+describe("captureDOMState", () => {
+  beforeEach(() => {
+    jest.clearAllMocks();
+    waitForSettledDOM.mockResolvedValue(undefined);
+  });
+
+  it("retries recoverable DOM errors and succeeds", async () => {
+    getA11yDOM
+      .mockRejectedValueOnce(new Error("Execution context was destroyed"))
+      .mockResolvedValueOnce(createDomState());
+
+    const result = await captureDOMState(createPage(), { maxRetries: 2 });
+
+    expect(result.domState).toBe("dom tree");
+    expect(getA11yDOM).toHaveBeenCalledTimes(2);
+    expect(waitForSettledDOM).toHaveBeenCalledWith(
+      expect.anything(),
+      undefined,
+      expect.objectContaining({
+        filterAdTrackingFrames: undefined,
+      })
+    );
+  });
+
+  it("forwards filterAdTrackingFrames option to DOM capture and retry waits", async () => {
+    getA11yDOM
+      .mockRejectedValueOnce(new Error("Execution context was destroyed"))
+      .mockResolvedValueOnce(createDomState());
+
+    const page = createPage();
+    await captureDOMState(page, {
+      maxRetries: 2,
+      filterAdTrackingFrames: false,
+    });
+
+    const domOptions = getA11yDOM.mock.calls[0]?.[4] as
+      | { filterAdTrackingFrames?: boolean }
+      | undefined;
+    expect(domOptions?.filterAdTrackingFrames).toBe(false);
+    expect(waitForSettledDOM).toHaveBeenCalledWith(
+      page,
+      undefined,
+      expect.objectContaining({
+        filterAdTrackingFrames: false,
+      })
+    );
+  });
+
+  it("throws immediately for non-recoverable errors", async () => {
+    getA11yDOM.mockRejectedValue(new Error("fatal capture failure"));
+
+    await expect(captureDOMState(createPage(), { maxRetries: 3 })).rejects.toThrow(
+      "fatal capture failure"
+    );
+    expect(getA11yDOM).toHaveBeenCalledTimes(1);
+    expect(waitForSettledDOM).toHaveBeenCalledTimes(0);
+  });
+
+  it("normalizes invalid maxRetries values to default attempts", async () => {
+    getA11yDOM.mockResolvedValue(
+      createDomState({
+        elements: new Map(),
+        domState: "Error: Could not extract accessibility tree",
+      })
+    );
+
+    await expect(captureDOMState(createPage(), { maxRetries: 0 })).rejects.toThrow(
+      "Error: Could not extract accessibility tree"
+    );
+    expect(getA11yDOM).toHaveBeenCalledTimes(3);
+  });
+
+  it("ignores onFrameChunk callback errors while streaming", async () => {
+    getA11yDOM.mockImplementation(
+      async (
+        _page: Page,
+        _debug: boolean,
+        _enableVisualMode: boolean,
+        _debugStepDir: string | undefined,
+        options?: { onFrameChunk?: (chunk: { order: number; simplified: string }) => void }
+      ) => {
+        options?.onFrameChunk?.({ order: 0, simplified: " streamed chunk " });
+        return createDomState({
+          elements: new Map([["0-1", { name: "button" }]]),
+          domState: "fallback",
+        });
+      }
+    );
+
+    const warnSpy = jest.spyOn(console, "warn").mockImplementation(() => {});
+    const logSpy = jest.spyOn(console, "log").mockImplementation(() => {});
+    try {
+      const result = await captureDOMState(createPage(), {
+        enableStreaming: true,
+        onFrameChunk: () => {
+          throw new Error("stream callback trap");
+        },
+        debug: true,
+      });
+
+      expect(result.domState).toBe("streamed chunk");
+      expect(getA11yDOM).toHaveBeenCalledTimes(1);
+      expect(warnSpy).toHaveBeenCalledWith(
+        "[DOM] onFrameChunk callback failed: stream callback trap"
+      );
+    } finally {
+      warnSpy.mockRestore();
+      logSpy.mockRestore();
+    }
+  });
+
+  it("sanitizes and truncates onFrameChunk callback diagnostics", async () => {
+    getA11yDOM.mockImplementation(
+      async (
+        _page: Page,
+        _debug: boolean,
+        _enableVisualMode: boolean,
+        _debugStepDir: string | undefined,
+        options?: { onFrameChunk?: (chunk: { order: number; simplified: string }) => void }
+      ) => {
+        options?.onFrameChunk?.({ order: 0, simplified: " streamed chunk " });
+        return createDomState({
+          elements: new Map([["0-1", { name: "button" }]]),
+          domState: "fallback",
+        });
+      }
+    );
+
+    const warnSpy = jest.spyOn(console, "warn").mockImplementation(() => {});
+    const logSpy = jest.spyOn(console, "log").mockImplementation(() => {});
+    try {
+      const result = await captureDOMState(createPage(), {
+        enableStreaming: true,
+        onFrameChunk: () => {
+          throw new Error(`stream\u0000\n${"x".repeat(10_000)}`);
+        },
+        debug: true,
+      });
+
+      expect(result.domState).toBe("streamed chunk");
+      const diagnostic = String(warnSpy.mock.calls[0]?.[0] ?? "");
+      expect(diagnostic).toContain("[truncated");
+      expect(diagnostic).not.toContain("\u0000");
+      expect(diagnostic).not.toContain("\n");
+      expect(diagnostic.length).toBeLessThan(700);
+    } finally {
+      warnSpy.mockRestore();
+      logSpy.mockRestore();
+    }
+  });
+});
diff --git a/src/agent/shared/dom-capture.ts b/src/agent/shared/dom-capture.ts
index e1939e24..c2d48996 100644
--- a/src/agent/shared/dom-capture.ts
+++ b/src/agent/shared/dom-capture.ts
@@ -6,6 +6,7 @@ import {
   type A11yDOMState,
 } from "@/context-providers/a11y-dom";
 import type { FrameChunkEvent } from "@/context-providers/a11y-dom/types";
+import { formatUnknownError } from "@/utils";
 import { waitForSettledDOM } from "@/utils/waitForSettledDOM";
 
 const DOM_CAPTURE_MAX_ATTEMPTS = 3;
@@ -23,6 +24,37 @@ export interface CaptureDOMOptions {
   enableStreaming?: boolean;
   onFrameChunk?: (chunk: FrameChunkEvent) => void;
   maxRetries?: number;
+  filterAdTrackingFrames?: boolean;
+}
+
+const MAX_DOM_CAPTURE_RETRIES = 10;
+const MAX_DOM_CAPTURE_DIAGNOSTIC_CHARS = 400;
+
+function sanitizeDomCaptureText(value: string): string {
+  if (value.length === 0) {
+    return value;
+  }
+  const withoutControlChars = Array.from(value, (char) => {
+    const code = char.charCodeAt(0);
+    return (code >= 0 && code < 32) || code === 127 ? " " : char;
+  }).join("");
+  return withoutControlChars.replace(/\s+/g, " ").trim();
+}
+
+function truncateDomCaptureDiagnostic(value: string): string {
+  if (value.length <= MAX_DOM_CAPTURE_DIAGNOSTIC_CHARS) {
+    return value;
+  }
+  const omittedChars = value.length - MAX_DOM_CAPTURE_DIAGNOSTIC_CHARS;
+  return `${value.slice(0, MAX_DOM_CAPTURE_DIAGNOSTIC_CHARS)}... [truncated ${omittedChars} chars]`;
+}
+
+function formatDomCaptureDiagnostic(value: unknown): string {
+  const normalized = sanitizeDomCaptureText(formatUnknownError(value));
+  if (normalized.length === 0) {
+    return "unknown callback error";
+  }
+  return truncateDomCaptureDiagnostic(normalized);
 }
 
 class DomChunkAggregator {
@@ -64,11 +96,17 @@ const isRecoverableDomError = (error: unknown): boolean => {
 };
 
 const isPlaceholderSnapshot = (snapshot: A11yDOMState): boolean => {
-  if (snapshot.elements.size > 0) return false;
-  return (
-    typeof snapshot.domState === "string" &&
-    snapshot.domState.startsWith("Error: Could not extract accessibility tree")
-  );
+  try {
+    if (!snapshot || typeof snapshot !== "object") return false;
+    if (!(snapshot.elements instanceof Map)) return false;
+    if (snapshot.elements.size > 0) return false;
+    return (
+      typeof snapshot.domState === "string" &&
+      snapshot.domState.startsWith("Error: Could not extract accessibility tree")
+    );
+  } catch {
+    return false;
+  }
 };
 
 function logPerf(
@@ -97,12 +135,19 @@ export async function captureDOMState(
     enableStreaming = false,
     onFrameChunk,
     maxRetries = DOM_CAPTURE_MAX_ATTEMPTS,
+    filterAdTrackingFrames,
   } = options;
+  const normalizedMaxRetries =
+    typeof maxRetries === "number" &&
+    Number.isFinite(maxRetries) &&
+    maxRetries > 0
+      ? Math.min(Math.floor(maxRetries), MAX_DOM_CAPTURE_RETRIES)
+      : DOM_CAPTURE_MAX_ATTEMPTS;
 
   let lastError: unknown;
   const domFetchStart = performance.now();
 
-  for (let attempt = 0; attempt < maxRetries; attempt++) {
+  for (let attempt = 0; attempt < normalizedMaxRetries; attempt++) {
     const attemptAggregator = enableStreaming
       ? new DomChunkAggregator()
       : null;
@@ -116,10 +161,22 @@ export async function captureDOMState(
         {
           useCache,
           enableStreaming,
+          filterAdTrackingFrames,
           onFrameChunk: attemptAggregator
             ? (chunk) => {
                 attemptAggregator.push(chunk);
-                onFrameChunk?.(chunk);
+                if (!onFrameChunk) return;
+                try {
+                  onFrameChunk(chunk);
+                } catch (error) {
+                  if (debug) {
+                    console.warn(
+                      `[DOM] onFrameChunk callback failed: ${formatDomCaptureDiagnostic(
+                        error
+                      )}`
+                    );
+                  }
+                }
               }
             : undefined,
         }
@@ -132,7 +189,6 @@ export async function captureDOMState(
       if (isPlaceholderSnapshot(snapshot)) {
         lastError = new Error(snapshot.domState);
       } else {
-        const domDuration = performance.now() - domFetchStart;
         logPerf(debug, `[Perf][captureDOMState] success (attempt ${attempt + 1})`, domFetchStart);
         
         // If we were streaming, update the full string in the snapshot
@@ -151,14 +207,19 @@ export async function captureDOMState(
 
     if (debug) {
       console.warn(
-        `[DOM] Capture failed (attempt ${attempt + 1}/${maxRetries}), waiting for navigation to settle...`
+        `[DOM] Capture failed (attempt ${attempt + 1}/${normalizedMaxRetries}), waiting for navigation to settle...`
       );
     }
     
     // Wait for DOM to settle before next retry
-    await waitForSettledDOM(page).catch(() => {});
+    await waitForSettledDOM(page, undefined, {
+      filterAdTrackingFrames,
+    }).catch(() => {});
   }
 
-  throw lastError ?? new Error(`Failed to capture DOM state after ${maxRetries} attempts`);
+  throw (
+    lastError ??
+    new Error(`Failed to capture DOM state after ${normalizedMaxRetries} attempts`)
+  );
 }
 
diff --git a/src/agent/shared/element-locator.test.ts b/src/agent/shared/element-locator.test.ts
new file mode 100644
index 00000000..2312c63e
--- /dev/null
+++ b/src/agent/shared/element-locator.test.ts
@@ -0,0 +1,416 @@
+import { getElementLocator } from "@/agent/shared/element-locator";
+
+jest.mock("@/context-providers/a11y-dom", () => {
+  const actual = jest.requireActual("@/context-providers/a11y-dom");
+  return {
+    ...actual,
+    toEncodedId: jest.fn((value: string) => value),
+    resolveFrameByXPath: jest.fn(),
+  };
+});
+
+const { toEncodedId, resolveFrameByXPath } = jest.requireMock(
+  "@/context-providers/a11y-dom"
+) as {
+  toEncodedId: jest.Mock;
+  resolveFrameByXPath: jest.Mock;
+};
+
+function createPage(overrides?: Record<string, unknown>) {
+  return {
+    locator: jest.fn((selector: string) => ({ selector })),
+    frames: jest.fn(() => []),
+    ...overrides,
+  } as unknown as import("playwright-core").Page;
+}
+
+describe("getElementLocator", () => {
+  beforeEach(() => {
+    jest.clearAllMocks();
+  });
+
+  it("resolves main-frame locator and normalizes xpath", async () => {
+    const page = createPage();
+    toEncodedId.mockReturnValue("0-10");
+
+    const result = await getElementLocator(
+      "0-10",
+      {
+        "0-10": "  //button[1]/text()  ",
+      },
+      page
+    );
+
+    expect((page.locator as jest.Mock)).toHaveBeenCalledWith("xpath=//button[1]");
+    expect(result.xpath).toBe("//button[1]");
+  });
+
+  it("rejects empty element IDs", async () => {
+    const page = createPage();
+
+    await expect(
+      getElementLocator(
+        "   ",
+        {},
+        page
+      )
+    ).rejects.toThrow("Element ID must be a non-empty string");
+  });
+
+  it("throws readable error when xpath map access traps throw", async () => {
+    const page = createPage();
+    toEncodedId.mockReturnValue("0-10");
+    const xpathMap = new Proxy(
+      {},
+      {
+        get: (_target, prop) => {
+          if (prop === "0-10") {
+            throw new Error("xpath map trap");
+          }
+          return undefined;
+        },
+      }
+    );
+
+    await expect(
+      getElementLocator(
+        "0-10",
+        xpathMap as unknown as Record<string, string>,
+        page
+      )
+    ).rejects.toThrow("Element lookup failed for 0-10: xpath map trap");
+  });
+
+  it("reuses first lookup value in debug path when map getter becomes trap-prone", async () => {
+    const errorSpy = jest.spyOn(console, "error").mockImplementation(() => {});
+    const page = createPage();
+    toEncodedId.mockReturnValue("0-10");
+    let readCount = 0;
+    const xpathMap = new Proxy(
+      {},
+      {
+        get: (_target, prop) => {
+          if (prop !== "0-10") {
+            return undefined;
+          }
+          readCount += 1;
+          if (readCount > 1) {
+            throw new Error("second lookup trap");
+          }
+          return undefined;
+        },
+      }
+    );
+
+    try {
+      await expect(
+        getElementLocator(
+          "0-10",
+          xpathMap as unknown as Record<string, string>,
+          page,
+          undefined,
+          true
+        )
+      ).rejects.toThrow("Element 0-10 not found in xpath map");
+    } finally {
+      errorSpy.mockRestore();
+    }
+  });
+
+  it("truncates oversized xpath-map trap diagnostics", async () => {
+    const page = createPage();
+    toEncodedId.mockReturnValue("0-10");
+    const xpathMap = new Proxy(
+      {},
+      {
+        get: (_target, prop) => {
+          if (prop === "0-10") {
+            throw new Error(`x${"y".repeat(2_000)}\nxpath trap`);
+          }
+          return undefined;
+        },
+      }
+    );
+
+    await expect(
+      getElementLocator(
+        "0-10",
+        xpathMap as unknown as Record<string, string>,
+        page
+      )
+    ).rejects.toThrow(/\[truncated/);
+  });
+
+  it("sanitizes oversized element identifiers in lookup failures", async () => {
+    const page = createPage();
+    const oversizedElementId = `id-${"x".repeat(300)}\nunsafe`;
+    toEncodedId.mockReturnValue("0-10");
+
+    await expect(
+      getElementLocator(oversizedElementId, {}, page)
+    ).rejects.toThrow(/\[truncated/);
+  });
+
+  it("throws readable error when frame-map lookup traps throw", async () => {
+    const page = createPage();
+    toEncodedId.mockReturnValue("1-10");
+    const frameMap = new Proxy(new Map<number, unknown>(), {
+      get: (target, prop, receiver) => {
+        if (prop === "has") {
+          return () => {
+            throw new Error("frame has trap");
+          };
+        }
+        return Reflect.get(target, prop, receiver);
+      },
+    }) as unknown as Map<number, never>;
+
+    await expect(
+      getElementLocator(
+        "1-10",
+        { "1-10": "//button[1]" },
+        page,
+        frameMap
+      )
+    ).rejects.toThrow("Frame metadata lookup failed for frame 1: frame has trap");
+  });
+
+  it("throws readable error when iframe resolution throws", async () => {
+    const page = createPage();
+    toEncodedId.mockReturnValue("1-10");
+    resolveFrameByXPath.mockRejectedValue(new Error("frame resolution failed"));
+    const frameMap = new Map<number, unknown>([
+      [1, { xpath: "//iframe[1]" }],
+    ]) as unknown as Map<number, never>;
+
+    await expect(
+      getElementLocator(
+        "1-10",
+        { "1-10": "//button[1]" },
+        page,
+        frameMap
+      )
+    ).rejects.toThrow(
+      "Could not resolve frame for element 1-10 (frameIndex: 1): frame resolution failed"
+    );
+  });
+
+  it("continues when iframe waitForLoadState times out", async () => {
+    const frame = {
+      waitForLoadState: jest.fn().mockRejectedValue(new Error("timeout")),
+      locator: jest.fn((selector: string) => ({ selector })),
+      url: jest.fn(() => "https://frame.example"),
+      name: jest.fn(() => "frame-1"),
+    };
+    const page = createPage({
+      frames: jest.fn(() => [frame]),
+    });
+    toEncodedId.mockReturnValue("1-10");
+    resolveFrameByXPath.mockResolvedValue(frame);
+    const frameMap = new Map<number, unknown>([
+      [1, { xpath: "//iframe[1]" }],
+    ]) as unknown as Map<number, never>;
+
+    const result = await getElementLocator(
+      "1-10",
+      { "1-10": "//button[1]" },
+      page,
+      frameMap
+    );
+
+    expect(frame.waitForLoadState).toHaveBeenCalledWith("domcontentloaded", {
+      timeout: 5000,
+    });
+    expect(frame.locator).toHaveBeenCalledWith("xpath=//button[1]");
+    expect(result.xpath).toBe("//button[1]");
+  });
+
+  it("keeps debug logging resilient when frame metadata access traps throw", async () => {
+    const logSpy = jest.spyOn(console, "log").mockImplementation(() => {});
+    const errorSpy = jest.spyOn(console, "error").mockImplementation(() => {});
+    const warnSpy = jest.spyOn(console, "warn").mockImplementation(() => {});
+    const frame = {
+      waitForLoadState: jest.fn().mockResolvedValue(undefined),
+      locator: jest.fn((selector: string) => ({ selector })),
+      url: jest.fn(() => {
+        throw new Error("frame url trap");
+      }),
+      name: jest.fn(() => {
+        throw new Error("frame name trap");
+      }),
+    };
+    const page = createPage({
+      frames: jest.fn(() => [frame]),
+    });
+    toEncodedId.mockReturnValue("1-10");
+    resolveFrameByXPath.mockResolvedValue(frame);
+    const frameMap = new Map<number, unknown>([
+      [1, { xpath: "//iframe[1]" }],
+    ]) as unknown as Map<number, never>;
+
+    try {
+      const result = await getElementLocator(
+        "1-10",
+        { "1-10": "//button[1]" },
+        page,
+        frameMap,
+        true
+      );
+      expect(result.xpath).toBe("//button[1]");
+      expect(frame.locator).toHaveBeenCalledWith("xpath=//button[1]");
+    } finally {
+      logSpy.mockRestore();
+      errorSpy.mockRestore();
+      warnSpy.mockRestore();
+    }
+  });
+
+  it("sanitizes and truncates unresolved-frame debug payload logs", async () => {
+    const errorSpy = jest.spyOn(console, "error").mockImplementation(() => {});
+    const page = createPage({
+      frames: jest.fn(() => [
+        {
+          url: () => `https://example.com/\u0000\n${"x".repeat(2_000)}`,
+          name: () => `frame\u0000\n${"y".repeat(2_000)}`,
+        },
+      ]),
+    });
+    toEncodedId.mockReturnValue("1-10");
+    resolveFrameByXPath.mockResolvedValue(null);
+    const frameMap = new Map<number, unknown>([
+      [
+        1,
+        {
+          src: `https://frame.example/\u0000\n${"x".repeat(2_000)}`,
+          name: `name\u0000\n${"y".repeat(2_000)}`,
+          xpath: "//iframe[1]",
+          parentFrameIndex: 0,
+        },
+      ],
+    ]) as unknown as Map<number, never>;
+
+    try {
+      await expect(
+        getElementLocator(
+          "1-10",
+          { "1-10": "//button[1]" },
+          page,
+          frameMap,
+          true
+        )
+      ).rejects.toThrow("Could not resolve frame for element 1-10");
+
+      const payloadLogs = errorSpy.mock.calls
+        .map((call) => String(call[0] ?? ""))
+        .filter((entry) =>
+          entry.includes("Frame info:") || entry.includes("Available frames:")
+        );
+      expect(payloadLogs.length).toBeGreaterThanOrEqual(2);
+      for (const logLine of payloadLogs) {
+        expect(logLine).toContain("[truncated");
+        expect(logLine).not.toContain("\u0000");
+        expect(logLine).not.toContain("\n");
+      }
+    } finally {
+      errorSpy.mockRestore();
+    }
+  });
+
+  it("keeps readable frame metadata when one frame entry getter traps", async () => {
+    const errorSpy = jest.spyOn(console, "error").mockImplementation(() => {});
+    const frames = new Proxy(
+      [
+        {},
+        {
+          url: () => "https://example.com/good-frame",
+          name: () => "good-frame",
+        },
+      ],
+      {
+        get: (target, prop, receiver) => {
+          if (prop === "0") {
+            throw new Error("frame entry trap");
+          }
+          return Reflect.get(target, prop, receiver);
+        },
+      }
+    );
+    const page = createPage({
+      frames: jest.fn(() => frames),
+    });
+    toEncodedId.mockReturnValue("1-10");
+    resolveFrameByXPath.mockResolvedValue(null);
+    const frameMap = new Map<number, unknown>([
+      [
+        1,
+        {
+          src: "https://frame.example",
+          name: "frame-name",
+          xpath: "//iframe[1]",
+          parentFrameIndex: 0,
+        },
+      ],
+    ]) as unknown as Map<number, never>;
+
+    try {
+      await expect(
+        getElementLocator("1-10", { "1-10": "//button[1]" }, page, frameMap, true)
+      ).rejects.toThrow("Could not resolve frame for element 1-10");
+
+      const availableFramesLine = String(
+        errorSpy.mock.calls.find((call) =>
+          String(call[0] ?? "").includes("Available frames:")
+        )?.[0] ?? ""
+      );
+      expect(availableFramesLine).toContain("https://example.com/good-frame");
+    } finally {
+      errorSpy.mockRestore();
+    }
+  });
+
+  it("reads frame metadata with frame receiver binding", async () => {
+    const errorSpy = jest.spyOn(console, "error").mockImplementation(() => {});
+    const frameWithReceiverState = {
+      frameUrl: "https://example.com/receiver-frame",
+      frameName: "receiver-frame",
+      url(this: { frameUrl: string }) {
+        return this.frameUrl;
+      },
+      name(this: { frameName: string }) {
+        return this.frameName;
+      },
+    };
+    const page = createPage({
+      frames: jest.fn(() => [frameWithReceiverState]),
+    });
+    toEncodedId.mockReturnValue("1-10");
+    resolveFrameByXPath.mockResolvedValue(null);
+    const frameMap = new Map<number, unknown>([
+      [
+        1,
+        {
+          src: "https://frame.example",
+          name: "frame-name",
+          xpath: "//iframe[1]",
+          parentFrameIndex: 0,
+        },
+      ],
+    ]) as unknown as Map<number, never>;
+
+    try {
+      await expect(
+        getElementLocator("1-10", { "1-10": "//button[1]" }, page, frameMap, true)
+      ).rejects.toThrow("Could not resolve frame for element 1-10");
+
+      const availableFramesLine = String(
+        errorSpy.mock.calls.find((call) =>
+          String(call[0] ?? "").includes("Available frames:")
+        )?.[0] ?? ""
+      );
+      expect(availableFramesLine).toContain("https://example.com/receiver-frame");
+      expect(availableFramesLine).toContain("receiver-frame");
+    } finally {
+      errorSpy.mockRestore();
+    }
+  });
+});
diff --git a/src/agent/shared/element-locator.ts b/src/agent/shared/element-locator.ts
index ba4c1098..601ebb02 100644
--- a/src/agent/shared/element-locator.ts
+++ b/src/agent/shared/element-locator.ts
@@ -1,6 +1,6 @@
 /**
  * Shared utility for getting Playwright locators from encoded element IDs
- * Extracted from HyperAgent for reusability across aiAction and agent actions
+ * Extracted from HyperAgent for reusability across page.perform and agent actions
  */
 
 import type { Page } from "playwright-core";
@@ -10,6 +10,160 @@ import {
   resolveFrameByXPath,
 } from "../../context-providers/a11y-dom";
 import { HyperagentError } from "../error";
+import { formatUnknownError } from "@/utils";
+
+const MAX_ELEMENT_LOCATOR_DIAGNOSTIC_CHARS = 400;
+const MAX_ELEMENT_LOCATOR_IDENTIFIER_CHARS = 128;
+const MAX_ELEMENT_LOCATOR_DEBUG_CHARS = 600;
+const MAX_ELEMENT_LOCATOR_DEBUG_FRAMES = 20;
+
+function sanitizeElementLocatorText(value: string): string {
+  if (value.length === 0) {
+    return value;
+  }
+  const withoutControlChars = Array.from(value, (char) => {
+    const code = char.charCodeAt(0);
+    return (code >= 0 && code < 32) || code === 127 ? " " : char;
+  }).join("");
+  return withoutControlChars.replace(/\s+/g, " ").trim();
+}
+
+function truncateElementLocatorText(value: string, maxChars: number): string {
+  if (value.length <= maxChars) {
+    return value;
+  }
+  const omitted = value.length - maxChars;
+  return `${value.slice(0, maxChars)}... [truncated ${omitted} chars]`;
+}
+
+function formatElementLocatorDiagnostic(value: unknown): string {
+  const normalized = sanitizeElementLocatorText(formatUnknownError(value));
+  const fallback = normalized.length > 0 ? normalized : "unknown error";
+  return truncateElementLocatorText(
+    fallback,
+    MAX_ELEMENT_LOCATOR_DIAGNOSTIC_CHARS
+  );
+}
+
+function formatElementLocatorIdentifier(value: unknown, fallback: string): string {
+  if (typeof value !== "string") {
+    return fallback;
+  }
+  const normalized = sanitizeElementLocatorText(value);
+  if (normalized.length === 0) {
+    return fallback;
+  }
+  return truncateElementLocatorText(
+    normalized,
+    MAX_ELEMENT_LOCATOR_IDENTIFIER_CHARS
+  );
+}
+
+function formatElementLocatorDebug(value: unknown, fallback: string): string {
+  const seen = new WeakSet<object>();
+  const raw = (() => {
+    if (typeof value === "string") {
+      return value;
+    }
+    try {
+      const serialized = JSON.stringify(value, (_key, candidate: unknown) => {
+        if (typeof candidate === "bigint") {
+          return `${candidate.toString()}n`;
+        }
+        if (typeof candidate === "object" && candidate !== null) {
+          if (seen.has(candidate)) {
+            return "[Circular]";
+          }
+          seen.add(candidate);
+        }
+        return candidate;
+      });
+      return typeof serialized === "string" ? serialized : fallback;
+    } catch {
+      return fallback;
+    }
+  })();
+  const normalized = sanitizeElementLocatorText(raw);
+  const safeFallback = fallback.trim().length > 0 ? fallback : "unavailable";
+  if (normalized.length === 0) {
+    return safeFallback;
+  }
+  return truncateElementLocatorText(normalized, MAX_ELEMENT_LOCATOR_DEBUG_CHARS);
+}
+
+function safeReadFrameText(
+  frame: unknown,
+  methodName: "url" | "name",
+  fallback: string
+): string {
+  if (!frame || (typeof frame !== "object" && typeof frame !== "function")) {
+    return fallback;
+  }
+  try {
+    const method = (frame as Record<string, unknown>)[methodName];
+    if (typeof method !== "function") {
+      return fallback;
+    }
+    const value = (method as (this: unknown) => unknown).call(frame);
+    return formatElementLocatorIdentifier(value, fallback);
+  } catch {
+    return fallback;
+  }
+}
+
+function safeFrameMetadata(frame: unknown): { url: string; name: string } {
+  return {
+    url: safeReadFrameText(frame, "url", "about:blank (url unavailable)"),
+    name: safeReadFrameText(frame, "name", "(name unavailable)"),
+  };
+}
+
+function safeArrayLength(value: unknown): number {
+  try {
+    if (Array.isArray(value)) {
+      return value.length;
+    }
+    if (value && typeof value === "object") {
+      const length = (value as { length?: unknown }).length;
+      if (typeof length === "number" && Number.isFinite(length) && length >= 0) {
+        return Math.floor(length);
+      }
+    }
+  } catch {
+    // ignore trap-prone length access
+  }
+  return 0;
+}
+
+function safeReadArrayItem(value: unknown, index: number): unknown {
+  if (!value || typeof value !== "object") {
+    return undefined;
+  }
+  try {
+    return (value as Record<number, unknown>)[index];
+  } catch {
+    return undefined;
+  }
+}
+
+function safeListFrameMetadata(page: Page): Array<{ url: string; name: string }> {
+  try {
+    const frames = page.frames();
+    const frameCount = safeArrayLength(frames);
+    const limit = Math.min(frameCount, MAX_ELEMENT_LOCATOR_DEBUG_FRAMES);
+    const metadata: Array<{ url: string; name: string }> = [];
+    for (let i = 0; i < limit; i++) {
+      const frame = safeReadArrayItem(frames, i);
+      if (!frame) {
+        continue;
+      }
+      metadata.push(safeFrameMetadata(frame));
+    }
+    return metadata;
+  } catch {
+    return [];
+  }
+}
 
 /**
  * Get a Playwright locator for an element by its encoded ID
@@ -31,38 +185,95 @@ export async function getElementLocator(
   frameMap?: Map<number, IframeInfo>,
   debug = false
 ): Promise<{ locator: ReturnType<Page["locator"]>; xpath: string }> {
+  const normalizedElementId =
+    typeof elementId === "string" ? elementId.trim() : "";
+  if (normalizedElementId.length === 0) {
+    throw new HyperagentError("Element ID must be a non-empty string", 400);
+  }
+  const safeElementId = formatElementLocatorIdentifier(
+    normalizedElementId,
+    "unknown-element"
+  );
+
   // Convert elementId to EncodedId format for xpath lookup
-  const encodedId = toEncodedId(elementId);
-  const rawXpath = xpathMap[encodedId];
+  let encodedId: string;
+  try {
+    encodedId = toEncodedId(normalizedElementId);
+  } catch (error) {
+    throw new HyperagentError(
+      `Failed to normalize element ID "${safeElementId}": ${formatElementLocatorDiagnostic(
+        error
+      )}`,
+      400
+    );
+  }
+  let rawXpath: unknown;
+  try {
+    rawXpath = xpathMap[encodedId];
+  } catch (error) {
+    throw new HyperagentError(
+      `Element lookup failed for ${safeElementId}: ${formatElementLocatorDiagnostic(
+        error
+      )}`,
+      500
+    );
+  }
 
-  if (!rawXpath) {
-    const errorMsg = `Element ${elementId} not found in xpath map`;
+  if (typeof rawXpath !== "string" || rawXpath.trim().length === 0) {
+    const errorMsg = `Element ${safeElementId} not found in xpath map`;
     if (debug) {
       console.error(`[getElementLocator] ${errorMsg}`);
       console.error(
-        `[getElementLocator] Looking for element with ID: ${elementId} (type: ${typeof elementId})`
+        `[getElementLocator] Looking for element with ID: ${normalizedElementId} (type: ${typeof normalizedElementId})`
       );
       console.error(
-        `[getElementLocator] Direct lookup result:`,
-        xpathMap[encodedId]
+        `[getElementLocator] Direct lookup result: ${formatElementLocatorDebug(
+          rawXpath,
+          "undefined"
+        )}`
       );
     }
     throw new HyperagentError(errorMsg, 404);
   }
 
   // Trim trailing text nodes from xpath
-  const xpath = rawXpath.replace(/\/text\(\)(\[\d+\])?$/iu, "");
+  const xpath = rawXpath
+    .trim()
+    .replace(/\/text\(\)(\[\d+\])?$/iu, "")
+    .trim();
 
   // Extract frameIndex from encodedId (format: "frameIndex-nodeIndex")
   const [frameIndexStr] = encodedId.split("-");
   const frameIndex = parseInt(frameIndexStr!, 10);
+  if (!Number.isFinite(frameIndex) || frameIndex < 0) {
+    const safeEncodedId = formatElementLocatorIdentifier(
+      encodedId,
+      "unknown-encoded-id"
+    );
+    throw new HyperagentError(
+      `Invalid frame index in encoded element ID "${safeEncodedId}"`,
+      400
+    );
+  }
 
   // Main frame (frameIndex 0) - use page.locator()
   if (frameIndex === 0) {
     return { locator: page.locator(`xpath=${xpath}`), xpath };
   }
 
-  if (!frameMap || !frameMap.has(frameIndex)) {
+  let hasFrameMetadata = false;
+  try {
+    hasFrameMetadata = Boolean(frameMap?.has(frameIndex));
+  } catch (error) {
+    throw new HyperagentError(
+      `Frame metadata lookup failed for frame ${frameIndex}: ${formatElementLocatorDiagnostic(
+        error
+      )}`,
+      500
+    );
+  }
+
+  if (!frameMap || !hasFrameMetadata) {
     const errorMsg = `Frame metadata not found for frame ${frameIndex}`;
     if (debug) {
       console.error(`[getElementLocator] ${errorMsg}`);
@@ -70,37 +281,72 @@ export async function getElementLocator(
     throw new HyperagentError(errorMsg, 404);
   }
 
-  const iframeInfo = frameMap.get(frameIndex)!;
+  let iframeInfo: IframeInfo | undefined;
+  try {
+    iframeInfo = frameMap.get(frameIndex) ?? undefined;
+  } catch (error) {
+    throw new HyperagentError(
+      `Frame metadata retrieval failed for frame ${frameIndex}: ${formatElementLocatorDiagnostic(
+        error
+      )}`,
+      500
+    );
+  }
+  if (!iframeInfo) {
+    throw new HyperagentError(
+      `Frame metadata not found for frame ${frameIndex}`,
+      404
+    );
+  }
 
   if (debug) {
     console.log(
       `[getElementLocator] Resolving frame ${frameIndex} via XPath/URL metadata`
     );
   }
-  const targetFrame =
-    (await resolveFrameByXPath(page, frameMap, frameIndex)) ?? undefined;
+  let targetFrame:
+    | Awaited<ReturnType<typeof resolveFrameByXPath>>
+    | undefined;
+  try {
+    targetFrame = (await resolveFrameByXPath(page, frameMap, frameIndex)) ?? undefined;
+  } catch (error) {
+    throw new HyperagentError(
+      `Could not resolve frame for element ${safeElementId} (frameIndex: ${frameIndex}): ${formatElementLocatorDiagnostic(
+        error
+      )}`,
+      500
+    );
+  }
 
   if (!targetFrame) {
-    const errorMsg = `Could not resolve frame for element ${elementId} (frameIndex: ${frameIndex})`;
+    const errorMsg = `Could not resolve frame for element ${safeElementId} (frameIndex: ${frameIndex})`;
     if (debug) {
       console.error(`[getElementLocator] ${errorMsg}`);
-      console.error(`[getElementLocator] Frame info:`, {
-        src: iframeInfo.src,
-        name: iframeInfo.name,
-        xpath: iframeInfo.xpath,
-        parentFrameIndex: iframeInfo.parentFrameIndex,
-      });
       console.error(
-        `[getElementLocator] Available frames:`,
-        page.frames().map((f) => ({ url: f.url(), name: f.name() }))
+        `[getElementLocator] Frame info: ${formatElementLocatorDebug(
+          {
+            src: iframeInfo.src,
+            name: iframeInfo.name,
+            xpath: iframeInfo.xpath,
+            parentFrameIndex: iframeInfo.parentFrameIndex,
+          },
+          "unavailable"
+        )}`
+      );
+      console.error(
+        `[getElementLocator] Available frames: ${formatElementLocatorDebug(
+          safeListFrameMetadata(page),
+          "[]"
+        )}`
       );
     }
     throw new HyperagentError(errorMsg, 404);
   }
 
   if (debug) {
+    const frameInfo = safeFrameMetadata(targetFrame);
     console.log(
-      `[getElementLocator] Using Playwright Frame ${frameIndex}: ${targetFrame.url()}`
+      `[getElementLocator] Using Playwright Frame ${frameIndex}: ${frameInfo.url}`
     );
   }
 
@@ -117,11 +363,12 @@ export async function getElementLocator(
   }
 
   if (debug) {
+    const frameInfo = safeFrameMetadata(targetFrame);
     console.log(
-      `[getElementLocator] Using frame ${frameIndex} locator for element ${elementId}`
+      `[getElementLocator] Using frame ${frameIndex} locator for element ${normalizedElementId}`
     );
     console.log(
-      `[getElementLocator] Frame URL: ${targetFrame.url()}, Name: ${targetFrame.name()}`
+      `[getElementLocator] Frame URL: ${frameInfo.url}, Name: ${frameInfo.name}`
     );
   }
 
diff --git a/src/agent/shared/execute-playwright-method.test.ts b/src/agent/shared/execute-playwright-method.test.ts
new file mode 100644
index 00000000..265cfb36
--- /dev/null
+++ b/src/agent/shared/execute-playwright-method.test.ts
@@ -0,0 +1,213 @@
+import type { Page } from "playwright-core";
+import { executePlaywrightMethod } from "@/agent/shared/execute-playwright-method";
+
+type LocatorLike = ReturnType<Page["locator"]>;
+
+function createMockLocator(overrides?: Partial<Record<string, jest.Mock>>): LocatorLike {
+  return {
+    click: jest.fn().mockResolvedValue(undefined),
+    evaluate: jest.fn().mockResolvedValue(undefined),
+    fill: jest.fn().mockResolvedValue(undefined),
+    selectOption: jest.fn().mockResolvedValue(undefined),
+    hover: jest.fn().mockResolvedValue(undefined),
+    press: jest.fn().mockResolvedValue(undefined),
+    check: jest.fn().mockResolvedValue(undefined),
+    uncheck: jest.fn().mockResolvedValue(undefined),
+    ...overrides,
+  } as unknown as LocatorLike;
+}
+
+describe("executePlaywrightMethod", () => {
+  it("formats non-Error click fallback failures with readable output", async () => {
+    const locator = createMockLocator({
+      click: jest.fn().mockRejectedValue({ reason: "click failed" }),
+      evaluate: jest.fn().mockRejectedValue({ reason: "js click failed" }),
+    });
+    const logSpy = jest.spyOn(console, "log").mockImplementation(() => {});
+
+    try {
+      let thrown: unknown;
+      try {
+        await executePlaywrightMethod("click", [], locator, { debug: true });
+      } catch (error) {
+        thrown = error;
+      }
+      expect(thrown).toBeDefined();
+      const message = (thrown as Error).message;
+      expect(message).toContain("Failed to click element. Playwright error:");
+      expect(message).toContain("locator.click failed");
+      expect(message).toContain("locator.evaluate failed");
+      expect(logSpy).toHaveBeenCalledWith(
+        expect.stringContaining(
+          "Playwright click failed, falling back to JS click: [executePlaywrightMethod] locator.click failed"
+        )
+      );
+    } finally {
+      logSpy.mockRestore();
+    }
+  });
+
+  it("truncates oversized click fallback diagnostics", async () => {
+    const locator = createMockLocator({
+      click: jest
+        .fn()
+        .mockRejectedValue(new Error(`x${"y".repeat(2_000)}\nclick failed`)),
+      evaluate: jest
+        .fn()
+        .mockRejectedValue(new Error(`x${"y".repeat(2_000)}\njs click failed`)),
+    });
+
+    await expect(
+      executePlaywrightMethod("click", [], locator, { debug: true })
+    ).rejects.toThrow(/\[truncated/);
+  });
+
+  it("does not crash debug logging on circular method args", async () => {
+    const circular: Record<string, unknown> = { id: "arg" };
+    circular.self = circular;
+    const locator = createMockLocator();
+    const logSpy = jest.spyOn(console, "log").mockImplementation(() => {});
+
+    try {
+      await expect(
+        executePlaywrightMethod("hover", [circular], locator, { debug: true })
+      ).resolves.toBeUndefined();
+
+      expect(logSpy).toHaveBeenCalledWith(
+        expect.stringContaining('"self":"[Circular]"')
+      );
+    } finally {
+      logSpy.mockRestore();
+    }
+  });
+
+  it("preserves explicit zero for scrollToPercentage target", async () => {
+    const evaluateSpy = jest.fn().mockResolvedValue(undefined);
+    const locator = createMockLocator({
+      evaluate: evaluateSpy,
+    });
+
+    await executePlaywrightMethod("scrollToPercentage", [0], locator);
+
+    expect(evaluateSpy).toHaveBeenCalled();
+    const call = evaluateSpy.mock.calls[0];
+    expect(call?.[1]).toEqual({ yArg: "0" });
+  });
+
+  it("preserves numeric zero values for fill and selectOption actions", async () => {
+    const fillSpy = jest.fn().mockResolvedValue(undefined);
+    const selectSpy = jest.fn().mockResolvedValue(undefined);
+    const locator = createMockLocator({
+      fill: fillSpy,
+      selectOption: selectSpy,
+    });
+
+    await executePlaywrightMethod("fill", [0], locator);
+    await executePlaywrightMethod("selectOptionFromDropdown", [0], locator);
+
+    expect(fillSpy).toHaveBeenCalledWith("0");
+    expect(selectSpy).toHaveBeenCalledWith("0");
+  });
+
+  it("falls back to Enter when press key is empty string", async () => {
+    const pressSpy = jest.fn().mockResolvedValue(undefined);
+    const locator = createMockLocator({
+      press: pressSpy,
+    });
+
+    await executePlaywrightMethod("press", [""], locator);
+
+    expect(pressSpy).toHaveBeenCalledWith("Enter");
+  });
+
+  it("rejects non-array args with readable message", async () => {
+    const locator = createMockLocator();
+
+    await expect(
+      executePlaywrightMethod(
+        "click",
+        null as unknown as unknown[],
+        locator
+      )
+    ).rejects.toThrow("[executePlaywrightMethod] args must be an array");
+  });
+
+  it("handles locator method getter traps with readable diagnostics", async () => {
+    const locator = new Proxy(
+      {},
+      {
+        get: (_target, prop) => {
+          if (prop === "press") {
+            throw new Error("press getter trap");
+          }
+          return undefined;
+        },
+      }
+    ) as unknown as LocatorLike;
+
+    await expect(
+      executePlaywrightMethod("press", ["Enter"], locator)
+    ).rejects.toThrow(
+      "[executePlaywrightMethod] Failed to access locator.press: press getter trap"
+    );
+  });
+
+  it("falls back to Enter when key coercion throws", async () => {
+    const pressSpy = jest.fn().mockResolvedValue(undefined);
+    const locator = createMockLocator({
+      press: pressSpy,
+    });
+    const badValue = {
+      toString(): string {
+        throw new Error("coercion trap");
+      },
+    };
+
+    await executePlaywrightMethod("press", [badValue], locator);
+
+    expect(pressSpy).toHaveBeenCalledWith("Enter");
+  });
+
+  it("normalizes clickTimeout bounds for click actions", async () => {
+    const clickSpy = jest.fn().mockResolvedValue(undefined);
+    const locator = createMockLocator({
+      click: clickSpy,
+    });
+
+    await executePlaywrightMethod("click", [], locator, {
+      clickTimeout: -1,
+    });
+    await executePlaywrightMethod("click", [], locator, {
+      clickTimeout: 999_999,
+    });
+
+    expect(clickSpy).toHaveBeenNthCalledWith(1, { timeout: 3500 });
+    expect(clickSpy).toHaveBeenNthCalledWith(2, { timeout: 120000 });
+  });
+
+  it("caps oversized text arguments before forwarding to fill", async () => {
+    const fillSpy = jest.fn().mockResolvedValue(undefined);
+    const locator = createMockLocator({
+      fill: fillSpy,
+    });
+    const huge = "x".repeat(25_000);
+
+    await executePlaywrightMethod("fill", [huge], locator);
+
+    expect(fillSpy).toHaveBeenCalled();
+    expect((fillSpy.mock.calls[0]?.[0] as string).length).toBe(20_000);
+  });
+
+  it("truncates unknown-method diagnostics for oversized non-string values", async () => {
+    const locator = createMockLocator();
+    const badMethod = `method-${"x".repeat(2_000)}\nunsafe`;
+
+    await expect(
+      executePlaywrightMethod(
+        badMethod as unknown as string,
+        [],
+        locator
+      )
+    ).rejects.toThrow(/\[truncated/);
+  });
+});
diff --git a/src/agent/shared/execute-playwright-method.ts b/src/agent/shared/execute-playwright-method.ts
index 722d8291..91302981 100644
--- a/src/agent/shared/execute-playwright-method.ts
+++ b/src/agent/shared/execute-playwright-method.ts
@@ -4,6 +4,142 @@
  */
 
 import type { Page } from "playwright-core";
+import { formatUnknownError } from "@/utils";
+
+const DEFAULT_CLICK_TIMEOUT_MS = 3_500;
+const MAX_CLICK_TIMEOUT_MS = 120_000;
+const MAX_METHOD_ARG_CHARS = 20_000;
+const MAX_SCROLL_PERCENT_ARG_CHARS = 64;
+const MAX_PLAYWRIGHT_METHOD_DIAGNOSTIC_CHARS = 240;
+
+function sanitizePlaywrightDiagnostic(value: string): string {
+  if (value.length === 0) {
+    return value;
+  }
+  const withoutControlChars = Array.from(value, (char) => {
+    const code = char.charCodeAt(0);
+    return (code >= 0 && code < 32) || code === 127 ? " " : char;
+  }).join("");
+  return withoutControlChars.replace(/\s+/g, " ").trim();
+}
+
+function truncatePlaywrightDiagnostic(value: string): string {
+  const normalized = sanitizePlaywrightDiagnostic(value);
+  const fallback = normalized.length > 0 ? normalized : "unknown error";
+  if (fallback.length <= MAX_PLAYWRIGHT_METHOD_DIAGNOSTIC_CHARS) {
+    return fallback;
+  }
+  return `${fallback.slice(
+    0,
+    MAX_PLAYWRIGHT_METHOD_DIAGNOSTIC_CHARS
+  )}... [truncated ${
+    fallback.length - MAX_PLAYWRIGHT_METHOD_DIAGNOSTIC_CHARS
+  } chars]`;
+}
+
+function stringifyMethodArgs(args: unknown[]): string {
+  try {
+    return truncatePlaywrightDiagnostic(formatUnknownError(args));
+  } catch {
+    return "[args unavailable]";
+  }
+}
+
+function coerceStringArg(value: unknown, fallback: string): string {
+  if (typeof value === "string") {
+    const normalized = value.length > 0 ? value : fallback;
+    if (normalized.length <= MAX_METHOD_ARG_CHARS) {
+      return normalized;
+    }
+    return normalized.slice(0, MAX_METHOD_ARG_CHARS);
+  }
+  if (value == null) {
+    return fallback;
+  }
+  let coerced: string;
+  try {
+    coerced = String(value);
+  } catch {
+    return fallback;
+  }
+  if (coerced.length === 0) {
+    return fallback;
+  }
+  if (coerced.length <= MAX_METHOD_ARG_CHARS) {
+    return coerced;
+  }
+  return coerced.slice(0, MAX_METHOD_ARG_CHARS);
+}
+
+function normalizeMethod(method: unknown): string {
+  if (typeof method !== "string") {
+    return "";
+  }
+  return method.trim();
+}
+
+function normalizeArgs(args: unknown): unknown[] {
+  if (!Array.isArray(args)) {
+    throw new Error("[executePlaywrightMethod] args must be an array");
+  }
+  try {
+    return Array.from(args);
+  } catch {
+    throw new Error("[executePlaywrightMethod] args must be an array");
+  }
+}
+
+function normalizeClickTimeout(value: unknown): number {
+  if (typeof value !== "number" || !Number.isFinite(value) || value <= 0) {
+    return DEFAULT_CLICK_TIMEOUT_MS;
+  }
+  return Math.min(Math.floor(value), MAX_CLICK_TIMEOUT_MS);
+}
+
+function getLocatorMethod(
+  locator: ReturnType<Page["locator"]>,
+  methodName: string
+): (...args: unknown[]) => Promise<unknown> {
+  let method: unknown;
+  try {
+    method = (locator as unknown as Record<string, unknown>)[methodName];
+  } catch (error) {
+    throw new Error(
+      `[executePlaywrightMethod] Failed to access locator.${methodName}: ${truncatePlaywrightDiagnostic(
+        formatUnknownError(error)
+      )}`
+    );
+  }
+  if (typeof method !== "function") {
+    throw new Error(`[executePlaywrightMethod] Missing locator.${methodName} method`);
+  }
+  return method.bind(locator) as (...args: unknown[]) => Promise<unknown>;
+}
+
+async function invokeLocatorMethod(
+  locator: ReturnType<Page["locator"]>,
+  methodName: string,
+  args: unknown[]
+): Promise<unknown> {
+  const method = getLocatorMethod(locator, methodName);
+  try {
+    return await method(...args);
+  } catch (error) {
+    throw new Error(
+      `[executePlaywrightMethod] locator.${methodName} failed: ${truncatePlaywrightDiagnostic(
+        formatUnknownError(error)
+      )}`
+    );
+  }
+}
+
+function normalizeScrollArg(value: unknown): string {
+  const normalized = coerceStringArg(value ?? "50%", "50%");
+  if (normalized.length <= MAX_SCROLL_PERCENT_ARG_CHARS) {
+    return normalized;
+  }
+  return normalized.slice(0, MAX_SCROLL_PERCENT_ARG_CHARS);
+}
 
 /**
  * Execute a Playwright method on a locator
@@ -21,30 +157,31 @@ export async function executePlaywrightMethod(
   locator: ReturnType<Page["locator"]>,
   options: { clickTimeout?: number; debug?: boolean } = {}
 ): Promise<void> {
-  const { clickTimeout = 3500, debug = false } = options;
+  const clickTimeout = normalizeClickTimeout(options?.clickTimeout);
+  const debug = options?.debug === true;
+  const normalizedMethod = normalizeMethod(method);
+  const normalizedArgs = normalizeArgs(args);
 
-  switch (method) {
+  switch (normalizedMethod) {
     case "click":
       try {
-        await locator.click({ timeout: clickTimeout });
+        await invokeLocatorMethod(locator, "click", [{ timeout: clickTimeout }]);
       } catch (e) {
-        const errorMsg = e instanceof Error ? e.message : String(e);
+        const errorMsg = truncatePlaywrightDiagnostic(formatUnknownError(e));
         if (debug) {
           console.log(
             `[executePlaywrightMethod] Playwright click failed, falling back to JS click: ${errorMsg}`
           );
         }
         try {
-          await locator.evaluate(
-            (el) => (el as HTMLElement).click(),
+          await invokeLocatorMethod(locator, "evaluate", [
+            (el: HTMLElement) => (el as HTMLElement).click(),
             undefined,
-            { timeout: clickTimeout }
-          );
+          ]);
         } catch (jsClickError) {
-          const jsErrorMsg =
-            jsClickError instanceof Error
-              ? jsClickError.message
-              : String(jsClickError);
+          const jsErrorMsg = truncatePlaywrightDiagnostic(
+            formatUnknownError(jsClickError)
+          );
           throw new Error(
             `Failed to click element. Playwright error: ${errorMsg}. JS click error: ${jsErrorMsg}`
           );
@@ -53,42 +190,48 @@ export async function executePlaywrightMethod(
       break;
     case "type":
     case "fill":
-      await locator.fill((args[0] as string) || "");
+      await invokeLocatorMethod(locator, "fill", [
+        coerceStringArg(normalizedArgs[0], ""),
+      ]);
       break;
     case "selectOptionFromDropdown":
-      await locator.selectOption((args[0] as string) || "");
+      await invokeLocatorMethod(locator, "selectOption", [
+        coerceStringArg(normalizedArgs[0], ""),
+      ]);
       break;
     case "hover":
-      await locator.hover();
+      await invokeLocatorMethod(locator, "hover", []);
       break;
     case "press":
-      await locator.press((args[0] as string) || "Enter");
+      await invokeLocatorMethod(locator, "press", [
+        coerceStringArg(normalizedArgs[0], "Enter"),
+      ]);
       break;
     case "check":
-      await locator.check();
+      await invokeLocatorMethod(locator, "check", []);
       break;
     case "uncheck":
-      await locator.uncheck();
+      await invokeLocatorMethod(locator, "uncheck", []);
       break;
     case "scrollToElement":
-      await locator.evaluate((element) => {
+      await invokeLocatorMethod(locator, "evaluate", [(element: Element) => {
         if (typeof element.scrollIntoView === "function") {
           element.scrollIntoView({ behavior: "smooth", block: "center" });
         }
-      });
+      }]);
       break;
     case "scrollToPercentage":
       {
-        const scrollArg = (args[0] || "50%").toString();
-        await locator.evaluate(
-          (element, { yArg }) => {
+        const scrollArg = normalizeScrollArg(normalizedArgs[0]);
+        await invokeLocatorMethod(locator, "evaluate", [
+          (element: HTMLElement | Element, args: { yArg: string }) => {
             function parsePercent(val: string): number {
               const cleaned = val.trim().replace("%", "");
               const num = parseFloat(cleaned);
               return Number.isNaN(num) ? 0 : Math.max(0, Math.min(num, 100));
             }
 
-            const yPct = parsePercent(yArg);
+            const yPct = parsePercent(args.yArg);
 
             if (element.tagName.toLowerCase() === "html") {
               const scrollHeight = document.body.scrollHeight;
@@ -119,13 +262,13 @@ export async function executePlaywrightMethod(
               }
             }
           },
-          { yArg: scrollArg }
-        );
+          { yArg: scrollArg },
+        ]);
       }
       break;
     case "scrollTo":
       {
-        const target = args[0];
+        const target = normalizedArgs[0];
         if (target == null) {
           await executePlaywrightMethod("scrollToElement", [], locator);
         } else {
@@ -139,7 +282,7 @@ export async function executePlaywrightMethod(
       break;
     case "nextChunk":
       // Scroll down by one viewport/element height
-      await locator.evaluate((element) => {
+      await invokeLocatorMethod(locator, "evaluate", [(element: HTMLElement | Element) => {
         const waitForScrollEnd = (el: HTMLElement | Element) =>
           new Promise<void>((resolve) => {
             let last = el.scrollTop ?? 0;
@@ -169,11 +312,11 @@ export async function executePlaywrightMethod(
           behavior: "smooth",
         });
         return waitForScrollEnd(element);
-      });
+      }]);
       break;
     case "prevChunk":
       // Scroll up by one viewport/element height
-      await locator.evaluate((element) => {
+      await invokeLocatorMethod(locator, "evaluate", [(element: HTMLElement | Element) => {
         const waitForScrollEnd = (el: HTMLElement | Element) =>
           new Promise<void>((resolve) => {
             let last = el.scrollTop ?? 0;
@@ -203,10 +346,13 @@ export async function executePlaywrightMethod(
           behavior: "smooth",
         });
         return waitForScrollEnd(element);
-      });
+      }]);
       break;
     default: {
-      const errorMsg = `Unknown method: ${method}`;
+      const methodLabel = normalizedMethod
+        ? truncatePlaywrightDiagnostic(normalizedMethod)
+        : truncatePlaywrightDiagnostic(formatUnknownError(method));
+      const errorMsg = `Unknown method: ${methodLabel}`;
       if (debug) {
         console.error(`[executePlaywrightMethod] ${errorMsg}`);
       }
@@ -216,7 +362,7 @@ export async function executePlaywrightMethod(
 
   if (debug) {
     console.log(
-      `[executePlaywrightMethod] Successfully executed ${method}(${JSON.stringify(args)})`
+      `[executePlaywrightMethod] Successfully executed ${normalizedMethod}(${stringifyMethodArgs(normalizedArgs)})`
     );
   }
 }
diff --git a/src/agent/shared/find-element.test.ts b/src/agent/shared/find-element.test.ts
new file mode 100644
index 00000000..61366752
--- /dev/null
+++ b/src/agent/shared/find-element.test.ts
@@ -0,0 +1,232 @@
+import type { HyperAgentLLM } from "@/llm/types";
+import { findElementWithInstruction } from "@/agent/shared/find-element";
+
+jest.mock("@/utils/waitForSettledDOM", () => ({
+  waitForSettledDOM: jest.fn(),
+}));
+
+jest.mock("@/agent/shared/dom-capture", () => ({
+  captureDOMState: jest.fn(),
+}));
+
+jest.mock("@/agent/examine-dom", () => ({
+  examineDom: jest.fn(),
+}));
+
+const { waitForSettledDOM } = jest.requireMock(
+  "@/utils/waitForSettledDOM"
+) as {
+  waitForSettledDOM: jest.Mock;
+};
+
+const { captureDOMState } = jest.requireMock(
+  "@/agent/shared/dom-capture"
+) as {
+  captureDOMState: jest.Mock;
+};
+
+const { examineDom } = jest.requireMock(
+  "@/agent/examine-dom"
+) as {
+  examineDom: jest.Mock;
+};
+
+function createMockLLM(): HyperAgentLLM {
+  return {
+    invoke: async () => ({ role: "assistant", content: "ok" }),
+    invokeStructured: async () => ({ rawText: "{}", parsed: null }),
+    getProviderId: () => "mock",
+    getModelId: () => "mock-model",
+    getCapabilities: () => ({
+      multimodal: false,
+      toolCalling: true,
+      jsonMode: true,
+    }),
+  };
+}
+
+function createDomState() {
+  return {
+    elements: new Map([["0-1", { name: "button" }]]),
+    domState: "dom tree",
+    xpathMap: { "0-1": "//button[1]" },
+    backendNodeMap: { "0-1": 111 },
+  };
+}
+
+describe("findElementWithInstruction", () => {
+  beforeEach(() => {
+    jest.clearAllMocks();
+    waitForSettledDOM.mockResolvedValue(undefined);
+    captureDOMState.mockResolvedValue(createDomState());
+  });
+
+  it("retries element discovery and returns first found element", async () => {
+    const page = {
+      url: () => "https://example.com",
+    } as unknown as import("playwright-core").Page;
+    examineDom
+      .mockResolvedValueOnce({
+        elements: [],
+        llmResponse: { rawText: "{}", parsed: null },
+      })
+      .mockResolvedValueOnce({
+        elements: [{ elementId: "0-1", method: "click", args: [] }],
+        llmResponse: { rawText: '{"ok":true}', parsed: { ok: true } },
+      });
+
+    const result = await findElementWithInstruction(
+      "click login",
+      page,
+      createMockLLM(),
+      {
+        maxRetries: 2,
+        retryDelayMs: 0,
+      }
+    );
+
+    expect(result.success).toBe(true);
+    expect(result.element).toEqual({ elementId: "0-1", method: "click", args: [] });
+    expect(examineDom).toHaveBeenCalledTimes(2);
+  });
+
+  it("normalizes invalid maxRetries and returns fallback domState on capture errors", async () => {
+    const page = {
+      url: () => "https://example.com",
+    } as unknown as import("playwright-core").Page;
+    captureDOMState.mockRejectedValue(new Error("capture failed"));
+
+    const result = await findElementWithInstruction(
+      "click login",
+      page,
+      createMockLLM(),
+      {
+        maxRetries: 0,
+        retryDelayMs: 0,
+      }
+    );
+
+    expect(result.success).toBe(false);
+    expect(result.domState.domState).toContain("capture failed");
+    expect(captureDOMState).toHaveBeenCalledTimes(1);
+  });
+
+  it("truncates oversized fallback diagnostics on capture errors", async () => {
+    const page = {
+      url: () => "https://example.com",
+    } as unknown as import("playwright-core").Page;
+    captureDOMState.mockRejectedValue(new Error(`x${"y".repeat(2_000)}\ncapture failed`));
+
+    const result = await findElementWithInstruction(
+      "click login",
+      page,
+      createMockLLM(),
+      {
+        maxRetries: 1,
+        retryDelayMs: 0,
+      }
+    );
+
+    expect(result.success).toBe(false);
+    expect(result.domState.domState).toContain("[truncated");
+    expect(result.domState.domState).not.toContain("\n");
+  });
+
+  it("uses fallback page URL when page.url() getter throws", async () => {
+    const page = {
+      url: () => {
+        throw new Error("url trap");
+      },
+    } as unknown as import("playwright-core").Page;
+    examineDom.mockResolvedValue({
+      elements: [],
+      llmResponse: { rawText: "{}", parsed: null },
+    });
+
+    await findElementWithInstruction("click login", page, createMockLLM(), {
+      maxRetries: 1,
+      retryDelayMs: 0,
+    });
+
+    expect(examineDom).toHaveBeenCalledWith(
+      "click login",
+      expect.objectContaining({
+        url: "about:blank",
+      }),
+      expect.any(Object)
+    );
+  });
+
+  it("sanitizes control characters in page URL passed to examineDom", async () => {
+    const page = {
+      url: () => "https://example.com/\u0000path\nsegment",
+    } as unknown as import("playwright-core").Page;
+    examineDom.mockResolvedValue({
+      elements: [],
+      llmResponse: { rawText: "{}", parsed: null },
+    });
+
+    await findElementWithInstruction("click login", page, createMockLLM(), {
+      maxRetries: 1,
+      retryDelayMs: 0,
+    });
+
+    expect(examineDom).toHaveBeenCalledWith(
+      "click login",
+      expect.objectContaining({
+        url: "https://example.com/ path segment",
+      }),
+      expect.any(Object)
+    );
+  });
+
+  it("truncates oversized page URL before passing to examineDom", async () => {
+    const page = {
+      url: () => `https://example.com/${"x".repeat(4_000)}`,
+    } as unknown as import("playwright-core").Page;
+    examineDom.mockResolvedValue({
+      elements: [],
+      llmResponse: { rawText: "{}", parsed: null },
+    });
+
+    await findElementWithInstruction("click login", page, createMockLLM(), {
+      maxRetries: 1,
+      retryDelayMs: 0,
+    });
+
+    expect(examineDom).toHaveBeenCalledWith(
+      "click login",
+      expect.objectContaining({
+        url: expect.stringContaining("[truncated"),
+      }),
+      expect.any(Object)
+    );
+  });
+
+  it("truncates oversized debug retry diagnostics", async () => {
+    const warnSpy = jest.spyOn(console, "warn").mockImplementation(() => {});
+    const page = {
+      url: () => "https://example.com",
+    } as unknown as import("playwright-core").Page;
+    captureDOMState.mockRejectedValue(new Error(`x${"y".repeat(2_000)}\ncapture failed`));
+
+    try {
+      await findElementWithInstruction(
+        "click login",
+        page,
+        createMockLLM(),
+        {
+          maxRetries: 1,
+          retryDelayMs: 0,
+          debug: true,
+        }
+      );
+
+      const warnMessage = String(warnSpy.mock.calls[0]?.[0] ?? "");
+      expect(warnMessage).toContain("[truncated");
+      expect(warnMessage).not.toContain("\n");
+    } finally {
+      warnSpy.mockRestore();
+    }
+  });
+});
diff --git a/src/agent/shared/find-element.ts b/src/agent/shared/find-element.ts
index 12e8dc8b..dd652f86 100644
--- a/src/agent/shared/find-element.ts
+++ b/src/agent/shared/find-element.ts
@@ -11,6 +11,7 @@ import type { AccessibilityNode } from "@/context-providers/a11y-dom/types";
 import { captureDOMState } from "./dom-capture";
 import type { A11yDOMState } from "@/context-providers/a11y-dom/types";
 import { waitForSettledDOM } from "@/utils/waitForSettledDOM";
+import { formatUnknownError, normalizePageUrl } from "@/utils";
 
 export interface FindElementOptions {
   /**
@@ -27,6 +28,12 @@ export interface FindElementOptions {
    * Enable debug logging
    */
   debug?: boolean;
+
+  /**
+   * Enable/disable ad and tracking iframe filtering during frame discovery.
+   * Defaults to true when unspecified.
+   */
+  filterAdTrackingFrames?: boolean;
 }
 
 export interface FindElementResult {
@@ -37,6 +44,64 @@ export interface FindElementResult {
   llmResponse?: { rawText: string; parsed: unknown };
 }
 
+const DEFAULT_MAX_RETRIES = 1;
+const MAX_FIND_ELEMENT_RETRIES = 20;
+const MAX_RETRY_DELAY_MS = 30_000;
+const MAX_FIND_ELEMENT_DIAGNOSTIC_CHARS = 400;
+const MAX_FIND_ELEMENT_URL_CHARS = 1_000;
+
+function formatFindElementDiagnostic(value: unknown): string {
+  const normalized = Array.from(formatUnknownError(value), (char) => {
+    const code = char.charCodeAt(0);
+    return (code >= 0 && code < 32) || code === 127 ? " " : char;
+  })
+    .join("")
+    .replace(/\s+/g, " ")
+    .trim();
+  const fallback = normalized.length > 0 ? normalized : "unknown error";
+  if (fallback.length <= MAX_FIND_ELEMENT_DIAGNOSTIC_CHARS) {
+    return fallback;
+  }
+  const omitted = fallback.length - MAX_FIND_ELEMENT_DIAGNOSTIC_CHARS;
+  return `${fallback.slice(
+    0,
+    MAX_FIND_ELEMENT_DIAGNOSTIC_CHARS
+  )}... [truncated ${omitted} chars]`;
+}
+
+function normalizeMaxRetries(value: unknown): number {
+  if (typeof value !== "number" || !Number.isFinite(value) || value <= 0) {
+    return DEFAULT_MAX_RETRIES;
+  }
+  return Math.min(Math.floor(value), MAX_FIND_ELEMENT_RETRIES);
+}
+
+function normalizeRetryDelayMs(value: unknown): number {
+  if (typeof value !== "number" || !Number.isFinite(value) || value < 0) {
+    return 1_000;
+  }
+  return Math.min(Math.floor(value), MAX_RETRY_DELAY_MS);
+}
+
+function safeGetPageUrl(page: Page): string {
+  try {
+    return normalizePageUrl(page.url(), {
+      maxChars: MAX_FIND_ELEMENT_URL_CHARS,
+    });
+  } catch {
+    return "about:blank";
+  }
+}
+
+function createFallbackDomState(message: string): A11yDOMState {
+  return {
+    elements: new Map(),
+    domState: message,
+    xpathMap: {},
+    backendNodeMap: {},
+  };
+}
+
 /**
  * Find an element via natural language instruction with retry logic
  *
@@ -47,7 +112,7 @@ export interface FindElementResult {
  * 4. Retries on failure (with DOM refresh on each attempt)
  *
  * Used by:
- * - findElementWithRetry (aiAction)
+ * - findElementWithRetry (page.perform / deprecated page.aiAction alias)
  * - actElement action (executeTask agent)
  *
  * @param instruction Natural language instruction (e.g., "click the Login button")
@@ -63,13 +128,16 @@ export async function findElementWithInstruction(
   llm: HyperAgentLLM,
   options: FindElementOptions = {}
 ): Promise<FindElementResult> {
-  const { maxRetries = 1, retryDelayMs = 1000, debug = false } = options;
+  const maxRetries = normalizeMaxRetries(options.maxRetries);
+  const retryDelayMs = normalizeRetryDelayMs(options.retryDelayMs);
+  const debug = options.debug === true;
 
   let lastDomState: A11yDOMState | null = null;
   let lastElementMap: Map<string, AccessibilityNode> | null = null;
   let lastLlmResponse: { rawText: string; parsed: unknown } | undefined;
+  let lastError: unknown;
 
-  // Retry loop with DOM refresh (matches aiAction's findElementWithRetry pattern)
+  // Retry loop with DOM refresh (matches executeSingleAction's findElementWithRetry pattern)
   for (let attempt = 0; attempt < maxRetries; attempt++) {
     if (debug) {
       if (attempt === 0) {
@@ -79,71 +147,85 @@ export async function findElementWithInstruction(
       }
     }
 
-    await waitForSettledDOM(page);
-    // Fetch FRESH a11y tree using the robust shared utility
-    // captureDOMState handles DOM settling and retries for bad snapshots internally for this *single* capture attempt
-    // We still need our outer loop for retrying the *finding* logic (e.g. if the LLM can't find the element)
-    const domState = await captureDOMState(page, {
-      debug,
-      // Don't retry capture inside captureDOMState too aggressively since we have an outer loop here
-      // But we do want it to handle transient CDP errors
-      maxRetries: 2,
-    });
+    try {
+      await waitForSettledDOM(page, undefined, {
+        filterAdTrackingFrames: options.filterAdTrackingFrames,
+      }).catch(() => undefined);
+      // Fetch FRESH a11y tree using the robust shared utility
+      // captureDOMState handles DOM settling and retries for bad snapshots internally for this *single* capture attempt
+      // We still need our outer loop for retrying the *finding* logic (e.g. if the LLM can't find the element)
+      const domState = await captureDOMState(page, {
+        debug,
+        // Don't retry capture inside captureDOMState too aggressively since we have an outer loop here
+        // But we do want it to handle transient CDP errors
+        maxRetries: 2,
+        filterAdTrackingFrames: options.filterAdTrackingFrames,
+      });
 
-    if (debug) {
-      console.log(
-        `[findElement] Fetched a11y tree: ${domState.elements.size} elements`
+      if (debug) {
+        console.log(
+          `[findElement] Fetched a11y tree: ${domState.elements.size} elements`
+        );
+      }
+
+      // Convert elements map to string-only keys for examineDom
+      const elementMap = new Map<string, AccessibilityNode>(
+        Array.from(domState.elements).map(([k, v]) => [String(k), v])
       );
-    }
 
-    // Convert elements map to string-only keys for examineDom
-    const elementMap = new Map<string, AccessibilityNode>(
-      Array.from(domState.elements).map(([k, v]) => [String(k), v])
-    );
+      if (debug) {
+        console.log(
+          `[findElement] Calling examineDom to find element for: "${instruction}"`
+        );
+      }
 
-    if (debug) {
-      console.log(
-        `[findElement] Calling examineDom to find element for: "${instruction}"`
+      const examineResult = await examineDom(
+        instruction,
+        {
+          tree: domState.domState,
+          xpathMap: domState.xpathMap || {},
+          elements: elementMap,
+          url: safeGetPageUrl(page),
+        },
+        llm
       );
-    }
 
-    const examineResult = await examineDom(
-      instruction,
-      {
-        tree: domState.domState,
-        xpathMap: domState.xpathMap || {},
-        elements: elementMap,
-        url: page.url(),
-      },
-      llm
-    );
-
-    // Store last attempt's data for error case
-    lastDomState = domState;
-    lastElementMap = elementMap;
-    lastLlmResponse = examineResult?.llmResponse;
-
-    // Check if element was found
-    if (examineResult && examineResult.elements.length > 0) {
-      // Found it! Break out of retry loop
-      if (debug && attempt > 0) {
-        console.log(`[findElement] Element found on attempt ${attempt + 1}`);
+      // Store last attempt's data for error case
+      lastDomState = domState;
+      lastElementMap = elementMap;
+      lastLlmResponse = examineResult?.llmResponse;
+
+      // Check if element was found
+      if (examineResult && examineResult.elements.length > 0) {
+        // Found it! Break out of retry loop
+        if (debug && attempt > 0) {
+          console.log(`[findElement] Element found on attempt ${attempt + 1}`);
+        }
+
+        return {
+          success: true,
+          element: examineResult.elements[0],
+          domState,
+          elementMap,
+          llmResponse: examineResult.llmResponse,
+        };
+      }
+    } catch (error) {
+      lastError = error;
+      if (debug) {
+        console.warn(
+          `[findElement] Attempt ${attempt + 1} failed: ${formatFindElementDiagnostic(
+            error
+          )}`
+        );
       }
-
-      return {
-        success: true,
-        element: examineResult.elements[0],
-        domState,
-        elementMap,
-        llmResponse: examineResult.llmResponse,
-      };
     }
 
     // Retry if not last attempt
     if (attempt < maxRetries - 1) {
       if (debug) {
         console.log(
-          `[aiAction] Element not found, retrying in ${retryDelayMs}ms (attempt ${attempt + 1}/${maxRetries})...`
+          `[perform] Element not found, retrying in ${retryDelayMs}ms (attempt ${attempt + 1}/${maxRetries})...`
         );
       }
       await new Promise((resolve) => setTimeout(resolve, retryDelayMs));
@@ -152,10 +234,14 @@ export async function findElementWithInstruction(
   }
 
   // Max retries reached - return failure with last attempt's data
+  const fallbackMessage =
+    lastError != null
+      ? `Element search failed: ${formatFindElementDiagnostic(lastError)}`
+      : "Element search failed: no matching element found.";
   return {
     success: false,
-    domState: lastDomState!,
-    elementMap: lastElementMap!,
+    domState: lastDomState ?? createFallbackDomState(fallbackMessage),
+    elementMap: lastElementMap ?? new Map<string, AccessibilityNode>(),
     llmResponse: lastLlmResponse,
   };
 }
diff --git a/src/agent/shared/parse-extract-output.test.ts b/src/agent/shared/parse-extract-output.test.ts
new file mode 100644
index 00000000..7b783174
--- /dev/null
+++ b/src/agent/shared/parse-extract-output.test.ts
@@ -0,0 +1,158 @@
+import { z } from "zod";
+import { parseExtractOutput } from "@/agent/shared/parse-extract-output";
+
+describe("parseExtractOutput", () => {
+  it("returns plain text output when no schema is provided", () => {
+    expect(parseExtractOutput("hello world", "completed")).toBe("hello world");
+  });
+
+  it("throws when output is empty or non-string", () => {
+    expect(() => parseExtractOutput("", "failed")).toThrow(
+      "did not complete with output"
+    );
+    expect(() => parseExtractOutput(undefined, "failed")).toThrow(
+      "did not complete with output"
+    );
+  });
+
+  it("formats non-string task status diagnostics safely", () => {
+    expect(() =>
+      parseExtractOutput(undefined, { reason: "agent failed", code: 500 })
+    ).toThrow('Task status: {"reason":"agent failed","code":500}');
+  });
+
+  it("sanitizes control characters in task status diagnostics", () => {
+    expect(() => parseExtractOutput(undefined, "failed\u0000\nstatus")).toThrow(
+      "Task status: failed status"
+    );
+  });
+
+  it("parses and validates structured output with schema", () => {
+    const schema = z.object({
+      total: z.number(),
+      currency: z.string(),
+    });
+    const parsed = parseExtractOutput(
+      "{\"total\":99,\"currency\":\"USD\"}",
+      "completed",
+      schema
+    );
+    expect(parsed).toEqual({
+      total: 99,
+      currency: "USD",
+    });
+  });
+
+  it("parses structured output with BOM-prefixed JSON", () => {
+    const schema = z.object({
+      total: z.number(),
+    });
+    const parsed = parseExtractOutput("\uFEFF{\"total\":42}", "completed", schema);
+    expect(parsed).toEqual({ total: 42 });
+  });
+
+  it("throws clear error for invalid JSON structured output", () => {
+    const schema = z.object({
+      total: z.number(),
+    });
+    expect(() =>
+      parseExtractOutput("not-json", "completed", schema)
+    ).toThrow("not valid JSON");
+  });
+
+  it("truncates oversized invalid JSON diagnostics", () => {
+    const schema = z.object({
+      total: z.number(),
+    });
+    const oversized = "x".repeat(1000);
+    expect(() =>
+      parseExtractOutput(oversized, "completed", schema)
+    ).toThrow("[truncated]");
+  });
+
+  it("throws clear error when structured output violates schema", () => {
+    const schema = z.object({
+      total: z.number(),
+    });
+    expect(() =>
+      parseExtractOutput("{\"total\":\"oops\"}", "completed", schema)
+    ).toThrow("does not match schema");
+  });
+
+  it("rejects oversized structured outputs before JSON parsing", () => {
+    const schema = z.object({
+      total: z.number(),
+    });
+    const oversized = `{"total":${"1".repeat(100_100)}}`;
+
+    expect(() =>
+      parseExtractOutput(oversized, "completed", schema)
+    ).toThrow("output exceeds 100000 characters");
+  });
+
+  it("handles primitive parsed output without crashing schema error rendering", () => {
+    const schema = z.object({
+      total: z.number(),
+    });
+    expect(() => parseExtractOutput("1", "completed", schema)).toThrow(
+      "does not match schema"
+    );
+  });
+
+  it("surfaces readable diagnostics when schema validation throws", () => {
+    const schema = new Proxy(
+      z.object({
+        total: z.number(),
+      }),
+      {
+        get: (target, prop, receiver) => {
+          if (prop === "safeParse") {
+            return () => {
+              throw new Error("schema crash");
+            };
+          }
+          return Reflect.get(target, prop, receiver);
+        },
+      }
+    ) as unknown as z.ZodType<unknown>;
+
+    expect(() =>
+      parseExtractOutput("{\"total\":1}", "completed", schema)
+    ).toThrow("schema validation threw (schema crash)");
+  });
+
+  it("truncates oversized schema-throw diagnostics", () => {
+    const schema = {
+      safeParse: () => {
+        throw new Error("x".repeat(1_000));
+      },
+    } as unknown as z.ZodType<unknown>;
+
+    expect(() =>
+      parseExtractOutput("{\"total\":1}", "completed", schema)
+    ).toThrow("[truncated]");
+  });
+
+  it("falls back safely when schema issue enumeration throws", () => {
+    const schema = {
+      safeParse: () => ({
+        success: false,
+        error: new Proxy(
+          {},
+          {
+            get: (_target, prop) => {
+              if (prop === "issues") {
+                throw new Error("issue trap");
+              }
+              return undefined;
+            },
+          }
+        ),
+      }),
+    } as unknown as z.ZodType<unknown>;
+
+    expect(() =>
+      parseExtractOutput("{\"total\":1}", "completed", schema)
+    ).toThrow("does not match schema (issue trap)");
+  });
+});
diff --git a/src/agent/shared/parse-extract-output.ts b/src/agent/shared/parse-extract-output.ts
new file mode 100644
index 00000000..634fa3c6
--- /dev/null
+++ b/src/agent/shared/parse-extract-output.ts
@@ -0,0 +1,155 @@
+import { z } from "zod";
+import { formatUnknownError } from "@/utils";
+
+const MAX_EXTRACT_DIAGNOSTIC_CHARS = 400;
+const MAX_EXTRACT_PARSE_CHARS = 100_000;
+
+function sanitizeExtractDiagnostic(value: string): string {
+  if (value.length === 0) {
+    return value;
+  }
+  const withoutControlChars = Array.from(value, (char) => {
+    const code = char.charCodeAt(0);
+    return (code >= 0 && code < 32) || code === 127 ? " " : char;
+  }).join("");
+  return withoutControlChars.replace(/\s+/g, " ").trim();
+}
+
+function truncateExtractDiagnostic(value: string): string {
+  if (value.length <= MAX_EXTRACT_DIAGNOSTIC_CHARS) {
+    return value;
+  }
+  return `${value.slice(0, MAX_EXTRACT_DIAGNOSTIC_CHARS)}... [truncated]`;
+}
+
+function formatExtractDiagnostic(value: unknown): string {
+  return (
+    truncateExtractDiagnostic(
+      sanitizeExtractDiagnostic(formatUnknownError(value))
+    ) || "unknown error"
+  );
+}
+
+function ensureStringOutput(output: unknown, taskStatus: unknown): string {
+  if (typeof output !== "string" || output.trim().length === 0) {
+    throw new Error(
+      `Extract failed: Agent did not complete with output. Task status: ${formatExtractDiagnostic(
+        taskStatus
+      )}. Check debug output for details.`
+    );
+  }
+  return output;
+}
+
+function safeStringify(value: unknown): string {
+  return formatExtractDiagnostic(value);
+}
+
+function parseStructuredOutput<TSchema extends z.ZodType<unknown>>(
+  rawOutput: string,
+  outputSchema: TSchema
+): z.infer<TSchema> {
+  if (rawOutput.length > MAX_EXTRACT_PARSE_CHARS) {
+    throw new Error(
+      `Extract failed: output exceeds ${MAX_EXTRACT_PARSE_CHARS} characters and cannot be parsed safely.`
+    );
+  }
+
+  const normalizedOutput = rawOutput.replace(/^\uFEFF/, "");
+
+  let parsed: unknown;
+  try {
+    parsed = JSON.parse(normalizedOutput);
+  } catch (error) {
+    const message = formatExtractDiagnostic(error);
+    throw new Error(
+      `Extract failed: output is not valid JSON (${message}). Raw output: ${truncateExtractDiagnostic(
+        sanitizeExtractDiagnostic(rawOutput)
+      )}`
+    );
+  }
+
+  let safeParseResult: unknown;
+  try {
+    safeParseResult = outputSchema.safeParse(parsed);
+  } catch (error) {
+    throw new Error(
+      `Extract failed: schema validation threw (${formatExtractDiagnostic(
+        error
+      )}). Parsed output: ${safeStringify(parsed)}`
+    );
+  }
+  if (
+    !safeParseResult ||
+    typeof safeParseResult !== "object" ||
+    !("success" in safeParseResult)
+  ) {
+    throw new Error(
+      `Extract failed: schema validation returned an invalid result shape. Parsed output: ${safeStringify(
+        parsed
+      )}`
+    );
+  }
+  const validationResult = safeParseResult as {
+    success: boolean;
+    data?: z.infer<TSchema>;
+    error?: { issues?: Array<{ path: PropertyKey[]; message: string }> };
+  };
+
+  if (!validationResult.success) {
+    let issues: string;
+    try {
+      issues = truncateExtractDiagnostic(
+        (validationResult.error?.issues ?? [])
+          .map((issue) => {
+            const path = Array.isArray(issue.path)
+              ? issue.path
+                  .map((segment) =>
+                    typeof segment === "string" || typeof segment === "number"
+                      ? String(segment)
+                      : typeof segment === "symbol"
+                        ? segment.toString()
+                        : formatExtractDiagnostic(segment)
+                  )
+                  .join(".")
+              : "<root>";
+            const normalizedIssueMessage = truncateExtractDiagnostic(
+              sanitizeExtractDiagnostic(issue.message)
+            );
+            return `${path || "<root>"}: ${normalizedIssueMessage}`;
+          })
+          .join("; ")
+      );
+    } catch (error) {
+      issues = formatExtractDiagnostic(error);
+    }
+    throw new Error(
+      `Extract failed: output does not match schema (${issues}). Parsed output: ${safeStringify(
+        parsed
+      )}`
+    );
+  }
+
+  return validationResult.data as z.infer<TSchema>;
+}
+
+export function parseExtractOutput(
+  output: unknown,
+  taskStatus: unknown
+): string;
+export function parseExtractOutput<TSchema extends z.ZodType<unknown>>(
+  output: unknown,
+  taskStatus: unknown,
+  outputSchema: TSchema
+): z.infer<TSchema>;
+export function parseExtractOutput<TSchema extends z.ZodType<unknown>>(
+  output: unknown,
+  taskStatus: unknown,
+  outputSchema?: TSchema
+): string | z.infer<TSchema> {
+  const rawOutput = ensureStringOutput(output, taskStatus);
+  if (!outputSchema) {
+    return rawOutput;
+  }
+  return parseStructuredOutput(rawOutput, outputSchema);
+}
diff --git a/src/agent/shared/replay-special-actions.test.ts b/src/agent/shared/replay-special-actions.test.ts
new file mode 100644
index 00000000..d858b2b5
--- /dev/null
+++ b/src/agent/shared/replay-special-actions.test.ts
@@ -0,0 +1,505 @@
+import { executeReplaySpecialAction } from "@/agent/shared/replay-special-actions";
+import type { Page } from "playwright-core";
+
+jest.mock("@/utils/waitForSettledDOM", () => ({
+  waitForSettledDOM: jest.fn(),
+}));
+
+jest.mock("@/context-providers/a11y-dom/dom-cache", () => ({
+  markDomSnapshotDirty: jest.fn(),
+}));
+
+const { waitForSettledDOM } = jest.requireMock(
+  "@/utils/waitForSettledDOM"
+) as {
+  waitForSettledDOM: jest.Mock;
+};
+
+const { markDomSnapshotDirty } = jest.requireMock(
+  "@/context-providers/a11y-dom/dom-cache"
+) as {
+  markDomSnapshotDirty: jest.Mock;
+};
+
+function createPage(overrides?: Record<string, unknown>) {
+  return {
+    goto: jest.fn().mockResolvedValue(undefined),
+    reload: jest.fn().mockResolvedValue(undefined),
+    waitForTimeout: jest.fn().mockResolvedValue(undefined),
+    waitForLoadState: jest.fn().mockResolvedValue(undefined),
+    ...overrides,
+  };
+}
+
+describe("executeReplaySpecialAction", () => {
+  beforeEach(() => {
+    jest.clearAllMocks();
+    waitForSettledDOM.mockResolvedValue(undefined);
+  });
+
+  it("replays goToUrl using actionParams url", async () => {
+    const page = createPage();
+
+    const result = await executeReplaySpecialAction({
+      taskId: "task-1",
+      actionType: "goToUrl",
+      actionParams: { url: "https://example.com" },
+      page: page as unknown as Page,
+    });
+
+    expect(page.goto).toHaveBeenCalledWith("https://example.com", {
+      waitUntil: "domcontentloaded",
+    });
+    expect(waitForSettledDOM).toHaveBeenCalledWith(
+      page,
+      undefined,
+      expect.objectContaining({
+        filterAdTrackingFrames: undefined,
+      })
+    );
+    expect(markDomSnapshotDirty).toHaveBeenCalledWith(page);
+    expect(result?.status).toBe("completed");
+    expect(result?.replayStepMeta?.retries).toBe(1);
+  });
+
+  it("forwards frame-filter option to waitForSettledDOM during special replay", async () => {
+    const page = createPage();
+
+    await executeReplaySpecialAction({
+      taskId: "task-filter-option",
+      actionType: "goToUrl",
+      actionParams: { url: "https://example.com" },
+      filterAdTrackingFrames: false,
+      page: page as unknown as Page,
+    });
+
+    expect(waitForSettledDOM).toHaveBeenCalledWith(
+      page,
+      undefined,
+      expect.objectContaining({
+        filterAdTrackingFrames: false,
+      })
+    );
+  });
+
+  it("fails goToUrl replay when url is empty after trimming", async () => {
+    const page = createPage();
+
+    const result = await executeReplaySpecialAction({
+      taskId: "task-empty-url",
+      actionType: "goToUrl",
+      arguments: ["   "],
+      page: page as unknown as Page,
+    });
+
+    expect(result?.status).toBe("failed");
+    expect(result?.output).toContain("Missing URL for goToUrl");
+    expect(page.goto).not.toHaveBeenCalled();
+  });
+
+  it("replays wait using duration from actionParams", async () => {
+    const page = createPage();
+
+    const result = await executeReplaySpecialAction({
+      taskId: "task-2",
+      actionType: "wait",
+      actionParams: { duration: "1500" },
+      page: page as unknown as Page,
+    });
+
+    expect(page.waitForTimeout).toHaveBeenCalledWith(1500);
+    expect(markDomSnapshotDirty).toHaveBeenCalledWith(page);
+    expect(result?.output).toBe("Waited 1500ms");
+  });
+
+  it("defaults wait duration when parsed value is negative", async () => {
+    const page = createPage();
+
+    const result = await executeReplaySpecialAction({
+      taskId: "task-6",
+      actionType: "wait",
+      actionParams: { duration: -5 },
+      page: page as unknown as Page,
+    });
+
+    expect(page.waitForTimeout).toHaveBeenCalledWith(1000);
+    expect(result?.output).toBe("Waited 1000ms");
+  });
+
+  it("caps oversized wait duration values to safe maximum", async () => {
+    const page = createPage();
+
+    const result = await executeReplaySpecialAction({
+      taskId: "task-wait-cap",
+      actionType: "wait",
+      arguments: [999_999],
+      page: page as unknown as Page,
+    });
+
+    expect(page.waitForTimeout).toHaveBeenCalledWith(120_000);
+    expect(result?.output).toBe("Waited 120000ms");
+  });
+
+  it("fails extract replay when instruction is missing", async () => {
+    const page = createPage({
+      extract: jest.fn(),
+    });
+
+    const result = await executeReplaySpecialAction({
+      taskId: "task-3",
+      actionType: "extract",
+      page: page as unknown as Page,
+    });
+
+    expect(result?.status).toBe("failed");
+    expect(result?.output).toContain("Missing objective/instruction");
+  });
+
+  it("fails extract replay when instruction is only whitespace", async () => {
+    const extract = jest.fn();
+    const page = createPage({
+      extract,
+    });
+
+    const result = await executeReplaySpecialAction({
+      taskId: "task-7",
+      actionType: "extract",
+      instruction: "   ",
+      page: page as unknown as Page,
+    });
+
+    expect(result?.status).toBe("failed");
+    expect(result?.output).toContain("Missing objective/instruction");
+    expect(extract).not.toHaveBeenCalled();
+  });
+
+  it("returns null for non-special actions", async () => {
+    const page = createPage();
+
+    const result = await executeReplaySpecialAction({
+      taskId: "task-4",
+      actionType: "actElement",
+      page: page as unknown as Page,
+    });
+
+    expect(result).toBeNull();
+  });
+
+  it("replays waitForLoadState with timeout argument", async () => {
+    const page = createPage();
+
+    const result = await executeReplaySpecialAction({
+      taskId: "task-loadstate",
+      actionType: "waitForLoadState",
+      arguments: ["networkidle", 2500],
+      page: page as unknown as Page,
+    });
+
+    expect(page.waitForLoadState).toHaveBeenCalledWith("networkidle", {
+      timeout: 2500,
+    });
+    expect(waitForSettledDOM).toHaveBeenCalledWith(
+      page,
+      undefined,
+      expect.objectContaining({
+        filterAdTrackingFrames: undefined,
+      })
+    );
+    expect(markDomSnapshotDirty).toHaveBeenCalledWith(page);
+    expect(result?.status).toBe("completed");
+    expect(result?.output).toBe("Waited for load state: networkidle");
+  });
+
+  it("defaults waitForLoadState to domcontentloaded for unsupported values", async () => {
+    const page = createPage();
+
+    const result = await executeReplaySpecialAction({
+      taskId: "task-loadstate-invalid",
+      actionType: "waitForLoadState",
+      arguments: ["interactive"],
+      page: page as unknown as Page,
+    });
+
+    expect(page.waitForLoadState).toHaveBeenCalledWith("domcontentloaded", undefined);
+    expect(result?.status).toBe("completed");
+    expect(result?.output).toBe("Waited for load state: domcontentloaded");
+  });
+
+  it("normalizes waitForLoadState value case-insensitively", async () => {
+    const page = createPage();
+
+    const result = await executeReplaySpecialAction({
+      taskId: "task-loadstate-uppercase",
+      actionType: "waitForLoadState",
+      arguments: ["LOAD"],
+      page: page as unknown as Page,
+    });
+
+    expect(page.waitForLoadState).toHaveBeenCalledWith("load", undefined);
+    expect(result?.status).toBe("completed");
+    expect(result?.output).toBe("Waited for load state: load");
+  });
+
+  it("parses string timeout for waitForLoadState", async () => {
+    const page = createPage();
+
+    await executeReplaySpecialAction({
+      taskId: "task-loadstate-timeout-string",
+      actionType: "waitForLoadState",
+      arguments: ["load", "1800"],
+      page: page as unknown as Page,
+    });
+
+    expect(page.waitForLoadState).toHaveBeenCalledWith("load", { timeout: 1800 });
+  });
+
+  it("uses actionParams fallback for waitForLoadState values", async () => {
+    const page = createPage();
+
+    await executeReplaySpecialAction({
+      taskId: "task-loadstate-actionparams",
+      actionType: "waitForLoadState",
+      actionParams: {
+        waitUntil: "networkidle",
+        timeout: 2200,
+      },
+      page: page as unknown as Page,
+    });
+
+    expect(page.waitForLoadState).toHaveBeenCalledWith("networkidle", {
+      timeout: 2200,
+    });
+  });
+
+  it("omits negative waitForLoadState timeout values", async () => {
+    const page = createPage();
+
+    await executeReplaySpecialAction({
+      taskId: "task-loadstate-negative-timeout",
+      actionType: "waitForLoadState",
+      arguments: ["load", -1],
+      page: page as unknown as Page,
+    });
+
+    expect(page.waitForLoadState).toHaveBeenCalledWith("load", undefined);
+  });
+
+  it("caps oversized waitForLoadState timeout values", async () => {
+    const page = createPage();
+
+    await executeReplaySpecialAction({
+      taskId: "task-loadstate-timeout-cap",
+      actionType: "waitForLoadState",
+      arguments: ["load", 999_999],
+      page: page as unknown as Page,
+    });
+
+    expect(page.waitForLoadState).toHaveBeenCalledWith("load", {
+      timeout: 120_000,
+    });
+  });
+
+  it("continues waitForLoadState replay when settle wait fails", async () => {
+    const page = createPage();
+    waitForSettledDOM.mockRejectedValueOnce(new Error("settle failed"));
+
+    const result = await executeReplaySpecialAction({
+      taskId: "task-loadstate-settle-fail",
+      actionType: "waitForLoadState",
+      arguments: ["load"],
+      page: page as unknown as Page,
+    });
+
+    expect(page.waitForLoadState).toHaveBeenCalledWith("load", undefined);
+    expect(result?.status).toBe("completed");
+    expect(result?.output).toBe("Waited for load state: load");
+  });
+
+  it("fails extract replay when extracted object cannot be serialized", async () => {
+    const circular: Record<string, unknown> = {};
+    circular.self = circular;
+    const extract = jest.fn().mockResolvedValue(circular);
+    const page = createPage({
+      extract,
+    });
+
+    const result = await executeReplaySpecialAction({
+      taskId: "task-circular-extract",
+      actionType: "extract",
+      instruction: "extract circular object",
+      page: page as unknown as Page,
+    });
+
+    expect(result?.status).toBe("failed");
+    expect(result?.output).toContain("could not serialize extracted output");
+  });
+
+  it("fails extract replay when serialization returns undefined", async () => {
+    const extract = jest.fn().mockResolvedValue(undefined);
+    const page = createPage({
+      extract,
+    });
+
+    const result = await executeReplaySpecialAction({
+      taskId: "task-undefined-extract",
+      actionType: "extract",
+      instruction: "extract undefined",
+      page: page as unknown as Page,
+    });
+
+    expect(result?.status).toBe("failed");
+    expect(result?.output).toContain("could not serialize extracted output");
+  });
+
+  it("formats object-thrown extract errors as readable JSON", async () => {
+    const extract = jest.fn().mockRejectedValue({ reason: "bad extract" });
+    const page = createPage({
+      extract,
+    });
+
+    const result = await executeReplaySpecialAction({
+      taskId: "task-object-error-extract",
+      actionType: "extract",
+      instruction: "extract info",
+      page: page as unknown as Page,
+    });
+
+    expect(result?.status).toBe("failed");
+    expect(result?.output).toContain('Extract failed: {"reason":"bad extract"}');
+  });
+
+  it("truncates oversized extract failure diagnostics", async () => {
+    const extract = jest
+      .fn()
+      .mockRejectedValue(new Error(`x${"y".repeat(2_000)}\nextract failed`));
+    const page = createPage({
+      extract,
+    });
+
+    const result = await executeReplaySpecialAction({
+      taskId: "task-oversized-extract-error",
+      actionType: "extract",
+      instruction: "extract info",
+      page: page as unknown as Page,
+    });
+
+    expect(result?.status).toBe("failed");
+    expect(result?.output).toContain("[truncated");
+    expect(result?.output).not.toContain("\n");
+  });
+
+  it("truncates oversized extract outputs", async () => {
+    const extract = jest
+      .fn()
+      .mockResolvedValue(`x${"y".repeat(5_000)}\nextract output`);
+    const page = createPage({
+      extract,
+    });
+
+    const result = await executeReplaySpecialAction({
+      taskId: "task-oversized-extract-output",
+      actionType: "extract",
+      instruction: "extract info",
+      page: page as unknown as Page,
+    });
+
+    expect(result?.status).toBe("completed");
+    expect(result?.output).toContain("[truncated");
+    expect(result?.output).not.toContain("\n");
+  });
+
+  it("honors explicit retry metadata value", async () => {
+    const page = createPage();
+
+    const result = await executeReplaySpecialAction({
+      taskId: "task-5",
+      actionType: "complete",
+      page: page as unknown as Page,
+      retries: 3,
+    });
+
+    expect(result?.replayStepMeta?.retries).toBe(3);
+  });
+
+  it("normalizes invalid retry metadata to a minimum value", async () => {
+    const page = createPage();
+
+    const result = await executeReplaySpecialAction({
+      taskId: "task-retries",
+      actionType: "complete",
+      page: page as unknown as Page,
+      retries: -2,
+    });
+
+    expect(result?.replayStepMeta?.retries).toBe(1);
+  });
+
+  it("returns failed output when top-level input getters throw", async () => {
+    const params = new Proxy(
+      {},
+      {
+        get: (_target, prop) => {
+          if (prop === "taskId") {
+            throw new Error("taskId trap");
+          }
+          return undefined;
+        },
+      }
+    );
+
+    const result = await executeReplaySpecialAction(
+      params as unknown as Parameters<typeof executeReplaySpecialAction>[0]
+    );
+
+    expect(result?.status).toBe("failed");
+    expect(result?.output).toContain("Invalid replay input: taskId trap");
+    expect(result?.taskId).toBe("unknown-replay-task");
+  });
+
+  it("truncates oversized top-level input trap diagnostics", async () => {
+    const params = new Proxy(
+      {},
+      {
+        get: (_target, prop) => {
+          if (prop === "taskId") {
+            throw new Error(`x${"y".repeat(2_000)}\ntrap`);
+          }
+          return undefined;
+        },
+      }
+    );
+
+    const result = await executeReplaySpecialAction(
+      params as unknown as Parameters<typeof executeReplaySpecialAction>[0]
+    );
+
+    expect(result?.status).toBe("failed");
+    expect(result?.output).toContain("[truncated");
+    expect(result?.output).not.toContain("\n");
+  });
+
+  it("falls back to actionParams URL when goToUrl argument access traps throw", async () => {
+    const trappedArgs = new Proxy(["https://bad.example"], {
+      get: (target, prop, receiver) => {
+        if (prop === "0") {
+          throw new Error("arg index trap");
+        }
+        return Reflect.get(target, prop, receiver);
+      },
+    });
+    const page = createPage();
+
+    const result = await executeReplaySpecialAction({
+      taskId: "task-go-url-fallback",
+      actionType: "goToUrl",
+      arguments: trappedArgs as unknown as Array<string | number>,
+      actionParams: { url: "https://example.com" },
+      page: page as unknown as Page,
+    });
+
+    expect(page.goto).toHaveBeenCalledWith("https://example.com", {
+      waitUntil: "domcontentloaded",
+    });
+    expect(result?.status).toBe("completed");
+  });
+});
diff --git a/src/agent/shared/replay-special-actions.ts b/src/agent/shared/replay-special-actions.ts
new file mode 100644
index 00000000..e355589c
--- /dev/null
+++ b/src/agent/shared/replay-special-actions.ts
@@ -0,0 +1,422 @@
+import type { Page } from "playwright-core";
+import { formatUnknownError } from "@/utils";
+import { waitForSettledDOM } from "@/utils/waitForSettledDOM";
+import { markDomSnapshotDirty } from "@/context-providers/a11y-dom/dom-cache";
+import { TaskOutput, TaskStatus } from "@/types/agent/types";
+
+interface ReplaySpecialActionInput {
+  taskId: string;
+  actionType: string;
+  instruction?: string;
+  arguments?: Array<string | number>;
+  actionParams?: Record<string, unknown>;
+  page: Page;
+  retries?: number;
+  filterAdTrackingFrames?: boolean;
+}
+
+const MAX_REPLAY_WAIT_MS = 120_000;
+const MAX_REPLAY_TIMEOUT_MS = 120_000;
+const MAX_REPLAY_SPECIAL_OUTPUT_CHARS = 4_000;
+const MAX_REPLAY_SPECIAL_DIAGNOSTIC_CHARS = 400;
+const MAX_REPLAY_SPECIAL_IDENTIFIER_CHARS = 128;
+
+export const REPLAY_SPECIAL_ACTION_TYPES: ReadonlySet<string> = new Set([
+  "goToUrl",
+  "complete",
+  "refreshPage",
+  "wait",
+  "waitForLoadState",
+  "extract",
+  "analyzePdf",
+]);
+
+function createReplayMeta(
+  retries: number
+): NonNullable<TaskOutput["replayStepMeta"]> {
+  return {
+    usedCachedAction: true,
+    fallbackUsed: false,
+    retries,
+    cachedXPath: null,
+    fallbackXPath: null,
+    fallbackElementId: null,
+  };
+}
+
+function asString(value: unknown): string | undefined {
+  return typeof value === "string" ? value : undefined;
+}
+
+function asNonEmptyTrimmedString(value: unknown): string | undefined {
+  const parsed = asString(value)?.trim();
+  return parsed && parsed.length > 0 ? parsed : undefined;
+}
+
+function asNumber(value: unknown): number | undefined {
+  if (typeof value === "number" && Number.isFinite(value)) {
+    return value;
+  }
+  if (typeof value === "string") {
+    const parsed = Number.parseInt(value, 10);
+    return Number.isFinite(parsed) ? parsed : undefined;
+  }
+  return undefined;
+}
+
+function sanitizeReplaySpecialText(value: string): string {
+  if (value.length === 0) {
+    return value;
+  }
+  const withoutControlChars = Array.from(value, (char) => {
+    const code = char.charCodeAt(0);
+    return (code >= 0 && code < 32) || code === 127 ? " " : char;
+  }).join("");
+  return withoutControlChars.replace(/\s+/g, " ").trim();
+}
+
+function truncateReplaySpecialText(
+  value: string,
+  maxChars: number
+): string {
+  if (value.length <= maxChars) {
+    return value;
+  }
+  const omitted = value.length - maxChars;
+  return `${value.slice(0, maxChars)}... [truncated ${omitted} chars]`;
+}
+
+function formatReplaySpecialDiagnostic(value: unknown): string {
+  const normalized = sanitizeReplaySpecialText(formatUnknownError(value));
+  const fallback = normalized.length > 0 ? normalized : "unknown error";
+  return truncateReplaySpecialText(
+    fallback,
+    MAX_REPLAY_SPECIAL_DIAGNOSTIC_CHARS
+  );
+}
+
+function normalizeReplaySpecialOutput(
+  value: unknown,
+  fallback: string
+): string {
+  if (typeof value !== "string") {
+    return fallback;
+  }
+  if (value.length === 0) {
+    return value;
+  }
+  const normalized = sanitizeReplaySpecialText(value);
+  if (normalized.length === 0) {
+    return fallback;
+  }
+  return truncateReplaySpecialText(normalized, MAX_REPLAY_SPECIAL_OUTPUT_CHARS);
+}
+
+function normalizeReplaySpecialIdentifier(
+  value: unknown,
+  fallback: string
+): string {
+  if (typeof value !== "string") {
+    return fallback;
+  }
+  const normalized = sanitizeReplaySpecialText(value);
+  if (normalized.length === 0) {
+    return fallback;
+  }
+  return truncateReplaySpecialText(
+    normalized,
+    MAX_REPLAY_SPECIAL_IDENTIFIER_CHARS
+  );
+}
+
+function safeReadArrayIndex(
+  value: unknown,
+  index: number
+): unknown {
+  if (!Array.isArray(value)) {
+    return undefined;
+  }
+  try {
+    return value[index];
+  } catch {
+    return undefined;
+  }
+}
+
+function safeReadRecordField(
+  value: unknown,
+  key: string
+): unknown {
+  if (!value || typeof value !== "object") {
+    return undefined;
+  }
+  try {
+    return (value as Record<string, unknown>)[key];
+  } catch {
+    return undefined;
+  }
+}
+
+function normalizeRetryCount(value: unknown): number {
+  const parsed = asNumber(value);
+  if (parsed === undefined || parsed <= 0) {
+    return 1;
+  }
+  return Math.floor(parsed);
+}
+
+function normalizeWaitMs(value: unknown): number {
+  const parsed = asNumber(value);
+  if (parsed === undefined) {
+    return 1000;
+  }
+  if (parsed < 0) {
+    return 1000;
+  }
+  return Math.min(parsed, MAX_REPLAY_WAIT_MS);
+}
+
+function normalizeOptionalTimeoutMs(value: unknown): number | undefined {
+  const parsed = asNumber(value);
+  if (parsed === undefined) {
+    return undefined;
+  }
+  if (parsed < 0) {
+    return undefined;
+  }
+  return Math.min(parsed, MAX_REPLAY_TIMEOUT_MS);
+}
+
+function normalizeWaitUntil(value: unknown): "domcontentloaded" | "load" | "networkidle" {
+  const parsed = asNonEmptyTrimmedString(value)?.toLowerCase();
+  if (parsed === "load" || parsed === "networkidle") {
+    return parsed;
+  }
+  return "domcontentloaded";
+}
+
+function serializeUnknown(value: unknown): string {
+  const serialized = JSON.stringify(value);
+  if (serialized === undefined) {
+    throw new Error("serialization produced undefined");
+  }
+  return serialized;
+}
+
+export async function executeReplaySpecialAction(
+  params: ReplaySpecialActionInput
+): Promise<TaskOutput | null> {
+  let taskId: unknown;
+  let actionType: unknown;
+  let actionArgs: unknown;
+  let actionParams: unknown;
+  let instruction: unknown;
+  let page: unknown;
+  let retries: unknown;
+  let filterAdTrackingFrames: unknown;
+  try {
+    taskId = params.taskId;
+    actionType = params.actionType;
+    actionArgs = params.arguments;
+    actionParams = params.actionParams;
+    instruction = params.instruction;
+    page = params.page;
+    retries = params.retries;
+    filterAdTrackingFrames = params.filterAdTrackingFrames;
+  } catch (error) {
+    return {
+      taskId: "unknown-replay-task",
+      status: TaskStatus.FAILED,
+      steps: [],
+      output: `Invalid replay input: ${formatReplaySpecialDiagnostic(error)}`,
+      replayStepMeta: createReplayMeta(1),
+    };
+  }
+
+  const normalizedTaskId = normalizeReplaySpecialIdentifier(
+    taskId,
+    "unknown-replay-task"
+  );
+  const normalizedActionType = asNonEmptyTrimmedString(actionType);
+  const normalizedRetries = normalizeRetryCount(retries);
+  const normalizedInstruction = asString(instruction);
+  const replayPage = page as Page;
+  const normalizedFilterAdTrackingFrames =
+    typeof filterAdTrackingFrames === "boolean"
+      ? filterAdTrackingFrames
+      : undefined;
+
+  if (!normalizedActionType) {
+    return null;
+  }
+
+  if (normalizedActionType === "goToUrl") {
+    const url =
+      asNonEmptyTrimmedString(safeReadArrayIndex(actionArgs, 0)) ??
+      asNonEmptyTrimmedString(safeReadRecordField(actionParams, "url")) ??
+      "";
+    if (!url) {
+      return {
+        taskId: normalizedTaskId,
+        status: TaskStatus.FAILED,
+        steps: [],
+        output: "Missing URL for goToUrl",
+        replayStepMeta: createReplayMeta(normalizedRetries),
+      };
+    }
+    await replayPage.goto(url, { waitUntil: "domcontentloaded" });
+    await waitForSettledDOM(replayPage, undefined, {
+      filterAdTrackingFrames: normalizedFilterAdTrackingFrames,
+    });
+    markDomSnapshotDirty(replayPage);
+    return {
+      taskId: normalizedTaskId,
+      status: TaskStatus.COMPLETED,
+      steps: [],
+      output: `Navigated to ${normalizeReplaySpecialOutput(url, "about:blank")}`,
+      replayStepMeta: createReplayMeta(normalizedRetries),
+    };
+  }
+
+  if (normalizedActionType === "complete") {
+    return {
+      taskId: normalizedTaskId,
+      status: TaskStatus.COMPLETED,
+      steps: [],
+      output: "Task Complete",
+      replayStepMeta: createReplayMeta(normalizedRetries),
+    };
+  }
+
+  if (normalizedActionType === "refreshPage") {
+    await replayPage.reload({ waitUntil: "domcontentloaded" });
+    await waitForSettledDOM(replayPage, undefined, {
+      filterAdTrackingFrames: normalizedFilterAdTrackingFrames,
+    });
+    markDomSnapshotDirty(replayPage);
+    return {
+      taskId: normalizedTaskId,
+      status: TaskStatus.COMPLETED,
+      steps: [],
+      output: "Page refreshed",
+      replayStepMeta: createReplayMeta(normalizedRetries),
+    };
+  }
+
+  if (normalizedActionType === "wait") {
+    const waitMs = normalizeWaitMs(
+      safeReadArrayIndex(actionArgs, 0) ?? safeReadRecordField(actionParams, "duration")
+    );
+    await replayPage.waitForTimeout(waitMs);
+    markDomSnapshotDirty(replayPage);
+    return {
+      taskId: normalizedTaskId,
+      status: TaskStatus.COMPLETED,
+      steps: [],
+      output: `Waited ${waitMs}ms`,
+      replayStepMeta: createReplayMeta(normalizedRetries),
+    };
+  }
+
+  if (normalizedActionType === "extract") {
+    const extractPage = replayPage as Page & {
+      extract?: (objective: string) => Promise<string | unknown>;
+    };
+    const extractInstruction = normalizedInstruction?.trim();
+    if (!extractInstruction) {
+      return {
+        taskId: normalizedTaskId,
+        status: TaskStatus.FAILED,
+        steps: [],
+        output: "Missing objective/instruction for extract action",
+        replayStepMeta: createReplayMeta(normalizedRetries),
+      };
+    }
+    if (!extractPage.extract) {
+      return {
+        taskId: normalizedTaskId,
+        status: TaskStatus.FAILED,
+        steps: [],
+        output: "Extract replay is unavailable on this page instance.",
+        replayStepMeta: createReplayMeta(normalizedRetries),
+      };
+    }
+    try {
+      const extracted = await extractPage.extract(extractInstruction);
+      let serializedExtracted = "";
+      if (typeof extracted === "string") {
+        serializedExtracted = extracted;
+      } else {
+        try {
+          serializedExtracted = serializeUnknown(extracted);
+        } catch (error) {
+          const message = formatReplaySpecialDiagnostic(error);
+          return {
+            taskId: normalizedTaskId,
+            status: TaskStatus.FAILED,
+            steps: [],
+            output: `Extract failed: could not serialize extracted output (${message})`,
+            replayStepMeta: createReplayMeta(normalizedRetries),
+          };
+        }
+      }
+      return {
+        taskId: normalizedTaskId,
+        status: TaskStatus.COMPLETED,
+        steps: [],
+        output: normalizeReplaySpecialOutput(
+          serializedExtracted,
+          "Extract completed."
+        ),
+        replayStepMeta: createReplayMeta(normalizedRetries),
+      };
+    } catch (error) {
+      const message = formatReplaySpecialDiagnostic(error);
+      return {
+        taskId: normalizedTaskId,
+        status: TaskStatus.FAILED,
+        steps: [],
+        output: `Extract failed: ${message}`,
+        replayStepMeta: createReplayMeta(normalizedRetries),
+      };
+    }
+  }
+
+  if (normalizedActionType === "analyzePdf") {
+    return {
+      taskId: normalizedTaskId,
+      status: TaskStatus.FAILED,
+      steps: [],
+      output: "analyzePdf replay is not supported in runFromActionCache.",
+      replayStepMeta: createReplayMeta(normalizedRetries),
+    };
+  }
+
+  if (normalizedActionType === "waitForLoadState") {
+    const waitUntil = normalizeWaitUntil(
+      safeReadArrayIndex(actionArgs, 0) ?? safeReadRecordField(actionParams, "waitUntil")
+    );
+    const timeoutMs = normalizeOptionalTimeoutMs(
+      safeReadArrayIndex(actionArgs, 1) ?? safeReadRecordField(actionParams, "timeout")
+    );
+    const options =
+      timeoutMs !== undefined ? { timeout: timeoutMs } : undefined;
+    await replayPage.waitForLoadState(
+      waitUntil,
+      options
+    );
+    await waitForSettledDOM(replayPage, undefined, {
+      filterAdTrackingFrames: normalizedFilterAdTrackingFrames,
+    }).catch(() => undefined);
+    markDomSnapshotDirty(replayPage);
+    return {
+      taskId: normalizedTaskId,
+      status: TaskStatus.COMPLETED,
+      steps: [],
+      output: `Waited for load state: ${waitUntil}`,
+      replayStepMeta: createReplayMeta(normalizedRetries),
+    };
+  }
+
+  return null;
+}
diff --git a/src/agent/shared/run-cached-action.test.ts b/src/agent/shared/run-cached-action.test.ts
new file mode 100644
index 00000000..034d1e68
--- /dev/null
+++ b/src/agent/shared/run-cached-action.test.ts
@@ -0,0 +1,802 @@
+import { runCachedStep } from "@/agent/shared/run-cached-action";
+import { TaskStatus } from "@/types/agent/types";
+import type { HyperAgentLLM } from "@/llm/types";
+
+jest.mock("uuid", () => ({
+  v4: () => "task-uuid",
+}));
+
+jest.mock("@/agent/shared/replay-special-actions", () => ({
+  executeReplaySpecialAction: jest.fn(),
+}));
+
+jest.mock("@/utils/waitForSettledDOM", () => ({
+  waitForSettledDOM: jest.fn(),
+}));
+
+jest.mock("@/context-providers/a11y-dom/dom-cache", () => ({
+  markDomSnapshotDirty: jest.fn(),
+}));
+
+jest.mock("@/agent/shared/dom-capture", () => ({
+  captureDOMState: jest.fn(),
+}));
+
+jest.mock("@/agent/shared/runtime-context", () => ({
+  initializeRuntimeContext: jest.fn(),
+}));
+
+jest.mock("@/agent/shared/xpath-cdp-resolver", () => ({
+  resolveXPathWithCDP: jest.fn(),
+}));
+
+jest.mock("@/agent/actions/shared/perform-action", () => ({
+  performAction: jest.fn(),
+}));
+
+const { executeReplaySpecialAction } = jest.requireMock(
+  "@/agent/shared/replay-special-actions"
+) as {
+  executeReplaySpecialAction: jest.Mock;
+};
+
+const { waitForSettledDOM } = jest.requireMock(
+  "@/utils/waitForSettledDOM"
+) as {
+  waitForSettledDOM: jest.Mock;
+};
+
+const { captureDOMState } = jest.requireMock("@/agent/shared/dom-capture") as {
+  captureDOMState: jest.Mock;
+};
+
+const { initializeRuntimeContext } = jest.requireMock(
+  "@/agent/shared/runtime-context"
+) as {
+  initializeRuntimeContext: jest.Mock;
+};
+
+const { resolveXPathWithCDP } = jest.requireMock(
+  "@/agent/shared/xpath-cdp-resolver"
+) as {
+  resolveXPathWithCDP: jest.Mock;
+};
+
+const { performAction } = jest.requireMock(
+  "@/agent/actions/shared/perform-action"
+) as {
+  performAction: jest.Mock;
+};
+
+function createMockLLM(): HyperAgentLLM {
+  return {
+    invoke: async () => ({ role: "assistant", content: "ok" }),
+    invokeStructured: async () => ({ rawText: "{}", parsed: null }),
+    getProviderId: () => "mock",
+    getModelId: () => "mock-model",
+    getCapabilities: () => ({
+      multimodal: false,
+      toolCalling: true,
+      jsonMode: true,
+    }),
+  };
+}
+
+function createMockPage() {
+  return {
+    goto: jest.fn().mockResolvedValue(undefined),
+    waitForTimeout: jest.fn().mockResolvedValue(undefined),
+    reload: jest.fn().mockResolvedValue(undefined),
+  } as unknown as import("playwright-core").Page;
+}
+
+describe("runCachedStep", () => {
+  beforeEach(() => {
+    jest.clearAllMocks();
+    waitForSettledDOM.mockResolvedValue(undefined);
+    captureDOMState.mockResolvedValue({
+      elements: new Map(),
+      domState: "",
+      xpathMap: {},
+      backendNodeMap: {},
+    });
+    initializeRuntimeContext.mockResolvedValue({
+      cdpClient: {},
+      frameContextManager: {},
+    });
+    performAction.mockResolvedValue({
+      success: true,
+      message: "ok",
+    });
+  });
+
+  it("uses shared special action result metadata", async () => {
+    executeReplaySpecialAction.mockResolvedValue({
+      taskId: "task-uuid",
+      status: TaskStatus.COMPLETED,
+      steps: [],
+      output: "Task Complete",
+      replayStepMeta: {
+        usedCachedAction: true,
+        fallbackUsed: false,
+        retries: 1,
+        cachedXPath: null,
+        fallbackXPath: null,
+        fallbackElementId: null,
+      },
+    });
+
+    const result = await runCachedStep({
+      page: createMockPage(),
+      instruction: "done",
+      cachedAction: {
+        actionType: "complete",
+      },
+      tokenLimit: 8000,
+      llm: createMockLLM(),
+      mcpClient: undefined,
+      variables: [],
+    });
+
+    expect(result.status).toBe(TaskStatus.COMPLETED);
+    expect(result.replayStepMeta?.retries).toBe(1);
+  });
+
+  it("skips CDP XPath resolution when cdpActionsEnabled is false", async () => {
+    executeReplaySpecialAction.mockResolvedValue(null);
+    const page = createMockPage();
+
+    const result = await runCachedStep({
+      page,
+      instruction: "click login",
+      cachedAction: {
+        actionType: "actElement",
+        method: "click",
+        xpath: "//button[1]",
+        frameIndex: 0,
+      },
+      cdpActionsEnabled: false,
+      tokenLimit: 8000,
+      llm: createMockLLM(),
+      mcpClient: undefined,
+      variables: [],
+    });
+
+    expect(result.status).toBe(TaskStatus.COMPLETED);
+    expect(initializeRuntimeContext).not.toHaveBeenCalled();
+    expect(resolveXPathWithCDP).not.toHaveBeenCalled();
+    expect(performAction).toHaveBeenCalledWith(
+      expect.objectContaining({
+        cdpActions: false,
+        cdp: undefined,
+      }),
+      expect.objectContaining({
+        elementId: "0-0",
+        method: "click",
+      })
+    );
+  });
+
+  it("sanitizes oversized special action outputs before returning", async () => {
+    executeReplaySpecialAction.mockResolvedValue({
+      taskId: "task-uuid",
+      status: TaskStatus.COMPLETED,
+      steps: [],
+      output: `x${"y".repeat(5_000)}\nunsafe`,
+      replayStepMeta: {
+        usedCachedAction: true,
+        fallbackUsed: false,
+        retries: 2,
+        cachedXPath: "//button[1]",
+        fallbackXPath: null,
+        fallbackElementId: null,
+      },
+    });
+
+    const result = await runCachedStep({
+      page: createMockPage(),
+      instruction: "done",
+      cachedAction: {
+        actionType: "complete",
+      },
+      tokenLimit: 8000,
+      llm: createMockLLM(),
+      mcpClient: undefined,
+      variables: [],
+    });
+
+    expect(result.status).toBe(TaskStatus.COMPLETED);
+    expect(result.output).toContain("[truncated");
+    expect(result.output).not.toContain("\n");
+    expect(result.replayStepMeta?.retries).toBe(2);
+    expect(result.replayStepMeta?.cachedXPath).toBe("//button[1]");
+  });
+
+  it("normalizes malformed special action payloads safely", async () => {
+    executeReplaySpecialAction.mockResolvedValue({
+      taskId: "  ",
+      status: "bad-status",
+      steps: [],
+      output: { bad: true },
+      replayStepMeta: {
+        retries: "bad",
+      },
+    });
+
+    const result = await runCachedStep({
+      page: createMockPage(),
+      instruction: "done",
+      cachedAction: {
+        actionType: "complete",
+      },
+      tokenLimit: 8000,
+      llm: createMockLLM(),
+      mcpClient: undefined,
+      variables: [],
+    });
+
+    expect(result.status).toBe(TaskStatus.FAILED);
+    expect(result.output).toBe("Special cached action failed.");
+    expect(result.replayStepMeta).toEqual(
+      expect.objectContaining({
+        usedCachedAction: true,
+        retries: 1,
+      })
+    );
+  });
+
+  it("returns unsupported error for non-special non-actElement actions", async () => {
+    executeReplaySpecialAction.mockResolvedValue(null);
+
+    const result = await runCachedStep({
+      page: createMockPage(),
+      instruction: "noop",
+      cachedAction: {
+        actionType: "unknown",
+      },
+      tokenLimit: 8000,
+      llm: createMockLLM(),
+      mcpClient: undefined,
+      variables: [],
+    });
+
+    expect(result.status).toBe(TaskStatus.FAILED);
+    expect(result.output).toBe("Unsupported cached action");
+    expect(result.replayStepMeta).toEqual(
+      expect.objectContaining({
+        usedCachedAction: true,
+        fallbackUsed: false,
+        retries: 1,
+      })
+    );
+  });
+
+  it("treats whitespace xpath or method as unsupported cached action", async () => {
+    executeReplaySpecialAction.mockResolvedValue(null);
+
+    const whitespaceXPathResult = await runCachedStep({
+      page: createMockPage(),
+      instruction: "click login",
+      cachedAction: {
+        actionType: "actElement",
+        xpath: "   ",
+        method: "click",
+      },
+      tokenLimit: 8000,
+      llm: createMockLLM(),
+      mcpClient: undefined,
+      variables: [],
+    });
+
+    const whitespaceMethodResult = await runCachedStep({
+      page: createMockPage(),
+      instruction: "click login",
+      cachedAction: {
+        actionType: "actElement",
+        xpath: "//button[1]",
+        method: "   ",
+      },
+      tokenLimit: 8000,
+      llm: createMockLLM(),
+      mcpClient: undefined,
+      variables: [],
+    });
+
+    expect(whitespaceXPathResult.status).toBe(TaskStatus.FAILED);
+    expect(whitespaceXPathResult.output).toBe("Unsupported cached action");
+    expect(whitespaceMethodResult.status).toBe(TaskStatus.FAILED);
+    expect(whitespaceMethodResult.output).toBe("Unsupported cached action");
+  });
+
+  it("falls back to perform when cached attempts fail", async () => {
+    executeReplaySpecialAction.mockResolvedValue(null);
+    resolveXPathWithCDP.mockRejectedValue(new Error("xpath resolution failed"));
+    const performFallback = jest.fn().mockResolvedValue({
+      taskId: "fallback-task",
+      status: TaskStatus.COMPLETED,
+      steps: [],
+      output: "fallback completed",
+      replayStepMeta: {
+        usedCachedAction: false,
+        fallbackUsed: true,
+        retries: 1,
+        fallbackXPath: "/html/body/button[1]",
+        fallbackElementId: "0-1",
+      },
+    });
+    const logSpy = jest.spyOn(console, "log").mockImplementation(() => {});
+
+    try {
+      const result = await runCachedStep({
+        page: createMockPage(),
+        instruction: "click login",
+        cachedAction: {
+          actionType: "actElement",
+          xpath: "//button[1]",
+          method: "click",
+          frameIndex: 0,
+          arguments: [],
+        },
+        maxSteps: 1,
+        tokenLimit: 8000,
+        llm: createMockLLM(),
+        mcpClient: undefined,
+        variables: [],
+        performFallback,
+      });
+
+      expect(performFallback).toHaveBeenCalledWith("click login");
+      expect(result.status).toBe(TaskStatus.COMPLETED);
+      expect(result.replayStepMeta).toEqual(
+        expect.objectContaining({
+          usedCachedAction: true,
+          fallbackUsed: true,
+          retries: 1,
+          cachedXPath: "//button[1]",
+          fallbackXPath: "/html/body/button[1]",
+          fallbackElementId: "0-1",
+        })
+      );
+      expect(logSpy).not.toHaveBeenCalled();
+    } finally {
+      logSpy.mockRestore();
+    }
+  });
+
+  it("logs cached fallback diagnostics only in debug mode", async () => {
+    executeReplaySpecialAction.mockResolvedValue(null);
+    resolveXPathWithCDP.mockRejectedValue(new Error("xpath resolution failed"));
+    const performFallback = jest.fn().mockResolvedValue({
+      taskId: "fallback-task",
+      status: TaskStatus.COMPLETED,
+      steps: [],
+      output: "fallback completed",
+      replayStepMeta: {
+        usedCachedAction: false,
+        fallbackUsed: true,
+        retries: 1,
+        fallbackXPath: "/html/body/button[1]",
+        fallbackElementId: "0-1",
+      },
+    });
+    const logSpy = jest.spyOn(console, "log").mockImplementation(() => {});
+
+    try {
+      await runCachedStep({
+        page: createMockPage(),
+        instruction: "click login",
+        cachedAction: {
+          actionType: "actElement",
+          xpath: "//button[1]",
+          method: "click",
+          frameIndex: 0,
+          arguments: [],
+        },
+        maxSteps: 1,
+        debug: true,
+        tokenLimit: 8000,
+        llm: createMockLLM(),
+        mcpClient: undefined,
+        variables: [],
+        performFallback,
+      });
+
+      expect(logSpy).toHaveBeenCalledTimes(1);
+    } finally {
+      logSpy.mockRestore();
+    }
+  });
+
+  it("returns failed replay metadata when cached attempts exhaust", async () => {
+    executeReplaySpecialAction.mockResolvedValue(null);
+    resolveXPathWithCDP.mockRejectedValue(new Error("xpath resolution failed"));
+
+    const result = await runCachedStep({
+      page: createMockPage(),
+      instruction: "click login",
+      cachedAction: {
+        actionType: "actElement",
+        xpath: "//button[1]",
+        method: "click",
+        frameIndex: 0,
+        arguments: [],
+      },
+      maxSteps: 2,
+      tokenLimit: 8000,
+      llm: createMockLLM(),
+      mcpClient: undefined,
+      variables: [],
+    });
+
+    expect(result.status).toBe(TaskStatus.FAILED);
+    expect(result.output).toContain("xpath resolution failed");
+    expect(result.replayStepMeta).toEqual(
+      expect.objectContaining({
+        usedCachedAction: true,
+        fallbackUsed: false,
+        retries: 2,
+        cachedXPath: "//button[1]",
+      })
+    );
+  });
+
+  it("returns failed task output when special action execution throws", async () => {
+    executeReplaySpecialAction.mockRejectedValue(new Error("navigation failed"));
+
+    const result = await runCachedStep({
+      page: createMockPage(),
+      instruction: "go to app",
+      cachedAction: {
+        actionType: "goToUrl",
+        arguments: ["https://example.com"],
+      },
+      tokenLimit: 8000,
+      llm: createMockLLM(),
+      mcpClient: undefined,
+      variables: [],
+    });
+
+    expect(result.status).toBe(TaskStatus.FAILED);
+    expect(result.output).toContain("Failed to execute cached special action");
+    expect(result.output).toContain("navigation failed");
+    expect(result.replayStepMeta).toEqual(
+      expect.objectContaining({
+        usedCachedAction: true,
+        fallbackUsed: false,
+        retries: 1,
+      })
+    );
+  });
+
+  it("truncates oversized special-action failure diagnostics", async () => {
+    executeReplaySpecialAction.mockRejectedValue(
+      new Error(`x${"y".repeat(2_000)}\nnavigation failed`)
+    );
+
+    const result = await runCachedStep({
+      page: createMockPage(),
+      instruction: "go to app",
+      cachedAction: {
+        actionType: "goToUrl",
+        arguments: ["https://example.com"],
+      },
+      tokenLimit: 8000,
+      llm: createMockLLM(),
+      mcpClient: undefined,
+      variables: [],
+    });
+
+    expect(result.status).toBe(TaskStatus.FAILED);
+    expect(result.output).toContain("[truncated");
+    expect(result.output).not.toContain("\n");
+  });
+
+  it("returns failed output when perform fallback throws", async () => {
+    executeReplaySpecialAction.mockResolvedValue(null);
+    resolveXPathWithCDP.mockRejectedValue(new Error("xpath resolution failed"));
+    const performFallback = jest
+      .fn()
+      .mockRejectedValue(new Error("perform fallback crashed"));
+
+    const result = await runCachedStep({
+      page: createMockPage(),
+      instruction: "click login",
+      cachedAction: {
+        actionType: "actElement",
+        xpath: "//button[1]",
+        method: "click",
+        frameIndex: 0,
+        arguments: [],
+      },
+      maxSteps: 1,
+      tokenLimit: 8000,
+      llm: createMockLLM(),
+      mcpClient: undefined,
+      variables: [],
+      performFallback,
+    });
+
+    expect(result.status).toBe(TaskStatus.FAILED);
+    expect(result.output).toContain("Fallback perform failed");
+    expect(result.output).toContain("perform fallback crashed");
+    expect(result.replayStepMeta).toEqual(
+      expect.objectContaining({
+        usedCachedAction: true,
+        fallbackUsed: true,
+        retries: 1,
+        cachedXPath: "//button[1]",
+      })
+    );
+  });
+
+  it("truncates oversized fallback failure diagnostics", async () => {
+    executeReplaySpecialAction.mockResolvedValue(null);
+    resolveXPathWithCDP.mockRejectedValue(new Error("xpath resolution failed"));
+    const performFallback = jest
+      .fn()
+      .mockRejectedValue(new Error(`x${"y".repeat(2_000)}\nperform fallback crashed`));
+
+    const result = await runCachedStep({
+      page: createMockPage(),
+      instruction: "click login",
+      cachedAction: {
+        actionType: "actElement",
+        xpath: "//button[1]",
+        method: "click",
+        frameIndex: 0,
+        arguments: [],
+      },
+      maxSteps: 1,
+      tokenLimit: 8000,
+      llm: createMockLLM(),
+      mcpClient: undefined,
+      variables: [],
+      performFallback,
+    });
+
+    expect(result.status).toBe(TaskStatus.FAILED);
+    expect(result.output).toContain("[truncated");
+    expect(result.output).not.toContain("\n");
+  });
+
+  it("normalizes invalid fallback responses safely", async () => {
+    executeReplaySpecialAction.mockResolvedValue(null);
+    resolveXPathWithCDP.mockRejectedValue(new Error("xpath resolution failed"));
+    const performFallback = jest.fn().mockResolvedValue("not-an-object");
+
+    const result = await runCachedStep({
+      page: createMockPage(),
+      instruction: "click login",
+      cachedAction: {
+        actionType: "actElement",
+        xpath: "//button[1]",
+        method: "click",
+        frameIndex: 0,
+        arguments: [],
+      },
+      maxSteps: 1,
+      tokenLimit: 8000,
+      llm: createMockLLM(),
+      mcpClient: undefined,
+      variables: [],
+      performFallback,
+    });
+
+    expect(result.status).toBe(TaskStatus.FAILED);
+    expect(result.output).toContain("invalid response payload");
+    expect(result.replayStepMeta).toEqual(
+      expect.objectContaining({
+        usedCachedAction: true,
+        fallbackUsed: true,
+        retries: 1,
+        cachedXPath: "//button[1]",
+      })
+    );
+  });
+
+  it("handles trap-prone fallback replay metadata getters safely", async () => {
+    executeReplaySpecialAction.mockResolvedValue(null);
+    resolveXPathWithCDP.mockRejectedValue(new Error("xpath resolution failed"));
+    const replayStepMeta = new Proxy(
+      {},
+      {
+        get: (_target, prop) => {
+          if (prop === "fallbackXPath" || prop === "fallbackElementId") {
+            throw new Error("fallback meta trap");
+          }
+          return undefined;
+        },
+      }
+    );
+    const performFallback = jest.fn().mockResolvedValue({
+      taskId: "fallback-task",
+      status: TaskStatus.COMPLETED,
+      output: "fallback done",
+      replayStepMeta,
+    });
+
+    const result = await runCachedStep({
+      page: createMockPage(),
+      instruction: "click login",
+      cachedAction: {
+        actionType: "actElement",
+        xpath: "//button[1]",
+        method: "click",
+        frameIndex: 0,
+        arguments: [],
+      },
+      maxSteps: 1,
+      tokenLimit: 8000,
+      llm: createMockLLM(),
+      mcpClient: undefined,
+      variables: [],
+      performFallback,
+    });
+
+    expect(result.status).toBe(TaskStatus.COMPLETED);
+    expect(result.replayStepMeta).toEqual(
+      expect.objectContaining({
+        fallbackXPath: null,
+        fallbackElementId: null,
+      })
+    );
+  });
+
+  it("normalizes invalid maxSteps values to a single attempt", async () => {
+    executeReplaySpecialAction.mockResolvedValue(null);
+    resolveXPathWithCDP.mockRejectedValue(new Error("xpath resolution failed"));
+
+    const result = await runCachedStep({
+      page: createMockPage(),
+      instruction: "click login",
+      cachedAction: {
+        actionType: "actElement",
+        xpath: "//button[1]",
+        method: "click",
+        frameIndex: 0,
+        arguments: [],
+      },
+      maxSteps: 0,
+      tokenLimit: 8000,
+      llm: createMockLLM(),
+      mcpClient: undefined,
+      variables: [],
+    });
+
+    expect(result.status).toBe(TaskStatus.FAILED);
+    expect(result.replayStepMeta?.retries).toBe(1);
+  });
+
+  it("surfaces non-Error throw values from cached attempts", async () => {
+    executeReplaySpecialAction.mockResolvedValue(null);
+    resolveXPathWithCDP.mockRejectedValue("string failure");
+
+    const result = await runCachedStep({
+      page: createMockPage(),
+      instruction: "click login",
+      cachedAction: {
+        actionType: "actElement",
+        xpath: "//button[1]",
+        method: "click",
+        frameIndex: 0,
+        arguments: [],
+      },
+      maxSteps: 1,
+      tokenLimit: 8000,
+      llm: createMockLLM(),
+      mcpClient: undefined,
+      variables: [],
+    });
+
+    expect(result.status).toBe(TaskStatus.FAILED);
+    expect(result.output).toContain("string failure");
+  });
+
+  it("truncates oversized cached attempt failure diagnostics", async () => {
+    executeReplaySpecialAction.mockResolvedValue(null);
+    resolveXPathWithCDP.mockRejectedValue(new Error(`x${"y".repeat(5_000)}`));
+
+    const result = await runCachedStep({
+      page: createMockPage(),
+      instruction: "click login",
+      cachedAction: {
+        actionType: "actElement",
+        xpath: "//button[1]",
+        method: "click",
+        frameIndex: 0,
+        arguments: [],
+      },
+      maxSteps: 1,
+      tokenLimit: 8000,
+      llm: createMockLLM(),
+      mcpClient: undefined,
+      variables: [],
+    });
+
+    expect(result.status).toBe(TaskStatus.FAILED);
+    expect(result.output).toContain("[truncated");
+    expect(String(result.output ?? "").length).toBeLessThanOrEqual(4100);
+  });
+
+  it("handles trap-prone cached-action getters safely", async () => {
+    executeReplaySpecialAction.mockResolvedValue(null);
+    const cachedAction = new Proxy(
+      {},
+      {
+        get: (_target, prop) => {
+          if (
+            prop === "actionType" ||
+            prop === "xpath" ||
+            prop === "method" ||
+            prop === "arguments" ||
+            prop === "frameIndex" ||
+            prop === "actionParams"
+          ) {
+            throw new Error("cached-action getter trap");
+          }
+          return undefined;
+        },
+      }
+    );
+
+    const result = await runCachedStep({
+      page: createMockPage(),
+      instruction: "click login",
+      cachedAction: cachedAction as unknown as Parameters<typeof runCachedStep>[0]["cachedAction"],
+      tokenLimit: 8000,
+      llm: createMockLLM(),
+      mcpClient: undefined,
+      variables: [],
+    });
+
+    expect(result.status).toBe(TaskStatus.FAILED);
+    expect(result.output).toBe("Unsupported cached action");
+  });
+
+  it("normalizes cached arguments and frame index before action replay", async () => {
+    executeReplaySpecialAction.mockResolvedValue(null);
+    resolveXPathWithCDP.mockResolvedValue({
+      backendNodeId: 222,
+      frameId: "frame-1",
+      objectId: "obj-1",
+      session: {},
+    });
+    performAction.mockResolvedValue({
+      success: true,
+      message: "clicked",
+    });
+    const oversizedArg = "x".repeat(3_500);
+    const manyArgs = Array.from({ length: 30 }, (_, i) => i);
+
+    const result = await runCachedStep({
+      page: createMockPage(),
+      instruction: "click login",
+      cachedAction: {
+        actionType: "actElement",
+        xpath: "//button[1]",
+        method: "click",
+        frameIndex: Number.NaN as unknown as number,
+        arguments: [0, null as unknown as string, oversizedArg, ...manyArgs],
+      },
+      maxSteps: 1,
+      tokenLimit: 8000,
+      llm: createMockLLM(),
+      mcpClient: undefined,
+      variables: [],
+    });
+
+    expect(result.status).toBe(TaskStatus.COMPLETED);
+    const callArgs = performAction.mock.calls[0]?.[1] as {
+      arguments: string[];
+    };
+    expect(callArgs.arguments[0]).toBe("0");
+    expect(callArgs.arguments[1]).toBe("");
+    expect(callArgs.arguments[2]?.length).toBe(2000);
+    expect(callArgs.arguments.length).toBeLessThanOrEqual(20);
+    expect(resolveXPathWithCDP).toHaveBeenCalledWith(
+      expect.objectContaining({
+        frameIndex: 0,
+      })
+    );
+  });
+});
diff --git a/src/agent/shared/run-cached-action.ts b/src/agent/shared/run-cached-action.ts
index 17bae9d5..3fa2fe82 100644
--- a/src/agent/shared/run-cached-action.ts
+++ b/src/agent/shared/run-cached-action.ts
@@ -3,11 +3,15 @@ import { ActionContext } from "@/types";
 import { performAction } from "@/agent/actions/shared/perform-action";
 import { captureDOMState } from "@/agent/shared/dom-capture";
 import { waitForSettledDOM } from "@/utils/waitForSettledDOM";
+import { formatUnknownError } from "@/utils";
 import { markDomSnapshotDirty } from "@/context-providers/a11y-dom/dom-cache";
 import { initializeRuntimeContext } from "@/agent/shared/runtime-context";
 import { resolveXPathWithCDP } from "@/agent/shared/xpath-cdp-resolver";
 import { resolveElement, dispatchCDPAction } from "@/cdp";
+import type { CDPClient } from "@/cdp/types";
+import type { FrameContextManager } from "@/cdp/frame-context-manager";
 import { TaskOutput, TaskStatus } from "@/types/agent/types";
+import { executeReplaySpecialAction } from "@/agent/shared/replay-special-actions";
 
 export interface CachedActionInput {
   actionType: string;
@@ -25,14 +29,276 @@ export interface RunCachedStepParams {
   maxSteps?: number;
   debug?: boolean;
   tokenLimit: number;
-  llm: any;
-  mcpClient: any;
+  llm: ActionContext["llm"];
+  mcpClient: ActionContext["mcpClient"];
   variables: Array<{ key: string; value: string; description: string }>;
   preferScriptBoundingBox?: boolean;
   cdpActionsEnabled?: boolean;
+  filterAdTrackingFrames?: boolean;
   performFallback?: (instruction: string) => Promise<TaskOutput>;
 }
 
+const isRecord = (value: unknown): value is Record<string, unknown> =>
+  typeof value === "object" && value !== null;
+
+const MAX_CACHED_ACTION_ARGS = 20;
+const MAX_CACHED_ACTION_ARG_CHARS = 2_000;
+const MAX_CACHED_ACTION_OUTPUT_CHARS = 4_000;
+const MAX_CACHED_ACTION_DIAGNOSTIC_CHARS = 400;
+const MAX_CACHED_ACTION_DEBUG_LABEL_CHARS = 200;
+
+const sanitizeCachedActionText = (value: string): string => {
+  if (value.length === 0) {
+    return value;
+  }
+  const withoutControlChars = Array.from(value, (char) => {
+    const code = char.charCodeAt(0);
+    return (code >= 0 && code < 32) || code === 127 ? " " : char;
+  }).join("");
+  return withoutControlChars.replace(/\s+/g, " ").trim();
+};
+
+const truncateCachedActionText = (
+  value: string,
+  maxChars: number
+): string => {
+  if (value.length <= maxChars) {
+    return value;
+  }
+  const omitted = value.length - maxChars;
+  return `${value.slice(0, maxChars)}... [truncated ${omitted} chars]`;
+};
+
+const formatCachedActionDiagnostic = (value: unknown): string =>
+  truncateCachedActionText(
+    sanitizeCachedActionText(formatUnknownError(value)) || "unknown error",
+    MAX_CACHED_ACTION_DIAGNOSTIC_CHARS
+  );
+
+const normalizeCachedActionOutputText = (
+  value: unknown,
+  fallback: string
+): string => {
+  if (typeof value !== "string") {
+    return fallback;
+  }
+  if (value.length === 0) {
+    return value;
+  }
+  const sanitized = sanitizeCachedActionText(value);
+  if (sanitized.length === 0) {
+    return fallback;
+  }
+  return truncateCachedActionText(
+    sanitized,
+    MAX_CACHED_ACTION_OUTPUT_CHARS
+  );
+};
+
+const formatCachedActionDebugLabel = (value: unknown, fallback: string): string => {
+  if (typeof value !== "string") {
+    return fallback;
+  }
+  const sanitized = sanitizeCachedActionText(value);
+  if (sanitized.length === 0) {
+    return fallback;
+  }
+  return truncateCachedActionText(sanitized, MAX_CACHED_ACTION_DEBUG_LABEL_CHARS);
+};
+
+const safeReadCachedActionField = (
+  cachedAction: CachedActionInput,
+  key: keyof CachedActionInput
+): unknown => {
+  try {
+    return (cachedAction as unknown as Record<string, unknown>)[key];
+  } catch {
+    return undefined;
+  }
+};
+
+const normalizeOptionalTrimmedString = (value: unknown): string | null => {
+  if (typeof value !== "string") {
+    return null;
+  }
+  const normalized = value.trim();
+  return normalized.length > 0 ? normalized : null;
+};
+
+const normalizeCachedActionArguments = (value: unknown): string[] => {
+  if (!Array.isArray(value)) {
+    return [];
+  }
+  let entries: unknown[];
+  try {
+    entries = Array.from(value);
+  } catch {
+    return [];
+  }
+  return entries.slice(0, MAX_CACHED_ACTION_ARGS).map((entry) => {
+    const normalized = entry == null ? "" : String(entry);
+    if (normalized.length <= MAX_CACHED_ACTION_ARG_CHARS) {
+      return normalized;
+    }
+    return normalized.slice(0, MAX_CACHED_ACTION_ARG_CHARS);
+  });
+};
+
+const normalizeCachedFrameIndex = (value: unknown): number => {
+  if (typeof value !== "number" || !Number.isFinite(value) || value < 0) {
+    return 0;
+  }
+  return Math.floor(value);
+};
+
+const safeReadTaskOutputField = (
+  value: unknown,
+  key: keyof TaskOutput
+): unknown => {
+  if (!value || typeof value !== "object") {
+    return undefined;
+  }
+  try {
+    return (value as Record<string, unknown>)[key];
+  } catch {
+    return undefined;
+  }
+};
+
+const safeReadRecordField = (
+  value: unknown,
+  key: string
+): unknown => {
+  if (!value || typeof value !== "object") {
+    return undefined;
+  }
+  try {
+    return (value as Record<string, unknown>)[key];
+  } catch {
+    return undefined;
+  }
+};
+
+const normalizeTaskStatus = (value: unknown): TaskStatus => {
+  if (
+    value === TaskStatus.COMPLETED ||
+    value === TaskStatus.FAILED ||
+    value === TaskStatus.CANCELLED ||
+    value === TaskStatus.PAUSED ||
+    value === TaskStatus.PENDING ||
+    value === TaskStatus.RUNNING
+  ) {
+    return value;
+  }
+  return TaskStatus.FAILED;
+};
+
+function normalizeFallbackTaskOutput(
+  fallbackResult: unknown,
+  taskId: string,
+  retries: number,
+  cachedXPath: string | null
+): TaskOutput {
+  const status = normalizeTaskStatus(safeReadTaskOutputField(fallbackResult, "status"));
+  const outputValue = safeReadTaskOutputField(fallbackResult, "output");
+  const replayStepMetaValue = safeReadTaskOutputField(
+    fallbackResult,
+    "replayStepMeta"
+  );
+  const normalizedReplayStepMeta = isRecord(replayStepMetaValue)
+    ? replayStepMetaValue
+    : undefined;
+
+  return {
+    taskId:
+      normalizeOptionalTrimmedString(
+        safeReadTaskOutputField(fallbackResult, "taskId")
+      ) ?? taskId,
+    status,
+    steps: [],
+    output: normalizeCachedActionOutputText(
+      outputValue,
+      status === TaskStatus.FAILED
+        ? "Fallback perform returned an invalid response payload."
+        : "Fallback perform completed."
+    ),
+    replayStepMeta: {
+      usedCachedAction: true,
+      fallbackUsed: true,
+      retries,
+      cachedXPath,
+      fallbackXPath:
+        normalizeOptionalTrimmedString(
+          safeReadRecordField(normalizedReplayStepMeta, "fallbackXPath")
+        ) ?? null,
+      fallbackElementId:
+        normalizeOptionalTrimmedString(
+          safeReadRecordField(normalizedReplayStepMeta, "fallbackElementId")
+        ) ?? null,
+    },
+  };
+}
+
+function normalizeSpecialActionTaskOutput(
+  specialResult: unknown,
+  taskId: string,
+  retries: number,
+  cachedXPath: string | null
+): TaskOutput {
+  const status = normalizeTaskStatus(safeReadTaskOutputField(specialResult, "status"));
+  const outputValue = safeReadTaskOutputField(specialResult, "output");
+  const replayStepMetaValue = safeReadTaskOutputField(
+    specialResult,
+    "replayStepMeta"
+  );
+  const normalizedReplayStepMeta = isRecord(replayStepMetaValue)
+    ? replayStepMetaValue
+    : undefined;
+  const rawRetries = safeReadRecordField(normalizedReplayStepMeta, "retries");
+  const normalizedRetries =
+    typeof rawRetries === "number" &&
+    Number.isFinite(rawRetries) &&
+    rawRetries > 0
+      ? Math.floor(rawRetries)
+      : retries;
+
+  return {
+    taskId:
+      normalizeOptionalTrimmedString(
+        safeReadTaskOutputField(specialResult, "taskId")
+      ) ?? taskId,
+    status,
+    steps: [],
+    output: normalizeCachedActionOutputText(
+      outputValue,
+      status === TaskStatus.FAILED
+        ? "Special cached action failed."
+        : "Special cached action completed."
+    ),
+    replayStepMeta: {
+      usedCachedAction: true,
+      fallbackUsed:
+        safeReadRecordField(normalizedReplayStepMeta, "fallbackUsed") === true,
+      retries: normalizedRetries,
+      cachedXPath:
+        normalizeOptionalTrimmedString(
+          safeReadRecordField(normalizedReplayStepMeta, "cachedXPath")
+        ) ?? cachedXPath,
+      fallbackXPath:
+        normalizeOptionalTrimmedString(
+          safeReadRecordField(normalizedReplayStepMeta, "fallbackXPath")
+        ) ?? null,
+      fallbackElementId:
+        normalizeOptionalTrimmedString(
+          safeReadRecordField(normalizedReplayStepMeta, "fallbackElementId")
+        ) ?? null,
+    },
+  };
+}
+
+const normalizeMaxSteps = (value: number): number =>
+  Number.isFinite(value) && value > 0 ? Math.floor(value) : 1;
+
 export async function runCachedStep(
   params: RunCachedStepParams
 ): Promise<TaskOutput> {
@@ -48,80 +314,101 @@ export async function runCachedStep(
     variables,
     preferScriptBoundingBox,
     cdpActionsEnabled,
+    filterAdTrackingFrames,
   } = params;
 
   const taskId = uuidv4();
+  const attempts = normalizeMaxSteps(maxSteps);
+  const normalizedActionType =
+    normalizeOptionalTrimmedString(
+      safeReadCachedActionField(cachedAction, "actionType")
+    ) ?? "unknown";
+  const normalizedXPath = normalizeOptionalTrimmedString(
+    safeReadCachedActionField(cachedAction, "xpath")
+  );
+  const normalizedMethod = normalizeOptionalTrimmedString(
+    safeReadCachedActionField(cachedAction, "method")
+  );
+  const normalizedArguments = normalizeCachedActionArguments(
+    safeReadCachedActionField(cachedAction, "arguments")
+  );
+  const normalizedFrameIndex = normalizeCachedFrameIndex(
+    safeReadCachedActionField(cachedAction, "frameIndex")
+  );
+  const actionParamsValue = safeReadCachedActionField(cachedAction, "actionParams");
+  const normalizedCachedAction: CachedActionInput = {
+    actionType: normalizedActionType,
+    actionParams: isRecord(actionParamsValue) ? actionParamsValue : undefined,
+    arguments: normalizedArguments,
+    frameIndex: normalizedFrameIndex,
+    xpath: normalizedXPath,
+    method: normalizedMethod,
+  };
 
-  if (cachedAction.actionType === "goToUrl") {
-    const url =
-      (cachedAction.arguments && cachedAction.arguments[0]) ||
-      (cachedAction.actionParams as any)?.url ||
-      "";
-    if (!url || typeof url !== "string") {
-      return {
-        taskId,
-        status: TaskStatus.FAILED,
-        steps: [],
-        output: "Missing URL for goToUrl",
-      };
-    }
-    await page.goto(url, { waitUntil: "domcontentloaded" });
-    await waitForSettledDOM(page);
-    markDomSnapshotDirty(page);
+  const specialActionResult = await executeReplaySpecialAction({
+    taskId,
+    actionType: normalizedActionType,
+    instruction,
+    arguments: normalizedArguments,
+    actionParams: normalizedCachedAction.actionParams,
+    page,
+    retries: 1,
+    filterAdTrackingFrames,
+  }).catch((error) => {
+    const message = formatCachedActionDiagnostic(error);
     return {
       taskId,
-      status: TaskStatus.COMPLETED,
+      status: TaskStatus.FAILED,
       steps: [],
-      output: `Navigated to ${url}`,
+      output: `Failed to execute cached special action: ${message}`,
       replayStepMeta: {
         usedCachedAction: true,
         fallbackUsed: false,
         retries: 1,
-        cachedXPath: null,
+        cachedXPath: normalizedXPath ?? null,
         fallbackXPath: null,
         fallbackElementId: null,
       },
-    };
+    } satisfies TaskOutput;
+  });
+  if (specialActionResult) {
+    return normalizeSpecialActionTaskOutput(
+      specialActionResult,
+      taskId,
+      1,
+      normalizedXPath ?? null
+    );
   }
 
-  if (cachedAction.actionType === "complete") {
+  if (
+    normalizedActionType !== "actElement" ||
+    !normalizedXPath ||
+    !normalizedMethod
+  ) {
     return {
       taskId,
-      status: TaskStatus.COMPLETED,
+      status: TaskStatus.FAILED,
       steps: [],
-      output: "Task Complete",
+      output: "Unsupported cached action",
       replayStepMeta: {
         usedCachedAction: true,
         fallbackUsed: false,
         retries: 1,
-        cachedXPath: null,
+        cachedXPath: normalizedXPath ?? null,
         fallbackXPath: null,
         fallbackElementId: null,
       },
     };
   }
 
-  if (
-    cachedAction.actionType !== "actElement" ||
-    !cachedAction.xpath ||
-    !cachedAction.method
-  ) {
-    return {
-      taskId,
-      status: TaskStatus.FAILED,
-      steps: [],
-      output: "Unsupported cached action",
-    };
-  }
-
   let lastError: unknown = null;
 
-  for (let attempt = 0; attempt < maxSteps; attempt++) {
+  for (let attempt = 0; attempt < attempts; attempt++) {
     const attemptIndex = attempt + 1;
     const attemptResult = await runCachedAttempt({
       page,
       instruction,
-      cachedAction,
+      cachedAction: normalizedCachedAction,
       debug,
       tokenLimit,
       llm,
@@ -129,24 +416,27 @@ export async function runCachedStep(
       variables,
       preferScriptBoundingBox,
       cdpActionsEnabled,
+      filterAdTrackingFrames,
     }).catch((err) => {
       lastError = err;
       return null;
     });
 
     if (!attemptResult) {
-      if (attempt < maxSteps - 1) {
+      if (attempt < attempts - 1) {
         continue;
       }
       // will fall through to fallback/final failure below
     } else if (!attemptResult.success) {
       lastError = new Error(attemptResult.message);
-      if (attempt < maxSteps - 1) {
+      if (attempt < attempts - 1) {
         continue;
       }
       // will fall through to fallback/final failure below
     } else {
-      await waitForSettledDOM(page);
+      await waitForSettledDOM(page, undefined, {
+        filterAdTrackingFrames,
+      });
       markDomSnapshotDirty(page);
       lastError = null;
       return {
@@ -158,7 +448,7 @@ export async function runCachedStep(
           usedCachedAction: true,
           fallbackUsed: false,
           retries: attemptIndex,
-          cachedXPath: cachedAction.xpath ?? null,
+          cachedXPath: normalizedXPath ?? null,
           fallbackXPath: null,
           fallbackElementId: null,
         },
@@ -168,42 +458,65 @@ export async function runCachedStep(
 
   // All cached attempts failed; optionally fall back to LLM perform
   if (params.performFallback) {
-    const fb = await params.performFallback(instruction);
-    const cachedXPath = cachedAction.xpath || "N/A";
-    const resolvedXPath = fb.replayStepMeta?.fallbackXPath || "N/A";
-    // eslint-disable-next-line no-console
-    console.log(
-      `
+    const fallbackResult = await params.performFallback(instruction).catch((error) => {
+      const message = formatCachedActionDiagnostic(error);
+      return {
+        taskId,
+        status: TaskStatus.FAILED,
+        steps: [],
+        output: `Fallback perform failed: ${message}`,
+        replayStepMeta: {
+          usedCachedAction: true,
+          fallbackUsed: true,
+          retries: attempts,
+          cachedXPath: normalizedXPath ?? null,
+          fallbackXPath: null,
+          fallbackElementId: null,
+        },
+      } satisfies TaskOutput;
+    });
+    const normalizedFallback = normalizeFallbackTaskOutput(
+      fallbackResult,
+      taskId,
+      attempts,
+      normalizedXPath ?? null
+    );
+    if (debug) {
+      const cachedXPath = normalizedXPath || "N/A";
+      const resolvedXPath =
+        formatCachedActionDebugLabel(
+          normalizedFallback.replayStepMeta?.fallbackXPath,
+          "N/A"
+        );
+      const safeInstruction = formatCachedActionDebugLabel(instruction, "N/A");
+      // eslint-disable-next-line no-console
+      console.log(
+        `
 ⚠️ [runCachedStep] Cached action failed. Falling back to LLM...
-   Instruction: "${instruction}"
-   ❌ Cached XPath Failed: "${cachedXPath}"
+   Instruction: "${safeInstruction}"
+   ❌ Cached XPath Failed: "${formatCachedActionDebugLabel(cachedXPath, "N/A")}"
    ✅ LLM Resolved New XPath: "${resolvedXPath}"
 `
-    );
-    return {
-      ...fb,
-      replayStepMeta: {
-        usedCachedAction: true,
-        fallbackUsed: true,
-        retries: maxSteps,
-        cachedXPath: cachedAction.xpath ?? null,
-        fallbackXPath: fb.replayStepMeta?.fallbackXPath ?? null,
-        fallbackElementId: fb.replayStepMeta?.fallbackElementId ?? null,
-      },
-    };
+      );
+    }
+    return normalizedFallback;
   }
 
   return {
     taskId,
     status: TaskStatus.FAILED,
     steps: [],
-    output:
-      (lastError as Error | null)?.message || "Failed to execute cached action",
+    output: normalizeCachedActionOutputText(
+      lastError !== null
+        ? formatCachedActionDiagnostic(lastError)
+        : "Failed to execute cached action",
+      "Failed to execute cached action"
+    ),
     replayStepMeta: {
       usedCachedAction: true,
       fallbackUsed: false,
-      retries: maxSteps,
-      cachedXPath: cachedAction.xpath ?? null,
+      retries: attempts,
+      cachedXPath: normalizedXPath ?? null,
       fallbackXPath: null,
       fallbackElementId: null,
     },
@@ -216,11 +529,12 @@ async function runCachedAttempt(args: {
   cachedAction: CachedActionInput;
   debug?: boolean;
   tokenLimit: number;
-  llm: any;
-  mcpClient: any;
+  llm: ActionContext["llm"];
+  mcpClient: ActionContext["mcpClient"];
   variables: Array<{ key: string; value: string; description: string }>;
   preferScriptBoundingBox?: boolean;
   cdpActionsEnabled?: boolean;
+  filterAdTrackingFrames?: boolean;
 }): Promise<{ success: boolean; message: string }> {
   const {
     page,
@@ -233,26 +547,43 @@ async function runCachedAttempt(args: {
     variables,
     preferScriptBoundingBox,
     cdpActionsEnabled,
+    filterAdTrackingFrames,
   } = args;
+  const useCdpActions = cdpActionsEnabled !== false;
+  let cdpClient: CDPClient | null = null;
+  let frameContextManager: FrameContextManager | null = null;
+  if (useCdpActions) {
+    const runtimeContext = await initializeRuntimeContext(
+      page,
+      debug,
+      {
+        filterAdTrackingFrames,
+      }
+    );
+    cdpClient = runtimeContext.cdpClient;
+    frameContextManager = runtimeContext.frameContextManager;
+  }
 
-  await waitForSettledDOM(page);
+  await waitForSettledDOM(page, undefined, {
+    filterAdTrackingFrames,
+  });
   const domState = await captureDOMState(page, {
     useCache: false,
     debug,
     enableVisualMode: false,
+    filterAdTrackingFrames,
   });
-
-  const { cdpClient, frameContextManager } = await initializeRuntimeContext(
-    page,
-    debug
-  );
-  const resolved = await resolveXPathWithCDP({
-    xpath: cachedAction.xpath!,
-    frameIndex: cachedAction.frameIndex ?? 0,
-    cdpClient,
-    frameContextManager,
-    debug,
-  });
+  let backendNodeId = 0;
+  if (useCdpActions && cdpClient && frameContextManager) {
+    const resolved = await resolveXPathWithCDP({
+      xpath: cachedAction.xpath!,
+      frameIndex: cachedAction.frameIndex ?? 0,
+      cdpClient,
+      frameContextManager,
+      debug,
+    });
+    backendNodeId = resolved.backendNodeId;
+  }
 
   const actionContext: ActionContext = {
     domState,
@@ -260,34 +591,36 @@ async function runCachedAttempt(args: {
     tokenLimit,
     llm,
     debug,
-    cdpActions: cdpActionsEnabled !== false,
-    cdp: {
-      client: cdpClient,
-      frameContextManager,
-      resolveElement,
-      dispatchCDPAction,
-      preferScriptBoundingBox: preferScriptBoundingBox ?? debug,
-      debug,
-    },
+    cdpActions: useCdpActions,
+    filterAdTrackingFrames,
+    cdp:
+      useCdpActions && cdpClient && frameContextManager
+        ? {
+            client: cdpClient,
+            frameContextManager,
+            resolveElement,
+            dispatchCDPAction,
+            preferScriptBoundingBox: preferScriptBoundingBox ?? debug,
+            debug,
+          }
+        : undefined,
     debugDir: undefined,
     mcpClient,
     variables,
     invalidateDomCache: () => markDomSnapshotDirty(page),
   };
 
-  const encodedId = `${cachedAction.frameIndex ?? 0}-${resolved.backendNodeId}`;
+  const encodedId = `${cachedAction.frameIndex ?? 0}-${backendNodeId}`;
   domState.backendNodeMap = {
     ...(domState.backendNodeMap || {}),
-    [encodedId]: resolved.backendNodeId,
+    [encodedId]: backendNodeId,
   };
   domState.xpathMap = {
     ...(domState.xpathMap || {}),
     [encodedId]: cachedAction.xpath!,
   };
 
-  const methodArgs = (cachedAction.arguments ?? []).map((v) =>
-    v == null ? "" : String(v)
-  );
+  const methodArgs = normalizeCachedActionArguments(cachedAction.arguments);
 
   const actionOutput = await performAction(actionContext, {
     elementId: encodedId,
@@ -300,12 +633,3 @@ async function runCachedAttempt(args: {
   return { success: actionOutput.success, message: actionOutput.message };
 }
 
-export async function performGoTo(
-  page: import("playwright-core").Page,
-  url: string,
-  waitUntil: "domcontentloaded" | "load" | "networkidle" = "domcontentloaded"
-): Promise<void> {
-  await page.goto(url, { waitUntil });
-  await waitForSettledDOM(page);
-  markDomSnapshotDirty(page);
-}
diff --git a/src/agent/shared/runtime-context.test.ts b/src/agent/shared/runtime-context.test.ts
new file mode 100644
index 00000000..2e276cac
--- /dev/null
+++ b/src/agent/shared/runtime-context.test.ts
@@ -0,0 +1,215 @@
+import type { Page } from "playwright-core";
+import { initializeRuntimeContext } from "@/agent/shared/runtime-context";
+
+const getCDPClientMock = jest.fn();
+const getOrCreateFrameContextManagerMock = jest.fn();
+
+jest.mock("@/cdp", () => ({
+  getCDPClient: (...args: unknown[]) => getCDPClientMock(...args),
+  getOrCreateFrameContextManager: (...args: unknown[]) =>
+    getOrCreateFrameContextManagerMock(...args),
+}));
+
+describe("initializeRuntimeContext", () => {
+  beforeEach(() => {
+    jest.clearAllMocks();
+  });
+
+  it("acquires CDP client and initializes frame manager", async () => {
+    const page = {} as unknown as Page;
+    const cdpClient = { id: "client-1" };
+    const frameContextManager = {
+      setDebug: jest.fn(),
+      ensureInitialized: jest.fn().mockResolvedValue(undefined),
+    };
+    getCDPClientMock.mockResolvedValue(cdpClient);
+    getOrCreateFrameContextManagerMock.mockReturnValue(frameContextManager);
+
+    const result = await initializeRuntimeContext(page, true);
+
+    expect(result).toEqual({
+      cdpClient,
+      frameContextManager,
+    });
+    expect(frameContextManager.setDebug).toHaveBeenCalledWith(true);
+    expect(frameContextManager.ensureInitialized).toHaveBeenCalledTimes(1);
+  });
+
+  it("applies frame filtering option when provided", async () => {
+    const page = {} as unknown as Page;
+    const cdpClient = { id: "client-filter" };
+    const frameContextManager = {
+      setDebug: jest.fn(),
+      setFrameFilteringEnabled: jest.fn(),
+      ensureInitialized: jest.fn().mockResolvedValue(undefined),
+    };
+    getCDPClientMock.mockResolvedValue(cdpClient);
+    getOrCreateFrameContextManagerMock.mockReturnValue(frameContextManager);
+
+    await initializeRuntimeContext(page, false, {
+      filterAdTrackingFrames: false,
+    });
+
+    expect(frameContextManager.setFrameFilteringEnabled).toHaveBeenCalledWith(
+      false
+    );
+    expect(frameContextManager.ensureInitialized).toHaveBeenCalledTimes(1);
+  });
+
+  it("continues when frame manager debug setter throws", async () => {
+    const warnSpy = jest.spyOn(console, "warn").mockImplementation(() => {});
+    const page = {} as unknown as Page;
+    const cdpClient = { id: "client-debug-trap" };
+    const frameContextManager = {
+      setDebug: jest.fn(() => {
+        throw new Error(`debug\u0000\n${"x".repeat(2_000)}`);
+      }),
+      ensureInitialized: jest.fn().mockResolvedValue(undefined),
+    };
+    getCDPClientMock.mockResolvedValue(cdpClient);
+    getOrCreateFrameContextManagerMock.mockReturnValue(frameContextManager);
+
+    try {
+      const result = await initializeRuntimeContext(page, true);
+      expect(result.frameContextManager).toBe(frameContextManager);
+      const warning = String(
+        warnSpy.mock.calls.find((call) =>
+          String(call[0] ?? "").includes("configure frame manager debug")
+        )?.[0] ?? ""
+      );
+      expect(warning).toContain("[truncated");
+      expect(warning).not.toContain("\u0000");
+      expect(warning).not.toContain("\n");
+      expect(frameContextManager.ensureInitialized).toHaveBeenCalledTimes(1);
+    } finally {
+      warnSpy.mockRestore();
+    }
+  });
+
+  it("continues when frame manager filtering setter throws", async () => {
+    const warnSpy = jest.spyOn(console, "warn").mockImplementation(() => {});
+    const page = {} as unknown as Page;
+    const cdpClient = { id: "client-filter-trap" };
+    const frameContextManager = {
+      setDebug: jest.fn(),
+      setFrameFilteringEnabled: jest.fn(() => {
+        throw new Error(`filter\u0000\n${"y".repeat(2_000)}`);
+      }),
+      ensureInitialized: jest.fn().mockResolvedValue(undefined),
+    };
+    getCDPClientMock.mockResolvedValue(cdpClient);
+    getOrCreateFrameContextManagerMock.mockReturnValue(frameContextManager);
+
+    try {
+      const result = await initializeRuntimeContext(page, true, {
+        filterAdTrackingFrames: false,
+      });
+      expect(result.frameContextManager).toBe(frameContextManager);
+      const warning = String(
+        warnSpy.mock.calls.find((call) =>
+          String(call[0] ?? "").includes("configure frame filtering")
+        )?.[0] ?? ""
+      );
+      expect(warning).toContain("[truncated");
+      expect(warning).not.toContain("\u0000");
+      expect(warning).not.toContain("\n");
+      expect(frameContextManager.ensureInitialized).toHaveBeenCalledTimes(1);
+    } finally {
+      warnSpy.mockRestore();
+    }
+  });
+
+  it("initializes even when setDebug is unavailable", async () => {
+    const page = {} as unknown as Page;
+    const cdpClient = { id: "client-2" };
+    const frameContextManager = {
+      ensureInitialized: jest.fn().mockResolvedValue(undefined),
+    };
+    getCDPClientMock.mockResolvedValue(cdpClient);
+    getOrCreateFrameContextManagerMock.mockReturnValue(frameContextManager);
+
+    const result = await initializeRuntimeContext(page, true);
+
+    expect(result.frameContextManager).toBe(frameContextManager);
+    expect(frameContextManager.ensureInitialized).toHaveBeenCalledTimes(1);
+  });
+
+  it("rejects invalid page instances", async () => {
+    await expect(
+      initializeRuntimeContext(undefined as unknown as Page)
+    ).rejects.toThrow(
+      "[FrameContext] Invalid page instance for runtime initialization"
+    );
+  });
+
+  it("throws readable errors when CDP client acquisition fails", async () => {
+    const page = {} as unknown as Page;
+    getCDPClientMock.mockRejectedValue({ reason: "cdp unavailable" });
+
+    await expect(initializeRuntimeContext(page)).rejects.toThrow(
+      '[FrameContext] Failed to acquire CDP client: {"reason":"cdp unavailable"}'
+    );
+  });
+
+  it("truncates oversized CDP acquisition diagnostics", async () => {
+    const page = {} as unknown as Page;
+    getCDPClientMock.mockRejectedValue(new Error(`x${"y".repeat(2_000)}\ncdp trap`));
+
+    await expect(initializeRuntimeContext(page)).rejects.toThrow(/\[truncated/);
+  });
+
+  it("throws when frame context manager is invalid", async () => {
+    const page = {} as unknown as Page;
+    getCDPClientMock.mockResolvedValue({ id: "client-3" });
+    getOrCreateFrameContextManagerMock.mockReturnValue({});
+
+    await expect(initializeRuntimeContext(page)).rejects.toThrow(
+      "[FrameContext] Invalid frame context manager: ensureInitialized() is unavailable"
+    );
+  });
+
+  it("logs and throws readable errors when initialization fails", async () => {
+    const warnSpy = jest.spyOn(console, "warn").mockImplementation(() => {});
+    const page = {} as unknown as Page;
+    getCDPClientMock.mockResolvedValue({ id: "client-4" });
+    getOrCreateFrameContextManagerMock.mockReturnValue({
+      setDebug: jest.fn(),
+      ensureInitialized: jest.fn().mockRejectedValue(new Error("init failed")),
+    });
+
+    try {
+      await expect(initializeRuntimeContext(page, true)).rejects.toThrow(
+        "[FrameContext] Failed to initialize frame context manager: init failed"
+      );
+      expect(warnSpy).toHaveBeenCalledWith(
+        "[FrameContext] Failed to initialize frame context manager:",
+        "init failed"
+      );
+    } finally {
+      warnSpy.mockRestore();
+    }
+  });
+
+  it("truncates oversized initialization diagnostics in logs and errors", async () => {
+    const warnSpy = jest.spyOn(console, "warn").mockImplementation(() => {});
+    const page = {} as unknown as Page;
+    getCDPClientMock.mockResolvedValue({ id: "client-5" });
+    getOrCreateFrameContextManagerMock.mockReturnValue({
+      setDebug: jest.fn(),
+      ensureInitialized: jest
+        .fn()
+        .mockRejectedValue(new Error(`x${"y".repeat(2_000)}\ninit failed`)),
+    });
+
+    try {
+      await expect(initializeRuntimeContext(page, true)).rejects.toThrow(
+        /\[truncated/
+      );
+      const warnMessage = String(warnSpy.mock.calls[0]?.[1] ?? "");
+      expect(warnMessage).toContain("[truncated");
+      expect(warnMessage).not.toContain("\n");
+    } finally {
+      warnSpy.mockRestore();
+    }
+  });
+});
diff --git a/src/agent/shared/runtime-context.ts b/src/agent/shared/runtime-context.ts
index 44a000f3..792ab936 100644
--- a/src/agent/shared/runtime-context.ts
+++ b/src/agent/shared/runtime-context.ts
@@ -5,41 +5,131 @@ import {
 } from "@/cdp";
 import type { CDPClient } from "@/cdp/types";
 import type { FrameContextManager } from "@/cdp/frame-context-manager";
+import { formatUnknownError } from "@/utils";
 
 export interface RuntimeContext {
   cdpClient: CDPClient;
   frameContextManager: FrameContextManager;
 }
 
+export interface RuntimeContextOptions {
+  filterAdTrackingFrames?: boolean;
+}
+
+const MAX_RUNTIME_CONTEXT_DIAGNOSTIC_CHARS = 400;
+
+function formatRuntimeContextDiagnostic(value: unknown): string {
+  const normalized = Array.from(formatUnknownError(value), (char) => {
+    const code = char.charCodeAt(0);
+    return (code >= 0 && code < 32) || code === 127 ? " " : char;
+  })
+    .join("")
+    .replace(/\s+/g, " ")
+    .trim();
+  const fallback = normalized.length > 0 ? normalized : "unknown error";
+  if (fallback.length <= MAX_RUNTIME_CONTEXT_DIAGNOSTIC_CHARS) {
+    return fallback;
+  }
+  const omitted = fallback.length - MAX_RUNTIME_CONTEXT_DIAGNOSTIC_CHARS;
+  return `${fallback.slice(
+    0,
+    MAX_RUNTIME_CONTEXT_DIAGNOSTIC_CHARS
+  )}... [truncated ${omitted} chars]`;
+}
+
 /**
  * Initialize shared runtime context for agent operations
  * Handles CDP client acquisition and frame manager initialization
  */
 export async function initializeRuntimeContext(
   page: Page,
-  debug: boolean = false
+  debug: boolean = false,
+  options: RuntimeContextOptions = {}
 ): Promise<RuntimeContext> {
+  if (!page || typeof page !== "object") {
+    throw new Error("[FrameContext] Invalid page instance for runtime initialization");
+  }
+
+  let cdpClient: CDPClient;
+  try {
+    cdpClient = await getCDPClient(page);
+  } catch (error) {
+    throw new Error(
+      `[FrameContext] Failed to acquire CDP client: ${formatRuntimeContextDiagnostic(
+        error
+      )}`
+    );
+  }
+
+  let frameContextManager: FrameContextManager;
+  try {
+    frameContextManager = getOrCreateFrameContextManager(cdpClient);
+  } catch (error) {
+    throw new Error(
+      `[FrameContext] Failed to create frame context manager: ${formatRuntimeContextDiagnostic(
+        error
+      )}`
+    );
+  }
+
+  if (
+    !frameContextManager ||
+    typeof frameContextManager.ensureInitialized !== "function"
+  ) {
+    throw new Error(
+      "[FrameContext] Invalid frame context manager: ensureInitialized() is unavailable"
+    );
+  }
+
   try {
-    const cdpClient = await getCDPClient(page);
-    const frameContextManager = getOrCreateFrameContextManager(cdpClient);
-    
-    frameContextManager.setDebug(debug);
+    if (typeof frameContextManager.setDebug === "function") {
+      try {
+        frameContextManager.setDebug(debug);
+      } catch (error) {
+        if (debug) {
+          console.warn(
+            `[FrameContext] Failed to configure frame manager debug: ${formatRuntimeContextDiagnostic(
+              error
+            )}`
+          );
+        }
+      }
+    }
+    if (
+      typeof frameContextManager.setFrameFilteringEnabled === "function" &&
+      typeof options.filterAdTrackingFrames === "boolean"
+    ) {
+      try {
+        frameContextManager.setFrameFilteringEnabled(
+          options.filterAdTrackingFrames
+        );
+      } catch (error) {
+        if (debug) {
+          console.warn(
+            `[FrameContext] Failed to configure frame filtering: ${formatRuntimeContextDiagnostic(
+              error
+            )}`
+          );
+        }
+      }
+    }
     await frameContextManager.ensureInitialized();
-    
-    return {
-      cdpClient,
-      frameContextManager
-    };
   } catch (error) {
+    const diagnostic = formatRuntimeContextDiagnostic(error);
     if (debug) {
       console.warn(
         "[FrameContext] Failed to initialize frame context manager:",
-        error
+        diagnostic
       );
     }
-    // Re-throw or handle as needed - consistent with previous ensureFrameContextsReady behavior
-    // but now we probably want the caller to know initialization failed if it's critical
-    throw error;
+    throw new Error(
+      `[FrameContext] Failed to initialize frame context manager: ${diagnostic}`
+    );
   }
+
+  return {
+    cdpClient,
+    frameContextManager,
+  };
 }
 
diff --git a/src/agent/shared/xpath-cdp-resolver.test.ts b/src/agent/shared/xpath-cdp-resolver.test.ts
new file mode 100644
index 00000000..69db3bcc
--- /dev/null
+++ b/src/agent/shared/xpath-cdp-resolver.test.ts
@@ -0,0 +1,270 @@
+import type { CDPClient, CDPSession } from "@/cdp/types";
+import type { FrameContextManager } from "@/cdp/frame-context-manager";
+import { resolveXPathWithCDP } from "@/agent/shared/xpath-cdp-resolver";
+
+function createSession(
+  backendNodeId = 101,
+  objectId = "obj-1"
+): CDPSession {
+  const sendImpl: CDPSession["send"] = async <T = unknown>(method: string) => {
+    if (method === "Runtime.evaluate") {
+      return {
+        result: { objectId },
+      } as T;
+    }
+    if (method === "DOM.describeNode") {
+      return {
+        node: { backendNodeId },
+      } as T;
+    }
+    return {} as T;
+  };
+
+  return {
+    id: "session-1",
+    send: jest.fn(sendImpl) as CDPSession["send"],
+    on: jest.fn(),
+    off: jest.fn(),
+    detach: jest.fn(async () => undefined),
+  };
+}
+
+function createClient(session: CDPSession): CDPClient {
+  return {
+    rootSession: session,
+    createSession: jest.fn(async () => session),
+    acquireSession: jest.fn(async () => session),
+    dispose: jest.fn(async () => undefined),
+  };
+}
+
+describe("resolveXPathWithCDP", () => {
+  it("resolves on main frame without frame manager using root fallback", async () => {
+    const session = createSession(321, "obj-main");
+    const client = createClient(session);
+
+    const resolved = await resolveXPathWithCDP({
+      xpath: "//button[1]",
+      frameIndex: 0,
+      cdpClient: client,
+    });
+
+    expect(resolved).toEqual({
+      backendNodeId: 321,
+      frameId: "root",
+      objectId: "obj-main",
+    });
+  });
+
+  it("throws clear diagnostics when iframe index is requested without manager", async () => {
+    const session = createSession();
+    const client = createClient(session);
+
+    await expect(
+      resolveXPathWithCDP({
+        xpath: "//button[1]",
+        frameIndex: 2,
+        cdpClient: client,
+      })
+    ).rejects.toThrow("FrameContextManager unavailable");
+  });
+
+  it("normalizes invalid frame indexes to root frame fallback", async () => {
+    const session = createSession(222, "obj-root");
+    const client = createClient(session);
+
+    const resolved = await resolveXPathWithCDP({
+      xpath: "//button[1]",
+      frameIndex: Number.NaN,
+      cdpClient: client,
+    });
+
+    expect(resolved).toEqual({
+      backendNodeId: 222,
+      frameId: "root",
+      objectId: "obj-root",
+    });
+  });
+
+  it("rejects empty xpath input", async () => {
+    const session = createSession();
+    const client = createClient(session);
+
+    await expect(
+      resolveXPathWithCDP({
+        xpath: "   ",
+        frameIndex: 0,
+        cdpClient: client,
+      })
+    ).rejects.toThrow("XPath must be a non-empty string");
+  });
+
+  it("throws readable error when acquiring a CDP session fails", async () => {
+    const session = createSession();
+    const client = {
+      ...createClient(session),
+      acquireSession: jest.fn(async () => {
+        throw new Error("session failure");
+      }),
+    } as CDPClient;
+
+    await expect(
+      resolveXPathWithCDP({
+        xpath: "//button[1]",
+        frameIndex: 0,
+        cdpClient: client,
+      })
+    ).rejects.toThrow(
+      "Failed to acquire CDP session for XPath resolution: session failure"
+    );
+  });
+
+  it("truncates oversized CDP session acquisition diagnostics", async () => {
+    const session = createSession();
+    const client = {
+      ...createClient(session),
+      acquireSession: jest.fn(async () => {
+        throw new Error(`x${"y".repeat(2_000)}\nsession failure`);
+      }),
+    } as CDPClient;
+
+    await expect(
+      resolveXPathWithCDP({
+        xpath: "//button[1]",
+        frameIndex: 0,
+        cdpClient: client,
+      })
+    ).rejects.toThrow(/\[truncated/);
+  });
+
+  it("throws when iframe execution context is missing", async () => {
+    const session = createSession();
+    const client = createClient(session);
+    const manager = {
+      getFrameByIndex: jest.fn((frameIndex: number) =>
+        frameIndex === 1
+          ? { frameId: "frame-1" }
+          : frameIndex === 0
+            ? { frameId: "root-frame" }
+            : undefined
+      ),
+      waitForExecutionContext: jest.fn(async () => undefined),
+      getFrameIndex: jest.fn((frameId: string) =>
+        frameId === "root-frame" ? 0 : frameId === "frame-1" ? 1 : undefined
+      ),
+      frameGraph: {
+        getAllFrames: jest.fn(() => [
+          {
+            frameId: "root-frame",
+            parentFrameId: null,
+            lastUpdated: Date.now(),
+          },
+          {
+            frameId: "frame-1",
+            parentFrameId: "root-frame",
+            lastUpdated: Date.now(),
+          },
+        ]),
+      },
+    } as unknown as FrameContextManager;
+
+    await expect(
+      resolveXPathWithCDP({
+        xpath: "//button[1]",
+        frameIndex: 1,
+        cdpClient: client,
+        frameContextManager: manager,
+      })
+    ).rejects.toThrow("Execution context missing for frameIndex 1");
+  });
+
+  it("throws readable error when execution-context wait throws", async () => {
+    const session = createSession();
+    const client = createClient(session);
+    const manager = {
+      getFrameByIndex: jest.fn(() => ({ frameId: "frame-1" })),
+      waitForExecutionContext: jest.fn(async () => {
+        throw new Error("wait failed");
+      }),
+      getFrameIndex: jest.fn(() => 1),
+      frameGraph: {
+        getAllFrames: jest.fn(() => [
+          {
+            frameId: "frame-1",
+            parentFrameId: null,
+            lastUpdated: Date.now(),
+          },
+        ]),
+      },
+    } as unknown as FrameContextManager;
+
+    await expect(
+      resolveXPathWithCDP({
+        xpath: "//button[1]",
+        frameIndex: 1,
+        cdpClient: client,
+        frameContextManager: manager,
+      })
+    ).rejects.toThrow(
+      "Failed while waiting for execution context (frame-1): wait failed"
+    );
+  });
+
+  it("truncates oversized execution-context wait diagnostics", async () => {
+    const session = createSession();
+    const client = createClient(session);
+    const manager = {
+      getFrameByIndex: jest.fn(() => ({ frameId: "frame-1" })),
+      waitForExecutionContext: jest.fn(async () => {
+        throw new Error(`x${"y".repeat(2_000)}\nwait failed`);
+      }),
+      getFrameIndex: jest.fn(() => 1),
+      frameGraph: {
+        getAllFrames: jest.fn(() => [
+          {
+            frameId: "frame-1",
+            parentFrameId: null,
+            lastUpdated: Date.now(),
+          },
+        ]),
+      },
+    } as unknown as FrameContextManager;
+
+    await expect(
+      resolveXPathWithCDP({
+        xpath: "//button[1]",
+        frameIndex: 1,
+        cdpClient: client,
+        frameContextManager: manager,
+      })
+    ).rejects.toThrow(/\[truncated/);
+  });
+
+  it("falls back to empty frame diagnostics when frame graph access traps throw", async () => {
+    const session = createSession();
+    const client = createClient(session);
+    const manager = {
+      getFrameByIndex: jest.fn(() => {
+        throw new Error("index trap");
+      }),
+      waitForExecutionContext: jest.fn(async () => undefined),
+      getFrameIndex: jest.fn(() => {
+        throw new Error("frame index trap");
+      }),
+      frameGraph: {
+        getAllFrames: jest.fn(() => {
+          throw new Error("frame graph trap");
+        }),
+      },
+    } as unknown as FrameContextManager;
+
+    await expect(
+      resolveXPathWithCDP({
+        xpath: "//button[1]",
+        frameIndex: 1,
+        cdpClient: client,
+        frameContextManager: manager,
+      })
+    ).rejects.toThrow("No frame indices currently tracked.");
+  });
+});
diff --git a/src/agent/shared/xpath-cdp-resolver.ts b/src/agent/shared/xpath-cdp-resolver.ts
index 462e164e..cd09b1cb 100644
--- a/src/agent/shared/xpath-cdp-resolver.ts
+++ b/src/agent/shared/xpath-cdp-resolver.ts
@@ -1,6 +1,9 @@
 import { CDPClient } from "@/cdp/types";
 import { FrameContextManager } from "@/cdp/frame-context-manager";
 import { HyperagentError } from "../error";
+import { formatUnknownError } from "@/utils";
+
+const MAX_XPATH_CDP_DIAGNOSTIC_CHARS = 400;
 
 export interface ResolvedCDPFromXPath {
   backendNodeId: number;
@@ -16,67 +19,129 @@ export interface ResolveXPathWithCDPParams {
   debug?: boolean;
 }
 
+function formatXPathCDPDiagnostic(value: unknown): string {
+  const normalized = Array.from(formatUnknownError(value), (char) => {
+    const code = char.charCodeAt(0);
+    return (code >= 0 && code < 32) || code === 127 ? " " : char;
+  })
+    .join("")
+    .replace(/\s+/g, " ")
+    .trim();
+  const fallback = normalized.length > 0 ? normalized : "unknown error";
+  if (fallback.length <= MAX_XPATH_CDP_DIAGNOSTIC_CHARS) {
+    return fallback;
+  }
+  const omitted = fallback.length - MAX_XPATH_CDP_DIAGNOSTIC_CHARS;
+  return `${fallback.slice(
+    0,
+    MAX_XPATH_CDP_DIAGNOSTIC_CHARS
+  )}... [truncated ${omitted} chars]`;
+}
+
 export async function resolveXPathWithCDP(
   params: ResolveXPathWithCDPParams
 ): Promise<ResolvedCDPFromXPath> {
-  const { xpath, frameIndex = 0, cdpClient, frameContextManager, debug } =
-    params;
+  const { cdpClient, frameContextManager, debug } = params;
+  const xpath = normalizeXPathInput(params.xpath);
+  const normalizedFrameIndex = normalizeFrameIndex(params.frameIndex);
 
   // Use a DOM session without detaching the shared session; this keeps root session intact.
-  const session = await cdpClient.acquireSession("dom");
-  let targetFrameId: string | undefined;
-
-  if (frameContextManager) {
-    const frameInfo = frameContextManager.getFrameByIndex(frameIndex ?? 0);
-    targetFrameId = frameInfo?.frameId;
+  let session: Awaited<ReturnType<CDPClient["acquireSession"]>>;
+  try {
+    session = await cdpClient.acquireSession("dom");
+  } catch (error) {
+    throw new HyperagentError(
+      `Failed to acquire CDP session for XPath resolution: ${formatXPathCDPDiagnostic(
+        error
+      )}`,
+      500
+    );
   }
+  const targetFrameId = resolveTargetFrameId(
+    normalizedFrameIndex,
+    frameContextManager
+  );
 
   if (!targetFrameId) {
     throw new HyperagentError(
-      `Unable to resolve frameId for frameIndex ${frameIndex}`,
+      `Unable to resolve frameId for frameIndex ${normalizedFrameIndex}. ${buildFrameDiagnostics(
+        frameContextManager
+      )}`,
       404
     );
   }
 
   const executionContextId = frameContextManager
-    ? await frameContextManager.waitForExecutionContext(targetFrameId)
+    ? await safeWaitForExecutionContext(frameContextManager, targetFrameId)
     : undefined;
 
+  if (frameContextManager && normalizedFrameIndex !== 0 && !executionContextId) {
+    throw new HyperagentError(
+      `Execution context missing for frameIndex ${normalizedFrameIndex} (${targetFrameId}). ${buildFrameDiagnostics(
+        frameContextManager
+      )}`,
+      404
+    );
+  }
+
   if (!executionContextId && debug) {
     console.warn(
-      `[resolveXPathWithCDP] Missing executionContextId for frame ${frameIndex} (${targetFrameId}), continuing`
+      `[resolveXPathWithCDP] Missing executionContextId for frame ${normalizedFrameIndex} (${targetFrameId}), continuing`
     );
   }
 
   await session.send("DOM.enable").catch(() => {});
   await session.send("Runtime.enable").catch(() => {});
 
-  const evalResponse = await session.send<{
+  let evalResponse: {
     result: { objectId?: string | null };
     exceptionDetails?: unknown;
-  }>("Runtime.evaluate", {
-    expression: buildXPathEvaluationExpression(xpath),
-    contextId: executionContextId,
-    includeCommandLineAPI: false,
-    returnByValue: false,
-    awaitPromise: false,
-  });
+  };
+  try {
+    evalResponse = await session.send<{
+      result: { objectId?: string | null };
+      exceptionDetails?: unknown;
+    }>("Runtime.evaluate", {
+      expression: buildXPathEvaluationExpression(xpath),
+      contextId: executionContextId,
+      includeCommandLineAPI: false,
+      returnByValue: false,
+      awaitPromise: false,
+    });
+  } catch (error) {
+    throw new HyperagentError(
+      `Failed to evaluate XPath in frame ${normalizedFrameIndex}: ${formatXPathCDPDiagnostic(
+        error
+      )}`,
+      500
+    );
+  }
 
   const objectId = evalResponse.result.objectId || undefined;
   if (!objectId) {
     throw new HyperagentError(
-      `Failed to resolve XPath to objectId in frame ${frameIndex}`,
+      `Failed to resolve XPath to objectId in frame ${normalizedFrameIndex}`,
       404
     );
   }
 
-  const describeNode = await session.send<{
-    node?: { backendNodeId?: number };
-  }>("DOM.describeNode", { objectId });
+  let describeNode: { node?: { backendNodeId?: number } };
+  try {
+    describeNode = await session.send<{
+      node?: { backendNodeId?: number };
+    }>("DOM.describeNode", { objectId });
+  } catch (error) {
+    throw new HyperagentError(
+      `Failed to describe resolved XPath node in frame ${normalizedFrameIndex}: ${formatXPathCDPDiagnostic(
+        error
+      )}`,
+      500
+    );
+  }
   const backendNodeId = describeNode.node?.backendNodeId;
   if (typeof backendNodeId !== "number") {
     throw new HyperagentError(
-      `DOM.describeNode did not return backendNodeId for frame ${frameIndex}`,
+      `DOM.describeNode did not return backendNodeId for frame ${normalizedFrameIndex}`,
       404
     );
   }
@@ -88,6 +153,118 @@ export async function resolveXPathWithCDP(
   };
 }
 
+function normalizeXPathInput(xpath: unknown): string {
+  if (typeof xpath !== "string") {
+    throw new HyperagentError("XPath must be a non-empty string", 400);
+  }
+  const normalized = xpath.trim();
+  if (normalized.length === 0) {
+    throw new HyperagentError("XPath must be a non-empty string", 400);
+  }
+  return normalized;
+}
+
+function normalizeFrameIndex(value: unknown): number {
+  if (typeof value !== "number" || !Number.isFinite(value)) {
+    return 0;
+  }
+  if (value < 0) {
+    return 0;
+  }
+  return Math.floor(value);
+}
+
+async function safeWaitForExecutionContext(
+  frameContextManager: FrameContextManager,
+  targetFrameId: string
+): Promise<number | undefined> {
+  try {
+    return await frameContextManager.waitForExecutionContext(targetFrameId);
+  } catch (error) {
+    throw new HyperagentError(
+      `Failed while waiting for execution context (${targetFrameId}): ${formatXPathCDPDiagnostic(
+        error
+      )}`,
+      500
+    );
+  }
+}
+
+function resolveTargetFrameId(
+  frameIndex: number,
+  frameContextManager?: FrameContextManager
+): string | undefined {
+  if (!frameContextManager) {
+    return frameIndex === 0 ? "root" : undefined;
+  }
+
+  const directMatch = safeGetFrameByIndex(frameContextManager, frameIndex)?.frameId;
+  if (directMatch) {
+    return directMatch;
+  }
+
+  if (frameIndex === 0) {
+    const rootFrame = safeGetAllFrames(frameContextManager)
+      .find((frame) => frame.parentFrameId === null);
+    return rootFrame?.frameId ?? "root";
+  }
+
+  return undefined;
+}
+
+function buildFrameDiagnostics(frameContextManager?: FrameContextManager): string {
+  if (!frameContextManager) {
+    return "FrameContextManager unavailable.";
+  }
+  const mappedIndices = safeGetAllFrames(frameContextManager)
+    .map((frame) => ({
+      frameId: frame.frameId,
+      frameIndex: safeGetFrameIndex(frameContextManager, frame.frameId),
+    }))
+    .filter(
+      (entry): entry is { frameId: string; frameIndex: number } =>
+        typeof entry.frameIndex === "number"
+    )
+    .sort((a, b) => a.frameIndex - b.frameIndex)
+    .map((entry) => `${entry.frameIndex}:${entry.frameId}`);
+
+  return mappedIndices.length > 0
+    ? `Available frames => ${mappedIndices.join(", ")}`
+    : "No frame indices currently tracked.";
+}
+
+function safeGetAllFrames(
+  frameContextManager: FrameContextManager
+): Array<{ frameId: string; parentFrameId: string | null }> {
+  try {
+    return frameContextManager.frameGraph.getAllFrames();
+  } catch {
+    return [];
+  }
+}
+
+function safeGetFrameByIndex(
+  frameContextManager: FrameContextManager,
+  frameIndex: number
+): { frameId: string } | undefined {
+  try {
+    return frameContextManager.getFrameByIndex(frameIndex) ?? undefined;
+  } catch {
+    return undefined;
+  }
+}
+
+function safeGetFrameIndex(
+  frameContextManager: FrameContextManager,
+  frameId: string
+): number | undefined {
+  try {
+    return frameContextManager.getFrameIndex(frameId);
+  } catch {
+    return undefined;
+  }
+}
+
 function buildXPathEvaluationExpression(xpath: string): string {
   const escaped = JSON.stringify(xpath);
   return `(function() {
diff --git a/src/agent/tools/agent.test.ts b/src/agent/tools/agent.test.ts
new file mode 100644
index 00000000..540d91f6
--- /dev/null
+++ b/src/agent/tools/agent.test.ts
@@ -0,0 +1,1492 @@
+import { z } from "zod";
+import type { Page } from "playwright-core";
+import fs from "fs";
+import * as cdp from "@/cdp";
+import type { AgentActionDefinition } from "@/types";
+import type { AgentCtx } from "@/agent/tools/types";
+import { TaskStatus, type TaskState } from "@/types/agent/types";
+import { runAgentTask } from "@/agent/tools/agent";
+
+jest.mock("@/agent/shared/dom-capture", () => ({
+  captureDOMState: jest.fn(),
+}));
+
+jest.mock("@/utils/waitForSettledDOM", () => ({
+  waitForSettledDOM: jest.fn(),
+}));
+
+jest.mock("@/agent/shared/runtime-context", () => ({
+  initializeRuntimeContext: jest.fn(),
+}));
+
+jest.mock("@/agent/messages/builder", () => ({
+  buildAgentStepMessages: jest.fn(),
+}));
+
+const { captureDOMState } = jest.requireMock("@/agent/shared/dom-capture") as {
+  captureDOMState: jest.Mock;
+};
+const { waitForSettledDOM } = jest.requireMock("@/utils/waitForSettledDOM") as {
+  waitForSettledDOM: jest.Mock;
+};
+const { initializeRuntimeContext } = jest.requireMock(
+  "@/agent/shared/runtime-context"
+) as {
+  initializeRuntimeContext: jest.Mock;
+};
+const { buildAgentStepMessages } = jest.requireMock("@/agent/messages/builder") as {
+  buildAgentStepMessages: jest.Mock;
+};
+
+function createMockPage(): Page {
+  return {
+    on: jest.fn(),
+    off: jest.fn(),
+    url: () => "https://example.com",
+  } as unknown as Page;
+}
+
+function createCompleteActionDefinition(): AgentActionDefinition<
+  z.ZodObject<{
+    success: z.ZodBoolean;
+    text: z.ZodOptional<z.ZodString>;
+  }>
+> {
+  return {
+    type: "complete",
+    actionParams: z.object({
+      success: z.boolean(),
+      text: z.string().optional(),
+    }),
+    run: async (_ctx, params) => {
+      if (params.success) {
+        return { success: true, message: "task complete" };
+      }
+      return { success: false, message: "task failed by model decision" };
+    },
+    completeAction: async (params) => params.text ?? "task complete",
+  };
+}
+
+function createAgentCtx(
+  actionOutput: { success: boolean; text?: string }
+): AgentCtx {
+  const parsedAction = {
+    thoughts: "done",
+    memory: "done",
+    action: {
+      type: "complete",
+      params: {
+        success: actionOutput.success,
+        text: actionOutput.text,
+      },
+    },
+  };
+
+  const llm = {
+    invoke: async () => ({
+      role: "assistant" as const,
+      content: "ok",
+    }),
+    invokeStructured: async () => ({
+      rawText: JSON.stringify(actionOutput),
+      parsed: parsedAction,
+    }),
+    getProviderId: () => "mock",
+    getModelId: () => "mock-model",
+    getCapabilities: () => ({
+      multimodal: false,
+      toolCalling: true,
+      jsonMode: true,
+    }),
+  } as unknown as AgentCtx["llm"];
+
+  return {
+    llm,
+    actions: [createCompleteActionDefinition()],
+    tokenLimit: 10000,
+    debug: false,
+    variables: {},
+    cdpActions: false,
+  };
+}
+
+function createThrowingCompleteCtx(errorMessage: string): AgentCtx {
+  const parsedAction = {
+    thoughts: "done",
+    memory: "done",
+    action: {
+      type: "complete",
+      params: {
+        success: true,
+        text: "unused",
+      },
+    },
+  };
+
+  const llm = {
+    invoke: async () => ({
+      role: "assistant" as const,
+      content: "ok",
+    }),
+    invokeStructured: async () => ({
+      rawText: "{}",
+      parsed: parsedAction,
+    }),
+    getProviderId: () => "mock",
+    getModelId: () => "mock-model",
+    getCapabilities: () => ({
+      multimodal: false,
+      toolCalling: true,
+      jsonMode: true,
+    }),
+  } as unknown as AgentCtx["llm"];
+
+  return {
+    llm,
+    actions: [
+      {
+        type: "complete",
+        actionParams: z.object({
+          success: z.boolean(),
+          text: z.string().optional(),
+        }),
+        run: async () => {
+          throw new Error(errorMessage);
+        },
+      },
+    ],
+    tokenLimit: 10000,
+    debug: false,
+    variables: {},
+    cdpActions: false,
+  };
+}
+
+function createThrowingObjectCtx(): AgentCtx {
+  const parsedAction = {
+    thoughts: "done",
+    memory: "done",
+    action: {
+      type: "complete",
+      params: {
+        success: true,
+        text: "unused",
+      },
+    },
+  };
+
+  const llm = {
+    invoke: async () => ({
+      role: "assistant" as const,
+      content: "ok",
+    }),
+    invokeStructured: async () => ({
+      rawText: "{}",
+      parsed: parsedAction,
+    }),
+    getProviderId: () => "mock",
+    getModelId: () => "mock-model",
+    getCapabilities: () => ({
+      multimodal: false,
+      toolCalling: true,
+      jsonMode: true,
+    }),
+  } as unknown as AgentCtx["llm"];
+
+  return {
+    llm,
+    actions: [
+      {
+        type: "complete",
+        actionParams: z.object({
+          success: z.boolean(),
+          text: z.string().optional(),
+        }),
+        run: async () => {
+          throw { reason: "object failure" };
+        },
+      },
+    ],
+    tokenLimit: 10000,
+    debug: false,
+    variables: {},
+    cdpActions: false,
+  };
+}
+
+function createCompleteFormatterThrowCtx(): AgentCtx {
+  const parsedAction = {
+    thoughts: "done",
+    memory: "done",
+    action: {
+      type: "complete",
+      params: {
+        success: true,
+        text: "unused",
+      },
+    },
+  };
+
+  const llm = {
+    invoke: async () => ({
+      role: "assistant" as const,
+      content: "ok",
+    }),
+    invokeStructured: async () => ({
+      rawText: "{}",
+      parsed: parsedAction,
+    }),
+    getProviderId: () => "mock",
+    getModelId: () => "mock-model",
+    getCapabilities: () => ({
+      multimodal: false,
+      toolCalling: true,
+      jsonMode: true,
+    }),
+  } as unknown as AgentCtx["llm"];
+
+  return {
+    llm,
+    actions: [
+      {
+        type: "complete",
+        actionParams: z.object({
+          success: z.boolean(),
+          text: z.string().optional(),
+        }),
+        run: async () => ({ success: true, message: "task complete" }),
+        completeAction: async () => {
+          throw new Error("formatter failed");
+        },
+      },
+    ],
+    tokenLimit: 10000,
+    debug: true,
+    variables: {},
+    cdpActions: false,
+  };
+}
+
+function createCompleteFormatterObjectOutputCtx(): AgentCtx {
+  const parsedAction = {
+    thoughts: "done",
+    memory: "done",
+    action: {
+      type: "complete",
+      params: {
+        success: true,
+        text: "unused",
+      },
+    },
+  };
+
+  const llm = {
+    invoke: async () => ({
+      role: "assistant" as const,
+      content: "ok",
+    }),
+    invokeStructured: async () => ({
+      rawText: "{}",
+      parsed: parsedAction,
+    }),
+    getProviderId: () => "mock",
+    getModelId: () => "mock-model",
+    getCapabilities: () => ({
+      multimodal: false,
+      toolCalling: true,
+      jsonMode: true,
+    }),
+  } as unknown as AgentCtx["llm"];
+
+  return {
+    llm,
+    actions: [
+      {
+        type: "complete",
+        actionParams: z.object({
+          success: z.boolean(),
+          text: z.string().optional(),
+        }),
+        run: async () => ({ success: true, message: "task complete" }),
+        completeAction: async () =>
+          ({ foo: "bar" } as unknown as string),
+      },
+    ],
+    tokenLimit: 10000,
+    debug: false,
+    variables: {},
+    cdpActions: false,
+  };
+}
+
+function createMissingRunHandlerCtx(): AgentCtx {
+  const parsedAction = {
+    thoughts: "done",
+    memory: "done",
+    action: {
+      type: "complete",
+      params: {
+        success: true,
+        text: "unused",
+      },
+    },
+  };
+
+  const llm = {
+    invoke: async () => ({
+      role: "assistant" as const,
+      content: "ok",
+    }),
+    invokeStructured: async () => ({
+      rawText: "{}",
+      parsed: parsedAction,
+    }),
+    getProviderId: () => "mock",
+    getModelId: () => "mock-model",
+    getCapabilities: () => ({
+      multimodal: false,
+      toolCalling: true,
+      jsonMode: true,
+    }),
+  } as unknown as AgentCtx["llm"];
+
+  return {
+    llm,
+    actions: [
+      {
+        type: "complete",
+        actionParams: z.object({
+          success: z.boolean(),
+          text: z.string().optional(),
+        }),
+        run: undefined as unknown as AgentActionDefinition["run"],
+      },
+    ],
+    tokenLimit: 10000,
+    debug: false,
+    variables: {},
+    cdpActions: false,
+  };
+}
+
+function createInvalidOutputCtx(): AgentCtx {
+  const parsedAction = {
+    thoughts: "done",
+    memory: "done",
+    action: {
+      type: "complete",
+      params: {
+        success: true,
+        text: "unused",
+      },
+    },
+  };
+
+  const llm = {
+    invoke: async () => ({
+      role: "assistant" as const,
+      content: "ok",
+    }),
+    invokeStructured: async () => ({
+      rawText: "{}",
+      parsed: parsedAction,
+    }),
+    getProviderId: () => "mock",
+    getModelId: () => "mock-model",
+    getCapabilities: () => ({
+      multimodal: false,
+      toolCalling: true,
+      jsonMode: true,
+    }),
+  } as unknown as AgentCtx["llm"];
+
+  return {
+    llm,
+    actions: [
+      {
+        type: "complete",
+        actionParams: z.object({
+          success: z.boolean(),
+          text: z.string().optional(),
+        }),
+        run: async () => null as unknown as { success: boolean; message: string },
+      },
+    ],
+    tokenLimit: 10000,
+    debug: false,
+    variables: {},
+    cdpActions: false,
+  };
+}
+
+function createSchemaRetryCtx(
+  rawText: string,
+  providerId = "mock",
+  modelId = "mock-model"
+): AgentCtx {
+  const parsedAction = {
+    thoughts: "done",
+    memory: "done",
+    action: {
+      type: "complete",
+      params: {
+        success: true,
+        text: "final answer",
+      },
+    },
+  };
+
+  const invokeStructured = jest
+    .fn()
+    .mockResolvedValueOnce({
+      rawText,
+      parsed: null,
+    })
+    .mockResolvedValue({
+      rawText: JSON.stringify(parsedAction),
+      parsed: parsedAction,
+    });
+
+  const llm = {
+    invoke: async () => ({
+      role: "assistant" as const,
+      content: "ok",
+    }),
+    invokeStructured,
+    getProviderId: () => providerId,
+    getModelId: () => modelId,
+    getCapabilities: () => ({
+      multimodal: false,
+      toolCalling: true,
+      jsonMode: true,
+    }),
+  } as unknown as AgentCtx["llm"];
+
+  return {
+    llm,
+    actions: [createCompleteActionDefinition()],
+    tokenLimit: 10000,
+    debug: false,
+    variables: {},
+    cdpActions: false,
+  };
+}
+
+function createTransientStructuredFailureCtx(
+  failurePayload: unknown = { reason: "temporary llm failure" }
+): AgentCtx {
+  const parsedAction = {
+    thoughts: "done",
+    memory: "done",
+    action: {
+      type: "complete",
+      params: {
+        success: true,
+        text: "final answer",
+      },
+    },
+  };
+
+  const invokeStructured = jest
+    .fn()
+    .mockRejectedValueOnce(failurePayload)
+    .mockResolvedValue({
+      rawText: JSON.stringify(parsedAction),
+      parsed: parsedAction,
+    });
+
+  const llm = {
+    invoke: async () => ({
+      role: "assistant" as const,
+      content: "ok",
+    }),
+    invokeStructured,
+    getProviderId: () => "mock",
+    getModelId: () => "mock-model",
+    getCapabilities: () => ({
+      multimodal: false,
+      toolCalling: true,
+      jsonMode: true,
+    }),
+  } as unknown as AgentCtx["llm"];
+
+  return {
+    llm,
+    actions: [createCompleteActionDefinition()],
+    tokenLimit: 10000,
+    debug: false,
+    variables: {},
+    cdpActions: false,
+  };
+}
+
+function createCircularParamsStepCtx(): AgentCtx {
+  const circularParams: Record<string, unknown> = { id: "progress" };
+  circularParams.self = circularParams;
+
+  const nonCompleteAction = {
+    thoughts: "progress",
+    memory: "progress",
+    action: {
+      type: "recordProgress",
+      params: circularParams,
+    },
+  };
+
+  const completeAction = {
+    thoughts: "done",
+    memory: "done",
+    action: {
+      type: "complete",
+      params: {
+        success: true,
+        text: "final answer",
+      },
+    },
+  };
+
+  const invokeStructured = jest
+    .fn()
+    .mockResolvedValueOnce({
+      rawText: "{}",
+      parsed: nonCompleteAction,
+    })
+    .mockResolvedValueOnce({
+      rawText: "{}",
+      parsed: completeAction,
+    });
+
+  const llm = {
+    invoke: async () => ({
+      role: "assistant" as const,
+      content: "ok",
+    }),
+    invokeStructured,
+    getProviderId: () => "mock",
+    getModelId: () => "mock-model",
+    getCapabilities: () => ({
+      multimodal: false,
+      toolCalling: true,
+      jsonMode: true,
+    }),
+  } as unknown as AgentCtx["llm"];
+
+  return {
+    llm,
+    actions: [
+      {
+        type: "recordProgress",
+        actionParams: z.record(z.string(), z.unknown()),
+        run: async () => ({
+          success: true,
+          message: "progress saved",
+        }),
+      },
+      createCompleteActionDefinition(),
+    ],
+    tokenLimit: 10000,
+    debug: false,
+    variables: {},
+    cdpActions: false,
+  };
+}
+
+function createSchemaErrorSummaryCtx(): AgentCtx {
+  const parsedAction = {
+    thoughts: "done",
+    memory: "done",
+    action: {
+      type: "complete",
+      params: {
+        success: true,
+        text: "final answer",
+      },
+    },
+  };
+
+  const invokeStructured = jest.fn().mockResolvedValue({
+    rawText: JSON.stringify(parsedAction),
+    parsed: parsedAction,
+  });
+
+  const llm = {
+    invoke: async () => ({
+      role: "assistant" as const,
+      content: "ok",
+    }),
+    invokeStructured,
+    getProviderId: () => "mock",
+    getModelId: () => "mock-model",
+    getCapabilities: () => ({
+      multimodal: false,
+      toolCalling: true,
+      jsonMode: true,
+    }),
+  } as unknown as AgentCtx["llm"];
+
+  return {
+    llm,
+    actions: [createCompleteActionDefinition()],
+    tokenLimit: 10000,
+    debug: false,
+    variables: {},
+    cdpActions: false,
+    schemaErrors: [
+      { stepIndex: 10, error: "x".repeat(3000), rawResponse: "{}" },
+      { stepIndex: 11, error: "y".repeat(3000), rawResponse: "{}" },
+      { stepIndex: 12, error: "z".repeat(3000), rawResponse: "{}" },
+    ],
+  };
+}
+
+function createRepeatedActionThenCompleteCtx(repeatedSteps: number): AgentCtx {
+  const repeatedAction = {
+    thoughts: "progress",
+    memory: "progress",
+    action: {
+      type: "recordProgress",
+      params: {
+        id: "progress",
+      },
+    },
+  };
+  const completeAction = {
+    thoughts: "done",
+    memory: "done",
+    action: {
+      type: "complete",
+      params: {
+        success: true,
+        text: "final answer",
+      },
+    },
+  };
+
+  const invokeStructured = jest.fn();
+  for (let idx = 0; idx < repeatedSteps; idx += 1) {
+    invokeStructured.mockResolvedValueOnce({
+      rawText: "{}",
+      parsed: repeatedAction,
+    });
+  }
+  invokeStructured.mockResolvedValue({
+    rawText: "{}",
+    parsed: completeAction,
+  });
+
+  const llm = {
+    invoke: async () => ({
+      role: "assistant" as const,
+      content: "ok",
+    }),
+    invokeStructured,
+    getProviderId: () => "mock",
+    getModelId: () => "mock-model",
+    getCapabilities: () => ({
+      multimodal: false,
+      toolCalling: true,
+      jsonMode: true,
+    }),
+  } as unknown as AgentCtx["llm"];
+
+  return {
+    llm,
+    actions: [
+      {
+        type: "recordProgress",
+        actionParams: z.object({ id: z.string() }),
+        run: async () => ({
+          success: true,
+          message: "progress saved",
+        }),
+      },
+      createCompleteActionDefinition(),
+    ],
+    tokenLimit: 10000,
+    debug: false,
+    variables: {},
+    cdpActions: false,
+  };
+}
+
+function createTaskState(page: Page): TaskState {
+  return {
+    id: "task-1",
+    task: "finish now",
+    status: TaskStatus.PENDING,
+    startingPage: page,
+    steps: [],
+  };
+}
+
+describe("runAgentTask completion behavior", () => {
+  beforeEach(() => {
+    jest.clearAllMocks();
+
+    captureDOMState.mockResolvedValue({
+      elements: new Map(),
+      domState: "dom",
+      xpathMap: {},
+      backendNodeMap: {},
+      frameMap: new Map(),
+    });
+    waitForSettledDOM.mockResolvedValue({
+      durationMs: 1,
+      lifecycleMs: 0,
+      networkMs: 1,
+      requestsSeen: 0,
+      peakInflight: 0,
+      resolvedByTimeout: false,
+      forcedDrops: 0,
+    });
+    initializeRuntimeContext.mockResolvedValue({
+      cdpClient: {},
+      frameContextManager: {},
+    });
+    buildAgentStepMessages.mockResolvedValue([]);
+  });
+
+  it("marks task completed when complete action succeeds", async () => {
+    const page = createMockPage();
+    const result = await runAgentTask(
+      createAgentCtx({ success: true, text: "final answer" }),
+      createTaskState(page)
+    );
+
+    expect(result.status).toBe(TaskStatus.COMPLETED);
+    expect(result.output).toBe("final answer");
+    expect(result.steps).toHaveLength(1);
+  });
+
+  it("propagates frame-filter override into settle and DOM capture calls", async () => {
+    const page = createMockPage();
+    const ctx = createAgentCtx({ success: true, text: "final answer" });
+    ctx.filterAdTrackingFrames = false;
+
+    await runAgentTask(ctx, createTaskState(page));
+
+    expect(waitForSettledDOM).toHaveBeenCalledWith(
+      page,
+      undefined,
+      expect.objectContaining({
+        filterAdTrackingFrames: false,
+      })
+    );
+    expect(captureDOMState).toHaveBeenCalledWith(
+      page,
+      expect.objectContaining({
+        filterAdTrackingFrames: false,
+      })
+    );
+  });
+
+  it("marks task failed when complete action signals failure", async () => {
+    const page = createMockPage();
+    const result = await runAgentTask(
+      createAgentCtx({ success: false, text: "nope" }),
+      createTaskState(page)
+    );
+
+    expect(result.status).toBe(TaskStatus.FAILED);
+    expect(result.output).toBe("task failed by model decision");
+    expect(result.steps).toHaveLength(1);
+  });
+
+  it("surfaces thrown action errors with readable messages", async () => {
+    const page = createMockPage();
+    const result = await runAgentTask(
+      createThrowingCompleteCtx("intentional failure"),
+      createTaskState(page)
+    );
+
+    expect(result.status).toBe(TaskStatus.FAILED);
+    expect(result.output).toContain("Action complete failed: intentional failure");
+  });
+
+  it("serializes non-Error thrown values in action failures", async () => {
+    const page = createMockPage();
+    const result = await runAgentTask(
+      createThrowingObjectCtx(),
+      createTaskState(page)
+    );
+
+    expect(result.status).toBe(TaskStatus.FAILED);
+    expect(result.output).toContain('Action complete failed: {"reason":"object failure"}');
+  });
+
+  it("falls back to action message when complete formatter throws", async () => {
+    const page = createMockPage();
+    const warnSpy = jest.spyOn(console, "warn").mockImplementation(() => {});
+    const logSpy = jest.spyOn(console, "log").mockImplementation(() => {});
+
+    try {
+      const result = await runAgentTask(
+        createCompleteFormatterThrowCtx(),
+        createTaskState(page)
+      );
+      expect(result.status).toBe(TaskStatus.COMPLETED);
+      expect(result.output).toBe("task complete");
+      expect(warnSpy).toHaveBeenCalledWith(
+        "[Agent] completeAction formatter failed: formatter failed"
+      );
+    } finally {
+      warnSpy.mockRestore();
+      logSpy.mockRestore();
+    }
+  });
+
+  it("normalizes non-string complete formatter output", async () => {
+    const page = createMockPage();
+    const result = await runAgentTask(
+      createCompleteFormatterObjectOutputCtx(),
+      createTaskState(page)
+    );
+
+    expect(result.status).toBe(TaskStatus.COMPLETED);
+    expect(result.output).toContain('{"foo":"bar"}');
+  });
+
+  it("truncates oversized complete formatter outputs", async () => {
+    const page = createMockPage();
+    const result = await runAgentTask(
+      createAgentCtx({ success: true, text: "x".repeat(30_000) }),
+      createTaskState(page)
+    );
+
+    expect(result.status).toBe(TaskStatus.COMPLETED);
+    expect(result.output).toContain("[truncated");
+    expect((result.output ?? "").length).toBeLessThan(20_500);
+  });
+
+  it("surfaces missing action handler implementations as failures", async () => {
+    const page = createMockPage();
+    const result = await runAgentTask(
+      createMissingRunHandlerCtx(),
+      createTaskState(page)
+    );
+
+    expect(result.status).toBe(TaskStatus.FAILED);
+    expect(result.output).toContain("missing a runnable handler");
+  });
+
+  it("normalizes invalid action outputs to readable failures", async () => {
+    const page = createMockPage();
+    const result = await runAgentTask(
+      createInvalidOutputCtx(),
+      createTaskState(page)
+    );
+
+    expect(result.status).toBe(TaskStatus.FAILED);
+    expect(result.output).toContain("returned invalid output");
+  });
+
+  it("falls back to empty variables when variables enumeration traps throw", async () => {
+    const page = createMockPage();
+    const ctx = createAgentCtx({ success: true, text: "final answer" });
+    ctx.variables = new Proxy(
+      {},
+      {
+        ownKeys: () => {
+          throw new Error("variables trap");
+        },
+      }
+    ) as AgentCtx["variables"];
+
+    const result = await runAgentTask(ctx, createTaskState(page));
+
+    expect(result.status).toBe(TaskStatus.COMPLETED);
+    expect(result.output).toBe("final answer");
+  });
+
+  it("reports CDP initialization failures as action failures", async () => {
+    const page = createMockPage();
+    const ctx = createAgentCtx({ success: true, text: "final answer" });
+    ctx.cdpActions = true;
+    initializeRuntimeContext.mockRejectedValueOnce(new Error("cdp init failed"));
+
+    const result = await runAgentTask(ctx, createTaskState(page));
+
+    expect(result.status).toBe(TaskStatus.FAILED);
+    expect(result.output).toContain("cdp init failed");
+  });
+
+  it("continues when page listener accessors trap during setup/cleanup", async () => {
+    const trappedPage = new Proxy(
+      {
+        url: () => "https://example.com",
+      },
+      {
+        get: (target, prop, receiver) => {
+          if (prop === "on" || prop === "off") {
+            throw new Error("listener trap");
+          }
+          return Reflect.get(target, prop, receiver);
+        },
+      }
+    ) as unknown as Page;
+
+    const result = await runAgentTask(
+      createAgentCtx({ success: true, text: "final answer" }),
+      createTaskState(trappedPage)
+    );
+
+    expect(result.status).toBe(TaskStatus.COMPLETED);
+    expect(result.output).toBe("final answer");
+  });
+
+  it("handles malformed waitForSettledDOM stats without crashing", async () => {
+    let waitCallCount = 0;
+    waitForSettledDOM.mockImplementation(async () => {
+      waitCallCount += 1;
+      if (waitCallCount === 2) {
+        return null;
+      }
+      return {
+        durationMs: 1,
+        lifecycleMs: 0,
+        networkMs: 1,
+        requestsSeen: 0,
+        peakInflight: 0,
+        resolvedByTimeout: false,
+        forcedDrops: 0,
+      };
+    });
+
+    const page = createMockPage();
+    const result = await runAgentTask(
+      createCircularParamsStepCtx(),
+      createTaskState(page)
+    );
+
+    expect(result.status).toBe(TaskStatus.COMPLETED);
+    expect(result.output).toBe("final answer");
+  });
+
+  it("handles page.url traps in repeated-action fingerprinting", async () => {
+    const page = {
+      on: jest.fn(),
+      off: jest.fn(),
+      url: () => {
+        throw new Error("url trap");
+      },
+    } as unknown as Page;
+
+    const result = await runAgentTask(
+      createCircularParamsStepCtx(),
+      createTaskState(page)
+    );
+
+    expect(result.status).toBe(TaskStatus.COMPLETED);
+    expect(result.output).toBe("final answer");
+  });
+
+  it("handles active-page URL getter traps in debug logging", async () => {
+    const page = createMockPage();
+    const nextPage = {
+      on: jest.fn(),
+      off: jest.fn(),
+      url: () => {
+        throw new Error("active page url trap");
+      },
+    } as unknown as Page;
+    const logSpy = jest.spyOn(console, "log").mockImplementation(() => {});
+    const ctx = createAgentCtx({ success: true, text: "final answer" });
+    ctx.debug = true;
+    ctx.activePage = jest.fn().mockResolvedValueOnce(nextPage).mockResolvedValue(nextPage);
+
+    try {
+      const result = await runAgentTask(ctx, createTaskState(page));
+      expect(result.status).toBe(TaskStatus.COMPLETED);
+      expect(result.output).toBe("final answer");
+    } finally {
+      logSpy.mockRestore();
+    }
+  });
+
+  it("sanitizes control characters in active-page debug URL logging", async () => {
+    const page = createMockPage();
+    const nextPage = {
+      on: jest.fn(),
+      off: jest.fn(),
+      url: () => "https://example.com/\u0000bad\npath",
+    } as unknown as Page;
+    const logSpy = jest.spyOn(console, "log").mockImplementation(() => {});
+    const ctx = createAgentCtx({ success: true, text: "final answer" });
+    ctx.debug = true;
+    ctx.activePage = jest.fn().mockResolvedValueOnce(nextPage).mockResolvedValue(nextPage);
+
+    try {
+      const result = await runAgentTask(ctx, createTaskState(page));
+      expect(result.status).toBe(TaskStatus.COMPLETED);
+      expect(result.output).toBe("final answer");
+
+      const matchingLog = logSpy.mock.calls
+        .map((call) => String(call[0] ?? ""))
+        .find((entry) => entry.includes("Switching active page context"));
+      expect(matchingLog).toContain("https://example.com/ bad path");
+      expect(matchingLog).not.toContain("\u0000");
+      expect(matchingLog).not.toContain("\n");
+    } finally {
+      logSpy.mockRestore();
+    }
+  });
+
+  it("throws readable errors for invalid task state input", async () => {
+    await expect(
+      runAgentTask(
+        createAgentCtx({ success: true, text: "final answer" }),
+        undefined as unknown as TaskState
+      )
+    ).rejects.toThrow("Task state not found");
+  });
+
+  it("does not fail task when debug artifact IO throws", async () => {
+    const page = createMockPage();
+    const mkdirSpy = jest.spyOn(fs, "mkdirSync").mockImplementation(() => {
+      throw new Error("mkdir denied");
+    });
+    const writeSpy = jest.spyOn(fs, "writeFileSync").mockImplementation(() => {
+      throw new Error("write denied");
+    });
+    const errorSpy = jest.spyOn(console, "error").mockImplementation(() => {});
+    const logSpy = jest.spyOn(console, "log").mockImplementation(() => {});
+    const ctx = createAgentCtx({ success: true, text: "final answer" });
+    ctx.debug = true;
+
+    try {
+      const result = await runAgentTask(ctx, createTaskState(page), {
+        debugDir: "debug/test",
+      });
+
+      expect(result.status).toBe(TaskStatus.COMPLETED);
+      expect(errorSpy).toHaveBeenCalled();
+      expect(writeSpy).not.toHaveBeenCalled();
+    } finally {
+      mkdirSpy.mockRestore();
+      writeSpy.mockRestore();
+      errorSpy.mockRestore();
+      logSpy.mockRestore();
+    }
+  });
+
+  it("formats non-Error debug IO failures with readable messages", async () => {
+    const page = createMockPage();
+    const mkdirSpy = jest.spyOn(fs, "mkdirSync").mockImplementation(() => {
+      throw { reason: "mkdir object failure" };
+    });
+    const writeSpy = jest.spyOn(fs, "writeFileSync").mockImplementation(() => {
+      return undefined;
+    });
+    const errorSpy = jest.spyOn(console, "error").mockImplementation(() => {});
+    const logSpy = jest.spyOn(console, "log").mockImplementation(() => {});
+    const ctx = createAgentCtx({ success: true, text: "final answer" });
+    ctx.debug = true;
+
+    try {
+      const result = await runAgentTask(ctx, createTaskState(page), {
+        debugDir: "debug/test",
+      });
+
+      expect(result.status).toBe(TaskStatus.COMPLETED);
+      expect(errorSpy).toHaveBeenCalledWith(
+        '[DebugIO] Failed to create directory "debug/test": {"reason":"mkdir object failure"}'
+      );
+      expect(writeSpy).not.toHaveBeenCalled();
+    } finally {
+      mkdirSpy.mockRestore();
+      writeSpy.mockRestore();
+      errorSpy.mockRestore();
+      logSpy.mockRestore();
+    }
+  });
+
+  it("truncates oversized debug IO diagnostics", async () => {
+    const page = createMockPage();
+    const hugeError = `mkdir\n${"x".repeat(10_000)}`;
+    const mkdirSpy = jest.spyOn(fs, "mkdirSync").mockImplementation(() => {
+      throw new Error(hugeError);
+    });
+    const writeSpy = jest.spyOn(fs, "writeFileSync").mockImplementation(() => {
+      return undefined;
+    });
+    const errorSpy = jest.spyOn(console, "error").mockImplementation(() => {});
+    const logSpy = jest.spyOn(console, "log").mockImplementation(() => {});
+    const ctx = createAgentCtx({ success: true, text: "final answer" });
+    ctx.debug = true;
+
+    try {
+      const result = await runAgentTask(ctx, createTaskState(page), {
+        debugDir: "debug/test",
+      });
+
+      expect(result.status).toBe(TaskStatus.COMPLETED);
+      const debugIoError = errorSpy.mock.calls
+        .map((call) => String(call[0]))
+        .find((line) => line.includes('[DebugIO] Failed to create directory'));
+      expect(debugIoError).toBeDefined();
+      expect(debugIoError).toContain("[truncated");
+      expect(debugIoError).not.toContain("\n");
+      expect(debugIoError).not.toContain("x".repeat(6_000));
+      expect(debugIoError?.length ?? 0).toBeLessThan(4_300);
+      expect(writeSpy).not.toHaveBeenCalled();
+    } finally {
+      mkdirSpy.mockRestore();
+      writeSpy.mockRestore();
+      errorSpy.mockRestore();
+      logSpy.mockRestore();
+    }
+  });
+
+  it("skips step artifact writes when step debug directory creation fails", async () => {
+    const page = createMockPage();
+    const mkdirSpy = jest
+      .spyOn(fs, "mkdirSync")
+      .mockImplementation((dirPath: fs.PathLike) => {
+        if (String(dirPath).includes("step-0")) {
+          throw new Error("step dir denied");
+        }
+        return undefined;
+      });
+    const writeSpy = jest.spyOn(fs, "writeFileSync").mockImplementation(() => {
+      return undefined;
+    });
+    const errorSpy = jest.spyOn(console, "error").mockImplementation(() => {});
+    const logSpy = jest.spyOn(console, "log").mockImplementation(() => {});
+    const ctx = createAgentCtx({ success: true, text: "final answer" });
+    ctx.debug = true;
+
+    try {
+      const result = await runAgentTask(ctx, createTaskState(page), {
+        debugDir: "debug/test",
+      });
+
+      expect(result.status).toBe(TaskStatus.COMPLETED);
+      const writtenFiles = writeSpy.mock.calls.map((call) => String(call[0]));
+      expect(writtenFiles.some((path) => path.includes("step-0"))).toBe(false);
+      expect(errorSpy).toHaveBeenCalled();
+    } finally {
+      mkdirSpy.mockRestore();
+      writeSpy.mockRestore();
+      errorSpy.mockRestore();
+      logSpy.mockRestore();
+    }
+  });
+
+  it("continues task when visual screenshot composition fails", async () => {
+    const page = createMockPage();
+    const getCDPClientSpy = jest
+      .spyOn(cdp, "getCDPClient")
+      .mockRejectedValue(new Error("cdp screenshot unavailable"));
+    captureDOMState.mockResolvedValue({
+      elements: new Map(),
+      domState: "dom",
+      xpathMap: {},
+      backendNodeMap: {},
+      frameMap: new Map(),
+      visualOverlay: "overlay-base64",
+    });
+
+    try {
+      const result = await runAgentTask(
+        createAgentCtx({ success: true, text: "final answer" }),
+        createTaskState(page),
+        { enableVisualMode: true }
+      );
+
+      expect(result.status).toBe(TaskStatus.COMPLETED);
+      expect(result.output).toBe("final answer");
+    } finally {
+      getCDPClientSpy.mockRestore();
+    }
+  });
+
+  it("continues frame-graph snapshot writing when frame-manager debug setter throws", async () => {
+    const page = createMockPage();
+    const getCDPClientSpy = jest
+      .spyOn(cdp, "getCDPClient")
+      .mockResolvedValue({} as Awaited<ReturnType<typeof cdp.getCDPClient>>);
+    const getOrCreateFrameContextManagerSpy = jest
+      .spyOn(cdp, "getOrCreateFrameContextManager")
+      .mockReturnValue({
+        setDebug: () => {
+          throw new Error(`frame-debug\u0000\n${"x".repeat(10_000)}`);
+        },
+        toJSON: () => ({ frames: [] }),
+      } as unknown as ReturnType<typeof cdp.getOrCreateFrameContextManager>);
+    const writeSpy = jest.spyOn(fs, "writeFileSync").mockImplementation(() => {
+      return undefined;
+    });
+    const warnSpy = jest.spyOn(console, "warn").mockImplementation(() => {});
+    const ctx = createRepeatedActionThenCompleteCtx(1);
+    ctx.debug = true;
+
+    try {
+      const result = await runAgentTask(ctx, createTaskState(page), {
+        debugDir: "debug/test",
+      });
+      expect(result.status).toBe(TaskStatus.COMPLETED);
+      expect(getCDPClientSpy).toHaveBeenCalled();
+      expect(getOrCreateFrameContextManagerSpy).toHaveBeenCalled();
+      const warning = String(
+        warnSpy.mock.calls.find((call) =>
+          String(call[0] ?? "").includes("Failed to configure frame graph debug mode")
+        )?.[0] ?? ""
+      );
+      expect(warning).toContain("[truncated");
+      expect(warning).not.toContain("\u0000");
+      expect(warning).not.toContain("\n");
+      expect(
+        warnSpy.mock.calls.some((call) =>
+          String(call[0] ?? "").includes("Failed to write frame graph")
+        )
+      ).toBe(false);
+    } finally {
+      getCDPClientSpy.mockRestore();
+      getOrCreateFrameContextManagerSpy.mockRestore();
+      writeSpy.mockRestore();
+      warnSpy.mockRestore();
+    }
+  });
+
+  it("truncates oversized structured-output diagnostics", async () => {
+    const page = createMockPage();
+    const hugeRaw = "x".repeat(120_000);
+    const errorSpy = jest.spyOn(console, "error").mockImplementation(() => {});
+    const ctx = createSchemaRetryCtx(hugeRaw);
+
+    try {
+      const result = await runAgentTask(ctx, createTaskState(page));
+      expect(result.status).toBe(TaskStatus.COMPLETED);
+      expect(ctx.schemaErrors).toBeDefined();
+      const firstSchemaError = ctx.schemaErrors?.[0];
+      expect(firstSchemaError).toBeDefined();
+      expect(firstSchemaError?.error).toContain(
+        "was skipped for validation diagnostics"
+      );
+      expect(firstSchemaError?.rawResponse).toContain("[truncated");
+      expect(firstSchemaError?.rawResponse.length ?? 0).toBeLessThan(8_300);
+
+      const structuredLogLine = errorSpy.mock.calls
+        .map((call) => String(call[0]))
+        .find((line) => line.includes("[LLM][StructuredOutput]"));
+      expect(structuredLogLine).toBeDefined();
+      expect(structuredLogLine).toContain("[truncated");
+      expect(structuredLogLine).not.toContain(hugeRaw);
+
+      const invokeStructuredMock = (
+        ctx.llm as unknown as { invokeStructured: jest.Mock }
+      ).invokeStructured;
+      const secondCallMessages = invokeStructuredMock.mock.calls[1]?.[1] as Array<{
+        role: string;
+        content: unknown;
+      }>;
+      expect(Array.isArray(secondCallMessages)).toBe(true);
+      const retryAssistantMessage = secondCallMessages
+        .slice()
+        .reverse()
+        .find((message) => message.role === "assistant");
+      const retryUserMessage = secondCallMessages
+        .slice()
+        .reverse()
+        .find((message) => message.role === "user");
+
+      expect(typeof retryAssistantMessage?.content).toBe("string");
+      expect(typeof retryUserMessage?.content).toBe("string");
+      expect(retryAssistantMessage?.content).toContain("[truncated");
+      expect(retryUserMessage?.content).toContain(
+        "was skipped for validation diagnostics"
+      );
+      expect(retryAssistantMessage?.content).not.toContain(hugeRaw);
+      expect(retryUserMessage?.content).not.toContain(hugeRaw);
+      expect((retryUserMessage?.content as string).length).toBeLessThan(4_500);
+    } finally {
+      errorSpy.mockRestore();
+    }
+  });
+
+  it("parses BOM-prefixed structured-output diagnostics for zod feedback", async () => {
+    const page = createMockPage();
+    const ctx = createSchemaRetryCtx('\uFEFF{"foo":"bar"}');
+    const errorSpy = jest.spyOn(console, "error").mockImplementation(() => {});
+
+    try {
+      await runAgentTask(ctx, createTaskState(page));
+
+      const invokeStructuredMock = (
+        ctx.llm as unknown as { invokeStructured: jest.Mock }
+      ).invokeStructured;
+      const secondCallMessages = invokeStructuredMock.mock.calls[1]?.[1] as Array<{
+        role: string;
+        content: unknown;
+      }>;
+      const retryUserMessage = secondCallMessages
+        .slice()
+        .reverse()
+        .find((message) => message.role === "user");
+
+      expect(typeof retryUserMessage?.content).toBe("string");
+      expect(retryUserMessage?.content).toContain('"thoughts"');
+      expect(retryUserMessage?.content).not.toContain("Unexpected token");
+    } finally {
+      errorSpy.mockRestore();
+    }
+  });
+
+  it("formats structured-output retry failures with readable messages", async () => {
+    const page = createMockPage();
+    const errorSpy = jest.spyOn(console, "error").mockImplementation(() => {});
+    const ctx = createTransientStructuredFailureCtx();
+
+    try {
+      const result = await runAgentTask(ctx, createTaskState(page));
+      expect(result.status).toBe(TaskStatus.COMPLETED);
+
+      const retryLogLine = errorSpy.mock.calls
+        .map((call) => String(call[0]))
+        .find((line) => line.includes("[LLM][StructuredOutput] Retry error"));
+      expect(retryLogLine).toBe(
+        '[LLM][StructuredOutput] Retry error Retry Attempt 1/3: {"reason":"temporary llm failure"}'
+      );
+    } finally {
+      errorSpy.mockRestore();
+    }
+  });
+
+  it("truncates oversized structured-output retry failure diagnostics", async () => {
+    const page = createMockPage();
+    const hugeFailure = { reason: "x".repeat(10_000) };
+    const errorSpy = jest.spyOn(console, "error").mockImplementation(() => {});
+    const ctx = createTransientStructuredFailureCtx(hugeFailure);
+
+    try {
+      const result = await runAgentTask(ctx, createTaskState(page));
+      expect(result.status).toBe(TaskStatus.COMPLETED);
+
+      const retryLogLine = errorSpy.mock.calls
+        .map((call) => String(call[0]))
+        .find((line) => line.includes("[LLM][StructuredOutput] Retry error"));
+      expect(retryLogLine).toBeDefined();
+      expect(retryLogLine).toContain("[truncated");
+      expect(retryLogLine).not.toContain(hugeFailure.reason);
+      expect(retryLogLine?.length ?? 0).toBeLessThan(4_600);
+    } finally {
+      errorSpy.mockRestore();
+    }
+  });
+
+  it("sanitizes structured-output provider diagnostics in logs", async () => {
+    const page = createMockPage();
+    const noisyProviderId = `provider\n${"x".repeat(200)}`;
+    const noisyModelId = `model\t${"y".repeat(200)}`;
+    const errorSpy = jest.spyOn(console, "error").mockImplementation(() => {});
+    const ctx = createSchemaRetryCtx("{}", noisyProviderId, noisyModelId);
+
+    try {
+      await runAgentTask(ctx, createTaskState(page));
+
+      const structuredLogLine = errorSpy.mock.calls
+        .map((call) => String(call[0]))
+        .find((line) =>
+          line.includes("[LLM][StructuredOutput] Failed to parse response")
+        );
+      expect(structuredLogLine).toBeDefined();
+      expect(structuredLogLine).toContain("provider ");
+      expect(structuredLogLine).toContain("model ");
+      expect(structuredLogLine).toContain("[truncated");
+      expect(structuredLogLine).not.toContain("\n");
+      expect(structuredLogLine).not.toContain("\t");
+    } finally {
+      errorSpy.mockRestore();
+    }
+  });
+
+  it("does not crash when action fingerprint params contain circular values", async () => {
+    const page = createMockPage();
+    const ctx = createCircularParamsStepCtx();
+
+    const result = await runAgentTask(ctx, createTaskState(page));
+    expect(result.status).toBe(TaskStatus.COMPLETED);
+    expect(result.output).toBe("final answer");
+  });
+
+  it("fails when identical successful actions repeat without DOM progress", async () => {
+    const page = createMockPage();
+    const ctx = createRepeatedActionThenCompleteCtx(4);
+
+    const result = await runAgentTask(ctx, createTaskState(page));
+
+    expect(result.status).toBe(TaskStatus.FAILED);
+    expect(result.output).toContain("Agent appears stuck");
+  });
+
+  it("allows repeated successful actions when DOM state keeps changing", async () => {
+    const page = createMockPage();
+    const ctx = createRepeatedActionThenCompleteCtx(4);
+    let domSnapshotIndex = 0;
+    captureDOMState.mockImplementation(async () => {
+      domSnapshotIndex += 1;
+      return {
+        elements: new Map(),
+        domState: `dom-${domSnapshotIndex}`,
+        xpathMap: {},
+        backendNodeMap: {},
+        frameMap: new Map(),
+      };
+    });
+
+    const result = await runAgentTask(ctx, createTaskState(page));
+
+    expect(result.status).toBe(TaskStatus.COMPLETED);
+    expect(result.output).toBe("final answer");
+  });
+
+  it("truncates schema-error summaries appended to retry context", async () => {
+    const page = createMockPage();
+    const ctx = createSchemaErrorSummaryCtx();
+
+    await runAgentTask(ctx, createTaskState(page));
+
+    const invokeStructuredMock = (
+      ctx.llm as unknown as { invokeStructured: jest.Mock }
+    ).invokeStructured;
+    const firstCallMessages = invokeStructuredMock.mock.calls[0]?.[1] as Array<{
+      role: string;
+      content: unknown;
+    }>;
+    const schemaSummaryMessage = firstCallMessages.find(
+      (message) =>
+        message.role === "user" &&
+        typeof message.content === "string" &&
+        message.content.includes("Previous steps had schema validation errors")
+    );
+
+    expect(schemaSummaryMessage).toBeDefined();
+    const summaryContent = schemaSummaryMessage?.content as string;
+    expect(summaryContent).toContain("[truncated");
+    expect(summaryContent.length).toBeLessThan(3_600);
+  });
+
+  it("caps schema-error history to avoid unbounded growth", async () => {
+    const page = createMockPage();
+    const ctx = createSchemaRetryCtx("not-json");
+    ctx.schemaErrors = Array.from({ length: 20 }, (_, index) => ({
+      stepIndex: 100 + index,
+      error: `existing-error-${index}`,
+      rawResponse: "{}",
+    }));
+    const errorSpy = jest.spyOn(console, "error").mockImplementation(() => {});
+
+    try {
+      await runAgentTask(ctx, createTaskState(page));
+
+      expect(ctx.schemaErrors).toHaveLength(20);
+      expect(ctx.schemaErrors?.some((error) => error.stepIndex === 100)).toBe(
+        false
+      );
+      expect(ctx.schemaErrors?.some((error) => error.stepIndex === 0)).toBe(true);
+    } finally {
+      errorSpy.mockRestore();
+    }
+  });
+});
diff --git a/src/agent/tools/agent.ts b/src/agent/tools/agent.ts
index ff38c35c..097e918f 100644
--- a/src/agent/tools/agent.ts
+++ b/src/agent/tools/agent.ts
@@ -1,5 +1,6 @@
 import {
   ActionCacheOutput,
+  AgentOutput,
   AgentStep,
   AgentTaskOutput,
 } from "@/types/agent/types";
@@ -19,14 +20,16 @@ import {
   getCDPClient,
   getOrCreateFrameContextManager,
 } from "@/cdp";
+import { formatUnknownError } from "@/utils";
+import { normalizePageUrl } from "@/utils/page-url";
 import { retry } from "@/utils/retry";
 import { sleep } from "@/utils/sleep";
 import { waitForSettledDOM } from "@/utils/waitForSettledDOM";
 import { captureDOMState } from "../shared/dom-capture";
 import { initializeRuntimeContext } from "../shared/runtime-context";
 
-import { AgentOutputFn, endTaskStatuses } from "@hyperbrowser/agent/types";
-import { TaskParams, TaskState, TaskStatus } from "@hyperbrowser/agent/types";
+import { AgentOutputFn, endTaskStatuses } from "@/types";
+import { TaskParams, TaskState, TaskStatus } from "@/types";
 
 import { HyperagentError } from "../error";
 import { buildAgentStepMessages } from "../messages/builder";
@@ -43,6 +46,283 @@ import { buildActionCacheEntry } from "../shared/action-cache";
 // DomChunkAggregator logic moved to shared/dom-capture.ts
 
 const READ_ONLY_ACTIONS = new Set(["wait", "extract", "complete"]);
+const MAX_REPEATED_ACTIONS_WITHOUT_PROGRESS = 4;
+const MAX_STRUCTURED_DIAGNOSTIC_PARSE_CHARS = 100_000;
+const MAX_STRUCTURED_DIAGNOSTIC_ERROR_CHARS = 4_000;
+const MAX_STRUCTURED_DIAGNOSTIC_RAW_RESPONSE_CHARS = 8_000;
+const MAX_STRUCTURED_DIAGNOSTIC_IDENTIFIER_CHARS = 120;
+const MAX_SCHEMA_ERROR_SUMMARY_CHARS = 3_000;
+const MAX_SCHEMA_ERROR_HISTORY = 20;
+const MAX_RUNTIME_ACTION_TYPE_CHARS = 120;
+const MAX_RUNTIME_ACTION_MESSAGE_CHARS = 4_000;
+const MAX_RUNTIME_URL_CHARS = 1_000;
+const MAX_RUNTIME_TASK_OUTPUT_CHARS = 20_000;
+const MAX_DOM_PROGRESS_SIGNATURE_CHARS = 800;
+
+function truncateDiagnosticText(value: string, maxChars: number): string {
+  if (value.length <= maxChars) {
+    return value;
+  }
+
+  const omittedChars = value.length - maxChars;
+  return `${value.slice(0, maxChars)}... [truncated ${omittedChars} chars]`;
+}
+
+function sanitizeDiagnosticText(value: string): string {
+  if (value.length === 0) {
+    return value;
+  }
+  const withoutControlChars = Array.from(value, (char) => {
+    const code = char.charCodeAt(0);
+    return (code >= 0 && code < 32) || code === 127 ? " " : char;
+  }).join("");
+  return withoutControlChars.replace(/\s+/g, " ").trim();
+}
+
+function formatDiagnosticText(
+  value: unknown,
+  maxChars: number,
+  fallback: string
+): string {
+  const raw = typeof value === "string" ? value : formatUnknownError(value);
+  const normalized = sanitizeDiagnosticText(raw);
+  if (normalized.length === 0) {
+    return fallback;
+  }
+  return truncateDiagnosticText(normalized, maxChars);
+}
+
+function formatDiagnosticIdentifier(value: unknown, fallback: string): string {
+  return formatDiagnosticText(
+    value,
+    MAX_STRUCTURED_DIAGNOSTIC_IDENTIFIER_CHARS,
+    fallback
+  );
+}
+
+function safeReadRecordField(value: unknown, key: string): unknown {
+  if (!value || (typeof value !== "object" && typeof value !== "function")) {
+    return undefined;
+  }
+  try {
+    return (value as Record<string, unknown>)[key];
+  } catch {
+    return undefined;
+  }
+}
+
+function normalizeRuntimeActionType(value: unknown): string {
+  return formatDiagnosticText(
+    value,
+    MAX_RUNTIME_ACTION_TYPE_CHARS,
+    "unknown"
+  );
+}
+
+function normalizeRuntimeActionMessage(value: unknown): string {
+  return formatDiagnosticText(
+    value,
+    MAX_RUNTIME_ACTION_MESSAGE_CHARS,
+    "Action failed without an error message."
+  );
+}
+
+function normalizeTaskOutputText(value: unknown, fallback: string): string {
+  const raw =
+    typeof value === "string"
+      ? value
+      : value == null
+        ? fallback
+        : formatUnknownError(value);
+  const normalized = raw.replace(/\r\n?/g, "\n").trim();
+  if (normalized.length === 0) {
+    return fallback;
+  }
+  return truncateDiagnosticText(normalized, MAX_RUNTIME_TASK_OUTPUT_CHARS);
+}
+
+function safeGetPageUrl(page: Page): string {
+  try {
+    return normalizePageUrl(page.url(), {
+      maxChars: MAX_RUNTIME_URL_CHARS,
+    });
+  } catch {
+    return "about:blank";
+  }
+}
+
+function buildDomProgressSignature(domState: A11yDOMState): string {
+  const rawDomState = safeReadRecordField(domState, "domState");
+  const normalized = formatDiagnosticText(
+    rawDomState,
+    MAX_DOM_PROGRESS_SIGNATURE_CHARS,
+    "DOM state unavailable"
+  );
+  if (normalized.length <= MAX_DOM_PROGRESS_SIGNATURE_CHARS) {
+    return normalized;
+  }
+  return truncateDiagnosticText(normalized, MAX_DOM_PROGRESS_SIGNATURE_CHARS);
+}
+
+function normalizeWaitStats(value: unknown): {
+  durationMs: number;
+  lifecycleMs: number;
+  networkMs: number;
+  requestsSeen: number;
+  peakInflight: number;
+  resolvedByTimeout: boolean;
+  forcedDrops: number;
+} {
+  if (!value || typeof value !== "object") {
+    return {
+      durationMs: 0,
+      lifecycleMs: 0,
+      networkMs: 0,
+      requestsSeen: 0,
+      peakInflight: 0,
+      resolvedByTimeout: false,
+      forcedDrops: 0,
+    };
+  }
+  const readNumber = (key: string): number => {
+    const field = safeReadRecordField(value, key);
+    if (typeof field !== "number" || !Number.isFinite(field)) {
+      return 0;
+    }
+    return field;
+  };
+  return {
+    durationMs: readNumber("durationMs"),
+    lifecycleMs: readNumber("lifecycleMs"),
+    networkMs: readNumber("networkMs"),
+    requestsSeen: readNumber("requestsSeen"),
+    peakInflight: readNumber("peakInflight"),
+    resolvedByTimeout: safeReadRecordField(value, "resolvedByTimeout") === true,
+    forcedDrops: readNumber("forcedDrops"),
+  };
+}
+
+function normalizeActionOutput(
+  value: unknown,
+  actionType: string
+): ActionOutput {
+  if (!value || typeof value !== "object") {
+    return {
+      success: false,
+      message: `Action ${actionType} returned invalid output: ${normalizeRuntimeActionMessage(
+        value
+      )}`,
+    };
+  }
+  const success = safeReadRecordField(value, "success") === true;
+  const message = normalizeRuntimeActionMessage(
+    safeReadRecordField(value, "message")
+  );
+  const extract = safeReadRecordField(value, "extract");
+  const debug = safeReadRecordField(value, "debug");
+  return {
+    success,
+    message,
+    ...(extract !== undefined ? { extract: extract as object } : {}),
+    ...(debug !== undefined ? { debug } : {}),
+  };
+}
+
+function normalizeAgentOutput(value: unknown): AgentOutput {
+  const thoughts = formatDiagnosticText(
+    safeReadRecordField(value, "thoughts"),
+    MAX_RUNTIME_ACTION_MESSAGE_CHARS,
+    ""
+  );
+  const memory = formatDiagnosticText(
+    safeReadRecordField(value, "memory"),
+    MAX_RUNTIME_ACTION_MESSAGE_CHARS,
+    ""
+  );
+  const action = safeReadRecordField(value, "action");
+  return {
+    thoughts,
+    memory,
+    action: {
+      type: normalizeRuntimeActionType(safeReadRecordField(action, "type")),
+      params: safeReadRecordField(action, "params"),
+    },
+  };
+}
+
+function resolveCompleteActionFormatter(
+  actions: Array<AgentActionDefinition>
+):
+  | ((params: unknown) => Promise<string> | string)
+  | null {
+  for (const actionDefinition of actions) {
+    if (
+      normalizeRuntimeActionType(safeReadRecordField(actionDefinition, "type")) !==
+      "complete"
+    ) {
+      continue;
+    }
+    const completeAction = safeReadRecordField(actionDefinition, "completeAction");
+    if (typeof completeAction === "function") {
+      return completeAction as (params: unknown) => Promise<string> | string;
+    }
+    return null;
+  }
+  return null;
+}
+
+function getContextVariables(ctx: AgentCtx): ActionContext["variables"] {
+  const rawVariables = safeReadRecordField(ctx, "variables");
+  if (!rawVariables || typeof rawVariables !== "object") {
+    return [];
+  }
+  try {
+    return Object.values(
+      rawVariables as Record<string, ActionContext["variables"][number]>
+    );
+  } catch {
+    return [];
+  }
+}
+
+function safeJsonStringify(value: unknown, spacing: number = 2): string {
+  const seen = new WeakSet<object>();
+  try {
+    const serialized = JSON.stringify(
+      value,
+      (_key, candidate: unknown) => {
+        if (typeof candidate === "bigint") {
+          return `${candidate.toString()}n`;
+        }
+        if (typeof candidate === "object" && candidate !== null) {
+          if (seen.has(candidate)) {
+            return "[Circular]";
+          }
+          seen.add(candidate);
+        }
+        return candidate;
+      },
+      spacing
+    );
+    if (typeof serialized === "string") {
+      return serialized;
+    }
+  } catch {
+    // fall through to fallback payload
+  }
+
+  return JSON.stringify(
+    {
+      __nonSerializable: formatDiagnosticText(
+        value,
+        MAX_RUNTIME_ACTION_MESSAGE_CHARS,
+        "non-serializable value"
+      ),
+    },
+    null,
+    spacing
+  );
+}
 
 const writeFrameGraphSnapshot = async (
   page: Page,
@@ -52,17 +332,79 @@ const writeFrameGraphSnapshot = async (
   try {
     const cdpClient = await getCDPClient(page);
     const frameManager = getOrCreateFrameContextManager(cdpClient);
-    frameManager.setDebug(debug);
+    if (typeof frameManager.setDebug === "function") {
+      try {
+        frameManager.setDebug(debug);
+      } catch (error) {
+        if (debug) {
+          console.warn(
+            `[FrameContext] Failed to configure frame graph debug mode: ${formatDiagnosticText(
+              error,
+              MAX_RUNTIME_ACTION_MESSAGE_CHARS,
+              "unknown error"
+            )}`
+          );
+        }
+      }
+    }
     const data = frameManager.toJSON();
-    fs.writeFileSync(`${dir}/frames.json`, JSON.stringify(data, null, 2));
+    fs.writeFileSync(`${dir}/frames.json`, safeJsonStringify(data));
+  } catch (error) {
+    if (debug) {
+      console.warn(
+        `[FrameContext] Failed to write frame graph: ${formatDiagnosticText(
+          error,
+          MAX_RUNTIME_ACTION_MESSAGE_CHARS,
+          "unknown error"
+        )}`
+      );
+    }
+  }
+};
+
+const ensureDirectorySafe = (dir: string, debug?: boolean): boolean => {
+  try {
+    fs.mkdirSync(dir, { recursive: true });
+    return true;
   } catch (error) {
     if (debug) {
-      console.warn("[FrameContext] Failed to write frame graph:", error);
+      console.error(
+        `[DebugIO] Failed to create directory "${dir}": ${formatDiagnosticText(
+          error,
+          MAX_RUNTIME_ACTION_MESSAGE_CHARS,
+          "unknown error"
+        )}`
+      );
     }
+    return false;
   }
 };
 
-const compositeScreenshot = async (page: Page, overlay: string) => {
+const writeDebugFileSafe = (
+  filePath: string,
+  content: string | Buffer,
+  debug?: boolean
+): void => {
+  try {
+    fs.writeFileSync(filePath, content);
+  } catch (error) {
+    if (debug) {
+      console.error(
+        `[DebugIO] Failed to write file "${filePath}": ${formatDiagnosticText(
+          error,
+          MAX_RUNTIME_ACTION_MESSAGE_CHARS,
+          "unknown error"
+        )}`
+      );
+    }
+  }
+};
+
+const compositeScreenshot = async (
+  page: Page,
+  overlay: string,
+  debug?: boolean
+) => {
   // Use CDP screenshot - faster, doesn't wait for fonts
   const cdpClient = await getCDPClient(page);
   const client = await cdpClient.acquireSession("screenshot");
@@ -83,9 +425,11 @@ const compositeScreenshot = async (page: Page, overlay: string) => {
     overlayImage.bitmap.width !== baseImage.bitmap.width ||
     overlayImage.bitmap.height !== baseImage.bitmap.height
   ) {
-    console.log(
-      `[Screenshot] Dimension mismatch - overlay: ${overlayImage.bitmap.width}x${overlayImage.bitmap.height}, screenshot: ${baseImage.bitmap.width}x${baseImage.bitmap.height}, scaling overlay...`
-    );
+    if (debug) {
+      console.log(
+        `[Screenshot] Dimension mismatch - overlay: ${overlayImage.bitmap.width}x${overlayImage.bitmap.height}, screenshot: ${baseImage.bitmap.width}x${baseImage.bitmap.height}, scaling overlay...`
+      );
+    }
     overlayImage.resize({
       w: baseImage.bitmap.width,
       h: baseImage.bitmap.height,
@@ -98,12 +442,32 @@ const compositeScreenshot = async (page: Page, overlay: string) => {
 };
 
 const getActionSchema = (actions: Array<AgentActionDefinition>) => {
-  const zodDefs = actions.map((action) =>
-    z.object({
-      type: z.literal(action.type),
-      params: action.actionParams,
-    })
-  );
+  const zodDefs: z.ZodObject<{
+    type: z.ZodLiteral<string>;
+    params: z.ZodTypeAny;
+  }>[] = [];
+  for (const action of actions) {
+    const actionType = normalizeRuntimeActionType(
+      safeReadRecordField(action, "type")
+    );
+    const actionParams = safeReadRecordField(action, "actionParams");
+    if (actionType === "unknown") {
+      continue;
+    }
+    if (
+      !actionParams ||
+      typeof actionParams !== "object" ||
+      typeof safeReadRecordField(actionParams, "safeParse") !== "function"
+    ) {
+      continue;
+    }
+    zodDefs.push(
+      z.object({
+        type: z.literal(actionType),
+        params: actionParams as z.ZodTypeAny,
+      })
+    );
+  }
 
   if (zodDefs.length === 0) {
     throw new Error("No actions registered for agent");
@@ -128,12 +492,21 @@ const getActionHandler = (
   actions: Array<AgentActionDefinition>,
   type: string
 ) => {
-  const foundAction = actions.find((actions) => actions.type === type);
-  if (foundAction) {
-    return foundAction.run;
-  } else {
-    throw new ActionNotFoundError(type);
+  const normalizedType = normalizeRuntimeActionType(type);
+  for (const action of actions) {
+    const actionType = normalizeRuntimeActionType(
+      safeReadRecordField(action, "type")
+    );
+    if (actionType !== normalizedType) {
+      continue;
+    }
+    const run = safeReadRecordField(action, "run");
+    if (typeof run !== "function") {
+      throw new Error(`Action ${normalizedType} is missing a runnable handler.`);
+    }
+    return run as AgentActionDefinition["run"];
   }
+  throw new ActionNotFoundError(normalizedType);
 };
 
 const runAction = async (
@@ -143,6 +516,8 @@ const runAction = async (
   ctx: AgentCtx
 ): Promise<ActionOutput> => {
   const actionStart = performance.now();
+  const actionType = normalizeRuntimeActionType(safeReadRecordField(action, "type"));
+  const actionParams = safeReadRecordField(action, "params");
   const actionCtx: ActionContext = {
     domState,
     page,
@@ -151,46 +526,74 @@ const runAction = async (
     debugDir: ctx.debugDir,
     debug: ctx.debug,
     mcpClient: ctx.mcpClient || undefined,
-    variables: Object.values(ctx.variables),
+    variables: getContextVariables(ctx),
     cdpActions: ctx.cdpActions,
+    filterAdTrackingFrames: ctx.filterAdTrackingFrames,
     invalidateDomCache: () => markDomSnapshotDirty(page),
   };
 
-  if (ctx.cdpActions) {
-    const { cdpClient, frameContextManager } = await initializeRuntimeContext(
-      page,
-      ctx.debug
+  let actionHandler: AgentActionDefinition["run"];
+  try {
+    actionHandler = getActionHandler(ctx.actions, actionType);
+  } catch (error) {
+    logPerf(
+      ctx.debug,
+      `[Perf][runAction][${actionType}] (handler error)`,
+      actionStart
     );
-    actionCtx.cdp = {
-      resolveElement,
-      dispatchCDPAction,
-      client: cdpClient,
-      preferScriptBoundingBox: !!ctx.debugDir,
-      frameContextManager,
-      debug: ctx.debug,
-    };
-  }
-  const actionType = action.type;
-  const actionHandler = getActionHandler(ctx.actions, action.type);
-  if (!actionHandler) {
     return {
       success: false,
-      message: `Unknown action type: ${actionType}`,
+      message: `Action ${actionType} failed: ${normalizeRuntimeActionMessage(error)}`,
     };
   }
+
+  if (ctx.cdpActions) {
+    try {
+      const { cdpClient, frameContextManager } = await initializeRuntimeContext(
+        page,
+        ctx.debug,
+        {
+          filterAdTrackingFrames: ctx.filterAdTrackingFrames,
+        }
+      );
+      actionCtx.cdp = {
+        resolveElement,
+        dispatchCDPAction,
+        client: cdpClient,
+        preferScriptBoundingBox: !!ctx.debugDir,
+        frameContextManager,
+        debug: ctx.debug,
+      };
+    } catch (error) {
+      logPerf(
+        ctx.debug,
+        `[Perf][runAction][${actionType}] (cdp init error)`,
+        actionStart
+      );
+      return {
+        success: false,
+        message: `Action ${actionType} failed: ${normalizeRuntimeActionMessage(
+          error
+        )}`,
+      };
+    }
+  }
+
   try {
-    const result = await actionHandler(actionCtx, action.params);
-    logPerf(ctx.debug, `[Perf][runAction][${action.type}]`, actionStart);
-    return result;
+    const result = await actionHandler(actionCtx, actionParams);
+    logPerf(ctx.debug, `[Perf][runAction][${actionType}]`, actionStart);
+    return normalizeActionOutput(result, actionType);
   } catch (error) {
     logPerf(
       ctx.debug,
-      `[Perf][runAction][${action.type}] (error)`,
+      `[Perf][runAction][${actionType}] (error)`,
       actionStart
     );
     return {
       success: false,
-      message: `Action ${action.type} failed: ${error}`,
+      message: `Action ${actionType} failed: ${normalizeRuntimeActionMessage(
+        error
+      )}`,
     };
   }
 };
@@ -210,17 +613,20 @@ export const runAgentTask = async (
   taskState: TaskState,
   params?: TaskParams
 ): Promise<AgentTaskOutput> => {
+  if (!taskState || typeof taskState !== "object") {
+    throw new HyperagentError("Task state not found");
+  }
   const taskStart = performance.now();
   const taskId = taskState.id;
   const debugDir = params?.debugDir || `debug/${taskId}`;
+  let debugArtifactsEnabled = Boolean(ctx.debug);
 
   if (ctx.debug) {
     console.log(`Debugging task ${taskId} in ${debugDir}`);
   }
-  if (!taskState) {
-    throw new HyperagentError(`Task ${taskId} not found`);
+  if (debugArtifactsEnabled) {
+    debugArtifactsEnabled = ensureDirectorySafe(debugDir, ctx.debug);
   }
-
   taskState.status = TaskStatus.RUNNING as TaskStatus;
   if (!ctx.llm) {
     throw new HyperagentError("LLM not initialized");
@@ -250,43 +656,98 @@ export const runAgentTask = async (
   };
 
   const setupDomListeners = (p: Page) => {
-    p.on("framenavigated", navigationDirtyHandler);
-    p.on("framedetached", navigationDirtyHandler);
-    p.on("load", navigationDirtyHandler);
+    const on = safeReadRecordField(p, "on");
+    if (typeof on !== "function") {
+      return;
+    }
+    try {
+      on.call(p, "framenavigated", navigationDirtyHandler);
+      on.call(p, "framedetached", navigationDirtyHandler);
+      on.call(p, "load", navigationDirtyHandler);
+    } catch (error) {
+      if (ctx.debug) {
+        console.warn(
+          `[Agent] Failed to attach DOM listeners: ${normalizeRuntimeActionMessage(
+            error
+          )}`
+        );
+      }
+    }
   };
 
   const cleanupDomListeners = (p: Page) => {
-    p.off?.("framenavigated", navigationDirtyHandler);
-    p.off?.("framedetached", navigationDirtyHandler);
-    p.off?.("load", navigationDirtyHandler);
+    const off = safeReadRecordField(p, "off");
+    if (typeof off !== "function") {
+      return;
+    }
+    try {
+      off.call(p, "framenavigated", navigationDirtyHandler);
+      off.call(p, "framedetached", navigationDirtyHandler);
+      off.call(p, "load", navigationDirtyHandler);
+    } catch (error) {
+      if (ctx.debug) {
+        console.warn(
+          `[Agent] Failed to detach DOM listeners: ${normalizeRuntimeActionMessage(
+            error
+          )}`
+        );
+      }
+    }
   };
 
   setupDomListeners(page);
   let currStep = 0;
   let consecutiveFailuresOrWaits = 0;
   const MAX_CONSECUTIVE_FAILURES_OR_WAITS = 5;
+  let lastSuccessfulProgressFingerprint: string | null = null;
+  let consecutiveRepeatedSuccessfulActions = 0;
   let lastOverlayKey: string | null = null;
   let lastScreenshotBase64: string | undefined;
   const actionCacheSteps: ActionCacheOutput["steps"] = [];
 
   try {
     // Initialize context at the start of the task
-    await initializeRuntimeContext(page, ctx.debug);
+    let runtimeContextReady = true;
+    try {
+      await initializeRuntimeContext(page, ctx.debug, {
+        filterAdTrackingFrames: ctx.filterAdTrackingFrames,
+      });
+    } catch (error) {
+      runtimeContextReady = false;
+      const initError = `Failed to initialize runtime context: ${normalizeRuntimeActionMessage(
+        error
+      )}`;
+      taskState.status = TaskStatus.FAILED;
+      taskState.error = initError;
+      output = initError;
+    }
 
-    while (true) {
+    while (runtimeContextReady) {
       // Check for page context switch
       if (ctx.activePage) {
         const newPage = await ctx.activePage();
         if (newPage && newPage !== page) {
           if (ctx.debug) {
             console.log(
-              `[Agent] Switching active page context to ${newPage.url()}`
+              `[Agent] Switching active page context to ${safeGetPageUrl(newPage)}`
             );
           }
           cleanupDomListeners(page);
           page = newPage;
           setupDomListeners(page);
-          await initializeRuntimeContext(page, ctx.debug);
+          try {
+            await initializeRuntimeContext(page, ctx.debug, {
+              filterAdTrackingFrames: ctx.filterAdTrackingFrames,
+            });
+          } catch (error) {
+            const switchError = `Failed to initialize runtime context for switched page: ${normalizeRuntimeActionMessage(
+              error
+            )}`;
+            taskState.status = TaskStatus.FAILED;
+            taskState.error = switchError;
+            output = switchError;
+            break;
+          }
           markDomSnapshotDirty(page);
         }
       }
@@ -309,23 +770,24 @@ export const runAgentTask = async (
       const stepMetrics: Record<string, unknown> = {
         stepIndex: currStep,
       };
-      if (ctx.debug) {
-        fs.mkdirSync(debugStepDir, { recursive: true });
-      }
+      const stepDebugArtifactsEnabled =
+        debugArtifactsEnabled && ensureDirectorySafe(debugStepDir, ctx.debug);
 
       // Get A11y DOM State (visual mode optional, default false for performance)
       let domState: A11yDOMState | null = null;
-      const domChunks: string | null = null;
       try {
         const domFetchStart = performance.now();
 
-        await waitForSettledDOM(page);
+        await waitForSettledDOM(page, undefined, {
+          filterAdTrackingFrames: ctx.filterAdTrackingFrames,
+        });
         domState = await captureDOMState(page, {
           useCache: useDomCache,
           debug: ctx.debug,
           enableVisualMode: params?.enableVisualMode ?? false,
-          debugStepDir: ctx.debug ? debugStepDir : undefined,
+          debugStepDir: stepDebugArtifactsEnabled ? debugStepDir : undefined,
           enableStreaming: enableDomStreaming,
+          filterAdTrackingFrames: ctx.filterAdTrackingFrames,
           onFrameChunk: enableDomStreaming
             ? () => {
                 // captureDOMState handles aggregation
@@ -360,9 +822,29 @@ export const runAgentTask = async (
         if (overlayKey === lastOverlayKey && lastScreenshotBase64) {
           trimmedScreenshot = lastScreenshotBase64;
         } else {
-          trimmedScreenshot = await compositeScreenshot(page, overlayKey);
-          lastOverlayKey = overlayKey;
-          lastScreenshotBase64 = trimmedScreenshot;
+          try {
+            trimmedScreenshot = await compositeScreenshot(
+              page,
+              overlayKey,
+              ctx.debug
+            );
+            lastOverlayKey = overlayKey;
+            lastScreenshotBase64 = trimmedScreenshot;
+          } catch (error) {
+            if (ctx.debug) {
+              console.warn(
+                "[Screenshot] Failed to compose overlay screenshot; continuing without visual image:",
+                formatDiagnosticText(
+                  error,
+                  MAX_RUNTIME_ACTION_MESSAGE_CHARS,
+                  "unknown error"
+                )
+              );
+            }
+            trimmedScreenshot = undefined;
+            lastOverlayKey = null;
+            lastScreenshotBase64 = undefined;
+          }
         }
       } else {
         lastOverlayKey = null;
@@ -370,21 +852,17 @@ export const runAgentTask = async (
       }
 
       // Store Dom State for Debugging
-      if (ctx.debug) {
-        fs.mkdirSync(debugDir, { recursive: true });
-        fs.writeFileSync(`${debugStepDir}/elems.txt`, domState.domState);
+      if (stepDebugArtifactsEnabled) {
+        writeDebugFileSafe(`${debugStepDir}/elems.txt`, domState.domState, ctx.debug);
         if (trimmedScreenshot) {
-          fs.writeFileSync(
+          writeDebugFileSafe(
             `${debugStepDir}/screenshot.png`,
-            Buffer.from(trimmedScreenshot, "base64")
+            Buffer.from(trimmedScreenshot, "base64"),
+            ctx.debug
           );
         }
       }
 
-      if (domChunks) {
-        domState.domState = domChunks;
-      }
-
       // Build Agent Step Messages
       let msgs = await buildAgentStepMessages(
         baseMsgs,
@@ -393,15 +871,18 @@ export const runAgentTask = async (
         page,
         domState,
         trimmedScreenshot,
-        Object.values(ctx.variables)
+        getContextVariables(ctx)
       );
 
       // Append accumulated schema errors from previous steps
       if (ctx.schemaErrors && ctx.schemaErrors.length > 0) {
-        const errorSummary = ctx.schemaErrors
-          .slice(-3) // Only keep last 3 errors to avoid context bloat
-          .map((err) => `Step ${err.stepIndex}: ${err.error}`)
-          .join("\n");
+        const errorSummary = truncateDiagnosticText(
+          ctx.schemaErrors
+            .slice(-3) // Only keep last 3 errors to avoid context bloat
+            .map((err) => `Step ${err.stepIndex}: ${err.error}`)
+            .join("\n"),
+          MAX_SCHEMA_ERROR_SUMMARY_CHARS
+        );
 
         msgs = [
           ...msgs,
@@ -413,15 +894,16 @@ export const runAgentTask = async (
       }
 
       // Store Agent Step Messages for Debugging
-      if (ctx.debug) {
-        fs.writeFileSync(
+      if (stepDebugArtifactsEnabled) {
+        writeDebugFileSafe(
           `${debugStepDir}/msgs.json`,
-          JSON.stringify(msgs, null, 2)
+          safeJsonStringify(msgs),
+          ctx.debug
         );
       }
 
       // Invoke LLM with structured output
-      const agentOutput = await (async () => {
+      const rawAgentOutput = await (async () => {
         const maxAttempts = 3;
         let currentMsgs = msgs;
 
@@ -450,7 +932,20 @@ export const runAgentTask = async (
                 return result;
               })(),
             onError: (...args: Array<unknown>) => {
-              console.error("[LLM][StructuredOutput] Retry error", ...args);
+              const [attemptLabel, failure] = args;
+              const safeAttemptLabel = formatDiagnosticText(
+                attemptLabel,
+                MAX_STRUCTURED_DIAGNOSTIC_IDENTIFIER_CHARS,
+                "retry"
+              );
+              const safeFailure = formatDiagnosticText(
+                failure,
+                MAX_STRUCTURED_DIAGNOSTIC_ERROR_CHARS,
+                "unknown error"
+              );
+              console.error(
+                `[LLM][StructuredOutput] Retry error ${safeAttemptLabel}: ${safeFailure}`
+              );
             },
           });
 
@@ -458,36 +953,87 @@ export const runAgentTask = async (
             return structuredResult.parsed;
           }
 
-          const providerId = ctx.llm?.getProviderId?.() ?? "unknown-provider";
-          const modelId = ctx.llm?.getModelId?.() ?? "unknown-model";
+          const providerId = formatDiagnosticIdentifier(
+            ctx.llm?.getProviderId?.(),
+            "unknown-provider"
+          );
+          const modelId = formatDiagnosticIdentifier(
+            ctx.llm?.getModelId?.(),
+            "unknown-model"
+          );
 
           // Try to get detailed Zod validation error
           let validationError = "Unknown validation error";
           if (structuredResult.rawText) {
             try {
-              const parsed = JSON.parse(structuredResult.rawText);
+              if (
+                structuredResult.rawText.length >
+                MAX_STRUCTURED_DIAGNOSTIC_PARSE_CHARS
+              ) {
+                validationError = `Response exceeded ${MAX_STRUCTURED_DIAGNOSTIC_PARSE_CHARS} characters and was skipped for validation diagnostics`;
+                throw new Error(validationError);
+              }
+
+              const normalizedRawText = structuredResult.rawText.replace(
+                /^\uFEFF/,
+                ""
+              );
+              const parsed = JSON.parse(normalizedRawText);
               AgentOutputFn(actionSchema).parse(parsed);
             } catch (zodError) {
               if (zodError instanceof z.ZodError) {
                 validationError = JSON.stringify(zodError.issues, null, 2);
+              } else if (
+                zodError instanceof Error &&
+                zodError.message === validationError
+              ) {
+                validationError = zodError.message;
               } else {
-                validationError = String(zodError);
+                validationError = formatDiagnosticText(
+                  zodError,
+                  MAX_STRUCTURED_DIAGNOSTIC_ERROR_CHARS,
+                  "unknown error"
+                );
               }
             }
           }
 
+          const rawResponseForLog = truncateDiagnosticText(
+            structuredResult.rawText?.trim() || "<empty>",
+            MAX_STRUCTURED_DIAGNOSTIC_RAW_RESPONSE_CHARS
+          );
+          const validationErrorForPrompt = truncateDiagnosticText(
+            validationError,
+            MAX_STRUCTURED_DIAGNOSTIC_ERROR_CHARS
+          );
+          const rawResponseForPrompt = truncateDiagnosticText(
+            structuredResult.rawText || "Failed to generate response",
+            MAX_STRUCTURED_DIAGNOSTIC_RAW_RESPONSE_CHARS
+          );
+
           console.error(
             `[LLM][StructuredOutput] Failed to parse response from ${providerId} (${modelId}). Raw response: ${
-              structuredResult.rawText?.trim() || "<empty>"
+              rawResponseForLog
             } (attempt ${attempt + 1}/${maxAttempts})`
           );
 
           // Store error for cross-step learning
-          ctx.schemaErrors?.push({
-            stepIndex: currStep,
-            error: validationError,
-            rawResponse: structuredResult.rawText || "",
-          });
+          if (ctx.schemaErrors) {
+            ctx.schemaErrors.push({
+              stepIndex: currStep,
+              error: validationErrorForPrompt,
+              rawResponse: truncateDiagnosticText(
+                structuredResult.rawText || "",
+                MAX_STRUCTURED_DIAGNOSTIC_RAW_RESPONSE_CHARS
+              ),
+            });
+            if (ctx.schemaErrors.length > MAX_SCHEMA_ERROR_HISTORY) {
+              ctx.schemaErrors.splice(
+                0,
+                ctx.schemaErrors.length - MAX_SCHEMA_ERROR_HISTORY
+              );
+            }
+          }
 
           // Append error feedback for next retry
           if (attempt < maxAttempts - 1) {
@@ -495,18 +1041,18 @@ export const runAgentTask = async (
               ...currentMsgs,
               {
                 role: "assistant",
-                content:
-                  structuredResult.rawText || "Failed to generate response",
+                content: rawResponseForPrompt,
               },
               {
                 role: "user",
-                content: `The previous response failed validation. Zod validation errors:\n\`\`\`json\n${validationError}\n\`\`\`\n\nPlease fix these errors and return valid structured output matching the schema.`,
+                content: `The previous response failed validation. Zod validation errors:\n\`\`\`json\n${validationErrorForPrompt}\n\`\`\`\n\nPlease fix these errors and return valid structured output matching the schema.`,
               },
             ];
           }
         }
         throw new Error("Failed to get structured output from LLM");
       })();
+      const agentOutput = normalizeAgentOutput(rawAgentOutput);
 
       params?.debugOnAgentOutput?.(agentOutput);
 
@@ -521,22 +1067,15 @@ export const runAgentTask = async (
       }
 
       // Run single action
-      const action = agentOutput.action;
-
-      // Handle complete action specially
-      if (action.type === "complete") {
-        taskState.status = TaskStatus.COMPLETED;
-        const actionDefinition = ctx.actions.find(
-          (actionDefinition) => actionDefinition.type === "complete"
-        );
-        if (actionDefinition) {
-          output =
-            (await actionDefinition.completeAction?.(action.params)) ??
-            "No complete action found";
-        } else {
-          output = "No complete action found";
-        }
-      }
+      const actionPayload = safeReadRecordField(agentOutput, "action");
+      const actionType = normalizeRuntimeActionType(
+        safeReadRecordField(actionPayload, "type")
+      );
+      const actionParams = safeReadRecordField(actionPayload, "params");
+      const action: ActionType = {
+        type: actionType,
+        params: actionParams,
+      };
 
       // Execute the action
       const actionExecStart = performance.now();
@@ -548,7 +1087,7 @@ export const runAgentTask = async (
         actionExecStart
       );
       stepMetrics.actionMs = Math.round(actionDuration);
-      stepMetrics.actionType = action.type;
+      stepMetrics.actionType = actionType;
       stepMetrics.actionSuccess = actionOutput.success;
       if (
         actionOutput.debug &&
@@ -559,7 +1098,7 @@ export const runAgentTask = async (
       ) {
         stepMetrics.actionTimings = actionOutput.debug.timings;
       }
-      if (!READ_ONLY_ACTIONS.has(action.type)) {
+      if (!READ_ONLY_ACTIONS.has(actionType)) {
         markDomSnapshotDirty(page);
       }
 
@@ -571,14 +1110,107 @@ export const runAgentTask = async (
       });
       actionCacheSteps.push(actionCacheEntry);
 
+      if (actionType === "complete") {
+        if (actionOutput.success) {
+          const completeFormatter = resolveCompleteActionFormatter(ctx.actions);
+          const fallbackCompleteOutput = normalizeTaskOutputText(
+            actionOutput.message,
+            "Task Complete"
+          );
+          if (completeFormatter) {
+            try {
+              output = normalizeTaskOutputText(
+                await completeFormatter(actionParams),
+                fallbackCompleteOutput
+              );
+            } catch (error) {
+              if (ctx.debug) {
+                console.warn(
+                  `[Agent] completeAction formatter failed: ${normalizeRuntimeActionMessage(
+                    error
+                  )}`
+                );
+              }
+              output = fallbackCompleteOutput;
+            }
+          } else {
+            output = fallbackCompleteOutput;
+          }
+          taskState.status = TaskStatus.COMPLETED;
+        } else {
+          taskState.status = TaskStatus.FAILED;
+          taskState.error = normalizeTaskOutputText(
+            actionOutput.message,
+            "Task failed"
+          );
+          output = taskState.error;
+        }
+
+        const step: AgentStep = {
+          idx: currStep,
+          agentOutput,
+          actionOutput,
+        };
+        taskState.steps.push(step);
+        await params?.onStep?.(step);
+        currStep = currStep + 1;
+        break;
+      }
+
+      if (actionOutput.success && actionType !== "wait") {
+        const progressFingerprint = safeJsonStringify(
+          {
+            actionType,
+            params: actionParams,
+            url: safeGetPageUrl(page),
+            domSignature: buildDomProgressSignature(domState),
+          },
+          0
+        );
+        if (progressFingerprint === lastSuccessfulProgressFingerprint) {
+          consecutiveRepeatedSuccessfulActions++;
+        } else {
+          consecutiveRepeatedSuccessfulActions = 1;
+          lastSuccessfulProgressFingerprint = progressFingerprint;
+        }
+
+        if (
+          consecutiveRepeatedSuccessfulActions >=
+          MAX_REPEATED_ACTIONS_WITHOUT_PROGRESS
+        ) {
+          taskState.status = TaskStatus.FAILED;
+          taskState.error = normalizeTaskOutputText(
+            `Agent appears stuck: repeated the same successful action ${MAX_REPEATED_ACTIONS_WITHOUT_PROGRESS} times without visible progress.`,
+            "Agent appears stuck after repeated actions."
+          );
+          output = taskState.error;
+
+          const step: AgentStep = {
+            idx: currStep,
+            agentOutput,
+            actionOutput,
+          };
+          taskState.steps.push(step);
+          await params?.onStep?.(step);
+          break;
+        }
+      } else {
+        consecutiveRepeatedSuccessfulActions = 0;
+        lastSuccessfulProgressFingerprint = null;
+      }
+
       // Check action result and handle retry logic
-      if (action.type === "wait") {
+      if (actionType === "wait") {
         // Wait action - increment counter
         consecutiveFailuresOrWaits++;
 
         if (consecutiveFailuresOrWaits >= MAX_CONSECUTIVE_FAILURES_OR_WAITS) {
           taskState.status = TaskStatus.FAILED;
-          taskState.error = `Agent is stuck: waited or failed ${MAX_CONSECUTIVE_FAILURES_OR_WAITS} consecutive times without making progress.`;
+          taskState.error = normalizeTaskOutputText(
+            `Agent is stuck: waited or failed ${MAX_CONSECUTIVE_FAILURES_OR_WAITS} consecutive times without making progress.`,
+            "Agent is stuck after repeated waits."
+          );
+          output = taskState.error;
 
           const step: AgentStep = {
             idx: currStep,
@@ -601,7 +1233,11 @@ export const runAgentTask = async (
 
         if (consecutiveFailuresOrWaits >= MAX_CONSECUTIVE_FAILURES_OR_WAITS) {
           taskState.status = TaskStatus.FAILED;
-          taskState.error = `Agent is stuck: waited or failed ${MAX_CONSECUTIVE_FAILURES_OR_WAITS} consecutive times without making progress. Last error: ${actionOutput.message}`;
+          taskState.error = normalizeTaskOutputText(
+            `Agent is stuck: waited or failed ${MAX_CONSECUTIVE_FAILURES_OR_WAITS} consecutive times without making progress. Last error: ${actionOutput.message}`,
+            "Agent is stuck after repeated failures."
+          );
+          output = taskState.error;
 
           const step: AgentStep = {
             idx: currStep,
@@ -624,7 +1260,11 @@ export const runAgentTask = async (
       }
 
       // Wait for DOM to settle after action
-      const waitStats = await waitForSettledDOM(page);
+      const waitStats = normalizeWaitStats(
+        await waitForSettledDOM(page, undefined, {
+          filterAdTrackingFrames: ctx.filterAdTrackingFrames,
+        })
+      );
       stepMetrics.waitForSettledMs = Math.round(waitStats.durationMs);
       stepMetrics.waitForSettled = {
         totalMs: Math.round(waitStats.durationMs),
@@ -652,15 +1292,17 @@ export const runAgentTask = async (
       );
       stepMetrics.totalMs = Math.round(totalDuration);
 
-      if (ctx.debug) {
+      if (stepDebugArtifactsEnabled) {
         await writeFrameGraphSnapshot(page, debugStepDir, ctx.debug);
-        fs.writeFileSync(
+        writeDebugFileSafe(
           `${debugStepDir}/stepOutput.json`,
-          JSON.stringify(step, null, 2)
+          safeJsonStringify(step),
+          ctx.debug
         );
-        fs.writeFileSync(
+        writeDebugFileSafe(
           `${debugStepDir}/perf.json`,
-          JSON.stringify(stepMetrics, null, 2)
+          safeJsonStringify(stepMetrics),
+          ctx.debug
         );
       }
     }
@@ -676,11 +1318,12 @@ export const runAgentTask = async (
     status: taskState.status,
     steps: actionCacheSteps,
   };
-  if (ctx.debug) {
-    fs.mkdirSync(debugDir, { recursive: true });
-    fs.writeFileSync(
+  if (debugArtifactsEnabled) {
+    ensureDirectorySafe(debugDir, ctx.debug);
+    writeDebugFileSafe(
       `${debugDir}/action-cache.json`,
-      JSON.stringify(actionCache, null, 2)
+      safeJsonStringify(actionCache),
+      ctx.debug
     );
   }
 
@@ -691,10 +1334,11 @@ export const runAgentTask = async (
     output,
     actionCache,
   };
-  if (ctx.debug) {
-    fs.writeFileSync(
+  if (debugArtifactsEnabled) {
+    writeDebugFileSafe(
       `${debugDir}/taskOutput.json`,
-      JSON.stringify(taskOutput, null, 2)
+      safeJsonStringify(taskOutput),
+      ctx.debug
     );
   }
   await params?.onComplete?.(taskOutput);
diff --git a/src/agent/tools/types.ts b/src/agent/tools/types.ts
index bf2a2c45..bc8f7ba3 100644
--- a/src/agent/tools/types.ts
+++ b/src/agent/tools/types.ts
@@ -13,6 +13,7 @@ export interface AgentCtx {
   tokenLimit: number;
   llm: HyperAgentLLM;
   cdpActions?: boolean;
+  filterAdTrackingFrames?: boolean;
   schemaErrors?: Array<{
     stepIndex: number;
     error: string;
diff --git a/src/browser-providers/hyperbrowser.test.ts b/src/browser-providers/hyperbrowser.test.ts
new file mode 100644
index 00000000..13a842c7
--- /dev/null
+++ b/src/browser-providers/hyperbrowser.test.ts
@@ -0,0 +1,220 @@
+import { chromium } from "playwright-core";
+import { Hyperbrowser } from "@hyperbrowser/sdk";
+
+import { HyperbrowserProvider } from "@/browser-providers/hyperbrowser";
+
+jest.mock("playwright-core", () => ({
+  chromium: {
+    connectOverCDP: jest.fn(),
+  },
+}));
+
+jest.mock("@hyperbrowser/sdk", () => ({
+  Hyperbrowser: jest.fn(),
+}));
+
+describe("HyperbrowserProvider lifecycle hardening", () => {
+  const createSession = jest.fn();
+  const stopSession = jest.fn();
+  const connectOverCDP = jest.mocked(chromium.connectOverCDP);
+  const HyperbrowserCtor = Hyperbrowser as unknown as jest.Mock;
+
+  beforeEach(() => {
+    jest.clearAllMocks();
+    createSession.mockReset();
+    stopSession.mockReset();
+    HyperbrowserCtor.mockImplementation(() => ({
+      sessions: {
+        create: createSession,
+        stop: stopSession,
+      },
+    }));
+  });
+
+  it("stops created session when CDP connect fails during start", async () => {
+    createSession.mockResolvedValue({
+      id: "session-1",
+      wsEndpoint: "ws://example",
+      liveUrl: "https://live",
+      sessionUrl: "https://session",
+    });
+    stopSession.mockResolvedValue(undefined);
+    connectOverCDP.mockRejectedValue(new Error("cdp trap"));
+
+    const provider = new HyperbrowserProvider();
+
+    await expect(provider.start()).rejects.toThrow(
+      "Failed to connect to Hyperbrowser session: cdp trap"
+    );
+    expect(stopSession).toHaveBeenCalledWith("session-1");
+    expect(provider.getSession()).toBeNull();
+  });
+
+  it("reports cleanup diagnostics when start cleanup stop fails", async () => {
+    createSession.mockResolvedValue({
+      id: "session-1",
+      wsEndpoint: "ws://example",
+      liveUrl: "https://live",
+      sessionUrl: "https://session",
+    });
+    connectOverCDP.mockRejectedValue(new Error("cdp trap"));
+    stopSession.mockRejectedValue(new Error("stop trap"));
+
+    const provider = new HyperbrowserProvider();
+
+    await expect(provider.start()).rejects.toThrow(
+      "Failed to connect to Hyperbrowser session: cdp trap; Failed to stop Hyperbrowser session session-1: stop trap"
+    );
+  });
+
+  it("truncates oversized start diagnostics", async () => {
+    createSession.mockResolvedValue({
+      id: "session-1",
+      wsEndpoint: "ws://example",
+      liveUrl: "https://live",
+      sessionUrl: "https://session",
+    });
+    connectOverCDP.mockRejectedValue(new Error("x".repeat(2_000)));
+    stopSession.mockRejectedValue(new Error("x".repeat(2_000)));
+
+    const provider = new HyperbrowserProvider();
+
+    await expect(provider.start()).rejects.toThrow(/\[truncated/);
+  });
+
+  it("sanitizes control characters in start diagnostics", async () => {
+    createSession.mockResolvedValue({
+      id: "session-1",
+      wsEndpoint: "ws://example",
+      liveUrl: "https://live",
+      sessionUrl: "https://session",
+    });
+    connectOverCDP.mockRejectedValue(new Error(`cdp\u0000\n${"x".repeat(2_000)}`));
+    stopSession.mockRejectedValue(new Error(`stop\u0000\n${"x".repeat(2_000)}`));
+
+    const provider = new HyperbrowserProvider();
+
+    await provider
+      .start()
+      .then(() => {
+        throw new Error("expected start to reject");
+      })
+      .catch((error) => {
+        const message = String(error instanceof Error ? error.message : error);
+        expect(message).toContain("[truncated");
+        expect(message).not.toContain("\u0000");
+        expect(message).not.toContain("\n");
+      });
+  });
+
+  it("rejects missing websocket endpoints and cleans up session", async () => {
+    createSession.mockResolvedValue({
+      id: "session-1",
+      wsEndpoint: "   ",
+      liveUrl: "https://live",
+      sessionUrl: "https://session",
+    });
+    stopSession.mockResolvedValue(undefined);
+
+    const provider = new HyperbrowserProvider();
+
+    await expect(provider.start()).rejects.toThrow(
+      "Failed to connect to Hyperbrowser session: missing wsEndpoint"
+    );
+    expect(stopSession).toHaveBeenCalledWith("session-1");
+  });
+
+  it("close still stops session when browser close fails", async () => {
+    const provider = new HyperbrowserProvider();
+    provider.browser = {
+      close: async () => {
+        throw new Error("browser close trap");
+      },
+    } as never;
+    provider.session = {
+      id: "session-1",
+    } as never;
+    provider.hbClient = {
+      sessions: {
+        stop: stopSession,
+      },
+    } as never;
+    stopSession.mockResolvedValue(undefined);
+
+    await expect(provider.close()).rejects.toThrow(
+      "Failed to close browser connection: browser close trap"
+    );
+    expect(stopSession).toHaveBeenCalledWith("session-1");
+    expect(provider.getSession()).toBeNull();
+  });
+
+  it("close returns readable errors when session stop fails", async () => {
+    const provider = new HyperbrowserProvider();
+    provider.browser = {
+      close: async () => undefined,
+    } as never;
+    provider.session = {
+      id: "session-1",
+    } as never;
+    provider.hbClient = {
+      sessions: {
+        stop: stopSession,
+      },
+    } as never;
+    stopSession.mockRejectedValue(new Error("stop trap"));
+
+    await expect(provider.close()).rejects.toThrow(
+      "Failed to stop Hyperbrowser session session-1: stop trap"
+    );
+  });
+
+  it("truncates oversized close diagnostics", async () => {
+    const provider = new HyperbrowserProvider();
+    provider.browser = {
+      close: async () => {
+        throw new Error("x".repeat(2_000));
+      },
+    } as never;
+    provider.session = {
+      id: "session-1",
+    } as never;
+    provider.hbClient = {
+      sessions: {
+        stop: stopSession,
+      },
+    } as never;
+    stopSession.mockRejectedValue(new Error("x".repeat(2_000)));
+
+    await expect(provider.close()).rejects.toThrow(/\[truncated/);
+  });
+
+  it("sanitizes control characters in close diagnostics", async () => {
+    const provider = new HyperbrowserProvider();
+    provider.browser = {
+      close: async () => {
+        throw new Error(`browser\u0000\n${"x".repeat(2_000)}`);
+      },
+    } as never;
+    provider.session = {
+      id: "session-1",
+    } as never;
+    provider.hbClient = {
+      sessions: {
+        stop: stopSession,
+      },
+    } as never;
+    stopSession.mockRejectedValue(new Error(`stop\u0000\n${"x".repeat(2_000)}`));
+
+    await provider
+      .close()
+      .then(() => {
+        throw new Error("expected close to reject");
+      })
+      .catch((error) => {
+        const message = String(error instanceof Error ? error.message : error);
+        expect(message).toContain("[truncated");
+        expect(message).not.toContain("\u0000");
+        expect(message).not.toContain("\n");
+      });
+  });
+});
diff --git a/src/browser-providers/hyperbrowser.ts b/src/browser-providers/hyperbrowser.ts
index 59c26875..272acdc8 100644
--- a/src/browser-providers/hyperbrowser.ts
+++ b/src/browser-providers/hyperbrowser.ts
@@ -7,6 +7,28 @@ import {
 } from "@hyperbrowser/sdk/types";
 
 import BrowserProvider from "@/types/browser-providers/types";
+import { formatUnknownError } from "@/utils";
+
+const MAX_HYPERBROWSER_DIAGNOSTIC_CHARS = 400;
+
+const formatHyperbrowserDiagnostic = (value: unknown): string => {
+  const normalized = Array.from(formatUnknownError(value), (char) => {
+    const code = char.charCodeAt(0);
+    return (code >= 0 && code < 32) || code === 127 ? " " : char;
+  })
+    .join("")
+    .replace(/\s+/g, " ")
+    .trim();
+  const fallback = normalized.length > 0 ? normalized : "unknown error";
+  if (fallback.length <= MAX_HYPERBROWSER_DIAGNOSTIC_CHARS) {
+    return fallback;
+  }
+  const omitted = fallback.length - MAX_HYPERBROWSER_DIAGNOSTIC_CHARS;
+  return `${fallback.slice(
+    0,
+    MAX_HYPERBROWSER_DIAGNOSTIC_CHARS
+  )}... [truncated ${omitted} chars]`;
+};
 
 export class HyperbrowserProvider extends BrowserProvider<SessionDetail> {
   browserConfig: Omit<ConnectOverCDPOptions, "endpointURL"> | undefined;
@@ -30,15 +52,67 @@ export class HyperbrowserProvider extends BrowserProvider<SessionDetail> {
     this.config = params?.config;
   }
 
+  private async stopSessionSafely(
+    client: Hyperbrowser,
+    sessionId: string
+  ): Promise<string | null> {
+    try {
+      await client.sessions.stop(sessionId);
+      return null;
+    } catch (error) {
+      return `Failed to stop Hyperbrowser session ${sessionId}: ${formatHyperbrowserDiagnostic(
+        error
+      )}`;
+    }
+  }
+
   async start(): Promise<Browser> {
     const client = new Hyperbrowser(this.config);
-    const session = await client.sessions.create(this.sessionConfig);
+    let session: SessionDetail;
+    try {
+      session = await client.sessions.create(this.sessionConfig);
+    } catch (error) {
+      throw new Error(
+        `Failed to create Hyperbrowser session: ${formatHyperbrowserDiagnostic(
+          error
+        )}`
+      );
+    }
+
     this.hbClient = client;
     this.session = session;
-    this.browser = await chromium.connectOverCDP(
-      session.wsEndpoint,
-      this.browserConfig
-    );
+    const endpoint =
+      typeof session.wsEndpoint === "string" ? session.wsEndpoint.trim() : "";
+    if (endpoint.length === 0) {
+      const stopError = await this.stopSessionSafely(client, session.id);
+      this.session = undefined;
+      this.hbClient = undefined;
+      const diagnostics = [
+        "Failed to connect to Hyperbrowser session: missing wsEndpoint",
+      ];
+      if (stopError) {
+        diagnostics.push(stopError);
+      }
+      throw new Error(diagnostics.join("; "));
+    }
+
+    try {
+      this.browser = await chromium.connectOverCDP(endpoint, this.browserConfig);
+    } catch (error) {
+      const stopError = await this.stopSessionSafely(client, session.id);
+      this.browser = undefined;
+      this.session = undefined;
+      this.hbClient = undefined;
+      const diagnostics = [
+        `Failed to connect to Hyperbrowser session: ${formatHyperbrowserDiagnostic(
+          error
+        )}`,
+      ];
+      if (stopError) {
+        diagnostics.push(stopError);
+      }
+      throw new Error(diagnostics.join("; "));
+    }
 
     if (this.debug) {
       console.log(
@@ -56,9 +130,32 @@ export class HyperbrowserProvider extends BrowserProvider<SessionDetail> {
   }
 
   async close(): Promise<void> {
-    await this.browser?.close();
-    if (this.session) {
-      await this.hbClient?.sessions.stop(this.session.id);
+    const diagnostics: string[] = [];
+    if (this.browser) {
+      try {
+        await this.browser.close();
+      } catch (error) {
+        diagnostics.push(
+          `Failed to close browser connection: ${formatHyperbrowserDiagnostic(
+            error
+          )}`
+        );
+      }
+    }
+    if (this.session && this.hbClient) {
+      const stopError = await this.stopSessionSafely(
+        this.hbClient,
+        this.session.id
+      );
+      if (stopError) {
+        diagnostics.push(stopError);
+      }
+    }
+    this.browser = undefined;
+    this.session = undefined;
+    this.hbClient = undefined;
+    if (diagnostics.length > 0) {
+      throw new Error(diagnostics.join("; "));
     }
   }
 
diff --git a/src/browser-providers/local.test.ts b/src/browser-providers/local.test.ts
new file mode 100644
index 00000000..a93a1da7
--- /dev/null
+++ b/src/browser-providers/local.test.ts
@@ -0,0 +1,125 @@
+import { chromium } from "playwright-core";
+
+import { LocalBrowserProvider } from "@/browser-providers/local";
+
+jest.mock("playwright-core", () => ({
+  chromium: {
+    launch: jest.fn(),
+  },
+}));
+
+describe("LocalBrowserProvider lifecycle hardening", () => {
+  const launch = jest.mocked(chromium.launch);
+
+  beforeEach(() => {
+    jest.clearAllMocks();
+    launch.mockReset();
+  });
+
+  it("surfaces readable launch failures", async () => {
+    launch.mockRejectedValue(new Error("launch trap"));
+    const provider = new LocalBrowserProvider();
+
+    await expect(provider.start()).rejects.toThrow(
+      "Failed to launch local browser: launch trap"
+    );
+  });
+
+  it("truncates oversized launch diagnostics", async () => {
+    launch.mockRejectedValue(new Error("x".repeat(2_000)));
+    const provider = new LocalBrowserProvider();
+
+    await expect(provider.start()).rejects.toThrow(/\[truncated/);
+  });
+
+  it("sanitizes control characters in launch diagnostics", async () => {
+    launch.mockRejectedValue(new Error(`launch\u0000\n${"x".repeat(2_000)}`));
+    const provider = new LocalBrowserProvider();
+
+    await provider
+      .start()
+      .then(() => {
+        throw new Error("expected start to reject");
+      })
+      .catch((error) => {
+        const message = String(error instanceof Error ? error.message : error);
+        expect(message).toContain("[truncated");
+        expect(message).not.toContain("\u0000");
+        expect(message).not.toContain("\n");
+      });
+  });
+
+  it("rejects invalid launch payloads", async () => {
+    launch.mockResolvedValue("invalid-browser" as never);
+    const provider = new LocalBrowserProvider();
+
+    await expect(provider.start()).rejects.toThrow(
+      "Local browser launch returned an invalid browser"
+    );
+  });
+
+  it("clears session even when close fails", async () => {
+    const provider = new LocalBrowserProvider();
+    provider.session = {
+      close: async () => {
+        throw new Error("close trap");
+      },
+    } as never;
+
+    await expect(provider.close()).rejects.toThrow(
+      "Failed to close local browser session: close trap"
+    );
+    expect(provider.getSession()).toBeNull();
+  });
+
+  it("truncates oversized close diagnostics", async () => {
+    const provider = new LocalBrowserProvider();
+    provider.session = {
+      close: async () => {
+        throw new Error("x".repeat(2_000));
+      },
+    } as never;
+
+    await expect(provider.close()).rejects.toThrow(/\[truncated/);
+    expect(provider.getSession()).toBeNull();
+  });
+
+  it("sanitizes control characters in close diagnostics", async () => {
+    const provider = new LocalBrowserProvider();
+    provider.session = {
+      close: async () => {
+        throw new Error(`close\u0000\n${"x".repeat(2_000)}`);
+      },
+    } as never;
+
+    await provider
+      .close()
+      .then(() => {
+        throw new Error("expected close to reject");
+      })
+      .catch((error) => {
+        const message = String(error instanceof Error ? error.message : error);
+        expect(message).toContain("[truncated");
+        expect(message).not.toContain("\u0000");
+        expect(message).not.toContain("\n");
+      });
+    expect(provider.getSession()).toBeNull();
+  });
+
+  it("adds anti-automation launch args by default", async () => {
+    launch.mockResolvedValue({
+      close: async () => undefined,
+    } as never);
+    const provider = new LocalBrowserProvider({
+      args: ["--foo"],
+    });
+
+    await provider.start();
+
+    expect(launch).toHaveBeenCalledWith(
+      expect.objectContaining({
+        args: ["--disable-blink-features=AutomationControlled", "--foo"],
+      })
+    );
+  });
+});
diff --git a/src/browser-providers/local.ts b/src/browser-providers/local.ts
index 1bb63517..5680e402 100644
--- a/src/browser-providers/local.ts
+++ b/src/browser-providers/local.ts
@@ -1,26 +1,75 @@
 import { chromium, Browser, LaunchOptions } from "playwright-core";
 import BrowserProvider from "@/types/browser-providers/types";
+import { formatUnknownError } from "@/utils";
+
+export type LocalBrowserProviderOptions = Omit<LaunchOptions, "channel"> & {
+  channel?: string;
+};
 
 export class LocalBrowserProvider extends BrowserProvider<Browser> {
-  options: Omit<Omit<LaunchOptions, "headless">, "channel"> | undefined;
+  private static readonly MAX_DIAGNOSTIC_CHARS = 400;
+  options: LocalBrowserProviderOptions | undefined;
   session: Browser | undefined;
-  constructor(options?: Omit<Omit<LaunchOptions, "headless">, "channel">) {
+  constructor(options?: LocalBrowserProviderOptions) {
     super();
     this.options = options;
   }
+
+  private formatDiagnostic(value: unknown): string {
+    const normalized = Array.from(formatUnknownError(value), (char) => {
+      const code = char.charCodeAt(0);
+      return (code >= 0 && code < 32) || code === 127 ? " " : char;
+    })
+      .join("")
+      .replace(/\s+/g, " ")
+      .trim();
+    const fallback = normalized.length > 0 ? normalized : "unknown error";
+    if (fallback.length <= LocalBrowserProvider.MAX_DIAGNOSTIC_CHARS) {
+      return fallback;
+    }
+    const omitted = fallback.length - LocalBrowserProvider.MAX_DIAGNOSTIC_CHARS;
+    return `${fallback.slice(
+      0,
+      LocalBrowserProvider.MAX_DIAGNOSTIC_CHARS
+    )}... [truncated ${omitted} chars]`;
+  }
+
   async start(): Promise<Browser> {
     const launchArgs = this.options?.args ?? [];
-    const browser = await chromium.launch({
-      ...(this.options ?? {}),
-      channel: "chrome",
-      headless: false,
-      args: ["--disable-blink-features=AutomationControlled", ...launchArgs],
-    });
-    this.session = browser;
+    let browser: unknown;
+    try {
+      browser = await chromium.launch({
+        ...(this.options ?? {}),
+        channel: this.options?.channel ?? "chrome",
+        headless: this.options?.headless ?? false,
+        args: ["--disable-blink-features=AutomationControlled", ...launchArgs],
+      });
+    } catch (error) {
+      throw new Error(
+        `Failed to launch local browser: ${this.formatDiagnostic(error)}`
+      );
+    }
+
+    if (!browser || typeof browser !== "object") {
+      throw new Error("Local browser launch returned an invalid browser");
+    }
+
+    this.session = browser as Browser;
     return this.session;
   }
   async close(): Promise<void> {
-    return await this.session?.close();
+    const session = this.session;
+    this.session = undefined;
+    if (!session) {
+      return;
+    }
+    try {
+      await session.close();
+    } catch (error) {
+      throw new Error(
+        `Failed to close local browser session: ${this.formatDiagnostic(error)}`
+      );
+    }
   }
   public getSession() {
     if (!this.session) {
diff --git a/src/cdp/bounding-box.test.ts b/src/cdp/bounding-box.test.ts
new file mode 100644
index 00000000..35deaec7
--- /dev/null
+++ b/src/cdp/bounding-box.test.ts
@@ -0,0 +1,81 @@
+import { getBoundingBox } from "@/cdp/bounding-box";
+import type { CDPSession } from "@/cdp/types";
+
+describe("bounding-box error formatting", () => {
+  it("formats non-Error failures from domain enabling and quad lookup", async () => {
+    const warnSpy = jest.spyOn(console, "warn").mockImplementation(() => {});
+    const session: CDPSession = {
+      id: "test-session",
+      raw: undefined,
+      send: async <T = unknown>(method: string): Promise<T> => {
+        if (method === "DOM.enable") {
+          throw { reason: "dom enable object failure" };
+        }
+        if (method === "DOM.getContentQuads") {
+          throw { reason: "quads object failure" };
+        }
+        return {} as T;
+      },
+      on: jest.fn(),
+      off: jest.fn(),
+      detach: jest.fn(async () => undefined),
+    };
+
+    try {
+      const result = await getBoundingBox({
+        session,
+        backendNodeId: 123,
+      });
+
+      expect(result).toBeNull();
+      expect(warnSpy).toHaveBeenCalledWith(
+        '[CDP][BoundingBox] Failed to enable DOM domain: {"reason":"dom enable object failure"}'
+      );
+      expect(warnSpy).toHaveBeenCalledWith(
+        '[CDP][BoundingBox] Failed to get content quads: {"reason":"quads object failure"}'
+      );
+    } finally {
+      warnSpy.mockRestore();
+    }
+  });
+
+  it("sanitizes and truncates oversized diagnostics", async () => {
+    const warnSpy = jest.spyOn(console, "warn").mockImplementation(() => {});
+    const noisyFailure = `quads\u0000\n${"x".repeat(10_000)}`;
+    const session: CDPSession = {
+      id: "test-session",
+      raw: undefined,
+      send: async <T = unknown>(method: string): Promise<T> => {
+        if (method === "DOM.enable") {
+          return {} as T;
+        }
+        if (method === "DOM.getContentQuads") {
+          throw new Error(noisyFailure);
+        }
+        return {} as T;
+      },
+      on: jest.fn(),
+      off: jest.fn(),
+      detach: jest.fn(async () => undefined),
+    };
+
+    try {
+      const result = await getBoundingBox({
+        session,
+        backendNodeId: 456,
+      });
+
+      expect(result).toBeNull();
+      const quadsWarning = warnSpy.mock.calls
+        .map((call) => String(call[0]))
+        .find((line) => line.includes("Failed to get content quads"));
+      expect(quadsWarning).toBeDefined();
+      expect(quadsWarning).toContain("[truncated");
+      expect(quadsWarning).not.toContain("\u0000");
+      expect(quadsWarning).not.toContain("\n");
+      expect(quadsWarning?.length ?? 0).toBeLessThan(700);
+    } finally {
+      warnSpy.mockRestore();
+    }
+  });
+});
diff --git a/src/cdp/bounding-box.ts b/src/cdp/bounding-box.ts
index b1d7aa9b..a304ff39 100644
--- a/src/cdp/bounding-box.ts
+++ b/src/cdp/bounding-box.ts
@@ -1,8 +1,37 @@
 import type { CDPSession } from "@/cdp/types";
 import type { Protocol } from "devtools-protocol";
+import { formatUnknownError } from "@/utils";
 
 // Track which domains have been enabled per session
 const enabledDomains = new WeakMap<object, Set<string>>();
+const MAX_BOUNDING_BOX_DIAGNOSTIC_CHARS = 400;
+
+function sanitizeBoundingBoxDiagnostic(value: string): string {
+  if (value.length === 0) {
+    return value;
+  }
+  const withoutControlChars = Array.from(value, (char) => {
+    const code = char.charCodeAt(0);
+    return (code >= 0 && code < 32) || code === 127 ? " " : char;
+  }).join("");
+  return withoutControlChars.replace(/\s+/g, " ").trim();
+}
+
+function truncateBoundingBoxDiagnostic(value: string): string {
+  if (value.length <= MAX_BOUNDING_BOX_DIAGNOSTIC_CHARS) {
+    return value;
+  }
+  const omitted = value.length - MAX_BOUNDING_BOX_DIAGNOSTIC_CHARS;
+  return `${value.slice(0, MAX_BOUNDING_BOX_DIAGNOSTIC_CHARS)}... [truncated ${omitted} chars]`;
+}
+
+function formatBoundingBoxDiagnostic(value: unknown): string {
+  const normalized = sanitizeBoundingBoxDiagnostic(formatUnknownError(value));
+  if (normalized.length === 0) {
+    return "unknown error";
+  }
+  return truncateBoundingBoxDiagnostic(normalized);
+}
 
 async function ensureDomainEnabled(
   session: CDPSession,
@@ -19,7 +48,11 @@ async function ensureDomainEnabled(
     await session.send(`${domain}.enable`);
     enabled.add(domain);
   } catch (error) {
-    console.warn(`[CDP][BoundingBox] Failed to enable ${domain} domain:`, error);
+    console.warn(
+      `[CDP][BoundingBox] Failed to enable ${domain} domain: ${formatBoundingBoxDiagnostic(
+        error
+      )}`
+    );
   }
 }
 
@@ -130,7 +163,11 @@ async function getBoundingBoxFromQuads(
       bottom,
     };
   } catch (error) {
-    console.warn("[CDP][BoundingBox] Failed to get content quads:", error);
+    console.warn(
+      `[CDP][BoundingBox] Failed to get content quads: ${formatBoundingBoxDiagnostic(
+        error
+      )}`
+    );
     return null;
   }
 }
diff --git a/src/cdp/element-resolver.test.ts b/src/cdp/element-resolver.test.ts
new file mode 100644
index 00000000..d5d09415
--- /dev/null
+++ b/src/cdp/element-resolver.test.ts
@@ -0,0 +1,112 @@
+import type { CDPClient, CDPSession } from "@/cdp/types";
+import { resolveElement } from "@/cdp/element-resolver";
+import type { EncodedId, IframeInfo } from "@/context-providers/a11y-dom/types";
+
+function createSession(
+  sendImplementation: <T = unknown>(
+    method: string,
+    params?: Record<string, unknown>
+  ) => Promise<T>
+): CDPSession {
+  return {
+    id: "session-1",
+    raw: undefined,
+    send: sendImplementation,
+    on: jest.fn(),
+    off: jest.fn(),
+    detach: jest.fn(async () => undefined),
+  };
+}
+
+describe("resolveElement diagnostics", () => {
+  it("sanitizes and truncates frame identifiers in missing execution-context warnings", async () => {
+    const warnSpy = jest.spyOn(console, "warn").mockImplementation(() => {});
+    const encodedId = "1-500" as EncodedId;
+    const noisyFrameId = `frame\u0000\n${"x".repeat(500)}`;
+    const frameInfo = {
+      frameId: noisyFrameId,
+    } as unknown as IframeInfo;
+    const session = createSession(
+      async <T = unknown>(method: string): Promise<T> => {
+      if (method === "Runtime.evaluate") {
+        return { result: { objectId: "runtime-obj" } } as T;
+      }
+      if (method === "DOM.describeNode") {
+        return { node: { backendNodeId: 500 } } as T;
+      }
+      if (method === "DOM.resolveNode") {
+        return { object: { objectId: "resolved-obj" } } as T;
+      }
+        return {} as T;
+      }
+    );
+
+    const frameManager = {
+      getFrameIdByIndex: () => noisyFrameId,
+      getFrameSession: () => session,
+      getExecutionContextId: () => undefined,
+      waitForExecutionContext: async () => {
+        throw new Error("context wait failed");
+      },
+    };
+
+    try {
+      const result = await resolveElement(encodedId, {
+        page: {} as never,
+        cdpClient: {} as CDPClient,
+        backendNodeMap: {},
+        xpathMap: {
+          [encodedId]: "//button",
+        },
+        frameMap: new Map([[1, frameInfo]]),
+        frameContextManager: frameManager as never,
+      });
+
+      expect(result.backendNodeId).toBe(500);
+      const warning = String(warnSpy.mock.calls[0]?.[0] ?? "");
+      expect(warning).toContain("[truncated");
+      expect(warning).not.toContain("\u0000");
+      expect(warning).not.toContain("\n");
+      expect(warning.length).toBeLessThan(900);
+    } finally {
+      warnSpy.mockRestore();
+    }
+  });
+
+  it("sanitizes and truncates encoded identifiers in XPath-missing errors", async () => {
+    const encodedId = `0-\u0000\n${"y".repeat(500)}` as EncodedId;
+    const session = createSession(
+      async <T = unknown>(method: string): Promise<T> => {
+      if (method === "DOM.resolveNode") {
+        return { object: { objectId: "resolved-obj" } } as T;
+      }
+      return {} as T;
+      }
+    );
+    const frameManager = {
+      getFrameIdByIndex: () => "root",
+      getFrameSession: () => session,
+      getExecutionContextId: () => undefined,
+      waitForExecutionContext: async () => undefined,
+    };
+
+    await resolveElement(encodedId, {
+      page: {} as never,
+      cdpClient: {} as CDPClient,
+      backendNodeMap: {},
+      xpathMap: {},
+      frameContextManager: frameManager as never,
+    })
+      .then(() => {
+        throw new Error("expected resolveElement to reject");
+      })
+      .catch((error) => {
+      const message = String(error instanceof Error ? error.message : error);
+      expect(message).toContain("XPath not found for encodedId");
+      expect(message).toContain("[truncated");
+      expect(message).not.toContain("\u0000");
+      expect(message).not.toContain("\n");
+      expect(message.length).toBeLessThan(500);
+      });
+  });
+});
diff --git a/src/cdp/element-resolver.ts b/src/cdp/element-resolver.ts
index ea411da7..0313513e 100644
--- a/src/cdp/element-resolver.ts
+++ b/src/cdp/element-resolver.ts
@@ -31,6 +31,43 @@ export interface ResolvedCDPElement {
 const sessionCache = new WeakMap<CDPClient, Map<number, CDPSession>>();
 const domEnabledSessions = new WeakSet<CDPSession>();
 const runtimeEnabledSessions = new WeakSet<CDPSession>();
+const MAX_ELEMENT_RESOLVER_IDENTIFIER_CHARS = 128;
+
+function sanitizeElementResolverText(value: string): string {
+  if (value.length === 0) {
+    return value;
+  }
+  const withoutControlChars = Array.from(value, (char) => {
+    const code = char.charCodeAt(0);
+    return (code >= 0 && code < 32) || code === 127 ? " " : char;
+  }).join("");
+  return withoutControlChars.replace(/\s+/g, " ").trim();
+}
+
+function truncateElementResolverText(value: string, maxChars: number): string {
+  if (value.length <= maxChars) {
+    return value;
+  }
+  const omittedChars = value.length - maxChars;
+  return `${value.slice(0, maxChars)}... [truncated ${omittedChars} chars]`;
+}
+
+function formatElementResolverIdentifier(
+  value: unknown,
+  fallback: string = "unknown"
+): string {
+  if (typeof value !== "string") {
+    return fallback;
+  }
+  const normalized = sanitizeElementResolverText(value);
+  if (normalized.length === 0) {
+    return fallback;
+  }
+  return truncateElementResolverText(
+    normalized,
+    MAX_ELEMENT_RESOLVER_IDENTIFIER_CHARS
+  );
+}
 
 export async function resolveElement(
   encodedId: EncodedId,
@@ -43,7 +80,9 @@ export async function resolveElement(
 
   if (frameIndex !== 0 && !frameInfo) {
     throw new Error(
-      `Frame metadata not found for frameIndex ${frameIndex} (encodedId ${encodedId})`
+      `Frame metadata not found for frameIndex ${frameIndex} (encodedId ${formatElementResolverIdentifier(
+        encodedId
+      )})`
     );
   }
 
@@ -157,28 +196,13 @@ async function resolveFrameSession(
     return { session: managedSession, frameId };
   }
   throw new Error(
-    `[CDP][ElementResolver] Session not registered for frameIndex=${frameIndex} (frameId=${frameId})`
+    `[CDP][ElementResolver] Session not registered for frameIndex=${frameIndex} (frameId=${formatElementResolverIdentifier(
+      frameId,
+      "unknown-frame"
+    )})`
   );
 }
 
-async function ensureRootSession(
-  ctx: ElementResolveContext
-): Promise<CDPSession> {
-  try {
-    const session = ctx.cdpClient.rootSession;
-    const cache = getSessionCache(ctx.cdpClient);
-    if (!cache.has(0)) {
-      cache.set(0, session);
-    }
-    return session;
-  } catch {
-    const session = await ctx.cdpClient.acquireSession("dom");
-    const cache = getSessionCache(ctx.cdpClient);
-    cache.set(0, session);
-    return session;
-  }
-}
-
 function getSessionCache(client: CDPClient): Map<number, CDPSession> {
   let cache = sessionCache.get(client);
   if (!cache) {
@@ -237,7 +261,11 @@ async function recoverBackendNodeId(
 ): Promise<number> {
   const xpath = ctx.xpathMap[encodedId];
   if (!xpath) {
-    throw new Error(`XPath not found for encodedId ${encodedId}`);
+    throw new Error(
+      `XPath not found for encodedId ${formatElementResolverIdentifier(
+        encodedId
+      )}`
+    );
   }
 
   let executionContextId =
@@ -264,7 +292,10 @@ async function recoverBackendNodeId(
       );
     }
     console.warn(
-      `[CDP][ElementResolver] executionContextId missing for frame ${frameIndex} (${frameId}). ` +
+      `[CDP][ElementResolver] executionContextId missing for frame ${frameIndex} (${formatElementResolverIdentifier(
+        frameId,
+        "unknown-frame"
+      )}). ` +
         `XPath evaluation may fail or evaluate in wrong context. ` +
         `This can happen if execution context collection timed out. ` +
         `Consider increasing DEFAULT_CONTEXT_COLLECTION_TIMEOUT_MS in a11y-dom/index.ts`
@@ -286,7 +317,9 @@ async function recoverBackendNodeId(
   const objectId = evalResponse.result.objectId;
   if (!objectId) {
     throw new Error(
-      `Failed to recover node for ${encodedId} (frame ${frameIndex}) via XPath`
+      `Failed to recover node for ${formatElementResolverIdentifier(
+        encodedId
+      )} (frame ${frameIndex}) via XPath`
     );
   }
 
@@ -299,7 +332,9 @@ async function recoverBackendNodeId(
     const backendNodeId = description.node?.backendNodeId;
     if (typeof backendNodeId !== "number") {
       throw new Error(
-        `DOM.describeNode did not return backendNodeId for ${encodedId} (frame ${frameIndex})`
+        `DOM.describeNode did not return backendNodeId for ${formatElementResolverIdentifier(
+          encodedId
+        )} (frame ${frameIndex})`
       );
     }
 
diff --git a/src/cdp/frame-context-manager.test.ts b/src/cdp/frame-context-manager.test.ts
new file mode 100644
index 00000000..ab0551bf
--- /dev/null
+++ b/src/cdp/frame-context-manager.test.ts
@@ -0,0 +1,623 @@
+import { FrameContextManager } from "@/cdp/frame-context-manager";
+import type { CDPClient, CDPSession } from "@/cdp/types";
+
+class FakeSession implements CDPSession {
+  public id = "session-1";
+  public raw = undefined;
+  public offEvents: string[] = [];
+  public onEvents: string[] = [];
+  private handlers = new Map<string, Set<(...payload: unknown[]) => void>>();
+
+  async send<T = unknown>(method: string): Promise<T> {
+    if (method === "Page.getFrameTree") {
+      return {
+        frameTree: {
+          frame: {
+            id: "root-frame",
+            parentId: undefined,
+            loaderId: "loader-1",
+            name: "root",
+            url: "https://example.com",
+          },
+          childFrames: [],
+        },
+      } as T;
+    }
+    if (
+      method === "Page.enable" ||
+      method === "Runtime.enable" ||
+      method === "DOM.getFrameOwner"
+    ) {
+      return {} as T;
+    }
+    return {} as T;
+  }
+
+  on<TPayload extends unknown[]>(
+    event: string,
+    handler: (...payload: TPayload) => void
+  ): void {
+    this.onEvents.push(event);
+    const eventHandlers = this.handlers.get(event) ?? new Set();
+    eventHandlers.add(handler as (...payload: unknown[]) => void);
+    this.handlers.set(event, eventHandlers);
+  }
+
+  off<TPayload extends unknown[]>(
+    event: string,
+    handler: (...payload: TPayload) => void
+  ): void {
+    this.offEvents.push(event);
+    const eventHandlers = this.handlers.get(event);
+    eventHandlers?.delete(handler as (...payload: unknown[]) => void);
+  }
+
+  emit(event: string, ...payload: unknown[]): void {
+    const eventHandlers = this.handlers.get(event);
+    if (!eventHandlers) {
+      return;
+    }
+    for (const handler of eventHandlers) {
+      handler(...payload);
+    }
+  }
+
+  async detach(): Promise<void> {
+    return;
+  }
+}
+
+class FailingEnableSession extends FakeSession {
+  async send<T = unknown>(method: string): Promise<T> {
+    if (method === "Page.enable") {
+      throw { reason: "page enable object failure" };
+    }
+    if (method === "Runtime.enable") {
+      throw { reason: "runtime enable object failure" };
+    }
+    return super.send<T>(method);
+  }
+}
+
+class OversizedFailingEnableSession extends FakeSession {
+  async send<T = unknown>(method: string): Promise<T> {
+    if (method === "Page.enable") {
+      throw new Error(`page\u0000\n${"x".repeat(10_000)}`);
+    }
+    if (method === "Runtime.enable") {
+      throw new Error(`runtime\u0000\n${"y".repeat(10_000)}`);
+    }
+    return super.send<T>(method);
+  }
+}
+
+class NoisyFrameTreeSession extends FakeSession {
+  async send<T = unknown>(method: string): Promise<T> {
+    if (method === "Page.getFrameTree") {
+      return {
+        frameTree: {
+          frame: {
+            id: "root-frame",
+            parentId: undefined,
+            loaderId: "loader-1",
+            name: `root\u0000\nframe-${"n".repeat(400)}`,
+            url: `https://example.com/\u0000root\nframe-${"u".repeat(2_000)}`,
+          },
+          childFrames: [],
+        },
+      } as T;
+    }
+    return super.send(method);
+  }
+}
+
+function createFakeClient(session: CDPSession): CDPClient {
+  return {
+    rootSession: session,
+    createSession: async () => session,
+    acquireSession: async () => session,
+    dispose: async () => undefined,
+  };
+}
+
+function createFakeClientWithPage(
+  session: CDPSession,
+  page: unknown
+): CDPClient {
+  return {
+    ...createFakeClient(session),
+    getPage: () => page,
+  };
+}
+
+describe("FrameContextManager listener bookkeeping", () => {
+  it("cleans up both page and runtime listeners on clear", async () => {
+    const session = new FakeSession();
+    const manager = new FrameContextManager(createFakeClient(session));
+
+    await manager.ensureInitialized();
+    manager.clear();
+
+    expect(session.offEvents).toEqual(
+      expect.arrayContaining([
+        "Page.frameAttached",
+        "Page.frameDetached",
+        "Page.frameNavigated",
+        "Runtime.executionContextCreated",
+        "Runtime.executionContextDestroyed",
+        "Runtime.executionContextsCleared",
+      ])
+    );
+  });
+
+  it("formats non-Error enable failures as readable messages", async () => {
+    const warnSpy = jest.spyOn(console, "warn").mockImplementation(() => {});
+    try {
+      const session = new FailingEnableSession();
+      const manager = new FrameContextManager(createFakeClient(session));
+
+      await manager.ensureInitialized();
+      await Promise.resolve();
+
+      expect(warnSpy).toHaveBeenCalledWith(
+        '[FrameContext] Failed to enable Page domain: {"reason":"page enable object failure"}'
+      );
+      expect(warnSpy).toHaveBeenCalledWith(
+        '[FrameContextManager] Failed to enable Runtime domain: {"reason":"runtime enable object failure"}'
+      );
+    } finally {
+      warnSpy.mockRestore();
+    }
+  });
+
+  it("sanitizes and truncates oversized enable diagnostics", async () => {
+    const warnSpy = jest.spyOn(console, "warn").mockImplementation(() => {});
+    try {
+      const session = new OversizedFailingEnableSession();
+      const manager = new FrameContextManager(createFakeClient(session));
+
+      await manager.ensureInitialized();
+      await Promise.resolve();
+
+      const pageEnableWarning = warnSpy.mock.calls
+        .map((call) => String(call[0]))
+        .find((line) => line.includes("Failed to enable Page domain"));
+      const runtimeEnableWarning = warnSpy.mock.calls
+        .map((call) => String(call[0]))
+        .find((line) => line.includes("Failed to enable Runtime domain"));
+
+      expect(pageEnableWarning).toBeDefined();
+      expect(runtimeEnableWarning).toBeDefined();
+      expect(pageEnableWarning).toContain("[truncated");
+      expect(runtimeEnableWarning).toContain("[truncated");
+      expect(pageEnableWarning).not.toContain("\u0000");
+      expect(runtimeEnableWarning).not.toContain("\u0000");
+      expect(pageEnableWarning).not.toContain("\n");
+      expect(runtimeEnableWarning).not.toContain("\n");
+      expect(pageEnableWarning?.length ?? 0).toBeLessThan(700);
+      expect(runtimeEnableWarning?.length ?? 0).toBeLessThan(700);
+    } finally {
+      warnSpy.mockRestore();
+    }
+  });
+
+  it("continues initialization when session.on getter traps", async () => {
+    const warnSpy = jest.spyOn(console, "warn").mockImplementation(() => {});
+    const baseSession = new FakeSession();
+    const trappedSession = new Proxy(baseSession, {
+      get: (target, property, receiver) => {
+        if (property === "on") {
+          throw new Error(`listener-on\u0000\n${"x".repeat(2_000)}`);
+        }
+        const value = Reflect.get(target, property, receiver);
+        if (typeof value === "function") {
+          return value.bind(target);
+        }
+        return value;
+      },
+    }) as unknown as CDPSession;
+    const manager = new FrameContextManager(createFakeClient(trappedSession));
+
+    try {
+      await expect(manager.ensureInitialized()).resolves.toBeUndefined();
+      expect(() => manager.clear()).not.toThrow();
+      const warning = String(
+        warnSpy.mock.calls.find((call) =>
+          String(call[0] ?? "").includes("Failed to read session.on")
+        )?.[0] ?? ""
+      );
+      expect(warning).toContain("[truncated");
+      expect(warning).not.toContain("\u0000");
+      expect(warning).not.toContain("\n");
+      expect(
+        warnSpy.mock.calls.some((call) =>
+          String(call[0] ?? "").includes("Failed to read session.off")
+        )
+      ).toBe(false);
+    } finally {
+      warnSpy.mockRestore();
+    }
+  });
+
+  it("continues clear() when session.off getter traps", async () => {
+    const warnSpy = jest.spyOn(console, "warn").mockImplementation(() => {});
+    const baseSession = new FakeSession();
+    const trappedSession = new Proxy(baseSession, {
+      get: (target, property, receiver) => {
+        if (property === "off") {
+          throw new Error(`listener-off\u0000\n${"x".repeat(2_000)}`);
+        }
+        const value = Reflect.get(target, property, receiver);
+        if (typeof value === "function") {
+          return value.bind(target);
+        }
+        return value;
+      },
+    }) as unknown as CDPSession;
+    const manager = new FrameContextManager(createFakeClient(trappedSession));
+
+    try {
+      await manager.ensureInitialized();
+      expect(() => manager.clear()).not.toThrow();
+      const warning = String(
+        warnSpy.mock.calls.find((call) =>
+          String(call[0] ?? "").includes("Failed to read session.off")
+        )?.[0] ?? ""
+      );
+      expect(warning).toContain("[truncated");
+      expect(warning).not.toContain("\u0000");
+      expect(warning).not.toContain("\n");
+    } finally {
+      warnSpy.mockRestore();
+    }
+  });
+
+  it("cleans cached Playwright OOPIF detach handlers on clear", () => {
+    const session = new FakeSession();
+    const manager = new FrameContextManager(createFakeClient(session));
+    const fakeFrame = {
+      url: () => "https://example.com/iframe",
+      parentFrame: () => null,
+      name: () => "iframe",
+      isDetached: () => false,
+    };
+    const detachHandler = jest.fn();
+
+    (
+      manager as unknown as {
+        playwrightOopifCache: Map<unknown, unknown>;
+      }
+    ).playwrightOopifCache.set(fakeFrame, {
+      frameId: "oopif-1",
+      session,
+      url: "https://example.com/iframe",
+      playwrightFrame: fakeFrame,
+      detachHandler,
+    });
+
+    manager.clear();
+
+    expect(session.offEvents).toContain("Detached");
+    expect(
+      (
+        manager as unknown as {
+          playwrightOopifCache: Map<unknown, unknown>;
+        }
+      ).playwrightOopifCache.size
+    ).toBe(0);
+  });
+
+  it("can reinitialize listeners after clear", async () => {
+    const session = new FakeSession();
+    const manager = new FrameContextManager(createFakeClient(session));
+
+    await manager.ensureInitialized();
+    const firstAttachedRegistrations = session.onEvents.filter(
+      (event) => event === "Page.frameAttached"
+    ).length;
+    expect(firstAttachedRegistrations).toBe(1);
+
+    manager.clear();
+    await manager.ensureInitialized();
+
+    const secondAttachedRegistrations = session.onEvents.filter(
+      (event) => event === "Page.frameAttached"
+    ).length;
+    expect(secondAttachedRegistrations).toBe(2);
+  });
+
+  it("sanitizes control characters in captured frame tree metadata", async () => {
+    const session = new NoisyFrameTreeSession();
+    const manager = new FrameContextManager(createFakeClient(session));
+
+    await manager.ensureInitialized();
+
+    const rootFrame = manager.getFrame("root-frame");
+    expect(rootFrame?.url).toContain("https://example.com/ root frame-");
+    expect(rootFrame?.url).toContain("[truncated");
+    expect(rootFrame?.url).not.toContain("\u0000");
+    expect(rootFrame?.url).not.toContain("\n");
+    expect((rootFrame?.name ?? "").startsWith("root frame-")).toBe(true);
+    expect((rootFrame?.name ?? "").length).toBeLessThanOrEqual(200);
+  });
+
+  it("sanitizes control characters in frameNavigated metadata updates", async () => {
+    const session = new FakeSession();
+    const manager = new FrameContextManager(createFakeClient(session));
+
+    await manager.ensureInitialized();
+
+    session.emit("Page.frameNavigated", {
+      frame: {
+        id: "root-frame",
+        parentId: undefined,
+        loaderId: "loader-2",
+        name: "updated\u0000\nname",
+        url: "https://example.com/\u0000updated\nframe",
+      },
+    });
+
+    const rootFrame = manager.getFrame("root-frame");
+    expect(rootFrame?.url).toBe("https://example.com/ updated frame");
+    expect(rootFrame?.name).toBe("updated name");
+  });
+
+  it("captureOOPIFs tolerates trap-prone frame metadata on same-origin frames", async () => {
+    const session = new FakeSession();
+    const mainFrame = {
+      url: () => "https://example.com",
+      parentFrame: () => null,
+      name: () => "main",
+      isDetached: () => false,
+    };
+    const trappedFrame = {
+      url: () => {
+        throw new Error("frame url trap");
+      },
+      parentFrame: () => {
+        throw new Error("parent frame trap");
+      },
+      name: () => {
+        throw new Error("frame name trap");
+      },
+      isDetached: () => false,
+    };
+    const page = {
+      context: () => ({
+        newCDPSession: jest.fn().mockRejectedValue(new Error("same origin frame")),
+      }),
+      frames: () => [mainFrame, trappedFrame],
+      mainFrame: () => mainFrame,
+    };
+
+    const manager = new FrameContextManager(
+      createFakeClientWithPage(session, page)
+    );
+
+    await expect(manager.captureOOPIFs(1)).resolves.toBeUndefined();
+  });
+
+  it("captureOOPIFs logs sanitized diagnostics when page context getter traps", async () => {
+    const logSpy = jest.spyOn(console, "log").mockImplementation(() => {});
+    const session = new FakeSession();
+    const page = {
+      get context() {
+        throw new Error(`context\u0000\n${"x".repeat(2_000)}`);
+      },
+    };
+    const manager = new FrameContextManager(
+      createFakeClientWithPage(session, page)
+    );
+    manager.setDebug(true);
+
+    try {
+      await expect(manager.captureOOPIFs(1)).resolves.toBeUndefined();
+      const diagnostic = String(
+        logSpy.mock.calls.find((call) =>
+          String(call[0] ?? "").includes("Failed to read page context")
+        )?.[0] ?? ""
+      );
+      expect(diagnostic).toContain("[truncated");
+      expect(diagnostic).not.toContain("\u0000");
+      expect(diagnostic).not.toContain("\n");
+    } finally {
+      logSpy.mockRestore();
+    }
+  });
+
+  it("captureOOPIFs logs sanitized diagnostics when newCDPSession getter traps", async () => {
+    const logSpy = jest.spyOn(console, "log").mockImplementation(() => {});
+    const session = new FakeSession();
+    const mainFrame = {
+      url: () => "https://example.com",
+      parentFrame: () => null,
+      name: () => "main",
+      isDetached: () => false,
+    };
+    const context = {};
+    Object.defineProperty(context, "newCDPSession", {
+      get: () => {
+        throw new Error(`new-session\u0000\n${"x".repeat(2_000)}`);
+      },
+      configurable: true,
+    });
+    const page = {
+      context: () => context,
+      frames: () => [mainFrame],
+      mainFrame: () => mainFrame,
+    };
+    const manager = new FrameContextManager(
+      createFakeClientWithPage(session, page)
+    );
+    manager.setDebug(true);
+
+    try {
+      await expect(manager.captureOOPIFs(1)).resolves.toBeUndefined();
+      const diagnostic = String(
+        logSpy.mock.calls.find((call) =>
+          String(call[0] ?? "").includes("Failed to read newCDPSession")
+        )?.[0] ?? ""
+      );
+      expect(diagnostic).toContain("[truncated");
+      expect(diagnostic).not.toContain("\u0000");
+      expect(diagnostic).not.toContain("\n");
+    } finally {
+      logSpy.mockRestore();
+    }
+  });
+
+  it("captureOOPIFs uses the browser-context receiver for session creation", async () => {
+    const session = new FakeSession();
+    const mainFrame = {
+      url: () => "https://example.com",
+      parentFrame: () => null,
+      name: () => "main",
+      isDetached: () => false,
+    };
+    const sameOriginFrame = {
+      url: () => "https://example.com/child",
+      parentFrame: () => mainFrame,
+      name: () => "child",
+      isDetached: () => false,
+    };
+    const context = {
+      newCDPSession: jest.fn(function (this: unknown, frame: unknown) {
+        if (this !== context) {
+          throw new Error("invalid context receiver");
+        }
+        void frame;
+        return Promise.reject(new Error("same origin frame"));
+      }),
+    };
+    const page = {
+      context: () => context,
+      frames: () => [mainFrame, sameOriginFrame],
+      mainFrame: () => mainFrame,
+    };
+    const manager = new FrameContextManager(
+      createFakeClientWithPage(session, page)
+    );
+
+    await expect(manager.captureOOPIFs(1)).resolves.toBeUndefined();
+    expect(context.newCDPSession).toHaveBeenCalledWith(sameOriginFrame);
+  });
+
+  it("captureOOPIFs skips ad/tracking frame session creation by default", async () => {
+    const session = new FakeSession();
+    const mainFrame = {
+      url: () => "https://example.com",
+      parentFrame: () => null,
+      name: () => "main",
+      isDetached: () => false,
+    };
+    const adFrame = {
+      url: () => "https://ad.doubleclick.net/pagead/ads?gdfp_req=1",
+      parentFrame: () => mainFrame,
+      name: () => "ad-frame",
+      isDetached: () => false,
+    };
+    const newCDPSession = jest.fn().mockRejectedValue(new Error("same origin frame"));
+    const page = {
+      context: () => ({
+        newCDPSession,
+      }),
+      frames: () => [mainFrame, adFrame],
+      mainFrame: () => mainFrame,
+    };
+
+    const manager = new FrameContextManager(
+      createFakeClientWithPage(session, page)
+    );
+
+    await expect(manager.captureOOPIFs(1)).resolves.toBeUndefined();
+    expect(newCDPSession).not.toHaveBeenCalled();
+  });
+
+  it("captureOOPIFs allows ad/tracking frame session creation when filtering is disabled", async () => {
+    const session = new FakeSession();
+    const mainFrame = {
+      url: () => "https://example.com",
+      parentFrame: () => null,
+      name: () => "main",
+      isDetached: () => false,
+    };
+    const adFrame = {
+      url: () => "https://ad.doubleclick.net/pagead/ads?gdfp_req=1",
+      parentFrame: () => mainFrame,
+      name: () => "ad-frame",
+      isDetached: () => false,
+    };
+    const newCDPSession = jest.fn().mockRejectedValue(new Error("same origin frame"));
+    const page = {
+      context: () => ({
+        newCDPSession,
+      }),
+      frames: () => [mainFrame, adFrame],
+      mainFrame: () => mainFrame,
+    };
+
+    const manager = new FrameContextManager(
+      createFakeClientWithPage(session, page)
+    );
+    manager.setFrameFilteringEnabled(false);
+
+    await expect(manager.captureOOPIFs(1)).resolves.toBeUndefined();
+    expect(newCDPSession).toHaveBeenCalledWith(adFrame);
+  });
+
+  it("captureOOPIFs keeps cached records when frame metadata getters trap", async () => {
+    const session = new FakeSession();
+    const mainFrame = {
+      url: () => "https://example.com",
+      parentFrame: () => null,
+      name: () => "main",
+      isDetached: () => false,
+    };
+    const trappedFrame = {
+      url: () => {
+        throw new Error("frame url trap");
+      },
+      parentFrame: () => null,
+      name: () => {
+        throw new Error("frame name trap");
+      },
+      isDetached: () => false,
+    };
+    const page = {
+      context: () => ({
+        newCDPSession: jest.fn(),
+      }),
+      frames: () => [mainFrame, trappedFrame],
+      mainFrame: () => mainFrame,
+    };
+
+    const manager = new FrameContextManager(
+      createFakeClientWithPage(session, page)
+    );
+    (
+      manager as unknown as {
+        playwrightOopifCache: Map<unknown, unknown>;
+      }
+    ).playwrightOopifCache.set(trappedFrame, {
+      frameId: "cached-oopif",
+      session,
+      url: "https://cached.example",
+      name: "cached-name",
+      parentFrameUrl: null,
+      playwrightFrame: trappedFrame,
+    });
+
+    await expect(manager.captureOOPIFs(1)).resolves.toBeUndefined();
+    const cached = (
+      manager as unknown as {
+        playwrightOopifCache: Map<
+          unknown,
+          { url?: string; name?: string; frameId?: string }
+        >;
+      }
+    ).playwrightOopifCache.get(trappedFrame);
+    expect(cached?.frameId).toBe("cached-oopif");
+    expect(cached?.url).toBe("about:blank");
+    expect(cached?.name).toBeUndefined();
+  });
+});
diff --git a/src/cdp/frame-context-manager.ts b/src/cdp/frame-context-manager.ts
index 86eb1f10..5dd392b3 100644
--- a/src/cdp/frame-context-manager.ts
+++ b/src/cdp/frame-context-manager.ts
@@ -3,6 +3,11 @@ import type { CDPSession, CDPClient } from "./types";
 import type { FrameRecord } from "./frame-graph";
 import { FrameGraph } from "./frame-graph";
 import { isAdOrTrackingFrame } from "./frame-filters";
+import { formatUnknownError, normalizePageUrl } from "@/utils";
+
+const MAX_FRAME_CONTEXT_DIAGNOSTIC_CHARS = 400;
+const MAX_FRAME_NAME_CHARS = 200;
+const MAX_FRAME_URL_CHARS = 1_000;
 
 interface FrameTreeNode {
   frame: Protocol.Page.Frame;
@@ -34,6 +39,96 @@ interface UpsertFrameInput
   parentFrameId: string | null;
 }
 
+function sanitizeFrameContextDiagnostic(value: string): string {
+  if (value.length === 0) {
+    return value;
+  }
+  const withoutControlChars = Array.from(value, (char) => {
+    const code = char.charCodeAt(0);
+    return (code >= 0 && code < 32) || code === 127 ? " " : char;
+  }).join("");
+  return withoutControlChars.replace(/\s+/g, " ").trim();
+}
+
+function truncateFrameContextDiagnostic(value: string): string {
+  if (value.length <= MAX_FRAME_CONTEXT_DIAGNOSTIC_CHARS) {
+    return value;
+  }
+  const omitted = value.length - MAX_FRAME_CONTEXT_DIAGNOSTIC_CHARS;
+  return `${value.slice(0, MAX_FRAME_CONTEXT_DIAGNOSTIC_CHARS)}... [truncated ${omitted} chars]`;
+}
+
+function formatFrameContextDiagnostic(value: unknown): string {
+  const normalized = sanitizeFrameContextDiagnostic(formatUnknownError(value));
+  if (normalized.length === 0) {
+    return "unknown error";
+  }
+  return truncateFrameContextDiagnostic(normalized);
+}
+
+function safeReadFrameUrl(
+  frame: PlaywrightFrameHandle,
+  fallback: string = "about:blank"
+): string {
+  try {
+    return normalizePageUrl(frame.url(), { fallback });
+  } catch {
+    return fallback;
+  }
+}
+
+function safeReadFrameName(frame: PlaywrightFrameHandle): string | undefined {
+  try {
+    const name = frame.name();
+    if (typeof name !== "string") {
+      return undefined;
+    }
+    const normalized = sanitizeFrameContextDiagnostic(name);
+    return normalized.length > 0 ? normalized : undefined;
+  } catch {
+    return undefined;
+  }
+}
+
+function normalizeFrameRecordUrl(value: unknown): string {
+  return normalizePageUrl(value, {
+    fallback: "about:blank",
+    maxChars: MAX_FRAME_URL_CHARS,
+  });
+}
+
+function normalizeFrameRecordName(value: unknown): string | undefined {
+  if (typeof value !== "string") {
+    return undefined;
+  }
+  const normalized = sanitizeFrameContextDiagnostic(value);
+  if (normalized.length === 0) {
+    return undefined;
+  }
+  if (normalized.length <= MAX_FRAME_NAME_CHARS) {
+    return normalized;
+  }
+  return normalized.slice(0, MAX_FRAME_NAME_CHARS);
+}
+
+function safeReadParentFrameUrl(
+  frame: PlaywrightFrameHandle
+): string | null {
+  try {
+    const parentFrameUnknown = frame.parentFrame();
+    if (!parentFrameUnknown || typeof parentFrameUnknown !== "object") {
+      return null;
+    }
+    const parentFrame = parentFrameUnknown as { url?: () => unknown };
+    if (typeof parentFrame.url !== "function") {
+      return null;
+    }
+    return normalizePageUrl(parentFrame.url(), { fallback: "about:blank" });
+  } catch {
+    return null;
+  }
+}
+
 export class FrameContextManager {
   private readonly graph = new FrameGraph();
   private readonly sessions = new Map<string, CDPSession>();
@@ -43,13 +138,13 @@ export class FrameContextManager {
     string,
     Set<{ resolve: (value?: number) => void; timeoutId?: NodeJS.Timeout }>
   >();
-  private readonly runtimeTrackedSessions = new WeakSet<CDPSession>();
+  private runtimeTrackedSessions = new WeakSet<CDPSession>();
   private readonly sessionListeners = new Map<
     CDPSession,
     Array<{ event: string; handler: (...args: unknown[]) => void }>
   >();
   private readonly oopifFrameIds = new Set<string>();
-  private readonly pageTrackedSessions = new WeakSet<CDPSession>();
+  private pageTrackedSessions = new WeakSet<CDPSession>();
   private readonly playwrightOopifCache = new Map<
     PlaywrightFrameHandle,
     PlaywrightOOPIFRecord
@@ -58,13 +153,92 @@ export class FrameContextManager {
   private initialized = false;
   private initializingPromise: Promise<void> | null = null;
   private debugLogs = false;
+  private filterAdTrackingFrames = true;
 
   constructor(private readonly client: CDPClient) {}
 
+  private addSessionListener(
+    session: CDPSession,
+    event: string,
+    handler: (...args: unknown[]) => void
+  ): void {
+    const listeners = this.sessionListeners.get(session) ?? [];
+    listeners.push({ event, handler });
+    this.sessionListeners.set(session, listeners);
+  }
+
+  private resolveSessionMethod(
+    session: CDPSession,
+    methodName: "on" | "off"
+  ): ((event: string, handler: (...args: unknown[]) => void) => void) | null {
+    try {
+      const method = (session as CDPSession & { [key: string]: unknown })[
+        methodName
+      ];
+      if (typeof method !== "function") {
+        return null;
+      }
+      return method as (event: string, handler: (...args: unknown[]) => void) => void;
+    } catch (error) {
+      console.warn(
+        `[FrameContext] Failed to read session.${methodName}: ${formatFrameContextDiagnostic(
+          error
+        )}`
+      );
+      return null;
+    }
+  }
+
+  private attachSessionListener(
+    session: CDPSession,
+    event: string,
+    handler: (...args: unknown[]) => void
+  ): boolean {
+    const onMethod = this.resolveSessionMethod(session, "on");
+    if (!onMethod) {
+      return false;
+    }
+    try {
+      onMethod.call(session, event, handler);
+      return true;
+    } catch (error) {
+      console.warn(
+        `[FrameContext] Failed to attach session listener (${event}): ${formatFrameContextDiagnostic(
+          error
+        )}`
+      );
+      return false;
+    }
+  }
+
+  private detachSessionListener(
+    session: CDPSession,
+    event: string,
+    handler: (...args: unknown[]) => void
+  ): void {
+    const offMethod = this.resolveSessionMethod(session, "off");
+    if (!offMethod) {
+      return;
+    }
+    try {
+      offMethod.call(session, event, handler);
+    } catch (error) {
+      console.warn(
+        `[FrameContext] Failed to detach session listener (${event}): ${formatFrameContextDiagnostic(
+          error
+        )}`
+      );
+    }
+  }
+
   setDebug(debug?: boolean): void {
     this.debugLogs = !!debug;
   }
 
+  setFrameFilteringEnabled(enabled?: boolean): void {
+    this.filterAdTrackingFrames = enabled !== false;
+  }
+
   private log(message: string): void {
     if (this.debugLogs) {
       console.log(message);
@@ -74,7 +248,7 @@ export class FrameContextManager {
     const record = this.playwrightOopifCache.get(frame);
     if (!record) return;
     if (record.detachHandler) {
-      record.session.off?.("Detached", record.detachHandler);
+      this.detachSessionListener(record.session, "Detached", record.detachHandler);
       record.detachHandler = undefined;
     }
     this.playwrightOopifCache.delete(frame);
@@ -117,7 +291,7 @@ export class FrameContextManager {
         const listeners = this.sessionListeners.get(session);
         if (listeners) {
           for (const { event, handler } of listeners) {
-            session.off?.(event, handler);
+            this.detachSessionListener(session, event, handler);
           }
           this.sessionListeners.delete(session);
         }
@@ -249,6 +423,10 @@ export class FrameContextManager {
   }
 
   clear(): void {
+    for (const trackedFrame of Array.from(this.playwrightOopifCache.keys())) {
+      this.removeCachedPlaywrightFrame(trackedFrame);
+    }
+
     this.graph.clear();
     this.sessions.clear();
     this.frameExecutionContexts.clear();
@@ -264,12 +442,16 @@ export class FrameContextManager {
 
     for (const [session, listeners] of this.sessionListeners.entries()) {
       for (const { event, handler } of listeners) {
-        session.off?.(event, handler);
+        this.detachSessionListener(session, event, handler);
       }
     }
     this.sessionListeners.clear();
 
     this.oopifFrameIds.clear();
+    this.runtimeTrackedSessions = new WeakSet<CDPSession>();
+    this.pageTrackedSessions = new WeakSet<CDPSession>();
+    this.initialized = false;
+    this.initializingPromise = null;
   }
 
   async ensureInitialized(): Promise<void> {
@@ -309,8 +491,8 @@ export class FrameContextManager {
         frameId,
         parentFrameId,
         loaderId: node.frame.loaderId,
-        name: node.frame.name,
-        url: node.frame.url,
+        name: normalizeFrameRecordName(node.frame.name),
+        url: normalizeFrameRecordUrl(node.frame.url),
       });
 
       this.setFrameSession(frameId, session);
@@ -354,10 +536,11 @@ export class FrameContextManager {
   }
 
   private getFrameIdByUrl(url: string): string | null {
-    if (!url || url === "about:blank") return null;
+    const normalizedUrl = normalizeFrameRecordUrl(url);
+    if (!normalizedUrl || normalizedUrl === "about:blank") return null;
 
     for (const frame of this.graph.getAllFrames()) {
-      if (frame.url === url) return frame.frameId;
+      if (frame.url === normalizedUrl) return frame.frameId;
     }
     return null;
   }
@@ -382,13 +565,86 @@ export class FrameContextManager {
 
     // Type cast to Playwright Page - this is safe because we're using PlaywrightCDPClient
     const page = pageUnknown as {
-      context(): { newCDPSession(frame: unknown): Promise<CDPSession> };
-      frames(): Array<PlaywrightFrameHandle>;
-      mainFrame(): unknown;
+      context?: () => unknown;
+      frames?: () => unknown;
+      mainFrame?: () => unknown;
     };
 
-    const context = page.context();
-    const allFrames = page.frames();
+    let contextUnknown: unknown;
+    try {
+      const contextMethod = page.context;
+      if (typeof contextMethod !== "function") {
+        this.log("[FrameContext] Page context() unavailable for OOPIF discovery");
+        return;
+      }
+      contextUnknown = contextMethod.call(page);
+    } catch (error) {
+      this.log(
+        `[FrameContext] Failed to read page context for OOPIF discovery: ${formatFrameContextDiagnostic(
+          error
+        )}`
+      );
+      return;
+    }
+    if (!contextUnknown || typeof contextUnknown !== "object") {
+      this.log("[FrameContext] Page context unavailable for OOPIF discovery");
+      return;
+    }
+
+    let newCDPSessionMethod: unknown;
+    try {
+      newCDPSessionMethod = (
+        contextUnknown as { newCDPSession?: unknown }
+      ).newCDPSession;
+    } catch (error) {
+      this.log(
+        `[FrameContext] Failed to read newCDPSession() for OOPIF discovery: ${formatFrameContextDiagnostic(
+          error
+        )}`
+      );
+      return;
+    }
+    if (typeof newCDPSessionMethod !== "function") {
+      this.log("[FrameContext] newCDPSession() unavailable for OOPIF discovery");
+      return;
+    }
+
+    let allFrames: Array<PlaywrightFrameHandle>;
+    try {
+      const framesMethod = page.frames;
+      if (typeof framesMethod !== "function") {
+        this.log("[FrameContext] page.frames() unavailable for OOPIF discovery");
+        return;
+      }
+      const framesValue = framesMethod.call(page);
+      if (!Array.isArray(framesValue)) {
+        this.log("[FrameContext] page.frames() returned a non-array value");
+        return;
+      }
+      allFrames = framesValue as Array<PlaywrightFrameHandle>;
+    } catch (error) {
+      this.log(
+        `[FrameContext] Failed to read page frames for OOPIF discovery: ${formatFrameContextDiagnostic(
+          error
+        )}`
+      );
+      return;
+    }
+
+    let mainFrame: unknown = null;
+    try {
+      const mainFrameMethod = page.mainFrame;
+      if (typeof mainFrameMethod === "function") {
+        mainFrame = mainFrameMethod.call(page);
+      }
+    } catch (error) {
+      this.log(
+        `[FrameContext] Failed to read main frame for OOPIF discovery: ${formatFrameContextDiagnostic(
+          error
+        )}`
+      );
+      mainFrame = null;
+    }
 
     // Cleanup any previously tracked Playwright frames that are no longer present or detached
     const frameSet = new Set(allFrames);
@@ -401,9 +657,7 @@ export class FrameContextManager {
     }
 
     // Filter frames to process (exclude main frame)
-    const framesToCheck = allFrames.filter(
-      (frame) => frame !== page.mainFrame()
-    );
+    const framesToCheck = allFrames.filter((frame) => frame !== mainFrame);
 
     if (framesToCheck.length === 0) {
       return;
@@ -412,17 +666,17 @@ export class FrameContextManager {
     // Parallelize OOPIF discovery: try to create CDP session for all frames simultaneously
     const discoveryPromises = framesToCheck.map(async (frame, index) => {
       const cachedRecord = this.playwrightOopifCache.get(frame);
-      const parentFrameUnknown = frame.parentFrame();
-      const parentFrame = parentFrameUnknown as { url(): string } | null;
-      const parentFrameUrl = parentFrame?.url();
+      const parentFrameUrl = safeReadParentFrameUrl(frame);
+      const frameUrl = safeReadFrameUrl(frame);
+      const frameName = safeReadFrameName(frame);
 
       if (cachedRecord) {
         this.log(
-          `[FrameContext] Frame ${frame.url()} already has a cached record, skipping`
+          `[FrameContext] Frame ${frameUrl} already has a cached record, skipping`
         );
         if (typeof frame.isDetached === "function" && frame.isDetached()) {
           this.log(
-            `[FrameContext] Frame ${frame.url()} is detached, removing cached record`
+            `[FrameContext] Frame ${frameUrl} is detached, removing cached record`
           );
           const frameId = cachedRecord.frameId;
           this.removeCachedPlaywrightFrame(frame);
@@ -431,8 +685,8 @@ export class FrameContextManager {
           }
           return null;
         }
-        cachedRecord.url = frame.url();
-        cachedRecord.name = frame.name() || undefined;
+        cachedRecord.url = frameUrl;
+        cachedRecord.name = frameName;
         cachedRecord.parentFrameUrl = parentFrameUrl;
         cachedRecord.playwrightFrame = frame;
         return {
@@ -441,10 +695,16 @@ export class FrameContextManager {
           playwrightFrame: frame,
         };
       }
-      const frameUrl = frame.url();
 
       // Filter ad/tracking frames before attempting CDP session creation
-      if (isAdOrTrackingFrame({ url: frameUrl, name: frame.name(), parentUrl: parentFrameUrl || undefined })) {
+      if (
+        this.filterAdTrackingFrames &&
+        isAdOrTrackingFrame({
+          url: frameUrl,
+          name: frameName,
+          parentUrl: parentFrameUrl || undefined,
+        })
+      ) {
         this.log(`[FrameContext] Skipping ad/tracking frame: ${frameUrl}`);
         return null;
       }
@@ -452,7 +712,12 @@ export class FrameContextManager {
       // Try to create CDP session - if it succeeds, this is an OOPIF
       let oopifSession: CDPSession | null = null;
       try {
-        oopifSession = await context.newCDPSession(frame);
+        oopifSession = await (
+          newCDPSessionMethod as (
+            this: object,
+            frameArg: PlaywrightFrameHandle
+          ) => Promise<CDPSession>
+        ).call(contextUnknown as object, frame);
       } catch {
         // Failed to create session = same-origin frame (already processed via DOM.getDocument)
         this.log(`[FrameContext] Frame ${frameUrl} is same-origin, skipping`);
@@ -462,7 +727,10 @@ export class FrameContextManager {
       // Success! This is an OOPIF - get its CDP frame ID
       try {
         await oopifSession.send("Page.enable");
-        const { frameTree } = await oopifSession.send("Page.getFrameTree");
+        const { frameTree } =
+          await oopifSession.send<Protocol.Page.GetFrameTreeResponse>(
+            "Page.getFrameTree"
+          );
         const frameId = frameTree.frame.id;
 
         this.log(
@@ -473,17 +741,19 @@ export class FrameContextManager {
           frameId,
           session: oopifSession,
           url: frameUrl,
-          name: frame.name() || undefined,
+          name: frameName,
           parentFrameUrl,
           playwrightFrame: frame,
         };
         const detachHandler = (): void => {
           this.removeCachedPlaywrightFrame(frame);
           this.removeFrame(frameId);
-          oopifSession?.off?.("Detached", detachHandler);
+          if (oopifSession) {
+            this.detachSessionListener(oopifSession, "Detached", detachHandler);
+          }
         };
         record.detachHandler = detachHandler;
-        oopifSession.on?.("Detached", detachHandler);
+        this.attachSessionListener(oopifSession, "Detached", detachHandler);
         this.playwrightOopifCache.set(frame, record);
 
         return {
@@ -493,7 +763,9 @@ export class FrameContextManager {
         };
       } catch (_error) {
         this.log(
-          `[FrameContext] Failed to process OOPIF ${frameUrl}: ${_error}`
+          `[FrameContext] Failed to process OOPIF ${frameUrl}: ${formatFrameContextDiagnostic(
+            _error
+          )}`
         );
         if (oopifSession) {
           await oopifSession.detach().catch(() => {
@@ -542,12 +814,20 @@ export class FrameContextManager {
     await session
       .send("Page.enable")
       .catch((error) =>
-        console.warn("[FrameContext] Failed to enable Page domain:", error)
+        console.warn(
+          `[FrameContext] Failed to enable Page domain: ${formatFrameContextDiagnostic(
+            error
+          )}`
+        )
       );
 
     const attachedHandler = (event: Protocol.Page.FrameAttachedEvent): void => {
       this.handlePageFrameAttached(event).catch((error) =>
-        console.warn("[FrameContext] Error handling frameAttached:", error)
+        console.warn(
+          `[FrameContext] Error handling frameAttached: ${formatFrameContextDiagnostic(
+            error
+          )}`
+        )
       );
     };
 
@@ -561,26 +841,45 @@ export class FrameContextManager {
       this.handlePageFrameNavigated(event);
     };
 
-    session.on("Page.frameAttached", attachedHandler);
-    session.on("Page.frameDetached", detachedHandler);
-    session.on("Page.frameNavigated", navigatedHandler);
-
-    const listeners = this.sessionListeners.get(session) ?? [];
-    listeners.push(
-      {
-        event: "Page.frameAttached",
-        handler: attachedHandler as (...args: unknown[]) => void,
-      },
-      {
-        event: "Page.frameDetached",
-        handler: detachedHandler as (...args: unknown[]) => void,
-      },
-      {
-        event: "Page.frameNavigated",
-        handler: navigatedHandler as (...args: unknown[]) => void,
-      }
-    );
-    this.sessionListeners.set(session, listeners);
+    if (
+      this.attachSessionListener(
+        session,
+        "Page.frameAttached",
+        attachedHandler as (...args: unknown[]) => void
+      )
+    ) {
+      this.addSessionListener(
+        session,
+        "Page.frameAttached",
+        attachedHandler as (...args: unknown[]) => void
+      );
+    }
+    if (
+      this.attachSessionListener(
+        session,
+        "Page.frameDetached",
+        detachedHandler as (...args: unknown[]) => void
+      )
+    ) {
+      this.addSessionListener(
+        session,
+        "Page.frameDetached",
+        detachedHandler as (...args: unknown[]) => void
+      );
+    }
+    if (
+      this.attachSessionListener(
+        session,
+        "Page.frameNavigated",
+        navigatedHandler as (...args: unknown[]) => void
+      )
+    ) {
+      this.addSessionListener(
+        session,
+        "Page.frameNavigated",
+        navigatedHandler as (...args: unknown[]) => void
+      );
+    }
   }
 
   private async handlePageFrameAttached(
@@ -627,11 +926,12 @@ export class FrameContextManager {
       frameId,
       parentFrameId: event.frame.parentId ?? null,
       loaderId: event.frame.loaderId,
-      url: event.frame.url,
-      name: event.frame.name,
+      url: normalizeFrameRecordUrl(event.frame.url),
+      name: normalizeFrameRecordName(event.frame.name),
     });
+    const normalizedUrl = normalizeFrameRecordUrl(event.frame.url);
     this.log(
-      `[FrameContext] Page.frameNavigated: frameId=${frameId}, url=${event.frame.url}`
+      `[FrameContext] Page.frameNavigated: frameId=${frameId}, url=${normalizedUrl}`
     );
   }
 
@@ -697,29 +997,51 @@ export class FrameContextManager {
       }
     };
 
-    session.on("Runtime.executionContextCreated", createdHandler);
-    session.on("Runtime.executionContextDestroyed", destroyedHandler);
-    session.on("Runtime.executionContextsCleared", clearedHandler);
-
-    this.sessionListeners.set(session, [
-      {
-        event: "Runtime.executionContextCreated",
-        handler: createdHandler as (...args: unknown[]) => void,
-      },
-      {
-        event: "Runtime.executionContextDestroyed",
-        handler: destroyedHandler as (...args: unknown[]) => void,
-      },
-      {
-        event: "Runtime.executionContextsCleared",
-        handler: clearedHandler as (...args: unknown[]) => void,
-      },
-    ]);
+    if (
+      this.attachSessionListener(
+        session,
+        "Runtime.executionContextCreated",
+        createdHandler as (...args: unknown[]) => void
+      )
+    ) {
+      this.addSessionListener(
+        session,
+        "Runtime.executionContextCreated",
+        createdHandler as (...args: unknown[]) => void
+      );
+    }
+    if (
+      this.attachSessionListener(
+        session,
+        "Runtime.executionContextDestroyed",
+        destroyedHandler as (...args: unknown[]) => void
+      )
+    ) {
+      this.addSessionListener(
+        session,
+        "Runtime.executionContextDestroyed",
+        destroyedHandler as (...args: unknown[]) => void
+      );
+    }
+    if (
+      this.attachSessionListener(
+        session,
+        "Runtime.executionContextsCleared",
+        clearedHandler as (...args: unknown[]) => void
+      )
+    ) {
+      this.addSessionListener(
+        session,
+        "Runtime.executionContextsCleared",
+        clearedHandler as (...args: unknown[]) => void
+      );
+    }
 
     session.send("Runtime.enable").catch((error) => {
       console.warn(
-        "[FrameContextManager] Failed to enable Runtime domain:",
-        error
+        `[FrameContextManager] Failed to enable Runtime domain: ${formatFrameContextDiagnostic(
+          error
+        )}`
       );
     });
   }
diff --git a/src/cdp/frame-filters.test.ts b/src/cdp/frame-filters.test.ts
new file mode 100644
index 00000000..ce1a3f09
--- /dev/null
+++ b/src/cdp/frame-filters.test.ts
@@ -0,0 +1,144 @@
+import { isAdOrTrackingFrame } from "@/cdp/frame-filters";
+
+describe("isAdOrTrackingFrame", () => {
+  it("keeps about:blank frames to avoid false positives", () => {
+    expect(
+      isAdOrTrackingFrame({
+        url: "about:blank",
+      })
+    ).toBe(false);
+  });
+
+  it("does not filter legitimate frames with a single weak keyword signal", () => {
+    expect(
+      isAdOrTrackingFrame({
+        url: "https://example.com/sync-settings",
+        name: "account sync settings",
+      })
+    ).toBe(false);
+  });
+
+  it("filters known ad domains immediately", () => {
+    expect(
+      isAdOrTrackingFrame({
+        url: "https://securepubads.g.doubleclick.net/pagead/ads",
+      })
+    ).toBe(true);
+  });
+
+  it("filters protocol-relative known ad domains", () => {
+    expect(
+      isAdOrTrackingFrame({
+        url: "//securepubads.g.doubleclick.net/pagead/ads",
+      })
+    ).toBe(true);
+  });
+
+  it("filters known ad domains without explicit protocol", () => {
+    expect(
+      isAdOrTrackingFrame({
+        url: "securepubads.g.doubleclick.net/pagead/ads",
+      })
+    ).toBe(true);
+  });
+
+  it("filters known ad domains with host:port urls missing explicit protocol", () => {
+    expect(
+      isAdOrTrackingFrame({
+        url: "securepubads.g.doubleclick.net:443/pagead/ads",
+      })
+    ).toBe(true);
+  });
+
+  it("filters obvious pixel-style tracking frames", () => {
+    expect(
+      isAdOrTrackingFrame({
+        url: "https://tracker.example.com/pixel.gif?event=impression",
+        name: "tracking pixel (1x1)",
+      })
+    ).toBe(true);
+  });
+
+  it("filters combined suspicious signals", () => {
+    expect(
+      isAdOrTrackingFrame({
+        url: "https://cdn.example.net/widget/sync?prebid=1",
+      })
+    ).toBe(true);
+  });
+
+  it("filters scheme-less host URLs when tracking query params are present", () => {
+    expect(
+      isAdOrTrackingFrame({
+        url: "cdn.example.net/widget?prebid=1",
+      })
+    ).toBe(true);
+  });
+
+  it("keeps same-site frames when only weak ad signals are present", () => {
+    expect(
+      isAdOrTrackingFrame({
+        url: "https://app.example.com/assets/pixel.png?theme=dark",
+        parentUrl: "https://app.example.com/dashboard",
+      })
+    ).toBe(false);
+  });
+
+  it("still filters same-site frames when strong tracking signals exist", () => {
+    expect(
+      isAdOrTrackingFrame({
+        url: "https://app.example.com/widget/frame?prebid=1",
+        parentUrl: "https://app.example.com/dashboard",
+      })
+    ).toBe(true);
+  });
+
+  it("does not treat ad-domain tokens in path as known ad host matches", () => {
+    expect(
+      isAdOrTrackingFrame({
+        url: "https://docs.example.com/reference/doubleclick.net-integration",
+        parentUrl: "https://docs.example.com/guide",
+      })
+    ).toBe(false);
+  });
+
+  it("matches known ad domains by subdomain suffix", () => {
+    expect(
+      isAdOrTrackingFrame({
+        url: "https://ads.securepubads.g.doubleclick.net/pagead/ads",
+      })
+    ).toBe(true);
+  });
+
+  it("matches host+path ad-domain rules on the correct hostname only", () => {
+    expect(
+      isAdOrTrackingFrame({
+        url: "https://www.yahoo.com/pixel?event=view",
+      })
+    ).toBe(true);
+  });
+
+  it("does not match host+path ad-domain rules from unrelated host query text", () => {
+    expect(
+      isAdOrTrackingFrame({
+        url: "https://example.com/redirect?next=https://yahoo.com/pixel",
+      })
+    ).toBe(false);
+  });
+
+  it("does not match host-based ad domains for path-only urls", () => {
+    expect(
+      isAdOrTrackingFrame({
+        url: "/redirect/doubleclick.net/pagead/ads",
+      })
+    ).toBe(false);
+  });
+
+  it("does not treat path-only tracking query params as strong frame signal", () => {
+    expect(
+      isAdOrTrackingFrame({
+        url: "/widget?prebid=1",
+      })
+    ).toBe(false);
+  });
+});
diff --git a/src/cdp/frame-filters.ts b/src/cdp/frame-filters.ts
index c25d75e0..dd7ffe6e 100644
--- a/src/cdp/frame-filters.ts
+++ b/src/cdp/frame-filters.ts
@@ -9,126 +9,282 @@ export interface FrameFilterContext {
   parentUrl?: string;
 }
 
+interface FrameRiskSignal {
+  name: string;
+  weight: number;
+  matched: boolean;
+  strong?: boolean;
+}
+
+interface AdDomainRule {
+  host: string;
+  path?: string;
+}
+
+const PIXEL_PATTERNS = [/\(1×1\)/i, /\(1x1\)/i];
+
+const SUSPICIOUS_PATTERNS = [
+  /pixel/i,
+  /user-sync/i,
+  /cookie-sync/i,
+  /usersync/i,
+  /ecm3/i,
+  /dcm/i,
+  /safeframe/i,
+  /topics\s+frame/i,
+];
+
+const TRACKING_EXTENSIONS = [
+  ".gif",
+  ".ashx",
+  ".png?",
+  "/pixel",
+  "/usersync",
+];
+
+const AD_DOMAINS = [
+  // Google ad networks
+  "doubleclick.net",
+  "googlesyndication.com",
+  "googleadservices.com",
+  "google-analytics.com",
+  "googletagmanager.com",
+  "googletagservices.com",
+  "imasdk.googleapis.com",
+  // Yahoo/Verizon Media
+  "ybp.yahoo.com",
+  "yahoo.com/pixel",
+  // Major ad exchanges
+  "adnxs.com",
+  "rubiconproject.com",
+  "pubmatic.com",
+  "openx.net",
+  "advertising.com",
+  "contextweb.com",
+  "casalemedia.com",
+  // Retargeting/programmatic
+  "criteo.com",
+  "criteo.net",
+  "bidswitch.net",
+  // Analytics/tracking
+  "quantserve.com",
+  "scorecardresearch.com",
+  "moatads.com",
+  "adsafeprotected.com",
+  "chartbeat.com",
+  // Content recommendation (often ads)
+  "outbrain.com",
+  "taboola.com",
+  "zemanta.com",
+  // Other common ad networks
+  "openwebmedia.org",
+  "turn.com",
+  "amazon-adsystem.com",
+];
+
+const AD_DOMAIN_RULES: AdDomainRule[] = AD_DOMAINS.map((entry) => {
+  const [hostPart, ...pathParts] = entry.toLowerCase().split("/");
+  const normalizedHost = hostPart?.trim() ?? "";
+  const normalizedPath = pathParts.join("/").trim();
+  return normalizedPath.length > 0
+    ? { host: normalizedHost, path: `/${normalizedPath}` }
+    : { host: normalizedHost };
+});
+
+const TRACKING_PARAMS = [
+  "correlator=",
+  "google_push=",
+  "gdfp_req=",
+  "prebid",
+  "pubads",
+];
+
+const MIN_FILTER_SCORE = 2;
+
+const HAS_SCHEME_WITH_SLASHES_PATTERN = /^[a-z][a-z0-9+\-.]*:\/\//i;
+const SPECIAL_SCHEME_PREFIXES = [
+  "about:",
+  "data:",
+  "blob:",
+  "file:",
+  "javascript:",
+  "mailto:",
+  "chrome:",
+  "devtools:",
+];
+
+function normalizeUrlForParsing(value: string): string {
+  const trimmed = value.trim();
+  if (trimmed.length === 0) {
+    return "";
+  }
+  if (trimmed.startsWith("//")) {
+    return `https:${trimmed}`;
+  }
+  if (
+    HAS_SCHEME_WITH_SLASHES_PATTERN.test(trimmed) ||
+    SPECIAL_SCHEME_PREFIXES.some((prefix) =>
+      trimmed.toLowerCase().startsWith(prefix)
+    )
+  ) {
+    return trimmed;
+  }
+  if (trimmed.startsWith("/")) {
+    return "";
+  }
+  return `https://${trimmed}`;
+}
+
+function safeParseUrl(value: string | undefined): URL | null {
+  if (!value) {
+    return null;
+  }
+  const normalized = normalizeUrlForParsing(value);
+  if (normalized.length === 0) {
+    return null;
+  }
+  try {
+    return new URL(normalized);
+  } catch {
+    return null;
+  }
+}
+
+function safeGetHostname(value: string | undefined): string | null {
+  const parsed = safeParseUrl(value);
+  if (!parsed) {
+    return null;
+  }
+  const hostname = parsed.hostname.toLowerCase();
+  return hostname.length > 0 ? hostname : null;
+}
+
+function isSameSiteFrame(url: string, parentUrl: string | undefined): boolean {
+  const hostname = safeGetHostname(url);
+  const parentHostname = safeGetHostname(parentUrl);
+  if (!hostname || !parentHostname) {
+    return false;
+  }
+  return (
+    hostname === parentHostname ||
+    hostname.endsWith(`.${parentHostname}`) ||
+    parentHostname.endsWith(`.${hostname}`)
+  );
+}
+
+function matchesKnownAdDomain(url: string): boolean {
+  const parsedUrl = safeParseUrl(url);
+  if (!parsedUrl) {
+    return false;
+  }
+
+  const hostname = parsedUrl.hostname.toLowerCase();
+  const pathAndQuery = `${parsedUrl.pathname}${parsedUrl.search}`.toLowerCase();
+
+  return AD_DOMAIN_RULES.some((rule) => {
+    if (!rule.host) {
+      return false;
+    }
+    const hostMatches =
+      hostname === rule.host || hostname.endsWith(`.${rule.host}`);
+    if (!hostMatches) {
+      return false;
+    }
+    if (!rule.path) {
+      return true;
+    }
+    return pathAndQuery.includes(rule.path);
+  });
+}
+
 /**
  * Check if a frame is likely an ad or tracking iframe
- * 
- * Detection criteria:
- * 1. Tiny pixel frames (1x1) - common for tracking pixels
- * 2. Known ad/tracking keywords in URL or name
- * 3. Known ad network domains
- * 4. Common tracking file extensions
+ *
+ * Heuristic model:
+ * - Assign weighted signals for ad/tracking traits
+ * - Filter only when score meets threshold
+ * - Prevent single weak indicators (e.g. generic "sync" in URL) from dropping legitimate frames
  */
 export function isAdOrTrackingFrame(context: FrameFilterContext): boolean {
-  const { url, name } = context;
+  const { url, name, parentUrl } = context;
   const urlLower = url.toLowerCase();
   const nameLower = (name || "").toLowerCase();
-  
-  // 1. Empty or about:blank frames (except named ones which might be legitimate)
-  if (!url || url === "about:blank") {
-    return !name; // Keep if it has a name, filter if anonymous
+  let normalizedPathSignalText = urlLower;
+  let normalizedQuerySignalText = "";
+  const parsedUrl = safeParseUrl(urlLower);
+  if (parsedUrl) {
+    normalizedPathSignalText = `${parsedUrl.hostname}${parsedUrl.pathname}`;
+    normalizedQuerySignalText = parsedUrl.search;
   }
-  
-  // 2. Pixel/sync frame patterns in title/name
-  const suspiciousPatterns = [
-    /\(1×1\)/i,
-    /\(1x1\)/i,
-    /pixel/i,
-    /sync/i,
-    /user-sync/i,
-    /cookie-sync/i,
-    /usersync/i,
-    /match/i,
-    /ecm3/i,
-    /dcm/i,
-    /safeframe/i,
-    /topics\s+frame/i,
-  ];
-  
-  if (suspiciousPatterns.some(pattern => 
-    pattern.test(urlLower) || pattern.test(nameLower)
-  )) {
-    return true;
-  }
-  
-  // 3. Tracking/ad file extensions
-  const trackingExtensions = [
-    '.gif',
-    '.ashx',
-    '.png?',
-    '/pixel',
-    '/sync',
-    '/match',
-    '/usersync',
-  ];
-  
-  if (trackingExtensions.some(ext => urlLower.includes(ext))) {
-    return true;
+
+  // Allow empty/about:blank frames. They are often bootstrapped to real apps post-load.
+  if (!url || urlLower === "about:blank") {
+    return false;
   }
-  
-  // 4. Known ad network domains
-  const adDomains = [
-    // Google ad networks
-    'doubleclick.net',
-    'googlesyndication.com',
-    'googleadservices.com',
-    'google-analytics.com',
-    'googletagmanager.com',
-    'googletagservices.com',
-    'imasdk.googleapis.com',
-    // Yahoo/Verizon Media
-    'ybp.yahoo.com',
-    'yahoo.com/pixel',
-    // Major ad exchanges
-    'adnxs.com',
-    'rubiconproject.com',
-    'pubmatic.com',
-    'openx.net',
-    'advertising.com',
-    'contextweb.com',
-    'casalemedia.com',
-    // Retargeting/programmatic
-    'criteo.com',
-    'criteo.net',
-    'bidswitch.net',
-    // Analytics/tracking
-    'quantserve.com',
-    'scorecardresearch.com',
-    'moatads.com',
-    'adsafeprotected.com',
-    'chartbeat.com',
-    // Content recommendation (often ads)
-    'outbrain.com',
-    'taboola.com',
-    'zemanta.com',
-    // Other common ad networks
-    'openwebmedia.org',
-    'turn.com',
-    'advertising.com',
-    'amazon-adsystem.com',
+
+  const signals: FrameRiskSignal[] = [
+    {
+      name: "pixel-pattern",
+      weight: 2,
+      strong: true,
+      matched: PIXEL_PATTERNS.some(
+        (pattern) =>
+          pattern.test(normalizedPathSignalText) || pattern.test(nameLower)
+      ),
+    },
+    {
+      name: "suspicious-keyword",
+      weight: 1,
+      matched: SUSPICIOUS_PATTERNS.some(
+        (pattern) =>
+          pattern.test(normalizedPathSignalText) || pattern.test(nameLower)
+      ),
+    },
+    {
+      name: "tracking-extension",
+      weight: 1,
+      matched: TRACKING_EXTENSIONS.some((ext) =>
+        normalizedPathSignalText.includes(ext)
+      ),
+    },
+    {
+      name: "known-ad-domain",
+      weight: 2,
+      strong: true,
+      matched: matchesKnownAdDomain(urlLower),
+    },
+    {
+      name: "tracking-query-param",
+      weight: 2,
+      strong: true,
+      matched: TRACKING_PARAMS.some((param) =>
+        normalizedQuerySignalText.includes(param)
+      ),
+    },
+    {
+      name: "data-uri",
+      weight: 2,
+      strong: true,
+      matched: urlLower.startsWith("data:"),
+    },
   ];
-  
-  if (adDomains.some(domain => urlLower.includes(domain))) {
-    return true;
-  }
-  
-  // 5. Data URIs (often used for embedded ads)
-  if (urlLower.startsWith('data:')) {
-    return true;
+
+  const riskScore = signals.reduce(
+    (score, signal) => score + (signal.matched ? signal.weight : 0),
+    0
+  );
+
+  if (riskScore < MIN_FILTER_SCORE) {
+    return false;
   }
-  
-  // 6. Common tracking query parameters
-  const trackingParams = [
-    'correlator=',
-    'google_push=',
-    'gdfp_req=',
-    'prebid',
-    'pubads',
-  ];
-  
-  if (trackingParams.some(param => urlLower.includes(param))) {
-    return true;
+
+  const hasStrongSignal = signals.some(
+    (signal) => signal.matched && signal.strong === true
+  );
+  if (!hasStrongSignal && isSameSiteFrame(url, parentUrl)) {
+    return false;
   }
-  
-  return false;
+
+  return true;
 }
 
diff --git a/src/cdp/interactions.test.ts b/src/cdp/interactions.test.ts
new file mode 100644
index 00000000..681ae8fc
--- /dev/null
+++ b/src/cdp/interactions.test.ts
@@ -0,0 +1,1063 @@
+import { dispatchCDPAction } from "@/cdp/interactions";
+import type { CDPSession } from "@/cdp/types";
+
+function createSession(
+  sendImpl: (method: string, params?: Record<string, unknown>) => Promise<unknown>
+): CDPSession {
+  const send: CDPSession["send"] = async <T = unknown>(
+    method: string,
+    params?: Record<string, unknown>
+  ): Promise<T> => {
+    const response = await sendImpl(method, params);
+    return response as T;
+  };
+
+  return {
+    send,
+    on: jest.fn(),
+    off: jest.fn(),
+    detach: jest.fn(async () => undefined),
+  };
+}
+
+describe("dispatchCDPAction input guards", () => {
+  it("throws when action args are not an array", async () => {
+    const session = createSession(async () => ({}));
+
+    await expect(
+      dispatchCDPAction("click", null as unknown as unknown[], {
+        element: {
+          session,
+          frameId: "frame-1",
+          backendNodeId: 11,
+          objectId: "obj-1",
+        },
+      })
+    ).rejects.toThrow("[CDP][Interactions] Action args must be an array");
+  });
+
+  it("throws when action context has no valid session", async () => {
+    await expect(
+      dispatchCDPAction("click", [], {
+        element: {
+          session: {} as unknown as CDPSession,
+          frameId: "frame-1",
+          backendNodeId: 11,
+          objectId: "obj-1",
+        },
+      })
+    ).rejects.toThrow("[CDP][Interactions] Action context missing valid CDP session");
+  });
+
+  it("throws when action method is not a non-empty string", async () => {
+    const session = createSession(async () => ({}));
+
+    await expect(
+      dispatchCDPAction(42 as unknown as never, [], {
+        element: {
+          session,
+          frameId: "frame-1",
+          backendNodeId: 11,
+          objectId: "obj-1",
+        },
+      })
+    ).rejects.toThrow("[CDP][Interactions] Action method must be a non-empty string");
+
+    await expect(
+      dispatchCDPAction("   " as unknown as never, [], {
+        element: {
+          session,
+          frameId: "frame-1",
+          backendNodeId: 11,
+          objectId: "obj-1",
+        },
+      })
+    ).rejects.toThrow("[CDP][Interactions] Action method must be a non-empty string");
+  });
+
+  it("sanitizes unsupported action-method diagnostics", async () => {
+    const session = createSession(async () => ({}));
+    const noisyMethod = `bad\n${"x".repeat(300)}`;
+
+    try {
+      await dispatchCDPAction(noisyMethod as unknown as never, [], {
+        element: {
+          session,
+          frameId: "frame-1",
+          backendNodeId: 11,
+          objectId: "obj-1",
+        },
+      });
+      throw new Error("Expected dispatchCDPAction to throw");
+    } catch (error) {
+      const message = (error as Error).message;
+      expect(message).toContain("[CDP][Interactions] Unsupported action method:");
+      expect(message).toContain("[truncated");
+      expect(message).not.toContain("\n");
+    }
+  });
+});
+
+describe("dispatchCDPAction scroll fallback failures", () => {
+  it("formats non-Error primary/fallback failures for scrollToElement", async () => {
+    const session = createSession(async (method) => {
+      if (method === "DOM.scrollIntoViewIfNeeded") {
+        throw { primary: "scroll failed" };
+      }
+      if (method === "Runtime.callFunctionOn") {
+        throw { fallback: "runtime fallback failed" };
+      }
+      return {};
+    });
+
+    await expect(
+      dispatchCDPAction("scrollToElement", [], {
+        element: {
+          session,
+          frameId: "frame-1",
+          backendNodeId: 11,
+          objectId: "obj-1",
+        },
+      })
+    ).rejects.toThrow(
+      '[CDP][Interactions] Failed to scroll element into view. Primary method failed: {"primary":"scroll failed"}. Fallback also failed: {"fallback":"runtime fallback failed"}'
+    );
+  });
+
+  it("formats non-Error primary/fallback failures for click scroll pre-step", async () => {
+    const session = createSession(async (method) => {
+      if (method === "DOM.enable" || method === "Runtime.enable") {
+        return {};
+      }
+      if (method === "DOM.scrollIntoViewIfNeeded") {
+        throw { primary: "scroll failed" };
+      }
+      if (method === "Runtime.callFunctionOn") {
+        throw { fallback: "runtime fallback failed" };
+      }
+      return {};
+    });
+
+    await expect(
+      dispatchCDPAction("click", [], {
+        element: {
+          session,
+          frameId: "frame-1",
+          backendNodeId: 11,
+          objectId: "obj-1",
+        },
+      })
+    ).rejects.toThrow(
+      '[CDP][Interactions] Failed to scroll element into view. Primary method failed: {"primary":"scroll failed"}. Fallback also failed: {"fallback":"runtime fallback failed"}'
+    );
+  });
+
+  it("sanitizes and truncates oversized scroll fallback diagnostics", async () => {
+    const oversizedPrimary = `primary\u0000\n${"x".repeat(2_000)}`;
+    const oversizedFallback = `fallback\u0000\n${"y".repeat(2_000)}`;
+    const session = createSession(async (method) => {
+      if (method === "DOM.scrollIntoViewIfNeeded") {
+        throw new Error(oversizedPrimary);
+      }
+      if (method === "Runtime.callFunctionOn") {
+        throw new Error(oversizedFallback);
+      }
+      return {};
+    });
+
+    try {
+      await dispatchCDPAction("scrollToElement", [], {
+        element: {
+          session,
+          frameId: "frame-1",
+          backendNodeId: 11,
+          objectId: "obj-1",
+        },
+      });
+      throw new Error("Expected dispatchCDPAction to throw");
+    } catch (error) {
+      const message = (error as Error).message;
+      expect(message).toContain("[truncated");
+      expect(message).not.toContain("\u0000");
+      expect(message).not.toContain("\n");
+      expect(message.length).toBeLessThan(700);
+    }
+  });
+});
+
+describe("dispatchCDPAction press key normalization", () => {
+  it("falls back to Enter when press key is blank", async () => {
+    const calls: Array<{ method: string; params?: Record<string, unknown> }> = [];
+    const session = createSession(async (method, params) => {
+      calls.push({ method, params });
+      return {};
+    });
+
+    await dispatchCDPAction("press", ["   "], {
+      element: {
+        session,
+        frameId: "frame-1",
+        backendNodeId: 11,
+        objectId: "obj-1",
+      },
+    });
+
+    const keyDown = calls.find(
+      (call) =>
+        call.method === "Input.dispatchKeyEvent" &&
+        call.params?.type === "keyDown"
+    );
+
+    expect(keyDown?.params?.key).toBe("Enter");
+    expect(keyDown?.params?.code).toBe("Enter");
+    expect(keyDown?.params?.windowsVirtualKeyCode).toBe(13);
+  });
+
+  it("trims whitespace around named press keys", async () => {
+    const calls: Array<{ method: string; params?: Record<string, unknown> }> = [];
+    const session = createSession(async (method, params) => {
+      calls.push({ method, params });
+      return {};
+    });
+
+    await dispatchCDPAction("press", ["  tab  "], {
+      element: {
+        session,
+        frameId: "frame-1",
+        backendNodeId: 11,
+        objectId: "obj-1",
+      },
+    });
+
+    const keyDown = calls.find(
+      (call) =>
+        call.method === "Input.dispatchKeyEvent" &&
+        call.params?.type === "keyDown"
+    );
+
+    expect(keyDown?.params?.key).toBe("Tab");
+    expect(keyDown?.params?.code).toBe("Tab");
+    expect(keyDown?.params?.windowsVirtualKeyCode).toBe(9);
+  });
+
+  it("normalizes spaced and dashed named keys", async () => {
+    const calls: Array<{ method: string; params?: Record<string, unknown> }> = [];
+    const session = createSession(async (method, params) => {
+      calls.push({ method, params });
+      return {};
+    });
+
+    await dispatchCDPAction("press", ["Arrow Up"], {
+      element: {
+        session,
+        frameId: "frame-1",
+        backendNodeId: 11,
+        objectId: "obj-1",
+      },
+    });
+    await dispatchCDPAction("press", ["page-down"], {
+      element: {
+        session,
+        frameId: "frame-1",
+        backendNodeId: 11,
+        objectId: "obj-1",
+      },
+    });
+
+    const keyDownCalls = calls.filter(
+      (call) =>
+        call.method === "Input.dispatchKeyEvent" &&
+        call.params?.type === "keyDown"
+    );
+    expect(keyDownCalls[0]?.params?.key).toBe("ArrowUp");
+    expect(keyDownCalls[0]?.params?.windowsVirtualKeyCode).toBe(38);
+    expect(keyDownCalls[1]?.params?.key).toBe("PageDown");
+    expect(keyDownCalls[1]?.params?.windowsVirtualKeyCode).toBe(34);
+  });
+
+  it("supports return and spacebar key aliases", async () => {
+    const calls: Array<{ method: string; params?: Record<string, unknown> }> = [];
+    const session = createSession(async (method, params) => {
+      calls.push({ method, params });
+      return {};
+    });
+
+    await dispatchCDPAction("press", ["return"], {
+      element: {
+        session,
+        frameId: "frame-1",
+        backendNodeId: 11,
+        objectId: "obj-1",
+      },
+    });
+    await dispatchCDPAction("press", ["spacebar"], {
+      element: {
+        session,
+        frameId: "frame-1",
+        backendNodeId: 11,
+        objectId: "obj-1",
+      },
+    });
+
+    const keyDownCalls = calls.filter(
+      (call) =>
+        call.method === "Input.dispatchKeyEvent" &&
+        call.params?.type === "keyDown"
+    );
+    expect(keyDownCalls[0]?.params?.key).toBe("Enter");
+    expect(keyDownCalls[0]?.params?.windowsVirtualKeyCode).toBe(13);
+    expect(keyDownCalls[1]?.params?.key).toBe(" ");
+    expect(keyDownCalls[1]?.params?.code).toBe("Space");
+    expect(keyDownCalls[1]?.params?.text).toBe(" ");
+    expect(keyDownCalls[1]?.params?.windowsVirtualKeyCode).toBe(32);
+  });
+
+  it("supports page-down shorthand aliases", async () => {
+    const calls: Array<{ method: string; params?: Record<string, unknown> }> = [];
+    const session = createSession(async (method, params) => {
+      calls.push({ method, params });
+      return {};
+    });
+
+    await dispatchCDPAction("press", ["pgdn"], {
+      element: {
+        session,
+        frameId: "frame-1",
+        backendNodeId: 11,
+        objectId: "obj-1",
+      },
+    });
+
+    const keyDown = calls.find(
+      (call) =>
+        call.method === "Input.dispatchKeyEvent" &&
+        call.params?.type === "keyDown"
+    );
+    expect(keyDown?.params?.key).toBe("PageDown");
+    expect(keyDown?.params?.code).toBe("PageDown");
+    expect(keyDown?.params?.windowsVirtualKeyCode).toBe(34);
+  });
+
+  it("bounds oversized custom key strings before dispatch", async () => {
+    const calls: Array<{ method: string; params?: Record<string, unknown> }> = [];
+    const session = createSession(async (method, params) => {
+      calls.push({ method, params });
+      return {};
+    });
+    const oversizedKey = "k".repeat(500);
+
+    await dispatchCDPAction("press", [oversizedKey], {
+      element: {
+        session,
+        frameId: "frame-1",
+        backendNodeId: 11,
+        objectId: "obj-1",
+      },
+    });
+
+    const keyDown = calls.find(
+      (call) =>
+        call.method === "Input.dispatchKeyEvent" &&
+        call.params?.type === "keyDown"
+    );
+    expect(typeof keyDown?.params?.key).toBe("string");
+    expect((keyDown?.params?.key as string).length).toBeLessThanOrEqual(64);
+  });
+
+  it("falls back safely when key-string coercion throws", async () => {
+    const calls: Array<{ method: string; params?: Record<string, unknown> }> = [];
+    const session = createSession(async (method, params) => {
+      calls.push({ method, params });
+      return {};
+    });
+    const badValue = {
+      toString(): string {
+        throw new Error("coercion failure");
+      },
+    };
+
+    await dispatchCDPAction("press", [badValue], {
+      element: {
+        session,
+        frameId: "frame-1",
+        backendNodeId: 11,
+        objectId: "obj-1",
+      },
+    });
+
+    const keyDown = calls.find(
+      (call) =>
+        call.method === "Input.dispatchKeyEvent" &&
+        call.params?.type === "keyDown"
+    );
+    expect(keyDown?.params?.key).toBe("Enter");
+    expect(keyDown?.params?.windowsVirtualKeyCode).toBe(13);
+  });
+});
+
+describe("dispatchCDPAction argument coercion", () => {
+  it("preserves numeric zero values for type and fill actions", async () => {
+    const calls: Array<{ method: string; params?: Record<string, unknown> }> = [];
+    const session = createSession(async (method, params) => {
+      calls.push({ method, params });
+      return {};
+    });
+    const ctx = {
+      element: {
+        session,
+        frameId: "frame-1",
+        backendNodeId: 11,
+        objectId: "obj-1",
+      },
+    };
+
+    await dispatchCDPAction("type", [0], ctx);
+    await dispatchCDPAction("fill", [0], ctx);
+
+    const insertTextCall = calls.find(
+      (call) => call.method === "Input.insertText"
+    );
+    expect(insertTextCall?.params?.text).toBe("0");
+
+    const fillCall = calls.find(
+      (call) =>
+        call.method === "Runtime.callFunctionOn" &&
+        typeof call.params?.functionDeclaration === "string" &&
+        (call.params.functionDeclaration as string).includes("function(rawValue)")
+    );
+    const fillArgs = fillCall?.params?.arguments as
+      | Array<{ value?: unknown }>
+      | undefined;
+    expect(fillArgs?.[0]?.value).toBe("0");
+  });
+
+  it("rejects oversized type input before dispatch", async () => {
+    const calls: Array<{ method: string; params?: Record<string, unknown> }> = [];
+    const session = createSession(async (method, params) => {
+      calls.push({ method, params });
+      return {};
+    });
+    const oversized = "x".repeat(20_001);
+
+    await expect(
+      dispatchCDPAction("type", [oversized], {
+        element: {
+          session,
+          frameId: "frame-1",
+          backendNodeId: 11,
+          objectId: "obj-1",
+        },
+      })
+    ).rejects.toThrow("[CDP][Interactions] type input exceeds 20000 characters");
+    expect(calls).toHaveLength(0);
+  });
+
+  it("rejects oversized fill input before dispatch", async () => {
+    const calls: Array<{ method: string; params?: Record<string, unknown> }> = [];
+    const session = createSession(async (method, params) => {
+      calls.push({ method, params });
+      return {};
+    });
+    const oversized = "x".repeat(20_001);
+
+    await expect(
+      dispatchCDPAction("fill", [oversized], {
+        element: {
+          session,
+          frameId: "frame-1",
+          backendNodeId: 11,
+          objectId: "obj-1",
+        },
+      })
+    ).rejects.toThrow("[CDP][Interactions] fill input exceeds 20000 characters");
+    expect(calls).toHaveLength(0);
+  });
+
+  it("preserves numeric zero values for selectOption action", async () => {
+    const calls: Array<{ method: string; params?: Record<string, unknown> }> = [];
+    const session = createSession(async (method, params) => {
+      calls.push({ method, params });
+      return { result: { value: { status: "selected", value: "0" } } };
+    });
+
+    await dispatchCDPAction("selectOptionFromDropdown", [0], {
+      element: {
+        session,
+        frameId: "frame-1",
+        backendNodeId: 11,
+        objectId: "obj-1",
+      },
+    });
+
+    const selectCall = calls.find(
+      (call) =>
+        call.method === "Runtime.callFunctionOn" &&
+        typeof call.params?.functionDeclaration === "string" &&
+        (call.params.functionDeclaration as string).includes("function(rawValue)")
+    );
+    const selectArgs = selectCall?.params?.arguments as
+      | Array<{ value?: unknown }>
+      | undefined;
+    expect(selectArgs?.[0]?.value).toBe("0");
+  });
+
+  it("throws readable error when selectOption value coercion fails", async () => {
+    const session = createSession(async () => ({
+      result: { value: { status: "selected", value: "x" } },
+    }));
+    const badValue = {
+      toString(): string {
+        throw new Error("coercion failure");
+      },
+    };
+
+    await expect(
+      dispatchCDPAction("selectOptionFromDropdown", [badValue], {
+        element: {
+          session,
+          frameId: "frame-1",
+          backendNodeId: 11,
+          objectId: "obj-1",
+        },
+      })
+    ).rejects.toThrow(
+      "[CDP][Interactions] Failed to coerce action argument to string"
+    );
+  });
+
+  it("sanitizes oversized selectOption values in failure diagnostics", async () => {
+    const session = createSession(async () => ({
+      result: { value: { status: "notfound" } },
+    }));
+    const noisyValue = `\u0007${"x".repeat(500)}`;
+
+    await expect(
+      dispatchCDPAction("selectOptionFromDropdown", [noisyValue], {
+        element: {
+          session,
+          frameId: "frame-1",
+          backendNodeId: 11,
+          objectId: "obj-1",
+        },
+      })
+    ).rejects.toThrow(/\[truncated \d+ chars\]/);
+
+    try {
+      await dispatchCDPAction("selectOptionFromDropdown", [noisyValue], {
+        element: {
+          session,
+          frameId: "frame-1",
+          backendNodeId: 11,
+          objectId: "obj-1",
+        },
+      });
+      throw new Error("Expected selectOptionFromDropdown to throw");
+    } catch (error) {
+      const message = (error as Error).message;
+      expect(message).not.toContain("\u0007");
+      expect(message).toContain("Failed to select");
+    }
+  });
+
+  it("rejects oversized selectOption values before dispatch", async () => {
+    const calls: Array<{ method: string; params?: Record<string, unknown> }> = [];
+    const session = createSession(async (method, params) => {
+      calls.push({ method, params });
+      return { result: { value: { status: "selected", value: "x" } } };
+    });
+    const oversizedValue = "x".repeat(2_001);
+
+    await expect(
+      dispatchCDPAction("selectOptionFromDropdown", [oversizedValue], {
+        element: {
+          session,
+          frameId: "frame-1",
+          backendNodeId: 11,
+          objectId: "obj-1",
+        },
+      })
+    ).rejects.toThrow(
+      "[CDP][Interactions] selectOption value exceeds 2000 characters"
+    );
+    expect(calls).toHaveLength(0);
+  });
+
+  it("rejects empty selectOption values before dispatch", async () => {
+    const calls: Array<{ method: string; params?: Record<string, unknown> }> = [];
+    const session = createSession(async (method, params) => {
+      calls.push({ method, params });
+      return { result: { value: { status: "selected", value: "x" } } };
+    });
+
+    await expect(
+      dispatchCDPAction("selectOptionFromDropdown", ["   "], {
+        element: {
+          session,
+          frameId: "frame-1",
+          backendNodeId: 11,
+          objectId: "obj-1",
+        },
+      })
+    ).rejects.toThrow("[CDP][Interactions] selectOption value must be non-empty");
+    expect(calls).toHaveLength(0);
+  });
+
+  it("still commits Enter for empty type action with commitEnter", async () => {
+    const calls: Array<{ method: string; params?: Record<string, unknown> }> = [];
+    const session = createSession(async (method, params) => {
+      calls.push({ method, params });
+      return {};
+    });
+
+    await dispatchCDPAction("type", ["", { commitEnter: true }], {
+      element: {
+        session,
+        frameId: "frame-1",
+        backendNodeId: 11,
+        objectId: "obj-1",
+      },
+    });
+
+    expect(calls.some((call) => call.method === "Input.insertText")).toBe(false);
+    expect(
+      calls.some(
+        (call) =>
+          call.method === "Input.dispatchKeyEvent" &&
+          call.params?.type === "keyDown" &&
+          call.params?.key === "Enter"
+      )
+    ).toBe(true);
+  });
+
+  it("requires boolean true for commitEnter option", async () => {
+    const calls: Array<{ method: string; params?: Record<string, unknown> }> = [];
+    const session = createSession(async (method, params) => {
+      calls.push({ method, params });
+      return {};
+    });
+
+    await dispatchCDPAction("type", ["hello", { commitEnter: "true" }], {
+      element: {
+        session,
+        frameId: "frame-1",
+        backendNodeId: 11,
+        objectId: "obj-1",
+      },
+    });
+
+    expect(
+      calls.some(
+        (call) =>
+          call.method === "Input.dispatchKeyEvent" &&
+          call.params?.type === "keyDown"
+      )
+    ).toBe(false);
+  });
+
+  it("rejects oversized delayMs options before dispatch", async () => {
+    const calls: Array<{ method: string; params?: Record<string, unknown> }> = [];
+    const session = createSession(async (method, params) => {
+      calls.push({ method, params });
+      return {};
+    });
+
+    await expect(
+      dispatchCDPAction("press", ["Enter", { delayMs: 10_001 }], {
+        element: {
+          session,
+          frameId: "frame-1",
+          backendNodeId: 11,
+          objectId: "obj-1",
+        },
+      })
+    ).rejects.toThrow("[CDP][Interactions] delayMs exceeds 10000ms");
+    expect(calls).toHaveLength(0);
+  });
+
+  it("ignores trap-prone option getters during option normalization", async () => {
+    const calls: Array<{ method: string; params?: Record<string, unknown> }> = [];
+    const session = createSession(async (method, params) => {
+      calls.push({ method, params });
+      return {};
+    });
+    const trappedOptions = new Proxy(
+      {},
+      {
+        get: (_target, prop) => {
+          if (prop === "delayMs") {
+            throw new Error("delay getter trap");
+          }
+          return undefined;
+        },
+      }
+    );
+
+    await dispatchCDPAction("press", ["Enter", trappedOptions], {
+      element: {
+        session,
+        frameId: "frame-1",
+        backendNodeId: 11,
+        objectId: "obj-1",
+      },
+    });
+
+    expect(
+      calls.some(
+        (call) =>
+          call.method === "Input.dispatchKeyEvent" &&
+          call.params?.type === "keyDown" &&
+          call.params?.key === "Enter"
+      )
+    ).toBe(true);
+  });
+
+  it("falls back to default scroll percentage for null/object targets", async () => {
+    const calls: Array<{ method: string; params?: Record<string, unknown> }> = [];
+    const session = createSession(async (method, params) => {
+      calls.push({ method, params });
+      return {
+        result: {
+          value: { status: "done", finalTop: 0, maxScroll: 100 },
+        },
+      };
+    });
+    const ctx = {
+      element: {
+        session,
+        frameId: "frame-1",
+        backendNodeId: 11,
+        objectId: "obj-1",
+      },
+    };
+
+    await dispatchCDPAction("scrollToPercentage", [null], ctx);
+    await dispatchCDPAction("scrollToPercentage", [{ target: null }], ctx);
+
+    const scrollCalls = calls.filter(
+      (call) =>
+        call.method === "Runtime.callFunctionOn" &&
+        typeof call.params?.functionDeclaration === "string" &&
+        (call.params.functionDeclaration as string).includes(
+          "function(percent, behavior)"
+        )
+    );
+    expect(scrollCalls.length).toBe(2);
+    for (const scrollCall of scrollCalls) {
+      const args = scrollCall.params?.arguments as
+        | Array<{ value?: unknown }>
+        | undefined;
+      expect(args?.[0]?.value).toBe(50);
+    }
+  });
+
+  it("handles throwing object getters in scroll options safely", async () => {
+    const calls: Array<{ method: string; params?: Record<string, unknown> }> = [];
+    const session = createSession(async (method, params) => {
+      calls.push({ method, params });
+      return {
+        result: {
+          value: { status: "done", finalTop: 0, maxScroll: 100 },
+        },
+      };
+    });
+    const throwingOptions: Record<string, unknown> = {};
+    Object.defineProperty(throwingOptions, "target", {
+      get(): unknown {
+        throw new Error("target read failed");
+      },
+    });
+    Object.defineProperty(throwingOptions, "behavior", {
+      get(): unknown {
+        throw new Error("behavior read failed");
+      },
+    });
+
+    await dispatchCDPAction("scrollTo", [throwingOptions], {
+      element: {
+        session,
+        frameId: "frame-1",
+        backendNodeId: 11,
+        objectId: "obj-1",
+      },
+    });
+
+    const scrollCall = calls.find(
+      (call) =>
+        call.method === "Runtime.callFunctionOn" &&
+        typeof call.params?.functionDeclaration === "string" &&
+        (call.params.functionDeclaration as string).includes(
+          "function(percent, behavior)"
+        )
+    );
+    const args = scrollCall?.params?.arguments as
+      | Array<{ value?: unknown }>
+      | undefined;
+    expect(args?.[0]?.value).toBe(50);
+    expect(args?.[1]?.value).toBeUndefined();
+  });
+
+  it("sanitizes control characters in scroll percentage strings", async () => {
+    const calls: Array<{ method: string; params?: Record<string, unknown> }> = [];
+    const session = createSession(async (method, params) => {
+      calls.push({ method, params });
+      return {
+        result: {
+          value: { status: "done", finalTop: 0, maxScroll: 100 },
+        },
+      };
+    });
+
+    await dispatchCDPAction("scrollToPercentage", ["75\u0007%"], {
+      element: {
+        session,
+        frameId: "frame-1",
+        backendNodeId: 11,
+        objectId: "obj-1",
+      },
+    });
+    await dispatchCDPAction("scrollToPercentage", ["\u0007"], {
+      element: {
+        session,
+        frameId: "frame-1",
+        backendNodeId: 11,
+        objectId: "obj-1",
+      },
+    });
+
+    const scrollCalls = calls.filter(
+      (call) =>
+        call.method === "Runtime.callFunctionOn" &&
+        typeof call.params?.functionDeclaration === "string" &&
+        (call.params.functionDeclaration as string).includes(
+          "function(percent, behavior)"
+        )
+    );
+    const firstArgs = scrollCalls[0]?.params?.arguments as
+      | Array<{ value?: unknown }>
+      | undefined;
+    const secondArgs = scrollCalls[1]?.params?.arguments as
+      | Array<{ value?: unknown }>
+      | undefined;
+
+    expect(firstArgs?.[0]?.value).toBe(75);
+    expect(secondArgs?.[0]?.value).toBe(50);
+  });
+
+  it("normalizes scroll behavior and target strings from object options", async () => {
+    const calls: Array<{ method: string; params?: Record<string, unknown> }> = [];
+    const session = createSession(async (method, params) => {
+      calls.push({ method, params });
+      return {
+        result: {
+          value: { status: "done", finalTop: 0, maxScroll: 100 },
+        },
+      };
+    });
+
+    await dispatchCDPAction(
+      "scrollTo",
+      [
+        {
+          target: "  80%\u0007 ",
+          behavior: "  SMOOTH\u0007 ",
+        },
+      ],
+      {
+        element: {
+          session,
+          frameId: "frame-1",
+          backendNodeId: 11,
+          objectId: "obj-1",
+        },
+      }
+    );
+
+    const scrollCall = calls.find(
+      (call) =>
+        call.method === "Runtime.callFunctionOn" &&
+        typeof call.params?.functionDeclaration === "string" &&
+        (call.params.functionDeclaration as string).includes(
+          "function(percent, behavior)"
+        )
+    );
+    const args = scrollCall?.params?.arguments as
+      | Array<{ value?: unknown }>
+      | undefined;
+    expect(args?.[0]?.value).toBe(80);
+    expect(args?.[1]?.value).toBe("smooth");
+  });
+
+  it("accepts auto scroll behavior alias in object options", async () => {
+    const calls: Array<{ method: string; params?: Record<string, unknown> }> = [];
+    const session = createSession(async (method, params) => {
+      calls.push({ method, params });
+      return {
+        result: {
+          value: { status: "done", finalTop: 0, maxScroll: 100 },
+        },
+      };
+    });
+
+    await dispatchCDPAction(
+      "scrollTo",
+      [
+        {
+          target: "30%",
+          behavior: "  AUTO\u0007 ",
+        },
+      ],
+      {
+        element: {
+          session,
+          frameId: "frame-1",
+          backendNodeId: 11,
+          objectId: "obj-1",
+        },
+      }
+    );
+
+    const scrollCall = calls.find(
+      (call) =>
+        call.method === "Runtime.callFunctionOn" &&
+        typeof call.params?.functionDeclaration === "string" &&
+        (call.params.functionDeclaration as string).includes(
+          "function(percent, behavior)"
+        )
+    );
+    const args = scrollCall?.params?.arguments as
+      | Array<{ value?: unknown }>
+      | undefined;
+    expect(args?.[0]?.value).toBe(30);
+    expect(args?.[1]?.value).toBe("instant");
+  });
+
+  it("falls back to 50% for non-finite numeric scroll targets", async () => {
+    const calls: Array<{ method: string; params?: Record<string, unknown> }> = [];
+    const session = createSession(async (method, params) => {
+      calls.push({ method, params });
+      return {
+        result: {
+          value: { status: "done", finalTop: 0, maxScroll: 100 },
+        },
+      };
+    });
+
+    await dispatchCDPAction("scrollToPercentage", [Number.NaN], {
+      element: {
+        session,
+        frameId: "frame-1",
+        backendNodeId: 11,
+        objectId: "obj-1",
+      },
+    });
+    await dispatchCDPAction("scrollToPercentage", [Number.POSITIVE_INFINITY], {
+      element: {
+        session,
+        frameId: "frame-1",
+        backendNodeId: 11,
+        objectId: "obj-1",
+      },
+    });
+
+    const scrollCalls = calls.filter(
+      (call) =>
+        call.method === "Runtime.callFunctionOn" &&
+        typeof call.params?.functionDeclaration === "string" &&
+        (call.params.functionDeclaration as string).includes(
+          "function(percent, behavior)"
+        )
+    );
+    const firstArgs = scrollCalls[0]?.params?.arguments as
+      | Array<{ value?: unknown }>
+      | undefined;
+    const secondArgs = scrollCalls[1]?.params?.arguments as
+      | Array<{ value?: unknown }>
+      | undefined;
+
+    expect(firstArgs?.[0]?.value).toBe(50);
+    expect(secondArgs?.[0]?.value).toBe(50);
+  });
+
+  it("falls back to 50% for non-finite string scroll targets", async () => {
+    const calls: Array<{ method: string; params?: Record<string, unknown> }> = [];
+    const session = createSession(async (method, params) => {
+      calls.push({ method, params });
+      return {
+        result: {
+          value: { status: "done", finalTop: 0, maxScroll: 100 },
+        },
+      };
+    });
+
+    await dispatchCDPAction("scrollToPercentage", ["Infinity"], {
+      element: {
+        session,
+        frameId: "frame-1",
+        backendNodeId: 11,
+        objectId: "obj-1",
+      },
+    });
+    await dispatchCDPAction("scrollToPercentage", ["1e309%"], {
+      element: {
+        session,
+        frameId: "frame-1",
+        backendNodeId: 11,
+        objectId: "obj-1",
+      },
+    });
+
+    const scrollCalls = calls.filter(
+      (call) =>
+        call.method === "Runtime.callFunctionOn" &&
+        typeof call.params?.functionDeclaration === "string" &&
+        (call.params.functionDeclaration as string).includes(
+          "function(percent, behavior)"
+        )
+    );
+    const firstArgs = scrollCalls[0]?.params?.arguments as
+      | Array<{ value?: unknown }>
+      | undefined;
+    const secondArgs = scrollCalls[1]?.params?.arguments as
+      | Array<{ value?: unknown }>
+      | undefined;
+
+    expect(firstArgs?.[0]?.value).toBe(50);
+    expect(secondArgs?.[0]?.value).toBe(50);
+  });
+
+  it("falls back to 50% for oversized scroll target strings", async () => {
+    const calls: Array<{ method: string; params?: Record<string, unknown> }> = [];
+    const session = createSession(async (method, params) => {
+      calls.push({ method, params });
+      return {
+        result: {
+          value: { status: "done", finalTop: 0, maxScroll: 100 },
+        },
+      };
+    });
+    const oversizedTarget = "9".repeat(200);
+
+    await dispatchCDPAction("scrollToPercentage", [oversizedTarget], {
+      element: {
+        session,
+        frameId: "frame-1",
+        backendNodeId: 11,
+        objectId: "obj-1",
+      },
+    });
+
+    const scrollCall = calls.find(
+      (call) =>
+        call.method === "Runtime.callFunctionOn" &&
+        typeof call.params?.functionDeclaration === "string" &&
+        (call.params.functionDeclaration as string).includes(
+          "function(percent, behavior)"
+        )
+    );
+    const args = scrollCall?.params?.arguments as
+      | Array<{ value?: unknown }>
+      | undefined;
+
+    expect(args?.[0]?.value).toBe(50);
+  });
+});
diff --git a/src/cdp/interactions.ts b/src/cdp/interactions.ts
index 4b2173a0..45896e1c 100644
--- a/src/cdp/interactions.ts
+++ b/src/cdp/interactions.ts
@@ -4,6 +4,7 @@ import type { BoundingBox } from "@/cdp/bounding-box";
 import { getBoundingBox } from "@/cdp/bounding-box";
 import type { ResolvedCDPElement } from "@/cdp/element-resolver";
 import type { CDPSession } from "@/cdp/types";
+import { formatUnknownError } from "@/utils";
 
 type MouseButton = "left" | "right" | "middle";
 
@@ -51,25 +52,6 @@ export interface CDPActionContext {
   preferScriptBoundingBox?: boolean;
 }
 
-interface ClickOptions {
-  button?: MouseButton;
-  clickCount?: 1 | 2;
-  delayMs?: number;
-}
-
-interface TypeOptions {
-  commitEnter?: boolean;
-  delayMs?: number;
-}
-
-interface PressOptions {
-  delayMs?: number;
-}
-
-interface FillOptions {
-  commitChange?: boolean;
-}
-
 interface ScrollToOptions {
   target?: string | number;
   behavior?: "smooth" | "instant";
@@ -79,9 +61,48 @@ interface SelectOptionOptions {
   value: string;
 }
 
+function formatInteractionDiagnostic(
+  value: unknown,
+  fallback: string
+): string {
+  const raw = typeof value === "string" ? value : formatUnknownError(value);
+  const normalized = stripControlChars(raw).replace(/\s+/g, " ").trim();
+  if (normalized.length === 0) {
+    return fallback;
+  }
+  if (normalized.length <= MAX_INTERACTION_DIAGNOSTIC_CHARS) {
+    return normalized;
+  }
+  return `${normalized.slice(
+    0,
+    MAX_INTERACTION_DIAGNOSTIC_CHARS
+  )}... [truncated ${normalized.length - MAX_INTERACTION_DIAGNOSTIC_CHARS} chars]`;
+}
+
+function createScrollIntoViewFailureMessage(
+  primaryError: unknown,
+  fallbackError: unknown
+): string {
+  return (
+    `[CDP][Interactions] Failed to scroll element into view. ` +
+    `Primary method failed: ${formatInteractionDiagnostic(
+      primaryError,
+      "unknown error"
+    )}. ` +
+    `Fallback also failed: ${formatInteractionDiagnostic(
+      fallbackError,
+      "unknown error"
+    )}`
+  );
+}
+
 type SelectOptionResult =
   | { status: "selected"; value: string }
   | { status: "notfound" };
+const MAX_INTERACTION_DIAGNOSTIC_CHARS = 200;
+const MAX_SELECT_OPTION_INPUT_CHARS = 2_000;
+const MAX_ACTION_TEXT_INPUT_CHARS = 20_000;
+const MAX_ACTION_DELAY_MS = 10_000;
 
 interface ScrollDebugMetrics {
   targetTagName: string | null;
@@ -93,6 +114,25 @@ interface ScrollDebugMetrics {
   maxScroll: number;
 }
 
+interface NormalizedClickOptions {
+  button: MouseButton;
+  clickCount: 1 | 2;
+  delayMs?: number;
+}
+
+interface NormalizedTypeOptions {
+  commitEnter: boolean;
+  delayMs?: number;
+}
+
+interface NormalizedPressOptions {
+  delayMs?: number;
+}
+
+interface NormalizedFillOptions {
+  commitChange: boolean;
+}
+
 const domEnabledSessions = new WeakSet<CDPSession>();
 const runtimeEnabledSessions = new WeakSet<CDPSession>();
 const inputEnabledSessions = new WeakSet<CDPSession>();
@@ -264,6 +304,86 @@ function ensureActionContext(ctx: CDPActionContext): void {
       "[CDP][Interactions] Action context missing element handle"
     );
   }
+  if (!ctx.element.session || typeof ctx.element.session.send !== "function") {
+    throw new Error(
+      "[CDP][Interactions] Action context missing valid CDP session"
+    );
+  }
+}
+
+function formatActionMethodDiagnostic(value: unknown): string {
+  return formatInteractionDiagnostic(value, "unknown-method");
+}
+
+function ensureActionTextInputSize(
+  value: string,
+  actionLabel: "type" | "fill"
+): string {
+  if (value.length <= MAX_ACTION_TEXT_INPUT_CHARS) {
+    return value;
+  }
+  throw new Error(
+    `[CDP][Interactions] ${actionLabel} input exceeds ${MAX_ACTION_TEXT_INPUT_CHARS} characters`
+  );
+}
+
+function readActionOptionValue(options: unknown, key: string): unknown {
+  if (!options || typeof options !== "object" || Array.isArray(options)) {
+    return undefined;
+  }
+  try {
+    return (options as Record<string, unknown>)[key];
+  } catch {
+    return undefined;
+  }
+}
+
+function normalizeActionDelayMs(value: unknown): number | undefined {
+  if (typeof value !== "number" || !Number.isFinite(value)) {
+    return undefined;
+  }
+  if (value <= 0) {
+    return undefined;
+  }
+  if (value > MAX_ACTION_DELAY_MS) {
+    throw new Error(
+      `[CDP][Interactions] delayMs exceeds ${MAX_ACTION_DELAY_MS}ms`
+    );
+  }
+  return value;
+}
+
+function normalizeClickOptions(value: unknown): NormalizedClickOptions {
+  const rawButton = readActionOptionValue(value, "button");
+  const rawClickCount = readActionOptionValue(value, "clickCount");
+  const rawDelayMs = readActionOptionValue(value, "delayMs");
+  return {
+    button:
+      rawButton === "left" || rawButton === "right" || rawButton === "middle"
+        ? rawButton
+        : "left",
+    clickCount: rawClickCount === 2 ? 2 : 1,
+    delayMs: normalizeActionDelayMs(rawDelayMs),
+  };
+}
+
+function normalizeTypeOptions(value: unknown): NormalizedTypeOptions {
+  return {
+    commitEnter: readActionOptionValue(value, "commitEnter") === true,
+    delayMs: normalizeActionDelayMs(readActionOptionValue(value, "delayMs")),
+  };
+}
+
+function normalizePressOptions(value: unknown): NormalizedPressOptions {
+  return {
+    delayMs: normalizeActionDelayMs(readActionOptionValue(value, "delayMs")),
+  };
+}
+
+function normalizeFillOptions(value: unknown): NormalizedFillOptions {
+  return {
+    commitChange: readActionOptionValue(value, "commitChange") === true,
+  };
 }
 
 export async function dispatchCDPAction(
@@ -272,31 +392,46 @@ export async function dispatchCDPAction(
   ctx: CDPActionContext
 ): Promise<void> {
   ensureActionContext(ctx);
+  if (!Array.isArray(args)) {
+    throw new Error("[CDP][Interactions] Action args must be an array");
+  }
+  if (typeof method !== "string" || method.trim().length === 0) {
+    throw new Error("[CDP][Interactions] Action method must be a non-empty string");
+  }
+  const normalizedMethod = method.trim();
 
-  switch (method) {
+  switch (normalizedMethod) {
     case "click":
-      await clickElement(ctx, args[0] as ClickOptions | undefined);
+      await clickElement(ctx, normalizeClickOptions(args[0]));
       return;
     case "doubleClick":
-      await clickElement(
-        ctx,
-        Object.assign({}, (args[0] as ClickOptions) ?? {}, { clickCount: 2 })
-      );
+      await clickElement(ctx, {
+        ...normalizeClickOptions(args[0]),
+        clickCount: 2,
+      });
       return;
     case "hover":
       await hoverElement(ctx);
       return;
     case "type":
-      await typeText(ctx, (args[0] as string) ?? "", args[1] as TypeOptions);
+      await typeText(
+        ctx,
+        ensureActionTextInputSize(coerceActionStringArg(args[0]), "type"),
+        normalizeTypeOptions(args[1])
+      );
       return;
     case "fill":
-      await fillElement(ctx, (args[0] as string) ?? "", args[1] as FillOptions);
+      await fillElement(
+        ctx,
+        ensureActionTextInputSize(coerceActionStringArg(args[0]), "fill"),
+        normalizeFillOptions(args[1])
+      );
       return;
     case "press":
       await pressKey(
         ctx,
-        (args[0] as string) ?? "Enter",
-        args[1] as PressOptions
+        coerceActionStringArg(args[0], "Enter"),
+        normalizePressOptions(args[1])
       );
       return;
     case "check":
@@ -307,7 +442,10 @@ export async function dispatchCDPAction(
       return;
     case "selectOptionFromDropdown":
       await selectOption(ctx, {
-        value: (args[0] as string) ?? "",
+        value:
+          args[0] == null
+            ? ""
+            : coerceActionStringArg(args[0], "", true),
       });
       return;
     case "scrollToElement": {
@@ -316,10 +454,7 @@ export async function dispatchCDPAction(
     }
     case "scrollToPercentage": {
       const targetArg = args[0];
-      const options =
-        typeof targetArg === "object" && !Array.isArray(targetArg)
-          ? (targetArg as ScrollToOptions)
-          : { target: targetArg as string | number };
+      const options = normalizeScrollOptions(targetArg);
       await scrollToPosition(ctx, options);
       return;
     }
@@ -328,10 +463,7 @@ export async function dispatchCDPAction(
       if (targetArg == null) {
         await scrollElementIntoView(ctx);
       } else {
-        const options =
-          typeof targetArg === "object" && !Array.isArray(targetArg)
-            ? (targetArg as ScrollToOptions)
-            : { target: targetArg as string | number };
+        const options = normalizeScrollOptions(targetArg);
         await scrollToPosition(ctx, options);
       }
       return;
@@ -344,19 +476,110 @@ export async function dispatchCDPAction(
       return;
     default:
       throw new Error(
-        `[CDP][Interactions] Unsupported action method: ${method}`
+        `[CDP][Interactions] Unsupported action method: ${formatActionMethodDiagnostic(
+          normalizedMethod
+        )}`
+      );
+  }
+}
+
+function coerceActionStringArg(
+  value: unknown,
+  fallback = "",
+  throwOnCoercionFailure = false
+): string {
+  if (value == null) {
+    return fallback;
+  }
+  if (typeof value === "string") {
+    return value;
+  }
+  try {
+    return String(value);
+  } catch {
+    if (throwOnCoercionFailure) {
+      throw new Error(
+        "[CDP][Interactions] Failed to coerce action argument to string"
       );
+    }
+    return fallback;
+  }
+}
+
+function normalizeScrollOptions(targetArg: unknown): ScrollToOptions {
+  const maxScrollTargetChars = 64;
+  const readCandidateValue = (
+    candidate: Record<string, unknown>,
+    key: "target" | "behavior"
+  ): unknown => {
+    try {
+      return candidate[key];
+    } catch {
+      return undefined;
+    }
+  };
+  const normalizeScrollTarget = (
+    value: unknown
+  ): string | number | undefined => {
+    if (typeof value === "number") {
+      if (!Number.isFinite(value)) {
+        return undefined;
+      }
+      return value;
+    }
+    if (typeof value !== "string") {
+      return undefined;
+    }
+    const normalized = stripControlChars(value).trim();
+    if (normalized.length === 0 || normalized.length > maxScrollTargetChars) {
+      return undefined;
+    }
+    return normalized;
+  };
+  const normalizeScrollBehavior = (
+    value: unknown
+  ): ScrollToOptions["behavior"] | undefined => {
+    if (typeof value !== "string") {
+      return undefined;
+    }
+    const normalized = stripControlChars(value).trim().toLowerCase();
+    if (normalized === "auto") {
+      return "instant";
+    }
+    if (normalized === "smooth" || normalized === "instant") {
+      return normalized;
+    }
+    return undefined;
+  };
+
+  if (
+    targetArg &&
+    typeof targetArg === "object" &&
+    !Array.isArray(targetArg)
+  ) {
+    const candidate = targetArg as Record<string, unknown>;
+    return {
+      target: normalizeScrollTarget(readCandidateValue(candidate, "target")),
+      behavior: normalizeScrollBehavior(
+        readCandidateValue(candidate, "behavior")
+      ),
+    };
+  }
+
+  if (typeof targetArg === "string" || typeof targetArg === "number") {
+    return { target: normalizeScrollTarget(targetArg) };
   }
+
+  return {};
 }
 
 async function clickElement(
   ctx: CDPActionContext,
-  options?: ClickOptions
+  options: NormalizedClickOptions
 ): Promise<void> {
   const { element } = ctx;
   const session = element.session;
-  const button = options?.button ?? "left";
-  const clickCount = options?.clickCount ?? 1;
+  const { button, clickCount, delayMs } = options;
 
   await scrollIntoViewIfNeeded(ctx);
   const box = await getEffectiveBoundingBox(ctx);
@@ -392,8 +615,8 @@ async function clickElement(
       button,
       clickCount,
     });
-    if (options?.delayMs) {
-      await delay(options.delayMs);
+    if (delayMs) {
+      await delay(delayMs);
     }
   }
 }
@@ -421,22 +644,22 @@ async function hoverElement(ctx: CDPActionContext): Promise<void> {
 async function typeText(
   ctx: CDPActionContext,
   text: string,
-  options?: TypeOptions
+  options: NormalizedTypeOptions
 ): Promise<void> {
-  if (!text) {
-    return;
-  }
-  const { element } = ctx;
-  const session = element.session;
+  const normalizedText = text ?? "";
+  if (normalizedText.length > 0) {
+    const { element } = ctx;
+    const session = element.session;
 
-  await focusElement(ctx);
-  await ensureInputEnabled(session);
-  await session.send("Input.insertText", { text });
+    await focusElement(ctx);
+    await ensureInputEnabled(session);
+    await session.send("Input.insertText", { text: normalizedText });
+  }
 
-  if (options?.commitEnter) {
+  if (options.commitEnter) {
     await pressKey(ctx, "Enter");
   }
-  if (options?.delayMs) {
+  if (options.delayMs) {
     await delay(options.delayMs);
   }
 }
@@ -444,7 +667,7 @@ async function typeText(
 async function fillElement(
   ctx: CDPActionContext,
   value: string,
-  options?: FillOptions
+  options: NormalizedFillOptions
 ): Promise<void> {
   const { element } = ctx;
   const session = element.session;
@@ -506,7 +729,7 @@ async function fillElement(
     }
   }
 
-  if (options?.commitChange) {
+  if (options.commitChange) {
     await session.send("Runtime.callFunctionOn", {
       objectId,
       functionDeclaration: `
@@ -523,7 +746,7 @@ async function fillElement(
 async function pressKey(
   ctx: CDPActionContext,
   key: string,
-  options?: PressOptions
+  options: NormalizedPressOptions = {}
 ): Promise<void> {
   const { element } = ctx;
   const session = element.session;
@@ -549,7 +772,7 @@ async function pressKey(
     nativeVirtualKeyCode: keyDef.nativeVirtualKeyCode,
   });
 
-  if (options?.delayMs) {
+  if (options.delayMs) {
     await delay(options.delayMs);
   }
 }
@@ -635,7 +858,7 @@ async function setChecked(
   }
 
   if (value.status === "needs_click") {
-    await clickElement(ctx);
+    await clickElement(ctx, normalizeClickOptions(undefined));
   }
 }
 
@@ -645,8 +868,19 @@ async function selectOption(
 ): Promise<void> {
   const { element } = ctx;
   const session = element.session;
+  const normalizedValue = stripControlChars(
+    String(options.value ?? "")
+  ).trim();
+  if (normalizedValue.length === 0) {
+    throw new Error("[CDP][Interactions] selectOption value must be non-empty");
+  }
+  if (normalizedValue.length > MAX_SELECT_OPTION_INPUT_CHARS) {
+    throw new Error(
+      `[CDP][Interactions] selectOption value exceeds ${MAX_SELECT_OPTION_INPUT_CHARS} characters`
+    );
+  }
+  const value = normalizedValue;
   const objectId = await ensureObjectHandle(element);
-  const value = options.value;
 
   await ensureRuntimeEnabled(session);
   const result = await session.send<Protocol.Runtime.CallFunctionOnResponse>(
@@ -713,7 +947,17 @@ async function selectOption(
 
   const selection = (result.result?.value ?? {}) as SelectOptionResult;
   if (selection.status !== "selected") {
-    throw new Error(`Failed to select "${value}" (no matching option)`);
+    const normalizedValue = stripControlChars(String(value ?? "")).trim();
+    const boundedValue =
+      normalizedValue.length <= MAX_INTERACTION_DIAGNOSTIC_CHARS
+        ? normalizedValue
+        : `${normalizedValue.slice(
+            0,
+            MAX_INTERACTION_DIAGNOSTIC_CHARS
+          )}... [truncated ${
+            normalizedValue.length - MAX_INTERACTION_DIAGNOSTIC_CHARS
+          } chars]`;
+    throw new Error(`Failed to select "${boundedValue}" (no matching option)`);
   }
 }
 
@@ -891,19 +1135,25 @@ async function scrollElementIntoView(ctx: CDPActionContext): Promise<void> {
     await session.send("DOM.scrollIntoViewIfNeeded", {
       backendNodeId: element.backendNodeId,
     });
-  } catch {
-    const objectId = await ensureObjectHandle(element);
-    await ensureRuntimeEnabled(session);
-    await session.send("Runtime.callFunctionOn", {
-      objectId,
-      functionDeclaration: `
-        function() {
-          if (typeof this.scrollIntoView === "function") {
-            this.scrollIntoView({ behavior: "auto", block: "center" });
+  } catch (primaryError) {
+    try {
+      const objectId = await ensureObjectHandle(element);
+      await ensureRuntimeEnabled(session);
+      await session.send("Runtime.callFunctionOn", {
+        objectId,
+        functionDeclaration: `
+          function() {
+            if (typeof this.scrollIntoView === "function") {
+              this.scrollIntoView({ behavior: "auto", block: "center" });
+            }
           }
-        }
-      `,
-    });
+        `,
+      });
+    } catch (fallbackError) {
+      throw new Error(
+        createScrollIntoViewFailureMessage(primaryError, fallbackError)
+      );
+    }
   }
   await waitForScrollSettlement(session, element.backendNodeId);
 }
@@ -983,9 +1233,7 @@ async function scrollIntoViewIfNeeded(ctx: CDPActionContext): Promise<void> {
     } catch (fallbackError) {
       // Re-throw with context about both failures
       throw new Error(
-        `[CDP][Interactions] Failed to scroll element into view. ` +
-          `Primary method failed: ${primaryError instanceof Error ? primaryError.message : String(primaryError)}. ` +
-          `Fallback also failed: ${fallbackError instanceof Error ? fallbackError.message : String(fallbackError)}`
+        createScrollIntoViewFailureMessage(primaryError, fallbackError)
       );
     }
   }
@@ -1181,16 +1429,41 @@ function formatScrollNumber(value: number): string {
   return value.toFixed(2);
 }
 
-function normalizeScrollPercent(target: string | number): number {
+function stripControlChars(value: string): string {
+  return Array.from(value)
+    .filter((char) => {
+      const code = char.charCodeAt(0);
+      return code > 31 && code !== 127;
+    })
+    .join("");
+}
+
+function normalizeScrollPercent(target: unknown): number {
+  const maxScrollTargetChars = 64;
   if (typeof target === "number") {
+    if (!Number.isFinite(target)) {
+      return 50;
+    }
     return clamp(target, 0, 100);
   }
-  const text = target.trim();
+  if (typeof target !== "string") {
+    return 50;
+  }
+  const text = stripControlChars(target).trim();
+  if (text.length === 0 || text.length > maxScrollTargetChars) {
+    return 50;
+  }
   if (text.endsWith("%")) {
     const parsed = Number.parseFloat(text.slice(0, -1));
+    if (!Number.isFinite(parsed)) {
+      return 50;
+    }
     return clamp(Number.isNaN(parsed) ? 50 : parsed, 0, 100);
   }
   const num = Number.parseFloat(text);
+  if (!Number.isFinite(num)) {
+    return 50;
+  }
   return clamp(Number.isNaN(num) ? 50 : num, 0, 100);
 }
 
@@ -1201,29 +1474,42 @@ interface KeyEventData {
   windowsVirtualKeyCode: number;
   nativeVirtualKeyCode: number;
 }
+const MAX_KEY_EVENT_INPUT_CHARS = 64;
 
 function getKeyEventData(inputKey: string): KeyEventData {
-  const key = (inputKey ?? "").toString();
+  const sanitizedKey = stripControlChars((inputKey ?? "").toString()).trim();
+  const normalizedKey = sanitizedKey.length === 0 ? "Enter" : sanitizedKey;
+  const key = normalizedKey.slice(0, MAX_KEY_EVENT_INPUT_CHARS);
   const lower = key.toLowerCase();
+  const lookupKey = lower.replace(/[\s_-]+/g, "");
   const mapping: Record<
     string,
     { key: string; code: string; keyCode: number; text?: string }
   > = {
     enter: { key: "Enter", code: "Enter", keyCode: 13 },
+    return: { key: "Enter", code: "Enter", keyCode: 13 },
     tab: { key: "Tab", code: "Tab", keyCode: 9 },
     escape: { key: "Escape", code: "Escape", keyCode: 27 },
     esc: { key: "Escape", code: "Escape", keyCode: 27 },
     space: { key: " ", code: "Space", keyCode: 32, text: " " },
+    spacebar: { key: " ", code: "Space", keyCode: 32, text: " " },
     backspace: { key: "Backspace", code: "Backspace", keyCode: 8 },
     delete: { key: "Delete", code: "Delete", keyCode: 46 },
     arrowup: { key: "ArrowUp", code: "ArrowUp", keyCode: 38 },
     arrowdown: { key: "ArrowDown", code: "ArrowDown", keyCode: 40 },
     arrowleft: { key: "ArrowLeft", code: "ArrowLeft", keyCode: 37 },
     arrowright: { key: "ArrowRight", code: "ArrowRight", keyCode: 39 },
+    pageup: { key: "PageUp", code: "PageUp", keyCode: 33 },
+    pagedown: { key: "PageDown", code: "PageDown", keyCode: 34 },
+    pgup: { key: "PageUp", code: "PageUp", keyCode: 33 },
+    pgdn: { key: "PageDown", code: "PageDown", keyCode: 34 },
+    pagedn: { key: "PageDown", code: "PageDown", keyCode: 34 },
+    home: { key: "Home", code: "Home", keyCode: 36 },
+    end: { key: "End", code: "End", keyCode: 35 },
   };
 
-  if (mapping[lower]) {
-    const entry = mapping[lower];
+  if (mapping[lookupKey]) {
+    const entry = mapping[lookupKey];
     return {
       key: entry.key,
       code: entry.code,
diff --git a/src/cdp/playwright-adapter.test.ts b/src/cdp/playwright-adapter.test.ts
new file mode 100644
index 00000000..dbc90a21
--- /dev/null
+++ b/src/cdp/playwright-adapter.test.ts
@@ -0,0 +1,524 @@
+import type { CDPSession as PlaywrightSession, Page } from "playwright-core";
+import {
+  disposeAllCDPClients,
+  disposeCDPClientForPage,
+  getCDPClientForPage,
+} from "@/cdp/playwright-adapter";
+
+jest.mock("@/debug/options", () => ({
+  getDebugOptions: jest.fn(() => ({
+    enabled: false,
+    cdpSessions: false,
+  })),
+}));
+
+const { getDebugOptions } = jest.requireMock("@/debug/options") as {
+  getDebugOptions: jest.Mock;
+};
+
+describe("playwright adapter error formatting", () => {
+  afterEach(async () => {
+    await disposeAllCDPClients();
+    jest.restoreAllMocks();
+  });
+
+  it("formats non-Error session detach failures", async () => {
+    const warnSpy = jest.spyOn(console, "warn").mockImplementation(() => {});
+    const session = {
+      send: jest.fn().mockResolvedValue({}),
+      on: jest.fn(),
+      off: jest.fn(),
+      detach: jest.fn().mockRejectedValue({ reason: "detach object failure" }),
+    } as unknown as PlaywrightSession;
+    const page = {
+      context: () => ({
+        newCDPSession: jest.fn().mockResolvedValue(session),
+      }),
+      once: jest.fn(),
+    } as unknown as Page;
+
+    await getCDPClientForPage(page);
+    await disposeCDPClientForPage(page);
+
+    expect(warnSpy).toHaveBeenCalledWith(
+      '[CDP][PlaywrightAdapter] Failed to detach session: {"reason":"detach object failure"}'
+    );
+  });
+
+  it("sanitizes and truncates oversized detach diagnostics", async () => {
+    const warnSpy = jest.spyOn(console, "warn").mockImplementation(() => {});
+    const noisyFailure = `detach\u0000\n${"x".repeat(10_000)}`;
+    const session = {
+      send: jest.fn().mockResolvedValue({}),
+      on: jest.fn(),
+      off: jest.fn(),
+      detach: jest.fn().mockRejectedValue(new Error(noisyFailure)),
+    } as unknown as PlaywrightSession;
+    const page = {
+      context: () => ({
+        newCDPSession: jest.fn().mockResolvedValue(session),
+      }),
+      once: jest.fn(),
+    } as unknown as Page;
+
+    await getCDPClientForPage(page);
+    await disposeCDPClientForPage(page);
+
+    const detachWarning = warnSpy.mock.calls
+      .map((call) => String(call[0]))
+      .find((line) => line.includes("Failed to detach session"));
+    expect(detachWarning).toBeDefined();
+    expect(detachWarning).toContain("[truncated");
+    expect(detachWarning).not.toContain("\u0000");
+    expect(detachWarning).not.toContain("\n");
+    expect(detachWarning?.length ?? 0).toBeLessThan(700);
+  });
+
+  it("surfaces sanitized diagnostics when session.detach getter traps", async () => {
+    const warnSpy = jest.spyOn(console, "warn").mockImplementation(() => {});
+    const session = {
+      send: jest.fn().mockResolvedValue({}),
+      on: jest.fn(),
+      off: jest.fn(),
+      get detach() {
+        throw new Error(`detach getter trap\u0000\n${"x".repeat(10_000)}`);
+      },
+    } as unknown as PlaywrightSession;
+    const page = {
+      context: () => ({
+        newCDPSession: jest.fn().mockResolvedValue(session),
+      }),
+      once: jest.fn(),
+    } as unknown as Page;
+
+    await getCDPClientForPage(page);
+    await disposeCDPClientForPage(page);
+
+    const detachWarning = warnSpy.mock.calls
+      .map((call) => String(call[0]))
+      .find((line) => line.includes("Failed to detach session"));
+    expect(detachWarning).toBeDefined();
+    expect(detachWarning).toContain("Failed to read session.detach");
+    expect(detachWarning).toContain("[truncated");
+    expect(detachWarning).not.toContain("\u0000");
+    expect(detachWarning).not.toContain("\n");
+  });
+
+  it("surfaces explicit diagnostics when session.detach is unavailable", async () => {
+    const warnSpy = jest.spyOn(console, "warn").mockImplementation(() => {});
+    const session = {
+      send: jest.fn().mockResolvedValue({}),
+      on: jest.fn(),
+      off: jest.fn(),
+    } as unknown as PlaywrightSession;
+    const page = {
+      context: () => ({
+        newCDPSession: jest.fn().mockResolvedValue(session),
+      }),
+      once: jest.fn(),
+    } as unknown as Page;
+
+    await getCDPClientForPage(page);
+    await disposeCDPClientForPage(page);
+
+    expect(warnSpy).toHaveBeenCalledWith(
+      "[CDP][PlaywrightAdapter] Failed to detach session: [CDP][PlaywrightAdapter] session.detach is unavailable"
+    );
+  });
+
+  it("continues disposing sessions when debug-options lookup traps", async () => {
+    const warnSpy = jest.spyOn(console, "warn").mockImplementation(() => {});
+    const session = {
+      send: jest.fn().mockResolvedValue({}),
+      on: jest.fn(),
+      off: jest.fn(),
+      detach: jest.fn().mockResolvedValue(undefined),
+    } as unknown as PlaywrightSession;
+    const page = {
+      context: () => ({
+        newCDPSession: jest.fn().mockResolvedValue(session),
+      }),
+      once: jest.fn(),
+    } as unknown as Page;
+    getDebugOptions.mockImplementationOnce(() => {
+      throw new Error(`debug\u0000\n${"x".repeat(2_000)}`);
+    });
+
+    try {
+      const client = await getCDPClientForPage(page);
+      await client.acquireSession("lifecycle");
+      await disposeCDPClientForPage(page);
+
+      const warning = String(
+        warnSpy.mock.calls.find((call) =>
+          String(call[0] ?? "").includes("Failed to read debug options")
+        )?.[0] ?? ""
+      );
+      expect(warning).toContain("[truncated");
+      expect(warning).not.toContain("\u0000");
+      expect(warning).not.toContain("\n");
+    } finally {
+      warnSpy.mockRestore();
+    }
+  });
+
+  it("surfaces sanitized diagnostics when page context traps during init", async () => {
+    const page = {
+      context: () => {
+        throw new Error(`context\u0000\n${"x".repeat(2_000)}`);
+      },
+      once: jest.fn(),
+    } as unknown as Page;
+
+    await expect(getCDPClientForPage(page)).rejects.toThrow(
+      "[CDP][PlaywrightAdapter] Failed to create CDP session"
+    );
+
+    await expect(getCDPClientForPage(page)).rejects.toThrow("[truncated");
+  });
+
+  it("clears pending init promise after context-init failure", async () => {
+    const session = {
+      send: jest.fn().mockResolvedValue({}),
+      on: jest.fn(),
+      off: jest.fn(),
+      detach: jest.fn().mockResolvedValue(undefined),
+    } as unknown as PlaywrightSession;
+
+    const context = jest
+      .fn<unknown, []>()
+      .mockImplementationOnce(() => {
+        throw new Error("first init failure");
+      })
+      .mockImplementation(() => ({
+        newCDPSession: jest.fn().mockResolvedValue(session),
+      }));
+
+    const page = {
+      context,
+      once: jest.fn(),
+    } as unknown as Page;
+
+    await expect(getCDPClientForPage(page)).rejects.toThrow(
+      "first init failure"
+    );
+    await expect(getCDPClientForPage(page)).resolves.toBeDefined();
+    expect(context).toHaveBeenCalledTimes(2);
+  });
+
+  it("warns and continues when close-listener attachment traps", async () => {
+    const warnSpy = jest.spyOn(console, "warn").mockImplementation(() => {});
+    const session = {
+      send: jest.fn().mockResolvedValue({}),
+      on: jest.fn(),
+      off: jest.fn(),
+      detach: jest.fn().mockResolvedValue(undefined),
+    } as unknown as PlaywrightSession;
+
+    const page = {
+      context: () => ({
+        newCDPSession: jest.fn().mockResolvedValue(session),
+      }),
+      get once() {
+        throw new Error(`close-listener\u0000\n${"x".repeat(2_000)}`);
+      },
+    } as unknown as Page;
+
+    try {
+      await expect(getCDPClientForPage(page)).resolves.toBeDefined();
+      const warning = String(
+        warnSpy.mock.calls.find((call) =>
+          String(call[0] ?? "").includes("Failed to attach page close listener")
+        )?.[0] ?? ""
+      );
+      expect(warning).toContain("[truncated");
+      expect(warning).not.toContain("\u0000");
+      expect(warning).not.toContain("\n");
+    } finally {
+      warnSpy.mockRestore();
+    }
+  });
+
+  it("creates CDP sessions with the browser-context receiver", async () => {
+    const session = {
+      send: jest.fn().mockResolvedValue({}),
+      on: jest.fn(),
+      off: jest.fn(),
+      detach: jest.fn().mockResolvedValue(undefined),
+    } as unknown as PlaywrightSession;
+    const context = {
+      newCDPSession: jest.fn(function (this: unknown, target: unknown) {
+        if (this !== context) {
+          throw new Error("invalid context receiver");
+        }
+        void target;
+        return Promise.resolve(session);
+      }),
+    };
+    const page = {
+      context: () => context,
+      once: jest.fn(),
+    } as unknown as Page;
+
+    const client = await getCDPClientForPage(page);
+    await expect(client.acquireSession("lifecycle")).resolves.toBeDefined();
+    expect(context.newCDPSession).toHaveBeenCalled();
+  });
+
+  it("continues pooled session creation when detach-listener attach traps", async () => {
+    const warnSpy = jest.spyOn(console, "warn").mockImplementation(() => {});
+    const session = {
+      send: jest.fn().mockResolvedValue({}),
+      get on() {
+        throw new Error(`listener-on\u0000\n${"x".repeat(2_000)}`);
+      },
+      off: jest.fn(),
+      detach: jest.fn().mockResolvedValue(undefined),
+    } as unknown as PlaywrightSession;
+    const page = {
+      context: () => ({
+        newCDPSession: jest.fn().mockResolvedValue(session),
+      }),
+      once: jest.fn(),
+    } as unknown as Page;
+
+    try {
+      const client = await getCDPClientForPage(page);
+      await expect(client.acquireSession("lifecycle")).resolves.toBeDefined();
+
+      const warning = String(
+        warnSpy.mock.calls.find((call) =>
+          String(call[0] ?? "").includes("Failed to attach pooled lifecycle")
+        )?.[0] ?? ""
+      );
+      expect(warning).toContain("[truncated");
+      expect(warning).not.toContain("\u0000");
+      expect(warning).not.toContain("\n");
+    } finally {
+      warnSpy.mockRestore();
+    }
+  });
+
+  it("continues disposal when pooled listener cleanup traps", async () => {
+    const warnSpy = jest.spyOn(console, "warn").mockImplementation(() => {});
+    const session = {
+      send: jest.fn().mockResolvedValue({}),
+      on: jest.fn(),
+      get off() {
+        throw new Error(`listener-off\u0000\n${"x".repeat(2_000)}`);
+      },
+      detach: jest.fn().mockResolvedValue(undefined),
+    } as unknown as PlaywrightSession;
+    const page = {
+      context: () => ({
+        newCDPSession: jest.fn().mockResolvedValue(session),
+      }),
+      once: jest.fn(),
+    } as unknown as Page;
+
+    try {
+      const client = await getCDPClientForPage(page);
+      await expect(client.acquireSession("lifecycle")).resolves.toBeDefined();
+      await expect(disposeCDPClientForPage(page)).resolves.toBeUndefined();
+
+      const warning = String(
+        warnSpy.mock.calls.find((call) =>
+          String(call[0] ?? "").includes("Failed to detach pooled lifecycle listener")
+        )?.[0] ?? ""
+      );
+      expect(warning).toContain("[truncated");
+      expect(warning).not.toContain("\u0000");
+      expect(warning).not.toContain("\n");
+    } finally {
+      warnSpy.mockRestore();
+    }
+  });
+
+  it("surfaces sanitized diagnostics when session.send getter traps", async () => {
+    const trappedSession = new Proxy(
+      {
+        on: jest.fn(),
+        off: jest.fn(),
+        detach: jest.fn().mockResolvedValue(undefined),
+      },
+      {
+        get: (target, prop, receiver) => {
+          if (prop === "send") {
+            throw new Error(`send\u0000\n${"x".repeat(2_000)}`);
+          }
+          return Reflect.get(target, prop, receiver);
+        },
+      }
+    ) as unknown as PlaywrightSession;
+    const page = {
+      context: () => ({
+        newCDPSession: jest.fn().mockResolvedValue(trappedSession),
+      }),
+      once: jest.fn(),
+    } as unknown as Page;
+
+    const client = await getCDPClientForPage(page);
+    const pooled = await client.acquireSession("lifecycle");
+
+    await expect(pooled.send("Runtime.enable")).rejects.toThrow(
+      "[CDP][PlaywrightAdapter] Failed to read session.send"
+    );
+    await expect(pooled.send("Runtime.enable")).rejects.toThrow("[truncated");
+  });
+
+  it("surfaces sanitized diagnostics when session.on getter traps", async () => {
+    const warnSpy = jest.spyOn(console, "warn").mockImplementation(() => {});
+    const trappedSession = new Proxy(
+      {
+        send: jest.fn().mockResolvedValue({}),
+        off: jest.fn(),
+        detach: jest.fn().mockResolvedValue(undefined),
+      },
+      {
+        get: (target, prop, receiver) => {
+          if (prop === "on") {
+            throw new Error(`on\u0000\n${"x".repeat(2_000)}`);
+          }
+          return Reflect.get(target, prop, receiver);
+        },
+      }
+    ) as unknown as PlaywrightSession;
+    const page = {
+      context: () => ({
+        newCDPSession: jest.fn().mockResolvedValue(trappedSession),
+      }),
+      once: jest.fn(),
+    } as unknown as Page;
+
+    const client = await getCDPClientForPage(page);
+    const pooled = await client.acquireSession("lifecycle");
+    const pooledWithOn = pooled as typeof pooled & {
+      on: NonNullable<typeof pooled.on>;
+    };
+
+    try {
+      expect(() => pooledWithOn.on("Detached", () => undefined)).toThrow(
+        "[CDP][PlaywrightAdapter] Failed to read session.on"
+      );
+      expect(() => pooledWithOn.on("Detached", () => undefined)).toThrow(
+        "[truncated"
+      );
+    } finally {
+      warnSpy.mockRestore();
+    }
+  });
+
+  it("surfaces sanitized diagnostics when session.off getter traps", async () => {
+    const warnSpy = jest.spyOn(console, "warn").mockImplementation(() => {});
+    const trappedSession = new Proxy(
+      {
+        send: jest.fn().mockResolvedValue({}),
+        on: jest.fn(),
+        detach: jest.fn().mockResolvedValue(undefined),
+      },
+      {
+        get: (target, prop, receiver) => {
+          if (prop === "off") {
+            throw new Error(`off\u0000\n${"x".repeat(2_000)}`);
+          }
+          return Reflect.get(target, prop, receiver);
+        },
+      }
+    ) as unknown as PlaywrightSession;
+    const page = {
+      context: () => ({
+        newCDPSession: jest.fn().mockResolvedValue(trappedSession),
+      }),
+      once: jest.fn(),
+    } as unknown as Page;
+
+    const client = await getCDPClientForPage(page);
+    const pooled = await client.acquireSession("lifecycle");
+    const pooledWithOff = pooled as typeof pooled & {
+      off: NonNullable<typeof pooled.off>;
+    };
+
+    try {
+      expect(() => pooledWithOff.off("Detached", () => undefined)).toThrow(
+        "[CDP][PlaywrightAdapter] Failed to read session.off"
+      );
+      expect(() => pooledWithOff.off("Detached", () => undefined)).toThrow(
+        "[truncated"
+      );
+      await disposeCDPClientForPage(page);
+    } finally {
+      warnSpy.mockRestore();
+    }
+  });
+
+  it("surfaces sanitized diagnostics when session.on listener registration throws", async () => {
+    const warnSpy = jest.spyOn(console, "warn").mockImplementation(() => {});
+    const trappedSession = {
+      send: jest.fn().mockResolvedValue({}),
+      on: () => {
+        throw new Error(`on-call\u0000\n${"x".repeat(2_000)}`);
+      },
+      off: jest.fn(),
+      detach: jest.fn().mockResolvedValue(undefined),
+    } as unknown as PlaywrightSession;
+    const page = {
+      context: () => ({
+        newCDPSession: jest.fn().mockResolvedValue(trappedSession),
+      }),
+      once: jest.fn(),
+    } as unknown as Page;
+
+    const client = await getCDPClientForPage(page);
+    const pooled = await client.acquireSession("lifecycle");
+    const pooledWithOn = pooled as typeof pooled & {
+      on: NonNullable<typeof pooled.on>;
+    };
+
+    try {
+      expect(() => pooledWithOn.on("Detached", () => undefined)).toThrow(
+        "[CDP][PlaywrightAdapter] Failed to register listener (Detached)"
+      );
+      expect(() => pooledWithOn.on("Detached", () => undefined)).toThrow(
+        "[truncated"
+      );
+    } finally {
+      warnSpy.mockRestore();
+    }
+  });
+
+  it("surfaces sanitized diagnostics when session.off listener removal throws", async () => {
+    const warnSpy = jest.spyOn(console, "warn").mockImplementation(() => {});
+    const trappedSession = {
+      send: jest.fn().mockResolvedValue({}),
+      on: jest.fn(),
+      off: () => {
+        throw new Error(`off-call\u0000\n${"x".repeat(2_000)}`);
+      },
+      detach: jest.fn().mockResolvedValue(undefined),
+    } as unknown as PlaywrightSession;
+    const page = {
+      context: () => ({
+        newCDPSession: jest.fn().mockResolvedValue(trappedSession),
+      }),
+      once: jest.fn(),
+    } as unknown as Page;
+
+    const client = await getCDPClientForPage(page);
+    const pooled = await client.acquireSession("lifecycle");
+    const pooledWithOff = pooled as typeof pooled & {
+      off: NonNullable<typeof pooled.off>;
+    };
+
+    try {
+      expect(() => pooledWithOff.off("Detached", () => undefined)).toThrow(
+        "[CDP][PlaywrightAdapter] Failed to remove listener (Detached)"
+      );
+      expect(() => pooledWithOff.off("Detached", () => undefined)).toThrow(
+        "[truncated"
+      );
+      await disposeCDPClientForPage(page);
+    } finally {
+      warnSpy.mockRestore();
+    }
+  });
+});
diff --git a/src/cdp/playwright-adapter.ts b/src/cdp/playwright-adapter.ts
index 5bad2621..0851c9a1 100644
--- a/src/cdp/playwright-adapter.ts
+++ b/src/cdp/playwright-adapter.ts
@@ -5,8 +5,38 @@ import type {
   CDPSessionKind,
 } from "@/cdp/types";
 import { getDebugOptions } from "@/debug/options";
+import { formatUnknownError } from "@/utils";
 import type { CDPSession as PlaywrightSession, Frame, Page } from "playwright-core";
 
+const MAX_PLAYWRIGHT_ADAPTER_DIAGNOSTIC_CHARS = 400;
+
+function sanitizePlaywrightAdapterDiagnostic(value: string): string {
+  if (value.length === 0) {
+    return value;
+  }
+  const withoutControlChars = Array.from(value, (char) => {
+    const code = char.charCodeAt(0);
+    return (code >= 0 && code < 32) || code === 127 ? " " : char;
+  }).join("");
+  return withoutControlChars.replace(/\s+/g, " ").trim();
+}
+
+function truncatePlaywrightAdapterDiagnostic(value: string): string {
+  if (value.length <= MAX_PLAYWRIGHT_ADAPTER_DIAGNOSTIC_CHARS) {
+    return value;
+  }
+  const omitted = value.length - MAX_PLAYWRIGHT_ADAPTER_DIAGNOSTIC_CHARS;
+  return `${value.slice(0, MAX_PLAYWRIGHT_ADAPTER_DIAGNOSTIC_CHARS)}... [truncated ${omitted} chars]`;
+}
+
+function formatPlaywrightAdapterDiagnostic(value: unknown): string {
+  const normalized = sanitizePlaywrightAdapterDiagnostic(formatUnknownError(value));
+  if (normalized.length === 0) {
+    return "unknown error";
+  }
+  return truncatePlaywrightAdapterDiagnostic(normalized);
+}
+
 class PlaywrightSessionAdapter implements CDPSession {
   readonly raw: PlaywrightSession;
   readonly id: string | null;
@@ -19,47 +49,148 @@ class PlaywrightSessionAdapter implements CDPSession {
     this.id = extractSessionId(session);
   }
 
-  // eslint-disable-next-line @typescript-eslint/no-explicit-any
-  async send<T = any>(
+  async send<T = unknown>(
     method: string,
     params?: Record<string, unknown>
   ): Promise<T> {
-    const result = (this.session.send as PlaywrightSession["send"])(
-      // eslint-disable-next-line @typescript-eslint/no-explicit-any
-      method as any,
-      // eslint-disable-next-line @typescript-eslint/no-explicit-any
-      params as any
-    );
+    type SendMethod = Parameters<PlaywrightSession["send"]>[0];
+    type SendParams = Parameters<PlaywrightSession["send"]>[1];
+    let sendMethod: unknown;
+    try {
+      sendMethod = (this.session as PlaywrightSession & { send?: unknown }).send;
+    } catch (error) {
+      throw new Error(
+        `[CDP][PlaywrightAdapter] Failed to read session.send: ${formatPlaywrightAdapterDiagnostic(
+          error
+        )}`
+      );
+    }
+    if (typeof sendMethod !== "function") {
+      throw new Error("[CDP][PlaywrightAdapter] session.send is unavailable");
+    }
+
+    let result: unknown;
+    try {
+      result = (
+        sendMethod as (
+          this: PlaywrightSession,
+          method: SendMethod,
+          params?: SendParams
+        ) => Promise<unknown>
+      ).call(this.session, method as SendMethod, params as SendParams);
+    } catch (error) {
+      throw new Error(
+        `[CDP][PlaywrightAdapter] Failed to send CDP command (${method}): ${formatPlaywrightAdapterDiagnostic(
+          error
+        )}`
+      );
+    }
+
     return result as Promise<T>;
   }
 
-  // eslint-disable-next-line @typescript-eslint/no-explicit-any
-  on(event: string, handler: (...payload: any[]) => void): void {
-    this.session.on(
-      event as Parameters<PlaywrightSession["on"]>[0],
-      handler as Parameters<PlaywrightSession["on"]>[1]
-    );
+  on<TPayload extends unknown[]>(
+    event: string,
+    handler: (...payload: TPayload) => void
+  ): void {
+    let onMethod: unknown;
+    try {
+      onMethod = (this.session as PlaywrightSession & { on?: unknown }).on;
+    } catch (error) {
+      throw new Error(
+        `[CDP][PlaywrightAdapter] Failed to read session.on: ${formatPlaywrightAdapterDiagnostic(
+          error
+        )}`
+      );
+    }
+    if (typeof onMethod !== "function") {
+      throw new Error("[CDP][PlaywrightAdapter] session.on is unavailable");
+    }
+    try {
+      (
+        onMethod as (
+          this: PlaywrightSession,
+          event: Parameters<PlaywrightSession["on"]>[0],
+          handler: Parameters<PlaywrightSession["on"]>[1]
+        ) => void
+      ).call(
+        this.session,
+        event as Parameters<PlaywrightSession["on"]>[0],
+        handler as unknown as Parameters<PlaywrightSession["on"]>[1]
+      );
+    } catch (error) {
+      throw new Error(
+        `[CDP][PlaywrightAdapter] Failed to register listener (${event}): ${formatPlaywrightAdapterDiagnostic(
+          error
+        )}`
+      );
+    }
   }
 
-  // eslint-disable-next-line @typescript-eslint/no-explicit-any
-  off(event: string, handler: (...payload: any[]) => void): void {
-    const off = (this.session as PlaywrightSession & {
-      off?: PlaywrightSession["off"];
-    }).off;
-    if (off) {
-      off.call(
+  off<TPayload extends unknown[]>(
+    event: string,
+    handler: (...payload: TPayload) => void
+  ): void {
+    let offMethod: unknown;
+    try {
+      offMethod = (this.session as PlaywrightSession & { off?: unknown }).off;
+    } catch (error) {
+      throw new Error(
+        `[CDP][PlaywrightAdapter] Failed to read session.off: ${formatPlaywrightAdapterDiagnostic(
+          error
+        )}`
+      );
+    }
+    if (typeof offMethod !== "function") {
+      return;
+    }
+    try {
+      (
+        offMethod as (
+          this: PlaywrightSession,
+          event: Parameters<PlaywrightSession["off"]>[0],
+          handler: Parameters<PlaywrightSession["off"]>[1]
+        ) => void
+      ).call(
         this.session,
         event as Parameters<PlaywrightSession["off"]>[0],
-        handler as Parameters<PlaywrightSession["off"]>[1]
+        handler as unknown as Parameters<PlaywrightSession["off"]>[1]
+      );
+    } catch (error) {
+      throw new Error(
+        `[CDP][PlaywrightAdapter] Failed to remove listener (${event}): ${formatPlaywrightAdapterDiagnostic(
+          error
+        )}`
       );
     }
   }
 
   async detach(): Promise<void> {
     try {
-      await this.session.detach();
+      let detachMethod: unknown;
+      try {
+        detachMethod = (this.session as PlaywrightSession & { detach?: unknown })
+          .detach;
+      } catch (error) {
+        throw new Error(
+          `[CDP][PlaywrightAdapter] Failed to read session.detach: ${formatPlaywrightAdapterDiagnostic(
+            error
+          )}`
+        );
+      }
+      if (typeof detachMethod !== "function") {
+        throw new Error("[CDP][PlaywrightAdapter] session.detach is unavailable");
+      }
+
+      await (
+        detachMethod as (this: PlaywrightSession) => Promise<unknown>
+      ).call(this.session);
     } catch (error) {
-      console.warn("[CDP][PlaywrightAdapter] Failed to detach session:", error);
+      console.warn(
+        `[CDP][PlaywrightAdapter] Failed to detach session: ${formatPlaywrightAdapterDiagnostic(
+          error
+        )}`
+      );
     } finally {
       this.release(this);
     }
@@ -84,8 +215,17 @@ class PlaywrightCDPClient implements CDPClient {
   constructor(private readonly page: Page) {}
 
   private get sessionLogging(): boolean {
-    const opts = getDebugOptions();
-    return !!(opts.enabled && opts.cdpSessions);
+    try {
+      const opts = getDebugOptions();
+      return !!(opts.enabled && opts.cdpSessions);
+    } catch (error) {
+      console.warn(
+        `[CDP][PlaywrightAdapter] Failed to read debug options: ${formatPlaywrightAdapterDiagnostic(
+          error
+        )}`
+      );
+      return false;
+    }
   }
 
   get rootSession(): CDPSession {
@@ -113,7 +253,55 @@ class PlaywrightCDPClient implements CDPClient {
 
   async createSession(descriptor?: CDPTargetDescriptor): Promise<CDPSession> {
     const target = this.resolveTarget(descriptor);
-    const session = await this.page.context().newCDPSession(target);
+    let pageContext: unknown;
+    try {
+      pageContext = this.page.context();
+    } catch (error) {
+      throw new Error(
+        `[CDP][PlaywrightAdapter] Failed to create CDP session: ${formatPlaywrightAdapterDiagnostic(
+          error
+        )}`
+      );
+    }
+    if (!pageContext || typeof pageContext !== "object") {
+      throw new Error(
+        "[CDP][PlaywrightAdapter] Failed to create CDP session: page context unavailable"
+      );
+    }
+
+    let newCDPSessionMethod: unknown;
+    try {
+      newCDPSessionMethod = (
+        pageContext as { newCDPSession?: unknown }
+      ).newCDPSession;
+    } catch (error) {
+      throw new Error(
+        `[CDP][PlaywrightAdapter] Failed to create CDP session: ${formatPlaywrightAdapterDiagnostic(
+          error
+        )}`
+      );
+    }
+    if (typeof newCDPSessionMethod !== "function") {
+      throw new Error(
+        "[CDP][PlaywrightAdapter] Failed to create CDP session: newCDPSession() unavailable"
+      );
+    }
+
+    let session: PlaywrightSession;
+    try {
+      session = (await (
+        newCDPSessionMethod as (
+          this: object,
+          targetArg: Page | Frame
+        ) => Promise<PlaywrightSession>
+      ).call(pageContext as object, target)) as PlaywrightSession;
+    } catch (error) {
+      throw new Error(
+        `[CDP][PlaywrightAdapter] Failed to create CDP session: ${formatPlaywrightAdapterDiagnostic(
+          error
+        )}`
+      );
+    }
     const wrapped = new PlaywrightSessionAdapter(session, (adapter) =>
       this.trackedSessions.delete(adapter)
     );
@@ -149,17 +337,22 @@ class PlaywrightCDPClient implements CDPClient {
   }
 
   async dispose(): Promise<void> {
-    this.sessionPoolCleanup.forEach((cleanup) => cleanup());
+    this.sessionPoolCleanup.forEach((cleanup) => {
+      try {
+        cleanup();
+      } catch (error) {
+        console.warn(
+          `[CDP][PlaywrightAdapter] Failed to run session cleanup: ${formatPlaywrightAdapterDiagnostic(
+            error
+          )}`
+        );
+      }
+    });
     this.sessionPoolCleanup.clear();
     this.sessionPool.clear();
 
     const detachPromises = Array.from(this.trackedSessions).map((session) =>
-      session.detach().catch((error) => {
-        console.warn(
-          "[CDP][PlaywrightAdapter] Failed to detach cached session:",
-          error
-        );
-      })
+      session.detach()
     );
     await Promise.all(detachPromises);
     this.trackedSessions.clear();
@@ -174,7 +367,7 @@ class PlaywrightCDPClient implements CDPClient {
     );
 
     const cleanup = (): void => {
-      session.off?.("Detached", onDetached);
+      this.detachPooledSessionListener(kind, session, onDetached);
       this.sessionPoolCleanup.delete(kind);
       this.sessionPool.delete(kind);
     };
@@ -186,13 +379,85 @@ class PlaywrightCDPClient implements CDPClient {
       cleanup();
     };
 
-    session.on?.("Detached", onDetached);
+    this.attachPooledSessionListener(kind, session, onDetached);
     this.sessionPoolCleanup.set(kind, cleanup);
 
     await this.initializeSessionForKind(kind, session);
     return session;
   }
 
+  private attachPooledSessionListener(
+    kind: CDPSessionKind,
+    session: CDPSession,
+    listener: () => void
+  ): void {
+    let onMethod: unknown;
+    try {
+      onMethod = (session as CDPSession & { on?: unknown }).on;
+    } catch (error) {
+      console.warn(
+        `[CDP][PlaywrightAdapter] Failed to read pooled ${kind} listener method: ${formatPlaywrightAdapterDiagnostic(
+          error
+        )}`
+      );
+      return;
+    }
+    if (typeof onMethod !== "function") {
+      return;
+    }
+    try {
+      (
+        onMethod as (
+          this: CDPSession,
+          event: "Detached",
+          listener: () => void
+        ) => void
+      ).call(session, "Detached", listener);
+    } catch (error) {
+      console.warn(
+        `[CDP][PlaywrightAdapter] Failed to attach pooled ${kind} detach listener: ${formatPlaywrightAdapterDiagnostic(
+          error
+        )}`
+      );
+    }
+  }
+
+  private detachPooledSessionListener(
+    kind: CDPSessionKind,
+    session: CDPSession,
+    listener: () => void
+  ): void {
+    let offMethod: unknown;
+    try {
+      offMethod = (session as CDPSession & { off?: unknown }).off;
+    } catch (error) {
+      console.warn(
+        `[CDP][PlaywrightAdapter] Failed to read pooled ${kind} off method: ${formatPlaywrightAdapterDiagnostic(
+          error
+        )}`
+      );
+      return;
+    }
+    if (typeof offMethod !== "function") {
+      return;
+    }
+    try {
+      (
+        offMethod as (
+          this: CDPSession,
+          event: "Detached",
+          listener: () => void
+        ) => void
+      ).call(session, "Detached", listener);
+    } catch (error) {
+      console.warn(
+        `[CDP][PlaywrightAdapter] Failed to detach pooled ${kind} listener: ${formatPlaywrightAdapterDiagnostic(
+          error
+        )}`
+      );
+    }
+  }
+
   private async initializeSessionForKind(
     kind: CDPSessionKind,
     session: CDPSession
@@ -255,12 +520,30 @@ export async function getCDPClientForPage(page: Page): Promise<CDPClient> {
     const client = new PlaywrightCDPClient(page);
     await client.init();
     clientCache.set(page, client);
-    pendingClients.delete(page);
-    page.once("close", () => {
-      disposeCDPClientForPage(page).catch(() => {});
-    });
+    try {
+      const once = (page as Page & { once?: unknown }).once;
+      if (typeof once === "function") {
+        (
+          once as (
+            this: Page,
+            event: "close",
+            listener: () => void
+          ) => void
+        ).call(page, "close", () => {
+          disposeCDPClientForPage(page).catch(() => {});
+        });
+      }
+    } catch (error) {
+      console.warn(
+        `[CDP][PlaywrightAdapter] Failed to attach page close listener: ${formatPlaywrightAdapterDiagnostic(
+          error
+        )}`
+      );
+    }
     return client;
-  })();
+  })().finally(() => {
+    pendingClients.delete(page);
+  });
 
   pendingClients.set(page, initPromise);
   return initPromise;
@@ -273,8 +556,9 @@ export async function disposeCDPClientForPage(page: Page): Promise<void> {
   if (!client) return;
   await client.dispose().catch((error) => {
     console.warn(
-      "[CDP][PlaywrightAdapter] Failed to dispose client for page:",
-      error
+      `[CDP][PlaywrightAdapter] Failed to dispose client for page: ${formatPlaywrightAdapterDiagnostic(
+        error
+      )}`
     );
   });
 }
@@ -286,8 +570,9 @@ export async function disposeAllCDPClients(): Promise<void> {
       pendingClients.delete(page);
       await client.dispose().catch((error) => {
         console.warn(
-          "[CDP][PlaywrightAdapter] Failed to dispose cached client:",
-          error
+          `[CDP][PlaywrightAdapter] Failed to dispose cached client: ${formatPlaywrightAdapterDiagnostic(
+            error
+          )}`
         );
       });
     }
diff --git a/src/cdp/script-injector.test.ts b/src/cdp/script-injector.test.ts
new file mode 100644
index 00000000..c5c145aa
--- /dev/null
+++ b/src/cdp/script-injector.test.ts
@@ -0,0 +1,73 @@
+import type { CDPSession } from "@/cdp/types";
+import { ensureScriptInjected } from "@/cdp/script-injector";
+
+function createSession(
+  sendImplementation: <T = unknown>(
+    method: string,
+    params?: Record<string, unknown>
+  ) => Promise<T>
+): CDPSession {
+  return {
+    id: "session-1",
+    raw: undefined,
+    send: sendImplementation,
+    on: jest.fn(),
+    off: jest.fn(),
+    detach: jest.fn(async () => undefined),
+  };
+}
+
+describe("ensureScriptInjected diagnostics", () => {
+  it("sanitizes and truncates oversized registration diagnostics", async () => {
+    const warnSpy = jest.spyOn(console, "warn").mockImplementation(() => {});
+    const session = createSession(
+      async <T = unknown>(method: string): Promise<T> => {
+      if (method === "Page.addScriptToEvaluateOnNewDocument") {
+        throw new Error(`register\u0000\n${"x".repeat(10_000)}`);
+      }
+      return {} as T;
+      }
+    );
+
+    try {
+      await ensureScriptInjected(
+        session,
+        `script\u0000\n${"k".repeat(500)}`,
+        "window.__script = true;"
+      );
+      const diagnostic = String(warnSpy.mock.calls[0]?.[0] ?? "");
+      expect(diagnostic).toContain("[truncated");
+      expect(diagnostic).not.toContain("\u0000");
+      expect(diagnostic).not.toContain("\n");
+      expect(diagnostic.length).toBeLessThan(900);
+    } finally {
+      warnSpy.mockRestore();
+    }
+  });
+
+  it("formats non-Error evaluation failures deterministically", async () => {
+    const warnSpy = jest.spyOn(console, "warn").mockImplementation(() => {});
+    const session = createSession(
+      async <T = unknown>(method: string): Promise<T> => {
+      if (method === "Runtime.evaluate") {
+        throw { reason: "evaluate object failure" };
+      }
+      return {} as T;
+      }
+    );
+
+    try {
+      await ensureScriptInjected(
+        session,
+        "script-key",
+        "window.__script = true;",
+        42
+      );
+      expect(warnSpy).toHaveBeenCalledWith(
+        expect.stringContaining('{"reason":"evaluate object failure"}')
+      );
+    } finally {
+      warnSpy.mockRestore();
+    }
+  });
+});
diff --git a/src/cdp/script-injector.ts b/src/cdp/script-injector.ts
index 1797bacf..ce727743 100644
--- a/src/cdp/script-injector.ts
+++ b/src/cdp/script-injector.ts
@@ -1,4 +1,5 @@
 import type { CDPSession } from "@/cdp/types";
+import { formatUnknownError } from "@/utils";
 
 interface ScriptInjectionState {
   registered: Set<string>;
@@ -8,6 +9,49 @@ interface ScriptInjectionState {
 const injectedScripts = new WeakMap<object, ScriptInjectionState>();
 
 const GLOBAL_CONTEXT_TOKEN = "__global__";
+const MAX_SCRIPT_INJECTOR_DIAGNOSTIC_CHARS = 400;
+const MAX_SCRIPT_INJECTOR_IDENTIFIER_CHARS = 120;
+
+function sanitizeScriptInjectorText(value: string): string {
+  if (value.length === 0) {
+    return value;
+  }
+  const withoutControlChars = Array.from(value, (char) => {
+    const code = char.charCodeAt(0);
+    return (code >= 0 && code < 32) || code === 127 ? " " : char;
+  }).join("");
+  return withoutControlChars.replace(/\s+/g, " ").trim();
+}
+
+function truncateScriptInjectorText(value: string, maxChars: number): string {
+  if (value.length <= maxChars) {
+    return value;
+  }
+  const omittedChars = value.length - maxChars;
+  return `${value.slice(0, maxChars)}... [truncated ${omittedChars} chars]`;
+}
+
+function formatScriptInjectorIdentifier(value: string): string {
+  const normalized = sanitizeScriptInjectorText(value);
+  if (normalized.length === 0) {
+    return "unknown";
+  }
+  return truncateScriptInjectorText(
+    normalized,
+    MAX_SCRIPT_INJECTOR_IDENTIFIER_CHARS
+  );
+}
+
+function formatScriptInjectorDiagnostic(value: unknown): string {
+  const normalized = sanitizeScriptInjectorText(formatUnknownError(value));
+  if (normalized.length === 0) {
+    return "unknown error";
+  }
+  return truncateScriptInjectorText(
+    normalized,
+    MAX_SCRIPT_INJECTOR_DIAGNOSTIC_CHARS
+  );
+}
 
 function getState(session: CDPSession): ScriptInjectionState {
   let state = injectedScripts.get(session as object);
@@ -49,8 +93,9 @@ export async function ensureScriptInjected(
       state.registered.add(key);
     } catch (error) {
       console.warn(
-        `[CDP][ScriptInjector] Failed to register script ${key}:`,
-        error
+        `[CDP][ScriptInjector] Failed to register script ${formatScriptInjectorIdentifier(
+          key
+        )}: ${formatScriptInjectorDiagnostic(error)}`
       );
     }
   }
@@ -79,8 +124,11 @@ export async function ensureScriptInjected(
     contextsForKey.add(token);
   } catch (error) {
     console.warn(
-      `[CDP][ScriptInjector] Failed to evaluate script ${key} in context ${token}:`,
-      error
+      `[CDP][ScriptInjector] Failed to evaluate script ${formatScriptInjectorIdentifier(
+        key
+      )} in context ${formatScriptInjectorIdentifier(
+        token
+      )}: ${formatScriptInjectorDiagnostic(error)}`
     );
   }
 }
diff --git a/src/cdp/types.ts b/src/cdp/types.ts
index f1ed18b2..8a798988 100644
--- a/src/cdp/types.ts
+++ b/src/cdp/types.ts
@@ -1,7 +1,16 @@
 export interface CDPSession {
-  send<T = any>(method: string, params?: Record<string, unknown>): Promise<T>;
-  on(event: string, handler: (...payload: any[]) => void): void;
-  off?(event: string, handler: (...payload: any[]) => void): void;
+  send<T = unknown>(
+    method: string,
+    params?: Record<string, unknown>
+  ): Promise<T>;
+  on<TPayload extends unknown[]>(
+    event: string,
+    handler: (...payload: TPayload) => void
+  ): void;
+  off?<TPayload extends unknown[]>(
+    event: string,
+    handler: (...payload: TPayload) => void
+  ): void;
   detach(): Promise<void>;
   raw?: unknown;
   id?: string | null;
diff --git a/src/cli/error-reporting.test.ts b/src/cli/error-reporting.test.ts
new file mode 100644
index 00000000..89abaedd
--- /dev/null
+++ b/src/cli/error-reporting.test.ts
@@ -0,0 +1,65 @@
+import { handleCliFatalError } from "@/cli/error-reporting";
+
+describe("handleCliFatalError", () => {
+  it("logs formatted error and trace in debug mode", async () => {
+    const logError = jest.fn();
+    const logTrace = jest.fn();
+
+    await handleCliFatalError({
+      error: { reason: "boom" },
+      debug: true,
+      logError,
+      logTrace,
+    });
+
+    expect(logError).toHaveBeenCalledWith(
+      expect.stringContaining('{"reason":"boom"}')
+    );
+    expect(logTrace).toHaveBeenCalledWith({ reason: "boom" });
+  });
+
+  it("attempts to close agent and logs shutdown failure", async () => {
+    const logShutdownError = jest.fn();
+    const agent = {
+      closeAgent: jest.fn().mockRejectedValue({ reason: "close failed" }),
+    };
+
+    await handleCliFatalError({
+      error: new Error("task failed"),
+      debug: false,
+      agent,
+      logError: jest.fn(),
+      logShutdownError,
+    });
+
+    expect(agent.closeAgent).toHaveBeenCalledTimes(1);
+    expect(logShutdownError).toHaveBeenCalledWith(
+      'Error during shutdown: {"reason":"close failed"}'
+    );
+  });
+
+  it("remains resilient when logger callbacks throw", async () => {
+    const agent = {
+      closeAgent: jest.fn().mockRejectedValue({ reason: "close failed" }),
+    };
+
+    await expect(
+      handleCliFatalError({
+        error: { reason: "boom" },
+        debug: true,
+        agent,
+        logError: () => {
+          throw new Error("log failed");
+        },
+        logTrace: () => {
+          throw new Error("trace failed");
+        },
+        logShutdownError: () => {
+          throw new Error("shutdown log failed");
+        },
+      })
+    ).resolves.toBeUndefined();
+
+    expect(agent.closeAgent).toHaveBeenCalledTimes(1);
+  });
+});
diff --git a/src/cli/error-reporting.ts b/src/cli/error-reporting.ts
new file mode 100644
index 00000000..85789123
--- /dev/null
+++ b/src/cli/error-reporting.ts
@@ -0,0 +1,51 @@
+import chalk from "chalk";
+import { formatCliError } from "./format-cli-error";
+import { closeAgentSafely } from "./shutdown";
+
+interface ClosableAgent {
+  closeAgent: () => Promise<void>;
+}
+
+export async function handleCliFatalError(params: {
+  error: unknown;
+  debug: boolean;
+  agent?: ClosableAgent;
+  logError?: (message: string) => void;
+  logTrace?: (...args: unknown[]) => void;
+  logShutdownError?: (message: string) => void;
+}): Promise<void> {
+  const {
+    error,
+    debug,
+    agent,
+    logError = console.log,
+    logTrace = console.trace,
+    logShutdownError = console.error,
+  } = params;
+
+  try {
+    logError(chalk.red(formatCliError(error)));
+  } catch {
+    // best-effort logging only
+  }
+  if (debug) {
+    try {
+      logTrace(error);
+    } catch {
+      // best-effort logging only
+    }
+  }
+
+  if (!agent) {
+    return;
+  }
+
+  const shutdown = await closeAgentSafely(agent);
+  if (!shutdown.success) {
+    try {
+      logShutdownError(`Error during shutdown: ${shutdown.message}`);
+    } catch {
+      // best-effort logging only
+    }
+  }
+}
diff --git a/src/cli/format-cli-error.test.ts b/src/cli/format-cli-error.test.ts
new file mode 100644
index 00000000..79879feb
--- /dev/null
+++ b/src/cli/format-cli-error.test.ts
@@ -0,0 +1,23 @@
+import { formatCliError } from "@/cli/format-cli-error";
+
+describe("formatCliError", () => {
+  it("formats object errors as readable JSON", () => {
+    expect(formatCliError({ reason: "failure" })).toBe('{"reason":"failure"}');
+  });
+
+  it("falls back to generic message for empty error text", () => {
+    expect(formatCliError("   ")).toBe("Unknown CLI error");
+  });
+
+  it("sanitizes control characters from CLI error output", () => {
+    expect(formatCliError("bad\u0007error\nmessage")).toBe("bad error message");
+  });
+
+  it("truncates oversized CLI error payloads", () => {
+    const oversized = `error-${"x".repeat(3_000)}`;
+    const result = formatCliError(oversized);
+
+    expect(result).toContain("[truncated");
+    expect(result.length).toBeLessThan(2_100);
+  });
+});
diff --git a/src/cli/format-cli-error.ts b/src/cli/format-cli-error.ts
new file mode 100644
index 00000000..8c38389f
--- /dev/null
+++ b/src/cli/format-cli-error.ts
@@ -0,0 +1,32 @@
+import { formatUnknownError } from "@/utils";
+
+const MAX_CLI_ERROR_CHARS = 2_000;
+
+function stripControlChars(value: string): string {
+  return Array.from(value)
+    .map((char) => {
+      const code = char.charCodeAt(0);
+      return (code >= 0 && code < 32) || code === 127 ? " " : char;
+    })
+    .join("");
+}
+
+function truncateCliError(value: string): string {
+  if (value.length <= MAX_CLI_ERROR_CHARS) {
+    return value;
+  }
+  return `${value.slice(
+    0,
+    MAX_CLI_ERROR_CHARS
+  )}... [truncated ${value.length - MAX_CLI_ERROR_CHARS} chars]`;
+}
+
+export function formatCliError(error: unknown): string {
+  const normalized = stripControlChars(formatUnknownError(error))
+    .replace(/\s+/g, " ")
+    .trim();
+  if (normalized.length === 0) {
+    return "Unknown CLI error";
+  }
+  return truncateCliError(normalized);
+}
diff --git a/src/cli/index.ts b/src/cli/index.ts
index d7f73ec7..495379dc 100644
--- a/src/cli/index.ts
+++ b/src/cli/index.ts
@@ -1,6 +1,5 @@
 #!/usr/bin/env node
 import "dotenv/config";
-import fs from "node:fs";
 import { Command } from "commander";
 import * as inquirer from "@inquirer/prompts";
 import ora from "ora";
@@ -17,10 +16,16 @@ import {
   AgentStep,
   Task,
   TaskOutput,
-  TaskStatus,
 } from "@/types";
-import { HyperagentError } from "@/agent/error";
 import { SessionDetail } from "@hyperbrowser/sdk/types";
+import { formatCliError } from "./format-cli-error";
+import { loadMCPServersFromFile } from "./mcp-config";
+import { closeAgentSafely } from "./shutdown";
+import { setRawModeIfSupported } from "./stdin-utils";
+import { loadTaskDescriptionFromFile, normalizeTaskDescription } from "./task-input";
+import { pauseTaskIfRunning, resumeTaskIfPaused } from "./task-controls";
+import { attachTaskErrorHandler } from "./task-error-handler";
+import { handleCliFatalError } from "./error-reporting";
 
 const program = new Command();
 
@@ -46,6 +51,7 @@ program
     let taskDescription = (options.command as string) || undefined;
     const filePath = (options.file as string) || undefined;
     const mcpPath = (options.mcp as string) || undefined;
+    let agent: HyperAgent<"Local" | "Hyperbrowser"> | undefined;
 
     console.log(chalk.blue("HyperAgent CLI"));
     currentSpinner.info(
@@ -68,7 +74,14 @@ program
         process.env.HYPERBROWSER_API_KEY = apiKey; // Set it for the current process
       }
 
-      const agent = new HyperAgent({
+      if (taskDescription !== undefined) {
+        taskDescription = normalizeTaskDescription(
+          taskDescription,
+          "Task description from --command"
+        );
+      }
+
+      const createdAgent = new HyperAgent({
         debug: debug,
         browserProvider: useHB ? "Hyperbrowser" : "Local",
         customActions: [
@@ -136,8 +149,15 @@ program
           ),
         ],
       });
+      agent = createdAgent;
 
       let task: Task;
+      const onTaskError = (error: unknown): void => {
+        console.log(chalk.red(formatCliError(error)));
+        if (debug) {
+          console.trace(error);
+        }
+      };
 
       readline.emitKeypressEvents(process.stdin);
 
@@ -154,58 +174,56 @@ program
           currentSpinner.stopAndPersist({ symbol: "⏸" });
           currentSpinner = ora();
 
-          if (task.getStatus() == TaskStatus.RUNNING) {
-            task.pause();
-          }
+          pauseTaskIfRunning(task);
         } else if (key && key.ctrl && key.name == "r") {
-          if (task.getStatus() == TaskStatus.PAUSED) {
+          if (resumeTaskIfPaused(task)) {
             currentSpinner.start(chalk.blue("Hyperagent will resume"));
             currentSpinner.stopAndPersist({ symbol: "⏵" });
             currentSpinner = ora();
-
-            task.resume();
           }
         } else if (key && key.ctrl && key.name == "c") {
           if (currentSpinner.isSpinning) {
             currentSpinner.stopAndPersist();
           }
           console.log("\nShutting down HyperAgent");
-          try {
-            await agent.closeAgent();
-            process.exit(0);
-          } catch (err) {
-            console.error("Error during shutdown:", err);
+          const shutdown = await closeAgentSafely(createdAgent);
+          if (!shutdown.success) {
+            console.error(
+              `Error during shutdown: ${formatCliError(shutdown.message)}`
+            );
             process.exit(1);
           }
+          process.exit(0);
         }
       });
 
-      process.stdin.setRawMode(true);
+      setRawModeIfSupported(true);
 
       const onStep = (params: AgentStep) => {
         const action = params.agentOutput.action;
         const output = params.actionOutput;
+        const failureMessage = formatCliError(output.message);
 
         const actionDisplay = output.success
-          ? `  └── [${chalk.yellow(action.type)}] ${agent.pprintAction(action as ActionType)}`
-          : `  └── [${chalk.red(action.type)}] ${chalk.red(output.message)}`;
+          ? `  └── [${chalk.yellow(action.type)}] ${createdAgent.pprintAction(action as ActionType)}`
+          : `  └── [${chalk.red(action.type)}] ${chalk.red(failureMessage)}`;
 
         currentSpinner.succeed(
           `[${chalk.yellow("step")}]: ${params.agentOutput.thoughts}\n${actionDisplay}`
         );
         currentSpinner = ora();
-        process.stdin.setRawMode(true);
+        setRawModeIfSupported(true);
         process.stdin.resume();
       };
 
       const debugAgentOutput = (params: AgentOutput) => {
         const action = params.action;
-        const actionDisplay = `  └── [${chalk.yellow(action.type)}] ${agent.pprintAction(action as ActionType)}`;
+        const actionDisplay = `  └── [${chalk.yellow(action.type)}] ${createdAgent.pprintAction(action as ActionType)}`;
 
         currentSpinner.start(
           `[${chalk.yellow("planning")}]: ${params.thoughts}\n${actionDisplay}`
         );
-        process.stdin.setRawMode(true);
+        setRawModeIfSupported(true);
         process.stdin.resume();
       };
 
@@ -228,72 +246,73 @@ program
           ],
         });
         if (continueTask) {
-          const taskDescription = await inquirer.input({
+          const nextTaskDescriptionInput = await inquirer.input({
             message: "What should HyperAgent do next for you?",
             required: true,
           });
+          const nextTaskDescription = normalizeTaskDescription(
+            nextTaskDescriptionInput,
+            "Task description from follow-up prompt"
+          );
 
-          process.stdin.setRawMode(true);
+          setRawModeIfSupported(true);
           process.stdin.resume();
 
-          task = await agent.executeTaskAsync(taskDescription, {
+          task = await createdAgent.executeTaskAsync(nextTaskDescription, {
             onStep: onStep,
             debugOnAgentOutput: debugAgentOutput,
             onComplete: onComplete,
           });
-          task.emitter.addListener("error", (error) => {
-            task.cancel();
-            throw error;
-          });
+          attachTaskErrorHandler(task, onTaskError);
         } else {
+          const shutdown = await closeAgentSafely(createdAgent);
+          if (!shutdown.success) {
+            console.error(
+              `Error during shutdown: ${formatCliError(shutdown.message)}`
+            );
+            process.exit(1);
+          }
           process.exit(0);
         }
       };
       if (!taskDescription) {
         if (filePath) {
-          taskDescription = (await fs.promises.readFile(filePath)).toString();
+          taskDescription = await loadTaskDescriptionFromFile(filePath);
         } else {
-          taskDescription = await inquirer.input({
+          const taskInput = await inquirer.input({
             message: "What should HyperAgent do for you today?",
             required: true,
           });
+          taskDescription = normalizeTaskDescription(
+            taskInput,
+            "Task description from interactive prompt"
+          );
         }
       }
 
       if (mcpPath) {
-        const mcpConfig = JSON.parse(
-          (await fs.promises.readFile(mcpPath)).toString()
-        );
-        await agent.initializeMCPClient({ servers: mcpConfig });
+        const mcpServers = await loadMCPServersFromFile(mcpPath);
+        await createdAgent.initializeMCPClient({ servers: mcpServers });
       }
 
       if (useHB && !debug) {
-        await agent.initBrowser();
-        const session = agent.getSession() as SessionDetail;
+        await createdAgent.initBrowser();
+        const session = createdAgent.getSession() as SessionDetail;
         console.log(`Hyperbrowser Live URL: ${session.liveUrl}\n`);
       }
 
-      task = await agent.executeTaskAsync(taskDescription, {
+      task = await createdAgent.executeTaskAsync(taskDescription, {
         onStep: onStep,
         onComplete: onComplete,
         debugOnAgentOutput: debugAgentOutput,
       });
-      task.emitter.addListener("error", (error) => {
-        task.cancel();
-        throw error;
-      });
+      attachTaskErrorHandler(task, onTaskError);
     } catch (err) {
-      if (err instanceof HyperagentError || err instanceof Error) {
-        console.log(chalk.red(err.message));
-        if (debug) {
-          console.trace(err);
-        }
-      } else {
-        console.log(chalk.red(err));
-        if (debug) {
-          console.trace(err);
-        }
-      }
+      await handleCliFatalError({
+        error: err,
+        debug,
+        agent,
+      });
     }
   });
 
diff --git a/src/cli/mcp-config.test.ts b/src/cli/mcp-config.test.ts
new file mode 100644
index 00000000..b6f2cae5
--- /dev/null
+++ b/src/cli/mcp-config.test.ts
@@ -0,0 +1,848 @@
+import fs from "node:fs";
+import os from "node:os";
+import path from "node:path";
+import {
+  loadMCPServersFromFile,
+  parseMCPServersConfig,
+} from "@/cli/mcp-config";
+
+describe("parseMCPServersConfig", () => {
+  it("parses array-formatted config", () => {
+    const parsed = parseMCPServersConfig(
+      '[{"id":"one","command":"npx","args":["-y","server"]}]'
+    );
+    expect(parsed).toEqual([
+      {
+        id: "one",
+        command: "npx",
+        args: ["-y", "server"],
+        connectionType: "stdio",
+      },
+    ]);
+  });
+
+  it("parses object config with servers array", () => {
+    const parsed = parseMCPServersConfig(
+      '{"servers":[{"id":"one","connectionType":"sse","sseUrl":"https://example.com/sse"}]}'
+    );
+    expect(parsed).toEqual([
+      {
+        id: "one",
+        connectionType: "sse",
+        sseUrl: "https://example.com/sse",
+      },
+    ]);
+  });
+
+  it("parses config content with BOM and surrounding whitespace", () => {
+    const parsed = parseMCPServersConfig(
+      "  \n\uFEFF[{\"command\":\"npx\",\"args\":[\"-y\"]}]  \n"
+    );
+    expect(parsed).toEqual([
+      {
+        command: "npx",
+        args: ["-y"],
+        connectionType: "stdio",
+      },
+    ]);
+  });
+
+  it("throws clear message for invalid JSON", () => {
+    expect(() => parseMCPServersConfig("{broken")).toThrow(
+      "Invalid MCP config JSON"
+    );
+  });
+
+  it("sanitizes and truncates oversized JSON parse diagnostics", () => {
+    const parseSpy = jest.spyOn(JSON, "parse").mockImplementation(() => {
+      throw new Error(`parse\u0000\n${"x".repeat(10_000)}`);
+    });
+
+    try {
+      expect(() => parseMCPServersConfig('{"servers":[{"command":"npx"}]}')).toThrow(
+        "[truncated"
+      );
+      expect(() => parseMCPServersConfig('{"servers":[{"command":"npx"}]}')).toThrow(
+        /Invalid MCP config JSON:/
+      );
+      try {
+        parseMCPServersConfig('{"servers":[{"command":"npx"}]}');
+      } catch (error) {
+        const message = String(error instanceof Error ? error.message : error);
+        expect(message).not.toContain("\u0000");
+        expect(message).not.toContain("\n");
+      }
+    } finally {
+      parseSpy.mockRestore();
+    }
+  });
+
+  it("throws clear message when config input is not a string", () => {
+    expect(() => parseMCPServersConfig(42 as unknown as string)).toThrow(
+      "Invalid MCP config JSON: config must be a string."
+    );
+  });
+
+  it("throws clear message for empty config payloads", () => {
+    expect(() => parseMCPServersConfig("   ")).toThrow(
+      "Invalid MCP config JSON: config is empty."
+    );
+  });
+
+  it("throws clear message when config contains null bytes", () => {
+    expect(() => parseMCPServersConfig("\u0000[]")).toThrow(
+      "Invalid MCP config JSON: config appears to be binary or contains null bytes."
+    );
+  });
+
+  it("throws clear message when config contains unsupported control characters", () => {
+    expect(() => parseMCPServersConfig("\u0007[]")).toThrow(
+      "Invalid MCP config JSON: config contains unsupported control characters."
+    );
+  });
+
+  it("throws when raw config exceeds maximum allowed size", () => {
+    expect(() => parseMCPServersConfig("x".repeat(1_000_001))).toThrow(
+      "Invalid MCP config JSON: config exceeds 1000000 characters."
+    );
+  });
+
+  it("throws when payload is not servers-shaped", () => {
+    expect(() => parseMCPServersConfig('{"foo":1}')).toThrow(
+      'MCP config must be a JSON array or an object with a "servers" array.'
+    );
+  });
+
+  it("throws when config contains no server entries", () => {
+    expect(() => parseMCPServersConfig("[]")).toThrow(
+      "MCP config must include at least one server entry."
+    );
+    expect(() => parseMCPServersConfig('{"servers":[]}')).toThrow(
+      "MCP config must include at least one server entry."
+    );
+  });
+
+  it("throws when config contains too many server entries", () => {
+    const entries = Array.from({ length: 101 }, () => ({
+      command: "npx",
+    }));
+    expect(() => parseMCPServersConfig(JSON.stringify(entries))).toThrow(
+      "MCP config must include no more than 100 server entries."
+    );
+  });
+
+  it("throws when server entries are not objects", () => {
+    expect(() => parseMCPServersConfig("[1]")).toThrow(
+      "MCP server entry at index 0 must be an object."
+    );
+  });
+
+  it("throws clear message when top-level servers field is unreadable", () => {
+    const parseSpy = jest.spyOn(JSON, "parse").mockImplementation(() =>
+      new Proxy(
+        {},
+        {
+          get: (_target, prop) => {
+            if (prop === "servers") {
+              throw new Error("servers getter trap");
+            }
+            return undefined;
+          },
+        }
+      ) as unknown
+    );
+
+    try {
+      expect(() => parseMCPServersConfig('{"servers":[{"command":"npx"}]}')).toThrow(
+        'MCP config must be a JSON array or an object with a "servers" array.'
+      );
+    } finally {
+      parseSpy.mockRestore();
+    }
+  });
+
+  it("throws clear message when server field getters throw", () => {
+    const parseSpy = jest.spyOn(JSON, "parse").mockImplementation(() => [
+      new Proxy(
+        { command: "npx" },
+        {
+          get: (target, prop, receiver) => {
+            if (prop === "id") {
+              throw new Error("id getter trap");
+            }
+            return Reflect.get(target, prop, receiver);
+          },
+        }
+      ),
+    ] as unknown);
+
+    try {
+      expect(() => parseMCPServersConfig('[{"command":"npx"}]')).toThrow(
+        'MCP server entry at index 0 has inaccessible "id" value.'
+      );
+    } finally {
+      parseSpy.mockRestore();
+    }
+  });
+
+  it("rejects args arrays when proxy traps block iteration", () => {
+    const trappedArgs = new Proxy(["-y", "server"], {
+      get: (target, prop, receiver) => {
+        if (prop === Symbol.iterator) {
+          throw new Error("iterator trap");
+        }
+        return Reflect.get(target, prop, receiver);
+      },
+    });
+    const parseSpy = jest.spyOn(JSON, "parse").mockImplementation(() => [
+      {
+        command: "npx",
+        args: trappedArgs,
+      },
+    ] as unknown);
+
+    try {
+      expect(() => parseMCPServersConfig('[{"command":"npx","args":["-y"]}]')).toThrow(
+        'MCP server entry at index 0 must provide "args" as an array of strings.'
+      );
+    } finally {
+      parseSpy.mockRestore();
+    }
+  });
+
+  it("throws when stdio server command is missing or blank", () => {
+    expect(() => parseMCPServersConfig('[{"connectionType":"stdio"}]')).toThrow(
+      'MCP server entry at index 0 must include a non-empty "command" for stdio connections.'
+    );
+    expect(() =>
+      parseMCPServersConfig('[{"connectionType":"stdio","command":"   "}]')
+    ).toThrow(
+      'MCP server entry at index 0 must include a non-empty "command" for stdio connections.'
+    );
+  });
+
+  it("throws when sse server sseUrl is missing or blank", () => {
+    expect(() => parseMCPServersConfig('[{"connectionType":"sse"}]')).toThrow(
+      'MCP server entry at index 0 must include a non-empty "sseUrl" for SSE connections.'
+    );
+    expect(() =>
+      parseMCPServersConfig('[{"connectionType":"sse","sseUrl":"   "}]')
+    ).toThrow(
+      'MCP server entry at index 0 must include a non-empty "sseUrl" for SSE connections.'
+    );
+  });
+
+  it("throws when duplicate non-empty server IDs are declared", () => {
+    expect(() =>
+      parseMCPServersConfig(
+        '[{"id":"shared","command":"npx"},{"id":"shared","command":"node"}]'
+      )
+    ).toThrow('MCP server entry at index 1 reuses duplicate id "shared".');
+  });
+
+  it("rejects duplicate server IDs case-insensitively", () => {
+    expect(() =>
+      parseMCPServersConfig(
+        '[{"id":"Server-A","command":"npx"},{"id":"server-a","command":"node"}]'
+      )
+    ).toThrow('MCP server entry at index 1 reuses duplicate id "server-a".');
+  });
+
+  it("throws when id or connectionType types are invalid", () => {
+    expect(() =>
+      parseMCPServersConfig('[{"id":123,"command":"npx"}]')
+    ).toThrow(
+      'MCP server entry at index 0 must provide "id" as a string when specified.'
+    );
+
+    expect(() =>
+      parseMCPServersConfig('[{"connectionType":123,"command":"npx"}]')
+    ).toThrow(
+      'MCP server entry at index 0 must provide "connectionType" as a string when specified.'
+    );
+  });
+
+  it("rejects control characters in id, connectionType, and command", () => {
+    expect(() =>
+      parseMCPServersConfig('[{"id":"bad\\u0007id","command":"npx"}]')
+    ).toThrow(
+      'MCP server entry at index 0 must provide "id" as a string when specified.'
+    );
+    expect(() =>
+      parseMCPServersConfig('[{"id":"bad\\nid","command":"npx"}]')
+    ).toThrow(
+      'MCP server entry at index 0 must provide "id" as a string when specified.'
+    );
+
+    expect(() =>
+      parseMCPServersConfig('[{"connectionType":"sse\\u0007","command":"npx"}]')
+    ).toThrow(
+      'MCP server entry at index 0 has unsupported connectionType "sse". Supported values are "stdio" and "sse".'
+    );
+
+    expect(() =>
+      parseMCPServersConfig('[{"command":"np\\u0007x"}]')
+    ).toThrow(
+      'MCP server entry at index 0 must include a non-empty "command" for stdio connections.'
+    );
+    expect(() =>
+      parseMCPServersConfig('[{"command":"np\\nx"}]')
+    ).toThrow(
+      'MCP server entry at index 0 must include a non-empty "command" for stdio connections.'
+    );
+
+    expect(() =>
+      parseMCPServersConfig(`[{"id":"${"x".repeat(129)}","command":"npx"}]`)
+    ).toThrow(
+      'MCP server entry at index 0 must provide "id" as a string when specified.'
+    );
+
+    expect(() =>
+      parseMCPServersConfig(`[{"command":"${"x".repeat(2049)}"}]`)
+    ).toThrow(
+      'MCP server entry at index 0 must include a non-empty "command" for stdio connections.'
+    );
+  });
+
+  it("returns normalized trimmed id/command/sseUrl fields", () => {
+    const parsed = parseMCPServersConfig(
+      '[{"id":"  stdio-1  ","command":"  npx  ","includeTools":["  search  ","lookup  records"],"excludeTools":[" notes  list " ]},{"connectionType":"sse","id":"  ","sseUrl":"  https://example.com/sse  "}]'
+    );
+
+    expect(parsed).toEqual([
+      {
+        id: "stdio-1",
+        command: "npx",
+        connectionType: "stdio",
+        includeTools: ["search", "lookup records"],
+        excludeTools: ["notes list"],
+      },
+      {
+        connectionType: "sse",
+        sseUrl: "https://example.com/sse",
+      },
+    ]);
+  });
+
+  it("throws when include/exclude tools are not non-empty string arrays", () => {
+    expect(() =>
+      parseMCPServersConfig(
+        '[{"command":"npx","includeTools":"search"}]'
+      )
+    ).toThrow(
+      'MCP server entry at index 0 must provide "includeTools" as an array of non-empty strings.'
+    );
+
+    expect(() =>
+      parseMCPServersConfig(
+        '[{"command":"npx","excludeTools":["ok", "   "]}]'
+      )
+    ).toThrow(
+      'MCP server entry at index 0 must provide "excludeTools" as an array of non-empty strings.'
+    );
+
+    expect(() =>
+      parseMCPServersConfig(
+        '[{"command":"npx","includeTools":["sea\\u0007rch"]}]'
+      )
+    ).toThrow(
+      'MCP server entry at index 0 must provide "includeTools" as an array of non-empty strings.'
+    );
+    expect(() =>
+      parseMCPServersConfig(
+        '[{"command":"npx","excludeTools":["bad\\nname"]}]'
+      )
+    ).toThrow(
+      'MCP server entry at index 0 must provide "excludeTools" as an array of non-empty strings.'
+    );
+
+    expect(() =>
+      parseMCPServersConfig(
+        `[{"command":"npx","includeTools":[${Array.from({ length: 201 })
+          .map((_, i) => `"tool-${i}"`)
+          .join(",")}]}]`
+      )
+    ).toThrow(
+      'MCP server entry at index 0 must provide no more than 200 "includeTools" entries.'
+    );
+
+    expect(() =>
+      parseMCPServersConfig(
+        `[{"command":"npx","excludeTools":["${"x".repeat(257)}"]}]`
+      )
+    ).toThrow(
+      'MCP server entry at index 0 must provide "excludeTools" as an array of non-empty strings.'
+    );
+  });
+
+  it("throws when include/exclude tool arrays contain duplicates after trimming", () => {
+    expect(() =>
+      parseMCPServersConfig(
+        '[{"command":"npx","includeTools":[" search ","search"]}]'
+      )
+    ).toThrow(
+      'MCP server entry at index 0 contains duplicate "includeTools" value "search" after trimming.'
+    );
+
+    expect(() =>
+      parseMCPServersConfig(
+        '[{"command":"npx","excludeTools":[" notes ","notes"]}]'
+      )
+    ).toThrow(
+      'MCP server entry at index 0 contains duplicate "excludeTools" value "notes" after trimming.'
+    );
+
+    expect(() =>
+      parseMCPServersConfig(
+        '[{"command":"npx","includeTools":["Search","search"]}]'
+      )
+    ).toThrow(
+      'MCP server entry at index 0 contains duplicate "includeTools" value "search" after trimming.'
+    );
+
+    expect(() =>
+      parseMCPServersConfig(
+        '[{"command":"npx","includeTools":["lookup   records","lookup records"]}]'
+      )
+    ).toThrow(
+      'MCP server entry at index 0 contains duplicate "includeTools" value "lookup records" after trimming.'
+    );
+  });
+
+  it("normalizes connectionType casing/whitespace and rejects unsupported values", () => {
+    const parsed = parseMCPServersConfig(
+      '[{"connectionType":"  SSE  ","sseUrl":"https://example.com/sse"}]'
+    );
+    expect(parsed[0]?.connectionType).toBe("sse");
+
+    expect(() =>
+      parseMCPServersConfig('[{"connectionType":"websocket","command":"npx"}]')
+    ).toThrow(
+      'MCP server entry at index 0 has unsupported connectionType "websocket". Supported values are "stdio" and "sse".'
+    );
+
+    const hugeConnectionType = `x${"y".repeat(500)}`;
+    expect(() =>
+      parseMCPServersConfig(
+        `[{"connectionType":"${hugeConnectionType}","command":"npx"}]`
+      )
+    ).toThrow(/\[truncated \d+ chars\]/);
+  });
+
+  it("infers SSE connectionType when only sseUrl is provided", () => {
+    const parsed = parseMCPServersConfig(
+      '[{"sseUrl":"https://example.com/sse"}]'
+    );
+    expect(parsed).toEqual([
+      {
+        connectionType: "sse",
+        sseUrl: "https://example.com/sse",
+      },
+    ]);
+  });
+
+  it("validates args/env/sseHeaders shapes and normalizes record keys", () => {
+    const parsed = parseMCPServersConfig(
+      '[{"command":"npx","args":[" -y "," server "],"env":{" KEY ":"value"}},{"connectionType":"sse","sseUrl":"https://example.com/sse","sseHeaders":{" Authorization ":" Bearer token "}}]'
+    );
+    expect(parsed[0]).toEqual(
+      expect.objectContaining({
+        args: ["-y", "server"],
+        env: { KEY: "value" },
+      })
+    );
+    expect(parsed[1]).toEqual(
+      expect.objectContaining({
+        sseHeaders: { Authorization: "Bearer token" },
+      })
+    );
+
+    expect(() =>
+      parseMCPServersConfig('[{"command":"npx","args":[1]}]')
+    ).toThrow(
+      'MCP server entry at index 0 must provide "args" as an array of strings.'
+    );
+    expect(() =>
+      parseMCPServersConfig('[{"command":"npx","args":[" "]}]')
+    ).toThrow(
+      'MCP server entry at index 0 must provide "args" as an array of non-empty strings.'
+    );
+    expect(() =>
+      parseMCPServersConfig('[{"command":"npx","args":["ok\\u0007bad"]}]')
+    ).toThrow(
+      'MCP server entry at index 0 must provide "args" as an array of non-empty strings.'
+    );
+    expect(() =>
+      parseMCPServersConfig('[{"command":"npx","args":["ok\\nbad"]}]')
+    ).toThrow(
+      'MCP server entry at index 0 must provide "args" as an array of non-empty strings.'
+    );
+    expect(() =>
+      parseMCPServersConfig(
+        `[{"command":"npx","args":[${Array.from({ length: 101 })
+          .map(() => '"ok"')
+          .join(",")}]}]`
+      )
+    ).toThrow(
+      'MCP server entry at index 0 must provide no more than 100 "args" entries.'
+    );
+    expect(() =>
+      parseMCPServersConfig(`[{"command":"npx","args":["${"x".repeat(4001)}"]}]`)
+    ).toThrow(
+      'MCP server entry at index 0 must provide "args" as an array of non-empty strings.'
+    );
+    expect(() =>
+      parseMCPServersConfig('[{"command":"npx","env":{"":1}}]')
+    ).toThrow(
+      'MCP server entry at index 0 must provide "env" as an object of string key/value pairs.'
+    );
+    expect(() =>
+      parseMCPServersConfig(
+        '[{"connectionType":"sse","sseUrl":"https://example.com/sse","sseHeaders":{"":1}}]'
+      )
+    ).toThrow(
+      'MCP server entry at index 0 must provide "sseHeaders" as an object of string key/value pairs.'
+    );
+    expect(() =>
+      parseMCPServersConfig('[{"command":"npx","env":{"constructor":"oops"}}]')
+    ).toThrow(
+      'MCP server entry at index 0 must provide "env" as an object of string key/value pairs.'
+    );
+    expect(() =>
+      parseMCPServersConfig('[{"command":"npx","env":{" Constructor ":"oops"}}]')
+    ).toThrow(
+      'MCP server entry at index 0 must provide "env" as an object of string key/value pairs.'
+    );
+    expect(() =>
+      parseMCPServersConfig('[{"command":"npx","env":{"KE\\u0007Y":"oops"}}]')
+    ).toThrow(
+      'MCP server entry at index 0 must provide "env" as an object of string key/value pairs.'
+    );
+    expect(() =>
+      parseMCPServersConfig('[{"command":"npx","env":{"KEY":"oo\\u0007ps"}}]')
+    ).toThrow(
+      'MCP server entry at index 0 must provide "env" as an object of string key/value pairs.'
+    );
+    expect(() =>
+      parseMCPServersConfig(
+        '[{"connectionType":"sse","sseUrl":"https://example.com/sse","sseHeaders":{"__proto__":"oops"}}]'
+      )
+    ).toThrow(
+      'MCP server entry at index 0 must provide "sseHeaders" as an object of string key/value pairs.'
+    );
+    expect(() =>
+      parseMCPServersConfig(
+        '[{"connectionType":"sse","sseUrl":"https://example.com/sse","sseHeaders":{"Authorization":"   "}}]'
+      )
+    ).toThrow(
+      'MCP server entry at index 0 must provide "sseHeaders" as an object of string key/value pairs.'
+    );
+    expect(() =>
+      parseMCPServersConfig(
+        '[{"connectionType":"sse","sseUrl":"https://example.com/sse","sseHeaders":{"Authorization":"Bearer\\u0007token"}}]'
+      )
+    ).toThrow(
+      'MCP server entry at index 0 must provide "sseHeaders" as an object of string key/value pairs.'
+    );
+    expect(() =>
+      parseMCPServersConfig('[{"command":"npx","env":{"KEY":"line1\\nline2"}}]')
+    ).toThrow(
+      'MCP server entry at index 0 must provide "env" as an object of string key/value pairs.'
+    );
+    expect(() =>
+      parseMCPServersConfig(
+        '[{"connectionType":"sse","sseUrl":"https://example.com/sse","sseHeaders":{"Authorization":"line1\\nline2"}}]'
+      )
+    ).toThrow(
+      'MCP server entry at index 0 must provide "sseHeaders" as an object of string key/value pairs.'
+    );
+    expect(() =>
+      parseMCPServersConfig(
+        `[{"command":"npx","env":{"${"k".repeat(257)}":"value"}}]`
+      )
+    ).toThrow(
+      'MCP server entry at index 0 must provide "env" as an object of string key/value pairs.'
+    );
+    expect(() =>
+      parseMCPServersConfig(
+        `[{"command":"npx","env":{"KEY":"${"x".repeat(4001)}"}}]`
+      )
+    ).toThrow(
+      'MCP server entry at index 0 must provide "env" as an object of string key/value pairs.'
+    );
+    expect(() =>
+      parseMCPServersConfig(
+        `[{"command":"npx","env":{${Array.from({ length: 201 })
+          .map((_, i) => `"k${i}":"v"`)
+          .join(",")}}}]`
+      )
+    ).toThrow(
+      'MCP server entry at index 0 must provide no more than 200 "env" entries.'
+    );
+
+    expect(() =>
+      parseMCPServersConfig(
+        '[{"command":"npx","env":{" KEY ":"a","KEY":"b"}}]'
+      )
+    ).toThrow(
+      'MCP server entry at index 0 has duplicate "env" key "KEY" after trimming.'
+    );
+    expect(() =>
+      parseMCPServersConfig(
+        '[{"connectionType":"sse","sseUrl":"https://example.com/sse","sseHeaders":{" Authorization ":"a","Authorization":"b"}}]'
+      )
+    ).toThrow(
+      'MCP server entry at index 0 has duplicate "sseHeaders" key "Authorization" after trimming.'
+    );
+    expect(() =>
+      parseMCPServersConfig(
+        '[{"connectionType":"sse","sseUrl":"https://example.com/sse","sseHeaders":{"Bad Header":"a"}}]'
+      )
+    ).toThrow(
+      'MCP server entry at index 0 must provide "sseHeaders" as an object of string key/value pairs.'
+    );
+    expect(() =>
+      parseMCPServersConfig(
+        '[{"connectionType":"sse","sseUrl":"https://example.com/sse","sseHeaders":{"Bad:Header":"a"}}]'
+      )
+    ).toThrow(
+      'MCP server entry at index 0 must provide "sseHeaders" as an object of string key/value pairs.'
+    );
+    expect(() =>
+      parseMCPServersConfig(
+        '[{"connectionType":"sse","sseUrl":"https://example.com/sse","sseHeaders":{"Authorization":"a","authorization":"b"}}]'
+      )
+    ).toThrow(
+      'MCP server entry at index 0 has duplicate "sseHeaders" key "authorization" after trimming.'
+    );
+  });
+
+  it("validates sseUrl formatting and protocol", () => {
+    expect(() =>
+      parseMCPServersConfig('[{"connectionType":"sse","sseUrl":"not-a-url"}]')
+    ).toThrow(
+      'MCP server entry at index 0 has invalid "sseUrl" value "not-a-url".'
+    );
+
+    expect(() =>
+      parseMCPServersConfig('[{"connectionType":"sse","sseUrl":"ftp://example.com/sse"}]')
+    ).toThrow(
+      'MCP server entry at index 0 has unsupported sseUrl protocol "ftp:". Use http:// or https://.'
+    );
+
+    expect(() =>
+      parseMCPServersConfig(
+        '[{"connectionType":"sse","sseUrl":"https://example.com/sse\\u0007"}]'
+      )
+    ).toThrow(
+      'MCP server entry at index 0 has invalid "sseUrl" value "https://example.com/sse".'
+    );
+
+    expect(() =>
+      parseMCPServersConfig(
+        `[{"connectionType":"sse","sseUrl":"https://example.com/${"x".repeat(
+          3990
+        )}"}]`
+      )
+    ).toThrow(/invalid "sseUrl" value/);
+    expect(() =>
+      parseMCPServersConfig(
+        `[{"connectionType":"sse","sseUrl":"https://example.com/${"x".repeat(
+          3990
+        )}"}]`
+      )
+    ).toThrow(/\[truncated \d+ chars\]/);
+  });
+
+  it("rejects ambiguous or mixed stdio/sse field combinations", () => {
+    expect(() =>
+      parseMCPServersConfig(
+        '[{"command":"npx","sseUrl":"https://example.com/sse"}]'
+      )
+    ).toThrow(
+      'MCP server entry at index 0 is ambiguous: provide either "command" (stdio) or "sseUrl" (sse), or set explicit "connectionType".'
+    );
+
+    expect(() =>
+      parseMCPServersConfig(
+        '[{"connectionType":"sse","command":"npx","sseUrl":"https://example.com/sse"}]'
+      )
+    ).toThrow(
+      'MCP server entry at index 0 configured as sse cannot define stdio fields ("command", "args", or "env").'
+    );
+
+    expect(() =>
+      parseMCPServersConfig(
+        '[{"connectionType":"stdio","command":"npx","sseUrl":"https://example.com/sse"}]'
+      )
+    ).toThrow(
+      'MCP server entry at index 0 configured as stdio cannot define sse fields ("sseUrl" or "sseHeaders").'
+    );
+  });
+
+  it("throws when includeTools and excludeTools overlap", () => {
+    expect(() =>
+      parseMCPServersConfig(
+        '[{"command":"npx","includeTools":["search","notes"],"excludeTools":["notes"]}]'
+      )
+    ).toThrow(
+      "MCP server entry at index 0 has tools present in both includeTools and excludeTools: notes."
+    );
+
+    expect(() =>
+      parseMCPServersConfig(
+        '[{"command":"npx","includeTools":["Search"],"excludeTools":["search"]}]'
+      )
+    ).toThrow(
+      "MCP server entry at index 0 has tools present in both includeTools and excludeTools: Search."
+    );
+  });
+
+  it("truncates overlap diagnostics when many tool names collide", () => {
+    const includeTools = Array.from({ length: 12 }, (_, index) => `tool-${index}`);
+    const excludeTools = [...includeTools];
+    expect(() =>
+      parseMCPServersConfig(
+        JSON.stringify([
+          {
+            command: "npx",
+            includeTools,
+            excludeTools,
+          },
+        ])
+      )
+    ).toThrow(
+      "MCP server entry at index 0 has tools present in both includeTools and excludeTools: tool-0, tool-1, tool-2, tool-3, tool-4, tool-5, tool-6, tool-7, tool-8, tool-9, ... (+2 more)."
+    );
+  });
+});
+
+describe("loadMCPServersFromFile", () => {
+  it("throws when config file path is not a non-empty string", async () => {
+    await expect(
+      loadMCPServersFromFile("" as unknown as string)
+    ).rejects.toThrow(
+      "Failed to read MCP config file: path must be a non-empty string."
+    );
+    await expect(
+      loadMCPServersFromFile(42 as unknown as string)
+    ).rejects.toThrow(
+      "Failed to read MCP config file: path must be a non-empty string."
+    );
+  });
+
+  it("throws when config file path contains control characters", async () => {
+    await expect(
+      loadMCPServersFromFile("mcp\nconfig.json")
+    ).rejects.toThrow(
+      "Failed to read MCP config file: path contains unsupported control characters."
+    );
+  });
+
+  it("loads and parses server config from file", async () => {
+    const tempDir = await fs.promises.mkdtemp(
+      path.join(os.tmpdir(), "hyperagent-mcp-config-")
+    );
+    const filePath = path.join(tempDir, "mcp.json");
+    await fs.promises.writeFile(
+      filePath,
+      '[{"id":"demo","command":"npx","args":["-y","server"]}]',
+      "utf-8"
+    );
+
+    try {
+      const parsed = await loadMCPServersFromFile(filePath);
+      expect(parsed).toEqual([
+        {
+          id: "demo",
+          command: "npx",
+          args: ["-y", "server"],
+          connectionType: "stdio",
+        },
+      ]);
+    } finally {
+      await fs.promises.rm(tempDir, { recursive: true, force: true });
+    }
+  });
+
+  it("throws readable error when config file cannot be read", async () => {
+    await expect(
+      loadMCPServersFromFile("/tmp/does-not-exist-mcp-config.json")
+    ).rejects.toThrow(
+      'Failed to read MCP config file "/tmp/does-not-exist-mcp-config.json":'
+    );
+  });
+
+  it("sanitizes and truncates oversized config read diagnostics", async () => {
+    const statSpy = jest.spyOn(fs.promises, "stat").mockResolvedValue({
+      isFile: () => true,
+      size: 1,
+    } as unknown as fs.Stats);
+    const readFileSpy = jest
+      .spyOn(fs.promises, "readFile")
+      .mockRejectedValue(new Error(`read\u0000\n${"x".repeat(10_000)}`));
+
+    try {
+      await loadMCPServersFromFile("/tmp/mcp-config-test.json")
+        .then(() => {
+          throw new Error("expected loadMCPServersFromFile to reject");
+        })
+        .catch((error) => {
+          const message = String(error instanceof Error ? error.message : error);
+          expect(message).toContain("[truncated");
+          expect(message).not.toContain("\u0000");
+          expect(message).not.toContain("\n");
+          expect(message.length).toBeLessThan(700);
+        });
+    } finally {
+      statSpy.mockRestore();
+      readFileSpy.mockRestore();
+    }
+  });
+
+  it("throws readable error when config path is not a regular file", async () => {
+    const tempDir = await fs.promises.mkdtemp(
+      path.join(os.tmpdir(), "hyperagent-mcp-config-")
+    );
+
+    try {
+      await expect(loadMCPServersFromFile(tempDir)).rejects.toThrow(
+        `Failed to read MCP config file "${tempDir}": path is not a regular file.`
+      );
+    } finally {
+      await fs.promises.rm(tempDir, { recursive: true, force: true });
+    }
+  });
+
+  it("throws readable error when config file contents are invalid", async () => {
+    const tempDir = await fs.promises.mkdtemp(
+      path.join(os.tmpdir(), "hyperagent-mcp-config-")
+    );
+    const filePath = path.join(tempDir, "mcp.json");
+    await fs.promises.writeFile(filePath, "{broken", "utf-8");
+
+    try {
+      await expect(loadMCPServersFromFile(filePath)).rejects.toThrow(
+        `Invalid MCP config file "${filePath}": Invalid MCP config JSON`
+      );
+    } finally {
+      await fs.promises.rm(tempDir, { recursive: true, force: true });
+    }
+  });
+
+  it("throws when config file exceeds maximum allowed size", async () => {
+    const tempDir = await fs.promises.mkdtemp(
+      path.join(os.tmpdir(), "hyperagent-mcp-config-")
+    );
+    const filePath = path.join(tempDir, "mcp.json");
+    await fs.promises.writeFile(filePath, "x".repeat(1_000_001), "utf-8");
+
+    try {
+      await expect(loadMCPServersFromFile(filePath)).rejects.toThrow(
+        `Invalid MCP config file "${filePath}": config exceeds 1000000 characters.`
+      );
+    } finally {
+      await fs.promises.rm(tempDir, { recursive: true, force: true });
+    }
+  });
+});
diff --git a/src/cli/mcp-config.ts b/src/cli/mcp-config.ts
new file mode 100644
index 00000000..48a274d3
--- /dev/null
+++ b/src/cli/mcp-config.ts
@@ -0,0 +1,649 @@
+import fs from "node:fs";
+import { MCPServerConfig } from "@/types/config";
+import { formatUnknownError } from "@/utils";
+
+const MAX_MCP_CONFIG_FILE_CHARS = 1_000_000;
+const MAX_MCP_SERVER_ENTRIES = 100;
+const MAX_MCP_SERVER_ID_CHARS = 128;
+const MAX_MCP_COMMAND_CHARS = 2_048;
+const MAX_MCP_SSE_URL_CHARS = 4_000;
+const MAX_MCP_ARGS_PER_SERVER = 100;
+const MAX_MCP_ARG_CHARS = 4_000;
+const MAX_MCP_TOOL_LIST_ENTRIES = 200;
+const MAX_MCP_TOOL_NAME_CHARS = 256;
+const MAX_MCP_RECORD_ENTRIES = 200;
+const MAX_MCP_RECORD_KEY_CHARS = 256;
+const MAX_MCP_RECORD_VALUE_CHARS = 4_000;
+const MAX_MCP_OVERLAP_ERROR_ITEMS = 10;
+const MAX_MCP_CONFIG_DIAGNOSTIC_CHARS = 200;
+const UNSAFE_RECORD_KEYS = new Set(["__proto__", "prototype", "constructor"]);
+const HTTP_HEADER_NAME_PATTERN = /^[!#$%&'*+.^_`|~0-9A-Za-z-]+$/u;
+
+function hasUnsupportedControlChars(value: string): boolean {
+  return Array.from(value).some((char) => {
+    const code = char.charCodeAt(0);
+    return (
+      (code >= 0 && code < 32 && code !== 9 && code !== 10 && code !== 13) ||
+      code === 127
+    );
+  });
+}
+
+function hasAnyControlChars(value: string): boolean {
+  return Array.from(value).some((char) => {
+    const code = char.charCodeAt(0);
+    return (code >= 0 && code < 32) || code === 127;
+  });
+}
+
+function formatMCPConfigDiagnostic(value: unknown): string {
+  const raw = typeof value === "string" ? value : formatUnknownError(value);
+  const normalized = Array.from(raw, (char) => {
+    const code = char.charCodeAt(0);
+    return (code >= 0 && code < 32) || code === 127 ? " " : char;
+  })
+    .join("")
+    .replace(/\s+/g, " ")
+    .trim();
+  const fallback = normalized.length > 0 ? normalized : "unknown error";
+  if (fallback.length <= MAX_MCP_CONFIG_DIAGNOSTIC_CHARS) {
+    return fallback;
+  }
+  const omitted = fallback.length - MAX_MCP_CONFIG_DIAGNOSTIC_CHARS;
+  return `${fallback.slice(0, MAX_MCP_CONFIG_DIAGNOSTIC_CHARS)}... [truncated ${omitted} chars]`;
+}
+
+const isRecord = (value: unknown): value is Record<string, unknown> =>
+  typeof value === "object" && value !== null;
+
+const isNonEmptyString = (value: unknown): value is string =>
+  typeof value === "string" && value.trim().length > 0;
+
+function safeHasOwnProperty(
+  value: Record<string, unknown>,
+  key: string,
+  index: number
+): boolean {
+  try {
+    return Object.prototype.hasOwnProperty.call(value, key);
+  } catch {
+    throw new Error(
+      `MCP server entry at index ${index} has inaccessible "${key}" value.`
+    );
+  }
+}
+
+function safeReadRecordField(
+  value: Record<string, unknown>,
+  key: string,
+  index: number
+): unknown {
+  try {
+    return value[key];
+  } catch {
+    throw new Error(
+      `MCP server entry at index ${index} has inaccessible "${key}" value.`
+    );
+  }
+}
+
+function safeCloneRecord(
+  value: Record<string, unknown>,
+  index: number
+): Record<string, unknown> {
+  try {
+    return { ...value };
+  } catch {
+    throw new Error(
+      `MCP server entry at index ${index} has unreadable fields.`
+    );
+  }
+}
+
+function normalizeOptionalArgs(value: unknown, index: number): string[] | undefined {
+  if (typeof value === "undefined") {
+    return undefined;
+  }
+  if (!Array.isArray(value)) {
+    throw new Error(
+      `MCP server entry at index ${index} must provide "args" as an array of strings.`
+    );
+  }
+  let entries: unknown[];
+  try {
+    entries = Array.from(value);
+  } catch {
+    throw new Error(
+      `MCP server entry at index ${index} must provide "args" as an array of strings.`
+    );
+  }
+  if (!entries.every((entry) => typeof entry === "string")) {
+    throw new Error(
+      `MCP server entry at index ${index} must provide "args" as an array of strings.`
+    );
+  }
+  if (entries.length > MAX_MCP_ARGS_PER_SERVER) {
+    throw new Error(
+      `MCP server entry at index ${index} must provide no more than ${MAX_MCP_ARGS_PER_SERVER} "args" entries.`
+    );
+  }
+  const normalized = (entries as string[]).map((entry) => entry.trim());
+  if (
+    normalized.some(
+      (entry) =>
+        entry.length === 0 ||
+        entry.length > MAX_MCP_ARG_CHARS ||
+        hasAnyControlChars(entry)
+    )
+  ) {
+    throw new Error(
+      `MCP server entry at index ${index} must provide "args" as an array of non-empty strings.`
+    );
+  }
+  return normalized;
+}
+
+function normalizeOptionalStringRecord(
+  field: "env" | "sseHeaders",
+  value: unknown,
+  index: number
+): Record<string, string> | undefined {
+  if (typeof value === "undefined") {
+    return undefined;
+  }
+  if (!isRecord(value)) {
+    throw new Error(
+      `MCP server entry at index ${index} must provide "${field}" as an object of string key/value pairs.`
+    );
+  }
+  let entries: [string, unknown][];
+  try {
+    entries = Object.entries(value);
+  } catch {
+    throw new Error(
+      `MCP server entry at index ${index} must provide "${field}" as an object of string key/value pairs.`
+    );
+  }
+  if (entries.length > MAX_MCP_RECORD_ENTRIES) {
+    throw new Error(
+      `MCP server entry at index ${index} must provide no more than ${MAX_MCP_RECORD_ENTRIES} "${field}" entries.`
+    );
+  }
+
+  const normalized: Record<string, string> = Object.create(null);
+  const seenKeys = new Set<string>();
+  for (const [rawKey, rawValue] of entries) {
+    const key = rawKey.trim();
+    const normalizedKey = key.toLowerCase();
+    const isUnsafeKey = UNSAFE_RECORD_KEYS.has(normalizedKey);
+    if (
+      key.length === 0 ||
+      typeof rawValue !== "string" ||
+      isUnsafeKey ||
+      hasAnyControlChars(key) ||
+      hasAnyControlChars(rawValue)
+    ) {
+      throw new Error(
+        `MCP server entry at index ${index} must provide "${field}" as an object of string key/value pairs.`
+      );
+    }
+    if (
+      field === "sseHeaders" &&
+      !HTTP_HEADER_NAME_PATTERN.test(key)
+    ) {
+      throw new Error(
+        `MCP server entry at index ${index} must provide "${field}" as an object of string key/value pairs.`
+      );
+    }
+    const normalizedValue =
+      field === "sseHeaders" ? rawValue.trim() : rawValue;
+    if (
+      key.length > MAX_MCP_RECORD_KEY_CHARS ||
+      normalizedValue.length > MAX_MCP_RECORD_VALUE_CHARS
+    ) {
+      throw new Error(
+        `MCP server entry at index ${index} must provide "${field}" as an object of string key/value pairs.`
+      );
+    }
+    if (field === "sseHeaders" && normalizedValue.length === 0) {
+      throw new Error(
+        `MCP server entry at index ${index} must provide "${field}" as an object of string key/value pairs.`
+      );
+    }
+    const duplicateLookupKey = field === "sseHeaders" ? normalizedKey : key;
+    if (seenKeys.has(duplicateLookupKey)) {
+      throw new Error(
+        `MCP server entry at index ${index} has duplicate "${field}" key "${key}" after trimming.`
+      );
+    }
+    seenKeys.add(duplicateLookupKey);
+    normalized[key] = normalizedValue;
+  }
+  return normalized;
+}
+
+function normalizeSSEUrl(value: unknown, index: number): string {
+  const raw = isNonEmptyString(value) ? value.trim() : "";
+  if (raw.length === 0) {
+    throw new Error(
+      `MCP server entry at index ${index} must include a non-empty "sseUrl" for SSE connections.`
+    );
+  }
+  if (hasAnyControlChars(raw)) {
+    throw new Error(
+      `MCP server entry at index ${index} has invalid "sseUrl" value "${formatMCPConfigDiagnostic(raw)}".`
+    );
+  }
+  if (raw.length > MAX_MCP_SSE_URL_CHARS) {
+    throw new Error(
+      `MCP server entry at index ${index} has invalid "sseUrl" value "${formatMCPConfigDiagnostic(raw)}".`
+    );
+  }
+  let url: URL;
+  try {
+    url = new URL(raw);
+  } catch {
+    throw new Error(
+      `MCP server entry at index ${index} has invalid "sseUrl" value "${formatMCPConfigDiagnostic(raw)}".`
+    );
+  }
+  if (url.protocol !== "http:" && url.protocol !== "https:") {
+    throw new Error(
+      `MCP server entry at index ${index} has unsupported sseUrl protocol "${url.protocol}". Use http:// or https://.`
+    );
+  }
+  return url.toString();
+}
+
+function normalizeOptionalStringArray(
+  field: "includeTools" | "excludeTools",
+  value: unknown,
+  index: number
+): string[] | undefined {
+  if (typeof value === "undefined") {
+    return undefined;
+  }
+  if (!Array.isArray(value)) {
+    throw new Error(
+      `MCP server entry at index ${index} must provide "${field}" as an array of non-empty strings.`
+    );
+  }
+  let entries: unknown[];
+  try {
+    entries = Array.from(value);
+  } catch {
+    throw new Error(
+      `MCP server entry at index ${index} must provide "${field}" as an array of non-empty strings.`
+    );
+  }
+  if (entries.length > MAX_MCP_TOOL_LIST_ENTRIES) {
+    throw new Error(
+      `MCP server entry at index ${index} must provide no more than ${MAX_MCP_TOOL_LIST_ENTRIES} "${field}" entries.`
+    );
+  }
+  const trimmedValues = entries
+    .filter((entry): entry is string => typeof entry === "string")
+    .map((entry) => entry.trim())
+    .filter((entry) => entry.length > 0);
+
+  if (trimmedValues.length !== entries.length) {
+    throw new Error(
+      `MCP server entry at index ${index} must provide "${field}" as an array of non-empty strings.`
+    );
+  }
+  if (trimmedValues.some((entry) => hasAnyControlChars(entry))) {
+    throw new Error(
+      `MCP server entry at index ${index} must provide "${field}" as an array of non-empty strings.`
+    );
+  }
+  const normalized = trimmedValues.map((entry) => entry.replace(/\s+/g, " "));
+  if (
+    normalized.some(
+      (entry) =>
+        entry.length > MAX_MCP_TOOL_NAME_CHARS ||
+        hasAnyControlChars(entry)
+    )
+  ) {
+    throw new Error(
+      `MCP server entry at index ${index} must provide "${field}" as an array of non-empty strings.`
+    );
+  }
+
+  const seen = new Set<string>();
+  for (const toolName of normalized) {
+    const normalizedKey = toolName.toLowerCase();
+    if (seen.has(normalizedKey)) {
+      throw new Error(
+        `MCP server entry at index ${index} contains duplicate "${field}" value "${toolName}" after trimming.`
+      );
+    }
+    seen.add(normalizedKey);
+  }
+
+  return normalized;
+}
+
+function normalizeServersPayload(payload: unknown): unknown[] {
+  const ensureNonEmpty = (servers: unknown[]): unknown[] => {
+    let normalizedServers: unknown[];
+    try {
+      normalizedServers = Array.from(servers);
+    } catch {
+      throw new Error(
+        'MCP config must be a JSON array or an object with a "servers" array.'
+      );
+    }
+
+    if (normalizedServers.length === 0) {
+      throw new Error(
+        "MCP config must include at least one server entry."
+      );
+    }
+    if (normalizedServers.length > MAX_MCP_SERVER_ENTRIES) {
+      throw new Error(
+        `MCP config must include no more than ${MAX_MCP_SERVER_ENTRIES} server entries.`
+      );
+    }
+    return normalizedServers;
+  };
+
+  if (Array.isArray(payload)) {
+    return ensureNonEmpty(payload);
+  }
+  if (isRecord(payload)) {
+    let servers: unknown;
+    try {
+      servers = payload.servers;
+    } catch {
+      throw new Error(
+        'MCP config must be a JSON array or an object with a "servers" array.'
+      );
+    }
+    if (Array.isArray(servers)) {
+      return ensureNonEmpty(servers);
+    }
+  }
+  throw new Error(
+    'MCP config must be a JSON array or an object with a "servers" array.'
+  );
+}
+
+export function parseMCPServersConfig(rawConfig: string): MCPServerConfig[] {
+  if (typeof rawConfig !== "string") {
+    throw new Error("Invalid MCP config JSON: config must be a string.");
+  }
+  let parsed: unknown;
+  const normalizedConfig = rawConfig.replace(/^\uFEFF/, "").trim();
+  if (normalizedConfig.length === 0) {
+    throw new Error("Invalid MCP config JSON: config is empty.");
+  }
+  if (normalizedConfig.includes("\u0000")) {
+    throw new Error(
+      "Invalid MCP config JSON: config appears to be binary or contains null bytes."
+    );
+  }
+  if (hasUnsupportedControlChars(normalizedConfig)) {
+    throw new Error(
+      "Invalid MCP config JSON: config contains unsupported control characters."
+    );
+  }
+  if (normalizedConfig.length > MAX_MCP_CONFIG_FILE_CHARS) {
+    throw new Error(
+      `Invalid MCP config JSON: config exceeds ${MAX_MCP_CONFIG_FILE_CHARS} characters.`
+    );
+  }
+  try {
+    parsed = JSON.parse(normalizedConfig);
+  } catch (error) {
+    throw new Error(
+      `Invalid MCP config JSON: ${formatMCPConfigDiagnostic(error)}`
+    );
+  }
+
+  const servers = normalizeServersPayload(parsed);
+  const seenIds = new Set<string>();
+  const normalizedServers: MCPServerConfig[] = [];
+  for (let i = 0; i < servers.length; i += 1) {
+    const entry = servers[i];
+    if (!isRecord(entry)) {
+      throw new Error(`MCP server entry at index ${i} must be an object.`);
+    }
+    const idValue = safeReadRecordField(entry, "id", i);
+    const connectionTypeValue = safeReadRecordField(entry, "connectionType", i);
+    const argsValue = safeReadRecordField(entry, "args", i);
+    const envValue = safeReadRecordField(entry, "env", i);
+    const sseHeadersValue = safeReadRecordField(entry, "sseHeaders", i);
+    const includeToolsValue = safeReadRecordField(entry, "includeTools", i);
+    const excludeToolsValue = safeReadRecordField(entry, "excludeTools", i);
+    const commandValue = safeReadRecordField(entry, "command", i);
+    const sseUrlValue = safeReadRecordField(entry, "sseUrl", i);
+    if (
+      safeHasOwnProperty(entry, "id", i) &&
+      typeof idValue !== "string"
+    ) {
+      throw new Error(
+        `MCP server entry at index ${i} must provide "id" as a string when specified.`
+      );
+    }
+    if (
+      safeHasOwnProperty(entry, "connectionType", i) &&
+      typeof connectionTypeValue !== "string"
+    ) {
+      throw new Error(
+        `MCP server entry at index ${i} must provide "connectionType" as a string when specified.`
+      );
+    }
+    const normalizedEntry = safeCloneRecord(entry, i);
+    const args = normalizeOptionalArgs(argsValue, i);
+    const env = normalizeOptionalStringRecord("env", envValue, i);
+    const sseHeaders = normalizeOptionalStringRecord(
+      "sseHeaders",
+      sseHeadersValue,
+      i
+    );
+    const includeTools = normalizeOptionalStringArray(
+      "includeTools",
+      includeToolsValue,
+      i
+    );
+    const excludeTools = normalizeOptionalStringArray(
+      "excludeTools",
+      excludeToolsValue,
+      i
+    );
+    if (includeTools) {
+      normalizedEntry.includeTools = includeTools;
+    }
+    if (excludeTools) {
+      normalizedEntry.excludeTools = excludeTools;
+    }
+    if (args) {
+      normalizedEntry.args = args;
+    }
+    if (env) {
+      normalizedEntry.env = env;
+    }
+    if (sseHeaders) {
+      normalizedEntry.sseHeaders = sseHeaders;
+    }
+    if (includeTools && excludeTools) {
+      const excludeLookup = new Set(excludeTools.map((tool) => tool.toLowerCase()));
+      const overlap = includeTools.filter((tool) =>
+        excludeLookup.has(tool.toLowerCase())
+      );
+      if (overlap.length > 0) {
+        const overlapPreview = overlap.slice(0, MAX_MCP_OVERLAP_ERROR_ITEMS);
+        const omittedCount = overlap.length - overlapPreview.length;
+        const overlapSummary =
+          omittedCount > 0
+            ? `${overlapPreview.join(", ")}, ... (+${omittedCount} more)`
+            : overlapPreview.join(", ");
+        throw new Error(
+          `MCP server entry at index ${i} has tools present in both includeTools and excludeTools: ${overlapSummary}.`
+        );
+      }
+    }
+
+    const normalizedId = isNonEmptyString(idValue) ? idValue.trim() : "";
+    if (normalizedId.length > 0) {
+      if (hasAnyControlChars(normalizedId)) {
+        throw new Error(
+          `MCP server entry at index ${i} must provide "id" as a string when specified.`
+        );
+      }
+      if (normalizedId.length > MAX_MCP_SERVER_ID_CHARS) {
+        throw new Error(
+          `MCP server entry at index ${i} must provide "id" as a string when specified.`
+        );
+      }
+      const normalizedIdLookup = normalizedId.toLowerCase();
+      if (seenIds.has(normalizedIdLookup)) {
+        throw new Error(
+          `MCP server entry at index ${i} reuses duplicate id "${normalizedId}".`
+        );
+      }
+      seenIds.add(normalizedIdLookup);
+      normalizedEntry.id = normalizedId;
+    } else {
+      delete normalizedEntry.id;
+    }
+
+    const rawConnectionType = isNonEmptyString(connectionTypeValue)
+      ? connectionTypeValue.trim().toLowerCase()
+      : undefined;
+    if (
+      typeof rawConnectionType === "string" &&
+      hasAnyControlChars(rawConnectionType)
+    ) {
+      throw new Error(
+        `MCP server entry at index ${i} has unsupported connectionType "${formatMCPConfigDiagnostic(
+          connectionTypeValue
+        )}". Supported values are "stdio" and "sse".`
+      );
+    }
+    if (
+      rawConnectionType &&
+      rawConnectionType !== "stdio" &&
+      rawConnectionType !== "sse"
+    ) {
+      throw new Error(
+        `MCP server entry at index ${i} has unsupported connectionType "${formatMCPConfigDiagnostic(
+          connectionTypeValue
+        )}". Supported values are "stdio" and "sse".`
+      );
+    }
+    const hasCommand = isNonEmptyString(commandValue);
+    const hasSseUrl = isNonEmptyString(sseUrlValue);
+    if (!rawConnectionType && hasCommand && hasSseUrl) {
+      throw new Error(
+        `MCP server entry at index ${i} is ambiguous: provide either "command" (stdio) or "sseUrl" (sse), or set explicit "connectionType".`
+      );
+    }
+    const inferredConnectionType =
+      !rawConnectionType && hasSseUrl && !hasCommand ? "sse" : "stdio";
+    const connectionType = rawConnectionType === "sse"
+      ? "sse"
+      : rawConnectionType === "stdio"
+        ? "stdio"
+        : inferredConnectionType;
+    normalizedEntry.connectionType = connectionType;
+    if (connectionType === "sse") {
+      if (hasCommand || args || env) {
+        throw new Error(
+          `MCP server entry at index ${i} configured as sse cannot define stdio fields ("command", "args", or "env").`
+        );
+      }
+      const sseUrl = normalizeSSEUrl(sseUrlValue, i);
+      normalizedEntry.sseUrl = sseUrl;
+      normalizedServers.push(normalizedEntry as MCPServerConfig);
+      continue;
+    }
+
+    if (hasSseUrl || sseHeaders) {
+      throw new Error(
+        `MCP server entry at index ${i} configured as stdio cannot define sse fields ("sseUrl" or "sseHeaders").`
+      );
+    }
+
+    const command = isNonEmptyString(commandValue) ? commandValue.trim() : "";
+    if (command.length === 0) {
+      throw new Error(
+        `MCP server entry at index ${i} must include a non-empty "command" for stdio connections.`
+      );
+    }
+    if (hasAnyControlChars(command)) {
+      throw new Error(
+        `MCP server entry at index ${i} must include a non-empty "command" for stdio connections.`
+      );
+    }
+    if (command.length > MAX_MCP_COMMAND_CHARS) {
+      throw new Error(
+        `MCP server entry at index ${i} must include a non-empty "command" for stdio connections.`
+      );
+    }
+    normalizedEntry.command = command;
+    normalizedServers.push(normalizedEntry as MCPServerConfig);
+  }
+  return normalizedServers;
+}
+
+export async function loadMCPServersFromFile(
+  filePath: string
+): Promise<MCPServerConfig[]> {
+  if (typeof filePath !== "string" || filePath.trim().length === 0) {
+    throw new Error(
+      "Failed to read MCP config file: path must be a non-empty string."
+    );
+  }
+  const normalizedFilePath = filePath.trim();
+  if (hasAnyControlChars(normalizedFilePath)) {
+    throw new Error(
+      "Failed to read MCP config file: path contains unsupported control characters."
+    );
+  }
+
+  let fileStats: fs.Stats | undefined;
+  try {
+    fileStats = await fs.promises.stat(normalizedFilePath);
+  } catch {
+    // Fall through to readFile for missing/inaccessible path diagnostics.
+  }
+
+  if (fileStats && !fileStats.isFile()) {
+    throw new Error(
+      `Failed to read MCP config file "${normalizedFilePath}": path is not a regular file.`
+    );
+  }
+  if (fileStats && fileStats.size > MAX_MCP_CONFIG_FILE_CHARS) {
+    throw new Error(
+      `Invalid MCP config file "${normalizedFilePath}": config exceeds ${MAX_MCP_CONFIG_FILE_CHARS} characters.`
+    );
+  }
+
+  let fileContent: string;
+  try {
+    fileContent = await fs.promises.readFile(normalizedFilePath, "utf-8");
+  } catch (error) {
+    throw new Error(
+      `Failed to read MCP config file "${normalizedFilePath}": ${formatMCPConfigDiagnostic(
+        error
+      )}`
+    );
+  }
+
+  if (fileContent.length > MAX_MCP_CONFIG_FILE_CHARS) {
+    throw new Error(
+      `Invalid MCP config file "${normalizedFilePath}": config exceeds ${MAX_MCP_CONFIG_FILE_CHARS} characters.`
+    );
+  }
+
+  try {
+    return parseMCPServersConfig(fileContent);
+  } catch (error) {
+    throw new Error(
+      `Invalid MCP config file "${normalizedFilePath}": ${formatMCPConfigDiagnostic(
+        error
+      )}`
+    );
+  }
+}
diff --git a/src/cli/shutdown.test.ts b/src/cli/shutdown.test.ts
new file mode 100644
index 00000000..eaf0c3e1
--- /dev/null
+++ b/src/cli/shutdown.test.ts
@@ -0,0 +1,98 @@
+import { closeAgentSafely } from "@/cli/shutdown";
+
+describe("closeAgentSafely", () => {
+  it("returns success when closeAgent resolves", async () => {
+    const agent = {
+      closeAgent: jest.fn().mockResolvedValue(undefined),
+    };
+
+    await expect(
+      closeAgentSafely(agent as unknown as Parameters<typeof closeAgentSafely>[0])
+    ).resolves.toEqual({ success: true });
+  });
+
+  it("returns formatted message when closeAgent rejects", async () => {
+    const agent = {
+      closeAgent: jest.fn().mockRejectedValue({ reason: "close failed" }),
+    };
+
+    await expect(
+      closeAgentSafely(agent as unknown as Parameters<typeof closeAgentSafely>[0])
+    ).resolves.toEqual({
+      success: false,
+      message: '{"reason":"close failed"}',
+    });
+  });
+
+  it("reuses in-flight shutdown result for repeated calls", async () => {
+    const closeAgent = jest.fn().mockResolvedValue(undefined);
+    const agent = { closeAgent };
+
+    const [first, second] = await Promise.all([
+      closeAgentSafely(
+        agent as unknown as Parameters<typeof closeAgentSafely>[0]
+      ),
+      closeAgentSafely(
+        agent as unknown as Parameters<typeof closeAgentSafely>[0]
+      ),
+    ]);
+
+    expect(first).toEqual({ success: true });
+    expect(second).toEqual({ success: true });
+    expect(closeAgent).toHaveBeenCalledTimes(1);
+  });
+
+  it("allows retrying shutdown after prior attempt settles", async () => {
+    const closeAgent = jest
+      .fn()
+      .mockRejectedValueOnce(new Error("first failed"))
+      .mockResolvedValueOnce(undefined);
+    const agent = { closeAgent };
+
+    const first = await closeAgentSafely(
+      agent as unknown as Parameters<typeof closeAgentSafely>[0]
+    );
+    const second = await closeAgentSafely(
+      agent as unknown as Parameters<typeof closeAgentSafely>[0]
+    );
+
+    expect(first).toEqual({ success: false, message: "first failed" });
+    expect(second).toEqual({ success: true });
+    expect(closeAgent).toHaveBeenCalledTimes(2);
+  });
+
+  it("returns readable error for invalid agent objects", async () => {
+    await expect(closeAgentSafely(undefined)).resolves.toEqual({
+      success: false,
+      message: "Invalid agent instance: closeAgent() is unavailable.",
+    });
+    await expect(closeAgentSafely(42)).resolves.toEqual({
+      success: false,
+      message: "Invalid agent instance: closeAgent() is unavailable.",
+    });
+    await expect(closeAgentSafely({})).resolves.toEqual({
+      success: false,
+      message: "Invalid agent instance: closeAgent() is unavailable.",
+    });
+  });
+
+  it("returns readable error when closeAgent getter throws", async () => {
+    const agent = new Proxy(
+      {},
+      {
+        get: (_target, prop) => {
+          if (prop === "closeAgent") {
+            throw new Error("close getter trap");
+          }
+          return undefined;
+        },
+      }
+    );
+
+    await expect(closeAgentSafely(agent)).resolves.toEqual({
+      success: false,
+      message:
+        "Invalid agent instance: failed to access closeAgent() (close getter trap).",
+    });
+  });
+});
diff --git a/src/cli/shutdown.ts b/src/cli/shutdown.ts
new file mode 100644
index 00000000..dca8fc2f
--- /dev/null
+++ b/src/cli/shutdown.ts
@@ -0,0 +1,80 @@
+import { formatCliError } from "./format-cli-error";
+
+type ClosableAgent = {
+  closeAgent: () => Promise<void>;
+};
+
+const shutdownPromises = new WeakMap<
+  ClosableAgent,
+  Promise<{ success: true } | { success: false; message: string }>
+>();
+
+function isObjectLike(value: unknown): value is Record<string, unknown> {
+  return (
+    typeof value === "object" ||
+    typeof value === "function"
+  ) && value !== null;
+}
+
+function resolveCloseAgent(
+  agent: unknown
+): { closeAgent: () => Promise<void> } | { error: string } {
+  if (!isObjectLike(agent)) {
+    return {
+      error: "Invalid agent instance: closeAgent() is unavailable.",
+    };
+  }
+  let closeAgentValue: unknown;
+  try {
+    closeAgentValue = (agent as { closeAgent?: unknown }).closeAgent;
+  } catch (error) {
+    return {
+      error: `Invalid agent instance: failed to access closeAgent() (${formatCliError(
+        error
+      )}).`,
+    };
+  }
+  if (typeof closeAgentValue !== "function") {
+    return {
+      error: "Invalid agent instance: closeAgent() is unavailable.",
+    };
+  }
+  return {
+    closeAgent: closeAgentValue.bind(agent) as () => Promise<void>,
+  };
+}
+
+export async function closeAgentSafely(
+  agent: unknown
+): Promise<{ success: true } | { success: false; message: string }> {
+  const resolvedAgent = resolveCloseAgent(agent);
+  if ("error" in resolvedAgent) {
+    return {
+      success: false,
+      message: resolvedAgent.error,
+    };
+  }
+
+  const trackedAgent = agent as ClosableAgent;
+  const existing = shutdownPromises.get(trackedAgent);
+  if (existing) {
+    return existing;
+  }
+
+  const shutdownPromise = (async () => {
+    try {
+      await resolvedAgent.closeAgent();
+      return { success: true } as const;
+    } catch (error) {
+      return {
+        success: false as const,
+        message: formatCliError(error),
+      };
+    }
+  })().finally(() => {
+    shutdownPromises.delete(trackedAgent);
+  });
+
+  shutdownPromises.set(trackedAgent, shutdownPromise);
+  return shutdownPromise;
+}
diff --git a/src/cli/stdin-utils.test.ts b/src/cli/stdin-utils.test.ts
new file mode 100644
index 00000000..fdebd995
--- /dev/null
+++ b/src/cli/stdin-utils.test.ts
@@ -0,0 +1,76 @@
+import { setRawModeIfSupported } from "@/cli/stdin-utils";
+
+describe("setRawModeIfSupported", () => {
+  it("does nothing when input is not a TTY", () => {
+    const setRawMode = jest.fn();
+
+    setRawModeIfSupported(true, {
+      isTTY: false,
+      setRawMode,
+    });
+
+    expect(setRawMode).not.toHaveBeenCalled();
+  });
+
+  it("does nothing when setRawMode is unavailable", () => {
+    expect(() =>
+      setRawModeIfSupported(true, {
+        isTTY: true,
+      })
+    ).not.toThrow();
+  });
+
+  it("enables raw mode when supported", () => {
+    const setRawMode = jest.fn();
+
+    setRawModeIfSupported(true, {
+      isTTY: true,
+      setRawMode,
+    });
+
+    expect(setRawMode).toHaveBeenCalledWith(true);
+  });
+
+  it("logs warning instead of throwing when setRawMode fails", () => {
+    const warnSpy = jest.spyOn(console, "warn").mockImplementation(() => {});
+    const setRawMode = jest.fn(() => {
+      throw { reason: "tty unavailable" };
+    });
+
+    try {
+      expect(() =>
+        setRawModeIfSupported(true, {
+          isTTY: true,
+          setRawMode,
+        })
+      ).not.toThrow();
+      expect(warnSpy).toHaveBeenCalledWith(
+        '[CLI] Failed to set raw mode: {"reason":"tty unavailable"}'
+      );
+    } finally {
+      warnSpy.mockRestore();
+    }
+  });
+
+  it("sanitizes and truncates oversized raw-mode diagnostics", () => {
+    const warnSpy = jest.spyOn(console, "warn").mockImplementation(() => {});
+    const setRawMode = jest.fn(() => {
+      throw new Error(`tty\u0000\n${"x".repeat(10_000)}`);
+    });
+
+    try {
+      setRawModeIfSupported(true, {
+        isTTY: true,
+        setRawMode,
+      });
+
+      const warning = String(warnSpy.mock.calls[0]?.[0] ?? "");
+      expect(warning).toContain("[truncated");
+      expect(warning).not.toContain("\u0000");
+      expect(warning).not.toContain("\n");
+      expect(warning.length).toBeLessThan(2300);
+    } finally {
+      warnSpy.mockRestore();
+    }
+  });
+});
diff --git a/src/cli/stdin-utils.ts b/src/cli/stdin-utils.ts
new file mode 100644
index 00000000..34e8289e
--- /dev/null
+++ b/src/cli/stdin-utils.ts
@@ -0,0 +1,22 @@
+import { formatCliError } from "@/cli/format-cli-error";
+
+interface RawModeCapableInput {
+  isTTY?: boolean;
+  setRawMode?: (mode: boolean) => void;
+}
+
+export function setRawModeIfSupported(
+  enabled: boolean,
+  input: RawModeCapableInput = process.stdin as RawModeCapableInput
+): void {
+  if (!input.isTTY || typeof input.setRawMode !== "function") {
+    return;
+  }
+  try {
+    input.setRawMode(enabled);
+  } catch (error) {
+    console.warn(
+      `[CLI] Failed to set raw mode: ${formatCliError(error)}`
+    );
+  }
+}
diff --git a/src/cli/task-controls.test.ts b/src/cli/task-controls.test.ts
new file mode 100644
index 00000000..5e2eb897
--- /dev/null
+++ b/src/cli/task-controls.test.ts
@@ -0,0 +1,231 @@
+import { TaskStatus } from "@/types";
+import { pauseTaskIfRunning, resumeTaskIfPaused } from "@/cli/task-controls";
+
+describe("task-controls helpers", () => {
+  it("does nothing when pause is requested without a task", () => {
+    expect(pauseTaskIfRunning(undefined)).toBe(false);
+  });
+
+  it("pauses only when task is running", () => {
+    const pause = jest.fn();
+    const runningTask = {
+      getStatus: () => TaskStatus.RUNNING,
+      pause,
+    };
+    const pausedTask = {
+      getStatus: () => TaskStatus.PAUSED,
+      pause,
+    };
+
+    expect(pauseTaskIfRunning(runningTask)).toBe(true);
+    expect(pause).toHaveBeenCalledTimes(1);
+    expect(pauseTaskIfRunning(pausedTask)).toBe(false);
+    expect(pause).toHaveBeenCalledTimes(1);
+  });
+
+  it("does nothing when resume is requested without a task", () => {
+    expect(resumeTaskIfPaused(undefined)).toBe(false);
+  });
+
+  it("resumes only when task is paused", () => {
+    const resume = jest.fn();
+    const pausedTask = {
+      getStatus: () => TaskStatus.PAUSED,
+      resume,
+    };
+    const runningTask = {
+      getStatus: () => TaskStatus.RUNNING,
+      resume,
+    };
+
+    expect(resumeTaskIfPaused(pausedTask)).toBe(true);
+    expect(resume).toHaveBeenCalledTimes(1);
+    expect(resumeTaskIfPaused(runningTask)).toBe(false);
+    expect(resume).toHaveBeenCalledTimes(1);
+  });
+
+  it("returns false and warns when getStatus throws", () => {
+    const warnSpy = jest.spyOn(console, "warn").mockImplementation(() => {});
+    try {
+      expect(
+        pauseTaskIfRunning({
+          getStatus: () => {
+            throw { reason: "status failed" };
+          },
+          pause: jest.fn(),
+        })
+      ).toBe(false);
+
+      expect(
+        resumeTaskIfPaused({
+          getStatus: () => {
+            throw { reason: "status failed" };
+          },
+          resume: jest.fn(),
+        })
+      ).toBe(false);
+
+      expect(warnSpy).toHaveBeenCalledWith(
+        '[CLI] Failed to read task status for pause: {"reason":"status failed"}'
+      );
+      expect(warnSpy).toHaveBeenCalledWith(
+        '[CLI] Failed to read task status for resume: {"reason":"status failed"}'
+      );
+    } finally {
+      warnSpy.mockRestore();
+    }
+  });
+
+  it("returns false and warns when pause/resume handlers throw", () => {
+    const warnSpy = jest.spyOn(console, "warn").mockImplementation(() => {});
+    try {
+      expect(
+        pauseTaskIfRunning({
+          getStatus: () => TaskStatus.RUNNING,
+          pause: () => {
+            throw { reason: "pause failed" };
+          },
+        })
+      ).toBe(false);
+      expect(
+        resumeTaskIfPaused({
+          getStatus: () => TaskStatus.PAUSED,
+          resume: () => {
+            throw { reason: "resume failed" };
+          },
+        })
+      ).toBe(false);
+
+      expect(warnSpy).toHaveBeenCalledWith(
+        '[CLI] Failed to pause task: {"reason":"pause failed"}'
+      );
+      expect(warnSpy).toHaveBeenCalledWith(
+        '[CLI] Failed to resume task: {"reason":"resume failed"}'
+      );
+    } finally {
+      warnSpy.mockRestore();
+    }
+  });
+
+  it("returns false and warns when task methods are not callable", () => {
+    const warnSpy = jest.spyOn(console, "warn").mockImplementation(() => {});
+    try {
+      expect(
+        pauseTaskIfRunning({
+          getStatus: "running",
+          pause: jest.fn(),
+        } as unknown as Parameters<typeof pauseTaskIfRunning>[0])
+      ).toBe(false);
+      expect(
+        pauseTaskIfRunning({
+          getStatus: () => TaskStatus.RUNNING,
+          pause: "not-a-function",
+        } as unknown as Parameters<typeof pauseTaskIfRunning>[0])
+      ).toBe(false);
+
+      expect(
+        resumeTaskIfPaused({
+          getStatus: "paused",
+          resume: jest.fn(),
+        } as unknown as Parameters<typeof resumeTaskIfPaused>[0])
+      ).toBe(false);
+      expect(
+        resumeTaskIfPaused({
+          getStatus: () => TaskStatus.PAUSED,
+          resume: "not-a-function",
+        } as unknown as Parameters<typeof resumeTaskIfPaused>[0])
+      ).toBe(false);
+
+      expect(warnSpy).toHaveBeenCalledWith(
+        "[CLI] Failed to read task status for pause: task.getStatus is not callable"
+      );
+      expect(warnSpy).toHaveBeenCalledWith(
+        "[CLI] Failed to pause task: task.pause is not callable"
+      );
+      expect(warnSpy).toHaveBeenCalledWith(
+        "[CLI] Failed to read task status for resume: task.getStatus is not callable"
+      );
+      expect(warnSpy).toHaveBeenCalledWith(
+        "[CLI] Failed to resume task: task.resume is not callable"
+      );
+    } finally {
+      warnSpy.mockRestore();
+    }
+  });
+
+  it("returns false and warns when task method getters are trap-prone", () => {
+    const warnSpy = jest.spyOn(console, "warn").mockImplementation(() => {});
+    const pauseTask = new Proxy(
+      {},
+      {
+        get: (_target, prop) => {
+          if (prop === "getStatus") {
+            throw new Error("status trap");
+          }
+          return undefined;
+        },
+      }
+    );
+    const resumeTask = new Proxy(
+      {},
+      {
+        get: (_target, prop) => {
+          if (prop === "resume") {
+            throw new Error("resume trap");
+          }
+          if (prop === "getStatus") {
+            return () => TaskStatus.PAUSED;
+          }
+          return undefined;
+        },
+      }
+    );
+    try {
+      expect(
+        pauseTaskIfRunning(
+          pauseTask as unknown as Parameters<typeof pauseTaskIfRunning>[0]
+        )
+      ).toBe(false);
+      expect(
+        resumeTaskIfPaused(
+          resumeTask as unknown as Parameters<typeof resumeTaskIfPaused>[0]
+        )
+      ).toBe(false);
+
+      expect(warnSpy).toHaveBeenCalledWith(
+        "[CLI] Failed to read task status for pause: task.getStatus is inaccessible (status trap)"
+      );
+      expect(warnSpy).toHaveBeenCalledWith(
+        "[CLI] Failed to resume task: task.resume is inaccessible (resume trap)"
+      );
+    } finally {
+      warnSpy.mockRestore();
+    }
+  });
+
+  it("sanitizes and truncates oversized task-control diagnostics", () => {
+    const warnSpy = jest.spyOn(console, "warn").mockImplementation(() => {});
+    const oversizedError = new Error(`status\u0000\n${"x".repeat(10_000)}`);
+    try {
+      expect(
+        pauseTaskIfRunning({
+          getStatus: () => {
+            throw oversizedError;
+          },
+          pause: jest.fn(),
+        })
+      ).toBe(false);
+
+      const warning = warnSpy.mock.calls
+        .map((call) => String(call[0]))
+        .find((line) => line.includes("Failed to read task status for pause"));
+      expect(warning).toBeDefined();
+      expect(warning).toContain("[truncated");
+      expect(warning).not.toContain("\u0000");
+      expect(warning).not.toContain("\n");
+      expect(warning?.length ?? 0).toBeLessThan(2_500);
+    } finally {
+      warnSpy.mockRestore();
+    }
+  });
+});
diff --git a/src/cli/task-controls.ts b/src/cli/task-controls.ts
new file mode 100644
index 00000000..5d836241
--- /dev/null
+++ b/src/cli/task-controls.ts
@@ -0,0 +1,85 @@
+import { TaskStatus } from "@/types";
+import { formatCliError } from "./format-cli-error";
+
+type PauseableTask = {
+  getStatus: () => TaskStatus;
+  pause: () => void;
+};
+
+type ResumableTask = {
+  getStatus: () => TaskStatus;
+  resume: () => void;
+};
+
+function readTaskMethod<T extends "getStatus" | "pause" | "resume">(
+  task: unknown,
+  method: T
+): () => unknown {
+  if (!task || typeof task !== "object") {
+    throw new Error("task instance is unavailable");
+  }
+  let value: unknown;
+  try {
+    value = (task as Record<string, unknown>)[method];
+  } catch (error) {
+    throw new Error(`task.${method} is inaccessible (${formatCliError(error)})`);
+  }
+  if (typeof value !== "function") {
+    throw new Error(`task.${method} is not callable`);
+  }
+  return value.bind(task);
+}
+
+export function pauseTaskIfRunning(task?: PauseableTask): boolean {
+  if (!task) {
+    return false;
+  }
+  let status: TaskStatus;
+  try {
+    status = readTaskMethod(task, "getStatus")() as TaskStatus;
+  } catch (error) {
+    console.warn(
+      `[CLI] Failed to read task status for pause: ${formatCliError(error)}`
+    );
+    return false;
+  }
+  if (status !== TaskStatus.RUNNING) {
+    return false;
+  }
+  try {
+    readTaskMethod(task, "pause")();
+  } catch (error) {
+    console.warn(
+      `[CLI] Failed to pause task: ${formatCliError(error)}`
+    );
+    return false;
+  }
+  return true;
+}
+
+export function resumeTaskIfPaused(task?: ResumableTask): boolean {
+  if (!task) {
+    return false;
+  }
+  let status: TaskStatus;
+  try {
+    status = readTaskMethod(task, "getStatus")() as TaskStatus;
+  } catch (error) {
+    console.warn(
+      `[CLI] Failed to read task status for resume: ${formatCliError(error)}`
+    );
+    return false;
+  }
+  if (status !== TaskStatus.PAUSED) {
+    return false;
+  }
+  try {
+    readTaskMethod(task, "resume")();
+  } catch (error) {
+    console.warn(
+      `[CLI] Failed to resume task: ${formatCliError(error)}`
+    );
+    return false;
+  }
+  return true;
+}
diff --git a/src/cli/task-error-handler.test.ts b/src/cli/task-error-handler.test.ts
new file mode 100644
index 00000000..16726631
--- /dev/null
+++ b/src/cli/task-error-handler.test.ts
@@ -0,0 +1,186 @@
+import { EventEmitter } from "node:events";
+import type { Task } from "@/types";
+import { attachTaskErrorHandler } from "@/cli/task-error-handler";
+
+describe("attachTaskErrorHandler", () => {
+  it("cancels task and forwards error payloads to callback", () => {
+    const emitter = new EventEmitter();
+    const cancel = jest.fn();
+    const onError = jest.fn();
+    const task = {
+      cancel,
+      emitter,
+    } as unknown as Task;
+
+    attachTaskErrorHandler(task, onError);
+
+    const errorPayload = { reason: "task failed" };
+    emitter.emit("error", errorPayload);
+
+    expect(cancel).toHaveBeenCalledTimes(1);
+    expect(onError).toHaveBeenCalledWith(errorPayload);
+  });
+
+  it("logs readable message when error callback itself throws", () => {
+    const emitter = new EventEmitter();
+    const cancel = jest.fn();
+    const errorSpy = jest.spyOn(console, "error").mockImplementation(() => {});
+    const task = {
+      cancel,
+      emitter,
+    } as unknown as Task;
+
+    try {
+      attachTaskErrorHandler(task, () => {
+        throw { reason: "callback blew up" };
+      });
+
+      emitter.emit("error", { reason: "task failed" });
+
+      expect(cancel).toHaveBeenCalledTimes(1);
+      expect(errorSpy).toHaveBeenCalledWith(
+        '[CLI] Task error handler failed: {"reason":"callback blew up"}'
+      );
+    } finally {
+      errorSpy.mockRestore();
+    }
+  });
+
+  it("handles only the first emitted task error", () => {
+    const emitter = new EventEmitter();
+    const cancel = jest.fn();
+    const onError = jest.fn();
+    const task = {
+      cancel,
+      emitter,
+    } as unknown as Task;
+
+    attachTaskErrorHandler(task, onError);
+
+    emitter.emit("error", { reason: "first" });
+    emitter.emit("error", { reason: "second" });
+
+    expect(cancel).toHaveBeenCalledTimes(1);
+    expect(onError).toHaveBeenCalledTimes(1);
+    expect(onError).toHaveBeenCalledWith({ reason: "first" });
+  });
+
+  it("logs cancellation failures but still forwards error to callback", () => {
+    const emitter = new EventEmitter();
+    const cancel = jest.fn(() => {
+      throw { reason: "cancel failed" };
+    });
+    const onError = jest.fn();
+    const errorSpy = jest.spyOn(console, "error").mockImplementation(() => {});
+    const task = {
+      cancel,
+      emitter,
+    } as unknown as Task;
+
+    try {
+      attachTaskErrorHandler(task, onError);
+      emitter.emit("error", { reason: "task failed" });
+
+      expect(onError).toHaveBeenCalledWith({ reason: "task failed" });
+      expect(errorSpy).toHaveBeenCalledWith(
+        '[CLI] Failed to cancel task after error: {"reason":"cancel failed"}'
+      );
+    } finally {
+      errorSpy.mockRestore();
+    }
+  });
+
+  it("logs when task emitter is unavailable", () => {
+    const errorSpy = jest.spyOn(console, "error").mockImplementation(() => {});
+    try {
+      attachTaskErrorHandler(
+        {
+          cancel: jest.fn(),
+          emitter: undefined,
+        } as unknown as Task,
+        jest.fn()
+      );
+
+      expect(errorSpy).toHaveBeenCalledWith(
+        "[CLI] Cannot attach task error handler: task emitter is unavailable"
+      );
+    } finally {
+      errorSpy.mockRestore();
+    }
+  });
+
+  it("logs when task emitter getter throws during attachment", () => {
+    const errorSpy = jest.spyOn(console, "error").mockImplementation(() => {});
+    const task = new Proxy(
+      {
+        cancel: jest.fn(),
+      },
+      {
+        get: (target, prop, receiver) => {
+          if (prop === "emitter") {
+            throw new Error("emitter trap");
+          }
+          return Reflect.get(target, prop, receiver);
+        },
+      }
+    ) as unknown as Task;
+    try {
+      attachTaskErrorHandler(task, jest.fn());
+
+      expect(errorSpy).toHaveBeenCalledWith(
+        "[CLI] Failed to access task emitter: emitter trap"
+      );
+      expect(errorSpy).toHaveBeenCalledWith(
+        "[CLI] Cannot attach task error handler: task emitter is unavailable"
+      );
+    } finally {
+      errorSpy.mockRestore();
+    }
+  });
+
+  it("logs when addListener registration throws", () => {
+    const errorSpy = jest.spyOn(console, "error").mockImplementation(() => {});
+    const task = {
+      cancel: jest.fn(),
+      emitter: {
+        addListener: () => {
+          throw { reason: "listener failed" };
+        },
+      },
+    } as unknown as Task;
+    try {
+      attachTaskErrorHandler(task, jest.fn());
+
+      expect(errorSpy).toHaveBeenCalledWith(
+        '[CLI] Failed to attach task error listener: {"reason":"listener failed"}'
+      );
+    } finally {
+      errorSpy.mockRestore();
+    }
+  });
+
+  it("sanitizes and truncates oversized listener attachment diagnostics", () => {
+    const errorSpy = jest.spyOn(console, "error").mockImplementation(() => {});
+    const task = {
+      cancel: jest.fn(),
+      emitter: {
+        addListener: () => {
+          throw new Error(`listener\u0000\n${"x".repeat(10_000)}`);
+        },
+      },
+    } as unknown as Task;
+    try {
+      attachTaskErrorHandler(task, jest.fn());
+      const message = errorSpy.mock.calls
+        .map((call) => String(call[0]))
+        .find((line) => line.includes("Failed to attach task error listener"));
+      expect(message).toBeDefined();
+      expect(message).toContain("[truncated");
+      expect(message).not.toContain("\u0000");
+      expect(message).not.toContain("\n");
+      expect(message?.length ?? 0).toBeLessThan(2_500);
+    } finally {
+      errorSpy.mockRestore();
+    }
+  });
+});
diff --git a/src/cli/task-error-handler.ts b/src/cli/task-error-handler.ts
new file mode 100644
index 00000000..0752f33e
--- /dev/null
+++ b/src/cli/task-error-handler.ts
@@ -0,0 +1,71 @@
+import type { Task } from "@/types";
+import { formatCliError } from "./format-cli-error";
+
+export type TaskErrorHandler = (error: unknown) => void;
+
+function safeReadTaskField(
+  task: Task,
+  field: "emitter" | "cancel"
+): unknown {
+  try {
+    return (task as unknown as Record<string, unknown>)[field];
+  } catch (error) {
+    console.error(
+      `[CLI] Failed to access task ${field}: ${formatCliError(error)}`
+    );
+    return undefined;
+  }
+}
+
+export function attachTaskErrorHandler(
+  task: Task,
+  onError: TaskErrorHandler
+): void {
+  if (typeof onError !== "function") {
+    console.error("[CLI] Cannot attach task error handler: onError must be a function");
+    return;
+  }
+
+  const emitter = safeReadTaskField(task, "emitter");
+  const addListener =
+    emitter && typeof emitter === "object"
+      ? (emitter as { addListener?: unknown }).addListener
+      : undefined;
+  if (typeof addListener !== "function") {
+    console.error(
+      "[CLI] Cannot attach task error handler: task emitter is unavailable"
+    );
+    return;
+  }
+
+  let hasHandledError = false;
+  try {
+    addListener.call(emitter, "error", (error: unknown) => {
+      if (hasHandledError) {
+        return;
+      }
+      hasHandledError = true;
+      const cancel = safeReadTaskField(task, "cancel");
+      if (typeof cancel === "function") {
+        try {
+          cancel.call(task);
+        } catch (cancelError) {
+          console.error(
+            `[CLI] Failed to cancel task after error: ${formatCliError(cancelError)}`
+          );
+        }
+      }
+      try {
+        onError(error);
+      } catch (handlerError) {
+        console.error(
+          `[CLI] Task error handler failed: ${formatCliError(handlerError)}`
+        );
+      }
+    });
+  } catch (error) {
+    console.error(
+      `[CLI] Failed to attach task error listener: ${formatCliError(error)}`
+    );
+  }
+}
diff --git a/src/cli/task-input.test.ts b/src/cli/task-input.test.ts
new file mode 100644
index 00000000..fd0daba4
--- /dev/null
+++ b/src/cli/task-input.test.ts
@@ -0,0 +1,215 @@
+import fs from "node:fs";
+import os from "node:os";
+import path from "node:path";
+import {
+  loadTaskDescriptionFromFile,
+  normalizeTaskDescription,
+} from "@/cli/task-input";
+
+describe("normalizeTaskDescription", () => {
+  it("returns trimmed non-empty values", () => {
+    expect(
+      normalizeTaskDescription("  do the thing  ", "Task description from --command")
+    ).toBe("do the thing");
+  });
+
+  it("removes UTF-8 BOM prefix before validation", () => {
+    expect(
+      normalizeTaskDescription(
+        "\uFEFFdo the thing",
+        "Task description from --command"
+      )
+    ).toBe("do the thing");
+  });
+
+  it("throws readable error for empty values after trim", () => {
+    expect(() =>
+      normalizeTaskDescription("   ", "Task description from --command")
+    ).toThrow(
+      "Task description from --command is empty after trimming whitespace. Please provide a non-empty task description."
+    );
+  });
+
+  it("throws when task description input is not a string", () => {
+    expect(() =>
+      normalizeTaskDescription(
+        42 as unknown as string,
+        "Task description from --command"
+      )
+    ).toThrow(
+      "Task description from --command must be a string. Please provide plain text."
+    );
+  });
+
+  it("sanitizes and truncates oversized source labels in errors", () => {
+    const oversizedLabel = `source-${"x".repeat(400)}`;
+    expect(() =>
+      normalizeTaskDescription(
+        42 as unknown as string,
+        oversizedLabel
+      )
+    ).toThrow("[truncated");
+    expect(() =>
+      normalizeTaskDescription(
+        42 as unknown as string,
+        oversizedLabel
+      )
+    ).toThrow("must be a string");
+  });
+
+  it("throws when task descriptions exceed the allowed size", () => {
+    expect(() =>
+      normalizeTaskDescription(
+        "x".repeat(20001),
+        "Task description from --command"
+      )
+    ).toThrow(
+      "Task description from --command exceeds 20000 characters. Please provide a shorter task description."
+    );
+  });
+
+  it("throws when task description contains null bytes", () => {
+    expect(() =>
+      normalizeTaskDescription(
+        "hello\u0000world",
+        "Task description from --command"
+      )
+    ).toThrow(
+      "Task description from --command appears to be binary or contains null bytes. Please provide plain text."
+    );
+  });
+
+  it("throws when task description contains unsupported control characters", () => {
+    expect(() =>
+      normalizeTaskDescription(
+        "hello\u0007world",
+        "Task description from --command"
+      )
+    ).toThrow(
+      "Task description from --command contains unsupported control characters. Please provide plain text."
+    );
+  });
+});
+
+describe("loadTaskDescriptionFromFile", () => {
+  it("throws when task file path is not a non-empty string", async () => {
+    await expect(
+      loadTaskDescriptionFromFile("" as unknown as string)
+    ).rejects.toThrow("Task description file path must be a non-empty string.");
+    await expect(
+      loadTaskDescriptionFromFile(42 as unknown as string)
+    ).rejects.toThrow("Task description file path must be a non-empty string.");
+  });
+
+  it("throws when task file path contains control characters", async () => {
+    await expect(
+      loadTaskDescriptionFromFile("task\nfile.txt")
+    ).rejects.toThrow(
+      "Task description file path contains unsupported control characters."
+    );
+  });
+
+  it("loads and trims task description text", async () => {
+    const tempDir = await fs.promises.mkdtemp(
+      path.join(os.tmpdir(), "hyperagent-task-input-")
+    );
+    const filePath = path.join(tempDir, "task.txt");
+    await fs.promises.writeFile(filePath, "  do the thing  \n", "utf-8");
+
+    try {
+      await expect(loadTaskDescriptionFromFile(filePath)).resolves.toBe(
+        "do the thing"
+      );
+    } finally {
+      await fs.promises.rm(tempDir, { recursive: true, force: true });
+    }
+  });
+
+  it("throws readable error for missing files", async () => {
+    await expect(
+      loadTaskDescriptionFromFile("/tmp/does-not-exist-task-file.txt")
+    ).rejects.toThrow(
+      'Failed to read task description file "/tmp/does-not-exist-task-file.txt":'
+    );
+  });
+
+  it("sanitizes and truncates oversized read-file diagnostics", async () => {
+    const statSpy = jest.spyOn(fs.promises, "stat").mockResolvedValue({
+      isFile: () => true,
+      size: 1,
+    } as unknown as fs.Stats);
+    const readFileSpy = jest
+      .spyOn(fs.promises, "readFile")
+      .mockRejectedValue(new Error(`read\u0000\n${"x".repeat(10_000)}`));
+
+    try {
+      await loadTaskDescriptionFromFile("/tmp/task-input-test.txt")
+        .then(() => {
+          throw new Error("expected loadTaskDescriptionFromFile to reject");
+        })
+        .catch((error) => {
+          const message = String(error instanceof Error ? error.message : error);
+          expect(message).toContain("[truncated");
+          expect(message).not.toContain("\u0000");
+          expect(message).not.toContain("\n");
+          expect(message.length).toBeLessThan(700);
+        });
+    } finally {
+      statSpy.mockRestore();
+      readFileSpy.mockRestore();
+    }
+  });
+
+  it("throws when file path is not a regular file", async () => {
+    const tempDir = await fs.promises.mkdtemp(
+      path.join(os.tmpdir(), "hyperagent-task-input-")
+    );
+
+    try {
+      await expect(loadTaskDescriptionFromFile(tempDir)).rejects.toThrow(
+        `Task description file "${tempDir}" must be a regular text file.`
+      );
+    } finally {
+      await fs.promises.rm(tempDir, { recursive: true, force: true });
+    }
+  });
+
+  it("throws when file exceeds maximum byte size", async () => {
+    const tempDir = await fs.promises.mkdtemp(
+      path.join(os.tmpdir(), "hyperagent-task-input-")
+    );
+    const filePath = path.join(tempDir, "task.txt");
+    await fs.promises.writeFile(filePath, "x".repeat(1_000_001), "utf-8");
+
+    try {
+      await expect(loadTaskDescriptionFromFile(filePath)).rejects.toThrow(
+        `Task description file "${filePath}" exceeds 1000000 bytes. Please provide a smaller text file.`
+      );
+    } finally {
+      await fs.promises.rm(tempDir, { recursive: true, force: true });
+    }
+  });
+
+  it("truncates oversized file-path diagnostics", async () => {
+    const longPath = `/tmp/${"x".repeat(400)}`;
+    await expect(loadTaskDescriptionFromFile(longPath)).rejects.toThrow(
+      "[truncated"
+    );
+  });
+
+  it("throws when file content is empty after trimming", async () => {
+    const tempDir = await fs.promises.mkdtemp(
+      path.join(os.tmpdir(), "hyperagent-task-input-")
+    );
+    const filePath = path.join(tempDir, "task.txt");
+    await fs.promises.writeFile(filePath, "   \n\t  ", "utf-8");
+
+    try {
+      await expect(loadTaskDescriptionFromFile(filePath)).rejects.toThrow(
+        `Task description file "${filePath}" is empty after trimming whitespace. Please provide a non-empty task description.`
+      );
+    } finally {
+      await fs.promises.rm(tempDir, { recursive: true, force: true });
+    }
+  });
+});
diff --git a/src/cli/task-input.ts b/src/cli/task-input.ts
new file mode 100644
index 00000000..3543dc13
--- /dev/null
+++ b/src/cli/task-input.ts
@@ -0,0 +1,127 @@
+import fs from "node:fs";
+import { formatUnknownError } from "@/utils";
+
+const MAX_TASK_DESCRIPTION_CHARS = 20_000;
+const MAX_TASK_FILE_BYTES = 1_000_000;
+const MAX_TASK_INPUT_DIAGNOSTIC_CHARS = 200;
+
+function hasUnsupportedControlChars(value: string): boolean {
+  return Array.from(value).some((char) => {
+    const code = char.charCodeAt(0);
+    return (code >= 0 && code < 32 && code !== 9 && code !== 10 && code !== 13) || code === 127;
+  });
+}
+
+function hasAnyControlChars(value: string): boolean {
+  return Array.from(value).some((char) => {
+    const code = char.charCodeAt(0);
+    return (code >= 0 && code < 32) || code === 127;
+  });
+}
+
+function formatTaskInputDiagnostic(value: string): string {
+  const sanitized = Array.from(value)
+    .map((char) => {
+      const code = char.charCodeAt(0);
+      return (code >= 0 && code < 32) || code === 127 ? " " : char;
+    })
+    .join("")
+    .replace(/\s+/g, " ")
+    .trim();
+  if (sanitized.length <= MAX_TASK_INPUT_DIAGNOSTIC_CHARS) {
+    return sanitized;
+  }
+  return `${sanitized.slice(
+    0,
+    MAX_TASK_INPUT_DIAGNOSTIC_CHARS
+  )}... [truncated ${sanitized.length - MAX_TASK_INPUT_DIAGNOSTIC_CHARS} chars]`;
+}
+
+function formatTaskInputUnknownDiagnostic(value: unknown): string {
+  return formatTaskInputDiagnostic(formatUnknownError(value)) || "unknown error";
+}
+
+export function normalizeTaskDescription(
+  value: string,
+  sourceLabel: string
+): string {
+  const safeSourceLabel = formatTaskInputDiagnostic(sourceLabel);
+  if (typeof value !== "string") {
+    throw new Error(
+      `${safeSourceLabel} must be a string. Please provide plain text.`
+    );
+  }
+  const trimmed = value.replace(/^\uFEFF/, "").trim();
+  if (trimmed.includes("\u0000")) {
+    throw new Error(
+      `${safeSourceLabel} appears to be binary or contains null bytes. Please provide plain text.`
+    );
+  }
+  if (hasUnsupportedControlChars(trimmed)) {
+    throw new Error(
+      `${safeSourceLabel} contains unsupported control characters. Please provide plain text.`
+    );
+  }
+  if (trimmed.length === 0) {
+    throw new Error(
+      `${safeSourceLabel} is empty after trimming whitespace. Please provide a non-empty task description.`
+    );
+  }
+  if (trimmed.length > MAX_TASK_DESCRIPTION_CHARS) {
+    throw new Error(
+      `${safeSourceLabel} exceeds ${MAX_TASK_DESCRIPTION_CHARS} characters. Please provide a shorter task description.`
+    );
+  }
+  return trimmed;
+}
+
+export async function loadTaskDescriptionFromFile(
+  filePath: string
+): Promise<string> {
+  if (typeof filePath !== "string" || filePath.trim().length === 0) {
+    throw new Error(
+      "Task description file path must be a non-empty string."
+    );
+  }
+  const normalizedFilePath = filePath.trim();
+  const safeFilePath = formatTaskInputDiagnostic(normalizedFilePath);
+  if (hasAnyControlChars(normalizedFilePath)) {
+    throw new Error(
+      "Task description file path contains unsupported control characters."
+    );
+  }
+
+  let fileStats: fs.Stats | undefined;
+  try {
+    fileStats = await fs.promises.stat(normalizedFilePath);
+  } catch {
+    // Fall back to readFile error handling for missing/inaccessible paths.
+  }
+
+  if (fileStats && !fileStats.isFile()) {
+    throw new Error(
+      `Task description file "${safeFilePath}" must be a regular text file.`
+    );
+  }
+  if (fileStats && fileStats.size > MAX_TASK_FILE_BYTES) {
+    throw new Error(
+      `Task description file "${safeFilePath}" exceeds ${MAX_TASK_FILE_BYTES} bytes. Please provide a smaller text file.`
+    );
+  }
+
+  let content: string;
+  try {
+    content = await fs.promises.readFile(normalizedFilePath, "utf-8");
+  } catch (error) {
+    throw new Error(
+      `Failed to read task description file "${safeFilePath}": ${formatTaskInputUnknownDiagnostic(
+        error
+      )}`
+    );
+  }
+
+  return normalizeTaskDescription(
+    content,
+    `Task description file "${safeFilePath}"`
+  );
+}
diff --git a/src/context-providers/a11y-dom/bounding-box-batch.test.ts b/src/context-providers/a11y-dom/bounding-box-batch.test.ts
new file mode 100644
index 00000000..a4789cd4
--- /dev/null
+++ b/src/context-providers/a11y-dom/bounding-box-batch.test.ts
@@ -0,0 +1,107 @@
+import type { CDPSession } from "@/cdp";
+import { ensureScriptInjected } from "@/cdp/script-injector";
+import {
+  batchCollectBoundingBoxesWithFailures,
+  type BoundingBoxTarget,
+} from "@/context-providers/a11y-dom/bounding-box-batch";
+import type { EncodedId } from "@/context-providers/a11y-dom/types";
+
+jest.mock("@/cdp/script-injector", () => ({
+  ensureScriptInjected: jest.fn(),
+}));
+
+const mockedEnsureScriptInjected = ensureScriptInjected as jest.MockedFunction<
+  typeof ensureScriptInjected
+>;
+
+function createSession(
+  sendImplementation?: <T = unknown>(
+    method: string,
+    params?: Record<string, unknown>
+  ) => Promise<T>
+): CDPSession {
+  return {
+    id: "session-1",
+    raw: undefined,
+    send:
+      sendImplementation ??
+      (async <T = unknown>(_method: string): Promise<T> => ({}) as T),
+    on: jest.fn(),
+    off: jest.fn(),
+    detach: jest.fn(async () => undefined),
+  };
+}
+
+function createTarget(session: CDPSession, frameId: string): BoundingBoxTarget {
+  return {
+    kind: "cdp",
+    session,
+    frameId,
+  };
+}
+
+describe("batchCollectBoundingBoxesWithFailures diagnostics", () => {
+  beforeEach(() => {
+    jest.clearAllMocks();
+    mockedEnsureScriptInjected.mockResolvedValue(undefined);
+  });
+
+  it("formats non-Error Runtime.callFunctionOn failures deterministically", async () => {
+    const warnSpy = jest.spyOn(console, "warn").mockImplementation(() => {});
+    const encodedId = "0-101" as EncodedId;
+    const session = createSession(
+      async <T = unknown>(method: string): Promise<T> => {
+      if (method === "Runtime.callFunctionOn") {
+        throw { reason: "batch bbox object failure" };
+      }
+      return {} as T;
+      }
+    );
+
+    try {
+      const result = await batchCollectBoundingBoxesWithFailures(
+        createTarget(session, "frame-main"),
+        { [encodedId]: "//button" },
+        [{ backendDOMNodeId: 101, encodedId }],
+        0
+      );
+
+      expect(result.boundingBoxMap.size).toBe(0);
+      expect(result.failures).toEqual([{ encodedId, backendNodeId: 101 }]);
+      expect(warnSpy).toHaveBeenCalledWith(
+        expect.stringContaining('{"reason":"batch bbox object failure"}')
+      );
+    } finally {
+      warnSpy.mockRestore();
+    }
+  });
+
+  it("sanitizes and truncates oversized batch-collection diagnostics", async () => {
+    const warnSpy = jest.spyOn(console, "warn").mockImplementation(() => {});
+    const encodedId = "3-202" as EncodedId;
+    mockedEnsureScriptInjected.mockRejectedValueOnce(
+      new Error(`inject\u0000\n${"x".repeat(10_000)}`)
+    );
+    const session = createSession();
+    const noisyFrameId = `frame\u0000\n${"y".repeat(500)}`;
+
+    try {
+      const result = await batchCollectBoundingBoxesWithFailures(
+        createTarget(session, noisyFrameId),
+        { [encodedId]: "//input" },
+        [{ backendDOMNodeId: 202, encodedId }],
+        3
+      );
+
+      expect(result.boundingBoxMap.size).toBe(0);
+      expect(result.failures).toEqual([{ encodedId, backendNodeId: 202 }]);
+      const diagnostic = String(warnSpy.mock.calls[0]?.[0] ?? "");
+      expect(diagnostic).toContain("[truncated");
+      expect(diagnostic).not.toContain("\u0000");
+      expect(diagnostic).not.toContain("\n");
+      expect(diagnostic.length).toBeLessThan(900);
+    } finally {
+      warnSpy.mockRestore();
+    }
+  });
+});
diff --git a/src/context-providers/a11y-dom/bounding-box-batch.ts b/src/context-providers/a11y-dom/bounding-box-batch.ts
index 1123a4cc..8a4672a6 100644
--- a/src/context-providers/a11y-dom/bounding-box-batch.ts
+++ b/src/context-providers/a11y-dom/bounding-box-batch.ts
@@ -5,6 +5,7 @@
 
 import type { CDPSession } from "@/cdp";
 import { ensureScriptInjected } from "@/cdp/script-injector";
+import { formatUnknownError } from "@/utils";
 import { EncodedId, DOMRect, IframeInfo } from "./types";
 import { createEncodedId } from "./utils";
 
@@ -15,6 +16,53 @@ export type BoundingBoxTarget = {
   frameId: string;
 };
 
+const MAX_BOUNDING_BOX_BATCH_DIAGNOSTIC_CHARS = 400;
+const MAX_BOUNDING_BOX_BATCH_IDENTIFIER_CHARS = 128;
+
+function sanitizeBoundingBoxBatchText(value: string): string {
+  if (value.length === 0) {
+    return value;
+  }
+  const withoutControlChars = Array.from(value, (char) => {
+    const code = char.charCodeAt(0);
+    return (code >= 0 && code < 32) || code === 127 ? " " : char;
+  }).join("");
+  return withoutControlChars.replace(/\s+/g, " ").trim();
+}
+
+function truncateBoundingBoxBatchText(value: string, maxChars: number): string {
+  if (value.length <= maxChars) {
+    return value;
+  }
+  const omittedChars = value.length - maxChars;
+  return `${value.slice(0, maxChars)}... [truncated ${omittedChars} chars]`;
+}
+
+function formatBoundingBoxBatchDiagnostic(value: unknown): string {
+  const normalized = sanitizeBoundingBoxBatchText(formatUnknownError(value));
+  if (normalized.length === 0) {
+    return "unknown error";
+  }
+  return truncateBoundingBoxBatchText(
+    normalized,
+    MAX_BOUNDING_BOX_BATCH_DIAGNOSTIC_CHARS
+  );
+}
+
+function formatBoundingBoxBatchIdentifier(value: unknown): string {
+  if (typeof value !== "string") {
+    return "unknown-frame";
+  }
+  const normalized = sanitizeBoundingBoxBatchText(value);
+  if (normalized.length === 0) {
+    return "unknown-frame";
+  }
+  return truncateBoundingBoxBatchText(
+    normalized,
+    MAX_BOUNDING_BOX_BATCH_IDENTIFIER_CHARS
+  );
+}
+
 function translateBoundingRect(
   rect: DOMRect,
   offsetX: number,
@@ -302,8 +350,9 @@ async function batchCollectBoundingBoxesViaCDP(
     return boundingBoxMap;
   } catch (error) {
     console.warn(
-      `[A11y] Batch bounding box collection via CDP failed for frame ${frameIndex} (${frameId}):`,
-      error
+      `[A11y] Batch bounding box collection via CDP failed for frame ${frameIndex} (${formatBoundingBoxBatchIdentifier(
+        frameId
+      )}): ${formatBoundingBoxBatchDiagnostic(error)}`
     );
     return new Map();
   }
diff --git a/src/context-providers/a11y-dom/build-maps.test.ts b/src/context-providers/a11y-dom/build-maps.test.ts
new file mode 100644
index 00000000..5e7aff4b
--- /dev/null
+++ b/src/context-providers/a11y-dom/build-maps.test.ts
@@ -0,0 +1,66 @@
+import { buildBackendIdMaps } from "@/context-providers/a11y-dom/build-maps";
+import type { CDPSession } from "@/cdp";
+
+describe("buildBackendIdMaps", () => {
+  it("formats non-Error failures when DOM document fetch fails", async () => {
+    const errorSpy = jest.spyOn(console, "error").mockImplementation(() => {});
+    const session: CDPSession = {
+      id: "session-1",
+      raw: undefined,
+      send: async <T = unknown>(method: string): Promise<T> => {
+        if (method === "DOM.getDocument") {
+          throw { reason: "dom document object failure" };
+        }
+        return {} as T;
+      },
+      on: jest.fn(),
+      off: jest.fn(),
+      detach: jest.fn(async () => undefined),
+    };
+
+    try {
+      const result = await buildBackendIdMaps(session);
+
+      expect(result.tagNameMap).toEqual({});
+      expect(result.xpathMap).toEqual({});
+      expect(result.accessibleNameMap).toEqual({});
+      expect(result.backendNodeMap).toEqual({});
+      expect(result.frameMap?.size ?? 0).toBe(0);
+      expect(errorSpy).toHaveBeenCalledWith(
+        'Error building backend ID maps: {"reason":"dom document object failure"}'
+      );
+    } finally {
+      errorSpy.mockRestore();
+    }
+  });
+
+  it("sanitizes and truncates oversized DOM document fetch diagnostics", async () => {
+    const errorSpy = jest.spyOn(console, "error").mockImplementation(() => {});
+    const session: CDPSession = {
+      id: "session-1",
+      raw: undefined,
+      send: async <T = unknown>(method: string): Promise<T> => {
+        if (method === "DOM.getDocument") {
+          throw new Error(`dom\u0000\n${"x".repeat(10_000)}`);
+        }
+        return {} as T;
+      },
+      on: jest.fn(),
+      off: jest.fn(),
+      detach: jest.fn(async () => undefined),
+    };
+
+    try {
+      const result = await buildBackendIdMaps(session);
+
+      expect(result.tagNameMap).toEqual({});
+      const diagnostic = String(errorSpy.mock.calls[0]?.[0] ?? "");
+      expect(diagnostic).toContain("[truncated");
+      expect(diagnostic).not.toContain("\u0000");
+      expect(diagnostic).not.toContain("\n");
+      expect(diagnostic.length).toBeLessThan(700);
+    } finally {
+      errorSpy.mockRestore();
+    }
+  });
+});
diff --git a/src/context-providers/a11y-dom/build-maps.ts b/src/context-providers/a11y-dom/build-maps.ts
index c697a298..a0bbe8b7 100644
--- a/src/context-providers/a11y-dom/build-maps.ts
+++ b/src/context-providers/a11y-dom/build-maps.ts
@@ -11,6 +11,28 @@ import {
   DOMRect,
 } from "./types";
 import { createEncodedId } from "./utils";
+import { formatUnknownError } from "@/utils";
+
+const MAX_BUILD_MAPS_DIAGNOSTIC_CHARS = 400;
+
+function formatBuildMapsDiagnostic(error: unknown): string {
+  const normalized = Array.from(formatUnknownError(error), (char) => {
+    const code = char.charCodeAt(0);
+    return (code >= 0 && code < 32) || code === 127 ? " " : char;
+  })
+    .join("")
+    .replace(/\s+/g, " ")
+    .trim();
+  const fallback = normalized.length > 0 ? normalized : "unknown error";
+  if (fallback.length <= MAX_BUILD_MAPS_DIAGNOSTIC_CHARS) {
+    return fallback;
+  }
+  const omitted = fallback.length - MAX_BUILD_MAPS_DIAGNOSTIC_CHARS;
+  return `${fallback.slice(
+    0,
+    MAX_BUILD_MAPS_DIAGNOSTIC_CHARS
+  )}... [truncated ${omitted} chars]`;
+}
 
 async function annotateIframeBoundingBoxes(
   session: CDPSession,
@@ -362,7 +384,9 @@ export async function buildBackendIdMaps(
       frameMap,
     };
   } catch (error) {
-    console.error("Error building backend ID maps:", error);
+    console.error(
+      `Error building backend ID maps: ${formatBuildMapsDiagnostic(error)}`
+    );
     return {
       tagNameMap: {},
       xpathMap: {},
diff --git a/src/context-providers/a11y-dom/index.test.ts b/src/context-providers/a11y-dom/index.test.ts
new file mode 100644
index 00000000..51d489a0
--- /dev/null
+++ b/src/context-providers/a11y-dom/index.test.ts
@@ -0,0 +1,541 @@
+import type { Page } from "playwright-core";
+import { getA11yDOM } from "@/context-providers/a11y-dom";
+import { domSnapshotCache } from "@/context-providers/a11y-dom/dom-cache";
+
+const getCDPClientMock = jest.fn();
+const getOrCreateFrameContextManagerMock = jest.fn();
+const buildBackendIdMapsMock = jest.fn();
+
+jest.mock("@/cdp", () => ({
+  getCDPClient: (...args: unknown[]) => getCDPClientMock(...args),
+  getOrCreateFrameContextManager: (...args: unknown[]) =>
+    getOrCreateFrameContextManagerMock(...args),
+}));
+
+jest.mock("./build-maps", () => ({
+  buildBackendIdMaps: (...args: unknown[]) => buildBackendIdMapsMock(...args),
+}));
+
+const getDebugOptionsMock = jest.fn(() => ({
+  enabled: false,
+  profileDomCapture: false,
+}));
+
+jest.mock("@/debug/options", () => ({
+  getDebugOptions: () => getDebugOptionsMock(),
+}));
+
+describe("getA11yDOM error formatting", () => {
+  beforeEach(() => {
+    getCDPClientMock.mockReset();
+    getOrCreateFrameContextManagerMock.mockReset();
+    getDebugOptionsMock.mockReset();
+    buildBackendIdMapsMock.mockReset();
+    getDebugOptionsMock.mockReturnValue({
+      enabled: false,
+      profileDomCapture: false,
+    });
+  });
+
+  it("formats non-Error failures from script injection and returns fallback state", async () => {
+    const errorSpy = jest.spyOn(console, "error").mockImplementation(() => {});
+    const page = {
+      evaluate: jest.fn().mockRejectedValue({ reason: "inject failed" }),
+    } as unknown as Page;
+
+    try {
+      const result = await getA11yDOM(page);
+
+      expect(result.domState).toBe("Error: Could not extract accessibility tree");
+      expect(result.elements.size).toBe(0);
+      expect(result.frameMap?.size ?? 0).toBe(0);
+      expect(errorSpy).toHaveBeenCalledWith(
+        'Error extracting accessibility tree: {"reason":"inject failed"}'
+      );
+    } finally {
+      errorSpy.mockRestore();
+    }
+  });
+
+  it("sanitizes and truncates oversized extraction diagnostics", async () => {
+    const errorSpy = jest.spyOn(console, "error").mockImplementation(() => {});
+    const page = {
+      evaluate: jest
+        .fn()
+        .mockRejectedValue(new Error(`inject\u0000\n${"x".repeat(10_000)}`)),
+    } as unknown as Page;
+
+    try {
+      const result = await getA11yDOM(page);
+
+      expect(result.domState).toBe("Error: Could not extract accessibility tree");
+      const diagnostic = String(errorSpy.mock.calls[0]?.[0] ?? "");
+      expect(diagnostic).toContain("[truncated");
+      expect(diagnostic).not.toContain("\u0000");
+      expect(diagnostic).not.toContain("\n");
+    } finally {
+      errorSpy.mockRestore();
+    }
+  });
+
+  it("sanitizes nested error-detail payloads for extraction failures", async () => {
+    const errorSpy = jest.spyOn(console, "error").mockImplementation(() => {});
+    const page = {
+      evaluate: jest
+        .fn()
+        .mockRejectedValue(new Error(`detail\u0000\n${"x".repeat(5_000)}`)),
+    } as unknown as Page;
+
+    try {
+      await getA11yDOM(page);
+
+      const detailsCall = errorSpy.mock.calls.find(
+        (call) => String(call[0] ?? "") === "Error details:"
+      );
+      expect(detailsCall).toBeDefined();
+      const details = (detailsCall?.[1] ?? {}) as {
+        message?: string;
+        stack?: string;
+      };
+      expect(details.message).toContain("[truncated");
+      expect(details.message).not.toContain("\u0000");
+      expect(details.message).not.toContain("\n");
+      expect(details.stack ?? "").not.toContain("\u0000");
+      expect((details.stack ?? "").length).toBeLessThan(700);
+    } finally {
+      errorSpy.mockRestore();
+    }
+  });
+
+  it("continues when frame manager debug setter throws", async () => {
+    const warnSpy = jest.spyOn(console, "warn").mockImplementation(() => {});
+    const errorSpy = jest.spyOn(console, "error").mockImplementation(() => {});
+    const page = {
+      evaluate: jest.fn().mockResolvedValue(undefined),
+    } as unknown as Page;
+    getCDPClientMock.mockResolvedValue({
+      acquireSession: jest
+        .fn()
+        .mockRejectedValue(new Error("dom session unavailable")),
+    });
+    getOrCreateFrameContextManagerMock.mockReturnValue({
+      setDebug: jest.fn(() => {
+        throw new Error(`debug\u0000\n${"x".repeat(5_000)}`);
+      }),
+      ensureInitialized: jest.fn().mockResolvedValue(undefined),
+    });
+
+    try {
+      const result = await getA11yDOM(page);
+      expect(result.domState).toBe("Error: Could not extract accessibility tree");
+      const warning = String(
+        warnSpy.mock.calls.find((call) =>
+          String(call[0] ?? "").includes("configure frame manager debug")
+        )?.[0] ?? ""
+      );
+      expect(warning).toContain("[truncated");
+      expect(warning).not.toContain("\u0000");
+      expect(warning).not.toContain("\n");
+    } finally {
+      warnSpy.mockRestore();
+      errorSpy.mockRestore();
+    }
+  });
+
+  it("continues when frame manager filtering setter throws", async () => {
+    const warnSpy = jest.spyOn(console, "warn").mockImplementation(() => {});
+    const errorSpy = jest.spyOn(console, "error").mockImplementation(() => {});
+    const page = {
+      evaluate: jest.fn().mockResolvedValue(undefined),
+    } as unknown as Page;
+    getCDPClientMock.mockResolvedValue({
+      acquireSession: jest
+        .fn()
+        .mockRejectedValue(new Error("dom session unavailable")),
+    });
+    getOrCreateFrameContextManagerMock.mockReturnValue({
+      setDebug: jest.fn(),
+      setFrameFilteringEnabled: jest.fn(() => {
+        throw new Error(`filter\u0000\n${"y".repeat(5_000)}`);
+      }),
+      ensureInitialized: jest.fn().mockResolvedValue(undefined),
+    });
+
+    try {
+      const result = await getA11yDOM(page, false, false, undefined, {
+        filterAdTrackingFrames: false,
+      });
+      expect(result.domState).toBe("Error: Could not extract accessibility tree");
+      const warning = String(
+        warnSpy.mock.calls.find((call) =>
+          String(call[0] ?? "").includes("configure frame filtering")
+        )?.[0] ?? ""
+      );
+      expect(warning).toContain("[truncated");
+      expect(warning).not.toContain("\u0000");
+      expect(warning).not.toContain("\n");
+    } finally {
+      warnSpy.mockRestore();
+      errorSpy.mockRestore();
+    }
+  });
+
+  it("continues when debug options lookup throws", async () => {
+    const warnSpy = jest.spyOn(console, "warn").mockImplementation(() => {});
+    const errorSpy = jest.spyOn(console, "error").mockImplementation(() => {});
+    const page = {
+      evaluate: jest.fn().mockResolvedValue(undefined),
+    } as unknown as Page;
+    getDebugOptionsMock.mockImplementationOnce(() => {
+      throw new Error(`debug\u0000\n${"x".repeat(5_000)}`);
+    });
+    getCDPClientMock.mockResolvedValue({
+      acquireSession: jest
+        .fn()
+        .mockRejectedValue(new Error("dom session unavailable")),
+    });
+    getOrCreateFrameContextManagerMock.mockReturnValue({
+      setDebug: jest.fn(),
+      ensureInitialized: jest.fn().mockResolvedValue(undefined),
+    });
+
+    try {
+      const result = await getA11yDOM(page);
+      expect(result.domState).toBe("Error: Could not extract accessibility tree");
+      const warning = String(
+        warnSpy.mock.calls.find((call) =>
+          String(call[0] ?? "").includes("Failed to read debug options")
+        )?.[0] ?? ""
+      );
+      expect(warning).toContain("[truncated");
+      expect(warning).not.toContain("\u0000");
+      expect(warning).not.toContain("\n");
+    } finally {
+      warnSpy.mockRestore();
+      errorSpy.mockRestore();
+    }
+  });
+
+  it("continues when a11y options getters trap", async () => {
+    const errorSpy = jest.spyOn(console, "error").mockImplementation(() => {});
+    const page = {
+      evaluate: jest.fn().mockResolvedValue(undefined),
+    } as unknown as Page;
+    getCDPClientMock.mockResolvedValue({
+      acquireSession: jest
+        .fn()
+        .mockRejectedValue(new Error("dom session unavailable")),
+    });
+    const setFrameFilteringEnabled = jest.fn();
+    getOrCreateFrameContextManagerMock.mockReturnValue({
+      setDebug: jest.fn(),
+      setFrameFilteringEnabled,
+      ensureInitialized: jest.fn().mockResolvedValue(undefined),
+    });
+    const trappedOptions = new Proxy(
+      {},
+      {
+        get: (_target, prop: string | symbol) => {
+          if (
+            prop === "filterAdTrackingFrames" ||
+            prop === "useCache" ||
+            prop === "onFrameChunk"
+          ) {
+            throw new Error("a11y options trap");
+          }
+          return undefined;
+        },
+      }
+    );
+
+    try {
+      const result = await getA11yDOM(
+        page,
+        false,
+        false,
+        undefined,
+        trappedOptions as unknown as Parameters<typeof getA11yDOM>[4]
+      );
+      expect(result.domState).toBe("Error: Could not extract accessibility tree");
+      expect(setFrameFilteringEnabled).not.toHaveBeenCalled();
+    } finally {
+      errorSpy.mockRestore();
+    }
+  });
+
+  it("continues when runtime listener method getter traps during context collection", async () => {
+    const warnSpy = jest.spyOn(console, "warn").mockImplementation(() => {});
+    const errorSpy = jest.spyOn(console, "error").mockImplementation(() => {});
+    const page = {
+      evaluate: jest.fn().mockResolvedValue(undefined),
+      url: jest.fn(() => "https://example.com"),
+    } as unknown as Page;
+    const session = {
+      id: "session-1",
+      send: jest.fn(async (method: string) => {
+        if (method === "Accessibility.getFullAXTree") {
+          throw new Error("stop after context collection");
+        }
+        return {};
+      }),
+      get on() {
+        throw new Error(`listener-on\u0000\n${"x".repeat(2_000)}`);
+      },
+      off: jest.fn(),
+    };
+    getCDPClientMock.mockResolvedValue({
+      acquireSession: jest.fn().mockResolvedValue(session),
+    });
+    getOrCreateFrameContextManagerMock.mockReturnValue({
+      setDebug: jest.fn(),
+      ensureInitialized: jest.fn().mockResolvedValue(undefined),
+      captureOOPIFs: jest.fn().mockResolvedValue(undefined),
+      setFrameFilteringEnabled: jest.fn(),
+    });
+    buildBackendIdMapsMock.mockResolvedValue({
+      frameMap: new Map([
+        [
+          1,
+          {
+            frameIndex: 1,
+            siblingPosition: 0,
+            src: "https://example.com/frame",
+            xpath: "//iframe[1]",
+            parentFrameIndex: 0,
+            frameId: "frame-1",
+          },
+        ],
+      ]),
+      backendNodeMap: {},
+      xpathMap: {},
+      frameMetadataMap: new Map(),
+      frameTree: new Map(),
+    });
+
+    try {
+      const result = await getA11yDOM(page, true);
+      expect(result.domState).toBe("Error: Could not extract accessibility tree");
+      const warning = String(
+        warnSpy.mock.calls.find((call) =>
+          String(call[0] ?? "").includes(
+            "Failed to read Runtime.executionContextCreated listener method"
+          )
+        )?.[0] ?? ""
+      );
+      expect(warning).toContain("[truncated");
+      expect(warning).not.toContain("\u0000");
+      expect(warning).not.toContain("\n");
+    } finally {
+      warnSpy.mockRestore();
+      errorSpy.mockRestore();
+    }
+  });
+
+  it("continues when runtime sender getter traps during context collection", async () => {
+    const warnSpy = jest.spyOn(console, "warn").mockImplementation(() => {});
+    const errorSpy = jest.spyOn(console, "error").mockImplementation(() => {});
+    const page = {
+      evaluate: jest.fn().mockResolvedValue(undefined),
+      url: jest.fn(() => "https://example.com"),
+    } as unknown as Page;
+    let sendGetterReadCount = 0;
+    const session = {
+      id: "session-1",
+      get send() {
+        sendGetterReadCount += 1;
+        if (sendGetterReadCount === 2) {
+          throw new Error(`runtime-send\u0000\n${"x".repeat(2_000)}`);
+        }
+        return async (method: string) => {
+          if (method === "Accessibility.getFullAXTree") {
+            throw new Error("stop after context collection");
+          }
+          return {};
+        };
+      },
+      on: jest.fn(),
+      off: jest.fn(),
+    };
+    getCDPClientMock.mockResolvedValue({
+      acquireSession: jest.fn().mockResolvedValue(session),
+    });
+    getOrCreateFrameContextManagerMock.mockReturnValue({
+      setDebug: jest.fn(),
+      ensureInitialized: jest.fn().mockResolvedValue(undefined),
+      captureOOPIFs: jest.fn().mockResolvedValue(undefined),
+      setFrameFilteringEnabled: jest.fn(),
+    });
+    buildBackendIdMapsMock.mockResolvedValue({
+      frameMap: new Map([
+        [
+          1,
+          {
+            frameIndex: 1,
+            siblingPosition: 0,
+            src: "https://example.com/frame",
+            xpath: "//iframe[1]",
+            parentFrameIndex: 0,
+            frameId: "frame-1",
+          },
+        ],
+      ]),
+      backendNodeMap: {},
+      xpathMap: {},
+      frameMetadataMap: new Map(),
+      frameTree: new Map(),
+    });
+
+    try {
+      const result = await getA11yDOM(page, true);
+      expect(result.domState).toBe("Error: Could not extract accessibility tree");
+      const warning = String(
+        warnSpy.mock.calls.find((call) =>
+          String(call[0] ?? "").includes("Failed to read Runtime.enable sender")
+        )?.[0] ?? ""
+      );
+      expect(warning).toContain("[truncated");
+      expect(warning).not.toContain("\u0000");
+      expect(warning).not.toContain("\n");
+    } finally {
+      warnSpy.mockRestore();
+      errorSpy.mockRestore();
+    }
+  });
+
+  it("continues when sync frame-manager debug setter traps", async () => {
+    const logSpy = jest.spyOn(console, "log").mockImplementation(() => {});
+    const warnSpy = jest.spyOn(console, "warn").mockImplementation(() => {});
+    const errorSpy = jest.spyOn(console, "error").mockImplementation(() => {});
+    const page = {
+      evaluate: jest.fn().mockResolvedValue(undefined),
+      url: jest.fn(() => "https://example.com"),
+    } as unknown as Page;
+    const session = {
+      id: "session-1",
+      send: jest.fn(async (method: string) => {
+        if (method === "Accessibility.getFullAXTree") {
+          return { nodes: [] };
+        }
+        if (method === "Page.getFrameTree") {
+          throw new Error("frame tree unavailable");
+        }
+        return {};
+      }),
+      on: jest.fn(),
+      off: jest.fn(),
+    };
+    getCDPClientMock.mockResolvedValue({
+      rootSession: session,
+      acquireSession: jest.fn().mockResolvedValue(session),
+    });
+    getOrCreateFrameContextManagerMock.mockReturnValue({
+      setDebug: jest
+        .fn()
+        .mockImplementationOnce(() => undefined)
+        .mockImplementation(() => {
+          throw new Error(`sync-debug\u0000\n${"x".repeat(2_000)}`);
+        }),
+      ensureInitialized: jest.fn().mockResolvedValue(undefined),
+      captureOOPIFs: jest.fn().mockResolvedValue(undefined),
+      setFrameFilteringEnabled: jest.fn(),
+      getOOPIFs: jest.fn(() => []),
+      getFrameIndex: jest.fn(),
+      getFrameSession: jest.fn(),
+      getExecutionContextId: jest.fn(),
+      getFrameIdByIndex: jest.fn(),
+      getFrameByBackendNodeId: jest.fn(),
+      setFrameSession: jest.fn(),
+      upsertFrame: jest.fn(),
+      assignFrameIndex: jest.fn(),
+    });
+    buildBackendIdMapsMock.mockResolvedValue({
+      frameMap: new Map(),
+      backendNodeMap: {},
+      xpathMap: {},
+      frameMetadataMap: new Map(),
+      frameTree: new Map(),
+    });
+
+    try {
+      const result = await getA11yDOM(page, true);
+      expect(result.domState).toBe("Error: Could not extract accessibility tree");
+      const warning = String(
+        warnSpy.mock.calls.find((call) =>
+          String(call[0] ?? "").includes("Failed to configure sync debug mode")
+        )?.[0] ?? ""
+      );
+      expect(warning).toContain("[truncated");
+      expect(warning).not.toContain("\u0000");
+      expect(warning).not.toContain("\n");
+    } finally {
+      logSpy.mockRestore();
+      warnSpy.mockRestore();
+      errorSpy.mockRestore();
+    }
+  });
+
+  it("continues cache hydration when frame-manager debug setter traps", async () => {
+    const page = {
+      url: jest.fn(() => "https://example.com"),
+    } as unknown as Page;
+    const cachedState = {
+      domState: "cached dom",
+      elements: new Map(),
+      xpathMap: {},
+      backendNodeMap: {},
+      frameMap: new Map([
+        [
+          1,
+          {
+            frameIndex: 1,
+            siblingPosition: 0,
+            frameId: "frame-1",
+            xpath: "//iframe[1]",
+            parentFrameIndex: 0,
+          },
+        ],
+      ]),
+    } as unknown as Parameters<typeof domSnapshotCache.set>[1];
+    domSnapshotCache.set(page, cachedState);
+
+    const rootSession = {
+      id: "session-1",
+      send: jest.fn().mockResolvedValue({
+        frameTree: {
+          frame: {
+            id: "root-frame",
+            parentId: undefined,
+            loaderId: "loader-1",
+            name: "root",
+            url: "https://example.com",
+          },
+        },
+      }),
+    };
+    const ensureInitialized = jest.fn().mockResolvedValue(undefined);
+    getCDPClientMock.mockResolvedValue({
+      rootSession,
+    });
+    getOrCreateFrameContextManagerMock.mockReturnValue({
+      setDebug: jest.fn(() => {
+        throw new Error("cache-hydration debug trap");
+      }),
+      ensureInitialized,
+      upsertFrame: jest.fn(),
+      assignFrameIndex: jest.fn(),
+      setFrameSession: jest.fn(),
+      getFrameByBackendNodeId: jest.fn(),
+      getFrameSession: jest.fn(),
+    });
+
+    try {
+      const result = await getA11yDOM(page, false, false, undefined, {
+        useCache: true,
+      });
+      expect(result.domState).toBe("cached dom");
+      expect(ensureInitialized).toHaveBeenCalled();
+    } finally {
+      domSnapshotCache.invalidate(page);
+    }
+  });
+});
diff --git a/src/context-providers/a11y-dom/index.ts b/src/context-providers/a11y-dom/index.ts
index 118856a6..47e68fb3 100644
--- a/src/context-providers/a11y-dom/index.ts
+++ b/src/context-providers/a11y-dom/index.ts
@@ -33,8 +33,66 @@ import type { CDPClient, CDPSession } from "@/cdp";
 import { domSnapshotCache } from "./dom-cache";
 import { PerformanceTracker } from "./performance";
 import { getDebugOptions } from "@/debug/options";
+import { formatUnknownError, normalizePageUrl } from "@/utils";
 
 const DEFAULT_CONTEXT_COLLECTION_TIMEOUT_MS = 500;
+const MAX_A11Y_DIAGNOSTIC_CHARS = 400;
+const MAX_A11Y_FRAME_URL_CHARS = 1_000;
+
+function formatA11yDiagnostic(value: unknown): string {
+  const normalized = Array.from(formatUnknownError(value), (char) => {
+    const code = char.charCodeAt(0);
+    return (code >= 0 && code < 32) || code === 127 ? " " : char;
+  })
+    .join("")
+    .replace(/\s+/g, " ")
+    .trim();
+  const fallback = normalized.length > 0 ? normalized : "unknown error";
+  if (fallback.length <= MAX_A11Y_DIAGNOSTIC_CHARS) {
+    return fallback;
+  }
+  const omitted = fallback.length - MAX_A11Y_DIAGNOSTIC_CHARS;
+  return `${fallback.slice(
+    0,
+    MAX_A11Y_DIAGNOSTIC_CHARS
+  )}... [truncated ${omitted} chars]`;
+}
+
+function readA11yDebugOptions(): {
+  enabled: boolean;
+  profileDomCapture: boolean;
+} {
+  try {
+    const options = getDebugOptions();
+    return {
+      enabled: options.enabled === true,
+      profileDomCapture: options.profileDomCapture === true,
+    };
+  } catch (error) {
+    console.warn(
+      `[A11y] Failed to read debug options: ${formatA11yDiagnostic(error)}`
+    );
+    return {
+      enabled: false,
+      profileDomCapture: false,
+    };
+  }
+}
+
+function normalizeA11yFrameUrl(value: unknown, fallback: string = "unknown"): string {
+  return normalizePageUrl(value, {
+    fallback,
+    maxChars: MAX_A11Y_FRAME_URL_CHARS,
+  });
+}
+
+function safeA11yPageUrl(page: Page): string {
+  try {
+    return normalizeA11yFrameUrl(page.url(), "about:blank");
+  } catch {
+    return "about:blank";
+  }
+}
 
 const delay = (ms: number): Promise<void> =>
   new Promise((resolve) => setTimeout(resolve, ms));
@@ -59,6 +117,34 @@ async function collectExecutionContexts(
 
   const targetFrames = frameIds ? new Set(frameIds) : undefined;
   const contexts = new Map<string, number>();
+  const readSessionMethod = (
+    methodName: "on" | "off"
+  ): ((
+    event: string,
+    listener: (event: Protocol.Runtime.ExecutionContextCreatedEvent) => void
+  ) => void) | null => {
+    try {
+      const method = (session as CDPSession & { [key: string]: unknown })[
+        methodName
+      ];
+      if (typeof method !== "function") {
+        return null;
+      }
+      return method as (
+        event: string,
+        listener: (event: Protocol.Runtime.ExecutionContextCreatedEvent) => void
+      ) => void;
+    } catch (error) {
+      if (debug) {
+        console.warn(
+          `[A11y] Failed to read Runtime.executionContextCreated listener method: ${formatA11yDiagnostic(
+            error
+          )}`
+        );
+      }
+      return null;
+    }
+  };
 
   let finishWait: (() => void) | undefined;
   let finished = false;
@@ -106,20 +192,77 @@ async function collectExecutionContexts(
     }
   };
 
-  session.on("Runtime.executionContextCreated", handler);
-  try {
-    await session.send("Runtime.enable").catch((error) => {
+  const enableRuntimeDomain = async (): Promise<void> => {
+    let sendMethod: unknown;
+    try {
+      sendMethod = (session as CDPSession & { send?: unknown }).send;
+    } catch (error) {
+      if (debug) {
+        console.warn(
+          `[A11y] Failed to read Runtime.enable sender: ${formatA11yDiagnostic(
+            error
+          )}`
+        );
+      }
+      return;
+    }
+    if (typeof sendMethod !== "function") {
+      if (debug) {
+        console.warn(
+          "[A11y] Runtime.enable sender unavailable during context collection"
+        );
+      }
+      return;
+    }
+    try {
+      await (
+        sendMethod as (
+          this: CDPSession,
+          method: "Runtime.enable"
+        ) => Promise<unknown>
+      ).call(session, "Runtime.enable");
+    } catch (error) {
       if (debug) {
         console.warn(
           "[A11y] Failed to enable Runtime domain for context collection. " +
-            "Execution contexts may be missing for iframe elements.",
-          error
+            `Execution contexts may be missing for iframe elements. ${formatA11yDiagnostic(error)}`
         );
       }
-    });
+    }
+  };
+
+  const onMethod = readSessionMethod("on");
+  if (onMethod) {
+    try {
+      onMethod.call(session, "Runtime.executionContextCreated", handler);
+    } catch (error) {
+      if (debug) {
+        console.warn(
+          `[A11y] Failed to attach Runtime.executionContextCreated listener: ${formatA11yDiagnostic(
+            error
+          )}`
+        );
+      }
+    }
+  }
+  try {
+    await enableRuntimeDomain();
     await waitPromise;
   } finally {
-    session.off?.("Runtime.executionContextCreated", handler);
+    const offMethod = readSessionMethod("off");
+    if (offMethod) {
+      try {
+        offMethod.call(session, "Runtime.executionContextCreated", handler);
+      } catch (error) {
+        if (debug) {
+          console.warn(
+            `[A11y] Failed to detach Runtime.executionContextCreated listener: ${formatA11yDiagnostic(
+              error
+            )}`
+          );
+        }
+      }
+    }
   }
 
   return contexts;
@@ -221,7 +364,17 @@ async function syncFrameContextManager({
   rootSession,
   debug,
 }: SyncFrameContextOptions): Promise<void> {
-  manager.setDebug(debug);
+  try {
+    manager.setDebug(debug);
+  } catch (error) {
+    if (debug) {
+      console.warn(
+        `[FrameContext] Failed to configure sync debug mode: ${formatA11yDiagnostic(
+          error
+        )}`
+      );
+    }
+  }
 
   const { frameTree } =
     await rootSession.send<Protocol.Page.GetFrameTreeResponse>(
@@ -342,7 +495,17 @@ async function hydrateFrameContextFromSnapshot(
   try {
     const cdpClient = await getCDPClient(page);
     const manager = getOrCreateFrameContextManager(cdpClient);
-    manager.setDebug(debug);
+    try {
+      manager.setDebug(debug);
+    } catch (error) {
+      if (debug) {
+        console.warn(
+          `[FrameContext] Failed to configure cache-hydration debug mode: ${formatA11yDiagnostic(
+            error
+          )}`
+        );
+      }
+    }
     await manager.ensureInitialized().catch(() => {});
     await syncFrameContextManager({
       manager,
@@ -353,8 +516,7 @@ async function hydrateFrameContextFromSnapshot(
   } catch (error) {
     if (debug) {
       console.warn(
-        "[FrameContext] Failed to hydrate frame manager from cache:",
-        error
+        `[FrameContext] Failed to hydrate frame manager from cache: ${formatA11yDiagnostic(error)}`
       );
     }
   }
@@ -522,7 +684,7 @@ async function fetchIframeAXTrees(
           debugInfo: debug
             ? {
                 frameIndex,
-                frameUrl: src || "unknown",
+                frameUrl: normalizeA11yFrameUrl(src, "unknown"),
                 totalNodes: iframeNodes.length,
                 rawNodes: iframeNodes,
               }
@@ -530,8 +692,9 @@ async function fetchIframeAXTrees(
         };
       } catch (error) {
         console.warn(
-          `[A11y] Failed to fetch AX tree for frame ${frameIndex} (contentDocBackendNodeId=${contentDocumentBackendNodeId}):`,
-          (error as Error).message || error
+          `[A11y] Failed to fetch AX tree for frame ${frameIndex} (contentDocBackendNodeId=${contentDocumentBackendNodeId}): ${formatA11yDiagnostic(
+            error
+          )}`
         );
         return null;
       }
@@ -579,7 +742,11 @@ async function fetchIframeAXTrees(
     }
 
     if (debug) {
-      console.log(`[A11y] Processing OOPIF frame ${frameIndex} (${url})`);
+      console.log(
+        `[A11y] Processing OOPIF frame ${frameIndex} (${normalizeA11yFrameUrl(
+          url
+        )})`
+      );
     }
 
     try {
@@ -634,8 +801,9 @@ async function fetchIframeAXTrees(
       };
     } catch (error) {
       console.warn(
-        `[A11y] Failed to process OOPIF frame ${frameIndex} (${url}):`,
-        (error as Error).message || error
+        `[A11y] Failed to process OOPIF frame ${frameIndex} (${normalizeA11yFrameUrl(
+          url
+        )}): ${formatA11yDiagnostic(error)}`
       );
       return null;
     }
@@ -788,7 +956,7 @@ async function collectCrossOriginFrameData({
   if (debug) {
     frameDebugInfo.push({
       frameIndex,
-      frameUrl: frameInfo.src || "unknown",
+      frameUrl: normalizeA11yFrameUrl(frameInfo.src, "unknown"),
       totalNodes: nodes.length,
       rawNodes: nodes,
     });
@@ -903,6 +1071,21 @@ interface GetA11yDomOptions {
   useCache?: boolean;
   enableStreaming?: boolean;
   onFrameChunk?: (chunk: FrameChunkEvent) => void;
+  filterAdTrackingFrames?: boolean;
+}
+
+function safeReadA11yOptionField(
+  options: unknown,
+  field: keyof GetA11yDomOptions
+): unknown {
+  if (!options || (typeof options !== "object" && typeof options !== "function")) {
+    return undefined;
+  }
+  try {
+    return (options as Record<string, unknown>)[field];
+  } catch {
+    return undefined;
+  }
 }
 
 export async function getA11yDOM(
@@ -912,7 +1095,7 @@ export async function getA11yDOM(
   debugDir?: string,
   options?: GetA11yDomOptions
 ): Promise<A11yDOMState> {
-  const debugOptions = getDebugOptions();
+  const debugOptions = readA11yDebugOptions();
   const profileDom =
     debug ||
     (debugOptions.enabled && debugOptions.profileDomCapture) ||
@@ -933,8 +1116,19 @@ export async function getA11yDOM(
     }
   };
 
-  const canUseCache = options?.useCache && !enableVisualMode;
-  const onFrameChunk = options?.onFrameChunk;
+  const canUseCache =
+    safeReadA11yOptionField(options, "useCache") === true && !enableVisualMode;
+  const onFrameChunkOption = safeReadA11yOptionField(options, "onFrameChunk");
+  const onFrameChunk =
+    typeof onFrameChunkOption === "function" ? onFrameChunkOption : undefined;
+  const filterAdTrackingFramesOption = safeReadA11yOptionField(
+    options,
+    "filterAdTrackingFrames"
+  );
+  const filterAdTrackingFrames =
+    typeof filterAdTrackingFramesOption === "boolean"
+      ? filterAdTrackingFramesOption
+      : undefined;
   if (canUseCache) {
     const cached = domSnapshotCache.get(page);
     if (cached) {
@@ -953,12 +1147,33 @@ export async function getA11yDOM(
     // Step 2: Create CDP session for main frame
     const cdpClient = await getCDPClient(page);
     const frameContextManager = getOrCreateFrameContextManager(cdpClient);
-    frameContextManager.setDebug(debug);
+    try {
+      frameContextManager.setDebug(debug);
+    } catch (error) {
+      console.warn(
+        `[FrameContext] Failed to configure frame manager debug: ${formatA11yDiagnostic(
+          error
+        )}`
+      );
+    }
+    if (
+      typeof frameContextManager.setFrameFilteringEnabled === "function" &&
+      typeof filterAdTrackingFrames === "boolean"
+    ) {
+      try {
+        frameContextManager.setFrameFilteringEnabled(filterAdTrackingFrames);
+      } catch (error) {
+        console.warn(
+          `[FrameContext] Failed to configure frame filtering: ${formatA11yDiagnostic(
+            error
+          )}`
+        );
+      }
+    }
     await frameContextManager.ensureInitialized().catch((error) => {
       if (debug) {
         console.warn(
-          "[FrameContext] Failed to initialize frame manager:",
-          error
+          `[FrameContext] Failed to initialize frame manager: ${formatA11yDiagnostic(error)}`
         );
       }
     });
@@ -987,9 +1202,10 @@ export async function getA11yDOM(
       debug,
     });
 
-    // Discover and attach OOPIF frames
-    // TODO: In the future we might want to consider patching playwright so we can we access underlying CDP session ID for frame attach events for OOPIF
-    // current problem is that the event only exposes sessionId, but this does not match any internal session ID playwright page.createCDPSession() creates.
+    // Discover and attach OOPIF frames.
+    // Note: Playwright does not currently expose the underlying CDP session id used by
+    // page.createCDPSession(), so OOPIF frame-attach events cannot be mapped through
+    // raw session ids directly.
     await frameContextManager.captureOOPIFs((maps.frameMap?.size ?? 0) + 1);
 
     // Step 4: Fetch accessibility trees for main frame and all iframes
@@ -1111,7 +1327,8 @@ export async function getA11yDOM(
             frameIndex: frameIdx,
             framePath: frameInfo?.framePath,
             frameUrl:
-              frameInfo?.src ?? (frameIdx === 0 ? page.url() : undefined),
+              frameInfo?.src ??
+              (frameIdx === 0 ? safeA11yPageUrl(page) : undefined),
             simplified: treeResult.simplified,
             totalNodes: nodes.length,
             order,
@@ -1233,12 +1450,14 @@ export async function getA11yDOM(
 
     return snapshot;
   } catch (error) {
-    console.error("Error extracting accessibility tree:", error);
+    console.error(
+      `Error extracting accessibility tree: ${formatA11yDiagnostic(error)}`
+    );
     if (error instanceof Error) {
       console.error("Error details:", {
-        message: error.message,
-        stack: error.stack,
-        name: error.name,
+        message: formatA11yDiagnostic(error.message),
+        stack: error.stack ? formatA11yDiagnostic(error.stack) : undefined,
+        name: formatA11yDiagnostic(error.name),
       });
     }
 
diff --git a/src/context-providers/a11y-dom/performance.test.ts b/src/context-providers/a11y-dom/performance.test.ts
new file mode 100644
index 00000000..5235bfb0
--- /dev/null
+++ b/src/context-providers/a11y-dom/performance.test.ts
@@ -0,0 +1,42 @@
+import { PerformanceTracker } from "@/context-providers/a11y-dom/performance";
+
+describe("PerformanceTracker diagnostics", () => {
+  it("sanitizes and truncates timer-not-found diagnostics", () => {
+    const warnSpy = jest.spyOn(console, "warn").mockImplementation(() => {});
+    const tracker = new PerformanceTracker("root");
+
+    try {
+      tracker.stopTimer(`timer\u0000\n${"x".repeat(600)}`);
+
+      const diagnostic = String(warnSpy.mock.calls[0]?.[0] ?? "");
+      expect(diagnostic).toContain("[truncated");
+      expect(diagnostic).not.toContain("\u0000");
+      expect(diagnostic).not.toContain("\n");
+      expect(diagnostic.length).toBeLessThan(500);
+    } finally {
+      warnSpy.mockRestore();
+    }
+  });
+
+  it("sanitizes and truncates out-of-order timer diagnostics", () => {
+    const warnSpy = jest.spyOn(console, "warn").mockImplementation(() => {});
+    const tracker = new PerformanceTracker("root");
+    const parentName = `parent\u0000\n${"p".repeat(300)}`;
+    const childName = `child\u0000\n${"c".repeat(300)}`;
+
+    try {
+      tracker.startTimer(parentName);
+      tracker.startTimer(childName);
+      tracker.stopTimer(parentName);
+
+      const diagnostic = String(warnSpy.mock.calls[0]?.[0] ?? "");
+      expect(diagnostic).toContain("stopped out of order");
+      expect(diagnostic).toContain("[truncated");
+      expect(diagnostic).not.toContain("\u0000");
+      expect(diagnostic).not.toContain("\n");
+      expect(diagnostic.length).toBeLessThan(700);
+    } finally {
+      warnSpy.mockRestore();
+    }
+  });
+});
diff --git a/src/context-providers/a11y-dom/performance.ts b/src/context-providers/a11y-dom/performance.ts
index 8821b957..03af6192 100644
--- a/src/context-providers/a11y-dom/performance.ts
+++ b/src/context-providers/a11y-dom/performance.ts
@@ -9,12 +9,12 @@ export interface TimingEntry {
   endTime?: number;
   duration?: number;
   children: TimingEntry[];
-  metadata?: Record<string, any>;
+  metadata?: Record<string, unknown>;
 }
 
 export interface PerformanceReport {
   totalTime: number;
-  breakdown: Record<string, any>;
+  breakdown: Record<string, unknown> | number;
   bottlenecks: Array<{
     operation: string;
     time: number;
@@ -25,6 +25,53 @@ export interface PerformanceReport {
   rawTimings: TimingEntry[];
 }
 
+const MAX_PERFORMANCE_DIAGNOSTIC_CHARS = 240;
+
+function sanitizePerformanceDiagnostic(value: string): string {
+  if (value.length === 0) {
+    return value;
+  }
+  const withoutControlChars = Array.from(value, (char) => {
+    const code = char.charCodeAt(0);
+    return (code >= 0 && code < 32) || code === 127 ? " " : char;
+  }).join("");
+  return withoutControlChars.replace(/\s+/g, " ").trim();
+}
+
+function truncatePerformanceDiagnostic(value: string): string {
+  if (value.length <= MAX_PERFORMANCE_DIAGNOSTIC_CHARS) {
+    return value;
+  }
+  const omittedChars = value.length - MAX_PERFORMANCE_DIAGNOSTIC_CHARS;
+  return `${value.slice(0, MAX_PERFORMANCE_DIAGNOSTIC_CHARS)}... [truncated ${omittedChars} chars]`;
+}
+
+function formatPerformanceDiagnostic(value: unknown, fallback: string): string {
+  if (typeof value !== "string") {
+    return fallback;
+  }
+  const normalized = sanitizePerformanceDiagnostic(value);
+  if (normalized.length === 0) {
+    return fallback;
+  }
+  return truncatePerformanceDiagnostic(normalized);
+}
+
+function readMetadataBoolean(
+  metadata: Record<string, unknown> | undefined,
+  key: string
+): boolean {
+  return metadata?.[key] === true;
+}
+
+function readMetadataNumber(
+  metadata: Record<string, unknown> | undefined,
+  key: string
+): number | null {
+  const value = metadata?.[key];
+  return typeof value === "number" && Number.isFinite(value) ? value : null;
+}
+
 /**
  * Performance tracker with hierarchical timing support
  */
@@ -46,7 +93,7 @@ export class PerformanceTracker {
   /**
    * Start a named timer
    */
-  startTimer(name: string, metadata?: Record<string, any>): void {
+  startTimer(name: string, metadata?: Record<string, unknown>): void {
     const entry: TimingEntry = {
       name,
       startTime: performance.now(),
@@ -71,14 +118,25 @@ export class PerformanceTracker {
   stopTimer(name: string): number {
     const entry = this.timerMap.get(name);
     if (!entry) {
-      console.warn(`[Performance] Timer '${name}' not found`);
+      console.warn(
+        `[Performance] Timer '${formatPerformanceDiagnostic(
+          name,
+          "unknown timer"
+        )}' not found`
+      );
       return 0;
     }
 
     // If this timer is not the current one, something went wrong
     if (this.currentEntry !== entry) {
       console.warn(
-        `[Performance] Timer '${name}' stopped out of order (current: ${this.currentEntry.name})`
+        `[Performance] Timer '${formatPerformanceDiagnostic(
+          name,
+          "unknown timer"
+        )}' stopped out of order (current: ${formatPerformanceDiagnostic(
+          this.currentEntry.name,
+          "unknown timer"
+        )})`
       );
     }
 
@@ -96,7 +154,7 @@ export class PerformanceTracker {
   /**
    * Record a single point-in-time mark
    */
-  mark(name: string, metadata?: Record<string, any>): void {
+  mark(name: string, metadata?: Record<string, unknown>): void {
     const entry: TimingEntry = {
       name,
       startTime: performance.now(),
@@ -122,8 +180,16 @@ export class PerformanceTracker {
   /**
    * Get flattened timing data
    */
-  getFlatTimings(): Array<{ name: string; duration: number; metadata?: Record<string, any> }> {
-    const flat: Array<{ name: string; duration: number; metadata?: Record<string, any> }> = [];
+  getFlatTimings(): Array<{
+    name: string;
+    duration: number;
+    metadata?: Record<string, unknown>;
+  }> {
+    const flat: Array<{
+      name: string;
+      duration: number;
+      metadata?: Record<string, unknown>;
+    }> = [];
 
     const traverse = (entry: TimingEntry, depth: number = 0) => {
       if (entry.duration !== undefined) {
@@ -146,12 +212,12 @@ export class PerformanceTracker {
   /**
    * Build hierarchical breakdown object
    */
-  private buildBreakdown(entry: TimingEntry): any {
+  private buildBreakdown(entry: TimingEntry): Record<string, unknown> | number {
     if (entry.children.length === 0) {
       return entry.duration ?? 0;
     }
 
-    const breakdown: any = {};
+    const breakdown: Record<string, unknown> = {};
 
     // If we have both duration and children, include total
     if (entry.duration !== undefined) {
@@ -199,14 +265,18 @@ export class PerformanceTracker {
       }
 
       // Check metadata for bottleneck hints
-      if (entry.metadata?.sequential && entry.metadata?.parallelizable) {
+      if (
+        readMetadataBoolean(entry.metadata, "sequential") &&
+        readMetadataBoolean(entry.metadata, "parallelizable")
+      ) {
         severity = severity === 'low' ? 'high' : severity;
         recommendation += ' Could be parallelized.';
       }
 
-      if (entry.metadata?.cdpCallCount && entry.metadata.cdpCallCount > 10) {
+      const cdpCallCount = readMetadataNumber(entry.metadata, "cdpCallCount");
+      if (cdpCallCount !== null && cdpCallCount > 10) {
         severity = severity === 'low' ? 'medium' : severity;
-        recommendation += ` Makes ${entry.metadata.cdpCallCount} CDP calls.`;
+        recommendation += ` Makes ${cdpCallCount} CDP calls.`;
       }
 
       if (severity !== 'low') {
@@ -312,7 +382,7 @@ export async function withTiming<T>(
   tracker: PerformanceTracker,
   name: string,
   fn: () => Promise<T>,
-  metadata?: Record<string, any>
+  metadata?: Record<string, unknown>
 ): Promise<T> {
   tracker.startTimer(name, metadata);
   try {
@@ -329,7 +399,7 @@ export function withTimingSync<T>(
   tracker: PerformanceTracker,
   name: string,
   fn: () => T,
-  metadata?: Record<string, any>
+  metadata?: Record<string, unknown>
 ): T {
   tracker.startTimer(name, metadata);
   try {
diff --git a/src/context-providers/a11y-dom/scrollable-detection.test.ts b/src/context-providers/a11y-dom/scrollable-detection.test.ts
new file mode 100644
index 00000000..7f61859b
--- /dev/null
+++ b/src/context-providers/a11y-dom/scrollable-detection.test.ts
@@ -0,0 +1,192 @@
+import {
+  decorateRoleIfScrollable,
+  findScrollableElementIds,
+  getScrollableElementXpaths,
+} from "@/context-providers/a11y-dom/scrollable-detection";
+import type { CDPSession } from "@/cdp";
+
+describe("scrollable detection error formatting", () => {
+  it("formats non-Error failures when reading scrollable xpaths", async () => {
+    const warnSpy = jest.spyOn(console, "warn").mockImplementation(() => {});
+    const pageOrFrame = {
+      evaluate: jest.fn().mockRejectedValue({ reason: "eval failed" }),
+    };
+
+    try {
+      const xpaths = await getScrollableElementXpaths(
+        pageOrFrame as unknown as Parameters<typeof getScrollableElementXpaths>[0]
+      );
+      expect(xpaths).toEqual([]);
+      expect(warnSpy).toHaveBeenCalledWith(
+        'Error getting scrollable element xpaths: {"reason":"eval failed"}'
+      );
+    } finally {
+      warnSpy.mockRestore();
+    }
+  });
+
+  it("sanitizes and truncates oversized xpath read diagnostics", async () => {
+    const warnSpy = jest.spyOn(console, "warn").mockImplementation(() => {});
+    const pageOrFrame = {
+      evaluate: jest.fn().mockRejectedValue(new Error(`eval\u0000\n${"x".repeat(10_000)}`)),
+    };
+
+    try {
+      const xpaths = await getScrollableElementXpaths(
+        pageOrFrame as unknown as Parameters<typeof getScrollableElementXpaths>[0]
+      );
+      expect(xpaths).toEqual([]);
+      const warning = String(warnSpy.mock.calls[0]?.[0] ?? "");
+      expect(warning).toContain("[truncated");
+      expect(warning).not.toContain("\u0000");
+      expect(warning).not.toContain("\n");
+    } finally {
+      warnSpy.mockRestore();
+    }
+  });
+
+  it("returns sanitized xpath list when browser result includes invalid entries", async () => {
+    const pageOrFrame = {
+      evaluate: jest
+        .fn()
+        .mockResolvedValue([" /html/body/div[1] ", "", 42, null, " //main "]),
+    };
+
+    const xpaths = await getScrollableElementXpaths(
+      pageOrFrame as unknown as Parameters<typeof getScrollableElementXpaths>[0]
+    );
+
+    expect(xpaths).toEqual(["/html/body/div[1]", "//main"]);
+  });
+
+  it("returns empty xpath list when browser result is not an array", async () => {
+    const pageOrFrame = {
+      evaluate: jest.fn().mockResolvedValue({ unexpected: true }),
+    };
+
+    const xpaths = await getScrollableElementXpaths(
+      pageOrFrame as unknown as Parameters<typeof getScrollableElementXpaths>[0]
+    );
+
+    expect(xpaths).toEqual([]);
+  });
+
+  it("formats non-Error failures when resolving xpath backend IDs", async () => {
+    const warnSpy = jest.spyOn(console, "warn").mockImplementation(() => {});
+    const pageOrFrame = {
+      evaluate: jest.fn().mockResolvedValue(["/html/body/div[1]"]),
+    };
+    const client: CDPSession = {
+      id: "cdp-session",
+      raw: undefined,
+      send: async <T = unknown>(method: string): Promise<T> => {
+        if (method === "Runtime.evaluate") {
+          throw { reason: "runtime evaluate failed" };
+        }
+        return {} as T;
+      },
+      on: jest.fn(),
+      off: jest.fn(),
+      detach: jest.fn(async () => undefined),
+    };
+
+    try {
+      const ids = await findScrollableElementIds(
+        pageOrFrame as unknown as Parameters<typeof findScrollableElementIds>[0],
+        client
+      );
+      expect(ids.size).toBe(0);
+      expect(warnSpy).toHaveBeenCalledWith(
+        'Error resolving XPath /html/body/div[1]: {"reason":"runtime evaluate failed"}'
+      );
+    } finally {
+      warnSpy.mockRestore();
+    }
+  });
+
+  it("sanitizes and truncates oversized xpath resolution diagnostics", async () => {
+    const warnSpy = jest.spyOn(console, "warn").mockImplementation(() => {});
+    const pageOrFrame = {
+      evaluate: jest.fn().mockResolvedValue(["/html/body/div[1]"]),
+    };
+    const client: CDPSession = {
+      id: "cdp-session",
+      raw: undefined,
+      send: async <T = unknown>(method: string): Promise<T> => {
+        if (method === "Runtime.evaluate") {
+          throw new Error(`runtime\u0000\n${"x".repeat(10_000)}`);
+        }
+        return {} as T;
+      },
+      on: jest.fn(),
+      off: jest.fn(),
+      detach: jest.fn(async () => undefined),
+    };
+
+    try {
+      const ids = await findScrollableElementIds(
+        pageOrFrame as unknown as Parameters<typeof findScrollableElementIds>[0],
+        client
+      );
+      expect(ids.size).toBe(0);
+      const warning = String(warnSpy.mock.calls[0]?.[0] ?? "");
+      expect(warning).toContain("[truncated");
+      expect(warning).not.toContain("\u0000");
+      expect(warning).not.toContain("\n");
+    } finally {
+      warnSpy.mockRestore();
+    }
+  });
+
+  it("resolves backend IDs only for sanitized xpath candidates", async () => {
+    const pageOrFrame = {
+      evaluate: jest
+        .fn()
+        .mockResolvedValue([" /html/body/div[1] ", "   ", 12, "/html/body/div[2]"]),
+    };
+    const runtimeEvaluateCalls: string[] = [];
+    const client: CDPSession = {
+      id: "cdp-session",
+      raw: undefined,
+      send: async <T = unknown>(
+        method: string,
+        params?: Record<string, unknown>
+      ): Promise<T> => {
+        if (method === "Runtime.evaluate") {
+          runtimeEvaluateCalls.push(String(params?.expression ?? ""));
+          return { result: { objectId: "object-id" } } as T;
+        }
+        if (method === "DOM.describeNode") {
+          return { node: { backendNodeId: 777 } } as T;
+        }
+        return {} as T;
+      },
+      on: jest.fn(),
+      off: jest.fn(),
+      detach: jest.fn(async () => undefined),
+    };
+
+    const ids = await findScrollableElementIds(
+      pageOrFrame as unknown as Parameters<typeof findScrollableElementIds>[0],
+      client
+    );
+
+    expect(ids).toEqual(new Set([777]));
+    expect(runtimeEvaluateCalls).toHaveLength(2);
+    expect(runtimeEvaluateCalls[0]).toContain("/html/body/div[1]");
+    expect(runtimeEvaluateCalls[1]).toContain("/html/body/div[2]");
+  });
+
+});
+
+describe("decorateRoleIfScrollable", () => {
+  it("decorates semantic roles and avoids generic/none duplicates", () => {
+    const ids = new Set([10]);
+    expect(decorateRoleIfScrollable("button", 10, ids)).toBe(
+      "scrollable, button"
+    );
+    expect(decorateRoleIfScrollable("generic", 10, ids)).toBe("scrollable");
+    expect(decorateRoleIfScrollable("none", 10, ids)).toBe("scrollable");
+    expect(decorateRoleIfScrollable("button", 9, ids)).toBe("button");
+  });
+});
diff --git a/src/context-providers/a11y-dom/scrollable-detection.ts b/src/context-providers/a11y-dom/scrollable-detection.ts
index a0cf612a..09d028b3 100644
--- a/src/context-providers/a11y-dom/scrollable-detection.ts
+++ b/src/context-providers/a11y-dom/scrollable-detection.ts
@@ -5,6 +5,28 @@
 
 import type { Page, Frame } from 'playwright-core';
 import type { CDPSession } from '@/cdp';
+import { formatUnknownError } from '@/utils';
+
+const MAX_SCROLLABLE_DIAGNOSTIC_CHARS = 400;
+
+function formatScrollableDiagnostic(error: unknown): string {
+  const normalized = Array.from(formatUnknownError(error), (char) => {
+    const code = char.charCodeAt(0);
+    return (code >= 0 && code < 32) || code === 127 ? " " : char;
+  })
+    .join("")
+    .replace(/\s+/g, " ")
+    .trim();
+  const fallback = normalized.length > 0 ? normalized : "unknown error";
+  if (fallback.length <= MAX_SCROLLABLE_DIAGNOSTIC_CHARS) {
+    return fallback;
+  }
+  const omitted = fallback.length - MAX_SCROLLABLE_DIAGNOSTIC_CHARS;
+  return `${fallback.slice(
+    0,
+    MAX_SCROLLABLE_DIAGNOSTIC_CHARS
+  )}... [truncated ${omitted} chars]`;
+}
 
 /**
  * Browser-side functions to detect scrollable elements
@@ -178,13 +200,23 @@ export async function getScrollableElementXpaths(
   topN?: number
 ): Promise<string[]> {
   try {
-    const xpaths = await pageOrFrame.evaluate((n) => {
+    const rawXpaths = await pageOrFrame.evaluate((n) => {
       // @ts-ignore - function injected via script
       return window.__hyperagent_getScrollableElementXpaths?.(n) ?? [];
     }, topN);
-    return xpaths;
+
+    if (!Array.isArray(rawXpaths)) {
+      return [];
+    }
+
+    return rawXpaths
+      .filter((value): value is string => typeof value === "string")
+      .map((value) => value.trim())
+      .filter((value) => value.length > 0);
   } catch (error) {
-    console.warn('Error getting scrollable element xpaths:', error);
+    console.warn(
+      `Error getting scrollable element xpaths: ${formatScrollableDiagnostic(error)}`
+    );
     return [];
   }
 }
@@ -237,13 +269,17 @@ export async function findScrollableElementIds(
         }
       } catch (error) {
         // Silently ignore errors for individual elements
-        console.warn(`Error resolving XPath ${xpath}:`, error);
+        console.warn(
+          `Error resolving XPath ${xpath}: ${formatScrollableDiagnostic(error)}`
+        );
       }
     }
 
     return backendIds;
   } catch (error) {
-    console.error('Error finding scrollable element IDs:', error);
+    console.error(
+      `Error finding scrollable element IDs: ${formatScrollableDiagnostic(error)}`
+    );
     return new Set();
   }
 }
diff --git a/src/context-providers/a11y-dom/utils.test.ts b/src/context-providers/a11y-dom/utils.test.ts
new file mode 100644
index 00000000..9e787a77
--- /dev/null
+++ b/src/context-providers/a11y-dom/utils.test.ts
@@ -0,0 +1,199 @@
+import type { Frame, Page } from "playwright-core";
+import { resolveFrameByXPath } from "@/context-providers/a11y-dom/utils";
+import type { IframeInfo } from "@/context-providers/a11y-dom/types";
+
+function createPage(overrides?: Partial<Page>): Page {
+  const mainFrame = {} as Frame;
+  return {
+    mainFrame: () => mainFrame,
+    frames: () => [mainFrame],
+    ...overrides,
+  } as unknown as Page;
+}
+
+describe("resolveFrameByXPath URL matching", () => {
+  it("continues URL matching when one frame.url getter throws", async () => {
+    const mainFrame = {
+      url: () => "https://example.com",
+    } as unknown as Frame;
+    const trappedFrame = {
+      url: () => {
+        throw new Error("url trap");
+      },
+    } as unknown as Frame;
+    const matchedFrame = {
+      url: () => "https://example.com/frame",
+    } as unknown as Frame;
+    const page = createPage({
+      mainFrame: () => mainFrame,
+      frames: () => [mainFrame, trappedFrame, matchedFrame],
+    });
+
+    const frameMap = new Map<number, IframeInfo>([
+      [
+        1,
+        {
+          frameIndex: 1,
+          siblingPosition: 0,
+          src: "https://example.com/frame",
+          xpath: "//iframe[1]",
+          parentFrameIndex: 0,
+        },
+      ],
+    ]);
+
+    const resolved = await resolveFrameByXPath(page, frameMap, 1);
+    expect(resolved).toBe(matchedFrame);
+  });
+
+  it("sanitizes control characters in target frame src when URL matching", async () => {
+    const mainFrame = {
+      url: () => "https://example.com",
+    } as unknown as Frame;
+    const matchedFrame = {
+      url: () => "https://example.com/frame",
+    } as unknown as Frame;
+    const page = createPage({
+      mainFrame: () => mainFrame,
+      frames: () => [mainFrame, matchedFrame],
+    });
+
+    const frameMap = new Map<number, IframeInfo>([
+      [
+        1,
+        {
+          frameIndex: 1,
+          siblingPosition: 0,
+          src: "  https://example.com/frame\u0000\n  ",
+          xpath: "//iframe[1]",
+          parentFrameIndex: 0,
+        },
+      ],
+    ]);
+
+    const resolved = await resolveFrameByXPath(page, frameMap, 1);
+    expect(resolved).toBe(matchedFrame);
+  });
+
+  it("falls back to XPath traversal when page.frames() throws", async () => {
+    const warnSpy = jest.spyOn(console, "warn").mockImplementation(() => {});
+    const targetFrame = {} as Frame;
+    const iframeHandle = {
+      contentFrame: jest.fn().mockResolvedValue(targetFrame),
+    };
+    const iframeLocator = {
+      elementHandle: jest.fn().mockResolvedValue(iframeHandle),
+    };
+    const mainFrame = {
+      locator: jest.fn(() => iframeLocator),
+    } as unknown as Frame;
+    const page = createPage({
+      mainFrame: () => mainFrame,
+      frames: () => {
+        throw new Error(`frames\u0000\n${"x".repeat(2_000)}`);
+      },
+    });
+
+    const frameMap = new Map<number, IframeInfo>([
+      [
+        1,
+        {
+          frameIndex: 1,
+          siblingPosition: 0,
+          src: "https://example.com/frame",
+          xpath: "//iframe[1]",
+          parentFrameIndex: 0,
+        },
+      ],
+    ]);
+
+    try {
+      const resolved = await resolveFrameByXPath(page, frameMap, 1);
+      expect(resolved).toBe(targetFrame);
+
+      const warning = String(warnSpy.mock.calls[0]?.[0] ?? "");
+      expect(warning).toContain("Failed to enumerate frames for URL matching");
+      expect(warning).toContain("[truncated");
+      expect(warning).not.toContain("\u0000");
+      expect(warning).not.toContain("\n");
+    } finally {
+      warnSpy.mockRestore();
+    }
+  });
+
+  it("keeps URL matching when one frame entry getter traps", async () => {
+    const mainFrame = {
+      url: () => "https://example.com",
+    } as unknown as Frame;
+    const matchedFrame = {
+      url: () => "https://example.com/frame",
+    } as unknown as Frame;
+    const frames = new Proxy([{}, matchedFrame], {
+      get: (target, prop, receiver) => {
+        if (prop === "0") {
+          throw new Error("frame entry trap");
+        }
+        return Reflect.get(target, prop, receiver);
+      },
+    });
+    const page = createPage({
+      mainFrame: () => mainFrame,
+      frames: () => frames as unknown as Frame[],
+    });
+
+    const frameMap = new Map<number, IframeInfo>([
+      [
+        1,
+        {
+          frameIndex: 1,
+          siblingPosition: 0,
+          src: "https://example.com/frame",
+          xpath: "//iframe[1]",
+          parentFrameIndex: 0,
+        },
+      ],
+    ]);
+
+    const resolved = await resolveFrameByXPath(page, frameMap, 1);
+    expect(resolved).toBe(matchedFrame);
+  });
+
+  it("sanitizes traversal diagnostics when locator traversal throws", async () => {
+    const warnSpy = jest.spyOn(console, "warn").mockImplementation(() => {});
+    const mainFrame = {
+      locator: () => {
+        throw new Error(`traverse\u0000\n${"x".repeat(2_000)}`);
+      },
+    } as unknown as Frame;
+    const page = createPage({
+      mainFrame: () => mainFrame,
+      frames: () => [],
+    });
+
+    const frameMap = new Map<number, IframeInfo>([
+      [
+        1,
+        {
+          frameIndex: 1,
+          siblingPosition: 0,
+          xpath: "//iframe[1]",
+          parentFrameIndex: 0,
+        },
+      ],
+    ]);
+
+    try {
+      const resolved = await resolveFrameByXPath(page, frameMap, 1);
+      expect(resolved).toBeNull();
+      const warning = warnSpy.mock.calls
+        .map((call) => String(call[0] ?? ""))
+        .find((entry) => entry.includes("Error traversing frame 1"));
+      expect(warning).toBeDefined();
+      expect(warning).toContain("[truncated");
+      expect(warning).not.toContain("\u0000");
+      expect(warning).not.toContain("\n");
+    } finally {
+      warnSpy.mockRestore();
+    }
+  });
+});
diff --git a/src/context-providers/a11y-dom/utils.ts b/src/context-providers/a11y-dom/utils.ts
index 0559dafc..50130760 100644
--- a/src/context-providers/a11y-dom/utils.ts
+++ b/src/context-providers/a11y-dom/utils.ts
@@ -4,6 +4,57 @@
 
 import { Page, Frame } from "playwright-core";
 import { AccessibilityNode, EncodedId, AXNode, IframeInfo } from "./types";
+import { normalizePageUrl } from "@/utils/page-url";
+import { formatUnknownError } from "@/utils";
+
+const MAX_FRAME_RESOLUTION_DIAGNOSTIC_CHARS = 400;
+
+function formatFrameResolutionDiagnostic(error: unknown): string {
+  const normalized = Array.from(formatUnknownError(error), (char) => {
+    const code = char.charCodeAt(0);
+    return (code >= 0 && code < 32) || code === 127 ? " " : char;
+  })
+    .join("")
+    .replace(/\s+/g, " ")
+    .trim();
+  const fallback = normalized.length > 0 ? normalized : "unknown error";
+  if (fallback.length <= MAX_FRAME_RESOLUTION_DIAGNOSTIC_CHARS) {
+    return fallback;
+  }
+  const omitted = fallback.length - MAX_FRAME_RESOLUTION_DIAGNOSTIC_CHARS;
+  return `${fallback.slice(
+    0,
+    MAX_FRAME_RESOLUTION_DIAGNOSTIC_CHARS
+  )}... [truncated ${omitted} chars]`;
+}
+
+function safeArrayLength(value: unknown): number {
+  try {
+    if (Array.isArray(value)) {
+      return value.length;
+    }
+    if (value && typeof value === "object") {
+      const length = (value as { length?: unknown }).length;
+      if (typeof length === "number" && Number.isFinite(length) && length >= 0) {
+        return Math.floor(length);
+      }
+    }
+  } catch {
+    // ignore trap-prone length getter reads
+  }
+  return 0;
+}
+
+function safeReadArrayItem(value: unknown, index: number): unknown {
+  if (!value || typeof value !== "object") {
+    return undefined;
+  }
+  try {
+    return (value as Record<number, unknown>)[index];
+  } catch {
+    return undefined;
+  }
+}
 
 /**
  * Clean text by removing private-use unicode characters and normalizing whitespace
@@ -373,11 +424,43 @@ export async function resolveFrameByXPath(
 
     // Try matching by URL (works for cross-origin frames)
     if (targetFrameInfo.src) {
-      const matchByUrl = page
-        .frames()
-        .find((frame) => frame.url() === targetFrameInfo.src);
-      if (matchByUrl) {
-        return matchByUrl;
+      const targetSrc = normalizePageUrl(targetFrameInfo.src, {
+        fallback: "",
+      });
+      if (targetSrc.length > 0) {
+        try {
+          const frames = page.frames();
+          const frameCount = safeArrayLength(frames);
+          for (let i = 0; i < frameCount; i++) {
+            const frame = safeReadArrayItem(frames, i);
+            if (!frame || typeof frame !== "object") {
+              continue;
+            }
+            let frameUrl = "";
+            try {
+              const frameUrlMethod = (frame as { url?: unknown }).url;
+              if (typeof frameUrlMethod !== "function") {
+                continue;
+              }
+              frameUrl = normalizePageUrl(
+                (frameUrlMethod as (this: unknown) => unknown).call(frame),
+                { fallback: "" }
+              );
+            } catch {
+              frameUrl = "";
+            }
+            if (frameUrl === targetSrc) {
+              return frame as Frame;
+            }
+          }
+        } catch (error) {
+          console.warn(
+            `[A11y] Failed to enumerate frames for URL matching: ${formatFrameResolutionDiagnostic(
+              error
+            )}`
+          );
+          // Continue with XPath traversal fallback.
+        }
       }
     }
 
@@ -435,8 +518,9 @@ export async function resolveFrameByXPath(
         currentFrame = nextFrame;
       } catch (error) {
         console.warn(
-          `[A11y] Error traversing frame ${frameIndex}:`,
-          error
+          `[A11y] Error traversing frame ${frameIndex}: ${formatFrameResolutionDiagnostic(
+            error
+          )}`
         );
         return null;
       }
@@ -445,8 +529,9 @@ export async function resolveFrameByXPath(
     return currentFrame;
   } catch (error) {
     console.error(
-      `[A11y] Failed to resolve frame ${targetFrameIndex}:`,
-      error
+      `[A11y] Failed to resolve frame ${targetFrameIndex}: ${formatFrameResolutionDiagnostic(
+        error
+      )}`
     );
     return null;
   }
diff --git a/src/debug/options.test.ts b/src/debug/options.test.ts
new file mode 100644
index 00000000..cd6d8caf
--- /dev/null
+++ b/src/debug/options.test.ts
@@ -0,0 +1,70 @@
+import { getDebugOptions, setDebugOptions } from "@/debug/options";
+
+describe("debug options", () => {
+  beforeEach(() => {
+    setDebugOptions(undefined, false);
+  });
+
+  it("stores boolean debug flags and enabled state", () => {
+    setDebugOptions(
+      {
+        cdpSessions: true,
+        traceWait: false,
+        profileDomCapture: true,
+        structuredSchema: false,
+      },
+      true
+    );
+
+    expect(getDebugOptions()).toEqual({
+      cdpSessions: true,
+      traceWait: false,
+      profileDomCapture: true,
+      structuredSchema: false,
+      enabled: true,
+    });
+  });
+
+  it("ignores non-boolean debug option values", () => {
+    setDebugOptions(
+      {
+        cdpSessions: true,
+        traceWait: "true" as unknown as boolean,
+      },
+      false
+    );
+
+    expect(getDebugOptions()).toEqual({
+      cdpSessions: true,
+      enabled: false,
+    });
+  });
+
+  it("omits trap-prone debug option getters without throwing", () => {
+    const trappedOptions = new Proxy(
+      {
+        cdpSessions: true,
+      },
+      {
+        get: (target, prop, receiver) => {
+          if (prop === "traceWait") {
+            throw new Error("traceWait trap");
+          }
+          return Reflect.get(target, prop, receiver);
+        },
+      }
+    );
+
+    expect(() =>
+      setDebugOptions(
+        trappedOptions as unknown as Parameters<typeof setDebugOptions>[0],
+        true
+      )
+    ).not.toThrow();
+
+    expect(getDebugOptions()).toEqual({
+      cdpSessions: true,
+      enabled: true,
+    });
+  });
+});
diff --git a/src/debug/options.ts b/src/debug/options.ts
index 75084862..deb97d90 100644
--- a/src/debug/options.ts
+++ b/src/debug/options.ts
@@ -5,14 +5,46 @@ export interface HyperAgentDebugOptions {
   structuredSchema?: boolean;
 }
 
+const DEBUG_OPTION_KEYS: ReadonlyArray<keyof HyperAgentDebugOptions> = [
+  "cdpSessions",
+  "traceWait",
+  "profileDomCapture",
+  "structuredSchema",
+];
+
 let currentDebugOptions: HyperAgentDebugOptions = {};
 let debugOptionsEnabled = false;
 
+function safeReadOptionField(
+  options: unknown,
+  key: keyof HyperAgentDebugOptions
+): unknown {
+  if (!options || (typeof options !== "object" && typeof options !== "function")) {
+    return undefined;
+  }
+  try {
+    return (options as Record<string, unknown>)[key];
+  } catch {
+    return undefined;
+  }
+}
+
+function normalizeDebugOptions(options?: HyperAgentDebugOptions): HyperAgentDebugOptions {
+  const normalized: HyperAgentDebugOptions = {};
+  for (const key of DEBUG_OPTION_KEYS) {
+    const value = safeReadOptionField(options, key);
+    if (typeof value === "boolean") {
+      normalized[key] = value;
+    }
+  }
+  return normalized;
+}
+
 export function setDebugOptions(
   options?: HyperAgentDebugOptions,
   enabled = false
 ): void {
-  currentDebugOptions = options ?? {};
+  currentDebugOptions = normalizeDebugOptions(options);
   debugOptionsEnabled = enabled;
 }
 
diff --git a/src/index.ts b/src/index.ts
index 5ea6e336..212aec79 100644
--- a/src/index.ts
+++ b/src/index.ts
@@ -1,7 +1,26 @@
 import { HyperAgent } from "./agent";
 import { TaskStatus } from "./types/agent/types";
+import { HyperagentError, HyperagentTaskError } from "./agent/error";
 
-export { TaskStatus, HyperAgent };
+export { TaskStatus, HyperAgent, HyperagentError, HyperagentTaskError };
+export type {
+  ActionCacheOutput,
+  ActionCacheReplayResult,
+  ActionCacheReplayStepResult,
+  AgentActionDefinition,
+  AgentTaskOutput,
+  HyperAgentConfig,
+  HyperPage,
+  HyperVariable,
+  MCPConfig,
+  MCPServerConfig,
+  PerformOptions,
+  PerformTaskParams,
+  RunFromActionCacheParams,
+  Task,
+  TaskOutput,
+  TaskParams,
+} from "./types";
 export default HyperAgent;
 
 // For CommonJS compatibility
@@ -9,5 +28,7 @@ if (typeof module !== "undefined" && module.exports) {
   module.exports = HyperAgent;
   module.exports.HyperAgent = HyperAgent;
   module.exports.TaskStatus = TaskStatus;
+  module.exports.HyperagentError = HyperagentError;
+  module.exports.HyperagentTaskError = HyperagentTaskError;
   module.exports.default = HyperAgent;
 }
diff --git a/src/llm/providers/anthropic.test.ts b/src/llm/providers/anthropic.test.ts
new file mode 100644
index 00000000..d2daeca4
--- /dev/null
+++ b/src/llm/providers/anthropic.test.ts
@@ -0,0 +1,568 @@
+import { z } from "zod";
+import { AnthropicClient } from "@/llm/providers/anthropic";
+
+const createMessageMock = jest.fn();
+const convertToAnthropicToolMock: jest.Mock = jest.fn(() => ({
+  name: "structured_output",
+  input_schema: { type: "object", properties: {} },
+}));
+const debugOptions = {
+  enabled: false,
+  structuredSchema: false,
+};
+
+jest.mock("@anthropic-ai/sdk", () => {
+  return jest.fn().mockImplementation(() => ({
+    messages: {
+      create: createMessageMock,
+    },
+  }));
+});
+
+jest.mock("@/llm/utils/message-converter", () => ({
+  convertToAnthropicMessages: jest.fn(() => ({
+    messages: [],
+    system: "system",
+  })),
+}));
+
+jest.mock("@/llm/utils/schema-converter", () => ({
+  convertActionsToAnthropicTools: jest.fn((actions: Array<{ type: string }>) =>
+    actions.map((action) => ({ name: action.type }))
+  ),
+  convertToAnthropicTool: (schema: unknown) =>
+    convertToAnthropicToolMock(schema),
+  createAnthropicToolChoice: jest.fn(() => ({ type: "tool" })),
+}));
+
+jest.mock("@/debug/options", () => ({
+  getDebugOptions: jest.fn(() => debugOptions),
+}));
+
+const { getDebugOptions } = jest.requireMock("@/debug/options") as {
+  getDebugOptions: jest.Mock;
+};
+
+describe("AnthropicClient", () => {
+  beforeEach(() => {
+    createMessageMock.mockReset();
+    convertToAnthropicToolMock.mockReset();
+    convertToAnthropicToolMock.mockReturnValue({
+      name: "structured_output",
+      input_schema: { type: "object", properties: {} },
+    });
+    debugOptions.enabled = false;
+    debugOptions.structuredSchema = false;
+  });
+
+  it("returns first text block even when not first content part", async () => {
+    createMessageMock.mockResolvedValue({
+      content: [
+        { type: "tool_use", name: "ignore", input: {} },
+        { type: "text", text: "hello from anthropic" },
+      ],
+      usage: {
+        input_tokens: 5,
+        output_tokens: 7,
+      },
+    });
+
+    const client = new AnthropicClient({ model: "claude-test" });
+    const result = await client.invoke([
+      { role: "user", content: "Hi" },
+    ]);
+
+    expect(result.content).toBe("hello from anthropic");
+    expect(result.usage).toEqual({
+      inputTokens: 5,
+      outputTokens: 7,
+    });
+  });
+
+  it("concatenates multiple text blocks in invoke responses", async () => {
+    createMessageMock.mockResolvedValue({
+      content: [
+        { type: "text", text: "first" },
+        { type: "tool_use", name: "ignored", input: {} },
+        { type: "text", text: "second" },
+      ],
+      usage: {
+        input_tokens: 3,
+        output_tokens: 4,
+      },
+    });
+
+    const client = new AnthropicClient({ model: "claude-test" });
+    const result = await client.invoke([{ role: "user", content: "Hi" }]);
+
+    expect(result.content).toBe("first\n\nsecond");
+  });
+
+  it("parses simple-tool structured output when tool_use block is not first", async () => {
+    createMessageMock.mockResolvedValue({
+      content: [
+        { type: "text", text: "draft" },
+        {
+          type: "tool_use",
+          input: {
+            result: {
+              value: "ok",
+            },
+          },
+        },
+      ],
+    });
+
+    const client = new AnthropicClient({ model: "claude-test" });
+    const result = await client.invokeStructured(
+      {
+        schema: z.object({
+          value: z.string(),
+        }),
+      },
+      [{ role: "user", content: "extract value" }]
+    );
+
+    expect(result.parsed).toEqual({ value: "ok" });
+    expect(result.rawText).toContain('"result"');
+  });
+
+  it("returns null parsed output for non-object simple-tool payloads", async () => {
+    createMessageMock.mockResolvedValue({
+      content: [
+        {
+          type: "tool_use",
+          input: "malformed",
+        },
+      ],
+    });
+
+    const client = new AnthropicClient({ model: "claude-test" });
+    const result = await client.invokeStructured(
+      {
+        schema: z.object({
+          value: z.string(),
+        }),
+      },
+      [{ role: "user", content: "extract value" }]
+    );
+
+    expect(result.parsed).toBeNull();
+    expect(result.rawText).toBe("malformed");
+  });
+
+  it("formats non-Error param validation failures in tool path warnings", async () => {
+    createMessageMock.mockResolvedValue({
+      content: [
+        {
+          type: "tool_use",
+          name: "click",
+          input: {
+            action: {
+              params: {},
+            },
+          },
+        },
+      ],
+    });
+    const warnSpy = jest.spyOn(console, "warn").mockImplementation(() => {});
+
+    const client = new AnthropicClient({ model: "claude-test" });
+    await client.invokeStructured(
+      {
+        schema: z.object({
+          thoughts: z.string().optional(),
+          memory: z.string().optional(),
+          action: z.object({
+            type: z.string(),
+            params: z.record(z.string(), z.unknown()),
+          }),
+        }),
+        actions: [
+          {
+            type: "click",
+            actionParams: {
+              parse: () => {
+                throw { reason: "param parse failed" };
+              },
+            } as unknown as z.ZodTypeAny,
+            run: async () => ({ success: true, message: "ok" }),
+          },
+        ],
+      },
+      [{ role: "user", content: "click it" }]
+    );
+
+    expect(warnSpy).toHaveBeenCalledWith(
+      '[LLM][Anthropic] Failed to validate params for action click: {"reason":"param parse failed"}'
+    );
+    warnSpy.mockRestore();
+  });
+
+  it("sanitizes and truncates oversized schema-validation diagnostics", async () => {
+    createMessageMock.mockResolvedValue({
+      content: [
+        {
+          type: "tool_use",
+          name: "click",
+          input: {
+            action: {
+              params: {
+                value: "ok",
+              },
+            },
+          },
+        },
+      ],
+    });
+    const warnSpy = jest.spyOn(console, "warn").mockImplementation(() => {});
+
+    const client = new AnthropicClient({ model: "claude-test" });
+    await client.invokeStructured(
+      {
+        schema: {
+          parse: () => {
+            throw new Error(`schema\u0000\n${"x".repeat(10_000)}`);
+          },
+        } as unknown as z.ZodTypeAny,
+        actions: [
+          {
+            type: "click",
+            actionParams: z.object({
+              value: z.string(),
+            }),
+            run: async () => ({ success: true, message: "ok" }),
+          },
+        ],
+      },
+      [{ role: "user", content: "click it" }]
+    );
+
+    const warning = String(warnSpy.mock.calls[0]?.[0] ?? "");
+    expect(warning).toContain("[truncated");
+    expect(warning).not.toContain("\u0000");
+    expect(warning).not.toContain("\n");
+    expect(warning.length).toBeLessThan(700);
+    warnSpy.mockRestore();
+  });
+
+  it("uses deterministic tool choice policy for multi-action structured calls", async () => {
+    createMessageMock.mockResolvedValue({
+      content: [
+        {
+          type: "tool_use",
+          name: "click",
+          input: {
+            thoughts: "select click",
+            memory: "state",
+            action: {
+              params: {},
+            },
+          },
+        },
+      ],
+    });
+
+    const client = new AnthropicClient({ model: "claude-test" });
+    const result = await client.invokeStructured(
+      {
+        schema: z.object({
+          thoughts: z.string().optional(),
+          memory: z.string().optional(),
+          action: z.object({
+            type: z.string(),
+            params: z.record(z.string(), z.unknown()),
+          }),
+        }),
+        actions: [
+          {
+            type: "click",
+            actionParams: z.object({}),
+            run: async () => ({ success: true, message: "ok" }),
+          },
+          {
+            type: "type",
+            actionParams: z.object({}),
+            run: async () => ({ success: true, message: "ok" }),
+          },
+        ],
+      },
+      [{ role: "user", content: "pick one action" }]
+    );
+
+    expect(result.parsed).toEqual({
+      thoughts: "select click",
+      memory: "state",
+      action: {
+        type: "click",
+        params: {},
+      },
+    });
+
+    const payload = createMessageMock.mock.calls[0]?.[0] as Record<
+      string,
+      unknown
+    >;
+    expect(payload?.tool_choice).toEqual({
+      type: "any",
+      disable_parallel_tool_use: true,
+    });
+  });
+
+  it("does not crash simple-tool debug logging on circular tool payloads", async () => {
+    const circularTool: Record<string, unknown> = { name: "structured_output" };
+    circularTool.self = circularTool;
+    convertToAnthropicToolMock.mockReturnValue(circularTool);
+    createMessageMock.mockResolvedValue({
+      content: [
+        {
+          type: "tool_use",
+          input: {
+            result: {
+              value: "ok",
+            },
+          },
+        },
+      ],
+    });
+    debugOptions.enabled = true;
+    debugOptions.structuredSchema = true;
+    const logSpy = jest.spyOn(console, "log").mockImplementation(() => {});
+
+    try {
+      const client = new AnthropicClient({ model: "claude-test" });
+      const result = await client.invokeStructured(
+        {
+          schema: z.object({
+            value: z.string(),
+          }),
+        },
+        [{ role: "user", content: "extract value" }]
+      );
+
+      expect(result.parsed).toEqual({ value: "ok" });
+      expect(logSpy).toHaveBeenCalledWith(
+        "[LLM][Anthropic] Simple structured output tool:",
+        expect.stringContaining('"self":"[Circular]"')
+      );
+    } finally {
+      logSpy.mockRestore();
+    }
+  });
+
+  it("continues structured invocation when debug option getter traps", async () => {
+    createMessageMock.mockResolvedValue({
+      content: [
+        {
+          type: "tool_use",
+          input: {
+            result: {
+              value: "ok",
+            },
+          },
+        },
+      ],
+    });
+    getDebugOptions.mockImplementationOnce(() => {
+      throw new Error("debug options trap");
+    });
+
+    const client = new AnthropicClient({ model: "claude-test" });
+    const result = await client.invokeStructured(
+      {
+        schema: z.object({
+          value: z.string(),
+        }),
+      },
+      [{ role: "user", content: "extract value" }]
+    );
+
+    expect(result.parsed).toEqual({ value: "ok" });
+  });
+
+  it("ignores reserved provider option overrides while preserving custom options", async () => {
+    createMessageMock.mockResolvedValue({
+      content: [{ type: "text", text: "ok" }],
+      usage: {
+        input_tokens: 1,
+        output_tokens: 2,
+      },
+    });
+
+    const client = new AnthropicClient({ model: "claude-test" });
+    await client.invoke([{ role: "user", content: "hello" }], {
+      providerOptions: {
+        model: "override-model",
+        messages: [{ role: "user", content: "bad" }],
+        max_tokens: 999,
+        top_p: 0.7,
+      },
+    });
+
+    expect(createMessageMock).toHaveBeenCalledWith(
+      expect.objectContaining({
+        model: "claude-test",
+        messages: [],
+        top_p: 0.7,
+      })
+    );
+    const payload = createMessageMock.mock.calls[0]?.[0] as Record<
+      string,
+      unknown
+    >;
+    expect(payload?.max_tokens).not.toBe(999);
+  });
+
+  it("sanitizes reserved provider options in simple structured path", async () => {
+    createMessageMock.mockResolvedValue({
+      content: [
+        {
+          type: "tool_use",
+          input: {
+            result: {
+              value: "ok",
+            },
+          },
+        },
+      ],
+    });
+
+    const client = new AnthropicClient({ model: "claude-test" });
+    await client.invokeStructured(
+      {
+        schema: z.object({
+          value: z.string(),
+        }),
+        options: {
+          providerOptions: {
+            model: "override-model",
+            messages: [{ role: "user", content: "bad" }],
+            tools: [{ name: "override-tool" }],
+            tool_choice: { type: "any" },
+            top_p: 0.7,
+          },
+        },
+      },
+      [{ role: "user", content: "hello" }]
+    );
+
+    expect(createMessageMock).toHaveBeenCalledWith(
+      expect.objectContaining({
+        model: "claude-test",
+        messages: [],
+        top_p: 0.7,
+      })
+    );
+    const payload = createMessageMock.mock.calls[0]?.[0] as Record<
+      string,
+      unknown
+    >;
+    expect(payload?.tools).toEqual([
+      {
+        name: "structured_output",
+        input_schema: { type: "object", properties: {} },
+      },
+    ]);
+    expect(payload?.tool_choice).toEqual({ type: "tool" });
+  });
+
+  it("sanitizes nested unsafe keys and circular provider options", async () => {
+    createMessageMock.mockResolvedValue({
+      content: [{ type: "text", text: "ok" }],
+      usage: {
+        input_tokens: 1,
+        output_tokens: 2,
+      },
+    });
+
+    const circular: Record<string, unknown> = { id: "node" };
+    circular.self = circular;
+
+    const client = new AnthropicClient({ model: "claude-test" });
+    await client.invoke([{ role: "user", content: "hello" }], {
+      providerOptions: {
+        metadata: {
+          safe: "yes",
+          constructor: "bad",
+          nested: circular,
+        },
+      },
+    });
+
+    expect(createMessageMock).toHaveBeenCalledWith(
+      expect.objectContaining({
+        metadata: {
+          safe: "yes",
+          nested: {
+            id: "node",
+            self: "[Circular]",
+          },
+        },
+      })
+    );
+  });
+
+  it("throws readable error when response content field is unreadable", async () => {
+    const response = new Proxy(
+      {},
+      {
+        get: (_target, prop) => {
+          if (prop === "content") {
+            throw new Error("content getter trap");
+          }
+          return undefined;
+        },
+      }
+    );
+    createMessageMock.mockResolvedValue(response);
+
+    const client = new AnthropicClient({ model: "claude-test" });
+    await expect(
+      client.invoke([{ role: "user", content: "hello" }])
+    ).rejects.toThrow(
+      "[LLM][Anthropic] Invalid response payload: failed to read content (content getter trap)"
+    );
+  });
+
+  it("throws readable error when response content is not an array", async () => {
+    createMessageMock.mockResolvedValue({
+      content: { bad: true },
+    });
+
+    const client = new AnthropicClient({ model: "claude-test" });
+    await expect(
+      client.invoke([{ role: "user", content: "hello" }])
+    ).rejects.toThrow(
+      "[LLM][Anthropic] Invalid response payload: content must be an array"
+    );
+  });
+
+  it("sanitizes and truncates oversized response diagnostics", async () => {
+    const response = new Proxy(
+      {},
+      {
+        get: (_target, prop) => {
+          if (prop === "content") {
+            throw new Error(`content\u0000\n${"x".repeat(2_000)}`);
+          }
+          return undefined;
+        },
+      }
+    );
+    createMessageMock.mockResolvedValue(response);
+
+    const client = new AnthropicClient({ model: "claude-test" });
+    await client
+      .invoke([{ role: "user", content: "hello" }])
+      .then(() => {
+        throw new Error("expected invoke to reject");
+      })
+      .catch((error) => {
+        const message = String(error instanceof Error ? error.message : error);
+        expect(message).toContain("[truncated");
+        expect(message).not.toContain("\u0000");
+        expect(message).not.toContain("\n");
+        expect(message.length).toBeLessThan(700);
+      });
+  });
+});
diff --git a/src/llm/providers/anthropic.ts b/src/llm/providers/anthropic.ts
index ed36dbbe..23359aea 100644
--- a/src/llm/providers/anthropic.ts
+++ b/src/llm/providers/anthropic.ts
@@ -3,6 +3,7 @@ import { z } from "zod";
 import {
   HyperAgentLLM,
   HyperAgentMessage,
+  HyperAgentContentPart,
   HyperAgentStructuredResult,
   HyperAgentCapabilities,
   StructuredOutputRequest,
@@ -13,21 +14,145 @@ import {
   convertToAnthropicTool,
   createAnthropicToolChoice,
 } from "../utils/schema-converter";
+import { sanitizeProviderOptions } from "../utils/provider-options";
 import type { MessageParam } from "@anthropic-ai/sdk/resources/messages/index";
 import { getDebugOptions } from "@/debug/options";
+import { formatUnknownError } from "@/utils";
 
 const ENV_STRUCTURED_SCHEMA_DEBUG =
   process.env.HYPERAGENT_DEBUG_STRUCTURED_SCHEMA === "1" ||
   process.env.HYPERAGENT_DEBUG_STRUCTURED_SCHEMA === "true";
 
+const RESERVED_ANTHROPIC_PROVIDER_OPTION_KEYS = new Set([
+  "model",
+  "messages",
+  "system",
+  "temperature",
+  "max_tokens",
+  "tools",
+  "tool_choice",
+]);
+const MAX_ANTHROPIC_DIAGNOSTIC_CHARS = 300;
+
 function shouldDebugStructuredSchema(): boolean {
-  const opts = getDebugOptions();
+  let opts: ReturnType<typeof getDebugOptions>;
+  try {
+    opts = getDebugOptions();
+  } catch {
+    return ENV_STRUCTURED_SCHEMA_DEBUG;
+  }
   if (opts.enabled && typeof opts.structuredSchema === "boolean") {
     return opts.structuredSchema;
   }
   return ENV_STRUCTURED_SCHEMA_DEBUG;
 }
 
+function isRecord(value: unknown): value is Record<string, unknown> {
+  return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+
+function formatAnthropicDiagnostic(value: unknown): string {
+  const normalized = Array.from(formatUnknownError(value), (char) => {
+    const code = char.charCodeAt(0);
+    return (code >= 0 && code < 32) || code === 127 ? " " : char;
+  })
+    .join("")
+    .replace(/\s+/g, " ")
+    .trim();
+  const fallback = normalized.length > 0 ? normalized : "unknown error";
+  if (fallback.length <= MAX_ANTHROPIC_DIAGNOSTIC_CHARS) {
+    return fallback;
+  }
+  return `${fallback.slice(
+    0,
+    MAX_ANTHROPIC_DIAGNOSTIC_CHARS
+  )}... [truncated ${fallback.length - MAX_ANTHROPIC_DIAGNOSTIC_CHARS} chars]`;
+}
+
+function safeReadOptionalRecordField(
+  source: Record<string, unknown>,
+  key: string
+): unknown {
+  try {
+    return source[key];
+  } catch {
+    return undefined;
+  }
+}
+
+function safeReadRequiredRecordField(
+  source: Record<string, unknown>,
+  key: string,
+  fieldLabel: string
+): unknown {
+  try {
+    return source[key];
+  } catch (error) {
+    throw new Error(
+      `[LLM][Anthropic] Invalid response payload: failed to read ${fieldLabel} (${formatAnthropicDiagnostic(
+        error
+      )})`
+    );
+  }
+}
+
+function extractAnthropicContentBlocks(response: unknown): unknown[] {
+  if (!isRecord(response)) {
+    throw new Error("[LLM][Anthropic] Invalid response payload: response must be an object");
+  }
+  const content = safeReadRequiredRecordField(response, "content", "content");
+  if (!Array.isArray(content)) {
+    throw new Error("[LLM][Anthropic] Invalid response payload: content must be an array");
+  }
+  try {
+    return Array.from(content);
+  } catch (error) {
+    throw new Error(
+      `[LLM][Anthropic] Invalid response payload: failed to iterate content (${formatAnthropicDiagnostic(
+        error
+      )})`
+    );
+  }
+}
+
+function findAnthropicToolUseBlock(contentBlocks: unknown[]): Record<string, unknown> | undefined {
+  return contentBlocks.find(
+    (block) =>
+      isRecord(block) &&
+      safeReadOptionalRecordField(block, "type") === "tool_use"
+  ) as Record<string, unknown> | undefined;
+}
+
+function safeReadAnthropicUsageTokens(
+  response: unknown,
+  key: "input_tokens" | "output_tokens"
+): number | undefined {
+  if (!isRecord(response)) {
+    return undefined;
+  }
+  const usage = safeReadOptionalRecordField(response, "usage");
+  if (!isRecord(usage)) {
+    return undefined;
+  }
+  const value = safeReadOptionalRecordField(usage, key);
+  return typeof value === "number" ? value : undefined;
+}
+
+function stringifyRawPayload(value: unknown): string {
+  if (typeof value === "string") {
+    return value;
+  }
+  return formatUnknownError(value);
+}
+
+function safeDebugStringify(value: unknown): string {
+  try {
+    return JSON.stringify(value, null, 2);
+  } catch {
+    return formatUnknownError(value);
+  }
+}
+
 export interface AnthropicClientConfig {
   apiKey?: string;
   model: string;
@@ -59,33 +184,53 @@ export class AnthropicClient implements HyperAgentLLM {
     }
   ): Promise<{
     role: "assistant";
-    content: string | any[];
+    content: string | HyperAgentContentPart[];
     toolCalls?: Array<{ id?: string; name: string; arguments: unknown }>;
     usage?: { inputTokens?: number; outputTokens?: number };
   }> {
     const { messages: anthropicMessages, system } =
       convertToAnthropicMessages(messages);
+    const providerOptions = sanitizeProviderOptions(
+      options?.providerOptions,
+      RESERVED_ANTHROPIC_PROVIDER_OPTION_KEYS
+    );
 
     const response = await this.client.messages.create({
       model: this.model,
-      messages: anthropicMessages as any,
+      messages:
+        anthropicMessages as unknown as Parameters<
+          typeof this.client.messages.create
+        >[0]["messages"],
       system,
       temperature: options?.temperature ?? this.temperature,
       max_tokens: options?.maxTokens ?? this.maxTokens,
-      ...options?.providerOptions,
+      ...providerOptions,
     });
 
-    const content = response.content[0];
-    if (!content || content.type !== "text") {
+    const contentBlocks = extractAnthropicContentBlocks(response);
+    const textParts = contentBlocks
+      .filter(
+        (block) =>
+          isRecord(block) &&
+          safeReadOptionalRecordField(block, "type") === "text"
+      )
+      .map((block) =>
+        isRecord(block)
+          ? safeReadOptionalRecordField(block, "text")
+          : undefined
+      )
+      .filter((value): value is string => typeof value === "string");
+    const content = textParts.join("\n\n");
+    if (content.length === 0) {
       throw new Error("No text response from Anthropic");
     }
 
     return {
       role: "assistant",
-      content: content.text,
+      content,
       usage: {
-        inputTokens: response.usage.input_tokens,
-        outputTokens: response.usage.output_tokens,
+        inputTokens: safeReadAnthropicUsageTokens(response, "input_tokens"),
+        outputTokens: safeReadAnthropicUsageTokens(response, "output_tokens"),
       },
     };
   }
@@ -142,6 +287,10 @@ export class AnthropicClient implements HyperAgentLLM {
     }
 
     const tools = convertActionsToAnthropicTools(request.actions);
+    const providerOptions = sanitizeProviderOptions(
+      request.options?.providerOptions,
+      RESERVED_ANTHROPIC_PROVIDER_OPTION_KEYS
+    );
 
     const toolChoice =
       tools.length === 1
@@ -154,50 +303,58 @@ export class AnthropicClient implements HyperAgentLLM {
       ...(system ? { system } : {}),
       temperature: request.options?.temperature ?? this.temperature,
       max_tokens: request.options?.maxTokens ?? this.maxTokens,
-      tools: tools as any,
-      tool_choice: toolChoice as any,
-      ...request.options?.providerOptions,
+      tools: tools as unknown as Parameters<
+        typeof this.client.messages.create
+      >[0]["tools"],
+      tool_choice:
+        toolChoice as unknown as Parameters<
+          typeof this.client.messages.create
+        >[0]["tool_choice"],
+      ...providerOptions,
     });
 
-    const toolContent = response.content.find(
-      (block: any) => block.type === "tool_use"
-    ) as
-      | { type: "tool_use"; name: string; input: Record<string, unknown> }
-      | undefined;
+    const responseContent = extractAnthropicContentBlocks(response);
+    const toolContent = findAnthropicToolUseBlock(responseContent);
 
     if (!toolContent) {
       return {
-        rawText: JSON.stringify(response.content ?? []),
+        rawText: stringifyRawPayload(responseContent),
         parsed: null,
       };
     }
 
+    const toolName = safeReadOptionalRecordField(toolContent, "name");
     const actionDefinition = request.actions.find(
-      (action) => (action.toolName ?? action.type) === toolContent.name
+      (action) =>
+        (action.toolName ?? action.type) ===
+        (typeof toolName === "string" ? toolName : "")
     );
     if (!actionDefinition) {
       return {
-        rawText: JSON.stringify(toolContent),
+        rawText: stringifyRawPayload(toolContent),
         parsed: null,
       };
     }
 
-    const input = toolContent.input ?? {};
-    const actionInput = (input as Record<string, unknown>).action ?? {};
-    const params =
-      (actionInput as Record<string, unknown>).params ?? {};
-    const thoughts = (input as Record<string, unknown>).thoughts;
-    const memory = (input as Record<string, unknown>).memory;
+    const inputValue = safeReadOptionalRecordField(toolContent, "input");
+    const input = isRecord(inputValue) ? inputValue : {};
+    const actionValue = safeReadOptionalRecordField(input, "action");
+    const actionInput = isRecord(actionValue) ? actionValue : {};
+    const paramsValue = safeReadOptionalRecordField(actionInput, "params");
+    const params = typeof paramsValue === "undefined" ? {} : paramsValue;
+    const thoughts = safeReadOptionalRecordField(input, "thoughts");
+    const memory = safeReadOptionalRecordField(input, "memory");
     let validatedParams: z.infer<typeof actionDefinition.actionParams>;
     try {
       validatedParams = actionDefinition.actionParams.parse(params);
     } catch (error) {
       console.warn(
-        `[LLM][Anthropic] Failed to validate params for action ${actionDefinition.type}:`,
-        error
+        `[LLM][Anthropic] Failed to validate params for action ${actionDefinition.type}: ${formatAnthropicDiagnostic(
+          error
+        )}`
       );
       return {
-        rawText: JSON.stringify(toolContent),
+        rawText: stringifyRawPayload(toolContent),
         parsed: null,
       };
     }
@@ -214,16 +371,17 @@ export class AnthropicClient implements HyperAgentLLM {
     try {
       const validated = request.schema.parse(structuredOutput);
       return {
-        rawText: JSON.stringify(toolContent),
+        rawText: stringifyRawPayload(toolContent),
         parsed: validated,
       };
     } catch (error) {
       console.warn(
-        "[LLM][Anthropic] Failed to validate structured output against schema:",
-        error
+        `[LLM][Anthropic] Failed to validate structured output against schema: ${formatAnthropicDiagnostic(
+          error
+        )}`
       );
       return {
-        rawText: JSON.stringify(toolContent),
+        rawText: stringifyRawPayload(toolContent),
         parsed: null,
       };
     }
@@ -244,7 +402,7 @@ export class AnthropicClient implements HyperAgentLLM {
     if (shouldDebugStructuredSchema()) {
       console.log(
         "[LLM][Anthropic] Simple structured output tool:",
-        JSON.stringify(tool, null, 2)
+        safeDebugStringify(tool)
       );
     }
 
@@ -254,29 +412,47 @@ export class AnthropicClient implements HyperAgentLLM {
       ...(system ? { system } : {}),
       temperature: request.options?.temperature ?? this.temperature,
       max_tokens: request.options?.maxTokens ?? this.maxTokens,
-      tools: [tool as any],
-      tool_choice: toolChoice as any,
-      ...request.options?.providerOptions,
+      tools: [tool] as unknown as Parameters<
+        typeof this.client.messages.create
+      >[0]["tools"],
+      tool_choice:
+        toolChoice as unknown as Parameters<
+          typeof this.client.messages.create
+        >[0]["tool_choice"],
+      ...sanitizeProviderOptions(
+        request.options?.providerOptions,
+        RESERVED_ANTHROPIC_PROVIDER_OPTION_KEYS
+      ),
     });
 
-    const content = response.content[0];
-    if (!content || content.type !== "tool_use") {
+    const responseContent = extractAnthropicContentBlocks(response);
+    const content = findAnthropicToolUseBlock(responseContent);
+    if (!content) {
       return {
         rawText: "",
         parsed: null,
       };
     }
 
+    const input = safeReadOptionalRecordField(content, "input");
+    if (!isRecord(input)) {
+      return {
+        rawText: stringifyRawPayload(input),
+        parsed: null,
+      };
+    }
+
     try {
-      const input = content.input as any;
-      const validated = request.schema.parse(input.result);
+      const validated = request.schema.parse(
+        safeReadOptionalRecordField(input, "result")
+      );
       return {
-        rawText: JSON.stringify(input),
+        rawText: stringifyRawPayload(input),
         parsed: validated,
       };
     } catch {
       return {
-        rawText: JSON.stringify(content.input),
+        rawText: stringifyRawPayload(input),
         parsed: null,
       };
     }
diff --git a/src/llm/providers/deepseek.test.ts b/src/llm/providers/deepseek.test.ts
new file mode 100644
index 00000000..4e876364
--- /dev/null
+++ b/src/llm/providers/deepseek.test.ts
@@ -0,0 +1,308 @@
+import { DeepSeekClient } from "@/llm/providers/deepseek";
+import { z } from "zod";
+
+const createCompletionMock = jest.fn();
+
+jest.mock("openai", () => {
+  return jest.fn().mockImplementation(() => ({
+    chat: {
+      completions: {
+        create: createCompletionMock,
+      },
+    },
+  }));
+});
+
+jest.mock("@/llm/utils/message-converter", () => ({
+  convertToOpenAIMessages: jest.fn(() => []),
+}));
+
+jest.mock("@/llm/utils/schema-converter", () => ({
+  convertToOpenAIJsonSchema: jest.fn(() => ({ type: "json_schema" })),
+}));
+
+describe("DeepSeekClient", () => {
+  beforeEach(() => {
+    createCompletionMock.mockReset();
+  });
+
+  it("converts array content blocks into HyperAgent content parts", async () => {
+    createCompletionMock.mockResolvedValue({
+      choices: [
+        {
+          message: {
+            content: [
+              { type: "text", text: "alpha" },
+              { type: "tool_call", function: { name: "lookup", arguments: "{broken" } },
+            ],
+          },
+        },
+      ],
+      usage: {
+        prompt_tokens: 3,
+        completion_tokens: 4,
+      },
+    });
+
+    const client = new DeepSeekClient({ model: "deepseek-test" });
+    const result = await client.invoke([{ role: "user", content: "hello" }]);
+
+    expect(result.content).toEqual([
+      { type: "text", text: "alpha" },
+      { type: "tool_call", toolName: "lookup", arguments: "{broken" },
+    ]);
+  });
+
+  it("does not crash on circular unknown array content parts", async () => {
+    const circularPart: Record<string, unknown> = { type: "mystery" };
+    circularPart.self = circularPart;
+
+    createCompletionMock.mockResolvedValue({
+      choices: [
+        {
+          message: {
+            content: [circularPart],
+          },
+        },
+      ],
+    });
+
+    const client = new DeepSeekClient({ model: "deepseek-test" });
+    const result = await client.invoke([{ role: "user", content: "hello" }]);
+
+    expect(result.content).toEqual([
+      {
+        type: "text",
+        text: '{"type":"mystery","self":"[Circular]"}',
+      },
+    ]);
+  });
+
+  it("formats object content payloads instead of returning [object Object]", async () => {
+    createCompletionMock.mockResolvedValue({
+      choices: [
+        {
+          message: {
+            content: { state: "object-content" },
+          },
+        },
+      ],
+    });
+
+    const client = new DeepSeekClient({ model: "deepseek-test" });
+    const result = await client.invoke([{ role: "user", content: "hello" }]);
+
+    expect(result.content).toBe('{"state":"object-content"}');
+  });
+
+  it("throws readable errors for unknown tool call payloads", async () => {
+    createCompletionMock.mockResolvedValue({
+      choices: [
+        {
+          message: {
+            content: "ok",
+            tool_calls: [
+              {
+                id: "tc-1",
+                type: "mystery",
+                data: { reason: "unknown type" },
+              },
+            ],
+          },
+        },
+      ],
+    });
+
+    const client = new DeepSeekClient({ model: "deepseek-test" });
+    await expect(
+      client.invoke([{ role: "user", content: "hello" }])
+    ).rejects.toThrow(
+      '[LLM][DeepSeek] Unknown tool call type: {"id":"tc-1","type":"mystery","data":{"reason":"unknown type"}}'
+    );
+  });
+
+  it("ignores reserved provider options overrides while preserving custom options", async () => {
+    createCompletionMock.mockResolvedValue({
+      choices: [
+        {
+          message: {
+            content: "ok",
+          },
+        },
+      ],
+    });
+
+    const client = new DeepSeekClient({ model: "deepseek-test" });
+    await client.invoke([{ role: "user", content: "hello" }], {
+      providerOptions: {
+        model: "override-model",
+        messages: [{ role: "user", content: "bad" }],
+        max_tokens: 999,
+        top_p: 0.7,
+      },
+    });
+
+    expect(createCompletionMock).toHaveBeenCalledWith(
+      expect.objectContaining({
+        model: "deepseek-test",
+        messages: [],
+        top_p: 0.7,
+      })
+    );
+    const payload = createCompletionMock.mock.calls[0]?.[0] as Record<
+      string,
+      unknown
+    >;
+    expect(payload?.max_tokens).not.toBe(999);
+  });
+
+  it("sanitizes reserved provider options in structured invoke path", async () => {
+    createCompletionMock.mockResolvedValue({
+      choices: [
+        {
+          message: {
+            content: '{"ok":true}',
+          },
+        },
+      ],
+    });
+
+    const client = new DeepSeekClient({ model: "deepseek-test" });
+    await client.invokeStructured(
+      {
+        schema: z.object({ ok: z.boolean() }),
+        options: {
+          providerOptions: {
+            model: "override-model",
+            messages: [{ role: "user", content: "bad" }],
+            response_format: { type: "text" },
+            top_p: 0.4,
+          },
+        },
+      },
+      [{ role: "user", content: "hello" }]
+    );
+
+    expect(createCompletionMock).toHaveBeenCalledWith(
+      expect.objectContaining({
+        model: "deepseek-test",
+        messages: [],
+        response_format: { type: "json_schema" },
+        top_p: 0.4,
+      })
+    );
+  });
+
+  it("sanitizes nested unsafe keys and circular provider options", async () => {
+    createCompletionMock.mockResolvedValue({
+      choices: [
+        {
+          message: {
+            content: "ok",
+          },
+        },
+      ],
+    });
+
+    const circular: Record<string, unknown> = { id: "node" };
+    circular.self = circular;
+
+    const client = new DeepSeekClient({ model: "deepseek-test" });
+    await client.invoke([{ role: "user", content: "hello" }], {
+      providerOptions: {
+        metadata: {
+          safe: "yes",
+          constructor: "bad",
+          nested: circular,
+        },
+      },
+    });
+
+    expect(createCompletionMock).toHaveBeenCalledWith(
+      expect.objectContaining({
+        metadata: {
+          safe: "yes",
+          nested: {
+            id: "node",
+            self: "[Circular]",
+          },
+        },
+      })
+    );
+  });
+
+  it("throws readable error when completion choices are unreadable", async () => {
+    const response = new Proxy(
+      {},
+      {
+        get: (_target, prop) => {
+          if (prop === "choices") {
+            throw new Error("choices getter trap");
+          }
+          return undefined;
+        },
+      }
+    );
+    createCompletionMock.mockResolvedValue(response);
+
+    const client = new DeepSeekClient({ model: "deepseek-test" });
+    await expect(
+      client.invoke([{ role: "user", content: "hello" }])
+    ).rejects.toThrow(
+      "[LLM][DeepSeek] Invalid completion payload: failed to read choices (choices getter trap)"
+    );
+  });
+
+  it("throws readable error when completion message fields are unreadable", async () => {
+    const choice = new Proxy(
+      {},
+      {
+        get: (_target, prop) => {
+          if (prop === "message") {
+            throw new Error("message getter trap");
+          }
+          return undefined;
+        },
+      }
+    );
+    createCompletionMock.mockResolvedValue({
+      choices: [choice],
+    });
+
+    const client = new DeepSeekClient({ model: "deepseek-test" });
+    await expect(
+      client.invoke([{ role: "user", content: "hello" }])
+    ).rejects.toThrow(
+      "[LLM][DeepSeek] Invalid completion payload: failed to read choice.message (message getter trap)"
+    );
+  });
+
+  it("sanitizes and truncates oversized completion diagnostics", async () => {
+    const response = new Proxy(
+      {},
+      {
+        get: (_target, prop) => {
+          if (prop === "choices") {
+            throw new Error(`choices\u0000\n${"x".repeat(2_000)}`);
+          }
+          return undefined;
+        },
+      }
+    );
+    createCompletionMock.mockResolvedValue(response);
+
+    const client = new DeepSeekClient({ model: "deepseek-test" });
+    await client
+      .invoke([{ role: "user", content: "hello" }])
+      .then(() => {
+        throw new Error("expected invoke to reject");
+      })
+      .catch((error) => {
+        const message = String(error instanceof Error ? error.message : error);
+        expect(message).toContain("[truncated");
+        expect(message).not.toContain("\u0000");
+        expect(message).not.toContain("\n");
+        expect(message.length).toBeLessThan(700);
+      });
+  });
+});
diff --git a/src/llm/providers/deepseek.ts b/src/llm/providers/deepseek.ts
index f446caca..cd6e0a7b 100644
--- a/src/llm/providers/deepseek.ts
+++ b/src/llm/providers/deepseek.ts
@@ -9,8 +9,13 @@ import {
   HyperAgentContentPart,
 } from "../types";
 import { convertToOpenAIMessages } from "../utils/message-converter";
+import { normalizeOpenAICompatibleContent } from "../utils/openai-content";
 import { convertToOpenAIJsonSchema } from "../utils/schema-converter";
+import { normalizeOpenAIToolCalls } from "../utils/openai-tool-calls";
+import { sanitizeProviderOptions } from "../utils/provider-options";
+import { parseStructuredResponse } from "../utils/structured-response";
 import { z } from "zod";
+import { formatUnknownError } from "@/utils";
 
 export interface DeepSeekClientConfig {
   apiKey?: string;
@@ -20,6 +25,106 @@ export interface DeepSeekClientConfig {
   baseURL?: string;
 }
 
+const RESERVED_DEEPSEEK_PROVIDER_OPTION_KEYS = new Set([
+  "model",
+  "messages",
+  "temperature",
+  "max_tokens",
+  "maxTokens",
+  "response_format",
+]);
+const MAX_PROVIDER_RESPONSE_DIAGNOSTIC_CHARS = 300;
+
+function isRecord(value: unknown): value is Record<string, unknown> {
+  return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+
+function formatProviderResponseDiagnostic(value: unknown): string {
+  const normalized = Array.from(formatUnknownError(value), (char) => {
+    const code = char.charCodeAt(0);
+    return (code >= 0 && code < 32) || code === 127 ? " " : char;
+  })
+    .join("")
+    .replace(/\s+/g, " ")
+    .trim();
+  const fallback = normalized.length > 0 ? normalized : "unknown error";
+  if (fallback.length <= MAX_PROVIDER_RESPONSE_DIAGNOSTIC_CHARS) {
+    return fallback;
+  }
+  return `${fallback.slice(
+    0,
+    MAX_PROVIDER_RESPONSE_DIAGNOSTIC_CHARS
+  )}... [truncated ${fallback.length - MAX_PROVIDER_RESPONSE_DIAGNOSTIC_CHARS} chars]`;
+}
+
+function safeReadRecordField(
+  source: Record<string, unknown>,
+  key: string,
+  fieldLabel: string,
+  providerLabel: string
+): unknown {
+  try {
+    return source[key];
+  } catch (error) {
+    throw new Error(
+      `[LLM][${providerLabel}] Invalid completion payload: failed to read ${fieldLabel} (${formatProviderResponseDiagnostic(
+        error
+      )})`
+    );
+  }
+}
+
+function extractMessageFromCompletionResponse(
+  response: unknown,
+  providerLabel: string
+): Record<string, unknown> {
+  if (!isRecord(response)) {
+    throw new Error(`[LLM][${providerLabel}] Invalid completion payload: response must be an object`);
+  }
+  const choices = safeReadRecordField(response, "choices", "choices", providerLabel);
+  if (!Array.isArray(choices) || choices.length === 0) {
+    throw new Error(`No response from ${providerLabel}`);
+  }
+  const firstChoice = choices[0];
+  if (!isRecord(firstChoice)) {
+    throw new Error(`[LLM][${providerLabel}] Invalid completion payload: first choice is not an object`);
+  }
+  const message = safeReadRecordField(
+    firstChoice,
+    "message",
+    "choice.message",
+    providerLabel
+  );
+  if (!isRecord(message)) {
+    throw new Error(`[LLM][${providerLabel}] Invalid completion payload: choice.message is not an object`);
+  }
+  return message;
+}
+
+function safeReadUsageTokens(
+  response: unknown,
+  field: "prompt_tokens" | "completion_tokens"
+): number | undefined {
+  if (!isRecord(response)) {
+    return undefined;
+  }
+  let usage: unknown;
+  try {
+    usage = response.usage;
+  } catch {
+    return undefined;
+  }
+  if (!isRecord(usage)) {
+    return undefined;
+  }
+  try {
+    const value = usage[field];
+    return typeof value === "number" ? value : undefined;
+  } catch {
+    return undefined;
+  }
+}
+
 export class DeepSeekClient implements HyperAgentLLM {
   private client: OpenAI;
   private model: string;
@@ -62,46 +167,48 @@ export class DeepSeekClient implements HyperAgentLLM {
     usage?: { inputTokens?: number; outputTokens?: number };
   }> {
     const openAIMessages = convertToOpenAIMessages(messages);
+    const providerOptions = sanitizeProviderOptions(
+      options?.providerOptions,
+      RESERVED_DEEPSEEK_PROVIDER_OPTION_KEYS
+    );
 
     const response = await this.client.chat.completions.create({
       model: this.model,
-      messages: openAIMessages as any,
+      messages:
+        openAIMessages as unknown as Parameters<
+          typeof this.client.chat.completions.create
+        >[0]["messages"],
       temperature: options?.temperature ?? this.temperature,
       max_tokens: options?.maxTokens ?? this.maxTokens,
-      ...options?.providerOptions,
+      ...providerOptions,
     });
 
-    const choice = response.choices[0];
-    if (!choice) {
-      throw new Error("No response from DeepSeek");
-    }
-
-    const content = choice.message.content || "";
-    const toolCalls = choice.message.tool_calls?.map((tc) => {
-      // Handle both function and custom tool calls in OpenAI v6
-      if (tc.type === "function") {
-        return {
-          id: tc.id,
-          name: tc.function.name,
-          arguments: JSON.parse(tc.function.arguments),
-        };
-      } else if (tc.type === "custom") {
-        return {
-          id: tc.id,
-          name: tc.custom.name,
-          arguments: JSON.parse(tc.custom.input),
-        };
-      }
-      throw new Error(`Unknown tool call type: ${(tc as any).type}`);
-    });
+    const message = extractMessageFromCompletionResponse(response, "DeepSeek");
+    const content = normalizeOpenAICompatibleContent(
+      safeReadRecordField(
+        message,
+        "content",
+        "choice.message.content",
+        "DeepSeek"
+      )
+    );
+    const toolCalls = normalizeOpenAIToolCalls(
+      safeReadRecordField(
+        message,
+        "tool_calls",
+        "choice.message.tool_calls",
+        "DeepSeek"
+      ),
+      "DeepSeek"
+    );
 
     return {
       role: "assistant",
       content: content,
       toolCalls: toolCalls,
       usage: {
-        inputTokens: response.usage?.prompt_tokens,
-        outputTokens: response.usage?.completion_tokens,
+        inputTokens: safeReadUsageTokens(response, "prompt_tokens"),
+        outputTokens: safeReadUsageTokens(response, "completion_tokens"),
       },
     };
   }
@@ -111,36 +218,35 @@ export class DeepSeekClient implements HyperAgentLLM {
     messages: HyperAgentMessage[]
   ): Promise<HyperAgentStructuredResult<TSchema>> {
     const openAIMessages = convertToOpenAIMessages(messages);
+    const providerOptions = sanitizeProviderOptions(
+      request.options?.providerOptions,
+      RESERVED_DEEPSEEK_PROVIDER_OPTION_KEYS
+    );
     const responseFormat = convertToOpenAIJsonSchema(request.schema);
 
     const response = await this.client.chat.completions.create({
       model: this.model,
-      messages: openAIMessages as any,
+      messages:
+        openAIMessages as unknown as Parameters<
+          typeof this.client.chat.completions.create
+        >[0]["messages"],
       temperature: request.options?.temperature ?? this.temperature,
       max_tokens: request.options?.maxTokens ?? this.maxTokens,
-      response_format: responseFormat as any,
-      ...request.options?.providerOptions,
+      response_format:
+        responseFormat as unknown as Parameters<
+          typeof this.client.chat.completions.create
+        >[0]["response_format"],
+      ...providerOptions,
     });
 
-    const choice = response.choices[0];
-    if (!choice) {
-      throw new Error("No response from DeepSeek");
-    }
-
-    const content = choice.message.content || "";
-    try {
-      const parsed = JSON.parse(content);
-      const validated = request.schema.parse(parsed);
-      return {
-        rawText: content,
-        parsed: validated,
-      };
-    } catch {
-      return {
-        rawText: content,
-        parsed: null,
-      };
-    }
+    const message = extractMessageFromCompletionResponse(response, "DeepSeek");
+    const content = safeReadRecordField(
+      message,
+      "content",
+      "choice.message.content",
+      "DeepSeek"
+    );
+    return parseStructuredResponse(content, request.schema);
   }
 }
 
diff --git a/src/llm/providers/gemini.test.ts b/src/llm/providers/gemini.test.ts
new file mode 100644
index 00000000..01f6fb58
--- /dev/null
+++ b/src/llm/providers/gemini.test.ts
@@ -0,0 +1,319 @@
+import { z } from "zod";
+import { GeminiClient } from "@/llm/providers/gemini";
+
+const generateContentMock = jest.fn();
+const convertToGeminiMessagesMock: jest.Mock = jest.fn(() => ({
+  messages: [{ role: "user", parts: [{ text: "hello" }] }],
+  systemInstruction: "follow system rules",
+}));
+const convertToGeminiResponseSchemaMock: jest.Mock = jest.fn(() => ({
+  type: "object",
+  properties: { ok: { type: "boolean" } },
+}));
+
+jest.mock("@google/genai", () => ({
+  GoogleGenAI: jest.fn().mockImplementation(() => ({
+    models: {
+      generateContent: generateContentMock,
+    },
+  })),
+}));
+
+jest.mock("@/llm/utils/message-converter", () => ({
+  convertToGeminiMessages: (messages: unknown) =>
+    convertToGeminiMessagesMock(messages),
+}));
+
+jest.mock("@/llm/utils/schema-converter", () => ({
+  convertToGeminiResponseSchema: (schema: unknown) =>
+    convertToGeminiResponseSchemaMock(schema),
+}));
+
+describe("GeminiClient", () => {
+  beforeEach(() => {
+    generateContentMock.mockReset();
+    convertToGeminiMessagesMock.mockReset();
+    convertToGeminiMessagesMock.mockReturnValue({
+      messages: [{ role: "user", parts: [{ text: "hello" }] }],
+      systemInstruction: "follow system rules",
+    });
+    convertToGeminiResponseSchemaMock.mockReset();
+    convertToGeminiResponseSchemaMock.mockReturnValue({
+      type: "object",
+      properties: { ok: { type: "boolean" } },
+    });
+  });
+
+  it("passes options and system instruction for invoke requests", async () => {
+    generateContentMock.mockResolvedValue({
+      text: "result text",
+      usageMetadata: {
+        promptTokenCount: 10,
+        candidatesTokenCount: 5,
+      },
+    });
+
+    const client = new GeminiClient({
+      model: "gemini-test",
+      temperature: 0.1,
+      maxTokens: 50,
+    });
+    const result = await client.invoke(
+      [{ role: "user", content: "hello" }],
+      {
+        temperature: 0.7,
+        maxTokens: 120,
+        providerOptions: { topK: 3 },
+      }
+    );
+
+    expect(result.content).toBe("result text");
+    expect(generateContentMock).toHaveBeenCalledWith({
+      model: "gemini-test",
+      contents: [{ role: "user", parts: [{ text: "hello" }] }],
+      config: {
+        topK: 3,
+        temperature: 0.7,
+        maxOutputTokens: 120,
+        systemInstruction: "follow system rules",
+      },
+    });
+  });
+
+  it("passes structured config while preserving schema constraints", async () => {
+    generateContentMock.mockResolvedValue({
+      text: '{"ok":true}',
+    });
+
+    const client = new GeminiClient({
+      model: "gemini-test",
+      temperature: 0.1,
+      maxTokens: 50,
+    });
+    const result = await client.invokeStructured(
+      {
+        schema: z.object({
+          ok: z.boolean(),
+        }),
+        options: {
+          providerOptions: { topP: 0.9 },
+        },
+      },
+      [{ role: "user", content: "hello" }]
+    );
+
+    expect(result.parsed).toEqual({ ok: true });
+    expect(generateContentMock).toHaveBeenCalledWith({
+      model: "gemini-test",
+      contents: [{ role: "user", parts: [{ text: "hello" }] }],
+      config: {
+        topP: 0.9,
+        temperature: 0.1,
+        maxOutputTokens: 50,
+        systemInstruction: "follow system rules",
+        responseMimeType: "application/json",
+        responseSchema: {
+          type: "object",
+          properties: { ok: { type: "boolean" } },
+        },
+      },
+    });
+  });
+
+  it("throws clear error when invoke response text is missing", async () => {
+    generateContentMock.mockResolvedValue({
+      text: "",
+    });
+
+    const client = new GeminiClient({
+      model: "gemini-test",
+    });
+
+    await expect(
+      client.invoke([{ role: "user", content: "hello" }])
+    ).rejects.toThrow("No text response from Gemini");
+  });
+
+  it("throws readable error when invoke response text is not a string", async () => {
+    generateContentMock.mockResolvedValue({
+      text: { value: "bad-shape" },
+    });
+
+    const client = new GeminiClient({
+      model: "gemini-test",
+    });
+
+    await expect(
+      client.invoke([{ role: "user", content: "hello" }])
+    ).rejects.toThrow(
+      '[LLM][Gemini] Invalid response payload: expected text string, received {"value":"bad-shape"}'
+    );
+  });
+
+  it("returns null structured output when response text getter throws", async () => {
+    const response = new Proxy(
+      {},
+      {
+        get: (_target, prop) => {
+          if (prop === "text") {
+            throw new Error("text getter trap");
+          }
+          return undefined;
+        },
+      }
+    );
+    generateContentMock.mockResolvedValue(response);
+
+    const client = new GeminiClient({
+      model: "gemini-test",
+    });
+
+    const result = await client.invokeStructured(
+      {
+        schema: z.object({ ok: z.boolean() }),
+      },
+      [{ role: "user", content: "hello" }]
+    );
+    expect(result.parsed).toBeNull();
+    expect(result.rawText).toContain("text getter trap");
+  });
+
+  it("sanitizes and truncates oversized text getter diagnostics", async () => {
+    const response = new Proxy(
+      {},
+      {
+        get: (_target, prop) => {
+          if (prop === "text") {
+            throw new Error(`text\u0000\n${"x".repeat(2_000)}`);
+          }
+          return undefined;
+        },
+      }
+    );
+    generateContentMock.mockResolvedValue(response);
+
+    const client = new GeminiClient({
+      model: "gemini-test",
+    });
+
+    const result = await client.invokeStructured(
+      {
+        schema: z.object({ ok: z.boolean() }),
+      },
+      [{ role: "user", content: "hello" }]
+    );
+    expect(result.parsed).toBeNull();
+    expect(result.rawText).toContain("[truncated");
+    expect(result.rawText).not.toContain("\u0000");
+    expect(result.rawText).not.toContain("\n");
+    expect(result.rawText.length).toBeLessThan(700);
+  });
+
+  it("sanitizes reserved config keys from provider options", async () => {
+    generateContentMock.mockResolvedValue({
+      text: "result text",
+    });
+
+    const client = new GeminiClient({
+      model: "gemini-test",
+      temperature: 0.1,
+      maxTokens: 50,
+    });
+    await client.invoke(
+      [{ role: "user", content: "hello" }],
+      {
+        temperature: 0.7,
+        maxTokens: 120,
+        providerOptions: {
+          temperature: 999,
+          maxOutputTokens: 999,
+          systemInstruction: "override",
+          topK: 9,
+        },
+      }
+    );
+
+    expect(generateContentMock).toHaveBeenCalledWith(
+      expect.objectContaining({
+        config: expect.objectContaining({
+          temperature: 0.7,
+          maxOutputTokens: 120,
+          systemInstruction: "follow system rules",
+          topK: 9,
+        }),
+      })
+    );
+  });
+
+  it("ignores non-object provider options safely", async () => {
+    generateContentMock.mockResolvedValue({
+      text: "result text",
+    });
+
+    const client = new GeminiClient({
+      model: "gemini-test",
+      temperature: 0.1,
+      maxTokens: 50,
+    });
+    await client.invoke(
+      [{ role: "user", content: "hello" }],
+      {
+        providerOptions: "oops" as unknown as Record<string, unknown>,
+      }
+    );
+
+    expect(generateContentMock).toHaveBeenCalledWith(
+      expect.objectContaining({
+        config: {
+          temperature: 0.1,
+          maxOutputTokens: 50,
+          systemInstruction: "follow system rules",
+        },
+      })
+    );
+  });
+
+  it("sanitizes nested unsafe keys and circular provider options", async () => {
+    generateContentMock.mockResolvedValue({
+      text: "result text",
+    });
+
+    const circular: Record<string, unknown> = { id: "node" };
+    circular.self = circular;
+
+    const client = new GeminiClient({
+      model: "gemini-test",
+      temperature: 0.1,
+      maxTokens: 50,
+    });
+    await client.invoke(
+      [{ role: "user", content: "hello" }],
+      {
+        providerOptions: {
+          metadata: {
+            safe: "yes",
+            constructor: "bad",
+            nested: circular,
+          },
+        },
+      }
+    );
+
+    expect(generateContentMock).toHaveBeenCalledWith(
+      expect.objectContaining({
+        config: {
+          metadata: {
+            safe: "yes",
+            nested: {
+              id: "node",
+              self: "[Circular]",
+            },
+          },
+          temperature: 0.1,
+          maxOutputTokens: 50,
+          systemInstruction: "follow system rules",
+        },
+      })
+    );
+  });
+});
diff --git a/src/llm/providers/gemini.ts b/src/llm/providers/gemini.ts
index 8b591f7f..e5584c96 100644
--- a/src/llm/providers/gemini.ts
+++ b/src/llm/providers/gemini.ts
@@ -3,12 +3,72 @@ import { z } from "zod";
 import {
   HyperAgentLLM,
   HyperAgentMessage,
+  HyperAgentContentPart,
   HyperAgentStructuredResult,
   HyperAgentCapabilities,
   StructuredOutputRequest,
 } from "../types";
 import { convertToGeminiMessages } from "../utils/message-converter";
 import { convertToGeminiResponseSchema } from "../utils/schema-converter";
+import { sanitizeProviderOptions } from "../utils/provider-options";
+import { parseStructuredResponse } from "../utils/structured-response";
+import { formatUnknownError } from "@/utils";
+
+const RESERVED_GEMINI_CONFIG_OPTION_KEYS = new Set([
+  "temperature",
+  "maxOutputTokens",
+  "systemInstruction",
+  "responseMimeType",
+  "responseSchema",
+]);
+const MAX_GEMINI_DIAGNOSTIC_CHARS = 300;
+
+function formatGeminiDiagnostic(value: unknown): string {
+  const normalized = Array.from(formatUnknownError(value), (char) => {
+    const code = char.charCodeAt(0);
+    return (code >= 0 && code < 32) || code === 127 ? " " : char;
+  })
+    .join("")
+    .replace(/\s+/g, " ")
+    .trim();
+  const fallback = normalized.length > 0 ? normalized : "unknown error";
+  if (fallback.length <= MAX_GEMINI_DIAGNOSTIC_CHARS) {
+    return fallback;
+  }
+  return `${fallback.slice(
+    0,
+    MAX_GEMINI_DIAGNOSTIC_CHARS
+  )}... [truncated ${fallback.length - MAX_GEMINI_DIAGNOSTIC_CHARS} chars]`;
+}
+
+function safeReadGeminiResponseText(response: unknown): unknown {
+  try {
+    return (response as { text?: unknown }).text;
+  } catch (error) {
+    return `[Unreadable Gemini response text: ${formatGeminiDiagnostic(error)}]`;
+  }
+}
+
+function safeReadGeminiUsageTokens(
+  response: unknown,
+  key: "promptTokenCount" | "candidatesTokenCount"
+): number | undefined {
+  let usageMetadata: unknown;
+  try {
+    usageMetadata = (response as { usageMetadata?: unknown }).usageMetadata;
+  } catch {
+    return undefined;
+  }
+  if (!usageMetadata || typeof usageMetadata !== "object") {
+    return undefined;
+  }
+  try {
+    const value = (usageMetadata as Record<string, unknown>)[key];
+    return typeof value === "number" ? value : undefined;
+  } catch {
+    return undefined;
+  }
+}
 
 export interface GeminiClientConfig {
   apiKey?: string;
@@ -35,6 +95,30 @@ export class GeminiClient implements HyperAgentLLM {
     this.maxTokens = config.maxTokens;
   }
 
+  private buildGeminiConfig(
+    options?: {
+      temperature?: number;
+      maxTokens?: number;
+      providerOptions?: Record<string, unknown>;
+    },
+    systemInstruction?: string
+  ): Record<string, unknown> {
+    const resolvedMaxTokens = options?.maxTokens ?? this.maxTokens;
+    const providerOptions = sanitizeProviderOptions(
+      options?.providerOptions,
+      RESERVED_GEMINI_CONFIG_OPTION_KEYS
+    );
+
+    return {
+      ...(providerOptions ?? {}),
+      temperature: options?.temperature ?? this.temperature,
+      ...(typeof resolvedMaxTokens === "number"
+        ? { maxOutputTokens: resolvedMaxTokens }
+        : {}),
+      ...(systemInstruction ? { systemInstruction } : {}),
+    };
+  }
+
   async invoke(
     messages: HyperAgentMessage[],
     options?: {
@@ -44,28 +128,43 @@ export class GeminiClient implements HyperAgentLLM {
     }
   ): Promise<{
     role: "assistant";
-    content: string | any[];
+    content: string | HyperAgentContentPart[];
     toolCalls?: Array<{ id?: string; name: string; arguments: unknown }>;
     usage?: { inputTokens?: number; outputTokens?: number };
   }> {
-    const { messages: geminiMessages } = convertToGeminiMessages(messages);
+    const { messages: geminiMessages, systemInstruction } =
+      convertToGeminiMessages(messages);
 
     const response = await this.client.models.generateContent({
       model: this.model,
-      contents: geminiMessages as any,
+      contents:
+        geminiMessages as Parameters<
+          typeof this.client.models.generateContent
+        >[0]["contents"],
+      config: this.buildGeminiConfig(options, systemInstruction),
     });
 
-    const text = response.text;
+    const text = safeReadGeminiResponseText(response);
     if (!text) {
       throw new Error("No text response from Gemini");
     }
+    if (typeof text !== "string") {
+      throw new Error(
+        `[LLM][Gemini] Invalid response payload: expected text string, received ${formatGeminiDiagnostic(
+          text
+        )}`
+      );
+    }
 
     return {
       role: "assistant",
       content: text,
       usage: {
-        inputTokens: response.usageMetadata?.promptTokenCount,
-        outputTokens: response.usageMetadata?.candidatesTokenCount,
+        inputTokens: safeReadGeminiUsageTokens(response, "promptTokenCount"),
+        outputTokens: safeReadGeminiUsageTokens(
+          response,
+          "candidatesTokenCount"
+        ),
       },
     };
   }
@@ -74,42 +173,25 @@ export class GeminiClient implements HyperAgentLLM {
     request: StructuredOutputRequest<TSchema>,
     messages: HyperAgentMessage[]
   ): Promise<HyperAgentStructuredResult<TSchema>> {
-    const { messages: geminiMessages } = convertToGeminiMessages(messages);
+    const { messages: geminiMessages, systemInstruction } =
+      convertToGeminiMessages(messages);
     const responseSchema = convertToGeminiResponseSchema(request.schema);
 
     const response = await this.client.models.generateContent({
       model: this.model,
-      contents: geminiMessages as any,
+      contents:
+        geminiMessages as Parameters<
+          typeof this.client.models.generateContent
+        >[0]["contents"],
       config: {
-        temperature: request.options?.temperature ?? this.temperature,
-        maxOutputTokens: request.options?.maxTokens ?? this.maxTokens,
+        ...this.buildGeminiConfig(request.options, systemInstruction),
         responseMimeType: "application/json",
         responseSchema: responseSchema,
       },
     });
 
-    const text = response.text;
-    if (!text) {
-      return {
-        rawText: "",
-        parsed: null,
-      };
-    }
-
-    try {
-      // Gemini returns pure JSON when using responseJsonSchema
-      const parsed = JSON.parse(text);
-      const validated = request.schema.parse(parsed);
-      return {
-        rawText: text,
-        parsed: validated,
-      };
-    } catch {
-      return {
-        rawText: text,
-        parsed: null,
-      };
-    }
+    const text = safeReadGeminiResponseText(response);
+    return parseStructuredResponse(text, request.schema);
   }
 
   getProviderId(): string {
diff --git a/src/llm/providers/index.test.ts b/src/llm/providers/index.test.ts
new file mode 100644
index 00000000..caac5a7a
--- /dev/null
+++ b/src/llm/providers/index.test.ts
@@ -0,0 +1,290 @@
+const createOpenAIClientMock = jest.fn();
+const createAnthropicClientMock = jest.fn();
+const createGeminiClientMock = jest.fn();
+const createDeepSeekClientMock = jest.fn();
+
+jest.mock("@/llm/providers/openai", () => ({
+  createOpenAIClient: (...args: unknown[]) => createOpenAIClientMock(...args),
+}));
+
+jest.mock("@/llm/providers/anthropic", () => ({
+  createAnthropicClient: (...args: unknown[]) =>
+    createAnthropicClientMock(...args),
+}));
+
+jest.mock("@/llm/providers/gemini", () => ({
+  createGeminiClient: (...args: unknown[]) => createGeminiClientMock(...args),
+}));
+
+jest.mock("@/llm/providers/deepseek", () => ({
+  createDeepSeekClient: (...args: unknown[]) =>
+    createDeepSeekClientMock(...args),
+}));
+
+import { createLLMClient, LLMConfig } from "@/llm/providers";
+
+describe("createLLMClient", () => {
+  beforeEach(() => {
+    createOpenAIClientMock.mockReset();
+    createAnthropicClientMock.mockReset();
+    createGeminiClientMock.mockReset();
+    createDeepSeekClientMock.mockReset();
+    createOpenAIClientMock.mockReturnValue({ provider: "openai" });
+    createAnthropicClientMock.mockReturnValue({ provider: "anthropic" });
+    createGeminiClientMock.mockReturnValue({ provider: "gemini" });
+    createDeepSeekClientMock.mockReturnValue({ provider: "deepseek" });
+  });
+
+  it("normalizes provider/model/baseURL and numeric values", () => {
+    const client = createLLMClient({
+      provider: " OpenAI " as unknown as LLMConfig["provider"],
+      model: " gpt-4o-mini ",
+      temperature: Number.NaN,
+      maxTokens: 120.7,
+      baseURL: " https://example.com/v1 ",
+    });
+
+    expect(client).toEqual({ provider: "openai" });
+    expect(createOpenAIClientMock).toHaveBeenCalledWith({
+      apiKey: undefined,
+      model: "gpt-4o-mini",
+      temperature: undefined,
+      maxTokens: 120,
+      baseURL: "https://example.com/v1",
+    });
+  });
+
+  it("strips control characters from provider identifiers", () => {
+    const client = createLLMClient({
+      provider: "open\u0000ai" as unknown as LLMConfig["provider"],
+      model: "gpt-test",
+    });
+
+    expect(client).toEqual({ provider: "openai" });
+    expect(createOpenAIClientMock).toHaveBeenCalledWith({
+      apiKey: undefined,
+      model: "gpt-test",
+      temperature: undefined,
+      maxTokens: undefined,
+      baseURL: undefined,
+    });
+  });
+
+  it("normalizes apiKey and trims trailing baseURL slash", () => {
+    createLLMClient({
+      provider: "openai",
+      apiKey: "  key-123  ",
+      model: "model",
+      baseURL: "https://example.com/v1/",
+    });
+
+    expect(createOpenAIClientMock).toHaveBeenCalledWith({
+      apiKey: "key-123",
+      model: "model",
+      temperature: undefined,
+      maxTokens: undefined,
+      baseURL: "https://example.com/v1",
+    });
+  });
+
+  it("normalizes deepseek config and drops invalid maxTokens", () => {
+    const client = createLLMClient({
+      provider: "deepseek",
+      model: " deepseek-reasoner ",
+      maxTokens: 0,
+      baseURL: " ",
+    });
+
+    expect(client).toEqual({ provider: "deepseek" });
+    expect(createDeepSeekClientMock).toHaveBeenCalledWith({
+      apiKey: undefined,
+      model: "deepseek-reasoner",
+      temperature: undefined,
+      maxTokens: undefined,
+      baseURL: undefined,
+    });
+  });
+
+  it("drops out-of-range temperatures and preserves valid values", () => {
+    createLLMClient({
+      provider: "openai",
+      model: "model",
+      temperature: 2.5,
+    });
+    expect(createOpenAIClientMock).toHaveBeenLastCalledWith({
+      apiKey: undefined,
+      model: "model",
+      temperature: undefined,
+      maxTokens: undefined,
+      baseURL: undefined,
+    });
+
+    createLLMClient({
+      provider: "openai",
+      model: "model",
+      temperature: 1.25,
+    });
+    expect(createOpenAIClientMock).toHaveBeenLastCalledWith({
+      apiKey: undefined,
+      model: "model",
+      temperature: 1.25,
+      maxTokens: undefined,
+      baseURL: undefined,
+    });
+  });
+
+  it("rejects unsupported provider values", () => {
+    expect(() =>
+      createLLMClient({
+        provider: "mystery" as unknown as LLMConfig["provider"],
+        model: "model",
+      })
+    ).toThrow("Unsupported provider: mystery");
+  });
+
+  it("rejects excessively long provider identifiers", () => {
+    const hugeProvider = "p".repeat(100);
+    expect(() =>
+      createLLMClient({
+        provider: hugeProvider as unknown as LLMConfig["provider"],
+        model: "model",
+      })
+    ).toThrow("LLM provider exceeds maximum length of 40 characters");
+  });
+
+  it("rejects empty model values", () => {
+    expect(() =>
+      createLLMClient({
+        provider: "openai",
+        model: "   ",
+      })
+    ).toThrow("LLM model must be a non-empty string");
+  });
+
+  it("strips control characters from model identifiers", () => {
+    createLLMClient({
+      provider: "openai",
+      model: "gpt-\u0000test",
+    });
+
+    expect(createOpenAIClientMock).toHaveBeenCalledWith({
+      apiKey: undefined,
+      model: "gpt-test",
+      temperature: undefined,
+      maxTokens: undefined,
+      baseURL: undefined,
+    });
+  });
+
+  it("rejects excessively long model identifiers", () => {
+    const hugeModel = "m".repeat(300);
+    expect(() =>
+      createLLMClient({
+        provider: "openai",
+        model: hugeModel,
+      })
+    ).toThrow("LLM model exceeds maximum length of 200 characters");
+  });
+
+  it("rejects invalid baseURL values", () => {
+    expect(() =>
+      createLLMClient({
+        provider: "openai",
+        model: "model",
+        baseURL: "not-a-url",
+      })
+    ).toThrow("Invalid LLM baseURL: not-a-url");
+  });
+
+  it("rejects unsupported baseURL protocols", () => {
+    expect(() =>
+      createLLMClient({
+        provider: "openai",
+        model: "model",
+        baseURL: "ftp://example.com/path",
+      })
+    ).toThrow("Invalid LLM baseURL protocol: ftp:");
+  });
+
+  it("ignores invalid baseURL for providers that do not use it", () => {
+    expect(() =>
+      createLLMClient({
+        provider: "anthropic",
+        model: "claude-3-5-sonnet",
+        baseURL: "not-a-url",
+      })
+    ).not.toThrow();
+
+    expect(createAnthropicClientMock).toHaveBeenCalledWith({
+      apiKey: undefined,
+      model: "claude-3-5-sonnet",
+      temperature: undefined,
+      maxTokens: undefined,
+    });
+  });
+
+  it("rejects non-object configs with a readable error", () => {
+    expect(() =>
+      createLLMClient(undefined as unknown as LLMConfig)
+    ).toThrow("Invalid LLM config: config must be an object");
+  });
+
+  it("throws readable errors when config field getters throw", () => {
+    const providerTrapConfig = new Proxy(
+      {},
+      {
+        get: (_target, prop) => {
+          if (prop === "provider") {
+            throw new Error("provider trap");
+          }
+          return undefined;
+        },
+      }
+    );
+    expect(() =>
+      createLLMClient(providerTrapConfig as unknown as LLMConfig)
+    ).toThrow('Invalid LLM config: failed to read "provider" (provider trap)');
+
+    const modelTrapConfig = new Proxy(
+      {
+        provider: "openai",
+      },
+      {
+        get: (target, prop, receiver) => {
+          if (prop === "model") {
+            throw new Error("model trap");
+          }
+          return Reflect.get(target, prop, receiver);
+        },
+      }
+    );
+    expect(() =>
+      createLLMClient(modelTrapConfig as unknown as LLMConfig)
+    ).toThrow('Invalid LLM config: failed to read "model" (model trap)');
+  });
+
+  it("sanitizes and truncates oversized config getter diagnostics", () => {
+    const providerTrapConfig = new Proxy(
+      {},
+      {
+        get: (_target, prop) => {
+          if (prop === "provider") {
+            throw new Error(`provider\u0000\n${"x".repeat(2_000)}`);
+          }
+          return undefined;
+        },
+      }
+    );
+
+    let errorMessage = "";
+    try {
+      createLLMClient(providerTrapConfig as unknown as LLMConfig);
+    } catch (error) {
+      errorMessage = String(error instanceof Error ? error.message : error);
+    }
+    expect(errorMessage).toContain("[truncated");
+    expect(errorMessage).not.toContain("\u0000");
+    expect(errorMessage).not.toContain("\n");
+    expect(errorMessage.length).toBeLessThan(400);
+  });
+});
diff --git a/src/llm/providers/index.ts b/src/llm/providers/index.ts
index e6797ab8..39d6bc1e 100644
--- a/src/llm/providers/index.ts
+++ b/src/llm/providers/index.ts
@@ -3,6 +3,7 @@ import { createOpenAIClient, OpenAIClientConfig } from "./openai";
 import { createAnthropicClient, AnthropicClientConfig } from "./anthropic";
 import { createGeminiClient, GeminiClientConfig } from "./gemini";
 import { createDeepSeekClient, DeepSeekClientConfig } from "./deepseek";
+import { formatUnknownError } from "@/utils";
 
 export type LLMProvider = "openai" | "anthropic" | "gemini" | "deepseek";
 
@@ -15,44 +16,197 @@ export interface LLMConfig {
   baseURL?: string; // For OpenAI custom endpoints
 }
 
+const MAX_MODEL_ID_CHARS = 200;
+const MAX_PROVIDER_ID_CHARS = 40;
+const MAX_LLM_CONFIG_DIAGNOSTIC_CHARS = 200;
+
+function truncateLLMConfigDiagnostic(value: string): string {
+  if (value.length <= MAX_LLM_CONFIG_DIAGNOSTIC_CHARS) {
+    return value;
+  }
+  return `${value.slice(
+    0,
+    MAX_LLM_CONFIG_DIAGNOSTIC_CHARS
+  )}... [truncated ${value.length - MAX_LLM_CONFIG_DIAGNOSTIC_CHARS} chars]`;
+}
+
+function formatLLMConfigDiagnostic(value: unknown): string {
+  const normalized = Array.from(formatUnknownError(value), (char) => {
+    const code = char.charCodeAt(0);
+    return (code >= 0 && code < 32) || code === 127 ? " " : char;
+  })
+    .join("")
+    .replace(/\s+/g, " ")
+    .trim();
+  const fallback = normalized.length > 0 ? normalized : "unknown error";
+  return truncateLLMConfigDiagnostic(fallback);
+}
+
+function safeReadConfigField(
+  config: Record<string, unknown>,
+  field: keyof LLMConfig
+): unknown {
+  try {
+    return config[field];
+  } catch (error) {
+    throw new Error(
+      `Invalid LLM config: failed to read "${field}" (${formatLLMConfigDiagnostic(
+        error
+      )})`
+    );
+  }
+}
+
+function normalizeProvider(provider: unknown): LLMProvider {
+  if (typeof provider !== "string") {
+    throw new Error("LLM provider must be a string");
+  }
+
+  const normalized = provider
+    .replace(/[\u0000-\u001F\u007F]/g, "")
+    .trim()
+    .toLowerCase();
+  if (normalized.length > MAX_PROVIDER_ID_CHARS) {
+    throw new Error(
+      `LLM provider exceeds maximum length of ${MAX_PROVIDER_ID_CHARS} characters`
+    );
+  }
+  if (
+    normalized === "openai" ||
+    normalized === "anthropic" ||
+    normalized === "gemini" ||
+    normalized === "deepseek"
+  ) {
+    return normalized;
+  }
+
+  throw new Error(`Unsupported provider: ${provider}`);
+}
+
+function normalizeModel(model: unknown): string {
+  if (typeof model !== "string") {
+    throw new Error("LLM model must be a non-empty string");
+  }
+  const normalized = model
+    .replace(/[\u0000-\u001F\u007F]/g, "")
+    .trim();
+  if (normalized.length === 0) {
+    throw new Error("LLM model must be a non-empty string");
+  }
+  if (normalized.length > MAX_MODEL_ID_CHARS) {
+    throw new Error(
+      `LLM model exceeds maximum length of ${MAX_MODEL_ID_CHARS} characters`
+    );
+  }
+  return normalized;
+}
+
+function normalizeTemperature(value: unknown): number | undefined {
+  if (typeof value !== "number" || !Number.isFinite(value)) {
+    return undefined;
+  }
+  if (value < 0 || value > 2) {
+    return undefined;
+  }
+  return value;
+}
+
+function normalizeMaxTokens(value: unknown): number | undefined {
+  if (typeof value !== "number" || !Number.isFinite(value)) {
+    return undefined;
+  }
+  if (value <= 0) {
+    return undefined;
+  }
+  return Math.floor(value);
+}
+
+function normalizeBaseURL(value: unknown): string | undefined {
+  if (typeof value !== "string") {
+    return undefined;
+  }
+  const trimmed = value.trim();
+  if (trimmed.length === 0) {
+    return undefined;
+  }
+
+  let parsed: URL;
+  try {
+    parsed = new URL(trimmed);
+  } catch {
+    throw new Error(`Invalid LLM baseURL: ${trimmed}`);
+  }
+
+  if (parsed.protocol !== "http:" && parsed.protocol !== "https:") {
+    throw new Error(`Invalid LLM baseURL protocol: ${parsed.protocol}`);
+  }
+
+  return parsed.toString().replace(/\/$/, "");
+}
+
+function normalizeApiKey(value: unknown): string | undefined {
+  if (typeof value !== "string") {
+    return undefined;
+  }
+  const trimmed = value.trim();
+  return trimmed.length > 0 ? trimmed : undefined;
+}
+
 export function createLLMClient(config: LLMConfig): HyperAgentLLM {
-  switch (config.provider) {
+  if (!config || typeof config !== "object") {
+    throw new Error("Invalid LLM config: config must be an object");
+  }
+
+  const configRecord = config as unknown as Record<string, unknown>;
+  const provider = normalizeProvider(safeReadConfigField(configRecord, "provider"));
+  const model = normalizeModel(safeReadConfigField(configRecord, "model"));
+  const temperature = normalizeTemperature(
+    safeReadConfigField(configRecord, "temperature")
+  );
+  const maxTokens = normalizeMaxTokens(safeReadConfigField(configRecord, "maxTokens"));
+  const baseURL =
+    provider === "openai" || provider === "deepseek"
+      ? normalizeBaseURL(safeReadConfigField(configRecord, "baseURL"))
+      : undefined;
+  const apiKey = normalizeApiKey(safeReadConfigField(configRecord, "apiKey"));
+
+  switch (provider) {
     case "openai":
       return createOpenAIClient({
-        apiKey: config.apiKey,
-        model: config.model,
-        temperature: config.temperature,
-        maxTokens: config.maxTokens,
-        baseURL: config.baseURL,
+        apiKey,
+        model,
+        temperature,
+        maxTokens,
+        baseURL,
       });
 
     case "anthropic":
       return createAnthropicClient({
-        apiKey: config.apiKey,
-        model: config.model,
-        temperature: config.temperature,
-        maxTokens: config.maxTokens,
+        apiKey,
+        model,
+        temperature,
+        maxTokens,
       });
 
     case "gemini":
       return createGeminiClient({
-        apiKey: config.apiKey,
-        model: config.model,
-        temperature: config.temperature,
-        maxTokens: config.maxTokens,
+        apiKey,
+        model,
+        temperature,
+        maxTokens,
       });
 
     case "deepseek":
       return createDeepSeekClient({
-        apiKey: config.apiKey,
-        model: config.model,
-        temperature: config.temperature,
-        maxTokens: config.maxTokens,
-        baseURL: config.baseURL,
+        apiKey,
+        model,
+        temperature,
+        maxTokens,
+        baseURL,
       });
 
     default:
-      throw new Error(`Unsupported provider: ${config.provider}`);
+      throw new Error(`Unsupported provider: ${provider}`);
   }
 }
 
diff --git a/src/llm/providers/openai.test.ts b/src/llm/providers/openai.test.ts
new file mode 100644
index 00000000..0e56dcfc
--- /dev/null
+++ b/src/llm/providers/openai.test.ts
@@ -0,0 +1,405 @@
+import { OpenAIClient } from "@/llm/providers/openai";
+import { z } from "zod";
+
+const createCompletionMock = jest.fn();
+const convertToOpenAIJsonSchemaMock: jest.Mock = jest.fn(() => ({
+  type: "json_schema",
+}));
+const debugOptions = {
+  enabled: false,
+  structuredSchema: false,
+};
+
+jest.mock("openai", () => {
+  return jest.fn().mockImplementation(() => ({
+    chat: {
+      completions: {
+        create: createCompletionMock,
+      },
+    },
+  }));
+});
+
+jest.mock("@/llm/utils/message-converter", () => ({
+  convertToOpenAIMessages: jest.fn(() => []),
+}));
+
+jest.mock("@/llm/utils/schema-converter", () => ({
+  convertToOpenAIJsonSchema: (schema: unknown) =>
+    convertToOpenAIJsonSchemaMock(schema),
+}));
+
+jest.mock("@/debug/options", () => ({
+  getDebugOptions: jest.fn(() => debugOptions),
+}));
+
+const { getDebugOptions } = jest.requireMock("@/debug/options") as {
+  getDebugOptions: jest.Mock;
+};
+
+describe("OpenAIClient", () => {
+  beforeEach(() => {
+    createCompletionMock.mockReset();
+    convertToOpenAIJsonSchemaMock.mockReset();
+    convertToOpenAIJsonSchemaMock.mockReturnValue({ type: "json_schema" });
+    debugOptions.enabled = false;
+    debugOptions.structuredSchema = false;
+  });
+
+  it("does not crash on unknown circular content parts", async () => {
+    const circularPart: Record<string, unknown> = { type: "unknown" };
+    circularPart.self = circularPart;
+
+    createCompletionMock.mockResolvedValue({
+      choices: [
+        {
+          message: {
+            content: [circularPart],
+          },
+        },
+      ],
+      usage: {
+        prompt_tokens: 1,
+        completion_tokens: 2,
+      },
+    });
+
+    const client = new OpenAIClient({ model: "gpt-test" });
+    const result = await client.invoke([{ role: "user", content: "hello" }]);
+
+    expect(Array.isArray(result.content)).toBe(true);
+    const firstPart = (result.content as Array<{ text?: string }>)[0];
+    expect(firstPart?.text).toContain('"self":"[Circular]"');
+  });
+
+  it("formats object content payloads instead of returning [object Object]", async () => {
+    createCompletionMock.mockResolvedValue({
+      choices: [
+        {
+          message: {
+            content: { state: "object-content" },
+          },
+        },
+      ],
+    });
+
+    const client = new OpenAIClient({ model: "gpt-test" });
+    const result = await client.invoke([{ role: "user", content: "hello" }]);
+
+    expect(result.content).toBe('{"state":"object-content"}');
+  });
+
+  it("preserves malformed tool call arguments as raw strings", async () => {
+    createCompletionMock.mockResolvedValue({
+      choices: [
+        {
+          message: {
+            content: "ok",
+            tool_calls: [
+              {
+                id: "tc-1",
+                type: "function",
+                function: {
+                  name: "lookup",
+                  arguments: "{broken",
+                },
+              },
+            ],
+          },
+        },
+      ],
+    });
+
+    const client = new OpenAIClient({ model: "gpt-test" });
+    const result = await client.invoke([{ role: "user", content: "hello" }]);
+
+    expect(result.toolCalls?.[0]).toEqual({
+      id: "tc-1",
+      name: "lookup",
+      arguments: "{broken",
+    });
+  });
+
+  it("throws readable errors for unknown tool call payloads", async () => {
+    createCompletionMock.mockResolvedValue({
+      choices: [
+        {
+          message: {
+            content: "ok",
+            tool_calls: [
+              {
+                id: "tc-1",
+                type: "mystery",
+                data: { reason: "unknown type" },
+              },
+            ],
+          },
+        },
+      ],
+    });
+
+    const client = new OpenAIClient({ model: "gpt-test" });
+    await expect(
+      client.invoke([{ role: "user", content: "hello" }])
+    ).rejects.toThrow(
+      '[LLM][OpenAI] Unknown tool call type: {"id":"tc-1","type":"mystery","data":{"reason":"unknown type"}}'
+    );
+  });
+
+  it("ignores reserved provider options overrides while preserving custom options", async () => {
+    createCompletionMock.mockResolvedValue({
+      choices: [
+        {
+          message: {
+            content: "ok",
+          },
+        },
+      ],
+    });
+
+    const client = new OpenAIClient({ model: "gpt-test" });
+    await client.invoke([{ role: "user", content: "hello" }], {
+      providerOptions: {
+        model: "override-model",
+        " Model ": "override-again",
+        messages: [{ role: "user", content: "bad" }],
+        max_tokens: 999,
+        top_p: 0.7,
+      },
+    });
+
+    expect(createCompletionMock).toHaveBeenCalledWith(
+      expect.objectContaining({
+        model: "gpt-test",
+        messages: [],
+        top_p: 0.7,
+      })
+    );
+    const payload = createCompletionMock.mock.calls[0]?.[0] as Record<
+      string,
+      unknown
+    >;
+    expect(payload?.max_tokens).not.toBe(999);
+  });
+
+  it("sanitizes reserved provider options in structured invoke path", async () => {
+    createCompletionMock.mockResolvedValue({
+      choices: [
+        {
+          message: {
+            content: '{"ok":"yes"}',
+          },
+        },
+      ],
+    });
+
+    const client = new OpenAIClient({ model: "gpt-test" });
+    await client.invokeStructured(
+      {
+        schema: z.object({ ok: z.string() }),
+        options: {
+          providerOptions: {
+            model: "override-model",
+            messages: [{ role: "user", content: "bad" }],
+            response_format: { type: "text" },
+            top_p: 0.4,
+          },
+        },
+      },
+      [{ role: "user", content: "hello" }]
+    );
+
+    expect(createCompletionMock).toHaveBeenCalledWith(
+      expect.objectContaining({
+        model: "gpt-test",
+        messages: [],
+        response_format: { type: "json_schema" },
+        top_p: 0.4,
+      })
+    );
+  });
+
+  it("sanitizes nested unsafe keys and circular provider options", async () => {
+    createCompletionMock.mockResolvedValue({
+      choices: [
+        {
+          message: {
+            content: "ok",
+          },
+        },
+      ],
+    });
+
+    const circular: Record<string, unknown> = { id: "node" };
+    circular.self = circular;
+
+    const client = new OpenAIClient({ model: "gpt-test" });
+    await client.invoke([{ role: "user", content: "hello" }], {
+      providerOptions: {
+        metadata: {
+          safe: "yes",
+          constructor: "bad",
+          nested: circular,
+        },
+      },
+    });
+
+    expect(createCompletionMock).toHaveBeenCalledWith(
+      expect.objectContaining({
+        metadata: {
+          safe: "yes",
+          nested: {
+            id: "node",
+            self: "[Circular]",
+          },
+        },
+      })
+    );
+  });
+
+  it("does not crash structured-schema debug logging on circular schema payloads", async () => {
+    const circularSchema: Record<string, unknown> = {};
+    circularSchema.self = circularSchema;
+    convertToOpenAIJsonSchemaMock.mockReturnValue({
+      json_schema: {
+        schema: circularSchema,
+      },
+    });
+
+    createCompletionMock.mockResolvedValue({
+      choices: [
+        {
+          message: {
+            content: '{"ok":"yes"}',
+          },
+        },
+      ],
+    });
+
+    debugOptions.enabled = true;
+    debugOptions.structuredSchema = true;
+    const logSpy = jest.spyOn(console, "log").mockImplementation(() => {});
+
+    try {
+      const client = new OpenAIClient({ model: "gpt-test" });
+      const result = await client.invokeStructured(
+        {
+          schema: z.object({
+            ok: z.string(),
+          }),
+        },
+        [{ role: "user", content: "hello" }]
+      );
+
+      expect(result.parsed).toEqual({ ok: "yes" });
+      expect(logSpy).toHaveBeenCalledWith(
+        "[LLM][OpenAI] Structured output schema:",
+        expect.stringContaining('"self":"[Circular]"')
+      );
+    } finally {
+      logSpy.mockRestore();
+    }
+  });
+
+  it("continues structured invocation when debug option getter traps", async () => {
+    createCompletionMock.mockResolvedValue({
+      choices: [
+        {
+          message: {
+            content: '{"ok":"yes"}',
+          },
+        },
+      ],
+    });
+    getDebugOptions.mockImplementationOnce(() => {
+      throw new Error("debug options trap");
+    });
+
+    const client = new OpenAIClient({ model: "gpt-test" });
+    const result = await client.invokeStructured(
+      {
+        schema: z.object({
+          ok: z.string(),
+        }),
+      },
+      [{ role: "user", content: "hello" }]
+    );
+
+    expect(result.parsed).toEqual({ ok: "yes" });
+  });
+
+  it("throws readable error when completion choices are unreadable", async () => {
+    const response = new Proxy(
+      {},
+      {
+        get: (_target, prop) => {
+          if (prop === "choices") {
+            throw new Error("choices getter trap");
+          }
+          return undefined;
+        },
+      }
+    );
+    createCompletionMock.mockResolvedValue(response);
+
+    const client = new OpenAIClient({ model: "gpt-test" });
+    await expect(
+      client.invoke([{ role: "user", content: "hello" }])
+    ).rejects.toThrow(
+      "[LLM][OpenAI] Invalid completion payload: failed to read choices (choices getter trap)"
+    );
+  });
+
+  it("throws readable error when completion message fields are unreadable", async () => {
+    const choice = new Proxy(
+      {},
+      {
+        get: (_target, prop) => {
+          if (prop === "message") {
+            throw new Error("message getter trap");
+          }
+          return undefined;
+        },
+      }
+    );
+    createCompletionMock.mockResolvedValue({
+      choices: [choice],
+    });
+
+    const client = new OpenAIClient({ model: "gpt-test" });
+    await expect(
+      client.invoke([{ role: "user", content: "hello" }])
+    ).rejects.toThrow(
+      "[LLM][OpenAI] Invalid completion payload: failed to read choice.message (message getter trap)"
+    );
+  });
+
+  it("sanitizes and truncates oversized completion diagnostics", async () => {
+    const response = new Proxy(
+      {},
+      {
+        get: (_target, prop) => {
+          if (prop === "choices") {
+            throw new Error(`choices\u0000\n${"x".repeat(2_000)}`);
+          }
+          return undefined;
+        },
+      }
+    );
+    createCompletionMock.mockResolvedValue(response);
+
+    const client = new OpenAIClient({ model: "gpt-test" });
+    await client
+      .invoke([{ role: "user", content: "hello" }])
+      .then(() => {
+        throw new Error("expected invoke to reject");
+      })
+      .catch((error) => {
+        const message = String(error instanceof Error ? error.message : error);
+        expect(message).toContain("[truncated");
+        expect(message).not.toContain("\u0000");
+        expect(message).not.toContain("\n");
+        expect(message.length).toBeLessThan(700);
+      });
+  });
+});
diff --git a/src/llm/providers/openai.ts b/src/llm/providers/openai.ts
index 4b1a4d17..6b014a9f 100644
--- a/src/llm/providers/openai.ts
+++ b/src/llm/providers/openai.ts
@@ -3,27 +3,145 @@ import { z } from "zod";
 import {
   HyperAgentLLM,
   HyperAgentMessage,
+  HyperAgentContentPart,
   HyperAgentStructuredResult,
   HyperAgentCapabilities,
   StructuredOutputRequest,
-  HyperAgentContentPart,
 } from "../types";
 import { convertToOpenAIMessages } from "../utils/message-converter";
 import { convertToOpenAIJsonSchema } from "../utils/schema-converter";
+import { normalizeOpenAICompatibleContent } from "../utils/openai-content";
+import { normalizeOpenAIToolCalls } from "../utils/openai-tool-calls";
+import { sanitizeProviderOptions } from "../utils/provider-options";
+import { parseStructuredResponse } from "../utils/structured-response";
 import { getDebugOptions } from "@/debug/options";
+import { formatUnknownError } from "@/utils";
 
 const ENV_STRUCTURED_SCHEMA_DEBUG =
   process.env.HYPERAGENT_DEBUG_STRUCTURED_SCHEMA === "1" ||
   process.env.HYPERAGENT_DEBUG_STRUCTURED_SCHEMA === "true";
 
+const RESERVED_OPENAI_PROVIDER_OPTION_KEYS = new Set([
+  "model",
+  "messages",
+  "temperature",
+  "max_tokens",
+  "maxTokens",
+  "response_format",
+]);
+const MAX_PROVIDER_RESPONSE_DIAGNOSTIC_CHARS = 300;
+
+function isRecord(value: unknown): value is Record<string, unknown> {
+  return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+
+function formatProviderResponseDiagnostic(value: unknown): string {
+  const normalized = Array.from(formatUnknownError(value), (char) => {
+    const code = char.charCodeAt(0);
+    return (code >= 0 && code < 32) || code === 127 ? " " : char;
+  })
+    .join("")
+    .replace(/\s+/g, " ")
+    .trim();
+  const fallback = normalized.length > 0 ? normalized : "unknown error";
+  if (fallback.length <= MAX_PROVIDER_RESPONSE_DIAGNOSTIC_CHARS) {
+    return fallback;
+  }
+  return `${fallback.slice(
+    0,
+    MAX_PROVIDER_RESPONSE_DIAGNOSTIC_CHARS
+  )}... [truncated ${fallback.length - MAX_PROVIDER_RESPONSE_DIAGNOSTIC_CHARS} chars]`;
+}
+
+function safeReadRecordField(
+  source: Record<string, unknown>,
+  key: string,
+  fieldLabel: string,
+  providerLabel: string
+): unknown {
+  try {
+    return source[key];
+  } catch (error) {
+    throw new Error(
+      `[LLM][${providerLabel}] Invalid completion payload: failed to read ${fieldLabel} (${formatProviderResponseDiagnostic(
+        error
+      )})`
+    );
+  }
+}
+
+function extractMessageFromCompletionResponse(
+  response: unknown,
+  providerLabel: string
+): Record<string, unknown> {
+  if (!isRecord(response)) {
+    throw new Error(`[LLM][${providerLabel}] Invalid completion payload: response must be an object`);
+  }
+  const choices = safeReadRecordField(response, "choices", "choices", providerLabel);
+  if (!Array.isArray(choices) || choices.length === 0) {
+    throw new Error(`No response from ${providerLabel}`);
+  }
+  const firstChoice = choices[0];
+  if (!isRecord(firstChoice)) {
+    throw new Error(`[LLM][${providerLabel}] Invalid completion payload: first choice is not an object`);
+  }
+  const message = safeReadRecordField(
+    firstChoice,
+    "message",
+    "choice.message",
+    providerLabel
+  );
+  if (!isRecord(message)) {
+    throw new Error(`[LLM][${providerLabel}] Invalid completion payload: choice.message is not an object`);
+  }
+  return message;
+}
+
+function safeReadUsageTokens(
+  response: unknown,
+  field: "prompt_tokens" | "completion_tokens"
+): number | undefined {
+  if (!isRecord(response)) {
+    return undefined;
+  }
+  let usage: unknown;
+  try {
+    usage = response.usage;
+  } catch {
+    return undefined;
+  }
+  if (!isRecord(usage)) {
+    return undefined;
+  }
+  try {
+    const value = usage[field];
+    return typeof value === "number" ? value : undefined;
+  } catch {
+    return undefined;
+  }
+}
+
 function shouldDebugStructuredSchema(): boolean {
-  const opts = getDebugOptions();
+  let opts: ReturnType<typeof getDebugOptions>;
+  try {
+    opts = getDebugOptions();
+  } catch {
+    return ENV_STRUCTURED_SCHEMA_DEBUG;
+  }
   if (opts.enabled && typeof opts.structuredSchema === "boolean") {
     return opts.structuredSchema;
   }
   return ENV_STRUCTURED_SCHEMA_DEBUG;
 }
 
+function safeDebugStringify(value: unknown): string {
+  try {
+    return JSON.stringify(value, null, 2);
+  } catch {
+    return formatUnknownError(value);
+  }
+}
+
 export interface OpenAIClientConfig {
   apiKey?: string;
   model: string;
@@ -32,42 +150,6 @@ export interface OpenAIClientConfig {
   baseURL?: string;
 }
 
-/**
- * Convert OpenAI's content format back to HyperAgentContentPart format
- */
-function convertFromOpenAIContent(
-  content: any
-): string | HyperAgentContentPart[] {
-  if (typeof content === "string") {
-    return content;
-  }
-
-  if (Array.isArray(content)) {
-    return content.map((part: any) => {
-      if (part.type === "text") {
-        return { type: "text", text: part.text };
-      } else if (part.type === "image_url") {
-        return {
-          type: "image",
-          url: part.image_url.url,
-          mimeType: "image/png", // Default, could be extracted from URL if needed
-        };
-      } else if (part.type === "tool_call") {
-        return {
-          type: "tool_call",
-          toolName: part.function.name,
-          arguments: JSON.parse(part.function.arguments),
-        };
-      }
-      // Fallback for unknown types
-      return { type: "text", text: JSON.stringify(part) };
-    });
-  }
-
-  // Fallback for unexpected content types
-  return String(content);
-}
-
 export class OpenAIClient implements HyperAgentLLM {
   private client: OpenAI;
   private model: string;
@@ -98,6 +180,10 @@ export class OpenAIClient implements HyperAgentLLM {
     usage?: { inputTokens?: number; outputTokens?: number };
   }> {
     const openAIMessages = convertToOpenAIMessages(messages);
+    const providerOptions = sanitizeProviderOptions(
+      options?.providerOptions,
+      RESERVED_OPENAI_PROVIDER_OPTION_KEYS
+    );
 
     // GPT-5 only supports temperature=1 (default), so omit temperature for this model
     const temperature = options?.temperature ?? this.temperature;
@@ -106,43 +192,38 @@ export class OpenAIClient implements HyperAgentLLM {
 
     const response = await this.client.chat.completions.create({
       model: this.model,
-      messages: openAIMessages as any,
+      messages:
+        openAIMessages as unknown as Parameters<
+          typeof this.client.chat.completions.create
+        >[0]["messages"],
       ...(shouldIncludeTemperature ? { temperature } : {}),
       max_tokens: options?.maxTokens ?? this.maxTokens,
-      ...options?.providerOptions,
+      ...providerOptions,
     });
 
-    const choice = response.choices[0];
-    if (!choice) {
-      throw new Error("No response from OpenAI");
-    }
-
-    const message = choice.message;
-    const toolCalls = message.tool_calls?.map((tc) => {
-      // Handle both function and custom tool calls in OpenAI v6
-      if (tc.type === "function") {
-        return {
-          id: tc.id,
-          name: tc.function.name,
-          arguments: JSON.parse(tc.function.arguments),
-        };
-      } else if (tc.type === "custom") {
-        return {
-          id: tc.id,
-          name: tc.custom.name,
-          arguments: JSON.parse(tc.custom.input),
-        };
-      }
-      throw new Error(`Unknown tool call type: ${(tc as any).type}`);
-    });
+    const message = extractMessageFromCompletionResponse(response, "OpenAI");
+    const content = safeReadRecordField(
+      message,
+      "content",
+      "choice.message.content",
+      "OpenAI"
+    );
+    const toolCalls = normalizeOpenAIToolCalls(
+      safeReadRecordField(
+        message,
+        "tool_calls",
+        "choice.message.tool_calls",
+        "OpenAI"
+      )
+    );
 
     return {
       role: "assistant",
-      content: convertFromOpenAIContent(message.content),
+      content: normalizeOpenAICompatibleContent(content),
       toolCalls,
       usage: {
-        inputTokens: response.usage?.prompt_tokens,
-        outputTokens: response.usage?.completion_tokens,
+        inputTokens: safeReadUsageTokens(response, "prompt_tokens"),
+        outputTokens: safeReadUsageTokens(response, "completion_tokens"),
       },
     };
   }
@@ -152,6 +233,10 @@ export class OpenAIClient implements HyperAgentLLM {
     messages: HyperAgentMessage[]
   ): Promise<HyperAgentStructuredResult<TSchema>> {
     const openAIMessages = convertToOpenAIMessages(messages);
+    const providerOptions = sanitizeProviderOptions(
+      request.options?.providerOptions,
+      RESERVED_OPENAI_PROVIDER_OPTION_KEYS
+    );
     const responseFormat = convertToOpenAIJsonSchema(request.schema);
     if (shouldDebugStructuredSchema()) {
       const schemaPayload =
@@ -159,7 +244,7 @@ export class OpenAIClient implements HyperAgentLLM {
           ?.schema ?? responseFormat;
       console.log(
         "[LLM][OpenAI] Structured output schema:",
-        JSON.stringify(schemaPayload, null, 2)
+        safeDebugStringify(schemaPayload)
       );
     }
 
@@ -170,39 +255,27 @@ export class OpenAIClient implements HyperAgentLLM {
 
     const response = await this.client.chat.completions.create({
       model: this.model,
-      messages: openAIMessages as any,
+      messages:
+        openAIMessages as unknown as Parameters<
+          typeof this.client.chat.completions.create
+        >[0]["messages"],
       ...(shouldIncludeTemperature ? { temperature } : {}),
       max_tokens: request.options?.maxTokens ?? this.maxTokens,
-      response_format: responseFormat as any,
-      ...request.options?.providerOptions,
+      response_format:
+        responseFormat as unknown as Parameters<
+          typeof this.client.chat.completions.create
+        >[0]["response_format"],
+      ...providerOptions,
     });
 
-    const choice = response.choices[0];
-    if (!choice) {
-      throw new Error("No response from OpenAI");
-    }
-
-    const content = choice.message.content;
-    if (!content || typeof content !== "string") {
-      return {
-        rawText: "",
-        parsed: null,
-      };
-    }
-
-    try {
-      const parsed = JSON.parse(content);
-      const validated = request.schema.parse(parsed);
-      return {
-        rawText: content,
-        parsed: validated,
-      };
-    } catch {
-      return {
-        rawText: content,
-        parsed: null,
-      };
-    }
+    const message = extractMessageFromCompletionResponse(response, "OpenAI");
+    const content = safeReadRecordField(
+      message,
+      "content",
+      "choice.message.content",
+      "OpenAI"
+    );
+    return parseStructuredResponse(content, request.schema);
   }
 
   getProviderId(): string {
diff --git a/src/llm/utils/message-converter.test.ts b/src/llm/utils/message-converter.test.ts
new file mode 100644
index 00000000..2feb4e95
--- /dev/null
+++ b/src/llm/utils/message-converter.test.ts
@@ -0,0 +1,693 @@
+import {
+  convertToAnthropicMessages,
+  convertToGeminiMessages,
+  convertToOpenAIMessages,
+  extractImageDataFromUrl,
+} from "@/llm/utils/message-converter";
+import { HyperAgentMessage } from "@/llm/types";
+
+describe("convertToOpenAIMessages", () => {
+  it("serializes circular tool-call arguments without throwing", () => {
+    const circular: Record<string, unknown> = { name: "root" };
+    circular.self = circular;
+
+    const messages: HyperAgentMessage[] = [
+      {
+        role: "assistant",
+        content: "done",
+        toolCalls: [
+          {
+            id: "call-1",
+            name: "tool-1",
+            arguments: circular,
+          },
+        ],
+      },
+    ];
+
+    const result = convertToOpenAIMessages(messages);
+    const serialized = (
+      result[0]?.tool_calls as Array<{
+        function: { arguments: string };
+      }>
+    )[0]?.function.arguments;
+
+    expect(serialized).toContain('"self":"[Circular]"');
+    expect(() => JSON.parse(serialized)).not.toThrow();
+  });
+
+  it("serializes bigint tool arguments in content tool_call parts", () => {
+    const messages: HyperAgentMessage[] = [
+      {
+        role: "assistant",
+        content: [
+          {
+            type: "tool_call",
+            toolName: "tool-1",
+            arguments: {
+              count: BigInt(42),
+            },
+          },
+        ],
+      },
+    ];
+
+    const result = convertToOpenAIMessages(messages);
+    const serialized = (
+      result[0]?.content as Array<{ function: { arguments: string } }>
+    )[0]?.function.arguments;
+
+    expect(serialized).toContain('"count":"42n"');
+    expect(() => JSON.parse(serialized)).not.toThrow();
+  });
+
+  it("falls back to empty object string for undefined arguments", () => {
+    const messages: HyperAgentMessage[] = [
+      {
+        role: "assistant",
+        content: "done",
+        toolCalls: [
+          {
+            id: "call-1",
+            name: "tool-1",
+            arguments: undefined,
+          },
+        ],
+      },
+    ];
+
+    const result = convertToOpenAIMessages(messages);
+    const serialized = (
+      result[0]?.tool_calls as Array<{
+        function: { arguments: string };
+      }>
+    )[0]?.function.arguments;
+
+    expect(serialized).toBe("{}");
+  });
+
+  it("falls back to empty object string for oversized assistant tool-call arguments", () => {
+    const messages: HyperAgentMessage[] = [
+      {
+        role: "assistant",
+        content: "done",
+        toolCalls: [
+          {
+            id: "call-1",
+            name: "tool-1",
+            arguments: {
+              payload: "x".repeat(120_000),
+            },
+          },
+        ],
+      },
+    ];
+
+    const result = convertToOpenAIMessages(messages);
+    const serialized = (
+      result[0]?.tool_calls as Array<{
+        function: { arguments: string };
+      }>
+    )[0]?.function.arguments;
+
+    expect(serialized).toBe("{}");
+  });
+
+  it("falls back to empty object string for oversized content tool_call arguments", () => {
+    const messages: HyperAgentMessage[] = [
+      {
+        role: "assistant",
+        content: [
+          {
+            type: "tool_call",
+            toolName: "tool-1",
+            arguments: {
+              payload: "x".repeat(120_000),
+            },
+          },
+        ],
+      },
+    ];
+
+    const result = convertToOpenAIMessages(messages);
+    const serialized = (
+      result[0]?.content as Array<{ function: { arguments: string } }>
+    )[0]?.function.arguments;
+
+    expect(serialized).toBe("{}");
+  });
+
+  it("normalizes unknown content parts to text payloads", () => {
+    const circularPart: Record<string, unknown> = { type: "mystery" };
+    circularPart.self = circularPart;
+
+    const result = convertToOpenAIMessages([
+      {
+        role: "assistant",
+        content: [circularPart as unknown as never],
+      },
+    ]);
+
+    expect(result[0]?.content).toEqual([
+      {
+        type: "text",
+        text: '{"type":"mystery","self":"[Circular]"}',
+      },
+    ]);
+  });
+
+  it("truncates oversized unknown content diagnostics", () => {
+    const huge = "x".repeat(3_500);
+    const result = convertToOpenAIMessages([
+      {
+        role: "assistant",
+        content: [{ type: "mystery", payload: huge } as unknown as never],
+      },
+    ]);
+
+    const text = (
+      result[0]?.content as Array<{
+        text: string;
+      }>
+    )[0]?.text;
+    expect(text).toContain("[truncated");
+  });
+
+  it("sanitizes control characters in unknown content diagnostics", () => {
+    const noisyError = new Error(`boom\u0000\n${"x".repeat(3_500)}`);
+    const result = convertToOpenAIMessages([
+      {
+        role: "assistant",
+        content: [noisyError as unknown as never],
+      },
+    ]);
+
+    const text = (
+      result[0]?.content as Array<{
+        text: string;
+      }>
+    )[0]?.text;
+    expect(text).toContain("[truncated");
+    expect(text).not.toContain("\u0000");
+    expect(text).not.toContain("\n");
+  });
+
+  it("normalizes tool-role messages with tool_call_id and text content", () => {
+    const result = convertToOpenAIMessages([
+      {
+        role: "tool",
+        toolName: "lookup-user",
+        toolCallId: "call-1",
+        content: [{ type: "text", text: "tool result payload" }],
+      },
+    ]);
+
+    expect(result[0]).toEqual({
+      role: "tool",
+      tool_call_id: "call-1",
+      content: "tool result payload",
+    });
+  });
+
+  it("normalizes tool-call identifiers and names defensively", () => {
+    const result = convertToOpenAIMessages([
+      {
+        role: "tool",
+        toolName: "   ",
+        toolCallId: "   ",
+        content: "tool result payload",
+      },
+      {
+        role: "assistant",
+        content: "done",
+        toolCalls: [
+          {
+            id: "call-1",
+            name: "   bad\nname   ",
+            arguments: {},
+          },
+        ],
+      },
+    ]);
+
+    expect(result[0]).toEqual({
+      role: "tool",
+      tool_call_id: "unknown-tool",
+      content: "tool result payload",
+    });
+    expect((result[1] as { tool_calls?: Array<{ function: { name: string } }> }).tool_calls?.[0]?.function.name).toBe(
+      "bad_name"
+    );
+  });
+
+  it("falls back assistant tool_call ids to normalized tool names", () => {
+    const result = convertToOpenAIMessages([
+      {
+        role: "assistant",
+        content: "done",
+        toolCalls: [
+          {
+            id: "   ",
+            name: "  weird name !@# ",
+            arguments: {},
+          },
+        ],
+      },
+    ]);
+
+    const toolCall = (result[0] as { tool_calls?: Array<{ id: string; function: { name: string } }> }).tool_calls?.[0];
+    expect(toolCall?.id).toBe("weird_name");
+    expect(toolCall?.function.name).toBe("weird_name");
+  });
+
+  it("sanitizes explicit tool_call ids to API-safe format", () => {
+    const result = convertToOpenAIMessages([
+      {
+        role: "assistant",
+        content: "done",
+        toolCalls: [
+          {
+            id: "  weird id !@# with\nspaces ",
+            name: "lookup",
+            arguments: {},
+          },
+        ],
+      },
+      {
+        role: "tool",
+        toolName: "lookup",
+        toolCallId: "  weird id !@# with\nspaces ",
+        content: "result",
+      },
+    ]);
+
+    const assistantToolCall = (result[0] as {
+      tool_calls?: Array<{ id: string }>;
+    }).tool_calls?.[0];
+    const toolMessage = result[1] as { tool_call_id?: string };
+    expect(assistantToolCall?.id).toBe("weird_id_with_spaces");
+    expect(toolMessage.tool_call_id).toBe("weird_id_with_spaces");
+  });
+
+  it("sanitizes OpenAI tool names to supported charset and length", () => {
+    const longName = "tool " + "x".repeat(80) + " !@#$";
+    const result = convertToOpenAIMessages([
+      {
+        role: "assistant",
+        content: [
+          {
+            type: "tool_call",
+            toolName: longName,
+            arguments: {},
+          },
+        ],
+      },
+    ]);
+
+    const toolPart = (result[0]?.content as Array<{
+      id: string;
+      function: { name: string };
+    }>)[0];
+    expect(toolPart.id.length).toBeLessThanOrEqual(64);
+    expect(toolPart.function.name.length).toBeLessThanOrEqual(64);
+    expect(toolPart.function.name).toMatch(/^[a-zA-Z0-9_-]+$/);
+  });
+});
+
+describe("image payload conversion", () => {
+  it("returns empty payload for malformed data URL in Anthropic messages", () => {
+    const { messages } = convertToAnthropicMessages([
+      {
+        role: "user",
+        content: [
+          {
+            type: "image",
+            url: "data:image/png;base64",
+          },
+        ],
+      },
+    ]);
+
+    expect(messages[0]?.content).toEqual([
+      {
+        type: "image",
+        source: {
+          type: "base64",
+          media_type: "image/png",
+          data: "",
+        },
+      },
+    ]);
+  });
+
+  it("returns empty payload for malformed data URL in Gemini messages", () => {
+    const { messages } = convertToGeminiMessages([
+      {
+        role: "user",
+        content: [
+          {
+            type: "image",
+            url: "data:image/png;base64",
+          },
+        ],
+      },
+    ]);
+
+    expect(messages[0]?.parts).toEqual([
+      {
+        inlineData: {
+          mimeType: "image/png",
+          data: "",
+        },
+      },
+    ]);
+  });
+
+  it("extractImageDataFromUrl tolerates malformed data URLs", () => {
+    expect(extractImageDataFromUrl("data:image/png;base64")).toEqual({
+      mimeType: "image/png",
+      data: "",
+    });
+  });
+});
+
+describe("system message text extraction", () => {
+  it("extracts system text parts for Anthropic conversion", () => {
+    const { system } = convertToAnthropicMessages([
+      {
+        role: "system",
+        content: [
+          { type: "text", text: "rule one" },
+          { type: "image", url: "https://example.com/img.png" },
+          { type: "text", text: "rule two" },
+        ],
+      },
+      {
+        role: "user",
+        content: "hello",
+      },
+    ]);
+
+    expect(system).toBe("rule one\nrule two");
+  });
+
+  it("combines multiple Anthropic system messages in order", () => {
+    const { system } = convertToAnthropicMessages([
+      {
+        role: "system",
+        content: "primary system instruction",
+      },
+      {
+        role: "system",
+        content: [{ type: "text", text: "secondary instruction" }],
+      },
+      {
+        role: "user",
+        content: "hello",
+      },
+    ]);
+
+    expect(system).toBe("primary system instruction\n\nsecondary instruction");
+  });
+
+  it("extracts system text parts for Gemini conversion", () => {
+    const { systemInstruction } = convertToGeminiMessages([
+      {
+        role: "system",
+        content: [
+          { type: "text", text: "rule one" },
+          { type: "tool_call", toolName: "ignored", arguments: {} },
+          { type: "text", text: "rule two" },
+        ],
+      },
+      {
+        role: "user",
+        content: "hello",
+      },
+    ]);
+
+    expect(systemInstruction).toBe("rule one\nrule two");
+  });
+
+  it("combines multiple Gemini system messages in order", () => {
+    const { systemInstruction } = convertToGeminiMessages([
+      {
+        role: "system",
+        content: "primary system instruction",
+      },
+      {
+        role: "system",
+        content: [{ type: "text", text: "secondary instruction" }],
+      },
+      {
+        role: "user",
+        content: "hello",
+      },
+    ]);
+
+    expect(systemInstruction).toBe(
+      "primary system instruction\n\nsecondary instruction"
+    );
+  });
+
+  it("normalizes unknown Gemini content parts into text blocks", () => {
+    const circularPart: Record<string, unknown> = { type: "mystery" };
+    circularPart.self = circularPart;
+
+    const { messages } = convertToGeminiMessages([
+      {
+        role: "user",
+        content: [circularPart as unknown as never],
+      },
+    ]);
+
+    expect(messages[0]?.parts).toEqual([
+      {
+        text: '{"type":"mystery","self":"[Circular]"}',
+      },
+    ]);
+  });
+
+  it("truncates oversized unknown Gemini content diagnostics", () => {
+    const huge = "x".repeat(3_500);
+    const { messages } = convertToGeminiMessages([
+      {
+        role: "user",
+        content: [{ type: "mystery", payload: huge } as unknown as never],
+      },
+    ]);
+
+    const text = (
+      messages[0]?.parts as Array<{
+        text: string;
+      }>
+    )[0]?.text;
+    expect(text).toContain("[truncated");
+  });
+
+  it("normalizes unknown Anthropic content parts into text blocks", () => {
+    const { messages } = convertToAnthropicMessages([
+      {
+        role: "assistant",
+        content: [
+          {
+            type: "tool_call",
+            toolName: "lookup",
+            arguments: { id: "123" },
+          },
+        ],
+      },
+    ]);
+
+    expect(messages[0]?.content).toEqual([
+      {
+        type: "text",
+        text: '{"type":"tool_call","toolName":"lookup","arguments":{"id":"123"}}',
+      },
+    ]);
+  });
+
+  it("truncates oversized unknown Anthropic content diagnostics", () => {
+    const huge = "x".repeat(3_500);
+    const { messages } = convertToAnthropicMessages([
+      {
+        role: "assistant",
+        content: [{ type: "mystery", payload: huge } as unknown as never],
+      },
+    ]);
+
+    const text = (
+      messages[0]?.content as Array<{
+        type: string;
+        text: string;
+      }>
+    )[0]?.text;
+    expect(text).toContain("[truncated");
+  });
+
+  it("prefixes Anthropic tool-role messages with tool label", () => {
+    const { messages } = convertToAnthropicMessages([
+      {
+        role: "tool",
+        toolName: "lookup-user",
+        content: "tool response",
+      },
+    ]);
+
+    expect(messages[0]).toEqual({
+      role: "user",
+      content: "[Tool lookup-user]\ntool response",
+    });
+  });
+
+  it("sanitizes Anthropic tool labels for unsafe characters", () => {
+    const { messages } = convertToAnthropicMessages([
+      {
+        role: "tool",
+        toolName: "  weird]\nname  ",
+        content: "tool response",
+      },
+    ]);
+
+    expect(messages[0]).toEqual({
+      role: "user",
+      content: "[Tool weird name]\ntool response",
+    });
+  });
+
+  it("prefixes Gemini tool-role messages with tool label", () => {
+    const { messages } = convertToGeminiMessages([
+      {
+        role: "tool",
+        toolName: "lookup-user",
+        content: "tool response",
+      },
+    ]);
+
+    expect(messages[0]).toEqual({
+      role: "user",
+      parts: [{ text: "[Tool lookup-user]\ntool response" }],
+    });
+  });
+
+  it("sanitizes Gemini tool labels for unsafe characters", () => {
+    const { messages } = convertToGeminiMessages([
+      {
+        role: "tool",
+        toolName: "  weird]\nname  ",
+        content: "tool response",
+      },
+    ]);
+
+    expect(messages[0]).toEqual({
+      role: "user",
+      parts: [{ text: "[Tool weird name]\ntool response" }],
+    });
+  });
+});
+
+describe("message converter trap resilience", () => {
+  it("falls back to user text message when OpenAI conversion hits getter traps", () => {
+    const trappedMessage = new Proxy(
+      {},
+      {
+        get: (_target, prop) => {
+          if (prop === "role" || prop === "content") {
+            throw new Error("message getter trap");
+          }
+          return undefined;
+        },
+      }
+    );
+
+    const result = convertToOpenAIMessages([
+      trappedMessage as unknown as HyperAgentMessage,
+    ]);
+
+    expect(result).toEqual([
+      {
+        role: "user",
+        content: "{}",
+      },
+    ]);
+  });
+
+  it("falls back to user text block when Anthropic conversion hits getter traps", () => {
+    const trappedMessage = new Proxy(
+      {},
+      {
+        get: (_target, prop) => {
+          if (prop === "content") {
+            throw new Error("content getter trap");
+          }
+          if (prop === "role") {
+            return "user";
+          }
+          return undefined;
+        },
+      }
+    );
+
+    const result = convertToAnthropicMessages([
+      trappedMessage as unknown as HyperAgentMessage,
+    ]);
+
+    expect(result.messages).toEqual([
+      {
+        role: "user",
+        content: "{}",
+      },
+    ]);
+  });
+
+  it("falls back to user parts when Gemini conversion hits getter traps", () => {
+    const trappedMessage = new Proxy(
+      {},
+      {
+        get: (_target, prop) => {
+          if (prop === "content") {
+            throw new Error("content getter trap");
+          }
+          if (prop === "role") {
+            return "user";
+          }
+          return undefined;
+        },
+      }
+    );
+
+    const result = convertToGeminiMessages([
+      trappedMessage as unknown as HyperAgentMessage,
+    ]);
+
+    expect(result.messages).toEqual([
+      {
+        role: "user",
+        parts: [{ text: "{}" }],
+      },
+    ]);
+  });
+
+  it("returns empty payloads when message-list traversal traps throw", () => {
+    const trappedMessages = new Proxy([{}], {
+      get: (target, prop, receiver) => {
+        if (prop === Symbol.iterator) {
+          throw new Error("messages iterator trap");
+        }
+        return Reflect.get(target, prop, receiver);
+      },
+    });
+
+    expect(
+      convertToOpenAIMessages(trappedMessages as unknown as HyperAgentMessage[])
+    ).toEqual([]);
+    expect(
+      convertToAnthropicMessages(
+        trappedMessages as unknown as HyperAgentMessage[]
+      )
+    ).toEqual({ messages: [], system: undefined });
+    expect(
+      convertToGeminiMessages(trappedMessages as unknown as HyperAgentMessage[])
+    ).toEqual({ messages: [], systemInstruction: undefined });
+  });
+});
diff --git a/src/llm/utils/message-converter.ts b/src/llm/utils/message-converter.ts
index 9527579b..fe9bbb9e 100644
--- a/src/llm/utils/message-converter.ts
+++ b/src/llm/utils/message-converter.ts
@@ -1,4 +1,5 @@
 import { HyperAgentMessage, HyperAgentContentPart } from "../types";
+import { formatUnknownError } from "@/utils";
 import type {
   MessageParam,
   ContentBlockParam,
@@ -10,100 +11,305 @@ import type {
  * Utility functions for converting between different message formats
  */
 
-export function convertToOpenAIMessages(messages: HyperAgentMessage[]) {
-  return messages.map((msg) => {
-    const openAIMessage: Record<string, unknown> = {
-      role: msg.role,
-    };
-
-    if (typeof msg.content === "string") {
-      openAIMessage.content = msg.content;
-    } else {
-      openAIMessage.content = msg.content.map((part: HyperAgentContentPart) => {
-        if (part.type === "text") {
-          return { type: "text", text: part.text };
-        } else if (part.type === "image") {
-          return {
-            type: "image_url",
-            image_url: { url: part.url },
-          };
-        } else if (part.type === "tool_call") {
-          return {
-            type: "tool_call",
-            id: part.toolName,
-            function: {
-              name: part.toolName,
-              arguments: JSON.stringify(part.arguments),
-            },
-          };
+const MAX_CONVERTER_DIAGNOSTIC_CHARS = 2_000;
+const MAX_TOOL_ARGUMENT_JSON_CHARS = 100_000;
+
+function stringifyToolArguments(value: unknown): string {
+  if (typeof value === "undefined") {
+    return "{}";
+  }
+
+  const seen = new WeakSet<object>();
+  try {
+    const serialized = JSON.stringify(value, (_key, candidate: unknown) => {
+      if (typeof candidate === "bigint") {
+        return `${candidate.toString()}n`;
+      }
+
+      if (typeof candidate === "object" && candidate !== null) {
+        if (seen.has(candidate)) {
+          return "[Circular]";
         }
-        return part;
-      });
+        seen.add(candidate);
+      }
+
+      return candidate;
+    });
+
+    if (typeof serialized !== "string") {
+      return "{}";
     }
 
-    if (msg.role === "assistant" && msg.toolCalls) {
-      openAIMessage.tool_calls = msg.toolCalls.map(
-        (tc: { id?: string; name: string; arguments: unknown }) => ({
-          id: tc.id || "",
-          type: "function",
-          function: {
-            name: tc.name,
-            arguments: JSON.stringify(tc.arguments),
-          },
-        })
-      );
+    if (serialized.length > MAX_TOOL_ARGUMENT_JSON_CHARS) {
+      return "{}";
     }
 
-    return openAIMessage;
+    return serialized;
+  } catch {
+    return "{}";
+  }
+}
+
+function truncateConverterDiagnostic(value: string): string {
+  if (value.length <= MAX_CONVERTER_DIAGNOSTIC_CHARS) {
+    return value;
+  }
+  const omitted = value.length - MAX_CONVERTER_DIAGNOSTIC_CHARS;
+  return `${value.slice(
+    0,
+    MAX_CONVERTER_DIAGNOSTIC_CHARS
+  )}... [truncated ${omitted} chars]`;
+}
+
+function sanitizeConverterDiagnostic(value: string): string {
+  if (value.length === 0) {
+    return value;
+  }
+  return Array.from(value, (char) => {
+    const code = char.charCodeAt(0);
+    return (code >= 0 && code < 32) || code === 127 ? " " : char;
+  })
+    .join("")
+    .replace(/\s+/g, " ")
+    .trim();
+}
+
+function formatConverterFallback(value: unknown): string {
+  const normalized = sanitizeConverterDiagnostic(formatUnknownError(value));
+  const fallback = normalized.length > 0 ? normalized : "{}";
+  return truncateConverterDiagnostic(fallback);
+}
+
+function extractBase64Payload(url: string): string {
+  if (!url.startsWith("data:")) {
+    return url;
+  }
+
+  const commaIndex = url.indexOf(",");
+  if (commaIndex < 0) {
+    return "";
+  }
+  return url.slice(commaIndex + 1);
+}
+
+function extractTextContent(
+  content: string | HyperAgentContentPart[]
+): string {
+  if (typeof content === "string") {
+    return content;
+  }
+
+  return content
+    .filter((part): part is Extract<HyperAgentContentPart, { type: "text" }> =>
+      part.type === "text"
+    )
+    .map((part) => part.text)
+    .join("\n")
+    .trim();
+}
+
+function normalizeToolName(toolName: string): string {
+  const normalized = toolName.trim().replace(/\s+/g, " ");
+  return normalized.length > 0 ? normalized : "unknown-tool";
+}
+
+function normalizeOpenAIToolName(toolName: string): string {
+  const normalized = normalizeToolName(toolName)
+    .replace(/[^a-zA-Z0-9_-]/g, "_")
+    .replace(/_+/g, "_")
+    .replace(/^_+|_+$/g, "");
+
+  if (normalized.length === 0) {
+    return "unknown_tool";
+  }
+
+  return normalized.slice(0, 64);
+}
+
+function normalizeToolNameForLabel(toolName: string): string {
+  const sanitized = normalizeToolName(toolName).replace(/[\[\]\r\n]/g, " ");
+  const normalized = sanitized.trim().replace(/\s+/g, " ");
+  return normalized.length > 0 ? normalized : "unknown-tool";
+}
+
+function normalizeToolCallId(
+  toolCallId: string | undefined,
+  toolName: string
+): string {
+  const normalizedId = toolCallId
+    ?.trim()
+    .replace(/\s+/g, "_")
+    .replace(/[^a-zA-Z0-9_-]/g, "_")
+    .replace(/_+/g, "_")
+    .replace(/^_+|_+$/g, "")
+    .slice(0, 64);
+  if (normalizedId && normalizedId.length > 0) {
+    return normalizedId;
+  }
+  return normalizeOpenAIToolName(toolName);
+}
+
+function buildToolMessageLabel(toolName: string): string {
+  return `[Tool ${normalizeToolNameForLabel(toolName)}]`;
+}
+
+function safeToMessageArray(messages: HyperAgentMessage[]): HyperAgentMessage[] {
+  try {
+    return Array.from(messages);
+  } catch {
+    return [];
+  }
+}
+
+export function convertToOpenAIMessages(messages: HyperAgentMessage[]) {
+  return safeToMessageArray(messages).map((msg) => {
+    try {
+      const openAIMessage: Record<string, unknown> = {
+        role: msg.role,
+      };
+
+      if (msg.role === "tool") {
+        const textContent =
+          typeof msg.content === "string"
+            ? msg.content
+            : extractTextContent(msg.content);
+        openAIMessage.content =
+          textContent.length > 0
+            ? textContent
+            : formatConverterFallback(msg.content);
+        openAIMessage.tool_call_id = normalizeToolCallId(
+          msg.toolCallId,
+          msg.toolName
+        );
+        return openAIMessage;
+      }
+
+      if (typeof msg.content === "string") {
+        openAIMessage.content = msg.content;
+      } else {
+        const parts = Array.isArray(msg.content) ? Array.from(msg.content) : [];
+        openAIMessage.content = parts.map((part: HyperAgentContentPart) => {
+          if (part.type === "text") {
+            return { type: "text", text: part.text };
+          } else if (part.type === "image") {
+            return {
+              type: "image_url",
+              image_url: { url: part.url },
+            };
+          } else if (part.type === "tool_call") {
+            const normalizedToolName = normalizeOpenAIToolName(part.toolName);
+            return {
+              type: "tool_call",
+              id: normalizedToolName,
+              function: {
+                name: normalizedToolName,
+                arguments: stringifyToolArguments(part.arguments),
+              },
+            };
+          }
+          return { type: "text", text: formatConverterFallback(part) };
+        });
+      }
+
+      if (msg.role === "assistant" && msg.toolCalls) {
+        const toolCalls = Array.isArray(msg.toolCalls) ? Array.from(msg.toolCalls) : [];
+        openAIMessage.tool_calls = toolCalls.map(
+          (tc: { id?: string; name: string; arguments: unknown }) => ({
+            id: normalizeToolCallId(tc.id, tc.name),
+            type: "function",
+            function: {
+              name: normalizeOpenAIToolName(tc.name),
+              arguments: stringifyToolArguments(tc.arguments),
+            },
+          })
+        );
+      }
+
+      return openAIMessage;
+    } catch {
+      return {
+        role: "user",
+        content: formatConverterFallback(msg),
+      };
+    }
   });
 }
 
 export function convertToAnthropicMessages(messages: HyperAgentMessage[]) {
   const anthropicMessages: MessageParam[] = [];
-  let systemMessage: string | undefined;
+  const systemMessageParts: string[] = [];
 
-  for (const msg of messages) {
-    if (msg.role === "system") {
-      systemMessage = typeof msg.content === "string" ? msg.content : "";
-      continue;
-    }
+  for (const msg of safeToMessageArray(messages)) {
+    try {
+      if (msg.role === "system") {
+        const systemText = extractTextContent(msg.content);
+        if (systemText.length > 0) {
+          systemMessageParts.push(systemText);
+        }
+        continue;
+      }
 
-    const role = msg.role === "assistant" ? "assistant" : "user";
-
-    let content: string | ContentBlockParam[];
-    if (typeof msg.content === "string") {
-      content = msg.content;
-    } else {
-      const blocks: ContentBlockParam[] = [];
-      for (const part of msg.content) {
-        if (part.type === "text") {
-          const textBlock: TextBlockParam = { type: "text", text: part.text };
-          blocks.push(textBlock);
-        } else if (part.type === "image") {
-          const base64Data = part.url.startsWith("data:")
-            ? part.url.split(",")[1]
-            : part.url;
-          const mediaType = normalizeImageMimeType(part.mimeType);
-          const imageBlock: ImageBlockParam = {
-            type: "image",
-            source: {
-              type: "base64",
-              media_type: mediaType,
-              data: base64Data,
-            },
-          };
-          blocks.push(imageBlock);
+      const role = msg.role === "assistant" ? "assistant" : "user";
+      const isToolMessage = msg.role === "tool";
+
+      let content: string | ContentBlockParam[];
+      if (typeof msg.content === "string") {
+        const baseContent = msg.content;
+        content = isToolMessage
+          ? `${buildToolMessageLabel(msg.toolName)}\n${baseContent}`
+          : baseContent;
+      } else {
+        const blocks: ContentBlockParam[] = [];
+        if (isToolMessage) {
+          blocks.push({
+            type: "text",
+            text: buildToolMessageLabel(msg.toolName),
+          });
+        }
+        const parts = Array.isArray(msg.content) ? Array.from(msg.content) : [];
+        for (const part of parts) {
+          if (part.type === "text") {
+            const textBlock: TextBlockParam = { type: "text", text: part.text };
+            blocks.push(textBlock);
+          } else if (part.type === "image") {
+            const base64Data = extractBase64Payload(part.url);
+            const mediaType = normalizeImageMimeType(part.mimeType);
+            const imageBlock: ImageBlockParam = {
+              type: "image",
+              source: {
+                type: "base64",
+                media_type: mediaType,
+                data: base64Data,
+              },
+            };
+            blocks.push(imageBlock);
+          } else {
+            const textBlock: TextBlockParam = {
+              type: "text",
+              text: formatConverterFallback(part),
+            };
+            blocks.push(textBlock);
+          }
         }
+        content = blocks;
       }
-      content = blocks;
-    }
 
-    anthropicMessages.push({
-      role,
-      content,
-    });
+      anthropicMessages.push({
+        role,
+        content,
+      });
+    } catch {
+      anthropicMessages.push({
+        role: "user",
+        content: formatConverterFallback(msg),
+      });
+    }
   }
 
+  const systemMessage =
+    systemMessageParts.length > 0
+      ? systemMessageParts.join("\n\n")
+      : undefined;
   return { messages: anthropicMessages, system: systemMessage };
 }
 
@@ -129,43 +335,66 @@ function normalizeImageMimeType(
 
 export function convertToGeminiMessages(messages: HyperAgentMessage[]) {
   const geminiMessages: Record<string, unknown>[] = [];
-  let systemInstruction: string | undefined;
+  const systemInstructionParts: string[] = [];
 
-  for (const msg of messages) {
-    if (msg.role === "system") {
-      systemInstruction = typeof msg.content === "string" ? msg.content : "";
-      continue;
-    }
-
-    const geminiMessage: Record<string, unknown> = {
-      role: msg.role === "assistant" ? "model" : "user",
-    };
-
-    if (typeof msg.content === "string") {
-      geminiMessage.parts = [{ text: msg.content }];
-    } else {
-      geminiMessage.parts = msg.content.map((part: HyperAgentContentPart) => {
-        if (part.type === "text") {
-          return { text: part.text };
-        } else if (part.type === "image") {
-          // Extract base64 data from data URL
-          const base64Data = part.url.startsWith("data:")
-            ? part.url.split(",")[1]
-            : part.url;
-          return {
-            inlineData: {
-              mimeType: part.mimeType || "image/png",
-              data: base64Data,
-            },
-          };
+  for (const msg of safeToMessageArray(messages)) {
+    try {
+      if (msg.role === "system") {
+        const systemText = extractTextContent(msg.content);
+        if (systemText.length > 0) {
+          systemInstructionParts.push(systemText);
         }
-        return part;
+        continue;
+      }
+
+      const geminiMessage: Record<string, unknown> = {
+        role: msg.role === "assistant" ? "model" : "user",
+      };
+      const isToolMessage = msg.role === "tool";
+
+      if (typeof msg.content === "string") {
+        const baseText = msg.content;
+        geminiMessage.parts = [
+          {
+            text: isToolMessage
+              ? `${buildToolMessageLabel(msg.toolName)}\n${baseText}`
+              : baseText,
+          },
+        ];
+      } else {
+        const contentParts = Array.isArray(msg.content) ? Array.from(msg.content) : [];
+        const parts = contentParts.map((part: HyperAgentContentPart) => {
+          if (part.type === "text") {
+            return { text: part.text };
+          } else if (part.type === "image") {
+            const base64Data = extractBase64Payload(part.url);
+            return {
+              inlineData: {
+                mimeType: part.mimeType || "image/png",
+                data: base64Data,
+              },
+            };
+          }
+          return { text: formatConverterFallback(part) };
+        });
+        geminiMessage.parts = isToolMessage
+          ? [{ text: buildToolMessageLabel(msg.toolName) }, ...parts]
+          : parts;
+      }
+
+      geminiMessages.push(geminiMessage);
+    } catch {
+      geminiMessages.push({
+        role: "user",
+        parts: [{ text: formatConverterFallback(msg) }],
       });
     }
-
-    geminiMessages.push(geminiMessage);
   }
 
+  const systemInstruction =
+    systemInstructionParts.length > 0
+      ? systemInstructionParts.join("\n\n")
+      : undefined;
   return { messages: geminiMessages, systemInstruction };
 }
 
@@ -174,7 +403,9 @@ export function extractImageDataFromUrl(url: string): {
   data: string;
 } {
   if (url.startsWith("data:")) {
-    const [header, data] = url.split(",");
+    const commaIndex = url.indexOf(",");
+    const header = commaIndex >= 0 ? url.slice(0, commaIndex) : url;
+    const data = commaIndex >= 0 ? url.slice(commaIndex + 1) : "";
     const mimeType = header.match(/data:([^;]+)/)?.[1] || "image/png";
     return { mimeType, data };
   }
diff --git a/src/llm/utils/openai-content.test.ts b/src/llm/utils/openai-content.test.ts
new file mode 100644
index 00000000..a64d1d18
--- /dev/null
+++ b/src/llm/utils/openai-content.test.ts
@@ -0,0 +1,296 @@
+import { normalizeOpenAICompatibleContent } from "@/llm/utils/openai-content";
+
+describe("normalizeOpenAICompatibleContent", () => {
+  it("returns strings unchanged", () => {
+    expect(normalizeOpenAICompatibleContent("hello")).toBe("hello");
+  });
+
+  it("normalizes content-part arrays", () => {
+    expect(
+      normalizeOpenAICompatibleContent([
+        { type: "text", text: "a" },
+        { type: "image_url", image_url: { url: "https://example.com/img.png" } },
+        { type: "tool_call", function: { name: "lookup", arguments: '{"id":1}' } },
+      ])
+    ).toEqual([
+      { type: "text", text: "a" },
+      { type: "image", url: "https://example.com/img.png", mimeType: "image/png" },
+      { type: "tool_call", toolName: "lookup", arguments: { id: 1 } },
+    ]);
+  });
+
+  it("formats non-string image URLs safely for diagnostics", () => {
+    expect(
+      normalizeOpenAICompatibleContent([
+        {
+          type: "image_url",
+          image_url: { url: { href: "bad-shape" } },
+        },
+      ])
+    ).toEqual([
+      {
+        type: "image",
+        url: '{"href":"bad-shape"}',
+        mimeType: "image/png",
+      },
+    ]);
+  });
+
+  it("normalizes and trims string image URLs", () => {
+    expect(
+      normalizeOpenAICompatibleContent([
+        {
+          type: "image_url",
+          image_url: { url: "  https://example.com/path\n  " },
+        },
+      ])
+    ).toEqual([
+      {
+        type: "image",
+        url: "https://example.com/path",
+        mimeType: "image/png",
+      },
+    ]);
+  });
+
+  it("truncates oversized image URL diagnostics", () => {
+    const huge = { url: "x".repeat(10_000) };
+    const result = normalizeOpenAICompatibleContent([
+      {
+        type: "image_url",
+        image_url: { url: huge },
+      },
+    ]) as Array<{ url: string }>;
+
+    expect(result[0]?.url.length).toBeGreaterThan(4_000);
+    expect(result[0]?.url).toContain("[truncated");
+  });
+
+  it("sanitizes unsafe keys in tool-call content arguments", () => {
+    expect(
+      normalizeOpenAICompatibleContent([
+        {
+          type: "tool_call",
+          function: {
+            name: "lookup",
+            arguments:
+              '{"safe":1,"__proto__":{"polluted":true},"nested":{"constructor":"bad","ok":true}}',
+          },
+        },
+      ])
+    ).toEqual([
+      {
+        type: "tool_call",
+        toolName: "lookup",
+        arguments: {
+          safe: 1,
+          nested: {
+            ok: true,
+          },
+        },
+      },
+    ]);
+  });
+
+  it("defaults missing tool-call content arguments to empty object", () => {
+    expect(
+      normalizeOpenAICompatibleContent([
+        {
+          type: "tool_call",
+          function: {
+            name: "lookup",
+          },
+        },
+      ])
+    ).toEqual([
+      {
+        type: "tool_call",
+        toolName: "lookup",
+        arguments: {},
+      },
+    ]);
+  });
+
+  it("normalizes whitespace-only tool names to fallback", () => {
+    expect(
+      normalizeOpenAICompatibleContent([
+        {
+          type: "tool_call",
+          function: {
+            name: "   ",
+            arguments: "{}",
+          },
+        },
+      ])
+    ).toEqual([
+      {
+        type: "tool_call",
+        toolName: "unknown-tool",
+        arguments: {},
+      },
+    ]);
+  });
+
+  it("collapses whitespace in normalized tool_call names", () => {
+    expect(
+      normalizeOpenAICompatibleContent([
+        {
+          type: "tool_call",
+          function: {
+            name: "  lookup\n\tuser  ",
+            arguments: "{}",
+          },
+        },
+      ])
+    ).toEqual([
+      {
+        type: "tool_call",
+        toolName: "lookup user",
+        arguments: {},
+      },
+    ]);
+  });
+
+  it("strips control characters and truncates oversized tool names", () => {
+    const hugeName = `\u0000tool ${"x".repeat(400)}\n`;
+    const result = normalizeOpenAICompatibleContent([
+      {
+        type: "tool_call",
+        function: {
+          name: hugeName,
+          arguments: "{}",
+        },
+      },
+    ]);
+
+    const toolPart = result as Array<{ toolName: string }>;
+    expect(toolPart[0]?.toolName.length).toBeLessThanOrEqual(256);
+    expect(toolPart[0]?.toolName).not.toContain("\u0000");
+  });
+
+  it("formats non-string text-part payloads safely", () => {
+    expect(
+      normalizeOpenAICompatibleContent([
+        { type: "text", text: 123 },
+        { type: "text", text: null },
+      ])
+    ).toEqual([
+      { type: "text", text: "123" },
+      { type: "text", text: "null" },
+    ]);
+  });
+
+  it("formats unknown object payloads safely", () => {
+    const circular: Record<string, unknown> = { kind: "mystery" };
+    circular.self = circular;
+
+    expect(normalizeOpenAICompatibleContent(circular)).toBe(
+      '{"kind":"mystery","self":"[Circular]"}'
+    );
+  });
+
+  it("normalizes single-part object payloads into content arrays", () => {
+    expect(
+      normalizeOpenAICompatibleContent({
+        type: "text",
+        text: "inline-object-part",
+      })
+    ).toEqual([{ type: "text", text: "inline-object-part" }]);
+  });
+
+  it("truncates oversized unknown object diagnostics", () => {
+    const hugeObject = { payload: "x".repeat(5_000) };
+    const result = normalizeOpenAICompatibleContent(hugeObject);
+    expect(typeof result).toBe("string");
+    expect(result).toContain("[truncated");
+  });
+
+  it("normalizes nullish content to empty string", () => {
+    expect(normalizeOpenAICompatibleContent(null)).toBe("");
+    expect(normalizeOpenAICompatibleContent(undefined)).toBe("");
+  });
+
+  it("handles content-part getters that throw", () => {
+    const trappedPart = new Proxy(
+      {},
+      {
+        get: (_target, prop) => {
+          if (prop === "type") {
+            throw new Error("type getter trap");
+          }
+          return undefined;
+        },
+      }
+    );
+
+    expect(
+      normalizeOpenAICompatibleContent([trappedPart])
+    ).toEqual([
+      {
+        type: "text",
+        text: "{}",
+      },
+    ]);
+  });
+
+  it("handles tool-call field getters that throw", () => {
+    const trappedFunction = new Proxy(
+      {},
+      {
+        get: (_target, prop) => {
+          if (prop === "name" || prop === "arguments") {
+            throw new Error("function field trap");
+          }
+          return undefined;
+        },
+      }
+    );
+
+    expect(
+      normalizeOpenAICompatibleContent([
+        {
+          type: "tool_call",
+          function: trappedFunction,
+        },
+      ])
+    ).toEqual([
+      {
+        type: "tool_call",
+        toolName: "unknown-tool",
+        arguments: {},
+      },
+    ]);
+  });
+
+  it("returns readable diagnostics when content array traversal throws", () => {
+    const trappedArray = new Proxy([1], {
+      get: (target, prop, receiver) => {
+        if (prop === Symbol.iterator) {
+          throw new Error("array iterator trap");
+        }
+        return Reflect.get(target, prop, receiver);
+      },
+    });
+
+    expect(
+      normalizeOpenAICompatibleContent(trappedArray)
+    ).toBe("array iterator trap");
+  });
+
+  it("sanitizes and truncates control-character diagnostics from traversal errors", () => {
+    const trappedArray = new Proxy([1], {
+      get: (target, prop, receiver) => {
+        if (prop === Symbol.iterator) {
+          throw new Error(`array\u0000\n${"x".repeat(5_000)}`);
+        }
+        return Reflect.get(target, prop, receiver);
+      },
+    });
+
+    const output = normalizeOpenAICompatibleContent(trappedArray);
+    expect(typeof output).toBe("string");
+    expect(output).toContain("[truncated");
+    expect(output).not.toContain("\u0000");
+    expect(output).not.toContain("\n");
+  });
+});
diff --git a/src/llm/utils/openai-content.ts b/src/llm/utils/openai-content.ts
new file mode 100644
index 00000000..cba11e7e
--- /dev/null
+++ b/src/llm/utils/openai-content.ts
@@ -0,0 +1,197 @@
+import { HyperAgentContentPart } from "@/llm/types";
+import { parseJsonMaybe } from "@/llm/utils/safe-json";
+import { sanitizeProviderOptions } from "@/llm/utils/provider-options";
+import { formatUnknownError } from "@/utils";
+
+function isRecord(value: unknown): value is Record<string, unknown> {
+  return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+
+const MAX_TOOL_NAME_CHARS = 256;
+const MAX_IMAGE_URL_CHARS = 4_000;
+const MAX_CONTENT_DIAGNOSTIC_CHARS = 2_000;
+
+function normalizeOptionalString(
+  value: unknown,
+  maxChars: number
+): string | undefined {
+  if (typeof value !== "string") {
+    return undefined;
+  }
+  const trimmed = value
+    .replace(/[\u0000-\u001F\u007F]/g, " ")
+    .trim()
+    .replace(/\s+/g, " ");
+  if (trimmed.length === 0) {
+    return undefined;
+  }
+  return trimmed.slice(0, maxChars);
+}
+
+const NO_RESERVED_PROVIDER_OPTION_KEYS: ReadonlySet<string> = new Set();
+
+function truncateContentDiagnostic(value: string, maxChars: number): string {
+  if (value.length <= maxChars) {
+    return value;
+  }
+
+  const omitted = value.length - maxChars;
+  return `${value.slice(0, maxChars)}... [truncated ${omitted} chars]`;
+}
+
+function sanitizeContentDiagnostic(value: string): string {
+  if (value.length === 0) {
+    return value;
+  }
+  return Array.from(value, (char) => {
+    const code = char.charCodeAt(0);
+    return (code >= 0 && code < 32) || code === 127 ? " " : char;
+  })
+    .join("")
+    .replace(/\s+/g, " ")
+    .trim();
+}
+
+function sanitizeToolArguments(value: unknown): unknown {
+  const sanitized = sanitizeProviderOptions(
+    { arguments: value },
+    NO_RESERVED_PROVIDER_OPTION_KEYS
+  );
+  return typeof sanitized?.arguments === "undefined"
+    ? {}
+    : sanitized.arguments;
+}
+
+function normalizeImageUrl(value: unknown): string {
+  if (typeof value === "string") {
+    const normalized = value
+      .replace(/[\u0000-\u001F\u007F]/g, " ")
+      .trim()
+      .replace(/\s+/g, " ");
+    return truncateContentDiagnostic(normalized, MAX_IMAGE_URL_CHARS);
+  }
+  if (typeof value === "undefined") {
+    return "";
+  }
+  return truncateContentDiagnostic(
+    sanitizeContentDiagnostic(formatUnknownError(value)),
+    MAX_IMAGE_URL_CHARS
+  );
+}
+
+function normalizeContentDiagnostic(value: unknown): string {
+  const normalized = sanitizeContentDiagnostic(formatUnknownError(value));
+  const fallback = normalized.length > 0 ? normalized : "{}";
+  return truncateContentDiagnostic(fallback, MAX_CONTENT_DIAGNOSTIC_CHARS);
+}
+
+function normalizeOpenAICompatibleContentPart(
+  part: unknown
+): HyperAgentContentPart {
+  if (!isRecord(part)) {
+    return {
+      type: "text",
+      text: normalizeContentDiagnostic(part),
+    };
+  }
+
+  const partType = safeReadRecordField(part, "type");
+
+  if (partType === "text") {
+    const textValue = safeReadRecordField(part, "text");
+    return {
+      type: "text",
+      text:
+        typeof textValue === "string"
+          ? textValue
+          : normalizeContentDiagnostic(textValue),
+    };
+  }
+
+  if (partType === "image_url") {
+    const imageUrlValue = safeReadRecordField(part, "image_url");
+    const imageUrl = isRecord(imageUrlValue) ? imageUrlValue : {};
+    return {
+      type: "image",
+      url: normalizeImageUrl(safeReadRecordField(imageUrl, "url")),
+      mimeType: "image/png",
+    };
+  }
+
+  if (partType === "tool_call") {
+    const functionValue = safeReadRecordField(part, "function");
+    const fn = isRecord(functionValue) ? functionValue : {};
+    return {
+      type: "tool_call",
+      toolName:
+        normalizeOptionalString(
+          safeReadRecordField(fn, "name"),
+          MAX_TOOL_NAME_CHARS
+        ) ?? "unknown-tool",
+      arguments: sanitizeToolArguments(
+        parseJsonMaybe(safeReadRecordField(fn, "arguments"))
+      ),
+    };
+  }
+
+  return {
+    type: "text",
+    text: normalizeContentDiagnostic(part),
+  };
+}
+
+function isSingleContentPartShape(value: unknown): boolean {
+  if (!isRecord(value)) {
+    return false;
+  }
+  const type = safeReadRecordField(value, "type");
+  if (typeof type !== "string") {
+    return false;
+  }
+  return (
+    type === "text" ||
+    type === "image_url" ||
+    type === "tool_call"
+  );
+}
+
+function safeReadRecordField(
+  value: Record<string, unknown>,
+  key: string
+): unknown {
+  try {
+    return value[key];
+  } catch {
+    return undefined;
+  }
+}
+
+export function normalizeOpenAICompatibleContent(
+  content: unknown
+): string | HyperAgentContentPart[] {
+  if (typeof content === "string") {
+    return content;
+  }
+
+  if (Array.isArray(content)) {
+    try {
+      return Array.from(content).map(normalizeOpenAICompatibleContentPart);
+    } catch (error) {
+      return normalizeContentDiagnostic(error);
+    }
+  }
+
+  if (content == null) {
+    return "";
+  }
+
+  if (isSingleContentPartShape(content)) {
+    return [normalizeOpenAICompatibleContentPart(content)];
+  }
+
+  if (typeof content === "object") {
+    return normalizeContentDiagnostic(content);
+  }
+
+  return normalizeContentDiagnostic(content);
+}
diff --git a/src/llm/utils/openai-tool-calls.test.ts b/src/llm/utils/openai-tool-calls.test.ts
new file mode 100644
index 00000000..bbda434b
--- /dev/null
+++ b/src/llm/utils/openai-tool-calls.test.ts
@@ -0,0 +1,342 @@
+import { normalizeOpenAIToolCalls } from "@/llm/utils/openai-tool-calls";
+
+describe("normalizeOpenAIToolCalls", () => {
+  it("returns undefined when tool_calls is not an array", () => {
+    expect(normalizeOpenAIToolCalls(undefined)).toBeUndefined();
+    expect(normalizeOpenAIToolCalls("oops")).toBeUndefined();
+  });
+
+  it("normalizes function and custom tool calls", () => {
+    const result = normalizeOpenAIToolCalls([
+      {
+        id: "fn-1",
+        type: "function",
+        function: {
+          name: "search",
+          arguments: '{"q":"hello"}',
+        },
+      },
+      {
+        id: "custom-1",
+        type: "custom",
+        custom: {
+          name: "lookup",
+          input: "{broken",
+        },
+      },
+    ]);
+
+    expect(result).toEqual([
+      {
+        id: "fn-1",
+        name: "search",
+        arguments: { q: "hello" },
+      },
+      {
+        id: "custom-1",
+        name: "lookup",
+        arguments: "{broken",
+      },
+    ]);
+  });
+
+  it("formats unknown tool call type errors with serialized payloads", () => {
+    expect(() =>
+      normalizeOpenAIToolCalls([
+        {
+          id: "x",
+          type: "mystery",
+          data: { answer: 42 },
+        },
+      ])
+    ).toThrow(
+      '[LLM][OpenAI] Unknown tool call type: {"id":"x","type":"mystery","data":{"answer":42}}'
+    );
+  });
+
+  it("formats non-object tool call entries with readable errors", () => {
+    expect(() => normalizeOpenAIToolCalls([null])).toThrow(
+      "[LLM][OpenAI] Unknown tool call payload: null"
+    );
+  });
+
+  it("supports provider-specific labels in error messages", () => {
+    expect(() =>
+      normalizeOpenAIToolCalls(
+        [
+          {
+            id: "x",
+            type: "mystery",
+          },
+        ],
+        "DeepSeek"
+      )
+    ).toThrow('[LLM][DeepSeek] Unknown tool call type: {"id":"x","type":"mystery"}');
+  });
+
+  it("normalizes provider labels used in diagnostics", () => {
+    expect(() =>
+      normalizeOpenAIToolCalls(
+        [
+          {
+            id: "x",
+            type: "mystery",
+          },
+        ],
+        "  DeepSeek\u0000 Provider \n Name That Is Really Really Long  "
+      )
+    ).toThrow("[LLM][DeepSeek Provider Name That Is Really Re]");
+  });
+
+  it("truncates oversized tool-call diagnostics in errors", () => {
+    const huge = "x".repeat(3_500);
+    expect(() =>
+      normalizeOpenAIToolCalls([
+        {
+          type: "mystery",
+          payload: huge,
+        },
+      ])
+    ).toThrow("[truncated");
+  });
+
+  it("normalizes whitespace-only ids and tool names safely", () => {
+    expect(
+      normalizeOpenAIToolCalls([
+        {
+          id: "   ",
+          type: "function",
+          function: {
+            name: "   ",
+            arguments: "{}",
+          },
+        },
+      ])
+    ).toEqual([
+      {
+        id: undefined,
+        name: "unknown-tool",
+        arguments: {},
+      },
+    ]);
+  });
+
+  it("sanitizes unsafe keys from parsed tool-call arguments", () => {
+    expect(
+      normalizeOpenAIToolCalls([
+        {
+          id: "fn-1",
+          type: "function",
+          function: {
+            name: "lookup",
+            arguments:
+              '{"safe":1,"__proto__":{"polluted":true},"nested":{"constructor":"bad","ok":true}}',
+          },
+        },
+      ])
+    ).toEqual([
+      {
+        id: "fn-1",
+        name: "lookup",
+        arguments: {
+          safe: 1,
+          nested: {
+            ok: true,
+          },
+        },
+      },
+    ]);
+  });
+
+  it("sanitizes circular direct-object arguments safely", () => {
+    const circular: Record<string, unknown> = { id: "node" };
+    circular.self = circular;
+
+    expect(
+      normalizeOpenAIToolCalls([
+        {
+          id: "custom-1",
+          type: "custom",
+          custom: {
+            name: "lookup",
+            input: circular,
+          },
+        },
+      ])
+    ).toEqual([
+      {
+        id: "custom-1",
+        name: "lookup",
+        arguments: {
+          id: "node",
+          self: "[Circular]",
+        },
+      },
+    ]);
+  });
+
+  it("defaults missing tool-call arguments to empty object", () => {
+    expect(
+      normalizeOpenAIToolCalls([
+        {
+          id: "fn-1",
+          type: "function",
+          function: {
+            name: "lookup",
+          },
+        },
+      ])
+    ).toEqual([
+      {
+        id: "fn-1",
+        name: "lookup",
+        arguments: {},
+      },
+    ]);
+  });
+
+  it("collapses whitespace in normalized tool-call names", () => {
+    expect(
+      normalizeOpenAIToolCalls([
+        {
+          id: "fn-1",
+          type: "function",
+          function: {
+            name: "  lookup\n\tuser  ",
+            arguments: "{}",
+          },
+        },
+      ])
+    ).toEqual([
+      {
+        id: "fn-1",
+        name: "lookup user",
+        arguments: {},
+      },
+    ]);
+  });
+
+  it("strips control characters and truncates oversized identifiers", () => {
+    const hugeName = `\u0000tool ${"x".repeat(400)}\n`;
+    const hugeId = `\u0000id ${"y".repeat(400)}\n`;
+
+    const result = normalizeOpenAIToolCalls([
+      {
+        id: hugeId,
+        type: "function",
+        function: {
+          name: hugeName,
+          arguments: "{}",
+        },
+      },
+    ]);
+
+    const normalized = result?.[0];
+    expect(normalized?.id?.length).toBeLessThanOrEqual(256);
+    expect(normalized?.name.length ?? 0).toBeLessThanOrEqual(256);
+    expect(normalized?.id).not.toContain("\u0000");
+    expect(normalized?.name).not.toContain("\u0000");
+  });
+
+  it("handles function tool fields with throwing getters", () => {
+    const trappedFunction = new Proxy(
+      {},
+      {
+        get: (_target, prop) => {
+          if (prop === "name" || prop === "arguments") {
+            throw new Error("function field trap");
+          }
+          return undefined;
+        },
+      }
+    );
+
+    expect(
+      normalizeOpenAIToolCalls([
+        {
+          id: "fn-1",
+          type: "function",
+          function: trappedFunction,
+        },
+      ])
+    ).toEqual([
+      {
+        id: "fn-1",
+        name: "unknown-tool",
+        arguments: {},
+      },
+    ]);
+  });
+
+  it("handles tool-call type getters that throw", () => {
+    const trappedToolCall = new Proxy(
+      {
+        id: "fn-1",
+      },
+      {
+        get: (target, prop, receiver) => {
+          if (prop === "type") {
+            throw new Error("type trap");
+          }
+          return Reflect.get(target, prop, receiver);
+        },
+      }
+    );
+
+    expect(() => normalizeOpenAIToolCalls([trappedToolCall])).toThrow(
+      '[LLM][OpenAI] Unknown tool call type: {"id":"fn-1"}'
+    );
+  });
+
+  it("throws readable error when tool-call array traversal fails", () => {
+    const trappedArray = new Proxy([{}], {
+      get: (target, prop, receiver) => {
+        if (prop === Symbol.iterator) {
+          throw new Error("tool-call iterator trap");
+        }
+        return Reflect.get(target, prop, receiver);
+      },
+    });
+
+    expect(() =>
+      normalizeOpenAIToolCalls(trappedArray)
+    ).toThrow(
+      "[LLM][OpenAI] Unknown tool calls payload: tool-call iterator trap"
+    );
+  });
+
+  it("sanitizes and truncates oversized traversal diagnostics", () => {
+    const trappedArray = new Proxy([{}], {
+      get: (target, prop, receiver) => {
+        if (prop === Symbol.iterator) {
+          throw new Error(`iterator\u0000\n${"x".repeat(5_000)}`);
+        }
+        return Reflect.get(target, prop, receiver);
+      },
+    });
+
+    try {
+      normalizeOpenAIToolCalls(trappedArray);
+      throw new Error("Expected normalizeOpenAIToolCalls to throw");
+    } catch (error) {
+      const message = String(error instanceof Error ? error.message : error);
+      expect(message).toContain("[truncated");
+      expect(message).not.toContain("\u0000");
+      expect(message).not.toContain("\n");
+      expect(message.length).toBeLessThan(2_500);
+    }
+  });
+
+  it("normalizes non-string provider labels safely", () => {
+    expect(() =>
+      normalizeOpenAIToolCalls(
+        [
+          {
+            type: "mystery",
+          },
+        ],
+        { provider: "mystery" } as unknown as string
+      )
+    ).toThrow('[LLM][{"provider":"mystery"}] Unknown tool call type: {"type":"mystery"}');
+  });
+});
diff --git a/src/llm/utils/openai-tool-calls.ts b/src/llm/utils/openai-tool-calls.ts
new file mode 100644
index 00000000..5ae03fc2
--- /dev/null
+++ b/src/llm/utils/openai-tool-calls.ts
@@ -0,0 +1,167 @@
+import { parseJsonMaybe } from "@/llm/utils/safe-json";
+import { sanitizeProviderOptions } from "@/llm/utils/provider-options";
+import { formatUnknownError } from "@/utils";
+
+export interface NormalizedOpenAIToolCall {
+  id?: string;
+  name: string;
+  arguments: unknown;
+}
+
+const NO_RESERVED_PROVIDER_OPTION_KEYS: ReadonlySet<string> = new Set();
+const MAX_TOOL_CALL_DIAGNOSTIC_CHARS = 2_000;
+const MAX_TOOL_CALL_ID_CHARS = 256;
+const MAX_TOOL_CALL_NAME_CHARS = 256;
+const MAX_PROVIDER_LABEL_CHARS = 40;
+
+function isRecord(value: unknown): value is Record<string, unknown> {
+  return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+
+function safeReadRecordField(
+  value: Record<string, unknown>,
+  key: string
+): unknown {
+  try {
+    return value[key];
+  } catch {
+    return undefined;
+  }
+}
+
+function normalizeOptionalString(
+  value: unknown,
+  maxChars: number
+): string | undefined {
+  if (typeof value !== "string") {
+    return undefined;
+  }
+  const trimmed = value
+    .replace(/[\u0000-\u001F\u007F]/g, " ")
+    .trim()
+    .replace(/\s+/g, " ");
+  if (trimmed.length === 0) {
+    return undefined;
+  }
+  return trimmed.slice(0, maxChars);
+}
+
+function sanitizeToolArguments(value: unknown): unknown {
+  const sanitized = sanitizeProviderOptions(
+    { arguments: value },
+    NO_RESERVED_PROVIDER_OPTION_KEYS
+  );
+  return typeof sanitized?.arguments === "undefined"
+    ? {}
+    : sanitized.arguments;
+}
+
+function normalizeProviderLabel(providerLabel: unknown): string {
+  const rawLabel =
+    typeof providerLabel === "string"
+      ? providerLabel
+      : formatUnknownError(providerLabel);
+  const normalized = rawLabel
+    .replace(/[\u0000-\u001F\u007F]/g, " ")
+    .trim()
+    .replace(/\s+/g, " ");
+  if (normalized.length === 0) {
+    return "Provider";
+  }
+  return normalized.slice(0, MAX_PROVIDER_LABEL_CHARS);
+}
+
+function formatToolCallDiagnostic(value: unknown): string {
+  const formatted = Array.from(formatUnknownError(value), (char) => {
+    const code = char.charCodeAt(0);
+    return (code >= 0 && code < 32) || code === 127 ? " " : char;
+  })
+    .join("")
+    .replace(/\s+/g, " ")
+    .trim();
+  const fallback = formatted.length > 0 ? formatted : "unknown error";
+  if (fallback.length <= MAX_TOOL_CALL_DIAGNOSTIC_CHARS) {
+    return fallback;
+  }
+
+  const omitted = fallback.length - MAX_TOOL_CALL_DIAGNOSTIC_CHARS;
+  return `${fallback.slice(
+    0,
+    MAX_TOOL_CALL_DIAGNOSTIC_CHARS
+  )}... [truncated ${omitted} chars]`;
+}
+
+export function normalizeOpenAIToolCalls(
+  toolCalls: unknown,
+  providerLabel = "OpenAI"
+): Array<NormalizedOpenAIToolCall> | undefined {
+  if (!Array.isArray(toolCalls)) {
+    return undefined;
+  }
+
+  const normalizedProviderLabel = normalizeProviderLabel(providerLabel);
+  let entries: unknown[];
+  try {
+    entries = Array.from(toolCalls);
+  } catch (error) {
+    throw new Error(
+      `[LLM][${normalizedProviderLabel}] Unknown tool calls payload: ${formatToolCallDiagnostic(
+        error
+      )}`
+    );
+  }
+
+  return entries.map((toolCall) => {
+    if (!isRecord(toolCall)) {
+      throw new Error(
+        `[LLM][${normalizedProviderLabel}] Unknown tool call payload: ${formatToolCallDiagnostic(toolCall)}`
+      );
+    }
+
+    const toolCallType = safeReadRecordField(toolCall, "type");
+
+    if (toolCallType === "function") {
+      const functionValue = safeReadRecordField(toolCall, "function");
+      const fn = isRecord(functionValue) ? functionValue : {};
+      return {
+        id: normalizeOptionalString(
+          safeReadRecordField(toolCall, "id"),
+          MAX_TOOL_CALL_ID_CHARS
+        ),
+        name:
+          normalizeOptionalString(
+            safeReadRecordField(fn, "name"),
+            MAX_TOOL_CALL_NAME_CHARS
+          ) ??
+          "unknown-tool",
+        arguments: sanitizeToolArguments(
+          parseJsonMaybe(safeReadRecordField(fn, "arguments"))
+        ),
+      };
+    }
+
+    if (toolCallType === "custom") {
+      const customValue = safeReadRecordField(toolCall, "custom");
+      const custom = isRecord(customValue) ? customValue : {};
+      return {
+        id: normalizeOptionalString(
+          safeReadRecordField(toolCall, "id"),
+          MAX_TOOL_CALL_ID_CHARS
+        ),
+        name:
+          normalizeOptionalString(
+            safeReadRecordField(custom, "name"),
+            MAX_TOOL_CALL_NAME_CHARS
+          ) ??
+          "unknown-tool",
+        arguments: sanitizeToolArguments(
+          parseJsonMaybe(safeReadRecordField(custom, "input"))
+        ),
+      };
+    }
+
+    throw new Error(
+      `[LLM][${normalizedProviderLabel}] Unknown tool call type: ${formatToolCallDiagnostic(toolCall)}`
+    );
+  });
+}
diff --git a/src/llm/utils/provider-options.test.ts b/src/llm/utils/provider-options.test.ts
new file mode 100644
index 00000000..c7a15f56
--- /dev/null
+++ b/src/llm/utils/provider-options.test.ts
@@ -0,0 +1,366 @@
+import { sanitizeProviderOptions } from "@/llm/utils/provider-options";
+
+describe("sanitizeProviderOptions", () => {
+  const reserved = new Set(["model", "messages", "max_tokens"]);
+
+  it("returns undefined for non-object provider options", () => {
+    expect(sanitizeProviderOptions(undefined, reserved)).toBeUndefined();
+    expect(sanitizeProviderOptions("oops", reserved)).toBeUndefined();
+    expect(sanitizeProviderOptions([], reserved)).toBeUndefined();
+  });
+
+  it("removes reserved keys and keeps custom options", () => {
+    expect(
+      sanitizeProviderOptions(
+        {
+          model: "override",
+          messages: "override",
+          max_tokens: 999,
+          top_p: 0.9,
+          frequency_penalty: 0.2,
+        },
+        reserved
+      )
+    ).toEqual({
+      top_p: 0.9,
+      frequency_penalty: 0.2,
+    });
+  });
+
+  it("returns undefined when all keys are reserved", () => {
+    expect(
+      sanitizeProviderOptions(
+        {
+          model: "override",
+          messages: "override",
+        },
+        reserved
+      )
+    ).toBeUndefined();
+  });
+
+  it("drops unsafe prototype-like keys", () => {
+    const options = {
+      ["__proto__"]: { polluted: true },
+      constructor: "bad",
+      prototype: "bad",
+      top_p: 0.95,
+    };
+
+    expect(
+      sanitizeProviderOptions(options, reserved)
+    ).toEqual({
+      top_p: 0.95,
+    });
+  });
+
+  it("matches reserved keys case-insensitively after trimming", () => {
+    expect(
+      sanitizeProviderOptions(
+        {
+          " Model ": "override",
+          " Messages ": "override",
+          top_p: 0.8,
+        },
+        reserved
+      )
+    ).toEqual({
+      top_p: 0.8,
+    });
+  });
+
+  it("trims custom keys and discards empty keys", () => {
+    expect(
+      sanitizeProviderOptions(
+        {
+          "  top_p  ": 0.8,
+          "   ": "empty",
+        },
+        reserved
+      )
+    ).toEqual({
+      top_p: 0.8,
+    });
+  });
+
+  it("sanitizes control characters in custom option keys", () => {
+    expect(
+      sanitizeProviderOptions(
+        {
+          "  top\n\tp  ": 0.7,
+        },
+        reserved
+      )
+    ).toEqual({
+      "top p": 0.7,
+    });
+  });
+
+  it("recursively removes unsafe keys from nested objects", () => {
+    const result = sanitizeProviderOptions(
+      {
+        top_p: 0.95,
+        metadata: {
+          safe: "ok",
+          constructor: "bad",
+          nested: {
+            ["__proto__"]: "bad",
+            keep: true,
+          },
+        },
+      },
+      reserved
+    );
+
+    expect(result).toEqual({
+      top_p: 0.95,
+      metadata: {
+        safe: "ok",
+        nested: {
+          keep: true,
+        },
+      },
+    });
+  });
+
+  it("removes nested unsafe keys with surrounding whitespace", () => {
+    const result = sanitizeProviderOptions(
+      {
+        metadata: {
+          " __proto__ ": "bad",
+          keep: true,
+        },
+      },
+      reserved
+    );
+
+    expect(result).toEqual({
+      metadata: {
+        keep: true,
+      },
+    });
+  });
+
+  it("replaces circular nested values with safe marker", () => {
+    const circular: Record<string, unknown> = { id: "node" };
+    circular.self = circular;
+
+    const result = sanitizeProviderOptions(
+      {
+        metadata: circular,
+      },
+      reserved
+    );
+
+    expect(result).toEqual({
+      metadata: {
+        id: "node",
+        self: "[Circular]",
+      },
+    });
+  });
+
+  it("replaces circular arrays with safe markers", () => {
+    const circularArray: unknown[] = [];
+    circularArray.push(circularArray);
+
+    const result = sanitizeProviderOptions(
+      {
+        list: circularArray,
+      },
+      reserved
+    );
+
+    expect(result).toEqual({
+      list: ["[Circular]"],
+    });
+  });
+
+  it("preserves non-plain objects like Date values", () => {
+    const createdAt = new Date("2026-01-01T00:00:00.000Z");
+    const result = sanitizeProviderOptions(
+      {
+        metadata: {
+          createdAt,
+        },
+      },
+      reserved
+    );
+
+    expect(result).toEqual({
+      metadata: {
+        createdAt,
+      },
+    });
+  });
+
+  it("normalizes bigint, symbol, and function values safely", () => {
+    const symbolValue = Symbol("token");
+    function sampleFunction(): void {
+      return;
+    }
+
+    const result = sanitizeProviderOptions(
+      {
+        bigintValue: BigInt(42),
+        symbolValue,
+        functionValue: sampleFunction,
+      },
+      reserved
+    );
+
+    expect(result).toEqual({
+      bigintValue: "42n",
+      symbolValue: "Symbol(token)",
+      functionValue: "[Function sampleFunction]",
+    });
+  });
+
+  it("truncates oversized string option values", () => {
+    const result = sanitizeProviderOptions(
+      {
+        metadata: "x".repeat(20_100),
+      },
+      reserved
+    ) as Record<string, unknown>;
+
+    expect(typeof result.metadata).toBe("string");
+    expect(result.metadata as string).toContain("[truncated");
+    expect((result.metadata as string).length).toBeLessThan(20_200);
+  });
+
+  it("returns deterministic marker for arrays that fail during traversal", () => {
+    const trappedArray = new Proxy(["ok"], {
+      get: (target, prop, receiver) => {
+        if (prop === "map") {
+          throw new Error("array map trap");
+        }
+        return Reflect.get(target, prop, receiver);
+      },
+    });
+
+    const result = sanitizeProviderOptions(
+      {
+        metadata: trappedArray,
+      },
+      reserved
+    );
+
+    expect(result).toEqual({
+      metadata: "[UnserializableArray: array map trap]",
+    });
+  });
+
+  it("sanitizes and truncates traversal diagnostics for arrays", () => {
+    const trappedArray = new Proxy(["ok"], {
+      get: (target, prop, receiver) => {
+        if (prop === "map") {
+          throw new Error(`array\u0000\n${"x".repeat(2_000)}`);
+        }
+        return Reflect.get(target, prop, receiver);
+      },
+    });
+
+    const result = sanitizeProviderOptions(
+      {
+        metadata: trappedArray,
+      },
+      reserved
+    ) as Record<string, unknown>;
+
+    expect(typeof result.metadata).toBe("string");
+    expect(result.metadata as string).toContain("[UnserializableArray: ");
+    expect(result.metadata as string).toContain("[truncated");
+    expect(result.metadata as string).not.toContain("\u0000");
+    expect(result.metadata as string).not.toContain("\n");
+  });
+
+  it("returns deterministic marker for objects that fail during entry traversal", () => {
+    const trappedObject = new Proxy(
+      {},
+      {
+        ownKeys: () => {
+          throw new Error("entry trap");
+        },
+      }
+    );
+
+    const result = sanitizeProviderOptions(
+      {
+        metadata: trappedObject,
+      },
+      reserved
+    );
+
+    expect(result).toEqual({
+      metadata: "[UnserializableObject: entry trap]",
+    });
+  });
+
+  it("returns undefined when top-level options object entries are unreadable", () => {
+    const trappedOptions = new Proxy(
+      {},
+      {
+        ownKeys: () => {
+          throw new Error("top-level entry trap");
+        },
+      }
+    );
+
+    expect(
+      sanitizeProviderOptions(
+        trappedOptions as unknown as Record<string, unknown>,
+        reserved
+      )
+    ).toBeUndefined();
+  });
+
+  it("falls back safely when reserved-key iteration throws", () => {
+    const trappedReservedKeys = new Proxy(
+      new Set(["model"]),
+      {
+        get: (target, prop, receiver) => {
+          if (prop === Symbol.iterator) {
+            throw new Error("reserved iterator trap");
+          }
+          return Reflect.get(target, prop, receiver);
+        },
+      }
+    );
+
+    expect(
+      sanitizeProviderOptions(
+        {
+          top_p: 0.8,
+        },
+        trappedReservedKeys as unknown as ReadonlySet<string>
+      )
+    ).toEqual({
+      top_p: 0.8,
+    });
+  });
+
+  it("caps excessive provider-option nesting depth", () => {
+    const deeplyNested: Record<string, unknown> = {};
+    let cursor: Record<string, unknown> = deeplyNested;
+    for (let depth = 0; depth < 30; depth += 1) {
+      cursor.child = {};
+      cursor = cursor.child as Record<string, unknown>;
+    }
+
+    const result = sanitizeProviderOptions(
+      {
+        metadata: deeplyNested,
+      },
+      reserved
+    ) as Record<string, unknown>;
+
+    let current = result.metadata as Record<string, unknown>;
+    for (let depth = 0; depth < 19; depth += 1) {
+      current = current.child as Record<string, unknown>;
+      expect(typeof current).toBe("object");
+    }
+
+    expect(current.child).toBe("[MaxDepthExceeded]");
+  });
+});
diff --git a/src/llm/utils/provider-options.ts b/src/llm/utils/provider-options.ts
new file mode 100644
index 00000000..19d4ac6d
--- /dev/null
+++ b/src/llm/utils/provider-options.ts
@@ -0,0 +1,193 @@
+import { formatUnknownError } from "@/utils";
+
+function isRecord(value: unknown): value is Record<string, unknown> {
+  return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+
+function isPlainRecord(value: unknown): value is Record<string, unknown> {
+  if (!isRecord(value)) {
+    return false;
+  }
+  let prototype: object | null;
+  try {
+    prototype = Object.getPrototypeOf(value);
+  } catch {
+    return false;
+  }
+  return prototype === Object.prototype || prototype === null;
+}
+
+const UNSAFE_OPTION_KEYS = new Set(["__proto__", "prototype", "constructor"]);
+const MAX_PROVIDER_OPTIONS_DEPTH = 20;
+const MAX_PROVIDER_OPTION_KEY_CHARS = 256;
+const MAX_PROVIDER_OPTION_STRING_CHARS = 20_000;
+const MAX_PROVIDER_OPTIONS_DIAGNOSTIC_CHARS = 200;
+
+function stripControlChars(value: string): string {
+  return Array.from(value)
+    .map((char) => {
+      const code = char.charCodeAt(0);
+      return (code >= 0 && code < 32) || code === 127 ? " " : char;
+    })
+    .join("");
+}
+
+function formatProviderOptionDiagnostic(value: unknown): string {
+  const normalized = stripControlChars(
+    typeof value === "string" ? value : formatUnknownError(value)
+  )
+    .replace(/\s+/g, " ")
+    .trim();
+  const fallback = normalized.length > 0 ? normalized : "unknown error";
+  if (fallback.length <= MAX_PROVIDER_OPTIONS_DIAGNOSTIC_CHARS) {
+    return fallback;
+  }
+  return `${fallback.slice(
+    0,
+    MAX_PROVIDER_OPTIONS_DIAGNOSTIC_CHARS
+  )}... [truncated ${fallback.length - MAX_PROVIDER_OPTIONS_DIAGNOSTIC_CHARS} chars]`;
+}
+
+function truncateProviderOptionString(value: string): string {
+  if (value.length <= MAX_PROVIDER_OPTION_STRING_CHARS) {
+    return value;
+  }
+  return `${value.slice(
+    0,
+    MAX_PROVIDER_OPTION_STRING_CHARS
+  )}... [truncated ${value.length - MAX_PROVIDER_OPTION_STRING_CHARS} chars]`;
+}
+
+function normalizeOptionKey(key: string): string {
+  const normalized = stripControlChars(key).replace(/\s+/g, " ").trim();
+  if (normalized.length <= MAX_PROVIDER_OPTION_KEY_CHARS) {
+    return normalized;
+  }
+  return normalized.slice(0, MAX_PROVIDER_OPTION_KEY_CHARS);
+}
+
+function toComparableOptionKey(key: string): string {
+  return normalizeOptionKey(key).toLowerCase();
+}
+
+function sanitizeOptionValue(
+  value: unknown,
+  seen: WeakSet<object>,
+  depth: number
+): unknown {
+  if (depth >= MAX_PROVIDER_OPTIONS_DEPTH) {
+    return "[MaxDepthExceeded]";
+  }
+
+  if (typeof value === "string") {
+    return truncateProviderOptionString(value);
+  }
+
+  if (typeof value === "object" && value !== null) {
+    if (seen.has(value)) {
+      return "[Circular]";
+    }
+    seen.add(value);
+  }
+
+  if (Array.isArray(value)) {
+    try {
+      return value.map((entry) => sanitizeOptionValue(entry, seen, depth + 1));
+    } catch (error) {
+      return `[UnserializableArray: ${formatProviderOptionDiagnostic(error)}]`;
+    } finally {
+      seen.delete(value);
+    }
+  }
+
+  if (isPlainRecord(value)) {
+    try {
+      const sanitizedEntries = new Map<string, unknown>();
+      for (const [rawKey, entry] of Object.entries(value)) {
+        const normalizedKey = normalizeOptionKey(rawKey);
+        const comparableKey = normalizedKey.toLowerCase();
+        if (normalizedKey.length === 0) {
+          continue;
+        }
+        if (UNSAFE_OPTION_KEYS.has(comparableKey)) {
+          continue;
+        }
+        sanitizedEntries.set(
+          normalizedKey,
+          sanitizeOptionValue(entry, seen, depth + 1)
+        );
+      }
+      return Object.fromEntries(sanitizedEntries);
+    } catch (error) {
+      return `[UnserializableObject: ${formatProviderOptionDiagnostic(error)}]`;
+    } finally {
+      seen.delete(value);
+    }
+  }
+
+  if (typeof value === "object" && value !== null) {
+    seen.delete(value);
+  }
+
+  if (typeof value === "bigint") {
+    return `${value.toString()}n`;
+  }
+
+  if (typeof value === "symbol") {
+    return value.toString();
+  }
+
+  if (typeof value === "function") {
+    return `[Function ${value.name || "anonymous"}]`;
+  }
+
+  return value;
+}
+
+export function sanitizeProviderOptions(
+  providerOptions: unknown,
+  reservedKeys: ReadonlySet<string>
+): Record<string, unknown> | undefined {
+  if (!isRecord(providerOptions)) {
+    return undefined;
+  }
+
+  let comparableReservedKeys: Set<string>;
+  try {
+    comparableReservedKeys = new Set(
+      Array.from(reservedKeys).map((key) => toComparableOptionKey(key))
+    );
+  } catch {
+    comparableReservedKeys = new Set<string>();
+  }
+
+  const seen = new WeakSet<object>();
+  const sanitizedEntries = new Map<string, unknown>();
+  let entries: [string, unknown][];
+  try {
+    entries = Object.entries(providerOptions);
+  } catch {
+    return undefined;
+  }
+
+  for (const [rawKey, value] of entries) {
+    const normalizedKey = normalizeOptionKey(rawKey);
+    if (normalizedKey.length === 0) {
+      continue;
+    }
+    const comparableKey = normalizedKey.toLowerCase();
+    if (
+      comparableReservedKeys.has(comparableKey) ||
+      UNSAFE_OPTION_KEYS.has(comparableKey)
+    ) {
+      continue;
+    }
+    sanitizedEntries.set(normalizedKey, sanitizeOptionValue(value, seen, 0));
+  }
+
+  if (sanitizedEntries.size === 0) {
+    return undefined;
+  }
+
+  return Object.fromEntries(sanitizedEntries);
+}
diff --git a/src/llm/utils/safe-json.test.ts b/src/llm/utils/safe-json.test.ts
new file mode 100644
index 00000000..89555d36
--- /dev/null
+++ b/src/llm/utils/safe-json.test.ts
@@ -0,0 +1,30 @@
+import { parseJsonMaybe } from "@/llm/utils/safe-json";
+
+describe("parseJsonMaybe", () => {
+  it("parses valid JSON strings", () => {
+    expect(parseJsonMaybe('{"ok":true}')).toEqual({ ok: true });
+  });
+
+  it("parses JSON strings with BOM and surrounding whitespace", () => {
+    expect(parseJsonMaybe(" \n\uFEFF {\"ok\":true} \n")).toEqual({ ok: true });
+  });
+
+  it("returns original string when parsing fails", () => {
+    expect(parseJsonMaybe("{broken")).toBe("{broken");
+  });
+
+  it("returns original string when value is only whitespace", () => {
+    expect(parseJsonMaybe("   ")).toBe("   ");
+  });
+
+  it("skips parsing when payload exceeds safe size threshold", () => {
+    const huge = `"${"x".repeat(120000)}"`;
+    expect(parseJsonMaybe(huge)).toBe(huge);
+  });
+
+  it("returns non-string values unchanged", () => {
+    const obj = { a: 1 };
+    expect(parseJsonMaybe(obj)).toBe(obj);
+    expect(parseJsonMaybe(1)).toBe(1);
+  });
+});
diff --git a/src/llm/utils/safe-json.ts b/src/llm/utils/safe-json.ts
new file mode 100644
index 00000000..1a807f78
--- /dev/null
+++ b/src/llm/utils/safe-json.ts
@@ -0,0 +1,19 @@
+const MAX_SAFE_JSON_PARSE_CHARS = 100_000;
+
+export function parseJsonMaybe(value: unknown): unknown {
+  if (typeof value !== "string") {
+    return value;
+  }
+  const normalized = value.replace(/^\uFEFF/, "").trim();
+  if (normalized.length === 0) {
+    return value;
+  }
+  if (normalized.length > MAX_SAFE_JSON_PARSE_CHARS) {
+    return value;
+  }
+  try {
+    return JSON.parse(normalized);
+  } catch {
+    return value;
+  }
+}
diff --git a/src/llm/utils/schema-converter.test.ts b/src/llm/utils/schema-converter.test.ts
new file mode 100644
index 00000000..019e6e29
--- /dev/null
+++ b/src/llm/utils/schema-converter.test.ts
@@ -0,0 +1,143 @@
+import { z } from "zod";
+import {
+  convertActionsToAnthropicTools,
+  convertToGeminiResponseSchema,
+} from "@/llm/utils/schema-converter";
+import type { AgentActionDefinition } from "@/types/agent/actions/types";
+
+function createAction(
+  overrides: Partial<AgentActionDefinition> = {}
+): AgentActionDefinition {
+  return {
+    type: "lookup",
+    toolName: "lookup",
+    toolDescription: "Lookup records",
+    actionParams: z.object({
+      query: z.string(),
+    }),
+    run: jest.fn(),
+    ...overrides,
+  } as unknown as AgentActionDefinition;
+}
+
+describe("convertActionsToAnthropicTools", () => {
+  it("converts action definitions into Anthropic tool schemas", () => {
+    const tools = convertActionsToAnthropicTools([createAction()]);
+    const tool = tools[0] as Record<string, unknown>;
+    const inputSchema = tool.input_schema as Record<string, unknown>;
+    const action = (inputSchema.properties as Record<string, unknown>)
+      .action as Record<string, unknown>;
+    const actionType = (action.properties as Record<string, unknown>)
+      .type as Record<string, unknown>;
+
+    expect(tool.name).toBe("lookup");
+    expect(actionType.const).toBe("lookup");
+    expect(tool.description).toContain("IMPORTANT: Response must have this exact structure");
+  });
+
+  it("falls back to permissive params schema when actionParams are unreadable", () => {
+    const trappedAction = new Proxy(createAction(), {
+      get: (target, prop, receiver) => {
+        if (prop === "actionParams") {
+          throw new Error("params trap");
+        }
+        return Reflect.get(target, prop, receiver);
+      },
+    });
+
+    const tools = convertActionsToAnthropicTools([
+      trappedAction as unknown as AgentActionDefinition,
+    ]);
+    const tool = tools[0] as Record<string, unknown>;
+    const inputSchema = tool.input_schema as Record<string, unknown>;
+    const action = (inputSchema.properties as Record<string, unknown>)
+      .action as Record<string, unknown>;
+    const params = (action.properties as Record<string, unknown>)
+      .params as Record<string, unknown>;
+
+    expect(params.type).toBe("object");
+    expect(params.additionalProperties).toBe(true);
+  });
+
+  it("falls back to synthesized action names when type/toolName are unreadable", () => {
+    const trappedAction = new Proxy(createAction(), {
+      get: (target, prop, receiver) => {
+        if (prop === "type" || prop === "toolName") {
+          throw new Error("name trap");
+        }
+        return Reflect.get(target, prop, receiver);
+      },
+    });
+
+    const tools = convertActionsToAnthropicTools([
+      trappedAction as unknown as AgentActionDefinition,
+    ]);
+    const tool = tools[0] as Record<string, unknown>;
+    const inputSchema = tool.input_schema as Record<string, unknown>;
+    const action = (inputSchema.properties as Record<string, unknown>)
+      .action as Record<string, unknown>;
+    const actionType = (action.properties as Record<string, unknown>)
+      .type as Record<string, unknown>;
+
+    expect(tool.name).toBe("unknown_action_1");
+    expect(actionType.const).toBe("unknown_action_1");
+  });
+
+  it("throws readable diagnostics when action-definition array traversal fails", () => {
+    const trappedActions = new Proxy([createAction()], {
+      get: (target, prop, receiver) => {
+        if (prop === Symbol.iterator) {
+          throw new Error("action array trap");
+        }
+        return Reflect.get(target, prop, receiver);
+      },
+    });
+
+    expect(() =>
+      convertActionsToAnthropicTools(
+        trappedActions as unknown as AgentActionDefinition[]
+      )
+    ).toThrow(
+      "[LLM][SchemaConverter] Invalid action definitions payload: action array trap"
+    );
+  });
+
+  it("sanitizes and truncates oversized action-array traversal diagnostics", () => {
+    const trappedActions = new Proxy([createAction()], {
+      get: (target, prop, receiver) => {
+        if (prop === Symbol.iterator) {
+          throw new Error(`action\u0000\n${"x".repeat(2_000)}`);
+        }
+        return Reflect.get(target, prop, receiver);
+      },
+    });
+
+    try {
+      convertActionsToAnthropicTools(
+        trappedActions as unknown as AgentActionDefinition[]
+      );
+      throw new Error("expected convertActionsToAnthropicTools to throw");
+    } catch (error) {
+      const message = String(error instanceof Error ? error.message : error);
+      expect(message).toContain("[truncated");
+      expect(message).not.toContain("\u0000");
+      expect(message).not.toContain("\n");
+      expect(message.length).toBeLessThan(700);
+    }
+  });
+});
+
+describe("convertToGeminiResponseSchema", () => {
+  it("injects placeholder properties for empty object nodes", () => {
+    const schema = z.object({
+      metadata: z.object({}),
+    });
+
+    const result = convertToGeminiResponseSchema(schema);
+    const metadata = (result.properties as Record<string, unknown>)
+      .metadata as Record<string, unknown>;
+
+    expect(metadata.type).toBe("OBJECT");
+    expect(metadata.propertyOrdering).toEqual(["_placeholder"]);
+  });
+});
diff --git a/src/llm/utils/schema-converter.ts b/src/llm/utils/schema-converter.ts
index 708c8f23..8a3eee68 100644
--- a/src/llm/utils/schema-converter.ts
+++ b/src/llm/utils/schema-converter.ts
@@ -1,5 +1,6 @@
 import { z } from "zod";
 import { AgentActionDefinition } from "@/types/agent/actions/types";
+import { formatUnknownError } from "@/utils";
 
 /**
  * Utility functions for converting Zod schemas to provider-specific formats
@@ -26,6 +27,101 @@ const THOUGHTS_DESCRIPTION =
   "Your reasoning about the current state and what needs to be done next based on the task goal and previous actions.";
 const MEMORY_DESCRIPTION =
   "A summary of successful actions completed so far and key state changes (e.g., 'Clicked login button -> login form appeared').";
+const MAX_ACTION_DIAGNOSTIC_CHARS = 400;
+const MAX_ACTION_DESCRIPTION_CHARS = 4_000;
+
+const FALLBACK_ACTION_PARAMS_SCHEMA = {
+  type: "object",
+  additionalProperties: true,
+  properties: {},
+};
+
+function truncateActionDiagnostic(value: string): string {
+  if (value.length <= MAX_ACTION_DIAGNOSTIC_CHARS) {
+    return value;
+  }
+  return `${value.slice(
+    0,
+    MAX_ACTION_DIAGNOSTIC_CHARS
+  )}... [truncated ${value.length - MAX_ACTION_DIAGNOSTIC_CHARS} chars]`;
+}
+
+function sanitizeActionDiagnostic(value: string): string {
+  if (value.length === 0) {
+    return value;
+  }
+  return Array.from(value, (char) => {
+    const code = char.charCodeAt(0);
+    return (code >= 0 && code < 32) || code === 127 ? " " : char;
+  })
+    .join("")
+    .replace(/\s+/g, " ")
+    .trim();
+}
+
+function formatActionDiagnostic(value: unknown): string {
+  const normalized = sanitizeActionDiagnostic(formatUnknownError(value));
+  const fallback = normalized.length > 0 ? normalized : "unknown error";
+  return truncateActionDiagnostic(fallback);
+}
+
+function safeReadActionField(
+  action: AgentActionDefinition,
+  field: keyof AgentActionDefinition
+): unknown {
+  try {
+    return (action as unknown as Record<string, unknown>)[field];
+  } catch (error) {
+    return `[Unreadable ${String(field)}: ${formatActionDiagnostic(error)}]`;
+  }
+}
+
+function isUnreadableFieldMarker(value: unknown): boolean {
+  return typeof value === "string" && value.startsWith("[Unreadable ");
+}
+
+function normalizeActionDescription(value: unknown): string {
+  const raw =
+    typeof value === "string"
+      ? sanitizeActionDiagnostic(value)
+      : formatActionDiagnostic(value);
+  const normalized = sanitizeActionDiagnostic(raw);
+  const fallback =
+    normalized.length > 0
+      ? normalized
+      : "Generate structured output according to the provided schema";
+  if (fallback.length <= MAX_ACTION_DESCRIPTION_CHARS) {
+    return fallback;
+  }
+  return `${fallback.slice(
+    0,
+    MAX_ACTION_DESCRIPTION_CHARS
+  )}... [truncated ${fallback.length - MAX_ACTION_DESCRIPTION_CHARS} chars]`;
+}
+
+function convertActionParamsToSchema(
+  actionParams: unknown
+): Record<string, unknown> {
+  try {
+    return z.toJSONSchema(actionParams as z.ZodTypeAny, {
+      target: "draft-4",
+      io: "output",
+    });
+  } catch {
+    return { ...FALLBACK_ACTION_PARAMS_SCHEMA };
+  }
+}
+
+function safeReadActionParamsDescription(actionParams: unknown): unknown {
+  if (!actionParams || typeof actionParams !== "object") {
+    return undefined;
+  }
+  try {
+    return (actionParams as Record<string, unknown>).description;
+  } catch (error) {
+    return `[Unreadable actionParams.description: ${formatActionDiagnostic(error)}]`;
+  }
+}
 
 /**
  * Convert a simple Zod schema to an Anthropic tool (for non-agent use cases)
@@ -67,15 +163,43 @@ export function createAnthropicToolChoice(
 export function convertActionsToAnthropicTools(
   actions: AgentActionDefinition[]
 ): Array<Record<string, unknown>> {
-  return actions.map((action) => {
-    const paramsSchema = z.toJSONSchema(action.actionParams, {
-      target: "draft-4",
-      io: "output",
-    });
+  let actionEntries: AgentActionDefinition[];
+  try {
+    actionEntries = Array.from(actions);
+  } catch (error) {
+    throw new Error(
+      `[LLM][SchemaConverter] Invalid action definitions payload: ${formatActionDiagnostic(
+        error
+      )}`
+    );
+  }
+
+  return actionEntries.map((action, index) => {
+    const actionTypeValue = safeReadActionField(action, "type");
+    const actionType =
+      typeof actionTypeValue === "string" &&
+      actionTypeValue.length > 0 &&
+      !isUnreadableFieldMarker(actionTypeValue)
+        ? actionTypeValue
+        : `unknown_action_${index + 1}`;
+    const actionParams = safeReadActionField(action, "actionParams");
+    const paramsSchema = convertActionParamsToSchema(actionParams);
+    const toolNameValue = safeReadActionField(action, "toolName");
+    const toolName =
+      typeof toolNameValue === "string" &&
+      toolNameValue.length > 0 &&
+      !isUnreadableFieldMarker(toolNameValue)
+        ? toolNameValue
+        : actionType;
 
     // Create enhanced description with structure example
-    const baseDescription =
-      action.toolDescription ?? action.actionParams.description;
+    const toolDescription = safeReadActionField(action, "toolDescription");
+    const actionParamsDescription = safeReadActionParamsDescription(actionParams);
+    const baseDescription = normalizeActionDescription(
+      typeof toolDescription === "undefined"
+        ? actionParamsDescription
+        : toolDescription
+    );
     const enhancedDescription = `${baseDescription}
 
 IMPORTANT: Response must have this exact structure:
@@ -83,7 +207,7 @@ IMPORTANT: Response must have this exact structure:
   "thoughts": "your reasoning",
   "memory": "summary of actions",
   "action": {
-    "type": "${action.type}",
+    "type": "${actionType}",
     "params": { ...action parameters here... }
   }
 }
@@ -91,7 +215,7 @@ IMPORTANT: Response must have this exact structure:
 Do NOT put params directly at root level. They MUST be nested inside action.params.`;
 
     return {
-      name: action.toolName ?? action.type,
+      name: toolName,
       description: enhancedDescription,
       input_schema: {
         type: "object",
@@ -107,17 +231,17 @@ Do NOT put params directly at root level. They MUST be nested inside action.para
           },
           action: {
             type: "object",
-            description: `The action object. MUST contain 'type' field set to "${action.type}" and 'params' field with the action parameters.`,
+            description: `The action object. MUST contain 'type' field set to "${actionType}" and 'params' field with the action parameters.`,
             additionalProperties: false,
             properties: {
               type: {
                 type: "string",
-                const: action.type,
-                description: `Must be exactly "${action.type}"`,
+                const: actionType,
+                description: `Must be exactly "${actionType}"`,
               },
               params: {
                 ...paramsSchema,
-                description: `Parameters for the ${action.type} action. These must be nested here, not at the root level.`,
+                description: `Parameters for the ${actionType} action. These must be nested here, not at the root level.`,
               },
             },
             required: ["type", "params"],
diff --git a/src/llm/utils/structured-response.test.ts b/src/llm/utils/structured-response.test.ts
new file mode 100644
index 00000000..bef54657
--- /dev/null
+++ b/src/llm/utils/structured-response.test.ts
@@ -0,0 +1,63 @@
+import { z } from "zod";
+import { parseStructuredResponse } from "@/llm/utils/structured-response";
+
+describe("parseStructuredResponse", () => {
+  const schema = z.object({
+    action: z.string(),
+  });
+
+  it("parses valid structured JSON payloads", () => {
+    const result = parseStructuredResponse('{"action":"click"}', schema);
+    expect(result.rawText).toBe('{"action":"click"}');
+    expect(result.parsed).toEqual({ action: "click" });
+  });
+
+  it("accepts BOM-prefixed JSON payloads", () => {
+    const result = parseStructuredResponse("\uFEFF{\"action\":\"click\"}", schema);
+    expect(result.parsed).toEqual({ action: "click" });
+  });
+
+  it("returns null parsed output for empty payloads", () => {
+    const result = parseStructuredResponse("   ", schema);
+    expect(result.rawText).toBe("   ");
+    expect(result.parsed).toBeNull();
+  });
+
+  it("formats non-string payloads for diagnostics without parsing", () => {
+    const result = parseStructuredResponse({ ok: true }, schema);
+    expect(result.rawText).toBe('{"ok":true}');
+    expect(result.parsed).toBeNull();
+  });
+
+  it("truncates oversized non-string diagnostics", () => {
+    const result = parseStructuredResponse(
+      { payload: "x".repeat(120_000) },
+      schema
+    );
+    expect(result.rawText).toContain("[truncated");
+    expect(result.rawText.length).toBeLessThan(101_000);
+    expect(result.parsed).toBeNull();
+  });
+
+  it("sanitizes control characters in non-string diagnostics", () => {
+    const result = parseStructuredResponse(
+      new Error("bad\u0000\npayload"),
+      schema
+    );
+    expect(result.rawText).toBe("bad \npayload");
+    expect(result.rawText).not.toContain("\u0000");
+    expect(result.parsed).toBeNull();
+  });
+
+  it("returns null parsed output when schema validation fails", () => {
+    const result = parseStructuredResponse('{"action":1}', schema);
+    expect(result.parsed).toBeNull();
+  });
+
+  it("skips oversized payload parsing safely", () => {
+    const huge = `"${"x".repeat(120_000)}"`;
+    const result = parseStructuredResponse(huge, z.string());
+    expect(result.rawText).toContain("[truncated");
+    expect(result.parsed).toBeNull();
+  });
+});
diff --git a/src/llm/utils/structured-response.ts b/src/llm/utils/structured-response.ts
new file mode 100644
index 00000000..7dfd4fbf
--- /dev/null
+++ b/src/llm/utils/structured-response.ts
@@ -0,0 +1,79 @@
+import { z } from "zod";
+import { HyperAgentStructuredResult } from "@/llm/types";
+import { parseJsonMaybe } from "@/llm/utils/safe-json";
+import { formatUnknownError } from "@/utils";
+
+const MAX_STRUCTURED_RAW_TEXT_CHARS = 100_000;
+
+function truncateStructuredRawText(value: string): string {
+  if (value.length <= MAX_STRUCTURED_RAW_TEXT_CHARS) {
+    return value;
+  }
+  return `${value.slice(
+    0,
+    MAX_STRUCTURED_RAW_TEXT_CHARS
+  )}... [truncated ${value.length - MAX_STRUCTURED_RAW_TEXT_CHARS} chars]`;
+}
+
+function sanitizeStructuredRawText(value: string): string {
+  if (value.length === 0) {
+    return value;
+  }
+  return Array.from(value, (char) => {
+    const code = char.charCodeAt(0);
+    return (code >= 0 && code < 32 && code !== 9 && code !== 10) || code === 127
+      ? " "
+      : char;
+  }).join("");
+}
+
+export function parseStructuredResponse<TSchema extends z.ZodTypeAny>(
+  rawText: unknown,
+  schema: TSchema
+): HyperAgentStructuredResult<TSchema> {
+  if (typeof rawText !== "string") {
+    return {
+      rawText: truncateStructuredRawText(
+        sanitizeStructuredRawText(formatUnknownError(rawText))
+      ),
+      parsed: null,
+    };
+  }
+
+  const text = rawText;
+  const normalizedRawText = truncateStructuredRawText(text);
+  if (text.trim().length === 0) {
+    return {
+      rawText: normalizedRawText,
+      parsed: null,
+    };
+  }
+
+  let parsed: unknown;
+  try {
+    parsed = parseJsonMaybe(text);
+  } catch {
+    return {
+      rawText: normalizedRawText,
+      parsed: null,
+    };
+  }
+  if (typeof parsed === "string") {
+    return {
+      rawText: normalizedRawText,
+      parsed: null,
+    };
+  }
+
+  try {
+    return {
+      rawText: normalizedRawText,
+      parsed: schema.parse(parsed),
+    };
+  } catch {
+    return {
+      rawText: normalizedRawText,
+      parsed: null,
+    };
+  }
+}
diff --git a/src/types/agent/actions/types.ts b/src/types/agent/actions/types.ts
index 54ed7b51..7defbab7 100644
--- a/src/types/agent/actions/types.ts
+++ b/src/types/agent/actions/types.ts
@@ -16,6 +16,7 @@ export interface ActionContext {
   mcpClient?: MCPClient;
   debug?: boolean;
   cdpActions?: boolean;
+  filterAdTrackingFrames?: boolean;
   invalidateDomCache: () => void;
   cdp?: {
     resolveElement: typeof import("@/cdp").resolveElement;
@@ -31,18 +32,18 @@ export interface ActionOutput {
   success: boolean;
   message: string;
   extract?: object;
-  debug?: any;
+  debug?: unknown;
 }
 
 export type ActionSchemaType = z.ZodObject<{
   type: z.ZodLiteral<string>;
-  params: z.ZodObject<any>;
+  params: z.ZodTypeAny;
 }>;
 
 export type ActionType = z.infer<ActionSchemaType>;
 
 export interface AgentActionDefinition<
-  T extends z.ZodType<any> = z.ZodType<any>,
+  T extends z.ZodTypeAny = z.ZodTypeAny,
 > {
   readonly type: string;
   readonly toolName?: string;
diff --git a/src/types/agent/types.ts b/src/types/agent/types.ts
index d846f659..50fe7163 100644
--- a/src/types/agent/types.ts
+++ b/src/types/agent/types.ts
@@ -1,10 +1,14 @@
 import { z } from "zod";
-import { ActionOutput } from "./actions/types";
+import { ActionOutput, ActionType } from "./actions/types";
 import { Page } from "playwright-core";
 import { ErrorEmitter } from "@/utils";
+import type { HyperAgentLLM } from "@/llm/types";
+import type { MCPClient } from "@/agent/mcp/client";
 
 export const AgentOutputFn = (
-  actionsSchema: z.ZodUnion<readonly [z.ZodType<any>, ...z.ZodType<any>[]]>
+  actionsSchema: z.ZodUnion<
+    readonly [z.ZodTypeAny, ...z.ZodTypeAny[]]
+  >
 ) =>
   z.object({
     thoughts: z
@@ -20,7 +24,11 @@ export const AgentOutputFn = (
     action: actionsSchema,
   });
 
-export type AgentOutput = z.infer<ReturnType<typeof AgentOutputFn>>;
+export interface AgentOutput {
+  thoughts: string;
+  memory: string;
+  action: ActionType;
+}
 
 export interface AgentStep {
   idx: number;
@@ -91,18 +99,68 @@ export interface ActionCacheReplayResult {
 export interface RunFromActionCacheParams {
   maxXPathRetries?: number;
   debug?: boolean;
+  /**
+   * Override CDP execution for this replay.
+   */
+  cdpActions?: boolean;
+  /**
+   * Override ad/tracking iframe filtering for this replay.
+   */
+  filterAdTrackingFrames?: boolean;
 }
 
-export interface TaskParams {
-  maxSteps?: number;
+export interface AgentExecutionHooks {
   debugDir?: string;
-  outputSchema?: z.ZodType<any>;
   onStep?: (step: AgentStep) => Promise<void> | void;
   onComplete?: (output: TaskOutput) => Promise<void> | void;
   debugOnAgentOutput?: (step: AgentOutput) => void;
+}
+
+export interface TaskParams extends AgentExecutionHooks {
+  maxSteps?: number;
+  outputSchema?: z.ZodType<unknown>;
   enableVisualMode?: boolean;
   useDomCache?: boolean;
   enableDomStreaming?: boolean;
+  /**
+   * Override CDP execution for this task run.
+   */
+  cdpActions?: boolean;
+  /**
+   * Override ad/tracking iframe filtering for this task run.
+   */
+  filterAdTrackingFrames?: boolean;
+}
+
+export interface PerformTaskParams {
+  /**
+   * Maximum attempts for finding and executing an element action.
+   */
+  maxElementRetries?: number;
+  /**
+   * Delay between element-finding retries in milliseconds.
+   */
+  retryDelayMs?: number;
+  /**
+   * Maximum retries when tab/page context switches mid-action.
+   */
+  maxContextSwitchRetries?: number;
+  /**
+   * Delay between retries caused by tab/page context switches in milliseconds.
+   */
+  contextSwitchRetryDelayMs?: number;
+  /**
+   * @deprecated use maxElementRetries instead.
+   */
+  maxSteps?: number;
+  /**
+   * Override CDP execution for this single action.
+   */
+  cdpActions?: boolean;
+  /**
+   * Override ad/tracking iframe filtering for this single action.
+   */
+  filterAdTrackingFrames?: boolean;
 }
 
 export interface TaskOutput {
@@ -123,6 +181,7 @@ export interface Task {
   pause: () => TaskStatus;
   resume: () => TaskStatus;
   cancel: () => TaskStatus;
+  result: Promise<AgentTaskOutput>;
   emitter: ErrorEmitter;
 }
 
@@ -154,10 +213,11 @@ export interface TaskState {
 export interface AgentDeps {
   debug?: boolean;
   tokenLimit: number;
-  llm: any;
-  mcpClient: any;
+  llm: HyperAgentLLM;
+  mcpClient?: MCPClient;
   variables: Array<{ key: string; value: string; description: string }>;
   cdpActionsEnabled?: boolean;
+  filterAdTrackingFrames?: boolean;
 }
 export interface HyperVariable {
   key: string;
@@ -172,6 +232,14 @@ export interface PerformOptions {
   frameIndex?: number | null;
   performInstruction?: string | null;
   maxSteps?: number;
+  /**
+   * Override CDP execution for this helper replay call.
+   */
+  cdpActions?: boolean;
+  /**
+   * Override ad/tracking iframe filtering for this helper replay call.
+   */
+  filterAdTrackingFrames?: boolean;
 }
 
 export interface HyperPage extends Page {
@@ -222,20 +290,26 @@ export interface HyperPage extends Page {
    * Best for: Single actions like "click login", "fill email with test@example.com"
    * Mode: Always a11y (accessibility tree, faster and more reliable)
    */
-  perform: (instruction: string, params?: TaskParams) => Promise<TaskOutput>;
+  perform: (
+    instruction: string,
+    params?: PerformTaskParams
+  ) => Promise<TaskOutput>;
 
   /**
    * @deprecated: use perform() instead.
    * Execute a single granular action using a11y mode
    */
-  aiAction: (instruction: string, params?: TaskParams) => Promise<TaskOutput>;
+  aiAction: (
+    instruction: string,
+    params?: PerformTaskParams
+  ) => Promise<TaskOutput>;
 
   aiAsync: (task: string, params?: TaskParams) => Promise<Task>;
-  extract<T extends z.ZodType<any> | undefined = undefined>(
+  extract<T extends z.ZodType<unknown> | undefined = undefined>(
     task?: string,
     outputSchema?: T,
     params?: Omit<TaskParams, "outputSchema">
-  ): Promise<T extends z.ZodType<any> ? z.infer<T> : string>;
+  ): Promise<T extends z.ZodType<unknown> ? z.infer<T> : string>;
   getActionCache: (taskId: string) => ActionCacheOutput | null;
   runFromActionCache: (
     cache: ActionCacheOutput,
diff --git a/src/types/config.ts b/src/types/config.ts
index 67c00dba..d0e0103a 100644
--- a/src/types/config.ts
+++ b/src/types/config.ts
@@ -94,6 +94,11 @@ export interface HyperAgentConfig<T extends BrowserProviders = "Local"> {
    * Configuration for agent actions
    */
   cdpActions?: boolean;
+  /**
+   * Enable/disable heuristic filtering of likely ad/tracking iframes during
+   * CDP frame discovery. Defaults to true.
+   */
+  filterAdTrackingFrames?: boolean;
   debugOptions?: {
     cdpSessions?: boolean;
     traceWait?: boolean;
diff --git a/src/types/index.ts b/src/types/index.ts
index 9177fa78..68868971 100644
--- a/src/types/index.ts
+++ b/src/types/index.ts
@@ -17,13 +17,17 @@ import {
   ActionCacheReplayResult,
   ActionCacheReplayStepResult,
   RunFromActionCacheParams,
+  PerformTaskParams,
   TaskParams,
   TaskOutput,
+  AgentTaskOutput,
   Task,
   TaskStatus,
   TaskState,
   endTaskStatuses,
   PerformOptions,
+  HyperPage,
+  HyperVariable,
 } from "./agent/types";
 
 // Config Types
@@ -50,12 +54,16 @@ export {
   ActionCacheReplayResult,
   ActionCacheReplayStepResult,
   RunFromActionCacheParams,
+  PerformTaskParams,
   TaskParams,
   TaskOutput,
+  AgentTaskOutput,
   Task,
   TaskStatus,
   TaskState,
   PerformOptions,
+  HyperPage,
+  HyperVariable,
 
   // Config Types
   MCPServerConfig,
diff --git a/src/utils/debugWriter.test.ts b/src/utils/debugWriter.test.ts
new file mode 100644
index 00000000..2a3819ec
--- /dev/null
+++ b/src/utils/debugWriter.test.ts
@@ -0,0 +1,359 @@
+import fs from "node:fs";
+import os from "node:os";
+import path from "node:path";
+import {
+  resetDebugSession,
+  writePerformDebug,
+  writeAiActionDebug,
+  type DebugData,
+} from "@/utils/debugWriter";
+
+describe("writeAiActionDebug", () => {
+  beforeEach(() => {
+    resetDebugSession();
+  });
+
+  it("writes debug artifacts via canonical writePerformDebug API", async () => {
+    const tempDir = await fs.promises.mkdtemp(
+      path.join(os.tmpdir(), "hyperagent-debug-writer-")
+    );
+    const debugData: DebugData = {
+      instruction: "click login",
+      url: "https://example.com",
+      timestamp: new Date().toISOString(),
+      domElementCount: 5,
+      domTree: "dom tree",
+      success: true,
+    };
+
+    try {
+      const debugDir = await writePerformDebug(debugData, tempDir);
+      const metadata = await fs.promises.readFile(
+        path.join(debugDir, "metadata.json"),
+        "utf-8"
+      );
+
+      expect(debugDir.endsWith("action-0")).toBe(true);
+      expect(metadata).toContain("click login");
+    } finally {
+      await fs.promises.rm(tempDir, { recursive: true, force: true });
+    }
+  });
+
+  it("serializes circular and bigint payloads without throwing", async () => {
+    const tempDir = await fs.promises.mkdtemp(
+      path.join(os.tmpdir(), "hyperagent-debug-writer-")
+    );
+    const circular: { self?: unknown } = {};
+    circular.self = circular;
+
+    const debugData: DebugData = {
+      instruction: "click login",
+      url: "https://example.com",
+      timestamp: new Date().toISOString(),
+      domElementCount: 5,
+      domTree: "dom tree",
+      llmResponse: {
+        rawText: "{}",
+        parsed: circular,
+      },
+      foundElement: {
+        elementId: "0-1",
+        method: "click",
+        arguments: [1n],
+      },
+      success: true,
+    };
+
+    try {
+      const debugDir = await writeAiActionDebug(debugData, tempDir);
+      const llmResponseJson = await fs.promises.readFile(
+        path.join(debugDir, "llm-response.json"),
+        "utf-8"
+      );
+      const foundElementJson = await fs.promises.readFile(
+        path.join(debugDir, "found-element.json"),
+        "utf-8"
+      );
+
+      expect(llmResponseJson).toContain('"[Circular]"');
+      expect(foundElementJson).toContain('"1n"');
+    } finally {
+      await fs.promises.rm(tempDir, { recursive: true, force: true });
+    }
+  });
+
+  it("continues writing debug artifacts when one file write fails", async () => {
+    const tempDir = await fs.promises.mkdtemp(
+      path.join(os.tmpdir(), "hyperagent-debug-writer-")
+    );
+    const warnSpy = jest.spyOn(console, "warn").mockImplementation(() => {});
+    const originalWrite = fs.writeFileSync;
+    let hasThrown = false;
+    const writeSpy = jest.spyOn(fs, "writeFileSync").mockImplementation(
+      (
+        filePath: fs.PathOrFileDescriptor,
+        data: string | NodeJS.ArrayBufferView,
+        options?: fs.WriteFileOptions
+      ) => {
+        if (!hasThrown && String(filePath).endsWith("metadata.json")) {
+          hasThrown = true;
+          throw { reason: "disk once failure" };
+        }
+        return originalWrite(filePath, data, options);
+      }
+    );
+
+    const debugData: DebugData = {
+      instruction: "click login",
+      url: "https://example.com",
+      timestamp: new Date().toISOString(),
+      domElementCount: 5,
+      domTree: "dom tree",
+      llmResponse: {
+        rawText: "{}",
+        parsed: { ok: true },
+      },
+      success: true,
+    };
+
+    try {
+      const debugDir = await writeAiActionDebug(debugData, tempDir);
+      const domTree = await fs.promises.readFile(
+        path.join(debugDir, "dom-tree.txt"),
+        "utf-8"
+      );
+      const llmText = await fs.promises.readFile(
+        path.join(debugDir, "llm-response.txt"),
+        "utf-8"
+      );
+
+      expect(domTree).toBe("dom tree");
+      expect(llmText).toBe("{}");
+      expect(warnSpy).toHaveBeenCalledWith(
+        expect.stringContaining("[debugWriter] Failed to write")
+      );
+    } finally {
+      writeSpy.mockRestore();
+      warnSpy.mockRestore();
+      await fs.promises.rm(tempDir, { recursive: true, force: true });
+    }
+  });
+
+  it("throws readable error when debug directory creation fails", async () => {
+    const tempDir = await fs.promises.mkdtemp(
+      path.join(os.tmpdir(), "hyperagent-debug-writer-")
+    );
+    const mkdirSpy = jest.spyOn(fs, "mkdirSync").mockImplementation(() => {
+      throw { reason: "mkdir denied" };
+    });
+    const debugData: DebugData = {
+      instruction: "click login",
+      url: "https://example.com",
+      timestamp: new Date().toISOString(),
+      domElementCount: 5,
+      domTree: "dom tree",
+      success: true,
+    };
+
+    try {
+      await expect(writeAiActionDebug(debugData, tempDir)).rejects.toThrow(
+        '[debugWriter] Failed to create debug directory'
+      );
+      await expect(writeAiActionDebug(debugData, tempDir)).rejects.toThrow(
+        '{"reason":"mkdir denied"}'
+      );
+    } finally {
+      mkdirSpy.mockRestore();
+      await fs.promises.rm(tempDir, { recursive: true, force: true });
+    }
+  });
+
+  it("sanitizes and truncates oversized directory creation diagnostics", async () => {
+    const tempDir = await fs.promises.mkdtemp(
+      path.join(os.tmpdir(), "hyperagent-debug-writer-")
+    );
+    const mkdirSpy = jest.spyOn(fs, "mkdirSync").mockImplementation(() => {
+      throw new Error(`mkdir\u0000\n${"x".repeat(10_000)}`);
+    });
+    const debugData: DebugData = {
+      instruction: "click login",
+      url: "https://example.com",
+      timestamp: new Date().toISOString(),
+      domElementCount: 5,
+      domTree: "dom tree",
+      success: true,
+    };
+
+    try {
+      await writeAiActionDebug(debugData, tempDir)
+        .then(() => {
+          throw new Error("expected writeAiActionDebug to reject");
+        })
+        .catch((error) => {
+          const message = String(error instanceof Error ? error.message : error);
+          expect(message).toContain("[truncated");
+          expect(message).not.toContain("\u0000");
+          expect(message).not.toContain("\n");
+          expect(message.length).toBeLessThan(800);
+        });
+    } finally {
+      mkdirSpy.mockRestore();
+      await fs.promises.rm(tempDir, { recursive: true, force: true });
+    }
+  });
+
+  it("does not consume action counter when directory creation fails", async () => {
+    const tempDir = await fs.promises.mkdtemp(
+      path.join(os.tmpdir(), "hyperagent-debug-writer-")
+    );
+    const originalMkdir = fs.mkdirSync;
+    let hasThrown = false;
+    const mkdirSpy = jest.spyOn(fs, "mkdirSync").mockImplementation(
+      (
+        targetPath: fs.PathLike,
+        options?: fs.Mode | fs.MakeDirectoryOptions | null
+      ) => {
+        if (!hasThrown) {
+          hasThrown = true;
+          throw { reason: "mkdir denied once" };
+        }
+        return originalMkdir(targetPath, options);
+      }
+    );
+    const debugData: DebugData = {
+      instruction: "click login",
+      url: "https://example.com",
+      timestamp: new Date().toISOString(),
+      domElementCount: 5,
+      domTree: "dom tree",
+      success: true,
+    };
+
+    try {
+      await expect(writeAiActionDebug(debugData, tempDir)).rejects.toThrow(
+        "mkdir denied once"
+      );
+      const debugDir = await writeAiActionDebug(debugData, tempDir);
+      expect(debugDir.endsWith("action-0")).toBe(true);
+    } finally {
+      mkdirSpy.mockRestore();
+      await fs.promises.rm(tempDir, { recursive: true, force: true });
+    }
+  });
+
+  it("normalizes trap-prone debug payload fields without throwing", async () => {
+    const tempDir = await fs.promises.mkdtemp(
+      path.join(os.tmpdir(), "hyperagent-debug-writer-")
+    );
+
+    const trappedData = {
+      get instruction() {
+        throw new Error("instruction trap");
+      },
+      get url() {
+        throw new Error("url trap");
+      },
+      timestamp: new Date().toISOString(),
+      domElementCount: 5,
+      domTree: "dom tree",
+      llmResponse: {
+        get rawText() {
+          throw new Error("rawText trap");
+        },
+        parsed: { ok: true },
+      },
+      success: true,
+    } as unknown as DebugData;
+
+    try {
+      const debugDir = await writeAiActionDebug(trappedData, tempDir);
+      const metadata = await fs.promises.readFile(
+        path.join(debugDir, "metadata.json"),
+        "utf-8"
+      );
+      const llmText = await fs.promises.readFile(
+        path.join(debugDir, "llm-response.txt"),
+        "utf-8"
+      );
+
+      expect(metadata).toContain("unknown instruction");
+      expect(metadata).toContain("about:blank");
+      expect(llmText).toBe("");
+    } finally {
+      await fs.promises.rm(tempDir, { recursive: true, force: true });
+    }
+  });
+
+  it("ignores non-buffer screenshot payloads and truncates oversized text", async () => {
+    const tempDir = await fs.promises.mkdtemp(
+      path.join(os.tmpdir(), "hyperagent-debug-writer-")
+    );
+    const hugeText = "x".repeat(250_000);
+    const debugData = {
+      instruction: "click login",
+      url: "https://example.com",
+      timestamp: new Date().toISOString(),
+      domElementCount: 5,
+      domTree: hugeText,
+      screenshot: "not-a-buffer",
+      llmResponse: {
+        rawText: hugeText,
+        parsed: { ok: true },
+      },
+      success: true,
+    } as unknown as DebugData;
+
+    try {
+      const debugDir = await writeAiActionDebug(debugData, tempDir);
+      const domTree = await fs.promises.readFile(
+        path.join(debugDir, "dom-tree.txt"),
+        "utf-8"
+      );
+      const screenshotPath = path.join(debugDir, "screenshot.png");
+
+      expect(domTree).toContain("[truncated");
+      await expect(fs.promises.stat(screenshotPath)).rejects.toThrow();
+    } finally {
+      await fs.promises.rm(tempDir, { recursive: true, force: true });
+    }
+  });
+
+  it("bounds non-serializable debug payload diagnostics", async () => {
+    const tempDir = await fs.promises.mkdtemp(
+      path.join(os.tmpdir(), "hyperagent-debug-writer-")
+    );
+    const trapParsed = {
+      toJSON: () => {
+        throw new Error(`serialize\u0000\n${"x".repeat(10_000)}`);
+      },
+    };
+    const debugData: DebugData = {
+      instruction: "click login",
+      url: "https://example.com",
+      timestamp: new Date().toISOString(),
+      domElementCount: 5,
+      domTree: "dom tree",
+      llmResponse: {
+        rawText: "{}",
+        parsed: trapParsed,
+      },
+      success: true,
+    };
+
+    try {
+      const debugDir = await writeAiActionDebug(debugData, tempDir);
+      const llmResponseJson = await fs.promises.readFile(
+        path.join(debugDir, "llm-response.json"),
+        "utf-8"
+      );
+
+      expect(llmResponseJson).toContain("__nonSerializable");
+      expect(llmResponseJson).not.toContain("\u0000");
+      expect(llmResponseJson).not.toContain("serialize\u0000");
+      expect(llmResponseJson.length).toBeLessThan(900);
+    } finally {
+      await fs.promises.rm(tempDir, { recursive: true, force: true });
+    }
+  });
+});
diff --git a/src/utils/debugWriter.ts b/src/utils/debugWriter.ts
index 95b933ab..baea7d40 100644
--- a/src/utils/debugWriter.ts
+++ b/src/utils/debugWriter.ts
@@ -1,10 +1,244 @@
 /**
- * Debug writer utility for aiAction debugging
+ * Debug writer utility for single-action debugging
  * Creates a debug folder structure similar to the agent task debugging
  */
 
-import fs from 'fs';
-import path from 'path';
+import fs from "fs";
+import path from "path";
+import { formatUnknownError } from "./format-unknown-error";
+
+interface FoundElementDebugData {
+  elementId: string;
+  method: string;
+  arguments: unknown[];
+  xpath?: string;
+}
+
+const MAX_DEBUG_TEXT_CHARS = 200_000;
+const MAX_DEBUG_ELEMENTS = 500;
+const MAX_DEBUG_FRAME_ITEMS = 100;
+const MAX_DEBUG_WRITER_DIAGNOSTIC_CHARS = 500;
+
+function sanitizeDebugWriterDiagnostic(value: string): string {
+  if (value.length === 0) {
+    return value;
+  }
+  return Array.from(value, (char) => {
+    const code = char.charCodeAt(0);
+    if (code === 9 || code === 10) {
+      return char;
+    }
+    return (code >= 0 && code < 32) || code === 127 ? " " : char;
+  })
+    .join("")
+    .replace(/\s+/g, " ")
+    .trim();
+}
+
+function formatDebugWriterDiagnostic(value: unknown): string {
+  const normalized = sanitizeDebugWriterDiagnostic(formatUnknownError(value));
+  const fallback = normalized.length > 0 ? normalized : "unknown error";
+  if (fallback.length <= MAX_DEBUG_WRITER_DIAGNOSTIC_CHARS) {
+    return fallback;
+  }
+  const omitted = fallback.length - MAX_DEBUG_WRITER_DIAGNOSTIC_CHARS;
+  return `${fallback.slice(
+    0,
+    MAX_DEBUG_WRITER_DIAGNOSTIC_CHARS
+  )}... [truncated ${omitted} chars]`;
+}
+
+function safeReadRecordField(value: unknown, key: string): unknown {
+  if (!value || (typeof value !== "object" && typeof value !== "function")) {
+    return undefined;
+  }
+  try {
+    return (value as Record<string, unknown>)[key];
+  } catch {
+    return undefined;
+  }
+}
+
+function normalizeDebugText(
+  value: unknown,
+  fallback: string,
+  maxChars: number = MAX_DEBUG_TEXT_CHARS
+): string {
+  const raw =
+    typeof value === "string"
+      ? value
+      : value == null
+        ? fallback
+        : formatUnknownError(value);
+  const normalized = raw.replace(/\r\n?/g, "\n").trim();
+  if (normalized.length === 0) {
+    return fallback;
+  }
+  if (normalized.length <= maxChars) {
+    return normalized;
+  }
+  const omitted = normalized.length - maxChars;
+  return `${normalized.slice(0, maxChars)}\n... [truncated ${omitted} chars]`;
+}
+
+function normalizeDebugData(input: DebugData): DebugData {
+  const normalizedInstruction = normalizeDebugText(
+    safeReadRecordField(input, "instruction"),
+    "unknown instruction"
+  );
+  const normalizedUrl = normalizeDebugText(
+    safeReadRecordField(input, "url"),
+    "about:blank"
+  );
+  const normalizedTimestamp = normalizeDebugText(
+    safeReadRecordField(input, "timestamp"),
+    new Date().toISOString()
+  );
+  const domElementCountValue = safeReadRecordField(input, "domElementCount");
+  const normalizedDomElementCount =
+    typeof domElementCountValue === "number" &&
+    Number.isFinite(domElementCountValue) &&
+    domElementCountValue >= 0
+      ? Math.floor(domElementCountValue)
+      : 0;
+  const normalizedDomTree = normalizeDebugText(
+    safeReadRecordField(input, "domTree"),
+    ""
+  );
+  const success = safeReadRecordField(input, "success") === true;
+
+  const screenshot = safeReadRecordField(input, "screenshot");
+  const normalizedScreenshot = Buffer.isBuffer(screenshot) ? screenshot : undefined;
+
+  const foundElementRaw = safeReadRecordField(input, "foundElement");
+  let foundElement: FoundElementDebugData | undefined;
+  if (foundElementRaw && typeof foundElementRaw === "object") {
+    const args = safeReadRecordField(foundElementRaw, "arguments");
+    foundElement = {
+      elementId: normalizeDebugText(
+        safeReadRecordField(foundElementRaw, "elementId"),
+        "unknown-element",
+        500
+      ),
+      method: normalizeDebugText(
+        safeReadRecordField(foundElementRaw, "method"),
+        "unknown-method",
+        200
+      ),
+      arguments: Array.isArray(args) ? Array.from(args).slice(0, 50) : [],
+      xpath:
+        typeof safeReadRecordField(foundElementRaw, "xpath") === "string"
+          ? normalizeDebugText(safeReadRecordField(foundElementRaw, "xpath"), "")
+          : undefined,
+    };
+  }
+
+  const llmResponseRaw = safeReadRecordField(input, "llmResponse");
+  const llmResponse =
+    llmResponseRaw && typeof llmResponseRaw === "object"
+      ? {
+          rawText: normalizeDebugText(
+            safeReadRecordField(llmResponseRaw, "rawText"),
+            ""
+          ),
+          parsed: safeReadRecordField(llmResponseRaw, "parsed"),
+        }
+      : undefined;
+
+  let availableElements: DebugData["availableElements"];
+  const availableElementsRaw = safeReadRecordField(input, "availableElements");
+  if (Array.isArray(availableElementsRaw)) {
+    availableElements = availableElementsRaw.slice(0, MAX_DEBUG_ELEMENTS).map((entry) => ({
+      id: normalizeDebugText(safeReadRecordField(entry, "id"), "unknown-id", 200),
+      role: normalizeDebugText(
+        safeReadRecordField(entry, "role"),
+        "unknown-role",
+        100
+      ),
+      label: normalizeDebugText(
+        safeReadRecordField(entry, "label"),
+        "",
+        5_000
+      ),
+    }));
+  }
+
+  const errorRaw = safeReadRecordField(input, "error");
+  const error =
+    errorRaw && typeof errorRaw === "object"
+      ? {
+          message: normalizeDebugText(
+            safeReadRecordField(errorRaw, "message"),
+            "unknown error",
+            10_000
+          ),
+          stack:
+            typeof safeReadRecordField(errorRaw, "stack") === "string"
+              ? normalizeDebugText(safeReadRecordField(errorRaw, "stack"), "", 20_000)
+              : undefined,
+        }
+      : undefined;
+
+  let frameDebugInfo: DebugData["frameDebugInfo"];
+  const frameInfoRaw = safeReadRecordField(input, "frameDebugInfo");
+  if (Array.isArray(frameInfoRaw)) {
+    frameDebugInfo = frameInfoRaw.slice(0, MAX_DEBUG_FRAME_ITEMS).map((frame) => ({
+      frameIndex:
+        typeof safeReadRecordField(frame, "frameIndex") === "number"
+          ? (safeReadRecordField(frame, "frameIndex") as number)
+          : -1,
+      frameUrl: normalizeDebugText(safeReadRecordField(frame, "frameUrl"), "unknown"),
+      totalNodes:
+        typeof safeReadRecordField(frame, "totalNodes") === "number"
+          ? (safeReadRecordField(frame, "totalNodes") as number)
+          : 0,
+      treeElementCount:
+        typeof safeReadRecordField(frame, "treeElementCount") === "number"
+          ? (safeReadRecordField(frame, "treeElementCount") as number)
+          : 0,
+      interactiveCount:
+        typeof safeReadRecordField(frame, "interactiveCount") === "number"
+          ? (safeReadRecordField(frame, "interactiveCount") as number)
+          : 0,
+      sampleNodes: Array.isArray(safeReadRecordField(frame, "sampleNodes"))
+        ? (safeReadRecordField(frame, "sampleNodes") as unknown[]).slice(0, 100).map((node) => ({
+            role:
+              typeof safeReadRecordField(node, "role") === "string"
+                ? (safeReadRecordField(node, "role") as string)
+                : undefined,
+            name:
+              typeof safeReadRecordField(node, "name") === "string"
+                ? (safeReadRecordField(node, "name") as string)
+                : undefined,
+            nodeId:
+              typeof safeReadRecordField(node, "nodeId") === "string"
+                ? (safeReadRecordField(node, "nodeId") as string)
+                : undefined,
+            ignored: safeReadRecordField(node, "ignored") === true,
+            childIds:
+              typeof safeReadRecordField(node, "childIds") === "number"
+                ? (safeReadRecordField(node, "childIds") as number)
+                : undefined,
+          }))
+        : undefined,
+    }));
+  }
+
+  return {
+    instruction: normalizedInstruction,
+    url: normalizedUrl,
+    timestamp: normalizedTimestamp,
+    domElementCount: normalizedDomElementCount,
+    domTree: normalizedDomTree,
+    screenshot: normalizedScreenshot,
+    foundElement,
+    availableElements,
+    llmResponse,
+    error,
+    success,
+    frameDebugInfo,
+  };
+}
 
 export interface DebugData {
   instruction: string;
@@ -13,12 +247,7 @@ export interface DebugData {
   domElementCount: number;
   domTree: string;
   screenshot?: Buffer;
-  foundElement?: {
-    elementId: string;
-    method: string;
-    arguments: any[];
-    xpath?: string;
-  };
+  foundElement?: FoundElementDebugData;
   availableElements?: Array<{
     id: string;
     role: string;
@@ -52,11 +281,57 @@ export interface DebugData {
 let actionCounter = 0;
 let sessionId: string | null = null;
 
+function stringifyDebugJson(value: unknown): string {
+  const seen = new WeakSet<object>();
+  try {
+    const serialized = JSON.stringify(
+      value,
+      (_key, candidate: unknown) => {
+        if (typeof candidate === "bigint") {
+          return `${candidate.toString()}n`;
+        }
+        if (typeof candidate === "object" && candidate !== null) {
+          if (seen.has(candidate)) {
+            return "[Circular]";
+          }
+          seen.add(candidate);
+        }
+        return candidate;
+      },
+      2
+    );
+    if (typeof serialized === "string") {
+      return serialized;
+    }
+  } catch {
+    // fall through to fallback serialization
+  }
+  return JSON.stringify(
+    {
+      __nonSerializable: formatDebugWriterDiagnostic(value),
+    },
+    null,
+    2
+  );
+}
+
+function writeDebugFileSafe(filePath: string, content: string | Buffer): void {
+  try {
+    fs.writeFileSync(filePath, content);
+  } catch (error) {
+    console.warn(
+      `[debugWriter] Failed to write "${filePath}": ${formatDebugWriterDiagnostic(
+        error
+      )}`
+    );
+  }
+}
+
 /**
  * Initialize a new debug session
  */
 export function initDebugSession(): string {
-  sessionId = new Date().toISOString().replace(/[:.]/g, '-');
+  sessionId = new Date().toISOString().replace(/[:.]/g, "-");
   actionCounter = 0;
   return sessionId;
 }
@@ -72,91 +347,101 @@ function getSessionId(): string {
 }
 
 /**
- * Write debug data for an aiAction call
+ * Write debug data for a canonical page.perform() single-action call.
  */
-export async function writeAiActionDebug(
+export async function writePerformDebug(
   debugData: DebugData,
-  baseDir: string = 'debug/aiAction'
+  baseDir: string = "debug/perform"
 ): Promise<string> {
+  const normalizedDebugData = normalizeDebugData(debugData);
   const session = getSessionId();
-  const actionNum = actionCounter++;
+  const actionNum = actionCounter;
   const debugDir = path.join(baseDir, session, `action-${actionNum}`);
 
   // Create debug directory
-  fs.mkdirSync(debugDir, { recursive: true });
+  try {
+    fs.mkdirSync(debugDir, { recursive: true });
+  } catch (error) {
+    throw new Error(
+      `[debugWriter] Failed to create debug directory "${debugDir}": ${formatDebugWriterDiagnostic(
+        error
+      )}`
+    );
+  }
+  actionCounter += 1;
 
   // Write instruction and metadata
   const metadata = {
     actionNumber: actionNum,
-    timestamp: debugData.timestamp,
-    instruction: debugData.instruction,
-    url: debugData.url,
-    domElementCount: debugData.domElementCount,
-    success: debugData.success,
+    timestamp: normalizedDebugData.timestamp,
+    instruction: normalizedDebugData.instruction,
+    url: normalizedDebugData.url,
+    domElementCount: normalizedDebugData.domElementCount,
+    success: normalizedDebugData.success,
   };
-  fs.writeFileSync(
-    path.join(debugDir, 'metadata.json'),
-    JSON.stringify(metadata, null, 2)
+  writeDebugFileSafe(
+    path.join(debugDir, "metadata.json"),
+    stringifyDebugJson(metadata)
   );
 
   // Write DOM tree
-  fs.writeFileSync(path.join(debugDir, 'dom-tree.txt'), debugData.domTree);
+  writeDebugFileSafe(path.join(debugDir, "dom-tree.txt"), normalizedDebugData.domTree);
 
   // Write screenshot if available
-  if (debugData.screenshot) {
-    fs.writeFileSync(path.join(debugDir, 'screenshot.png'), debugData.screenshot);
+  if (normalizedDebugData.screenshot) {
+    writeDebugFileSafe(path.join(debugDir, "screenshot.png"), normalizedDebugData.screenshot);
   }
 
   // Write found element info
-  if (debugData.foundElement) {
-    fs.writeFileSync(
-      path.join(debugDir, 'found-element.json'),
-      JSON.stringify(debugData.foundElement, null, 2)
+  if (normalizedDebugData.foundElement) {
+    writeDebugFileSafe(
+      path.join(debugDir, "found-element.json"),
+      stringifyDebugJson(normalizedDebugData.foundElement)
     );
   }
 
   // Write LLM response if available
-  if (debugData.llmResponse) {
-    fs.writeFileSync(
-      path.join(debugDir, 'llm-response.json'),
-      JSON.stringify(debugData.llmResponse, null, 2)
+  if (normalizedDebugData.llmResponse) {
+    writeDebugFileSafe(
+      path.join(debugDir, "llm-response.json"),
+      stringifyDebugJson(normalizedDebugData.llmResponse)
     );
     // Also write just the raw text for easy viewing
-    fs.writeFileSync(
-      path.join(debugDir, 'llm-response.txt'),
-      debugData.llmResponse.rawText
+    writeDebugFileSafe(
+      path.join(debugDir, "llm-response.txt"),
+      normalizedDebugData.llmResponse.rawText
     );
   }
 
   // Write available elements if provided (for debugging failures)
-  if (debugData.availableElements) {
-    const elementsText = debugData.availableElements
+  if (normalizedDebugData.availableElements) {
+    const elementsText = normalizedDebugData.availableElements
       .map((e) => `[${e.id}] ${e.role}: "${e.label}"`)
-      .join('\n');
-    fs.writeFileSync(path.join(debugDir, 'available-elements.txt'), elementsText);
-    fs.writeFileSync(
-      path.join(debugDir, 'available-elements.json'),
-      JSON.stringify(debugData.availableElements, null, 2)
+      .join("\n");
+    writeDebugFileSafe(path.join(debugDir, "available-elements.txt"), elementsText);
+    writeDebugFileSafe(
+      path.join(debugDir, "available-elements.json"),
+      stringifyDebugJson(normalizedDebugData.availableElements)
     );
   }
 
   // Write error if present
-  if (debugData.error) {
-    fs.writeFileSync(
-      path.join(debugDir, 'error.json'),
-      JSON.stringify(debugData.error, null, 2)
+  if (normalizedDebugData.error) {
+    writeDebugFileSafe(
+      path.join(debugDir, "error.json"),
+      stringifyDebugJson(normalizedDebugData.error)
     );
   }
 
   // Write frame debug info if available
-  if (debugData.frameDebugInfo && debugData.frameDebugInfo.length > 0) {
-    fs.writeFileSync(
-      path.join(debugDir, 'frame-debug-info.json'),
-      JSON.stringify(debugData.frameDebugInfo, null, 2)
+  if (normalizedDebugData.frameDebugInfo && normalizedDebugData.frameDebugInfo.length > 0) {
+    writeDebugFileSafe(
+      path.join(debugDir, "frame-debug-info.json"),
+      stringifyDebugJson(normalizedDebugData.frameDebugInfo)
     );
 
     // Also write a human-readable summary
-    const frameSummary = debugData.frameDebugInfo
+    const frameSummary = normalizedDebugData.frameDebugInfo
       .map((frame) => {
         const lines = [
           `Frame ${frame.frameIndex}: ${frame.frameUrl}`,
@@ -168,24 +453,37 @@ export async function writeAiActionDebug(
         if (frame.sampleNodes && frame.sampleNodes.length > 0) {
           lines.push(`  Sample Nodes (${frame.sampleNodes.length}):`);
           frame.sampleNodes.forEach((node, idx) => {
-            const ignored = node.ignored ? ' [IGNORED]' : '';
-            const role = node.role || 'unknown';
-            const name = node.name ? ` "${node.name}"` : '';
-            const childCount = node.childIds ? ` (${node.childIds} children)` : '';
+            const ignored = node.ignored ? " [IGNORED]" : "";
+            const role = node.role || "unknown";
+            const name = node.name ? ` "${node.name}"` : "";
+            const childCount = node.childIds
+              ? ` (${node.childIds} children)`
+              : "";
             lines.push(`    ${idx + 1}. ${role}${name}${childCount}${ignored}`);
           });
         }
 
-        return lines.join('\n');
+        return lines.join("\n");
       })
-      .join('\n\n');
+      .join("\n\n");
 
-    fs.writeFileSync(path.join(debugDir, 'frame-debug-summary.txt'), frameSummary);
+    writeDebugFileSafe(path.join(debugDir, "frame-debug-summary.txt"), frameSummary);
   }
 
   return debugDir;
 }
 
+/**
+ * @deprecated Use writePerformDebug() instead.
+ * Backward-compatible alias that keeps the legacy default base directory.
+ */
+export async function writeAiActionDebug(
+  debugData: DebugData,
+  baseDir: string = "debug/aiAction"
+): Promise<string> {
+  return writePerformDebug(debugData, baseDir);
+}
+
 /**
  * Reset the action counter (useful for testing or new sessions)
  */
diff --git a/src/utils/format-unknown-error.test.ts b/src/utils/format-unknown-error.test.ts
new file mode 100644
index 00000000..b1900e6c
--- /dev/null
+++ b/src/utils/format-unknown-error.test.ts
@@ -0,0 +1,29 @@
+import { formatUnknownError } from "@/utils";
+
+describe("formatUnknownError", () => {
+  it("returns message for Error instances", () => {
+    expect(formatUnknownError(new Error("boom"))).toBe("boom");
+  });
+
+  it("falls back to error name when message is empty", () => {
+    expect(formatUnknownError(new Error("   "))).toBe("Error");
+  });
+
+  it("returns strings unchanged", () => {
+    expect(formatUnknownError("plain error")).toBe("plain error");
+  });
+
+  it("serializes plain objects", () => {
+    expect(formatUnknownError({ reason: "bad" })).toBe('{"reason":"bad"}');
+  });
+
+  it("falls back to string conversion when JSON serialization fails", () => {
+    const circular: { self?: unknown } = {};
+    circular.self = circular;
+    expect(formatUnknownError(circular)).toBe('{"self":"[Circular]"}');
+  });
+
+  it("serializes bigint values to readable strings", () => {
+    expect(formatUnknownError({ value: 42n })).toBe('{"value":"42n"}');
+  });
+});
diff --git a/src/utils/format-unknown-error.ts b/src/utils/format-unknown-error.ts
new file mode 100644
index 00000000..05859407
--- /dev/null
+++ b/src/utils/format-unknown-error.ts
@@ -0,0 +1,34 @@
+function stringifyUnknownObject(value: object): string {
+  const seen = new WeakSet<object>();
+  const serialized = JSON.stringify(value, (_key, candidate: unknown) => {
+    if (typeof candidate === "bigint") {
+      return `${candidate.toString()}n`;
+    }
+    if (typeof candidate === "object" && candidate !== null) {
+      if (seen.has(candidate)) {
+        return "[Circular]";
+      }
+      seen.add(candidate);
+    }
+    return candidate;
+  });
+  return serialized ?? String(value);
+}
+
+export function formatUnknownError(error: unknown): string {
+  if (error instanceof Error) {
+    const message = error.message?.trim();
+    return message && message.length > 0 ? message : error.name;
+  }
+  if (typeof error === "string") {
+    return error;
+  }
+  if (error && typeof error === "object") {
+    try {
+      return stringifyUnknownObject(error);
+    } catch {
+      return String(error);
+    }
+  }
+  return String(error);
+}
diff --git a/src/utils/html-to-markdown.test.ts b/src/utils/html-to-markdown.test.ts
new file mode 100644
index 00000000..5e99ade0
--- /dev/null
+++ b/src/utils/html-to-markdown.test.ts
@@ -0,0 +1,50 @@
+import { parseMarkdown, turndownService } from "@/utils/html-to-markdown";
+
+describe("parseMarkdown", () => {
+  afterEach(() => {
+    jest.restoreAllMocks();
+  });
+
+  it("returns empty string for nullish HTML", async () => {
+    await expect(parseMarkdown(null)).resolves.toBe("");
+    await expect(parseMarkdown(undefined)).resolves.toBe("");
+  });
+
+  it("formats non-Error turndown failures and returns empty markdown", async () => {
+    const errorSpy = jest.spyOn(console, "error").mockImplementation(() => {});
+    jest.spyOn(turndownService, "turndown").mockImplementation(() => {
+      throw { reason: "turndown crashed" };
+    });
+
+    try {
+      const result = await parseMarkdown("<div>content</div>");
+
+      expect(result).toBe("");
+      expect(errorSpy).toHaveBeenCalledWith(
+        'Error converting HTML to Markdown: {"reason":"turndown crashed"}'
+      );
+    } finally {
+      errorSpy.mockRestore();
+    }
+  });
+
+  it("sanitizes and truncates oversized turndown diagnostics", async () => {
+    const errorSpy = jest.spyOn(console, "error").mockImplementation(() => {});
+    jest.spyOn(turndownService, "turndown").mockImplementation(() => {
+      throw new Error(`markdown\u0000\n${"x".repeat(10_000)}`);
+    });
+
+    try {
+      const result = await parseMarkdown("<div>content</div>");
+
+      expect(result).toBe("");
+      const diagnostic = String(errorSpy.mock.calls[0]?.[0] ?? "");
+      expect(diagnostic).toContain("[truncated");
+      expect(diagnostic).not.toContain("\u0000");
+      expect(diagnostic).not.toContain("\n");
+      expect(diagnostic.length).toBeLessThan(700);
+    } finally {
+      errorSpy.mockRestore();
+    }
+  });
+});
diff --git a/src/utils/html-to-markdown.ts b/src/utils/html-to-markdown.ts
index 6bdab835..029ae958 100644
--- a/src/utils/html-to-markdown.ts
+++ b/src/utils/html-to-markdown.ts
@@ -1,6 +1,5 @@
 import TurndownService from "turndown";
-// TODO: Add gfm plugin
-// import { gfm } from "joplin-turndown-plugin-gfm";
+import { formatUnknownError } from "./format-unknown-error";
 
 export const turndownService = new TurndownService();
 
@@ -12,20 +11,46 @@ turndownService.addRule("removeUnwantedTags", {
 });
 
 turndownService.addRule("inlineLink", {
-  filter: function (node: any, options: any) {
+  filter: function (
+    node: { nodeName: string; getAttribute: (name: string) => string | null },
+    options: { linkStyle?: string }
+  ) {
     return (
       options.linkStyle === "inlined" &&
       node.nodeName === "A" &&
-      node.getAttribute("href")
+      Boolean(node.getAttribute("href"))
     );
   },
-  replacement: function (content: string, node: any) {
-    var href = node.getAttribute("href").trim();
-    var title = node.title ? ' "' + node.title + '"' : "";
+  replacement: function (
+    content: string,
+    node: { getAttribute: (name: string) => string | null; title?: string }
+  ) {
+    const href = (node.getAttribute("href") ?? "").trim();
+    const title = node.title ? ` "${node.title}"` : "";
     return "[" + content.trim() + "](" + href + title + ")\n";
   },
 });
-// turndownService.use(gfm);
+
+const MAX_HTML_TO_MARKDOWN_DIAGNOSTIC_CHARS = 400;
+
+function formatHtmlToMarkdownDiagnostic(value: unknown): string {
+  const normalized = Array.from(formatUnknownError(value), (char) => {
+    const code = char.charCodeAt(0);
+    return (code >= 0 && code < 32) || code === 127 ? " " : char;
+  })
+    .join("")
+    .replace(/\s+/g, " ")
+    .trim();
+  const fallback = normalized.length > 0 ? normalized : "unknown error";
+  if (fallback.length <= MAX_HTML_TO_MARKDOWN_DIAGNOSTIC_CHARS) {
+    return fallback;
+  }
+  const omittedChars = fallback.length - MAX_HTML_TO_MARKDOWN_DIAGNOSTIC_CHARS;
+  return `${fallback.slice(
+    0,
+    MAX_HTML_TO_MARKDOWN_DIAGNOSTIC_CHARS
+  )}... [truncated ${omittedChars} chars]`;
+}
 
 const processMultiLineLinks = (markdownContent: string): string => {
   let insideLinkContent = false;
@@ -53,7 +78,7 @@ const processMultiLineLinks = (markdownContent: string): string => {
 const removeSkipToContentLinks = (markdownContent: string): string => {
   // Remove [Skip to Content](#page) and [Skip to content](#skip)
   const newMarkdownContent = markdownContent.replace(
-    /\[Skip to Content\]\(#[^\)]*\)/gi,
+    /\[Skip to Content\]\(#[^)]*\)/gi,
     ""
   );
   return newMarkdownContent;
@@ -71,7 +96,11 @@ export async function parseMarkdown(
     markdownContent = removeSkipToContentLinks(markdownContent);
     return markdownContent;
   } catch (error) {
-    console.error("Error converting HTML to Markdown", { error });
+    console.error(
+      `Error converting HTML to Markdown: ${formatHtmlToMarkdownDiagnostic(
+        error
+      )}`
+    );
     return ""; // Optionally return an empty string or handle the error as needed
   }
 }
diff --git a/src/utils/index.ts b/src/utils/index.ts
index 598ffff9..b5938a88 100644
--- a/src/utils/index.ts
+++ b/src/utils/index.ts
@@ -1,5 +1,7 @@
 import { sleep } from "./sleep";
 import { retry } from "./retry";
 import { ErrorEmitter } from "./error-emitter";
+import { formatUnknownError } from "./format-unknown-error";
+import { normalizePageUrl } from "./page-url";
 
-export { sleep, retry, ErrorEmitter };
+export { sleep, retry, ErrorEmitter, formatUnknownError, normalizePageUrl };
diff --git a/src/utils/page-url.test.ts b/src/utils/page-url.test.ts
new file mode 100644
index 00000000..7844c6c5
--- /dev/null
+++ b/src/utils/page-url.test.ts
@@ -0,0 +1,70 @@
+import { normalizePageUrl } from "@/utils/page-url";
+
+describe("normalizePageUrl", () => {
+  it("returns fallback for non-string values", () => {
+    expect(normalizePageUrl(undefined)).toBe("about:blank");
+    expect(normalizePageUrl({})).toBe("about:blank");
+  });
+
+  it("sanitizes control characters and collapses whitespace", () => {
+    expect(normalizePageUrl("  https://example.com/\u0000a\nb\tc  ")).toBe(
+      "https://example.com/ a b c"
+    );
+  });
+
+  it("returns fallback for empty normalized strings", () => {
+    expect(normalizePageUrl("\u0000\n\t")).toBe("about:blank");
+  });
+
+  it("supports custom fallback values", () => {
+    expect(normalizePageUrl(null, { fallback: "unknown" })).toBe("unknown");
+  });
+
+  it("sanitizes custom fallback values", () => {
+    expect(normalizePageUrl(null, { fallback: " bad\u0000\nfallback " })).toBe(
+      "bad fallback"
+    );
+  });
+
+  it("truncates sanitized URLs when maxChars is provided", () => {
+    const normalized = normalizePageUrl(
+      `https://example.com/${"x".repeat(200)}`,
+      { maxChars: 40 }
+    );
+    expect(normalized).toContain("[truncated");
+    expect(normalized.length).toBeGreaterThan(40);
+  });
+
+  it("does not throw when options getters trap", () => {
+    const trappedOptions = new Proxy(
+      {},
+      {
+        get: (_target, prop: string | symbol) => {
+          if (prop === "fallback" || prop === "maxChars") {
+            throw new Error("option trap");
+          }
+          return undefined;
+        },
+      }
+    );
+
+    expect(() =>
+      normalizePageUrl(
+        "https://example.com/path",
+        trappedOptions as unknown as Parameters<typeof normalizePageUrl>[1]
+      )
+    ).not.toThrow();
+    expect(
+      normalizePageUrl(
+        "https://example.com/path",
+        trappedOptions as unknown as Parameters<typeof normalizePageUrl>[1]
+      )
+    ).toBe("https://example.com/path");
+    expect(
+      normalizePageUrl(
+        undefined,
+        trappedOptions as unknown as Parameters<typeof normalizePageUrl>[1]
+      )
+    ).toBe("about:blank");
+  });
+});
diff --git a/src/utils/page-url.ts b/src/utils/page-url.ts
new file mode 100644
index 00000000..6f8de7bd
--- /dev/null
+++ b/src/utils/page-url.ts
@@ -0,0 +1,70 @@
+const DEFAULT_PAGE_URL_FALLBACK = "about:blank";
+
+type NormalizePageUrlOptions = {
+  fallback?: string;
+  maxChars?: number;
+};
+
+function safeReadOptionField(
+  options: unknown,
+  field: keyof NormalizePageUrlOptions
+): unknown {
+  if (!options || (typeof options !== "object" && typeof options !== "function")) {
+    return undefined;
+  }
+  try {
+    return (options as Record<string, unknown>)[field];
+  } catch {
+    return undefined;
+  }
+}
+
+function sanitizePageUrlText(value: string): string {
+  if (value.length === 0) {
+    return value;
+  }
+  return Array.from(value, (char) => {
+    const code = char.charCodeAt(0);
+    return (code >= 0 && code < 32) || code === 127 ? " " : char;
+  })
+    .join("")
+    .replace(/\s+/g, " ")
+    .trim();
+}
+
+function truncatePageUrl(value: string, maxChars: number): string {
+  if (value.length <= maxChars) {
+    return value;
+  }
+  const omitted = value.length - maxChars;
+  return `${value.slice(0, maxChars)}... [truncated ${omitted} chars]`;
+}
+
+export function normalizePageUrl(
+  value: unknown,
+  options?: NormalizePageUrlOptions
+): string {
+  const fallbackOption = safeReadOptionField(options, "fallback");
+  const fallbackCandidate =
+    typeof fallbackOption === "string"
+      ? sanitizePageUrlText(fallbackOption)
+      : DEFAULT_PAGE_URL_FALLBACK;
+  const fallback =
+    fallbackCandidate.length > 0 ? fallbackCandidate : DEFAULT_PAGE_URL_FALLBACK;
+  if (typeof value !== "string") {
+    return fallback;
+  }
+  const normalized = sanitizePageUrlText(value);
+  if (normalized.length === 0) {
+    return fallback;
+  }
+  const maxChars = safeReadOptionField(options, "maxChars");
+  if (
+    typeof maxChars !== "number" ||
+    !Number.isFinite(maxChars) ||
+    maxChars <= 0
+  ) {
+    return normalized;
+  }
+  return truncatePageUrl(normalized, Math.floor(maxChars));
+}
diff --git a/src/utils/retry.test.ts b/src/utils/retry.test.ts
new file mode 100644
index 00000000..67b2965a
--- /dev/null
+++ b/src/utils/retry.test.ts
@@ -0,0 +1,216 @@
+import { retry } from "@/utils/retry";
+
+jest.mock("@/utils/sleep", () => ({
+  sleep: jest.fn().mockResolvedValue(undefined),
+}));
+
+const { sleep } = jest.requireMock("@/utils/sleep") as {
+  sleep: jest.Mock;
+};
+
+describe("retry", () => {
+  beforeEach(() => {
+    jest.clearAllMocks();
+  });
+
+  it("uses default retry count when provided retry count is invalid", async () => {
+    const func = jest
+      .fn()
+      .mockRejectedValueOnce(new Error("one"))
+      .mockRejectedValueOnce(new Error("two"))
+      .mockResolvedValue("ok");
+
+    const result = await retry({
+      func,
+      params: { retryCount: 0 },
+    });
+
+    expect(result).toBe("ok");
+    expect(func).toHaveBeenCalledTimes(3);
+  });
+
+  it("uses default retry count when retry params omit retryCount", async () => {
+    const func = jest
+      .fn()
+      .mockRejectedValueOnce(new Error("one"))
+      .mockRejectedValueOnce(new Error("two"))
+      .mockResolvedValue("ok");
+
+    const result = await retry({
+      func,
+      params: {},
+    });
+
+    expect(result).toBe("ok");
+    expect(func).toHaveBeenCalledTimes(3);
+  });
+
+  it("caps retry count to prevent unbounded retry loops", async () => {
+    const func = jest.fn().mockRejectedValue(new Error("always fails"));
+
+    await expect(
+      retry({
+        func,
+        params: { retryCount: 1000 },
+      })
+    ).rejects.toThrow("always fails");
+
+    expect(func).toHaveBeenCalledTimes(10);
+  });
+
+  it("caps exponential backoff delay to bounded maximum", async () => {
+    const func = jest.fn().mockRejectedValue(new Error("always fails"));
+
+    await expect(
+      retry({
+        func,
+        params: { retryCount: 10 },
+      })
+    ).rejects.toThrow("always fails");
+
+    expect(sleep).toHaveBeenCalledTimes(9);
+    const sleepDelays = sleep.mock.calls.map((call) => call[0] as number);
+    expect(Math.max(...sleepDelays)).toBe(10000);
+    expect(sleepDelays.some((delay) => delay > 10000)).toBe(false);
+  });
+
+  it("does not sleep after the final failed attempt", async () => {
+    const func = jest.fn().mockRejectedValue(new Error("always fails"));
+
+    await expect(
+      retry({
+        func,
+        params: { retryCount: 2 },
+      })
+    ).rejects.toThrow("always fails");
+
+    expect(func).toHaveBeenCalledTimes(2);
+    expect(sleep).toHaveBeenCalledTimes(1);
+    expect(sleep).toHaveBeenCalledWith(1000);
+  });
+
+  it("reports attempt numbers in onError callback", async () => {
+    const onError = jest.fn();
+    const func = jest
+      .fn()
+      .mockRejectedValueOnce(new Error("first"))
+      .mockResolvedValue("ok");
+
+    const result = await retry({
+      func,
+      params: { retryCount: 3 },
+      onError,
+    });
+
+    expect(result).toBe("ok");
+    expect(onError).toHaveBeenCalledWith(
+      "Retry Attempt 1/3",
+      expect.any(Error)
+    );
+  });
+
+  it("continues retrying when onError callback throws", async () => {
+    const warnSpy = jest.spyOn(console, "warn").mockImplementation(() => {});
+    const onError = jest.fn(() => {
+      throw { reason: "onError crashed" };
+    });
+    const func = jest
+      .fn()
+      .mockRejectedValueOnce(new Error("first"))
+      .mockResolvedValue("ok");
+
+    try {
+      const result = await retry({
+        func,
+        params: { retryCount: 2 },
+        onError,
+      });
+
+      expect(result).toBe("ok");
+      expect(warnSpy).toHaveBeenCalledWith(
+        '[retry] onError handler failed: {"reason":"onError crashed"}'
+      );
+    } finally {
+      warnSpy.mockRestore();
+    }
+  });
+
+  it("sanitizes and truncates oversized onError handler diagnostics", async () => {
+    const warnSpy = jest.spyOn(console, "warn").mockImplementation(() => {});
+    const onError = jest.fn(() => {
+      throw new Error(`handler\u0000\n${"x".repeat(10_000)}`);
+    });
+    const func = jest
+      .fn()
+      .mockRejectedValueOnce(new Error("first"))
+      .mockResolvedValue("ok");
+
+    try {
+      const result = await retry({
+        func,
+        params: { retryCount: 2 },
+        onError,
+      });
+
+      expect(result).toBe("ok");
+      const warning = String(warnSpy.mock.calls[0]?.[0] ?? "");
+      expect(warning).toContain("[truncated");
+      expect(warning).not.toContain("\u0000");
+      expect(warning).not.toContain("\n");
+      expect(warning.length).toBeLessThan(700);
+    } finally {
+      warnSpy.mockRestore();
+    }
+  });
+
+  it("continues retrying when sleep throws", async () => {
+    const warnSpy = jest.spyOn(console, "warn").mockImplementation(() => {});
+    sleep.mockRejectedValueOnce({ reason: "sleep failed" }).mockResolvedValue(undefined);
+    const func = jest
+      .fn()
+      .mockRejectedValueOnce(new Error("first"))
+      .mockResolvedValue("ok");
+
+    try {
+      const result = await retry({
+        func,
+        params: { retryCount: 2 },
+      });
+
+      expect(result).toBe("ok");
+      expect(func).toHaveBeenCalledTimes(2);
+      expect(warnSpy).toHaveBeenCalledWith(
+        '[retry] sleep failed: {"reason":"sleep failed"}'
+      );
+    } finally {
+      warnSpy.mockRestore();
+    }
+  });
+
+  it("sanitizes and truncates oversized sleep diagnostics", async () => {
+    const warnSpy = jest.spyOn(console, "warn").mockImplementation(() => {});
+    sleep
+      .mockRejectedValueOnce(new Error(`sleep\u0000\n${"x".repeat(10_000)}`))
+      .mockResolvedValue(undefined);
+    const func = jest
+      .fn()
+      .mockRejectedValueOnce(new Error("first"))
+      .mockResolvedValue("ok");
+
+    try {
+      const result = await retry({
+        func,
+        params: { retryCount: 2 },
+      });
+
+      expect(result).toBe("ok");
+      const warning = String(warnSpy.mock.calls[0]?.[0] ?? "");
+      expect(warning).toContain("[truncated");
+      expect(warning).not.toContain("\u0000");
+      expect(warning).not.toContain("\n");
+      expect(warning.length).toBeLessThan(700);
+    } finally {
+      warnSpy.mockRestore();
+    }
+  });
+});
diff --git a/src/utils/retry.ts b/src/utils/retry.ts
index 18bdcf9d..e588135e 100644
--- a/src/utils/retry.ts
+++ b/src/utils/retry.ts
@@ -1,25 +1,72 @@
 import { sleep } from "./sleep";
+import { formatUnknownError } from "./format-unknown-error";
+
+const DEFAULT_RETRY_COUNT = 3;
+const MAX_RETRY_COUNT = 10;
+const MAX_RETRY_DELAY_MS = 10_000;
+const MAX_RETRY_DIAGNOSTIC_CHARS = 300;
+
+function formatRetryDiagnostic(value: unknown): string {
+  const normalized = Array.from(formatUnknownError(value), (char) => {
+    const code = char.charCodeAt(0);
+    return (code >= 0 && code < 32) || code === 127 ? " " : char;
+  })
+    .join("")
+    .replace(/\s+/g, " ")
+    .trim();
+  const fallback = normalized.length > 0 ? normalized : "unknown error";
+  if (fallback.length <= MAX_RETRY_DIAGNOSTIC_CHARS) {
+    return fallback;
+  }
+  const omittedChars = fallback.length - MAX_RETRY_DIAGNOSTIC_CHARS;
+  return `${fallback.slice(0, MAX_RETRY_DIAGNOSTIC_CHARS)}... [truncated ${omittedChars} chars]`;
+}
+
+function normalizeRetryCount(value?: number): number {
+  if (typeof value !== "number" || !Number.isFinite(value)) {
+    return DEFAULT_RETRY_COUNT;
+  }
+  if (value <= 0) {
+    return DEFAULT_RETRY_COUNT;
+  }
+  return Math.min(Math.floor(value), MAX_RETRY_COUNT);
+}
+
 export async function retry<T>({
   func,
   params,
   onError,
 }: {
   func: () => Promise<T>;
-  params?: { retryCount: number };
+  params?: { retryCount?: number };
   onError?: (...err: Array<unknown>) => void;
-}) {
-  let err = null;
-  const retryCount = params?.retryCount || 3;
-  for (let i = 0; i < retryCount; i++) {
+}): Promise<T> {
+  let lastError: unknown = new Error("Retry operation failed");
+  const retryCount = normalizeRetryCount(params?.retryCount);
+  for (let attempt = 0; attempt < retryCount; attempt++) {
     try {
       const resp = await func();
       return resp;
     } catch (error) {
-      onError?.(`Retry Attempt: ${i}`, error);
-      err = error;
-      await sleep(Math.pow(2, i) * 1000);
-      continue;
+      try {
+        onError?.(`Retry Attempt ${attempt + 1}/${retryCount}`, error);
+      } catch (handlerError) {
+        console.warn(
+          `[retry] onError handler failed: ${formatRetryDiagnostic(handlerError)}`
+        );
+      }
+      lastError = error;
+      if (attempt < retryCount - 1) {
+        const delayMs = Math.min(Math.pow(2, attempt) * 1000, MAX_RETRY_DELAY_MS);
+        try {
+          await sleep(delayMs);
+        } catch (sleepError) {
+          console.warn(
+            `[retry] sleep failed: ${formatRetryDiagnostic(sleepError)}`
+          );
+        }
+      }
     }
   }
-  throw err;
+  throw lastError;
 }
diff --git a/src/utils/waitForSettledDOM.test.ts b/src/utils/waitForSettledDOM.test.ts
new file mode 100644
index 00000000..6f20f784
--- /dev/null
+++ b/src/utils/waitForSettledDOM.test.ts
@@ -0,0 +1,763 @@
+import {
+  waitForSettledDOM,
+  type WaitForSettledOptions,
+} from "@/utils/waitForSettledDOM";
+import type { CDPClient, CDPSession } from "@/cdp";
+
+jest.mock("@/cdp", () => ({
+  getCDPClient: jest.fn(),
+  getOrCreateFrameContextManager: jest.fn(),
+}));
+
+jest.mock("@/debug/options", () => ({
+  getDebugOptions: jest.fn(),
+}));
+
+const { getCDPClient, getOrCreateFrameContextManager } = jest.requireMock(
+  "@/cdp"
+) as {
+  getCDPClient: jest.Mock;
+  getOrCreateFrameContextManager: jest.Mock;
+};
+const { getDebugOptions } = jest.requireMock("@/debug/options") as {
+  getDebugOptions: jest.Mock;
+};
+
+type EventHandler = (...args: unknown[]) => void;
+
+function createSessionWithEvents(options?: {
+  throwOnOnEvent?: string;
+  throwOnOffEvent?: string;
+  onErrorMessage?: string;
+  offErrorMessage?: string;
+  onErrorValue?: unknown;
+  offErrorValue?: unknown;
+}): {
+  session: CDPSession;
+  emit: (event: string, payload: unknown) => void;
+} {
+  const handlers = new Map<string, Set<EventHandler>>();
+  const session: CDPSession = {
+    send: async <T = unknown>(): Promise<T> => ({} as T),
+    on: <TPayload extends unknown[]>(
+      event: string,
+      handler: (...payload: TPayload) => void
+    ) => {
+      if (options?.throwOnOnEvent === event) {
+        if (typeof options.onErrorValue !== "undefined") {
+          throw options.onErrorValue;
+        }
+        throw new Error(options.onErrorMessage ?? "listener registration failed");
+      }
+      const eventHandler = handler as EventHandler;
+      const existing = handlers.get(event);
+      if (existing) {
+        existing.add(eventHandler);
+      } else {
+        handlers.set(event, new Set([eventHandler]));
+      }
+    },
+    off: <TPayload extends unknown[]>(
+      event: string,
+      handler: (...payload: TPayload) => void
+    ) => {
+      if (options?.throwOnOffEvent === event) {
+        if (typeof options.offErrorValue !== "undefined") {
+          throw options.offErrorValue;
+        }
+        throw new Error(options.offErrorMessage ?? "listener detach failed");
+      }
+      handlers.get(event)?.delete(handler as EventHandler);
+    },
+    detach: async () => undefined,
+    id: "session-1",
+  };
+
+  const emit = (event: string, payload: unknown): void => {
+    handlers.get(event)?.forEach((handler) => {
+      handler(payload);
+    });
+  };
+
+  return { session, emit };
+}
+
+describe("waitForSettledDOM diagnostics", () => {
+  beforeEach(() => {
+    jest.useFakeTimers();
+    jest.clearAllMocks();
+    getDebugOptions.mockReturnValue({
+      enabled: true,
+      traceWait: true,
+    });
+  });
+
+  afterEach(() => {
+    jest.useRealTimers();
+  });
+
+  it("sanitizes and truncates stalled-request warning diagnostics", async () => {
+    const warnSpy = jest.spyOn(console, "warn").mockImplementation(() => {});
+    const logSpy = jest.spyOn(console, "log").mockImplementation(() => {});
+    const { session, emit } = createSessionWithEvents();
+    const cdpClient: CDPClient = {
+      rootSession: session,
+      createSession: async () => session,
+      acquireSession: async () => session,
+      dispose: async () => undefined,
+    };
+    getCDPClient.mockResolvedValue(cdpClient);
+    getOrCreateFrameContextManager.mockReturnValue({
+      setDebug: jest.fn(),
+    });
+
+    const page = {
+      context: () => ({}),
+    } as never;
+
+    try {
+      const waitPromise = waitForSettledDOM(page, 5_000);
+      await Promise.resolve();
+      await Promise.resolve();
+
+      emit("Network.requestWillBeSent", {
+        requestId: `req\u0000\n${"x".repeat(600)}`,
+        type: "Document",
+        request: {
+          url: `https://example.com/path\u0000\n${"y".repeat(2_000)}`,
+        },
+      });
+
+      await jest.advanceTimersByTimeAsync(3_100);
+      const stats = await waitPromise;
+
+      const warning = String(warnSpy.mock.calls[0]?.[0] ?? "");
+      expect(warning).toContain("[truncated");
+      expect(warning).not.toContain("\u0000");
+      expect(warning).not.toContain("\n");
+      expect(warning.length).toBeLessThan(900);
+      expect(stats.forcedDrops).toBe(1);
+      expect(stats.requestsSeen).toBe(1);
+      expect(stats.peakInflight).toBe(1);
+      expect(stats.resolvedByTimeout).toBe(false);
+    } finally {
+      warnSpy.mockRestore();
+      logSpy.mockRestore();
+    }
+  });
+
+  it("reports timeout-driven completion when requests remain inflight", async () => {
+    const { session, emit } = createSessionWithEvents();
+    const cdpClient: CDPClient = {
+      rootSession: session,
+      createSession: async () => session,
+      acquireSession: async () => session,
+      dispose: async () => undefined,
+    };
+    getCDPClient.mockResolvedValue(cdpClient);
+    getOrCreateFrameContextManager.mockReturnValue({
+      setDebug: jest.fn(),
+    });
+    getDebugOptions.mockReturnValue({
+      enabled: false,
+      traceWait: false,
+    });
+
+    const page = {
+      context: () => ({}),
+    } as never;
+
+    const waitPromise = waitForSettledDOM(page, 600);
+    await Promise.resolve();
+    await Promise.resolve();
+
+    emit("Network.requestWillBeSent", {
+      requestId: "req-1",
+      type: "Document",
+      request: { url: "https://example.com/slow" },
+    });
+
+    await jest.advanceTimersByTimeAsync(700);
+    const stats = await waitPromise;
+
+    expect(stats.resolvedByTimeout).toBe(true);
+    expect(stats.forcedDrops).toBe(0);
+    expect(stats.requestsSeen).toBe(1);
+    expect(stats.peakInflight).toBe(1);
+  });
+
+  it("normalizes invalid timeout values instead of timing out immediately", async () => {
+    const { session } = createSessionWithEvents();
+    const cdpClient: CDPClient = {
+      rootSession: session,
+      createSession: async () => session,
+      acquireSession: async () => session,
+      dispose: async () => undefined,
+    };
+    getCDPClient.mockResolvedValue(cdpClient);
+    getOrCreateFrameContextManager.mockReturnValue({
+      setDebug: jest.fn(),
+    });
+    getDebugOptions.mockReturnValue({
+      enabled: false,
+      traceWait: false,
+    });
+
+    const page = {
+      context: () => ({}),
+    } as never;
+
+    const waitPromise = waitForSettledDOM(page, Number.NaN as unknown as number);
+    await Promise.resolve();
+    await Promise.resolve();
+    await jest.advanceTimersByTimeAsync(600);
+    const stats = await waitPromise;
+
+    expect(stats.resolvedByTimeout).toBe(false);
+    expect(stats.requestsSeen).toBe(0);
+    expect(stats.forcedDrops).toBe(0);
+  });
+
+  it("continues when debug-options lookup throws", async () => {
+    const warnSpy = jest.spyOn(console, "warn").mockImplementation(() => {});
+    const { session } = createSessionWithEvents();
+    const cdpClient: CDPClient = {
+      rootSession: session,
+      createSession: async () => session,
+      acquireSession: async () => session,
+      dispose: async () => undefined,
+    };
+    getCDPClient.mockResolvedValue(cdpClient);
+    getOrCreateFrameContextManager.mockReturnValue({
+      setDebug: jest.fn(),
+    });
+    getDebugOptions.mockImplementationOnce(() => {
+      throw new Error(`debug options\u0000\n${"x".repeat(2_000)}`);
+    });
+
+    const page = {
+      context: () => ({}),
+    } as never;
+
+    try {
+      const waitPromise = waitForSettledDOM(page, 600);
+      await Promise.resolve();
+      await Promise.resolve();
+      await jest.advanceTimersByTimeAsync(700);
+      const stats = await waitPromise;
+
+      expect(stats.resolvedByTimeout).toBe(false);
+      const warning = String(
+        warnSpy.mock.calls.find((call) =>
+          String(call[0] ?? "").includes("Failed to read debug options")
+        )?.[0] ?? ""
+      );
+      expect(warning).toContain("[truncated");
+      expect(warning).not.toContain("\u0000");
+      expect(warning).not.toContain("\n");
+    } finally {
+      warnSpy.mockRestore();
+    }
+  });
+
+  it("continues when page.context() getter throws", async () => {
+    const warnSpy = jest.spyOn(console, "warn").mockImplementation(() => {});
+    const { session } = createSessionWithEvents();
+    const cdpClient: CDPClient = {
+      rootSession: session,
+      createSession: async () => session,
+      acquireSession: async () => session,
+      dispose: async () => undefined,
+    };
+    getCDPClient.mockResolvedValue(cdpClient);
+    getOrCreateFrameContextManager.mockReturnValue({
+      setDebug: jest.fn(),
+    });
+    getDebugOptions.mockReturnValue({
+      enabled: false,
+      traceWait: false,
+    });
+
+    const page = {
+      context: () => {
+        throw new Error(`context\u0000\n${"x".repeat(2_000)}`);
+      },
+    } as never;
+
+    try {
+      const waitPromise = waitForSettledDOM(page, 600);
+      await Promise.resolve();
+      await Promise.resolve();
+      await jest.advanceTimersByTimeAsync(700);
+      const stats = await waitPromise;
+
+      expect(stats.resolvedByTimeout).toBe(false);
+      const warning = String(
+        warnSpy.mock.calls.find((call) =>
+          String(call[0] ?? "").includes("Failed to read page context")
+        )?.[0] ?? ""
+      );
+      expect(warning).toContain("[truncated");
+      expect(warning).not.toContain("\u0000");
+      expect(warning).not.toContain("\n");
+    } finally {
+      warnSpy.mockRestore();
+    }
+  });
+
+  it("does not warn when page.context method is unavailable", async () => {
+    const warnSpy = jest.spyOn(console, "warn").mockImplementation(() => {});
+    const { session } = createSessionWithEvents();
+    const cdpClient: CDPClient = {
+      rootSession: session,
+      createSession: async () => session,
+      acquireSession: async () => session,
+      dispose: async () => undefined,
+    };
+    getCDPClient.mockResolvedValue(cdpClient);
+    getOrCreateFrameContextManager.mockReturnValue({
+      setDebug: jest.fn(),
+    });
+    getDebugOptions.mockReturnValue({
+      enabled: false,
+      traceWait: false,
+    });
+
+    const page = {} as never;
+
+    try {
+      const waitPromise = waitForSettledDOM(page, 600);
+      await Promise.resolve();
+      await Promise.resolve();
+      await jest.advanceTimersByTimeAsync(700);
+      const stats = await waitPromise;
+
+      expect(stats.resolvedByTimeout).toBe(false);
+      expect(
+        warnSpy.mock.calls.some((call) =>
+          String(call[0] ?? "").includes("Failed to read page context")
+        )
+      ).toBe(false);
+    } finally {
+      warnSpy.mockRestore();
+    }
+  });
+
+  it("applies frame filtering option when provided", async () => {
+    const { session } = createSessionWithEvents();
+    const cdpClient: CDPClient = {
+      rootSession: session,
+      createSession: async () => session,
+      acquireSession: async () => session,
+      dispose: async () => undefined,
+    };
+    const setFrameFilteringEnabled = jest.fn();
+    getCDPClient.mockResolvedValue(cdpClient);
+    getOrCreateFrameContextManager.mockReturnValue({
+      setDebug: jest.fn(),
+      setFrameFilteringEnabled,
+    });
+    getDebugOptions.mockReturnValue({
+      enabled: false,
+      traceWait: false,
+    });
+
+    const page = {
+      context: () => ({}),
+    } as never;
+
+    const waitPromise = waitForSettledDOM(page, 600, {
+      filterAdTrackingFrames: false,
+    });
+    await Promise.resolve();
+    await Promise.resolve();
+    await jest.advanceTimersByTimeAsync(700);
+    await waitPromise;
+
+    expect(setFrameFilteringEnabled).toHaveBeenCalledWith(false);
+  });
+
+  it("enables network trace diagnostics when context is recording video", async () => {
+    const warnSpy = jest.spyOn(console, "warn").mockImplementation(() => {});
+    const logSpy = jest.spyOn(console, "log").mockImplementation(() => {});
+    const { session, emit } = createSessionWithEvents();
+    const cdpClient: CDPClient = {
+      rootSession: session,
+      createSession: async () => session,
+      acquireSession: async () => session,
+      dispose: async () => undefined,
+    };
+    getCDPClient.mockResolvedValue(cdpClient);
+    getOrCreateFrameContextManager.mockReturnValue({
+      setDebug: jest.fn(),
+    });
+    getDebugOptions.mockReturnValue({
+      enabled: false,
+      traceWait: false,
+    });
+
+    const page = {
+      context: () => ({
+        _options: {
+          recordVideo: {},
+        },
+      }),
+    } as never;
+
+    try {
+      const waitPromise = waitForSettledDOM(page, 5_000);
+      await Promise.resolve();
+      await Promise.resolve();
+
+      emit("Network.requestWillBeSent", {
+        requestId: "req-1",
+        type: "Document",
+        request: { url: "https://example.com/video" },
+      });
+
+      await jest.advanceTimersByTimeAsync(3_100);
+      await waitPromise;
+
+      const traceMessages = warnSpy.mock.calls
+        .map((call) => String(call[0] ?? ""))
+        .filter((message) => message.includes("[waitForSettledDOM]"));
+      expect(
+        traceMessages.some((message) =>
+          message.includes("Forcing completion of stalled request")
+        )
+      ).toBe(true);
+    } finally {
+      warnSpy.mockRestore();
+      logSpy.mockRestore();
+    }
+  });
+
+  it("continues when frame-filter configuration throws", async () => {
+    const warnSpy = jest.spyOn(console, "warn").mockImplementation(() => {});
+    const { session } = createSessionWithEvents();
+    const cdpClient: CDPClient = {
+      rootSession: session,
+      createSession: async () => session,
+      acquireSession: async () => session,
+      dispose: async () => undefined,
+    };
+    getCDPClient.mockResolvedValue(cdpClient);
+    getOrCreateFrameContextManager.mockReturnValue({
+      setDebug: jest.fn(),
+      setFrameFilteringEnabled: jest.fn(() => {
+        throw new Error(`filter\u0000\n${"x".repeat(2_000)}`);
+      }),
+    });
+    getDebugOptions.mockReturnValue({
+      enabled: false,
+      traceWait: false,
+    });
+
+    const page = {
+      context: () => ({}),
+    } as never;
+
+    try {
+      const waitPromise = waitForSettledDOM(page, 600, {
+        filterAdTrackingFrames: false,
+      });
+      await Promise.resolve();
+      await Promise.resolve();
+      await jest.advanceTimersByTimeAsync(700);
+      const stats = await waitPromise;
+
+      expect(stats.resolvedByTimeout).toBe(false);
+      const warning = String(
+        warnSpy.mock.calls.find((call) =>
+          String(call[0] ?? "").includes("configure frame filtering")
+        )?.[0] ?? ""
+      );
+      expect(warning).toContain("[truncated");
+      expect(warning).not.toContain("\u0000");
+      expect(warning).not.toContain("\n");
+    } finally {
+      warnSpy.mockRestore();
+    }
+  });
+
+  it("ignores trap-prone frame-filter option getters", async () => {
+    const { session } = createSessionWithEvents();
+    const cdpClient: CDPClient = {
+      rootSession: session,
+      createSession: async () => session,
+      acquireSession: async () => session,
+      dispose: async () => undefined,
+    };
+    const setFrameFilteringEnabled = jest.fn();
+    getCDPClient.mockResolvedValue(cdpClient);
+    getOrCreateFrameContextManager.mockReturnValue({
+      setDebug: jest.fn(),
+      setFrameFilteringEnabled,
+    });
+    getDebugOptions.mockReturnValue({
+      enabled: false,
+      traceWait: false,
+    });
+
+    const trappedOptions = new Proxy(
+      {},
+      {
+        get: (_target, prop: string | symbol) => {
+          if (prop === "filterAdTrackingFrames") {
+            throw new Error("frame-filter option trap");
+          }
+          return undefined;
+        },
+      }
+    ) as WaitForSettledOptions;
+
+    const page = {
+      context: () => ({}),
+    } as never;
+
+    const waitPromise = waitForSettledDOM(page, 600, trappedOptions);
+    await Promise.resolve();
+    await Promise.resolve();
+    await jest.advanceTimersByTimeAsync(700);
+    const stats = await waitPromise;
+
+    expect(stats.resolvedByTimeout).toBe(false);
+    expect(setFrameFilteringEnabled).not.toHaveBeenCalled();
+  });
+
+  it("falls back to timeout when network listener registration fails", async () => {
+    const warnSpy = jest.spyOn(console, "warn").mockImplementation(() => {});
+    const { session } = createSessionWithEvents({
+      throwOnOnEvent: "Network.requestWillBeSent",
+      onErrorMessage: `attach\u0000\n${"x".repeat(10_000)}`,
+    });
+    const cdpClient: CDPClient = {
+      rootSession: session,
+      createSession: async () => session,
+      acquireSession: async () => session,
+      dispose: async () => undefined,
+    };
+    getCDPClient.mockResolvedValue(cdpClient);
+    getOrCreateFrameContextManager.mockReturnValue({
+      setDebug: jest.fn(),
+    });
+    getDebugOptions.mockReturnValue({
+      enabled: false,
+      traceWait: false,
+    });
+
+    const page = {
+      context: () => ({}),
+    } as never;
+
+    try {
+      const waitPromise = waitForSettledDOM(page, 700);
+      await Promise.resolve();
+      await Promise.resolve();
+      await jest.advanceTimersByTimeAsync(800);
+      const stats = await waitPromise;
+
+      const attachWarning = String(warnSpy.mock.calls[0]?.[0] ?? "");
+      const fallbackWarning = String(warnSpy.mock.calls[1]?.[0] ?? "");
+      expect(attachWarning).toContain("[truncated");
+      expect(attachWarning).not.toContain("\u0000");
+      expect(attachWarning).not.toContain("\n");
+      expect(fallbackWarning).toContain("falling back to timeout-based settle");
+      expect(stats.resolvedByTimeout).toBe(true);
+      expect(stats.requestsSeen).toBe(0);
+      expect(stats.peakInflight).toBe(0);
+    } finally {
+      warnSpy.mockRestore();
+    }
+  });
+
+  it("falls back to timeout when listener method getter traps", async () => {
+    const warnSpy = jest.spyOn(console, "warn").mockImplementation(() => {});
+    const { session } = createSessionWithEvents();
+    const trappedSession = new Proxy(session, {
+      get: (target, prop, receiver) => {
+        if (prop === "on") {
+          throw new Error(`on getter\u0000\n${"x".repeat(10_000)}`);
+        }
+        return Reflect.get(target, prop, receiver);
+      },
+    }) as CDPSession;
+    const cdpClient: CDPClient = {
+      rootSession: trappedSession,
+      createSession: async () => trappedSession,
+      acquireSession: async () => trappedSession,
+      dispose: async () => undefined,
+    };
+    getCDPClient.mockResolvedValue(cdpClient);
+    getOrCreateFrameContextManager.mockReturnValue({
+      setDebug: jest.fn(),
+    });
+    getDebugOptions.mockReturnValue({
+      enabled: false,
+      traceWait: false,
+    });
+
+    const page = {
+      context: () => ({}),
+    } as never;
+
+    try {
+      const waitPromise = waitForSettledDOM(page, 700);
+      await Promise.resolve();
+      await Promise.resolve();
+      await jest.advanceTimersByTimeAsync(800);
+      const stats = await waitPromise;
+
+      const attachWarning = String(warnSpy.mock.calls[0]?.[0] ?? "");
+      const fallbackWarning = String(
+        warnSpy.mock.calls.find((call) =>
+          String(call[0] ?? "").includes("falling back to timeout-based settle")
+        )?.[0] ?? ""
+      );
+      expect(attachWarning).toContain("[truncated");
+      expect(attachWarning).not.toContain("\u0000");
+      expect(attachWarning).not.toContain("\n");
+      expect(fallbackWarning).toContain("falling back to timeout-based settle");
+      expect(stats.resolvedByTimeout).toBe(true);
+      expect(stats.requestsSeen).toBe(0);
+      expect(stats.peakInflight).toBe(0);
+    } finally {
+      warnSpy.mockRestore();
+    }
+  });
+
+  it("formats non-Error listener registration diagnostics deterministically", async () => {
+    const warnSpy = jest.spyOn(console, "warn").mockImplementation(() => {});
+    const { session } = createSessionWithEvents({
+      throwOnOnEvent: "Network.requestWillBeSent",
+      onErrorValue: { reason: "attach object failure" },
+    });
+    const cdpClient: CDPClient = {
+      rootSession: session,
+      createSession: async () => session,
+      acquireSession: async () => session,
+      dispose: async () => undefined,
+    };
+    getCDPClient.mockResolvedValue(cdpClient);
+    getOrCreateFrameContextManager.mockReturnValue({
+      setDebug: jest.fn(),
+    });
+    getDebugOptions.mockReturnValue({
+      enabled: false,
+      traceWait: false,
+    });
+
+    const page = {
+      context: () => ({}),
+    } as never;
+
+    try {
+      const waitPromise = waitForSettledDOM(page, 700);
+      await Promise.resolve();
+      await Promise.resolve();
+      await jest.advanceTimersByTimeAsync(800);
+      await waitPromise;
+
+      const attachWarning = String(warnSpy.mock.calls[0]?.[0] ?? "");
+      expect(attachWarning).toContain('{"reason":"attach object failure"}');
+    } finally {
+      warnSpy.mockRestore();
+    }
+  });
+
+  it("sanitizes and truncates listener detach getter diagnostics", async () => {
+    const warnSpy = jest.spyOn(console, "warn").mockImplementation(() => {});
+    const { session } = createSessionWithEvents();
+    const trappedSession = new Proxy(session, {
+      get: (target, prop, receiver) => {
+        if (prop === "off") {
+          throw new Error(`off getter\u0000\n${"x".repeat(10_000)}`);
+        }
+        return Reflect.get(target, prop, receiver);
+      },
+    }) as CDPSession;
+    const cdpClient: CDPClient = {
+      rootSession: trappedSession,
+      createSession: async () => trappedSession,
+      acquireSession: async () => trappedSession,
+      dispose: async () => undefined,
+    };
+    getCDPClient.mockResolvedValue(cdpClient);
+    getOrCreateFrameContextManager.mockReturnValue({
+      setDebug: jest.fn(),
+    });
+    getDebugOptions.mockReturnValue({
+      enabled: false,
+      traceWait: false,
+    });
+
+    const page = {
+      context: () => ({}),
+    } as never;
+
+    try {
+      const waitPromise = waitForSettledDOM(page, 2000);
+      await Promise.resolve();
+      await Promise.resolve();
+      await jest.advanceTimersByTimeAsync(600);
+      const stats = await waitPromise;
+
+      const detachWarning = String(
+        warnSpy.mock.calls.find((call) =>
+          String(call[0] ?? "").includes("Failed to detach listener")
+        )?.[0] ?? ""
+      );
+      expect(detachWarning).toContain("[truncated");
+      expect(detachWarning).not.toContain("\u0000");
+      expect(detachWarning).not.toContain("\n");
+      expect(stats.resolvedByTimeout).toBe(false);
+      expect(stats.requestsSeen).toBe(0);
+    } finally {
+      warnSpy.mockRestore();
+    }
+  });
+
+  it("sanitizes and truncates listener detach diagnostics", async () => {
+    const warnSpy = jest.spyOn(console, "warn").mockImplementation(() => {});
+    const { session } = createSessionWithEvents({
+      throwOnOffEvent: "Network.loadingFinished",
+      offErrorMessage: `detach\u0000\n${"x".repeat(10_000)}`,
+    });
+    const cdpClient: CDPClient = {
+      rootSession: session,
+      createSession: async () => session,
+      acquireSession: async () => session,
+      dispose: async () => undefined,
+    };
+    getCDPClient.mockResolvedValue(cdpClient);
+    getOrCreateFrameContextManager.mockReturnValue({
+      setDebug: jest.fn(),
+    });
+    getDebugOptions.mockReturnValue({
+      enabled: false,
+      traceWait: false,
+    });
+
+    const page = {
+      context: () => ({}),
+    } as never;
+
+    try {
+      const waitPromise = waitForSettledDOM(page, 2000);
+      await Promise.resolve();
+      await Promise.resolve();
+      await jest.advanceTimersByTimeAsync(600);
+      const stats = await waitPromise;
+
+      const detachWarning = String(warnSpy.mock.calls[0]?.[0] ?? "");
+      expect(detachWarning).toContain("Failed to detach listener");
+      expect(detachWarning).toContain("[truncated");
+      expect(detachWarning).not.toContain("\u0000");
+      expect(detachWarning).not.toContain("\n");
+      expect(stats.resolvedByTimeout).toBe(false);
+      expect(stats.requestsSeen).toBe(0);
+    } finally {
+      warnSpy.mockRestore();
+    }
+  });
+});
diff --git a/src/utils/waitForSettledDOM.ts b/src/utils/waitForSettledDOM.ts
index 9cbc03c8..ed01cbc5 100644
--- a/src/utils/waitForSettledDOM.ts
+++ b/src/utils/waitForSettledDOM.ts
@@ -14,20 +14,160 @@
  * 6. Global timeout ensures we don't wait forever
  */
 
-import type { BrowserContext, Page } from "playwright-core";
+import type { Page } from "playwright-core";
 import { getCDPClient, getOrCreateFrameContextManager } from "@/cdp";
 import type { CDPSession } from "@/cdp";
 import { Protocol } from "devtools-protocol";
 import { performance } from "perf_hooks";
 import { getDebugOptions } from "@/debug/options";
+import { formatUnknownError } from "@/utils";
 
 const NETWORK_IDLE_THRESHOLD_MS = 500;
 const STALLED_REQUEST_MS = 2000;
 const STALLED_SWEEP_INTERVAL_MS = 500;
+const MAX_WAIT_DIAGNOSTIC_CHARS = 400;
+const MAX_WAIT_IDENTIFIER_CHARS = 200;
+const DEFAULT_WAIT_TIMEOUT_MS = 10_000;
+const MAX_WAIT_TIMEOUT_MS = 120_000;
 const ENV_TRACE_WAIT =
   process.env.HYPERAGENT_TRACE_WAIT === "1" ||
   process.env.HYPERAGENT_TRACE_WAIT === "true";
 
+function sanitizeWaitDiagnosticText(value: string): string {
+  if (value.length === 0) {
+    return value;
+  }
+  const withoutControlChars = Array.from(value, (char) => {
+    const code = char.charCodeAt(0);
+    return (code >= 0 && code < 32) || code === 127 ? " " : char;
+  }).join("");
+  return withoutControlChars.replace(/\s+/g, " ").trim();
+}
+
+function truncateWaitDiagnostic(value: string, maxChars: number): string {
+  if (value.length <= maxChars) {
+    return value;
+  }
+  const omittedChars = value.length - maxChars;
+  return `${value.slice(0, maxChars)}... [truncated ${omittedChars} chars]`;
+}
+
+function formatWaitIdentifier(value: unknown): string {
+  if (typeof value !== "string") {
+    return "unknown";
+  }
+  const normalized = sanitizeWaitDiagnosticText(value);
+  if (normalized.length === 0) {
+    return "unknown";
+  }
+  return truncateWaitDiagnostic(normalized, MAX_WAIT_IDENTIFIER_CHARS);
+}
+
+function formatWaitUrl(value: unknown): string {
+  if (typeof value !== "string") {
+    return "unknown";
+  }
+  const normalized = sanitizeWaitDiagnosticText(value);
+  if (normalized.length === 0) {
+    return "unknown";
+  }
+  return truncateWaitDiagnostic(normalized, MAX_WAIT_DIAGNOSTIC_CHARS);
+}
+
+function formatWaitDiagnostic(value: unknown): string {
+  const normalized = sanitizeWaitDiagnosticText(formatUnknownError(value));
+  if (normalized.length === 0) {
+    return "unknown error";
+  }
+  return truncateWaitDiagnostic(normalized, MAX_WAIT_DIAGNOSTIC_CHARS);
+}
+
+function attachSessionListener<TPayload extends unknown[]>(
+  session: CDPSession,
+  event: string,
+  handler: (...payload: TPayload) => void
+): boolean {
+  let onMethod: unknown;
+  try {
+    onMethod = (session as unknown as { on?: unknown }).on;
+  } catch (error) {
+    console.warn(
+      `[waitForSettledDOM] Failed to attach listener ${formatWaitIdentifier(
+        event
+      )}: ${formatWaitDiagnostic(error)}`
+    );
+    return false;
+  }
+  if (typeof onMethod !== "function") {
+    console.warn(
+      `[waitForSettledDOM] Failed to attach listener ${formatWaitIdentifier(
+        event
+      )}: listener method unavailable`
+    );
+    return false;
+  }
+  try {
+    (
+      onMethod as (
+        this: CDPSession,
+        event: string,
+        handler: (...payload: unknown[]) => void
+      ) => void
+    ).call(session, event, handler as (...payload: unknown[]) => void);
+    return true;
+  } catch (error) {
+    console.warn(
+      `[waitForSettledDOM] Failed to attach listener ${formatWaitIdentifier(
+        event
+      )}: ${formatWaitDiagnostic(error)}`
+    );
+    return false;
+  }
+}
+
+function detachSessionListener<TPayload extends unknown[]>(
+  session: CDPSession,
+  event: string,
+  handler: (...payload: TPayload) => void
+): void {
+  let offMethod: unknown;
+  try {
+    offMethod = (session as unknown as { off?: unknown }).off;
+  } catch (error) {
+    console.warn(
+      `[waitForSettledDOM] Failed to detach listener ${formatWaitIdentifier(
+        event
+      )}: ${formatWaitDiagnostic(error)}`
+    );
+    return;
+  }
+  if (typeof offMethod !== "function") {
+    return;
+  }
+  try {
+    (
+      offMethod as (
+        this: CDPSession,
+        event: string,
+        handler: (...payload: unknown[]) => void
+      ) => void
+    ).call(session, event, handler as (...payload: unknown[]) => void);
+  } catch (error) {
+    console.warn(
+      `[waitForSettledDOM] Failed to detach listener ${formatWaitIdentifier(
+        event
+      )}: ${formatWaitDiagnostic(error)}`
+    );
+  }
+}
+
+function normalizeWaitTimeoutMs(value: number): number {
+  if (typeof value !== "number" || !Number.isFinite(value) || value <= 0) {
+    return DEFAULT_WAIT_TIMEOUT_MS;
+  }
+  return Math.min(Math.floor(value), MAX_WAIT_TIMEOUT_MS);
+}
+
 export interface LifecycleOptions {
   waitUntil?: Array<"domcontentloaded" | "load" | "networkidle">;
   timeoutMs?: number;
@@ -43,17 +183,107 @@ export interface WaitForSettledStats {
   forcedDrops: number;
 }
 
+export interface WaitForSettledOptions {
+  filterAdTrackingFrames?: boolean;
+}
+
+function readWaitDebugOptions(): { enabled: boolean; traceWait: boolean } {
+  try {
+    const value = getDebugOptions();
+    return {
+      enabled: value.enabled === true,
+      traceWait: value.traceWait === true,
+    };
+  } catch (error) {
+    console.warn(
+      `[waitForSettledDOM] Failed to read debug options: ${formatWaitDiagnostic(
+        error
+      )}`
+    );
+    return {
+      enabled: false,
+      traceWait: false,
+    };
+  }
+}
+
+function hasRecordingVideoContext(page: Page): boolean {
+  let contextMethod: unknown;
+  try {
+    contextMethod = (
+      page as unknown as { context?: unknown }
+    ).context;
+  } catch (error) {
+    console.warn(
+      `[waitForSettledDOM] Failed to read page context method: ${formatWaitDiagnostic(
+        error
+      )}`
+    );
+    return false;
+  }
+  if (typeof contextMethod !== "function") {
+    return false;
+  }
+
+  let context: unknown;
+  try {
+    context = (contextMethod as (this: Page) => unknown).call(page);
+  } catch (error) {
+    console.warn(
+      `[waitForSettledDOM] Failed to read page context: ${formatWaitDiagnostic(
+        error
+      )}`
+    );
+    return false;
+  }
+  if (!context || typeof context !== "object") {
+    return false;
+  }
+  try {
+    const options = (context as { _options?: { recordVideo?: unknown } })._options;
+    return !!options?.recordVideo;
+  } catch (error) {
+    console.warn(
+      `[waitForSettledDOM] Failed to read context options: ${formatWaitDiagnostic(
+        error
+      )}`
+    );
+    return false;
+  }
+}
+
+function safeReadWaitOptionField(
+  options: unknown,
+  field: keyof WaitForSettledOptions
+): unknown {
+  if (!options || (typeof options !== "object" && typeof options !== "function")) {
+    return undefined;
+  }
+  try {
+    return (options as Record<string, unknown>)[field];
+  } catch {
+    return undefined;
+  }
+}
+
 export async function waitForSettledDOM(
   page: Page,
-  timeoutMs: number = 10000
+  timeoutMs: number = DEFAULT_WAIT_TIMEOUT_MS,
+  options: WaitForSettledOptions = {}
 ): Promise<WaitForSettledStats> {
-  const ctx = page.context() as BrowserContext & {
-    _options?: { recordVideo?: unknown };
-  };
-  const debugOptions = getDebugOptions();
+  const normalizedTimeoutMs = normalizeWaitTimeoutMs(timeoutMs);
+  const filterAdTrackingFramesOption = safeReadWaitOptionField(
+    options,
+    "filterAdTrackingFrames"
+  );
+  const filterAdTrackingFrames =
+    typeof filterAdTrackingFramesOption === "boolean"
+      ? filterAdTrackingFramesOption
+      : undefined;
+  const debugOptions = readWaitDebugOptions();
   const traceWaitFlag =
     (debugOptions.enabled && debugOptions.traceWait) || ENV_TRACE_WAIT;
-  const traceWait = traceWaitFlag || !!ctx._options?.recordVideo;
+  const traceWait = traceWaitFlag || hasRecordingVideoContext(page);
   const totalStart = performance.now();
 
   // Currently we only wait for network idle (historical behavior). Hook exists if we add DOM states later.
@@ -68,14 +298,36 @@ export async function waitForSettledDOM(
 
   const cdpClient = await getCDPClient(page);
   const manager = getOrCreateFrameContextManager(cdpClient);
-  manager.setDebug(traceWait);
+  try {
+    manager.setDebug(traceWait);
+  } catch (error) {
+    console.warn(
+      `[waitForSettledDOM] Failed to configure frame manager debug flag: ${formatWaitDiagnostic(
+        error
+      )}`
+    );
+  }
+  if (
+    typeof manager.setFrameFilteringEnabled === "function" &&
+    typeof filterAdTrackingFrames === "boolean"
+  ) {
+    try {
+      manager.setFrameFilteringEnabled(filterAdTrackingFrames);
+    } catch (error) {
+      console.warn(
+        `[waitForSettledDOM] Failed to configure frame filtering: ${formatWaitDiagnostic(
+          error
+        )}`
+      );
+    }
+  }
 
   const lifecycleSession = await cdpClient.acquireSession("lifecycle");
 
   const networkStart = performance.now();
   const stats = await waitForNetworkIdle(lifecycleSession, {
-    timeoutMs,
-    trace: traceWaitFlag,
+    timeoutMs: normalizedTimeoutMs,
+    trace: traceWait,
   });
   const networkDuration = performance.now() - networkStart;
 
@@ -135,8 +387,12 @@ async function waitForNetworkIdle(
   await new Promise<void>((resolve) => {
     const requestMeta = new Map<string, { url?: string; start: number }>();
     let stalledSweepTimer: NodeJS.Timeout | null = null;
+    let listenerSetupFailed = false;
 
     const maybeResolve = () => {
+      if (listenerSetupFailed) {
+        return;
+      }
       if (inflight.size === 0 && !quietTimer) {
         quietTimer = setTimeout(
           () => resolveDone(false),
@@ -154,11 +410,9 @@ async function waitForNetworkIdle(
     };
 
     const cleanup = () => {
-      if (session.off) {
-        session.off("Network.requestWillBeSent", onRequestWillBeSent);
-        session.off("Network.loadingFinished", onLoadingFinished);
-        session.off("Network.loadingFailed", onLoadingFailed);
-      }
+      detachSessionListener(session, "Network.requestWillBeSent", onRequestWillBeSent);
+      detachSessionListener(session, "Network.loadingFinished", onLoadingFinished);
+      detachSessionListener(session, "Network.loadingFailed", onLoadingFailed);
       if (stalledSweepTimer) {
         clearInterval(stalledSweepTimer);
         stalledSweepTimer = null;
@@ -198,9 +452,30 @@ async function waitForNetworkIdle(
       finishRequest(event.requestId);
     };
 
-    session.on("Network.requestWillBeSent", onRequestWillBeSent);
-    session.on("Network.loadingFinished", onLoadingFinished);
-    session.on("Network.loadingFailed", onLoadingFailed);
+    const requestListenerAttached = attachSessionListener(
+      session,
+      "Network.requestWillBeSent",
+      onRequestWillBeSent
+    );
+    const loadingFinishedListenerAttached = attachSessionListener(
+      session,
+      "Network.loadingFinished",
+      onLoadingFinished
+    );
+    const loadingFailedListenerAttached = attachSessionListener(
+      session,
+      "Network.loadingFailed",
+      onLoadingFailed
+    );
+    listenerSetupFailed =
+      !requestListenerAttached ||
+      !loadingFinishedListenerAttached ||
+      !loadingFailedListenerAttached;
+    if (listenerSetupFailed) {
+      console.warn(
+        "[waitForSettledDOM] Network listeners could not be fully attached; falling back to timeout-based settle."
+      );
+    }
 
     stalledSweepTimer = setInterval(() => {
       if (!requestMeta.size) return;
@@ -211,7 +486,11 @@ async function waitForNetworkIdle(
             stats.forcedDrops += 1;
             if (trace) {
               console.warn(
-                `[waitForSettledDOM] Forcing completion of stalled request ${id} (age=${now - meta.start}ms url=${meta.url ?? "unknown"})`
+                `[waitForSettledDOM] Forcing completion of stalled request ${formatWaitIdentifier(
+                  id
+                )} (age=${now - meta.start}ms url=${formatWaitUrl(
+                  meta.url
+                )})`
               );
             }
             requestMeta.delete(id);
diff --git a/yarn.lock b/yarn.lock
index 78dfaa02..0a023193 100644
--- a/yarn.lock
+++ b/yarn.lock
@@ -9,11 +9,279 @@
   dependencies:
     json-schema-to-ts "^3.1.1"
 
+"@babel/code-frame@^7.0.0", "@babel/code-frame@^7.27.1", "@babel/code-frame@^7.28.6", "@babel/code-frame@^7.29.0":
+  version "7.29.0"
+  resolved "https://registry.yarnpkg.com/@babel/code-frame/-/code-frame-7.29.0.tgz#7cd7a59f15b3cc0dcd803038f7792712a7d0b15c"
+  integrity sha512-9NhCeYjq9+3uxgdtp20LSiJXJvN0FeCtNGpJxuMFZ1Kv3cWUNb6DOhJwUvcVCzKGR66cw4njwM6hrJLqgOwbcw==
+  dependencies:
+    "@babel/helper-validator-identifier" "^7.28.5"
+    js-tokens "^4.0.0"
+    picocolors "^1.1.1"
+
+"@babel/compat-data@^7.28.6":
+  version "7.29.0"
+  resolved "https://registry.yarnpkg.com/@babel/compat-data/-/compat-data-7.29.0.tgz#00d03e8c0ac24dd9be942c5370990cbe1f17d88d"
+  integrity sha512-T1NCJqT/j9+cn8fvkt7jtwbLBfLC/1y1c7NtCeXFRgzGTsafi68MRv8yzkYSapBnFA6L3U2VSc02ciDzoAJhJg==
+
+"@babel/core@^7.23.9", "@babel/core@^7.27.4":
+  version "7.29.0"
+  resolved "https://registry.yarnpkg.com/@babel/core/-/core-7.29.0.tgz#5286ad785df7f79d656e88ce86e650d16ca5f322"
+  integrity sha512-CGOfOJqWjg2qW/Mb6zNsDm+u5vFQ8DxXfbM09z69p5Z6+mE1ikP2jUXw+j42Pf1XTYED2Rni5f95npYeuwMDQA==
+  dependencies:
+    "@babel/code-frame" "^7.29.0"
+    "@babel/generator" "^7.29.0"
+    "@babel/helper-compilation-targets" "^7.28.6"
+    "@babel/helper-module-transforms" "^7.28.6"
+    "@babel/helpers" "^7.28.6"
+    "@babel/parser" "^7.29.0"
+    "@babel/template" "^7.28.6"
+    "@babel/traverse" "^7.29.0"
+    "@babel/types" "^7.29.0"
+    "@jridgewell/remapping" "^2.3.5"
+    convert-source-map "^2.0.0"
+    debug "^4.1.0"
+    gensync "^1.0.0-beta.2"
+    json5 "^2.2.3"
+    semver "^6.3.1"
+
+"@babel/generator@^7.27.5", "@babel/generator@^7.29.0":
+  version "7.29.1"
+  resolved "https://registry.yarnpkg.com/@babel/generator/-/generator-7.29.1.tgz#d09876290111abbb00ef962a7b83a5307fba0d50"
+  integrity sha512-qsaF+9Qcm2Qv8SRIMMscAvG4O3lJ0F1GuMo5HR/Bp02LopNgnZBC/EkbevHFeGs4ls/oPz9v+Bsmzbkbe+0dUw==
+  dependencies:
+    "@babel/parser" "^7.29.0"
+    "@babel/types" "^7.29.0"
+    "@jridgewell/gen-mapping" "^0.3.12"
+    "@jridgewell/trace-mapping" "^0.3.28"
+    jsesc "^3.0.2"
+
+"@babel/helper-compilation-targets@^7.28.6":
+  version "7.28.6"
+  resolved "https://registry.yarnpkg.com/@babel/helper-compilation-targets/-/helper-compilation-targets-7.28.6.tgz#32c4a3f41f12ed1532179b108a4d746e105c2b25"
+  integrity sha512-JYtls3hqi15fcx5GaSNL7SCTJ2MNmjrkHXg4FSpOA/grxK8KwyZ5bubHsCq8FXCkua6xhuaaBit+3b7+VZRfcA==
+  dependencies:
+    "@babel/compat-data" "^7.28.6"
+    "@babel/helper-validator-option" "^7.27.1"
+    browserslist "^4.24.0"
+    lru-cache "^5.1.1"
+    semver "^6.3.1"
+
+"@babel/helper-globals@^7.28.0":
+  version "7.28.0"
+  resolved "https://registry.yarnpkg.com/@babel/helper-globals/-/helper-globals-7.28.0.tgz#b9430df2aa4e17bc28665eadeae8aa1d985e6674"
+  integrity sha512-+W6cISkXFa1jXsDEdYA8HeevQT/FULhxzR99pxphltZcVaugps53THCeiWA8SguxxpSp3gKPiuYfSWopkLQ4hw==
+
+"@babel/helper-module-imports@^7.28.6":
+  version "7.28.6"
+  resolved "https://registry.yarnpkg.com/@babel/helper-module-imports/-/helper-module-imports-7.28.6.tgz#60632cbd6ffb70b22823187201116762a03e2d5c"
+  integrity sha512-l5XkZK7r7wa9LucGw9LwZyyCUscb4x37JWTPz7swwFE/0FMQAGpiWUZn8u9DzkSBWEcK25jmvubfpw2dnAMdbw==
+  dependencies:
+    "@babel/traverse" "^7.28.6"
+    "@babel/types" "^7.28.6"
+
+"@babel/helper-module-transforms@^7.28.6":
+  version "7.28.6"
+  resolved "https://registry.yarnpkg.com/@babel/helper-module-transforms/-/helper-module-transforms-7.28.6.tgz#9312d9d9e56edc35aeb6e95c25d4106b50b9eb1e"
+  integrity sha512-67oXFAYr2cDLDVGLXTEABjdBJZ6drElUSI7WKp70NrpyISso3plG9SAGEF6y7zbha/wOzUByWWTJvEDVNIUGcA==
+  dependencies:
+    "@babel/helper-module-imports" "^7.28.6"
+    "@babel/helper-validator-identifier" "^7.28.5"
+    "@babel/traverse" "^7.28.6"
+
+"@babel/helper-plugin-utils@^7.0.0", "@babel/helper-plugin-utils@^7.10.4", "@babel/helper-plugin-utils@^7.12.13", "@babel/helper-plugin-utils@^7.14.5", "@babel/helper-plugin-utils@^7.28.6", "@babel/helper-plugin-utils@^7.8.0":
+  version "7.28.6"
+  resolved "https://registry.yarnpkg.com/@babel/helper-plugin-utils/-/helper-plugin-utils-7.28.6.tgz#6f13ea251b68c8532e985fd532f28741a8af9ac8"
+  integrity sha512-S9gzZ/bz83GRysI7gAD4wPT/AI3uCnY+9xn+Mx/KPs2JwHJIz1W8PZkg2cqyt3RNOBM8ejcXhV6y8Og7ly/Dug==
+
+"@babel/helper-string-parser@^7.27.1":
+  version "7.27.1"
+  resolved "https://registry.yarnpkg.com/@babel/helper-string-parser/-/helper-string-parser-7.27.1.tgz#54da796097ab19ce67ed9f88b47bb2ec49367687"
+  integrity sha512-qMlSxKbpRlAridDExk92nSobyDdpPijUq2DW6oDnUqd0iOGxmQjyqhMIihI9+zv4LPyZdRje2cavWPbCbWm3eA==
+
+"@babel/helper-validator-identifier@^7.28.5":
+  version "7.28.5"
+  resolved "https://registry.yarnpkg.com/@babel/helper-validator-identifier/-/helper-validator-identifier-7.28.5.tgz#010b6938fab7cb7df74aa2bbc06aa503b8fe5fb4"
+  integrity sha512-qSs4ifwzKJSV39ucNjsvc6WVHs6b7S03sOh2OcHF9UHfVPqWWALUsNUVzhSBiItjRZoLHx7nIarVjqKVusUZ1Q==
+
+"@babel/helper-validator-option@^7.27.1":
+  version "7.27.1"
+  resolved "https://registry.yarnpkg.com/@babel/helper-validator-option/-/helper-validator-option-7.27.1.tgz#fa52f5b1e7db1ab049445b421c4471303897702f"
+  integrity sha512-YvjJow9FxbhFFKDSuFnVCe2WxXk1zWc22fFePVNEaWJEu8IrZVlda6N0uHwzZrUM1il7NC9Mlp4MaJYbYd9JSg==
+
+"@babel/helpers@^7.28.6":
+  version "7.28.6"
+  resolved "https://registry.yarnpkg.com/@babel/helpers/-/helpers-7.28.6.tgz#fca903a313ae675617936e8998b814c415cbf5d7"
+  integrity sha512-xOBvwq86HHdB7WUDTfKfT/Vuxh7gElQ+Sfti2Cy6yIWNW05P8iUslOVcZ4/sKbE+/jQaukQAdz/gf3724kYdqw==
+  dependencies:
+    "@babel/template" "^7.28.6"
+    "@babel/types" "^7.28.6"
+
+"@babel/parser@^7.1.0", "@babel/parser@^7.20.7", "@babel/parser@^7.23.9", "@babel/parser@^7.28.6", "@babel/parser@^7.29.0":
+  version "7.29.0"
+  resolved "https://registry.yarnpkg.com/@babel/parser/-/parser-7.29.0.tgz#669ef345add7d057e92b7ed15f0bac07611831b6"
+  integrity sha512-IyDgFV5GeDUVX4YdF/3CPULtVGSXXMLh1xVIgdCgxApktqnQV0r7/8Nqthg+8YLGaAtdyIlo2qIdZrbCv4+7ww==
+  dependencies:
+    "@babel/types" "^7.29.0"
+
+"@babel/plugin-syntax-async-generators@^7.8.4":
+  version "7.8.4"
+  resolved "https://registry.yarnpkg.com/@babel/plugin-syntax-async-generators/-/plugin-syntax-async-generators-7.8.4.tgz#a983fb1aeb2ec3f6ed042a210f640e90e786fe0d"
+  integrity sha512-tycmZxkGfZaxhMRbXlPXuVFpdWlXpir2W4AMhSJgRKzk/eDlIXOhb2LHWoLpDF7TEHylV5zNhykX6KAgHJmTNw==
+  dependencies:
+    "@babel/helper-plugin-utils" "^7.8.0"
+
+"@babel/plugin-syntax-bigint@^7.8.3":
+  version "7.8.3"
+  resolved "https://registry.yarnpkg.com/@babel/plugin-syntax-bigint/-/plugin-syntax-bigint-7.8.3.tgz#4c9a6f669f5d0cdf1b90a1671e9a146be5300cea"
+  integrity sha512-wnTnFlG+YxQm3vDxpGE57Pj0srRU4sHE/mDkt1qv2YJJSeUAec2ma4WLUnUPeKjyrfntVwe/N6dCXpU+zL3Npg==
+  dependencies:
+    "@babel/helper-plugin-utils" "^7.8.0"
+
+"@babel/plugin-syntax-class-properties@^7.12.13":
+  version "7.12.13"
+  resolved "https://registry.yarnpkg.com/@babel/plugin-syntax-class-properties/-/plugin-syntax-class-properties-7.12.13.tgz#b5c987274c4a3a82b89714796931a6b53544ae10"
+  integrity sha512-fm4idjKla0YahUNgFNLCB0qySdsoPiZP3iQE3rky0mBUtMZ23yDJ9SJdg6dXTSDnulOVqiF3Hgr9nbXvXTQZYA==
+  dependencies:
+    "@babel/helper-plugin-utils" "^7.12.13"
+
+"@babel/plugin-syntax-class-static-block@^7.14.5":
+  version "7.14.5"
+  resolved "https://registry.yarnpkg.com/@babel/plugin-syntax-class-static-block/-/plugin-syntax-class-static-block-7.14.5.tgz#195df89b146b4b78b3bf897fd7a257c84659d406"
+  integrity sha512-b+YyPmr6ldyNnM6sqYeMWE+bgJcJpO6yS4QD7ymxgH34GBPNDM/THBh8iunyvKIZztiwLH4CJZ0RxTk9emgpjw==
+  dependencies:
+    "@babel/helper-plugin-utils" "^7.14.5"
+
+"@babel/plugin-syntax-import-attributes@^7.24.7":
+  version "7.28.6"
+  resolved "https://registry.yarnpkg.com/@babel/plugin-syntax-import-attributes/-/plugin-syntax-import-attributes-7.28.6.tgz#b71d5914665f60124e133696f17cd7669062c503"
+  integrity sha512-jiLC0ma9XkQT3TKJ9uYvlakm66Pamywo+qwL+oL8HJOvc6TWdZXVfhqJr8CCzbSGUAbDOzlGHJC1U+vRfLQDvw==
+  dependencies:
+    "@babel/helper-plugin-utils" "^7.28.6"
+
+"@babel/plugin-syntax-import-meta@^7.10.4":
+  version "7.10.4"
+  resolved "https://registry.yarnpkg.com/@babel/plugin-syntax-import-meta/-/plugin-syntax-import-meta-7.10.4.tgz#ee601348c370fa334d2207be158777496521fd51"
+  integrity sha512-Yqfm+XDx0+Prh3VSeEQCPU81yC+JWZ2pDPFSS4ZdpfZhp4MkFMaDC1UqseovEKwSUpnIL7+vK+Clp7bfh0iD7g==
+  dependencies:
+    "@babel/helper-plugin-utils" "^7.10.4"
+
+"@babel/plugin-syntax-json-strings@^7.8.3":
+  version "7.8.3"
+  resolved "https://registry.yarnpkg.com/@babel/plugin-syntax-json-strings/-/plugin-syntax-json-strings-7.8.3.tgz#01ca21b668cd8218c9e640cb6dd88c5412b2c96a"
+  integrity sha512-lY6kdGpWHvjoe2vk4WrAapEuBR69EMxZl+RoGRhrFGNYVK8mOPAW8VfbT/ZgrFbXlDNiiaxQnAtgVCZ6jv30EA==
+  dependencies:
+    "@babel/helper-plugin-utils" "^7.8.0"
+
+"@babel/plugin-syntax-jsx@^7.27.1":
+  version "7.28.6"
+  resolved "https://registry.yarnpkg.com/@babel/plugin-syntax-jsx/-/plugin-syntax-jsx-7.28.6.tgz#f8ca28bbd84883b5fea0e447c635b81ba73997ee"
+  integrity sha512-wgEmr06G6sIpqr8YDwA2dSRTE3bJ+V0IfpzfSY3Lfgd7YWOaAdlykvJi13ZKBt8cZHfgH1IXN+CL656W3uUa4w==
+  dependencies:
+    "@babel/helper-plugin-utils" "^7.28.6"
+
+"@babel/plugin-syntax-logical-assignment-operators@^7.10.4":
+  version "7.10.4"
+  resolved "https://registry.yarnpkg.com/@babel/plugin-syntax-logical-assignment-operators/-/plugin-syntax-logical-assignment-operators-7.10.4.tgz#ca91ef46303530448b906652bac2e9fe9941f699"
+  integrity sha512-d8waShlpFDinQ5MtvGU9xDAOzKH47+FFoney2baFIoMr952hKOLp1HR7VszoZvOsV/4+RRszNY7D17ba0te0ig==
+  dependencies:
+    "@babel/helper-plugin-utils" "^7.10.4"
+
+"@babel/plugin-syntax-nullish-coalescing-operator@^7.8.3":
+  version "7.8.3"
+  resolved "https://registry.yarnpkg.com/@babel/plugin-syntax-nullish-coalescing-operator/-/plugin-syntax-nullish-coalescing-operator-7.8.3.tgz#167ed70368886081f74b5c36c65a88c03b66d1a9"
+  integrity sha512-aSff4zPII1u2QD7y+F8oDsz19ew4IGEJg9SVW+bqwpwtfFleiQDMdzA/R+UlWDzfnHFCxxleFT0PMIrR36XLNQ==
+  dependencies:
+    "@babel/helper-plugin-utils" "^7.8.0"
+
+"@babel/plugin-syntax-numeric-separator@^7.10.4":
+  version "7.10.4"
+  resolved "https://registry.yarnpkg.com/@babel/plugin-syntax-numeric-separator/-/plugin-syntax-numeric-separator-7.10.4.tgz#b9b070b3e33570cd9fd07ba7fa91c0dd37b9af97"
+  integrity sha512-9H6YdfkcK/uOnY/K7/aA2xpzaAgkQn37yzWUMRK7OaPOqOpGS1+n0H5hxT9AUw9EsSjPW8SVyMJwYRtWs3X3ug==
+  dependencies:
+    "@babel/helper-plugin-utils" "^7.10.4"
+
+"@babel/plugin-syntax-object-rest-spread@^7.8.3":
+  version "7.8.3"
+  resolved "https://registry.yarnpkg.com/@babel/plugin-syntax-object-rest-spread/-/plugin-syntax-object-rest-spread-7.8.3.tgz#60e225edcbd98a640332a2e72dd3e66f1af55871"
+  integrity sha512-XoqMijGZb9y3y2XskN+P1wUGiVwWZ5JmoDRwx5+3GmEplNyVM2s2Dg8ILFQm8rWM48orGy5YpI5Bl8U1y7ydlA==
+  dependencies:
+    "@babel/helper-plugin-utils" "^7.8.0"
+
+"@babel/plugin-syntax-optional-catch-binding@^7.8.3":
+  version "7.8.3"
+  resolved "https://registry.yarnpkg.com/@babel/plugin-syntax-optional-catch-binding/-/plugin-syntax-optional-catch-binding-7.8.3.tgz#6111a265bcfb020eb9efd0fdfd7d26402b9ed6c1"
+  integrity sha512-6VPD0Pc1lpTqw0aKoeRTMiB+kWhAoT24PA+ksWSBrFtl5SIRVpZlwN3NNPQjehA2E/91FV3RjLWoVTglWcSV3Q==
+  dependencies:
+    "@babel/helper-plugin-utils" "^7.8.0"
+
+"@babel/plugin-syntax-optional-chaining@^7.8.3":
+  version "7.8.3"
+  resolved "https://registry.yarnpkg.com/@babel/plugin-syntax-optional-chaining/-/plugin-syntax-optional-chaining-7.8.3.tgz#4f69c2ab95167e0180cd5336613f8c5788f7d48a"
+  integrity sha512-KoK9ErH1MBlCPxV0VANkXW2/dw4vlbGDrFgz8bmUsBGYkFRcbRwMh6cIJubdPrkxRwuGdtCk0v/wPTKbQgBjkg==
+  dependencies:
+    "@babel/helper-plugin-utils" "^7.8.0"
+
+"@babel/plugin-syntax-private-property-in-object@^7.14.5":
+  version "7.14.5"
+  resolved "https://registry.yarnpkg.com/@babel/plugin-syntax-private-property-in-object/-/plugin-syntax-private-property-in-object-7.14.5.tgz#0dc6671ec0ea22b6e94a1114f857970cd39de1ad"
+  integrity sha512-0wVnp9dxJ72ZUJDV27ZfbSj6iHLoytYZmh3rFcxNnvsJF3ktkzLDZPy/mA17HGsaQT3/DQsWYX1f1QGWkCoVUg==
+  dependencies:
+    "@babel/helper-plugin-utils" "^7.14.5"
+
+"@babel/plugin-syntax-top-level-await@^7.14.5":
+  version "7.14.5"
+  resolved "https://registry.yarnpkg.com/@babel/plugin-syntax-top-level-await/-/plugin-syntax-top-level-await-7.14.5.tgz#c1cfdadc35a646240001f06138247b741c34d94c"
+  integrity sha512-hx++upLv5U1rgYfwe1xBQUhRmU41NEvpUvrp8jkrSCdvGSnM5/qdRMtylJ6PG5OFkBaHkbTAKTnd3/YyESRHFw==
+  dependencies:
+    "@babel/helper-plugin-utils" "^7.14.5"
+
+"@babel/plugin-syntax-typescript@^7.27.1":
+  version "7.28.6"
+  resolved "https://registry.yarnpkg.com/@babel/plugin-syntax-typescript/-/plugin-syntax-typescript-7.28.6.tgz#c7b2ddf1d0a811145b1de800d1abd146af92e3a2"
+  integrity sha512-+nDNmQye7nlnuuHDboPbGm00Vqg3oO8niRRL27/4LYHUsHYh0zJ1xWOz0uRwNFmM1Avzk8wZbc6rdiYhomzv/A==
+  dependencies:
+    "@babel/helper-plugin-utils" "^7.28.6"
+
 "@babel/runtime@^7.18.3":
   version "7.28.4"
   resolved "https://registry.yarnpkg.com/@babel/runtime/-/runtime-7.28.4.tgz#a70226016fabe25c5783b2f22d3e1c9bc5ca3326"
   integrity sha512-Q/N6JNWvIvPnLDvjlE1OUBLPQHH6l3CltCEsHIujp45zQUSSh8K+gHnaEX45yAT1nyngnINhvWtzN+Nb9D8RAQ==
 
+"@babel/template@^7.28.6":
+  version "7.28.6"
+  resolved "https://registry.yarnpkg.com/@babel/template/-/template-7.28.6.tgz#0e7e56ecedb78aeef66ce7972b082fce76a23e57"
+  integrity sha512-YA6Ma2KsCdGb+WC6UpBVFJGXL58MDA6oyONbjyF/+5sBgxY/dwkhLogbMT2GXXyU84/IhRw/2D1Os1B/giz+BQ==
+  dependencies:
+    "@babel/code-frame" "^7.28.6"
+    "@babel/parser" "^7.28.6"
+    "@babel/types" "^7.28.6"
+
+"@babel/traverse@^7.28.6", "@babel/traverse@^7.29.0":
+  version "7.29.0"
+  resolved "https://registry.yarnpkg.com/@babel/traverse/-/traverse-7.29.0.tgz#f323d05001440253eead3c9c858adbe00b90310a"
+  integrity sha512-4HPiQr0X7+waHfyXPZpWPfWL/J7dcN1mx9gL6WdQVMbPnF3+ZhSMs8tCxN7oHddJE9fhNE7+lxdnlyemKfJRuA==
+  dependencies:
+    "@babel/code-frame" "^7.29.0"
+    "@babel/generator" "^7.29.0"
+    "@babel/helper-globals" "^7.28.0"
+    "@babel/parser" "^7.29.0"
+    "@babel/template" "^7.28.6"
+    "@babel/types" "^7.29.0"
+    debug "^4.3.1"
+
+"@babel/types@^7.0.0", "@babel/types@^7.20.7", "@babel/types@^7.27.3", "@babel/types@^7.28.2", "@babel/types@^7.28.6", "@babel/types@^7.29.0":
+  version "7.29.0"
+  resolved "https://registry.yarnpkg.com/@babel/types/-/types-7.29.0.tgz#9f5b1e838c446e72cf3cd4b918152b8c605e37c7"
+  integrity sha512-LwdZHpScM4Qz8Xw2iKSzS+cfglZzJGvofQICy7W7v4caru4EaAmyUuO6BGrbyQ2mYV11W0U8j5mBhd14dd3B0A==
+  dependencies:
+    "@babel/helper-string-parser" "^7.27.1"
+    "@babel/helper-validator-identifier" "^7.28.5"
+
+"@bcoe/v8-coverage@^0.2.3":
+  version "0.2.3"
+  resolved "https://registry.yarnpkg.com/@bcoe/v8-coverage/-/v8-coverage-0.2.3.tgz#75a2e8b51cb758a7553d6804a5932d7aace75c39"
+  integrity sha512-0hYQ8SB4Db5zvZB4axdMHGwEaQjkZzFjQiN9LVYvIFB2nSUHW9tYpxWriPrWDASIxiaXax83REcLxuSdnGPZtw==
+
 "@cspotcode/source-map-support@^0.8.0":
   version "0.8.1"
   resolved "https://registry.yarnpkg.com/@cspotcode/source-map-support/-/source-map-support-0.8.1.tgz#00629c35a688e05a88b1cda684fb9d5e73f000a1"
@@ -21,6 +289,28 @@
   dependencies:
     "@jridgewell/trace-mapping" "0.3.9"
 
+"@emnapi/core@^1.4.3":
+  version "1.8.1"
+  resolved "https://registry.yarnpkg.com/@emnapi/core/-/core-1.8.1.tgz#fd9efe721a616288345ffee17a1f26ac5dd01349"
+  integrity sha512-AvT9QFpxK0Zd8J0jopedNm+w/2fIzvtPKPjqyw9jwvBaReTTqPBk9Hixaz7KbjimP+QNz605/XnjFcDAL2pqBg==
+  dependencies:
+    "@emnapi/wasi-threads" "1.1.0"
+    tslib "^2.4.0"
+
+"@emnapi/runtime@^1.4.3":
+  version "1.8.1"
+  resolved "https://registry.yarnpkg.com/@emnapi/runtime/-/runtime-1.8.1.tgz#550fa7e3c0d49c5fb175a116e8cd70614f9a22a5"
+  integrity sha512-mehfKSMWjjNol8659Z8KxEMrdSJDDot5SXMq00dM8BN4o+CLNXQ0xH2V7EchNHV4RmbZLmmPdEaXZc5H2FXmDg==
+  dependencies:
+    tslib "^2.4.0"
+
+"@emnapi/wasi-threads@1.1.0":
+  version "1.1.0"
+  resolved "https://registry.yarnpkg.com/@emnapi/wasi-threads/-/wasi-threads-1.1.0.tgz#60b2102fddc9ccb78607e4a3cf8403ea69be41bf"
+  integrity sha512-WI0DdZ8xFSbgMjR1sFsKABJ/C5OnRrjT06JXbZKexJGrDuPTzZdDYfFlsgcCXCyf+suG5QU2e/y1Wo2V/OapLQ==
+  dependencies:
+    tslib "^2.4.0"
+
 "@esbuild/aix-ppc64@0.25.11":
   version "0.25.11"
   resolved "https://registry.yarnpkg.com/@esbuild/aix-ppc64/-/aix-ppc64-0.25.11.tgz#2ae33300598132cc4cf580dbbb28d30fed3c5c49"
@@ -417,6 +707,242 @@
     wrap-ansi "^8.1.0"
     wrap-ansi-cjs "npm:wrap-ansi@^7.0.0"
 
+"@istanbuljs/load-nyc-config@^1.0.0":
+  version "1.1.0"
+  resolved "https://registry.yarnpkg.com/@istanbuljs/load-nyc-config/-/load-nyc-config-1.1.0.tgz#fd3db1d59ecf7cf121e80650bb86712f9b55eced"
+  integrity sha512-VjeHSlIzpv/NyD3N0YuHfXOPDIixcA1q2ZV98wsMqcYlPmv2n3Yb2lYP9XMElnaFVXg5A7YLTeLu6V84uQDjmQ==
+  dependencies:
+    camelcase "^5.3.1"
+    find-up "^4.1.0"
+    get-package-type "^0.1.0"
+    js-yaml "^3.13.1"
+    resolve-from "^5.0.0"
+
+"@istanbuljs/schema@^0.1.2", "@istanbuljs/schema@^0.1.3":
+  version "0.1.3"
+  resolved "https://registry.yarnpkg.com/@istanbuljs/schema/-/schema-0.1.3.tgz#e45e384e4b8ec16bce2fd903af78450f6bf7ec98"
+  integrity sha512-ZXRY4jNvVgSVQ8DL3LTcakaAtXwTVUxE81hslsyD2AtoXW/wVob10HkOJ1X/pAlcI7D+2YoZKg5do8G/w6RYgA==
+
+"@jest/console@30.2.0":
+  version "30.2.0"
+  resolved "https://registry.yarnpkg.com/@jest/console/-/console-30.2.0.tgz#c52fcd5b58fdd2e8eb66b2fd8ae56f2f64d05b28"
+  integrity sha512-+O1ifRjkvYIkBqASKWgLxrpEhQAAE7hY77ALLUufSk5717KfOShg6IbqLmdsLMPdUiFvA2kTs0R7YZy+l0IzZQ==
+  dependencies:
+    "@jest/types" "30.2.0"
+    "@types/node" "*"
+    chalk "^4.1.2"
+    jest-message-util "30.2.0"
+    jest-util "30.2.0"
+    slash "^3.0.0"
+
+"@jest/core@30.2.0":
+  version "30.2.0"
+  resolved "https://registry.yarnpkg.com/@jest/core/-/core-30.2.0.tgz#813d59faa5abd5510964a8b3a7b17cc77b775275"
+  integrity sha512-03W6IhuhjqTlpzh/ojut/pDB2LPRygyWX8ExpgHtQA8H/3K7+1vKmcINx5UzeOX1se6YEsBsOHQ1CRzf3fOwTQ==
+  dependencies:
+    "@jest/console" "30.2.0"
+    "@jest/pattern" "30.0.1"
+    "@jest/reporters" "30.2.0"
+    "@jest/test-result" "30.2.0"
+    "@jest/transform" "30.2.0"
+    "@jest/types" "30.2.0"
+    "@types/node" "*"
+    ansi-escapes "^4.3.2"
+    chalk "^4.1.2"
+    ci-info "^4.2.0"
+    exit-x "^0.2.2"
+    graceful-fs "^4.2.11"
+    jest-changed-files "30.2.0"
+    jest-config "30.2.0"
+    jest-haste-map "30.2.0"
+    jest-message-util "30.2.0"
+    jest-regex-util "30.0.1"
+    jest-resolve "30.2.0"
+    jest-resolve-dependencies "30.2.0"
+    jest-runner "30.2.0"
+    jest-runtime "30.2.0"
+    jest-snapshot "30.2.0"
+    jest-util "30.2.0"
+    jest-validate "30.2.0"
+    jest-watcher "30.2.0"
+    micromatch "^4.0.8"
+    pretty-format "30.2.0"
+    slash "^3.0.0"
+
+"@jest/diff-sequences@30.0.1":
+  version "30.0.1"
+  resolved "https://registry.yarnpkg.com/@jest/diff-sequences/-/diff-sequences-30.0.1.tgz#0ededeae4d071f5c8ffe3678d15f3a1be09156be"
+  integrity sha512-n5H8QLDJ47QqbCNn5SuFjCRDrOLEZ0h8vAHCK5RL9Ls7Xa8AQLa/YxAc9UjFqoEDM48muwtBGjtMY5cr0PLDCw==
+
+"@jest/environment@30.2.0":
+  version "30.2.0"
+  resolved "https://registry.yarnpkg.com/@jest/environment/-/environment-30.2.0.tgz#1e673cdb8b93ded707cf6631b8353011460831fa"
+  integrity sha512-/QPTL7OBJQ5ac09UDRa3EQes4gt1FTEG/8jZ/4v5IVzx+Cv7dLxlVIvfvSVRiiX2drWyXeBjkMSR8hvOWSog5g==
+  dependencies:
+    "@jest/fake-timers" "30.2.0"
+    "@jest/types" "30.2.0"
+    "@types/node" "*"
+    jest-mock "30.2.0"
+
+"@jest/expect-utils@30.2.0":
+  version "30.2.0"
+  resolved "https://registry.yarnpkg.com/@jest/expect-utils/-/expect-utils-30.2.0.tgz#4f95413d4748454fdb17404bf1141827d15e6011"
+  integrity sha512-1JnRfhqpD8HGpOmQp180Fo9Zt69zNtC+9lR+kT7NVL05tNXIi+QC8Csz7lfidMoVLPD3FnOtcmp0CEFnxExGEA==
+  dependencies:
+    "@jest/get-type" "30.1.0"
+
+"@jest/expect@30.2.0":
+  version "30.2.0"
+  resolved "https://registry.yarnpkg.com/@jest/expect/-/expect-30.2.0.tgz#9a5968499bb8add2bbb09136f69f7df5ddbf3185"
+  integrity sha512-V9yxQK5erfzx99Sf+7LbhBwNWEZ9eZay8qQ9+JSC0TrMR1pMDHLMY+BnVPacWU6Jamrh252/IKo4F1Xn/zfiqA==
+  dependencies:
+    expect "30.2.0"
+    jest-snapshot "30.2.0"
+
+"@jest/fake-timers@30.2.0":
+  version "30.2.0"
+  resolved "https://registry.yarnpkg.com/@jest/fake-timers/-/fake-timers-30.2.0.tgz#0941ddc28a339b9819542495b5408622dc9e94ec"
+  integrity sha512-HI3tRLjRxAbBy0VO8dqqm7Hb2mIa8d5bg/NJkyQcOk7V118ObQML8RC5luTF/Zsg4474a+gDvhce7eTnP4GhYw==
+  dependencies:
+    "@jest/types" "30.2.0"
+    "@sinonjs/fake-timers" "^13.0.0"
+    "@types/node" "*"
+    jest-message-util "30.2.0"
+    jest-mock "30.2.0"
+    jest-util "30.2.0"
+
+"@jest/get-type@30.1.0":
+  version "30.1.0"
+  resolved "https://registry.yarnpkg.com/@jest/get-type/-/get-type-30.1.0.tgz#4fcb4dc2ebcf0811be1c04fd1cb79c2dba431cbc"
+  integrity sha512-eMbZE2hUnx1WV0pmURZY9XoXPkUYjpc55mb0CrhtdWLtzMQPFvu/rZkTLZFTsdaVQa+Tr4eWAteqcUzoawq/uA==
+
+"@jest/globals@30.2.0":
+  version "30.2.0"
+  resolved "https://registry.yarnpkg.com/@jest/globals/-/globals-30.2.0.tgz#2f4b696d5862664b89c4ee2e49ae24d2bb7e0988"
+  integrity sha512-b63wmnKPaK+6ZZfpYhz9K61oybvbI1aMcIs80++JI1O1rR1vaxHUCNqo3ITu6NU0d4V34yZFoHMn/uoKr/Rwfw==
+  dependencies:
+    "@jest/environment" "30.2.0"
+    "@jest/expect" "30.2.0"
+    "@jest/types" "30.2.0"
+    jest-mock "30.2.0"
+
+"@jest/pattern@30.0.1":
+  version "30.0.1"
+  resolved "https://registry.yarnpkg.com/@jest/pattern/-/pattern-30.0.1.tgz#d5304147f49a052900b4b853dedb111d080e199f"
+  integrity sha512-gWp7NfQW27LaBQz3TITS8L7ZCQ0TLvtmI//4OwlQRx4rnWxcPNIYjxZpDcN4+UlGxgm3jS5QPz8IPTCkb59wZA==
+  dependencies:
+    "@types/node" "*"
+    jest-regex-util "30.0.1"
+
+"@jest/reporters@30.2.0":
+  version "30.2.0"
+  resolved "https://registry.yarnpkg.com/@jest/reporters/-/reporters-30.2.0.tgz#a36b28fcbaf0c4595250b108e6f20e363348fd91"
+  integrity sha512-DRyW6baWPqKMa9CzeiBjHwjd8XeAyco2Vt8XbcLFjiwCOEKOvy82GJ8QQnJE9ofsxCMPjH4MfH8fCWIHHDKpAQ==
+  dependencies:
+    "@bcoe/v8-coverage" "^0.2.3"
+    "@jest/console" "30.2.0"
+    "@jest/test-result" "30.2.0"
+    "@jest/transform" "30.2.0"
+    "@jest/types" "30.2.0"
+    "@jridgewell/trace-mapping" "^0.3.25"
+    "@types/node" "*"
+    chalk "^4.1.2"
+    collect-v8-coverage "^1.0.2"
+    exit-x "^0.2.2"
+    glob "^10.3.10"
+    graceful-fs "^4.2.11"
+    istanbul-lib-coverage "^3.0.0"
+    istanbul-lib-instrument "^6.0.0"
+    istanbul-lib-report "^3.0.0"
+    istanbul-lib-source-maps "^5.0.0"
+    istanbul-reports "^3.1.3"
+    jest-message-util "30.2.0"
+    jest-util "30.2.0"
+    jest-worker "30.2.0"
+    slash "^3.0.0"
+    string-length "^4.0.2"
+    v8-to-istanbul "^9.0.1"
+
+"@jest/schemas@30.0.5":
+  version "30.0.5"
+  resolved "https://registry.yarnpkg.com/@jest/schemas/-/schemas-30.0.5.tgz#7bdf69fc5a368a5abdb49fd91036c55225846473"
+  integrity sha512-DmdYgtezMkh3cpU8/1uyXakv3tJRcmcXxBOcO0tbaozPwpmh4YMsnWrQm9ZmZMfa5ocbxzbFk6O4bDPEc/iAnA==
+  dependencies:
+    "@sinclair/typebox" "^0.34.0"
+
+"@jest/snapshot-utils@30.2.0":
+  version "30.2.0"
+  resolved "https://registry.yarnpkg.com/@jest/snapshot-utils/-/snapshot-utils-30.2.0.tgz#387858eb90c2f98f67bff327435a532ac5309fbe"
+  integrity sha512-0aVxM3RH6DaiLcjj/b0KrIBZhSX1373Xci4l3cW5xiUWPctZ59zQ7jj4rqcJQ/Z8JuN/4wX3FpJSa3RssVvCug==
+  dependencies:
+    "@jest/types" "30.2.0"
+    chalk "^4.1.2"
+    graceful-fs "^4.2.11"
+    natural-compare "^1.4.0"
+
+"@jest/source-map@30.0.1":
+  version "30.0.1"
+  resolved "https://registry.yarnpkg.com/@jest/source-map/-/source-map-30.0.1.tgz#305ebec50468f13e658b3d5c26f85107a5620aaa"
+  integrity sha512-MIRWMUUR3sdbP36oyNyhbThLHyJ2eEDClPCiHVbrYAe5g3CHRArIVpBw7cdSB5fr+ofSfIb2Tnsw8iEHL0PYQg==
+  dependencies:
+    "@jridgewell/trace-mapping" "^0.3.25"
+    callsites "^3.1.0"
+    graceful-fs "^4.2.11"
+
+"@jest/test-result@30.2.0":
+  version "30.2.0"
+  resolved "https://registry.yarnpkg.com/@jest/test-result/-/test-result-30.2.0.tgz#9c0124377fb7996cdffb86eda3dbc56eacab363d"
+  integrity sha512-RF+Z+0CCHkARz5HT9mcQCBulb1wgCP3FBvl9VFokMX27acKphwyQsNuWH3c+ojd1LeWBLoTYoxF0zm6S/66mjg==
+  dependencies:
+    "@jest/console" "30.2.0"
+    "@jest/types" "30.2.0"
+    "@types/istanbul-lib-coverage" "^2.0.6"
+    collect-v8-coverage "^1.0.2"
+
+"@jest/test-sequencer@30.2.0":
+  version "30.2.0"
+  resolved "https://registry.yarnpkg.com/@jest/test-sequencer/-/test-sequencer-30.2.0.tgz#bf0066bc72e176d58f5dfa7f212b6e7eee44f221"
+  integrity sha512-wXKgU/lk8fKXMu/l5Hog1R61bL4q5GCdT6OJvdAFz1P+QrpoFuLU68eoKuVc4RbrTtNnTL5FByhWdLgOPSph+Q==
+  dependencies:
+    "@jest/test-result" "30.2.0"
+    graceful-fs "^4.2.11"
+    jest-haste-map "30.2.0"
+    slash "^3.0.0"
+
+"@jest/transform@30.2.0":
+  version "30.2.0"
+  resolved "https://registry.yarnpkg.com/@jest/transform/-/transform-30.2.0.tgz#54bef1a4510dcbd58d5d4de4fe2980a63077ef2a"
+  integrity sha512-XsauDV82o5qXbhalKxD7p4TZYYdwcaEXC77PPD2HixEFF+6YGppjrAAQurTl2ECWcEomHBMMNS9AH3kcCFx8jA==
+  dependencies:
+    "@babel/core" "^7.27.4"
+    "@jest/types" "30.2.0"
+    "@jridgewell/trace-mapping" "^0.3.25"
+    babel-plugin-istanbul "^7.0.1"
+    chalk "^4.1.2"
+    convert-source-map "^2.0.0"
+    fast-json-stable-stringify "^2.1.0"
+    graceful-fs "^4.2.11"
+    jest-haste-map "30.2.0"
+    jest-regex-util "30.0.1"
+    jest-util "30.2.0"
+    micromatch "^4.0.8"
+    pirates "^4.0.7"
+    slash "^3.0.0"
+    write-file-atomic "^5.0.1"
+
+"@jest/types@30.2.0":
+  version "30.2.0"
+  resolved "https://registry.yarnpkg.com/@jest/types/-/types-30.2.0.tgz#1c678a7924b8f59eafd4c77d56b6d0ba976d62b8"
+  integrity sha512-H9xg1/sfVvyfU7o3zMfBEjQ1gcsdeTMgqHoYdN79tuLqfTtuu7WckRA1R5whDwOzxaZAeMKTYWqP+WCAi0CHsg==
+  dependencies:
+    "@jest/pattern" "30.0.1"
+    "@jest/schemas" "30.0.5"
+    "@types/istanbul-lib-coverage" "^2.0.6"
+    "@types/istanbul-reports" "^3.0.4"
+    "@types/node" "*"
+    "@types/yargs" "^17.0.33"
+    chalk "^4.1.2"
+
 "@jimp/core@1.6.0":
   version "1.6.0"
   resolved "https://registry.yarnpkg.com/@jimp/core/-/core-1.6.0.tgz#3ef241bf02f40431bb382aea665e5187a2c05eef"
@@ -690,12 +1216,28 @@
     "@jimp/types" "1.6.0"
     tinycolor2 "^1.6.0"
 
-"@jridgewell/resolve-uri@^3.0.3":
+"@jridgewell/gen-mapping@^0.3.12", "@jridgewell/gen-mapping@^0.3.5":
+  version "0.3.13"
+  resolved "https://registry.yarnpkg.com/@jridgewell/gen-mapping/-/gen-mapping-0.3.13.tgz#6342a19f44347518c93e43b1ac69deb3c4656a1f"
+  integrity sha512-2kkt/7niJ6MgEPxF0bYdQ6etZaA+fQvDcLKckhy1yIQOzaoKjBBjSj63/aLVjYE3qhRt5dvM+uUyfCg6UKCBbA==
+  dependencies:
+    "@jridgewell/sourcemap-codec" "^1.5.0"
+    "@jridgewell/trace-mapping" "^0.3.24"
+
+"@jridgewell/remapping@^2.3.5":
+  version "2.3.5"
+  resolved "https://registry.yarnpkg.com/@jridgewell/remapping/-/remapping-2.3.5.tgz#375c476d1972947851ba1e15ae8f123047445aa1"
+  integrity sha512-LI9u/+laYG4Ds1TDKSJW2YPrIlcVYOwi2fUC6xB43lueCjgxV4lffOCZCtYFiH6TNOX+tQKXx97T4IKHbhyHEQ==
+  dependencies:
+    "@jridgewell/gen-mapping" "^0.3.5"
+    "@jridgewell/trace-mapping" "^0.3.24"
+
+"@jridgewell/resolve-uri@^3.0.3", "@jridgewell/resolve-uri@^3.1.0":
   version "3.1.2"
   resolved "https://registry.yarnpkg.com/@jridgewell/resolve-uri/-/resolve-uri-3.1.2.tgz#7a0ee601f60f99a20c7c7c5ff0c80388c1189bd6"
   integrity sha512-bRISgCIjP20/tbWSPWMEi54QVPRZExkuD9lJL+UIxUKtwVJA8wW1Trb1jMs1RFXo1CBTNZ/5hpC9QvmKWdopKw==
 
-"@jridgewell/sourcemap-codec@^1.4.10":
+"@jridgewell/sourcemap-codec@^1.4.10", "@jridgewell/sourcemap-codec@^1.4.14", "@jridgewell/sourcemap-codec@^1.5.0":
   version "1.5.5"
   resolved "https://registry.yarnpkg.com/@jridgewell/sourcemap-codec/-/sourcemap-codec-1.5.5.tgz#6912b00d2c631c0d15ce1a7ab57cd657f2a8f8ba"
   integrity sha512-cYQ9310grqxueWbl+WuIUIaiUaDcj7WOq5fVhEljNVgRfOUhY9fy2zTvfoqWsnebh8Sl70VScFbICvJnLKB0Og==
@@ -708,6 +1250,14 @@
     "@jridgewell/resolve-uri" "^3.0.3"
     "@jridgewell/sourcemap-codec" "^1.4.10"
 
+"@jridgewell/trace-mapping@^0.3.12", "@jridgewell/trace-mapping@^0.3.23", "@jridgewell/trace-mapping@^0.3.24", "@jridgewell/trace-mapping@^0.3.25", "@jridgewell/trace-mapping@^0.3.28":
+  version "0.3.31"
+  resolved "https://registry.yarnpkg.com/@jridgewell/trace-mapping/-/trace-mapping-0.3.31.tgz#db15d6781c931f3a251a3dac39501c98a6082fd0"
+  integrity sha512-zzNR+SdQSDJzc8joaeP8QQoCQr8NuYx2dIIytl1QeBEZHJ9uW6hebsrYgbz8hJwUQao3TWCMtmfV8Nu1twOLAw==
+  dependencies:
+    "@jridgewell/resolve-uri" "^3.1.0"
+    "@jridgewell/sourcemap-codec" "^1.4.14"
+
 "@mixmark-io/domino@^2.2.0":
   version "2.2.0"
   resolved "https://registry.yarnpkg.com/@mixmark-io/domino/-/domino-2.2.0.tgz#4e8ec69bf1afeb7a14f0628b7e2c0f35bdb336c3"
@@ -731,6 +1281,15 @@
     zod "^3.23.8"
     zod-to-json-schema "^3.24.1"
 
+"@napi-rs/wasm-runtime@^0.2.11":
+  version "0.2.12"
+  resolved "https://registry.yarnpkg.com/@napi-rs/wasm-runtime/-/wasm-runtime-0.2.12.tgz#3e78a8b96e6c33a6c517e1894efbd5385a7cb6f2"
+  integrity sha512-ZVWUcfwY4E/yPitQJl481FjFo3K22D6qF0DuFH6Y/nbnE11GY5uguDxZMGXPQ8WQ0128MXQD7TnfHyK4oWoIJQ==
+  dependencies:
+    "@emnapi/core" "^1.4.3"
+    "@emnapi/runtime" "^1.4.3"
+    "@tybys/wasm-util" "^0.10.0"
+
 "@nodelib/fs.scandir@2.1.5":
   version "2.1.5"
   resolved "https://registry.yarnpkg.com/@nodelib/fs.scandir/-/fs.scandir-2.1.5.tgz#7619c2eb21b25483f6d167548b4cfd5a7488c3d5"
@@ -757,6 +1316,30 @@
   resolved "https://registry.yarnpkg.com/@pkgjs/parseargs/-/parseargs-0.11.0.tgz#a77ea742fab25775145434eb1d2328cf5013ac33"
   integrity sha512-+1VkjdD0QBLPodGrJUeqarH8VAIvQODIbwh9XpP5Syisf7YoQgsJKPNFoqqLQlu+VQ/tVSshMR6loPMn8U+dPg==
 
+"@pkgr/core@^0.2.9":
+  version "0.2.9"
+  resolved "https://registry.yarnpkg.com/@pkgr/core/-/core-0.2.9.tgz#d229a7b7f9dac167a156992ef23c7f023653f53b"
+  integrity sha512-QNqXyfVS2wm9hweSYD2O7F0G06uurj9kZ96TRQE5Y9hU7+tgdZwIkbAKc5Ocy1HxEY2kuDQa6cQ1WRs/O5LFKA==
+
+"@sinclair/typebox@^0.34.0":
+  version "0.34.48"
+  resolved "https://registry.yarnpkg.com/@sinclair/typebox/-/typebox-0.34.48.tgz#75b0ead87e59e1adbd6dccdc42bad4fddee73b59"
+  integrity sha512-kKJTNuK3AQOrgjjotVxMrCn1sUJwM76wMszfq1kdU4uYVJjvEWuFQ6HgvLt4Xz3fSmZlTOxJ/Ie13KnIcWQXFA==
+
+"@sinonjs/commons@^3.0.1":
+  version "3.0.1"
+  resolved "https://registry.yarnpkg.com/@sinonjs/commons/-/commons-3.0.1.tgz#1029357e44ca901a615585f6d27738dbc89084cd"
+  integrity sha512-K3mCHKQ9sVh8o1C9cxkwxaOmXoAMlDxC1mYyHrjqOWEcBjYr76t96zL2zlj5dUGZ3HSw240X1qgH3Mjf1yJWpQ==
+  dependencies:
+    type-detect "4.0.8"
+
+"@sinonjs/fake-timers@^13.0.0":
+  version "13.0.5"
+  resolved "https://registry.yarnpkg.com/@sinonjs/fake-timers/-/fake-timers-13.0.5.tgz#36b9dbc21ad5546486ea9173d6bea063eb1717d5"
+  integrity sha512-36/hTbH2uaWuGVERyC6da9YwGWnzUZXuPro/F2LfsdOsLnCojz/iSH8MxUt/FD2S5XBSVPhmArFUXcpCQ2Hkiw==
+  dependencies:
+    "@sinonjs/commons" "^3.0.1"
+
 "@tokenizer/token@^0.3.0":
   version "0.3.0"
   resolved "https://registry.yarnpkg.com/@tokenizer/token/-/token-0.3.0.tgz#fe98a93fe789247e998c75e74e9c7c63217aa276"
@@ -782,6 +1365,46 @@
   resolved "https://registry.yarnpkg.com/@tsconfig/node16/-/node16-1.0.4.tgz#0b92dcc0cc1c81f6f306a381f28e31b1a56536e9"
   integrity sha512-vxhUy4J8lyeyinH7Azl1pdd43GJhZH/tP2weN8TntQblOY+A0XbT8DJk1/oCPuOOyg/Ja757rG0CgHcWC8OfMA==
 
+"@tybys/wasm-util@^0.10.0":
+  version "0.10.1"
+  resolved "https://registry.yarnpkg.com/@tybys/wasm-util/-/wasm-util-0.10.1.tgz#ecddd3205cf1e2d5274649ff0eedd2991ed7f414"
+  integrity sha512-9tTaPJLSiejZKx+Bmog4uSubteqTvFrVrURwkmHixBo0G4seD0zUxp98E1DzUBJxLQ3NPwXrGKDiVjwx/DpPsg==
+  dependencies:
+    tslib "^2.4.0"
+
+"@types/babel__core@^7.20.5":
+  version "7.20.5"
+  resolved "https://registry.yarnpkg.com/@types/babel__core/-/babel__core-7.20.5.tgz#3df15f27ba85319caa07ba08d0721889bb39c017"
+  integrity sha512-qoQprZvz5wQFJwMDqeseRXWv3rqMvhgpbXFfVyWhbx9X47POIA6i/+dXefEmZKoAgOaTdaIgNSMqMIU61yRyzA==
+  dependencies:
+    "@babel/parser" "^7.20.7"
+    "@babel/types" "^7.20.7"
+    "@types/babel__generator" "*"
+    "@types/babel__template" "*"
+    "@types/babel__traverse" "*"
+
+"@types/babel__generator@*":
+  version "7.27.0"
+  resolved "https://registry.yarnpkg.com/@types/babel__generator/-/babel__generator-7.27.0.tgz#b5819294c51179957afaec341442f9341e4108a9"
+  integrity sha512-ufFd2Xi92OAVPYsy+P4n7/U7e68fex0+Ee8gSG9KX7eo084CWiQ4sdxktvdl0bOPupXtVJPY19zk6EwWqUQ8lg==
+  dependencies:
+    "@babel/types" "^7.0.0"
+
+"@types/babel__template@*":
+  version "7.4.4"
+  resolved "https://registry.yarnpkg.com/@types/babel__template/-/babel__template-7.4.4.tgz#5672513701c1b2199bc6dad636a9d7491586766f"
+  integrity sha512-h/NUaSyG5EyxBIp8YRxo4RMe2/qQgvyowRwVMzhYhBCONbW8PUsg4lkFMrhgZhUe5z3L3MiLDuvyJ/CaPa2A8A==
+  dependencies:
+    "@babel/parser" "^7.1.0"
+    "@babel/types" "^7.0.0"
+
+"@types/babel__traverse@*":
+  version "7.28.0"
+  resolved "https://registry.yarnpkg.com/@types/babel__traverse/-/babel__traverse-7.28.0.tgz#07d713d6cce0d265c9849db0cbe62d3f61f36f74"
+  integrity sha512-8PvcXf70gTDZBgt9ptxJ8elBeBjcLOAcOtoO/mPJjtji1+CdGbHgm77om1GrsPxsiE+uXIpNSK64UYaIwQXd4Q==
+  dependencies:
+    "@babel/types" "^7.28.2"
+
 "@types/crypto-js@^4.2.2":
   version "4.2.2"
   resolved "https://registry.yarnpkg.com/@types/crypto-js/-/crypto-js-4.2.2.tgz#771c4a768d94eb5922cc202a3009558204df0cea"
@@ -792,6 +1415,33 @@
   resolved "https://registry.yarnpkg.com/@types/estree/-/estree-1.0.8.tgz#958b91c991b1867ced318bedea0e215ee050726e"
   integrity sha512-dWHzHa2WqEXI/O1E9OjrocMTKJl2mSrEolh1Iomrv6U+JuNwaHXsXx9bLu5gG7BUWFIN0skIQJQ/L1rIex4X6w==
 
+"@types/istanbul-lib-coverage@*", "@types/istanbul-lib-coverage@^2.0.1", "@types/istanbul-lib-coverage@^2.0.6":
+  version "2.0.6"
+  resolved "https://registry.yarnpkg.com/@types/istanbul-lib-coverage/-/istanbul-lib-coverage-2.0.6.tgz#7739c232a1fee9b4d3ce8985f314c0c6d33549d7"
+  integrity sha512-2QF/t/auWm0lsy8XtKVPG19v3sSOQlJe/YHZgfjb/KBBHOGSV+J2q/S671rcq9uTBrLAXmZpqJiaQbMT+zNU1w==
+
+"@types/istanbul-lib-report@*":
+  version "3.0.3"
+  resolved "https://registry.yarnpkg.com/@types/istanbul-lib-report/-/istanbul-lib-report-3.0.3.tgz#53047614ae72e19fc0401d872de3ae2b4ce350bf"
+  integrity sha512-NQn7AHQnk/RSLOxrBbGyJM/aVQ+pjj5HCgasFxc0K/KhoATfQ/47AyUl15I2yBUpihjmas+a+VJBOqecrFH+uA==
+  dependencies:
+    "@types/istanbul-lib-coverage" "*"
+
+"@types/istanbul-reports@^3.0.4":
+  version "3.0.4"
+  resolved "https://registry.yarnpkg.com/@types/istanbul-reports/-/istanbul-reports-3.0.4.tgz#0f03e3d2f670fbdac586e34b433783070cc16f54"
+  integrity sha512-pk2B1NWalF9toCRu6gjBzR69syFjP4Od8WRAX+0mmf9lAjCRicLOWc+ZrxZHx/0XRjotgkF9t6iaMJ+aXcOdZQ==
+  dependencies:
+    "@types/istanbul-lib-report" "*"
+
+"@types/jest@^30.0.0":
+  version "30.0.0"
+  resolved "https://registry.yarnpkg.com/@types/jest/-/jest-30.0.0.tgz#5e85ae568006712e4ad66f25433e9bdac8801f1d"
+  integrity sha512-XTYugzhuwqWjws0CVz8QpM36+T+Dz5mTEBKhNs/esGLnCIlGdRy+Dq78NRjd7ls7r8BC8ZRMOrKlkO1hU0JOwA==
+  dependencies:
+    expect "^30.0.0"
+    pretty-format "^30.0.0"
+
 "@types/json-schema@^7.0.15":
   version "7.0.15"
   resolved "https://registry.yarnpkg.com/@types/json-schema/-/json-schema-7.0.15.tgz#596a1747233694d50f6ad8a7869fcb6f56cf5841"
@@ -802,6 +1452,13 @@
   resolved "https://registry.yarnpkg.com/@types/lodash/-/lodash-4.17.20.tgz#1ca77361d7363432d29f5e55950d9ec1e1c6ea93"
   integrity sha512-H3MHACvFUEiujabxhaI/ImO6gUrd8oOurg7LQtS7mbwIXA/cUqWrvBsaeJ23aZEPk1TAYkurjfMbSELfoCXlGA==
 
+"@types/node@*":
+  version "25.2.3"
+  resolved "https://registry.yarnpkg.com/@types/node/-/node-25.2.3.tgz#9c18245be768bdb4ce631566c7da303a5c99a7f8"
+  integrity sha512-m0jEgYlYz+mDJZ2+F4v8D1AyQb+QzsNqRuI7xg1VQX/KlKS0qT9r1Mo16yo5F/MtifXFgaofIFsdFMox2SxIbQ==
+  dependencies:
+    undici-types "~7.16.0"
+
 "@types/node@16.9.1":
   version "16.9.1"
   resolved "https://registry.yarnpkg.com/@types/node/-/node-16.9.1.tgz#0611b37db4246c937feef529ddcc018cf8e35708"
@@ -814,11 +1471,28 @@
   dependencies:
     undici-types "~6.21.0"
 
+"@types/stack-utils@^2.0.3":
+  version "2.0.3"
+  resolved "https://registry.yarnpkg.com/@types/stack-utils/-/stack-utils-2.0.3.tgz#6209321eb2c1712a7e7466422b8cb1fc0d9dd5d8"
+  integrity sha512-9aEbYZ3TbYMznPdcdr3SmIrLXwC/AKZXQeCf9Pgao5CKb8CyHuEX5jzWPTkvregvhRJHcpRO6BFoGW9ycaOkYw==
+
 "@types/turndown@^5.0.5":
   version "5.0.6"
   resolved "https://registry.yarnpkg.com/@types/turndown/-/turndown-5.0.6.tgz#42a27397298a312d6088f29c0ff4819c518c1ecb"
   integrity sha512-ru00MoyeeouE5BX4gRL+6m/BsDfbRayOskWqUvh7CLGW+UXxHQItqALa38kKnOiZPqJrtzJUgAC2+F0rL1S4Pg==
 
+"@types/yargs-parser@*":
+  version "21.0.3"
+  resolved "https://registry.yarnpkg.com/@types/yargs-parser/-/yargs-parser-21.0.3.tgz#815e30b786d2e8f0dcd85fd5bcf5e1a04d008f15"
+  integrity sha512-I4q9QU9MQv4oEOz4tAHJtNz1cwuLxn2F3xcc2iV5WdqLPpUnj30aUuxt1mAxYTG+oe8CZMV/+6rU4S4gRDzqtQ==
+
+"@types/yargs@^17.0.33":
+  version "17.0.35"
+  resolved "https://registry.yarnpkg.com/@types/yargs/-/yargs-17.0.35.tgz#07013e46aa4d7d7d50a49e15604c1c5340d4eb24"
+  integrity sha512-qUHkeCyQFxMXg79wQfTtfndEC+N9ZZg76HJftDJp+qH2tV7Gj4OJi7l+PiWwJ+pWtW8GwSmqsDj/oymhrTWXjg==
+  dependencies:
+    "@types/yargs-parser" "*"
+
 "@typescript-eslint/eslint-plugin@^8.15.0":
   version "8.46.2"
   resolved "https://registry.yarnpkg.com/@typescript-eslint/eslint-plugin/-/eslint-plugin-8.46.2.tgz#dc4ab93ee3d7e6c8e38820a0d6c7c93c7183e2dc"
@@ -917,6 +1591,108 @@
     "@typescript-eslint/types" "8.46.2"
     eslint-visitor-keys "^4.2.1"
 
+"@ungap/structured-clone@^1.3.0":
+  version "1.3.0"
+  resolved "https://registry.yarnpkg.com/@ungap/structured-clone/-/structured-clone-1.3.0.tgz#d06bbb384ebcf6c505fde1c3d0ed4ddffe0aaff8"
+  integrity sha512-WmoN8qaIAo7WTYWbAZuG8PYEhn5fkz7dZrqTBZ7dtt//lL2Gwms1IcnQ5yHqjDfX8Ft5j4YzDM23f87zBfDe9g==
+
+"@unrs/resolver-binding-android-arm-eabi@1.11.1":
+  version "1.11.1"
+  resolved "https://registry.yarnpkg.com/@unrs/resolver-binding-android-arm-eabi/-/resolver-binding-android-arm-eabi-1.11.1.tgz#9f5b04503088e6a354295e8ea8fe3cb99e43af81"
+  integrity sha512-ppLRUgHVaGRWUx0R0Ut06Mjo9gBaBkg3v/8AxusGLhsIotbBLuRk51rAzqLC8gq6NyyAojEXglNjzf6R948DNw==
+
+"@unrs/resolver-binding-android-arm64@1.11.1":
+  version "1.11.1"
+  resolved "https://registry.yarnpkg.com/@unrs/resolver-binding-android-arm64/-/resolver-binding-android-arm64-1.11.1.tgz#7414885431bd7178b989aedc4d25cccb3865bc9f"
+  integrity sha512-lCxkVtb4wp1v+EoN+HjIG9cIIzPkX5OtM03pQYkG+U5O/wL53LC4QbIeazgiKqluGeVEeBlZahHalCaBvU1a2g==
+
+"@unrs/resolver-binding-darwin-arm64@1.11.1":
+  version "1.11.1"
+  resolved "https://registry.yarnpkg.com/@unrs/resolver-binding-darwin-arm64/-/resolver-binding-darwin-arm64-1.11.1.tgz#b4a8556f42171fb9c9f7bac8235045e82aa0cbdf"
+  integrity sha512-gPVA1UjRu1Y/IsB/dQEsp2V1pm44Of6+LWvbLc9SDk1c2KhhDRDBUkQCYVWe6f26uJb3fOK8saWMgtX8IrMk3g==
+
+"@unrs/resolver-binding-darwin-x64@1.11.1":
+  version "1.11.1"
+  resolved "https://registry.yarnpkg.com/@unrs/resolver-binding-darwin-x64/-/resolver-binding-darwin-x64-1.11.1.tgz#fd4d81257b13f4d1a083890a6a17c00de571f0dc"
+  integrity sha512-cFzP7rWKd3lZaCsDze07QX1SC24lO8mPty9vdP+YVa3MGdVgPmFc59317b2ioXtgCMKGiCLxJ4HQs62oz6GfRQ==
+
+"@unrs/resolver-binding-freebsd-x64@1.11.1":
+  version "1.11.1"
+  resolved "https://registry.yarnpkg.com/@unrs/resolver-binding-freebsd-x64/-/resolver-binding-freebsd-x64-1.11.1.tgz#d2513084d0f37c407757e22f32bd924a78cfd99b"
+  integrity sha512-fqtGgak3zX4DCB6PFpsH5+Kmt/8CIi4Bry4rb1ho6Av2QHTREM+47y282Uqiu3ZRF5IQioJQ5qWRV6jduA+iGw==
+
+"@unrs/resolver-binding-linux-arm-gnueabihf@1.11.1":
+  version "1.11.1"
+  resolved "https://registry.yarnpkg.com/@unrs/resolver-binding-linux-arm-gnueabihf/-/resolver-binding-linux-arm-gnueabihf-1.11.1.tgz#844d2605d057488d77fab09705f2866b86164e0a"
+  integrity sha512-u92mvlcYtp9MRKmP+ZvMmtPN34+/3lMHlyMj7wXJDeXxuM0Vgzz0+PPJNsro1m3IZPYChIkn944wW8TYgGKFHw==
+
+"@unrs/resolver-binding-linux-arm-musleabihf@1.11.1":
+  version "1.11.1"
+  resolved "https://registry.yarnpkg.com/@unrs/resolver-binding-linux-arm-musleabihf/-/resolver-binding-linux-arm-musleabihf-1.11.1.tgz#204892995cefb6bd1d017d52d097193bc61ddad3"
+  integrity sha512-cINaoY2z7LVCrfHkIcmvj7osTOtm6VVT16b5oQdS4beibX2SYBwgYLmqhBjA1t51CarSaBuX5YNsWLjsqfW5Cw==
+
+"@unrs/resolver-binding-linux-arm64-gnu@1.11.1":
+  version "1.11.1"
+  resolved "https://registry.yarnpkg.com/@unrs/resolver-binding-linux-arm64-gnu/-/resolver-binding-linux-arm64-gnu-1.11.1.tgz#023eb0c3aac46066a10be7a3f362e7b34f3bdf9d"
+  integrity sha512-34gw7PjDGB9JgePJEmhEqBhWvCiiWCuXsL9hYphDF7crW7UgI05gyBAi6MF58uGcMOiOqSJ2ybEeCvHcq0BCmQ==
+
+"@unrs/resolver-binding-linux-arm64-musl@1.11.1":
+  version "1.11.1"
+  resolved "https://registry.yarnpkg.com/@unrs/resolver-binding-linux-arm64-musl/-/resolver-binding-linux-arm64-musl-1.11.1.tgz#9e6f9abb06424e3140a60ac996139786f5d99be0"
+  integrity sha512-RyMIx6Uf53hhOtJDIamSbTskA99sPHS96wxVE/bJtePJJtpdKGXO1wY90oRdXuYOGOTuqjT8ACccMc4K6QmT3w==
+
+"@unrs/resolver-binding-linux-ppc64-gnu@1.11.1":
+  version "1.11.1"
+  resolved "https://registry.yarnpkg.com/@unrs/resolver-binding-linux-ppc64-gnu/-/resolver-binding-linux-ppc64-gnu-1.11.1.tgz#b111417f17c9d1b02efbec8e08398f0c5527bb44"
+  integrity sha512-D8Vae74A4/a+mZH0FbOkFJL9DSK2R6TFPC9M+jCWYia/q2einCubX10pecpDiTmkJVUH+y8K3BZClycD8nCShA==
+
+"@unrs/resolver-binding-linux-riscv64-gnu@1.11.1":
+  version "1.11.1"
+  resolved "https://registry.yarnpkg.com/@unrs/resolver-binding-linux-riscv64-gnu/-/resolver-binding-linux-riscv64-gnu-1.11.1.tgz#92ffbf02748af3e99873945c9a8a5ead01d508a9"
+  integrity sha512-frxL4OrzOWVVsOc96+V3aqTIQl1O2TjgExV4EKgRY09AJ9leZpEg8Ak9phadbuX0BA4k8U5qtvMSQQGGmaJqcQ==
+
+"@unrs/resolver-binding-linux-riscv64-musl@1.11.1":
+  version "1.11.1"
+  resolved "https://registry.yarnpkg.com/@unrs/resolver-binding-linux-riscv64-musl/-/resolver-binding-linux-riscv64-musl-1.11.1.tgz#0bec6f1258fc390e6b305e9ff44256cb207de165"
+  integrity sha512-mJ5vuDaIZ+l/acv01sHoXfpnyrNKOk/3aDoEdLO/Xtn9HuZlDD6jKxHlkN8ZhWyLJsRBxfv9GYM2utQ1SChKew==
+
+"@unrs/resolver-binding-linux-s390x-gnu@1.11.1":
+  version "1.11.1"
+  resolved "https://registry.yarnpkg.com/@unrs/resolver-binding-linux-s390x-gnu/-/resolver-binding-linux-s390x-gnu-1.11.1.tgz#577843a084c5952f5906770633ccfb89dac9bc94"
+  integrity sha512-kELo8ebBVtb9sA7rMe1Cph4QHreByhaZ2QEADd9NzIQsYNQpt9UkM9iqr2lhGr5afh885d/cB5QeTXSbZHTYPg==
+
+"@unrs/resolver-binding-linux-x64-gnu@1.11.1":
+  version "1.11.1"
+  resolved "https://registry.yarnpkg.com/@unrs/resolver-binding-linux-x64-gnu/-/resolver-binding-linux-x64-gnu-1.11.1.tgz#36fb318eebdd690f6da32ac5e0499a76fa881935"
+  integrity sha512-C3ZAHugKgovV5YvAMsxhq0gtXuwESUKc5MhEtjBpLoHPLYM+iuwSj3lflFwK3DPm68660rZ7G8BMcwSro7hD5w==
+
+"@unrs/resolver-binding-linux-x64-musl@1.11.1":
+  version "1.11.1"
+  resolved "https://registry.yarnpkg.com/@unrs/resolver-binding-linux-x64-musl/-/resolver-binding-linux-x64-musl-1.11.1.tgz#bfb9af75f783f98f6a22c4244214efe4df1853d6"
+  integrity sha512-rV0YSoyhK2nZ4vEswT/QwqzqQXw5I6CjoaYMOX0TqBlWhojUf8P94mvI7nuJTeaCkkds3QE4+zS8Ko+GdXuZtA==
+
+"@unrs/resolver-binding-wasm32-wasi@1.11.1":
+  version "1.11.1"
+  resolved "https://registry.yarnpkg.com/@unrs/resolver-binding-wasm32-wasi/-/resolver-binding-wasm32-wasi-1.11.1.tgz#752c359dd875684b27429500d88226d7cc72f71d"
+  integrity sha512-5u4RkfxJm+Ng7IWgkzi3qrFOvLvQYnPBmjmZQ8+szTK/b31fQCnleNl1GgEt7nIsZRIf5PLhPwT0WM+q45x/UQ==
+  dependencies:
+    "@napi-rs/wasm-runtime" "^0.2.11"
+
+"@unrs/resolver-binding-win32-arm64-msvc@1.11.1":
+  version "1.11.1"
+  resolved "https://registry.yarnpkg.com/@unrs/resolver-binding-win32-arm64-msvc/-/resolver-binding-win32-arm64-msvc-1.11.1.tgz#ce5735e600e4c2fbb409cd051b3b7da4a399af35"
+  integrity sha512-nRcz5Il4ln0kMhfL8S3hLkxI85BXs3o8EYoattsJNdsX4YUU89iOkVn7g0VHSRxFuVMdM4Q1jEpIId1Ihim/Uw==
+
+"@unrs/resolver-binding-win32-ia32-msvc@1.11.1":
+  version "1.11.1"
+  resolved "https://registry.yarnpkg.com/@unrs/resolver-binding-win32-ia32-msvc/-/resolver-binding-win32-ia32-msvc-1.11.1.tgz#72fc57bc7c64ec5c3de0d64ee0d1810317bc60a6"
+  integrity sha512-DCEI6t5i1NmAZp6pFonpD5m7i6aFrpofcp4LA2i8IIq60Jyo28hamKBxNrZcyOwVOZkgsRp9O2sXWBWP8MnvIQ==
+
+"@unrs/resolver-binding-win32-x64-msvc@1.11.1":
+  version "1.11.1"
+  resolved "https://registry.yarnpkg.com/@unrs/resolver-binding-win32-x64-msvc/-/resolver-binding-win32-x64-msvc-1.11.1.tgz#538b1e103bf8d9864e7b85cc96fa8d6fb6c40777"
+  integrity sha512-lrW200hZdbfRtztbygyaq/6jP6AKE8qQN2KvPcJ+x7wiD038YtnYtZ82IMNJ69GJibV7bwL3y9FgK+5w/pYt6g==
+
 abort-controller@^3.0.0:
   version "3.0.0"
   resolved "https://registry.yarnpkg.com/abort-controller/-/abort-controller-3.0.0.tgz#eaf54d53b62bae4138e809ca225c8439a6efb392"
@@ -971,6 +1747,13 @@ ansi-align@^3.0.0:
   dependencies:
     string-width "^4.1.0"
 
+ansi-escapes@^4.3.2:
+  version "4.3.2"
+  resolved "https://registry.yarnpkg.com/ansi-escapes/-/ansi-escapes-4.3.2.tgz#6b2291d1db7d98b6521d5f1efa42d0f3a9feb65e"
+  integrity sha512-gKXj5ALrKWQLsYG9jlTRmR/xKluxHV+Z9QEwNIgCfM1/uwPMCuzVVnh5mwTd+OuBZcwSIMbqssNWRm1lE51QaQ==
+  dependencies:
+    type-fest "^0.21.3"
+
 ansi-regex@^5.0.1:
   version "5.0.1"
   resolved "https://registry.yarnpkg.com/ansi-regex/-/ansi-regex-5.0.1.tgz#082cb2c89c9fe8659a311a53bd6a4dc5301db304"
@@ -988,6 +1771,11 @@ ansi-styles@^4.0.0, ansi-styles@^4.1.0:
   dependencies:
     color-convert "^2.0.1"
 
+ansi-styles@^5.2.0:
+  version "5.2.0"
+  resolved "https://registry.yarnpkg.com/ansi-styles/-/ansi-styles-5.2.0.tgz#07449690ad45777d1924ac2abb2fc8895dba836b"
+  integrity sha512-Cxwpt2SfTzTtXcfOlzGEee8O+c+MmUgGrNiBcXnuWxuFJHe6a5Hz7qwhwe5OgaSYI0IJvkLqWX1ASG+cJOkEiA==
+
 ansi-styles@^6.1.0:
   version "6.2.3"
   resolved "https://registry.yarnpkg.com/ansi-styles/-/ansi-styles-6.2.3.tgz#c044d5dcc521a076413472597a1acb1f103c4041"
@@ -998,7 +1786,7 @@ any-base@^1.1.0:
   resolved "https://registry.yarnpkg.com/any-base/-/any-base-1.1.0.tgz#ae101a62bc08a597b4c9ab5b7089d456630549fe"
   integrity sha512-uMgjozySS8adZZYePpaWs8cxB9/kdzmpX6SgJZ+wbz1K5eYk5QMYDVJaZKhxyIHUdnnJkfR7SVgStgH7LkGUyg==
 
-anymatch@~3.1.2:
+anymatch@^3.1.3, anymatch@~3.1.2:
   version "3.1.3"
   resolved "https://registry.yarnpkg.com/anymatch/-/anymatch-3.1.3.tgz#790c58b19ba1720a84205b57c618d5ad8524973e"
   integrity sha512-KMReFUr0B4t+D+OBkjR3KYqvocp2XaSzO55UcB6mgQMd3KbcE+mWTyvVV7D/zsdEbNnV6acZUutkiHQXvTr1Rw==
@@ -1011,6 +1799,13 @@ arg@^4.1.0:
   resolved "https://registry.yarnpkg.com/arg/-/arg-4.1.3.tgz#269fc7ad5b8e42cb63c896d5666017261c144089"
   integrity sha512-58S9QDqG0Xx27YwPSt9fJxivjYl432YCwfDMfZ+71RAqUrZef7LrKQZ3LHLOwCS4FLNBplP533Zx895SeOCHvA==
 
+argparse@^1.0.7:
+  version "1.0.10"
+  resolved "https://registry.yarnpkg.com/argparse/-/argparse-1.0.10.tgz#bcd6791ea5ae09725e17e5ad988134cd40b3d911"
+  integrity sha512-o5Roy6tNG4SL/FOkCAN6RzjiakZS25RLYFrcMttJqbdd8BWrnA+fGz57iN5Pb06pvBGvl5gQ0B48dJlslXvoTg==
+  dependencies:
+    sprintf-js "~1.0.2"
+
 argparse@^2.0.1:
   version "2.0.1"
   resolved "https://registry.yarnpkg.com/argparse/-/argparse-2.0.1.tgz#246f50f3ca78a3240f6c997e8a9bd1eac49e4b38"
@@ -1040,6 +1835,66 @@ axios@^1.8.4:
     form-data "^4.0.4"
     proxy-from-env "^1.1.0"
 
+babel-jest@30.2.0:
+  version "30.2.0"
+  resolved "https://registry.yarnpkg.com/babel-jest/-/babel-jest-30.2.0.tgz#fd44a1ec9552be35ead881f7381faa7d8f3b95ac"
+  integrity sha512-0YiBEOxWqKkSQWL9nNGGEgndoeL0ZpWrbLMNL5u/Kaxrli3Eaxlt3ZtIDktEvXt4L/R9r3ODr2zKwGM/2BjxVw==
+  dependencies:
+    "@jest/transform" "30.2.0"
+    "@types/babel__core" "^7.20.5"
+    babel-plugin-istanbul "^7.0.1"
+    babel-preset-jest "30.2.0"
+    chalk "^4.1.2"
+    graceful-fs "^4.2.11"
+    slash "^3.0.0"
+
+babel-plugin-istanbul@^7.0.1:
+  version "7.0.1"
+  resolved "https://registry.yarnpkg.com/babel-plugin-istanbul/-/babel-plugin-istanbul-7.0.1.tgz#d8b518c8ea199364cf84ccc82de89740236daf92"
+  integrity sha512-D8Z6Qm8jCvVXtIRkBnqNHX0zJ37rQcFJ9u8WOS6tkYOsRdHBzypCstaxWiu5ZIlqQtviRYbgnRLSoCEvjqcqbA==
+  dependencies:
+    "@babel/helper-plugin-utils" "^7.0.0"
+    "@istanbuljs/load-nyc-config" "^1.0.0"
+    "@istanbuljs/schema" "^0.1.3"
+    istanbul-lib-instrument "^6.0.2"
+    test-exclude "^6.0.0"
+
+babel-plugin-jest-hoist@30.2.0:
+  version "30.2.0"
+  resolved "https://registry.yarnpkg.com/babel-plugin-jest-hoist/-/babel-plugin-jest-hoist-30.2.0.tgz#94c250d36b43f95900f3a219241e0f4648191ce2"
+  integrity sha512-ftzhzSGMUnOzcCXd6WHdBGMyuwy15Wnn0iyyWGKgBDLxf9/s5ABuraCSpBX2uG0jUg4rqJnxsLc5+oYBqoxVaA==
+  dependencies:
+    "@types/babel__core" "^7.20.5"
+
+babel-preset-current-node-syntax@^1.2.0:
+  version "1.2.0"
+  resolved "https://registry.yarnpkg.com/babel-preset-current-node-syntax/-/babel-preset-current-node-syntax-1.2.0.tgz#20730d6cdc7dda5d89401cab10ac6a32067acde6"
+  integrity sha512-E/VlAEzRrsLEb2+dv8yp3bo4scof3l9nR4lrld+Iy5NyVqgVYUJnDAmunkhPMisRI32Qc4iRiz425d8vM++2fg==
+  dependencies:
+    "@babel/plugin-syntax-async-generators" "^7.8.4"
+    "@babel/plugin-syntax-bigint" "^7.8.3"
+    "@babel/plugin-syntax-class-properties" "^7.12.13"
+    "@babel/plugin-syntax-class-static-block" "^7.14.5"
+    "@babel/plugin-syntax-import-attributes" "^7.24.7"
+    "@babel/plugin-syntax-import-meta" "^7.10.4"
+    "@babel/plugin-syntax-json-strings" "^7.8.3"
+    "@babel/plugin-syntax-logical-assignment-operators" "^7.10.4"
+    "@babel/plugin-syntax-nullish-coalescing-operator" "^7.8.3"
+    "@babel/plugin-syntax-numeric-separator" "^7.10.4"
+    "@babel/plugin-syntax-object-rest-spread" "^7.8.3"
+    "@babel/plugin-syntax-optional-catch-binding" "^7.8.3"
+    "@babel/plugin-syntax-optional-chaining" "^7.8.3"
+    "@babel/plugin-syntax-private-property-in-object" "^7.14.5"
+    "@babel/plugin-syntax-top-level-await" "^7.14.5"
+
+babel-preset-jest@30.2.0:
+  version "30.2.0"
+  resolved "https://registry.yarnpkg.com/babel-preset-jest/-/babel-preset-jest-30.2.0.tgz#04717843e561347781d6d7f69c81e6bcc3ed11ce"
+  integrity sha512-US4Z3NOieAQumwFnYdUWKvUKh8+YSnS/gB3t6YBiz0bskpu7Pine8pPCheNxlPEW4wnUkma2a94YuW2q3guvCQ==
+  dependencies:
+    babel-plugin-jest-hoist "30.2.0"
+    babel-preset-current-node-syntax "^1.2.0"
+
 balanced-match@^1.0.0:
   version "1.0.2"
   resolved "https://registry.yarnpkg.com/balanced-match/-/balanced-match-1.0.2.tgz#e83e3a7e3f300b34cb9d87f615fa0cbf357690ee"
@@ -1050,6 +1905,11 @@ base64-js@^1.3.0, base64-js@^1.3.1:
   resolved "https://registry.yarnpkg.com/base64-js/-/base64-js-1.5.1.tgz#1b1b440160a5bf7ad40b650f095963481903930a"
   integrity sha512-AKpaYlHn8t4SVbOHCy+b5+KKgvR4vrsD8vbvrbiQJps7fKDTkjkDry6ji0rUJjC0kzbNePLwzxq8iypo41qeWA==
 
+baseline-browser-mapping@^2.9.0:
+  version "2.9.19"
+  resolved "https://registry.yarnpkg.com/baseline-browser-mapping/-/baseline-browser-mapping-2.9.19.tgz#3e508c43c46d961eb4d7d2e5b8d1dd0f9ee4f488"
+  integrity sha512-ipDqC8FrAl/76p2SSWKSI+H9tFwm7vYqXQrItCuiVPt26Km0jS+NzSsBWAaBusvSbQcfJG+JitdMm+wZAgTYqg==
+
 bignumber.js@^9.0.0:
   version "9.3.1"
   resolved "https://registry.yarnpkg.com/bignumber.js/-/bignumber.js-9.3.1.tgz#759c5aaddf2ffdc4f154f7b493e1c8770f88c4d7"
@@ -1125,11 +1985,41 @@ braces@^3.0.3, braces@~3.0.2:
   dependencies:
     fill-range "^7.1.1"
 
+browserslist@^4.24.0:
+  version "4.28.1"
+  resolved "https://registry.yarnpkg.com/browserslist/-/browserslist-4.28.1.tgz#7f534594628c53c63101079e27e40de490456a95"
+  integrity sha512-ZC5Bd0LgJXgwGqUknZY/vkUQ04r8NXnJZ3yYi4vDmSiZmC/pdSN0NbNRPxZpbtO4uAfDUAFffO8IZoM3Gj8IkA==
+  dependencies:
+    baseline-browser-mapping "^2.9.0"
+    caniuse-lite "^1.0.30001759"
+    electron-to-chromium "^1.5.263"
+    node-releases "^2.0.27"
+    update-browserslist-db "^1.2.0"
+
+bs-logger@^0.2.6:
+  version "0.2.6"
+  resolved "https://registry.yarnpkg.com/bs-logger/-/bs-logger-0.2.6.tgz#eb7d365307a72cf974cc6cda76b68354ad336bd8"
+  integrity sha512-pd8DCoxmbgc7hyPKOvxtqNcjYoOsABPQdcCUjGp3d42VR2CX1ORhk2A87oqqu5R1kk+76nsxZupkmyd+MVtCog==
+  dependencies:
+    fast-json-stable-stringify "2.x"
+
+bser@2.1.1:
+  version "2.1.1"
+  resolved "https://registry.yarnpkg.com/bser/-/bser-2.1.1.tgz#e6787da20ece9d07998533cfd9de6f5c38f4bc05"
+  integrity sha512-gQxTNE/GAfIIrmHLUE3oJyp5FO6HRBfhjnw4/wMmA63ZGDJnWBmgY/lyQBpnDUkGmAhbSe39tx2d/iTOAfglwQ==
+  dependencies:
+    node-int64 "^0.4.0"
+
 buffer-equal-constant-time@^1.0.1:
   version "1.0.1"
   resolved "https://registry.yarnpkg.com/buffer-equal-constant-time/-/buffer-equal-constant-time-1.0.1.tgz#f8e71132f7ffe6e01a5c9697a4c6f3e48d5cc819"
   integrity sha512-zRpUiDwd/xk6ADqPMATG8vc9VPrkck7T07OIx0gnjmJAnHnTVXNQG3vfvWNuiZIkwu9KrKdA1iJKfsfTVxE6NA==
 
+buffer-from@^1.0.0:
+  version "1.1.2"
+  resolved "https://registry.yarnpkg.com/buffer-from/-/buffer-from-1.1.2.tgz#2b146a6fd72e80b4f55d255f35ed59a3a9a41bd5"
+  integrity sha512-E+XQCRwSbaaiChtv6k6Dwgc+bx+Bs6vuKJHHl5kox/BaKbhiXzqQOwK4cO22yElGp2OCmjwVhT3HmxgyPGnJfQ==
+
 buffer@^5.5.0:
   version "5.7.1"
   resolved "https://registry.yarnpkg.com/buffer/-/buffer-5.7.1.tgz#ba62e7c13133053582197160851a8f648e99eed0"
@@ -1167,17 +2057,27 @@ call-bound@^1.0.2:
     call-bind-apply-helpers "^1.0.2"
     get-intrinsic "^1.3.0"
 
-callsites@^3.0.0:
+callsites@^3.0.0, callsites@^3.1.0:
   version "3.1.0"
   resolved "https://registry.yarnpkg.com/callsites/-/callsites-3.1.0.tgz#b3630abd8943432f54b3f0519238e33cd7df2f73"
   integrity sha512-P8BjAsXvZS+VIDUI11hHCQEv74YT67YUi5JJFNWIqL235sBmjX4+qx9Muvls5ivyNENctx46xQLQ3aTuE7ssaQ==
 
-camelcase@^6.2.0:
+camelcase@^5.3.1:
+  version "5.3.1"
+  resolved "https://registry.yarnpkg.com/camelcase/-/camelcase-5.3.1.tgz#e3c9b31569e106811df242f715725a1f4c494320"
+  integrity sha512-L28STB170nwWS63UjtlEOE3dldQApaJXZkOI1uMFfzf3rRuPegHaHesyee+YxQ+W6SvRDQV6UrdOdRiR153wJg==
+
+camelcase@^6.2.0, camelcase@^6.3.0:
   version "6.3.0"
   resolved "https://registry.yarnpkg.com/camelcase/-/camelcase-6.3.0.tgz#5685b95eb209ac9c0c177467778c9c84df58ba9a"
   integrity sha512-Gmy6FhYlCY7uOElZUSbxo2UCDH8owEk996gkbrpsgGtrJLM3J7jGxl9Ic7Qwwj4ivOE5AWZWRMecDdF7hqGjFA==
 
-chalk@4.1.2, chalk@^4.0.0, chalk@^4.1.0:
+caniuse-lite@^1.0.30001759:
+  version "1.0.30001769"
+  resolved "https://registry.yarnpkg.com/caniuse-lite/-/caniuse-lite-1.0.30001769.tgz#1ad91594fad7dc233777c2781879ab5409f7d9c2"
+  integrity sha512-BCfFL1sHijQlBGWBMuJyhZUhzo7wer5sVj9hqekB/7xn0Ypy+pER/edCYQm4exbXj4WiySGp40P8UuTh6w1srg==
+
+chalk@4.1.2, chalk@^4.0.0, chalk@^4.1.0, chalk@^4.1.2:
   version "4.1.2"
   resolved "https://registry.yarnpkg.com/chalk/-/chalk-4.1.2.tgz#aac4e2b7734a740867aeb16bf02aad556a1e7a01"
   integrity sha512-oKnbhFyRIXpUuez8iBMmyEa4nbj4IOQyuhc/wy9kY7/WVPcwIO9VA668Pu8RkO7+0G76SLROeyw9CpQ061i4mA==
@@ -1185,6 +2085,11 @@ chalk@4.1.2, chalk@^4.0.0, chalk@^4.1.0:
     ansi-styles "^4.1.0"
     supports-color "^7.1.0"
 
+char-regex@^1.0.2:
+  version "1.0.2"
+  resolved "https://registry.yarnpkg.com/char-regex/-/char-regex-1.0.2.tgz#d744358226217f981ed58f479b1d6bcc29545dcf"
+  integrity sha512-kWWXztvZ5SBQV+eRgKFeh8q5sLuZY2+8WUIzlxWVTg+oGwY14qylx1KbKzHd8P6ZYkAg0xyIDU9JMHhyJMZ1jw==
+
 chardet@^2.1.0:
   version "2.1.0"
   resolved "https://registry.yarnpkg.com/chardet/-/chardet-2.1.0.tgz#1007f441a1ae9f9199a4a67f6e978fb0aa9aa3fe"
@@ -1205,6 +2110,16 @@ chokidar@^3.5.3:
   optionalDependencies:
     fsevents "~2.3.2"
 
+ci-info@^4.2.0:
+  version "4.4.0"
+  resolved "https://registry.yarnpkg.com/ci-info/-/ci-info-4.4.0.tgz#7d54eff9f54b45b62401c26032696eb59c8bd18c"
+  integrity sha512-77PSwercCZU2Fc4sX94eF8k8Pxte6JAwL4/ICZLFjJLqegs7kCuAsqqj/70NQF6TvDpgFjkubQB2FW2ZZddvQg==
+
+cjs-module-lexer@^2.1.0:
+  version "2.2.0"
+  resolved "https://registry.yarnpkg.com/cjs-module-lexer/-/cjs-module-lexer-2.2.0.tgz#b3ca5101843389259ade7d88c77bd06ce55849ca"
+  integrity sha512-4bHTS2YuzUvtoLjdy+98ykbNB5jS0+07EvFNXerqZQJ89F7DI6ET7OQo/HJuW6K0aVsKA9hj9/RVb2kQVOrPDQ==
+
 cli-boxes@^2.2.1:
   version "2.2.1"
   resolved "https://registry.yarnpkg.com/cli-boxes/-/cli-boxes-2.2.1.tgz#ddd5035d25094fce220e9cab40a45840a440318f"
@@ -1227,11 +2142,30 @@ cli-width@^4.1.0:
   resolved "https://registry.yarnpkg.com/cli-width/-/cli-width-4.1.0.tgz#42daac41d3c254ef38ad8ac037672130173691c5"
   integrity sha512-ouuZd4/dm2Sw5Gmqy6bGyNNNe1qt9RpmxveLSO7KcgsTnU7RXfsw+/bukWGo1abgBiMAic068rclZsO4IWmmxQ==
 
+cliui@^8.0.1:
+  version "8.0.1"
+  resolved "https://registry.yarnpkg.com/cliui/-/cliui-8.0.1.tgz#0c04b075db02cbfe60dc8e6cf2f5486b1a3608aa"
+  integrity sha512-BSeNnyus75C4//NQ9gQt1/csTXyo/8Sb+afLAkzAptFuMsod9HFokGNudZpi/oQV73hnVK+sR+5PVRMd+Dr7YQ==
+  dependencies:
+    string-width "^4.2.0"
+    strip-ansi "^6.0.1"
+    wrap-ansi "^7.0.0"
+
 clone@^1.0.2:
   version "1.0.4"
   resolved "https://registry.yarnpkg.com/clone/-/clone-1.0.4.tgz#da309cc263df15994c688ca902179ca3c7cd7c7e"
   integrity sha512-JQHZ2QMW6l3aH/j6xCqQThY/9OH4D/9ls34cgkUBiEeocRTU04tHfKPBsUK1PqZCUQM7GiA0IIXJSuXHI64Kbg==
 
+co@^4.6.0:
+  version "4.6.0"
+  resolved "https://registry.yarnpkg.com/co/-/co-4.6.0.tgz#6ea6bdf3d853ae54ccb8e47bfa0bf3f9031fb184"
+  integrity sha512-QVb0dM5HvG+uaxitm8wONl7jltx8dqhfU33DcqtOZcLSVIKSDDLDi7+0LbAKiyI8hD9u42m2YxXSkMGWThaecQ==
+
+collect-v8-coverage@^1.0.2:
+  version "1.0.3"
+  resolved "https://registry.yarnpkg.com/collect-v8-coverage/-/collect-v8-coverage-1.0.3.tgz#cc1f01eb8d02298cbc9a437c74c70ab4e5210b80"
+  integrity sha512-1L5aqIkwPfiodaMgQunkF1zRhNqifHBmtbbbxcr6yVxxBnliw4TDOW6NxpO8DJLgJ16OT+Y4ztZqP6p/FtXnAw==
+
 color-convert@^2.0.1:
   version "2.0.1"
   resolved "https://registry.yarnpkg.com/color-convert/-/color-convert-2.0.1.tgz#72d3a68d598c9bdb3af2ad1e84f21d896abd4de3"
@@ -1278,6 +2212,11 @@ content-type@^1.0.5:
   resolved "https://registry.yarnpkg.com/content-type/-/content-type-1.0.5.tgz#8b773162656d1d1086784c8f23a54ce6d73d7918"
   integrity sha512-nTjqfcBFEipKdXCv4YDQWCfmcLZKm81ldF0pAopTvyrFGVbcR6P/VAAd5G7N+0tTr8QqiU0tFadD6FK4NtJwOA==
 
+convert-source-map@^2.0.0:
+  version "2.0.0"
+  resolved "https://registry.yarnpkg.com/convert-source-map/-/convert-source-map-2.0.0.tgz#4b560f649fc4e918dd0ab75cf4961e8bc882d82a"
+  integrity sha512-Kvp459HrV2FEJ1CAsi1Ku+MY3kasH19TFykTz2xWmMeq6bk2NU3XXvfJ+Q61m0xktWwt+1HSYf3JZsTms3aRJg==
+
 cookie-signature@^1.2.1:
   version "1.2.2"
   resolved "https://registry.yarnpkg.com/cookie-signature/-/cookie-signature-1.2.2.tgz#57c7fc3cc293acab9fec54d73e15690ebe4a1793"
@@ -1308,7 +2247,7 @@ cross-fetch@~4.1.0:
   dependencies:
     node-fetch "^2.7.0"
 
-cross-spawn@^7.0.5, cross-spawn@^7.0.6:
+cross-spawn@^7.0.3, cross-spawn@^7.0.5, cross-spawn@^7.0.6:
   version "7.0.6"
   resolved "https://registry.yarnpkg.com/cross-spawn/-/cross-spawn-7.0.6.tgz#8a58fe78f00dcd70c370451759dfbfaf03e8ee9f"
   integrity sha512-uV2QOWP2nWzsy2aMp8aRibhi9dlzF5Hgh5SHaB9OiTGEyDTiJJyx0uy51QXdyWbtAHNua4XJzUKca3OzKUd3vA==
@@ -1327,18 +2266,28 @@ data-uri-to-buffer@^4.0.0:
   resolved "https://registry.yarnpkg.com/data-uri-to-buffer/-/data-uri-to-buffer-4.0.1.tgz#d8feb2b2881e6a4f58c2e08acfd0e2834e26222e"
   integrity sha512-0R9ikRb668HB7QDxT1vkpuUBtqc53YyAwMwGeUFKRojY/NWKvdZ+9UYtRfGmhqNbRkTSVpMbmyhXipFFv2cb/A==
 
-debug@4, debug@^4.3.1, debug@^4.3.2, debug@^4.3.4, debug@^4.3.5, debug@^4.4.0:
+debug@4, debug@^4.1.0, debug@^4.1.1, debug@^4.3.1, debug@^4.3.2, debug@^4.3.4, debug@^4.3.5, debug@^4.4.0:
   version "4.4.3"
   resolved "https://registry.yarnpkg.com/debug/-/debug-4.4.3.tgz#c6ae432d9bd9662582fce08709b038c58e9e3d6a"
   integrity sha512-RGwwWnwQvkVfavKVt22FGLw+xYSdzARwm0ru6DhTVA3umU5hZc28V3kO4stgYryrTlLpuvgI9GiijltAjNbcqA==
   dependencies:
     ms "^2.1.3"
 
+dedent@^1.6.0:
+  version "1.7.1"
+  resolved "https://registry.yarnpkg.com/dedent/-/dedent-1.7.1.tgz#364661eea3d73f3faba7089214420ec2f8f13e15"
+  integrity sha512-9JmrhGZpOlEgOLdQgSm0zxFaYoQon408V1v49aqTWuXENVlnCuY9JBZcXZiCsZQWDjTm5Qf/nIvAy77mXDAjEg==
+
 deep-is@^0.1.3:
   version "0.1.4"
   resolved "https://registry.yarnpkg.com/deep-is/-/deep-is-0.1.4.tgz#a6f2dce612fadd2ef1f519b73551f17e85199831"
   integrity sha512-oIPzksmTg4/MriiaYGO+okXDT7ztn/w3Eptv/+gSIdMdKsJo0u4CfYNFJPy+4SKMuCqGw2wxnA+URMg3t8a/bQ==
 
+deepmerge@^4.3.1:
+  version "4.3.1"
+  resolved "https://registry.yarnpkg.com/deepmerge/-/deepmerge-4.3.1.tgz#44b5f2147cd3b00d4b56137685966f26fd25dd4a"
+  integrity sha512-3sUqbMEc77XqpdNO7FRyRog+eW3ph+GYCbj+rK+uYyRMuwsVy0rMiVtPn+QJlKFvWP/1PYpapqYn0Me2knFn+A==
+
 defaults@^1.0.3:
   version "1.0.4"
   resolved "https://registry.yarnpkg.com/defaults/-/defaults-1.0.4.tgz#b0b02062c1e2aa62ff5d9528f0f98baa90978d7a"
@@ -1356,6 +2305,11 @@ depd@2.0.0, depd@^2.0.0:
   resolved "https://registry.yarnpkg.com/depd/-/depd-2.0.0.tgz#b696163cc757560d09cf22cc8fad1571b79e76df"
   integrity sha512-g7nH6P6dyDioJogAAGprGpCtVImJhpPk/roCzdb3fIh61/s/nPsfR6onyMwkCAR/OlC3yBC0lESvUoQEAssIrw==
 
+detect-newline@^3.1.0:
+  version "3.1.0"
+  resolved "https://registry.yarnpkg.com/detect-newline/-/detect-newline-3.1.0.tgz#576f5dfc63ae1a192ff192d8ad3af6308991b651"
+  integrity sha512-TLz+x/vEXm/Y7P7wn1EJFNLxYpUD4TgMosxY6fAVJUnJMbupHBOncxyWUG9OpTaH9EBD7uFI5LfEgmMOc54DsA==
+
 devtools-protocol@^0.0.1537100:
   version "0.0.1537100"
   resolved "https://registry.yarnpkg.com/devtools-protocol/-/devtools-protocol-0.0.1537100.tgz#0d272eca71ce69914513c301921d980dcda8432d"
@@ -1409,6 +2363,16 @@ ee-first@1.1.1:
   resolved "https://registry.yarnpkg.com/ee-first/-/ee-first-1.1.1.tgz#590c61156b0ae2f4f0255732a158b266bc56b21d"
   integrity sha512-WMwm9LhRUo+WUaRN+vRuETqG89IgZphVSNkdFgeb6sS/E4OrDIN7t48CAewSHXc6C8lefD8KKfr5vY61brQlow==
 
+electron-to-chromium@^1.5.263:
+  version "1.5.286"
+  resolved "https://registry.yarnpkg.com/electron-to-chromium/-/electron-to-chromium-1.5.286.tgz#142be1ab5e1cd5044954db0e5898f60a4960384e"
+  integrity sha512-9tfDXhJ4RKFNerfjdCcZfufu49vg620741MNs26a9+bhLThdB+plgMeou98CAaHu/WATj2iHOOHTp1hWtABj2A==
+
+emittery@^0.13.1:
+  version "0.13.1"
+  resolved "https://registry.yarnpkg.com/emittery/-/emittery-0.13.1.tgz#c04b8c3457490e0847ae51fced3af52d338e3dad"
+  integrity sha512-DeWwawk6r5yR9jFgnDKYt4sLS0LmHJJi3ZOnb5/JdbYwj3nW+FxQnHIjhBKz8YLC7oRNPVM9NQ47I3CVx34eqQ==
+
 emoji-regex@^8.0.0:
   version "8.0.0"
   resolved "https://registry.yarnpkg.com/emoji-regex/-/emoji-regex-8.0.0.tgz#e818fd69ce5ccfcb404594f842963bf53164cc37"
@@ -1424,6 +2388,13 @@ encodeurl@^2.0.0:
   resolved "https://registry.yarnpkg.com/encodeurl/-/encodeurl-2.0.0.tgz#7b8ea898077d7e409d3ac45474ea38eaf0857a58"
   integrity sha512-Q0n9HRi4m6JuGIV1eFlmvJB7ZEVxu93IrMyiMsGC0lrMJMWzRgx6WGquyfQgZVb31vhGgXnfmPNNXmxnOkRBrg==
 
+error-ex@^1.3.1:
+  version "1.3.4"
+  resolved "https://registry.yarnpkg.com/error-ex/-/error-ex-1.3.4.tgz#b3a8d8bb6f92eecc1629e3e27d3c8607a8a32414"
+  integrity sha512-sqQamAnR14VgCr1A618A3sGrygcpK+HEbenA/HiEAkkUwcZIIB/tgWqHFxWgOyDh4nB4JCRimh79dR5Ywc9MDQ==
+  dependencies:
+    is-arrayish "^0.2.1"
+
 es-define-property@^1.0.1:
   version "1.0.1"
   resolved "https://registry.yarnpkg.com/es-define-property/-/es-define-property-1.0.1.tgz#983eb2f9a6724e9303f61addf011c72e09e0b0fa"
@@ -1483,11 +2454,21 @@ esbuild@^0.25.2, esbuild@~0.25.0:
     "@esbuild/win32-ia32" "0.25.11"
     "@esbuild/win32-x64" "0.25.11"
 
+escalade@^3.1.1, escalade@^3.2.0:
+  version "3.2.0"
+  resolved "https://registry.yarnpkg.com/escalade/-/escalade-3.2.0.tgz#011a3f69856ba189dffa7dc8fcce99d2a87903e5"
+  integrity sha512-WUj2qlxaQtO4g6Pq5c29GTcWGDyd8itL8zTlipgECz3JesAiiOKotd8JU6otB3PACgG6xkJUyVhboMS+bje/jA==
+
 escape-html@^1.0.3:
   version "1.0.3"
   resolved "https://registry.yarnpkg.com/escape-html/-/escape-html-1.0.3.tgz#0258eae4d3d0c0974de1c169188ef0051d1d1988"
   integrity sha512-NiSupZ4OeuGwr68lGIeym/ksIZMJodUGOSCZ/FSnTxcrekbvqrgdUxlJOMpijaKZVjAJrWrGs/6Jy8OMuyj9ow==
 
+escape-string-regexp@^2.0.0:
+  version "2.0.0"
+  resolved "https://registry.yarnpkg.com/escape-string-regexp/-/escape-string-regexp-2.0.0.tgz#a30304e99daa32e23b2fd20f51babd07cffca344"
+  integrity sha512-UpzcLCXolUWcNu5HtVMHYdXJjArjsF9C0aNnquZYY4uW/Vu0miy5YoWvbV345HauVvcAUnpRuhMMcqTcGOY2+w==
+
 escape-string-regexp@^4.0.0:
   version "4.0.0"
   resolved "https://registry.yarnpkg.com/escape-string-regexp/-/escape-string-regexp-4.0.0.tgz#14ba83a5d373e3d311e5afca29cf5bfad965bf34"
@@ -1565,6 +2546,11 @@ espree@^10.0.1, espree@^10.4.0:
     acorn-jsx "^5.3.2"
     eslint-visitor-keys "^4.2.1"
 
+esprima@^4.0.0:
+  version "4.0.1"
+  resolved "https://registry.yarnpkg.com/esprima/-/esprima-4.0.1.tgz#13b04cdb3e6c5d19df91ab6987a8695619b0aa71"
+  integrity sha512-eGuFFw7Upda+g4p+QHvnW0RyTX/SVeJBDM/gCtMARO0cLuT2HcEKnTPvhjV6aGeqrCB/sbNop0Kszm0jsaWU4A==
+
 esquery@^1.5.0:
   version "1.6.0"
   resolved "https://registry.yarnpkg.com/esquery/-/esquery-1.6.0.tgz#91419234f804d852a82dceec3e16cdc22cf9dae7"
@@ -1627,11 +2613,43 @@ exa-js@^1.5.13:
     zod "^3.22.0"
     zod-to-json-schema "^3.20.0"
 
+execa@^5.1.1:
+  version "5.1.1"
+  resolved "https://registry.yarnpkg.com/execa/-/execa-5.1.1.tgz#f80ad9cbf4298f7bd1d4c9555c21e93741c411dd"
+  integrity sha512-8uSpZZocAZRBAPIEINJj3Lo9HyGitllczc27Eh5YYojjMFMn8yHMDMaUHE2Jqfq05D/wucwI4JGURyXt1vchyg==
+  dependencies:
+    cross-spawn "^7.0.3"
+    get-stream "^6.0.0"
+    human-signals "^2.1.0"
+    is-stream "^2.0.0"
+    merge-stream "^2.0.0"
+    npm-run-path "^4.0.1"
+    onetime "^5.1.2"
+    signal-exit "^3.0.3"
+    strip-final-newline "^2.0.0"
+
 exif-parser@^0.1.12:
   version "0.1.12"
   resolved "https://registry.yarnpkg.com/exif-parser/-/exif-parser-0.1.12.tgz#58a9d2d72c02c1f6f02a0ef4a9166272b7760922"
   integrity sha512-c2bQfLNbMzLPmzQuOr8fy0csy84WmwnER81W88DzTp9CYNPJ6yzOj2EZAh9pywYpqHnshVLHQJ8WzldAyfY+Iw==
 
+exit-x@^0.2.2:
+  version "0.2.2"
+  resolved "https://registry.yarnpkg.com/exit-x/-/exit-x-0.2.2.tgz#1f9052de3b8d99a696b10dad5bced9bdd5c3aa64"
+  integrity sha512-+I6B/IkJc1o/2tiURyz/ivu/O0nKNEArIUB5O7zBrlDVJr22SCLH3xTeEry428LvFhRzIA1g8izguxJ/gbNcVQ==
+
+expect@30.2.0, expect@^30.0.0:
+  version "30.2.0"
+  resolved "https://registry.yarnpkg.com/expect/-/expect-30.2.0.tgz#d4013bed267013c14bc1199cec8aa57cee9b5869"
+  integrity sha512-u/feCi0GPsI+988gU2FLcsHyAHTU0MX1Wg68NhAnN7z/+C5wqG+CY8J53N9ioe8RXgaoz0nBR/TYMf3AycUuPw==
+  dependencies:
+    "@jest/expect-utils" "30.2.0"
+    "@jest/get-type" "30.1.0"
+    jest-matcher-utils "30.2.0"
+    jest-message-util "30.2.0"
+    jest-mock "30.2.0"
+    jest-util "30.2.0"
+
 express-rate-limit@^7.5.0:
   version "7.5.1"
   resolved "https://registry.yarnpkg.com/express-rate-limit/-/express-rate-limit-7.5.1.tgz#8c3a42f69209a3a1c969890070ece9e20a879dec"
@@ -1691,7 +2709,7 @@ fast-glob@^3.2.9, fast-glob@^3.3.2:
     merge2 "^1.3.0"
     micromatch "^4.0.8"
 
-fast-json-stable-stringify@^2.0.0:
+fast-json-stable-stringify@2.x, fast-json-stable-stringify@^2.0.0, fast-json-stable-stringify@^2.1.0:
   version "2.1.0"
   resolved "https://registry.yarnpkg.com/fast-json-stable-stringify/-/fast-json-stable-stringify-2.1.0.tgz#874bf69c6f404c2b5d99c481341399fd55892633"
   integrity sha512-lhd/wF+Lk98HZoTCtlVraHtfh5XYijIjalXck7saUtuanSDyLMxnHhSXEDJqHxD7msR8D0uCmqlkwjCV8xvwHw==
@@ -1708,6 +2726,13 @@ fastq@^1.6.0:
   dependencies:
     reusify "^1.0.4"
 
+fb-watchman@^2.0.2:
+  version "2.0.2"
+  resolved "https://registry.yarnpkg.com/fb-watchman/-/fb-watchman-2.0.2.tgz#e9524ee6b5c77e9e5001af0f85f3adbb8623255c"
+  integrity sha512-p5161BqbuCaSnB8jIbzQHOlpgsPmK5rJVDfDKO91Axs5NC1uu3HRQm6wt9cd9/+GtQQIO53JdGXXoyDpTAsgYA==
+  dependencies:
+    bser "2.1.1"
+
 fetch-blob@^3.1.2, fetch-blob@^3.1.4:
   version "3.2.0"
   resolved "https://registry.yarnpkg.com/fetch-blob/-/fetch-blob-3.2.0.tgz#f09b8d4bbd45adc6f0c20b7e787e793e309dcce9"
@@ -1751,6 +2776,14 @@ finalhandler@^2.1.0:
     parseurl "^1.3.3"
     statuses "^2.0.1"
 
+find-up@^4.0.0, find-up@^4.1.0:
+  version "4.1.0"
+  resolved "https://registry.yarnpkg.com/find-up/-/find-up-4.1.0.tgz#97afe7d6cdc0bc5928584b7c8d7b16e8a9aa5d19"
+  integrity sha512-PpOwAdQ/YlXQ2vj8a3h8IipDuYRi3wceVQQGYWxNINccq40Anw7BlsEXCMbt1Zt+OLA6Fq9suIpIWD0OsnISlw==
+  dependencies:
+    locate-path "^5.0.0"
+    path-exists "^4.0.0"
+
 find-up@^5.0.0:
   version "5.0.0"
   resolved "https://registry.yarnpkg.com/find-up/-/find-up-5.0.0.tgz#4c92819ecb7083561e4f4a240a86be5198f536fc"
@@ -1813,12 +2846,17 @@ fresh@^2.0.0:
   resolved "https://registry.yarnpkg.com/fresh/-/fresh-2.0.0.tgz#8dd7df6a1b3a1b3a5cf186c05a5dd267622635a4"
   integrity sha512-Rx/WycZ60HOaqLKAi6cHRKKI7zxWbJ31MhntmtwMoaTeF7XFH9hhBp8vITaMidfljRQ6eYWCKkaTK+ykVJHP2A==
 
+fs.realpath@^1.0.0:
+  version "1.0.0"
+  resolved "https://registry.yarnpkg.com/fs.realpath/-/fs.realpath-1.0.0.tgz#1504ad2523158caa40db4a2787cb01411994ea4f"
+  integrity sha512-OO0pH2lK6a0hZnAdau5ItzHPI6pUlvI7jMVnxUQRtw4owF2wk8lOSabtGDCTP4Ggrg2MbGnWO9X8K1t4+fGMDw==
+
 fsevents@2.3.2:
   version "2.3.2"
   resolved "https://registry.yarnpkg.com/fsevents/-/fsevents-2.3.2.tgz#8a526f78b8fdf4623b709e0b975c52c24c02fd1a"
   integrity sha512-xiqMQR4xAeHTuB9uWm+fFRcIOgKBMiOBP+eXiyT7jsgVCq1bkVygt00oASowB7EdtpOHaaPgKt812P9ab+DDKA==
 
-fsevents@~2.3.2, fsevents@~2.3.3:
+fsevents@^2.3.3, fsevents@~2.3.2, fsevents@~2.3.3:
   version "2.3.3"
   resolved "https://registry.yarnpkg.com/fsevents/-/fsevents-2.3.3.tgz#cac6407785d03675a2a5e1a5305c697b347d90d6"
   integrity sha512-5xoDfX+fL7faATnagmWPpbFtwh/R77WmMMqqHGS65C3vvB0YHrgF+B1YmZ3441tMj5n63k0212XNoJwzlhffQw==
@@ -1847,6 +2885,16 @@ gcp-metadata@^8.0.0:
     google-logging-utils "^1.0.0"
     json-bigint "^1.0.0"
 
+gensync@^1.0.0-beta.2:
+  version "1.0.0-beta.2"
+  resolved "https://registry.yarnpkg.com/gensync/-/gensync-1.0.0-beta.2.tgz#32a6ee76c3d7f52d46b2b1ae5d93fea8580a25e0"
+  integrity sha512-3hN7NaskYvMDLQY55gnW3NQ+mesEAepTqlg+VEbj7zzqEMBVNhzcGYYeqFo/TlYz6eQiFcp1HcsCZO+nGgS8zg==
+
+get-caller-file@^2.0.5:
+  version "2.0.5"
+  resolved "https://registry.yarnpkg.com/get-caller-file/-/get-caller-file-2.0.5.tgz#4f94412a82db32f36e3b0b9741f8a97feb031f7e"
+  integrity sha512-DyFP3BM/3YHTQOCUL/w0OZHR0lpKeGrxotcHWcqNEdnltqFwXVfhEBQ94eIo34AfQpo0rGki4cyIiftY06h2Fg==
+
 get-intrinsic@^1.2.5, get-intrinsic@^1.2.6, get-intrinsic@^1.3.0:
   version "1.3.0"
   resolved "https://registry.yarnpkg.com/get-intrinsic/-/get-intrinsic-1.3.0.tgz#743f0e3b6964a93a5491ed1bffaae054d7f98d01"
@@ -1863,6 +2911,11 @@ get-intrinsic@^1.2.5, get-intrinsic@^1.2.6, get-intrinsic@^1.3.0:
     hasown "^2.0.2"
     math-intrinsics "^1.1.0"
 
+get-package-type@^0.1.0:
+  version "0.1.0"
+  resolved "https://registry.yarnpkg.com/get-package-type/-/get-package-type-0.1.0.tgz#8de2d803cff44df3bc6c456e6668b36c3926e11a"
+  integrity sha512-pjzuKtY64GYfWizNAJ0fr9VqttZkNiK2iS430LtIHzjBEr6bX8Am2zm4sW4Ro5wjWW5cAlRL1qAMTcXbjNAO2Q==
+
 get-proto@^1.0.1:
   version "1.0.1"
   resolved "https://registry.yarnpkg.com/get-proto/-/get-proto-1.0.1.tgz#150b3f2743869ef3e851ec0c49d15b1d14d00ee1"
@@ -1871,6 +2924,11 @@ get-proto@^1.0.1:
     dunder-proto "^1.0.1"
     es-object-atoms "^1.0.0"
 
+get-stream@^6.0.0:
+  version "6.0.1"
+  resolved "https://registry.yarnpkg.com/get-stream/-/get-stream-6.0.1.tgz#a262d8eef67aced57c2852ad6167526a43cbf7b7"
+  integrity sha512-ts6Wi+2j3jQjqi70w5AlN8DFnkSwC+MqmxEzdEALB2qXZYV3X/b1CTfgPLGJNMeAWxdPfU8FO1ms3NUfaHCPYg==
+
 get-tsconfig@^4.10.0, get-tsconfig@^4.7.5:
   version "4.13.0"
   resolved "https://registry.yarnpkg.com/get-tsconfig/-/get-tsconfig-4.13.0.tgz#fcdd991e6d22ab9a600f00e91c318707a5d9a0d7"
@@ -1900,6 +2958,18 @@ glob-parent@^6.0.2:
   dependencies:
     is-glob "^4.0.3"
 
+glob@^10.3.10:
+  version "10.5.0"
+  resolved "https://registry.yarnpkg.com/glob/-/glob-10.5.0.tgz#8ec0355919cd3338c28428a23d4f24ecc5fe738c"
+  integrity sha512-DfXN8DfhJ7NH3Oe7cFmu3NCu1wKbkReJ8TorzSAFbSKrlNaQSKfIzqYqVY8zlbs2NLBbWpRiU52GX2PbaBVNkg==
+  dependencies:
+    foreground-child "^3.1.0"
+    jackspeak "^3.1.2"
+    minimatch "^9.0.4"
+    minipass "^7.1.2"
+    package-json-from-dist "^1.0.0"
+    path-scurry "^1.11.1"
+
 glob@^10.3.7:
   version "10.4.5"
   resolved "https://registry.yarnpkg.com/glob/-/glob-10.4.5.tgz#f4d9f0b90ffdbab09c9d77f5f29b4262517b0956"
@@ -1912,6 +2982,18 @@ glob@^10.3.7:
     package-json-from-dist "^1.0.0"
     path-scurry "^1.11.1"
 
+glob@^7.1.4:
+  version "7.2.3"
+  resolved "https://registry.yarnpkg.com/glob/-/glob-7.2.3.tgz#b8df0fb802bbfa8e89bd1d938b4e16578ed44f2b"
+  integrity sha512-nFR0zLpU2YCaRxwoCJvL6UvCH2JFyFVIvwTLsIf21AuHlMskA1hhTdk+LlYJtOlYt9v6dvszD2BGRqBL+iQK9Q==
+  dependencies:
+    fs.realpath "^1.0.0"
+    inflight "^1.0.4"
+    inherits "2"
+    minimatch "^3.1.1"
+    once "^1.3.0"
+    path-is-absolute "^1.0.0"
+
 globals@^14.0.0:
   version "14.0.0"
   resolved "https://registry.yarnpkg.com/globals/-/globals-14.0.0.tgz#898d7413c29babcf6bafe56fcadded858ada724e"
@@ -1952,6 +3034,11 @@ gopd@^1.2.0:
   resolved "https://registry.yarnpkg.com/gopd/-/gopd-1.2.0.tgz#89f56b8217bdbc8802bd299df6d7f1081d7e51a1"
   integrity sha512-ZUKRh6/kUFoAiTAtTYPZJ3hw9wNxx+BIBOijnlG9PnrJsCcSjs1wyyD6vJpaYtgnzDrKYRSqf3OO6Rfa93xsRg==
 
+graceful-fs@^4.2.11:
+  version "4.2.11"
+  resolved "https://registry.yarnpkg.com/graceful-fs/-/graceful-fs-4.2.11.tgz#4183e4e8bf08bb6e05bbb2f7d2e0c8f712ca40e3"
+  integrity sha512-RbJ5/jmFcNNCcDV5o9eTnBLJ/HszWV0P73bc+Ff4nS/rJj+YaS6IGyiOL0VoBYX+l1Wrl3k63h/KrH+nhJ0XvQ==
+
 graphemer@^1.4.0:
   version "1.4.0"
   resolved "https://registry.yarnpkg.com/graphemer/-/graphemer-1.4.0.tgz#fb2f1d55e0e3a1849aeffc90c4fa0dd53a0e66c6"
@@ -1965,6 +3052,18 @@ gtoken@^8.0.0:
     gaxios "^7.0.0"
     jws "^4.0.0"
 
+handlebars@^4.7.8:
+  version "4.7.8"
+  resolved "https://registry.yarnpkg.com/handlebars/-/handlebars-4.7.8.tgz#41c42c18b1be2365439188c77c6afae71c0cd9e9"
+  integrity sha512-vafaFqs8MZkRrSX7sFVUdo3ap/eNiLnb4IakshzvP56X5Nr1iGKAIqdX6tMlm6HcNRIkr6AxO5jFEoJzzpT8aQ==
+  dependencies:
+    minimist "^1.2.5"
+    neo-async "^2.6.2"
+    source-map "^0.6.1"
+    wordwrap "^1.0.0"
+  optionalDependencies:
+    uglify-js "^3.1.4"
+
 has-flag@^4.0.0:
   version "4.0.0"
   resolved "https://registry.yarnpkg.com/has-flag/-/has-flag-4.0.0.tgz#944771fd9c81c81265c4d6941860da06bb59479b"
@@ -1989,6 +3088,11 @@ hasown@^2.0.2:
   dependencies:
     function-bind "^1.1.2"
 
+html-escaper@^2.0.0:
+  version "2.0.2"
+  resolved "https://registry.yarnpkg.com/html-escaper/-/html-escaper-2.0.2.tgz#dfd60027da36a36dfcbe236262c00a5822681453"
+  integrity sha512-H2iMtd0I4Mt5eYiapRdIDjp+XzelXQ0tFE4JS7YFwFevXXMmOp9myNrUvCg0D6ws8iqkRPBfKHgbwig1SmlLfg==
+
 http-errors@2.0.0, http-errors@^2.0.0:
   version "2.0.0"
   resolved "https://registry.yarnpkg.com/http-errors/-/http-errors-2.0.0.tgz#b7774a1486ef73cf7667ac9ae0858c012c57b9d3"
@@ -2008,6 +3112,11 @@ https-proxy-agent@^7.0.1:
     agent-base "^7.1.2"
     debug "4"
 
+human-signals@^2.1.0:
+  version "2.1.0"
+  resolved "https://registry.yarnpkg.com/human-signals/-/human-signals-2.1.0.tgz#dc91fcba42e4d06e4abaed33b3e7a3c02f514ea0"
+  integrity sha512-B4FFZ6q/T2jhhksgkbEW3HBvWIfDW85snkQgawt07S7J5QXTk6BkNV+0yAeZrM5QpMAdYlocGoljn0sJ/WQkFw==
+
 iconv-lite@0.7.0, iconv-lite@^0.7.0:
   version "0.7.0"
   resolved "https://registry.yarnpkg.com/iconv-lite/-/iconv-lite-0.7.0.tgz#c50cd80e6746ca8115eb98743afa81aa0e147a3e"
@@ -2052,12 +3161,28 @@ import-fresh@^3.2.1:
     parent-module "^1.0.0"
     resolve-from "^4.0.0"
 
+import-local@^3.2.0:
+  version "3.2.0"
+  resolved "https://registry.yarnpkg.com/import-local/-/import-local-3.2.0.tgz#c3d5c745798c02a6f8b897726aba5100186ee260"
+  integrity sha512-2SPlun1JUPWoM6t3F0dw0FkCF/jWY8kttcY4f599GLTSjh2OCuuhdTkJQsEcZzBqbXZGKMK2OqW1oZsjtf/gQA==
+  dependencies:
+    pkg-dir "^4.2.0"
+    resolve-cwd "^3.0.0"
+
 imurmurhash@^0.1.4:
   version "0.1.4"
   resolved "https://registry.yarnpkg.com/imurmurhash/-/imurmurhash-0.1.4.tgz#9218b9b2b928a238b13dc4fb6b6d576f231453ea"
   integrity sha512-JmXMZ6wuvDmLiHEml9ykzqO6lwFbof0GG4IkcGaENdCRDDmMVnny7s5HsIgHCbaq0w2MyPhDqkhTUgS2LU2PHA==
 
-inherits@2.0.4, inherits@^2.0.3, inherits@^2.0.4:
+inflight@^1.0.4:
+  version "1.0.6"
+  resolved "https://registry.yarnpkg.com/inflight/-/inflight-1.0.6.tgz#49bd6331d7d02d0c09bc910a1075ba8165b56df9"
+  integrity sha512-k92I/b08q4wvFscXCLvqfsHCrjrF7yiXsQuIVvVE7N82W3+aqpzuUdBbfhWcy/FZR3/4IgflMgKLOsvPDrGCJA==
+  dependencies:
+    once "^1.3.0"
+    wrappy "1"
+
+inherits@2, inherits@2.0.4, inherits@^2.0.3, inherits@^2.0.4:
   version "2.0.4"
   resolved "https://registry.yarnpkg.com/inherits/-/inherits-2.0.4.tgz#0fa2c64f932917c3433a0ded55363aae37416b7c"
   integrity sha512-k/vGaX4/Yla3WzyMCvTQOXYeIHvqOKtnqBduzTHpzpQZzAskKMhZ2K+EnBiSM9zGSoIFeMpXKxa4dYeZIQqewQ==
@@ -2067,6 +3192,11 @@ ipaddr.js@1.9.1:
   resolved "https://registry.yarnpkg.com/ipaddr.js/-/ipaddr.js-1.9.1.tgz#bff38543eeb8984825079ff3a2a8e6cbd46781b3"
   integrity sha512-0KI/607xoxSToH7GjN1FfSbLoU0+btTicjsQSWQlh/hZykN8KpmMf7uYwPW3R+akZ6R/w18ZlXSHBYXiYUPO3g==
 
+is-arrayish@^0.2.1:
+  version "0.2.1"
+  resolved "https://registry.yarnpkg.com/is-arrayish/-/is-arrayish-0.2.1.tgz#77c99840527aa8ecb1a8ba697b80645a7a926a9d"
+  integrity sha512-zz06S8t0ozoDXMG+ube26zeCTNXcKIPJZJi8hBrF4idCLms4CG9QtK7qBl1boi5ODzFpjswb5JPmHCbMpjaYzg==
+
 is-binary-path@~2.1.0:
   version "2.1.0"
   resolved "https://registry.yarnpkg.com/is-binary-path/-/is-binary-path-2.1.0.tgz#ea1f7f3b80f064236e83470f86c09c254fb45b09"
@@ -2084,6 +3214,11 @@ is-fullwidth-code-point@^3.0.0:
   resolved "https://registry.yarnpkg.com/is-fullwidth-code-point/-/is-fullwidth-code-point-3.0.0.tgz#f116f8064fe90b3f7844a38997c0b75051269f1d"
   integrity sha512-zymm5+u+sCsSWyD9qNaejV3DFvhCKclKdizYaJUuHA83RLjb7nSuGnddCHGv0hk+KY7BMAlsWeK4Ueg6EV6XQg==
 
+is-generator-fn@^2.1.0:
+  version "2.1.0"
+  resolved "https://registry.yarnpkg.com/is-generator-fn/-/is-generator-fn-2.1.0.tgz#7d140adc389aaf3011a8f2a2a4cfa6faadffb118"
+  integrity sha512-cTIB4yPYL/Grw0EaSzASzg6bBy9gqCofvWN8okThAYIxKJZC+udlRAmGbM0XLeniEJSs8uEgHPGuHSe1XsOLSQ==
+
 is-glob@^4.0.0, is-glob@^4.0.1, is-glob@^4.0.3, is-glob@~4.0.1:
   version "4.0.3"
   resolved "https://registry.yarnpkg.com/is-glob/-/is-glob-4.0.3.tgz#64f61e42cbbb2eec2071a9dac0b28ba1e65d5084"
@@ -2106,6 +3241,11 @@ is-promise@^4.0.0:
   resolved "https://registry.yarnpkg.com/is-promise/-/is-promise-4.0.0.tgz#42ff9f84206c1991d26debf520dd5c01042dd2f3"
   integrity sha512-hvpoI6korhJMnej285dSg6nu1+e6uxs7zG3BYAm5byqDsgJNWwxzM6z6iZiAgQR4TJ30JmBTOwqZUw3WlyH3AQ==
 
+is-stream@^2.0.0:
+  version "2.0.1"
+  resolved "https://registry.yarnpkg.com/is-stream/-/is-stream-2.0.1.tgz#fac1e3d53b97ad5a9d0ae9cef2389f5810a5c077"
+  integrity sha512-hFoiJiTl63nn+kstHGBtewWSKnQLpyb155KHheA1l39uvtO9nWIop1p3udqPcUd/xbF1VLMO4n7OI6p7RbngDg==
+
 is-unicode-supported@^0.1.0:
   version "0.1.0"
   resolved "https://registry.yarnpkg.com/is-unicode-supported/-/is-unicode-supported-0.1.0.tgz#3f26c76a809593b52bfa2ecb5710ed2779b522a7"
@@ -2116,6 +3256,48 @@ isexe@^2.0.0:
   resolved "https://registry.yarnpkg.com/isexe/-/isexe-2.0.0.tgz#e8fbf374dc556ff8947a10dcb0572d633f2cfa10"
   integrity sha512-RHxMLp9lnKHGHRng9QFhRCMbYAcVpn69smSGcq3f36xjgVVWThj4qqLbTLlq7Ssj8B+fIQ1EuCEGI2lKsyQeIw==
 
+istanbul-lib-coverage@^3.0.0, istanbul-lib-coverage@^3.2.0:
+  version "3.2.2"
+  resolved "https://registry.yarnpkg.com/istanbul-lib-coverage/-/istanbul-lib-coverage-3.2.2.tgz#2d166c4b0644d43a39f04bf6c2edd1e585f31756"
+  integrity sha512-O8dpsF+r0WV/8MNRKfnmrtCWhuKjxrq2w+jpzBL5UZKTi2LeVWnWOmWRxFlesJONmc+wLAGvKQZEOanko0LFTg==
+
+istanbul-lib-instrument@^6.0.0, istanbul-lib-instrument@^6.0.2:
+  version "6.0.3"
+  resolved "https://registry.yarnpkg.com/istanbul-lib-instrument/-/istanbul-lib-instrument-6.0.3.tgz#fa15401df6c15874bcb2105f773325d78c666765"
+  integrity sha512-Vtgk7L/R2JHyyGW07spoFlB8/lpjiOLTjMdms6AFMraYt3BaJauod/NGrfnVG/y4Ix1JEuMRPDPEj2ua+zz1/Q==
+  dependencies:
+    "@babel/core" "^7.23.9"
+    "@babel/parser" "^7.23.9"
+    "@istanbuljs/schema" "^0.1.3"
+    istanbul-lib-coverage "^3.2.0"
+    semver "^7.5.4"
+
+istanbul-lib-report@^3.0.0:
+  version "3.0.1"
+  resolved "https://registry.yarnpkg.com/istanbul-lib-report/-/istanbul-lib-report-3.0.1.tgz#908305bac9a5bd175ac6a74489eafd0fc2445a7d"
+  integrity sha512-GCfE1mtsHGOELCU8e/Z7YWzpmybrx/+dSTfLrvY8qRmaY6zXTKWn6WQIjaAFw069icm6GVMNkgu0NzI4iPZUNw==
+  dependencies:
+    istanbul-lib-coverage "^3.0.0"
+    make-dir "^4.0.0"
+    supports-color "^7.1.0"
+
+istanbul-lib-source-maps@^5.0.0:
+  version "5.0.6"
+  resolved "https://registry.yarnpkg.com/istanbul-lib-source-maps/-/istanbul-lib-source-maps-5.0.6.tgz#acaef948df7747c8eb5fbf1265cb980f6353a441"
+  integrity sha512-yg2d+Em4KizZC5niWhQaIomgf5WlL4vOOjZ5xGCmF8SnPE/mDWWXgvRExdcpCgh9lLRRa1/fSYp2ymmbJ1pI+A==
+  dependencies:
+    "@jridgewell/trace-mapping" "^0.3.23"
+    debug "^4.1.1"
+    istanbul-lib-coverage "^3.0.0"
+
+istanbul-reports@^3.1.3:
+  version "3.2.0"
+  resolved "https://registry.yarnpkg.com/istanbul-reports/-/istanbul-reports-3.2.0.tgz#cb4535162b5784aa623cee21a7252cf2c807ac93"
+  integrity sha512-HGYWWS/ehqTV3xN10i23tkPkpH46MLCIMFNCaaKNavAXTF1RkqxawEPtnjnGZ6XKSInBKkiOA5BKS+aZiY3AvA==
+  dependencies:
+    html-escaper "^2.0.0"
+    istanbul-lib-report "^3.0.0"
+
 jackspeak@^3.1.2:
   version "3.4.3"
   resolved "https://registry.yarnpkg.com/jackspeak/-/jackspeak-3.4.3.tgz#8833a9d89ab4acde6188942bd1c53b6390ed5a8a"
@@ -2125,6 +3307,362 @@ jackspeak@^3.1.2:
   optionalDependencies:
     "@pkgjs/parseargs" "^0.11.0"
 
+jest-changed-files@30.2.0:
+  version "30.2.0"
+  resolved "https://registry.yarnpkg.com/jest-changed-files/-/jest-changed-files-30.2.0.tgz#602266e478ed554e1e1469944faa7efd37cee61c"
+  integrity sha512-L8lR1ChrRnSdfeOvTrwZMlnWV8G/LLjQ0nG9MBclwWZidA2N5FviRki0Bvh20WRMOX31/JYvzdqTJrk5oBdydQ==
+  dependencies:
+    execa "^5.1.1"
+    jest-util "30.2.0"
+    p-limit "^3.1.0"
+
+jest-circus@30.2.0:
+  version "30.2.0"
+  resolved "https://registry.yarnpkg.com/jest-circus/-/jest-circus-30.2.0.tgz#98b8198b958748a2f322354311023d1d02e7603f"
+  integrity sha512-Fh0096NC3ZkFx05EP2OXCxJAREVxj1BcW/i6EWqqymcgYKWjyyDpral3fMxVcHXg6oZM7iULer9wGRFvfpl+Tg==
+  dependencies:
+    "@jest/environment" "30.2.0"
+    "@jest/expect" "30.2.0"
+    "@jest/test-result" "30.2.0"
+    "@jest/types" "30.2.0"
+    "@types/node" "*"
+    chalk "^4.1.2"
+    co "^4.6.0"
+    dedent "^1.6.0"
+    is-generator-fn "^2.1.0"
+    jest-each "30.2.0"
+    jest-matcher-utils "30.2.0"
+    jest-message-util "30.2.0"
+    jest-runtime "30.2.0"
+    jest-snapshot "30.2.0"
+    jest-util "30.2.0"
+    p-limit "^3.1.0"
+    pretty-format "30.2.0"
+    pure-rand "^7.0.0"
+    slash "^3.0.0"
+    stack-utils "^2.0.6"
+
+jest-cli@30.2.0:
+  version "30.2.0"
+  resolved "https://registry.yarnpkg.com/jest-cli/-/jest-cli-30.2.0.tgz#1780f8e9d66bf84a10b369aea60aeda7697dcc67"
+  integrity sha512-Os9ukIvADX/A9sLt6Zse3+nmHtHaE6hqOsjQtNiugFTbKRHYIYtZXNGNK9NChseXy7djFPjndX1tL0sCTlfpAA==
+  dependencies:
+    "@jest/core" "30.2.0"
+    "@jest/test-result" "30.2.0"
+    "@jest/types" "30.2.0"
+    chalk "^4.1.2"
+    exit-x "^0.2.2"
+    import-local "^3.2.0"
+    jest-config "30.2.0"
+    jest-util "30.2.0"
+    jest-validate "30.2.0"
+    yargs "^17.7.2"
+
+jest-config@30.2.0:
+  version "30.2.0"
+  resolved "https://registry.yarnpkg.com/jest-config/-/jest-config-30.2.0.tgz#29df8c50e2ad801cc59c406b50176c18c362a90b"
+  integrity sha512-g4WkyzFQVWHtu6uqGmQR4CQxz/CH3yDSlhzXMWzNjDx843gYjReZnMRanjRCq5XZFuQrGDxgUaiYWE8BRfVckA==
+  dependencies:
+    "@babel/core" "^7.27.4"
+    "@jest/get-type" "30.1.0"
+    "@jest/pattern" "30.0.1"
+    "@jest/test-sequencer" "30.2.0"
+    "@jest/types" "30.2.0"
+    babel-jest "30.2.0"
+    chalk "^4.1.2"
+    ci-info "^4.2.0"
+    deepmerge "^4.3.1"
+    glob "^10.3.10"
+    graceful-fs "^4.2.11"
+    jest-circus "30.2.0"
+    jest-docblock "30.2.0"
+    jest-environment-node "30.2.0"
+    jest-regex-util "30.0.1"
+    jest-resolve "30.2.0"
+    jest-runner "30.2.0"
+    jest-util "30.2.0"
+    jest-validate "30.2.0"
+    micromatch "^4.0.8"
+    parse-json "^5.2.0"
+    pretty-format "30.2.0"
+    slash "^3.0.0"
+    strip-json-comments "^3.1.1"
+
+jest-diff@30.2.0:
+  version "30.2.0"
+  resolved "https://registry.yarnpkg.com/jest-diff/-/jest-diff-30.2.0.tgz#e3ec3a6ea5c5747f605c9e874f83d756cba36825"
+  integrity sha512-dQHFo3Pt4/NLlG5z4PxZ/3yZTZ1C7s9hveiOj+GCN+uT109NC2QgsoVZsVOAvbJ3RgKkvyLGXZV9+piDpWbm6A==
+  dependencies:
+    "@jest/diff-sequences" "30.0.1"
+    "@jest/get-type" "30.1.0"
+    chalk "^4.1.2"
+    pretty-format "30.2.0"
+
+jest-docblock@30.2.0:
+  version "30.2.0"
+  resolved "https://registry.yarnpkg.com/jest-docblock/-/jest-docblock-30.2.0.tgz#42cd98d69f887e531c7352309542b1ce4ee10256"
+  integrity sha512-tR/FFgZKS1CXluOQzZvNH3+0z9jXr3ldGSD8bhyuxvlVUwbeLOGynkunvlTMxchC5urrKndYiwCFC0DLVjpOCA==
+  dependencies:
+    detect-newline "^3.1.0"
+
+jest-each@30.2.0:
+  version "30.2.0"
+  resolved "https://registry.yarnpkg.com/jest-each/-/jest-each-30.2.0.tgz#39e623ae71641c2ac3ee69b3ba3d258fce8e768d"
+  integrity sha512-lpWlJlM7bCUf1mfmuqTA8+j2lNURW9eNafOy99knBM01i5CQeY5UH1vZjgT9071nDJac1M4XsbyI44oNOdhlDQ==
+  dependencies:
+    "@jest/get-type" "30.1.0"
+    "@jest/types" "30.2.0"
+    chalk "^4.1.2"
+    jest-util "30.2.0"
+    pretty-format "30.2.0"
+
+jest-environment-node@30.2.0:
+  version "30.2.0"
+  resolved "https://registry.yarnpkg.com/jest-environment-node/-/jest-environment-node-30.2.0.tgz#3def7980ebd2fd86e74efd4d2e681f55ab38da0f"
+  integrity sha512-ElU8v92QJ9UrYsKrxDIKCxu6PfNj4Hdcktcn0JX12zqNdqWHB0N+hwOnnBBXvjLd2vApZtuLUGs1QSY+MsXoNA==
+  dependencies:
+    "@jest/environment" "30.2.0"
+    "@jest/fake-timers" "30.2.0"
+    "@jest/types" "30.2.0"
+    "@types/node" "*"
+    jest-mock "30.2.0"
+    jest-util "30.2.0"
+    jest-validate "30.2.0"
+
+jest-haste-map@30.2.0:
+  version "30.2.0"
+  resolved "https://registry.yarnpkg.com/jest-haste-map/-/jest-haste-map-30.2.0.tgz#808e3889f288603ac70ff0ac047598345a66022e"
+  integrity sha512-sQA/jCb9kNt+neM0anSj6eZhLZUIhQgwDt7cPGjumgLM4rXsfb9kpnlacmvZz3Q5tb80nS+oG/if+NBKrHC+Xw==
+  dependencies:
+    "@jest/types" "30.2.0"
+    "@types/node" "*"
+    anymatch "^3.1.3"
+    fb-watchman "^2.0.2"
+    graceful-fs "^4.2.11"
+    jest-regex-util "30.0.1"
+    jest-util "30.2.0"
+    jest-worker "30.2.0"
+    micromatch "^4.0.8"
+    walker "^1.0.8"
+  optionalDependencies:
+    fsevents "^2.3.3"
+
+jest-leak-detector@30.2.0:
+  version "30.2.0"
+  resolved "https://registry.yarnpkg.com/jest-leak-detector/-/jest-leak-detector-30.2.0.tgz#292fdca7b7c9cf594e1e570ace140b01d8beb736"
+  integrity sha512-M6jKAjyzjHG0SrQgwhgZGy9hFazcudwCNovY/9HPIicmNSBuockPSedAP9vlPK6ONFJ1zfyH/M2/YYJxOz5cdQ==
+  dependencies:
+    "@jest/get-type" "30.1.0"
+    pretty-format "30.2.0"
+
+jest-matcher-utils@30.2.0:
+  version "30.2.0"
+  resolved "https://registry.yarnpkg.com/jest-matcher-utils/-/jest-matcher-utils-30.2.0.tgz#69a0d4c271066559ec8b0d8174829adc3f23a783"
+  integrity sha512-dQ94Nq4dbzmUWkQ0ANAWS9tBRfqCrn0bV9AMYdOi/MHW726xn7eQmMeRTpX2ViC00bpNaWXq+7o4lIQ3AX13Hg==
+  dependencies:
+    "@jest/get-type" "30.1.0"
+    chalk "^4.1.2"
+    jest-diff "30.2.0"
+    pretty-format "30.2.0"
+
+jest-message-util@30.2.0:
+  version "30.2.0"
+  resolved "https://registry.yarnpkg.com/jest-message-util/-/jest-message-util-30.2.0.tgz#fc97bf90d11f118b31e6131e2b67fc4f39f92152"
+  integrity sha512-y4DKFLZ2y6DxTWD4cDe07RglV88ZiNEdlRfGtqahfbIjfsw1nMCPx49Uev4IA/hWn3sDKyAnSPwoYSsAEdcimw==
+  dependencies:
+    "@babel/code-frame" "^7.27.1"
+    "@jest/types" "30.2.0"
+    "@types/stack-utils" "^2.0.3"
+    chalk "^4.1.2"
+    graceful-fs "^4.2.11"
+    micromatch "^4.0.8"
+    pretty-format "30.2.0"
+    slash "^3.0.0"
+    stack-utils "^2.0.6"
+
+jest-mock@30.2.0:
+  version "30.2.0"
+  resolved "https://registry.yarnpkg.com/jest-mock/-/jest-mock-30.2.0.tgz#69f991614eeb4060189459d3584f710845bff45e"
+  integrity sha512-JNNNl2rj4b5ICpmAcq+WbLH83XswjPbjH4T7yvGzfAGCPh1rw+xVNbtk+FnRslvt9lkCcdn9i1oAoKUuFsOxRw==
+  dependencies:
+    "@jest/types" "30.2.0"
+    "@types/node" "*"
+    jest-util "30.2.0"
+
+jest-pnp-resolver@^1.2.3:
+  version "1.2.3"
+  resolved "https://registry.yarnpkg.com/jest-pnp-resolver/-/jest-pnp-resolver-1.2.3.tgz#930b1546164d4ad5937d5540e711d4d38d4cad2e"
+  integrity sha512-+3NpwQEnRoIBtx4fyhblQDPgJI0H1IEIkX7ShLUjPGA7TtUTvI1oiKi3SR4oBR0hQhQR80l4WAe5RrXBwWMA8w==
+
+jest-regex-util@30.0.1:
+  version "30.0.1"
+  resolved "https://registry.yarnpkg.com/jest-regex-util/-/jest-regex-util-30.0.1.tgz#f17c1de3958b67dfe485354f5a10093298f2a49b"
+  integrity sha512-jHEQgBXAgc+Gh4g0p3bCevgRCVRkB4VB70zhoAE48gxeSr1hfUOsM/C2WoJgVL7Eyg//hudYENbm3Ne+/dRVVA==
+
+jest-resolve-dependencies@30.2.0:
+  version "30.2.0"
+  resolved "https://registry.yarnpkg.com/jest-resolve-dependencies/-/jest-resolve-dependencies-30.2.0.tgz#3370e2c0b49cc560f6a7e8ec3a59dd99525e1a55"
+  integrity sha512-xTOIGug/0RmIe3mmCqCT95yO0vj6JURrn1TKWlNbhiAefJRWINNPgwVkrVgt/YaerPzY3iItufd80v3lOrFJ2w==
+  dependencies:
+    jest-regex-util "30.0.1"
+    jest-snapshot "30.2.0"
+
+jest-resolve@30.2.0:
+  version "30.2.0"
+  resolved "https://registry.yarnpkg.com/jest-resolve/-/jest-resolve-30.2.0.tgz#2e2009cbd61e8f1f003355d5ec87225412cebcd7"
+  integrity sha512-TCrHSxPlx3tBY3hWNtRQKbtgLhsXa1WmbJEqBlTBrGafd5fiQFByy2GNCEoGR+Tns8d15GaL9cxEzKOO3GEb2A==
+  dependencies:
+    chalk "^4.1.2"
+    graceful-fs "^4.2.11"
+    jest-haste-map "30.2.0"
+    jest-pnp-resolver "^1.2.3"
+    jest-util "30.2.0"
+    jest-validate "30.2.0"
+    slash "^3.0.0"
+    unrs-resolver "^1.7.11"
+
+jest-runner@30.2.0:
+  version "30.2.0"
+  resolved "https://registry.yarnpkg.com/jest-runner/-/jest-runner-30.2.0.tgz#c62b4c3130afa661789705e13a07bdbcec26a114"
+  integrity sha512-PqvZ2B2XEyPEbclp+gV6KO/F1FIFSbIwewRgmROCMBo/aZ6J1w8Qypoj2pEOcg3G2HzLlaP6VUtvwCI8dM3oqQ==
+  dependencies:
+    "@jest/console" "30.2.0"
+    "@jest/environment" "30.2.0"
+    "@jest/test-result" "30.2.0"
+    "@jest/transform" "30.2.0"
+    "@jest/types" "30.2.0"
+    "@types/node" "*"
+    chalk "^4.1.2"
+    emittery "^0.13.1"
+    exit-x "^0.2.2"
+    graceful-fs "^4.2.11"
+    jest-docblock "30.2.0"
+    jest-environment-node "30.2.0"
+    jest-haste-map "30.2.0"
+    jest-leak-detector "30.2.0"
+    jest-message-util "30.2.0"
+    jest-resolve "30.2.0"
+    jest-runtime "30.2.0"
+    jest-util "30.2.0"
+    jest-watcher "30.2.0"
+    jest-worker "30.2.0"
+    p-limit "^3.1.0"
+    source-map-support "0.5.13"
+
+jest-runtime@30.2.0:
+  version "30.2.0"
+  resolved "https://registry.yarnpkg.com/jest-runtime/-/jest-runtime-30.2.0.tgz#395ea792cde048db1b0cd1a92dc9cb9f1921bf8a"
+  integrity sha512-p1+GVX/PJqTucvsmERPMgCPvQJpFt4hFbM+VN3n8TMo47decMUcJbt+rgzwrEme0MQUA/R+1de2axftTHkKckg==
+  dependencies:
+    "@jest/environment" "30.2.0"
+    "@jest/fake-timers" "30.2.0"
+    "@jest/globals" "30.2.0"
+    "@jest/source-map" "30.0.1"
+    "@jest/test-result" "30.2.0"
+    "@jest/transform" "30.2.0"
+    "@jest/types" "30.2.0"
+    "@types/node" "*"
+    chalk "^4.1.2"
+    cjs-module-lexer "^2.1.0"
+    collect-v8-coverage "^1.0.2"
+    glob "^10.3.10"
+    graceful-fs "^4.2.11"
+    jest-haste-map "30.2.0"
+    jest-message-util "30.2.0"
+    jest-mock "30.2.0"
+    jest-regex-util "30.0.1"
+    jest-resolve "30.2.0"
+    jest-snapshot "30.2.0"
+    jest-util "30.2.0"
+    slash "^3.0.0"
+    strip-bom "^4.0.0"
+
+jest-snapshot@30.2.0:
+  version "30.2.0"
+  resolved "https://registry.yarnpkg.com/jest-snapshot/-/jest-snapshot-30.2.0.tgz#266fbbb4b95fc4665ce6f32f1f38eeb39f4e26d0"
+  integrity sha512-5WEtTy2jXPFypadKNpbNkZ72puZCa6UjSr/7djeecHWOu7iYhSXSnHScT8wBz3Rn8Ena5d5RYRcsyKIeqG1IyA==
+  dependencies:
+    "@babel/core" "^7.27.4"
+    "@babel/generator" "^7.27.5"
+    "@babel/plugin-syntax-jsx" "^7.27.1"
+    "@babel/plugin-syntax-typescript" "^7.27.1"
+    "@babel/types" "^7.27.3"
+    "@jest/expect-utils" "30.2.0"
+    "@jest/get-type" "30.1.0"
+    "@jest/snapshot-utils" "30.2.0"
+    "@jest/transform" "30.2.0"
+    "@jest/types" "30.2.0"
+    babel-preset-current-node-syntax "^1.2.0"
+    chalk "^4.1.2"
+    expect "30.2.0"
+    graceful-fs "^4.2.11"
+    jest-diff "30.2.0"
+    jest-matcher-utils "30.2.0"
+    jest-message-util "30.2.0"
+    jest-util "30.2.0"
+    pretty-format "30.2.0"
+    semver "^7.7.2"
+    synckit "^0.11.8"
+
+jest-util@30.2.0:
+  version "30.2.0"
+  resolved "https://registry.yarnpkg.com/jest-util/-/jest-util-30.2.0.tgz#5142adbcad6f4e53c2776c067a4db3c14f913705"
+  integrity sha512-QKNsM0o3Xe6ISQU869e+DhG+4CK/48aHYdJZGlFQVTjnbvgpcKyxpzk29fGiO7i/J8VENZ+d2iGnSsvmuHywlA==
+  dependencies:
+    "@jest/types" "30.2.0"
+    "@types/node" "*"
+    chalk "^4.1.2"
+    ci-info "^4.2.0"
+    graceful-fs "^4.2.11"
+    picomatch "^4.0.2"
+
+jest-validate@30.2.0:
+  version "30.2.0"
+  resolved "https://registry.yarnpkg.com/jest-validate/-/jest-validate-30.2.0.tgz#273eaaed4c0963b934b5b31e96289edda6e0a2ef"
+  integrity sha512-FBGWi7dP2hpdi8nBoWxSsLvBFewKAg0+uSQwBaof4Y4DPgBabXgpSYC5/lR7VmnIlSpASmCi/ntRWPbv7089Pw==
+  dependencies:
+    "@jest/get-type" "30.1.0"
+    "@jest/types" "30.2.0"
+    camelcase "^6.3.0"
+    chalk "^4.1.2"
+    leven "^3.1.0"
+    pretty-format "30.2.0"
+
+jest-watcher@30.2.0:
+  version "30.2.0"
+  resolved "https://registry.yarnpkg.com/jest-watcher/-/jest-watcher-30.2.0.tgz#f9c055de48e18c979e7756a3917e596e2d69b07b"
+  integrity sha512-PYxa28dxJ9g777pGm/7PrbnMeA0Jr7osHP9bS7eJy9DuAjMgdGtxgf0uKMyoIsTWAkIbUW5hSDdJ3urmgXBqxg==
+  dependencies:
+    "@jest/test-result" "30.2.0"
+    "@jest/types" "30.2.0"
+    "@types/node" "*"
+    ansi-escapes "^4.3.2"
+    chalk "^4.1.2"
+    emittery "^0.13.1"
+    jest-util "30.2.0"
+    string-length "^4.0.2"
+
+jest-worker@30.2.0:
+  version "30.2.0"
+  resolved "https://registry.yarnpkg.com/jest-worker/-/jest-worker-30.2.0.tgz#fd5c2a36ff6058ec8f74366ec89538cc99539d26"
+  integrity sha512-0Q4Uk8WF7BUwqXHuAjc23vmopWJw5WH7w2tqBoUOZpOjW/ZnR44GXXd1r82RvnmI2GZge3ivrYXk/BE2+VtW2g==
+  dependencies:
+    "@types/node" "*"
+    "@ungap/structured-clone" "^1.3.0"
+    jest-util "30.2.0"
+    merge-stream "^2.0.0"
+    supports-color "^8.1.1"
+
+jest@^30.2.0:
+  version "30.2.0"
+  resolved "https://registry.yarnpkg.com/jest/-/jest-30.2.0.tgz#9f0a71e734af968f26952b5ae4b724af82681630"
+  integrity sha512-F26gjC0yWN8uAA5m5Ss8ZQf5nDHWGlN/xWZIh8S5SRbsEKBovwZhxGd6LJlbZYxBgCYOtreSUyb8hpXyGC5O4A==
+  dependencies:
+    "@jest/core" "30.2.0"
+    "@jest/types" "30.2.0"
+    import-local "^3.2.0"
+    jest-cli "30.2.0"
+
 jimp@^1.6.0:
   version "1.6.0"
   resolved "https://registry.yarnpkg.com/jimp/-/jimp-1.6.0.tgz#7c7e5133c8dc06706e1ed35e771c685af393bfd2"
@@ -2168,6 +3706,19 @@ jpeg-js@^0.4.4:
   resolved "https://registry.yarnpkg.com/jpeg-js/-/jpeg-js-0.4.4.tgz#a9f1c6f1f9f0fa80cdb3484ed9635054d28936aa"
   integrity sha512-WZzeDOEtTOBK4Mdsar0IqEU5sMr3vSV2RqkAIzUEV2BHnUfKGyswWFPFwK5EeDo93K3FohSHbLAjj0s1Wzd+dg==
 
+js-tokens@^4.0.0:
+  version "4.0.0"
+  resolved "https://registry.yarnpkg.com/js-tokens/-/js-tokens-4.0.0.tgz#19203fb59991df98e3a287050d4647cdeaf32499"
+  integrity sha512-RdJUflcE3cUzKiMqQgsCu06FPu9UdIJO0beYbPhHN4k6apgJtifcoCtT9bcxOpYBtpD2kCM6Sbzg4CausW/PKQ==
+
+js-yaml@^3.13.1:
+  version "3.14.2"
+  resolved "https://registry.yarnpkg.com/js-yaml/-/js-yaml-3.14.2.tgz#77485ce1dd7f33c061fd1b16ecea23b55fcb04b0"
+  integrity sha512-PMSmkqxr106Xa156c2M265Z+FTrPl+oxd/rgOQy2tijQeK5TxQ43psO1ZCwhVOSdnn+RzkzlRz/eY4BgJBYVpg==
+  dependencies:
+    argparse "^1.0.7"
+    esprima "^4.0.0"
+
 js-yaml@^4.1.0:
   version "4.1.0"
   resolved "https://registry.yarnpkg.com/js-yaml/-/js-yaml-4.1.0.tgz#c1fb65f8f5017901cdd2c951864ba18458a10602"
@@ -2175,6 +3726,11 @@ js-yaml@^4.1.0:
   dependencies:
     argparse "^2.0.1"
 
+jsesc@^3.0.2:
+  version "3.1.0"
+  resolved "https://registry.yarnpkg.com/jsesc/-/jsesc-3.1.0.tgz#74d335a234f67ed19907fdadfac7ccf9d409825d"
+  integrity sha512-/sM3dO2FOzXjKQhJuo0Q173wf2KOo8t4I8vHy6lF9poUp7bKT0/NHE8fPX23PwfhnykfqnC2xRxOnVw5XuGIaA==
+
 json-bigint@^1.0.0:
   version "1.0.0"
   resolved "https://registry.yarnpkg.com/json-bigint/-/json-bigint-1.0.0.tgz#ae547823ac0cad8398667f8cd9ef4730f5b01ff1"
@@ -2187,6 +3743,11 @@ json-buffer@3.0.1:
   resolved "https://registry.yarnpkg.com/json-buffer/-/json-buffer-3.0.1.tgz#9338802a30d3b6605fbe0613e094008ca8c05a13"
   integrity sha512-4bV5BfR2mqfQTJm+V5tPPdf+ZpuhiIvTuAB5g8kcrXOZpTT/QwwVRWBywX1ozr6lEuPdbHxwaJlm9G6mI2sfSQ==
 
+json-parse-even-better-errors@^2.3.0:
+  version "2.3.1"
+  resolved "https://registry.yarnpkg.com/json-parse-even-better-errors/-/json-parse-even-better-errors-2.3.1.tgz#7c47805a94319928e05777405dc12e1f7a4ee02d"
+  integrity sha512-xyFwyhro/JEof6Ghe2iz2NcXoj2sloNsWr/XsERDK/oiPCfaNhl5ONfp+jQdAZRQQ0IJWNzH9zIZF7li91kh2w==
+
 json-schema-to-ts@^3.1.1:
   version "3.1.1"
   resolved "https://registry.yarnpkg.com/json-schema-to-ts/-/json-schema-to-ts-3.1.1.tgz#81f3acaf5a34736492f6f5f51870ef9ece1ca853"
@@ -2205,7 +3766,7 @@ json-stable-stringify-without-jsonify@^1.0.1:
   resolved "https://registry.yarnpkg.com/json-stable-stringify-without-jsonify/-/json-stable-stringify-without-jsonify-1.0.1.tgz#9db7b59496ad3f3cfef30a75142d2d930ad72651"
   integrity sha512-Bdboy+l7tA3OGW6FjyFHWkP5LuByj1Tk33Ljyq0axyzdk9//JSi2u3fP1QSmd1KNwq6VOKYGlAu87CisVir6Pw==
 
-json5@^2.2.2:
+json5@^2.2.2, json5@^2.2.3:
   version "2.2.3"
   resolved "https://registry.yarnpkg.com/json5/-/json5-2.2.3.tgz#78cd6f1a19bdc12b73db5ad0c61efd66c1e29283"
   integrity sha512-XmOWe7eyHYH14cLdVPoyg+GOH3rYX++KpzrylJwSW98t3Nk+U8XOl8FWKOgwtzdb8lXGf6zYwDUzeHMWfxasyg==
@@ -2234,6 +3795,11 @@ keyv@^4.5.4:
   dependencies:
     json-buffer "3.0.1"
 
+leven@^3.1.0:
+  version "3.1.0"
+  resolved "https://registry.yarnpkg.com/leven/-/leven-3.1.0.tgz#77891de834064cccba82ae7842bb6b14a13ed7f2"
+  integrity sha512-qsda+H8jTaUaN/x5vzW2rzc+8Rw4TAQ/4KjB46IwK5VH+IlVeeeje/EoZRpiXvIqjFgK84QffqPztGI3VBLG1A==
+
 levn@^0.4.1:
   version "0.4.1"
   resolved "https://registry.yarnpkg.com/levn/-/levn-0.4.1.tgz#ae4562c007473b932a6200d403268dd2fffc6ade"
@@ -2242,6 +3808,18 @@ levn@^0.4.1:
     prelude-ls "^1.2.1"
     type-check "~0.4.0"
 
+lines-and-columns@^1.1.6:
+  version "1.2.4"
+  resolved "https://registry.yarnpkg.com/lines-and-columns/-/lines-and-columns-1.2.4.tgz#eca284f75d2965079309dc0ad9255abb2ebc1632"
+  integrity sha512-7ylylesZQ/PV29jhEDl3Ufjo6ZX7gCqJr5F7PKrqc93v7fzSymt1BpwEU8nAUXs8qzzvqhbjhK5QZg6Mt/HkBg==
+
+locate-path@^5.0.0:
+  version "5.0.0"
+  resolved "https://registry.yarnpkg.com/locate-path/-/locate-path-5.0.0.tgz#1afba396afd676a6d42504d0a67a3a7eb9f62aa0"
+  integrity sha512-t7hw9pI+WvuwNJXwk5zVHpyhIqzg2qTlklJOf0mVxGSbe3Fp2VieZcduNYjaLDoy6p9uGpQEGWG87WpMKlNq8g==
+  dependencies:
+    p-locate "^4.1.0"
+
 locate-path@^6.0.0:
   version "6.0.0"
   resolved "https://registry.yarnpkg.com/locate-path/-/locate-path-6.0.0.tgz#55321eb309febbc59c4801d931a72452a681d286"
@@ -2249,6 +3827,11 @@ locate-path@^6.0.0:
   dependencies:
     p-locate "^5.0.0"
 
+lodash.memoize@^4.1.2:
+  version "4.1.2"
+  resolved "https://registry.yarnpkg.com/lodash.memoize/-/lodash.memoize-4.1.2.tgz#bcc6c49a42a2840ed997f323eada5ecd182e0bfe"
+  integrity sha512-t7j+NzmgnQzTAYXcsHYLgimltOV1MXHtlOWf6GjL9Kj8GK5FInw5JotxvbOs+IvV1/Dzo04/fCGfLVs7aXb4Ag==
+
 lodash.merge@^4.6.2:
   version "4.6.2"
   resolved "https://registry.yarnpkg.com/lodash.merge/-/lodash.merge-4.6.2.tgz#558aa53b43b661e1925a0afdfa36a9a1085fe57a"
@@ -2272,11 +3855,32 @@ lru-cache@^10.2.0:
   resolved "https://registry.yarnpkg.com/lru-cache/-/lru-cache-10.4.3.tgz#410fc8a17b70e598013df257c2446b7f3383f119"
   integrity sha512-JNAzZcXrCt42VGLuYz0zfAzDfAvJWW6AfYlDBQyDV5DClI2m5sAmK+OIO7s59XfsRsWHp02jAJrRadPRGTt6SQ==
 
-make-error@^1.1.1:
+lru-cache@^5.1.1:
+  version "5.1.1"
+  resolved "https://registry.yarnpkg.com/lru-cache/-/lru-cache-5.1.1.tgz#1da27e6710271947695daf6848e847f01d84b920"
+  integrity sha512-KpNARQA3Iwv+jTA0utUVVbrh+Jlrr1Fv0e56GGzAFOXN7dk/FviaDW8LHmK52DlcH4WP2n6gI8vN1aesBFgo9w==
+  dependencies:
+    yallist "^3.0.2"
+
+make-dir@^4.0.0:
+  version "4.0.0"
+  resolved "https://registry.yarnpkg.com/make-dir/-/make-dir-4.0.0.tgz#c3c2307a771277cd9638305f915c29ae741b614e"
+  integrity sha512-hXdUTZYIVOt1Ex//jAQi+wTZZpUpwBj/0QsOzqegb3rGMMeJiSEu5xLHnYfBrRV4RH2+OCSOO95Is/7x1WJ4bw==
+  dependencies:
+    semver "^7.5.3"
+
+make-error@^1.1.1, make-error@^1.3.6:
   version "1.3.6"
   resolved "https://registry.yarnpkg.com/make-error/-/make-error-1.3.6.tgz#2eb2e37ea9b67c4891f684a1394799af484cf7a2"
   integrity sha512-s8UhlNe7vPKomQhC1qFelMokr/Sc3AgNbso3n74mVPA5LTZwkB9NlXf4XPamLxJE8h0gh73rM94xvwRT2CVInw==
 
+makeerror@1.0.12:
+  version "1.0.12"
+  resolved "https://registry.yarnpkg.com/makeerror/-/makeerror-1.0.12.tgz#3e5dd2079a82e812e983cc6610c4a2cb0eaa801a"
+  integrity sha512-JmqCvUhmt43madlpFzG4BQzG2Z3m6tvQDNKdClZnO3VbIudJYmxsT0FNJMeiB2+JTSlTQTSbU8QdesVmwJcmLg==
+  dependencies:
+    tmpl "1.0.5"
+
 math-intrinsics@^1.1.0:
   version "1.1.0"
   resolved "https://registry.yarnpkg.com/math-intrinsics/-/math-intrinsics-1.1.0.tgz#a0dd74be81e2aa5c2f27e65ce283605ee4e2b7f9"
@@ -2292,6 +3896,11 @@ merge-descriptors@^2.0.0:
   resolved "https://registry.yarnpkg.com/merge-descriptors/-/merge-descriptors-2.0.0.tgz#ea922f660635a2249ee565e0449f951e6b603808"
   integrity sha512-Snk314V5ayFLhp3fkUREub6WtjBfPdCPY1Ln8/8munuLuiYhsABgBVWsozAG+MWMbVEvcdcpbi9R7ww22l9Q3g==
 
+merge-stream@^2.0.0:
+  version "2.0.0"
+  resolved "https://registry.yarnpkg.com/merge-stream/-/merge-stream-2.0.0.tgz#52823629a14dd00c9770fb6ad47dc6310f2c1f60"
+  integrity sha512-abv/qOcuPfk3URPfDzmZU1LKmuw8kT+0nIHvKrKgFrwifol/doWcdA4ZqsWQ8ENrFKkd67Mfpo/LovbIUsbt3w==
+
 merge2@^1.3.0, merge2@^1.4.1:
   version "1.4.1"
   resolved "https://registry.yarnpkg.com/merge2/-/merge2-1.4.1.tgz#4368892f885e907455a6fd7dc55c0c9d404990ae"
@@ -2339,7 +3948,7 @@ mimic-fn@^2.1.0:
   resolved "https://registry.yarnpkg.com/mimic-fn/-/mimic-fn-2.1.0.tgz#7ed2c2ccccaf84d3ffcb7a69b57711fc2083401b"
   integrity sha512-OqbOk5oEQeAZ8WXWydlu9HJjz9WVdEIvamMCcXmuqUYjTknH/sqsWvhQ3vgwKFRR1HpjvNBKQ37nbJgYzGqGcg==
 
-minimatch@^3.1.2:
+minimatch@^3.0.4, minimatch@^3.1.1, minimatch@^3.1.2:
   version "3.1.2"
   resolved "https://registry.yarnpkg.com/minimatch/-/minimatch-3.1.2.tgz#19cd194bfd3e428f049a70817c038d89ab4be35b"
   integrity sha512-J7p63hRiAjw1NDEww1W7i37+ByIrOWO5XQQAzZ3VOcL0PNybwpfmV/N05zFAzwQ9USyEcX6t3UO+K5aqBQOIHw==
@@ -2353,7 +3962,7 @@ minimatch@^9.0.3, minimatch@^9.0.4:
   dependencies:
     brace-expansion "^2.0.1"
 
-minimist@^1.2.6:
+minimist@^1.2.5, minimist@^1.2.6:
   version "1.2.8"
   resolved "https://registry.yarnpkg.com/minimist/-/minimist-1.2.8.tgz#c1a464e7693302e082a075cee0c057741ac4772c"
   integrity sha512-2yyAR8qBkN3YuheJanUpWC5U3bb5osDywNB8RzDVlDwDHbocAJveqqj1u8+SVD7jkWT4yvsHCpWqqWqAxb0zCA==
@@ -2378,6 +3987,11 @@ mylas@^2.1.9:
   resolved "https://registry.yarnpkg.com/mylas/-/mylas-2.1.13.tgz#1e23b37d58fdcc76e15d8a5ed23f9ae9fc0cbdf4"
   integrity sha512-+MrqnJRtxdF+xngFfUUkIMQrUUL0KsxbADUkn23Z/4ibGg192Q+z+CQyiYwvWTsYjJygmMR8+w3ZDa98Zh6ESg==
 
+napi-postinstall@^0.3.0:
+  version "0.3.4"
+  resolved "https://registry.yarnpkg.com/napi-postinstall/-/napi-postinstall-0.3.4.tgz#7af256d6588b5f8e952b9190965d6b019653bbb9"
+  integrity sha512-PHI5f1O0EP5xJ9gQmFGMS6IZcrVvTjpXjz7Na41gTE7eE2hK11lg04CECCYEEjdc17EV4DO+fkGEtt7TpTaTiQ==
+
 natural-compare@^1.4.0:
   version "1.4.0"
   resolved "https://registry.yarnpkg.com/natural-compare/-/natural-compare-1.4.0.tgz#4abebfeed7541f2c27acfb29bdbbd15c8d5ba4f7"
@@ -2388,6 +4002,11 @@ negotiator@^1.0.0:
   resolved "https://registry.yarnpkg.com/negotiator/-/negotiator-1.0.0.tgz#b6c91bb47172d69f93cfd7c357bbb529019b5f6a"
   integrity sha512-8Ofs/AUQh8MaEcrlq5xOX0CQ9ypTF5dl78mjlMNfOK08fzpgTHQRQPBxcPlEtIw0yRpws+Zo/3r+5WRby7u3Gg==
 
+neo-async@^2.6.2:
+  version "2.6.2"
+  resolved "https://registry.yarnpkg.com/neo-async/-/neo-async-2.6.2.tgz#b4aafb93e3aeb2d8174ca53cf163ab7d7308305f"
+  integrity sha512-Yd3UES5mWCSqR+qNT93S3UoYUkqAZ9lLg8a7g9rimsWmYGK8cVToA4/sF3RrshdyV3sAGMXVUmpMYOw+dLpOuw==
+
 node-domexception@^1.0.0:
   version "1.0.0"
   resolved "https://registry.yarnpkg.com/node-domexception/-/node-domexception-1.0.0.tgz#6888db46a1f71c0b76b3f7555016b63fe64766e5"
@@ -2409,11 +4028,28 @@ node-fetch@^3.3.2:
     fetch-blob "^3.1.4"
     formdata-polyfill "^4.0.10"
 
+node-int64@^0.4.0:
+  version "0.4.0"
+  resolved "https://registry.yarnpkg.com/node-int64/-/node-int64-0.4.0.tgz#87a9065cdb355d3182d8f94ce11188b825c68a3b"
+  integrity sha512-O5lz91xSOeoXP6DulyHfllpq+Eg00MWitZIbtPfoSEvqIHdl5gfcY6hYzDWnj0qD5tz52PI08u9qUvSVeUBeHw==
+
+node-releases@^2.0.27:
+  version "2.0.27"
+  resolved "https://registry.yarnpkg.com/node-releases/-/node-releases-2.0.27.tgz#eedca519205cf20f650f61d56b070db111231e4e"
+  integrity sha512-nmh3lCkYZ3grZvqcCH+fjmQ7X+H0OeZgP40OierEaAptX4XofMh5kwNbWh7lBduUzCcV/8kZ+NDLCwm2iorIlA==
+
 normalize-path@^3.0.0, normalize-path@~3.0.0:
   version "3.0.0"
   resolved "https://registry.yarnpkg.com/normalize-path/-/normalize-path-3.0.0.tgz#0dcd69ff23a1c9b11fd0978316644a0388216a65"
   integrity sha512-6eZs5Ls3WtCisHWp9S2GUy8dqkpGi4BVSz3GaqiE6ezub0512ESztXUwUB6C6IKbQkY2Pnb/mD4WYojCRwcwLA==
 
+npm-run-path@^4.0.1:
+  version "4.0.1"
+  resolved "https://registry.yarnpkg.com/npm-run-path/-/npm-run-path-4.0.1.tgz#b7ecd1e5ed53da8e37a55e1c2269e0b97ed748ea"
+  integrity sha512-S48WzZW777zhNIrn7gxOlISNAqi9ZC/uQFnRdbeIHhZhCA6UqpkOT8T1G7BvfdgP4Er8gF4sUbaS0i7QvIfCWw==
+  dependencies:
+    path-key "^3.0.0"
+
 object-assign@^4:
   version "4.1.1"
   resolved "https://registry.yarnpkg.com/object-assign/-/object-assign-4.1.1.tgz#2109adc7965887cfc05cbbd442cac8bfbb360863"
@@ -2436,14 +4072,14 @@ on-finished@^2.4.1:
   dependencies:
     ee-first "1.1.1"
 
-once@^1.4.0:
+once@^1.3.0, once@^1.4.0:
   version "1.4.0"
   resolved "https://registry.yarnpkg.com/once/-/once-1.4.0.tgz#583b1aa775961d4b113ac17d9c50baef9dd76bd1"
   integrity sha512-lNaJgI+2Q5URQBkccEKHTQOPaXdUxnZZElQTZY0MFUAuaEqe1E+Nyvgdz/aIyNi6Z9MzO5dv1H8n58/GELp3+w==
   dependencies:
     wrappy "1"
 
-onetime@^5.1.0:
+onetime@^5.1.0, onetime@^5.1.2:
   version "5.1.2"
   resolved "https://registry.yarnpkg.com/onetime/-/onetime-5.1.2.tgz#d0e96ebb56b07476df1dd9c4806e5237985ca45e"
   integrity sha512-kbpaSSGJTWdAY5KPVeMOKXSrPtr8C8C7wodJbcsd51jRnmD+GZu8Y0VoU6Dm5Z4vWr0Ig/1NKuWRKf7j5aaYSg==
@@ -2487,13 +4123,27 @@ ora@5.4.1:
     strip-ansi "^6.0.0"
     wcwidth "^1.0.1"
 
-p-limit@^3.0.2:
+p-limit@^2.2.0:
+  version "2.3.0"
+  resolved "https://registry.yarnpkg.com/p-limit/-/p-limit-2.3.0.tgz#3dd33c647a214fdfffd835933eb086da0dc21db1"
+  integrity sha512-//88mFWSJx8lxCzwdAABTJL2MyWB12+eIY7MDL2SqLmAkeKU9qxRvWuSyTjm3FUmpBEMuFfckAIqEaVGUDxb6w==
+  dependencies:
+    p-try "^2.0.0"
+
+p-limit@^3.0.2, p-limit@^3.1.0:
   version "3.1.0"
   resolved "https://registry.yarnpkg.com/p-limit/-/p-limit-3.1.0.tgz#e1daccbe78d0d1388ca18c64fea38e3e57e3706b"
   integrity sha512-TYOanM3wGwNGsZN2cVTYPArw454xnXj5qmWF1bEoAc4+cU/ol7GVh7odevjp1FNHduHc3KZMcFduxU5Xc6uJRQ==
   dependencies:
     yocto-queue "^0.1.0"
 
+p-locate@^4.1.0:
+  version "4.1.0"
+  resolved "https://registry.yarnpkg.com/p-locate/-/p-locate-4.1.0.tgz#a3428bb7088b3a60292f66919278b7c297ad4f07"
+  integrity sha512-R79ZZ/0wAxKGu3oYMlz8jy/kbhsNrS7SKZ7PxEHBgJ5+F2mtFW2fK2cOtBh1cHYkQsbzFV7I+EoRKe6Yt0oK7A==
+  dependencies:
+    p-limit "^2.2.0"
+
 p-locate@^5.0.0:
   version "5.0.0"
   resolved "https://registry.yarnpkg.com/p-locate/-/p-locate-5.0.0.tgz#83c8315c6785005e3bd021839411c9e110e6d834"
@@ -2501,6 +4151,11 @@ p-locate@^5.0.0:
   dependencies:
     p-limit "^3.0.2"
 
+p-try@^2.0.0:
+  version "2.2.0"
+  resolved "https://registry.yarnpkg.com/p-try/-/p-try-2.2.0.tgz#cb2868540e313d61de58fafbe35ce9004d5540e6"
+  integrity sha512-R4nPAVTAU0B9D35/Gk3uJf/7XYbQcyohSKdvAxIRSNghFl4e71hVoGnBNQz9cWaXxO2I10KTC+3jMdvvoKw6dQ==
+
 package-json-from-dist@^1.0.0:
   version "1.0.1"
   resolved "https://registry.yarnpkg.com/package-json-from-dist/-/package-json-from-dist-1.0.1.tgz#4f1471a010827a86f94cfd9b0727e36d267de505"
@@ -2536,6 +4191,16 @@ parse-bmfont-xml@^1.1.6:
     xml-parse-from-string "^1.0.0"
     xml2js "^0.5.0"
 
+parse-json@^5.2.0:
+  version "5.2.0"
+  resolved "https://registry.yarnpkg.com/parse-json/-/parse-json-5.2.0.tgz#c76fc66dee54231c962b22bcc8a72cf2f99753cd"
+  integrity sha512-ayCKvm/phCGxOkYRSCM82iDwct8/EonSEgCSxWxD7ve6jHggsFl4fZVQBPRNgQoKiuV/odhFrGzQXZwbifC8Rg==
+  dependencies:
+    "@babel/code-frame" "^7.0.0"
+    error-ex "^1.3.1"
+    json-parse-even-better-errors "^2.3.0"
+    lines-and-columns "^1.1.6"
+
 parseurl@^1.3.3:
   version "1.3.3"
   resolved "https://registry.yarnpkg.com/parseurl/-/parseurl-1.3.3.tgz#9da19e7bee8d12dff0513ed5b76957793bc2e8d4"
@@ -2560,7 +4225,12 @@ path-exists@^4.0.0:
   resolved "https://registry.yarnpkg.com/path-exists/-/path-exists-4.0.0.tgz#513bdbe2d3b95d7762e8c1137efa195c6c61b5b3"
   integrity sha512-ak9Qy5Q7jYb2Wwcey5Fpvg2KoAc/ZIhLSLOSBmRmygPsGwkVVt0fZa0qrtMz+m6tJTAHfZQ8FnmB4MG4LWy7/w==
 
-path-key@^3.1.0:
+path-is-absolute@^1.0.0:
+  version "1.0.1"
+  resolved "https://registry.yarnpkg.com/path-is-absolute/-/path-is-absolute-1.0.1.tgz#174b9268735534ffbc7ace6bf53a5a9e1b5c5f5f"
+  integrity sha512-AVbw3UJ2e9bq64vSaS9Am0fje1Pa8pbGqTTsmXfaIiMpnr5DlDhfJOuLj9Sf95ZPVDAUerDfEk88MPmPe7UCQg==
+
+path-key@^3.0.0, path-key@^3.1.0:
   version "3.1.1"
   resolved "https://registry.yarnpkg.com/path-key/-/path-key-3.1.1.tgz#581f6ade658cbba65a0d3380de7753295054f375"
   integrity sha512-ojmeN0qd+y0jszEtoY48r0Peq5dwMEkIlCOu6Q5f41lfkswXuKtYrhgoTpLnyIcHm24Uhqx+5Tqm2InSwLhE6Q==
@@ -2588,11 +4258,26 @@ peek-readable@^4.1.0:
   resolved "https://registry.yarnpkg.com/peek-readable/-/peek-readable-4.1.0.tgz#4ece1111bf5c2ad8867c314c81356847e8a62e72"
   integrity sha512-ZI3LnwUv5nOGbQzD9c2iDG6toheuXSZP5esSHBjopsXH4dg19soufvpUGA3uohi5anFtGb2lhAVdHzH6R/Evvg==
 
+picocolors@^1.1.1:
+  version "1.1.1"
+  resolved "https://registry.yarnpkg.com/picocolors/-/picocolors-1.1.1.tgz#3d321af3eab939b083c8f929a1d12cda81c26b6b"
+  integrity sha512-xceH2snhtb5M9liqDsmEw56le376mTZkEX/jEb/RxNFyegNul7eNslCXP9FDj/Lcu0X8KEyMceP2ntpaHrDEVA==
+
 picomatch@^2.0.4, picomatch@^2.2.1, picomatch@^2.3.1:
   version "2.3.1"
   resolved "https://registry.yarnpkg.com/picomatch/-/picomatch-2.3.1.tgz#3ba3833733646d9d3e4995946c1365a67fb07a42"
   integrity sha512-JU3teHTNjmE2VCGFzuY8EXzCDVwEqB2a8fsIvwaStHhAWJEeVd1o1QD80CU6+ZdEXXSLbSsuLwJjkCBWqRQUVA==
 
+picomatch@^4.0.2:
+  version "4.0.3"
+  resolved "https://registry.yarnpkg.com/picomatch/-/picomatch-4.0.3.tgz#796c76136d1eead715db1e7bad785dedd695a042"
+  integrity sha512-5gTmgEY/sqK6gFXLIsQNH19lWb4ebPDLA4SdLP7dsWkIXHWlG66oPuVvXSGFPppYZz8ZDZq0dYYrbHfBCVUb1Q==
+
+pirates@^4.0.7:
+  version "4.0.7"
+  resolved "https://registry.yarnpkg.com/pirates/-/pirates-4.0.7.tgz#643b4a18c4257c8a65104b73f3049ce9a0a15e22"
+  integrity sha512-TfySrs/5nm8fQJDcBDuUng3VOUKsd7S+zqvbOTiGXHfxX4wK31ard+hoNuvkicM/2YFzlpDgABOevKSsB4G/FA==
+
 pixelmatch@^5.3.0:
   version "5.3.0"
   resolved "https://registry.yarnpkg.com/pixelmatch/-/pixelmatch-5.3.0.tgz#5e5321a7abedfb7962d60dbf345deda87cb9560a"
@@ -2605,6 +4290,13 @@ pkce-challenge@^5.0.0:
   resolved "https://registry.yarnpkg.com/pkce-challenge/-/pkce-challenge-5.0.0.tgz#c3a405cb49e272094a38e890a2b51da0228c4d97"
   integrity sha512-ueGLflrrnvwB3xuo/uGob5pd5FN7l0MsLf0Z87o/UQmRtwjvfylfc9MurIxRAWywCYTgrvpXBcqjV4OfCYGCIQ==
 
+pkg-dir@^4.2.0:
+  version "4.2.0"
+  resolved "https://registry.yarnpkg.com/pkg-dir/-/pkg-dir-4.2.0.tgz#f099133df7ede422e81d1d8448270eeb3e4261f3"
+  integrity sha512-HRDzbaKjC+AOWVXxAU/x54COGeIv9eb+6CkDSQoNTt4XyWoIJvuPsXizxu/Fr23EiekbtZwmh1IcIG/l/a10GQ==
+  dependencies:
+    find-up "^4.0.0"
+
 playwright-core@^1.56.1:
   version "1.56.1"
   resolved "https://registry.yarnpkg.com/playwright-core/-/playwright-core-1.56.1.tgz#24a66481e5cd33a045632230aa2c4f0cb6b1db3d"
@@ -2637,6 +4329,15 @@ prettier@^3.3.3:
   resolved "https://registry.yarnpkg.com/prettier/-/prettier-3.6.2.tgz#ccda02a1003ebbb2bfda6f83a074978f608b9393"
   integrity sha512-I7AIg5boAr5R0FFtJ6rCfD+LFsWHp81dolrFD8S79U9tb8Az2nGrJncnMSnys+bpQJfRUzqs9hnA81OAA3hCuQ==
 
+pretty-format@30.2.0, pretty-format@^30.0.0:
+  version "30.2.0"
+  resolved "https://registry.yarnpkg.com/pretty-format/-/pretty-format-30.2.0.tgz#2d44fe6134529aed18506f6d11509d8a62775ebe"
+  integrity sha512-9uBdv/B4EefsuAL+pWqueZyZS2Ba+LxfFeQ9DN14HU4bN8bhaxKdkpjpB6fs9+pSjIBu+FXQHImEg8j/Lw0+vA==
+  dependencies:
+    "@jest/schemas" "30.0.5"
+    ansi-styles "^5.2.0"
+    react-is "^18.3.1"
+
 process@^0.11.10:
   version "0.11.10"
   resolved "https://registry.yarnpkg.com/process/-/process-0.11.10.tgz#7332300e840161bda3e69a1d1d91a7d4bc16f182"
@@ -2660,6 +4361,11 @@ punycode@^2.1.0:
   resolved "https://registry.yarnpkg.com/punycode/-/punycode-2.3.1.tgz#027422e2faec0b25e1549c3e1bd8309b9133b6e5"
   integrity sha512-vYt7UD1U9Wg6138shLtLOvdAu+8DsC/ilFtEVHcH+wydcSpNE20AfSOduf6MkRFahL5FY7X1oU7nKVZFtfq8Fg==
 
+pure-rand@^7.0.0:
+  version "7.0.1"
+  resolved "https://registry.yarnpkg.com/pure-rand/-/pure-rand-7.0.1.tgz#6f53a5a9e3e4a47445822af96821ca509ed37566"
+  integrity sha512-oTUZM/NAZS8p7ANR3SHh30kXB+zK2r2BPcEn/awJIbOvq82WoMN4p62AWWp3Hhw50G0xMsw1mhIBLqHw64EcNQ==
+
 qs@^6.14.0:
   version "6.14.0"
   resolved "https://registry.yarnpkg.com/qs/-/qs-6.14.0.tgz#c63fa40680d2c5c941412a0e899c89af60c0a930"
@@ -2692,6 +4398,11 @@ raw-body@^3.0.0:
     iconv-lite "0.7.0"
     unpipe "1.0.0"
 
+react-is@^18.3.1:
+  version "18.3.1"
+  resolved "https://registry.yarnpkg.com/react-is/-/react-is-18.3.1.tgz#e83557dc12eae63a99e003a46388b1dcbb44db7e"
+  integrity sha512-/LLMVyas0ljjAtoYiPqYiL8VWXzUUdThrmU5+n20DZv+a+ClRoevUzw5JxU+Ieh5/c87ytoTBV9G1FiKfNJdmg==
+
 readable-stream@^3.4.0:
   version "3.6.2"
   resolved "https://registry.yarnpkg.com/readable-stream/-/readable-stream-3.6.2.tgz#56a9b36ea965c00c5a93ef31eb111a0f11056967"
@@ -2731,11 +4442,28 @@ readline@^1.3.0:
   resolved "https://registry.yarnpkg.com/readline/-/readline-1.3.0.tgz#c580d77ef2cfc8752b132498060dc9793a7ac01c"
   integrity sha512-k2d6ACCkiNYz222Fs/iNze30rRJ1iIicW7JuX/7/cozvih6YCkFZH+J6mAFDVgv0dRBaAyr4jDqC95R2y4IADg==
 
+require-directory@^2.1.1:
+  version "2.1.1"
+  resolved "https://registry.yarnpkg.com/require-directory/-/require-directory-2.1.1.tgz#8c64ad5fd30dab1c976e2344ffe7f792a6a6df42"
+  integrity sha512-fGxEI7+wsG9xrvdjsrlmL22OMTTiHRwAMroiEeMgq8gzoLC/PQr7RsRDSTLUg/bZAZtF+TVIkHc6/4RIKrui+Q==
+
+resolve-cwd@^3.0.0:
+  version "3.0.0"
+  resolved "https://registry.yarnpkg.com/resolve-cwd/-/resolve-cwd-3.0.0.tgz#0f0075f1bb2544766cf73ba6a6e2adfebcb13f2d"
+  integrity sha512-OrZaX2Mb+rJCpH/6CpSqt9xFVpN++x01XnN2ie9g6P5/3xelLAkXWVADpdz1IHD/KFfEXyE6V0U01OQ3UO2rEg==
+  dependencies:
+    resolve-from "^5.0.0"
+
 resolve-from@^4.0.0:
   version "4.0.0"
   resolved "https://registry.yarnpkg.com/resolve-from/-/resolve-from-4.0.0.tgz#4abcd852ad32dd7baabfe9b40e00a36db5f392e6"
   integrity sha512-pb/MYmXstAkysRFx8piNI1tGFNQIFA3vkE3Gq4EuA1dF6gHp/+vgZqsCGJapvy8N3Q+4o7FwvquPJcnZ7RYy4g==
 
+resolve-from@^5.0.0:
+  version "5.0.0"
+  resolved "https://registry.yarnpkg.com/resolve-from/-/resolve-from-5.0.0.tgz#c35225843df8f776df21c57557bc087e9dfdfc69"
+  integrity sha512-qYg9KP24dD5qka9J47d0aVky0N+b4fTU89LN9iDnjB5waksiC49rvMB0PrUJQGoTmH50XPiqOvAjDfaijGxYZw==
+
 resolve-pkg-maps@^1.0.0:
   version "1.0.0"
   resolved "https://registry.yarnpkg.com/resolve-pkg-maps/-/resolve-pkg-maps-1.0.0.tgz#616b3dc2c57056b5588c31cdf4b3d64db133720f"
@@ -2794,6 +4522,16 @@ sax@>=0.6.0:
   resolved "https://registry.yarnpkg.com/sax/-/sax-1.4.1.tgz#44cc8988377f126304d3b3fc1010c733b929ef0f"
   integrity sha512-+aWOz7yVScEGoKNd4PA10LZ8sk0A/z5+nXQG5giUO5rprX9jgYsTdov9qCchZiPIZezbZH+jRut8nPodFAX4Jg==
 
+semver@^6.3.1:
+  version "6.3.1"
+  resolved "https://registry.yarnpkg.com/semver/-/semver-6.3.1.tgz#556d2ef8689146e46dcea4bfdd095f3434dffcb4"
+  integrity sha512-BR7VvDCVHO+q2xBEWskxS6DJE1qRnb7DxzUrogb71CWoSficBxYsiAGd+Kl0mmq/MprG9yArRkyrQxTO6XjMzA==
+
+semver@^7.5.3, semver@^7.5.4, semver@^7.7.2, semver@^7.7.3:
+  version "7.7.4"
+  resolved "https://registry.yarnpkg.com/semver/-/semver-7.7.4.tgz#28464e36060e991fa7a11d0279d2d3f3b57a7e8a"
+  integrity sha512-vFKC2IEtQnVhpT78h1Yp8wzwrf8CM+MzKMHGJZfBtzhZNycRFnXsHk6E5TxIkkMsgNS7mdX3AGB7x2QM2di4lA==
+
 semver@^7.6.0:
   version "7.7.3"
   resolved "https://registry.yarnpkg.com/semver/-/semver-7.7.3.tgz#4b5f4143d007633a8dc671cd0a6ef9147b8bb946"
@@ -2883,7 +4621,7 @@ side-channel@^1.1.0:
     side-channel-map "^1.0.1"
     side-channel-weakmap "^1.0.2"
 
-signal-exit@^3.0.2:
+signal-exit@^3.0.2, signal-exit@^3.0.3:
   version "3.0.7"
   resolved "https://registry.yarnpkg.com/signal-exit/-/signal-exit-3.0.7.tgz#a9a1767f8af84155114eaabd73f99273c8f59ad9"
   integrity sha512-wnD2ZE+l+SPC/uoS0vXeE9L1+0wuaMqKlfz9AMUo38JsyLSBWSFcHR1Rri62LZc12vLr1gb3jl7iwQhgwpAbGQ==
@@ -2903,6 +4641,31 @@ slash@^3.0.0:
   resolved "https://registry.yarnpkg.com/slash/-/slash-3.0.0.tgz#6539be870c165adbd5240220dbe361f1bc4d4634"
   integrity sha512-g9Q1haeby36OSStwb4ntCGGGaKsaVSjQ68fBxoQcutl5fS1vuY18H3wSt3jFyFtrkx+Kz0V1G85A4MyAdDMi2Q==
 
+source-map-support@0.5.13:
+  version "0.5.13"
+  resolved "https://registry.yarnpkg.com/source-map-support/-/source-map-support-0.5.13.tgz#31b24a9c2e73c2de85066c0feb7d44767ed52932"
+  integrity sha512-SHSKFHadjVA5oR4PPqhtAVdcBWwRYVd6g6cAXnIbRiIwc2EhPrTuKUBdSLvlEKyIP3GCf89fltvcZiP9MMFA1w==
+  dependencies:
+    buffer-from "^1.0.0"
+    source-map "^0.6.0"
+
+source-map@^0.6.0, source-map@^0.6.1:
+  version "0.6.1"
+  resolved "https://registry.yarnpkg.com/source-map/-/source-map-0.6.1.tgz#74722af32e9614e9c287a8d0bbde48b5e2f1a263"
+  integrity sha512-UjgapumWlbMhkBgzT7Ykc5YXUT46F0iKu8SGXq0bcwP5dz/h0Plj6enJqjz1Zbq2l5WaqYnrVbwWOWMyF3F47g==
+
+sprintf-js@~1.0.2:
+  version "1.0.3"
+  resolved "https://registry.yarnpkg.com/sprintf-js/-/sprintf-js-1.0.3.tgz#04e6926f662895354f3dd015203633b857297e2c"
+  integrity sha512-D9cPgkvLlV3t3IzL0D0YLvGA9Ahk4PcvVwUbN0dSGr1aP0Nrt4AEnTUbuGvquEC0mA64Gqt1fzirlRs5ibXx8g==
+
+stack-utils@^2.0.6:
+  version "2.0.6"
+  resolved "https://registry.yarnpkg.com/stack-utils/-/stack-utils-2.0.6.tgz#aaf0748169c02fc33c8232abccf933f54a1cc34f"
+  integrity sha512-XlkWvfIm6RmsWtNJx+uqtKLS8eqFbxUg0ZzLXqY0caEy9l7hruX8IpiDnjsLavoBgqCCR71TqWO8MaXYheJ3RQ==
+  dependencies:
+    escape-string-regexp "^2.0.0"
+
 statuses@2.0.1:
   version "2.0.1"
   resolved "https://registry.yarnpkg.com/statuses/-/statuses-2.0.1.tgz#55cb000ccf1d48728bd23c685a063998cf1a1b63"
@@ -2913,6 +4676,14 @@ statuses@^2.0.1:
   resolved "https://registry.yarnpkg.com/statuses/-/statuses-2.0.2.tgz#8f75eecef765b5e1cfcdc080da59409ed424e382"
   integrity sha512-DvEy55V3DB7uknRo+4iOGT5fP1slR8wQohVdknigZPMpMstaKJQWhwiYBACJE3Ul2pTnATihhBYnRhZQHGBiRw==
 
+string-length@^4.0.2:
+  version "4.0.2"
+  resolved "https://registry.yarnpkg.com/string-length/-/string-length-4.0.2.tgz#a8a8dc7bd5c1a82b9b3c8b87e125f66871b6e57a"
+  integrity sha512-+l6rNN5fYHNhZZy41RXsYptCjA2Igmq4EG7kZAYFQI1E1VTXarr6ZPXBg6eq7Y6eK4FEhY6AJlyuFIb/v/S0VQ==
+  dependencies:
+    char-regex "^1.0.2"
+    strip-ansi "^6.0.0"
+
 "string-width-cjs@npm:string-width@^4.2.0":
   version "4.2.3"
   resolved "https://registry.yarnpkg.com/string-width/-/string-width-4.2.3.tgz#269c7117d27b05ad2e536830a8ec895ef9c6d010"
@@ -2922,7 +4693,7 @@ statuses@^2.0.1:
     is-fullwidth-code-point "^3.0.0"
     strip-ansi "^6.0.1"
 
-string-width@^4.0.0, string-width@^4.1.0, string-width@^4.2.2:
+string-width@^4.0.0, string-width@^4.1.0, string-width@^4.2.0, string-width@^4.2.2, string-width@^4.2.3:
   version "4.2.3"
   resolved "https://registry.yarnpkg.com/string-width/-/string-width-4.2.3.tgz#269c7117d27b05ad2e536830a8ec895ef9c6d010"
   integrity sha512-wKyQRQpjJ0sIp62ErSZdGsjMJWsap5oRNihHhu6G7JVO/9jIB6UyevL+tXuOqrng8j/cxKTWyWUwvSTriiZz/g==
@@ -2973,6 +4744,16 @@ strip-bom@^3.0.0:
   resolved "https://registry.yarnpkg.com/strip-bom/-/strip-bom-3.0.0.tgz#2334c18e9c759f7bdd56fdef7e9ae3d588e68ed3"
   integrity sha512-vavAMRXOgBVNF6nyEEmL3DBK19iRpDcoIwW+swQ+CbGiu7lju6t+JklA1MHweoWtadgt4ISVUsXLyDq34ddcwA==
 
+strip-bom@^4.0.0:
+  version "4.0.0"
+  resolved "https://registry.yarnpkg.com/strip-bom/-/strip-bom-4.0.0.tgz#9c3505c1db45bcedca3d9cf7a16f5c5aa3901878"
+  integrity sha512-3xurFv5tEgii33Zi8Jtp55wEIILR9eh34FAW00PZf+JnSsTmV/ioewSgQl97JHvgjoRGwPShsWm+IdrxB35d0w==
+
+strip-final-newline@^2.0.0:
+  version "2.0.0"
+  resolved "https://registry.yarnpkg.com/strip-final-newline/-/strip-final-newline-2.0.0.tgz#89b852fb2fcbe936f6f4b3187afb0a12c1ab58ad"
+  integrity sha512-BrpvfNAE3dcvq7ll3xVumzjKjZQ5tI1sEUIKr3Uoks0XUl45St3FlatVqef9prk4jRDzhW6WZg+3bk93y6pLjA==
+
 strip-json-comments@^3.1.1:
   version "3.1.1"
   resolved "https://registry.yarnpkg.com/strip-json-comments/-/strip-json-comments-3.1.1.tgz#31f1281b3832630434831c310c01cccda8cbe006"
@@ -2993,11 +4774,39 @@ supports-color@^7.1.0:
   dependencies:
     has-flag "^4.0.0"
 
+supports-color@^8.1.1:
+  version "8.1.1"
+  resolved "https://registry.yarnpkg.com/supports-color/-/supports-color-8.1.1.tgz#cd6fc17e28500cff56c1b86c0a7fd4a54a73005c"
+  integrity sha512-MpUEN2OodtUzxvKQl72cUF7RQ5EiHsGvSsVG0ia9c5RbWGL2CI4C7EpPS8UTBIplnlzZiNuV56w+FuNxy3ty2Q==
+  dependencies:
+    has-flag "^4.0.0"
+
+synckit@^0.11.8:
+  version "0.11.12"
+  resolved "https://registry.yarnpkg.com/synckit/-/synckit-0.11.12.tgz#abe74124264fbc00a48011b0d98bdc1cffb64a7b"
+  integrity sha512-Bh7QjT8/SuKUIfObSXNHNSK6WHo6J1tHCqJsuaFDP7gP0fkzSfTxI8y85JrppZ0h8l0maIgc2tfuZQ6/t3GtnQ==
+  dependencies:
+    "@pkgr/core" "^0.2.9"
+
+test-exclude@^6.0.0:
+  version "6.0.0"
+  resolved "https://registry.yarnpkg.com/test-exclude/-/test-exclude-6.0.0.tgz#04a8698661d805ea6fa293b6cb9e63ac044ef15e"
+  integrity sha512-cAGWPIyOHU6zlmg88jwm7VRyXnMN7iV68OGAbYDk/Mh/xC/pzVPlQtY6ngoIH/5/tciuhGfvESU8GrHrcxD56w==
+  dependencies:
+    "@istanbuljs/schema" "^0.1.2"
+    glob "^7.1.4"
+    minimatch "^3.0.4"
+
 tinycolor2@^1.6.0:
   version "1.6.0"
   resolved "https://registry.yarnpkg.com/tinycolor2/-/tinycolor2-1.6.0.tgz#f98007460169b0263b97072c5ae92484ce02d09e"
   integrity sha512-XPaBkWQJdsf3pLKJV9p4qN/S+fm2Oj8AIPo1BTUhg5oxkvm9+SVEGFdhyOz7tTdUTfvxMiAs4sp6/eZO2Ew+pw==
 
+tmpl@1.0.5:
+  version "1.0.5"
+  resolved "https://registry.yarnpkg.com/tmpl/-/tmpl-1.0.5.tgz#8683e0b902bb9c20c4f726e3c0b69f36518c07cc"
+  integrity sha512-3f0uOEAQwIqGuWW2MVzYg8fV/QNnc/IpuJNG837rLuczAaLVHslWHZQj4IGiEl5Hs3kkbhwL9Ab7Hrsmuj+Smw==
+
 to-regex-range@^5.0.1:
   version "5.0.1"
   resolved "https://registry.yarnpkg.com/to-regex-range/-/to-regex-range-5.0.1.tgz#1648c44aae7c8d988a326018ed72f5b4dd0392e4"
@@ -3033,6 +4842,21 @@ ts-api-utils@^2.1.0:
   resolved "https://registry.yarnpkg.com/ts-api-utils/-/ts-api-utils-2.1.0.tgz#595f7094e46eed364c13fd23e75f9513d29baf91"
   integrity sha512-CUgTZL1irw8u29bzrOD/nH85jqyc74D6SshFgujOIA7osm2Rz7dYH77agkx7H4FBNxDq7Cjf+IjaX/8zwFW+ZQ==
 
+ts-jest@^29.4.6:
+  version "29.4.6"
+  resolved "https://registry.yarnpkg.com/ts-jest/-/ts-jest-29.4.6.tgz#51cb7c133f227396818b71297ad7409bb77106e9"
+  integrity sha512-fSpWtOO/1AjSNQguk43hb/JCo16oJDnMJf3CdEGNkqsEX3t0KX96xvyX1D7PfLCpVoKu4MfVrqUkFyblYoY4lA==
+  dependencies:
+    bs-logger "^0.2.6"
+    fast-json-stable-stringify "^2.1.0"
+    handlebars "^4.7.8"
+    json5 "^2.2.3"
+    lodash.memoize "^4.1.2"
+    make-error "^1.3.6"
+    semver "^7.7.3"
+    type-fest "^4.41.0"
+    yargs-parser "^21.1.1"
+
 ts-node@^10.9.2:
   version "10.9.2"
   resolved "https://registry.yarnpkg.com/ts-node/-/ts-node-10.9.2.tgz#70f021c9e185bccdca820e26dc413805c101c71f"
@@ -3074,6 +4898,11 @@ tsconfig-paths@^4.2.0:
     minimist "^1.2.6"
     strip-bom "^3.0.0"
 
+tslib@^2.4.0:
+  version "2.8.1"
+  resolved "https://registry.yarnpkg.com/tslib/-/tslib-2.8.1.tgz#612efe4ed235d567e8aba5f2a5fab70280ade83f"
+  integrity sha512-oJFu94HQb+KVduSUQL7wnpmqnfmLsOA/nAh6b6EH0wCEoK0/mPeXU6c3wKDV83MkOuHPRHtSXKKU99IBazS/2w==
+
 tsx@^4.19.3:
   version "4.20.6"
   resolved "https://registry.yarnpkg.com/tsx/-/tsx-4.20.6.tgz#8fb803fd9c1f70e8ccc93b5d7c5e03c3979ccb2e"
@@ -3098,11 +4927,26 @@ type-check@^0.4.0, type-check@~0.4.0:
   dependencies:
     prelude-ls "^1.2.1"
 
+type-detect@4.0.8:
+  version "4.0.8"
+  resolved "https://registry.yarnpkg.com/type-detect/-/type-detect-4.0.8.tgz#7646fb5f18871cfbb7749e69bd39a6388eb7450c"
+  integrity sha512-0fr/mIH1dlO+x7TlcMy+bIDqKPsw/70tVyeHW787goQjhmqaZe10uwLujubK9q9Lg6Fiho1KUKDYz0Z7k7g5/g==
+
 type-fest@^0.20.2:
   version "0.20.2"
   resolved "https://registry.yarnpkg.com/type-fest/-/type-fest-0.20.2.tgz#1bf207f4b28f91583666cb5fbd327887301cd5f4"
   integrity sha512-Ne+eE4r0/iWnpAxD852z3A+N0Bt5RN//NjJwRd2VFHEmrywxf5vsZlh4R6lixl6B+wz/8d+maTSAkN1FIkI3LQ==
 
+type-fest@^0.21.3:
+  version "0.21.3"
+  resolved "https://registry.yarnpkg.com/type-fest/-/type-fest-0.21.3.tgz#d260a24b0198436e133fa26a524a6d65fa3b2e37"
+  integrity sha512-t0rzBq87m3fVcduHDUFhKmyyX+9eo6WQjZvf51Ea/M0Q7+T374Jp1aUiyUl0GKxp8M/OETVHSDvmkyPgvX+X2w==
+
+type-fest@^4.41.0:
+  version "4.41.0"
+  resolved "https://registry.yarnpkg.com/type-fest/-/type-fest-4.41.0.tgz#6ae1c8e5731273c2bf1f58ad39cbae2c91a46c58"
+  integrity sha512-TeTSQ6H5YHvpqVwBRcnLDCBnDOHWYu7IvGbHT6N8AOymcr9PJGjc1GTtiWZTYg0NCgYwvnYWEkVChQAr9bjfwA==
+
 type-is@^2.0.0, type-is@^2.0.1:
   version "2.0.1"
   resolved "https://registry.yarnpkg.com/type-is/-/type-is-2.0.1.tgz#64f6cf03f92fce4015c2b224793f6bdd4b068c97"
@@ -3117,16 +4961,61 @@ typescript@^5.6.3:
   resolved "https://registry.yarnpkg.com/typescript/-/typescript-5.9.3.tgz#5b4f59e15310ab17a216f5d6cf53ee476ede670f"
   integrity sha512-jl1vZzPDinLr9eUt3J/t7V6FgNEw9QjvBPdysz9KfQDD41fQrC2Y4vKQdiaUpFT4bXlb1RHhLpp8wtm6M5TgSw==
 
+uglify-js@^3.1.4:
+  version "3.19.3"
+  resolved "https://registry.yarnpkg.com/uglify-js/-/uglify-js-3.19.3.tgz#82315e9bbc6f2b25888858acd1fff8441035b77f"
+  integrity sha512-v3Xu+yuwBXisp6QYTcH4UbH+xYJXqnq2m/LtQVWKWzYc1iehYnLixoQDN9FH6/j9/oybfd6W9Ghwkl8+UMKTKQ==
+
 undici-types@~6.21.0:
   version "6.21.0"
   resolved "https://registry.yarnpkg.com/undici-types/-/undici-types-6.21.0.tgz#691d00af3909be93a7faa13be61b3a5b50ef12cb"
   integrity sha512-iwDZqg0QAGrg9Rav5H4n0M64c3mkR59cJ6wQp+7C4nI0gsmExaedaYLNO44eT4AtBBwjbTiGPMlt2Md0T9H9JQ==
 
+undici-types@~7.16.0:
+  version "7.16.0"
+  resolved "https://registry.yarnpkg.com/undici-types/-/undici-types-7.16.0.tgz#ffccdff36aea4884cbfce9a750a0580224f58a46"
+  integrity sha512-Zz+aZWSj8LE6zoxD+xrjh4VfkIG8Ya6LvYkZqtUQGJPZjYl53ypCaUwWqo7eI0x66KBGeRo+mlBEkMSeSZ38Nw==
+
 unpipe@1.0.0:
   version "1.0.0"
   resolved "https://registry.yarnpkg.com/unpipe/-/unpipe-1.0.0.tgz#b2bf4ee8514aae6165b4817829d21b2ef49904ec"
   integrity sha512-pjy2bYhSsufwWlKwPc+l3cN7+wuJlK6uz0YdJEOlQDbl6jo/YlPi4mb8agUkVC8BF7V8NuzeyPNqRksA3hztKQ==
 
+unrs-resolver@^1.7.11:
+  version "1.11.1"
+  resolved "https://registry.yarnpkg.com/unrs-resolver/-/unrs-resolver-1.11.1.tgz#be9cd8686c99ef53ecb96df2a473c64d304048a9"
+  integrity sha512-bSjt9pjaEBnNiGgc9rUiHGKv5l4/TGzDmYw3RhnkJGtLhbnnA/5qJj7x3dNDCRx/PJxu774LlH8lCOlB4hEfKg==
+  dependencies:
+    napi-postinstall "^0.3.0"
+  optionalDependencies:
+    "@unrs/resolver-binding-android-arm-eabi" "1.11.1"
+    "@unrs/resolver-binding-android-arm64" "1.11.1"
+    "@unrs/resolver-binding-darwin-arm64" "1.11.1"
+    "@unrs/resolver-binding-darwin-x64" "1.11.1"
+    "@unrs/resolver-binding-freebsd-x64" "1.11.1"
+    "@unrs/resolver-binding-linux-arm-gnueabihf" "1.11.1"
+    "@unrs/resolver-binding-linux-arm-musleabihf" "1.11.1"
+    "@unrs/resolver-binding-linux-arm64-gnu" "1.11.1"
+    "@unrs/resolver-binding-linux-arm64-musl" "1.11.1"
+    "@unrs/resolver-binding-linux-ppc64-gnu" "1.11.1"
+    "@unrs/resolver-binding-linux-riscv64-gnu" "1.11.1"
+    "@unrs/resolver-binding-linux-riscv64-musl" "1.11.1"
+    "@unrs/resolver-binding-linux-s390x-gnu" "1.11.1"
+    "@unrs/resolver-binding-linux-x64-gnu" "1.11.1"
+    "@unrs/resolver-binding-linux-x64-musl" "1.11.1"
+    "@unrs/resolver-binding-wasm32-wasi" "1.11.1"
+    "@unrs/resolver-binding-win32-arm64-msvc" "1.11.1"
+    "@unrs/resolver-binding-win32-ia32-msvc" "1.11.1"
+    "@unrs/resolver-binding-win32-x64-msvc" "1.11.1"
+
+update-browserslist-db@^1.2.0:
+  version "1.2.3"
+  resolved "https://registry.yarnpkg.com/update-browserslist-db/-/update-browserslist-db-1.2.3.tgz#64d76db58713136acbeb4c49114366cc6cc2e80d"
+  integrity sha512-Js0m9cx+qOgDxo0eMiFGEueWztz+d4+M3rGlmKPT+T4IS/jP4ylw3Nwpu6cpTTP8R1MAC1kF4VbdLt3ARf209w==
+  dependencies:
+    escalade "^3.2.0"
+    picocolors "^1.1.1"
+
 uri-js@^4.2.2:
   version "4.4.1"
   resolved "https://registry.yarnpkg.com/uri-js/-/uri-js-4.4.1.tgz#9b1a52595225859e55f669d928f88c6c57f2a77e"
@@ -3156,11 +5045,27 @@ v8-compile-cache-lib@^3.0.1:
   resolved "https://registry.yarnpkg.com/v8-compile-cache-lib/-/v8-compile-cache-lib-3.0.1.tgz#6336e8d71965cb3d35a1bbb7868445a7c05264bf"
   integrity sha512-wa7YjyUGfNZngI/vtK0UHAN+lgDCxBPCylVXGp0zu59Fz5aiGtNXaq3DhIov063MorB+VfufLh3JlF2KdTK3xg==
 
+v8-to-istanbul@^9.0.1:
+  version "9.3.0"
+  resolved "https://registry.yarnpkg.com/v8-to-istanbul/-/v8-to-istanbul-9.3.0.tgz#b9572abfa62bd556c16d75fdebc1a411d5ff3175"
+  integrity sha512-kiGUalWN+rgBJ/1OHZsBtU4rXZOfj/7rKQxULKlIzwzQSvMJUUNgPwJEEh7gU6xEVxC0ahoOBvN2YI8GH6FNgA==
+  dependencies:
+    "@jridgewell/trace-mapping" "^0.3.12"
+    "@types/istanbul-lib-coverage" "^2.0.1"
+    convert-source-map "^2.0.0"
+
 vary@^1, vary@^1.1.2:
   version "1.1.2"
   resolved "https://registry.yarnpkg.com/vary/-/vary-1.1.2.tgz#2299f02c6ded30d4a5961b0b9f74524a18f634fc"
   integrity sha512-BNGbWLfd0eUPabhkXUVm0j8uuvREyTh5ovRa/dyow/BqAbZJyC+5fU+IzQOzmAKzYqYRAISoRhdQr3eIZ/PXqg==
 
+walker@^1.0.8:
+  version "1.0.8"
+  resolved "https://registry.yarnpkg.com/walker/-/walker-1.0.8.tgz#bd498db477afe573dc04185f011d3ab8a8d7653f"
+  integrity sha512-ts/8E8l5b7kY0vlWLewOkDXMmPdLcVV4GmOQLyxuSswIJsweeFZtAsMF7k1Nszz+TYBQrlYRmzOnr398y1JemQ==
+  dependencies:
+    makeerror "1.0.12"
+
 wcwidth@^1.0.1:
   version "1.0.1"
   resolved "https://registry.yarnpkg.com/wcwidth/-/wcwidth-1.0.1.tgz#f0b0dcf915bc5ff1528afadb2c0e17b532da2fe8"
@@ -3205,6 +5110,11 @@ word-wrap@^1.2.5:
   resolved "https://registry.yarnpkg.com/word-wrap/-/word-wrap-1.2.5.tgz#d2c45c6dd4fbce621a66f136cbe328afd0410b34"
   integrity sha512-BN22B5eaMMI9UMtjrGd5g5eCYPpCPDUy0FJXbYsaT5zYxjFOckS53SQDE3pWkVoWpHXVb3BrYcEN4Twa55B5cA==
 
+wordwrap@^1.0.0:
+  version "1.0.0"
+  resolved "https://registry.yarnpkg.com/wordwrap/-/wordwrap-1.0.0.tgz#27584810891456a4171c8d0226441ade90cbcaeb"
+  integrity sha512-gvVzJFlPycKc5dZN4yPkP8w7Dc37BtP1yczEneOb4uq34pXZcvrtRTmWV8W+Ume+XCxKgbjM+nevkyFPMybd4Q==
+
 "wrap-ansi-cjs@npm:wrap-ansi@^7.0.0":
   version "7.0.0"
   resolved "https://registry.yarnpkg.com/wrap-ansi/-/wrap-ansi-7.0.0.tgz#67e145cff510a6a6984bdf1152911d69d2eb9e43"
@@ -3246,6 +5156,14 @@ wrappy@1:
   resolved "https://registry.yarnpkg.com/wrappy/-/wrappy-1.0.2.tgz#b5243d8f3ec1aa35f1364605bc0d1036e30ab69f"
   integrity sha512-l4Sp/DRseor9wL6EvV2+TuQn63dMkPjZ/sp9XkghTEbV9KlPS1xUsZ3u7/IQO4wxtcFB4bgpQPRcR3QCvezPcQ==
 
+write-file-atomic@^5.0.1:
+  version "5.0.1"
+  resolved "https://registry.yarnpkg.com/write-file-atomic/-/write-file-atomic-5.0.1.tgz#68df4717c55c6fa4281a7860b4c2ba0a6d2b11e7"
+  integrity sha512-+QU2zd6OTD8XWIJCbffaiQeH9U73qIqafo1x6V1snCWYGJf6cVE0cDR4D8xRzcEnfI21IFrUPzPGtcPf8AC+Rw==
+  dependencies:
+    imurmurhash "^0.1.4"
+    signal-exit "^4.0.1"
+
 ws@^8.18.0:
   version "8.18.3"
   resolved "https://registry.yarnpkg.com/ws/-/ws-8.18.3.tgz#b56b88abffde62791c639170400c93dcb0c95472"
@@ -3269,6 +5187,34 @@ xmlbuilder@~11.0.0:
   resolved "https://registry.yarnpkg.com/xmlbuilder/-/xmlbuilder-11.0.1.tgz#be9bae1c8a046e76b31127726347d0ad7002beb3"
   integrity sha512-fDlsI/kFEx7gLvbecc0/ohLG50fugQp8ryHzMTuW9vSa1GJ0XYWKnhsUx7oie3G98+r56aTQIUB4kht42R3JvA==
 
+y18n@^5.0.5:
+  version "5.0.8"
+  resolved "https://registry.yarnpkg.com/y18n/-/y18n-5.0.8.tgz#7f4934d0f7ca8c56f95314939ddcd2dd91ce1d55"
+  integrity sha512-0pfFzegeDWJHJIAmTLRP2DwHjdF5s7jo9tuztdQxAhINCdvS+3nGINqPd00AphqJR/0LhANUS6/+7SCb98YOfA==
+
+yallist@^3.0.2:
+  version "3.1.1"
+  resolved "https://registry.yarnpkg.com/yallist/-/yallist-3.1.1.tgz#dbb7daf9bfd8bac9ab45ebf602b8cbad0d5d08fd"
+  integrity sha512-a4UGQaWPH59mOXUYnAG2ewncQS4i4F43Tv3JoAM+s2VDAmS9NsK8GpDMLrCHPksFT7h3K6TOoUNn2pb7RoXx4g==
+
+yargs-parser@^21.1.1:
+  version "21.1.1"
+  resolved "https://registry.yarnpkg.com/yargs-parser/-/yargs-parser-21.1.1.tgz#9096bceebf990d21bb31fa9516e0ede294a77d35"
+  integrity sha512-tVpsJW7DdjecAiFpbIB1e3qxIQsE6NoPc5/eTdrbbIC4h0LVsWhnoa3g+m2HclBIujHzsxZ4VJVA+GUuc2/LBw==
+
+yargs@^17.7.2:
+  version "17.7.2"
+  resolved "https://registry.yarnpkg.com/yargs/-/yargs-17.7.2.tgz#991df39aca675a192b816e1e0363f9d75d2aa269"
+  integrity sha512-7dSzzRQ++CKnNI/krKnYRV7JKKPUXMEh61soaHKg9mrWEhzFWhFnxPxGl+69cD1Ou63C13NUPCnmIcrvqCuM6w==
+  dependencies:
+    cliui "^8.0.1"
+    escalade "^3.1.1"
+    get-caller-file "^2.0.5"
+    require-directory "^2.1.1"
+    string-width "^4.2.3"
+    y18n "^5.0.5"
+    yargs-parser "^21.1.1"
+
 yn@3.1.1:
   version "3.1.1"
   resolved "https://registry.yarnpkg.com/yn/-/yn-3.1.1.tgz#1e87401a09d767c1d5eab26a6e4c185182d2eb50"