rcrewai-rails 0.7.0 → 0.8.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: e21a3a1057f9221cca3d280f2307b219d15a636995284c781404c4ed3d283fa6
-  data.tar.gz: 9b715b0cc17839eb5fb23f578905d962c4b6450d0aae2b8b1f494d549497a8b3
+  metadata.gz: 7987750789244c90f421923541a2132e3aab1f6891f6b706ed42544ea4ae2507
+  data.tar.gz: 99fe0af08b0ad8f1a4c5bccf93edd2285e32f5966f6c3d93c2f152c239074ffe
 SHA512:
-  metadata.gz: 1be59f83c847e48c36b0ac61527ca9dedc61b903763be6145d6dd26354575a74d2dee3fc807a804e6f847660347c8368a28d70f33df6cb57d75d2b952b98657f
-  data.tar.gz: 0f37c9c304ef0264afeb363f07ca1b23c72045d9686869fe9325e336a79f30bc1930d08f97470a6235ad7d4dc8d1e5ebab4c78eb3de9d9ae1129ea42cb48dca8
+  metadata.gz: edafeb7cbf6461861bee821981911a5262d0dff09ec034cbb4cb2de123fe5a31a135e25685b7ba756931c665a908cf41e369b474aa33bb7a4beab7b99fcc17a3
+  data.tar.gz: f2edb449ac6b178e62392e809b677c103456e1ec6141e35b3dcac52b15c3254c5af0abe7e3165ba2b5f95137b87fcbcae1cf9dfc2cb0082afe3da795af470c3b

data/CHANGELOG.md

@@ -7,6 +7,86 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [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
+- **`rails db:migrate` raised `NameError` on 0.7.0.** The engine registers an
+  `RcrewAI` acronym inflection (Zeitwerk needs it to resolve
+  `rcrewai/rails/span.rb` to `RcrewAI::Rails::Span`), so Rails camelizes
+  `create_rcrewai_tables` to `CreateRcrewAITables` — but the shipped migrations
+  declared `CreateRcrewaiTables`. Rails resolves a migration's class from its
+  filename, so following the documented install verbatim failed. Nine migrations
+  in `db/migrate` and the install template were affected; all now declare the
+  name Rails derives. Thanks to the user who reported this from a real install.
+
+  **If you already installed 0.7.0** and renamed the class by hand, no action is
+  needed — your migration works. Otherwise, delete the copied migration, upgrade,
+  and re-run the install (or `rcrew_ai_rails:install:migrations`).
+
 ## [0.7.0] - 2026-08-13
 
 ### Added
@@ -36,6 +116,16 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 - `rcrewai >= 0.7.1` for agent-level tracing. On earlier 0.7.x versions traces
   contain only crew-level spans.
 
+### Upgrading
+- **Existing installs need two new migrations.** Do not run the install
+  generator (it creates every table and will fail on duplicates). Instead run
+  `rails rcrew_ai_rails:install:migrations && rails db:migrate` to copy only
+  what is missing: `010_create_rcrewai_spans` (the trace tree) and
+  `011_add_observation_rollups_to_rcrewai_executions` (cost/token totals). Both
+  are additive — nothing existing is altered or dropped. Observation is enabled
+  by default once the tables exist; set `config.observation_enabled = false` to
+  upgrade without turning tracing on.
+
 ## [0.6.1] - 2026-07-07
 
 ### Fixed
@@ -152,7 +242,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.0...HEAD
+[Unreleased]: https://github.com/gkosmo/rcrewai-rails/compare/v0.8.0...HEAD
+[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
 [0.6.0]: https://github.com/gkosmo/rcrewai-rails/compare/v0.5.1...v0.6.0

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
 
@@ -86,6 +87,46 @@ This will:
 - Add an initializer file for configuration
 - Mount the engine routes in `config/routes.rb`
 
+### Upgrading an existing install
+
+The install generator above is for **new** installs — it creates every table, so
+running it against an app that already has the RcrewAI tables will fail on
+duplicates.
+
+If you are already running rcrewai-rails, pull in only the migrations you are
+missing using the standard Rails engine task:
+
+```bash
+$ rails rcrew_ai_rails:install:migrations
+$ 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.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 |
+
+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
+`config/initializers/rcrewai.rb` before migrating.
+
+If your schema was created by hand (the install generator did not copy a
+migration before 0.7.0, so this is likely), review the copied migrations before
+running `db:migrate` and delete any whose tables you already have.
+
 ### Manual Routes Setup
 
 If you need to mount the routes manually, add this to your `config/routes.rb`:
@@ -235,10 +276,86 @@ 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`.
+
+### 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.
 
@@ -342,6 +459,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

@@ -5,7 +5,7 @@ module RcrewAI
 
       retry_on StandardError, wait: :exponentially_longer, attempts: 3
 
-      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 +22,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 +59,19 @@ 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
+
+        RcrewAI::Rails.config.checkpoint_store || ActiveRecordCheckpointStore.new
+      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/002_add_config_to_rcrewai_agents.rb

@@ -1,4 +1,4 @@
-class AddConfigToRcrewaiAgents < ActiveRecord::Migration[7.0]
+class AddConfigToRcrewAIAgents < ActiveRecord::Migration[7.0]
   def change
     # max_rpm and llm_config already exist on rcrewai_agents from the
     # original create table; only the 0.5.0 additions are new.

data/db/migrate/003_add_output_processing_to_rcrewai_tasks.rb

@@ -1,4 +1,4 @@
-class AddOutputProcessingToRcrewaiTasks < ActiveRecord::Migration[7.0]
+class AddOutputProcessingToRcrewAITasks < ActiveRecord::Migration[7.0]
   def change
     # output_file already exists on rcrewai_tasks from the original create
     # table; only the new 0.4/0.5 output-processing options are added here.

data/db/migrate/004_add_lifecycle_to_rcrewai_crews.rb

@@ -1,4 +1,4 @@
-class AddLifecycleToRcrewaiCrews < ActiveRecord::Migration[7.0]
+class AddLifecycleToRcrewAICrews < ActiveRecord::Migration[7.0]
   def change
     add_column :rcrewai_crews, :planning, :boolean, default: false, null: false
     add_column :rcrewai_crews, :planning_llm, :string

data/db/migrate/005_add_batch_id_to_rcrewai_executions.rb

@@ -1,4 +1,4 @@
-class AddBatchIdToRcrewaiExecutions < ActiveRecord::Migration[7.0]
+class AddBatchIdToRcrewAIExecutions < ActiveRecord::Migration[7.0]
   def change
     add_column :rcrewai_executions, :batch_id, :string
     add_index :rcrewai_executions, :batch_id

data/db/migrate/006_create_rcrewai_knowledge_sources.rb

@@ -1,4 +1,4 @@
-class CreateRcrewaiKnowledgeSources < ActiveRecord::Migration[7.0]
+class CreateRcrewAIKnowledgeSources < ActiveRecord::Migration[7.0]
   def change
     create_table :rcrewai_knowledge_sources do |t|
       t.references :owner, polymorphic: true, null: false

data/db/migrate/007_create_rcrewai_flows.rb

@@ -1,4 +1,4 @@
-class CreateRcrewaiFlows < ActiveRecord::Migration[7.0]
+class CreateRcrewAIFlows < ActiveRecord::Migration[7.0]
   def change
     create_table :rcrewai_flow_states do |t|
       t.string :state_id, null: false

data/db/migrate/008_add_consensus_agents_to_rcrewai_crews.rb

@@ -1,4 +1,4 @@
-class AddConsensusAgentsToRcrewaiCrews < ActiveRecord::Migration[7.0]
+class AddConsensusAgentsToRcrewAICrews < ActiveRecord::Migration[7.0]
   def change
     add_column :rcrewai_crews, :consensus_agents, :integer
   end

data/db/migrate/010_create_rcrewai_spans.rb

@@ -1,4 +1,4 @@
-class CreateRcrewaiSpans < ActiveRecord::Migration[7.0]
+class CreateRcrewAISpans < ActiveRecord::Migration[7.0]
   def change
     create_table :rcrewai_spans do |t|
       t.references :execution, null: false, foreign_key: { to_table: :rcrewai_executions }

data/db/migrate/011_add_observation_rollups_to_rcrewai_executions.rb

@@ -1,4 +1,4 @@
-class AddObservationRollupsToRcrewaiExecutions < ActiveRecord::Migration[7.0]
+class AddObservationRollupsToRcrewAIExecutions < ActiveRecord::Migration[7.0]
   def change
     add_column :rcrewai_executions, :total_cost_usd, :decimal, precision: 12, scale: 6
     add_column :rcrewai_executions, :total_tokens, :integer

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

@@ -1,4 +1,4 @@
-class CreateRcrewaiTables < ActiveRecord::Migration[7.0]
+class CreateRcrewAITables < ActiveRecord::Migration[7.0]
   def change
     create_table :rcrewai_crews do |t|
       t.string :name, null: false
@@ -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.0"
+    VERSION = "0.8.0"
     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.0
+  version: 0.8.0
 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