belay 0.1.0 → 0.2.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 628271c83f016c169bdd9050abf23bbb6932fb27dcf15a74bbfbaae63e1814e4
-  data.tar.gz: 154ee22a4b15d42c20ae9879bad70b2f55597fd89b8f7a26bd4e96472d9f386e
+  metadata.gz: 52f50e4537c30e2b3eb43793cc383813ca063aa24f158c8fb094e4aa79e5a932
+  data.tar.gz: 1b058a13b621cbc6eee5b44b478a3416aea6c7d2e27dd967031ca9657887bd2b
 SHA512:
-  metadata.gz: f75b75dd4980103b44896aac3b8c2b20adbf643975c198cd5127efadc353a86b70c7cd12ad825153ef816696af4066cb58e8c1d8972abbc9a79508ba94837e8b
-  data.tar.gz: 34595eaa201103123588bb2f08a0111c305ab0579c12b119b15508f55ab0c410ae2bd094feb326f16dc2f4f7063408f6d60823b42d00822613f8d06436d766f6
+  metadata.gz: 2954f88a1817e5a6e5b57f556157279b74bd30b8bd0769b451f5b662b72ff10127731d9bf3121823137a69fda172dff4b79acf46d78079378a251e2048dac078
+  data.tar.gz: 99b29ce7dd493c0218a1e8e94600108370ec74fc7b1e0fba9307eb7ce9f4793af11ee67eb4b9c644da0f2f4bb78cd9157c5af9fc286250399bab90cbdb96cfaa

data/README.md

@@ -132,7 +132,7 @@ ctx.llm(model:, prompt:, schema: nil, cacheable: false)
 
 Calls `Belay.config.provider`, validates the response against `schema:` provider-agnostically, and returns `response.content` directly as the step's own output.
 
-**→ [docs/providers.md](docs/providers.md)** - Belay isn't Anthropic-only; bring your own provider.
+**→ [docs/providers.md](docs/providers.md)** - ships `AnthropicProvider`, `OpenAIProvider`, and `GeminiProvider`; bring your own for anything else.
 **→ [docs/caching.md](docs/caching.md)** - `cacheable: true` and when it's actually safe to use.
 
 ## Dashboard
@@ -146,6 +146,12 @@ A runs index, a run detail page with the full step timeline, a replay diff view,
 
 **→ [docs/dashboard.md](docs/dashboard.md)** for mounting, wiring in your own auth (Devise/Pundit/CanCanCan/anything), and what each page shows.
 
+## Instrumentation
+
+Belay publishes `ActiveSupport::Notifications` events for the run/step/gate lifecycle (`belay.run.started`, `belay.step.completed`, `belay.gate.paused`, and others) - the same mechanism Rails itself uses for `sql.active_record`, so you can pipe what Belay is doing into your own logs/APM without polling the dashboard.
+
+**→ [docs/instrumentation.md](docs/instrumentation.md)** for the full event list and payloads.
+
 ## Roadmap
 
 See [ROADMAP.md](ROADMAP.md).

data/lib/belay/executor.rb

@@ -186,6 +186,8 @@ module Belay
         # human. Run#pause! already exists (running -> paused) for exactly this shape
         # of "stopped, not failed, waiting on something external."
         @run.pause!
+        ActiveSupport::Notifications.instrument("belay.step.needs_review", run_id: @run.id, step_id: existing.id,
+                                                                           name: existing.name, reason: reason)
         raise Error, "#{reason} - flagged needs_review; the run is paused until a human resolves it"
       end
 
@@ -240,12 +242,37 @@ module Belay
         output = run_block(step_run, context, step)
         return [nil, nil] if output.equal?(AUTO_SETTLED) # auto_settle_gate! already wrote this row itself
 
-        step.update!(status: settled_status(step_run), output: output, **extra_step_attrs(step_run, context))
-        [output, nil]
+        settle_succeeded!(step_run, step, context, output)
       rescue StandardError => e
-        step.update!(status: "failed", error: { "class" => e.class.name, "message" => e.message },
+        settle_failed!(step_run, step, context, e)
+      end
+
+      def settle_succeeded!(step_run, step, context, output)
+        status = settled_status(step_run)
+        step.update!(status: status, output: output, **extra_step_attrs(step_run, context))
+        instrument_step_completed(step, status: status)
+        [output, nil]
+      end
+
+      def settle_failed!(step_run, step, context, error)
+        step.update!(status: "failed", error: { "class" => error.class.name, "message" => error.message },
                      **extra_step_attrs(step_run, context))
-        [nil, e]
+        instrument_step_completed(step, status: "failed")
+        [nil, error]
+      end
+
+      # One event per settled attempt (success or failure alike), not separate
+      # started/completed events - the same consolidation ActionController's own
+      # process_action.action_controller notification makes (one event, status: in
+      # the payload), rather than one event per outcome. A step's own row already
+      # records attempt: - a retried step fires this once per attempt, same as it
+      # gets its own Step row per attempt.
+      def instrument_step_completed(step, status:)
+        ActiveSupport::Notifications.instrument(
+          "belay.step.completed",
+          run_id: @run.id, step_id: step.id, position: step.position, name: step.name,
+          kind: step.kind, status: status, attempt: step.attempt
+        )
       end
 
       # Wrapped in @run.heartbeat_while, not called bare - this is the one call in
@@ -311,6 +338,8 @@ module Belay
       def auto_settle_gate!(step, context_key, rule)
         step.update!(status: "succeeded", output: nil, input: { "context_key" => context_key },
                      rule_applied_id: rule.id)
+        ActiveSupport::Notifications.instrument("belay.gate.auto_approved", run_id: @run.id, step_id: step.id,
+                                                                            name: step.name, rule_id: rule.id)
         AUTO_SETTLED
       end
 
@@ -347,6 +376,8 @@ module Belay
           @run.pause!
           @run.release_lease!
         end
+        ActiveSupport::Notifications.instrument("belay.gate.paused", run_id: @run.id, step_id: step.id,
+                                                                     name: step.name)
         throw :gate_paused
       end
 

data/lib/belay/gemini_provider.rb

@@ -0,0 +1,158 @@
+# frozen_string_literal: true
+
+require "net/http"
+require "json"
+require "uri"
+
+module Belay
+  # Calls Google's Gemini API directly over Net::HTTP (stdlib) - same
+  # reasoning as AnthropicProvider/OpenAIProvider: no SDK gem, so no second
+  # gem's own version matrix for this gem to track for a provider this
+  # central.
+  #
+  # Endpoint and field names verified against Google's own REST reference
+  # (ai.google.dev/api/generate-content) as of 2026-10-28.
+  #
+  # The API key goes in the request URL's own ?key= query param, not a
+  # header - that's Gemini's own convention, unlike Anthropic's x-api-key or
+  # OpenAI's Authorization: Bearer. URI.encode_www_form escapes it rather
+  # than interpolating it directly into the URL string, purely so a key
+  # containing a URL-meaningful character (unlikely, but API keys are
+  # opaque strings this gem didn't generate) can't corrupt the request line.
+  #
+  # schema: is passed through to generationConfig.responseSchema completely
+  # unvalidated and untranslated - Gemini's schema dialect uses its own,
+  # UPPERCASE type names ("OBJECT", "STRING", "INTEGER", ...), not standard
+  # JSON Schema's lowercase ones ("object", "string"), and doesn't support
+  # every JSON Schema keyword. A schema written for AnthropicProvider or
+  # OpenAIProvider will not work here unchanged - same spirit as
+  # AnthropicProvider's additionalProperties: false requirement, just a
+  # different provider-specific dialect. See docs/providers.md.
+  #
+  # finishReason is mapped to the same StructuredOutputError reason: values
+  # the other two providers use, so a caller can branch on reason: the same
+  # way regardless of which provider is configured: "SAFETY"/"RECITATION"
+  # (the model declined to produce matching content) -> "refusal";
+  # "MAX_TOKENS" -> "max_tokens". Like AnthropicProvider/OpenAIProvider, this
+  # check only runs when schema: was given - see OpenAIProvider's own comment
+  # for why a refusal/truncation on a plain-text call isn't this gem's call
+  # to second-guess.
+  class GeminiProvider < Provider
+    API_BASE = "https://generativelanguage.googleapis.com/v1beta/models"
+
+    # Raised on any non-2xx response. Gemini's own error body (JSON, usually
+    # {"error": {"code":, "message":, "status":}}) is preserved verbatim in
+    # the message, same reasoning as AnthropicProvider::RequestError.
+    class RequestError < Error
+      attr_reader :status
+
+      def initialize(status:, body:)
+        @status = status
+        super("Gemini API request failed with status #{status}: #{body}")
+      end
+    end
+
+    # Raised when schema: was given but the response can't be trusted to
+    # contain valid, complete schema-matching JSON. reason: is "refusal" or
+    # "max_tokens" - see the class comment above for which finishReason maps
+    # to each.
+    class StructuredOutputError < Error
+      attr_reader :reason, :response
+
+      def initialize(reason:, response:)
+        @reason = reason
+        @response = response
+        super("Gemini did not return schema-matching output (reason: #{reason.inspect}): #{response.inspect}")
+      end
+    end
+
+    # pricing: {"gemini-..." => { input_per_million: <USD Float>, output_per_million: <USD Float> }, ...}
+    # Deliberately not pre-filled with Google's current rates - same
+    # reasoning as AnthropicProvider's own pricing: comment.
+    def initialize(api_key: ENV.fetch("GEMINI_API_KEY", nil), max_output_tokens: 4096, pricing: {})
+      super()
+      raise ArgumentError, "#{self.class} requires api_key: (or GEMINI_API_KEY)" if api_key.nil?
+
+      @api_key = api_key
+      @max_output_tokens = max_output_tokens
+      @pricing = pricing
+    end
+
+    def call(model:, prompt:, schema: nil)
+      started_at = Process.clock_gettime(Process::CLOCK_MONOTONIC)
+      status, body = perform_request(model, request_body(prompt: prompt, schema: schema))
+      latency_ms = ((Process.clock_gettime(Process::CLOCK_MONOTONIC) - started_at) * 1000).round
+
+      raise RequestError.new(status: status, body: body) unless status.between?(200, 299)
+
+      build_response(JSON.parse(body), model: model, schema: schema, latency_ms: latency_ms)
+    end
+
+    private
+
+    def request_body(prompt:, schema:)
+      body = {
+        contents: [{ parts: [{ text: prompt }] }],
+        generationConfig: { maxOutputTokens: @max_output_tokens }
+      }
+      return body if schema.nil?
+
+      body[:generationConfig] = body[:generationConfig].merge(responseMimeType: "application/json",
+                                                              responseSchema: schema)
+      body
+    end
+
+    def perform_request(model, body)
+      uri = URI("#{API_BASE}/#{model}:generateContent")
+      uri.query = URI.encode_www_form(key: @api_key)
+      response = Net::HTTP.post(uri, JSON.generate(body), { "content-type" => "application/json" })
+      [response.code.to_i, response.body]
+    end
+
+    def build_response(response, model:, schema:, latency_ms:)
+      usage = response["usageMetadata"] || {}
+      input_tokens, output_tokens = usage.values_at("promptTokenCount", "candidatesTokenCount")
+
+      ProviderResponse.new(
+        content: extract_content(response, schema: schema),
+        model: response["modelVersion"] || model,
+        input_tokens: input_tokens,
+        output_tokens: output_tokens,
+        cost_cents: cost_cents(model: model, input_tokens: input_tokens, output_tokens: output_tokens),
+        latency_ms: latency_ms
+      )
+    end
+
+    def extract_content(response, schema:)
+      schema ? extract_structured_output(response) : extract_text(response)
+    end
+
+    def extract_structured_output(response)
+      finish_reason = response.dig("candidates", 0, "finishReason")
+      if %w[SAFETY RECITATION].include?(finish_reason)
+        raise StructuredOutputError.new(reason: "refusal", response: response)
+      end
+      raise StructuredOutputError.new(reason: "max_tokens", response: response) if finish_reason == "MAX_TOKENS"
+
+      JSON.parse(extract_text(response))
+    end
+
+    def extract_text(response)
+      part = response.dig("candidates", 0, "content", "parts", 0)
+      raise Error, "Gemini response had no text content part" if part.nil? || part["text"].nil?
+
+      part["text"]
+    end
+
+    def cost_cents(model:, input_tokens:, output_tokens:)
+      return nil if input_tokens.nil? || output_tokens.nil?
+
+      rates = @pricing[model]
+      return nil if rates.nil?
+
+      input_cost = input_tokens * rates.fetch(:input_per_million)
+      output_cost = output_tokens * rates.fetch(:output_per_million)
+      ((input_cost + output_cost) / 1_000_000.0 * 100).round
+    end
+  end
+end

data/lib/belay/openai_provider.rb

@@ -0,0 +1,246 @@
+# frozen_string_literal: true
+
+require "net/http"
+require "json"
+require "uri"
+
+module Belay
+  # Calls OpenAI's API directly over Net::HTTP (stdlib) - same reasoning as
+  # AnthropicProvider: no SDK gem, so no second gem's own version matrix for
+  # this gem to track for a provider this central. POST a JSON body, read a
+  # JSON body back is small enough that stdlib Net::HTTP + JSON covers it.
+  #
+  # api: picks which of OpenAI's two current text-generation APIs to call -
+  # :responses (default, OpenAI's own forward-looking API, POST /v1/responses)
+  # or :chat_completions (the older, still fully supported POST
+  # /v1/chat/completions). Both are real, current APIs, not a deprecated/
+  # replacement pair, and their request/response shapes differ enough
+  # (structured-output config lives at text.format vs response_format; usage
+  # keys are input_tokens/output_tokens vs prompt_tokens/completion_tokens;
+  # truncation and refusal surface completely differently - see
+  # extract_responses_content/extract_chat_completions_content below) that
+  # this class branches internally on @api rather than guessing one and
+  # forcing callers who need the other to go write their own provider. The
+  # public interface (#call) and everything around it (errors, cost, latency)
+  # is identical either way.
+  #
+  # Endpoint and field names verified against OpenAI's own public OpenAPI spec
+  # (github.com/openai/openai-openapi) as of 2026-10-28.
+  #
+  # schema: on :responses sets text.format: {type: "json_schema", name:,
+  # schema:, strict: true}; on :chat_completions it's response_format:
+  # {type: "json_schema", json_schema: {name:, schema:, strict: true}}.
+  # Unlike Anthropic, OpenAI requires a name: on the schema either way - a
+  # fixed, gem-chosen value (SCHEMA_NAME) is used throughout, since nothing
+  # about the schema format itself needs that name to be caller-visible.
+  # strict: true is always passed (not left to OpenAI's own default: false) -
+  # a non-strict schema is advisory only, and this gem's own
+  # StructuredOutputError handling below assumes a schema that was actually
+  # enforced.
+  #
+  # refusal/truncation are each mapped to the same StructuredOutputError
+  # reason: values AnthropicProvider uses ("refusal"/"max_tokens"), so a
+  # caller can branch on reason: the same way regardless of which provider is
+  # configured:
+  #   :responses        - a "refusal" content item on the output message ->
+  #                        "refusal"; status: "incomplete" with
+  #                        incomplete_details.reason == "max_output_tokens" ->
+  #                        "max_tokens"
+  #   :chat_completions  - message.refusal present -> "refusal";
+  #                        finish_reason == "length" -> "max_tokens"
+  # Both checks, like AnthropicProvider's own, only run when schema: was
+  # given - a refusal or truncation on a plain-text call isn't this gem's
+  # problem to second-guess; it surfaces as whatever text (or lack of it)
+  # the author's own code then has to deal with, same as any other provider.
+  # Genuinely two providers' worth of request/response handling behind one #call
+  # interface (see api: above), not one class that grew unchecked - same
+  # ClassLength exemption reasoning as Executor::StepRunner (executor.rb).
+  class OpenAIProvider < Provider # rubocop:disable Metrics/ClassLength
+    API_URLS = {
+      responses: URI("https://api.openai.com/v1/responses"),
+      chat_completions: URI("https://api.openai.com/v1/chat/completions")
+    }.freeze
+
+    SCHEMA_NAME = "belay_response"
+
+    # Raised on any non-2xx response. OpenAI's own error body (JSON, usually
+    # {"error": {"type":, "message":}}) is preserved verbatim in the message,
+    # same reasoning as AnthropicProvider::RequestError.
+    class RequestError < Error
+      attr_reader :status
+
+      def initialize(status:, body:)
+        @status = status
+        super("OpenAI API request failed with status #{status}: #{body}")
+      end
+    end
+
+    # Raised when schema: was given but the response can't be trusted to
+    # contain valid, complete schema-matching JSON. reason: is "refusal" or
+    # "max_tokens" - see the class comment above for exactly what maps to
+    # each, per api:.
+    class StructuredOutputError < Error
+      attr_reader :reason, :response
+
+      def initialize(reason:, response:)
+        @reason = reason
+        @response = response
+        super("OpenAI did not return schema-matching output (reason: #{reason.inspect}): #{response.inspect}")
+      end
+    end
+
+    # pricing: {"gpt-..." => { input_per_million: <USD Float>, output_per_million: <USD Float> }, ...}
+    # Deliberately not pre-filled with OpenAI's current rates - same reasoning
+    # as AnthropicProvider's own pricing: comment.
+    def initialize(api_key: ENV.fetch("OPENAI_API_KEY", nil), api: :responses, max_tokens: 4096, pricing: {})
+      super()
+      raise ArgumentError, "#{self.class} requires api_key: (or OPENAI_API_KEY)" if api_key.nil?
+      raise ArgumentError, "api: must be one of #{API_URLS.keys.inspect}, got #{api.inspect}" unless API_URLS.key?(api)
+
+      @api_key = api_key
+      @api = api
+      @max_tokens = max_tokens
+      @pricing = pricing
+    end
+
+    def call(model:, prompt:, schema: nil)
+      started_at = Process.clock_gettime(Process::CLOCK_MONOTONIC)
+      status, body = perform_request(request_body(model: model, prompt: prompt, schema: schema))
+      latency_ms = ((Process.clock_gettime(Process::CLOCK_MONOTONIC) - started_at) * 1000).round
+
+      raise RequestError.new(status: status, body: body) unless status.between?(200, 299)
+
+      build_response(JSON.parse(body), model: model, schema: schema, latency_ms: latency_ms)
+    end
+
+    private
+
+    def request_body(model:, prompt:, schema:)
+      return responses_request_body(model, prompt, schema) if @api == :responses
+
+      chat_completions_request_body(model, prompt, schema)
+    end
+
+    def responses_request_body(model, prompt, schema)
+      body = { model: model, input: prompt, max_output_tokens: @max_tokens }
+      return body if schema.nil?
+
+      body.merge(text: { format: { type: "json_schema", name: SCHEMA_NAME, schema: schema, strict: true } })
+    end
+
+    def chat_completions_request_body(model, prompt, schema)
+      body = { model: model, max_completion_tokens: @max_tokens, messages: [{ role: "user", content: prompt }] }
+      return body if schema.nil?
+
+      body.merge(response_format: { type: "json_schema",
+                                    json_schema: { name: SCHEMA_NAME, schema: schema, strict: true } })
+    end
+
+    def perform_request(body)
+      response = Net::HTTP.post(API_URLS.fetch(@api), JSON.generate(body), request_headers)
+      [response.code.to_i, response.body]
+    end
+
+    def request_headers
+      { "Authorization" => "Bearer #{@api_key}", "content-type" => "application/json" }
+    end
+
+    def build_response(response, model:, schema:, latency_ms:)
+      usage = response["usage"] || {}
+      input_tokens, output_tokens = usage_tokens(usage)
+
+      ProviderResponse.new(
+        content: extract_content(response, schema: schema),
+        model: response["model"] || model,
+        input_tokens: input_tokens,
+        output_tokens: output_tokens,
+        cost_cents: cost_cents(model: model, input_tokens: input_tokens, output_tokens: output_tokens),
+        latency_ms: latency_ms
+      )
+    end
+
+    def usage_tokens(usage)
+      keys = @api == :responses ? %w[input_tokens output_tokens] : %w[prompt_tokens completion_tokens]
+      usage.values_at(*keys)
+    end
+
+    def extract_content(response, schema:)
+      return extract_responses_content(response, schema: schema) if @api == :responses
+
+      extract_chat_completions_content(response, schema: schema)
+    end
+
+    def extract_responses_content(response, schema:)
+      message = find_output_message(response)
+      return extract_responses_structured_output(response, message) if schema
+
+      text = output_text(message)
+      raise Error, "OpenAI response had no output_text content" if text.nil?
+
+      text
+    end
+
+    def extract_responses_structured_output(response, message)
+      raise StructuredOutputError.new(reason: "refusal", response: response) if refusal?(message)
+      raise StructuredOutputError.new(reason: "max_tokens", response: response) if responses_truncated?(response)
+
+      text = output_text(message)
+      raise Error, "OpenAI response had no output_text content" if text.nil?
+
+      JSON.parse(text)
+    end
+
+    def find_output_message(response)
+      message = (response["output"] || []).find { |item| item["type"] == "message" }
+      raise Error, "OpenAI response had no output message" if message.nil?
+
+      message
+    end
+
+    def output_text(message)
+      text_block = (message["content"] || []).find { |c| c["type"] == "output_text" }
+      text_block && text_block["text"]
+    end
+
+    def refusal?(message)
+      (message["content"] || []).any? { |c| c["type"] == "refusal" }
+    end
+
+    def responses_truncated?(response)
+      response["status"] == "incomplete" && response.dig("incomplete_details", "reason") == "max_output_tokens"
+    end
+
+    def extract_chat_completions_content(response, schema:)
+      return extract_chat_completions_structured_output(response) if schema
+
+      content = response.dig("choices", 0, "message", "content")
+      raise Error, "OpenAI response had no message content" if content.nil?
+
+      content
+    end
+
+    def extract_chat_completions_structured_output(response)
+      message = response.dig("choices", 0, "message") || {}
+      raise StructuredOutputError.new(reason: "refusal", response: response) if message["refusal"]
+
+      finish_reason = response.dig("choices", 0, "finish_reason")
+      raise StructuredOutputError.new(reason: "max_tokens", response: response) if finish_reason == "length"
+
+      content = message["content"]
+      raise Error, "OpenAI response had no message content" if content.nil?
+
+      JSON.parse(content)
+    end
+
+    def cost_cents(model:, input_tokens:, output_tokens:)
+      return nil if input_tokens.nil? || output_tokens.nil?
+
+      rates = @pricing[model]
+      return nil if rates.nil?
+
+      input_cost = input_tokens * rates.fetch(:input_per_million)
+      output_cost = output_tokens * rates.fetch(:output_per_million)
+      ((input_cost + output_cost) / 1_000_000.0 * 100).round
+    end
+  end
+end

data/lib/belay/run.rb

@@ -36,15 +36,15 @@ module Belay
     validates :workflow_version, presence: true
 
     def start!
-      transition!(from: "pending", to: "running", started_at: Time.current)
+      transition!(from: "pending", to: "running", event: "started", started_at: Time.current)
     end
 
     def pause!
-      transition!(from: "running", to: "paused")
+      transition!(from: "running", to: "paused", event: "paused")
     end
 
     def resume!
-      transition!(from: "paused", to: "running")
+      transition!(from: "paused", to: "running", event: "resumed")
     end
 
     # None of complete!/fail!/cancel! below clear lease_owner/lease_expires_at - a
@@ -53,15 +53,16 @@ module Belay
     # first, so a stale lease on a terminal run is never actually read. Would need
     # fixing if anything ever queries leases without that status filter.
     def complete!
-      transition!(from: "running", to: "completed", finished_at: Time.current)
+      transition!(from: "running", to: "completed", event: "completed", finished_at: Time.current)
     end
 
     def fail!(error: nil)
-      transition!(from: %w[pending running paused], to: "failed", finished_at: Time.current, error: error)
+      transition!(from: %w[pending running paused], to: "failed", event: "failed",
+                  finished_at: Time.current, error: error)
     end
 
     def cancel!
-      transition!(from: %w[pending running paused], to: "cancelled", finished_at: Time.current)
+      transition!(from: %w[pending running paused], to: "cancelled", event: "cancelled", finished_at: Time.current)
     end
 
     # At most one, by construction: Executor stops at the FIRST gate whose when:
@@ -251,6 +252,13 @@ module Belay
       # answer wasn't quite right, which is the opposite of "safe to auto-settle
       # identically next time."
       record_rule_decision!(gate, approved: true) if edited_payload.nil?
+      # Last, same ordering principle as ResumeRunJob/record_rule_decision! above: a
+      # subscriber that raises (ActiveSupport::Notifications runs subscribers
+      # synchronously, in-process - a slow or broken one is this gem's problem the
+      # moment it's subscribed) must never be able to leave the gate settled with no
+      # job enqueued, which placing this any earlier would risk.
+      ActiveSupport::Notifications.instrument("belay.gate.approved", run_id: id, step_id: gate.id, name: gate.name,
+                                                                     by: by, edited: !edited_payload.nil?)
     end
 
     # Rejects this run's pending gate: records a rejected Belay::Approval, settles
@@ -273,6 +281,8 @@ module Belay
       end
 
       record_rule_decision!(gate, approved: false)
+      ActiveSupport::Notifications.instrument("belay.gate.rejected", run_id: id, step_id: gate.id, name: gate.name,
+                                                                     by: by)
     end
 
     # The two outcomes a human can give a needs_review step (flag_needs_review!,
@@ -615,7 +625,19 @@ module Belay
     # No concurrency guard: this reads status in memory, then does a plain update!. Two
     # processes racing on the same run (stale in-memory copies) can both pass the check.
     # Deferred to the leases work (Phase 1f) rather than solved here.
-    def transition!(from:, to:, **attrs)
+    #
+    # event: is a separate argument from to:, not derived from it (e.g. "belay.run.#{to}") -
+    # to: "running" is reached by both start! and resume!, and those are two meaningfully
+    # different events for anything listening (ActiveSupport::Notifications.instrument
+    # below; see docs/instrumentation.md), the same way the comment above this method
+    # already explains why dispatch can't collapse them into one target-keyed graph either.
+    #
+    # Wrapping update! in .instrument, not instrumenting after the fact, is deliberate: a
+    # subscriber gets the real duration of the UPDATE for free (same convention
+    # ActiveRecord's own sql.active_record notification uses), and a failed update! never
+    # fires the event at all - nothing here is misreported as a transition that didn't
+    # actually happen.
+    def transition!(from:, to:, event:, **attrs)
       allowed_from = Array(from)
       unless allowed_from.include?(status)
         raise InvalidTransitionError,
@@ -623,7 +645,8 @@ module Belay
               "(expected current status to be #{allowed_from.inspect})"
       end
 
-      update!(**attrs, status: to)
+      payload = { run_id: id, workflow: workflow, workflow_version: workflow_version, from: status, to: to }
+      ActiveSupport::Notifications.instrument("belay.run.#{event}", payload) { update!(**attrs, status: to) }
     end
   end
 end

data/lib/belay/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module Belay
-  VERSION = "0.1.0"
+  VERSION = "0.2.0"
 end

data/lib/belay.rb

@@ -20,6 +20,8 @@ module Belay
   require_relative "belay/provider"
   require_relative "belay/fake_provider"
   require_relative "belay/anthropic_provider"
+  require_relative "belay/openai_provider"
+  require_relative "belay/gemini_provider"
   require_relative "belay/executor"
   require_relative "belay/resume_run_job"
   require_relative "belay/janitor_job"

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: belay
 version: !ruby/object:Gem::Version
-  version: 0.1.0
+  version: 0.2.0
 platform: ruby
 authors:
 - Swakhar Dey
 autorequire:
 bindir: bin
 cert_chain: []
-date: 2026-10-27 00:00:00.000000000 Z
+date: 2026-10-28 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: actionpack
@@ -180,7 +180,9 @@ files:
 - lib/belay/engine.rb
 - lib/belay/executor.rb
 - lib/belay/fake_provider.rb
+- lib/belay/gemini_provider.rb
 - lib/belay/janitor_job.rb
+- lib/belay/openai_provider.rb
 - lib/belay/provider.rb
 - lib/belay/provider_response.rb
 - lib/belay/resume_run_job.rb