bosun 0.41.0 → 0.41.2

package/workflow/workflow-cli.mjs

@@ -0,0 +1,128 @@
+import { existsSync, readFileSync } from "node:fs";
+import { resolve } from "node:path";
+import { loadConfig } from "../config/config.mjs";
+import {
+  listConfiguredWorkflows,
+  loadWorkflowInputFromFile,
+  runConfiguredWorkflow,
+} from "./declarative-workflows.mjs";
+
+function hasFlag(args, ...flags) {
+  return flags.some((flag) => args.includes(flag));
+}
+
+function getArgValue(args, flag) {
+  const direct = args.find((arg) => arg.startsWith(`${flag}=`));
+  if (direct) return direct.slice(flag.length + 1).trim();
+  const index = args.indexOf(flag);
+  if (index >= 0 && index + 1 < args.length) return String(args[index + 1] || "").trim();
+  return "";
+}
+
+export function parseWorkflowInput(rawValue, cwd = process.cwd()) {
+  const trimmed = String(rawValue || "").trim();
+  if (!trimmed) return "";
+  const fullPath = resolve(cwd, trimmed);
+  if (existsSync(fullPath)) {
+    const raw = readFileSync(fullPath, "utf8");
+    try {
+      return JSON.parse(raw);
+    } catch {
+      return raw;
+    }
+  }
+  try {
+    return JSON.parse(trimmed);
+  } catch {
+    return trimmed;
+  }
+}
+
+function parseInput(args, cwd = process.cwd()) {
+  const inputFile = getArgValue(args, "--file");
+  if (inputFile) return loadWorkflowInputFromFile(inputFile);
+  const inlineJson = getArgValue(args, "--input-json");
+  if (inlineJson) return JSON.parse(inlineJson);
+  const inputText = getArgValue(args, "--input");
+  if (inputText) return parseWorkflowInput(inputText, cwd);
+  const positional = args.filter((arg) => !arg.startsWith("--"));
+  return positional.length > 2 ? positional.slice(2).join(" ") : "";
+}
+
+function showHelp(stdout = console.log) {
+  stdout(`
+  bosun workflow — Declarative multi-agent workflows
+
+  SUBCOMMANDS
+    list                      List configured and built-in workflows
+    run <name> [input]        Run a workflow with fresh-context agents
+
+  OPTIONS
+    --json                    Emit JSON output
+    --dry-run                 Render prompts without executing agents
+    --input <text>            Inline workflow input
+    --input-json <json>       Structured JSON input
+    --file <path>             Load workflow input from a file
+`);
+}
+
+export function listWorkflowSummaries(config = loadConfig(process.argv)) {
+  return listConfiguredWorkflows(config);
+}
+
+export async function executeWorkflowCommand(args, options = {}) {
+  const normalizedArgs = Array.isArray(args) && args[0] === "workflow" ? args.slice(1) : args;
+  const subcommand = normalizedArgs?.[0] || "list";
+  const stdout = options.stdout || ((line) => console.log(line));
+  if (hasFlag(normalizedArgs, "--help", "-h") || subcommand === "help") {
+    showHelp(stdout);
+    return { ok: true, command: "help" };
+  }
+
+  const config = options.config || loadConfig(process.argv);
+  const asJson = hasFlag(normalizedArgs, "--json") || options.json === true;
+  if (subcommand === "list") {
+    const workflows = listConfiguredWorkflows(config);
+    if (asJson) {
+      stdout(JSON.stringify(workflows, null, 2));
+    } else {
+      for (const workflow of workflows) {
+        stdout(`${workflow.id}\t${workflow.type}\t${workflow.description}`);
+      }
+    }
+    return { ok: true, command: "list", workflows };
+  }
+
+  if (subcommand === "run") {
+    const name = normalizedArgs[1];
+    if (!name) throw new Error("Workflow name is required. Usage: bosun workflow run <name>");
+    const input = parseInput(normalizedArgs, options.cwd || process.cwd());
+    const result = await runConfiguredWorkflow(name, input, {
+      config,
+      dryRun: hasFlag(normalizedArgs, "--dry-run"),
+      services: options.services,
+      runOptions: options.runOptions,
+    });
+    if (asJson || options.forceJsonOutput === true) {
+      stdout(JSON.stringify(result, null, 2));
+    } else {
+      stdout(`workflow=${result.workflow.id} status=${result.status} outputs=${result.outputs.length} errors=${result.errors.length}`);
+      for (const output of result.outputs) {
+        const summary = String(output.summary || output.output || "").slice(0, 160);
+        stdout(`- ${output.agentId}: ${summary}`);
+      }
+      if (result.consensus?.text) {
+        stdout(`consensus=${result.consensus.text}`);
+      }
+    }
+    return { ok: true, command: "run", workflowName: name, result };
+  }
+
+  throw new Error(`Unknown workflow subcommand: ${subcommand}`);
+}
+
+export async function runWorkflowCli(args, options = {}) {
+  return executeWorkflowCommand(["workflow", ...(Array.isArray(args) ? args : [])], options);
+}
+
+export default runWorkflowCli;

package/workflow/workflow-engine.mjs

@@ -34,7 +34,6 @@
  */
 
 import { existsSync, readFileSync, writeFileSync, mkdirSync, readdirSync, unlinkSync, statSync } from "node:fs";
-import { writeFile as writeFileAsync } from "node:fs/promises";
 import { resolve, basename, extname, join } from "node:path";
 import { randomUUID } from "node:crypto";
 import { EventEmitter } from "node:events";
@@ -170,17 +169,243 @@ export const WorkflowStatus = Object.freeze({
 // ── Node Type Registry ──────────────────────────────────────────────────────
 
 const _nodeTypeRegistry = new Map();
+const _nodeTypeMetaRegistry = new Map();
+const _normalizedHandlerCache = new WeakMap();
+
+function clonePortDescriptor(port) {
+  if (!port || typeof port !== "object") return null;
+  return {
+    name: String(port.name || "default").trim() || "default",
+    label: String(port.label || port.name || "default").trim() || "default",
+    type: String(port.type || "Any").trim() || "Any",
+    description: String(port.description || "").trim(),
+    color: typeof port.color === "string" && port.color.trim() ? port.color.trim() : null,
+    accepts: Array.isArray(port.accepts)
+      ? Array.from(new Set(port.accepts.map((value) => String(value || "").trim()).filter(Boolean)))
+      : [],
+  };
+}
+
+function normalizePortDescriptor(port, direction, index) {
+  const fallbackName = index === 0 ? "default" : `${direction}-${index + 1}`;
+  if (typeof port === "string") {
+    return {
+      name: fallbackName,
+      label: fallbackName,
+      type: port,
+      description: "",
+      color: null,
+      accepts: [],
+    };
+  }
+
+  if (!port || typeof port !== "object") {
+    return {
+      name: fallbackName,
+      label: fallbackName,
+      type: "Any",
+      description: "",
+      color: null,
+      accepts: [],
+    };
+  }
+
+  return clonePortDescriptor({
+    ...port,
+    name: port.name || fallbackName,
+    label: port.label || port.name || fallbackName,
+    type: port.type || "Any",
+  });
+}
+
+function normalizePortList(ports, direction) {
+  if (!Array.isArray(ports)) return [];
+  return ports
+    .map((port, index) => normalizePortDescriptor(port, direction, index))
+    .filter(Boolean);
+}
+
+function normalizeNodeUi(ui = {}) {
+  const primaryFields = Array.isArray(ui?.primaryFields)
+    ? Array.from(new Set(ui.primaryFields.map((value) => String(value || "").trim()).filter(Boolean)))
+    : [];
+  return {
+    ...ui,
+    primaryFields,
+  };
+}
+
+function normalizeHandlerMetadata(handler) {
+  if (_normalizedHandlerCache.has(handler)) {
+    return _normalizedHandlerCache.get(handler);
+  }
+
+  const inputPorts = normalizePortList(handler?.inputs ?? handler?.ports?.inputs, "input");
+  const outputPorts = normalizePortList(handler?.outputs ?? handler?.ports?.outputs, "output");
+
+  const normalized = {
+    ...handler,
+    ports: {
+      inputs: inputPorts,
+      outputs: outputPorts,
+    },
+    ui: normalizeNodeUi(handler?.ui),
+  };
+  _normalizedHandlerCache.set(handler, normalized);
+  return normalized;
+}
+
+function resolveNodePorts(node) {
+  const handler = node?.type ? _nodeTypeRegistry.get(node.type) : null;
+  const handlerPorts = handler?.ports || {};
+  const inputPorts = normalizePortList(node?.inputPorts, "input");
+  const outputPorts = normalizePortList(node?.outputPorts, "output");
+
+  return {
+    inputs: inputPorts.length > 0 ? inputPorts : normalizePortList(handlerPorts.inputs, "input"),
+    outputs: outputPorts.length > 0 ? outputPorts : normalizePortList(handlerPorts.outputs, "output"),
+  };
+}
+
+function resolvePortByName(ports, requestedName, direction) {
+  if (!Array.isArray(ports) || ports.length === 0) return null;
+  const normalizedName = String(requestedName || "").trim();
+  if (!normalizedName) return ports[0];
+  const matched = ports.find((port) => port.name === normalizedName);
+  if (matched) return matched;
+  return normalizePortDescriptor({
+    name: normalizedName,
+    label: normalizedName,
+    type: "Any",
+  }, direction, 0);
+}
+
+function isWildcardPortType(type) {
+  const normalized = String(type || "").trim();
+  return normalized === "*" || normalized === "Any";
+}
+
+export function isPortConnectionCompatible(sourcePort, targetPort) {
+  if (!sourcePort || !targetPort) {
+    return { compatible: true, reason: null };
+  }
+
+  const sourceType = String(sourcePort.type || "Any").trim() || "Any";
+  const targetType = String(targetPort.type || "Any").trim() || "Any";
+  const accepted = new Set(
+    [targetType, ...(Array.isArray(targetPort.accepts) ? targetPort.accepts : [])]
+      .map((value) => String(value || "").trim())
+      .filter(Boolean),
+  );
+
+  if (isWildcardPortType(sourceType) || isWildcardPortType(targetType) || accepted.has("*") || accepted.has("Any")) {
+    return { compatible: true, reason: null };
+  }
+
+  if (sourceType === targetType || accepted.has(sourceType)) {
+    return { compatible: true, reason: null };
+  }
+
+  return {
+    compatible: false,
+    reason: `${sourcePort.label || sourcePort.name} emits ${sourceType}, but ${targetPort.label || targetPort.name} expects ${targetType}`,
+  };
+}
+
+function hydrateWorkflowDefinition(def, { strict = false } = {}) {
+  const normalized = {
+    ...(def || {}),
+    nodes: Array.isArray(def?.nodes) ? def.nodes.map((node) => ({ ...node })) : [],
+    edges: Array.isArray(def?.edges) ? def.edges.map((edge) => ({ ...edge })) : [],
+    metadata: { ...(def?.metadata || {}) },
+  };
+
+  const nodeMap = new Map();
+  normalized.nodes = normalized.nodes.map((node) => {
+    const ports = resolveNodePorts(node);
+    const explicitOutputs = Array.isArray(node?.outputs)
+      ? Array.from(new Set(node.outputs.map((value) => String(value || "").trim()).filter(Boolean)))
+      : undefined;
+    const nextNode = {
+      ...node,
+      inputPorts: ports.inputs.map((port) => clonePortDescriptor(port)),
+      outputPorts: ports.outputs.map((port) => clonePortDescriptor(port)),
+      ...(explicitOutputs !== undefined ? { outputs: explicitOutputs } : {}),
+    };
+    nodeMap.set(nextNode.id, nextNode);
+    return nextNode;
+  });
+
+  const issues = [];
+
+  normalized.edges = normalized.edges.map((edge) => {
+    const sourceNode = nodeMap.get(edge.source);
+    const targetNode = nodeMap.get(edge.target);
+    const sourcePorts = resolveNodePorts(sourceNode);
+    const targetPorts = resolveNodePorts(targetNode);
+    const sourcePort = resolvePortByName(sourcePorts.outputs, edge.sourcePort || "default", "output");
+    const targetPort = resolvePortByName(targetPorts.inputs, edge.targetPort || "default", "input");
+    const compatibility = isPortConnectionCompatible(sourcePort, targetPort);
+
+    if (!compatibility.compatible) {
+      issues.push({
+        edgeId: edge.id || `${edge.source}->${edge.target}`,
+        source: edge.source,
+        target: edge.target,
+        sourcePort: sourcePort?.name || "default",
+        targetPort: targetPort?.name || "default",
+        sourceType: sourcePort?.type || null,
+        targetType: targetPort?.type || null,
+        severity: "error",
+        message: compatibility.reason,
+      });
+    }
+
+    return {
+      ...edge,
+      sourcePort: sourcePort?.name || String(edge.sourcePort || "default").trim() || "default",
+      targetPort: targetPort?.name || String(edge.targetPort || "default").trim() || "default",
+      sourcePortType: sourcePort?.type || null,
+      targetPortType: targetPort?.type || null,
+    };
+  });
+
+  normalized.metadata.validationIssues = issues;
+
+  if (strict && issues.length > 0) {
+    throw new Error(`Workflow port validation failed: ${issues.map((issue) => issue.message).join("; ")}`);
+  }
+
+  return normalized;
+}
 
 /**
  * Register a node type handler.
  * @param {string} type - Node type identifier (e.g., "trigger.task_low", "action.run_agent")
  * @param {object} handler - { execute(node, context, engine), validate?(node), describe?() }
  */
-export function registerNodeType(type, handler) {
+export function registerNodeType(type, handler, options = {}) {
   if (!handler || typeof handler.execute !== "function") {
     throw new Error(`${TAG} Node type "${type}" must have an execute function`);
   }
-  _nodeTypeRegistry.set(type, handler);
+  const normalized = normalizeHandlerMetadata(handler);
+  _nodeTypeRegistry.set(type, normalized);
+  _nodeTypeMetaRegistry.set(type, {
+    source: String(options.source || handler.source || "builtin"),
+    badge: options.badge || handler.badge || null,
+    isCustom: options.isCustom === true || handler.isCustom === true || String(options.source || handler.source || "").toLowerCase() === "custom",
+    filePath: options.filePath || handler.filePath || null,
+    inputs: Array.isArray(options.inputs)
+      ? options.inputs
+      : Array.isArray(handler.inputs)
+        ? handler.inputs
+        : (normalized.ports?.inputs || []).map((port) => port?.name || "default"),
+    outputs: Array.isArray(options.outputs)
+      ? options.outputs
+      : Array.isArray(handler.outputs)
+        ? handler.outputs
+        : (normalized.ports?.outputs || []).map((port) => port?.name || "default"),
+  });
 }
 
 /**
@@ -192,6 +417,15 @@ export function getNodeType(type) {
   return _nodeTypeRegistry.get(type) || null;
 }
 
+export function getNodeTypeMeta(type) {
+  return _nodeTypeMetaRegistry.get(type) || null;
+}
+
+export function unregisterNodeType(type) {
+  _nodeTypeRegistry.delete(type);
+  _nodeTypeMetaRegistry.delete(type);
+}
+
 /**
  * List all registered node types with metadata.
  * @returns {Array<{type: string, category: string, description: string}>}
@@ -200,11 +434,23 @@ export function listNodeTypes() {
   const result = [];
   for (const [type, handler] of _nodeTypeRegistry) {
     const [category] = type.split(".");
+    const metadata = _nodeTypeMetaRegistry.get(type) || {};
     result.push({
       type,
       category,
       description: handler.describe?.() || type,
       schema: handler.schema || null,
+      source: metadata.source || "builtin",
+      badge: metadata.badge || null,
+      isCustom: metadata.isCustom === true,
+      filePath: metadata.filePath || null,
+      inputs: Array.isArray(metadata.inputs) ? [...metadata.inputs] : [],
+      outputs: Array.isArray(metadata.outputs) ? [...metadata.outputs] : [],
+      ports: {
+        inputs: (handler.ports?.inputs || []).map((port) => clonePortDescriptor(port)),
+        outputs: (handler.ports?.outputs || []).map((port) => clonePortDescriptor(port)),
+      },
+      ui: normalizeNodeUi(handler.ui),
     });
   }
   return result;
@@ -689,7 +935,7 @@ export class WorkflowEngine extends EventEmitter {
     for (const file of files) {
       try {
         const raw = readFileSync(resolve(this.workflowDir, file), "utf8");
-        const def = JSON.parse(raw);
+        const def = hydrateWorkflowDefinition(JSON.parse(raw));
         if (def.id) {
           this._workflows.set(def.id, def);
         }
@@ -741,6 +987,7 @@ export class WorkflowEngine extends EventEmitter {
 
   /** Save (create or update) a workflow definition */
   save(def) {
+    def = hydrateWorkflowDefinition(def, { strict: true });
     if (!def.id) def.id = randomUUID();
     if (!def.metadata) def.metadata = {};
     def.metadata.updatedAt = new Date().toISOString();
@@ -887,6 +1134,59 @@ export class WorkflowEngine extends EventEmitter {
     }
   }
 
+  /**
+   * Execute an ephemeral workflow definition without saving it to the registry.
+   * Useful for inline/embedded workflow composition where the child flow should
+   * have its own run/context history but not become an installed workflow.
+   *
+   * @param {object} workflowDef
+   * @param {object} inputData
+   * @param {object} [opts]
+   * @returns {Promise<WorkflowContext>}
+   */
+  async executeDefinition(workflowDef, inputData = {}, opts = {}) {
+    const requestedId = String(workflowDef?.id || opts.inlineWorkflowId || "").trim();
+    const workflowId = requestedId || `inline:${randomUUID()}`;
+    const normalized = hydrateWorkflowDefinition({
+      enabled: true,
+      trigger: workflowDef?.trigger || "trigger.workflow_call",
+      ...workflowDef,
+      id: workflowId,
+      name: String(workflowDef?.name || opts.inlineWorkflowName || workflowId).trim() || workflowId,
+      metadata: {
+        ...(workflowDef?.metadata || {}),
+        inline: true,
+        ephemeral: true,
+        sourceNodeId: opts.sourceNodeId || workflowDef?.metadata?.sourceNodeId || null,
+      },
+    }, { strict: true });
+
+    if (normalized.enabled === false && !opts.force) {
+      throw new Error(`${TAG} Inline workflow "${normalized.name}" is disabled`);
+    }
+
+    if (this._runSlots >= MAX_CONCURRENT_RUNS) {
+      this.emit("run:queued", { workflowId: normalized.id, name: normalized.name, queueDepth: this._runQueue.length + 1 });
+      await new Promise((resolve, reject) => {
+        this._runQueue.push({ resolve, reject });
+      });
+    }
+    this._runSlots++;
+
+    try {
+      return await this._executeInner(normalized, normalized.id, inputData, {
+        ...opts,
+        force: true,
+      });
+    } finally {
+      this._runSlots--;
+      if (this._runQueue.length > 0) {
+        const next = this._runQueue.shift();
+        next.resolve();
+      }
+    }
+  }
+
   /**
    * Inner execute logic — called only once a concurrency slot is acquired.
    * @private
@@ -1392,14 +1692,25 @@ export class WorkflowEngine extends EventEmitter {
         || n.type === "trigger.task_low",
       );
 
+      const scheduleCtx = new WorkflowContext({
+        ...(def.variables || {}),
+        ...(def.data || {}),
+      });
+
+      const resolvePositiveInterval = (rawValue, fallbackMs) => {
+        const resolved = scheduleCtx.resolve(rawValue);
+        const parsed = Number(resolved);
+        return Number.isFinite(parsed) && parsed > 0 ? parsed : fallbackMs;
+      };
+
       for (const tNode of triggerNodes) {
         let intervalMs = 3600000;
         if (tNode.type === "trigger.task_available") {
-          intervalMs = Number(tNode.config?.pollIntervalMs) || 30000;
+          intervalMs = resolvePositiveInterval(tNode.config?.pollIntervalMs, 30000);
         } else if (tNode.type === "trigger.task_low") {
-          intervalMs = Number(tNode.config?.pollIntervalMs) || 60000;
+          intervalMs = resolvePositiveInterval(tNode.config?.pollIntervalMs, 60000);
         } else {
-          intervalMs = Number(tNode.config?.intervalMs) || 3600000;
+          intervalMs = resolvePositiveInterval(tNode.config?.intervalMs, 3600000);
         }
 
         // Find the most recent completed run for this workflow
@@ -2592,8 +2903,7 @@ export class WorkflowEngine extends EventEmitter {
 
       // Write initial detail file so we can resume from it
       const detail = this._serializeRunContext(ctx, true);
-      const detailPath = resolve(this.runsDir, `${runId}.json`);
-      writeFileSync(detailPath, JSON.stringify(detail, null, 2), "utf8");
+      this._writeRunDetail(runId, detail);
 
       // Also ensure the run appears in the main index (with RUNNING status)
       // so that getRunDetail() can find it even before completion.
@@ -2617,13 +2927,12 @@ export class WorkflowEngine extends EventEmitter {
     const timer = setTimeout(() => {
       this._checkpointTimers.delete(runId);
       try {
+        // If the run has already been finalized/removed, skip writing a
+        // late checkpoint snapshot that could overwrite terminal detail.
+        if (!this._activeRuns.has(runId)) return;
         this._ensureDirs();
         const detail = this._serializeRunContext(ctx, true);
-        const detailPath = resolve(this.runsDir, `${runId}.json`);
-        // Async write — checkpoint is fire-and-forget, no need to block event loop
-        writeFileAsync(detailPath, JSON.stringify(detail, null, 2), "utf8").catch((err) => {
-          console.error(`${TAG} Checkpoint write failed for run ${runId}:`, err.message);
-        });
+        this._writeRunDetail(runId, detail);
       } catch (err) {
         console.error(`${TAG} Checkpoint failed for run ${runId}:`, err.message);
       }
@@ -2984,12 +3293,16 @@ export class WorkflowEngine extends EventEmitter {
       writeFileSync(indexPath, JSON.stringify({ runs }, null, 2), "utf8");
 
       // Save full run detail
-      const detailPath = resolve(this.runsDir, `${runId}.json`);
-      writeFileSync(detailPath, JSON.stringify(detail, null, 2), "utf8");
+      this._writeRunDetail(runId, detail);
     } catch (err) {
       console.error(`${TAG} Failed to persist run log:`, err.message);
     }
   }
+
+  _writeRunDetail(runId, detail) {
+    const detailPath = resolve(this.runsDir, `${runId}.json`);
+    writeFileSync(detailPath, JSON.stringify(detail, null, 2), "utf8");
+  }
 }
 
 // ── Module-level convenience functions ──────────────────────────────────────
@@ -3055,4 +3368,3 @@ export function listWorkflows(opts) { return getWorkflowEngine(opts).list(); }
 export function getWorkflow(id, opts) { return getWorkflowEngine(opts).get(id); }
 export async function executeWorkflow(id, data, opts) { return getWorkflowEngine(opts).execute(id, data, opts); }
 export async function retryWorkflowRun(runId, retryOpts, engineOpts) { return getWorkflowEngine(engineOpts).retryRun(runId, retryOpts); }
-