insika 0.0.1 → 0.2.0

data/lib/insika/dsl.rb

@@ -0,0 +1,364 @@
+# frozen_string_literal: true
+
+require_relative "pack"
+
+module Insika
+  # Public Ruby DSL — the OSS "business card":
+  #
+  #   agent = Insika.agent("assistant") do
+  #     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). `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.
+  #
+  # Nothing here loads ruby_llm or the HTTP server: `require "insika"` stays light.
+  # The runtime (chat/serve) is pulled in lazily by Definition (dsl/runtime.rb).
+  module DSL
+    module_function
+
+    # Insika.agent("id") { … } → Definition (see #agent below on the module).
+    def agent(id, &block)
+      Builder.new(id).build(&block)
+    end
+
+    # Insika.system { agent("a") { … }; agent("b") { … } } → System.
+    def system(&block)
+      SystemBuilder.new.build(&block)
+    end
+
+    # Insika.embed(backend:) { … } → System (see #embed below on the module).
+    def embed(backend:, &block)
+      SystemBuilder.new.build(backend: backend, &block)
+    end
+
+    # Collects several agents into ONE runtime. A single agent is a Definition;
+    # more than one needs a container, because delegation (`subagents`) and any
+    # multi-agent pattern only mean something when the children live in the same
+    # graph. It adds no new engine path: each agent is still its own Pack,
+    # imported through the standard PackImporter.
+    class SystemBuilder
+      def initialize
+        @definitions = []
+        @workflows = []
+        @runtime = {}
+      end
+
+      def build(backend: nil, &block)
+        instance_eval(&block) if block
+        raise ArgumentError, "Insika.system needs at least one agent" if @definitions.empty?
+
+        System.new(definitions: @definitions, workflows: @workflows, runtime: @runtime, backend: backend)
+      end
+
+      # Declares one agent — the SAME block the standalone `Insika.agent` takes.
+      # Returns its Definition, so a script can keep a handle if it wants one.
+      def agent(id, &block)
+        definition = Builder.new(id).build(&block)
+        if @definitions.any? { |d| d.id == definition.id }
+          raise ArgumentError, "duplicate agent id in system: #{definition.id}"
+        end
+
+        @definitions << definition
+        definition
+      end
+
+      # Declares a WORKFLOW: deterministic Ruby orchestrating agent turns, for the
+      # shapes a single tool-loop should not decide on its own — chaining, routing,
+      # evaluate-and-retry. It is registered in the same WorkflowRegistry a
+      # deployment uses, so it gets a durable run (the run id IS a Task),
+      # `:workflow_started`/`:workflow_completed` on the event stream, and — when
+      # served — `GET /v1/workflows` + `POST /v1/workflows/:name`.
+      #
+      #   workflow "draft", input: { type: "object", required: ["topic"], … } do |input, ctx|
+      #     draft = ctx.ask("writer", "Write about #{input['topic']}")
+      #     ctx.ask("editor", "Tighten this:\n#{draft}")
+      #   end
+      #
+      # `input:`/`output:` take a JSON Schema Hash (validated by the engine's
+      # zero-dep validator) or any dry-schema-compatible `#call`-able. A bad input
+      # is refused synchronously, with NO run created.
+      def workflow(name, description: nil, input: nil, output: nil, &block)
+        raise ArgumentError, "workflow '#{name}' needs a block" if block.nil?
+
+        name = name.to_s
+        raise ArgumentError, "duplicate workflow in system: #{name}" if @workflows.any? { |w| w[:name] == name }
+
+        @workflows << { name: name, description: description,
+                        input_schema: input, output_schema: output, block: block }
+        name
+      end
+
+      # System-wide runtime knobs (NOT part of any pack): they configure the LLM
+      # clients for every agent. A per-agent `provider` still wins for that agent;
+      # this is the default and the place to put a shared key.
+      def provider(name) = @runtime[:provider] = name.to_s
+      def api_key(value) = @runtime[:api_key] = value.to_s
+      def api_base(value) = @runtime[:api_base] = value.to_s
+    end
+
+    # Collects the declarations and emits a Insika::Pack. Declarations map 1:1 to
+    # the pack manifest (AgentProfile.build attrs) + the pack's files/skills/tools —
+    # so what you write is exactly the data the engine stores.
+    class Builder
+      def initialize(id)
+        @id = id.to_s
+        @config = {}
+        @files = {}
+        @skills = {}
+        @tools = []
+        # Auto-enable the allowlist policies: harmless when the allowlist is nil=all,
+        # correct once you restrict tools/skills. Visible in #to_pack — no hidden magic.
+        @config[:policies] = %i[tool_allowlist skill_allowlist]
+        @runtime = {} # non-pack knobs (llm provider/key/base) consumed by the runtime
+      end
+
+      def build(&block)
+        instance_eval(&block) if block
+        Definition.new(pack: to_pack, runtime: @runtime)
+      end
+
+      # --- identity & model ------------------------------------------------
+      def model(name) = @config[:model] = name.to_s
+
+      # Provider for both the profile AND the RubyLLM configuration at run time.
+      def provider(name)
+        @config[:provider] = name.to_s
+        @runtime[:provider] ||= name.to_s
+      end
+
+      def instructions(text) = @config[:base_prompt] = text.to_s
+      alias_method :prompt, :instructions
+
+      # An extra prompt FILE (identity fragment). Name = the file name (e.g. "SOUL.md").
+      def prompt_file(name, content)
+        @files[name.to_s] = content.to_s
+      end
+
+      # --- tools -----------------------------------------------------------
+      # tools "a", "b"  → allowlist [names]. Not called → nil = all (parity).
+      def tools(*names)
+        @config[:tools_allow] = names.flatten.map(&:to_s)
+      end
+
+      def deny_tools(*names)
+        @config[:tools_deny] = names.flatten.map(&:to_s)
+      end
+
+      # 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.
+      def data_tool(defn)
+        h = defn.transform_keys(&:to_s)
+        @tools << h
+        name = h["name"].to_s
+        (@config[:tools_allow] ||= []) << name unless name.empty? || Array(@config[:tools_allow]).include?(name)
+        h
+      end
+
+      # --- skills ----------------------------------------------------------
+      # skill "escalate", "<full SKILL.md>"  — or —
+      # skill "escalate", description: "…", instructions: "…"
+      # The name is auto-added to the agent's skill allowlist.
+      def skill(name, content = nil, description: nil, instructions: nil)
+        n = name.to_s
+        @skills[n] = normalize_skill(n, content, description, instructions)
+        (@config[:skills] ||= []) << n unless @config.fetch(:skills, []).include?(n)
+        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. 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)
+        @config[:subagents] = ids.flatten.map(&:to_s)
+      end
+
+      # --- knobs -----------------------------------------------------------
+      def memory(on = true) = @config[:memory] = on
+
+      # 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-v4-flash",
+      #              responses: { "injection" => "I can't help with that." }
+      def guardrails(hash) = (@config[:guardrails] ||= {}).merge!(hash.transform_keys(&:to_s))
+
+      # 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 (writes nothing).
+      #   refine mode: "propose", window: { last_sessions: 200 }, files: %w[TOOLS.md],
+      #          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, 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"
+      def declares(*names)
+        (@config[:capabilities_declared] ||= []).concat(names.flatten.map(&:to_s))
+      end
+
+      # Which internal channels may cross to the CUSTOMER. Both off by default: the
+      # answer is the answer, and the provider's reasoning (`thinking`) or the model
+      # narrating its tool loop (`intermediate`) is for the Studio and the trace.
+      # Each opted-in channel gets its OWN frame type at `/v1/responses` — never the
+      # answer's — so a consumer that only reads the answer is unaffected either way.
+      #   edge_stream thinking: true, intermediate: false
+      def edge_stream(hash) = (@config[:edge_stream] ||= {}).merge!(hash.transform_keys(&:to_s))
+
+      # 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)
+      def max_tokens(value) = param(:max_tokens, value)
+
+      # Per-agent limits (timeouts/budgets). `limit :turn_timeout, 120` or `limits(...)`.
+      def limit(key, value) = (@config[:limits] ||= {})[key.to_sym] = value
+      def limits(hash) = (@config[:limits] ||= {}).merge!(hash.transform_keys(&:to_sym))
+
+      def policies(*names) = @config[:policies] = names.flatten.map(&:to_sym)
+      def metadata(hash) = (@config[:metadata] ||= {}).merge!(hash.transform_keys(&:to_s))
+
+      # --- runtime (LLM provider) config — NOT part of the pack ------------
+      # Configures RubyLLM at chat/serve time. Defaults: provider = the agent's
+      # provider; key = ENV["<PROVIDER>_API_KEY"].
+      def api_key(value) = @runtime[:api_key] = value.to_s
+      def api_base(value) = @runtime[:api_base] = value.to_s
+
+      # The generated portable artifact — the heart of "generates the data".
+      def to_pack
+        Insika::Pack.from_h(
+          config: @config.merge(id: @id),
+          files: @files, skills: @skills, tools: @tools
+        )
+      end
+
+      private
+
+      # Ensure the skill body is a valid SKILL.md (YAML frontmatter with `name`),
+      # which is what SkillCatalog parses. Raw content with frontmatter passes
+      # through untouched; a bare body / structured args get wrapped.
+      def normalize_skill(name, content, description, instructions)
+        return content.to_s if content.is_a?(String) && content.lstrip.start_with?("---")
+
+        body = (instructions || content).to_s
+        desc = (description || first_line(body) || name).to_s
+        <<~SKILL
+          ---
+          name: #{name}
+          description: #{desc}
+          ---
+
+          #{body}
+        SKILL
+      end
+
+      def first_line(text) = text.to_s.strip.lines.first&.strip
+    end
+  end
+
+  module_function
+
+  # Top-level entry point (see Insika::DSL). Returns a Insika::DSL::Definition.
+  def agent(id, &block)
+    DSL.agent(id, &block)
+  end
+
+  # Several agents in one runtime — the shape every multi-agent pattern needs
+  # (delegation, fan-out/fan-in, routing). Returns a Insika::DSL::System.
+  def system(&block)
+    DSL.system(&block)
+  end
+
+  # 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-v4-flash"
+  #       instructions "…"
+  #     end
+  #   end
+  #   # config/routes.rb — mount the /v1 transport as a value:
+  #   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, 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)
+  end
+end
+
+require_relative "dsl/definition"
+require_relative "dsl/system"

data/lib/insika/edge_limiter.rb

@@ -0,0 +1,268 @@
+# frozen_string_literal: true
+
+require_relative "middleware"
+require_relative "coercion"
+
+module Insika
+  # 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):
+  #
+  #   · chat rate limit    — turn ATTEMPTS per chat per window. Counted on entry
+  #     (a blocked attempt still counts), so a flood keeps hitting the wall.
+  #   · 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: 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"
+
+    DEFAULT_CHAT_WINDOW   = 60      # seconds
+    DEFAULT_TOKEN_WINDOW  = 86_400  # seconds (daily ceiling)
+
+    # Neutral fallback, same contract as Safety::SafeResponses (pt-BR — the
+    # pilot's language; override via settings edge.limit_response).
+    DEFAULT_RESPONSE = "Estou recebendo muitas mensagens agora. Aguarde um " \
+                       "momento e tente novamente, por favor."
+
+    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)
+      edge = platform_edge
+      limits = state.profile.limits || {}
+      # A resume (crash/pause recovery) re-enters the pipeline for a turn that was
+      # ALREADY admitted: re-counting it would swallow a legitimate message with
+      # the rate-limit reply exactly when the window is saturated. Entry checks
+      # are skipped; the turn's usage still lands on the ledger below.
+      resumed = state.resumed
+
+      if !resumed && (limit = positive(limits.key?(:chat_rate_limit) ? limits[:chat_rate_limit] : edge["chat_rate_limit"]))
+        breach = check_chat_rate(state, limit, edge)
+        return block(state, edge, **breach) if breach
+      end
+
+      # NB: a per-agent key PRESENT with nil (e.g. an imported pack carrying
+      # `"chat_rate_limit": null`) reads as OFF for that agent, not "inherit".
+      if (ceiling = positive(limits.key?(:agent_token_ceiling) ? limits[:agent_token_ceiling] : edge["agent_token_ceiling"]))
+        token_window = positive(edge["agent_token_window"]) || DEFAULT_TOKEN_WINDOW
+        unless resumed
+          spent = @ledger.count(TOKENS_KIND, state.profile.id.to_s, window: token_window)
+          if spent >= ceiling
+            return block(state, edge, category: :token_ceiling,
+                                      detail: "agent #{state.profile.id}: #{spent}/#{ceiling} tokens per #{token_window}s")
+          end
+        end
+
+        record_after = token_window
+      end
+
+      # 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
+
+    private
+
+    # One KV get per turn (same order of cost as the guardrail's config read);
+    # no SettingsStore in the wiring -> per-agent limits only.
+    def platform_edge
+      (@settings&.get || {})["edge"] || {}
+    end
+
+    # Counts the ATTEMPT first, then compares — the standard fixed-window
+    # semantics (blocked attempts keep counting). A blank chat id is skipped:
+    # unrelated anonymous traffic must not share one bucket.
+    def check_chat_rate(state, limit, edge)
+      chat_id = (state.turn_context || {})[:chat_id].to_s
+      return nil if chat_id.empty?
+
+      window = positive(edge["chat_rate_window"]) || DEFAULT_CHAT_WINDOW
+      taken = @ledger.add(CHAT_KIND, chat_id, window: window)
+      return nil if taken <= limit
+
+      { category: :rate_limit, detail: "chat #{chat_id}: #{taken}/#{limit} turns per #{window}s" }
+    end
+
+    # The turn's real spend, accumulated on the agent's ledger. The engine's
+    # `total_tokens` is input + output and DELIBERATELY excludes the cached
+    # 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. 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 || {}
+      tokens = usage[:total_tokens].to_i + usage[:cached_tokens].to_i +
+               usage[:cache_creation_tokens].to_i
+      return if tokens.zero?
+
+      @ledger.add(TOKENS_KIND, state.profile.id.to_s, window: window, by: tokens)
+    end
+
+    # Graceful halt: safe reply + audit metadata, short-circuit (no nxt).
+    # `detail` carries only ids/counters — never message content.
+    def block(state, edge, category:, detail:)
+      state.halt_response = Coercion.presence(edge["limit_response"]) || DEFAULT_RESPONSE
+      state.guardrail_block = {
+        category: category.to_s, source: "edge", action: "refuse", detail: detail
+      }
+      nil
+    end
+
+    def positive(value)
+      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