kward 0.67.1 → 0.69.0

data/lib/kward/model/stream_parser.rb

@@ -1,6 +1,15 @@
 require "json"
 
+# Namespace for the Kward CLI agent runtime.
 module Kward
+  # Parses streaming provider responses into Kward assistant messages.
+  #
+  # `ModelStreamParser` is intentionally provider-shape focused and side-effect
+  # light: it accumulates assistant text, reasoning summaries, tool calls, and
+  # normalized usage from SSE events. Network IO, retries, credentials, and
+  # telemetry stay in `Client`; frontend rendering stays in CLI/RPC event
+  # handlers. Keep parser methods deterministic and easy to unit test with raw
+  # response bodies.
   module ModelStreamParser
     module_function
 
@@ -46,6 +55,11 @@ module Kward
       raise "Codex OAuth returned invalid SSE JSON: #{e.message}"
     end
 
+    # Incrementally parses a Codex/Responses SSE HTTP response body.
+    #
+    # Deltas are yielded as soon as complete SSE blocks arrive so interactive
+    # frontends can render streamed assistant and reasoning text without waiting
+    # for the provider to close the response.
     def parse_codex_sse_stream(response, on_reasoning_delta: nil, on_assistant_delta: nil, cancellation: nil, usage_normalizer: nil, request_error_class: nil)
       state = codex_sse_state
       buffer = +""
@@ -67,6 +81,122 @@ module Kward
       raise "Codex OAuth returned invalid SSE JSON: #{e.message}"
     end
 
+    def parse_anthropic_sse_stream(response, on_reasoning_delta: nil, on_assistant_delta: nil, cancellation: nil, usage_normalizer: nil, request_error_class: nil)
+      state = anthropic_sse_state
+      buffer = +""
+      response.read_body do |chunk|
+        cancellation&.raise_if_cancelled!
+        buffer << chunk
+        while (index = buffer.index(/\r?\n\r?\n/))
+          delimiter = Regexp.last_match[0]
+          block = buffer[0...index]
+          buffer = buffer[(index + delimiter.length)..] || +""
+          process_anthropic_sse_block(block, state, on_reasoning_delta: on_reasoning_delta, on_assistant_delta: on_assistant_delta, usage_normalizer: usage_normalizer, request_error_class: request_error_class)
+        end
+      end
+      cancellation&.raise_if_cancelled!
+      process_anthropic_sse_block(buffer, state, on_reasoning_delta: on_reasoning_delta, on_assistant_delta: on_assistant_delta, usage_normalizer: usage_normalizer, request_error_class: request_error_class) unless buffer.empty?
+      anthropic_sse_message(state)
+    rescue JSON::ParserError => e
+      raise "Anthropic returned invalid SSE JSON: #{e.message}"
+    end
+
+    def anthropic_sse_state
+      { content: +"", reasoning_summary: +"", blocks: {}, tool_calls: [], usage: nil }
+    end
+
+    def process_anthropic_sse_block(block, state, on_reasoning_delta: nil, on_assistant_delta: nil, usage_normalizer: nil, request_error_class: nil)
+      event_name = nil
+      data = block.lines.filter_map do |line|
+        event_name = line.delete_prefix("event:").strip if line.start_with?("event:")
+        line.start_with?("data:") ? line.delete_prefix("data:").strip : nil
+      end.join("\n")
+      return if data.empty? || data == "[DONE]"
+      raise anthropic_sse_error(data, request_error_class: request_error_class) if event_name == "error"
+
+      event = JSON.parse(data)
+      case event["type"]
+      when "message_start"
+        state[:usage] ||= usage_normalizer&.call(event.dig("message", "usage"))
+      when "content_block_start"
+        block_data = event["content_block"] || {}
+        state[:blocks][event["index"].to_i] = block_data.merge("partial_json" => "")
+        if block_data["type"] == "text"
+          text = block_data["text"].to_s
+          state[:content] << text
+          on_assistant_delta&.call(text) unless text.empty?
+        elsif block_data["type"] == "thinking"
+          text = block_data["thinking"].to_s
+          state[:reasoning_summary] << text
+          on_reasoning_delta&.call(text) unless text.empty?
+        end
+      when "content_block_delta"
+        current = state[:blocks][event["index"].to_i] ||= { "partial_json" => "" }
+        delta = event["delta"] || {}
+        case delta["type"]
+        when "text_delta"
+          text = delta["text"].to_s
+          state[:content] << text
+          on_assistant_delta&.call(text)
+        when "thinking_delta"
+          text = delta["thinking"].to_s
+          state[:reasoning_summary] << text
+          on_reasoning_delta&.call(text)
+        when "input_json_delta"
+          current["partial_json"] = current["partial_json"].to_s + delta["partial_json"].to_s
+        end
+      when "content_block_stop"
+        block_data = state[:blocks][event["index"].to_i]
+        tool_call = anthropic_tool_call(block_data)
+        state[:tool_calls] << tool_call if tool_call
+      when "message_delta"
+        state[:usage] = usage_normalizer&.call(event["usage"]) || state[:usage]
+      end
+    end
+
+    def anthropic_sse_error(data, request_error_class: nil)
+      if request_error_class
+        request_error_class.new(provider: "Anthropic", code: 400, body: data)
+      else
+        data
+      end
+    end
+
+    def anthropic_tool_call(block_data)
+      return nil unless block_data.is_a?(Hash) && block_data["type"] == "tool_use"
+
+      name = from_claude_code_tool_name(block_data["name"])
+      arguments = block_data["partial_json"].to_s
+      arguments = JSON.dump(block_data["input"] || {}) if arguments.empty?
+      arguments = "{}" if arguments.empty?
+      {
+        "id" => block_data["id"] || "call_#{name}",
+        "type" => "function",
+        "function" => { "name" => name, "arguments" => arguments }
+      }
+    end
+
+    def anthropic_sse_message(state)
+      message = { "role" => "assistant", "content" => state[:content] }
+      message["reasoning_summary"] = state[:reasoning_summary] unless state[:reasoning_summary].empty?
+      message["tool_calls"] = state[:tool_calls] unless state[:tool_calls].empty?
+      message["usage"] = state[:usage] if state[:usage]
+      message
+    end
+
+    def from_claude_code_tool_name(name)
+      case name.to_s
+      when "Read" then "read_file"
+      when "Write" then "write_file"
+      when "Edit" then "edit_file"
+      when "Bash" then "run_shell_command"
+      when "WebSearch" then "web_search"
+      when "WebFetch" then "fetch_content"
+      when "AskUserQuestion" then "ask_user_question"
+      else name.to_s
+      end
+    end
+
     def merge_streaming_tool_call(tool_calls, delta)
       index = (delta["index"] || tool_calls.length).to_i
       tool_calls[index] ||= { "id" => nil, "type" => "function", "function" => { "name" => "", "arguments" => "" } }
@@ -89,7 +219,18 @@ module Kward
     end
 
     def codex_sse_state
-      { content: +"", reasoning_summary: +"", tool_calls: [], final_output: [], usage: nil }
+      {
+        content: +"",
+        raw_content: +"",
+        emitted_message_keys: [],
+        reasoning_summary: +"",
+        tool_calls: [],
+        response_item_keys: [],
+        items_by_id: {},
+        active_item_id: nil,
+        current_text_content_part: nil,
+        usage: nil
+      }
     end
 
     def process_codex_sse_block(block, state, on_reasoning_delta: nil, on_assistant_delta: nil, usage_normalizer: nil, request_error_class: nil)
@@ -98,30 +239,33 @@ module Kward
 
       event = JSON.parse(data)
       case event["type"]
-      when "response.output_text.delta"
-        delta = event["delta"].to_s
-        state[:content] << delta
-        on_assistant_delta&.call(delta)
+      when "response.output_item.added"
+        codex_output_item_added(state, event["item"])
+      when "response.content_part.added"
+        codex_content_part_added(state, event["part"])
+      when "response.output_text.delta", "response.refusal.delta"
+        codex_output_text_delta(state, event["delta"], on_assistant_delta: on_assistant_delta)
+      when "response.reasoning_summary_part.added"
+        codex_reasoning_summary_part_added(state, event["part"])
       when "response.reasoning_summary_text.delta"
-        delta = event["delta"].to_s
-        state[:reasoning_summary] << delta
-        on_reasoning_delta&.call(delta)
+        codex_reasoning_delta(state, event["delta"], on_reasoning_delta: on_reasoning_delta)
+      when "response.reasoning_summary_part.done"
+        codex_reasoning_part_done(state, on_reasoning_delta: on_reasoning_delta)
+      when "response.reasoning_text.delta"
+        codex_reasoning_delta(state, event["delta"], on_reasoning_delta: on_reasoning_delta)
+      when "response.function_call_arguments.delta", "response.custom_tool_call_input.delta"
+        codex_tool_arguments_delta(state, event["delta"])
+      when "response.function_call_arguments.done"
+        codex_tool_arguments_done(state, event["arguments"])
       when "response.output_item.done"
-        item = event["item"]
-        state[:final_output] << item if item.is_a?(Hash)
-        tool_call = codex_tool_call(item)
-        state[:tool_calls] << tool_call if tool_call
+        codex_output_item_done(state, event["item"], on_assistant_delta: on_assistant_delta, on_reasoning_delta: on_reasoning_delta)
       when "response.completed"
         response = event["response"]
         state[:usage] ||= usage_normalizer&.call(response["usage"]) if response.is_a?(Hash)
         state[:usage] ||= usage_normalizer&.call(event["usage"])
-        if state[:content].empty? && response.is_a?(Hash) && response["output"].is_a?(Array)
-          state[:final_output] = response["output"]
-          text = text_from_codex_items(state[:final_output])
-          state[:content] << text
-          on_assistant_delta&.call(text) unless text.empty?
-          if state[:reasoning_summary].empty?
-            state[:reasoning_summary] << reasoning_summary_from_codex_items(state[:final_output])
+        if response.is_a?(Hash) && response["output"].is_a?(Array) && state[:response_item_keys].empty?
+          response["output"].each do |item|
+            codex_output_item_done(state, item, on_assistant_delta: on_assistant_delta, on_reasoning_delta: on_reasoning_delta)
           end
         end
       when "response.failed", "response.incomplete"
@@ -146,21 +290,239 @@ module Kward
       end
     end
 
-    def codex_sse_message(state)
-      if state[:tool_calls].empty?
-        state[:final_output].each do |item|
-          tool_call = codex_tool_call(item)
-          state[:tool_calls] << tool_call if tool_call
+    def codex_output_item_added(state, item)
+      return unless item.is_a?(Hash)
+
+      item = deep_dup_hash(item)
+      item["content"] = [] if item["type"] == "message" && !item["content"].is_a?(Array)
+      item["summary"] = [] if item["type"] == "reasoning" && !item["summary"].is_a?(Array)
+      remember_codex_item(state, item)
+      state[:active_item_id] = codex_item_key(item)
+      state[:current_text_content_part] = nil
+    end
+
+    def codex_content_part_added(state, part)
+      item = active_codex_item(state)
+      return unless item&.fetch("type", nil) == "message" && part.is_a?(Hash)
+      return unless ["output_text", "text", "refusal"].include?(part["type"])
+
+      item["content"] ||= []
+      item["content"] << deep_dup_hash(part)
+      state[:current_text_content_part] = item["content"].last
+    end
+
+    def codex_output_text_delta(state, delta, on_assistant_delta: nil)
+      text = delta.to_s
+      return if text.empty?
+
+      item = active_codex_item(state)
+      if item&.fetch("type", nil) == "message"
+        item["content"] ||= [{ "type" => "output_text", "text" => +"" }]
+        part = state[:current_text_content_part] || item["content"].last
+        part = item["content"].last unless part.is_a?(Hash)
+        part["type"] ||= "output_text"
+        text_key = part["type"] == "refusal" ? "refusal" : "text"
+        part[text_key] = part[text_key].to_s + text
+      end
+      state[:raw_content] << text
+    end
+
+    def codex_reasoning_summary_part_added(state, part)
+      item = active_codex_item(state)
+      return unless item&.fetch("type", nil) == "reasoning" && part.is_a?(Hash)
+
+      item["summary"] ||= []
+      item["summary"] << deep_dup_hash(part)
+    end
+
+    def codex_reasoning_delta(state, delta, on_reasoning_delta: nil)
+      text = delta.to_s
+      return if text.empty?
+
+      item = active_codex_item(state)
+      if item&.fetch("type", nil) == "reasoning"
+        item["summary"] ||= []
+        item["summary"] << { "type" => "summary_text", "text" => +"" } if item["summary"].empty?
+        item["summary"].last["text"] = item["summary"].last["text"].to_s + text
+      end
+      state[:reasoning_summary] << text
+      on_reasoning_delta&.call(text)
+    end
+
+    def codex_reasoning_part_done(state, on_reasoning_delta: nil)
+      item = active_codex_item(state)
+      return unless item&.fetch("type", nil) == "reasoning"
+      return if item["summary"].to_a.empty?
+
+      text = "\n\n"
+      item["summary"].last["text"] = item["summary"].last["text"].to_s + text
+      state[:reasoning_summary] << text
+      on_reasoning_delta&.call(text)
+    end
+
+    def codex_tool_arguments_delta(state, delta)
+      item = active_codex_item(state)
+      return unless item && ["function_call", "custom_tool_call"].include?(item["type"])
+
+      key = item["type"] == "custom_tool_call" ? "input" : "arguments"
+      item[key] = item[key].to_s + delta.to_s
+    end
+
+    def codex_tool_arguments_done(state, arguments)
+      item = active_codex_item(state)
+      return unless item&.fetch("type", nil) == "function_call"
+
+      item["arguments"] = arguments.to_s
+    end
+
+    def codex_output_item_done(state, item, on_assistant_delta: nil, on_reasoning_delta: nil)
+      return unless item.is_a?(Hash)
+
+      item = merge_codex_item(active_or_known_codex_item(state, item), item)
+      remember_codex_item(state, item)
+      collect_codex_item_output(state, item, on_assistant_delta: on_assistant_delta, on_reasoning_delta: on_reasoning_delta)
+      state[:active_item_id] = nil if state[:active_item_id] == codex_item_key(item)
+      state[:current_text_content_part] = nil
+    end
+
+    def collect_codex_item_output(state, item, on_assistant_delta: nil, on_reasoning_delta: nil)
+      case item["type"]
+      when "message"
+        text = text_from_codex_items([item])
+        return if text.empty? || !codex_streamable_message_item?(item)
+
+        state[:content] << text
+        key = codex_item_key(item)
+        unless state[:emitted_message_keys].include?(key)
+          on_assistant_delta&.call(text)
+          state[:emitted_message_keys] << key
         end
+      when "reasoning"
+        text = reasoning_summary_from_codex_items([item])
+        if state[:reasoning_summary].empty? && !text.empty?
+          state[:reasoning_summary] << text
+          on_reasoning_delta&.call(text)
+        end
+      when "function_call", "custom_tool_call"
+        tool_call = codex_tool_call(item)
+        state[:tool_calls] << tool_call if tool_call && !state[:tool_calls].any? { |call| call["id"] == tool_call["id"] }
       end
+    end
 
-      message = { "role" => "assistant", "content" => state[:content] }
+    def active_or_known_codex_item(state, item)
+      key = codex_item_key(item)
+      known = state[:items_by_id][key]
+      return known if known
+
+      active = active_codex_item(state)
+      return active if active && (!codex_item_has_stable_key?(item) || codex_item_key(active) == key)
+
+      nil
+    end
+
+    def codex_item_has_stable_key?(item)
+      item.key?("id") || item.key?("call_id")
+    end
+
+    def active_codex_item(state)
+      key = state[:active_item_id]
+      key ? state[:items_by_id][key] : nil
+    end
+
+    def remember_codex_item(state, item)
+      key = codex_item_key(item)
+      if state[:items_by_id].key?(key)
+        stored = state[:items_by_id][key]
+        stored.replace(merge_codex_item(stored, item))
+      else
+        state[:items_by_id][key] = item
+        state[:response_item_keys] << key
+      end
+    end
+
+    def codex_item_key(item)
+      item["id"] || item["call_id"] || "item_#{item.object_id}"
+    end
+
+    def merge_codex_item(existing, update)
+      return deep_dup_hash(update) unless existing.is_a?(Hash)
+
+      merged = deep_dup_hash(existing)
+      update.each do |key, value|
+        next if value.nil?
+
+        merged[key] = if key == "content" && merged[key].is_a?(Array) && value.is_a?(Array)
+                        value.empty? ? merged[key] : value
+                      elsif key == "summary" && merged[key].is_a?(Array) && value.is_a?(Array)
+                        value.empty? ? merged[key] : value
+                      elsif key == "arguments" && value.to_s.empty? && !merged[key].to_s.empty?
+                        merged[key]
+                      else
+                        deep_dup(value)
+                      end
+      end
+      merged
+    end
+
+    def deep_dup_hash(hash)
+      deep_dup(hash)
+    end
+
+    def deep_dup(value)
+      case value
+      when Hash
+        value.each_with_object({}) { |(key, entry), result| result[key] = deep_dup(entry) }
+      when Array
+        value.map { |entry| deep_dup(entry) }
+      when String
+        value.dup
+      else
+        value
+      end
+    end
+
+    def codex_sse_message(state)
+      message = { "role" => "assistant", "content" => codex_visible_content(state) }
       message["reasoning_summary"] = state[:reasoning_summary] unless state[:reasoning_summary].empty?
       message["tool_calls"] = state[:tool_calls] unless state[:tool_calls].empty?
+      response_items = codex_response_items(state)
+      message["response_items"] = response_items unless response_items.empty?
       message["usage"] = state[:usage] if state[:usage]
       message
     end
 
+    def codex_visible_content(state)
+      return state[:content] unless state[:content].empty?
+
+      response_items = codex_response_items(state)
+      visible_text = text_from_codex_items(visible_codex_message_items(response_items, tool_calls: state[:tool_calls]))
+      return visible_text unless visible_text.empty?
+      return "" unless state[:tool_calls].empty?
+
+      state[:raw_content]
+    end
+
+    def visible_codex_message_items(items, tool_calls: [])
+      messages = Array(items).select { |item| item.is_a?(Hash) && item["type"] == "message" }
+      final_messages = messages.select { |item| codex_message_phase(item) == "final_answer" }
+      return final_messages unless final_messages.empty?
+      return [] unless tool_calls.empty?
+
+      messages.reject { |item| codex_message_phase(item) == "commentary" }
+    end
+
+    def codex_streamable_message_item?(item)
+      codex_message_phase(item) == "final_answer"
+    end
+
+    def codex_message_phase(item)
+      item["phase"].to_s
+    end
+
+    def codex_response_items(state)
+      state[:response_item_keys].filter_map { |key| state[:items_by_id][key] }
+    end
+
     def codex_tool_call(item)
       return nil unless item.is_a?(Hash) && ["function_call", "custom_tool_call"].include?(item["type"])
 

data/lib/kward/pan/server.rb

@@ -15,7 +15,9 @@ require_relative "../tools/tool_call"
 require_relative "../tools/registry"
 require_relative "../workspace"
 
+# Namespace for the Kward CLI agent runtime.
 module Kward
+  # Minimal local HTTP server for the experimental Pan web UI.
   class PanServer
     DEFAULT_HOST = "0.0.0.0"
     DEFAULT_PORT = 8765
@@ -269,7 +271,7 @@ module Kward
     end
 
     def pan_config(config)
-      values = config["pan_mode"] || config["panMode"]
+      values = config["pan_mode"]
       values.is_a?(Hash) ? values : {}
     end
 

data/lib/kward/plugin_registry.rb

@@ -1,11 +1,17 @@
 require_relative "config_files"
 
+# Namespace for the Kward CLI agent runtime.
 module Kward
   # Loads trusted user plugin files and provides the plugin DSL.
   #
   # Plugins live in the user plugin directory, run as local Ruby code, and can
   # register slash commands, one footer renderer, prompt context, and live
   # transcript-event observers for CLI and RPC frontends.
+  #
+  # This registry is intentionally trust-based, not a sandbox. Keep plugin loading
+  # restricted to `ConfigFiles.plugin_paths`, keep workspace-local code out of the
+  # load path, and expose immutable transcript views so plugins can observe state
+  # without corrupting active conversations.
   class PluginRegistry
     COMMAND_NAME_PATTERN = /\A[A-Za-z0-9][A-Za-z0-9_-]*\z/.freeze
 
@@ -26,6 +32,7 @@ module Kward
 
     # Read-only transcript view exposed to plugin code.
     class Transcript
+      # Creates an object for trusted plugin loading and dispatch.
       def initialize(conversation)
         @conversation = conversation
       end
@@ -43,6 +50,7 @@ module Kward
     class Context
       attr_reader :args, :workspace_root
 
+      # Creates an object for trusted plugin loading and dispatch.
       def initialize(conversation:, args: "", session: nil, workspace_root: Dir.pwd, say_callback: nil)
         @conversation = conversation
         @args = args.to_s
@@ -89,6 +97,7 @@ module Kward
 
     # DSL object yielded by `Kward.plugin` blocks.
     class DSL
+      # Creates an object for trusted plugin loading and dispatch.
       def initialize(registry, path)
         @registry = registry
         @path = path
@@ -128,6 +137,7 @@ module Kward
       end
     end
 
+    # Mutable singleton guard used while loading trusted plugin files.
     class << self
       attr_accessor :loading_registry, :loading_path
 
@@ -161,6 +171,7 @@ module Kward
       end
     end
 
+    # Creates an object for trusted plugin loading and dispatch.
     def initialize(reserved_commands: [])
       @reserved_commands = reserved_commands.map(&:to_s)
       @commands = {}
@@ -170,6 +181,7 @@ module Kward
       @prompt_context_renderers = []
     end
 
+    # @return [String, nil] plugin file currently responsible for footer output
     attr_reader :footer_path
 
     def commands

data/lib/kward/private_file.rb

@@ -1,7 +1,9 @@
 require "fileutils"
 require "json"
 
+# Namespace for the Kward CLI agent runtime.
 module Kward
+  # Writes sensitive JSON files with private filesystem permissions.
   module PrivateFile
     module_function
 

data/lib/kward/prompt_interface/banner.rb

@@ -2,8 +2,11 @@ require_relative "../ansi"
 require_relative "../resources/avatar_kward_logo"
 require_relative "../resources/pixel_logo"
 
+# Namespace for the Kward CLI agent runtime.
 module Kward
+  # Startup banner logo and message renderer.
   class PromptInterface
+    # Startup banner rendering data and helpers for the prompt interface.
     class Banner
       LOGO_WIDTH = 32
       LOGO_PIXEL_HEIGHT = 32