insika 0.0.1 → 0.2.0

data/lib/insika/safety/safe_responses.rb

@@ -0,0 +1,47 @@
+# frozen_string_literal: true
+
+module Insika
+  module Safety
+    # Safe reply for a blocked turn. A blocked turn NEVER returns a
+    # raw error nor silence — it completes gracefully with one of these.
+    #
+    # CONFIGURATION OVER CONVENTION: this is OSS across arbitrary businesses and
+    # languages, so the engine does NOT hard-bake tone. The built-in `DEFAULTS` are a
+    # deliberately NEUTRAL, business-agnostic fallback (pt-BR — the pilot's language;
+    # override for others). Each agent tailors its own voice via
+    # `guardrails.responses` (Safety::Config#responses). Resolution order:
+    #
+    #   agent[category] → agent["default"] → DEFAULTS[category] → DEFAULTS[:default]
+    #
+    # So a store that wants a warm brand voice, a different language, or a specific
+    # discount-scam reply just configures it — nothing here is a ceiling.
+    module SafeResponses
+      # Neutral, generic fallback. No brand, no vertical ("loja"/"produtos") baked in
+      # beyond what a generic assistant can say. Agents are expected to override.
+      DEFAULTS = {
+        injection: "Não consigo compartilhar minhas instruções internas ou " \
+                   "configurações. Como posso te ajudar de outra forma?",
+        sexual:    "Prefiro manter nossa conversa respeitosa e profissional. " \
+                   "Como posso te ajudar?",
+        abuse:     "Sinto muito pela experiência. Quero te ajudar — me conta o que " \
+                   "você precisa e eu sigo daqui, ou te encaminho para um atendente humano.",
+        escalate:  "Vou te encaminhar para um atendente humano que poderá te ajudar " \
+                   "melhor com isso. Um momento, por favor.",
+        default:   "Não consigo ajudar com esse pedido específico, mas estou à " \
+                   "disposição para o que mais você precisar."
+      }.freeze
+
+      module_function
+
+      # Safe reply for a category, honoring the agent's per-category / catch-all
+      # overrides first. `overrides` is Safety::Config#responses ({ "cat" => text }).
+      # Always returns a non-blank string.
+      def for(category, overrides: {})
+        cat = category&.to_s
+        ov = overrides || {}
+        ov[cat] || ov["default"] ||
+          DEFAULTS[cat&.to_sym] || DEFAULTS[:default]
+      end
+    end
+  end
+end

data/lib/insika/sandbox/boundary.rb

@@ -0,0 +1,93 @@
+# frozen_string_literal: true
+
+require "fileutils"
+
+module Insika
+  module Sandbox
+    # HARD filesystem boundary: confines every path a tool resolves to a single
+    # root directory. Each model/user supplied path is resolved and verified to
+    # live INSIDE the root BEFORE any IO happens. This is the FS half of the
+    # sandbox primitive — always on, independent of the exec provider (local or
+    # docker) and of the engine's approval layer.
+    #
+    # Extracted VERBATIM from the insika-code prototype's `Workspace`
+    # and promoted to a core primitive. The two layers of defense:
+    #   1. `File.expand_path` normalizes `..` traversal; the expanded path must be
+    #      the root itself or a descendant of it (string containment on a
+    #      separator boundary, so `/ws-evil` does not pass for root `/ws`).
+    #   2. symlink guard: the final path component may never be a symlink (an
+    #      lstat check that also catches a BROKEN symlink whose target does not
+    #      yet exist), and for an existing target (or, on writes, its parent dir)
+    #      the REAL path (`File.realpath`, which follows symlinks) must also be
+    #      contained — a symlink inside the sandbox pointing outside is rejected.
+    #
+    # A value object: immutable root, no IO of its own beyond the realpath checks.
+    class Boundary
+      # Raised on any attempt to touch a path outside the root. Tools rescue it
+      # and return a structured error to the model (never crash a turn).
+      Escape = Class.new(StandardError)
+
+      attr_reader :root
+
+      # root: the directory that bounds all operations. Must exist (a boundary
+      # rooted at a missing dir is a misconfiguration -> fail fast at boot).
+      def initialize(root)
+        @root = File.realpath(File.expand_path(root.to_s))
+      rescue Errno::ENOENT
+        raise Escape, "sandbox root does not exist: #{root}"
+      end
+
+      # Resolve a relative/absolute path to an absolute path GUARANTEED inside the
+      # root. Raises Escape on traversal/symlink escape or an empty path.
+      #   for_write: the target file may not exist yet, so the symlink guard is
+      #   applied to its PARENT directory instead of the file itself.
+      def resolve(path, for_write: false)
+        raise Escape, "empty path" if path.to_s.strip.empty?
+
+        abs = File.expand_path(path.to_s, @root)
+        contain!(abs)
+
+        # The final component is never allowed to be a symlink. On writes this is
+        # the crux of the boundary: `contain!` only checks the STRING, and the
+        # parent-dir realpath probe below only vets the parent — so without this a
+        # symlink under the root pointing outside would let `File.write` follow it
+        # and clobber a file outside the sandbox. `File.symlink?` is an lstat, so
+        # it also catches a BROKEN symlink (dangling target) that `File.exist?`
+        # would report as absent.
+        raise Escape, "path is a symlink" if File.symlink?(abs)
+
+        probe = for_write ? File.dirname(abs) : abs
+        contain!(File.realpath(probe)) if File.exist?(probe)
+        abs
+      end
+
+      # Boolean containment check for an ALREADY-absolute path (used by grep to
+      # skip glob results that resolve outside the root via a symlink). Never
+      # raises.
+      def inside?(abs)
+        real = File.exist?(abs) ? File.realpath(abs) : File.expand_path(abs)
+        real == @root || real.start_with?(@root + File::SEPARATOR)
+      rescue StandardError
+        false
+      end
+
+      # Path relative to the root, for display — never leaks absolute host paths
+      # back to the model. The root itself renders as ".".
+      def relative(abs)
+        return "." if abs == @root
+
+        abs.delete_prefix(@root + File::SEPARATOR)
+      end
+
+      private
+
+      def contain!(abs)
+        return if abs == @root || abs.start_with?(@root + File::SEPARATOR)
+
+        raise Escape, "path escapes sandbox root (#{relative_or_abs(abs)})"
+      end
+
+      def relative_or_abs(abs) = abs.start_with?(@root) ? relative(abs) : abs
+    end
+  end
+end

data/lib/insika/sandbox/docker.rb

@@ -0,0 +1,74 @@
+# frozen_string_literal: true
+
+require "securerandom"
+require_relative "runner"
+
+module Insika
+  module Sandbox
+    # Isolated exec provider: runs the command inside a throwaway Docker container
+    # (`docker run --rm`) with the sandbox root bind-mounted at a fixed workdir.
+    # This is the isolation boundary the `local` provider is NOT — a real target
+    # for UNTRUSTED shell execution.
+    #
+    # "Narrowest sandbox that supports the task": only the risky part — shell exec
+    # — is containerized. The FS tools (read/write/edit/grep) keep operating on
+    # the host path, confined by the `Boundary`; the container sees the SAME bytes
+    # through the bind mount, so a file the model writes is immediately visible to
+    # a subsequent `bash` call and vice-versa.
+    #
+    # Defaults are conservative: `--network none` (no egress from the container),
+    # a memory cap and a cpu cap, and a minimal image. All are overridable via the
+    # profile's `sandbox` config (config-over-code).
+    class Docker
+      DEFAULTS = {
+        "image" => "alpine:3.20",
+        "network" => "none",
+        "memory" => "512m",
+        "cpus" => "1.0",
+        "workdir" => "/workspace",
+        "shell" => "/bin/sh",
+        "docker_bin" => "docker"
+      }.freeze
+
+      def initialize(config = {})
+        cfg = DEFAULTS.merge(config.transform_keys(&:to_s).compact)
+        @image      = cfg["image"]
+        @network    = cfg["network"]
+        @memory     = cfg["memory"]
+        @cpus       = cfg["cpus"].to_s
+        @workdir    = cfg["workdir"]
+        @shell      = cfg["shell"]
+        @docker_bin = cfg["docker_bin"]
+      end
+
+      # PURE argv builder — unit-testable without Docker present. `--name` lets
+      # the timeout teardown `docker kill` the exact container (killing the client
+      # process alone does not stop it).
+      def argv(command, root:, name:)
+        [@docker_bin, "run", "--rm", "--name", name,
+         "--network", @network, "--memory", @memory, "--cpus", @cpus,
+         "--volume", "#{root}:#{@workdir}:rw", "--workdir", @workdir,
+         @image, @shell, "-c", command.to_s]
+      end
+
+      def exec(command, root:, timeout:, max_output:)
+        name = "harness-sbx-#{SecureRandom.hex(8)}"
+        Runner.run(argv(command, root: root, name: name),
+                   chdir: root, timeout: timeout, max_output: max_output,
+                   # On the wall-clock deadline, stop the container by name; the
+                   # `--rm` then removes it. Squelch output — this is teardown.
+                   kill: -> { system(@docker_bin, "kill", name, out: File::NULL, err: File::NULL) })
+      end
+
+      # Whether the Docker daemon is reachable. Used at boot to fail fast (or warn)
+      # instead of discovering it mid-turn.
+      def available?
+        system(@docker_bin, "version", out: File::NULL, err: File::NULL)
+      rescue StandardError
+        false
+      end
+
+      def to_s = "docker(#{@image}, network=#{@network})"
+    end
+  end
+end

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 (COMPETITIVE-ANALYSIS): 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