kward 0.79.0 → 0.80.0

data/lib/kward/plugin_chat_runtime.rb

@@ -0,0 +1,374 @@
+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"
+
+# Frontend-neutral runtime for trusted plugin-owned conversational drivers.
+module Kward
+  # Coordinates plugin chat drivers without depending on RPC or the terminal UI.
+  # Frontends use this runtime for queuing, cancellation, event replay, and
+  # transcript access while the plugin remains responsible for its own storage,
+  # model settings, and domain behavior.
+  class PluginChatRuntime
+    EVENT_LIMIT = 1_000
+    WORKER_STOP = Object.new.freeze
+
+    Chat = Struct.new(
+      :id,
+      :type,
+      :driver,
+      :queue,
+      :worker,
+      :running_turn_id,
+      :scope_key,
+      :descriptor,
+      :workspace_root,
+      keyword_init: true
+    )
+    Turn = Struct.new(
+      :id,
+      :chat_id,
+      :input,
+      :display_input,
+      :context,
+      :status,
+      :cancellation,
+      :created_at,
+      :started_at,
+      :finished_at,
+      :events,
+      :next_sequence,
+      :error,
+      :mutex,
+      keyword_init: true
+    )
+
+    def initialize(client:, plugin_registry_provider: nil, message_normalizer: nil)
+      @client = client
+      @plugin_registry_provider = plugin_registry_provider
+      @message_normalizer = message_normalizer
+      @chats = {}
+      @turns = {}
+      @event_listeners = []
+      @mutex = Mutex.new
+    end
+
+    def supported_types(surface: :rpc)
+      case surface.to_sym
+      when :rpc
+        plugin_registry.tab_types.select(&:rpc)
+      when :transport
+        plugin_registry.transport_tab_types
+      else
+        raise ArgumentError, "Unknown plugin chat surface: #{surface}"
+      end
+    end
+
+    def subscribe_events(&block)
+      raise ArgumentError, "plugin chat event subscription requires a block" unless block
+
+      @mutex.synchronize { @event_listeners << block }
+      block
+    end
+
+    def open(type_id:, surface: :rpc, scope_key: nil, descriptor: {}, workspace_root: Dir.pwd)
+      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)
+    end
+
+    def chat(chat_id)
+      @mutex.synchronize { @chats[chat_id.to_s] }
+    end
+
+    def start_turn(chat_id:, input:, display_input: nil, context: nil)
+      chat = fetch_chat(chat_id)
+      turn = Turn.new(
+        id: SecureRandom.uuid,
+        chat_id: chat.id,
+        input: input,
+        display_input: display_input.nil? ? input.to_s : display_input.to_s,
+        context: context || {},
+        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
+    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
+    end
+
+    def turn_status(turn_id:)
+      fetch_turn(turn_id)
+    end
+
+    def turn_events(turn_id:, after_sequence: 0)
+      turn = fetch_turn(turn_id)
+      turn.mutex.synchronize do
+        turn.events.select { |event| event[:sequence].to_i > after_sequence.to_i }
+      end
+    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
+    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
+      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)
+      attachments = Array(attachments)
+      return input.to_s if attachments.empty?
+
+      [{ type: "text", text: input.to_s }] + attachments.map do |attachment|
+        {
+          type: "image",
+          media_type: attachment.fetch(:mimeType) { attachment.fetch("mimeType") },
+          data: attachment.fetch(:data) { attachment.fetch("data") },
+          alt: attachment[:alt] || attachment["alt"]
+        }.compact
+      end
+    end
+
+    private
+
+    def plugin_registry
+      return @plugin_registry_provider.call if @plugin_registry_provider
+
+      @plugin_registry ||= PluginRegistry.load
+    end
+
+    def chat_for(type, scope_key:, descriptor:, workspace_root:)
+      scope_key = normalize_scope_key(scope_key)
+      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
+          }.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
+
+          Chat.new(
+            id: chat_id,
+            type: type,
+            driver: driver,
+            queue: Queue.new,
+            scope_key: scope_key,
+            descriptor: descriptor,
+            workspace_root: workspace_root
+          )
+        end
+      end
+    end
+
+    def normalize_scope_key(scope_key)
+      value = scope_key.to_s
+      value.empty? ? "default" : value
+    end
+
+    def chat_id_for(type, scope_key)
+      return type.id if type.singleton == :global
+      return type.id if scope_key == "default"
+
+      "#{type.id}:#{Digest::SHA256.hexdigest(scope_key)[0, 16]}"
+    end
+
+    def fetch_chat(chat_id)
+      chat(chat_id) || raise(ArgumentError, "Unknown plugin chat: #{chat_id}")
+    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" })
+      submit_options = {
+        display_input: turn.display_input,
+        cancellation: turn.cancellation
+      }
+      if !turn.context.empty? && accepts_context?(chat.driver)
+        submit_options[:context] = turn.context
+      end
+      chat.driver.submit(turn.input, **submit_options) 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 accepts_context?(driver)
+      driver.method(:submit).parameters.any? do |kind, name|
+        kind == :keyrest || ((kind == :key || kind == :keyreq) && name == :context)
+      end
+    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: normalized_assistant_message(event.message) }]
+      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: chat.workspace_root)
+      plugin_registry.notify_transcript_event(event, context)
+    end
+
+    def normalized_assistant_message(message)
+      @message_normalizer ? @message_normalizer.call(message) : message
+    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)
+      listeners = @mutex.synchronize { @event_listeners.dup }
+      listeners.each do |listener|
+        listener.call(event)
+      rescue StandardError
+        nil
+      end
+    end
+
+    def terminal?(turn)
+      %w[completed failed canceled].include?(turn.status)
+    end
+  end
+end

data/lib/kward/plugin_registry.rb

@@ -1,6 +1,7 @@
 require_relative "config_files"
 require_relative "deep_copy"
 require_relative "hooks"
+require_relative "transport"
 
 # Namespace for the Kward CLI agent runtime.
 module Kward
@@ -36,7 +37,11 @@ module Kward
 
     # Registered plugin-owned tab runtime. Its factory receives a
     # `PluginTabHost` and its persisted descriptor, then returns a driver.
-    TabType = Struct.new(:id, :name, :title, :singleton, :rpc, :transcript_events, :path, :handler, keyword_init: true)
+    TabType = Struct.new(:id, :name, :title, :singleton, :rpc, :transport, :local, :transcript_events, :path, :handler, keyword_init: true)
+
+    # Registered external transport. The factory receives a transport host and
+    # configuration when the transport is started, not while plugins load.
+    TransportType = Struct.new(:id, :name, :capabilities, :execution_profile, :path, :handler, keyword_init: true)
 
     # Read-only event passed to plugin transcript observers.
     TranscriptEvent = Struct.new(:type, :payload, keyword_init: true) do
@@ -269,21 +274,38 @@ module Kward
         @registry.register_interactive_command(name, rows: rows, fps: fps, description: description, argument_hint: argument_hint, path: @path, &block)
       end
 
-      # Registers a plugin-owned tab type for the interactive CLI. `id` is a
-      # durable identifier used in persisted tab layouts and must not change.
+      # Registers a plugin-owned chat type. `id` is a durable identifier used
+      # in persisted tab layouts and transport chat handles and must not change.
       # The factory receives a `PluginTabHost` and a descriptor hash.
       #
       # @param name [String] command name used by `/tab open <name>`
       # @param id [String] stable persisted tab type identifier
       # @param title [String] default tab label
       # @param singleton [Symbol] `:global` for one shared plugin runtime
+      # @param rpc [Boolean] expose this chat through trusted local RPC
+      # @param transport [Boolean] allow external transport adapters to target this chat
+      # @param local [Boolean] expose this chat as an interactive local tab
       # @param transcript_events [Boolean] allow global transcript observers to receive this tab's events
       # @yieldparam host [PluginTabHost] supported host dependencies
       # @yieldparam descriptor [Hash] persisted tab descriptor
       # @return [void]
       # @api public
-      def tab_type(name, id:, title: nil, singleton: nil, rpc: false, transcript_events: false, &block)
-        @registry.register_tab_type(name, id: id, title: title, singleton: singleton, rpc: rpc, transcript_events: transcript_events, path: @path, &block)
+      def tab_type(name, id:, title: nil, singleton: nil, rpc: false, transport: false, local: true, transcript_events: false, &block)
+        @registry.register_tab_type(name, id: id, title: title, singleton: singleton, rpc: rpc, transport: transport, local: local, transcript_events: transcript_events, path: @path, &block)
+      end
+
+      # Registers an external messaging or event transport. The factory is
+      # called when the transport runtime starts.
+      #
+      # @param name [String] human-readable transport name
+      # @param id [String] stable transport identifier
+      # @param capabilities [Hash, Transport::Capabilities] supported features
+      # @yieldparam host [Object] transport host
+      # @yieldparam config [Object] transport configuration
+      # @return [void]
+      # @api public
+      def transport(name, id:, capabilities: nil, execution_profile: nil, &block)
+        @registry.register_transport(name, id: id, capabilities: capabilities, execution_profile: execution_profile, path: @path, &block)
       end
     end
 
@@ -305,6 +327,8 @@ module Kward
       @interactive_commands = {}
       @tab_types = {}
       @tab_types_by_id = {}
+      @transports = {}
+      @transports_by_id = {}
       @footer = nil
       @footer_path = nil
       @transcript_event_handlers = []
@@ -347,6 +371,22 @@ module Kward
       @tab_types_by_id[id.to_s]
     end
 
+    def transport_tab_types
+      @tab_types.values.select(&:transport)
+    end
+
+    def transports
+      @transports.values
+    end
+
+    def transport_for(name)
+      @transports[name.to_s]
+    end
+
+    def transport_for_id(id)
+      @transports_by_id[id.to_s]
+    end
+
     def footer_renderer
       @footer
     end
@@ -464,7 +504,7 @@ module Kward
       )
     end
 
-    def register_tab_type(name, id:, title: nil, singleton: nil, rpc: false, transcript_events: false, path: nil, &handler)
+    def register_tab_type(name, id:, title: nil, singleton: nil, rpc: false, transport: false, local: true, transcript_events: false, path: nil, &handler)
       name = name.to_s
       id = id.to_s
       raise "Plugin tab type name is invalid: #{name}" unless name.match?(COMMAND_NAME_PATTERN)
@@ -476,11 +516,30 @@ module Kward
         return nil
       end
 
-      tab_type = TabType.new(id: id, name: name, title: title.to_s.empty? ? name.capitalize : title.to_s, singleton: singleton&.to_sym, rpc: rpc == true, transcript_events: transcript_events == true, path: path, handler: handler)
+      tab_type = TabType.new(id: id, name: name, title: title.to_s.empty? ? name.capitalize : title.to_s, singleton: singleton&.to_sym, rpc: rpc == true, transport: transport == true, local: local == true, transcript_events: transcript_events == true, path: path, handler: handler)
       @tab_types[name] = tab_type
       @tab_types_by_id[id] = tab_type
     end
 
+    def register_transport(name, id:, capabilities: nil, execution_profile: nil, path: nil, &handler)
+      name = name.to_s
+      id = id.to_s
+      raise "Plugin transport name is invalid: #{name}" unless name.match?(COMMAND_NAME_PATTERN)
+      raise "Plugin transport id is required" if id.empty?
+      raise "Plugin transport #{name} requires a handler" unless handler
+
+      if @transports.key?(name) || @transports_by_id.key?(id)
+        warn "Warning: skipping duplicate Kward plugin transport #{id}: #{path}"
+        return nil
+      end
+
+      capabilities = normalize_transport_capabilities(capabilities)
+      execution_profile = normalize_execution_profile(execution_profile)
+      transport = TransportType.new(id: id, name: name, capabilities: capabilities, execution_profile: execution_profile, path: path, handler: handler)
+      @transports[name] = transport
+      @transports_by_id[id] = transport
+    end
+
     def register_footer(path: nil, &renderer)
       raise "Plugin footer requires a renderer" unless renderer
 
@@ -520,6 +579,20 @@ module Kward
 
     private
 
+    def normalize_execution_profile(profile)
+      return nil if profile.nil?
+      return profile if profile.is_a?(Transport::ExecutionProfile)
+      raise ArgumentError, "Plugin transport execution_profile must be a Transport::ExecutionProfile"
+    end
+
+    def normalize_transport_capabilities(capabilities)
+      return Transport.capabilities if capabilities.nil?
+      return capabilities if capabilities.is_a?(Transport::Capabilities)
+      raise ArgumentError, "Plugin transport capabilities must be a hash or Transport::Capabilities" unless capabilities.is_a?(Hash)
+
+      Transport.capabilities(**capabilities.transform_keys(&:to_sym))
+    end
+
     def transcript_event_for(event)
       case event.class.name
       when "Kward::Events::ReasoningDelta"

data/lib/kward/private_file.rb

@@ -1,5 +1,6 @@
 require "fileutils"
 require "json"
+require "tempfile"
 
 # Namespace for the Kward CLI agent runtime.
 module Kward
@@ -9,12 +10,17 @@ module Kward
 
     def write_json(path, data)
       path = File.expand_path(path)
-      FileUtils.mkdir_p(File.dirname(path), mode: 0o700)
-      File.open(path, File::WRONLY | File::CREAT | File::TRUNC, 0o600) do |file|
+      directory = File.dirname(path)
+      FileUtils.mkdir_p(directory, mode: 0o700)
+
+      Tempfile.create([".#{File.basename(path)}.", ".tmp"], directory, mode: 0o600) do |file|
         file.write(JSON.pretty_generate(data))
         file.write("\n")
+        file.flush
+        file.fsync
+        file.close
+        File.rename(file.path, path)
       end
-      File.chmod(0o600, path)
     end
   end
 end

data/lib/kward/prompt_interface/approval_prompt.rb

@@ -37,6 +37,7 @@ module Kward
       def tool_approval_title(tool_name)
         case tool_name.to_s
         when "run_shell_command" then "Shell command"
+        when "git_commit" then "Git commit"
         when "write_file" then "Write file"
         when "edit_file" then "Edit file"
         when "fetch_content", "fetch_raw" then "Network request"
@@ -48,6 +49,7 @@ module Kward
       def tool_approval_details(tool_name, args)
         action = case tool_name.to_s
                  when "run_shell_command" then "run this shell command"
+                 when "git_commit" then "create this Git commit"
                  when "write_file" then "write this file"
                  when "edit_file" then "edit this file"
                  when "read_file", "read_skill" then "read these resources"

data/lib/kward/prompt_interface/composer_renderer.rb

@@ -230,11 +230,7 @@ module Kward
       end
 
       def footer_text
-        return "" unless @footer
-
-        @footer.call.to_s.gsub(/\s+/, " ").strip
-      rescue StandardError
-        ""
+        cached_footer_text
       end
 
       def attachment_badge_rows(content_width)

data/lib/kward/prompt_interface/editor/auto_indent.rb

@@ -323,6 +323,8 @@ module Kward
           code.match?(/:\s*(?:[#].*)?\z/)
         when :html
           editor_html_line_opens_indent?(code)
+        when :erb
+          editor_erb_line_opens_indent?(code)
         when *C_LIKE_INDENT_LANGUAGES
           false
         else
@@ -364,6 +366,46 @@ module Kward
         true
       end
 
+      def editor_erb_line_opens_indent?(code)
+        segments, = editor_erb_segments(code.to_s, :template)
+        segments.any? do |kind, text|
+          case kind
+          when :ruby
+            editor_ruby_line_opens_indent?(text.strip)
+          when :template
+            editor_html_line_opens_indent?(text.strip)
+          else
+            false
+          end
+        end
+      end
+
+      def editor_erb_line_closer?(code)
+        segments, = editor_erb_segments(code.to_s, :template)
+        segments.any? do |kind, text|
+          case kind
+          when :ruby
+            text.strip.match?(/\Aend\z/)
+          when :template
+            text.strip.match?(/\A<\/[A-Za-z][\w:-]*>\z/)
+          else
+            false
+          end
+        end
+      end
+
+      def editor_matching_erb_indent(line_index = nil)
+        stack = []
+        editor_previous_code_lines(line_index).each do |line|
+          code = line[:code].strip
+          next if code.empty?
+
+          stack.pop if editor_erb_line_closer?(code)
+          stack << line[:indent] if editor_erb_line_opens_indent?(code)
+        end
+        stack.last || ""
+      end
+
       def editor_closing_punctuation?(text)
         PUNCTUATION_PAIRS.key?(text) && PUNCTUATION_INDENT_LANGUAGES.include?(editor_syntax_language)
       end
@@ -424,6 +466,8 @@ module Kward
           code.match?(/\A[ \t]*(?:#{Regexp.union(SHELL_DEDENT_KEYWORDS)})\z/)
         when :html
           code.match?(/\A[ \t]*<\/[A-Za-z][\w:-]*>\z/)
+        when :erb
+          editor_erb_line_closer?(code)
         else
           false
         end
@@ -439,6 +483,8 @@ module Kward
           editor_matching_keyword_indent(nil, SHELL_DEDENT_KEYWORDS, line_index)
         when :html
           editor_matching_html_indent(line_index)
+        when :erb
+          editor_matching_erb_indent(line_index)
         end
       end