usertester 0.1.0

package/dist/tools/inbox.js

@@ -0,0 +1,65 @@
+/**
+ * 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 { AgentMailClient } from 'agentmail';
+const inboxParams = z.object({
+    inboxId: z.string().describe('The full inbox email address, e.g. ut-abc123@agentmail.to'),
+    subjectContains: z.string().optional().describe('Optional: filter by subject keyword, e.g. "verification" or "code"'),
+    waitMinutes: z.number().optional().describe('How many minutes to wait for the email to arrive. Default: 2.'),
+});
+export const readInboxEmail = {
+    description: `Read emails from an AgentMail inbox using the API.
+Use this when you need to retrieve a verification code, magic link, or any email sent to your inbox.
+Do NOT try to navigate to a web-based email client — use this tool instead.
+Returns the email subject, body snippet, and any 6-digit codes found.`,
+    inputSchema: inboxParams,
+    execute: async ({ inboxId, subjectContains, waitMinutes = 2 }) => {
+        const apiKey = process.env.AGENTMAIL_API_KEY;
+        if (!apiKey)
+            return { found: false, error: 'AGENTMAIL_API_KEY not set' };
+        const client = new AgentMailClient({ apiKey });
+        const deadline = Date.now() + waitMinutes * 60 * 1000;
+        while (Date.now() < deadline) {
+            try {
+                const threads = await client.inboxes.threads.list(inboxId);
+                // AgentMail API returns { count, threads: [...] }
+                const items = (threads.threads ?? threads.items ?? []);
+                for (const thread of items) {
+                    if (subjectContains && !thread.subject?.toLowerCase().includes(subjectContains.toLowerCase())) {
+                        continue;
+                    }
+                    // Fetch full thread to get message HTML (snippet is often undefined)
+                    const detail = await client.inboxes.threads.get(inboxId, thread.threadId);
+                    const msg = detail.messages?.[0];
+                    const fullText = JSON.stringify(msg ?? '');
+                    // Extract 6-digit verification codes — filter out obvious template placeholders
+                    const allCodes = fullText.match(/\b\d{6}\b/g) ?? [];
+                    // De-duplicate and filter repeated filler codes (e.g. 333333, 666666)
+                    const codes = [...new Set(allCodes)].filter(c => !/^(\d)\1{5}$/.test(c));
+                    return {
+                        found: true,
+                        subject: thread.subject,
+                        snippet: (msg?.extractedHtml ?? msg?.html ?? '').slice(0, 200),
+                        verificationCodes: codes,
+                        primaryCode: codes[0] ?? null,
+                    };
+                }
+            }
+            catch (err) {
+                return { found: false, error: String(err) };
+            }
+            // Wait 5 seconds before polling again
+            await new Promise(r => setTimeout(r, 5000));
+        }
+        return {
+            found: false,
+            message: `No email found in ${inboxId} after ${waitMinutes} minutes`,
+        };
+    },
+};
+//# sourceMappingURL=inbox.js.map

package/dist/tools/inbox.js.map

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

package/dist/types.d.ts

@@ -0,0 +1,121 @@
+/**
+ * Shared types for usertester-agent
+ */
+export type AgentStatus = 'QUEUED' | 'SPAWNING' | 'INBOX_READY' | 'SIGNING_UP' | 'RUNNING' | 'WAITING' | 'DONE' | 'FAILED' | 'CANCELLED';
+export interface AgentState {
+    id: string;
+    status: AgentStatus;
+    inboxId?: string;
+    currentMessage?: string;
+    startedAt?: number;
+    updatedAt: number;
+    error?: string;
+    lastScreenshot?: string;
+    retryCount: number;
+}
+export interface SessionState {
+    sessionId: string;
+    url: string;
+    agents: AgentState[];
+    startedAt: number;
+    completedAt?: number;
+}
+export interface ActionRecord {
+    ts: number;
+    action: string;
+    selector?: string;
+    result: 'success' | 'failed' | 'skipped';
+    observation?: string;
+    url?: string;
+}
+export interface RecoveryTip {
+    url: string;
+    scenario: string;
+    failedApproaches: string[];
+    successApproach: string;
+    toolsUsed: string[];
+    finalUrl: string;
+    confidence: number;
+    ts: number;
+}
+export interface SessionMemory {
+    taskDescription: string;
+    startUrl: string;
+    actions: ActionRecord[];
+    archivedActionCount: number;
+    recoveryTips: RecoveryTip[];
+}
+export interface HarnessHint {
+    observation: string;
+    confidence: number;
+    addedAt: number;
+}
+export interface ProfileFacts {
+    url: string;
+    scenario: string;
+    harnessHints: HarnessHint[];
+    runCount: number;
+    lastRunAt: number;
+}
+export type UsertesterEvent = {
+    event: 'session_start';
+    sessionId: string;
+    url: string;
+    n: number;
+    ts: string;
+} | {
+    event: 'spawned';
+    agent: string;
+    inbox: string;
+    ts: string;
+} | {
+    event: 'state';
+    agent: string;
+    from: AgentStatus;
+    to: AgentStatus;
+    message?: string;
+    ts: string;
+} | {
+    event: 'ready';
+    agent: string;
+    message_completed: string;
+    summary: string;
+    screenshot?: string;
+    ts: string;
+} | {
+    event: 'failed';
+    agent: string;
+    error: string;
+    ts: string;
+} | {
+    event: 'session_complete';
+    sessionId: string;
+    ts: string;
+};
+export interface AgentCommand {
+    type: 'send' | 'kill';
+    message?: string;
+    issuedAt: number;
+}
+export interface UsertesterConfig {
+    agentmail_api_key?: string;
+    anthropic_api_key?: string;
+    openrouter_api_key?: string;
+    openai_api_key?: string;
+    /** Customer-specific secret for Cloudflare WAF bypass. Never hardcoded — read from env only. */
+    bypass_token?: string;
+    browserbase_api_key?: string;
+    browserbase_project_id?: string;
+    cua_backend: 'stagehand';
+    max_agents: number;
+    cua_concurrency_limit: number;
+    agent_timeout_ms: number;
+    screenshot_interval_ms: number;
+    results_dir: string;
+    rlm_recent_actions: number;
+    rlm_max_failed_actions: number;
+    orchestrator_model: string;
+    cua_model: string;
+    proposer_model: string;
+}
+export declare const DEFAULT_CONFIG: UsertesterConfig;

package/dist/types.js

@@ -0,0 +1,30 @@
+/**
+ * Shared types for usertester-agent
+ */
+export const DEFAULT_CONFIG = {
+    agentmail_api_key: process.env.AGENTMAIL_API_KEY,
+    anthropic_api_key: process.env.ANTHROPIC_API_KEY,
+    openrouter_api_key: process.env.OPENROUTER_API_KEY,
+    openai_api_key: process.env.OPENAI_API_KEY,
+    bypass_token: process.env.USERTESTER_BYPASS_TOKEN,
+    browserbase_api_key: process.env.BROWSERBASE_API_KEY,
+    browserbase_project_id: process.env.BROWSERBASE_PROJECT_ID,
+    cua_backend: 'stagehand',
+    max_agents: 20,
+    cua_concurrency_limit: 5,
+    agent_timeout_ms: 300_000,
+    screenshot_interval_ms: 2_000,
+    results_dir: `${process.env.HOME}/.usertester`,
+    rlm_recent_actions: 10,
+    rlm_max_failed_actions: 5,
+    orchestrator_model: process.env.OPENROUTER_API_KEY
+        ? 'openrouter/openai/gpt-5.4-mini'
+        : 'anthropic/claude-haiku-4-5-20251001',
+    cua_model: process.env.OPENROUTER_API_KEY
+        ? 'openrouter/anthropic/claude-opus-4-6'
+        : 'anthropic/claude-opus-4-6',
+    proposer_model: process.env.OPENROUTER_API_KEY
+        ? 'openrouter/anthropic/claude-opus-4-6'
+        : 'anthropic/claude-opus-4-6',
+};
+//# sourceMappingURL=types.js.map

package/dist/types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.js","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":"AAAA;;GAEG;AA2HH,MAAM,CAAC,MAAM,cAAc,GAAqB;IAC9C,iBAAiB,EAAE,OAAO,CAAC,GAAG,CAAC,iBAAiB;IAChD,iBAAiB,EAAE,OAAO,CAAC,GAAG,CAAC,iBAAiB;IAChD,kBAAkB,EAAE,OAAO,CAAC,GAAG,CAAC,kBAAkB;IAClD,cAAc,EAAE,OAAO,CAAC,GAAG,CAAC,cAAc;IAC1C,YAAY,EAAE,OAAO,CAAC,GAAG,CAAC,uBAAuB;IACjD,mBAAmB,EAAE,OAAO,CAAC,GAAG,CAAC,mBAAmB;IACpD,sBAAsB,EAAE,OAAO,CAAC,GAAG,CAAC,sBAAsB;IAC1D,WAAW,EAAE,WAAW;IACxB,UAAU,EAAE,EAAE;IACd,qBAAqB,EAAE,CAAC;IACxB,gBAAgB,EAAE,OAAO;IACzB,sBAAsB,EAAE,KAAK;IAC7B,WAAW,EAAE,GAAG,OAAO,CAAC,GAAG,CAAC,IAAI,cAAc;IAC9C,kBAAkB,EAAE,EAAE;IACtB,sBAAsB,EAAE,CAAC;IACzB,kBAAkB,EAAE,OAAO,CAAC,GAAG,CAAC,kBAAkB;QAChD,CAAC,CAAC,gCAAgC;QAClC,CAAC,CAAC,qCAAqC;IACzC,SAAS,EAAE,OAAO,CAAC,GAAG,CAAC,kBAAkB;QACvC,CAAC,CAAC,sCAAsC;QACxC,CAAC,CAAC,2BAA2B;IAC/B,cAAc,EAAE,OAAO,CAAC,GAAG,CAAC,kBAAkB;QAC5C,CAAC,CAAC,sCAAsC;QACxC,CAAC,CAAC,2BAA2B;CAChC,CAAA"}

package/package.json

@@ -0,0 +1,60 @@
+{
+  "name": "usertester",
+  "version": "0.1.0",
+  "description": "Spawn N AI agents as simulated users to test web app flows",
+  "author": "Vishal Tandale",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/vishaltandale00/usertester.git"
+  },
+  "homepage": "https://github.com/vishaltandale00/usertester#readme",
+  "bugs": "https://github.com/vishaltandale00/usertester/issues",
+  "keywords": [
+    "testing",
+    "ai-agents",
+    "browser-automation",
+    "user-testing",
+    "qa",
+    "stagehand",
+    "e2e-testing",
+    "web-testing"
+  ],
+  "type": "module",
+  "bin": {
+    "usertester": "./dist/cli/index.js"
+  },
+  "files": [
+    "dist/",
+    "tasks.example.json",
+    "README.md",
+    "LICENSE"
+  ],
+  "engines": {
+    "node": ">=20"
+  },
+  "scripts": {
+    "build": "tsc && node -e \"require('fs').chmodSync('dist/cli/index.js',0o755)\" && echo 'bin ready: dist/cli/index.js'",
+    "dev": "tsx src/cli/index.ts",
+    "prepublishOnly": "npm run build",
+    "spike:stagehand": "tsx src/spikes/stagehand.ts",
+    "spike:agentmail": "tsx src/spikes/agentmail.ts",
+    "spike:rlm": "tsx src/spikes/rlm.ts"
+  },
+  "dependencies": {
+    "@anthropic-ai/sdk": "^0.54.0",
+    "@browserbasehq/stagehand": "^3.0.0",
+    "@captcha-libs/capsolver": "^2.1.1",
+    "@openrouter/ai-sdk-provider": "^1.5.0",
+    "agentmail": "^0.1.0",
+    "commander": "^12.0.0",
+    "dotenv": "^16.0.0",
+    "jiti": "^2.0.0",
+    "zod": "^4.3.6"
+  },
+  "devDependencies": {
+    "@types/node": "^22.0.0",
+    "tsx": "^4.0.0",
+    "typescript": "^5.0.0"
+  }
+}

package/tasks.example.json

@@ -0,0 +1,5 @@
+[
+  { "message": "Sign up as a new user and complete the full onboarding flow" },
+  { "message": "Sign up, then try to upgrade to the paid plan" },
+  { "message": "Sign up using Google OAuth if available, otherwise use the email form" }
+]