onbuzz 4.5.0 → 4.6.0

package/src/core/flowExecutor.js

@@ -10,6 +10,9 @@
  */
 
 import { AGENT_MODES } from '../utilities/constants.js';
+import { validateFlowDefinition } from './flowSchema.js';
+import { assembleNodeInputs } from './flowFieldMapping.js';
+import { runWithRetry, FlowRetryError } from './flowRetry.js';
 
 class FlowExecutor {
   constructor(config, logger, stateManager, agentPool, messageProcessor) {
@@ -27,6 +30,40 @@ class FlowExecutor {
 
     // Completion listeners per run
     this.completionListeners = new Map();
+
+    // Phase 8: agentId → currently-awaited node contract.
+    // Set when an agent is invoked inside a flow node; cleared when
+    // the await resolves. The jobdone tool reads this to validate
+    // the agent's job-done call AT TOOL TIME — rejecting partial
+    // calls before they propagate into the executor.
+    this.activeContracts = new Map();
+
+    // Optional disk checkpointing — when set, every successful node
+    // persists its result so the run can resume after a crash. Off by
+    // default (preserves pre-Phase-4 behavior; opt in via setCheckpointStore).
+    this.checkpointStore = null;
+  }
+
+  /**
+   * Phase 8: get the currently-awaited node contract for an agent (if any).
+   * Returns the contract object { inputs, outputs, instructions, ... } so
+   * the jobdone tool can validate the agent's call against it AT TOOL TIME
+   * — much faster recovery than waiting for executor-level re-prompts.
+   *
+   * @param {string} agentId
+   * @returns {object|null} the contract, or null when the agent isn't in
+   *                        a flow step right now.
+   */
+  getActiveContract(agentId) {
+    return this.activeContracts.get(agentId) || null;
+  }
+
+  /**
+   * Phase 4: enable disk checkpoints + resume by injecting a store.
+   * Calling with null disables checkpointing.
+   */
+  setCheckpointStore(store) {
+    this.checkpointStore = store || null;
   }
 
   /**
@@ -51,6 +88,21 @@ class FlowExecutor {
       throw new Error(`Flow not found: ${flowId}`);
     }
 
+    // Belt-and-suspenders schema check. The POST/PUT routes already gate
+    // on this, but flows can also be authored by importing JSON files
+    // directly into the index, or by older clients that bypassed the
+    // route. Catching here means we never queue agents on a flow that
+    // we can't actually execute. Errors include path so the caller can
+    // surface them in the run-detail view.
+    const validation = validateFlowDefinition(flow);
+    if (!validation.ok) {
+      const detail = validation.errors.map(e => e.message).join('; ');
+      this.logger.warn(`Flow ${flowId} failed schema validation; refusing to execute`, {
+        errors: validation.errors,
+      });
+      throw new Error(`Flow definition is invalid: ${detail}`);
+    }
+
     // Create flow run record
     const run = await this.stateManager.createFlowRun(flowId, initialInput);
     const runId = run.id;
@@ -71,8 +123,13 @@ class FlowExecutor {
       startedAt: new Date()
     });
 
-    // Update run status to running
-    await this.stateManager.updateFlowRun(runId, { status: 'running' });
+    // Update run status to running. Phase 6.3: stamp the flow's
+    // current version onto the run so we can later answer "which
+    // definition produced this output?" — important after rollbacks.
+    await this.stateManager.updateFlowRun(runId, {
+      status: 'running',
+      flowVersion: flow.version ?? null,
+    });
     const startedAt = new Date().toISOString();
     this.broadcastFlowUpdate(sessionId, {
       type: 'flow_run_started',
@@ -120,6 +177,14 @@ class FlowExecutor {
           return { runId, status: 'stopped' };
         }
 
+        // Phase 4: skip nodes already completed in a previous run that
+        // we're resuming from. Their outputs were rehydrated into
+        // context.nodeOutputs by resumeFlow before the loop started.
+        if (context.skipCompletedNodeIds?.has?.(node.id)) {
+          this.logger.info(`Flow ${flowId}: skipping already-completed node ${node.id} on resume`);
+          continue;
+        }
+
         // Execute node
         const nodeResult = await this.executeNode(node, context, runId, sessionId, flow);
 
@@ -133,6 +198,18 @@ class FlowExecutor {
 
         // Update node state in run
         await this.updateNodeState(runId, node.id, 'completed', nodeResult);
+
+        // Phase 4: persist a checkpoint after each successful node so a
+        // resume can skip back here. Best-effort — checkpoint failures
+        // don't fail the run (we'd rather complete without resumability
+        // than blow up because disk is full).
+        if (this.checkpointStore) {
+          try {
+            await this.checkpointStore.saveNodeResult(runId, node.id, nodeResult);
+          } catch (err) {
+            this.logger.warn(`Flow ${flowId}: failed to checkpoint node ${node.id}`, { error: err.message });
+          }
+        }
       }
 
       // Flow completed successfully
@@ -182,6 +259,111 @@ class FlowExecutor {
     }
   }
 
+  /**
+   * Phase 4: resume a previously-failed or interrupted run.
+   *
+   * Loads the run record + per-node checkpoints, rehydrates the
+   * execution context with all completed nodes' outputs, and re-runs
+   * the loop. The standard executeFlow loop skips any node whose ID is
+   * present in `context.skipCompletedNodeIds`, so completed work isn't
+   * repeated.
+   *
+   * Requires `setCheckpointStore` to have been called — without it,
+   * there are no per-node checkpoints to read and resume is a no-op
+   * fall-through.
+   *
+   * @param {string} runId
+   * @param {string|null} sessionId
+   * @returns {Promise<{ runId, status, output? }>}
+   */
+  async resumeFlow(runId, sessionId = null) {
+    if (!this.checkpointStore) {
+      throw new Error('Cannot resume: no checkpoint store configured (call setCheckpointStore first)');
+    }
+
+    const run = await this.stateManager.getFlowRun(runId);
+    if (!run) throw new Error(`Cannot resume: flow run not found: ${runId}`);
+    if (run.status === 'completed') {
+      return { runId, status: 'completed', output: run.output };
+    }
+
+    const flow = await this.stateManager.getFlow(run.flowId);
+    if (!flow) throw new Error(`Cannot resume: flow definition not found: ${run.flowId}`);
+
+    // Same schema gate as executeFlow — the flow definition might have
+    // been edited between runs into an invalid shape.
+    const validation = validateFlowDefinition(flow);
+    if (!validation.ok) {
+      const detail = validation.errors.map(e => e.message).join('; ');
+      throw new Error(`Cannot resume: flow definition is invalid: ${detail}`);
+    }
+
+    // Rehydrate completed-node outputs from disk.
+    const persistedOutputs = await this.checkpointStore.loadAllNodeResults(runId);
+    const completedIds = new Set(Object.keys(persistedOutputs));
+    this.logger.info(`Resuming flow ${run.flowId} run ${runId}`, {
+      completedNodes: completedIds.size,
+      totalNodes: flow.nodes.length,
+    });
+
+    this.activeExecutions.set(runId, {
+      flowId: run.flowId, flow, runId, sessionId,
+      status: 'running', startedAt: new Date(),
+    });
+    await this.stateManager.updateFlowRun(runId, { status: 'running', resumedAt: new Date().toISOString() });
+    this.broadcastFlowUpdate(sessionId, { type: 'flow_run_resumed', runId, flowId: run.flowId });
+
+    try {
+      await this.ensureAgentsLoaded(flow.nodes);
+      const sortedNodes = this.topologicalSort(flow.nodes, flow.edges);
+      if (sortedNodes.length === 0) throw new Error('Flow has no executable nodes');
+
+      const context = {
+        input: run.initialInput?.userInput || run.initialInput?.input || '',
+        nodeOutputs: { ...persistedOutputs },
+        variables: { ...flow.variables },
+        sortedNodes,
+        flow,
+        skipCompletedNodeIds: completedIds,
+      };
+
+      for (const node of sortedNodes) {
+        const execution = this.activeExecutions.get(runId);
+        if (!execution || execution.status === 'stopped') {
+          await this.stateManager.updateFlowRun(runId, { status: 'stopped', completedAt: new Date().toISOString() });
+          this.broadcastFlowUpdate(sessionId, { type: 'flow_run_stopped', runId, flowId: run.flowId });
+          return { runId, status: 'stopped' };
+        }
+        if (completedIds.has(node.id)) {
+          this.logger.info(`Resume: skipping already-completed node ${node.id}`);
+          continue;
+        }
+        const nodeResult = await this.executeNode(node, context, runId, sessionId, flow);
+        context.nodeOutputs[node.id] = nodeResult;
+        if (node.data?.outputKey) context.nodeOutputs[node.data.outputKey] = nodeResult;
+        await this.updateNodeState(runId, node.id, 'completed', nodeResult);
+        try { await this.checkpointStore.saveNodeResult(runId, node.id, nodeResult); }
+        catch (err) { this.logger.warn(`Resume: checkpoint save failed for ${node.id}`, { error: err.message }); }
+      }
+
+      const finalOutput = this.collectFinalOutput(sortedNodes, context);
+      await this.stateManager.updateFlowRun(runId, {
+        status: 'completed', output: finalOutput, completedAt: new Date().toISOString(),
+      });
+      this.broadcastFlowUpdate(sessionId, { type: 'flow_run_completed', runId, flowId: run.flowId, output: finalOutput });
+      this.activeExecutions.delete(runId);
+      return { runId, status: 'completed', output: finalOutput };
+    } catch (error) {
+      this.logger.error(`Flow resume failed: ${run.flowId}`, { runId, error: error.message });
+      await this.stateManager.updateFlowRun(runId, {
+        status: 'failed', error: error.message, completedAt: new Date().toISOString(),
+      });
+      this.broadcastFlowUpdate(sessionId, { type: 'flow_run_failed', runId, flowId: run.flowId, error: error.message });
+      this.activeExecutions.delete(runId);
+      return { runId, status: 'failed', error: error.message };
+    }
+  }
+
   /**
    * Stop a flow execution
    * @param {string} runId - Run identifier
@@ -210,6 +392,21 @@ class FlowExecutor {
   async ensureAgentsLoaded(nodes) {
     if (!nodes || nodes.length === 0) return;
 
+    // First: surface ALL agent nodes that have no agentId at all (e.g.
+    // a template was loaded but the user hasn't picked agents yet).
+    // Better one clear "you haven't filled in N agents yet" than a
+    // confusing chain of partial loads followed by a "name === ''" error.
+    const unbound = nodes.filter(n =>
+      n.type === 'agent' &&
+      (typeof n.data?.agentId !== 'string' || n.data.agentId.trim().length === 0)
+    );
+    if (unbound.length > 0) {
+      const labels = unbound.map(n => n.data?.label || n.id).join(', ');
+      throw new Error(
+        `Cannot run flow: ${unbound.length} agent node(s) have no agent assigned (${labels}). Open each node and pick an agent in the properties panel.`
+      );
+    }
+
     // Extract agent IDs from agent nodes
     const agentNodes = nodes.filter(n => n.type === 'agent' && n.data?.agentId);
     const agentIds = [...new Set(agentNodes.map(n => n.data.agentId))];
@@ -235,18 +432,33 @@ class FlowExecutor {
         const agent = await this.stateManager.importArchivedAgent(agentId, projectDir, this.agentPool);
         this.logger.info(`Successfully loaded agent: ${agentId}`);
 
-        // Broadcast agent-loaded event so UI sidebar updates
+        // Broadcast agent-loaded event so UI sidebar updates.
+        // Defensive: this is pure UX — it must NEVER kill the load.
+        // The WebServer instance exposes broadcastToSession(null, msg)
+        // for "broadcast to all"; some other manager shapes use
+        // broadcast(msg). Use whichever is available, swallow errors.
         if (this.webSocketManager && agent) {
-          this.webSocketManager.broadcast({
-            type: 'agent-loaded',
-            agent: {
-              id: agent.id,
-              name: agent.name,
-              status: agent.status,
-              model: agent.currentModel || agent.preferredModel,
-              capabilities: agent.capabilities
+          try {
+            const msg = {
+              type: 'agent-loaded',
+              agent: {
+                id: agent.id,
+                name: agent.name,
+                status: agent.status,
+                model: agent.currentModel || agent.preferredModel,
+                capabilities: agent.capabilities,
+              },
+            };
+            if (typeof this.webSocketManager.broadcast === 'function') {
+              this.webSocketManager.broadcast(msg);
+            } else if (typeof this.webSocketManager.broadcastToSession === 'function') {
+              this.webSocketManager.broadcastToSession(null, msg);
             }
-          });
+          } catch (broadcastErr) {
+            this.logger.warn(`Failed to broadcast agent-loaded event (non-fatal)`, {
+              agentId, error: broadcastErr.message,
+            });
+          }
         }
       } catch (error) {
         throw new Error(`Failed to load agent ${agentId}: ${error.message}. Make sure the agent exists.`);
@@ -413,13 +625,25 @@ class FlowExecutor {
       return result;
 
     } catch (error) {
-      await this.updateNodeState(runId, node.id, 'failed', { error: error.message });
+      // Phase 6.1: capture structured error info — kind classification
+      // (timeout / agent-error / agent-failure) + per-attempt history
+      // (from runWithRetry). Persisted on the node state so the run-
+      // detail UI can show "node-B timed out after 3 attempts" without
+      // re-parsing log files.
+      const errorInfo = {
+        kind: error?.kind || 'agent-error',
+        message: error?.message || String(error),
+        attempts: error?.attempts || null,
+        lastAt: new Date().toISOString(),
+      };
+      await this.updateNodeState(runId, node.id, 'failed', { error: error.message }, errorInfo);
       this.broadcastFlowUpdate(sessionId, {
         type: 'flow_node_failed',
         runId,
         nodeId: node.id,
         nodeType: node.type,
-        error: error.message
+        error: error.message,
+        errorInfo,
       });
       throw error;
     }
@@ -467,17 +691,38 @@ class FlowExecutor {
       throw new Error(`Agent not found: ${agentId}`);
     }
 
-    // Get input from previous nodes
+    // ---- Phase 1: typed-input assembly ---------------------------------
+    // For v2 nodes (with declared inputs[]), assemble typed values from
+    // upstream outputs by following the edge field mappings. For legacy
+    // nodes (no inputs[]), this falls back to {input, previousOutput}
+    // built by concatenating upstream outputs — identical to v1 behavior.
+    const assembled = assembleNodeInputs(node, flow.edges, context.nodeOutputs);
+
+    if (!assembled.legacy && assembled.missing.length > 0) {
+      // v2 fail-fast: a required input has no upstream value. Better to
+      // bail here with a clear error than send the agent half its data.
+      throw new Error(
+        `Agent node ${node.id} (${agentId}) is missing required input(s): ${assembled.missing.join(', ')}`
+      );
+    }
+
+    // Legacy fallback also exposes inputNodeIds + previousOutput for the
+    // existing buildPreviousAgentData / context-injection code paths.
     const inputNodeIds = this.getInputNodeIds(node.id, flow.edges);
-    const previousOutput = this.collectPreviousOutput(inputNodeIds, context.nodeOutputs);
+    const previousOutput = assembled.legacy
+      ? assembled.values.previousOutput
+      : this.collectPreviousOutput(inputNodeIds, context.nodeOutputs);
 
-    // Apply prompt template
+    // Apply prompt template. Typed input values are exposed BY NAME so
+    // templates can write {{topic}}, {{research}}, etc. Legacy keys
+    // {{input}} / {{previousOutput}} stay available for backwards compat.
     const template = node.data?.promptTemplate || '{{input}}';
     const prompt = this.applyTemplate(template, {
       input: previousOutput,
       previousOutput,
       ...context.variables,
-      ...context.nodeOutputs
+      ...context.nodeOutputs,
+      ...assembled.values,            // typed inputs win over collisions
     });
 
     this.logger.info(`Sending message to agent: ${agentId}`, {
@@ -485,66 +730,252 @@ class FlowExecutor {
       nodeId: node.id
     });
 
-    // Store current agent mode to restore later
-    const originalMode = agent.mode;
-
-    // Reset completion state from any previous run, then put in AGENT mode
-    agent.autonomousWorkComplete = false;
-    agent.lastCompletionSummary = null;
-    agent.lastCompletionDetails = null;
-    agent.mode = AGENT_MODES.AGENT;
-    await this.agentPool.persistAgentState(agentId);
-
-    // Clear conversation history for a fresh execution context
-    try {
-      await this.agentPool.clearConversation(agentId);
-      this.logger.info(`Cleared conversation for agent ${agentId} before flow execution`);
-    } catch (error) {
-      this.logger.warn(`Failed to clear conversation for agent ${agentId}`, { error: error.message });
-    }
-
-    // Create completion promise
-    const completionPromise = this.waitForAgentCompletion(agentId, runId);
-
-    // Build flow metadata for context injection
+    // Build flow metadata + previous-agent data ONCE — reused per retry
     const sortedNodes = context.sortedNodes || [];
     const nodePosition = sortedNodes.findIndex(n => n.id === node.id) + 1;
     const flowMetadata = {
       flowId: flow.id,
       flowName: flow.name || 'Unnamed Flow',
+      // Phase 7: forward flow.description so system prompt can render
+      // a "FLOW GOAL" section orienting each agent to the bigger picture.
+      flowDescription: flow.description,
       nodeName: node.data?.label || 'Agent',
       nodePosition: nodePosition || 1,
       totalNodes: sortedNodes.length
     };
-
-    // Build previous agent data for context passing
     const previousAgentData = this.buildPreviousAgentData(node, context, flow);
 
-    this.logger.info(`Flow context for agent ${agentId}`, {
-      flowMetadata,
-      hasPreviousAgent: !!previousAgentData,
-      previousAgentId: previousAgentData?.agentId
-    });
+    // v2: derive the node's typed I/O contract for system-prompt
+    // advertisement (handled downstream in agentScheduler). v1 nodes
+    // don't have inputs/outputs declared → contract is undefined and
+    // the scheduler skips the contract section.
+    // Phase 7: also forward node.data.instructions (the per-node role
+    // + success-criteria description) so the prompt can render a
+    // NODE INSTRUCTIONS section.
+    const hasTypedIO = Array.isArray(node.inputs) || Array.isArray(node.outputs);
+    const hasInstructions = typeof node.data?.instructions === 'string' && node.data.instructions.trim().length > 0;
+    const nodeContract = (hasTypedIO || hasInstructions)
+      ? {
+          inputs: node.inputs || [],
+          outputs: node.outputs || [],
+          instructions: node.data?.instructions,
+          // Phase 8: opt-out flag — when true, scheduler keeps the
+          // agent's native system prompt and APPENDS flow context
+          // (legacy behavior). When false/absent, scheduler REPLACES
+          // the system prompt with a flow-worker version, eliminating
+          // identity conflicts.
+          useNativeSystemPrompt: node.data?.useNativeSystemPrompt === true,
+        }
+      : undefined;
+
+    // ---- Phase 3: per-node retry + per-node timeout -------------------
+    // The closure below is "one full agent invocation" — clear conv,
+    // queue message, wait for jobdone, validate outputs. Each retry is
+    // a brand-new invocation with the agent's conversation reset.
+    // Precedence: node.execution > flow.execution > config.flows.execution > defaults.
+    const exec = this._resolveExecutionConfig(node, flow);
+
+    // Store original mode for potential restoration on hard fail (not
+    // currently restored — same as pre-Phase 3 behavior — but useful
+    // to capture if we add cleanup).
+    const originalMode = agent.mode; // eslint-disable-line no-unused-vars
+
+    // Compute the list of missing required outputs given a job-done result.
+    // Returns [] when contract is satisfied (or no contract). Used both
+    // inside attemptOnce (to drive in-conversation re-prompts) and once
+    // more after the retry loop as a defensive belt-and-suspenders check.
+    const detectMissingOutputs = (result) => {
+      if (!nodeContract || !Array.isArray(nodeContract.outputs) || nodeContract.outputs.length === 0) return [];
+      const provided = (result?.outputs && typeof result.outputs === 'object') ? result.outputs : {};
+      const missing = [];
+      for (const decl of nodeContract.outputs) {
+        if (!decl || typeof decl.name !== 'string') continue;
+        if (!(decl.name in provided) || provided[decl.name] === null || provided[decl.name] === undefined) {
+          missing.push(decl.name);
+        }
+      }
+      return missing;
+    };
 
-    // Queue message to agent with enhanced flow context
-    await this.messageProcessor.processMessage(agentId, prompt, {
-      sessionId,
-      isFlowExecution: true,
-      flowRunId: runId,
-      flowNodeId: node.id,
-      flowMetadata,
-      previousAgentData
-    });
+    // Build a corrective re-prompt that lists EXACTLY which fields are
+    // missing and shows the JSON shape the agent must emit on the next
+    // job-done. This is sent in the SAME conversation — the agent keeps
+    // its working memory and just patches the handoff.
+    const MAX_REPROMPTS_PER_ATTEMPT = 2;
+    const buildRepromptMessage = (missing) => {
+      // Phase 7: enrich the corrective message with each declared
+      // output's description + example so the agent has the FULL
+      // contract to satisfy on the retry, not just a list of names.
+      const required = nodeContract.outputs.map(o => {
+        const lines = [`  • ${o.name}: ${o.type}`];
+        if (typeof o.description === 'string' && o.description.trim()) {
+          lines.push(`    ${o.description.trim()}`);
+        }
+        if (o.example !== undefined && o.example !== null) {
+          try {
+            const ex = (typeof o.example === 'string')
+              ? JSON.stringify(o.example)
+              : JSON.stringify(o.example, null, 2);
+            const oneLine = !ex.includes('\n');
+            lines.push(oneLine ? `    Example: ${ex}` : `    Example: ${ex.split('\n').join('\n    ')}`);
+          } catch { /* ignore unstringifiable examples */ }
+        }
+        return lines.join('\n');
+      }).join('\n');
+      const example = nodeContract.outputs
+        .map(o => `    "${o.name}": <${o.type} value>`).join(',\n');
+      return [
+        `⚠ Your previous job-done was incomplete. The flow node declares REQUIRED OUTPUTS that must all be present in the "outputs" field of job-done.`,
+        ``,
+        `Missing field(s): ${missing.join(', ')}`,
+        ``,
+        `All required outputs:`,
+        required,
+        ``,
+        `Please call job-done AGAIN with the complete payload. The "outputs" object must include EVERY field above. Example structure:`,
+        ``,
+        `{`,
+        `  "toolId": "jobdone",`,
+        `  "actions": [{`,
+        `    "action": "complete",`,
+        `    "summary": "<your summary>",`,
+        `    "outputs": {`,
+        example,
+        `    }`,
+        `  }]`,
+        `}`,
+        ``,
+        `Use the work you've already done — do not redo the task. Just emit the structured outputs.`,
+      ].join('\n');
+    };
 
-    // Wait for agent to complete (via jobdone tool)
-    const completionResult = await Promise.race([
-      completionPromise,
-      this.createTimeoutPromise(this.config.flows?.nodeTimeout || 300000) // 5 min default
-    ]);
+    const attemptOnce = async (attemptIndex) => {
+      // Phase 8: register the active contract so the jobdone tool can
+      // validate the agent's job-done call AT TOOL TIME — rejecting
+      // partial calls before they propagate. Cleared in the finally
+      // block of the outer try (see below) when the attempt completes
+      // (success OR failure).
+      if (nodeContract) {
+        this.activeContracts.set(agentId, nodeContract);
+      }
 
-    if (completionResult.timeout) {
-      throw new Error(`Agent ${agentId} timed out`);
+      // Reset completion state + conversation for a clean slate every
+      // OUTER retry. In-conversation re-prompts (below) keep history.
+      agent.autonomousWorkComplete = false;
+      agent.lastCompletionSummary = null;
+      agent.lastCompletionDetails = null;
+      agent.mode = AGENT_MODES.AGENT;
+      await this.agentPool.persistAgentState(agentId);
+      try {
+        await this.agentPool.clearConversation(agentId);
+      } catch (error) {
+        this.logger.warn(`Failed to clear conversation for agent ${agentId}`, { error: error.message });
+      }
+
+      // Register the listener BEFORE queuing the message so a fast jobdone
+      // can resolve us immediately.
+      let completionPromise = this.waitForAgentCompletion(agentId, runId);
+
+      await this.messageProcessor.processMessage(agentId, prompt, {
+        sessionId,
+        isFlowExecution: true,
+        flowRunId: runId,
+        flowNodeId: node.id,
+        flowMetadata,
+        previousAgentData,
+        nodeContract,
+        attemptIndex,
+      });
+
+      let result = await completionPromise;
+
+      // v2 in-conversation re-prompt loop: when outputs are missing, ask
+      // the agent to fix the LAST job-done call WITHOUT clearing memory.
+      // Cheap (~1 model call vs full re-run) and almost always succeeds
+      // because the agent already produced the data — they just forgot
+      // to put it in the outputs field. After MAX_REPROMPTS, we fall
+      // through to the outer retry which DOES clear conversation.
+      let reprompts = 0;
+      while (reprompts < MAX_REPROMPTS_PER_ATTEMPT) {
+        const missing = detectMissingOutputs(result);
+        if (missing.length === 0) break;
+
+        this.logger.warn(`Flow node ${node.id}: re-prompting agent for missing outputs`, {
+          missing, reprompts, attemptIndex,
+        });
+
+        // Re-arm the listener BEFORE sending — the agent's response will
+        // resolve it.
+        agent.autonomousWorkComplete = false;
+        await this.agentPool.persistAgentState(agentId);
+        completionPromise = this.waitForAgentCompletion(agentId, runId);
+
+        await this.messageProcessor.processMessage(agentId, buildRepromptMessage(missing), {
+          sessionId,
+          isFlowExecution: true,
+          flowRunId: runId,
+          flowNodeId: node.id,
+          flowMetadata,
+          previousAgentData,
+          nodeContract,
+          attemptIndex,
+          isReprompt: true,
+        });
+
+        result = await completionPromise;
+        reprompts++;
+      }
+
+      // Final check: if still missing after re-prompts, throw a retryable
+      // error so the OUTER loop (runWithRetry) starts a fresh agent
+      // invocation with cleared conversation.
+      const stillMissing = detectMissingOutputs(result);
+      if (stillMissing.length > 0) {
+        throw new FlowRetryError(
+          `Agent ${agentId} (node ${node.id}) job-done is missing required output(s) after ${reprompts} re-prompt(s): ${stillMissing.join(', ')}. ` +
+          `Declared outputs: ${nodeContract.outputs.map(o => `${o.name}:${o.type}`).join(', ')}`,
+          'agent-error'
+        );
+      }
+      return result;
+    };
+
+    let attemptHistory = [];
+    let completionResult;
+    try {
+      const ran = await runWithRetry(attemptOnce, {
+        timeoutMs: exec.timeoutMs,
+        maxRetries: exec.maxRetries,
+        retryOn: exec.retryOn,
+        backoffBaseMs: exec.backoffBaseMs,
+        backoffMultiplier: exec.backoffMultiplier,
+        onAttempt: (meta) => {
+          this.logger.warn(`Flow node ${node.id} attempt ${meta.attempt} failed`, {
+            kind: meta.error?.kind, message: meta.error?.message, willRetry: meta.willRetry,
+          });
+        },
+      });
+      completionResult = ran.result;
+      attemptHistory = ran.attempts;
+    } catch (e) {
+      // Surface the kind on the thrown error so the caller (executeFlow)
+      // and observability can distinguish timeout vs agent-error vs
+      // explicit failure.
+      const kind = e?.kind || 'agent-error';
+      const friendly = kind === 'timeout'
+        ? `Agent ${agentId} timed out (after ${exec.maxRetries + 1} attempt(s))`
+        : (e?.message || `Agent ${agentId} failed`);
+      const wrapped = new Error(friendly);
+      wrapped.kind = kind;
+      wrapped.attempts = e?.attempts;
+      // Phase 8: clear active contract on failure so the jobdone tool
+      // doesn't validate against a stale node when the agent gets used
+      // outside the flow later.
+      this.activeContracts.delete(agentId);
+      throw wrapped;
     }
+    // Phase 8: clear active contract on success too.
+    this.activeContracts.delete(agentId);
 
     // Get the agent's response (last assistant message)
     const updatedAgent = await this.agentPool.getAgent(agentId);
@@ -553,17 +984,105 @@ class FlowExecutor {
     // Extract files created during this agent's execution (from completion result or messages)
     const filesCreated = completionResult.filesCreated || this.extractFilesFromCompletion(completionResult);
 
+    // v2: outputs validation already happened inside attemptOnce; this
+    // block stays only as a defensive belt-and-suspenders for the case
+    // where attemptOnce somehow returns without outputs. Same logic.
+    if (nodeContract && Array.isArray(nodeContract.outputs) && nodeContract.outputs.length > 0) {
+      const provided = (completionResult.outputs && typeof completionResult.outputs === 'object')
+        ? completionResult.outputs : {};
+      const missing = [];
+      for (const decl of nodeContract.outputs) {
+        if (!decl || typeof decl.name !== 'string') continue;
+        if (!(decl.name in provided) || provided[decl.name] === null || provided[decl.name] === undefined) {
+          missing.push(decl.name);
+        }
+      }
+      if (missing.length > 0) {
+        throw new Error(
+          `Agent ${agentId} (node ${node.id}) job-done is missing required output(s): ${missing.join(', ')}. ` +
+          `Declared outputs: ${nodeContract.outputs.map(o => `${o.name}:${o.type}`).join(', ')}`
+        );
+      }
+    }
+
+    // Choose what becomes the legacy `output` field used by v1 handoff
+    // and the prose preview in the next agent's system prompt.
+    //
+    // Preference order:
+    //   1. summary + details (if both present, glue them)
+    //   2. lastResponse (the agent's full final assistant message)
+    //   3. summary alone
+    //   4. ''
+    //
+    // Why: tiny "Done." summaries used to flow through as the next
+    // agent's entire context — agents had nothing to work with. Falling
+    // back to the assistant's last message gives the next agent a real
+    // payload even when the upstream agent skipped `details`.
+    const summary = (completionResult.summary || '').trim();
+    const details = (completionResult.details || '').trim();
+    let prose;
+    if (summary && details) prose = `${summary}\n\n${details}`;
+    else if (summary && summary.length < 40 && lastResponse) prose = lastResponse;
+    else prose = summary || lastResponse || '';
+
     return {
       type: 'agent',
       agentId,
       agentName: agent.name,
-      output: completionResult.summary || lastResponse || '',
+      output: prose,
+      // v2: structured outputs bag — keyed by declared field name. This
+      // is what assembleNodeInputs reads when wiring the next node.
+      outputs: completionResult.outputs,
       details: completionResult.details,
       filesCreated,
+      // Phase 3: attempt history (one entry per try; failed entries
+      // include { kind, message }). Surfaces in run-detail UI later.
+      attempts: attemptHistory,
       success: completionResult.success !== false
     };
   }
 
+  /**
+   * Resolve effective per-node execution config — timeout, retries,
+   * backoff, retryOn classes. Precedence (highest wins):
+   *   node.execution > flow.execution > config.flows.execution > defaults
+   *
+   * Defaults:
+   *   timeoutMs        300000 (5min, matches pre-Phase-3 behavior; legacy
+   *                    config.flows.nodeTimeout still honored as a global
+   *                    timeout for back-compat)
+   *   maxRetries       1      (one fresh-conversation retry after re-prompts
+   *                            exhaust — without this, structured-output
+   *                            misses by some models cause flow failure
+   *                            after only 2 in-conversation re-prompts).
+   *                            Override per node to 0 to disable retries.
+   *   retryOn          ['timeout', 'agent-error']
+   *   backoffBaseMs    1000
+   *   backoffMultiplier 2
+   */
+  _resolveExecutionConfig(node, flow) {
+    const globalCfg = this.config?.flows?.execution || {};
+    const flowCfg   = flow?.execution || {};
+    const nodeCfg   = node?.execution || {};
+    // Legacy: config.flows.nodeTimeout was the only knob in v1. Keep
+    // it as the default timeout if more-specific configs aren't set.
+    const legacyTimeout = this.config?.flows?.nodeTimeout;
+
+    const pick = (k, fallback) =>
+      nodeCfg[k] !== undefined ? nodeCfg[k] :
+      flowCfg[k] !== undefined ? flowCfg[k] :
+      globalCfg[k] !== undefined ? globalCfg[k] :
+      fallback;
+
+    return {
+      timeoutMs:         pick('timeoutMs', legacyTimeout ?? 300000),
+      maxRetries:        pick('maxRetries', 1),
+      retryOn:           pick('retryOn', ['timeout', 'agent-error']),
+      backoffBaseMs:     pick('backoffBaseMs', 1000),
+      backoffMultiplier: pick('backoffMultiplier', 2),
+    };
+  }
+
   /**
    * Build previous agent data for context passing to next agent
    * @param {Object} currentNode - Current agent node
@@ -575,25 +1094,52 @@ class FlowExecutor {
     // Find the previous agent node that feeds into this one
     const inputNodeIds = this.getInputNodeIds(currentNode.id, flow.edges);
 
-    // Look for the most recent agent node in the inputs
+    // Look for the most recent agent node in the inputs.
+    // We collect ALL upstream agent contributions (not just one) so a
+    // node fed by multiple agents gets a merged outputs bag and a
+    // labeled list of contributors. v1 fallback: pick the first.
+    const contributors = [];
     for (const inputId of inputNodeIds) {
       const nodeOutput = context.nodeOutputs[inputId];
-
-      // Check if this is an agent node output
-      if (nodeOutput && nodeOutput.type === 'agent') {
-        return {
-          agentId: nodeOutput.agentId,
-          agentName: nodeOutput.agentName || nodeOutput.agentId,
-          summary: nodeOutput.output,
-          details: nodeOutput.details,
-          filesCreated: nodeOutput.filesCreated || [],
-          output: nodeOutput.output
-        };
+      if (nodeOutput && nodeOutput.type === 'agent') contributors.push(nodeOutput);
+    }
+    if (contributors.length === 0) return null;
+
+    // Merge structured outputs from all contributors. When the same
+    // field name appears on multiple upstream agents, the LATER one
+    // wins (sortedNodes order in context.sortedNodes is topological).
+    const mergedOutputs = {};
+    for (const c of contributors) {
+      if (c.outputs && typeof c.outputs === 'object') {
+        Object.assign(mergedOutputs, c.outputs);
       }
     }
 
-    // No previous agent found (first agent in flow or only non-agent predecessors)
-    return null;
+    // Primary "previous agent" used for the legacy fields stays the
+    // most recent contributor (last one in topo order).
+    const primary = contributors[contributors.length - 1];
+
+    return {
+      agentId: primary.agentId,
+      agentName: primary.agentName || primary.agentId,
+      summary: primary.output,
+      details: primary.details,
+      filesCreated: primary.filesCreated || [],
+      output: primary.output,
+      // Phase 5/6 fix: forward the structured outputs bag end-to-end.
+      // Without this the next agent never sees the typed handoff —
+      // only the free-text summary, defeating the whole v2 contract.
+      outputs: Object.keys(mergedOutputs).length > 0 ? mergedOutputs : undefined,
+      // When multiple agents fed this node, list them so the system
+      // prompt can show "you received outputs from agents A, B".
+      contributors: contributors.length > 1
+        ? contributors.map(c => ({
+            agentId: c.agentId,
+            agentName: c.agentName || c.agentId,
+            outputs: c.outputs || null,
+          }))
+        : undefined,
+    };
   }
 
   /**
@@ -736,6 +1282,9 @@ class FlowExecutor {
           completed: true,
           summary: completionData.summary || '',
           details: completionData.details || null,
+          // v2: structured outputs bag — forwarded through to the
+          // executor's contract validator. v1 callers don't set this.
+          outputs: completionData.outputs,
           success: completionData.success !== false
         });
         return true;
@@ -838,22 +1387,32 @@ class FlowExecutor {
   }
 
   /**
-   * Update node state in the run record
-   * @param {string} runId - Run ID
-   * @param {string} nodeId - Node ID
-   * @param {string} status - Node status
-   * @param {Object} result - Node result
+   * Update node state in the run record.
+   *
+   * Phase 6.1: optional `errorInfo` captures classified failure detail
+   * (kind, message, attempts) for run-detail diagnostics. Stored as
+   * `nodeStates[id].error` alongside the truncated result.
+   *
+   * @param {string} runId
+   * @param {string} nodeId
+   * @param {string} status      'running' | 'completed' | 'failed'
+   * @param {Object} result
+   * @param {Object} [errorInfo] { kind, message, attempts, lastAt }
    */
-  async updateNodeState(runId, nodeId, status, result) {
+  async updateNodeState(runId, nodeId, status, result, errorInfo) {
     const run = await this.stateManager.getFlowRun(runId);
     if (!run) return;
 
     const nodeStates = run.nodeStates || {};
-    nodeStates[nodeId] = {
+    const entry = {
       status,
       result: result ? this.truncateOutput(result) : null,
       updatedAt: new Date().toISOString()
     };
+    if (errorInfo && typeof errorInfo === 'object') {
+      entry.error = errorInfo;
+    }
+    nodeStates[nodeId] = entry;
 
     await this.stateManager.updateFlowRun(runId, { nodeStates });
   }
@@ -874,7 +1433,16 @@ class FlowExecutor {
   }
 
   /**
-   * Truncate output for storage/transmission
+   * Truncate output for storage/transmission.
+   *
+   * Special-case: when the output is an agent completion result with a
+   * structured `outputs` field, preserve the `outputs` object verbatim.
+   * Those are the typed contract values that downstream nodes consume —
+   * truncating them silently breaks edge field-mapping (`writer.bullets
+   * → critic.bullets` would deliver a string-truncation marker instead
+   * of the real list). Long prose lives in `output` / `summary` /
+   * `details`; those get the legacy string truncation.
+   *
    * @param {Object} output - Output to truncate
    * @returns {Object} Truncated output
    */
@@ -882,7 +1450,21 @@ class FlowExecutor {
     if (typeof output === 'string' && output.length > 1000) {
       return output.substring(0, 1000) + '... (truncated)';
     }
-    if (typeof output === 'object') {
+    if (output && typeof output === 'object') {
+      // Agent-completion shape: preserve structured `outputs`, truncate
+      // only the long prose fields. Keeps the run dump useful for
+      // post-mortem inspection AND keeps downstream edges working.
+      const hasStructuredOutputs = output.outputs && typeof output.outputs === 'object';
+      if (hasStructuredOutputs) {
+        const trunc = { ...output };
+        for (const k of ['output', 'summary', 'details']) {
+          if (typeof trunc[k] === 'string' && trunc[k].length > 1000) {
+            trunc[k] = trunc[k].substring(0, 1000) + '... (truncated)';
+          }
+        }
+        // outputs object preserved as-is; it's structured contract data.
+        return trunc;
+      }
       const str = JSON.stringify(output);
       if (str.length > 1000) {
         return { truncated: true, preview: str.substring(0, 1000) };