fast-completions 0.2.0 → 0.3.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: b689b98f53f49ee1e7dcf541b2339f24683d34c6b8331994764ddffc0bdb86df
-  data.tar.gz: 815c13df95de3782a8dfd8303d3ad50173fd9c0d5c8795fa8cdd7fc9173df8c6
+  metadata.gz: e2cecdfed6a68aef560e112239c184f36f20d906b7122ae1311cbeb92b726b4d
+  data.tar.gz: cb1ecd28ceecb63144bc7ad9b9328ffd9624033c26d793c691496d67ea909551
 SHA512:
-  metadata.gz: 5025050d712a676ac2bb5972506260cc63fa4aaff9ca47d20409e18a9ea756b0096deeea9a5168729d5f3757bf03820a88c680107e718d097946b52b0c3ae9dc
-  data.tar.gz: 4715c20690b34fc1d569a9b41ff9f291f3c110d32ed66daa9945989f54b18f53de09b265f6d7c1c11815b0f95201327a3627339968ebe2b0b0f37fbc89468317
+  metadata.gz: 12dcd5ced8e6c2ecee077178c138425ccae68061e6e0b42c6ec6540f952a3a93d3862ca319f761cfdebef89c04fc21024c09883f072a9949a0dc1a4ccace96d0
+  data.tar.gz: 934df8a658af5d27c9da6aca37ab8e0d999f5ff633149227c646888af30c8b63e6629452b227aab5d34e74aa5fd128bd283bab405bba0993d3e0fed0f06cc881

data/CHANGELOG.md

@@ -3,6 +3,60 @@
 Notable changes to the fast-completions gem. The format is prose-first,
 one section per released version, newest first.
 
+## 0.3.0 (2026-10-15)
+
+- Mid-stream salvage: a failure after a 2xx status — a mid-body connection
+  abort, the network-error family, or any other exception except
+  cancellation — no longer discards the streamed work. The client yields the
+  `:error` terminal event FIRST, carrying the live partial (every streamed
+  block and the usage so far; a thinking block's streamed
+  `reasoning_details` are serialized into its signature exactly as finalize
+  would) with no block-end events after the failure, then raises
+  (`ConnectionError` for the network family, message form preserved;
+  anything else re-raised unchanged). Creation-phase failures (non-2xx
+  after the retry decision, network failures with retries exhausted) yield
+  the same `:error` event — the accumulator still empty, `:start` still not
+  emitted — before their mapped raise.
+- Request-creation retry: the POST — creation through status receipt,
+  structurally pre-first-body-byte — now retries bounded at ONE retry by
+  default (constructor `max_retries:`, integer ≥ 0; `0` restores the single
+  attempt), exactly on pi's provider-retry trigger classes: header
+  `x-should-retry: true` (any status) retries; `x-should-retry: false` is
+  final even on 429/5xx; statusless errors (network failures during the
+  POST, a TTFB watchdog fire) retry; 408/409/429/5xx retry; every other
+  status is final. Never after a 2xx — a mid-body failure salvages instead,
+  making exactly one request. Cancellation is never retried; retries are
+  immediate (backoff out of scope); a retried TTFB deadline re-arms per
+  attempt and the final failure still surfaces `TimeoutError`, never
+  `CancelledError`.
+- Outgoing-string scrub (I62): every string the codec emits onto the wire
+  params passes through a `String#scrub { "" }` deletion scrub (pi
+  `sanitizeSurrogates`) at each emission point — the leading instructions
+  and system content, user strings and text parts, the assistant's joined
+  text and reasoning-field text, tool-result content, and the string
+  values inside tool-call `arguments` (deep). Malformed bytes (lone
+  surrogates, CESU-8 pairs, any invalid UTF-8 — Ruby's class is broader
+  than JS's) are DELETED, never replaced with U+FFFD, so
+  `JSON.generate` over a built request no longer raises
+  `GeneratorError` from message content. Valid strings pass
+  byte-identical — the canonical wire fixtures are untouched.
+- `Message#stop_reason` (I62): nil-default replay metadata with no
+  vocabulary validation; `to_h` emits the key only when set, `from_h`
+  round-trips it, and the assistant factory accepts it.
+  `Codec.normalize` skips assistants whose `stop_reason` is `:error` or
+  `:aborted` entirely on replay (pi transform-messages): their tool calls
+  never become pending orphans and never synthesize results, while a
+  previous valid assistant's unanswered calls still do and surrounding
+  user/system messages are unaffected. Histories without errored rows
+  are byte-unaffected.
+- Tool-call index-map backfill (I62): a tool-call fragment that resolves
+  its block by id (or creation) while carrying an `index` now binds the
+  block into the accumulator's index map (pi openai-completions :536-539)
+  — first index wins, one index per block, ever — so the
+  `{id, name}` → `{id, index, args}` → `{index, args}` fragment shape
+  assembles ONE tool call instead of a spurious second block. Boundness
+  is tracked accumulator-side; no scratch keys leak onto message blocks.
+
 ## 0.2.0 (2026-10-15)
 
 - Tolerant inbound stream (I61): a malformed SSE chunk no longer kills

data/lib/fast/completions/client.rb

@@ -11,6 +11,10 @@ module Fast
     # its own (§6).
     class Client
       DEFAULT_TIMEOUT = 30
+      # Bounded creation retry (I62, Grounds R2): ONE retry (two attempts)
+      # by default so a transient 429/5xx/connection refusal no longer
+      # kills the turn; `max_retries: 0` restores the single attempt.
+      DEFAULT_MAX_RETRIES = 1
 
       # TTFB deadline + inactivity read-timeout watchdog (D5/OQ-1): one
       # value serves both. A fire cancels the waiting task; `fired` tells
@@ -26,9 +30,13 @@ module Fast
         attr_reader :fired
 
         # (Re)arm: TTFB deadline before the POST, re-armed as the
-        # inactivity read-timeout after every body chunk.
+        # inactivity read-timeout after every body chunk. The fired flag
+        # resets with the timer: a retried attempt (I62) must not inherit
+        # the previous attempt's fire, or the post-stream guard and the
+        # cancel-vs-fired discipline would misread attempt 2 (D5/D8).
         def arm
           stop
+          @fired = false
           @timer = Async do
             sleep @seconds
             @fired = true
@@ -47,12 +55,15 @@ module Fast
         Errno::ENETUNREACH, Errno::ETIMEDOUT, EOFError, IOError, SocketError,
       ].freeze
 
-      attr_reader :timeout, :dropped_chunks
+      attr_reader :timeout, :max_retries, :dropped_chunks
+
+      def initialize(base_url:, api_key:, timeout: DEFAULT_TIMEOUT, max_retries: DEFAULT_MAX_RETRIES)
+        raise ArgumentError, "max_retries must be an Integer >= 0" unless max_retries.is_a?(Integer) && max_retries >= 0
 
-      def initialize(base_url:, api_key:, timeout: DEFAULT_TIMEOUT)
         @endpoint = Async::HTTP::Endpoint.parse(base_url)
         @api_key = api_key
         @timeout = timeout
+        @max_retries = max_retries
         @client = Async::HTTP::Client.new(@endpoint)
         @path = @endpoint.path.chomp("/") + "/chat/completions"
       end
@@ -65,6 +76,17 @@ module Fast
       # POST {base}/chat/completions, stream the SSE reply, yield every
       # Event to the block, return the final assistant Message (the
       # accumulator itself — §3). Runs inside the caller's task.
+      #
+      # Failure discipline (I62): EVERY failure raises AFTER the one
+      # `:error` terminal event — a streaming-phase failure carries the
+      # salvaged partial (pi :707-728 catch-all), a creation-phase
+      # failure an empty accumulator (:start is never emitted for a
+      # failed creation) — except cancellation, which keeps its
+      # no-terminal-event discipline (D8), and the watchdog's read
+      # inactivity, reached as Async::Cancel through the same untouched
+      # ladder. The rescue order is load-bearing: Async::Cancel first
+      # (cancel never salvages, never retries), then the network family,
+      # then the StandardError catch-all.
       def stream(model:, messages:, instructions: nil, tools: [], thinking: nil,
         max_tokens: nil, temperature: nil, session_id: nil, &block)
         request = Protocol.build_request(
@@ -73,31 +95,35 @@ module Fast
           temperature: temperature,
         )
         headers = default_headers.merge(session_headers(model.dialect, session_id))
+        body = JSON.generate(request)
         accumulator = Protocol::StreamAccumulator.new(model, model.dialect)
 
         watchdog = Watchdog.new(Async::Task.current, @timeout)
+        response = nil
         begin
-          watchdog.arm
-          response = @client.post(@path, headers: headers, body: JSON.generate(request))
-          begin
-            raise_api_error(response) unless (200...300).cover?(response.status)
-            yield accumulator.start_event if block # :start precedes every block event (§10.6)
-            feed_stream(response, accumulator, watchdog, &block)
-          ensure
-            # Complete bodies return the connection to the pool; an aborted
-            # read (cancel/timeout) discards it — a cancelled connection is
-            # never reused (AC3/D8).
-            begin
-              response.finish
-            rescue StandardError, Async::Cancel
-              nil
-            end
-          end
+          # The POST attempt — creation through status receipt (§2),
+          # bounded-retried on pi's trigger set; every final creation
+          # failure raises its mapped error from in there.
+          response = create_response(headers, body, watchdog)
+          yield accumulator.start_event if block # :start precedes every block event (§10.6)
+          feed_stream(response, accumulator, watchdog, &block)
         rescue Async::Cancel
           watchdog.fired ? raise(TimeoutError, "no data within #{@timeout}s") : raise(CancelledError, "stream cancelled")
         rescue *NETWORK_ERRORS => e
+          salvage(accumulator, &block) # the :error terminal carries the partial BEFORE the raise (§1)
           raise ConnectionError, "#{e.class}: #{e.message}"
+        rescue StandardError
+          salvage(accumulator, &block) # pi's catch-all: any other streaming failure — same terminal, raised unchanged
+          raise
         ensure
+          # Complete bodies return the connection to the pool; an aborted
+          # read (cancel/timeout) discards it — a cancelled connection is
+          # never reused (AC3/D8).
+          begin
+            response.finish
+          rescue StandardError, Async::Cancel
+            nil
+          end
           watchdog.stop
         end
         raise TimeoutError, "no data within #{@timeout}s" if watchdog.fired
@@ -183,7 +209,96 @@ module Fast
         accumulator.partial
       end
 
-      # Non-2xx: read the body, map per §8.
+      # The bounded creation retry (I62 §2, pi retryProviderRequest around
+      # chat.completions.create — the attempt is creation through status
+      # receipt, structurally pre-first-body-byte, Grounds R4). At most
+      # @max_retries immediate retries, exactly on pi's trigger set
+      # (provider-retry.ts :25-38): header x-should-retry true (any
+      # status) / false (FINAL, even on a retryable status), statusless
+      # errors (NETWORK_ERRORS at the POST, a TTFB watchdog fire),
+      # statuses 408/409/429/5xx. NEVER after a 2xx — the attempt is
+      # committed to streaming and any later failure is §1 salvage, never
+      # a retry. Cancellation is not a failure and is never retried. Each
+      # final failure raises its mapped error; stream's ladder adds the
+      # :error terminal before it (the accumulator is still empty — no
+      # :start was emitted).
+      def create_response(headers, body, watchdog)
+        remaining = @max_retries
+        loop do
+          watchdog.arm # re-armed per attempt: a retried TTFB deadline restarts (D5)
+          begin
+            response = @client.post(@path, headers: headers, body: body)
+          rescue Async::Cancel
+            raise unless watchdog.fired # the user's cancel is not a failure — never retried (D8)
+            raise TimeoutError, "no data within #{@timeout}s" if remaining.zero?
+            remaining -= 1
+            next
+          rescue *NETWORK_ERRORS => e
+            # Statusless — no response was received (pi's statusless trigger).
+            raise ConnectionError, "#{e.class}: #{e.message}" if remaining.zero?
+            remaining -= 1
+            next
+          end
+          return response if (200...300).cover?(response.status)
+
+          if retry_response?(response) && remaining.positive?
+            finish_quietly(response) # the discarded attempt's connection returns to the pool
+            remaining -= 1
+            next
+          end
+          raise_api_error(response) # final non-2xx: the §8 mapping, reached only after the retry decision
+        end
+      end
+
+      # pi provider-retry.ts :26-34, exact: the header beats the status
+      # both ways (strict "true"/"false"); then 408/409/429/5xx; every
+      # other status is final.
+      def retry_response?(response)
+        flag = retry_header(response.headers)
+        return true if flag == "true"
+        return false if flag == "false"
+
+        [408, 409, 429].include?(response.status) || (500..599).cover?(response.status)
+      end
+
+      # Header NAMES arrive in wire case (HTTP/1); Protocol::HTTP::Headers
+      # collects repeated fields into arrays — scan case-insensitively and
+      # unwrap, pi headers.get("x-should-retry") shape.
+      def retry_header(headers)
+        headers.each do |key, value|
+          return Array(value).first if key.to_s.downcase == "x-should-retry"
+        end
+        nil
+      end
+
+      # The salvage arm (pi openai-completions.ts :707-728 catch-all): a
+      # streaming-phase failure yields the ONE error-terminal event FIRST
+      # — the live partial (every streamed block + usage so far) — with NO
+      # block-end events after the failure; the rescue ladder raises
+      # after. pi's catch applies the same scratch finalization to the
+      # partial (applyStreamedReasoningDetails): `finish` runs
+      # finalize_blocks — the thinking reasoning_details serialized into
+      # the signature, tool arguments finalized — whose end events we
+      # discard here, so a salvaged partial replays like a completed one's.
+      def salvage(accumulator)
+        return unless block_given?
+
+        accumulator.finish
+        yield Event.new(type: :error, reason: :error, message: accumulator.partial)
+      end
+
+      # Complete bodies return the connection to the pool; an aborted read
+      # (cancel/timeout) discards it — a cancelled connection is never
+      # reused (AC3/D8). Same discipline as stream's ensure.
+      def finish_quietly(response)
+        response.finish
+      rescue StandardError, Async::Cancel
+        nil
+      end
+
+      # Non-2xx: read the body, map per §8. Now reached only after the
+      # retry decision (I62) — stream's ladder yields the :error terminal
+      # before this raise.
       def raise_api_error(response)
         body = response.body.read
         raise Errors.class_for_status(response.status, body).new(status: response.status, body: body)

data/lib/fast/completions/codec.rb

@@ -20,7 +20,9 @@ module Fast
       # ── Pass 1: transform-messages.ts ──────────────────────────────
 
       def normalize(messages, model)
-        transformed = messages.map { |msg| transform_message(msg, model) }
+        # filter_map: the transform pass drops errored/aborted assistants
+        # ENTIRELY (I62, pi :196-206) so pass 2 never sees their tool calls.
+        transformed = messages.filter_map { |msg| transform_message(msg, model) }
         insert_orphan_synthetic_results(transformed)
       end
 
@@ -30,6 +32,12 @@ module Fast
       # (Specification §12.3 note; pi :97-99).
       def transform_message(msg, model)
         return msg unless msg.assistant?
+        # Errored/aborted turns skip replay entirely (pi :196-206): dropped
+        # in THIS pass, so their tool calls never become pending orphans in
+        # pass 2 and never synthesize results — while a PREVIOUS valid
+        # assistant's unanswered calls still flush there, and user/system
+        # messages around the skip are untouched.
+        return nil if msg.stop_reason == :error || msg.stop_reason == :aborted
 
         same_model = msg.provider == model.provider && msg.model == model.id
         content = msg.content.flat_map do |block|
@@ -48,7 +56,7 @@ module Fast
           end
         end
         Message.new(role: :assistant, content: content, provider: msg.provider,
-          model: msg.model, api: msg.api, usage: msg.usage)
+          model: msg.model, api: msg.api, usage: msg.usage, stop_reason: msg.stop_reason)
       end
 
       # Thinking-block rules (transform-messages.ts :103-118):
@@ -61,7 +69,9 @@ module Fast
           return same_model ? [block] : []
         end
         return [block] if same_model && block[:signature]
-        return [] if block[:thinking].nil? || block[:thinking].strip.empty?
+        # scrub: the empty-predicate must not die on defect-class bytes
+        # (I62) — the reasoning-field text is a scrubbed emission position.
+        return [] if block[:thinking].to_s.scrub { "" }.strip.empty?
         return [block] if same_model
 
         [{type: :text, text: block[:thinking]}]
@@ -122,20 +132,44 @@ module Fast
 
       # ── Pass 2: convertMessages (openai-completions.ts :1293-1465) ──
 
+      # pi sanitizeSurrogates (utils/sanitize-unicode.ts :24-27, call sites
+      # :1259/:1265/:1274/:1305/:1326/:1426): invalid sequences DELETED —
+      # "Text \u{D83D} here" → "Text  here", never U+FFFD. String#scrub
+      # { "" } deletes Ruby's whole invalid-encoding class (lone high/low
+      # surrogates, CESU-8 pairs, any malformed bytes — Ruby's class is
+      # broader than JS's) and is a byte-identical no-op on valid strings,
+      # so JSON.generate over the built params never raises
+      # GeneratorError from message content (Grounds row 3).
+      def scrub_text(str)
+        str.is_a?(String) ? str.scrub { "" } : str
+      end
+
+      # Tool-call arguments are message content too (the live-parsed
+      # JSON): string VALUES scrubbed, Hash/Array recursed, other leaves
+      # (numbers, booleans, nil) pass.
+      def scrub_json_values(node)
+        case node
+        when String then scrub_text(node)
+        when Hash then node.each_with_object({}) { |(key, value), out| out[key] = scrub_json_values(value) }
+        when Array then node.map { |item| scrub_json_values(item) }
+        else node
+        end
+      end
+
       # instructions is the ONE leading system/developer message (§9.1,
       # pi :1233): role "developer" iff model.reasoning AND
       # dialect.supports_developer_role, else "system".
       def to_wire_messages(instructions, messages, model, dialect)
         instruction_role = model.reasoning && dialect.supports_developer_role ? "developer" : "system"
         params = []
-        params << {role: instruction_role, content: instructions} if instructions && !instructions.empty?
+        params << {role: instruction_role, content: scrub_text(instructions)} if instructions && !instructions.empty?
 
         messages.each do |msg|
           case msg.role
           when :system
             next if msg.content.to_s.empty?
 
-            params << {role: instruction_role, content: msg.content}
+            params << {role: instruction_role, content: scrub_text(msg.content)}
           when :user
             wire_user(params, msg)
           when :assistant
@@ -152,13 +186,13 @@ module Fast
       # all-empty blocks skip the message (pi :1319-1342).
       def wire_user(params, msg)
         if msg.content.is_a?(String)
-          params << {role: "user", content: msg.content}
+          params << {role: "user", content: scrub_text(msg.content)}
           return
         end
 
         parts = msg.content
           .select { |block| block[:type] == :text && !block[:text].to_s.empty? }
-          .map { |block| {type: "text", text: block[:text]} }
+          .map { |block| {type: "text", text: scrub_text(block[:text])} }
         return if parts.empty?
 
         params << {role: "user", content: parts}
@@ -168,7 +202,7 @@ module Fast
       # tool_call_id:}; empty → "(no tool output)"; NO name key
       # (requires_tool_result_name unported, §14).
       def wire_tool_result(params, msg)
-        text = text_block_texts(msg.content).join("\n")
+        text = scrub_text(text_block_texts(msg.content).join("\n"))
         text = "(no tool output)" if text.empty?
         params << {role: "tool", content: text, tool_call_id: msg.tool_call_id}
       end
@@ -182,7 +216,7 @@ module Fast
         thinking_blocks = msg.content.select { |b| b[:type] == :thinking }
         tool_calls = msg.content.select { |b| b[:type] == :tool_call }
 
-        non_empty_thinking = thinking_blocks.reject { |b| b[:thinking].to_s.strip.empty? }
+        non_empty_thinking = thinking_blocks.reject { |b| b[:thinking].to_s.scrub { "" }.strip.empty? } # scrub: I62 defect-class safety
         # pi computes preservedReasoningDetails over ALL thinking blocks
         # (:1313-1316) and emits it independent of the non-empty branch
         # (:1382-1386) — encrypted-only blocks replay too.
@@ -190,15 +224,15 @@ module Fast
         unless non_empty_thinking.empty?
           if preserved_details.nil?
             field = non_empty_thinking.first[:signature]
-            assistant[field] = non_empty_thinking.map { |b| b[:thinking] }.join("\n") if REASONING_FIELDS.include?(field)
+            assistant[field] = scrub_text(non_empty_thinking.map { |b| b[:thinking] }.join("\n")) if REASONING_FIELDS.include?(field)
           end
         end
 
-        assistant[:content] = text unless text.empty?
+        assistant[:content] = scrub_text(text) unless text.empty?
         unless tool_calls.empty?
           assistant[:tool_calls] = tool_calls.map do |tc|
             {id: tc[:id], type: "function",
-             function: {name: tc[:name], arguments: JSON.generate(tc[:arguments])}}
+             function: {name: tc[:name], arguments: JSON.generate(scrub_json_values(tc[:arguments]))}}
           end
         end
         assistant["reasoning_details"] = preserved_details if preserved_details
@@ -326,8 +360,10 @@ module Fast
 
       def text_block_texts(content, non_whitespace: false)
         blocks = content.is_a?(String) ? [{type: :text, text: content}] : content
+        # scrub before the strip predicate (I62): defect-class bytes must
+        # reach the emission-point scrub, not die in the whitespace filter.
         blocks.select { |b| b.is_a?(Hash) && b[:type] == :text }
-          .map { |b| b[:text].to_s }
+          .map { |b| scrub_text(b[:text]).to_s }
           .then { |texts| non_whitespace ? texts.reject { |t| t.strip.empty? } : texts }
       end
     end

data/lib/fast/completions/errors.rb

@@ -10,6 +10,9 @@ module Fast
     # Non-2xx responses map here (pi maps the OpenAI SDK status error).
     # #message is "<status>: <provider message>" — the provider's
     # error.message when the body parses, else the raw body truncated.
+    # I62: a non-2xx raise happens only after the creation-retry decision,
+    # and the client-level `:error` event (empty partial, no `:start`)
+    # precedes every such raise (§1 creation-phase discipline).
     class ApiError < Error
       attr_reader :status, :body
 
@@ -28,14 +31,25 @@ module Fast
     class RateLimitError < ApiError; end             # 429
     class ServerError < ApiError; end                # 5xx
 
-    class TimeoutError < Error; end                  # TTFB deadline / read inactivity (D5)
-    class ConnectionError < Error; end               # ECONNREFUSED/ECONNRESET/... (§6)
+    # TTFB deadline / read inactivity (D5). I62: a TTFB fire before the
+    # response is a statusless retry trigger — a retried deadline re-arms
+    # per attempt, and the final failure still surfaces this class, never
+    # CancelledError. A mid-stream read inactivity arrives as
+    # Async::Cancel through the untouched cancel ladder (no retry, no
+    # terminal event).
+    class TimeoutError < Error; end
+    # ECONNREFUSED/ECONNRESET/... (§6). I62: a mid-body network failure
+    # salvages the partial as the `:error` terminal BEFORE this raise
+    # (message form `"<class>: <message>"` preserved); at creation the
+    # same terminal carries the empty accumulator after retries exhaust.
+    class ConnectionError < Error; end
 
     # Terminal stream errors (pi throws inside stream; the gem emits the
     # :error event first, then raises this — §10.5). NOT the malformed-
     # chunk path since I61: a malformed chunk is repaired at the seam,
     # else dropped and counted while the stream continues. What remains
-    # here: a provider error finish_reason or a missing finish.
+    # here: a provider error finish_reason or a missing finish. I62 did
+    # not change this path — it IS the model for the new salvage arm.
     class StreamError < Error
       attr_reader :stop_reason
 

data/lib/fast/completions/protocol.rb

@@ -403,7 +403,6 @@ module Fast
           block ||= @tool_by_id[entry["id"]] if entry["id"]
           unless block
             block = {type: :tool_call, id: entry["id"] || "", name: name, arguments: {}}
-            @tool_by_index[index] = block if index
             @tool_by_id[block[:id]] = block unless block[:id].empty?
             @partial.append_block(block)
             events << Event.new(type: :tool_call_start, content_index: content_index(block), partial: @partial)
@@ -413,6 +412,17 @@ module Fast
             @tool_by_id[block[:id]] = block
           end
           block[:name] = name if block[:name].empty? && !name.empty?
+          # Index-map backfill (I62, pi :536-539): a fragment that resolved
+          # its block — by index, by id, or by creation — while CARRYING an
+          # index the block has never bound, binds it here. FIRST index
+          # wins; one index per block, ever. Boundness is tracked
+          # accumulator-side (identity-keyed, like @args_scratch): the
+          # blocks ARE message content — no scratch keys on them.
+          @tool_index_bound ||= {}.compare_by_identity
+          if index && !@tool_index_bound.key?(block)
+            @tool_by_index[index] = block
+            @tool_index_bound[block] = true
+          end
 
           raw = entry.dig("function", "arguments")
           raw = "" unless raw.is_a?(String)

data/lib/fast/completions/types.rb

@@ -138,10 +138,12 @@ module Fast
       ROLES = %i[system user assistant tool_result].freeze
 
       attr_reader :role, :content, :provider, :model, :api, :usage,
-        :tool_call_id, :tool_name, :is_error, :response_id, :response_model
+        :tool_call_id, :tool_name, :is_error, :response_id, :response_model,
+        :stop_reason
 
       def initialize(role:, content:, provider: nil, model: nil, api: nil,
-        tool_call_id: nil, tool_name: nil, is_error: false, usage: nil)
+        tool_call_id: nil, tool_name: nil, is_error: false, usage: nil,
+        stop_reason: nil)
         unless ROLES.include?(role)
           raise ArgumentError, "role must be one of #{ROLES.inspect}, got #{role.inspect}"
         end
@@ -155,6 +157,10 @@ module Fast
         @tool_name = tool_name
         @is_error = is_error == true
         @usage = usage
+        # Stream/replay metadata (I62, pi transform-messages :196-206): nil
+        # default, NO vocabulary validation — consumers may carry their own
+        # values (tart's follow-up threads the stream's mapped reasons).
+        @stop_reason = stop_reason
         @response_id = nil
         @response_model = nil
       end
@@ -190,12 +196,13 @@ module Fast
         new(role: :system, content: content).freeze
       end
 
-      def self.assistant(content, provider: nil, model: nil, api: nil)
+      def self.assistant(content, provider: nil, model: nil, api: nil, stop_reason: nil)
         unless content.is_a?(Array)
           raise ArgumentError, "assistant content must be an Array of block hashes"
         end
 
-        new(role: :assistant, content: content, provider: provider, model: model, api: api).freeze
+        new(role: :assistant, content: content, provider: provider, model: model, api: api,
+          stop_reason: stop_reason).freeze
       end
 
       def self.tool_result(tool_call_id:, content:, tool_name: nil, is_error: false)
@@ -219,6 +226,7 @@ module Fast
         out[:usage] = @usage.to_h if @usage
         out[:response_id] = @response_id if @response_id
         out[:response_model] = @response_model if @response_model
+        out[:stop_reason] = @stop_reason if @stop_reason
         out
       end
 
@@ -234,6 +242,7 @@ module Fast
           tool_name: hash[:tool_name],
           is_error: hash[:is_error] == true,
           usage: hash[:usage] && Usage.new(**hash[:usage].transform_keys(&:to_sym)),
+          stop_reason: hash[:stop_reason]&.to_sym,
         )
         message.set_response_id(hash[:response_id]) if hash[:response_id]
         message.set_response_model(hash[:response_model]) if hash[:response_model]

data/lib/fast/completions/version.rb

@@ -2,6 +2,6 @@
 
 module Fast
   module Completions
-    VERSION = "0.2.0"
+    VERSION = "0.3.0"
   end
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: fast-completions
 version: !ruby/object:Gem::Version
-  version: 0.2.0
+  version: 0.3.0
 platform: ruby
 authors:
 - Eric Jacobs