insika 0.0.1 → 0.2.0

data/lib/insika/commands/set_skill_agents.rb

@@ -0,0 +1,112 @@
+# frozen_string_literal: true
+
+require "time"
+
+module Insika
+  module Commands
+    # Control command: enables/disables a skill on N
+    # agents at once, adjusting each one's `profile.skills` allowlist — and, with
+    # `eager_ids`, which of them keep the body in the prompt on EVERY turn
+    # (`profile.skills_eager`). Takes effect on the next dispatch (hot via
+    # ProfileSource). -> { name, enabled_for, eager_for, skipped_all, skipped_eager_all }.
+    #
+    # Both are per-agent decisions about the same skill, which is why they are one
+    # command: eagerness lives on the agent precisely BECAUSE the skill is shared, so
+    # the screen that says "which agents can load this" is the screen that says "and
+    # which of them always have it".
+    #
+    # Allowlist semantics (AgentProfile): nil = ALL, [] = none,
+    # [names] = subset. Important and deliberate consequence:
+    #  - enabling on an agent with skills=nil: no-op (already has all).
+    #  - DISABLING on an agent with skills=nil: NOT done here — removing one from
+    #    "all" would require enumerating the catalog and materializing an explicit
+    #    allowlist (destructive/surprising). These agents are left intact and
+    #    go into `skipped_all`. To restrict, use an explicit :set_agent_tools/allowlist
+    #    first.
+    #
+    # `skills_eager` is NOT allowlist semantics (nil = NONE, see
+    # SkillCatalog#eager_for), so the two fields are adjusted by different rules: nil
+    # there is an empty set that can simply be added to, and only the BLANKET `true`
+    # has the same "cannot remove one name from all" problem (-> skipped_eager_all).
+    class SetSkillAgents
+      def initialize(profile_source:, event_stream:)
+        @profile_source = profile_source
+        @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?
+        raise Insika::ValidationError, "agent_ids must be a list" unless p[:agent_ids].nil? || p[:agent_ids].is_a?(Array)
+        raise Insika::ValidationError, "eager_ids must be a list" unless p[:eager_ids].nil? || p[:eager_ids].is_a?(Array)
+
+        wanted = Array(p[:agent_ids]).map(&:to_s)
+        # eager_ids ABSENT means "this form does not manage eagerness" — leave every
+        # profile's setting alone. An empty ARRAY means "none of them", which is a real
+        # instruction and must be applied. `nil` and `[]` are not the same request.
+        eager_wanted = p[:eager_ids].nil? ? nil : Array(p[:eager_ids]).map(&:to_s)
+        result = { enabled_for: [], eager_for: [], skipped_all: [], skipped_eager_all: [] }
+
+        @profile_source.all.each { |profile| apply(profile, name, wanted, eager_wanted, result) }
+
+        @event_stream.emit(Insika::Event.new(
+                             type: :skill_agents_set,
+                             data: { name: name, agent_ids: wanted, eager_ids: eager_wanted,
+                                     skipped_all: result[:skipped_all] }.compact,
+                             meta: { at: Time.now.utc.iso8601 }
+                           ))
+        { name: name }.merge(result)
+      end
+
+      private
+
+      def apply(profile, name, wanted, eager_wanted, result)
+        want = wanted.include?(profile.id)
+        new_skills = next_skills(profile.skills, name, want)
+        new_eager = next_eager(profile, name, eager_wanted, result)
+
+        if new_skills == :skip
+          result[:skipped_all] << profile.id
+          new_skills = profile.skills
+        end
+        result[:enabled_for] << profile.id if want
+        result[:eager_for] << profile.id if eager_wanted&.include?(profile.id)
+        return if new_skills == profile.skills && new_eager == profile.skills_eager
+
+        @profile_source.put(Insika::AgentProfile.build(
+                              **profile.to_h.merge(skills: new_skills, skills_eager: new_eager)
+                            ))
+      end
+
+      # -> new allowlist | :skip (agent with nil that requested disable).
+      def next_skills(current, name, want)
+        if want
+          current.nil? ? nil : (Array(current).map(&:to_s) | [name])
+        elsif current.nil?
+          :skip
+        else
+          Array(current).map(&:to_s) - [name]
+        end
+      end
+
+      # -> new skills_eager. nil eager_wanted = not managed by this call.
+      def next_eager(profile, name, eager_wanted, result)
+        current = profile.skills_eager
+        return current if eager_wanted.nil?
+
+        want = eager_wanted.include?(profile.id)
+        # Blanket `true` already includes every skill; removing ONE name from it would
+        # mean materializing the whole catalog as a list, the same destructive surprise
+        # `skipped_all` exists for.
+        if Coercion.truthy?(current)
+          result[:skipped_eager_all] << profile.id unless want
+          return current
+        end
+
+        list = current.nil? || current == false ? [] : Array(current).map(&:to_s)
+        want ? (list | [name]) : (list - [name])
+      end
+    end
+  end
+end

data/lib/insika/commands/trigger_workflow.rb

@@ -0,0 +1,80 @@
+# frozen_string_literal: true
+
+module Insika
+  module Commands
+    # Turn command: fires a workflow. Reuses the canonical
+    # pipeline — only stage 6 varies (Executor). Validates everything
+    # synchronously and responds `{task_id:}` immediately. The workflow allowlist is NOT
+    # checked here: it is stage-3 enforcement via WorkflowAllowlist
+    # -> PolicyDenied -> task :failed.
+    class TriggerWorkflow
+      ALLOWED_KEYS = %i[workflow agent input session_id].freeze
+
+      def initialize(profiles:, session_store:, task_store:, executor:, workflow_registry:)
+        @profiles = ProfileSource.coerce(profiles)
+        @session_store = session_store
+        @task_store = task_store
+        @executor = executor
+        @workflow_registry = workflow_registry
+      end
+
+      def call(command)
+        p = normalize(command.payload)
+        reject_unknown_keys!(command.payload) # strict validation
+
+        workflow = p[:workflow].to_s
+        raise Insika::ValidationError, "workflow is required" if workflow.empty?
+
+        agent = p[:agent].to_s
+        raise Insika::ValidationError, "agent is required" if agent.empty?
+
+        profile = @profiles[agent] ||
+                  (raise Insika::NotFoundError, "agent '#{agent}' not configured")
+
+        input = p[:input] || {}
+        raise Insika::ValidationError, "input must be a Hash" unless input.is_a?(Hash)
+
+        if p[:session_id]
+          @session_store.find(p[:session_id]) ||
+            (raise Insika::NotFoundError, "session '#{p[:session_id]}' not found")
+        end
+
+        # existence is validatable without executing — names, NEVER resolve (don't instantiate
+        # outside the fiber).
+        unless @workflow_registry.names.include?(workflow)
+          raise Insika::NotFoundError, "workflow '#{workflow}' not registered"
+        end
+
+        # I/O by schema: the INPUT is validated SYNCHRONOUSLY —
+        # a non-conforming input is a WorkflowSchemaError (< ValidationError -> 422)
+        # with NO run created. `definition` reads the schema metadata without
+        # resolving the factory (stays out of the fiber). No-op without an input_schema.
+        @workflow_registry.definition(workflow).validate_input!(input)
+
+        task = @task_store.create(command: command.to_h, session_id: p[:session_id])
+        @executor.spawn_in_session(task, profile: profile)
+        # runId = the run's durable record, which IS the Task (checkpointed +
+        # recoverable). Exposed under both names so the workflow consumer has a
+        # stable `run_id` while every task surface (GET /v1/tasks/:id, the event
+        # stream) keeps working unchanged.
+        { task_id: task.id, run_id: task.id }
+      end
+
+      private
+
+      def normalize(payload)
+        {
+          workflow: payload[:workflow] || payload["workflow"],
+          agent: payload[:agent] || payload["agent"],
+          input: payload[:input] || payload["input"],
+          session_id: payload[:session_id] || payload["session_id"]
+        }
+      end
+
+      def reject_unknown_keys!(payload)
+        extra = payload.keys.map(&:to_sym) - ALLOWED_KEYS
+        raise Insika::ValidationError, "unknown keys in payload: #{extra.join(', ')}" unless extra.empty?
+      end
+    end
+  end
+end

data/lib/insika/commands/update_agent.rb

@@ -0,0 +1,49 @@
+# frozen_string_literal: true
+
+require "time"
+
+module Insika
+  module Commands
+    # Control command: edits an existing agent. Merges the
+    # patch over the current profile (only the sent fields change) + rebuild + put.
+    # Takes effect on the NEXT dispatch (the ProfileSource reads fresh). -> AgentProfile.
+    class UpdateAgent
+      def initialize(profile_source:, event_stream:)
+        @profile_source = profile_source
+        @event_stream = event_stream
+      end
+
+      def call(command)
+        patch = AgentPayload.attrs(command.payload)
+        id = AgentPayload.presence(patch[:id])
+        raise Insika::ValidationError, "id is required" if id.nil?
+
+        existing = @profile_source.fetch(id) ||
+                   (raise Insika::NotFoundError, "agent '#{id}' not found")
+
+        # to_h of the current profile brings the correct symbols; patch overwrites only
+        # what was sent. id never changes (rename = create+delete, out of scope).
+        merged = existing.to_h.merge(patch).merge(id: id)
+        profile = Insika::AgentProfile.build(**merged)
+        # definition-time cycle + depth check (an update may ADD
+        # subagents to an existing agent). Raises SubagentError before persisting.
+        validate_subagent_graph!(profile)
+        @profile_source.put(profile)
+        @event_stream.emit(Insika::Event.new(
+                             type: :agent_updated, data: { agent_id: id },
+                             meta: { at: Time.now.utc.iso8601 }
+                           ))
+        @profile_source.fetch(id)
+      end
+
+      private
+
+      def validate_subagent_graph!(profile)
+        return if Array(profile.subagents).empty?
+
+        others = @profile_source.all.reject { |p| p.id.to_s == profile.id.to_s }
+        Insika::SubagentGraph.validate!(others + [profile])
+      end
+    end
+  end
+end

data/lib/insika/commands/update_settings.rb

@@ -0,0 +1,33 @@
+# frozen_string_literal: true
+
+require "time"
+
+module Insika
+  module Commands
+    # Control command: merges a patch into the
+    # general settings (timeouts/streaming/compaction) and persists it in the SettingsStore.
+    # Only what came in the patch changes; the rest (and the defaults) is preserved. Takes effect on the
+    # next turn that reads settings. -> Hash (resulting settings).
+    class UpdateSettings
+      def initialize(settings_store:, event_stream:)
+        @settings_store = settings_store
+        @event_stream = event_stream
+      end
+
+      def call(command)
+        p = AgentPayload.symbolize(command.payload)
+        patch = p[:patch]
+        raise Insika::ValidationError, "patch must be an object" unless patch.nil? || patch.is_a?(Hash)
+        raise Insika::ValidationError, "empty patch" if patch.nil? || patch.empty?
+
+        settings = @settings_store.update(patch)
+        @event_stream.emit(Insika::Event.new(
+                             type: :settings_updated,
+                             data: { keys: patch.keys.map(&:to_s) },
+                             meta: { at: Time.now.utc.iso8601 }
+                           ))
+        settings
+      end
+    end
+  end
+end

data/lib/insika/commands/upsert_llm_provider.rb

@@ -0,0 +1,34 @@
+# frozen_string_literal: true
+
+require "time"
+
+module Insika
+  module Commands
+    # Control command: creates/edits an LLM provider
+    # (api/base_url/auth_header/api_key/models) in the LLMProviderStore and RECONFIGURES
+    # RubyLLM at runtime (LLMConfigurator) — swaps key/base without a restart.
+    # The `api_key` is sentinel-aware (__OCULTO__ preserves; "" clears; a new string
+    # replaces). Returns the MASKED record (the key never comes back in plaintext).
+    class UpsertLLMProvider
+      def initialize(provider_store:, configurator:, event_stream:)
+        @provider_store = provider_store
+        @configurator = configurator
+        @event_stream = event_stream
+      end
+
+      def call(command)
+        p = AgentPayload.symbolize(command.payload)
+        masked = @provider_store.upsert(p) # validates `api`; returns masked
+
+        # Reconfigures only THIS provider (with the real key from the store, already reconciled).
+        result = @configurator.apply([@provider_store.get_raw(masked["api"])])
+        @event_stream.emit(Insika::Event.new(
+                             type: :llm_provider_upserted,
+                             data: { api: masked["api"], applied: result[:applied], skipped: result[:skipped] },
+                             meta: { at: Time.now.utc.iso8601 }
+                           ))
+        masked
+      end
+    end
+  end
+end

data/lib/insika/commands/upsert_mcp.rb

@@ -0,0 +1,32 @@
+# frozen_string_literal: true
+
+require "time"
+
+module Insika
+  module Commands
+    # Control command: creates/edits an MCP instance
+    # (transport/command/url/enabled + `env` credentials) in the McpStore. The
+    # credentials are sentinel-aware per key (__OCULTO__ preserves; "" clears;
+    # a new string replaces). Returns the MASKED record (env never comes back in
+    # plaintext). Durable config CRUD — running an MCP client against the
+    # instance is later runtime.
+    class UpsertMcp
+      def initialize(mcp_store:, event_stream:)
+        @mcp_store = mcp_store
+        @event_stream = event_stream
+      end
+
+      def call(command)
+        p = AgentPayload.symbolize(command.payload)
+        masked = @mcp_store.upsert(p) # validates `name`; returns masked
+
+        @event_stream.emit(Insika::Event.new(
+                             type: :mcp_upserted,
+                             data: { name: masked["name"], enabled: masked["enabled"] },
+                             meta: { at: Time.now.utc.iso8601 }
+                           ))
+        masked
+      end
+    end
+  end
+end

data/lib/insika/commands/write_agent_file.rb

@@ -0,0 +1,57 @@
+# frozen_string_literal: true
+
+require "time"
+
+module Insika
+  module Commands
+    # Control command: writes an agent's prompt file to the
+    # workspace (AgentFileStore). This is what gives each BIA its own identity — the
+    # Prompt provider reads these files via `profile.prompt_files`. Takes effect
+    # on the next dispatch (hot). -> { agent_id, file, updated_at }.
+    class WriteAgentFile
+      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?
+        profile = @profile_source.fetch(agent_id) ||
+                  (raise Insika::NotFoundError, "agent '#{agent_id}' not found")
+
+        # `.to_s` used to be unconditional here, which is how a JSON body carrying an
+        # OBJECT for `content` became a prompt file holding Ruby's #inspect of it. The
+        # store refuses that now; keep the coercion for scalars (a form always sends a
+        # String, and nil means "clear the file").
+        content = Insika::AgentFileStore.text!(p[:content], agent_id, file).to_s
+        entry = @agent_files.write(agent_id, file, content, create_only: !!p[:create_only])
+        # Writing a prompt registers it in prompt_files — otherwise the Prompt provider
+        # would never load it. It's the Command's job, not the dispatcher's.
+        register_prompt_file(profile, file)
+        emit(:agent_file_written, agent_id, file)
+        { agent_id: agent_id, file: file, updated_at: entry["updated_at"] }
+      end
+
+      private
+
+      def register_prompt_file(profile, file)
+        files = Array(profile.prompt_files).map(&:to_s)
+        return if files.include?(file)
+
+        @profile_source.put(Insika::AgentProfile.build(**profile.to_h.merge(prompt_files: files + [file])))
+      end
+
+      def emit(type, agent_id, file)
+        @event_stream.emit(Insika::Event.new(
+                             type: type, data: { agent_id: agent_id, file: file },
+                             meta: { at: Time.now.utc.iso8601 }
+                           ))
+      end
+    end
+  end
+end

data/lib/insika/commands/write_data_tool.rb

@@ -0,0 +1,43 @@
+# frozen_string_literal: true
+
+require "time"
+
+module Insika
+  module Commands
+    # Writes (upserts) a DATA-defined tool into the ToolStore and RELOADS the overlay +
+    # catalog — takes effect without a restart. Rejects a name that collides with a
+    # code tool (R3). Validating the definition (format, method/url, types,
+    # placeholders) is the ToolStore/ToolDefinition's job. Secrets (headers) reconcile
+    # in the store; the event carries only the name (0 leakage). -> { name, definition }.
+    class WriteDataTool
+      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?
+        raise Insika::ValidationError, "'#{name}' is already a code tool" if @registry.code_tool?(name)
+
+        masked = @tool_store.write(p, create_only: !!p[:create_only])
+        @registry.reload
+        @tool_catalog.reload
+        emit(name)
+        { name: name, definition: masked }
+      end
+
+      private
+
+      def emit(name)
+        @event_stream.emit(Insika::Event.new(
+                             type: :data_tool_written, data: { name: name },
+                             meta: { at: Time.now.utc.iso8601 }
+                           ))
+      end
+    end
+  end
+end

data/lib/insika/commands/write_golden.rb

@@ -0,0 +1,58 @@
+# frozen_string_literal: true
+
+require "time"
+
+module Insika
+  module Commands
+    # Control command: writes an eval case into the GoldenStore. This
+    # is what lets a domain owner add a case — above all its RUBRIC, the part of an eval
+    # that is plain language — without a checkout and a text editor.
+    #
+    # The payload carries the case as DATA (`case:`), the same mapping the YAML file
+    # holds; the store validates it with the one loader, so a case authored here and a
+    # case read from `evals/golden/` cannot diverge. -> { id, agent }.
+    class WriteGolden
+      def initialize(golden_store:, event_stream:)
+        @goldens = golden_store
+        @event_stream = event_stream
+      end
+
+      def call(command)
+        p = AgentPayload.symbolize(command.payload)
+        raise Insika::ValidationError, "case is required" unless p[:case].is_a?(Hash)
+
+        golden = @goldens.write(p[:case])
+        emit(:golden_written, id: golden.id, agent: golden.agent)
+        { id: golden.id, agent: golden.agent }
+      end
+
+      private
+
+      def emit(type, **data)
+        @event_stream.emit(Insika::Event.new(type: type, data: data,
+                                            meta: { at: Time.now.utc.iso8601 }))
+      end
+    end
+
+    # Control command: removes an eval case. The corpus on disk is the way back
+    # (`insika evals:import`), which is why this needs no version history.
+    # -> { id, existed }.
+    class DeleteGolden
+      def initialize(golden_store:, event_stream:)
+        @goldens = golden_store
+        @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?
+
+        existed = @goldens.delete(id)
+        @event_stream.emit(Insika::Event.new(type: :golden_deleted, data: { id: id, existed: existed },
+                                            meta: { at: Time.now.utc.iso8601 }))
+        { id: id, existed: existed }
+      end
+    end
+  end
+end

data/lib/insika/commands/write_skill.rb

@@ -0,0 +1,60 @@
+# frozen_string_literal: true
+
+require "time"
+require "yaml"
+
+module Insika
+  module Commands
+    # Control command: writes a skill (complete SKILL.md) into
+    # the SkillStore and RELOADS the catalog — takes effect without a restart (hot).
+    # Validates the frontmatter (name required) before writing. -> { name, agent, updated_at }.
+    #
+    # `agent` (optional) writes into that agent's scope instead of the shared one: the
+    # SPECIALIZATION of a shared skill, or a skill private to one agent. Same `name`
+    # either way — the store position is the identity, so the frontmatter inside an
+    # override keeps saying the bare shared name and the level-1 catalog, load_skill,
+    # the labels and the events all keep displaying it.
+    class WriteSkill
+      def initialize(skill_store:, skill_catalog:, event_stream:)
+        @skill_store = skill_store
+        @skill_catalog = skill_catalog
+        @event_stream = event_stream
+      end
+
+      def call(command)
+        p = AgentPayload.symbolize(command.payload)
+        name = AgentPayload.presence(p[:name])
+        agent = AgentPayload.presence(p[:agent])
+        content = p[:content].to_s
+        raise Insika::ValidationError, "name is required" if name.nil?
+        validate_frontmatter!(content)
+
+        rec = @skill_store.write(name, content, agent: agent, create_only: !!p[:create_only])
+        @skill_catalog.reload
+        emit(:skill_written, name, agent)
+        { name: name, agent: agent, updated_at: rec["updated_at"] }
+      end
+
+      private
+
+      def emit(type, name, agent)
+        @event_stream.emit(Insika::Event.new(
+                             type: type, data: { name: name, agent: agent }.compact,
+                             meta: { at: Time.now.utc.iso8601 }
+                           ))
+      end
+
+      # Mirrors the SkillCatalog parse: without YAML frontmatter with `name`, the skill
+      # would be silently ignored on reload — fail early, in the Command.
+      def validate_frontmatter!(content)
+        match = content.match(/\A---\s*\n(.*?)\n---\s*\n/m)
+        raise Insika::ValidationError, "SKILL.md missing YAML frontmatter (--- ... ---)" unless match
+
+        # Tolerant parser (Frontmatter): prose with `: ` in the description is valid —
+        # it must not become a Psych::SyntaxError (500). Only fails if `name` is missing.
+        meta = Insika::Frontmatter.parse(match[1])
+        raise Insika::ValidationError, "frontmatter missing `name`" if AgentPayload.presence(meta["name"]).nil?
+      end
+    end
+  end
+end

data/lib/insika/commands/write_system_file.rb

@@ -0,0 +1,31 @@
+# frozen_string_literal: true
+
+require "time"
+
+module Insika
+  module Commands
+    # Control command: writes a GLOBAL system file into the
+    # SystemFileStore. Unlike write_agent_file (per agent), these files
+    # apply to ALL agents — the Prompt provider injects them before the
+    # individual identity. Takes effect on the next turn (hot). -> { file, updated_at }.
+    class WriteSystemFile
+      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?
+
+        entry = @system_files.write(file, p[:content].to_s, create_only: !!p[:create_only])
+        @event_stream.emit(Insika::Event.new(
+                             type: :system_file_written, data: { file: file },
+                             meta: { at: Time.now.utc.iso8601 }
+                           ))
+        { file: file, updated_at: entry["updated_at"] }
+      end
+    end
+  end
+end