insika 0.0.1 → 0.2.0

data/lib/insika/channels/web/widget.js

@@ -0,0 +1,283 @@
+// Insika web widget.
+//
+// One <script> tag, no framework, no build step, no dependency:
+//
+//   <script src="https://agents.example.com/channels/web/asset/widget.js"
+//           data-agent="support" data-title="Ask us anything" defer></script>
+//
+// Everything it needs it reads off its own tag: the agent, the chrome text, and
+// the engine's base URL (derived from this file's own src, so an adopter never
+// configures a host twice). Theming is a block of CSS custom properties — set
+// them on :root and they win, because they are declared on the widget root with
+// var(..., fallback).
+//
+// The one design decision worth stating: a message POST is NEVER retried. It is
+// the request that runs a turn, so re-sending it costs a second LLM call and can
+// put a second answer in front of the customer. A dropped stream shows what
+// arrived plus a failure note, and the person decides whether to ask again. The
+// backoff below is for minting a session — the only call here that is safe to
+// repeat.
+(function () {
+  "use strict";
+
+  var script = document.currentScript;
+  if (!script) return;
+
+  var base = new URL(script.src, window.location.href).href.replace(/\/channels\/[^/]+\/asset\/[^/]*$/, "");
+  var channel = (script.src.match(/\/channels\/([^/]+)\/asset\//) || [])[1] || "web";
+  var agent = script.dataset.agent || "";
+  var title = script.dataset.title || "Chat";
+  var placeholder = script.dataset.placeholder || "Type a message…";
+  var greeting = script.dataset.greeting || "";
+  var storageKey = "insika:" + channel + ":" + agent + ":session";
+
+  if (!agent) {
+    console.error("[insika] the widget needs data-agent on its <script> tag");
+    return;
+  }
+
+  // --- chrome ---------------------------------------------------------
+
+  var CSS = [
+    ".insika-w{position:fixed;right:var(--insika-offset,20px);bottom:var(--insika-offset,20px);z-index:2147483000;",
+    "font-family:var(--insika-font,system-ui,-apple-system,Segoe UI,Roboto,sans-serif);font-size:15px;line-height:1.5}",
+    ".insika-b{width:56px;height:56px;border-radius:50%;border:0;cursor:pointer;display:block;margin-left:auto;",
+    "background:var(--insika-accent,#1f2937);color:var(--insika-on-accent,#fff);font-size:24px;",
+    "box-shadow:0 6px 24px rgba(0,0,0,.22)}",
+    ".insika-p{display:none;flex-direction:column;width:min(380px,calc(100vw - 40px));height:min(560px,calc(100vh - 120px));",
+    "margin-bottom:12px;border-radius:14px;overflow:hidden;background:var(--insika-bg,#fff);color:var(--insika-fg,#111827);",
+    "border:1px solid var(--insika-border,rgba(0,0,0,.12));box-shadow:0 12px 48px rgba(0,0,0,.24)}",
+    ".insika-w.open .insika-p{display:flex}",
+    ".insika-h{padding:12px 14px;font-weight:600;background:var(--insika-accent,#1f2937);color:var(--insika-on-accent,#fff);",
+    "display:flex;align-items:center;justify-content:space-between}",
+    ".insika-x{background:none;border:0;color:inherit;font-size:20px;cursor:pointer;line-height:1;padding:0 2px}",
+    ".insika-log{flex:1;overflow-y:auto;padding:14px;display:flex;flex-direction:column;gap:10px}",
+    ".insika-m{max-width:85%;padding:9px 12px;border-radius:12px;white-space:pre-wrap;overflow-wrap:anywhere}",
+    ".insika-m.user{align-self:flex-end;background:var(--insika-accent,#1f2937);color:var(--insika-on-accent,#fff)}",
+    ".insika-m.agent{align-self:flex-start;background:var(--insika-muted,#f3f4f6);color:var(--insika-fg,#111827)}",
+    ".insika-m.note{align-self:center;font-size:13px;opacity:.7;background:none;padding:2px}",
+    ".insika-f{display:flex;gap:8px;padding:10px;border-top:1px solid var(--insika-border,rgba(0,0,0,.12))}",
+    ".insika-f input{flex:1;min-width:0;padding:9px 11px;border-radius:9px;font:inherit;color:inherit;background:transparent;",
+    "border:1px solid var(--insika-border,rgba(0,0,0,.18))}",
+    ".insika-f button{padding:9px 14px;border:0;border-radius:9px;cursor:pointer;font:inherit;",
+    "background:var(--insika-accent,#1f2937);color:var(--insika-on-accent,#fff)}",
+    ".insika-f button[disabled]{opacity:.5;cursor:default}"
+  ].join("");
+
+  var style = document.createElement("style");
+  style.textContent = CSS;
+  document.head.appendChild(style);
+
+  var root = el("div", "insika-w");
+  var panel = el("div", "insika-p");
+  var header = el("div", "insika-h");
+  var log = el("div", "insika-log");
+  var form = document.createElement("form");
+  var input = document.createElement("input");
+  var send = document.createElement("button");
+  var bubble = el("button", "insika-b");
+
+  header.appendChild(text("span", title));
+  var close = el("button", "insika-x");
+  close.type = "button";
+  close.textContent = "×";
+  close.setAttribute("aria-label", "Close");
+  header.appendChild(close);
+
+  form.className = "insika-f";
+  input.type = "text";
+  input.placeholder = placeholder;
+  input.setAttribute("aria-label", placeholder);
+  send.type = "submit";
+  send.textContent = "Send";
+  form.appendChild(input);
+  form.appendChild(send);
+
+  panel.appendChild(header);
+  panel.appendChild(log);
+  panel.appendChild(form);
+
+  bubble.type = "button";
+  bubble.textContent = "💬";
+  bubble.setAttribute("aria-label", title);
+
+  root.appendChild(panel);
+  root.appendChild(bubble);
+  document.body.appendChild(root);
+
+  if (greeting) say("agent", greeting);
+
+  bubble.addEventListener("click", toggle);
+  close.addEventListener("click", toggle);
+  form.addEventListener("submit", function (e) {
+    e.preventDefault();
+    var value = input.value.trim();
+    if (!value || busy) return;
+    input.value = "";
+    ask(value);
+  });
+
+  function toggle() {
+    root.classList.toggle("open");
+    if (root.classList.contains("open")) input.focus();
+  }
+
+  // --- the turn -------------------------------------------------------
+
+  var busy = false;
+
+  function ask(message) {
+    busy = true;
+    send.disabled = true;
+    say("user", message);
+
+    var bubbleEl = null;
+    var note = null;
+
+    session()
+      .then(function (id) {
+        return fetch(base + "/channels/" + channel + "/messages", {
+          method: "POST",
+          headers: { "content-type": "application/json" },
+          body: JSON.stringify({ agent: agent, session_id: id, message: message })
+        });
+      })
+      .then(function (res) {
+        // An unknown session id (the store was wiped, the id expired) is the one
+        // recoverable failure: drop ours and let the next message mint a new one.
+        if (res.status === 404) {
+          forget();
+          throw new Error("session expired — please send that again");
+        }
+        if (!res.ok || !res.body) throw new Error("the assistant is unavailable right now");
+        return read(res.body.getReader(), function (event, data) {
+          if (event === "delta" && data.delta) {
+            if (note) { note.remove(); note = null; }
+            if (!bubbleEl) bubbleEl = say("agent", "");
+            bubbleEl.textContent += data.delta;
+            log.scrollTop = log.scrollHeight;
+          } else if (event === "working" && !bubbleEl && !note) {
+            note = say("note", "working…");
+          } else if (event === "error") {
+            if (note) { note.remove(); note = null; }
+            throw new Error(data.message || "something went wrong");
+          }
+        });
+      })
+      .catch(function (err) {
+        if (note) note.remove();
+        say("note", err.message || "something went wrong");
+      })
+      .finally(function () {
+        busy = false;
+        send.disabled = false;
+        input.focus();
+      });
+  }
+
+  // The engine issues the session id; we only ever store the one it gave us
+  // (a client that proposes its own id on a public endpoint is
+  // one enumeration away from reading someone else's conversation).
+  function session() {
+    var saved = remembered;
+    if (saved) return Promise.resolve(saved);
+
+    return mint(0).then(function (id) {
+      remember(id);
+      return id;
+    });
+  }
+
+  // localStorage THROWS (not returns null) in a sandboxed iframe, in Safari's
+  // private mode and wherever site data is blocked. Reading it unguarded would
+  // throw out of `ask` before the .catch is attached, leaving the send button
+  // disabled forever. So the conversation degrades to in-memory instead: it lives
+  // for the page, which is worse than remembering and much better than frozen.
+  var remembered = read_storage();
+
+  function read_storage() {
+    try { return localStorage.getItem(storageKey); } catch (e) { return null; }
+  }
+
+  function remember(id) {
+    remembered = id;
+    try { localStorage.setItem(storageKey, id); } catch (e) { /* in-memory only */ }
+  }
+
+  function forget() {
+    remembered = null;
+    try { localStorage.removeItem(storageKey); } catch (e) { /* in-memory only */ }
+  }
+
+  // 1s → 30s backoff, one attempt in flight, the same discipline the Studio's
+  // live transcript uses. Safe to repeat because minting has no side effect the
+  // customer can see: the worst case is an unused empty session.
+  function mint(attempt) {
+    return fetch(base + "/channels/" + channel + "/sessions", { method: "POST" })
+      .then(function (res) {
+        if (!res.ok) throw new Error("HTTP " + res.status);
+        return res.json();
+      })
+      .then(function (body) {
+        if (!body.session_id) throw new Error("no session id");
+        return body.session_id;
+      })
+      .catch(function (err) {
+        if (attempt >= 4) throw new Error("cannot reach the assistant right now");
+        var wait = Math.min(30000, 1000 * Math.pow(2, attempt));
+        return delay(wait).then(function () { return mint(attempt + 1); });
+      });
+  }
+
+  // Minimal SSE reader over fetch — EventSource cannot POST, and the turn is a
+  // POST. Frames are `event: <name>\ndata: <json>\n\n`; anything else is skipped,
+  // so a frame added later cannot break an old widget.
+  function read(reader, onEvent) {
+    var decoder = new TextDecoder();
+    var buffer = "";
+
+    return reader.read().then(function step(chunk) {
+      if (chunk.done) return;
+      buffer += decoder.decode(chunk.value, { stream: true });
+
+      var parts = buffer.split("\n\n");
+      buffer = parts.pop();
+      parts.forEach(function (frame) {
+        var name = (frame.match(/^event: (.+)$/m) || [])[1];
+        var raw = (frame.match(/^data: (.*)$/m) || [])[1];
+        if (!name) return;
+        var data = {};
+        try { data = raw ? JSON.parse(raw) : {}; } catch (e) { return; }
+        onEvent(name, data);
+      });
+
+      return reader.read().then(step);
+    });
+  }
+
+  // --- helpers --------------------------------------------------------
+
+  function say(kind, content) {
+    var node = el("div", "insika-m " + kind);
+    node.textContent = content;
+    log.appendChild(node);
+    log.scrollTop = log.scrollHeight;
+    return node;
+  }
+
+  function el(tag, className) {
+    var node = document.createElement(tag);
+    node.className = className;
+    return node;
+  }
+
+  function text(tag, content) {
+    var node = document.createElement(tag);
+    node.textContent = content;
+    return node;
+  }
+
+  function delay(ms) {
+    return new Promise(function (resolve) { setTimeout(resolve, ms); });
+  }
+})();

data/lib/insika/channels/web.rb

@@ -0,0 +1,211 @@
+# frozen_string_literal: true
+
+require "digest"
+require "json"
+require "securerandom"
+
+module Insika
+  module Channels
+    # The web widget — the FIRST Shape A channel, and the adoption
+    # claim behind the whole RFC: an adopter pastes one tag into their site and has
+    # a working agent, with no backend of their own and no build step.
+    #
+    #   <script src="https://agents.example.com/channels/web/asset/widget.js"
+    #           data-agent="support" data-title="Ask us anything" defer></script>
+    #
+    # Shape A means the reply comes back on the request's own stream, so there is
+    # no outbox, no claim and no `deliver` here — the three routes and a static
+    # asset are the entire surface:
+    #
+    #   POST /channels/web/sessions      mint an opaque session id (the engine's)
+    #   POST /channels/web/messages      the turn, answered as SSE on this connection
+    #   GET  /channels/web/asset/widget.js
+    #
+    # What makes this channel different from the relay is that it is PUBLIC: the
+    # caller is an anonymous browser, so there is no shared secret to check and the
+    # money faucet is real. Three things stand in for the missing credential, and
+    # all three are refusals, never grants (R2):
+    #
+    #   · an AGENT allowlist — a visitor addresses the agents the operator published
+    #     to the widget, not every agent in the deployment;
+    #   · an ORIGIN allowlist — exact match, no wildcards, and no "allow all" value;
+    #   · a mandatory chat RATE LIMIT — the channel answers `:disabled`
+    #     until one is configured, because a public endpoint with an LLM behind it
+    #     and no ceiling is an unmetered bill waiting to happen.
+    #
+    # R1/R2 hold: this object translates and refuses, and does nothing else. No
+    # Executor, no store, no RubyLLM — the rate-limit probe is injected as a plain
+    # callable so the channel never learns what a profile or a settings store is.
+    class Web
+      DEFAULT_ID = "web"
+
+      # The static files this channel serves, by request name. A closed map, not a
+      # directory listing: `asset/:f` takes a name from the URL, and anything that
+      # resolves a path from user input is a traversal waiting to be found.
+      ASSETS = {
+        "widget.js" => { file: "web/widget.js", content_type: "application/javascript; charset=utf-8" }
+      }.freeze
+
+      # An unversioned URL cannot be cached for a year — the next release would
+      # never reach a browser that already has it. Short max-age + an ETag instead:
+      # the common case is a 304 with no body, and an upgrade lands within minutes.
+      # (A deliberate narrowing of's "long-cache versioned URL": the install
+      # snippet in the RFC has no version in it, so there is nothing to bust.)
+      ASSET_CACHE_CONTROL = "public, max-age=300"
+
+      attr_reader :id
+
+      # The bundled widget as an operator configures it. BOTH allowlists are the
+      # switch: a widget with no origins can be embedded nowhere, and one with no
+      # agents can address nothing, so either one missing means the operator has not
+      # actually asked for this channel. -> Web | nil.
+      def self.from_env(env = ENV, id: DEFAULT_ID, chat_rate_limit: nil)
+        origins = csv(Insika::EnvSchema.read("INSIKA_WIDGET_ORIGINS", env))
+        agents  = csv(Insika::EnvSchema.read("INSIKA_WIDGET_AGENTS", env))
+        return nil if origins.empty? || agents.empty?
+
+        new(origins: origins, agents: agents, id: id, chat_rate_limit: chat_rate_limit)
+      end
+
+      # The probe's gate needs, asked exactly the way `EdgeLimiter` asks it at
+      # turn time: the per-agent override first, the platform default second. Built
+      # here so both composition roots wire the gate identically, and returned as a
+      # lambda so the channel itself stays store-free.
+      #
+      # Resolved on every check rather than at boot: an operator who removes the
+      # limit tomorrow closes the widget, instead of leaving it open because it was
+      # configured correctly once.
+      def self.limit_resolver(profiles:, settings_store: nil)
+        lambda do |agent_id|
+          limits = profiles&.fetch(agent_id.to_s)&.limits || {}
+          next limits[:chat_rate_limit] if limits.key?(:chat_rate_limit)
+
+          ((settings_store&.get || {})["edge"] || {})["chat_rate_limit"]
+        end
+      end
+
+      def self.csv(value) = value.to_s.split(",").map(&:strip).reject(&:empty?)
+
+      # origins:         exact-match origin allowlist (`https://shop.example`). No
+      #                  wildcard, no "*" — CORS is a browser courtesy and a value
+      #                  that means "anyone" would only make it look like a control.
+      # agents:          agent ids a visitor may address.
+      # chat_rate_limit: callable(agent_id) -> the effective limit, or nil. Absent ⇒
+      #                  the channel is `:disabled`, which is the fail-closed
+      #                  reading of "no ceiling configured".
+      def initialize(origins:, agents:, id: DEFAULT_ID, chat_rate_limit: nil)
+        @id = id.to_s
+        @origins = Array(origins).map(&:to_s)
+        @agents = Array(agents).map(&:to_s)
+        @chat_rate_limit = chat_rate_limit
+        @assets = {}
+      end
+
+      # -> :ok | :unauthorized | :disabled. Same verdict vocabulary as every other
+      # channel (no Rack triple in `lib/`), and the same fail-closed default.
+      #
+      # A request with NO `Origin` is not a browser, so there is nothing for CORS to
+      # protect and refusing it would be theatre — curl can always set any origin it
+      # likes. The rate limit is what actually defends this route, which is why it
+      # is checked here and not left to the operator's memory.
+      def authenticate(req)
+        return :disabled if @agents.empty?
+        return :disabled unless rate_limited?
+
+        origin = req.get_header("HTTP_ORIGIN").to_s
+        return :ok if origin.empty?
+
+        allowed_origin?(origin) ? :ok : :unauthorized
+      end
+
+      # Is a chat rate limit configured for EVERY agent the widget publishes? All of
+      # them and not just the one being addressed: the check runs before the body is
+      # parsed, and "the widget is open for agent A but closed for agent B" is a
+      # posture nobody can hold in their head.
+      def rate_limited?
+        return false if @chat_rate_limit.nil?
+
+        !@agents.empty? && @agents.all? { |agent| @chat_rate_limit.call(agent).to_i.positive? }
+      end
+
+      # POST /channels/web/messages — STRING keys in, because this body comes off
+      # the public internet and nothing in it should become a symbol.
+      #
+      #   { "agent": "support", "session_id": "web:8f3c…", "message": "oi" }
+      #
+      # The agent allowlist is checked HERE, which is a refusal and not a grant: the
+      # profile still decides what that agent may do.
+      def parse(_req, body:)
+        body = body.is_a?(Hash) ? body : {}
+        agent = body["agent"].to_s.strip
+        session_id = body["session_id"].to_s.strip
+        message = body["message"].to_s
+
+        raise Insika::ValidationError, "agent is required" if agent.empty?
+        raise Insika::ValidationError, "agent '#{agent}' is not published to the widget" unless @agents.include?(agent)
+        raise Insika::ValidationError, "session_id is required" if session_id.empty?
+        raise Insika::ValidationError, "message is required" if message.strip.empty?
+
+        { agent: agent, session_id: session_id, message: message }
+      end
+
+      #'s hard rule for a public channel: the ENGINE issues the id and the
+      # client never proposes one. A visitor-supplied session id on an anonymous
+      # endpoint is session hijacking by enumeration, so there is no create-on-write
+      # path — `POST /messages` with an unknown id is a 404, not a new conversation.
+      def mint_session_id = "#{@id}:#{SecureRandom.hex(16)}"
+
+      # Turn Event -> SSE frame | nil. Four frames, which is the whole widget
+      # protocol: what to type, what to say while a tool runs, and how it ended.
+      #
+      # `:intermediate` and `:thinking` are deliberately absent. `:content` is the
+      # ANSWER — the model's narration on the way there is internal, and a
+      # widget that rendered it would show the customer the engine thinking out loud.
+      def frame_for(event)
+        case event.type
+        when :content        then sse("delta", { delta: event.data[:delta].to_s })
+        when :tool_call      then sse("working", { name: event.data[:name].to_s })
+        when :task_completed then sse("done", {})
+        when :task_failed    then sse("error", { message: event.data[:message].to_s })
+        when :task_cancelled then sse("error", { message: "task cancelled" })
+        when :error          then sse("error", { message: event.data[:message].to_s })
+        end
+      end
+
+      # GET /channels/web/asset/:f -> { content_type:, body:, etag: } | nil.
+      # Read once and memoized: the file ships with the gem and cannot change under
+      # a running process.
+      def asset(name)
+        entry = ASSETS[name.to_s]
+        return nil if entry.nil?
+
+        @assets[name.to_s] ||= begin
+          body = File.read(File.expand_path(entry[:file], __dir__))
+          { content_type: entry[:content_type], body: body,
+            etag: %("#{Digest::SHA256.hexdigest(body)[0, 16]}"),
+            cache_control: ASSET_CACHE_CONTROL }
+        end
+      end
+
+      # -> the CORS headers for this request's origin. An origin that is not on the
+      # list simply gets none, and the browser refuses the response itself — the
+      # engine does not have to pretend that is an authorization decision.
+      def cors_headers(origin)
+        o = origin.to_s
+        return { "vary" => "origin" } unless allowed_origin?(o)
+
+        { "access-control-allow-origin" => o,
+          "vary" => "origin",
+          "access-control-allow-headers" => "content-type",
+          "access-control-allow-methods" => "POST, OPTIONS",
+          "access-control-max-age" => "600" }
+      end
+
+      private
+
+      def allowed_origin?(origin) = !origin.empty? && @origins.include?(origin)
+
+      def sse(name, data) = "event: #{name}\ndata: #{JSON.generate(data)}\n\n"
+    end
+  end
+end

data/lib/insika/channels/webhook.rb

@@ -0,0 +1,58 @@
+# frozen_string_literal: true
+
+require "json"
+
+module Insika
+  module Channels
+    # A webhook as a Shape B "channel": the recipient of operator ALERTS
+    # (WS6). One instance per configured URL, registered in the ChannelRegistry
+    # so ChannelDelivery's outbox+claim+retry pipeline delivers the alert the
+    # same way it delivers a chat answer — at-most-once, bounded retry, boot
+    # sweep. Deliberately NOT Slack/CRM/anything: it POSTs the event as JSON and
+    # the consumer interprets it (the engine transports, it does not integrate).
+    #
+    # The target URL is operator configuration, so the POST crosses the SAME
+    # egress guard the Relay applies: https-only (fails closed), private/
+    # loopback/metadata targets and DNS-rebindable hosts blocked. Without it the
+    # `alerts.webhook` URL is an SSRF vector — a URL pointed at cloud metadata
+    # or an internal API exfiltrates alert events out of the boundary (WS6).
+    class Webhook
+      def initialize(url, http:, allow_http: false, allow_private: false)
+        @http = http
+        @allow_http = allow_http
+        @allow_private = allow_private
+      end
+
+      # The ChannelDelivery contract: -> HTTP status (200..299 = delivered).
+      # Every failure becomes a DeliveryError so the bounded retry records it.
+      def deliver(payload, to:, delivery_id: nil)
+        if (reason = egress_violation(to))
+          raise Insika::DeliveryError, "webhook egress blocked for #{to}: #{reason}"
+        end
+
+        result = @http.request(
+          method: :post, url: to,
+          headers: { "content-type" => "application/json" },
+          body: JSON.generate(payload)
+        )
+        result[:status].to_i
+      rescue Insika::DeliveryError
+        raise
+      rescue StandardError => e
+        raise Insika::DeliveryError, "webhook: #{e.message}"
+      end
+
+      private
+
+      # Resolved on EVERY delivery, not once at registration: a host that
+      # answered a public address yesterday can answer 169.254.169.254 today,
+      # and this POST carries the operator's alerts.
+      def egress_violation(url)
+        Insika::EgressGuard.violation(url, allow_http: @allow_http,
+                                           allow_private: @allow_private)
+      rescue URI::InvalidURIError
+        "invalid URL"
+      end
+    end
+  end
+end