@taodigital/agents 0.0.0-stage → 1.2.0

package/dist/nlp-agent.js

@@ -0,0 +1,340 @@
+"use strict";
+/**
+ * ZeTa-AI NLP Test Input Agent
+ *
+ * Converts plain-English test descriptions into structured, grounded test cases.
+ * Unlike competitors (testRigor, Functionize) this grounds the output in the
+ * Zeta Core — only uses elements that ACTUALLY EXIST on the real screen.
+ *
+ * Input:  "When a user logs in with valid credentials, they should see the dashboard"
+ * Output: A structured TestCase grounded in real elements, ready for review.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.convertNlpToTest = convertNlpToTest;
+exports.extractLocatorsWithLLM = extractLocatorsWithLLM;
+const app_brain_1 = require("@taodigital/app-brain");
+const llm_js_1 = require("./llm.js");
+const llm_config_js_1 = require("./llm-config.js");
+const core_1 = require("@taodigital/core");
+async function convertNlpToTest(opts) {
+    // Load all project screens to find the most relevant one.
+    const project = await app_brain_1.AppBrain.getProjectMap(opts.tenantId, opts.projectId);
+    if (!project)
+        throw new Error('Project not found.');
+    const ELEMENT_LIMIT = parseInt(process.env.NLP_ELEMENT_LIMIT ?? '10', 10);
+    const screenSummaries = project.screens.map((s) => ({
+        id: s.id,
+        name: s.name,
+        url: s.url,
+        elementCount: s.elements.length,
+        elements: s.elements.slice(0, ELEMENT_LIMIT).map((e) => e.meaning),
+    }));
+    // ZETA-041: load existing test titles from the suite so the AI can avoid
+    // generating duplicate or off-topic test items.
+    let existingTitles = [];
+    if (opts.suiteId) {
+        try {
+            const suite = await app_brain_1.AppBrain.getTestSuiteWithCases(opts.tenantId, opts.suiteId);
+            existingTitles = (suite?.testCases ?? []).map((tc) => String(tc.title ?? '')).filter(Boolean);
+        }
+        catch { /* non-fatal — proceed without existing titles */ }
+    }
+    const SYSTEM_DEFAULT = [
+        'You are ZeTa-AI\'s Natural Language Test Converter.',
+        'Convert a plain-English test description into a structured test case.',
+        'ONLY use elements that exist in the provided Zeta Core context.',
+        'Never invent buttons, fields, or screens that are not listed.',
+        'The generated test case MUST be distinct from any existing test titles listed below.',
+        'Return JSON: { targetScreenId, confidence, understoodIntent, unmatchedTerms, testCase: { title, kind, steps, expectedResult, groundedOn } }',
+    ].join(' ');
+    const system = await (0, core_1.getAgentPrompt)('nlp-locator-extractor', undefined, opts.tenantId) ?? SYSTEM_DEFAULT;
+    const user = [
+        `USER DESCRIPTION: "${opts.description}"`,
+        '',
+        'AVAILABLE SCREENS IN Zeta Core:',
+        screenSummaries.map((s) => `Screen ID: ${s.id}\nName: ${s.name}\nURL: ${s.url ?? 'n/a'}\nSample elements: ${s.elements.join(', ')}`).join('\n\n'),
+        '',
+        existingTitles.length > 0
+            ? `EXISTING TEST CASES IN SUITE (do NOT generate a duplicate of any of these):\n${existingTitles.map((t) => `- ${t}`).join('\n')}`
+            : '',
+        '',
+        'Instructions:',
+        '1. Identify which screen the user is describing',
+        '2. Map user terms to real element meanings from that screen',
+        '3. Build structured test steps using ONLY real element names',
+        '4. Note any terms you could not match to real elements',
+        '5. Set confidence 0-100 (lower if many terms unmatched)',
+        '6. Ensure the generated test title is meaningfully different from existing test titles',
+    ].filter((line) => line !== '').join('\n');
+    let parsed;
+    try {
+        const t0 = Date.now();
+        // GAP-14: NLP conversion needs full reasoning model — was using fast model
+        const llmCfg = await (0, llm_config_js_1.getTaskAgentLLMConfig)(opts.tenantId, 'testGeneration');
+        const seed = (0, llm_js_1.deterministicSeed)(`${opts.tenantId}:${opts.projectId}:nlp:${opts.description.slice(0, 500)}:${opts.suiteId ?? ''}`);
+        const { text: raw, usage } = await (0, llm_js_1.askTracked)(system, user, llmCfg, undefined, undefined, { temperature: 0, seed });
+        const latencyMs = Date.now() - t0;
+        const json = raw.slice(raw.indexOf('{'), raw.lastIndexOf('}') + 1);
+        parsed = JSON.parse(json);
+        (0, app_brain_1.recordLLMCall)({
+            tenantId: opts.tenantId,
+            projectId: opts.projectId,
+            agentType: 'nlp',
+            label: 'nlp_to_test',
+            entityType: 'test_case',
+            usage,
+            latencyMs,
+        }).catch(console.error);
+    }
+    catch {
+        return {
+            error: 'Could not parse test from description. Try being more specific about which screen and elements you want to test.',
+            description: opts.description,
+        };
+    }
+    // Validate that groundedOn elements actually exist on the target screen.
+    let grounded;
+    try {
+        const screen = await app_brain_1.AppBrain.getScreenWithElements(opts.tenantId, parsed.targetScreenId);
+        const allowed = new Set((screen?.elements ?? []).map((e) => e.meaning));
+        parsed.testCase.groundedOn = parsed.testCase.groundedOn.filter((e) => allowed.has(e));
+        grounded = parsed;
+    }
+    catch {
+        grounded = parsed;
+    }
+    // Save as PENDING_REVIEW (human must approve NLP-generated tests).
+    const suiteName = opts.suiteId ? undefined : `NLP: ${grounded.understoodIntent.slice(0, 60)}`;
+    const saved = opts.suiteId
+        ? await app_brain_1.AppBrain.addTestCaseToSuite(opts.tenantId, opts.projectId, opts.suiteId, {
+            ...grounded.testCase,
+            screenId: parsed.targetScreenId,
+            expectedResult: grounded.testCase.expectedResult,
+        })
+        : await app_brain_1.AppBrain.saveGeneratedTestCases(opts.tenantId, opts.projectId, suiteName, [{
+                ...grounded.testCase,
+                screenId: parsed.targetScreenId,
+                expectedResult: grounded.testCase.expectedResult,
+            }]);
+    const savedCase = opts.suiteId
+        ? saved
+        : saved?.testCases?.[0] ?? saved;
+    const resolvedRef = savedCase?.ref ?? `TC-NLP-001`;
+    const finalizedTestCase = {
+        ...grounded.testCase,
+        id: savedCase?.id,
+        ref: resolvedRef,
+        screenId: parsed.targetScreenId,
+    };
+    return {
+        id: savedCase?.id,
+        ref: resolvedRef,
+        title: grounded.testCase.title,
+        steps: grounded.testCase.steps,
+        expectedResult: grounded.testCase.expectedResult,
+        confidence: grounded.confidence,
+        understoodIntent: grounded.understoodIntent,
+        unmatchedTerms: grounded.unmatchedTerms,
+        testCase: finalizedTestCase,
+        saved,
+        warning: grounded.confidence < 70
+            ? 'Low confidence. Review carefully — some user-described elements may not have been matched correctly.'
+            : undefined,
+    };
+}
+/**
+ * Use an LLM to extract Playwright locators from test case steps of any format.
+ * Handles structured (QA Wolf), plain-English (AI-generated), or mixed step formats.
+ * Falls back to empty array if no LLM is configured or extraction fails.
+ */
+async function extractLocatorsWithLLM(opts) {
+    const llmCfg = await (0, llm_config_js_1.getTaskAgentLLMConfig)(opts.tenantId, 'testGeneration');
+    if (!llmCfg)
+        return [];
+    const cleanStepForLLM = (s) => s.replace(/\{\{\s*fze\.env\.([^}\s]+)\s*\}\}/gi, (_, v) => `<${v}>`)
+        .replace(/\[protected\]/gi, '<credential>')
+        .replace(/\[captured:\s*([^\]]+)\]/gi, (_, v) => `<captured_${v}>`)
+        .replace(/\[random[^\]]*\]/gi, '<random_value>');
+    const stepLines = opts.steps
+        .map((s, i) => {
+        const action = typeof s === 'string'
+            ? s
+            : [s.action, s.text, s.description, s.label]
+                .filter((v) => typeof v === 'string' && String(v).trim().length > 0)
+                .join(' ')
+                .trim();
+        return `${i + 1}. ${cleanStepForLLM(action)}`;
+    })
+        .filter(l => l.trim().length > 2)
+        .slice(0, 80)
+        .join('\n');
+    if (!stepLines.trim())
+        return [];
+    // Deterministic pre-extraction for credential and critical action steps
+    const deterministicLocators = [];
+    const seenDetExpr = new Set();
+    const addDet = (key, expr, desc, confidence) => {
+        if (seenDetExpr.has(expr))
+            return;
+        seenDetExpr.add(expr);
+        deterministicLocators.push({ key, expression: expr, elementType: 'textbox', confidence, source: 'llm-step-analysis', description: desc });
+    };
+    for (const rawStep of opts.steps) {
+        const stepStr = typeof rawStep === 'string' ? rawStep : String(rawStep.action ?? '');
+        if (/enter\s+username\b/i.test(stepStr))
+            addDet('usernameInput', "page.getByLabel('Username')", 'Username field', 'high');
+        if (/enter\s+password\b/i.test(stepStr) || /\[protected\]/i.test(stepStr))
+            addDet('passwordInput', "page.getByLabel('Password')", 'Password field', 'high');
+    }
+    // Build value→fieldKey map for locator key alignment
+    const dataValueMap = new Map(); // exampleValue → fieldKey
+    for (const f of opts.dataFields ?? []) {
+        if (f.exampleValue && f.exampleValue.trim().length >= 3) {
+            dataValueMap.set(f.exampleValue.trim(), f.fieldKey);
+        }
+    }
+    const dataFieldsHint = dataValueMap.size > 0
+        ? `\nDATA FIELDS (use these fieldKey names when a locator's value matches the exampleValue):\n${Array.from(dataValueMap.entries()).map(([v, k]) => `  fieldKey="${k}" exampleValue="${v}"`).join('\n')}\nWhen an element's name/text exactly matches an exampleValue above, use the corresponding fieldKey as the locator key (append "Button", "Link", or "Text" as appropriate).`
+        : '';
+    const SYSTEM_DEFAULT = `You are a Playwright test automation expert. Your task: analyze test steps and extract Playwright locators for every UI element that is interacted with or verified.
+
+Output ONLY a JSON array — no markdown, no explanation, no wrapper object. Each item:
+{"key":"camelCaseName","expression":"page.getByRole(...)","elementType":"button|link|heading|textbox|combobox|checkbox|text","confidence":"high|medium|low","description":"short label"}
+
+Playwright locator priority (use the first that applies):
+1. getByRole('button'|'link'|'heading'|'textbox'|'combobox'|'checkbox'|'radio', { name: '...' }) — for semantic elements
+2. getByLabel('...') — for form fields identified by label text
+3. getByPlaceholder('...') — for inputs with placeholder
+4. getByText('...') — for verifying visible text content
+5. getByTestId('...') — only if a data-testid attribute is explicitly mentioned
+
+Rules:
+- Deduplicate by expression
+- key must be camelCase, max 40 chars
+- Skip pure navigation steps (URL-only, no element)
+- confidence: high=role+name match, medium=text match, low=ambiguous
+- If a step is too vague to produce a locator, skip it
+- SKIP steps that verify a plain numeric value (e.g. 'Verify text: "392"', 'Verify element text: "458"') — these are dynamic dashboard counts, not stable locators
+- SKIP multi-line element strings containing "Remove Chip" — these are filter chip combinations, not reusable locators
+- SKIP filter buttons whose name ends with \\n(count) like "Source: All\\n(68)" or "UP Type: All\\n(4)" — the count is dynamic; if the same button appears without the count suffix use that instead
+- For steps like "Enter username: X" → generate getByLabel('Username') or getByRole('textbox', { name: 'Username' }) with key "usernameInput"
+- For steps like "Enter password: [protected]" → generate getByLabel('Password') with key "passwordInput" — do NOT skip protected/masked credential steps
+- For steps like "Click login button: X" → generate getByRole('button', { name: X }) with key "signInButton"
+- For date range buttons (element name contains a date pattern like "02/01/2025 - 02/13/2025"), use key "dateRangeButton"
+- Do NOT strip date separators (/ and -) to create numeric keys like "0201202502132025" — use semantic names instead${dataFieldsHint}`;
+    const locatorSystemBase = await (0, core_1.getAgentPrompt)('nlp-playwright-locator', undefined, opts.tenantId) ?? SYSTEM_DEFAULT;
+    // Append the dataFieldsHint (which is dynamic per-call) only when using the fallback; DB prompt already has the static rules.
+    const SYSTEM = locatorSystemBase.includes(dataFieldsHint) || !dataFieldsHint
+        ? locatorSystemBase
+        : `${locatorSystemBase}${dataFieldsHint}`;
+    // Build optional context block for scenario-derived TCs where steps may be vague BDD phrases.
+    // Gherkin text and title give the LLM enough signal to infer element names even when individual
+    // step lines say things like "the user completes the registration".
+    const ctx = opts.tcContext;
+    const contextParts = [];
+    if (ctx?.title?.trim())
+        contextParts.push(`Test case: ${ctx.title.trim()}`);
+    if (ctx?.preconditions?.trim())
+        contextParts.push(`Preconditions: ${ctx.preconditions.trim()}`);
+    if (ctx?.gherkin?.trim())
+        contextParts.push(`Full Gherkin scenario:\n${ctx.gherkin.trim().slice(0, 2000)}`);
+    const tcContextBlock = contextParts.length > 0
+        ? `\n\nADDITIONAL CONTEXT (use to infer element names when steps are vague):\n${contextParts.join('\n')}`
+        : '';
+    const USER = `Test steps:\n${stepLines}${tcContextBlock}\n\nReturn JSON array of Playwright locators:`;
+    try {
+        const seed = (0, llm_js_1.deterministicSeed)(`${opts.tenantId}:nlp-locators:${stepLines.slice(0, 500)}`);
+        const result = await (0, llm_js_1.askTracked)(SYSTEM, USER, llmCfg, 2048, undefined, { temperature: 0, seed });
+        const raw = result.text.trim();
+        const json = raw.startsWith('```') ? raw.replace(/^```[^\n]*\n?/, '').replace(/\n?```$/, '') : raw;
+        const parsed = JSON.parse(json);
+        if (!Array.isArray(parsed))
+            return [];
+        const seenKeys = new Set();
+        const seenExprs = new Set();
+        const locators = [];
+        for (const l of parsed) {
+            if (!l?.key || !l?.expression || !String(l.expression).startsWith('page.'))
+                continue;
+            const expr = String(l.expression);
+            // Filter 1: skip multi-line chip combo expressions
+            // Match both real newlines (LLM JSON parsed) and literal \n (safety)
+            const newlineCount = (expr.match(/\\n|\n/g) ?? []).length;
+            if (expr.includes('Remove Chip') || newlineCount >= 2)
+                continue;
+            // Filter 2: skip pure numeric descriptions or keys (dynamic dashboard counts like 392, 458)
+            const desc = String(l.description ?? '').trim();
+            if (/^\d+$/.test(desc))
+                continue;
+            if (/^\d+$/.test(String(l.key ?? '')))
+                continue;
+            // Filter 3: skip filter-chip buttons with dynamic count suffix like "Source: All\n(68)"
+            // LLM JSON "Source: All\n(68)" parses to a real newline, so match real newline char
+            if (/\n\(\d+\)/.test(expr))
+                continue;
+            // Filter 4: skip locators that use display artifact tokens — these are never real DOM text
+            if (/\[captured:\s*|'\[random|\[dynamic\]/i.test(expr))
+                continue;
+            // Deduplicate by expression
+            if (seenExprs.has(expr))
+                continue;
+            seenExprs.add(expr);
+            let key = String(l.key).replace(/[^a-zA-Z0-9]/g, '').slice(0, 40) || 'element';
+            // Fix 1: rename all-digit keys (date string munging like "0201202502132025")
+            if (/^\d{6,}$/.test(key)) {
+                if (/\d{1,2}\/\d{1,2}\/\d{4}/.test(expr)) {
+                    key = 'dateRangeButton';
+                }
+                else {
+                    key = `element${key.slice(0, 6)}`;
+                }
+            }
+            // Fix 2: align key with data field name when expression matches a field's example value
+            for (const [val, fieldKey] of dataValueMap) {
+                if (expr.includes(val)) {
+                    const suffix = String(l.elementType ?? '').toLowerCase().includes('button') ? 'Button'
+                        : String(l.elementType ?? '').toLowerCase().includes('link') ? 'Link'
+                            : String(l.elementType ?? '').toLowerCase().includes('text') ? 'Text'
+                                : 'Element';
+                    key = (fieldKey + suffix).replace(/[^a-zA-Z0-9]/g, '').slice(0, 40);
+                    break;
+                }
+            }
+            // Disambiguate duplicate keys
+            const baseKey = key;
+            let dedupeIdx = 2;
+            while (seenKeys.has(key)) {
+                key = `${baseKey}${dedupeIdx++}`;
+            }
+            seenKeys.add(key);
+            locators.push({
+                key,
+                expression: expr,
+                elementType: String(l.elementType ?? 'element'),
+                confidence: ['high', 'medium', 'low'].includes(l.confidence) ? l.confidence : 'medium',
+                source: 'llm-step-analysis',
+                description: desc.slice(0, 80),
+            });
+        }
+        // Merge deterministic locators first (they take priority on key), then LLM locators
+        const finalLocators = [...deterministicLocators];
+        const seenFinalExprs = new Set(deterministicLocators.map(l => l.expression));
+        const seenFinalKeys = new Set(deterministicLocators.map(l => l.key));
+        for (const loc of locators) {
+            if (seenFinalExprs.has(loc.expression))
+                continue;
+            // Disambiguate key
+            let k = loc.key;
+            let idx = 2;
+            while (seenFinalKeys.has(k))
+                k = `${loc.key}${idx++}`;
+            seenFinalKeys.add(k);
+            seenFinalExprs.add(loc.expression);
+            finalLocators.push({ ...loc, key: k });
+        }
+        return finalLocators;
+    }
+    catch {
+        return [];
+    }
+}

package/dist/orchestrator.d.ts

@@ -0,0 +1,285 @@
+export interface OrchestratorRequest {
+    tenantId: string;
+    projectId: string;
+    jobId?: string;
+    targetScreenId?: string;
+    targetFlowStartScreenId?: string;
+    targetFlowEndScreenId?: string;
+    viewport?: string;
+    suiteNameOverride?: string;
+    force?: boolean;
+    /**
+     * 'append' (default) — deduplicates by content hash + grounding hash + title Jaccard.
+     * 'replace'          — deletes existing AI-generated cases, then inserts fresh.
+     * 'edit'             — upserts matched cases (updates steps/gherkin/expectedResult, snapshots old version).
+     */
+    mode?: 'replace' | 'append' | 'edit';
+    /**
+     * When provided, only generates test cases of these kinds.
+     * Passed through to generateTestCases. Omit for all-kinds generation (default).
+     */
+    kinds?: readonly string[];
+}
+/**
+ * Dual-Context Orchestrator — routes test generation to the right agent.
+ *
+ * ROUTE 1: targetScreenId  → Pure CAG  → generateTestCases() (21-pass)
+ * ROUTE 2: targetFlowStart + targetFlowEnd → KAG BFS + CAG → generateFlowTestCases()
+ */
+export declare class DualContextOrchestrator {
+    static execute(req: OrchestratorRequest): Promise<{
+        status: string;
+        cases: never[];
+        saved: null;
+        screenCount?: undefined;
+        suiteName?: undefined;
+    } | {
+        status: string;
+        cases: never[];
+        saved: null;
+        screenCount: number;
+        suiteName?: undefined;
+    } | {
+        status: string;
+        cases: import("./flow-agent.js").FlowTestCase[];
+        saved: {
+            suite: {
+                tenantId: string;
+                id: string;
+                projectId: string;
+                name: string;
+                createdAt: Date;
+                genModel: string | null;
+                category: import(".prisma/client").$Enums.SuiteCategory | null;
+                parentId: string | null;
+                ownerUserId: string | null;
+                genTotalTokens: number | null;
+                genTotalCostUsd: number | null;
+                genAt: Date | null;
+                genScreenCount: number | null;
+                coverageReport: import("@prisma/client/runtime/library").JsonValue | null;
+            };
+            testCases: {
+                tenantId: string;
+                screenId: string | null;
+                id: string;
+                projectId: string;
+                source: string;
+                status: string;
+                createdAt: Date;
+                updatedAt: Date;
+                steps: import("@prisma/client/runtime/library").JsonValue;
+                kind: string;
+                tags: import("@prisma/client/runtime/library").JsonValue;
+                approvedBy: string | null;
+                suiteId: string;
+                ref: string | null;
+                title: string;
+                priority: string;
+                preconditions: string | null;
+                expectedResult: string | null;
+                gherkin: string | null;
+                approvedAt: Date | null;
+                groundedOn: import("@prisma/client/runtime/library").JsonValue;
+                caseRefs: import("@prisma/client/runtime/library").JsonValue;
+                viewports: import("@prisma/client/runtime/library").JsonValue;
+                viewportConstraint: string;
+                techniqueOfRecord: string | null;
+                traceTo: string | null;
+                traceToExtra: import("@prisma/client/runtime/library").JsonValue;
+                testDataInline: import("@prisma/client/runtime/library").JsonValue | null;
+                dataNote: string | null;
+                scriptNote: string | null;
+                structuredSteps: import("@prisma/client/runtime/library").JsonValue | null;
+                artifactId: string | null;
+                scenarioId: string | null;
+                suspect: boolean;
+                suspectReason: string | null;
+                flakyScore: number;
+                consecutiveFlakes: number;
+                lastFlakyAt: Date | null;
+                quarantined: boolean;
+                quarantinedAt: Date | null;
+                quarantineReason: string | null;
+                genPromptTokens: number | null;
+                genCompletionTokens: number | null;
+                genCostUsd: number | null;
+                genModel: string | null;
+                dataSetId: string | null;
+                repoTargetPath: string | null;
+                stepsKey: string | null;
+                gherkinKey: string | null;
+                contentHash: string | null;
+                groundingHash: string | null;
+                locatorsJson: import("@prisma/client/runtime/library").JsonValue | null;
+                locatorsExtractedAt: Date | null;
+                captureStepScreenshots: import("@prisma/client/runtime/library").JsonValue | null;
+            }[];
+        };
+        screenCount: number;
+        suiteName: string;
+    } | {
+        skipped: boolean;
+        reason: string;
+        existingCaseCount: number;
+        status?: undefined;
+        raw?: undefined;
+        cases?: undefined;
+        groundedFacts?: undefined;
+        saved?: undefined;
+        passBreakdown?: undefined;
+        coverageReport?: undefined;
+    } | {
+        status: string;
+        raw: string;
+        cases: {
+            title: string;
+            ref: string;
+            viewportConstraint: "ALL" | "MOBILE_ONLY" | "TABLET_ONLY";
+            techniqueOfRecord: string | undefined;
+            traceTo: string | undefined;
+            testDataInline: Record<string, unknown> | undefined;
+            category: string[] | undefined;
+            dataNote: string | undefined;
+            scriptNote: string | undefined;
+            structuredSteps: {
+                action: string;
+                target?: string;
+                data?: string;
+            }[] | undefined;
+            kind: import("@taodigital/core").TestKind;
+            priority: "CRITICAL" | "HIGH" | "MEDIUM" | "LOW";
+            preconditions: string;
+            expectedResult: string;
+            steps: string[];
+            groundedOn: string[];
+            gherkin: string;
+            tags: string[];
+        }[];
+        groundedFacts: import("@taodigital/core").ElementFact[];
+        saved: {
+            suite: {
+                tenantId: string;
+                id: string;
+                projectId: string;
+                name: string;
+                createdAt: Date;
+                genModel: string | null;
+                category: import(".prisma/client").$Enums.SuiteCategory | null;
+                parentId: string | null;
+                ownerUserId: string | null;
+                genTotalTokens: number | null;
+                genTotalCostUsd: number | null;
+                genAt: Date | null;
+                genScreenCount: number | null;
+                coverageReport: import("@prisma/client/runtime/library").JsonValue | null;
+            };
+            testCases: {
+                tenantId: string;
+                screenId: string | null;
+                id: string;
+                projectId: string;
+                source: string;
+                status: string;
+                createdAt: Date;
+                updatedAt: Date;
+                steps: import("@prisma/client/runtime/library").JsonValue;
+                kind: string;
+                tags: import("@prisma/client/runtime/library").JsonValue;
+                approvedBy: string | null;
+                suiteId: string;
+                ref: string | null;
+                title: string;
+                priority: string;
+                preconditions: string | null;
+                expectedResult: string | null;
+                gherkin: string | null;
+                approvedAt: Date | null;
+                groundedOn: import("@prisma/client/runtime/library").JsonValue;
+                caseRefs: import("@prisma/client/runtime/library").JsonValue;
+                viewports: import("@prisma/client/runtime/library").JsonValue;
+                viewportConstraint: string;
+                techniqueOfRecord: string | null;
+                traceTo: string | null;
+                traceToExtra: import("@prisma/client/runtime/library").JsonValue;
+                testDataInline: import("@prisma/client/runtime/library").JsonValue | null;
+                dataNote: string | null;
+                scriptNote: string | null;
+                structuredSteps: import("@prisma/client/runtime/library").JsonValue | null;
+                artifactId: string | null;
+                scenarioId: string | null;
+                suspect: boolean;
+                suspectReason: string | null;
+                flakyScore: number;
+                consecutiveFlakes: number;
+                lastFlakyAt: Date | null;
+                quarantined: boolean;
+                quarantinedAt: Date | null;
+                quarantineReason: string | null;
+                genPromptTokens: number | null;
+                genCompletionTokens: number | null;
+                genCostUsd: number | null;
+                genModel: string | null;
+                dataSetId: string | null;
+                repoTargetPath: string | null;
+                stepsKey: string | null;
+                gherkinKey: string | null;
+                contentHash: string | null;
+                groundingHash: string | null;
+                locatorsJson: import("@prisma/client/runtime/library").JsonValue | null;
+                locatorsExtractedAt: Date | null;
+                captureStepScreenshots: import("@prisma/client/runtime/library").JsonValue | null;
+            }[];
+        };
+        passBreakdown: {
+            [k: string]: number;
+        };
+        coverageReport: {
+            byKind: Record<string, number>;
+            byPriority: Record<string, number>;
+            byTechnique: Record<string, number>;
+            targetsDiscovered: number;
+            targetsCovered: number;
+            gaps: string[];
+            passBreakdown: {
+                [k: string]: number;
+            };
+        };
+        skipped?: undefined;
+        reason?: undefined;
+        existingCaseCount?: undefined;
+    }>;
+}
+export interface SwarmRequest {
+    tenantId: string;
+    projectId: string;
+    jobId?: string;
+    /** Run all screens in parallel — swarm mode */
+    screenIds: string[];
+    /** Max concurrent agents. Default 4. */
+    concurrency?: number;
+}
+export interface SwarmResult {
+    succeeded: string[];
+    failed: {
+        screenId: string;
+        error: string;
+    }[];
+    totalGenerated: number;
+}
+/**
+ * Swarm Orchestrator — runs multiple test-generation agents in parallel.
+ *
+ * Each agent reads shared skill files before generating (so they all share
+ * the same application knowledge). After all agents complete, COVERAGE_MATRIX
+ * skill file is updated with aggregated counts.
+ *
+ * Skill files act as the shared memory bus — any knowledge learned from
+ * artifacts (via learnFromArtifact) or from crawls (via skill-file-agent)
+ * is automatically available to every agent in the swarm.
+ */
+export declare class SwarmOrchestrator {
+    static execute(req: SwarmRequest): Promise<SwarmResult>;
+    /** Run swarm over ALL crawled screens in a project */
+    static executeForProject(req: Omit<SwarmRequest, 'screenIds'>): Promise<SwarmResult>;
+}