pgbus 0.19.4 → 0.20.0

data/lib/pgbus/integrations/appsignal/dashboard.json

@@ -4,7 +4,7 @@
   ],
   "dashboard": {
     "title": "Pgbus",
-    "description": "PostgreSQL-native job processing and event bus built on PGMQ.\nMonitor job throughput, queue depth, latency, dead letter queues,\nworker processes, event handlers, and stream broadcasts.\n",
+    "description": "PostgreSQL-native job processing and event bus built on PGMQ.\nMonitor job throughput, queue depth, latency, dead letter queues,\nworker processes, event handlers, and stream broadcasts.\nWorkflow step outcomes and run times, and stuck workflows.\n",
     "visuals": [
       {
         "type": "timeseries",
@@ -393,6 +393,133 @@
             "tags": []
           }
         ]
+      },
+      {
+        "type": "timeseries",
+        "display": "LINE",
+        "title": "Workflow steps per outcome",
+        "description": "Workflow step attempts by class, step and outcome (completed, reattempted, skipped, paused, cancelled, finished_early).",
+        "line_label": "%workflow_class% - %step% - %outcome%",
+        "format": "number",
+        "draw_null_as_zero": true,
+        "metrics": [
+          {
+            "name": "pgbus_workflow_steps_total",
+            "fields": [
+              {
+                "field": "COUNTER"
+              }
+            ],
+            "tags": [
+              {
+                "key": "workflow_class",
+                "value": "*"
+              },
+              {
+                "key": "step",
+                "value": "*"
+              },
+              {
+                "key": "outcome",
+                "value": "*"
+              }
+            ]
+          }
+        ]
+      },
+      {
+        "type": "timeseries",
+        "display": "LINE",
+        "title": "Workflow step run time (seconds)",
+        "description": "Mean and p95 run time of each workflow step's body, in seconds.",
+        "line_label": "%workflow_class% - %step% - %outcome%",
+        "format": "number",
+        "draw_null_as_zero": true,
+        "metrics": [
+          {
+            "name": "pgbus_workflow_step_duration_seconds",
+            "fields": [
+              {
+                "field": "MEAN"
+              },
+              {
+                "field": "P95"
+              }
+            ],
+            "tags": [
+              {
+                "key": "workflow_class",
+                "value": "*"
+              },
+              {
+                "key": "step",
+                "value": "*"
+              },
+              {
+                "key": "outcome",
+                "value": "*"
+              }
+            ]
+          }
+        ]
+      },
+      {
+        "type": "timeseries",
+        "display": "LINE",
+        "title": "Workflows by status",
+        "description": "Workflow runs per class and status, from each dispatcher sweep.",
+        "line_label": "%workflow_class% - %status%",
+        "format": "number",
+        "draw_null_as_zero": true,
+        "metrics": [
+          {
+            "name": "pgbus_workflows",
+            "fields": [
+              {
+                "field": "GAUGE"
+              }
+            ],
+            "tags": [
+              {
+                "key": "workflow_class",
+                "value": "*"
+              },
+              {
+                "key": "status",
+                "value": "*"
+              }
+            ]
+          }
+        ]
+      },
+      {
+        "type": "timeseries",
+        "display": "LINE",
+        "title": "Stuck workflows",
+        "description": "Ongoing workflow runs that need a person, by class and reason (paused_error, stalled, paused_manual, overdue).",
+        "line_label": "%workflow_class% - %reason%",
+        "format": "number",
+        "draw_null_as_zero": true,
+        "metrics": [
+          {
+            "name": "pgbus_workflows_stuck",
+            "fields": [
+              {
+                "field": "GAUGE"
+              }
+            ],
+            "tags": [
+              {
+                "key": "workflow_class",
+                "value": "*"
+              },
+              {
+                "key": "reason",
+                "value": "*"
+              }
+            ]
+          }
+        ]
       }
     ]
   }

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

@@ -76,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).
@@ -273,6 +274,20 @@ module Pgbus
               { reason: payload[:reason], kind: "consumer" }
             )
           end
+
+          # ── Workflows (issue #540) ──────────────────────────────────────
+
+          # 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
     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

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