HyperAgent core robustness

.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

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`.

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.