insika 0.0.1 → 0.1.0

data/lib/insika/tools/data_defined_tool.rb

@@ -0,0 +1,220 @@
+# frozen_string_literal: true
+
+require "ruby_llm"
+require "json"
+require "erb"
+
+module Insika
+  module Tools
+    # DATA-DEFINED tool: one class, N instances parameterized by a
+    # ToolDefinition (the same pattern as A2ARemote). It makes an HTTP call described
+    # in config — no Ruby code per tool. Since it inherits RubyLLM::Tool (pulls in the gem),
+    # it is NOT required in lib/insika.rb; the overlay loads it lazily at registration
+    # (Step B). Phase 5, Step A.
+    #
+    # Contract preserved by duck-typing: it overrides name/description/parameters/
+    # execute; RubyLLM's params_schema derives from #parameters automatically.
+    # execute NEVER raises — an error (missing param, blocked egress, HTTP, parse)
+    # becomes `{ error: }` to the model, like the other tools.
+    class DataDefinedTool < RubyLLM::Tool
+      def initialize(definition:, http:, egress: Insika::EgressGuard, egress_options: {},
+                     event_stream: nil, turn_context: {})
+        @definition = definition
+        @http = http
+        @egress = egress
+        @egress_options = egress_options
+        @event_stream = event_stream
+        @turn_context = symbolize_ctx(turn_context)
+        super()
+      end
+
+      # Turn context (Phase 6/D2/G3): the registry tool does NOT receive TurnState,
+      # so the Executor DEPOSITS the turn ids here, per-turn
+      # (chat/agent/tenant/store). They resolve {{ctx.*}} — SEPARATE from the model's
+      # {{param}} — to emit X-Chat-Id/X-Store-Id/X-Agent-Id. They come from the TURN, never from
+      # the model (R2). Reader for testing; the writer is the Executor's injection point.
+      attr_reader :turn_context
+
+      def turn_context=(ctx)
+        @turn_context = symbolize_ctx(ctx)
+      end
+
+      # name/description/parameters per INSTANCE (otherwise the model would see the name
+      # derived from the class for every data-tool).
+      def name = @definition.name
+      def description = @definition.description
+
+      # FULL (nested) JSON Schema straight into RubyLLM's params_schema — it is what
+      # the providers serialize (OpenAI/Anthropic/Gemini/Bedrock prefer
+      # params_schema; parameters is just a fallback). Provider-agnostic (Phase 7/F6) and
+      # the only form that expresses nesting (object/array/enum). Phase 7, Step A.
+      def params_schema = @definition.parameters
+
+      # FLAT top-level view for discovery (tool_search calls #parameters on the resolved
+      # tool). The real nested schema goes through #params_schema above.
+      def parameters
+        @parameters ||= @definition.top_level_params.each_with_object({}) do |p, acc|
+          sym = p[:name].to_sym
+          acc[sym] = RubyLLM::Parameter.new(sym, type: p[:type], desc: p[:description], required: p[:required])
+        end
+      end
+
+      # The args are checked against the tool's own JSON Schema BEFORE the request is
+      # built: a call the schema does not allow becomes `{ error: }` the model can act
+      # on, instead of a wrongly-shaped request that a backend answers 200 to.
+      def execute(**kwargs)
+        if (bad = Insika::SchemaGuard.violation(@definition.parameters, kwargs))
+          return { error: bad }
+        end
+
+        req = build_request(kwargs)
+        reason = @egress.violation(req[:url], **@egress_options)
+        return { error: "destination blocked: #{reason}" } if reason
+
+        result = @http.request(**req)
+        emit(result[:status])
+        payload = extract(result)
+        # The RESPONSE says the turn is over (`halt_when`): the backend already
+        # answered the customer, so letting the model comment would deliver the
+        # message twice. RubyLLM's Tool::Halt ends its loop right here — no second
+        # provider call, and the decision is the engine's, not a request in a prompt.
+        # Only on a 2xx: an error body that happens to carry the value is a failure,
+        # and a failure must reach the model.
+        if http_ok?(result) && @definition.halt?(result[:body])
+          # `say` (optional) travels WITH the halt so the Executor can publish it when
+          # the model wrote no lead-in. Wrapped only when there is one, so every tool
+          # that declares no `say` keeps producing exactly the payload it always did.
+          say = @definition.halt_say(result[:body])
+          return RubyLLM::Tool::Halt.new(say ? Insika::ToolDefinition.wrap_halt(payload, say) : payload)
+        end
+
+        payload
+      rescue StandardError => e
+        { error: "HTTP call failed: #{e.message}" }
+      end
+
+      private
+
+      # Interpolates the definition's templates with the model's args, escaping by
+      # context: url/query -> percent-encode; header -> strips CR/LF (anti-injection);
+      # body -> JSON escaping.
+      def build_request(kwargs)
+        r = @definition.request
+        url = interpolate(r[:url], kwargs, :url)
+        url = append_query(url, r[:query], kwargs)
+        headers = r[:headers].transform_values { |v| interpolate(v, kwargs, :header) }
+        body = r[:body] && interpolate(r[:body], kwargs, :body)
+        { method: r[:method], url: url, headers: headers, body: body, timeout: @definition.timeout }
+      end
+
+      def append_query(url, query, kwargs)
+        return url if query.nil? || query.empty?
+
+        pairs = query.map { |k, v| "#{ERB::Util.url_encode(k)}=#{interpolate(v, kwargs, :query)}" }
+        url + (url.include?("?") ? "&" : "?") + pairs.join("&")
+      end
+
+      def interpolate(template, kwargs, mode)
+        template.to_s.gsub(Insika::ToolDefinition::PLACEHOLDER_RE) do
+          encode(resolve(Regexp.last_match(1), kwargs), mode)
+        end
+      end
+
+      # ctx.* -> TURN context (deposited by the Executor); the rest -> MODEL args
+      # (kwargs). The split is the D2/R2 trust boundary: the model does
+      # not choose which chat/store the tool accesses.
+      def resolve(name, kwargs)
+        prefix = Insika::ToolDefinition::CTX_PREFIX
+        if name.start_with?(prefix)
+          @turn_context[name.delete_prefix(prefix).to_sym]
+        else
+          kwargs[name.to_sym]
+        end
+      end
+
+      def symbolize_ctx(ctx)
+        (ctx || {}).each_with_object({}) { |(k, v), acc| acc[k.to_sym] = v }
+      end
+
+      def encode(value, mode)
+        case mode
+        when :url, :query then ERB::Util.url_encode(value.to_s)
+        when :header then value.to_s.gsub(/[\r\n]/, "")
+        when :body then value.is_a?(String) ? value.to_json[1..-2] : value.to_json
+        end
+      end
+
+      def extract(result)
+        case @definition.response[:extract]
+        when "status" then { status: result[:status] }
+        when "body_raw" then http_ok?(result) ? result[:body] : http_error(result)
+        when "json_path" then extract_json(result)
+        end
+      end
+
+      def extract_json(result)
+        return http_error(result) unless http_ok?(result)
+
+        parsed = begin
+          JSON.parse(result[:body])
+        rescue JSON::ParserError
+          return { error: "response is not JSON" }
+        end
+        dig_path(parsed, @definition.response[:path])
+      end
+
+      def dig_path(obj, path)
+        path.split(".").reduce(obj) do |cur, seg|
+          return { error: "path '#{path}' not found in the response" } unless cur.is_a?(Hash) && cur.key?(seg)
+
+          cur[seg]
+        end
+      end
+
+      # 2xx only. A 3xx is NOT success: the HttpClient does not follow redirects
+      # (the EgressGuard cleared the authored URL, not the hop's destination), and
+      # servers send a 3xx with an empty body — so treating it as ok handed the
+      # model "" and it narrated a plausible outage. A moved API must read as an
+      # error naming its new URL, which is a definition to fix.
+      def http_ok?(result) = result[:status] >= 200 && result[:status] < 300
+
+      # A non-2xx is an ERROR — the backend said so, and the model has to know the call
+      # failed. But the body of a failure is often the backend TALKING: an envelope with
+      # a status and an instruction ("chat not found — ask the person to start over").
+      # Flattening it into a 200-char slice of a string threw that away exactly when the
+      # model needed it most, so a JSON body rides along parsed, under its own key.
+      # A non-JSON body (an HTML error page) stays truncated: it is noise, not a message.
+      ERROR_BODY_MAX = 2_000
+
+      def http_error(result)
+        if (300..399).cover?(result[:status]) && result[:location]
+          return { error: "HTTP #{result[:status]}: moved to #{result[:location]}" }
+        end
+
+        raw = result[:body].to_s
+        parsed = parse_error_body(raw)
+        return { error: "HTTP #{result[:status]}", body: parsed } if parsed
+
+        { error: "HTTP #{result[:status]}: #{raw[0, 200]}" }
+      end
+
+      # -> parsed JSON body worth forwarding | nil (not JSON, or too big to be a message).
+      def parse_error_body(raw)
+        return nil if raw.empty? || raw.bytesize > ERROR_BODY_MAX
+
+        parsed = JSON.parse(raw)
+        parsed.is_a?(Hash) || parsed.is_a?(Array) ? parsed : nil
+      rescue JSON::ParserError
+        nil
+      end
+
+      # No task correlation (registry tool does not receive TurnState) -> meta {}.
+      # Emits only name + status: NEVER body/headers (0 secret leakage, R2).
+      def emit(status)
+        @event_stream&.emit(Insika::Event.new(
+                              type: :data_tool_call, data: { tool: @definition.name, status: status }, meta: {}
+                            ))
+      end
+    end
+  end
+end

data/lib/insika/tools/load_skill.rb

@@ -0,0 +1,41 @@
+# frozen_string_literal: true
+
+require "ruby_llm"
+
+module Insika
+  module Tools
+    # Level 2 of progressive disclosure: loads the full SKILL.md body
+    # on demand. Respects the agent's allowlist (the model does not load a
+    # skill that the policy did not expose).
+    #
+    # `require "ruby_llm"` stays in THIS file (it inherits from
+    # RubyLLM::Tool), which is why it does NOT enter lib/insika.rb: the Executor
+    # loads it lazily inside create_chat.
+    class LoadSkill < RubyLLM::Tool
+      description "Loads the complete instructions (SKILL.md) of a skill by name"
+      param :name, desc: "Exact skill name, as listed in <available_skills>"
+
+      # RubyLLM::Tool#name derives from self.class.name — for a nested class it produces
+      # "insika--tools--load_skill", not "load_skill" (which wire_callbacks/
+      # :skill_activated and SkillCatalog#format_for_prompt assume). Explicit
+      # override. Coexists with
+      # `param :name` (verified: the param is still present).
+      def name = "load_skill"
+
+      def initialize(catalog, allowed_names)
+        @catalog = catalog
+        @allowed = Array(allowed_names).map(&:to_s)
+        super()
+      end
+
+      def execute(name:)
+        return { error: "skill '#{name}' not available for this agent" } unless @allowed.include?(name.to_s)
+
+        skill = @catalog.find(name)
+        return { error: "skill '#{name}' not found" } unless skill
+
+        skill.body
+      end
+    end
+  end
+end

data/lib/insika/tools/remember.rb

@@ -0,0 +1,53 @@
+# frozen_string_literal: true
+
+require "ruby_llm"
+
+module Insika
+  module Tools
+    # Write path of the cross-session memory: the agent stores a
+    # fact (key+value, durable upsert) or a note (value without key) on demand.
+    # Deterministic — NO model call.
+    # System builtin (like load_skill/tool_search): `require "ruby_llm"` stays
+    # in THIS file, loaded lazily by the Executor in create_chat.
+    class Remember < RubyLLM::Tool
+      description "Stores information to remember in future conversations. Use `key` " \
+                  "for a durable key-value fact (overwrites the previous one); omit " \
+                  "`key` for a free-form note."
+      param :value, desc: "The content to remember"
+      param :key, desc: "Fact key (e.g.: 'plan', 'name'); omit for a note", required: false
+
+      # otherwise RubyLLM derives "insika--tools--remember" from the class name.
+      def name = "remember"
+
+      def initialize(store, tenant, event_stream:, state:)
+        @store = store
+        @tenant = tenant
+        @event_stream = event_stream
+        @state = state
+        super()
+      end
+
+      def execute(value:, key: nil)
+        if key.to_s.strip.empty?
+          note = @store.add_note(tenant: @tenant, text: value.to_s)
+          emit("note", note.id)
+          { remembered: "note", id: note.id }
+        else
+          @store.put_fact(tenant: @tenant, key: key.to_s, value: value.to_s)
+          emit("fact", key.to_s)
+          { remembered: "fact", key: key.to_s }
+        end
+      end
+
+      private
+
+      def emit(kind, ref)
+        @event_stream.emit(Insika::Event.new(
+                             type: :memory_written,
+                             data: { kind: kind, key: ref },
+                             meta: { task_id: @state.task.id, session_id: @state.task.session_id }
+                           ))
+      end
+    end
+  end
+end

data/lib/insika/tools/subagent.rb

@@ -0,0 +1,75 @@
+# frozen_string_literal: true
+
+require "ruby_llm"
+require_relative "agent_enum"
+
+module Insika
+  module Tools
+    # In-process delegation to a CHILD agent (RFC-0010, item 21) — the Flue
+    # `session.task()` primitive. A system tool (like remember/load_skill): wired
+    # by the ChatBuilder ONLY when `profile.subagents` is present, so `require
+    # "ruby_llm"` stays in this file (loaded lazily in create_chat). NOT enveloped
+    # (system tool) — in the synchronous mode the child lives in the parent's
+    # envelope and re-runs on the parent's resume (RFC-0010 §6).
+    #
+    # It holds no delegation logic itself: `execute` reads the parent TurnState
+    # (the subagents allowlist + resolved model for inheritance + depth) and hands
+    # off to `Executor#run_subagent`, which spawns the isolated child turn and
+    # returns its result. The child result = its text + the linked child session
+    # id (§4.3 R3).
+    class Subagent < RubyLLM::Tool
+      description "Delegates a self-contained task to a specialized child agent. " \
+                  "The child runs in an ISOLATED context (it does not see this " \
+                  "conversation) — pass everything it needs in `message`. By default " \
+                  "it BLOCKS and returns the child's final answer. Set async:true to " \
+                  "fire-and-forget a long task: it returns immediately and the child's " \
+                  "result arrives later as a new message on this conversation."
+      param :agent, desc: "Id of the child agent to delegate to (must be one this agent may spawn)"
+      param :message, desc: "The self-contained task/prompt for the child agent"
+      param :async, type: :boolean, required: false,
+                    desc: "true = dispatch and continue (result delivered later); default false = wait for the answer"
+
+      # otherwise RubyLLM derives "insika--tools--subagent" from the class name.
+      def name = "spawn_subagent"
+
+      def initialize(runner:, state:)
+        @runner = runner
+        @state = state
+        @allowed = Array(state.profile.subagents).map(&:to_s)
+        super()
+      end
+
+      # The parent's allowlist is per-TURN data, so it is named per instance: the
+      # ids go into the description AND as an `enum` on `agent`. Measured, not
+      # guessed — with only "must be one this agent may spawn" in the schema, a
+      # real provider answered "let me check which agents are available" and then
+      # did the work itself instead of delegating. A model cannot call what it
+      # cannot name.
+      def description
+        return super if @allowed.empty?
+
+        "#{super} Agents you may spawn: #{@allowed.join(', ')}."
+      end
+
+      def params_schema
+        @agent_enum_schema ||= Insika::Tools::AgentEnum.inject(super, @allowed, path: %i[agent])
+      end
+
+      # The child result is returned to the model as the tool result. On error we
+      # return { error: } (never raise) — a bad `agent`/depth/child failure is a
+      # message to the model, not a turn-killer (parity with A2ARemote).
+      def execute(agent:, message:, async: false)
+        result = @runner.run_subagent(agent: agent.to_s, message: message.to_s,
+                                      parent_state: @state, async: async == true)
+        return { error: result[:error] } if result[:error]
+
+        # async dispatch: the ack (the child result arrives later as a new turn).
+        return { dispatched: true, agent: result[:agent], session_id: result[:session_id] } if result[:dispatched]
+
+        # sync: link the child session id alongside the text so a multi-step parent
+        # can reference it and the transcript stays auditable (§4.3 R3 / §7).
+        { text: result[:text], session_id: result[:session_id] }
+      end
+    end
+  end
+end

data/lib/insika/tools/subagents.rb

@@ -0,0 +1,77 @@
+# frozen_string_literal: true
+
+require "ruby_llm"
+require_relative "agent_enum"
+
+module Insika
+  module Tools
+    # PARALLEL fan-out of child agents (RFC-0010 §A): delegate N self-contained
+    # tasks at once and get all answers back together, in ONE parent turn. Sibling
+    # of `spawn_subagent` (single); this one always sync-joins — the children run
+    # concurrently (their provider waits overlap on the reactor) and the combined
+    # result comes back as this tool's result. A system tool wired by the ChatBuilder
+    # when `profile.subagents` is present; `require "ruby_llm"` stays in this file
+    # (loaded lazily in create_chat). NOT enveloped (children live in the parent's
+    # envelope, same as the sync single).
+    class Subagents < RubyLLM::Tool
+      description "Delegates SEVERAL self-contained tasks to child agents IN " \
+                  "PARALLEL and returns all their answers together. Use this — not " \
+                  "repeated spawn_subagent calls — when you have multiple independent " \
+                  "subtasks whose results you'll combine: it runs them concurrently " \
+                  "(much faster). Each child runs in an ISOLATED context, so put " \
+                  "everything it needs in its `message`."
+      # array-of-objects param via the explicit JSON-schema form (the `param` DSL
+      # only reaches strings/scalars). Top-level `tasks` arrives as a kwarg to execute.
+      params(
+        type: "object",
+        properties: {
+          tasks: {
+            type: "array",
+            description: "The independent subtasks to run in parallel",
+            items: {
+              type: "object",
+              properties: {
+                agent: { type: "string", description: "id of the child agent (must be one this agent may spawn)" },
+                message: { type: "string", description: "the self-contained task/prompt for that child" }
+              },
+              required: %w[agent message]
+            }
+          }
+        },
+        required: %w[tasks]
+      )
+
+      # otherwise RubyLLM derives "insika--tools--subagents" from the class name.
+      def name = "spawn_subagents"
+
+      def initialize(runner:, state:)
+        @runner = runner
+        @state = state
+        @allowed = Array(state.profile.subagents).map(&:to_s)
+        super()
+      end
+
+      # Same reason as `spawn_subagent`: the parent's allowlist is per-turn data,
+      # so the ids are named per instance — in the description and as an `enum` on
+      # each task's `agent`. See Tools::AgentEnum.
+      def description
+        return super if @allowed.empty?
+
+        "#{super} Agents you may spawn: #{@allowed.join(', ')}."
+      end
+
+      def params_schema
+        @agent_enum_schema ||= Insika::Tools::AgentEnum.inject(super, @allowed, path: %i[tasks agent])
+      end
+
+      # -> { results: [{agent:, text:, session_id:} | {agent:, error:}] } | { error: }.
+      # Never raises: a bad envelope / per-task failure is a message to the model.
+      def execute(tasks:)
+        result = @runner.run_subagents(tasks: Array(tasks), parent_state: @state)
+        return { error: result[:error] } if result[:error]
+
+        { results: result[:results] }
+      end
+    end
+  end
+end

data/lib/insika/tools/tool_search.rb

@@ -0,0 +1,94 @@
+# frozen_string_literal: true
+
+require "ruby_llm"
+
+module Insika
+  module Tools
+    # Level 2 of TOOLS progressive disclosure (analog of LoadSkill):
+    # searches the deferred catalog and PROMOTES the relevant ones into the live chat via
+    # chat.with_tools (verified to propagate on the next round of the same `ask`
+    # in ruby_llm 1.16). `require "ruby_llm"` stays in THIS file (it inherits from
+    # RubyLLM::Tool) — it does not enter lib/insika.rb; the Executor loads it lazily in
+    # configure_chat (like LoadSkill).
+    class ToolSearch < RubyLLM::Tool
+      description "Searches and enables additional tools by describing the need"
+      param :query, desc: "What you need to do (e.g.: 'send email', 'generate invoice')"
+
+      # RubyLLM::Tool#name derives from self.class.name — for a nested class
+      # (Insika::Tools::ToolSearch) it produces "insika--tools--tool_search", not
+      # "tool_search". Explicit override: the name the model calls must match
+      # the catalog/docs/tests.
+      def name = "tool_search"
+
+      def initialize(catalog, deferred_allowed, chat, tool_registry:, event_stream:,
+                     checkpoint_store:, state:)
+        @catalog = catalog
+        @deferred_allowed = Array(deferred_allowed).map(&:to_s)
+        @chat = chat
+        @tool_registry = tool_registry
+        @event_stream = event_stream
+        @checkpoint_store = checkpoint_store
+        @state = state
+        @promoted = [] # names already promoted IN THIS chat — idempotency
+        super()
+      end
+
+      def execute(query:)
+        matches = @catalog.search(query, within: @deferred_allowed)
+        emit_tool_search(query, matches.map(&:name))
+        if matches.empty?
+          return { matched: [], message: "no tool found for '#{query}'" }
+        end
+
+        new_matches = matches.reject { |m| @promoted.include?(m.name) }
+        promote(new_matches) unless new_matches.empty?
+
+        { matched: matches.map { |m| describe(m) } }
+      end
+
+      private
+
+      # Instantiates (via tool_registry), wraps in the SAME ToolEnvelope as the eager
+      # ones (profile timeout + state's skip_side_effects) and promotes via
+      # chat.with_tools. A NotFoundError (misaligned catalog) drops only
+      # that match — the search does not break.
+      def promote(entries)
+        timeout = @state.profile.limits[:tool_timeout] || 60
+        wrapped = entries.filter_map do |entry|
+          tool = @tool_registry.resolve(entry.name)
+          @promoted << entry.name
+          ToolEnvelope.new(tool, state: @state, checkpoint_store: @checkpoint_store,
+                                 tool_registry: @tool_registry, timeout: timeout,
+                                 skip_side_effects: Array(@state.skip_side_effects))
+        rescue Insika::NotFoundError
+          nil
+        end
+        @chat.with_tools(*wrapped) unless wrapped.empty?
+      end
+
+      # Mirrors :skill_activated, but emitted by the tool itself (it has event_stream/
+      # state in the constructor). Without a monotonic `seq` (private to the Executor) — a
+      # documented gap, not a blocker.
+      def emit_tool_search(query, matched_names)
+        @event_stream.emit(Insika::Event.new(
+                             type: :tool_search,
+                             data: { query: query, matched: matched_names },
+                             meta: { task_id: @state.task.id, session_id: @state.task.session_id }
+                           ))
+      end
+
+      def describe(entry)
+        tool = @tool_registry.resolve(entry.name)
+        {
+          name: entry.name,
+          description: entry.description,
+          parameters: tool.parameters.transform_values do |p|
+            { type: p.type, description: p.description, required: p.required }
+          end
+        }
+      rescue Insika::NotFoundError
+        { name: entry.name, description: entry.description, parameters: {} }
+      end
+    end
+  end
+end