durable_agent 0.1.0

data/MIT-LICENSE

@@ -0,0 +1,20 @@
+Copyright Mikkel Malmberg
+
+Permission is hereby granted, free of charge, to any person obtaining
+a copy of this software and associated documentation files (the
+"Software"), to deal in the Software without restriction, including
+without limitation the rights to use, copy, modify, merge, publish,
+distribute, sublicense, and/or sell copies of the Software, and to
+permit persons to whom the Software is furnished to do so, subject to
+the following conditions:
+
+The above copyright notice and this permission notice shall be
+included in all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
+EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
+MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND
+NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE
+LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION
+OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION
+WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

data/README.md

@@ -0,0 +1,23 @@
+# durable_agent
+
+Crash-safe, resumable AI agent conversations for Rails. The gem ships [pi-durable](https://github.com/earendil-works/pi-durable)
+as a bundled sidecar process that keeps its state in your app's own database, Postgres or SQLite, which Rails reads
+with Active Record. Tools are Ruby classes. Pages update over Turbo.
+
+```sh
+bundle add durable_agent
+bin/rails g durable_agent:install   # migration, initializer, mount, Procfile.dev line
+bin/rails db:migrate
+bin/dev                             # web, sidecar
+```
+
+```ruby
+conversation = DurableAgent.start
+conversation.say("Summarize the invoice", request_id: message.id)
+conversation.transcript
+```
+
+Early. The contract is in [DESIGN.md](DESIGN.md), the guide in [docs/guide.md](docs/guide.md), the example app in
+[test/dummy](test/dummy). Needs Ruby 3.3+, Rails 8+, Node 22.19+.
+
+MIT.

data/Rakefile

@@ -0,0 +1,46 @@
+require "bundler/setup"
+
+APP_RAKEFILE = File.expand_path("test/dummy/Rakefile", __dir__)
+load "rails/tasks/engine.rake"
+
+require "bundler/gem_tasks"
+
+# The gem ships the bundled sidecar (sidecar/dist/sidecar.js), which is not checked in. `rake build` (and
+# `rake release`, which runs it) bundles it first so it is never missing or stale; the gemspec refuses a bare
+# `gem build` without it.
+namespace :sidecar do
+  desc "Bundle the sidecar into sidecar/dist/sidecar.js"
+  task :build do
+    sh "npm ci --prefix sidecar"
+    sh "npm run build --prefix sidecar"
+    abort "sidecar/dist/sidecar.js was not built" unless File.exist?(File.expand_path("sidecar/dist/sidecar.js", __dir__))
+  end
+end
+task build: "sidecar:build"
+
+# The dummy app's pages need its Tailwind build (gitignored), so the test tasks build it first.
+namespace :dummy do
+  desc "Build test/dummy's CSS"
+  task :css do
+    sh "cd test/dummy && bin/rails tailwindcss:build"
+  end
+end
+
+# The suite runs on either database; database.yml picks the adapter from DURABLE_AGENT_DB.
+desc "Run the tests on SQLite"
+task test: "dummy:css" do
+  sh({ "DURABLE_AGENT_DB" => "sqlite" }, "bin/rails test")
+end
+
+namespace :test do
+  desc "Run the tests on Postgres (durable_agent_test)"
+  task postgres: "dummy:css" do
+    sh({ "DURABLE_AGENT_DB" => "postgres", "RAILS_ENV" => "test" }, "bin/rails db:create")
+    sh({ "DURABLE_AGENT_DB" => "postgres" }, "bin/rails test")
+  end
+
+  desc "Run the tests on SQLite, then on Postgres"
+  task all: [ :test, :postgres ]
+end
+
+task default: :test

data/app/controllers/durable_agent/application_controller.rb

@@ -0,0 +1,15 @@
+module DurableAgent
+  # The engine renders no views: its only endpoints are the ones the sidecar calls.
+  class ApplicationController < ActionController::API
+    before_action :authenticate_sidecar
+
+    private
+      # `Authorization: Bearer <token>`, exactly: a bare token, another scheme or extra whitespace is refused.
+      def authenticate_sidecar
+        scheme, given = request.authorization.to_s.split(/ /, 2)
+        unless scheme == "Bearer" && ActiveSupport::SecurityUtils.secure_compare(given.to_s, DurableAgent.config.token)
+          render json: { error: "unauthorized" }, status: :unauthorized
+        end
+      end
+  end
+end

data/app/controllers/durable_agent/events_controller.rb

@@ -0,0 +1,28 @@
+module DurableAgent
+  # The sidecar posts the conversations and reports each commit touched, and the providers whose sign-in changed.
+  # Events are a hint: the state is already in the database, so ids that do not exist are skipped and a failing
+  # callback never fails the request.
+  class EventsController < ApplicationController
+    def create
+      Conversation.where(id: ids("conversations")).each { |conversation| notify(:on_change, conversation, id: conversation.id) }
+      Report.where(id: ids("reports")).each { |report| notify(:on_report, report, id: report.id) }
+      notify(:on_auth, providers, providers: providers) if providers.any?
+      head :no_content
+    end
+
+    private
+      def ids(key)
+        Array(params[key]).map(&:to_i)
+      end
+
+      def providers
+        @providers ||= Array(params[:auth]).map(&:to_s).compact_blank.uniq
+      end
+
+      def notify(callback, argument, **context)
+        DurableAgent.config.public_send(callback).call(argument)
+      rescue => error
+        Rails.error.report(error, context: { durable_agent: callback, **context })
+      end
+  end
+end

data/app/controllers/durable_agent/tools_controller.rb

@@ -0,0 +1,33 @@
+module DurableAgent
+  # The model sees a tool's error message, so only errors meant for it carry their message: bad arguments, a
+  # missing record, and DurableAgent::Tool::Error. Anything else is reported to Rails.error and reaches the model as
+  # its class name only, so a message holding SQL, paths or secrets stays in the app.
+  class ToolsController < ApplicationController
+    MODEL_FACING = [ ArgumentError, ActiveRecord::RecordNotFound, DurableAgent::Tool::Error ]
+
+    def index
+      render json: DurableAgent.config.tools.map(&:to_definition)
+    end
+
+    def create
+      if tool = DurableAgent.config.tool(params[:name])
+        Current.set(conversation_id: body["conversation_id"], call_id: body["call_id"]) do
+          render json: { result: tool.run(body["arguments"]) }
+        end
+      else
+        render json: { error: "unknown tool #{params[:name]}" }, status: :not_found
+      end
+    rescue *MODEL_FACING => error
+      render json: { error: error.message }, status: :unprocessable_content
+    rescue StandardError => error
+      Rails.error.report(error, context: { durable_agent: :tool, tool: params[:name], conversation_id: @body.to_h["conversation_id"] })
+      render json: { error: "#{error.class} while running #{params[:name]}" }, status: :unprocessable_content
+    end
+
+    private
+      # The raw JSON, not params: arguments are the model's object exactly as it produced it.
+      def body
+        @body ||= JSON.parse(request.raw_post.presence || "{}")
+      end
+  end
+end

data/app/models/concerns/durable_agent/harness_record.rb

@@ -0,0 +1,11 @@
+# Rows of pi-durable's own tables, which the sidecar's harness writes. Rails never changes them: a write here
+# would bypass the harness and corrupt its state.
+module DurableAgent::HarnessRecord
+  extend ActiveSupport::Concern
+
+  included do
+    self.table_name = "durable_agent_#{model_name.element.pluralize}"
+  end
+
+  def readonly? = true
+end

data/app/models/durable_agent/application_record.rb

@@ -0,0 +1,5 @@
+module DurableAgent
+  class ApplicationRecord < DurableAgent.config.parent_record_class.to_s.constantize
+    self.abstract_class = true
+  end
+end

data/app/models/durable_agent/connection.rb

@@ -0,0 +1,66 @@
+# Provider sign-in as Rails sees it. Pure sidecar calls: the sidecar stores the tokens and keys in
+# durable_agent_credentials, encrypted with a key derived from DURABLE_AGENT_TOKEN, and Rails never reads or
+# decrypts them.
+#
+#   connection = DurableAgent::Connection.new("openai")
+#   login = connection.start_login       # => {"id" => ..., "status" => "awaiting_browser", "url" => "https://..."}
+#   connection.complete_login(login["id"], pasted_url)
+#
+# With an account the connection is that account's own credential, which the conversations started with
+# `DurableAgent.start(account:)` run on:
+#
+#   DurableAgent::Connection.new("openai", account: user.id).set_api_key(params[:key])
+class DurableAgent::Connection
+  PROVIDERS = { "openai" => "ChatGPT", "anthropic" => "Claude" }.freeze
+
+  attr_reader :provider, :account, :error
+
+  def self.all(account: nil)
+    statuses = DurableAgent.auth(account: account)
+    PROVIDERS.keys.map { |provider| new(provider, account: account, status: statuses[provider]) }
+  rescue DurableAgent::Error => error
+    PROVIDERS.keys.map { |provider| new(provider, account: account, status: nil, error: error.message) }
+  end
+
+  def initialize(provider, account: nil, status: :unknown, error: nil)
+    @provider = provider.to_s
+    raise ArgumentError, "unknown provider #{provider}" unless PROVIDERS.key?(@provider)
+    @account = DurableAgent::Account.normalize(account)
+    @status, @error = status, error
+  end
+
+  def status
+    @status = DurableAgent.auth(account: account)[provider] if @status == :unknown
+    @status
+  rescue DurableAgent::Error => error
+    @error = error.message
+    @status = nil
+  end
+
+  def name = PROVIDERS.fetch(provider)
+  def scoped_provider = DurableAgent::Account.scoped(provider, account)
+  def stream_name = DurableAgent.auth_stream(account)
+
+  def connected? = status.present?
+  def subscription? = status&.dig("type") == "oauth"
+  def api_key? = status&.dig("type") == "api_key"
+  def source = status&.dig("source")
+  def unreachable? = status.nil? && error.present?
+
+  # Stores the key on the sidecar, encrypted, and returns the new status.
+  def set_api_key(key)
+    raise ArgumentError, "API key is blank" if key.blank?
+    @error = nil
+    @status = client.set_api_key(provider, key, **scope)
+  end
+
+  def start_login = client.start_login(provider, **scope)
+  def login(id) = client.login(provider, id)
+  def complete_login(id, url) = client.complete_login(provider, id, url)
+  def cancel_login(id) = client.cancel_login(provider, id)
+  def disconnect = client.logout(provider, **scope)
+
+  private
+    def client = DurableAgent.client
+    def scope = DurableAgent.account_scope(account)
+end

data/app/models/durable_agent/conversation.rb

@@ -0,0 +1,107 @@
+# A pi-durable conversation, read straight from the harness tables. The sidecar writes the rows; Rails reads them
+# and sends commands through DurableAgent.client. Your own record (a Chat, a Ticket) holds the conversation id.
+class DurableAgent::Conversation < DurableAgent::ApplicationRecord
+  include DurableAgent::HarnessRecord
+
+  attribute :record, :json
+
+  # Own rows only: a forked conversation's inherited entries are not followed.
+  has_many :entries, dependent: nil
+  has_many :submissions, dependent: nil
+  has_many :tasks, dependent: nil
+  has_many :reports, dependent: nil
+  has_many :documents, -> { current.where(scope_kind: "conversation") }, foreign_key: :owner_id, dependent: nil
+  belongs_to :owner, class_name: "DurableAgent::Conversation", foreign_key: :owner_conversation_id, optional: true
+
+  # The sidecar creates the root conversation (id 1) at boot, before any app asks for one.
+  ROOT_ID = 1
+
+  scope :top_level, -> { where(owner_conversation_id: nil).where.not(id: ROOT_ID) }
+
+  def self.root = find_by(id: ROOT_ID)
+
+  def root? = id == ROOT_ID
+
+  # The sidecar fills created_at from the column default when it inserts the row.
+  def last_activity_at
+    entries.maximum(:created_at) || created_at
+  end
+
+  def parent
+    DurableAgent::Conversation.find_by(id: record.dig("parent", "conversationId")) if record["parent"]
+  end
+
+  # The entry of the parent conversation through which this one inherits history.
+  def parent_at
+    DurableAgent::Entry.find_by(id: record.dig("parent", "at")) if record["parent"]
+  end
+
+  def document(kind)
+    documents.of_kind(kind).first&.value || {}
+  end
+
+  def live = document("pi.live")
+  def inbox = document("pi.inbox").fetch("items", [])
+  def agent = document("pi.agent")
+
+  # The model this conversation runs on, "provider/modelId", pinned when it was started. The sidecar's default
+  # model only applies to conversations started without one.
+  def model
+    ref = agent["model"]
+    "#{ref["provider"]}/#{ref["modelId"]}" if ref
+  end
+
+  # "openai" and "u42" from the model "openai@u42/gpt-6.1-sol"; account is nil for a conversation on the app's
+  # own credentials.
+  def provider = scoped_provider.first
+  def account = scoped_provider.second
+
+  def busy?
+    live["run"].present?
+  end
+
+  def streaming_message
+    live.dig("generation", "message")
+  end
+
+  def running_tools
+    live.fetch("tools", [])
+  end
+
+  def transcript
+    entries.chronologically.visible
+  end
+
+  # The newest input that settled without an answer, if it is more recent than the last answer. An assistant
+  # entry that ended in an error or an abort is not an answer.
+  def last_failure
+    failure = submissions.unanswered.reverse_chronologically.first
+    return unless failure
+
+    last_answer = entries.reverse_chronologically.of_kind("pi.assistant").find(&:answer?)
+    failure if last_answer.nil? || failure.entry_id.to_i > last_answer.id
+  end
+
+  # pi.usage: tokens and cost per model over the whole conversation, and per tool.
+  def usage = document("pi.usage")
+  def usage_by_model = usage.fetch("models", {})
+  def total_tokens = usage_by_model.values.sum { |model| model["totalTokens"].to_i }
+  def total_cost = usage_by_model.values.sum { |model| model.dig("cost", "total").to_f }
+
+  # The sidecar commits the submission before it answers, so the row is there to find.
+  # Both clear the query cache, so busy?, live and transcript read what the sidecar committed.
+  def say(content, request_id:, when_busy: nil)
+    response = DurableAgent.client.submit(id, content, request_id: request_id, when_busy: when_busy)
+    DurableAgent.changed_by_sidecar
+    submissions.find(response.fetch("id"))
+  end
+
+  def abort
+    DurableAgent.client.abort(id).tap { DurableAgent.changed_by_sidecar }
+  end
+
+  private
+    def scoped_provider
+      model ? DurableAgent::Account.parse(model.split("/", 2).first) : []
+    end
+end

data/app/models/durable_agent/document/revision.rb

@@ -0,0 +1,16 @@
+# A base (the whole value) or a delta (chord ops) of a document, in commit order.
+class DurableAgent::Document::Revision < DurableAgent::ApplicationRecord
+  include DurableAgent::HarnessRecord
+
+  self.table_name = "durable_agent_document_revisions"
+  self.primary_key = [ :document_id, :seq ]
+
+  belongs_to :document
+
+  def base? = kind == "base"
+  def delta? = kind == "delta"
+
+  def value
+    JSON.parse(content) if base?
+  end
+end

data/app/models/durable_agent/document.rb

@@ -0,0 +1,27 @@
+# One incarnation of a pi-durable document: pi.agent, pi.live, pi.inbox, pi.usage, pi.provider, or an
+# application's. The sidecar stores every document Rails reads as a single base revision (it folds each delta
+# into a new base before committing), so the current value is the content of the newest revision.
+class DurableAgent::Document < DurableAgent::ApplicationRecord
+  include DurableAgent::HarnessRecord
+
+  # The newest revision is a delta: reading it would need a port of chord's delta replay.
+  class HistoryNotSupported < StandardError; end
+
+  attribute :record, :json
+
+  has_many :revisions, -> { order(:seq) }, dependent: nil
+
+  scope :current, -> { where(retired_at: nil) }
+  scope :of_kind, ->(kind) { where(kind: DurableAgent::IndexedString.encode(kind)) }
+
+  def kind = DurableAgent::IndexedString.decode(super)
+  def key = (DurableAgent::IndexedString.decode(key_value) if keyed?)
+  def keyed? = family == 1
+  def retired? = retired_at.present?
+
+  def value
+    newest = revisions.reorder(seq: :desc).first
+    raise HistoryNotSupported, "document #{id} (#{kind}) ends in a delta revision" if newest&.delta?
+    newest&.value
+  end
+end

data/app/models/durable_agent/entry.rb

@@ -0,0 +1,56 @@
+# One immutable transcript record. `kind` is pi's (`pi.user`, `pi.assistant`, `pi.tool-result`, `pi.system`,
+# `pi.reset`, `pi.compaction`) or an application kind. `model` holds the messages the model sees; `data` is the
+# application payload. All of it lives in the `record` JSON, so kind filtering happens in Ruby.
+class DurableAgent::Entry < DurableAgent::ApplicationRecord
+  include DurableAgent::HarnessRecord
+
+  HIDDEN_KINDS = %w[ pi.system pi.reset ].freeze
+
+  attribute :record, :json
+
+  belongs_to :conversation
+
+  scope :chronologically, -> { order(:id) }
+  scope :reverse_chronologically, -> { order(id: :desc) }
+
+  def self.visible = all.select(&:visible?)
+  def self.of_kind(*kinds) = all.select { |entry| entry.kind.in?(kinds.flatten) }
+
+  def kind = record["kind"]
+  def data = record["data"]
+  def model = record["model"]
+  def head = record["head"]
+  def by_task_id = record["byTaskId"]
+
+  def visible? = !kind.in?(HIDDEN_KINDS)
+  def user? = kind == "pi.user"
+  def assistant? = kind == "pi.assistant"
+  def tool_result? = kind == "pi.tool-result"
+  def compaction? = kind == "pi.compaction"
+
+  def messages = Array.wrap(model)
+  def text = DurableAgent::MessageText.text(messages)
+  def tool_calls = DurableAgent::MessageText.tool_calls(messages)
+  def thinking? = DurableAgent::MessageText.thinking?(messages)
+
+  def tool_name = messages.first&.dig("toolName")
+  def error? = messages.any? { |message| message["isError"] }
+
+  # What pi-ai records on each message: the model that answered, how it stopped, tokens, timing.
+  def message = messages.first || {}
+  def provider = message["provider"]
+  def model_id = message["model"] # not model_name, which is Active Model's
+  def model_ref = ("#{provider}/#{model_id}" if provider && model_id)
+  def stop_reason = message["stopReason"] # "stop", "length", "toolUse", "aborted", "error"
+  def error_message = message["errorMessage"]
+  def usage = message["usage"] || {}
+  def total_tokens = usage["totalTokens"]
+  def cost = usage.dig("cost", "total")
+  def duration_ms = message["durationMs"]
+  def timestamp = (Time.zone.at(message["timestamp"] / 1000.0) if message["timestamp"])
+
+  # An assistant entry the model request ended in an error or an abort: it carries no answer, and the input it was
+  # for settles unanswered.
+  def failed? = assistant? && stop_reason.in?(%w[ error aborted ])
+  def answer? = assistant? && !failed?
+end

data/app/models/durable_agent/report.rb

@@ -0,0 +1,14 @@
+# A failure the harness reported without failing the operation: a faulted or parked task, a hook error, a
+# failed session. Show these to operators.
+class DurableAgent::Report < DurableAgent::ApplicationRecord
+  include DurableAgent::HarnessRecord
+
+  self.inheritance_column = nil
+
+  attribute :info, :json
+
+  belongs_to :conversation, optional: true
+
+  scope :reverse_chronologically, -> { order(id: :desc) }
+  scope :latest, -> { reverse_chronologically.limit(20) }
+end

data/app/models/durable_agent/submission.rb

@@ -0,0 +1,57 @@
+# Something Rails handed to a conversation: queued, placed as an entry, then done (answered) or unanswered.
+# `request_id` is the id Rails chose, so a retried request finds the same submission. pi-durable stores it
+# JSON-encoded ("\"42\""), as JSON.stringify writes it, so lookups encode it the same way.
+class DurableAgent::Submission < DurableAgent::ApplicationRecord
+  include DurableAgent::HarnessRecord
+
+  attribute :record, :json
+
+  belongs_to :conversation
+
+  scope :chronologically, -> { order(:id) }
+  scope :reverse_chronologically, -> { order(id: :desc) }
+  scope :pending, -> { where(status: %w[ queued placed ]) }
+  scope :settled, -> { where(status: %w[ done unanswered ]) }
+  scope :unanswered, -> { where(status: "unanswered") }
+  scope :for_request, ->(request_id) { where(request_id: DurableAgent::IndexedString.encode(request_id)) }
+
+  # Why an input went unanswered, for people. pi-durable reasons: no_model, run_failed, aborted, withdrawn...
+  REASONS = {
+    "no_model" => "No model could run: the conversation has none, or the sidecar does not know its model id.",
+    "model_error" => "The model returned an error.",
+    "run_failed" => "The run failed.",
+    "aborted" => "The run was stopped."
+  }.freeze
+
+  def request_id
+    DurableAgent::IndexedString.decode(super) if super
+  end
+
+  def type = record["type"] # "input" or "write"
+  def entry_id = record["entry"]
+  def answer_entry_id = record["answer"]
+  def reason = record["reason"]
+  def detail = record["detail"]
+
+  def entry = DurableAgent::Entry.find_by(id: entry_id)
+  def answer = DurableAgent::Entry.find_by(id: answer_entry_id)
+
+  # The detail pi-durable recorded: a string for model_error (the provider's message), a hash for run_failed.
+  def detail_text
+    detail.is_a?(Hash) ? detail["message"] : detail.presence
+  end
+
+  # no_model names the conversation's pinned model when it has one: the sidecar does not register that provider, or
+  # the id is not in its catalog. pi-durable records no detail for it. model_error and run_failed carry theirs.
+  def explanation
+    if reason == "no_model" && (model = conversation&.model)
+      "Model #{model} is not available on the sidecar. Its provider is not registered, or the model id is unknown."
+    else
+      [ REASONS.fetch(reason.to_s) { "The agent did not answer (#{reason})." }, detail_text ].compact.join(" ")
+    end
+  end
+
+  def pending? = status.in?(%w[ queued placed ])
+  def done? = status == "done"
+  def unanswered? = status == "unanswered"
+end

data/app/models/durable_agent/task.rb

@@ -0,0 +1,17 @@
+# Durable work inside a conversation: a run, a tool call, a compaction. `kind` is the task definition's name.
+class DurableAgent::Task < DurableAgent::ApplicationRecord
+  include DurableAgent::HarnessRecord
+
+  attribute :record, :json
+
+  belongs_to :conversation
+
+  scope :of_kind, ->(kind) { where(kind: DurableAgent::IndexedString.encode(kind)) }
+  scope :unfinished, -> { where.not(status: "terminal") }
+
+  def kind = DurableAgent::IndexedString.decode(super)
+
+  def terminal? = status == "terminal"
+  def abort_requested? = abort_requested == 1
+  def background? = background == 1
+end

data/config/routes.rb

@@ -0,0 +1,5 @@
+DurableAgent::Engine.routes.draw do
+  get "tools", to: "tools#index"
+  post "tools/:name", to: "tools#create", as: :tool
+  post "events", to: "events#create"
+end