kward 0.78.0 → 0.80.0

data/lib/kward/transport/host.rb

@@ -0,0 +1,343 @@
+require_relative "../deep_copy"
+require_relative "store"
+
+module Kward
+  module Transport
+    # Public dependencies made available to a running transport adapter.
+    class Host
+      class UnavailableGateway < StandardError; end
+      class PolicyDenied < StandardError; end
+
+      SessionHandle = Data.define(:id, :workspace_root, :name)
+      TurnHandle = Data.define(:id, :session_id)
+      PluginChatHandle = Data.define(:id, :type_id, :scope_key, :name)
+      PluginChatTurnHandle = Data.define(:id, :chat_id)
+
+      # Creates a host for one registered transport instance.
+      def initialize(transport_id:, gateway: nil, plugin_chat_gateway: nil, config: {}, storage: nil, policy: nil, logger: nil, execution_profile: nil)
+        unless execution_profile.nil? || execution_profile.is_a?(ExecutionProfile)
+          raise ArgumentError, "execution_profile must be a Transport::ExecutionProfile"
+        end
+
+        @transport_id = transport_id.to_s.freeze
+        @gateway = gateway
+        @plugin_chat_gateway = plugin_chat_gateway
+        @config = freeze_copy(config)
+        @storage = storage || Store.new(@transport_id)
+        @policy = policy || AllowAllPolicy.new
+        @execution_profile = execution_profile
+        @logger = logger || Logger.new($stderr)
+        @sessions = Sessions.new(self)
+        @plugin_chats = PluginChats.new(self)
+        @interactions = Interactions.new(self)
+      end
+
+      attr_reader :transport_id, :config, :storage, :policy, :execution_profile, :logger
+
+      def sessions
+        @sessions
+      end
+
+      def interactions
+        @interactions
+      end
+
+      def plugin_chats
+        @plugin_chats
+      end
+
+      def gateway
+        return @gateway if @gateway
+
+        raise UnavailableGateway, "transport host has no session gateway"
+      end
+
+      def authorize!(action, **attributes)
+        return true if policy.authorize(action: action, transport_id: @transport_id, **attributes) == true
+
+        raise PolicyDenied, "Transport policy denied #{action}"
+      end
+
+      def plugin_chat_gateway
+        return @plugin_chat_gateway if @plugin_chat_gateway
+
+        raise UnavailableGateway, "transport host has no plugin chat gateway"
+      end
+
+      # Reads a transport secret from private config or an explicit environment
+      # variable without exposing it through status or logging helpers.
+      def secret(key, env: nil)
+        key = key.to_s
+        raise ArgumentError, "secret key is required" if key.empty?
+
+        value = config[key]
+        value = ENV.fetch(env.to_s) if value.nil? && env
+        value = ENV[default_secret_env_name(key)] if value.nil?
+        value.to_s unless value.nil?
+      end
+
+      def shutdown
+        @gateway&.shutdown
+        @plugin_chat_gateway&.shutdown
+        nil
+      end
+
+      # Resolves an external conversation to a normal Kward session.
+      class Sessions
+        def initialize(host)
+          @host = host
+        end
+
+        def resolve(conversation:, actor:, workspace_root: nil, name: nil)
+          workspace_root = fixed_workspace_root(workspace_root)
+          @host.authorize!(:resolve_session, conversation: conversation, actor: actor, workspace_root: workspace_root)
+          result = @host.gateway.resolve_transport_session(
+            transport_id: @host.transport_id,
+            conversation: conversation,
+            actor: actor,
+            workspace_root: workspace_root,
+            name: name,
+            execution_profile: @host.execution_profile
+          )
+          Session.new(@host, normalize_handle(result), actor)
+        end
+
+        private
+
+        def fixed_workspace_root(workspace_root)
+          return workspace_root unless @host.execution_profile&.workspace_mode == :fixed
+
+          configured = @host.config["workspace"] || @host.config[:workspace]
+          raise ArgumentError, "fixed execution profile requires a configured workspace" if configured.to_s.empty?
+
+          configured.to_s
+        end
+
+        def normalize_handle(result)
+          return result if result.is_a?(SessionHandle)
+          return SessionHandle.new(**result.transform_keys(&:to_sym)) if result.is_a?(Hash)
+
+          raise TypeError, "session gateway returned an invalid session handle"
+        end
+      end
+
+      # Narrow session operations exposed to a transport.
+      class Session
+        attr_reader :id, :workspace_root, :name
+
+        def initialize(host, handle, actor)
+          @host = host
+          @actor = actor
+          @id = handle.id.to_s.freeze
+          @workspace_root = handle.workspace_root.to_s.freeze
+          @name = handle.name&.to_s&.freeze
+        end
+
+        def start_turn(input, attachments: [], options: {}, streaming_behavior: nil)
+          @host.authorize!(:start_turn, actor: @actor, session_id: @id, input: input.to_s)
+          result = @host.gateway.start_transport_turn(
+            session_id: @id,
+            input: input.to_s,
+            attachments: attachments,
+            options: options,
+            streaming_behavior: streaming_behavior,
+            execution_profile: @host.execution_profile
+          )
+          handle = result.is_a?(TurnHandle) ? result : TurnHandle.new(**result.transform_keys(&:to_sym))
+          Turn.new(@host, handle, @actor)
+        end
+
+        def transcript
+          @host.authorize!(:read_transcript, actor: @actor, session_id: @id)
+          @host.gateway.transport_transcript(session_id: @id)
+        end
+
+        def answer_interaction(request_id:, answer:)
+          if @host.execution_profile&.approval_mode == :deny
+            raise PolicyDenied, "Transport execution profile does not allow interactions"
+          end
+
+          @host.authorize!(:answer_interaction, actor: @actor, session_id: @id, request_id: request_id)
+          @host.gateway.answer_transport_interaction(session_id: @id, request_id: request_id, answer: answer)
+        end
+      end
+
+      # Resolves an external conversation to a plugin-owned chat.
+      class PluginChats
+        def initialize(host)
+          @host = host
+        end
+
+        def resolve(type_id:, conversation:, actor:, scope_key: nil, descriptor: {})
+          scope_key ||= conversation.external_id
+          @host.authorize!(:resolve_plugin_chat, type_id: type_id.to_s, conversation: conversation, actor: actor, scope_key: scope_key)
+          result = @host.plugin_chat_gateway.resolve_transport_chat(
+            transport_id: @host.transport_id,
+            type_id: type_id,
+            conversation: conversation,
+            actor: actor,
+            scope_key: scope_key,
+            descriptor: descriptor,
+            workspace_root: workspace_root
+          )
+          PluginChat.new(@host, normalize_handle(result), actor)
+        end
+
+        private
+
+        def workspace_root
+          if @host.execution_profile&.workspace_mode == :fixed
+            configured = @host.config["workspace"] || @host.config[:workspace]
+            raise ArgumentError, "fixed execution profile requires a configured workspace" if configured.to_s.empty?
+
+            return configured.to_s
+          end
+
+          @host.config["workspace"] || @host.config[:workspace] || Dir.pwd
+        end
+
+        def normalize_handle(result)
+          return result if result.is_a?(PluginChatHandle)
+          return PluginChatHandle.new(**result.transform_keys(&:to_sym)) if result.is_a?(Hash)
+
+          raise TypeError, "plugin chat gateway returned an invalid chat handle"
+        end
+      end
+
+      # Narrow plugin-chat operations exposed to a transport.
+      class PluginChat
+        attr_reader :id, :type_id, :scope_key, :name
+
+        def initialize(host, handle, actor)
+          @host = host
+          @actor = actor
+          @id = handle.id.to_s.freeze
+          @type_id = handle.type_id.to_s.freeze
+          @scope_key = handle.scope_key.to_s.freeze
+          @name = handle.name&.to_s&.freeze
+        end
+
+        def start_turn(input, attachments: [], options: {}, streaming_behavior: nil)
+          @host.authorize!(:start_plugin_chat_turn, actor: @actor, chat_id: @id, type_id: @type_id, input: input.to_s)
+          if @host.execution_profile && !@host.execution_profile.attachments && !Array(attachments).empty?
+            raise PolicyDenied, "Transport execution profile does not allow attachments"
+          end
+          unless options.nil? || options.empty?
+            raise ArgumentError, "plugin chat turns do not support options"
+          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
+
+          result = @host.plugin_chat_gateway.start_transport_plugin_chat_turn(
+            chat_id: @id,
+            actor: @actor,
+            input: input,
+            attachments: attachments,
+            streaming_behavior: streaming_behavior,
+            execution_profile: @host.execution_profile
+          )
+          handle = result.is_a?(PluginChatTurnHandle) ? result : PluginChatTurnHandle.new(**result.transform_keys(&:to_sym))
+          PluginChatTurn.new(@host, handle, @actor)
+        end
+
+        def transcript
+          @host.authorize!(:read_plugin_chat_transcript, actor: @actor, chat_id: @id, type_id: @type_id)
+          @host.plugin_chat_gateway.transport_plugin_chat_transcript(chat_id: @id)
+        end
+      end
+
+      # Handle for an asynchronously running plugin-chat turn.
+      class PluginChatTurn
+        attr_reader :id, :chat_id
+
+        def initialize(host, handle, actor)
+          @host = host
+          @actor = actor
+          @id = handle.id.to_s.freeze
+          @chat_id = handle.chat_id.to_s.freeze
+        end
+
+        def subscribe(after: nil, &block)
+          raise ArgumentError, "plugin chat turn subscription requires a block" unless block
+
+          @host.plugin_chat_gateway.subscribe_transport_plugin_chat_turn(turn_id: @id, after: after, &block)
+        end
+
+        def events(after: nil)
+          @host.plugin_chat_gateway.transport_plugin_chat_turn_events(turn_id: @id, after: after)
+        end
+
+        def status
+          @host.plugin_chat_gateway.transport_plugin_chat_turn_status(turn_id: @id)
+        end
+
+        def cancel
+          @host.authorize!(:cancel_plugin_chat_turn, actor: @actor, chat_id: @chat_id, turn_id: @id)
+          @host.plugin_chat_gateway.cancel_transport_plugin_chat_turn(turn_id: @id)
+        end
+      end
+
+      # Subscribes to questions and tool approval requests for this transport.
+      class Interactions
+        def initialize(host)
+          @host = host
+        end
+
+        def subscribe(&block)
+          raise ArgumentError, "interaction subscription requires a block" unless block
+
+          @host.gateway.subscribe_transport_interactions(&block)
+        end
+      end
+
+      # Handle for an asynchronously running Kward turn.
+      class Turn
+        attr_reader :id, :session_id
+
+        def initialize(host, handle, actor)
+          @host = host
+          @actor = actor
+          @id = handle.id.to_s.freeze
+          @session_id = handle.session_id.to_s.freeze
+        end
+
+        def subscribe(after: nil, &block)
+          raise ArgumentError, "turn subscription requires a block" unless block
+
+          @host.gateway.subscribe_transport_turn(turn_id: @id, after: after, &block)
+        end
+
+        def events(after: nil)
+          @host.gateway.transport_turn_events(turn_id: @id, after: after)
+        end
+
+        def status
+          @host.gateway.transport_turn_status(turn_id: @id)
+        end
+
+        def cancel
+          @host.authorize!(:cancel_turn, actor: @actor, session_id: @session_id, turn_id: @id)
+          @host.gateway.cancel_transport_turn(turn_id: @id)
+        end
+      end
+
+      # Default policy used by the host until a configured policy is supplied.
+      class AllowAllPolicy
+        def authorize(**)
+          true
+        end
+      end
+
+      private
+
+      def default_secret_env_name(key)
+        "KWARD_TRANSPORT_#{@transport_id.gsub(/[^A-Za-z0-9]/, "_").upcase}_#{key.gsub(/[^A-Za-z0-9]/, "_").upcase}"
+      end
+
+      def freeze_copy(value)
+        DeepCopy.freeze(DeepCopy.dup(value))
+      end
+    end
+  end
+end

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