onbuzz 5.1.0 → 5.3.0

package/src/services/attachments/attachmentStrategy.js

@@ -0,0 +1,87 @@
+/**
+ * Attachment strategy — pure decision logic for HOW a chat attachment is
+ * materialized into the model context. No I/O.
+ *
+ * Strategies:
+ *   - 'inline-text'     : small text → inject full content into the system prompt
+ *                         every turn (compaction-safe, full fidelity).
+ *   - 'document-recall' : large text / extracted-PDF text → store + semantic
+ *                         recall only relevant chunks (RAG) at turn time.
+ *   - 'vision-native'   : image/PDF AND the active chat model can see images →
+ *                         send a native image/document content block.
+ *   - 'vision-analyze'  : image AND the chat model is NOT vision-capable but a
+ *                         separate vision model exists → analyze via the vision
+ *                         tool/endpoint and inject the resulting text.
+ *   - 'reference'       : nothing better applies (binary/unknown, oversize, or
+ *                         no vision model at all) → a lightweight pointer the
+ *                         agent can act on via tools.
+ *
+ * Inputs come from the validator (contentType), the stored bytes (byteSize),
+ * the processor (tokenEstimate of the text representation, when known), and the
+ * catalog (whether the active chat model is vision-capable, and whether ANY
+ * vision model is available).
+ */
+
+export const DEFAULT_THRESHOLDS = {
+  // Text at/under this many estimated tokens is injected in full; above → RAG.
+  inlineTextMaxTokens: 3000,
+  // Fallback byte ceiling for inline text when no token estimate is available
+  // (~4 chars/token → 3000 tokens ≈ 12KB; use a generous safety net).
+  inlineTextMaxBytes: 24 * 1024,
+  // Images larger than this aren't sent/analyzed inline (kept as a reference).
+  visionMaxBytes: 20 * 1024 * 1024,
+};
+
+/**
+ * @param {Object} input
+ * @param {'text'|'image'|'pdf'|'binary'} input.contentType
+ * @param {number} [input.byteSize]
+ * @param {number|null} [input.tokenEstimate]   estimated tokens of the text repr
+ * @param {boolean} [input.modelVisionCapable]  active chat model can see images
+ * @param {boolean} [input.hasVisionModel]      any vision-capable model exists
+ * @param {Object} [cfg] threshold overrides
+ * @returns {{ strategy: string, reason: string }}
+ */
+export function classifyAttachment(input = {}, cfg = {}) {
+  const {
+    contentType,
+    byteSize = 0,
+    tokenEstimate = null,
+    modelVisionCapable = false,
+    hasVisionModel = false,
+  } = input;
+  const t = { ...DEFAULT_THRESHOLDS, ...cfg };
+
+  if (contentType === 'text') {
+    const overByTokens = tokenEstimate != null && tokenEstimate > t.inlineTextMaxTokens;
+    const overByBytes = tokenEstimate == null && byteSize > t.inlineTextMaxBytes;
+    return overByTokens || overByBytes
+      ? { strategy: 'document-recall', reason: 'large text → semantic recall (RAG)' }
+      : { strategy: 'inline-text', reason: 'small text → full inline injection' };
+  }
+
+  if (contentType === 'image') {
+    if (byteSize > t.visionMaxBytes) {
+      return { strategy: 'reference', reason: 'image exceeds vision size limit' };
+    }
+    if (modelVisionCapable) {
+      return { strategy: 'vision-native', reason: 'chat model is vision-capable' };
+    }
+    if (hasVisionModel) {
+      return { strategy: 'vision-analyze', reason: 'analyze via a separate vision model' };
+    }
+    return { strategy: 'reference', reason: 'no vision-capable model available' };
+  }
+
+  if (contentType === 'pdf') {
+    if (modelVisionCapable && byteSize <= t.visionMaxBytes) {
+      return { strategy: 'vision-native', reason: 'native PDF to a vision-capable model' };
+    }
+    return { strategy: 'document-recall', reason: 'PDF extracted text → semantic recall' };
+  }
+
+  // binary / unknown
+  return { strategy: 'reference', reason: 'binary/unknown type — reference only' };
+}
+
+export default classifyAttachment;

package/src/services/fileAttachmentService.js

@@ -86,7 +86,7 @@ class FileAttachmentService {
    * @param {string} options.fileName - Optional custom file name
    * @returns {Promise<Object>} Attachment metadata
    */
-  async uploadFile({ agentId, filePath, mode = 'content', fileName = null }) {
+  async uploadFile({ agentId, filePath, mode = 'content', fileName = null, scope = 'agent', conversationId = null }) {
     if (!this.index) {
       await this.loadIndex();
     }
@@ -157,6 +157,10 @@ class FileAttachmentService {
       const metadata = {
         fileId,
         agentId,
+        // Scope: 'agent' (default, persistent) or 'conversation' (only applies
+        // to the conversation it was attached in — see attachmentScope.js).
+        scope: scope === 'conversation' ? 'conversation' : 'agent',
+        conversationId: scope === 'conversation' ? (conversationId || null) : null,
         fileName: actualFileName,
         originalPath: filePath,
         fileType: this.validator.getMimeType(actualFileName),
@@ -347,8 +351,9 @@ class FileAttachmentService {
         throw new Error(`Attachment not found: ${fileId}`);
       }
 
-      // Allow only safe updates
-      const allowedFields = ['fileName', 'active'];
+      // Allow only safe updates. docId/indexed link a large-text attachment to
+      // its DocumentStore copy so the context builder can semantically recall it.
+      const allowedFields = ['fileName', 'active', 'docId', 'indexed'];
       for (const field of allowedFields) {
         if (updates[field] !== undefined) {
           metadata[field] = updates[field];

package/src/services/scheduleService.js

@@ -93,6 +93,87 @@ function getNextCronDate(parsed, after = new Date()) {
   return null;
 }
 
+/**
+ * Decide what to do with a schedule whose next run may be due/past-due — the
+ * core of missed-run handling. Pure + exported for testing.
+ *
+ *   due         — the scheduled time has arrived or passed.
+ *   missed      — it's late by more than `missThresholdMs`, i.e. the app was
+ *                 almost certainly OFF when it should have fired (a normal tick
+ *                 is at most one interval late).
+ *   withinGrace — the miss is recent enough (<= catchUpGraceMs) to be worth
+ *                 catching up; a months-old miss is recorded but not run.
+ *   shouldFire  — execute now: on-time, or missed-but-recent.
+ *
+ * @param {{nextRun: string|null, now: Date, missThresholdMs: number, catchUpGraceMs: number}} args
+ */
+export function evaluateScheduleRun({ nextRun, now, missThresholdMs, catchUpGraceMs }) {
+  if (!nextRun) return { due: false, missed: false, withinGrace: false, shouldFire: false, lateMs: 0 };
+  const lateMs = now.getTime() - new Date(nextRun).getTime();
+  const due = lateMs >= 0;
+  const missed = due && lateMs > missThresholdMs;
+  const withinGrace = lateMs <= catchUpGraceMs;
+  const shouldFire = due && (!missed || withinGrace);
+  return { due, missed, withinGrace, shouldFire, lateMs };
+}
+
+/**
+ * Build the command the OS scheduler (crontab/schtasks) runs to fire a
+ * schedule while the app is closed. Pure + exported for testing.
+ *
+ * In a packaged Electron desktop app there is no `loxia` CLI on PATH (and
+ * possibly no `node`), so a bare `loxia trigger-schedule` entry would silently
+ * fail — that's why "run when off" didn't work for desktop installs. When
+ * running under Electron we register the APP EXECUTABLE itself with a
+ * `--trigger-schedule=<id>` flag; electron/main.js detects that flag on launch,
+ * fires the schedule, and lets the idle-shutdown close it.
+ *
+ * @param {{scheduleId: string, isElectron: boolean, execPath?: string, loxiaBin: string}} args
+ */
+export function resolveTriggerCommand({ scheduleId, isElectron, execPath, loxiaBin }) {
+  if (isElectron && execPath) {
+    return `"${execPath}" --trigger-schedule=${scheduleId}`;
+  }
+  return `${loxiaBin} trigger-schedule ${scheduleId}`;
+}
+
+/**
+ * Extract the schedule id from an Electron launch argv. The OS scheduler runs
+ * the app with `--trigger-schedule=<id>` (see resolveTriggerCommand). Pure +
+ * exported so both electron/main.js and tests use the same parser.
+ * @param {string[]} argv
+ * @returns {string|null}
+ */
+/**
+ * Build a well-formed `schtasks /Create` command. The task action (/TR) is a
+ * double-quoted string, so any quotes inside the command (e.g. a quoted exe
+ * path "C:\…\OnBuzz.exe" or node "bin/cli.js") MUST be escaped as \" — otherwise
+ * Task Scheduler stores a truncated/garbled action that silently fails to run.
+ * Pure + exported for testing.
+ */
+export function buildSchtasksCreateCommand(taskName, command, scArgs) {
+  const escapedAction = String(command).replace(/"/g, '\\"');
+  return `schtasks /Create /TN "${taskName}" /TR "${escapedAction}" ${scArgs} /F`;
+}
+
+/**
+ * Extract the schedule id from an Electron launch argv. The OS scheduler runs
+ * the app with `--trigger-schedule=<id>` (see resolveTriggerCommand). Pure +
+ * exported so both electron/main.js and tests use the same parser.
+ * @param {string[]} argv
+ * @returns {string|null}
+ */
+export function parseTriggerScheduleArg(argv = []) {
+  const prefix = '--trigger-schedule=';
+  for (const a of argv) {
+    if (typeof a === 'string' && a.startsWith(prefix)) {
+      const id = a.slice(prefix.length).trim();
+      if (id) return id;
+    }
+  }
+  return null;
+}
+
 // ========================
 // Predefined presets for user-friendly schedule creation
 // ========================
@@ -120,6 +201,10 @@ class ScheduleService {
     this.schedules = new Map(); // id → schedule object
     this.configPath = path.join(getUserDataDir(), 'schedules.json');
     this.checkIntervalMs = 30000; // Check every 30 seconds
+    // Missed-run handling: a run >90s late means the app was off (a live tick is
+    // at most one interval late). Catch up a missed run only if it's <24h stale.
+    this.missThresholdMs = 90 * 1000;
+    this.catchUpGraceMs = 24 * 60 * 60 * 1000;
     this.checkTimer = null;
 
     // Dependencies (injected)
@@ -169,6 +254,16 @@ class ScheduleService {
     this.syncAllToOS().catch(err =>
       this.logger.warn('Failed to sync schedules to OS on startup', { error: err.message })
     );
+
+    // Electron OS-scheduler launch: the app was started solely to fire a
+    // schedule while it was closed (see resolveTriggerCommand). Fire it now.
+    const bootTriggerId = process.env.LOXIA_TRIGGER_SCHEDULE;
+    if (bootTriggerId) {
+      this.logger.info('Boot-triggering schedule from OS scheduler', { id: bootTriggerId });
+      this.triggerSchedule(bootTriggerId).catch(err =>
+        this.logger.error('Boot-trigger failed', { id: bootTriggerId, error: err.message })
+      );
+    }
   }
 
   stop() {
@@ -231,6 +326,8 @@ class ScheduleService {
       lastRun: null,
       lastRunStatus: null,
       runCount: 0,
+      lastMissedRun: null,   // ISO of the most recent run missed while offline
+      missedRunCount: 0,     // how many runs were missed while offline
       createdAt: new Date().toISOString(),
       updatedAt: new Date().toISOString()
     };
@@ -253,10 +350,14 @@ class ScheduleService {
 
     // If cron changed, reparse and recalculate next run
     if (updates.cronExpression) {
+      // Capture the preset name from the ORIGINAL input before resolving —
+      // checking it against the resolved cron (as before) always returned null,
+      // silently dropping the preset label on every preset-based update.
+      const presetName = CRON_PRESETS[updates.cronExpression] ? updates.cronExpression : null;
       const resolvedCron = CRON_PRESETS[updates.cronExpression] || updates.cronExpression;
       parseCron(resolvedCron); // validate
       updates.cronExpression = resolvedCron;
-      updates.cronPreset = CRON_PRESETS[updates.cronExpression] ? updates.cronExpression : null;
+      updates.cronPreset = presetName;
       const parsed = parseCron(resolvedCron);
       updates.nextRun = getNextCronDate(parsed)?.toISOString() || null;
     }
@@ -313,6 +414,25 @@ class ScheduleService {
     return { ...CRON_PRESETS };
   }
 
+  /**
+   * Force-run a schedule immediately, regardless of cron timing. Used by the
+   * "run now" UI button, the CLI `trigger-schedule` route, and the Electron
+   * boot-trigger (when the OS scheduler launches the app to fire a missed run).
+   * Counts as a real execution (advances lastRun/runCount) but does NOT change
+   * the cron-derived nextRun.
+   */
+  async triggerSchedule(id) {
+    const schedule = this.getSchedule(id);
+    if (!schedule) throw new Error(`Schedule not found: ${id}`);
+    await this._executeSchedule(schedule);
+    schedule.lastRun = new Date().toISOString();
+    schedule.runCount++;
+    schedule.updatedAt = new Date().toISOString();
+    await this._saveSchedules();
+    this._broadcast('schedule_updated', schedule);
+    return schedule;
+  }
+
   // ========================
   // Tick — check and fire due schedules
   // ========================
@@ -338,30 +458,54 @@ class ScheduleService {
         continue;
       }
 
-      const nextRun = new Date(schedule.nextRun);
-      if (now >= nextRun) {
-        // Fire!
-        await this._executeSchedule(schedule);
+      const decision = evaluateScheduleRun({
+        nextRun: schedule.nextRun,
+        now,
+        missThresholdMs: this.missThresholdMs,
+        catchUpGraceMs: this.catchUpGraceMs,
+      });
+      if (!decision.due) continue;
+
+      // Record a miss (run came due while the app was off). Surfaced in the UI.
+      if (decision.missed) {
+        schedule.lastMissedRun = schedule.nextRun;
+        schedule.missedRunCount = (schedule.missedRunCount || 0) + 1;
+        this.logger.warn('Scheduled run was missed while offline', {
+          id: schedule.id, name: schedule.name,
+          missedRun: schedule.nextRun,
+          caughtUp: decision.shouldFire,
+          staleMs: decision.lateMs,
+        });
+        this._broadcast('schedule_missed', {
+          id: schedule.id, name: schedule.name,
+          missedRun: schedule.nextRun, caughtUp: decision.shouldFire,
+        });
+      }
 
+      if (decision.shouldFire) {
+        // Fire (on-time, or a recent missed run we're catching up).
+        await this._executeSchedule(schedule);
         schedule.lastRun = now.toISOString();
         schedule.runCount++;
-        schedule.updatedAt = now.toISOString();
+      }
+      // (A missed run older than the grace window is recorded above but NOT
+      // executed — we just advance to the next occurrence below.)
+      schedule.updatedAt = now.toISOString();
 
-        // Check if schedule should auto-disable (runOnce or maxRuns reached)
-        if (schedule.runOnce || (schedule.maxRuns != null && schedule.runCount >= schedule.maxRuns)) {
-          schedule.enabled = false;
-          schedule.nextRun = null;
-          this._broadcast('schedule_updated', schedule);
-          this.logger.info('Schedule auto-disabled', {
-            id: schedule.id, name: schedule.name,
-            reason: schedule.runOnce ? 'run-once' : `maxRuns (${schedule.maxRuns}) reached`
-          });
-        } else {
-          // Calculate next run
-          const parsed = parseCron(schedule.cronExpression);
-          const next = getNextCronDate(parsed, now);
-          schedule.nextRun = next ? next.toISOString() : null;
-        }
+      // Auto-disable (runOnce / maxRuns) only counts actual executions.
+      if (decision.shouldFire && (schedule.runOnce || (schedule.maxRuns != null && schedule.runCount >= schedule.maxRuns))) {
+        schedule.enabled = false;
+        schedule.nextRun = null;
+        this._broadcast('schedule_updated', schedule);
+        this.logger.info('Schedule auto-disabled', {
+          id: schedule.id, name: schedule.name,
+          reason: schedule.runOnce ? 'run-once' : `maxRuns (${schedule.maxRuns}) reached`
+        });
+      } else {
+        // Advance to the next occurrence after now.
+        const parsed = parseCron(schedule.cronExpression);
+        const next = getNextCronDate(parsed, now);
+        schedule.nextRun = next ? next.toISOString() : null;
       }
     }
 
@@ -550,7 +694,12 @@ class ScheduleService {
 
     try {
       const loxiaBin = this._findLoxiaBin();
-      const command = `${loxiaBin} trigger-schedule ${schedule.id}`;
+      const command = resolveTriggerCommand({
+        scheduleId: schedule.id,
+        isElectron: !!process.versions?.electron,
+        execPath: process.execPath,
+        loxiaBin,
+      });
 
       if (process.platform === 'win32') {
         await this._syncToWindows(schedule, command);
@@ -658,7 +807,7 @@ class ScheduleService {
     }
 
     execSync(
-      `schtasks /Create /TN "${taskName}" /TR "${command}" ${scArgs} /F`,
+      buildSchtasksCreateCommand(taskName, command, scArgs),
       { encoding: 'utf-8' }
     );
 

package/src/services/vision/__tests__/visionAnalysisService.test.js

@@ -0,0 +1,160 @@
+import { jest, describe, test, expect } from '@jest/globals';
+import { VisionAnalysisService } from '../visionAnalysisService.js';
+
+const ok = (body) => ({ ok: true, json: async () => body });
+const bad = (status, body = {}) => ({ ok: false, status, json: async () => body });
+
+function make({ models = [{ name: 'gpt-4o', supportsVision: true }], fetchImpl, apiKey = 'k', baseUrl = 'https://b' } = {}) {
+  const aiService = {
+    baseUrl,
+    apiKeyManager: { getKeysForRequest: jest.fn().mockReturnValue({ loxiaApiKey: apiKey }) },
+  };
+  const modelsService = { getModels: () => models };
+  return new VisionAnalysisService({ aiService, modelsService, fetchImpl, logger: { warn() {} } });
+}
+
+describe('vision model discovery + selection', () => {
+  test('visionModels filters by supportsVision', () => {
+    const s = make({ models: [{ name: 'a', supportsVision: true }, { name: 'b' }, null] });
+    expect(s.visionModels().map((m) => m.name)).toEqual(['a']);
+  });
+  test('hasVisionModel reflects availability', () => {
+    expect(make({ models: [{ name: 'a', supportsVision: true }] }).hasVisionModel()).toBe(true);
+    expect(make({ models: [] }).hasVisionModel()).toBe(false);
+  });
+  test('selectModel: recommended > budget > first', () => {
+    expect(make({ models: [{ name: 'first', supportsVision: true }, { name: 'rec', supportsVision: true, recommended_for: ['vision'] }] }).selectModel()).toBe('rec');
+    expect(make({ models: [{ name: 'first', supportsVision: true }, { name: 'bud', supportsVision: true, tier: 'budget' }] }).selectModel()).toBe('bud');
+    expect(make({ models: [{ name: 'first', supportsVision: true }, { name: 'second', supportsVision: true }] }).selectModel()).toBe('first');
+    expect(make({ models: [] }).selectModel()).toBeNull();
+  });
+  test('constructor with no deps does not throw; no models → empty', () => {
+    const s = new VisionAnalysisService();
+    expect(s.hasVisionModel()).toBe(false);
+  });
+});
+
+describe('analyze', () => {
+  test('throws without an image or prompt or model', async () => {
+    await expect(make().analyze({ prompt: 'q' })).rejects.toThrow(/imageBase64 is required/);
+    await expect(make().analyze({ imageBase64: 'x' })).rejects.toThrow(/prompt is required/);
+    await expect(make({ models: [] }).analyze({ imageBase64: 'x', prompt: 'q' })).rejects.toThrow(/No vision-capable model/);
+  });
+
+  test('primary /llm/chat success returns text + model', async () => {
+    const fetchImpl = jest.fn().mockResolvedValue(ok({ content: 'a cat' }));
+    const res = await make({ fetchImpl }).analyze({ imageBase64: 'B64', mimeType: 'image/png', prompt: 'what is it?' });
+    expect(res).toEqual({ text: 'a cat', model: 'gpt-4o' });
+    expect(fetchImpl.mock.calls[0][0]).toBe('https://b/llm/chat');
+  });
+
+  test('OpenAI image block + bearer header', async () => {
+    const fetchImpl = jest.fn().mockResolvedValue(ok({ choices: [{ message: { content: 'x' } }] }));
+    await make({ fetchImpl }).analyze({ imageBase64: 'B64', prompt: 'q' });
+    const body = JSON.parse(fetchImpl.mock.calls[0][1].body);
+    expect(body.messages[0].content[0]).toMatchObject({ type: 'image_url' });
+    expect(fetchImpl.mock.calls[0][1].headers.Authorization).toBe('Bearer k');
+  });
+
+  test('Anthropic model → anthropic image block', async () => {
+    const fetchImpl = jest.fn().mockResolvedValue(ok({ content: 'x' }));
+    await make({ models: [{ name: 'claude-x', supportsVision: true }], fetchImpl }).analyze({ imageBase64: 'B64', prompt: 'q' });
+    const body = JSON.parse(fetchImpl.mock.calls[0][1].body);
+    expect(body.messages[0].content[0]).toMatchObject({ type: 'image', source: { type: 'base64' } });
+  });
+
+  test('falls back to /llm/vision when /llm/chat fails', async () => {
+    const fetchImpl = jest.fn()
+      .mockResolvedValueOnce(bad(500, { error: 'chat down' }))
+      .mockResolvedValueOnce(ok({ content: 'fallback answer' }));
+    const res = await make({ fetchImpl }).analyze({ imageBase64: 'B64', prompt: 'q' });
+    expect(res.text).toBe('fallback answer');
+    expect(fetchImpl.mock.calls[1][0]).toBe('https://b/llm/vision');
+  });
+
+  test('both endpoints failing → throws', async () => {
+    const fetchImpl = jest.fn()
+      .mockResolvedValueOnce(bad(500))
+      .mockResolvedValueOnce(bad(503, { error: { message: 'vision down' } }));
+    await expect(make({ fetchImpl }).analyze({ imageBase64: 'B64', prompt: 'q' })).rejects.toThrow(/vision down/);
+  });
+
+  test('no api key → no Authorization header', async () => {
+    const fetchImpl = jest.fn().mockResolvedValue(ok({ content: 'x' }));
+    await make({ fetchImpl, apiKey: null }).analyze({ imageBase64: 'B64', prompt: 'q' });
+    expect(fetchImpl.mock.calls[0][1].headers.Authorization).toBeUndefined();
+  });
+
+  test('uses backendUrl when baseUrl is absent', async () => {
+    const fetchImpl = jest.fn().mockResolvedValue(ok({ content: 'x' }));
+    const s = new VisionAnalysisService({
+      aiService: { backendUrl: 'https://alt', apiKeyManager: { getKeysForRequest: () => ({ loxiaApiKey: 'k' }) } },
+      modelsService: { getModels: () => [{ name: 'gpt-4o', supportsVision: true }] },
+      fetchImpl,
+    });
+    await s.analyze({ imageBase64: 'B64', prompt: 'q' });
+    expect(fetchImpl.mock.calls[0][0]).toBe('https://alt/llm/chat');
+  });
+
+  test('chat returns no content field → empty string text', async () => {
+    const fetchImpl = jest.fn().mockResolvedValue(ok({}));
+    const res = await make({ fetchImpl }).analyze({ imageBase64: 'B64', prompt: 'q' });
+    expect(res.text).toBe('');
+  });
+
+  test('analyze() with no arguments throws (default {} param)', async () => {
+    await expect(make().analyze()).rejects.toThrow(/imageBase64 is required/);
+  });
+
+  test('uses the global fetch when no fetchImpl is injected', async () => {
+    const prev = global.fetch;
+    global.fetch = jest.fn().mockResolvedValue(ok({ content: 'via global' }));
+    try {
+      const s = new VisionAnalysisService({
+        aiService: { baseUrl: 'https://b', apiKeyManager: { getKeysForRequest: () => ({ loxiaApiKey: 'k' }) } },
+        modelsService: { getModels: () => [{ name: 'gpt-4o', supportsVision: true }] },
+      });
+      const res = await s.analyze({ imageBase64: 'B64', prompt: 'q' });
+      expect(res.text).toBe('via global');
+      expect(global.fetch).toHaveBeenCalled();
+    } finally { global.fetch = prev; }
+  });
+
+  test('empty backend url when aiService has no urls (|| "" guard)', async () => {
+    const fetchImpl = jest.fn().mockResolvedValue(ok({ content: 'x' }));
+    const s = new VisionAnalysisService({
+      aiService: { apiKeyManager: { getKeysForRequest: () => ({}) } }, // no baseUrl/backendUrl
+      modelsService: { getModels: () => [{ name: 'gpt-4o', supportsVision: true }] },
+      fetchImpl,
+    });
+    await s.analyze({ imageBase64: 'B64', prompt: 'q' });
+    expect(fetchImpl.mock.calls[0][0]).toBe('/llm/chat'); // backend url resolved to ''
+  });
+
+  test('vision-endpoint fallback: string error body + empty content arm', async () => {
+    // chat fails (no body), vision returns empty content → ''
+    const fetchImpl = jest.fn()
+      .mockResolvedValueOnce(bad(500))
+      .mockResolvedValueOnce(ok({}));
+    const res = await make({ fetchImpl }).analyze({ imageBase64: 'B64', prompt: 'q' });
+    expect(res.text).toBe('');
+  });
+
+  test('error responses with unparseable JSON bodies are tolerated (both .catch arms)', async () => {
+    const throwingBad = (status) => ({ ok: false, status, json: async () => { throw new Error('nope'); } });
+    const fetchImpl = jest.fn().mockResolvedValueOnce(throwingBad(500)).mockResolvedValueOnce(throwingBad(503));
+    await expect(make({ fetchImpl }).analyze({ imageBase64: 'B64', prompt: 'q' })).rejects.toThrow(/vision 503/);
+  });
+
+  test('vision-endpoint failure with no body → status message', async () => {
+    const fetchImpl = jest.fn().mockResolvedValueOnce(bad(500)).mockResolvedValueOnce(bad(503));
+    await expect(make({ fetchImpl }).analyze({ imageBase64: 'B64', prompt: 'q' })).rejects.toThrow(/vision 503/);
+  });
+
+  test('vision-endpoint failure with a string error → message surfaced', async () => {
+    const fetchImpl = jest.fn()
+      .mockResolvedValueOnce(bad(500))
+      .mockResolvedValueOnce(bad(503, { error: 'plain string error' }));
+    await expect(make({ fetchImpl }).analyze({ imageBase64: 'B64', prompt: 'q' })).rejects.toThrow(/plain string error/);
+  });
+});

package/src/services/vision/visionAnalysisService.js

@@ -0,0 +1,124 @@
+/**
+ * Vision analysis service.
+ *
+ * Not every chat model can see images. This service analyzes an image with a
+ * SEPARATE vision-capable model (chosen from the catalog) and returns text —
+ * so an image attachment can be made useful to ANY chat model by injecting the
+ * analysis. It reuses the same backend endpoints the VisionTool uses:
+ *   1. POST /llm/chat with a multimodal message (works for all vision models)
+ *   2. fallback POST /llm/vision (the dedicated endpoint)
+ *
+ * Pure dependency injection (aiService / modelsService / fetchImpl) so it is
+ * fully unit-testable without a network. Extracted as a standalone service so
+ * both the attachment context builder and (in future) the VisionTool can share
+ * one vision path.
+ */
+
+const SYSTEM_PROMPT = 'You are a precise image analysis assistant. Answer directly and concisely. If the image contains text, transcribe it accurately. If asked about objects, list them clearly.';
+
+export class VisionAnalysisService {
+  constructor({ aiService = null, modelsService = null, fetchImpl = null, logger = null } = {}) {
+    this.aiService = aiService;
+    this.modelsService = modelsService;
+    this.fetchImpl = fetchImpl || ((...args) => fetch(...args));
+    this.logger = logger;
+  }
+
+  /** All catalog models flagged with vision support. */
+  visionModels() {
+    const all = this.modelsService?.getModels?.() || [];
+    return all.filter((m) => m && m.supportsVision === true);
+  }
+
+  /** Whether any vision-capable model is available. */
+  hasVisionModel() {
+    return this.visionModels().length > 0;
+  }
+
+  /** Pick the best vision model: recommended → budget tier → first. */
+  selectModel() {
+    const models = this.visionModels();
+    if (models.length === 0) return null;
+    const recommended = models.find((m) => m.recommended_for?.includes('vision'));
+    if (recommended) return recommended.name;
+    const budget = models.find((m) => m.tier === 'budget');
+    if (budget) return budget.name;
+    return models[0].name;
+  }
+
+  /**
+   * Analyze an image and return its description text.
+   * @param {Object} opts
+   * @param {string} opts.imageBase64
+   * @param {string} [opts.mimeType]
+   * @param {string} opts.prompt
+   * @param {string} [opts.sessionId]
+   * @returns {Promise<{text: string, model: string}>}
+   */
+  async analyze({ imageBase64, mimeType = 'image/png', prompt, sessionId = null } = {}) {
+    if (!imageBase64) throw new Error('imageBase64 is required');
+    if (!prompt || !prompt.trim()) throw new Error('prompt is required');
+    const model = this.selectModel();
+    if (!model) throw new Error('No vision-capable model available');
+
+    try {
+      const text = await this._callChat({ imageBase64, mimeType, prompt, model, sessionId });
+      return { text, model };
+    } catch (chatErr) {
+      this.logger?.warn?.('[visionAnalysis] /llm/chat failed, trying /llm/vision', { error: chatErr?.message });
+      const text = await this._callVisionEndpoint({ imageBase64, prompt, model, sessionId });
+      return { text, model };
+    }
+  }
+
+  _backendUrl() {
+    return this.aiService?.baseUrl || this.aiService?.backendUrl || '';
+  }
+
+  _apiKey(sessionId) {
+    const keys = this.aiService?.apiKeyManager?.getKeysForRequest?.(sessionId, { platformProvided: true });
+    return keys?.loxiaApiKey || null;
+  }
+
+  _headers(sessionId) {
+    const apiKey = this._apiKey(sessionId);
+    return { 'Content-Type': 'application/json', ...(apiKey ? { Authorization: `Bearer ${apiKey}` } : {}) };
+  }
+
+  async _callChat({ imageBase64, mimeType, prompt, model, sessionId }) {
+    const isAnthropic = /claude|anthropic/i.test(model);
+    const imageBlock = isAnthropic
+      ? { type: 'image', source: { type: 'base64', media_type: mimeType, data: imageBase64 } }
+      : { type: 'image_url', image_url: { url: `data:${mimeType};base64,${imageBase64}` } };
+
+    const messages = [{ role: 'user', content: [imageBlock, { type: 'text', text: prompt }] }];
+    const payload = {
+      model, message: prompt, systemPrompt: SYSTEM_PROMPT, messages,
+      options: { max_tokens: 2048, temperature: 0.1 },
+    };
+
+    const resp = await this.fetchImpl(`${this._backendUrl()}/llm/chat`, {
+      method: 'POST', headers: this._headers(sessionId), body: JSON.stringify(payload),
+    });
+    if (!resp.ok) {
+      const data = await resp.json().catch(() => ({}));
+      throw new Error(data.error?.message || data.error || `chat ${resp.status}`);
+    }
+    const data = await resp.json();
+    return data.content || data.choices?.[0]?.message?.content || '';
+  }
+
+  async _callVisionEndpoint({ imageBase64, prompt, model, sessionId }) {
+    const resp = await this.fetchImpl(`${this._backendUrl()}/llm/vision`, {
+      method: 'POST', headers: this._headers(sessionId), body: JSON.stringify({ image: imageBase64, prompt, model, metadata: {} }),
+    });
+    if (!resp.ok) {
+      const data = await resp.json().catch(() => ({}));
+      throw new Error(data.error?.message || data.error || `vision ${resp.status}`);
+    }
+    const data = await resp.json();
+    return data.content || '';
+  }
+}
+
+export default VisionAnalysisService;