kward 0.79.0 → 0.80.0

data/lib/kward/transport/manager.rb

@@ -0,0 +1,179 @@
+require "thread"
+require "time"
+require_relative "host"
+
+module Kward
+  module Transport
+    # Starts and supervises registered transport adapters.
+    class Manager
+      Entry = Struct.new(:type, :host, :adapter, :state, :error, :started_at, :stopped_at, keyword_init: true)
+
+      def initialize(registry:, gateway: nil, plugin_chat_gateway: nil, config_root: nil, config_provider: nil, policy: nil, logger: nil)
+        @registry = registry
+        @gateway = gateway
+        @plugin_chat_gateway = plugin_chat_gateway
+        @config_root = config_root
+        @config_provider = config_provider
+        @policy = policy
+        @logger = logger || Logger.new($stderr)
+        @entries = {}
+        @mutex = Mutex.new
+      end
+
+      def list
+        @registry.transports.map { |type| descriptor(type) }
+      end
+
+      def status(name_or_id = nil)
+        return status_for(resolve_type(name_or_id)) if name_or_id
+
+        list.map { |type| status_for(type) }
+      end
+
+      def start(name_or_id, config: nil, workspace_root: nil)
+        type = resolve_type(name_or_id)
+        @mutex.synchronize do
+          raise "Transport #{type.id} is already running" if running_entry?(type.id)
+        end
+
+        config ||= @config_provider&.call(type.id) || {}
+        config = config.merge("workspace" => workspace_root.to_s) if workspace_root
+        gateway = @gateway.respond_to?(:call) ? @gateway.call(type.id) : @gateway
+        plugin_chat_gateway = @plugin_chat_gateway.respond_to?(:call) ? @plugin_chat_gateway.call(type.id) : @plugin_chat_gateway
+        host = Host.new(
+          transport_id: type.id,
+          gateway: gateway,
+          plugin_chat_gateway: plugin_chat_gateway,
+          config: config,
+          storage: @config_root && Store.new(type.id, root: @config_root),
+          policy: @policy,
+          logger: @logger,
+          execution_profile: type.execution_profile
+        )
+        adapter = type.handler.call(host, host.config)
+        unless adapter.respond_to?(:start) && adapter.respond_to?(:stop)
+          raise "Transport #{type.id} must implement start and stop"
+        end
+
+        entry = Entry.new(type: type, host: host, adapter: adapter, state: "starting")
+        @mutex.synchronize { @entries[type.id] = entry }
+        begin
+          adapter.start
+          @mutex.synchronize do
+            entry.state = "running"
+            entry.started_at = Time.now.utc
+            entry.error = nil
+          end
+          adapter
+        rescue StandardError => e
+          @mutex.synchronize do
+            entry.state = "failed"
+            entry.error = e.message
+            entry.stopped_at = Time.now.utc
+          end
+          log_error(type, e)
+          raise
+        end
+      end
+
+      def stop(name_or_id)
+        type = resolve_type(name_or_id)
+        entry = @mutex.synchronize { @entries[type.id] }
+        return false unless entry
+
+        begin
+          entry.adapter.stop
+        ensure
+          entry.host.shutdown
+          @mutex.synchronize do
+            entry.state = "stopped"
+            entry.stopped_at = Time.now.utc
+          end
+        end
+        true
+      end
+
+      def restart(name_or_id, config: nil)
+        stop(name_or_id)
+        start(name_or_id, config: config)
+      end
+
+      def reload(registry)
+        shutdown
+        @mutex.synchronize { @registry = registry }
+        list
+      end
+
+      def shutdown
+        entries = @mutex.synchronize { @entries.values.dup }
+        entries.each { |entry| stop(entry.type.id) if entry.state == "running" || entry.state == "starting" }
+        nil
+      end
+
+      private
+
+      def resolve_type(name_or_id)
+        type = @registry.transport_for(name_or_id) || @registry.transport_for_id(name_or_id)
+        raise ArgumentError, "Unknown transport: #{name_or_id}" unless type
+
+        type
+      end
+
+      def running_entry?(id)
+        entry = @entries[id]
+        entry && %w[starting running].include?(entry.state)
+      end
+
+      def descriptor(type)
+        {
+          id: type.id,
+          name: type.name,
+          capabilities: type.capabilities.to_h,
+          execution_profile: profile_payload(type.execution_profile),
+          path: type.path
+        }
+      end
+
+      def status_for(type)
+        entry = @mutex.synchronize { @entries[type.id] }
+        descriptor(type).merge(
+          state: entry&.state || "stopped",
+          error: entry&.error,
+          health: health_for(entry),
+          started_at: entry&.started_at,
+          stopped_at: entry&.stopped_at
+        )
+      end
+
+      def profile_payload(profile)
+        return nil unless profile
+
+        {
+          id: profile.id,
+          tool_mode: profile.tool_mode,
+          allowed_tools: profile.allowed_tools,
+          disabled_tools: profile.disabled_tools,
+          plugin_commands: profile.plugin_commands,
+          approval_mode: profile.approval_mode,
+          memory: profile.memory,
+          attachments: profile.attachments,
+          workspace_mode: profile.workspace_mode
+        }
+      end
+
+      def health_for(entry)
+        return nil unless entry&.adapter&.respond_to?(:health)
+
+        entry.adapter.health
+      rescue StandardError => e
+        { state: "error", message: e.message }
+      end
+
+      def log_error(type, error)
+        @logger.error("Transport #{type.id} failed to start: #{error.class}: #{error.message}")
+      rescue StandardError
+        nil
+      end
+    end
+  end
+end

data/lib/kward/transport/plugin_chat_gateway.rb

@@ -0,0 +1,186 @@
+require "base64"
+require "thread"
+require_relative "../plugin_chat_runtime"
+
+module Kward
+  module Transport
+    # Adapts the shared plugin-chat runtime to the transport host contract.
+    class PluginChatGateway
+      POLL_INTERVAL = 0.05
+      TERMINAL_STATUSES = %w[completed canceled failed].freeze
+      IMAGE_MIME_TYPES = %w[image/png image/jpeg image/gif image/webp].freeze
+
+      def initialize(runtime:, transport_id:, poll_interval: POLL_INTERVAL)
+        @runtime = runtime
+        @transport_id = transport_id.to_s
+        @poll_interval = poll_interval
+        @subscriptions = []
+        @mutex = Mutex.new
+      end
+
+      def resolve_transport_chat(transport_id:, type_id:, conversation:, actor:, scope_key:, descriptor: {}, workspace_root: nil)
+        validate_transport_id!(transport_id)
+        validate_conversation!(conversation)
+        validate_actor!(actor)
+        chat = @runtime.open(
+          type_id: type_id,
+          surface: :transport,
+          scope_key: scope_key,
+          descriptor: transport_descriptor(conversation, actor, descriptor),
+          workspace_root: workspace_root || Dir.pwd
+        )
+        Host::PluginChatHandle.new(
+          id: chat.id,
+          type_id: chat.type.id,
+          scope_key: chat.scope_key,
+          name: chat.type.title
+        )
+      end
+
+      def start_transport_plugin_chat_turn(chat_id:, actor:, input:, attachments: [], streaming_behavior: nil, execution_profile: nil)
+        if execution_profile && !execution_profile.attachments && !Array(attachments).empty?
+          raise ArgumentError, "transport execution profile does not allow attachments"
+        end
+        unless streaming_behavior.nil? || %i[aggregate none].include?(streaming_behavior.to_sym)
+          raise ArgumentError, "plugin chat turns do not support #{streaming_behavior} streaming"
+        end
+
+        turn = @runtime.start_turn(
+          chat_id: chat_id,
+          input: @runtime.input_with_attachments(input, normalize_attachments(attachments)),
+          display_input: input.to_s,
+          context: { actor: actor }
+        )
+        Host::PluginChatTurnHandle.new(id: turn.id, chat_id: turn.chat_id)
+      end
+
+      def transport_plugin_chat_transcript(chat_id:)
+        chat = fetch_chat(chat_id)
+        { messages: chat.driver.messages }
+      end
+
+      def transport_plugin_chat_turn_events(turn_id:, after: nil)
+        @runtime.turn_events(turn_id: turn_id, after_sequence: after.to_i).map do |event|
+          Transport.turn_event(
+            type: event.fetch(:type),
+            session_id: event.fetch(:chatId),
+            turn_id: event.fetch(:turnId),
+            sequence: event.fetch(:sequence),
+            payload: event.fetch(:payload, {})
+          )
+        end
+      end
+
+      def transport_plugin_chat_turn_status(turn_id:)
+        turn_payload(@runtime.turn_status(turn_id: turn_id))
+      end
+
+      def cancel_transport_plugin_chat_turn(turn_id:)
+        @runtime.cancel_turn(turn_id: turn_id)
+        nil
+      end
+
+      def subscribe_transport_plugin_chat_turn(turn_id:, after: nil)
+        cursor = after.to_i
+        thread = Thread.new do
+          loop do
+            events = transport_plugin_chat_turn_events(turn_id: turn_id, after: cursor)
+            events.each do |event|
+              cursor = event.sequence
+              yield event
+            end
+            status = transport_plugin_chat_turn_status(turn_id: turn_id)
+            break if TERMINAL_STATUSES.include?(status[:status].to_s)
+
+            sleep @poll_interval
+          end
+        rescue StandardError
+          nil
+        end
+        @mutex.synchronize { @subscriptions << thread }
+        thread
+      end
+
+      def shutdown
+        subscriptions = @mutex.synchronize do
+          current = @subscriptions
+          @subscriptions = []
+          current
+        end
+        subscriptions.each(&:kill)
+        subscriptions.each(&:join)
+        nil
+      end
+
+      private
+
+      def validate_transport_id!(transport_id)
+        return if transport_id.to_s == @transport_id
+
+        raise ArgumentError, "transport id does not match plugin chat gateway"
+      end
+
+      def validate_conversation!(conversation)
+        unless conversation.is_a?(ConversationKey)
+          raise ArgumentError, "conversation must be a Transport::ConversationKey"
+        end
+        return if conversation.transport_id == @transport_id
+
+        raise ArgumentError, "conversation transport does not match plugin chat gateway"
+      end
+
+      def validate_actor!(actor)
+        return if actor.is_a?(Actor)
+
+        raise ArgumentError, "actor must be a Transport::Actor"
+      end
+
+      def fetch_chat(chat_id)
+        @runtime.chat(chat_id) || raise(ArgumentError, "Unknown plugin chat: #{chat_id}")
+      end
+
+      def transport_descriptor(conversation, actor, descriptor)
+        {
+          "kind" => "transport",
+          "transport_id" => @transport_id,
+          "conversation" => conversation.to_h,
+          "actor" => actor.to_h
+        }.merge(descriptor.transform_keys(&:to_s))
+      end
+
+      def normalize_attachments(attachments)
+        Array(attachments).map do |attachment|
+          unless attachment.is_a?(Attachment)
+            raise ArgumentError, "transport attachment must be a Transport::Attachment"
+          end
+          if attachment.url
+            raise ArgumentError, "plugin chat attachment URLs are not supported"
+          end
+          unless IMAGE_MIME_TYPES.include?(attachment.mime_type.to_s.downcase)
+            raise ArgumentError, "unsupported plugin chat attachment MIME type: #{attachment.mime_type}"
+          end
+
+          {
+            mimeType: attachment.mime_type,
+            data: Base64.strict_encode64(attachment.data),
+            alt: attachment.name
+          }.compact
+        end
+      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/transport/runtime.rb

@@ -0,0 +1,41 @@
+require "stringio"
+require_relative "../config_files"
+require_relative "../rpc/server"
+require_relative "gateway"
+require_relative "manager"
+require_relative "plugin_chat_gateway"
+
+module Kward
+  module Transport
+    # Builds the Kward runtime needed by foreground transport processes.
+    class Runtime
+      attr_reader :manager
+
+      def initialize(client:)
+        @server = RPC::Server.new(
+          input: StringIO.new,
+          output: StringIO.new,
+          error_output: $stderr,
+          client: client
+        )
+        @manager = Manager.new(
+          registry: @server.session_manager.plugin_registry,
+          gateway: lambda { |transport_id|
+            Gateway.new(session_manager: @server.session_manager, transport_id: transport_id)
+          },
+          plugin_chat_gateway: lambda { |transport_id|
+            PluginChatGateway.new(runtime: @server.plugin_chat_manager.runtime, transport_id: transport_id)
+          },
+          config_root: ConfigFiles.config_dir,
+          config_provider: ->(transport_id) { ConfigFiles.transport_config(transport_id) }
+        )
+      end
+
+      def shutdown
+        @manager.shutdown
+        @server.shutdown
+        nil
+      end
+    end
+  end
+end

data/lib/kward/transport/store.rb

@@ -0,0 +1,101 @@
+require "fileutils"
+require "json"
+require "thread"
+require "time"
+require_relative "../config_files"
+require_relative "../deep_copy"
+require_relative "../private_file"
+
+module Kward
+  module Transport
+    # Small private JSON store scoped to one transport plugin.
+    class Store
+      KEY_PATTERN = /\A[A-Za-z0-9][A-Za-z0-9:._-]*\z/.freeze
+      DEFAULT_MAX_PROCESSED_KEYS = 10_000
+
+      attr_reader :transport_id
+
+      def initialize(transport_id, root: ConfigFiles.config_dir)
+        @transport_id = validate_key(transport_id, "transport id")
+        @path = File.join(File.expand_path(root), "transports", @transport_id, "state.json")
+        @mutex = Mutex.new
+        @values, @processed = 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
+
+      # Claims an external event key. Returns false when the key was already
+      # claimed, making duplicate webhook and polling deliveries harmless.
+      def claim(key, max_keys: DEFAULT_MAX_PROCESSED_KEYS)
+        key = validate_key(key, "idempotency key")
+        max_keys = Integer(max_keys)
+        raise ArgumentError, "max_keys must be positive" unless max_keys.positive?
+
+        @mutex.synchronize do
+          return false if @processed.key?(key)
+
+          @processed[key] = Time.now.utc.iso8601
+          @processed.shift while @processed.length > max_keys
+          persist
+          true
+        end
+      end
+
+      private
+
+      def load_state
+        return [{}, {}] unless File.file?(@path)
+
+        state = JSON.parse(File.read(@path))
+        values = state.fetch("values", {})
+        processed = state.fetch("processed", {})
+        unless values.is_a?(Hash) && processed.is_a?(Hash)
+          raise JSON::ParserError, "transport state must contain JSON objects"
+        end
+
+        [values, processed]
+      rescue JSON::ParserError => e
+        raise "Invalid transport state #{@path}: #{e.message}"
+      end
+
+      def persist
+        PrivateFile.write_json(@path, "values" => @values, "processed" => @processed)
+      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
+  end
+end

data/lib/kward/transport.rb

@@ -0,0 +1,204 @@
+require "logger"
+require_relative "deep_copy"
+
+# Namespace for frontend-neutral external transport contracts.
+module Kward
+  module Transport
+    STREAMING_MODES = %i[native edit aggregate none].freeze
+
+    Actor = Data.define(:id, :display_name, :metadata)
+    Attachment = Data.define(:name, :mime_type, :data, :url, :metadata)
+    ConversationKey = Data.define(:transport_id, :external_id)
+    InboundMessage = Data.define(
+      :conversation,
+      :message_id,
+      :actor,
+      :text,
+      :attachments,
+      :reply_context,
+      :idempotency_key,
+      :metadata
+    )
+    TurnEvent = Data.define(:type, :session_id, :turn_id, :sequence, :payload)
+    InteractionRequest = Data.define(
+      :id,
+      :session_id,
+      :turn_id,
+      :kind,
+      :prompt,
+      :choices,
+      :expires_at,
+      :metadata
+    )
+    Capabilities = Data.define(:inbound, :outbound, :streaming, :limits)
+    ExecutionProfile = Data.define(
+      :id,
+      :tool_mode,
+      :allowed_tools,
+      :disabled_tools,
+      :plugin_commands,
+      :approval_mode,
+      :memory,
+      :attachments,
+      :workspace_mode,
+      :prompt_context
+    )
+
+    TOOL_MODES = %i[all none allowlist].freeze
+    APPROVAL_MODES = %i[default ask deny].freeze
+    MEMORY_MODES = %i[default none].freeze
+    WORKSPACE_MODES = %i[session fixed].freeze
+
+    module_function
+
+    def actor(id:, display_name: nil, metadata: {})
+      Actor.new(
+        id: required_string(id, "actor id"),
+        display_name: optional_string(display_name),
+        metadata: frozen_copy(metadata)
+      )
+    end
+
+    def attachment(name: nil, mime_type:, data: nil, url: nil, metadata: {})
+      raise ArgumentError, "attachment requires data or url" if data.nil? && url.nil?
+      raise ArgumentError, "attachment cannot contain both data and url" unless data.nil? || url.nil?
+
+      Attachment.new(
+        name: optional_string(name),
+        mime_type: required_string(mime_type, "attachment MIME type"),
+        data: data&.dup&.freeze,
+        url: url && required_string(url, "attachment URL"),
+        metadata: frozen_copy(metadata)
+      )
+    end
+
+    def conversation_key(transport_id:, external_id:)
+      ConversationKey.new(
+        transport_id: required_string(transport_id, "transport id"),
+        external_id: required_string(external_id, "external conversation id")
+      )
+    end
+
+    def inbound_message(conversation:, message_id:, actor:, text: "", attachments: [], reply_context: {}, idempotency_key:, metadata: {})
+      unless conversation.is_a?(ConversationKey)
+        raise ArgumentError, "conversation must be a Transport::ConversationKey"
+      end
+      unless actor.is_a?(Actor)
+        raise ArgumentError, "actor must be a Transport::Actor"
+      end
+
+      InboundMessage.new(
+        conversation: conversation,
+        message_id: required_string(message_id, "message id"),
+        actor: actor,
+        text: text.to_s.freeze,
+        attachments: frozen_copy(Array(attachments)),
+        reply_context: frozen_copy(reply_context),
+        idempotency_key: required_string(idempotency_key, "idempotency key"),
+        metadata: frozen_copy(metadata)
+      )
+    end
+
+    def turn_event(type:, session_id:, turn_id:, sequence:, payload: {})
+      TurnEvent.new(
+        type: required_string(type, "turn event type"),
+        session_id: required_string(session_id, "session id"),
+        turn_id: required_string(turn_id, "turn id"),
+        sequence: Integer(sequence),
+        payload: frozen_copy(payload)
+      )
+    end
+
+    def interaction_request(id:, session_id:, turn_id:, kind:, prompt:, choices: [], expires_at: nil, metadata: {})
+      InteractionRequest.new(
+        id: required_string(id, "interaction id"),
+        session_id: required_string(session_id, "session id"),
+        turn_id: required_string(turn_id, "turn id"),
+        kind: required_string(kind, "interaction kind"),
+        prompt: required_string(prompt, "interaction prompt"),
+        choices: frozen_copy(Array(choices)),
+        expires_at: expires_at,
+        metadata: frozen_copy(metadata)
+      )
+    end
+
+    def execution_profile(
+      id:,
+      tool_mode: :all,
+      allowed_tools: nil,
+      disabled_tools: nil,
+      plugin_commands: true,
+      approval_mode: :default,
+      memory: :default,
+      attachments: true,
+      workspace_mode: :session,
+      prompt_context: nil
+    )
+      id = required_string(id, "execution profile id")
+      tool_mode = tool_mode.to_sym
+      approval_mode = approval_mode.to_sym
+      memory = memory.to_sym
+      workspace_mode = workspace_mode.to_sym
+      raise ArgumentError, "unsupported tool mode: #{tool_mode}" unless TOOL_MODES.include?(tool_mode)
+      raise ArgumentError, "unsupported approval mode: #{approval_mode}" unless APPROVAL_MODES.include?(approval_mode)
+      raise ArgumentError, "unsupported memory mode: #{memory}" unless MEMORY_MODES.include?(memory)
+      raise ArgumentError, "unsupported workspace mode: #{workspace_mode}" unless WORKSPACE_MODES.include?(workspace_mode)
+      raise ArgumentError, "allowlist tool mode requires allowed_tools" if tool_mode == :allowlist && Array(allowed_tools).empty?
+      raise ArgumentError, "none tool mode cannot define allowed_tools" if tool_mode == :none && allowed_tools
+      raise ArgumentError, "allowed_tools and disabled_tools cannot both be set" if allowed_tools && disabled_tools
+
+      ExecutionProfile.new(
+        id: id,
+        tool_mode: tool_mode,
+        allowed_tools: frozen_symbols(allowed_tools),
+        disabled_tools: frozen_symbols(disabled_tools),
+        plugin_commands: !!plugin_commands,
+        approval_mode: approval_mode,
+        memory: memory,
+        attachments: !!attachments,
+        workspace_mode: workspace_mode,
+        prompt_context: prompt_context.nil? ? nil : prompt_context.to_s.freeze
+      )
+    end
+
+    def capabilities(inbound: [], outbound: [], streaming: :none, limits: {})
+      streaming = streaming.to_sym
+      raise ArgumentError, "unsupported streaming mode: #{streaming}" unless STREAMING_MODES.include?(streaming)
+
+      Capabilities.new(
+        inbound: frozen_symbols(inbound),
+        outbound: frozen_symbols(outbound),
+        streaming: streaming,
+        limits: frozen_copy(limits)
+      )
+    end
+
+    def required_string(value, name)
+      value = value.to_s
+      raise ArgumentError, "#{name} is required" if value.empty?
+
+      value.freeze
+    end
+    private_class_method :required_string
+
+    def optional_string(value)
+      value.nil? ? nil : value.to_s.freeze
+    end
+    private_class_method :optional_string
+
+    def frozen_symbols(values)
+      Array(values).map { |value| value.to_sym }.uniq.freeze
+    end
+    private_class_method :frozen_symbols
+
+    def frozen_copy(value)
+      DeepCopy.freeze(DeepCopy.dup(value))
+    end
+    private_class_method :frozen_copy
+  end
+end
+
+require_relative "transport/store"
+require_relative "transport/host"
+require_relative "transport/manager"
+require_relative "transport/gateway"