autokap 1.1.4 → 1.1.5

package/dist/agent-message-utils.d.ts

@@ -1,21 +0,0 @@
-/**
- * Message compression and conversation history utilities for the capture agent.
- * Extracted from agent.ts — these are pure functions with no closure dependencies.
- */
-import type { ChatCompletionMessageParam } from 'openai/resources/chat/completions';
-/**
- * Remove old screenshots from the conversation history, keeping only the most recent ones.
- * Replaces image_url parts with a compact text placeholder.
- */
-export declare function compressOldScreenshots(messages: ChatCompletionMessageParam[], keepRecentImages?: number): void;
-/**
- * Strip <page_dom>...</page_dom> blocks from old user messages to reduce token count.
- * Keeps the DOM in the most recent `keepRecentWithDom` user messages intact.
- */
-export declare function compressOldDomBlocks(messages: ChatCompletionMessageParam[], keepRecentWithDom?: number, preservedPrefixMessages?: number): void;
-/**
- * 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;

package/dist/agent-message-utils.js

@@ -1,77 +0,0 @@
-/**
- * Message compression and conversation history utilities for the capture agent.
- * Extracted from agent.ts — these are pure functions with no closure dependencies.
- */
-/**
- * Remove old screenshots from the conversation history, keeping only the most recent ones.
- * Replaces image_url parts with a compact text placeholder.
- */
-export function compressOldScreenshots(messages, keepRecentImages = 3) {
-    let imageCount = 0;
-    for (let i = messages.length - 1; i >= 1; i--) {
-        const msg = messages[i];
-        if (msg.role !== 'user' || !Array.isArray(msg.content))
-            continue;
-        const content = msg.content;
-        const hasImage = content.some(p => p.type === 'image_url');
-        if (!hasImage)
-            continue;
-        imageCount++;
-        if (imageCount <= keepRecentImages)
-            continue;
-        msg.content = content.map(p => p.type === 'image_url'
-            ? { type: 'text', text: '[screenshot removed — older context]' }
-            : p);
-    }
-}
-/**
- * Strip <page_dom>...</page_dom> blocks from old user messages to reduce token count.
- * Keeps the DOM in the most recent `keepRecentWithDom` user messages intact.
- */
-export function compressOldDomBlocks(messages, keepRecentWithDom = 6, preservedPrefixMessages = 1) {
-    const PAGE_DOM_RE = /<page_dom>[\s\S]*?<\/page_dom>/g;
-    const PLACEHOLDER = '<page_dom>[older context — see current iteration for latest DOM]</page_dom>';
-    let domMessageCount = 0;
-    for (let i = messages.length - 1; i >= preservedPrefixMessages; i--) {
-        const msg = messages[i];
-        if (msg.role !== 'user')
-            continue;
-        const contentArr = Array.isArray(msg.content) ? msg.content : null;
-        const hasDom = contentArr
-            ? contentArr.some(p => typeof p === 'object' && 'text' in p && typeof p.text === 'string' && PAGE_DOM_RE.test(p.text))
-            : typeof msg.content === 'string' && PAGE_DOM_RE.test(msg.content);
-        PAGE_DOM_RE.lastIndex = 0;
-        if (!hasDom)
-            continue;
-        domMessageCount++;
-        if (domMessageCount <= keepRecentWithDom)
-            continue;
-        if (contentArr) {
-            for (const part of contentArr) {
-                if (typeof part === 'object' && 'text' in part && typeof part.text === 'string') {
-                    PAGE_DOM_RE.lastIndex = 0;
-                    part.text = part.text.replace(PAGE_DOM_RE, PLACEHOLDER);
-                }
-            }
-        }
-        else if (typeof msg.content === 'string') {
-            PAGE_DOM_RE.lastIndex = 0;
-            msg.content = msg.content.replace(PAGE_DOM_RE, PLACEHOLDER);
-        }
-    }
-}
-/**
- * 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 function trimConversationHistory(messages, maxMessages = 48, preservedPrefixMessages = 1) {
-    compressOldScreenshots(messages, 1);
-    compressOldDomBlocks(messages, 6, preservedPrefixMessages);
-    if (messages.length <= maxMessages + preservedPrefixMessages)
-        return;
-    const preservedPrefix = messages.slice(0, preservedPrefixMessages);
-    const recent = messages.slice(-(maxMessages));
-    messages.splice(0, messages.length, ...preservedPrefix, ...recent);
-}
-//# sourceMappingURL=agent-message-utils.js.map

package/dist/agent-url-utils.d.ts

@@ -1,30 +0,0 @@
-/**
- * URL matching, click guard, and verification cache utilities for the capture agent.
- * Extracted from agent.ts — these are pure functions with no closure dependencies.
- */
-import type { VerificationResult, VariantCaptureManifest } from './types.js';
-import type { BrowserVerificationBundle } from './browser.js';
-export declare function urlsRoughlyMatch(expectedUrl: string | undefined, currentUrl: string | undefined): boolean;
-export declare function normalizeStrictComparableUrl(value: string): string;
-export declare function urlsStrictlyMatch(expectedUrl: string | undefined, currentUrl: string | undefined): boolean;
-export declare function normalizeGuardPageUrl(value: unknown): string;
-export declare function buildClickGuardAnchor(params: Record<string, unknown>): string | null;
-export declare function buildClickGuardSignature(params: Record<string, unknown>, currentUrl?: string): string | null;
-export declare function buildVerificationCacheKey(config: {
-    prompt: string;
-    variantManifest?: VariantCaptureManifest | null;
-    currentLang?: string | null;
-    currentTheme?: string | null;
-    captureCursor?: {
-        targetId?: string;
-    } | null;
-}, bundle: BrowserVerificationBundle): string;
-export declare function cloneVerificationResult(result: VerificationResult): VerificationResult;
-export declare function summarizeVariantManifestForPlanner(manifest: VariantCaptureManifest | undefined): string;
-export declare function buildPageStateFingerprint(pageState: {
-    simplifiedDOM?: string | null;
-    interactiveElements: Array<unknown>;
-    scrollInfo?: {
-        scrollY?: number;
-    } | null;
-}, currentUrl: string): string;

package/dist/agent-url-utils.js

@@ -1,138 +0,0 @@
-/**
- * URL matching, click guard, and verification cache utilities for the capture agent.
- * Extracted from agent.ts — these are pure functions with no closure dependencies.
- */
-import { createHash } from 'crypto';
-// -- URL matching --
-export function urlsRoughlyMatch(expectedUrl, currentUrl) {
-    if (!expectedUrl || !currentUrl)
-        return false;
-    try {
-        const expected = new URL(expectedUrl);
-        const current = new URL(currentUrl);
-        if (expected.origin !== current.origin)
-            return false;
-        const expectedPath = expected.pathname || '/';
-        const currentPath = current.pathname || '/';
-        if (currentPath === expectedPath)
-            return true;
-        if (currentPath.startsWith(expectedPath) && (expectedPath.endsWith('/') || currentPath[expectedPath.length] === '/')) {
-            return true;
-        }
-        return false;
-    }
-    catch {
-        return currentUrl === expectedUrl;
-    }
-}
-export function normalizeStrictComparableUrl(value) {
-    const parsed = new URL(value);
-    const normalizedPath = parsed.pathname.replace(/\/+$/, '') || '/';
-    const searchEntries = Array.from(parsed.searchParams.entries()).sort(([aKey, aValue], [bKey, bValue]) => {
-        if (aKey === bKey)
-            return aValue.localeCompare(bValue);
-        return aKey.localeCompare(bKey);
-    });
-    const normalizedSearch = searchEntries.length > 0
-        ? `?${new URLSearchParams(searchEntries).toString()}`
-        : '';
-    return `${parsed.origin}${normalizedPath}${normalizedSearch}`;
-}
-export function urlsStrictlyMatch(expectedUrl, currentUrl) {
-    if (!expectedUrl || !currentUrl)
-        return false;
-    try {
-        return normalizeStrictComparableUrl(expectedUrl) === normalizeStrictComparableUrl(currentUrl);
-    }
-    catch {
-        return currentUrl.trim().replace(/\/+$/, '') === expectedUrl.trim().replace(/\/+$/, '');
-    }
-}
-export function normalizeGuardPageUrl(value) {
-    if (typeof value !== 'string' || value.trim().length === 0)
-        return '';
-    try {
-        const parsed = new URL(value);
-        return `${parsed.origin}${parsed.pathname}`.replace(/\/$/, '') || parsed.origin;
-    }
-    catch {
-        return value.trim().replace(/\/$/, '');
-    }
-}
-// -- Click guards --
-export function buildClickGuardAnchor(params) {
-    const parts = [];
-    if (typeof params.selector === 'string' && params.selector.trim()) {
-        parts.push(`selector:${params.selector.trim()}`);
-    }
-    if (params.index !== undefined) {
-        parts.push(`index:${String(params.index)}`);
-    }
-    if (typeof params.elementLabel === 'string' && params.elementLabel.trim()) {
-        parts.push(`label:${params.elementLabel.trim().toLowerCase()}`);
-    }
-    if (typeof params.href === 'string' && params.href.trim()) {
-        parts.push(`href:${normalizeGuardPageUrl(params.href)}`);
-    }
-    return parts.length > 0 ? parts.join('|') : null;
-}
-export function buildClickGuardSignature(params, currentUrl) {
-    const anchor = buildClickGuardAnchor(params);
-    if (!anchor)
-        return null;
-    const pageKey = normalizeGuardPageUrl(params.preActionUrl ?? params.postActionUrl ?? currentUrl);
-    return `click|${pageKey}|${anchor}`;
-}
-// -- Verification cache --
-export function buildVerificationCacheKey(config, bundle) {
-    const promptHash = createHash('sha1').update(config.prompt).digest('hex').slice(0, 12);
-    return [
-        bundle.coherenceKey,
-        config.variantManifest?.currentPageId ?? 'main',
-        config.currentLang ?? 'default-lang',
-        config.currentTheme ?? 'default-theme',
-        config.captureCursor?.targetId ?? 'default-target',
-        promptHash,
-    ].join('|');
-}
-export function cloneVerificationResult(result) {
-    return {
-        ...result,
-        usage: result.usage.map(u => ({ ...u })),
-    };
-}
-export function summarizeVariantManifestForPlanner(manifest) {
-    if (!manifest)
-        return '';
-    const parts = [
-        `expected=${manifest.expectedPageIds.join(',') || 'main'}`,
-        `current=${manifest.currentPageId ?? 'main'}`,
-        manifest.currentPageIdentity ? `identity=${manifest.currentPageIdentity.summary}` : '',
-        `completed=${manifest.completedPages.join(',') || 'none'}`,
-        `remaining=${manifest.remainingPages.join(',') || 'none'}`,
-        manifest.lastCheckpointId ? `checkpoint=${manifest.lastCheckpointId}` : '',
-    ];
-    if (manifest.captureStatuses) {
-        parts.push(`statuses=${Object.entries(manifest.captureStatuses)
-            .slice(0, 6)
-            .map(([pageId, status]) => `${pageId}:${status}`)
-            .join('|') || 'none'}`);
-    }
-    if (manifest.previousValidatedCaptures.length > 0) {
-        parts.push(`validated=${manifest.previousValidatedCaptures
-            .slice(-3)
-            .map((capture) => `${capture.pageId}${capture.identity ? `[${capture.identity.summary}]` : ''}:${capture.assessment.slice(0, 80)}`)
-            .join(' | ')}`);
-    }
-    return parts.join('; ');
-}
-// -- Page state fingerprint --
-export function buildPageStateFingerprint(pageState, currentUrl) {
-    return createHash('sha1')
-        .update(pageState.simplifiedDOM || '')
-        .update(String(pageState.interactiveElements.length))
-        .update(String(pageState.scrollInfo?.scrollY ?? 0))
-        .update(currentUrl)
-        .digest('hex');
-}
-//# sourceMappingURL=agent-url-utils.js.map

package/dist/agent.d.ts

@@ -1,226 +0,0 @@
-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>;