pgbus 0.19.4 → 0.20.1

data/lib/pgbus/mcp/server.rb

@@ -5,7 +5,8 @@ module Pgbus
     # Assembles the read-only pgbus diagnostic MCP server: registers every
     # diagnostic tool and wires a DataSource (plus the payload gate) into the
     # server context so tools never touch the database directly or leak
-    # payloads by default.
+    # payloads by default. The workflow write tools (WRITE_TOOLS, issue #550)
+    # join only when config.mcp_write_tools is true when the server is built.
     #
     # This class only builds the +MCP::Server+ instance — transport is the
     # caller's concern (Runner drives stdio). Keeping them separate means the
@@ -27,38 +28,80 @@ module Pgbus
         Tools::ThroughputTool,
         Tools::StatsTool,
         Tools::RecurringTool,
-        Tools::DeployTasksTool
+        Tools::DeployTasksTool,
+        Tools::WorkflowsTool,
+        Tools::WorkflowDetailTool,
+        Tools::WorkflowsAttentionTool,
+        Tools::WorkflowDefinitionsTool,
+        Tools::WorkflowStatsTool
       ].freeze
 
-      INSTRUCTIONS = <<~TEXT
-        Read-only diagnostic tools for a pgbus (PostgreSQL/PGMQ) deployment.
+      # The opt-in write surface (issue #180's rule: separate, explicitly
+      # opt-in, off by default). Never merged into TOOLS: with
+      # config.mcp_write_tools false these are not constructed at all.
+      WRITE_TOOLS = [
+        Tools::WorkflowResumeTool,
+        Tools::WorkflowCancelTool,
+        Tools::WorkflowSkipStepTool,
+        Tools::WorkflowResumeAtTool,
+        Tools::WorkflowRunNowTool,
+        Tools::WorkflowSignalTool
+      ].freeze
+
+      DIAGNOSTICS = <<~TEXT
+        Diagnostic tools for a pgbus (PostgreSQL/PGMQ) deployment.
         Start with pgbus_health for a one-call OK/DEGRADED/STALLED verdict,
         then drill in with pgbus_queues, pgbus_processes, pgbus_jobs,
-        pgbus_dlq, pgbus_locks, and pgbus_concurrency. No tool mutates state. Message payloads
-        are redacted unless the server was started with payloads explicitly
-        allowed.
+        pgbus_dlq, pgbus_locks, and pgbus_concurrency; workflow runs with
+        pgbus_workflows_attention, pgbus_workflows and pgbus_workflow, and how
+        each workflow class performs with pgbus_workflow_definitions and
+        pgbus_workflow_stats. Message payloads are redacted unless the server
+        was started with payloads explicitly allowed.
+      TEXT
+
+      INSTRUCTIONS = "#{DIAGNOSTICS}No tool mutates state.\n".freeze
+
+      WRITE_INSTRUCTIONS = <<~TEXT
+        The tools above do not mutate state. This server was also built with
+        config.mcp_write_tools, so pgbus_workflow_resume, pgbus_workflow_cancel,
+        pgbus_workflow_skip_step, pgbus_workflow_resume_at,
+        pgbus_workflow_run_now and pgbus_workflow_signal change one workflow
+        run each. Read the run with pgbus_workflow first, then pass a reason
+        (recorded on the run's audit trail) and expected_status (the status
+        you read): a run that has moved on by the time the call starts
+        answers ok: false and nothing is done (the check runs just before the
+        action, whose transition is guarded again under the run's row lock).
+        There are no bulk write tools: pgbus_workflows_attention groups the
+        stuck runs; list a group's runs with pgbus_workflows (status,
+        workflow_class, step, error_class) and call once per run.
       TEXT
 
       module_function
 
-      # Build an MCP::Server with all diagnostic tools registered.
+      # Build an MCP::Server with all diagnostic tools registered, plus the
+      # write tools when config.mcp_write_tools is true (read here, once).
       #
       # @param data_source [Pgbus::Web::DataSource] read layer the tools query.
       # @param allow_payloads [Boolean] when true, tools honor a per-call
       #   include_payloads flag; otherwise payloads are always redacted.
       def build(data_source: Pgbus::Web::DataSource.new, allow_payloads: false)
+        write = write_tools?
         ::MCP::Server.new(
           name: "pgbus",
           title: "Pgbus Diagnostics",
           version: Pgbus::VERSION,
-          instructions: INSTRUCTIONS,
-          tools: TOOLS.dup,
+          instructions: write ? DIAGNOSTICS + WRITE_INSTRUCTIONS : INSTRUCTIONS,
+          tools: write ? TOOLS + WRITE_TOOLS : TOOLS.dup,
           server_context: {
             data_source: data_source,
             allow_payloads: allow_payloads
           }
         )
       end
+
+      # Only a literal true turns the write tools on (validate! rejects
+      # anything else, but an app may skip validation).
+      def write_tools? = Pgbus.configuration.mcp_write_tools == true
     end
   end
 end

data/lib/pgbus/mcp/tools/deploy_tasks_tool.rb

@@ -69,16 +69,7 @@ module Pgbus
         end
         private_class_method :task_hash
 
-        # Times as ISO 8601 UTC, symbols as strings, string keys throughout.
-        def self.serialize(value)
-          case value
-          when Hash then value.to_h { |key, val| [key.to_s, serialize(val)] }
-          when Array then value.map { |val| serialize(val) }
-          when Symbol then value.to_s
-          when Time, DateTime, ActiveSupport::TimeWithZone then value.utc.iso8601
-          else value
-          end
-        end
+        def self.serialize(value) = Serialization.serialize(value)
         private_class_method :serialize
       end
     end

data/lib/pgbus/mcp/tools/workflow_cancel_tool.rb

@@ -0,0 +1,23 @@
+# frozen_string_literal: true
+
+module Pgbus
+  module MCP
+    module Tools
+      # Cancels an ongoing workflow run (issue #550). DataSource#cancel_workflow.
+      class WorkflowCancelTool < WriteTool
+        tool_name "pgbus_workflow_cancel"
+        title "Pgbus Workflow: Cancel"
+        description verb_description(:cancel, "Cancel an ongoing Pgbus::Workflow run. A cancelled run does not come back.")
+        idempotent!
+        input_schema(**workflow_input_schema)
+
+        def self.call(workflow_id:, reason:, expected_status: nil, server_context: nil)
+          perform(:cancel, workflow_id: workflow_id, reason: reason, expected_status: expected_status,
+                           server_context: server_context) do |data_source, **who|
+            data_source.cancel_workflow(workflow_id, **who)
+          end
+        end
+      end
+    end
+  end
+end

data/lib/pgbus/mcp/tools/workflow_definitions_tool.rb

@@ -0,0 +1,36 @@
+# frozen_string_literal: true
+
+module Pgbus
+  module MCP
+    module Tools
+      # Every workflow class with its runs going on now, the runs that ended
+      # in a window and the end-to-end percentiles (issue #549). Maps to
+      # DataSource#workflow_definitions, the dashboard's
+      # /pgbus/workflows/definitions.
+      class WorkflowDefinitionsTool < BaseTool
+        tool_name "pgbus_workflow_definitions"
+        title "Pgbus Workflow Definitions"
+        description <<~DESC
+          One row per Pgbus::Workflow class (every registered subclass and every class name still in pgbus_workflows): loaded (false when the class no longer loads in this app), ongoing and paused runs now, attention (runs that need a person, as pgbus_workflows_attention groups them), finished and cancelled runs that ended in the window, e2e_ms (p50/p95 of created → finished over the finished ones, with samples) and removed_in_flight ([{step, runs}] of ongoing runs still on a removed_step). window is 1h, 24h (default), 7d or 30d, capped at workflow_retention; the answer says what it read. Drill into one class with pgbus_workflow_stats.
+        DESC
+
+        input_schema(
+          properties: {
+            window: { type: "string", enum: Web::WorkflowWindow::CHOICES.keys,
+                      description: "1h, 24h (default), 7d or 30d; capped at workflow_retention." }
+          },
+          required: []
+        )
+
+        def self.call(window: nil, server_context: nil)
+          parsed = Web::WorkflowWindow.parse(window)
+          definitions = data_source_from(server_context).workflow_definitions(window: parsed)
+          rows = definitions.map { |row| WorkflowInsightsPayload.row(row) }
+          json_response(Serialization.serialize(window: parsed.to_h, definitions: rows))
+        rescue Web::WorkflowWindow::Invalid => e
+          error_response(e.message)
+        end
+      end
+    end
+  end
+end

data/lib/pgbus/mcp/tools/workflow_detail_tool.rb

@@ -0,0 +1,38 @@
+# frozen_string_literal: true
+
+module Pgbus
+  module MCP
+    module Tools
+      # One workflow run (issue #542): every attempt with its durations, the
+      # signals, the audit trail and the outside verbs its status allows.
+      # Maps to DataSource#workflow_detail.
+      class WorkflowDetailTool < BaseTool
+        tool_name "pgbus_workflow"
+        title "Pgbus Workflow"
+        description <<~DESC
+          One Pgbus::Workflow run by workflow_id: status, current step, every step attempt (newest first, at most 100) with status, outcome, scheduled/started/finished times, the waited/queued/ran/waiting durations in seconds, worker, app revision and error class; the signals delivered to it; the audit trail (event, actor, reason; newest first); available_actions (the outside verbs its status allows) and resume_action (what resume would do). Arguments, step outputs, signal payloads and error messages/backtraces are redacted unless the server allows payloads and include_payloads is set.
+        DESC
+
+        input_schema(
+          properties: {
+            workflow_id: { type: "string", description: "The run's workflow_id (a UUID)." },
+            include_payloads: {
+              type: "boolean",
+              description: "Include arguments, outputs, signal payloads and error text. Only honored when the server allows payloads."
+            }
+          },
+          required: %w[workflow_id]
+        )
+
+        def self.call(workflow_id:, include_payloads: false, server_context: nil)
+          detail = data_source_from(server_context).workflow_detail(workflow_id)
+          return error_response("Workflow #{workflow_id} not found") unless detail
+
+          allowed = payloads_allowed?(server_context, include_payloads)
+          json_response({ workflow: WorkflowPayloads.detail(detail, allowed: allowed) },
+                        server_context: server_context, include_payloads: include_payloads)
+        end
+      end
+    end
+  end
+end

data/lib/pgbus/mcp/tools/workflow_resume_at_tool.rb

@@ -0,0 +1,32 @@
+# frozen_string_literal: true
+
+module Pgbus
+  module MCP
+    module Tools
+      # Resumes a paused workflow run at a named step (issue #550).
+      # DataSource#resume_workflow_at.
+      class WorkflowResumeAtTool < WriteTool
+        tool_name "pgbus_workflow_resume_at"
+        title "Pgbus Workflow: Resume At"
+        description verb_description(
+          :resume_at, "Resume a paused Pgbus::Workflow run at the named step (pgbus_workflow lists its step_names)."
+        )
+        input_schema(
+          **workflow_input_schema(
+            properties: { step: { type: "string", minLength: 1, description: "The step to run next, e.g. capture." } },
+            required: %w[step]
+          )
+        )
+
+        def self.call(workflow_id:, reason:, step:, expected_status: nil, server_context: nil)
+          step = step.to_s.strip
+          perform(:resume_at, workflow_id: workflow_id, reason: reason, expected_status: expected_status,
+                              server_context: server_context,
+                              invalid: step.empty? ? "step must name a step" : nil) do |data_source, **who|
+            data_source.resume_workflow_at(workflow_id, step: step, **who)
+          end
+        end
+      end
+    end
+  end
+end

data/lib/pgbus/mcp/tools/workflow_resume_tool.rb

@@ -0,0 +1,24 @@
+# frozen_string_literal: true
+
+module Pgbus
+  module MCP
+    module Tools
+      # Resumes a paused workflow run (issue #550). DataSource#resume_workflow.
+      class WorkflowResumeTool < WriteTool
+        tool_name "pgbus_workflow_resume"
+        title "Pgbus Workflow: Resume"
+        description verb_description(
+          :resume, "Resume a paused Pgbus::Workflow run (pgbus_workflow's resume_action says what runs next)."
+        )
+        input_schema(**workflow_input_schema)
+
+        def self.call(workflow_id:, reason:, expected_status: nil, server_context: nil)
+          perform(:resume, workflow_id: workflow_id, reason: reason, expected_status: expected_status,
+                           server_context: server_context) do |data_source, **who|
+            data_source.resume_workflow(workflow_id, **who)
+          end
+        end
+      end
+    end
+  end
+end

data/lib/pgbus/mcp/tools/workflow_run_now_tool.rb

@@ -0,0 +1,23 @@
+# frozen_string_literal: true
+
+module Pgbus
+  module MCP
+    module Tools
+      # Sends a ready run's scheduled step now (issue #550).
+      # DataSource#run_workflow_step_now.
+      class WorkflowRunNowTool < WriteTool
+        tool_name "pgbus_workflow_run_now"
+        title "Pgbus Workflow: Run Now"
+        description verb_description(:run_now, "Run a ready Pgbus::Workflow run's scheduled step now instead of after its wait.")
+        input_schema(**workflow_input_schema)
+
+        def self.call(workflow_id:, reason:, expected_status: nil, server_context: nil)
+          perform(:run_now, workflow_id: workflow_id, reason: reason, expected_status: expected_status,
+                            server_context: server_context) do |data_source, **who|
+            data_source.run_workflow_step_now(workflow_id, **who)
+          end
+        end
+      end
+    end
+  end
+end

data/lib/pgbus/mcp/tools/workflow_signal_tool.rb

@@ -0,0 +1,77 @@
+# frozen_string_literal: true
+
+require "json"
+
+module Pgbus
+  module MCP
+    module Tools
+      # Delivers a signal to an ongoing workflow run (issue #550).
+      # DataSource#signal_workflow.
+      class WorkflowSignalTool < WriteTool
+        # Both columns are indexed; an index entry has a size limit.
+        KEY_LIMIT = 255
+
+        tool_name "pgbus_workflow_signal"
+        title "Pgbus Workflow: Signal"
+        description verb_description(
+          :signal, "Send a named signal, with an optional JSON object payload, to an ongoing Pgbus::Workflow run. " \
+                   "Pass an idempotency_key when the call may be retried: a redelivery with the same key stores " \
+                   "nothing and answers duplicate: true, but only while the run is ongoing (once it finished or " \
+                   "was cancelled, a retry answers ok: false: signal is not allowed)."
+        )
+        input_schema(
+          **workflow_input_schema(
+            properties: {
+              name: { type: "string", minLength: 1, maxLength: KEY_LIMIT,
+                      description: "The signal's name, e.g. payment_confirmed." },
+              payload: {
+                type: "object",
+                description: "The signal's payload, a JSON object of at most workflow_max_payload_size bytes."
+              },
+              idempotency_key: { type: "string", maxLength: KEY_LIMIT,
+                                 description: "Makes a retried call deliver the signal once. Blank means none." }
+            },
+            required: %w[name]
+          )
+        )
+
+        def self.call(workflow_id:, reason:, name:, payload: nil, idempotency_key: nil, expected_status: nil,
+                      server_context: nil)
+          name = name.to_s.strip
+          idempotency_key = idempotency_key.to_s.presence # blank is no key, as in Signals.deliver
+          payload = payload_object(payload)
+          perform(:signal, workflow_id: workflow_id, reason: reason, expected_status: expected_status,
+                           server_context: server_context,
+                           invalid: signal_refusal(name, idempotency_key, payload)) do |data_source, **who|
+            data_source.signal_workflow(workflow_id, name: name, payload: payload, idempotency_key: idempotency_key, **who)
+          end
+        end
+
+        # Why the signal cannot be sent as given, or nil.
+        def self.signal_refusal(name, idempotency_key, payload)
+          return "name must name a signal" if name.empty?
+          return "name must be at most #{KEY_LIMIT} characters" if name.length > KEY_LIMIT
+          return "idempotency_key must be at most #{KEY_LIMIT} characters" if idempotency_key && idempotency_key.length > KEY_LIMIT
+
+          payload if payload.is_a?(String)
+        end
+        private_class_method :signal_refusal
+
+        # The payload with string keys (as the dashboard's form sends it), or
+        # why it cannot be sent. Workflow::Payload enforces the cap again on
+        # the serialized form.
+        def self.payload_object(payload)
+          return {} if payload.nil?
+          return "payload must be a JSON object" unless payload.is_a?(Hash)
+
+          json = JSON.generate(payload)
+          limit = Pgbus.configuration.workflow_max_payload_size
+          return "payload is #{json.bytesize} bytes, over workflow_max_payload_size (#{limit})" if json.bytesize > limit
+
+          JSON.parse(json)
+        end
+        private_class_method :payload_object
+      end
+    end
+  end
+end

data/lib/pgbus/mcp/tools/workflow_skip_step_tool.rb

@@ -0,0 +1,23 @@
+# frozen_string_literal: true
+
+module Pgbus
+  module MCP
+    module Tools
+      # Skips the step a waiting workflow run waits on (issue #550).
+      # DataSource#skip_workflow_step.
+      class WorkflowSkipStepTool < WriteTool
+        tool_name "pgbus_workflow_skip_step"
+        title "Pgbus Workflow: Skip Step"
+        description verb_description(:skip, "Skip the step a waiting Pgbus::Workflow run waits on (a signal or a fan-out batch).")
+        input_schema(**workflow_input_schema)
+
+        def self.call(workflow_id:, reason:, expected_status: nil, server_context: nil)
+          perform(:skip, workflow_id: workflow_id, reason: reason, expected_status: expected_status,
+                         server_context: server_context) do |data_source, **who|
+            data_source.skip_workflow_step(workflow_id, **who)
+          end
+        end
+      end
+    end
+  end
+end

data/lib/pgbus/mcp/tools/workflow_stats_tool.rb

@@ -0,0 +1,42 @@
+# frozen_string_literal: true
+
+module Pgbus
+  module MCP
+    module Tools
+      # One workflow class's insights over a window (issue #549): its
+      # pipeline with live counts and step performance, throughput, durations,
+      # funnel and per-revision numbers. Maps to DataSource#workflow_definition,
+      # the dashboard's /pgbus/workflows/definitions/:workflow_class.
+      class WorkflowStatsTool < BaseTool
+        tool_name "pgbus_workflow_stats"
+        title "Pgbus Workflow Stats"
+        description <<~DESC
+          One Pgbus::Workflow class over a window (1h, 24h default, 7d or 30d, capped at workflow_retention). steps, in declaration order (gravestones as kind "removed"; names only the rows hold as declared: false): counts (runs sitting at the step now by run status ready/performing/waiting/paused), run_ms (p50/p95/p99 of finished_at - started_at over completed or failed attempts) and pickup_ms (p50/p95 of scheduled → started), rates (failed: an error was recorded, reattempted, skipped) and outcomes over the sample_size attempts that finished in the window; percentiles over fewer than 20 samples are noisy. Also: started/finished/cancelled, e2e_ms, duration_histogram (finished runs per created → finished range), throughput (runs started/finished/cancelled per bucket_seconds), funnel (of the runs started in the window: reached = runs with a row for the step, stopped = where each run is now by status) and by_revision (the five app revisions that finished an attempt last, newest first, totals and per step).
+        DESC
+
+        input_schema(
+          properties: {
+            workflow_class: { type: "string", description: "The class name, e.g. OrderWorkflow or Billing::OrderWorkflow." },
+            window: { type: "string", enum: Web::WorkflowWindow::CHOICES.keys,
+                      description: "1h, 24h (default), 7d or 30d; capped at workflow_retention." }
+          },
+          required: %w[workflow_class]
+        )
+
+        def self.call(workflow_class:, window: nil, server_context: nil)
+          name = workflow_class.to_s
+          unless Web::DataSource::WorkflowInsights::CLASS_NAME.match?(name)
+            return error_response("#{name.inspect} is not a class name (OrderWorkflow or Billing::OrderWorkflow)")
+          end
+
+          detail = data_source_from(server_context).workflow_definition(name, window: Web::WorkflowWindow.parse(window))
+          return error_response("No workflow class or run named #{name}") unless detail
+
+          json_response(Serialization.serialize(workflow: WorkflowInsightsPayload.row(detail)))
+        rescue Web::WorkflowWindow::Invalid => e
+          error_response(e.message)
+        end
+      end
+    end
+  end
+end

data/lib/pgbus/mcp/tools/workflows_attention_tool.rb

@@ -0,0 +1,42 @@
+# frozen_string_literal: true
+
+module Pgbus
+  module MCP
+    module Tools
+      # The dashboard's needs-attention view (issue #542): ongoing runs that
+      # wait on a person, grouped. Maps to DataSource#workflow_attention_groups.
+      class WorkflowsAttentionTool < BaseTool
+        tool_name "pgbus_workflows_attention"
+        title "Pgbus Workflows Needing Attention"
+        description <<~DESC
+          Ongoing Pgbus::Workflow runs that need a person, grouped by (workflow_class, step_name, reason, error_class): reason is paused_error, stalled, paused_manual, overdue (due but not picked up past workflow_stall_threshold) or waiting_overdue (waiting past workflow_waiting_visibility_threshold without a wait_timeout). Each group has its run count, first_seen_at/last_seen_at, the status its runs are in and the actions that status allows; total_runs sums the groups (at most 200 groups, biggest first). workflow_class narrows them to one class. The newest error message is redacted unless the server allows payloads and include_payloads is set.
+        DESC
+
+        input_schema(
+          properties: {
+            workflow_class: { type: "string", description: "Only this class's groups, e.g. OrderWorkflow." },
+            include_payloads: {
+              type: "boolean", description: "Include error messages. Only honored when the server allows payloads."
+            }
+          },
+          required: []
+        )
+
+        def self.call(workflow_class: nil, include_payloads: false, server_context: nil)
+          if workflow_class && !Web::DataSource::WorkflowInsights::CLASS_NAME.match?(workflow_class.to_s)
+            return error_response("#{workflow_class.inspect} is not a class name (OrderWorkflow or Billing::OrderWorkflow)")
+          end
+
+          groups = data_source_from(server_context).workflow_attention_groups(workflow_class: workflow_class&.to_s)
+          allowed = payloads_allowed?(server_context, include_payloads)
+
+          json_response(
+            { groups: groups.map { |group| WorkflowPayloads.group(group, allowed: allowed) },
+              total_runs: groups.sum { |group| group[:count] } },
+            server_context: server_context, include_payloads: include_payloads
+          )
+        end
+      end
+    end
+  end
+end

data/lib/pgbus/mcp/tools/workflows_tool.rb

@@ -0,0 +1,60 @@
+# frozen_string_literal: true
+
+module Pgbus
+  module MCP
+    module Tools
+      # Workflow runs, filtered like the dashboard's /pgbus/workflows (issue
+      # #542). Maps to DataSource#workflows and #workflows_count; the filters
+      # are checked by the same Web::WorkflowQuery the index uses.
+      class WorkflowsTool < BaseTool
+        tool_name "pgbus_workflows"
+        title "Pgbus Workflows"
+        description <<~DESC
+          List Pgbus::Workflow runs, newest first: class, subject, status, current step and attempt, what a waiting step waits for (signal name, fan-out batch progress), when a scheduled step runs, and the error class of a paused one. status is "ongoing" (default: ready, performing, waiting or paused), one state, or "all"; the other filters combine with AND. created_from/created_to and ended_from/ended_to (when a run finished or was cancelled) take an ISO 8601 date or time. Paginated (default 25, max 100); total is capped at 10000. The error message is redacted unless the server allows payloads and include_payloads is set.
+        DESC
+
+        MAX_PER_PAGE = 100
+        MAX_PAGE = 1_000
+        TEXT = %w[workflow_class step error_class subject_type subject_id workflow_id].freeze
+
+        input_schema(
+          properties: {
+            status: { type: "string", enum: Web::DataSource::WorkflowList::STATUSES,
+                      description: "ongoing (default), ready, performing, waiting, paused, finished, cancelled or all." },
+            **TEXT.to_h { |name| [name.to_sym, { type: "string", description: "Exact #{name.tr("_", " ")}." }] },
+            created_from: { type: "string", description: "Created at or after this ISO 8601 date or time." },
+            created_to: { type: "string", description: "Created at or before this ISO 8601 date (the whole day) or time." },
+            ended_from: { type: "string", description: "Finished or cancelled at or after this ISO 8601 date or time." },
+            ended_to: {
+              type: "string", description: "Finished or cancelled at or before this ISO 8601 date (the whole day) or time."
+            },
+            page: { type: "integer", description: "1-based page number (default 1, max 1000).", minimum: 1 },
+            per_page: { type: "integer", description: "Rows per page (default 25, max 100).", minimum: 1 },
+            include_payloads: {
+              type: "boolean", description: "Include error messages. Only honored when the server allows payloads."
+            }
+          },
+          required: []
+        )
+
+        def self.call(page: 1, per_page: 25, include_payloads: false, server_context: nil, **filters)
+          query = Web::WorkflowQuery.new(filters)
+          data_source = data_source_from(server_context)
+          per_page = per_page.to_i.clamp(1, MAX_PER_PAGE)
+          page = page.to_i.clamp(1, MAX_PAGE)
+          rows = data_source.workflows(status: query.status, page: page, per_page: per_page, **query.filters)
+          count = data_source.workflows_count(status: query.status, **query.filters)
+          allowed = payloads_allowed?(server_context, include_payloads)
+
+          json_response(
+            { workflows: rows.map { |row| WorkflowPayloads.row(row, allowed: allowed) }, page: page, per_page: per_page,
+              total: count.total, has_more: more_pages?(count, page: page, per_page: per_page, shown: rows.size) },
+            server_context: server_context, include_payloads: include_payloads
+          )
+        rescue Web::WorkflowQuery::Invalid => e
+          error_response(e.message)
+        end
+      end
+    end
+  end
+end

data/lib/pgbus/mcp/workflow_insights_payload.rb

@@ -0,0 +1,15 @@
+# frozen_string_literal: true
+
+module Pgbus
+  module MCP
+    # The workflow insights' hashes as the MCP tools send them (issue #549).
+    # removed_in_flight is keyed by step name, and a step may be named like a
+    # payload key (removed_step :payload), which the Redactor would blank:
+    # the tools send it as [{ step:, runs: }] rows instead.
+    module WorkflowInsightsPayload
+      module_function
+
+      def row(row) = row.merge(removed_in_flight: row.fetch(:removed_in_flight, {}).map { |step, runs| { step: step, runs: runs } })
+    end
+  end
+end

data/lib/pgbus/mcp/workflow_payloads.rb

@@ -0,0 +1,53 @@
+# frozen_string_literal: true
+
+module Pgbus
+  module MCP
+    # What the workflow tools (issue #542) send back. A run's arguments, its
+    # steps' outputs, its signals' payloads and its error text (message,
+    # backtrace, cause messages, an event's error_message) can carry
+    # application data, and the Redactor only blanks known payload keys
+    # holding a leaf value, so these tools gate them explicitly: replaced by
+    # Redactor::REDACTED unless BaseTool.payloads_allowed? says otherwise.
+    # Written out through MCP::Serialization.
+    module WorkflowPayloads
+      REDACTED = Redactor::REDACTED
+      STEP_SECRETS = %i[output error_message error_backtrace].freeze
+
+      module_function
+
+      def row(row, allowed:)
+        serialize(allowed ? row : row.merge(redact(row, :error_message)))
+      end
+
+      def detail(detail, allowed:)
+        return serialize(detail.except(:timeline)) if allowed
+
+        gated = detail.except(:timeline).merge(arguments: REDACTED, **redact(detail, :error_message))
+        gated[:steps] = Array(detail[:steps]).map { |step| gate_step(step) }
+        gated[:signals] = Array(detail[:signals]).map { |signal| signal.merge(payload: REDACTED) }
+        gated[:events] = Array(detail[:events]).map { |event| gate_event(event) }
+        serialize(gated)
+      end
+
+      def group(group, allowed:)
+        serialize(allowed ? group : group.merge(redact(group, :error_message)))
+      end
+
+      def gate_step(step)
+        gated = step.merge(STEP_SECRETS.to_h { |key| [key, step[key].nil? ? nil : REDACTED] })
+        gated[:error_causes] = Array(step[:error_causes]).map { |cause| cause.slice("class", :class) }
+        gated
+      end
+
+      def gate_event(event)
+        details = event[:details] || {}
+        event.merge(details: details.reject { |key, _| key.to_s == "error_message" })
+      end
+
+      # { key => REDACTED } when the value is there, so a nil stays nil.
+      def redact(hash, key) = hash[key].nil? ? {} : { key => REDACTED }
+
+      def serialize(value) = Serialization.serialize(value)
+    end
+  end
+end