onbuzz 4.5.0 → 4.6.0

package/src/core/__tests__/flowMigration.test.js

@@ -0,0 +1,160 @@
+/**
+ * flowMigration — legacy v1 → v2 auto-wrap.
+ *
+ * Existing flows on disk have no typed I/O and edges with no field mapping.
+ * Rather than force a hard migration, the executor wraps legacy flows on
+ * load: each node gets a single implicit `context: text` input and a
+ * single implicit `result: text` output; each edge gets the obvious
+ * field mapping. That keeps day-1 v2 reads of v1 data identical to v1
+ * behavior, and lets users opt into typing on a flow-by-flow basis.
+ *
+ * Invariants tested:
+ *   - already-v2 flows pass through unchanged (idempotent)
+ *   - v1 flow gets defaulted inputs/outputs/edge mappings
+ *   - edge mapping picks defensible defaults that match v1 semantics
+ *   - `isV2Flow` detects v2 by structural signal (typed inputs/outputs)
+ */
+
+import { describe, test, expect } from '@jest/globals';
+import { isV2Flow, migrateLegacyFlow } from '../flowMigration.js';
+
+const v1Flow = () => ({
+  id: 'flow-1', name: 'Legacy',
+  nodes: [
+    { id: 'in',  type: 'input',  data: { promptTemplate: '{{userInput}}' } },
+    { id: 'ag',  type: 'agent',  data: { agentId: 'writer' } },
+    { id: 'out', type: 'output', data: { outputFormat: 'text' } },
+  ],
+  edges: [
+    { source: 'in', target: 'ag' },
+    { source: 'ag', target: 'out' },
+  ],
+});
+
+const v2Flow = () => ({
+  id: 'flow-2', name: 'Already v2', schemaVersion: 2,
+  nodes: [
+    { id: 'in', type: 'input', data: {},
+      inputs: [], outputs: [{ name: 'result', type: 'text' }] },
+    { id: 'ag', type: 'agent', data: { agentId: 'writer' },
+      inputs: [{ name: 'context', type: 'text', required: true }],
+      outputs: [{ name: 'result', type: 'text' }] },
+  ],
+  edges: [
+    { source: 'in', sourceField: 'result', target: 'ag', targetField: 'context' },
+  ],
+});
+
+describe('isV2Flow detection', () => {
+  test('v1 flow → false', () => {
+    expect(isV2Flow(v1Flow())).toBe(false);
+  });
+
+  test('v2 flow with schemaVersion → true', () => {
+    expect(isV2Flow(v2Flow())).toBe(true);
+  });
+
+  test('v1 flow with at least one typed node → true (treat as v2)', () => {
+    const f = v1Flow();
+    f.nodes[1].outputs = [{ name: 'result', type: 'text' }];
+    expect(isV2Flow(f)).toBe(true);
+  });
+
+  test('null/undefined → false (defensive)', () => {
+    expect(isV2Flow(null)).toBe(false);
+    expect(isV2Flow(undefined)).toBe(false);
+    expect(isV2Flow({})).toBe(false);
+  });
+});
+
+describe('migrateLegacyFlow — already-v2 passthrough', () => {
+  test('returns the same object reference (no-op)', () => {
+    const f = v2Flow();
+    const out = migrateLegacyFlow(f);
+    expect(out).toBe(f);
+  });
+});
+
+describe('migrateLegacyFlow — v1 → v2', () => {
+  test('every node gets default inputs/outputs', () => {
+    const out = migrateLegacyFlow(v1Flow());
+    for (const node of out.nodes) {
+      expect(Array.isArray(node.inputs)).toBe(true);
+      expect(Array.isArray(node.outputs)).toBe(true);
+    }
+  });
+
+  test('input node has no inputs and one text output named "result"', () => {
+    const out = migrateLegacyFlow(v1Flow());
+    const inNode = out.nodes.find(n => n.id === 'in');
+    expect(inNode.inputs).toEqual([]);
+    expect(inNode.outputs).toEqual([{ name: 'result', type: 'text' }]);
+  });
+
+  test('agent node has one text "context" input and one text "result" output', () => {
+    const out = migrateLegacyFlow(v1Flow());
+    const ag = out.nodes.find(n => n.id === 'ag');
+    expect(ag.inputs).toEqual([{ name: 'context', type: 'text', required: true }]);
+    expect(ag.outputs).toEqual([{ name: 'result', type: 'text' }]);
+  });
+
+  test('output node has one text "context" input and no outputs', () => {
+    const out = migrateLegacyFlow(v1Flow());
+    const o = out.nodes.find(n => n.id === 'out');
+    expect(o.inputs).toEqual([{ name: 'context', type: 'text', required: true }]);
+    expect(o.outputs).toEqual([]);
+  });
+
+  test('every edge gets sourceField="result" and targetField="context"', () => {
+    const out = migrateLegacyFlow(v1Flow());
+    for (const edge of out.edges) {
+      expect(edge.sourceField).toBe('result');
+      expect(edge.targetField).toBe('context');
+    }
+  });
+
+  test('migrated flow is marked schemaVersion: 2', () => {
+    const out = migrateLegacyFlow(v1Flow());
+    expect(out.schemaVersion).toBe(2);
+  });
+
+  test('migration does not mutate the input flow', () => {
+    const f = v1Flow();
+    const snapshot = JSON.parse(JSON.stringify(f));
+    migrateLegacyFlow(f);
+    expect(f).toEqual(snapshot);
+  });
+
+  test('preserves existing data (label, agentId, promptTemplate, etc.)', () => {
+    const out = migrateLegacyFlow(v1Flow());
+    expect(out.nodes.find(n => n.id === 'ag').data.agentId).toBe('writer');
+    expect(out.nodes.find(n => n.id === 'in').data.promptTemplate).toBe('{{userInput}}');
+  });
+
+  test('handles flow with no edges (single node) without throwing', () => {
+    const f = { id: 'solo', name: 'Solo', nodes: [{ id: 'a', type: 'input', data: {} }], edges: [] };
+    const out = migrateLegacyFlow(f);
+    expect(out.schemaVersion).toBe(2);
+    expect(out.nodes[0].inputs).toEqual([]);
+    expect(out.nodes[0].outputs).toEqual([{ name: 'result', type: 'text' }]);
+    expect(out.edges).toEqual([]);
+  });
+
+  test('idempotent: migrating an already-migrated flow is a no-op', () => {
+    const once  = migrateLegacyFlow(v1Flow());
+    const twice = migrateLegacyFlow(once);
+    expect(twice).toBe(once);
+  });
+});
+
+describe('migrateLegacyFlow — defensive', () => {
+  test('null/undefined returns input as-is (caller decides)', () => {
+    expect(migrateLegacyFlow(null)).toBe(null);
+    expect(migrateLegacyFlow(undefined)).toBe(undefined);
+  });
+
+  test('flow without nodes array returns input unchanged', () => {
+    const broken = { name: 'broken' };
+    expect(migrateLegacyFlow(broken)).toBe(broken);
+  });
+});

package/src/core/__tests__/flowRetry.test.js

@@ -0,0 +1,145 @@
+/**
+ * flowRetry — runs a node-attempt function with timeout + retry.
+ *
+ * Why pull this out: retry semantics and exponential backoff have a lot
+ * of edge cases (max attempts, retry-only-on-timeout, attempt-count
+ * tracking, onAttempt callbacks for observability). Embedding all of
+ * this in executeAgentNode would bury the logic; isolating it keeps
+ * the executor short and lets us hammer the retry rules in tests.
+ *
+ * Contract:
+ *   runWithRetry(attemptFn, opts) → { result, attempts: [...] }
+ *
+ *   - attemptFn(attemptIndex) returns a promise
+ *   - opts.timeoutMs            per-attempt timeout (default 5min)
+ *   - opts.maxRetries           additional tries beyond the first (default 0)
+ *   - opts.retryOn              which errors trigger retry (default ['timeout','agent-error'])
+ *   - opts.backoffBaseMs        base delay (default 1000)
+ *   - opts.backoffMultiplier    exponential factor (default 2)
+ *   - opts.onAttempt(meta)      called with { attempt, error?, willRetry } between attempts
+ *
+ * Errors throw with a `.kind` field that retryOn can match. attemptFn
+ * may also throw plain errors — those classified as 'agent-error'.
+ */
+
+import { jest, describe, test, expect } from '@jest/globals';
+import { runWithRetry, FlowRetryError } from '../flowRetry.js';
+
+describe('runWithRetry — happy path', () => {
+  test('returns result on first success without retrying', async () => {
+    const fn = jest.fn().mockResolvedValue('ok');
+    const r = await runWithRetry(fn, { maxRetries: 3, timeoutMs: 1000 });
+    expect(r.result).toBe('ok');
+    expect(r.attempts).toHaveLength(1);
+    expect(r.attempts[0].error).toBeUndefined();
+  });
+
+  test('passes the attempt index (0-based) to attemptFn', async () => {
+    const fn = jest.fn().mockResolvedValue('ok');
+    await runWithRetry(fn, { maxRetries: 2, timeoutMs: 500 });
+    expect(fn).toHaveBeenCalledWith(0);
+  });
+});
+
+describe('runWithRetry — timeout', () => {
+  test('throws timeout when attemptFn exceeds timeoutMs (no retries)', async () => {
+    const fn = () => new Promise(() => {});  // never resolves
+    await expect(runWithRetry(fn, { maxRetries: 0, timeoutMs: 50 }))
+      .rejects.toMatchObject({ kind: 'timeout' });
+  });
+
+  test('retries on timeout up to maxRetries, then succeeds', async () => {
+    let calls = 0;
+    const fn = () => new Promise((resolve) => {
+      calls++;
+      if (calls < 3) return; // first 2 hang
+      resolve('eventually');
+    });
+    const r = await runWithRetry(fn, {
+      maxRetries: 3, timeoutMs: 30, backoffBaseMs: 1, backoffMultiplier: 1,
+    });
+    expect(r.result).toBe('eventually');
+    expect(r.attempts).toHaveLength(3);
+    expect(r.attempts[0].error.kind).toBe('timeout');
+    expect(r.attempts[1].error.kind).toBe('timeout');
+    expect(r.attempts[2].error).toBeUndefined();
+  });
+
+  test('exhausts retries on persistent timeout', async () => {
+    const fn = () => new Promise(() => {});
+    await expect(runWithRetry(fn, {
+      maxRetries: 2, timeoutMs: 20, backoffBaseMs: 1, backoffMultiplier: 1,
+    })).rejects.toMatchObject({ kind: 'timeout' });
+  });
+});
+
+describe('runWithRetry — agent-error', () => {
+  test('retries on plain thrown errors (classified as agent-error)', async () => {
+    let calls = 0;
+    const fn = () => {
+      calls++;
+      if (calls < 2) throw new Error('boom');
+      return Promise.resolve('ok');
+    };
+    const r = await runWithRetry(fn, {
+      maxRetries: 2, timeoutMs: 500, backoffBaseMs: 1, backoffMultiplier: 1,
+    });
+    expect(r.result).toBe('ok');
+    expect(r.attempts).toHaveLength(2);
+    expect(r.attempts[0].error.kind).toBe('agent-error');
+    expect(r.attempts[0].error.message).toBe('boom');
+  });
+
+  test('does NOT retry when retryOn excludes agent-error', async () => {
+    const fn = jest.fn().mockRejectedValue(new Error('boom'));
+    await expect(runWithRetry(fn, {
+      maxRetries: 5, timeoutMs: 500, retryOn: ['timeout'],
+      backoffBaseMs: 1, backoffMultiplier: 1,
+    })).rejects.toThrow('boom');
+    expect(fn).toHaveBeenCalledTimes(1);
+  });
+
+  test('preserves the kind on FlowRetryError when fed back through', async () => {
+    const fn = () => Promise.reject(new FlowRetryError('explicit', 'agent-failure'));
+    await expect(runWithRetry(fn, {
+      maxRetries: 0, timeoutMs: 100, retryOn: ['timeout'],
+    })).rejects.toMatchObject({ kind: 'agent-failure', message: 'explicit' });
+  });
+});
+
+describe('runWithRetry — backoff timing', () => {
+  test('waits backoffBaseMs * multiplier^attempt between retries', async () => {
+    const onAttempt = jest.fn();
+    let calls = 0;
+    const fn = () => {
+      calls++;
+      if (calls < 3) throw new Error('fail');
+      return Promise.resolve('ok');
+    };
+    const t0 = Date.now();
+    await runWithRetry(fn, {
+      maxRetries: 3, timeoutMs: 200,
+      backoffBaseMs: 30, backoffMultiplier: 2,
+      onAttempt,
+    });
+    const elapsed = Date.now() - t0;
+    // Backoffs: after attempt 0 (failed) wait ~30ms, after 1 (failed) wait ~60ms.
+    // Total ≥ 90ms, allow generous slack for CI.
+    expect(elapsed).toBeGreaterThanOrEqual(80);
+    expect(onAttempt).toHaveBeenCalledTimes(2); // only "between" attempts (not the final success)
+  });
+});
+
+describe('runWithRetry — defensive', () => {
+  test('maxRetries=0 means exactly one attempt', async () => {
+    const fn = jest.fn().mockRejectedValue(new Error('one shot'));
+    await expect(runWithRetry(fn, { maxRetries: 0, timeoutMs: 100 }))
+      .rejects.toThrow('one shot');
+    expect(fn).toHaveBeenCalledTimes(1);
+  });
+
+  test('non-function attemptFn throws synchronously', async () => {
+    await expect(runWithRetry(null)).rejects.toThrow();
+    await expect(runWithRetry('nope')).rejects.toThrow();
+  });
+});

package/src/core/__tests__/flowSavePayload.test.js

@@ -0,0 +1,169 @@
+/**
+ * UI → Server save-payload round-trip tests.
+ *
+ * Why this file exists: my unit tests built clean fixtures and ran them
+ * through the validator. The actual EDITOR wraps nodes through ReactFlow,
+ * which augments them with runtime state (selected, dragging, dimensions,
+ * positionAbsolute) AND we (FlowCanvas) inject UI-only data fields
+ * (executionStatus, lintWarnings, declaredInputs, declaredOutputs).
+ * On save, that augmented mess gets sent to PUT /api/flows/:id.
+ *
+ * These tests simulate that pollution and verify two things:
+ *   1. The sanitize-on-save logic in FlowEditor strips ALL the noise
+ *      (so the persisted flow stays clean across save round-trips).
+ *   2. After sanitization, every starter template still validates.
+ *
+ * Without this, the next change to FlowCanvas's data injection could
+ * silently re-introduce the same class of "save fails with HTTP 400"
+ * bug we just shipped a fix for.
+ */
+
+import { describe, test, expect } from '@jest/globals';
+import { validateFlowDefinition } from '../flowSchema.js';
+import { STARTER_TEMPLATES } from '../../../web-ui/src/utils/flowTemplates.js';
+
+/**
+ * Mirror of FlowEditor.sanitizeNodesForSave — kept identical so this
+ * test suite locks the contract. If the UI sanitizer drifts, both
+ * places must update together.
+ */
+function sanitizeNodesForSave(rawNodes) {
+  return (rawNodes || []).map(n => {
+    const { selected, dragging, width, height, positionAbsolute, ...keptTop } = n;
+    const data = { ...(n.data || {}) };
+    delete data.executionStatus;
+    delete data.lintWarnings;
+    delete data.declaredInputs;
+    delete data.declaredOutputs;
+    delete data.charactersStreamed;
+    return { ...keptTop, data };
+  });
+}
+
+/**
+ * Pollute a clean node with the same augmentations the live UI adds:
+ *   - data.executionStatus, data.lintWarnings (from FlowCanvas useMemo)
+ *   - data.declaredInputs, data.declaredOutputs (Phase 5 surfacing)
+ *   - data.charactersStreamed (streaming progress)
+ *   - selected, dragging, width, height, positionAbsolute (ReactFlow internal)
+ */
+function pollute(node) {
+  return {
+    ...node,
+    selected: false,
+    dragging: false,
+    width: 220,
+    height: 96,
+    positionAbsolute: { ...(node.position || { x: 0, y: 0 }) },
+    data: {
+      ...(node.data || {}),
+      executionStatus: 'completed',
+      lintWarnings: [{ kind: 'unbound-agent', message: '...' }],
+      declaredInputs:  Array.isArray(node.inputs)  ? node.inputs  : null,
+      declaredOutputs: Array.isArray(node.outputs) ? node.outputs : null,
+      charactersStreamed: 1234,
+    },
+  };
+}
+
+describe('save payload round-trip', () => {
+  test('sanitizer removes every UI-only data field', () => {
+    const polluted = pollute({
+      id: 'n', type: 'agent', position: { x: 0, y: 0 },
+      data: { agentId: 'a', label: 'A', promptTemplate: '{{x}}' },
+      inputs: [{ name: 'x', type: 'text', required: true }],
+      outputs: [{ name: 'y', type: 'text' }],
+    });
+    // Sanity: pollution actually happened
+    expect(polluted.data.executionStatus).toBe('completed');
+    expect(polluted.selected).toBe(false);
+    expect(polluted.width).toBe(220);
+
+    const [clean] = sanitizeNodesForSave([polluted]);
+
+    // Runtime data fields stripped
+    expect(clean.data.executionStatus).toBeUndefined();
+    expect(clean.data.lintWarnings).toBeUndefined();
+    expect(clean.data.declaredInputs).toBeUndefined();
+    expect(clean.data.declaredOutputs).toBeUndefined();
+    expect(clean.data.charactersStreamed).toBeUndefined();
+    // ReactFlow internal flags stripped
+    expect(clean.selected).toBeUndefined();
+    expect(clean.dragging).toBeUndefined();
+    expect(clean.width).toBeUndefined();
+    expect(clean.height).toBeUndefined();
+    expect(clean.positionAbsolute).toBeUndefined();
+    // User-authored data preserved
+    expect(clean.data.agentId).toBe('a');
+    expect(clean.data.label).toBe('A');
+    expect(clean.data.promptTemplate).toBe('{{x}}');
+    expect(clean.inputs).toEqual([{ name: 'x', type: 'text', required: true }]);
+    expect(clean.outputs).toEqual([{ name: 'y', type: 'text' }]);
+    expect(clean.position).toEqual({ x: 0, y: 0 });
+  });
+
+  test('sanitizer is idempotent (saving twice produces same shape)', () => {
+    const polluted = pollute({
+      id: 'n', type: 'agent', position: { x: 5, y: 10 },
+      data: { agentId: 'a' },
+      inputs: [], outputs: [{ name: 'y', type: 'text' }],
+    });
+    const once  = sanitizeNodesForSave([polluted]);
+    const twice = sanitizeNodesForSave(once);
+    expect(twice).toEqual(once);
+  });
+
+  test('sanitizer handles null/undefined nodes gracefully', () => {
+    expect(sanitizeNodesForSave(null)).toEqual([]);
+    expect(sanitizeNodesForSave(undefined)).toEqual([]);
+    expect(sanitizeNodesForSave([])).toEqual([]);
+  });
+});
+
+describe('every starter template survives a polluted save round-trip', () => {
+  // The actual bug the user hit: load a template → canvas injects
+  // runtime fields → user clicks save → server PUT validates the
+  // augmented payload. This test reproduces that path end-to-end
+  // for every template. If any new template ships with a shape that
+  // the canvas augmentation breaks, this fails loud.
+  for (const t of STARTER_TEMPLATES) {
+    test(`"${t.key}" round-trips clean → polluted → sanitized → validated`, () => {
+      // Mimic what the editor sends to PUT /api/flows/:id:
+      const polluted = t.flow.nodes.map(pollute);
+      const sanitized = sanitizeNodesForSave(polluted);
+
+      // Reassemble the flow exactly as the PUT route's merge step
+      // would: existing template + nodes/edges from the editor.
+      const asUserSaves = {
+        ...t.flow,
+        nodes: sanitized,
+        edges: t.flow.edges,
+      };
+
+      const result = validateFlowDefinition(asUserSaves);
+      if (!result.ok) {
+        // eslint-disable-next-line no-console
+        console.error(`Save round-trip for "${t.key}" failed validation:`, result.errors);
+      }
+      expect(result.ok).toBe(true);
+    });
+  }
+
+  test('UNSANITIZED polluted save would have failed if validator tightened (regression evidence)', () => {
+    // This documents WHY sanitization matters. Today the validator
+    // accepts unknown fields silently — so a polluted save would
+    // technically validate. But ReactFlow's `selected`/`dragging`
+    // booleans and dimensions clutter the on-disk record and grow on
+    // every round-trip. Sanitization is the contract.
+    const polluted = STARTER_TEMPLATES[0].flow.nodes.map(pollute);
+    // Confirm the pollution is observable
+    expect(polluted[0].data.executionStatus).toBeDefined();
+    expect(polluted[0].selected).toBeDefined();
+    // After sanitize, none of those leak through
+    const clean = sanitizeNodesForSave(polluted);
+    for (const n of clean) {
+      expect(n.data.executionStatus).toBeUndefined();
+      expect(n.selected).toBeUndefined();
+    }
+  });
+});