@geravant/sinain 1.7.2 → 1.9.0

package/onboard.js

@@ -0,0 +1,345 @@
+#!/usr/bin/env node
+/**
+ * sinain onboard — interactive setup wizard using @clack/prompts
+ * Modeled after `openclaw onboard` for a familiar, polished experience.
+ */
+import * as p from "@clack/prompts";
+import fs from "fs";
+import path from "path";
+import { execFileSync } from "child_process";
+import {
+  c, guard, maskKey, readEnv, writeEnv, summarizeConfig, runHealthCheck,
+  stepApiKey, stepTranscription, stepGateway, stepPrivacy, stepModel,
+  HOME, SINAIN_DIR, ENV_PATH, PKG_DIR, IS_WINDOWS, IS_MAC,
+} from "./config-shared.js";
+
+// ── Header ──────────────────────────────────────────────────────────────────
+
+function printHeader() {
+  console.log();
+  console.log(c.bold("  ┌─────────────────────────────────────────┐"));
+  console.log(c.bold("  │                                         │"));
+  console.log(c.bold("  │") + c.cyan("    ╔═╗╦╔╗╔╔═╗╦╔╗╔  ╦ ╦╦ ╦╔╦╗        ") + c.bold("│"));
+  console.log(c.bold("  │") + c.cyan("    ╚═╗║║║║╠═╣║║║║  ╠═╣║ ║ ║║        ") + c.bold("│"));
+  console.log(c.bold("  │") + c.cyan("    ╚═╝╩╝╚╝╩ ╩╩╝╚╝  ╩ ╩╚═╝═╩╝        ") + c.bold("│"));
+  console.log(c.bold("  │") + c.dim("      Privacy-first AI overlay          ") + c.bold("│"));
+  console.log(c.bold("  │                                         │"));
+  console.log(c.bold("  └─────────────────────────────────────────┘"));
+  console.log();
+}
+
+// ── Steps (imported from config-shared.js) ──────────────────────────────────
+// stepApiKey, stepTranscription, stepGateway, stepPrivacy, stepModel
+// are imported above and accept an optional label parameter.
+
+async function stepOverlay(existing) {
+  // Check if overlay is already installed
+  const overlayPaths = [
+    path.join(SINAIN_DIR, "overlay", "SinainHUD.app"),
+    path.join(SINAIN_DIR, "overlay", "sinain_hud.exe"),
+  ];
+  const overlayInstalled = overlayPaths.some((p) => fs.existsSync(p));
+
+  const choice = guard(await p.select({
+    message: "Install overlay",
+    options: [
+      {
+        value: "download",
+        label: "Download pre-built app (recommended)",
+        hint: "No Flutter SDK needed",
+      },
+      {
+        value: "source",
+        label: "Build from source",
+        hint: "Requires Flutter SDK",
+      },
+      {
+        value: "skip",
+        label: overlayInstalled ? "Skip (already installed)" : "Skip for now",
+        hint: overlayInstalled ? "SinainHUD.app detected" : "Install later: sinain setup-overlay",
+      },
+    ],
+    initialValue: overlayInstalled ? "skip" : "download",
+  }));
+
+  if (choice === "download" || choice === "source") {
+    const s = p.spinner();
+    const label = choice === "download" ? "Downloading overlay..." : "Building overlay from source...";
+    s.start(label);
+    try {
+      // setup-overlay.js handles both modes via process.argv
+      if (choice === "source") process.argv.push("--from-source");
+      await import("./setup-overlay.js");
+      s.stop(c.green("Overlay installed."));
+    } catch (err) {
+      s.stop(c.yellow(`Failed: ${err.message}`));
+      p.note("Install manually: sinain setup-overlay", "Overlay");
+    }
+  }
+}
+
+// ── Main ────────────────────────────────────────────────────────────────────
+
+export async function runOnboard(args = {}) {
+  printHeader();
+  p.intro("SinainHUD setup");
+
+  const existing = readEnv(ENV_PATH);
+  const hasExisting = Object.keys(existing).length > 0;
+
+  // ── Existing config handling ────────────────────────────────────────────
+
+  let configAction = "fresh";
+  if (hasExisting) {
+    p.note(summarizeConfig(existing).join("\n"), "Existing config detected");
+
+    configAction = guard(await p.select({
+      message: "Config handling",
+      options: [
+        { value: "keep", label: "Use existing values" },
+        { value: "update", label: "Update values" },
+        { value: "reset", label: "Reset (start fresh)" },
+      ],
+      initialValue: "keep",
+    }));
+
+    if (configAction === "keep") {
+      p.log.success("Using existing configuration.");
+      await stepOverlay(existing);
+      await runHealthCheck();
+      printOutro();
+      return;
+    }
+
+    if (configAction === "reset") {
+      fs.unlinkSync(ENV_PATH);
+      p.log.info("Config reset.");
+    }
+  }
+
+  const base = configAction === "update" ? existing : {};
+
+  // ── Flow selection ──────────────────────────────────────────────────────
+
+  const flow = args.flow || guard(await p.select({
+    message: "Setup mode",
+    options: [
+      {
+        value: "quickstart",
+        label: "QuickStart",
+        hint: "Get running in 2 minutes. Configure details later.",
+      },
+      {
+        value: "advanced",
+        label: "Advanced",
+        hint: "Full control over privacy, models, and connections.",
+      },
+    ],
+    initialValue: "quickstart",
+  }));
+
+  const totalSteps = flow === "quickstart" ? 2 : 5;
+
+  // ── Collect vars ────────────────────────────────────────────────────────
+
+  const vars = { ...base };
+
+  // Step 1: API key (both flows)
+  const apiKey = await stepApiKey(base, `[1/${totalSteps}] OpenRouter API key`);
+  vars.OPENROUTER_API_KEY = apiKey;
+  p.log.success("API key saved.");
+
+  if (flow === "quickstart") {
+    // QuickStart: sensible defaults
+    vars.TRANSCRIPTION_BACKEND = base.TRANSCRIPTION_BACKEND || "openrouter";
+    vars.PRIVACY_MODE = base.PRIVACY_MODE || "standard";
+    vars.AGENT_MODEL = base.AGENT_MODEL || "google/gemini-2.5-flash-lite";
+    vars.ESCALATION_MODE = base.ESCALATION_MODE || "off";
+    vars.SINAIN_AGENT = base.SINAIN_AGENT || "claude";
+    if (!vars.OPENCLAW_WS_URL) {
+      vars.OPENCLAW_WS_URL = "";
+      vars.OPENCLAW_HTTP_URL = "";
+    }
+
+    p.note(
+      [
+        `Transcription: ${vars.TRANSCRIPTION_BACKEND}`,
+        `Privacy: ${vars.PRIVACY_MODE}`,
+        `Model: ${vars.AGENT_MODEL}`,
+        `Escalation: ${vars.ESCALATION_MODE}`,
+        "",
+        `Change later: sinain config`,
+      ].join("\n"),
+      "QuickStart defaults",
+    );
+  } else {
+    // Advanced flow: steps 2-5
+    const transcription = await stepTranscription(base, "[2/5] Audio transcription");
+    vars.TRANSCRIPTION_BACKEND = transcription;
+    p.log.success(`Using ${transcription === "openrouter" ? "cloud" : "local"} transcription.`);
+
+    if (transcription === "local") {
+      const modelDir = path.join(HOME, "models");
+      const modelPath = path.join(modelDir, "ggml-large-v3-turbo.bin");
+      if (!fs.existsSync(modelPath)) {
+        const download = guard(await p.confirm({
+          message: "Download Whisper model (~1.5 GB)?",
+          initialValue: true,
+        }));
+        if (download) {
+          const s = p.spinner();
+          s.start("Downloading Whisper model...");
+          try {
+            fs.mkdirSync(modelDir, { recursive: true });
+            execFileSync("curl", [
+              "-L", "--progress-bar",
+              "-o", modelPath,
+              "https://huggingface.co/ggerganov/whisper.cpp/resolve/main/ggml-large-v3-turbo.bin",
+            ], { stdio: "inherit" });
+            s.stop(c.green("Model downloaded."));
+            vars.LOCAL_WHISPER_MODEL = modelPath;
+          } catch {
+            s.stop(c.yellow("Download failed. You can download manually later."));
+          }
+        }
+      } else {
+        vars.LOCAL_WHISPER_MODEL = modelPath;
+        p.log.info(`Whisper model found: ${c.dim(modelPath)}`);
+      }
+    }
+
+    const gatewayVars = await stepGateway(base, "[3/5] OpenClaw gateway");
+    Object.assign(vars, gatewayVars);
+    if (gatewayVars.ESCALATION_MODE === "off") {
+      p.log.info("Standalone mode (no gateway).");
+    } else {
+      p.log.success("Gateway configured.");
+    }
+
+    const privacy = await stepPrivacy(base, "[4/5] Privacy mode");
+    vars.PRIVACY_MODE = privacy;
+    p.log.success(`Privacy: ${privacy}.`);
+
+    const model = await stepModel(base, "[5/5] AI model for HUD analysis");
+    vars.AGENT_MODEL = model;
+    p.log.success(`Model: ${model}.`);
+
+    vars.SINAIN_AGENT = base.SINAIN_AGENT || "claude";
+  }
+
+  // ── Common defaults ───────────────────────────────────────────────────
+
+  vars.SINAIN_CORE_URL = vars.SINAIN_CORE_URL || "http://localhost:9500";
+  vars.SINAIN_POLL_INTERVAL = vars.SINAIN_POLL_INTERVAL || "5";
+  vars.SINAIN_HEARTBEAT_INTERVAL = vars.SINAIN_HEARTBEAT_INTERVAL || "900";
+  vars.AUDIO_CAPTURE_CMD = vars.AUDIO_CAPTURE_CMD || "screencapturekit";
+  vars.AUDIO_AUTO_START = vars.AUDIO_AUTO_START || "true";
+  vars.PORT = vars.PORT || "9500";
+
+  // ── Write config ──────────────────────────────────────────────────────
+
+  const s = p.spinner();
+  s.start("Writing configuration...");
+  writeEnv(vars);
+  s.stop(c.green(`Config saved: ${c.dim(ENV_PATH)}`));
+
+  // ── Overlay ───────────────────────────────────────────────────────────
+
+  await stepOverlay(base);
+
+  // ── Health check ──────────────────────────────────────────────────────
+
+  await runHealthCheck();
+
+  // ── What now ──────────────────────────────────────────────────────────
+
+  printOutro();
+
+  // ── Start? ────────────────────────────────────────────────────────────
+
+  const startNow = guard(await p.confirm({
+    message: "Start sinain now?",
+    initialValue: true,
+  }));
+
+  if (startNow) {
+    p.outro("Launching sinain...");
+    try {
+      await import("./launcher.js");
+    } catch (err) {
+      console.log(c.yellow(`  Launch failed: ${err.message}`));
+      console.log(c.dim("  Try manually: sinain start"));
+    }
+  } else {
+    p.outro("Run when ready: sinain start");
+  }
+}
+
+function printOutro() {
+  const hotkey = IS_WINDOWS ? "Ctrl+Shift" : "Cmd+Shift";
+  p.note(
+    [
+      "Hotkeys:",
+      `  ${hotkey}+Space — Show/hide overlay`,
+      `  ${hotkey}+E     — Cycle tabs (Stream → Agent → Tasks)`,
+      `  ${hotkey}+C     — Toggle click-through`,
+      `  ${hotkey}+M     — Cycle display mode`,
+      "",
+      "Docs: https://github.com/geravant/sinain-hud",
+      "Re-run: sinain onboard (or sinain onboard --advanced)",
+    ].join("\n"),
+    "What now",
+  );
+}
+
+// ── CLI entry point ─────────────────────────────────────────────────────────
+
+const cliArgs = process.argv.slice(2);
+const flags = {};
+for (const arg of cliArgs) {
+  if (arg === "--advanced") flags.flow = "advanced";
+  if (arg === "--quickstart") flags.flow = "quickstart";
+  if (arg.startsWith("--key=")) flags.key = arg.slice(6);
+  if (arg === "--non-interactive") flags.nonInteractive = true;
+  if (arg === "--reset") flags.reset = true;
+}
+
+if (flags.reset) {
+  if (fs.existsSync(ENV_PATH)) {
+    fs.unlinkSync(ENV_PATH);
+    console.log(c.green("  Config reset."));
+  }
+}
+
+if (flags.nonInteractive) {
+  const vars = {
+    OPENROUTER_API_KEY: flags.key || process.env.OPENROUTER_API_KEY || "",
+    TRANSCRIPTION_BACKEND: "openrouter",
+    PRIVACY_MODE: "standard",
+    AGENT_MODEL: "google/gemini-2.5-flash-lite",
+    ESCALATION_MODE: "off",
+    SINAIN_AGENT: "claude",
+    OPENCLAW_WS_URL: "",
+    OPENCLAW_HTTP_URL: "",
+    PORT: "9500",
+    AUDIO_CAPTURE_CMD: "screencapturekit",
+    AUDIO_AUTO_START: "true",
+    SINAIN_CORE_URL: "http://localhost:9500",
+    SINAIN_POLL_INTERVAL: "5",
+    SINAIN_HEARTBEAT_INTERVAL: "900",
+  };
+
+  if (!vars.OPENROUTER_API_KEY) {
+    console.error(c.red("  --key=<key> or OPENROUTER_API_KEY required for non-interactive mode."));
+    process.exit(1);
+  }
+
+  writeEnv(vars);
+  console.log(c.green(`  Config written to ${ENV_PATH}`));
+  process.exit(0);
+} else {
+  runOnboard(flags).catch((err) => {
+    console.error(c.red(`  Error: ${err.message}`));
+    process.exit(1);
+  });
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@geravant/sinain",
-  "version": "1.7.2",
+  "version": "1.9.0",
   "description": "Ambient intelligence that sees what you see, hears what you hear, and acts on your behalf",
   "type": "module",
   "bin": {
@@ -14,6 +14,9 @@
   },
   "files": [
     "cli.js",
+    "config.js",
+    "config-shared.js",
+    "onboard.js",
     "launcher.js",
     "setup-overlay.js",
     "setup-sck-capture.js",
@@ -47,5 +50,8 @@
       "./index.ts"
     ]
   },
-  "license": "MIT"
+  "license": "MIT",
+  "dependencies": {
+    "@clack/prompts": "^1.1.0"
+  }
 }

package/sense_client/__main__.py

@@ -371,13 +371,17 @@ def main():
                 try:
                     from PIL import Image as PILImage
                     pil = PILImage.fromarray(frame) if isinstance(frame, np.ndarray) else frame
-                    scene = vision_provider.describe(pil, prompt=prompt or None)
-                    if scene:
-                        log(f"vision: {scene[:80]}...")
+                    result = vision_provider.describe(pil, prompt=prompt or None)
+                    scene = result.text
+                    v_cost = result.cost
+                    if scene or v_cost:
+                        if scene:
+                            log(f"vision: {scene[:80]}...")
                         ctx_ev = SenseEvent(type="context", ts=ts)
-                        ctx_ev.observation = SenseObservation(scene=scene)
+                        ctx_ev.observation = SenseObservation(scene=scene or "")
                         ctx_ev.meta = meta
                         ctx_ev.roi = package_full_frame(frame)
+                        ctx_ev.vision_cost = v_cost
                         sender.send(ctx_ev)
                 except Exception as e:
                     log(f"vision error: {e}")

package/sense_client/gate.py

@@ -43,6 +43,7 @@ class SenseEvent:
     diff: dict | None = None
     meta: SenseMeta = field(default_factory=SenseMeta)
     observation: SenseObservation = field(default_factory=SenseObservation)
+    vision_cost: dict | None = None  # {cost, tokens_in, tokens_out, model}
 
 
 class DecisionGate:

package/sense_client/ocr.py

@@ -1,4 +1,5 @@
 """OCR backends for UI text extraction: macOS Vision, Windows.Media.Ocr, and Tesseract."""
+
 from __future__ import annotations
 
 import io
@@ -24,8 +25,13 @@ class OCRResult:
 class LocalOCR:
     """Tesseract OCR wrapper for UI text extraction."""
 
-    def __init__(self, lang: str = "eng", psm: int = 11,
-                 min_confidence: int = 30, enabled: bool = True):
+    def __init__(
+        self,
+        lang: str = "eng",
+        psm: int = 11,
+        min_confidence: int = 30,
+        enabled: bool = True,
+    ):
         self.lang = lang
         self.psm = psm
         self.min_confidence = min_confidence
@@ -87,8 +93,12 @@ class LocalOCR:
 class VisionOCR:
     """macOS Vision framework OCR using pyobjc."""
 
-    def __init__(self, languages: list[str] | None = None,
-                 min_confidence: float = 0.5, enabled: bool = True):
+    def __init__(
+        self,
+        languages: list[str] | None = None,
+        min_confidence: float = 0.5,
+        enabled: bool = True,
+    ):
         self.languages = languages or ["en", "ru"]
         self.min_confidence = min_confidence
         self.enabled = enabled
@@ -101,8 +111,12 @@ class VisionOCR:
             import objc  # noqa: F401
             import Quartz  # noqa: F401
             from Foundation import NSURL, NSData  # noqa: F401
-            objc.loadBundle('Vision', bundle_path='/System/Library/Frameworks/Vision.framework',
-                            module_globals=globals())
+
+            objc.loadBundle(
+                "Vision",
+                bundle_path="/System/Library/Frameworks/Vision.framework",
+                module_globals=globals(),
+            )
             self._available = True
         except Exception as e:
             print(f"[ocr] Vision framework unavailable: {e}", flush=True)
@@ -120,9 +134,8 @@ class VisionOCR:
 
     def _do_extract(self, image: Image.Image) -> OCRResult:
         import objc
-        import Vision
-        from Foundation import NSData
         import Quartz
+        from Foundation import NSData
 
         # Convert PIL Image to CGImage via PNG bytes
         buf = io.BytesIO()
@@ -138,13 +151,13 @@ class VisionOCR:
             return OCRResult(text="", confidence=0, word_count=0)
 
         # Create and configure request
-        request = Vision.VNRecognizeTextRequest.alloc().init()
-        request.setRecognitionLevel_(Vision.VNRequestTextRecognitionLevelAccurate)
+        request = VNRecognizeTextRequest.alloc().init()
+        request.setRecognitionLevel_(0)  # VNRequestTextRecognitionLevelAccurate
         request.setRecognitionLanguages_(self.languages)
         request.setUsesLanguageCorrection_(True)
 
         # Execute
-        handler = Vision.VNImageRequestHandler.alloc().initWithCGImage_options_(cg_image, None)
+        handler = VNImageRequestHandler.alloc().initWithCGImage_options_(cg_image, None)
         success = handler.performRequests_error_([request], objc.nil)
         if not success[0]:
             return OCRResult(text="", confidence=0, word_count=0)
@@ -197,8 +210,9 @@ class VisionOCR:
 class WinOCR:
     """Windows.Media.Ocr backend via winrt-python (Windows 10+)."""
 
-    def __init__(self, language: str = "en", min_confidence: float = 0.5,
-                 enabled: bool = True):
+    def __init__(
+        self, language: str = "en", min_confidence: float = 0.5, enabled: bool = True
+    ):
         self.language = language
         self.min_confidence = min_confidence
         self.enabled = enabled
@@ -209,8 +223,8 @@ class WinOCR:
             return
 
         try:
-            from winrt.windows.media.ocr import OcrEngine
             from winrt.windows.globalization import Language
+            from winrt.windows.media.ocr import OcrEngine
 
             lang = Language(language)
             if OcrEngine.is_language_supported(lang):
@@ -234,11 +248,15 @@ class WinOCR:
 
     def _do_extract(self, image: Image.Image) -> OCRResult:
         import asyncio
+
         from winrt.windows.graphics.imaging import (
-            SoftwareBitmap, BitmapPixelFormat, BitmapAlphaMode,
+            BitmapAlphaMode,
+            BitmapPixelFormat,
+            SoftwareBitmap,
         )
         from winrt.windows.storage.streams import (
-            InMemoryRandomAccessStream, DataWriter,
+            DataWriter,
+            InMemoryRandomAccessStream,
         )
 
         # Convert PIL to BMP bytes and load as SoftwareBitmap
@@ -254,13 +272,15 @@ class WinOCR:
             stream.seek(0)
 
             from winrt.windows.graphics.imaging import BitmapDecoder
+
             decoder = await BitmapDecoder.create_async(stream)
             bitmap = await decoder.get_software_bitmap_async()
 
             # Convert to supported pixel format if needed
             if bitmap.bitmap_pixel_format != BitmapPixelFormat.BGRA8:
-                bitmap = SoftwareBitmap.convert(bitmap, BitmapPixelFormat.BGRA8,
-                                                 BitmapAlphaMode.PREMULTIPLIED)
+                bitmap = SoftwareBitmap.convert(
+                    bitmap, BitmapPixelFormat.BGRA8, BitmapAlphaMode.PREMULTIPLIED
+                )
 
             result = await self._engine.recognize_async(bitmap)
             return result
@@ -318,10 +338,15 @@ def create_ocr(config: dict):
             enabled=enabled,
         )
         if vision._available:
-            print(f"[ocr] using Vision backend (languages={vision.languages})", flush=True)
+            print(
+                f"[ocr] using Vision backend (languages={vision.languages})", flush=True
+            )
             return vision
         if backend == "vision":
-            print("[ocr] Vision requested but unavailable, falling back to Tesseract", flush=True)
+            print(
+                "[ocr] Vision requested but unavailable, falling back to Tesseract",
+                flush=True,
+            )
 
     # Windows: try Windows.Media.Ocr
     if sys.platform == "win32" and backend in ("auto", "winocr"):
@@ -332,10 +357,15 @@ def create_ocr(config: dict):
             enabled=enabled,
         )
         if winocr._available:
-            print(f"[ocr] using WinOCR backend (language={winocr.language})", flush=True)
+            print(
+                f"[ocr] using WinOCR backend (language={winocr.language})", flush=True
+            )
             return winocr
         if backend == "winocr":
-            print("[ocr] WinOCR requested but unavailable, falling back to Tesseract", flush=True)
+            print(
+                "[ocr] WinOCR requested but unavailable, falling back to Tesseract",
+                flush=True,
+            )
 
     # Fallback to Tesseract (cross-platform)
     print("[ocr] using Tesseract backend", flush=True)

package/sense_client/sender.py

@@ -51,6 +51,8 @@ class SenseSender:
                 "narrative": event.observation.narrative,
                 "concepts": event.observation.concepts,
             }
+        if event.vision_cost:
+            payload["vision_cost"] = event.vision_cost
 
         for attempt in range(_MAX_RETRIES):
             try:

package/sense_client/vision.py

@@ -18,6 +18,7 @@ import json
 import logging
 import os
 import time
+import uuid
 from abc import ABC, abstractmethod
 from typing import TYPE_CHECKING, Optional
 
@@ -27,14 +28,23 @@ if TYPE_CHECKING:
 logger = logging.getLogger("sinain.vision")
 
 
+class VisionResult:
+    """Result of a vision call: text + optional cost info."""
+    __slots__ = ("text", "cost")
+
+    def __init__(self, text: Optional[str], cost: Optional[dict] = None):
+        self.text = text
+        self.cost = cost  # {cost, tokens_in, tokens_out, model, cost_id}
+
+
 class VisionProvider(ABC):
     """Abstract base for vision inference backends."""
 
     name: str = "unknown"
 
     @abstractmethod
-    def describe(self, image: "Image.Image", prompt: Optional[str] = None) -> Optional[str]:
-        """Describe image content. Returns None on failure."""
+    def describe(self, image: "Image.Image", prompt: Optional[str] = None) -> VisionResult:
+        """Describe image content. Returns VisionResult (text may be None on failure)."""
         ...
 
     @abstractmethod
@@ -53,8 +63,8 @@ class OllamaVisionProvider(VisionProvider):
                                      timeout=timeout, max_tokens=max_tokens)
         self.name = f"ollama ({model})"
 
-    def describe(self, image: "Image.Image", prompt: Optional[str] = None) -> Optional[str]:
-        return self._client.describe(image, prompt)
+    def describe(self, image: "Image.Image", prompt: Optional[str] = None) -> VisionResult:
+        return VisionResult(self._client.describe(image, prompt))
 
     def is_available(self) -> bool:
         return self._client.is_available()
@@ -73,9 +83,9 @@ class OpenRouterVisionProvider(VisionProvider):
         self._max_tokens = max_tokens
         self.name = f"openrouter ({model})"
 
-    def describe(self, image: "Image.Image", prompt: Optional[str] = None) -> Optional[str]:
+    def describe(self, image: "Image.Image", prompt: Optional[str] = None) -> VisionResult:
         if not self._api_key:
-            return None
+            return VisionResult(None)
 
         try:
             import requests
@@ -83,7 +93,7 @@ class OpenRouterVisionProvider(VisionProvider):
             # Encode image
             img_b64 = self._encode(image)
             if not img_b64:
-                return None
+                return VisionResult(None)
 
             prompt_text = prompt or "Describe what's on this screen concisely (2-3 sentences)."
 
@@ -112,13 +122,23 @@ class OpenRouterVisionProvider(VisionProvider):
             resp.raise_for_status()
             data = resp.json()
             content = data["choices"][0]["message"]["content"].strip()
-            logger.debug("openrouter vision: model=%s tokens=%s",
-                         self._model, data.get("usage", {}).get("total_tokens", "?"))
-            return content if content else None
+            usage = data.get("usage", {})
+            logger.debug("openrouter vision: model=%s tokens=%s cost=%s",
+                         self._model, usage.get("total_tokens", "?"), usage.get("cost", "?"))
+            cost_info = None
+            if usage.get("cost") is not None:
+                cost_info = {
+                    "cost": usage["cost"],
+                    "tokens_in": usage.get("prompt_tokens", 0),
+                    "tokens_out": usage.get("completion_tokens", 0),
+                    "model": self._model,
+                    "cost_id": uuid.uuid4().hex[:16],
+                }
+            return VisionResult(content if content else None, cost_info)
 
         except Exception as e:
             logger.debug("openrouter vision failed: %s", e)
-            return None
+            return VisionResult(None)
 
     def is_available(self) -> bool:
         return bool(self._api_key)