insika 0.0.1 → 0.2.0

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/revoke_token.rb

@@ -0,0 +1,39 @@
+# frozen_string_literal: true
+
+module Insika
+  module Commands
+    # WS1: revokes ONE token by id. The edge resolves tokens by hash, so the
+    # plaintext is not needed to kill a credential. Idempotent: revoking an
+    # already-revoked or unknown id -> { revoked: false }, never an error.
+    # -> { id:, revoked: bool }.
+    class RevokeToken
+      def initialize(token_store:, event_stream:)
+        @token_store = token_store
+        @event_stream = event_stream
+      end
+
+      def call(command)
+        raise Insika::ValidationError, "token commands are operator-only" if command.meta[:tenant]
+
+        id = Insika::Coercion.presence(
+          command.payload[:token_id] || command.payload["token_id"]
+        )
+        raise Insika::ValidationError, "token_id is required" if id.nil?
+
+        revoked = @token_store.revoke(id)
+        emit(id, revoked)
+        { id: id, revoked: revoked }
+      end
+
+      private
+
+      def emit(token_id, revoked)
+        @event_stream.emit(Insika::Event.new(
+                             type: :tenant_token_revoked,
+                             data: { token_id: token_id, revoked: revoked },
+                             meta: { at: Time.now.utc.iso8601 }
+                           ))
+      end
+    end
+  end
+end

data/lib/insika/commands/rotate_tenant_token.rb

@@ -0,0 +1,43 @@
+# frozen_string_literal: true
+
+module Insika
+  module Commands
+    # WS1: rotates a tenant's credential — revokes every active token of the
+    # tenant and issues a fresh one, in ONE transaction (a crashed half-rotation
+    # must never leave the tenant with nothing valid). Only the tenant's own
+    # tokens are touched; the operator token and other tenants are untouched.
+    # -> { revoked: n, token: Issue.to_h }.
+    class RotateTenantToken
+      def initialize(token_store:, event_stream:)
+        @token_store = token_store
+        @event_stream = event_stream
+      end
+
+      def call(command)
+        raise Insika::ValidationError, "token commands are operator-only" if command.meta[:tenant]
+
+        tenant_id = Insika::Coercion.presence(
+          command.payload[:tenant_id] || command.payload["tenant_id"]
+        )
+        raise Insika::ValidationError, "tenant_id is required" if tenant_id.nil?
+
+        label = command.payload[:label] || command.payload["label"] || "default"
+        result = @token_store.rotate(tenant_id: tenant_id, label: label)
+        issue = result[:issue]
+        emit(issue.id, tenant_id, result[:revoked])
+        { revoked: result[:revoked],
+          token: { token: issue.token, id: issue.id, tenant_id: tenant_id, label: label.to_s } }
+      end
+
+      private
+
+      def emit(token_id, tenant_id, revoked)
+        @event_stream.emit(Insika::Event.new(
+                             type: :tenant_token_rotated,
+                             data: { token_id: token_id, tenant_id: tenant_id, revoked: revoked },
+                             meta: { at: Time.now.utc.iso8601 }
+                           ))
+      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: 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 (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.
+    #
+    # writes NOTHING to the agent, so it needs no opt-in: an absent
+    # `refinement` config reads as report-only. Only `propose`/`auto_apply`
+    # 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.
+      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

data/lib/insika/commands/send_message.rb

@@ -0,0 +1,150 @@
+# frozen_string_literal: true
+
+module Insika
+  module Commands
+    # Canonical turn command: validates everything synchronously, creates the Task, fires
+    # the fiber and responds `{task_id:}` immediately — the result flows through the Event
+    # Stream. Validations that fail do NOT create a Task
+    # (ValidationError/NotFoundError -> direct HTTP response).
+    class SendMessage
+      # surfaces whose response can carry the "you do not own the reply"
+      # verdict (`merged` for `collect`, `steered` for `steer`), and therefore the only
+      # ones where a message may join another turn. `/v1/responses` is NOT here: its body
+      # is OpenAI-shaped SSE with nowhere to put the field, and it is frozen because a
+      # live consumer speaks it. Joining a caller that cannot hear the verdict makes it
+      # deliver the same answer once per message, which is worse than not joining at all.
+      # Channels declare themselves by `channel:<id>` once lands.
+      COALESCABLE_TRANSPORTS = %i[http:json].freeze
+
+      # `inbound_log` is the retry window for channel event ids.
+      # nil = no dedup (every surface that does not send an `event_id`, which is all
+      # of them today), and a caller that cannot supply a stable id gets
+      # at-least-once turns rather than a content hash pretending to be dedup.
+      def initialize(profiles:, session_store:, task_store:, executor:, inbound_log: nil)
+        @profiles = ProfileSource.coerce(profiles)
+        @session_store = session_store
+        @task_store = task_store
+        @executor = executor
+        @inbound_log = inbound_log
+      end
+
+      def call(command)
+        p = normalize(command.payload) # accepts string and symbol keys
+
+        agent = p[:agent].to_s
+        raise Insika::ValidationError, "agent is required" if agent.empty?
+
+        profile = @profiles[agent] ||
+                  (raise Insika::NotFoundError, "agent '#{agent}' not configured")
+
+        message = p[:message]
+        raise Insika::ValidationError, "message is required and non-empty" if message.to_s.strip.empty?
+
+        # session_id XOR history (both -> error; neither -> one-shot).
+        if p[:session_id] && p[:history]
+          raise Insika::ValidationError, "session_id and history are mutually exclusive"
+        end
+
+        validate_history!(p[:history]) if p[:history]
+        # WHO wrote this message (MessageOrigin). Absent = a customer typed it, which
+        # is what a turn has always meant. Refused here rather than downstream: a
+        # typo'd origin would read as absent, and a marker that silently means
+        # "unmarked" is worse than none — it looks like the filtering is on.
+        Insika::MessageOrigin.parse!(p[:origin])
+        if p[:session_id]
+          @session_store.find(p[:session_id]) ||
+            (raise Insika::NotFoundError, "session '#{p[:session_id]}' not found")
+        end
+
+        # the platform retried a webhook it already delivered. Answer
+        # with the turn it ALREADY produced and run nothing: without this, one flaky
+        # ack costs a second LLM turn and sends the customer the same answer twice.
+        # Checked before the queue doors on purpose — a duplicate is not a fragment to
+        # merge and not a correction to steer with, it is the same message again.
+        key = dedup_key(command, p)
+        if key && (prior = @inbound_log.find(key))
+          return { task_id: prior, duplicate: true }
+        end
+
+        result = start_turn(command, p, profile)
+        @inbound_log.record(key, result[:task_id]) if key
+        result
+      end
+
+      private
+
+      # The turn (or the verdict that this message joined someone else's).
+      def start_turn(command, p, profile)
+        message = p[:message]
+
+        # a fragment for a session whose turn is still at the door
+        # joins it instead of becoming a turn of its own. Asked BEFORE `create` so a
+        # merge leaves no orphan :queued task behind (Recovery replays :queued at
+        # boot). Only offered on a surface that can report the verdict back —
+        # coalescing a caller that cannot hear `merged` makes it deliver the
+        # same answer twice.
+        if coalescable?(command)
+          if (joined = @executor.collect_into_pending(p[:session_id], message, profile: profile))
+            return { task_id: joined, merged: true }
+          end
+
+          # the turn is already RUNNING: the message is appended to it at
+          # the next tool-batch boundary. Same verdict as a merge, different word: the
+          # answer comes out of `task_id`, which is not this call's to deliver. Asked
+          # after `collect` because the two cannot both apply — a turn is either still at
+          # the door or running.
+          if (steered = @executor.steer_into_running(p[:session_id], message, profile: profile))
+            return { task_id: steered, steered: true }
+          end
+        end
+
+        # command.to_h persists the entire Command in the Task;
+        # ResumeTask re-reads payload.message from there.
+        task = @task_store.create(command: command.to_h, session_id: p[:session_id])
+        # `interrupt` mode: the turn in flight is now answering the wrong
+        # question, so it is abandoned at its next boundary. This message keeps its OWN
+        # task and its own reply (that is why it needs no verdict and no surface gate), and
+        # the cancel is posted after `create` so the event can name what replaced what.
+        # No-op in every other mode.
+        @executor.interrupt_running(p[:session_id], profile: profile, replaced_by: task.id)
+        @executor.spawn_in_session(task, profile: profile)
+        { task_id: task.id }
+      end
+
+      def coalescable?(command)
+        transport = command.meta[:transport]
+        COALESCABLE_TRANSPORTS.include?(transport) || transport.to_s.start_with?("channel:")
+      end
+
+      # Scoped by TRANSPORT, never bare: two channels are two consumers with two id
+      # spaces, and a Slack event id that happened to equal a `wamid` would otherwise
+      # silence a real message. nil (no log wired, or no id sent) = no dedup.
+      def dedup_key(command, payload)
+        return nil unless @inbound_log
+
+        event_id = Coercion.presence(payload[:event_id])
+        event_id && "#{command.meta[:transport]}:#{event_id}"
+      end
+
+      def normalize(payload)
+        {
+          agent: payload[:agent] || payload["agent"],
+          message: payload[:message] || payload["message"],
+          session_id: payload[:session_id] || payload["session_id"],
+          history: payload[:history] || payload["history"],
+          origin: payload[:origin] || payload["origin"],
+          event_id: payload[:event_id] || payload["event_id"]
+        }
+      end
+
+      def validate_history!(history)
+        ok = history.is_a?(Array) && history.all? do |m|
+          m.is_a?(Hash) &&
+            !m.values_at(:role, "role").compact.empty? &&
+            !m.values_at(:content, "content").compact.empty?
+        end
+        raise Insika::ValidationError, "history must be [{role:, content:}]" unless ok
+      end
+    end
+  end
+end

data/lib/insika/commands/set_agent_tools.rb

@@ -0,0 +1,39 @@
+# frozen_string_literal: true
+
+require "time"
+
+module Insika
+  module Commands
+    # Control command: adjusts an agent's tools allow/denylist.
+    # `allow` nil = all (AgentProfile rule); `deny` always
+    # wins. `allow_groups`: per-group allowlist, only
+    # overwritten if the key comes in the payload (otherwise preserved). Takes effect on the next
+    # dispatch (hot). -> AgentProfile.
+    class SetAgentTools
+      def initialize(profile_source:, event_stream:)
+        @profile_source = profile_source
+        @event_stream = event_stream
+      end
+
+      def call(command)
+        p = AgentPayload.symbolize(command.payload)
+        id = AgentPayload.presence(p[:id])
+        raise Insika::ValidationError, "id is required" if id.nil?
+        raise Insika::ValidationError, "allow must be a list or nil" unless p[:allow].nil? || p[:allow].is_a?(Array)
+        raise Insika::ValidationError, "allow_groups must be a list or nil" unless p[:allow_groups].nil? || p[:allow_groups].is_a?(Array)
+
+        existing = @profile_source.fetch(id) ||
+                   (raise Insika::NotFoundError, "agent '#{id}' not found")
+
+        merged = existing.to_h.merge(tools_allow: p[:allow], tools_deny: Array(p[:deny]))
+        merged[:tools_allow_groups] = p[:allow_groups] if p.key?(:allow_groups)
+        @profile_source.put(Insika::AgentProfile.build(**merged))
+        @event_stream.emit(Insika::Event.new(
+                             type: :agent_tools_set, data: { agent_id: id },
+                             meta: { at: Time.now.utc.iso8601 }
+                           ))
+        @profile_source.fetch(id)
+      end
+    end
+  end
+end