durable_agent 0.1.0

data/docs/guide.md

@@ -0,0 +1,421 @@
+# durable_agent
+
+Crash-safe, resumable AI agent conversations for Rails.
+
+durable_agent packages [pi-durable](https://github.com/earendil-works/pi), a durable agent runtime written in
+TypeScript, as one gem: a Rails engine plus the sidecar process that runs the agents. pi-durable keeps its state
+in your app's own database, Postgres or SQLite, in tables your migration creates. The sidecar is their only
+writer; your app reads conversations with plain Active Record and gets live updates over Turbo. Tools are Ruby
+classes.
+
+```
+browser ◀─Turbo── Puma ──HTTP commands─────────────────▶ sidecar (node)
+                   │   ◀──GET/POST /durable_agent/tools──   │
+                   │   ◀──POST /durable_agent/events─────   │
+                   │ reads                                  │ writes
+                   ▼                                        ▼
+                  your database (Postgres or SQLite), durable_agent_* tables
+```
+
+Status: v1. `DESIGN.md` is the contract both halves are built against.
+
+## Requirements
+
+- Rails 8, with Postgres or SQLite (the app brings its own `pg` or `sqlite3` gem; durable_agent depends on neither)
+- Node 22.19 or newer on the machine that runs the sidecar
+
+## Install
+
+```sh
+bundle add durable_agent
+bin/rails generate durable_agent:install
+bin/rails db:migrate
+```
+
+The generator:
+
+- copies `db/migrate/*_create_durable_agent_tables.rb` (twelve `durable_agent_*` tables, the same on either database),
+- writes `config/initializers/durable_agent.rb`,
+- mounts the engine: `mount DurableAgent::Engine => "/durable_agent"`,
+- adds a `sidecar:` line to `Procfile.dev` (creating it with `web: bin/rails server -p 3000` and `sidecar:` if
+  needed; the sidecar calls Rails at port 3000 by default, and foreman would otherwise run Puma on 5000),
+- prints how to set a production token.
+
+## Use
+
+```ruby
+conversation = DurableAgent.start                       # or start(model: "anthropic/claude-x", instructions: "Be brief")
+chat.update!(durable_agent_conversation_id: conversation.id)
+
+conversation.say("Summarize invoice INV-1042", request_id: message.id)
+conversation.say("Actually, only the total", request_id: other.id, when_busy: :steer)   # :followUp, :steer, :reject
+conversation.abort
+
+conversation.transcript      # visible entries, oldest first (an Array)
+conversation.busy?           # a run is in progress
+conversation.streaming_message
+conversation.running_tools
+conversation.inbox
+conversation.last_failure    # the newest unanswered input, with #explanation
+conversation.model           # "openai/gpt-6.1-sol", pinned when the conversation started
+conversation.total_tokens / total_cost / usage_by_model   # from pi.usage, over the whole conversation
+
+entry.text / tool_calls / tool_name / error?
+entry.model_ref / stop_reason / total_tokens / cost / duration_ms / timestamp   # what pi-ai recorded on the message
+entry.failed?                # an assistant entry that ended in an error or abort: no answer, and error_message
+```
+
+`say` is idempotent on `request_id`: retrying with the same id returns the same submission. It returns the
+`DurableAgent::Submission` row, which the sidecar commits before it answers. Find it later with
+`conversation.submissions.for_request(id)`. `start`, `say` and `abort` clear the query cache, so `busy?`,
+`transcript` and friends read the sidecar's commit within the same request.
+
+`DurableAgent.start` cannot take part in your transaction: the sidecar commits the conversation on its own
+connection before it answers. If saving your own record fails afterwards, the conversation stays behind,
+unreferenced. It is harmless, and you can find such leftovers by comparing `DurableAgent::Conversation.top_level`
+with your own references.
+
+`DurableAgent::Conversation.top_level` lists conversations no task owns, without the root conversation the sidecar
+creates at boot (id 1, `DurableAgent::Conversation.root`). Conversations, entries and submissions carry
+`created_at`; `conversation.last_activity_at` is the newest entry's, or the conversation's own.
+
+Every entry has `kind` (`pi.user`, `pi.assistant`, `pi.tool-result`, ...), `text`, `tool_calls`, `tool_name` and
+`error?`. In a view, subscribe to the conversation and the default `on_change` callback refreshes the page
+whenever the sidecar commits a change to it:
+
+```erb
+<%= turbo_stream_from @chat.conversation %>
+<% @chat.conversation.transcript.each do |entry| %>
+  <p class="<%= entry.kind %>"><%= entry.text %></p>
+<% end %>
+```
+
+Add `<meta name="turbo-refresh-method" content="morph">` for smooth refreshes.
+
+### Errors
+
+All inherit from `DurableAgent::Error` (`status`, `body`):
+
+- `DurableAgent::Busy`: 409, the conversation is running and the submission used `when_busy: :reject`.
+- `DurableAgent::UnknownModel`: the model id is not one pi knows; `suggestions` lists close matches.
+- `DurableAgent::Unavailable`: the sidecar is not running, timed out, went away mid-response, or is still starting.
+
+### Provider sign-in
+
+Sign-ins (including OAuth refresh tokens) are stored in your app's database, in
+`durable_agent_credentials`, encrypted by the sidecar with AES-256-GCM under a key derived from the shared
+`DURABLE_AGENT_TOKEN`. Database dumps, replicas and read-only database users see ciphertext. Rails has no model for
+the table and never decrypts it. This is not a vault: the sidecar process holds the key, and anyone with both the
+database and the token can decrypt. API keys work through `OPENAI_API_KEY` / `ANTHROPIC_API_KEY`, read from the
+environment, or through `connection.set_api_key`, which stores them in the same table; subscriptions sign in with
+OAuth:
+
+```ruby
+DurableAgent.auth
+# => {"openai" => {"type" => "oauth", "source" => "OAuth"},
+#     "anthropic" => {"type" => "api_key", "source" => "ANTHROPIC_API_KEY"},
+#     "google" => nil, ...}
+
+connection = DurableAgent::Connection.new("openai")
+connection.connected? / connection.subscription? / connection.unreachable?
+login = connection.start_login                  # => {"id" => ..., "status" => "awaiting_browser", "url" => ...}
+connection.complete_login(login["id"], url_the_browser_ended_on)
+connection.login(login["id"])                   # poll status
+connection.cancel_login(login["id"])
+connection.disconnect
+```
+
+`DurableAgent.auth` lists every provider the sidecar's pi-ai knows, signed in or not (`nil`), plus `faux`, the
+offline model. `type` is `"oauth"` or `"api_key"`; `source` says where pi-ai found it (`"OAuth"`,
+`"stored credential"`, or the environment variable). `Connection` covers OpenAI and Anthropic, and tolerates an
+unreachable sidecar: it reads as not connected with `error` set.
+
+When a sign-in completes or a provider signs out, the sidecar posts an auth event and `config.on_auth` runs. Its
+default refreshes pages subscribed to `"durable_agent:auth"`, so a settings page updates by itself:
+
+```erb
+<%= turbo_stream_from "durable_agent:auth" %>
+```
+
+### Accounts
+
+Who pays for a conversation is the account it runs on. An account is a string you choose, typically a user id
+(`[A-Za-z0-9_.-]{1,64}`); without one, a conversation runs on the app's own credentials.
+
+| Who pays | Credential | Conversation |
+|---|---|---|
+| The app, one API key or sign-in for everyone | `OPENAI_API_KEY`, `Connection.new("openai").set_api_key(key)`, or Sign in with ChatGPT | `DurableAgent.start` |
+| Each user, with an API key | `Connection.new("openai", account: user.id).set_api_key(key)` | `DurableAgent.start(account: user.id)` |
+| Each user, with their ChatGPT plan | `Connection.new("openai", account: user.id).start_login`, then the user approves in the browser | `DurableAgent.start(account: user.id)` |
+
+```ruby
+DurableAgent.auth(account: user.id)            # that account's providers, under their base names
+connection = DurableAgent::Connection.new("openai", account: user.id)
+connection.set_api_key(params[:key])           # => {"type" => "api_key", "source" => "stored credential"}
+connection.api_key? / connection.source / connection.scoped_provider   # => true, "stored credential", "openai@42"
+connection.disconnect                          # their running conversations settle model_error until they connect again
+
+conversation = DurableAgent.start(account: user.id)
+conversation.model                             # => "openai@42/gpt-6.1-sol"
+conversation.provider / conversation.account   # => "openai", "42"
+```
+
+Your app decides which account a conversation runs on and what to do when that account has no credential;
+`DurableAgent.auth(account:)` says which providers it has. `config.on_auth` receives scoped provider ids
+(`"openai@42"`), and its default also refreshes each named account's stream, which a user's settings page
+subscribes to:
+
+```erb
+<%= turbo_stream_from DurableAgent.auth_stream(Current.user.id) %>
+```
+
+Usage per account is the sum of `conversation.usage` over that account's conversations.
+
+## Tools
+
+```ruby
+# app/tools/lookup_invoice.rb
+class LookupInvoice < DurableAgent::Tool
+  description "Fetch one invoice by number"
+  param :number, :string, "Invoice number like INV-1042"          # required by default
+  param :include_lines, :boolean, "Include line items", required: false
+  param :currency, :string, required: false, enum: %w[ EUR USD ] # extra JSON Schema keywords pass through
+  replay :safe                                                    # default :unsafe
+
+  def call(number:, include_lines: false)
+    invoice = Invoice.find_by!(number:)
+    invoice.as_json(include: include_lines ? :lines : nil)
+  end
+end
+```
+
+```ruby
+DurableAgent.configure { |config| config.tools = %w[ LookupInvoice ] }
+```
+
+Give tool names as strings (classes work too); names are resolved on every request so code reloading keeps
+working. Param types are `:string`, `:integer`, `:number`, `:boolean`, `:array`, `:object`. The tool name is the
+underscored class name without its namespace (`lookup_invoice`); override with `tool_name "other"`.
+
+`replay :safe` lets pi run the tool again if the sidecar crashed mid-call. Leave tools that change the world
+`:unsafe`.
+
+At boot (and on `DurableAgent.client.reload_tools`) the sidecar fetches `GET /durable_agent/tools`. Each call is a
+`POST /durable_agent/tools/:name`, authenticated with the shared token. Inside `call`,
+`DurableAgent::Current.conversation_id` and `.call_id` say who asked. Return a string or anything JSON
+serialisable.
+
+Errors become an error result the model sees. Unknown or missing arguments (`ArgumentError`),
+`ActiveRecord::RecordNotFound` and `DurableAgent::Tool::Error` carry their message; raise the last to tell the model
+what went wrong:
+
+```ruby
+raise DurableAgent::Tool::Error, "Invoices before 2020 are archived; ask for a newer one"
+```
+
+Any other exception reaches the model only as `"<ErrorClass> while running <tool>"` and is reported to
+`Rails.error` in full, so messages carrying SQL, paths or secrets stay in your app.
+
+## Configuration
+
+```ruby
+DurableAgent.configure do |config|
+  config.model = "openai/gpt-6.1-sol"      # "provider/modelId"; "faux/faux-1" is a scripted offline model
+  config.tools = %w[ LookupInvoice ]
+  config.host = "127.0.0.1"                # sidecar bind address
+  config.port = 4010
+  config.url = "http://127.0.0.1:4010"     # where Rails reaches the sidecar; defaults to host and port
+  config.rails_url = "http://127.0.0.1:3000"  # where the sidecar reaches Rails for tools and change events
+  config.token = "..."
+  config.workspace_root = "storage/durable_agent"
+  config.agent_name = "MyApp"              # shown on provider consent screens
+  config.parent_record_class = "ApplicationRecord"  # default "ActiveRecord::Base"
+  config.on_change = ->(conversation) { ... }
+  config.on_report = ->(report) { ... }
+  config.on_auth = ->(providers) { ... }
+end
+```
+
+Every setting the sidecar also reads defaults to its `DURABLE_AGENT_*` variable (`MODEL`, `HOST`, `PORT`,
+`RAILS_URL`, `TOKEN`, `WORKSPACE_ROOT`, `NAME`), so `DURABLE_AGENT_MODEL=faux/faux-1 bin/dev` moves both
+processes. A value set in the initializer wins over the variable, which is why the generated initializer leaves
+`config.model` commented out.
+
+A conversation pins the model it was started with (`DurableAgent.start(model:)`, else the default) and keeps it
+when the default changes; `conversation.model` reads it. The faux model is registered on every sidecar, so
+conversations from a `faux/faux-1` session still answer after the switch to a real provider.
+
+If your `ApplicationRecord` uses `connects_to` (roles, shards), set `config.parent_record_class =
+"ApplicationRecord"` in the initializer, so the durable_agent models inherit it and follow role switching.
+
+The token is read from `credentials.durable_agent.token`, then `ENV["DURABLE_AGENT_TOKEN"]`. In development and
+test it falls back to a value derived from `secret_key_base`, so both processes agree with no setup. In
+production a missing or blank token raises where it is used (starting the sidecar, the engine's endpoints, the
+client), not at boot, so `db:migrate` and `console` work without one.
+
+The token is also the key for stored provider sign-ins (see [Provider sign-in](#provider-sign-in)). Rotating it, or
+moving from the development fallback to a real token, makes the stored sign-ins unreadable: the sidecar logs a
+warning per provider, treats them as signed out, and users must sign in again.
+
+```sh
+bin/rails credentials:edit
+# durable_agent:
+#   token: <output of `bin/rails secret`>
+```
+
+## Running the processes
+
+```
+web: bin/rails server -p 3000
+sidecar: bin/rails durable_agent:sidecar
+```
+
+`durable_agent:sidecar` derives the sidecar's whole environment from Rails (`DurableAgent::Sidecar.env`):
+`DATABASE_URL` from the primary database in `database.yml` (`postgres://…` with `sslmode`, `sslrootcert`,
+`sslcert`, `sslkey` and `schema_search_path` carried over, or `sqlite:///absolute/path`), the token, bind address, Rails URL, model and agent name, and passes
+`OPENAI_API_KEY` / `ANTHROPIC_API_KEY` through. It then replaces itself with `node sidecar/dist/sidecar.js` (or
+the TypeScript source when no bundle is built). Run exactly one sidecar per app.
+
+The sidecar refuses to boot until the tables exist ("run bin/rails db:migrate"). An unknown default model is
+logged and the sidecar keeps running. Missing provider credentials are not an error: inputs settle as
+unanswered with reason `no_model` until someone signs in.
+
+SQLite suits development, test and single-host production: both processes open the same file (WAL, 5 s busy
+timeout, as Rails 8 configures it). Use Postgres when the web and sidecar processes run on different hosts.
+
+`sslmode=require` means "encrypt, but do not verify the certificate" to libpq (and Rails), while node-postgres
+reads it as full verification and would refuse the self-signed certificates many hosted databases use. The
+sidecar is therefore given `sslmode=no-verify`, node-postgres' name for the same thing, whether `require` comes
+from `database.yml` or from `DATABASE_URL`. `verify-ca` and `verify-full` pass through and verify, against
+`sslrootcert` when you set it.
+
+### Production
+
+The sidecar calls Rails over plain HTTP at `rails_url` (loopback by default). If you use `config.force_ssl`,
+keep `/durable_agent` out of the HTTPS redirect; if you set `config.hosts`, allow the sidecar's host. In
+`config/environments/production.rb`:
+
+```ruby
+config.ssl_options = { redirect: { exclude: ->(request) { request.path.start_with?("/durable_agent") } } }
+config.hosts << "127.0.0.1"
+```
+
+## How it works
+
+pi-durable's storage lives in your database. The sidecar runs pi-durable's own storage core over these tables,
+so there is one copy of the state and nothing to keep in sync:
+
+| Table | Holds | Model |
+|---|---|---|
+| `durable_agent_conversations` | one row per conversation, including ones tools created (`owner_conversation_id`) | `Conversation` |
+| `durable_agent_entries` | the immutable transcript | `Entry` |
+| `durable_agent_tasks` | durable work: runs, tool calls, compactions | `Task` |
+| `durable_agent_submissions` | every input Rails sent, from queued to done or unanswered | `Submission` |
+| `durable_agent_documents`, `_document_revisions` | conversation documents (`pi.live`, `pi.inbox`, `pi.agent`, ...) | `Document`, `Document::Revision` |
+| `durable_agent_record_ids`, `_durable_schema`, `_durable_metadata` | pi-durable's bookkeeping | |
+| `durable_agent_reports` | faults the harness reported | `Report` |
+| `durable_agent_credentials` | provider sign-ins, encrypted; Rails has no model for it | |
+| `durable_agent_settings` | `device_id`, `schema_version` | |
+
+Rails owns the schema: the migration creates every table and the sidecar never runs DDL. The sidecar owns the
+rows: every model is read-only, and a write from Rails would bypass the harness. Ids are pi's own. Records keep
+pi-durable's shapes as JSON text (`record`, `content`, `info`), and a few indexed columns are JSON-encoded
+strings (`kind`, `request_id`, `key_value`); the models decode them, and scopes such as `for_request` and
+`of_kind` encode their arguments. Kind filtering on entries (`visible`, `of_kind`) happens in Ruby and returns
+arrays. On boot the sidecar re-attaches every conversation and re-awaits unsettled submissions, so a crash loses
+nothing that was committed.
+
+pi-durable stores a document as a base revision plus deltas. The sidecar folds every delta into a new base
+before it commits, so **a document's current value is the content of its newest base revision**, which is what
+`Document#value` and `conversation.document(kind)` read. A document whose newest revision is a delta (a
+rewindable document that does not checkpoint) raises `DurableAgent::Document::HistoryNotSupported`; none of the
+`pi.*` documents Rails reads do.
+
+After each commit the sidecar posts the ids it touched to `POST /durable_agent/events`
+(`{"conversations": [7], "reports": [3], "auth": ["openai"]}`), authenticated with `Authorization: Bearer
+<token>`. Puma calls `config.on_change(conversation)` and `config.on_report(report)` for each id that exists, and
+`config.on_auth(providers)` when sign-ins changed. The defaults broadcast Turbo refreshes: `on_change` to the
+conversation; `on_report` to the report's conversation, or to the `"durable_agent:reports"` stream when it has
+none (an operator page can `turbo_stream_from "durable_agent:reports"`); `on_auth` to `"durable_agent:auth"`.
+Replace them to broadcast your own partials or to notify other systems. While a model streams, change events
+arrive up to every 100 ms, and a page refresh is a full GET each time; an app that cares sends one Turbo Stream
+message replacing the regions that change (the transcript, the streaming answer, the composer) with
+`method: :morph`, so the browser keeps focus, open details and the draft message:
+
+```ruby
+config.on_change = ->(conversation) { Chat.changed(conversation) }   # see the slopdep example app's Chat#broadcast_changes
+```
+
+Callback errors go to `Rails.error` and never fail the request. Because the broadcast
+happens inside Puma, the default `async` cable adapter works in development. Events are a hint, debounced and
+retried once: the state is already in the database, and the next event or page load shows anything a dropped
+event missed.
+
+## Testing your app
+
+durable_agent ships test support. In `test/test_helper.rb`:
+
+```ruby
+require "durable_agent/test_helper"
+
+class ActiveSupport::TestCase
+  include DurableAgent::TestHelper
+end
+```
+
+`fake_sidecar` answers `create_conversation`, `submit` and `abort` the way the sidecar does: it commits the
+conversation or the queued submission row first, then answers with its id, so `DurableAgent.start` and
+`conversation.say` find their rows inside the test's transaction. Submissions are idempotent on `request_id`, and
+an unknown conversation raises the sidecar's 404. `stub_sidecar` replaces any client call with a value, a
+callable or an exception; both record calls in `sidecar_calls`. Once stubbed, the client is sealed: a call the
+test did not stub raises `DurableAgent::Unavailable` instead of reaching a sidecar that happens to be running.
+
+```ruby
+test "sending a message" do
+  fake_sidecar(auth: CONNECTED)              # CONNECTED / DISCONNECTED are sample DurableAgent.auth answers
+
+  chat = Chat.create!                        # your code calls DurableAgent.start
+  chat.conversation.say("Hi", request_id: 1)
+
+  assert_equal 1, sidecar_calls(:submit).size
+  assert chat.conversation.submissions.for_request(1).sole.pending?
+end
+
+test "the sidecar is down" do
+  stub_sidecar(submit: DurableAgent::Unavailable)
+  # ...
+end
+```
+
+Rows for the harness tables can also come from fixtures under `test/fixtures/durable_agent/`. Use
+`DurableAgent::IndexedString.encode` for the JSON-encoded columns (`kind`, `key_value`, `request_id`).
+
+## Limits of v1
+
+- One sidecar per app, one set of provider credentials for the whole app (no per-user credentials).
+- No compaction, reset or task-graph routes; no SSE event stream; no usage endpoint.
+- A forked conversation's inherited entries are not followed: `entries` are its own.
+- No UI: the engine only serves the tool and event endpoints the sidecar calls.
+- No MCP. Tools are Ruby classes only.
+- The workspace root is reserved for built-in tools and unused.
+
+## Development
+
+```sh
+(cd sidecar && npm install)        # enables the round-trip test
+rake test                          # SQLite (test/dummy/storage/test.sqlite3); builds the dummy app's CSS first
+DURABLE_AGENT_DB=postgres bin/rails db:create
+DURABLE_AGENT_DB=postgres bin/rails test   # Postgres: durable_agent_test
+bundle exec rake test:all          # both
+```
+
+The round-trip test boots the real sidecar on `faux/faux-1` against the test database; it skips when
+`sidecar/node_modules` is missing or `node` is not on the PATH.
+
+Package the gem with `bundle exec rake build` (or `rake release`): it bundles the sidecar into
+`sidecar/dist/sidecar.js`, which is not checked in, before packaging. A bare `gem build` refuses to run without
+the bundle. Changes go in `CHANGELOG.md` under Unreleased.
+
+## License
+
+MIT

data/lib/durable_agent/account.rb

@@ -0,0 +1,29 @@
+module DurableAgent
+  # Whose provider credentials a conversation runs on: an app-chosen string, typically a user id. On the sidecar an
+  # account scopes the provider id, so "openai@u42" is account u42's OpenAI and "openai@u42/gpt-6.1-sol" its model
+  # ref. A provider id without "@" is the app's own.
+  module Account
+    PATTERN = /\A[A-Za-z0-9_.-]{1,64}\z/
+
+    class << self
+      # nil for the app's own account; raises ArgumentError for a value outside PATTERN.
+      def normalize(value)
+        return if value.blank?
+
+        value.to_s.tap do |account|
+          raise ArgumentError, "invalid account #{account.inspect}" unless PATTERN.match?(account)
+        end
+      end
+
+      def scoped(provider, account)
+        account ? "#{provider}@#{account}" : provider.to_s
+      end
+
+      # "openai@u42" => ["openai", "u42"]; "openai" => ["openai", nil].
+      def parse(scoped_provider)
+        provider, account = scoped_provider.to_s.split("@", 2)
+        [ provider, account.presence ]
+      end
+    end
+  end
+end

data/lib/durable_agent/client.rb

@@ -0,0 +1,121 @@
+require "net/http"
+require "json"
+
+module DurableAgent
+  class Error < StandardError
+    attr_reader :status, :body
+
+    def initialize(status = nil, body = nil, message = nil)
+      @status, @body = status, body
+      super(message || "sidecar returned #{status}: #{body.is_a?(Hash) ? body["error"] || body.to_json : body}")
+    end
+  end
+
+  # 409: the conversation is running and the submission asked to be rejected rather than queued.
+  class Busy < Error; end
+
+  # 422 on conversation creation: the model id is not one pi knows.
+  class UnknownModel < Error
+    def suggestions = body.is_a?(Hash) ? Array(body["suggestions"]) : []
+  end
+
+  # The sidecar is not running, did not answer in time, or went away mid-response.
+  class Unavailable < Error; end
+
+  # The sidecar's HTTP API v1. Rails sends commands here and reads the results from the harness tables.
+  class Client
+    UNREACHABLE = [ Errno::ECONNREFUSED, Errno::ECONNRESET, Errno::EHOSTUNREACH, Errno::EPIPE, Net::OpenTimeout, Net::ReadTimeout,
+      SocketError, EOFError, IOError ]
+
+    def initialize(url: nil, token: nil)
+      @url, @token = url, token
+    end
+
+    def url = @url || DurableAgent.config.url
+    def token = @token || DurableAgent.config.token
+
+    def health = get("/health")
+
+    # `model` is "provider/modelId" or {provider:, modelId:}. With `account` the conversation runs on that account's
+    # credentials: its model's provider becomes "provider@account".
+    def create_conversation(model: nil, instructions: nil, account: nil)
+      post("/conversations", { model: model_payload(model), instructions: instructions, account: account&.to_s }.compact)
+    rescue Error => error
+      raise UnknownModel.new(error.status, error.body) if error.status == 422
+      raise
+    end
+
+    def submit(conversation_id, content, request_id:, when_busy: nil)
+      post("/conversations/#{conversation_id}/submissions",
+        { content: content, request_id: request_id.to_s, when_busy: when_busy&.to_s }.compact)
+    end
+
+    def abort(conversation_id) = post("/conversations/#{conversation_id}/abort")
+
+    # `provider` is the base id ("openai"); `account` scopes it. A login's id names its account, so the calls that
+    # take one need none.
+    def auth(account: nil) = get(scoped("/auth", account))
+    def set_api_key(provider, key, account: nil) = put(scoped("/auth/#{provider}/api_key", account), { key: key })
+    def start_login(provider, account: nil) = post(scoped("/auth/#{provider}/logins", account))
+    def login(provider, id) = get("/auth/#{provider}/logins/#{id}")
+    def complete_login(provider, id, url) = post("/auth/#{provider}/logins/#{id}/callback", { url: url })
+    def cancel_login(provider, id) = delete("/auth/#{provider}/logins/#{id}")
+    def logout(provider, account: nil) = delete(scoped("/auth/#{provider}", account))
+
+    def reload_tools = post("/tools/reload")
+
+    private
+      def get(path) = request(Net::HTTP::Get.new(path))
+      def delete(path) = request(Net::HTTP::Delete.new(path))
+      def post(path, body = {}) = request(Net::HTTP::Post.new(path), body)
+      def put(path, body = {}) = request(Net::HTTP::Put.new(path), body)
+
+      def scoped(path, account)
+        account.nil? ? path : "#{path}?#{URI.encode_www_form(account: account)}"
+      end
+
+      def request(http_request, body = nil)
+        http_request["Authorization"] = "Bearer #{token}"
+        http_request["Accept"] = "application/json"
+        if body
+          http_request["Content-Type"] = "application/json"
+          http_request.body = body.to_json
+        end
+
+        uri = URI(url)
+        response = Net::HTTP.start(uri.host, uri.port, use_ssl: uri.scheme == "https", open_timeout: 5, read_timeout: 15) do |http|
+          http.request(http_request)
+        end
+
+        body = parse(response.body)
+        error = body["error"] if body.is_a?(Hash)
+        # Until the harness has resumed (after tools load) the sidecar answers commands with 503 "starting".
+        raise Unavailable.new(503, body, "sidecar is starting") if response.code == "503" && error == "starting"
+        # Ruby validates accounts before sending them, so this is a programming error rather than a sidecar failure.
+        raise ArgumentError, "invalid account" if response.code == "422" && error == "invalid_account"
+
+        case response
+        when Net::HTTPSuccess then body || {}
+        when Net::HTTPConflict then raise Busy.new(response.code.to_i, body)
+        else raise Error.new(response.code.to_i, body)
+        end
+      rescue *UNREACHABLE => error
+        raise Unavailable.new(nil, nil, "sidecar unreachable at #{url}: #{error.message}")
+      end
+
+      def parse(body)
+        JSON.parse(body) if body.present?
+      rescue JSON::ParserError
+        body
+      end
+
+      def model_payload(model)
+        case model
+        when nil, Hash then model
+        else
+          provider, model_id = model.to_s.split("/", 2)
+          { provider: provider, modelId: model_id }
+        end
+      end
+  end
+end

data/lib/durable_agent/configuration.rb

@@ -0,0 +1,81 @@
+module DurableAgent
+  class Configuration
+    class MissingToken < StandardError; end
+
+    attr_writer :model, :tools, :url, :rails_url, :token, :host, :port, :workspace_root, :agent_name,
+      :parent_record_class, :on_change, :on_report, :on_auth
+
+    # Defaults come from the same DURABLE_AGENT_* variables the sidecar reads, so `DURABLE_AGENT_PORT=4020 bin/dev`
+    # moves both halves at once.
+    def model = @model || env("MODEL", "openai/gpt-6.1-sol")
+    def host = @host || env("HOST", "127.0.0.1")
+    def port = @port || env("PORT", 4010).to_i
+    def url = @url || "http://#{host}:#{port}"
+    def rails_url = @rails_url || env("RAILS_URL", "http://127.0.0.1:3000")
+    def workspace_root = @workspace_root || env("WORKSPACE_ROOT", Rails.root.join("storage/durable_agent").to_s)
+    def agent_name = @agent_name || env("NAME", Rails.application.class.module_parent_name)
+
+    # The class DurableAgent::ApplicationRecord inherits from. An app whose ApplicationRecord uses connects_to sets
+    # it to "ApplicationRecord", so the harness models follow its roles and shards. Read when the models load, so
+    # set it in an initializer.
+    def parent_record_class = @parent_record_class || "ActiveRecord::Base"
+
+    # Entries may be classes or class names. Names are resolved on every call so they survive code reloading.
+    def tools
+      Array(@tools).map { |tool| tool.is_a?(String) ? tool.constantize : tool }
+    end
+
+    def tool(name)
+      tools.find { |tool| tool.tool_name == name.to_s }
+    end
+
+    # Both halves read this: Rails to authenticate the sidecar's calls and talk to it, the rake task to start it.
+    # Development and test derive one from secret_key_base so nothing needs setting up. A blank token would let
+    # an empty Authorization header through, so it is refused rather than compared.
+    def token
+      @token = default_token if @token.nil?
+      raise MissingToken, "DurableAgent.config.token is blank" if @token.blank?
+      @token
+    end
+
+    # Called from Puma when the sidecar posts a change event for the conversation.
+    def on_change
+      @on_change || ->(conversation) { Turbo::StreamsChannel.broadcast_refresh_to(conversation) }
+    end
+
+    # A report without a conversation (a failed session, most reports on pi-durable 1.3.0) refreshes the pages
+    # subscribed with `turbo_stream_from "durable_agent:reports"`.
+    def on_report
+      @on_report || ->(report) { Turbo::StreamsChannel.broadcast_refresh_to(report.conversation || "durable_agent:reports") }
+    end
+
+    # Called with the provider ids when a sign-in completes or a provider signs out, scoped for accounts
+    # ("openai", "openai@u42"). The default refreshes the pages subscribed with `turbo_stream_from
+    # DurableAgent.auth_stream`, such as a settings page, and with `turbo_stream_from
+    # DurableAgent.auth_stream(account)` for each account named.
+    def on_auth
+      @on_auth || ->(providers) do
+        accounts = providers.filter_map { |provider| DurableAgent::Account.parse(provider).second }.uniq
+        [ nil, *accounts ].each { |account| Turbo::StreamsChannel.broadcast_refresh_to(DurableAgent.auth_stream(account)) }
+      end
+    end
+
+    private
+      def env(name, default)
+        ENV["DURABLE_AGENT_#{name}"].presence || default
+      end
+
+      def default_token
+        Rails.application.credentials.dig(:durable_agent, :token).presence ||
+          ENV["DURABLE_AGENT_TOKEN"].presence ||
+          derived_token ||
+          raise(MissingToken, "Set credentials.durable_agent.token or DURABLE_AGENT_TOKEN, or assign DurableAgent.config.token")
+      end
+
+      def derived_token
+        if Rails.env.local?
+          Rails.application.key_generator.generate_key("durable_agent/token", 32).unpack1("H*")
+        end
+      end
+  end
+end

data/lib/durable_agent/current.rb

@@ -0,0 +1,6 @@
+module DurableAgent
+  # Set while a tool runs, so the tool (and anything it calls) knows which conversation asked.
+  class Current < ActiveSupport::CurrentAttributes
+    attribute :conversation_id, :call_id
+  end
+end

data/lib/durable_agent/engine.rb

@@ -0,0 +1,7 @@
+require "turbo-rails"
+
+module DurableAgent
+  class Engine < ::Rails::Engine
+    isolate_namespace DurableAgent
+  end
+end