insika 0.0.1 → 0.2.0

data/lib/insika/command_bus.rb

@@ -0,0 +1,39 @@
+# frozen_string_literal: true
+
+module Insika
+  # Routes Commands to handlers registered by the composition root.
+  # The bus does NOT distinguish control Commands (synchronous response) from
+  # turn Commands (immediate `{task_id:}`) — that is the handler's job; the bus
+  # only routes.
+  #
+  # No lock/mutex: one reactor, cooperative fibers; `dispatch`
+  # does no IO of its own.
+  class CommandBus
+    # Handlers receive their dependencies in their own constructor and emit on
+    # their own — the bus only routes.
+    def initialize
+      @handlers = {}
+    end
+
+    # handler: any object responding to #call(command). Re-registering the
+    # same type overwrites (last wins — the composition root is the only
+    # caller).
+    def register(type, handler)
+      @handlers[type.to_sym] = handler
+    end
+
+    # Introspection for the composition roots / graph specs: which command
+    # types the bus can route. Read-only; does not expose the handlers.
+    def registered?(type) = @handlers.key?(type.to_sym)
+    def types = @handlers.keys
+
+    # -> the handler's result. Unregistered type -> synchronous ValidationError,
+    # no Task created (never KeyError/NoMethodError).
+    def dispatch(command)
+      handler = @handlers[command.type]
+      raise Insika::ValidationError, "unknown command: #{command.type}" if handler.nil?
+
+      handler.call(command)
+    end
+  end
+end

data/lib/insika/commands/agent_payload.rb

@@ -0,0 +1,43 @@
+# frozen_string_literal: true
+
+module Insika
+  module Commands
+    # Shared normalization for the agent-authoring payload.
+    # The transport delivers string keys (JSON); internal dispatch uses
+    # symbols. Here: symbolize the top level, keep only the fields buildable by
+    # AgentProfile, and re-symbolize the fields the runtime consumes as symbols
+    # (provider, policies, limits keys) — same rule as StoredProfileSource.
+    module AgentPayload
+      # Fields accepted by AgentProfile.build (order irrelevant).
+      FIELDS = %i[id model provider base_prompt prompt_files tools_allow tools_deny
+                  tools_allow_groups skills skills_eager context_providers workflows_allow policies
+                  prompt_refs limits approvals_required capabilities subagents tools_deferred
+                  memory prompt_caching tool_output_compression budget reliability alerts
+                  stuck_signal
+                  params model_policy guardrails refinement capabilities_declared
+                  edge_stream metadata].freeze
+
+      module_function
+
+      # payload (string|symbol keys) -> Hash of attrs ready for AgentProfile.build.
+      def attrs(payload)
+        h = symbolize(payload)
+        out = {}
+        FIELDS.each { |f| out[f] = h[f] if h.key?(f) }
+        out[:provider] = presence(out[:provider])&.to_sym if out.key?(:provider)
+        out[:policies] = Array(out[:policies]).map(&:to_sym) if out.key?(:policies)
+        out[:limits] = out[:limits].transform_keys(&:to_sym) if out[:limits].is_a?(Hash)
+        # generation params consumed by symbol key (temperature/max_tokens/thinking).
+        out[:params] = out[:params].transform_keys(&:to_sym) if out[:params].is_a?(Hash)
+        out
+      end
+
+      def symbolize(payload)
+        (payload || {}).each_with_object({}) { |(k, v), acc| acc[k.to_sym] = v }
+      end
+
+      # Stable name used by the handlers; the rule lives in Insika::Coercion.
+      def presence(str) = Insika::Coercion.presence(str)
+    end
+  end
+end

data/lib/insika/commands/approve_action.rb

@@ -0,0 +1,46 @@
+# frozen_string_literal: true
+
+require "time"
+
+module Insika
+  module Commands
+    # Control command: the operator resolves a pending action
+    # (human-in-the-loop). Resolves the PendingAction in the store (durable source
+    # of truth) and WAKES the turn suspended on :waiting by posting :approval to the
+    # live fiber. Order matters: RESOLVE before posting — when the await wakes, the
+    # store already has the decision (request_approval re-reads it from there). Crash-safe:
+    # with no live fiber the post is a no-op; recovery re-executes and uses the durable decision.
+    #
+    # Payload `{ pending_id:, decision: "approved"|"rejected", operator?: }`.
+    # -> resolved PendingAction.
+    class ApproveAction
+      def initialize(pending_action_store:, executor:, event_stream:)
+        @pending_action_store = pending_action_store
+        @executor = executor
+        @event_stream = event_stream
+      end
+
+      def call(command)
+        p = command.payload
+        pending_id = (p[:pending_id] || p["pending_id"]).to_s
+        decision = (p[:decision] || p["decision"]).to_s
+        raise Insika::ValidationError, "pending_id is required" if pending_id.empty?
+
+        # operator: from the operator's auth (Control UI) via payload; nil ok.
+        operator = p[:operator] || p["operator"] || command.meta[:operator]
+
+        # resolve() validates the decision and the state (:pending); NotFound if absent.
+        resolved = @pending_action_store.resolve(pending_id, decision: decision, operator: operator)
+
+        @executor.approve(resolved.task_id) # wakes the live fiber (no-op if it crashed)
+        @event_stream.emit(Insika::Event.new(
+                             type: :approval_resolved,
+                             data: { pending_id: pending_id, decision: resolved.status,
+                                     task_id: resolved.task_id, resolved_by: operator },
+                             meta: { task_id: resolved.task_id, at: Time.now.utc.iso8601 }
+                           ))
+        resolved
+      end
+    end
+  end
+end

data/lib/insika/commands/cancel_task.rb

@@ -0,0 +1,33 @@
+# frozen_string_literal: true
+
+module Insika
+  module Commands
+    # Control command: posts `:cancel` to the Task's in-process mailbox
+    # and responds synchronously. Payload `{ task_id: String }` -> returns Task.
+    #
+    # Cancellation is COOPERATIVE: the one that transitions the status is the
+    # task's fiber when it drains the mailbox — NEVER this handler. Cancelling a task with no
+    # live fiber (terminal or orphaned) is an idempotent no-op.
+    class CancelTask
+      # executor: object with #cancel(task_id) — the real implementation is
+      # `@running[task_id]&.post(:cancel)`; here it's a contract (duck type).
+      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.cancel(task_id) # no-op if there is no live fiber in this process
+        # Does not transition status nor touch the persisted mailbox_state: it only uses
+        # the in-process mailbox (Async::Queue). Returns the current state after the post.
+        @task_store.find(task_id)
+      end
+    end
+  end
+end

data/lib/insika/commands/create_agent.rb

@@ -0,0 +1,54 @@
+# frozen_string_literal: true
+
+require "time"
+
+module Insika
+  module Commands
+    # Control command: creates an agent (AgentProfile) at
+    # RUNTIME and persists it in the ProfileSource (ConfigStore). This is the "everyone creates
+    # their own BIA". Synchronous; does not create a Task. -> AgentProfile (round-tripped from the store).
+    class CreateAgent
+      def initialize(profile_source:, event_stream:)
+        @profile_source = profile_source
+        @event_stream = event_stream
+      end
+
+      def call(command)
+        attrs = AgentPayload.attrs(command.payload)
+        id = AgentPayload.presence(attrs[:id])
+        raise Insika::ValidationError, "id is required" if id.nil?
+        # model is OPTIONAL as of v2: omitted -> resolves the platform
+        # default_model (Settings) at turn start. An agent with neither its own
+        # model nor a platform default fails clearly at the first turn.
+        raise Insika::ValidationError, "agent '#{id}' already exists" if @profile_source.fetch(id)
+
+        profile = Insika::AgentProfile.build(**attrs)
+        # definition-time cycle + depth check. Only a profile that
+        # introduces edges (non-empty subagents) can create a violation — a
+        # childless agent is always a safe leaf. Raises SubagentError (a
+        # ValidationError) BEFORE persisting, so a bad graph never lands.
+        validate_subagent_graph!(profile)
+        @profile_source.put(profile)
+        emit(:agent_created, id)
+        @profile_source.fetch(id) # returns the persisted profile (symbols already normalized)
+      end
+
+      private
+
+      # Validates the delegation graph with `profile` added to the current set.
+      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
+
+      def emit(type, id)
+        @event_stream.emit(Insika::Event.new(
+                             type: type, data: { agent_id: id },
+                             meta: { at: Time.now.utc.iso8601 }
+                           ))
+      end
+    end
+  end
+end

data/lib/insika/commands/create_session.rb

@@ -0,0 +1,67 @@
+# frozen_string_literal: true
+
+require "time"
+
+module Insika
+  module Commands
+    # Control command: creates a session and responds synchronously —
+    # does not create a Task. Payload `{ vars: {} }` -> returns Session. `id` optional:
+    # when present, the session is born with that id (correlation by external key —
+    # e.g.: chat.id in the /v1/responses adapter; contextId in A2A). Absent -> uuid.
+    class CreateSession
+      # event_stream: any object with #emit(event) (tests use a spy).
+      def initialize(session_store:, event_stream:)
+        @session_store = session_store
+        @event_stream = event_stream
+      end
+
+      def call(command)
+        # Accepts a symbol key (internal dispatch) and a string key (transport JSON)
+        # — normalizes at the handler boundary.
+        vars = command.payload[:vars] || command.payload["vars"] || {}
+        raise Insika::ValidationError, "vars must be a Hash" unless vars.is_a?(Hash)
+
+        # Per-chat model pin: `model`/`provider` on the payload become a
+        # reserved, collision-safe slot in vars (never rendered in the prompt — the
+        # Request provider skips "__"-prefixed vars). The ModelResolver reads it as
+        # the highest-precedence layer (Chat > Agent > platform default).
+        vars = apply_model_pin(vars.dup, command.payload)
+
+        id = command.payload[:id] || command.payload["id"]
+        session = id ? @session_store.create(id: id, vars: vars) : @session_store.create(vars: vars)
+        # :session_created is from the closed catalog (origin: CreateSession handler).
+        # meta without task_id/seq (control has no Task); Event#to_h does meta.compact.
+        @event_stream.emit(Insika::Event.new(
+                             type: :session_created,
+                             data: { session_id: session.id },
+                             meta: { session_id: session.id, at: Time.now.utc.iso8601 }
+                           ))
+        session
+      end
+
+      private
+
+      # Reads `model`/`provider`/`thinking` (string|symbol keys) and, when any is
+      # present, writes the reserved vars slot. All must be strings; `thinking` is
+      # the per-chat reasoning override (off/on/low/medium/high) and may be set
+      # WITHOUT a model pin. Absent -> vars unchanged.
+      def apply_model_pin(vars, payload)
+        model = payload[:model] || payload["model"]
+        provider = payload[:provider] || payload["provider"]
+        thinking = payload[:thinking] || payload["thinking"]
+        return vars if model.nil? && provider.nil? && thinking.nil?
+
+        raise Insika::ValidationError, "model must be a String" unless model.nil? || model.is_a?(String)
+        raise Insika::ValidationError, "provider must be a String" unless provider.nil? || provider.is_a?(String)
+        raise Insika::ValidationError, "thinking must be a String" unless thinking.nil? || thinking.is_a?(String)
+
+        pin = {}
+        pin["model"] = model if model
+        pin["provider"] = provider if provider
+        pin["thinking"] = thinking if thinking
+        vars[Insika::ModelResolver::SESSION_SLOT] = pin
+        vars
+      end
+    end
+  end
+end

data/lib/insika/commands/delete_agent.rb

@@ -0,0 +1,33 @@
+# frozen_string_literal: true
+
+require "time"
+
+module Insika
+  module Commands
+    # Control command: removes an agent. -> the removed AgentProfile
+    # (so the transport can confirm what disappeared). Turns ALREADY in progress
+    # that captured the profile keep going until they finish (the ProfileSource only affects
+    # new dispatches).
+    class DeleteAgent
+      def initialize(profile_source:, event_stream:)
+        @profile_source = profile_source
+        @event_stream = event_stream
+      end
+
+      def call(command)
+        id = AgentPayload.presence(AgentPayload.symbolize(command.payload)[:id])
+        raise Insika::ValidationError, "id is required" if id.nil?
+
+        removed = @profile_source.fetch(id) ||
+                  (raise Insika::NotFoundError, "agent '#{id}' not found")
+
+        @profile_source.delete(id)
+        @event_stream.emit(Insika::Event.new(
+                             type: :agent_deleted, data: { agent_id: id },
+                             meta: { at: Time.now.utc.iso8601 }
+                           ))
+        removed
+      end
+    end
+  end
+end

data/lib/insika/commands/delete_agent_file.rb

@@ -0,0 +1,50 @@
+# frozen_string_literal: true
+
+require "time"
+
+module Insika
+  module Commands
+    # Control command: removes a prompt file from an agent's
+    # workspace. Nonexistent -> NotFoundError. -> { agent_id, file }.
+    class DeleteAgentFile
+      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?
+
+        unless @agent_files.delete(agent_id, file)
+          raise Insika::NotFoundError, "file '#{file}' not found for agent '#{agent_id}'"
+        end
+
+        unregister_prompt_file(agent_id, file)
+        @event_stream.emit(Insika::Event.new(
+                             type: :agent_file_deleted, data: { agent_id: agent_id, file: file },
+                             meta: { at: Time.now.utc.iso8601 }
+                           ))
+        { agent_id: agent_id, file: file }
+      end
+
+      private
+
+      # Removing the file also drops it from prompt_files (the inverse operation of
+      # WriteAgentFile) — the Command's job, not the dispatcher's.
+      def unregister_prompt_file(agent_id, file)
+        profile = @profile_source.fetch(agent_id)
+        return unless profile
+
+        files = Array(profile.prompt_files).map(&:to_s)
+        return unless files.include?(file)
+
+        @profile_source.put(Insika::AgentProfile.build(**profile.to_h.merge(prompt_files: files - [file])))
+      end
+    end
+  end
+end

data/lib/insika/commands/delete_data_tool.rb

@@ -0,0 +1,33 @@
+# frozen_string_literal: true
+
+require "time"
+
+module Insika
+  module Commands
+    # Removes a data tool from the ToolStore and reloads overlay + catalog.
+    # 404 if it did not exist. -> { name }.
+    class DeleteDataTool
+      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::NotFoundError, "tool '#{name}' not found" unless @tool_store.delete(name)
+
+        @registry.reload
+        @tool_catalog.reload
+        @event_stream.emit(Insika::Event.new(
+                             type: :data_tool_deleted, data: { name: name },
+                             meta: { at: Time.now.utc.iso8601 }
+                           ))
+        { name: name }
+      end
+    end
+  end
+end

data/lib/insika/commands/delete_llm_provider.rb

@@ -0,0 +1,36 @@
+# frozen_string_literal: true
+
+require "time"
+
+module Insika
+  module Commands
+    # Control command: removes an LLM provider from the
+    # LLMProviderStore. Idempotent (`existed: false` if there was none). UNDOES the
+    # config in RubyLLM at runtime: when the provider existed, calls
+    # `configurator.unapply(api)` clearing the global key/base — without a restart. A provider
+    # that RubyLLM does not recognize degrades gracefully (unapply: false, nothing to
+    # undo). -> { existed: bool }.
+    class DeleteLLMProvider
+      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)
+        api = AgentPayload.presence(p[:api])
+        raise Insika::ValidationError, "api is required" if api.nil?
+
+        existed = @provider_store.delete(api)
+        @configurator.unapply(api) if existed
+        @event_stream.emit(Insika::Event.new(
+                             type: :llm_provider_deleted,
+                             data: { api: api, existed: existed },
+                             meta: { at: Time.now.utc.iso8601 }
+                           ))
+        { existed: existed }
+      end
+    end
+  end
+end

data/lib/insika/commands/delete_mcp.rb

@@ -0,0 +1,30 @@
+# frozen_string_literal: true
+
+require "time"
+
+module Insika
+  module Commands
+    # Control command: removes an MCP instance from the
+    # McpStore. Idempotent (`existed: false` if there was none). -> { existed: bool }.
+    class DeleteMcp
+      def initialize(mcp_store:, event_stream:)
+        @mcp_store = mcp_store
+        @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?
+
+        existed = @mcp_store.delete(name)
+        @event_stream.emit(Insika::Event.new(
+                             type: :mcp_deleted,
+                             data: { name: name, existed: existed },
+                             meta: { at: Time.now.utc.iso8601 }
+                           ))
+        { existed: existed }
+      end
+    end
+  end
+end

data/lib/insika/commands/delete_skill.rb

@@ -0,0 +1,43 @@
+# frozen_string_literal: true
+
+require "time"
+
+module Insika
+  module Commands
+    # Control command: removes an authored skill from the SkillStore and RELOADS the
+    # catalog. -> { name, agent, deleted }.
+    #
+    # With `agent`, it deletes only that agent's SPECIALIZATION — the shared skill
+    # stays exactly where it was, and the agent falls back to it on the next turn.
+    # "Stop specializing this" is the inverse of the specialize action, and it must not
+    # be expressible as "delete the skill".
+    #
+    # Deleting a shared skill does NOT touch any allowlist: an agent left naming a
+    # skill that no longer exists sees nothing (the catalog resolves nothing), which is
+    # the same outcome as never having allowed it.
+    class DeleteSkill
+      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])
+        raise Insika::ValidationError, "name is required" if name.nil?
+
+        deleted = @skill_store.delete(name, agent: agent)
+        raise Insika::NotFoundError, "skill '#{name}' not found#{" for agent '#{agent}'" if agent}" unless deleted
+
+        @skill_catalog.reload
+        @event_stream.emit(Insika::Event.new(
+                             type: :skill_deleted, data: { name: name, agent: agent }.compact,
+                             meta: { at: Time.now.utc.iso8601 }
+                           ))
+        { name: name, agent: agent, deleted: true }
+      end
+    end
+  end
+end

data/lib/insika/commands/delete_system_file.rb

@@ -0,0 +1,29 @@
+# frozen_string_literal: true
+
+require "time"
+
+module Insika
+  module Commands
+    # Control command: removes a global system file
+    # from the SystemFileStore. Idempotent (`existed: false`). -> { existed: bool }.
+    class DeleteSystemFile
+      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?
+
+        existed = @system_files.delete(file)
+        @event_stream.emit(Insika::Event.new(
+                             type: :system_file_deleted, data: { file: file, existed: existed },
+                             meta: { at: Time.now.utc.iso8601 }
+                           ))
+        { existed: existed }
+      end
+    end
+  end
+end