studio-engine 0.115.4.rc1 → 0.116.0.rc1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: fa2d9adfea1b7487c4d3e6179f6c9f35883f66220d453289486c70751491ba46
-  data.tar.gz: 1d37a2a532562cfc6ade149f582f902638b72c4d7f094663297178ca54c4b605
+  metadata.gz: 2c4110fb2193a6a381c74f20802d33e407c06192bd454f5b3e11b8f681cb9728
+  data.tar.gz: acc4906d77b7a8e286c5c601c86113964e3b7fab1073fe1332b77f0e54e78a61
 SHA512:
-  metadata.gz: 36e42c01b2ccdbf1d014d618148d4243716e55f15ab5bbfa126f425d26b60c8920ad4804cdc485394add55c580398c76d98fb208a8e546cf8737255d7ab7f9ea
-  data.tar.gz: 53fcc424881f1aec06cb246b5c458a48f98f4806d1723c2f92f23c748e9d18c448902fa7f808b3d526fb28e35da669fb669cb4bc31127417900c581a15446288
+  metadata.gz: 5bb8eb6f9ef719a032a0a1ec05394222a70753e107a406fb82c7c2adf0cea769fc673395448e65fe3d356542450edb933f9eb9e8402b9a7dc14df86c5991d47d
+  data.tar.gz: 76a7b9f0d7a60022406cdfa66b0b02e5245ef7bba95cbdcc997c6c9277b00c103cb85547fb44ce89996844c3f39c9b412736321b32bffa0eb34b923b6e0a3fcf

data/CHANGELOG.md

@@ -4,6 +4,37 @@ The format is [Keep a Changelog](https://keepachangelog.com/en/1.1.0/). This pro
 
 ## Unreleased
 
+## 0.116.0 — 2026-10-28
+
+### Added
+
+- **The shared agent chat.** `render "studio/agent_chat/chat", soul:, name:, portrait:`
+  puts one chat with a hub agent on any page: the portrait header, a card slot
+  (`cards:`), the thread, the thinking/typing line, the composer and a friendly
+  retry when the hub is down, lifted from the hub's /build chat. The hub holds the
+  thread; `Studio::AgentChatsController` (`POST /agent_chat/messages`,
+  `GET /agent_chat/turns`) proxies to it with the signed-in user's email or a
+  signed anonymous cookie token, and `Studio::AgentChat` is the bounded hub
+  client. Only a verified email (`email_verified_at`, or the app's
+  `Studio.agent_chat_verified_email` hook) names a person to the hub; anyone
+  else chats anonymously. Opt in with `Studio.agent_chat_souls` and
+  `AGENT_CHAT_TOKEN`; no soul, no route. [`docs/AGENT_CHAT.md`](docs/AGENT_CHAT.md).
+
+### Changed
+
+- **The gear, the name and the avatar light together.** Where the account opens
+  the link sidebar, as the gear does, pointing at or focusing any of the three
+  turns the gear and the name the theme's primary, turns the gear an eighth
+  (not under reduced motion) and puts a soft primary glow on the avatar; the
+  gear's own hover pill is dropped inside the group. CSS only (`engine.css`,
+  *THE ACCOUNT GROUP*), keyed on the row's existing hooks, so the navbar
+  baseline's bytes are unchanged. Two shapes group: the engine's link sidebar
+  gear with an account that opens it, and a host's gear in the menu trigger
+  seat (`Studio.navbar_menu_trigger`) with an account that opens the host's
+  sidebar (`Studio.navbar_account_sidebar`), as Turf Monster's gear sidebar
+  does. An account link is never grouped. Guards: `test/views/navbar_account_group_css_test.rb`,
+  `test/views/user_nav_test.rb`, `e2e/navbar_account_group.spec.js`.
+
 ## 0.115.4 — 2026-10-27
 
 ### Changed

data/README.md

@@ -245,6 +245,8 @@ Set `Studio.draw_survey_routes = true` to add the public survey pages (`/surveys
 
 **Magic links need the `studio_links` table.** Install it with `bin/rails studio_engine:install:migrations && bin/rails db:migrate` (install all of them) before enabling `:magic_link` — never by hand-copying the migration, which collides with the task's own copy on `class CreateStudioLinks`. Without the table, the first sign-in raises `Studio::Link::MissingTable`.
 
+Set `Studio.agent_chat_souls = %w[alex]` to add the shared agent chat's proxy (`POST /agent_chat/messages`, `GET /agent_chat/turns`), which forwards to the McRitchie Studio hub with the app's `AGENT_CHAT_TOKEN`; then `render "studio/agent_chat/chat", soul: "alex", name: "Alex", portrait: ...` on any page ([`docs/AGENT_CHAT.md`](docs/AGENT_CHAT.md)).
+
 In non-production local requests, this also draws `/_studio/local_emails`, a local email inbox for agent/worktree proof flows. Set `LOCAL_EMAIL_CAPTURE=1` or run with `AGENT_WORKTREE=1` to record outbox rows without sending real email.
 
 In every environment, production included, it also draws `/_studio/health_report`: the daily health report as counts-only JSON, which the McRitchie Studio hub pulls at 07:00 and posts to Discord. It answers 404 until the app sets `STUDIO_HEALTH_TOKEN` (or `config.health_report_token`), and 401 to a request without that bearer token ([`docs/HEALTH_REPORT.md`](docs/HEALTH_REPORT.md#the-hub-endpoint)).
@@ -1097,6 +1099,13 @@ helper `studio_account_opens_sidebar?` to decide otherwise; with no sidebar
 the account stays a link to the account page. Log out lives in the sidebar,
 never the bar.
 
+Since the gear and the account open the same sidebar, they read as one control:
+pointing at or focusing any of the gear, the name or the avatar lights all three
+(the primary colour, a turn of the gear, a primary glow on the avatar). The
+same holds for a host sidebar: a host that sets both `navbar_menu_trigger` and
+`navbar_account_sidebar` gets its gear and account lit as one menu. An account
+link is never grouped (`engine.css`, *THE ACCOUNT GROUP*).
+
 ## Transactional emails
 
 Every consuming app can render the same admin page — **`/admin/emails`** —

data/app/assets/tailwind/studio_engine/engine-motion.css

@@ -2010,3 +2010,156 @@ body.modal-open { overflow: visible; }
   .email-reject { animation-name: email-reject-fade; }
 }
 }
+
+/* -- Agent chat: a pending answer's indicator --------------------------------
+   studio/agent_chat/_typing, lifted from the hub's agent_typing.css. Two looks
+   share one grid cell, so the swap from thinking to typing never moves the page:
+
+   THINKING  the agent's portrait in a soft turning ring with a glow, and
+             "<Agent> is thinking" with a slow shimmer across it.
+   TYPING    a chat bubble on the agent's side with three wave dots.
+
+   data-phase picks the look (studio/agent_chat sets it); the other fades out
+   and is hidden, so it is not read aloud. Theme tokens only, so dark mode
+   follows the theme. Under prefers-reduced-motion nothing moves and the swap
+   is instant. In the components layer, like every rule here; needs this
+   layer, which host.css imports (a host that skips it sees both labels). */
+@layer components {
+  .studio-agent-typing {
+    --studio-agent-typing-beat: 2.4s;
+    --studio-agent-typing-fade: 280ms;
+    display: grid;
+    align-items: center;
+    padding-block: 0.375rem;
+    font-size: 0.75rem;
+    line-height: 1rem;
+    color: var(--color-text-muted);
+  }
+
+  .studio-agent-typing > .studio-agent-typing-layer {
+    grid-area: 1 / 1;
+    display: flex;
+    align-items: center;
+    gap: 0.625rem;
+    min-width: 0;
+    transition: opacity var(--studio-agent-typing-fade) ease, transform var(--studio-agent-typing-fade) ease,
+      visibility 0s linear 0s;
+  }
+
+  .studio-agent-typing[data-phase="thinking"] > .studio-agent-typing-types,
+  .studio-agent-typing[data-phase="typing"] > .studio-agent-typing-thinks {
+    opacity: 0;
+    transform: translateY(3px);
+    visibility: hidden;
+    pointer-events: none;
+    transition: opacity var(--studio-agent-typing-fade) ease, transform var(--studio-agent-typing-fade) ease,
+      visibility 0s linear var(--studio-agent-typing-fade);
+  }
+
+  .studio-agent-typing-label {
+    min-width: 0;
+    overflow: hidden;
+    text-overflow: ellipsis;
+    white-space: nowrap;
+  }
+
+  .studio-agent-typing-orbit {
+    position: relative;
+    display: inline-flex;
+    flex: none;
+    border-radius: 9999px;
+    padding: 3px;
+  }
+
+  .studio-agent-typing-orbit::before,
+  .studio-agent-typing-orbit::after {
+    content: "";
+    position: absolute;
+    inset: 0;
+    border-radius: inherit;
+    pointer-events: none;
+  }
+
+  .studio-agent-typing-orbit::before {
+    background: conic-gradient(
+      from 0deg,
+      rgb(var(--color-primary-rgb) / 0) 0deg,
+      rgb(var(--color-primary-rgb) / 0.25) 90deg,
+      rgb(var(--color-primary-rgb) / 0.95) 200deg,
+      rgb(var(--color-primary-rgb) / 0) 300deg
+    );
+    -webkit-mask: radial-gradient(farthest-side, transparent calc(100% - 2px), #000 calc(100% - 1.5px));
+            mask: radial-gradient(farthest-side, transparent calc(100% - 2px), #000 calc(100% - 1.5px));
+    animation: studio-agent-typing-spin var(--studio-agent-typing-beat) linear infinite;
+  }
+
+  .studio-agent-typing-orbit::after {
+    box-shadow: 0 0 0.9rem 0.05rem rgb(var(--color-primary-rgb) / 0.35);
+    animation: studio-agent-typing-breathe var(--studio-agent-typing-beat) ease-in-out infinite;
+  }
+
+  .studio-agent-typing-orbit > * {
+    position: relative;
+    z-index: 1;
+  }
+
+  .studio-agent-typing-shimmer {
+    background-image: linear-gradient(100deg, var(--color-text-muted) 0%, var(--color-text-muted) 38%,
+      var(--color-text) 50%, var(--color-text-muted) 62%, var(--color-text-muted) 100%);
+    background-size: 250% 100%;
+    -webkit-background-clip: text;
+            background-clip: text;
+    -webkit-text-fill-color: transparent;
+    color: transparent;
+    animation: studio-agent-typing-shimmer var(--studio-agent-typing-beat) ease-in-out infinite;
+  }
+
+  .studio-agent-typing-bubble {
+    display: inline-flex;
+    align-items: center;
+    gap: 0.25rem;
+    flex: none;
+    padding: 0.625rem 0.75rem;
+    border-radius: 1rem 1rem 1rem 0.25rem;
+    background: var(--color-inset);
+    border: 1px solid var(--color-border);
+  }
+
+  .studio-agent-typing-dot {
+    width: 0.4rem;
+    height: 0.4rem;
+    border-radius: 9999px;
+    background: var(--color-text-muted);
+    animation: studio-agent-typing-wave calc(var(--studio-agent-typing-beat) / 2) ease-in-out infinite;
+  }
+
+  .studio-agent-typing-dot:nth-child(2) { animation-delay: 0.15s; }
+  .studio-agent-typing-dot:nth-child(3) { animation-delay: 0.3s; }
+
+  @media (prefers-reduced-motion: reduce) {
+    .studio-agent-typing-orbit::before,
+    .studio-agent-typing-orbit::after,
+    .studio-agent-typing-shimmer,
+    .studio-agent-typing-dot { animation: none; }
+    .studio-agent-typing > .studio-agent-typing-layer { transition: none; }
+  }
+
+  @keyframes studio-agent-typing-spin {
+    to { transform: rotate(360deg); }
+  }
+
+  @keyframes studio-agent-typing-breathe {
+    0%, 100% { opacity: 0.45; }
+    50% { opacity: 1; }
+  }
+
+  @keyframes studio-agent-typing-shimmer {
+    0% { background-position: 100% 0; }
+    100% { background-position: 0% 0; }
+  }
+
+  @keyframes studio-agent-typing-wave {
+    0%, 60%, 100% { transform: translateY(0); opacity: 0.5; }
+    30% { transform: translateY(-3px); opacity: 1; }
+  }
+}

data/app/assets/tailwind/studio_engine/engine.css

@@ -723,9 +723,55 @@ body.modal-open .studio-app-banner {
       top: -0.25rem;
       pointer-events: auto;
     }
+    /* THE ACCOUNT GROUP (components/_user_nav). Where the gear and the account
+       (name and avatar) open the same sidebar, the three are one control to
+       the eye: pointing at or focusing any of them lights all three. The gear
+       and the name take the primary colour, the gear turns an eighth, and the
+       avatar glows in the brand's primary. The gear drops its own hover pill,
+       which would mark it out as a separate control.
+
+       The group is the user nav's row, found by what it holds, so no markup
+       changes (the navbar baseline holds its bytes). Two shapes group:
+         THE LINK SIDEBAR: the engine's gear ([data-link-sidebar-trigger]) and
+           an account whose aria-controls names studio-link-sidebar.
+         A HOST SIDEBAR: the host's gear in the menu trigger seat
+           (Studio.navbar_menu_trigger) and an account that opens the host's
+           sidebar (Studio.navbar_account_sidebar). A host that sets both is
+           saying they are its one menu, as Turf Monster's gear sidebar is.
+       An account link is never grouped. */
+    :has(> [data-nav-tools]):has(> [data-nav-account][aria-controls~="studio-link-sidebar"]) [data-link-sidebar-trigger] svg,
+    :has(> [data-nav-tools]):has(> [data-nav-account][aria-controls~="studio-link-sidebar"]) [data-nav-account] > [aria-hidden] > * {
+      transition: transform 200ms ease, box-shadow 200ms ease;
+    }
+    :has(> [data-nav-tools]):has(> [data-nav-account][aria-controls~="studio-link-sidebar"]) [data-link-sidebar-trigger]:hover { background-color: transparent; }
+    :has(> [data-nav-tools]):has(> [data-nav-account][aria-controls~="studio-link-sidebar"]):has([data-link-sidebar-trigger]:hover, [data-nav-account]:hover, [data-link-sidebar-trigger]:focus-visible, [data-nav-account]:focus-visible) [data-link-sidebar-trigger],
+    :has(> [data-nav-tools]):has(> [data-nav-account][aria-controls~="studio-link-sidebar"]):has([data-link-sidebar-trigger]:hover, [data-nav-account]:hover, [data-link-sidebar-trigger]:focus-visible, [data-nav-account]:focus-visible) [data-nav-name] { color: var(--color-primary); }
+    :has(> [data-nav-tools]):has(> [data-nav-account][aria-controls~="studio-link-sidebar"]):has([data-link-sidebar-trigger]:hover, [data-nav-account]:hover, [data-link-sidebar-trigger]:focus-visible, [data-nav-account]:focus-visible) [data-nav-account] > [aria-hidden] > * {
+      box-shadow:
+        0 0 0 2px rgb(var(--color-primary-rgb) / 0.85),
+        0 0 14px 2px rgb(var(--color-primary-rgb) / 0.45);
+    }
+    @media (prefers-reduced-motion: no-preference) {
+      :has(> [data-nav-tools]):has(> [data-nav-account][aria-controls~="studio-link-sidebar"]):has([data-link-sidebar-trigger]:hover, [data-nav-account]:hover, [data-link-sidebar-trigger]:focus-visible, [data-nav-account]:focus-visible) [data-link-sidebar-trigger] svg { transform: rotate(45deg); }
+    }
+    :has(> [data-nav-tools] [data-nav-menu-trigger]):has(> [data-nav-account][data-profile-image-toggle]:not([aria-controls~="studio-link-sidebar"])) [data-nav-menu-trigger] [aria-controls] svg,
+    :has(> [data-nav-tools] [data-nav-menu-trigger]):has(> [data-nav-account][data-profile-image-toggle]:not([aria-controls~="studio-link-sidebar"])) [data-nav-account] > [aria-hidden] > * {
+      transition: transform 200ms ease, box-shadow 200ms ease;
+    }
+    :has(> [data-nav-tools] [data-nav-menu-trigger]):has(> [data-nav-account][data-profile-image-toggle]:not([aria-controls~="studio-link-sidebar"])) [data-nav-menu-trigger] [aria-controls]:hover { background-color: transparent; }
+    :has(> [data-nav-tools] [data-nav-menu-trigger]):has(> [data-nav-account][data-profile-image-toggle]:not([aria-controls~="studio-link-sidebar"])):has([data-nav-menu-trigger] [aria-controls]:hover, [data-nav-account]:hover, [data-nav-menu-trigger] [aria-controls]:focus-visible, [data-nav-account]:focus-visible) [data-nav-menu-trigger] [aria-controls],
+    :has(> [data-nav-tools] [data-nav-menu-trigger]):has(> [data-nav-account][data-profile-image-toggle]:not([aria-controls~="studio-link-sidebar"])):has([data-nav-menu-trigger] [aria-controls]:hover, [data-nav-account]:hover, [data-nav-menu-trigger] [aria-controls]:focus-visible, [data-nav-account]:focus-visible) [data-nav-name] { color: var(--color-primary); }
+    :has(> [data-nav-tools] [data-nav-menu-trigger]):has(> [data-nav-account][data-profile-image-toggle]:not([aria-controls~="studio-link-sidebar"])):has([data-nav-menu-trigger] [aria-controls]:hover, [data-nav-account]:hover, [data-nav-menu-trigger] [aria-controls]:focus-visible, [data-nav-account]:focus-visible) [data-nav-account] > [aria-hidden] > * {
+      box-shadow:
+        0 0 0 2px rgb(var(--color-primary-rgb) / 0.85),
+        0 0 14px 2px rgb(var(--color-primary-rgb) / 0.45);
+    }
+    @media (prefers-reduced-motion: no-preference) {
+      :has(> [data-nav-tools] [data-nav-menu-trigger]):has(> [data-nav-account][data-profile-image-toggle]:not([aria-controls~="studio-link-sidebar"])):has([data-nav-menu-trigger] [aria-controls]:hover, [data-nav-account]:hover, [data-nav-menu-trigger] [aria-controls]:focus-visible, [data-nav-account]:focus-visible) [data-nav-menu-trigger] [aria-controls] svg { transform: rotate(45deg); }
+    }
     /* THE ACCOUNT ROW (components/_user_nav), from 768px. Every app whose
-       navbar renders the engine's user nav gets this; Turf Monster forks the
-       partial, carries none of these hooks, and keeps its own two-row nav.
+       navbar renders the engine's user nav gets this, Turf Monster included:
+       it renders the engine's partial, its gear in the menu trigger seat.
 
        ICONS. The theme toggle leads the rail (the partial renders it first) and
        both icons sit a size down: the moon at 14px, the gear's 16px glyph in a

data/app/controllers/studio/agent_chats_controller.rb

@@ -0,0 +1,178 @@
+# frozen_string_literal: true
+
+module Studio
+  # The shared agent chat's proxy (docs/AGENT_CHAT.md). The browser talks only
+  # to its own app; this controller forwards its two calls to the hub through
+  # Studio::AgentChat:
+  #
+  #   POST /agent_chat/messages  soul, text         -> 201 {turn}
+  #   GET  /agent_chat/turns     soul, after, limit -> 200 {turns, pending}
+  #
+  # Drawn by Studio.routes only for an app that names a soul
+  # (Studio.agent_chat_souls).
+  #
+  # WHAT THE BROWSER MAY CHOOSE, AND WHAT IT MAY NOT:
+  #
+  #   soul    only from the app's allow-list (Studio.agent_chat_souls); off the
+  #           list, or absent when the list holds more than one, is a 404. The
+  #           hub re-checks that this app may address it.
+  #   person  never. A signed-in user with a VERIFIED email (email_verified_at
+  #           present, or the app's Studio.agent_chat_verified_email hook) is
+  #           that email. Everyone else, signed out or signed in with an address
+  #           they only claimed (the profile page and password signup save any
+  #           address), is a random token in a SIGNED, http-only cookie
+  #           (ANON_COOKIE), minted on the first message: a claimed address
+  #           would open its owner's hub thread on every app. A browser cannot
+  #           name another person's email or forge another's token. A verified
+  #           POST that still holds the cookie sends both, so the hub folds the
+  #           anonymous thread into the person's; the cookie is then deleted.
+  #   ip      never: request.remote_ip, which the hub caps on.
+  #
+  # The host's ApplicationController is the base, so its session, current_user
+  # and CSRF protection hold: the POST must carry the page's authenticity token
+  # (the composer's form does; the script sends it as X-CSRF-Token). Sign-in is
+  # skipped: a signed-out visitor may chat, as on /build.
+  #
+  # Every answer is JSON and no-store. A hub that is down, slow or misconfigured
+  # is a 503 {error, retry: true}, which the page shows as a friendly retry, and
+  # a failed send or a refused app credential is an ErrorLog row (#capture).
+  class AgentChatsController < ::ApplicationController
+    skip_before_action :require_authentication, raise: false
+    protect_from_forgery with: :exception
+
+    ANON_COOKIE = :studio_agent_chat_anon
+    ANON_TTL = 1.year
+    UNAVAILABLE = "Can't reach the chat right now. Try again in a moment."
+
+    before_action :no_store
+    before_action :resolve_soul
+
+    def create
+      text = params[:text].to_s.strip
+      return render_error("Write a message first.", :unprocessable_entity) if text.empty?
+      if text.length > Studio::AgentChat::MAX_TEXT_LENGTH
+        return render_error("That message is too long (#{Studio::AgentChat::MAX_TEXT_LENGTH} characters at most).",
+                            :unprocessable_entity)
+      end
+
+      who = person(mint: true, fold: true)
+      turn = Studio::AgentChat.post_message(soul: @soul, text: text, person: who, ip: request.remote_ip)
+      # A signed-in post that carried the anon token has folded that thread into
+      # the person's: the token is spent. Kept on any failure, for the retry.
+      cookies.delete(ANON_COOKIE) if who.key?(:email) && who.key?(:anon_token)
+      render json: { turn: turn }, status: :created
+    rescue Studio::AgentChat::Error => e
+      render_hub_error(e)
+    end
+
+    def turns
+      who = person(mint: false)
+      # A visitor who has never sent a message has no thread; the hub need not be asked.
+      return render(json: { turns: [], pending: false }) unless who
+
+      after = params[:after].to_s.presence
+      after = nil if after && !after.match?(/\A[\w-]{1,64}\z/)
+      limit = params[:limit].presence&.to_i || Studio::AgentChat::MAX_LIMIT
+      render json: Studio::AgentChat.turns(soul: @soul, person: who, after: after, limit: limit)
+    rescue Studio::AgentChat::Error => e
+      render_hub_error(e)
+    end
+
+    private
+
+    def no_store
+      response.headers["Cache-Control"] = "no-store"
+    end
+
+    def resolve_soul
+      souls = Studio.agent_chat_soul_list
+      asked = params[:soul].to_s.strip
+      @soul = if asked.empty? then (souls.one? ? souls.first : nil)
+              else souls.find { |soul| soul == asked }
+              end
+      render_error("No chat here.", :not_found) unless @soul
+    end
+
+    # {email:} for a user with a VERIFIED email (#verified_email), else
+    # {anon_token:} from the signed cookie, as for a signed-out visitor. With
+    # mint: false a visitor with no cookie is nil.
+    #
+    # THE FOLD. With fold: true (the POST) a verified user who still holds a
+    # valid anon cookie is {email:, anon_token:}: the hub folds the anonymous
+    # thread into the person's, and #create then deletes the cookie. A verified
+    # user is never minted a token, and GET /turns sends the email alone (the
+    # fold is the hub's job on a post).
+    def person(mint:, fold: false)
+      email = verified_email
+      token = anon_token
+      if email
+        return fold && token ? { email: email, anon_token: token } : { email: email }
+      end
+      return { anon_token: token } if token
+      return nil unless mint
+
+      token = SecureRandom.urlsafe_base64(32)
+      cookies.signed[ANON_COOKIE] = {
+        value: token, expires: ANON_TTL.from_now, httponly: true, same_site: :lax,
+        secure: request.ssl?
+      }
+      { anon_token: token }
+    end
+
+    # The email the hub may know this user by, or nil. The hub keys a person's
+    # threads on it across every app, so a CLAIMED address is never enough: the
+    # profile page saves a new email directly and clears email_verified_at, and
+    # password signup saves any address. The app's Studio.agent_chat_verified_email
+    # hook decides when set; otherwise only a user whose email_verified_at is
+    # present (the magic link stamps it; so does the host from_omniauth pattern
+    # in docs/GOOGLE_AUTH_SETUP.md) counts. Anyone else chats as an
+    # anonymous visitor.
+    def verified_email
+      user = respond_to?(:current_user, true) ? current_user : nil
+      return nil unless user
+
+      hook = Studio.agent_chat_verified_email
+      email = if hook.respond_to?(:call) then hook.call(user)
+              elsif user.respond_to?(:email_verified_at) && user.email_verified_at.present? && user.respond_to?(:email)
+                user.email
+              end
+      email.to_s.strip.presence
+    end
+
+    # The token in the signed anon cookie, or nil when there is none or it is
+    # not one this app minted.
+    def anon_token
+      token = cookies.signed[ANON_COOKIE].to_s
+      token.match?(/\A[A-Za-z0-9_-]{32,64}\z/) ? token : nil
+    end
+
+    def render_hub_error(error)
+      case error
+      when Studio::AgentChat::Invalid then render_error(error.message, :unprocessable_entity)
+      when Studio::AgentChat::Capped
+        response.headers["Retry-After"] = error.retry_after.to_s if error.retry_after
+        render_error("You've sent a lot of messages. Wait a little, then try again.", :too_many_requests,
+                     retry_after: error.retry_after)
+      when Studio::AgentChat::UnknownSoul then render_error("No chat here.", :not_found)
+      else
+        Rails.logger.warn("[studio] agent chat: #{error.class}: #{error.message}")
+        capture(error) if error.is_a?(Studio::AgentChat::Unauthorized) || action_name == "create"
+        render_error(UNAVAILABLE, :service_unavailable, retry: true)
+      end
+    end
+
+    # An ErrorLog row for a message that could not be sent, and for every
+    # refusal of the app's own credential (a configuration fault). A poll that
+    # fails is only logged: an open page polls every 15 seconds while the hub is
+    # down, and a row per poll would bury the outage it reports. Never raises.
+    def capture(error)
+      ::ErrorLog.capture!(error) if defined?(::ErrorLog) && ::ErrorLog.respond_to?(:capture!)
+    rescue StandardError
+      nil
+    end
+
+    def render_error(message, status, **extra)
+      render json: { error: message, **extra }, status: status
+    end
+  end
+end

data/app/javascript/studio/agent_chat.js

@@ -0,0 +1,286 @@
+// studio/agent_chat: the shared agent chat's thread (studio/agent_chat/_chat;
+// docs/AGENT_CHAT.md). The hub holds the conversation; this page asks its own
+// app for it (GET /agent_chat/turns, POST /agent_chat/messages), which proxies.
+//
+// The look is the ERB: each turn is a clone of a <template data-agent-chat-template>
+// (studio/agent_chat/_turn), filled with textContent, never HTML.
+//
+//   LOAD     on connect, the thread's latest turns; a failure shows the offline
+//            notice with Try again (and retries itself, slowly).
+//   POLL     answers arrive by polling, as on the hub's /build: every POLL_MS
+//            while an answer is pending, slowing to SLOW_MS once it has waited
+//            SLOW_AFTER_MS (a hub that is down is not hammered); every IDLE_MS
+//            otherwise, and not at all while the tab is hidden (it asks at once
+//            when the tab comes back). Each poll asks
+//            for turns AFTER the last settled one (afterCursor), so a turn still
+//            pending is asked about again until it settles.
+//   SEND     Enter sends, Shift+Enter is a new line. The words stay in the box
+//            until the app answers 201; a refusal shows its reason above them.
+//   FOLLOW   the thread stays at its end while the reader is within FOLLOW_PX of
+//            it, and always after their own send (the hub's chat_follow rule).
+//   TYPING   the typing line shows while the hub says an answer is pending:
+//            "thinking", then "typing" once a turn's status is "typing".
+//
+// It imports nothing, so test/javascript/agent_chat.test.mjs loads it as a
+// data: module; studio/controllers/agent_chat_controller mounts it.
+
+export const POLL_MS = 2500
+export const SLOW_MS = 10000
+export const SLOW_AFTER_MS = 120000
+export const IDLE_MS = 30000
+export const OFFLINE_MS = 15000
+export const FOLLOW_PX = 20
+export const LIMIT = 50
+const UNSETTLED = new Set(["pending", "typing"])
+
+export function settled(turn) {
+  return !UNSETTLED.has(String(turn && turn.status))
+}
+
+// A turn's identity is its id AND its role: the hub answers one message row as
+// two turns with the row's id, the visitor's words ("user") and, once answered,
+// the agent's ("agent"). Keyed by id alone, the answer would replace the words.
+export function turnKey(turn) {
+  return `${turn.id}:${turn.role === "agent" ? "agent" : "user"}`
+}
+
+// Merge `incoming` turns into `turns` (both oldest first): a known (id, role) is
+// replaced in place. A new agent turn goes right after its own user turn (same
+// id), so when the visitor sends A then B before A is answered, A's answer sits
+// under A, not under B. Any other new turn is appended. Returns a new array.
+export function mergeTurns(turns, incoming) {
+  const merged = turns.slice()
+  for (const turn of incoming || []) {
+    if (!turn || turn.id == null) continue
+    const key = turnKey(turn)
+    const at = merged.findIndex((known) => turnKey(known) === key)
+    if (at !== -1) { merged[at] = turn; continue }
+    const own = turn.role === "agent" ? merged.findIndex((known) => turnKey(known) === `${turn.id}:user`) : -1
+    if (own !== -1) merged.splice(own + 1, 0, turn)
+    else merged.push(turn)
+  }
+  return merged
+}
+
+// The `after` a poll sends: the id of the last turn before the first one still
+// unsettled (so that one is asked about again), or of the last turn when all
+// are settled. null asks for the latest turns. `after` is a hub ROW id (rows
+// with id > after): an unsettled row's user turn is itself unsettled, so the
+// cursor lands on an earlier row and the pending row is asked about again.
+export function afterCursor(turns) {
+  const first = turns.findIndex((turn) => !settled(turn))
+  if (first === -1) return turns.length ? String(turns[turns.length - 1].id) : null
+  return first === 0 ? null : String(turns[first - 1].id)
+}
+
+// Milliseconds to the next poll.
+export function pollDelay({ waiting, waitingSince, now, offline }) {
+  if (offline) return OFFLINE_MS
+  if (!waiting) return IDLE_MS
+  return now - (waitingSince ?? now) > SLOW_AFTER_MS ? SLOW_MS : POLL_MS
+}
+
+export function typingPhase(turns) {
+  return turns.some((turn) => turn.status === "typing") ? "typing" : "thinking"
+}
+
+export function isFollowing(log, px = FOLLOW_PX) {
+  return log.scrollHeight - log.clientHeight - log.scrollTop <= px
+}
+
+// The page's authenticity token: the form's own field, else the csrf meta.
+export function csrfToken(form, doc = globalThis.document) {
+  const field = form && form.querySelector("input[name='authenticity_token']")
+  if (field && field.value) return field.value
+  const meta = doc && doc.querySelector("meta[name='csrf-token']")
+  return meta ? meta.getAttribute("content") : null
+}
+
+export function turnsUrl(base, { soul, after, limit = LIMIT }) {
+  const params = new URLSearchParams({ soul, limit: String(limit) })
+  if (after != null) params.set("after", after)
+  return `${base}${base.includes("?") ? "&" : "?"}${params}`
+}
+
+export function mountAgentChat(root, {
+  fetch: fetcher = globalThis.fetch.bind(globalThis),
+  doc = globalThis.document,
+  now = () => Date.now(),
+  setTimer = (fn, ms) => globalThis.setTimeout(fn, ms),
+  clearTimer = (id) => globalThis.clearTimeout(id)
+} = {}) {
+  const $ = (selector) => root.querySelector(selector)
+  const log = $("[data-agent-chat-log]")
+  const typing = $("[data-agent-chat-typing]")
+  const phase = $("[data-agent-chat-phase]")
+  const offlineNote = $("[data-agent-chat-offline]")
+  const retry = $("[data-agent-chat-retry]")
+  const form = $("[data-agent-chat-form]")
+  const input = $("[data-agent-chat-input]")
+  const send = $("[data-agent-chat-send]")
+  const error = $("[data-agent-chat-error]")
+  const status = $("[data-agent-chat-status]")
+  const soul = root.dataset.agentChatSoul
+  const name = root.dataset.agentChatName || "The agent"
+
+  const state = { turns: [], pending: false, waitingSince: null, offline: false, inFlight: false, sending: false, timer: null, alive: true, following: true }
+
+  const onScroll = () => { state.following = isFollowing(log) }
+  log.addEventListener("scroll", onScroll, { passive: true })
+
+  function toEnd() { log.scrollTop = log.scrollHeight }
+
+  function setOffline(offline) {
+    state.offline = offline
+    if (offlineNote) offlineNote.hidden = !offline
+  }
+
+  function showError(text) {
+    if (!error) return
+    error.textContent = text || ""
+    error.hidden = !text
+  }
+
+  function render() {
+    const follow = state.following
+    for (const turn of state.turns) {
+      const key = turnKey(turn)
+      let node = Array.from(log.querySelectorAll("[data-turn-key]")).find((el) => el.dataset.turnKey === key)
+      if (!node) {
+        const template = root.querySelector(`template[data-agent-chat-template="${turn.role === "agent" ? "agent" : "user"}"]`)
+        if (!template) continue
+        node = template.content.firstElementChild.cloneNode(true)
+        node.dataset.turnId = String(turn.id)
+        node.dataset.turnKey = key
+        // Placed where mergeTurns put it: after the previous turn's element.
+        const index = state.turns.indexOf(turn)
+        const prevKey = index > 0 ? turnKey(state.turns[index - 1]) : null
+        const prev = prevKey && Array.from(log.querySelectorAll("[data-turn-key]")).find((el) => el.dataset.turnKey === prevKey)
+        if (prev) prev.after(node)
+        else log.appendChild(node)
+      }
+      node.dataset.status = turn.status || ""
+      const text = node.querySelector("[data-agent-chat-text]")
+      if (text && text.textContent !== String(turn.text ?? "")) text.textContent = String(turn.text ?? "")
+      const failed = node.querySelector("[data-agent-chat-failed]")
+      if (failed) failed.hidden = turn.status !== "failed"
+    }
+    const waiting = state.pending || state.turns.some((turn) => !settled(turn))
+    if (typing) typing.hidden = !waiting
+    if (phase) phase.dataset.phase = typingPhase(state.turns)
+    if (follow) toEnd()
+  }
+
+  function schedule() {
+    if (!state.alive) return
+    clearTimer(state.timer)
+    const waiting = state.pending || state.turns.some((turn) => !settled(turn))
+    if (waiting) state.waitingSince = state.waitingSince || now()
+    else state.waitingSince = null
+    state.timer = setTimer(poll, pollDelay({ waiting, waitingSince: state.waitingSince, now: now(), offline: state.offline }))
+  }
+
+  async function poll() {
+    if (!state.alive) return
+    const hidden = doc && doc.visibilityState === "hidden"
+    if (hidden || state.inFlight) { schedule(); return }
+    state.inFlight = true
+    try {
+      const response = await fetcher(turnsUrl(root.dataset.agentChatTurnsUrl, { soul, after: afterCursor(state.turns) }), {
+        headers: { Accept: "application/json" }, credentials: "same-origin"
+      })
+      if (!response.ok) throw new Error(`turns ${response.status}`)
+      const data = await response.json()
+      state.turns = mergeTurns(state.turns, data.turns)
+      state.pending = data.pending === true
+      setOffline(false)
+      render()
+    } catch (_error) {
+      setOffline(true)
+    } finally {
+      state.inFlight = false
+      schedule()
+    }
+  }
+
+  async function submit(event) {
+    if (event) event.preventDefault()
+    const text = (input.value || "").trim()
+    if (!text || state.sending) return
+    state.sending = true
+    if (send) send.disabled = true
+    showError("")
+    if (status) status.textContent = `Sending to ${name}…`
+    try {
+      const headers = { Accept: "application/json", "Content-Type": "application/json" }
+      const token = csrfToken(form, doc)
+      if (token) headers["X-CSRF-Token"] = token
+      const response = await fetcher(form.getAttribute("action"), {
+        method: "POST", headers, credentials: "same-origin", body: JSON.stringify({ soul, text })
+      })
+      let data = {}
+      try { data = await response.json() } catch (_e) { data = {} }
+      if (response.status === 201 && data.turn) {
+        input.value = ""
+        state.turns = mergeTurns(state.turns, [data.turn])
+        state.pending = true
+        state.following = true
+        setOffline(false)
+        render()
+        toEnd()
+        if (status) status.textContent = "Sent."
+        state.waitingSince = now()
+        clearTimer(state.timer)
+        state.timer = setTimer(poll, POLL_MS)
+      } else {
+        showError(data.error || `Couldn't send that to ${name}. Try again.`)
+        if (status) status.textContent = ""
+      }
+    } catch (_error) {
+      showError(`Can't reach ${name} right now. Your message is still here; try again in a moment.`)
+      if (status) status.textContent = ""
+    } finally {
+      state.sending = false
+      if (send) send.disabled = false
+    }
+  }
+
+  function onKeydown(event) {
+    if (event.key !== "Enter" || event.shiftKey || event.isComposing) return
+    event.preventDefault()
+    submit()
+  }
+
+  function onRetry() {
+    clearTimer(state.timer)
+    poll()
+  }
+
+  // A tab that comes back asks at once rather than waiting out an idle poll.
+  function onVisible() {
+    if (doc && doc.visibilityState === "visible" && !state.inFlight) { clearTimer(state.timer); poll() }
+  }
+
+  form && form.addEventListener("submit", submit)
+  input && input.addEventListener("keydown", onKeydown)
+  retry && retry.addEventListener("click", onRetry)
+  doc && doc.addEventListener && doc.addEventListener("visibilitychange", onVisible)
+  root.dataset.agentChatReady = "true"
+  poll()
+
+  return {
+    state,
+    poll,
+    submit,
+    destroy() {
+      state.alive = false
+      clearTimer(state.timer)
+      log.removeEventListener("scroll", onScroll)
+      form && form.removeEventListener("submit", submit)
+      input && input.removeEventListener("keydown", onKeydown)
+      retry && retry.removeEventListener("click", onRetry)
+      doc && doc.removeEventListener && doc.removeEventListener("visibilitychange", onVisible)
+      delete root.dataset.agentChatReady
+    }
+  }
+}

data/app/javascript/studio/controllers/agent_chat_controller.js

@@ -0,0 +1,20 @@
+// agent-chat: the shared agent chat (studio/agent_chat/_chat), on the engine's
+// Stimulus application (studio/stimulus registers it lazily, the first time a
+// page renders a chat). It sits on the chat's section:
+//
+//   <section data-studio-controller="agent-chat" data-agent-chat-soul="alex" ...>
+//
+// The loading, polling, sending and following are studio/agent_chat.
+import { Controller } from "@hotwired/stimulus"
+import { mountAgentChat } from "studio/agent_chat"
+
+export default class extends Controller {
+  connect() {
+    this.chat = mountAgentChat(this.element)
+  }
+
+  disconnect() {
+    if (this.chat) this.chat.destroy()
+    this.chat = null
+  }
+}

data/app/javascript/studio/stimulus.js

@@ -55,7 +55,9 @@ export const schema = {
 // board whose controller failed still renders, counts and toasts, and says that
 // its cards do not drag (data-studio-controller-failed="board"). So is the
 // knowledge transcript: a recording whose controller failed still plays from
-// its own controls, and its page says that click-to-play did not load.
+// its own controls, and its page says that click-to-play did not load. So is the
+// agent chat: a chat whose controller failed still renders, and its section
+// carries data-studio-controller-failed="agent-chat".
 export const LAZY = {
   "board": () => import("studio/controllers/board_controller"),
   "geo-settings": () => import("studio/controllers/geo_settings_controller"),
@@ -64,7 +66,8 @@ export const LAZY = {
   "booking": () => import("studio/controllers/booking_controller"),
   "footer-map": () => import("studio/controllers/footer_map_controller"),
   "survey": () => import("studio/controllers/survey_controller"),
-  "knowledge-transcript": () => import("studio/controllers/knowledge_transcript_controller")
+  "knowledge-transcript": () => import("studio/controllers/knowledge_transcript_controller"),
+  "agent-chat": () => import("studio/controllers/agent_chat_controller")
 }
 
 export const application = Application.start(document.documentElement, schema)

data/app/views/studio/agent_chat/_chat.html.erb

@@ -0,0 +1,52 @@
+<%# locals: (soul:, name:, portrait: nil, role: nil, empty: nil, cards: nil) %>
+<%#
+  The shared agent chat (docs/AGENT_CHAT.md): one conversation with one agent,
+  held by the hub, on any app's page.
+
+    render "studio/agent_chat/chat", soul: "alex", name: "Alex", portrait: image_tag("alex.png", class: "w-24 h-24 rounded-full")
+
+  soul      the agent's slug; must be on the app's Studio.agent_chat_souls.
+  name      the agent's display name (header, composer, typing line).
+  portrait  ready markup for the big round portrait; nil shows the initial.
+  role      ready markup or text under the name.
+  empty     the line an empty thread shows (default "Say hello to <name>.").
+  cards     THE CARD SLOT: ready markup shown between the header and the
+            thread (/build's intake cards). A local, never a bare yield: a
+            partial rendered without a block yields the LAYOUT's body.
+
+  Top to bottom, as the hub's /build: the portrait and name, the card slot, the
+  thread, the typing line, the offline notice and the composer. The thread is
+  drawn by studio/agent_chat (the "agent-chat" controller, loaded lazily) from
+  the two <template>s below, which are studio/agent_chat/_turn: the look lives
+  here, in ERB, and the script only fills it. ONE PAGE HOLDS ONE CHAT.
+%>
+<% souls = Studio.agent_chat_soul_list %>
+<% raise ArgumentError, "studio/agent_chat/chat: soul #{soul.inspect} is not in Studio.agent_chat_souls (#{souls.inspect})" unless souls.include?(soul.to_s) %>
+<section class="w-full max-w-3xl mx-auto px-4 pt-4 sm:pt-8 flex flex-col gap-6 min-w-0"
+         data-studio-controller="agent-chat" data-test="agent-chat"
+         data-agent-chat-soul="<%= soul %>" data-agent-chat-name="<%= name %>"
+         data-agent-chat-messages-url="<%= studio_agent_chat_messages_path %>"
+         data-agent-chat-turns-url="<%= studio_agent_chat_turns_path %>">
+  <%= render "studio/agent_chat/header", name: name, portrait: portrait, role: role %>
+  <% if cards.present? %>
+    <div class="flex flex-col gap-3 min-w-0" data-agent-chat-cards data-test="agent-chat-cards"><%= cards %></div>
+  <% end %>
+  <div class="flex flex-col gap-3 min-w-0">
+    <div role="log" aria-live="polite" aria-label="Conversation with <%= name %>"
+         class="flex flex-col gap-4 px-1 py-2 overflow-y-auto overscroll-contain max-h-[60vh] min-w-0"
+         data-agent-chat-log data-test="agent-chat-messages">
+      <p class="hidden only:block text-center text-secondary text-sm py-6" data-test="agent-chat-empty"><%= empty.presence || "Say hello to #{name}." %></p>
+    </div>
+    <div class="px-1" data-agent-chat-typing hidden data-test="agent-chat-typing-slot">
+      <%= render "studio/agent_chat/typing", name: name, portrait: portrait %>
+    </div>
+    <div class="rounded-2xl border border-subtle bg-inset px-4 py-3 flex flex-wrap items-center justify-between gap-3"
+         role="alert" data-agent-chat-offline hidden data-test="agent-chat-offline">
+      <p class="text-sm text-body min-w-0">Can't reach <%= name %> right now. Your messages are safe; try again in a moment.</p>
+      <button type="button" class="btn btn-secondary btn-sm shrink-0" data-agent-chat-retry data-test="agent-chat-retry">Try again</button>
+    </div>
+    <%= render "studio/agent_chat/form", soul: soul, name: name %>
+  </div>
+  <template data-agent-chat-template="user"><%= render "studio/agent_chat/turn", turn: { "role" => "user" }, name: name %></template>
+  <template data-agent-chat-template="agent"><%= render "studio/agent_chat/turn", turn: { "role" => "agent" }, name: name %></template>
+</section>

data/app/views/studio/agent_chat/_form.html.erb

@@ -0,0 +1,23 @@
+<%# locals: (soul:, name:) %>
+<%# The chat's composer (studio/agent_chat/_chat), as the hub's agent_chats/_form: the text over a round send button at its bottom right, sticky at the window's bottom. Enter sends; Shift+Enter is a new line (studio/agent_chat). It posts to POST /agent_chat/messages with the page's authenticity token (form_with adds it; the script sends it as X-CSRF-Token). A send that fails keeps the words in the box and says why above them. %>
+<%= form_with url: studio_agent_chat_messages_path, method: :post, local: true,
+              html: { style: "view-transition-name: agent-composer;" },
+              class: "sticky bottom-3 z-10 rounded-3xl border border-subtle bg-surface shadow-lg focus-within:border-primary transition-colors p-2 flex flex-col gap-2",
+              data: { agent_chat_form: true, turbo: false, test: "agent-chat-form" } do |f| %>
+  <%= hidden_field_tag :soul, soul, id: nil %>
+  <p class="px-3 pt-1 text-xs text-danger-ink" role="alert" data-agent-chat-error hidden data-test="agent-chat-error"></p>
+  <p class="sr-only" role="status" aria-live="polite" data-agent-chat-status data-test="agent-chat-status"></p>
+  <div class="relative">
+    <%= label_tag :studio_agent_chat_text, "Message #{name}", class: "sr-only" %>
+    <%= text_area_tag :text, nil, id: "studio_agent_chat_text", rows: 2, maxlength: Studio::AgentChat::MAX_TEXT_LENGTH, required: true,
+                      placeholder: "Message #{name}…", autocomplete: "off",
+                      class: "block w-full min-w-0 resize-none bg-transparent pl-3 pr-14 py-2 text-base text-heading placeholder:text-muted focus:outline-none",
+                      data: { agent_chat_input: true, test: "agent-chat-input" } %>
+    <button type="submit" class="absolute bottom-1 right-1 inline-flex h-10 w-10 items-center justify-center rounded-full bg-primary text-white disabled:opacity-40"
+            aria-label="Send to <%= name %>" data-agent-chat-send data-test="agent-chat-send">
+      <svg viewBox="0 0 24 24" class="h-5 w-5" fill="none" stroke="currentColor" stroke-width="2.2" stroke-linecap="round" stroke-linejoin="round" aria-hidden="true">
+        <path d="M12 19V5M5 12l7-7 7 7"/>
+      </svg>
+    </button>
+  </div>
+<% end %>

data/app/views/studio/agent_chat/_header.html.erb

@@ -0,0 +1,14 @@
+<%# locals: (name:, portrait: nil, role: nil) %>
+<%# The chat's head (studio/agent_chat/_chat): the agent's portrait, a big circle centered on top, its name and role under it. `portrait` is ready markup; with none, the name's initial on a plain circle. The portrait keeps one view-transition name, as on the hub's agent pages. %>
+<div class="flex flex-col items-center gap-2 text-center min-w-0" data-test="agent-chat-header" data-agent-name="<%= name %>">
+  <div class="rounded-full shadow-md overflow-hidden" style="view-transition-name: agent-portrait;" data-test="agent-chat-portrait">
+    <% if portrait.present? %>
+      <%= portrait %>
+    <% else %>
+      <span class="w-24 h-24 text-3xl rounded-full flex items-center justify-center bg-inset border border-subtle text-heading font-bold" aria-hidden="true"><%= name.to_s.first.to_s.upcase %></span>
+    <% end %>
+  </div>
+  <p class="text-sm text-secondary break-words" data-test="agent-chat-caption">
+    <span class="font-semibold text-heading"><%= name %></span><% if role.present? %> · <%= role %><% end %>
+  </p>
+</div>

data/app/views/studio/agent_chat/_turn.html.erb

@@ -0,0 +1,19 @@
+<%# locals: (turn:, name:) %>
+<%# One turn of the chat (studio/agent_chat/_chat), from a hub turn {id, role, text, status}, identified by its id AND role (data-turn-key "<id>:<role>"): the hub answers one message row as a user turn and an agent turn sharing the row's id. The page renders it twice, blank, as the <template>s studio/agent_chat clones; a host may also render real turns with it. The visitor's words sit in a right-hand bubble; the agent's are plain text across the thread (as the hub's agent-reply), its name kept for a screen reader. Text only, never HTML: the script sets textContent. A failed turn says so. %>
+<% agent = turn["role"].to_s == "agent" %>
+<% status = turn["status"].to_s %>
+<div class="flex flex-col gap-2 min-w-0" data-agent-chat-turn data-role="<%= agent ? "agent" : "user" %>"
+     data-status="<%= status %>" data-turn-id="<%= turn["id"] %>"
+     data-turn-key="<%= "#{turn["id"]}:#{agent ? "agent" : "user"}" if turn["id"].present? %>" data-test="agent-chat-turn">
+  <% if agent %>
+    <div class="self-stretch min-w-0" data-test="agent-chat-reply">
+      <p class="sr-only"><%= name %>:</p>
+      <div class="text-body text-[0.9375rem] leading-relaxed whitespace-pre-wrap break-words" data-agent-chat-text><%= turn["text"] %></div>
+    </div>
+  <% else %>
+    <div class="self-end max-w-[85%] rounded-2xl rounded-br-sm px-3 py-2 bg-primary/15 text-primary-ink text-sm whitespace-pre-wrap break-words"
+         data-agent-chat-text data-test="agent-chat-sent"><%= turn["text"] %></div>
+  <% end %>
+  <p class="<%= agent ? "self-start" : "self-end" %> text-xs text-danger-ink" data-agent-chat-failed data-test="agent-chat-failed"
+     <%= "hidden" unless status == "failed" %>><%= name %> could not answer this one. Send it again.</p>
+</div>

data/app/views/studio/agent_chat/_typing.html.erb

@@ -0,0 +1,18 @@
+<%# locals: (name:, portrait: nil) %>
+<%# A pending answer (studio/agent_chat/_chat), as the hub's agent_chats/_typing: THINKING (a small portrait in a turning ring, "<name> is thinking" shimmering) until the hub says the answer has begun, then TYPING (a bubble of wave dots). Both are drawn in one grid cell so the swap never moves the page; data-phase picks one (studio/agent_chat sets it). The motion is engine-motion.css (.studio-agent-typing) and holds still under reduced motion. %>
+<div class="studio-agent-typing" data-phase="thinking" data-agent-chat-phase data-test="agent-chat-typing">
+  <div class="studio-agent-typing-layer studio-agent-typing-thinks" data-test="agent-chat-thinking">
+    <span class="studio-agent-typing-orbit" aria-hidden="true">
+      <span class="w-10 h-10 text-sm rounded-full flex items-center justify-center bg-inset border border-subtle text-heading font-bold shrink-0 overflow-hidden [&>img]:w-full [&>img]:h-full [&>img]:object-cover [&>svg]:w-full [&>svg]:h-full">
+        <% if portrait.present? %><%= portrait %><% else %><%= name.to_s.first.to_s.upcase %><% end %>
+      </span>
+    </span>
+    <span class="studio-agent-typing-label studio-agent-typing-shimmer"><%= name %> is thinking</span>
+  </div>
+  <div class="studio-agent-typing-layer studio-agent-typing-types" data-test="agent-chat-typing-bubble">
+    <span class="studio-agent-typing-bubble" aria-hidden="true">
+      <span class="studio-agent-typing-dot"></span><span class="studio-agent-typing-dot"></span><span class="studio-agent-typing-dot"></span>
+    </span>
+    <span class="studio-agent-typing-label"><%= name %> is typing</span>
+  </div>
+</div>

data/lib/studio/agent_chat.rb

@@ -0,0 +1,216 @@
+# frozen_string_literal: true
+
+require "json"
+require "net/http"
+require "openssl"
+require "uri"
+require "zlib"
+require "active_support/core_ext/object/blank"
+require "active_support/core_ext/object/to_query"
+
+module Studio
+  # The hub client behind the shared agent chat (docs/AGENT_CHAT.md). An app
+  # never stores a chat message: the McRitchie Studio hub holds every thread,
+  # one per (person, soul), and this client is the app's server talking to it.
+  # The browser only ever talks to its own app (Studio::AgentChatsController).
+  #
+  # THE CONTRACT (.agents/epics/agent-chat-primitive.md, "Contract"):
+  #
+  #   POST /api/v1/agent_chat/messages  soul, text, person, ip
+  #        201 {turn} · 422 {error} · 429 capped · 404 soul has no web chat
+  #   GET  /api/v1/agent_chat/turns     soul, person, after, limit (<= 50)
+  #        200 {turns: [...], pending: bool}
+  #
+  # `person` is {email:} for a signed-in user, else {anon_token:}; a signed-in
+  # POST that still holds the visitor's anon token sends {email:, anon_token:},
+  # and the hub folds the anonymous thread into the person's. A turn is
+  # {id, role: "user"|"agent", text, created_at, status} with status
+  # pending|typing|answered|failed.
+  #
+  # AUTHENTICATION is the APP's own bearer credential (Studio.agent_chat_token,
+  # else ENV["AGENT_CHAT_TOKEN"]), never a user's. It is sent only over TLS: a
+  # plain-http hub URL is refused unless its host is this machine (a developer
+  # pointing at a local hub).
+  #
+  # EVERY CALL IS BOUNDED: OPEN_TIMEOUT to connect and finish TLS, then
+  # READ_TIMEOUT (and WRITE_TIMEOUT) per socket operation; Net::HTTP's silent
+  # retry of an idempotent request is off, so a GET costs at most one wait.
+  #
+  # ERRORS. Every failure is a Studio::AgentChat::Error, so a caller rescues one
+  # class; the subclasses say what the visitor is told:
+  #
+  #   Unavailable   the hub could not be reached or answered 5xx / garbage, or
+  #                 the app is not configured (no token, a bad URL). "Try again."
+  #   Unauthorized  401/403: the hub refused THIS APP's credential. A
+  #                 configuration fault, shown to the visitor as Unavailable.
+  #   UnknownSoul   404: the hub has no web chat for that soul for this app.
+  #   Invalid       422: the hub refused the message; #message is its reason.
+  #   Capped        429: too many messages; #retry_after is seconds, or nil.
+  module AgentChat
+    class Error < StandardError
+      attr_reader :status
+
+      def initialize(message = nil, status: nil)
+        super(message)
+        @status = status
+      end
+    end
+
+    class Unavailable < Error; end
+    class Unauthorized < Error; end
+    class UnknownSoul < Error; end
+    class Invalid < Error; end
+
+    class Capped < Error
+      attr_reader :retry_after
+
+      def initialize(message = nil, status: 429, retry_after: nil)
+        super(message, status: status)
+        @retry_after = retry_after
+      end
+    end
+
+    MESSAGES_PATH = "/api/v1/agent_chat/messages"
+    TURNS_PATH = "/api/v1/agent_chat/turns"
+    # Seconds to open the connection and finish TLS.
+    OPEN_TIMEOUT = 3
+    # Seconds for any one read or write once connected. A post returns as soon
+    # as the hub has stored the message; the agent's answer arrives by polling.
+    READ_TIMEOUT = 8
+    WRITE_TIMEOUT = 8
+    MAX_LIMIT = 50
+    # The longest message the app forwards; the hub may refuse a shorter one.
+    MAX_TEXT_LENGTH = 4_000
+    # A hub answer larger than this is not a chat answer.
+    MAX_BODY_BYTES = 1_048_576
+    LOOPBACK_HOSTS = %w[localhost 127.0.0.1 ::1 [::1]].freeze
+    NETWORK_ERRORS = [
+      Net::OpenTimeout, Net::ReadTimeout, Net::WriteTimeout, Timeout::Error,
+      SocketError, SystemCallError, IOError, EOFError, OpenSSL::SSL::SSLError,
+      Net::HTTPBadResponse, Net::ProtocolError, Zlib::Error
+    ].freeze
+
+    class << self
+      # Stores one message from `person` to `soul` and answers its turn (a Hash
+      # with string keys). Raises a Studio::AgentChat::Error.
+      def post_message(soul:, text:, person:, ip: nil)
+        body = { soul: soul.to_s, text: text.to_s, person: person_param(person), ip: ip.to_s.presence }.compact
+        payload = request(:post, MESSAGES_PATH, body: body)
+        turn = payload.is_a?(Hash) && payload["turn"].is_a?(Hash) ? payload["turn"] : payload
+        raise Unavailable.new("the hub answered with no turn", status: 201) unless turn.is_a?(Hash)
+
+        turn
+      end
+
+      # The thread's turns after `after` (a turn id; nil for the latest), and
+      # whether an answer is still pending: {"turns" => [...], "pending" => bool}.
+      def turns(soul:, person:, after: nil, limit: MAX_LIMIT)
+        query = { soul: soul.to_s, person: person_param(person), limit: limit.to_i.clamp(1, MAX_LIMIT) }
+        query[:after] = after.to_s if after.present?
+        payload = request(:get, TURNS_PATH, query: query)
+        raise Unavailable.new("the hub answered with no turns", status: 200) unless payload.is_a?(Hash) && payload["turns"].is_a?(Array)
+
+        { "turns" => payload["turns"].select { |turn| turn.is_a?(Hash) }, "pending" => payload["pending"] == true }
+      end
+
+      def hub_url = Studio.agent_chat_hub_url.to_s
+      def token = Studio.agent_chat_token.presence || ENV["AGENT_CHAT_TOKEN"].presence
+
+      private
+
+      # {email:}, {anon_token:}, or both: a signed-in post that still holds the
+      # visitor's anon token sends both, and the hub folds that anonymous thread
+      # into the person's.
+      def person_param(person)
+        person = person.to_h.transform_keys(&:to_s)
+        email = person["email"].to_s.strip
+        token = person["anon_token"].to_s.strip
+        raise ArgumentError, "person needs an email or an anon_token" if email.empty? && token.empty?
+
+        { email: email.presence, anon_token: token.presence }.compact
+      end
+
+      def request(verb, path, body: nil, query: nil)
+        uri = endpoint(path)
+        uri.query = query.to_query if query
+        credential = token || raise(Unavailable, "no AGENT_CHAT_TOKEN: the app has no agent chat credential")
+
+        req = verb == :post ? Net::HTTP::Post.new(uri) : Net::HTTP::Get.new(uri)
+        req["Authorization"] = "Bearer #{credential}"
+        req["Accept"] = "application/json"
+        req["User-Agent"] = "studio-engine/#{Studio::VERSION} agent-chat"
+        if body
+          req["Content-Type"] = "application/json"
+          req.body = JSON.generate(body)
+        end
+
+        response = http_for(uri).start { |http| http.request(req) }
+        interpret(response)
+      rescue *NETWORK_ERRORS => e
+        raise Unavailable, "the hub could not be reached (#{e.class})"
+      end
+
+      def endpoint(path)
+        base = URI.parse(hub_url)
+        raise Unavailable, "agent_chat_hub_url is not an http(s) URL" unless base.is_a?(URI::HTTP) && base.host.present?
+        if base.scheme != "https" && !LOOPBACK_HOSTS.include?(base.host)
+          raise Unavailable, "agent_chat_hub_url must be https (plain http only to this machine)"
+        end
+
+        URI.join(base.to_s.end_with?("/") ? base.to_s : "#{base}/", path.delete_prefix("/"))
+      rescue URI::InvalidURIError
+        raise Unavailable, "agent_chat_hub_url is not a URL"
+      end
+
+      def http_for(uri)
+        http = Net::HTTP.new(uri.host, uri.port)
+        http.use_ssl = uri.scheme == "https"
+        http.verify_mode = OpenSSL::SSL::VERIFY_PEER if http.use_ssl?
+        http.open_timeout = OPEN_TIMEOUT
+        http.read_timeout = READ_TIMEOUT
+        http.write_timeout = WRITE_TIMEOUT
+        http.ssl_timeout = OPEN_TIMEOUT if http.use_ssl?
+        http.max_retries = 0
+        http
+      end
+
+      def interpret(response)
+        status = response.code.to_i
+        success = status.between?(200, 299)
+        payload = success ? parse(response.body) : parse_reason(response.body)
+        reason = payload.is_a?(Hash) ? payload["error"].presence : nil
+
+        case status
+        when 200..299 then payload
+        when 401, 403 then raise Unauthorized.new("the hub refused this app's credential (#{status})", status: status)
+        when 404 then raise UnknownSoul.new(reason || "no web chat for that soul", status: status)
+        when 422 then raise Invalid.new(reason || "the hub refused that message", status: status)
+        when 429 then raise Capped.new(reason || "too many messages", retry_after: retry_after(response))
+        else raise Unavailable.new("the hub answered #{status}", status: status)
+        end
+      end
+
+      def parse(body)
+        return nil if body.nil? || body.empty?
+        raise Unavailable, "the hub's answer is too large" if body.bytesize > MAX_BODY_BYTES
+
+        JSON.parse(body)
+      rescue JSON::ParserError
+        raise Unavailable, "the hub's answer is not JSON"
+      end
+
+      # A refusal's body, read only for its {"error"} reason; a body that is not
+      # JSON (a proxy's HTML error page) is no reason.
+      def parse_reason(body)
+        parse(body)
+      rescue Unavailable
+        nil
+      end
+
+      def retry_after(response)
+        value = response["Retry-After"].to_s
+        value.match?(/\A\d+\z/) ? value.to_i : nil
+      end
+    end
+  end
+end

data/lib/studio/version.rb

@@ -1,3 +1,3 @@
 module Studio
-  VERSION = "0.115.4.rc1"
+  VERSION = "0.116.0.rc1"
 end

data/lib/studio.rb

@@ -47,6 +47,7 @@ require "studio/profile_image"
 require "studio/oauth_identity"
 require "studio/newsletter"
 require "studio/health_report"
+require "studio/agent_chat"
 require "studio/username_generator"
 require "studio/public_user"
 require "studio/name_parts"
@@ -1313,6 +1314,34 @@ module Studio
   mattr_accessor :draw_knowledge_routes, default: false
   mattr_accessor :knowledge_agents,      default: []
 
+  # The shared agent chat (docs/AGENT_CHAT.md): `render "studio/agent_chat/chat",
+  # soul:, name:, portrait:` on any page, answered by the hub's agents. The hub
+  # holds every thread; the app's server proxies the browser's two calls
+  # (Studio::AgentChatsController, Studio::AgentChat).
+  #
+  # agent_chat_souls is the app's ALLOW-LIST of agent slugs a page may chat
+  # with (e.g. %w[alex]). It is the gate: an app that names no soul draws no
+  # /agent_chat routes, and a request naming a soul off the list is a 404. The
+  # browser's `soul` is never trusted beyond it, and the hub re-checks that this
+  # app may address that soul.
+  mattr_accessor :agent_chat_souls,   default: []
+  mattr_accessor :agent_chat_hub_url, default: "https://mcritchie.studio"
+  # The app's bearer credential for the hub. Leave nil to read
+  # ENV["AGENT_CHAT_TOKEN"] (1Password apps.<slug>.agent-chat).
+  mattr_accessor :agent_chat_token,   default: nil
+  # Which signed-in users the hub may know by email. An email the user only
+  # CLAIMS (the profile page saves a new address and clears email_verified_at;
+  # password signup saves any address) would open that person's hub thread on
+  # every app, so by default only a user whose email_verified_at is present is
+  # sent by email; everyone else chats as an anonymous visitor (the anon
+  # cookie). Set a callable ->(user) { "proven@address" or nil } to use another
+  # proof; nil keeps the default. Never answer a claimed address.
+  mattr_accessor :agent_chat_verified_email, default: nil
+
+  def self.agent_chat_soul_list
+    Array(agent_chat_souls).map { |soul| soul.to_s.strip }.reject(&:empty?).uniq
+  end
+
   class S3ConfigError < StandardError; end
 
   # Whether to validate the host app's User model at boot. See docs/USER_CONTRACT.md.
@@ -1702,6 +1731,16 @@ module Studio
              constraints: { token: %r{[^/]+} }
       end
 
+      # The shared agent chat's proxy (Studio::AgentChatsController): the
+      # browser's two calls, which the app's server forwards to the hub. Drawn
+      # only for an app that names a soul (Studio.agent_chat_souls).
+      if Studio.agent_chat_soul_list.any?
+        post "agent_chat/messages", to: "studio/agent_chats#create", as: :studio_agent_chat_messages,
+             defaults: { format: :json }
+        get  "agent_chat/turns",    to: "studio/agent_chats#turns",  as: :studio_agent_chat_turns,
+             defaults: { format: :json }
+      end
+
       # The session-drift rehydrate endpoint (Studio::SessionStatesController).
       # OPT-IN — see Studio.draw_session_routes. JSON only: the browser store is
       # its one caller, and an HTML answer would only ever be a mistake.

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: studio-engine
 version: !ruby/object:Gem::Version
-  version: 0.115.4.rc1
+  version: 0.116.0.rc1
 platform: ruby
 authors:
 - Alex McRitchie
@@ -395,6 +395,7 @@ files:
 - app/controllers/sessions_controller.rb
 - app/controllers/solana_sessions_controller.rb
 - app/controllers/studio/admin_surveys_controller.rb
+- app/controllers/studio/agent_chats_controller.rb
 - app/controllers/studio/bookings_controller.rb
 - app/controllers/studio/component_previews_controller.rb
 - app/controllers/studio/emails_controller.rb
@@ -424,6 +425,7 @@ files:
 - app/helpers/studio_navbar_helper.rb
 - app/helpers/studio_sidebar_helper.rb
 - app/helpers/studio_theme_helper.rb
+- app/javascript/studio/agent_chat.js
 - app/javascript/studio/alpine_scopes.js
 - app/javascript/studio/alpine_shims.js
 - app/javascript/studio/alpine_stores.js
@@ -432,6 +434,7 @@ files:
 - app/javascript/studio/board.js
 - app/javascript/studio/booking.js
 - app/javascript/studio/confirm_interstitial.js
+- app/javascript/studio/controllers/agent_chat_controller.js
 - app/javascript/studio/controllers/board_controller.js
 - app/javascript/studio/controllers/booking_controller.js
 - app/javascript/studio/controllers/email_banner_scale_controller.js
@@ -559,6 +562,11 @@ files:
 - app/views/studio/admin_models/show.html.erb
 - app/views/studio/admin_surveys/index.html.erb
 - app/views/studio/admin_surveys/show.html.erb
+- app/views/studio/agent_chat/_chat.html.erb
+- app/views/studio/agent_chat/_form.html.erb
+- app/views/studio/agent_chat/_header.html.erb
+- app/views/studio/agent_chat/_turn.html.erb
+- app/views/studio/agent_chat/_typing.html.erb
 - app/views/studio/banners/_app_banner.html.erb
 - app/views/studio/banners/_button.html.erb
 - app/views/studio/banners/_dev_mode_button.html.erb
@@ -733,6 +741,7 @@ files:
 - lib/generators/studio/site_identity/site_identity_generator.rb
 - lib/studio-engine.rb
 - lib/studio.rb
+- lib/studio/agent_chat.rb
 - lib/studio/auth_labels.rb
 - lib/studio/booking.rb
 - lib/studio/cable.rb