studio-engine 0.121.0 → 0.123.0

data/app/views/style/index.html.erb

@@ -3,10 +3,10 @@
      application.html.erb, inheriting that app's navbar and theme, so every
      specimen restyles per app and in dark or light automatically.
 
-     Five ENGINE sections, reached by the sticky section nav below and rendered
+     Five ENGINE sections, reached by the sticky title row below and rendered
      as sibling partials: Theme is the landing section (the color foundation - it
-     owns the role tokens/swatches, the folded-in /admin/theme editor, and the
-     live preview), then Modals (the shared host + engine card blocks), Tricks
+     owns the role tokens/swatches, the theme editor, the live preview, and the
+     logos and type), then Modals (the shared host + engine card blocks), Tricks
      (the button/surface/motion/effect/leveling primitives, framed as a board of
      copy-paste-for-an-agent snippets), Tasks (the shared board primitive), and
      Components (the ViewComponent previews, linking into the gallery at
@@ -54,36 +54,34 @@
   ]
 %>
 <div class="max-w-6xl mx-auto px-4 pb-16">
-  <header class="space-y-2 pt-8 pb-6">
-    <p class="label-upper">studio-engine &middot; v<%= Studio::VERSION %></p>
-    <h1 class="text-3xl font-bold text-heading">Style</h1>
-    <p class="text-body max-w-2xl">
-      A living gallery of the shared UI primitives, rendered live in this app's
-      theme. Everything below is styled by the engine's own
-      <code class="font-mono text-2xs bg-inset px-1.5 py-0.5 rounded">engine.css</code>
-      and
-      <code class="font-mono text-2xs bg-inset px-1.5 py-0.5 rounded">engine-motion.css</code>
-      layers - toggle this app between light and dark and every specimen follows.
-    </p>
-  </header>
-
-  <%# Section nav — sticky under the whole pinned stack (--pin-stack-bottom; then
-      --nav-bottom and --nav-h for a host on an older publisher; then 0). Not --nav-h first: that
-      is the header's HEIGHT, and chrome stacked above the header would sit over
-      the nav by its own height. A pill per
-      section; the row scrolls horizontally on narrow screens, its edges softened
-      by the .fade-edge-x primitive. Order leads with Theme (the color foundation).
-      It sits at --z-sticky, above --z-raised, so the live hold button's portal
-      bubbles scroll under it rather than over it. %>
-  <nav class="sticky -mx-4 px-4 py-3 bg-surface border-y border-subtle"
-       style="top: var(--pin-stack-bottom, var(--nav-bottom, var(--nav-h, 0px))); z-index: var(--z-sticky, 30)" aria-label="Style guide sections">
-    <div class="fade-edge-x overflow-x-auto">
-      <div class="flex items-center gap-2 min-w-max">
-        <% sections.each do |anchor, label| %>
-          <a href="#<%= anchor %>" class="btn btn-neutral btn-sm"><%= label %></a>
+  <%# The page's title and its section tabs, one sticky row under the whole pinned
+      stack (--pin-stack-bottom; then --nav-bottom and --nav-h for a host on an
+      older publisher; then 0). Not --nav-h first: that is the header's HEIGHT,
+      and chrome stacked above the header would sit over the row by its own
+      height. The tabs scroll sideways on a narrow screen, softened by
+      .fade-edge-x; px-8 matches its 2rem fade, so a tab at rest is not faded.
+      The row sits at --z-sticky, above --z-raised, so the live hold button's
+      portal bubbles scroll under it rather than over it.
+  
+      The style-section-nav controller moves the highlight as the page scrolls
+      (studio/style_section_nav). Theme starts active, so the first paint is
+      right before the module loads. %>
+  <nav class="sticky -mx-4 mt-6 px-4 py-2 bg-surface border-y border-subtle flex items-center gap-2"
+       style="top: var(--pin-stack-bottom, var(--nav-bottom, var(--nav-h, 0px))); z-index: var(--z-sticky, 30)"
+       aria-label="Style guide sections"
+       data-studio-controller="style-section-nav">
+    <h1 class="text-xl font-bold text-heading shrink-0">Style</h1>
+    <div class="fade-edge-x overflow-x-auto min-w-0 flex-1" data-style-section-nav-target="scroller">
+      <div class="flex items-center gap-2 min-w-max px-8">
+        <% sections.each_with_index do |(anchor, label), index| %>
+          <a href="#<%= anchor %>"
+             class="btn btn-sm <%= index.zero? ? "btn-primary" : "btn-neutral" %>"
+             <%= 'aria-current="true"'.html_safe if index.zero? %>
+             data-style-section-nav-target="link"><%= label %></a>
         <% end %>
       </div>
     </div>
+    <p class="label-upper shrink-0 hidden md:block" title="studio-engine">v<%= Studio::VERSION %></p>
   </nav>
 
   <div class="space-y-16 pt-10">

data/db/migrate/20261103120000_create_studio_user_sessions.rb

@@ -0,0 +1,16 @@
+# One row per signed-in browser session (Studio::UserSession). A small, cached
+# record every app keeps the same way. No foreign key: a host's users table is
+# its own, and a deleted user's sessions may stay as counts.
+class CreateStudioUserSessions < ActiveRecord::Migration[7.2]
+  def change
+    create_table :studio_user_sessions do |t|
+      t.bigint :user_id, null: false
+      t.boolean :admin, null: false, default: false
+      t.datetime :started_at, null: false
+      t.datetime :last_seen_at, null: false
+      t.timestamps
+      t.index :user_id
+      t.index :last_seen_at
+    end
+  end
+end

data/docs/SITE_FOOTER.md

@@ -319,6 +319,39 @@ config.site_footer = ->(view) {
   only with a lockup (`studio/site_footer/_lockup_assets`). An engine older
   than the fact ignores the key, so a host can declare it before it upgrades.
 
+## The Chat link
+
+The standard way to reach an app's agent chat ([`AGENT_CHAT.md`](AGENT_CHAT.md)):
+a plain link at the end of the column headed **Contact** (any case), or a new
+Contact column at the end if the facts have none. An app that sets nothing sees
+no change.
+
+```ruby
+config.site_footer_chat_path = "/chat"             # or ->(view) { view.chat_path }
+# config.site_footer_chat_label = "Chat"           # the default
+# config.site_footer_chat_allowed = ->(user) { user&.admin? }  # default: Studio.agent_chat_allowed
+```
+
+| Setting | Meaning | Unset |
+|---------|---------|-------|
+| `site_footer_chat_path` | A path, or a callable taking the view (route helpers do not exist yet in an initializer). It answers nil to show no link on this page | No link |
+| `site_footer_chat_label` | The link's words | "Chat" |
+| `site_footer_chat_allowed` | A callable taking the viewer: `current_user`, **nil when signed out**, so write `user&.admin?` | `Studio.agent_chat_allowed` (everyone, by default) |
+
+- The link looks and behaves as any other column link (`_link.html.erb`). An href
+  the footer refuses (`javascript:`) adds nothing, and a Contact column that
+  already links the same path keeps its own row and label.
+- A hook that raises hides the link and reports once through
+  `Studio::SiteFooter.reporter`, so `user.admin?` on a signed-out viewer shows the
+  link to no one and costs no page. Write `user&.admin?` all the same.
+- **Hiding the link is not a gate.** `Studio.agent_chat_allowed` is
+  ([`AGENT_CHAT.md`](AGENT_CHAT.md), "Who may use it"); set that one, and the link
+  follows it.
+- **An admin-only link needs a page that shows the footer to a signed-in viewer.**
+  A signed-in viewer sees the footer only on `site_footer_controllers` (see
+  *Where it shows*), so list the pages your admins will look at.
+- Never cache the footer across viewers while the link is limited.
+
 ## Where it shows
 
 `studio_site_footer` asks `config.site_footer_visible`, one callable that

data/lib/studio/agent_chat.rb

@@ -16,8 +16,8 @@ module Studio
   #
   # 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
+  #   POST /api/v1/agent_chat/messages  soul, text, person, ip, voice (optional)
+  #        201 {turn, voice} · 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}
   #
@@ -27,6 +27,11 @@ module Studio
   # {id, role: "user"|"agent", text, created_at, status} with status
   # pending|typing|answered|failed.
   #
+  # `voice` marks a spoken message: {check, score, duration_ms}, what POST
+  # /voice/takes answered for the take (voice_param). NEVER A NAME: the hub
+  # names the speaker itself (the verified person's own name when check is
+  # "matched", else "Someone new") and may answer what it kept as `voice`.
+  #
   # 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
@@ -83,6 +88,31 @@ module Studio
     MAX_TEXT_LENGTH = 4_000
     # A hub answer larger than this is not a chat answer.
     MAX_BODY_BYTES = 1_048_576
+    # The words beside the microphone, approved by Alex McRitchie on 2026-11-01.
+    # Verbatim here and on an app's privacy page, from this one constant.
+    VOICE_PRIVACY = "When you speak to an agent, your recording is sent to OpenAI to turn it " \
+                    "into text, then deleted. We never keep the audio."
+
+    # The hold-to-talk button's words per recorder state (merged over
+    # Studio::VoiceCapture::RECORDER_COPY). The recorder says nothing while it
+    # records: the chat's own status line says "Listening...", so the button does
+    # not move under a held finger when the line appears.
+    VOICE_RECORDER_COPY = {
+      "idle" => { "button" => "Hold to talk" },
+      "recording" => { "button" => "Let go to send", "status" => "", "heard" => "" },
+      "captured" => { "button" => "Hold to talk", "status" => "" },
+      "silent" => { "button" => "Hold to talk" },
+      "failed" => { "button" => "Hold to try again" },
+      "denied" => { "button" => "Hold to talk" },
+      "unsupported" => { "button" => "Hold to talk" }
+    }.freeze
+
+    # The microphone chip's first words (the engine's say "tap Record").
+    VOICE_CHIP_COPY = {
+      "prompt" => { "chip" => "Microphone: hold to talk to allow",
+                    "note" => "Hold the talk button once and allow the microphone. Then you can pick one here." }
+    }.freeze
+
     LOOPBACK_HOSTS = %w[localhost 127.0.0.1 ::1 [::1]].freeze
     NETWORK_ERRORS = [
       Net::OpenTimeout, Net::ReadTimeout, Net::WriteTimeout, Timeout::Error,
@@ -93,13 +123,49 @@ module Studio
     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
+      #
+      # `voice` marks it as spoken (voice_param). When the hub answers what it
+      # kept, the returned Hash also carries it under "voice".
+      def post_message(soul:, text:, person:, ip: nil, voice: nil)
+        body = { soul: soul.to_s, text: text.to_s, person: person_param(person), ip: ip.to_s.presence,
+                 voice: voice_param(voice) }.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
+        kept = payload["voice"] if payload.is_a?(Hash)
+        kept.is_a?(Hash) ? turn.merge("voice" => kept) : turn
+      end
+
+      # The words of the chat's voice option: {"privacy", "recorder", "chip"},
+      # the `overrides` (voice_copy: on studio/agent_chat/chat) over the defaults.
+      # A blank privacy line is the default one: the line is never just dropped.
+      def voice_copy(overrides = nil)
+        words = (overrides || {}).to_h.transform_keys(&:to_s)
+        {
+          "privacy" => words["privacy"].presence || VOICE_PRIVACY,
+          "recorder" => Studio::VoiceCapture.merge(VOICE_RECORDER_COPY, words["recorder"]),
+          "chip" => Studio::VoiceCapture.merge(VOICE_CHIP_COPY, words["chip"])
+        }
+      end
+
+      # What a message's `voice` may say to the hub, as the hub reads it: `check`
+      # is one of the engine's own (else Invalid), `score` a cosine (-1..1, 4
+      # places) or nil, `duration_ms` 1..MAX_DURATION_MS or nil. Everything else,
+      # a browser-chosen name above all, stops here. nil or "" is a typed message.
+      def voice_param(voice)
+        return nil if voice.nil? || voice == ""
+
+        voice = voice.to_unsafe_h if voice.respond_to?(:to_unsafe_h)
+        raise Invalid.new("voice must be {check, score, duration_ms}", status: 422) unless voice.is_a?(Hash)
+
+        voice = voice.transform_keys(&:to_s)
+        check = voice["check"].to_s
+        unless Studio::VoiceTranscription::CHECKS.include?(check)
+          raise Invalid.new("voice.check is not one the engine answers", status: 422)
+        end
+
+        { check: check, score: voice_score(voice["score"]), duration_ms: voice_duration(voice["duration_ms"]) }
       end
 
       # The thread's turns after `after` (a turn id; nil for the latest), and
@@ -118,6 +184,18 @@ module Studio
 
       private
 
+      def voice_score(raw)
+        return nil unless raw.is_a?(Numeric) || raw.is_a?(String)
+
+        value = Float(raw, exception: false)
+        value&.finite? ? value.clamp(-1.0, 1.0).round(4) : nil
+      end
+
+      def voice_duration(raw)
+        value = raw.to_s.match?(/\A\d{1,9}\z/) ? raw.to_s.to_i : nil
+        value&.between?(1, Studio::VoiceTranscription::MAX_DURATION_MS) ? value : nil
+      end
+
       # {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.

data/lib/studio/site_footer.rb

@@ -170,7 +170,8 @@ module Studio
     #   booking_path: the booking page's path (Studio.booking_path_for), or nil
     #   address:      Studio.site_footer_address: the address of facts that
     #                 carry none of their own
-    def resolve(declared, view, name: nil, logo: nil, booking_path: nil, address: nil)
+    #   chat:         the Chat entry's [label, path] (`chat_row`), or nil
+    def resolve(declared, view, name: nil, logo: nil, booking_path: nil, address: nil, chat: nil)
       raw = declared.respond_to?(:call) ? declared.call(view) : declared
       return nil if raw.nil? || raw == false
 
@@ -189,7 +190,7 @@ module Studio
         email: text(facts[:email]),
         address: address_for(facts, address),
         social: Array(facts[:social]).filter_map { |row| social(row) },
-        columns: Array(facts[:columns]).filter_map { |row| column(row, booking_path) },
+        columns: with_chat(Array(facts[:columns]).filter_map { |row| column(row, booking_path) }, chat),
         legal: Array(facts[:legal]).filter_map { |row| link(row, booking_path) },
         booking_label: text(booking[:label]) || DEFAULT_BOOKING_LABEL,
         booking_title: text(booking[:title])
@@ -374,6 +375,48 @@ module Studio
       { heading: heading, links: links, width: column_width(options[:width]) }
     end
 
+    # The column the standard Chat entry joins, made if the app has none.
+    CONTACT_HEADING = "Contact"
+
+    # The Chat entry for this viewer as a [label, path] row, or nil: no path
+    # means the app has no chat, and `allowed` (a callable taking the viewer, nil
+    # when signed out) can hide it, e.g. admins only while testing. A hook that
+    # raises hides the entry and logs; the footer is on every page, and a link
+    # meant for a few must not show because its gate broke.
+    def chat_row(view, path:, label: nil, allowed: nil)
+      href = path.respond_to?(:call) ? path.call(view) : path
+      return nil if text(href).nil?
+      return nil unless chat_allowed?(view, allowed)
+
+      [text(label) || "Chat", href]
+    end
+
+    def chat_allowed?(view, allowed)
+      return true if allowed.nil?
+
+      user = view.respond_to?(:current_user) ? view.current_user : nil
+      (allowed.respond_to?(:call) ? allowed.call(user) : allowed) ? true : false
+    rescue StandardError => error
+      SiteFooter.reporter.call("[studio.site_footer] site_footer_chat_allowed raised #{error.class}: the Chat link is hidden")
+      false
+    end
+
+    # `columns` with the Chat entry last in the Contact column (any case), which
+    # is added at the end if there is none. A refused href adds nothing, and an
+    # app that already links the same path keeps its own row.
+    def with_chat(columns, chat)
+      row = chat && link(chat)
+      return columns if row.nil? || row[:href].nil?
+
+      at = columns.index { |column| column[:heading].to_s.casecmp?(CONTACT_HEADING) }
+      return columns + [{ heading: CONTACT_HEADING, links: [row], width: nil }] if at.nil?
+      return columns if columns[at][:links].any? { |known| known[:href] == row[:href] }
+
+      columns.each_with_index.map do |column, index|
+        index == at ? column.merge(links: column[:links] + [row]) : column
+      end
+    end
+
     # A column's width hint, or nil for the default share. Anything that is not a
     # number between MIN_COLUMN_WIDTH and MAX_COLUMN_WIDTH is no hint.
     MIN_COLUMN_WIDTH = 0.5

data/lib/studio/ui_primitives.rb

@@ -10,8 +10,10 @@ module Studio
         align-items: center;
         justify-content: center;
         vertical-align: middle;
-        width: 1.5rem;
-        height: 1.25rem;
+        /* In em so a larger glyph fits: at text-lg on a 16px scale a fixed 1.25rem
+           box clipped 4px off a 24px emoji. The floor keeps the navbar size. */
+        width: max(1.5rem, 1.25em);
+        height: max(1.25rem, 1.25em);
         overflow: hidden;
       }
 

data/lib/studio/version.rb

@@ -1,3 +1,3 @@
 module Studio
-  VERSION = "0.121.0"
+  VERSION = "0.123.0"
 end

data/lib/studio/voice_transcription.rb

@@ -5,6 +5,7 @@ require "net/http"
 require "openssl"
 require "securerandom"
 require "stringio"
+require "timeout"
 require "uri"
 
 # Understand: one finished take (the recorder's blob and its mime type, plus the
@@ -38,17 +39,36 @@ require "uri"
 # logger and environment, so the unit suite runs it without an app.
 module Studio
   module VoiceTranscription
-    # A transcriber call that failed: the message carries the vendor's words.
+    # A transcriber call that failed.
     class Error < StandardError; end
 
-    # The vendor answered a non-2xx; the status rides along so a caller can tell
-    # an auth failure from a model that fell over.
+    # The vendor failed. The status rides along (0 when nothing answered) with a
+    # reason code, so a caller can tell an auth failure from a model that fell
+    # over. The message names only the model, the status and the reason, never
+    # the vendor's own words: it reaches ErrorLog, and a vendor's error text can
+    # echo what it was sent.
     class HttpError < Error
-      attr_reader :status
+      # Why, as a code: unauthorized (401/403), rate_limited (429),
+      # server_error (5xx), rejected (another non-2xx), timeout (the deadline
+      # ran out), unreachable (no answer: refused, reset, DNS, TLS).
+      REASONS = %w[unauthorized rate_limited server_error rejected timeout unreachable].freeze
 
-      def initialize(message, status:)
+      attr_reader :status, :reason
+
+      def initialize(message, status:, reason: nil)
         super(message)
         @status = status
+        @reason = reason || self.class.reason_for(status)
+      end
+
+      def self.reason_for(status)
+        case status.to_i
+        when 401, 403 then "unauthorized"
+        when 429 then "rate_limited"
+        when 500..599 then "server_error"
+        when 0 then "unreachable"
+        else "rejected"
+        end
       end
     end
 
@@ -64,7 +84,8 @@ module Studio
 
     NO_LIVE_CALLS_ENV = "VOICE_NO_LIVE_CALLS"
     TRANSCRIBER_ENV = "STUDIO_VOICE_TRANSCRIBER"
-    API_KEY_ENV = "OPENAI_API_KEY"
+    # Voice's own key. Deliberately NOT the app's shared OPENAI_API_KEY.
+    API_KEY_ENV = "STUDIO_VOICE_OPENAI_API_KEY"
 
     # What a page shows when the app has no transcriber key. Says what is wrong
     # without naming the variable to a visitor.
@@ -123,24 +144,38 @@ module Studio
     # The real speech-to-text: OpenAI's POST /v1/audio/transcriptions, one
     # multipart file. Ported from Voicebox's Transcription::OpenAI: the model is
     # told the language (left to guess, a model handed near-silence answers a
-    # stock word in any language), and a failure other than auth is retried once
-    # on the fallback model from the start of the audio.
+    # stock word in any language), and a model that fell over (a 5xx, or a 4xx
+    # other than auth and 429) is retried once on the fallback from the start of
+    # the audio.
+    #
+    # ONE DEADLINE for the whole take (Studio.voice_transcribe_deadline, 25 s):
+    # both attempts share it, every socket timeout is what is left of it, and a
+    # hard Timeout backs it, so a vendor that trickles bytes cannot hold a web
+    # thread past it. Nothing is retried after a timeout (the deadline is spent),
+    # a 429 (the account is throttled; a second model only spends more), an auth
+    # failure, or no answer at all; nor with under MIN_RETRY_SECONDS left.
     class OpenAI
       ENDPOINT = "https://api.openai.com/v1/audio/transcriptions"
+      # The cap on connecting, inside the deadline.
       OPEN_TIMEOUT = 10
-      READ_TIMEOUT = 120
-      AUTH_FAILURES = [401, 403].freeze
+      NO_RETRY = %w[unauthorized rate_limited timeout unreachable].freeze
+      MIN_RETRY_SECONDS = 2
 
-      attr_reader :model, :fallback_model, :language, :endpoint
+      # The hard backstop's exception; turned into HttpError(reason: "timeout").
+      class DeadlineExceeded < Timeout::Error; end
+
+      attr_reader :model, :fallback_model, :language, :endpoint, :deadline
 
       def initialize(api_key: VoiceTranscription.api_key, model: Studio.voice_transcribe_model,
                      fallback_model: Studio.voice_transcribe_fallback_model,
-                     language: Studio.voice_transcribe_language, endpoint: ENDPOINT)
+                     language: Studio.voice_transcribe_language, endpoint: ENDPOINT,
+                     deadline: Studio.voice_transcribe_deadline)
         @api_key = api_key
         @model = model.to_s
         @fallback_model = fallback_model.to_s.strip.empty? ? nil : fallback_model.to_s
         @language = language.to_s.strip.empty? ? nil : language.to_s
         @endpoint = endpoint
+        @deadline = deadline.to_f.positive? ? deadline.to_f : 25.0
       end
 
       def configured? = !@api_key.to_s.strip.empty?
@@ -149,13 +184,24 @@ module Studio
       def transcribe(io:, filename:, content_type:)
         raise NotConfigured, "#{API_KEY_ENV} is not set, so this app cannot transcribe voice" unless configured?
 
-        request_text(model, io, filename, content_type)
-      rescue HttpError => e
-        raise if fallback_model.nil? || fallback_model == model || AUTH_FAILURES.include?(e.status)
+        ends_at = now + deadline
+        begin
+          request_text(model, io, filename, content_type, ends_at)
+        rescue HttpError => e
+          raise unless retry?(e, ends_at)
 
-        VoiceTranscription.log_warn("#{model} transcription failed (#{e.message}); retrying on #{fallback_model}")
-        io.rewind
-        request_text(fallback_model, io, filename, content_type)
+          VoiceTranscription.log_warn("#{model} transcription failed (HTTP #{e.status}, #{e.reason}); " \
+                                      "retrying on #{fallback_model}")
+          io.rewind
+          request_text(fallback_model, io, filename, content_type, ends_at)
+        end
+      end
+
+      def retry?(error, ends_at)
+        return false if fallback_model.nil? || fallback_model == model
+        return false if NO_RETRY.include?(error.reason)
+
+        ends_at - now >= MIN_RETRY_SECONDS
       end
 
       # The multipart fields, apart from the socket so a test reads them.
@@ -184,36 +230,52 @@ module Studio
 
       private
 
-      def request_text(model_name, io, filename, content_type)
-        perform(model_name, io, filename, content_type).fetch("text", "").to_s.strip
+      def now = Process.clock_gettime(Process::CLOCK_MONOTONIC)
+
+      def request_text(model_name, io, filename, content_type, ends_at)
+        perform(model_name, io, filename, content_type, ends_at).fetch("text", "").to_s.strip
       end
 
       # The only place a socket opens, so the only place the trap sits.
-      def perform(model_name, io, filename, content_type)
+      # uri.hostname, not uri.host: an IPv6 literal's host keeps its brackets
+      # ("[::1]"), which neither the loopback check nor the connect reads.
+      def perform(model_name, io, filename, content_type, ends_at)
         uri = URI.parse(endpoint)
-        VoiceTranscription.guard_live_call!("OpenAI", host: uri.host)
+        VoiceTranscription.guard_live_call!("OpenAI", host: uri.hostname)
+
+        left = ends_at - now
+        raise HttpError.new("OpenAI #{model_name} was not tried: the take's deadline ran out", status: 0, reason: "timeout") if left <= 0
 
         request = build_request(model_name, io, filename, content_type)
-        response = Net::HTTP.start(uri.host, uri.port, use_ssl: uri.scheme == "https",
-                                                       open_timeout: OPEN_TIMEOUT, read_timeout: READ_TIMEOUT) do |http|
-          http.request(request)
+        response = Timeout.timeout(left, DeadlineExceeded) do
+          Net::HTTP.start(uri.hostname, uri.port, use_ssl: uri.scheme == "https", open_timeout: [OPEN_TIMEOUT, left].min,
+                                                  read_timeout: left, write_timeout: left) do |http|
+            http.request(request)
+          end
         end
         interpret(response, model_name)
-      rescue Timeout::Error, SystemCallError, IOError, OpenSSL::SSL::SSLError, SocketError => e
-        raise HttpError.new("OpenAI #{model_name} could not be reached (#{e.class})", status: 0)
+      rescue Timeout::Error => e
+        raise HttpError.new("OpenAI #{model_name} did not answer within the take's #{deadline.round(1)} s deadline (#{e.class})",
+                            status: 0, reason: "timeout")
+      rescue SystemCallError, IOError, OpenSSL::SSL::SSLError, SocketError => e
+        raise HttpError.new("OpenAI #{model_name} could not be reached (#{e.class})", status: 0, reason: "unreachable")
       end
 
+      # A failure carries the status and its reason code, never the vendor's
+      # words (HttpError).
       def interpret(response, model_name)
+        status = response.code.to_i
+        unless response.is_a?(Net::HTTPSuccess)
+          reason = HttpError.reason_for(status)
+          raise HttpError.new("OpenAI #{model_name} answered HTTP #{status} (#{reason})", status: status, reason: reason)
+        end
+
         parsed = begin
           JSON.parse(response.body.to_s)
         rescue JSON::ParserError
           {}
         end
-        parsed = {} unless parsed.is_a?(Hash)
-        return parsed if response.is_a?(Net::HTTPSuccess)
-
-        detail = parsed.dig("error", "message") || response.body.to_s[0, 200]
-        raise HttpError.new("OpenAI #{model_name} answered HTTP #{response.code}: #{detail}", status: response.code.to_i)
+        parsed.is_a?(Hash) ? parsed : {}
       end
     end
 
@@ -269,7 +331,8 @@ module Studio
       klass.new
     end
 
-    # Studio.voice_openai_api_key, else OPENAI_API_KEY (Voicebox's name).
+    # Studio.voice_openai_api_key, else STUDIO_VOICE_OPENAI_API_KEY. Never the
+    # app's shared OPENAI_API_KEY: voice spends on its own key and budget.
     def api_key
       key = Studio.voice_openai_api_key.to_s.strip
       key.empty? ? ENV[API_KEY_ENV].to_s.strip : key
@@ -285,9 +348,12 @@ module Studio
       rails_env == "test"
     end
 
+    # This machine. host is URI#hostname, so IPv6 arrives unbracketed.
+    LOOPBACK_HOSTS = %w[127.0.0.1 localhost ::1].freeze
+
     def guard_live_call!(vendor, host:)
       return unless live_calls_blocked?
-      return if %w[127.0.0.1 localhost ::1].include?(host.to_s)
+      return if LOOPBACK_HOSTS.include?(host.to_s)
 
       raise LiveCallAttempted, "A live #{vendor} call was attempted with #{NO_LIVE_CALLS_ENV} armed. " \
                                "Tests drive the mock transcriber (Studio.voice_transcriber = \"mock\")."