insika 0.0.1 → 0.1.0

data/lib/insika/sandbox/local.rb

@@ -0,0 +1,33 @@
+# frozen_string_literal: true
+
+require_relative "runner"
+
+module Insika
+  module Sandbox
+    # Default exec provider: runs the command IN-PROCESS on the host, with the
+    # working directory pinned to the sandbox root. This is the "narrowest sandbox
+    # that supports the task" for trusted/local operation — cheap, no daemon, no
+    # image pull. It is NOT an isolation boundary for a shell (a command can still
+    # read absolute paths or `cd ..`); that is why shell tools stay approval-gated
+    # and why the `docker` provider exists for untrusted execution.
+    #
+    # The improvement over the prototype's raw `capture2e` is the real hard-kill
+    # timeout (via Runner): a hung command no longer holds the turn open until the
+    # OS returns.
+    class Local
+      # `-c` (non-login): a login shell would source ~/.bash_profile on every
+      # call, adding latency and letting host dotfiles mutate PATH/env under the
+      # command — surprising for a sandboxed tool.
+      def initialize(shell: "/bin/bash")
+        @shell = shell
+      end
+
+      def exec(command, root:, timeout:, max_output:)
+        Runner.run([@shell, "-c", command.to_s],
+                   chdir: root, timeout: timeout, max_output: max_output)
+      end
+
+      def to_s = "local(#{@shell})"
+    end
+  end
+end

data/lib/insika/sandbox/runner.rb

@@ -0,0 +1,80 @@
+# frozen_string_literal: true
+
+require "open3"
+require_relative "../coercion"
+
+module Insika
+  module Sandbox
+    # Structured result of a sandboxed command. `timed_out` distinguishes a
+    # deadline kill (exit_status nil) from a normal exit. `output` is the combined
+    # stdout+stderr, already clipped to the provider's cap.
+    Result = Data.define(:exit_status, :output, :timed_out) do
+      def timed_out? = timed_out
+      # Shape returned to the model by the bash tool (parity with the prototype).
+      def to_h = { exit_status: exit_status, output: output, timed_out: timed_out }
+    end
+
+    # Spawns a command with a REAL hard-kill timeout, shared by every exec
+    # provider. Unlike the prototype's `Open3.capture2e` (which blocks
+    # uninterruptibly — a hung command holds the fiber until the OS returns), this
+    # bounds wall-clock: on expiry the process (and, via its own process group,
+    # any children) is force-killed and whatever partial output was captured is
+    # returned with `timed_out: true`.
+    #
+    # Stdlib `Timeout.timeout` is deliberately NOT used (forbidden by the engine's
+    # fiber contract, see errors.rb); the deadline is enforced by
+    # `Thread#join(timeout)` — a single bounded blocking call — and the reader
+    # runs on its own thread so partial output survives the kill.
+    module Runner
+      # Grace period for the output reader to drain after the process is killed.
+      DRAIN_TIMEOUT = 2
+
+      module_function
+
+      # argv:      the command as an argv array (never a shell string — no
+      #            re-interpretation by the host shell).
+      # chdir:     working directory of the spawned process.
+      # kill:      optional extra teardown (e.g. `docker kill <name>`); the
+      #            process group is ALWAYS killed regardless.
+      def run(argv, chdir:, timeout:, max_output:, env: {}, kill: nil)
+        # pgroup: true -> the child is a new group leader (pgid == pid), so a
+        # single kill on the negated pid reaps the command AND anything it forked.
+        Open3.popen2e(env, *argv, chdir: chdir, pgroup: true) do |stdin, out, wait_thr|
+          stdin.close
+          reader = Thread.new { out.read }
+
+          if wait_thr.join(timeout).nil?
+            terminate(wait_thr.pid, kill)
+            Result.new(exit_status: nil, output: drain(reader, max_output), timed_out: true)
+          else
+            Result.new(exit_status: wait_thr.value.exitstatus,
+                       output: drain(reader, max_output), timed_out: false)
+          end
+        end
+      end
+
+      # Kill the whole process group, then run any provider-specific teardown.
+      # ESRCH (already gone) / EPERM are benign races — the process is dying.
+      def terminate(pid, kill)
+        Process.kill("KILL", -pid)
+      rescue Errno::ESRCH, Errno::EPERM
+        nil
+      ensure
+        kill&.call
+      end
+
+      # Collect the reader's output within a grace window. After a kill the write
+      # end closes and `out.read` returns promptly; the bound guards a reader that
+      # somehow does not (returns "" rather than blocking the fiber forever).
+      #
+      # The output of an arbitrary command is arbitrary bytes: scrubbed to valid
+      # UTF-8 before clipping (the clip is then by character, never splitting one)
+      # because it becomes a tool result and gets JSON-serialized downstream.
+      def drain(reader, max_output)
+        return "" if reader.join(DRAIN_TIMEOUT).nil?
+
+        Insika::Coercion.utf8(reader.value)[0, max_output]
+      end
+    end
+  end
+end

data/lib/insika/sandbox.rb

@@ -0,0 +1,85 @@
+# frozen_string_literal: true
+
+require_relative "coercion"
+require_relative "sandbox/boundary"
+require_relative "sandbox/runner"
+require_relative "sandbox/local"
+require_relative "sandbox/docker"
+
+module Insika
+  # Sandbox primitive (item 35 / COMPETITIVE-ANALYSIS §4.6): a single, pluggable
+  # interface for confined execution, promoted to the core from the insika-code
+  # prototype. Two halves:
+  #
+  #   * FS confinement (`Boundary`) — ALWAYS host-side, always on: every path a
+  #     tool resolves is proven inside the root before any IO.
+  #   * command exec — via a swappable PROVIDER: `local` (in-process, the default)
+  #     or `docker` (isolated container). Providers are chosen by DATA, not code
+  #     (config-over-code): the agent profile's `sandbox` block names the provider
+  #     and its policy.
+  #
+  # `Env` is the object a tool holds; `Sandbox.build(config)` assembles one from
+  # the declarative config (the same hash shape stored on the profile).
+  module Sandbox
+    # Ergonomic alias so tools can rescue `Insika::Sandbox::Escape` without
+    # reaching into the Boundary. It IS Boundary::Escape (same class).
+    Escape = Boundary::Escape
+
+    DEFAULT_TIMEOUT    = 120
+    DEFAULT_MAX_OUTPUT = 40_000
+
+    module_function
+
+    # config keys (all optional, string or symbol):
+    #   provider    "local" (default) | "docker"
+    #   root        confinement root (default: Dir.pwd)
+    #   timeout     per-exec wall-clock seconds (default 120)
+    #   max_output  bytes of combined output kept (default 40_000)
+    #   + provider-specific keys (image/network/memory/cpus/... for docker)
+    def build(config = {})
+      cfg  = Coercion.deep_stringify(config || {})
+      root = cfg["root"].to_s.empty? ? Dir.pwd : cfg["root"]
+      Env.new(
+        boundary: Boundary.new(root),
+        provider: provider_for(cfg),
+        timeout: Integer(cfg["timeout"] || DEFAULT_TIMEOUT),
+        max_output: Integer(cfg["max_output"] || DEFAULT_MAX_OUTPUT)
+      )
+    end
+
+    def provider_for(cfg)
+      case cfg["provider"].to_s
+      when "", "local" then Local.new(shell: cfg["shell"] || "/bin/bash")
+      when "docker"     then Docker.new(cfg)
+      else raise ArgumentError, "unknown sandbox provider: #{cfg["provider"].inspect}"
+      end
+    end
+
+    # The per-agent sandbox environment: composes an FS boundary with an exec
+    # provider and the default limits. Delegates the boundary surface (resolve /
+    # relative / inside?) and adds `exec`. Immutable, safely shared across turns.
+    class Env
+      attr_reader :boundary, :provider, :root, :timeout, :max_output
+
+      def initialize(boundary:, provider:, timeout:, max_output:)
+        @boundary   = boundary
+        @provider   = provider
+        @root       = boundary.root
+        @timeout    = timeout
+        @max_output = max_output
+      end
+
+      # --- FS boundary (host-side, always on) ---
+      def resolve(path, for_write: false) = @boundary.resolve(path, for_write: for_write)
+      def inside?(abs) = @boundary.inside?(abs)
+      def relative(abs) = @boundary.relative(abs)
+
+      # --- command exec (via the provider) -> Result ---
+      def exec(command, timeout: @timeout, max_output: @max_output)
+        @provider.exec(command, root: @root, timeout: timeout, max_output: max_output)
+      end
+
+      def to_s = "Sandbox(#{@provider}, root=#{@root})"
+    end
+  end
+end

data/lib/insika/schema_guard.rb

@@ -0,0 +1,147 @@
+# frozen_string_literal: true
+
+module Insika
+  # Checks a tool call's ARGUMENTS against the tool's JSON Schema, at call time.
+  # `violation` returns nil (fine) or ONE message describing what is wrong —
+  # the same idiom as EgressGuard, and consumed the same way: DataDefinedTool turns
+  # it into `{ error: … }` for the model, so a malformed call is a correctable
+  # answer instead of a request that goes out shaped wrong.
+  #
+  # Why this exists: the schema declares the contract, but nothing used to hold the
+  # model to it. A call carrying `["arroz"]` where the schema says
+  # `[{query, filters}]` was interpolated into the body as-is, the backend answered
+  # 200, and the wrong results came back with no error anywhere. Validating here
+  # closes that loop *and* names the fix in the message the model reads next.
+  #
+  # Scope: the safe subset ToolDefinition already validates
+  # (object/array/string/number/integer/boolean + enum + minItems/maxItems). Only what
+  # the schema DECLARES is checked; undeclared keys pass (providers add nothing, and
+  # `additionalProperties` is a tool author's business, not ours).
+  #
+  # NEVER coerces. The value the model sent is what reaches the request — the guard
+  # only decides whether the call may proceed, so turning it on cannot change the
+  # bytes of a call that was already correct.
+  module SchemaGuard
+    # A scalar the schema calls a number/integer/boolean may arrive as its string
+    # form ("2", "true") — providers do that, it is lossless, and rejecting it would
+    # break working tools for no gain. Structure (object/array) is NEVER lenient.
+    NUMERIC_RE = /\A-?\d+(?:\.\d+)?\z/
+    INTEGER_RE = /\A-?\d+\z/
+    BOOLEAN_STRINGS = %w[true false].freeze
+    MAX_REPORTED = 5
+
+    module_function
+
+    # schema: canonical JSON Schema (ToolDefinition#parameters). args: the model's
+    # kwargs (symbol keys). -> nil | String.
+    def violation(schema, args)
+      return nil unless schema.is_a?(Hash)
+
+      values = Insika::Coercion.deep_stringify(args || {})
+      missing = missing_top_level(schema, values)
+      return "missing required parameter(s): #{missing.join(', ')}" unless missing.empty?
+
+      problems = []
+      (schema["properties"] || {}).each do |pname, pschema|
+        value = values[pname.to_s]
+        next if value.nil?
+
+        problems.concat(check(value, pschema, pname.to_s))
+        break if problems.length >= MAX_REPORTED
+      end
+      return nil if problems.empty?
+
+      "invalid arguments: #{problems.first(MAX_REPORTED).join('; ')}"
+    end
+
+    # Top-level `required` uses PRESENCE (an empty string is missing), because these
+    # values feed `{{placeholder}}` interpolation — an empty one produces a silently
+    # broken URL/body. Nested `required` uses JSON Schema semantics (key present),
+    # where "" can be a legitimate value.
+    def missing_top_level(schema, values)
+      Array(schema["required"]).map(&:to_s).reject { |n| Insika::Coercion.present?(values[n]) }
+    end
+
+    # -> [String] problems found at/below `path`.
+    def check(value, schema, path)
+      return [] unless schema.is_a?(Hash)
+
+      case schema["type"].to_s
+      when "object" then check_object(value, schema, path)
+      when "array" then check_array(value, schema, path)
+      else check_scalar(value, schema, path)
+      end
+    end
+
+    def check_object(value, schema, path)
+      return ["#{path}: expected an object, got #{kind(value)}"] unless value.is_a?(Hash)
+
+      props = schema["properties"] || {}
+      missing = Array(schema["required"]).map(&:to_s).reject { |k| value.key?(k) }
+      problems = missing.map { |k| "#{path}.#{k}: missing (required)" }
+
+      props.each do |pname, pschema|
+        child = value[pname.to_s]
+        next if child.nil?
+
+        problems.concat(check(child, pschema, "#{path}.#{pname}"))
+      end
+      problems
+    end
+
+    def check_array(value, schema, path)
+      return ["#{path}: expected a list, got #{kind(value)}"] unless value.is_a?(Array)
+
+      problems = size_problems(value, schema, path)
+      problems + value.each_with_index.flat_map { |item, i| check(item, schema["items"], "#{path}[#{i}]") }
+    end
+
+    # minItems/maxItems are the only cardinality the authors actually write (a search
+    # that takes "1 or more pairs"), and an empty list is exactly the call that reads as
+    # success and returns nothing.
+    def size_problems(value, schema, path)
+      min = schema["minItems"]
+      max = schema["maxItems"]
+      problems = []
+      problems << "#{path}: needs at least #{min} item(s), got #{value.length}" if min.is_a?(Numeric) && value.length < min
+      problems << "#{path}: accepts at most #{max} item(s), got #{value.length}" if max.is_a?(Numeric) && value.length > max
+      problems
+    end
+
+    def check_scalar(value, schema, path)
+      type = schema["type"].to_s
+      return ["#{path}: expected #{type}, got #{kind(value)}"] unless scalar_ok?(value, type)
+
+      enum = schema["enum"]
+      return [] unless enum.is_a?(Array) && !enum.empty?
+      return [] if enum.map(&:to_s).include?(value.to_s)
+
+      ["#{path}: #{value.to_s.inspect} is not one of #{enum.map(&:to_s).join('/')}"]
+    end
+
+    def scalar_ok?(value, type)
+      return false if value.is_a?(Hash) || value.is_a?(Array)
+
+      case type
+      when "string" then true                       # any scalar stringifies losslessly
+      when "number" then value.is_a?(Numeric) || NUMERIC_RE.match?(value.to_s)
+      when "integer" then value.is_a?(Integer) || INTEGER_RE.match?(value.to_s)
+      when "boolean" then [true, false].include?(value) || BOOLEAN_STRINGS.include?(value.to_s)
+      else true                                     # unknown type: not ours to police
+      end
+    end
+
+    # Name the shape the way a model reads it, not the way Ruby does.
+    def kind(value)
+      case value
+      when Hash then "an object"
+      when Array then "a list"
+      when String then "a string"
+      when Numeric then "a number"
+      when true, false then "a boolean"
+      when nil then "nothing"
+      else value.class.name.downcase
+      end
+    end
+  end
+end

data/lib/insika/secret_masking.rb

@@ -0,0 +1,34 @@
+# frozen_string_literal: true
+
+module Insika
+  # Secret masking on the UI<->Store round-trip. OpenClaw
+  # convention: a secret NEVER comes back to the screen in plaintext — it becomes
+  # the sentinel `__OCULTO__`. On save, the sentinel coming back means "keep what
+  # was already there"; a new string replaces it; `""` clears it. Shared by
+  # llm_providers (api keys) and, in the future, MCP instances (credentials).
+  module SecretMasking
+    SENTINEL = "__OCULTO__"
+
+    module_function
+
+    # Value to DISPLAY: present -> sentinel (never the plaintext); absent -> nil.
+    def mask(value)
+      present?(value) ? SENTINEL : nil
+    end
+
+    # Value to PERSIST given what the form sent (`incoming`) and what already
+    # existed (`existing`):
+    #   - not sent (nil) ............ preserves `existing`
+    #   - sentinel `__OCULTO__` ..... preserves `existing`
+    #   - "" (empty) ................ clears (nil)
+    #   - new string ................ replaces
+    def reconcile(incoming, existing)
+      return existing if incoming.nil? || incoming == SENTINEL
+
+      s = incoming.to_s
+      s.empty? ? nil : s
+    end
+
+    def present?(value) = Insika::Coercion.present?(value)
+  end
+end

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

@@ -0,0 +1,27 @@
+# frozen_string_literal: true
+
+module Insika
+  module Server
+    module A2A
+      # A2A AgentCard: discovery for the exposed agent. One agent
+      # per deployment; HONEST capabilities (streaming/push false in this slice).
+      module AgentCard
+        def self.build(agent:, base_url:, skills: [], version: "0.1.0")
+          {
+            name: agent.id,
+            description: agent.base_prompt.to_s[0, 280],
+            url: "#{base_url}/a2a",
+            version: version,
+            protocolVersion: "0.2.5", # A2A wire — to confirm
+            capabilities: { streaming: false, pushNotifications: false, stateTransitionHistory: false },
+            defaultInputModes: ["text/plain"],
+            defaultOutputModes: ["text/plain"],
+            skills: Array(skills).map do |s|
+              { id: s.name, name: s.name, description: s.description, tags: [] }
+            end
+          }
+        end
+      end
+    end
+  end
+end

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