kward 0.84.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/{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/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]
 

data/lib/kward/tools/list_directory.rb

@@ -7,19 +7,19 @@ module Kward
     # Tool wrapper for listing workspace directory entries.
     class ListDirectory < 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(
           "list_directory",
           "List workspace directory entries.",
-          properties: { path: { type: "string", description: "Workspace-relative directory." } },
+          properties: targeted_properties(path: { type: "string", description: "Workspace-relative directory." }),
           required: ["path"]
         )
       end
 
       # Executes the tool and returns model-facing output text.
       def call(args, _conversation, cancellation: nil)
-        @workspace.list_directory(argument(args, :path, "."))
+        workspace_for(args).list_directory(argument(args, :path, "."))
       end
     end
   end

data/lib/kward/tools/plugin_tool.rb

@@ -0,0 +1,41 @@
+require_relative "base"
+
+# Namespace for the Kward CLI agent runtime.
+module Kward
+  # Model-callable tool wrappers and their argument schemas.
+  module Tools
+    # Adapts a trusted plugin tool registration to the normal tool interface.
+    class PluginTool < Base
+      attr_reader :plugin_path
+
+      def initialize(registration:, context_factory:)
+        @description = registration.description
+        @parameters = registration.schema
+        @plugin_path = registration.path
+        @handler = registration.handler
+        @context_factory = context_factory
+        super(registration.name, registration.description)
+      end
+
+      # Returns the strict JSON schema declared by the plugin.
+      def schema
+        {
+          type: "function",
+          function: {
+            name: name,
+            description: @description,
+            parameters: @parameters
+          }
+        }
+      end
+
+      # Executes trusted plugin code with parsed model arguments and scoped context.
+      def call(args, conversation, cancellation: nil)
+        context = @context_factory.call(conversation, cancellation)
+        result = @handler.call(args, context)
+        cancellation&.raise_if_cancelled!
+        result.to_s
+      end
+    end
+  end
+end

data/lib/kward/tools/prepare_shell_command.rb

@@ -1,5 +1,5 @@
 require_relative "base"
-require_relative "../shell_prompt_session"
+require_relative "../shell/prompt_session"
 
 # Namespace for the Kward agent runtime.
 module Kward

data/lib/kward/tools/read_file.rb

@@ -7,18 +7,18 @@ module Kward
     # Tool wrapper for bounded workspace file reads.
     class ReadFile < 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(
           "read_file",
           "Read a workspace text file. Output is capped; use offset/limit or mode to control context budget.",
-          properties: {
+          properties: targeted_properties(
             path: { type: "string", description: "Workspace-relative path." },
             limit: { type: "integer", description: "Maximum lines to return." },
             max_bytes: { type: "integer", description: "Optional byte budget for this read, capped by Kward's workspace read limit." },
             mode: { type: "string", enum: %w[preview outline range full], description: "Context mode. preview returns a short slice, outline returns source declarations, range reads offset/limit, full reads until Kward's cap." },
             offset: { type: "integer", description: "1-indexed start line." }
-          },
+          ),
           required: ["path"]
         )
       end
@@ -30,8 +30,9 @@ module Kward
         limit = argument(args, :limit)
         mode = argument(args, :mode)
         max_bytes = argument(args, :max_bytes)
-        content = @workspace.read_file(path, offset: offset, limit: limit, mode: mode, max_bytes: max_bytes)
-        conversation.mark_read(@workspace.resolved_path(path)) unless content.start_with?("Error:")
+        workspace = workspace_for(args)
+        content = workspace.read_file(path, offset: offset, limit: limit, mode: mode, max_bytes: max_bytes)
+        conversation.mark_read(workspace.resolved_path(path)) unless content.start_with?("Error:")
         content
       end
     end