kward 0.83.0 → 0.85.0

data/lib/kward/{plugin_chat_runtime.rb → plugins/chat_runtime.rb}

@@ -1,11 +1,11 @@
 require "digest"
 require "securerandom"
 require "thread"
-require_relative "cancellation"
-require_relative "events"
-require_relative "plugin_registry"
-require_relative "tab_driver"
-require_relative "tools/tool_call"
+require_relative "../cancellation"
+require_relative "../events"
+require_relative "registry"
+require_relative "../tabs/driver"
+require_relative "../tools/tool_call"
 
 # Frontend-neutral runtime for trusted plugin-owned conversational drivers.
 module Kward
@@ -21,6 +21,7 @@ module Kward
       :id,
       :type,
       :driver,
+      :host,
       :queue,
       :worker,
       :running_turn_id,
@@ -55,6 +56,7 @@ module Kward
       @turns = {}
       @event_listeners = []
       @mutex = Mutex.new
+      @shutdown = false
     end
 
     def supported_types(surface: :rpc)
@@ -79,7 +81,7 @@ module Kward
       type = supported_types(surface: surface).find { |entry| entry.id == type_id.to_s }
       raise ArgumentError, "Unknown #{surface} plugin chat: #{type_id}" unless type
 
-      chat_for(type, scope_key: scope_key, descriptor: descriptor, workspace_root: workspace_root)
+      chat_for(type, surface: surface, scope_key: scope_key, descriptor: descriptor, workspace_root: workspace_root)
     end
 
     def chat(chat_id)
@@ -138,20 +140,31 @@ module Kward
     end
 
     def shutdown
-      chats = @mutex.synchronize { @chats.values.dup }
+      chats = @mutex.synchronize do
+        return nil if @shutdown
+
+        @shutdown = true
+        @chats.values.dup
+      end
+      @mutex.synchronize { @turns.values.dup }.each { |turn| turn.cancellation.cancel! }
       chats.each do |chat|
         chat.queue << WORKER_STOP if chat.worker&.alive?
         chat.worker&.join(0.2)
+        close_chat(chat)
       end
+      @plugin_registry&.shutdown! unless @plugin_registry_provider
       nil
     end
 
     # Converts normalized image attachment hashes into the input shape accepted
     # by plugin chat drivers. RPC and transport frontends can normalize their
     # own boundary formats before calling this helper.
-    def input_with_attachments(input, attachments)
+    def input_with_attachments(input, attachments, capabilities: PluginChatCapabilities.legacy)
       attachments = Array(attachments)
       return input.to_s if attachments.empty?
+      if capabilities.declared? && !capabilities.allows_attachment?(:image)
+        raise ArgumentError, "plugin chat does not allow image attachments"
+      end
 
       [{ type: "text", text: input.to_s }] + attachments.map do |attachment|
         {
@@ -166,30 +179,49 @@ module Kward
     private
 
     def plugin_registry
-      return @plugin_registry_provider.call if @plugin_registry_provider
-
-      @plugin_registry ||= PluginRegistry.load
+      registry = @plugin_registry_provider ? @plugin_registry_provider.call : (@plugin_registry ||= PluginRegistry.load)
+      registry.start!
+      registry
     end
 
-    def chat_for(type, scope_key:, descriptor:, workspace_root:)
+    def chat_for(type, surface:, scope_key:, descriptor:, workspace_root:)
+      surface = surface.to_sym
+      host_surface = type.rpc && type.transport ? :shared : surface
       scope_key = normalize_scope_key(scope_key)
+      scope_key = "global" if type.singleton == :global && type.capabilities.declared?
       chat_id = chat_id_for(type, scope_key)
       @mutex.synchronize do
         @chats[chat_id] ||= begin
           descriptor = {
             "kind" => "plugin",
-            "plugin_tab_type" => type.id,
-            "label" => type.title,
-            "scope_key" => scope_key
+            "label" => type.title
           }.merge(descriptor.transform_keys(&:to_s))
-          host = PluginTabHost.new(client: @client, workspace_root: workspace_root)
-          driver = type.handler.call(host, descriptor)
-          raise "Plugin chat #{type.id.inspect} did not return a tab driver." unless driver
+          descriptor["plugin_tab_type"] = type.id
+          descriptor["scope_key"] = scope_key
+          host = PluginTabHost.new(
+            client: @client,
+            workspace_root: workspace_root,
+            plugin_host: type.plugin_id && plugin_registry.plugin_for(type.plugin_id),
+            type_id: type.id,
+            surface: host_surface,
+            scope_key: scope_key,
+            capabilities: type.capabilities
+          )
+          begin
+            driver = type.handler.call(host, descriptor)
+            raise "Plugin chat #{type.id.inspect} did not return a tab driver." unless driver
+
+            type.capabilities.validate_driver!(driver)
+          rescue StandardError
+            host.shutdown
+            raise
+          end
 
           Chat.new(
             id: chat_id,
             type: type,
             driver: driver,
+            host: host,
             queue: Queue.new,
             scope_key: scope_key,
             descriptor: descriptor,
@@ -199,6 +231,18 @@ module Kward
       end
     end
 
+    def close_chat(chat)
+      if chat.driver.respond_to?(:close)
+        chat.driver.close
+      elsif chat.driver.respond_to?(:shutdown)
+        chat.driver.shutdown
+      end
+    rescue StandardError => e
+      ConfigFiles.emit_warning("Warning: Kward plugin chat cleanup error: #{e.message}")
+    ensure
+      chat.host.shutdown
+    end
+
     def normalize_scope_key(scope_key)
       value = scope_key.to_s
       value.empty? ? "default" : value

data/lib/kward/plugins/host.rb

@@ -0,0 +1,232 @@
+require "digest"
+require "json"
+require "logger"
+require "thread"
+require_relative "../config_files"
+require_relative "../deep_copy"
+require_relative "../private_file"
+require_relative "resources"
+
+# Namespace for the Kward CLI agent runtime.
+module Kward
+  # Private JSON-backed key/value storage scoped to one stable plugin ID.
+  class PluginStore
+    KEY_PATTERN = /\A[A-Za-z0-9][A-Za-z0-9:._-]*\z/.freeze
+
+    attr_reader :plugin_id
+
+    def initialize(plugin_id, root: ConfigFiles.config_dir)
+      @plugin_id = validate_key(plugin_id, "plugin id")
+      @path = File.join(File.expand_path(root), "plugin_state", @plugin_id, "state.json")
+      @mutex = Mutex.new
+      @values = load_state
+    end
+
+    def get(key)
+      key = validate_key(key, "storage key")
+      @mutex.synchronize { copy(@values[key]) }
+    end
+
+    def put(key, value)
+      key = validate_key(key, "storage key")
+      @mutex.synchronize do
+        @values[key] = copy(value)
+        persist
+      end
+      value
+    end
+
+    def delete(key)
+      key = validate_key(key, "storage key")
+      @mutex.synchronize do
+        present = @values.key?(key)
+        value = @values.delete(key)
+        persist if present
+        copy(value)
+      end
+    end
+
+    # Returns a view whose keys cannot overlap another plugin-owned scope.
+    def scoped(namespace)
+      PluginScopedStore.new(self, namespace)
+    end
+
+    private
+
+    def load_state
+      return {} unless File.file?(@path)
+
+      state = JSON.parse(File.read(@path))
+      values = state.fetch("values", {})
+      raise JSON::ParserError, "plugin state values must be a JSON object" unless values.is_a?(Hash)
+
+      values
+    rescue JSON::ParserError => e
+      raise "Invalid plugin state #{@path}: #{e.message}"
+    end
+
+    def persist
+      PrivateFile.write_json(@path, "values" => @values)
+    end
+
+    def validate_key(value, name)
+      value = value.to_s
+      raise ArgumentError, "#{name} is required" unless value.match?(KEY_PATTERN)
+
+      value
+    end
+
+    def copy(value)
+      return nil if value.nil?
+
+      DeepCopy.dup(value)
+    end
+  end
+
+  # Namespaced view over an identified plugin's durable storage.
+  class PluginScopedStore
+    attr_reader :namespace
+
+    def initialize(storage, namespace)
+      @storage = storage
+      @namespace = namespace.to_s
+      raise ArgumentError, "plugin storage namespace is required" if @namespace.empty?
+
+      @prefix = "scope.#{Digest::SHA256.hexdigest(@namespace)[0, 24]}"
+    end
+
+    def get(key)
+      @storage.get(scoped_key(key))
+    end
+
+    def put(key, value)
+      @storage.put(scoped_key(key), value)
+    end
+
+    def delete(key)
+      @storage.delete(scoped_key(key))
+    end
+
+    private
+
+    def scoped_key(key)
+      key = key.to_s
+      raise ArgumentError, "storage key is required" unless key.match?(PluginStore::KEY_PATTERN)
+
+      "#{@prefix}.#{key}"
+    end
+  end
+
+  # Shared immutable metadata and managed services for one identified plugin.
+  class PluginHost
+    ID_PATTERN = /\A[A-Za-z0-9][A-Za-z0-9._-]*\z/.freeze
+
+    class LogDevice
+      def write(message)
+        ConfigFiles.emit_warning(message.to_s.chomp)
+      end
+
+      def close
+        nil
+      end
+    end
+    private_constant :LogDevice
+
+    attr_reader :id, :version, :api_version, :source_path, :config, :storage, :logger
+
+    def initialize(id:, version:, api_version:, source_path: nil, config: nil, storage: nil, logger: nil, env: ENV, storage_root: ConfigFiles.config_dir, warning_sink: nil)
+      @id = validate_id(id).freeze
+      @version = validate_value(version, "plugin version").freeze
+      @api_version = validate_value(api_version, "plugin API version").freeze
+      @source_path = source_path&.to_s&.freeze
+      @config = freeze_config(config.nil? ? configured_values : config)
+      @storage = storage || PluginStore.new(@id, root: storage_root)
+      @logger = logger || default_logger
+      @env = env
+      @resources = PluginResources.new(name: "Kward plugin #{id}", warning_sink: warning_sink)
+    end
+
+    # Starts cooperative background work owned by this plugin. The block may
+    # accept a cancellation token and must stop cooperatively when cancelled.
+    #
+    # @return [PluginTask]
+    def background(name: nil, cancellation: nil, &block)
+      @resources.background(name: name, cancellation: cancellation, &block)
+    end
+
+    # Registers idempotent cleanup for a subscription or other plugin resource.
+    # The returned disposable may be invoked early; otherwise Kward invokes it
+    # during plugin reload or shutdown.
+    #
+    # @return [PluginDisposable]
+    def on_cleanup(resource = nil, &block)
+      @resources.on_cleanup(resource, &block)
+    end
+
+    alias manage on_cleanup
+
+    # Activates managed runtime services after plugin loading completes.
+    # @api private
+    def activate!
+      @resources.activate!
+      self
+    end
+
+    # Cancels background work and invokes registered cleanup callbacks.
+    # @api private
+    def shutdown(timeout: PluginResources::DEFAULT_SHUTDOWN_TIMEOUT)
+      @resources.shutdown(timeout: timeout)
+      self
+    end
+
+    # 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 = validate_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
+
+    # Returns public metadata suitable for diagnostics and capability reports.
+    def to_h
+      { id: id, version: version, api_version: api_version }.freeze
+    end
+
+    private
+
+    def configured_values
+      ConfigFiles.plugin_config(@id)
+    end
+
+    def freeze_config(value)
+      raise ArgumentError, "Kward plugin config for #{@id} must be an object" unless value.is_a?(Hash)
+
+      DeepCopy.freeze(DeepCopy.dup(value))
+    end
+
+    def validate_id(value)
+      value = value.to_s
+      raise ArgumentError, "plugin id is invalid: #{value}" unless value.match?(ID_PATTERN)
+
+      value
+    end
+
+    def validate_value(value, name)
+      value = value.to_s
+      raise ArgumentError, "#{name} is required" if value.empty?
+
+      value
+    end
+
+    def default_secret_env_name(key)
+      parts = [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 #{id}" }
+    end
+  end
+end