llm.rb 16.0.0.pre.9 → 16.0.0

data/CHANGELOG.md

@@ -1,23 +1,25 @@
-<p align="center">
-  <a href="https://r.uby.dev">
-    <img
-      src="https://github.com/r-uby-dev/llm.rb/raw/main/rubydev.svg"
-      width="400"
-      height="200"
-      border="0"
-      alt="a r.uby.dev project"
-     >
-  </a>
-</p>
-
 > Changelog <br>
 > [r.uby.dev](https://r.uby.dev) project
 
-This file covers the v15 series and the unreleased changes that follow it.
-Releases before v15 are kept in [changelog/old.md](changelog/old.md).
+This file covers the v16 series. Releases up to and including v15 are kept in
+[changelog/old.md](changelog/old.md).
 
 ## What's next
 
+*No unreleased changes yet. Check back after the next release.*
+
+## v16.0.0
+
+Changes since `v15.5.0`.
+
+This release makes an interrupt precise: `LLM::Interrupt` moves outside
+`StandardError`, a turn between its requests ends where it is, and a cancel is
+delivered inside the tool that has to handle it. It also requires Ruby 3.4 or
+later, reads a `:jsonb` record's messages from the column, saves a
+record-backed conversation after each request, and adds
+`LLM::ActiveRecord#messages!`, `LLM::Stream#on_step`, and a tracer's
+`on_interrupt` hook.
+
 ### Breaking
 
 #### Migration
@@ -232,6 +234,17 @@ Releases before v15 are kept in [changelog/old.md](changelog/old.md).
   where a stream can checkpoint, and it fires once per successful request even
   when streaming is off.
 
+### Tools
+
+* **tools: wait for a command's status, not only for it to stop running** <br>
+  Fix a bug where an exec-backed tool could answer `ok: nil` for a command
+  that ran and printed its output.
+  [`LLM::Tool::Utils#wait`](https://r.uby.dev/api-docs/llm.rb/LLM/Tool/Utils.html#wait-instance_method)
+  left as soon as `running?` said the process was gone, and the status is not
+  decided at that moment, so `command.success?` was read before it had an
+  answer. It waits for the status now, and a command that was never found is
+  the exception, because there was nothing to reap.
+
 ### Tracers
 
 * **tracer: report a request that failed** <br>
@@ -253,1217 +266,3 @@ Releases before v15 are kept in [changelog/old.md](changelog/old.md).
   [`LLM::Context#wait`](https://r.uby.dev/api-docs/llm.rb/LLM/Context.html#wait-instance_method)
   now calls `on_interrupt` once when an interrupt unwinds through it, rather
   than once per tool, matching the single exception the caller receives.
-
-## v15.5.0
-
-Changes since `v15.4.1`.
-
-This release makes the exec-backed tools report how long a command ran, calls a
-tracer's `on_exit` hook once when the last scope ends, and resolves a `Proc`
-parameter type when a schema is serialized. It also fixes `LLM::Schema.to_s`
-for a schema with a deferred type.
-
-### Tools
-
-* **tools: report how long a command ran** <br>
-  [`LLM::Tool::Exec#call`](https://r.uby.dev/api-docs/llm.rb/LLM/Tool/Exec.html#call-instance_method)
-  now includes a `duration` field in its result, a string such as `"0.4 seconds"`
-  that reports how long the command took. The tools that route through `exec`
-  (`git`, `rg`, `mkdir`, `ruby`, and `bundle`) return it as well. A command that
-  was not found still returns the error hash, which has no `duration`.
-
-### Tracers
-
-* **tracer: call `on_exit` once, when the last scope ends** <br>
-  [`LLM::Tracer#on_exit`](https://r.uby.dev/api-docs/llm.rb/LLM/Tracer.html#on_exit-instance_method)
-  is a new hook, called once when the last scope that is open for a tracer
-  ends. A tracer that holds a connection, a file, or a span releases it here.
-  The count of open scopes belongs to the tracer rather than to the thread that
-  opened one, because a tool runs on a thread of its own and scopes the turn's
-  tracer while it does. Before this, a tool's scope looked like the outermost
-  one: a tracer that released its resource in `on_exit` lost it in the middle
-  of the turn, and the rest of the trace was written without it.
-
-### Schema
-
-* **schema: resolve a parameter type when the schema is serialized** <br>
-  [`LLM::Schema`](https://r.uby.dev/api-docs/llm.rb/LLM/Schema.html) and
-  [`LLM::Tool`](https://r.uby.dev/api-docs/llm.rb/LLM/Tool.html) accept a `Proc`
-  as the type of a parameter or a property, and the proc is called when the
-  schema is serialized rather than when the class that declares it is defined.
-  A type that is only known at runtime no longer has to be known at load time:
-  `parameter :kind, proc { Enum[*Article.kinds] }, "The article kind"` asks the
-  model for the values a store holds right now, and the proc runs again on the
-  next request, so it sees the values that are current then. Whatever the proc
-  returns is resolved in turn, so it may be a leaf, a class, or an array of
-  either, and the description, `required`, `default`, and `enum` given with the
-  parameter are applied to it.
-
-* **schema: keep `to_s` working for a deferred type** <br>
-  Fix a bug where a schema with a proc-typed property raised from
-  [`LLM::Schema.to_s`](https://r.uby.dev/api-docs/llm.rb/LLM/Schema.html#to_s-class_method)
-  (and so from `inspect` and `p`) because the placeholder resolved its leaf
-  through a private method that shadowed the one `LLM::Schema::Leaf#default`
-  uses. Serialization, and therefore the request sent to a provider, was
-  unaffected.
-
-## v15.4.1
-
-Changes since `v15.4.0`.
-
-This release removes the gemspec's post-install message, so installing the gem
-no longer prints the r.uby.dev notice. It also refreshes the model registry
-with current model listings, limits, and pricing.
-
-### Core
-
-* **remove the gemspec post install message** <br>
-  The gemspec no longer sets `post_install_message`, so installing the
-  gem no longer prints the r.uby.dev website notice.
-
-### Registry
-
-* **refresh model metadata** <br>
-  Update `data/` with current model listings, limits, and pricing for the
-  Alibaba, Bedrock, DeepSeek, Google, Moonshot, and OpenRouter registries.
-  Bedrock adds the Kimi K3 and GPT-6 Sol and GPT-6 Luna families in both
-  the global and US regions and raises the context limit to 1M tokens for
-  two models, while Moonshot raises the Kimi K3 output limit to 1M tokens.
-  OpenRouter adds `qwen/qwen3.8-max-prime`, `z-ai/glm-5.3-prime`,
-  `upstage/solar-mini4`, the Aion 3.5 models, and `stealth/space-bunny-alpha`,
-  drops `mistralai/devstral-2512` and a free Ling 3.0 Flash VL entry, and
-  reprices several DeepSeek and Mistral models.
-
-## v15.4.0
-
-Changes since `v15.3.0`.
-
-This release saves token usage with the context state, moves the retry budget
-onto the provider, groups a turn's spans under one trace, and lets an agent
-declare `name`, `description`, `path`, and `tool_budget` with a block. It also
-gives every tracer request an id, adds `LLM::ActiveRecord::Message`, reads
-`AGENTS.md` as the console's system prompt, removes `LLM::Guard::Loop`, and
-refreshes the model registry.
-
-### Core
-
-* **context: save token usage with the state** <br>
-  [`LLM::Context#to_h`](https://r.uby.dev/api-docs/llm.rb/LLM/Context.html#to_h-instance_method)
-  now writes `context_used` and `context_window`, so a saved state can be
-  inspected without loading the runtime. They are never read back, and a payload
-  without them still loads.
-
-### Provider
-
-* **provider: decide the retry budget on the provider** <br>
-  [`LLM::Provider#retry_budget`](https://r.uby.dev/api-docs/llm.rb/LLM/Provider.html#retry_budget-instance_method)
-  returns how many times a rate-limited request is retried before the error is
-  raised, and defaults to 5. An agent that sets no `retry_budget` of its own
-  now takes the budget from its provider instead of special-casing Alibaba, so
-  [`LLM::Alibaba`](https://r.uby.dev/api-docs/llm.rb/LLM/Alibaba.html)
-  still retries 8 times and a provider that recovers from rate limits slowly can
-  return a higher budget. An explicit `retry_budget:` still takes precedence.
-
-### Agent
-
-* **agent: group a turn's spans into one trace** <br>
-  [`LLM::Agent`](https://r.uby.dev/api-docs/llm.rb/LLM/Agent.html) now opens a
-  `llm.turn` trace group around every turn, so all spans a turn produces share
-  one trace id. It uses the agent's tracer when it has one, the provider's
-  otherwise; previously a provider-wide tracer split one turn across traces.
-
-* **agent: declare `name`, `description`, `path`, and `tool_budget` with a block** <br>
-  A block passed to any of these four class-level setters was previously
-  ignored, because the call was read as a getter. Now
-  [`LLM::Agent.name`](https://r.uby.dev/api-docs/llm.rb/LLM/Agent.html#name-class_method)
-  and [`LLM::Agent.description`](https://r.uby.dev/api-docs/llm.rb/LLM/Agent.html#description-class_method)
-  store the block, and an instance resolves it against itself, or against its
-  ORM record when it is bound to one. `name` and `description` also accept a
-  `Symbol` or a `Proc`, and the class-level reader still returns what was
-  configured, so read them on an instance for the resolved string.
-
-### Console
-
-* **console: use `AGENTS.md` as the system prompt** <br>
-  `bin/llm.rb` now looks for `AGENTS.md` in the current working directory when
-  it boots, and when the file exists its contents become the agent's
-  instructions for the session. The instructions are injected once, so a
-  resumed session that already has a system message keeps the one it has.
-
-* **console: stop a cancelled turn from crashing the console** <br>
-  A turn cancelled with Esc can still have chunks queued, and they arrive after
-  the buffer that renders them is closed. The streaming path then tried to
-  replace a row that no longer existed and raised.
-  [`LLM::Console::Buffer`](https://r.uby.dev/api-docs/llm.rb/LLM/Console/Buffer.html)
-  now reports whether it has a row to replace through `open?`, the stream drops
-  chunks that arrive for a closed buffer, and `replace` keeps the current text
-  instead of raising.
-
-### Guard
-
-* **guard: remove `LLM::Guard::Loop`** <br>
-  `LLM::Guard::Loop` is removed. It stopped repeated tool-call patterns, but
-  could also interrupt a loop that was making progress, so it did not hold up as
-  a default. Agents no longer enable a guard of their own; bound the loop with
-  `tool_budget` instead.
-
-### ActiveRecord
-
-* **activerecord: add `LLM::ActiveRecord::Message`** <br>
-  [`LLM::ActiveRecord::Message`](https://r.uby.dev/api-docs/llm.rb/LLM/ActiveRecord/Message.html)
-  is a virtual model over the JSONB column that holds an agent's state, so
-  messages can be filtered, ordered, and counted in SQL instead of in memory.
-  `for(agent:)` returns an
-  [`ActiveRecord::Relation`](https://api.rubyonrails.org/classes/ActiveRecord/Relation.html)
-  with `id`, `role`, `content`, `tools`, and `position` columns; a row's
-  `unwrap!` returns the message. The class never materializes as a table.
-
-### Tracer
-
-* **tracer: give every request an id** <br>
-  [`LLM::Tracer#on_request_start`](https://r.uby.dev/api-docs/llm.rb/LLM/Tracer.html#on_request_start-instance_method)
-  now takes a `request_id:`, a UUIDv7 that the runtime mints when a request
-  begins and passes to `on_request_finish` and `on_request_error` for that same
-  request. A turn can make many requests, so `trace_group_id` groups a turn but
-  not the events inside one request; the id lets a tracer correlate a request's
-  start, finish, and error events. The keyword is required, so a subclass that
-  overrides these hooks must accept it.
-
-* **tracer: record the model the provider answers with** <br>
-  [`LLM::Tracer::Telemetry`](https://r.uby.dev/api-docs/llm.rb/LLM/Tracer/Telemetry.html)
-  now sets `gen_ai.response.model` from the model on the response instead of the
-  model requested, so a span reports the model a provider actually served. A
-  router model such as `openrouter/auto` records the model it resolved to,
-  while `gen_ai.request.model` keeps the name that was asked for.
-
-### Registry
-
-* **refresh model metadata** <br>
-  Update `data/` with current pricing, limits, and capabilities for the
-  Alibaba, Anthropic, Bedrock, DeepInfra, DeepSeek, Mistral, OpenAI,
-  OpenRouter, xAI, and Z.ai registries. Claude Opus 5.5 reaches Anthropic,
-  Bedrock, and OpenRouter, OpenAI adds GPT-6 Sol and GPT-6 Luna, Bedrock adds
-  Gemma 4 and more regional Claude Sonnet 4 and GPT-5.6 entries, and
-  OpenRouter adds the Xiaomi MiMo V2.6, Nex N2.5, Cohere Command A+, and
-  Qwen3.8 Omni Flash models. Z.ai adds `glm-4.6v-flash` and `glm-5.3-flashx`,
-  xAI adds Grok 4.7, DeepSeek adds a `low` reasoning effort to
-  `deepseek-v4-pro` and deprecates `deepseek-v4-flash` and
-  `deepseek-v4-flash-vision-exp`, DeepInfra reprices `tencent/Hy3`, and
-  OpenRouter drops `anthropic/claude-opus-4` and `kwaipilot/kat-coder-pro-v2`.
-
-## v15.3.0
-
-Changes since `v15.2.2`.
-
-This release gives contexts, agents, and messages UUIDv7 ids that survive
-persistence and back their `created_at`, scopes per-request headers through a
-block on `LLM::Provider#with`, and pins an OpenRouter session per context. It
-also fixes the OpenAI tool schema sent through OpenRouter and Azure, which
-mixed the Responses and Chat Completions shapes and left nested objects open.
-
-### Core
-
-* **context: give every context an id you can sort and trace** <br>
-  [`LLM::Context#id`](https://r.uby.dev/api-docs/llm.rb/LLM/Context.html#id-instance_method)
-  returns a UUIDv7 string that encodes its creation time, so contexts and their
-  agents sort by creation order and stay identifiable within and across
-  sessions. The id is generated on creation and restored with the runtime state
-  on load. [`LLM::Agent#id`](https://r.uby.dev/api-docs/llm.rb/LLM/Agent.html#id-instance_method)
-  delegates to the context it wraps; a model and its agent keep separate ids.
-
-* **context: read the creation time without storing it** <br>
-  [`LLM::Context#created_at`](https://r.uby.dev/api-docs/llm.rb/LLM/Context.html#created_at-instance_method)
-  returns when the context was created, read from the timestamp its UUIDv7 id
-  already carries, so no separate timestamp has to be persisted or kept in sync.
-  `LLM::Agent#created_at` delegates to it. The time is recomputed rather than
-  stored, so it returns `nil` for a context whose id is not a UUIDv7 string.
-
-* **message: give every message an id that survives persistence** <br>
-  [`LLM::Message#id`](https://r.uby.dev/api-docs/llm.rb/LLM/Message.html#id-instance_method)
-  returns a UUIDv7 string generated once when the message is created and restored
-  with the runtime state on load, so a message keeps the same identity across
-  saves and loads. `LLM::Message#created_at` is derived from the id rather than
-  stored. `LLM::Message#==` ignores the id, so two messages with the same role
-  and content are equal even when they were created at different times;
-  previously the timestamp took part in the comparison.
-
-* **utils: decode a UUIDv7 timestamp once, in one place** <br>
-  [`LLM::Utils.timestamp`](https://r.uby.dev/api-docs/llm.rb/LLM/Utils.html#timestamp-instance_method)
-  returns the UTC time encoded in a UUIDv7 string, or `nil` when the value is not
-  a UUIDv7. It backs `created_at` on messages, contexts, and agents, so the
-  decoding logic lives in a single method instead of three.
-
-### Provider
-
-* **provider: set a per-request header without leaking it** <br>
-  [`LLM::Provider#with`](https://r.uby.dev/api-docs/llm.rb/LLM/Provider.html#with-instance_method)
-  now takes a block: headers set inside apply to the current fiber only and are
-  restored when the block returns, so a header that varies per request can be set
-  for one call without leaking into the next. Without a block the headers are
-  merged into the provider's defaults as before. The method returns the provider
-  without a block and the block's value with one.
-
-* **openrouter: keep one session so requests reuse a cached model** <br>
-  A context now sends its id as the `x-session-id` header on OpenRouter requests,
-  so consecutive requests share a session and OpenRouter can route them to the
-  same cached model instead of starting fresh each time. Other providers are
-  unaffected.
-
-### Fix
-
-* **openai: make tools callable through OpenRouter and Azure again** <br>
-  Fix a bug where [`LLM::OpenAI`](https://r.uby.dev/api-docs/llm.rb/LLM/OpenAI.html)
-  sent a function schema that mixed the Responses and Chat Completions shapes,
-  carrying a top-level `name` next to a nested `function` object. OpenRouter and
-  OpenAI through Azure read it as a Responses function and could not describe the
-  tool correctly. The name, description, parameters, and `strict: false` now sit
-  under `function:`, the shape chat completions documents.
-
-* **openai: stop Azure rejecting nested schema objects** <br>
-  Tool parameters and structured-output schemas now carry
-  `additionalProperties: false` on every object they contain, not just the root,
-  in the chat completions and Responses paths alike. OpenAI and Azure reject a
-  schema that leaves any object open, so nested objects were failing validation.
-  The chat completions structured-output schema, which was sent open, is now
-  closed too.
-
-## v15.2.2
-
-Changes since `v15.2.1`.
-
-This release fixes the `set_provider`, `set_context`, and `set_tracer`
-callbacks installed by `acts_as_llm` and `plugin :llm` so a subclass
-inherits them from its superclass instead of raising.
-
-### Fix
-
-* **activerecord, sequel: inherit `set_provider` from a superclass** <br>
-  The `set_provider`, `set_context`, and `set_tracer` callbacks installed by
-  `acts_as_llm` / `plugin :llm` (and their agent counterparts) are now resolved
-  through the normal method lookup chain. Defining a callback on a superclass,
-  the usual single-table inheritance setup, no longer raises
-  `NotImplementedError`, and a subclass can still override it.
-
-## v15.2.1
-
-Changes since `v15.2.0`.
-
-This release makes the agent count its tool budget across the whole turn
-and emit tool returns to the stream once that budget is spent, and lets
-`LLM::Function#cancel` carry extra return fields.
-
-### Agent
-
-* **agent: count the tool budget across the whole turn** <br>
-  [`LLM::Agent.tool_budget`](https://r.uby.dev/api-docs/llm.rb/LLM/Agent.html#tool_budget-class_method)
-  now caps the tool calls a turn runs in total. A batch of calls is
-  spent as a batch, and a batch that would take the turn past its
-  budget is not run at all; once the budget is spent no tool call runs,
-  and the agent keeps sending its in-band advisory until the model
-  answers without requesting more tools. Previously the agent ran up to
-  the budget, then ran further batches after each advisory, so a turn
-  could run more tool calls than its budget allowed.
-
-* **agent: emit tool returns when the budget is spent** <br>
-  Fix a bug where, once a turn's tool budget was spent, the agent passed
-  its in-band returns to the model without emitting them to the stream.
-  The stream went silent, so a stream that tracked tool-call state left
-  the calls in the `call` state. The returns are now emitted through
-  [`LLM::Stream#on_tool_return`](https://r.uby.dev/api-docs/llm.rb/LLM/Stream.html#on_tool_return-instance_method)
-  like any other tool return.
-
-### Function
-
-* **function: `LLM::Function#cancel` takes extra return fields** <br>
-  [`LLM::Function#cancel`](https://r.uby.dev/api-docs/llm.rb/LLM/Function.html#cancel-instance_method)
-  now accepts keywords beyond `reason:` and merges them into the
-  [`LLM::Function::Return`](https://r.uby.dev/api-docs/llm.rb/LLM/Function/Return.html)
-  it builds. `LLM::Function#budget_spent` now builds its return through
-  `cancel` instead of hand-rolling an error, so a budget-spent return is
-  marked `cancelled: true` and carries `action:` and `advice:` hints. A
-  callback that receives returns can now tell a cancellation apart from
-  an ordinary error.
-
-## v15.2.0
-
-Changes since `v15.1.0`.
-
-This release renames the REPL to `LLM::Console` (with `/keep` replacing
-`/compact`) and routes every shell-out tool through a shared, bounded
-`exec` runner. It also adds `LLM::Message#created_at`, the `LLM::Tracer`
-factory methods, a `bundle` tool, per-tool `max_bytes` output limits,
-and a `-v` switch to the CLI, and refreshes the model registry.
-
-### Core
-
-* **message: add `LLM::Message#created_at`** <br>
-  [`LLM::Message#created_at`](https://r.uby.dev/api-docs/llm.rb/LLM/Message.html#created_at-instance_method)
-  returns the time the message was created, defaulting to the moment the
-  message is initialized. The timestamp is serialized into
-  [`LLM::Context#to_json`](https://r.uby.dev/api-docs/llm.rb/LLM/Context.html#to_json-instance_method)
-  as an ISO-8601 string and restored on deserialization, so it can be
-  stored alongside the rest of the conversation.
-
-### Agent
-
-* **agent: inherit the ORM model's name** <br>
-  An `acts_as_agent` (ActiveRecord) or `plugin :agent` (Sequel) model now
-  names its generated
-  [`LLM::Agent`](https://r.uby.dev/api-docs/llm.rb/LLM/Agent.html) after
-  the model class. Previously the agent was an anonymous subclass, so
-  without an explicit name it defaulted to a gibberish `#<Class:0x...>`
-  string. The wrapper now initializes the agent's name before `.agent`
-  returns, and
-  [`LLM::Agent.name`](https://r.uby.dev/api-docs/llm.rb/LLM/Agent.html#name-class_method)
-  kebab-cases a `Class` argument, so an `AdminUser` model yields an agent
-  named `admin-user`.
-
-### Cli
-
-* **cli: add a `-v` switch** <br>
-  `bin/llm.rb` gains a `-v` switch that prints the version (`llm.rb v#{LLM::VERSION}`) and exits.
-
-### Console
-
-* **console: raise `LLM::Interrupt` on the agent's thread** <br>
-  Pressing Esc to cancel now also raises `LLM::Interrupt` on the agent's
-  thread. `LLM::Agent#cancel!` alone can be a no-op at some stages of the
-  request lifecycle, so the console backs it up by interrupting the thread
-  that runs the agent.
-
-* **console: add a `/keep` command and retire `/compact`** <br>
-  The console now offers `/keep` for freeing space in the context window;
-  the `/compact` command is removed. `/keep` takes the same argument, so
-  `/keep 20%` keeps 20% of the context window. Closes
-  [issue #161](https://github.com/r-uby-dev/llm.rb/issues/161).
-
-* **console: keep the UI responsive during long streams** <br>
-  A model can emit many chunks in a single turn. The console now draws
-  at most four streamed chunks at a time, then checks for input, so the
-  UI stays responsive even when a turn produces a large amount of
-  output.
-
-* **console: persist the conversation when a turn is done** <br>
-  The console now saves the agent's state after the turn finishes,
-  rather than while the response is still streaming. State is still
-  saved every turn, but not until the turn has completed.
-
-* **console: render markdown text as typed** <br>
-  Fix a bug where [`LLM::Console::Markdown`](https://r.uby.dev/api-docs/llm.rb/LLM/Console/Markdown.html)
-  mangled the model's output: HTML could render invisible, and
-  sequences like `...` were converted to unicode glyphs. The renderer
-  now uses a custom kramdown parser that disables the HTML, smart-quote,
-  and typographic-symbol parsers, so tags and punctuation come through
-  exactly as written.
-
-* **console: fix a crash in the markdown parser** <br>
-  Fix a bug where the markdown renderer raised an error on an unclosed
-  HTML tag or a partial tag taken out of context, such as `4 < 5`. The
-  parser now emits the `<...` run literally when there is no closing
-  `>`, so the text renders instead of crashing.
-
-* **console: stop rendering bare pipes as tables** <br>
-  Fix a bug where the markdown renderer treated a lone `|foo|` in prose
-  as a table and mangled its output. A pipe line now parses as a table
-  only when a header row is followed by a delimiter row, so bare pipes
-  come through literally while real tables still render.
-
-* **console: find the worker thread when cancelling** <br>
-  Fix a bug where pressing Esc to cancel raised `LLM::Interrupt` on an
-  instance variable that does not exist, so the interrupt was a no-op and
-  a cancel could leave the turn running. The console now resolves the
-  worker thread through its `#thread` reader and interrupts it.
-
-* **console: protect the state write from cancellation** <br>
-  The console now defers `LLM::Interrupt` while it saves the agent's
-  state after a turn, so a cancel that arrives during the write cannot
-  interrupt `agent.save` mid-flight and risk a lost or corrupted session
-  file.
-
-### Tools
-
-* **tools: the command runner is now `exec`** <br>
-  The command tool that spawns a process without a shell is now
-  [`LLM::Tool::Exec`](https://r.uby.dev/api-docs/llm.rb/LLM/Tool/Exec.html),
-  with the tool name `exec` instead of the previous `shell`. This is an
-  internal refactor of the shell-out tools: `git`, `rg`, `mkdir`,
-  `ruby`, and `bundle` all route through it and inherit
-  its bounded output.
-
-* **tools: report when a command cannot be found** <br>
-  `LLM::Tool::Exec` now returns `{ok: false, error: "command 'NAME' was
-  not found on this system"}` when the requested command is missing,
-  instead of a bare `{ok: false}` result that did not tell the model why
-  the tool failed.
-
-* **tools: drop the `name:` parameter from `LLM::Tool::Exec#call`** <br>
-  `LLM::Tool::Exec#call` now takes a single `arguments:` array instead of
-  separate `name:` and `arguments:` parameters, with the command name as
-  the first element (for example `arguments: ["rg", "-m", "10", "lib"]`).
-  The `Git`, `Mkdir`, `Rg`, `Ruby`, and `Bundle` tools build their calls
-  the same way. The change was made after models were observed confusing
-  the two parameters, so a single list is simpler and more reliable.
-
-* **tools: rename `repl` as `console`** <br>
-  The interactive loop is renamed to
-  [`LLM::Console`](https://r.uby.dev/api-docs/llm.rb/LLM/Console.html),
-  which better reflects what it does. `agent.console` is the primary
-  entry point, and the require path moves from `llm/repl` to
-  `llm/console`. Backwards-compatible aliases remain: `LLM::Repl`,
-  `LLM::Agent#repl`, the ORM wrappers' `#repl`, and `LLM::Command =`
-  `LLM::Console::Command`.
-
-* **tools: `LLM::Tool::Git#call` takes an `arguments:` array** <br>
-  [`LLM::Tool::Git#call`](https://r.uby.dev/api-docs/llm.rb/LLM/Tool/Git.html)
-  now takes a single `arguments:` array in place of the previous
-  `subcommand:` parameter. The first element must be one of `log`,
-  `diff`, `commit`, `checkout`, `branch`, or `show`, validated before the
-  command is spawned; the remaining elements are forwarded to git.
-
-* **tools: `LLM::Tool::Utils` now owns command spawning** <br>
-  The shared [`LLM::Tool::Utils`](https://r.uby.dev/api-docs/llm.rb/LLM/Tool/Utils.html)
-  module now requires the `test-cmd.rb` gem (at `~> 2.7.1`) itself and
-  exposes the `spawn` and `wait` helpers, so any tool that includes
-  `Utils` gets command spawning without requiring `exec` directly.
-  `Exec` and `ReadFile` include `Utils`, and the tools that shell out
-  (`Git`, `Rg`, `Mkdir`, `Ruby`, and `Bundle`) route through `Exec`,
-  so they all get the same bounded output.
-
-* **tools: route `git`, `rg`, `mkdir`, and `ruby` through `exec`** <br>
-  `LLM::Tool::Git`, `LLM::Tool::Rg`, `LLM::Tool::Mkdir`, and
-  `LLM::Tool::Ruby` now implement their calls through the `exec` tool,
-  completing the refactor so every tool that shells out flows through
-  the shared command runner with its bounded output.
-
-* **tools: read-file returns structured lines** <br>
-  `LLM::Tool::ReadFile#call` now returns its content as structured
-  `{lineno:, content:}` lines under a `lines:` key instead of a single
-  `content:` string, and adds a `truncated:` flag. A reversed range
-  (`start: 20, stop: 2`) is swapped to read lines 2 through 20. The
-  truncation marker is kept out of the returned lines, so the model
-  does not mistake it for a real file line.
-
-* **tools: write-file appends a trailing newline by default** <br>
-  `LLM::Tool::WriteFile` now ensures written content ends with a newline,
-  adding one when the content does not already end with `\n`. It previously
-  wrote the content exactly as given. A new `newline:` parameter (default
-  `true`) controls this, so `newline: false` writes the content exactly as
-  given.
-
-* **tools: fix `edit-file` treating `before` as a regex** <br>
-  `LLM::Tool::EditFile` now escapes the `before` snippet with
-  `Regexp.escape`, so regex metacharacters are matched literally, and
-  switches to the block form of `sub` so the `after` replacement keeps
-  backslash sequences like `\1` and `\&` literal.
-
-* **tools: bound tool output with a per-tool `max_bytes`** <br>
-  Each of the `Exec`, `ReadFile`, `Rg`, `Mkdir`, `Ruby`, and
-  `Bundle` tools gains a `max_bytes` limit (default 75,000) for the
-  maximum number of bytes a tool returns to the model. `Exec` and
-  `ReadFile` add the class-level `max_bytes` accessor, which the other
-  tools inherit through `Exec`, so each tool's cap can be configured
-  independently, for example `LLM::Tool::ReadFile.max_bytes(175_000)`.
-  It does not enforce the limit by itself;
-  [`LLM::Tool::Utils#truncate`](https://r.uby.dev/api-docs/llm.rb/LLM/Tool/Utils.html#truncate-instance_method)
-  trims a string within the limit and marks the trailing content as
-  truncated, and `truncate!` returns a `[content, truncated]` tuple for
-  callers that structure truncated output themselves. `rg` also gains a
-  `max_count:` parameter that caps the number of results per file.
-
-* **tools: add a `bundle` tool** <br>
-  A new [`LLM::Tool::Bundle`](https://r.uby.dev/api-docs/llm.rb/LLM/Tool/Bundle.html)
-  tool runs a command through `bundle`. It uses the `BUNDLE_GEMFILE`
-  environment variable when set, or a `Gemfile` in the current working
-  directory otherwise. The tool takes an `arguments:` array, so the
-  model passes the bundle command and its arguments as a single list,
-  for example `arguments: ["exec", "rspec"]`.
-
-* **tools: resolve defaults through `LLM::Utils.resolve_option`** <br>
-  A tool parameter default can now be an immediate value, a Symbol resolved
-  as a method on the tool, or a Proc evaluated lazily at runtime, matching
-  how `LLM::Agent` resolves its attributes. This lets a default track a
-  value that can change between boot and runtime, such as a tool's
-  `max_bytes`.
-
-### Registry
-
-* **refresh model metadata** <br>
-  Update `data/` with current pricing, limits, and capabilities for the
-  OpenRouter, OpenAI, Bedrock, DeepInfra, DeepSeek, Google, Mistral,
-  Moonshot, Z.ai, and Alibaba registries.
-
-### Provider
-
-* **provider: retry `Net::WriteTimeout`, too** <br>
-  Requests that raise `Net::WriteTimeout` are now retried alongside the
-  other timed-out and rate-limited requests, up to the `retry_budget`,
-  matching how `Net::OpenTimeout` and `Net::ReadTimeout` are handled. The
-  console status bar also reports a write timeout as `Timed out`.
-
-* **alibaba: default to a retry budget of 8** <br>
-  An agent that runs on the Alibaba provider now defaults to a retry
-  budget of 8 instead of 5, because Alibaba (token plan) frequently rate
-  limits and times out requests that it later recovers from. An explicit
-  `retry_budget:` still overrides the default.
-
-* **deepseek: default to the `deepseek-flash` model** <br>
-  The default DeepSeek chat model is now `deepseek-flash` instead of
-  `deepseek-v4-flash`. DeepSeek resolves `deepseek-flash` to
-  `deepseek-v4.1-flash` and recommends the name in its documentation and
-  API error messages, so the default follows the current model alias
-  instead of a pinned version.
-
-### Tracer
-
-* **tracer: add `LLM::Tracer` factory methods** <br>
-  Add
-  [`LLM::Tracer.logger`](https://r.uby.dev/api-docs/llm.rb/LLM/Tracer.html#logger-class_method),
-  [`LLM::Tracer.pretty_logger`](https://r.uby.dev/api-docs/llm.rb/LLM/Tracer.html#pretty_logger-class_method),
-  and
-  [`LLM::Tracer.telemetry`](https://r.uby.dev/api-docs/llm.rb/LLM/Tracer.html#telemetry-class_method)
-  as the preferred way to build a tracer for a provider, so switching
-  between tracers means changing a factory method instead of a class name.
-  The old `LLM.logger(llm, ...)` convenience method is removed in favor
-  of `LLM::Tracer.logger(llm, ...)`.
-
-* **tracer: add `path:` support to `LLM::Tracer::PrettyLogger`** <br>
-  [`LLM::Tracer::PrettyLogger`](https://r.uby.dev/api-docs/llm.rb/LLM/Tracer/PrettyLogger.html)
-  now accepts a `path:` option to write its human-readable entries to a
-  file, matching `LLM::Tracer::Logger`. It previously only accepted `io:`.
-
-### Fix
-
-* **json: scrub invalid UTF-8 on dump** <br>
-  Fix a bug where [`LLM::JSONAdapter`](https://r.uby.dev/api-docs/llm.rb/LLM/JSONAdapter.html)
-  raised a JSON generator error when dumping a string tagged as UTF-8 that
-  carried invalid bytes. The normalize step now transcodes every string to
-  valid UTF-8, replacing invalid sequences with the replacement character,
-  so dumping works on `json ~> 3.0`. The `oj` and `yajl` adapters now run
-  the same normalization, so every backend scrubs invalid bytes before
-  serializing.
-
-* **fork: require xchan.rb `~> 0.23`** <br>
-  The `:fork` concurrency strategy now requires the `xchan.rb` gem at
-  `~> 0.23` instead of `~> 0.22`. xchan.rb 0.23.0 replaces the external
-  `lockf.rb` gem with a built-in, Fiddle-based `Chan::Lockf`, so fork
-  channels no longer carry that extra dependency. (The socket
-  length-header deadlock fix shipped earlier, in xchan.rb 0.22.0.)
-
-* **async: fix a shutdown exception on the reactor thread** <br>
-  Fix a bug where the `:async` strategy's
-  [`LLM::Function::Async::Reactor`](https://r.uby.dev/api-docs/llm.rb/LLM/Function/Async/Reactor.html)
-  raised a `TypeError` on shutdown with recent `async` and `io-event`
-  versions, because their internals tried to raise an integer as an
-  exception. The scheduler is now detached from the reactor thread
-  before it exits, which avoids that code path entirely, and teardown
-  is managed by `reactor.stop`, so the thread exits promptly instead of
-  abruptly or hanging.
-
-* **openai: prevent the loss of user messages in the completions path** <br>
-  Fix a bug where the request body was built from `params[:messages]`
-  alone when that key was present, discarding the messages built from the
-  prompt. The DeepSeek and Alibaba schema support injects the schema
-  system message into `params[:messages]`, so a request with a `schema:`
-  could be sent with the schema message only, dropping the user's
-  messages. The built messages now lead with `params[:messages]`, and the
-  key is removed before the body is assembled.
-
-## v15.1.0
-
-Changes since `v15.0.3`.
-
-This release adds the OpenRouter provider, splits provider timeouts
-into `connect_timeout` and `read_timeout`, retries timed-out requests,
-and renames `on_rate_limit` to `on_retry`. Skills now gain a
-frontmatter `model:` parameter and inherit the parent agent's model,
-while the CLI gains `-m` and `-x` switches, and the console shows retry
-progress and measures text by display width.
-
-### Provider
-
-* **add `LLM::OpenRouter` for the OpenRouter provider** <br>
-  [`LLM::OpenRouter`](https://r.uby.dev/api-docs/llm.rb/LLM/OpenRouter.html)
-  is a new provider that talks to [OpenRouter](https://openrouter.ai)
-  through its OpenAI-compatible API, contributed via
-  [PR #165](https://github.com/r-uby-dev/llm.rb/pull/165). Create an
-  instance with
-  [`LLM.openrouter`](https://r.uby.dev/api-docs/llm.rb/LLM.html#openrouter-class_method),
-  which accepts the same `key:`, `host:`, and `base_path:` options as the
-  OpenAI provider. It defaults to the `openrouter/auto` router model and
-  supports chat completions, streaming, tool calls, structured output,
-  and embeddings; image, audio, moderation, files, and vector store
-  endpoints raise `NotImplementedError`. Model metadata ships in
-  `data/openrouter.json` for the registry.
-
-* **provider: `LLM::Provider#with` accepts headers without the `headers:` keyword** <br>
-  [`LLM::Provider#with`](https://r.uby.dev/api-docs/llm.rb/LLM/Provider.html#with-instance_method)
-  now accepts headers directly as a Hash (`llm.with("User-Agent" => "llmrb/1.0")`)
-  in addition to the legacy `headers:` keyword form. Both are merged, and
-  the keyword form remains for backwards compatibility.
-
-* **providers: `model: nil` falls back to `default_model`** <br>
-  [`LLM::Provider`](https://r.uby.dev/api-docs/llm.rb/LLM/Provider.html)
-  now treats a `model: nil` payload as "use the default model" instead of
-  sending a model value that providers reject. Previously a `{model: nil}`
-  param overwrote the default and then was removed by `.compact`, leaving
-  undefined behavior where providers could reject the request.
-
-* **openai: handle `model: nil` in the Responses API** <br>
-  The OpenAI Responses API path now also falls back to the default model
-  when `model: nil`, matching the completions path.
-
-* **provider: separate `connect_timeout` and `read_timeout`** <br>
-  [`LLM::Provider`](https://r.uby.dev/api-docs/llm.rb/LLM/Provider.html)
-  now accepts a `connect_timeout:` for opening the connection (default 5
-  seconds) and a `read_timeout:` for waiting on an idle connection (default
-  600 seconds), instead of a single `timeout`. The legacy `timeout:` option
-  remains as a shorthand for `read_timeout`. The provider exposes the new
-  `#read_timeout` and `#connect_timeout` accessors.
-
-* **provider: retry timed-out requests** <br>
-  Requests that time out (`Net::OpenTimeout` or `Net::ReadTimeout`) are now
-  retried along with rate-limited requests, up to the `retry_budget`. When
-  a heavily loaded provider (for example DeepSeek) drops the connection
-  during the connect or read phase, the request is retried instead of
-  failing, and the stream is notified through `on_retry`.
-
-* **context: retry on `LLM::InsufficientQuotaError`, too** <br>
-  A request that raises
-  [`LLM::InsufficientQuotaError`](https://r.uby.dev/api-docs/llm.rb/LLM/InsufficientQuotaError.html)
-  is now retried like other rate-limited requests. The error is a subclass
-  of `LLM::RateLimitError` and can be raised at regular intervals, in
-  particular by the Alibaba provider.
-
-* **cost: return `LLM::Cost.zero` when the registry has no pricing** <br>
-  Add
-  [`LLM::Cost.zero`](https://r.uby.dev/api-docs/llm.rb/LLM/Cost.html#zero-class_method),
-  a factory for a zero-valued cost breakdown.
-  [`LLM::Context#cost`](https://r.uby.dev/api-docs/llm.rb/LLM/Context.html#cost-instance_method)
-  now returns it when the active model has no pricing in the registry (for
-  example OpenRouter's `openrouter/auto` router model), instead of crashing
-  on a nil pricing entry.
-
-### Skills
-
-* **skills: add a `model` frontmatter parameter** <br>
-  A skill's `SKILL.md` frontmatter can now declare a `model:` value, so a
-  skill's sub-agent runs on a specific model instead of the default. This
-  lets a parent agent run on one model (for example `deepseek-v4-flash`)
-  while the skill runs on another (`deepseek-v4-pro`). The `model` value is
-  not strictly portable between providers.
-
-* **skills: inherit the model of the parent agent** <br>
-  A skill's sub-agent now inherits the active model of the agent that
-  spawns it instead of falling back to the provider default. The frontmatter
-  `model:` parameter overrides it explicitly when set.
-  [`LLM::Context#model`](https://r.uby.dev/api-docs/llm.rb/LLM/Context.html#model-instance_method)
-  now falls back to the provider's default model when no model is set.
-
-### Stream
-
-* **stream: rename `on_rate_limit` to `on_retry`** <br>
-  [`LLM::Stream#on_rate_limit`](https://r.uby.dev/api-docs/llm.rb/LLM/Stream.html#on_rate_limit-instance_method)
-  is renamed to
-  [`LLM::Stream#on_retry`](https://r.uby.dev/api-docs/llm.rb/LLM/Stream.html#on_retry-instance_method),
-  which fires when a request is retried after a rate limit or a timeout,
-  and now receives the one-based retry attempt number as a second argument.
-  The old `on_rate_limit` name remains as an alias.
-
-### CLI
-
-* **cli: add a `-m` switch for choosing the model** <br>
-  `bin/llm.rb` now accepts `-m MODEL` to run the session on a model other
-  than the provider default, for example
-  `llm.rb -p deepseek -m deepseek-v4-pro`. A model unknown to the provider's
-  registry prints an error and exits.
-
-* **cli: add a `-x` switch for the read timeout** <br>
-  `bin/llm.rb` now accepts `-x SECONDS` to set the provider read timeout.
-
-* **cli: print a backtrace on fatal crashes** <br>
-  When `bin/llm.rb` hits an unexpected error, the crash message now includes
-  up to three stack lines from the backtrace, so the failure is easier to
-  locate and report than a bare diagnostic.
-
-### Console
-
-* **console: show retry progress in the status bar** <br>
-  When a request is rate limited or times out, the curses-based console status
-  bar shows a retry indicator with the error and the remaining attempts, for
-  example `🔁 Rate limited • attempt 2 of 5`.
-
-* **console: measure text width with `unicode-display_width`** <br>
-  The curses-based console now counts and slices text by display column width
-  instead of character count, so wrapping, table columns, and clipping stay
-  aligned for wide characters such as emoji. It requires the optional
-  `unicode-display_width` gem.
-
-* **console: treat `LLM::InsufficientQuotaError` as a rate limit in the status bar** <br>
-  The curses-based console status bar now shows `Rate limited` when a request
-  raises
-  [`LLM::InsufficientQuotaError`](https://r.uby.dev/api-docs/llm.rb/LLM/InsufficientQuotaError.html),
-  matching how ordinary `LLM::RateLimitError`s are shown, instead of falling
-  through to the raw class name.
-
-### Registry
-
-* **refresh model metadata** <br>
-  Update `data/*.json` with current model listings and pricing, adding
-  GPT-5.6 Sol, Terra, and Luna models to Bedrock, Grok 4.6 and Grok Imagine
-  Image 2.0 to xAI, DeepSeek V4 Flash Vision to DeepSeek, and DeepSeek V4
-  Pro 0813, Qwen3 VL, and Qwen3.8 models to DeepInfra.
-
-## v15.0.3
-
-Changes since `v15.0.2`.
-
-This release fixes ActiveRecord `:json`/`:jsonb` serialization so tool
-call arguments round-trip as JSON objects instead of arrays of pairs.
-
-### Fix
-
-* **activerecord: serialize tool call arguments properly** <br>
-  Fix a bug where the ActiveRecord `:json`/`:jsonb` layer serialized tool
-  call arguments as an array of pairs instead of a Hash. The context is
-  now serialized through its JSON form, so tool call arguments round-trip
-  as JSON objects that providers accept.
-
-## v15.0.2
-
-Changes since `v15.0.1`.
-
-This release fixes a concurrency race in MCP tool calls by
-reference-counting the transport session, so overlapping tool calls
-reuse the running transport instead of racing `start`/`stop`.
-
-### Fix
-
-* **mcp: fix concurrent MCP tool call race** <br>
-  `LLM::MCP` now reference-counts its transport session: the first
-  caller starts the transport and the last caller stops it. Concurrent
-  or overlapping tool calls reuse the running transport instead of
-  racing `start`/`stop`, avoiding "MCP transport is not running" errors
-  that could occur with the `async` strategy. An externally started
-  transport is never stopped by a borrower.
-
-## v15.0.1
-
-Changes since `v15.0.0`.
-
-This release fixes agent `set` handling of single `Symbol`/`Proc`
-values and resolves ORM options as `Symbol`s through the bound record
-instead of the `LLM::Agent` instance.
-
-### Agent
-
-* **agent: fix `set (skills|tools): Symbol|Proc`** <br>
-  The `skills`, `tools`, `confirm`, and `schema` class accessors now
-  consistently resolve a single `Symbol` or `Proc` lazily at agent
-  initialization, so `LLM::Agent.set(skills: proc { [...] })` and
-  `LLM::Agent.set(tools: :tools)` no longer raise. The `set` family
-  shares one `single_callable?` helper rather than each accessor
-  duplicating its own logic.
-
-### Fix
-
-* **orm: resolve a `Symbol` through the bound record** <br>
-  When an ORM model using `acts_as_agent` (ActiveRecord), `plugin :agent`
-  (Sequel), or `acts_as_llm` / `plugin :llm` configures an option as a
-  `Symbol`, that symbol is now resolved on the model instance (or its
-  bound record) instead of the `LLM::Agent` instance. The contexts and
-  agents built by the wrappers are now bound to the record, so a model like
-  `agent.set :tools` with a `tools` method on the record works as
-  expected.
-
-## v15.0.0
-
-Changes since `v14.0.0`.
-
-This release renames `usage` to `token_usage` across contexts, agents,
-and messages, makes `context_window` return `nil` when unknown, and
-makes `LLM::Cost` accessors always return `Float`. It also adds the
-Alibaba provider, automatic API key discovery from the environment,
-new context-usage and context-used methods, a retry budget for
-rate-limited requests, and a range of REPL and skills improvements.
-
-### Breaking
-
-#### Migration
-
-| Old | New |
-|-----|-----|
-| `ctx.usage` / `agent.usage` / `msg.usage` | `ctx.token_usage` / `agent.token_usage` / `msg.token_usage` (`usage` remains an alias) |
-| `LLM::Message#usage` returns `LLM::Object` | `LLM::Message#token_usage` returns a copy of `LLM::Usage`, for assistant messages only |
-| `ctx.context_window` returns `0` when the model isn't in the registry | returns `nil` when unknown |
-| `LLM::Cost#input` (and other accessors) return `nil` when unused | return `0.0` |
-| `ctx.usage` returns the most recent assistant message usage | sums token usage across all assistant messages |
-| a skill exposes its tool as `weather` (the skill name) | the generated tool is now named `weather-skill` |
-
-* **rename `#usage` to `#token_usage` across contexts, agents, and messages** <br>
-  [`LLM::Context#usage`](https://r.uby.dev/api-docs/llm.rb/LLM/Context.html#usage-instance_method),
-  [`LLM::Agent#usage`](https://r.uby.dev/api-docs/llm.rb/LLM/Agent.html#usage-instance_method),
-  and
-  [`LLM::Message#usage`](https://r.uby.dev/api-docs/llm.rb/LLM/Message.html#usage-instance_method)
-  are now aliases of `token_usage`.
-  [`LLM::Message#token_usage`](https://r.uby.dev/api-docs/llm.rb/LLM/Message.html#token_usage-instance_method)
-  now returns a copy of `LLM::Usage` instead of `LLM::Object`, and only
-  returns a value for assistant messages.
-
-* **`LLM::Context#context_window` now returns `nil` when unknown** <br>
-  [`LLM::Context#context_window`](https://r.uby.dev/api-docs/llm.rb/LLM/Context.html#context_window-instance_method)
-  now returns `nil` when the model's context window size is not known to the
-  runtime, instead of `0`. This makes the code check for a window instead
-  of a number, so an unknown window no longer reads as a real (zero) size.
-
-* **`LLM::Cost` accessors always return `Float` objects** <br>
-  The cost accessors on
-  [`LLM::Cost`](https://r.uby.dev/api-docs/llm.rb/LLM/Cost.html)
-  (`input`, `output`, `input_audio`, `output_audio`, `input_image`,
-  `cache_read`, `cache_write`, and `reasoning`) now always return a
-  `Float`, returning `0.0` when no tokens of that kind were used, instead
-  of `nil`. Callers can sum and compare cost values without guarding
-  against `nil`.
-
-* **expose new context methods on the ActiveRecord and Sequel wrappers** <br>
-  The `acts_as_llm` (ActiveRecord) and `plugin :llm` (Sequel) wrappers
-  now expose `context_used` and `context_usage`, delegating to the
-  wrapped `LLM::Context`. `token_usage` replaces `usage` (which remains
-  as an alias), and `context_window` now returns `nil` when the model's
-  context window is unknown instead of `0`.
-
-### Core
-
-* **discover API keys from the environment** <br>
-  [Cloud provider factories](https://r.uby.dev/api-docs/llm.rb/LLM.html)
-  (`LLM.anthropic`, `LLM.google`, `LLM.deepseek`, `LLM.openai`,
-  `LLM.xai`, `LLM.mistral`, `LLM.zai`, `LLM.moonshot`,
-  `LLM.alibaba`, and `LLM.aliyun`) now resolve the provider's API key
-  automatically when no `key:` is given, by walking the environment
-  variable names listed in the models.dev registry. So `LLM.openai`
-  works without an explicit key as long as `OPENAI_API_KEY` (or one of
-  the registry's alternative names) is set in the environment. A
-  missing key raises `ArgumentError`.
-
-* **cli: auto-discover credentials and support Bedrock** <br>
-  `bin/llm.rb` now resolves the provider through the `LLM` factory
-  methods instead of mapping environment variable names directly, so it
-  picks up Bedrock (all three AWS credentials) and relies on the same
-  automatic key discovery as the library. The CLI also always starts
-  now: without arguments it falls back to `ollama` or `llamacpp`. A
-  provider whose credentials are not set exits with status 1.
-
-* **cli: add `-c` and `-n` switches** <br>
-  `bin/llm.rb` now accepts a `-c STRATEGY` switch to choose the
-  concurrency strategy used for tool calls (`thread`, `async`, `fork`,
-  or any of the other strategies) and a `-n TRANSPORT` switch to choose
-  the HTTP transport (`net-http`, `net-http-persistent`, or `curb`),
-  both forwarded to the session's agent and provider.
-
-* **context: keep runtime parameters from reaching the provider** <br>
-  [`LLM::Context`](https://r.uby.dev/api-docs/llm.rb/LLM/Context.html)
-  now strips its runtime-only parameters (`guard`, `retry_budget`,
-  `concurrency`, `transformer`, and `compactor`) before merging params
-  into a provider request, so they can never cross the context-provider
-  boundary and risk an API-level error.
-
-* **add `retry_budget` support for rate-limited requests** <br>
-  [`LLM::Context`](https://r.uby.dev/api-docs/llm.rb/LLM/Context.html)
-  now accepts a `retry_budget:` that automatically sleeps and retries a
-  rate-limited request up to the given number of times before raising
-  `LLM::RateLimitError`. Each retry sleeps a growing interval (2s, 4s,
-  6s, ...) and notifies the stream through
-  [`LLM::Stream#on_rate_limit`](https://r.uby.dev/api-docs/llm.rb/LLM/Stream.html#on_rate_limit-instance_method).
-  [`LLM::Agent`](https://r.uby.dev/api-docs/llm.rb/LLM/Agent.html)
-  enables a budget of 5 by default, while a raw context disables it (0)
-  unless configured.
-
-* **add `LLM::Usage.zero`** <br>
-  Add
-  [`LLM::Usage.zero`](https://r.uby.dev/api-docs/llm.rb/LLM/Usage.html#zero-class_method)
-  as a zero-valued usage object. `LLM::Context#usage`, `LLM::Agent#usage`,
-  and the ActiveRecord and Sequel wrappers now return `LLM::Usage` objects
-  instead of `LLM::Object` when no provider usage has been recorded yet.
-
-* **add `LLM::Context#context_usage` and `LLM::Agent#context_usage`** <br>
-  Add
-  [`LLM::Context#context_usage`](https://r.uby.dev/api-docs/llm.rb/LLM/Context.html#context_usage-instance_method)
-  and
-  [`LLM::Agent#context_usage`](https://r.uby.dev/api-docs/llm.rb/LLM/Agent.html#context_usage-instance_method),
-  which return the fraction of the model's context window currently used as
-  a `Rational` (for example `Rational(100, 10_000)`), or `nil` when the used
-  amount or the window size is unknown. The REPL status bar now renders this
-  fraction instead of computing the remainder from raw token counts.
-
-* **add `LLM::Context#context_used` and `LLM::Agent#context_used`** <br>
-  Add
-  [`LLM::Context#context_used`](https://r.uby.dev/api-docs/llm.rb/LLM/Context.html#context_used-instance_method)
-  and
-  [`LLM::Agent#context_used`](https://r.uby.dev/api-docs/llm.rb/LLM/Agent.html#context_used-instance_method),
-  which return the live context size (in tokens) of the most recent
-  assistant message, or `nil` when no assistant message has a recorded token
-  usage. This fills the gap left after `token_usage` became accumulative and
-  no longer represented a single turn, so callers can read how much of the
-  context window has been used without walking the messages themselves.
-
-### Provider
-
-* **add `LLM::Provider#registry`** <br>
-  Add [`LLM::Provider#registry`](https://r.uby.dev/api-docs/llm.rb/LLM/Provider.html#registry-instance_method),
-  which returns the provider's model registry. `LLM::Context#registry`
-  and `LLM::Agent#registry` now delegate to their underlying provider
-  instead of looking it up on their own.
-
-* **add `LLM::Alibaba` for Alibaba Cloud Model Studio** <br>
-  [`LLM::Alibaba`](https://r.uby.dev/api-docs/llm.rb/LLM/Alibaba.html)
-  is a new provider that talks to
-  [Alibaba Cloud Model Studio](https://www.alibabacloud.com/help/en/model-studio/models)
-  through its OpenAI-compatible API, including the Qwen3 family of
-  models. Create an instance with
-  [`LLM.alibaba`](https://r.uby.dev/api-docs/llm.rb/LLM.html#alibaba-class_method),
-  also aliased as `LLM.aliyun`, which accepts the same `key:`, `host:`,
-  and `base_path:` options as the OpenAI provider. The provider defaults
-  to the `deepseek-v4-flash-0731` model and supports chat completions,
-  streaming, tool calls, and structured output through the shared
-  OpenAI-compatible path; image, audio, moderation, responses, and
-  vector store endpoints raise `NotImplementedError`. Model metadata
-  ships in `data/alibaba.json` for the registry.
-
-* **alibaba: support structured outputs via `json_object`** <br>
-  [`LLM::Alibaba`](https://r.uby.dev/api-docs/llm.rb/LLM/Alibaba.html)
-  now supports structured output through a shared `json_object` fallback,
-  since Alibaba models do not support `json_schema` natively. The schema is
-  described in an injected system message that also satisfies the
-  "messages must contain the word json" requirement. The same shared
-  fallback now also backs DeepSeek.
-
-* **alibaba: default to the pay-as-you-go host** <br>
-  The default
-  [`LLM::Alibaba`](https://r.uby.dev/api-docs/llm.rb/LLM/Alibaba.html)
-  host is now `dashscope-intl.aliyuncs.com`. Override it globally with
-  the `DASHSCOPE_API_HOST` environment variable, or per instance with
-  `LLM.alibaba(host: ...)`, for example to point at a Token Plan
-  endpoint.
-
-* **alibaba: use `DASHSCOPE_API_KEY` as the default key env var** <br>
-  [`LLM::Alibaba`](https://r.uby.dev/api-docs/llm.rb/LLM/Alibaba.html)
-  now discovers its API key from `DASHSCOPE_API_KEY` instead of
-  `ALIBABA_API_KEY`, following the models.dev registry convention.
-
-* **alibaba: raise `LLM::InsufficientQuotaError` for exhausted quota** <br>
-  Add
-  [`LLM::InsufficientQuotaError`](https://r.uby.dev/api-docs/llm.rb/LLM/InsufficientQuotaError.html),
-  a subclass of `LLM::RateLimitError`, for when a provider reports a
-  tokens-per-minute (TPM) quota limit.
-  [`LLM::Alibaba`](https://r.uby.dev/api-docs/llm.rb/LLM/Alibaba.html)
-  now raises it when Alibaba responds with an `insufficient_quota`
-  error. Since it subclasses `RateLimitError`, quota errors are retried
-  like other rate limits.
-
-* **bedrock: auto-discover AWS credentials from the environment** <br>
-  [`LLM.bedrock`](https://r.uby.dev/api-docs/llm.rb/LLM.html#bedrock-class_method)
-  now infers its credentials from the `AWS_ACCESS_KEY_ID`,
-  `AWS_SECRET_ACCESS_KEY`, and `AWS_REGION` environment variables when
-  they are not passed explicitly, matching the other cloud providers. A
-  missing key raises `ArgumentError`.
-
-* **add `LLM::Bedrock#key?`** <br>
-  Add
-  [`LLM::Bedrock#key?`](https://r.uby.dev/api-docs/llm.rb/LLM/Bedrock.html#key%3F-instance_method),
-  which overrides the superclass method to check all three Bedrock
-  credentials (`access_key_id`, `secret_access_key`, and `region`)
-  instead of a single API key.
-
-### Function
-
-* **make `Sequential::Group` abide by the `LLM::Function::Group` contract** <br>
-  [`LLM::Function::Sequential::Group`](https://r.uby.dev/api-docs/llm.rb/LLM/Function/Sequential/Group.html)
-  now receives an array of
-  [`LLM::Function::Sequential::Task`](https://r.uby.dev/api-docs/llm.rb/LLM/Function/Sequential/Task.html)
-  objects instead of raw `LLM::Function` objects, matching the interface
-  shared by every other concurrency strategy.
-  [`LLM::Function::Array#task`](https://r.uby.dev/api-docs/llm.rb/LLM/Function/Array.html#task-instance_method)
-  wraps each function as a `Sequential::Task` before constructing the
-  group, and the group delegates `spawn`, `alive?`, and `wait` to those
-  tasks. This fixes `Sequential::Group#alive?`, which always returned
-  `false`, and restores guard handling for sequential execution by
-  honoring the shared `guarded:` option on `Sequential::Task`.
-
-* **function: redirect output streams in `:fork` tool processes** <br>
-  The `:fork` concurrency strategy (via
-  [`LLM::Function::Fork::Task`](https://r.uby.dev/api-docs/llm.rb/LLM/Function/Fork/Task.html))
-  now redirects the child process's `$stdout` and `$stderr` to
-  `File::NULL`, so a forked tool can no longer clobber the parent
-  terminal, for example by blanking the curses REPL display. A tool that
-  genuinely needs the terminal can still reopen `/dev/tty`; the file
-  descriptor stays available to the child.
-
-### Fix
-
-* **a2a: fix a typo in the HTTP transport** <br>
-  Fix a bug in
-  [`LLM::A2A::Transport::HTTP`](https://r.uby.dev/api-docs/llm.rb/LLM/A2A/Transport/HTTP.html)
-  where the constructor read `uri.port` instead of `@uri.port`, which
-  crashed the program whenever
-  [`LLM::A2A.rest`](https://r.uby.dev/api-docs/llm.rb/LLM/A2A.html#rest-class_method)
-  or
-  [`LLM::A2A.jsonrpc`](https://r.uby.dev/api-docs/llm.rb/LLM/A2A.html#jsonrpc-class_method)
-  was used. The transport now reads the port from the parsed `@uri`.
-
-* **openai: report usage for streamed completions requests** <br>
-  Fix a bug in the OpenAI completions path where `params[:stream]` was
-  checked after it had been deleted from the params hash, so the check
-  always evaluated to `false`. The fix checks the resolved stream's
-  `enabled?` instead, so `stream_options: {include_usage: true}` is
-  added to streamed requests and API usage is reported back to the
-  caller.
-
-* **curb: read the stream body and resolve streaming requests** <br>
-  Fix two bugs in [`LLM::Transport::Curb`](https://r.uby.dev/api-docs/llm.rb/LLM/Transport/Curb.html)
-  that left the `curb` transport unusable. The request body setter now
-  reads a streaming request's body stream into a string (dropping the
-  chunked transfer header, which curb replaces with a content length),
-  and the result builder now accumulates the response body from the
-  `on_body` callback instead of leaving it empty.
-
-* **cli: handle errors in `main`** <br>
-  Wrap all of `bin/llm.rb`'s `main` method in error handling: an
-  interrupted session exits gracefully with `Bye!`, an explicit provider
-  is passed the resolved transport, and any unexpected error prints a
-  formatted diagnostic with a link to issue tracking before exiting.
-
-* **cli: persist the session mapping file** <br>
-  Fix a bug where `bin/llm.rb` saved the session file at
-  `~/.llm.rb/<provider>/<uuid>.json` but never wrote the updated
-  working-directory mapping back to `~/.llm.rb/<provider>.json`. The
-  mapping file is now written whenever a new session is registered.
-
-* **context: aggregate usage across all assistant messages** <br>
-  [`LLM::Context#usage`](https://r.uby.dev/api-docs/llm.rb/LLM/Context.html#usage-instance_method)
-  now sums token usage across every assistant message in the conversation
-  instead of returning only the first message's usage.
-  [`LLM::Cost.from`](https://r.uby.dev/api-docs/llm.rb/LLM/Cost.html)
-  now subtracts reasoning tokens from the output total and cache-read
-  tokens from the input total before pricing, and prices reasoning tokens
-  with the model's reasoning rate when one is available.
-
-### Repl
-
-* **draw a top chrome row with the cwd and active model** <br>
-  The curses-based REPL now draws a white-on-blue row at the very top of
-  the screen showing the current working directory on the left and the
-  active model on the right. The row is drawn above the transcript and
-  uses a new blue status-bar color pair.
-
-* **redraw the window on resize** <br>
-  The curses-based REPL now handles the terminal resize signal
-  (`KEY_RESIZE`) while reading input, clearing and redrawing the entire
-  window so the layout stays aligned after the terminal is resized.
-
-* **hide the cursor until the window is ready** <br>
-  Fix a visual glitch where the curses-based REPL showed the cursor at
-  position 0,0 at startup and then jumped it to the input area once the
-  window was drawn. The cursor is now hidden until the input field has
-  been drawn and the cursor can be placed directly into it.
-
-* **collapse the cost to two decimal places** <br>
-  [`LLM::Cost#to_s`](https://r.uby.dev/api-docs/llm.rb/LLM/Cost.html)
-  now renders the total cost with two decimal places (for example
-  `$0.01`), so the REPL status bar shows a compact cost estimate instead
-  of a long run of digits.
-
-* **add auto-complete ability for commands** <br>
-  [`LLM::Repl::Command`](https://r.uby.dev/api-docs/llm.rb/LLM/Repl/Command.html)
-  subclasses can now override a `complete` method to autocomplete their
-  arguments. The method receives the command's parameters as keyword
-  arguments, with the non-nil keyword being the active fragment, and
-  returns candidate completions. Repeated TAB presses cycle through the
-  candidate list.
-
-* **add `LLM::Repl#model` and `LLM::Repl#model=`** <br>
-  [`LLM::Repl`](https://r.uby.dev/api-docs/llm.rb/LLM/Repl.html#model-instance_method)
-  now tracks the active model in its own `model` attribute, seeded from
-  the wrapped agent's model. The status bar reads the model through the
-  repl instead of the agent, so the model can be switched within a
-  session.
-
-* **add `/model` command** <br>
-  A new `/model <name>` command switches the active model within a
-  single REPL session. Its argument auto-completes through the
-  text-to-text models in the registry.
-
-* **repl: restrict autocomplete to text-to-text models** <br>
-  The `/model` command's argument auto-complete now suggests only
-  text-to-text models, so embedding and other non-chat models are
-  left out of the completion list.
-
-* **repl: highlight GitHub-flavored codeblocks** <br>
-  The curses-based REPL now parses the GitHub-style ``` fences that
-  models commonly emit as real code blocks. Kramdown's native fenced-code
-  syntax uses `~~~`, so the ``` fences were previously parsed as inline
-  code spans. The language name is now shown in bold white above the code,
-  which renders in green.
-
-* **repl: fix a scroll render artifact** <br>
-  Fix a bug where scrolling upward could leave a piece of text just
-  above the status row as a render artifact. The row above the status
-  row is now cleared on every buffer render.
-
-* **repl: add a buffer row below the blue status bar** <br>
-  The curses-based REPL buffer now starts with an empty row below the
-  blue status bar, improving the visual spacing of the first exchange
-  in the chat.
-
-* **repl: pin `curses` and `kramdown` to tested versions** <br>
-  The REPL now pins `curses` to `~> 1.6` and `kramdown` to `~> 2.5`
-  through `LLM.require`, so it loads gem versions known to have been
-  tested instead of whatever happens to be installed.
-
-### Skills
-
-* **skills: append `-skill` to the generated tool name** <br>
-  A skill is now exposed as a tool named `"<skill>-skill"` instead of
-  just the skill's name, so a skill like `weather` that also uses a tool
-  named `weather` no longer collides with it (or a same-named global
-  tool) in the tool registry.
-
-* **skills: add `LLM::Stream` skill lifecycle callbacks** <br>
-  Add
-  [`LLM::Stream#on_skill_call`](https://r.uby.dev/api-docs/llm.rb/LLM/Stream.html#on_skill_call-instance_method)
-  and
-  [`LLM::Stream#on_skill_return`](https://r.uby.dev/api-docs/llm.rb/LLM/Stream.html#on_skill_return-instance_method),
-  which are called before a skill's sub-agent runs and after it finishes.
-  `on_skill_return` receives the `LLM::Agent` sub-agent that ran the skill
-  along with the resulting `LLM::Response`, so a stream can inspect the
-  sub-agent's conversation, tally its usage, or add a verification step. A
-  stream can use the two callbacks to know when a skill sub-agent is
-  running.
-
-### Registry
-
-* **add `LLM::Registry::Model` as a comparable model wrapper** <br>
-  Add [`LLM::Registry::Model`](https://r.uby.dev/api-docs/llm.rb/LLM/Registry/Model.html),
-  a wrapper around a model's registry metadata (pricing, limits,
-  capabilities, and modalities). Models are comparable by price, so
-  `models.sort` orders them from cheapest to most expensive. The class
-  exposes predicate helpers such as `tool_call?`, `reasoning?`,
-  `structured_output?`, `open_weights?`, `text?`, `image?`, `audio?`,
-  `pdf?`, and `video?`, plus `input_cost`, `output_cost`, and
-  `context_window` accessors.
-
-* **gemspec: bundle the deepdive guide from `docs/`** <br>
-  The gemspec now packages the deepdive guide from `docs/deepdive.md`
-  and `docs/deepdive/*/*.md` after the deepdive sources moved from
-  `resources/` to `docs/`, so the full guide ships with the gem.
-
-* **make `LLM::Registry#models` return model objects** <br>
-  [`LLM::Registry#models`](https://r.uby.dev/api-docs/llm.rb/LLM/Registry.html#models-instance_method)
-  now returns a list of
-  [`LLM::Registry::Model`](https://r.uby.dev/api-docs/llm.rb/LLM/Registry/Model.html)
-  objects instead of model name strings. Use the new
-  [`LLM::Registry#keys`](https://r.uby.dev/api-docs/llm.rb/LLM/Registry.html#keys-instance_method)
-  method to get the model names.
-
-* **refresh DeepInfra model metadata** <br>
-  Update `data/deepinfra.json` with current pricing for the DeepSeek
-  V4, DeepSeek-V3, DeepSeek-R1-0528, and Kimi-K3 models, and mark
-  `structured_output` support for one model.