insika 0.3.0 → 0.8.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

@@ -12,9 +12,9 @@ module Insika
     # OpenAI Responses SSE frame (or nil for events with no counterpart). Follows the
     # constitutional rule: no business logic, no store access here.
     #
-    # Request: { model: "openclaw:<agent>", user: "<chat.id>", stream: true,
+    # Request: { model: "insika:<agent>", user: "<chat.id>", stream: true,
     #            input: "<string with already-composed blocks>" } + header
-    # X-Openclaw-Agent (agent fallback). The `input` enters VERBATIM as the
+    # X-Insika-Agent (agent fallback). The `input` enters VERBATIM as the
     # turn's message — the blocks (<memoria>/<dados_conhecidos>/directives) already come
     # composed by the consumer (the engine does not interpret them).
     module Responses
@@ -32,8 +32,8 @@ module Insika
       # gets that filtered structurally instead of by a regex on the leading tag.
       # Omitted = a customer typed it, which is what every turn meant before.
       def parse_request(body, req)
-        agent = body[:model].to_s.sub(/\Aopenclaw:/, "")
-        agent = req.get_header("HTTP_X_OPENCLAW_AGENT").to_s if agent.empty?
+        agent = body[:model].to_s.sub(/\Ainsika:/, "")
+        agent = req.get_header("HTTP_X_INSIKA_AGENT").to_s if agent.empty?
         raise Insika::ValidationError, "model/agent missing" if agent.strip.empty?
 
         user = body[:user].to_s
@@ -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/session_store.rb

@@ -23,11 +23,11 @@ module Insika
     KEY_PREFIX = "session:"
 
     Session = Data.define(:id, :messages, :vars, :memory_refs,
-                          :created_at, :updated_at, :briefing, :evidence) do
+                          :created_at, :updated_at, :briefing, :evidence, :compaction) do
       # Trailing members with defaults: an old record without the "briefing" /
-      # "evidence" keys reads as empty/nil without a migration.
+      # "evidence" / "compaction" keys reads as empty/nil without a migration.
       def initialize(id:, messages:, vars:, memory_refs:, created_at:, updated_at:,
-                     briefing: nil, evidence: nil)
+                     briefing: nil, evidence: nil, compaction: nil)
         super
       end
     end
@@ -150,6 +150,35 @@ module Insika
       to_session(record)
     end
 
+    # -> Session. Persists the in-session compaction state (RFC-0044): the
+    # summary of messages[0...upto] plus the boundary. `upto` is MONOTONIC —
+    # a write that does not move the boundary forward is a no-op (a stale
+    # double-write from a racing worker can never move it backwards). `runs`
+    # counts compactions over the session's lifetime (the trace reports it).
+    #
+    # CONCURRENCY NOTE: an unlocked RMW (read -> mutate -> set), like
+    # update_briefing — and safe for the same reason: nothing in the
+    # read/mutate/set path suspends, so no other writer can interleave
+    # mid-RMW. The LLM call that produced the summary happened BEFORE this
+    # method; only the plain write lives here.
+    def set_compaction(id, summary:, upto:, model: nil)
+      record = fetch!(id)
+      current = record["compaction"]
+      upto = Integer(upto)
+      return to_session(record) if current && upto <= current["upto"].to_i
+
+      record["compaction"] = {
+        "summary" => Coercion.utf8(summary.to_s),
+        "upto" => upto,
+        "runs" => (current ? current["runs"].to_i : 0) + 1,
+        "model" => Coercion.presence(model.to_s),
+        "at" => timestamp
+      }.compact
+      record["updated_at"] = timestamp
+      @store.set(SCOPE, key_for(id), record)
+      to_session(record)
+    end
+
     # -> bool (delegates to the backend: false for a nonexistent id)
     def delete(id)
       @store.delete(SCOPE, key_for(id))
@@ -189,7 +218,8 @@ module Insika
         created_at: record["created_at"],
         updated_at: record["updated_at"],
         briefing: record["briefing"] || { "fields" => {}, "next_step" => nil },
-        evidence: record["evidence"]
+        evidence: record["evidence"],
+        compaction: record["compaction"]
       )
     end
 

data/lib/insika/settings_store.rb

@@ -30,7 +30,14 @@ module Insika
       "max_retries" => 2,
       "turn_timeout" => 120,
       "tool_timeout" => 30,
-      "compaction" => { "enabled" => false, "keep_last" => 20 },
+      # In-session compaction (RFC-0044): when a session's UNCOMPACTED
+      # transcript grows past `compact_after` messages, everything but the
+      # last `keep_last` is summarized (model -> compaction.model, else the
+      # platform utility_model) into one history fragment. `prompt` replaces
+      # the engine default wholesale (the distill convention). enabled: false
+      # = parity (nothing runs). Additive keys — reads overlay DEFAULTS.
+      "compaction" => { "enabled" => false, "keep_last" => 20,
+                        "compact_after" => 40, "model" => nil },
       # Data lifecycle (WS8, phase 2): the RETENTION window in days. The
       # tick's Retention sweep purges sessions (+traces), terminal tasks
       # (+checkpoints), memory cells and outcomes older than this. nil/0 =

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/soak/runner.rb

@@ -50,7 +50,7 @@ module Insika
 
         Environment:
           INSIKA_URL              base URL of the engine (default: http://localhost:9292)
-          OPENCLAW_GATEWAY_TOKEN  Bearer; falls back to ADMIN_TOKEN, then "local-demo"
+          INSIKA_GATEWAY_TOKEN  Bearer; falls back to ADMIN_TOKEN, then "local-demo"
       TXT
 
       # Poisson inter-arrival seconds: `-mean * Math.log(1.0 - rand)`. Seeded,
@@ -245,7 +245,7 @@ module Insika
           "  agent:    #{@agent}",
           "  shape:    #{@envelope[:turns_per_hour]} turns/h poisson, #{@envelope[:session_turns]}-turn sessions, " \
           "cap #{@envelope[:concurrency_cap]}, #{@envelope[:duration_hours]}h (#{@envelope[:warmup_hours]}h warmup)",
-          "  sample:   POST #{URI.join(target_url + '/', 'v1/responses')} model=openclaw:#{@agent} user=soak-1",
+          "  sample:   POST #{URI.join(target_url + '/', 'v1/responses')} model=insika:#{@agent} user=soak-1",
           "  out:      #{@out}/"
         ]
         unless @envelope.calibrated?
@@ -345,7 +345,7 @@ module Insika
 
       private
 
-      def resolve_token(env) = env["OPENCLAW_GATEWAY_TOKEN"] || env["ADMIN_TOKEN"] || "local-demo"
+      def resolve_token(env) = env["INSIKA_GATEWAY_TOKEN"] || env["ADMIN_TOKEN"] || "local-demo"
 
       def install_traps
         %w[INT TERM].each { |sig| Signal.trap(sig) { @stop_reason = "interrupted" } }
@@ -489,7 +489,7 @@ module Insika
           req["Authorization"] = "Bearer #{@token}"
           req["Content-Type"] = "application/json"
           req["Accept"] = "text/event-stream"
-          req.body = JSON.generate(model: "openclaw:#{agent}", user: user, stream: true, input: message)
+          req.body = JSON.generate(model: "insika:#{agent}", user: user, stream: true, input: message)
 
           t0 = Process.clock_gettime(Process::CLOCK_MONOTONIC)
           ttfb = nil

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)