onbuzz 4.5.0 → 4.6.0

package/src/modules/widget/galleryStore.js

@@ -157,13 +157,38 @@ export class GalleryStore {
   async _writeNow() {
     const dir = path.dirname(this.filePath);
     try { await fs.mkdir(dir, { recursive: true }); } catch { /* race-tolerant */ }
-    const tmp = this.filePath + '.tmp';
+    // Per-call unique tmp suffix so two concurrent writes (debounce+flush
+    // racing, or any future caller) can't trample each other's tmp file.
+    // The earlier static `.tmp` suffix produced ENOENT under parallel test
+    // load on Windows: writer A renamed first, writer B saw its own tmp
+    // disappear before its rename ran.
+    const tmp = `${this.filePath}.${process.pid}.${Date.now()}.${Math.random().toString(36).slice(2, 8)}.tmp`;
     const payload = JSON.stringify({
       schema: VERSION_SCHEMA,
       entries: Array.from(this._entries.values()),
     }, null, 2);
     await fs.writeFile(tmp, payload, 'utf-8');
-    await fs.rename(tmp, this.filePath);
+    // Windows-fs renames intermittently fail with EPERM / EBUSY when an
+    // antivirus scanner or another process briefly holds the destination
+    // open. A short retry loop covers both production users on Windows
+    // and the parallel-jest workers that surface this most often.
+    let lastErr;
+    for (let attempt = 0; attempt < 5; attempt++) {
+      try {
+        await fs.rename(tmp, this.filePath);
+        return;
+      } catch (err) {
+        lastErr = err;
+        // ENOENT means our tmp already vanished — give up; the source
+        // file is gone, retrying won't recreate it. Other transients
+        // (EPERM/EBUSY/EACCES) get a brief backoff.
+        if (err.code === 'ENOENT') break;
+        await new Promise(r => setTimeout(r, 20 * (attempt + 1)));
+      }
+    }
+    // Best-effort cleanup of stranded tmp; ignore failure.
+    try { await fs.unlink(tmp); } catch { /* ok */ }
+    throw lastErr;
   }
 
   /**

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

@@ -120,6 +120,169 @@ describe('ApiKeyManager', () => {
     expect(manager.keys.vendorKeys.anthropic).toBe('anth-key');
   });
 
+  // Regression locks: the UI used to write display-only placeholder
+  // strings into the editable settings field; auto-save then echoed
+  // them here, overwriting real keys with strings like
+  // `lx_••••••••••••••••(server-managed)` and breaking every agent
+  // request with 401. loadFromDisk must scrub any placeholder that
+  // already snuck onto disk before the fix, so a poisoned persist
+  // file from an older build self-heals on next boot.
+  describe('loadFromDisk placeholder scrub (poisoned persist file)', () => {
+    /**
+     * Helper: prep a manager so loadFromDisk takes the happy path
+     * and returns deterministic decrypted data without going through
+     * the real crypto. Each call hands back the manager + a stub.
+     */
+    function primeForLoad(manager, decryptedJson) {
+      manager.persistenceFile = '/fake/api-keys.enc';
+      manager.encryptionKey = Buffer.alloc(32, 'k');
+      mockFs.readFile.mockResolvedValueOnce('encrypted-bytes-ignored');
+      mockFs.writeFile.mockResolvedValue(undefined);
+      manager._decrypt = jest.fn(() => decryptedJson);
+    }
+
+    test('scrubs bullet-string loxia key + re-persists', async () => {
+      primeForLoad(manager, JSON.stringify({
+        version: 2,
+        keys: {
+          loxiaApiKey: 'lx_••••••••••••••••(server-managed)',
+          vendorKeys: { anthropic: 'sk-ant-real-key' },
+        },
+      }));
+      // Stub persist so we can observe it without going through crypto.
+      manager.persist = jest.fn().mockResolvedValue(undefined);
+
+      await manager.loadFromDisk();
+
+      expect(manager.keys.loxiaApiKey).toBeNull();
+      // Real vendor keys preserved.
+      expect(manager.keys.vendorKeys.anthropic).toBe('sk-ant-real-key');
+      // Best-effort re-persist fired.
+      expect(manager.persist).toHaveBeenCalledTimes(1);
+      // Operator-visible warning logged so the scrub is observable.
+      expect(logger.warn).toHaveBeenCalledWith(
+        expect.stringContaining('Scrubbing placeholder loxiaApiKey')
+      );
+    });
+
+    test('scrubs platform-managed sentinel and any placeholder vendor keys', async () => {
+      primeForLoad(manager, JSON.stringify({
+        version: 2,
+        keys: {
+          loxiaApiKey: 'platform-managed',
+          vendorKeys: {
+            anthropic: '••••••••(server-managed)',
+            openai:    'sk-real-openai-key',
+            azure:     'foo[server-managed]bar',
+          },
+        },
+      }));
+      manager.persist = jest.fn().mockResolvedValue(undefined);
+
+      await manager.loadFromDisk();
+
+      expect(manager.keys.loxiaApiKey).toBeNull();
+      // Placeholder vendors removed entirely (NOT just blanked) so the
+      // shape stays clean for downstream serialization.
+      expect(manager.keys.vendorKeys).not.toHaveProperty('anthropic');
+      expect(manager.keys.vendorKeys).not.toHaveProperty('azure');
+      // Real vendor preserved.
+      expect(manager.keys.vendorKeys.openai).toBe('sk-real-openai-key');
+      expect(manager.persist).toHaveBeenCalledTimes(1);
+    });
+
+    test('clean persist file: no scrub, no re-persist', async () => {
+      primeForLoad(manager, JSON.stringify({
+        version: 2,
+        keys: {
+          loxiaApiKey: 'lx_real_loxia_key_abc123',
+          vendorKeys: { anthropic: 'sk-ant-real', openai: 'sk-real-openai' },
+        },
+      }));
+      manager.persist = jest.fn().mockResolvedValue(undefined);
+
+      await manager.loadFromDisk();
+
+      expect(manager.keys.loxiaApiKey).toBe('lx_real_loxia_key_abc123');
+      expect(manager.keys.vendorKeys).toEqual({ anthropic: 'sk-ant-real', openai: 'sk-real-openai' });
+      // Nothing to scrub → no extra write.
+      expect(manager.persist).not.toHaveBeenCalled();
+    });
+
+    test('legacy globalKeys format: scrub still applies after migration', async () => {
+      primeForLoad(manager, JSON.stringify({
+        // No `version` / `keys` — old shape with `globalKeys` at root.
+        globalKeys: {
+          loxiaApiKey: 'lx_••••(server-managed)',
+          vendorKeys:  { anthropic: 'sk-ant-still-good' },
+        },
+      }));
+      manager.persist = jest.fn().mockResolvedValue(undefined);
+
+      await manager.loadFromDisk();
+
+      expect(manager.keys.loxiaApiKey).toBeNull();
+      expect(manager.keys.vendorKeys.anthropic).toBe('sk-ant-still-good');
+      expect(manager.persist).toHaveBeenCalled();
+    });
+
+    test('persist failure during scrub is non-fatal (in-memory state still clean)', async () => {
+      primeForLoad(manager, JSON.stringify({
+        version: 2,
+        keys: { loxiaApiKey: 'platform-managed', vendorKeys: {} },
+      }));
+      manager.persist = jest.fn().mockRejectedValue(new Error('disk full'));
+
+      // Should NOT throw — re-persist failure is tolerated.
+      await expect(manager.loadFromDisk()).resolves.toBeUndefined();
+      // In-memory state is clean even though disk wasn't updated.
+      expect(manager.keys.loxiaApiKey).toBeNull();
+    });
+  });
+
+  describe('placeholder rejection (server-managed key bug guard)', () => {
+    test('refuses bullet-string placeholder for loxia key, keeps existing', async () => {
+      manager.persistenceFile = null;
+      manager.keys.loxiaApiKey = 'real-key-existing';
+      await manager.setSessionKeys('sess-1', {
+        loxiaApiKey: 'lx_••••••••••••••••(server-managed)'
+      });
+      expect(manager.keys.loxiaApiKey).toBe('real-key-existing');
+    });
+
+    test('refuses [server-managed] tag', async () => {
+      manager.persistenceFile = null;
+      manager.keys.loxiaApiKey = 'real-key';
+      await manager.setSessionKeys('sess-1', {
+        loxiaApiKey: 'lx_abc[server-managed]'
+      });
+      expect(manager.keys.loxiaApiKey).toBe('real-key');
+    });
+
+    test('refuses platform-managed sentinel', async () => {
+      manager.persistenceFile = null;
+      manager.keys.loxiaApiKey = 'real-key';
+      await manager.setSessionKeys('sess-1', { loxiaApiKey: 'platform-managed' });
+      expect(manager.keys.loxiaApiKey).toBe('real-key');
+    });
+
+    test('refuses placeholder vendor keys', async () => {
+      manager.persistenceFile = null;
+      manager.keys.vendorKeys = { anthropic: 'real-anth-key' };
+      await manager.setSessionKeys('sess-1', {
+        vendorKeys: { anthropic: '••••••••(server-managed)' }
+      });
+      expect(manager.keys.vendorKeys.anthropic).toBe('real-anth-key');
+    });
+
+    test('still accepts real keys (regression guard for the guard)', async () => {
+      manager.persistenceFile = null;
+      manager.keys.loxiaApiKey = 'old';
+      await manager.setSessionKeys('sess-1', { loxiaApiKey: 'lx_brand_new_real_key' });
+      expect(manager.keys.loxiaApiKey).toBe('lx_brand_new_real_key');
+    });
+  });
+
   test('getSessionKeys returns keys regardless of sessionId', () => {
     manager.keys.loxiaApiKey = 'test-key';
     const keys = manager.getSessionKeys('any-session');

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

@@ -67,6 +67,329 @@ describe('FlowContextService', () => {
       const result = service.buildFlowAgentContext(meta, null);
       expect(result).toContain('Agent');
     });
+
+    // -- Phase 1.5: typed-output advertisement --
+
+    test('advertises declared outputs by name + type when nodeContract is provided', () => {
+      // When the agent's node declares typed outputs, the system prompt
+      // tells the agent EXACTLY what fields to produce. This is the
+      // mechanism that turns vague job-done summaries into structured
+      // handoffs that the next agent can rely on.
+      const nodeContract = {
+        inputs: [{ name: 'topic', type: 'text', required: true }],
+        outputs: [
+          { name: 'draft',     type: 'text' },
+          { name: 'wordCount', type: 'number' },
+          { name: 'sources',   type: 'file[]' },
+        ],
+      };
+      const result = service.buildFlowAgentContext(baseFlowMetadata, null, nodeContract);
+      expect(result).toContain('REQUIRED OUTPUTS');
+      expect(result).toContain('draft');
+      expect(result).toContain('wordCount');
+      expect(result).toContain('sources');
+      expect(result).toContain('text');
+      expect(result).toContain('number');
+      expect(result).toContain('file[]');
+    });
+
+    test('advertises declared inputs (so agent knows what payload to expect)', () => {
+      const nodeContract = {
+        inputs: [
+          { name: 'topic',    type: 'text',  required: true },
+          { name: 'research', type: 'json',  required: false },
+        ],
+        outputs: [{ name: 'draft', type: 'text' }],
+      };
+      const result = service.buildFlowAgentContext(baseFlowMetadata, null, nodeContract);
+      expect(result).toContain('INPUTS');
+      expect(result).toContain('topic');
+      expect(result).toContain('research');
+    });
+
+    test('omits outputs section when nodeContract is absent (v1 backwards compat)', () => {
+      const result = service.buildFlowAgentContext(baseFlowMetadata, null);
+      expect(result).not.toContain('REQUIRED OUTPUTS');
+    });
+
+    test('omits outputs section when contract.outputs is empty', () => {
+      const nodeContract = { inputs: [], outputs: [] };
+      const result = service.buildFlowAgentContext(baseFlowMetadata, null, nodeContract);
+      expect(result).not.toContain('REQUIRED OUTPUTS');
+    });
+
+    // ---- Phase 7: rich contracts (description / example / instructions) ----
+
+    test('renders FLOW GOAL when flowMetadata.flowDescription is set', () => {
+      const meta = { ...baseFlowMetadata, flowDescription: 'Produce a fact-checked article on the input topic.' };
+      const result = service.buildFlowAgentContext(meta, null);
+      expect(result).toContain('FLOW GOAL:');
+      expect(result).toContain('Produce a fact-checked article');
+    });
+
+    test('omits FLOW GOAL when flowDescription is empty/whitespace', () => {
+      const meta = { ...baseFlowMetadata, flowDescription: '   ' };
+      const result = service.buildFlowAgentContext(meta, null);
+      expect(result).not.toContain('FLOW GOAL:');
+    });
+
+    test('renders NODE INSTRUCTIONS when nodeContract.instructions is set', () => {
+      const nodeContract = { inputs: [], outputs: [],
+        instructions: 'Search peer-reviewed sources first; done when ≥3 citations.' };
+      const result = service.buildFlowAgentContext(baseFlowMetadata, null, nodeContract);
+      expect(result).toContain('NODE INSTRUCTIONS');
+      expect(result).toContain('Search peer-reviewed sources');
+      expect(result).toContain('≥3 citations');
+    });
+
+    test('omits NODE INSTRUCTIONS when instructions is missing or empty', () => {
+      // Missing
+      let result = service.buildFlowAgentContext(baseFlowMetadata, null,
+        { inputs: [], outputs: [{ name: 'x', type: 'text' }] });
+      expect(result).not.toContain('NODE INSTRUCTIONS');
+      // Empty string
+      result = service.buildFlowAgentContext(baseFlowMetadata, null,
+        { inputs: [], outputs: [{ name: 'x', type: 'text' }], instructions: '' });
+      expect(result).not.toContain('NODE INSTRUCTIONS');
+    });
+
+    test('renders description under each input when provided', () => {
+      const nodeContract = {
+        inputs: [{
+          name: 'topic', type: 'text', required: true,
+          description: 'The research topic exactly as provided by the user.',
+        }],
+        outputs: [],
+      };
+      const result = service.buildFlowAgentContext(baseFlowMetadata, null, nodeContract);
+      expect(result).toContain('topic');
+      expect(result).toContain('text');
+      expect(result).toContain('The research topic exactly as provided');
+    });
+
+    test('renders description under each output when provided', () => {
+      const nodeContract = {
+        inputs: [],
+        outputs: [{
+          name: 'findings', type: 'json',
+          description: 'Structured research bag for the writer to use as source of truth.',
+        }],
+      };
+      const result = service.buildFlowAgentContext(baseFlowMetadata, null, nodeContract);
+      expect(result).toContain('findings');
+      expect(result).toContain('Structured research bag');
+    });
+
+    test('renders inline example for short scalar values', () => {
+      const nodeContract = {
+        inputs: [],
+        outputs: [{ name: 'wordCount', type: 'number', example: 850 }],
+      };
+      const result = service.buildFlowAgentContext(baseFlowMetadata, null, nodeContract);
+      expect(result).toContain('Example: 850');
+    });
+
+    test('renders multi-line example as indented block for object values', () => {
+      const nodeContract = {
+        inputs: [],
+        outputs: [{
+          name: 'findings', type: 'json',
+          example: { title: 'AI safety', citations: ['Bostrom 2014'] },
+        }],
+      };
+      const result = service.buildFlowAgentContext(baseFlowMetadata, null, nodeContract);
+      expect(result).toContain('Example:');
+      expect(result).toContain('"title"');
+      expect(result).toContain('"AI safety"');
+      expect(result).toContain('"Bostrom 2014"');
+    });
+
+    test('handles unstringifiable example without throwing (circular ref)', () => {
+      const circular = {};
+      circular.self = circular;
+      const nodeContract = {
+        inputs: [],
+        outputs: [{ name: 'x', type: 'json', example: circular }],
+      };
+      expect(() => service.buildFlowAgentContext(baseFlowMetadata, null, nodeContract))
+        .not.toThrow();
+    });
+
+    test('combines description + example + required marker in one block per field', () => {
+      const nodeContract = {
+        inputs: [],
+        outputs: [{
+          name: 'draft', type: 'text', required: true,
+          description: 'The article draft, ≥500 words.',
+          example: 'Once upon a time...',
+        }],
+      };
+      const result = service.buildFlowAgentContext(baseFlowMetadata, null, nodeContract);
+      // All three pieces appear together
+      expect(result).toContain('draft');
+      expect(result).toContain('text');
+      expect(result).toContain('The article draft, ≥500 words.');
+      expect(result).toContain('"Once upon a time..."');
+    });
+
+    test('treats empty-string description as absent', () => {
+      const nodeContract = {
+        inputs: [],
+        outputs: [{ name: 'x', type: 'text', description: '   ' }],
+      };
+      const result = service.buildFlowAgentContext(baseFlowMetadata, null, nodeContract);
+      // The whitespace-only description should NOT appear in the prompt
+      expect(result).not.toMatch(/^\s+\s+$/m);
+    });
+
+    // -- Phase 5/6 fix: structured handoff rendering --
+
+    test('renders STRUCTURED HANDOFF section when previous agent provided outputs', () => {
+      // The whole point of v2: the next agent reads structured fields,
+      // not free text. This section is what makes the handoff usable.
+      const prevData = {
+        agentId: 'prev', agentName: 'Researcher',
+        summary: 'Did research',
+        outputs: { findings: { title: 'AI safety' }, citations: 5 },
+      };
+      const result = service.buildFlowAgentContext(baseFlowMetadata, prevData);
+      expect(result).toContain('STRUCTURED HANDOFF');
+      expect(result).toContain('findings');
+      expect(result).toContain('citations');
+      // Number values are rendered raw (no JSON quoting)
+      expect(result).toContain('= 5');
+    });
+
+    test('does NOT render structured handoff when previous outputs is empty/absent', () => {
+      const prevData = { agentId: 'prev', summary: 'Did stuff' };
+      const result = service.buildFlowAgentContext(baseFlowMetadata, prevData);
+      expect(result).not.toContain('STRUCTURED HANDOFF');
+    });
+
+    test('renders ALL UPSTREAM CONTRIBUTORS when multiple agents fed this node', () => {
+      const prevData = {
+        agentId: 'last', agentName: 'Aggregator',
+        summary: 'Merged',
+        contributors: [
+          { agentId: 'a', agentName: 'Researcher', outputs: { facts: 'x' } },
+          { agentId: 'b', agentName: 'Analyst',    outputs: { trends: 'y' } },
+        ],
+      };
+      const result = service.buildFlowAgentContext(baseFlowMetadata, prevData);
+      expect(result).toContain('ALL UPSTREAM CONTRIBUTORS');
+      expect(result).toContain('Researcher');
+      expect(result).toContain('Analyst');
+      expect(result).toContain('facts');
+      expect(result).toContain('trends');
+    });
+  });
+
+  describe('buildFlowAgentSystemPrompt (Phase 8 — replace mode)', () => {
+    test('returns null when no contract', () => {
+      expect(service.buildFlowAgentSystemPrompt(baseFlowMetadata, null, null)).toBeNull();
+      expect(service.buildFlowAgentSystemPrompt(baseFlowMetadata, null, undefined)).toBeNull();
+    });
+
+    test('returns null when contract has no instructions and no outputs', () => {
+      const contract = { inputs: [{ name: 'x', type: 'text' }], outputs: [], instructions: '' };
+      expect(service.buildFlowAgentSystemPrompt(baseFlowMetadata, null, contract)).toBeNull();
+    });
+
+    test('builds standalone prompt that REPLACES rather than appends', () => {
+      const contract = {
+        inputs:  [{ name: 'topic', type: 'text', required: true, description: 'The topic.' }],
+        outputs: [{ name: 'bullets', type: 'list<text>', description: '3 bullets.', example: ['a','b','c'] }],
+        instructions: 'Produce 3 substantive bullets on the topic.',
+      };
+      const prompt = service.buildFlowAgentSystemPrompt(
+        { ...baseFlowMetadata, flowDescription: 'Summarize topics into bullet lists.' },
+        null,
+        contract,
+      );
+      // The output is a SELF-CONTAINED prompt — does NOT presuppose a
+      // "you are a software developer" base prompt before it.
+      expect(prompt).toContain('You are acting as the "Step A" step (1/3)');
+      expect(prompt).toContain('OVERALL FLOW GOAL');
+      expect(prompt).toContain('YOUR ROLE FOR THIS STEP');
+      expect(prompt).toContain('Produce 3 substantive bullets');
+      expect(prompt).toContain('REQUIRED OUTPUTS');
+      expect(prompt).toContain('bullets');
+      expect(prompt).toContain('list<text>');
+      // Strict completion guidance — phrased as "DO NOT:" + bullet list
+      expect(prompt).toMatch(/DO NOT/);
+      expect(prompt).toMatch(/Maintain or update task lists/i);
+      expect(prompt).toMatch(/Write status paragraphs/i);
+      // Concrete example block
+      expect(prompt).toContain('"toolId": "jobdone"');
+      expect(prompt).toContain('"action": "complete"');
+    });
+
+    test('renders previous agent\'s structured outputs in upstream context', () => {
+      const contract = {
+        inputs:  [{ name: 'findings', type: 'json', required: true }],
+        outputs: [{ name: 'draft', type: 'text' }],
+        instructions: 'Write an article using the findings.',
+      };
+      const prevData = {
+        agentId: 'r', agentName: 'Researcher',
+        summary: 'Did research',
+        outputs: { findings: { title: 'AI safety', citations: ['Bostrom 2014'] } },
+      };
+      const prompt = service.buildFlowAgentSystemPrompt(baseFlowMetadata, prevData, contract);
+      expect(prompt).toContain('UPSTREAM CONTEXT');
+      expect(prompt).toContain('Researcher');
+      expect(prompt).toContain('AI safety');
+      expect(prompt).toContain('Bostrom 2014');
+    });
+
+    test('builds prompt for first-step (no previous agent)', () => {
+      const contract = {
+        outputs: [{ name: 'topic', type: 'text' }],
+        instructions: 'Identify the topic.',
+      };
+      const prompt = service.buildFlowAgentSystemPrompt(baseFlowMetadata, null, contract);
+      expect(prompt).toContain('FIRST step');
+    });
+  });
+
+  describe('_formatStructuredValue', () => {
+    test('strings get quoted inline when short', () => {
+      expect(service._formatStructuredValue('hi')).toBe('"hi"');
+    });
+
+    test('multi-line strings get triple-quoted block', () => {
+      const v = 'line1\nline2\nline3';
+      const result = service._formatStructuredValue(v);
+      expect(result).toContain('"""');
+      expect(result).toContain('line1');
+    });
+
+    test('numbers and booleans render as raw values', () => {
+      expect(service._formatStructuredValue(42)).toBe('42');
+      expect(service._formatStructuredValue(true)).toBe('true');
+    });
+
+    test('arrays of strings render compactly when short', () => {
+      expect(service._formatStructuredValue(['a', 'b'])).toBe('["a", "b"]');
+    });
+
+    test('objects render as pretty JSON', () => {
+      const result = service._formatStructuredValue({ a: 1, b: 'two' });
+      expect(result).toContain('"a"');
+      expect(result).toContain('1');
+    });
+
+    test('null/undefined return literal labels', () => {
+      expect(service._formatStructuredValue(null)).toBe('null');
+      expect(service._formatStructuredValue(undefined)).toBe('undefined');
+    });
+
+    test('long values are truncated', () => {
+      const huge = 'x'.repeat(5000);
+      const result = service._formatStructuredValue(huge);
+      expect(result.length).toBeLessThan(2000);
+      expect(result).toContain('truncated');
+    });
   });
 
   describe('_formatPreviousOutput', () => {
@@ -155,6 +478,74 @@ describe('FlowContextService', () => {
       });
       expect(result.valid).toBe(true);
     });
+
+    // -- Phase 1.5: structured-output validation against nodeContract --
+
+    test('validates jobDone.outputs against nodeContract — happy path', () => {
+      const nodeContract = {
+        outputs: [
+          { name: 'draft',     type: 'text' },
+          { name: 'wordCount', type: 'number' },
+        ],
+      };
+      // Summary intentionally avoids file-mention keywords ("created",
+      // "wrote", etc.) so the v1 file-path heuristic stays quiet and we
+      // can isolate the v2 outputs-contract behavior.
+      const result = service.validateJobDoneForFlow({
+        summary: 'Produced a thorough analysis of the topic with full coverage',
+        outputs: { draft: 'Long draft text', wordCount: 850 },
+      }, nodeContract);
+      expect(result.valid).toBe(true);
+      expect(result.missingOutputs).toEqual([]);
+    });
+
+    test('reports missing required output fields', () => {
+      const nodeContract = {
+        outputs: [
+          { name: 'draft',     type: 'text' },
+          { name: 'wordCount', type: 'number' },
+          { name: 'sources',   type: 'file[]' },
+        ],
+      };
+      const result = service.validateJobDoneForFlow({
+        summary: 'Wrote a thorough draft of the article on AI safety',
+        outputs: { draft: 'text only' },              // missing wordCount + sources
+      }, nodeContract);
+      expect(result.valid).toBe(false);
+      expect(result.missingOutputs).toEqual(expect.arrayContaining(['wordCount', 'sources']));
+    });
+
+    test('reports type mismatch on declared output', () => {
+      const nodeContract = {
+        outputs: [{ name: 'wordCount', type: 'number' }],
+      };
+      const result = service.validateJobDoneForFlow({
+        summary: 'Wrote a thorough draft of the article on AI safety',
+        outputs: { wordCount: 'not a number' },
+      }, nodeContract);
+      expect(result.valid).toBe(false);
+      expect(result.warnings.some(w => /wordCount.*number|type/i.test(w))).toBe(true);
+    });
+
+    test('treats missing outputs object as missing all required fields', () => {
+      const nodeContract = {
+        outputs: [{ name: 'draft', type: 'text' }],
+      };
+      const result = service.validateJobDoneForFlow({
+        summary: 'Wrote a thorough draft of the article on AI safety',
+        // no outputs at all
+      }, nodeContract);
+      expect(result.valid).toBe(false);
+      expect(result.missingOutputs).toContain('draft');
+    });
+
+    test('without nodeContract → no outputs field validation (v1 compat)', () => {
+      const result = service.validateJobDoneForFlow({
+        summary: 'Wrote a thorough draft of the article on AI safety',
+        details: 'some details',
+      });
+      expect(result.missingOutputs).toBeUndefined();
+    });
   });
 
   describe('extractFilePaths', () => {