onbuzz 4.1.0 → 4.3.0

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

@@ -0,0 +1,305 @@
+/**
+ * CLI ingestion contract test — consumes the exact SSE bytes that
+ * autopilot-backend's `/llm/chat` route emits (locked in backend's
+ * `routes/__tests__/llm.chat.reasoning.test.js`) and asserts that the
+ * resulting response object carries content, reasoning, and reasoning
+ * tokens correctly.
+ *
+ * Why this exists: the feature spans two repos. Per-repo tests prove
+ * each side holds its own assumption. This one proves they share the
+ * SAME wire contract: backend emissions parse correctly on the CLI
+ * side. If either drifts in the future, this tripwire catches it BEFORE
+ * "works in dev, broken in prod."
+ *
+ * The tested function (`_parseSSEResponseStream`) is the real production
+ * parser used by `_makeStreamingAPIRequest` — it's not a test double.
+ * Production and tests share a single implementation, so passing tests
+ * mean passing production.
+ */
+
+import { describe, test, expect } from '@jest/globals';
+import { _parseSSEResponseStream } from '../aiService.js';
+
+/**
+ * Build a fake ReadableStream-default-reader over a series of Uint8Array
+ * chunks. Mirrors what `response.body.getReader()` returns in production,
+ * but with caller-controlled bytes.
+ */
+function makeReader(chunks) {
+  let i = 0;
+  return {
+    async read() {
+      if (i >= chunks.length) return { done: true, value: undefined };
+      const value = typeof chunks[i] === 'string'
+        ? new TextEncoder().encode(chunks[i])
+        : chunks[i];
+      i++;
+      return { done: false, value };
+    },
+  };
+}
+
+/**
+ * Build an SSE frame string. Backend emits these via
+ * `data: ${JSON.stringify(event)}\n\n`.
+ */
+function sse(event) {
+  return `data: ${JSON.stringify(event)}\n\n`;
+}
+
+// ────────────────────────────────────────────────────────────────────────
+// Backward compat — plain content-only stream
+// ────────────────────────────────────────────────────────────────────────
+
+describe('_parseSSEResponseStream — backward compat (no reasoning)', () => {
+  test('plain chunk + done stream returns content only, reasoning empty', async () => {
+    const chunks = [
+      sse({ type: 'start', model: 'gpt-4o' }),
+      sse({ type: 'chunk', content: 'Hello ' }),
+      sse({ type: 'chunk', content: 'world.' }),
+      sse({ type: 'done', content: 'Hello world.',
+            usage: { input_tokens: 10, output_tokens: 5, total_tokens: 15 },
+            model: 'gpt-4o', finishReason: 'stop' }),
+    ];
+    const result = await _parseSSEResponseStream(makeReader(chunks), { fallbackModel: 'gpt-4o' });
+
+    expect(result.content).toBe('Hello world.');
+    expect(result.reasoning).toBe('');
+    expect(result.reasoningTokens).toBeNull();
+    expect(result.usage).toEqual({ input_tokens: 10, output_tokens: 5, total_tokens: 15 });
+    expect(result.model).toBe('gpt-4o');
+    expect(result.finishReason).toBe('stop');
+  });
+
+  test('onChunk callback fires per chunk in order', async () => {
+    const chunks = [
+      sse({ type: 'chunk', content: 'a' }),
+      sse({ type: 'chunk', content: 'b' }),
+      sse({ type: 'chunk', content: 'c' }),
+      sse({ type: 'done', usage: null, model: 'x', finishReason: 'stop' }),
+    ];
+    const captured = [];
+    await _parseSSEResponseStream(makeReader(chunks), { onChunk: (c) => captured.push(c) });
+    expect(captured).toEqual(['a', 'b', 'c']);
+  });
+});
+
+// ────────────────────────────────────────────────────────────────────────
+// Reasoning — full content path (DeepSeek / Kimi / xAI / Claude-thinking)
+// ────────────────────────────────────────────────────────────────────────
+
+describe('_parseSSEResponseStream — reasoning accumulation', () => {
+  test('interleaved reasoning_chunk + chunk accumulate into separate fields', async () => {
+    const chunks = [
+      sse({ type: 'reasoning_chunk', content: 'Let me think...' }),
+      sse({ type: 'chunk', content: 'Answer: ' }),
+      sse({ type: 'reasoning_chunk', content: ' still checking.' }),
+      sse({ type: 'chunk', content: '42.' }),
+      sse({ type: 'done', content: 'Answer: 42.',
+            usage: {
+              input_tokens: 10, output_tokens: 50, total_tokens: 60,
+              reasoning_tokens: 40,
+            },
+            model: 'DeepSeek-R1-0528', finishReason: 'stop' }),
+    ];
+    const result = await _parseSSEResponseStream(makeReader(chunks));
+
+    expect(result.content).toBe('Answer: 42.');
+    expect(result.reasoning).toBe('Let me think... still checking.');
+    expect(result.reasoningTokens).toBe(40);
+    expect(result.model).toBe('DeepSeek-R1-0528');
+  });
+
+  test('onReasoningChunk callback fires separately from onChunk', async () => {
+    const chunks = [
+      sse({ type: 'reasoning_chunk', content: 'thinking' }),
+      sse({ type: 'chunk', content: 'answer' }),
+      sse({ type: 'done', usage: null, model: 'x', finishReason: 'stop' }),
+    ];
+    const texts = [];
+    const reasons = [];
+    await _parseSSEResponseStream(makeReader(chunks), {
+      onChunk: (c) => texts.push(c),
+      onReasoningChunk: (c) => reasons.push(c),
+    });
+    expect(texts).toEqual(['answer']);
+    expect(reasons).toEqual(['thinking']);
+  });
+
+  test('backend-batched reasoning on done event is used when no reasoning_chunk events arrived', async () => {
+    const chunks = [
+      sse({ type: 'chunk', content: 'answer' }),
+      sse({ type: 'done', content: 'answer', reasoning: 'batched thinking trace',
+            usage: { input_tokens: 10, output_tokens: 30, reasoning_tokens: 25, total_tokens: 40 },
+            model: 'x', finishReason: 'stop' }),
+    ];
+    const result = await _parseSSEResponseStream(makeReader(chunks));
+    expect(result.reasoning).toBe('batched thinking trace');
+    expect(result.reasoningTokens).toBe(25);
+  });
+
+  test('streamed reasoning beats done.reasoning when both present', async () => {
+    // Belt-and-suspenders backends might send both. Prefer the streamed
+    // accumulation (it's what the caller's onReasoningChunk saw).
+    const chunks = [
+      sse({ type: 'reasoning_chunk', content: 'streamed' }),
+      sse({ type: 'chunk', content: 'ok' }),
+      sse({ type: 'done', reasoning: 'batched', usage: null, model: 'x', finishReason: 'stop' }),
+    ];
+    const result = await _parseSSEResponseStream(makeReader(chunks));
+    expect(result.reasoning).toBe('streamed');
+  });
+});
+
+// ────────────────────────────────────────────────────────────────────────
+// OpenAI o-series — reasoning_tokens count without content text
+// ────────────────────────────────────────────────────────────────────────
+
+describe('_parseSSEResponseStream — opaque reasoning (count-only)', () => {
+  test('reasoning_tokens in done.usage but no reasoning_chunk events → reasoning="" + count', async () => {
+    const chunks = [
+      sse({ type: 'chunk', content: 'Final answer.' }),
+      sse({ type: 'done', content: 'Final answer.',
+            usage: {
+              input_tokens: 10, output_tokens: 100, total_tokens: 110,
+              reasoning_tokens: 85,
+            },
+            model: 'o3', finishReason: 'stop' }),
+    ];
+    const result = await _parseSSEResponseStream(makeReader(chunks));
+    expect(result.reasoning).toBe('');
+    expect(result.reasoningTokens).toBe(85);
+    expect(result.content).toBe('Final answer.');
+  });
+
+  test('reasoning_tokens in the completion_tokens_details alt shape also extracts', async () => {
+    const chunks = [
+      sse({ type: 'chunk', content: 'answer' }),
+      sse({ type: 'done', usage: {
+        input_tokens: 10, output_tokens: 50, total_tokens: 60,
+        completion_tokens_details: { reasoning_tokens: 40 },
+      }, model: 'x', finishReason: 'stop' }),
+    ];
+    const result = await _parseSSEResponseStream(makeReader(chunks));
+    expect(result.reasoningTokens).toBe(40);
+  });
+});
+
+// ────────────────────────────────────────────────────────────────────────
+// Robustness — chunking boundaries, malformed frames, errors
+// ────────────────────────────────────────────────────────────────────────
+
+describe('_parseSSEResponseStream — robustness', () => {
+  test('SSE frames split across TCP chunks at arbitrary byte positions still parse correctly', async () => {
+    // Assemble one big SSE stream, then slice it at weird positions.
+    const full =
+      sse({ type: 'reasoning_chunk', content: 'Hmm.' }) +
+      sse({ type: 'chunk', content: 'Answer.' }) +
+      sse({ type: 'done', content: 'Answer.',
+            usage: { input_tokens: 5, output_tokens: 5, total_tokens: 10, reasoning_tokens: 3 },
+            model: 'x', finishReason: 'stop' });
+    // Split into 7-byte chunks (nothing magical — small enough to cross event boundaries).
+    const chunks = [];
+    for (let i = 0; i < full.length; i += 7) chunks.push(full.slice(i, i + 7));
+
+    const result = await _parseSSEResponseStream(makeReader(chunks));
+    expect(result.content).toBe('Answer.');
+    expect(result.reasoning).toBe('Hmm.');
+    expect(result.reasoningTokens).toBe(3);
+  });
+
+  test('malformed JSON data frames are skipped without crashing', async () => {
+    const chunks = [
+      'data: this-is-not-json\n\n',
+      sse({ type: 'chunk', content: 'real' }),
+      sse({ type: 'done', usage: null, model: 'x', finishReason: 'stop' }),
+    ];
+    const result = await _parseSSEResponseStream(makeReader(chunks));
+    expect(result.content).toBe('real');
+  });
+
+  test('[DONE] sentinel is ignored (SSE end-of-stream marker convention)', async () => {
+    const chunks = [
+      sse({ type: 'chunk', content: 'hi' }),
+      sse({ type: 'done', content: 'hi', usage: null, model: 'x', finishReason: 'stop' }),
+      'data: [DONE]\n\n',
+    ];
+    const result = await _parseSSEResponseStream(makeReader(chunks));
+    expect(result.content).toBe('hi');
+  });
+
+  test('stream ending without trailing newline still emits the final done event', async () => {
+    // Some proxies drop the terminal \n\n. Verify the trailing-line flush works.
+    const chunks = [
+      'data: {"type":"chunk","content":"x"}\n\n',
+      'data: {"type":"done","content":"x","usage":null,"model":"m","finishReason":"stop"}', // NO \n\n
+    ];
+    const result = await _parseSSEResponseStream(makeReader(chunks));
+    expect(result.content).toBe('x');
+    expect(result.finishReason).toBe('stop');
+  });
+
+  test('type:"error" event throws with .code propagated', async () => {
+    const chunks = [
+      sse({ type: 'error', error: 'provider 500', code: 'upstream_500' }),
+    ];
+    await expect(_parseSSEResponseStream(makeReader(chunks))).rejects.toMatchObject({
+      message: 'provider 500',
+      code: 'upstream_500',
+    });
+  });
+
+  test('stream ends before done → returns accumulated content with no finalData', async () => {
+    const chunks = [
+      sse({ type: 'chunk', content: 'partial' }),
+      // No done event.
+    ];
+    const result = await _parseSSEResponseStream(makeReader(chunks), { fallbackModel: 'm' });
+    expect(result.content).toBe('partial');
+    expect(result.finishReason).toBe('stop');
+    expect(result.model).toBe('m');
+  });
+
+  test('unknown event types are silently ignored (forward compat)', async () => {
+    const chunks = [
+      sse({ type: 'start', model: 'x', requestId: 'r1' }), // metadata, no content
+      sse({ type: 'some_new_future_event', data: 'whatever' }),
+      sse({ type: 'chunk', content: 'real' }),
+      sse({ type: 'done', content: 'real', usage: null, model: 'x', finishReason: 'stop' }),
+    ];
+    const result = await _parseSSEResponseStream(makeReader(chunks));
+    expect(result.content).toBe('real');
+  });
+});
+
+// ────────────────────────────────────────────────────────────────────────
+// Tool-call bridge output — inline JSON flows through as content
+// ────────────────────────────────────────────────────────────────────────
+
+describe('_parseSSEResponseStream — tool-call inline JSON passthrough', () => {
+  test('backend-bridged tool_call inline JSON arrives in content verbatim', async () => {
+    // The backend converts native tool_calls to inline JSON blocks and
+    // yields them as regular `chunk` events. Verify the CLI receives
+    // them intact so its TagParser can extract.
+    // Header only — see toolCallBridge.js DESIGN NOTE: the preamble
+    // is "**Calling X**" with no param preview, because the JSON block
+    // below is the single source of truth and duplicating its contents
+    // in a preview was bloating the context.
+    const inlineBlock = '\n**Calling filesystem**\n\n'
+      + '```json\n'
+      + '{\n  "toolId": "filesystem",\n  "parameters": {\n    "action": "read"\n  }\n}\n'
+      + '```\n';
+    const chunks = [
+      sse({ type: 'chunk', content: 'Sure, checking. ' }),
+      sse({ type: 'chunk', content: inlineBlock }),
+      sse({ type: 'done', content: 'Sure, checking. ' + inlineBlock,
+            usage: { input_tokens: 5, output_tokens: 30, total_tokens: 35 },
+            model: 'DeepSeek-R1-0528', finishReason: 'tool_calls' }),
+    ];
+    const result = await _parseSSEResponseStream(makeReader(chunks));
+    expect(result.content).toContain('```json');
+    expect(result.content).toContain('"toolId": "filesystem"');
+    expect(result.content).toContain('"action": "read"');
+    expect(result.finishReason).toBe('tool_calls');
+  });
+});

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

@@ -108,7 +108,9 @@ describe('filterContentForExternalRelay()', () => {
   });
 
   test('CONTENT VERBATIM — "Calling X" bridge preamble preserved if wrapped', () => {
-    const txt = '**Calling terminal** — cmd: ls…\n\nsee below';
+    // Bridge emits header-only (no em-dash param preview — see
+    // toolCallBridge.js DESIGN NOTE).
+    const txt = '**Calling terminal**\n\nsee below';
     const { blocks } = filterContentForExternalRelay(`<external>${txt}</external>`);
     expect(blocks[0].text).toBe(txt);
   });
@@ -134,7 +136,7 @@ describe('filterContentForExternalRelay()', () => {
     // after the bridge has converted native tool calls to inline blocks.
     const content =
       "Thinking through this…\n\n" +
-      "**Calling taskmanager** — type: create, title: foo…\n\n" +
+      "**Calling taskmanager**\n\n" +
       "```json\n{\"toolId\":\"taskmanager\",\"parameters\":{\"actions\":[{\"type\":\"create\",\"title\":\"foo\"}]}}\n```\n\n" +
       "<external to=\"discord:#ops\">\n" +
       "Created a task for you: **foo**. I'll post back when it's done.\n" +

package/src/services/__tests__/channelRelay.integration.test.js

@@ -454,7 +454,7 @@ describe('Cross-service isolation: a single agent response splits across platfor
     // for either Responses API or Chat Completions after the bridge.
     const content =
       'Private reasoning the operator sees.\n' +
-      '**Calling taskmanager** — type: complete…\n' +
+      '**Calling taskmanager**\n' +
       '```json\n{"toolId":"taskmanager","parameters":{"actions":[{"type":"complete","taskId":"t-1"}]}}\n```\n\n' +
       '<external to="discord:#ops">\n' +
       '**Deploy finished.** 42 tests passed.\n' +

package/src/services/__tests__/conversationQuery.reasoning.test.js

@@ -0,0 +1,102 @@
+/**
+ * Tests for reasoning-content handling in conversationQuery.read().
+ *
+ * Contract:
+ *   - `hasReasoning` is ALWAYS surfaced when the archived message carries
+ *     a non-empty `reasoning` field, even when the text isn't returned.
+ *     Gives the agent a signal to re-fetch with includeReasoning=true.
+ *   - `reasoningTokens` is ALWAYS surfaced when present (non-null).
+ *   - The reasoning TEXT is returned only when includeReasoning=true.
+ *   - Other modes (overview, range, search, around, byTool) are
+ *     unaffected by this change — reasoning is deliberately scoped to
+ *     `read` because loading chain-of-thought in bulk responses would
+ *     blow the byte cap immediately.
+ */
+
+import { describe, test, expect } from '@jest/globals';
+import { read, range, around } from '../conversationQuery.js';
+
+function mkMsg({ id = 'msg_0001', content = 'hello', reasoning, reasoningTokens }) {
+  const m = {
+    id,
+    role: 'assistant',
+    content,
+    createdAt: '2026-04-21T10:00:00Z',
+    tokenUsage: { totalTokens: 100 },
+  };
+  if (reasoning !== undefined) m.reasoning = reasoning;
+  if (reasoningTokens !== undefined) m.reasoningTokens = reasoningTokens;
+  return m;
+}
+
+describe('read() — reasoning presence signalling', () => {
+  test('hasReasoning=true + reasoningTokens surfaced without returning the text', () => {
+    const messages = [mkMsg({ reasoning: 'long chain of thought', reasoningTokens: 512 })];
+    const out = read(messages, { messageId: 'msg_0001' });
+    expect(out.targetFound).toBe(true);
+    expect(out.message.hasReasoning).toBe(true);
+    expect(out.message.reasoningTokens).toBe(512);
+    // Reasoning text is NOT returned by default
+    expect(out.message.reasoning).toBeUndefined();
+  });
+
+  test('includeReasoning=true returns the reasoning text', () => {
+    const thought = 'Let me think step by step. First I need to...';
+    const messages = [mkMsg({ reasoning: thought, reasoningTokens: 150 })];
+    const out = read(messages, { messageId: 'msg_0001', includeReasoning: true });
+    expect(out.message.reasoning).toBe(thought);
+    expect(out.message.hasReasoning).toBe(true);
+    expect(out.message.reasoningTokens).toBe(150);
+  });
+
+  test('message with no reasoning → hasReasoning=false, reasoningTokens=null', () => {
+    const messages = [mkMsg({})];
+    const out = read(messages, { messageId: 'msg_0001' });
+    expect(out.message.hasReasoning).toBe(false);
+    expect(out.message.reasoningTokens).toBeNull();
+    expect(out.message.reasoning).toBeUndefined();
+  });
+
+  test('message with only reasoningTokens (opaque provider, no text)', () => {
+    // OpenAI o-series case: we know they thought, but not what they thought.
+    const messages = [mkMsg({ reasoningTokens: 4217 })];
+    const out = read(messages, { messageId: 'msg_0001', includeReasoning: true });
+    expect(out.message.hasReasoning).toBe(false);    // no text present
+    expect(out.message.reasoningTokens).toBe(4217);
+    expect(out.message.reasoning).toBeUndefined();
+  });
+
+  test('empty reasoning string treated as absent (keeps signal honest)', () => {
+    const messages = [mkMsg({ reasoning: '', reasoningTokens: 0 })];
+    const out = read(messages, { messageId: 'msg_0001', includeReasoning: true });
+    expect(out.message.hasReasoning).toBe(false);
+    expect(out.message.reasoning).toBeUndefined();
+  });
+
+  test('reasoning is not pulled into around()/range() responses (byte-cap discipline)', () => {
+    // Other modes return slim entries; reasoning inclusion is scoped to
+    // read() only because chain-of-thought content can dwarf content.
+    const messages = [mkMsg({ reasoning: 'x'.repeat(50_000) })];
+    const rangeOut = range(messages);
+    const aroundOut = around(messages, { messageId: 'msg_0001' });
+    expect(rangeOut.messages[0].reasoning).toBeUndefined();
+    expect(aroundOut.messages[0].reasoning).toBeUndefined();
+  });
+
+  test('includeReasoning does not leak reasoning across byte cap — cap still applies', () => {
+    // A large reasoning block honored alongside a small content block
+    // should still be bounded by maxBytes in the overall response.
+    const huge = 'R'.repeat(50_000);
+    const messages = [mkMsg({ content: 'tiny', reasoning: huge })];
+    const out = read(messages, {
+      messageId: 'msg_0001',
+      includeReasoning: true,
+      maxBytes: 4096,
+    });
+    // Either reasoning was omitted entirely, OR included but the content
+    // field was trimmed via the existing byte-cap path — both are valid.
+    // What must NOT happen: the full 50KB reasoning in the response.
+    const serialized = JSON.stringify(out);
+    expect(serialized.length).toBeLessThan(50_000);
+  });
+});

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

@@ -0,0 +1,225 @@
+/**
+ * Tests for GalleryService — the durable store for tool-generated
+ * images + videos with metadata sidecars.
+ *
+ * Locks:
+ *   - save copies file + writes a JSON sidecar
+ *   - filename gets a timestamp prefix to avoid collisions
+ *   - list returns entries newest-first with metadata from the sidecar
+ *   - list filters by agentId when supplied
+ *   - delete removes both the asset and its sidecar
+ *   - delete rejects path traversal + unsupported extensions
+ *   - saveImage on a non-image source returns null (no-op, non-fatal)
+ *   - IO failures on the gallery path don't crash the caller (warn + null)
+ */
+
+import { jest, describe, test, expect, beforeEach, afterEach } from '@jest/globals';
+import path from 'path';
+import os from 'os';
+import { promises as fs } from 'fs';
+
+// Point userDataDir to a tmp dir for the duration of the test.
+let tmpRoot;
+jest.unstable_mockModule('../../utilities/userDataDir.js', () => ({
+  getUserDataDir: () => tmpRoot,
+  getUserDataPaths: () => ({
+    base: tmpRoot,
+    state: path.join(tmpRoot, 'state'),
+    agents: path.join(tmpRoot, 'state', 'agents'),
+    settings: path.join(tmpRoot, 'settings'),
+    attachments: path.join(tmpRoot, 'attachments'),
+    logs: path.join(tmpRoot, 'logs'),
+    cache: path.join(tmpRoot, 'cache'),
+    operations: path.join(tmpRoot, 'state', 'operations'),
+    models: path.join(tmpRoot, 'state', 'models'),
+    runtime: path.join(tmpRoot, 'runtime'),
+    skills: path.join(tmpRoot, 'state', 'skills'),
+    gallery: path.join(tmpRoot, 'gallery'),
+    galleryImages: path.join(tmpRoot, 'gallery', 'images'),
+    galleryVideos: path.join(tmpRoot, 'gallery', 'videos'),
+  }),
+  ensureUserDataDirs: async () => {},
+}));
+
+const mod = await import('../galleryService.js');
+const { GalleryService, _resetGalleryServiceForTests, getGalleryService } = mod;
+
+const LOGGER = { info() {}, warn() {}, error() {}, debug() {} };
+
+beforeEach(async () => {
+  _resetGalleryServiceForTests();
+  tmpRoot = await fs.mkdtemp(path.join(os.tmpdir(), 'gallery-svc-'));
+});
+
+afterEach(async () => {
+  await fs.rm(tmpRoot, { recursive: true, force: true }).catch(() => {});
+});
+
+async function makeSourceImage(name = 'fox.png') {
+  const srcDir = path.join(tmpRoot, 'src');
+  await fs.mkdir(srcDir, { recursive: true });
+  const src = path.join(srcDir, name);
+  await fs.writeFile(src, 'PNG-DATA');
+  return src;
+}
+
+async function makeSourceVideo(name = 'dragon.mp4') {
+  const srcDir = path.join(tmpRoot, 'src');
+  await fs.mkdir(srcDir, { recursive: true });
+  const src = path.join(srcDir, name);
+  await fs.writeFile(src, 'MP4-DATA');
+  return src;
+}
+
+describe('GalleryService.saveImage', () => {
+  test('copies the file into gallery/images and writes a sidecar', async () => {
+    const svc = new GalleryService(LOGGER);
+    const src = await makeSourceImage('fox.png');
+    const result = await svc.saveImage({
+      sourcePath: src,
+      metadata: { prompt: 'a fox', model: 'dall-e-3', agentId: 'agent-1', agentName: 'Alice' },
+    });
+    expect(result).toBeTruthy();
+    expect(result.filename).toMatch(/_fox\.png$/);
+    const contents = await fs.readFile(result.path, 'utf8');
+    expect(contents).toBe('PNG-DATA');
+    const sidecar = JSON.parse(await fs.readFile(`${result.path}.json`, 'utf8'));
+    expect(sidecar.prompt).toBe('a fox');
+    expect(sidecar.model).toBe('dall-e-3');
+    expect(sidecar.agentId).toBe('agent-1');
+    expect(sidecar.kind).toBe('image');
+    expect(sidecar.createdAt).toBeTruthy();
+  });
+
+  test('returns null for a non-image source (no throw, no file)', async () => {
+    const svc = new GalleryService(LOGGER);
+    const txt = path.join(tmpRoot, 'src', 'notes.txt');
+    await fs.mkdir(path.dirname(txt), { recursive: true });
+    await fs.writeFile(txt, 'hi');
+    const r = await svc.saveImage({ sourcePath: txt });
+    expect(r).toBeNull();
+  });
+
+  test('returns null when the source path does not exist (warn, not crash)', async () => {
+    const svc = new GalleryService(LOGGER);
+    const r = await svc.saveImage({
+      sourcePath: path.join(tmpRoot, 'does-not-exist.png'),
+    });
+    expect(r).toBeNull();
+  });
+
+  test('two saves of the same basename do not collide', async () => {
+    const svc = new GalleryService(LOGGER);
+    const src = await makeSourceImage('boom.png');
+    const a = await svc.saveImage({ sourcePath: src });
+    // Enough wall-clock for the timestamp prefix to change.
+    await new Promise(r => setTimeout(r, 5));
+    const b = await svc.saveImage({ sourcePath: src });
+    expect(a.filename).not.toBe(b.filename);
+  });
+});
+
+describe('GalleryService.saveVideo', () => {
+  test('copies + writes sidecar with kind=video', async () => {
+    const svc = new GalleryService(LOGGER);
+    const src = await makeSourceVideo('dragon.mp4');
+    const result = await svc.saveVideo({
+      sourcePath: src,
+      metadata: { prompt: 'a dragon', duration: 5, variants: 1, agentId: 'agent-1' },
+    });
+    expect(result).toBeTruthy();
+    const sidecar = JSON.parse(await fs.readFile(`${result.path}.json`, 'utf8'));
+    expect(sidecar.kind).toBe('video');
+    expect(sidecar.duration).toBe(5);
+  });
+});
+
+describe('GalleryService.listImages', () => {
+  test('returns saved images with sidecar metadata, newest first', async () => {
+    const svc = new GalleryService(LOGGER);
+    const src = await makeSourceImage('a.png');
+    const a = await svc.saveImage({ sourcePath: src, metadata: { prompt: 'first', agentId: 'x' } });
+    await new Promise(r => setTimeout(r, 20));
+    const b = await svc.saveImage({ sourcePath: src, metadata: { prompt: 'second', agentId: 'x' } });
+
+    const list = await svc.listImages();
+    expect(list.map(i => i.filename)).toEqual([b.filename, a.filename]);
+    expect(list[0].prompt).toBe('second');
+    expect(list[0].kind).toBe('image');
+    expect(list[0].bytes).toBeGreaterThan(0);
+    expect(list[0].mtime).toMatch(/^\d{4}-\d{2}-\d{2}T/);
+  });
+
+  test('filters by agentId', async () => {
+    const svc = new GalleryService(LOGGER);
+    const src = await makeSourceImage('a.png');
+    await svc.saveImage({ sourcePath: src, metadata: { agentId: 'agent-A' } });
+    await svc.saveImage({ sourcePath: src, metadata: { agentId: 'agent-B' } });
+
+    const onlyB = await svc.listImages({ agentId: 'agent-B' });
+    expect(onlyB).toHaveLength(1);
+    expect(onlyB[0].agentId).toBe('agent-B');
+  });
+
+  test('empty gallery → empty list', async () => {
+    const svc = new GalleryService(LOGGER);
+    const list = await svc.listImages();
+    expect(list).toEqual([]);
+  });
+
+  test('files without sidecars are still listed (best-effort)', async () => {
+    const svc = new GalleryService(LOGGER);
+    const dir = path.join(tmpRoot, 'gallery', 'images');
+    await fs.mkdir(dir, { recursive: true });
+    await fs.writeFile(path.join(dir, 'orphan.png'), 'x');
+    const list = await svc.listImages();
+    expect(list.map(i => i.filename)).toEqual(['orphan.png']);
+    expect(list[0].prompt).toBeUndefined();
+  });
+});
+
+describe('GalleryService.deleteImage', () => {
+  test('removes the image AND its sidecar', async () => {
+    const svc = new GalleryService(LOGGER);
+    const src = await makeSourceImage('gone.png');
+    const { filename, path: assetPath } = await svc.saveImage({ sourcePath: src });
+    await fs.access(assetPath);
+    await fs.access(`${assetPath}.json`);
+
+    const ok = await svc.deleteImage(filename);
+    expect(ok).toBe(true);
+    await expect(fs.access(assetPath)).rejects.toBeTruthy();
+    await expect(fs.access(`${assetPath}.json`)).rejects.toBeTruthy();
+  });
+
+  test('rejects path-traversal filenames', async () => {
+    const svc = new GalleryService(LOGGER);
+    await expect(svc.deleteImage('../secret')).rejects.toMatchObject({ code: 'INVALID_FILENAME' });
+  });
+
+  test('rejects unsupported extensions', async () => {
+    const svc = new GalleryService(LOGGER);
+    await expect(svc.deleteImage('secret.txt')).rejects.toMatchObject({ code: 'INVALID_EXT' });
+  });
+
+  test('returns false when the file is already gone (no throw)', async () => {
+    const svc = new GalleryService(LOGGER);
+    const r = await svc.deleteImage('ghost.png');
+    expect(r).toBe(false);
+  });
+});
+
+describe('getGalleryService singleton', () => {
+  test('returns the same instance across calls', () => {
+    const a = getGalleryService(LOGGER);
+    const b = getGalleryService(LOGGER);
+    expect(a).toBe(b);
+  });
+
+  test('_resetGalleryServiceForTests creates a fresh instance', () => {
+    const a = getGalleryService(LOGGER);
+    _resetGalleryServiceForTests();
+    const b = getGalleryService(LOGGER);
+    expect(a).not.toBe(b);
+  });
+});