insika 0.0.1 → 0.2.0

data/lib/insika/budget_ledger.rb

@@ -0,0 +1,135 @@
+# frozen_string_literal: true
+
+module Insika
+  # Fixed-window spend counters for BUDGETS (WS2): the accounting layer the
+  # edge middleware rolls against. One scope, cells keyed
+  # "tenant:agent:window:calendar-bucket":
+  #
+  #   · DAILY    — the UTC calendar day (epoch/86400 IS midnight-aligned).
+  #   · MONTHLY  — (year * 12 + month) of the UTC calendar month: a budget month
+  #                is the CALENDAR month, however many days long it is (a fixed
+  #                N-day window drifts its bucket start across month lengths).
+  #                UTC like the daily, so both rollovers agree on any host.
+  #
+  # Built on the UsageLedger vocabulary (tenant/agent instead of kind/id) but
+  # on the store directly, with the increment riding `@store.transaction` — the
+  # exact read-modify-write discipline WS2's enforcement will build on. Two
+  # processes (or two SQLite handles) racing the same cell serialize on
+  # BEGIN IMMEDIATE: no lost update. No enforcement here — the middleware is
+  # WS2; this file is only correct accounting.
+  #
+  # Growth is bounded like UsageLedger: each `add` deletes the (id)'s previous
+  # day AND previous month cell, so an active scope holds at most 4 keys and an
+  # idle one converges to 2.
+  class BudgetLedger
+    SCOPE = "budget_counters"
+    ALERT_SCOPE = "budget_alerts"
+    DAY = 86_400
+
+    def initialize(store:)
+      @store = store
+    end
+
+    # Adds `by` across both windows; -> { daily:, monthly: } the NEW totals
+    # for (tenant, agent). Atomic per call: one transaction, both bumps.
+    def add(tenant:, agent:, by:, now: Time.now)
+      id = cell_id(tenant, agent)
+      @store.transaction do
+        daily = bump(id, daily_bucket(now), by)
+        monthly = bump(id, month_bucket(now), by)
+        @store.delete(SCOPE, key(id, daily_bucket(now - DAY)))   # previous day cell
+        @store.delete(SCOPE, key(id, month_bucket(now) - 1))     # previous calendar month cell
+        { daily: daily, monthly: monthly }
+      end
+    end
+
+    # -> { daily:, monthly: } current totals for (tenant, agent). Purely
+    # read; an expired window reads as 0 (rolls over at the boundary).
+    def current(tenant:, agent:, now: Time.now)
+      id = cell_id(tenant, agent)
+      { daily: @store.get(SCOPE, key(id, daily_bucket(now))).to_i,
+        monthly: @store.get(SCOPE, key(id, month_bucket(now))).to_i }
+    end
+
+    # Seconds until the window's bucket rolls over (the retry_after the
+    # enforcement quotes when a hard budget refuses a turn). Both windows are
+    # UTC-aligned (the daily via the epoch, the monthly via UTC components) so a
+    # non-UTC host never quotes a negative or local-midnight reset.
+    def reset_in(window, now: Time.now)
+      case window
+      when :daily then DAY - (now.to_i % DAY)
+      when :monthly then (next_utc_month_start(now) - now).to_i
+      end
+    end
+
+    # "1× per window" alert markers (the soft enforcement's event): a flag per
+    # (id, window, level, bucket) so a budget that stays over the threshold
+    # cannot spam one event per turn. `level:` separates DISTINCT triggers in
+    # the same window (WS2): the `alert_at` crossing and the real soft-cap
+    # crossing each warn once — the cap event must not be swallowed by the
+    # 80% marker having fired earlier. Marked/read in the same transaction
+    # discipline. -> bool: had the window already been marked?
+    def mark_alert(tenant:, agent:, window:, level: nil, now: Time.now)
+      id = cell_id(tenant, agent)
+      flag = alert_key(id, window, now, level)
+      @store.transaction do
+        # `next`, NOT `return`: a non-local return from inside the block skips
+        # the store's COMMIT and leaks the BEGIN IMMEDIATE open — the 2nd turn
+        # over a threshold then locks the whole backend (WS2).
+        next true unless @store.get(ALERT_SCOPE, flag).nil?
+
+        @store.set(ALERT_SCOPE, flag, 1)
+        false
+      end
+    end
+
+    def alerted?(tenant:, agent:, window:, level: nil, now: Time.now)
+      !@store.get(ALERT_SCOPE, alert_key(cell_id(tenant, agent), window, now, level)).nil?
+    end
+
+    private
+
+    # No tenant (single_tenant default) is a LITERAL "platform" cell, never a
+    # null-key collision with some other scope.
+    def cell_id(tenant, agent)
+      [tenant || "platform", agent].join(":")
+    end
+
+    def bump(id, bucket, by)
+      total = @store.get(SCOPE, key(id, bucket)).to_i + by
+      @store.set(SCOPE, key(id, bucket), total)
+      total
+    end
+
+    # the UTC calendar day's start (epoch is aligned to midnight UTC).
+    def daily_bucket(now)
+      (now.to_i / DAY) * DAY
+    end
+
+    # the UTC calendar month as one integer (2026-08 -> 24296). UTC, not local:
+    # the month boundary must agree with the daily epoch-day boundary on a
+    # non-UTC host (WS2), or the cap resets at a different moment than the day.
+    def month_bucket(now)
+      u = now.utc
+      u.year * 12 + u.month
+    end
+
+    # Midnight UTC of the 1st of the window's NEXT month — December-safe
+    # (Time.utc(y, 13, 1) raises; y+1/1 is the calendar answer).
+    def next_utc_month_start(now)
+      u = now.utc
+      u.month == 12 ? Time.utc(u.year + 1, 1, 1) : Time.utc(u.year, u.month + 1, 1)
+    end
+
+    def key(id, bucket)
+      "#{id}:#{bucket}"
+    end
+
+    # One alert flag per (id, window, level, calendar bucket): daily cells are
+    # keyed by day, monthly by (year*12+month) — a flag dies with its window.
+    def alert_key(id, window, now, level = nil)
+      bucket = window == :monthly ? month_bucket(now) : daily_bucket(now)
+      level ? "#{id}:#{window}:#{level}:#{bucket}" : "#{id}:#{window}:#{bucket}"
+    end
+  end
+end

data/lib/insika/capability/resolved_tool.rb

@@ -0,0 +1,34 @@
+# frozen_string_literal: true
+
+require "delegate"
+
+module Insika
+  module Capability
+    # Thin decorator: swaps only the `name` exposed to the model for the
+    # STABLE capability name (e.g. "browse"), regardless of which concrete impl
+    # (`impl_name`, e.g. "puppeteer_browser") resolution chose.
+    # `execute`/`parameters`/`description`/`call` keep delegating to the impl via
+    # SimpleDelegator — nothing reimplemented, same spirit as `ToolEnvelope`.
+    #
+    # Wrapping order in run_pipeline: impl -> ResolvedTool ->
+    # ToolEnvelope. The Envelope, from the outside, sees the already-renamed call (the
+    # model calls `browse`); for side_effect?/approval it needs the REAL `impl_name`
+    # (it's the tool_registry that knows whether "puppeteer_browser" is a side-effect, not
+    # "browse") — that's why `impl_name` is exposed here. This is consumed by the
+    # Executor (ToolEnvelope).
+    class ResolvedTool < SimpleDelegator
+      def initialize(impl, capability_name:, impl_name:)
+        super(impl)
+        @capability_name = capability_name.to_s
+        @impl_name = impl_name.to_s
+      end
+
+      # STABLE name exposed to the model — shadows the impl's `name`.
+      def name = @capability_name
+
+      # Concrete name behind resolution — for side_effect?/approval in the
+      # ToolEnvelope, NEVER exposed to the model.
+      def impl_name = @impl_name
+    end
+  end
+end

data/lib/insika/capability_registry.rb

@@ -0,0 +1,112 @@
+# frozen_string_literal: true
+
+module Insika
+  # Intent→implementation resolution. Pure INDIRECTION: does NOT inherit
+  # from `Registry` (which holds executables) — it holds `Provider`s (resolution
+  # metadata) and returns the `impl_name` that ANOTHER registry instantiates.
+  # Immutable post-boot by construction (only boot/loader registers), like `Registry`.
+  class CapabilityRegistry
+    Provider = Data.define(:capability, :impl_name, :kind, :plugin, :priority, :available)
+    #   kind:      :tool | :workflow
+    #   priority:  Integer | nil (nil = lowest; inherits plugin precedence)
+    #   available: callable -> bool (default -> { true }; never nil in a registered Provider)
+
+    def initialize
+      # capability(Symbol) -> [Provider], na ordem de registro (proxy de announce)
+      @providers = Hash.new { |h, k| h[k] = [] }
+    end
+
+    # Unlike `Registry#register`, there is NO "first wins": registering the
+    # same capability more than once is the normal case (providers competing) —
+    # dedup/tie-breaking happens in `resolve`, not here.
+    def register(capability, impl_name:, kind:, plugin: nil, priority: nil, available: nil)
+      unless %i[tool workflow].include?(kind)
+        raise ArgumentError, "invalid kind: #{kind.inspect} (use :tool or :workflow)"
+      end
+
+      if kind == :workflow
+        warn "[capability_registry] '#{capability}' registered with kind: :workflow — " \
+             "exposure to the agent deferred (L5)"
+      end
+
+      @providers[capability.to_sym] << Provider.new(
+        capability: capability.to_sym, impl_name: impl_name.to_s, kind: kind,
+        plugin: plugin&.to_s, priority: priority, available: available || -> { true }
+      )
+      self
+    end
+
+    def providers(capability) = @providers[capability.to_sym].dup
+
+    def capabilities = @providers.keys
+
+    # Loader rollback, symmetric to `Registry#deregister_plugin`. Removes
+    # only the plugin's Providers; capabilities with no remaining provider drop
+    # from `capabilities` (clears the key so the Hash.new-with-block won't recreate it empty).
+    def deregister_plugin(plugin_id)
+      @providers.each_value { |list| list.delete_if { |p| p.plugin == plugin_id.to_s } }
+      @providers.delete_if { |_cap, list| list.empty? }
+      nil
+    end
+
+    # -> chosen Provider | raise CapabilityUnavailable | raise CapabilityAmbiguous.
+    # PURE and deterministic: same input → same choice or same error. No
+    # IO beyond the Provider's own `available.call`. Emits `:capability_resolved`
+    # when `event_stream:` is present (audit).
+    def resolve(capability, profile:, context: {}, event_stream: nil)
+      candidates = providers(capability)
+      candidates = candidates.select { |p| p.available.call }
+      candidates = apply_deny(candidates, profile)
+
+      raise CapabilityUnavailable.new(capability: capability) if candidates.empty?
+
+      chosen = pick_top(candidates, capability)
+      event_stream&.emit(Insika::Event.new(
+                           type: :capability_resolved,
+                           data: {
+                             capability: capability.to_sym,
+                             chosen: chosen.impl_name,
+                             candidates: candidates.map do |p|
+                               { impl_name: p.impl_name, plugin: p.plugin, priority: p.priority }
+                             end
+                           }
+                         ))
+      chosen
+    end
+
+    private
+
+    # Resolution applies ONLY `tools_deny` over `impl_name` (deny ALWAYS wins) — it does
+    # NOT apply `tools_allow`: the grant to use the capability is
+    # listing it in `profile.capabilities`, checked by the Executor BEFORE
+    # calling `resolve`. Reusing `tools_allow` would filter out a provider for
+    # an agent that lists only the capability (not the raw impl). Per-agent provider
+    # pinning (`capability_providers`) is future work.
+    def apply_deny(candidates, profile)
+      deny = Array(profile.tools_deny).map(&:to_s)
+      candidates.reject { |p| deny.include?(p.impl_name) }
+    end
+
+    # `priority` desc primary, `nil` as the LOWEST possible (below
+    # any Integer, including negative — do not normalize to 0, which would collide
+    # with an explicit `priority: 0`). Tie-break by plugin precedence (registration
+    # order, announce proxy): different plugins always
+    # break the tie; same plugin (nil included) tied = CapabilityAmbiguous.
+    def pick_top(candidates, capability)
+      indexed = providers(capability).each_with_index.to_h { |p, i| [p, i] }
+
+      rank = ->(p) { p.priority.nil? ? [0, 0] : [1, p.priority] }
+      top_rank = candidates.map(&rank).max
+      top = candidates.select { |p| rank.call(p) == top_rank }
+
+      return top.first if top.size == 1
+
+      groups = top.group_by(&:plugin).values
+      if groups.any? { |g| g.size > 1 }
+        raise CapabilityAmbiguous.new(capability: capability, candidates: top)
+      end
+
+      groups.min_by { |g| indexed[g.first] }.first
+    end
+  end
+end

data/lib/insika/channel_delivery.rb

@@ -0,0 +1,153 @@
+# frozen_string_literal: true
+
+require "time"
+
+module Insika
+  # Hands a finished turn's answer to a Shape B channel. The turn
+  # ended; the recipient is not on any connection; the reply has to travel out of
+  # band and survive a crash on the way. Three moves, in this order, and the order
+  # is the whole design:
+  #
+  #   1. RECORD at the turn's terminal (durable, `pending`).
+  #   2. CLAIM before the HTTP call (`pending -> delivering`, atomic). A crash
+  #      between the claim and the POST loses that delivery; it does not duplicate
+  #      it. At-most-once, stated rather than papered over — the same honest scope
+  #      the async-delegation path already has.
+  #   3. RETRY, bounded and explicit. Unlike a delegation, the recipient is a third
+  #      party with outages, so "keep trying" is a real requirement and "keep trying
+  #      forever" is a real outage of ours.
+  #
+  # It is NOT a job queue: no scheduler, no priorities, no fan-out. The moment it
+  # grows one, the thing to do is take a real queue, not to finish building this.
+  class ChannelDelivery
+    MAX_ATTEMPTS = 3
+    # Waits BETWEEN attempts, so attempt 1 is immediate. Short on purpose: a
+    # customer waiting on WhatsApp is the deadline, not the consumer's SLA.
+    BACKOFF_SECONDS = [1, 5].freeze
+
+    def initialize(channels:, outbox:, session_store:, event_stream: nil,
+                   max_attempts: MAX_ATTEMPTS, backoff: BACKOFF_SECONDS, sleeper: nil)
+      @channels = channels
+      @outbox = outbox
+      @session_store = session_store
+      @event_stream = event_stream
+      @max_attempts = max_attempts
+      @backoff = Array(backoff)
+      @sleeper = sleeper || method(:default_sleep)
+    end
+
+    # The turn committed an answer. -> the Delivery to dispatch, or nil when there
+    # is nothing to deliver, which is the common case and must stay cheap:
+    #   · the turn did not come in through a channel,
+    #   · the channel is Shape A (answers on its own stream — no `deliver`),
+    #   · the answer is empty (a turn that died mid-message published nothing, and
+    #     half a sentence was never an answer),
+    #   · or we do not know who to send it to.
+    def record(task:, channel_id:, content:)
+      return nil if content.to_s.strip.empty?
+
+      channel = @channels&.find(channel_id)
+      return nil unless channel.respond_to?(:deliver)
+
+      to = recipient(channel, task.session_id)
+      return nil if to.nil? || to.empty?
+
+      @outbox.create(
+        channel: channel_id, to: to, task_id: task.id, session_id: task.session_id,
+        payload: { "session_id" => task.session_id.to_s, "task_id" => task.id.to_s,
+                   "content" => content.to_s }
+      )
+    end
+
+    # Claim + POST + bounded retry. Safe to call twice: the second caller loses the
+    # claim and returns without touching the recipient.
+    def deliver(id)
+      return false unless @outbox.claim(id)
+
+      delivery = @outbox.find(id)
+      channel = @channels&.find(delivery&.channel)
+      # The channel vanished between the record and the dispatch (a plugin was
+      # disabled, the deployment was reconfigured). Nothing can send this; leave it
+      # terminal so the boot sweep does not spin on it forever.
+      if channel.nil? || !channel.respond_to?(:deliver)
+        return finish(@outbox.mark_failed(id, error: "channel '#{delivery&.channel}' is not registered"))
+      end
+
+      attempt(delivery, channel)
+    end
+
+    # Boot: re-drive what a previous process recorded and never claimed. Records
+    # left `delivering` are deliberately NOT swept — that process may have POSTed
+    # before it died, and replaying is the duplicate the claim exists to prevent.
+    # -> { dispatched: [ids] }
+    def sweep
+      dispatched = @outbox.pending.map do |delivery|
+        deliver(delivery.id)
+        delivery.id
+      end
+      { dispatched: dispatched }
+    end
+
+    private
+
+    def attempt(delivery, channel)
+      last_error = nil
+
+      @max_attempts.times do |i|
+        @sleeper.call(@backoff[i - 1]) if i.positive? && @backoff[i - 1]
+
+        begin
+          status = channel.deliver(delivery.payload, to: delivery.to, delivery_id: delivery.id)
+          return finish(@outbox.mark_delivered(delivery.id)) if (200..299).cover?(status.to_i)
+
+          last_error = "HTTP #{status}"
+        rescue Insika::DeliveryError => e
+          last_error = e.message
+        end
+        @outbox.record_attempt(delivery.id, error: last_error)
+      end
+
+      finish(@outbox.mark_failed(delivery.id, error: last_error))
+    end
+
+    # The consumer's own key for this conversation. Written into the session's vars
+    # when the channel minted it; the channel's own id parser is the fallback
+    # for a session created before those vars existed.
+    def recipient(channel, session_id)
+      session = session_id && @session_store.find(session_id)
+      vars = session&.vars || {}
+      from_vars = vars["external_id"] || vars[:external_id]
+      return from_vars.to_s if Insika::Coercion.presence(from_vars)
+
+      channel.respond_to?(:external_id_from) ? channel.external_id_from(session_id) : nil
+    end
+
+    def finish(delivery)
+      emit(delivery)
+      delivery.status == :delivered
+    end
+
+    def emit(delivery)
+      return unless @event_stream
+
+      data = { channel: delivery.channel, outbox_id: delivery.id,
+               status: delivery.status.to_s, attempts: delivery.attempts,
+               error: delivery.last_error }
+      meta = { task_id: delivery.task_id, session_id: delivery.session_id,
+               at: Time.now.utc.iso8601 }
+      # :delivery_failed is the ALERT face of a failed delivery (WS6) — emitted
+      # alongside :channel_delivered so the delivery audit stream is unchanged.
+      @event_stream.emit(Insika::Event.new(type: :channel_delivered, data: data, meta: meta))
+      if delivery.status == :failed
+        @event_stream.emit(Insika::Event.new(type: :delivery_failed, data: data, meta: meta))
+      end
+    end
+
+    # Async when there is a reactor (production: the retry must not block the
+    # worker), plain sleep otherwise (boot sweep before the reactor, specs).
+    def default_sleep(seconds)
+      task = defined?(Async::Task) ? Async::Task.current? : nil
+      task ? task.sleep(seconds) : sleep(seconds)
+    end
+  end
+end

data/lib/insika/channel_registry.rb

@@ -0,0 +1,30 @@
+# frozen_string_literal: true
+
+module Insika
+  # The channels this deployment speaks, by id. A `Registry` like
+  # tools and workflows — same plugin bookkeeping, so `deregister_plugin` rolls a
+  # half-registered plugin back exactly as it does for a tool.
+  #
+  # The id is the URL segment (`/channels/relay/events`), which is why lookup here
+  # is a `find` and not a `resolve`: an unknown segment is a 404, not an exception
+  # the transport has to rescue.
+  class ChannelRegistry < Registry
+    # -> the channel instance | nil (unknown id). A blank id never matches.
+    def find(id)
+      name = id.to_s
+      return nil if name.empty?
+
+      resolve(name)
+    rescue Insika::NotFoundError
+      nil
+    end
+
+    # Does this channel deliver out of band (Shape B)? A Shape A channel answers on
+    # the request's own stream and has no `deliver`, so nothing is ever written to
+    # the outbox for it. Duck-typed, like every other seam in the engine.
+    def deliverable?(id)
+      channel = find(id)
+      !channel.nil? && channel.respond_to?(:deliver)
+    end
+  end
+end

data/lib/insika/channels/relay.rb

@@ -0,0 +1,178 @@
+# frozen_string_literal: true
+
+require "digest"
+require "json"
+require "openssl"
+require "uri"
+
+module Insika
+  module Channels
+    # The channel for an adopter who ALREADY owns a messaging integration
+    # A WhatsApp BSP, a Zendesk, a legacy Rails app: they want the
+    # engine for the TURN, not for the platform. Two routes and an envelope —
+    #
+    #   consumer --POST /channels/relay/events--> engine   acked now, never the reply
+    #   consumer <--POST <deliver_url>---------- engine    the reply, when there is one
+    #
+    # — and everything platform-shaped stays theirs: the 24-hour window, template
+    # approval, media, read receipts, and how markdown becomes WhatsApp formatting
+    # That is the promise, not the limitation: an integration someone has
+    # already tuned for years does not have to move for them to adopt the engine.
+    # A relay that starts growing template logic has stopped being a relay.
+    #
+    # It is also the cheapest possible Shape B, which is why it is built first:
+    # both ends are ours, so there is no third-party signature scheme and no
+    # rendering to get wrong at the same time as the durability. What it DOES
+    # exercise — the outbox, the claim, bounded retry, inbound dedup — is what
+    # Slack and native WhatsApp inherit untouched.
+    #
+    # R1/R2 hold: this object translates and authenticates, and does nothing else.
+    # No Executor, no store, no RubyLLM; it may refuse a request, never grant a
+    # capability.
+    class Relay
+      DEFAULT_ID = "relay"
+      DEFAULT_TIMEOUT = 10
+
+      attr_reader :id
+
+      # The bundled relay as an operator configures it: three env vars, of which the
+      # token is the SWITCH — no token, no channel, so there is no way to end up with
+      # this route mounted and open. -> Relay | nil.
+      #
+      # Shared by every composition root on purpose: the DSL front door has to reach
+      # the same feature as `config.ru`, or the docs are true of only one of them.
+      def self.from_env(env = ENV, http: nil, allow_http: false, allow_private: false)
+        token = Insika::EnvSchema.read("INSIKA_RELAY_TOKEN", env)
+        return nil unless Insika::EnvSchema.present?(token)
+
+        new(inbound_token: token,
+            deliver_url: Insika::EnvSchema.read("INSIKA_RELAY_DELIVER_URL", env),
+            deliver_token: Insika::EnvSchema.read("INSIKA_RELAY_DELIVER_TOKEN", env),
+            http: http, allow_http: allow_http, allow_private: allow_private)
+      end
+
+      # inbound_token:  shared secret the consumer sends us (Bearer). Blank ->
+      #                 the channel answers :disabled to every request, fail-closed
+      #                 by construction rather than open by omission.
+      # deliver_url:    where the reply goes. Blank -> nothing is ever delivered
+      #                 (the channel still accepts inbound; the outbox records the
+      #                 reply and the delivery fails loudly instead of silently).
+      # deliver_token:  Bearer we send THEM. Optional: a consumer on a private
+      #                 network may authenticate us another way.
+      def initialize(inbound_token:, deliver_url:, deliver_token: nil, http: nil,
+                     id: DEFAULT_ID, allow_http: false, allow_private: false,
+                     timeout: DEFAULT_TIMEOUT)
+        @id = id.to_s
+        @inbound_token = inbound_token.to_s
+        @deliver_url = deliver_url.to_s
+        @deliver_token = deliver_token.to_s
+        @http = http || Insika::HttpClient.new
+        @allow_http = allow_http
+        @allow_private = allow_private
+        @timeout = timeout
+      end
+
+      # -> :ok | :unauthorized | :disabled. A SYMBOL and not a Rack triple (the
+      # RFC sketched one): a status code is the transport's vocabulary, and keeping
+      # it out of here is what lets this class be tested without Rack and read
+      # without knowing HTTP.
+      def authenticate(req)
+        return :disabled if @inbound_token.empty?
+
+        provided = req.get_header("HTTP_AUTHORIZATION").to_s[/\ABearer (.+)\z/, 1]
+        return :unauthorized if provided.nil?
+
+        secure_compare(@inbound_token, provided) ? :ok : :unauthorized
+      end
+
+      # Inbound envelope -> the fields the mount turns into a `:send_message`.
+      # STRING keys in, because the consumer's `vars` are arbitrary data keys.
+      #
+      #   { "agent": "support", "external_id": "5511999998888",
+      #     "event_id": "wamid.HBg…", "message": "queria saber do pedido",
+      #     "vars": { … } }
+      def parse(_req, body:)
+        body = body.is_a?(Hash) ? body : {}
+        agent = string(body["agent"])
+        external_id = string(body["external_id"])
+        message = string(body["message"])
+
+        raise Insika::ValidationError, "agent is required" if agent.empty?
+        raise Insika::ValidationError, "external_id is required" if external_id.empty?
+        raise Insika::ValidationError, "message is required" if message.strip.empty?
+
+        vars = body["vars"].is_a?(Hash) ? body["vars"] : {}
+        { agent: agent, external_id: external_id, message: message,
+          event_id: presence(body["event_id"]), vars: vars }
+      end
+
+      # the engine namespaces the platform's conversation key, so a
+      # Slack channel id and a phone number can never collide, an operator can see
+      # where a conversation came from, and an id minted for one channel cannot be
+      # used to read another's session.
+      def session_id_for(external_id) = "#{@id}:#{external_id}"
+
+      # The reverse: what the consumer called this conversation. Reads off the
+      # session id so a delivery needs no extra state.
+      def external_id_from(session_id)
+        s = session_id.to_s
+        s.start_with?("#{@id}:") ? s.delete_prefix("#{@id}:") : nil
+      end
+
+      # Hands ONE reply to the consumer's callback. -> the HTTP status (the
+      # dispatcher decides what 2xx means); raises DeliveryError when the request
+      # could not be made at all.
+      #
+      # `X-Insika-Delivery` is the outbox id: a stable idempotency key, so a
+      # consumer that receives the same delivery twice (we retried after a timeout
+      # that actually landed) can drop the second one.
+      def deliver(payload, to:, delivery_id: nil)
+        raise Insika::DeliveryError, "relay deliver_url is not configured" if @deliver_url.empty?
+
+        if (reason = egress_violation)
+          raise Insika::DeliveryError, "egress blocked for deliver_url: #{reason}"
+        end
+
+        response = @http.request(method: :post, url: @deliver_url, timeout: @timeout,
+                                 headers: headers(delivery_id),
+                                 body: JSON.generate(payload.merge("external_id" => to.to_s)))
+        response[:status].to_i
+      rescue Insika::DeliveryError
+        raise
+      rescue StandardError => e
+        raise Insika::DeliveryError, "#{e.class}: #{e.message}"
+      end
+
+      private
+
+      # Resolved on EVERY call, not once at boot: a hostname that answered a public
+      # address yesterday can answer 169.254.169.254 today, and this POST carries
+      # the customer's conversation.
+      def egress_violation
+        Insika::EgressGuard.violation(@deliver_url, allow_http: @allow_http,
+                                                    allow_private: @allow_private,
+                                                    host_allowlist: [URI.parse(@deliver_url).host].compact)
+      rescue URI::InvalidURIError
+        "invalid URL"
+      end
+
+      def headers(delivery_id)
+        h = { "content-type" => "application/json" }
+        h["authorization"] = "Bearer #{@deliver_token}" unless @deliver_token.empty?
+        h["x-insika-delivery"] = delivery_id.to_s if delivery_id
+        h
+      end
+
+      # Constant time, and length-safe: comparing the digests means an attacker
+      # learns nothing from how long the check took, not even the token's length.
+      # OpenSSL rather than Rack::Utils so the engine's lib/ keeps no web framework
+      # in its load path.
+      def secure_compare(a, b)
+        OpenSSL.fixed_length_secure_compare(Digest::SHA256.digest(a), Digest::SHA256.digest(b))
+      end
+
+      def string(value) = value.to_s
+      def presence(value) = Insika::Coercion.presence(value)
+    end
+  end
+end