omnibot-ruby 0.1.0 → 0.2.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 075266e9395d95dedce797206f30b73cdfd972aa59a97813f87e1b6b7f6ce75b
-  data.tar.gz: 4cda42ac155f91a4422000ebc2773c328062694cef3e9867292c47d8d5e7e393
+  metadata.gz: 6a9e962ec1fc30233e103cc753f9db7db243db279f3bb51f6fa8a7bf5abdd940
+  data.tar.gz: 73f4531396f0d8a73a7e6302195a6ff42a9d70ab9b3436a0c9c877a5f234af85
 SHA512:
-  metadata.gz: 2bbf2240ffcae6a4225abf426d0e0799e075cff632b10cb3357bd03383263564af5706f71bc205a7c8d7adb6111bd863c857087a0efadf8008288907c7be5b36
-  data.tar.gz: ff9256f23f891d0664f2e476c797b02462bbd3dd2c2f9ff41c1a70ce4f509c56c1769d8ac171e146fe957b244ace503dfa3dbacf137b57c964d6b40065489b59
+  metadata.gz: d9373a4af7299c9a2ef450b93242c387cefd23ec8efd21b9eeec30dc51e1f7c003848b861e1ae3e52d6698800725e419ad1b09db0256f7bb57a5445ee7e25bdf
+  data.tar.gz: 9b24f2b865bee9764f474e7613e91d14d09c9afc9144175caf48d2a996294588ca501c47bfb5e48ed554a42189f5cfff7fcba76497e963c6b8fd6f6dde69c776

data/README.md

@@ -4,7 +4,7 @@ Rails-first LLM agents for Ruby.
 
 ## Why
 
-`omnibot-ruby` is a Rails-idiomatic agent framework built on [`ruby_llm`](https://github.com/crmne/ruby_llm) — a class DSL for bounded tool-calling agents that lives in your Rails app, not a Python sidecar you have to deploy, proxy, and keep in sync. It ships two primitives: **Agent** (v0.1, available now — a bounded tool-calling loop with fast paths, structured extraction, and streaming) and **Workflow** (coming in v0.2 — a durable, ActiveRecord-checkpointed graph engine for multi-step conversations with human handover, so long-running flows survive restarts without a Redis checkpointer). Everything runs in-process, which means token streaming to ActionCable/Turbo is a callback away instead of blocked behind an HTTP hop.
+`omnibot-ruby` is a Rails-idiomatic agent framework built on [`ruby_llm`](https://github.com/crmne/ruby_llm) — a class DSL for bounded tool-calling agents that lives in your Rails app, not a Python sidecar you have to deploy, proxy, and keep in sync. It ships two primitives: **Agent** (a bounded tool-calling loop with fast paths, structured extraction, and streaming) and **Workflow** (v0.2 — a durable, ActiveRecord-checkpointed graph engine for multi-step conversations with human handover, so long-running flows survive restarts without a Redis checkpointer). Everything runs in-process, which means token streaming to ActionCable/Turbo is a callback away instead of blocked behind an HTTP hop.
 
 ## Install
 
@@ -174,6 +174,83 @@ end
 
 The fake replays your script in order: `to_call_tool` asserts a tool is called and actually executes it (so bugs in your tool body still surface), `then_reply` ends the turn with a text reply, and `then_extract` ends it with a Hash for `Agent.extract` specs. If the script runs out, unscripted calls get a default `"(fake) <message>"` reply so runaway loops fail loudly instead of hanging. Class-form tools are plain Ruby objects — unit-test them directly, no fake required.
 
+## Durable workflows
+
+`Omnibot::Workflow` is a checkpoint-per-step graph engine for multi-step conversations that must survive a restart between messages: steps are nodes, transitions are edges, state persists as jsonb on a gem-owned `omnibot_workflow_runs` table. No Redis checkpointer, no graph compilation, no sidecar — it's ActiveRecord and ActiveJob, which your Rails app already has.
+
+```bash
+rails g omnibot:install       # also creates the omnibot_workflow_runs migration (skipped if it exists)
+rails g omnibot:workflow DepositCheck
+```
+
+```ruby
+class DepositCheckWorkflow < Omnibot::Workflow
+  state :amount, :bank, :paid
+
+  step :ask_for_proof do
+    reply "Please upload your transfer receipt 🙏"
+    wait_for_input                              # checkpoint: pause and persist; resumes on the next message
+  end
+
+  step :extract_proof do
+    proof = ProofAgent.extract(input, schema: Class.new)   # input = what resume() received
+    state.amount = proof[:amount]
+    state.bank = proof[:bank]
+    reply "Got it — Rp#{state.amount} via #{state.bank}. Checking with the gateway…"
+  end
+
+  step :watch_gateway, poll: { every: 5, max_attempts: 5 } do
+    status = gateway_check
+    if status == :pending
+      reply "Still checking with the gateway… (attempt #{attempts})"
+      poll_again                                # schedule the next tick, stop this one
+    end
+    state.paid = (status == :paid)
+  end
+
+  transition from: :ask_for_proof, to: :extract_proof
+  transition from: :extract_proof, to: :watch_gateway
+  transition from: :watch_gateway, to: :done, if: -> { state.paid }
+  transition from: :watch_gateway, to: :failed
+end
+
+run = DepositCheckWorkflow.start
+run.status          # => "waiting_for_input"
+run.replies         # => ["Please upload your transfer receipt 🙏"]
+
+run = DepositCheckWorkflow.resume(run, input: "transfer 50rb via BCA, receipt attached")
+run.status          # => "running" — now polling the gateway on an ActiveJob timer
+run.current_step    # => "watch_gateway"
+run.state["amount"] # => 50_000
+```
+
+This is the same flow as `examples/deposit_check.rb` (runnable: `bundle exec ruby examples/deposit_check.rb`) and `spec/omnibot/workflow_integration_spec.rb` — copy-paste it and swap in your own agent/gateway calls.
+
+A step body runs at most once per entry: `wait_for_input` throws out of the step immediately (statements after it never run), so bodies need no idempotence gymnastics. After a step returns normally, transitions are evaluated in declaration order — first matching `if:` wins (unconditional always matches) — and the run walks into the next step in the same activation, stopping only at `wait_for_input`, `handover!`, a poll schedule, a terminal step (`:done`, `:expired`, `:failed`, `:cancelled`, or any user step with no outgoing transitions), or an exception (→ `failed`, with `run.error` set).
+
+**Replies have two delivery paths.** Foreground activations (`start`/`resume`) return the activation's replies on `run.replies`. Background activations — a poll tick or a timeout firing via `Omnibot::WorkflowTimerJob` — have no caller to return to, so `reply` *always* also emits `omnibot.workflow.reply`; that's the one seam for both. Bridge it to your message provider with a one-line subscriber:
+
+```ruby
+ActiveSupport::Notifications.subscribe("omnibot.workflow.reply") do |event|
+  YourMessenger.send(event.payload[:run_id], event.payload[:text])
+end
+```
+
+**Human handover and control operations:**
+
+```ruby
+run.status              # => "waiting_for_human" after a step calls handover!(reason: "...")
+run.resume_from_human    # re-enters the current step as a fresh attempt
+run.retry!               # re-enters a *failed* run's current step (attempts increments)
+run.cancel!               # any active run -> "cancelled"; raises Omnibot::WorkflowError::StaleResume if already terminal
+```
+
+`resume` raises `Omnibot::WorkflowError::StaleResume` when the run is terminal (`done`/`failed`/`expired`/`cancelled`) or `waiting_for_human` (its own message points you at `resume_from_human` instead). `while_running :ignore` (the default) makes `resume` on a still-`running` run a no-op that returns it unchanged — this is the only mode v0.2 implements; `while_running :interrupt` (abort the in-flight step and apply the new input immediately) is documented but raises `NotImplementedError` and ships in v0.3. Resuming a run sitting at a `wait_for_input` checkpoint evaluates its transitions and re-enters; if that lands on another `wait_for_input` checkpoint, it simply resumes again next time.
+
+Timers (`timeout :step, after:, to:`, and poll's `every:`) are ActiveJob, scheduled with `set(wait:)`, and stale-checked against a per-entry `timer_token` before they act — a fired timer from a step the run has since left is a safe no-op. **Running the example:** the demo and integration spec use ActiveJob's `:test` adapter with `perform_enqueued_jobs`, not `:inline` — `InlineAdapter#enqueue_at` isn't implemented in any ActiveJob version we've checked, so `:inline` can't run a `poll`/`timeout` step at all. See "Production queue adapters" below for real deployments.
+
+**Production queue adapters:** schedule jobs fire through `Omnibot::WorkflowTimerJob` via ActiveJob, so `wait:` timing depends on your adapter's `enqueue_at` support (Sidekiq, Sidekiq Cron, GoodJob, etc. all handle it — `:inline` and `:async` don't). Set `Omnibot::WorkflowTimerJob.enqueue_after_transaction_commit` so a timer scheduled inside a still-open transaction doesn't fire before the transaction commits — on Rails 7.2 that setting takes a symbol (`= :always`); on Rails 8.0+ it also accepts a boolean (`= true`). On Rails 7.1 the setting doesn't exist at all — rely on the token guard instead: a rolled-back activation may still enqueue a harmless no-op job, but the job re-checks `status`/`current_step`/`timer_token` under `with_lock` before doing anything, so the stale timer just finds nothing to do (the `timer_token` guard makes it self-healing).
+
 ## Instrumentation
 
 Everything is instrumented via `ActiveSupport::Notifications`, so you can wire usage logging, cost caps, or a dashboard without touching the gem:
@@ -186,7 +263,17 @@ Everything is instrumented via `ActiveSupport::Notifications`, so you can wire u
 
 `omnibot.llm.call`'s `usage:` is per-call (that one provider round trip's final response). `omnibot.agent.run`'s `usage:` is the run total, summed across every provider round trip in the run — a single `Agent.run` can be several `omnibot.llm.call`s deep when the tool-calling loop goes more than one turn.
 
-Timing is available on the event object itself (`event.duration`) for any subscribed event — it is not a payload key. Workflow events (`omnibot.workflow.*`) arrive with Workflow in v0.2.
+Workflow (v0.2) emits its own events on the same seam:
+
+| Event | Payload keys |
+|---|---|
+| `omnibot.workflow.step` | `workflow:` (Workflow class), `run_id:`, `step:` (Symbol), `attempts:` (Integer), `status:` (String, the run's status after the step body ran), `error:` (String, present only when the step raised) |
+| `omnibot.workflow.transition` | `workflow:`, `run_id:`, `from:` (Symbol), `to:` (Symbol) |
+| `omnibot.workflow.reply` | `workflow:`, `run_id:`, `step:` (String — `run.current_step`), `text:` (String) |
+| `omnibot.workflow.handover` | `workflow:`, `run_id:`, `step:` (String), `reason:` (whatever was passed to `handover!`) |
+| `omnibot.workflow.timeout` | `workflow:`, `run_id:`, `step:` (Symbol) |
+
+Timing is available on the event object itself (`event.duration`) for any subscribed event — it is not a payload key.
 
 A minimal usage-log subscriber — the whole recipe is 4 lines:
 
@@ -201,8 +288,9 @@ Nothing in the gem phones home, ever — instrumentation is a local seam you sub
 
 ## Roadmap
 
-- **v0.2 — Workflow.** A durable, ActiveRecord-checkpointed graph engine for multi-step conversations: steps as nodes, transitions as edges, `wait_for_input` to checkpoint and pause for the next inbound message, `handover!` to page a human. State persists as jsonb on a gem-owned `omnibot_workflow_runs` table, so a workflow survives a deploy or a restart mid-conversation without a Redis checkpointer.
-- **Later — hosted observability.** A subscriber gem plus a hosted dashboard, built entirely on the instrumentation events above. Paid, optional, and no core changes required to adopt it.
+- **v0.2 — Workflow. Shipped.** A durable, ActiveRecord-checkpointed graph engine for multi-step conversations: steps as nodes, transitions as edges, `wait_for_input` to checkpoint and pause for the next inbound message, `handover!` to page a human. State persists as jsonb on a gem-owned `omnibot_workflow_runs` table, so a workflow survives a deploy or a restart mid-conversation without a Redis checkpointer. See [Durable workflows](#durable-workflows) above.
+- **Next — hosted observability.** A subscriber gem plus a hosted dashboard, built entirely on the instrumentation events above (Agent and Workflow both). Paid, optional, and no core changes required to adopt it.
+- **Next — `while_running :interrupt`.** Full semantics for aborting an in-flight step when a new message arrives mid-activation, if demand shows up; `:ignore` is the only implemented mode today.
 
 ## License
 

data/lib/generators/omnibot/install/install_generator.rb

@@ -1,13 +1,25 @@
 require "rails/generators"
+require "rails/generators/migration"
 
 module Omnibot
   module Generators
     class InstallGenerator < Rails::Generators::Base
+      include Rails::Generators::Migration
       source_root File.expand_path("templates", __dir__)
 
+      def self.next_migration_number(_dir)
+        Time.now.utc.strftime("%Y%m%d%H%M%S")
+      end
+
       def create_initializer
         template "initializer.rb.tt", "config/initializers/omnibot.rb"
       end
+
+      def create_workflow_runs_migration
+        return if Dir[File.join(destination_root, "db/migrate/*_create_omnibot_workflow_runs.rb")].any?
+        migration_template "create_omnibot_workflow_runs.rb.tt",
+                            "db/migrate/create_omnibot_workflow_runs.rb"
+      end
     end
   end
 end

data/lib/generators/omnibot/install/templates/create_omnibot_workflow_runs.rb.tt

@@ -0,0 +1,19 @@
+class CreateOmnibotWorkflowRuns < ActiveRecord::Migration[7.1]
+  def change
+    create_table :omnibot_workflow_runs do |t|
+      t.string :type, null: false
+      t.string :status, null: false
+      t.string :current_step
+      # On PostgreSQL you may change this to t.jsonb
+      t.json :state, default: {}
+      t.integer :attempts, default: 0, null: false
+      t.datetime :step_entered_at
+      t.integer :timer_token, default: 0, null: false
+      t.references :ref, polymorphic: true, index: true
+      t.text :error
+      t.timestamps
+    end
+    add_index :omnibot_workflow_runs, :status
+    add_index :omnibot_workflow_runs, [:type, :status]
+  end
+end

data/lib/generators/omnibot/workflow/templates/workflow.rb.tt

@@ -0,0 +1,16 @@
+class <%= class_name %>Workflow < Omnibot::Workflow
+  state :example_field
+
+  step :ask do
+    reply "What can I help you with?"
+    wait_for_input                     # checkpoint: resumes on the next message
+  end
+
+  step :handle do
+    state.example_field = input
+  end
+
+  transition from: :ask, to: :handle
+  transition from: :handle, to: :done
+  timeout :ask, after: 30.minutes, to: :expired
+end

data/lib/generators/omnibot/workflow/templates/workflow_spec.rb.tt

@@ -0,0 +1,12 @@
+require "rails_helper"
+
+RSpec.describe <%= class_name %>Workflow do
+  it "asks, waits, and completes on input" do
+    run = <%= class_name %>Workflow.start
+    expect(run.status).to eq("waiting_for_input")
+    expect(run.replies).to eq(["What can I help you with?"])
+
+    run = <%= class_name %>Workflow.resume(run, input: "hello")
+    expect(run.status).to eq("done")
+  end
+end

data/lib/generators/omnibot/workflow/workflow_generator.rb

@@ -0,0 +1,14 @@
+require "rails/generators"
+
+module Omnibot
+  module Generators
+    class WorkflowGenerator < Rails::Generators::NamedBase
+      source_root File.expand_path("templates", __dir__)
+
+      def create_workflow
+        template "workflow.rb.tt", "app/workflows/#{file_name}_workflow.rb"
+        template "workflow_spec.rb.tt", "spec/workflows/#{file_name}_workflow_spec.rb"
+      end
+    end
+  end
+end

data/lib/omnibot/errors.rb

@@ -3,5 +3,8 @@ module Omnibot
   class LLMError < Error; end
   class ToolError < Error; end
   class ExtractionError < Error; end
-  class WorkflowError < Error; end
+  class WorkflowError < Error
+    class InvalidTransition < WorkflowError; end
+    class StaleResume < WorkflowError; end
+  end
 end

data/lib/omnibot/version.rb

@@ -1,3 +1,3 @@
 module Omnibot
-  VERSION = "0.1.0"
+  VERSION = "0.2.0"
 end

data/lib/omnibot/workflow/runner.rb

@@ -0,0 +1,196 @@
+module Omnibot
+  class Workflow
+    INTERRUPT = :__omnibot_workflow_interrupt
+
+    # Runs inside run.with_lock, always.
+    class Runner
+      MAX_STEPS_PER_ACTIVATION = 100
+
+      def initialize(run)
+        @run = run
+        @workflow = run.workflow_class
+      end
+
+      # Enter `step` (fresh entry or re-entry), then follow transitions
+      # until an interrupt, terminal step, or error stops the loop.
+      def enter(step, input: nil)
+        iterations = 0
+        loop do
+          iterations += 1
+          if iterations > MAX_STEPS_PER_ACTIVATION
+            return fail_run("activation exceeded #{MAX_STEPS_PER_ACTIVATION} step entries " \
+                             "(transition loop at :#{step}?)")
+          end
+          record_entry(step)
+          ctx = ExecutionContext.new(@run, @workflow, input)
+          outcome = execute_body(step, ctx)
+          case outcome
+          in { interrupt: :wait_input } then return checkpoint("waiting_for_input")
+          in { interrupt: :handover }   then return checkpoint("waiting_for_human")
+          in { interrupt: :poll_again } then return schedule_poll(step)
+          in { error: e }               then return fail_run(e.message)
+          in { completed: true }
+            input = nil # input is consumed by the first step that runs after resume
+            nxt = next_step_from(step, ctx)
+            return if nxt.nil? # fail_run already called
+            return complete(nxt) if TERMINAL_STEPS.include?(nxt)
+            step = nxt
+          end
+        end
+      end
+
+      def poll_tick(step)
+        poll = @workflow.steps.fetch(step)[:poll]
+        if @run.attempts >= poll[:max_attempts]
+          target = @workflow.timeouts[step]&.fetch(:to) || :expired
+          if TERMINAL_STEPS.include?(target)
+            complete(target)
+          else
+            @run.update!(status: "running")
+            enter(target)
+          end
+          return
+        end
+        enter(step)
+      end
+
+      private
+
+      def record_entry(step)
+        # attempts.positive? distinguishes a genuine first entry (attempts=0, current_step
+        # pre-seeded by create!) from a re-entry into the same step.
+        same = @run.current_step == step.to_s && @run.attempts.positive?
+        @run.attempts    = same ? @run.attempts + 1 : 1
+        @run.current_step = step.to_s
+        @run.timer_token += 1
+        @run.step_entered_at = Time.current
+        @run.save!
+
+        if (t = @workflow.timeouts[step])
+          WorkflowTimerJob.set(wait: t[:after])
+                          .perform_later(@run.id, step.to_s, @run.timer_token, "timeout")
+        end
+      end
+
+      def execute_body(step, ctx)
+        body = @workflow.steps.fetch(step)[:body]
+        ActiveSupport::Notifications.instrument(
+          "omnibot.workflow.step",
+          workflow: @workflow, run_id: @run.id, step: step, attempts: @run.attempts
+        ) do |payload|
+          interrupted = catch(INTERRUPT) do
+            ctx.instance_exec(&body)
+            nil
+          end
+          payload[:status] = @run.status
+          interrupted ? { interrupt: interrupted } : { completed: true }
+        rescue StandardError => e
+          payload[:error] = e.message
+          payload[:status] = "failed"
+          { error: e }
+        end
+      end
+
+      def next_step_from(step, ctx)
+        rules = @workflow.transitions.select { |t| t[:from] == step }
+        return :done if rules.empty? # terminal-by-absence
+        rule = rules.find do |t|
+          next true if t[:if].nil?
+          begin
+            ctx.instance_exec(&t[:if])
+          rescue StandardError => e
+            fail_run("transition condition from :#{step} raised: #{e.message}")
+            return nil
+          end
+        end
+        if rule.nil?
+          fail_run("no transition matched from :#{step}")
+          return nil
+        end
+        ActiveSupport::Notifications.instrument(
+          "omnibot.workflow.transition",
+          workflow: @workflow, run_id: @run.id, from: step, to: rule[:to]
+        )
+        rule[:to]
+      end
+
+      def complete(terminal_step)
+        if terminal_step == :done && (hook = @workflow.on_complete_hook)
+          begin
+            ExecutionContext.new(@run, @workflow, nil).instance_exec(&hook)
+          rescue StandardError => e
+            # ponytail: a completed workflow whose hook failed lands in failed — retry! re-runs the
+            # FINAL step, so hooks should be idempotent
+            return fail_run("on_complete hook raised: #{e.message}")
+          end
+        end
+        @run.update!(status: terminal_step.to_s)
+      end
+
+      def fail_run(message)
+        @run.update!(status: "failed", error: message)
+      end
+
+      def checkpoint(status)
+        @run.update!(status: status)
+      end
+
+      def schedule_poll(step)
+        poll = @workflow.steps.fetch(step)[:poll]
+        return fail_run("poll_again called from non-poll step :#{step}") if poll.nil?
+        @run.update!(status: "running")
+        WorkflowTimerJob.set(wait: poll[:every])
+                        .perform_later(@run.id, step.to_s, @run.timer_token, "poll")
+      end
+    end
+
+    class ExecutionContext
+      attr_reader :run, :input
+
+      def initialize(run, workflow, input)
+        @run = run
+        @workflow = workflow
+        @input = input
+        define_state_proxy
+      end
+
+      def state = @state_proxy
+      def attempts = @run.attempts
+
+      def reply(text)
+        @run.replies << text
+        ActiveSupport::Notifications.instrument(
+          "omnibot.workflow.reply",
+          workflow: @workflow, run_id: @run.id, step: @run.current_step, text: text
+        )
+        text
+      end
+
+      def wait_for_input = throw(INTERRUPT, :wait_input)
+
+      def handover!(reason: nil)
+        ActiveSupport::Notifications.instrument(
+          "omnibot.workflow.handover",
+          workflow: @workflow, run_id: @run.id, step: @run.current_step, reason: reason
+        )
+        throw(INTERRUPT, :handover)
+      end
+
+      def poll_again = throw(INTERRUPT, :poll_again)
+
+      private
+
+      def define_state_proxy
+        run = @run
+        keys = @workflow.state_keys
+        @state_proxy = Object.new
+        keys.each do |key|
+          @state_proxy.define_singleton_method(key) { run.state[key.to_s] }
+          @state_proxy.define_singleton_method("#{key}=") do |v|
+            run.state = run.state.merge(key.to_s => v)
+          end
+        end
+      end
+    end
+  end
+end

data/lib/omnibot/workflow.rb

@@ -0,0 +1,127 @@
+module Omnibot
+  class Workflow
+    TERMINAL_STEPS = %i[done expired failed cancelled].freeze
+    WHILE_RUNNING_MODES = %i[ignore interrupt].freeze
+
+    class << self
+      def state(*keys) = keys.any? ? state_keys.concat(keys) : state_keys
+      def state_keys = @state_keys ||= []
+
+      def step(name, poll: nil, &body)
+        steps[name.to_sym] = { body: body, poll: poll }
+      end
+
+      def steps = @steps ||= {}
+
+      def transition(from:, to:, if: nil)
+        cond = binding.local_variable_get(:if)
+        transitions << { from: from.to_sym, to: to.to_sym, if: cond }
+      end
+
+      def transitions = @transitions ||= []
+
+      def timeout(step, after:, to:)
+        timeouts[step.to_sym] = { after: after, to: to.to_sym }
+      end
+
+      def timeouts = @timeouts ||= {}
+
+      def on_complete(&blk) = blk ? @on_complete_hook = blk : nil
+      def on_complete_hook = @on_complete_hook
+
+      def while_running(mode = nil)
+        return @while_running || :ignore if mode.nil?
+        unless WHILE_RUNNING_MODES.include?(mode)
+          raise ArgumentError, "while_running must be :ignore or :interrupt"
+        end
+        @while_running = mode
+      end
+
+      def start(ref: nil, state: {})
+        first = steps.keys.first or raise WorkflowError, "#{name} declares no steps"
+        run = WorkflowRun.create!(
+          type: name, status: "running", current_step: first.to_s,
+          state: state.transform_keys(&:to_s), attempts: 0, timer_token: 0,
+          step_entered_at: Time.current, ref: ref
+        )
+        run.replies = []
+        run.with_lock { Runner.new(run).enter(first) }
+        run
+      end
+
+      def resume(run, input: nil)
+        run.reload
+        run.replies = []
+        run.with_lock do
+          case run.status
+          when "waiting_for_input"
+            step = run.current_step.to_sym
+            ctx = ExecutionContext.new(run, self, input)
+            runner = Runner.new(run)
+            nxt = runner.send(:next_step_from, step, ctx)
+            break if nxt.nil?
+            if TERMINAL_STEPS.include?(nxt)
+              runner.send(:complete, nxt)
+            else
+              runner.enter(nxt, input: input)
+            end
+          when "running"
+            if while_running == :interrupt
+              raise NotImplementedError, "while_running :interrupt ships in v0.3"
+            end
+            # :ignore — return unchanged
+          when "waiting_for_human"
+            raise WorkflowError::StaleResume, "use resume_from_human for waiting_for_human runs"
+          else
+            raise WorkflowError::StaleResume, "cannot resume a #{run.status} run"
+          end
+        end
+        run
+      end
+
+      def resume_from_human(run, input: nil)
+        control(run, allowed: %w[waiting_for_human]) do
+          run.update!(status: "running")
+          Runner.new(run).enter(run.current_step.to_sym, input: input)
+        end
+      end
+
+      def retry!(run)
+        control(run, allowed: %w[failed]) do
+          run.update!(status: "running", error: nil)
+          Runner.new(run).enter(run.current_step.to_sym)
+        end
+      end
+
+      def cancel!(run)
+        control(run, allowed: WorkflowRun::ACTIVE_STATUSES) do
+          run.update!(status: "cancelled")
+        end
+      end
+
+      private
+
+      def control(run, allowed:)
+        run.reload
+        run.replies = []
+        run.with_lock do
+          unless allowed.include?(run.status)
+            raise WorkflowError::StaleResume, "cannot perform this on a #{run.status} run"
+          end
+          yield
+        end
+        run
+      end
+
+      def inherited(subclass)
+        super
+        subclass.instance_variable_set(:@state_keys, state_keys.dup)
+        subclass.instance_variable_set(:@steps, steps.dup)
+        subclass.instance_variable_set(:@transitions, transitions.map(&:dup))
+        subclass.instance_variable_set(:@timeouts, timeouts.dup)
+        subclass.instance_variable_set(:@on_complete_hook, @on_complete_hook)
+        subclass.instance_variable_set(:@while_running, @while_running)
+      end
+    end
+  end
+end

data/lib/omnibot/workflow_run.rb

@@ -0,0 +1,25 @@
+require "active_record"
+
+module Omnibot
+  class WorkflowRun < ActiveRecord::Base
+    self.table_name = "omnibot_workflow_runs"
+    self.inheritance_column = nil # `type` stores the workflow class name, not STI
+
+    ACTIVE_STATUSES   = %w[running waiting_for_input waiting_for_human].freeze
+    TERMINAL_STATUSES = %w[done failed expired cancelled].freeze
+
+    belongs_to :ref, polymorphic: true, optional: true
+
+    attr_accessor :replies
+
+    after_initialize { @replies ||= [] }
+
+    def active?   = ACTIVE_STATUSES.include?(status)
+    def terminal? = TERMINAL_STATUSES.include?(status)
+    def workflow_class = type.constantize
+
+    def retry!  = workflow_class.retry!(self)
+    def cancel! = workflow_class.cancel!(self)
+    def resume_from_human(input: nil) = workflow_class.resume_from_human(self, input: input)
+  end
+end

data/lib/omnibot/workflow_timer_job.rb

@@ -0,0 +1,31 @@
+module Omnibot
+  class WorkflowTimerJob < ActiveJob::Base
+    def perform(run_id, step, token, kind)
+      run = WorkflowRun.find_by(id: run_id) or return
+      run.replies = []
+      run.with_lock do
+        return unless run.active?
+        return unless run.current_step == step && run.timer_token == token
+
+        workflow = run.workflow_class
+        case kind
+        when "timeout"
+          ActiveSupport::Notifications.instrument(
+            "omnibot.workflow.timeout",
+            workflow: workflow, run_id: run.id, step: step.to_sym
+          )
+          target = workflow.timeouts.fetch(step.to_sym)[:to]
+          runner = Workflow::Runner.new(run)
+          if Workflow::TERMINAL_STEPS.include?(target)
+            runner.send(:complete, target)
+          else
+            run.update!(status: "running")
+            runner.enter(target)
+          end
+        when "poll"
+          Workflow::Runner.new(run).poll_tick(step.to_sym)
+        end
+      end
+    end
+  end
+end

data/lib/omnibot.rb

@@ -3,6 +3,8 @@ require "active_support"
 require "active_support/core_ext"
 require "active_support/notifications"
 require "ruby_llm"
+require "active_record"
+require "active_job"
 
 require_relative "omnibot/version"
 require_relative "omnibot/errors"
@@ -11,3 +13,7 @@ require_relative "omnibot/tool"
 require_relative "omnibot/result"
 require_relative "omnibot/agent"
 require_relative "omnibot/testing"
+require_relative "omnibot/workflow_run"
+require_relative "omnibot/workflow"
+require_relative "omnibot/workflow/runner"
+require_relative "omnibot/workflow_timer_job"

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: omnibot-ruby
 version: !ruby/object:Gem::Version
-  version: 0.1.0
+  version: 0.2.0
 platform: ruby
 authors:
 - Johannes Dwicahyo
@@ -37,6 +37,34 @@ dependencies:
     - - ">="
       - !ruby/object:Gem::Version
         version: '7.1'
+- !ruby/object:Gem::Dependency
+  name: activerecord
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '7.1'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '7.1'
+- !ruby/object:Gem::Dependency
+  name: activejob
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '7.1'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '7.1'
 description: 'Agent framework for Rails: bounded tool-calling loops, fast paths, structured
   extraction, and (v0.2) durable workflows on ActiveRecord. Built on ruby_llm.'
 email:
@@ -51,7 +79,11 @@ files:
 - lib/generators/omnibot/agent/templates/agent.rb.tt
 - lib/generators/omnibot/agent/templates/agent_spec.rb.tt
 - lib/generators/omnibot/install/install_generator.rb
+- lib/generators/omnibot/install/templates/create_omnibot_workflow_runs.rb.tt
 - lib/generators/omnibot/install/templates/initializer.rb.tt
+- lib/generators/omnibot/workflow/templates/workflow.rb.tt
+- lib/generators/omnibot/workflow/templates/workflow_spec.rb.tt
+- lib/generators/omnibot/workflow/workflow_generator.rb
 - lib/omnibot.rb
 - lib/omnibot/agent.rb
 - lib/omnibot/config.rb
@@ -60,6 +92,10 @@ files:
 - lib/omnibot/testing.rb
 - lib/omnibot/tool.rb
 - lib/omnibot/version.rb
+- lib/omnibot/workflow.rb
+- lib/omnibot/workflow/runner.rb
+- lib/omnibot/workflow_run.rb
+- lib/omnibot/workflow_timer_job.rb
 homepage: https://github.com/johannesdwicahyo/omnibot-ruby
 licenses:
 - MIT