onbuzz 4.5.0 → 4.6.1

package/src/core/flowSchema.js

@@ -0,0 +1,297 @@
+/**
+ * flowSchema — pure-JS validator for flow definitions.
+ *
+ * The gate: anything posted to /api/flows or executed by FlowExecutor
+ * runs through this first. If it fails, the user gets specific errors
+ * BEFORE waiting 90s for a runtime crash.
+ *
+ * Why hand-rolled (not Ajv): we want path-precise error messages
+ * (e.g. "nodes[1].data.agentId is required") and we want the validator
+ * to do graph-shape checks (cycles, edge endpoints) that Ajv can't
+ * express in JSONSchema. ~150 LoC, zero runtime deps.
+ *
+ * Returns: { ok: boolean, errors: Array<{ path?: string, message: string }> }
+ *
+ * Optional `agentResolver(agentId): boolean` lets callers verify that
+ * agent IDs referenced in agent-typed nodes actually exist in the pool.
+ * Without it, presence/non-empty checks still run but existence isn't
+ * verified — useful for client-side editor validation before save.
+ */
+
+import { isKnownType, isCompatible, describeCompat } from './flowTypes.js';
+import { isV2Flow } from './flowMigration.js';
+
+const NODE_TYPES = new Set(['input', 'agent', 'output']);
+
+/**
+ * @param {object} flow
+ * @param {object} [opts]
+ * @param {(agentId: string) => boolean} [opts.agentResolver]
+ * @returns {{ ok: boolean, errors: Array<{ path?: string, message: string }> }}
+ */
+export function validateFlowDefinition(flow, opts = {}) {
+  const errors = [];
+  const push = (message, path) => errors.push(path ? { path, message } : { message });
+
+  // --- root shape ---------------------------------------------------------
+  if (flow === null || typeof flow !== 'object' || Array.isArray(flow)) {
+    push('flow must be an object');
+    return { ok: false, errors };
+  }
+
+  if (typeof flow.name !== 'string' || flow.name.trim().length === 0) {
+    push('name is required and must be a non-empty string', 'name');
+  }
+
+  if (!Array.isArray(flow.nodes)) {
+    push('nodes must be an array', 'nodes');
+    // can't continue without nodes — return early
+    return { ok: false, errors };
+  }
+
+  if (flow.edges !== undefined && !Array.isArray(flow.edges)) {
+    push('edges must be an array when present', 'edges');
+    return { ok: false, errors };
+  }
+
+  const edges = flow.edges || [];
+
+  // --- node validation ---------------------------------------------------
+  const seenIds = new Set();
+  const nodeIds = new Set();              // populated only for valid-shape nodes
+  for (let i = 0; i < flow.nodes.length; i++) {
+    const node = flow.nodes[i];
+    const path = `nodes[${i}]`;
+    if (node === null || typeof node !== 'object') {
+      push('node must be an object', path);
+      continue;
+    }
+    if (typeof node.id !== 'string' || node.id.trim().length === 0) {
+      push('node.id is required and must be a non-empty string', `${path}.id`);
+      continue;
+    }
+    if (seenIds.has(node.id)) {
+      push(`duplicate node id "${node.id}"`, `${path}.id`);
+    } else {
+      seenIds.add(node.id);
+      nodeIds.add(node.id);
+    }
+    if (typeof node.type !== 'string' || !NODE_TYPES.has(node.type)) {
+      push(
+        `node.type must be one of ${[...NODE_TYPES].join(', ')} (got ${JSON.stringify(node.type)})`,
+        `${path}.type`,
+      );
+      continue;
+    }
+    if (node.type === 'agent') {
+      const agentId = node.data?.agentId;
+      // Empty agentId is allowed at SAVE time so users can draft flows
+      // (esp. from templates) and pick agents later. The lint surfaces
+      // empty slots as warnings, and the executor refuses to RUN a flow
+      // with unbound agent slots — separate concerns.
+      if (agentId !== undefined && agentId !== null && typeof agentId !== 'string') {
+        push(`agent node "${node.id}" data.agentId must be a string`, `${path}.data.agentId`);
+      } else if (typeof agentId === 'string' && agentId.trim().length > 0 && typeof opts.agentResolver === 'function') {
+        try {
+          if (!opts.agentResolver(agentId)) {
+            push(`agent "${agentId}" not found (referenced by node "${node.id}")`, `${path}.data.agentId`);
+          }
+        } catch (e) {
+          // Resolver threw — treat as not-found but include the cause
+          push(`agent resolver failed for "${agentId}": ${e?.message || e}`, `${path}.data.agentId`);
+        }
+      }
+    }
+  }
+
+  // --- edge validation ---------------------------------------------------
+  for (let i = 0; i < edges.length; i++) {
+    const edge = edges[i];
+    const path = `edges[${i}]`;
+    if (edge === null || typeof edge !== 'object') {
+      push('edge must be an object', path);
+      continue;
+    }
+    if (typeof edge.source !== 'string' || edge.source.length === 0) {
+      push('edge.source is required', `${path}.source`);
+      continue;
+    }
+    if (typeof edge.target !== 'string' || edge.target.length === 0) {
+      push('edge.target is required', `${path}.target`);
+      continue;
+    }
+    if (edge.source === edge.target) {
+      push(`edge has self-loop on "${edge.source}" (cycle)`, path);
+      continue;
+    }
+    if (!nodeIds.has(edge.source)) {
+      push(`edge.source "${edge.source}" does not match any node id`, `${path}.source`);
+    }
+    if (!nodeIds.has(edge.target)) {
+      push(`edge.target "${edge.target}" does not match any node id`, `${path}.target`);
+    }
+  }
+
+  // --- cycle detection (only if all edges reference real nodes) ---------
+  // We build the adjacency only over edges whose endpoints both resolve;
+  // unresolved-endpoint edges already reported above. Detecting cycles
+  // separately avoids false positives from the broken edges.
+  const adj = new Map();
+  for (const id of nodeIds) adj.set(id, []);
+  for (const edge of edges) {
+    if (!edge || edge.source === edge.target) continue;
+    if (nodeIds.has(edge.source) && nodeIds.has(edge.target)) {
+      adj.get(edge.source).push(edge.target);
+    }
+  }
+
+  // Iterative DFS with WHITE/GRAY/BLACK coloring. GRAY ⇒ back-edge ⇒ cycle.
+  const WHITE = 0, GRAY = 1, BLACK = 2;
+  const color = new Map();
+  for (const id of nodeIds) color.set(id, WHITE);
+  let cycleFound = false;
+  let cycleHint = null;
+
+  for (const start of nodeIds) {
+    if (cycleFound) break;
+    if (color.get(start) !== WHITE) continue;
+    const stack = [{ node: start, idx: 0 }];
+    color.set(start, GRAY);
+    while (stack.length) {
+      const frame = stack[stack.length - 1];
+      const neighbors = adj.get(frame.node);
+      if (frame.idx >= neighbors.length) {
+        color.set(frame.node, BLACK);
+        stack.pop();
+        continue;
+      }
+      const next = neighbors[frame.idx++];
+      const c = color.get(next);
+      if (c === GRAY) {
+        cycleFound = true;
+        cycleHint = `${frame.node} → ${next}`;
+        break;
+      }
+      if (c === WHITE) {
+        color.set(next, GRAY);
+        stack.push({ node: next, idx: 0 });
+      }
+    }
+  }
+
+  if (cycleFound) {
+    push(`flow has a cycle (back edge ${cycleHint}); flows must be acyclic`);
+  }
+
+  // --- v2 typed I/O validation ------------------------------------------
+  // v2 = any node carries typed inputs/outputs OR schemaVersion: 2.
+  // v1 flows skip this entirely (backwards compat).
+  if (isV2Flow(flow)) {
+    validateTypedIO(flow, errors, push);
+  }
+
+  return { ok: errors.length === 0, errors };
+}
+
+/**
+ * Validate inputs/outputs arrays per node and edge field mappings + type
+ * compatibility. Mutates `errors` via the `push` helper passed in.
+ *
+ * Why a separate function: keeps validateFlowDefinition readable and
+ * makes it easy to skip for v1 flows.
+ */
+function validateTypedIO(flow, errors, push) {
+  // Build per-node lookup of declared inputs/outputs by name → type
+  // for fast edge validation.
+  const nodeIO = new Map();   // nodeId → { inputs: Map<name,type>, outputs: Map<name,type> }
+
+  for (let i = 0; i < flow.nodes.length; i++) {
+    const node = flow.nodes[i];
+    if (!node || typeof node !== 'object' || typeof node.id !== 'string') continue;
+    const path = `nodes[${i}]`;
+    const ios = { inputs: new Map(), outputs: new Map() };
+
+    for (const kind of ['inputs', 'outputs']) {
+      const arr = node[kind];
+      if (arr === undefined) continue;       // omit = "no declared fields"; allowed
+      if (!Array.isArray(arr)) {
+        push(`node.${kind} must be an array when present`, `${path}.${kind}`);
+        continue;
+      }
+      for (let j = 0; j < arr.length; j++) {
+        const field = arr[j];
+        const fpath = `${path}.${kind}[${j}]`;
+        if (!field || typeof field !== 'object') {
+          push(`${kind.slice(0, -1)} entry must be an object`, fpath);
+          continue;
+        }
+        if (typeof field.name !== 'string' || field.name.length === 0) {
+          push(`${kind.slice(0, -1)} field name is required`, `${fpath}.name`);
+          continue;
+        }
+        if (!isKnownType(field.type)) {
+          push(
+            `${kind.slice(0, -1)} field "${field.name}" has unknown type ${JSON.stringify(field.type)}`,
+            `${fpath}.type`,
+          );
+          continue;
+        }
+        if (ios[kind].has(field.name)) {
+          push(`duplicate ${kind.slice(0, -1)} field name "${field.name}" on node "${node.id}"`, fpath);
+          continue;
+        }
+        ios[kind].set(field.name, field.type);
+      }
+    }
+    nodeIO.set(node.id, ios);
+  }
+
+  // Edge field mapping validation. An edge in a v2 flow MUST declare
+  // sourceField + targetField. Each must reference a real declared field
+  // on the corresponding node, and the types must be compatible per the
+  // matrix.
+  const edges = flow.edges || [];
+  for (let i = 0; i < edges.length; i++) {
+    const edge = edges[i];
+    if (!edge || typeof edge !== 'object') continue;
+    const path = `edges[${i}]`;
+    const srcIO = nodeIO.get(edge.source);
+    const dstIO = nodeIO.get(edge.target);
+    if (!srcIO || !dstIO) continue;   // already-reported broken endpoint
+
+    if (typeof edge.sourceField !== 'string' || edge.sourceField.length === 0) {
+      push('v2 edge requires sourceField (output name on source node)', `${path}.sourceField`);
+      continue;
+    }
+    if (typeof edge.targetField !== 'string' || edge.targetField.length === 0) {
+      push('v2 edge requires targetField (input name on target node)', `${path}.targetField`);
+      continue;
+    }
+
+    const srcType = srcIO.outputs.get(edge.sourceField);
+    if (srcType === undefined) {
+      push(
+        `edge.sourceField "${edge.sourceField}" is not a declared output of node "${edge.source}"`,
+        `${path}.sourceField`,
+      );
+      continue;
+    }
+    const dstType = dstIO.inputs.get(edge.targetField);
+    if (dstType === undefined) {
+      push(
+        `edge.targetField "${edge.targetField}" is not a declared input of node "${edge.target}"`,
+        `${path}.targetField`,
+      );
+      continue;
+    }
+
+    if (!isCompatible(srcType, dstType)) {
+      push(
+        `edge ${edge.source}.${edge.sourceField} → ${edge.target}.${edge.targetField}: ${describeCompat(srcType, dstType)}`,
+        path,
+      );
+    }
+  }
+}
+
+export default { validateFlowDefinition };

package/src/core/flowTypes.js

@@ -0,0 +1,81 @@
+/**
+ * flowTypes — type registry + compatibility matrix for Flows v2.
+ *
+ * Every node declares typed `inputs` and `outputs`; every edge maps an
+ * output field to an input field. `isCompatible(srcType, dstType)` is
+ * the rule that says "this connection won't surprise you at runtime."
+ *
+ * The matrix is intentionally narrow:
+ *   - exact match always works
+ *   - safe widenings work (any scalar → text/json, file → file[], text → list<text>)
+ *   - everything else needs an explicit cast node (so the user is the one
+ *     deciding what "parse this number" or "read this file" means)
+ *
+ * Editor uses this to refuse incompatible drag-connects. Server-side
+ * schema validator uses it to reject saves. Single source of truth.
+ */
+
+export const TYPES = Object.freeze([
+  'text',
+  'number',
+  'boolean',
+  'json',
+  'file',
+  'file[]',
+  'list<text>',
+]);
+
+const TYPE_SET = new Set(TYPES);
+
+export function isKnownType(t) {
+  return typeof t === 'string' && TYPE_SET.has(t);
+}
+
+/**
+ * Compatibility matrix. Encoded as a Map<from, Set<to>> so additions
+ * are easy to read; exact-match handled separately to keep the data
+ * minimal.
+ *
+ * NOTE: file is intentionally NOT compatible with text/json. Auto-reading
+ * a file is surprising behavior — if the user wants the content, they
+ * should add a "read file" cast/transform node. Conversely, file → file[]
+ * is allowed because "this single file" → "a list with one file" is
+ * unambiguous and the most common pipeline shape.
+ */
+const ALLOWED = new Map([
+  // any scalar / json → text (auto-stringify)
+  ['number',     new Set(['text', 'json'])],
+  ['boolean',    new Set(['text', 'json'])],
+  ['json',       new Set(['text'])],
+  // text widens to json (wraps as a JSON string) and to a 1-element list
+  ['text',       new Set(['json', 'list<text>'])],
+  // file singleton → list-of-files (very common)
+  ['file',       new Set(['file[]'])],
+  // list<text> can wrap as JSON
+  ['list<text>', new Set(['json'])],
+]);
+
+/**
+ * @param {string} from  source output type
+ * @param {string} to    target input type
+ * @returns {boolean}    true iff the connection is allowed without a cast
+ */
+export function isCompatible(from, to) {
+  if (!isKnownType(from) || !isKnownType(to)) return false;
+  if (from === to) return true;
+  return ALLOWED.get(from)?.has(to) === true;
+}
+
+/**
+ * Human-readable explanation for why two types don't connect. Returns
+ * null when they DO connect (caller treats null as "all good"). Used
+ * by editor tooltips and the schema validator's error messages.
+ */
+export function describeCompat(from, to) {
+  if (isCompatible(from, to)) return null;
+  if (!isKnownType(from)) return `unknown source type "${from}"`;
+  if (!isKnownType(to))   return `unknown target type "${to}"`;
+  return `${from} → ${to} requires an explicit cast node (incompatible types)`;
+}
+
+export default { TYPES, isKnownType, isCompatible, describeCompat };

package/src/core/flowVersionStore.js

@@ -0,0 +1,122 @@
+/**
+ * FlowVersionStore — append-only flow version archive.
+ *
+ * Each PUT to a flow records a new immutable snapshot:
+ *   <baseDir>/<safeFlowId>/v-<N>.json   (N monotonically increasing)
+ *
+ * Snapshot file content: { version: N, savedAt: ISO, flow: <full> }
+ *
+ * Pure data layer. Routes decide WHEN to record (on save) and HOW to
+ * roll back (load version + write through stateManager.updateFlow).
+ *
+ * Why not just rely on stateManager.updateFlow's overwrite + a backup
+ * dir? Versioning needs three guarantees:
+ *   1. Monotonic version numbers visible to UI/runs
+ *   2. Immutable snapshots (rollback never edits history)
+ *   3. Independent of stateManager's internal storage choices
+ */
+
+import path from 'path';
+import { promises as fs } from 'fs';
+
+function _safe(s) {
+  return String(s).replace(/[^a-zA-Z0-9_.-]+/g, '_');
+}
+
+function _resolveDir(baseDir, flowId) {
+  if (typeof flowId === 'string' && (flowId.includes('..') || flowId.startsWith('/') || flowId.startsWith('\\'))) {
+    throw new Error(`flowId must not contain ".." or absolute path segments: ${flowId}`);
+  }
+  const dir = path.resolve(baseDir, _safe(flowId));
+  const baseResolved = path.resolve(baseDir);
+  if (!dir.startsWith(baseResolved + path.sep) && dir !== baseResolved) {
+    throw new Error(`flowId resolves outside baseDir: ${flowId}`);
+  }
+  return dir;
+}
+
+async function _writeAtomic(filePath, json) {
+  const tmp = filePath + '.tmp-' + process.pid + '-' + Date.now();
+  await fs.writeFile(tmp, json, 'utf8');
+  await fs.rename(tmp, filePath);
+}
+
+const FILE_RE = /^v-(\d+)\.json$/;
+
+export class FlowVersionStore {
+  constructor({ baseDir }) {
+    if (!baseDir || typeof baseDir !== 'string') {
+      throw new Error('FlowVersionStore requires a string baseDir');
+    }
+    this.baseDir = baseDir;
+  }
+
+  async _nextVersion(dir) {
+    let entries;
+    try { entries = await fs.readdir(dir); }
+    catch (e) {
+      if (e?.code === 'ENOENT') return 1;
+      throw e;
+    }
+    let max = 0;
+    for (const name of entries) {
+      const m = FILE_RE.exec(name);
+      if (m) {
+        const n = parseInt(m[1], 10);
+        if (n > max) max = n;
+      }
+    }
+    return max + 1;
+  }
+
+  async recordVersion(flowId, flow) {
+    const dir = _resolveDir(this.baseDir, flowId);
+    await fs.mkdir(dir, { recursive: true });
+    const version = await this._nextVersion(dir);
+    const savedAt = new Date().toISOString();
+    // Deep-clone to be sure we don't mutate the caller's reference
+    // and that the snapshot is decoupled from later mutations.
+    const snapshot = { version, savedAt, flow: JSON.parse(JSON.stringify(flow)) };
+    await _writeAtomic(path.join(dir, `v-${version}.json`), JSON.stringify(snapshot, null, 2));
+    return { version, savedAt };
+  }
+
+  async listVersions(flowId) {
+    const dir = _resolveDir(this.baseDir, flowId);
+    let entries;
+    try { entries = await fs.readdir(dir); }
+    catch (e) {
+      if (e?.code === 'ENOENT') return [];
+      throw e;
+    }
+    const out = [];
+    for (const name of entries) {
+      const m = FILE_RE.exec(name);
+      if (!m) continue;
+      try {
+        const raw = await fs.readFile(path.join(dir, name), 'utf8');
+        const obj = JSON.parse(raw);
+        out.push({
+          version: obj.version,
+          savedAt: obj.savedAt,
+          name: obj.flow?.name,
+        });
+      } catch { /* skip unreadable */ }
+    }
+    out.sort((a, b) => a.version - b.version);
+    return out;
+  }
+
+  async loadVersion(flowId, version) {
+    const dir = _resolveDir(this.baseDir, flowId);
+    try {
+      const raw = await fs.readFile(path.join(dir, `v-${version}.json`), 'utf8');
+      return JSON.parse(raw);
+    } catch (e) {
+      if (e?.code === 'ENOENT') return null;
+      throw e;
+    }
+  }
+}
+
+export default FlowVersionStore;

package/src/core/messageProcessor.js

@@ -162,7 +162,11 @@ class MessageProcessor {
         flowRunId: context.flowRunId,
         flowNodeId: context.flowNodeId,
         flowMetadata: context.flowMetadata,
-        previousAgentData: context.previousAgentData
+        previousAgentData: context.previousAgentData,
+        // v2: typed I/O contract for this node — { inputs, outputs }.
+        // Forwarded to the scheduler so the system prompt can advertise
+        // the exact named/typed payload the agent must produce.
+        nodeContract: context.nodeContract
       });
     }