@sayer/agent-step 0.1.0

package/dist/agent/model.js

@@ -0,0 +1,161 @@
+import OpenAI from 'openai';
+export function normalizeOpenAICompatibleBaseURL(baseURL) {
+    let normalized = baseURL.trim().replace(/\/+$/, '');
+    normalized = normalized.replace(/\/chat\/completions$/i, '');
+    normalized = normalized.replace(/\/+$/, '');
+    return normalized;
+}
+export function loadAgentConfig() {
+    const baseURL = process.env.AGENT_LLM_BASE_URL;
+    const apiKey = process.env.AGENT_LLM_API_KEY;
+    const model = process.env.AGENT_LLM_MODEL;
+    if (!baseURL || !apiKey || !model) {
+        throw new Error('Missing required environment variables: AGENT_LLM_BASE_URL, AGENT_LLM_API_KEY, AGENT_LLM_MODEL');
+    }
+    return {
+        baseURL: normalizeOpenAICompatibleBaseURL(baseURL),
+        apiKey,
+        model,
+    };
+}
+export function createModelClient(config) {
+    const baseURL = normalizeOpenAICompatibleBaseURL(config.baseURL);
+    const client = new OpenAI({
+        apiKey: config.apiKey,
+        baseURL,
+        defaultHeaders: {
+            'HTTP-Referer': process.env.AGENT_LLM_SITE_URL ?? 'https://github.com/Sayer122/agent-step',
+            'X-OpenRouter-Title': process.env.AGENT_LLM_SITE_NAME ?? 'agent-step',
+        },
+    });
+    return {
+        async chat(params) {
+            let response;
+            try {
+                response = await client.chat.completions.create({
+                    model: config.model,
+                    messages: params.messages.map(toOpenAIMessage),
+                    tools: params.tools?.map((tool) => ({
+                        type: 'function',
+                        function: tool.function,
+                    })),
+                    tool_choice: params.toolChoice ?? 'auto',
+                    response_format: params.responseFormat,
+                }, { signal: params.signal });
+            }
+            catch (error) {
+                throw wrapModelRequestError(error, baseURL, config.model);
+            }
+            return parseOpenAIChatResponse(response, baseURL, config.model);
+        },
+    };
+}
+export function parseOpenAIChatResponse(response, baseURL, model) {
+    const record = asRecord(response);
+    if (record?.error) {
+        throw wrapModelRequestError(embeddedProviderError(record.error), baseURL, model);
+    }
+    const choices = record?.choices;
+    const choice = Array.isArray(choices) ? asRecord(choices[0]) : undefined;
+    const message = asRecord(choice?.message);
+    if (!choice || !message) {
+        throw wrapModelRequestError(new Error(`LLM returned no chat choices. body=${truncateJson(response)}`), baseURL, model);
+    }
+    const usageRecord = asRecord(record?.usage);
+    const usage = {
+        promptTokens: numberOrZero(usageRecord?.prompt_tokens),
+        completionTokens: numberOrZero(usageRecord?.completion_tokens),
+        totalTokens: numberOrZero(usageRecord?.total_tokens),
+    };
+    return {
+        content: typeof message.content === 'string' ? message.content : null,
+        toolCalls: readToolCalls(message.tool_calls),
+        usage,
+    };
+}
+function wrapModelRequestError(error, baseURL, model) {
+    const record = asRecord(error);
+    const status = numberOrUndefined(record?.status);
+    const message = error instanceof Error ? error.message : String(error);
+    const hint = status === 404
+        ? ` Check AGENT_LLM_BASE_URL. The OpenAI SDK posts to ${baseURL}/chat/completions; for OpenRouter use https://openrouter.ai/api/v1, not .../chat/completions.`
+        : message.includes('no chat choices')
+            ? ' The provider accepted the request but returned no completion. Check AGENT_LLM_MODEL supports tool calling on this endpoint.'
+            : '';
+    return new Error(`LLM request failed (${status ?? 'unknown'}): ${message}. model=${model} baseURL=${baseURL}.${hint}`, { cause: error instanceof Error ? error : undefined });
+}
+function readToolCalls(value) {
+    if (!Array.isArray(value))
+        return [];
+    return value.flatMap((item, index) => {
+        const call = asRecord(item);
+        const fn = asRecord(call?.function);
+        const name = typeof fn?.name === 'string' ? fn.name : undefined;
+        if (!name)
+            return [];
+        return [
+            {
+                id: typeof call?.id === 'string' ? call.id : `call_${index}`,
+                name,
+                arguments: typeof fn?.arguments === 'string' ? fn.arguments : '{}',
+            },
+        ];
+    });
+}
+function embeddedProviderError(error) {
+    const record = asRecord(error);
+    const message = typeof record?.message === 'string'
+        ? record.message
+        : truncateJson(error);
+    const code = record?.code;
+    return new Error(code === undefined ? message : `${message} (code ${String(code)})`);
+}
+function asRecord(value) {
+    if (!value || typeof value !== 'object' || Array.isArray(value)) {
+        return undefined;
+    }
+    return value;
+}
+function numberOrZero(value) {
+    return typeof value === 'number' && Number.isFinite(value) ? value : 0;
+}
+function numberOrUndefined(value) {
+    return typeof value === 'number' && Number.isFinite(value) ? value : undefined;
+}
+function truncateJson(value, max = 800) {
+    try {
+        const text = JSON.stringify(value) ?? String(value);
+        return text.length > max ? `${text.slice(0, max)}…` : text;
+    }
+    catch {
+        return String(value);
+    }
+}
+function toOpenAIMessage(message) {
+    if (message.role === 'tool') {
+        return {
+            role: 'tool',
+            tool_call_id: message.toolCallId,
+            content: message.content ?? '',
+        };
+    }
+    if (message.role === 'assistant') {
+        return {
+            role: 'assistant',
+            content: message.content,
+            tool_calls: message.toolCalls?.map((call) => ({
+                id: call.id,
+                type: 'function',
+                function: {
+                    name: call.name,
+                    arguments: call.arguments,
+                },
+            })),
+        };
+    }
+    return {
+        role: message.role,
+        content: message.content ?? '',
+    };
+}
+//# sourceMappingURL=model.js.map

package/dist/agent/model.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"model.js","sourceRoot":"","sources":["../../src/agent/model.ts"],"names":[],"mappings":"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","sourcesContent":["import OpenAI from 'openai';\nimport type {\n  AgentConfig,\n  ChatParams,\n  ChatResponse,\n  ModelClient,\n  TokenUsage,\n} from './types.js';\n\nexport function normalizeOpenAICompatibleBaseURL(baseURL: string): string {\n  let normalized = baseURL.trim().replace(/\\/+$/, '');\n  normalized = normalized.replace(/\\/chat\\/completions$/i, '');\n  normalized = normalized.replace(/\\/+$/, '');\n  return normalized;\n}\n\nexport function loadAgentConfig(): AgentConfig {\n  const baseURL = process.env.AGENT_LLM_BASE_URL;\n  const apiKey = process.env.AGENT_LLM_API_KEY;\n  const model = process.env.AGENT_LLM_MODEL;\n\n  if (!baseURL || !apiKey || !model) {\n    throw new Error(\n      'Missing required environment variables: AGENT_LLM_BASE_URL, AGENT_LLM_API_KEY, AGENT_LLM_MODEL',\n    );\n  }\n\n  return {\n    baseURL: normalizeOpenAICompatibleBaseURL(baseURL),\n    apiKey,\n    model,\n  };\n}\n\nexport function createModelClient(config: AgentConfig): ModelClient {\n  const baseURL = normalizeOpenAICompatibleBaseURL(config.baseURL);\n  const client = new OpenAI({\n    apiKey: config.apiKey,\n    baseURL,\n    defaultHeaders: {\n      'HTTP-Referer': process.env.AGENT_LLM_SITE_URL ?? 'https://github.com/Sayer122/agent-step',\n      'X-OpenRouter-Title':\n        process.env.AGENT_LLM_SITE_NAME ?? 'agent-step',\n    },\n  });\n\n  return {\n    async chat(params: ChatParams): Promise<ChatResponse> {\n      let response;\n      try {\n        response = await client.chat.completions.create(\n          {\n            model: config.model,\n            messages: params.messages.map(toOpenAIMessage),\n            tools: params.tools?.map((tool) => ({\n              type: 'function' as const,\n              function: tool.function,\n            })),\n            tool_choice: params.toolChoice ?? 'auto',\n            response_format: params.responseFormat,\n          },\n          { signal: params.signal },\n        );\n      } catch (error) {\n        throw wrapModelRequestError(error, baseURL, config.model);\n      }\n\n      return parseOpenAIChatResponse(response, baseURL, config.model);\n    },\n  };\n}\n\nexport function parseOpenAIChatResponse(\n  response: unknown,\n  baseURL: string,\n  model: string,\n): ChatResponse {\n  const record = asRecord(response);\n  if (record?.error) {\n    throw wrapModelRequestError(\n      embeddedProviderError(record.error),\n      baseURL,\n      model,\n    );\n  }\n\n  const choices = record?.choices;\n  const choice = Array.isArray(choices) ? asRecord(choices[0]) : undefined;\n  const message = asRecord(choice?.message);\n\n  if (!choice || !message) {\n    throw wrapModelRequestError(\n      new Error(\n        `LLM returned no chat choices. body=${truncateJson(response)}`,\n      ),\n      baseURL,\n      model,\n    );\n  }\n\n  const usageRecord = asRecord(record?.usage);\n  const usage: TokenUsage = {\n    promptTokens: numberOrZero(usageRecord?.prompt_tokens),\n    completionTokens: numberOrZero(usageRecord?.completion_tokens),\n    totalTokens: numberOrZero(usageRecord?.total_tokens),\n  };\n\n  return {\n    content: typeof message.content === 'string' ? message.content : null,\n    toolCalls: readToolCalls(message.tool_calls),\n    usage,\n  };\n}\n\nfunction wrapModelRequestError(\n  error: unknown,\n  baseURL: string,\n  model: string,\n): Error {\n  const record = asRecord(error);\n  const status = numberOrUndefined(record?.status);\n  const message = error instanceof Error ? error.message : String(error);\n  const hint =\n    status === 404\n      ? ` Check AGENT_LLM_BASE_URL. The OpenAI SDK posts to ${baseURL}/chat/completions; for OpenRouter use https://openrouter.ai/api/v1, not .../chat/completions.`\n      : message.includes('no chat choices')\n        ? ' The provider accepted the request but returned no completion. Check AGENT_LLM_MODEL supports tool calling on this endpoint.'\n        : '';\n\n  return new Error(\n    `LLM request failed (${status ?? 'unknown'}): ${message}. model=${model} baseURL=${baseURL}.${hint}`,\n    { cause: error instanceof Error ? error : undefined },\n  );\n}\n\nfunction readToolCalls(value: unknown): ChatResponse['toolCalls'] {\n  if (!Array.isArray(value)) return [];\n  return value.flatMap((item, index) => {\n    const call = asRecord(item);\n    const fn = asRecord(call?.function);\n    const name = typeof fn?.name === 'string' ? fn.name : undefined;\n    if (!name) return [];\n    return [\n      {\n        id: typeof call?.id === 'string' ? call.id : `call_${index}`,\n        name,\n        arguments: typeof fn?.arguments === 'string' ? fn.arguments : '{}',\n      },\n    ];\n  });\n}\n\nfunction embeddedProviderError(error: unknown): Error {\n  const record = asRecord(error);\n  const message =\n    typeof record?.message === 'string'\n      ? record.message\n      : truncateJson(error);\n  const code = record?.code;\n  return new Error(\n    code === undefined ? message : `${message} (code ${String(code)})`,\n  );\n}\n\nfunction asRecord(value: unknown): Record<string, unknown> | undefined {\n  if (!value || typeof value !== 'object' || Array.isArray(value)) {\n    return undefined;\n  }\n  return value as Record<string, unknown>;\n}\n\nfunction numberOrZero(value: unknown): number {\n  return typeof value === 'number' && Number.isFinite(value) ? value : 0;\n}\n\nfunction numberOrUndefined(value: unknown): number | undefined {\n  return typeof value === 'number' && Number.isFinite(value) ? value : undefined;\n}\n\nfunction truncateJson(value: unknown, max = 800): string {\n  try {\n    const text = JSON.stringify(value) ?? String(value);\n    return text.length > max ? `${text.slice(0, max)}…` : text;\n  } catch {\n    return String(value);\n  }\n}\n\nfunction toOpenAIMessage(\n  message: ChatParams['messages'][number],\n): OpenAI.Chat.Completions.ChatCompletionMessageParam {\n  if (message.role === 'tool') {\n    return {\n      role: 'tool',\n      tool_call_id: message.toolCallId!,\n      content: message.content ?? '',\n    };\n  }\n\n  if (message.role === 'assistant') {\n    return {\n      role: 'assistant',\n      content: message.content,\n      tool_calls: message.toolCalls?.map((call) => ({\n        id: call.id,\n        type: 'function' as const,\n        function: {\n          name: call.name,\n          arguments: call.arguments,\n        },\n      })),\n    };\n  }\n\n  return {\n    role: message.role,\n    content: message.content ?? '',\n  };\n}\n"]}

package/dist/agent/redaction.d.ts

@@ -0,0 +1,4 @@
+export declare function resolveSecretValue(value: string, secrets: Record<string, string>): string;
+export declare function redactSecrets(text: string, secrets: Record<string, string>): string;
+export declare function redactObject(value: unknown, secrets: Record<string, string>): unknown;
+//# sourceMappingURL=redaction.d.ts.map

package/dist/agent/redaction.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"redaction.d.ts","sourceRoot":"","sources":["../../src/agent/redaction.ts"],"names":[],"mappings":"AAEA,wBAAgB,kBAAkB,CAChC,KAAK,EAAE,MAAM,EACb,OAAO,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,GAC9B,MAAM,CAQR;AAED,wBAAgB,aAAa,CAC3B,IAAI,EAAE,MAAM,EACZ,OAAO,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,GAC9B,MAAM,CAOR;AAED,wBAAgB,YAAY,CAC1B,KAAK,EAAE,OAAO,EACd,OAAO,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,GAC9B,OAAO,CAeT"}

package/dist/agent/redaction.js

@@ -0,0 +1,37 @@
+const SECRET_PLACEHOLDER = /^%([A-Za-z_][A-Za-z0-9_]*)%$/;
+export function resolveSecretValue(value, secrets) {
+    const match = value.match(SECRET_PLACEHOLDER);
+    if (!match)
+        return value;
+    const key = match[1];
+    if (!(key in secrets)) {
+        throw new Error(`Missing secret placeholder value for %${key}%`);
+    }
+    return secrets[key];
+}
+export function redactSecrets(text, secrets) {
+    let result = text;
+    for (const [key, value] of Object.entries(secrets)) {
+        if (!value)
+            continue;
+        result = result.split(value).join(`%${key}%`);
+    }
+    return result;
+}
+export function redactObject(value, secrets) {
+    if (typeof value === 'string') {
+        return redactSecrets(value, secrets);
+    }
+    if (Array.isArray(value)) {
+        return value.map((item) => redactObject(item, secrets));
+    }
+    if (value && typeof value === 'object') {
+        const result = {};
+        for (const [key, nested] of Object.entries(value)) {
+            result[key] = redactObject(nested, secrets);
+        }
+        return result;
+    }
+    return value;
+}
+//# sourceMappingURL=redaction.js.map

package/dist/agent/redaction.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"redaction.js","sourceRoot":"","sources":["../../src/agent/redaction.ts"],"names":[],"mappings":"AAAA,MAAM,kBAAkB,GAAG,8BAA8B,CAAC;AAE1D,MAAM,UAAU,kBAAkB,CAChC,KAAa,EACb,OAA+B;IAE/B,MAAM,KAAK,GAAG,KAAK,CAAC,KAAK,CAAC,kBAAkB,CAAC,CAAC;IAC9C,IAAI,CAAC,KAAK;QAAE,OAAO,KAAK,CAAC;IACzB,MAAM,GAAG,GAAG,KAAK,CAAC,CAAC,CAAC,CAAC;IACrB,IAAI,CAAC,CAAC,GAAG,IAAI,OAAO,CAAC,EAAE,CAAC;QACtB,MAAM,IAAI,KAAK,CAAC,yCAAyC,GAAG,GAAG,CAAC,CAAC;IACnE,CAAC;IACD,OAAO,OAAO,CAAC,GAAG,CAAC,CAAC;AACtB,CAAC;AAED,MAAM,UAAU,aAAa,CAC3B,IAAY,EACZ,OAA+B;IAE/B,IAAI,MAAM,GAAG,IAAI,CAAC;IAClB,KAAK,MAAM,CAAC,GAAG,EAAE,KAAK,CAAC,IAAI,MAAM,CAAC,OAAO,CAAC,OAAO,CAAC,EAAE,CAAC;QACnD,IAAI,CAAC,KAAK;YAAE,SAAS;QACrB,MAAM,GAAG,MAAM,CAAC,KAAK,CAAC,KAAK,CAAC,CAAC,IAAI,CAAC,IAAI,GAAG,GAAG,CAAC,CAAC;IAChD,CAAC;IACD,OAAO,MAAM,CAAC;AAChB,CAAC;AAED,MAAM,UAAU,YAAY,CAC1B,KAAc,EACd,OAA+B;IAE/B,IAAI,OAAO,KAAK,KAAK,QAAQ,EAAE,CAAC;QAC9B,OAAO,aAAa,CAAC,KAAK,EAAE,OAAO,CAAC,CAAC;IACvC,CAAC;IACD,IAAI,KAAK,CAAC,OAAO,CAAC,KAAK,CAAC,EAAE,CAAC;QACzB,OAAO,KAAK,CAAC,GAAG,CAAC,CAAC,IAAI,EAAE,EAAE,CAAC,YAAY,CAAC,IAAI,EAAE,OAAO,CAAC,CAAC,CAAC;IAC1D,CAAC;IACD,IAAI,KAAK,IAAI,OAAO,KAAK,KAAK,QAAQ,EAAE,CAAC;QACvC,MAAM,MAAM,GAA4B,EAAE,CAAC;QAC3C,KAAK,MAAM,CAAC,GAAG,EAAE,MAAM,CAAC,IAAI,MAAM,CAAC,OAAO,CAAC,KAAK,CAAC,EAAE,CAAC;YAClD,MAAM,CAAC,GAAG,CAAC,GAAG,YAAY,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;QAC9C,CAAC;QACD,OAAO,MAAM,CAAC;IAChB,CAAC;IACD,OAAO,KAAK,CAAC;AACf,CAAC","sourcesContent":["const SECRET_PLACEHOLDER = /^%([A-Za-z_][A-Za-z0-9_]*)%$/;\n\nexport function resolveSecretValue(\n  value: string,\n  secrets: Record<string, string>,\n): string {\n  const match = value.match(SECRET_PLACEHOLDER);\n  if (!match) return value;\n  const key = match[1];\n  if (!(key in secrets)) {\n    throw new Error(`Missing secret placeholder value for %${key}%`);\n  }\n  return secrets[key];\n}\n\nexport function redactSecrets(\n  text: string,\n  secrets: Record<string, string>,\n): string {\n  let result = text;\n  for (const [key, value] of Object.entries(secrets)) {\n    if (!value) continue;\n    result = result.split(value).join(`%${key}%`);\n  }\n  return result;\n}\n\nexport function redactObject(\n  value: unknown,\n  secrets: Record<string, string>,\n): unknown {\n  if (typeof value === 'string') {\n    return redactSecrets(value, secrets);\n  }\n  if (Array.isArray(value)) {\n    return value.map((item) => redactObject(item, secrets));\n  }\n  if (value && typeof value === 'object') {\n    const result: Record<string, unknown> = {};\n    for (const [key, nested] of Object.entries(value)) {\n      result[key] = redactObject(nested, secrets);\n    }\n    return result;\n  }\n  return value;\n}\n"]}

package/dist/agent/types.d.ts

@@ -0,0 +1,89 @@
+import type { Page, TestInfo } from '@playwright/test';
+export interface AgentStepInput {
+    action: string;
+    expect: string[];
+    timeout?: number;
+    secrets?: Record<string, string>;
+}
+export interface AgentStepResult {
+    action: string;
+    expect: string[];
+    actionTranscript: TranscriptEntry[];
+    verification: VerificationResult;
+    tokenUsage: TokenUsage;
+    rawVerifierContent?: string;
+}
+export interface TranscriptEntry {
+    turn: number;
+    type: 'tool_call' | 'tool_result' | 'message';
+    name?: string;
+    input?: unknown;
+    output?: unknown;
+    content?: string;
+}
+export interface TokenUsage {
+    promptTokens: number;
+    completionTokens: number;
+    totalTokens: number;
+}
+export interface CriterionVerdict {
+    criterion: string;
+    passed: boolean;
+    evidence: string;
+}
+export interface VerificationResult {
+    passed: boolean;
+    criteria: CriterionVerdict[];
+    inconclusive: boolean;
+}
+export interface AgentRuntimeOptions {
+    page: Page;
+    testInfo: TestInfo;
+    allowedOrigins?: string[];
+    maxTurns?: number;
+    defaultTimeout?: number;
+    /** Override model client for deterministic framework tests. */
+    modelClient?: ModelClient;
+}
+export interface ModelClient {
+    chat(params: ChatParams): Promise<ChatResponse>;
+}
+export interface ChatParams {
+    messages: ChatMessage[];
+    tools?: ToolDefinition[];
+    toolChoice?: 'auto' | 'none' | 'required';
+    responseFormat?: {
+        type: 'json_object';
+    };
+    signal?: AbortSignal;
+}
+export interface ChatMessage {
+    role: 'system' | 'user' | 'assistant' | 'tool';
+    content?: string | null;
+    toolCallId?: string;
+    toolCalls?: ToolCall[];
+}
+export interface ToolCall {
+    id: string;
+    name: string;
+    arguments: string;
+}
+export interface ToolDefinition {
+    type: 'function';
+    function: {
+        name: string;
+        description: string;
+        parameters: Record<string, unknown>;
+    };
+}
+export interface ChatResponse {
+    content: string | null;
+    toolCalls: ToolCall[];
+    usage: TokenUsage;
+}
+export interface AgentConfig {
+    baseURL: string;
+    apiKey: string;
+    model: string;
+}
+//# sourceMappingURL=types.d.ts.map

package/dist/agent/types.d.ts.map

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

package/dist/agent/types.js

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=types.js.map

package/dist/agent/types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.js","sourceRoot":"","sources":["../../src/agent/types.ts"],"names":[],"mappings":"","sourcesContent":["import type { Page, TestInfo } from '@playwright/test';\n\nexport interface AgentStepInput {\n  action: string;\n  expect: string[];\n  timeout?: number;\n  secrets?: Record<string, string>;\n}\n\nexport interface AgentStepResult {\n  action: string;\n  expect: string[];\n  actionTranscript: TranscriptEntry[];\n  verification: VerificationResult;\n  tokenUsage: TokenUsage;\n  rawVerifierContent?: string;\n}\n\nexport interface TranscriptEntry {\n  turn: number;\n  type: 'tool_call' | 'tool_result' | 'message';\n  name?: string;\n  input?: unknown;\n  output?: unknown;\n  content?: string;\n}\n\nexport interface TokenUsage {\n  promptTokens: number;\n  completionTokens: number;\n  totalTokens: number;\n}\n\nexport interface CriterionVerdict {\n  criterion: string;\n  passed: boolean;\n  evidence: string;\n}\n\nexport interface VerificationResult {\n  passed: boolean;\n  criteria: CriterionVerdict[];\n  inconclusive: boolean;\n}\n\nexport interface AgentRuntimeOptions {\n  page: Page;\n  testInfo: TestInfo;\n  allowedOrigins?: string[];\n  maxTurns?: number;\n  defaultTimeout?: number;\n  /** Override model client for deterministic framework tests. */\n  modelClient?: ModelClient;\n}\n\nexport interface ModelClient {\n  chat(params: ChatParams): Promise<ChatResponse>;\n}\n\nexport interface ChatParams {\n  messages: ChatMessage[];\n  tools?: ToolDefinition[];\n  toolChoice?: 'auto' | 'none' | 'required';\n  responseFormat?: { type: 'json_object' };\n  signal?: AbortSignal;\n}\n\nexport interface ChatMessage {\n  role: 'system' | 'user' | 'assistant' | 'tool';\n  content?: string | null;\n  toolCallId?: string;\n  toolCalls?: ToolCall[];\n}\n\nexport interface ToolCall {\n  id: string;\n  name: string;\n  arguments: string;\n}\n\nexport interface ToolDefinition {\n  type: 'function';\n  function: {\n    name: string;\n    description: string;\n    parameters: Record<string, unknown>;\n  };\n}\n\nexport interface ChatResponse {\n  content: string | null;\n  toolCalls: ToolCall[];\n  usage: TokenUsage;\n}\n\nexport interface AgentConfig {\n  baseURL: string;\n  apiKey: string;\n  model: string;\n}\n"]}

package/dist/agent/verifier.d.ts

@@ -0,0 +1,22 @@
+import type { ModelClient, TokenUsage, VerificationResult } from './types.js';
+export interface VerifierOptions {
+    modelClient: ModelClient;
+    expect: string[];
+    snapshot: unknown;
+    url: string;
+    signal: AbortSignal;
+}
+export interface VerifierResult {
+    verification: VerificationResult;
+    tokenUsage: TokenUsage;
+    rawContent: string;
+}
+export declare class Verifier {
+    private readonly options;
+    constructor(options: VerifierOptions);
+    run(): Promise<VerifierResult>;
+    private requestVerdict;
+}
+export declare function parseJsonObject(content: string): Record<string, unknown>;
+export declare function normalizeVerification(parsed: Record<string, unknown>, expected: string[]): VerificationResult;
+//# sourceMappingURL=verifier.d.ts.map

package/dist/agent/verifier.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"verifier.d.ts","sourceRoot":"","sources":["../../src/agent/verifier.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAEV,WAAW,EACX,UAAU,EACV,kBAAkB,EACnB,MAAM,YAAY,CAAC;AAEpB,MAAM,WAAW,eAAe;IAC9B,WAAW,EAAE,WAAW,CAAC;IACzB,MAAM,EAAE,MAAM,EAAE,CAAC;IACjB,QAAQ,EAAE,OAAO,CAAC;IAClB,GAAG,EAAE,MAAM,CAAC;IACZ,MAAM,EAAE,WAAW,CAAC;CACrB;AAED,MAAM,WAAW,cAAc;IAC7B,YAAY,EAAE,kBAAkB,CAAC;IACjC,UAAU,EAAE,UAAU,CAAC;IACvB,UAAU,EAAE,MAAM,CAAC;CACpB;AAcD,qBAAa,QAAQ;IACP,OAAO,CAAC,QAAQ,CAAC,OAAO;gBAAP,OAAO,EAAE,eAAe;IAE/C,GAAG,IAAI,OAAO,CAAC,cAAc,CAAC;YAkCtB,cAAc;CAsD7B;AAED,wBAAgB,eAAe,CAAC,OAAO,EAAE,MAAM,GAAG,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAcxE;AAED,wBAAgB,qBAAqB,CACnC,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAC/B,QAAQ,EAAE,MAAM,EAAE,GACjB,kBAAkB,CA4CpB"}

package/dist/agent/verifier.js

@@ -0,0 +1,209 @@
+const VERIFIER_SYSTEM_PROMPT = [
+    'You are a read-only test verifier.',
+    'Given an accessibility snapshot and pass criteria, decide whether each criterion is satisfied.',
+    'Use only evidence visible in the snapshot or URL.',
+    'If evidence is insufficient, set passed=false for that criterion and inconclusive=true.',
+    'Respond with a JSON object only. Do not wrap it in markdown.',
+    'Required shape:',
+    '{"inconclusive":false,"criteria":[{"criterion":"<exact expected string>","passed":true,"evidence":"<short visible evidence>"}]}',
+    'Every criteria item MUST include boolean passed and string evidence.',
+    'Include one criteria object for every expected string, using the expected text as criterion.',
+].join(' ');
+export class Verifier {
+    options;
+    constructor(options) {
+        this.options = options;
+    }
+    async run() {
+        const first = await this.requestVerdict(undefined);
+        const firstVerification = normalizeVerification(first.parsed, this.options.expect);
+        if (!needsRepair(firstVerification)) {
+            return {
+                verification: firstVerification,
+                tokenUsage: first.usage,
+                rawContent: first.content,
+            };
+        }
+        const repaired = await this.requestVerdict(first.content);
+        const repairedVerification = normalizeVerification(repaired.parsed, this.options.expect);
+        const tokenUsage = {
+            promptTokens: first.usage.promptTokens + repaired.usage.promptTokens,
+            completionTokens: first.usage.completionTokens + repaired.usage.completionTokens,
+            totalTokens: first.usage.totalTokens + repaired.usage.totalTokens,
+        };
+        return {
+            verification: repairedVerification,
+            tokenUsage,
+            rawContent: repaired.content,
+        };
+    }
+    async requestVerdict(previousContent) {
+        const response = await this.options.modelClient.chat({
+            messages: [
+                {
+                    role: 'system',
+                    content: VERIFIER_SYSTEM_PROMPT,
+                },
+                {
+                    role: 'user',
+                    content: JSON.stringify({
+                        url: this.options.url,
+                        snapshot: this.options.snapshot,
+                        expect: this.options.expect,
+                    }, null, 2),
+                },
+                ...(previousContent
+                    ? [
+                        {
+                            role: 'assistant',
+                            content: previousContent,
+                        },
+                        {
+                            role: 'user',
+                            content: 'That JSON omitted required fields. Reply with JSON only in this exact shape: {"inconclusive":false,"criteria":[{"criterion":"<exact expected string>","passed":true,"evidence":"<short visible evidence>"}]}. Include every expected criterion, with boolean passed and string evidence on each item.',
+                        },
+                    ]
+                    : []),
+            ],
+            toolChoice: 'none',
+            responseFormat: { type: 'json_object' },
+            signal: this.options.signal,
+        });
+        if (!response.content) {
+            throw new Error('Verifier returned empty content');
+        }
+        return {
+            content: response.content,
+            parsed: parseJsonObject(response.content),
+            usage: response.usage,
+        };
+    }
+}
+export function parseJsonObject(content) {
+    const trimmed = content.trim();
+    const fenced = trimmed.match(/```(?:json)?\s*([\s\S]*?)```/i);
+    const candidate = fenced ? fenced[1].trim() : trimmed;
+    try {
+        const parsed = JSON.parse(candidate);
+        if (!parsed || typeof parsed !== 'object' || Array.isArray(parsed)) {
+            throw new Error('Verifier JSON was not an object');
+        }
+        return parsed;
+    }
+    catch {
+        throw new Error(`Verifier returned malformed JSON: ${truncate(content)}`);
+    }
+}
+export function normalizeVerification(parsed, expected) {
+    const rawCriteria = Array.isArray(parsed.criteria)
+        ? parsed.criteria
+        : Array.isArray(parsed.results)
+            ? parsed.results
+            : [];
+    const normalized = rawCriteria.map((item, index) => normalizeCriterion(item, expected[index]));
+    const criteria = expected.map((criterion, index) => {
+        const exact = normalized.find((item) => item.criterion === criterion);
+        if (exact)
+            return { ...exact, criterion };
+        const loose = normalized.find((item) => item.criterion.trim().toLowerCase() === criterion.trim().toLowerCase());
+        if (loose)
+            return { ...loose, criterion };
+        if (normalized.length === expected.length) {
+            return { ...normalized[index], criterion };
+        }
+        return {
+            criterion,
+            passed: false,
+            evidence: 'Verifier did not return a verdict for this criterion',
+        };
+    });
+    const omittedVerdict = criteria.some((item) => item.evidence.startsWith('Verifier omitted') ||
+        item.evidence.startsWith('Verifier did not return') ||
+        item.evidence.startsWith('Verifier returned a non-object'));
+    const inconclusive = coerceBoolean(parsed.inconclusive) === true || omittedVerdict;
+    return {
+        passed: !inconclusive && criteria.every((item) => item.passed),
+        criteria,
+        inconclusive,
+    };
+}
+function needsRepair(verification) {
+    return verification.criteria.some((item) => item.evidence.startsWith('Verifier omitted') ||
+        item.evidence.startsWith('Verifier did not return') ||
+        item.evidence.startsWith('Verifier returned a non-object'));
+}
+function normalizeCriterion(item, fallbackCriterion) {
+    if (typeof item === 'string') {
+        return {
+            criterion: item,
+            passed: false,
+            evidence: 'Verifier omitted boolean passed and string evidence',
+        };
+    }
+    if (!item || typeof item !== 'object') {
+        return {
+            criterion: fallbackCriterion ?? 'unknown',
+            passed: false,
+            evidence: 'Verifier returned a non-object criterion',
+        };
+    }
+    const record = item;
+    const criterion = readString(record.criterion) ??
+        readString(record.expected) ??
+        readString(record.text) ??
+        fallbackCriterion ??
+        'unknown';
+    const passed = coerceBoolean(record.passed ??
+        record.pass ??
+        record.ok ??
+        record.met ??
+        record.satisfied ??
+        record.success ??
+        record.status);
+    const evidence = readString(record.evidence) ??
+        readString(record.reason) ??
+        readString(record.explanation) ??
+        readString(record.details) ??
+        readString(record.notes);
+    if (passed === undefined) {
+        return {
+            criterion,
+            passed: false,
+            evidence: evidence
+                ? `Verifier omitted boolean passed. ${evidence}`
+                : 'Verifier omitted boolean passed and string evidence',
+        };
+    }
+    return {
+        criterion,
+        passed,
+        evidence: evidence ?? 'Verifier omitted evidence',
+    };
+}
+function coerceBoolean(value) {
+    if (typeof value === 'boolean')
+        return value;
+    if (typeof value === 'number') {
+        if (value === 1)
+            return true;
+        if (value === 0)
+            return false;
+    }
+    if (typeof value === 'string') {
+        const normalized = value.trim().toLowerCase();
+        if (['true', 'pass', 'passed', 'yes', 'ok', 'success'].includes(normalized)) {
+            return true;
+        }
+        if (['false', 'fail', 'failed', 'no', 'not_passed'].includes(normalized)) {
+            return false;
+        }
+    }
+    return undefined;
+}
+function readString(value) {
+    return typeof value === 'string' && value.trim() ? value : undefined;
+}
+function truncate(value, max = 500) {
+    return value.length > max ? `${value.slice(0, max)}…` : value;
+}
+//# sourceMappingURL=verifier.js.map

package/dist/agent/verifier.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"verifier.js","sourceRoot":"","sources":["../../src/agent/verifier.ts"],"names":[],"mappings":"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","sourcesContent":["import type {\n  CriterionVerdict,\n  ModelClient,\n  TokenUsage,\n  VerificationResult,\n} from './types.js';\n\nexport interface VerifierOptions {\n  modelClient: ModelClient;\n  expect: string[];\n  snapshot: unknown;\n  url: string;\n  signal: AbortSignal;\n}\n\nexport interface VerifierResult {\n  verification: VerificationResult;\n  tokenUsage: TokenUsage;\n  rawContent: string;\n}\n\nconst VERIFIER_SYSTEM_PROMPT = [\n  'You are a read-only test verifier.',\n  'Given an accessibility snapshot and pass criteria, decide whether each criterion is satisfied.',\n  'Use only evidence visible in the snapshot or URL.',\n  'If evidence is insufficient, set passed=false for that criterion and inconclusive=true.',\n  'Respond with a JSON object only. Do not wrap it in markdown.',\n  'Required shape:',\n  '{\"inconclusive\":false,\"criteria\":[{\"criterion\":\"<exact expected string>\",\"passed\":true,\"evidence\":\"<short visible evidence>\"}]}',\n  'Every criteria item MUST include boolean passed and string evidence.',\n  'Include one criteria object for every expected string, using the expected text as criterion.',\n].join(' ');\n\nexport class Verifier {\n  constructor(private readonly options: VerifierOptions) {}\n\n  async run(): Promise<VerifierResult> {\n    const first = await this.requestVerdict(undefined);\n    const firstVerification = normalizeVerification(\n      first.parsed,\n      this.options.expect,\n    );\n\n    if (!needsRepair(firstVerification)) {\n      return {\n        verification: firstVerification,\n        tokenUsage: first.usage,\n        rawContent: first.content,\n      };\n    }\n\n    const repaired = await this.requestVerdict(first.content);\n    const repairedVerification = normalizeVerification(\n      repaired.parsed,\n      this.options.expect,\n    );\n    const tokenUsage = {\n      promptTokens: first.usage.promptTokens + repaired.usage.promptTokens,\n      completionTokens:\n        first.usage.completionTokens + repaired.usage.completionTokens,\n      totalTokens: first.usage.totalTokens + repaired.usage.totalTokens,\n    };\n\n    return {\n      verification: repairedVerification,\n      tokenUsage,\n      rawContent: repaired.content,\n    };\n  }\n\n  private async requestVerdict(\n    previousContent: string | undefined,\n  ): Promise<{\n    content: string;\n    parsed: Record<string, unknown>;\n    usage: TokenUsage;\n  }> {\n    const response = await this.options.modelClient.chat({\n      messages: [\n        {\n          role: 'system',\n          content: VERIFIER_SYSTEM_PROMPT,\n        },\n        {\n          role: 'user',\n          content: JSON.stringify(\n            {\n              url: this.options.url,\n              snapshot: this.options.snapshot,\n              expect: this.options.expect,\n            },\n            null,\n            2,\n          ),\n        },\n        ...(previousContent\n          ? [\n              {\n                role: 'assistant' as const,\n                content: previousContent,\n              },\n              {\n                role: 'user' as const,\n                content:\n                  'That JSON omitted required fields. Reply with JSON only in this exact shape: {\"inconclusive\":false,\"criteria\":[{\"criterion\":\"<exact expected string>\",\"passed\":true,\"evidence\":\"<short visible evidence>\"}]}. Include every expected criterion, with boolean passed and string evidence on each item.',\n              },\n            ]\n          : []),\n      ],\n      toolChoice: 'none',\n      responseFormat: { type: 'json_object' },\n      signal: this.options.signal,\n    });\n\n    if (!response.content) {\n      throw new Error('Verifier returned empty content');\n    }\n\n    return {\n      content: response.content,\n      parsed: parseJsonObject(response.content),\n      usage: response.usage,\n    };\n  }\n}\n\nexport function parseJsonObject(content: string): Record<string, unknown> {\n  const trimmed = content.trim();\n  const fenced = trimmed.match(/```(?:json)?\\s*([\\s\\S]*?)```/i);\n  const candidate = fenced ? fenced[1].trim() : trimmed;\n\n  try {\n    const parsed = JSON.parse(candidate) as unknown;\n    if (!parsed || typeof parsed !== 'object' || Array.isArray(parsed)) {\n      throw new Error('Verifier JSON was not an object');\n    }\n    return parsed as Record<string, unknown>;\n  } catch {\n    throw new Error(`Verifier returned malformed JSON: ${truncate(content)}`);\n  }\n}\n\nexport function normalizeVerification(\n  parsed: Record<string, unknown>,\n  expected: string[],\n): VerificationResult {\n  const rawCriteria = Array.isArray(parsed.criteria)\n    ? parsed.criteria\n    : Array.isArray(parsed.results)\n      ? parsed.results\n      : [];\n\n  const normalized = rawCriteria.map((item, index) =>\n    normalizeCriterion(item, expected[index]),\n  );\n\n  const criteria = expected.map((criterion, index) => {\n    const exact = normalized.find((item) => item.criterion === criterion);\n    if (exact) return { ...exact, criterion };\n\n    const loose = normalized.find(\n      (item) => item.criterion.trim().toLowerCase() === criterion.trim().toLowerCase(),\n    );\n    if (loose) return { ...loose, criterion };\n\n    if (normalized.length === expected.length) {\n      return { ...normalized[index], criterion };\n    }\n\n    return {\n      criterion,\n      passed: false,\n      evidence: 'Verifier did not return a verdict for this criterion',\n    };\n  });\n\n  const omittedVerdict = criteria.some((item) =>\n    item.evidence.startsWith('Verifier omitted') ||\n    item.evidence.startsWith('Verifier did not return') ||\n    item.evidence.startsWith('Verifier returned a non-object'),\n  );\n  const inconclusive =\n    coerceBoolean(parsed.inconclusive) === true || omittedVerdict;\n\n  return {\n    passed: !inconclusive && criteria.every((item) => item.passed),\n    criteria,\n    inconclusive,\n  };\n}\n\nfunction needsRepair(verification: VerificationResult): boolean {\n  return verification.criteria.some(\n    (item) =>\n      item.evidence.startsWith('Verifier omitted') ||\n      item.evidence.startsWith('Verifier did not return') ||\n      item.evidence.startsWith('Verifier returned a non-object'),\n  );\n}\n\nfunction normalizeCriterion(\n  item: unknown,\n  fallbackCriterion?: string,\n): CriterionVerdict {\n  if (typeof item === 'string') {\n    return {\n      criterion: item,\n      passed: false,\n      evidence: 'Verifier omitted boolean passed and string evidence',\n    };\n  }\n\n  if (!item || typeof item !== 'object') {\n    return {\n      criterion: fallbackCriterion ?? 'unknown',\n      passed: false,\n      evidence: 'Verifier returned a non-object criterion',\n    };\n  }\n\n  const record = item as Record<string, unknown>;\n  const criterion =\n    readString(record.criterion) ??\n    readString(record.expected) ??\n    readString(record.text) ??\n    fallbackCriterion ??\n    'unknown';\n\n  const passed = coerceBoolean(\n    record.passed ??\n      record.pass ??\n      record.ok ??\n      record.met ??\n      record.satisfied ??\n      record.success ??\n      record.status,\n  );\n\n  const evidence =\n    readString(record.evidence) ??\n    readString(record.reason) ??\n    readString(record.explanation) ??\n    readString(record.details) ??\n    readString(record.notes);\n\n  if (passed === undefined) {\n    return {\n      criterion,\n      passed: false,\n      evidence: evidence\n        ? `Verifier omitted boolean passed. ${evidence}`\n        : 'Verifier omitted boolean passed and string evidence',\n    };\n  }\n\n  return {\n    criterion,\n    passed,\n    evidence: evidence ?? 'Verifier omitted evidence',\n  };\n}\n\nfunction coerceBoolean(value: unknown): boolean | undefined {\n  if (typeof value === 'boolean') return value;\n  if (typeof value === 'number') {\n    if (value === 1) return true;\n    if (value === 0) return false;\n  }\n  if (typeof value === 'string') {\n    const normalized = value.trim().toLowerCase();\n    if (['true', 'pass', 'passed', 'yes', 'ok', 'success'].includes(normalized)) {\n      return true;\n    }\n    if (['false', 'fail', 'failed', 'no', 'not_passed'].includes(normalized)) {\n      return false;\n    }\n  }\n  return undefined;\n}\n\nfunction readString(value: unknown): string | undefined {\n  return typeof value === 'string' && value.trim() ? value : undefined;\n}\n\nfunction truncate(value: string, max = 500): string {\n  return value.length > max ? `${value.slice(0, max)}…` : value;\n}\n"]}

package/dist/agent-step.d.ts

@@ -0,0 +1,10 @@
+import { type Page, type TestInfo } from '@playwright/test';
+import type { AgentStepInput, AgentStepResult } from './agent/types.js';
+export type AgentStep = (input: AgentStepInput) => Promise<AgentStepResult>;
+export interface CreateAgentStepOptions {
+    page: Page;
+    testInfo: TestInfo;
+}
+export declare function createAgentStep({ page, testInfo, }: CreateAgentStepOptions): AgentStep;
+export declare function agentStep(page: Page, input: AgentStepInput): Promise<AgentStepResult>;
+//# sourceMappingURL=agent-step.d.ts.map

package/dist/agent-step.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"agent-step.d.ts","sourceRoot":"","sources":["../src/agent-step.ts"],"names":[],"mappings":"AAAA,OAAO,EAAQ,KAAK,IAAI,EAAE,KAAK,QAAQ,EAAE,MAAM,kBAAkB,CAAC;AAGlE,OAAO,KAAK,EAAE,cAAc,EAAE,eAAe,EAAE,MAAM,kBAAkB,CAAC;AAExE,MAAM,MAAM,SAAS,GAAG,CAAC,KAAK,EAAE,cAAc,KAAK,OAAO,CAAC,eAAe,CAAC,CAAC;AAE5E,MAAM,WAAW,sBAAsB;IACrC,IAAI,EAAE,IAAI,CAAC;IACX,QAAQ,EAAE,QAAQ,CAAC;CACpB;AAED,wBAAgB,eAAe,CAAC,EAC9B,IAAI,EACJ,QAAQ,GACT,EAAE,sBAAsB,GAAG,SAAS,CA4EpC;AAED,wBAAsB,SAAS,CAC7B,IAAI,EAAE,IAAI,EACV,KAAK,EAAE,cAAc,GACpB,OAAO,CAAC,eAAe,CAAC,CAE1B"}