insika 0.1.0 → 0.2.0

data/lib/insika/studio/app.rb

@@ -30,8 +30,8 @@ module Studio
   # Same-origin assets: versioned esbuild bundle in `assets/dist/*`, served
   # by `/studio/assets/dist/*`. Strict `'self'` CSP (no `unsafe-inline`).
   class App < Roda
-    include Forms     # form -> command-payload parsing (§11 B6)
-    include NavIcons  # nav SVG helper (§11 B6)
+    include Forms     # form -> command-payload parsing
+    include NavIcons  # nav SVG helper
 
     # The session cookie lives N days. 7 days = parity with the OpenClaw default.
     SESSION_MAX_AGE = 7 * 24 * 3600
@@ -82,7 +82,7 @@ module Studio
                     agent_file_store: nil, skill_store: nil, skill_catalog: nil,
                     tool_catalog: nil, tool_store: nil, memory_store: nil, session_store: nil,
                     settings_store: nil, llm_provider_store: nil, mcp_store: nil,
-                    system_file_store: nil, tool_trace_store: nil,
+                    system_file_store: nil, tool_trace_store: nil, context_trace_store: nil,
                     task_store: nil, checkpoint_store: nil, pending_action_store: nil,
                     refinement_store: nil, golden_store: nil, session_secret: nil)
         @insika = {
@@ -90,7 +90,7 @@ module Studio
           event_stream: event_stream, config: config,
           agent_file_store: agent_file_store, skill_store: skill_store,
           skill_catalog: skill_catalog, tool_catalog: tool_catalog,
-          # tool_store: DATA-DEFINED tool definitions (Phase 5). The catalog already
+          # tool_store: DATA-DEFINED tool definitions. The catalog already
           # shows the data-tools in the matrix; the store feeds the authoring page.
           tool_store: tool_store,
           memory_store: memory_store, session_store: session_store,
@@ -99,17 +99,20 @@ module Studio
           settings_store: settings_store, llm_provider_store: llm_provider_store,
           mcp_store: mcp_store, system_file_store: system_file_store,
           # per-session tool-call trace (debug): args + result + status per
-          # turn, rendered in the session viewer (FOLLOWUP §3.1).
+          # turn, rendered in the session viewer.
           tool_trace_store: tool_trace_store,
-          # operate: tasks + human-in-the-loop approvals (§12 G5). Reads the
+          # per-session context breakdown: tokens by category +
+          # budget per turn, on the same viewer. Counts only, no content.
+          context_trace_store: context_trace_store,
+          # operate: tasks + human-in-the-loop approvals. Reads the
           # task/checkpoint/pending stores to render; controls (pause/resume/
           # cancel/approve) dispatch on the bus — parity with server/admin.
           task_store: task_store, checkpoint_store: checkpoint_store,
           pending_action_store: pending_action_store,
-          # refinement runs (RFC-0013 phase A): the ranked failure report per agent.
+          # refinement runs: the ranked failure report per agent.
           # Read-only here; the "Run" button dispatches :run_refinement on the bus.
           refinement_store: refinement_store,
-          # eval cases (RFC-0008 §3.1): read to render; writes go through :write_golden.
+          # eval cases: read to render; writes go through:write_golden.
           golden_store: golden_store
         }.freeze
         # "restart recommended" flag — in memory, PER PROCESS. A
@@ -304,15 +307,53 @@ module Studio
             end
           end
 
-          # Agent skills → :update_agent with the `skills` allowlist.
-          # "all" = nil; otherwise the checked subset (possibly []).
-          r.post "skills" do
-            check_csrf!
-            skills = r.params["all_skills"] == "1" ? nil : Array(r.params["skills"]).map(&:to_s)
-            with_flash("Skills updated.") do
-              dispatch(:update_agent, { id: id, skills: skills })
+          r.on "skills" do
+            # POST /studio/agents/:id/skills → :update_agent with the `skills`
+            # allowlist. "all" = nil; otherwise the checked subset (possibly []).
+            r.is do
+              r.post do
+                check_csrf!
+                skills = r.params["all_skills"] == "1" ? nil : Array(r.params["skills"]).map(&:to_s)
+                with_flash("Skills updated.") do
+                  dispatch(:update_agent, { id: id, skills: skills })
+                end
+                r.redirect(agent_path(id))
+              end
+            end
+
+            # /studio/agents/:id/skills/:name — this agent's OWN version of a skill.
+            # TWO path segments, which is exactly why the store takes the agent as a
+            # second argument: a composite "agent/name" key would put a `/` inside
+            # what this route serves as one segment.
+            r.on String do |name|
+              name = utf8(name)
+              r.is do
+                r.get do
+                  load_skills_master(agent: id)
+                  @selected = name
+                  @scope_agent = id
+                  @skill_content = skill_source(name, agent: id)
+                  view("skills")
+                end
+                # Saving the specialization: same command, `agent:` set.
+                r.post do
+                  check_csrf!
+                  with_flash("Specialization saved.") do
+                    dispatch(:write_skill, { name: name, agent: id, content: r.params["content"].to_s })
+                  end
+                  r.redirect("#{agent_path(id)}/skills/#{Rack::Utils.escape(name)}")
+                end
+              end
+
+              # Un-specialize: the shared skill stays, and the agent falls back to it.
+              r.post "delete" do
+                check_csrf!
+                with_flash("Specialization removed — the agent falls back to the shared skill.") do
+                  dispatch(:delete_skill, { name: name, agent: id })
+                end
+                r.redirect("/studio/skills/#{Rack::Utils.escape(name)}")
+              end
             end
-            r.redirect(agent_path(id))
           end
 
           # Agent memory. Scoped by tenant = agent id — the
@@ -381,25 +422,37 @@ module Studio
               view("skills")
             end
           end
-          # Enables/disables the skill on N agents at once.
+          # Enables/disables the skill on N agents at once, and marks it always-on for
+          # the ones that checked `eager`. Both are per-agent decisions about the same
+          # skill, so they are the same form and the same dispatch.
           r.post "agents" do
             check_csrf!
             agent_ids = Array(r.params["agent_ids"]).map(&:to_s)
+            eager_ids = Array(r.params["eager_ids"]).map(&:to_s)
             result = with_flash("Skill's agents updated.") do
-              dispatch(:set_skill_agents, { name: name, agent_ids: agent_ids })
-            end
-            skipped = Array(result && result[:skipped_all])
-            if skipped.any?
-              flash["notice"] = "#{flash['notice']} — #{skipped.size} agent(s) with 'all' skills were left intact."
+              dispatch(:set_skill_agents, { name: name, agent_ids: agent_ids, eager_ids: eager_ids })
             end
+            note_skipped(result)
             r.redirect("/studio/skills")
           end
+
+          # Seeds a per-agent override from the SHARED body and opens it for editing.
+          # Seeded and not blank: specializing means "this, but for me" — starting from
+          # an empty editor is how the two versions drift apart on day one.
+          r.post "specialize" do
+            check_csrf!
+            agent_id = presence(r.params["agent_id"])
+            with_flash("Specialized for #{agent_id}.") do
+              dispatch(:write_skill, { name: name, agent: agent_id, content: skill_source(name) })
+            end
+            r.redirect("/studio/agents/#{Rack::Utils.escape(agent_id.to_s)}/skills/#{Rack::Utils.escape(name)}")
+          end
         end
       end
 
       # --- Tools: tool × agent matrix + DATA-DEFINED tool authoring -----------
       r.on "tools" do
-        # Data-defined tool authoring (Phase 5). Under /tools/def/* — BEFORE the
+        # Data-defined tool authoring. Under /tools/def/* — BEFORE the
         # generic `r.post String` matcher (which is the allow/deny matrix per agent :id).
         r.on "def" do
           # /studio/tools/def/new — empty editor.
@@ -474,7 +527,7 @@ module Studio
       r.on "settings" do
         r.is do
           r.get { render_settings }
-          # General settings (streaming/timeouts/compaction) → :update_settings.
+          # General settings (streaming/timeouts) → :update_settings.
           r.post do
             check_csrf!
             with_flash("Settings saved.") do
@@ -484,7 +537,7 @@ module Studio
           end
         end
 
-        # Platform model defaults (sub-resource, v2 §10): its own form/route so a
+        # Platform model defaults (sub-resource, v2): its own form/route so a
         # general-settings save never clobbers the model layer.
         r.post "models" do
           check_csrf!
@@ -494,7 +547,7 @@ module Studio
           r.redirect("/studio/settings?s=models")
         end
 
-        # Per-model reasoning defaults (§10, the per-model layer): its own form so a
+        # Per-model reasoning defaults (the per-model layer): its own form so a
         # model-defaults save never clobbers the per-model map, and vice-versa.
         r.post "model-params" do
           check_csrf!
@@ -504,7 +557,7 @@ module Studio
           r.redirect("/studio/settings?s=models")
         end
 
-        # Edge limits (item 33 / §12 G7): the platform rate-limit/cost layer.
+        # Edge limits: the platform rate-limit/cost layer.
         # Its own form for the same reason as models — saves never cross-clobber.
         r.post "edge" do
           check_csrf!
@@ -514,7 +567,7 @@ module Studio
           r.redirect("/studio/settings?s=edge")
         end
 
-        # Evals (RFC-0008 / RFC-0013 §3.9): the judge PANEL and how it agrees. Its own
+        # Evals: the judge PANEL and how it agrees. Its own
         # form, like models and edge — a save here must not clobber those.
         r.post "evals" do
           check_csrf!
@@ -619,12 +672,14 @@ module Studio
             # Session's tool-call trace (debug): grouped by turn in the view.
             @tool_traces = (insika[:tool_trace_store]&.for_session(sid) || [])
                            .group_by { |t| t["turn"] }
+            # Context breakdown per turn: chronological entries.
+            @context_traces = insika[:context_trace_store]&.for_session(sid) || []
             view("session")
           end
         end
       end
 
-      # --- Tasks: list + detail + operator controls (§12 G5) -------
+      # Tasks: list + detail + operator controls -------
       # Parity with server/admin: READS the task/checkpoint/pending stores to
       # render; pause/resume/cancel dispatch Commands on the bus (never a direct
       # store write). Every control audits the ATTEMPT to the EventStream first.
@@ -658,7 +713,7 @@ module Studio
         end
       end
 
-      # --- Approvals: human-in-the-loop inbox (§12 G5) -------------
+      # Approvals: human-in-the-loop inbox -------------
       # Lists every :pending action across tasks; resolving one dispatches
       # :approve_action, which resolves the store AND wakes the suspended turn.
       r.on "approvals" do
@@ -677,7 +732,7 @@ module Studio
         end
       end
 
-# --- Evals: the cases that grade an agent (RFC-0008 §3.1) -------
+# Evals: the cases that grade an agent -------
 # A case is DATA in the same YAML shape the corpus files use, so what an operator
 # edits here is what a pull request would review. The one loader validates it, on
 # the way in — a malformed case is a red flash, never a silently skipped test.
@@ -702,8 +757,8 @@ r.on "evals" do
 end
 
       # --- Refinement: what broke in real traffic, and what to do about it --
-      # `POST /refinement` runs the report (RFC-0013 phase A). `POST
-      # /refinement/propose` is phase C: the configured model writes a candidate from
+      # `POST /refinement` runs the report. `POST
+      # refinement/propose` is: the configured model writes a candidate from
       # the findings and the gate scores it by replaying the golden set. `POST
       # /refinement/resolve` is a human approving or rejecting what the gate passed.
       # All three go through the bus like every other Studio write — this page reads
@@ -755,7 +810,7 @@ end
           @agent = presence(r.params["agent"]) || default_agent
           @session_id = presence(r.params["session_id"])
           @agents = insika[:profile_source].ids.sort
-          # Server-side echo + continuity (§11 A1): render the session's persisted
+          # Server-side echo + continuity: render the session's persisted
           # transcript as bubbles. The user's message is only persisted at the END
           # of the turn, so the just-sent message rides a one-shot flash bubble
           # (@sent_message) until it lands in history — an optimistic JS echo can't
@@ -772,7 +827,7 @@ end
           # Blank session = new conversation: created via Command (create_session
           # generates the id — the Studio doesn't write to the store directly). A typed id
           # continues an existing conversation (send_message requires it to exist).
-          # The per-chat model pin (v2, §10) is set at creation and rides the whole
+          # The per-chat model pin is set at creation and rides the whole
           # conversation, so it only applies to a NEW session — an existing one keeps
           # whatever it was pinned to.
           session_id = typed_session ||
@@ -780,7 +835,7 @@ end
                                       provider: presence(r.params["provider"]),
                                       thinking: presence(r.params["thinking"]))
           dispatch_send_message(agent: agent, session_id: session_id, message: message)
-          # Optimistic echo of the just-sent message (§11 A1): survives the redirect
+          # Optimistic echo of the just-sent message: survives the redirect
           # as a one-shot flash, rendered as a user bubble on the next GET.
           flash["sent_message"] = message unless message.empty?
           r.redirect(playground_path(agent, session_id))
@@ -830,7 +885,7 @@ end
       ]
     end
 
-    # NAV_ICONS + nav_icon moved to Studio::NavIcons (§11 B6).
+    # NAV_ICONS + nav_icon moved to Studio::NavIcons.
 
     def authenticated? = session["auth"] == true
 
@@ -914,7 +969,7 @@ end
 
     # A stored message's content for display: strings as-is; structured payloads
     # as pretty JSON. NEVER Ruby #inspect (session.erb:45 leaked hashrockets to the
-    # operator). §11 A2.
+    # operator)..
     def message_content(content)
       return content.to_s if content.is_a?(String)
 
@@ -923,6 +978,29 @@ end
       content.to_s
     end
 
+    # An activation label from the context trace, as the operator reads it:
+    # "gift-concierge · trigger:presente". The REASON is the point of the card — a
+    # bare list of names answers "was something injected", never "which one did I
+    # trigger". A label with no reason (a plugin-supplied body) shows just the name.
+    def skill_label(label)
+      return label.to_s unless label.is_a?(Hash)
+
+      name = label["name"].to_s
+      reason = label["reason"].to_s
+      reason.empty? ? name : "#{name} · #{reason}"
+    end
+
+    # One word for the whole turn, for the collapsed summary: the shared reason when
+    # every body arrived the same way, "mixed" when they did not. A turn CAN mix (the
+    # agent's eager set plus what this message triggered), which is exactly why the
+    # single per-turn `mode` this replaced was a lie waiting to happen.
+    def skill_mode(labels)
+      kinds = Array(labels).map { |l| (l.is_a?(Hash) ? l["reason"].to_s : "").split(":").first }.uniq
+      return "context" if kinds.empty? || kinds.any?(&:nil?) || kinds.include?("")
+
+      kinds.length == 1 ? kinds.first : "mixed"
+    end
+
     # ISO8601 → "HH:MM" for a transcript timestamp; "" when unparseable/absent.
     def short_time(iso)
       Time.parse(iso.to_s).strftime("%H:%M")
@@ -981,11 +1059,11 @@ end
       end
       @all_skills = insika[:skill_catalog]&.all || []
       @agent_skills = @agent.skills.nil? ? nil : Array(@agent.skills).map(&:to_s)
-      # v2 (§10) config surfaces: generation params + model fence. AgentProfile.build
+      # v2 config surfaces: generation params + model fence. AgentProfile.build
       # string-keys these hashes, so the form helpers read plain string keys.
       @params = @agent.params
       @model_policy_allow = model_policy_allow(@agent)
-      # guardrails config (RFC-0009); nil when the agent never configured any.
+      # guardrails config; nil when the agent never configured any.
       @guardrails = @agent.guardrails || {}
       mem = insika[:memory_store]
       @facts = mem ? mem.facts(tenant: id) : []
@@ -1003,7 +1081,7 @@ end
     end
 
     # Renders the reasoning <select> shared by the agent config, settings and
-    # playground (§10, 4-layer). `blank_label` names the empty option — the
+    # playground (4-layer). `blank_label` names the empty option — the
     # "inherit the broader layer" / provider-default choice. Values come from a
     # fixed constant (safe to emit); `current` is only compared, never output.
     def thinking_select(name, current, blank_label)
@@ -1047,21 +1125,34 @@ end
 
     # Config patch from the form (native types: memory bool, limits int).
     # Preserves the existing limits, overwriting only the form's fields.
-    # `model` is OPTIONAL as of v2 (§10): blank clears it, so the agent inherits
+    # `model` is OPTIONAL as of v2: blank clears it, so the agent inherits
     # the platform `default_model` via the ModelResolver — the config form is the
     # place that surfaces that layering. params/model_policy: see the helpers below.
     # config_patch/guardrails_patch/guardrail_responses_patch/params_patch/
-    # model_policy_patch/coerce moved to Studio::Forms (§11 B6).
+    # model_policy_patch/coerce moved to Studio::Forms.
 
     # --- Skills index --------------------------------------------------------
 
     # Master data for the Skills drill-down (list + authored badges + agents),
     # shared by every skill route so the master pane always renders. @selected
     # drives the detail pane (nil = none, "" = new, name = edit).
-    def load_skills_master
-      @skills = (insika[:skill_catalog]&.all || []).sort_by(&:name)
-      @stored = insika[:skill_store] ? insika[:skill_store].names : []
+    # `agent` renders the AGENT's view of the catalog: its own version of each shared
+    # skill, plus whatever is private to it. Absent = the shared catalog.
+    def load_skills_master(agent: nil)
+      catalog = insika[:skill_catalog]
+      @skills = (catalog ? catalog.all(agent: agent) : []).sort_by(&:name)
+      @stored = insika[:skill_store] ? insika[:skill_store].names(agent: agent) : []
       @agents = insika[:profile_source].all.sort_by(&:id)
+      # Which agents specialized THIS skill — the availability grid shows it, so an
+      # override is discoverable from the shared skill it overrides.
+      @specialized = insika[:skill_store] ? specialized_by : {}
+    end
+
+    # { skill name => [agent ids] } across every agent scope in the store.
+    def specialized_by
+      insika[:skill_store].agents.each_with_object({}) do |agent, acc|
+        insika[:skill_store].names(agent: agent).each { |name| (acc[name] ||= []) << agent }
+      end
     end
 
     def render_skills_index
@@ -1076,14 +1167,20 @@ end
     # Raw content for the editor: prefer the store (real SKILL.md), otherwise
     # reconstruct from what the catalog parsed (editing a disk skill
     # creates an override in the store — Store wins).
-    def skill_source(name)
-      raw = insika[:skill_store]&.get(name)
+    def skill_source(name, agent: nil)
+      raw = insika[:skill_store]&.get(name, agent: agent)
       return raw if raw
 
-      skill = insika[:skill_catalog]&.find(name)
+      skill = insika[:skill_catalog]&.find(name, agent: agent)
       return new_skill_template(name) unless skill
 
-      "---\nname: #{skill.name}\ndescription: #{skill.description}\n---\n\n#{skill.body}\n"
+      # The WHOLE frontmatter, not just name/description: this text seeds the
+      # specialize action and any first edit of a disk skill, and an override that
+      # silently drops `triggers:` turns the agent's deterministic activation off.
+      fm = ["name: #{skill.name}", "description: #{skill.description}"]
+      fm << "triggers: #{skill.triggers.join(', ')}" if Array(skill.triggers).any?
+      fm << "companions: #{skill.companions.join(', ')}" if Array(skill.companions).any?
+      "---\n#{fm.join("\n")}\n---\n\n#{skill.body}\n"
     end
 
     def new_skill_template(name = "my-skill")
@@ -1097,6 +1194,31 @@ end
       profile.skills.nil? || Array(profile.skills).map(&:to_s).include?(skill_name.to_s)
     end
 
+    # Is this skill always-on for this agent? `skills_eager` is nil/false (none), true
+    # (blanket) or a list — NOT allowlist semantics, so nil must read as false here.
+    def skill_eager_for?(profile, skill_name)
+      spec = profile.skills_eager
+      return true if Insika::Coercion.truthy?(spec)
+      return false if spec.nil? || spec == false
+
+      Array(spec).map(&:to_s).include?(skill_name.to_s)
+    end
+
+    # The two "left intact" outcomes of :set_skill_agents: an agent whose allowlist (or
+    # eager set) is "all" cannot have ONE name removed from it without materializing an
+    # explicit list, which would be a destructive surprise. Say so instead of silently
+    # doing nothing.
+    def note_skipped(result)
+      return unless result
+
+      parts = []
+      skipped = Array(result[:skipped_all])
+      eager = Array(result[:skipped_eager_all])
+      parts << "#{skipped.size} agent(s) with 'all' skills were left intact" if skipped.any?
+      parts << "#{eager.size} agent(s) with blanket eager were left intact" if eager.any?
+      flash["notice"] = "#{flash['notice']} — #{parts.join(', ')}." if parts.any?
+    end
+
     # --- Tools matrix --------------------------------------------------------
 
     def render_tools_matrix
@@ -1137,7 +1259,7 @@ end
       tools.count { |t| allow.include?(t.name.to_s) && !tool_denied_for?(profile, t.name) }
     end
 
-    # --- Data-defined tool authoring (Phase 5) -------------------------------
+    # Data-defined tool authoring -------------------------------
 
     def render_tool_edit(name:, tool:)
       @tool_name = name
@@ -1164,7 +1286,7 @@ end
       }
     end
 
-    # tool_patch/parse_parameters moved to Studio::Forms (§11 B6).
+    # tool_patch/parse_parameters moved to Studio::Forms.
 
     # Inverse of parse_parameters: the stored params -> text for the textarea. A schema
     # the flat sugar can express round-trips as pipe lines (the friendly form); anything
@@ -1333,10 +1455,10 @@ end
       view("settings")
     end
 
-    # Settings patch from the form. streaming/compaction are bool
-    # (checkbox); the timeouts are integers; compaction.keep_last integer. Only what
-    # came in the form enters the patch (the rest and the defaults are preserved in the store).
-    # settings_patch/model_defaults_patch/provider_patch moved to Studio::Forms (§11 B6).
+    # Settings patch from the form. streaming is a bool (checkbox); the timeouts
+    # are integers. Only what came in the form enters the patch (the rest and
+    # the defaults are preserved in the store).
+    # settings_patch/model_defaults_patch/provider_patch moved to Studio::Forms.
 
     # --- MCP -------------------------------------------------------
 
@@ -1345,7 +1467,7 @@ end
       view("mcp")
     end
 
-    # mcp_patch moved to Studio::Forms (§11 B6).
+    # mcp_patch moved to Studio::Forms.
 
     # --- System-files ----------------------------------------------
 
@@ -1365,7 +1487,7 @@ end
       view("chats")
     end
 
-    # --- Tasks & Approvals (§12 G5) --------------------------------
+    # Tasks & Approvals --------------------------------
 
     # Task list, most-recently-updated first. Empty-state if no store was injected.
     def render_tasks
@@ -1392,7 +1514,7 @@ end
       view("approvals")
     end
 
-# --- Evals (RFC-0008 §3.1) -------------------------------------
+# Evals -------------------------------------
 
 # The stored cases, grouped by agent, plus the one being edited (?id=). Cases whose
 # stored mapping no longer validates are listed separately: a broken case must be
@@ -1417,7 +1539,7 @@ def golden_yaml(golden)
   YAML.dump(h.merge("expect" => golden.expect))
 end
 
-    # --- Refinement (RFC-0013 phase A) -----------------------------
+    # Refinement -----------------------------
 
     # The agent's latest failure report + its run history. Empty-state when no store
     # was injected or the agent has never been run — the page is the invitation to
@@ -1484,7 +1606,7 @@ end
 
     def task_path(id) = "/studio/tasks/#{Rack::Utils.escape(id.to_s)}"
 
-    # parse_kv_lines moved to Studio::Forms (§11 B6).
+    # parse_kv_lines moved to Studio::Forms.
 
     # CSV/whitespace -> [String], blanks dropped.
     def split_list(str)