playwright-intelligence-engine 0.0.0-stage → 2.0.0

package/src/intelligence/locator-disambiguation-engine.ts

@@ -0,0 +1,331 @@
+import { ResolvedElement } from '../trace/snapshot-resolver.js';
+import { CandidateExtractor } from '../selector/candidate-extractor.js';
+
+export type DisambiguationStrategy =
+  | 'UNIQUE_DIRECT_MATCH'
+  | 'VISIBILITY_FILTER'
+  | 'CONTAINER_ANCHOR'
+  | 'LANDMARK_SECTION'
+  | 'EXPLICIT_POSITIONAL_INTENT'
+  | 'ABSTAIN_AMBIGUOUS';
+
+export interface DisambiguationContext {
+  originalSelector?: string | undefined;
+  intendedAction?: string | undefined;
+  testIntentText?: string | undefined;
+  rootDom?: ResolvedElement | undefined;
+}
+
+export interface DisambiguationResult {
+  strategy: DisambiguationStrategy;
+  resolvedCandidate?: ResolvedElement;
+  resolvedExpression?: string;
+  scopedContainer?: ResolvedElement;
+  containerAnchorText?: string;
+  matchCount: number;
+  explanation: string;
+  confidence: number;
+  isUnique: boolean;
+}
+
+export class LocatorDisambiguationEngine {
+  /**
+   * Evaluates multiple candidate elements through the evidence-based disambiguation hierarchy:
+   * 1. Unique Direct Match (matchCount === 1)
+   * 2. Visibility Filtering (filter { visible: true })
+   * 3. Container Anchoring (tr, card, list item with distinguishing text)
+   * 4. Landmark / Section Scoping (header, nav, main, dialog)
+   * 5. Explicit Positional Intent (.first(), .nth() only if original test explicitly declared it)
+   * 6. Safe Abstention (never guess positional intent)
+   */
+  public static disambiguate(
+    candidates: ResolvedElement[],
+    context: DisambiguationContext = {},
+    pageProperty = 'page'
+  ): DisambiguationResult {
+    if (candidates.length === 0) {
+      return {
+        strategy: 'ABSTAIN_AMBIGUOUS',
+        matchCount: 0,
+        explanation: 'Zero matching candidate elements found.',
+        confidence: 0,
+        isUnique: false,
+      };
+    }
+
+    // 1. Single Unique Candidate
+    if (candidates.length === 1) {
+      const candidate = candidates[0]!;
+      const expr = CandidateExtractor.generateLocator(candidate, pageProperty);
+      return {
+        strategy: 'UNIQUE_DIRECT_MATCH',
+        resolvedCandidate: candidate,
+        resolvedExpression: expr,
+        matchCount: 1,
+        explanation: 'Candidate is strictly unique in the DOM snapshot (matchCount === 1).',
+        confidence: 1.0,
+        isUnique: true,
+      };
+    }
+
+    // 2. Visibility Filtering
+    const visibleCandidates = candidates.filter((c) => this.isElementVisible(c));
+    if (visibleCandidates.length === 1) {
+      const candidate = visibleCandidates[0]!;
+      const baseExpr = CandidateExtractor.generateLocator(candidate, pageProperty);
+      const resolvedExpression = `${baseExpr}.filter({ visible: true })`;
+      return {
+        strategy: 'VISIBILITY_FILTER',
+        resolvedCandidate: candidate,
+        resolvedExpression,
+        matchCount: candidates.length,
+        explanation: `Disambiguated by visibility: exactly 1 candidate is visible and interactive while ${candidates.length - 1} duplicate(s) are hidden or off-screen.`,
+        confidence: 0.95,
+        isUnique: true,
+      };
+    }
+
+    // 3. Container Anchoring
+    if (context.rootDom) {
+      const anchorResult = this.attemptContainerAnchoring(candidates, context, pageProperty);
+      if (anchorResult) {
+        return anchorResult;
+      }
+    }
+
+    // 4. Landmark / Section Scoping
+    if (context.rootDom && (context.originalSelector || context.testIntentText)) {
+      const landmarkResult = this.attemptLandmarkScoping(candidates, context, pageProperty);
+      if (landmarkResult) {
+        return landmarkResult;
+      }
+    }
+
+    // 5. Explicit Positional Intent Verification
+    const hasExplicitPositionalIntent = this.verifyExplicitPositionalIntent(context);
+    if (hasExplicitPositionalIntent) {
+      const candidate = candidates[0]!;
+      const baseExpr = CandidateExtractor.generateLocator(candidate, pageProperty);
+      const positionalMethod = hasExplicitPositionalIntent.method; // '.first()', '.last()', or '.nth(N)'
+      const resolvedExpression = `${baseExpr}${positionalMethod}`;
+      return {
+        strategy: 'EXPLICIT_POSITIONAL_INTENT',
+        resolvedCandidate: candidate,
+        resolvedExpression,
+        matchCount: candidates.length,
+        explanation: `Verified explicit positional intent: original test or requirement explicitly specified ${positionalMethod}. Positional selection preserved with verified evidence.`,
+        confidence: 0.90,
+        isUnique: true,
+      };
+    }
+
+    // 6. Safe Abstention (Never invent positional intent!)
+    return {
+      strategy: 'ABSTAIN_AMBIGUOUS',
+      matchCount: candidates.length,
+      explanation: `NON_UNIQUE_MATCH: Locator matches ${candidates.length} elements. Disambiguation failed across visibility filtering, container anchoring, and landmark scoping. In accordance with PIE safety invariants, positional intent (.first()/.nth()) is NOT invented. Safe abstention enforced.`,
+      confidence: 0,
+      isUnique: false,
+    };
+  }
+
+  // ---------------------------------------------------------------------------
+  // Internal Resolution Strategies
+  // ---------------------------------------------------------------------------
+
+  private static isElementVisible(el: ResolvedElement): boolean {
+    if (el.attributes['hidden'] === 'true' || el.attributes['hidden'] !== undefined) {
+      return false;
+    }
+    if (el.attributes['aria-hidden'] === 'true') {
+      return false;
+    }
+    const style = (el.attributes['style'] ?? '').toLowerCase();
+    if (style.includes('display: none') || style.includes('visibility: hidden') || style.includes('opacity: 0')) {
+      return false;
+    }
+    return true;
+  }
+
+  private static attemptContainerAnchoring(
+    candidates: ResolvedElement[],
+    context: DisambiguationContext,
+    pageProperty: string
+  ): DisambiguationResult | null {
+    if (!context.rootDom) return null;
+
+    // For each candidate, find its parent container chain
+    const candidatePaths = candidates.map((c) => this.findPathToElement(context.rootDom!, c));
+
+    // Try finding the closest enclosing container: tr, li, article, card
+    for (let cIdx = 0; cIdx < candidates.length; cIdx++) {
+      const path = candidatePaths[cIdx];
+      if (!path || path.length < 2) continue;
+
+      // Search bottom-up for a container
+      for (let i = path.length - 2; i >= 0; i--) {
+        const container = path[i]!;
+        const isContainer =
+          container.tag === 'tr' ||
+          container.tag === 'li' ||
+          container.tag === 'article' ||
+          container.tag === 'section' ||
+          (container.attributes['data-testid'] ?? '').includes('card') ||
+          (container.attributes['data-testid'] ?? '').includes('item') ||
+          (container.attributes['class'] ?? '').includes('card') ||
+          (container.attributes['class'] ?? '').includes('item') ||
+          container.role === 'row' ||
+          container.role === 'listitem';
+
+        if (isContainer) {
+          // Check distinguishing text inside this container
+          const containerText = this.getCleanText(container);
+          if (containerText.length > 2 && containerText.length < 80) {
+            // Check if other candidates' containers have different text
+            const otherContainersHaveText = candidatePaths.some((otherPath, oIdx) => {
+              if (oIdx === cIdx || !otherPath) return false;
+              const otherContainer = otherPath[i];
+              if (!otherContainer) return false;
+              return this.getCleanText(otherContainer).includes(containerText);
+            });
+
+            // Distinguishing text must NOT appear in other candidates' containers
+            if (!otherContainersHaveText) {
+              const candidate = candidates[cIdx]!;
+              const innerPlan = CandidateExtractor.generateLocatorPlan(candidate);
+              const innerExpr = CandidateExtractor.planToExpression(innerPlan, '').replace(/^\./, '');
+              const containerTag = container.attributes['data-testid']
+                ? `[data-testid="${container.attributes['data-testid']}"]`
+                : container.tag;
+              const escapedText = CandidateExtractor.escapeLocatorString(containerText);
+              const resolvedExpression = `${pageProperty}.locator('${containerTag}').filter({ hasText: '${escapedText}' }).${innerExpr}`;
+
+              return {
+                strategy: 'CONTAINER_ANCHOR',
+                resolvedCandidate: candidate,
+                resolvedExpression,
+                scopedContainer: container,
+                containerAnchorText: containerText,
+                matchCount: candidates.length,
+                explanation: `Disambiguated via container anchoring: target is uniquely scoped within <${container.tag}> anchored by distinguishing text '${containerText}'.`,
+                confidence: 0.92,
+                isUnique: true,
+              };
+            }
+          }
+        }
+      }
+    }
+
+    return null;
+  }
+
+  private static attemptLandmarkScoping(
+    candidates: ResolvedElement[],
+    context: DisambiguationContext,
+    pageProperty: string
+  ): DisambiguationResult | null {
+    if (!context.rootDom) return null;
+
+    const landmarks = ['header', 'nav', 'main', 'footer', 'aside', 'dialog'];
+    const textToCheck = `${context.originalSelector ?? ''} ${context.testIntentText ?? ''}`.toLowerCase();
+
+    for (const landmark of landmarks) {
+      if (textToCheck.includes(landmark)) {
+        // Collect all candidates residing inside this landmark
+        const candidatesInLandmark = candidates.filter((candidate) => {
+          const path = this.findPathToElement(context.rootDom!, candidate);
+          return Boolean(path && path.some((el) => el.tag === landmark || el.role === landmark));
+        });
+
+        // ONLY when exactly one candidate is inside this landmark is it unique
+        if (candidatesInLandmark.length === 1) {
+          const candidate = candidatesInLandmark[0]!;
+          const innerPlan = CandidateExtractor.generateLocatorPlan(candidate);
+          const innerExpr = CandidateExtractor.planToExpression(innerPlan, '').replace(/^\./, '');
+          const resolvedExpression = `${pageProperty}.locator('${landmark}').${innerExpr}`;
+
+          return {
+            strategy: 'LANDMARK_SECTION',
+            resolvedCandidate: candidate,
+            resolvedExpression,
+            matchCount: candidates.length,
+            explanation: `Disambiguated via landmark scoping: exactly one target candidate scoped to <${landmark}> based on context.`,
+            confidence: 0.88,
+            isUnique: true,
+          };
+        }
+      }
+    }
+
+    return null;
+  }
+
+  private static verifyExplicitPositionalIntent(
+    context: DisambiguationContext
+  ): { method: string; index: number } | null {
+    const sel = context.originalSelector ?? '';
+    const intent = (context.testIntentText ?? '').toLowerCase();
+
+    // 1. Check original selector method calls
+    if (sel.includes('.first()')) {
+      return { method: '.first()', index: 0 };
+    }
+    if (sel.includes('.last()')) {
+      return { method: '.last()', index: -1 };
+    }
+    const nthMatch = sel.match(/\.nth\((\d+)\)/);
+    if (nthMatch && nthMatch[1] !== undefined) {
+      const idx = parseInt(nthMatch[1], 10);
+      return { method: `.nth(${idx})`, index: idx };
+    }
+
+    // 2. Check explicit test intent text
+    if (intent.includes('first ') || intent.includes('1st ') || intent.includes('top item') || intent.includes('top result')) {
+      return { method: '.first()', index: 0 };
+    }
+    if (intent.includes('second ') || intent.includes('2nd ')) {
+      return { method: '.nth(1)', index: 1 };
+    }
+    if (intent.includes('third ') || intent.includes('3rd ')) {
+      return { method: '.nth(2)', index: 2 };
+    }
+    if (intent.includes('last item') || intent.includes('last row')) {
+      return { method: '.last()', index: -1 };
+    }
+
+    return null;
+  }
+
+  private static findPathToElement(
+    root: ResolvedElement,
+    target: ResolvedElement,
+    currentPath: ResolvedElement[] = []
+  ): ResolvedElement[] | null {
+    const nextPath = [...currentPath, root];
+    if (root === target) {
+      return nextPath;
+    }
+
+    for (const child of root.children ?? []) {
+      const found = this.findPathToElement(child, target, nextPath);
+      if (found) return found;
+    }
+
+    return null;
+  }
+
+  private static getCleanText(el: ResolvedElement): string {
+    if (el.text && el.text.trim().length > 0) {
+      return el.text.trim();
+    }
+    // Collect child text
+    const childTexts: string[] = [];
+    for (const child of el.children ?? []) {
+      if (child.text && child.text.trim().length > 0) {
+        childTexts.push(child.text.trim());
+      }
+    }
+    return childTexts.join(' ').trim();
+  }
+}

package/src/intelligence/model-contract.ts

@@ -0,0 +1,205 @@
+export type ModelTransport = 'openai-compatible' | 'anthropic-compatible' | 'local' | 'unknown';
+export type StructuredOutputCapability = 'json_schema' | 'json_object' | 'prompt_only' | 'unknown';
+export type ReasoningCapability = 'separate_channel' | 'inline' | 'unsupported' | 'unknown';
+export type ToolCallCapability = 'native' | 'application_protocol' | 'unsupported' | 'unknown';
+
+export interface ModelCapabilities {
+  transport: ModelTransport;
+  structuredOutput: StructuredOutputCapability;
+  reasoning: ReasoningCapability;
+  toolCalls: ToolCallCapability;
+  maxOutputTokens?: number | undefined;
+}
+
+export interface ModelUsageEnvelope {
+  inputTokens?: number | undefined;
+  outputTokens?: number | undefined;
+  totalTokens?: number | undefined;
+}
+
+/** Provider-neutral response shape consumed by PIE's agent protocol. */
+export interface ModelResponseEnvelope {
+  finalText?: string | undefined;
+  reasoningText?: string | undefined;
+  structuredOutput?: unknown;
+  toolCalls?: unknown[] | undefined;
+  usage?: ModelUsageEnvelope | undefined;
+  finishReason?: string | undefined;
+  transport: ModelTransport;
+}
+
+export type ModelRequestKind = 'proposal' | 'agent_step';
+
+export interface ModelResponseDiagnostics {
+  requestKind: ModelRequestKind;
+  transport: ModelTransport;
+  topLevelKeys: string[];
+  choiceKeys: string[];
+  messageKeys: string[];
+  contentKind: 'string' | 'array' | 'missing' | 'null';
+  hasFinalText: boolean;
+  finalTextLength: number;
+  reasoningTextLength: number;
+  toolCallCount: number;
+  finishReason?: string | undefined;
+  usagePresent: boolean;
+  candidateKeys: string[];
+  candidateResponseType?: string | undefined;
+  candidateStatus?: string | undefined;
+  candidateDecision?: string | undefined;
+  candidateActionKind?: string | undefined;
+  candidateProposalVersion?: string | undefined;
+  /** Transport metadata keys recognized and removed before protocol validation. */
+  recognizedResponseMetadataKeys: string[];
+  validationErrors: string[];
+  normalizationNotes: string[];
+  redactedPreview?: string | undefined;
+}
+
+export interface OpenAiCompatibleResponsePayload {
+  choices?: Array<{
+    finish_reason?: string;
+    message?: {
+      content?: string | Array<{ type?: string; text?: string }> | null;
+      reasoning_content?: string | null;
+      tool_calls?: unknown[];
+    };
+  }>;
+  output_text?: string;
+  usage?: ModelUsageEnvelope & {
+    prompt_tokens?: number;
+    completion_tokens?: number;
+    total_tokens?: number;
+  };
+}
+
+export interface AnthropicResponsePayload {
+  content?: Array<{ type?: string; text?: string }>;
+  usage?: { input_tokens?: number; output_tokens?: number };
+  stop_reason?: string;
+}
+
+export function normalizeOpenAiResponse(payload: OpenAiCompatibleResponsePayload): ModelResponseEnvelope {
+  const message = payload.choices?.[0]?.message;
+  const content = message?.content;
+  const finalText = typeof payload.output_text === 'string'
+    ? payload.output_text
+    : typeof content === 'string'
+      ? content
+      : Array.isArray(content)
+        ? content.map((part) => part.text ?? '').join('')
+        : undefined;
+  const inputTokens = payload.usage?.inputTokens ?? payload.usage?.prompt_tokens;
+  const outputTokens = payload.usage?.outputTokens ?? payload.usage?.completion_tokens;
+  const totalTokens = payload.usage?.totalTokens ?? payload.usage?.total_tokens
+    ?? (inputTokens === undefined && outputTokens === undefined ? undefined : (inputTokens ?? 0) + (outputTokens ?? 0));
+  return {
+    finalText: finalText || undefined,
+    reasoningText: message?.reasoning_content ?? undefined,
+    toolCalls: message?.tool_calls,
+    usage: inputTokens === undefined && outputTokens === undefined && totalTokens === undefined
+      ? undefined
+      : { inputTokens, outputTokens, totalTokens },
+    finishReason: payload.choices?.[0]?.finish_reason,
+    transport: 'openai-compatible',
+  };
+}
+
+export function normalizeAnthropicResponse(payload: AnthropicResponsePayload): ModelResponseEnvelope {
+  const textParts = payload.content?.filter((part) => part.type === 'text').map((part) => part.text ?? '') ?? [];
+  const reasoningParts = payload.content?.filter((part) => part.type === 'thinking').map((part) => part.text ?? '') ?? [];
+  const inputTokens = payload.usage?.input_tokens;
+  const outputTokens = payload.usage?.output_tokens;
+  return {
+    finalText: textParts.join('') || undefined,
+    reasoningText: reasoningParts.join('') || undefined,
+    usage: inputTokens === undefined && outputTokens === undefined
+      ? undefined
+      : { inputTokens, outputTokens, totalTokens: (inputTokens ?? 0) + (outputTokens ?? 0) },
+    finishReason: payload.stop_reason,
+    transport: 'anthropic-compatible',
+  };
+}
+
+function redactPreview(value: string): string {
+  return value
+    .replace(/Bearer\s+[A-Za-z0-9._-]+/gi, 'Bearer [REDACTED]')
+    .replace(/(api[_-]?key|token|password|secret)\s*[:=]\s*["']?[^\s,"'}]+/gi, '$1=[REDACTED]')
+    .slice(0, 1000);
+}
+
+interface CandidateInspection {
+  keys: string[];
+  responseType?: string | undefined;
+  status?: string | undefined;
+  decision?: string | undefined;
+  actionKind?: string | undefined;
+  proposalVersion?: string | undefined;
+}
+
+function inspectCandidate(text: string | undefined): CandidateInspection {
+  if (!text) return { keys: [] };
+  const fenced = text.trim().match(/```(?:json)?\s*([\s\S]*?)\s*```/i)?.[1];
+  const candidateText = (fenced ?? text).trim();
+  const start = candidateText.indexOf('{');
+  const end = candidateText.lastIndexOf('}');
+  if (start < 0 || end <= start) return { keys: [] };
+  try {
+    const candidate = JSON.parse(candidateText.slice(start, end + 1)) as Record<string, unknown>;
+    return {
+      keys: Object.keys(candidate),
+      responseType: typeof candidate.responseType === 'string' ? candidate.responseType : undefined,
+      status: typeof candidate.status === 'string' ? candidate.status : undefined,
+      decision: typeof candidate.decision === 'string' ? candidate.decision : undefined,
+      actionKind: typeof (candidate.action as Record<string, unknown> | undefined)?.kind === 'string'
+        ? String((candidate.action as Record<string, unknown>).kind)
+        : undefined,
+      proposalVersion: typeof candidate.proposalVersion === 'string' ? candidate.proposalVersion : undefined,
+    };
+  } catch {
+    return { keys: [] };
+  }
+}
+
+export function createModelResponseDiagnostics(
+  payload: unknown,
+  envelope: ModelResponseEnvelope,
+  requestKind: ModelRequestKind,
+  validationErrors: string[] = [],
+  normalizationNotes: string[] = [],
+  recognizedResponseMetadataKeys: string[] = [],
+  includePreview = false,
+): ModelResponseDiagnostics {
+  const record = payload && typeof payload === 'object' ? payload as Record<string, unknown> : {};
+  const choices = Array.isArray(record.choices) ? record.choices : [];
+  const firstChoice = choices[0] && typeof choices[0] === 'object' ? choices[0] as Record<string, unknown> : {};
+  const message = firstChoice.message && typeof firstChoice.message === 'object' ? firstChoice.message as Record<string, unknown> : {};
+  const content = message.content;
+  const contentKind = content === null ? 'null' : typeof content === 'string' ? 'string' : Array.isArray(content) ? 'array' : content === undefined ? 'missing' : 'missing';
+  const candidate = inspectCandidate(envelope.finalText);
+  const diagnostics: ModelResponseDiagnostics = {
+    requestKind,
+    transport: envelope.transport,
+    topLevelKeys: Object.keys(record),
+    choiceKeys: Object.keys(firstChoice),
+    messageKeys: Object.keys(message),
+    contentKind,
+    hasFinalText: Boolean(envelope.finalText),
+    finalTextLength: envelope.finalText?.length ?? 0,
+    reasoningTextLength: envelope.reasoningText?.length ?? 0,
+    toolCallCount: envelope.toolCalls?.length ?? 0,
+    finishReason: envelope.finishReason,
+    usagePresent: envelope.usage !== undefined,
+    candidateKeys: candidate.keys,
+    candidateResponseType: candidate.responseType,
+    candidateStatus: candidate.status,
+    candidateDecision: candidate.decision,
+    candidateActionKind: candidate.actionKind,
+    candidateProposalVersion: candidate.proposalVersion,
+    recognizedResponseMetadataKeys,
+    validationErrors,
+    normalizationNotes,
+  };
+  if (includePreview && envelope.finalText) diagnostics.redactedPreview = redactPreview(envelope.finalText);
+  return diagnostics;
+}