legion-llm 0.6.20 → 0.6.24

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 45d07a2c60a8663ba1b62165b3b489d49a2aac37ee1e1ec6abff7bd5f4357d6c
-  data.tar.gz: 9ee8246c75fee6d7e690b55f4e2a91b030f6b142c91dd79acb7bf66edf4d9d05
+  metadata.gz: c7e4263174302a505c21078bbc343c36134c08e22f0ad2d2741e6e2b4b747327
+  data.tar.gz: ef99cbea7efe6f0e0c479586c73792d814328169ca1e0faaf2362da8cb140be1
 SHA512:
-  metadata.gz: 92b102167bb6f346fab490787baedda2f2fa6fb528713c6b055b269f747c490d56fed5d21027616bc2c6d1f7cf4069ce14bb9b7607f7a6ad07c2c69b05ce0814
-  data.tar.gz: f1fded39722bf678936df28f3bbf3ec095265bdabc28f70eaf67e64fae5519b7c58842a8432e4b4bfdc0476c9275473f75a9c83bf0c77d6f5cc2afe1fa700aeb
+  metadata.gz: bb18ac2c9d7cb8108edc71208dc97b4befaed9ab6cdbcb7c1f8662c00402c08619609e3ce5d372b9f4483175020ef2100ac5b86ae2d147216e755f4211173f41
+  data.tar.gz: e0f5b35fb908eff66faea9509f984fa141531c467db9ab1c8e2276f5e47dcd7a65f42e63e5004db4d27334867489c578a44c51b3779d9d954bd7d4028487e37e

data/CHANGELOG.md

@@ -1,5 +1,56 @@
 # Legion LLM Changelog
 
+## [0.6.24] - 2026-04-08
+
+### Added
+- `Legion::LLM::Patches::RubyLLMParallelTools`: monkey-patch that replaces RubyLLM's serial `handle_tool_calls` loop with concurrent thread execution so all tool calls in a batch run in parallel
+- `ToolResultWrapper` struct exposes `tool_call_id`, `id`, `tool_name`, `result`, and `content` so bridge scripts can match results back to UI slots without falling back to name-based matching
+- `emit_tool_result_event` in `Pipeline::Executor`: fires `tool_event_handler` with `type: :tool_result`, `duration_ms`, `started_at`, and `finished_at` after each tool completes
+- `tool_event_handler` now also fires `type: :model_fallback` events (with `from_model`, `to_model`, `error`, `reason`) on auth-failed provider fallback in both regular and streaming paths
+- `max_tool_rounds` setting (default `200`) in LLM settings; `install_tool_loop_guard` now reads it at call time so callers can override the cap per-session
+- `started_at` timestamp stored in `Thread.current[:legion_current_tool_started_at]` for accurate per-call wall-clock duration even across parallel threads
+
+### Changed
+- `MAX_RUBY_LLM_TOOL_ROUNDS` constant raised from `25` to `200` (now serves as a fallback default for the configurable `max_tool_rounds` setting)
+
+### Fixed
+- `ConversationStore#db_append_message` now serializes non-String `content` values (e.g., tool-call arrays) to JSON before writing to the database, preventing Sequel type errors when tool-use messages are persisted
+
+## [0.6.23] - 2026-04-07
+
+### Fixed
+- `build_response_routing` now always sets `routing[:escalated]` (defaults to `false`) instead of conditionally omitting the key
+- Schema spec annotations updated: Thinking, Cache, Config(Generation) corrected to reflect `from_chat_args` first-class field mapping; ErrorResponse annotation updated with complete error hierarchy including `EscalationExhausted`, `PrivacyModeError`, `TokenBudgetExceeded`, `DaemonDeniedError`, `DaemonRateLimitedError`
+
+## [0.6.22] - 2026-04-07
+
+### Fixed
+- Classification LEVELS ordering: swapped `[:public, :internal, :restricted, :confidential]` to correct `[:public, :internal, :confidential, :restricted]` so severity comparisons work properly
+- `Response.from_ruby_llm` now extracts actual `stop_reason` from provider response instead of hardcoding `:end_turn`
+- `Request.from_chat_args` maps 16 fields (`tool_choice`, `generation`, `thinking`, `response_format`, `context_strategy`, `cache`, `fork`, `tokens`, `stop`, `modality`, `hooks`, `idempotency_key`, `ttl`, `metadata`, `enrichments`, `predictions`) to first-class struct members instead of dumping into `extra`
+- `build_response` populates routing details (strategy, tier, escalation chain, latency), cost estimation via `CostEstimator`, and actual stop reason instead of hardcoded defaults
+- `response_tool_calls` merges execution data (exchange_id, source, status, duration_ms, result) from timeline events into tool call hashes
+- `step_conversation_uuid` now auto-generates `conv_<hex>` when no conversation_id is provided (was a no-op)
+- `step_response_normalization` now normalizes all enrichment keys to string format (was a no-op)
+- Enrichment key `[:conversation_history]` corrected to `['context:conversation_history']` for consistent `source:type` pattern
+
+### Changed
+- Schema spec (`docs/llm-schema-spec.md`) updated: ToolCall, Config(Generation), Cost, Routing(response), Stop status changed from Partial/Not-implemented to Implemented
+
+## [0.6.21] - 2026-04-07
+
+### Added
+- Real-time tool call SSE streaming: tool-call, tool-result, and tool-error events emitted during execution, not after completion
+- `ClientToolMethods` module extracted from inline tool class for cleaner separation
+- Rich tool execution logging: command, path, pattern, url shown per tool type instead of just key names
+- `summarize_tool_args` produces structured log details per tool type (sh, file_read, file_write, file_edit, grep, glob, web_fetch, list_directory)
+- `tool_event_handler` callback on `Pipeline::Executor` for real-time tool event forwarding via `Thread.current`
+
+### Fixed
+- `install_tool_loop_guard` now uses `session.on_tool_call` instead of `session.on(:tool_call)` — RubyLLM callback was never firing, tool_call_id was always nil
+- `list_directory` tool now expands `~` via `File.expand_path` — previously failed with `ENOENT` on tilde paths
+- SSE text-delta events logged at debug level instead of info to reduce log noise
+
 ## [0.6.20] - 2026-04-06
 
 ### Added

data/README.md

@@ -2,7 +2,7 @@
 
 LLM integration for the [LegionIO](https://github.com/LegionIO/LegionIO) framework. Wraps [ruby_llm](https://github.com/crmne/ruby_llm) to provide chat, embeddings, tool use, and agent capabilities to any Legion extension.
 
-**Version**: 0.6.14
+**Version**: 0.6.23
 
 ## Installation
 

data/docs/llm-schema-spec.md

@@ -1,6 +1,75 @@
 # Legion::LLM Schema Specification
 
-## Status: Draft / Brainstorming
+## Status: Mixed — Envelope Implemented, Inner Types Aspirational
+
+**Implemented in**: `Pipeline::Request` and `Pipeline::Response` (`lib/legion/llm/pipeline/request.rb`, `response.rb`)
+**Version**: 1.0.0 (schema_version field on all payloads)
+**Last verified**: 2026-04-07
+
+The outer envelope is implemented: all 32 `Request` fields and 34 `Response` fields exist as `Data.define` members. However, many inner types (Message, ContentBlock, ToolCall, Chunk, Conversation, Feedback, ErrorResponse) are **not yet implemented as dedicated structs** — they are plain hashes or strings in the current code. Several Response fields are **always nil or empty** in the pipeline today.
+
+This document serves as both the **canonical reference** for what is implemented and the **target specification** for what inner types should look like. Sections are annotated with implementation status.
+
+For the AMQP wire protocol (exchange topology, queue configuration, message envelope, routing keys), see the Legion Wire Protocol spec in the LegionIO docs repo.
+
+### Implementation Status Matrix
+
+| Section | Status | Notes |
+|---------|--------|-------|
+| **Request (envelope)** | Implemented | All 32 fields exist on `Data.define`. `from_chat_args` maps all to first-class fields. |
+| **Response (envelope)** | Partial | All 34 fields exist. 10 fields always nil/empty (see below). |
+| **Message** | Not implemented | Plain `{ role:, content: }` hashes. No struct, no id/seq/status/version. |
+| **ContentBlock** | Not implemented | Content is always String. Only `:text` block used (system prompt caching). |
+| **Tool** | Partial | `ToolAdapter` has name/description/parameters. No `source` on object, no `version`. |
+| **ToolCall** | Partial | `id`, `name`, `arguments` + `exchange_id`, `source`, `status`, `duration_ms`, `result` merged from Timeline. `error` field never populated. Timeline lookup by tool name, not call ID (breaks duplicate tool calls). |
+| **ToolChoice** | Stub | Field exists on Request, defaults to `{ mode: :auto }`, never forwarded to provider. |
+| **Enrichment** | Implemented | RAG/GAIA enrichments work. Value shapes vary between steps. |
+| **Prediction** | Partial | Request-side works. Response-side actuals never filled in. |
+| **Tracing** | Implemented | trace_id, span_id, exchange_id all generated and propagated. |
+| **Classification** | Partial | Labels applied but routing restrictions not enforced. |
+| **Caller** | Implemented | Identity propagated, Profile derived. |
+| **Agent** | Not implemented | Response `agent` field always nil. |
+| **Billing** | Partial | Per-request cap only. No cumulative budget enforcement. |
+| **Test** | Implemented | Test mode flags propagated. |
+| **Modality** | Not implemented | Field exists, not acted upon. |
+| **Hooks** | Partial | Pre/post hooks on Request. Response hooks not fired. |
+| **Feedback** | Not implemented | No struct, class, or storage. Spec only. |
+| **Audit** | Implemented | Uses symbol keys (not string keys as spec claims). |
+| **Timeline** | Implemented | Event recording works. Participant tracking works. |
+| **Participants** | Implemented | Tracked via Timeline. |
+| **Wire Capture** | Not implemented | Response `wire` field always nil. |
+| **Retry** | Not implemented | Response `retry` field always nil. |
+| **Safety** | Not implemented | Response `safety` field always nil. |
+| **Rate Limit** | Not implemented | Response `rate_limit` field always nil. |
+| **Thinking** | Partial | Request thinking config mapped to first-class field. Response thinking **never populated** by executor (always nil). |
+| **Context Window** | Not implemented | `tokens.context_window`, `utilization`, `headroom` never populated. |
+| **Validation** | Not implemented | Response `validation` field always nil. |
+| **Provider Features** | Not implemented | Response `features` field always nil. |
+| **Model Deprecation** | Not implemented | Response `deprecation` field always nil. |
+| **Cache** | Partial | Request cache mapped to first-class field. Response `cache` always `{}`. |
+| **Chunk (Streaming)** | Not implemented | Raw RubyLLM chunks passed through; no spec-compliant Chunk struct. |
+| **ErrorResponse** | Not implemented | No struct; only exception classes (`LLMError` hierarchy). |
+| **Conversation** | Partial | `ConversationStore` exists but no `Conversation` struct. Limited fields. |
+| **Config (Generation)** | Implemented | `from_chat_args` now maps generation, thinking, response_format, etc. to first-class fields. |
+| **Quality** | Implemented | Returns `{ score:, band:, source: }` (not `{ score:, acceptable:, checker: }` as spec says). |
+| **Cost** | Implemented | Populated via `CostEstimator.estimate` with `estimated_usd`, `provider`, `model`. |
+| **Routing (response)** | Implemented | `provider`, `model`, `strategy`, `tier`, `escalated`, `escalation_chain`, `latency_ms` populated. |
+| **Stop** | Implemented | `stop.reason` extracted from provider response (`:end_turn`, `:tool_use`, etc.). |
+| **Metering** | Not implemented | Module exists but not wired into pipeline steps. |
+
+#### Response Fields Always Nil/Empty
+
+These Response fields exist on the `Data.define` but are **never populated** by the executor today:
+
+- `agent` — always nil
+- `cache` — always `{}`
+- `safety` — always nil
+- `rate_limit` — always nil
+- `features` — always nil
+- `deprecation` — always nil
+- `validation` — always nil
+- `wire` — always nil
+- `retry` — always nil
 
 ## Design Principles
 
@@ -27,6 +96,8 @@ schema_version: "1.0.0"   # semver -- major.minor.patch
 
 ## Message
 
+> **Implementation status: NOT IMPLEMENTED** — No `Message` struct exists. Messages are plain hashes with only `role` and `content` in the pipeline. `ConversationStore` persists additional fields (`id`, `seq`, `parent_id`, `agent_id`, `created_at`) in its DB rows, but these are not surfaced as a structured Message object.
+
 The atomic unit of conversation. Every exchange between user, assistant, and tools is a Message.
 
 ```
@@ -78,6 +149,8 @@ message.text  # returns text content regardless of String vs Array<ContentBlock>
 
 ## Content Blocks
 
+> **Implementation status: NOT IMPLEMENTED** — No `ContentBlock` struct exists. Content is always a plain String in the pipeline. The only place a typed block hash is constructed is for system prompt caching (`{ type: :text, content: ..., cache_control: ... }`). No image, audio, video, document, tool_use, tool_result, citation, or error block handling exists.
+
 Multimodal content. When `Message.content` is an array, each element is a ContentBlock.
 
 ### Block Types
@@ -199,6 +272,8 @@ data:            Hash?         # structured error data
 
 ## Tool
 
+> **Implementation status: PARTIAL** — `ToolAdapter` wraps `RubyLLM::Tool` with `name`, `description`, `parameters`. The `source` field exists as a parallel lookup in `find_tool_source` (not on the tool object). `version` does not exist.
+
 Tool definitions available to the LLM.
 
 ```
@@ -227,6 +302,8 @@ Used by RBAC (can this caller use tools from this source?) and audit (which syst
 
 ## ToolCall
 
+> **Implementation status: PARTIAL** — Tool calls are hashes with `id`, `name`, `arguments` and optionally `exchange_id`, `source`, `status`, `duration_ms`, `result` merged from matching Timeline events. The `error` field is never populated. Timeline lookup uses tool name (not call ID), so duplicate invocations of the same tool in one response will only have execution data for the last invocation.
+
 A tool invocation made by the assistant, with execution results.
 
 ```
@@ -251,6 +328,8 @@ Always a parsed Hash, never a JSON string. Provider adapters that receive argume
 
 ## ToolChoice
 
+> **Implementation status: STUB** — Field exists on Request, defaults to `{ mode: :auto }`. The `:specific` mode's `name` field is not handled. The `tool_choice` value is never forwarded to the underlying RubyLLM provider call.
+
 Controls how the LLM uses available tools.
 
 ```
@@ -263,6 +342,8 @@ ToolChoice
 
 ## Enrichment
 
+> **Implementation status: IMPLEMENTED** — RAG and GAIA enrichments work. Note: value shapes are inconsistent across pipeline steps — not all enrichments include `content:`, `data:`, `duration_ms:`, `timestamp:` as spec describes.
+
 Things that *shaped* the request during processing. Any system can contribute enrichments without schema changes. Enrichments modify or observe the request -- for decisions and outcomes, see [Audit](#audit).
 
 Enrichments are a **Hash keyed by `"source:type"`**, not an array. This enables direct lookup and clean request-vs-response comparison without looping.
@@ -319,6 +400,8 @@ Adding a new system requires zero schema changes -- just add a new key.
 
 ## Prediction
 
+> **Implementation status: PARTIAL** — Request-side predictions work (components can contribute predictions). Response-side actuals (`actual_value`, `accurate`) are never filled in — no post-execution comparison occurs.
+
 Hypothesis recorded before execution, compared to reality after execution. Enables self-improving systems. Any component in the pipeline can contribute predictions.
 
 Predictions are a **Hash keyed by `"source:type"`**, same pattern as enrichments. Direct lookup, no looping.
@@ -395,6 +478,8 @@ response.predictions.count { |_, v| v[:correct] }.to_f / response.predictions.si
 
 ## Tracing & Correlation
 
+> **Implementation status: IMPLEMENTED** — `trace_id`, `span_id`, `exchange_id` all generated and propagated via `Pipeline::Tracing`.
+
 OpenTelemetry-compatible distributed tracing. Groups related requests across agentic loops, forks, and multi-step tasks.
 
 ```
@@ -424,6 +509,8 @@ Tracing is present on Request, Response, ErrorResponse, and Chunk.
 
 ## Exchange (Per-Hop Tracking)
 
+> **Implementation status: IMPLEMENTED** — `conversation_id`, `request_id` (mapped to `id`), and `exchange_id` all generated via `Pipeline::Tracing` and propagated through the pipeline.
+
 Three-level ID hierarchy inspired by SIP's Call-ID / CSeq / Branch/Via model. Tracks every hop within a single request.
 
 ```
@@ -487,6 +574,8 @@ In practice, each exchange would become a child span under the request's span in
 
 ## Data Classification & Compliance
 
+> **Implementation status: PARTIAL** — Classification labels are applied to requests. However, routing restrictions (e.g., preventing PHI-tagged data from going to certain providers) are not enforced.
+
 Data governance for enterprise adoption. Controls where data can be processed, how long it's retained, and what it contains.
 
 ```
@@ -538,6 +627,8 @@ Provider registry includes each provider's processing jurisdiction. Router match
 
 ## Caller
 
+> **Implementation status: IMPLEMENTED** — Caller identity propagated through the pipeline. `Profile.derive` reads `caller[:requested_by][:type]` to determine step skipping.
+
 Auth-level identity tracking. Who authenticated to make this request, and on whose behalf. Separate from `agent` (which tracks AI entity identity).
 
 ```
@@ -602,6 +693,8 @@ RBAC checks `caller.requested_by` for permission evaluation. If `requested_for`
 
 ## Agent Identity
 
+> **Implementation status: NOT IMPLEMENTED** — The `agent` field exists on both Request and Response but is always nil. No agent identity is attached during pipeline execution.
+
 Tracks which AI entity is executing the request. Not about auth (that's `caller`) -- about the AI agent doing the work.
 
 ```
@@ -648,6 +741,8 @@ Multiple LLM requests can share a `task_id`, enabling: "Show me everything that
 
 ## Billing & Budget
 
+> **Implementation status: PARTIAL** — Per-request cost cap works. Cumulative budget tracking (daily/monthly limits) is not implemented. Metering module exists but is not wired into pipeline steps.
+
 Cost tracking, budget enforcement, and rate limiting.
 
 ```
@@ -690,6 +785,8 @@ Checked in the pipeline before the provider call:
 
 ## Test & Evaluation Mode
 
+> **Implementation status: IMPLEMENTED** — Test mode flags propagated through the pipeline.
+
 Controls for testing, benchmarking, replay, and experimentation.
 
 ```
@@ -743,6 +840,8 @@ Experiment results are tracked via predictions (expected: better quality with GA
 
 ## Modality
 
+> **Implementation status: NOT IMPLEMENTED** — The `modality` field exists on Request but is not acted upon by the pipeline or provider adapters.
+
 Declares input and output modality expectations. Guides routing (not all providers support all combinations) and future-proofs for multimodal evolution.
 
 ```
@@ -799,6 +898,8 @@ Provider capabilities:
 
 ## Lifecycle Hooks
 
+> **Implementation status: PARTIAL** — Pre/post hooks on Request are supported. Response-side hook firing is not implemented.
+
 Caller-declared injection points in the pipeline. Named hooks registered by extensions or configuration.
 
 ```
@@ -839,6 +940,8 @@ Hooks receive the full request/response context and can add enrichments, but can
 
 ## Feedback
 
+> **Implementation status: NOT IMPLEMENTED** — No Feedback struct, class, or storage exists. No code submits, receives, or stores feedback.
+
 User or automated quality feedback on specific messages. Lives on the Conversation, not on individual requests. Closes the learning loop.
 
 ```
@@ -884,6 +987,8 @@ Quality checkers and GAIA can also submit feedback:
 
 ## Audit
 
+> **Implementation status: IMPLEMENTED** — Audit records are populated by the pipeline. Note: uses symbol keys (`:step`, `:action`), not string keys as some examples in this spec show.
+
 Record of what *happened* during pipeline processing -- decisions, actions, outcomes. Separate from enrichments (which record what *shaped* the request). Response-only.
 
 Audit is a **Hash keyed by `"step:action"`**, same pattern as enrichments and predictions.
@@ -990,6 +1095,8 @@ response.audit[:"persistence:store"][:data][:method]  # => :direct
 
 ## Pipeline Timeline
 
+> **Implementation status: IMPLEMENTED** — `Pipeline::Timeline` records ordered events with participant tracking.
+
 Inspired by [Homer/SIPCAPTURE](https://github.com/sipcapture/homer) call flow diagrams. A unified, globally-sequenced timeline of **everything** that happened during a request. Reconstructs the full call flow across all systems -- enrichments, audit, tool calls, provider calls, connections -- in one ordered record.
 
 This is the **one place an array is correct**. Timeline is ordered data, not lookup data. You iterate it in sequence to reconstruct the call flow, like Homer's ladder diagram.
@@ -1125,6 +1232,8 @@ The timeline is built during pipeline execution and returned on the response. It
 
 ## Participants
 
+> **Implementation status: IMPLEMENTED** — Tracked via `Pipeline::Timeline`.
+
 All systems that touched this request. Enables Homer-style column headers for call flow visualization. Response-only, populated by the pipeline.
 
 ```
@@ -1154,6 +1263,8 @@ Auto-populated: every unique `from` and `to` value in the timeline becomes a par
 
 ## Wire Capture
 
+> **Implementation status: NOT IMPLEMENTED** — Response `wire` field is always nil. No capture of raw provider payloads occurs.
+
 Raw request and response payloads as sent to/received from the provider. For debugging translator issues, you need both sides of the wire. Opt-in (can be expensive to store).
 
 Keyed by `exchange_id` -- one capture per provider call, not per request. A request with retries or tool loops produces multiple wire captures.
@@ -1223,6 +1334,8 @@ This lives on `response.routing.connection` since it's part of the routing outco
 
 ## Retry
 
+> **Implementation status: NOT IMPLEMENTED** — Response `retry` field is always nil. Retry logic exists in the executor (rate limit rescue) but results are not captured in the retry struct.
+
 Distinct from escalation. Retries are the same provider/model attempted again after a transient failure. Escalation is switching to a different provider/model.
 
 ```
@@ -1269,6 +1382,8 @@ response.retry = {
 
 ## Content Safety
 
+> **Implementation status: NOT IMPLEMENTED** — Response `safety` field is always nil. Provider safety results are not captured.
+
 Provider-reported content filtering results. Different from classification (which is our data governance). This is the provider saying "I evaluated this content against my safety policies."
 
 Response-only. Not all providers return this.
@@ -1322,6 +1437,8 @@ response.safety = {
 
 ## Rate Limit State
 
+> **Implementation status: NOT IMPLEMENTED** — Response `rate_limit` field is always nil. Provider rate limit headers are not captured (rate limit errors are rescued and retried, but quota state is not stored).
+
 Provider quota state returned in response headers. Structured and always captured (not opt-in like wire). Critical for routing decisions.
 
 ```
@@ -1361,6 +1478,8 @@ end
 
 ## Thinking & Reasoning
 
+> **Implementation status: PARTIAL** — Request-side thinking configuration is mapped to the first-class `thinking` field by `from_chat_args`. Response-side `thinking` field exists on the Response struct but is **never populated** by the executor — it is always nil.
+
 Controls for extended thinking, chain-of-thought, and reasoning behavior. Separate from generation parameters (temperature, top_p) because reasoning is about *how deeply* the model thinks, not *how randomly* it samples.
 
 ### Request side
@@ -1395,6 +1514,8 @@ Thinking tokens are tracked separately from regular output tokens because they h
 
 ## Context Window Utilization
 
+> **Implementation status: NOT IMPLEMENTED** — `tokens.context_window`, `tokens.utilization`, and `tokens.headroom` are never populated on the Response. Only `input_tokens` and `output_tokens` are set.
+
 Expands response-side tokens with capacity information. Drives context strategy decisions.
 
 Added to `response.tokens`:
@@ -1439,6 +1560,8 @@ end
 
 ## Structured Output Validation
 
+> **Implementation status: NOT IMPLEMENTED** — Response `validation` field is always nil. `StructuredOutput` module exists for enforcing schemas but does not populate this struct.
+
 When `response_format.type` is `:json` or `:json_schema`, reports whether the response actually validated.
 
 Response-only. Added to response alongside quality.
@@ -1479,6 +1602,8 @@ response.validation = {
 
 ## Provider Features
 
+> **Implementation status: NOT IMPLEMENTED** — Response `features` field is always nil.
+
 Post-hoc report of which provider-specific features actually activated on this request. Different from capabilities (what the provider CAN do) -- this is what it DID.
 
 Response-only. Hash-keyed by feature name.
@@ -1519,6 +1644,8 @@ end
 
 ## Model Deprecation
 
+> **Implementation status: NOT IMPLEMENTED** — Response `deprecation` field is always nil.
+
 Structured deprecation warnings from providers. Separate from the `warnings` array because automated systems need to act on these programmatically.
 
 Response-only.
@@ -1564,6 +1691,8 @@ end
 
 ## Cache
 
+> **Implementation status: PARTIAL** — Request-side `cache` field is mapped to the first-class field by `from_chat_args` (defaults to `{ strategy: :default, cacheable: true }`). Response-side `cache` field is always `{}`.
+
 Symmetric caching controls on request and response. Replaces a flat strategy symbol with structured metadata.
 
 ### Request side (what I want)
@@ -1631,6 +1760,8 @@ Response: cache: { hit: true, key: "sha256:abc123", tier: :local, age: 45, expir
 
 ## Request
 
+> **Implementation status: IMPLEMENTED (envelope)** — All 32 fields exist as `Data.define` members with `.build` and `.from_chat_args` constructors. All fields including `generation`, `thinking`, `response_format`, `context_strategy`, `cache`, `fork`, `tokens`, `stop`, `modality`, `hooks`, `idempotency_key`, `ttl`, `metadata`, `enrichments`, and `predictions` are mapped to first-class struct members. Convenience accessors (`.model`, `.provider`) described in the spec are not defined.
+
 What goes into the Legion::LLM pipeline.
 
 ```
@@ -1795,6 +1926,8 @@ For queue ordering when requests go through RMQ:
 
 ## Response
 
+> **Implementation status: PARTIAL (envelope)** — All 34 fields exist as `Data.define` members. 9 fields are always nil/empty (see status matrix above). `routing` populates `provider`, `model`, `strategy`, `tier`, `escalated`, `escalation_chain`, `latency_ms`. `stop.reason` extracted from provider response (falls back to `:end_turn`). `quality` returns `{ score:, band:, source:, signals: }` from `ConfidenceScorer` (not `{ score:, acceptable:, checker: }` as the Response struct below shows). `cost` populated via `CostEstimator.estimate` with `estimated_usd`, `provider`, `model`. Convenience accessors (`.model`, `.provider`) are not defined.
+
 What comes back from the Legion::LLM pipeline.
 
 ```
@@ -1843,7 +1976,7 @@ Response
 
   # Stop (symmetric with request)
   stop:              Hash
-    reason:          Symbol       # :end_turn, :tool_calls, :max_tokens, :safety, :stop_sequence
+    reason:          Symbol       # :end_turn, :tool_use, :max_tokens, :safety, :stop_sequence
     sequence:        String?      # which stop sequence was hit (nil if none)
 
   # Tools (symmetric with request)
@@ -1984,6 +2117,8 @@ response.participants          # ["pipeline", "rbac", "provider:claude", ...]
 
 ## Chunk (Streaming)
 
+> **Implementation status: NOT IMPLEMENTED** — No `Chunk` struct exists. Streaming (`call_stream`) yields raw RubyLLM chunk objects directly to callers with no translation to the spec format.
+
 Incremental data during a streamed response.
 
 ```
@@ -2015,6 +2150,8 @@ Chunk
 
 ## ErrorResponse
 
+> **Implementation status: NOT IMPLEMENTED** — No `ErrorResponse` struct exists. Errors are raised as exceptions from the `Legion::LLM` error hierarchy: `LLMError` (base), `AuthError`, `RateLimitError`, `ContextOverflow`, `ProviderError`, `ProviderDown`, `UnsupportedCapability`, `PipelineError`, `TokenBudgetExceeded`, `EmbeddingUnavailableError`. Additionally, `EscalationExhausted`, `DaemonDeniedError`, `DaemonRateLimitedError`, and `PrivacyModeError` inherit from `StandardError` directly (not `LLMError`). These are Ruby exceptions, not structured response payloads.
+
 Standard error format for failed requests.
 
 ```
@@ -2059,6 +2196,8 @@ ErrorResponse
 
 ## Conversation
 
+> **Implementation status: PARTIAL** — `ConversationStore` exists as an in-memory LRU (256 slots) with optional DB persistence. No `Conversation` struct — conversations are plain hashes (`{ messages: [], metadata: {}, lru_tick: N }`). DB persistence stores `id`, `caller_identity`, `metadata` (JSON blob), `created_at`, `updated_at`. Most spec fields (`title`, `summary`, `state`, `shared`, `participants`, `tags`, `pinned`, `usage_total`, `routing_history`) exist only as arbitrary metadata blob entries, not first-class fields.
+
 The persistent conversation object stored in the ConversationStore.
 
 ```
@@ -2119,6 +2258,8 @@ Legion::LLM.chat(
 
 ## Config (Generation Parameters)
 
+> **Implementation status: PARTIAL** — Generation parameters are mapped to the first-class `generation` field by `from_chat_args`. However, provider adapters only forward `model` and `provider` to RubyLLM, not temperature/top_p/etc from the `generation` hash.
+
 Sent in `request.generation`. Provider adapters map supported parameters and ignore unsupported ones.
 
 ```
@@ -2162,6 +2303,8 @@ response_format:
 
 ## Provider Adapter Contract
 
+> **Implementation status: PARTIAL** — Provider LEXs (extensions-ai/) exist and work for chat/embed. The formal `ProviderAdapter` interface with `Translator` is not enforced — providers integrate via RubyLLM's native provider system.
+
 Every provider LEX must implement `Legion::LLM::ProviderAdapter` including a `Translator`.
 
 ### Required methods

data/lib/legion/llm/conversation_store.rb

@@ -373,11 +373,13 @@ module Legion
         end
 
         def db_append_message(conversation_id, msg)
+          content = msg[:content]
+          content = content.to_json unless content.is_a?(String) || content.nil?
           row = {
             conversation_id: conversation_id,
             seq:             msg[:seq],
             role:            msg[:role].to_s,
-            content:         msg[:content],
+            content:         content,
             provider:        msg[:provider]&.to_s,
             model:           msg[:model]&.to_s,
             input_tokens:    msg[:input_tokens],

data/lib/legion/llm/patches/ruby_llm_parallel_tools.rb

@@ -0,0 +1,102 @@
+# frozen_string_literal: true
+
+# Patch: RubyLLM::Chat parallel tool call execution
+#
+# RubyLLM's default `handle_tool_calls` iterates tool calls serially with
+# `.each_value`, meaning when an LLM returns N tool calls in a single response
+# they execute one-at-a-time. This patch replaces that loop with concurrent
+# thread execution so all tool calls in a batch run in parallel, and results
+# are collected before re-prompting the model.
+#
+# Additionally, RubyLLM fires `on_tool_result` with the raw tool return value
+# (a String/Hash/etc.) which carries no `tool_call_id`. The legion-interlink
+# bridge script's `serialize_tool_result` needs a `tool_call_id` field to
+# match results back to the correct tool call slot in the UI — without it
+# every result falls back to name-based matching, which breaks when multiple
+# tools of the same name run in parallel and leaves them stuck on RUNNING.
+#
+# Fix: wrap each result in a ToolResultWrapper that exposes both the raw
+# content/result AND the originating tool_call_id / id fields.
+#
+# NOTE: This is a temporary shim. When RubyLLM is replaced this file goes away.
+#
+# Thread safety notes:
+#   - Each tool call executes in its own thread.
+#   - @on[:tool_call] fires per-thread (fast, just event emission — safe).
+#   - @on[:tool_result] fires per-thread with the wrapper object.
+#   - add_message is called serially after all threads complete to preserve
+#     message ordering and avoid races on @messages.
+#   - If ANY tool returns a RubyLLM::Tool::Halt, complete() is skipped —
+#     matching the original semantics.
+
+module Legion
+  module LLM
+    module Patches
+      # Wraps a raw tool result value so that the bridge-script's
+      # serialize_tool_result can read both :tool_call_id/:id (for UI matching)
+      # and :result/:content (for the result payload) off a single object.
+      ToolResultWrapper = Struct.new(:result, :content, :tool_call_id, :id, :tool_name) do
+        # Delegate is_a? checks for RubyLLM::Tool::Halt so the caller can still
+        # detect halt results transparently.
+        def is_a?(klass)
+          result.is_a?(klass) || super
+        end
+
+        alias_method :kind_of?, :is_a?
+      end
+
+      module RubyLLMParallelTools
+        def handle_tool_calls(response, &)
+          tool_calls = response.tool_calls.values
+
+          # Dispatch all tool calls concurrently, preserving original order.
+          threads = tool_calls.map do |tool_call|
+            Thread.new do
+              @on[:new_message]&.call
+              @on[:tool_call]&.call(tool_call)
+              raw = execute_tool(tool_call)
+              # Wrap so serialize_tool_result in the bridge script gets an ID.
+              wrapper = ToolResultWrapper.new(
+                raw,                  # :result  — raw value (String/Hash/Halt/etc.)
+                raw,                  # :content — alias for bridge compat
+                tool_call.id,         # :tool_call_id
+                tool_call.id,         # :id
+                tool_call.name        # :tool_name
+              )
+              @on[:tool_result]&.call(wrapper)
+              { tool_call: tool_call, raw: raw }
+            end
+          end
+
+          begin
+            results = threads.map(&:value) # block until all complete
+
+            # Commit messages serially — preserves ordering, avoids @messages races.
+            halt_result = nil
+            results.each do |entry|
+              tool_call    = entry[:tool_call]
+              raw          = entry[:raw]
+              tool_payload = raw.is_a?(RubyLLM::Tool::Halt) ? raw.content : raw
+              content      = content_like?(tool_payload) ? tool_payload : tool_payload.to_s
+              message      = add_message(role: :tool, content: content, tool_call_id: tool_call.id)
+              @on[:end_message]&.call(message)
+              halt_result = raw if raw.is_a?(RubyLLM::Tool::Halt)
+            end
+
+            reset_tool_choice if forced_tool_choice?
+            halt_result || complete(&)
+          ensure
+            threads.each do |thread|
+              thread.kill if thread.alive?
+              thread.join
+            end
+          end
+        end
+      end
+    end
+  end
+end
+
+# Use prepend (not alias_method/override) so the patch stays clearly visible
+# in the ancestor chain and is easy to remove when RubyLLM is dropped.
+RubyLLM::Chat.prepend(Legion::LLM::Patches::RubyLLMParallelTools)