insika 0.0.1 → 0.1.0

data/lib/insika/tool_manifest.rb

@@ -0,0 +1,218 @@
+# frozen_string_literal: true
+
+module Insika
+  # Tool manifest (Phase 7, Step B): the BATCH, DATA-driven, industry-STANDARD
+  # (JSON Schema) form of the data-tools. A `defaults` (common binding:
+  # base_url/path_template/method/headers/secret_headers/response) + a list of
+  # `tools`. Each tool is normalized — inheriting the defaults, applying the envelope
+  # adapter (OpenAI/MCP/raw) and resolving `endpoint`→url + `{{secret.*}}`/
+  # `{{env.*}}` — into a ToolDefinition Hash consumable by the ToolStore.
+  #
+  # GENERIC (NF1): nothing here mentions achei/openclaw — the manifest IS the contract. It
+  # only NORMALIZES/RESOLVES; the final validation (method/url/types, model placeholders
+  # `{{param}}`/turn `{{ctx.*}}`, safe subset of JSON Schema) belongs to
+  # ToolDefinition (single source). The batch upsert + hot reload belongs to the
+  # :import_tools Command (which injects the secret/env resolvers).
+  #
+  # Two placeholder classes by resolution MOMENT:
+  #   - `{{param}}`/`{{ctx.*}}` : resolved AT THE TURN (by DataDefinedTool) —
+  #     they stay INTACT here; ToolDefinition validates them.
+  #   - `{{secret.*}}`/`{{env.*}}` : resolved AT INGESTION (here) — from the deployment,
+  #     never from the manifest (D6/R3). `{{env.*}}` is non-secret config (any
+  #     template); `{{secret.*}}` is a credential and is ONLY allowed in a header
+  #     declared in `secret_headers`, with value === `{{secret.X}}` (nothing literal,
+  #     nothing outside a header — otherwise the secret would leak without masking).
+  #
+  # Interface envelope (what the model sees), by adapter (D3):
+  #   - `parameters` (raw JSON Schema), OR
+  #   - `{ "function": { name, description, parameters } }` (OpenAI/Anthropic), OR
+  #   - `{ "inputSchema": {...} }` (MCP).
+  ToolManifest = Data.define(:version, :defaults, :tools)
+
+  # Reopens the class (constants inside a Data.define block land in the wrong LEXICAL
+  # scope — same pattern as the sibling ToolDefinition).
+  class ToolManifest
+    ENV_PREFIX = "env."
+    SECRET_PREFIX = "secret."
+    private_constant :ENV_PREFIX, :SECRET_PREFIX
+
+    # Raw Hash (string|symbol keys) -> ToolManifest. Validates only the top-level
+    # STRUCTURE (version/defaults/tools); each tool's content is validated during
+    # normalization (per-tool, isolable by the Command — R4). Raises ValidationError.
+    def self.from_h(hash)
+      h = stringify(hash || {})
+      version = h.fetch("version", 1)
+      defaults = h.fetch("defaults", {}) || {}
+      tools = h.fetch("tools", []) || []
+      raise Insika::ValidationError, "manifest: 'defaults' must be an object" unless defaults.is_a?(Hash)
+      raise Insika::ValidationError, "manifest: 'tools' must be a list" unless tools.is_a?(Array)
+
+      new(version: version, defaults: defaults, tools: tools)
+    end
+
+    # -> [ { ToolDefinition hash } ] with inherited defaults, normalized envelopes,
+    # resolved endpoint→url and resolved secret/env. Raises on the FIRST malformed
+    # tool — use #definition_for per-tool to isolate partial failure (R4).
+    def tool_definitions(secrets:, env:)
+      tools.map { |t| definition_for(t, secrets: secrets, env: env) }
+    end
+
+    # Normalizes ONE raw tool -> ToolDefinition Hash. Raises ValidationError
+    # (invalid envelope, missing endpoint/url, secret/env not configured, R3).
+    def definition_for(raw_tool, secrets:, env:)
+      t = self.class.stringify(raw_tool || {})
+      raise Insika::ValidationError, "tool must be an object" unless t.is_a?(Hash)
+
+      interface = extract_interface(t)
+      binding = build_binding(t, secrets, env)
+
+      {
+        "name" => interface[:name], "description" => interface[:description],
+        "parameters" => interface[:parameters],
+        "request" => binding[:request],
+        "response" => binding[:response],
+        "secret_headers" => binding[:secret_headers],
+        "side_effect" => t["side_effect"],
+        "group" => t["group"] || defaults["group"],       # Phase 7/D4/F5 (Step C):
+        "tags" => (Array(defaults["tags"]) | Array(t["tags"])), # inherited default; tags unioned
+        # Per-tool only: "this result ends the turn" is a property of THIS backend's
+        # response, never something a manifest default should hand to its siblings.
+        "halt_when" => t["halt_when"]
+      }.compact
+    end
+
+    private
+
+    # Envelope adapter (D3): extracts the INTERFACE (name/description/parameters) from
+    # any standard form. name/description fall back to the tool's top level when the
+    # envelope does not carry them.
+    def extract_interface(t)
+      fn = t["function"]
+      if fn.is_a?(Hash)                                   # OpenAI/Anthropic function tool
+        { name: fn["name"] || t["name"], description: fn["description"] || t["description"],
+          parameters: fn["parameters"] }
+      elsif t.key?("inputSchema")                         # MCP tool
+        { name: t["name"], description: t["description"], parameters: t["inputSchema"] }
+      else                                               # raw: parameters is JSON Schema
+        { name: t["name"], description: t["description"], parameters: t["parameters"] }
+      end
+    end
+
+    # Builds the binding (request/response/secret_headers) inheriting defaults, with the
+    # tool winning. Resolves endpoint→url, secret (only in secret headers) and env.
+    def build_binding(t, secrets, env)
+      method = (t["method"] || defaults["method"] || "GET").to_s.upcase
+      headers = merge_maps(defaults["headers"], t["headers"])
+      query = merge_maps(defaults["query"], t["query"])
+      body = t.key?("body") ? t["body"] : defaults["body"]
+      secret_headers = (Array(defaults["secret_headers"]) | Array(t["secret_headers"])).map(&:to_s)
+      response = t["response"] || defaults["response"] || { "extract" => "body_raw" }
+
+      url = resolve_url(t, env)
+      headers = resolve_headers(headers, secret_headers, secrets, env)
+      query = query.transform_values { |v| resolve_env(v, env) }
+      body = body.nil? ? nil : resolve_env(body, env)
+      guard_no_stray_secrets!(url: url, headers: headers, secret_headers: secret_headers, query: query, body: body)
+
+      { request: { "method" => method, "url" => url, "headers" => headers,
+                   "query" => query, "body" => body }.compact,
+        response: response, secret_headers: secret_headers }
+    end
+
+    # explicit tool url OR base_url + path_template({endpoint}). The `endpoint` is
+    # DATA (never inferred from the name — R6): it resolves name↔slug remaps. `{endpoint}`
+    # is a manifest substitution (single key), distinct from the turn's `{{param}}`.
+    def resolve_url(t, env)
+      if self.class.presence(t["url"])
+        return resolve_env(t["url"], env)
+      end
+
+      base = self.class.presence(defaults["base_url"]) ||
+             (raise Insika::ValidationError, "tool '#{t['name']}' has no url and manifest has no defaults.base_url")
+      path = self.class.presence(defaults["path_template"]) ||
+             (raise Insika::ValidationError, "tool '#{t['name']}' has no url and manifest has no defaults.path_template")
+      endpoint = self.class.presence(t["endpoint"]) ||
+                 (raise Insika::ValidationError, "tool '#{t['name']}' has no 'endpoint' (never inferred from the name — R6)")
+
+      resolve_env(base.to_s + path.to_s.gsub("{endpoint}", endpoint.to_s), env)
+    end
+
+    # Resolves headers: a SECRET header (name in secret_headers) MUST contain a
+    # {{secret.*}} reference (never literal — R3; a prefix like "Bearer " is ok) and
+    # resolves secret+env; the rest resolve only {{env.*}}.
+    def resolve_headers(headers, secret_headers, secrets, env)
+      headers.each_with_object({}) do |(name, value), acc|
+        acc[name] =
+          if secret_headers.include?(name)
+            resolve_secret_header(name, value, secrets, env)
+          else
+            resolve_env(value, env)
+          end
+      end
+    end
+
+    def resolve_secret_header(name, value, secrets, env)
+      unless value.to_s.match?(/\{\{\s*#{SECRET_PREFIX}/)
+        raise Insika::ValidationError,
+              "secret_header '#{name}' must reference {{secret.<name>}} (never a literal — R3)"
+      end
+
+      substitute(value, secrets: secrets, env: env)
+    end
+
+    # Substitutes {{env.X}} with the deployment value; leaves the other placeholders
+    # ({{param}}/{{ctx.*}}/{{secret.*}}) INTACT. Used on NON-secret fields — a
+    # remaining {{secret.*}} is blocked by #guard_no_stray_secrets! (it would leak).
+    def resolve_env(template, env)
+      substitute(template, secrets: nil, env: env)
+    end
+
+    # Ingestion interpolator: always resolves {{env.X}}; resolves {{secret.X}} only
+    # when `secrets` was passed (secret fields). TURN placeholders
+    # ({{param}}/{{ctx.*}}) stay INTACT. Missing secret/env -> ValidationError.
+    def substitute(template, secrets:, env:)
+      template.to_s.gsub(Insika::ToolDefinition::PLACEHOLDER_RE) do
+        ref = Regexp.last_match(1)
+        if secrets && ref.start_with?(SECRET_PREFIX)
+          fetch!(secrets, ref.delete_prefix(SECRET_PREFIX), "secret")
+        elsif ref.start_with?(ENV_PREFIX)
+          fetch!(env, ref.delete_prefix(ENV_PREFIX), "env")
+        else
+          Regexp.last_match(0) # preserves {{param}}/{{ctx.*}} (and {{secret.*}} outside a secret header)
+        end
+      end
+    end
+
+    def fetch!(resolver, key, kind)
+      val = resolver[key]
+      raise Insika::ValidationError, "#{kind} '#{key}' not configured in the deployment" if blank?(val)
+
+      val.to_s
+    end
+
+    # A secret outside a secret-header would leak (it is not masked): reject {{secret.*}}
+    # in url/query/body/non-secret header after env resolution.
+    def guard_no_stray_secrets!(url:, headers:, secret_headers:, query:, body:)
+      non_secret = headers.reject { |name, _| secret_headers.include?(name) }.values
+      strings = [url, *non_secret, *query.values, body].compact
+      stray = strings.flat_map { |s| s.to_s.scan(Insika::ToolDefinition::PLACEHOLDER_RE).flatten }
+                     .select { |r| r.start_with?(SECRET_PREFIX) }.uniq
+      return if stray.empty?
+
+      raise Insika::ValidationError,
+            "{{secret.*}} is only allowed in secret_headers (would leak without masking): #{stray.join(', ')}"
+    end
+
+    def merge_maps(base, override)
+      (self.class.stringify(base || {})).merge(self.class.stringify(override || {}))
+    end
+
+    def blank?(v) = Insika::Coercion.blank?(v)
+
+    # Deep string keys (the wire may arrive symbolized; the nested JSON Schema
+    # must stay string-keyed — same as ToolDefinition's canonicalization).
+    def self.stringify(obj) = Insika::Coercion.deep_stringify(obj)
+
+    def self.presence(str) = Insika::Coercion.presence(str)
+  end
+end

data/lib/insika/tool_registry.rb

@@ -0,0 +1,21 @@
+# frozen_string_literal: true
+
+module Insika
+  # Tool registry. Inherits from the generic one; `optional`/`side_effect`
+  # live in the metadata (defaults false). `side_effect: true` marks a
+  # non-idempotent tool — the checkpoint mechanism consumes it via `side_effect?`.
+  class ToolRegistry < Registry
+    # Legacy compat: `optional:`/`plugin:` are still accepted; `side_effect:` is
+    # new. Everything is normalized into the metadata (defaults false).
+    def register(name, callable = nil, optional: false, side_effect: false, plugin: nil, **extra, &block)
+      super(name, callable, plugin: plugin,
+                            optional: optional, side_effect: side_effect, **extra, &block)
+    end
+
+    # -> bool; consumed by ToolEnvelope. Unknown tool = false.
+    def side_effect?(name)
+      entry = entries.find { |e| e.name == name.to_s }
+      entry ? !!entry.metadata[:side_effect] : false
+    end
+  end
+end

data/lib/insika/tool_store.rb

@@ -0,0 +1,135 @@
+# frozen_string_literal: true
+
+require "time"
+
+module Insika
+  # DATA-DEFINED tools authored at runtime. One record per tool in the ConfigStore
+  # (scope "tools"), keyed by name. It stores the whole ToolDefinition, versions it
+  # (like SkillStore/AgentFileStore) and MASKS the credential headers (just as
+  # McpStore masks the env): headers whose name is in `secret_headers` never
+  # leave in plaintext to the UI — they become the sentinel `__OCULTO__`. Only `get_raw`/
+  # `all_raw` (consumed by DataDefinedTool/overlay, never the screen) return the
+  # real values. Phase 5, Step A.
+  #
+  # Record in the ConfigStore:
+  #   { "definition" => { ...ToolDefinition#to_h... },
+  #     "updated_at" => iso8601,
+  #     "history"    => [ { "definition" =>, "at" => }, ... ] }
+  class ToolStore
+    SCOPE = "tools"
+    HISTORY_MAX = 20
+
+    def initialize(config_store:)
+      @cs = config_store
+    end
+
+    # -> MASKED ToolDefinition Hash (secret headers with sentinel) | nil.
+    def get(name)
+      d = raw_definition(name)
+      d && mask_definition(d)
+    end
+
+    # -> ToolDefinition Hash with REAL headers | nil. Internal use (tool/overlay).
+    def get_raw(name) = raw_definition(name)
+
+    # -> [String] names, lexicographic order.
+    def names = @cs.keys(SCOPE)
+
+    # -> [Hash] MASKED definitions (for the UI).
+    def all
+      names.filter_map { |n| get(n) }
+    end
+
+    # -> [Hash] definitions with REAL headers (for the overlay/registry). Never to the screen.
+    def all_raw
+      names.filter_map { |n| raw_definition(n) }
+    end
+
+    # Writes (upsert). `attrs` is a ToolDefinition Hash (the UI may send secret
+    # headers as sentinel: preserves what was stored). create_only refuses to overwrite.
+    # Validates via ToolDefinition.from_h. -> MASKED definition Hash.
+    def write(attrs, create_only: false)
+      definition = Insika::ToolDefinition.from_h(attrs)   # validates (raises ValidationError)
+      name = definition.name
+      existing = @cs.get(SCOPE, name)
+      raise Insika::ValidationError, "tool '#{name}' already exists" if create_only && existing
+
+      final = definition.to_h
+      final["request"]["headers"] = reconcile_secret_headers(
+        final["request"]["headers"], definition.secret_headers,
+        existing&.dig("definition", "request", "headers")
+      )
+
+      rec = build_record(final, existing)
+      @cs.put(SCOPE, name, rec)
+      mask_definition(final)
+    end
+
+    # -> bool (did it exist?).
+    def delete(name) = @cs.delete(SCOPE, name.to_s)
+
+    # -> [ { "definition" => MASKED, "at" => } ] most recent first.
+    def versions(name)
+      (record(name)&.fetch("history", []) || []).map do |h|
+        { "definition" => mask_definition(h["definition"]), "at" => h["at"] }
+      end
+    end
+
+    # Restores version `index` as the current definition (new write, versions the current).
+    # -> MASKED definition Hash.
+    def restore(name, index)
+      rec = record(name)
+      raise Insika::NotFoundError, "tool '#{name}' not found" unless rec
+
+      hist = rec.fetch("history", [])
+      i = Integer(index)
+      raise Insika::ValidationError, "version #{index} does not exist" if i.negative? || i >= hist.length
+
+      # The historical version stores REAL headers -> rewrite directly (bypasses the
+      # input masking; write only re-validates the structure).
+      write(hist[i]["definition"])
+    end
+
+    private
+
+    def record(name) = @cs.get(SCOPE, name.to_s)
+
+    def raw_definition(name) = record(name)&.fetch("definition", nil)
+
+    def build_record(definition, current)
+      history = current ? current.fetch("history", []) : []
+      if current
+        history = [{ "definition" => current["definition"], "at" => current["updated_at"] }] + history
+        history = history.first(HISTORY_MAX)
+      end
+      { "definition" => definition, "updated_at" => Time.now.utc.iso8601, "history" => history }
+    end
+
+    # Each header in secret_headers becomes a sentinel; the rest pass through intact.
+    def mask_definition(definition)
+      secret = definition["secret_headers"] || []
+      return definition if secret.empty?
+
+      headers = (definition.dig("request", "headers") || {}).each_with_object({}) do |(k, v), acc|
+        acc[k] = secret.include?(k) ? SecretMasking.mask(v) : v
+      end
+      definition.merge("request" => definition["request"].merge("headers" => headers))
+    end
+
+    # Reconciles ONLY the secret headers against what was stored: sentinel preserves,
+    # a new string replaces, "" clears (removes the key). Non-secret pass through intact.
+    def reconcile_secret_headers(incoming, secret_names, existing)
+      old = existing || {}
+      secret_names.each_with_object(incoming.dup) do |hname, acc|
+        next unless acc.key?(hname)
+
+        value = SecretMasking.reconcile(acc[hname], old[hname])
+        if value.nil? || value.to_s.empty?
+          acc.delete(hname)
+        else
+          acc[hname] = value
+        end
+      end
+    end
+  end
+end

data/lib/insika/tool_trace_store.rb

@@ -0,0 +1,92 @@
+# frozen_string_literal: true
+
+require "json"
+
+module Insika
+  # Per-session TOOL-CALL trace, for debugging in the Studio (FOLLOWUP §3.1). One
+  # record per session in the raw backend (scope "tool_traces") — RUNTIME data, next
+  # to sessions/tasks, NOT config (hence the raw `store:`, like SessionStore,
+  # not the ConfigStore). A capped LIST of entries; ToolEnvelope writes one
+  # per call (name + model args + result + status + ms). Serves
+  # `/studio/sessions/:id`.
+  #
+  # SECURITY lives HERE (the store owns it): the screen is for the operator, but the
+  # args/response may carry PII/credentials. Every write goes through mask (values of
+  # sensitive keys become a sentinel) + clip (truncates large fields). The ephemeral
+  # `data_tool_call` event (name+status, 0 leakage) still goes to the live cards;
+  # THIS is the durable, richer record, behind the Studio login.
+  class ToolTraceStore
+    SCOPE = "tool_traces"
+    MAX_PER_SESSION = 200                # tail per session (avoids growing without bound)
+    MAX_FIELD_CHARS = 2_000              # cap per args/result field
+    SECRET_KEY_RE = /token|secret|authorization|password|passwd|api[-_]?key|bearer|cookie/i
+
+    def initialize(store:)
+      @store = store
+    end
+
+    # Writes a (sanitized) entry into the session. Missing session_id -> no-op.
+    # ToolEnvelope already guards, but so does this: the trace NEVER breaks the turn.
+    def record(session_id:, entry:)
+      sid = session_id.to_s
+      return if sid.empty?
+
+      list = (@store.get(SCOPE, sid) || []) + [sanitize(entry)]
+      @store.set(SCOPE, sid, list.last(MAX_PER_SESSION))
+    rescue StandardError
+      nil
+    end
+
+    # -> [Hash] session entries in chronological order. [] if none.
+    def for_session(session_id) = @store.get(SCOPE, session_id.to_s) || []
+
+    # Discards a session's trace (cleanup). -> bool (did it exist?).
+    def clear(session_id) = @store.delete(SCOPE, session_id.to_s)
+
+    private
+
+    def sanitize(entry)
+      e = stringify_keys(entry)
+      {
+        "turn" => e["turn"], "tool" => e["tool"].to_s, "call_id" => e["call_id"].to_s,
+        "ok" => ok?(e["result"]),
+        "args" => clip(mask(e["args"])), "result" => clip(mask(e["result"])),
+        "ms" => e["ms"], "at" => e["at"].to_s
+      }
+    end
+
+    # Conventional tool error = Hash with key "error"/:error (everything else is ok).
+    def ok?(result)
+      !(result.is_a?(Hash) && (result.key?("error") || result.key?(:error)))
+    end
+
+    # Masks values of sensitive keys (recursive); the rest pass through intact.
+    def mask(obj)
+      case obj
+      when Hash
+        obj.each_with_object({}) do |(k, v), acc|
+          acc[k.to_s] = SECRET_KEY_RE.match?(k.to_s) ? SecretMasking::SENTINEL : mask(v)
+        end
+      when Array then obj.map { |v| mask(v) }
+      else obj
+      end
+    end
+
+    # -> Readable, capped String (JSON when structured). Truncates by CHARACTER
+    # (not byte — avoids cutting UTF-8 mid-sequence).
+    def clip(obj)
+      s = obj.is_a?(String) ? obj : safe_json(obj)
+      s.length > MAX_FIELD_CHARS ? "#{s[0, MAX_FIELD_CHARS]}…(truncado)" : s
+    end
+
+    def safe_json(obj)
+      JSON.generate(obj)
+    rescue StandardError
+      obj.inspect
+    end
+
+    def stringify_keys(hash)
+      (hash || {}).each_with_object({}) { |(k, v), acc| acc[k.to_s] = v }
+    end
+  end
+end

data/lib/insika/tools/a2a_remote.rb

@@ -0,0 +1,48 @@
+# frozen_string_literal: true
+
+require "ruby_llm"
+
+module Insika
+  module Tools
+    # Delegates to a remote A2A agent. A NORMAL Tool Registry tool — the
+    # agent's allowlist governs who may delegate. Lazy require of the gem: it does NOT
+    # enter lib/insika.rb; it is loaded in the registration block (wiring) on the 1st
+    # instance. One instance per remote agent (its own name/description).
+    class A2ARemote < RubyLLM::Tool
+      param :message, desc: "The message/task for the remote agent"
+
+      def initialize(client:, url:, tool_name:, description:, event_stream: nil)
+        @client = client
+        @url = url
+        @tool_name = tool_name
+        @description = description
+        @event_stream = event_stream
+        super()
+      end
+
+      # name/description per INSTANCE (RubyLLM derives them from the class; we override —
+      # otherwise the model would see "insika--tools--a2a_remote" for every remote).
+      def name = @tool_name
+      def description = @description
+
+      def execute(message:)
+        result = @client.call(@url, message.to_s)
+        emit(result)
+        result[:error] ? { error: result[:error] } : result[:text]
+      end
+
+      private
+
+      # :a2a_call without task correlation: registry tools do not receive the
+      # TurnState -> meta {} (like the Builder's :provider_warning). The :tool_call
+      # from wire_callbacks already correlates the call itself.
+      def emit(result)
+        @event_stream&.emit(Insika::Event.new(
+                              type: :a2a_call,
+                              data: { agent: @tool_name, remote_task_id: result[:id], state: result[:state] },
+                              meta: {}
+                            ))
+      end
+    end
+  end
+end

data/lib/insika/tools/agent_enum.rb

@@ -0,0 +1,68 @@
+# frozen_string_literal: true
+
+module Insika
+  module Tools
+    # Names the parent's subagent allowlist INSIDE the delegation tools' schema.
+    #
+    # The allowlist is per-turn data (`profile.subagents`), while a RubyLLM tool's
+    # schema is class-level, so the enum has to be injected per instance. Without
+    # it the model is told only that `agent` "must be one this agent may spawn" and
+    # is left to guess the ids; with it, the valid values are part of the contract
+    # the provider sees.
+    #
+    # Tolerant by construction: JSON-schema hashes reach us with symbol keys (the
+    # class-level `params(...)` form) or string keys (anything that round-tripped
+    # through JSON), and a shape we do not recognize is returned UNTOUCHED — a
+    # schema we failed to annotate still works, one we corrupted would break every
+    # delegation.
+    module AgentEnum
+      module_function
+
+      # schema: the tool's JSON schema · allowed: [String] · path: the property
+      # chain leading to the `agent` property, e.g. %i[agent] or %i[tasks agent].
+      # -> a COPY with `enum` set, or the original when there is nothing to do.
+      def inject(schema, allowed, path:)
+        return schema if schema.nil? || Array(allowed).empty?
+
+        copy = deep_dup(schema)
+        target = resolve(copy, path)
+        return schema if target.nil?
+
+        target[key_for(target, :enum)] = Array(allowed).map(&:to_s)
+        copy
+      end
+
+      # Walks `properties` (and `items` for an array) down to the named property.
+      def resolve(node, path)
+        path.reduce(node) do |current, segment|
+          props = fetch(current, :properties)
+          props = fetch(fetch(current, :items) || {}, :properties) if props.nil?
+          prop = props && (props[segment] || props[segment.to_s])
+          return nil unless prop.is_a?(Hash)
+
+          prop
+        end
+      end
+
+      def fetch(node, key)
+        return nil unless node.is_a?(Hash)
+
+        node[key] || node[key.to_s]
+      end
+
+      # Keep the hash's own key convention instead of mixing symbols into a
+      # string-keyed schema.
+      def key_for(hash, key)
+        hash.keys.any? { |k| k.is_a?(String) } ? key.to_s : key
+      end
+
+      def deep_dup(value)
+        case value
+        when Hash  then value.each_with_object({}) { |(k, v), acc| acc[k] = deep_dup(v) }
+        when Array then value.map { |v| deep_dup(v) }
+        else value
+        end
+      end
+    end
+  end
+end

data/lib/insika/tools/concurrency.rb

@@ -0,0 +1,54 @@
+# frozen_string_literal: true
+
+require "async"
+require "async/semaphore"
+
+module Insika
+  module Tools
+    # Fan-out INSIDE a single tool (RFC-0010 §B1): when a tool must gather N
+    # independent I/O calls (stock + price + promo + delivery) into ONE result,
+    # `gather` runs them CONCURRENTLY on the turn's reactor and returns their values
+    # IN ORDER. Because a data-tool spends its time on the HTTP wait, those waits
+    # overlap → wall-clock ≈ the slowest call, not the sum.
+    #
+    # This is the "aggregator tool" pattern: the model makes ONE tool call and the
+    # concurrency is an implementation detail of that tool — no change to the agent
+    # loop, no dependency on parallel tool execution (item 30). Use it in a custom
+    # Ruby tool's #execute:
+    #
+    #   def execute(store_id:)
+    #     stock, price, promo = Insika::Tools::Concurrency.gather(
+    #       -> { fetch_stock(store_id) },
+    #       -> { fetch_price(store_id) },
+    #       -> { fetch_promo(store_id) }
+    #     )
+    #     { stock:, price:, promo: }
+    #   end
+    #
+    # Bounded by `max` concurrent (default 8) to respect upstream rate limits. Runs
+    # correctly whether or not there is already a reactor (a tool runs inside the
+    # turn's Async fiber; `Sync` reuses it, and starts one otherwise for tests).
+    module Concurrency
+      DEFAULT_MAX = 8
+
+      module_function
+
+      # blocks: callables (procs/lambdas) or a block yielding an index. Returns an
+      # Array of results aligned to the input order. An exception in any block
+      # propagates (the caller decides how to degrade — this helper does not swallow).
+      def gather(*blocks, max: DEFAULT_MAX)
+        blocks = blocks.flatten
+        return [] if blocks.empty?
+
+        results = Array.new(blocks.size)
+        Sync do
+          semaphore = Async::Semaphore.new([max, blocks.size].min)
+          blocks.each_with_index.map do |blk, i|
+            semaphore.async { results[i] = blk.call }
+          end.each(&:wait)
+        end
+        results
+      end
+    end
+  end
+end