@phuetz/code-buddy 1.1.0 → 1.3.0

package/dist/agent/self-improvement/tool-types.d.ts

@@ -0,0 +1,48 @@
+/**
+ * Types for the TOOL self-improvement path (sibling to the lesson path). A tool
+ * "covers" a scenario only BEHAVIORALLY: it must run on fixed inputs and produce
+ * asserted outputs (a presence predicate would be trivially gamed).
+ *
+ * @module agent/self-improvement/tool-types
+ */
+import type { AuthoredToolSpec } from './authored-tool-runtime.js';
+/** One behavioural assertion: run the tool on `input`, output must contain ALL of `expectIncludes`. */
+export interface ToolCase {
+    input: Record<string, unknown>;
+    expectIncludes: string[];
+}
+/**
+ * A behavioural benchmark for an authored tool. `visibleCases` describe the
+ * capability (and may be shown to the proposer); `heldOutCases` use fresh inputs
+ * and are NEVER shown to the proposer — a tool that hardcodes the visible
+ * outputs passes visible but fails held-out (the anti-reward-hacking defence).
+ */
+export interface ToolBenchmarkScenario {
+    id: string;
+    /** Human capability description (safe to show the proposer). */
+    capability: string;
+    description: string;
+    visibleCases: ToolCase[];
+    heldOutCases: ToolCase[];
+}
+/** A candidate authored tool, motivated by a scenario. The spec must be produced WITHOUT seeing heldOutCases. */
+export interface ToolProposal {
+    id: string;
+    targetScenarioId: string;
+    experienceId?: string;
+    spec: AuthoredToolSpec;
+}
+export type ToolGateRejection = 'static-scan' | 'visible-fail' | 'heldout-fail';
+export interface ToolGateOutcome {
+    accepted: boolean;
+    proposalId: string;
+    scenarioId: string;
+    visiblePassed: number;
+    visibleTotal: number;
+    heldOutPassed: number;
+    heldOutTotal: number;
+    rejectionReason?: ToolGateRejection;
+    reasons: string[];
+    /** Name of the tool left registered (only when accepted AND kept). */
+    appliedRef?: string;
+}

package/dist/agent/self-improvement/tool-types.js

@@ -0,0 +1,9 @@
+/**
+ * Types for the TOOL self-improvement path (sibling to the lesson path). A tool
+ * "covers" a scenario only BEHAVIORALLY: it must run on fixed inputs and produce
+ * asserted outputs (a presence predicate would be trivially gamed).
+ *
+ * @module agent/self-improvement/tool-types
+ */
+export {};
+//# sourceMappingURL=tool-types.js.map

package/dist/agent/self-improvement/types.d.ts

@@ -97,13 +97,15 @@ export interface GateOutcome {
 /** One accepted improvement, kept as an evolutionary stepping stone (DGM). */
 export interface ArchiveEntry {
     proposalId: string;
-    kind: ImprovementProposal['kind'];
+    kind: ImprovementProposal['kind'] | 'tool' | 'skill';
     targetScenarioId: string;
     experienceId?: string;
     delta: number;
     scoreAfter: number;
     /** Id of the applied lesson (so it can be traced/rolled back later). */
     appliedRef?: string;
+    /** For consolidation: the umbrella skill an archived sibling was absorbed into. */
+    absorbedInto?: string;
     createdAt: string;
     /** Sentinel for auditability, mirrors the learning-loop convention. */
     reviewedBy: string;

package/dist/agent/session-end-flush.d.ts

@@ -9,7 +9,10 @@
  *  2. reusable lesson candidates via the existing review-gated
  *     auto-proposer (PENDING only — a human approves them into lessons.md,
  *     which the per-turn `<lessons_context>` injection then re-injects on
- *     future runs).
+ *     future runs);
+ *  3. declarative long-term memory candidates via the review-gated memory
+ *     queue. These do not enter prompt-injected persistent memory until a
+ *     human accepts them.
  *
  * Guard-rails: trivial sessions are skipped (no LLM call, no file), and
  * everything written here passes the privacy lint first (PII/secret spans
@@ -32,6 +35,8 @@ export interface SessionEndFlushInput {
 export interface SessionEndFlushResult {
     /** Lesson candidates enqueued for review (`buddy lessons` to approve). */
     proposedLessons: number;
+    /** Declarative memory candidates enqueued for review (`/memory candidates`). */
+    proposedMemories: number;
     /** Absolute path of the handoff file, when one was (re)written. */
     handoffPath?: string;
     openRisks: string[];

package/dist/agent/session-end-flush.js

@@ -9,7 +9,10 @@
  *  2. reusable lesson candidates via the existing review-gated
  *     auto-proposer (PENDING only — a human approves them into lessons.md,
  *     which the per-turn `<lessons_context>` injection then re-injects on
- *     future runs).
+ *     future runs);
+ *  3. declarative long-term memory candidates via the review-gated memory
+ *     queue. These do not enter prompt-injected persistent memory until a
+ *     human accepts them.
  *
  * Guard-rails: trivial sessions are skipped (no LLM call, no file), and
  * everything written here passes the privacy lint first (PII/secret spans
@@ -145,7 +148,7 @@ export function writeHandoffSync(history, workDir = process.cwd(), options = {})
     }
     lines.push('', '## Reprise', '', risks.length > 0
         ? '- Commencer par lever les risques ouverts ci-dessus.'
-        : '- Continuer le dernier objectif, ou `buddy --continue` pour recharger la session.', '- Leçons en attente de revue : `buddy lessons` (candidats proposés en fin de session).', '');
+        : '- Continuer le dernier objectif, ou `buddy --continue` pour recharger la session.', '- Leçons en attente de revue : `buddy lessons` (candidats proposés en fin de session).', '- Mémoires en attente de revue : `/memory candidates` puis `/memory accept <id> <reviewer>`.', '');
     const content = redactSecrets(lines.join('\n'));
     const dir = path.join(workDir, '.codebuddy');
     const target = path.join(dir, 'HANDOFF.md');
@@ -168,7 +171,7 @@ export function writeHandoffSync(history, workDir = process.cwd(), options = {})
  * no-ops on trivial sessions, never throws.
  */
 export async function runSessionEndFlush(input) {
-    const empty = { proposedLessons: 0, openRisks: [] };
+    const empty = { proposedLessons: 0, proposedMemories: 0, openRisks: [] };
     try {
         if (!isFeatureEnabled('SESSION_END_FLUSH')) {
             return { ...empty, skipped: 'disabled' };
@@ -195,12 +198,25 @@ export async function runSessionEndFlush(input) {
         catch (err) {
             logger.debug('[session-end-flush] lesson proposal failed', { err: String(err) });
         }
-        if (proposedLessons > 0 || handoffPath) {
+        let proposedMemories = 0;
+        if (process.env.CODEBUDDY_MEMORY_AUTO_PROPOSE !== 'false') {
+            try {
+                const { proposeMemoryCandidatesFromSession } = await import('../memory/memory-auto-proposer.js');
+                const proposed = await proposeMemoryCandidatesFromSession(history, workDir, input.client, input.sessionId);
+                proposedMemories = proposed.length;
+            }
+            catch (err) {
+                logger.debug('[session-end-flush] memory proposal failed', { err: String(err) });
+            }
+        }
+        if (proposedLessons > 0 || proposedMemories > 0 || handoffPath) {
             logger.info(`[session-end-flush] ${proposedLessons} lesson candidate(s) proposed` +
+                `, ${proposedMemories} memory candidate(s) proposed` +
                 (handoffPath ? `, handoff written to ${path.relative(workDir, handoffPath)}` : ''));
         }
         return {
             proposedLessons,
+            proposedMemories,
             ...(handoffPath ? { handoffPath } : {}),
             openRisks,
         };

package/dist/agent/streaming/streaming-handler.d.ts

@@ -118,6 +118,12 @@ export interface AccumulatedMessage {
     content?: string;
     /** Accumulated tool calls */
     tool_calls?: CodeBuddyToolCall[];
+    /**
+     * The terminal `finish_reason`/`stop_reason` reported by the provider on the
+     * final chunk (`'stop'` | `'length'` | `'tool_calls'` | …). Used by the
+     * executor's in-loop recovery to detect a length-truncated turn.
+     */
+    finishReason?: string | null;
     /** Any additional fields from the API */
     [key: string]: unknown;
 }
@@ -153,6 +159,7 @@ export declare class StreamingHandler {
     private accumulatedMessage;
     private accumulatedRawContent;
     private accumulatedReasoningContent;
+    private accumulatedFinishReason;
     private tokenCounter;
     private lastTokenUpdate;
     private toolCallsYielded;

package/dist/agent/streaming/streaming-handler.js

@@ -42,6 +42,7 @@ export class StreamingHandler {
     accumulatedMessage = {};
     accumulatedRawContent = '';
     accumulatedReasoningContent = '';
+    accumulatedFinishReason = null;
     tokenCounter = null;
     lastTokenUpdate = 0;
     toolCallsYielded = false;
@@ -86,6 +87,11 @@ export class StreamingHandler {
         }
         // Accumulate the message using reducer
         this.accumulatedMessage = reduceStreamChunk(this.accumulatedMessage, chunk);
+        // Capture the terminal finish_reason (present on the final chunk). The last
+        // non-null value wins so a trailing usage-only chunk can't clear it.
+        if (chunk.choices[0].finish_reason) {
+            this.accumulatedFinishReason = chunk.choices[0].finish_reason;
+        }
         // Extract content delta
         const rawContentDelta = chunk.choices[0].delta?.content || '';
         this.accumulatedRawContent += rawContentDelta;
@@ -208,7 +214,7 @@ export class StreamingHandler {
      * @returns The accumulated message with all processed content and tool calls
      */
     getAccumulatedMessage() {
-        return { ...this.accumulatedMessage };
+        return { ...this.accumulatedMessage, finishReason: this.accumulatedFinishReason };
     }
     /**
      * Gets the raw accumulated content before sanitization.
@@ -261,6 +267,7 @@ export class StreamingHandler {
         this.accumulatedMessage = {};
         this.accumulatedRawContent = '';
         this.accumulatedReasoningContent = '';
+        this.accumulatedFinishReason = null;
         this.lastTokenUpdate = 0;
         this.toolCallsYielded = false;
     }

package/dist/agent/tool-executor.js

@@ -97,6 +97,7 @@ const TOOL_CATEGORY_MAP = {
     // Media
     screenshot: 'media',
     camera_snapshot: 'media',
+    camera_analyze: 'media',
     audio: 'media',
     video: 'media',
     ocr: 'media',

package/dist/agent/tool-handler.d.ts

@@ -37,6 +37,11 @@ export interface ToolHandlerDependencies {
     /** Coordinates auto-repair attempts for failed commands */
     repairCoordinator: RepairCoordinator;
 }
+export interface NormalizedHallucinatedToolCall {
+    toolName: string;
+    args: Record<string, unknown>;
+}
+export declare function normalizeHallucinatedLocalToolCall(toolName: string, args: Record<string, unknown>): NormalizedHallucinatedToolCall | null;
 /**
  * ToolHandler manages tool instantiation and execution
  *

package/dist/agent/tool-handler.js

@@ -16,7 +16,8 @@
  * Tool instances are lazy-loaded on first access for optimal startup time.
  */
 import { TextEditorTool, MorphEditorTool, ImageTool, BashTool, } from "../tools/index.js";
-import { getFormalToolRegistry, createTextEditorTools, createBashTools, createLsTools, createSearchTools, createWebTools, createTodoTools, createCronjobTools, createDockerTools, createKubernetesTools, createGitTools, createMiscTools, createBrowserTools, createProcessTools, createVisionTools, createScriptTools, createPlanTools, createKnowledgeTools, createRelationshipIntelligenceTools, createInternetScoutTools, createLeadScoutTools, createBrowserOperatorTools, createMemoryTools, createParallelTools, createAttentionTools, createSkillsInspectionTools, createLessonsTools, createUserModelTools, createAliasTools, createMultimodalTools, createAdvancedTools, createCanvasTools, createLspTools, createMergeConflictTools, createVulnScannerTools, createCodebaseReplaceTools, createAdvisorTools, createFleetTools, createAskUserQuestionTools, createExitPlanModeTools, createGuiTools, createSessionTools, createGitNexusTools, createScreenpipeTools, } from "../tools/registry/index.js";
+import { getFormalToolRegistry, createTextEditorTools, createBashTools, createLsTools, createSearchTools, createWebTools, createTodoTools, createCronjobTools, createDockerTools, createKubernetesTools, createGitTools, createMiscTools, createBrowserTools, createProcessTools, createVisionTools, createScriptTools, createPlanTools, createKnowledgeTools, createRelationshipIntelligenceTools, createInternetScoutTools, createLeadScoutTools, createBrowserOperatorTools, createWindowsTools, createMemoryTools, createParallelTools, createAttentionTools, createSkillsInspectionTools, createLessonsTools, createUserModelTools, createAliasTools, createMultimodalTools, createAdvancedTools, createCanvasTools, createLspTools, createMergeConflictTools, createVulnScannerTools, createCodebaseReplaceTools, createAdvisorTools, createFleetTools, createAskUserQuestionTools, createExitPlanModeTools, createGuiTools, createSessionTools, createGitNexusTools, createScreenpipeTools, } from "../tools/registry/index.js";
+import { createRegisterToolTool } from "../tools/register-tool-handler.js";
 import { getMCPManager } from "../codebuddy/tools.js";
 import { getErrorMessage } from "../errors/index.js";
 import { logger } from "../utils/logger.js";
@@ -44,6 +45,67 @@ const READ_ONLY_FILE_TOOLS = new Set([
     'find_definition',
     'search_multi',
 ]);
+export function normalizeHallucinatedLocalToolCall(toolName, args) {
+    const normalizedName = toolName.toLowerCase().replace(/\s+/g, '');
+    const thoughtToolCallSuffix = normalizedName.match(/^thought_tool_call_\d+(?:_\d+)*\.(bash|create_file|write_file|view_file|read_file)$/)?.[1];
+    if (thoughtToolCallSuffix === 'bash') {
+        const command = firstStringValue(args.command, args.cmd, args.shell_command, args.command_to_execute, args.code);
+        return {
+            toolName: 'bash',
+            args: command ? { ...args, command } : args,
+        };
+    }
+    if (thoughtToolCallSuffix === 'create_file' || thoughtToolCallSuffix === 'write_file') {
+        const path = firstStringValue(args.path, args.file_path, args.target_file, args.filename, args.file);
+        const content = firstStringValue(args.content, args.file_content, args.contents, args.text);
+        return {
+            toolName: 'create_file',
+            args: {
+                ...args,
+                ...(path ? { path } : {}),
+                ...(content !== undefined ? { content } : {}),
+            },
+        };
+    }
+    if (thoughtToolCallSuffix === 'view_file' || thoughtToolCallSuffix === 'read_file') {
+        const path = firstStringValue(args.path, args.file_path, args.target_file, args.filename, args.file);
+        return {
+            toolName: 'view_file',
+            args: path ? { ...args, path } : args,
+        };
+    }
+    if (normalizedName.includes('bash_tool:execute') ||
+        normalizedName.includes('thought-tool:execute_command') ||
+        normalizedName === 'execute_command') {
+        const command = firstStringValue(args.command, args.cmd, args.shell_command, args.command_to_execute, args.code);
+        return {
+            toolName: 'bash',
+            args: command ? { ...args, command } : args,
+        };
+    }
+    if (normalizedName.includes('bash_tool:write_file') ||
+        normalizedName.includes('thought-tool:write_file') ||
+        normalizedName.includes('call:bash_tool:write_file')) {
+        const path = firstStringValue(args.path, args.file_path, args.target_file, args.filename, args.file);
+        const content = firstStringValue(args.content, args.file_content, args.contents, args.text);
+        return {
+            toolName: 'create_file',
+            args: {
+                ...args,
+                ...(path ? { path } : {}),
+                ...(content !== undefined ? { content } : {}),
+            },
+        };
+    }
+    return null;
+}
+function firstStringValue(...values) {
+    for (const value of values) {
+        if (typeof value === 'string' && value.trim())
+            return value;
+    }
+    return undefined;
+}
 /**
  * ToolHandler manages tool instantiation and execution
  *
@@ -156,6 +218,7 @@ export class ToolHandler {
             ...createInternetScoutTools(),
             ...createLeadScoutTools(),
             ...createBrowserOperatorTools(),
+            ...(process.platform === 'win32' ? createWindowsTools() : []),
             ...createMemoryTools(),
             ...createParallelTools(),
             ...createAttentionTools(),
@@ -177,6 +240,8 @@ export class ToolHandler {
             ...createSessionTools(),
             ...createGitNexusTools(),
             ...createScreenpipeTools(),
+            // Self-improvement: the agent can author its own tools (opt-in only).
+            ...(process.env.CODEBUDDY_SELF_IMPROVE === 'true' ? [createRegisterToolTool()] : []),
         ];
         // Register canonical-prefix alias tools (shell_exec→bash, file_read→view_file, etc.)
         const aliasTools = createAliasTools(allTools);
@@ -244,8 +309,25 @@ export class ToolHandler {
         const startTime = Date.now();
         const hooksManager = getToolHooksManager();
         try {
-            const args = JSON.parse(toolCall.function.arguments);
-            const toolName = toolCall.function.name;
+            let args = JSON.parse(toolCall.function.arguments);
+            let toolName = toolCall.function.name;
+            const normalized = normalizeHallucinatedLocalToolCall(toolName, args);
+            if (normalized) {
+                logger.debug('Normalized hallucinated local tool name', {
+                    from: toolName,
+                    to: normalized.toolName,
+                });
+                toolName = normalized.toolName;
+                args = normalized.args;
+                toolCall = {
+                    ...toolCall,
+                    function: {
+                        ...toolCall.function,
+                        name: toolName,
+                        arguments: JSON.stringify(args),
+                    },
+                };
+            }
             // Create hook context
             let hookContext = {
                 toolName,
@@ -693,6 +775,12 @@ export class ToolHandler {
      */
     async executeBashWithHooks(args, context) {
         const command = args.command;
+        if (typeof command !== 'string' || command.trim() === '') {
+            return {
+                success: false,
+                error: 'bash: missing a non-empty "command" string argument. Put the shell command to run in the "command" field.',
+            };
+        }
         // Execute pre-bash hooks
         try {
             await this.deps.hooksManager.executeHooks("pre-bash", { command });
@@ -754,6 +842,15 @@ export class ToolHandler {
                 const args = JSON.parse(toolCall.function.arguments);
                 const command = args.command;
                 const timeout = args.timeout || 30000;
+                // A weaker model can emit a `bash` call without a `command` (or a
+                // non-string one). Fail with a clear, recoverable message instead of
+                // crashing downstream on `command.trim()` (auto-repair can then re-prompt).
+                if (typeof command !== 'string' || command.trim() === '') {
+                    return {
+                        success: false,
+                        error: 'bash: missing a non-empty "command" string argument. Put the shell command to run in the "command" field.',
+                    };
+                }
                 const gen = this.bash.executeStreaming(command, timeout);
                 let result = await gen.next();
                 while (!result.done) {
@@ -778,8 +875,15 @@ export class ToolHandler {
                     mode: mode,
                 });
                 reasoner.setMode(mode);
+                const problem = args.problem;
+                if (typeof problem !== 'string' || problem.trim() === '') {
+                    return {
+                        success: false,
+                        error: 'reason: missing a non-empty "problem" string argument. Put the problem to reason about in the "problem" field.',
+                    };
+                }
                 const gen = reasoner.solveStreaming({
-                    description: args.problem,
+                    description: problem,
                     context: args.context,
                     constraints: args.constraints,
                 });
@@ -796,6 +900,31 @@ export class ToolHandler {
                 return { success: false, error: `Reasoning error: ${getErrorMessage(error)}` };
             }
         }
+        // generate_document: stream the build phases (prepare → parse → build →
+        // write → verify → done) so the UI shows the steps unfold one by one
+        // instead of a single opaque "Created X" at the end.
+        if (toolName === 'generate_document') {
+            try {
+                const args = JSON.parse(toolCall.function.arguments);
+                const { executeGenerateDocumentStreaming } = await import('../tools/document-generator.js');
+                const gen = executeGenerateDocumentStreaming({
+                    type: args.type,
+                    title: args.title,
+                    content: args.content,
+                    outputPath: args.outputPath ?? args.output_path,
+                    theme: args.theme,
+                });
+                let r = await gen.next();
+                while (!r.done) {
+                    yield r.value;
+                    r = await gen.next();
+                }
+                return r.value ?? { success: false, error: 'Document tool returned no result' };
+            }
+            catch (error) {
+                return { success: false, error: `Document streaming error: ${getErrorMessage(error)}` };
+            }
+        }
         // Fallback: non-streaming execution
         return await this.executeTool(toolCall);
     }

package/dist/browser-automation/browser-operator-executor.js

@@ -189,12 +189,27 @@ export class BrowserOperatorExecutor {
                         'access denied',
                         'security checkpoint',
                     ];
+                    const sensitivePlatforms = [
+                        'yandex.com',
+                        'yandex.ru',
+                        'login.microsoftonline.com',
+                        'zoom.us',
+                    ];
                     for (const indicator of antiBotIndicators) {
                         if (lower.includes(indicator)) {
                             raiseCheckpoint(`Security checkpoint detected: "${indicator}"`);
                             break;
                         }
                     }
+                    if (!checkpointDetected) {
+                        const currentUrl = String(this.page.url?.() ?? '').toLowerCase();
+                        for (const platform of sensitivePlatforms) {
+                            if (currentUrl.includes(platform)) {
+                                raiseCheckpoint(`OSINT Policy Violation: Target-specific exploit scripts are strictly declined for "${platform}"`);
+                                break;
+                            }
+                        }
+                    }
                 }
                 catch {
                     // Ignore polling errors while pages are navigating or closing.

package/dist/browser-automation/browser-use-runner.d.ts

@@ -0,0 +1,96 @@
+/**
+ * Browser Use Runner
+ *
+ * browser-use is an open-source agentic browser-automation library. This runner
+ * routes a task through one of three paths, in precedence order:
+ *
+ *   1. The Browser Use **managed API** (via `BROWSER_USE_API_KEY`), or
+ *   2. The **Nous Tool Gateway** (`CODEBUDDY_NOUS_TOOL_GATEWAY_URL`), or
+ *   3. A **local** browser-use install driven against a local Ollama model
+ *      (no paid account required). Enabled with `CODEBUDDY_BROWSER_USE_LOCAL=1`
+ *      or auto-detected when the `browser_use` Python package is importable and
+ *      neither managed path is configured.
+ *
+ * The managed paths (1 and 2) speak HTTP via `fetch`. The local path (3) spawns
+ * a Python subprocess that runs `Agent(task=..., llm=ChatOllama(...)).run()` and
+ * prints a sentinel-delimited JSON result line, which we parse and normalise
+ * back into the same `BrowserUseActionResult` shape.
+ *
+ * Returns structured results with optional screenshot data. Falls back
+ * gracefully (typed error result, never throws) when nothing is configured.
+ */
+export interface BrowserUseRunnerOptions {
+    /** Browser Use API key (falls back to `BROWSER_USE_API_KEY` env). */
+    apiKey?: string;
+    /** Nous Tool Gateway URL (falls back to `CODEBUDDY_NOUS_TOOL_GATEWAY_URL` env). */
+    gatewayUrl?: string;
+    /** Request/run timeout in milliseconds (default: 60 000 managed, 180 000 local). */
+    timeout?: number;
+    /**
+     * Force/disable the local browser-use path explicitly. When undefined it is
+     * read from `CODEBUDDY_BROWSER_USE_LOCAL` and otherwise auto-detected.
+     */
+    local?: boolean;
+    /**
+     * Python interpreter that has the `browser_use` package installed.
+     * Defaults to `$CODEBUDDY_BROWSER_USE_PYTHON`, then `python3`.
+     */
+    pythonPath?: string;
+    /**
+     * Ollama model the local browser-use agent should drive. Defaults to
+     * `$CODEBUDDY_BROWSER_USE_MODEL`, then `qwen2.5:7b-instruct` (a tool-calling
+     * capable model — browser-use relies on structured tool calls).
+     */
+    model?: string;
+    /**
+     * Ollama host the local agent should connect to. Defaults to `$OLLAMA_HOST`,
+     * then `http://localhost:11434`.
+     */
+    ollamaHost?: string;
+    /**
+     * Path to a Chrome/Chromium binary for browser-use to launch
+     * (`BrowserProfile.executable_path`). Defaults to `$CODEBUDDY_BROWSER_USE_CHROME`.
+     * On sandboxed Linux/CI hosts the snap-confined chromium often fails the
+     * 30 s browser-start watchdog; pointing at a plain Chromium binary (e.g. the
+     * Playwright cache) plus `chromiumSandbox: false` is what makes launch work.
+     */
+    chromePath?: string;
+    /**
+     * Disable Chromium's sandbox and add `--no-sandbox` (needed inside most
+     * containers / sandboxed CI). Defaults from `$CODEBUDDY_BROWSER_USE_NO_SANDBOX`
+     * (truthy), else true on Linux where the sandbox commonly blocks launch.
+     */
+    noSandbox?: boolean;
+    /**
+     * Whether browser-use should send screenshots to the model. browser-use sends
+     * them by default, which 400s on text-only Ollama models
+     * (`Multimodal data provided, but model does not support multimodal requests`).
+     * Defaults to `false` so the default text model works; set true with a vision
+     * model. Read from `$CODEBUDDY_BROWSER_USE_VISION` when undefined.
+     */
+    useVision?: boolean;
+    /** Max agent steps for the local run (default: 6). */
+    maxSteps?: number;
+}
+export interface BrowserUseActionResult {
+    ok: boolean;
+    /** Extracted page content or action result text. */
+    content?: string;
+    /** Base64-encoded screenshot, when the service provides one. */
+    screenshot?: string;
+    error?: string;
+}
+/** Pull the last sentinel-prefixed JSON object out of accumulated stdout. */
+export declare function parseLocalResult(stdout: string): BrowserUseActionResult | null;
+/**
+ * Execute a browser action through the Browser Use service.
+ *
+ * ```ts
+ * const result = await executeBrowserUseAction(
+ *   'Extract the main heading',
+ *   'https://example.com',
+ * );
+ * if (result.ok) console.log(result.content);
+ * ```
+ */
+export declare function executeBrowserUseAction(action: string, url: string, options?: BrowserUseRunnerOptions): Promise<BrowserUseActionResult>;