insika 0.3.0 → 0.7.0

data/lib/insika/server/app.rb

@@ -56,7 +56,7 @@ module Insika
                      config:, pending_action_store: nil, a2a: nil, provisioner: nil,
                      workflow_registry: nil, onboarding: nil, profiles: nil,
                      channels: nil, logger: nil, token_store: nil, outcome_store: nil,
-                     executor: nil, db_path: nil)
+                     executor: nil, db_path: nil, tool_registry: nil, mcp_store: nil)
         @command_bus = command_bus
         @event_stream = event_stream
         @session_store = session_store
@@ -104,6 +104,17 @@ module Insika
         # Both optional — nil means the body simply omits those readings.
         @executor = executor
         @db_path = db_path
+        # The deployment's EFFECTIVE tool registry, so the capability view can
+        # answer what the agent can reach that can WRITE (the derived
+        # eval-profile swap list). Read-only use (names/side_effect?) — same
+        # constitutional footing as the profile source. nil = the view omits it.
+        @tool_registry = tool_registry
+        # The durable MCP instance CRUD (GET/PUT/DELETE
+        # /v1/mcp[/:name]) — a direct store read/Command surface, same footing
+        # as @profiles/@outcome_store. nil = the routes 404 (parity — a
+        # deployment that never wires an McpStore never exposes MCP config
+        # over HTTP, same as one that skips provisioning).
+        @mcp_store = mcp_store
         @heartbeat = config.fetch(:heartbeat, 15)
         @sync_timeout = config.fetch(:sync_timeout, 10) # synchronous control
       end
@@ -181,6 +192,14 @@ module Insika
           handle_list_outcomes(req)
         in ["POST", ["v1", "tools", "manifest"]]
           handle_import_tools(req)
+        in ["GET", ["v1", "mcp"]] if @mcp_store
+          handle_list_mcp
+        in ["GET", ["v1", "mcp", name]] if @mcp_store
+          handle_read_mcp(name)
+        in ["PUT", ["v1", "mcp"]] if @mcp_store
+          handle_upsert_mcp(req)
+        in ["DELETE", ["v1", "mcp", name]] if @mcp_store
+          handle_delete_mcp(req, name)
         in ["POST", ["v1", "mcp", name, "import"]]
           handle_import_mcp_tools(req, name)
         in ["POST", ["v1", "agents"]] if @provisioner
@@ -438,18 +457,61 @@ module Insika
         json_response(200, dispatch_with_timeout(command))
       end
 
-      # POST /v1/mcp/:name/import — LIVE MCP ingestion. Same
+      # GET /v1/mcp — every configured MCP instance, MASKED (@mcp_store.all
+      # already masks — never plaintext over the wire). A direct store read,
+      # not a Command (constitutional rule at the top of this file); the
+      # generic route gate already confined this to the operator (not a
+      # TENANT_SURFACES entry), same footing as GET /v1/agents/:id.
+      def handle_list_mcp
+        json_response(200, { instances: @mcp_store.all })
+      end
+
+      # GET /v1/mcp/:name — one instance, MASKED. Missing -> 404.
+      def handle_read_mcp(name)
+        record = @mcp_store.get(name)
+        raise Insika::NotFoundError, "MCP instance '#{name}' not found" if record.nil?
+
+        json_response(200, record)
+      end
+
+      # PUT /v1/mcp — create/edit an instance (the CLI/DSL/Studio
+      # config surfaces share this ONE seam: the `:upsert_mcp` Command already
+      # registered on the bus). Per-key secret reconciliation (the `__OCULTO__`
+      # sentinel round-trips: preserves; a new string replaces; "" clears) —
+      # same contract as `Insika::McpJson`. 200 { the MASKED upserted record }.
+      def handle_upsert_mcp(req)
+        gate = gateway_gate(req)
+        return gate if gate
+
+        command = Insika::Command.build(:upsert_mcp, parse_body(req), transport: :http)
+        json_response(200, dispatch_with_timeout(command))
+      end
+
+      # DELETE /v1/mcp/:name — removes an instance (`:delete_mcp`). Idempotent
+      # (200 { existed: false } on a name that was never there — never a 404;
+      # deleting a thing that is already gone is not an error). The name comes
+      # from the ROUTE (data), not the body.
+      def handle_delete_mcp(req, name)
+        gate = gateway_gate(req)
+        return gate if gate
+
+        command = Insika::Command.build(:delete_mcp, { name: name }, transport: :http)
+        json_response(200, dispatch_with_timeout(command))
+      end
+
+      # POST /v1/mcp/:name/import — kept as the alias for the
+      # "Refresh tools" action (the route predates the live registry; the name
+      # stuck). Dispatches :refresh_mcp_tools — LIVE connect + tools/list +
+      # write McpStore#tools_cache, never the retired ingestor snapshot. Same
       # Bearer as provisioning (gateway_token, fail-closed): it's an authoring
-      # surface. Discovers the tools of the MCP instance `:name` (via a client injectable
-      # at the composition root) and ingests them as data-tools (reuses :import_tools:
-      # upsert + hot reload). Dispatches :import_mcp_tools -> 200 { per-tool report
-      # + instance }. Missing instance -> 404; disabled/no-url -> 422; per-tool
-      # failure isolated in `errors[]` (R4). The name comes from the ROUTE (data), not the body.
+      # surface. Missing instance -> 404; disabled -> 422; a transport failure
+      # surfaces as whatever #call's rescue maps it to. The name comes from the
+      # ROUTE (data), not the body.
       def handle_import_mcp_tools(req, name)
         gate = gateway_gate(req)
         return gate if gate
 
-        command = Insika::Command.build(:import_mcp_tools, { name: name }, transport: :http)
+        command = Insika::Command.build(:refresh_mcp_tools, { name: name }, transport: :http)
         json_response(200, dispatch_with_timeout(command))
       end
 
@@ -466,22 +528,50 @@ module Insika
       # (a client: it never reads a store) can tell "this case cannot run here" from
       # "this case failed". Deliberately NOT the profile: the prompt,
       # the model and the guardrail config are none of the caller's business. Just the
-      # two facts a case declares `requires` against.
+      # three facts a case declares `requires` against — plus the side-effect set,
+      # which is what an eval profile must swap.
       #
       # `tools` is the DECLARED allowlist, and `null` means the agent has an open one
       # (every registered tool) — the client reads that as "cannot rule anything out"
       # and runs the case rather than skipping it.
+      #
+      # `side_effect_tools` is DERIVED here from the deployment's own registry (the
+      # effective one the Executor uses): the agent's reachable tools the registry
+      # marks `side_effect` (a data-tool's non-GET method, the MCP ingestor's
+      # `tools/call`). It is the list a simulated run's eval profile must cover —
+      # and it is a fact of the deployment, never a hand-maintained client list.
+      # Absent (no registry wired) -> the key is omitted, and the view behaves as
+      # before.
       def handle_read_agent(id)
         profile = @profiles.fetch(id)
         raise Insika::NotFoundError, "agent not found: #{id}" if profile.nil?
 
         allow = profile.tools_allow
         deny = Array(profile.tools_deny).map(&:to_s)
-        json_response(200, {
-                        id: profile.id,
-                        tools: allow.nil? ? nil : (Array(allow).map(&:to_s) - deny),
-                        capabilities: Array(profile.capabilities_declared).map(&:to_s)
-                      })
+        payload = {
+          id: profile.id,
+          # `tools: null` is MEANINGFUL (an open allowlist — the client reads it
+          # as "cannot rule anything out"), so it must survive, unlike the new
+          # field below.
+          tools: allow.nil? ? nil : (Array(allow).map(&:to_s) - deny),
+          capabilities: Array(profile.capabilities_declared).map(&:to_s)
+        }
+        derived = side_effect_tools(profile)
+        payload[:side_effect_tools] = derived unless derived.nil?
+        json_response(200, payload)
+      end
+
+      # The derived side-effect set for an agent: its reachable tools (the same
+      # allowlist − deny resolution the `tools` field uses) that the registry marks
+      # `side_effect`, sorted for a stable answer. -> [names] | nil (no registry).
+      def side_effect_tools(profile)
+        return nil unless @tool_registry
+
+        allowed = if profile.tools_allow.nil? then Array(@tool_registry.names)
+                  else Array(profile.tools_allow).map(&:to_s)
+                  end
+        denied = Array(profile.tools_deny).map(&:to_s)
+        (allowed - denied).select { |name| @tool_registry.side_effect?(name) }.sort
       end
 
       # `/v1` only — `/a2a` is versioned by its own JSON-RPC spec and a channel's
@@ -887,7 +977,7 @@ TENANT_SURFACES = [
         parts = payload[:parts] || payload["parts"]
         if parts && !Insika::Media.well_formed?(parts)
           raise Insika::ValidationError,
-                "malformed content part — each part must be {type: text|image|audio} with text/url"
+                "malformed content part — each part must be {type: text|image|audio|document} with text/url"
         end
         # WS9: the only declared message source is "voice" (pre-transcribed
         # audio) — a consumer that writes prose here is told so, not silently.

data/lib/insika/server/rack_app.rb

@@ -59,8 +59,10 @@ module Insika
           pending_action_store: @graph.pending_action_store,
           provisioner: Insika::PackImporter.new(bus: @graph.bus, profiles: @graph.profiles),
           # GET /v1/agents/:id — the read-only capability view a case's `requires`
-          # resolves against.
+          # resolves against (and the derived side-effect set an eval profile must
+          # cover).
           profiles: @graph.profiles,
+          tool_registry: @graph.tool_registry,
           # the OSS onboarding surface (start.md + models.json + docs).
           # This is the primary "build my first agent" target — models.json reports the
           # DSL's stores + the agents this process serves (each id IS the `model`).
@@ -76,6 +78,8 @@ module Insika
           config: { gateway_token: @token, tenancy: tenancy }.merge(@config),
           token_store: store,
           outcome_store: @graph.outcome_store,
+          # GET/PUT/DELETE /v1/mcp[/:name] — the config surface.
+          mcp_store: @rt.component(:mcp_store),
           # a 500's error_ref must be findable in the process log.
           logger: $stdout
         )

data/lib/insika/server/responses.rb

@@ -53,7 +53,7 @@ module Insika
         if raw.is_a?(Array)
           unless Insika::Media.well_formed?(raw)
             raise Insika::ValidationError,
-                  "malformed content part — each part must be {type: text|image|audio} with text/url"
+                  "malformed content part — each part must be {type: text|image|audio|document} with text/url"
           end
 
           normalized = Insika::Media.parts(raw).map do |p|

data/lib/insika/skill_catalog.rb

@@ -68,6 +68,18 @@ module Insika
       self
     end
 
+    # Appends roots at the END — lowest precedence, so a workspace skill always
+    # overrides a same-named one shipped by a plugin. This is how
+    # the plugin Loader's `skill_dirs` reach the catalog at boot; reloads only
+    # when something new actually arrived.
+    def add_roots(dirs)
+      added = Array(dirs).map { |d| File.expand_path(d.to_s) } - @roots.map { |r| File.expand_path(r) }
+      return self if added.empty?
+
+      @roots.concat(added)
+      reload
+    end
+
     # Per-agent allowlist: nil -> all | [] -> none | [names] -> subset. `agent`
     # selects WHICH body each allowed name resolves to (see #find); the allowlist is
     # by NAME either way, so specializing a skill never touches the allowlist.

data/lib/insika/steer_injector.rb

@@ -69,14 +69,32 @@ module Insika
       inject! if @seen >= @expected
     end
 
+    # Tail-appends whatever is in the mailbox right now and reports how many. Called
+    # at a batch boundary (#inject!) and ONCE MORE by the Executor when the run ended
+    # with a message no boundary ever arrived for (a text-only turn closes no batch) —
+    # the append, the running count and the `:turn_steered` event belong in one place
+    # either way.
+    def absorb_pending!
+      texts = @actor.take_user_messages!
+      return 0 if texts.empty?
+
+      texts.each { |text| @chat.add_message(role: :user, content: @policy.frame(text)) }
+      @injected += texts.size
+      # Counts only, never content — the text is already in the transcript, which is the
+      # surface that is allowed to carry it. `task_id`/`session_id` are the event's meta.
+      @emit.call(:turn_steered, { count: texts.size, total: @injected })
+      texts.size
+    end
+
     private
 
     def open_batch(message)
       calls = field(message, :tool_calls)
       size = calls.respond_to?(:size) ? calls.size : 0
       # A message with no tool call is the model talking, not a batch: leave any
-      # pending message where it is (the turn is about to end, and the Executor
-      # releases it as a follow-up turn rather than answering it half-way).
+      # pending message where it is. The turn is about to end, and the Executor
+      # absorbs it there in ONE extra round (#absorb_pending!) — a text-only turn
+      # closes no batch, and answering it half-way is not an option.
       return @expected = nil if size.zero?
 
       @expected = size
@@ -88,14 +106,7 @@ module Insika
       @expected = nil
       return if @halted # nothing will read it: leave it in the mailbox
 
-      texts = @actor.take_user_messages!
-      return if texts.empty?
-
-      texts.each { |text| @chat.add_message(role: :user, content: @policy.frame(text)) }
-      @injected += texts.size
-      # Counts only, never content — the text is already in the transcript, which is the
-      # surface that is allowed to carry it. `task_id`/`session_id` are the event's meta.
-      @emit.call(:turn_steered, { count: texts.size, total: @injected })
+      absorb_pending!
     end
 
     def halt?(result) = defined?(RubyLLM::Tool::Halt) && result.is_a?(RubyLLM::Tool::Halt)