autokap 1.0.6 → 1.0.7

package/dist/agent.d.ts

@@ -0,0 +1,142 @@
+import type { ChatCompletionMessageParam } from 'openai/resources/chat/completions';
+import { Browser } from './browser.js';
+import type { BrowserObservation, BrowserVerificationBundle } from './browser.js';
+import type { AgentConfig, AgentResult, ExecutedAction, ActionType, InteractiveElement, PageState, VariantCaptureManifest, VerificationResult } from './types.js';
+export declare function inferVariantIdentityFailure(params: {
+    pageId?: string | null;
+    prompt: string;
+    currentUrl: string;
+    visibleText: string;
+    dialogCount: number;
+    pageIdentity?: VariantCaptureManifest["currentPageIdentity"];
+}): string | null;
+export declare function inferDeterministicReadyDecision(params: {
+    observation: BrowserObservation;
+    assessment: string;
+    targetUrl: string;
+    skipDialogCheck?: boolean;
+    allowSuccess?: boolean;
+}): {
+    verified: boolean;
+    reason?: string;
+} | null;
+export declare function inferManifestReadyDecision(params: {
+    observation: BrowserObservation;
+    assessment: string;
+    config: AgentConfig;
+    bundle: BrowserVerificationBundle;
+}): {
+    verified: boolean;
+    reason?: string;
+} | null;
+/**
+ * Page-signal deterministic verification: accepts when ALL of the following hold:
+ *  1. Assessment text parses as positive (caller already believes ready)
+ *  2. inferVariantIdentityFailure finds no identity mismatch
+ *  3. No loading indicators, readyState === 'complete'
+ *  4. No hard variant (lang/theme) mismatch
+ *  5. No unexpected dialog blocking the page (unless dialog is the target)
+ *
+ * Returns { verified: true } when confident, null when inconclusive (→ LLM).
+ * NEVER returns { verified: false } — absence of evidence is not evidence of absence.
+ */
+export declare function inferPageSignalReadyDecision(params: {
+    observation: BrowserObservation;
+    assessment: string;
+    config: AgentConfig;
+    bundle: BrowserVerificationBundle;
+    identityFailure: string | null;
+}): {
+    verified: boolean;
+} | null;
+/**
+ * Fast-path optimization: extract a PASS/FAIL verdict from LLM text output
+ * using keyword matching, avoiding a separate LLM call when the signal is clear.
+ *
+ * Returns null when uncertain — the caller MUST fall back to an LLM vision call.
+ * Do not add more patterns here; expand LLM fallback coverage instead.
+ */
+export declare function parseVerificationDecisionText(content: string): {
+    verified: boolean;
+    reason?: string;
+} | null;
+export declare function inferActionFromAssistantText(content: string): {
+    name: ActionType;
+    args: Record<string, unknown>;
+} | null;
+export declare function executeAction(browser: Browser, action: ActionType, args: Record<string, unknown>): Promise<{
+    success: boolean;
+    error?: string;
+    outcome?: string;
+    stateChanged?: boolean;
+}>;
+export declare function verifyCaptureReadiness(browser: Browser, config: AgentConfig, apiKey: string, options?: {
+    assessment?: string;
+    stepNumber?: number;
+}): Promise<VerificationResult>;
+export declare function getLivePreviewScreenshot(pageState: Pick<PageState, 'cleanScreenshot' | 'screenshot'>): Buffer;
+export declare function analyzeReplayCandidate(recordedActions: ExecutedAction[], params?: {
+    currentUrl?: string;
+    targetUrl?: string;
+    currentViewport?: {
+        width: number;
+        height: number;
+    } | null;
+    isAuthenticated?: boolean;
+    currentDialogCount?: number | null;
+    pageIdentity?: VariantCaptureManifest['currentPageIdentity'] | null;
+}): {
+    replayableActions: ExecutedAction[];
+    skipReason: string | null;
+};
+export declare function matchRecordedActionToElement(action: Pick<ExecutedAction, 'params'>, interactiveElements: InteractiveElement[]): InteractiveElement | null;
+export declare function resolveReplayActionArgs(action: ExecutedAction, interactiveElements: InteractiveElement[]): {
+    args: Record<string, unknown> | null;
+    reason: string | null;
+};
+export declare function compactReplayActions(recordedActions: ExecutedAction[], params?: {
+    currentUrl?: string;
+    targetUrl?: string;
+    currentViewport?: {
+        width: number;
+        height: number;
+    } | null;
+    /** When true, filter out login/auth actions (session already active). */
+    isAuthenticated?: boolean;
+}): ExecutedAction[];
+export declare function countRecentNoEffectActions(actionHistory: ExecutedAction[]): number;
+export declare function shouldTriggerRecovery(actionHistory: ExecutedAction[]): boolean;
+export declare function inferPrematureGiveUpCorrection(params: {
+    reason: string;
+    actionHistory: ExecutedAction[];
+    lastVerificationFailure?: string;
+    iteration: number;
+    maxIterations: number;
+}): string | null;
+export declare function inferRepeatedActionGuard(params: {
+    actionHistory: ExecutedAction[];
+    action: ActionType;
+    args: Record<string, unknown>;
+    currentUrl?: string;
+}): string | null;
+export interface WorkflowCacheEntry {
+    subgoalName: string;
+    actionSummary: string;
+    selectors: string[];
+}
+export declare function findReusableWorkflow(workflowCache: WorkflowCacheEntry[], subgoalName: string): WorkflowCacheEntry | null;
+/**
+ * Trim the conversation thread to avoid context window overflow.
+ * Always preserves the first `preservedPrefixMessages` entries, then the last maxMessages messages.
+ * Also compresses old screenshots and DOM blocks to save tokens.
+ */
+export declare function trimConversationHistory(messages: ChatCompletionMessageParam[], maxMessages?: number, preservedPrefixMessages?: number): void;
+export declare function runAgent(browser: Browser, config: AgentConfig, apiKey: string): Promise<AgentResult>;
+/**
+ * Replay a previous successful capture's recorded actions instead of running the full AI agent.
+ * Falls back to a full runAgent if replay fails or verification doesn't pass.
+ * Much cheaper than a full agent run: only 1 verification call vs. N agent iterations.
+ */
+export declare function replayAgent(browser: Browser, config: AgentConfig, apiKey: string, recordedActions: ExecutedAction[], options?: {
+    allowFullAgentFallback?: boolean;
+}): Promise<AgentResult>;