onbuzz 4.4.0 → 4.6.0

package/src/interfaces/agentContextRoutes.js

@@ -0,0 +1,257 @@
+/**
+ * Agent context + memory routes.
+ *
+ * Powers the "Memory" tab in the AgentEditModal. Three concerns:
+ *
+ *   1. Memory catalog CRUD — backed by MemoryService.
+ *      GET    /api/agents/:agentId/memories
+ *      POST   /api/agents/:agentId/memories
+ *      PUT    /api/agents/:agentId/memories/:memoryId
+ *      DELETE /api/agents/:agentId/memories/:memoryId
+ *
+ *   2. Live "what would be sent to the model on the next turn" snapshot —
+ *      the full system prompt (with all tool/capability injections), the
+ *      message array assembled by agentPool.getMessagesForAI, and the
+ *      pending message queues that haven't been folded in yet.
+ *      GET /api/agents/:agentId/context-snapshot
+ *
+ *   3. Future: any other "lives inside the context window" data
+ *      (compaction state, working dir, persisted skills, …) gets added
+ *      here as a single read-only window into agent state.
+ *
+ * Extracted as a module (not inline in webServer.js) so the routes are
+ * testable in isolation against a fake express + injected dependencies,
+ * mirroring the schedulerRoutes / widget routes pattern.
+ */
+
+/**
+ * @param {object} app                 express app
+ * @param {object} deps
+ * @param {() => object|null} deps.getAgentPool   resolve agentPool at request time
+ * @param {(logger?) => object} deps.getMemoryService  memory service factory
+ * @param {object} [deps.logger]
+ */
+export function registerAgentContextRoutes(app, deps = {}) {
+  if (!app) return;
+  const getAgentPool = typeof deps.getAgentPool === 'function' ? deps.getAgentPool : () => null;
+  const getMemoryService = typeof deps.getMemoryService === 'function' ? deps.getMemoryService : null;
+  const logger = deps.logger || { error: () => {}, warn: () => {} };
+
+  if (!getMemoryService) {
+    // Module is wired up but no memory service available — bail gracefully.
+    // Routes will return 503 below; we don't even register them.
+    return;
+  }
+
+  // ── Memory CRUD ─────────────────────────────────────────────────────
+
+  // GET /api/agents/:agentId/memories — full memory objects (content + metadata).
+  app.get('/api/agents/:agentId/memories', async (req, res) => {
+    try {
+      const { agentId } = req.params;
+      if (!agentId) return res.status(400).json({ success: false, error: 'agentId is required' });
+      const svc = getMemoryService(logger);
+      const memories = await svc.loadMemories(agentId);
+      res.json({ success: true, count: memories.length, memories });
+    } catch (err) {
+      logger.error('[agentContext] list memories failed', { error: err?.message });
+      res.status(500).json({ success: false, error: err?.message || 'unknown' });
+    }
+  });
+
+  // POST /api/agents/:agentId/memories — add memory.
+  // Body: { title (required), description?, content (required), expiration? }
+  app.post('/api/agents/:agentId/memories', async (req, res) => {
+    try {
+      const { agentId } = req.params;
+      const { title, description, content, expiration } = req.body || {};
+      if (!agentId) return res.status(400).json({ success: false, error: 'agentId is required' });
+      if (typeof title !== 'string' || !title.trim()) {
+        return res.status(400).json({ success: false, error: 'title (non-empty string) is required' });
+      }
+      if (typeof content !== 'string' || !content.trim()) {
+        return res.status(400).json({ success: false, error: 'content (non-empty string) is required' });
+      }
+      const svc = getMemoryService(logger);
+      const memory = await svc.addMemory(agentId, {
+        title: title.trim(),
+        description: typeof description === 'string' ? description.trim() : '',
+        content,
+        expiration,
+      });
+      res.json({ success: true, memory });
+    } catch (err) {
+      logger.error('[agentContext] add memory failed', { error: err?.message });
+      res.status(500).json({ success: false, error: err?.message || 'unknown' });
+    }
+  });
+
+  // PUT /api/agents/:agentId/memories/:memoryId — update memory.
+  // Body: any subset of { title, description, content, expiration }.
+  app.put('/api/agents/:agentId/memories/:memoryId', async (req, res) => {
+    try {
+      const { agentId, memoryId } = req.params;
+      if (!agentId || !memoryId) {
+        return res.status(400).json({ success: false, error: 'agentId and memoryId are required' });
+      }
+      const updates = req.body || {};
+      const svc = getMemoryService(logger);
+      const memory = await svc.updateMemory(agentId, memoryId, updates);
+      if (!memory) return res.status(404).json({ success: false, error: `Memory not found: ${memoryId}` });
+      res.json({ success: true, memory });
+    } catch (err) {
+      logger.error('[agentContext] update memory failed', { error: err?.message });
+      res.status(500).json({ success: false, error: err?.message || 'unknown' });
+    }
+  });
+
+  // DELETE /api/agents/:agentId/memories/:memoryId — delete memory.
+  app.delete('/api/agents/:agentId/memories/:memoryId', async (req, res) => {
+    try {
+      const { agentId, memoryId } = req.params;
+      if (!agentId || !memoryId) {
+        return res.status(400).json({ success: false, error: 'agentId and memoryId are required' });
+      }
+      const svc = getMemoryService(logger);
+      const ok = await svc.deleteMemory(agentId, memoryId);
+      if (!ok) return res.status(404).json({ success: false, error: `Memory not found: ${memoryId}` });
+      res.json({ success: true });
+    } catch (err) {
+      logger.error('[agentContext] delete memory failed', { error: err?.message });
+      res.status(500).json({ success: false, error: err?.message || 'unknown' });
+    }
+  });
+
+  // ── Context snapshot ────────────────────────────────────────────────
+
+  // GET /api/agents/:agentId/context-snapshot — atomic read-only view of
+  // everything "live in the context window" for this agent right now:
+  //   - systemPrompt.original = user-authored prompt
+  //   - systemPrompt.full     = enhanced prompt with all tool injections
+  //   - messages              = exactly what getMessagesForAI returns
+  //                             (i.e. what would be sent on the next turn)
+  //   - pendingQueues         = msg queues not yet folded into the
+  //                             conversation history
+  //   - stats                 = sizes, counts, model id
+  app.get('/api/agents/:agentId/context-snapshot', async (req, res) => {
+    try {
+      const { agentId } = req.params;
+      if (!agentId) return res.status(400).json({ success: false, error: 'agentId is required' });
+
+      const agentPool = getAgentPool();
+      if (!agentPool || typeof agentPool.getAgent !== 'function') {
+        return res.status(503).json({ success: false, error: 'agent pool not available' });
+      }
+
+      const agent = await agentPool.getAgent(agentId);
+      if (!agent) return res.status(404).json({ success: false, error: `Agent not found: ${agentId}` });
+
+      // System prompt — both forms. `systemPrompt` is the enhanced one
+      // (with tool descriptions injected); `originalSystemPrompt` is the
+      // user-authored version. Showing both lets the user understand
+      // exactly what the model sees vs what they typed.
+      const original = agent.originalSystemPrompt || agent.systemPrompt || '';
+      const full     = agent.systemPrompt || original;
+
+      // Messages prepared for the next turn. getMessagesForAI is the
+      // exact function the scheduler calls right before sending; this
+      // is the source of truth for "what would the model see now?".
+      const modelId = agent.currentModel || agent.preferredModel;
+      let messages = [];
+      let messagesError = null;
+      if (modelId && typeof agentPool.getMessagesForAI === 'function') {
+        try {
+          messages = await agentPool.getMessagesForAI(agentId, modelId);
+        } catch (e) {
+          // Don't fail the whole snapshot — surface the error inline so
+          // the user can see "messages couldn't be assembled" without
+          // losing the system-prompt + queue views.
+          messagesError = e?.message || String(e);
+        }
+      }
+
+      // Per-message lightweight projection — strip enormous tool output
+      // bodies so the snapshot is bounded. Caller can re-query with a
+      // "give me message X in full" path if/when we add it.
+      const MAX_PREVIEW = 4000;
+      const projection = (Array.isArray(messages) ? messages : []).map((m, i) => {
+        const content = typeof m.content === 'string' ? m.content : safeStringify(m.content);
+        const truncated = content.length > MAX_PREVIEW;
+        return {
+          index: i,
+          role: m.role,
+          name: m.name || null,
+          contentPreview: truncated ? content.slice(0, MAX_PREVIEW) : content,
+          contentLength: content.length,
+          truncated,
+          timestamp: m.timestamp || null,
+          hasToolCalls: !!(m.toolCalls || m.tool_calls),
+          toolCallId: m.toolCallId || m.tool_call_id || null,
+        };
+      });
+
+      // Pending queues — what's waiting to be folded in but isn't yet.
+      const queues = agent.messageQueues || {};
+      const queueProjection = (arr, kind) => (Array.isArray(arr) ? arr : []).map((m, i) => ({
+        index: i,
+        kind,
+        contentPreview: safePreview(m?.content ?? m?.message ?? m?.text ?? '', 200),
+        timestamp: m?.timestamp || null,
+      }));
+
+      const totalSystemPromptLen = full.length;
+      const totalMessageLen = projection.reduce((acc, m) => acc + (m.contentLength || 0), 0);
+      // Rough token estimate (≈ 4 chars / token). Cheap and good enough
+      // for the UI bar; the model-side accounting still uses real tokenizers.
+      const estimatedTokens = Math.ceil((totalSystemPromptLen + totalMessageLen) / 4);
+
+      res.json({
+        success: true,
+        agent: {
+          id: agent.id,
+          name: agent.name,
+          mode: agent.mode,
+          status: agent.status,
+          currentModel: agent.currentModel || null,
+          preferredModel: agent.preferredModel || null,
+        },
+        systemPrompt: {
+          original,
+          full,
+          enhancementBytes: Math.max(0, full.length - original.length),
+          originalLength: original.length,
+          fullLength: full.length,
+        },
+        messages: projection,
+        messagesError,
+        pendingQueues: {
+          userMessages:       queueProjection(queues.userMessages,       'user'),
+          interAgentMessages: queueProjection(queues.interAgentMessages, 'inter-agent'),
+          toolResults:        queueProjection(queues.toolResults,        'tool-result'),
+        },
+        stats: {
+          messageCount: projection.length,
+          totalMessageBytes: totalMessageLen,
+          estimatedTokens,
+          generatedAt: new Date().toISOString(),
+        },
+      });
+    } catch (err) {
+      logger.error('[agentContext] snapshot failed', { error: err?.message });
+      res.status(500).json({ success: false, error: err?.message || 'unknown' });
+    }
+  });
+}
+
+function safeStringify(v) {
+  if (v == null) return '';
+  try { return typeof v === 'string' ? v : JSON.stringify(v); }
+  catch { return String(v); }
+}
+
+function safePreview(v, max) {
+  const s = safeStringify(v);
+  return s.length > max ? s.slice(0, max) : s;
+}
+
+export default { registerAgentContextRoutes };

package/src/interfaces/webServer.js

@@ -43,9 +43,20 @@ import { initFileExplorerModule } from '../modules/fileExplorer/index.js';
 
 // Import FlowExecutor for flow pipeline execution
 import FlowExecutor from '../core/flowExecutor.js';
+// Flow definition gate — rejects malformed flows BEFORE persistence/execution.
+import { validateFlowDefinition } from '../core/flowSchema.js';
+// Phase 4: disk checkpoint store backs resume/restart of failed runs.
+import { FlowCheckpointStore } from '../core/flowCheckpointStore.js';
+// Phase 5: editor lint — soft warnings (unbound placeholders, etc.)
+import { lintFlow } from '../core/flowLint.js';
+// Phase 6: append-only flow version archive (rollback support).
+import { FlowVersionStore } from '../core/flowVersionStore.js';
 
 // Scheduler visualizer routes (extracted for testability)
 import { registerSchedulerRoutes } from './schedulerRoutes.js';
+// Agent memory + context-snapshot routes — power the Memory tab in AgentEditModal.
+import { registerAgentContextRoutes } from './agentContextRoutes.js';
+import { getMemoryService } from '../services/memoryService.js';
 
 const __filename = fileURLToPath(import.meta.url);
 const __dirname = path.dirname(__filename);
@@ -533,6 +544,39 @@ class WebServer {
       // WebServer has broadcastToSession method that FlowExecutor will use
       this.flowExecutor.setWebSocketManager(this);
 
+      // Phase 4: wire a disk checkpoint store so failed/interrupted
+      // flow runs can be resumed instead of starting over from scratch.
+      // Stored under the user data dir alongside agent state so the
+      // data survives `npm i -g` updates and follows the user across
+      // working-directory changes. (Earlier code read `dataPaths?.dataDir`
+      // which doesn't exist on getUserDataPaths() — that fell through to
+      // process.cwd() and dropped checkpoints into whatever directory the
+      // process happened to start in. Use `state` instead, grouping with
+      // agents/, operations/, models/, skills/.)
+      try {
+        const dataPaths = getUserDataPaths();
+        const checkpointDir = path.join(dataPaths?.state || process.cwd(), 'flow-checkpoints');
+        const store = new FlowCheckpointStore({ baseDir: checkpointDir });
+        this.flowExecutor.setCheckpointStore(store);
+        this.logger.info('FlowExecutor checkpoint store enabled', { baseDir: checkpointDir });
+      } catch (err) {
+        // Non-fatal: continue without resumability rather than failing init.
+        this.logger.warn('Failed to enable flow checkpoint store (non-fatal)', { error: err.message });
+      }
+
+      // Phase 6: wire a version store so every flow save records an
+      // immutable snapshot. Used by /api/flows/:id/versions and
+      // /api/flows/:id/rollback. Stored alongside checkpoints under
+      // user data dir (see comment above for path-fix history).
+      try {
+        const dataPaths = getUserDataPaths();
+        const versionDir = path.join(dataPaths?.state || process.cwd(), 'flow-versions');
+        this.flowVersionStore = new FlowVersionStore({ baseDir: versionDir });
+        this.logger.info('Flow version store enabled', { baseDir: versionDir });
+      } catch (err) {
+        this.logger.warn('Failed to enable flow version store (non-fatal)', { error: err.message });
+      }
+
       // Wire FlowExecutor into jobDoneTool so it can signal completion directly
       const toolsRegistry = this.orchestrator?.toolsRegistry;
       if (toolsRegistry) {
@@ -3494,6 +3538,14 @@ h2{color:#16a34a;margin-bottom:.5rem;} p{color:#666;}</style></head>
       html: SCHEDULER_VIEWER_HTML,
     });
 
+    // Agent context + memory routes (Memory tab in AgentEditModal).
+    // Same thunk pattern: agentPool may be attached after route registration.
+    registerAgentContextRoutes(this.app, {
+      getAgentPool: () => this.orchestrator?.agentPool,
+      getMemoryService,
+      logger: this.logger,
+    });
+
     // ============================================
     // Artifacts API Endpoint
     // ============================================
@@ -4238,9 +4290,37 @@ h2{color:#16a34a;margin-bottom:.5rem;} p{color:#666;}</style></head>
           });
         }
 
+        // If the resilient state loader recovered from missing/empty/
+        // corrupt files, broadcast each recovery as a UI toast so the
+        // operator sees what was salvaged. The reports were attached to
+        // the restored agent in stateManager.restoreAgent.
+        const recoveries = Array.isArray(agent._restoreRecoveries) ? agent._restoreRecoveries : [];
+        if (recoveries.length > 0 && this.wsManager) {
+          for (const r of recoveries) {
+            this.wsManager.broadcast({
+              type: 'state-file-recovery',
+              level: r.kind === 'unrepairable' ? 'error'
+                   : r.kind === 'partial'      ? 'warning'
+                   : 'info',
+              agentId: agent.id,
+              agentName: agent.name,
+              recovery: {
+                kind: r.kind,
+                label: r.label,
+                message: r.message,
+                archivePath: r.archivePath || null,
+              },
+            });
+          }
+        }
+        // Strip the recovery payload before logging/serializing back to
+        // the client — it's an internal hint, not part of the agent shape.
+        delete agent._restoreRecoveries;
+
         this.logger.info('Agent imported successfully', {
           agentId: agent.id,
-          name: agent.name
+          name: agent.name,
+          recoveryCount: recoveries.length,
         });
 
         res.json({
@@ -4253,7 +4333,12 @@ h2{color:#16a34a;margin-bottom:.5rem;} p{color:#666;}</style></head>
             capabilities: agent.capabilities,
             lastActivity: agent.lastActivity
           },
-          message: `Agent ${agent.name} imported successfully`
+          message: `Agent ${agent.name} imported successfully`,
+          // Surfaced to the importer too so a non-WS client (curl) sees
+          // them in the response body.
+          ...(recoveries.length > 0 ? { recoveries: recoveries.map(r => ({
+            kind: r.kind, label: r.label, message: r.message,
+          })) } : {}),
         });
       } catch (error) {
         this.logger.error('Failed to import agent', {
@@ -4712,10 +4797,15 @@ h2{color:#16a34a;margin-bottom:.5rem;} p{color:#666;}</style></head>
       try {
         const { name, description, nodes, edges, variables } = req.body;
 
-        if (!name) {
+        // Schema gate: reject malformed flows BEFORE they reach persistence
+        // (avoids "saved but unexecutable" states). 400 with structured
+        // errors so the editor can highlight specific problems inline.
+        const validation = validateFlowDefinition({ name, nodes: nodes || [], edges: edges || [], variables });
+        if (!validation.ok) {
           return res.status(400).json({
             success: false,
-            error: 'Flow name is required'
+            error: 'Flow definition is invalid',
+            details: validation.errors
           });
         }
 
@@ -4728,6 +4818,20 @@ h2{color:#16a34a;margin-bottom:.5rem;} p{color:#666;}</style></head>
           variables
         }, projectDir);
 
+        // Phase 6: record initial version (v1). Best-effort — the flow
+        // is already saved; failing to version is a non-fatal warning.
+        // Stamp the version number back onto the flow record so runs
+        // can record which definition produced their output.
+        if (this.flowVersionStore && flow?.id) {
+          try {
+            const v = await this.flowVersionStore.recordVersion(flow.id, flow);
+            const projectDir = this.orchestrator.config.project?.directory || process.cwd();
+            await this.orchestrator.stateManager.updateFlow(flow.id, { version: v.version }, projectDir);
+            flow.version = v.version;
+          }
+          catch (e) { this.logger.warn('flow version record failed', { error: e.message }); }
+        }
+
         // Broadcast flow created event
         if (this.wsManager) {
           this.wsManager.broadcast({
@@ -4783,6 +4887,35 @@ h2{color:#16a34a;margin-bottom:.5rem;} p{color:#666;}</style></head>
         const { name, description, nodes, edges, variables } = req.body;
         const projectDir = this.orchestrator.config.project?.directory || process.cwd();
 
+        // PUT supports partial updates (e.g. just `{ nodes, edges }`
+        // when the user clicks Save in the editor). Load the existing
+        // flow and merge the patch before validating, so the schema
+        // gate sees the full resulting record — not just the diff.
+        const existing = await this.orchestrator.stateManager.getFlow(flowId, projectDir);
+        if (!existing) {
+          return res.status(404).json({ success: false, error: `Flow ${flowId} not found` });
+        }
+        const merged = {
+          ...existing,
+          ...(name        !== undefined ? { name }        : {}),
+          ...(description !== undefined ? { description } : {}),
+          ...(nodes       !== undefined ? { nodes }       : {}),
+          ...(edges       !== undefined ? { edges }       : {}),
+          ...(variables   !== undefined ? { variables }   : {}),
+        };
+
+        // Same schema gate as POST. Editing a flow into an invalid state
+        // is just as bad as creating one — both should be caught here, not
+        // 90s into a future execution.
+        const validation = validateFlowDefinition(merged);
+        if (!validation.ok) {
+          return res.status(400).json({
+            success: false,
+            error: 'Flow definition is invalid',
+            details: validation.errors
+          });
+        }
+
         const flow = await this.orchestrator.stateManager.updateFlow(flowId, {
           name,
           description,
@@ -4791,6 +4924,17 @@ h2{color:#16a34a;margin-bottom:.5rem;} p{color:#666;}</style></head>
           variables
         }, projectDir);
 
+        // Phase 6: record a new version snapshot on every PUT and
+        // stamp the new version number onto the live record.
+        if (this.flowVersionStore && flow?.id) {
+          try {
+            const v = await this.flowVersionStore.recordVersion(flow.id, flow);
+            await this.orchestrator.stateManager.updateFlow(flow.id, { version: v.version }, projectDir);
+            flow.version = v.version;
+          }
+          catch (e) { this.logger.warn('flow version record failed', { error: e.message }); }
+        }
+
         // Broadcast flow updated event
         if (this.wsManager) {
           this.wsManager.broadcast({
@@ -4945,6 +5089,140 @@ h2{color:#16a34a;margin-bottom:.5rem;} p{color:#666;}</style></head>
       }
     });
 
+    // Phase 6: list versions of a flow (lightweight metadata only).
+    this.app.get('/api/flows/:flowId/versions', async (req, res) => {
+      try {
+        if (!this.flowVersionStore) return res.status(503).json({ success: false, error: 'version store not available' });
+        const versions = await this.flowVersionStore.listVersions(req.params.flowId);
+        res.json({ success: true, data: versions });
+      } catch (error) {
+        this.logger.error('list versions failed', { error: error.message });
+        res.status(500).json({ success: false, error: error.message });
+      }
+    });
+
+    // Phase 6: read a specific version snapshot (full flow definition).
+    this.app.get('/api/flows/:flowId/versions/:version', async (req, res) => {
+      try {
+        if (!this.flowVersionStore) return res.status(503).json({ success: false, error: 'version store not available' });
+        const v = parseInt(req.params.version, 10);
+        if (!Number.isFinite(v) || v < 1) {
+          return res.status(400).json({ success: false, error: 'version must be a positive integer' });
+        }
+        const snap = await this.flowVersionStore.loadVersion(req.params.flowId, v);
+        if (!snap) return res.status(404).json({ success: false, error: 'version not found' });
+        res.json({ success: true, data: snap });
+      } catch (error) {
+        this.logger.error('load version failed', { error: error.message });
+        res.status(500).json({ success: false, error: error.message });
+      }
+    });
+
+    // Phase 6: rollback — restore version N as the live flow record.
+    // Body: { version: N }. Records ANOTHER new version after rollback
+    // so history stays append-only ("rolled back to v3" produces v(N+1)).
+    this.app.post('/api/flows/:flowId/rollback', async (req, res) => {
+      try {
+        if (!this.flowVersionStore) return res.status(503).json({ success: false, error: 'version store not available' });
+        const { flowId } = req.params;
+        const target = parseInt(req.body?.version, 10);
+        if (!Number.isFinite(target) || target < 1) {
+          return res.status(400).json({ success: false, error: 'body.version must be a positive integer' });
+        }
+        const snap = await this.flowVersionStore.loadVersion(flowId, target);
+        if (!snap) return res.status(404).json({ success: false, error: `version ${target} not found` });
+
+        // Validate the target snapshot before promoting it. A flow that
+        // passed validation when first saved may now be invalid against
+        // a newer schema — surfacing that here is better than at execute.
+        const validation = validateFlowDefinition(snap.flow);
+        if (!validation.ok) {
+          return res.status(400).json({
+            success: false,
+            error: `version ${target} fails current validation`,
+            details: validation.errors,
+          });
+        }
+
+        const projectDir = this.orchestrator.config.project?.directory || process.cwd();
+        const restored = await this.orchestrator.stateManager.updateFlow(flowId, {
+          name:        snap.flow.name,
+          description: snap.flow.description,
+          nodes:       snap.flow.nodes,
+          edges:       snap.flow.edges,
+          variables:   snap.flow.variables,
+        }, projectDir);
+
+        // Append a new version entry tagging the rollback
+        try {
+          await this.flowVersionStore.recordVersion(flowId, {
+            ...restored,
+            _rollbackOf: target,
+          });
+        } catch (e) {
+          this.logger.warn('post-rollback version record failed', { error: e.message });
+        }
+
+        if (this.wsManager) {
+          this.wsManager.broadcast({ type: 'flow-updated', flow: restored });
+        }
+        res.json({ success: true, data: restored, rolledBackTo: target });
+      } catch (error) {
+        this.logger.error('rollback failed', { error: error.message });
+        res.status(500).json({ success: false, error: error.message });
+      }
+    });
+
+    // Phase 5: dry-run / lint an unsaved flow definition.
+    // Posted body IS the flow definition (so the editor can lint
+    // unsaved drafts). Combines schema gate + lint warnings into a
+    // single report so the editor can highlight everything inline.
+    this.app.post('/api/flows/dry-run', async (req, res) => {
+      try {
+        const flow = req.body || {};
+        const validation = validateFlowDefinition(flow);
+        const lint = lintFlow(flow);
+        res.json({
+          success: true,
+          ok: validation.ok && lint.errors.length === 0,
+          schemaErrors: validation.errors,
+          lintErrors: lint.errors,
+          lintWarnings: lint.warnings,
+        });
+      } catch (error) {
+        this.logger.error('Dry-run failed', { error: error.message });
+        res.status(500).json({ success: false, error: error.message });
+      }
+    });
+
+    // Phase 4: resume a failed / interrupted flow run.
+    // Per-node checkpoints on disk let us skip already-completed nodes
+    // and re-run from the first non-completed one. The run record lives
+    // under runId regardless of the flow it belongs to, so this lookup
+    // does not require the flowId in the URL.
+    this.app.post('/api/flows/runs/:runId/resume', async (req, res) => {
+      try {
+        const { runId } = req.params;
+        const { sessionId } = req.body || {};
+        if (!this.flowExecutor) {
+          return res.status(503).json({ success: false, error: 'FlowExecutor not initialized' });
+        }
+        // Async: kick off and return immediately so the HTTP request
+        // doesn't sit open for minutes. Errors propagate via WebSocket
+        // (flow_run_failed) and the run record's status field.
+        this.flowExecutor.resumeFlow(runId, sessionId || null).catch(err => {
+          this.logger.error(`Resume flow failed for run ${runId}`, { error: err.message });
+        });
+        res.json({ success: true, runId, status: 'resuming' });
+      } catch (error) {
+        this.logger.error('Failed to resume flow run', { error: error.message, runId: req.params.runId });
+        const status = /not found/i.test(error.message) ? 404
+                     : /checkpoint store/i.test(error.message) ? 503
+                     : 500;
+        res.status(status).json({ success: false, error: error.message });
+      }
+    });
+
     // Stop a flow run
     this.app.post('/api/flows/:flowId/stop', async (req, res) => {
       try {