@xoxoai/checkmate 0.4.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 Dawid Dobrowolski SoftQA
+
+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,244 @@
+# **_checkmate_**
+
+AI test automation that actually works. Write tests in plain English, without locators, and with less code.
+
+![playwright](https://img.shields.io/badge/Playwright-1.59.1-blue.svg)
+![typescript](https://img.shields.io/badge/TypeScript-5.9.3-blue.svg)
+![nodejs](https://img.shields.io/badge/Node.js-LTS-green.svg)
+![openai](https://img.shields.io/badge/OpenAI-API-yellow.svg)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](LICENSE)
+
+## Why?
+
+Spending countless hours building and maintaining E2E tests that look like this?
+
+```
+await page.goto('https://www.google.com')
+const searchBox = page.getByRole('combobox', { name: 'Search', exact: true })
+await searchBox.fill('playwright test automation')
+await searchBox.press('Enter')
+await expect(page.getByRole('link', { name: 'playwright' })
+    .filter({ hasText: 'playwright.dev' })
+    .first(), 'playwright.dev link should be visible')
+    .toBeVisible( { timeout: 30 * 1000 } )
+```
+
+Try **_checkmate_**!
+
+```typescript
+await ai.run({
+	action: `
+        Navigate to google.com
+        Type 'playwright test automation' in the search bar
+        Press Enter key`,
+	expect: `
+        Search results contain the playwright.dev link`,
+})
+```
+
+## What You Get
+
+✅ **Zero Locators** - Write tests in plain English  
+✅ **Self-Healing** - Tests adapt to UI changes automatically  
+✅ **Any Provider** - Gemini, Claude, Groq, GPT, xAI, or local models  
+✅ **Web & Salesforce** - Basic support out of the box  
+✅ **Cost Optimized** - Built-in token management and budgeting  
+✅ **Playwright Test** - Native reports, traces and debugging  
+✅ **Fully Customizable** - Build your own [extensions](docs/EXTENSIONS.md) and tools
+
+<img src="docs/img/gpt-oss-20b-e2e-checkout.gif" alt="example-e2e-test" width="100%"/>
+
+## Get Started in 5 Minutes
+
+### Prerequisites
+
+- Node.js [LTS](https://nodejs.org/en/download)
+- OpenAI [API key](https://platform.openai.com/api-keys) or compatible provider [Groq](https://console.groq.com/keys) [Gemini](https://aistudio.google.com/app/api-keys) [xAI](https://x.ai/api) etc.
+
+### 1. Install
+
+```bash
+npm install -D @playwright/test @xoxoai/checkmate
+npx playwright install
+```
+
+### 2. Configure `.env`
+
+_using [OpenAI API](https://platform.openai.com/settings/organization/api-keys) key and default settings:_
+
+```bash
+OPENAI_API_KEY=#your_api_key_here
+```
+
+_for other providers, set the base url and model:_
+
+```bash
+OPENAI_BASE_URL=https://api.groq.com/openai/v1
+OPENAI_MODEL=openai/gpt-oss-20b
+```
+
+### 3. Run Tests
+
+```
+npm run test:web:example
+```
+
+### 4. View Report
+
+```
+npm run show:report
+```
+
+## Writing Tests
+
+Import `test` and `expect` from `@xoxoai/checkmate/playwright` and use the `ai` fixture to run AI-driven tests alongside standard Playwright assertions.  
+**_checkmate_** tests are written using natural language by specifying `action` and `expect`:
+
+```typescript
+import { expect, test } from '@xoxoai/checkmate/playwright'
+
+test('google search', async ({ ai }) => {
+	await ai.run({
+		action: `
+            Open the browser and navigate to google.com.
+            Type 'playwright test automation' in the search bar.
+            Press Enter key.`,
+		expect: `
+            Search results contain the 'playwright.dev' link`,
+	})
+})
+```
+
+That's it. No page objects, no selectors. No locators. Peace on Earth.
+
+Browser settings (viewport, headless mode, video recording, timeouts, etc.) are configured in [playwright.config.ts](playwright.config.ts) using Playwright's [standard](https://playwright.dev/docs/test-configuration) configuration mechanism.
+
+See [guide](docs/GUIDE.md#best-practices) for detailed examples and best practices.
+
+### Programmatic API
+
+If you use **_checkmate_** without the fixture wrapper, compose a runner from `@xoxoai/checkmate/core` and extensions:
+
+```typescript
+import { createRunner } from '@xoxoai/checkmate/core'
+import { web } from '@xoxoai/checkmate/playwright'
+
+const ai = createRunner({
+	extensions: [web({ page })],
+})
+
+await ai.run({
+	action: 'Open the pricing page',
+	expect: 'Pricing details are visible',
+})
+```
+
+See [guide](docs/GUIDE.md#advanced-topics) for advanced topics and [extensions](docs/EXTENSIONS.md) for building custom tools, extensions, and runners.
+
+Published entry points:
+
+`@xoxoai/checkmate/core`: Build your own runner with extensions.  
+`@xoxoai/checkmate/playwright`: Use the built-in web extension with Playwright `test` and `expect`.  
+`@xoxoai/checkmate/salesforce`: Use the built-in web + Salesforce extensions with the same `ai` fixture shape.
+
+The repository keeps runnable consumer-style examples under `test/examples/`.
+
+## Costs
+
+Costs vary based on model and provider, test complexity and number of steps.
+**_checkmate_** includes built-in token usage [monitoring](docs/GUIDE.md#cost-management).
+
+Cost estimates with [gpt-oss-20b hosted on groq.com](https://console.groq.com/docs/model/openai/gpt-oss-20b) for optimal balance:
+
+- Simple test (~5 steps): ~$0.001 - $0.01
+- Complex test (~20 steps): ~$0.01 - $0.05
+- Full E2E suite (~50 complex tests): ~$1.00 - $2.00
+
+See [guide](docs/GUIDE.md#cost-management) for detailed cost control and monitoring options.
+
+## Common Issues
+
+**AI makes incorrect decisions**
+
+- Provide precise descriptions in `action` and more focused assertions in `expect`
+- Reference specific element identifiers and roles (for example: text, label, button, list)
+- Break complex workflows into single-action steps; use a step-by-step approach
+
+**Tests loop during step execution**
+
+- Increase `OPENAI_TEMPERATURE` to encourage exploration
+- Use a reasoning/thinking model (if available) to improve planning and avoid repetitive loops
+
+**High token costs**
+
+- Enable [snapshot filtering](docs/GUIDE.md#using-snapshot-filtering-for-token-optimization) with `CHECKMATE_SNAPSHOT_FILTERING=true` to score and narrow the elements automatically from `action` and `expect`. Use `topPercent` to dial how much of the scored snapshot to keep for a step.
+- Set a lower reasoning effort: `OPENAI_REASONING_EFFORT`
+- Consider disabling `OPENAI_INCLUDE_SCREENSHOT_IN_SNAPSHOT`
+- Use a cheaper model, lower-end models often perform well (e.g., `gpt-5.4-nano` or `gpt-oss-20b`)
+
+See [guide](docs/GUIDE.md#openai-api-settings) for detailed configuration options and troubleshooting tips.
+
+## FAQ
+
+**Which models work best?**  
+You can use any model that was trained for tool use. Here are the best picks based on extensive testing:
+
+- Highly recommended: [`gpt-oss-20b` hosted on groq.com](https://console.groq.com/docs/model/openai/gpt-oss-20b). Groq's infrastructure is optimized for minimal latency and fast inference, making it ideal for E2E test automation.
+- Google's `gemini-2.5-flash` offers an excellent balance of cost and performance if you prefer major cloud providers.
+- OpenAI's `gpt-5-mini`, `gpt-5.4-nano` and xAI's `grok-4-1-fast-reasoning` also work well and keep costs relatively low.
+
+**Can I use local models?**  
+Yes - **_checkmate_** works with any OpenAI‑compatible API, including local models via LM Studio, Ollama, or llama.cpp. I recommend [qwen3.5-4b](https://huggingface.co/Qwen/Qwen3.5-4B). It is fast (≈100 tokens/sec on an RTX 3060 Ti; ≈40 tokens/sec on Apple M3) and performs surprisingly well for E2E testing.
+
+**Does it work with CI/CD?**  
+Absolutely. Use **_checkmate_** as part of your existing [Playwright Test suites in any CI/CD pipeline](https://playwright.dev/docs/best-practices#run-tests-on-ci). You can mix AI‑driven steps and traditional tests as needed.
+
+**Is this production-ready?**  
+It depends. If you can accept some non‑deterministic behavior and leverage LLMs' randomness to help address the [pesticide paradox](https://medium.com/@suwekasansiluni/the-pesticide-paradox-what-farming-teaches-us-about-software-testing-ab5d625d4de1), **_checkmate_** can be production-ready. In many cases, the maintenance savings, faster development, and benefits of non‑linear execution outweigh occasional hiccups.
+
+If you require 100% deterministic tests at all times, traditional Playwright remains the better choice.
+
+**Best part?**  
+You can mix both approaches within the same test suite, combining AI‑driven and traditional tests as needed:
+
+```typescript
+// traditional playwright actions:
+await page.goto('https://www.google.com')
+const searchBox = page.getByRole('combobox', { name: 'Search', exact: true })
+await searchBox.fill('playwright test automation')
+await searchBox.press('Enter')
+
+// ai-driven actions and assertions:
+await ai.run({
+	action: 'Click on the link that leads to playwright.dev',
+	expect: 'The playwright.dev homepage is displayed',
+})
+```
+
+## Documentation
+
+- [**_checkmate_**](docs/GUIDE.md)
+- [Playwright](https://playwright.dev/)
+
+## Contributing
+
+I'd love your help! Key areas:
+
+- Additional tool integrations (API testing, Salesforce, etc.)
+- Further cost optimization techniques
+- Context and prompt engineering improvements
+- Error handling and recovery
+
+See [roadmap](docs/ROADMAP.md) for future plans and development
+
+## MIT License
+
+See [license](LICENSE) file for details
+
+## Why I build this?
+
+Test automation shouldn't require a PhD in XPath. This project explores how AI can make it accessible to anyone.
+
+Less coding, more testing.
+
+Built with ❤️ by [Dawid Dobrowolski](https://github.com/dawiddiwad)

package/dist/ai/client.d.ts

@@ -0,0 +1,49 @@
+import { ChatCompletion, ChatCompletionMessageParam } from 'openai/resources/chat/completions';
+import { RuntimeConfig } from '../config/runtime-config';
+import { ToolRegistry } from '../tools/registry';
+import { Step, ResolveStepResult } from '../runtime/types';
+import { ExtensionHost } from '../runtime/extension';
+export type AiClientDependencies = {
+    runtimeConfig: RuntimeConfig;
+    toolRegistry: ToolRegistry;
+    extensionHost: ExtensionHost;
+};
+export declare class AiClient {
+    private client;
+    private messages;
+    private readonly responseProcessor;
+    private readonly retryableStatus;
+    private step;
+    private resolveStepResult;
+    temperature: number;
+    private readonly messageHistory;
+    constructor({ runtimeConfig, toolRegistry, extensionHost }: AiClientDependencies);
+    private readonly runtimeConfig;
+    private readonly toolRegistry;
+    initialize(step: Step, resolveStepResult: ResolveStepResult): Promise<void>;
+    getMessages(): ChatCompletionMessageParam[];
+    getToolRegistry(): ToolRegistry;
+    getRuntimeConfig(): RuntimeConfig;
+    sendMessage(userMessage: string | ChatCompletionMessageParam[]): Promise<void>;
+    addToolResponse(toolCallId: string, content: string): Promise<void>;
+    addUserMessage(content: string): Promise<void>;
+    addToolExecutionSummaryMessage(content: string): Promise<void>;
+    addCurrentSnapshotMessage(snapshotContent: string): Promise<void>;
+    addCurrentScreenshotMessage(base64Data: string, mimeType?: string): Promise<void>;
+    sendToolResponseWithRetry(): Promise<ChatCompletion>;
+    private createChatCompletion;
+    private appendResponseMessages;
+    private sanitizeAssistantMessage;
+    private executeWithRetry;
+    private getStatus;
+    private isRetryable;
+    private getRetryAfterSeconds;
+    private calculateBackoff;
+    private sleep;
+    countHistoryTokens(): number;
+    replaceHistory(history: ChatCompletionMessageParam[]): void;
+    private enhanceError;
+    private isToolError;
+    private countContentChars;
+}
+//# sourceMappingURL=client.d.ts.map

package/dist/ai/client.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"client.d.ts","sourceRoot":"","sources":["../../src/ai/client.ts"],"names":[],"mappings":"AACA,OAAO,EACN,cAAc,EAEd,0BAA0B,EAC1B,MAAM,mCAAmC,CAAA;AAC1C,OAAO,EAAE,aAAa,EAAE,MAAM,0BAA0B,CAAA;AAIxD,OAAO,EAAE,YAAY,EAAE,MAAM,mBAAmB,CAAA;AAChD,OAAO,EAAE,IAAI,EAAE,iBAAiB,EAAE,MAAM,kBAAkB,CAAA;AAG1D,OAAO,EAAE,aAAa,EAAE,MAAM,sBAAsB,CAAA;AAEpD,MAAM,MAAM,oBAAoB,GAAG;IAClC,aAAa,EAAE,aAAa,CAAA;IAC5B,YAAY,EAAE,YAAY,CAAA;IAC1B,aAAa,EAAE,aAAa,CAAA;CAC5B,CAAA;AAED,qBAAa,QAAQ;IACpB,OAAO,CAAC,MAAM,CAAS;IACvB,OAAO,CAAC,QAAQ,CAAmC;IACnD,OAAO,CAAC,QAAQ,CAAC,iBAAiB,CAAmB;IACrD,OAAO,CAAC,QAAQ,CAAC,eAAe,CAS/B;IACD,OAAO,CAAC,IAAI,CAAO;IACnB,OAAO,CAAC,iBAAiB,CAAoB;IAC7C,WAAW,EAAE,MAAM,CAAA;IACnB,OAAO,CAAC,QAAQ,CAAC,cAAc,CAAuB;gBAE1C,EAAE,aAAa,EAAE,YAAY,EAAE,aAAa,EAAE,EAAE,oBAAoB;IAOhF,OAAO,CAAC,QAAQ,CAAC,aAAa,CAAe;IAC7C,OAAO,CAAC,QAAQ,CAAC,YAAY,CAAc;IAErC,UAAU,CAAC,IAAI,EAAE,IAAI,EAAE,iBAAiB,EAAE,iBAAiB,GAAG,OAAO,CAAC,IAAI,CAAC;IAiBjF,WAAW,IAAI,0BAA0B,EAAE;IAI3C,eAAe,IAAI,YAAY;IAI/B,gBAAgB,IAAI,aAAa;IAI3B,WAAW,CAAC,WAAW,EAAE,MAAM,GAAG,0BAA0B,EAAE;IAe9D,eAAe,CAAC,UAAU,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;IAInE,cAAc,CAAC,OAAO,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;IAI9C,8BAA8B,CAAC,OAAO,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;IAO9D,yBAAyB,CAAC,eAAe,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;IAIjE,2BAA2B,CAAC,UAAU,EAAE,MAAM,EAAE,QAAQ,GAAE,MAAoB,GAAG,OAAO,CAAC,IAAI,CAAC;IAI9F,yBAAyB,IAAI,OAAO,CAAC,cAAc,CAAC;YAS5C,oBAAoB;IAalC,OAAO,CAAC,sBAAsB;IAQ9B,OAAO,CAAC,wBAAwB;YAgClB,gBAAgB;IAmC9B,OAAO,CAAC,SAAS;IAYjB,OAAO,CAAC,WAAW;IAKnB,OAAO,CAAC,oBAAoB;IAqB5B,OAAO,CAAC,gBAAgB;IAKxB,OAAO,CAAC,KAAK;IAIb,kBAAkB,IAAI,MAAM;IAK5B,cAAc,CAAC,OAAO,EAAE,0BAA0B,EAAE,GAAG,IAAI;IAI3D,OAAO,CAAC,YAAY;IAMpB,OAAO,CAAC,WAAW;IAanB,OAAO,CAAC,iBAAiB;CA0BzB"}

package/dist/ai/client.js

@@ -0,0 +1,244 @@
+import OpenAI from 'openai';
+import { logger } from '../logging';
+import { CheckmateLogger } from '../logging/logger';
+import { LoopDetectedError } from '../tools/loop-detector';
+import { MessageHistory } from './message-history';
+import { ResponseProcessor } from './response-processor';
+export class AiClient {
+    client;
+    messages = [];
+    responseProcessor;
+    retryableStatus = [
+        408,
+        409,
+        429,
+        500,
+        502,
+        503,
+        504,
+        LoopDetectedError.STATUS,
+    ];
+    step;
+    resolveStepResult;
+    temperature;
+    messageHistory = new MessageHistory();
+    constructor({ runtimeConfig, toolRegistry, extensionHost }) {
+        this.runtimeConfig = runtimeConfig;
+        this.toolRegistry = toolRegistry;
+        this.responseProcessor = new ResponseProcessor({ aiClient: this, extensionHost });
+        this.temperature = this.runtimeConfig.getTemperature();
+    }
+    runtimeConfig;
+    toolRegistry;
+    async initialize(step, resolveStepResult) {
+        this.client = new OpenAI({
+            apiKey: this.runtimeConfig.getApiKey(),
+            baseURL: this.runtimeConfig.getBaseURL(),
+            timeout: this.runtimeConfig.getTimeout(),
+            maxRetries: 0,
+            logLevel: this.runtimeConfig.getLogLevel(),
+            logger: CheckmateLogger.create('ai_client', this.runtimeConfig.getLogLevel()),
+        });
+        this.messages = [];
+        this.step = step;
+        this.resolveStepResult = resolveStepResult;
+        this.responseProcessor.resetStepTokens();
+        this.temperature = this.runtimeConfig.getTemperature();
+    }
+    getMessages() {
+        return this.messages;
+    }
+    getToolRegistry() {
+        return this.toolRegistry;
+    }
+    getRuntimeConfig() {
+        return this.runtimeConfig;
+    }
+    async sendMessage(userMessage) {
+        if (typeof userMessage === 'string') {
+            this.messages.push({ role: 'user', content: userMessage });
+        }
+        else {
+            this.messages.push(...userMessage);
+        }
+        return this.executeWithRetry(async () => {
+            const tools = await this.toolRegistry.getTools();
+            const response = await this.createChatCompletion(tools, true);
+            this.appendResponseMessages(response);
+            await this.responseProcessor.handleResponse(response, this.step, this.resolveStepResult);
+        });
+    }
+    async addToolResponse(toolCallId, content) {
+        this.messages.push({ role: 'tool', tool_call_id: toolCallId, content });
+    }
+    async addUserMessage(content) {
+        this.messages.push({ role: 'user', content });
+    }
+    async addToolExecutionSummaryMessage(content) {
+        this.messages.push({
+            role: 'user',
+            content: `${MessageHistory.TOOL_EXECUTION_SUMMARY_IDENTIFIER}:\n${content}`,
+        });
+    }
+    async addCurrentSnapshotMessage(snapshotContent) {
+        this.messages.push(this.messageHistory.createSnapshotMessage(snapshotContent));
+    }
+    async addCurrentScreenshotMessage(base64Data, mimeType = 'image/png') {
+        this.messages.push(this.messageHistory.createScreenshotMessage(base64Data, mimeType));
+    }
+    async sendToolResponseWithRetry() {
+        return this.executeWithRetry(async () => {
+            const tools = await this.toolRegistry.getTools();
+            const response = await this.createChatCompletion(tools, false);
+            this.appendResponseMessages(response);
+            return response;
+        });
+    }
+    async createChatCompletion(tools, includeN) {
+        return this.client.chat.completions.create({
+            model: this.runtimeConfig.getModel(),
+            messages: this.messages,
+            tools,
+            tool_choice: this.runtimeConfig.getToolChoice(),
+            parallel_tool_calls: false,
+            temperature: this.temperature,
+            reasoning_effort: this.runtimeConfig.getReasoningEffort(),
+            ...(includeN ? { n: 1 } : {}),
+        });
+    }
+    appendResponseMessages(response) {
+        response.choices.forEach((choice) => {
+            if (choice.message) {
+                this.messages.push(this.sanitizeAssistantMessage(choice.message));
+            }
+        });
+    }
+    sanitizeAssistantMessage(message) {
+        const sanitizedMessage = { role: 'assistant' };
+        if (message.content !== undefined) {
+            sanitizedMessage.content = message.content;
+        }
+        if ('refusal' in message && message.refusal !== undefined) {
+            sanitizedMessage.refusal = message.refusal;
+        }
+        if ('tool_calls' in message && message.tool_calls !== undefined) {
+            sanitizedMessage.tool_calls = message.tool_calls;
+        }
+        if ('function_call' in message && message.function_call !== undefined) {
+            sanitizedMessage.function_call = message.function_call;
+        }
+        if ('name' in message && typeof message.name === 'string') {
+            sanitizedMessage.name = message.name;
+        }
+        if ('audio' in message && message.audio !== undefined) {
+            sanitizedMessage.audio = message.audio;
+        }
+        return sanitizedMessage;
+    }
+    async executeWithRetry(operation) {
+        const maxRetries = this.runtimeConfig.getMaxRetries();
+        let lastError = null;
+        for (let attempt = 0; attempt <= maxRetries; attempt++) {
+            try {
+                return await operation();
+            }
+            catch (error) {
+                lastError = error instanceof Error ? error : new Error(String(error));
+                if ((!this.isRetryable(error) && !this.isToolError(error)) || attempt === maxRetries) {
+                    throw this.enhanceError(error);
+                }
+                if (error instanceof LoopDetectedError) {
+                    const antiLoopTempChange = Math.round(Math.random() * 10) / 10;
+                    logger.warn(`repeated tool calls detected: adjusting temperature from ${this.temperature} to ${antiLoopTempChange} to mitigate looping`);
+                    this.temperature = antiLoopTempChange;
+                }
+                const retryAfter = this.getRetryAfterSeconds(error);
+                const delay = retryAfter ? retryAfter * 1000 : this.calculateBackoff(attempt);
+                logger.warn(`status: ${this.getStatus(error)} retry attempt: ${attempt + 1}/${maxRetries} starting in: ${delay}ms ...`);
+                logger.debug(`retryable error details:\n${JSON.stringify(error, null, 2)}`);
+                await this.sleep(delay);
+            }
+        }
+        throw lastError || new Error('Unexpected error in retry loop');
+    }
+    getStatus(error) {
+        if (typeof error !== 'object' || error === null) {
+            return null;
+        }
+        const status = error.status ??
+            error.statusCode ??
+            error.code;
+        return typeof status === 'number' || typeof status === 'string' ? status : null;
+    }
+    isRetryable(error) {
+        const statusCode = this.getStatus(error);
+        return statusCode !== null && this.retryableStatus.includes(statusCode);
+    }
+    getRetryAfterSeconds(error) {
+        if (typeof error !== 'object' || error === null) {
+            return null;
+        }
+        const headers = error.headers;
+        if (!headers) {
+            return null;
+        }
+        const retryAfter = headers.get?.('retry-after') ??
+            headers['retry-after'];
+        if (!retryAfter) {
+            return null;
+        }
+        const seconds = parseInt(retryAfter, 10);
+        return Number.isNaN(seconds) ? null : seconds;
+    }
+    calculateBackoff(attempt) {
+        const delays = [1_000, 10_000, 60_000];
+        return delays[Math.min(attempt, delays.length - 1)];
+    }
+    sleep(ms) {
+        return new Promise((resolve) => setTimeout(resolve, ms));
+    }
+    countHistoryTokens() {
+        const totalChars = this.messages.reduce((sum, msg) => sum + this.countContentChars(msg.content), 0);
+        return Math.ceil(totalChars / 4);
+    }
+    replaceHistory(history) {
+        this.messages = [...history];
+    }
+    enhanceError(error) {
+        const status = this.getStatus(error) ?? 'unknown';
+        const message = error instanceof Error ? error.message : null;
+        return new Error(`OpenAI API error [${status}]: ${message ?? JSON.stringify(error, null, 2)}`);
+    }
+    isToolError(error) {
+        const errorAsString = JSON.stringify(error, null, 2).toLowerCase();
+        if (this.getStatus(error) === 400 && errorAsString.includes('tool')) {
+            logger.warn('tool call error detected [400]');
+            void this.addUserMessage('you did not call a tool or called it incorrectly, try again and always only call a tool with correct parameters to proceed with the step.');
+            return true;
+        }
+        return false;
+    }
+    countContentChars(content) {
+        if (typeof content === 'string') {
+            return content.length;
+        }
+        if (!Array.isArray(content)) {
+            return 0;
+        }
+        let totalChars = 0;
+        for (const part of content) {
+            if ('text' in part && typeof part.text === 'string') {
+                totalChars += part.text.length;
+                continue;
+            }
+            if ('image_url' in part) {
+                const imageUrl = part.image_url;
+                if (typeof imageUrl.url === 'string') {
+                    totalChars += imageUrl.url.length;
+                }
+            }
+        }
+        return totalChars;
+    }
+}
+//# sourceMappingURL=client.js.map

package/dist/ai/client.js.map

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

package/dist/ai/message-handler.d.ts

@@ -0,0 +1,11 @@
+import { ChatCompletion } from 'openai/resources/chat/completions';
+import { Step, ResolveStepResult } from '../runtime/types';
+import { AiClient } from './client';
+import { ResponseProcessor } from './response-processor';
+export declare class MessageHandler {
+    private readonly aiClient;
+    private readonly responseProcessor;
+    constructor(aiClient: AiClient, responseProcessor: ResponseProcessor);
+    handle(choice: ChatCompletion.Choice, step: Step, resolveStepResult: ResolveStepResult): Promise<void>;
+}
+//# sourceMappingURL=message-handler.d.ts.map

package/dist/ai/message-handler.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"message-handler.d.ts","sourceRoot":"","sources":["../../src/ai/message-handler.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,cAAc,EAAE,MAAM,mCAAmC,CAAA;AAElE,OAAO,EAAE,IAAI,EAAE,iBAAiB,EAAE,MAAM,kBAAkB,CAAA;AAE1D,OAAO,EAAE,QAAQ,EAAE,MAAM,UAAU,CAAA;AACnC,OAAO,EAAE,iBAAiB,EAAE,MAAM,sBAAsB,CAAA;AAExD,qBAAa,cAAc;IAEzB,OAAO,CAAC,QAAQ,CAAC,QAAQ;IACzB,OAAO,CAAC,QAAQ,CAAC,iBAAiB;gBADjB,QAAQ,EAAE,QAAQ,EAClB,iBAAiB,EAAE,iBAAiB;IAGhD,MAAM,CAAC,MAAM,EAAE,cAAc,CAAC,MAAM,EAAE,IAAI,EAAE,IAAI,EAAE,iBAAiB,EAAE,iBAAiB,GAAG,OAAO,CAAC,IAAI,CAAC;CA8B5G"}

package/dist/ai/message-handler.js

@@ -0,0 +1,33 @@
+import { logger } from '../logging';
+import { StepResultTool } from '../tools/step/result-tool';
+export class MessageHandler {
+    aiClient;
+    responseProcessor;
+    constructor(aiClient, responseProcessor) {
+        this.aiClient = aiClient;
+        this.responseProcessor = responseProcessor;
+    }
+    async handle(choice, step, resolveStepResult) {
+        const { message } = choice;
+        if (choice.finish_reason === 'stop' || message.content) {
+            logger.warn(`text: ${message.content}`);
+            logger.warn(`warning: model responded with text but no tool call. Prompting to use ${StepResultTool.TOOL_PASS_TEST_STEP} or ${StepResultTool.TOOL_FAIL_TEST_STEP}.`);
+            await this.aiClient.addUserMessage(`You provided a text response but did not call a tool. Based on your analysis, call either '${StepResultTool.TOOL_PASS_TEST_STEP}' or '${StepResultTool.TOOL_FAIL_TEST_STEP}' with the actual result. Do not respond with text. Only use the tool.`);
+            const followUpResponse = await this.aiClient.sendToolResponseWithRetry();
+            await this.responseProcessor.handleResponse(followUpResponse, step, resolveStepResult);
+            return;
+        }
+        if (choice.finish_reason && choice.finish_reason !== 'tool_calls') {
+            resolveStepResult({
+                passed: false,
+                actual: `OpenAI API finished unexpectedly with reason: ${choice.finish_reason}`,
+            });
+            return;
+        }
+        if (!choice.message.content && (!choice.message.tool_calls || choice.message.tool_calls.length === 0)) {
+            throw new Error(`No content or tool calls found in message:\n${JSON.stringify(choice.message, null, 2)}`);
+        }
+        throw new Error(`Unhandled choice on response from model:\n${JSON.stringify(choice, null, 2)}`);
+    }
+}
+//# sourceMappingURL=message-handler.js.map

package/dist/ai/message-handler.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"message-handler.js","sourceRoot":"","sources":["../../src/ai/message-handler.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,MAAM,EAAE,MAAM,YAAY,CAAA;AAEnC,OAAO,EAAE,cAAc,EAAE,MAAM,2BAA2B,CAAA;AAI1D,MAAM,OAAO,cAAc;IAER;IACA;IAFlB,YACkB,QAAkB,EAClB,iBAAoC;QADpC,aAAQ,GAAR,QAAQ,CAAU;QAClB,sBAAiB,GAAjB,iBAAiB,CAAmB;IACnD,CAAC;IAEJ,KAAK,CAAC,MAAM,CAAC,MAA6B,EAAE,IAAU,EAAE,iBAAoC;QAC3F,MAAM,EAAE,OAAO,EAAE,GAAG,MAAM,CAAA;QAE1B,IAAI,MAAM,CAAC,aAAa,KAAK,MAAM,IAAI,OAAO,CAAC,OAAO,EAAE,CAAC;YACxD,MAAM,CAAC,IAAI,CAAC,SAAS,OAAO,CAAC,OAAO,EAAE,CAAC,CAAA;YACvC,MAAM,CAAC,IAAI,CACV,yEAAyE,cAAc,CAAC,mBAAmB,OAAO,cAAc,CAAC,mBAAmB,GAAG,CACvJ,CAAA;YACD,MAAM,IAAI,CAAC,QAAQ,CAAC,cAAc,CACjC,8FAA8F,cAAc,CAAC,mBAAmB,SAAS,cAAc,CAAC,mBAAmB,wEAAwE,CACnP,CAAA;YACD,MAAM,gBAAgB,GAAG,MAAM,IAAI,CAAC,QAAQ,CAAC,yBAAyB,EAAE,CAAA;YACxE,MAAM,IAAI,CAAC,iBAAiB,CAAC,cAAc,CAAC,gBAAgB,EAAE,IAAI,EAAE,iBAAiB,CAAC,CAAA;YACtF,OAAM;QACP,CAAC;QAED,IAAI,MAAM,CAAC,aAAa,IAAI,MAAM,CAAC,aAAa,KAAK,YAAY,EAAE,CAAC;YACnE,iBAAiB,CAAC;gBACjB,MAAM,EAAE,KAAK;gBACb,MAAM,EAAE,iDAAiD,MAAM,CAAC,aAAa,EAAE;aAC/E,CAAC,CAAA;YACF,OAAM;QACP,CAAC;QAED,IAAI,CAAC,MAAM,CAAC,OAAO,CAAC,OAAO,IAAI,CAAC,CAAC,MAAM,CAAC,OAAO,CAAC,UAAU,IAAI,MAAM,CAAC,OAAO,CAAC,UAAU,CAAC,MAAM,KAAK,CAAC,CAAC,EAAE,CAAC;YACvG,MAAM,IAAI,KAAK,CAAC,+CAA+C,IAAI,CAAC,SAAS,CAAC,MAAM,CAAC,OAAO,EAAE,IAAI,EAAE,CAAC,CAAC,EAAE,CAAC,CAAA;QAC1G,CAAC;QAED,MAAM,IAAI,KAAK,CAAC,6CAA6C,IAAI,CAAC,SAAS,CAAC,MAAM,EAAE,IAAI,EAAE,CAAC,CAAC,EAAE,CAAC,CAAA;IAChG,CAAC;CACD"}

package/dist/ai/message-history.d.ts

@@ -0,0 +1,19 @@
+import { ChatCompletionMessageParam } from 'openai/resources/chat/completions';
+import { AiClient } from './client';
+type InitialMessageParameters = {
+    systemPrompt: string;
+    userPrompt: string;
+    contextMessages?: ChatCompletionMessageParam[];
+};
+export declare class MessageHistory {
+    static readonly SNAPSHOT_IDENTIFIER = "this is a current page snapshot";
+    static readonly SCREENSHOT_IDENTIFIER = "this is a current screenshot of the page";
+    static readonly TOOL_EXECUTION_SUMMARY_IDENTIFIER = "tool execution summary";
+    buildInitialMessages(config: InitialMessageParameters): ChatCompletionMessageParam[];
+    createSnapshotMessage(snapshotContent: string | null): ChatCompletionMessageParam;
+    createScreenshotMessage(base64Data: string, mimeType?: string): ChatCompletionMessageParam;
+    removeEphemeralStateMessages(aiClient: AiClient): void;
+    private isEphemeralStateMessage;
+}
+export {};
+//# sourceMappingURL=message-history.d.ts.map

package/dist/ai/message-history.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"message-history.d.ts","sourceRoot":"","sources":["../../src/ai/message-history.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,0BAA0B,EAAE,MAAM,mCAAmC,CAAA;AAC9E,OAAO,EAAE,QAAQ,EAAE,MAAM,UAAU,CAAA;AAEnC,KAAK,wBAAwB,GAAG;IAC/B,YAAY,EAAE,MAAM,CAAA;IACpB,UAAU,EAAE,MAAM,CAAA;IAClB,eAAe,CAAC,EAAE,0BAA0B,EAAE,CAAA;CAC9C,CAAA;AAED,qBAAa,cAAc;IAC1B,MAAM,CAAC,QAAQ,CAAC,mBAAmB,qCAAoC;IACvE,MAAM,CAAC,QAAQ,CAAC,qBAAqB,8CAA6C;IAClF,MAAM,CAAC,QAAQ,CAAC,iCAAiC,4BAA2B;IAE5E,oBAAoB,CAAC,MAAM,EAAE,wBAAwB,GAAG,0BAA0B,EAAE;IAcpF,qBAAqB,CAAC,eAAe,EAAE,MAAM,GAAG,IAAI,GAAG,0BAA0B;IAOjF,uBAAuB,CAAC,UAAU,EAAE,MAAM,EAAE,QAAQ,GAAE,MAAoB,GAAG,0BAA0B;IAUvG,4BAA4B,CAAC,QAAQ,EAAE,QAAQ,GAAG,IAAI;IAItD,OAAO,CAAC,uBAAuB;CAe/B"}