kward 0.77.0 → 0.78.0

data/lib/kward/rpc/plugin_chat_manager.rb

@@ -0,0 +1,299 @@
+require "securerandom"
+require "thread"
+require_relative "../cancellation"
+require_relative "../events"
+require_relative "../image_attachments"
+require_relative "../message_access"
+require_relative "../plugin_registry"
+require_relative "../tools/tool_call"
+require_relative "../tab_driver"
+require_relative "attachment_normalizer"
+require_relative "transcript_normalizer"
+
+# Namespace for the Kward CLI agent runtime.
+module Kward
+  module RPC
+    # Coordinates optional RPC access to plugin-owned conversational runtimes.
+    # Unlike SessionManager, this manager never creates workspace sessions,
+    # agents, or tool registries: each plugin driver owns its chat and storage.
+    class PluginChatManager
+      EVENT_LIMIT = 1_000
+      WORKER_STOP = Object.new.freeze
+
+      Chat = Struct.new(:id, :type, :driver, :queue, :worker, :running_turn_id, keyword_init: true)
+      Turn = Struct.new(:id, :chat_id, :input, :display_input, :status, :cancellation, :created_at, :started_at, :finished_at, :events, :next_sequence, :error, :mutex, keyword_init: true)
+
+      def initialize(server:, client: Client.new)
+        @server = server
+        @client = client
+        @chats = {}
+        @turns = {}
+        @subscriptions = {}
+        @mutex = Mutex.new
+      end
+
+      def supported_types
+        plugin_registry.tab_types.select(&:rpc)
+      end
+
+      def list
+        { chats: supported_types.map { |type| type_payload(type) } }
+      end
+
+      def open(type_id:)
+        type = supported_types.find { |entry| entry.id == type_id.to_s } || raise(ArgumentError, "Unknown RPC plugin chat: #{type_id}")
+        chat = chat_for(type)
+        return chat_payload(chat) if chat.driver.respond_to?(:transcript_page)
+
+        chat_payload(chat).merge(messages: TranscriptNormalizer.new(chat.driver.messages).normalize)
+      end
+
+      def transcript(chat_id:, limit: nil, before: nil)
+        chat = fetch_chat(chat_id)
+        page = transcript_page(chat.driver, limit: limit, before: before)
+        {
+          chat: chat_payload(chat),
+          messages: TranscriptNormalizer.new(page.fetch(:messages)).normalize,
+          hasMore: page.fetch(:has_more),
+          nextBefore: page[:next_before]
+        }.compact
+      end
+
+      def subscribe(chat_id:)
+        chat = fetch_chat(chat_id)
+        @mutex.synchronize { @subscriptions[chat.id] = true }
+        { chat: chat_payload(chat), subscribed: true }
+      end
+
+      def unsubscribe(chat_id:)
+        chat = fetch_chat(chat_id)
+        @mutex.synchronize { @subscriptions.delete(chat.id) }
+        { chat: chat_payload(chat), subscribed: false }
+      end
+
+      def start_turn(chat_id:, input:, attachments: [])
+        chat = fetch_chat(chat_id)
+        normalized_attachments = AttachmentNormalizer.new.normalize(attachments)
+        turn = Turn.new(
+          id: SecureRandom.uuid,
+          chat_id: chat.id,
+          input: input_with_attachments(input, normalized_attachments),
+          display_input: input.to_s,
+          status: "queued",
+          cancellation: Cancellation.new,
+          created_at: Time.now.utc.iso8601(3),
+          events: [],
+          next_sequence: 1,
+          mutex: Mutex.new
+        )
+        @mutex.synchronize { @turns[turn.id] = turn }
+        chat.queue << turn.id
+        ensure_worker(chat)
+        emit_event(turn, "turnQueued", { status: "queued" })
+        turn_payload(turn)
+      end
+
+      def cancel_turn(turn_id:)
+        turn = fetch_turn(turn_id)
+        queued = turn.mutex.synchronize do
+          turn.cancellation.cancel!
+          turn.status == "queued"
+        end
+        emit_event(turn, "turnCancelRequested", {})
+        finish_turn(turn, "canceled") if queued
+        turn_payload(turn)
+      end
+
+      def turn_status(turn_id:)
+        turn_payload(fetch_turn(turn_id))
+      end
+
+      def turn_events(turn_id:, after_sequence: 0)
+        turn = fetch_turn(turn_id)
+        events = turn.mutex.synchronize { turn.events.select { |event| event[:sequence].to_i > after_sequence.to_i } }
+        { turn: turn_payload(turn), events: events }
+      end
+
+      def list_turns(chat_id: nil, active: false)
+        turns = @mutex.synchronize { @turns.values.dup }
+        turns.select! { |turn| turn.chat_id == chat_id.to_s } if chat_id
+        turns.select! { |turn| %w[queued running].include?(turn.status) } if active
+        { turns: turns.map { |turn| turn_payload(turn) } }
+      end
+
+      def shutdown
+        chats = @mutex.synchronize { @chats.values.dup }
+        chats.each do |chat|
+          chat.queue << WORKER_STOP if chat.worker&.alive?
+          chat.worker&.join(0.2)
+        end
+      end
+
+      private
+
+      def plugin_registry
+        @plugin_registry ||= PluginRegistry.load
+      end
+
+      def chat_for(type)
+        @mutex.synchronize do
+          @chats[type.id] ||= begin
+            descriptor = { "kind" => "plugin", "plugin_tab_type" => type.id, "label" => type.title }
+            driver = type.handler.call(PluginTabHost.new(client: @client, workspace_root: Dir.pwd), descriptor)
+            raise "Plugin chat #{type.id.inspect} did not return a tab driver." unless driver
+
+            Chat.new(id: type.id, type: type, driver: driver, queue: Queue.new)
+          end
+        end
+      end
+
+      def fetch_chat(chat_id)
+        @mutex.synchronize { @chats[chat_id.to_s] } || open(type_id: chat_id).then { @mutex.synchronize { @chats[chat_id.to_s] } }
+      end
+
+      def fetch_turn(turn_id)
+        @mutex.synchronize { @turns[turn_id.to_s] } || raise(ArgumentError, "Unknown plugin chat turn: #{turn_id}")
+      end
+
+      def ensure_worker(chat)
+        return if chat.worker&.alive?
+
+        chat.worker = Thread.new do
+          loop do
+            turn_id = chat.queue.pop
+            break if turn_id.equal?(WORKER_STOP)
+
+            turn = fetch_turn(turn_id)
+            run_turn(chat, turn) unless turn.cancellation.cancelled?
+          end
+        end
+        chat.worker.report_on_exception = false
+      end
+
+      def run_turn(chat, turn)
+        turn.mutex.synchronize do
+          return if terminal?(turn)
+
+          turn.status = "running"
+          turn.started_at = Time.now.utc.iso8601(3)
+        end
+        chat.running_turn_id = turn.id
+        emit_event(turn, "turnStarted", { status: "running" })
+        chat.driver.submit(turn.input, display_input: turn.display_input, cancellation: turn.cancellation) do |event|
+          handle_driver_event(chat, turn, event)
+        end
+        finish_turn(turn, turn.cancellation.cancelled? ? "canceled" : "completed")
+      rescue Cancellation::CancelledError
+        finish_turn(turn, "canceled")
+      rescue StandardError => e
+        turn.mutex.synchronize { turn.error = { message: e.message, code: e.class.name, fatal: false } }
+        finish_turn(turn, "failed")
+      ensure
+        chat.running_turn_id = nil if chat.running_turn_id == turn.id
+      end
+
+      def handle_driver_event(chat, turn, event)
+        notify_plugin_tab_transcript_event(chat, event) if chat.type.transcript_events
+
+        type, payload = case event
+        when Events::ReasoningDelta then ["reasoningDelta", { delta: event.delta }]
+        when Events::ReasoningBoundary then ["reasoningBoundary", {}]
+        when Events::AssistantDelta then ["assistantDelta", { delta: event.delta }]
+        when Events::AssistantMessage then ["assistantMessage", { message: TranscriptNormalizer.new([event.message]).normalize.first }]
+        when Events::Retry then ["modelRetry", retry_event_payload(event)]
+        when Events::ToolCall then ["toolCall", tool_call_payload(event.tool_call)]
+        when Events::ToolResult then ["toolResult", tool_result_payload(event.tool_call, event.content)]
+        when Events::Answer then ["answer", { content: event.content }]
+        end
+        emit_event(turn, type, payload) if type
+      end
+
+      def notify_plugin_tab_transcript_event(chat, event)
+        return if plugin_registry.transcript_event_handlers.empty?
+
+        context = PluginRegistry::Context.new(conversation: chat.driver, workspace_root: Dir.pwd)
+        plugin_registry.notify_transcript_event(event, context)
+      end
+
+      def retry_event_payload(event)
+        { provider: event.provider, model: event.model, attempt: event.attempt, maxAttempts: event.max_attempts, delaySeconds: event.delay_seconds, error: event.error, requestBytes: event.request_bytes }.compact
+      end
+
+      def tool_call_payload(tool_call)
+        { toolCallId: ToolCall.id(tool_call), toolName: ToolCall.name(tool_call), args: ToolCall.parse_arguments(ToolCall.raw_arguments(tool_call)) }.compact
+      end
+
+      def tool_result_payload(tool_call, content)
+        { toolCallId: ToolCall.id(tool_call), toolName: ToolCall.name(tool_call), result: { content: content.to_s, isError: content.to_s.start_with?("Unknown", "Invalid", "Research tool failed") } }.compact
+      end
+
+      def finish_turn(turn, status)
+        event = turn.mutex.synchronize do
+          next nil if terminal?(turn)
+
+          turn.status = status
+          turn.finished_at = Time.now.utc.iso8601(3)
+          append_event(turn, "turnFinished", { status: status, error: turn.error }.compact)
+        end
+        notify_event(event) if event
+      end
+
+      def emit_event(turn, type, payload)
+        event = turn.mutex.synchronize { append_event(turn, type, payload) }
+        notify_event(event)
+      end
+
+      def append_event(turn, type, payload)
+        event = {
+          sequence: turn.next_sequence,
+          timestamp: Time.now.utc.iso8601(3),
+          chatId: turn.chat_id,
+          turnId: turn.id,
+          type: type,
+          payload: payload
+        }
+        turn.next_sequence += 1
+        turn.events << event
+        turn.events.shift while turn.events.length > EVENT_LIMIT
+        event
+      end
+
+      def notify_event(event)
+        subscribed = @mutex.synchronize { @subscriptions[event[:chatId]] }
+        @server.notify("pluginChat/event", event) if subscribed
+      end
+
+      def input_with_attachments(input, attachments)
+        return input.to_s if attachments.empty?
+
+        [{ type: "text", text: input.to_s }] + attachments.map do |attachment|
+          { type: "image", media_type: attachment[:mimeType], data: attachment[:data], alt: attachment[:alt] }
+        end
+      end
+
+      def terminal?(turn)
+        %w[completed failed canceled].include?(turn.status)
+      end
+
+      def type_payload(type)
+        { id: type.id, name: type.name, title: type.title, singleton: type.singleton }.compact
+      end
+
+      def transcript_page(driver, limit:, before:)
+        return { messages: driver.messages, has_more: false } unless limit && driver.respond_to?(:transcript_page)
+
+        driver.transcript_page(limit: limit, before: before)
+      end
+
+      def chat_payload(chat)
+        type_payload(chat.type).merge(id: chat.id, subscribed: @mutex.synchronize { @subscriptions[chat.id] == true })
+      end
+
+      def turn_payload(turn)
+        turn.mutex.synchronize do
+          { id: turn.id, chatId: turn.chat_id, status: turn.status, createdAt: turn.created_at, startedAt: turn.started_at, finishedAt: turn.finished_at, error: turn.error }.compact
+        end
+      end
+    end
+  end
+end

data/lib/kward/rpc/server.rb

@@ -13,6 +13,7 @@ require_relative "config_manager"
 require_relative "mcp_status"
 require_relative "redactor"
 require_relative "session_manager"
+require_relative "plugin_chat_manager"
 require_relative "transport"
 
 # Namespace for the Kward CLI agent runtime.
@@ -57,6 +58,7 @@ module Kward
         "sessions/export", "sessions/delete", "sessions/close", "sessions/transcript", "sessions/active"
       ].freeze
       TURN_METHODS = ["turns/start", "turns/cancel", "turns/status", "turns/events", "turns/list", "turns/listActive"].freeze
+      PLUGIN_CHAT_METHODS = ["pluginChats/list", "pluginChats/open", "pluginChats/transcript", "pluginChats/subscribe", "pluginChats/unsubscribe", "pluginChats/turns/start", "pluginChats/turns/cancel", "pluginChats/turns/status", "pluginChats/turns/events", "pluginChats/turns/list", "pluginChats/turns/listActive"].freeze
       MODEL_METHODS = ["models/list", "models/current", "models/set", "reasoning/set"].freeze
       RUNTIME_METHODS = ["runtime/state", "runtime/stats"].freeze
       RUNTIME_SETTING_METHODS = ["runtime/updateSetting", "runtime/reload"].freeze
@@ -92,6 +94,7 @@ module Kward
         prompts: PROMPT_METHODS,
         sessions: SESSION_METHODS,
         turns: TURN_METHODS,
+        plugin_chats: PLUGIN_CHAT_METHODS,
         models: MODEL_METHODS,
         runtime: RUNTIME_METHODS,
         runtime_settings: RUNTIME_SETTING_METHODS,
@@ -119,6 +122,7 @@ module Kward
         @client = client
         @config_manager = ConfigManager.new
         @session_manager = SessionManager.new(server: self, client: client, config_manager: @config_manager)
+        @plugin_chat_manager = PluginChatManager.new(server: self, client: client)
         @auth_manager = AuthManager.new(server: self, config_manager: @config_manager)
         @shutdown = false
       end
@@ -140,6 +144,7 @@ module Kward
           end
         end
       ensure
+        @plugin_chat_manager.shutdown
         @session_manager.shutdown_sessions
       end
 
@@ -349,6 +354,28 @@ module Kward
           @session_manager.list_turns(session_id: params["sessionId"])
         when TURN_METHODS[5]
           @session_manager.list_turns(session_id: params["sessionId"], active: true)
+        when PLUGIN_CHAT_METHODS[0]
+          @plugin_chat_manager.list
+        when PLUGIN_CHAT_METHODS[1]
+          @plugin_chat_manager.open(type_id: params.fetch("typeId"))
+        when PLUGIN_CHAT_METHODS[2]
+          @plugin_chat_manager.transcript(chat_id: params.fetch("chatId"), limit: params["limit"], before: params["before"])
+        when PLUGIN_CHAT_METHODS[3]
+          @plugin_chat_manager.subscribe(chat_id: params.fetch("chatId"))
+        when PLUGIN_CHAT_METHODS[4]
+          @plugin_chat_manager.unsubscribe(chat_id: params.fetch("chatId"))
+        when PLUGIN_CHAT_METHODS[5]
+          @plugin_chat_manager.start_turn(chat_id: params.fetch("chatId"), input: params.fetch("input"), attachments: params["attachments"] || [])
+        when PLUGIN_CHAT_METHODS[6]
+          @plugin_chat_manager.cancel_turn(turn_id: params.fetch("turnId"))
+        when PLUGIN_CHAT_METHODS[7]
+          @plugin_chat_manager.turn_status(turn_id: params.fetch("turnId"))
+        when PLUGIN_CHAT_METHODS[8]
+          @plugin_chat_manager.turn_events(turn_id: params.fetch("turnId"), after_sequence: params["afterSequence"] || 0)
+        when PLUGIN_CHAT_METHODS[9]
+          @plugin_chat_manager.list_turns(chat_id: params["chatId"])
+        when PLUGIN_CHAT_METHODS[10]
+          @plugin_chat_manager.list_turns(chat_id: params["chatId"], active: true)
         when UI_METHODS[0]
           @session_manager.answer_question(session_id: params.fetch("sessionId"), question_request_id: params.fetch("questionRequestId"), answers: params.fetch("answers"))
         when TOOL_APPROVAL_METHODS[0]
@@ -392,6 +419,14 @@ module Kward
             tree: { supported: true, method: SESSION_METHODS[8], labels: true, labelTimestamps: true, navigate: true, summarize: true, shape: "kward-tree-items-v1" },
             updates: { supported: false, notification: SESSION_UPDATED_NOTIFICATION }
           },
+          pluginChats: {
+            supported: @plugin_chat_manager.supported_types.any?,
+            methods: PLUGIN_CHAT_METHODS,
+            notification: "pluginChat/event",
+            subscriptions: { supported: true, methods: PLUGIN_CHAT_METHODS.values_at(3, 4), requiredForLiveEvents: true },
+            attachments: { supported: true, method: PLUGIN_CHAT_METHODS[5], encoding: "base64", mimeTypes: SessionManager::RPC_IMAGE_MIME_TYPES, maxBytes: SessionManager::RPC_ATTACHMENT_MAX_BYTES },
+            types: @plugin_chat_manager.supported_types.map { |type| { id: type.id, name: type.name, title: type.title, singleton: type.singleton }.compact }
+          },
           turns: {
             mode: "async",
             perSessionConcurrency: 1,

data/lib/kward/rpc/session_manager.rb

@@ -968,6 +968,7 @@ module Kward
           prompt: prompt,
           allowed_tool_names: allowed_tool_names,
           tool_approval: tool_approval,
+          approval_for_allowed_tools: !tool_approval.nil?,
           hook_manager: hook_manager,
           hook_context: hook_context
         )

data/lib/kward/rpc/transcript_normalizer.rb

@@ -54,10 +54,13 @@ module Kward
       end
 
       def normalize_user_message(message)
-        {
-          role: "user",
-          content: normalize_content(MessageAccess.content(message))
-        }
+        with_timestamp(
+          {
+            role: "user",
+            content: normalize_content(MessageAccess.content(message))
+          },
+          message
+        )
       end
 
       def normalize_assistant_message(message)
@@ -76,7 +79,7 @@ module Kward
         result = { role: "assistant", content: content }
         error_message = ToolCall.value(message, :errorMessage) || ToolCall.value(message, :error_message)
         result[:errorMessage] = error_message unless error_message.to_s.empty?
-        result
+        with_timestamp(result, message)
       end
 
       def normalize_tool_result_message(message)
@@ -96,6 +99,12 @@ module Kward
 
         details = tool_result_details(message, matching_call, content)
         result[:details] = details unless details.empty?
+        with_timestamp(result, message)
+      end
+
+      def with_timestamp(result, message)
+        timestamp = ToolCall.value(message, :timestamp)
+        result[:timestamp] = timestamp if timestamp
         result
       end
 

data/lib/kward/starter_pack_installer.rb

@@ -6,6 +6,7 @@ require "tmpdir"
 require "uri"
 require "zlib"
 require_relative "config_files"
+require_relative "http"
 
 # Namespace for the Kward CLI agent runtime.
 module Kward
@@ -56,8 +57,9 @@ module Kward
 
     def download(url)
       uri = URI(url)
+      request = Http.apply_user_agent(Net::HTTP::Get.new(uri))
       response = Net::HTTP.start(uri.hostname, uri.port, use_ssl: uri.scheme == "https", open_timeout: 10, read_timeout: 30) do |http|
-        http.get(uri.request_uri)
+        http.request(request)
       end
       raise "Starter pack download failed with HTTP #{response.code}" unless response.is_a?(Net::HTTPSuccess)
 

data/lib/kward/tab_driver.rb

@@ -0,0 +1,87 @@
+# Namespace for the Kward CLI agent runtime.
+module Kward
+  # Adapts a session-backed agent to the tab runtime interface. Plugin tab
+  # drivers implement the same small surface without becoming Kward sessions.
+  class SessionTabDriver
+    attr_reader :session, :agent
+
+    def initialize(session:, agent:)
+      @session = session
+      @agent = agent
+    end
+
+    def messages
+      agent.conversation.messages
+    end
+
+    def conversation
+      agent.conversation
+    end
+
+    def submit(input, display_input:, cancellation:, steering: nil, &block)
+      options = { cancellation: cancellation }
+      options[:display_input] = display_input unless display_input.nil?
+      options[:steering] = steering if steering
+      agent.ask(input, **options, &block)
+    end
+
+    def descriptor
+      { "kind" => "session", "session_path" => session.path }
+    end
+
+    def session?
+      true
+    end
+
+    def supports_steering?
+      true
+    end
+
+    def assistant_label
+      nil
+    end
+  end
+
+  # Represents a persisted plugin tab whose provider plugin is unavailable.
+  # Its descriptor is retained so reinstalling the plugin restores the tab.
+  class UnavailableTabDriver
+    attr_reader :descriptor
+
+    def initialize(descriptor:, message:)
+      @descriptor = descriptor
+      @message = message
+    end
+
+    def messages
+      [{ role: "assistant", content: @message }]
+    end
+
+    def submit(*)
+      raise @message
+    end
+
+    def session?
+      false
+    end
+
+    def supports_steering?
+      false
+    end
+
+    def assistant_label
+      "Plugin"
+    end
+  end
+
+  # Dependencies made available to a plugin tab factory. The host deliberately
+  # exposes provider transport and frontend-neutral facts, not CLI internals or
+  # workspace session state.
+  class PluginTabHost
+    attr_reader :client, :workspace_root
+
+    def initialize(client:, workspace_root:)
+      @client = client
+      @workspace_root = workspace_root
+    end
+  end
+end

data/lib/kward/tab_store.rb

@@ -5,32 +5,45 @@ require_relative "private_file"
 
 # Namespace for the Kward CLI agent runtime.
 module Kward
-  # Persists the terminal UI's open session tabs per workspace.
+  # Persists the terminal UI's open tabs per workspace.
   class TabStore
+    VERSION = 2
+
     def initialize(config_dir: ConfigFiles.config_dir, cwd: Dir.pwd)
       @config_dir = config_dir
       @cwd = File.expand_path(cwd)
     end
 
     def load
-      return { "session_paths" => [], "active_index" => 0 } unless File.file?(path)
+      return empty_state unless File.file?(path)
 
       data = JSON.parse(File.read(path))
-      paths = Array(data["session_paths"]).map(&:to_s).reject(&:empty?)
-      labels = Array(data["labels"]).map(&:to_s)
-      active_index = data["active_index"].to_i
-      { "session_paths" => paths, "labels" => labels, "active_index" => active_index }
+      return typed_state(data) if data["tabs"].is_a?(Array)
+
+      legacy_state(data)
     rescue JSON::ParserError
-      { "session_paths" => [], "active_index" => 0 }
+      empty_state
     end
 
-    def save(session_paths:, active_index:, labels: [])
-      paths = Array(session_paths).map(&:to_s).reject(&:empty?)
+    # `session_paths` remains supported for callers and layouts written before
+    # typed tab descriptors were introduced.
+    def save(session_paths: nil, tabs: nil, active_index:, labels: [])
+      tabs ||= Array(session_paths).filter_map.with_index do |session_path, index|
+        path = session_path.to_s
+        next if path.empty?
+
+        {
+          "kind" => "session",
+          "session_path" => path,
+          "label" => Array(labels)[index].to_s
+        }
+      end
+      tabs = normalize_tabs(tabs)
       PrivateFile.write_json(path, {
+        "version" => VERSION,
         "cwd" => @cwd,
-        "session_paths" => paths,
-        "labels" => Array(labels).map(&:to_s),
-        "active_index" => [[active_index.to_i, 0].max, [paths.length - 1, 0].max].min
+        "tabs" => tabs,
+        "active_index" => [[active_index.to_i, 0].max, [tabs.length - 1, 0].max].min
       })
     end
 
@@ -40,6 +53,55 @@ module Kward
 
     private
 
+    def empty_state
+      { "tabs" => [], "session_paths" => [], "labels" => [], "active_index" => 0 }
+    end
+
+    def typed_state(data)
+      tabs = normalize_tabs(data["tabs"])
+      state_for(tabs, data["active_index"])
+    end
+
+    def legacy_state(data)
+      paths = Array(data["session_paths"]).map(&:to_s).reject(&:empty?)
+      labels = Array(data["labels"]).map(&:to_s)
+      tabs = paths.each_with_index.map do |session_path, index|
+        { "kind" => "session", "session_path" => session_path, "label" => labels[index].to_s }
+      end
+      state_for(tabs, data["active_index"])
+    end
+
+    def state_for(tabs, active_index)
+      {
+        "tabs" => tabs,
+        "session_paths" => tabs.filter_map { |tab| tab["session_path"] if tab["kind"] == "session" },
+        "labels" => tabs.map { |tab| tab["label"].to_s },
+        "active_index" => [[active_index.to_i, 0].max, [tabs.length - 1, 0].max].min
+      }
+    end
+
+    def normalize_tabs(tabs)
+      session_paths = {}
+
+      Array(tabs).filter_map do |tab|
+        next unless tab.is_a?(Hash)
+
+        normalized = tab.transform_keys(&:to_s)
+        kind = normalized["kind"].to_s
+        next if kind.empty?
+        next if kind == "session" && normalized["session_path"].to_s.empty?
+
+        if kind == "session"
+          session_path = File.expand_path(normalized["session_path"].to_s, @cwd)
+          next if session_paths[session_path]
+
+          session_paths[session_path] = true
+        end
+
+        normalized
+      end
+    end
+
     def workspace_key
       Digest::SHA256.hexdigest(@cwd)[0, 24]
     end

data/lib/kward/tools/code_search.rb

@@ -37,7 +37,11 @@ module Kward
             },
             path: {
               type: "string",
-              description: "Repo-relative path."
+              description: "Repo-relative path; inferred from GitHub blob URLs when omitted."
+            },
+            ref: {
+              type: "string",
+              description: "Git branch, tag, or commit; inferred from GitHub blob URLs when omitted."
             },
             start_line: {
               type: "integer",
@@ -63,7 +67,9 @@ module Kward
       # Executes the tool and returns model-facing output text.
       def call(args, _conversation, cancellation: nil)
         cancellation&.raise_if_cancelled!
-        @code_search.call(args)
+        return @code_search.call(args) unless cancellation
+
+        @code_search.call(args, cancellation: cancellation)
       end
     end
   end