onbuzz 4.5.0 → 4.6.0

package/src/core/flowFieldMapping.js

@@ -0,0 +1,138 @@
+/**
+ * flowFieldMapping — assembles a target node's typed inputs from
+ * upstream node outputs, following the v2 edge field mappings.
+ *
+ * Why pull this out of FlowExecutor: it's pure logic, easy to unit
+ * test, and the executor already has plenty going on. Two consumers:
+ *
+ *   1. FlowExecutor.executeAgentNode — builds the prompt template
+ *      variables before queueing a message.
+ *   2. flowContextService — could surface the typed bag to the system
+ *      prompt ("you will receive: topic (text), research (json)").
+ *
+ * Output shape:
+ *   {
+ *     values: { [inputName]: <coerced value> },
+ *     missing: [inputName, ...],   // required inputs with no source / no upstream output
+ *     legacy: boolean              // true when called against a v1 node
+ *   }
+ *
+ * v1 fallback (legacy=true): when the target node has no `inputs[]`
+ * declared, this returns `{ input, previousOutput }` keys built by
+ * concatenating all upstream outputs — matching what FlowExecutor used
+ * to compute inline.
+ */
+
+const SCALAR = new Set(['text', 'number', 'boolean']);
+
+/**
+ * Coerce `value` to the target input's type. Mirrors the compatibility
+ * matrix in flowTypes.js — but applied at runtime to the actual value.
+ *
+ * The matrix says WHAT can connect; this function says HOW. They're
+ * intentionally separate so the editor can refuse bad connects WITHOUT
+ * needing the runtime data.
+ */
+function coerce(value, targetType) {
+  if (value === undefined || value === null) return value;
+
+  switch (targetType) {
+    case 'text': {
+      if (typeof value === 'string')   return value;
+      if (typeof value === 'number')   return String(value);
+      if (typeof value === 'boolean')  return String(value);
+      // json → text: stringify
+      try { return JSON.stringify(value); } catch { return String(value); }
+    }
+    case 'json':
+      // Anything is valid JSON. Pass through unchanged (caller may
+      // serialize at the boundary if it needs a string).
+      return value;
+    case 'file[]':
+      if (Array.isArray(value)) return value;
+      // Singleton string → 1-element list (file → file[]).
+      return [value];
+    case 'list<text>':
+      if (Array.isArray(value)) return value.map(v => typeof v === 'string' ? v : String(v));
+      return [typeof value === 'string' ? value : String(value)];
+    default:
+      // number / boolean / file: exact match expected (validator already
+      // rejected mismatches), so pass through.
+      return value;
+  }
+}
+
+/**
+ * Read a named output from a node's recorded result. Supports two
+ * shapes:
+ *   - v2:   { outputs: { fieldName: value } }                ← preferred
+ *   - v1:   { output: <single value>, type: 'agent', ... }   ← legacy
+ *
+ * For v1 fallback, the only available "field" is treated as either
+ * `result` (matching the migration default) or whatever name the edge
+ * declares — both resolve to the single `output` value.
+ */
+function readSourceOutput(sourceResult, sourceField) {
+  if (!sourceResult || typeof sourceResult !== 'object') return undefined;
+  if (sourceResult.outputs && typeof sourceResult.outputs === 'object') {
+    return sourceResult.outputs[sourceField];
+  }
+  // Legacy: the only output IS the .output field, regardless of name.
+  // Migration default uses 'result' — accept that name and any name as
+  // a fallback so partially-migrated flows work.
+  if ('output' in sourceResult) return sourceResult.output;
+  return undefined;
+}
+
+/**
+ * @param {object}   node          The target node (with optional inputs[])
+ * @param {Array}    edges         All flow edges (we filter to inbound)
+ * @param {object}   nodeOutputs   Map of nodeId → result object
+ * @returns {{ values: object, missing: string[], legacy: boolean }}
+ */
+export function assembleNodeInputs(node, edges, nodeOutputs) {
+  const safeEdges   = Array.isArray(edges) ? edges : [];
+  const safeOutputs = (nodeOutputs && typeof nodeOutputs === 'object') ? nodeOutputs : {};
+
+  // v1 fallback: no inputs[] declared at all → legacy concat shape.
+  // Note: an explicitly empty array means "this node takes no inputs"
+  // (a valid v2 declaration), so we treat it as v2.
+  const inputs = node?.inputs;
+  if (!Array.isArray(inputs)) {
+    const inboundIds = safeEdges
+      .filter(e => e && e.target === node?.id)
+      .map(e => e.source);
+    const parts = inboundIds
+      .map(id => safeOutputs[id])
+      .filter(Boolean)
+      .map(o => (typeof o.output === 'string' ? o.output : JSON.stringify(o.output ?? '')));
+    const concat = parts.join('\n\n');
+    return {
+      legacy: true,
+      values: { input: concat, previousOutput: concat },
+      missing: [],
+    };
+  }
+
+  // v2: per-declared-input lookup via edge targetField.
+  const values = {};
+  const missing = [];
+  for (const input of inputs) {
+    if (!input || typeof input.name !== 'string') continue;
+    const edge = safeEdges.find(e => e && e.target === node.id && e.targetField === input.name);
+    if (!edge) {
+      if (input.required) missing.push(input.name);
+      continue;
+    }
+    const sourceResult = safeOutputs[edge.source];
+    const raw = readSourceOutput(sourceResult, edge.sourceField);
+    if (raw === undefined) {
+      if (input.required) missing.push(input.name);
+      continue;
+    }
+    values[input.name] = coerce(raw, input.type);
+  }
+  return { legacy: false, values, missing };
+}
+
+export default { assembleNodeInputs };

package/src/core/flowLint.js

@@ -0,0 +1,102 @@
+/**
+ * flowLint — semantic checks beyond what the schema validator catches.
+ *
+ * Schema = HARD gate (blocks save/execute on shape errors).
+ * Lint   = SOFT advice (surface in editor tooltips and dry-run reports).
+ *
+ * Today's checks:
+ *   - Unbound `{{placeholder}}` in a node's promptTemplate (no declared
+ *     input by that name, no flow variable). Legacy `{{input}}` and
+ *     `{{previousOutput}}` are always treated as bound.
+ *   - Required v2 input without an inbound edge (this would also fail
+ *     at runtime — surfacing it at edit-time saves the round-trip).
+ *
+ * Returns: { errors: [], warnings: [{ nodeId?, message }] }
+ *
+ * Pure-data — no I/O, no async. Safe to run client-side AND server-side.
+ */
+
+import { isV2Flow } from './flowMigration.js';
+
+const PLACEHOLDER_RE = /\{\{\s*([a-zA-Z_$][\w.$]*)\s*\}\}/g;
+
+// Names always considered bound (legacy executor-injected variables).
+const ALWAYS_BOUND = new Set(['input', 'previousOutput', 'userInput']);
+
+export function lintFlow(flow) {
+  const errors = [];
+  const warnings = [];
+  if (!flow || typeof flow !== 'object' || !Array.isArray(flow.nodes)) {
+    return { errors, warnings };
+  }
+
+  // Lint focuses on v2 features. v1 flows skip these checks (their
+  // semantics are looser by design).
+  if (!isV2Flow(flow)) {
+    return { errors, warnings };
+  }
+
+  const variableNames = new Set(Object.keys(flow.variables || {}));
+  const edges = Array.isArray(flow.edges) ? flow.edges : [];
+
+  for (const node of flow.nodes) {
+    if (!node || typeof node.id !== 'string') continue;
+
+    // Agent nodes with empty/missing agentId are valid at save (drafts)
+    // but the run will fail. Surface this as a warning so the editor
+    // can mark the node and the dry-run report can call it out.
+    if (node.type === 'agent') {
+      const agentId = node.data?.agentId;
+      if (typeof agentId !== 'string' || agentId.trim().length === 0) {
+        warnings.push({
+          nodeId: node.id,
+          kind: 'unbound-agent',
+          message: `Agent node "${node.id}" has no agent assigned — pick one in the properties panel before running`,
+        });
+      }
+    }
+
+    // Per-node bound names: declared inputs + flow variables + legacy.
+    const inputNames = new Set((Array.isArray(node.inputs) ? node.inputs : []).map(i => i?.name).filter(Boolean));
+    const bound = new Set([...inputNames, ...variableNames, ...ALWAYS_BOUND]);
+
+    // 1) Unbound {{placeholder}} in promptTemplate
+    const tpl = node?.data?.promptTemplate;
+    if (typeof tpl === 'string' && tpl.length > 0) {
+      // Reset the regex (state is sticky across calls)
+      PLACEHOLDER_RE.lastIndex = 0;
+      const seen = new Set();
+      let m;
+      while ((m = PLACEHOLDER_RE.exec(tpl)) !== null) {
+        // Strip dot-paths to root identifier (e.g. {{user.name}} → 'user')
+        const root = m[1].split('.')[0];
+        if (seen.has(root)) continue;
+        seen.add(root);
+        if (!bound.has(root)) {
+          warnings.push({
+            nodeId: node.id,
+            message: `Template references "{{${m[1]}}}" but no input named "${root}" or variable is declared on node "${node.id}"`,
+          });
+        }
+      }
+    }
+
+    // 2) Required input with no inbound edge mapping its targetField
+    if (Array.isArray(node.inputs)) {
+      for (const inp of node.inputs) {
+        if (!inp || !inp.required) continue;
+        const fed = edges.some(e => e && e.target === node.id && e.targetField === inp.name);
+        if (!fed) {
+          warnings.push({
+            nodeId: node.id,
+            message: `Required input "${inp.name}" on node "${node.id}" has no inbound edge feeding it`,
+          });
+        }
+      }
+    }
+  }
+
+  return { errors, warnings };
+}
+
+export default { lintFlow };

package/src/core/flowMigration.js

@@ -0,0 +1,88 @@
+/**
+ * flowMigration — legacy v1 → v2 flow auto-wrap.
+ *
+ * v2 flows declare typed `inputs[]` / `outputs[]` per node and
+ * `sourceField` / `targetField` per edge. v1 flows have none of that.
+ * Rather than force a global migration, the executor wraps v1 flows
+ * on load using sane defaults that preserve v1 behavior:
+ *
+ *   - input  node: no inputs, one output  { name: 'result',  type: 'text' }
+ *   - agent  node: one input  { name: 'context', type: 'text', required: true },
+ *                  one output { name: 'result',  type: 'text' }
+ *   - output node: one input  { name: 'context', type: 'text', required: true },
+ *                  no outputs
+ *   - every edge: sourceField='result', targetField='context'
+ *
+ * Idempotent. v2 flows pass through untouched. Never mutates input.
+ */
+
+const DEFAULT_TEXT_INPUT  = Object.freeze({ name: 'context', type: 'text', required: true });
+const DEFAULT_TEXT_OUTPUT = Object.freeze({ name: 'result',  type: 'text' });
+
+/**
+ * A flow is v2 if it declares `schemaVersion: 2` OR if any node already
+ * carries typed `inputs` / `outputs`. The "any typed node" heuristic
+ * lets partial migrations round-trip cleanly without re-wrapping.
+ */
+export function isV2Flow(flow) {
+  if (!flow || typeof flow !== 'object') return false;
+  if (flow.schemaVersion === 2) return true;
+  if (!Array.isArray(flow.nodes)) return false;
+  return flow.nodes.some(n =>
+    Array.isArray(n?.inputs) || Array.isArray(n?.outputs)
+  );
+}
+
+function wrapNode(node) {
+  // Preserve all existing fields; only ADD typed inputs/outputs.
+  const next = { ...node };
+  switch (node.type) {
+    case 'input':
+      next.inputs  = [];
+      next.outputs = [{ ...DEFAULT_TEXT_OUTPUT }];
+      break;
+    case 'output':
+      next.inputs  = [{ ...DEFAULT_TEXT_INPUT }];
+      next.outputs = [];
+      break;
+    case 'agent':
+    default:
+      // Default to "takes context, produces result" for any unknown
+      // node type too — keeps the migration total.
+      next.inputs  = [{ ...DEFAULT_TEXT_INPUT }];
+      next.outputs = [{ ...DEFAULT_TEXT_OUTPUT }];
+      break;
+  }
+  return next;
+}
+
+function wrapEdge(edge) {
+  return {
+    ...edge,
+    sourceField: 'result',
+    targetField: 'context',
+  };
+}
+
+/**
+ * Migrate a v1 flow to v2 shape. Idempotent — already-v2 flows return
+ * unchanged (same reference).
+ *
+ * Returns the input as-is if it isn't a recognizable flow object
+ * (null/undefined/missing nodes). Lets callers fall through to their
+ * own error handling without us throwing on the load path.
+ */
+export function migrateLegacyFlow(flow) {
+  if (!flow || typeof flow !== 'object') return flow;
+  if (!Array.isArray(flow.nodes)) return flow;
+  if (isV2Flow(flow)) return flow;
+
+  return {
+    ...flow,
+    schemaVersion: 2,
+    nodes: flow.nodes.map(wrapNode),
+    edges: Array.isArray(flow.edges) ? flow.edges.map(wrapEdge) : [],
+  };
+}
+
+export default { isV2Flow, migrateLegacyFlow };

package/src/core/flowRetry.js

@@ -0,0 +1,103 @@
+/**
+ * flowRetry — runs a node attempt with timeout + classified retry.
+ *
+ * Why a separate module: retry semantics in the executor get tangled
+ * fast (per-node config, exponential backoff, attempt history, retry
+ * classification, observability). Pulling it out keeps executeAgentNode
+ * readable and gives us a tight test surface.
+ *
+ * Errors carry a `kind` so callers can:
+ *   - decide whether to retry (per `retryOn`)
+ *   - report which type of failure happened (timeout vs explicit fail)
+ *
+ * Default kinds:
+ *   - 'timeout'         attemptFn didn't finish in timeoutMs
+ *   - 'agent-error'     attemptFn threw a plain Error (default classification)
+ *   - 'agent-failure'   attemptFn explicitly returned/threw a non-retryable failure
+ *                       (caller throws FlowRetryError(msg, 'agent-failure'))
+ *
+ * Retries don't replay the underlying agent — the attemptFn IS the
+ * "do one full agent invocation" closure. That keeps job-done semantics
+ * clean: every retry is a fresh agent call.
+ */
+
+const DEFAULTS = Object.freeze({
+  timeoutMs: 300000,
+  maxRetries: 0,
+  retryOn: ['timeout', 'agent-error'],
+  backoffBaseMs: 1000,
+  backoffMultiplier: 2,
+});
+
+export class FlowRetryError extends Error {
+  constructor(message, kind = 'agent-error') {
+    super(message);
+    this.name = 'FlowRetryError';
+    this.kind = kind;
+  }
+}
+
+function _withTimeout(promise, ms) {
+  let to;
+  const timeout = new Promise((_, reject) => {
+    to = setTimeout(() => {
+      const e = new FlowRetryError(`attempt timed out after ${ms}ms`, 'timeout');
+      reject(e);
+    }, ms);
+  });
+  return Promise.race([promise, timeout]).finally(() => clearTimeout(to));
+}
+
+function _classify(err) {
+  if (err instanceof FlowRetryError) return err;
+  // Plain Error → agent-error by default
+  const wrapped = new FlowRetryError(err?.message || String(err), 'agent-error');
+  wrapped.cause = err;
+  return wrapped;
+}
+
+const _sleep = (ms) => new Promise(r => setTimeout(r, ms));
+
+/**
+ * @param {(attemptIndex: number) => Promise<any>} attemptFn
+ * @param {object} [opts] see DEFAULTS
+ * @returns {Promise<{ result, attempts: Array<{ attempt: number, error?: { kind, message } }> }>}
+ */
+export async function runWithRetry(attemptFn, opts = {}) {
+  if (typeof attemptFn !== 'function') {
+    throw new TypeError('runWithRetry: attemptFn must be a function');
+  }
+  const cfg = { ...DEFAULTS, ...opts };
+  const attempts = [];
+  let lastErr;
+
+  // Total tries = 1 (initial) + maxRetries
+  const totalTries = Math.max(1, 1 + (cfg.maxRetries | 0));
+
+  for (let i = 0; i < totalTries; i++) {
+    try {
+      const result = await _withTimeout(Promise.resolve().then(() => attemptFn(i)), cfg.timeoutMs);
+      attempts.push({ attempt: i });
+      return { result, attempts };
+    } catch (e) {
+      const err = _classify(e);
+      lastErr = err;
+      const isLast = i === totalTries - 1;
+      const willRetry = !isLast && cfg.retryOn.includes(err.kind);
+      attempts.push({
+        attempt: i,
+        error: { kind: err.kind, message: err.message },
+      });
+      if (typeof cfg.onAttempt === 'function') {
+        try { cfg.onAttempt({ attempt: i, error: err, willRetry }); } catch { /* observer must not break retry */ }
+      }
+      if (!willRetry) throw err;
+      const wait = Math.round(cfg.backoffBaseMs * Math.pow(cfg.backoffMultiplier, i));
+      await _sleep(wait);
+    }
+  }
+  // Defensive — loop above always returns or throws.
+  throw lastErr || new FlowRetryError('runWithRetry exhausted unexpectedly');
+}
+
+export default { runWithRetry, FlowRetryError };