nexo_ai 0.9.0 → 0.10.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 6c12fe51de0643c44b5ede5f140d45a2c2c50b15b8f357ad0e40132bcd40034c
-  data.tar.gz: 6c98b8a0adab754ba7ea290ca2227df8f464f9a71407ad4956b6a985b5a40346
+  metadata.gz: 8815820e94035d1d5c68defa4e862111c95572852098b735e885eaf98b6a3407
+  data.tar.gz: 57ca3d98c0d1acd6877276e9322715a7e003928b2da258866b1e7ccabcf33b29
 SHA512:
-  metadata.gz: 221c754bcd1d4d46bf8550c5411c95e194840b5c9de42dbf66a4035a7b5d95bdccb2fb8c5a5ade8eccf88e238e763cb59b9e97d2b40d7d92fc9aee273dfe8376
-  data.tar.gz: 337b96d65dcbfcb2d879ed2e6dc62867d1a27a768f0693e007db8a0f562de0a6e5d3d129f0092d804eb531cbac0b375b7b97731016e1551cd9d1c164bae94e05
+  metadata.gz: 8ad1a55220bcddd2ea1e2d06ea2bc2c680ae4f2a52c1cd8f24e0942f66ad38e38c6b1dc992fcc766b720400083bb07b500feaae9285fbb671e203bfa3f46e0f4
+  data.tar.gz: cea3ce8167dae3b4e44a5d87c84e42f04a333c7cd7e5aae8ad236133b821ba10fd3688e63851035d2c1b494b9c533807fa29bfbfd1c3439ed8c8ce6473fe1e52

data/CHANGELOG.md

@@ -1,5 +1,22 @@
 ## [Unreleased]
 
+## [0.10.0] - 2026-08-20
+
+Durable workflows without a database.
+
+### Added
+
+- `Nexo.config.run_store` — set a store instance and it wins over the automatic
+  choice (ActiveRecord under Rails, in-memory otherwise).
+- `Nexo::RunStore::Disk` — a file-backed store, one JSON document per run under a
+  directory, written atomically (temp file + rename). This is what makes `checkpoint`,
+  `suspend!`/`resume` and a run's recorded artifacts available to a host with no
+  database: all of them read state back from the store, and the in-memory one dies
+  with the process. `Disk::Run` subclasses `Memory::Run`, so the run shape and every
+  read helper are shared and host code behaves identically on either store. `#all`
+  lists the directory newest-first. `claim_for_resume!` re-reads from disk so a stale
+  copy cannot win a claim; it is atomic within a process, not across machines.
+
 ## [0.9.0] - 2026-08-20
 
 Skills and sandboxes learn to talk about the environment, and an agent's output finally

data/docs/workflows.md

@@ -82,6 +82,34 @@ ActiveRecord when it is available and the in-memory store otherwise. The schema
 uses portable `json` columns (SQLite and PostgreSQL alike) and a UUID string
 primary key.
 
+### Durable without a database — `RunStore::Disk`
+
+The in-memory store dies with the process, and **everything durable reads state
+back from the store**: `checkpoint`, `suspend!`/`resume`, and a run's recorded
+artifacts. So for a CLI or a script — no Rails, no database, but a process that
+ends — point the store at a directory:
+
+```ruby
+Nexo.config.run_store = Nexo::RunStore::Disk.new(dir: "~/.local/state/myapp/runs")
+```
+
+One JSON document per run, rewritten whenever the run changes, written to a temp
+file and renamed so a crash cannot leave a truncated document behind. The run shape
+and every read helper are Memory's — `Disk::Run` subclasses it — so host code
+written against one store behaves identically on the other. `#all` lists the
+directory newest-first, which is what a host wants for *"what did the last run
+produce?"*.
+
+A configured store wins over the automatic choice, including under Rails.
+
+**Scope, honestly.** Rewriting the whole document per change suits the run sizes this
+is meant for (a CLI's own history) and is wrong for a busy multi-worker queue — that
+is what the ActiveRecord backend is for. `claim_for_resume!` re-reads from disk, so a
+stale in-memory copy cannot win a claim, but it is atomic **within** a process only.
+Runs are never pruned: retention is the host's policy and `dir` is a plain directory
+it can manage. `Workflow.reconcile_interrupted!` sweeps the Memory and ActiveRecord
+stores only.
+
 ## Input staging and artifacts
 
 A run owns a **sandbox** — declared with the `sandbox` class macro (default

data/lib/nexo/configuration.rb

@@ -57,6 +57,14 @@ module Nexo
     # this only gates the opt-in Turbo mirror.
     attr_accessor :broadcast_events
 
+    # The run store Workflow persists runs through, default +nil+ → the automatic
+    # choice (ActiveRecord under Rails, in-memory otherwise). Set an instance to
+    # override, which is what a host outside Rails needs for anything durable:
+    # checkpoint/suspend/resume all read state back from the store, and the
+    # in-memory one dies with the process. +Nexo::RunStore::Disk.new(dir:)+ is the
+    # shipped answer for a CLI or a script.
+    attr_accessor :run_store
+
     # The ActiveJob queue Workflow.run_later enqueues onto (Spec 11 R1), default
     # +nil+ → ActiveJob's default queue. Set to a symbol (e.g. +:nexo+) to route
     # workflow jobs to a dedicated queue.
@@ -74,6 +82,7 @@ module Nexo
       @buffer_workflow_events = false
       @session_chat_model = "Chat" # ruby_llm's own default acts_as_chat host
       @broadcast_events = false # safe default: opt in to the Turbo mirror
+      @run_store = nil # nil → the automatic choice (ActiveRecord under Rails, else Memory)
       @job_queue = nil # nil → ActiveJob's default queue
     end
 

data/lib/nexo/run_store.rb

@@ -1,5 +1,8 @@
 # frozen_string_literal: true
 
+require "json"
+require "fileutils"
+
 module Nexo
   # Storage seam for Workflow runs. Two interchangeable backends expose an
   # identical create/find interface and return run objects responding to the
@@ -11,11 +14,19 @@ module Nexo
   # +push_event(event)+, +save_events!+, +push_artifact(artifact)+,
   # +save_artifacts!+, and +save_state!+ (Spec 13).
   module RunStore
-    # Selects a backend: the ActiveRecord store when both ::ActiveRecord::Base
-    # and Nexo::WorkflowRun are defined (the Rails path), otherwise the in-memory
-    # store. With no Rails loaded the AR check short-circuits, so the plain-Ruby
-    # path never references ActiveRecord.
+    # Selects a backend: +Nexo.config.run_store+ when a host set one, else the
+    # ActiveRecord store when both ::ActiveRecord::Base and Nexo::WorkflowRun are
+    # defined (the Rails path), otherwise the in-memory store. With no Rails loaded
+    # the AR check short-circuits, so the plain-Ruby path never references
+    # ActiveRecord.
+    #
+    # The configured store wins over both, which is the only way a non-Rails host
+    # gets durability: everything that survives a process — checkpoint, suspend,
+    # resume, a run's recorded artifacts — is read back from the store, and Memory
+    # dies with the process. See Disk.
     def self.default
+      return Nexo.config.run_store if Nexo.config.run_store
+
       if defined?(::ActiveRecord::Base) && defined?(Nexo::WorkflowRun)
         ActiveRecord.new
       else
@@ -158,5 +169,137 @@ module Nexo
           .update_all(status: "running") == 1
       end
     end
+
+    # File-backed backend for a host with no database: one JSON document per run
+    # under +dir+, rewritten whenever the run changes. This is what makes durability
+    # available outside Rails — checkpoint, suspend/resume and a run's recorded
+    # artifacts all read state back from the store, and Memory dies with the process.
+    #
+    #   Nexo.config.run_store = Nexo::RunStore::Disk.new(dir: "~/.local/state/myapp/runs")
+    #
+    # The Run is Memory's, subclassed: the shape and every read helper are shared, so
+    # a host written against one store behaves identically on the other. Only the
+    # +save_*+ hooks differ — they write the document. +push_event+/+push_artifact+
+    # deliberately do NOT, because Workflow always calls the matching +save_*+ right
+    # after, and persisting twice would double the writes for nothing.
+    #
+    # Scope, honestly: rewriting the whole document per change is fine for the run
+    # sizes this is meant for (a CLI's own history) and wrong for a busy multi-worker
+    # queue — that is what the ActiveRecord backend is for. +claim_for_resume!+ is
+    # atomic within a process but NOT across processes; two machines resuming the
+    # same run concurrently is out of scope. Runs are never pruned here: retention is
+    # the host's policy, and +dir+ is a plain directory it can manage.
+    class Disk
+      # A Memory::Run that writes itself to +path+ whenever Workflow saves it.
+      class Run < Memory::Run
+        # Absolute path of this run's JSON document. Assigned by the store.
+        attr_accessor :path
+
+        # The three save hooks Workflow calls after mutating a run. Memory's are
+        # no-ops because the Struct already holds everything; here they are the
+        # whole point.
+        def save_events! = persist!
+
+        # Writes the run after Workflow appended an artifact.
+        def save_artifacts! = persist!
+
+        # Writes the run after Workflow stored checkpoint/suspend state.
+        def save_state! = persist!
+
+        # Assigns attributes (Memory's behaviour) and writes the run.
+        def update!(attrs)
+          super
+          persist!
+        end
+
+        # Writes the document atomically — a temp file in the same directory, then
+        # a rename — so a crash mid-write cannot leave a truncated run behind.
+        def persist!
+          return if path.nil?
+
+          tmp = "#{path}.#{Process.pid}.tmp"
+          ::File.write(tmp, JSON.generate(to_h.except(:path)))
+          ::File.rename(tmp, path)
+        end
+      end
+
+      # Serializes writes within the process, mirroring Memory's store-wide lock.
+      MUTEX = Mutex.new
+
+      # +dir+ is created on demand; +~+ is expanded.
+      def initialize(dir:)
+        @dir = ::File.expand_path(dir)
+      end
+
+      # The directory runs are written to.
+      attr_reader :dir
+
+      # Builds a fresh +"pending"+ Run, writes it, and returns it.
+      def create(workflow_class:, payload:)
+        run = Run.new(
+          id: Nexo.generate_run_id, workflow_class: workflow_class, status: "pending",
+          payload: payload, result: nil, error: nil, events: [], artifacts: [], state: {}
+        )
+        ::FileUtils.mkdir_p(@dir)
+        run.path = path_for(run.id)
+        run.persist!
+        run
+      end
+
+      # Reads a run back by id. A miss raises KeyError, matching Memory.
+      def find(id)
+        path = path_for(id)
+        raise KeyError, "run not found: #{id}" unless ::File.exist?(path)
+
+        hydrate(JSON.parse(::File.read(path)), path)
+      end
+
+      # Every run in the directory, newest-written first. Not part of the store
+      # contract Workflow calls — it is here because a host with a run directory
+      # inevitably wants to list it ("what did the last run produce?").
+      def all
+        return [] unless ::File.directory?(@dir)
+
+        Dir.glob(::File.join(@dir, "*.json"))
+          .sort_by { |p| -::File.mtime(p).to_f }
+          .filter_map do |p|
+            hydrate(JSON.parse(::File.read(p)), p)
+          rescue JSON::ParserError, SystemCallError
+            # A half-written or hand-edited document must not break the listing.
+            nil
+          end
+      end
+
+      # Atomically claims a +"suspended"+ run for resume, re-reading from disk so a
+      # stale in-memory copy cannot win. Within one process only — see the class
+      # note.
+      def claim_for_resume!(run)
+        MUTEX.synchronize do
+          current = find(run.id)
+          return false unless current.status == "suspended"
+
+          run.status = "running"
+          run.path ||= path_for(run.id)
+          run.persist!
+          true
+        end
+      end
+
+      private
+
+      def path_for(id) = ::File.join(@dir, "#{id}.json")
+
+      # Rebuilds a Run from its document. Missing members read as nil/empty rather
+      # than raising, so a document written by an older version still loads.
+      def hydrate(data, path)
+        run = Run.new(
+          id: data["id"], workflow_class: data["workflow_class"], status: data["status"],
+          payload: data["payload"], result: data["result"], error: data["error"],
+          events: data["events"] || [], artifacts: data["artifacts"] || [], state: data["state"] || {}
+        )
+        run.path = path
+        run
+      end
+    end
   end
 end

data/lib/nexo/version.rb

@@ -2,5 +2,5 @@
 
 module Nexo
   # The gem version (also used as +spec.version+ in the gemspec).
-  VERSION = "0.9.0"
+  VERSION = "0.10.0"
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: nexo_ai
 version: !ruby/object:Gem::Version
-  version: 0.9.0
+  version: 0.10.0
 platform: ruby
 authors:
 - Mario Alberto Chávez