onbuzz 4.1.0 → 4.3.0

package/src/interfaces/__tests__/videoJobsRoutes.test.js

@@ -0,0 +1,179 @@
+/**
+ * Tests for /api/videos/jobs (list), /api/videos/jobs/:id/cancel,
+ * /api/videos (list files), and DELETE /api/videos (delete file).
+ * Mini-app pattern — routes only, no full webServer boot.
+ */
+
+import { describe, it, expect, beforeAll, afterAll, beforeEach } from '@jest/globals';
+import express from 'express';
+import { createServer } from 'http';
+import path from 'path';
+import fs from 'fs/promises';
+import os from 'os';
+
+const HTTP_STATUS = {
+  OK: 200, BAD_REQUEST: 400, NOT_FOUND: 404, SERVICE_UNAVAILABLE: 503, INTERNAL_SERVER_ERROR: 500,
+};
+
+function buildApp({ toolsRegistry, agentPool, sessions }) {
+  const app = express();
+
+  app.get('/api/videos/jobs', async (_req, res) => {
+    try {
+      const tool = toolsRegistry?.getTool?.('video-gen');
+      if (!tool || typeof tool.getJobsSnapshot !== 'function') {
+        return res.json({ success: true, queued: [], active: [], completed: [], limits: {} });
+      }
+      res.json({ success: true, ...tool.getJobsSnapshot() });
+    } catch (error) {
+      res.status(HTTP_STATUS.INTERNAL_SERVER_ERROR).json({ success: false, error: error.message });
+    }
+  });
+
+  app.post('/api/videos/jobs/:jobId/cancel', async (req, res) => {
+    try {
+      const tool = toolsRegistry?.getTool?.('video-gen');
+      if (!tool || typeof tool.cancelJob !== 'function') {
+        return res.status(HTTP_STATUS.SERVICE_UNAVAILABLE).json({ success: false, error: 'Video tool not available' });
+      }
+      const result = tool.cancelJob(req.params.jobId);
+      if (!result.success) return res.status(HTTP_STATUS.NOT_FOUND).json(result);
+      res.json(result);
+    } catch (error) {
+      res.status(HTTP_STATUS.INTERNAL_SERVER_ERROR).json({ success: false, error: error.message });
+    }
+  });
+
+  app.get('/api/videos', async (req, res) => {
+    try {
+      if (!agentPool) return res.json({ success: true, videos: [] });
+      const requestedAgentId = req.query.agentId || null;
+      const agents = await agentPool.getAllAgents();
+      const results = [];
+      const seen = new Set();
+      const VIDEO_EXTS = new Set(['.mp4', '.webm', '.mov', '.gif']);
+      for (const agent of (agents instanceof Map ? Array.from(agents.values()) : agents)) {
+        if (requestedAgentId && agent.id !== requestedAgentId) continue;
+        const workDir = agent.directoryAccess?.workingDirectory || agent.projectDir;
+        if (!workDir) continue;
+        const videosDir = path.join(workDir, 'videos');
+        let entries;
+        try { entries = await fs.readdir(videosDir); } catch { continue; }
+        for (const name of entries) {
+          const ext = path.extname(name).toLowerCase();
+          if (!VIDEO_EXTS.has(ext)) continue;
+          const abs = path.join(videosDir, name);
+          if (seen.has(abs)) continue;
+          seen.add(abs);
+          let stat;
+          try { stat = await fs.stat(abs); } catch { continue; }
+          if (!stat.isFile()) continue;
+          const anySession = Array.from(sessions.values())[0];
+          const sessionId = agent.sessionId || anySession?.sessionId || 'web-session';
+          results.push({
+            filename: name, agentId: agent.id, agentName: agent.name,
+            projectDir: workDir, mtime: stat.mtime.toISOString(), size: stat.size,
+            url: `/api/videos/${encodeURIComponent(sessionId)}/${encodeURIComponent(name)}`,
+          });
+        }
+      }
+      results.sort((a, b) => b.mtime.localeCompare(a.mtime));
+      res.json({ success: true, videos: results });
+    } catch (error) {
+      res.status(HTTP_STATUS.INTERNAL_SERVER_ERROR).json({ success: false, error: error.message });
+    }
+  });
+
+  app.delete('/api/videos', async (req, res) => {
+    try {
+      const { agentId, filename } = req.query;
+      if (!agentId || !filename) return res.status(HTTP_STATUS.BAD_REQUEST).json({ success: false, error: 'agentId and filename are required' });
+      const normalized = path.basename(filename);
+      if (normalized !== filename || filename.includes('..')) return res.status(HTTP_STATUS.BAD_REQUEST).json({ success: false, error: 'Invalid filename' });
+      const ext = path.extname(normalized).toLowerCase();
+      if (!['.mp4', '.webm', '.mov', '.gif'].includes(ext)) return res.status(HTTP_STATUS.BAD_REQUEST).json({ success: false, error: 'Unsupported file extension for video delete' });
+      if (!agentPool) return res.status(HTTP_STATUS.SERVICE_UNAVAILABLE).json({ success: false, error: 'Agent pool not available' });
+      const agent = await agentPool.getAgent(agentId);
+      if (!agent) return res.status(HTTP_STATUS.NOT_FOUND).json({ success: false, error: 'Agent not found' });
+      const workDir = agent.directoryAccess?.workingDirectory || agent.projectDir;
+      if (!workDir) return res.status(HTTP_STATUS.BAD_REQUEST).json({ success: false, error: 'Agent has no working directory' });
+      const target = path.join(workDir, 'videos', normalized);
+      await fs.unlink(target);
+      res.json({ success: true });
+    } catch (error) {
+      if (error.code === 'ENOENT') return res.status(HTTP_STATUS.NOT_FOUND).json({ success: false, error: 'Video not found' });
+      res.status(HTTP_STATUS.INTERNAL_SERVER_ERROR).json({ success: false, error: error.message });
+    }
+  });
+
+  return app;
+}
+
+async function http(url, options = {}) {
+  const resp = await globalThis.fetch(url, options);
+  const body = resp.headers.get('content-type')?.includes('json') ? await resp.json() : await resp.text();
+  return { status: resp.status, body };
+}
+
+describe('video jobs routes', () => {
+  let server, baseUrl;
+  let tool; // fake video tool
+
+  beforeAll(() => {
+    tool = {
+      _q: [],
+      _a: [],
+      _c: [],
+      getJobsSnapshot() {
+        return { queued: this._q, active: this._a, completed: this._c, limits: { queue: 5, concurrency: 2 } };
+      },
+      cancelJob(jobId) {
+        if (this._q.find(j => j.jobId === jobId)) { this._q = this._q.filter(j => j.jobId !== jobId); return { success: true, state: 'queued' }; }
+        if (this._a.find(j => j.jobId === jobId)) { this._a = this._a.filter(j => j.jobId !== jobId); return { success: true, state: 'active' }; }
+        return { success: false, error: 'Job not found or already terminal' };
+      },
+    };
+    const toolsRegistry = { getTool: (id) => id === 'video-gen' ? tool : null };
+    const app = buildApp({ toolsRegistry, agentPool: null, sessions: new Map() });
+    server = createServer(app);
+    return new Promise(r => server.listen(0, () => { baseUrl = `http://localhost:${server.address().port}`; r(); }));
+  });
+
+  afterAll(() => { server?.close(); });
+
+  beforeEach(() => {
+    tool._q = []; tool._a = []; tool._c = [];
+  });
+
+  it('GET /api/videos/jobs returns snapshot', async () => {
+    tool._q = [{ jobId: 'q1', prompt: 'fox' }];
+    tool._a = [{ jobId: 'a1', prompt: 'bear' }];
+    tool._c = [{ jobId: 'c1', prompt: 'eagle' }];
+    const { status, body } = await http(`${baseUrl}/api/videos/jobs`);
+    expect(status).toBe(200);
+    expect(body.queued).toHaveLength(1);
+    expect(body.active).toHaveLength(1);
+    expect(body.completed).toHaveLength(1);
+    expect(body.limits).toMatchObject({ queue: 5 });
+  });
+
+  it('POST cancel removes a queued job', async () => {
+    tool._q = [{ jobId: 'q1' }];
+    const { status, body } = await http(`${baseUrl}/api/videos/jobs/q1/cancel`, { method: 'POST' });
+    expect(status).toBe(200);
+    expect(body.success).toBe(true);
+    expect(body.state).toBe('queued');
+    expect(tool._q).toHaveLength(0);
+  });
+
+  it('POST cancel returns 404 for unknown job', async () => {
+    const { status, body } = await http(`${baseUrl}/api/videos/jobs/nope/cancel`, { method: 'POST' });
+    expect(status).toBe(404);
+    expect(body.success).toBe(false);
+  });
+});
+
+// Library routes are now GalleryService-backed — see galleryService.test.js
+// and galleryRoutes.test.js for the thorough coverage. The only difference
+// for videos is the file extensions and paths, which galleryService handles
+// by delegation; a duplicate integration test here would be redundant.

package/src/interfaces/webServer.js

@@ -29,6 +29,8 @@ import { getVisualEditorServer, getVisualEditorPort, getVisualEditorBaseUrl, set
 
 // Import credential vault for secure credential management
 import { getCredentialVault } from '../services/credentialVault.js';
+import { getGalleryService } from '../services/galleryService.js';
+import { getUserDataPaths } from '../utilities/userDataDir.js';
 
 // Connect visual editor server to bridge (enables element selection forwarding)
 setBridgeGetter(getVisualEditorBridge);
@@ -192,13 +194,19 @@ const SCHEDULER_VIEWER_HTML = `<!doctype html>
     // (finish_reason, has tool calls, has reasoning, model).
     const chip = '<span class="chip ' + cls + '" title="first at ' + esc(new Date(e.firstAt).toISOString()) + '">' + e.count + 'x / ' + fmtMs(elapsedMs) + '</span>';
     if (!lastSample) return chip;
+    // NB: the newline in .join below is double-escaped on purpose. This
+    // whole block is inside a JS template literal (SCHEDULER_VIEWER_HTML),
+    // so a single-escaped newline sequence would be processed at server
+    // load time, yielding a literal newline inside a single-quoted string
+    // in the served JS — which the browser rejects. Same trick in
+    // fmtModeCell below.
     const sampleDetail = samples.map(s =>
       s.at + ': content=' + s.contentType + '(' + s.contentLength + ') ' +
       'tools=' + (s.hasToolCalls ? s.toolCallCount : 0) + ' ' +
       'reasoning=' + (s.hasReasoning ? 'yes' : 'no') + ' ' +
       'finish=' + (s.finishReason || '—') + ' ' +
       'model=' + (s.model || '—')
-    ).join('\n');
+    ).join('\\n');
     return chip +
       '<div class="tasks-line" title="' + esc(sampleDetail) + '">' +
         esc(lastSample.hint || '(empty response — cause unknown)') +
@@ -223,10 +231,13 @@ const SCHEDULER_VIEWER_HTML = `<!doctype html>
     const last = history[history.length - 1];
     const age = Date.now() - new Date(last.at).getTime();
     // Build a title tooltip with the last ~5 transitions as a plain-text list.
+    // See note above (chipEmpty): double-escape in the .join is intentional
+    // — the outer template literal would otherwise process a single-escape
+    // newline into a real newline at load time.
     const historyTip = history.slice(-5).reverse().map(t => {
       const ageT = Date.now() - new Date(t.at).getTime();
       return fmtMs(ageT) + ' ago: ' + t.from + ' → ' + t.to + ' — ' + t.humanReason;
-    }).join('\n');
+    }).join('\\n');
     const direction = last.from + ' → ' + last.to;
     return current +
       '<div class="tasks-line" title="' + esc(historyTip) + '">' +
@@ -2694,6 +2705,213 @@ h2{color:#16a34a;margin-bottom:.5rem;} p{color:#666;}</style></head>
       }
     });
 
+    // Gallery: list images from the durable gallery store. Delegates to
+    // GalleryService which reads `{userDataDir}/gallery/images/` and
+    // enriches each entry from its .json sidecar (prompt, model, agent,
+    // etc.). The tool writes to the gallery automatically when the
+    // agent's toolConfig.image-gen.saveToGallery is true (default).
+    this.app.get('/api/images', async (req, res) => {
+      try {
+        const gallery = getGalleryService(this.logger);
+        const entries = await gallery.listImages({ agentId: req.query.agentId || undefined });
+        const images = entries.map(e => ({
+          ...e,
+          size: e.bytes, // legacy name used by the frontend
+          url: `/api/gallery/images/${encodeURIComponent(e.filename)}`,
+        }));
+        res.json({ success: true, images });
+      } catch (error) {
+        this.logger.error('Gallery list failed', { error: error.message });
+        res.status(HTTP_STATUS.INTERNAL_SERVER_ERROR).json({
+          success: false,
+          error: error.message,
+        });
+      }
+    });
+
+    // Delete a gallery image (asset + sidecar). Filename is the gallery's
+    // timestamped filename, not the agent's original — the list endpoint
+    // emits it as `filename`.
+    this.app.delete('/api/images', async (req, res) => {
+      try {
+        const { filename } = req.query;
+        if (!filename) {
+          return res.status(HTTP_STATUS.BAD_REQUEST).json({
+            success: false,
+            error: 'filename is required',
+          });
+        }
+        const gallery = getGalleryService(this.logger);
+        const existed = await gallery.deleteImage(filename);
+        if (!existed) {
+          return res.status(HTTP_STATUS.NOT_FOUND).json({
+            success: false,
+            error: 'Image not found',
+          });
+        }
+        res.json({ success: true });
+      } catch (error) {
+        if (error.code === 'INVALID_FILENAME') {
+          return res.status(HTTP_STATUS.BAD_REQUEST).json({
+            success: false,
+            error: 'Invalid filename',
+          });
+        }
+        if (error.code === 'INVALID_EXT') {
+          return res.status(HTTP_STATUS.BAD_REQUEST).json({
+            success: false,
+            error: 'Unsupported file extension',
+          });
+        }
+        this.logger.error('Gallery delete failed', { error: error.message });
+        res.status(HTTP_STATUS.INTERNAL_SERVER_ERROR).json({
+          success: false,
+          error: error.message,
+        });
+      }
+    });
+
+    // Serve a gallery image directly from `{userDataDir}/gallery/images/`.
+    // Used by the /gallery page. Path traversal + extension gating live
+    // here — the raw file is under userDataDir so this is the only
+    // access point.
+    this.app.get('/api/gallery/images/:filename', async (req, res) => {
+      try {
+        const filename = req.params.filename;
+        const normalized = path.basename(filename);
+        if (normalized !== filename || filename.includes('..')) {
+          return res.status(HTTP_STATUS.BAD_REQUEST).json({ success: false, error: 'Invalid filename' });
+        }
+        const ext = path.extname(normalized).toLowerCase();
+        if (!['.png', '.jpg', '.jpeg', '.webp', '.gif'].includes(ext)) {
+          return res.status(HTTP_STATUS.BAD_REQUEST).json({ success: false, error: 'Unsupported extension' });
+        }
+        const target = path.join(getUserDataPaths().galleryImages, normalized);
+        res.sendFile(target, (err) => {
+          if (err && !res.headersSent) {
+            res.status(HTTP_STATUS.NOT_FOUND).json({ success: false, error: 'Image not found' });
+          }
+        });
+      } catch (error) {
+        res.status(HTTP_STATUS.INTERNAL_SERVER_ERROR).json({ success: false, error: error.message });
+      }
+    });
+
+    // Video jobs: live snapshot of queue + active + recently completed
+    // jobs from the `video-gen` tool instance. The tool keeps this state
+    // in-memory on its singleton instance; we fetch via toolsRegistry.
+    this.app.get('/api/videos/jobs', async (req, res) => {
+      try {
+        const tool = this.orchestrator?.toolsRegistry?.getTool?.('video-gen');
+        if (!tool || typeof tool.getJobsSnapshot !== 'function') {
+          return res.json({ success: true, queued: [], active: [], completed: [], limits: {} });
+        }
+        const snap = tool.getJobsSnapshot();
+        res.json({ success: true, ...snap });
+      } catch (error) {
+        this.logger.error('Video jobs list failed', { error: error.message });
+        res.status(HTTP_STATUS.INTERNAL_SERVER_ERROR).json({
+          success: false,
+          error: error.message,
+        });
+      }
+    });
+
+    // Cancel a queued or active video job. Completed/failed jobs can't be
+    // cancelled — delete them from the history with DELETE /api/videos.
+    this.app.post('/api/videos/jobs/:jobId/cancel', async (req, res) => {
+      try {
+        const { jobId } = req.params;
+        const tool = this.orchestrator?.toolsRegistry?.getTool?.('video-gen');
+        if (!tool || typeof tool.cancelJob !== 'function') {
+          return res.status(HTTP_STATUS.SERVICE_UNAVAILABLE).json({
+            success: false,
+            error: 'Video tool not available',
+          });
+        }
+        const result = tool.cancelJob(jobId);
+        if (!result.success) {
+          return res.status(HTTP_STATUS.NOT_FOUND).json(result);
+        }
+        res.json(result);
+      } catch (error) {
+        this.logger.error('Video job cancel failed', { error: error.message });
+        res.status(HTTP_STATUS.INTERNAL_SERVER_ERROR).json({
+          success: false,
+          error: error.message,
+        });
+      }
+    });
+
+    // Video gallery: list videos from the durable gallery store.
+    // Delegates to GalleryService. Sidecars carry prompt/model/duration.
+    this.app.get('/api/videos', async (req, res) => {
+      try {
+        const gallery = getGalleryService(this.logger);
+        const entries = await gallery.listVideos({ agentId: req.query.agentId || undefined });
+        const videos = entries.map(e => ({
+          ...e,
+          size: e.bytes,
+          url: `/api/gallery/videos/${encodeURIComponent(e.filename)}`,
+        }));
+        res.json({ success: true, videos });
+      } catch (error) {
+        this.logger.error('Video gallery list failed', { error: error.message });
+        res.status(HTTP_STATUS.INTERNAL_SERVER_ERROR).json({
+          success: false,
+          error: error.message,
+        });
+      }
+    });
+
+    // Delete a gallery video (asset + sidecar).
+    this.app.delete('/api/videos', async (req, res) => {
+      try {
+        const { filename } = req.query;
+        if (!filename) {
+          return res.status(HTTP_STATUS.BAD_REQUEST).json({ success: false, error: 'filename is required' });
+        }
+        const gallery = getGalleryService(this.logger);
+        const existed = await gallery.deleteVideo(filename);
+        if (!existed) {
+          return res.status(HTTP_STATUS.NOT_FOUND).json({ success: false, error: 'Video not found' });
+        }
+        res.json({ success: true });
+      } catch (error) {
+        if (error.code === 'INVALID_FILENAME') {
+          return res.status(HTTP_STATUS.BAD_REQUEST).json({ success: false, error: 'Invalid filename' });
+        }
+        if (error.code === 'INVALID_EXT') {
+          return res.status(HTTP_STATUS.BAD_REQUEST).json({ success: false, error: 'Unsupported file extension' });
+        }
+        this.logger.error('Video delete failed', { error: error.message });
+        res.status(HTTP_STATUS.INTERNAL_SERVER_ERROR).json({ success: false, error: error.message });
+      }
+    });
+
+    // Serve a gallery video from `{userDataDir}/gallery/videos/`.
+    this.app.get('/api/gallery/videos/:filename', async (req, res) => {
+      try {
+        const filename = req.params.filename;
+        const normalized = path.basename(filename);
+        if (normalized !== filename || filename.includes('..')) {
+          return res.status(HTTP_STATUS.BAD_REQUEST).json({ success: false, error: 'Invalid filename' });
+        }
+        const ext = path.extname(normalized).toLowerCase();
+        if (!['.mp4', '.webm', '.mov', '.gif'].includes(ext)) {
+          return res.status(HTTP_STATUS.BAD_REQUEST).json({ success: false, error: 'Unsupported extension' });
+        }
+        const target = path.join(getUserDataPaths().galleryVideos, normalized);
+        res.sendFile(target, (err) => {
+          if (err && !res.headersSent) {
+            res.status(HTTP_STATUS.NOT_FOUND).json({ success: false, error: 'Video not found' });
+          }
+        });
+      } catch (error) {
+        res.status(HTTP_STATUS.INTERNAL_SERVER_ERROR).json({ success: false, error: error.message });
+      }
+    });
+
     // Video serving endpoint for generated videos
     this.app.get('/api/videos/:sessionId/:filename', async (req, res) => {
       try {

package/src/services/__tests__/agentActivityService.test.js

@@ -315,5 +315,88 @@ describe('agentActivityService', () => {
       expect(result.skip).toBe(false);
       expect(result.reason).toBeNull();
     });
+
+    // Belt-and-suspenders: inbound work always beats delay/pause. The
+    // primary fix lives in agentPool._wakeAgentForMessage — this is the
+    // second line of defence against any path that bypasses it.
+    test('delayed agent with queued user message does NOT skip', () => {
+      const future = new Date(Date.now() + 60_000).toISOString();
+      const agent = makeAgent({
+        delayEndTime: future,
+        messageQueues: { userMessages: [{ content: 'hi' }], interAgentMessages: [], toolResults: [] },
+      });
+      expect(shouldSkipIteration(agent).skip).toBe(false);
+    });
+
+    test('delayed agent with queued inter-agent message does NOT skip', () => {
+      const future = new Date(Date.now() + 60_000).toISOString();
+      const agent = makeAgent({
+        delayEndTime: future,
+        messageQueues: { userMessages: [], interAgentMessages: [{ content: 'ping' }], toolResults: [] },
+      });
+      expect(shouldSkipIteration(agent).skip).toBe(false);
+    });
+
+    test('delayed agent with queued tool result does NOT skip', () => {
+      const future = new Date(Date.now() + 60_000).toISOString();
+      const agent = makeAgent({
+        delayEndTime: future,
+        messageQueues: { userMessages: [], interAgentMessages: [], toolResults: [{ toolId: 'x', status: 'completed' }] },
+      });
+      expect(shouldSkipIteration(agent).skip).toBe(false);
+    });
+
+    test('paused-until agent with queued message does NOT skip', () => {
+      const future = new Date(Date.now() + 60_000).toISOString();
+      const agent = makeAgent({
+        pausedUntil: future,
+        messageQueues: { userMessages: [{ content: 'hi' }], interAgentMessages: [], toolResults: [] },
+      });
+      expect(shouldSkipIteration(agent).skip).toBe(false);
+    });
+  });
+
+  describe('shouldAgentBeActive — inbound work overrides delay/pause', () => {
+    test('delayed agent with user message → active', () => {
+      const future = new Date(Date.now() + 60_000).toISOString();
+      const agent = makeAgent({
+        delayEndTime: future,
+        messageQueues: { userMessages: [{ content: 'hi' }], interAgentMessages: [], toolResults: [] },
+        taskList: { tasks: [{ status: 'pending' }] },
+      });
+      expect(shouldAgentBeActive(agent).active).toBe(true);
+    });
+
+    test('delayed agent with inter-agent message → active', () => {
+      const future = new Date(Date.now() + 60_000).toISOString();
+      const agent = makeAgent({
+        delayEndTime: future,
+        messageQueues: { userMessages: [], interAgentMessages: [{ content: 'ping' }], toolResults: [] },
+        taskList: { tasks: [{ status: 'pending' }] },
+      });
+      expect(shouldAgentBeActive(agent).active).toBe(true);
+    });
+
+    test('pausedUntil agent (status=active) with queued work → active', () => {
+      // Unusual but defensive: status still ACTIVE but pausedUntil set
+      const future = new Date(Date.now() + 60_000).toISOString();
+      const agent = makeAgent({
+        pausedUntil: future,
+        messageQueues: { userMessages: [], interAgentMessages: [{ content: 'ping' }], toolResults: [] },
+        taskList: { tasks: [{ status: 'pending' }] },
+      });
+      expect(shouldAgentBeActive(agent).active).toBe(true);
+    });
+
+    test('delayed agent WITHOUT queued work → still inactive (delay honoured)', () => {
+      const future = new Date(Date.now() + 60_000).toISOString();
+      const agent = makeAgent({
+        delayEndTime: future,
+        messageQueues: { userMessages: [], interAgentMessages: [], toolResults: [] },
+      });
+      const r = shouldAgentBeActive(agent);
+      expect(r.active).toBe(false);
+      expect(r.reason).toBe('agent-delayed');
+    });
   });
 });

package/src/services/__tests__/aiService.reasoningTokens.test.js

@@ -0,0 +1,66 @@
+/**
+ * Tests for _extractReasoningTokens — pulls a reasoning-token count out
+ * of a provider's `usage` block regardless of which schema the provider
+ * chose. Surfaced even for opaque providers (OpenAI o-series) that don't
+ * return reasoning content text — the count alone is useful signal.
+ */
+
+import { describe, test, expect } from '@jest/globals';
+import { _extractReasoningTokens } from '../aiService.js';
+
+describe('_extractReasoningTokens', () => {
+  test('returns null for null/undefined/non-object', () => {
+    expect(_extractReasoningTokens(null)).toBeNull();
+    expect(_extractReasoningTokens(undefined)).toBeNull();
+    expect(_extractReasoningTokens('{}')).toBeNull();
+    expect(_extractReasoningTokens(42)).toBeNull();
+  });
+
+  test('returns null when no reasoning tokens fields present', () => {
+    expect(_extractReasoningTokens({ prompt_tokens: 100, completion_tokens: 50 })).toBeNull();
+  });
+
+  test('OpenAI shape: completion_tokens_details.reasoning_tokens', () => {
+    const usage = {
+      prompt_tokens: 100,
+      completion_tokens: 200,
+      completion_tokens_details: { reasoning_tokens: 150 },
+    };
+    expect(_extractReasoningTokens(usage)).toBe(150);
+  });
+
+  test('Flat shape: usage.reasoning_tokens', () => {
+    expect(_extractReasoningTokens({ reasoning_tokens: 512 })).toBe(512);
+  });
+
+  test('Anthropic-style shape: output_tokens_details.reasoning_tokens', () => {
+    expect(_extractReasoningTokens({
+      output_tokens_details: { reasoning_tokens: 4217 }
+    })).toBe(4217);
+  });
+
+  test('camelCase variant: completionTokensDetails.reasoningTokens', () => {
+    expect(_extractReasoningTokens({
+      completionTokensDetails: { reasoningTokens: 1024 }
+    })).toBe(1024);
+  });
+
+  test('preference order — flat reasoning_tokens wins when multiple present', () => {
+    // Not a provider we expect, but defensive: if both are set, the
+    // flattened top-level field is first in the candidate list.
+    expect(_extractReasoningTokens({
+      reasoning_tokens: 100,
+      completion_tokens_details: { reasoning_tokens: 999 },
+    })).toBe(100);
+  });
+
+  test('zero is a valid count, not null', () => {
+    expect(_extractReasoningTokens({ reasoning_tokens: 0 })).toBe(0);
+  });
+
+  test('non-finite values are skipped (defensive against NaN/Infinity)', () => {
+    expect(_extractReasoningTokens({ reasoning_tokens: NaN })).toBeNull();
+    expect(_extractReasoningTokens({ reasoning_tokens: Infinity })).toBeNull();
+    expect(_extractReasoningTokens({ reasoning_tokens: 'lots' })).toBeNull();
+  });
+});