insika 0.3.0 → 0.8.0

data/lib/insika/tools/run_persona_eval.rb

@@ -0,0 +1,328 @@
+# frozen_string_literal: true
+
+require "securerandom"
+require "ruby_llm"
+require_relative "agent_enum"
+
+module Insika
+  module Tools
+    # `run_persona_eval` — a QA agent's own probe: pick an authored SIMULATED
+    # persona case (Evals::GoldenStore) and run it, in-process, against the
+    # case's declared target agent — the same Simulator + Judge machinery
+    # `insika evals:simulate` drives over HTTP, minus the CLI and the network
+    # hop.
+    #
+    # SAFETY is DERIVED, never a flag: the target's reachable side-effect tools
+    # are computed from the live registry (Evals::EvalProfile), the same way
+    # the CLI derives them. A read-only target needs no swap:
+    # Simulator::Safety's own "side_effect_tools.empty?" branch allows it
+    # directly. A target that DOES reach a side-effect tool gets the REAL
+    # swap (Evals::EvalProfile.registry — own overlay, wired here):
+    # every one of those tools resolves to a Simulator::DryRunTool for the
+    # duration of this ONE simulated conversation, run through a THROWAWAY
+    # Executor+Bus built fresh per call (`shadow_runtime`) — sharing every
+    # OTHER collaborator of the real graph (guardrails, policy, context
+    # assembly, skills/prompts, the real session/task/checkpoint stores), so
+    # the target is tested as faithfully as `--staging` ever was, minus the
+    # one write. Needs the real `graph:` (see `initialize`) — a caller that
+    # does not have one (an old-style double) falls back to refusing outright.
+    #
+    # BUDGET: the persona model + judge model calls are the cost of running the
+    # eval, charged to the CALLING agent's turn (never the target's — the
+    # target's own turns are billed normally, through the ordinary edge
+    # limiter, exactly as if a customer had sent those messages). A hard cap on
+    # the calling agent skips the run — visibly, in the tool result — before a
+    # cent is spent.
+    #
+    # TENANT ISOLATION: a persona case belongs to a tenant (Golden#tenant,
+    # "platform" by default); this tool only ever lists/runs cases in the
+    # CALLING agent's own tenant (calling_tenant, read off turn_context, never
+    # the model). One QA agent per store (the C3.2 plan) is what makes this
+    # meaningful -- without it, "qa-store-a" could enumerate and run
+    # "qa-store-b"'s persona and read its `knows` in the transcript.
+    class RunPersonaEval < RubyLLM::Tool
+      description "Run an authored simulated-customer persona case, in-process, against " \
+                  "its target agent and score the whole conversation with the configured " \
+                  "judge panel. Refuses if the target exposes a tool that could write for " \
+                  "real."
+      param :case_id, desc: "Id of the persona case to run"
+
+      def name = "run_persona_eval"
+
+      # golden_store: Evals::GoldenStore — where authored persona cases live,
+      #               scoped to the CALLING agent's own tenant (never the
+      #               model's — see `calling_tenant`). A case authored for
+      #               another tenant is invisible here, not merely undocumented.
+      # profiles:     ProfileSource — resolves both the target agent (the
+      #               case's `agent:`) and the CALLING agent (turn_context, for
+      #               the budget check).
+      # tool_registry: the deployment's EFFECTIVE registry — what
+      #               Evals::EvalProfile derives the target's side-effect tools
+      #               from (the same registry a real turn resolves tools on).
+      # runtime:      anything answering `#chat(message, session_id:, agent:)`
+      #               (raises Insika::Error on failure) — Evals::GraphTransport's
+      #               contract. Used AS-IS for a read-only target; a target
+      #               with a reachable side-effect tool needs `graph:` instead
+      #               (this alone cannot swap anything).
+      # graph:        the real Wiring::Graph::Result — ONLY consulted to build
+      #               the throwaway swapped-registry Executor+Bus
+      #               (`shadow_runtime`) when the target has a reachable
+      #               side-effect tool. nil (an old-style double) = that case
+      #               refuses outright, same as before this existed.
+      # settings_store: where the platform `utility_model` (persona) and the
+      #               judge panel (`evals.judges`) are configured.
+      # budget_ledger: WS2 counters — read before the run (skip on a hard cap),
+      #               written after (persona + judge spend only).
+      # llm:          this graph's own RubyLLM::Context, if it has one (a
+      #               DSL-built graph's own credentials) — the persona/judge
+      #               calls' preferred source, ahead of `runtime.llm`
+      #               (kept for the existing double-based specs) and the
+      #               process-wide RubyLLM constant.
+      def initialize(golden_store:, profiles:, tool_registry:, runtime:, settings_store:,
+                     graph: nil, budget_ledger: nil, event_stream: nil, llm: nil)
+        @golden_store = golden_store
+        @profiles = profiles
+        @tool_registry = tool_registry
+        @runtime = runtime
+        @graph = graph
+        @settings_store = settings_store
+        @budget_ledger = budget_ledger
+        @event_stream = event_stream
+        @llm = llm
+        super()
+      end
+
+      # Per-turn bindings, deposited by the Executor (ToolAssembly's
+      # `turn_context=` seam — same as save_artifact/data-tools). Only the
+      # CALLING agent's id + declared tenant are used here (the budget check);
+      # never a tenant/agent the model types.
+      attr_reader :turn_context
+
+      def turn_context=(ctx)
+        @turn_context = (ctx || {}).each_with_object({}) { |(k, v), acc| acc[k.to_sym] = v }
+      end
+
+      # The runnable case ids, named so the model cannot guess one that does
+      # not exist (the Subagent tool's lesson — see AgentEnum).
+      def description
+        ids = case_ids
+        return super if ids.empty?
+
+        "#{super} Cases you may run: #{ids.join(', ')}."
+      end
+
+      def params_schema
+        Insika::Tools::AgentEnum.inject(super, case_ids, path: %i[case_id])
+      end
+
+      def execute(case_id:)
+        golden = @golden_store.find(case_id.to_s)
+        # The SAME error, whether the case does not exist or exists under another
+        # tenant — a QA agent must not be able to tell the two apart (that
+        # distinction is itself a leak: "case exists, just not yours").
+        unless golden&.simulated? && golden.tenant == calling_tenant
+          return { error: "unknown or invalid persona case '#{case_id}'" }
+        end
+
+        target = @profiles[golden.agent]
+        return { error: "persona case '#{case_id}' targets unknown agent '#{golden.agent}'" } unless target
+
+        derived = Insika::Evals::EvalProfile.side_effect_tools(target, @tool_registry)
+        return refuse_side_effects(golden.agent, derived) if !derived.empty? && @graph.nil?
+
+        skip = budget_skip
+        return skip if skip
+
+        meter = []
+        judge = build_judge(meter)
+        return { error: "no judge configured for this case — Studio -> Settings -> Evals" } unless judge
+
+        persona_ask = build_persona_ask(meter)
+        return persona_ask if persona_ask.is_a?(Hash) # {error:}
+
+        run_and_score(golden, derived, persona_ask, judge, meter)
+      rescue Insika::Evals::Simulator::UnsafeTarget => e
+        { error: e.message }
+      end
+
+      private
+
+      def refuse_side_effects(agent, derived)
+        { error: "target agent '#{agent}' exposes side-effect tool(s) (#{derived.join(', ')}) — " \
+                 "run_persona_eval needs the real graph (no swap available for this caller)" }
+      end
+
+      def run_and_score(golden, derived, persona_ask, judge, meter)
+        runtime = derived.empty? ? @runtime : shadow_runtime(derived)
+        transport = Insika::Evals::GraphTransport.new(runtime: runtime, event_stream: @event_stream)
+        safety = Insika::Evals::Simulator::Safety.new(
+          side_effect_tools: derived, eval_profile: !derived.empty?, swapped_tools: derived
+        )
+        simulator = Insika::Evals::Simulator.new(transport: transport, ask: persona_ask, safety: safety)
+
+        conv = "eval-#{golden.id}-#{SecureRandom.hex(4)}" # a fresh session every run (never reused)
+        run = simulator.run(persona: golden.persona, agent: golden.agent, conv: conv)
+        verdict = judge.score_conversation(
+          rubric: golden.rubric, transcript: run.transcript, policy: golden.policy,
+          min_score: golden.min_score || Insika::Evals::Judge::DEFAULT_MIN_SCORE
+        )
+        account_spend(meter)
+
+        { case: golden.id, agent: golden.agent, stop: run.stop.to_s, turns: run.turns,
+          score: verdict&.score, pass: verdict&.pass, reason: verdict&.reason,
+          transcript: run.transcript.map { |m| { role: m[:role], text: m[:text] } } }
+      end
+
+      # A THROWAWAY Executor+Bus, built fresh for THIS call, over the SAME
+      # session/task/checkpoint stores, guardrails, policy engine, context
+      # assembly, skills/prompts and capabilities as the real graph — the
+      # ONLY thing different is the tool registry, which resolves every name
+      # in `derived` to a Simulator::DryRunTool (Evals::EvalProfile.registry)
+      # and everything else exactly as the real one does. Never persisted
+      # anywhere NEW: the simulated turn's session/task rows land in the
+      # SAME stores a `--staging` run's already do (RunPersonaEval's own
+      # never-reused `conv` id is what keeps it from colliding with a real
+      # customer session, same as before this existed).
+      def shadow_runtime(derived)
+        overlay = Insika::Evals::EvalProfile.registry(@tool_registry, side_effect_tools: derived)
+        executor = Insika::Executor.new(
+          context_builder: @graph.context_builder, policy_engine: @graph.policy_engine,
+          middleware: @graph.middleware, hooks: @graph.hooks,
+          tool_registry: overlay, skill_catalog: @graph.skill_catalog, profiles: @graph.profiles,
+          session_store: @graph.session_store, task_store: @graph.task_store,
+          checkpoint_store: @graph.checkpoint_store, event_stream: @graph.event_stream,
+          workflow_registry: @graph.workflow_registry, pending_action_store: @graph.pending_action_store,
+          capability_registry: @graph.capability_registry,
+          tool_catalog: Insika::ToolCatalog.new(tool_registry: overlay),
+          memory_store: @graph.memory_store, settings_store: @settings_store,
+          delegation_store: @graph.delegation_store, channel_delivery: @graph.channel_delivery,
+          llm: llm_context
+        )
+        bus = Insika::CommandBus.new
+        bus.register(:send_message, Insika::Commands::SendMessage.new(
+                                       profiles: @graph.profiles, session_store: @graph.session_store,
+                                       task_store: @graph.task_store, executor: executor,
+                                       inbound_log: @graph.inbound_log, contact_store: @graph.contact_store,
+                                       followup_store: @graph.followup_store, store: @graph.backend
+                                     ))
+        shadow = @graph.dup
+        shadow.bus = bus
+        shadow.executor = executor
+        Insika::Wiring::GraphChat.new(graph: shadow)
+      end
+
+      # -> [String] every case this tool can run: a valid, SIMULATED (persona:)
+      # golden belonging to the CALLING agent's own tenant. A scripted (turns:)
+      # case has nothing to simulate — the CLI skips it too — and a case outside
+      # `calling_tenant` is not merely un-runnable, it never appears at all (the
+      # model cannot even learn another tenant's case ids from the enum).
+      def case_ids
+        @golden_store.for_tenant(calling_tenant).select(&:simulated?).map(&:id)
+      end
+
+      # The CALLING agent's tenant — never the model's, never the target's. The
+      # same "declared command tenant, 'platform' is the single-tenant default"
+      # rule `save_artifact`'s `binding_tenant` uses. Every persona-case
+      # read/list/run in this tool is scoped to it.
+      def calling_tenant
+        Insika::Coercion.presence(turn_context&.dig(:command_tenant)) || "platform"
+      end
+
+      # settings["evals"] -> the configured judge panel, scoped to this
+      # graph's own RubyLLM credentials (never the process-wide default —
+      # a graph's judge spends the graph's own key) and METERED (every judge
+      # call's usage lands in `meter`). nil = nobody configured (the CLI's own
+      # rule: never guess a judge to spend money on).
+      def build_judge(meter)
+        judge, = Insika::Evals::JudgePanel.build(@settings_store.get["evals"] || {}, chat_factory: metered_factory(meter))
+        judge
+      end
+
+      # The persona model — the platform `utility_model` (never a caller-chosen
+      # model: the model does not get to pick what it costs to test itself),
+      # metered the same way. -> callable | {error:}.
+      def build_persona_ask(meter)
+        model = Insika::Coercion.presence(@settings_store.get["utility_model"])
+        return { error: "no persona model — set the platform utility_model (Studio -> Settings)" } if model.nil?
+
+        metered_factory(meter).call(model, nil)
+      end
+
+      # The explicit `llm:` wins (the real wiring passes it — see
+      # `Wiring::Graph.register_persona_eval_tool`); `@runtime.llm` is the
+      # fallback the existing double-based specs rely on (a fake `runtime`
+      # answering `#llm` with no `graph:` at all). nil = the process-wide
+      # RubyLLM constant.
+      def llm_context
+        @llm || (@runtime.respond_to?(:llm) ? @runtime.llm : nil)
+      end
+
+      # ->(model, provider) { ask } — a RubyLLM chat (this graph's own
+      # credentials, temperature 0) whose every `#ask` lands its Message in
+      # `sink` before handing back the text. Same shape as
+      # JudgePanel.ruby_llm_ask, except it does not throw the usage away.
+      # `assume_model_exists` is passed ONLY alongside an explicit `provider`
+      # (the judge panel's own shape — `settings["evals"]["judges"]` always
+      # carries one) — RubyLLM raises ArgumentError on `assume_model_exists:
+      # true` with no provider. The persona's own model (the platform
+      # `utility_model`, a bare ref with no companion provider setting
+      # anywhere in the schema) needs the OPPOSITE: no provider, no
+      # assume_model_exists, so RubyLLM resolves it from its own registry —
+      # exactly how a bare model ref already works everywhere else this
+      # codebase reaches for `utility_model`.
+      def metered_factory(sink)
+        lambda do |model, provider|
+          kwargs = { model: model }
+          if provider
+            kwargs[:provider] = provider
+            kwargs[:assume_model_exists] = true
+          end
+          chat = (llm_context || RubyLLM).chat(**kwargs).with_temperature(0)
+          lambda do |prompt|
+            msg = chat.ask(prompt)
+            sink << msg
+            msg.content
+          end
+        end
+      end
+
+      # -> truthy (a visible skip result) when the CALLING agent's own hard
+      # budget is already at/over a window cap; nil otherwise. Mirrors
+      # ScheduleEngine#budget_exhausted? — a HARD cap skips rather than spends
+      # (a soft one just runs; the ledger's own alert already warns).
+      def budget_skip
+        return nil unless @budget_ledger
+
+        agent_id = turn_context&.dig(:agent_id)
+        profile = agent_id && @profiles[agent_id]
+        budget = profile&.respond_to?(:budget) ? profile.budget : nil
+        return nil if budget.nil? || budget["soft"] == true
+
+        tenant = turn_context&.dig(:command_tenant)
+        window = %w[daily monthly].find do |w|
+          cap = budget[w].to_i
+          cap.positive? && @budget_ledger.current(tenant: tenant, agent: agent_id)[w.to_sym] >= cap
+        end
+        { skipped: true, reason: "budget", window: window } if window
+      end
+
+      # The turn's real billed spend for the persona + judge calls (the A4
+      # rule: total + cached + cache_creation), charged to the CALLING agent —
+      # never the target, whose own turns are billed normally by the edge
+      # limiter, exactly like a real customer's would be.
+      def account_spend(meter)
+        return if @budget_ledger.nil? || meter.empty?
+
+        tokens = meter.sum do |m|
+          m.input_tokens.to_i + m.output_tokens.to_i +
+            (m.respond_to?(:cached_tokens) ? m.cached_tokens.to_i : 0) +
+            (m.respond_to?(:cache_creation_tokens) ? m.cache_creation_tokens.to_i : 0)
+        end
+        return if tokens.zero?
+
+        @budget_ledger.add(tenant: turn_context&.dig(:command_tenant),
+                          agent: turn_context&.dig(:agent_id), by: tokens)
+      end
+    end
+  end
+end

data/lib/insika/tools/save_artifact.rb

@@ -0,0 +1,95 @@
+# frozen_string_literal: true
+
+require "ruby_llm"
+
+module Insika
+  module Tools
+    # `save_artifact` — the agent delivers a page (a report, a digest) to a
+    # destination that survives the channel: title + content in, a URL out,
+    # which it can include in a channel message ("today's report: <url>").
+    #
+    # A REGISTRY tool (not a ChatBuilder system tool): the per-agent
+    # `tools_allow` is the switch — registered `optional: true`, so an agent
+    # that did not name it cannot call it, and nothing global enables it.
+    # The bindings (tenant, agent, task) are the tool INSTANCE's, deposited
+    # by the Executor into `turn_context` like a data-tool's — never
+    # parameters the model types.
+    class SaveArtifact < RubyLLM::Tool
+      description "Save an HTML (or markdown / SVG) page — a report, a digest, " \
+                  "a summary — and get back a URL to share. Use when the answer " \
+                  "is a document the channel message cannot carry."
+      param :title, desc: "Short human-readable title (<= 200 chars)"
+      param :content, desc: "The page content: HTML with inline SVG for charts, " \
+                            "markdown, or SVG. No scripts, no external resources."
+      param :mime, desc: "text/html (default), text/markdown, or image/svg+xml",
+                   required: false
+
+      def name = "save_artifact"
+
+      def initialize(artifact_store:, base_url: nil, signing_key: nil, signing_ttl: nil,
+                     max_bytes: nil, event_stream: nil)
+        @artifact_store = artifact_store
+        @base_url = base_url.to_s.sub(%r{/\z}, "")
+        @signing_key = signing_key
+        @signing_ttl = signing_ttl
+        @max_bytes = max_bytes
+        @event_stream = event_stream
+        super()
+      end
+
+      # Per-turn bindings, deposited by the Executor (ToolAssembly's
+      # `turn_context=` seam — the same one data-tools use). From the TURN,
+      # never from the model (the tenant-lesson: an id the model types is
+      # inventable, and the turn looks right anyway).
+      attr_reader :turn_context
+
+      def turn_context=(ctx)
+        @turn_context = (ctx || {}).each_with_object({}) { |(k, v), acc| acc[k.to_sym] = v }
+      end
+
+      def execute(title:, content:, mime: "text/html")
+        # the deployment's size cap rides the tool instance (INSIKA_ARTIFACT_
+        # MAX_BYTES at wiring); absent -> the store's default.
+        attrs = { tenant: binding_tenant, agent: @turn_context&.dig(:agent_id),
+                  task_id: @turn_context&.dig(:task_id), title: title, mime: mime,
+                  content: content }
+        attrs[:max_bytes] = @max_bytes if @max_bytes
+        record = @artifact_store.create(**attrs)
+        # the authenticated Studio URL is the always-on answer; the signed
+        # link exists ONLY when a key was configured (it shares OUTSIDE the
+        # Studio and expires).
+        url = Insika::ArtifactSigning.url_for(id: record.id, base: @base_url)
+        result = { id: record.id, url: url }
+        signed = Insika::ArtifactSigning.url_for(
+          id: record.id, base: @base_url, key: @signing_key, ttl: @signing_ttl
+        )
+        result[:signed_url] = signed if signed != url
+        emit(record)
+        result
+      rescue Insika::ValidationError => e
+        { error: e.message }
+      end
+
+      private
+
+      # The tenant is the AGENT's tenant: the declared command tenant, or the
+      # deployment's "platform" in single-tenant — never the chat id (a report
+      # belongs to the agent, not to whichever chat ran it), never a parameter
+      # the model types.
+      def binding_tenant
+        declared = @turn_context&.dig(:command_tenant).to_s
+        declared.empty? ? "platform" : declared
+      end
+
+      # :artifact_saved carries ids + title — NEVER the content (a report is
+      # customer data that rides the store, not the events).
+      def emit(record)
+        @event_stream&.emit(Insika::Event.new(
+                              type: :artifact_saved,
+                              data: { id: record.id, title: record.title },
+                              meta: { task_id: @turn_context&.dig(:task_id) }
+                            ))
+      end
+    end
+  end
+end

data/lib/insika/turn_budget.rb

@@ -0,0 +1,91 @@
+# frozen_string_literal: true
+
+module Insika
+  # The turn's tool-call counter — one object, three jobs: count, warn, abort.
+  #
+  # `max_tool_calls` was enforced but never announced: the model learned of the
+  # ceiling only when the turn DIED with `stage: :tool_limit`. A real run in
+  # `round1.db` (task d0421891) burned all 50 calls summing a 40-number list one
+  # `calc` at a time and delivered nothing — the model had no way to know it was
+  # spending a budget at all.
+  #
+  # So the budget speaks before it kills: at 10 / 5 / 2 calls remaining the
+  # engine appends a short notice and the model gets to converge on an answer.
+  #
+  # · **User turn, never system.** The system prefix stays byte-stable, so the
+  #   Anthropic cache breakpoint (`chat_builder.rb`'s `apply_instructions`) keeps
+  #   hitting. A notice in the prompt would bill a cache WRITE every turn.
+  # · **Batch boundary only** (ToolBatch), and **a halted batch receives
+  #   nothing** — the two rules SteerInjector established for mid-turn appends.
+  # · **Off when there is no limit.** `max: nil` = count nothing, warn nothing,
+  #   abort never.
+  #
+  # KNOWN REACH (measured against DeepSeek, 2026-08-30): a model that announces
+  # ONE batch bigger than the whole budget — 30 independent tool calls in a single
+  # assistant message — never reaches a boundary before the abort, so it gets no
+  # notice. Nothing can be appended mid-batch, so that shape is out of reach by
+  # construction; it is also the shape where the model already knows what it asked
+  # for. What this catches is the SEQUENTIAL burn, which is the one `round1.db`
+  # actually shows: 46 `calc` calls, one per step.
+  class TurnBudget
+    # The three notices, verbatim and escalating — one constant, so a transcript
+    # reader can recognize an engine sentence without an origin stamp (chat
+    # messages carry none). Keyed by calls REMAINING after the call being made.
+    NOTICES = {
+      10 => "Tool budget: 10 of your %<max>d tool calls for this turn are left. " \
+            "Start converging — prefer one call that answers the question over several that circle it.",
+      5 => "Tool budget: 5 tool calls left in this turn. " \
+           "Drop anything optional and gather only what the answer actually needs.",
+      2 => "Tool budget: 2 tool calls left in this turn. " \
+           "Consolidate what you already have and answer now — do not start new work."
+    }.freeze
+
+    def self.notice(remaining, max) = format(NOTICES.fetch(remaining), max: max)
+
+    # chat: the turn's chat — must answer #add_message (the boundary append).
+    # max:  the profile's max_tool_calls. nil = no budget: no notice, no abort.
+    # emit: ->(type, data) — the Executor's emitter, bound to the task.
+    def initialize(chat:, max:, emit:)
+      @chat = chat
+      @max = max
+      @emit = emit
+      @calls = 0
+      @batch = ToolBatch.new
+      @pending = nil # a threshold was crossed; waiting for the batch boundary
+      @warned = []   # thresholds already spent (each fires at most once a turn)
+    end
+
+    # From ChatBuilder's before_tool_call, FIRST thing: counts the call about to
+    # run and raises when it is past the ceiling. The raise is the pre-existing
+    # guard-rail, moved here so the count has exactly one owner.
+    def tool_call
+      return if @max.nil?
+
+      @calls += 1
+      if @calls > @max
+        raise Insika::TimeoutError.new("tool call limit exceeded (#{@max})", stage: :tool_limit)
+      end
+
+      remaining = @max - @calls
+      @pending = remaining if NOTICES.key?(remaining) && !@warned.include?(remaining)
+    end
+
+    # From ChatBuilder's after_tool_result, with the RAW result.
+    def tool_result(result) = @batch.halt!(result)
+
+    # RubyLLM after_message: delivers the armed notice the moment the batch of
+    # tool results closes.
+    def message_ended(message)
+      return unless @batch.closed?(message)
+      return if @pending.nil?
+
+      remaining = @pending
+      @pending = nil
+      return if @batch.halted? # nothing will read it (halt_when): drop, never deliver
+
+      @warned << remaining
+      @chat.add_message(role: :user, content: self.class.notice(remaining, @max))
+      @emit.call(:tool_budget_warned, { remaining: remaining, max: @max })
+    end
+  end
+end

data/lib/insika/turn_output.rb

@@ -33,7 +33,7 @@ module Insika
   #   answer; the fragment is still on the stream as `:intermediate` for whoever is
   #   debugging it.
   #
-  # `halt_when` (PR #130) is the one case where narration IS the turn: the tool
+  # `halt_when` is the one case where narration IS the turn: the tool
   # already answered the customer, and the model's lead-in ("vou te inscrever
   # agora") is all the turn is worth. That text is retained and published by the
   # Executor's halt branch — see #halt_text.

data/lib/insika/turn_state.rb

@@ -31,10 +31,15 @@ module Insika
                   :message_source,     # WS9: how the turn's message entered (:voice when it came
                   #                      from a transcribed audio part; nil = typed). Rides the
                   #                      terminal event additively.
-                   :media_attachments,  # WS9: the ask's attachments (image parts); nil = none.
-                  #                      The provider bills them; usage flows like any ask.
-                  #                      The first image URL also lands on turn_context[:image_url]
-                  #                      for data/HTTP tools (`{{ctx.image_url}}`).
+                   :media_attachments,  # WS9: the ask's attachments (image + document parts);
+                  #                      nil = none. The provider bills them; usage flows like
+                  #                      any ask. The first URL of each kind also lands on
+                  #                      turn_context (`{{ctx.image_url}}` / `{{ctx.document_url}}`).
+                  :image_attachments,  # WS9: the IMAGE subset of media_attachments (nil = no
+                  #                      inbound image this turn). The default edit SOURCE for
+                  #                      generate_image — kept separate from
+                  #                      media_attachments because that one may also hold a
+                  #                      document, which is never a paint(with:) source.
                   :output_parts,       # WS9 (saída): media the turn GENERATED, as additive
                   #                      parts ({ type:, mime_type:, base64:, model: }). Rides
                   #                      the terminal event (output_parts) and the /v1/responses
@@ -114,6 +119,12 @@ module Insika
     # rules the run started under.
     attr_accessor :queue_policy
 
+    # Internal: the run's SteerInjector, or nil when steering is off (or the chat
+    # cannot host the boundary). Rebuilt per ATTEMPT — a WS3 fallback builds a new
+    # chat, and the injector belongs to the chat it appends to. The Executor reaches
+    # for it at the end of stage 6 to absorb whatever no tool boundary took.
+    attr_accessor :steer_injector
+
     # Internal: true when this turn re-enters the pipeline via
     # resume_task/recovery. The EdgeLimiter reads it to NEVER re-count or block a
     # turn that was already admitted — a crash/pause under a saturated window must

data/lib/insika/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module Insika
-  VERSION = "0.3.0"
+  VERSION = "0.8.0"
 end