usertester 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 usertester contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,219 @@
+# usertester
+
+Spawn N AI agents as simulated users to test your web app flows — signup, onboarding, checkout, email verification — in parallel, with real email inboxes and natural language control.
+
+```
+usertester spawn --url https://myapp.com --n 3 --message "Sign up as a new user"
+```
+
+Each agent gets a unique email inbox, runs a headless browser, and executes your task as a first-time user. You watch a live NDJSON event stream. When an agent finishes, send it a follow-up task — the browser session stays open.
+
+---
+
+## Install
+
+```bash
+npm install -g usertester
+```
+
+Or run without installing:
+
+```bash
+npx usertester setup
+```
+
+You need Node.js 20+ and Google Chrome installed locally.
+
+---
+
+## Quick start
+
+**Step 1 — Get two API keys**
+
+- Anthropic API key: https://console.anthropic.com/settings/keys
+- AgentMail API key: https://agentmail.to/dashboard
+
+**Step 2 — Configure**
+
+```bash
+usertester setup
+```
+
+Prompts for both keys, validates them live, writes `.env`.
+
+**Step 3 — Spawn agents**
+
+```bash
+usertester spawn --url https://yourapp.com --n 1 --message "Sign up as a new user"
+```
+
+Output (NDJSON, one event per line):
+
+```jsonl
+{"event":"session_start","sessionId":"abc123","url":"https://yourapp.com","n":1}
+{"event":"spawned","agent":"agent-01","inbox":"abc@agentmail.to"}
+{"event":"state","agent":"agent-01","from":"SIGNING_UP","to":"RUNNING"}
+{"event":"ready","agent":"agent-01","message_completed":"Sign up as a new user","summary":"Filled the registration form and clicked Register. Signup succeeded and was redirected to the dashboard.","screenshot":"/Users/you/.usertester/abc123/agent-01/screenshots/001.png"}
+```
+
+**Step 4 — Send follow-up tasks**
+
+While an agent is in `WAITING` state, send it a new task — the browser session stays open:
+
+```bash
+usertester send agent-01 "Go to the pricing page and try to upgrade to the Pro plan"
+```
+
+---
+
+## Commands
+
+```bash
+usertester setup                              # First-run API key configuration
+usertester spawn --url URL --n N --message M  # Spawn N agents with a shared task
+usertester spawn --url URL --messages-file tasks.json  # Per-agent tasks from file
+usertester status                             # Show all agents + current state
+usertester send <agent-id> <message>          # Resume a waiting agent with a new task
+usertester kill <agent-id>                    # Kill a running or waiting agent
+usertester logs <agent-id> [--follow]         # Tail an agent's log
+usertester cleanup                            # Delete all AgentMail inboxes for current session
+usertester cleanup --all                      # Clean up all sessions
+usertester profiles list                      # Show learned profile hints per URL/scenario
+```
+
+---
+
+## Per-agent task file
+
+```json
+[
+  { "message": "Sign up as a new user and complete onboarding" },
+  { "message": "Sign up, then try to upgrade to the paid plan" },
+  { "message": "Sign up using Google OAuth if available" }
+]
+```
+
+If the file has fewer entries than `--n`, tasks cycle.
+
+---
+
+## How it works
+
+1. **Inbox provisioning** — each agent gets a unique `@agentmail.to` email address (~135ms)
+2. **Browser agent** — headless Chrome via Stagehand v3, controlled by `claude-opus-4-6`
+3. **Multi-step execution** — `agent().execute()` runs an observe→act→check loop until the task completes
+4. **RLM memory** — session history is queried in chunks rather than fed whole into context. Cost stays near-flat as sessions grow.
+5. **Profile learning** — after each session, failures are extracted into `facts.json` per URL/scenario. Next run, the agent starts with those hints.
+6. **NDJSON event stream** — every state transition and result is a JSON line to stdout. Calling agents (Claude Code, etc.) parse this to decide next steps.
+
+---
+
+## Bypassing bot detection (Cloudflare, CAPTCHA)
+
+usertester injects an `x-usertester-session: 1` header on every request. Configure your app to allow this traffic through.
+
+### Option A: Cloudflare WAF bypass (recommended, free)
+
+**Step 1 — Generate a secret bypass token:**
+```bash
+openssl rand -hex 24   # → e.g. a3f9c2b8d7e14f6a9c2b8d7e14f6a9c2b8d7e14f
+```
+
+**Step 2 — Add it to your `.env`:**
+```
+USERTESTER_BYPASS_TOKEN=a3f9c2b8d7e14f6a9c2b8d7e14f6a9c2b8d7e14f
+```
+
+**Step 3 — Add a WAF rule in Cloudflare dashboard → Security → WAF → Custom rules:**
+```
+Field:      Request Header
+Header:     x-usertester-bypass
+Operator:   equals
+Value:      a3f9c2b8d7e14f6a9c2b8d7e14f6a9c2b8d7e14f   ← your secret
+Action:     Skip → All remaining custom rules
+```
+
+The token is never in source code — only in your `.env` and Cloudflare dashboard. Rotate it anytime by generating a new one and updating both places.
+
+### Option B: Supabase Auth — use Cloudflare test keys
+
+If your app uses Supabase Auth with Cloudflare Turnstile:
+
+1. Supabase dashboard → **Authentication → Security → CAPTCHA protection**
+2. Switch site key to: `1x00000000000000000000AA` (Cloudflare's official test key — always passes)
+3. Switch secret key to: `1x0000000000000000000000000000000AA`
+
+Use only in dev/staging — not production.
+
+### Option C: Automatic CAPTCHA solving (no app changes, paid)
+
+Add `CAPSOLVER_API_KEY` to `.env` and usertester will automatically solve Cloudflare Turnstile via [CapSolver](https://capsolver.com) (~$1.20/1K solves, ~85-90% success rate).
+
+```bash
+CAPSOLVER_API_KEY=CAP-...
+```
+
+---
+
+## Calling from a coding agent
+
+usertester is designed to be orchestrated by a coding agent (Claude Code, Codex) as well as used directly. Parse the NDJSON stream:
+
+```typescript
+import { spawn } from 'node:child_process'
+import * as readline from 'node:readline'
+
+const proc = spawn('usertester', ['spawn', '--url', url, '--n', '3', '--message', task])
+const rl = readline.createInterface({ input: proc.stdout })
+
+rl.on('line', (line) => {
+  const event = JSON.parse(line)
+  if (event.event === 'ready') {
+    // agent.summary tells you what happened
+    // send next task:
+    spawn('usertester', ['send', event.agent, 'Next task here'])
+  }
+})
+```
+
+---
+
+## Limits
+
+| | Free plan | Paid plan |
+|---|---|---|
+| AgentMail inboxes | 3 simultaneous | Unlimited |
+| Agents per session | 3 | Up to 20 (configurable) |
+
+Always run `usertester cleanup` between sessions to free inbox slots on the free plan.
+
+---
+
+## Results
+
+After a session, results are saved to `~/.usertester/<session-id>/`:
+
+```
+~/.usertester/<session-id>/
+├── state.json              # Live session + agent states
+├── agent-01/
+│   ├── agent.log           # Full agent activity log
+│   ├── events.ndjson       # Structured event history
+│   └── screenshots/        # Screenshots per task
+└── ...
+```
+
+---
+
+## Requirements
+
+- Node.js 20+
+- Google Chrome (for local browser automation)
+- Anthropic API key
+- AgentMail API key
+
+---
+
+## License
+
+MIT

package/dist/browser/agent.d.ts

@@ -0,0 +1,33 @@
+import type { SessionMemory, ProfileFacts, UsertesterConfig } from '../types.js';
+import type { RetryAttempt } from '../orchestrator/retry.js';
+export interface ResumeResult {
+    summary: string;
+    screenshotPath: string;
+}
+export declare class BrowserAgent {
+    private stagehand;
+    private config;
+    private memory;
+    private agentDir;
+    private screenshotIndex;
+    private rlmRecentActions;
+    private rlmMaxFailedActions;
+    private retryHistory;
+    constructor(opts: {
+        config: Partial<UsertesterConfig>;
+        agentDir: string;
+        rlmRecentActions?: number;
+        rlmMaxFailedActions?: number;
+    });
+    start(url: string, inbox: string, initialTask: string, profileHints?: ProfileFacts): Promise<void>;
+    resume(task: string): Promise<ResumeResult>;
+    exportMemory(): SessionMemory;
+    exportRetryHistory(): RetryAttempt[];
+    destroy(): Promise<void>;
+    private buildRLMContext;
+    private llmBatch;
+    private executeTask;
+    private recordAction;
+    private takeScreenshot;
+    private summarizeLastTask;
+}

package/dist/browser/agent.js

@@ -0,0 +1,393 @@
+/**
+ * BrowserAgent: Stagehand v3 wrapper with RLM memory loop
+ *
+ * Implements the BrowserAgent interface from the design doc:
+ *   start(url, inbox, initialTask, profileHints?) → void
+ *   resume(task) → ResumeResult
+ *   exportMemory() → SessionMemory
+ *   destroy() → void
+ */
+import { Stagehand } from '@browserbasehq/stagehand';
+import path from 'node:path';
+import { appendAgentEvent, appendAgentLog } from '../output/events.js';
+import { cheapCall, cheapBatch } from '../llm/provider.js';
+import { classifyFailure, selectToolsForRecovery, buildRetryInstruction } from '../orchestrator/retry.js';
+const ARCHIVE_THRESHOLD = 50;
+const ARCHIVE_BATCH = 10;
+export class BrowserAgent {
+    stagehand = null;
+    config;
+    memory;
+    agentDir;
+    screenshotIndex = 0;
+    rlmRecentActions;
+    rlmMaxFailedActions;
+    retryHistory = [];
+    constructor(opts) {
+        this.config = opts.config;
+        this.agentDir = opts.agentDir;
+        this.rlmRecentActions = opts.rlmRecentActions ?? 10;
+        this.rlmMaxFailedActions = opts.rlmMaxFailedActions ?? 5;
+        this.memory = {
+            taskDescription: '',
+            startUrl: '',
+            actions: [],
+            archivedActionCount: 0,
+            recoveryTips: [],
+        };
+    }
+    async start(url, inbox, initialTask, profileHints) {
+        this.memory.taskDescription = initialTask;
+        this.memory.startUrl = url;
+        // Use Stagehand's native model config (provider/model format + apiKey)
+        // This is the format confirmed working from spike tests
+        const cuaModelString = this.config.cua_model ?? 'anthropic/claude-opus-4-6';
+        // Strip 'openrouter/' prefix — Stagehand uses provider/model directly
+        const stagehandModelName = cuaModelString.startsWith('openrouter/')
+            ? cuaModelString.slice('openrouter/'.length)
+            : cuaModelString;
+        const apiKey = this.config.anthropic_api_key
+            ?? this.config.openrouter_api_key
+            ?? this.config.openai_api_key
+            ?? process.env.ANTHROPIC_API_KEY
+            ?? process.env.OPENROUTER_API_KEY
+            ?? '';
+        const useBrowserbase = !!(this.config.browserbase_api_key && this.config.browserbase_project_id);
+        if (useBrowserbase) {
+            appendAgentLog(this.agentDir, `Using Browserbase (project: ${this.config.browserbase_project_id})`);
+            this.stagehand = new Stagehand({
+                env: 'BROWSERBASE',
+                apiKey: this.config.browserbase_api_key,
+                projectId: this.config.browserbase_project_id,
+                verbose: 0,
+                model: { modelName: stagehandModelName, apiKey },
+                logger: () => { },
+                experimental: true,
+                disableAPI: true,
+            });
+        }
+        else {
+            appendAgentLog(this.agentDir, `Using local Chrome (headless)`);
+            this.stagehand = new Stagehand({
+                env: 'LOCAL',
+                verbose: 0,
+                model: { modelName: stagehandModelName, apiKey },
+                localBrowserLaunchOptions: { headless: true },
+                logger: () => { },
+                experimental: true,
+                disableAPI: true,
+            });
+        }
+        await this.stagehand.init();
+        const page = this.stagehand.context.pages()[0];
+        // Inject customer-specific bypass token if configured.
+        // Customers add a WAF rule: (http.request.headers["x-usertester-bypass"] eq "<their-token>") → Skip
+        // The token is secret — read from USERTESTER_BYPASS_TOKEN env, never hardcoded.
+        const bypassToken = this.config.bypass_token;
+        if (bypassToken) {
+            await page.setExtraHTTPHeaders({ 'x-usertester-bypass': bypassToken });
+        }
+        appendAgentLog(this.agentDir, `Browser started. Navigating to ${url}`);
+        appendAgentEvent(this.agentDir, { event: 'browser_started', url });
+        await page.goto(url, { waitUntil: 'load' });
+        // Build initial system context including profile hints.
+        // If a high-confidence recovery tip exists (proven approach), use it exclusively —
+        // contradictory lower-confidence hints are excluded to avoid confusing the agent.
+        const provenApproach = profileHints?.harnessHints.find(h => h.confidence >= 0.95 && h.observation.startsWith('PROVEN APPROACH'));
+        const hintLines = provenApproach
+            ? `- ${provenApproach.observation}`
+            : profileHints?.harnessHints
+                .filter(h => h.confidence > 0.5)
+                .map(h => `- ${h.observation}`)
+                .join('\n');
+        const systemContext = [
+            `You are testing this web app as a first-time user.`,
+            `Your email address is: ${inbox}`,
+            `Your task: ${initialTask}`,
+            `Navigate the app, complete the task, and note anything confusing, broken, or unclear.`,
+            `Do not skip steps. Use the email ${inbox} when asked for an email.`,
+            `If verification fails and you need to resend a code, wait for any cooldown timer shown before clicking Resend. Then call readInboxEmail again to get the new code.`,
+            hintLines ? `\nKnown context from previous runs:\n${hintLines}` : '',
+        ]
+            .filter(Boolean)
+            .join('\n');
+        appendAgentLog(this.agentDir, `Starting task: ${initialTask}`);
+        // Pre-inject tools from recovery tip on attempt 1.
+        // The profile's PROVEN APPROACH hint records which tools worked — inject them immediately
+        // so the agent doesn't waste attempt 1 discovering it needs them.
+        const attempt1Tools = {};
+        const { readInboxEmail } = await import('../tools/inbox.js');
+        const provenHint = profileHints?.harnessHints.find(h => h.confidence >= 0.95 && h.observation.startsWith('PROVEN APPROACH'));
+        if (provenHint?.observation.includes('readInboxEmail')) {
+            attempt1Tools['readInboxEmail'] = readInboxEmail;
+            appendAgentLog(this.agentDir, `Pre-injecting readInboxEmail from profile recovery tip`);
+        }
+        this.retryHistory = [];
+        let result = await this.executeTask(systemContext, initialTask, attempt1Tools);
+        if (!result.completed) {
+            for (let attempt = 2; attempt <= 5; attempt++) {
+                const classification = await classifyFailure(result.message, this.config);
+                appendAgentLog(this.agentDir, `Retry ${attempt}: classified as ${classification.type} — ${classification.recoveryHint}`);
+                this.retryHistory.push({
+                    attempt: attempt - 1,
+                    instruction: initialTask,
+                    toolsInjected: [],
+                    result: 'failed',
+                    failureType: classification.type,
+                    agentMessage: result.message,
+                    finalUrl: result.finalUrl,
+                });
+                if (classification.type === 'COMPLETE')
+                    break;
+                if (classification.type === 'ESCALATE')
+                    break;
+                // RATE_LIMITED: wait the app's specified cooldown then retry
+                if (classification.type === 'RATE_LIMITED') {
+                    const secondsMatch = result.message.match(/only request this after (\d+)|wait (\d+) second/i);
+                    const waitSeconds = secondsMatch
+                        ? parseInt(secondsMatch[1] ?? secondsMatch[2], 10)
+                        : 90; // default to 90s if we can't parse
+                    appendAgentLog(this.agentDir, `  Rate limited — waiting ${waitSeconds}s before retry`);
+                    await new Promise(r => setTimeout(r, waitSeconds * 1000));
+                }
+                // ENVIRONMENT_BLOCK: only break if no solver tool available for it
+                if (classification.type === 'ENVIRONMENT_BLOCK') {
+                    const recoveryTools = selectToolsForRecovery(classification);
+                    if (Object.keys(recoveryTools).length === 0)
+                        break; // no tool can help
+                }
+                if (classification.type === 'TRANSIENT' && attempt > 3)
+                    break;
+                const tools = selectToolsForRecovery(classification);
+                const retryInstruction = buildRetryInstruction(initialTask, this.retryHistory, this.memory, url);
+                appendAgentLog(this.agentDir, `  injecting tools: ${Object.keys(tools).join(', ') || 'none'}`);
+                result = await this.executeTask(systemContext, retryInstruction, tools);
+                if (result.completed) {
+                    appendAgentLog(this.agentDir, `✓ Retry ${attempt} succeeded`);
+                    const tip = {
+                        url: this.memory.startUrl,
+                        scenario: 'signup',
+                        failedApproaches: this.retryHistory
+                            .filter(a => a.result === 'failed')
+                            .map(a => a.agentMessage.slice(0, 150)),
+                        successApproach: result.message.slice(0, 400),
+                        toolsUsed: Object.keys(tools),
+                        finalUrl: result.finalUrl,
+                        confidence: 0.95,
+                        ts: Date.now(),
+                    };
+                    this.memory.recoveryTips.push(tip);
+                    appendAgentEvent(this.agentDir, { event: 'recovery_tip_written', tip });
+                    appendAgentLog(this.agentDir, `Recovery tip stored: ${tip.successApproach.slice(0, 80)}`);
+                    break;
+                }
+            }
+        }
+    }
+    async resume(task) {
+        if (!this.stagehand)
+            throw new Error('BrowserAgent not started');
+        const context = await this.buildRLMContext(task);
+        appendAgentLog(this.agentDir, `Resuming with task: ${task}`);
+        appendAgentLog(this.agentDir, `RLM context: ${context.slice(0, 200)}...`);
+        await this.executeTask(context, task, {});
+        const screenshotPath = await this.takeScreenshot();
+        const summary = await this.summarizeLastTask(task);
+        return { summary, screenshotPath };
+    }
+    exportMemory() {
+        return { ...this.memory, actions: [...this.memory.actions] };
+    }
+    exportRetryHistory() {
+        return [...this.retryHistory];
+    }
+    async destroy() {
+        if (this.stagehand) {
+            await this.stagehand.close();
+            this.stagehand = null;
+        }
+    }
+    // --- Private: RLM context builder ---
+    async buildRLMContext(nextTask) {
+        const page = this.stagehand.context.pages()[0];
+        const currentUrl = page.url();
+        const recentWindow = this.memory.actions.slice(-this.rlmRecentActions);
+        const failedWindow = this.memory.actions
+            .filter(a => a.result === 'failed')
+            .slice(-this.rlmMaxFailedActions);
+        const [recentContext, failureContext] = await this.llmBatch([
+            {
+                data: recentWindow,
+                prompt: 'What is the current browser state and what has the agent done most recently?',
+            },
+            {
+                data: failedWindow,
+                prompt: 'What has failed before that the agent should avoid repeating?',
+            },
+        ]);
+        return [
+            `You are a browser automation agent testing a web app.`,
+            `Current URL: ${currentUrl}`,
+            `Next task: ${nextTask}`,
+            `Total actions taken so far: ${this.memory.actions.length + this.memory.archivedActionCount}`,
+            `Recent state: ${recentContext}`,
+            failureContext !== '(no data)' ? `Things to avoid: ${failureContext}` : null,
+        ]
+            .filter(Boolean)
+            .join('\n');
+    }
+    async llmBatch(queries) {
+        const prompts = queries.map(({ data, prompt }) => {
+            if (data.length === 0)
+                return null;
+            const dataStr = data
+                .map(a => `${a.action} → ${a.result}${a.observation ? ` | ${a.observation}` : ''}`)
+                .join('\n');
+            return `${prompt}\n\nActions:\n${dataStr}\n\nAnswer in 1-2 sentences.`;
+        });
+        return Promise.all(prompts.map(async (p) => {
+            if (p === null)
+                return '(no data)';
+            const text = await cheapBatch([p], this.config, 150);
+            return text[0] || '(no data)';
+        }));
+    }
+    // --- Private: task execution ---
+    async executeTask(systemContext, task, tools = {}) {
+        if (!this.stagehand)
+            throw new Error('Stagehand not initialized');
+        const page = this.stagehand.context.pages()[0];
+        const startUrl = page.url();
+        const fullInstruction = systemContext ? `${systemContext}\n\nTask: ${task}` : task;
+        try {
+            // Tools are passed to stagehand.agent() config, not to execute()
+            const agentConfig = {};
+            if (Object.keys(tools).length > 0) {
+                agentConfig.tools = tools;
+            }
+            const agent = this.stagehand.agent(agentConfig);
+            const result = await agent.execute({ instruction: fullInstruction, maxSteps: 15 });
+            await page.waitForLoadState('load').catch(() => { });
+            const newUrl = page.url();
+            appendAgentLog(this.agentDir, `agent.execute() completed: ${result.completed ? 'done' : 'incomplete'}`);
+            appendAgentLog(this.agentDir, `  steps: ${result.actions?.length ?? 0}, tools injected: ${Object.keys(tools).join(', ') || 'none'}`);
+            appendAgentLog(this.agentDir, `  message: ${result.message}`);
+            appendAgentLog(this.agentDir, `  final url: ${newUrl}`);
+            // Record each step as an ActionRecord for RLM memory
+            for (const action of (result.actions ?? [])) {
+                this.recordAction({
+                    ts: Date.now(),
+                    action: action.type ?? 'unknown',
+                    result: 'success',
+                    observation: action.reasoning ?? undefined,
+                    url: startUrl,
+                });
+            }
+            // Record overall outcome with agent's message as observation
+            this.recordAction({
+                ts: Date.now(),
+                action: task.slice(0, 100),
+                result: result.completed ? 'success' : 'failed',
+                observation: result.message ?? (newUrl !== startUrl ? `Navigated to ${newUrl}` : `Stayed on ${startUrl}`),
+                url: startUrl,
+            });
+            return { completed: result.completed, message: result.message ?? '', finalUrl: newUrl };
+        }
+        catch (err) {
+            appendAgentLog(this.agentDir, `agent.execute() failed: ${err}`);
+            // Fallback: individual act() calls per observed action
+            let allActions = [];
+            try {
+                allActions = await this.stagehand.observe();
+            }
+            catch { }
+            if (allActions.length > 0) {
+                appendAgentLog(this.agentDir, `Falling back to ${allActions.length} individual act() calls`);
+                for (const action of allActions.slice(0, 5)) {
+                    try {
+                        await this.stagehand.act(action.description);
+                        await page.waitForLoadState('load').catch(() => { });
+                        this.recordAction({
+                            ts: Date.now(),
+                            action: action.description,
+                            selector: action.selector,
+                            result: 'success',
+                            url: startUrl,
+                        });
+                        appendAgentLog(this.agentDir, `  ok ${action.description}`);
+                    }
+                    catch (err2) {
+                        this.recordAction({
+                            ts: Date.now(),
+                            action: action.description,
+                            selector: action.selector,
+                            result: 'failed',
+                            observation: String(err2),
+                            url: startUrl,
+                        });
+                        appendAgentLog(this.agentDir, `  fail ${action.description}: ${err2}`);
+                    }
+                }
+            }
+            else {
+                this.recordAction({
+                    ts: Date.now(),
+                    action: task.slice(0, 100),
+                    result: 'failed',
+                    observation: String(err),
+                    url: startUrl,
+                });
+            }
+            return { completed: false, message: String(err), finalUrl: page.url() };
+        }
+    }
+    recordAction(action) {
+        this.memory.actions.push(action);
+        appendAgentEvent(this.agentDir, { event: 'action', ...action });
+        // Archive oldest actions when exceeding threshold (RLM memory management)
+        if (this.memory.actions.length > ARCHIVE_THRESHOLD) {
+            const archived = this.memory.actions.splice(0, ARCHIVE_BATCH);
+            this.memory.archivedActionCount += archived.length;
+            appendAgentEvent(this.agentDir, {
+                event: 'actions_archived',
+                count: archived.length,
+                total_archived: this.memory.archivedActionCount,
+                actions: archived,
+            });
+        }
+    }
+    async takeScreenshot() {
+        if (!this.stagehand)
+            return '';
+        this.screenshotIndex++;
+        const screenshotDir = path.join(this.agentDir, 'screenshots');
+        const filename = `${String(this.screenshotIndex).padStart(3, '0')}.png`;
+        const screenshotPath = path.join(screenshotDir, filename);
+        try {
+            const page = this.stagehand.context.pages()[0];
+            await page.screenshot({ path: screenshotPath });
+            appendAgentLog(this.agentDir, `Screenshot saved: ${filename}`);
+        }
+        catch (err) {
+            appendAgentLog(this.agentDir, `Screenshot failed: ${err}`);
+        }
+        return screenshotPath;
+    }
+    async summarizeLastTask(task) {
+        const recentActions = this.memory.actions.slice(-10);
+        if (recentActions.length === 0)
+            return 'No actions recorded.';
+        const actionsStr = recentActions
+            .map(a => `${a.action} → ${a.result}${a.observation ? ` (${a.observation})` : ''}`)
+            .join('\n');
+        const prompt = `Task: "${task}"\n\nActions taken:\n${actionsStr}\n\nSummarize in 1-2 sentences: what happened, did the task complete, and anything confusing or broken?`;
+        try {
+            const text = await cheapCall(prompt, this.config, 200);
+            return text || 'Task execution complete.';
+        }
+        catch {
+            return `Completed ${recentActions.filter(a => a.result === 'success').length}/${recentActions.length} actions.`;
+        }
+    }
+}
+//# sourceMappingURL=agent.js.map