riffer-rig 0.11.0 → 0.12.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 5f79d98c522224290937a01b701fa7f4ac72f2be08fbbb39abf32f06691880f7
-  data.tar.gz: 3c66dbd81e98e86b1c1132094431e0803d23c757a950684c6663ad5abd8c3369
+  metadata.gz: 04c27f5bf6e9339d06df9f64501e3b3dac5fa4724b0272a29641b0d9b707f788
+  data.tar.gz: a89ddd0ef08516f50c3ea42c2374ff7ff80ea78b55ba1ed8a561851df6280745
 SHA512:
-  metadata.gz: 6087cb7527548ca826bf04ab3b214c36ab29e18c676c62f7df84377010bb47fddae9e88b1354d1fa8815efa4967d4599ccc63e022c57660a567b58e226554679
-  data.tar.gz: 2aae83bea0978c35b33674149527c0281baeb33f7bf186ba38d9b6abdeb905a3649989eae97430d7eae6284a80a253152d0532c8ba3d75f3ae3d7adee6f6a757
+  metadata.gz: 11115efca8ca651cf9d1211c0c17e112e4369ce72f606c0c3886e1caae0c3a5b48b281f298a88481fdfff630eb57b19b2de2aa2dffbb9ef3e01a23fe0fa32a11
+  data.tar.gz: f0548a971011eb9b8439de4237bdeaf61803867a2a692f02cf37ea8f69e6ddb1f4492e5fb5e49fe81d95ac3b379909383ca15949822e5e50f2c39c4686cf77b7

data/CHANGELOG.md

@@ -1,5 +1,16 @@
 # Changelog
 
+## [0.12.0](https://github.com/bottrall/riffer-rig/compare/v0.11.0...v0.12.0) (2026-10-07)
+
+
+### Features
+
+* --json streams every Runtime event as NDJSON ([#231](https://github.com/bottrall/riffer-rig/issues/231)) ([a5e4641](https://github.com/bottrall/riffer-rig/commit/a5e464172cb84fcbfc2fbce0a311c070b54a539a))
+* /resume picker and /new in the terminal ([#232](https://github.com/bottrall/riffer-rig/issues/232)) ([140fbac](https://github.com/bottrall/riffer-rig/commit/140fbac7c7fc966987ee77c78222204bb755e37f))
+* ACP session/load and session/list ([#237](https://github.com/bottrall/riffer-rig/issues/237)) ([db81553](https://github.com/bottrall/riffer-rig/commit/db815536fa940d3f14615fa55b27af63164665ce))
+* resolve secret MCP headers from env and auth.json ([#234](https://github.com/bottrall/riffer-rig/issues/234)) ([6253f95](https://github.com/bottrall/riffer-rig/commit/6253f95932b81e276cec0850f7aa48abdb332b63))
+* riffer acp serves the Runtime over ACP ([#235](https://github.com/bottrall/riffer-rig/issues/235)) ([9497122](https://github.com/bottrall/riffer-rig/commit/9497122cc0cdac3576481f6efeda6e49f595d999))
+
 ## [0.11.0](https://github.com/bottrall/riffer-rig/compare/v0.10.0...v0.11.0) (2026-10-06)
 
 

data/README.md

@@ -1,8 +1,8 @@
 # riffer-rig
 
-A dead-simple terminal coding agent built on [riffer](https://github.com/janeapp/riffer).
+**riffer, in your terminal and in your process.**
 
-`riffer-rig` is an interactive terminal coding agent with read, write, edit, and bash tools — point it at your project and chat with it from the command line.
+`riffer-rig` is a general-purpose agent for Ruby developers who want to own their harness. It runs as a terminal agent and, because the runtime is separate from the terminal, it also runs inside any Ruby process: a Rails app, a script, a job. You extend it in Ruby: tools, commands, providers and hooks are ordinary Ruby classes on [riffer](https://github.com/janeapp/riffer)'s primitives, and the same objects work whether the host is the terminal or your app. It ships with a coding toolkit (read, write, edit, bash) as the default bundle, because a shell and file access are the most efficient way to get almost any task done — but the prompt gives it no coding identity. [Overview](docs/OVERVIEW.md) has the full thesis.
 
 ## Requirements
 
@@ -48,10 +48,10 @@ The model is the first of these that is set: `--model`, `RIFFER_MODEL`, `model`
 | `--max-steps N`         | stops a turn after `N` model calls                                          |
 | `--no-save`             | does not save this session to the [store](docs/SESSIONS.md)                 |
 | `-c`, `--continue`      | continues the most recent session in this directory ([Sessions](docs/SESSIONS.md#resuming)) |
-| `-r ID`, `--resume ID`  | resumes the session with id `ID` ([Sessions](docs/SESSIONS.md#resuming))    |
+| `-r ID`, `--resume ID`  | resumes the session with id `ID`; bare `-r` opens the [picker](docs/SESSIONS.md#the-picker) ([Sessions](docs/SESSIONS.md#resuming)) |
 | `-h`, `--help`          | prints the usage                                                            |
 
-`riffer acp` (an editor's agent over stdio) is reserved: for now it prints the usage and exits with status 2.
+An editor registers the agent as `riffer acp`, the same Runtimes over the [Agent Client Protocol](https://agentclientprotocol.com) on stdio ([ACP](docs/ACP.md)).
 
 ### Headless
 
@@ -63,7 +63,7 @@ git diff | riffer -p "review this diff"   # piped stdin appended as context
 echo "explain this diff" | riffer -p      # piped stdin alone is the prompt
 ```
 
-Everything loads exactly as the REPL does, the shared flags work the same — `-c` and `-r` included: `riffer -p -c "now run the tests"` continues the most recent session in this directory, and a missing session exits 2 ([Headless](docs/HEADLESS.md)). The session is saved like any other unless `--no-save`. Only the assistant's text is printed, streamed to stdout; errors and warnings go to stderr, and `--verbose` adds a one-line trace of each tool call there. Headless never prompts: a missing model, credential, or SDK prints the reason on stderr and exits 2.
+Everything loads exactly as the REPL does, the shared flags work the same — `-c` and `-r` included: `riffer -p -c "now run the tests"` continues the most recent session in this directory, and a missing session exits 2 ([Headless](docs/HEADLESS.md)). The session is saved like any other unless `--no-save`. Only the assistant's text is printed, streamed to stdout; errors and warnings go to stderr, and `--verbose` adds a one-line trace of each tool call there. With `--json`, stdout is instead one JSON object per line for every Runtime event — the NDJSON stream ([Headless](docs/HEADLESS.md#the-ndjson-stream---json)). Headless never prompts: a missing model, credential, or SDK prints the reason on stderr and exits 2.
 
 The exit code says how the turn ended: `0` finished, `1` runtime error, `2` usage or configuration, `3` the turn ended without completing (`--max-steps`, a full context window, a provider content filter), `130` SIGINT (the turn is cancelled first).
 
@@ -73,10 +73,15 @@ Type a prompt and press Enter; the reply streams in, with each tool call and the
 
 - Ctrl-C during a turn cancels it and returns to the prompt. Ctrl-C at the prompt asks for a second one, which exits.
 - `/exit` or `/quit` ends the session, as does Ctrl-D.
+- `/resume [--all]` opens the [session picker](docs/SESSIONS.md#the-picker): type to filter, switch with Enter on a single match or a row number, and delete with Ctrl-D and a confirm. `/new` starts a fresh session in place; the one you left stays on disk. Both replace the session the terminal drives and re-render the banner.
 - `/model provider/name` switches the model ([below](#switching-the-model)), and `/skill:<name> [text]` runs a skill ([Skills](docs/SKILLS.md)).
 - Any other `/name args` runs the Runtime command of that name, such as one an extension registers ([Extensions](docs/EXTENSIONS.md)); an unknown name is reported and nothing is sent to the model.
 
-### Authentication
+### Switching the model
+
+`/model provider/name` switches the model for the current session only, keeping the conversation so far — `/model openai/gpt-5`, say. The provider prefix is required: a bare name such as `/model sonnet` is rejected with the list of providers. `/model` alone shows the model in use. Switching runs the same setup for the new provider as startup does: its SDK gem is offered for install (or refused with the exact Gemfile line), and missing credentials are resolved — you are prompted for them when the host can ask, and the values apply to the running session immediately. The switch is refused with one error when the host cannot supply what is missing, and the model is left unchanged. `/model --save` writes the model in effect to the home `settings.json`, so new sessions start with it; `/model provider/name --save` switches and saves in one step, and a refused switch saves nothing ([Configuration](docs/CONFIGURATION.md#model)).
+
+## Authentication
 
 `riffer-rig` talks to the provider named by the model's prefix — `anthropic/claude-sonnet-4-6` means Anthropic. Provide that provider's credentials in either of two ways:
 
@@ -107,33 +112,92 @@ The flat `{"anthropic": "sk-…"}` shape earlier versions wrote is no longer rea
 
 Inside a session, `/auth` lists every provider with where its secret comes from — `env`, `stored`, `chain` (the SDK's own credential chain, for Bedrock) or `missing`. `/auth <provider>` re-runs that provider's setup, which is how you rotate a key, and applies the new values to the current session, so the next request uses them. `/auth remove <provider>` deletes the provider's `auth.json` entry and its `providers` block in settings.
 
-### Switching the model
+## Configuration
 
-`/model provider/name` switches the model for the current session only, keeping the conversation so far — `/model openai/gpt-5`, say. The provider prefix is required: a bare name such as `/model sonnet` is rejected with the list of providers. `/model` alone shows the model in use. Switching runs the same setup for the new provider as startup does: its SDK gem is offered for install (or refused with the exact Gemfile line), and missing credentials are resolved — you are prompted for them when the host can ask, and the values apply to the running session immediately. The switch is refused with one error when the host cannot supply what is missing, and the model is left unchanged. `/model --save` writes the model in effect to the home `settings.json`, so new sessions start with it; `/model provider/name --save` switches and saves in one step, and a refused switch saves nothing ([Configuration](docs/CONFIGURATION.md#model)).
+Settings live in two scopes, both optional: `~/.riffer/settings.json` for every project, and `<cwd>/.riffer/settings.json` for one project, merged key by key with the project winning ([Configuration](docs/CONFIGURATION.md)). Every core key is optional:
 
-### Configuration
+| Key          | What it sets                                                                     |
+| ------------ | -------------------------------------------------------------------------------- |
+| `model`      | the model new sessions start with, as `provider/name`                            |
+| `reasoning`  | the reasoning effort, translated to the provider's own parameter                 |
+| `models`     | prices each model in USD per million tokens                                      |
+| `providers`  | non-secret provider fields such as an endpoint or region (home file only)        |
+| `extensions` | `disabled` — bundled extensions to leave out; `autoload` — gem extension autoload |
+| `reload`     | `"auto"` (default) or `"manual"` — the hot-reload trigger                        |
+| `sessions`   | `save: false` stops saving sessions to the store                                 |
+| `tools`      | the provider-native tool switches (`native`), off by default                     |
 
-- `AGENTS.md` — `~/.riffer/AGENTS.md` and an `AGENTS.md` in the current working directory or any directory above it, whichever exist, are re-read every turn as instructions that take precedence over the default norms ([Instructions](docs/INSTRUCTIONS.md#agentsmd)).
-- Skills — Agent Skills in `.agents/skills/` from the current working directory up to the repository root, and in `~/.agents/skills/`, are offered to the model, and each can be run with `/skill:<name>` ([Skills](docs/SKILLS.md)).
 - `RIFFER_MODEL` — the model for this run as `provider/name`, winning over the `model` setting. A bare name such as `sonnet` is rejected with the list of providers.
-- `~/.riffer/settings.json` — optional user settings, and `<cwd>/.riffer/settings.json` for one project, merged key by key with the project winning. Every key is optional:
-
-  ```json
-  {
-    "model": "anthropic/claude-sonnet-4-6",
-    "reasoning": "low",
-    "models": {
-      "anthropic/claude-sonnet-4-6": {
-        "input": 3.0,
-        "output": 15.0,
-        "cache_write": 3.75,
-        "cache_read": 0.3
-      }
-    }
-  }
-  ```
-
-  `model` is the model new sessions start with; a host built on the [Loader](docs/EMBEDDING.md#building-a-runtime-with-the-loader) asks for one when none is set and writes the answer here. `extensions.disabled` (for example `["mcp"]`) leaves bundled extensions out. `models` prices each model in USD per million tokens; [Configuration](docs/CONFIGURATION.md) has every key. `reasoning` is translated to the provider's own parameter — Anthropic accepts `low`, `medium`, `high`, `xhigh` and `max`; OpenAI and OpenRouter accept `low`, `medium`, `high` and `xhigh`. Omitting it, or supplying an unrecognised value, leaves the model's default reasoning behaviour unchanged.
+- `AGENTS.md` — `~/.riffer/AGENTS.md` and an `AGENTS.md` in the current working directory or any directory above it are re-read every turn as instructions that take precedence over the default norms ([Instructions](docs/INSTRUCTIONS.md#agentsmd)).
+- Skills — Agent Skills in `.agents/skills/` from the working directory up to the repository root, and in `~/.agents/skills/`, are offered to the model, and `/skill:<name> [text]` runs one ([Skills](docs/SKILLS.md)).
+- MCP servers — declared under the `mcp` key in either settings file and registered with the Runtime ([MCP](docs/MCP.md)).
+
+## Extending
+
+An extension is a named registrar block in a `rig.rb` file — `~/.riffer/rig.rb` runs in every project, `<project>/.riffer/rig.rb` in one, and the first run of a project file asks you to trust it:
+
+```ruby
+Riffer::Rig.extension('git') do |rig|
+  # A tool the model can call
+  rig.tool GitLog
+
+  # A /log command in the session
+  rig.command('log', description: 'Recent commits') do |ctx|
+    ctx.say `git log --oneline -n #{ctx.args}`
+  end
+
+  # A section appended to the system message, re-read every turn
+  rig.prompt(:branch) { |ctx| "Branch: #{`git branch --show-current`}" }
+end
+```
+
+Tools, commands, prompt sections, event handlers, skills, MCP servers and providers register the same way, and the same objects work whether the host is the terminal or your app. [Extensions](docs/EXTENSIONS.md) has all eight seams, error isolation, and packaging an extension as a gem.
+
+## Embedding
+
+The runtime is separate from the terminal, so the same agent runs inside any Ruby process:
+
+```ruby
+runtime = Riffer::Rig::Loader.runtime(cwd: Dir.pwd, host: Riffer::Rig::Hosts::Null.new)
+response = runtime.ask('why is this test failing?')
+puts response.content
+```
+
+`Loader.runtime` applies the same filesystem conventions as the terminal — settings, credentials, `rig.rb`, skills. [Embedding](docs/EMBEDDING.md) has the streaming `prompt`, snapshots, and rebuilding after a code reload.
+
+## Documentation
+
+The guides, in reading order:
+
+Start here:
+
+- [Overview](https://riffer.bottrall.dev/guides/overview/) — What riffer-rig is, the four tiers, the runtime and host layers
+- [Getting started](https://riffer.bottrall.dev/guides/getting-started/) — Install, pick a model, first session
+
+Using the terminal:
+
+- [Configuration](https://riffer.bottrall.dev/guides/configuration/) — Settings scopes and every core key
+- [Instructions](https://riffer.bottrall.dev/guides/instructions/) — How the system message is built; AGENTS.md
+- [Tools](https://riffer.bottrall.dev/guides/tools/) — The bundled toolkit and provider-native tools
+- [Skills](https://riffer.bottrall.dev/guides/skills/) — Agent Skills directories and activation
+- [MCP](https://riffer.bottrall.dev/guides/mcp/) — Declaring MCP servers
+- [Sessions](https://riffer.bottrall.dev/guides/sessions/) — Saving, resuming, the picker, the JSONL store
+- [Reloading](https://riffer.bottrall.dev/guides/reloading/) — The /reload command, what reloads and what does not
+- [Headless](https://riffer.bottrall.dev/guides/headless/) — riffer -p, NDJSON, exit codes
+- [ACP](https://riffer.bottrall.dev/guides/acp/) — riffer acp, the ACP agent over stdio
+
+Extending and embedding:
+
+- [Extensions](https://riffer.bottrall.dev/guides/extensions/) — rig.rb, the registrar, the eight seams, commands, handlers, gems
+- [Embedding](https://riffer.bottrall.dev/guides/embedding/) — Runtime and Loader from Ruby; snapshots; rebuild
+- [Hosts](https://riffer.bottrall.dev/guides/hosts/) — The Host interface and writing a host
+
+Providers:
+
+- [Providers](https://riffer.bottrall.dev/guides/providers/overview/) — Model strings, precedence, credentials, /auth
+- [Custom providers](https://riffer.bottrall.dev/guides/providers/custom/) — Registering a provider from an extension; the setup, credentials, listings
+
+The guide sources are in `docs/`. To preview the site locally, run `bin/docs serve` and open <http://localhost:8000>.
 
 ## Development
 
@@ -150,7 +214,6 @@ Every project chore is a script in `bin/`. The Rakefile behind them is an implem
 | `bin/ci`        | Run everything CI runs, serially. Use before pushing                                           |
 | `bin/build`     | Build the gem into `pkg/`; the publish workflow runs this before `gem push`                    |
 | `bin/docs`      | Build the docs site and API reference into `_site/`; `bin/docs serve` serves it at http://localhost:8000 |
-| `bin/plans`     | Serve the building plans in `plans/` at http://localhost:8001                                  |
 
 ## Releasing
 
@@ -174,4 +237,4 @@ Licensed under the MIT License. See [`LICENSE.txt`](LICENSE.txt) for details.
 
 ## Maintainer
 
-- Jake Bottrall - https://github.com/bottrall
+- Jake Bottrall - https://github.com/bottrall

data/lib/riffer/rig/acp/host.rb

@@ -0,0 +1,83 @@
+# frozen_string_literal: true
+
+require 'acp/sdk'
+
+class Riffer::Rig::ACP::Host
+  CAPABILITIES = Set[:notify].freeze #: Set[Symbol]
+
+  # @rbs @client: ::ACP::AgentConnection::_Client
+  # @rbs @session_id: String?
+  # @rbs @buffered: Array[String]
+
+  # @rbs client: ::ACP::AgentConnection::_Client
+  # @rbs return: void
+  def initialize(client:)
+    @client = client
+    @session_id = nil
+    @buffered = []
+  end
+
+  # @rbs return: Set[Symbol]
+  def capabilities
+    CAPABILITIES
+  end
+
+  # @rbs question: String?
+  # @rbs options: Array[String]?
+  # @rbs secret: bool
+  # @rbs return: String?
+  def ask(question = nil, options: nil, secret: false)
+    nil
+  end
+
+  # @rbs question: String?
+  # @rbs return: bool
+  def confirm(_question = nil)
+    false
+  end
+
+  # @rbs message: String?
+  # @rbs level: Symbol
+  # @rbs return: void
+  def notify(message = nil, level: :info)
+    id = @session_id
+    return @buffered << message.to_s unless id
+
+    send_update(id, message.to_s)
+  end
+
+  # @rbs label: String?
+  # @rbs &block: ? () -> void
+  # @rbs return: void
+  def progress(label = nil, &block)
+    notify(label) if label
+    block&.call
+  end
+
+  # Session updates name their session, and acp-sdk runs session_created after
+  # the session/new reply so the client knows the id before any update for it
+  # arrives — that is why the build-time notifies wait for this, not for the
+  # Runtime's construction to end.
+  # @rbs id: String
+  # @rbs return: void
+  def session_id=(id)
+    @session_id = id
+    buffered = @buffered
+    @buffered = []
+    buffered.each { |message| send_update(id, message) }
+  end
+
+  private
+
+  # @rbs id: String
+  # @rbs message: String
+  # @rbs return: void
+  def send_update(id, message)
+    @client.update(
+      id,
+      ::ACP::Types::SessionUpdate::AgentMessageChunk.new(
+        content: ::ACP::Types::ContentBlock::Text.new(text: message)
+      )
+    )
+  end
+end

data/lib/riffer/rig/acp.rb

@@ -0,0 +1,353 @@
+# frozen_string_literal: true
+
+require 'acp/sdk'
+require 'time'
+
+# The ACP tier: Runtime events reach the client only through this adapter's
+# mapping, so nothing else in rig may translate an event into an ACP type.
+class Riffer::Rig::ACP
+  AGENT_NAME = 'riffer' #: String
+  AGENT_TITLE = 'Riffer' #: String
+
+  SESSION_EXTENSION = 'acp' #: String
+
+  TOOL_KINDS = {
+    'read' => ::ACP::Types::ToolKind::READ,
+    'write' => ::ACP::Types::ToolKind::EDIT,
+    'edit' => ::ACP::Types::ToolKind::EDIT,
+    'bash' => ::ACP::Types::ToolKind::EXECUTE
+  }.freeze #: Hash[String, String]
+
+  # @rbs @input: IO
+  # @rbs @output: IO
+  # @rbs @env: Riffer::Rig::Env | Riffer::Rig::Env::Invalid
+  # @rbs @home: String
+  # @rbs @build: ^(String, Riffer::Rig::Hosts::_Host, Hash[String, Riffer::Rig::Mcp::Declaration]) -> Riffer::Rig::Runtime
+  # @rbs @client: ::ACP::AgentConnection::_Client?
+  # @rbs @sessions: Hash[String, Riffer::Rig::Runtime]
+  # @rbs @hosts: Hash[String, Riffer::Rig::ACP::Host]
+  # @rbs @lock: Thread::Mutex
+
+  # @rbs input: IO
+  # @rbs output: IO
+  # @rbs env: Riffer::Rig::Env | Riffer::Rig::Env::Invalid
+  # @rbs home: String
+  # @rbs build: (^(String, Riffer::Rig::Hosts::_Host, Hash[String, Riffer::Rig::Mcp::Declaration]) -> Riffer::Rig::Runtime)?
+  # @rbs return: Riffer::Rig::ACP
+  def self.for(input:, output:, env:, home:, build: nil)
+    new(input: input, output: output, env: env, home: home, build: build)
+  end
+
+  # Builds the Runtime a session runs on: the client's MCP servers flow
+  # through the rig.mcp seam as a synthetic extension, so a reload rebuild
+  # re-declares them and a same-name declaration from an extension replaces
+  # them with the usual notify.
+  # @rbs cwd: String
+  # @rbs host: Riffer::Rig::Hosts::_Host
+  # @rbs servers: Hash[String, Riffer::Rig::Mcp::Declaration]
+  # @rbs env: Riffer::Rig::Env | Riffer::Rig::Env::Invalid
+  # @rbs home: String
+  # @rbs return: Riffer::Rig::Runtime
+  def self.build_runtime(cwd, host, servers, env:, home:)
+    extension = session_extension(servers)
+    Riffer::Rig::Loader.runtime(
+      cwd: cwd, host: host, env: env, home: home, extra_extensions: extension ? [extension] : []
+    )
+  end
+
+  # @rbs servers: Hash[String, Riffer::Rig::Mcp::Declaration]
+  # @rbs return: Riffer::Rig::Extension?
+  def self.session_extension(servers)
+    return nil if servers.empty?
+
+    Riffer::Rig::Extension.new(SESSION_EXTENSION) do |rig|
+      servers.each { |name, server| rig.mcp(name, command: server.command, args: server.args, env: server.env) }
+    end
+  end
+
+  # @rbs input: IO
+  # @rbs output: IO
+  # @rbs env: Riffer::Rig::Env | Riffer::Rig::Env::Invalid
+  # @rbs home: String
+  # @rbs build: (^(String, Riffer::Rig::Hosts::_Host, Hash[String, Riffer::Rig::Mcp::Declaration]) -> Riffer::Rig::Runtime)?
+  # @rbs return: void
+  def initialize(input:, output:, env:, home:, build: nil)
+    @input = input
+    @output = output
+    @env = env
+    @home = home
+    @build = build || ->(cwd, host, servers) { self.class.build_runtime(cwd, host, servers, env: @env, home: @home) }
+    @client = nil
+    @sessions = {}
+    @hosts = {}
+    @lock = Mutex.new
+  end
+
+  # Serves the connection until the client closes stdin; then the reader
+  # thread ends and run returns.
+  # @rbs return: Integer
+  def run
+    connection = ::ACP::AgentConnection.new(
+      transport: ::ACP::Transport::Stdio.new(input: @input, output: @output),
+      capabilities: ::ACP::Types::AgentCapabilities.new(
+        load_session: true,
+        session_capabilities: ::ACP::Types::SessionCapabilities.new(list: ::ACP::Types::SessionListCapabilities.new)
+      ),
+      agent_info: ::ACP::Types::Implementation.new(name: AGENT_NAME, version: Riffer::Rig::VERSION, title: AGENT_TITLE)
+    ) do |client|
+      @client = client
+      self
+    end
+    connection.start.join
+    0
+  end
+
+  # @rbs request: ::ACP::Types::NewSessionRequest
+  # @rbs return: (::ACP::Types::NewSessionResponse | ::ACP::RequestError)
+  def new_session(request)
+    host = Riffer::Rig::ACP::Host.new(client: client)
+    servers = declarations(request.mcp_servers, host)
+    runtime = @build.call(request.cwd, host, servers)
+    @lock.synchronize do
+      @sessions[runtime.id] = runtime
+      @hosts[runtime.id] = host
+    end
+    ::ACP::Types::NewSessionResponse.new(session_id: runtime.id)
+  rescue StandardError => e
+    ::ACP::RequestError.new(code: ::ACP::RequestError::INTERNAL_ERROR, message: e.message)
+  end
+
+  # @rbs request: ::ACP::Types::PromptRequest
+  # @rbs return: (::ACP::Types::PromptResponse | ::ACP::RequestError)
+  def prompt(request)
+    runtime = session(request.session_id)
+    return ::ACP::RequestError.resource_not_found unless runtime
+
+    # @type var stop_reason: Symbol?
+    stop_reason = nil
+    runtime.prompt(prompt_text(request.prompt)) do |event|
+      case event
+      when Riffer::StreamEvents::TextDelta
+        client.update(request.session_id, message_chunk(event.content))
+      when Riffer::StreamEvents::ToolCallDone
+        client.update(request.session_id, tool_call(event))
+      when Riffer::Rig::Events::TurnEnd
+        stop_reason = event.stop_reason
+      end
+    end
+    ::ACP::Types::PromptResponse.new(stop_reason: stop_reason_of(stop_reason))
+  rescue Riffer::Rig::Runtime::BusyError, Riffer::Rig::Runtime::ClosedError => e
+    ::ACP::RequestError.new(code: ::ACP::RequestError::INTERNAL_ERROR, message: e.message)
+  end
+
+  # The host takes the session id before the build, so a build-time notify
+  # still reaches the client as an update for this session.
+  # @rbs request: ::ACP::Types::LoadSessionRequest
+  # @rbs return: (::ACP::Types::LoadSessionResponse | ::ACP::RequestError)
+  def load_session(request)
+    host = Riffer::Rig::ACP::Host.new(client: client)
+    host.session_id = request.session_id
+    loader = Riffer::Rig::Loader.new(cwd: request.cwd, host: host, env: @env, home: @home)
+    runtime = loader.resume(request.session_id)
+    return ::ACP::RequestError.resource_not_found unless runtime
+
+    @lock.synchronize do
+      @sessions[request.session_id] = runtime
+      @hosts[request.session_id] = host
+    end
+    loader.messages(request.session_id)
+          .filter_map { |message| replay_of(message) }
+          .each { |update| client.update(request.session_id, update) }
+    ::ACP::Types::LoadSessionResponse.new
+  rescue StandardError => e
+    ::ACP::RequestError.new(code: ::ACP::RequestError::INTERNAL_ERROR, message: e.message)
+  end
+
+  # @rbs request: ::ACP::Types::ListSessionsRequest
+  # @rbs return: (::ACP::Types::ListSessionsResponse | ::ACP::RequestError)
+  def list_sessions(request)
+    loader = Riffer::Rig::Loader.new(
+      cwd: request.cwd || Dir.pwd,
+      host: Riffer::Rig::Hosts::Null.new,
+      env: @env,
+      home: @home
+    )
+    headers = request.cwd ? loader.list : loader.list(all: true)
+    sessions = headers.map do |header|
+      ::ACP::Types::SessionInfo.new(
+        session_id: header.id,
+        cwd: header.cwd,
+        title: header.title,
+        updated_at: header.updated&.utc&.iso8601
+      )
+    end
+    ::ACP::Types::ListSessionsResponse.new(sessions: sessions)
+  rescue StandardError => e
+    ::ACP::RequestError.new(code: ::ACP::RequestError::INTERNAL_ERROR, message: e.message)
+  end
+
+  # Runs on the transport's reader thread, so it only sets the cancel flag.
+  # @rbs notification: ::ACP::Types::CancelNotification
+  # @rbs return: void
+  def cancel(notification)
+    session(notification.session_id)&.cancel
+  end
+
+  # Runs after the session/new reply, so the client knows the id before any
+  # update for it arrives: the build-time notifies flush here, then the
+  # commands go out.
+  # @rbs response: ::ACP::Types::NewSessionResponse
+  # @rbs return: void
+  def session_created(response)
+    id = response.session_id
+    # @type var found: [Riffer::Rig::ACP::Host?, Riffer::Rig::Runtime?]
+    found = @lock.synchronize { [@hosts[id], @sessions[id]] }
+    host, runtime = found
+    return unless host && runtime
+
+    host.session_id = id
+    client.available_commands(id, available_commands(runtime))
+  end
+
+  private
+
+  # @rbs return: ::ACP::AgentConnection::_Client
+  def client
+    @client or raise 'ACP agent used before ::ACP::AgentConnection.start built it'
+  end
+
+  # @rbs id: String
+  # @rbs return: Riffer::Rig::Runtime?
+  def session(id)
+    @lock.synchronize { @sessions[id] }
+  end
+
+  # @rbs servers: Array[::ACP::Types::McpServer::t]
+  # @rbs host: Riffer::Rig::ACP::Host
+  # @rbs return: Hash[String, Riffer::Rig::Mcp::Declaration]
+  def declarations(servers, host)
+    servers.filter_map { |server| declaration_of(server, host) }.to_h
+  end
+
+  # @rbs server: ::ACP::Types::McpServer::t
+  # @rbs host: Riffer::Rig::ACP::Host
+  # @rbs return: [String, Riffer::Rig::Mcp::Declaration]?
+  def declaration_of(server, host)
+    unless server.is_a?(::ACP::Types::McpServerStdio)
+      host.notify("Skipped MCP server #{server_name(server)}: only stdio servers are supported", level: :warning)
+      return nil
+    end
+
+    [
+      server.name,
+      Riffer::Rig::Mcp::Declaration.new(command: server.command, args: server.args, env: stdio_env(server))
+    ]
+  end
+
+  # @rbs server: ::ACP::Types::McpServer::t
+  # @rbs return: String
+  def server_name(server)
+    case server
+    when ::ACP::Types::McpServer::Http, ::ACP::Types::McpServer::Sse then server.name
+    when Hash then server['name'].to_s
+    else 'unnamed'
+    end
+  end
+
+  # @rbs server: ::ACP::Types::McpServerStdio
+  # @rbs return: Hash[String, String]
+  def stdio_env(server)
+    server.env.to_h { |variable| [variable.name, variable.value] }
+  end
+
+  # Text and resource links are ACP's must-support prompt blocks; the client
+  # cannot send the others unless the agent advertised them.
+  # @rbs blocks: Array[::ACP::Types::ContentBlock::t]
+  # @rbs return: String
+  def prompt_text(blocks)
+    blocks.filter_map { |block| prompt_text_of(block) }.join("\n\n")
+  end
+
+  # @rbs block: ::ACP::Types::ContentBlock::t
+  # @rbs return: String?
+  def prompt_text_of(block)
+    case block
+    when ::ACP::Types::ContentBlock::Text then block.text
+    when ::ACP::Types::ContentBlock::ResourceLink then "#{block.title || block.name} #{block.uri}"
+    end
+  end
+
+  # @rbs content: String
+  # @rbs return: ::ACP::Types::SessionUpdate::AgentMessageChunk
+  def message_chunk(content)
+    ::ACP::Types::SessionUpdate::AgentMessageChunk.new(content: text_block(content))
+  end
+
+  # @rbs text: String
+  # @rbs return: ::ACP::Types::ContentBlock::Text
+  def text_block(text)
+    ::ACP::Types::ContentBlock::Text.new(text: text)
+  end
+
+  # @rbs message: Hash[Symbol, untyped]
+  # @rbs return: ::ACP::Types::SessionUpdate::t?
+  def replay_of(message)
+    case message[:role]
+    when 'user' then ::ACP::Types::SessionUpdate::UserMessageChunk.new(content: text_block(message[:content].to_s))
+    when 'assistant' then message_chunk(message[:content].to_s)
+    when 'tool' then replayed_tool_call(message)
+    end
+  end
+
+  # The stored result is all a replayed call has: the arguments live in the
+  # assistant message's tool_calls, so the title is the name alone.
+  # @rbs message: Hash[Symbol, untyped]
+  # @rbs return: ::ACP::Types::SessionUpdate::ToolCall
+  def replayed_tool_call(message)
+    name = message[:name].to_s
+    ::ACP::Types::SessionUpdate::ToolCall.new(
+      tool_call_id: message[:tool_call_id].to_s,
+      title: name,
+      name: name,
+      kind: TOOL_KINDS.fetch(name, ::ACP::Types::ToolKind::OTHER),
+      status: ::ACP::Types::ToolCallStatus::COMPLETED,
+      content: [::ACP::Types::ToolCallContent::Content.new(content: text_block(message[:content].to_s))]
+    )
+  end
+
+  # riffer's stream has no completion boundary for a tool call, so a call goes
+  # out once, in progress, when its arguments are complete.
+  # @rbs event: Riffer::StreamEvents::ToolCallDone
+  # @rbs return: ::ACP::Types::SessionUpdate::ToolCall
+  def tool_call(event)
+    ::ACP::Types::SessionUpdate::ToolCall.new(
+      tool_call_id: event.call_id,
+      title: "#{event.name}(#{event.arguments})",
+      name: event.name,
+      kind: TOOL_KINDS.fetch(event.name, ::ACP::Types::ToolKind::OTHER),
+      status: ::ACP::Types::ToolCallStatus::IN_PROGRESS
+    )
+  end
+
+  # riffer's failure reasons (:error, :other, :guardrail_blocked) have no ACP
+  # counterpart; refusal is the closest signal that the turn did not complete.
+  # @rbs stop_reason: Symbol?
+  # @rbs return: String
+  def stop_reason_of(stop_reason)
+    case stop_reason
+    when :completed then ::ACP::Types::StopReason::END_TURN
+    when Riffer::Rig::Runtime::INTERRUPT_CANCELLED then ::ACP::Types::StopReason::CANCELLED
+    when :max_steps then ::ACP::Types::StopReason::MAX_TURN_REQUESTS
+    when :context_window, :length, :content_filter, :malformed_output then ::ACP::Types::StopReason::MAX_TOKENS
+    else ::ACP::Types::StopReason::REFUSAL
+    end
+  end
+
+  # @rbs runtime: Riffer::Rig::Runtime
+  # @rbs return: Array[::ACP::Types::AvailableCommand]
+  def available_commands(runtime)
+    runtime.commands.map do |command|
+      ::ACP::Types::AvailableCommand.new(name: command.name, description: command.description)
+    end
+  end
+end

data/lib/riffer/rig/bundled/mcp.rb

@@ -3,7 +3,12 @@
 module Riffer::Rig::Bundled
   Mcp = Riffer::Rig::Extension.new('mcp') do |rig|
     rig.settings[:servers].to_h.each do |name, server|
-      rig.mcp(name.to_s, url: server.fetch(:url), headers: server[:headers].to_h.transform_keys(&:to_s))
+      rig.mcp(
+        name.to_s,
+        url: server.fetch(:url),
+        headers: server[:headers].to_h.transform_keys(&:to_s),
+        auth: Hash(server[:auth])
+      )
     end
   end #: Riffer::Rig::Extension
 end