insika 0.1.0 → 0.2.0

data/lib/insika/dsl.rb

@@ -3,17 +3,17 @@
 require_relative "pack"
 
 module Insika
-  # Public Ruby DSL (item 36 / §13.3) — the OSS "business card":
+  # Public Ruby DSL — the OSS "business card":
   #
   #   agent = Insika.agent("assistant") do
-  #     model "deepseek-chat"
+  #     model "deepseek-v4-flash"
   #     instructions "You are a concise, friendly assistant."
   #   end
   #   puts agent.reply("hi, what can you do?")   # one turn, in-process
   #   agent.serve                                # control UI + /v1 on :9292
   #
   # It is THIN SUGAR that GENERATES the data (a Insika::Pack), never a bypass of
-  # config-over-code (COMPETITIVE-ANALYSIS §4.1). `Insika.agent { … }.to_pack`
+  # config-over-code (COMPETITIVE-ANALYSIS). `Insika.agent { … }.to_pack`
   # is the same portable artifact the PackImporter consumes at runtime — the DSL
   # and a hand-written pack produce the SAME profile (the parity spec proves it),
   # because BOTH go through the standard import → StoredProfileSource round-trip.
@@ -153,7 +153,7 @@ module Insika
 
       # A DATA-DEFINED (declarative HTTP) tool — pure config-over-code. `defn` is a
       # ToolDefinition hash (name/description/parameters/binding…). Its name is
-      # auto-added to the allowlist so the agent can call its own tool (NF2).
+      # auto-added to the allowlist so the agent can call its own tool.
       def data_tool(defn)
         h = defn.transform_keys(&:to_s)
         @tools << h
@@ -173,9 +173,31 @@ module Insika
         n
       end
 
+      # skills_eager — turns progressive disclosure off for THIS agent, wholly or in
+      # part. The body of an eager skill is in the prompt on every turn, so its
+      # activation is not a decision and cannot be missed; it is paid for on every
+      # turn, so measure the bodies against `context_budget` first (a stable position
+      # makes them a cacheable prefix).
+      #
+      #   skills_eager                       # every allowed skill
+      #   skills_eager "formato", "markers"  # exactly these
+      #   skills_eager false                 # none (the default)
+      #
+      # A LIST and not a per-skill flag because skills are shared: `escalation-to-human`
+      # sits in several allowlists, and one flag on the skill would force one decision
+      # onto every agent holding it.
+      def skills_eager(*names)
+        flat = names.flatten
+        @config[:skills_eager] =
+          if flat.empty? then true
+          elsif flat == [true] || flat == [false] then flat.first
+          else flat.map(&:to_s)
+          end
+      end
+
       # --- delegation ------------------------------------------------------
       # subagents "security", "performance" → the child agents this one MAY
-      # spawn (RFC-0010). CAPACITY field: opt-in, never inherited, and the ids
+      # spawn. CAPACITY field: opt-in, never inherited, and the ids
       # must be agents of the same system (`Insika.system { … }`) or already in
       # the store. Present ⇒ the engine wires `spawn_subagent`/`spawn_subagents`.
       def subagents(*ids)
@@ -185,23 +207,58 @@ module Insika
       # --- knobs -----------------------------------------------------------
       def memory(on = true) = @config[:memory] = on
 
-      # Content-safety guardrails (RFC-0009) — opt-in and configurable per agent.
+      # Spend caps per calendar window (WS2): daily/monthly token budgets for
+      # this agent, per (tenant, agent) when multi-tenant. HARD is the default:
+      # absent `soft:` (or `soft: false`) turns the cap into a hard wall (the
+      # turn fails with budget_exceeded + retry_after); `soft: true` warns once
+      # per window and keeps running.
+      #   budget daily: 100_000, monthly: 2_000_000, soft: false
+      def budget(hash) = (@config[:budget] ||= {}).merge!(hash.transform_keys(&:to_s))
+
+      # Provider-interaction reliability, as DATA (WS3): retries + exponential
+      # backoff on transient failures, a fallback model chain (mid-turn
+      # rotation), and a circuit breaker per (tenant, provider/model) that
+      # fail-fasts once the window trips. `fallback`/`circuit_breaker` entries
+      # are "provider/model" refs or plain model ids.
+      #   reliability retries: 3, backoff: "exponential",
+      #               fallback: ["gpt-4o-mini"], circuit_breaker: { after: 10, within: 60, cooldown: 300 }
+      def reliability(hash)
+        (@config[:reliability] ||= {}).merge!(hash.transform_keys(&:to_s))
+      end
+
+      # Operator alert delivery (WS6): POST this agent's budget_warning /
+      # breaker_open / delivery_failed events to the webhook, as JSON.
+      #   alerts webhook: "https://ops.example.com/insika-alerts"
+      def alerts(hash) = (@config[:alerts] ||= {}).merge!(hash.transform_keys(&:to_s))
+
+      # The agent may signal it cannot proceed (WS5): when on, the model
+      # can call `signal_stuck`, which ends the turn with `outcome: :stuck` + a final
+      # message + a `:turn_stuck` event. What "stuck" means is the consumer's call.
+      #   stuck_signal true
+      def stuck_signal(on = true) = @config[:stuck_signal] = on
+
+      # Mechanical tool-result dedupe in the replayed history
+      # (no-LLM compaction, apt for bloated transcripts). CHANGES WHAT THE MODEL
+      # SEES: repeated identical tool results collapse to a back-reference.
+      def tool_output_compression(on = true) = @config[:tool_output_compression] = on
+
+      # Content-safety guardrails — opt-in and configurable per agent.
       # Pure config-over-code: the hash is stored on the profile and consumed by
       # Safety::Config.from_profile. Merges, so repeated calls accumulate.
       #   guardrails input: true, output: true, strictness: "medium",
-      #              moderator: "deepseek/deepseek-chat",
+      #              moderator: "deepseek/deepseek-v4-flash",
       #              responses: { "injection" => "I can't help with that." }
       def guardrails(hash) = (@config[:guardrails] ||= {}).merge!(hash.transform_keys(&:to_s))
 
-      # Refinement (RFC-0013) — how the agent's own instruction files may be
+      # Refinement — how the agent's own instruction files may be
       # improved from real traffic. Same config-over-code shape as `guardrails`;
-      # omitting it entirely leaves the agent report-only (phase A writes nothing).
+      # omitting it entirely leaves the agent report-only (writes nothing).
       #   refine mode: "propose", window: { last_sessions: 200 }, files: %w[TOOLS.md],
-      #          proposers: ["deepseek/deepseek-chat", "gpt-5-mini"],
+      #          proposers: ["deepseek/deepseek-v4-flash", "gpt-5-mini"],
       #          budget: { tokens: 200_000 }
       def refine(hash) = (@config[:refinement] ||= {}).merge!(hash.transform_keys(&:to_s))
 
-      # Facts about THIS deployment that are not tools (RFC-0014 §3.5), so an eval
+      # Facts about THIS deployment that are not tools, so an eval
       # case can declare what it needs and be skipped where it is absent instead of
       # failing for the wrong reason.
       #   declares "promotions", "human_handoff"
@@ -217,7 +274,7 @@ module Insika
       #   edge_stream thinking: true, intermediate: false
       def edge_stream(hash) = (@config[:edge_stream] ||= {}).merge!(hash.transform_keys(&:to_s))
 
-      # LLM generation params (v2, §10). `param :temperature, 0.2` or `params(...)`.
+      # LLM generation params. `param:temperature, 0.2` or `params(...)`.
       def param(key, value) = (@config[:params] ||= {})[key.to_sym] = value
       def params(hash) = (@config[:params] ||= {}).merge!(hash.transform_keys(&:to_sym))
       def temperature(value) = param(:temperature, value)
@@ -281,14 +338,14 @@ module Insika
     DSL.system(&block)
   end
 
-  # RFC-0017 A1 — the front door for MOUNTING Insika into an app you already
+  # the front door for MOUNTING Insika into an app you already
   # have. Same block as `Insika.system`, one added obligation: the caller names
   # the store, so the graph stops discovering it from `INSIKA_DB` and two graphs
   # in one process can no longer read each other's sessions.
   #
   #   INSIKA = Insika.embed(backend: Insika::Stores::SQLite.new(path: "storage/insika.sqlite3")) do
   #     agent "support" do
-  #       model "deepseek-chat"
+  #       model "deepseek-v4-flash"
   #       instructions "…"
   #     end
   #   end
@@ -296,7 +353,7 @@ module Insika
   #   mount Insika::Server.rack_app(INSIKA, token: ENV.fetch("INSIKA_TOKEN")), at: "/ai"
   #
   # It is a thin front door over the SAME assembly `Insika.system` uses — there is
-  # one pipeline (RFC-0001), and the parity spec holds it to that. What an embedded
+  # one pipeline, and the parity spec holds it to that. What an embedded
   # graph owns, and what it still shares with the process, is docs/EMBEDDING.md.
   def embed(backend:, &block)
     DSL.embed(backend: backend, &block)

data/lib/insika/edge_limiter.rb

@@ -4,7 +4,7 @@ require_relative "middleware"
 require_relative "coercion"
 
 module Insika
-  # The production edge (item 33 / §12 G7): THE named place where volume/cost
+  # The production edge: THE named place where volume/cost
   # abuse is cut. A Middleware with two independent limits, both OPT-IN
   # (nil/0 = off — a bare wiring behaves exactly as before):
   #
@@ -13,16 +13,29 @@ module Insika
   #   · agent token ceiling — total tokens per agent per window. Checked on entry
   #     against the accumulated ledger; the turn's own usage is recorded AFTER the
   #     terminal returns (the Middleware wraps stages 5-9, so state.usage is set).
+  #   · calendar budget    — WS2: `AgentProfile#budget` caps the spend per
+  #     (tenant, agent) over CALENDAR windows (daily/monthly), on the
+  #     BudgetLedger. Hard (default): crossing the cap raises the typed
+  #     Insika::BudgetExceeded (the envelope quotes budget_exceeded +
+  #     retry_after); soft: crossing warns instead — ONE budget_warning event
+  #     per window plus a note injected into the context. Crossing `alert_at`
+  #     (default 0.8 of the cap) warns the same way, before the wall. The turn's
+  #     billed spend (input+output+cached+cache_creation — the A4 rule) lands on
+  #     the windows after the terminal.
   #
   # Config resolution, per turn (configuration over convention):
   #   profile.limits[:chat_rate_limit / :agent_token_ceiling]  — per-agent override
   #   settings["edge"]                                          — platform default
   # A per-agent 0 explicitly disables a platform default for that agent.
   #
-  # On breach it uses the graceful-halt contract (RFC-0009 §3.1): halt_response
+  # On breach it uses the graceful-halt contract: halt_response
   # (the safe reply) + guardrail_block (audit -> :guardrail_blocked) and does NOT
   # call `nxt` — the turn completes with ZERO LLM calls. It sits BEFORE the
   # InputGuardrail in the stack so a flood can't spend the LLM moderator either.
+  # The BUDGET breach is the ONE deliberate exception: it is a typed failure
+  # (BudgetExceeded), not a customer-facing reply — the operator wants the
+  # envelope to say "budget" and quote when the window rolls, not to hand the
+  # customer a cost message.
   class EdgeLimiter < Middleware
     CHAT_KIND   = "chat"
     TOKENS_KIND = "tokens"
@@ -35,9 +48,13 @@ module Insika
     DEFAULT_RESPONSE = "Estou recebendo muitas mensagens agora. Aguarde um " \
                        "momento e tente novamente, por favor."
 
-    def initialize(ledger:, settings_store: nil)
+    def initialize(ledger:, settings_store: nil, budget_ledger: nil, event_stream: nil)
       @ledger = ledger
       @settings = settings_store
+      # WS2: the calendar-window ledger. nil = budget off (parity — the bare
+      # wiring is byte-identical to before).
+      @budget_ledger = budget_ledger
+      @event_stream = event_stream
     end
 
     def call(state, &nxt)
@@ -69,8 +86,25 @@ module Insika
         record_after = token_window
       end
 
-      result = nxt.call(state)
-      record_usage(state, record_after) if record_after
+      # WS2: calendar budgets. Entry — a HARD budget at/over the cap raises the
+      # typed error (never a customer-facing reply); the alert_at warning and
+      # the SOFT over-cap both warn once per window + inject a context note.
+      # A resumed turn (crash/pause replay) was already admitted: it is never
+      # refused twice — its spend still lands on the ledger below.
+      budget_on = budget_configured?(state)
+      budget_enforce(state) unless resumed
+
+      result = begin
+        nxt.call(state)
+      ensure
+        # A turn that FAILED after burning tokens still SPENT them: record the
+        # usage the state captured before the error propagates. The ask's usage
+        # lands on state.usage before any later stage (guardrail block, tool
+        # error, workflow schema) can fail the turn — a failed turn must count
+        # against the budget like a completed one (WS2).
+        record_usage(state, record_after) if record_after
+        record_budget_usage(state) if budget_on
+      end
       result
     end
 
@@ -101,7 +135,7 @@ module Insika
     # prefix (`Executor#usage_of` reports `cached_tokens`/`cache_creation_tokens`
     # alongside it) — on a cached identity that prefix is ~95% of what the
     # provider actually processed, so a ceiling reading only `total_tokens` is
-    # blind (RFC-0016 A4). Same billed-spend rule as `Evals::Runner#billed_tokens`.
+    # blind. Same billed-spend rule as `Evals::Runner#billed_tokens`.
     # nil usage (workflow turn / provider without counts) records nothing.
     def record_usage(state, window)
       usage = state.usage || {}
@@ -126,5 +160,109 @@ module Insika
       v = value.to_i
       v.positive? ? v : nil
     end
+
+    # --- WS2 calendar budgets ------------------------------------------
+
+    # -> truthy when a budget is configured AND the ledger is wired.
+    def budget_configured?(state)
+      budget = state.profile.respond_to?(:budget) ? state.profile.budget : nil
+      !budget.nil? && !@budget_ledger.nil?
+    end
+
+    # -> truthy (the budget hash) when budget checks ran. Raises BudgetExceeded
+    # on a HARD cap breach.
+    def budget_enforce(state, now: Time.now)
+      budget = state.profile.respond_to?(:budget) ? state.profile.budget : nil
+      return nil if budget.nil? || @budget_ledger.nil?
+
+      tenant = budget_tenant(state)
+      agent = state.profile.id.to_s
+      budget_windows(budget).each do |w|
+        spent = @budget_ledger.current(tenant: tenant, agent: agent, now: now)[w[:window]]
+        if spent >= w[:cap]
+          unless w[:soft]
+            raise Insika::BudgetExceeded.new(
+              window: w[:window],
+              retry_after: @budget_ledger.reset_in(w[:window], now: now)
+            )
+          end
+          warn_budget(state, tenant, agent, w, spent, now, level: "cap")
+        elsif spent >= w[:alert_at]
+          warn_budget(state, tenant, agent, w, spent, now, level: "alert_at")
+        end
+      end
+      budget
+    end
+
+    # The (tenant, agent) scope: the COMMAND's tenant (nil -> the BudgetLedger's
+    # "platform" cell) — never state.tenant, which falls back to the session id
+    # (a per-chat bucket is not a budget).
+    def budget_tenant(state)
+      command = state.respond_to?(:task) && state.task&.command
+      return nil unless command.is_a?(Hash)
+
+      meta = command["meta"] || command[:meta] || {}
+      meta["tenant"] || meta[:tenant]
+    end
+
+    # -> [{ window:, cap:, soft:, alert_at: }] — one entry per configured window
+    # (a 0/absent cap is off). absent `soft` = FALSE (hard): a limit that does
+    # not limit is decoration; the alert_at warning is the soft half.
+    def budget_windows(budget)
+      alert_at = budget["alert_at"].to_f
+      alert_at = 0.8 if alert_at <= 0 || alert_at >= 1
+      soft = budget["soft"] == true
+      %i[daily monthly].filter_map do |window|
+        cap = budget[window.to_s].to_i
+        cap.positive? ? { window: window, cap: cap, soft: soft,
+                          alert_at: (cap * alert_at).floor } : nil
+      end
+    end
+
+    # The warning: a note in the context (the model sees it, the customer's
+    # transcript does not) + the budget_warning event — each LEVEL once per
+    # (window) cell: the `alert_at` crossing and the real soft-cap crossing are
+    # separate markers, so the cap event is never swallowed by the 80% one that
+    # fired earlier (WS2).
+    def warn_budget(state, tenant, agent, w, spent, now, level:)
+      inject_budget_note(state,
+                         "[budget: agent '#{agent}' is at #{spent}/#{w[:cap]} tokens this " \
+                         "#{w[:window]} window — keep this turn cheap]")
+      return if @budget_ledger.mark_alert(tenant: tenant, agent: agent, window: w[:window],
+                                          level: level, now: now)
+
+      @event_stream&.emit(Insika::Event.new(
+                            type: :budget_warning,
+                            data: { agent: agent, tenant: tenant, window: w[:window],
+                                    spent: spent, cap: w[:cap], level: level },
+                            meta: { task_id: state.task&.id, session_id: state.task&.session_id,
+                                    at: Time.now.utc.iso8601 }
+                          ))
+    end
+
+    # Appends the note to the assembled system prompt: the real Data package is
+    # immutable (with), the specs' minimal Struct is mutable — both duck-typed.
+    def inject_budget_note(state, note)
+      ctx = state.context
+      return if ctx.nil?
+
+      if ctx.respond_to?(:with)
+        state.context = ctx.with(system: "#{ctx.system}\n\n#{note}")
+      elsif ctx.respond_to?(:system=)
+        ctx.system = "#{ctx.system}\n\n#{note}"
+      end
+    end
+
+    # The turn's REAL billed spend (input + output + cached + cache_creation —
+    # the A4 rule) on the calendar windows.
+    def record_budget_usage(state, now: Time.now)
+      usage = state.usage || {}
+      tokens = usage[:total_tokens].to_i + usage[:cached_tokens].to_i +
+               usage[:cache_creation_tokens].to_i
+      return if tokens.zero?
+
+      @budget_ledger.add(tenant: budget_tenant(state), agent: state.profile.id.to_s,
+                         by: tokens, now: now)
+    end
   end
 end

data/lib/insika/egress_guard.rb

@@ -8,14 +8,14 @@ module Insika
   # EGRESS guard for data-tools (SSRF). A data-tool makes a server-side HTTP
   # request with a URL coming from UI-editable config — without a guard, it's an
   # SSRF vector (hitting cloud metadata, internal services, localhost). Rules
-  # (spec NF2):
+  # (spec):
   #   - https only by default (http requires explicit opt-in);
   #   - host required;
   #   - optional host allowlist (when present, only it passes);
   #   - resolves the host and BLOCKS if ANY address falls into a private/
   #     loopback/link-local/metadata network (defense against DNS rebinding);
   #   - `allow_private:` (opt-in) ALLOWS the private target — to reach a trusted
-  #     INTERNAL API (NF4: the consumer's /api/internal/* comes in via an
+  #     INTERNAL API (the consumer's /api/internal/* comes in via an
   #     allowlist). Dangerous without `host_allowlist`: PIN it to a known host.
   #     Default false = strict guard.
   #
@@ -48,7 +48,7 @@ module Insika
       addrs = resolve(host)
       return "host did not resolve" if addrs.empty?
       # allow_private skips the private-network block (trusted internal API,
-      # NF4). Without it, a private/loopback/metadata target is always blocked.
+      # Without it, a private/loopback/metadata target is always blocked.
       return "private-network destination blocked" if !allow_private && addrs.any? { |ip| blocked?(ip) }
 
       nil

data/lib/insika/env_schema.rb

@@ -1,7 +1,7 @@
 # frozen_string_literal: true
 
 module Insika
-  # STRICT config, environment layer (item 23 / §8.1). OpenClaw's config discipline
+  # STRICT config, environment layer. OpenClaw's config discipline
   # — "recusa boot com chave desconhecida, no silent config compat" — applied to the
   # env vars the engine reads at boot. A declarative registry of the keys the engine
   # OWNS (config over convention: the schema IS data), used two ways:
@@ -12,7 +12,7 @@ module Insika
   #     silence), and a DEPRECATED legacy key still set under the old HARNESS_ prefix.
   #     Unknown-key detection is scoped to the OWNED prefixes only, so the platform's
   #     own vars (Railway's RAILWAY_*, PORT, PATH, the litestream sidecar's
-  #     LITESTREAM_*, the deployment's DEEPSEEK_*/ACHEI_*) are never flagged.
+  #     LITESTREAM_*, the deployment's DEEPSEEK_*/CONSUMER_*) are never flagged.
   #   · `enforce!(strict:)` — the boot gate. WARNS on every finding by default and
   #     lets the engine come up (last-known-good — a rotated key or a typo must never
   #     take the whole service down, same reasoning as the resilient DEEPSEEK boot);
@@ -92,7 +92,7 @@ module Insika
       Spec.new(name: name, type: type, secret: secret, required: required, enum: enum, description: description)
     end
 
-    # The engine's own keys. Deployment/app keys (DEEPSEEK_*, ACHEI_*, …) are NOT
+    # The engine's own keys. Deployment/app keys (DEEPSEEK_*, CONSUMER_*, …) are NOT
     # here — a root passes them as `extra:`.
     DEFAULT = [
       spec(name: "INSIKA_DB", type: :path, description: "SQLite path; durable config+state. Unset -> ephemeral memory."),
@@ -107,17 +107,20 @@ module Insika
       spec(name: "INSIKA_EGRESS_HOSTS", type: :csv, description: "Comma-separated host allowlist for data-tool egress."),
       spec(name: "INSIKA_OTEL", type: :boolean, description: "Turn on OpenTelemetry export (opt-in)."),
       spec(name: "INSIKA_MODEL_PRICING", description: "JSON rates table (USD per million tokens) for the estimated-cost attribute; unset -> no cost reported."),
-      spec(name: "INSIKA_TURN_TIMING", type: :boolean, description: "Emit per-turn TTFB breakdown in responses (opt-in, item 34)."),
+      spec(name: "INSIKA_TURN_TIMING", type: :boolean, description: "Emit per-turn TTFB breakdown in responses (opt-in)."),
       spec(name: "INSIKA_SUBAGENT_DEPTH_CAP", type: :integer, description: "Max delegation depth in the subagent graph (default 5)."),
       spec(name: "INSIKA_SUBAGENT_FANOUT_CAP", type: :integer, description: "Max parallel children in spawn_subagents (default 8)."),
-      spec(name: "INSIKA_CONFIG_STRICT", type: :boolean, description: "Refuse boot on any config finding instead of warning (item 23)."),
-      spec(name: "INSIKA_BOOT_ID", description: "Boot generation id shared by all workers of one container start; the recovery task sweep runs once per id (RFC-0016). Unset -> every boot sweeps."),
-      spec(name: "INSIKA_DRAIN_TIMEOUT", type: :integer, description: "Seconds a stopping worker waits for in-flight turns before abandoning them to the next boot's recovery (default 20, RFC-0016 A3)."),
-      spec(name: "INSIKA_ONBOARDING", type: :boolean, description: "Expose the public onboarding surface (/start.md, /models.json, /docs) in production (opt-in, item 20)."),
-      spec(name: "INSIKA_RELAY_TOKEN", secret: true, description: "Bearer the relay consumer sends us. Unset -> the relay channel is not mounted (RFC-0011 §6)."),
+      spec(name: "INSIKA_CONFIG_STRICT", type: :boolean, description: "Refuse boot on any config finding instead of warning."),
+      spec(name: "INSIKA_BOOT_ID", description: "Boot generation id shared by all workers of one container start; the recovery task sweep runs once per id. Unset -> every boot sweeps."),
+      spec(name: "INSIKA_DRAIN_TIMEOUT", type: :integer, description: "Seconds a stopping worker waits for in-flight turns before abandoning them to the next boot's recovery (default 20)."),
+      spec(name: "INSIKA_TICK_INTERVAL", type: :integer, description: "Seconds between tick passes (outbox drain + stale recovery sweep). Default 60; 0 disables."),
+      spec(name: "INSIKA_TICK_STALE_AFTER", type: :integer, description: "Seconds a :queued/:running task must sit untouched before the tick sweeps it (default 900). Must exceed the largest turn_timeout of the deployment."),
+      spec(name: "INSIKA_TENANCY", enum: %w[single_tenant multi_tenant], description: "single_tenant (default: one operator credential) or multi_tenant (per-tenant + operator tokens resolved from the store)."),
+      spec(name: "INSIKA_ONBOARDING", type: :boolean, description: "Expose the public onboarding surface (/start.md, /models.json, /docs) in production (opt-in)."),
+      spec(name: "INSIKA_RELAY_TOKEN", secret: true, description: "Bearer the relay consumer sends us. Unset -> the relay channel is not mounted."),
       spec(name: "INSIKA_RELAY_DELIVER_URL", type: :url, description: "Consumer callback the relay POSTs each reply to."),
       spec(name: "INSIKA_RELAY_DELIVER_TOKEN", secret: true, description: "Bearer the relay sends TO the consumer's callback (optional)."),
-      spec(name: "INSIKA_WIDGET_ORIGINS", type: :csv, description: "Exact-match origins allowed to embed the web widget. Unset -> the widget channel is not mounted (RFC-0011 §5)."),
+      spec(name: "INSIKA_WIDGET_ORIGINS", type: :csv, description: "Exact-match origins allowed to embed the web widget. Unset -> the widget channel is not mounted."),
       spec(name: "INSIKA_WIDGET_AGENTS", type: :csv, description: "Agent ids a widget visitor may address. Unset -> the widget channel is not mounted."),
       spec(name: "OPENCLAW_GATEWAY_TOKEN", secret: true, description: "Bearer for /v1 + /a2a (falls back to ADMIN_TOKEN)."),
       spec(name: "OPENCLAW_AGENTS_DIR", type: :path, description: "Directory of OpenClaw-style agent packs."),

data/lib/insika/errors.rb

@@ -30,7 +30,63 @@ module Insika
     end
   end
 
-  class ProviderError  < Error; end  # RubyLLM exhausted retries -> task :failed
+    # A provider/transport failure, wrapped by ProviderErrorClassifier with an
+  # ACTION classification (B9). The fields ride in the task's error record and
+  # the :task_failed event so the client envelope can tell fatal from
+  # retryable and quote the provider's own retry_after (A8). A bare
+  # `ProviderError.new("boom")` has an empty classification and adds nothing
+  # to the contract.
+  class ProviderError < Error
+    attr_reader :kind, :retryable, :retry_after
+
+    def initialize(message = nil, kind: nil, retryable: nil, retry_after: nil)
+      @kind = kind
+      @retryable = retryable
+      @retry_after = retry_after
+      super(message)
+    end
+
+    # the additive envelope fields, compacted — nil retry_after stays absent.
+    def classification
+      { kind: kind, retryable: retryable, retry_after: retry_after }.compact
+    end
+  end
+
+  # The hard budget refused the turn (WS2): the (tenant, agent) spend in the
+  # window already met its cap BEFORE the turn ran. A typed, retryable failure —
+  # the envelope reads `budget_exceeded` + `retry_after` (seconds until the
+  # window rolls) — never a silent drop. `window` is :daily | :monthly.
+  class BudgetExceeded < Error
+    attr_reader :window, :retry_after
+
+    def initialize(message = nil, window: nil, retry_after: nil)
+      @window = window
+      @retry_after = retry_after
+      super(message || "budget exceeded (#{window})")
+    end
+
+    def classification
+      { kind: :budget_exceeded, retryable: true, retry_after: retry_after }.compact
+    end
+  end
+
+  # The circuit breaker refused the turn WITHOUT touching the provider (WS3):
+  # the (tenant, provider/model) saw `after` failures within `within` seconds.
+  # Typed + retryable — the envelope reads `circuit_open` + `retry_after`
+  # (seconds until the cooldown lets a half-open trial through).
+  class CircuitOpenError < Error
+    attr_reader :ref, :retry_after
+
+    def initialize(message = nil, ref: nil, retry_after: nil)
+      @ref = ref
+      @retry_after = retry_after
+      super(message || "circuit open for #{ref}")
+    end
+
+    def classification
+      { kind: :circuit_open, retryable: true, retry_after: retry_after }.compact
+    end
+  end
   class StoreError     < Error; end  # persistence backend failed -> task :failed
   class CancelledError < Error; end  # cooperative cancellation -> task :cancelled
 
@@ -75,7 +131,7 @@ module Insika
     end
   end
 
-  # Subagent graph integrity (RFC-0010 §4.4). Raised at DEFINITION-time
+  # Subagent graph integrity. Raised at DEFINITION-time
   # (CreateAgent/UpdateAgent/boot) by SubagentGraph.validate! — a subagents
   # allowlist that forms a cycle or exceeds the depth cap is a configuration
   # error, never a runtime surprise. A ValidationError so the authoring Command
@@ -101,7 +157,7 @@ module Insika
     end
   end
 
-  # Workflow I/O contract violation (item 22 / §4.4). A workflow may declare an
+  # Workflow I/O contract violation. A workflow may declare an
   # `input_schema` / `output_schema`; a value that does not conform is rejected.
   # INPUT is validated SYNCHRONOUSLY (TriggerWorkflow) so it is a ValidationError
   # -> HTTP 422, no run created. OUTPUT is validated inside the fiber after the
@@ -119,14 +175,14 @@ module Insika
     end
   end
 
-  # A channel could not hand a reply to its recipient (RFC-0011 §6.5). NOT a turn
+  # A channel could not hand a reply to its recipient. NOT a turn
   # failure: the turn already completed and its answer is durable in the session —
   # what failed is the delivery, which lives in the OutboxStore with its own status
   # and its own bounded retry. Raised by a channel's `deliver` so the dispatcher can
   # tell "the recipient refused" from "the engine has a bug".
   class DeliveryError < Error; end
 
-  # Strict configuration violation (item 23 / §8.1 — OpenClaw's config discipline:
+  # Strict configuration violation (— OpenClaw's config discipline:
   # "recusa boot com chave desconhecida, no silent config compat"). Raised by
   # EnvSchema.enforce! at boot ONLY when strictness is on (INSIKA_CONFIG_STRICT) —
   # by default a bad key WARNS and the engine still boots (last-known-good: a rotated

data/lib/insika/evals/assertions.rb

@@ -1,6 +1,6 @@
 # frozen_string_literal: true
 
-# D4 (RFC-0009): the PII/secret patterns live in the RUNTIME (single source of
+# the PII/secret patterns live in the RUNTIME (single source of
 # truth) — the eval consumes them rather than keeping a divergent copy. Since the
 # module moved under `lib/`, `Safety::Detectors` is loaded by `insika.rb` before this
 # file; the explicit climb out of `evals/` that used to be here is gone.
@@ -33,12 +33,12 @@ module Insika
     # evaluated", never a silent pass. A case passes only if the deterministic checks
     # pass AND (there's no judge verdict OR it passed).
     #
-    # `skipped` (a reason, nil = it ran) is the THIRD outcome (RFC-0014 §3.2): the
+    # `skipped` (a reason, nil = it ran) is the THIRD outcome: the
     # deployment lacks something the case declared it needs, so there was nothing to
     # assert. It is never a pass and never a failure — a suite of 40 cases where 12
     # are skipped says something true, where 40 cases with 12 failures on capability
     # grounds says nothing and gets ignored.
-    # `pairwise` (a Pairwise::Verdict, RFC-0014 §3.4) is attached when the case
+    # `pairwise` (a Pairwise::Verdict) is attached when the case
     # carries a `reference:` and a panel is configured. It DELIBERATELY does not enter
     # `pass?`: "worse than the incumbent" is a judgement about a replacement decision,
     # not a regression in the suite, and letting it fail a case would put an opinion
@@ -53,25 +53,25 @@ module Insika
       def judge_pending? = !skipped? && !rubric.to_s.strip.empty? && judge.nil?
     end
 
-    # Deterministic (Fase A) evaluation — cheap, zero-token, zero-flakiness. It's the
+    # Deterministic evaluation — cheap, zero-token, zero-flakiness. It's the
     # layer that catches the gross regressions (a tool stopped being called, a secret
-    # leaked, the turn errored). Subjective scoring is the LLM-judge in Fase B.
+    # leaked, the turn errored). Subjective scoring is the LLM-judge in.
     module Assertions
-      # Named negative detectors for `must_not` now live in the runtime (D4). Kept as
+      # Named negative detectors for `must_not` now live in the runtime. Kept as
       # an alias so any external reference to Evals::Assertions::PII_DETECTORS still
       # resolves; the values ARE the runtime's, never a fork.
       PII_DETECTORS = Insika::Safety::Detectors::PII
 
-      # HOW MUCH THE AGENT SHOULD ASK BEFORE ACTING (RFC-0014 §3.3). Declared per
+      # HOW MUCH THE AGENT SHOULD ASK BEFORE ACTING. Declared per
       # case because it is a per-STORE decision, not a universal rule: sometimes the
       # agent should establish the objective before searching ("energia, treino ou
-      # sono?" — Ocean Drop does this well), and sometimes asking again is the
+      # sono?" — a good store agent does this well), and sometimes asking again is the
       # failure and it should just search. A global assertion would be wrong half
       # the time; the judge is TOLD the policy (Judge#build_prompt) and this layer
       # checks the half that needs no reader.
       #
-      # Each rule is stated as the CUSTOMER-VISIBLE fact it checks. RFC-0014 phrased
-      # this as "questions before the first tool call", written before P19: text a
+      # Each rule is stated as the CUSTOMER-VISIBLE fact it checks. phrased
+      # this as "questions before the first tool call", written before: text a
       # model emits before calling a tool never reaches the customer now (it rides
       # `:intermediate`), and the eval is a client of `/v1/responses`, so what it can
       # observe per turn is the published answer plus the tools that turn called.
@@ -87,7 +87,7 @@ module Insika
 
       module_function
 
-      # WHAT THIS DEPLOYMENT LACKS for the case to be worth running (RFC-0014 §3.2).
+      # WHAT THIS DEPLOYMENT LACKS for the case to be worth running.
       # -> [reason]; empty = run it.
       #
       # `available` is the deployment's answer for this agent:
@@ -237,7 +237,7 @@ module Insika
 
       # Runs a named detector over the text. "pii_leak" = union of all PII detectors;
       # otherwise a single named pattern. Delegates to the runtime's single source
-      # (D4) — which itself fails loud on an unknown name (a typo'd assertion must not
+      # which itself fails loud on an unknown name (a typo'd assertion must not
       # silently pass).
       def detect(name, text)
         Insika::Safety::Detectors.detect(name, text)

data/lib/insika/evals/baseline.rb

@@ -4,7 +4,7 @@ require "json"
 
 module Insika
   module Evals
-    # Fase C gating (RFC-0008 §3.4). A baseline is the accepted state of the golden
+    # gating. A baseline is the accepted state of the golden
     # set — `{ cases: { id => { pass, score } } }`. A gated run compares against it and
     # blocks only on a REGRESSION, so known-failing cases don't wedge the gate while a
     # real drop (a passing case that now fails, or a judge score that fell past the
@@ -16,7 +16,7 @@ module Insika
 
       # [CaseResult] -> baseline hash. `at` is stamped by the caller (kept out of here
       # so the module stays deterministic/testable).
-      # A SKIPPED case is left out entirely (RFC-0014 §3.2): writing it as `pass:
+      # A SKIPPED case is left out entirely: writing it as `pass:
       # false` would accept "this deployment cannot run it" as the accepted state,
       # and the case would never block anywhere again.
       def snapshot(results, at:)
@@ -38,7 +38,7 @@ module Insika
       # in BOTH are compared: a new case (no baseline entry) never blocks the gate (it
       # shows in the report as ❌ but is not a "regression"); document this in README.
       #   • pass→fail   : baseline pass, now failing (hard regression).
-      #   • pass→skipped: baseline pass, now unrunnable HERE. RFC-0014 §3.2 says the
+      #   • pass→skipped: baseline pass, now unrunnable HERE. says the
       #                   gate never blocks ON a skip, and it does not: a case that was
       #                   already skipped or unknown stays silent. But a case that used
       #                   to run on this deployment and no longer can means the agent