autokap 1.0.6 → 1.0.8

package/dist/agent.d.ts

@@ -0,0 +1,226 @@
+import { Browser } from './browser.js';
+import type { BrowserObservation, BrowserVerificationBundle } from './browser.js';
+import type { AgentConfig, AgentResult, ActionExpectedEffect, ExecutedAction, ActionType, InteractiveElement, OverlayScopeSummary, PageState, VariantCaptureManifest, VerificationResult } from './types.js';
+export declare function buildPromptFingerprint(params: {
+    prompt: string;
+    url: string;
+    pageIdentitySummary?: string | null;
+}): string;
+export declare function inferVariantIdentityFailure(params: {
+    pageId?: string | null;
+    prompt: string;
+    currentUrl: string;
+    visibleText: string;
+    dialogCount: number;
+    pageIdentity?: VariantCaptureManifest["currentPageIdentity"];
+}): string | null;
+/** Build the reasoning body fragment for OpenRouter requests. */
+export declare function resolveProviderReasoningEffort(effort?: AgentConfig['reasoningEffort']): 'xhigh' | 'high' | 'medium' | 'low' | 'none' | null;
+type ProviderBudgetError = {
+    status?: number;
+    message?: string;
+};
+export declare function extractAffordableMaxTokens(message: string): number | null;
+export declare function isInsufficientCreditsError(error: ProviderBudgetError | null | undefined): boolean;
+export declare function deriveRetryMaxTokensFromBudgetError(error: ProviderBudgetError | null | undefined, requestedMaxTokens: number): number | 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, options?: {
+    allowHeuristicWait?: boolean;
+}): {
+    name: ActionType;
+    args: Record<string, unknown>;
+} | null;
+export declare function executeAction(browser: Browser, action: ActionType, args: Record<string, unknown>, options?: {
+    beforeObservation?: BrowserObservation | null;
+    fast?: boolean;
+}): Promise<{
+    success: boolean;
+    error?: string;
+    outcome?: string;
+    stateChanged?: boolean;
+    expectedEffect?: ActionExpectedEffect;
+    observedEffects?: string[];
+    effectConfirmed?: boolean;
+    noEffectReason?: string | null;
+    afterObservation?: BrowserObservation | null;
+}>;
+export declare function verifyCaptureReadiness(browser: Browser, config: AgentConfig, apiKey: string, options?: {
+    assessment?: string;
+    stepNumber?: number;
+}): Promise<VerificationResult>;
+export declare function buildFreshNodeCaptureVerification(params: {
+    browser: Browser;
+    config: AgentConfig;
+    nodeId: string;
+}): Promise<VerificationResult | undefined>;
+export declare function urlsStrictlyMatch(expectedUrl: string | undefined, currentUrl: string | undefined): boolean;
+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;
+    ignoreRecordedViewport?: boolean;
+}): {
+    replayableActions: ExecutedAction[];
+    skipReason: string | null;
+    trimmedActionCount: number;
+};
+export declare function findReplayResumeIndex(replayableActions: ExecutedAction[], currentUrl: string | undefined, startIndex?: number, observation?: BrowserObservation | null, pageIdentity?: VariantCaptureManifest['currentPageIdentity'] | null): number | null;
+export declare function sanitizeSemanticContextHint(value: string | null | undefined): string | null;
+export declare function deriveOverlayScope(params: {
+    pageState: Pick<PageState, 'akTree'>;
+    pageIdentity?: VariantCaptureManifest['currentPageIdentity'] | null;
+    prompt?: string;
+    currentSubgoal?: string | null;
+}): OverlayScopeSummary | null;
+export declare function guardTapTargetSelection(params: {
+    pageState: Pick<PageState, 'akTree'>;
+    action: ActionType;
+    args: Record<string, unknown>;
+    pageIdentity?: VariantCaptureManifest['currentPageIdentity'] | null;
+    currentSubgoal?: string | null;
+    overlayScope?: OverlayScopeSummary | null;
+}): {
+    blocked: boolean;
+    reason?: string;
+    betterCandidate?: {
+        nodeId: string;
+        label: string;
+    };
+};
+export declare function shouldBlockFocusTool(params: {
+    pageState: Pick<PageState, 'akTree'>;
+    pageIdentity?: VariantCaptureManifest['currentPageIdentity'] | null;
+    currentSubgoal?: string | null;
+    overlayScope?: OverlayScopeSummary | null;
+}): string | null;
+export declare function shouldBlockAnalyzeTool(params: {
+    overlayScope?: OverlayScopeSummary | null;
+    overlayChangedRecently: boolean;
+    fingerprint: string;
+    lastAnalyzeFingerprint?: string | null;
+    lastAnalyzeIteration?: number;
+    iteration: number;
+    lastExecutionFailed: boolean;
+}): string | null;
+export declare function buildCompactAKTreeSummary(params: {
+    pageState: Pick<PageState, 'akTree'>;
+    pageIdentity?: VariantCaptureManifest['currentPageIdentity'] | null;
+    currentSubgoal?: string | null;
+    overlayScope?: OverlayScopeSummary | null;
+    lastVerificationFailure?: string;
+}): string;
+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;
+    /** When true, drop recorded resize actions and let the orchestrator own the viewport. */
+    ignoreRecordedViewport?: 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 inferSearchScrollLoopGuard(params: {
+    actionHistory: ExecutedAction[];
+    action: ActionType;
+    args: Record<string, unknown>;
+}): 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;
+/**
+ * Replace base64 image content in older conversation messages with a text placeholder.
+ * Keeps only the most recent `keepRecentImages` user messages that contain screenshots.
+ * This dramatically reduces token cost on long agent runs (40-60% savings).
+ */
+export { trimConversationHistory } from './agent-message-utils.js';
+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;
+    ignoreRecordedViewport?: boolean;
+}): Promise<AgentResult>;