@taodigital/agents 0.0.0-stage → 1.2.0

package/dist/test-script-agent.d.ts

@@ -0,0 +1,16 @@
+export interface ExecutionStep {
+    stepNumber: number;
+    description: string;
+    action: 'navigate' | 'click' | 'fill' | 'select' | 'assert_visible' | 'assert_text' | 'assert_url' | 'wait' | 'screenshot' | 'hover' | 'press_key' | 'script' | 'setVariable';
+    selector?: string;
+    selectorStrategy?: 'css' | 'text' | 'role' | 'label';
+    value?: string;
+    url?: string;
+    timeout?: number;
+    optional?: boolean;
+}
+export declare function generateExecutionPlan(tenantId: string, testCase: {
+    title: string;
+    steps: unknown;
+    preconditions?: string | null;
+}, baseUrl: string): Promise<ExecutionStep[]>;

package/dist/test-script-agent.js

@@ -0,0 +1,48 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.generateExecutionPlan = generateExecutionPlan;
+const core_1 = require("@taodigital/core");
+const llm_js_1 = require("./llm.js");
+const llm_config_js_1 = require("./llm-config.js");
+const SYSTEM_DEFAULT = `You are a test execution planner. Convert human-readable test steps into a structured JSON array of ExecutionStep objects.
+
+Rules:
+- Map "click on X" / "click X" / "tap X" → action: "click", selectorStrategy: "text", selector: "X"
+- Map ANY fill/type/enter/input step "enter X in Y" / "type X in Y" / "fill X in Y" / "enter X into Y" / "type X into Y" / "input X in Y" → action: "fill", selectorStrategy: "label", selector: "<core label of Y — strip 'the', strip trailing 'field/input/box/area'>", value: "X"
+- Map "navigate to X" / "go to X" / "open X" → action: "navigate", url: "X"
+- Map "assert X visible" / "verify X is shown" → action: "assert_visible", selectorStrategy: "text", selector: "X"
+- Map "assert X contains Y" → action: "assert_text", selector: "X", value: "Y"
+- Map "wait N seconds" → action: "wait", timeout: N*1000
+- Map "Execute script (setVariable): X" or anything ending with "-> script:setVariable" → action: "setVariable", value: "X"
+- Map "Execute script: X" or anything ending with "-> script" → action: "script", value: "X"
+- Use selectorStrategy: "label" for ALL form field interactions (inputs, textareas, selects) — the selector must be the SHORT visible label, not the full phrase like "the Username input field"
+- Use selectorStrategy: "role" for buttons, checkboxes, links by their accessible name
+- Use selectorStrategy: "text" for text-matched elements or assertions
+- Use selectorStrategy: "css" only when a specific CSS selector is evident
+- Keep selector values SHORT: "Username" not "the Username input field", "Email" not "email address input"
+- Return ONLY the JSON array, no explanation`;
+async function generateExecutionPlan(tenantId, testCase, baseUrl) {
+    const llmCfg = await (0, llm_config_js_1.getTaskAgentLLMConfig)(tenantId, 'testRunner');
+    const steps = Array.isArray(testCase.steps) ? testCase.steps : [];
+    const preconditions = typeof testCase.preconditions === 'string' && testCase.preconditions
+        ? [testCase.preconditions]
+        : [];
+    const prompt = [
+        preconditions.length > 0 ? `Preconditions: ${preconditions.join('. ')}` : '',
+        `Base URL: ${baseUrl}`,
+        `Test: ${testCase.title}`,
+        `Steps:\n${steps.map((s, i) => `${i + 1}. ${s}`).join('\n')}`,
+    ].filter(Boolean).join('\n\n');
+    const seed = (0, llm_js_1.deterministicSeed)(`${tenantId}:${testCase.title}:${steps.join('|').slice(0, 300)}:${baseUrl}`);
+    const system = await (0, core_1.getAgentPrompt)('test-script-execution', undefined, tenantId) ?? SYSTEM_DEFAULT;
+    const { text } = await (0, llm_js_1.askTracked)(system, prompt, llmCfg, 8192, undefined, { temperature: 0, seed });
+    try {
+        // Strip markdown fences if the model wraps in ```json ... ```
+        const cleaned = text.trim().replace(/^```(?:json)?\s*/i, '').replace(/\s*```$/, '');
+        const parsed = JSON.parse(cleaned);
+        return Array.isArray(parsed) ? parsed.map((s, i) => ({ ...s, stepNumber: i })) : [];
+    }
+    catch {
+        return [];
+    }
+}

package/dist/token-pricing.d.ts

@@ -0,0 +1,14 @@
+import type { LLMUsage } from '@taodigital/core';
+export interface ProviderPricing {
+    inputPer1M: number;
+    outputPer1M: number;
+    cacheReadPer1M?: number;
+    cacheWritePer1M?: number;
+}
+export declare const PRICING: Record<string, ProviderPricing>;
+/**
+ * Load pricing overrides from the LlmPricing DB table into the in-process cache.
+ * Call once at agent worker startup — does not require making estimateCost() async.
+ */
+export declare function loadPricingOverrides(): Promise<void>;
+export declare function estimateCost(usage: Omit<LLMUsage, 'estimatedCostUsd'>, providerKey: string): number;

package/dist/token-pricing.js

@@ -0,0 +1,62 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.PRICING = void 0;
+exports.loadPricingOverrides = loadPricingOverrides;
+exports.estimateCost = estimateCost;
+const database_1 = require("@taodigital/database");
+exports.PRICING = {
+    // Anthropic (as of mid-2025)
+    'anthropic/claude-sonnet-4-6': { inputPer1M: 3.00, outputPer1M: 15.00, cacheReadPer1M: 0.30, cacheWritePer1M: 3.75 },
+    'anthropic/claude-haiku-4-5': { inputPer1M: 0.80, outputPer1M: 4.00, cacheReadPer1M: 0.08, cacheWritePer1M: 1.00 },
+    'anthropic/claude-opus-4-8': { inputPer1M: 15.00, outputPer1M: 75.00, cacheReadPer1M: 1.50, cacheWritePer1M: 18.75 },
+    'anthropic/claude-3-5-sonnet-20241022': { inputPer1M: 3.00, outputPer1M: 15.00, cacheReadPer1M: 0.30, cacheWritePer1M: 3.75 },
+    // OpenAI
+    'openai/gpt-4o': { inputPer1M: 2.50, outputPer1M: 10.00 },
+    'openai/gpt-4o-mini': { inputPer1M: 0.15, outputPer1M: 0.60 },
+    'openai/o3-mini': { inputPer1M: 1.10, outputPer1M: 4.40 },
+    // Gemini
+    'gemini/gemini-2.5-pro': { inputPer1M: 1.25, outputPer1M: 10.00 },
+    'gemini/gemini-2.0-flash': { inputPer1M: 0.10, outputPer1M: 0.40 },
+    // Grok
+    'grok/grok-3': { inputPer1M: 3.00, outputPer1M: 15.00 },
+    // OpenRouter (acts as a router — pricing varies per routed model)
+    // Estimate using the underlying model's price
+    'openrouter/*': { inputPer1M: 3.00, outputPer1M: 15.00 },
+    // Ollama (local — zero cost)
+    'ollama/*': { inputPer1M: 0, outputPer1M: 0 },
+};
+// In-process cache loaded by loadPricingOverrides() at agent startup.
+// Keys are "provider/model"; values override the static PRICING table.
+const _pricingOverrides = new Map();
+/**
+ * Load pricing overrides from the LlmPricing DB table into the in-process cache.
+ * Call once at agent worker startup — does not require making estimateCost() async.
+ */
+async function loadPricingOverrides() {
+    try {
+        const rows = await database_1.prismaAdmin.llmPricing.findMany({
+            select: { modelKey: true, inputPer1M: true, outputPer1M: true, cacheReadPer1M: true, cacheWritePer1M: true },
+        });
+        for (const row of rows) {
+            _pricingOverrides.set(row.modelKey, {
+                inputPer1M: row.inputPer1M,
+                outputPer1M: row.outputPer1M,
+                cacheReadPer1M: row.cacheReadPer1M,
+                cacheWritePer1M: row.cacheWritePer1M,
+            });
+        }
+    }
+    catch { /* DB unavailable — fall back to static PRICING */ }
+}
+function estimateCost(usage, providerKey) {
+    const pricing = _pricingOverrides.get(providerKey)
+        ?? _pricingOverrides.get(`${usage.provider}/*`)
+        ?? exports.PRICING[providerKey]
+        ?? exports.PRICING[`${usage.provider}/*`]
+        ?? { inputPer1M: 3, outputPer1M: 15 };
+    const inputCost = (usage.promptTokens / 1_000_000) * pricing.inputPer1M;
+    const outputCost = (usage.completionTokens / 1_000_000) * pricing.outputPer1M;
+    const cacheRead = ((usage.cacheReadTokens ?? 0) / 1_000_000) * (pricing.cacheReadPer1M ?? 0);
+    const cacheWrite = ((usage.cacheWriteTokens ?? 0) / 1_000_000) * (pricing.cacheWritePer1M ?? 0);
+    return parseFloat((inputCost + outputCost + cacheRead + cacheWrite).toFixed(6));
+}

package/dist/types.d.ts

@@ -0,0 +1,232 @@
+/**
+ * Gap 1: Contract interfaces for @taodigital/agents.
+ * Routes should import from this file and depend on interfaces, not implementations.
+ * This enables swapping agent implementations without touching route code.
+ */
+import type { LLMConfig } from './llm.js';
+export interface GenerateTestCasesOpts {
+    tenantId: string;
+    projectId: string;
+    screenId: string;
+    jobId?: string;
+    oversized?: boolean;
+    viewport?: string;
+    apiEndpoints?: Array<{
+        method: string;
+        urlPattern: string;
+    }>;
+    suiteNameOverride?: string;
+    force?: boolean;
+    fullCoverage?: boolean;
+    suiteLastGenAt?: Date;
+    /**
+     * 'append' (default) — deduplicates by content hash + grounding hash + title Jaccard.
+     * 'replace'          — deletes existing AI-generated cases for this screen before inserting.
+     * 'edit'             — upserts: updates steps/gherkin/expectedResult on matched cases.
+     */
+    mode?: 'replace' | 'append' | 'edit';
+    repository?: {
+        getChangedScreenIds: (tenantId: string, projectId: string, sinceDate: Date) => Promise<string[]>;
+    };
+    llmCfg?: LLMConfig;
+    fastPassLlmCfg?: LLMConfig;
+    /** Override hardcoded GLOBAL_RULES_FALLBACK — load via agent-prompts.ts before calling. */
+    globalRules?: string;
+}
+export interface GenerateTestCasesResult {
+    skipped?: boolean;
+    reason?: string;
+    existingCaseCount?: number;
+    saved?: unknown[];
+    cases?: unknown[];
+}
+export interface RegenerateTestCaseTitleOpts {
+    tenantId: string;
+    testCaseId: string;
+    currentTitle: string;
+    screenName?: string;
+    steps?: string[];
+    expectedResult?: string;
+    kind?: string;
+    attempt?: number;
+}
+export interface TestGenerationAgent {
+    generateTestCases(opts: GenerateTestCasesOpts): Promise<GenerateTestCasesResult>;
+    regenerateTestCaseTitle(opts: RegenerateTestCaseTitleOpts): Promise<{
+        title: string;
+    }>;
+}
+export interface GenerateTestDataOpts {
+    tenantId: string;
+    projectId: string;
+    testCaseId: string;
+    jobId?: string;
+    targetCount?: number;
+    /** Called at key pipeline stages with real progress (0–95). */
+    onProgress?: (pct: number, step: string) => void;
+}
+export interface GenerateTestDataBatchCase {
+    id: string;
+    title: string;
+    steps: string[];
+    expectedResult: string;
+    preconditions?: string;
+    testDataInline?: object;
+}
+export interface GenerateTestDataBatchOpts {
+    llmCfg?: LLMConfig;
+    skillFile?: string;
+    tenantId?: string;
+    projectId?: string;
+}
+export interface GenerateTestDataResult {
+    dataSets: unknown[];
+    saved: unknown[];
+    skipped?: boolean;
+    reason?: string;
+    mode?: string;
+    source?: string;
+}
+export interface TestDataAgent {
+    generateTestData(opts: GenerateTestDataOpts): Promise<GenerateTestDataResult>;
+    generateTestDataBatch(cases: GenerateTestDataBatchCase[], options?: GenerateTestDataBatchOpts): Promise<Map<string, unknown>>;
+}
+export interface GenerateTestScriptOpts {
+    tenantId: string;
+    projectId: string;
+    testCaseId: string;
+    language?: string;
+    /** When true, derive and persist repoTargetPath on the test case for IDE push. */
+    useV2?: boolean;
+    jobId?: string;
+    /** Pre-extracted Playwright locators from the live page. */
+    extractedLocators?: Array<{
+        key: string;
+        expression: string;
+        description: string;
+        confidence: string;
+    }>;
+    /** Repo style profile — avoids internal re-query and ensures pomPaths() gets correct directories. */
+    styleProfile?: Record<string, unknown>;
+    /** Existing page-object inventory from the repo connection. */
+    pageObjectInventory?: Array<{
+        filePath: string;
+        className: string;
+        methods: Array<{
+            name: string;
+            params: string;
+            returnType: string;
+        }>;
+        importPath: string;
+    }>;
+    /** Optional user instruction to override or guide the LLM during regeneration. */
+    instructionOverride?: string;
+}
+export interface GenerateTestScriptResult {
+    language: string;
+    code: string;
+    files: Array<{
+        filename: string;
+        code: string;
+        path: string;
+        testCaseId: string;
+        role: string;
+    }>;
+    saved: unknown;
+    lintViolations: unknown[];
+}
+export interface GenerateSuiteScriptOpts {
+    tenantId: string;
+    projectId: string;
+    suiteId: string;
+    language?: string;
+    caseIds?: string[];
+    useV2?: boolean;
+    styleProfile?: Record<string, unknown>;
+    pageObjectInventory?: Array<{
+        filePath: string;
+        className: string;
+        methods: Array<{
+            name: string;
+            params: string;
+            returnType: string;
+        }>;
+        importPath: string;
+    }>;
+    onProgress?: (done: number, total: number) => void;
+    jobId?: string;
+}
+export interface GenerateSuiteScriptResult {
+    language: string;
+    files: Array<{
+        filename: string;
+        code: string;
+        path?: string;
+        testCaseId?: string;
+        role?: string;
+    }>;
+    basePage: string | null;
+}
+export interface ScriptAgent {
+    generateTestScript(opts: GenerateTestScriptOpts): Promise<GenerateTestScriptResult>;
+    generateSuiteScript(opts: GenerateSuiteScriptOpts): Promise<GenerateSuiteScriptResult>;
+}
+export interface GenerateScenariosOpts {
+    tenantId: string;
+    projectId: string;
+    requirement: {
+        reqId: string;
+        title: string;
+        actor?: string;
+        type?: string;
+        priority?: string;
+        acceptanceCriteria?: string[];
+        businessRules?: string[];
+    };
+    /** Number of scenarios to generate. Default 4, min 1, max 10. */
+    count?: number;
+}
+/** Mirrors the ScenarioOutput interface defined in scenario-agent.ts */
+export interface ScenarioOutput {
+    title: string;
+    description?: string;
+    gherkin: string;
+}
+export interface ScenarioAgent {
+    generateScenarios(opts: GenerateScenariosOpts): Promise<ScenarioOutput[]>;
+}
+export interface ConvertNlpToTestOpts {
+    tenantId: string;
+    projectId: string;
+    description: string;
+    suiteId?: string;
+}
+export interface ConvertNlpToTestResult {
+    confidence?: number;
+    understoodIntent?: string;
+    unmatchedTerms?: string[];
+    testCase?: {
+        title: string;
+        kind: string;
+        steps: string[];
+        expectedResult: string;
+        groundedOn: string[];
+    };
+    saved?: unknown;
+    warning?: string;
+    error?: string;
+    description?: string;
+}
+export interface NlpAgent {
+    convertNlpToTest(opts: ConvertNlpToTestOpts): Promise<ConvertNlpToTestResult>;
+}
+export interface SkillFileAgent {
+    refreshTestCasesSkillFile(tenantId: string, projectId: string): Promise<void>;
+    refreshTestDataSkillFile(tenantId: string, projectId: string): Promise<void>;
+    refreshTestScriptSkillFile(tenantId: string, projectId: string): Promise<void>;
+    refreshRequirementsCoverageSkillFile(tenantId: string, projectId: string): Promise<void>;
+    refreshCoverageMatrix(tenantId: string, projectId: string): Promise<void>;
+    refreshTestCaseInventory(tenantId: string, projectId: string): Promise<void>;
+    refreshScriptInventory(tenantId: string, projectId: string): Promise<void>;
+    refreshFieldCatalogSkillFile(tenantId: string, projectId: string): Promise<void>;
+}

package/dist/types.js

@@ -0,0 +1,7 @@
+"use strict";
+/**
+ * Gap 1: Contract interfaces for @taodigital/agents.
+ * Routes should import from this file and depend on interfaces, not implementations.
+ * This enables swapping agent implementations without touching route code.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });

package/dist/visual-agent.d.ts

@@ -0,0 +1,114 @@
+/**
+ * ZeTa-AI Visual Intelligence Agent
+ *
+ * Handles visual regression testing:
+ * 1. On first crawl — save screenshots as baselines.
+ * 2. On subsequent crawls — compare new screenshots to baselines.
+ * 3. AI analyzes diffs: meaningful change vs. rendering noise.
+ * 4. Generates bug report drafts for critical visual changes.
+ *
+ * Phase 2: Vision AI integration (uses Claude's vision capability).
+ * Phase 1: Pixel-diff fallback (no vision AI needed yet).
+ */
+export interface VisualComparisonResult {
+    screenId: string;
+    changeType: 'NONE' | 'MINOR' | 'SIGNIFICANT' | 'CRITICAL';
+    diffScore: number;
+    changes: Array<{
+        description: string;
+        location: string;
+        severity: string;
+    }>;
+    recommendation: 'APPROVE' | 'REVIEW' | 'FLAG' | 'BLOCK';
+    bugReportDraft?: {
+        title: string;
+        severity: string;
+        steps: string[];
+        expected: string;
+        actual: string;
+    };
+}
+/**
+ * Set or update the visual baseline for a screen.
+ * Called after the first successful crawl screenshot is stored.
+ */
+export declare function setVisualBaseline(opts: {
+    tenantId: string;
+    projectId: string;
+    screenId: string;
+    screenshotPath: string;
+    viewport?: string;
+    approvedBy?: string;
+}): Promise<void>;
+/**
+ * Compare a new screenshot against the stored baseline.
+ * Phase 1: returns a structural diff (element count change).
+ * Phase 2: Vision AI reads both images and produces rich analysis.
+ */
+export declare function compareToBaseline(opts: {
+    tenantId: string;
+    projectId: string;
+    screenId: string;
+    newScreenshotPath: string;
+    screenName: string;
+    viewport?: string;
+}): Promise<VisualComparisonResult | null>;
+/**
+ * Update the ignored regions for a visual baseline.
+ * Regions are excluded from AI visual comparison (PHI masking, dynamic content).
+ * Each region is a rectangle in original image coordinates (before compression).
+ */
+export declare function updateIgnoredRegions(opts: {
+    tenantId: string;
+    projectId: string;
+    screenId: string;
+    viewport?: string;
+    regions: Array<{
+        x: number;
+        y: number;
+        width: number;
+        height: number;
+        label?: string;
+    }>;
+}): Promise<void>;
+/**
+ * Set visual baselines for all standard viewports from a map of viewport→screenshotPath.
+ * Call after crawl completes with screenshots at each breakpoint.
+ */
+export declare function setAllViewportBaselines(opts: {
+    tenantId: string;
+    projectId: string;
+    screenId: string;
+    screenshots: Partial<Record<'DESKTOP' | 'TABLET' | 'MOBILE', string>>;
+    approvedBy?: string;
+}): Promise<void>;
+/**
+ * Compare a screen against baselines for ALL viewports that have baselines stored.
+ * Returns a map of viewport → comparison result. Null value = no baseline for that viewport.
+ */
+export declare function compareAllViewports(opts: {
+    tenantId: string;
+    projectId: string;
+    screenId: string;
+    screenName: string;
+    screenshots: Partial<Record<'DESKTOP' | 'TABLET' | 'MOBILE', string>>;
+}): Promise<Record<string, VisualComparisonResult | null>>;
+/**
+ * Phase 2: AI-powered visual comparison using Claude vision.
+ * This replaces the file-size proxy with real image understanding.
+ */
+export declare function aiVisualCompare(opts: {
+    baselineImageBase64: string;
+    newImageBase64: string;
+    imageMediaType?: 'image/png' | 'image/jpeg';
+    screenName: string;
+    screenPurpose: string;
+    tenantId?: string;
+    projectId?: string;
+}): Promise<{
+    changeType: string;
+    changes: any[];
+    recommendation: string;
+    diffScore: number;
+    summary: string;
+}>;