insika 0.3.0 → 0.8.0

data/lib/insika/templates.rb

@@ -0,0 +1,112 @@
+# frozen_string_literal: true
+
+require "yaml"
+
+module Insika
+  # Template gallery: example agents shipped INSIDE the gem
+  # (`lib/insika/templates/<name>/{agent.rb,README.md}`), one DSL file per
+  # template that is BOTH doors — `insika new <name>` copies it for the user
+  # to run and edit, and this module `evaluate`s the same file to hand its
+  # pack(s) to the Studio's "New from template" gallery. No parallel pack
+  # format to drift.
+  #
+  # A template's `agent.rb` guards its CLI demo footer with
+  # `if __FILE__ == $PROGRAM_NAME` (false when this module evaluates it) and
+  # ends with the bare `Insika.agent`/`Insika.system` result as its LAST
+  # expression, so `evaluate` gets it back as the string-eval's return value
+  # — no registration call, no second source of truth.
+  module Templates
+    ROOT = File.expand_path("templates", __dir__)
+
+    Entry = Data.define(:name, :title, :trail, :description, :capabilities, :studio, :env, :requires) do
+      def studio? = studio
+    end
+
+    module_function
+
+    # -> [String] template dirs that have an agent.rb, lexicographic.
+    def names
+      return [] unless Dir.exist?(ROOT)
+
+      Dir.children(ROOT).select { |n| File.file?(agent_path(n)) }.sort
+    end
+
+    # -> [Entry] every template, parsed metadata only (no evaluation — cheap,
+    # safe to call on every render of the Studio gallery).
+    def all = names.map { |n| read(n) }
+
+    # -> Entry for one template. Raises NotFoundError for an unknown name —
+    # same discipline as a missing agent/MCP instance.
+    def read(name)
+      path = agent_path(name)
+      raise Insika::NotFoundError, "template '#{name}' not found" unless File.file?(path)
+
+      meta = frontmatter(File.read(path))
+      Entry.new(
+        name: name.to_s, title: presence(meta["title"]) || name.to_s, trail: presence(meta["trail"]),
+        description: meta["description"].to_s,
+        capabilities: split_list(meta["capabilities"]),
+        studio: meta.fetch("studio", true) != false,
+        env: split_list(meta["env"]), requires: presence(meta["requires"])
+      )
+    end
+
+    # Evaluates the template's agent.rb in an ISOLATED scope (a fresh Object's
+    # instance_eval) and returns whatever its last expression is — the built
+    # `Insika::DSL::Definition` or `Insika::DSL::System`. $PROGRAM_NAME here is
+    # whatever process called this (rspec, the CLI, the Studio server), never
+    # this file's path, so the template's own `if __FILE__ == $PROGRAM_NAME`
+    # demo footer never runs: no network call, no ARGV parsing, no puts.
+    #
+    # The fresh-Object receiver keeps a template's local variables and `def`s
+    # from leaking into the next one evaluated in the same process; a
+    # top-level CONSTANT would still leak (Ruby scopes constant assignment
+    # lexically, not by `self`) — wave-1 templates simply don't declare any
+    # (the conformance spec, would catch a future one that did).
+    def evaluate(name)
+      path = agent_path(name)
+      raise Insika::NotFoundError, "template '#{name}' not found" unless File.file?(path)
+
+      Object.new.instance_eval(File.read(path), path)
+    end
+
+    # -> [Pack] one per agent, regardless of whether the template is a single
+    # `Insika.agent` (Definition#to_pack) or a system (System#to_packs).
+    def packs_for(name)
+      built = evaluate(name)
+      built.respond_to?(:to_packs) ? built.to_packs : [built.to_pack]
+    end
+
+    def agent_path(name) = File.join(ROOT, name.to_s, "agent.rb")
+    def readme_path(name) = File.join(ROOT, name.to_s, "README.md")
+
+    # A `# ---` … `# ---` comment block at the very top of the file, YAML
+    # inside (each line stripped of its leading `# `). Not real Ruby
+    # frontmatter (there's no such thing) — a convention this module alone
+    # parses, so the metadata lives in the one file without needing a
+    # side-channel manifest.
+    def frontmatter(source)
+      lines = source.lines
+      # Every template starts with the same magic comment every other .rb
+      # file in the gem does — skip it (and any blank line) before looking
+      # for the block, so templates don't have to break that convention.
+      lines = lines.drop(1) while lines.first && (lines.first.strip.empty? || lines.first.strip == "# frozen_string_literal: true")
+      return {} unless lines.first&.strip == "# ---"
+
+      body = lines.drop(1)
+                  .take_while { |l| l.strip != "# ---" }
+                  .map { |l| l.sub(/\A#\s?/, "") }
+                  .join
+      YAML.safe_load(body) || {}
+    end
+    private_class_method :frontmatter
+
+    def split_list(value)
+      value.to_s.split(",").map(&:strip).reject(&:empty?)
+    end
+    private_class_method :split_list
+
+    def presence(str) = Insika::Coercion.presence(str)
+    private_class_method :presence
+  end
+end

data/lib/insika/tick.rb

@@ -3,21 +3,23 @@
 require "time"
 
 module Insika
-  # The periodic tick: durability stops waiting for a reboot. One
-  # pass does two things, in this order:
+# The periodic tick: durability stops waiting for a reboot. One
+  # pass does three things, in this order:
   #
   #   1. DRAIN the outbox (`ChannelDelivery#sweep`) — replies a previous pass
   #      (or process) recorded and never claimed. Ungated: every record carries
   #      its own transactional claim, so N workers draining is safe.
-  #   2. SWEEP stale orphaned tasks (`Recovery#run(stale_after:)`) — gated by a
-  #      bucketed claim (`Recovery.claim_sweep` on "tick:<epoch/interval>"), so
-  #      exactly one worker per window sweeps. The staleness threshold is the
-  #      liveness gate: a live :running turn is bounded by turn_timeout, so
-  #      anything untouched past it cannot be alive.
+  #   2. The engine's background duties, each gated by its OWN claim window so
+  #      their O(n) scans never ride the 60 s loop: retention (daily), the
+  #      outcome fold, the follow-up firer, and the recurring-schedule firer
+  #      (the engine's own cron — it superseded the "point your own cron at
+  #      the route" decision, see docs/SCHEDULING.md).
+  #   3. SWEEP stale orphaned tasks (`Recovery#run(stale_after:)`) — gated by a
+  #      bucketed claim, so exactly one worker per window sweeps. The staleness
+  #      threshold is the liveness gate: a live :running turn is bounded by
+  #      turn_timeout, so anything untouched past it cannot be alive.
   #
-  # It is NOT a job queue: no schedules, no priorities, no fan-out. The
-  # refinement hook once pictured here is dropped by merit —
-  # docs/REFINEMENT.md's "no scheduler in the engine" stands.
+  # It is NOT a job queue: no schedules queue, no priorities, no fan-out.
   class Tick
     # 60s: a customer waiting on WhatsApp is the deadline. 900s = 3x the
     # default turn_timeout (300s) — the rule, not the number: the threshold
@@ -31,7 +33,8 @@ module Insika
 
     def initialize(store:, recovery:, channel_delivery:, logger: nil,
                    interval: DEFAULT_INTERVAL, stale_after: DEFAULT_STALE_AFTER,
-                   sleeper: nil, retention: nil, funnel: nil, followup: nil)
+                   sleeper: nil, retention: nil, funnel: nil, followup: nil,
+                   schedule: nil)
       @store = store
       @recovery = recovery
       @channel_delivery = channel_delivery
@@ -39,9 +42,10 @@ module Insika
       @interval = interval.to_i
       @stale_after = stale_after.to_i
       @sleeper = sleeper || method(:default_sleep)
-      @retention = retention # WS8: the daily age-based sweep; nil = none
+      @retention = retention # the daily age-based sweep; nil = none
       @funnel = funnel # the tick-driven outcome fold; nil = none
       @followup = followup # the tick-driven follow-up firer; nil = none
+      @schedule = schedule # the recurring-schedule firer; nil = none
     end
 
     # the fold is wired after the Tick is built (the graph passes
@@ -53,6 +57,10 @@ module Insika
     # shape as `funnel` — the stores come from the spine).
     attr_accessor :followup
 
+    # the recurring-schedule firer, wired after the Tick is built
+    # (same shape — the stores come from the spine).
+    attr_accessor :schedule
+
     def enabled? = @interval.positive?
 
     # One pass, pure (no reactor needed): the serving loop calls it on a timer,
@@ -73,6 +81,10 @@ module Insika
       # OWN claim window so the O(n) scans never ride the 60 s loop.
       followup_summary = @followup&.run
       summary[:followup] = followup_summary if followup_summary
+      # the recurring-schedule firer — the tick's fourth duty,
+      # the same claim-window discipline as the follow-up firer.
+      schedule_summary = @schedule&.run
+      summary[:schedule] = schedule_summary if schedule_summary
       return summary unless claim_window
 
       result = @recovery.run(stale_after: @stale_after)

data/lib/insika/timezone.rb

@@ -0,0 +1,45 @@
+# frozen_string_literal: true
+
+module Insika
+  # IANA timezone handling through the OS tz database — the
+  # engine's only route to a zone NAME (Ruby stdlib's `Time#getlocal` takes an
+  # offset, not a zone name). Shared by FollowupPolicy (quiet hours), the cron
+  # parser (next-fire materialization) and the doctor (zone existence).
+  #
+  # IANA names are resolved by pointing Ruby's `TZ` at the zone for the
+  # computation. Save/restore keeps the global intact; under the engine's
+  # cooperative fiber model — no IO between the save and the restore — the
+  # mutation is atomic on the calling fiber.
+  module Timezone
+    # The candidate tz-data roots (TZDIR first — Ruby's own lookup env). The
+    # zone name maps to a FILE under the root ("America/Sao_Paulo" ->
+    # "America/Sao_Paulo").
+    TZ_ROOTS = ([ENV["TZDIR"]] +
+                %w[/usr/share/zoneinfo /usr/share/lib/zoneinfo /etc/zoneinfo])
+               .compact.freeze
+
+    module_function
+
+    # -> bool: is `zone` an IANA name the OS tz database knows? A bogus zone
+    # is a malformed declaration — refused where the doctor can name it (an
+    # unknown ENV["TZ"] silently behaves as UTC, so existence is checked
+    # against the database, not by asking Time).
+    def known?(zone)
+      zone = zone.to_s
+      return true if zone == "UTC" || zone == "Etc/UTC"
+
+      TZ_ROOTS.any? { |root| File.directory?(root) && File.exist?(File.join(root, zone)) }
+    end
+
+    # Yields `time` interpreted in the given IANA zone (via a save/restore of
+    # ENV["TZ"] — the stdlib-only route to the OS tz database). Returns the
+    # block's value.
+    def in_zone(zone, time)
+      previous = ENV["TZ"]
+      ENV["TZ"] = zone.to_s
+      yield time
+    ensure
+      ENV["TZ"] = previous
+    end
+  end
+end

data/lib/insika/tool_batch.rb

@@ -0,0 +1,67 @@
+# frozen_string_literal: true
+
+module Insika
+  # The batch arithmetic behind every mid-turn `user` append.
+  #
+  # A model step that calls tools produces ONE assistant message announcing N
+  # tool calls, followed by N `role: tool` messages. Anthropic rejects a `user`
+  # message that lands between two of those results outright, so the ONLY valid
+  # append point inside a turn is the instant the Nth result closes the batch.
+  # SteerInjector discovered this rule; LoopDetector and TurnBudget both live by
+  # it, which is why the counting lives here instead of twice.
+  #
+  # Not a general-purpose helper: it answers one question ("did a batch just
+  # close?") and remembers one fact ("was this batch halted"), because a
+  # `halt_when` batch has no next model step and anything appended there would
+  # sit unread forever.
+  class ToolBatch
+    def initialize
+      @expected = nil # tool calls announced by the batch in flight (nil = none)
+      @seen = 0
+      @halted = false
+    end
+
+    # Feeds a RubyLLM message (duck-typed). True EXACTLY on the message that
+    # closes a batch of tool calls — the append boundary. Everything else,
+    # including the assistant message that opens the batch, is false.
+    def closed?(message)
+      role = field(message, :role).to_s
+      return open(message) if role == "assistant"
+      return false unless role == "tool" && @expected
+
+      @seen += 1
+      return false if @seen < @expected
+
+      @expected = nil
+      true
+    end
+
+    # From after_tool_result, with the RAW result: a Tool::Halt is only
+    # recognizable there.
+    def halt!(result)
+      @halted = true if defined?(RubyLLM::Tool::Halt) && result.is_a?(RubyLLM::Tool::Halt)
+    end
+
+    def halted? = @halted
+
+    private
+
+    # An assistant message with no tool calls is the model TALKING: the turn is
+    # ending, so nothing is in flight any more.
+    def open(message)
+      calls = field(message, :tool_calls)
+      size = calls.respond_to?(:size) ? calls.size : 0
+      @expected = size.zero? ? nil : size
+      @seen = 0
+      @halted = false
+      false
+    end
+
+    def field(message, name)
+      return message.public_send(name) if message.respond_to?(name)
+      return message[name] || message[name.to_s] if message.respond_to?(:[])
+
+      nil
+    end
+  end
+end

data/lib/insika/tool_usage_report.rb

@@ -0,0 +1,162 @@
+# frozen_string_literal: true
+
+require "time"
+
+module Insika
+  # The tool AUDIT the per-session trace cannot answer: `tool_traces` records
+  # every call, but one session at a time, and nothing aggregates — so "which
+  # tools does this agent carry and never use?" had no surface at all. This
+  # report is that surface. Read-only by design: it names the candidates, the
+  # OPERATOR removes (a tool the report flags may still be the one a rare but
+  # critical flow needs).
+  #
+  # Attribution rides the task record: a session does not stamp its agent, but
+  # every task carries the agent in its command payload — tasks → sessions →
+  # tool_traces is the same read the Studio does. Three findings per agent:
+  #
+  #   never_called — in `tools_allow`, zero calls in any stored trace. Dead
+  #                  weight: it costs schema tokens on every request and buys
+  #                  nothing (the pilot's `search_orders` is the known example).
+  #   error_rate   — called inside the window with > 30% conventional errors
+  #                  (the trace's own `ok` flag). Either the tool is broken or
+  #                  the model cannot hold its contract; both are operator work.
+  #   stale        — called at some point, but not once inside the window.
+  #
+  # Bounded and honest: it reads only what the stores kept (the trace caps at
+  # 200 entries/session), so a count here is "at least", never an exact total.
+  class ToolUsageReport
+    WINDOW_DAYS = 14
+    ERROR_RATE_THRESHOLD = 0.30
+
+    # One finding. kind: "never_called" | "error_rate" | "stale".
+    Row = Data.define(:agent, :tool, :kind, :detail) do
+      def to_h = { "agent" => agent, "tool" => tool, "kind" => kind, "detail" => detail }
+    end
+
+    Report = Data.define(:generated_at, :days, :agents, :rows) do
+      def to_h
+        { "generated_at" => generated_at, "days" => days, "agents" => agents,
+          "rows" => rows.map(&:to_h) }
+      end
+
+      # Human report, grouped by agent. Silent agents still print their header —
+      # "nothing flagged" is a result, not an omission.
+      def to_s
+        lines = ["tool usage — last #{days} day(s), generated #{generated_at}"]
+        agents.each do |agent|
+          mine = rows.select { |r| r.agent == agent }
+          lines << "" << "#{agent}: #{mine.empty? ? 'nothing flagged' : "#{mine.length} finding(s)"}"
+          mine.each { |r| lines << format("  %-13s %s — %s", r.kind, r.tool, r.detail) }
+        end
+        lines.join("\n")
+      end
+    end
+
+    def initialize(task_store:, tool_trace_store:, profile_source:, now: nil)
+      @task_store = task_store
+      @tool_trace_store = tool_trace_store
+      @profile_source = profile_source
+      @now = now
+    end
+
+    # -> Report. `agent:` narrows to one agent (must still be a stored profile).
+    def generate(days: WINDOW_DAYS, agent: nil)
+      now = @now || Time.now.utc
+      cutoff = now - (days * 24 * 60 * 60)
+      profiles = @profile_source.all_raw
+      profiles = profiles.select { |r| r["id"].to_s == agent.to_s } if agent
+      sessions = sessions_by_agent
+
+      rows = profiles.flat_map do |record|
+        id = record["id"].to_s
+        stats = tool_stats(sessions[id] || [], cutoff)
+        never_called_rows(id, record, stats) +
+          error_rate_rows(id, stats, days) +
+          stale_rows(id, stats)
+      end
+
+      Report.new(generated_at: now.iso8601, days: days,
+                 agents: profiles.map { |r| r["id"].to_s }.sort,
+                 rows: rows.sort_by { |r| [r.agent, r.kind, r.tool] }.freeze)
+    end
+
+    private
+
+    # agent id -> [session ids], via the task records (the only place a session
+    # is tied to its agent). A task without agent or session (operator commands,
+    # workflows without a chat) contributes nothing.
+    def sessions_by_agent
+      acc = Hash.new { |h, k| h[k] = [] }
+      @task_store.each_id do |task_id|
+        task = @task_store.find(task_id) or next
+        agent = task.command.is_a?(Hash) ? task.command.dig("payload", "agent") : nil
+        next if agent.to_s.empty? || task.session_id.to_s.empty?
+
+        acc[agent.to_s] << task.session_id
+      end
+      acc.transform_values(&:uniq)
+    end
+
+    # tool name -> { calls:, errors:, window_calls:, window_errors:, last_at: }
+    # over every stored trace entry of the agent's sessions.
+    def tool_stats(session_ids, cutoff)
+      stats = Hash.new { |h, k| h[k] = { calls: 0, errors: 0, window_calls: 0, window_errors: 0, last_at: nil } }
+      session_ids.each do |sid|
+        @tool_trace_store.for_session(sid).each do |entry|
+          s = stats[entry["tool"].to_s]
+          at = parse_time(entry["at"])
+          error = entry["ok"] == false
+          s[:calls] += 1
+          s[:errors] += 1 if error
+          s[:last_at] = at if at && (s[:last_at].nil? || at > s[:last_at])
+          next unless at && at >= cutoff
+
+          s[:window_calls] += 1
+          s[:window_errors] += 1 if error
+        end
+      end
+      stats
+    end
+
+    def never_called_rows(agent, record, stats)
+      allow = record["tools_allow"]
+      return [] if allow.nil? # no allowlist declared -> nothing to audit against
+
+      Array(allow).map(&:to_s).reject { |t| stats.key?(t) }.map do |tool|
+        Row.new(agent: agent, tool: tool, kind: "never_called",
+                detail: "in tools_allow, never called in any stored trace — " \
+                        "its schema still ships on every request")
+      end
+    end
+
+    def error_rate_rows(agent, stats, days)
+      stats.filter_map do |tool, s|
+        next if s[:window_calls].zero?
+
+        rate = s[:window_errors].to_f / s[:window_calls]
+        next if rate <= ERROR_RATE_THRESHOLD
+
+        Row.new(agent: agent, tool: tool, kind: "error_rate",
+                detail: "#{s[:window_errors]}/#{s[:window_calls]} call(s) errored in the last " \
+                        "#{days} day(s) (#{(rate * 100).round}%)")
+      end
+    end
+
+    def stale_rows(agent, stats)
+      stats.filter_map do |tool, s|
+        next if s[:window_calls].positive? || s[:last_at].nil?
+
+        Row.new(agent: agent, tool: tool, kind: "stale",
+                detail: "last called #{s[:last_at].iso8601}, not once inside the window")
+      end
+    end
+
+    def parse_time(value)
+      return nil if value.to_s.empty?
+
+      Time.parse(value.to_s).utc
+    rescue ArgumentError
+      nil
+    end
+  end
+end

data/lib/insika/tools/generate_image.rb

@@ -14,12 +14,42 @@ module Insika
     # (`channel.capabilities` includes "image_output") — nothing leaks by
     # default. The image is an envelope part, never part of the answer text;
     # the provider's tokens are merged into the turn's usage like any ask.
+    #
+    # Also EDITS — `source_image_urls` (or, absent that, the turn's
+    # own inbound photo) rides `paint(with:)`; `mask_url` rides `paint(mask:)`.
+    # What the edit MEANS (a try-on, a mockup) is the skill's business; this
+    # tool only transports the bytes.
     class GenerateImage < RubyLLM::Tool
-      description "Generate an image and attach it to the reply as an output part. " \
-                  "Use when the customer asked for a picture or an image would help."
-      param :prompt, desc: "What to draw, in detail"
-      param :size, desc: "Optional canvas size, e.g. 1024x1024 (default from the agent config)",
-            required: false
+      description "Generate an image, or EDIT one, and attach it to the reply as an " \
+                  "output part. Use when the customer asked for a picture, or asked to " \
+                  "transform/edit a photo (a virtual try-on, a mockup on their wall, a " \
+                  "touch-up). Omitting source_image_urls generates a new image from the " \
+                  "prompt alone — UNLESS this turn carries an inbound photo, in which case " \
+                  "that photo is edited by default (pass source_image_urls explicitly to " \
+                  "generate from scratch instead)."
+      # explicit JSON-schema form (the `param` DSL only reaches strings/scalars,
+      # and source_image_urls needs a typed array — the bare-array gotcha, #128).
+      params(
+        type: "object",
+        properties: {
+          prompt: { type: "string", description: "What to draw, or what edit to make, in detail" },
+          size: { type: "string",
+                  description: "Optional canvas size, e.g. 1024x1024 (default from the agent config)" },
+          source_image_urls: {
+            type: "array",
+            description: "Image URLs to edit instead of generating from scratch — e.g. " \
+                         "the photo the customer just sent in this conversation " \
+                         "({{ctx.image_url}}), or any other URL from this chat. Omit to use " \
+                         "the turn's inbound photo by default (if any), or to generate a " \
+                         "fresh image when there is none.",
+            items: { type: "string" }
+          },
+          mask_url: { type: "string",
+                      description: "Optional mask image URL marking which area of the " \
+                                   "source(s) to edit (transparent = editable)" }
+        },
+        required: %w[prompt]
+      )
 
       def name = "generate_image"
 
@@ -32,13 +62,28 @@ module Insika
         super()
       end
 
-      def execute(prompt:, size: nil)
-        cfg = @config.merge("size" => size.to_s).reject { |_, v| v.to_s.empty? }
+      def execute(prompt:, size: nil, source_image_urls: nil, mask_url: nil)
+        cfg = @config.merge("size" => size.to_s, "mask_url" => mask_url.to_s)
+                      .reject { |_, v| v.to_s.empty? }
+        cfg = cfg.merge(source_config(source_image_urls))
         part, usage = @runner.generate_media_output(:image, prompt.to_s, cfg)
         @state.output_parts << part
         @runner.account_media_usage(@state, part, usage)
         "image generated and attached to the reply (#{part["mime_type"]})"
       end
+
+      private
+
+      # Explicit URLs win over the default; a turn with inbound images (no
+      # explicit URLs) hands `Output.generate_image` the ALREADY-FETCHED
+      # attachments (bypassing the URL fetch — they are bytes we hold).
+      def source_config(source_image_urls)
+        urls = Array(source_image_urls).map(&:to_s).reject(&:empty?)
+        return { "source_urls" => urls } if urls.any?
+        return {} unless Array(@state.image_attachments).any?
+
+        { "source_attachments" => @state.image_attachments }
+      end
     end
   end
 end

data/lib/insika/tools/load_knowledge.rb

@@ -0,0 +1,74 @@
+# frozen_string_literal: true
+
+require "ruby_llm"
+require "time"
+
+module Insika
+  module Tools
+    # Level 2 of knowledge's progressive disclosure: loads a learned
+    # concept's full body on demand, by the name the `<knowledge>` block
+    # listed. Same shape as `LoadSkill` — a system default (outside the
+    # allowlist), wired only when the profile opted in
+    # (`knowledge.retrieve`), never through `tools_allow`.
+    #
+    # `require "ruby_llm"` stays in THIS file (it inherits from
+    # RubyLLM::Tool), so it does NOT enter lib/insika.rb — the Executor
+    # loads it lazily inside create_chat, same as load_skill.
+    class LoadKnowledge < RubyLLM::Tool
+      description "Loads the complete content of a learned concept by name"
+      param :name, desc: "Exact concept name, as listed in <knowledge>"
+
+      # RubyLLM::Tool#name derives from self.class.name — for a nested class it
+      # produces "insika--tools--load_knowledge", not "load_knowledge" (which
+      # wire_callbacks/:knowledge_retrieved assume). Explicit override, same
+      # reason LoadSkill has one.
+      def name = "load_knowledge"
+
+      # trace_recorder/state are OPTIONAL (nil = no trace, parity): this tool
+      # is deliberately NOT enveloped (ToolAssembly#wrap_tools), so without
+      # recording HERE the call is missing from the Studio's trace — same
+      # shape as LoadSkill.
+      def initialize(store, agent_id, tenant: nil, trace_recorder: nil, state: nil)
+        @store = store
+        @agent_id = agent_id
+        @tenant = tenant
+        @trace_recorder = trace_recorder
+        @state = state
+        super()
+      end
+
+      def execute(name:)
+        started = Process.clock_gettime(Process::CLOCK_MONOTONIC)
+        result = load(name)
+        trace(name, result, started)
+        result
+      end
+
+      private
+
+      def load(name)
+        content = @store.get(@agent_id, name.to_s, tenant: @tenant)
+        return { error: "concept '#{name}' not found" } unless content
+
+        content
+      end
+
+      # Mirrors LoadSkill#trace (same entry shape, so the Studio renders it
+      # like any other call). NEVER breaks the turn — the trace is
+      # observability, not the answer.
+      def trace(name, result, started)
+        return unless @trace_recorder && @state&.task&.session_id
+
+        @trace_recorder.record(
+          session_id: @state.task.session_id,
+          entry: { "turn" => @state.turn, "tool" => "load_knowledge", "call_id" => "",
+                   "args" => { "name" => name.to_s }, "result" => result,
+                   "ms" => ((Process.clock_gettime(Process::CLOCK_MONOTONIC) - started) * 1000).round,
+                   "at" => Time.now.utc.iso8601 }
+        )
+      rescue StandardError
+        nil
+      end
+    end
+  end
+end