rcrewai-rails 0.7.1 → 0.8.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: ec3c830730933e9510d7749b89decd73af35f5b69e5f6f441a21d0cca9290b61
-  data.tar.gz: 698877cbbaf6cd49924144a585b5d32a4817ddd1e51307d34cd488f51ba5d0a7
+  metadata.gz: 89c254df462d78758a78ea3ac3e54c2aef26cc0126f3c0db941ae2c0ad23b607
+  data.tar.gz: '029aab1519fbb10ac847dc043cdaa1dcaed493cce784a3186ef439ad3b9206bd'
 SHA512:
-  metadata.gz: 94f1e5d38e34c5a8668a4c1be005d3fe4cf6e6e29353ea580de7581485262948af2824f166feb58e4903e59e3aef8dfd3eb1c3ecf8642da021b1f15e3025e89d
-  data.tar.gz: 71e6c33d7e34a248ce650556a1cb5bc900d20f282f02fccb82fe2fadd71744ea45fddb618962da777488213084f0048057817e6572f46f27320d40d685b6e14f
+  metadata.gz: c69a4a28cf7927140a04724cf9e2e66e05cf777c12e7e259c5cb4d5e36b3e3ed68b31d2702cb337d2be009f1789408d1e7c91047f3e77252c7f77313943a18f0
+  data.tar.gz: 7cd18030c6621e9fbad921f4f3bd3d96680796a73238b907f7cc5bd877ae1e8e53d8eacdb6b9151de7c2000d3b27ea7e068b146ca6b300742d65275076f30907

data/CHANGELOG.md

@@ -7,6 +7,102 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [0.8.1] - 2026-09-10
+
+### Fixed
+- **Enabling checkpointing without running the 0.8 migration failed mid-run.**
+  `CrewExecutionJob` built the default `ActiveRecordCheckpointStore` without
+  checking that its table existed, so the run raised
+  `ActiveRecord::StatementInvalid: Could not find table 'rcrewai_checkpoints'`
+  partway through — after tasks had already executed and been paid for, and
+  with nothing in the message naming the cause. The job now fails up front with
+  `CheckpointTableMissing`, whose message names the migration command to run.
+  It is `discard_on`'d rather than retried, since retrying cannot fix a missing
+  table. Configuring a custom `checkpoint_store` skips the check, and nothing
+  changes when checkpointing is off (the default).
+- **The test suite was order-dependent.** `real_migrate_spec` and
+  `upgrade_migrate_spec` called `ActiveRecord::Base.establish_connection` to get
+  a scratch database for migrating. The test database is sqlite3 `":memory:"`,
+  so that discarded the pool holding Combustion's schema, and reconnecting gave
+  an empty database — every later example lost its tables. The suite passed only
+  because those specs happened to run last: under `--order random` it failed
+  ~128 of 258 examples. Migrations now run against an isolated connection via
+  `ActiveRecord::Tasks::DatabaseTasks.migration_class`, leaving the suite's own
+  connection untouched.
+- **`rails_logger_tool_spec` leaked a fake `Rails.logger`** into every example
+  that ran after it. The fake accepts exactly one argument, so unrelated specs
+  logging through the real logger raised `ArgumentError: wrong number of
+  arguments`. It is now restored after each example.
+
+### Changed
+- Specs run in random order by default (`config.order = :random`), so an example
+  that leaks global state fails immediately instead of silently depending on
+  file order. Seeds are reproducible: `bundle exec rspec --seed 1234`.
+
+## [0.8.0] - 2026-09-10
+
+Tracks **rcrewai 0.8.0**, which is backward compatible for this engine — the
+0.7.1 suite passed against it unchanged. This release is about surfacing the
+new capabilities in Rails terms: durable **checkpointing** with resume, **LLM
+interceptors**, and the **event hierarchy**, plus the four new providers.
+
+### Added
+- **Checkpointing.** `RcrewAI::Rails::ActiveRecordCheckpointStore` persists
+  rcrewai crew checkpoints to the new `rcrewai_checkpoints` table, implementing
+  the gem's store contract (`save`/`load`/`list`/`delete`). Enable globally with
+  `config.checkpoint_enabled = true`, or per crew via the new
+  `checkpoint_enabled` column. Records are stored verbatim as JSON, so a record
+  written by any store implementation round-trips identically.
+- **Resume.** `crew.resume_async(execution)` / `crew.resume_sync(execution)`
+  re-run a checkpointed execution, replaying tasks that already completed
+  instead of paying for them again. Accepts an `Execution` or a bare run id.
+  `crew.resumable_executions` lists what can be resumed.
+- **Run lineage.** Executions record `run_id` and `parent_run_id`, so a resumed
+  run links back to the one it continues and `RCrewAI::Checkpoint.lineage`
+  walks the chain. `RcrewAI::Rails::Checkpoint` exposes `children`, `roots`,
+  `completed_task_names` and `failed_task_names`.
+- **LLM interceptors.** `config.llm_before_request` and
+  `config.llm_after_response` attach rcrewai 0.8 hooks to every client the
+  engine builds. The gem forwards hooks only through `LLMClient.for_provider`,
+  and agents resolve their client via `LLMClient.resolve`, which does not — so
+  the engine registers them on the built client, covering per-agent LLMs too.
+- **New providers.** `openai_compatible`, `bedrock`, `snowflake` and
+  `openai_responses` resolve through an agent's `llm_config` and are documented
+  in the generated initializer. (No engine change was required — provider
+  values pass through to the gem — but they are now covered by specs.)
+
+### Fixed
+- **Crew inputs never reached the gem.** `CrewExecutionJob` persisted the
+  execution's `inputs` but called `rcrew.execute` without them, so
+  `before_kickoff` hooks and `Crew#last_inputs` always saw `{}` and no task
+  could interpolate an input. Inputs are now forwarded. Pre-existing, unrelated
+  to the upgrade.
+- **Concurrent runs of the same agent shared one span stack.** The observation
+  collector keyed open spans by agent name, so when one agent ran twice
+  concurrently, one run's tool call could nest under the other run's iteration
+  (and its usage, text and errors could land on the wrong span). rcrewai 0.8
+  stamps every event with the id of its enclosing run span; the collector now
+  scopes its bookkeeping by that id. Events without one — older streams, and
+  the engine's own crew/agent spans — keep the previous behavior.
+
+### Changed
+- Requires `rcrewai ~> 0.8.0`.
+- `SpanStack.key_for` takes an optional second argument (the run id) and
+  `push`/`pop`/`current` take an optional `run_id:`. Existing calls without it
+  behave as before.
+
+### Upgrading
+Existing installs need the new migration:
+
+```bash
+$ rails rcrew_ai_rails:install:migrations
+$ rails db:migrate
+```
+
+This adds `rcrewai_checkpoints`, `rcrewai_crews.checkpoint_enabled`, and
+`run_id`/`parent_run_id` on `rcrewai_executions`. Checkpointing is off by
+default, so nothing changes until you enable it.
+
 ## [0.7.1] - 2026-08-13
 
 ### Fixed
@@ -178,7 +274,9 @@ existing agents, tasks, and crews build unchanged.
 ### Changed
 - Rename generators from `rcrew_a_i` to `rcrewai` namespacing.
 
-[Unreleased]: https://github.com/gkosmo/rcrewai-rails/compare/v0.7.1...HEAD
+[Unreleased]: https://github.com/gkosmo/rcrewai-rails/compare/v0.8.1...HEAD
+[0.8.1]: https://github.com/gkosmo/rcrewai-rails/compare/v0.8.0...v0.8.1
+[0.8.0]: https://github.com/gkosmo/rcrewai-rails/compare/v0.7.1...v0.8.0
 [0.7.1]: https://github.com/gkosmo/rcrewai-rails/compare/v0.7.0...v0.7.1
 [0.7.0]: https://github.com/gkosmo/rcrewai-rails/compare/v0.6.1...v0.7.0
 [0.6.1]: https://github.com/gkosmo/rcrewai-rails/compare/v0.6.0...v0.6.1

data/README.md

@@ -10,11 +10,12 @@ Rails engine for integrating [RcrewAI](https://github.com/gkosmo/rcrewai-rails)
 - **Web UI**: Monitor and manage crews through a built-in interface
 - **Rails-Specific Tools**: Pre-built tools for ActiveRecord, ActionMailer, Rails cache, and more
 - **Configuration**: Flexible configuration through Rails initializers
-- **Full rcrewai 0.7 feature coverage** (see [rcrewai 0.7 capabilities](#rcrewai-07-capabilities)):
+- **Full rcrewai 0.8 feature coverage** (see [rcrewai 0.8 capabilities](#rcrewai-08-capabilities) and [rcrewai 0.7 capabilities](#rcrewai-07-capabilities)):
   - Agent config: reasoning, per-agent LLM, rate limiting, context-window trimming, cognitive memory
   - Task output: structured output schemas, guardrails, file output, multimodal attachments
   - Crew: `before_kickoff`/`after_kickoff` hooks, planning, the `consensual` process, batch execution
   - Knowledge (RAG) sources and Flow persistence
+  - Checkpointing with resume, LLM interceptors, and the Bedrock / Snowflake / OpenAI-compatible providers
 
 ## Observation Engine
 
@@ -103,14 +104,20 @@ $ rails db:migrate
 (The task name comes from the engine's railtie name, `rcrew_ai_rails`.)
 
 Rails copies only the migrations your app does not already have. Upgrading to
-0.7.0 from 0.6.x adds two:
+0.8.0 from 0.7.x adds one:
+
+| Migration | Purpose |
+|---|---|
+| `012_create_rcrewai_checkpoints` | `rcrewai_checkpoints`, `rcrewai_crews.checkpoint_enabled`, and `run_id`/`parent_run_id` on executions — checkpointing and resume |
+
+Upgrading from 0.6.x adds two more:
 
 | Migration | Purpose |
 |---|---|
 | `010_create_rcrewai_spans` | `rcrewai_spans` and `rcrewai_span_events` — the observation engine's trace tree |
 | `011_add_observation_rollups_to_rcrewai_executions` | `total_cost_usd`, `total_tokens`, `span_count`, `error_count` on executions |
 
-Both are additive: no existing column or table is changed, and nothing is
+All are additive: no existing column or table is changed, and nothing is
 dropped. Existing crews, agents, tasks, and executions are unaffected, and
 observation is enabled by default once the tables exist. To upgrade the gem
 without turning tracing on, set `config.observation_enabled = false` in
@@ -269,10 +276,91 @@ crew.execute_sync(inputs)
 CrewExecutionJob.set(wait: 5.minutes).perform_later(crew, inputs)
 ```
 
+## rcrewai 0.8 capabilities
+
+This engine tracks [rcrewai](https://github.com/gkosmo/rcrewAI) `~> 0.8`.
+
+### Checkpointing and resume
+
+A crew run can record durable per-task state, so an interrupted run resumes
+instead of re-executing (and re-paying for) the tasks that already finished.
+Checkpoints are written to `rcrewai_checkpoints` after each task settles.
+
+```ruby
+# Globally, in config/initializers/rcrewai.rb
+config.checkpoint_enabled = true
+
+# ...or per crew
+crew.update!(checkpoint_enabled: true)
+
+execution = crew.executions.order(:id).last
+execution.run_id          # => the checkpointed run
+
+# Resume it: completed tasks are replayed, the rest execute.
+crew.resume_sync(execution)     # or resume_async(execution)
+crew.resumable_executions       # executions that recorded a run id
+```
+
+A resumed run gets its own `run_id` and records the original in
+`parent_run_id`, leaving the first run's record intact:
+
+```ruby
+store = RcrewAI::Rails::ActiveRecordCheckpointStore.new
+RCrewAI::Checkpoint.lineage(store, resumed.run_id)
+# => ["<original run id>", "<resumed run id>"]
+```
+
+Any object responding to `save`/`load`/`list`/`delete` can replace the store via
+`config.checkpoint_store`.
+
+Checkpointing needs the `rcrewai_checkpoints` table, so run the migration when
+you enable it (see [Upgrading an existing install](#upgrading-an-existing-install)).
+If the table is missing, the job raises `CheckpointTableMissing` up front rather
+than failing partway through a run.
+
+### LLM interceptors
+
+Hooks that run around every LLM request the engine's agents make — useful for
+logging, request tagging, or signing (AWS SigV4 for Bedrock, for instance).
+Return a replacement value to modify the payload or result, or `nil` to leave it
+untouched. A hook that raises is reported and skipped, so instrumentation can
+never break a run.
+
+```ruby
+config.llm_before_request = lambda do |payload, context|
+  Rails.logger.info("[llm] -> #{context[:provider]}/#{context[:model]}")
+  payload
+end
+
+config.llm_after_response = lambda do |result, context|
+  Rails.logger.info("[llm] <- #{context[:duration_ms]}ms")
+  result
+end
+```
+
+### Providers
+
+Alongside `openai`, `anthropic`, `google`, `azure` and `ollama`, rcrewai 0.8
+adds four, set as an agent's `llm_config` provider (or
+`config.default_llm_provider`):
+
+| Provider | Notes |
+|---|---|
+| `openai_compatible` | Any OpenAI-format endpoint (Groq, Together, Fireworks, vLLM, OpenRouter, a self-hosted gateway). Requires RCrewAI's `base_url`. |
+| `bedrock` | AWS Bedrock via the Converse API. Requires `aws_region`. |
+| `snowflake` | Snowflake Cortex inference. Requires `snowflake_account`. |
+| `openai_responses` | OpenAI's Responses API. Non-streaming only. |
+
+### Tracing accuracy
+
+rcrewai 0.8 stamps every event with the id of its enclosing run span, and the
+observation collector uses it to keep concurrent runs of the *same* agent apart.
+Previously both runs shared one span stack, so one run's tool call could nest
+under the other's iteration.
+
 ## rcrewai 0.7 capabilities
 
-This engine tracks [rcrewai](https://github.com/gkosmo/rcrewAI) `~> 0.7`. The
-following capabilities are configured through columns on the persisted models and
+These capabilities are configured through columns on the persisted models and
 forwarded to the core objects at build time. All are **off/absent by default**, so
 existing records are unaffected — set only what you need.
 
@@ -376,6 +464,8 @@ The gem provides these ActiveRecord models:
 - `RcrewAI::Rails::KnowledgeSource` - Knowledge (RAG) sources, owned by an agent or a crew
 - `RcrewAI::Rails::FlowState` - Persisted rcrewai Flow state (resume flows across restarts)
 - `RcrewAI::Rails::FlowRun` - Flow-run tracking (status, inputs, result, timing)
+- `RcrewAI::Rails::Span` / `SpanEvent` - The observation engine's trace tree
+- `RcrewAI::Rails::Checkpoint` - Persisted crew checkpoints (resume and lineage)
 
 ## API Endpoints
 

data/app/jobs/rcrewai/rails/crew_execution_job.rb

@@ -1,11 +1,18 @@
 module RcrewAI
   module Rails
     class CrewExecutionJob < ActiveJob::Base
+      # Raised when checkpointing is enabled but its table is missing, which
+      # means the 0.8 migration has not been run.
+      class CheckpointTableMissing < StandardError; end
+
       queue_as { RcrewAI::Rails.config.job_queue_name }
 
       retry_on StandardError, wait: :exponentially_longer, attempts: 3
+      # A missing table is a configuration problem: retrying cannot fix it and
+      # only delays the error the operator needs to see.
+      discard_on CheckpointTableMissing
 
-      def perform(crew, inputs = {}, batch_id: nil)
+      def perform(crew, inputs = {}, batch_id: nil, resume_run_id: nil)
         execution = crew.executions.create!(
           status: "pending",
           inputs: inputs,
@@ -22,7 +29,16 @@ module RcrewAI
           collector = collector_for(execution)
           collector&.start_crew_span(crew_name: crew.name)
 
-          result = rcrew.execute(stream: collector)
+          store = checkpoint_store_for(crew)
+          result = if resume_run_id
+                     execution.update!(parent_run_id: resume_run_id)
+                     rcrew.resume(resume_run_id, checkpoint: store, stream: collector, inputs: inputs)
+                   else
+                     rcrew.execute(stream: collector, inputs: inputs, checkpoint: store)
+                   end
+          # The gem assigns the run id during execute, so it can only be
+          # recorded once the run has opened.
+          execution.update!(run_id: rcrew.run_id) if rcrew.run_id
 
           # Close agent spans as successful before finish!, which treats
           # anything still open as an aborted run.
@@ -50,6 +66,36 @@ module RcrewAI
 
       private
 
+      # The checkpoint store for this run, or nil when checkpointing is off.
+      # A crew may opt in per-record; otherwise the engine default applies.
+      def checkpoint_store_for(crew)
+        enabled = if crew.respond_to?(:checkpoint_enabled) && !crew.checkpoint_enabled.nil?
+                    crew.checkpoint_enabled
+                  else
+                    RcrewAI::Rails.config.checkpoint_enabled
+                  end
+        return nil unless enabled
+
+        store = RcrewAI::Rails.config.checkpoint_store
+        return store if store
+
+        ensure_checkpoint_table!
+        ActiveRecordCheckpointStore.new
+      end
+
+      # Checkpointing was turned on but the 0.8 migration has not been run, so
+      # the default store has no table to write to. Failing here with the fix
+      # in the message beats an ActiveRecord::StatementInvalid raised partway
+      # through the run, once tasks have already been executed and paid for.
+      def ensure_checkpoint_table!
+        return if Checkpoint.table_exists?
+
+        raise CheckpointTableMissing,
+              "checkpointing is enabled but the #{Checkpoint.table_name} table does not exist. " \
+              "Run `rails rcrew_ai_rails:install:migrations && rails db:migrate` to add it, " \
+              "or set config.checkpoint_enabled = false."
+      end
+
       # Translates rcrewai events into the span tree. Returns nil when
       # observation is disabled so no sink is attached at all.
       def collector_for(execution)

data/app/models/rcrewai/rails/active_record_checkpoint_store.rb

@@ -0,0 +1,53 @@
+module RcrewAI
+  module Rails
+    # Persists rcrewai crew checkpoints to the DB. Implements the core
+    # checkpoint-store contract: save(id, record) / load(id) => record or nil /
+    # list => ids / delete(id). Pass an instance as +checkpoint:+ to
+    # RCrewAI::Crew#execute or #resume.
+    #
+    # Records are plain JSON-shaped hashes with string keys (the gem's own
+    # stores round-trip through JSON, and Crew reads them back with string
+    # keys), so they are stored verbatim rather than mapped onto columns.
+    # run_id/parent_run_id/crew_name are mirrored into columns for querying.
+    #
+    # Unlike the gem's FileStore, an id needs no path sanitizing here -- it is
+    # bound as a query parameter, never used to build a filesystem path.
+    class ActiveRecordCheckpointStore
+      def save(id, record)
+        checkpoint = Checkpoint.find_or_initialize_by(run_id: id.to_s)
+        checkpoint.data = record
+        checkpoint.parent_run_id = record["parent_run_id"] || record[:parent_run_id]
+        checkpoint.crew_name = record["crew"] || record[:crew]
+        checkpoint.checkpoint_updated_at = parse_time(record["updated_at"] || record[:updated_at])
+        checkpoint.save!
+        record
+      end
+
+      def load(id)
+        Checkpoint.find_by(run_id: id.to_s)&.data
+      end
+
+      def list
+        Checkpoint.order(:id).pluck(:run_id)
+      end
+
+      def delete(id)
+        Checkpoint.where(run_id: id.to_s).delete_all
+        nil
+      end
+
+      private
+
+      # The gem stamps an ISO8601 string. A malformed value must not take down
+      # the run -- the column is a convenience mirror, the authoritative copy
+      # lives in +data+.
+      def parse_time(value)
+        return nil if value.blank?
+
+        Time.zone ? Time.zone.parse(value.to_s) : Time.parse(value.to_s)
+      rescue ArgumentError, TypeError
+        nil
+      end
+    end
+  end
+end

data/app/models/rcrewai/rails/agent.rb

@@ -17,6 +17,10 @@ module RcrewAI
       scope :active, -> { where(active: true) }
 
       def to_rcrew_agent
+        Interceptors.apply_to_agent(build_rcrew_agent)
+      end
+
+      def build_rcrew_agent
         RCrewAI::Agent.new(
           name: name,
           role: role,

data/app/models/rcrewai/rails/checkpoint.rb

@@ -0,0 +1,37 @@
+module RcrewAI
+  module Rails
+    # One persisted rcrewai checkpoint run record.
+    #
+    # The gem writes a plain JSON-shaped hash per run (see
+    # RCrewAI::Checkpoint.record_for); +data+ holds it verbatim so a record
+    # written by any store implementation round-trips identically. run_id and
+    # parent_run_id are also mirrored into columns so lineage can be queried in
+    # SQL rather than by deserializing every row.
+    class Checkpoint < ApplicationRecord
+      self.table_name = "rcrewai_checkpoints"
+
+      serialize :data, coder: JSON
+
+      validates :run_id, presence: true, uniqueness: true
+
+      scope :roots, -> { where(parent_run_id: nil) }
+
+      def children
+        self.class.where(parent_run_id: run_id)
+      end
+
+      # The per-task entries of the stored record, keyed by task name.
+      def tasks
+        (data || {})["tasks"] || {}
+      end
+
+      def completed_task_names
+        tasks.select { |_name, entry| entry["status"] == "completed" }.keys
+      end
+
+      def failed_task_names
+        tasks.select { |_name, entry| entry["status"] == "failed" }.keys
+      end
+    end
+  end
+end

data/app/models/rcrewai/rails/crew.rb

@@ -61,6 +61,22 @@ module RcrewAI
         CrewExecutionJob.perform_now(self, inputs)
       end
 
+      # Re-runs a checkpointed execution, replaying tasks that already
+      # completed instead of paying for them again. Accepts either a run id or
+      # an Execution that recorded one.
+      def resume_async(run, inputs = {})
+        CrewExecutionJob.perform_later(self, inputs, resume_run_id: run_id_for(run))
+      end
+
+      def resume_sync(run, inputs = {})
+        CrewExecutionJob.perform_now(self, inputs, resume_run_id: run_id_for(run))
+      end
+
+      # Executions of this crew that recorded a checkpoint run id, newest first.
+      def resumable_executions
+        executions.where.not(run_id: nil).order(created_at: :desc)
+      end
+
       def execute_batch_async(inputs_list)
         batch_id = SecureRandom.uuid
         normalize_batch_inputs(inputs_list).each do |inputs|
@@ -97,6 +113,15 @@ module RcrewAI
 
       private
 
+      # Accepts an Execution or a bare run id, so callers can pass whichever
+      # they have without unwrapping it themselves.
+      def run_id_for(run)
+        id = run.respond_to?(:run_id) ? run.run_id : run
+        raise ArgumentError, "no checkpoint run id to resume from" if id.blank?
+
+        id
+      end
+
       # Wraps a single inputs hash into a one-element array; leaves an array of
       # hashes as-is. Avoids Array()'s hash-destructuring (Array({a:1}) => [[:a,1]]).
       def normalize_batch_inputs(inputs_list)

data/db/migrate/012_create_rcrewai_checkpoints.rb

@@ -0,0 +1,22 @@
+class CreateRcrewAICheckpoints < ActiveRecord::Migration[7.0]
+  def change
+    create_table :rcrewai_checkpoints do |t|
+      t.string :run_id, null: false
+      t.string :parent_run_id
+      t.string :crew_name
+      t.text :data, null: false
+      t.datetime :checkpoint_updated_at
+
+      t.timestamps
+    end
+
+    add_index :rcrewai_checkpoints, :run_id, unique: true
+    add_index :rcrewai_checkpoints, :parent_run_id
+
+    add_column :rcrewai_crews, :checkpoint_enabled, :boolean
+
+    add_column :rcrewai_executions, :run_id, :string
+    add_column :rcrewai_executions, :parent_run_id, :string
+    add_index :rcrewai_executions, :run_id
+  end
+end

data/lib/generators/rcrewai/rails/install/templates/create_rcrewai_tables.rb

@@ -16,6 +16,7 @@ class CreateRcrewAITables < ActiveRecord::Migration[7.0]
       t.string :after_kickoff_class
       t.string :after_kickoff_method
       t.text :config
+      t.boolean :checkpoint_enabled
       t.boolean :active, default: true
 
       t.timestamps
@@ -112,6 +113,8 @@ class CreateRcrewAITables < ActiveRecord::Migration[7.0]
       t.integer :total_tokens
       t.integer :span_count, default: 0, null: false
       t.integer :error_count, default: 0, null: false
+      t.string :run_id
+      t.string :parent_run_id
 
       t.timestamps
     end
@@ -119,6 +122,7 @@ class CreateRcrewAITables < ActiveRecord::Migration[7.0]
     add_index :rcrewai_executions, :status
     add_index :rcrewai_executions, :created_at
     add_index :rcrewai_executions, :batch_id
+    add_index :rcrewai_executions, :run_id
 
     create_table :rcrewai_execution_logs do |t|
       t.references :execution, null: false, foreign_key: { to_table: :rcrewai_executions }
@@ -204,6 +208,19 @@ class CreateRcrewAITables < ActiveRecord::Migration[7.0]
     add_index :rcrewai_spans, :status
     add_index :rcrewai_spans, %i[execution_id sequence]
 
+    create_table :rcrewai_checkpoints do |t|
+      t.string :run_id, null: false
+      t.string :parent_run_id
+      t.string :crew_name
+      t.text :data, null: false
+      t.datetime :checkpoint_updated_at
+
+      t.timestamps
+    end
+
+    add_index :rcrewai_checkpoints, :run_id, unique: true
+    add_index :rcrewai_checkpoints, :parent_run_id
+
     create_table :rcrewai_span_events do |t|
       t.references :span, null: false, foreign_key: { to_table: :rcrewai_spans }
       t.string :level, null: false, default: "info"

data/lib/generators/rcrewai/rails/install/templates/rcrewai.rb

@@ -16,7 +16,13 @@ RcrewAI::Rails.configure do |config|
   config.persistence_backend = :active_record
 
   # Default LLM provider
-  # Options: "openai", "anthropic", "cohere", "groq", etc.
+  # Options: "openai", "anthropic", "google", "azure", "ollama", and (rcrewai
+  # 0.8+) "openai_compatible", "bedrock", "snowflake", "openai_responses".
+  #   openai_compatible - any OpenAI-format endpoint (Groq, Together,
+  #                       Fireworks, vLLM, OpenRouter); needs RCrewAI's
+  #                       base_url set.
+  #   bedrock           - AWS Bedrock Converse API; needs aws_region.
+  #   snowflake         - Snowflake Cortex; needs snowflake_account.
   config.default_llm_provider = ENV.fetch("RCREWAI_LLM_PROVIDER", "openai")
 
   # Default LLM model
@@ -67,4 +73,32 @@ RcrewAI.configure do |config|
   # Configure other RcrewAI settings
   # config.default_model = "gpt-4"
   # config.temperature = 0.7
-end
+
+  # --- Checkpointing (rcrewai 0.8+) -----------------------------------------
+  # Records durable per-task state during a crew run so an interrupted run can
+  # be resumed instead of re-executing (and re-paying for) completed tasks.
+  # Off by default; a crew record can also opt in individually via its
+  # checkpoint_enabled column.
+  # config.checkpoint_enabled = true
+
+  # Where checkpoints are stored. Defaults to the bundled ActiveRecord store
+  # (the rcrewai_checkpoints table). Any object responding to
+  # save/load/list/delete works.
+  # config.checkpoint_store = RcrewAI::Rails::ActiveRecordCheckpointStore.new
+
+  # --- LLM interceptors (rcrewai 0.8+) --------------------------------------
+  # Hooks run around every LLM request the engine's agents make. Each receives
+  # (payload, context) / (result, context); return a replacement to modify it,
+  # or nil to leave it untouched. A hook that raises is reported and skipped,
+  # so instrumentation can never break a run.
+  #
+  # config.llm_before_request = lambda do |payload, context|
+  #   Rails.logger.info("[llm] -> #{context[:provider]}/#{context[:model]}")
+  #   payload
+  # end
+  #
+  # config.llm_after_response = lambda do |result, context|
+  #   Rails.logger.info("[llm] <- #{context[:duration_ms]}ms")
+  #   result
+  # end
+end

data/lib/rcrewai/rails/agent_builder.rb

@@ -76,6 +76,10 @@ module RcrewAI
       protected
 
       def build_agent
+        RcrewAI::Rails::Interceptors.apply_to_agent(new_rcrew_agent)
+      end
+
+      def new_rcrew_agent
         RCrewAI::Agent.new(
           name: @attributes[:name] || default_agent_name,
           role: @attributes[:role] || self.class.agent_role,

data/lib/rcrewai/rails/configuration.rb

@@ -7,7 +7,9 @@ module RcrewAI
                     :default_memory_embedder, :default_memory_store,
                     :observation_enabled, :observation_capture_prompts,
                     :observation_prompt_max_bytes, :observation_flush_mode,
-                    :observation_flush_every, :observation_retention_days
+                    :observation_flush_every, :observation_retention_days,
+                    :checkpoint_enabled, :checkpoint_store,
+                    :llm_before_request, :llm_after_response
 
       def initialize
         @job_queue_name = "default"
@@ -28,6 +30,16 @@ module RcrewAI
         @observation_flush_mode = :batched # :batched | :immediate
         @observation_flush_every = 25
         @observation_retention_days = 30
+        # Checkpointing (rcrewai 0.8+). Off by default: it writes a row per
+        # task settlement, which an app should opt into rather than inherit.
+        @checkpoint_enabled = false
+        # Defaults to ActiveRecordCheckpointStore when checkpointing is on.
+        # Set to any object responding to save/load/list/delete to override.
+        @checkpoint_store = nil
+        # LLM interceptor hooks (rcrewai 0.8+). Each is a callable, or an
+        # array of callables, applied to every client the engine builds.
+        @llm_before_request = nil
+        @llm_after_response = nil
       end
     end
   end

data/lib/rcrewai/rails/interceptors.rb

@@ -0,0 +1,52 @@
+# frozen_string_literal: true
+
+module RcrewAI
+  module Rails
+    # Applies the configured LLM interceptor hooks (rcrewai 0.8+) to a client.
+    #
+    # The gem forwards +before_request:+/+after_response:+ only through
+    # LLMClient.for_provider. Agents build their client via LLMClient.resolve,
+    # which does not, so hooks configured on the engine would never reach a
+    # per-agent client. Registering them on the built client instead covers
+    # every path uniformly.
+    module Interceptors
+      module_function
+
+      # Registers the configured hooks on +client+ and returns it.
+      #
+      # A client the host supplied ready-made (anything not speaking the hook
+      # API, e.g. a bare double or a custom object responding only to #chat)
+      # is returned untouched rather than raising -- the gem accepts any
+      # object responding to #chat as an llm, and instrumentation must never
+      # be the reason a run fails.
+      def apply(client, config = RcrewAI::Rails.config)
+        return client unless client
+
+        Array(config.llm_before_request).each do |hook|
+          client.before_request(hook) if client.respond_to?(:before_request)
+        end
+
+        Array(config.llm_after_response).each do |hook|
+          client.after_response(hook) if client.respond_to?(:after_response)
+        end
+
+        client
+      end
+
+      # True when any interceptor is configured, so callers can skip the work
+      # entirely in the common case where none are.
+      def configured?(config = RcrewAI::Rails.config)
+        Array(config.llm_before_request).any? || Array(config.llm_after_response).any?
+      end
+
+      # Registers the hooks on an already-built agent's client.
+      def apply_to_agent(agent, config = RcrewAI::Rails.config)
+        return agent unless configured?(config)
+        return agent unless agent.respond_to?(:llm_client)
+
+        apply(agent.llm_client, config)
+        agent
+      end
+    end
+  end
+end

data/lib/rcrewai/rails/observation/collector.rb

@@ -106,11 +106,12 @@ module RcrewAI
         end
 
         def on_iteration_start(event)
+          run = SpanStack.run_id_for(event)
           id = open_span(
             kind: "llm_call", name: "iteration #{event.iteration_index}",
             parent_span_id: agent_span_for(event.agent), agent: event.agent
           )
-          @stack.push(agent: event.agent, key: :iteration, id: id)
+          @stack.push(agent: event.agent, key: :iteration, id: id, run_id: run)
         end
 
         # Returns the agent span that events from +agent+ belong under,
@@ -126,7 +127,7 @@ module RcrewAI
         end
 
         def on_iteration_end(event)
-          id = @stack.pop(agent: event.agent, key: :iteration)
+          id = @stack.pop(agent: event.agent, key: :iteration, run_id: SpanStack.run_id_for(event))
           return unless id
 
           merge_attributes(id, "finish_reason" => event.finish_reason.to_s)
@@ -136,7 +137,8 @@ module RcrewAI
         def on_tool_start(event)
           id = open_span(
             kind: "tool_call", name: event.tool.to_s,
-            parent_span_id: @stack.current(agent: event.agent), agent: event.agent,
+            parent_span_id: @stack.current(agent: event.agent, run_id: SpanStack.run_id_for(event)),
+            agent: event.agent,
             attributes: { "args" => event.args }
           )
           @stack.register_call(call_id: event.call_id, span_id: id)
@@ -160,7 +162,7 @@ module RcrewAI
         end
 
         def on_usage(event)
-          id = @stack.current(agent: event.agent)
+          id = @stack.current(agent: event.agent, run_id: SpanStack.run_id_for(event))
           return unless id
 
           @writer.update_span(id,
@@ -176,16 +178,16 @@ module RcrewAI
         def on_text_delta(event)
           return if config.observation_capture_prompts == :none
 
-          @text_buffers[SpanStack.key_for(event.agent)] << event.text.to_s
+          @text_buffers[SpanStack.key_for(event.agent, SpanStack.run_id_for(event))] << event.text.to_s
         end
 
         # Prefers the event's own text, falling back to the accumulated
         # deltas when the provider sends TextDone without a payload.
         def on_text_done(event)
-          buffered = @text_buffers.delete(SpanStack.key_for(event.agent))
+          buffered = @text_buffers.delete(SpanStack.key_for(event.agent, SpanStack.run_id_for(event)))
           return if config.observation_capture_prompts == :none
 
-          id = @stack.current(agent: event.agent)
+          id = @stack.current(agent: event.agent, run_id: SpanStack.run_id_for(event))
           return unless id
 
           text = event.text.to_s
@@ -196,14 +198,14 @@ module RcrewAI
         def on_thinking(event)
           return if config.observation_capture_prompts == :none
 
-          id = @stack.current(agent: event.agent)
+          id = @stack.current(agent: event.agent, run_id: SpanStack.run_id_for(event))
           return unless id
 
           merge_attributes(id, "thinking" => truncate(event.text.to_s))
         end
 
         def on_error(event)
-          id = @stack.current(agent: event.agent)
+          id = @stack.current(agent: event.agent, run_id: SpanStack.run_id_for(event))
           return unless id
 
           merge_attributes(id, "error" => event.error.to_s)

data/lib/rcrewai/rails/observation/span_stack.rb

@@ -23,17 +23,34 @@ module RcrewAI
 
         # Normalizes an agent key. Blank/nil agents share a single reserved
         # bucket that cannot collide with a real agent name.
-        def self.key_for(agent)
+        def self.key_for(agent, run_id = nil)
           key = agent.to_s
-          key.empty? ? UNTAGGED : key
+          key = UNTAGGED if key.empty?
+          # rcrewai 0.8+ stamps every event with the id of the enclosing run
+          # span. Scoping the stack by it keeps two concurrent runs of the
+          # *same* agent apart -- keyed on name alone they share one stack, so
+          # one run's tool call nests under the other's iteration. Events from
+          # older streams (and the engine's own crew/agent spans) carry no run
+          # id and keep the previous name-only key.
+          run = run_id.to_s
+          run.empty? ? key : "#{key}\u0000#{run}"
+        end
+
+        # The run-span id an event belongs to, or nil for events that predate
+        # the 0.8 event hierarchy or are emitted outside a runner span.
+        def self.run_id_for(event)
+          return nil unless event.respond_to?(:parent_id)
+
+          id = event.parent_id
+          id.nil? || id.to_s.empty? ? nil : id
         end
 
         def next_sequence
           @mutex.synchronize { @sequence += 1 }
         end
 
-        def push(agent:, key:, id:)
-          @mutex.synchronize { @stacks[self.class.key_for(agent)] << { key: key, id: id } }
+        def push(agent:, key:, id:, run_id: nil)
+          @mutex.synchronize { @stacks[self.class.key_for(agent, run_id)] << { key: key, id: id } }
           id
         end
 
@@ -41,9 +58,9 @@ module RcrewAI
         #
         # Reads use +fetch+ rather than +[]+: the default block auto-vivifies
         # on read, so querying unknown agents would retain a key forever.
-        def pop(agent:, key:)
+        def pop(agent:, key:, run_id: nil)
           @mutex.synchronize do
-            stack = @stacks.fetch(self.class.key_for(agent), nil)
+            stack = @stacks.fetch(self.class.key_for(agent, run_id), nil)
             next nil if stack.nil?
 
             index = stack.rindex { |frame| frame[:key] == key }
@@ -53,8 +70,8 @@ module RcrewAI
           end
         end
 
-        def current(agent:)
-          @mutex.synchronize { @stacks.fetch(self.class.key_for(agent), nil)&.last&.fetch(:id) }
+        def current(agent:, run_id: nil)
+          @mutex.synchronize { @stacks.fetch(self.class.key_for(agent, run_id), nil)&.last&.fetch(:id) }
         end
 
         def register_call(call_id:, span_id:)

data/lib/rcrewai/rails/version.rb

@@ -1,6 +1,6 @@
 module RcrewAI
   module Rails
-    VERSION = "0.7.1"
+    VERSION = "0.8.1"
     Version = VERSION
   end
 end

data/lib/rcrewai/rails.rb

@@ -8,6 +8,7 @@ require "stimulus-rails"
 require_relative "rails/version"
 require_relative "rails/engine"
 require_relative "rails/configuration"
+require_relative "rails/interceptors"
 require_relative "rails/crew_builder"
 require_relative "rails/agent_builder"
 require_relative "rails/observation/span_stack"

data/rcrewai-rails.gemspec

@@ -45,7 +45,7 @@ Gem::Specification.new do |spec|
   spec.require_paths = ["lib"]
 
   # Core dependency
-  spec.add_dependency "rcrewai", "~> 0.7.1"
+  spec.add_dependency "rcrewai", "~> 0.8.0"
   
   # Rails dependencies
   spec.add_dependency "rails", ">= 7.0.0"

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: rcrewai-rails
 version: !ruby/object:Gem::Version
-  version: 0.7.1
+  version: 0.8.1
 platform: ruby
 authors:
 - gkosmo
@@ -15,14 +15,14 @@ dependencies:
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: 0.7.1
+        version: 0.8.0
   type: :runtime
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: 0.7.1
+        version: 0.8.0
 - !ruby/object:Gem::Dependency
   name: rails
   requirement: !ruby/object:Gem::Requirement
@@ -210,9 +210,11 @@ files:
 - app/controllers/rcrewai/rails/tools_controller.rb
 - app/jobs/rcrewai/rails/crew_execution_job.rb
 - app/jobs/rcrewai/rails/task_execution_job.rb
+- app/models/rcrewai/rails/active_record_checkpoint_store.rb
 - app/models/rcrewai/rails/active_record_state_store.rb
 - app/models/rcrewai/rails/agent.rb
 - app/models/rcrewai/rails/application_record.rb
+- app/models/rcrewai/rails/checkpoint.rb
 - app/models/rcrewai/rails/crew.rb
 - app/models/rcrewai/rails/execution.rb
 - app/models/rcrewai/rails/execution_log.rb
@@ -259,6 +261,7 @@ files:
 - db/migrate/009_add_memory_config_to_agents_and_clean_crews.rb
 - db/migrate/010_create_rcrewai_spans.rb
 - db/migrate/011_add_observation_rollups_to_rcrewai_executions.rb
+- db/migrate/012_create_rcrewai_checkpoints.rb
 - docs/api.html
 - docs/capabilities.html
 - docs/examples.html
@@ -275,6 +278,7 @@ files:
 - lib/rcrewai/rails/configuration.rb
 - lib/rcrewai/rails/crew_builder.rb
 - lib/rcrewai/rails/engine.rb
+- lib/rcrewai/rails/interceptors.rb
 - lib/rcrewai/rails/observation/collector.rb
 - lib/rcrewai/rails/observation/pruner.rb
 - lib/rcrewai/rails/observation/rollup.rb