usertester 0.1.0

package/dist/orchestrator/retry.js

@@ -0,0 +1,145 @@
+/**
+ * Autonomous retry loop with failure classification.
+ *
+ * After each failed agent.execute() call:
+ * 1. Classifies WHY it failed (TRANSIENT / WRONG_APPROACH / CAPABILITY_GAP / ENVIRONMENT_BLOCK)
+ * 2. Decides recovery strategy
+ * 3. Retries with adjusted instruction or new tools injected
+ * 4. Stops when: completed, or max attempts reached
+ *
+ * Based on: Meta-Harness (arxiv:2603.28052) + Live-SWE-agent (arxiv:2511.13646)
+ * Key principle: raw trace beats summaries for classification (never summarize before classifying)
+ */
+import { cheapCall } from '../llm/provider.js';
+import { readInboxEmail } from '../tools/inbox.js';
+import { solveTurnstile, capsolverAvailable } from '../tools/captcha.js';
+export const MAX_ATTEMPTS = 5;
+// Signal patterns that map to failure types
+export const FAILURE_SIGNALS = [
+    {
+        pattern: /DNS|ERR_NAME_NOT_RESOLVED|net::ERR|could not resolve|unreachable/i,
+        type: 'WRONG_APPROACH',
+        hint: 'Do not navigate to external web UIs. Use available API tools instead.',
+    },
+    {
+        pattern: /verification code|6.digit|magic link|check.*email|inbox|sent.*code/i,
+        type: 'CAPABILITY_GAP',
+        hint: 'Use the readInboxEmail tool to retrieve the verification code from the email inbox.',
+    },
+    {
+        pattern: /only request this after (\d+)|too many requests|rate.?limit|429|resend.*after/i,
+        type: 'RATE_LIMITED',
+        hint: 'Rate limited — wait the specified cooldown period before retrying.',
+    },
+    {
+        pattern: /timeout|503|temporarily unavailable|connection failed/i,
+        type: 'TRANSIENT',
+        hint: 'Transient error — retry the same approach after a short wait.',
+    },
+    {
+        pattern: /captcha|CAPTCHA|bot detection|unusual traffic/i,
+        type: 'ENVIRONMENT_BLOCK',
+        hint: 'CAPTCHA detected — cannot automate this step.',
+    },
+];
+export async function classifyFailure(agentMessage, config) {
+    // Fast path: check signal patterns first (no LLM needed)
+    for (const { pattern, type, hint } of FAILURE_SIGNALS) {
+        if (pattern.test(agentMessage)) {
+            return { type, evidence: agentMessage.slice(0, 200), recoveryHint: hint };
+        }
+    }
+    // Slow path: ask the cheap model to classify
+    const prompt = `You are classifying why a browser automation agent failed.
+
+Agent failure message:
+${agentMessage.slice(0, 800)}
+
+Classify into exactly one of:
+- COMPLETE: the task actually succeeded (agent was wrong about failing)
+- TRANSIENT: network timeout, rate limit, temporary error — retry same approach
+- WRONG_APPROACH: agent used wrong method (e.g. navigated to web UI instead of using API)
+- CAPABILITY_GAP: agent knew what it needed but lacked a tool to do it
+- ENVIRONMENT_BLOCK: CAPTCHA, auth wall, or structural blocker — cannot automate
+- ESCALATE: unclear or unrecoverable
+
+Reply with JSON: {"type": "...", "evidence": "one sentence", "recoveryHint": "one sentence"}`;
+    try {
+        const text = await cheapCall(prompt, config, 150);
+        const match = text.match(/\{[\s\S]*\}/);
+        if (match) {
+            const parsed = JSON.parse(match[0]);
+            return {
+                type: parsed.type,
+                evidence: parsed.evidence ?? '',
+                recoveryHint: parsed.recoveryHint ?? '',
+            };
+        }
+    }
+    catch { }
+    return { type: 'ESCALATE', evidence: agentMessage.slice(0, 100), recoveryHint: 'Manual intervention needed' };
+}
+// Build a ToolSet to inject based on failure classification
+export function selectToolsForRecovery(classification) {
+    const tools = {};
+    if (classification.type === 'CAPABILITY_GAP' ||
+        (classification.type === 'WRONG_APPROACH' && /email|inbox|code|verification/i.test(classification.evidence))) {
+        tools['readInboxEmail'] = readInboxEmail;
+    }
+    // ENVIRONMENT_BLOCK from CAPTCHA: inject solver if CapSolver is configured
+    if (classification.type === 'ENVIRONMENT_BLOCK' &&
+        /captcha|turnstile|cloudflare|verify.*human/i.test(classification.evidence) &&
+        capsolverAvailable()) {
+        tools['solveTurnstile'] = solveTurnstile;
+    }
+    return tools;
+}
+// Build a constraint addendum to inject into the next attempt's instruction
+export function buildRetryInstruction(originalInstruction, history, memory, currentUrl) {
+    // --- Recovery tip takes priority over failure constraints ---
+    if (memory?.recoveryTips?.length && currentUrl) {
+        const tip = memory.recoveryTips.find(t => {
+            try {
+                return currentUrl.includes(new URL(t.url).hostname) || t.url.includes(currentUrl);
+            }
+            catch {
+                return false;
+            }
+        });
+        if (tip) {
+            return [
+                `App URL: ${currentUrl} — navigate here if the page is blank or shows an error.`,
+                ``,
+                `PROVEN APPROACH FOR THIS APP:`,
+                `The following approach previously succeeded (tools: ${tip.toolsUsed.join(', ') || 'none'}):`,
+                `"${tip.successApproach}"`,
+                ``,
+                `REPEAT this approach exactly. Ignore any previous context suggesting otherwise.`,
+                ``,
+                `Task: ${originalInstruction}`,
+            ].join('\n');
+        }
+    }
+    // --- Fallback: accumulate failure constraints (existing behavior) ---
+    if (history.length === 0)
+        return originalInstruction;
+    const constraints = history
+        .filter(a => a.failureType && a.failureType !== 'TRANSIENT' && a.failureType !== 'COMPLETE')
+        .map((a) => `Attempt ${a.attempt} failed (${a.failureType}): ${a.agentMessage.slice(0, 150)}`);
+    if (constraints.length === 0)
+        return originalInstruction;
+    const toolHints = history.some(a => a.toolsInjected.includes('readInboxEmail'))
+        ? '\n\nIMPORTANT: You have a readInboxEmail tool available. Use it to read any verification emails — do NOT try to navigate to a web-based inbox.'
+        : '';
+    // Always pin the URL so the agent never guesses if navigation fails
+    const urlPin = currentUrl ? `\nApp URL: ${currentUrl} — always navigate here first if the page is blank or shows an error.` : '';
+    return [
+        originalInstruction,
+        urlPin,
+        '',
+        '--- Previous attempt context ---',
+        ...constraints,
+        toolHints,
+    ].join('\n');
+}
+//# sourceMappingURL=retry.js.map

package/dist/orchestrator/retry.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"retry.js","sourceRoot":"","sources":["../../src/orchestrator/retry.ts"],"names":[],"mappings":"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"}

package/dist/orchestrator/session.d.ts

@@ -0,0 +1,13 @@
+import type { SessionState, AgentState, AgentStatus } from '../types.js';
+export declare function createSession(opts: {
+    resultsDir: string;
+    sessionId: string;
+    url: string;
+    agentIds: string[];
+}): SessionState;
+export declare function getStatePath(resultsDir: string, sessionId: string): string;
+export declare function saveSession(resultsDir: string, state: SessionState): void;
+export declare function loadSession(resultsDir: string, sessionId: string): SessionState | null;
+export declare function updateAgent(state: SessionState, agentId: string, updates: Partial<AgentState>): SessionState;
+export declare function transitionAgent(state: SessionState, agentId: string, to: AgentStatus, extras?: Partial<AgentState>): SessionState;
+export declare function resolveSessionId(resultsDir: string, sessionId?: string): string | null;

package/dist/orchestrator/session.js

@@ -0,0 +1,55 @@
+/**
+ * Session state management
+ * Reads/writes ~/.usertester/<session-id>/state.json (atomic)
+ */
+import path from 'node:path';
+import fs from 'node:fs';
+import { writeStateAtomic, readState, getSessionDir } from '../output/events.js';
+export function createSession(opts) {
+    const agents = opts.agentIds.map(id => ({
+        id,
+        status: 'QUEUED',
+        updatedAt: Date.now(),
+        retryCount: 0,
+    }));
+    return {
+        sessionId: opts.sessionId,
+        url: opts.url,
+        agents,
+        startedAt: Date.now(),
+    };
+}
+export function getStatePath(resultsDir, sessionId) {
+    return path.join(getSessionDir(resultsDir, sessionId), 'state.json');
+}
+export function saveSession(resultsDir, state) {
+    writeStateAtomic(getStatePath(resultsDir, state.sessionId), state);
+}
+export function loadSession(resultsDir, sessionId) {
+    return readState(getStatePath(resultsDir, sessionId));
+}
+export function updateAgent(state, agentId, updates) {
+    return {
+        ...state,
+        agents: state.agents.map(a => a.id === agentId
+            ? { ...a, ...updates, updatedAt: Date.now() }
+            : a),
+    };
+}
+export function transitionAgent(state, agentId, to, extras) {
+    return updateAgent(state, agentId, { status: to, ...extras });
+}
+export function resolveSessionId(resultsDir, sessionId) {
+    if (sessionId)
+        return sessionId;
+    // Read current symlink
+    try {
+        const currentLink = path.join(resultsDir, 'current');
+        const target = fs.readlinkSync(currentLink);
+        return path.basename(target);
+    }
+    catch {
+        return null;
+    }
+}
+//# sourceMappingURL=session.js.map

package/dist/orchestrator/session.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"session.js","sourceRoot":"","sources":["../../src/orchestrator/session.ts"],"names":[],"mappings":"AAAA;;;GAGG;AACH,OAAO,IAAI,MAAM,WAAW,CAAA;AAC5B,OAAO,EAAE,MAAM,SAAS,CAAA;AAExB,OAAO,EAAE,gBAAgB,EAAE,SAAS,EAAE,aAAa,EAAE,MAAM,qBAAqB,CAAA;AAEhF,MAAM,UAAU,aAAa,CAAC,IAK7B;IACC,MAAM,MAAM,GAAiB,IAAI,CAAC,QAAQ,CAAC,GAAG,CAAC,EAAE,CAAC,EAAE,CAAC,CAAC;QACpD,EAAE;QACF,MAAM,EAAE,QAAQ;QAChB,SAAS,EAAE,IAAI,CAAC,GAAG,EAAE;QACrB,UAAU,EAAE,CAAC;KACd,CAAC,CAAC,CAAA;IAEH,OAAO;QACL,SAAS,EAAE,IAAI,CAAC,SAAS;QACzB,GAAG,EAAE,IAAI,CAAC,GAAG;QACb,MAAM;QACN,SAAS,EAAE,IAAI,CAAC,GAAG,EAAE;KACtB,CAAA;AACH,CAAC;AAED,MAAM,UAAU,YAAY,CAAC,UAAkB,EAAE,SAAiB;IAChE,OAAO,IAAI,CAAC,IAAI,CAAC,aAAa,CAAC,UAAU,EAAE,SAAS,CAAC,EAAE,YAAY,CAAC,CAAA;AACtE,CAAC;AAED,MAAM,UAAU,WAAW,CAAC,UAAkB,EAAE,KAAmB;IACjE,gBAAgB,CAAC,YAAY,CAAC,UAAU,EAAE,KAAK,CAAC,SAAS,CAAC,EAAE,KAAK,CAAC,CAAA;AACpE,CAAC;AAED,MAAM,UAAU,WAAW,CAAC,UAAkB,EAAE,SAAiB;IAC/D,OAAO,SAAS,CAAe,YAAY,CAAC,UAAU,EAAE,SAAS,CAAC,CAAC,CAAA;AACrE,CAAC;AAED,MAAM,UAAU,WAAW,CACzB,KAAmB,EACnB,OAAe,EACf,OAA4B;IAE5B,OAAO;QACL,GAAG,KAAK;QACR,MAAM,EAAE,KAAK,CAAC,MAAM,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,CAC3B,CAAC,CAAC,EAAE,KAAK,OAAO;YACd,CAAC,CAAC,EAAE,GAAG,CAAC,EAAE,GAAG,OAAO,EAAE,SAAS,EAAE,IAAI,CAAC,GAAG,EAAE,EAAE;YAC7C,CAAC,CAAC,CAAC,CACN;KACF,CAAA;AACH,CAAC;AAED,MAAM,UAAU,eAAe,CAC7B,KAAmB,EACnB,OAAe,EACf,EAAe,EACf,MAA4B;IAE5B,OAAO,WAAW,CAAC,KAAK,EAAE,OAAO,EAAE,EAAE,MAAM,EAAE,EAAE,EAAE,GAAG,MAAM,EAAE,CAAC,CAAA;AAC/D,CAAC;AAED,MAAM,UAAU,gBAAgB,CAAC,UAAkB,EAAE,SAAkB;IACrE,IAAI,SAAS;QAAE,OAAO,SAAS,CAAA;IAC/B,uBAAuB;IACvB,IAAI,CAAC;QACH,MAAM,WAAW,GAAG,IAAI,CAAC,IAAI,CAAC,UAAU,EAAE,SAAS,CAAC,CAAA;QACpD,MAAM,MAAM,GAAG,EAAE,CAAC,YAAY,CAAC,WAAW,CAAW,CAAA;QACrD,OAAO,IAAI,CAAC,QAAQ,CAAC,MAAM,CAAC,CAAA;IAC9B,CAAC;IAAC,MAAM,CAAC;QACP,OAAO,IAAI,CAAA;IACb,CAAC;AACH,CAAC"}

package/dist/output/events.d.ts

@@ -0,0 +1,12 @@
+import type { UsertesterEvent } from '../types.js';
+export declare function emitEvent(event: UsertesterEvent): void;
+export declare function ts(): string;
+export declare function appendAgentEvent(agentDir: string, data: Record<string, unknown>): void;
+export declare function appendAgentLog(agentDir: string, message: string): void;
+export declare function writeStateAtomic(statePath: string, state: unknown): void;
+export declare function readState<T>(statePath: string): T | null;
+export declare function readPendingCommand(commandsPath: string): import('../types.js').AgentCommand | null;
+export declare function writeCommand(commandsPath: string, cmd: import('../types.js').AgentCommand): void;
+export declare function getSessionDir(resultsDir: string, sessionId: string): string;
+export declare function getAgentDir(sessionDir: string, agentId: string): string;
+export declare function initSessionDirs(resultsDir: string, sessionId: string, agentIds: string[]): void;

package/dist/output/events.js

@@ -0,0 +1,81 @@
+/**
+ * NDJSON event emitter + per-agent event log writer
+ */
+import fs from 'node:fs';
+import path from 'node:path';
+export function emitEvent(event) {
+    process.stdout.write(JSON.stringify(event) + '\n');
+}
+export function ts() {
+    return new Date().toISOString();
+}
+// --- Per-agent event log (push model) ---
+export function appendAgentEvent(agentDir, data) {
+    const logPath = path.join(agentDir, 'events.ndjson');
+    fs.appendFileSync(logPath, JSON.stringify({ ...data, ts: ts() }) + '\n');
+}
+export function appendAgentLog(agentDir, message) {
+    const logPath = path.join(agentDir, 'agent.log');
+    fs.appendFileSync(logPath, `[${ts()}] ${message}\n`);
+}
+// --- State file (atomic write) ---
+export function writeStateAtomic(statePath, state) {
+    const tmp = statePath + '.tmp';
+    fs.writeFileSync(tmp, JSON.stringify(state, null, 2));
+    fs.renameSync(tmp, statePath);
+}
+export function readState(statePath) {
+    try {
+        return JSON.parse(fs.readFileSync(statePath, 'utf-8'));
+    }
+    catch {
+        return null;
+    }
+}
+// --- Command mailbox ---
+export function readPendingCommand(commandsPath) {
+    try {
+        const content = fs.readFileSync(commandsPath, 'utf-8').trim();
+        if (!content)
+            return null;
+        const lines = content.split('\n').filter(Boolean);
+        if (lines.length === 0)
+            return null;
+        // Read last command
+        const cmd = JSON.parse(lines[lines.length - 1]);
+        // Clear the file after reading
+        fs.writeFileSync(commandsPath, '');
+        return cmd;
+    }
+    catch {
+        return null;
+    }
+}
+export function writeCommand(commandsPath, cmd) {
+    fs.appendFileSync(commandsPath, JSON.stringify(cmd) + '\n');
+}
+// --- Session dir layout ---
+export function getSessionDir(resultsDir, sessionId) {
+    return path.join(resultsDir, sessionId);
+}
+export function getAgentDir(sessionDir, agentId) {
+    return path.join(sessionDir, agentId);
+}
+export function initSessionDirs(resultsDir, sessionId, agentIds) {
+    const sessionDir = getSessionDir(resultsDir, sessionId);
+    fs.mkdirSync(sessionDir, { recursive: true });
+    for (const agentId of agentIds) {
+        const agentDir = getAgentDir(sessionDir, agentId);
+        fs.mkdirSync(path.join(agentDir, 'screenshots'), { recursive: true });
+        // Create empty command mailbox
+        fs.writeFileSync(path.join(agentDir, 'commands.ndjson'), '');
+    }
+    // Symlink ~/.usertester/current → latest session
+    const currentLink = path.join(resultsDir, 'current');
+    try {
+        fs.unlinkSync(currentLink);
+    }
+    catch { }
+    fs.symlinkSync(sessionDir, currentLink);
+}
+//# sourceMappingURL=events.js.map

package/dist/output/events.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"events.js","sourceRoot":"","sources":["../../src/output/events.ts"],"names":[],"mappings":"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"}

package/dist/profiles/learner.d.ts

@@ -0,0 +1,4 @@
+import type { ProfileFacts, SessionMemory, RecoveryTip } from '../types.js';
+export declare function loadProfile(resultsDir: string, url: string, scenario: string): ProfileFacts | null;
+export declare function updateProfile(resultsDir: string, url: string, scenario: string, memory: SessionMemory): Promise<void>;
+export declare function updateProfileWithSuccess(resultsDir: string, tip: RecoveryTip): Promise<void>;

package/dist/profiles/learner.js

@@ -0,0 +1,168 @@
+/**
+ * Profile meta-learning system
+ *
+ * After each session, extract reusable observations from session memory
+ * and persist them as facts.json per (url, scenario).
+ *
+ * Next run: agent loads these hints via BrowserAgent.start(profileFacts).
+ * Repeated failures become high-confidence hints ("avoid CAPTCHA on form submit").
+ *
+ * Inspired by the meta-harness paper (arxiv:2603.28052): post-session outer loop
+ * that reads execution traces and updates the harness config.
+ */
+import path from 'node:path';
+import fs from 'node:fs';
+import { cheapCall } from '../llm/provider.js';
+const PROFILES_DIR_NAME = 'profiles';
+function profileKey(url, scenario) {
+    // Stable key from url domain + scenario
+    const domain = new URL(url).hostname.replace(/\./g, '_');
+    return `${domain}_${scenario}`;
+}
+function getProfilePath(resultsDir, url, scenario) {
+    const profilesDir = path.join(resultsDir, PROFILES_DIR_NAME);
+    fs.mkdirSync(profilesDir, { recursive: true });
+    return path.join(profilesDir, `${profileKey(url, scenario)}.json`);
+}
+export function loadProfile(resultsDir, url, scenario) {
+    const profilePath = getProfilePath(resultsDir, url, scenario);
+    try {
+        return JSON.parse(fs.readFileSync(profilePath, 'utf-8'));
+    }
+    catch {
+        return null;
+    }
+}
+export async function updateProfile(resultsDir, url, scenario, memory) {
+    const profilePath = getProfilePath(resultsDir, url, scenario);
+    const existing = loadProfile(resultsDir, url, scenario) ?? {
+        url,
+        scenario,
+        harnessHints: [],
+        runCount: 0,
+        lastRunAt: Date.now(),
+    };
+    const failedActions = memory.actions.filter(a => a.result === 'failed');
+    if (failedActions.length === 0 && existing.harnessHints.length > 0) {
+        // Perfect run — bump confidence on existing hints, update run count
+        existing.runCount++;
+        existing.lastRunAt = Date.now();
+        existing.harnessHints = existing.harnessHints.map(h => ({
+            ...h,
+            confidence: Math.min(1.0, h.confidence + 0.1),
+        }));
+        writeProfileAtomic(profilePath, existing);
+        return;
+    }
+    // Extract new hints from failures using LLM
+    const failuresStr = failedActions
+        .slice(0, 10)
+        .map(a => `- ${a.action}: ${a.observation}`)
+        .join('\n');
+    let newHints = [];
+    try {
+        const responseText = await cheapCall(`You are analyzing failed browser automation actions to extract reusable hints for future runs.
+
+URL: ${url}
+Scenario: ${scenario}
+Failed actions:
+${failuresStr}
+
+Extract 1-3 brief, actionable hints that would help future automation avoid these failures.
+Each hint should be a concrete observation (e.g., "CAPTCHA appears after 3rd form submit attempt").
+Reply with JSON array: [{"observation": "...", "confidence": 0.7}]
+Only include hints where confidence >= 0.5.`, undefined, 400);
+        const match = responseText.match(/\[[\s\S]*\]/);
+        if (match) {
+            const parsed = JSON.parse(match[0]);
+            newHints = parsed.map(h => ({
+                observation: h.observation,
+                confidence: Math.min(1.0, Math.max(0.0, h.confidence)),
+                addedAt: Date.now(),
+            }));
+        }
+    }
+    catch {
+        // Learner failures are non-fatal
+    }
+    // Merge: update confidence on existing similar hints, add new ones
+    const updated = mergeHints(existing.harnessHints, newHints);
+    const profile = {
+        ...existing,
+        harnessHints: updated,
+        runCount: existing.runCount + 1,
+        lastRunAt: Date.now(),
+    };
+    writeProfileAtomic(profilePath, profile);
+}
+function mergeHints(existing, newHints) {
+    const merged = [...existing];
+    for (const hint of newHints) {
+        // Check for similar existing hint (simple substring match)
+        const similar = merged.findIndex(h => h.observation.toLowerCase().includes(hint.observation.toLowerCase().slice(0, 20)));
+        if (similar >= 0) {
+            // Boost confidence
+            merged[similar] = {
+                ...merged[similar],
+                confidence: Math.min(1.0, merged[similar].confidence + 0.15),
+            };
+        }
+        else {
+            merged.push(hint);
+        }
+    }
+    // Keep top 10 by confidence, prune low-confidence stale hints
+    return merged
+        .filter(h => h.confidence > 0.3)
+        .sort((a, b) => b.confidence - a.confidence)
+        .slice(0, 10);
+}
+export async function updateProfileWithSuccess(resultsDir, tip) {
+    const profilePath = getProfilePath(resultsDir, tip.url, tip.scenario);
+    const existing = loadProfile(resultsDir, tip.url, tip.scenario) ?? {
+        url: tip.url,
+        scenario: tip.scenario,
+        harnessHints: [],
+        runCount: 0,
+        lastRunAt: Date.now(),
+    };
+    // MemCollab intersection: discard hints that contradict the proven approach
+    // A hint contradicts if it recommends an approach NOT used in the success
+    const filteredHints = existing.harnessHints.filter(hint => {
+        // Discard hints that recommend approaches explicitly absent from success
+        const contradicts = hint.observation.toLowerCase().includes('password instead') &&
+            !tip.successApproach.toLowerCase().includes('password');
+        return !contradicts;
+    });
+    // Add recovery tip as top-priority hint
+    const recoveryHint = {
+        observation: `PROVEN APPROACH: ${tip.successApproach.slice(0, 300)}. Tools that worked: ${tip.toolsUsed.join(', ') || 'none'}.`,
+        confidence: 0.97,
+        addedAt: tip.ts,
+    };
+    // Merge: recovery tip first, then filtered existing hints, deduped
+    const merged = [recoveryHint, ...filteredHints]
+        .filter(h => h.confidence > 0.3)
+        .sort((a, b) => b.confidence - a.confidence)
+        .slice(0, 5); // Keep only top 5 — K=3-5 is empirically sufficient
+    const profile = {
+        ...existing,
+        harnessHints: merged,
+        runCount: existing.runCount + 1,
+        lastRunAt: Date.now(),
+    };
+    writeProfileAtomic(profilePath, profile);
+}
+function extractKeywords(text) {
+    // Extract meaningful action words — naive but effective for O(1) comparison
+    const stopwords = new Set(['the', 'a', 'an', 'and', 'or', 'but', 'in', 'on', 'at', 'to', 'for', 'with', 'by']);
+    return text.toLowerCase()
+        .split(/\W+/)
+        .filter(w => w.length > 3 && !stopwords.has(w));
+}
+function writeProfileAtomic(profilePath, profile) {
+    const tmp = profilePath + '.tmp';
+    fs.writeFileSync(tmp, JSON.stringify(profile, null, 2));
+    fs.renameSync(tmp, profilePath);
+}
+//# sourceMappingURL=learner.js.map

package/dist/profiles/learner.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"learner.js","sourceRoot":"","sources":["../../src/profiles/learner.ts"],"names":[],"mappings":"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"}

package/dist/tools/captcha.d.ts

@@ -0,0 +1,19 @@
+import { z } from 'zod';
+import type { Tool } from 'ai';
+declare const captchaParams: z.ZodObject<{
+    pageURL: z.ZodString;
+    siteKey: z.ZodOptional<z.ZodString>;
+}, z.core.$strip>;
+type CaptchaParams = z.infer<typeof captchaParams>;
+type CaptchaResult = {
+    solved: true;
+    token: string;
+    type: string;
+} | {
+    solved: false;
+    error: string;
+    hint: string;
+};
+export declare const solveTurnstile: Tool<CaptchaParams, CaptchaResult>;
+export declare function capsolverAvailable(): boolean;
+export {};

package/dist/tools/captcha.js

@@ -0,0 +1,76 @@
+import { z } from 'zod';
+const captchaParams = z.object({
+    pageURL: z.string().describe('The full URL of the page showing the CAPTCHA'),
+    siteKey: z.string().optional().describe('Cloudflare Turnstile site key (found in page source). Leave empty to auto-detect.'),
+});
+export const solveTurnstile = {
+    description: `Solve a Cloudflare Turnstile CAPTCHA using the CapSolver API.
+Use this when you see a "Verify you are human" challenge blocking form submission.
+Returns a token you can inject into the page to bypass the challenge.
+Only works if CAPSOLVER_API_KEY is configured — check first before calling.`,
+    inputSchema: captchaParams,
+    execute: async ({ pageURL, siteKey }) => {
+        const apiKey = process.env.CAPSOLVER_API_KEY;
+        if (!apiKey) {
+            return {
+                solved: false,
+                error: 'CAPSOLVER_API_KEY not configured',
+                hint: 'Add CAPSOLVER_API_KEY to .env, or configure X-Usertester-Session WAF bypass in Cloudflare instead (recommended).',
+            };
+        }
+        try {
+            // CapSolver REST API — no SDK needed, direct HTTP is cleaner
+            const createTask = await fetch('https://api.capsolver.com/createTask', {
+                method: 'POST',
+                headers: { 'Content-Type': 'application/json' },
+                body: JSON.stringify({
+                    clientKey: apiKey,
+                    task: {
+                        type: 'AntiTurnstileTaskProxyLess',
+                        websiteURL: pageURL,
+                        websiteKey: siteKey ?? '0x4AAAAAAADnPIDROrmt1Wwj', // Cloudflare default demo key fallback
+                    },
+                }),
+            }).then(r => r.json());
+            if (!createTask.taskId) {
+                return {
+                    solved: false,
+                    error: createTask.errorDescription ?? 'Task creation failed',
+                    hint: 'Check CAPSOLVER_API_KEY balance and validity.',
+                };
+            }
+            // Poll for result (Turnstile typically solves in 5-15 seconds)
+            const deadline = Date.now() + 60_000;
+            while (Date.now() < deadline) {
+                await new Promise(r => setTimeout(r, 3000));
+                const result = await fetch('https://api.capsolver.com/getTaskResult', {
+                    method: 'POST',
+                    headers: { 'Content-Type': 'application/json' },
+                    body: JSON.stringify({ clientKey: apiKey, taskId: createTask.taskId }),
+                }).then(r => r.json());
+                if (result.status === 'ready' && result.solution?.token) {
+                    return {
+                        solved: true,
+                        token: result.solution.token,
+                        type: 'AntiTurnstileTaskProxyLess',
+                    };
+                }
+                if (result.status === 'failed' || result.errorCode) {
+                    return {
+                        solved: false,
+                        error: result.errorDescription ?? 'Solve failed',
+                        hint: 'Turnstile may be in hardened mode. Try configuring X-Usertester-Session WAF bypass instead.',
+                    };
+                }
+            }
+            return { solved: false, error: 'Timeout waiting for CAPTCHA solve', hint: 'CapSolver took >60s' };
+        }
+        catch (err) {
+            return { solved: false, error: String(err), hint: 'CapSolver API request failed' };
+        }
+    },
+};
+export function capsolverAvailable() {
+    return !!process.env.CAPSOLVER_API_KEY;
+}
+//# sourceMappingURL=captcha.js.map

package/dist/tools/captcha.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"captcha.js","sourceRoot":"","sources":["../../src/tools/captcha.ts"],"names":[],"mappings":"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"}

package/dist/tools/inbox.d.ts

@@ -0,0 +1,30 @@
+/**
+ * readInboxEmail tool — lets the browser agent read emails via AgentMail API
+ * instead of trying to navigate to a web inbox (which fails DNS).
+ *
+ * Used by the retry loop when it detects a CAPABILITY_GAP around email reading.
+ * Injected into Stagehand via stagehand.agent({ tools: { readInboxEmail } })
+ */
+import { z } from 'zod';
+import type { Tool } from 'ai';
+declare const inboxParams: z.ZodObject<{
+    inboxId: z.ZodString;
+    subjectContains: z.ZodOptional<z.ZodString>;
+    waitMinutes: z.ZodOptional<z.ZodNumber>;
+}, z.core.$strip>;
+type InboxParams = z.infer<typeof inboxParams>;
+type InboxResult = {
+    found: false;
+    error: string;
+} | {
+    found: false;
+    message: string;
+} | {
+    found: true;
+    subject?: string;
+    snippet?: string;
+    verificationCodes: string[];
+    primaryCode: string | null;
+};
+export declare const readInboxEmail: Tool<InboxParams, InboxResult>;
+export {};