autokap 1.0.6 → 1.0.8

package/dist/legacy/video-variant-state.d.ts

@@ -0,0 +1,29 @@
+import { Browser } from '../browser.js';
+import type { VideoPageSignals } from '../types.js';
+export interface VariantStateDetection {
+    lang: {
+        requested: string | undefined;
+        detected: string | null;
+        active: boolean;
+        ambiguous: boolean;
+    };
+    theme: {
+        requested: 'light' | 'dark' | undefined;
+        detected: 'light' | 'dark' | null;
+        active: boolean;
+        ambiguous: boolean;
+    };
+    pageSignals: VideoPageSignals;
+}
+export declare function scoreLocaleSignals(signals: VideoPageSignals, requestedLang?: string): {
+    score: number;
+    reasons: string[];
+    ambiguous: boolean;
+};
+export declare function evaluateRequestedThemeState(signals: VideoPageSignals, requestedTheme?: 'light' | 'dark'): {
+    detected: 'light' | 'dark' | null;
+    active: boolean;
+    ambiguous: boolean;
+    reason: string;
+};
+export declare function detectVariantStateDeterministic(browser: Browser, requestedLang?: string, requestedTheme?: 'light' | 'dark'): Promise<VariantStateDetection>;

package/dist/legacy/video-variant-state.js

@@ -0,0 +1,80 @@
+import { evaluateRequestedLanguageState, evaluateRequestedThemeState as evaluateRequestedThemeStateRich, } from '../session-profile.js';
+function normalizeConfidenceScore(confidence) {
+    switch (confidence) {
+        case 'high':
+            return 1;
+        case 'medium':
+            return 0.78;
+        case 'low':
+        default:
+            return 0.58;
+    }
+}
+export function scoreLocaleSignals(signals, requestedLang) {
+    if (!requestedLang)
+        return { score: 1, reasons: [], ambiguous: false };
+    const languageState = evaluateRequestedLanguageState({
+        currentUrl: signals.url,
+        requestedLang,
+        signals,
+    });
+    if (languageState.active) {
+        return {
+            score: normalizeConfidenceScore(languageState.confidence),
+            reasons: languageState.reasons,
+            ambiguous: false,
+        };
+    }
+    if (languageState.ambiguous) {
+        return {
+            score: languageState.confidence === 'high' ? 0.45 : languageState.confidence === 'medium' ? 0.32 : 0.18,
+            reasons: languageState.reasons,
+            ambiguous: true,
+        };
+    }
+    return {
+        score: 0,
+        reasons: languageState.reasons,
+        ambiguous: false,
+    };
+}
+export function evaluateRequestedThemeState(signals, requestedTheme) {
+    const themeState = evaluateRequestedThemeStateRich({
+        requestedTheme,
+        signals,
+    });
+    return {
+        detected: themeState.detected,
+        active: themeState.active,
+        ambiguous: themeState.ambiguous,
+        reason: themeState.reasons.join('; ') || 'no_theme_signal',
+    };
+}
+export async function detectVariantStateDeterministic(browser, requestedLang, requestedTheme) {
+    const signals = await browser.capturePageSignals();
+    const languageState = evaluateRequestedLanguageState({
+        currentUrl: signals.url,
+        requestedLang,
+        signals,
+    });
+    const themeState = evaluateRequestedThemeStateRich({
+        requestedTheme,
+        signals,
+    });
+    return {
+        lang: {
+            requested: requestedLang,
+            detected: languageState.detected,
+            active: requestedLang ? languageState.active : true,
+            ambiguous: requestedLang ? languageState.ambiguous : false,
+        },
+        theme: {
+            requested: requestedTheme,
+            detected: themeState.detected,
+            active: requestedTheme ? themeState.active : true,
+            ambiguous: requestedTheme ? themeState.ambiguous : false,
+        },
+        pageSignals: signals,
+    };
+}
+//# sourceMappingURL=video-variant-state.js.map

package/dist/legacy/vision-model.d.ts

@@ -0,0 +1,17 @@
+export declare class VisionModelUnsupportedError extends Error {
+    requestedModel: string;
+    fallbackModel?: string;
+    constructor(requestedModel: string, fallbackModel?: string);
+}
+export declare function isImageInputUnsupportedError(err: unknown): boolean;
+export declare function buildVisionModelUnavailableMessage(requestedModel: string, fallbackModel?: string): string;
+export declare function callVisionCapableModel<T>(params: {
+    primaryModel: string;
+    fallbackModel?: string;
+    callModel: (model: string) => Promise<T>;
+    onFallbackActivated?: (model: string, reason: string) => void;
+}): Promise<{
+    result: T;
+    model: string;
+    fellBack: boolean;
+}>;

package/dist/legacy/vision-model.js

@@ -0,0 +1,74 @@
+export class VisionModelUnsupportedError extends Error {
+    requestedModel;
+    fallbackModel;
+    constructor(requestedModel, fallbackModel) {
+        super(buildVisionModelUnavailableMessage(requestedModel, fallbackModel));
+        this.name = 'VisionModelUnsupportedError';
+        this.requestedModel = requestedModel;
+        this.fallbackModel = fallbackModel;
+    }
+}
+function extractNestedErrorMessage(err) {
+    if (!err || typeof err !== 'object')
+        return '';
+    const errorRecord = err;
+    const directMessage = typeof errorRecord.message === 'string' ? errorRecord.message : '';
+    const nestedError = errorRecord.error;
+    const nestedMessage = nestedError && typeof nestedError === 'object' && typeof nestedError.message === 'string'
+        ? nestedError.message
+        : '';
+    if (nestedMessage && nestedMessage === directMessage)
+        return directMessage;
+    return [directMessage, nestedMessage].filter(Boolean).join(' ');
+}
+export function isImageInputUnsupportedError(err) {
+    if (!err || typeof err !== 'object')
+        return false;
+    const errorRecord = err;
+    const status = typeof errorRecord.status === 'number' ? errorRecord.status : undefined;
+    const message = extractNestedErrorMessage(err).toLowerCase();
+    if (!message)
+        return false;
+    const mentionsImageEndpoint = message.includes('no endpoints found that support image input')
+        || message.includes('no providers that support image input')
+        || (message.includes('image input') && message.includes('no') && message.includes('support'))
+        || (message.includes('image input') && message.includes('endpoint') && message.includes('no'));
+    if (!mentionsImageEndpoint)
+        return false;
+    return status === undefined || status === 400 || status === 404 || status === 422;
+}
+export function buildVisionModelUnavailableMessage(requestedModel, fallbackModel) {
+    const fallbackHint = fallbackModel && fallbackModel !== requestedModel
+        ? ` Automatic fallback to "${fallbackModel}" also failed or was unavailable.`
+        : '';
+    return `The model "${requestedModel}" has no available endpoint that supports image input.${fallbackHint} Configure a vision-capable default/fallback model or retry later if the provider is degraded.`;
+}
+export async function callVisionCapableModel(params) {
+    const { primaryModel, fallbackModel, callModel, onFallbackActivated } = params;
+    let fallbackReason = '';
+    try {
+        const result = await callModel(primaryModel);
+        return { result, model: primaryModel, fellBack: false };
+    }
+    catch (err) {
+        if (!isImageInputUnsupportedError(err)) {
+            throw err;
+        }
+        fallbackReason = extractNestedErrorMessage(err) || 'image input unsupported';
+        if (!fallbackModel || fallbackModel === primaryModel) {
+            throw new VisionModelUnsupportedError(primaryModel, fallbackModel);
+        }
+    }
+    try {
+        const result = await callModel(fallbackModel);
+        onFallbackActivated?.(fallbackModel, fallbackReason);
+        return { result, model: fallbackModel, fellBack: true };
+    }
+    catch (fallbackErr) {
+        if (isImageInputUnsupportedError(fallbackErr)) {
+            throw new VisionModelUnsupportedError(primaryModel, fallbackModel);
+        }
+        throw fallbackErr;
+    }
+}
+//# sourceMappingURL=vision-model.js.map

package/dist/llm-healer.d.ts

@@ -0,0 +1,63 @@
+/**
+ * Capture Agent — LLM Healer
+ *
+ * Last-resort recovery: when all deterministic strategies fail,
+ * the healer asks an LLM to analyze the current page state and
+ * produce a replacement opcode.
+ *
+ * Constraints:
+ * - Cannot change the preset's intention
+ * - Cannot change variant order
+ * - Cannot invent new capture targets
+ * - Cannot skip the failed opcode's postcondition
+ * - Max 1 LLM call per healing attempt
+ * - Max 3 healing attempts per run
+ */
+import type { ExecutionOpcode, HealerPatch } from './execution-types.js';
+import type { LLMCallResult } from './llm-provider.js';
+export interface HealerContext {
+    /** The failed opcode */
+    failedOpcode: ExecutionOpcode;
+    /** Index in the program */
+    opcodeIndex: number;
+    /** Serialized AKTree of the current page */
+    akTreeSerialized: string;
+    /** Current page URL */
+    currentUrl: string;
+    /** Screenshot buffer (for multimodal models) */
+    screenshot?: Buffer;
+    /** The 3 opcodes before and after the failed one (for context) */
+    surroundingOpcodes: ExecutionOpcode[];
+    /** Error message from the failed attempt */
+    errorMessage: string;
+}
+export interface HealerResult {
+    healed: boolean;
+    patch?: HealerPatch;
+    reason: string;
+    /** Raw LLM usage for this healing attempt */
+    llmResult?: LLMCallResult;
+}
+export interface HealerLLMProvider {
+    /**
+     * Call the LLM with a healing prompt. Returns raw JSON string.
+     * The provider handles model selection, API keys, etc.
+     */
+    call(prompt: string, screenshot?: Buffer): Promise<{
+        response: string;
+        llmResult: LLMCallResult;
+    }>;
+}
+/**
+ * The LLM Healer — a constrained agent that repairs failed opcodes.
+ */
+export declare class LLMHealer {
+    private llmProvider;
+    private invocationCount;
+    private maxInvocations;
+    constructor(llmProvider: HealerLLMProvider, options?: {
+        maxInvocations?: number;
+    });
+    get remainingInvocations(): number;
+    heal(context: HealerContext): Promise<HealerResult>;
+}

package/dist/llm-healer.js

@@ -0,0 +1,166 @@
+/**
+ * Capture Agent — LLM Healer
+ *
+ * Last-resort recovery: when all deterministic strategies fail,
+ * the healer asks an LLM to analyze the current page state and
+ * produce a replacement opcode.
+ *
+ * Constraints:
+ * - Cannot change the preset's intention
+ * - Cannot change variant order
+ * - Cannot invent new capture targets
+ * - Cannot skip the failed opcode's postcondition
+ * - Max 1 LLM call per healing attempt
+ * - Max 3 healing attempts per run
+ */
+import { ExecutionOpcodeSchema } from './execution-schema.js';
+/**
+ * The LLM Healer — a constrained agent that repairs failed opcodes.
+ */
+export class LLMHealer {
+    llmProvider;
+    invocationCount = 0;
+    maxInvocations;
+    constructor(llmProvider, options) {
+        this.llmProvider = llmProvider;
+        this.maxInvocations = options?.maxInvocations ?? 3;
+    }
+    get remainingInvocations() {
+        return Math.max(0, this.maxInvocations - this.invocationCount);
+    }
+    async heal(context) {
+        if (this.invocationCount >= this.maxInvocations) {
+            return { healed: false, reason: `healer budget exhausted (${this.maxInvocations}/${this.maxInvocations} used)` };
+        }
+        this.invocationCount++;
+        try {
+            const prompt = buildHealerPrompt(context);
+            const { response, llmResult } = await this.llmProvider.call(prompt, context.screenshot);
+            // Parse the LLM response
+            const parsed = parseHealerResponse(response, context);
+            if (!parsed) {
+                return { healed: false, reason: 'healer produced invalid response', llmResult };
+            }
+            if (parsed.cannotHeal) {
+                return { healed: false, reason: parsed.reason ?? 'healer cannot resolve this failure', llmResult };
+            }
+            // Validate replacement opcodes against schema
+            const validOpcodes = [];
+            for (const opcode of parsed.replacementOpcodes) {
+                const result = ExecutionOpcodeSchema.safeParse(opcode);
+                if (!result.success) {
+                    return { healed: false, reason: `healer produced invalid opcode: ${result.error}`, llmResult };
+                }
+                validOpcodes.push(result.data);
+            }
+            if (validOpcodes.length === 0 || validOpcodes.length > 3) {
+                return { healed: false, reason: `healer produced ${validOpcodes.length} opcodes (expected 1-3)`, llmResult };
+            }
+            const patch = {
+                opcodeIndex: context.opcodeIndex,
+                originalOpcode: context.failedOpcode,
+                replacementOpcodes: validOpcodes,
+                reason: parsed.reason ?? 'healer repair',
+                patchedAt: new Date().toISOString(),
+            };
+            return { healed: true, patch, reason: parsed.reason ?? 'healer repair applied', llmResult };
+        }
+        catch (err) {
+            return {
+                healed: false,
+                reason: `healer error: ${err instanceof Error ? err.message : String(err)}`,
+            };
+        }
+    }
+}
+// ── Prompt construction ─────────────────────────────────────────────
+function buildHealerPrompt(context) {
+    const { failedOpcode, errorMessage, akTreeSerialized, currentUrl, surroundingOpcodes } = context;
+    const surroundingDesc = surroundingOpcodes
+        .map((op, i) => `  ${i + 1}. ${op.kind}: ${op.description}`)
+        .join('\n');
+    return `You are a web automation repair agent. An opcode in a deterministic browser automation program has failed. Your job is to analyze the current page state and produce a replacement opcode that achieves the same goal.
+
+## Failed Opcode
+Kind: ${failedOpcode.kind}
+Description: ${failedOpcode.description}
+${failedOpcode.kind === 'CLICK' ? `Selector: ${failedOpcode.selector}` : ''}
+${failedOpcode.kind === 'TYPE' ? `Selector: ${failedOpcode.selector}, Text: ${failedOpcode.text}` : ''}
+${failedOpcode.kind === 'WAIT_FOR' ? `Selector: ${failedOpcode.selector}` : ''}
+
+## Error
+${errorMessage}
+
+## Current Page
+URL: ${currentUrl}
+
+## AKTree (current page structure)
+${akTreeSerialized.slice(0, 8000)}
+
+## Surrounding Opcodes (context)
+${surroundingDesc}
+
+## Rules
+1. You MUST produce the same kind of opcode (${failedOpcode.kind}) or a sequence of 1-3 opcodes that achieve the same postcondition.
+2. You CANNOT change the intention — only fix the selector or interaction method.
+3. You CANNOT invent new navigation targets or capture actions.
+4. Every opcode must have a valid postcondition.
+5. Use selectors you can actually see in the AKTree above.
+
+## Response Format
+Respond with a JSON object:
+{
+  "cannotHeal": false,
+  "reason": "explanation of what you changed",
+  "replacementOpcodes": [
+    { "kind": "${failedOpcode.kind}", "description": "...", "selector": "...", "postcondition": {...}, "recovery": {...}, "timeoutMs": 15000, "maxFailures": 3, ... }
+  ]
+}
+
+Or if you cannot fix it:
+{
+  "cannotHeal": true,
+  "reason": "explanation of why this cannot be fixed"
+}
+
+Respond ONLY with the JSON object, no markdown, no explanation outside JSON.`;
+}
+function parseHealerResponse(response, context) {
+    try {
+        // Extract JSON from response (handle markdown code blocks)
+        const jsonStr = response
+            .replace(/```json\s*/g, '')
+            .replace(/```\s*/g, '')
+            .trim();
+        const parsed = JSON.parse(jsonStr);
+        if (typeof parsed !== 'object' || parsed === null)
+            return null;
+        if (parsed.cannotHeal) {
+            return {
+                cannotHeal: true,
+                reason: parsed.reason ?? null,
+                replacementOpcodes: [],
+            };
+        }
+        if (!Array.isArray(parsed.replacementOpcodes))
+            return null;
+        // Inject the original postcondition and recovery into replacement opcodes
+        // (healer cannot skip postconditions)
+        const enriched = parsed.replacementOpcodes.map((op) => ({
+            ...op,
+            postcondition: op.postcondition ?? context.failedOpcode.postcondition,
+            recovery: op.recovery ?? context.failedOpcode.recovery,
+            timeoutMs: op.timeoutMs ?? context.failedOpcode.timeoutMs,
+            maxFailures: op.maxFailures ?? context.failedOpcode.maxFailures,
+        }));
+        return {
+            cannotHeal: false,
+            reason: parsed.reason ?? null,
+            replacementOpcodes: enriched,
+        };
+    }
+    catch {
+        return null;
+    }
+}
+//# sourceMappingURL=llm-healer.js.map

package/dist/llm-provider.d.ts

@@ -0,0 +1,29 @@
+/**
+ * Capture Agent — LLM Provider
+ *
+ * Thin wrapper around OpenAI SDK for OpenRouter calls.
+ * Used by: capture verification, alt text generation, healer.
+ */
+export interface LLMCallResult {
+    text: string;
+    model: string;
+    promptTokens: number;
+    completionTokens: number;
+    costEur: number;
+    /** OpenRouter generation ID for async cost resolution */
+    generationId: string | null;
+}
+export interface LLMProviderConfig {
+    apiKey: string;
+    /** Model to use. Default: google/gemini-2.5-flash */
+    model?: string;
+    /** Max tokens for response. Default: 200 */
+    maxTokens?: number;
+    /** Timeout in ms. Default: 15000 */
+    timeoutMs?: number;
+}
+/**
+ * Makes a single LLM call with optional image input.
+ * Returns the text response and usage metadata.
+ */
+export declare function callLLM(config: LLMProviderConfig, systemPrompt: string, userContent: string, image?: Buffer): Promise<LLMCallResult>;

package/dist/llm-provider.js

@@ -0,0 +1,80 @@
+/**
+ * Capture Agent — LLM Provider
+ *
+ * Thin wrapper around OpenAI SDK for OpenRouter calls.
+ * Used by: capture verification, alt text generation, healer.
+ */
+import OpenAI from 'openai';
+import { createOpenRouterCompletion } from './openrouter-client.js';
+const OPENROUTER_BASE_URL = 'https://openrouter.ai/api/v1';
+const DEFAULT_MODEL = 'google/gemini-2.5-flash';
+/**
+ * Makes a single LLM call with optional image input.
+ * Returns the text response and usage metadata.
+ */
+export async function callLLM(config, systemPrompt, userContent, image) {
+    const client = new OpenAI({
+        baseURL: OPENROUTER_BASE_URL,
+        apiKey: config.apiKey,
+    });
+    const model = config.model ?? DEFAULT_MODEL;
+    const maxTokens = config.maxTokens ?? 200;
+    const messages = [
+        { role: 'system', content: systemPrompt },
+    ];
+    if (image) {
+        const base64 = image.toString('base64');
+        messages.push({
+            role: 'user',
+            content: [
+                { type: 'text', text: userContent },
+                {
+                    type: 'image_url',
+                    image_url: { url: `data:image/png;base64,${base64}`, detail: 'low' },
+                },
+            ],
+        });
+    }
+    else {
+        messages.push({ role: 'user', content: userContent });
+    }
+    const params = {
+        model,
+        messages,
+        max_tokens: maxTokens,
+        temperature: 0.1,
+    };
+    const controller = new AbortController();
+    const timer = setTimeout(() => controller.abort(), config.timeoutMs ?? 15000);
+    try {
+        const response = await createOpenRouterCompletion(client, params, { signal: controller.signal });
+        clearTimeout(timer);
+        const text = response.choices?.[0]?.message?.content?.trim() ?? '';
+        const usage = response.usage;
+        return {
+            text,
+            model: response.model ?? model,
+            promptTokens: usage?.prompt_tokens ?? 0,
+            completionTokens: usage?.completion_tokens ?? 0,
+            costEur: estimateCost(model, usage?.prompt_tokens ?? 0, usage?.completion_tokens ?? 0),
+            generationId: response.id ?? null,
+        };
+    }
+    catch (err) {
+        clearTimeout(timer);
+        throw err;
+    }
+}
+/**
+ * Rough cost estimation based on known model pricing.
+ * Actual cost is resolved asynchronously via OpenRouter generation API.
+ */
+function estimateCost(model, promptTokens, completionTokens) {
+    // Gemini 2.5 Flash pricing (approximate)
+    if (model.includes('gemini')) {
+        return (promptTokens * 0.15 + completionTokens * 0.6) / 1_000_000;
+    }
+    // Fallback: conservative estimate
+    return (promptTokens * 0.5 + completionTokens * 1.5) / 1_000_000;
+}
+//# sourceMappingURL=llm-provider.js.map

package/dist/llm-usage.d.ts

@@ -0,0 +1,17 @@
+import type { ChatCompletion } from 'openai/resources/chat/completions';
+import type { StepUsage } from './types.js';
+export type LlmUsageSnapshot = Pick<StepUsage, 'generationId' | 'modelUsed' | 'promptTokens' | 'completionTokens' | 'totalTokens' | 'cacheReadTokens' | 'cacheWriteTokens' | 'reasoningTokens'>;
+export declare function extractLlmUsageSnapshot(response: ChatCompletion): LlmUsageSnapshot;
+export declare function buildStepUsageFromSnapshot(snapshot: LlmUsageSnapshot, params: {
+    stepNumber: number;
+    stepType: StepUsage['stepType'];
+    modelRequested: string;
+    imagesInPrompt: number;
+}): StepUsage;
+export declare function normalizeLlmUsageSnapshot(snapshot: Partial<LlmUsageSnapshot>): LlmUsageSnapshot;
+export declare function extractStepUsage(response: ChatCompletion, params: {
+    stepNumber: number;
+    stepType: StepUsage['stepType'];
+    modelRequested: string;
+    imagesInPrompt: number;
+}): StepUsage;

package/dist/llm-usage.js

@@ -0,0 +1,45 @@
+export function extractLlmUsageSnapshot(response) {
+    const usageDetails = response.usage;
+    const promptDetails = usageDetails?.prompt_tokens_details;
+    const completionDetails = usageDetails?.completion_tokens_details;
+    return {
+        generationId: response.id ?? null,
+        modelUsed: response.model ?? null,
+        promptTokens: response.usage?.prompt_tokens ?? null,
+        completionTokens: response.usage?.completion_tokens ?? null,
+        totalTokens: response.usage?.total_tokens ?? null,
+        cacheReadTokens: promptDetails?.cached_tokens
+            ?? usageDetails?.cache_read_input_tokens
+            ?? null,
+        cacheWriteTokens: promptDetails?.cache_creation_input_tokens
+            ?? usageDetails?.cache_write_input_tokens
+            ?? null,
+        reasoningTokens: completionDetails?.reasoning_tokens
+            ?? null,
+    };
+}
+export function buildStepUsageFromSnapshot(snapshot, params) {
+    return {
+        stepNumber: params.stepNumber,
+        stepType: params.stepType,
+        modelRequested: params.modelRequested,
+        imagesInPrompt: params.imagesInPrompt,
+        ...snapshot,
+    };
+}
+export function normalizeLlmUsageSnapshot(snapshot) {
+    return {
+        generationId: snapshot.generationId ?? null,
+        modelUsed: snapshot.modelUsed ?? null,
+        promptTokens: snapshot.promptTokens ?? null,
+        completionTokens: snapshot.completionTokens ?? null,
+        totalTokens: snapshot.totalTokens ?? null,
+        cacheReadTokens: snapshot.cacheReadTokens ?? null,
+        cacheWriteTokens: snapshot.cacheWriteTokens ?? null,
+        reasoningTokens: snapshot.reasoningTokens ?? null,
+    };
+}
+export function extractStepUsage(response, params) {
+    return buildStepUsageFromSnapshot(extractLlmUsageSnapshot(response), params);
+}
+//# sourceMappingURL=llm-usage.js.map

package/dist/logger.d.ts

@@ -1,4 +1,4 @@
-export type LogLevel = 'info' | 'action' | 'success' | 'error' | 'ai';
+export type LogLevel = 'info' | 'warn' | 'action' | 'success' | 'error' | 'ai';
 export type LogKind = 'reasoning' | 'action' | 'system' | 'guidance';
 export interface LogEntry {
     level: LogLevel;
@@ -25,6 +25,8 @@ interface LoggerContext {
     onScreenshot?: OnScreenshotCallback | null;
     onReasoningDelta?: OnReasoningDeltaCallback | null;
 }
+export declare function setDebugEnabled(enabled: boolean): void;
+export declare function isDebugEnabled(): boolean;
 export declare function runWithLoggerCallbacks<T>(callbacks: LoggerContext, fn: () => Promise<T>): Promise<T>;
 export declare function setOnLog(cb: OnLogCallback | null): void;
 export declare function setOnScreenshot(cb: OnScreenshotCallback | null): void;
@@ -33,8 +35,10 @@ export declare function emitReasoningDelta(delta: string, messageId: string): vo
 export declare const logger: {
     /** User-visible informational log — shown in both console and UI. */
     info(msg: string): void;
-    /** Internal debug log — console only, NOT emitted to the UI callback. */
+    /** Internal debug log — only printed when --debug is enabled. Console only, NOT emitted to the UI callback. */
     debug(msg: string): void;
+    /** Security / rate-limit warnings — emitted to both console and UI. */
+    warn(msg: string): void;
     action(iteration: number, maxIter: number, action: string, params: Record<string, unknown>, context?: {
         lang?: string;
         theme?: string;

package/dist/logger.js

@@ -2,7 +2,14 @@ import { AsyncLocalStorage } from 'node:async_hooks';
 import chalk from 'chalk';
 let _onLog = null;
 let _onScreenshot = null;
+let _debugEnabled = false;
 const _loggerContext = new AsyncLocalStorage();
+export function setDebugEnabled(enabled) {
+    _debugEnabled = enabled;
+}
+export function isDebugEnabled() {
+    return _debugEnabled;
+}
 export async function runWithLoggerCallbacks(callbacks, fn) {
     return _loggerContext.run(callbacks, fn);
 }
@@ -42,10 +49,17 @@ export const logger = {
         console.log(chalk.cyan('[INFO]'), msg);
         emit({ level: 'info', message: msg, timestamp: Date.now(), kind: 'system' });
     },
-    /** Internal debug log — console only, NOT emitted to the UI callback. */
+    /** Internal debug log — only printed when --debug is enabled. Console only, NOT emitted to the UI callback. */
     debug(msg) {
+        if (!_debugEnabled)
+            return;
         console.log(chalk.gray('[DEBUG]'), msg);
     },
+    /** Security / rate-limit warnings — emitted to both console and UI. */
+    warn(msg) {
+        console.log(chalk.yellow('[WARN]'), msg);
+        emit({ level: 'warn', message: msg, timestamp: Date.now(), kind: 'system' });
+    },
     action(iteration, maxIter, action, params, context) {
         const paramsStr = Object.entries(params)
             .map(([k, v]) => `${k}=${JSON.stringify(v)}`)