pgbus 0.19.3 → 0.20.0

data/lib/pgbus/integrations/appsignal/subscriber.rb

@@ -1,6 +1,7 @@
 # frozen_string_literal: true
 
-require "time"
+require "pgbus/integrations/appsignal/job_span"
+require "pgbus/integrations/appsignal/event_span"
 
 module Pgbus
   module Integrations
@@ -10,16 +11,23 @@ module Pgbus
       #
       # Job and event-handler events open a BACKGROUND_JOB transaction so they
       # appear under AppSignal's "Performance > Background jobs" view, with
-      # action `<JobClass>#perform` or `<HandlerClass>#handle`. All other
-      # events are reported as counters or distributions only.
+      # action `<JobClass>#perform` or `<HandlerClass>#handle`. The transaction
+      # is opened when pgbus.executor.execute / pgbus.event_processed starts and
+      # completed when it finishes (JobSpan, EventSpan), so it is current while the
+      # job or handler runs and carries the error the execution raised. All
+      # other events are reported as counters or distributions only.
       #
       # All metric names are prefixed `pgbus_`. Tag keys avoid high-cardinality
       # values (no msg_id, no event_id) so AppSignal's metric storage stays
       # efficient.
       module Subscriber
-        BACKGROUND_JOB = "background_job"
         METRIC_PREFIX = "pgbus_"
-        private_constant :BACKGROUND_JOB, :METRIC_PREFIX
+
+        # Built once, at load: a span keeps its state in a fiber-local frame,
+        # never in itself.
+        JOB_SPAN = JobSpan.new.freeze
+        EVENT_SPAN = EventSpan.new.freeze
+        private_constant :METRIC_PREFIX, :JOB_SPAN, :EVENT_SPAN
 
         # Tracked so we can detach in reset! (used by specs). Installed once
         # at boot (the engine's after_initialize); @install_lock makes the
@@ -54,11 +62,11 @@ module Pgbus
 
           def subscribe_all
             [
-              subscribe("pgbus.executor.execute") { |event| on_executor_execute(event) },
+              ActiveSupport::Notifications.subscribe("pgbus.executor.execute", JOB_SPAN),
               subscribe("pgbus.job_completed") { |event| on_job_completed(event) },
               subscribe("pgbus.job_failed") { |event| on_job_failed(event) },
               subscribe("pgbus.job_dead_lettered") { |event| on_job_dead_lettered(event) },
-              subscribe("pgbus.event_processed") { |event| on_event_processed(event) },
+              ActiveSupport::Notifications.subscribe("pgbus.event_processed", EVENT_SPAN),
               subscribe("pgbus.event_failed") { |event| on_event_failed(event) },
               subscribe("pgbus.event_dead_lettered") { |event| on_event_dead_lettered(event) },
               subscribe("pgbus.client.send_message") { |event| on_send_message(event) },
@@ -68,7 +76,8 @@ module Pgbus
               subscribe("pgbus.outbox.publish") { |event| on_outbox_publish(event) },
               subscribe("pgbus.recurring.enqueue") { |event| on_recurring_enqueue(event) },
               subscribe("pgbus.worker.recycle") { |event| on_worker_recycle(event) },
-              subscribe("pgbus.consumer.recycle") { |event| on_consumer_recycle(event) }
+              subscribe("pgbus.consumer.recycle") { |event| on_consumer_recycle(event) },
+              *Pgbus::Metrics::WorkflowMetrics::EVENTS.map { |name| subscribe(name) { |event| on_workflow(event) } }
               # pgbus.client.pool is deliberately NOT subscribed here — the
               # minutely Probe#track_pool already reports pgbus_pool_size /
               # pgbus_pool_available gauges for AppSignal (see probe.rb).
@@ -98,22 +107,6 @@ module Pgbus
 
           # ── Job execution ───────────────────────────────────────────────
 
-          def on_executor_execute(event)
-            payload = event.payload
-            transaction = ::Appsignal::Transaction.create(BACKGROUND_JOB)
-            transaction.set_action_if_nil("#{payload[:job_class] || "UnknownJob"}#perform")
-            apply_queue_start(transaction, payload[:enqueued_at])
-            transaction.add_tags(job_tags(payload))
-            transaction.add_params_if_nil { { arguments: payload[:arguments] } }
-            ::Appsignal.add_distribution_value(
-              "#{METRIC_PREFIX}job_duration_ms",
-              event.duration,
-              { queue: payload[:queue], job_class: payload[:job_class] }
-            )
-          ensure
-            ::Appsignal::Transaction.complete_current!
-          end
-
           def on_job_completed(event)
             payload = event.payload
             ::Appsignal.increment_counter(
@@ -123,15 +116,18 @@ module Pgbus
             )
           end
 
+          # The counter has its own guard so a raise there cannot keep the
+          # error from being reported.
           def on_job_failed(event)
             payload = event.payload
-            ::Appsignal.increment_counter(
-              "#{METRIC_PREFIX}queue_job_count",
-              1,
-              { queue: payload[:queue], job_class: payload[:job_class], status: "failed" }
-            )
-            err = payload[:exception_object]
-            ::Appsignal.set_error(err) if err && ::Appsignal.respond_to?(:set_error)
+            safely do
+              ::Appsignal.increment_counter(
+                "#{METRIC_PREFIX}queue_job_count",
+                1,
+                { queue: payload[:queue], job_class: payload[:job_class], status: "failed" }
+              )
+            end
+            JOB_SPAN.report_unattached(payload[:exception_object], payload)
           end
 
           def on_job_dead_lettered(event)
@@ -145,40 +141,23 @@ module Pgbus
 
           # ── Event handler ───────────────────────────────────────────────
 
-          def on_event_processed(event)
-            payload = event.payload
-            transaction = ::Appsignal::Transaction.create(BACKGROUND_JOB)
-            transaction.set_action_if_nil("#{payload[:handler] || "UnknownHandler"}#handle")
-            apply_queue_start(transaction, payload[:published_at])
-            transaction.add_tags(handler_tags(payload))
-            ::Appsignal.add_distribution_value(
-              "#{METRIC_PREFIX}event_duration_ms",
-              event.duration,
-              { handler: payload[:handler], routing_key: payload[:routing_key] }
-            )
-            ::Appsignal.increment_counter(
-              "#{METRIC_PREFIX}event_count",
-              1,
-              { handler: payload[:handler], routing_key: payload[:routing_key], status: "processed" }
-            )
-          ensure
-            ::Appsignal::Transaction.complete_current!
-          end
-
+          # The counter has its own guard so a raise there cannot keep the
+          # error from being reported.
           def on_event_failed(event)
             payload = event.payload
-            ::Appsignal.increment_counter(
-              "#{METRIC_PREFIX}event_count",
-              1,
-              { handler: payload[:handler], routing_key: payload[:routing_key], status: "failed" }
-            )
-            err = payload[:exception_object]
-            ::Appsignal.set_error(err) if err && ::Appsignal.respond_to?(:set_error)
+            safely do
+              ::Appsignal.increment_counter(
+                "#{METRIC_PREFIX}event_count",
+                1,
+                { handler: payload[:handler], routing_key: payload[:routing_key], status: "failed" }
+              )
+            end
+            EVENT_SPAN.report_unattached(payload[:exception_object], payload)
           end
 
           # A counter only, like on_job_dead_lettered: nothing is raised at
-          # move time, and the handler's error already went out through
-          # pgbus.event_failed on the attempt that raised (issue #543). A body
+          # move time, and the handler's error already went out on the
+          # attempt that raised (issues #543, #552). A body
           # that is not JSON leaves handler and routing_key nil; compact drops
           # those tags, as Metrics::Subscriber does.
           def on_event_dead_lettered(event)
@@ -296,47 +275,18 @@ module Pgbus
             )
           end
 
-          # ── Helpers ─────────────────────────────────────────────────────
-
-          # AppSignal expects queue-start as Unix epoch milliseconds. Pgbus
-          # carries it as either an ISO-8601 String or a Time — both happen
-          # in practice (executor passes the JSON string, handler passes a
-          # parsed Time).
-          def apply_queue_start(transaction, value)
-            return unless value
-
-            millis =
-              case value
-              when Time
-                (value.to_f * 1_000).to_i
-              when String
-                (Time.parse(value).to_f * 1_000).to_i
-              when Numeric
-                value.to_i
-              end
-            transaction.set_queue_start(millis) if millis
-          rescue ArgumentError
-            # Unparseable timestamp — skip rather than blow up.
-          end
-
-          def job_tags(payload)
-            tags = {
-              "queue" => payload[:queue],
-              "job_class" => payload[:job_class],
-              "attempts" => payload[:read_ct]
-            }
-            tags["active_job_id"] = payload[:job_id] if payload[:job_id]
-            tags["provider_job_id"] = payload[:provider_job_id] if payload[:provider_job_id]
-            tags["request_id"] = payload[:provider_job_id] || payload[:job_id]
-            tags.compact
-          end
+          # ── Workflows (issue #540) ──────────────────────────────────────
 
-          def handler_tags(payload)
-            {
-              "handler" => payload[:handler],
-              "routing_key" => payload[:routing_key],
-              "attempts" => payload[:read_ct]
-            }.compact
+          # The same names and labels as Metrics::Subscriber
+          # (Pgbus::Metrics::WorkflowMetrics), as AppSignal custom metrics.
+          def on_workflow(event)
+            Pgbus::Metrics::WorkflowMetrics.samples(event.name, event.payload).each do |kind, name, value, tags|
+              case kind
+              when :histogram then ::Appsignal.add_distribution_value(name, value, tags)
+              when :counter then ::Appsignal.increment_counter(name, value, tags)
+              when :gauge then ::Appsignal.set_gauge(name, value, tags)
+              end
+            end
           end
         end
       end

data/lib/pgbus/mcp/rack_app.rb

@@ -19,7 +19,8 @@ module Pgbus
     #
     # Security: requests are rejected with 401 unless they carry the configured
     # token (or pass the supplied auth callable). Run it on an internal network
-    # / behind your VPN, never internet-exposed.
+    # / behind your VPN, never internet-exposed. With config.mcp_write_tools on
+    # it also serves the workflow write tools (issue #550): gate it.
     #
     # DNS-rebinding protection: since mcp 0.23 the transport validates the Host
     # header (loopback only, by default) and the Origin header (same-origin
@@ -123,9 +124,13 @@ module Pgbus
         @token.nil? && @auth.nil?
       end
 
+      # With config.mcp_write_tools on, an unauthenticated mount can change
+      # workflow runs. Warned, not refused: a mount inside the app's own
+      # authenticated routes is gated where this class cannot see it.
       def warn_unauthenticated!
         Pgbus.logger.warn do
-          "[Pgbus::MCP] HTTP diagnostic server mounted without authentication. " \
+          writes = Server.write_tools? ? " config.mcp_write_tools is on: anyone who reaches it can change workflow runs." : ""
+          "[Pgbus::MCP] HTTP diagnostic server mounted without authentication.#{writes} " \
             "Pass token: or auth: to Pgbus::MCP.rack_app, and keep it on an internal network."
         end
       end

data/lib/pgbus/mcp/runner.rb

@@ -66,7 +66,8 @@ module Pgbus
 
       def log_start(allow_payloads)
         mode = allow_payloads ? "payloads ALLOWED" : "payloads redacted"
-        Pgbus.logger.info { "[Pgbus::MCP] starting read-only diagnostic server over stdio (#{mode})" }
+        kind = Server.write_tools? ? "diagnostic server with the workflow write tools ON (mcp_write_tools)" : "read-only diagnostic server"
+        Pgbus.logger.info { "[Pgbus::MCP] starting #{kind} over stdio (#{mode})" }
       end
     end
   end

data/lib/pgbus/mcp/serialization.rb

@@ -0,0 +1,25 @@
+# frozen_string_literal: true
+
+require "date"
+require "time"
+require "active_support/core_ext/time"
+
+module Pgbus
+  module MCP
+    # How MCP tools write a data-source row as JSON: times as ISO 8601 UTC,
+    # symbols as strings, keys as strings, recursively.
+    module Serialization
+      module_function
+
+      def serialize(value)
+        case value
+        when Hash then value.to_h { |key, nested| [key.to_s, serialize(nested)] }
+        when Array then value.map { |nested| serialize(nested) }
+        when Symbol then value.to_s
+        when Time, DateTime, ActiveSupport::TimeWithZone then value.utc.iso8601
+        else value
+        end
+      end
+    end
+  end
+end

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