insika 0.0.1 → 0.1.0

data/lib/insika/commands/import_tools.rb

@@ -0,0 +1,81 @@
+# frozen_string_literal: true
+
+require "time"
+
+module Insika
+  module Commands
+    # BATCH ingestion of data-tools from a manifest (Phase 7, Step B).
+    # Normalizes each tool (defaults + envelope adapter + endpoint→url + secret/
+    # env) via ToolManifest, UPSERTs it into the ToolStore, and RELOADS the overlay +
+    # catalog ONCE at the end — takes effect without a restart (NF3). Idempotent
+    # (re-importing reconciles). Injects the deployment's `{{secret.*}}`/`{{env.*}}`
+    # resolvers (D6/open-q2): the secret NEVER comes in the manifest.
+    #
+    # ISOLATED PARTIAL FAILURE (R4): a malformed tool (invalid envelope, missing
+    # endpoint, unconfigured secret, collision with a code tool, invalid url)
+    # does NOT bring down the batch — it becomes an entry in `errors[]`. Only a STRUCTURAL error in the
+    # manifest (defaults/tools of the wrong type) raises (transport -> 422).
+    # Per-tool report in the shape of the Phase 6 pack importer.
+    #   -> { version, created: [names], updated: [names], errors: [{tool,error}] }
+    class ImportTools
+      def initialize(tool_store:, registry:, tool_catalog:, event_stream:, secrets: ENV, env: ENV)
+        @tool_store = tool_store
+        @registry = registry
+        @tool_catalog = tool_catalog
+        @event_stream = event_stream
+        @secrets = secrets
+        @env = env
+      end
+
+      def call(command)
+        manifest = Insika::ToolManifest.from_h(command.payload) # structural -> 422
+        report = { version: manifest.version, created: [], updated: [], errors: [] }
+
+        manifest.tools.each_with_index do |raw, i|
+          import_one(manifest, raw, i, report)
+        end
+
+        reload_hot unless report[:created].empty? && report[:updated].empty?
+        emit(report)
+        report
+      end
+
+      private
+
+      def import_one(manifest, raw, index, report)
+        defn = manifest.definition_for(raw, secrets: @secrets, env: @env)
+        name = defn["name"].to_s
+        raise Insika::ValidationError, "'#{name}' is already a code tool" if @registry.code_tool?(name)
+
+        existed = !@tool_store.get(name).nil?
+        @tool_store.write(defn)
+        (existed ? report[:updated] : report[:created]) << name
+      rescue Insika::Error => e
+        report[:errors] << { tool: tool_label(raw, index), error: e.message }
+      end
+
+      def reload_hot
+        @registry.reload
+        @tool_catalog.reload
+      end
+
+      # Tool name for the error report; falls back to the index when the envelope
+      # didn't even carry a name (keeps the error entry from being anonymous).
+      def tool_label(raw, index)
+        h = raw.is_a?(Hash) ? raw : {}
+        name = h["name"] || h[:name] || h.dig("function", "name") || h.dig(:function, :name)
+        Insika::Coercion.presence(name) || "#<tool ##{index}>"
+      end
+
+      # Emits only COUNTS + names (never headers/secrets): 0 leakage.
+      def emit(report)
+        @event_stream.emit(Insika::Event.new(
+                             type: :tools_imported,
+                             data: { created: report[:created].size, updated: report[:updated].size,
+                                     errors: report[:errors].size },
+                             meta: { at: Time.now.utc.iso8601 }
+                           ))
+      end
+    end
+  end
+end

data/lib/insika/commands/memory_add_note.rb

@@ -0,0 +1,32 @@
+# frozen_string_literal: true
+
+require "time"
+
+module Insika
+  module Commands
+    # Control command: appends a free-form note
+    # (append-only) to the agent's memory (MemoryStore, `notes` layer). Scoped
+    # by `tenant`. Synchronous; does not create a Task. -> Note.
+    class MemoryAddNote
+      def initialize(memory_store:, event_stream:)
+        @memory_store = memory_store
+        @event_stream = event_stream
+      end
+
+      def call(command)
+        p = AgentPayload.symbolize(command.payload)
+        text = AgentPayload.presence(p[:text])
+        raise Insika::ValidationError, "text is required" if text.nil?
+
+        tenant = AgentPayload.presence(p[:tenant]) || command.meta[:tenant]
+        note = @memory_store.add_note(tenant: tenant, text: text)
+        @event_stream.emit(Insika::Event.new(
+                             type: :memory_note_added,
+                             data: { tenant: tenant, note_id: note.id },
+                             meta: { at: Time.now.utc.iso8601 }
+                           ))
+        note
+      end
+    end
+  end
+end

data/lib/insika/commands/memory_forget_fact.rb

@@ -0,0 +1,32 @@
+# frozen_string_literal: true
+
+require "time"
+
+module Insika
+  module Commands
+    # Control command: forgets (removes) a fact from the
+    # agent's memory. Idempotent: forgetting something that doesn't exist is not an error
+    # (`existed: false`). Scoped by `tenant`. -> { existed: bool }.
+    class MemoryForgetFact
+      def initialize(memory_store:, event_stream:)
+        @memory_store = memory_store
+        @event_stream = event_stream
+      end
+
+      def call(command)
+        p = AgentPayload.symbolize(command.payload)
+        key = AgentPayload.presence(p[:key])
+        raise Insika::ValidationError, "key is required" if key.nil?
+
+        tenant = AgentPayload.presence(p[:tenant]) || command.meta[:tenant]
+        existed = @memory_store.forget_fact(tenant: tenant, key: key)
+        @event_stream.emit(Insika::Event.new(
+                             type: :memory_fact_forgotten,
+                             data: { tenant: tenant, key: key, existed: existed },
+                             meta: { at: Time.now.utc.iso8601 }
+                           ))
+        { existed: existed }
+      end
+    end
+  end
+end

data/lib/insika/commands/memory_put_fact.rb

@@ -0,0 +1,35 @@
+# frozen_string_literal: true
+
+require "time"
+
+module Insika
+  module Commands
+    # Control command: writes a stable fact to the agent's
+    # memory (MemoryStore, `profile` layer). Until now memory was only written
+    # from WITHIN the turn (the `remember` tool); this Command is the HTTP surface the
+    # Studio uses to edit facts directly. Scoped by `tenant` (nil = _default).
+    # Synchronous; does not create a Task. -> Fact.
+    class MemoryPutFact
+      def initialize(memory_store:, event_stream:)
+        @memory_store = memory_store
+        @event_stream = event_stream
+      end
+
+      def call(command)
+        p = AgentPayload.symbolize(command.payload)
+        key = AgentPayload.presence(p[:key])
+        raise Insika::ValidationError, "key is required" if key.nil?
+        raise Insika::ValidationError, "value is required" if p[:value].nil?
+
+        tenant = AgentPayload.presence(p[:tenant]) || command.meta[:tenant]
+        fact = @memory_store.put_fact(tenant: tenant, key: key, value: p[:value])
+        @event_stream.emit(Insika::Event.new(
+                             type: :memory_fact_put,
+                             data: { tenant: tenant, key: key },
+                             meta: { at: Time.now.utc.iso8601 }
+                           ))
+        fact
+      end
+    end
+  end
+end

data/lib/insika/commands/pause_task.rb

@@ -0,0 +1,29 @@
+# frozen_string_literal: true
+
+module Insika
+  module Commands
+    # Control command: posts `:pause` to the Task's in-process
+    # mailbox and responds synchronously. Payload `{ task_id: String }` -> returns Task.
+    #
+    # Cooperative: the one that transitions `running -> paused` and emits
+    # `:task_paused` is the task's fiber when it drains at the next boundary — NEVER this
+    # handler. Pausing a task with no live fiber (terminal/orphaned) is an idempotent no-op.
+    class PauseTask
+      def initialize(task_store:, executor:)
+        @task_store = task_store
+        @executor = executor
+      end
+
+      def call(command)
+        task_id = command.payload[:task_id] || command.payload["task_id"]
+        raise Insika::ValidationError, "task_id is required" if task_id.to_s.empty?
+
+        task = @task_store.find(task_id)
+        raise Insika::NotFoundError, "task '#{task_id}' not found" unless task
+
+        @executor.pause(task_id) # no-op if there is no live fiber in this process
+        @task_store.find(task_id) # current state after the post
+      end
+    end
+  end
+end

data/lib/insika/commands/resolve_refinement.rb

@@ -0,0 +1,126 @@
+# frozen_string_literal: true
+
+require "time"
+
+module Insika
+  module Commands
+    # Control command (RFC-0013 §3.6): the human's answer to a gated proposal.
+    #
+    #   approve -> each edit is written through `AgentFileStore#write`, which pushes
+    #              the previous content into `history`. Rollback is therefore already
+    #              built: `restore_agent_file` with index 0, the same button the file
+    #              editor has had since the Studio existed.
+    #   reject  -> recorded on the run with the operator's note. The finding must
+    #              re-surface with new evidence before anything is proposed again;
+    #              nothing retries on its own.
+    #
+    # Payload `{ run_id:, decision: "approved"|"rejected", operator?, note? }`.
+    # -> the resolved Run.
+    #
+    # **The candidate is re-validated against the CURRENT files before anything is
+    # written.** The gate scored a snapshot; an operator approves minutes or days
+    # later, and in between a human may have edited the same file in the Studio.
+    # Applying an edit whose `before` no longer matches would silently overwrite that
+    # person's work — the exact failure the anchored format exists to prevent, thrown
+    # away at the last step. A stale approval is refused and the operator re-gates.
+    class ResolveRefinement
+      def initialize(profiles:, refinement_store:, agent_file_store:, event_stream:)
+        @profiles = ProfileSource.coerce(profiles)
+        @runs = refinement_store
+        @agent_files = agent_file_store
+        @event_stream = event_stream
+      end
+
+      def call(command)
+        p = AgentPayload.symbolize(command.payload)
+        run_id = AgentPayload.presence(p[:run_id])
+        decision = AgentPayload.presence(p[:decision]).to_s
+        raise Insika::ValidationError, "run_id is required" if run_id.nil?
+
+        run = @runs.find(run_id) || (raise Insika::NotFoundError, "refinement run not found: #{run_id}")
+        operator = p[:operator] || command.meta[:operator]
+
+        case decision
+        when "rejected"
+          resolved = @runs.resolve(run.id, decision: :rejected, operator: operator, note: p[:note])
+          emit(:refinement_rejected, resolved, files: [])
+          resolved
+        when "approved"
+          apply(run, operator: operator, note: p[:note])
+        else
+          raise Insika::ValidationError, "invalid decision: #{decision} (approved|rejected)"
+        end
+      end
+
+      private
+
+      def apply(run, operator:, note:)
+        unless run.awaiting_approval?
+          raise ArgumentError, "run #{run.id} is #{run.status}, expected awaiting_approval"
+        end
+
+        config = refinement_config(run.agent_id)
+        contents = current_files(run.agent_id)
+        candidate = rebuild(run, config, contents)
+
+        written = candidate.apply(contents)
+        written.each { |file, body| @agent_files.write(run.agent_id, file, body) }
+
+        # Recorded AFTER the writes land: a crash in between leaves the run awaiting
+        # approval and the operator approves again. Re-approving re-validates against
+        # the (now edited) files and refuses as stale, which is a confusing message but
+        # a safe outcome — recording `applied` before writing would be a lie the
+        # history could not correct.
+        resolved = @runs.resolve(run.id, decision: :applied, operator: operator, note: note)
+        emit(:refinement_applied, resolved, files: written.keys, edits: candidate.edits.size)
+        resolved
+      end
+
+      # Re-runs the SAME validator the gate used, against the files as they are now.
+      # Anything that drifted comes back as a drop, and any drop at all refuses the
+      # apply: a partial application would land some edits and silently skip others,
+      # leaving a prompt in a state no one reviewed and the gate never scored.
+      def rebuild(run, config, contents)
+        allowlist = Array(config["files"]).map(&:to_s)
+        raw = { "proposer" => (run.candidate || {})["proposer"],
+                "rationale" => (run.candidate || {})["rationale"],
+                "edits" => run.edits }
+        candidate = Refinement::CandidateBuilder.build(raw, allowlist: allowlist,
+                                                            contents: contents, limits: config)
+
+        if candidate.dropped.any? || candidate.edits.size != run.edits.size
+          reasons = candidate.dropped.map { |d| "#{d.file}: #{d.reason}" }
+          raise Insika::ValidationError,
+                "the files changed since this proposal was gated, so it no longer applies " \
+                "(#{reasons.join('; ')}). Re-run the gate against the current files."
+        end
+
+        candidate
+      end
+
+      def refinement_config(agent_id)
+        profile = @profiles[agent_id] ||
+                  (raise Insika::NotFoundError, "agent '#{agent_id}' not configured")
+        raw = profile.respond_to?(:refinement) ? profile.refinement : nil
+        raw.is_a?(Hash) ? Coercion.deep_stringify(raw) : {}
+      end
+
+      def current_files(agent_id)
+        @agent_files.list(agent_id).each_with_object({}) do |name, acc|
+          acc[name] = @agent_files.read(agent_id, name).to_s
+        end
+      end
+
+      # File NAMES are fine on the stream (the operator needs to know what changed);
+      # their content is not, and never appears here.
+      def emit(type, run, **data)
+        @event_stream.emit(Insika::Event.new(
+                             type: type,
+                             data: { agent: run.agent_id, run_id: run.id, status: run.status.to_s,
+                                     by: run.decision && run.decision["by"], **data },
+                             meta: { at: Time.now.utc.iso8601 }
+                           ))
+      end
+    end
+  end
+end

data/lib/insika/commands/restore_agent_file.rb

@@ -0,0 +1,36 @@
+# frozen_string_literal: true
+
+require "time"
+
+module Insika
+  module Commands
+    # Control command: restores an old version of a
+    # prompt file as the current content (a new write — history is
+    # linear, no rewinding). `version` = index into `versions` (0 = most recent
+    # old one). -> { agent_id, file, updated_at }.
+    class RestoreAgentFile
+      def initialize(profile_source:, agent_file_store:, event_stream:)
+        @profile_source = profile_source
+        @agent_files = agent_file_store
+        @event_stream = event_stream
+      end
+
+      def call(command)
+        p = AgentPayload.symbolize(command.payload)
+        agent_id = AgentPayload.presence(p[:agent_id])
+        file = AgentPayload.presence(p[:file])
+        raise Insika::ValidationError, "agent_id is required" if agent_id.nil?
+        raise Insika::ValidationError, "file is required" if file.nil?
+        raise Insika::ValidationError, "version is required" if p[:version].nil?
+
+        entry = @agent_files.restore(agent_id, file, p[:version])
+        @event_stream.emit(Insika::Event.new(
+                             type: :agent_file_restored,
+                             data: { agent_id: agent_id, file: file, version: Integer(p[:version]) },
+                             meta: { at: Time.now.utc.iso8601 }
+                           ))
+        { agent_id: agent_id, file: file, updated_at: entry["updated_at"] }
+      end
+    end
+  end
+end

data/lib/insika/commands/restore_data_tool.rb

@@ -0,0 +1,34 @@
+# frozen_string_literal: true
+
+require "time"
+
+module Insika
+  module Commands
+    # Restores an old version of a data tool (a new write) and reloads
+    # overlay + catalog. The ToolStore raises NotFound/Validation. -> { name,
+    # definition (masked) }.
+    class RestoreDataTool
+      def initialize(tool_store:, registry:, tool_catalog:, event_stream:)
+        @tool_store = tool_store
+        @registry = registry
+        @tool_catalog = tool_catalog
+        @event_stream = event_stream
+      end
+
+      def call(command)
+        p = AgentPayload.symbolize(command.payload)
+        name = AgentPayload.presence(p[:name])
+        raise Insika::ValidationError, "name is required" if name.nil?
+
+        masked = @tool_store.restore(name, p[:index])
+        @registry.reload
+        @tool_catalog.reload
+        @event_stream.emit(Insika::Event.new(
+                             type: :data_tool_restored, data: { name: name },
+                             meta: { at: Time.now.utc.iso8601 }
+                           ))
+        { name: name, definition: masked }
+      end
+    end
+  end
+end

data/lib/insika/commands/restore_system_file.rb

@@ -0,0 +1,31 @@
+# frozen_string_literal: true
+
+require "time"
+
+module Insika
+  module Commands
+    # Control command: restores an old version of a
+    # global system file as the current content (a new write — linear
+    # history). -> { file, updated_at }.
+    class RestoreSystemFile
+      def initialize(system_file_store:, event_stream:)
+        @system_files = system_file_store
+        @event_stream = event_stream
+      end
+
+      def call(command)
+        p = AgentPayload.symbolize(command.payload)
+        file = AgentPayload.presence(p[:file])
+        raise Insika::ValidationError, "file is required" if file.nil?
+        raise Insika::ValidationError, "version is required" if p[:version].nil?
+
+        entry = @system_files.restore(file, p[:version])
+        @event_stream.emit(Insika::Event.new(
+                             type: :system_file_restored, data: { file: file, version: p[:version].to_s },
+                             meta: { at: Time.now.utc.iso8601 }
+                           ))
+        { file: file, updated_at: entry["updated_at"] }
+      end
+    end
+  end
+end

data/lib/insika/commands/resume_task.rb

@@ -0,0 +1,85 @@
+# frozen_string_literal: true
+
+module Insika
+  module Commands
+    # Turn command: resumes a task from the latest checkpoint. Crash-recovery
+    # and manual resume both use THIS same path (Recovery only discovers and dispatches).
+    # Re-executes the entire checkpointed turn; non-idempotent tools that already
+    # completed are skipped via the side-effect registry.
+    class ResumeTask
+      def initialize(profiles:, task_store:, checkpoint_store:, executor:)
+        @profiles = ProfileSource.coerce(profiles)
+        @task_store = task_store
+        @checkpoint_store = checkpoint_store
+        @executor = executor
+      end
+
+      def call(command)
+        task_id = (command.payload[:task_id] || command.payload["task_id"]).to_s
+        raise Insika::ValidationError, "task_id is required" if task_id.empty?
+
+        task = @task_store.find(task_id) ||
+               (raise Insika::NotFoundError, "task '#{task_id}' not found")
+
+        # IN-PROCESS RESUME: a :paused task whose fiber is STILL alive (blocked
+        # on await) — do NOT re-dispatch (spawn would duplicate the fiber). Just post :resume;
+        # the fiber transitions paused->running and continues. (A live :waiting is resolved
+        # by ApproveAction, not here.)
+        if task.status == :paused && @executor.running?(task_id)
+          @executor.resume_live(task_id)
+          return { task_id: task_id }
+        end
+
+        # :queued: a turn that was in the SessionActor queue and never
+        # started at crash time (no checkpoint) — recovering = RUN from scratch, from the
+        # original Command. Profile comes from the agent in the Command itself.
+        if task.status == :queued
+          @executor.spawn_in_session(task, profile: profile_for(task), resume_from: nil)
+          return { task_id: task_id }
+        end
+
+        # RE-DISPATCH (crash-resume): no live fiber, re-executes from the checkpoint.
+        # resume requires a checkpoint; without one the task is unrecoverable (Recovery
+        # would already have marked it :failed during the sweep).
+        checkpoint = @checkpoint_store.latest(task_id) ||
+                     (raise Insika::ValidationError,
+                            "task '#{task_id}' has no checkpoint — unrecoverable")
+
+        check_eligibility!(task)
+
+        # profile comes from the checkpoint (agent_id): the agent may have been removed from
+        # the config between the crash and boot -> fail loudly and clearly.
+        profile = @profiles[checkpoint.agent_id] ||
+                  (raise Insika::NotFoundError, "agent '#{checkpoint.agent_id}' not configured")
+
+        @executor.spawn_in_session(task, profile: profile, resume_from: checkpoint)
+        { task_id: task_id }
+      end
+
+      private
+
+      # Profile for re-running a :queued task: from the agent in the persisted Command
+      # (there is no checkpoint). NotFoundError if the agent left the config.
+      def profile_for(task)
+        payload = task.command["payload"] || task.command[:payload] || {}
+        agent = (payload["agent"] || payload[:agent]).to_s
+        @profiles[agent] || (raise Insika::NotFoundError, "agent '#{agent}' not configured")
+      end
+
+      # Eligibility matrix: paused/waiting always; running only when
+      # orphaned (no live fiber IN THIS process — single-node); :queued is handled
+      # earlier (re-run); terminal states are not resumable.
+      def check_eligibility!(task)
+        case task.status
+        when :paused, :waiting
+          nil
+        when :running
+          raise Insika::ValidationError, "task '#{task.id}' is running" if @executor.running?(task.id)
+        else # terminal states (:completed, :failed, :cancelled)
+          raise Insika::ValidationError,
+                "task '#{task.id}' with status '#{task.status}' is not resumable"
+        end
+      end
+    end
+  end
+end

data/lib/insika/commands/run_refinement.rb

@@ -0,0 +1,133 @@
+# frozen_string_literal: true
+
+require "time"
+
+module Insika
+  module Commands
+    # Control command (RFC-0013 phase A): reads a window of the agent's real traffic
+    # and records a ranked failure REPORT. Synchronous — it only scans durable stores
+    # (no provider call, no fiber), so it answers with the Run and does not create a
+    # Task. It is the ONLY way a refinement run starts: the CLI, the Studio button
+    # and any external cron all dispatch this one command (§3.10 — there is no
+    # scheduler in the engine).
+    #
+    # Payload:
+    #   agent          (required) agent id
+    #   since          ISO8601 — only turns from this instant on
+    #   last_sessions  Integer — the N most recent conversations instead
+    #   full           truthy — ignore the previous run and use the full window
+    #   max_findings   Integer cap on the report
+    #   exclude_sessions [prefix] — session ids to drop (load tests, debug traffic)
+    #
+    # Window resolution (first that applies): explicit payload -> INCREMENTAL (since
+    # the previous run for this agent, unless `full`) -> the agent's configured
+    # `refinement.window` -> the collector's default.
+    #
+    # Phase A writes NOTHING to the agent, so it needs no opt-in: an absent
+    # `refinement` config reads as report-only. Only `propose`/`auto_apply` (phase C)
+    # require the operator to enable them explicitly.
+    class RunRefinement
+      READ_ONLY_MODES = %w[report propose auto_apply].freeze
+
+      def initialize(profiles:, refinement_store:, collector:, event_stream:)
+        @profiles = ProfileSource.coerce(profiles)
+        @refinement_store = refinement_store
+        @collector = collector
+        @event_stream = event_stream
+      end
+
+      def call(command)
+        p = AgentPayload.symbolize(command.payload)
+        agent = AgentPayload.presence(p[:agent])
+        raise Insika::ValidationError, "agent is required" if agent.nil?
+
+        profile = @profiles[agent] ||
+                  (raise Insika::NotFoundError, "agent '#{agent}' not configured")
+        config = refinement_config(profile)
+        validate_mode!(config)
+
+        window = resolve_window(agent, p, config)
+        run = @refinement_store.create(agent_id: agent, window: window)
+        emit(:refinement_started, agent: agent, run_id: run.id, window: window)
+
+        begin
+          report = @collector.collect(
+            agent_id: agent, max_findings: max_findings(p, config),
+            exclude_sessions: exclude_sessions(p, config), **collect_args(window)
+          )
+          done = @refinement_store.complete(run.id, findings: report.findings,
+                                            excluded: report.excluded)
+          emit(:refinement_report, agent: agent, run_id: run.id, status: done.status,
+                                   findings: done.findings_count,
+                                   sessions: report.sessions_seen, turns: report.turns_seen,
+                                   excluded: report.excluded)
+          done
+        rescue StandardError => e
+          @refinement_store.fail(run.id, error: e.message)
+          raise
+        end
+      end
+
+      private
+
+      def refinement_config(profile)
+        raw = profile.respond_to?(:refinement) ? profile.refinement : nil
+        raw.is_a?(Hash) ? raw : {}
+      end
+
+      # An unknown mode is a config typo, and a typo that silently degrades to
+      # "report" would be the kind of quiet wrong the strict-config rule exists to
+      # prevent (item 23).
+      def validate_mode!(config)
+        mode = AgentPayload.presence(config["mode"]) || "report"
+        return if READ_ONLY_MODES.include?(mode)
+
+        raise Insika::ValidationError,
+              "unknown refinement mode: #{mode} (expected #{READ_ONLY_MODES.join(', ')})"
+      end
+
+      def resolve_window(agent, payload, config)
+        since = AgentPayload.presence(payload[:since])
+        return { "since" => since } if since
+        return { "last_sessions" => Integer(payload[:last_sessions]) } if payload[:last_sessions]
+
+        # `full` arrives as true (internal dispatch) or "1" (Studio form) — one
+        # reading of a boolean, the same one item #131 settled on.
+        unless Insika::EnvSchema.truthy?(payload[:full])
+          previous = @refinement_store.latest_for(agent)
+          return { "since" => previous.started_at } if previous&.started_at
+        end
+
+        configured = config.dig("window", "last_sessions")
+        configured ? { "last_sessions" => Integer(configured) } : {}
+      end
+
+      # Window (as recorded) -> collector kwargs. {} = the collector's own default.
+      def collect_args(window)
+        return { since: window["since"] } if window["since"]
+        return { last_sessions: window["last_sessions"] } if window["last_sessions"]
+
+        {}
+      end
+
+      def max_findings(payload, config)
+        raw = payload[:max_findings] || config["max_findings"]
+        raw ? Integer(raw) : Refinement::EvidenceCollector::DEFAULT_MAX_FINDINGS
+      end
+
+      # Session-id prefixes to drop (load tests, debug conversations). Configured per
+      # agent; a payload list overrides it for one run. Never defaulted — the report
+      # does not get to decide what counts as real traffic.
+      def exclude_sessions(payload, config)
+        Array(payload[:exclude_sessions] || config["exclude_sessions"]).map(&:to_s)
+      end
+
+      def emit(type, **data)
+        @event_stream.emit(Insika::Event.new(
+                             type: type, data: data,
+                             meta: { at: Time.now.utc.iso8601 }
+                           ))
+      end
+    end
+  end
+end