durable_agent 0.1.0

data/lib/durable_agent/indexed_string.rb

@@ -0,0 +1,14 @@
+require "json"
+
+module DurableAgent
+  # pi-durable indexes some strings (task and document kinds, document keys, request ids) by their JSON encoding,
+  # written in the sidecar by JavaScript's JSON.stringify. A lookup must produce the same bytes. Rails' to_json
+  # escapes &, < and > (and U+2028/U+2029) as \uXXXX, which JSON.stringify never does; JSON.generate escapes only
+  # what JSON requires, as JSON.stringify does.
+  module IndexedString
+    extend self
+
+    def encode(value) = JSON.generate(value.to_s)
+    def decode(text) = JSON.parse(text)
+  end
+end

data/lib/durable_agent/message_text.rb

@@ -0,0 +1,23 @@
+module DurableAgent
+  # Turns pi messages (an entry's `model` column, or the streaming partial in pi.live) into plain text.
+  # Content is either a string or an array of blocks: text, thinking, toolCall, image.
+  module MessageText
+    extend self
+
+    def text(messages)
+      blocks(messages).filter_map { |block| block.is_a?(String) ? block : (block["text"] if block["type"] == "text") }.join
+    end
+
+    def tool_calls(messages)
+      blocks(messages).select { |block| block.is_a?(Hash) && block["type"] == "toolCall" }
+    end
+
+    def thinking?(messages)
+      blocks(messages).any? { |block| block.is_a?(Hash) && block["type"] == "thinking" }
+    end
+
+    def blocks(messages)
+      Array.wrap(messages).flat_map { |message| Array.wrap(message["content"]) }
+    end
+  end
+end

data/lib/durable_agent/sidecar.rb

@@ -0,0 +1,97 @@
+require "erb"
+
+module DurableAgent
+  # Starts the bundled sidecar with every setting derived from the Rails app, so the two halves agree.
+  module Sidecar
+    extend self
+
+    PASS_THROUGH = %w[ OPENAI_API_KEY ANTHROPIC_API_KEY ].freeze
+
+    def env
+      config = DurableAgent.config
+
+      {
+        "DATABASE_URL" => database_url,
+        "DURABLE_AGENT_TOKEN" => config.token,
+        "DURABLE_AGENT_HOST" => config.host.to_s,
+        "DURABLE_AGENT_PORT" => config.port.to_s,
+        "DURABLE_AGENT_RAILS_URL" => config.rails_url.to_s,
+        "DURABLE_AGENT_MODEL" => config.model.to_s,
+        "DURABLE_AGENT_WORKSPACE_ROOT" => config.workspace_root.to_s,
+        "DURABLE_AGENT_NAME" => config.agent_name.to_s
+      }.merge(ENV.slice(*PASS_THROUGH))
+    end
+
+    # The one place to swap in a compiled binary later. Falls back to the TypeScript source when no bundle was
+    # built, which Node runs directly with type stripping.
+    def command
+      bundle = root.join("dist/sidecar.js")
+      [ "node", (bundle.exist? ? bundle : root.join("src/main.ts")).to_s ]
+    end
+
+    def exec
+      FileUtils.mkdir_p(DurableAgent.config.workspace_root)
+      Kernel.exec(env, *command)
+    end
+
+    def root
+      DurableAgent::Engine.root.join("sidecar")
+    end
+
+    # The app's primary database, which the sidecar opens too: pi-durable's tables live there.
+    def database_url(db_config = ActiveRecord::Base.connection_db_config)
+      return node_sslmode_in(db_config.url) if db_config.respond_to?(:url) && db_config.url.present?
+
+      case db_config.adapter
+      when "sqlite3" then sqlite_url(db_config.configuration_hash)
+      when "postgresql" then postgres_url(db_config.configuration_hash)
+      else raise ArgumentError, "durable_agent needs a postgresql or sqlite3 database, not #{db_config.adapter}"
+      end
+    end
+
+    # libpq's sslmode=require encrypts without verifying the server's certificate; node-postgres reads `require`
+    # as verify-full and would refuse the self-signed certificates many hosted databases use. `no-verify` is
+    # node-postgres' name for libpq's `require`. verify-ca and verify-full pass through and verify.
+    NODE_SSLMODES = { "require" => "no-verify" }.freeze
+
+    private
+      def sqlite_url(config)
+        "sqlite://#{File.expand_path(config[:database].to_s, Rails.root)}"
+      end
+
+      def postgres_url(config)
+        userinfo = [ config[:username], config[:password] ].compact.map { |part| ERB::Util.url_encode(part.to_s) }.join(":")
+        host = config[:host].presence || "localhost"
+        query = {}
+
+        # A socket directory cannot sit in the authority part of the URL; libpq and node-postgres take it as ?host=.
+        if host.start_with?("/")
+          query[:host] = host
+          host = ""
+        end
+        query[:sslmode] = NODE_SSLMODES.fetch(config[:sslmode].to_s, config[:sslmode].to_s) if config[:sslmode].present?
+        %i[ sslrootcert sslcert sslkey ].each do |key|
+          query[key] = File.expand_path(config[key].to_s, Rails.root) if config[key].present?
+        end
+        query[:options] = "-c search_path=#{search_path(config[:schema_search_path])}" if config[:schema_search_path].present?
+
+        authority = [ userinfo.presence, host ].compact.join("@")
+        authority += ":#{config[:port]}" if config[:port].present?
+        url = "postgres://#{authority}/#{ERB::Util.url_encode(config[:database].to_s)}"
+        query.any? ? "#{url}?#{query.map { |key, value| "#{key}=#{ERB::Util.url_encode(value)}" }.join("&")}" : url
+      end
+
+      # A startup option is split on spaces, so "public, shared" must lose its spaces (and any left be escaped).
+      def search_path(value)
+        value.to_s.split(",").map(&:strip).join(",").gsub(" ", "\\ ")
+      end
+
+      def node_sslmode_in(url)
+        if url.start_with?("postgres:", "postgresql:")
+          url.sub(/([?&]sslmode=)([^&#]*)/) { "#{$1}#{NODE_SSLMODES.fetch($2, $2)}" }
+        else
+          url
+        end
+      end
+  end
+end

data/lib/durable_agent/test_helper.rb

@@ -0,0 +1,110 @@
+module DurableAgent
+  # Test support for apps built on durable_agent. In test/test_helper.rb:
+  #
+  #   require "durable_agent/test_helper"
+  #
+  #   class ActiveSupport::TestCase
+  #     include DurableAgent::TestHelper
+  #   end
+  #
+  # `stub_sidecar` replaces DurableAgent.client calls with canned responses or callables and records each call.
+  # It also seals the client: every other call raises DurableAgent::Unavailable, so a test never reaches a sidecar
+  # that happens to be running. `fake_sidecar` goes further for the three commands that write: like the real sidecar,
+  # it commits the conversation or submission row before it answers, so `DurableAgent.start` and `conversation.say`
+  # find them.
+  #
+  #   fake_sidecar
+  #   chat = Chat.create!                      # calls DurableAgent.start
+  #   chat.conversation.say("Hi", request_id: 1)
+  #   assert_equal 1, sidecar_calls(:submit).size
+  module TestHelper
+    DISCONNECTED = { "openai" => nil, "anthropic" => nil }.freeze
+    CONNECTED = { "openai" => { "type" => "oauth", "source" => "OAuth" }, "anthropic" => nil }.freeze
+
+    # Ids the fake hands out: above the ids pi-durable starts from, and above the gem's own test fixtures.
+    FAKE_IDS_FROM = 950_000
+
+    # The client's calls to the sidecar; `url` and `token` are configuration.
+    SIDECAR_CALLS = DurableAgent::Client.public_instance_methods(false) - %i[ url token ]
+
+    #   stub_sidecar(auth: CONNECTED, submit: ->(id, content, **) { { "id" => 1 } }, abort: DurableAgent::Unavailable)
+    def stub_sidecar(**responses)
+      client = DurableAgent.client
+      responses.each_key { |name| raise ArgumentError, "DurableAgent::Client has no method #{name}" unless client.respond_to?(name) }
+
+      @sidecar_stubbed ||= []
+      sealed = (SIDECAR_CALLS - @sidecar_stubbed - responses.keys).index_with do |name|
+        ->(*, **) { raise DurableAgent::Unavailable.new(nil, nil, "DurableAgent.client.#{name} is not stubbed; stub_sidecar(#{name}: ...)") }
+      end
+
+      calls = sidecar_calls
+      responses.merge(sealed).each do |name, response|
+        @sidecar_stubbed << name
+        client.define_singleton_method(name) do |*args, **kwargs|
+          calls << [ name, args, kwargs ]
+          if response.is_a?(Exception) || (response.is_a?(Class) && response < Exception)
+            raise response
+          else
+            response.respond_to?(:call) ? response.call(*args, **kwargs) : response
+          end
+        end
+      end
+    end
+
+    # Every stubbed call as [name, args, kwargs], or only those of one name.
+    def sidecar_calls(name = nil)
+      calls = (@sidecar_calls ||= [])
+      name ? calls.select { |call| call.first == name } : calls
+    end
+
+    # create_conversation, submit and abort answered as the sidecar answers them, after committing the rows it
+    # commits. Submissions are idempotent on request_id, and an unknown conversation is a 404, as on the sidecar.
+    # Further responses stub other calls: fake_sidecar(auth: CONNECTED).
+    def fake_sidecar(**responses)
+      stub_sidecar(create_conversation: method(:fake_create_conversation), submit: method(:fake_submit),
+        abort: method(:fake_abort), **responses)
+    end
+
+    def teardown
+      super
+      Array(@sidecar_stubbed).uniq.each { |name| DurableAgent.client.singleton_class.send(:remove_method, name) }
+      @sidecar_stubbed = @sidecar_calls = @fake_sidecar_id = nil
+    end
+
+    private
+      def fake_create_conversation(model: nil, instructions: nil, account: nil)
+        id = next_fake_sidecar_id
+        DurableAgent::Conversation.insert({ id: id, record: { id: id } })
+        { "id" => id }
+      end
+
+      def fake_submit(conversation_id, content, request_id:, when_busy: nil)
+        fake_conversation!(conversation_id)
+
+        submission = DurableAgent::Submission.where(conversation_id: conversation_id).for_request(request_id).first
+        submission ||= begin
+          id = next_fake_sidecar_id
+          DurableAgent::Submission.insert({ id: id, conversation_id: conversation_id, request_id: DurableAgent::IndexedString.encode(request_id),
+            status: "queued", record: { id: id, conversationId: conversation_id, requestId: request_id.to_s, type: "input", status: "queued" } })
+          DurableAgent::Submission.find(id)
+        end
+
+        { "id" => submission.id, "status" => submission.status }
+      end
+
+      def fake_abort(conversation_id)
+        fake_conversation!(conversation_id)
+        { "ok" => true }
+      end
+
+      def fake_conversation!(id)
+        unless DurableAgent::Conversation.exists?(id)
+          raise DurableAgent::Error.new(404, { "error" => "conversation #{id} not found" })
+        end
+      end
+
+      def next_fake_sidecar_id
+        @fake_sidecar_id = (@fake_sidecar_id || FAKE_IDS_FROM) + 1
+      end
+  end
+end

data/lib/durable_agent/tool.rb

@@ -0,0 +1,91 @@
+module DurableAgent
+  # A tool the agent can call, written in Ruby. The sidecar fetches every tool's definition from
+  # GET /durable_agent/tools and runs one with POST /durable_agent/tools/:name.
+  #
+  #   class LookupInvoice < DurableAgent::Tool
+  #     description "Fetch one invoice by number"
+  #     param :number, :string, "Invoice number like INV-1042"
+  #     param :include_lines, :boolean, "Include line items", required: false
+  #     replay :safe
+  #
+  #     def call(number:, include_lines: false)
+  #       Invoice.find_by!(number:).as_json
+  #     end
+  #   end
+  class Tool
+    # Raise this with a message for the model: "No invoice INV-9; numbers look like INV-1042". Other errors reach
+    # the model as their class name only.
+    class Error < StandardError; end
+
+    TYPES = %i[ string integer number boolean array object ].freeze
+    REPLAY_MODES = %i[ safe unsafe ].freeze
+
+    class_attribute :params, instance_accessor: false, default: {}
+
+    class << self
+      def description(text = nil)
+        text ? @description = text : @description.to_s
+      end
+
+      # Extra JSON Schema keywords (enum:, items:, properties:) pass straight through.
+      def param(name, type, description = nil, required: true, **schema)
+        raise ArgumentError, "unknown param type #{type.inspect}" unless type.in?(TYPES)
+        self.params = params.merge(name.to_sym => { type: type, description: description, required: required, schema: schema })
+      end
+
+      # Whether pi may run the tool again after a crash mid-call. Unsafe tools are reported instead of repeated.
+      def replay(mode = nil)
+        if mode
+          raise ArgumentError, "replay is :safe or :unsafe" unless mode.in?(REPLAY_MODES)
+          @replay = mode
+        else
+          @replay || (superclass.respond_to?(:replay) ? superclass.replay : :unsafe)
+        end
+      end
+
+      def tool_name(name = nil)
+        name ? @tool_name = name.to_s : @tool_name || self.name.demodulize.underscore
+      end
+
+      def to_definition
+        {
+          name: tool_name,
+          description: description,
+          parameters: {
+            type: "object",
+            properties: params.transform_values { |param| { type: param[:type].to_s, description: param[:description] }.compact.merge(param[:schema]) },
+            required: params.select { |_, param| param[:required] }.keys.map(&:to_s),
+            additionalProperties: false
+          },
+          replay: replay.to_s
+        }
+      end
+
+      # Runs the tool with the arguments object the model produced (JSON, string keys).
+      def run(arguments)
+        new.call(**coerce(arguments))
+      end
+
+      def coerce(arguments)
+        arguments ||= {}
+        raise ArgumentError, "arguments must be an object" unless arguments.is_a?(Hash)
+        arguments = arguments.transform_keys(&:to_s)
+
+        unknown = arguments.keys - params.keys.map(&:to_s)
+        raise ArgumentError, "unknown #{"argument".pluralize(unknown.size)}: #{unknown.join(", ")}" if unknown.any?
+
+        # Models send null for optional arguments they skip; let the method's default apply instead.
+        given = arguments.compact.transform_keys(&:to_sym)
+
+        missing = params.select { |name, param| param[:required] && !given.key?(name) }.keys
+        raise ArgumentError, "missing required #{"argument".pluralize(missing.size)}: #{missing.join(", ")}" if missing.any?
+
+        given
+      end
+    end
+
+    def call(**)
+      raise NotImplementedError, "#{self.class.name} must implement #call"
+    end
+  end
+end

data/lib/durable_agent/version.rb

@@ -0,0 +1,3 @@
+module DurableAgent
+  VERSION = "0.1.0"
+end

data/lib/durable_agent.rb

@@ -0,0 +1,67 @@
+require "durable_agent/version"
+require "durable_agent/engine"
+require "durable_agent/configuration"
+require "durable_agent/account"
+require "durable_agent/client"
+require "durable_agent/current"
+require "durable_agent/message_text"
+require "durable_agent/indexed_string"
+require "durable_agent/tool"
+require "durable_agent/sidecar"
+
+module DurableAgent
+  class << self
+    def configure
+      yield config
+    end
+
+    def config
+      @config ||= Configuration.new
+    end
+
+    def client
+      @client ||= Client.new
+    end
+
+    # Creates a conversation on the sidecar and returns its row, which the sidecar commits before it answers.
+    # Without a model the sidecar uses its default, which `durable_agent:sidecar` sets from config.model.
+    #
+    # With an account the conversation runs on that account's provider credentials (see Connection), without one
+    # on the app's. The sidecar commits in its own transaction, so this cannot join the caller's: when the app's own
+    # record fails to save afterwards, the conversation stays behind, unreferenced.
+    def start(model: nil, instructions: nil, account: nil)
+      response = client.create_conversation(model: model, instructions: instructions, **account_scope(account))
+      changed_by_sidecar
+      conversation(response.fetch("id"))
+    end
+
+    def conversation(id)
+      Conversation.find(id)
+    end
+
+    # Every provider the sidecar knows, signed in or not, with how: {"openai" => {"type" => "oauth", "source" =>
+    # "OAuth"}, "anthropic" => {"type" => "api_key", "source" => "ANTHROPIC_API_KEY"}, "google" => nil, ...}.
+    # Includes "faux" when the sidecar's model is faux/faux-1. With an account, that account's providers, under
+    # their base names.
+    def auth(account: nil)
+      client.auth(**account_scope(account))
+    end
+
+    # The stream config.on_auth refreshes when the app's sign-ins change, or the account's:
+    # `turbo_stream_from DurableAgent.auth_stream(account)`.
+    def auth_stream(account = nil)
+      [ "durable_agent:auth", Account.normalize(account) ].compact.join(":")
+    end
+
+    # The sidecar just committed rows this thread may already have read: drop the query cache so the next read in
+    # the same request sees them.
+    def changed_by_sidecar
+      DurableAgent::ApplicationRecord.connection_pool.clear_query_cache
+    end
+
+    # The keyword arguments that scope a client call to an account: none for the app's own account.
+    def account_scope(account)
+      { account: Account.normalize(account) }.compact
+    end
+  end
+end

data/lib/generators/durable_agent/install/install_generator.rb

@@ -0,0 +1,75 @@
+require "rails/generators"
+require "rails/generators/active_record"
+
+module DurableAgent
+  module Generators
+    class InstallGenerator < Rails::Generators::Base
+      include Rails::Generators::Migration
+
+      source_root File.expand_path("templates", __dir__)
+
+      SIDECAR = "sidecar: bin/rails durable_agent:sidecar"
+      # foreman gives the first process PORT=5000; the sidecar reaches Rails at rails_url, port 3000 by default.
+      WEB = "web: bin/rails server -p 3000"
+
+      def self.next_migration_number(dirname)
+        ActiveRecord::Generators::Base.next_migration_number(dirname)
+      end
+
+      def copy_migration
+        migration_template "create_durable_agent_tables.rb.tt", "db/migrate/create_durable_agent_tables.rb"
+      end
+
+      def create_initializer
+        template "durable_agent.rb.tt", "config/initializers/durable_agent.rb"
+      end
+
+      def mount_engine
+        routes = File.join(destination_root, "config/routes.rb")
+        route %(mount DurableAgent::Engine => "/durable_agent") unless File.read(routes).include?("DurableAgent::Engine")
+      end
+
+      def add_sidecar_process
+        procfile = File.join(destination_root, "Procfile.dev")
+
+        if !File.exist?(procfile)
+          create_file "Procfile.dev", "#{WEB}\n#{SIDECAR}\n"
+        else
+          append_to_file "Procfile.dev", "#{SIDECAR}\n", force: true unless File.read(procfile).include?(SIDECAR)
+          warn_about_web_port File.read(procfile)
+        end
+      end
+
+      def show_next_steps
+        say <<~TEXT
+
+          durable_agent is installed. Next:
+
+            bin/rails db:migrate
+            bin/dev            # runs web and sidecar from Procfile.dev (needs foreman or overmind)
+
+          Development and test derive the sidecar token from secret_key_base. In production set one:
+
+            bin/rails credentials:edit     # durable_agent:
+                                           #   token: #{SecureRandom.hex(32)}
+
+          or export DURABLE_AGENT_TOKEN for both the web and the sidecar processes. If production uses
+          force_ssl or config.hosts, see the note at the end of config/initializers/durable_agent.rb.
+        TEXT
+      end
+
+      private
+        def warn_about_web_port(procfile)
+          web = procfile[/^web:.*$/]
+          if web && web !~ /\s(-p|--port)[\s=]?\d+/
+            say <<~TEXT, :yellow
+
+              Procfile.dev's web process sets no port: foreman runs it on PORT=5000, but the sidecar calls this app at
+              config.rails_url, http://127.0.0.1:3000 by default. Change the line to `#{WEB}`,
+              or set DURABLE_AGENT_RAILS_URL=http://127.0.0.1:5000.
+            TEXT
+          end
+        end
+    end
+  end
+end

data/lib/generators/durable_agent/install/templates/create_durable_agent_tables.rb.tt

@@ -0,0 +1,120 @@
+# The first nine tables are pi-durable's own storage schema (version 1) under the durable_agent_ prefix: the
+# sidecar runs pi-durable's storage core over them, so names, columns and indexes must match it. Rails owns the
+# DDL and the sidecar never runs any; the sidecar is the only writer, Rails reads. Ids and singletons are pi's: the
+# sidecar supplies every one, so the default primary keys are only a type (an INTEGER PRIMARY KEY rowid alias on
+# SQLite, as in pi-durable's own DDL; bigserial on Postgres, its sequence unused). created_at is extra: pi-durable's
+# inserts name their columns, so the database's default fills it. JSON lives in text columns, never jsonb, which
+# rejects \u0000 that a model may produce. No foreign keys: pi-durable writes the rows of one commit in its own
+# order. No data: the sidecar seeds the singletons at boot.
+class CreateDurableAgentTables < ActiveRecord::Migration[<%= ActiveRecord::Migration.current_version %>]
+  def change
+    create_table :durable_agent_durable_schema, primary_key: :singleton do |t|  # one row, singleton = 1
+      t.integer :version, null: false
+    end
+
+    create_table :durable_agent_durable_metadata, primary_key: :singleton do |t|
+      t.text :next_id, null: false            # pi stores it as text: ids can exceed 2^53 in principle
+      t.bigint :next_seq, null: false
+    end
+
+    create_table :durable_agent_record_ids do |t|
+      t.text :record_type, null: false        # conversation | entry | task | submission | document
+    end
+
+    create_table :durable_agent_conversations do |t|
+      t.bigint :owner_conversation_id
+      t.bigint :owner_task_id
+      t.text :record, null: false             # ConversationRecord JSON: {id, parent?: {conversationId, at}, owner?, ...}
+      t.datetime :created_at, null: false, default: -> { "CURRENT_TIMESTAMP" }
+      t.index [ :owner_conversation_id, :id ], name: "durable_agent_conversations_by_owner_conversation"
+      t.index [ :owner_task_id, :id ], name: "durable_agent_conversations_by_owner_task"
+    end
+
+    create_table :durable_agent_entries do |t|
+      t.bigint :conversation_id, null: false
+      t.bigint :head
+      t.bigint :commit_seq, null: false
+      t.text :record, null: false             # EntryRecord JSON: {id, conversationId, kind, data?, model?, head?, byTaskId?}
+      t.datetime :created_at, null: false, default: -> { "CURRENT_TIMESTAMP" }
+      t.index [ :conversation_id, :id ], order: { id: :desc }, name: "durable_agent_entries_by_conversation"
+      t.index [ :conversation_id, :id ], order: { id: :desc }, name: "durable_agent_entry_heads_by_conversation", where: "head IS NOT NULL"
+    end
+
+    create_table :durable_agent_tasks do |t|
+      t.bigint :conversation_id, null: false
+      t.text :kind, null: false               # JSON-encoded string, e.g. "\"pi.run\""
+      t.text :status, null: false             # pending | running | waiting | completing | terminal
+      t.integer :abort_requested, null: false # 0 | 1
+      t.integer :background, null: false      # 0 | 1
+      t.text :record, null: false
+      t.index [ :status, :id ], name: "durable_agent_tasks_by_status"
+      t.index [ :conversation_id, :id ], name: "durable_agent_tasks_by_conversation"
+      t.index [ :kind, :id ], name: "durable_agent_tasks_by_kind"
+      t.index [ :abort_requested, :id ], name: "durable_agent_tasks_by_abort_requested"
+      t.index [ :background, :id ], name: "durable_agent_tasks_by_background"
+    end
+
+    create_table :durable_agent_submissions do |t|
+      t.bigint :conversation_id, null: false
+      t.text :request_id                      # JSON-encoded string, e.g. "\"42\""; NULL when the harness made it
+      t.text :status, null: false             # queued | placed | done | unanswered
+      t.text :record, null: false             # SubmissionRecord JSON: {id, conversationId, requestId?, type, status, entry?, answer?, reason?, detail?}
+      t.datetime :created_at, null: false, default: -> { "CURRENT_TIMESTAMP" }
+      t.index [ :conversation_id, :request_id ], name: "durable_agent_submissions_by_request"
+      t.index [ :conversation_id, :id ], name: "durable_agent_submissions_by_conversation"
+      t.index [ :status, :id ], name: "durable_agent_submissions_by_status"
+    end
+
+    create_table :durable_agent_documents do |t|
+      t.text :kind, null: false               # JSON-encoded string, e.g. "\"pi.live\""
+      t.integer :family, null: false          # 0 = unkeyed, 1 = keyed
+      t.text :key_value, null: false          # JSON-encoded key, "\"\"" when unkeyed
+      t.text :scope_kind, null: false         # session | conversation | task
+      t.bigint :owner_id, null: false         # 0, the conversation id, or the task id
+      t.bigint :created_at, null: false       # commit seq, not a time
+      t.bigint :retired_at                    # commit seq, not a time
+      t.text :record, null: false             # DocumentRecord JSON: {id, kind, scope: {kind, conversationId?|taskId?}, key?, history, fork?, createdAt, retiredAt?}
+      t.index [ :kind, :scope_kind, :owner_id, :family, :key_value, :created_at, :retired_at ], order: { created_at: :desc },
+        name: "durable_agent_documents_by_address"
+      t.index [ :scope_kind, :owner_id, :id ], name: "durable_agent_documents_by_scope"
+      t.index [ :scope_kind, :owner_id, :kind, :id ], name: "durable_agent_documents_by_scope_kind"
+    end
+
+    create_table :durable_agent_document_revisions, primary_key: [ :document_id, :seq ] do |t|
+      t.bigint :document_id, null: false
+      t.bigint :seq, null: false
+      t.text :kind, null: false               # base | delta
+      t.bigint :version, null: false
+      t.text :content, null: false            # base: the value as JSON; delta: chord ops as JSON
+      t.index [ :document_id, :kind, :seq ], order: { seq: :desc }, name: "durable_agent_document_revisions_by_kind"
+    end
+
+    # Written by the sidecar through its database facade.
+    create_table :durable_agent_reports do |t|
+      t.text :type, null: false
+      t.bigint :conversation_id
+      t.bigint :task_id
+      t.text :task_kind
+      t.text :extension
+      t.text :message, null: false
+      t.text :info, null: false               # JSON text
+      t.datetime :created_at, null: false
+      t.index [ :conversation_id, :id ]
+    end
+
+    # Provider sign-ins, encrypted by the sidecar with a key derived from DURABLE_AGENT_TOKEN. Rails has no model
+    # for this table and never decrypts it; connection status comes from the sidecar's GET /auth.
+    create_table :durable_agent_credentials, id: false do |t|
+      t.text :provider_id, primary_key: true
+      t.text :credential, null: false         # the encrypted envelope as JSON text
+      t.datetime :updated_at, null: false
+    end
+
+    # device_id and schema_version, written by the sidecar.
+    create_table :durable_agent_settings, id: false do |t|
+      t.text :key, primary_key: true
+      t.text :value, null: false
+      t.datetime :updated_at, null: false
+    end
+  end
+end

data/lib/generators/durable_agent/install/templates/durable_agent.rb.tt

@@ -0,0 +1,36 @@
+DurableAgent.configure do |config|
+  # The default model, "provider/modelId". Unset, it is ENV["DURABLE_AGENT_MODEL"], then "openai/gpt-6.1-sol", so
+  # `DURABLE_AGENT_MODEL=faux/faux-1 bin/dev` runs the scripted offline model. Setting it here wins over the variable.
+  # config.model = "openai/gpt-6.1-sol"
+
+  # Tools are DurableAgent::Tool subclasses. Give their names as strings so code reloading keeps working.
+  # config.tools = %w[ LookupInvoice ]
+
+  # Where the sidecar listens, and where it reaches this app for tools and change events.
+  # config.host = "127.0.0.1"
+  # config.port = 4010
+  # config.rails_url = "http://127.0.0.1:3000"
+
+  # The shared secret. Defaults to credentials.durable_agent.token, then ENV["DURABLE_AGENT_TOKEN"], and in
+  # development and test to a value derived from secret_key_base.
+  # config.token = "..."
+
+  # The models' base class. If ApplicationRecord uses connects_to (roles, shards), inherit from it.
+  # config.parent_record_class = "ApplicationRecord"
+
+  # Called in this app's web process when the sidecar reports a change. The defaults refresh the pages subscribed
+  # with `turbo_stream_from conversation`; reports without a conversation refresh `turbo_stream_from
+  # "durable_agent:reports"`; sign-ins and sign-outs refresh `turbo_stream_from "durable_agent:auth"`.
+  # config.on_change = ->(conversation) { Turbo::StreamsChannel.broadcast_refresh_to(conversation) }
+  # config.on_report = ->(report) { Rails.logger.warn(report.message) }
+  # on_auth gets provider ids, scoped for accounts ("openai", "openai@u42"); its default also refreshes
+  # `turbo_stream_from DurableAgent.auth_stream(account)` for each account named.
+  # config.on_auth = ->(providers) { Turbo::StreamsChannel.broadcast_refresh_to("durable_agent:auth") }
+end
+
+# In production the sidecar calls this app over plain HTTP at rails_url (loopback by default). With
+# config.force_ssl, keep /durable_agent out of the HTTPS redirect; with config.hosts set, allow the sidecar's
+# host. In config/environments/production.rb:
+#
+#   config.ssl_options = { redirect: { exclude: ->(request) { request.path.start_with?("/durable_agent") } } }
+#   config.hosts << "127.0.0.1"

data/lib/tasks/durable_agent_tasks.rake

@@ -0,0 +1,6 @@
+namespace :durable_agent do
+  desc "Run the durable_agent sidecar with settings derived from this app"
+  task sidecar: :environment do
+    DurableAgent::Sidecar.exec
+  end
+end