rcrewai 0.7.1 → 0.8.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: e0a4a20865a08157cf9148d63439eeb653570c39f4f6e850bf6cc9f8e963a437
-  data.tar.gz: 4abf734ac77a3bdb1c43887b077cd99e1aea4ff9e2f8ba08b5fcac72a27ac7b5
+  metadata.gz: cbd74067513b5593791b282baf20f18c8dd8f6cd9257b02f70423ee4cba3486d
+  data.tar.gz: 215cade06d04b032d254e792a2af9d36d7c00de073580dff31125d46e5de4b48
 SHA512:
-  metadata.gz: 01bd0f68ca18dcee76ccca334821bd1412695922b1a84fba092b7bf4686179401c581844b36094b9cf765415e8ce2652cfb7300b496d4c57c9b78dbcd6b7ac22
-  data.tar.gz: afdc22e50a5a61bc0e153c0e8a702e9e0aa465cbf268d06d71a82f372c626236a163ceab777f4eee5e8f6134740a8b54903fdb50cdebd38b6ae7b987d1394581
+  metadata.gz: 735222585596dc578801792d74a6f5435037c78352f10e80670b2e179e0cce11a6257b79624e8a1abd0a3aa6978d86ec852e02cbdd6dc22e00a1364eafbb1058
+  data.tar.gz: 3f5b7145864b603e292b9daced5ef1c39c2d3084847658265d2b67a58ef8e3575ba8383e9494e7a2bcfcd7d6de231daadaac43ae41245afea7ed2c4f817649b9

data/CHANGELOG.md

@@ -7,6 +7,53 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [0.8.1] - 2026-09-10
+
+Dependency cleanup. No API or behavior change.
+
+### Changed
+- Dropped three unused runtime dependencies: `anthropic`, `ruby-openai` and `faraday-multipart`. Every LLM client talks to Faraday directly and none of these gems was ever required, but they had been declared since `0.3.0`, so each install pulled them plus their transitive dependencies (`event_stream_parser`, `multipart-post`) — seven gems in total. No API change; the Anthropic and OpenAI clients are unaffected.
+
+## [0.8.0] - 2026-09-10
+
+Closes the feature-parity gap against CrewAI's `1.x` line. Adds **LLM message
+interceptors**, an **event hierarchy** with safe fan-out, **task-level
+checkpointing** with resume and lineage, and **four new providers** (AWS
+Bedrock, Snowflake Cortex, any OpenAI-compatible endpoint, and OpenAI's
+Responses API).
+
+Almost entirely additive. One behavior change — `Events.fan_out` now serializes
+delivery, so stream subscribers no longer need their own mutex; sinks that
+already lock remain correct. See **Changed** below.
+
+Also repairs `bin/rcrewai`, which had never worked in any published version.
+
+### Added
+
+#### Interceptors & observability
+- LLM message interceptors: `before_request` / `after_response` hooks on every provider client (`LLMClients::Base`), registered via block, callable, or the `before_request:` / `after_response:` constructor kwargs. A `before_request` hook receives `(payload, context)` and may return a replacement payload; an `after_response` hook receives `(result, context)` and may return a replacement result. Returning `nil` keeps the original, so a pure-observer hook needs no return value. `context` carries `:provider` and `:model`, and `after_response` adds `:duration_ms`. Hooks run in registration order, threading the value through. A hook that raises is reported to stderr and skipped — instrumentation never breaks a call. Wired on both the plain and streaming paths of all five providers.
+- Event hierarchy: every `Events::*` event now carries an auto-assigned `:id`, and `:parent_id` naming the enclosing span. `Events.with_parent(id) { ... }` opens a span for the current thread (nesting, restored on exit, and on raise); `Events.emit(sink, event)` stamps the enclosing parent before delivery. Both runners (`ToolRunner`, `LegacyReactRunner`) open a per-run span, so a subscriber can reassemble the flat stream into a tree — what tracing exporters need.
+
+#### Checkpointing
+- Checkpointing: `crew.execute(checkpoint: store)` records durable per-run state, and `crew.resume(run_id)` replays completed tasks instead of re-executing them. Granularity is task-level — a checkpoint is written after each task settles, so a crash loses at most the task in flight. Failed tasks are recorded as failed rather than omitted, so a resume retries them instead of treating them as never-attempted. Supported on the sequential, hierarchical, and consensual processes.
+- Checkpoint stores follow the existing `Flow::StateStore` shape (`save`/`load`/`list`/`delete`): `Checkpoint::MemoryStore` (volatile) and `Checkpoint::FileStore` (one JSON file per run). `FileStore` rejects run ids containing path separators or traversal segments, since ids arrive both from callers and from stored records.
+- Lineage: a resumed run gets its own run id linked to its parent via `parent_run_id`, leaving the original record intact. `Checkpoint.lineage(store, run_id)` walks the chain back to the root, truncating rather than raising if an ancestor has been pruned.
+- CLI: `rcrewai checkpoint list` / `info RUN_ID` / `delete RUN_ID` inspect saved checkpoints (`--dir`, default `.rcrewai/checkpoints`).
+
+#### Providers
+- New providers: `:openai_compatible` (any endpoint speaking the OpenAI Chat Completions format — Together, Groq, Fireworks, vLLM, LiteLLM, OpenRouter, a self-hosted gateway; requires `base_url`), `:bedrock` (AWS Bedrock via the Converse API, giving every Bedrock model one request shape; requires `aws_region`), and `:snowflake` (Snowflake Cortex inference; requires `snowflake_account`). New configuration attributes `aws_region` and `snowflake_account`, also read from `AWS_REGION`/`AWS_DEFAULT_REGION` and `SNOWFLAKE_ACCOUNT`.
+- `:openai_responses` — OpenAI's Responses API alongside the existing Chat Completions client. Messages go under `input` with the system prompt lifted to `instructions`, `max_tokens` becomes `max_output_tokens`, tools are sent flat rather than nested under `function`, and the `output` array is parsed back into the canonical `content` / `tool_calls` shape. An `incomplete` response capped by `max_output_tokens` is reported as `finish_reason: :length`. Non-streaming only — Responses streams a distinct set of semantic events that this client does not model.
+- `LLMClient::PROVIDERS` — provider resolution is now a table rather than a `case`, so registering a client is a one-line change.
+
+
+### Changed
+- **Behavior change:** subscribers passed to `crew.execute(stream:)` no longer need their own mutex. Existing sinks that lock are unaffected.
+
+### Fixed
+- `Events.fan_out` now serializes delivery: sinks are invoked under a mutex, so a sink shared by concurrently executing agents is never entered from two threads at once. Previously it called sinks inline on the emitting thread with no serialization, which under `async: true` meant every subscriber had to do its own locking or race — the 0.7.1 notes documented this as a caveat, but for any aggregating subscriber it was a live defect. The lock is reentrant, so a sink that emits back through the same fan-out does not deadlock. Sinks that already lock internally remain correct.
+- `LLMClient.for_provider` silently dropped interceptor hooks: it constructed each client with only the config, so `before_request` / `after_response` passed through the normal resolution path never reached the client. It now forwards them.
+- `bin/rcrewai` never worked. `lib/rcrewai/cli.rb` defined `def run`, which Thor reserves, so the class raised `"run" is a Thor reserved word` on load; the file was consequently never required from `lib/rcrewai.rb`, which hid the breakage from the test suite while `bin/rcrewai` — shipped as a gem executable since the initial commit — crashed for every installed user. The command is now defined as `run_crew` and mapped back to `run`, so the user-facing invocation (`rcrewai run --crew NAME`) is unchanged, and the CLI is required and covered by specs.
+
 ## [0.7.1] - 2026-08-13
 
 ### Fixed
@@ -14,7 +61,7 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 - Tasks retained a reference to the caller's sink after `execute` returned, keeping request-scoped subscribers reachable for the lifetime of the task object. The sink is now cleared in an `ensure`.
 
 ### Note
-- `Events.fan_out` invokes sinks inline on the emitting thread with no serialization, so under `async: true` a sink may be called concurrently from multiple worker threads. Subscribers must do their own locking.
+- `Events.fan_out` invokes sinks inline on the emitting thread with no serialization, so under `async: true` a sink may be called concurrently from multiple worker threads. Subscribers must do their own locking. **Superseded in `0.8.0`:** fan-out now serializes delivery.
 
 ## [0.7.0] - 2026-07-07
 

data/ROADMAP.md

@@ -5,85 +5,154 @@ This roadmap tracks feature parity between **RCrewAI** (Ruby) and the upstream
 
 ## Current status
 
-- **RCrewAI:** `0.3.0` (2026-05-12)
-- **Upstream crewai:** `1.15.x` (mid-2026)
+- **RCrewAI:** `0.7.1` released; `0.8.0`, `0.9.0` and `0.9.x` merged to `main`, unreleased
+- **Upstream crewai:** `1.15.21`
 
 RCrewAI is a faithful port of CrewAI's **"Crews"** mental model (Agents / Tasks /
-Crew, sequential + hierarchical processes, tools, memory, human-in-the-loop). As
-of `0.3.0` the LLM plumbing is modern: native function calling across all five
-providers, a tool-schema DSL, typed streaming events, MCP client, and per-model
-pricing.
+Crew, sequential + hierarchical + consensual processes, tools, memory,
+human-in-the-loop), and it carries CrewAI's second pillar (**Flows**) plus
+**Knowledge (RAG)**, **guardrails**, **structured output**, **planning**, and
+**training/testing**. In one area — cognitive memory (semantic recall, SQLite
+persistence, four memory types) — the gem went past what was originally ported.
+
+**Status: one milestone remaining.** An earlier revision of this file declared
+parity "complete" against a matrix that only covered CrewAI through roughly
+`1.0` (October 2025) while quoting `1.15.x` in its header; everything upstream
+added across `1.1`–`1.15` was unmeasured. That delta was re-derived, and three
+of the four scheduled milestones have since shipped. Only native async (1.0.0)
+is outstanding, and it is blocked on an open decision — see below.
 
-Since CrewAI's `1.0`, the framework grew a second pillar (**Flows**) plus
-**Knowledge (RAG)**, **Guardrails**, **structured output**, **Planning**, and
-**Training/Testing**. RCrewAI now implements all of these — see the matrix below.
+## Parity matrix
 
-**Status: complete.** All milestone issues (#5–#12) shipped in v0.4.0, and all
-backlog items (#15–#20) shipped in v0.5.0. There is no outstanding roadmap work.
+### Shipped
+
+| Concept | crewai | RCrewAI |
+|---|---|---|
+| Agents / Tasks / Crew | ✅ | ✅ |
+| Sequential / hierarchical process | ✅ | ✅ |
+| Consensual process (propose → vote → pick) | ✅ | ✅ (0.7.0) |
+| Native function calling + tool DSL | ✅ | ✅ (0.3.0) |
+| Streaming events | ✅ | ✅ (0.3.0) |
+| MCP client | ✅ | ✅ (0.3.0) |
+| Per-model pricing / cost | ✅ | ✅ (0.3.0) |
+| Per-agent LLM override | ✅ | ✅ (0.4.0) |
+| Structured output (schema) | ✅ | ✅ (0.4.0) |
+| Task guardrails | ✅ | ✅ (0.4.0) |
+| `output_file` / markdown | ✅ | ✅ (0.4.0) |
+| Knowledge / RAG | ✅ | ✅ (0.4.0) |
+| Planning | ✅ | ✅ (0.4.0) |
+| Flows (`start`/`listen`/`router`) | ✅ | ✅ (0.4.0) |
+| Flow state + persistence | ✅ | ✅ (0.4.0) |
+| Training / testing | ✅ | ✅ (0.4.0) |
+| Lifecycle hooks, batch kickoff, rate limiting | ✅ | ✅ (0.5.0) |
+| Reasoning, context window, multimodal | ✅ | ✅ (0.5.0) |
+| Cognitive memory (semantic, persistent, typed) | ✅ | ✅ (0.6.x) |
+| LLM message interceptor hooks | ✅ | ✅ (0.8.0) |
+| Event hierarchy + safe fan-out | ✅ | ✅ (0.8.0) |
+| Checkpointing (save / resume / lineage) | ✅ | ✅ (0.9.0) |
+| Newer providers (Bedrock, Cortex, OpenAI-compatible) | ✅ | ✅ (0.9.x) |
+| OpenAI Responses API | ✅ | ✅ (0.9.x) |
+
+### Gaps
+
+| Concept | crewai | RCrewAI | Plan |
+|---|---|---|---|
+| Native async (LLM + tool level) | ✅ (1.4–1.6) | ⚠️ partial | 1.0.0 |
+| OTel export for the event hierarchy | ✅ (1.10+) | ❌ | 1.0.x |
+| Streaming for Bedrock / Responses | ✅ | ❌ | 1.0.x |
+| Bedrock SigV4 signing | ✅ | ❌ (hook workaround) | 1.0.x |
+| A2A (agent-to-agent) | ✅ (1.7–1.9) | ❌ | deferred |
 
-## Parity matrix
+### Out of scope
+
+Three upstream areas are deliberately **not** targets. They are CrewAI's
+commercial platform surface rather than framework capability, and porting them
+means tracking someone else's product roadmap with no Ruby-side consumer:
+
+- **JSON-first project format** (`agents/*.jsonc`, `crew.jsonc`, declarative and
+  conversational flows in the CLI TUI) — a config format whose shape is set by
+  upstream's tooling.
+- **Skills Repository** — a hosted registry plus authentication.
+- **Policies** — CrewAI enforces these at the infrastructure level via the NVIDIA
+  OpenShell runtime. Reimplementing them in-process would provide the appearance
+  of enforcement without the property that makes enforcement worth having.
+
+If a Ruby-side need for any of these appears, revisit — but not speculatively.
+
+## Milestones
+
+### 0.8.0 — Interceptors & observability ✅ shipped (#39)
+
+`before_request` / `after_response` hooks on `LLMClients::Base`, inherited by
+every provider and wired on both the plain and streaming paths. Events gained
+`:id` / `:parent_id` with `Events.with_parent` spans opened per agent run.
+
+`Events.fan_out` now serializes delivery under a reentrant mutex, fixing a live
+race: it previously called sinks inline on the emitting thread, so under
+`async: true` an aggregating subscriber was entered from several pool workers at
+once. **Behavior change:** subscribers no longer need their own mutex.
+
+### 0.9.0 — Checkpointing ✅ shipped (#42)
+
+Task-level `crew.execute(checkpoint: store)` / `crew.resume(run_id)` across the
+sequential, hierarchical and consensual processes, with `MemoryStore` and
+`FileStore` following the `Flow::StateStore` shape. Resumed runs link to their
+parent via `parent_run_id`; `Checkpoint.lineage` walks the chain to the root.
+CLI: `rcrewai checkpoint list|info|delete`.
+
+Also repaired `bin/rcrewai`, which had never worked: `lib/rcrewai/cli.rb`
+defined `def run`, a Thor reserved word, so the class raised on load and the
+file was never required — hiding the breakage from the suite while the shipped
+gem executable crashed for every installed user.
+
+### 0.9.x — Providers & Responses API ✅ shipped (#41)
+
+`:openai_compatible`, `:bedrock` (Converse v4), `:snowflake` (Cortex) and
+`:openai_responses`. Provider resolution moved to a `LLMClient::PROVIDERS`
+table, which also fixed `for_provider` silently dropping interceptor hooks.
+
+Two deliberate limitations carried forward to 1.0.x: Bedrock does not implement
+SigV4 (a hard `aws-sigv4` dependency for one provider is not worth it; sign via
+a `before_request` hook), and Bedrock/Responses are non-streaming only.
+
+### 1.0.0 — Native async
+
+The largest item, and the one with a genuine architecture decision attached.
+Today `AsyncExecutor` fans tasks out across a `Concurrent::ThreadPoolExecutor` in
+dependency-ordered phases; concurrency stops at the task boundary. CrewAI went
+async *through* the LLM and tool calls (1.4–1.6), covering flows, crews, tasks,
+knowledge, and memory.
+
+Ruby has no direct port of that. Two candidate models:
+
+1. **Fibers** via the `async` gem — closer to upstream's shape, new runtime
+   dependency, and every provider client's HTTP layer has to cooperate.
+2. **Stay on threads** and make the client layer non-blocking — smaller
+   conceptual change, keeps `concurrent-ruby`, less faithful to upstream.
+
+**This decision is open and blocks the milestone.** It touches all five LLM
+clients either way. The 8.2k lines of `lib/` are backed by 4.9k lines of spec,
+which is what makes a refactor at this depth tractable.
+
+### Deferred — A2A
+
+Agent-to-agent task execution utilities and server configuration (upstream
+1.7–1.9). Real framework capability, but it presumes a deployment topology that
+no current RCrewAI user has asked for. Revisit once the items above land.
+
+## Sequencing
 
-| Concept | crewai | RCrewAI 0.3.0 | Target |
+| Milestone | Contents | Risk | Status |
 |---|---|---|---|
-| Agents / Tasks / Crew | ✅ | ✅ | — |
-| Sequential / hierarchical process | ✅ | ✅ | — |
-| Native function calling + tool DSL | ✅ | ✅ (0.3.0) | — |
-| Streaming events | ✅ | ✅ (0.3.0) | — |
-| MCP client | ✅ | ✅ (0.3.0) | — |
-| Per-model pricing / cost | ✅ | ✅ (0.3.0) | — |
-| Per-agent LLM override | ✅ | ✅ (#5) | ✅ done |
-| Structured output (schema) | ✅ | ✅ (#6) | ✅ done |
-| Task guardrails | ✅ | ✅ (#7) | ✅ done |
-| `output_file` / markdown | ✅ | ✅ (#8) | ✅ done |
-| Knowledge / RAG | ✅ | ✅ (#9) | ✅ done |
-| Planning | ✅ | ✅ (#10) | ✅ done |
-| Flows (`start`/`listen`/`router`) | ✅ | ✅ (#11) | ✅ done |
-| Flow state + persistence | ✅ | ✅ (#11) | ✅ done |
-| Training / Testing | ✅ | ✅ (#12) | ✅ done |
-| Reasoning, rate-limiting, batch kickoff, hooks, context window, multimodal | ✅ | ✅ (#15–#20) | ✅ done |
-
-## Milestones (highest leverage first)
-
-### 0.3.1 — Per-agent LLM override
-Let `Agent.new(llm:)` accept a provider/model, instead of only the global
-`RCrewAI.configure`. Unblocks mixed-model crews (cheap model for workers, strong
-model for the manager).
-
-### 0.4.0 — Structured output & guardrails
-Builds directly on the 0.3.0 tool-schema/JSON-schema plumbing.
-- `Task.new(output_schema:)` → validated, coerced structured result.
-- `Task.new(guardrail:)` → proc/object that validates & transforms output, with
-  bounded retries (`guardrail_max_retries`).
-- `output_file:` + `markdown:` output formatting.
-
-### 0.5.0 — Knowledge (RAG) & Planning
-- Knowledge sources: string, `.txt`, PDF (have `pdf-reader`), CSV, JSON, URL
-  (have `nokogiri`). Embeddings client + a pluggable vector store (start with an
-  in-memory / SQLite cosine store; no hard Chroma dependency).
-- Attach at agent **and** crew level.
-- `Crew.new(planning: true)` → a planner pass that drafts a step plan before
-  execution.
-
-### 0.6.0 — Flows
-The flagship. A Ruby DSL mirroring CrewAI Flows:
-- `start`, `listen`, `router` decorators/class-methods.
-- `and_` / `or_` trigger combinators.
-- Structured flow **state** (a plain struct/`Data` or dry-struct) with a UUID.
-- `@persist`-equivalent state persistence across restarts.
-- `human_feedback` pause/resume point.
-
-### 0.7.0 — Training & Testing
-- `crew.train(n_iterations:, filename:)` capturing human feedback.
-- `crew.test(n_iterations:, model:)` scoring runs.
-
-### Backlog — ✅ all complete
-
-Formerly polish items with no set version; all shipped in the `[Unreleased]`
-changes (see CHANGELOG):
-
-- [#15](https://github.com/gkosmo/rcrewAI/issues/15) — `before_kickoff` / `after_kickoff` lifecycle hooks ✅
-- [#16](https://github.com/gkosmo/rcrewAI/issues/16) — `kickoff_for_each` batch execution ✅
-- [#17](https://github.com/gkosmo/rcrewAI/issues/17) — `max_rpm` rate limiting ✅
-- [#18](https://github.com/gkosmo/rcrewAI/issues/18) — per-agent reasoning (`reasoning:`, `max_reasoning_attempts:`) ✅
-- [#19](https://github.com/gkosmo/rcrewAI/issues/19) — `respect_context_window` history trimming ✅
-- [#20](https://github.com/gkosmo/rcrewAI/issues/20) — multimodal agents (image/file inputs) ✅
+| 0.8.0 | Interceptors + observability | Low | ✅ merged (#39) |
+| 0.9.0 | Checkpointing | Moderate | ✅ merged (#42) |
+| 0.9.x | Providers, Responses API | Low | ✅ merged (#41) |
+| 1.0.0 | Native async | High — decision open | ⏳ blocked |
+
+The three shipped milestones are on `main` and unreleased; they want a version
+bump and a release before or alongside 1.0.0 work.
+
+**1.0.0 is blocked on the fibers-vs-threads decision above.** It is the only
+remaining scheduled work, and the largest single change in this roadmap: it
+touches all nine provider clients and the executor. Nothing else should start
+before that call is made.

data/lib/rcrewai/checkpoint/cli.rb

@@ -0,0 +1,98 @@
+# frozen_string_literal: true
+
+require 'thor'
+
+module RCrewAI
+  module Checkpoint
+    # Inspects checkpoints written by a crew run.
+    class CLI < Thor
+      DEFAULT_DIR = '.rcrewai/checkpoints'
+
+      class_option :dir, type: :string, default: DEFAULT_DIR,
+                         desc: 'Directory holding checkpoint files'
+
+      desc 'list', 'List saved checkpoint runs'
+      def list
+        ids = store.list
+        if ids.empty?
+          puts 'No checkpoints found.'
+          return
+        end
+
+        puts "Checkpoints in #{options[:dir]}:"
+        ids.sort.each do |id|
+          record = store.load(id)
+          next unless record
+
+          puts "  #{id}  #{summarize(record)}"
+        end
+      end
+
+      desc 'info RUN_ID', 'Show a checkpoint in detail'
+      def info(run_id)
+        record = store.load(run_id)
+        unless record
+          puts "No checkpoint for run id #{run_id}."
+          return
+        end
+
+        puts "run:     #{record['run_id']}"
+        puts "crew:    #{record['crew']}"
+        puts "updated: #{record['updated_at']}"
+        print_lineage(run_id, record)
+        print_tasks(record)
+      end
+
+      desc 'delete RUN_ID', 'Delete a checkpoint'
+      def delete(run_id)
+        unless store.load(run_id)
+          puts "No checkpoint for run id #{run_id}."
+          return
+        end
+
+        store.delete(run_id)
+        puts "Deleted checkpoint #{run_id}."
+      end
+
+      # Thor exits non-zero on an unhandled error rather than swallowing it.
+      def self.exit_on_failure?
+        true
+      end
+
+      private
+
+      def store
+        @store ||= FileStore.new(options[:dir])
+      end
+
+      def summarize(record)
+        tasks = record['tasks'] || {}
+        done = tasks.count { |_n, t| t['status'] == 'completed' }
+        "#{record['crew']}  #{done}/#{tasks.size} tasks"
+      end
+
+      def print_lineage(run_id, record)
+        return unless record['parent_run_id']
+
+        chain = Checkpoint.lineage(store, run_id)
+        puts "lineage: #{chain.join(' -> ')}"
+      end
+
+      def print_tasks(record)
+        tasks = record['tasks'] || {}
+        return puts 'tasks:   (none)' if tasks.empty?
+
+        puts 'tasks:'
+        tasks.each do |name, entry|
+          secs = entry['execution_time']
+          timing = secs ? format(' (%.2fs)', secs) : ''
+          puts "  #{status_mark(entry['status'])} #{name}  #{entry['status']}#{timing}"
+        end
+      end
+
+      def status_mark(status)
+        status == 'completed' ? '+' : '!'
+      end
+    end
+  end
+end

data/lib/rcrewai/checkpoint.rb

@@ -0,0 +1,145 @@
+# frozen_string_literal: true
+
+require 'json'
+require 'fileutils'
+require 'securerandom'
+require 'time'
+
+module RCrewAI
+  # Durable execution state for a crew run.
+  #
+  # A checkpoint records, per task, whether it completed and what it produced.
+  # Resuming a run replays those results instead of re-executing the tasks --
+  # the expensive part of a crew run is the LLM calls, so skipping a completed
+  # task is the whole point.
+  #
+  # Granularity is task-level: a checkpoint is written after each task settles,
+  # so a crash loses at most the task in flight. Stores are pluggable; anything
+  # responding to #save(id, record), #load(id), #list and #delete works.
+  module Checkpoint
+    class CheckpointError < RCrewAI::Error; end
+
+    # Volatile; for tests and single-process runs.
+    class MemoryStore
+      def initialize
+        @data = {}
+      end
+
+      def save(id, record)
+        @data[id] = deep_dup(record)
+      end
+
+      def load(id)
+        record = @data[id]
+        record && deep_dup(record)
+      end
+
+      def list
+        @data.keys
+      end
+
+      def delete(id)
+        @data.delete(id)
+        nil
+      end
+
+      private
+
+      # Records are plain JSON-shaped data, so a round-trip is a sufficient
+      # deep copy and keeps a caller's later mutation from reaching the store.
+      def deep_dup(record)
+        JSON.parse(JSON.generate(record))
+      end
+    end
+
+    # One JSON file per run under a directory.
+    class FileStore
+      def initialize(dir)
+        @dir = dir
+        FileUtils.mkdir_p(@dir)
+      end
+
+      def save(id, record)
+        File.write(path_for(id), JSON.pretty_generate(record))
+      end
+
+      def load(id)
+        path = path_for(id)
+        return nil unless File.exist?(path)
+
+        JSON.parse(File.read(path))
+      end
+
+      def list
+        Dir.glob(File.join(@dir, '*.json')).map { |p| File.basename(p, '.json') }
+      end
+
+      def delete(id)
+        path = path_for(id)
+        File.delete(path) if File.exist?(path)
+        nil
+      end
+
+      private
+
+      # Run ids reach here from callers and from stored records, so a path
+      # separator or traversal segment must not be able to steer the write
+      # outside the checkpoint directory.
+      def path_for(id)
+        s = id.to_s
+        raise CheckpointError, "invalid run id: #{id.inspect}" if s.empty? ||
+                                                                  s.include?('/') ||
+                                                                  s.include?('\\') ||
+                                                                  s == '.' || s == '..'
+
+        File.join(@dir, "#{s}.json")
+      end
+    end
+
+    module_function
+
+    def new_run_id
+      SecureRandom.uuid
+    end
+
+    # Builds the record persisted for a run.
+    def record_for(run_id:, crew_name:, tasks:, parent_run_id: nil)
+      {
+        'run_id' => run_id,
+        'parent_run_id' => parent_run_id,
+        'crew' => crew_name,
+        'updated_at' => Time.now.utc.iso8601,
+        'tasks' => tasks
+      }
+    end
+
+    # Serializes one task's settled state.
+    def task_entry(task, status)
+      {
+        'status' => status.to_s,
+        'result' => task.result,
+        'execution_time' => task.execution_time
+      }
+    end
+
+    # Walks parent_run_id links from +run_id+ back to the root, returning the
+    # chain oldest-first. Stops on a missing record rather than raising, so a
+    # pruned ancestor truncates the chain instead of breaking it.
+    def lineage(store, run_id)
+      chain = []
+      seen = {}
+      current = run_id
+
+      while current && !seen[current]
+        seen[current] = true
+        record = store.load(current)
+        break unless record
+
+        chain.unshift(current)
+        current = record['parent_run_id']
+      end
+
+      chain
+    end
+  end
+end

data/lib/rcrewai/cli.rb

@@ -8,9 +8,13 @@ module RCrewAI
       Crew.create(crew_name)
     end
 
+    # Thor reserves #run, so the command is defined under another name and
+    # mapped back. Without this the whole class raises on load, which is why
+    # cli.rb went unrequired -- and why bin/rcrewai never worked.
     desc 'run', 'Run the AI crew'
     option :crew, type: :string, required: true, desc: 'Name of the crew to run'
-    def run
+    map 'run' => :run_crew
+    def run_crew
       crew_name = options[:crew]
       puts "Running crew: #{crew_name}"
       crew = Crew.load(crew_name)
@@ -31,9 +35,16 @@ module RCrewAI
     desc 'task SUBCOMMAND ...ARGS', 'Manage tasks'
     subcommand 'task', Task::CLI
 
+    desc 'checkpoint SUBCOMMAND ...ARGS', 'Inspect run checkpoints'
+    subcommand 'checkpoint', Checkpoint::CLI
+
     desc 'version', 'Show version'
     def version
       puts "rcrewai version #{RCrewAI::VERSION}"
     end
+
+    def self.exit_on_failure?
+      true
+    end
   end
 end

data/lib/rcrewai/configuration.rb

@@ -6,6 +6,7 @@ module RCrewAI
                   :openai_api_key, :anthropic_api_key, :google_api_key, :azure_api_key,
                   :openai_model, :anthropic_model, :google_model, :azure_model,
                   :base_url, :api_version, :deployment_name,
+                  :aws_region, :snowflake_account,
                   :pricing, :ollama_native_tools, :log_level
 
     def initialize
@@ -21,6 +22,9 @@ module RCrewAI
       @google_model = 'gemini-pro'
       @azure_model = 'gpt-4'
 
+      @aws_region = nil
+      @snowflake_account = nil
+
       @pricing = nil
       @ollama_native_tools = nil
       @log_level = :info
@@ -101,6 +105,9 @@ module RCrewAI
       @google_api_key = ENV['GOOGLE_API_KEY'] || ENV['GEMINI_API_KEY']
       @azure_api_key = ENV['AZURE_OPENAI_API_KEY']
 
+      @aws_region ||= ENV.fetch('AWS_REGION', nil) || ENV.fetch('AWS_DEFAULT_REGION', nil)
+      @snowflake_account ||= ENV.fetch('SNOWFLAKE_ACCOUNT', nil)
+
       @api_key = ENV['LLM_API_KEY'] if @api_key.nil?
       @base_url = ENV['LLM_BASE_URL'] if @base_url.nil?
       @api_version = ENV['AZURE_API_VERSION'] if @api_version.nil?