onbuzz 4.4.0 → 4.6.0

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', () => {

package/src/services/apiKeyManager.js

@@ -17,6 +17,7 @@ import path from 'path';
 import crypto from 'crypto';
 import os from 'os';
 import { getUserDataPaths, ensureUserDataDirs } from '../utilities/userDataDir.js';
+import { isPlaceholderApiKey } from '../utilities/apiKeyPlaceholders.js';
 
 // Encryption configuration
 const ALGORITHM = 'aes-256-gcm';
@@ -219,6 +220,32 @@ class ApiKeyManager {
         this.keys = data.globalKeys;
       }
 
+      // Scrub any UI placeholder strings that a buggy older build may
+      // have written to disk before the API-key sanitiser was added.
+      // Without this, a poisoned persist file keeps 401-ing every agent
+      // request even after the UI fix is deployed.
+      let scrubbed = false;
+      if (isPlaceholderApiKey(this.keys?.loxiaApiKey)) {
+        this.logger?.warn('[ApiKeyManager] Scrubbing placeholder loxiaApiKey from persisted store');
+        this.keys.loxiaApiKey = null;
+        scrubbed = true;
+      }
+      if (this.keys?.vendorKeys && typeof this.keys.vendorKeys === 'object') {
+        for (const k of Object.keys(this.keys.vendorKeys)) {
+          if (isPlaceholderApiKey(this.keys.vendorKeys[k])) {
+            this.logger?.warn(`[ApiKeyManager] Scrubbing placeholder vendor key: ${k}`);
+            delete this.keys.vendorKeys[k];
+            scrubbed = true;
+          }
+        }
+      }
+      if (scrubbed) {
+        // Best-effort re-persist so the scrub takes effect on the next
+        // boot too. Failures here aren't fatal — we already have clean
+        // in-memory state.
+        try { await this.persist(); } catch { /* ok */ }
+      }
+
       this.logger?.info('[ApiKeyManager] Loaded persisted keys', {
         hasLoxiaKey: !!this.keys.loxiaApiKey,
         vendorKeys: Object.keys(this.keys.vendorKeys || {}),
@@ -236,7 +263,17 @@ class ApiKeyManager {
   }
 
   /**
-   * Set API keys (sessionId parameter kept for API compatibility but ignored)
+   * Set API keys (sessionId parameter kept for API compatibility but ignored).
+   *
+   * Defense-in-depth: reject UI placeholder strings on the way in. Earlier
+   * the frontend wrote display-only placeholders like
+   * `lx_••••••••••••••••(server-managed)` and the `platform-managed`
+   * sentinel into the editable settings field, then auto-save echoed them
+   * back here — overwriting the real key with the literal placeholder and
+   * 401-ing every subsequent agent request. The frontend has been fixed
+   * to never write those values, but this guard makes sure a regression
+   * (or a third-party UI hitting this endpoint) can't repeat the bug.
+   *
    * @param {string} sessionId - Ignored, kept for API compatibility
    * @param {Object} keys - API keys object
    * @param {string} keys.loxiaApiKey - Loxia platform API key
@@ -244,10 +281,24 @@ class ApiKeyManager {
    */
   async setSessionKeys(sessionId, keys) {
     if (keys.loxiaApiKey) {
-      this.keys.loxiaApiKey = keys.loxiaApiKey;
+      if (isPlaceholderApiKey(keys.loxiaApiKey)) {
+        this.logger?.warn('[ApiKeyManager] Refusing to store placeholder string as Loxia API key — keeping existing key', {
+          received: keys.loxiaApiKey.slice(0, 16) + '…'
+        });
+      } else {
+        this.keys.loxiaApiKey = keys.loxiaApiKey;
+      }
     }
     if (keys.vendorKeys) {
-      this.keys.vendorKeys = { ...this.keys.vendorKeys, ...keys.vendorKeys };
+      const cleanVendor = {};
+      for (const [vendor, value] of Object.entries(keys.vendorKeys)) {
+        if (isPlaceholderApiKey(value)) {
+          this.logger?.warn(`[ApiKeyManager] Refusing to store placeholder for vendor ${vendor} — keeping existing key`);
+          continue;
+        }
+        cleanVendor[vendor] = value;
+      }
+      this.keys.vendorKeys = { ...this.keys.vendorKeys, ...cleanVendor };
     }
 
     this.logger?.info('[ApiKeyManager] API keys updated', {

package/src/services/contextInjectionService.js

@@ -263,6 +263,30 @@ class ContextInjectionService {
       return '';
     }
   }
+
+  /**
+   * Build a "Current local time" line to prepend to the per-turn system
+   * prompt. Re-evaluated on every turn so the agent always sees the time
+   * the model is actually answering at, not the time the agent was created.
+   *
+   * Format: "Current local time: hh:mm dd/mm/yyyy" — fixed, one line.
+   * Locale-independent because LLMs do not need surprises across locales:
+   * agents reasoning about "now is past 17:00, schedule for tomorrow" should
+   * get the same shape regardless of where the host runs.
+   *
+   * @param {Date} [now] override for tests
+   * @returns {string} Empty string if `now` is not a valid Date.
+   */
+  buildCurrentTimeContext(now = new Date()) {
+    if (!(now instanceof Date) || Number.isNaN(now.getTime())) return '';
+    const pad = (n) => String(n).padStart(2, '0');
+    const hh = pad(now.getHours());
+    const mm = pad(now.getMinutes());
+    const dd = pad(now.getDate());
+    const mo = pad(now.getMonth() + 1);
+    const yy = now.getFullYear();
+    return `\n\nCurrent local time: ${hh}:${mm} ${dd}/${mo}/${yy}`;
+  }
 }
 
 export default ContextInjectionService;