@appliqation/agent-core 0.1.0

package/dist/providers/openai.js

@@ -0,0 +1,87 @@
+import OpenAI from 'openai';
+export const DEFAULT_OPENAI_MODEL = 'gpt-5';
+function toResponsesInput(messages) {
+    const out = [];
+    for (const m of messages) {
+        if (m.role === 'user') {
+            out.push({ role: 'user', content: m.content });
+        }
+        else if (m.role === 'assistant') {
+            if (m.content)
+                out.push({ role: 'assistant', content: m.content });
+            for (const call of m.toolCalls ?? []) {
+                out.push({
+                    type: 'function_call',
+                    call_id: call.id,
+                    name: call.name,
+                    arguments: JSON.stringify(call.arguments),
+                });
+            }
+        }
+        else if (m.role === 'tool') {
+            out.push({ type: 'function_call_output', call_id: m.toolCallId ?? '', output: m.content });
+            // The Responses API's function_call_output is text-only — there's no
+            // way to attach an image to a tool result the way Anthropic's
+            // tool_result blocks allow. The documented workaround is a synthetic
+            // user message with input_image content immediately after the output
+            // — without this, an "image" is just a base64 blob sitting unseen in
+            // a JSON string, never actually shown to the model.
+            if (m.images?.length) {
+                out.push({
+                    role: 'user',
+                    content: m.images.map((img) => ({
+                        type: 'input_image',
+                        detail: 'auto',
+                        image_url: `data:${img.mimeType};base64,${img.data}`,
+                    })),
+                });
+            }
+        }
+    }
+    return out;
+}
+export function createOpenAiAdapter(apiKey, model = DEFAULT_OPENAI_MODEL, maxOutputTokens = 4096) {
+    const client = new OpenAI({ apiKey });
+    return {
+        async complete({ system, messages, tools, signal }) {
+            const response = await client.responses.create({
+                model,
+                max_output_tokens: maxOutputTokens,
+                instructions: system,
+                input: toResponsesInput(messages),
+                tools: tools.map((t) => ({
+                    type: 'function',
+                    name: t.name,
+                    description: t.description,
+                    parameters: t.inputSchema,
+                    strict: false,
+                })),
+            }, { signal });
+            let text = '';
+            const toolCalls = [];
+            for (const item of response.output) {
+                if (item.type === 'message') {
+                    for (const part of item.content) {
+                        if (part.type === 'output_text')
+                            text += part.text;
+                    }
+                }
+                else if (item.type === 'function_call') {
+                    toolCalls.push({
+                        id: item.call_id,
+                        name: item.name,
+                        arguments: JSON.parse(item.arguments || '{}'),
+                    });
+                }
+            }
+            return {
+                text,
+                toolCalls,
+                usage: response.usage
+                    ? { inputTokens: response.usage.input_tokens, outputTokens: response.usage.output_tokens }
+                    : undefined,
+            };
+        },
+    };
+}
+//# sourceMappingURL=openai.js.map

package/dist/providers/openai.js.map

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

package/dist/tools/apiTools.d.ts

@@ -0,0 +1,21 @@
+import type { APIRequestContext } from 'playwright';
+import type { LlmToolDef, ToolResult } from '../types.js';
+export declare const API_TOOL_DEFS: LlmToolDef[];
+export interface ApiRequestRecord {
+    method: string;
+    url: string;
+    status: number | null;
+    ok: boolean;
+    dryRunSuppressed: boolean;
+    timestamp: number;
+}
+/** Wraps a live Playwright APIRequestContext as an http_request tool dispatcher. */
+export declare class ApiRequestTools {
+    private readonly context;
+    private readonly dryRun;
+    private readonly requestHistory;
+    constructor(context: APIRequestContext, dryRun?: boolean);
+    getRequestHistory(): ApiRequestRecord[];
+    dispatch(name: string, args: Record<string, unknown>): Promise<ToolResult>;
+}
+//# sourceMappingURL=apiTools.d.ts.map

package/dist/tools/apiTools.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"apiTools.d.ts","sourceRoot":"","sources":["../../src/tools/apiTools.ts"],"names":[],"mappings":"AAaA,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,YAAY,CAAC;AACpD,OAAO,KAAK,EAAE,UAAU,EAAE,UAAU,EAAE,MAAM,aAAa,CAAC;AAI1D,eAAO,MAAM,aAAa,EAAE,UAAU,EAkBrC,CAAC;AAEF,MAAM,WAAW,gBAAgB;IAC/B,MAAM,EAAE,MAAM,CAAC;IACf,GAAG,EAAE,MAAM,CAAC;IACZ,MAAM,EAAE,MAAM,GAAG,IAAI,CAAC;IACtB,EAAE,EAAE,OAAO,CAAC;IACZ,gBAAgB,EAAE,OAAO,CAAC;IAC1B,SAAS,EAAE,MAAM,CAAC;CACnB;AAED,oFAAoF;AACpF,qBAAa,eAAe;IAIxB,OAAO,CAAC,QAAQ,CAAC,OAAO;IACxB,OAAO,CAAC,QAAQ,CAAC,MAAM;IAJzB,OAAO,CAAC,QAAQ,CAAC,cAAc,CAA0B;gBAGtC,OAAO,EAAE,iBAAiB,EAC1B,MAAM,GAAE,OAAe;IAG1C,iBAAiB,IAAI,gBAAgB,EAAE;IAIjC,QAAQ,CAAC,IAAI,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,OAAO,CAAC,UAAU,CAAC;CAuCjF"}

package/dist/tools/apiTools.js

@@ -0,0 +1,82 @@
+// The http_request tool palette — the API-testing counterpart to
+// browserTools.ts's browser_* tools. Structurally parallel on purpose: one
+// tool, backed by a real Playwright APIRequestContext (already a dependency
+// via the `playwright` package — no new one added for this), returning the
+// real status/headers/body as the tool result. Same "never fabricate, only
+// report what actually happened" discipline as every other tool in this
+// family.
+//
+// Write-verb gating (POST/PUT/PATCH/DELETE) is dry-run-aware by
+// construction, not bolted on after — this is the one place that knows a
+// request is about to have a real side effect, the same reasoning behind
+// browserTools.ts's destructive-action gate on browser_click.
+const WRITE_VERBS = new Set(['POST', 'PUT', 'PATCH', 'DELETE']);
+export const API_TOOL_DEFS = [
+    {
+        name: 'http_request',
+        description: 'Send a real HTTP request and return the real response (status, headers, body, duration). Use this for ' +
+            'every step of an API test case — no browser is offered for these. Write-verb requests ' +
+            '(POST/PUT/PATCH/DELETE) are suppressed and logged instead of sent when running in dry-run mode.',
+        inputSchema: {
+            type: 'object',
+            properties: {
+                method: { type: 'string', description: 'HTTP method, e.g. GET, POST, PUT, PATCH, DELETE.' },
+                url: { type: 'string', description: 'Absolute URL, or a path relative to the configured base URL.' },
+                headers: { type: 'object', description: 'Optional extra request headers.' },
+                body: { description: 'Optional request body — a JSON-serializable value, sent as the JSON request body.' },
+            },
+            required: ['method', 'url'],
+        },
+    },
+];
+/** Wraps a live Playwright APIRequestContext as an http_request tool dispatcher. */
+export class ApiRequestTools {
+    context;
+    dryRun;
+    requestHistory = [];
+    constructor(context, dryRun = false) {
+        this.context = context;
+        this.dryRun = dryRun;
+    }
+    getRequestHistory() {
+        return [...this.requestHistory];
+    }
+    async dispatch(name, args) {
+        if (name !== 'http_request')
+            return { ok: false, text: `Unknown API tool "${name}"` };
+        const method = String(args.method ?? 'GET').toUpperCase();
+        const url = String(args.url ?? '');
+        const headers = args.headers ?? undefined;
+        const body = args.body;
+        if (this.dryRun && WRITE_VERBS.has(method)) {
+            this.requestHistory.push({ method, url, status: null, ok: true, dryRunSuppressed: true, timestamp: Date.now() });
+            console.error(`[dry-run] would send ${method} ${url} with body: ${JSON.stringify(body)}`);
+            return {
+                ok: true,
+                text: `[dry-run] ${method} ${url} suppressed — no request was sent. Args were logged for review.`,
+            };
+        }
+        const startedAt = Date.now();
+        try {
+            const response = await this.context.fetch(url, {
+                method,
+                headers,
+                data: body !== undefined ? JSON.stringify(body) : undefined,
+            });
+            const durationMs = Date.now() - startedAt;
+            const status = response.status();
+            const responseHeaders = response.headers();
+            const responseBodyText = await response.text().catch(() => '');
+            const ok = response.ok();
+            this.requestHistory.push({ method, url, status, ok, dryRunSuppressed: false, timestamp: Date.now() });
+            const result = { method, url, status, headers: responseHeaders, body: responseBodyText, duration_ms: durationMs };
+            const text = JSON.stringify(result);
+            return { ok: true, text: text.length > 20_000 ? `${text.slice(0, 20_000)}... (truncated)` : text };
+        }
+        catch (err) {
+            this.requestHistory.push({ method, url, status: null, ok: false, dryRunSuppressed: false, timestamp: Date.now() });
+            return { ok: false, text: `Request failed: ${err.message}` };
+        }
+    }
+}
+//# sourceMappingURL=apiTools.js.map

package/dist/tools/apiTools.js.map

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

package/dist/tools/authState.d.ts

@@ -0,0 +1,21 @@
+import type { BrowserContextOptions } from 'playwright';
+export declare function resolveStorageState(projectId: number, role: string): NonNullable<BrowserContextOptions['storageState']>;
+/**
+ * BYO-credential resolution for API testing — same posture as
+ * resolveStorageState()'s UI auth: read from the consuming agent's own
+ * .env, never performed or handled beyond that single read, never exposed
+ * to the model as a value (the caller injects the returned header directly
+ * into an APIRequestContext's extraHTTPHeaders, once, at construction).
+ *
+ * APPQ_PROJECT_<id>_<ROLE>_API_KEY holds the credential value.
+ * APPQ_PROJECT_<id>_<ROLE>_API_HEADER_NAME optionally overrides the header
+ * name (defaults to "Authorization", with the value sent as "Bearer
+ * <key>" — set API_HEADER_NAME to send the raw key as-is under a different
+ * header, e.g. "X-Api-Key").
+ */
+export interface ApiAuthHeader {
+    name: string;
+    value: string;
+}
+export declare function resolveApiAuth(projectId: number, role: string): ApiAuthHeader | undefined;
+//# sourceMappingURL=authState.d.ts.map

package/dist/tools/authState.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"authState.d.ts","sourceRoot":"","sources":["../../src/tools/authState.ts"],"names":[],"mappings":"AAUA,OAAO,KAAK,EAAE,qBAAqB,EAAE,MAAM,YAAY,CAAC;AAExD,wBAAgB,mBAAmB,CAAC,SAAS,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,GAAG,WAAW,CAAC,qBAAqB,CAAC,cAAc,CAAC,CAAC,CAUvH;AAED;;;;;;;;;;;;GAYG;AACH,MAAM,WAAW,aAAa;IAC5B,IAAI,EAAE,MAAM,CAAC;IACb,KAAK,EAAE,MAAM,CAAC;CACf;AAED,wBAAgB,cAAc,CAAC,SAAS,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,GAAG,aAAa,GAAG,SAAS,CAQzF"}

package/dist/tools/authState.js

@@ -0,0 +1,29 @@
+// Reads the Playwright storageState a project/role's authenticated session
+// lives at, computed by @appliqation/automation-sdk's setupAuth() — the same
+// pure path function the customer's own Playwright config, the appq-auth-setup
+// CLI, and Appliqation's hosted executor all already agree on. A consuming
+// agent never performs login itself and never handles credentials: only the
+// resulting session (cookies/localStorage) is ever read, directly from disk,
+// never through an LLM tool call.
+import { existsSync, readFileSync } from 'node:fs';
+import { setupAuth } from '@appliqation/automation-sdk/utils';
+export function resolveStorageState(projectId, role) {
+    const path = setupAuth({ project_id: projectId, role });
+    if (!existsSync(path)) {
+        throw new Error(`No authenticated session found for project ${projectId}, role "${role}" (expected at ${path}). ` +
+            `Run \`npx appq-auth-setup --project-id ${projectId} --role ${role}\` first ` +
+            `(needs APPQ_PROJECT_${projectId}_${role.toUpperCase()}_USERNAME/_PASSWORD and APPLIQATION_SUT_BASE_URL set).`);
+    }
+    return JSON.parse(readFileSync(path, 'utf-8'));
+}
+export function resolveApiAuth(projectId, role) {
+    const upperRole = role.toUpperCase();
+    const apiKey = process.env[`APPQ_PROJECT_${projectId}_${upperRole}_API_KEY`];
+    if (!apiKey)
+        return undefined;
+    const headerName = process.env[`APPQ_PROJECT_${projectId}_${upperRole}_API_HEADER_NAME`];
+    if (headerName)
+        return { name: headerName, value: apiKey };
+    return { name: 'Authorization', value: `Bearer ${apiKey}` };
+}
+//# sourceMappingURL=authState.js.map

package/dist/tools/authState.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"authState.js","sourceRoot":"","sources":["../../src/tools/authState.ts"],"names":[],"mappings":"AAAA,2EAA2E;AAC3E,6EAA6E;AAC7E,+EAA+E;AAC/E,2EAA2E;AAC3E,4EAA4E;AAC5E,6EAA6E;AAC7E,kCAAkC;AAElC,OAAO,EAAE,UAAU,EAAE,YAAY,EAAE,MAAM,SAAS,CAAC;AACnD,OAAO,EAAE,SAAS,EAAE,MAAM,mCAAmC,CAAC;AAG9D,MAAM,UAAU,mBAAmB,CAAC,SAAiB,EAAE,IAAY;IACjE,MAAM,IAAI,GAAG,SAAS,CAAC,EAAE,UAAU,EAAE,SAAS,EAAE,IAAI,EAAE,CAAC,CAAC;IACxD,IAAI,CAAC,UAAU,CAAC,IAAI,CAAC,EAAE,CAAC;QACtB,MAAM,IAAI,KAAK,CACb,8CAA8C,SAAS,WAAW,IAAI,kBAAkB,IAAI,KAAK;YAC/F,0CAA0C,SAAS,WAAW,IAAI,WAAW;YAC7E,uBAAuB,SAAS,IAAI,IAAI,CAAC,WAAW,EAAE,wDAAwD,CACjH,CAAC;IACJ,CAAC;IACD,OAAO,IAAI,CAAC,KAAK,CAAC,YAAY,CAAC,IAAI,EAAE,OAAO,CAAC,CAAC,CAAC;AACjD,CAAC;AAoBD,MAAM,UAAU,cAAc,CAAC,SAAiB,EAAE,IAAY;IAC5D,MAAM,SAAS,GAAG,IAAI,CAAC,WAAW,EAAE,CAAC;IACrC,MAAM,MAAM,GAAG,OAAO,CAAC,GAAG,CAAC,gBAAgB,SAAS,IAAI,SAAS,UAAU,CAAC,CAAC;IAC7E,IAAI,CAAC,MAAM;QAAE,OAAO,SAAS,CAAC;IAE9B,MAAM,UAAU,GAAG,OAAO,CAAC,GAAG,CAAC,gBAAgB,SAAS,IAAI,SAAS,kBAAkB,CAAC,CAAC;IACzF,IAAI,UAAU;QAAE,OAAO,EAAE,IAAI,EAAE,UAAU,EAAE,KAAK,EAAE,MAAM,EAAE,CAAC;IAC3D,OAAO,EAAE,IAAI,EAAE,eAAe,EAAE,KAAK,EAAE,UAAU,MAAM,EAAE,EAAE,CAAC;AAC9D,CAAC"}

package/dist/tools/browserTools.d.ts

@@ -0,0 +1,35 @@
+import type { Page } from 'playwright';
+import type { LlmToolDef, ToolResult } from '../types.js';
+import { EvidenceCapture } from '../evidence/capture.js';
+import { type ClickTarget } from './destructiveActionGate.js';
+export type ClickGate = (target: ClickTarget) => ToolResult | null;
+/** Stages a captured screenshot somewhere (an appq upload, a local file, ...) and returns a ref for it. */
+export type ScreenshotSink = (png: Buffer, label: string) => Promise<{
+    ok: true;
+    ref: string;
+} | {
+    ok: false;
+    note: string;
+}>;
+export interface BrowserToolsHooks {
+    onBeforeClick?: ClickGate;
+    screenshotSink?: ScreenshotSink;
+}
+export declare const BROWSER_TOOL_DEFS: LlmToolDef[];
+/** Wraps a live Playwright Page as a browser_* tool dispatcher, tracking evidence as it goes. */
+export declare class PlaywrightBrowserTools {
+    private readonly ringBufferCap?;
+    private readonly hooks;
+    private knownRefs;
+    private pages;
+    private selected;
+    private evidenceByPage;
+    constructor(page: Page, ringBufferCap?: number | undefined, hooks?: BrowserToolsHooks);
+    private currentPage;
+    /** The currently selected tab's evidence tracker — same call shape as the old single-page `.evidence` field. */
+    get evidence(): EvidenceCapture;
+    private locatorFor;
+    dispatch(name: string, args: Record<string, unknown>): Promise<ToolResult>;
+    private dispatchTabs;
+}
+//# sourceMappingURL=browserTools.d.ts.map

package/dist/tools/browserTools.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"browserTools.d.ts","sourceRoot":"","sources":["../../src/tools/browserTools.ts"],"names":[],"mappings":"AAWA,OAAO,KAAK,EAAE,IAAI,EAAE,MAAM,YAAY,CAAC;AACvC,OAAO,KAAK,EAAE,UAAU,EAAE,UAAU,EAAE,MAAM,aAAa,CAAC;AAC1D,OAAO,EAAE,eAAe,EAAE,MAAM,wBAAwB,CAAC;AACzD,OAAO,EAAiB,KAAK,WAAW,EAAE,MAAM,4BAA4B,CAAC;AAE7E,MAAM,MAAM,SAAS,GAAG,CAAC,MAAM,EAAE,WAAW,KAAK,UAAU,GAAG,IAAI,CAAC;AAEnE,2GAA2G;AAC3G,MAAM,MAAM,cAAc,GAAG,CAC3B,GAAG,EAAE,MAAM,EACX,KAAK,EAAE,MAAM,KACV,OAAO,CAAC;IAAE,EAAE,EAAE,IAAI,CAAC;IAAC,GAAG,EAAE,MAAM,CAAA;CAAE,GAAG;IAAE,EAAE,EAAE,KAAK,CAAC;IAAC,IAAI,EAAE,MAAM,CAAA;CAAE,CAAC,CAAC;AAEtE,MAAM,WAAW,iBAAiB;IAChC,aAAa,CAAC,EAAE,SAAS,CAAC;IAC1B,cAAc,CAAC,EAAE,cAAc,CAAC;CACjC;AAED,eAAO,MAAM,iBAAiB,EAAE,UAAU,EAmHzC,CAAC;AAEF,iGAAiG;AACjG,qBAAa,sBAAsB;IAqB/B,OAAO,CAAC,QAAQ,CAAC,aAAa,CAAC;IAC/B,OAAO,CAAC,QAAQ,CAAC,KAAK;IAhBxB,OAAO,CAAC,SAAS,CAAqB;IAStC,OAAO,CAAC,KAAK,CAAS;IACtB,OAAO,CAAC,QAAQ,CAAK;IACrB,OAAO,CAAC,cAAc,CAA6B;gBAGjD,IAAI,EAAE,IAAI,EACO,aAAa,CAAC,EAAE,MAAM,YAAA,EACtB,KAAK,GAAE,iBAAsB;IAMhD,OAAO,CAAC,WAAW;IAInB,gHAAgH;IAChH,IAAI,QAAQ,IAAI,eAAe,CAE9B;IAED,OAAO,CAAC,UAAU;IAKZ,QAAQ,CAAC,IAAI,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,OAAO,CAAC,UAAU,CAAC;YAqGlE,YAAY;CA2C3B"}

package/dist/tools/browserTools.js

@@ -0,0 +1,313 @@
+// Playwright-backed implementations of the browser_* tool palette. Tool names
+// mirror Playwright MCP's own naming convention so any workflow prose written
+// against that vocabulary transfers unchanged to this engine.
+//
+// Two behaviors are injectable rather than hardcoded, so this class has zero
+// appq-specific coupling: the destructive-action check before a click
+// (defaults to the shared classifyClick()), and where a screenshot gets
+// staged for attachment (no default — a consuming agent either wires its own
+// appq upload, a local file sink, or neither; browser_take_screenshot still
+// works either way, just without a ref to hand back when there's no sink).
+import { EvidenceCapture } from '../evidence/capture.js';
+import { classifyClick } from './destructiveActionGate.js';
+export const BROWSER_TOOL_DEFS = [
+    {
+        name: 'browser_navigate',
+        description: 'Navigate the page to a URL.',
+        inputSchema: { type: 'object', properties: { url: { type: 'string' } }, required: ['url'] },
+    },
+    {
+        name: 'browser_navigate_back',
+        description: 'Go back to the previous page.',
+        inputSchema: { type: 'object', properties: {} },
+    },
+    {
+        name: 'browser_snapshot',
+        description: 'Take an accessibility-tree snapshot of the current page. Returns a text tree with element refs ' +
+            '(e1, e2, ...) to use with browser_click/browser_type/etc.',
+        inputSchema: { type: 'object', properties: {} },
+    },
+    {
+        name: 'browser_click',
+        description: 'Click an element by its ref from the last browser_snapshot. `label` must describe the control\'s ' +
+            'visible text/purpose (e.g. "Delete account", "Pay now") — it is checked against a destructive-action ' +
+            'gate before the click happens.',
+        inputSchema: {
+            type: 'object',
+            properties: { ref: { type: 'string' }, label: { type: 'string' } },
+            required: ['ref', 'label'],
+        },
+    },
+    {
+        name: 'browser_type',
+        description: 'Type text into an element by its ref from the last browser_snapshot.',
+        inputSchema: {
+            type: 'object',
+            properties: { ref: { type: 'string' }, text: { type: 'string' }, submit: { type: 'boolean' } },
+            required: ['ref', 'text'],
+        },
+    },
+    {
+        name: 'browser_select_option',
+        description: 'Select an option in a <select> element by its ref.',
+        inputSchema: {
+            type: 'object',
+            properties: { ref: { type: 'string' }, value: { type: 'string' } },
+            required: ['ref', 'value'],
+        },
+    },
+    {
+        name: 'browser_press_key',
+        description: 'Press a keyboard key (e.g. "Enter", "Escape").',
+        inputSchema: { type: 'object', properties: { key: { type: 'string' } }, required: ['key'] },
+    },
+    {
+        name: 'browser_take_screenshot',
+        description: 'Take a screenshot of the current viewport and stage it for attachment. Returns a screenshot_upload_id ' +
+            'when a screenshot sink is configured — pass that straight through wherever the calling workflow expects ' +
+            'it. You never need to handle the image bytes yourself.',
+        inputSchema: { type: 'object', properties: {} },
+    },
+    {
+        name: 'browser_console_messages',
+        description: 'Return console messages logged since the last check.',
+        inputSchema: { type: 'object', properties: {} },
+    },
+    {
+        name: 'browser_network_requests',
+        description: 'Return network requests observed since the last check.',
+        inputSchema: { type: 'object', properties: {} },
+    },
+    {
+        name: 'browser_wait_for',
+        description: 'Wait for a duration in milliseconds, or for text to appear on the page.',
+        inputSchema: {
+            type: 'object',
+            properties: { millis: { type: 'number' }, text: { type: 'string' } },
+        },
+    },
+    {
+        name: 'browser_resize',
+        description: 'Resize the browser viewport of the currently selected tab.',
+        inputSchema: {
+            type: 'object',
+            properties: { width: { type: 'number' }, height: { type: 'number' } },
+            required: ['width', 'height'],
+        },
+    },
+    {
+        name: 'browser_tabs',
+        description: 'List, open, close, or switch between browser tabs. `list` returns every open tab with its index and URL, ' +
+            'marking which one is selected. `new` opens a tab (optionally navigating it to `url`) and selects it. ' +
+            '`close` closes a tab by `index` (defaults to the selected tab) — at least one tab must remain open. ' +
+            '`select` by `index` makes that tab the target of every other browser_* tool. Switching tabs invalidates ' +
+            'refs from a prior browser_snapshot — call browser_snapshot again after selecting a different tab.',
+        inputSchema: {
+            type: 'object',
+            properties: {
+                action: { type: 'string', enum: ['list', 'new', 'close', 'select'] },
+                index: { type: 'number' },
+                url: { type: 'string' },
+            },
+            required: ['action'],
+        },
+    },
+    {
+        name: 'browser_evaluate',
+        description: 'Run JavaScript in the page context of the currently selected tab and return the result. Pass either a ' +
+            'plain expression (e.g. "document.title") or a function (e.g. "() => document.title"). Unrestricted — use ' +
+            'for read-only inspection (Service Worker state, Performance API, localStorage, etc.), not to work around ' +
+            'the destructive-action gate on browser_click.',
+        inputSchema: { type: 'object', properties: { function: { type: 'string' } }, required: ['function'] },
+    },
+];
+/** Wraps a live Playwright Page as a browser_* tool dispatcher, tracking evidence as it goes. */
+export class PlaywrightBrowserTools {
+    ringBufferCap;
+    hooks;
+    // Refs come from page.ariaSnapshot({mode:'ai'}), which embeds [ref=eN]
+    // markers directly in its output — no manual tree-walking needed. A ref
+    // resolves back to a live element via the 'aria-ref=' selector engine.
+    // Refs are only valid against the page they were snapshotted from, so a
+    // tab switch clears them — the model must call browser_snapshot again.
+    knownRefs = new Set();
+    // Multi-tab support: every existing browser_* op targets whichever page is
+    // currently selected, via currentPage()/currentEvidence(). Consumers that
+    // never call browser_tabs see no behavior change — pages always has
+    // exactly one entry, selected always 0. Evidence is tracked per page (not
+    // just the original one) since console/network listeners are bound at
+    // Page construction — a new tab's console output would otherwise be
+    // silently invisible to browser_console_messages after switching to it.
+    pages;
+    selected = 0;
+    evidenceByPage;
+    constructor(page, ringBufferCap, hooks = {}) {
+        this.ringBufferCap = ringBufferCap;
+        this.hooks = hooks;
+        this.pages = [page];
+        this.evidenceByPage = new Map([[page, new EvidenceCapture(page, ringBufferCap)]]);
+    }
+    currentPage() {
+        return this.pages[this.selected];
+    }
+    /** The currently selected tab's evidence tracker — same call shape as the old single-page `.evidence` field. */
+    get evidence() {
+        return this.evidenceByPage.get(this.currentPage());
+    }
+    locatorFor(ref) {
+        if (!this.knownRefs.has(ref))
+            throw new Error(`Unknown ref "${ref}" — call browser_snapshot first`);
+        return this.currentPage().locator(`aria-ref=${ref}`);
+    }
+    async dispatch(name, args) {
+        switch (name) {
+            case 'browser_navigate': {
+                await this.currentPage().goto(String(args.url), { waitUntil: 'domcontentloaded' });
+                return { ok: true, text: `Navigated to ${args.url}` };
+            }
+            case 'browser_navigate_back': {
+                await this.currentPage().goBack({ waitUntil: 'domcontentloaded' });
+                return { ok: true, text: 'Navigated back' };
+            }
+            case 'browser_snapshot': {
+                const text = await this.currentPage().ariaSnapshot({ mode: 'ai' });
+                this.knownRefs = new Set([...text.matchAll(/\[ref=([^\]]+)\]/g)].map((m) => m[1]));
+                return { ok: true, text: text || '(empty page)' };
+            }
+            case 'browser_click': {
+                const ref = String(args.ref);
+                // label is required (not derived from the ref) so the destructive-action
+                // gate has something to check before the click ever dispatches.
+                const label = String(args.label ?? '');
+                const gate = this.hooks.onBeforeClick ?? classifyClick;
+                const blocked = gate({ label, tag: 'button' });
+                if (blocked)
+                    return blocked;
+                await this.locatorFor(ref).click();
+                return { ok: true, text: `Clicked "${label || ref}"` };
+            }
+            case 'browser_type': {
+                const ref = String(args.ref);
+                await this.locatorFor(ref).fill(String(args.text));
+                if (args.submit)
+                    await this.locatorFor(ref).press('Enter');
+                return { ok: true, text: `Typed into ${ref}` };
+            }
+            case 'browser_select_option': {
+                const ref = String(args.ref);
+                await this.locatorFor(ref).selectOption(String(args.value));
+                return { ok: true, text: `Selected "${args.value}" in ${ref}` };
+            }
+            case 'browser_press_key': {
+                await this.currentPage().keyboard.press(String(args.key));
+                return { ok: true, text: `Pressed ${args.key}` };
+            }
+            case 'browser_take_screenshot': {
+                const png = await this.currentPage().screenshot({ type: 'png' });
+                if (!this.hooks.screenshotSink) {
+                    return { ok: true, text: `Captured screenshot (${png.length} bytes). No screenshot sink configured for this agent.`, data: png };
+                }
+                try {
+                    const staged = await this.hooks.screenshotSink(png, 'autotest-step');
+                    if (staged.ok) {
+                        return { ok: true, text: `Captured screenshot (${png.length} bytes). screenshot_upload_id: ${staged.ref}`, data: png };
+                    }
+                    // Non-fatal — the step's other evidence (accessibility snapshot,
+                    // console/network deltas) still stands on its own; one failed
+                    // staging attempt shouldn't block the whole step.
+                    return {
+                        ok: true,
+                        text: `Captured screenshot (${png.length} bytes), but staging it failed: ${staged.note}. ` +
+                            'No screenshot_upload_id available for this step — submit evidence without one.',
+                        data: png,
+                    };
+                }
+                catch (err) {
+                    return {
+                        ok: true,
+                        text: `Captured screenshot (${png.length} bytes), but staging it failed: ${err.message}. ` +
+                            'No screenshot_upload_id available for this step — submit evidence without one.',
+                        data: png,
+                    };
+                }
+            }
+            case 'browser_console_messages': {
+                return { ok: true, text: JSON.stringify(this.evidence.getConsoleDeltas()) };
+            }
+            case 'browser_network_requests': {
+                return { ok: true, text: JSON.stringify(this.evidence.getNetworkDeltas()) };
+            }
+            case 'browser_wait_for': {
+                if (args.text) {
+                    await this.currentPage().getByText(String(args.text)).waitFor({ timeout: 15000 });
+                    return { ok: true, text: `Text "${args.text}" appeared` };
+                }
+                await this.currentPage().waitForTimeout(Number(args.millis ?? 1000));
+                return { ok: true, text: 'Waited' };
+            }
+            case 'browser_resize': {
+                const width = Number(args.width);
+                const height = Number(args.height);
+                await this.currentPage().setViewportSize({ width, height });
+                return { ok: true, text: `Resized viewport to ${width}x${height}` };
+            }
+            case 'browser_tabs': {
+                return this.dispatchTabs(args);
+            }
+            case 'browser_evaluate': {
+                const result = await this.currentPage().evaluate(String(args.function));
+                return { ok: true, text: result === undefined ? 'undefined' : JSON.stringify(result) };
+            }
+            default:
+                return { ok: false, text: `Unknown browser tool "${name}"` };
+        }
+    }
+    async dispatchTabs(args) {
+        const action = String(args.action ?? '');
+        switch (action) {
+            case 'list': {
+                const lines = this.pages.map((p, i) => `${i}${i === this.selected ? ' (selected)' : ''}: ${p.url()}`);
+                return { ok: true, text: lines.join('\n') };
+            }
+            case 'new': {
+                const newPage = await this.currentPage().context().newPage();
+                if (args.url)
+                    await newPage.goto(String(args.url), { waitUntil: 'domcontentloaded' });
+                this.pages.push(newPage);
+                this.evidenceByPage.set(newPage, new EvidenceCapture(newPage, this.ringBufferCap));
+                this.selected = this.pages.length - 1;
+                this.knownRefs = new Set();
+                return { ok: true, text: `Opened new tab at index ${this.selected}${args.url ? ` (${args.url})` : ''}` };
+            }
+            case 'close': {
+                const index = args.index !== undefined ? Number(args.index) : this.selected;
+                if (!Number.isInteger(index) || index < 0 || index >= this.pages.length) {
+                    return { ok: false, text: `No tab at index ${args.index}` };
+                }
+                if (this.pages.length === 1)
+                    return { ok: false, text: 'Cannot close the only remaining tab' };
+                const [closed] = this.pages.splice(index, 1);
+                this.evidenceByPage.delete(closed);
+                await closed.close();
+                if (this.selected >= this.pages.length)
+                    this.selected = this.pages.length - 1;
+                else if (this.selected > index)
+                    this.selected -= 1;
+                this.knownRefs = new Set();
+                return { ok: true, text: `Closed tab ${index}. Now on tab ${this.selected} (${this.currentPage().url()}).` };
+            }
+            case 'select': {
+                const index = Number(args.index);
+                if (!Number.isInteger(index) || index < 0 || index >= this.pages.length) {
+                    return { ok: false, text: `No tab at index ${args.index}` };
+                }
+                this.selected = index;
+                this.knownRefs = new Set();
+                return { ok: true, text: `Selected tab ${index} (${this.currentPage().url()})` };
+            }
+            default:
+                return { ok: false, text: `Unknown browser_tabs action "${action}"` };
+        }
+    }
+}
+//# sourceMappingURL=browserTools.js.map