@phuetz/code-buddy 1.6.1 → 2.1.0

package/dist/tools/registry/types.d.ts

@@ -76,6 +76,11 @@ export interface IToolMetadata {
     modifiesFiles?: boolean;
     /** Whether tool makes network requests */
     makesNetworkRequests?: boolean;
+    /**
+     * Declared side-effect class (`read` / `reversible` / `emission`).
+     * Kept in lockstep with `ToolMetadata.effect`.
+     */
+    effect?: 'read' | 'reversible' | 'emission';
     /**
      * Whether this tool is safe to expose to remote peers via A2A / fleet.
      * Default `false` (opt-in). See `src/tools/types.ts:ToolMetadata.fleetSafe`

package/dist/tools/registry/verify-tools.d.ts

@@ -0,0 +1,50 @@
+/**
+ * Verify Tool Adapter
+ *
+ * ITool-compliant adapter that makes the independent Verifier agent REACHABLE
+ * at runtime as an LLM tool. The agent calls `verify` to explicitly delegate a
+ * "does this actually work?" check to a fresh-context verifier (Manus doctrine:
+ * "delegate to the verifier"), which reproduces the work, runs real oracles and
+ * hands back a CONFIRMED / NEEDS REVIEW verdict with evidence.
+ *
+ * The Verifier is an LLM+tools agent: it needs an `llmCall` (to reason) and an
+ * `executeTool` (to drive read/execute-only tools). Those are supplied once at
+ * boot by the host CodeBuddyAgent via `setVerifyToolProvider()` — the agent
+ * already owns both a `CodeBuddyClient` and a tool executor, so this reuses the
+ * same plumbing the SWE/multi-agent bridges use. When no provider is wired the
+ * tool fails closed with a clear configuration error (never a silent no-op).
+ */
+import type { ToolResult } from '../../types/index.js';
+import type { ITool, ToolSchema, IToolMetadata, IValidationResult } from './types.js';
+import type { SWEMessage, SWETool, SWELLMResponse, SWEToolResult } from '../../agent/specialized/swe-agent.js';
+/** LLM bridge the Verifier reasons through (same shape as the SWE agent). */
+export type VerifyLlmCall = (messages: SWEMessage[], tools: SWETool[]) => Promise<SWELLMResponse>;
+/** Tool executor the Verifier drives (gated read/execute-only inside the agent). */
+export type VerifyExecuteTool = (name: string, args: Record<string, unknown>) => Promise<SWEToolResult>;
+/**
+ * The callable bridge the host injects so the `verify` tool can run the
+ * Verifier agent. Kept behind a provider (not imported statically) so the tool
+ * module has no dependency on a live LLM client — the agent owns that.
+ */
+export interface VerifyToolProvider {
+    llmCall: VerifyLlmCall;
+    executeTool: VerifyExecuteTool;
+}
+/**
+ * Wire the llmCall + executeTool bridge for the `verify` tool. Called once from
+ * codebuddy-agent.ts with the agent's own client + tool executor.
+ */
+export declare function setVerifyToolProvider(provider: () => VerifyToolProvider): void;
+/** Reset the provider (for testing). */
+export declare function resetVerifyToolProvider(): void;
+export declare class VerifyTool implements ITool {
+    readonly name = "verify";
+    readonly description = "Delegate to an independent, fresh-context Verifier that runs real oracles and returns a CONFIRMED / NEEDS REVIEW verdict with evidence. Read-only \u2014 it never edits files.";
+    execute(input: Record<string, unknown>): Promise<ToolResult>;
+    getSchema(): ToolSchema;
+    validate(input: unknown): IValidationResult;
+    getMetadata(): IToolMetadata;
+    isAvailable(): boolean;
+}
+export declare function createVerifyTools(): ITool[];
+export declare function resetVerifyInstances(): void;

package/dist/tools/registry/verify-tools.js

@@ -0,0 +1,136 @@
+/**
+ * Verify Tool Adapter
+ *
+ * ITool-compliant adapter that makes the independent Verifier agent REACHABLE
+ * at runtime as an LLM tool. The agent calls `verify` to explicitly delegate a
+ * "does this actually work?" check to a fresh-context verifier (Manus doctrine:
+ * "delegate to the verifier"), which reproduces the work, runs real oracles and
+ * hands back a CONFIRMED / NEEDS REVIEW verdict with evidence.
+ *
+ * The Verifier is an LLM+tools agent: it needs an `llmCall` (to reason) and an
+ * `executeTool` (to drive read/execute-only tools). Those are supplied once at
+ * boot by the host CodeBuddyAgent via `setVerifyToolProvider()` — the agent
+ * already owns both a `CodeBuddyClient` and a tool executor, so this reuses the
+ * same plumbing the SWE/multi-agent bridges use. When no provider is wired the
+ * tool fails closed with a clear configuration error (never a silent no-op).
+ */
+let _verifyProvider = null;
+/**
+ * Wire the llmCall + executeTool bridge for the `verify` tool. Called once from
+ * codebuddy-agent.ts with the agent's own client + tool executor.
+ */
+export function setVerifyToolProvider(provider) {
+    _verifyProvider = provider;
+}
+/** Reset the provider (for testing). */
+export function resetVerifyToolProvider() {
+    _verifyProvider = null;
+}
+export class VerifyTool {
+    name = 'verify';
+    description = 'Delegate to an independent, fresh-context Verifier that runs real oracles and returns a CONFIRMED / NEEDS REVIEW verdict with evidence. Read-only — it never edits files.';
+    async execute(input) {
+        const instruction = typeof input.instruction === 'string' && input.instruction.trim()
+            ? input.instruction.trim()
+            : typeof input._input === 'string'
+                ? input._input
+                : '';
+        if (!instruction) {
+            return { success: false, error: 'verify requires an `instruction` describing what to verify.' };
+        }
+        if (!_verifyProvider) {
+            // Fail closed: the tool is registered but the host never wired the LLM
+            // bridge, so it cannot run the Verifier. Surface a clear config error.
+            return {
+                success: false,
+                error: 'verify is not wired to an LLM bridge (setVerifyToolProvider was never called). This is a configuration error.',
+            };
+        }
+        const url = typeof input.url === 'string' && input.url.trim() ? input.url.trim() : undefined;
+        try {
+            const { llmCall, executeTool } = _verifyProvider();
+            // Route through the AgentRegistry so the Verifier's own toolset gate
+            // (read/execute only, writes refused fail-closed) and doctrine prompt
+            // apply. This is the runtime call-site that makes the Verifier reachable.
+            const { AgentRegistry } = await import('../../agent/specialized/agent-registry.js');
+            const registry = new AgentRegistry();
+            await registry.registerBuiltInAgents();
+            const result = await registry.executeOn('verifier', {
+                action: 'verify',
+                params: {
+                    llmCall,
+                    executeTool,
+                    instruction,
+                    ...(url ? { url } : {}),
+                },
+            });
+            if (!result.success) {
+                return { success: false, error: result.error || 'Verifier failed to produce a verdict.' };
+            }
+            const verdict = result.metadata?.verdict;
+            const header = verdict ? `[Verifier verdict: ${verdict}]\n` : '';
+            return { success: true, output: `${header}${result.output ?? ''}`.trim() };
+        }
+        catch (error) {
+            return {
+                success: false,
+                error: `verify failed: ${error instanceof Error ? error.message : String(error)}`,
+            };
+        }
+    }
+    getSchema() {
+        return {
+            name: this.name,
+            description: this.description,
+            parameters: {
+                type: 'object',
+                properties: {
+                    instruction: {
+                        type: 'string',
+                        description: 'What to verify — the change/flow and the claim to prove.',
+                    },
+                    url: {
+                        type: 'string',
+                        description: 'Optional URL to drive when verifying a running web UI.',
+                    },
+                },
+                required: ['instruction'],
+            },
+        };
+    }
+    validate(input) {
+        if (typeof input !== 'object' || input === null) {
+            return { valid: false, errors: ['Input must be an object'] };
+        }
+        const data = input;
+        if (typeof data.instruction !== 'string' || !data.instruction.trim()) {
+            // Pipeline callers may pass _input instead; allow that through validate.
+            if (typeof data._input !== 'string' || !data._input.trim()) {
+                return { valid: false, errors: ['instruction must be a non-empty string'] };
+            }
+        }
+        return { valid: true };
+    }
+    getMetadata() {
+        return {
+            name: this.name,
+            description: this.description,
+            category: 'utility',
+            keywords: ['verify', 'verification', 'evidence', 'confirm', 'validate', 'oracle', 'independent', 'test', 'proof'],
+            priority: 6,
+            requiresConfirmation: true,
+            modifiesFiles: false,
+            makesNetworkRequests: true,
+        };
+    }
+    isAvailable() {
+        return true;
+    }
+}
+export function createVerifyTools() {
+    return [new VerifyTool()];
+}
+export function resetVerifyInstances() {
+    // Stateless tool — nothing instance-level to reset (provider reset is separate).
+}
+//# sourceMappingURL=verify-tools.js.map

package/dist/tools/registry/video-studio-tools.d.ts

@@ -0,0 +1,13 @@
+/**
+ * Video-studio ITool adapters wrapping the PR #111 modules
+ * (hybrid router, visual/YouTube gates, long-form + trailer plans, Google Flow handoff).
+ * Dispatch surface: included from createMultimodalTools().
+ */
+import type { ITool } from './types.js';
+import { VideoFlowHandoffTool } from '../video-flow-handoff-tool.js';
+import { VideoLongFormPlanTool } from '../video-long-form-plan-tool.js';
+import { VideoQualityGateTool } from '../video-quality-gate-tool.js';
+import { VideoRouteTool } from '../video-route-tool.js';
+import { VideoTrailerPlanTool } from '../video-trailer-plan-tool.js';
+export { VideoFlowHandoffTool, VideoLongFormPlanTool, VideoQualityGateTool, VideoRouteTool, VideoTrailerPlanTool, };
+export declare function createVideoStudioTools(): ITool[];

package/dist/tools/registry/video-studio-tools.js

@@ -0,0 +1,21 @@
+/**
+ * Video-studio ITool adapters wrapping the PR #111 modules
+ * (hybrid router, visual/YouTube gates, long-form + trailer plans, Google Flow handoff).
+ * Dispatch surface: included from createMultimodalTools().
+ */
+import { VideoFlowHandoffTool } from '../video-flow-handoff-tool.js';
+import { VideoLongFormPlanTool } from '../video-long-form-plan-tool.js';
+import { VideoQualityGateTool } from '../video-quality-gate-tool.js';
+import { VideoRouteTool } from '../video-route-tool.js';
+import { VideoTrailerPlanTool } from '../video-trailer-plan-tool.js';
+export { VideoFlowHandoffTool, VideoLongFormPlanTool, VideoQualityGateTool, VideoRouteTool, VideoTrailerPlanTool, };
+export function createVideoStudioTools() {
+    return [
+        new VideoQualityGateTool(),
+        new VideoLongFormPlanTool(),
+        new VideoTrailerPlanTool(),
+        new VideoFlowHandoffTool(),
+        new VideoRouteTool(),
+    ];
+}
+//# sourceMappingURL=video-studio-tools.js.map

package/dist/tools/registry/vision-tools.d.ts

@@ -6,6 +6,7 @@
 import type { ToolResult } from '../../types/index.js';
 import type { ITool, ToolSchema, IToolMetadata, IValidationResult, IToolExecutionContext } from './types.js';
 import { type VisionAnalysisOptions } from '../vision/vision-analysis.js';
+import { type ObjectDetectionRuntime } from '../vision/object-detection.js';
 import { captureCameraSnapshot } from '../../companion/camera.js';
 export declare class VisionAnalyzeTool implements ITool {
     private readonly options;
@@ -50,6 +51,18 @@ export declare class ImageAnalyzeTool implements ITool {
     getMetadata(): IToolMetadata;
     isAvailable(): boolean;
 }
+export declare class ObjectDetectTool implements ITool {
+    private readonly options;
+    private readonly runtime;
+    readonly name = "object_detect";
+    readonly description = "Detect objects in a local image using a local YOLOv8/Ultralytics Python runtime.";
+    constructor(options?: VisionAnalysisOptions, runtime?: ObjectDetectionRuntime);
+    execute(input: Record<string, unknown>, context?: IToolExecutionContext): Promise<ToolResult>;
+    getSchema(): ToolSchema;
+    validate(input: unknown): IValidationResult;
+    getMetadata(): IToolMetadata;
+    isAvailable(): boolean;
+}
 export declare class CameraSnapshotTool implements ITool {
     readonly name = "camera_snapshot";
     readonly description = "Capture one local webcam frame to an image file for Buddy companion vision. Requires ffmpeg and OS camera permission.";
@@ -67,11 +80,12 @@ export interface CameraAnalyzeRuntime {
     /** Injected for tests; defaults to process.env. */
     env?: NodeJS.ProcessEnv;
 }
+export declare function resolveCameraVisionModel(requested: string | undefined, env?: NodeJS.ProcessEnv): string;
 export declare class CameraAnalyzeTool implements ITool {
     private readonly options;
     private readonly runtime;
     readonly name = "camera_analyze";
-    readonly description = "Capture one local webcam frame and return a natural-language description from a local multimodal vision model (default Ollama gemma4:12b). Requires ffmpeg, OS camera permission, and a reachable local vision model.";
+    readonly description = "Describe a still image with a local multimodal vision model (default Ollama moondream, or CODEBUDDY_VISION_MODEL). Pass image_path to analyze an existing file without touching the webcam. Omitting image_path captures one local webcam frame (ffmpeg). Dark frames (mean luma < 12) are refused \u2014 the SENSE1 darkness door.";
     constructor(options?: VisionAnalysisOptions, runtime?: CameraAnalyzeRuntime);
     execute(input: Record<string, unknown>, context?: IToolExecutionContext): Promise<ToolResult>;
     private describeImage;

package/dist/tools/registry/vision-tools.js

@@ -8,8 +8,10 @@ import path from 'path';
 import { OcrTool } from '../vision/ocr-tool.js';
 import { ImageProcessorTool } from '../vision/image-processor.js';
 import { analyzeVisionImage, } from '../vision/vision-analysis.js';
+import { detectObjectsInImage, } from '../vision/object-detection.js';
 import { captureCameraSnapshot } from '../../companion/camera.js';
 import { BrowserExecuteTool } from './misc-tools.js';
+import { DARK_SCENE_LUMA_THRESHOLD, meanLumaOfImage, } from '../vision/mean-luma.js';
 // ============================================================================
 // VisionAnalyzeTool (Hermes vision_analyze parity)
 // ============================================================================
@@ -381,6 +383,155 @@ export class ImageAnalyzeTool {
     isAvailable() { return true; }
 }
 // ============================================================================
+// ObjectDetectTool
+// ============================================================================
+export class ObjectDetectTool {
+    options;
+    runtime;
+    name = 'object_detect';
+    description = 'Detect objects in a local image using a local YOLOv8/Ultralytics Python runtime.';
+    constructor(options = {}, runtime = {}) {
+        this.options = options;
+        this.runtime = runtime;
+    }
+    async execute(input, context) {
+        try {
+            const result = await detectObjectsInImage({
+                imagePath: requiredString(input, 'image_path'),
+                modelPath: optionalString(input, 'model_path'),
+                pythonPath: optionalString(input, 'python_path'),
+                minConfidence: optionalNumber(input, 'min_confidence'),
+                iouThreshold: optionalNumber(input, 'iou_threshold'),
+                classes: optionalStringArray(input, 'classes'),
+                device: optionalString(input, 'device'),
+                maxDetections: optionalNumber(input, 'max_detections'),
+                saveAnnotated: input.save_annotated === true,
+                annotatedOutputPath: optionalString(input, 'annotated_output_path'),
+                timeoutMs: optionalNumber(input, 'timeout_ms'),
+            }, {
+                rootDir: this.options.rootDir ?? context?.cwd,
+                now: this.options.now,
+                createId: this.options.createId,
+            }, this.runtime);
+            return {
+                success: true,
+                output: JSON.stringify(result, null, 2),
+                data: result,
+            };
+        }
+        catch (error) {
+            return {
+                success: false,
+                error: error instanceof Error ? error.message : String(error),
+            };
+        }
+    }
+    getSchema() {
+        return {
+            name: this.name,
+            description: this.description,
+            parameters: {
+                type: 'object',
+                properties: {
+                    image_path: {
+                        type: 'string',
+                        description: 'Absolute or workspace-relative path to the image file. For webcam use, call camera_snapshot first and pass the captured path here.',
+                    },
+                    model_path: {
+                        type: 'string',
+                        description: 'Optional YOLO model path. Defaults to CODEBUDDY_YOLO_MODEL, ~/vision_tests/yolov8n.onnx, ~/vision_tests/yolov8n.pt, or yolov8n.pt.',
+                    },
+                    python_path: {
+                        type: 'string',
+                        description: 'Optional Python executable with ultralytics installed. Defaults to CODEBUDDY_YOLO_PYTHON, ~/vision_tests/venv/bin/python, or python3.',
+                    },
+                    min_confidence: {
+                        type: 'number',
+                        description: 'Minimum detection confidence from 0 to 1. Default 0.25.',
+                        minimum: 0,
+                        maximum: 1,
+                    },
+                    iou_threshold: {
+                        type: 'number',
+                        description: 'YOLO IoU threshold from 0 to 1. Default 0.7.',
+                        minimum: 0,
+                        maximum: 1,
+                    },
+                    classes: {
+                        type: 'array',
+                        items: { type: 'string' },
+                        description: 'Optional class names or numeric class IDs to keep, e.g. ["person"] or ["0"].',
+                    },
+                    device: {
+                        type: 'string',
+                        description: 'Optional Ultralytics device, e.g. cpu, cuda:0, mps, or a ROCm-supported device string.',
+                    },
+                    max_detections: {
+                        type: 'number',
+                        description: 'Maximum detections to return. Default 100.',
+                        minimum: 1,
+                        maximum: 1000,
+                    },
+                    save_annotated: {
+                        type: 'boolean',
+                        description: 'Also save an annotated image with boxes. Default false.',
+                    },
+                    annotated_output_path: {
+                        type: 'string',
+                        description: 'Optional output path for the annotated image when save_annotated is true.',
+                    },
+                    timeout_ms: {
+                        type: 'number',
+                        description: 'YOLO runtime timeout in milliseconds. Default 120000.',
+                        minimum: 1000,
+                        maximum: 600000,
+                    },
+                },
+                required: ['image_path'],
+            },
+        };
+    }
+    validate(input) {
+        if (typeof input !== 'object' || input === null) {
+            return { valid: false, errors: ['Input must be an object'] };
+        }
+        const data = input;
+        if (typeof data.image_path !== 'string' || data.image_path.trim() === '') {
+            return { valid: false, errors: ['image_path is required'] };
+        }
+        for (const key of ['model_path', 'python_path', 'device', 'annotated_output_path']) {
+            if (data[key] !== undefined && typeof data[key] !== 'string') {
+                return { valid: false, errors: [`${key} must be a string`] };
+            }
+        }
+        for (const key of ['min_confidence', 'iou_threshold', 'max_detections', 'timeout_ms']) {
+            if (data[key] !== undefined && typeof data[key] !== 'number') {
+                return { valid: false, errors: [`${key} must be a number`] };
+            }
+        }
+        if (data.classes !== undefined && (!Array.isArray(data.classes) ||
+            !data.classes.every(value => typeof value === 'string'))) {
+            return { valid: false, errors: ['classes must be an array of strings'] };
+        }
+        if (data.save_annotated !== undefined && typeof data.save_annotated !== 'boolean') {
+            return { valid: false, errors: ['save_annotated must be a boolean'] };
+        }
+        return { valid: true };
+    }
+    getMetadata() {
+        return {
+            name: this.name,
+            description: this.description,
+            category: 'media',
+            keywords: ['vision', 'image', 'object', 'detect', 'detection', 'yolo', 'yolov8', 'ultralytics', 'person'],
+            priority: 8,
+            modifiesFiles: true,
+            makesNetworkRequests: false,
+        };
+    }
+    isAvailable() { return true; }
+}
+// ============================================================================
 // CameraSnapshotTool
 // ============================================================================
 export class CameraSnapshotTool {
@@ -466,13 +617,41 @@ export class CameraSnapshotTool {
     }
     isAvailable() { return true; }
 }
-const DEFAULT_CAMERA_VISION_MODEL = 'gemma4:12b';
+const DEFAULT_CAMERA_VISION_MODEL = 'moondream';
 const CAMERA_VISION_TIMEOUT_MS = 180_000;
+export function resolveCameraVisionModel(requested, env = process.env) {
+    const fromInput = requested?.trim();
+    if (fromInput)
+        return fromInput;
+    const fromEnv = env.CODEBUDDY_VISION_MODEL?.trim();
+    if (fromEnv)
+        return fromEnv;
+    return DEFAULT_CAMERA_VISION_MODEL;
+}
+function mimeTypeForImage(filePath, bytes) {
+    if (bytes.length >= 3 && bytes[0] === 0xff && bytes[1] === 0xd8 && bytes[2] === 0xff) {
+        return 'image/jpeg';
+    }
+    if (bytes.length >= 8 && bytes.subarray(0, 8).equals(Buffer.from([0x89, 0x50, 0x4e, 0x47, 0x0d, 0x0a, 0x1a, 0x0a]))) {
+        return 'image/png';
+    }
+    if (bytes.length >= 12 && bytes.toString('ascii', 0, 4) === 'RIFF' && bytes.toString('ascii', 8, 12) === 'WEBP') {
+        return 'image/webp';
+    }
+    const ext = path.extname(filePath).toLowerCase();
+    if (ext === '.jpg' || ext === '.jpeg')
+        return 'image/jpeg';
+    if (ext === '.webp')
+        return 'image/webp';
+    if (ext === '.gif')
+        return 'image/gif';
+    return 'image/png';
+}
 export class CameraAnalyzeTool {
     options;
     runtime;
     name = 'camera_analyze';
-    description = 'Capture one local webcam frame and return a natural-language description from a local multimodal vision model (default Ollama gemma4:12b). Requires ffmpeg, OS camera permission, and a reachable local vision model.';
+    description = 'Describe a still image with a local multimodal vision model (default Ollama moondream, or CODEBUDDY_VISION_MODEL). Pass image_path to analyze an existing file without touching the webcam. Omitting image_path captures one local webcam frame (ffmpeg). Dark frames (mean luma < 12) are refused — the SENSE1 darkness door.';
     constructor(options = {}, runtime = {}) {
         this.options = options;
         this.runtime = runtime;
@@ -480,37 +659,64 @@ export class CameraAnalyzeTool {
     async execute(input, context) {
         const cwd = this.options.rootDir ?? context?.cwd;
         const prompt = optionalString(input, 'prompt') ?? 'Describe what you see.';
-        const model = optionalString(input, 'model') ?? DEFAULT_CAMERA_VISION_MODEL;
+        const model = resolveCameraVisionModel(optionalString(input, 'model'), this.runtime.env ?? process.env);
         const device = optionalString(input, 'device');
         const outputPath = optionalString(input, 'output_path');
         const includeOcr = input.include_ocr === true;
-        // (1) Capture a frame from the local webcam.
-        const captureSnapshot = this.runtime.captureSnapshot ?? captureCameraSnapshot;
-        const snapshot = await captureSnapshot({
-            cwd,
-            ...(outputPath ? { outputPath } : {}),
-            ...(device ? { device } : {}),
-            timeoutMs: typeof input.timeout_ms === 'number' ? input.timeout_ms : undefined,
-        });
-        if (!snapshot.success || !snapshot.path) {
-            return {
-                success: false,
-                error: snapshot.error || 'Camera snapshot failed before analysis',
-                output: snapshot.command,
-            };
+        const providedPath = optionalString(input, 'image_path');
+        let imagePath;
+        if (providedPath) {
+            imagePath = path.isAbsolute(providedPath)
+                ? path.resolve(providedPath)
+                : path.resolve(cwd ?? process.cwd(), providedPath);
+            try {
+                const stat = await fs.stat(imagePath);
+                if (!stat.isFile()) {
+                    return { success: false, error: `image_path is not a file: ${imagePath}` };
+                }
+            }
+            catch {
+                return { success: false, error: `image_path not found: ${imagePath}` };
+            }
+        }
+        else {
+            // Capture a frame from the local webcam only when no file was given.
+            const captureSnapshot = this.runtime.captureSnapshot ?? captureCameraSnapshot;
+            const snapshot = await captureSnapshot({
+                cwd,
+                ...(outputPath ? { outputPath } : {}),
+                ...(device ? { device } : {}),
+                timeoutMs: typeof input.timeout_ms === 'number' ? input.timeout_ms : undefined,
+            });
+            if (!snapshot.success || !snapshot.path) {
+                return {
+                    success: false,
+                    error: snapshot.error || 'Camera snapshot failed before analysis',
+                    output: snapshot.command,
+                };
+            }
+            imagePath = snapshot.path;
         }
-        // (2) base64 the captured PNG into a data URL.
-        let dataUrl;
+        let bytes;
         try {
-            const bytes = await fs.readFile(snapshot.path);
-            dataUrl = `data:image/png;base64,${bytes.toString('base64')}`;
+            bytes = await fs.readFile(imagePath);
         }
         catch (error) {
             return {
                 success: false,
-                error: `Failed to read captured frame ${snapshot.path}: ${error instanceof Error ? error.message : String(error)}`,
+                error: `Failed to read frame ${imagePath}: ${error instanceof Error ? error.message : String(error)}`,
             };
         }
+        const meanLuma = await meanLumaOfImage(imagePath);
+        if (meanLuma !== undefined && meanLuma < DARK_SCENE_LUMA_THRESHOLD) {
+            return {
+                success: false,
+                error: `Dark frame refused (meanLuma=${meanLuma} < ${DARK_SCENE_LUMA_THRESHOLD}). ` +
+                    'SENSE1 darkness door skips VLM analysis on near-black images.',
+                data: { imagePath, meanLuma, model },
+            };
+        }
+        const dataUrl = `data:${mimeTypeForImage(imagePath, bytes)};base64,${bytes.toString('base64')}`;
         // (3) Make a REAL vision completion against the local Ollama /v1 endpoint.
         let description;
         try {
@@ -520,14 +726,14 @@ export class CameraAnalyzeTool {
             return {
                 success: false,
                 error: error instanceof Error ? error.message : String(error),
-                output: `Captured frame saved to ${snapshot.path}, but the vision model could not describe it.`,
+                output: `Frame saved to ${imagePath}, but the vision model could not describe it.`,
             };
         }
         // (4) Optionally add local metadata/OCR evidence.
         let ocr;
         if (includeOcr) {
             try {
-                const analysis = await analyzeVisionImage(snapshot.path, {
+                const analysis = await analyzeVisionImage(imagePath, {
                     ...this.options,
                     rootDir: cwd,
                     includeOcr: true,
@@ -542,9 +748,10 @@ export class CameraAnalyzeTool {
         }
         // (5) Return the description text as the primary output.
         const data = {
-            imagePath: snapshot.path,
+            imagePath,
             description,
             model,
+            ...(meanLuma !== undefined ? { meanLuma } : {}),
             ...(ocr ? { ocr } : {}),
         };
         return {
@@ -622,17 +829,21 @@ export class CameraAnalyzeTool {
             parameters: {
                 type: 'object',
                 properties: {
+                    image_path: {
+                        type: 'string',
+                        description: 'Existing still image to describe (no webcam). JPEG/PNG/WebP. Use this for files; omit to capture the camera.',
+                    },
                     prompt: {
                         type: 'string',
                         description: 'What to ask the vision model about the frame. Default "Describe what you see."',
                     },
                     device: {
                         type: 'string',
-                        description: 'Optional ffmpeg camera device. Linux example: /dev/video0; Windows: video=Integrated Camera; macOS: 0.',
+                        description: 'Optional ffmpeg camera device. Linux example: /dev/video0; Windows: video=Integrated Camera; macOS: 0. Ignored when image_path is set.',
                     },
                     model: {
                         type: 'string',
-                        description: 'Local multimodal model id served by Ollama. Default gemma4:12b.',
+                        description: 'Local multimodal model id served by Ollama. Default moondream (or CODEBUDDY_VISION_MODEL). gemma* is text-only and will invent.',
                     },
                     include_ocr: {
                         type: 'boolean',
@@ -663,6 +874,9 @@ export class CameraAnalyzeTool {
         if (typeof input !== 'object')
             return { valid: false, errors: ['Input must be an object'] };
         const data = input;
+        if (data.image_path !== undefined && typeof data.image_path !== 'string') {
+            return { valid: false, errors: ['image_path must be a string'] };
+        }
         if (data.prompt !== undefined && typeof data.prompt !== 'string') {
             return { valid: false, errors: ['prompt must be a string'] };
         }
@@ -703,6 +917,7 @@ export function createVisionTools(options = {}) {
         new BrowserVisionTool(options),
         new OcrExtractTool(),
         new ImageAnalyzeTool(),
+        new ObjectDetectTool(options),
         new CameraSnapshotTool(),
         new CameraAnalyzeTool(options),
     ];
@@ -757,6 +972,16 @@ function optionalString(data, key) {
     const value = data[key];
     return typeof value === 'string' && value.trim() ? value.trim() : undefined;
 }
+function optionalNumber(data, key) {
+    const value = data[key];
+    return typeof value === 'number' ? value : undefined;
+}
+function optionalStringArray(data, key) {
+    const value = data[key];
+    if (!Array.isArray(value))
+        return undefined;
+    return value.filter((item) => typeof item === 'string');
+}
 function sanitizeFilename(id) {
     return id.trim().replace(/[^A-Za-z0-9_.-]+/g, '-').replace(/^-+|-+$/g, '') || String(Date.now());
 }