insika 0.0.1 → 0.2.0

data/lib/insika/server/a2a/app.rb

@@ -0,0 +1,112 @@
+# frozen_string_literal: true
+
+require "time"
+require_relative "protocol"
+require_relative "errors"
+require_relative "message"
+require_relative "task_projection"
+require_relative "agent_card"
+
+module Insika
+  module Server
+    module A2A
+      # A2A edge handler: injected sub-app mounted by Server::App. A2A is
+      # TRANSPORT — translates JSON-RPC↔Command on the SAME bus, projects
+      # Task→A2A, and NEVER leaks an exception (always an error object).
+      class App
+        def initialize(command_bus:, task_store:, session_store:, profiles:, skill_catalog:, config:)
+          @command_bus = command_bus
+          @task_store = task_store
+          @session_store = session_store
+          @profiles = Insika::ProfileSource.coerce(profiles)
+          @skill_catalog = skill_catalog
+          @config = config # { a2a_agent:, base_url: }
+        end
+
+        # POST /a2a — `body` is already the deserialized Hash. -> JSON-RPC envelope.
+        def rpc(body)
+          kind, parsed = Protocol.parse(body)
+          return Protocol.error(parsed[:id], parsed[:code], parsed[:message]) if kind == :error
+
+          dispatch_method(parsed[:id], parsed[:method], parsed[:params])
+        rescue StandardError => e # safety net: parse ok but something slipped through
+          code, message = Errors.from_exception(e)
+          Protocol.error(nil, code, message)
+        end
+
+        # GET /.well-known/agent-card.json
+        def agent_card
+          agent = @profiles[@config[:a2a_agent]]
+          skills = @skill_catalog.effective(agent.skills)
+          AgentCard.build(agent: agent, base_url: @config[:base_url], skills: skills)
+        end
+
+        private
+
+        def dispatch_method(id, method, params)
+          case method
+          when "message/send" then message_send(id, params)
+          when "tasks/get"    then tasks_get(id, params)
+          when "tasks/cancel" then tasks_cancel(id, params)
+          else Protocol.error(id, Errors::METHOD_NOT_FOUND, "method '#{method}' not supported")
+          end
+        rescue StandardError => e # map core error -> A2A code
+          code, message = Errors.from_exception(e)
+          Protocol.error(id, code, message)
+        end
+
+        # message/send returns the Task; missing contextId -> creates a session (the
+        # server assigns the contextId; ensures a transcript for tasks/get).
+        def message_send(id, params)
+          message = params["message"] || {}
+          session_id = message["contextId"] || params["contextId"]
+          session_id ||= @command_bus.dispatch(build(:create_session, {})).id
+          text = Message.text_from(message)
+          result = @command_bus.dispatch(build(:send_message,
+                                               agent: @config[:a2a_agent], message: text, session_id: session_id))
+          task = @task_store.find(result[:task_id])
+          Protocol.result(id, TaskProjection.call(task, at: now))
+        end
+
+        def tasks_get(id, params)
+          task = @task_store.find(params["id"])
+          return Protocol.error(id, Errors::TASK_NOT_FOUND, "task not found: #{params['id']}") if task.nil?
+
+          Protocol.result(id, TaskProjection.call(task, at: now,
+                                                        content: terminal_content(task),
+                                                        error: terminal_error(task)))
+        end
+
+        def tasks_cancel(id, params)
+          task_id = params["id"]
+          return Protocol.error(id, Errors::TASK_NOT_FOUND, "task not found: #{task_id}") if @task_store.find(task_id).nil?
+
+          @command_bus.dispatch(build(:cancel_task, task_id: task_id))
+          Protocol.result(id, TaskProjection.call(@task_store.find(task_id), at: now))
+        end
+
+        # Final content = last `assistant` message in the session transcript.
+        def terminal_content(task)
+          return nil unless task.session_id
+
+          session = @session_store.find(task.session_id)
+          return nil unless session
+
+          msg = session.messages.reverse.find { |m| (m["role"] || m[:role]).to_s == "assistant" }
+          msg && (msg["content"] || msg[:content])
+        end
+
+        # Error message from the last :failed Execution.
+        def terminal_error(task)
+          exec = task.executions.last
+          return nil unless exec && exec.outcome.to_s == "failed"
+
+          exec.error && (exec.error["message"] || exec.error[:message])
+        end
+
+        def build(type, payload) = Insika::Command.build(type, payload, transport: :a2a)
+        def now = Time.now.utc.iso8601
+      end
+    end
+  end
+end

data/lib/insika/server/a2a/client.rb

@@ -0,0 +1,101 @@
+# frozen_string_literal: true
+
+require_relative "message"
+
+module Insika
+  module Server
+    module A2A
+      # JSON-RPC response envelope carrying `error` (the remote refused/failed).
+      class RemoteError < StandardError
+        attr_reader :code
+
+        def initialize(code, message)
+          @code = code
+          super(message)
+        end
+      end
+
+      # Outbound A2A client: calls a remote A2A agent. PURE — the
+      # `http` (post_json(url, body) -> Hash) is injected; the smoke test uses loopback.
+      class Client
+        TERMINAL = %w[completed failed canceled rejected input-required].freeze
+        POLL_DELAY = 0.02
+
+        def initialize(http:, poll_max: 30, sleeper: nil)
+          @http = http
+          @poll_max = poll_max
+          @sleeper = sleeper || ->(seconds) { Async::Task.current&.sleep(seconds) }
+          @id_seq = 0
+        end
+
+        # -> remote A2A Task (Hash) | raise RemoteError.
+        def send_message(url, text, context_id: nil)
+          message = { "role" => "user", "parts" => [{ "kind" => "text", "text" => text.to_s }] }
+          message["contextId"] = context_id if context_id
+          parse_envelope(@http.post_json(url, request("message/send", { "message" => message })))
+        end
+
+        # -> remote A2A Task (Hash) | raise RemoteError.
+        def get_task(url, task_id)
+          parse_envelope(@http.post_json(url, request("tasks/get", { "id" => task_id })))
+        end
+
+        # High level: send + poll until terminal. ALWAYS does ≥1 get_task — the
+        # inbound message/send projects the Task WITHOUT `status.message` (the content
+        # only comes from tasks/get). -> { text:, state:, id: } | { error:, state:, id: }.
+        # NEVER raises (wraps RemoteError).
+        def call(url, text, context_id: nil)
+          sent = send_message(url, text, context_id: context_id)
+          id = remote_id(sent)
+          task = get_task(url, id)
+          attempts = 0
+          until TERMINAL.include?(remote_state(task)) || attempts >= @poll_max
+            @sleeper.call(POLL_DELAY)
+            attempts += 1
+            task = get_task(url, id)
+          end
+          project(task, id)
+        rescue RemoteError => e
+          { error: e.message, state: "failed", id: nil }
+        end
+
+        private
+
+        def request(method, params)
+          @id_seq += 1
+          { "jsonrpc" => "2.0", "id" => @id_seq, "method" => method, "params" => params }
+        end
+
+        def parse_envelope(response)
+          raise RemoteError.new(nil, "invalid A2A response") unless response.is_a?(Hash)
+          return response["result"] if response.key?("result")
+
+          err = response["error"]
+          raise RemoteError.new(err && err["code"], (err && err["message"]).to_s) if err
+
+          raise RemoteError.new(nil, "A2A response has neither result nor error")
+        end
+
+        def remote_state(task) = task.is_a?(Hash) ? task.dig("status", "state").to_s : ""
+        def remote_text(task)  = Message.text_from(task.is_a?(Hash) ? task.dig("status", "message") : nil)
+        def remote_id(task)    = task.is_a?(Hash) ? task["id"] : nil
+
+        # completed/input-required -> text; failed/canceled/rejected -> error
+        # (text if present, else the state itself — avoids the "".truthy footgun);
+        # exhausted poll (non-terminal) -> error.
+        def project(task, id)
+          state = remote_state(task)
+          text = remote_text(task)
+          case state
+          when "completed", "input-required"
+            { text: text, state: state, id: id }
+          when "failed", "canceled", "rejected"
+            { error: text.empty? ? state : text, state: state, id: id }
+          else
+            { error: "remote task did not complete (state: #{state})", state: state, id: id }
+          end
+        end
+      end
+    end
+  end
+end

data/lib/insika/server/a2a/errors.rb

@@ -0,0 +1,32 @@
+# frozen_string_literal: true
+
+module Insika
+  module Server
+    module A2A
+      # A2A adapter error map: standard JSON-RPC 2.0 codes +
+      # A2A extensions. The `App` NEVER leaks an exception — always an error object.
+      module Errors
+        PARSE_ERROR         = -32_700
+        INVALID_REQUEST     = -32_600
+        METHOD_NOT_FOUND    = -32_601
+        INVALID_PARAMS      = -32_602
+        INTERNAL_ERROR      = -32_603
+        TASK_NOT_FOUND      = -32_001 # A2A TaskNotFoundError
+        TASK_NOT_CANCELABLE = -32_002 # A2A TaskNotCancelableError
+
+        # Core exception -> [code, message]. A task `NotFoundError` is handled
+        # EXPLICITLY in the App (tasks/get returns TASK_NOT_FOUND directly), so
+        # here `NotFoundError` falls into INVALID_PARAMS (missing agent/session in the
+        # request). Anything else -> INTERNAL_ERROR (generic message, no stack).
+        def self.from_exception(error)
+          case error
+          when Insika::ValidationError, Insika::NotFoundError
+            [INVALID_PARAMS, error.message]
+          else
+            [INTERNAL_ERROR, "internal error"]
+          end
+        end
+      end
+    end
+  end
+end

data/lib/insika/server/a2a/http.rb

@@ -0,0 +1,42 @@
+# frozen_string_literal: true
+
+require "json"
+
+module Insika
+  module Server
+    module A2A
+      # Production HTTP adapter: implements the duck-type
+      # `post_json(url, body) -> Hash` over async-http (runs on the turn's reactor).
+      # BOUNDARY — the lib require lives here, never in lib/insika.rb/wiring-load.
+      # The Client (the logic) is tested with a fake; this adapter, with a light test.
+      class Http
+        HEADERS = [["content-type", "application/json"], ["accept", "application/json"]].freeze
+
+        def initialize(internet: nil)
+          @internet = internet # lazy: Async::HTTP::Internet.new
+        end
+
+        # POST JSON -> Hash (parsed JSON-RPC, string keys).
+        def post_json(url, body)
+          response = internet.post(url, HEADERS, JSON.generate(body))
+          JSON.parse(response.read.to_s)
+        end
+
+        def close
+          @internet&.close
+        rescue StandardError
+          nil # best-effort
+        end
+
+        private
+
+        def internet
+          @internet ||= begin
+            require "async/http/internet"
+            Async::HTTP::Internet.new
+          end
+        end
+      end
+    end
+  end
+end

data/lib/insika/server/a2a/message.rb

@@ -0,0 +1,27 @@
+# frozen_string_literal: true
+
+module Insika
+  module Server
+    module A2A
+      # Message parts translation: TextPart only in this slice.
+      # Tolerates `kind` (A2A ~v0.2+) and `type` (older spec) at the boundary.
+      module Message
+        # A2A Message (Hash) -> String (concatenates the TextParts). "" if none.
+        def self.text_from(a2a_message)
+          parts = a2a_message.is_a?(Hash) ? Array(a2a_message["parts"] || a2a_message[:parts]) : []
+          parts.filter_map do |part|
+            next unless part.is_a?(Hash)
+
+            kind = part["kind"] || part["type"] || part[:kind] || part[:type]
+            (part["text"] || part[:text]).to_s if kind.to_s == "text"
+          end.join
+        end
+
+        # String -> A2A Message (role agent, 1 TextPart).
+        def self.agent_message(text)
+          { role: "agent", parts: [{ kind: "text", text: text.to_s }] }
+        end
+      end
+    end
+  end
+end

data/lib/insika/server/a2a/protocol.rb

@@ -0,0 +1,45 @@
+# frozen_string_literal: true
+
+require_relative "errors"
+
+module Insika
+  module Server
+    module A2A
+      # JSON-RPC 2.0 envelope. PURE — receives the already
+      # deserialized Hash (raw JSON parsing belongs to Server::App). NEVER raises.
+      module Protocol
+        VERSION = "2.0"
+
+        # -> [:ok, { id:, method:, params: }] | [:error, { id:, code:, message: }]
+        def self.parse(body)
+          return err(nil, Errors::INVALID_REQUEST, "request must be a JSON-RPC object") unless body.is_a?(Hash)
+
+          id = body["id"] # missing -> nil (we always respond; no notifications in this slice)
+          return err(id, Errors::INVALID_REQUEST, "jsonrpc must be '2.0'") unless body["jsonrpc"] == VERSION
+
+          method = body["method"]
+          return err(id, Errors::INVALID_REQUEST, "method missing") unless method.is_a?(String) && !method.empty?
+
+          [:ok, { id: id, method: method, params: body["params"] || {} }]
+        end
+
+        # { jsonrpc:, id:, result: }
+        def self.result(id, result)
+          { jsonrpc: VERSION, id: id, result: result }
+        end
+
+        # { jsonrpc:, id:, error: { code:, message:, data? } }
+        def self.error(id, code, message, data: nil)
+          err = { code: code, message: message }
+          err[:data] = data unless data.nil?
+          { jsonrpc: VERSION, id: id, error: err }
+        end
+
+        def self.err(id, code, message)
+          [:error, { id: id, code: code, message: message }]
+        end
+        private_class_method :err
+      end
+    end
+  end
+end

data/lib/insika/server/a2a/remotes.rb

@@ -0,0 +1,25 @@
+# frozen_string_literal: true
+
+module Insika
+  module Server
+    module A2A
+      # Remote A2A agents config. Parses "id=url,id2=url2".
+      module Remotes
+        Remote = Data.define(:id, :url, :description)
+
+        # -> [Remote]. Malformed entries (no '=', empty id/url) are ignored
+        # with a warn. env nil/"" -> [].
+        def self.parse(env_string, descriptions: {})
+          env_string.to_s.split(",").filter_map do |entry|
+            id, url = entry.split("=", 2).map { |s| s.to_s.strip }
+            if id.to_s.empty? || url.to_s.empty?
+              warn "[a2a] malformed remote ignored: #{entry.inspect} (use id=url)"
+              next
+            end
+            Remote.new(id: id, url: url, description: descriptions[id])
+          end
+        end
+      end
+    end
+  end
+end

data/lib/insika/server/a2a/task_projection.rb

@@ -0,0 +1,40 @@
+# frozen_string_literal: true
+
+require_relative "message"
+
+module Insika
+  module Server
+    module A2A
+      # Task (core) -> A2A Task projection. PURE.
+      module TaskProjection
+        # State map. Unknown state -> "unknown".
+        STATE = {
+          queued: "submitted", running: "working", waiting: "input-required",
+          paused: "working", completed: "completed", failed: "failed", cancelled: "canceled"
+        }.freeze
+
+        # task (TaskStore::Task) + content/error (String|nil) + at (ISO8601) -> Hash A2A Task.
+        def self.call(task, at:, content: nil, error: nil)
+          state = STATE.fetch(task.status.to_sym, "unknown")
+          status = { state: state, timestamp: at }
+          msg = status_message(state, content, error)
+          status[:message] = msg if msg
+
+          {
+            id: task.id, contextId: task.session_id, kind: "task",
+            status: status, artifacts: [], history: []
+          }
+        end
+
+        # completed -> content; failed -> error; other states have no message.
+        def self.status_message(state, content, error)
+          case state
+          when "completed" then content && Message.agent_message(content)
+          when "failed"    then error && Message.agent_message(error)
+          end
+        end
+        private_class_method :status_message
+      end
+    end
+  end
+end