llm.rb 9.0.0 → 11.0.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 197ff330dc5e414f4f9291835fbcdeece4450ee3a8d3748e4f9cf28a46db07b1
-  data.tar.gz: 3020a4511134f292ed38c6fc826b157f05cc31c722e9fe52692b8b2f705551c7
+  metadata.gz: 24c3c2930dd3ab321999075b34ef2e5c6d445fec5c873b00ef071caeef3c1406
+  data.tar.gz: 0d6921f20dc327f7c424f7282ff3c76f5073ad3eec7f21d483ee7623e4c782f7
 SHA512:
-  metadata.gz: 41f733d7d5b8a329420497f85c289f070f9016cf4d1bfdf5c5e49e274714310f5285e5598d4d27f5daa84cf26e837f311541ac8526bd987d7c7d917eb60eca21
-  data.tar.gz: f751b3887bd380e8f911106bedf6a0c606bcdc813ea4d7b01f2f332311ddd974c6dcfe838c7db5446d1683844ffbf379b2f5c8ef4b94459bedefaafc70be2098
+  metadata.gz: 3b96ea3336114822ccb2defee4da43089df6e004cebdf27987562f7f339bc2a733cc169d64f9752cc51d0346a069ba3921e99db69c2de1f795abfa69f260a730
+  data.tar.gz: b4135fad5bd1c5499b1177c27d6eb9c2da5a84b50a5492e82fe6396821c2b4a5e0891e55cb557d07e5ee4ec912b7ecdd8c7df223ebe76109aa74b7ede5227195

data/CHANGELOG.md

@@ -2,6 +2,184 @@
 
 ## Unreleased
 
+## v11.0.0
+
+Changes since `v10.0.0`.
+
+This release removes several deprecated or unused APIs, including the `#chat`
+alias from contexts and agents, the `LLM::Function#register` alias, and the
+unused positional `llm` argument from MCP constructors. Generated MCP and A2A
+tools are no longer added to the global tool registry by default.
+
+On the additions side, it introduces the A2A (Agent2Agent) protocol client,
+a new `#ask` convenience interface on contexts and agents, one-shot stdio MCP
+requests outside `#session`, `LLM::Function#def` as a short alias for
+`LLM::Function#define`, `LLM::File#exist?`, and `LLM::Tool.a2a?`.
+
+### Breaking
+
+* **Remove the unused `llm` argument from MCP clients** <br>
+  Remove the unused positional `llm` argument from `LLM::MCP.new`,
+  `LLM::MCP.stdio`, `LLM::MCP.http`, and `LLM.mcp`.
+
+* **Stop globally registering generated MCP and A2A tools** <br>
+  Generated tools returned by `LLM::Tool.mcp(...)` and
+  `LLM::Tool.a2a(...)` are no longer added to the global
+  `LLM::Tool.registry` or `LLM::Function.registry`. They still work
+  when passed directly to a context or agent, but registry-based lookup
+  now only sees normal loaded `LLM::Tool` subclasses.
+
+* **Remove `LLM::Function#register`** <br>
+  Remove the `LLM::Function#register` alias and prefer
+  `LLM::Function#define` or `LLM::Function#def` when binding a
+  function to its implementation. The `register` alias was too easy to
+  confuse with the class-level `LLM::Tool.register` and
+  `LLM::Function.register` registry APIs.
+
+* **Remove the `#chat` alias from contexts and agents** <br>
+  Remove the `LLM::Context#chat` and `LLM::Agent#chat` aliases. Prefer
+  `#talk` for all context and agent turns.
+
+### Add
+
+* **Add `LLM::Function#def`** <br>
+  Add `LLM::Function#def` as a short alias for
+  `LLM::Function#define` when binding a function instance to its
+  implementation.
+
+* **Add `LLM::MCP#session`** <br>
+  Add `LLM::MCP#session` as an alias for `LLM::MCP#run`, and prefer it
+  in examples for scoped stdio MCP sessions that should stay alive
+  across discovery and tool calls.
+
+* **Add `#ask` to contexts and agents** <br>
+  Add `LLM::Context#ask` and `LLM::Agent#ask` as a RubyLLM-compatible
+  convenience interface over `#talk`. `#ask` accepts a prompt, optional
+  `with:` attachments, an optional `stream:` target, and an optional
+  block for streamed chunks, and returns an `LLM::Response`.
+
+* **Add `LLM::File#exist?`** <br>
+  Add `LLM::File#exist?` as a small convenience wrapper for checking
+  whether a local file exists on disk.
+
+* **Allow one-shot stdio MCP requests outside `#session`** <br>
+  Allow `mcp.tools`, `mcp.prompts`, `mcp.find_prompt(...)`, and
+  `mcp.call_tool(...)` to work outside `mcp.session` by starting and
+  stopping a stdio transport on demand when needed. This makes stdio
+  MCP usable without an explicit session block, while keeping
+  `mcp.session` as the preferred pattern for efficient, stateful
+  stdio workflows.
+
+* **Add A2A client support** <br>
+  Add `LLM::A2A`, a client for the Agent2Agent (A2A) protocol with
+  REST and JSON-RPC bindings. Remote agent skills can be exposed as
+  `LLM::Tool` classes and used through `LLM::Context` or `LLM::Agent`,
+  and the client also supports direct messaging, streaming, task
+  operations, push notification configuration, extended agent cards,
+  persistent HTTP transport selection, and optional REST `base_path`
+  prefixing.
+
+  Refactor shared MCP/A2A HTTP transport setup into
+  `LLM::Transport::Utils`, and extend
+  `LLM::Transport::StreamDecoder` to accept a callback block directly.
+
+* **Add `LLM::Tool.a2a?`** <br>
+  Add `LLM::Tool.a2a?` and mark generated A2A-backed tool classes so
+  callers can distinguish them from local or MCP tools.
+
+### Fix
+
+* **Fix context and agent JSON serialization through `LLM.json`** <br>
+  Fix `LLM::Context#to_json` and `LLM::Agent#to_json` to serialize
+  through `LLM.json.dump(...)` instead of plain `to_json`. 
+
+* **Fix block-form ORM agent DSL forwarding** <br>
+  Fix block-form `model { ... }`, `tools { ... }`, and
+  `schema { ... }` declarations in the ActiveRecord and Sequel agent
+  wrappers so persisted agent models configure the internal agent class
+  the same way as `LLM::Agent`.
+
+* **Fix missing `skills` in ORM agent wrappers** <br>
+  Fix the ActiveRecord and Sequel agent wrappers to expose `skills`, so
+  persisted agent models can declare skills the same way as
+  `LLM::Agent`.
+
+* **Fix `acts_as_agent#ctx` return type** <br>
+  Fix the ActiveRecord `acts_as_agent` wrapper so its `ctx` helper
+  returns the wrapped `LLM::Agent` instead of returning the underlying
+  `LLM::Context` directly.
+
+## v10.0.0
+
+Changes since `v9.0.0`.
+
+This release removes the `LLM::Context#respond` method, and
+also removes the deprecated `LLM::Bot` alias. **All** class-level
+agent tunables can now be resolved lazily via a Symbol (method name),
+or a Proc. The `LLM::Agent` class can now confirm a tool call
+before it happens, and the `LLM::Schema` class has been extended
+to support `Array[String,Integer]` as a shorthand for
+`Array[AnyOf[String, Integer]]`. The `LLM::Stream` class has
+had its public method surface reduced to help avoid accidental
+collisions.
+
+### Breaking
+
+* **Unify context turns under `#talk`** <br>
+  Remove `LLM::Context#respond` and route responses-mode turns through
+  `LLM::Context#talk` with `mode: :responses` instead.
+
+* **Remove the `LLM::Bot` alias** <br>
+  Remove the backward-compatible `LLM::Bot` alias for `LLM::Context`.
+  Use `LLM::Context` directly instead.
+
+### Add
+
+* **Add shared option resolution through `LLM::Utils`** <br>
+  Add `LLM::Utils.resolve_option` for resolving configured values as
+  literals, procs, symbol-named methods, or duplicated hashes, and use
+  it in agent and ORM option resolution paths.
+
+* **Resolve all class-level agent tunables via Proc** <br>
+  Let `model`, `tools`, `skills`, `schema`, `stream`, and `tracer`
+  declared with a block be lazily evaluated against the agent instance
+  at initialization time, matching how `stream` and `tracer` already
+  worked.
+
+  Add `LLM::Agent#params` for direct access to the underlying context
+  parameters.
+
+  Ported from mruby-llm.
+
+* **Support `Array[...]` schema and tool param types** <br>
+  Let `LLM::Schema` properties and `LLM::Tool` params accept
+  `Array[...]` type declarations, including mixed item unions that are
+  serialized as `anyOf` array items.
+
+* **Add `LLM::Provider#key?`** <br>
+  Add `key?` to providers so callers can check whether a non-blank API
+  key has been configured.
+
+* **Add agent tool confirmation hooks** <br>
+  Add `LLM::Agent.confirm` and `LLM::Agent#on_tool_confirmation` so
+  selected tools can be approved or cancelled before execution. Pending
+  tool resolution now relies on `LLM::Context#functions` so confirmed
+  tools are not executed twice when mixed with unconfirmed tool calls.
+
+* **Add `LLM::Function#spawn(:call).wait`** <br>
+  Add task-shaped sequential execution support for direct
+  `LLM::Function#spawn(:call).wait`.
+
+### Fix
+
+* **Reduce private internal methods on `LLM::Stream`** <br>
+  Remove `tool_not_found` and `__tools__` from `LLM::Stream`. The
+  `__tools__` logic is inlined directly into `__find__` since that
+  was its only caller. The `tool_not_found` utility method was unused
+  externally and added unnecessary surface to LLM::Stream.
+
+  Ported from mruby-llm.
+
 ## v9.0.0
 
 Changes since `v8.1.0`.
@@ -162,7 +340,7 @@ DSML tool-marker filtering in streamed text.
   blocks that Bedrock rejects.
 
 * **Suppress Bedrock DSML tool markers in streamed text** <br>
-  Filter `"<｜DSML｜function_calls"` markers out of streamed Bedrock
+  Filter `\"<｜DSML｜function_calls\"` markers out of streamed Bedrock
   assistant text so tool-call sentinels do not leak into user-visible
   output.
 
@@ -313,7 +491,7 @@ provider usage has been recorded yet.
   buffer API.
 
 * **Support percentage compaction token thresholds** <br>
-  Let `LLM::Compactor` accept `token_threshold:` values like `"90%"` so
+  Let `LLM::Compactor` accept `token_threshold:` values like `\"90%\"` so
   compaction can trigger at a percentage of the active model context
   window.
 
@@ -1096,7 +1274,7 @@ Changes since `v4.9.0`.
 
 - Add HTTP transport for MCP with `LLM::MCP::Transport::HTTP` for remote servers
 - Add JSON Schema union types (`any_of`, `all_of`, `one_of`) with parser integration
-- Add JSON Schema type array union support (e.g., `"type\": [\"object\", \"null\"]`)
+- Add JSON Schema type array union support (e.g., `\"type\": [\"object\", \"null\"]`)
 - Add JSON Schema type inference from `const`, `enum`, or `default` fields
 
 ### Change
@@ -1197,7 +1375,7 @@ Notable merged work in this range includes:
 - `Add rack + websocket example (#130)`
 - `feat(gemspec): add changelog URI (#136)`
 - `feat(function): alias ThreadGroup#wait as ThreadGroup#value (#62)`
-- README and screencast refresh across `#66`, `#67`, `#68`, `#71`, and
+- README and screencast refresh across `#66`, `#68`, `#71`, and
   `#72`
 - `chore(bot): update deprecation warning from v5.0 to v6.0`
 - `fix(deepseek): tolerate malformed tool arguments`

data/README.md

@@ -1,10 +1,18 @@
 <p align="center">
-  <a href="llm.rb"><img src="https://github.com/llmrb/llm.rb/raw/main/llm.png" width="200" height="200" border="0" alt="llm.rb"></a>
+  <a href="https://github.com/llmrb/llm.rb">
+    <img src="https://github.com/llmrb/llm.rb/raw/main/llm.png" width="200" height="200" border="0" alt="llm.rb">
+  </a>
 </p>
 <p align="center">
-  <a href="https://0x1eef.github.io/x/llm.rb?rebuild=1"><img src="https://img.shields.io/badge/docs-0x1eef.github.io-blue.svg" alt="RubyDoc"></a>
-  <a href="https://opensource.org/license/0bsd"><img src="https://img.shields.io/badge/License-0BSD-orange.svg?" alt="License"></a>
-  <a href="https://github.com/llmrb/llm.rb/tags"><img src="https://img.shields.io/badge/version-9.0.0-green.svg?" alt="Version"></a>
+  <a href="https://0x1eef.github.io/x/llm.rb?rebuild=1">
+    <img src="https://img.shields.io/badge/docs-0x1eef.github.io-blue.svg" alt="RubyDoc">
+  </a>
+  <a href="https://opensource.org/license/0bsd">
+    <img src="https://img.shields.io/badge/License-0BSD-orange.svg?" alt="License">
+  </a>
+  <a href="https://github.com/llmrb/llm.rb/tags">
+    <img src="https://img.shields.io/badge/version-11.0.0-green.svg?" alt="Version">
+  </a>
 </p>
 
 ## About
@@ -13,8 +21,9 @@ llm.rb is Ruby's most capable AI runtime.
 
 It runs on Ruby's standard library by default. loads optional pieces
 only when needed, and offers a single runtime for providers, agents,
-tools, skills, MCP, streaming, files, and persisted state. As a bonus,
-llm.rb is also [available for mruby](https://github.com/llmrb/mruby-llm).
+tools, skills, MCP, A2A (Agent2Agent), RAG (vector stores & embeddings),
+streaming, files, and persisted state. As a bonus, llm.rb is also
+[available for mruby](https://github.com/llmrb/mruby-llm).
 
 It supports OpenAI, OpenAI-compatible endpoints, Anthropic, Google
 Gemini, DeepSeek, xAI, Z.ai, AWS Bedrock, Ollama, and llama.cpp. It
@@ -64,6 +73,36 @@ agent = LLM::Agent.new(llm, stream: $stdout)
 agent.talk "Hello world"
 ```
 
+#### Agents (Advanced)
+
+An agent can be configured to require confirmation before a tool is
+executed. When a matching tool is called, llm.rb runs
+`on_tool_confirmation`. That callback must decide whether to cancel the
+tool call or approve it and execute it by calling
+`fn.spawn(strategy).wait`, and it must always return an instance of
+[`LLM::Function::Return`](https://0x1eef.github.io/x/llm.rb/LLM/Function/Return.html):
+
+```ruby
+require "llm"
+
+class Agent < LLM::Agent
+  tools DeleteFile
+  confirm "delete-file"
+
+  def on_tool_confirmation(fn, strategy)
+    path = fn.arguments["path"] || fn.arguments[:path]
+    if path.start_with?("/tmp/")
+      fn.spawn(strategy).wait
+    else
+      fn.cancel(reason: "Deletion requires approval")
+    end
+  end
+end
+
+llm = LLM.openai(key: ENV["KEY"])
+Agent.new(llm, stream: $stdout).talk("Delete /tmp/example.txt.")
+```
+
 #### Tools
 
 The
@@ -96,7 +135,9 @@ or
 [LLM::Agent](https://0x1eef.github.io/x/llm.rb/LLM/Agent.html).
 In this example, the MCP server runs over stdio and
 [LLM::Context](https://0x1eef.github.io/x/llm.rb/LLM/Context.html)
-uses the same tool loop as local tools:
+uses the same tool loop as local tools. For **stdio**, `mcp.session`
+is the preferred pattern because it keeps one MCP session alive across
+discovery and tool calls:
 
 ```ruby
 require "llm"
@@ -104,20 +145,96 @@ require "llm"
 llm = LLM.openai(key: ENV["KEY"])
 mcp = LLM::MCP.stdio(argv: ["ruby", "server.rb"])
 
-mcp.run do
+mcp.session do
   ctx = LLM::Context.new(llm, stream: $stdout, tools: mcp.tools)
   ctx.talk "Use the available tools to inspect the environment."
   ctx.talk(ctx.wait(:call)) while ctx.functions?
 end
 ```
 
+MCP can also be used without `session`. Although it works it is generally
+not recommended for the **stdio** transport because it is inefficient
+to start and stop a fresh MCP process for tool discovery and each tool
+call:
+
+```ruby
+require "llm"
+
+llm = LLM.openai(key: ENV["KEY"])
+mcp = LLM::MCP.stdio(argv: ["ruby", "server.rb"])
+
+ctx = LLM::Context.new(llm, tools: mcp.tools)
+ctx.talk("Use the available tools to inspect the environment.")
+ctx.talk(ctx.wait(:call)) while ctx.functions?
+```
+
+The HTTP transport can be used with or without the `session` method,
+and unlike the stdio transport it can remain efficient without the
+`session` method through a persistent connection pool that is available
+through the [LLM::Transport.net_http_persistent](https://0x1eef.github.io/x/llm.rb/LLM/Transport.html#method-c-net_http_persistent) transport:
+
+```ruby
+require "llm"
+
+llm = LLM.openai(key: ENV["KEY"])
+mcp = LLM::MCP.http(
+  url: "https://remote-mcp.example.com",
+  transport: LLM::Transport.net_http_persistent
+)
+
+ctx = LLM::Context.new(llm, tools: mcp.tools)
+ctx.talk("Use the available tools to inspect the environment.")
+ctx.talk(ctx.wait(:call)) while ctx.functions?
+```
+
+#### A2A (Agent 2 Agent)
+
+The
+[LLM::A2A](https://0x1eef.github.io/x/llm.rb/LLM/A2A.html)
+object lets llm.rb use skills provided by a remote A2A agent. Those
+skills are exposed through the same runtime as local tools, so you can
+pass them to either
+[LLM::Context](https://0x1eef.github.io/x/llm.rb/LLM/Context.html)
+or
+[LLM::Agent](https://0x1eef.github.io/x/llm.rb/LLM/Agent.html).
+
+Use remote skills as local tools:
+
+```ruby
+require "llm"
+
+a2a = LLM::A2A.rest(
+  url: "https://remote-agent.example.com",
+  headers: {"Authorization" => "Bearer token"}
+)
+llm = LLM.openai(key: ENV["KEY"])
+ctx = LLM::Context.new(llm, tools: a2a.skills)
+ctx.talk "Analyze this CSV and summarize the trends."
+ctx.talk(ctx.wait(:call)) while ctx.functions?
+```
+
+Use persistent HTTP connections:
+
+```ruby
+require "llm"
+
+a2a = LLM::A2A.rest(
+  url: "https://remote-agent.example.com",
+  transport: LLM::Transport.net_http_persistent
+)
+```
+
+For more on direct messaging, task operations, push notification
+configs, and JSON-RPC, see the
+[LLM::A2A API docs](https://0x1eef.github.io/x/llm.rb/LLM/A2A.html).
+
 #### Skills
 
 Skills are reusable instructions loaded from a `SKILL.md` directory. They let
-you package behavior and tool access together, and they plug into the same
-runtime as tools, agents, and MCP. When a skill runs, llm.rb spawns a
-subagent with the skill instructions, access to only the tools listed in the
-skill, and recent conversation context:
+you package behavior and tool access together, and they plug into the
+same runtime as tools, agents, MCP, and A2A. When a skill runs, llm.rb
+spawns a subagent with the skill instructions, access to only the tools
+listed in the skill, and recent conversation context:
 
 ```yaml
 ---
@@ -239,6 +356,27 @@ ctx2.restore(string:)
 ctx2.talk "What is my favorite language?"
 ```
 
+#### ask
+
+[`LLM::Context`](https://0x1eef.github.io/x/llm.rb/LLM/Context.html)
+also provides `ask`, a convenience interface that is compatible with
+RubyLLM's `ask` method. It accepts a prompt, an optional `with:`
+attachment path or paths, an optional `stream:` target, and an optional
+block that chunks are yielded to. It returns an
+[`LLM::Response`](https://0x1eef.github.io/x/llm.rb/LLM/Response.html),
+so use `.content` when you want the text directly:
+
+```ruby
+require "llm"
+
+llm = LLM.openai(key: ENV["KEY"])
+ctx = LLM::Context.new(llm)
+
+puts ctx.ask("Hello world").content
+puts ctx.ask("Summarize this document.", with: "README.md").content
+ctx.ask("Stream this reply.") { $stdout << _1 }
+```
+
 ## Installation
 
 ```bash
@@ -249,7 +387,10 @@ gem install llm.rb
 
 #### REPL
 
-This example uses [`LLM::Context`](https://0x1eef.github.io/x/llm.rb/LLM/Context.html) directly for an interactive REPL. <br> See the [deepdive (web)](https://0x1eef.github.io/x/llm.rb/file.deepdive.html) or [deepdive (markdown)](resources/deepdive.md) for more examples.
+This example uses [`LLM::Context`](https://0x1eef.github.io/x/llm.rb/LLM/Context.html)
+directly for an interactive REPL. <br> See the
+[deepdive (web)](https://0x1eef.github.io/x/llm.rb/file.deepdive.html) or
+[deepdive (markdown)](resources/deepdive.md) for more examples.
 
 ```ruby
 require "llm"
@@ -274,17 +415,18 @@ or [`ctx.remote_file(...)`](https://0x1eef.github.io/x/llm.rb/LLM/Context.html#r
 Those tagged objects carry the metadata the provider adapter needs to turn one
 Ruby prompt into the provider-specific multimodal request schema.
 
-`ctx.local_file(path)` tags a local path as a `:local_file` object around
-`LLM.File(path)`. If the model understands that file type, you can include it
-directly in the prompt array instead of uploading it first through a provider
-Files API:
+If the model understands that file type, you can attach a local file directly
+with `ctx.ask(..., with: path)` instead of uploading it first through a
+provider Files API. Under the hood, llm.rb tags the path as a
+[`ctx.local_file(...)`](https://0x1eef.github.io/x/llm.rb/LLM/Context.html#local_file-instance_method)
+object:
 
 ```ruby
 require "llm"
 
 llm = LLM.openai(key: ENV["KEY"])
 ctx = LLM::Context.new(llm)
-ctx.talk ["Summarize this document.", ctx.local_file("README.md")]
+puts ctx.ask("Summarize this document.", with: "README.md").content
 ```
 
 #### Context Compaction
@@ -299,7 +441,9 @@ compactor can also use its own `model:` if you want summarization to run on a
 different model from the main context. `token_threshold:` accepts either a
 fixed token count or a percentage string like `"90%"`, which resolves
 against the active model context window and triggers compaction once total
-token usage goes over that percentage. See the [deepdive (web)](https://0x1eef.github.io/x/llm.rb/file.deepdive.html) or [deepdive (markdown)](resources/deepdive.md) for more examples.
+token usage goes over that percentage. See the
+[deepdive (web)](https://0x1eef.github.io/x/llm.rb/file.deepdive.html) or
+[deepdive (markdown)](resources/deepdive.md) for more examples.
 
 ```ruby
 require "llm"
@@ -328,7 +472,15 @@ ctx = LLM::Context.new(
 
 #### Reasoning
 
-This example uses [`LLM::Stream`](https://0x1eef.github.io/x/llm.rb/LLM/Stream.html) with the OpenAI Responses API so reasoning output is streamed separately from visible assistant output. See the [deepdive (web)](https://0x1eef.github.io/x/llm.rb/file.deepdive.html) or [deepdive (markdown)](resources/deepdive.md) for more examples.
+This example uses [`LLM::Stream`](https://0x1eef.github.io/x/llm.rb/LLM/Stream.html)
+with the OpenAI Responses API so reasoning output is streamed separately from
+visible assistant output. See the
+[deepdive (web)](https://0x1eef.github.io/x/llm.rb/file.deepdive.html) or
+[deepdive (markdown)](resources/deepdive.md) for more examples.
+
+To use the Responses API (OpenAI-specific), initialize a
+context or agent with `mode: :responses` and keep using
+`talk` for turns.
 
 ```ruby
 require "llm"
@@ -356,7 +508,10 @@ ctx.talk("Solve 17 * 19 and show your work.")
 
 #### Request Cancellation
 
-Need to cancel a stream? llm.rb has you covered through [`LLM::Context#interrupt!`](https://0x1eef.github.io/x/llm.rb/LLM/Context.html#interrupt-21-instance_method). <br> See the [deepdive (web)](https://0x1eef.github.io/x/llm.rb/file.deepdive.html) or [deepdive (markdown)](resources/deepdive.md) for more examples.
+Need to cancel a stream? llm.rb has you covered through
+[`LLM::Context#interrupt!`](https://0x1eef.github.io/x/llm.rb/LLM/Context.html#interrupt-21-instance_method).
+<br> See the [deepdive (web)](https://0x1eef.github.io/x/llm.rb/file.deepdive.html)
+or [deepdive (markdown)](resources/deepdive.md) for more examples.
 
 ```ruby
 require "llm"
@@ -377,7 +532,14 @@ worker.join
 
 #### Sequel (ORM)
 
-The `plugin :llm` integration wraps [`LLM::Context`](https://0x1eef.github.io/x/llm.rb/LLM/Context.html) on a `Sequel::Model` and keeps tool execution explicit. Like the ActiveRecord wrappers, its built-in persistence contract is the serialized `data` column, while `provider:` resolves a real `LLM::Provider` instance and `context:` injects defaults such as `model:`. <br> See the [deepdive (web)](https://0x1eef.github.io/x/llm.rb/file.deepdive.html) or [deepdive (markdown)](resources/deepdive.md) for more examples.
+The `plugin :llm` integration wraps
+[`LLM::Context`](https://0x1eef.github.io/x/llm.rb/LLM/Context.html) on a
+`Sequel::Model` and keeps tool execution explicit. Like the ActiveRecord
+wrappers, its built-in persistence contract is the serialized `data` column,
+while `provider:` resolves a real `LLM::Provider` instance and `context:`
+injects defaults such as `model:`. <br> See the
+[deepdive (web)](https://0x1eef.github.io/x/llm.rb/file.deepdive.html) or
+[deepdive (markdown)](resources/deepdive.md) for more examples.
 
 ```ruby
 require "llm"
@@ -412,7 +574,8 @@ one serialized `data` column. If your app has provider, model, or usage
 columns, provide them to llm.rb through `provider:` and `context:` instead of
 relying on reserved wrapper columns.
 
-See the [deepdive (web)](https://0x1eef.github.io/x/llm.rb/file.deepdive.html) or [deepdive (markdown)](resources/deepdive.md) for more examples.
+See the [deepdive (web)](https://0x1eef.github.io/x/llm.rb/file.deepdive.html)
+or [deepdive (markdown)](resources/deepdive.md) for more examples.
 
 ```ruby
 require "llm"
@@ -468,7 +631,8 @@ manages tool execution for you. Like `acts_as_llm`, its built-in persistence
 contract is one serialized `data` column. If your app has provider or model
 columns, provide them to llm.rb through your hooks and agent DSL.
 
-See the [deepdive (web)](https://0x1eef.github.io/x/llm.rb/file.deepdive.html) or [deepdive (markdown)](resources/deepdive.md) for more examples.
+See the [deepdive (web)](https://0x1eef.github.io/x/llm.rb/file.deepdive.html)
+or [deepdive (markdown)](resources/deepdive.md) for more examples.
 
 ```ruby
 require "llm"
@@ -521,7 +685,12 @@ end
 
 #### MCP
 
-This example uses [`LLM::MCP`](https://0x1eef.github.io/x/llm.rb/LLM/MCP.html) over HTTP so remote GitHub MCP tools run through the same `LLM::Context` tool path as local tools. It expects a GitHub token in `ENV["GITHUB_PAT"]`. See the [deepdive (web)](https://0x1eef.github.io/x/llm.rb/file.deepdive.html) or [deepdive (markdown)](resources/deepdive.md) for more examples.
+This example uses [`LLM::MCP`](https://0x1eef.github.io/x/llm.rb/LLM/MCP.html)
+over HTTP so remote GitHub MCP tools run through the same
+`LLM::Context` tool path as local tools. It expects a GitHub token in
+`ENV["GITHUB_PAT"]`. See the
+[deepdive (web)](https://0x1eef.github.io/x/llm.rb/file.deepdive.html) or
+[deepdive (markdown)](resources/deepdive.md) for more examples.
 
 ```ruby
 require "llm"
@@ -534,26 +703,9 @@ mcp = LLM::MCP.http(
   persistent: true
 )
 
-mcp.start
 ctx = LLM::Context.new(llm, stream: $stdout, tools: mcp.tools)
 ctx.talk("Pull information about my GitHub account.")
 ctx.talk(ctx.wait(:call)) while ctx.functions?
-mcp.stop
-```
-
-For scoped work, `mcp.run do ... end` is shorter and handles cleanup for you:
-
-```ruby
-mcp = LLM::MCP.http(
-  url: "https://api.githubcopilot.com/mcp/",
-  headers: {"Authorization" => "Bearer #{ENV["GITHUB_PAT"]}"},
-  persistent: true
-)
-mcp.run do
-  ctx = LLM::Context.new(llm, stream: $stdout, tools: mcp.tools)
-  ctx.talk("Pull information about my GitHub account.")
-  ctx.talk(ctx.wait(:call)) while ctx.functions?
-end
 ```
 
 ## Resources