durable_agent

Install, use

Install

bundle add durable_agent
bin/rails g durable_agent:install   # migration, initializer, mount, Procfile.dev line
bin/rails db:migrate                # twelve durable_agent_* tables
bin/dev                             # web, sidecar

Use

conversation = DurableAgent.start         # model from config
conversation.say("Summarize the invoice",
                 request_id: message.id)  # idempotent on request_id
conversation.transcript                   # pi-durable's own entries
conversation.busy?                        # the pi.live document

# in the view
turbo_stream_from conversation            # refresh broadcasts, morph

say is idempotent on request_id and returns the submission row, committed before the sidecar answers. Tools are Ruby classes (below). The app brings its own pg or sqlite3.

Why one database

pi-durable's storage core is portable: SQLite dialect over a small facade, with a conformance suite. The sidecar supplies the facade for SQLite and for Postgres and runs the unchanged core over the Rails tables.

Runtime shape

One sidecar per app. SQLite for development, test and one host. Postgres for the rest.

What a message does

The storage layer

SqliteStorage talks to a facade: exec, run, get, all, transaction, close, ? placeholders. The scheme of DATABASE_URL picks the adapter. Two wrappers sit on the resulting Storage.

SQLite to Postgres

db/translate.ts, 69 lines, memoized by SQL text. The gem's own SQL is written in the SQLite dialect and goes through it too.

Connections run in UTC. int8 parses to a number.

Rails owns the schema

The install migration creates twelve tables with adapter-neutral DDL. Nine are pi-durable 1.3.0's schema under the durable_agent_ prefix, same names, same indexes. Three are the gem's.

• text, not jsonb. jsonb rejects \u0000; one model output would kill a commit.
• bigint ids, no defaults. pi-durable mints them.
• No STRICT, no CHECK, no foreign keys, no seed rows. pi-durable validates and orders its own writes.

Boot

1. Record the gem's schema version.Missing table: stop with "run bin/rails db:migrate".
2. Check the harness tables.SELECT id FROM durable_agent_conversations LIMIT 0, else MissingSchema.
3. Seed the two singleton rows.ON CONFLICT DO NOTHING, so a schema.rb load boots.
4. Refuse a schema mismatch.Newer pi-durable schemas ship as gem migrations. The sidecar never migrates.
5. Open SqliteStorage under the prefix.Gem schema_version newer than the gem refuses; older warns.
6. Serve, load tools, then resume.Tools are fetched with retries for 60 s before the Harness resumes, so an interrupted replay-safe tool call reruns. Until then: 503 starting, resumed: false.
7. Supervise.A failed session or an uncaught exception exits 1. The supervisor restarts.

Two commit wrappers

The contract

Two version numbers in /health: the gem's schema (2) and pi-durable's (1). The sidecar ships inside the gem, so they always match. Everything but /health needs Authorization: Bearer, constant-time on both sides.

HTTP API (gem → sidecar)

Sidecar environment

bin/rails durable_agent:sidecar derives everything from Rails configuration and execs the bundle.

No harness file. Unknown default model: logged, sidecar runs. No credentials: runs settle unanswered. Missing tables: boot stops.

Who pays

Three arrangements. Each is a credential on an account and a conversation started on that account; the app picks per conversation.

The app pays

One credential for everyone: OPENAI_API_KEY in the environment, a key stored with connection.set_api_key, or the operator's Sign in with ChatGPT on the Settings page. Conversations start with DurableAgent.start. The operator's bill or plan carries every user. Right for an app with one operator, or one that bills its users itself.

Each user pays with an API key

The user pastes their own key; the app stores it with Connection.new("openai", account: user.id).set_api_key(key) and starts their conversations with DurableAgent.start(account: user.id). Usage lands on the user's OpenAI or Anthropic bill. No browser flow, no provider program.

Each user pays with their ChatGPT plan

The user signs in with ChatGPT through Connection.new("openai", account: user.id).start_login, approves the app in the browser, and their conversations run on the usage included in their plan, with limits they manage in ChatGPT settings. The app holds a refreshable token per user and never sees a key.

An app can mix them: a user with a credential runs on their account, the rest on the app's. DurableAgent.auth(account:) says which a user has.

Accounts

An account names whose credential a conversation runs on. It is an app-chosen string, typically a user id. The sidecar carries it in the provider id: openai@u42 is account u42's OpenAI, openai@u42/gpt-6.1-sol its model ref, and no @ is the app's own. pi-ai keys credentials, logins and auth checks by provider id, and each conversation pins its provider in pi.agent, so the three arrangements above share one mechanism.

The sidecar registers a clone of the base provider under the scoped id on demand and at boot from the credentials table: same catalog, same auth methods, one more credential row. The clone's models carry the scoped id, so pi-ai resolves the account's credential; each request goes to the base provider under its own id, so assistant entries record openai while pi.agent keeps openai@u42. An account never falls back to the app's OPENAI_API_KEY. A conversation on an account whose credential is gone settles model_error. Usage per account is the sum of pi.usage over its conversations.

Sign in with ChatGPT is pi-ai's OpenAI OAuth: a public client registered per login, scope chatgpt.tokens.use.direct, the token sent to the Responses API, usage drawn from the signed-in user's plan. The redirect is 127.0.0.1:1455: on the sidecar's host the listener completes the login; elsewhere the user pastes the final URL into the app.

Tools in Ruby

The sidecar fetches definitions and installs them as one extension. POST /tools/reload replaces it in place.

# app/tools/lookup_invoice.rb
class LookupInvoice < DurableAgent::Tool
  description "Fetch one invoice by number"
  param :number, :string, "Invoice number like INV-1042"
  replay :safe                        # no side effects; may rerun after a crash

  def call(number:)
    Invoice.find_by!(number:).as_json(only: %i[ number total status due_on ])
  end
end

# config/initializers/durable_agent.rb
DurableAgent.configure do |config|
  config.model = "openai/gpt-6.1-sol"
  config.tools = %w[ LookupInvoice ]  # class names survive code reloading
end

Reading the tables from Ruby

DurableAgent.start(model: nil, instructions: nil, account: nil)   # => Conversation, created on the sidecar
DurableAgent.conversation(id)
DurableAgent.auth(account: nil)                                   # => {"openai" => {"type" => "oauth"}, "anthropic" => nil}
DurableAgent.auth_stream(account)                                 # "durable_agent:auth:u42", for turbo_stream_from

conversation.say("Hello", request_id: message.id)                 # => Submission, the row exists
conversation.abort
conversation.transcript                                           # visible entries, oldest first
conversation.entries / submissions / tasks / reports / documents
conversation.live / busy? / streaming_message / running_tools / inbox / last_failure
conversation.model / provider / account / total_tokens / total_cost / usage_by_model
conversation.parent / parent_at
entry.text / tool_calls / model_ref / stop_reason / total_tokens / cost
entry.duration_ms / timestamp / failed? / error_message

connection = DurableAgent::Connection.new("openai", account: user.id)
connection.connected? / api_key? / subscription? / source
connection.set_api_key(key) / start_login / complete_login(id, url) / disconnect

Every model is readonly?. Ids are pi's. Records stay JSON text (attribute :record, :json). kind, data, model live in the record, so kind filters run in Ruby and return arrays.

on_change, on_report and on_auth default to Turbo::StreamsChannel.broadcast_refresh_to. The event names the conversation; the tables hold the rest.

In the box

durable_agent/
  lib/durable_agent.rb                   configure, config, client, start, conversation, auth
  lib/durable_agent/configuration.rb     defaults, callbacks, token chain
  lib/durable_agent/client.rb            Net::HTTP; Error, Busy, UnknownModel, Unavailable
  lib/durable_agent/tool.rb              description, param, replay, coercion
  lib/durable_agent/current.rb           conversation_id, call_id during a tool call
  lib/durable_agent/sidecar.rb           env and DATABASE_URL from Rails config, exec
  lib/durable_agent/message_text.rb      text and tool calls out of pi messages
  lib/durable_agent/indexed_string.rb    JSON.stringify-compatible encoding
  lib/durable_agent/test_helper.rb       stub_sidecar, fake_sidecar
  lib/generators/durable_agent/install/  migration, initializer
  app/models/durable_agent/              conversation, entry, task, submission, document,
                                         revision, report, connection
  app/controllers/durable_agent/         tools_controller, events_controller (bearer)
  sidecar/src/                           main, config, harness, storage, documents, events,
                                         server, auth, credentials, settings, reports, tools
  sidecar/src/db/                        index, sqlite, postgres, translate
  sidecar/dist/sidecar.js                one ~3 MB esbuild bundle, Node >= 22.19

Out of scope

• More than one sidecar. One process per app and database serves every user.
• Compaction, reset, task graph, SSE routes. pi-durable has them; no need yet.
• Forked conversations' inherited entries. entries are a conversation's own rows.
• A Ruby port of chord deltas. The base wrapper makes it unnecessary.
• UI, MCP. Tools are Ruby classes.

Decisions

• The sidecar never runs DDL. Migrations own every schema change, pi-durable's included.
• Boot fails early. Every step runs in one handler; any missing table is "run bin/rails db:migrate". Seeding before the version check lets a schema.rb load boot.
• The Harness closes the database. close is idempotent on both adapters.
• Postgres runs in UTC. -c TimeZone=UTC on every connection.
• Postgres needs CREATE on the schema. pi-durable's one CREATE TABLE IF NOT EXISTS, a no-op, still checks it.
• Rails index syntax reproduces pi-durable's indexes. order: { id: :desc }, where: "head IS NOT NULL", pi-durable's names.
• Rails' default primary keys. Rowid alias on SQLite, bigserial on Postgres, sequence unused. Conversations, entries, submissions get a created_at.
• One serial queue on Postgres, as on SQLite. Pool of two. The checked-out client has an error listener, so a dropped connection rejects the transaction, not the process. Only plain SELECTs retry.
• SQLite waits without stalling. 100 ms synchronous busy wait, then async retries of BEGIN IMMEDIATE up to 30 s.
• Shutdown has a deadline. 10 s for requests, 30 s total, second signal exits.
• Events are hints. Debounced, one retry, then dropped. The tables are correct without them.
• Bases exactly where the core keeps one revision. Rewindable documents keep deltas; HistoryNotSupported makes a violation loud.
• Accounts are provider ids. openai@u42 rides every path pi-ai and pi-durable already key by provider: credential rows, logins, the model pinned per conversation. No schema change, no pi-durable change.
• Small guarantees. Zero-setup tokens in development and test. Tools as class names survive reloading. A wrong default model does not take the service down.

Status

1. Storage over the app's database, both adapters, both wrappers.Done. 127 node:test cases on SQLite, 126 on Postgres, 24 of them pi-durable's conformance cases.
2. Ruby engine.Done. 207 Minitest runs per adapter, the example app's included, with a full schema comparison.
3. Round trip on each adapter.Done. The real sidecar on faux/faux-1 against the test database.
4. Installer, rake task, bundle.Done.
5. Resilience under real failures.Done. Backend terminated inside a transaction, SQLite lock held from another process, storage failure exiting 1, restart during a replay-safe tool call, failing reads around a commit.
6. A real app on the gem.Done. test/dummy is slopdep, a Nitro Kit chat app with three tools, a settings page and a morphing live page; it is the engine's dummy app and its tests are part of the gem's suite.
7. Accounts: scoped credentials, API keys, Sign in with ChatGPT per account.Done. Verified live against the HTTP API: an account's key reaches OpenAI (a 401 naming it), faux answers on an account, a per-account sign-in starts as openai@u42, a stored account credential survives a restart.
8. A real-provider run with a tool call.Done. gpt-6.1-sol on a Sign in with ChatGPT credential, in the slopdep app: the model called rename_chat and current_time through the Ruby tools endpoint, the renames landed on the app's rows, answers streamed into the morphing live region, and pi.usage recorded tokens and cost per conversation.

Known limitations

• A report raised while the Harness closes is lost.
• The default on_change refreshes the page, up to every 100 ms per streaming conversation. An app replaces regions instead: slopdep sends one morphing stream message per event for the transcript, the live answer and the composer.
• pi-durable 1.3.0 reports carry no conversation. They land on durable_agent:reports.
• A revoked OAuth credential reads as connected until a run fails. OpenAI rotates refresh tokens; one grant cannot serve two installations. The next message shows a model_error.
• Smaller. Demodulized tool names can collide; very long request ids or keys can exceed Postgres index limits; sslmode=prefer and allow mean full verification in node; the shutdown deadline and the uncaught-exception exit are untested.