kward 0.83.0 → 0.85.0

data/lib/kward/tabs/driver.rb

@@ -0,0 +1,194 @@
+require "digest"
+require "logger"
+require_relative "../config_files"
+require_relative "../deep_copy"
+require_relative "../plugins/chat_contract"
+require_relative "../plugins/host"
+require_relative "../plugins/resources"
+
+# 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, :worktree
+
+    def initialize(session:, agent:, worktree: nil)
+      @session = session
+      @agent = agent
+      @worktree = worktree
+    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
+      descriptor = { "kind" => "session", "session_path" => session.path }
+      descriptor["worktree"] = worktree.descriptor if worktree
+      descriptor
+    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 and instance-scoped services made available to a plugin chat
+  # factory without exposing CLI or workspace-session internals.
+  class PluginTabHost
+    SURFACES = %i[local rpc transport shared].freeze
+
+    class LogDevice
+      def write(message)
+        ConfigFiles.emit_warning(message.to_s.chomp)
+      end
+
+      def close
+        nil
+      end
+    end
+    private_constant :LogDevice
+
+    attr_reader :client, :workspace_root, :plugin_id, :type_id, :surface, :scope_key,
+      :capabilities, :config, :storage, :logger
+
+    def initialize(client:, workspace_root:, plugin_host: nil, type_id: nil, surface: :local, scope_key: "default", capabilities: nil, config: nil, storage: nil, logger: nil, env: ENV)
+      @client = client
+      @workspace_root = workspace_root
+      @plugin_id = plugin_host&.id
+      @type_id = required_value(type_id || @plugin_id || "anonymous", "plugin chat type id").freeze
+      @surface = normalize_surface(surface)
+      @scope_key = required_value(scope_key, "plugin chat scope key").freeze
+      @capabilities = capabilities || PluginChatCapabilities.legacy
+      @config = freeze_config(config || plugin_host&.config || ConfigFiles.plugin_config(storage_owner_id))
+      @storage = PluginScopedStore.new(storage || plugin_host&.storage || default_storage, storage_namespace)
+      @logger = logger || plugin_host&.logger || default_logger
+      @env = env
+      @resources = PluginResources.new(name: "Kward plugin chat #{@type_id}", warning_sink: ConfigFiles.warning_sink).tap(&:activate!)
+    end
+
+    # Starts cooperative background work owned by this chat instance.
+    def background(name: nil, cancellation: nil, &block)
+      @resources.background(name: name, cancellation: cancellation, &block)
+    end
+
+    # Registers cleanup that runs when the chat instance closes.
+    def on_cleanup(resource = nil, &block)
+      @resources.on_cleanup(resource, &block)
+    end
+
+    alias manage on_cleanup
+
+    # Reads a secret from private plugin config, an explicit environment
+    # variable, or the plugin's conventional KWARD_PLUGIN_* variable.
+    def secret(key, env: nil)
+      key = required_value(key, "secret key")
+      value = config[key]
+      value = @env[env.to_s] if value.nil? && env
+      value = @env[default_secret_env_name(key)] if value.nil?
+      value.to_s unless value.nil?
+    end
+
+    # Cancels chat-owned work and invokes cleanup callbacks.
+    # @api private
+    def shutdown(timeout: PluginResources::DEFAULT_SHUTDOWN_TIMEOUT)
+      @resources.shutdown(timeout: timeout)
+      self
+    end
+
+    private
+
+    def storage_owner_id
+      plugin_id || type_id
+    end
+
+    def storage_namespace
+      "plugin_chat:#{type_id}:#{scope_key}"
+    end
+
+    def default_storage
+      safe_id = "chat.#{Digest::SHA256.hexdigest(storage_owner_id)[0, 24]}"
+      PluginStore.new(safe_id)
+    end
+
+    def freeze_config(value)
+      raise ArgumentError, "Kward plugin config for #{storage_owner_id} must be an object" unless value.is_a?(Hash)
+
+      DeepCopy.freeze(DeepCopy.dup(value))
+    end
+
+    def normalize_surface(value)
+      surface = value.to_sym
+      raise ArgumentError, "Unknown plugin chat surface: #{value}" unless SURFACES.include?(surface)
+
+      surface
+    end
+
+    def required_value(value, name)
+      value = value.to_s
+      raise ArgumentError, "#{name} is required" if value.empty?
+
+      value
+    end
+
+    def default_secret_env_name(key)
+      parts = [storage_owner_id, key].map { |part| part.gsub(/[^A-Za-z0-9]/, "_").upcase }
+      "KWARD_PLUGIN_#{parts.join("_")}"
+    end
+
+    def default_logger
+      Logger.new(LogDevice.new).tap { |logger| logger.progname = "Kward plugin chat #{type_id}" }
+    end
+  end
+end

data/lib/kward/{tab_store.rb → tabs/store.rb}

@@ -1,7 +1,7 @@
 require "digest"
 require "json"
-require_relative "config_files"
-require_relative "private_file"
+require_relative "../config_files"
+require_relative "../private_file"
 
 # Namespace for the Kward CLI agent runtime.
 module Kward

data/lib/kward/{ansi.rb → terminal/ansi.rb}

@@ -23,6 +23,12 @@ module Kward
       gray: 90,
       grey: 90,
       white: 97,
+      activity: 36,
+      success: 32,
+      caution: 33,
+      failure: 31,
+      tool: 35,
+      metadata: 90,
       primary_green: "38;2;138;160;106",
       bright_accent_green: "38;2;155;255;0",
       augen: "38;2;155;255;0",
@@ -181,23 +187,30 @@ module Kward
         @enabled = enabled
         @pending = +""
         @in_fence = false
+        @line_streaming = false
       end
 
       def render(delta, final: false)
-        text = delta.to_s
-        return ANSI.markdown(text, enabled: @enabled) if fast_markdown?(text, final)
-
-        @pending << text
+        @pending << delta.to_s
         rendered = +""
         while (match = @pending.match(/\r\n|\r|\n/))
           line = @pending[0...match.begin(0)]
           @pending = @pending[(match.end(0))..] || +""
-          rendered << render_line(line) << "\n"
+          rendered << render_pending_line(line) << "\n"
         end
 
-        if final && !@pending.empty?
-          rendered << render_line(@pending)
-          @pending.clear
+        if final
+          unless @pending.empty?
+            rendered << render_pending_line(@pending)
+            @pending.clear
+          end
+        else
+          streamable = streamable_inline_prefix
+          unless streamable.empty?
+            rendered << ANSI.inline_markdown(streamable, enabled: @enabled)
+            @pending = @pending[streamable.length..] || +""
+            @line_streaming = true
+          end
         end
 
         if final && @in_fence
@@ -211,8 +224,95 @@ module Kward
 
       private
 
-      def fast_markdown?(text, final)
-        !final && !@in_fence && @pending.empty? && !text.match?(/[`*~_\[\]>]/)
+      def render_pending_line(line)
+        if @line_streaming
+          @line_streaming = false
+          ANSI.inline_markdown(line, enabled: @enabled)
+        else
+          render_line(line)
+        end
+      end
+
+      def streamable_inline_prefix
+        return "" if @pending.empty? || block_line_pending?
+
+        boundary = [
+          unmatched_marker_index("`"),
+          unmatched_marker_index("**"),
+          unmatched_marker_index("~~"),
+          unmatched_emphasis_index("*"),
+          unmatched_emphasis_index("_"),
+          incomplete_marker_prefix_index,
+          incomplete_link_index
+        ].compact.min
+        boundary ? @pending[0...boundary] : @pending.dup
+      end
+
+      def unmatched_marker_index(marker)
+        unmatched = nil
+        offset = 0
+        while (index = @pending.index(marker, offset))
+          unmatched = unmatched ? nil : index
+          offset = index + marker.length
+        end
+        unmatched
+      end
+
+      def unmatched_emphasis_index(marker)
+        unmatched = nil
+        offset = 0
+        while (index = @pending.index(marker, offset))
+          previous = index.positive? ? @pending[index - 1] : nil
+          following = @pending[index + 1]
+          offset = index + 1
+          next if previous == marker || following == marker
+
+          if unmatched
+            unmatched = nil if following.nil? || following.match?(/[\s\)\]},.!?:;]/)
+          elsif previous.nil? || previous.match?(/[\s\(\[{]/)
+            unmatched = index
+          end
+        end
+        unmatched
+      end
+
+      def incomplete_marker_prefix_index
+        trailing = @pending[/~+\z/]
+        return nil unless trailing&.length&.odd?
+
+        @pending.length - 1
+      end
+
+      def incomplete_link_index
+        offset = 0
+        while (opening = @pending.index("[", offset))
+          closing = @pending.index("]", opening + 1)
+          return opening unless closing
+          return opening if closing == @pending.length - 1
+
+          unless @pending[closing + 1] == "("
+            offset = closing + 1
+            next
+          end
+
+          closing_parenthesis = @pending.index(")", closing + 2)
+          return opening unless closing_parenthesis
+
+          offset = closing_parenthesis + 1
+        end
+        nil
+      end
+
+      def block_line_pending?
+        return true if @in_fence
+        return false if @line_streaming
+
+        line = @pending.lstrip
+        line.start_with?("```") || line.match?(/\A`{1,2}\z/) ||
+          line.match?(/\A\#{1,6}(?:\s|\z)/) ||
+          line.start_with?(">") ||
+          line.match?(/\A[-*]\s+\[[ xX]\](?:\s|\z)/) ||
+          line.match?(/\A[-*](?:\s*\z|\s+\[[ xX]?\z)/)
       end
 
       def render_line(line)

data/lib/kward/{clipboard.rb → terminal/clipboard.rb}

@@ -1,5 +1,5 @@
 require "open3"
-require_relative "terminal_sequences"
+require_relative "sequences"
 require "rbconfig"
 
 # Namespace for the Kward CLI agent runtime.

data/lib/kward/{terminal_image_support.rb → terminal/image_support.rb}

@@ -1,4 +1,4 @@
-require_relative "terminal_sequences"
+require_relative "sequences"
 
 # Namespace for the Kward CLI agent runtime.
 module Kward

data/lib/kward/{terminal_keys.rb → terminal/keys.rb}

@@ -9,6 +9,8 @@ module Kward
     CTRL_D = "\x04".freeze
     CTRL_E = "\x05".freeze
     CTRL_F = "\x06".freeze
+    CTRL_H = "\x08".freeze
+    CTRL_J = "\x0A".freeze
     CTRL_K = "\x0B".freeze
     CTRL_L = "\x0C".freeze
     CTRL_N = "\x0E".freeze
@@ -71,6 +73,16 @@ module Kward
     CTRL_T_CSI_U = "\e[116;5u".freeze
     CTRL_W_CSI_U = "\e[119;5u".freeze
     CTRL_NUMBER_TAB_PATTERN = /\A\e\[((?:49)|(?:5[0-7]));5u\z/.freeze
+    TAB_ACTION_SEQUENCES = (
+      CTRL_TAB +
+      CTRL_SHIFT_TAB +
+      [CTRL_T, CTRL_T_CSI_U, CTRL_W_CSI_U] +
+      (49..57).map { |code| "\e[#{code};5u" } +
+      ["\et", "\eT"] +
+      ALT_RIGHT +
+      ALT_LEFT +
+      (1..9).map { |number| "\e#{number}" }
+    ).freeze
 
     CSI_U_PATTERN = /\A\e\[(\d+)((?:;[\d:]*)*)u/.freeze
     MODIFIED_CURSOR_PATTERN = /\A\e\[(\d+);(\d+)([CDFH])\z/.freeze

data/lib/kward/terminal/text.rb

@@ -0,0 +1,121 @@
+require "unicode/display_width"
+
+# Namespace for the Kward CLI agent runtime.
+module Kward
+  # Terminal-cell and grapheme helpers for cursor-aware text layout.
+  module TerminalText
+    module_function
+
+    def width(text)
+      Unicode::DisplayWidth.of(text.to_s, ambiguous: 1, emoji: :all)
+    end
+
+    def truncate(text, max_width)
+      string = text.to_s
+      limit = [max_width.to_i, 0].max
+      return string[0, limit].to_s if string.ascii_only?
+
+      remaining = limit
+      truncated = +""
+      string.each_grapheme_cluster do |grapheme|
+        grapheme_width = width(grapheme)
+        break if grapheme_width > remaining
+
+        truncated << grapheme
+        remaining -= grapheme_width
+      end
+      truncated
+    end
+
+    def wrap(text, width:, cursor: nil)
+      string = text.to_s
+      line_width = [width.to_i, 1].max
+      return wrap_ascii(string, line_width, cursor) if string.ascii_only?
+
+      rows = [+""]
+      row_widths = [0]
+      cursor_row = nil
+      cursor_col = nil
+      offset = 0
+
+      string.each_grapheme_cluster do |grapheme|
+        if !cursor.nil? && cursor_row.nil? && cursor <= offset
+          append_empty_row(rows, row_widths) if row_widths.last >= line_width
+          cursor_row = rows.length - 1
+          cursor_col = row_widths.last
+        end
+
+        grapheme_width = width(grapheme)
+        append_empty_row(rows, row_widths) if row_widths.last.positive? && row_widths.last + grapheme_width > line_width
+        rows.last << grapheme
+        row_widths[-1] += grapheme_width
+        offset += grapheme.length
+
+        if !cursor.nil? && cursor_row.nil? && cursor <= offset
+          cursor_row = rows.length - 1
+          cursor_col = row_widths.last
+        end
+      end
+
+      if !cursor.nil? && cursor_row.nil?
+        append_empty_row(rows, row_widths) if row_widths.last >= line_width
+        cursor_row = rows.length - 1
+        cursor_col = row_widths.last
+      elsif !cursor.nil? && cursor >= offset && row_widths.last >= line_width
+        append_empty_row(rows, row_widths)
+        cursor_row = rows.length - 1
+        cursor_col = 0
+      end
+
+      { rows: rows, cursor_row: cursor_row, cursor_col: cursor_col }
+    end
+
+    def previous_grapheme_boundary(text, index)
+      string = text.to_s
+      cursor = [[index.to_i, 0].max, string.length].min
+      return [cursor - 1, 0].max if string.ascii_only?
+
+      previous = 0
+      offset = 0
+      string.each_grapheme_cluster do |grapheme|
+        offset += grapheme.length
+        return previous if offset >= cursor
+
+        previous = offset
+      end
+      previous
+    end
+
+    def next_grapheme_boundary(text, index)
+      string = text.to_s
+      cursor = [[index.to_i, 0].max, string.length].min
+      return [cursor + 1, string.length].min if string.ascii_only?
+
+      offset = 0
+      string.each_grapheme_cluster do |grapheme|
+        offset += grapheme.length
+        return offset if offset > cursor
+      end
+      string.length
+    end
+
+    def wrap_ascii(text, line_width, cursor)
+      rows = text.scan(/.{1,#{line_width}}/m)
+      rows = [""] if rows.empty?
+      return { rows: rows, cursor_row: nil, cursor_col: nil } if cursor.nil?
+
+      cursor = [[cursor.to_i, 0].max, text.length].min
+      if cursor == text.length && text.length.positive? && (text.length % line_width).zero?
+        rows << ""
+      end
+      { rows: rows, cursor_row: cursor / line_width, cursor_col: cursor % line_width }
+    end
+    private_class_method :wrap_ascii
+
+    def append_empty_row(rows, row_widths)
+      rows << +""
+      row_widths << 0
+    end
+    private_class_method :append_empty_row
+  end
+end

data/lib/kward/text_matcher.rb

@@ -0,0 +1,18 @@
+# Namespace for the Kward CLI agent runtime.
+module Kward
+  # Allocation-conscious text matching helpers shared by interactive search UI.
+  module TextMatcher
+    module_function
+
+    def subsequence_pattern(query)
+      source = query.to_s.each_char.map { |character| Regexp.escape(character) }.join(".*")
+      Regexp.new(source, Regexp::MULTILINE)
+    end
+
+    def subsequence?(value, query, pattern = subsequence_pattern(query))
+      text = value.to_s
+      needle = query.to_s
+      needle.empty? || text.match?(pattern)
+    end
+  end
+end

data/lib/kward/tools/base.rb

@@ -1,3 +1,5 @@
+require_relative "workspace_targets"
+
 # Namespace for the Kward CLI agent runtime.
 module Kward
   # Model-callable tool wrappers and their argument schemas.
@@ -54,6 +56,22 @@ module Kward
         end
       end
 
+      # Configures the active workspace and any additional host-scoped targets.
+      def configure_workspace_targets(workspace, workspace_targets)
+        @workspace = workspace
+        @workspace_targets = workspace_targets || WorkspaceTargets.new(active: workspace)
+      end
+
+      # Adds the optional target selector when additional workspaces are available.
+      def targeted_properties(properties)
+        @workspace_targets.properties(properties)
+      end
+
+      # Resolves the requested role through the trusted target map.
+      def workspace_for(args)
+        @workspace_targets.workspace_for(args)
+      end
+
       # Reads a tool argument while accepting symbol or string keys from restored calls.
       def argument(args, key, default = nil)
         return args[key] if args.key?(key)

data/lib/kward/tools/context_for_task.rb

@@ -1,5 +1,5 @@
 require "pathname"
-require_relative "../workspace"
+require_relative "../workspace/workspace"
 require_relative "base"
 
 # Namespace for the Kward CLI agent runtime.
@@ -16,23 +16,32 @@ module Kward
       SKIP_DIRECTORIES = %w[.git .yardoc _yardoc node_modules vendor tmp log coverage dist build .bundle].freeze
 
       # Builds the tool schema and stores the execution dependency.
-      def initialize(workspace:)
-        @workspace = workspace
+      def initialize(workspace:, workspace_targets: nil)
+        configure_workspace_targets(workspace, workspace_targets)
         super(
           "context_for_task",
           "Build focused workspace context for a task from outlines and matching excerpts within a byte budget.",
-          properties: {
+          properties: targeted_properties(
             budget: { type: "integer", description: "Approximate byte budget for the returned context. Default 4000, maximum 20000." },
             paths: { type: "array", items: { type: "string" }, description: "Optional workspace-relative files or directories to focus." },
             task: { type: "string", description: "Task or question to gather context for." }
-          },
+          ),
           required: ["task"]
         )
       end
 
       # Executes focused context retrieval.
-      def call(args, _conversation, cancellation: nil)
+      def call(args, conversation, cancellation: nil)
         cancellation&.raise_if_cancelled!
+        selected_workspace = workspace_for(args)
+        unless selected_workspace.equal?(@workspace)
+          return self.class.new(workspace: selected_workspace).call(
+            @workspace_targets.without_target(args),
+            conversation,
+            cancellation: cancellation
+          )
+        end
+
         task = argument(args, :task, "").to_s.strip
         return "Error: task is required" if task.empty?
 

data/lib/kward/tools/edit_file.rb

@@ -7,12 +7,12 @@ module Kward
     # Tool wrapper for exact block replacement edits.
     class EditFile < Base
       # Builds the tool schema and stores the execution dependency.
-      def initialize(workspace:)
-        @workspace = workspace
+      def initialize(workspace:, workspace_targets: nil)
+        configure_workspace_targets(workspace, workspace_targets)
         super(
           "edit_file",
           "Edit a read workspace file by exact replacements. Each old_text must match once; edits must not overlap.",
-          properties: {
+          properties: targeted_properties(
             path: { type: "string", description: "Workspace-relative path." },
             edits: {
               type: "array",
@@ -27,7 +27,7 @@ module Kward
                 additionalProperties: false
               }
             }
-          },
+          ),
           required: ["path", "edits"]
         )
       end
@@ -37,8 +37,11 @@ module Kward
         path = argument(args, :path, "")
         edits = argument(args, :edits, [])
 
-        result = @workspace.edit_file(path, edits, read_paths: conversation.read_paths)
-        conversation.refresh_system_message! if agents_file_changed?(@workspace, path, result)
+        workspace = workspace_for(args)
+        result = workspace.edit_file(path, edits, read_paths: conversation.read_paths)
+        if workspace.equal?(@workspace) && agents_file_changed?(workspace, path, result)
+          conversation.refresh_system_message!
+        end
         result
       end
     end

data/lib/kward/tools/git_commit.rb

@@ -5,15 +5,18 @@ module Kward
   module Tools
     # Tool wrapper for the trusted host-side Git commit operation.
     class GitCommit < Base
-      def initialize(committer:)
+      def initialize(committer:, workspace_targets: nil)
         @committer = committer
+        @workspace_targets = workspace_targets
+        properties = {
+          message: { type: "string", description: "Commit message." },
+          paths: { type: "array", items: { type: "string" }, description: "Optional workspace-relative paths to include." }
+        }
+        properties = workspace_targets.properties(properties) if workspace_targets
         super(
           "git_commit",
-          "Stage and commit changes in the active worktree. Omit paths to include all current changes.",
-          properties: {
-            message: { type: "string", description: "Commit message." },
-            paths: { type: "array", items: { type: "string" }, description: "Optional workspace-relative paths to include." }
-          },
+          "Stage and commit changes in the selected worktree (active by default). Omit paths to include all current changes.",
+          properties: properties,
           required: ["message"]
         )
       end
@@ -27,7 +30,10 @@ module Kward
         return "Error: paths must contain strings" if paths && paths.any? { |path| !path.is_a?(String) }
 
         paths = nil if paths&.empty?
-        result = @committer.call(message: message, paths: paths)
+        target = @workspace_targets&.target_name(args)
+        options = { message: message, paths: paths }
+        options[:target] = target if target && target != WorkspaceTargets::ACTIVE
+        result = @committer.call(**options)
         output = result[:output].to_s.strip
         return "Git commit succeeded\n#{output}" if result[:success]