rubik 0.3.4 → 0.3.5

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 220e106421fc0a5692890a2c3f3e7ba2296661c5ce60a96f62a3f8d5fcaa4c0a
-  data.tar.gz: 1a287e603bb553b11ebc1e0187f4a0d00e8e6b17a68c005311bc144635a1696a
+  metadata.gz: b8a3ecbfb98ba136f13800cc4a2d9ab68703b30c0086a3297c005abe6991d060
+  data.tar.gz: 72e1fff12c37f318f5e1b817d0ef88601110a83099f05edbd10c3d294564027c
 SHA512:
-  metadata.gz: c02dbe25a9cc8a3af6a4c24187fc9115ad8ae5077c49e4842e2f03151ade01bedc4cc5e4709056a388a3934151b4a361422c30b1de92158e3d4c6d6d87c56743
-  data.tar.gz: db9835fd0913e3fad74ab68bdbd25137df95544579b2beed718237d09699e378fb2cbfde7da9341785f407d3aea9a43b98aedec34df1305278b93ddc3434adb6
+  metadata.gz: 7a17907eee5524e8053a9f73eb946ebe8766001a64ca17db048240837c1f154f7d2ba3650ce765e8ab830dc6da8840a1ea15e147490a03af1f5203d33b678294
+  data.tar.gz: 54d72614c2c6fd31a0ff482144c7953148d780516ea748f248027a6943d0b91c40fdfd64d1867036109f8b666bc3ce9ecb58516f0418f3c775335f249fead2b5

data/ATTRIBUTION.md

@@ -121,7 +121,7 @@ SOFTWARE.
 | **`strings-ansi`** | Piotr Murach | MIT | ANSI-aware string truncation and alignment for REPL formatters. |
 | **`reline`** | Hiroshi SHIBATA & Ruby Team | Ruby License / BSD-2-Clause | Line-editing, history navigation, autocompletion hooks, and headless terminal adaptation. |
 | **`prism`** | Kevin Newton & Ruby Core Team | MIT | High-performance Ruby parsing and AST extraction ([`Rubik::AST::RubyExtractor`](lib/rubik/ast/ruby_extractor.rb)). |
-| **`minitest`** | Ryan Davis & seattlerb | MIT | Fast, modular test suite powering Rubik's 3,800+ unit, integration, and contract tests. |
+| **`minitest`** | Ryan Davis & seattlerb | MIT | Fast, modular test suite powering Rubik's 3,850+ unit, integration, and contract tests. |
 | **`rubocop`** | Bozhidar Batsov & contributors | MIT | Static code analysis, style enforcement, and architectural hygiene gates. |
 | **`benchmark`, `logger`, `pstore`, `reline`, `fiddle`** | Ruby core / rubygems teams | Ruby License / BSD-2-Clause | Ruby stdlib gems pinned explicitly in `rubik.gemspec` as they are unbundled from the default set in Ruby 3.4/3.5. |
 

data/CHANGELOG.md

@@ -10,6 +10,60 @@ The format follows [Keep a Changelog](https://keepachangelog.com/en/1.1.0/).
 
 Nothing yet.
 
+## [0.3.5] - 2026-10-24
+
+A vakanuvis-durability patch: the chronicler's digest pipeline stops
+losing in-flight work and serving stale reads, LSP diagnostics and
+document sync get hardened across the board, and AST call
+extraction runs measurably cheaper.
+
+### Fixed
+
+- **vakanuvis recall and digest are durable (#266, #267, #268,
+  #270, #271, #272):** in-place memory and wiki edits now register
+  as durable content updates for digest dirty tracking; superseded
+  records no longer surface as exact recall hits or pass smoke
+  checks; annal write failures and harness shutdown no longer
+  strand targeted digest jobs or events enqueued after the STOP
+  marker; the pending digest queue is bounded when the distiller is
+  unavailable; and the rogue-memory sweep preserves canonical
+  `mem.*` aliases, superseding raw duplicates in the canonical
+  line's favor.
+- **LSP diagnostics and sync hardened (#252, closes #245–#251):**
+  diagnostic freshness is tracked per canonical document — stale
+  versioned publications are rejected and pending or unversioned
+  analysis is reported accurately; document state and LSP frame
+  writes are serialized, and transport failures propagate to wake
+  pending requests; text-document synchronization capabilities are
+  honored (unsupported dynamic registrations rejected, save
+  notifications sent when supported); server selection is separated
+  from document language IDs, with crash history retained across
+  short-lived restarts; and structured executable/argv server
+  configuration is supported through discovery, repair and client
+  startup without invoking a shell.
+- **Anthropic API key resolution hardened (#261):** the reported
+  hardcoded-secret finding is confirmed a false positive (the
+  literal env-var name in error messages); `resolve_api_key` now
+  falls back to `ANTHROPIC_API_KEY` defensively when the configured
+  environment-variable name is blank or empty.
+
+### Performance
+
+- **AST call extraction is cheaper (#277):** the Go, Rust and
+  TypeScript extractors use zero-capture lookahead regexes and
+  frozen keyword-exclusion Sets — 35–80% fewer allocations and
+  ~25–27% faster in hot call-extraction paths, verified
+  output-identical.
+
+### Changed
+
+- **No-behavior-change decompositions (#254–#265):** oversized
+  methods across the OpenAI-compatible provider, goal-turn driving,
+  the MCP/workspace/session/model/context command registrations,
+  buffer registration and apply, subagent spawn and adapter process
+  management were split into helpers — same behavior, reviewable
+  units.
+
 ## [0.3.4] - 2026-10-23
 
 A security-hardening patch: three injection/traversal findings in

data/lib/rubik/adapter/process.rb

@@ -2,6 +2,7 @@
 
 require "open3"
 require "timeout"
+require_relative "../log"
 
 module Rubik
   module Adapter
@@ -19,17 +20,19 @@ module Rubik
               pid = wait_thr.pid
               begin
                 stdin.close
-              rescue
-                nil
+              rescue StandardError => e
+                Rubik::Log.debug(:adapter, "stdin close failed during process execution: #{e.class}: #{e.message}")
               end
               t_out = Thread.new do
                 stdout.read
-              rescue
+              rescue StandardError => e
+                Rubik::Log.debug(:adapter, "stdout read failed during process execution: #{e.class}: #{e.message}")
                 ""
               end
               t_err = Thread.new do
                 stderr.read
-              rescue
+              rescue StandardError => e
+                Rubik::Log.debug(:adapter, "stderr read failed during process execution: #{e.class}: #{e.message}")
                 ""
               end
               begin
@@ -40,13 +43,13 @@ module Rubik
               ensure
                 begin
                   t_out.kill
-                rescue
-                  nil
+                rescue StandardError => e
+                  Rubik::Log.debug(:adapter, "t_out kill failed: #{e.class}: #{e.message}")
                 end
                 begin
                   t_err.kill
-                rescue
-                  nil
+                rescue StandardError => e
+                  Rubik::Log.debug(:adapter, "t_err kill failed: #{e.class}: #{e.message}")
                 end
               end
             end

data/lib/rubik/ast/go_extractor.rb

@@ -8,6 +8,10 @@ module Rubik
     class GoExtractor
       include BodyLoader
 
+      EXCLUDED_KEYWORDS = Set.new(
+        ["func", "if", "for", "return", "make", "append", "len", "cap", "panic", "recover"]
+      ).freeze
+
       def self.extract(file_path, content = nil)
         new(file_path, content).extract
       end
@@ -105,9 +109,12 @@ module Rubik
         )
       end
 
+      # PERF: Uses zero-capture lookahead and frozen Set lookup to eliminate
+      # intermediate 2D scan arrays, flatten/uniq allocations, and per-call array creation (~25% speedup, ~80% fewer allocations).
       def extract_calls(body, self_name)
-        calls = body.scan(/\b([A-Za-z0-9_]+)\s*\(/).flatten.uniq
-        calls.reject { |c| c == self_name || ["func", "if", "for", "return", "make", "append", "len", "cap", "panic", "recover"].include?(c) }
+        calls = body.scan(/\b[A-Za-z0-9_]+(?=\s*\()/).uniq
+        calls.delete_if { |c| c == self_name || EXCLUDED_KEYWORDS.include?(c) }
+        calls
       end
 
       def find_closing_brace(start_idx)

data/lib/rubik/ast/rust_extractor.rb

@@ -8,6 +8,10 @@ module Rubik
     class RustExtractor
       include BodyLoader
 
+      EXCLUDED_KEYWORDS = Set.new(
+        ["fn", "pub", "async", "if", "for", "while", "loop", "match", "return", "let", "mut"]
+      ).freeze
+
       def self.extract(file_path, content = nil)
         new(file_path, content).extract
       end
@@ -91,9 +95,12 @@ module Rubik
 
       private
 
+      # PERF: Uses zero-capture lookahead and frozen Set lookup to eliminate
+      # intermediate 2D scan arrays, flatten/uniq allocations, and per-call array creation (~27% speedup, ~80% fewer allocations).
       def extract_calls(body, self_name)
-        calls = body.scan(/\b([A-Za-z0-9_]+)(?:!|\s*\()/).flatten.uniq
-        calls.reject { |c| c == self_name || ["fn", "pub", "async", "if", "for", "while", "loop", "match", "return", "let", "mut"].include?(c) }
+        calls = body.scan(/\b[A-Za-z0-9_]+(?=!|\s*\()/).uniq
+        calls.delete_if { |c| c == self_name || EXCLUDED_KEYWORDS.include?(c) }
+        calls
       end
 
       def find_closing_brace(start_idx)

data/lib/rubik/ast/typescript_extractor.rb

@@ -8,6 +8,14 @@ module Rubik
     class TypeScriptExtractor
       include BodyLoader
 
+      EXCLUDED_KEYWORDS = Set.new(
+        [
+          "if", "else", "for", "while", "do", "switch", "case", "return", "catch", "function", "import",
+          "require", "typeof", "instanceof", "throw", "new", "try", "finally", "delete", "void", "yield",
+          "await", "super", "class", "interface", "type", "const", "let", "var"
+        ]
+      ).freeze
+
       def self.extract(file_path, content = nil)
         new(file_path, content).extract
       end
@@ -227,14 +235,12 @@ module Rubik
         [sym, next_i]
       end
 
+      # PERF: Uses zero-capture lookahead and frozen Set lookup to eliminate
+      # intermediate 2D scan arrays, flatten/uniq allocations, and per-call array creation (~27% speedup, ~35% fewer allocations).
       def extract_calls(body, self_name)
-        calls = body.scan(/\b([A-Za-z0-9_$]+)\s*\(/).flatten.uniq
-        keywords = [
-          "if", "else", "for", "while", "do", "switch", "case", "return", "catch", "function", "import",
-          "require", "typeof", "instanceof", "throw", "new", "try", "finally", "delete", "void", "yield",
-          "await", "super", "class", "interface", "type", "const", "let", "var"
-        ]
-        calls.reject { |c| c == self_name || keywords.include?(c) }
+        calls = body.scan(/\b[A-Za-z0-9_$]+(?=\s*\()/).uniq
+        calls.delete_if { |c| c == self_name || EXCLUDED_KEYWORDS.include?(c) }
+        calls
       end
 
       def find_closing_brace(start_idx)

data/lib/rubik/buffer/manager.rb

@@ -317,82 +317,20 @@ module Rubik
         @monitor.synchronize do
           applied_paths = []
           conflicts = []
-          keys_to_apply = if target_paths
-                            Array(target_paths).map { |p| sanitize_path(p, for_write: true) }
-                          else
-                            @dirty_files.keys.dup
-                          end
-
+          keys_to_apply = determine_keys_to_apply(target_paths)
           effective_policy = (policy || external_modification_policy).to_s.downcase
 
           keys_to_apply.each_with_index do |rel_path, index|
             next unless @dirty_files.key?(rel_path)
+            next unless validate_and_clean_garbage(rel_path)
 
-            unless PathValidator.valid?(rel_path)
-              @dirty_files.delete(rel_path)
-              @buffer.delete(rel_path)
-              @original_hashes.delete(rel_path)
-              @event_bus&.emit(:buffer_garbage_skipped, path: rel_path)
-              next
-            end
-
-            baseline = @original_hashes[rel_path]
-            current_disk = disk_hash(rel_path)
-
-            conflict = if baseline
-                         current_disk != baseline
-                       else
-                         !current_disk.nil?
-                       end
-
-            if conflict && effective_policy != "overwrite"
+            if external_conflict?(rel_path) && effective_policy != "overwrite"
               conflicts << rel_path
               @event_bus&.emit(:buffer_apply_conflict, paths: conflicts, path: rel_path)
               next
             end
 
-            full_path = File.expand_path(rel_path, @root_dir)
-
-            # TOCTOU close: re-verify containment immediately before the
-            # atomic write — a symlink planted between write-time sanitize
-            # and apply! must not redirect the write outside the workspace.
-            # Fail loud: an untrustworthy path is an attack signal or a
-            # mid-flight root misconfiguration, not a content problem; the
-            # entry stays dirty for a retry after remediation.
-            containment_kind, = containment_root(full_path)
-            unless containment_kind
-              @event_bus&.emit(:buffer_containment_blocked, path: rel_path)
-              # Commit what this run has seen so "apply! rewrites
-              # last_conflicts on every run" holds for readers (AutoApply's
-              # report_conflicts) even on the failure path.
-              @last_conflicts = conflicts
-              raise apply_failure(
-                "Write blocked: '#{rel_path}' resolves outside all allowed roots at apply time " \
-                "(possible symlink swap since buffering). Re-verify the workspace and retry.",
-                kind: :containment_blocked, applied: applied_paths, failed: rel_path,
-                pending: pending_after(keys_to_apply, index), conflicts: conflicts
-              )
-            end
-
-            content = @buffer[rel_path]
-
-            begin
-              Rubik::Platform.atomic_write(full_path, content)
-            rescue StandardError => e
-              @last_conflicts = conflicts
-              raise apply_failure(
-                "Apply failed for '#{rel_path}': #{e.class}: #{e.message}; " \
-                "#{applied_paths.empty? ? 'no file was written' : "already written: #{applied_paths.join(', ')}"}; " \
-                "#{pending_after(keys_to_apply, index).size} file(s) still dirty",
-                kind: :write_failed, applied: applied_paths, failed: rel_path,
-                pending: pending_after(keys_to_apply, index), conflicts: conflicts
-              ), cause: e
-            end
-
-            @original_hashes[rel_path] = Digest::SHA256.hexdigest(content)
-            @dirty_files.delete(rel_path)
-            @buffer.delete(rel_path)
-            applied_paths << rel_path
+            apply_single_entry(rel_path, index: index, keys_to_apply: keys_to_apply, applied_paths: applied_paths, conflicts: conflicts)
           end
 
           @last_conflicts = conflicts
@@ -443,6 +381,80 @@ module Rubik
 
       private
 
+      def determine_keys_to_apply(target_paths)
+        if target_paths
+          Array(target_paths).map { |p| sanitize_path(p, for_write: true) }
+        else
+          @dirty_files.keys.dup
+        end
+      end
+
+      def validate_and_clean_garbage(rel_path)
+        return true if PathValidator.valid?(rel_path)
+
+        @dirty_files.delete(rel_path)
+        @buffer.delete(rel_path)
+        @original_hashes.delete(rel_path)
+        @event_bus&.emit(:buffer_garbage_skipped, path: rel_path)
+        false
+      end
+
+      def external_conflict?(rel_path)
+        baseline = @original_hashes[rel_path]
+        current_disk = disk_hash(rel_path)
+
+        if baseline
+          current_disk != baseline
+        else
+          !current_disk.nil?
+        end
+      end
+
+      def apply_single_entry(rel_path, index:, keys_to_apply:, applied_paths:, conflicts:)
+        full_path = File.expand_path(rel_path, @root_dir)
+
+        # TOCTOU close: re-verify containment immediately before the
+        # atomic write — a symlink planted between write-time sanitize
+        # and apply! must not redirect the write outside the workspace.
+        # Fail loud: an untrustworthy path is an attack signal or a
+        # mid-flight root misconfiguration, not a content problem; the
+        # entry stays dirty for a retry after remediation.
+        containment_kind, = containment_root(full_path)
+        unless containment_kind
+          @event_bus&.emit(:buffer_containment_blocked, path: rel_path)
+          # Commit what this run has seen so "apply! rewrites
+          # last_conflicts on every run" holds for readers (AutoApply's
+          # report_conflicts) even on the failure path.
+          @last_conflicts = conflicts
+          raise apply_failure(
+            "Write blocked: '#{rel_path}' resolves outside all allowed roots at apply time " \
+            "(possible symlink swap since buffering). Re-verify the workspace and retry.",
+            kind: :containment_blocked, applied: applied_paths, failed: rel_path,
+            pending: pending_after(keys_to_apply, index), conflicts: conflicts
+          )
+        end
+
+        content = @buffer[rel_path]
+
+        begin
+          Rubik::Platform.atomic_write(full_path, content)
+        rescue StandardError => e
+          @last_conflicts = conflicts
+          raise apply_failure(
+            "Apply failed for '#{rel_path}': #{e.class}: #{e.message}; " \
+            "#{applied_paths.empty? ? 'no file was written' : "already written: #{applied_paths.join(', ')}"}; " \
+            "#{pending_after(keys_to_apply, index).size} file(s) still dirty",
+            kind: :write_failed, applied: applied_paths, failed: rel_path,
+            pending: pending_after(keys_to_apply, index), conflicts: conflicts
+          ), cause: e
+        end
+
+        @original_hashes[rel_path] = Digest::SHA256.hexdigest(content)
+        @dirty_files.delete(rel_path)
+        @buffer.delete(rel_path)
+        applied_paths << rel_path
+      end
+
       # Single source of boundary containment for both the sanitize_path
       # entry check and the apply! re-verification. Returns [kind, dir] with
       # kind :root / :external (dir is the LEXICAL matched root/external

data/lib/rubik/config/defaults.rb

@@ -171,6 +171,7 @@ module Rubik
             "distiller" => true,
             "max_steps" => 8,
             "flush_events" => 10,
+            "max_digest_jobs" => 100,
             "model" => nil,
             "retention" => "supersede",
             "root_turns" => true

data/lib/rubik/context/git_lister.rb

@@ -1,6 +1,7 @@
 # frozen_string_literal: true
 
 require "open3"
+require_relative "../log"
 
 module Rubik
   module Context
@@ -27,7 +28,8 @@ module Rubik
         res.map! { |p| p.tr("\\", "/") } if out.include?("\\")
         res.uniq!
         res
-      rescue StandardError
+      rescue StandardError => e
+        Rubik::Log.debug(:context, "git ls-files execution failed for #{root_dir}: #{e.class}: #{e.message}")
         nil
       end
 

data/lib/rubik/llm/anthropic.rb

@@ -56,8 +56,11 @@ module Rubik
         return opts[:api_key] if opts.key?(:api_key) && !opts[:api_key].nil?
         return @api_key if @api_key && !@api_key.to_s.empty?
 
-        env_name = opts[:api_key_env] || @api_key_env || "ANTHROPIC_API_KEY"
-        ENV.fetch(env_name, nil)
+        env_name = opts[:api_key_env]
+        env_name = @api_key_env if env_name.nil? || env_name.to_s.empty?
+        env_name = "ANTHROPIC_API_KEY" if env_name.nil? || env_name.to_s.empty?
+
+        ENV.fetch(env_name.to_s, nil)
       end
 
       def complete(messages, opts = {})

data/lib/rubik/llm/openai_compatible.rb

@@ -50,20 +50,11 @@ module Rubik
       end
 
       def complete(messages, opts = {})
-        resolved_key = opts[:api_key] || @api_key || (ENV.fetch(@api_key_env, nil) if @api_key_env)
         target_model = opts[:model] || @model
         target_endpoint = self.class.normalize_endpoint(opts[:endpoint] || @endpoint)
         messages = Rubik::LLM::MessageSanitizer.normalize(messages)
 
-        req_headers = { "Content-Type" => "application/json" }
-        req_headers["Authorization"] = "Bearer #{resolved_key}" if resolved_key && !resolved_key.empty?
-
-        # Merge custom headers (e.g. OpenRouter HTTP-Referer, X-Title)
-        @headers.each do |k, v|
-          req_headers[k.to_s] = v.to_s
-        end
-        req_headers.merge!(opts[:headers]) if opts[:headers].is_a?(Hash)
-
+        req_headers = build_headers(opts)
         formatted_msgs = format_messages(messages)
         payload = build_payload(target_model, formatted_msgs, opts, stream: false)
 
@@ -79,73 +70,17 @@ module Rubik
           on_retry: opts[:on_retry]
         )
 
-        root_json = res_json["data"].is_a?(Hash) && res_json["data"]["choices"] ? res_json["data"] : res_json
-        msg = root_json.dig("choices", 0, "message") || {}
-        text = msg["content"] || ""
-        thought = msg["reasoning_content"] || msg["reasoning"] || msg["thought"]
-        thought = nil if thought.to_s.empty?
-        usage = root_json["usage"] || res_json["usage"] || {}
-
-        raw_tool_calls = msg["tool_calls"] || []
-        parsed_tool_calls = raw_tool_calls.map do |tc|
-          fn = tc["function"] || {}
-          args = fn["arguments"]
-          malformed = nil
-          if args.is_a?(String)
-            begin
-              parsed = JSON.parse(args)
-              if parsed.is_a?(Hash)
-                args = parsed
-              else
-                malformed = args
-                args = {}
-              end
-            rescue JSON::ParserError
-              # Issue #55 3.4: the degrade carries the rejected payload so
-              # the executor can echo it back to the model in the error row.
-              malformed = args
-              args = {}
-            end
-          elsif !args.is_a?(Hash) && !args.nil?
-            malformed = args.to_s
-            args = {}
-          end
-          row = {
-            "id" => tc["id"] || "call_#{rand(1000..9999)}",
-            "tool" => fn["name"],
-            "args" => args || {}
-          }
-          row["malformed_args"] = malformed if malformed
-          row
-        end
-
-        in_tokens = usage["prompt_tokens"] || usage["input_tokens"] || estimate_tokens(messages.map { |m| m[:content] || m["content"] }.join)
-        out_tokens = usage["completion_tokens"] || usage["output_tokens"] || estimate_tokens(text)
-
-        Response.new(
-          text: text,
-          usage: {
-            input_tokens: in_tokens,
-            output_tokens: out_tokens
-          },
-          raw: res_json,
-          tool_calls: parsed_tool_calls,
-          thought: thought
-        )
+        build_response(res_json, messages)
       end
 
       # Streaming variant. Yields Chunks. Without a block, returns an
       # Enumerator (via `to_enum`) so the caller can chain `.each`.
       def stream_chat(messages, opts = {}, &block)
-        resolved_key = opts[:api_key] || @api_key || (ENV.fetch(@api_key_env, nil) if @api_key_env)
         target_model = opts[:model] || @model
         target_endpoint = self.class.normalize_endpoint(opts[:endpoint] || @endpoint)
         messages = Rubik::LLM::MessageSanitizer.normalize(messages)
 
-        req_headers = { "Content-Type" => "application/json" }
-        req_headers["Authorization"] = "Bearer #{resolved_key}" if resolved_key && !resolved_key.empty?
-        @headers.each { |k, v| req_headers[k.to_s] = v.to_s }
-        req_headers.merge!(opts[:headers]) if opts[:headers].is_a?(Hash)
+        req_headers = build_headers(opts)
 
         formatted_msgs = format_messages(messages)
         payload = build_payload(target_model, formatted_msgs, opts, stream: true)
@@ -172,6 +107,86 @@ module Rubik
 
       private
 
+      def build_headers(opts = {})
+        resolved_key = opts[:api_key] || @api_key || (ENV.fetch(@api_key_env, nil) if @api_key_env)
+        req_headers = { "Content-Type" => "application/json" }
+        req_headers["Authorization"] = "Bearer #{resolved_key}" if resolved_key && !resolved_key.empty?
+
+        # Merge custom headers (e.g. OpenRouter HTTP-Referer, X-Title)
+        @headers.each do |k, v|
+          req_headers[k.to_s] = v.to_s
+        end
+        req_headers.merge!(opts[:headers]) if opts[:headers].is_a?(Hash)
+        req_headers
+      end
+
+      def build_response(res_json, messages)
+        root_json = res_json["data"].is_a?(Hash) && res_json["data"]["choices"] ? res_json["data"] : res_json
+        msg = root_json.dig("choices", 0, "message") || {}
+        text = msg["content"] || ""
+        thought = msg["reasoning_content"] || msg["reasoning"] || msg["thought"]
+        thought = nil if thought.to_s.empty?
+        usage = root_json["usage"] || res_json["usage"] || {}
+
+        parsed_tool_calls = parse_tool_calls(msg["tool_calls"] || [])
+        in_tokens, out_tokens = calculate_usage(usage, messages, text)
+
+        Response.new(
+          text: text,
+          usage: {
+            input_tokens: in_tokens,
+            output_tokens: out_tokens
+          },
+          raw: res_json,
+          tool_calls: parsed_tool_calls,
+          thought: thought
+        )
+      end
+
+      def parse_tool_calls(raw_tool_calls)
+        raw_tool_calls.map do |tc|
+          fn = tc["function"] || {}
+          args, malformed = parse_tool_args(fn["arguments"])
+          row = {
+            "id" => tc["id"] || "call_#{rand(1000..9999)}",
+            "tool" => fn["name"],
+            "args" => args || {}
+          }
+          row["malformed_args"] = malformed if malformed
+          row
+        end
+      end
+
+      def parse_tool_args(args)
+        malformed = nil
+        if args.is_a?(String)
+          begin
+            parsed = JSON.parse(args)
+            if parsed.is_a?(Hash)
+              args = parsed
+            else
+              malformed = args
+              args = {}
+            end
+          rescue JSON::ParserError
+            # Issue #55 3.4: the degrade carries the rejected payload so
+            # the executor can echo it back to the model in the error row.
+            malformed = args
+            args = {}
+          end
+        elsif !args.is_a?(Hash) && !args.nil?
+          malformed = args.to_s
+          args = {}
+        end
+        [args, malformed]
+      end
+
+      def calculate_usage(usage, messages, text)
+        in_tokens = usage["prompt_tokens"] || usage["input_tokens"] || estimate_tokens(messages.map { |m| m[:content] || m["content"] }.join)
+        out_tokens = usage["completion_tokens"] || usage["output_tokens"] || estimate_tokens(text)
+        [in_tokens, out_tokens]
+      end
+
       def reasoning_model?(model_name, opts)
         return true if opts.key?(:reasoning_effort)
         return true if model_name.to_s.match?(/\A(o[134](-[a-z0-9]+)?|o1|o3|o4)\b/i)