insika 0.0.1 → 0.2.0

data/lib/insika/tool_assembly.rb

@@ -0,0 +1,140 @@
+# frozen_string_literal: true
+
+require "async"
+require "async/semaphore"
+
+module Insika
+  # Turn-scoped assembly of the agent's tool instances (pipeline stage 3 tail):
+  # capability resolution, instantiation (Entry#factory | ready instance),
+  # turn-context injection, the capability<->direct dedup join, and the
+  # ToolEnvelope wrap (stage 7 seam: per-call timeout + side-effect recording).
+  #
+  # Extracted from the Executor to keep the hot-path file smaller. It is
+  # a pure collaborator — it holds only the injected registries/stores and no
+  # per-turn state; everything turn-specific arrives via `state`/`turn_context`.
+  # The Executor keeps thin delegators (resolve_capabilities/assemble_tool_instances/
+  # wrap_tools) so the existing private-method contract stays intact.
+  class ToolAssembly
+    def initialize(tool_registry:, capability_registry:, event_stream:,
+                   checkpoint_store:, tool_trace_store:)
+      @tool_registry = tool_registry
+      @capability_registry = capability_registry
+      @event_stream = event_stream
+      @checkpoint_store = checkpoint_store
+      @tool_trace_store = tool_trace_store
+    end
+
+    # Resolution sub-step BETWEEN Context and Policy —
+    # it does NOT feed candidate_tools (those stay ONLY tool_registry.entries,
+    # a capability does not go through the ToolAllowlist). Resolves each
+    # capability of the profile to the concrete Entry already registered in the
+    # tool_registry and keeps the impl_name -> capability_name mapping for the
+    # post-Policy join. Errors
+    # (Unavailable/Ambiguous, or an unregistered impl) propagate as a
+    # CapabilityError -> single capture in `execute` (stage :capability). Without
+    # @capability_registry OR without profile.capabilities: {} (parity).
+    def resolve_capabilities(profile, context)
+      return {} if @capability_registry.nil?
+
+      Array(profile.capabilities).each_with_object({}) do |cap_name, names|
+        provider = @capability_registry.resolve(cap_name, profile: profile, context: context,
+                                                           event_stream: @event_stream)
+        next if provider.kind == :workflow # exposure to the agent loop is a follow-up
+
+        entry = @tool_registry.entries.find { |e| e.name == provider.impl_name.to_s }
+        if entry.nil?
+          raise CapabilityError, "capability '#{cap_name}' resolveu para impl " \
+                                 "'#{provider.impl_name}', not registered in tool_registry"
+        end
+
+        names[entry.name] ||= cap_name.to_s # the 1st capability to claim an impl wins
+      end
+    end
+
+    # Joins the direct instances (Policy/ToolAllowlist) with the
+    # capability-sourced ones (grant = profile.capabilities — they never went
+    # through Policy). Avoids double-exposure: if the SAME impl_name was also
+    # allowed directly, the DIRECT instance is discarded — the model sees only the
+    # capability alias.
+    def assemble_tool_instances(allowed, state)
+      names = state.respond_to?(:capability_names) ? (state.capability_names || {}) : {}
+      ctx = state.respond_to?(:turn_context) ? state.turn_context : nil
+      return instantiate_tools(allowed, ctx) if names.empty?
+
+      # Dedup by the ENTRY NAME (registry key = impl_name) BEFORE
+      # instantiating — the INSTANCE's `.name` (RubyLLM) is not the registration
+      # name.
+      direct = Array(allowed).reject { |e| e.respond_to?(:name) && names.key?(e.name.to_s) }
+      instantiate_tools(direct, ctx) + capability_tool_instances(names, ctx)
+    end
+
+    # Envelopes each allowed tool (per-call timeout + side-effect recording).
+    # The system LoadSkill (configure_chat) is NOT enveloped — it is a system
+    # tool with no side-effect and of trivial latency.
+    def wrap_tools(tools, state, skip_side_effects = [])
+      timeout = state.profile.limits[:tool_timeout] || 60
+      install_tool_gate(state)
+      tools.map do |tool|
+        ToolEnvelope.new(tool, state: state, checkpoint_store: @checkpoint_store,
+                               tool_registry: @tool_registry, timeout: timeout,
+                               skip_side_effects: skip_side_effects,
+                               trace_recorder: @tool_trace_store)
+      end
+    end
+
+    private
+
+    # the model decides the fan-out, so without a cap a batch of 15
+    # data-tools is 15 simultaneous requests to the same upstream — which is how
+    # one turn earns a 429 for every other turn in the process. Note the contrast
+    # with the primitives that already shipped: `spawn_subagents` caps at 8
+    # (SubagentGraph.fan_out_cap) and `Tools::Concurrency.gather` takes `max:`.
+    #
+    # The cap is enforced in OUR decorator, not in the gem (which has none): ONE
+    # semaphore per turn, installed here — once, in the turn's own fiber, before
+    # any tool can run — and acquired by every ToolEnvelope. Off (nil) unless the
+    # turn actually got concurrency, so the serial path allocates nothing.
+    # A state that predates these fields (a unit stub) is left alone.
+    def install_tool_gate(state)
+      return unless state.respond_to?(:tool_gate) && state.respond_to?(:tool_concurrency)
+
+      cap = state.tool_concurrency
+      state.tool_gate = cap ? Async::Semaphore.new(cap) : nil
+    end
+
+    # Real Engine -> Entries (respond to factory); fakes -> ready instances.
+    # `turn_context` is deposited into the instances that expose it
+    # (data-tools); the rest ignore it (parity).
+    def instantiate_tools(allowed, turn_context = nil)
+      Array(allowed).map do |t|
+        tool = t.respond_to?(:factory) ? t.factory.call : t
+        inject_turn_context(tool, turn_context)
+        tool
+      end
+    end
+
+    # seam: deposits the turn context into the freshly created instance
+    # (same idea as `remember`, which receives tenant/state) BEFORE the
+    # ToolEnvelope. Duck-typed: only what exposes `turn_context=` (DataDefinedTool)
+    # receives it. nil (a state with no turn_context, e.g. a test stub) -> no-op.
+    def inject_turn_context(tool, turn_context)
+      return if turn_context.nil?
+
+      tool.turn_context = turn_context if tool.respond_to?(:turn_context=)
+    end
+
+    # impl_name -> Capability::ResolvedTool(capability_name:), STILL without
+    # ToolEnvelope (the call site's wrap_tools wraps the whole set — same
+    # order impl -> ResolvedTool -> ToolEnvelope). entry already validated in
+    # resolve_capabilities.
+    def capability_tool_instances(names, turn_context = nil)
+      names.map do |impl_name, capability_name|
+        entry = @tool_registry.entries.find { |e| e.name == impl_name }
+        tool = entry.factory.call
+        inject_turn_context(tool, turn_context)
+        Capability::ResolvedTool.new(tool, capability_name: capability_name,
+                                           impl_name: impl_name)
+      end
+    end
+  end
+end

data/lib/insika/tool_catalog.rb

@@ -0,0 +1,89 @@
+# frozen_string_literal: true
+
+module Insika
+  # "Level 1" (progressive disclosure) view of the tools: just
+  # name+description, the analog of SkillCatalog for tools. It does NOT read
+  # disk (the tools are already in the ToolRegistry, registered at boot) and does NOT
+  # inherit from RubyLLM::Tool — duck typing over `.description` (pure, testable without
+  # the gem).
+  #
+  # The canonical `description` does not live in the Entry (Registry::Entry has no such
+  # field): it comes from the tool INSTANCE (`factory.call.description`). That is why the
+  # catalog is LAZY: it only instantiates the tools on the first query (`all`), not at
+  # boot. A deployment without `tools_deferred` never touches the catalog and pays for
+  # no instantiation at all; a broken factory surfaces on first use (where the
+  # Executor would also catch it at stage 3), not at construction.
+  class ToolCatalog
+    Entry = Data.define(:name, :description)
+
+    def initialize(tool_registry:)
+      @tool_registry = tool_registry
+    end
+
+    def all
+      @entries ||= build_entries
+    end
+
+    # Reloads the index (after authoring a data-tool in the overlay). Mirrors
+    # SkillCatalog#reload — level-1/tool_search starts seeing the new tool without a
+    # restart. An in-flight turn has already captured `all`.
+    def reload
+      @entries = build_entries
+      self
+    end
+
+    # Allowed deferred slice (typically allowed_tools ∩ tools_deferred).
+    # Names outside the catalog are silently ignored (safe failure: less
+    # exposure, never more).
+    def subset(names)
+      wanted = Array(names).map(&:to_s)
+      all.select { |e| wanted.include?(e.name) }
+    end
+
+    # PURE matcher: case-insensitive, substring/keyword, NO
+    # embeddings. name weighs 2, description weighs 1; ties broken by original index
+    # (Ruby's sort_by is not stable). `within:` restricts the universe via subset.
+    def search(query, within: nil)
+      terms = query.to_s.downcase.split(/\s+/).reject(&:empty?)
+      return [] if terms.empty?
+
+      universe = within ? subset(within) : all
+      scored = universe.each_with_index.filter_map do |entry, idx|
+        score = score_entry(entry, terms)
+        [entry, score, idx] if score.positive?
+      end
+      scored.sort_by { |_entry, score, idx| [-score, idx] }.map(&:first)
+    end
+
+    # Level 1 injected into the prompt — mirror of SkillCatalog#format_for_prompt,
+    # swapping the tag and the final instruction (load_skill -> tool_search).
+    def format_for_prompt(entries = all)
+      return "" if entries.empty?
+
+      lines = entries.map { |e| %(  <tool name="#{e.name}">#{e.description}</tool>) }.join("\n")
+
+      <<~PROMPT.strip
+        <available_tools>
+        #{lines}
+        </available_tools>
+
+        Before using a tool above, call `tool_search` with what you need
+        to do to enable it in this conversation.
+      PROMPT
+    end
+
+    private
+
+    def build_entries
+      @tool_registry.entries.map do |entry|
+        Entry.new(name: entry.name, description: entry.factory.call.description.to_s)
+      end
+    end
+
+    def score_entry(entry, terms)
+      name = entry.name.downcase
+      desc = entry.description.downcase
+      terms.sum { |term| (name.include?(term) ? 2 : 0) + (desc.include?(term) ? 1 : 0) }
+    end
+  end
+end