@mindstudio-ai/remy 0.1.261 → 0.1.263

package/dist/headless.js

@@ -483,13 +483,17 @@ var ALLOWED_MODELS_BY_TYPE = {
     "gemini-3.1-pro",
     "gemini-3-flash",
     "gemini-3.5-flash",
+    "gemini-3.7-flash",
     "grok-build-0.1",
     "grok-4.5",
+    "grok-4.6",
     "glm-5.2",
     "muse-spark-1.1",
     "kimi-k2-7-code",
     "kimi-k3",
-    "deepseek-v4-flash-0731"
+    "deepseek-v4-flash-0731",
+    "qwen3.8-2.4t-a95b-deepinfra",
+    "minimax-m3"
   ]
   // vision: undefined — unconstrained
   // image_generation: undefined — unconstrained
@@ -2106,7 +2110,7 @@ var loadSkillTool = {
   definition: {
     clearable: true,
     name: "loadSkill",
-    description: "Load the full reference for a platform capability that isn't in your system prompt \u2014 task agents, agent interfaces, MCP interfaces, data sources. The available skills and the trigger for each are listed in <available_skills>. Load one before writing code in its area, not after: these are APIs where a plausible-looking guess is usually wrong. Calling this is cheap and expected \u2014 if you're unsure whether you need it, load it. Only covers the capabilities listed in the catalog; for backend SDK actions and model IDs use askMindStudioSdk.",
+    description: "Load the full reference for a platform capability that isn't in your system prompt \u2014 task agents, agent interfaces, voice interfaces, MCP interfaces, data sources. The available skills and the trigger for each are listed in <available_skills>. Load one before writing code in its area, not after: these are APIs where a plausible-looking guess is usually wrong. Calling this is cheap and expected \u2014 if you're unsure whether you need it, load it. Only covers the capabilities listed in the catalog; for backend SDK actions and model IDs use askMindStudioSdk.",
     inputSchema: {
       type: "object",
       properties: {
@@ -4323,6 +4327,7 @@ Each interface type invokes the same backend methods. Methods don't know which i
 - Email \u2014 inbound email processing
 - MCP \u2014 tool servers for AI assistants
 - Agent \u2014 conversational LLM interface with tool access to backend methods
+- Voice \u2014 the app's agent as a realtime voice conversation, with the same tool access
 
 ## Backend
 

package/dist/index.js

@@ -2195,13 +2195,17 @@ var init_surfaces = __esm({
         "gemini-3.1-pro",
         "gemini-3-flash",
         "gemini-3.5-flash",
+        "gemini-3.7-flash",
         "grok-build-0.1",
         "grok-4.5",
+        "grok-4.6",
         "glm-5.2",
         "muse-spark-1.1",
         "kimi-k2-7-code",
         "kimi-k3",
-        "deepseek-v4-flash-0731"
+        "deepseek-v4-flash-0731",
+        "qwen3.8-2.4t-a95b-deepinfra",
+        "minimax-m3"
       ]
       // vision: undefined — unconstrained
       // image_generation: undefined — unconstrained
@@ -2923,7 +2927,7 @@ var init_loadSkill = __esm({
       definition: {
         clearable: true,
         name: "loadSkill",
-        description: "Load the full reference for a platform capability that isn't in your system prompt \u2014 task agents, agent interfaces, MCP interfaces, data sources. The available skills and the trigger for each are listed in <available_skills>. Load one before writing code in its area, not after: these are APIs where a plausible-looking guess is usually wrong. Calling this is cheap and expected \u2014 if you're unsure whether you need it, load it. Only covers the capabilities listed in the catalog; for backend SDK actions and model IDs use askMindStudioSdk.",
+        description: "Load the full reference for a platform capability that isn't in your system prompt \u2014 task agents, agent interfaces, voice interfaces, MCP interfaces, data sources. The available skills and the trigger for each are listed in <available_skills>. Load one before writing code in its area, not after: these are APIs where a plausible-looking guess is usually wrong. Calling this is cheap and expected \u2014 if you're unsure whether you need it, load it. Only covers the capabilities listed in the catalog; for backend SDK actions and model IDs use askMindStudioSdk.",
         inputSchema: {
           type: "object",
           properties: {
@@ -5160,6 +5164,7 @@ Each interface type invokes the same backend methods. Methods don't know which i
 - Email \u2014 inbound email processing
 - MCP \u2014 tool servers for AI assistants
 - Agent \u2014 conversational LLM interface with tool access to backend methods
+- Voice \u2014 the app's agent as a realtime voice conversation, with the same tool access
 
 ## Backend
 

package/dist/prompt/compiled/auth.md

@@ -214,6 +214,8 @@ All auth methods throw on failure with a `code` property:
 | `invalid_state` | 400 | Sign in with Remy: returned CSRF state didn't match (stale/replayed redirect) |
 | `popup_blocked` | — | Sign in with Remy (embedded): popup was blocked — prompt to allow popups and retry |
 | `signin_timeout` | — | Sign in with Remy (embedded): popup didn't complete in time |
+| `auth_required` | 401 | Agent/voice interface requires an authenticated user (interface `auth` block) |
+| `role_required` | 403 | Agent/voice interface requires a role the user doesn't hold |
 
 ### Phone Helpers
 
@@ -380,9 +382,19 @@ Roles are declared in the manifest, stored as an array column on the user table,
 - Writable from dashboard: Remy dashboard shows app users and their roles
 - Backend enforcement: `auth.requireRole('admin')` works as before
 
+## Interface-Level Auth (Agent + Voice)
+
+Agent and voice interfaces additionally declare auth **in their config** (a required `auth` key:
+`{ "requireUser": boolean, "requireRole"?: string[] }`) because those sessions spend money without
+necessarily calling a backend method — the platform gates the lobby itself, before any model or
+media spend. `requireRole` uses the same manifest role ids with OR semantics. Denials reach the
+frontend SDK as `MindStudioInterfaceError` codes `auth_required` (401) and `role_required` (403) —
+route them to the app's login flow. See the `agentInterfaces` / `voiceInterfaces` skills for the
+full contract. Method-level `auth.requireRole(...)` checks still apply to every tool call inside.
+
 ## Apps Without Auth
 
-Apps without `auth` in the manifest use anonymous guest sessions. No login, no user identity, no roles. This is the default and works fine for single-user apps, internal tools, and simple utilities.
+Apps without `auth` in the manifest use anonymous guest sessions. No login, no user identity, no roles. This is the default and works fine for single-user apps, internal tools, and simple utilities. (Agent/voice interfaces on such apps declare `"auth": { "requireUser": false }` explicitly — anonymous callers are scoped by a per-browser visitor identity.)
 
 ## Important: Designing Auth in Web Interfaces
 

package/dist/prompt/compiled/interfaces.md

@@ -88,6 +88,8 @@ auth.logout()                       // clears session
 
 For apps with an agent interface, the SDK also provides `createAgentChatClient()` for thread management and streaming chat. Load the `agentInterfaces` skill for its usage — thread APIs, streaming callbacks, and attachments are all there.
 
+For apps with a voice interface, `createVoiceClient()` lives on the `@mindstudio-ai/interface/voice` subpath (deliberately separate so non-voice apps ship none of it). Load the `voiceInterfaces` skill for its usage — session lifecycle, live-caption events, tool status, and the voice-UI patterns are all there.
+
 The project uses `"jsx": "react-jsx"` (automatic JSX transform) — do not `import React from 'react'`. Only import the specific hooks and types you need (e.g., `import { useState, useEffect } from 'react'`).
 
 On deploy, the platform runs `npm install && npm run build` in the web directory and hosts the output on CDN.
@@ -180,10 +182,16 @@ It supports the full MCP surface: tools (methods the agent can call), resources
 
 ## Agent (Conversational Interface)
 
-A conversational interface where an LLM has access to the app's methods as tools. Unlike MCP (which exposes methods for external agents), the agent interface IS the agent — it has its own personality, system prompt, and model config, and orchestrates tool calls against the app's methods internally. Chat runs as the authenticated user, so every tool call carries that user's roles.
+A conversational interface where an LLM has access to the app's methods as tools. Unlike MCP (which exposes methods for external agents), the agent interface IS the agent — it has its own personality, system prompt, and model config, and orchestrates tool calls against the app's methods internally. Chat runs as the authenticated user, so every tool call carries that user's roles. The config must declare an `auth` block (`{ "requireUser": boolean, "requireRole"?: string[] }`) gating who may chat at all.
 
 **Load the `agentInterfaces` skill** before authoring `src/interfaces/agent.md` or building the chat UI — the spec frontmatter, compiled output, `agent.json`, and the entire frontend surface are all there.
 
+## Voice (Realtime Conversation)
+
+The app's agent as a live voice conversation — the user talks, and the agent answers in sub-second, interruptible speech, calling methods mid-conversation. A sibling of the agent interface, not a mode of it: its own spec, a persona written for the ear rather than the screen, and a smaller toolset where every tool carries a latency class governing how the agent handles the wait out loud. Sessions run as the authenticated user, so tool calls carry that user's roles; the platform handles the realtime media, turn-taking, barge-in, and transcripts. The config must declare an `auth` block (`{ "requireUser": boolean, "requireRole"?: string[] }`) gating who may start a session at all.
+
+**Load the `voiceInterfaces` skill** before authoring `src/interfaces/voice.md` or building the voice UI — the spoken-register rules, latency classes, spec format, `interface.json`, and the `createVoiceClient()` frontend surface are all there.
+
 ## Manifest Declaration
 
 Each interface is declared in `mindstudio.json`:
@@ -197,7 +205,8 @@ Each interface is declared in `mindstudio.json`:
     { "type": "webhook", "path": "dist/interfaces/webhook/interface.json" },
     { "type": "email", "path": "dist/interfaces/email/interface.json" },
     { "type": "mcp", "path": "dist/interfaces/mcp/interface.json" },
-    { "type": "agent", "path": "dist/interfaces/agent/agent.json" }
+    { "type": "agent", "path": "dist/interfaces/agent/agent.json" },
+    { "type": "voice", "path": "dist/interfaces/voice/interface.json" }
   ]
 }
 ```

package/dist/prompt/compiled/manifest.md

@@ -111,7 +111,7 @@
 
 | Field | Type | Required | Description |
 |-------|------|----------|-------------|
-| `type` | `string` | Yes | One of: `web`, `api`, `cron`, `webhook`, `email`, `mcp`, `agent` |
+| `type` | `string` | Yes | One of: `web`, `api`, `cron`, `webhook`, `email`, `mcp`, `agent`, `voice` |
 | `path` | `string` | No | Path to the interface config file |
 | `config` | `object` | No | Inline config (alternative to a file) |
 | `enabled` | `boolean` | No | Default `true`. Set `false` to skip during build. |

package/dist/prompt/compiled/platform.md

@@ -23,6 +23,7 @@ my-app/
       web.md                           web UI spec
       api.md                           API conventions
       agent.md                         agent personality and behavior spec
+      voice.md                         voice agent persona and toolset spec
       cron.md                          scheduled job descriptions
     roadmap/                           feature roadmap (one file per item, type: roadmap)
 
@@ -53,6 +54,10 @@ my-app/
         agent.json                         agent config
         system.md                          compiled system prompt
         tools/                             tool descriptions (one .md per method)
+      voice/                             voice interface
+        interface.json                     voice config
+        system.md                          compiled voice-register system prompt
+        tools/                             tool descriptions (one .md per method)
 ```
 
 ## What Goes Where
@@ -95,7 +100,7 @@ const { vendor } = await api.approveVendor({ vendorId: '...' });
 
 - **Managed databases.** SQLite with typed schemas. Push a schema change and the platform diffs, migrates, and promotes atomically.
 - **Built-in auth.** Opt-in via manifest. Developer builds login UI, platform handles verification codes (email/SMS), cookie sessions, and role enforcement. Backend methods use `auth.requireRole('admin')` for access control.
-- **Multiple interfaces, one codebase.** Web, API, Cron, Webhook, Email, MCP — all invoke the same methods. Methods don't know which interface called them.
+- **Multiple interfaces, one codebase.** Web, API, Cron, Webhook, Email, MCP, Agent, Voice — all invoke the same methods. Methods don't know which interface called them.
 - **Sandboxed execution.** Each method invocation runs in its own isolated execution context with npm packages pre-installed.
 - **Git-native deployment.** Push to default branch to deploy. Push to feature branch for preview. Rollback is a git revert.
 - **Secrets.** Encrypted environment variables with separate dev/prod values. Injected as `process.env` in methods. For third-party service credentials not covered by the SDK.

package/dist/prompt/skills/agentInterfaces.md

@@ -257,6 +257,7 @@ dist/interfaces/agent/
     "temperature": 0.5,
     "maxTokens": 16000,
     "systemPrompt": "system.md",
+    "auth": { "requireUser": true },
     "tools": [
       { "method": "create-todo", "description": "tools/createTodo.md" },
       { "method": "list-todos", "description": "tools/listTodos.md" }
@@ -276,6 +277,7 @@ across rather than copying the key.
 | `temperature` | Model temperature |
 | `maxTokens` | Max response tokens (the spec's `maxResponseTokens`) |
 | `systemPrompt` | Relative path to the compiled system prompt markdown file |
+| `auth` | **Required.** Who may open the lobby: `{ "requireUser": boolean, "requireRole"?: string[] }`. See the Auth section below |
 | `tools` | Array of tool entries — `method` references a method `id` from the manifest, `description` is a relative path to a markdown file with rich tool docs (when to use, examples, edge cases, parameter guidance) |
 | `webInterfacePath` | Optional. If the app has a web interface with a chat page, this path tells the IDE where to show the preview. Otherwise the agent is accessed via API. |
 
@@ -287,8 +289,29 @@ Declare it in `mindstudio.json`:
 
 ## Auth
 
-Agent chat runs as the **authenticated user**, not as a system role — tool calls carry that user's
-roles, so a method gated with `auth.requireRole` behaves exactly as it would if the user had called it
-from the web frontend. That's what makes exposing real methods safe; it's also why role restrictions
-belong in the tool descriptions, so the agent can decline gracefully instead of surfacing a rejection.
+**Every agent config declares an `auth` block.** Agent chat spends the owner's money on every
+message without necessarily touching a backend method, so the platform gates the lobby itself —
+enforced at thread creation and message send:
+
+```json
+"auth": { "requireUser": true, "requireRole": ["support-agent", "admin"] }
+```
+
+- `requireUser: true` — only authenticated app users may chat; `false` — anyone, including
+  anonymous visitors. Most apps want `true`; choose `false` deliberately (a public concierge).
+- `requireRole` (optional) — the user must hold **at least one** of the listed manifest role ids
+  (OR semantics, same as the backend `auth.requireRole(...)`). Omit or leave empty for no role
+  gate. Requires `requireUser: true`. Unknown role ids fail the build.
+- Denials surface to the frontend SDK as `MindStudioInterfaceError` with code `auth_required`
+  (401) or `role_required` (403).
+- Dev preview is exempt — the builder is never locked out while testing.
+- Older compiled apps without the block fall back to the manifest's `auth.enabled` (auth-enabled →
+  users only; no auth → public). New configs always declare it explicitly.
+
+Once inside, agent chat runs as the **authenticated user**, not as a system role — tool calls
+carry that user's roles, so a method gated with `auth.requireRole` behaves exactly as it would if
+the user had called it from the web frontend. That's what makes exposing real methods safe; it's
+also why role restrictions belong in the tool descriptions, so the agent can decline gracefully
+instead of surfacing a rejection. Anonymous visitors (when allowed) are scoped by a per-browser
+visitor identity: their threads are private to their browser, and gated methods still reject.
 

package/dist/prompt/skills/mcpInterfaces.md

@@ -268,7 +268,7 @@ Declare it in `mindstudio.json`:
   `custom_subdomain` host (e.g. `myapp.madewithremy.com`), a custom domain if configured, or the UUID
   host (`<appId>.madewithremy.com` / `.msagent.ai`).
 - **Auth is optional.** A `Bearer` key resolves to a user with full RBAC, so the method's own
-  `auth.requireRole`/`requireUser` checks apply as they would for that user. With no key, calls run
+  `auth.requireRole(...)`/`hasRole(...)` checks apply as they would for that user. With no key, calls run
   anonymously — no user, no roles. The method is the boundary: gate sensitive tools, and understand that
   a public (keyless) server effectively exposes only the un-gated ones.
 - Input schemas are derived automatically from each method's input contract.

package/dist/prompt/skills/restApi.md

@@ -141,7 +141,7 @@ Routes are mounted at `/_/api{path}` (e.g. `DELETE /_/api/vendors/abc123`).
 - **Request body** for POST/PUT/PATCH is the input directly (no `{ input: {...} }` wrapper)
 - **Response** is the method output directly (no `{ output: {...} }` wrapper)
 - **Auth** via `Authorization: Bearer sk_...` — an API key resolves to a user with full RBAC, so the
-  method's own `auth.requireRole`/`requireUser` checks apply exactly as they would for that user
+  method's own `auth.requireRole(...)`/`hasRole(...)` checks apply exactly as they would for that user
 - **Streaming**: `Accept: text/event-stream` header returns SSE chunks
 - **Raw request context**: Every API method receives `input._request` with `{ method, headers, rawBody }`.
   `rawBody` is the original unparsed body as a UTF-8 string — needed for signature verification, since

package/dist/prompt/skills/voiceInterfaces.md

@@ -0,0 +1,359 @@
+---
+name: Voice Interfaces
+what: Realtime voice conversation as a first-class interface — the user talks to the app and its voice agent talks back in sub-second, interruptible speech, calling the app's methods mid-conversation as the authenticated user. The platform handles the media transport, turn-taking, barge-in, and transcripts, so the work is authorship — a persona written for the ear, a small toolset where every tool carries a latency class, and descriptions that say results out loud. Any app whose methods do something interesting can pick up a voice, and it is often the most impressive surface it has.
+when: Before authoring `src/interfaces/voice.md`, choosing a voice model or pipeline, deciding which methods a voice agent gets, or building the voice UI with `createVoiceClient()`.
+---
+
+# Building Voice Interfaces
+
+A voice interface is the app's agent as a live phone-call-quality conversation: the user speaks, the
+agent answers in speech, and the app's methods are its tools. It is a **sibling of the agent
+interface, not a mode of it** — the two share a philosophy (an LLM projecting the backend contract
+into conversation; load the `agentInterfaces` skill for that shared ground), but everything you
+author differs. The persona is written for the ear, not the screen. The toolset is smaller and
+curated for conversational latency. And every tool declares how the agent should handle the wait,
+because in a live call, silence reads as a dropped line.
+
+The platform owns the hard parts — realtime audio transport, turn detection, interruption handling,
+transcripts, session limits, per-user auth on every tool call. Your job is the spec
+(`src/interfaces/voice.md`) and its compilation into `dist/interfaces/voice/`.
+
+## Voice Agent Design
+
+### Written for the ear
+
+Everything the agent produces gets spoken aloud. That inverts several habits that are correct
+everywhere else, and the compiled system prompt must carry them explicitly:
+
+- **No visual formatting, ever.** No markdown, no lists, no tables, no emoji, no URLs read as
+  punctuation soup. If a tool returns a link, say what it is and where it will be, don't recite it.
+- **Spoken-form values.** "Forty-two fifty," not "$42.50". "Two fifteen in the afternoon," not
+  "14:15". Read email addresses and confirmation codes character by character, and read them *back*
+  for confirmation before acting on them — mishearing one digit of a phone number is the classic
+  voice failure.
+- **Brevity is a hard rule, not a style preference.** One to two sentences per turn, one question at
+  a time. A paragraph that reads fine in chat is a monologue on a call.
+- **Handle unclear audio explicitly.** Give the prompt a rule for it: respond only to clear audio;
+  if it's noisy or ambiguous, ask the user to repeat — never guess, and never call a tool on input
+  the agent isn't sure it heard.
+- **Pin the language.** State the response language in the prompt; don't let the model infer it from
+  an accent.
+
+Beyond the mechanics, the persona itself should be *of the ear*: pacing, warmth, how it handles
+being interrupted, what it says when it needs a second. This is the fun part, same as the agent
+interface — a distinct character beats a generic assistant, and voice makes character land harder
+than any other surface.
+
+### The latency classes
+
+Every tool in the spec declares one of three classes. This is the voice-specific discipline — get it
+right and tool use feels like talking to a competent person; get it wrong and every action is an
+awkward pause.
+
+- **`fast`** — sub-second reads: lookups, availability checks, small queries. The agent calls
+  silently; announcing a sub-second call adds more delay than the call itself.
+- **`slow`** — a noticeable wait, roughly one to three seconds: writes, searches, anything that does
+  real work. The agent speaks a one-line preamble ("Let me get that booked") generated in parallel
+  with the call, so the line never goes quiet.
+- **`background`** — long-running work: reports, enrichment, bulk operations. The agent
+  acknowledges, keeps conversing, and reports the result when it lands. Background tools are
+  cancellable — if the user changes course mid-run, the work stops.
+
+Classify by how the method actually behaves, not by what it is named. A "lookup" that fans out to an
+external service is `slow`. When in doubt between `fast` and `slow`, pick `slow` — a needless
+preamble is mildly chatty; an unexplained silence feels broken.
+
+### Tool descriptions say results out loud
+
+Follow the agent-interface principles for tool descriptions (when to use and when not, parameter
+guidance, what comes back) — plus one voice-specific layer: **how to speak the result.** A tool that
+returns a booking record needs its description to say what the confirmation sounds like ("You're all
+set for Tuesday at two") and what never gets read aloud (internal ids, timestamps, enum values).
+
+Curate harder than you would for chat. A voice agent with four excellent tools outperforms one with
+twelve adequate ones — every tool the model considers is a beat of hesitation. Skip batch
+operations, admin utilities, and anything whose output can't be said in a breath or two. Note role
+restrictions in the description so the agent declines gracefully in character instead of surfacing a
+rejection.
+
+### Confirmation scales with risk
+
+Bake the policy into the system prompt: read-only tools — just call them. Writes — summarize what's
+about to happen and get a yes. Anything destructive or financial — read the details back first,
+piece by piece. In voice there is no confirmation dialog to lean on; the conversation *is* the
+confirmation UI.
+
+### Choosing the model
+
+Two shapes, one `model` field:
+
+- **Native speech-to-speech** (`{"model": ..., "voice": ...}`) — one realtime model hears and
+  speaks. Lowest latency, most natural prosody, hears tone and hesitation. The default for
+  personality-forward, conversational apps.
+- **Cascaded** (`{"llm": ..., "stt": ..., "tts": ..., "voice": ...}`) — streaming transcription
+  into any chat model in the catalog, streaming speech out. Slightly higher latency, but the brain
+  can be *any* chat model — the right choice when the app's reasoning demands a specific model, or
+  when the agent interface already uses one and the voice should think identically. The blessed
+  streaming pairing is `"stt": "deepgram-nova-3", "tts": "cartesia-sonic-3"` — the lowest-latency
+  combination the platform wires; prefer it unless there's a reason not to. One nuance: cascaded
+  engines speak the `greeting` verbatim (they have a real TTS); speech-to-speech engines have the
+  model say it, so it may paraphrase slightly.
+
+Ask `askMindStudioSdk` for available ids — realtime, transcription, and speech models are separate
+catalogs, and MindStudio ids don't match vendor ids, so treat ids in this document as illustrative.
+Voice ids are model-specific; query for those too. The user's UI has a picker for changing the model
+later, so validate only when you set it.
+
+### Seeding from an existing agent
+
+If the app already has an agent interface, start from it: same character, same values, same
+terminology — then rewrite for the ear (shorter, spoken-form, no formatting) and re-curate the
+toolset for latency. Don't copy `agent.md`'s prose wholesale; a chat persona read aloud sounds like
+someone reading chat aloud.
+
+### Anti-patterns
+
+- Prose that would render fine in chat — bullet lists, headers, or markdown anywhere in `system.md`.
+- A tool description that explains what to display instead of what to say.
+- Exposing the whole method surface. Voice is the most curated interface the app has.
+- A generic greeting ("Hello! How can I assist you today?"). The greeting is the first thing anyone
+  hears; make it the character's.
+- Writing your own current-user placeholder — the platform appends a `## Current User` block (name,
+  roles) to every system prompt at runtime.
+
+## Compiling the Voice Spec
+
+When building `dist/interfaces/voice/`, consider the spec, the app, and the `@brand/` guidelines —
+the voice agent should be unmistakably the same product as the web UI, projected into sound. Output:
+
+**`system.md`** — the persona compiled for the ear. Character first, then the mandatory carries from
+"Written for the ear" above (spoken-form rules, brevity, unclear-audio handling, language pinning,
+confirmation-by-risk), then any preamble phrasing guidance for `slow` tools so the fillers sound like
+the character too.
+
+**`tools/*.md`** — one per tool: when to use, parameter guidance, how to say the result, role
+restrictions.
+
+**`interface.json`** — the config tying it together. Full shape in "The wiring" below.
+
+## Voice UI
+
+When the app has a web interface, voice arrives as a **layer over it**, not a separate page: a
+persistent affordance (a button, an orb in a corner) that starts a session in place, with the app
+still visible and usable. A dedicated full-screen voice mode is the immersive option for apps where
+the conversation *is* the product — earn it, don't default to it.
+
+### Frontend SDK: `createVoiceClient()`
+
+Ships as a subpath of the interface SDK so apps that never use voice pay nothing for it. All voice
+UIs go through it — never hand-roll audio capture or transport.
+
+```ts
+import { createVoiceClient } from '@mindstudio-ai/interface/voice';
+
+const voice = createVoiceClient();
+
+// Prompts for mic permission, mints a session, connects.
+// Throws MindStudioInterfaceError('microphone_denied') on refusal.
+const session = await voice.startSession();
+
+session.state;  // 'connecting' | 'listening' | 'thinking' | 'speaking' | 'ended'
+session.on('stateChange', (state) => { });          // on() returns an unsubscribe fn
+
+// Live captions, both sides. Each event carries the segment's FULL text so
+// far (never a delta) — render by upserting on segmentId, not appending.
+session.on('transcript', ({ role, segmentId, text, final }) => { });
+
+session.on('toolCall', ({ method, status }) => { }); // 'running' | 'done' | 'failed'
+session.on('error', (err) => { });
+
+session.mute(); session.unmute(); session.isMuted;
+session.sendText('123 Main Street');  // inject text into the live conversation
+session.end();
+```
+
+Agent audio playback is handled inside the SDK (a hidden autoplaying element) — never create audio
+elements for the agent. `startSession()` throws `MindStudioInterfaceError` with code
+`microphone_denied` when mic access is refused (surface that state gently in the UI),
+`voice_concurrency_limit` / `voice_visitor_limit` when the app's session limits are hit, and
+`auth_required` (401) / `role_required` (403) when the interface's `auth` block denies the caller
+(route those to the app's login flow).
+
+Past sessions are call records with transcripts: `voice.listSessions()` /
+`voice.getSession(id)` — the material for a history view if the app wants one.
+
+### The state machine, made visible
+
+One audio-reactive element carries the session: idle → connecting → listening → thinking → speaking.
+Always pair it with a **text state label** — never signal state by color or motion alone. Calm at
+idle, responsive to actual audio levels while listening and speaking. Respect
+`prefers-reduced-motion` with a static-but-labeled variant.
+
+### Live captions
+
+Stream `transcript` events as captions — both sides of the conversation. Captions make the agent
+feel accurate, catch mishearings early, and are the accessibility story. User-side transcripts
+arrive as recognition output and can lag or differ slightly from what the model heard; render them
+as captions, never treat them as input to app logic.
+
+### Controls that must exist
+
+**Mute** and **end call**, always visible, always working. `sendText` earns its place the moment the
+conversation needs an exact string — an address, a code, an email — typing it beats spelling it
+aloud three times. Show tool activity as a compact inline status from `toolCall` events, in the
+app's voice ("Booking your appointment…"), never raw names or JSON.
+
+### Anti-patterns
+
+- Blocking the whole UI behind the session — voice is a layer, the app stays usable.
+- An orb with no label, or state changes conveyed only by color.
+- Rendering user-side captions as authoritative ("you said X") — they're recognition output.
+- Auto-starting a session on page load. Microphone access is always a deliberate user action.
+
+---
+
+# The wiring
+
+## Spec: `src/interfaces/voice.md`
+
+Frontmatter holds the structured fields; the body is the persona plus an explicit `## Tools`
+section.
+
+```yaml
+---
+name: Front Desk
+description: Books appointments and answers questions by voice.
+type: interface/voice
+model: {"model": "gpt-realtime-mini", "voice": "marin"}
+turnDetection: {"eagerness": "medium"}
+greeting: Hey! I can help you book, reschedule, or answer questions — what do you need?
+---
+```
+
+Frontmatter fields:
+
+- `name` — display name
+- `description` — one-liner for listings
+- `model` — JSON string, two shapes: native speech-to-speech `{"model": <realtime model id>,
+  "voice": <voice id>}`, or cascaded `{"llm": <chat model id>, "stt": <transcription model id>,
+  "tts": <speech model id>, "voice": <voice id>}`. Optional `config` for model-specific settings.
+  Ids via `askMindStudioSdk`.
+- `turnDetection` — optional; `{"eagerness": "low" | "medium" | "high"}` — how quickly the platform
+  decides the user finished speaking. High is snappier; low is more patient (users dictating
+  numbers or addresses). Default `medium`.
+- `greeting` — optional spoken opener, delivered on session start. Omit and the agent waits for the
+  user to speak first. Verbatim on cascaded engines; model-spoken (may paraphrase) on
+  speech-to-speech.
+
+Body: persona prose (voice register), then the toolset:
+
+```markdown
+## Tools
+
+### Book appointment
+method: book-appointment
+latency: slow
+~~~
+Book an appointment once the caller has confirmed a date, time, and service.
+Read the details back and get a yes before calling. Say the confirmation
+naturally ("You're all set for Tuesday the 4th at 2pm") — never read the
+booking id aloud unless asked.
+~~~
+```
+
+`latency` is one of `fast` / `slow` / `background` (semantics in "The latency classes" above).
+Don't hand-author input schemas — the platform derives them from the method contract.
+
+## Compiled Output: `dist/interfaces/voice/`
+
+```
+dist/interfaces/voice/
+├── interface.json      ← config the platform reads
+├── system.md           ← compiled voice-register system prompt
+└── tools/
+    └── bookAppointment.md   ← rich tool description, one per tool
+```
+
+## Config (`interface.json`)
+
+The top-level key must match the interface type (`voice`):
+
+```json
+{
+  "voice": {
+    "name": "Front Desk",
+    "description": "Books appointments and answers questions by voice.",
+    "model": "gpt-realtime-mini",
+    "voice": "marin",
+    "turnDetection": { "eagerness": "medium" },
+    "greeting": "Hey! I can help you book, reschedule, or answer questions — what do you need?",
+    "systemPrompt": "system.md",
+    "auth": { "requireUser": true },
+    "tools": [
+      { "method": "book-appointment", "latency": "slow", "description": "tools/bookAppointment.md" }
+    ],
+    "webInterfacePath": "/"
+  }
+}
+```
+
+| Field | Description |
+|-------|-------------|
+| `name`, `description` | Display name + listing metadata |
+| `model` | Realtime model id (native speech-to-speech). Mutually exclusive with `llm`/`stt`/`tts` |
+| `llm`, `stt`, `tts` | The cascaded alternative: chat model id + streaming transcription id + streaming speech id |
+| `voice` | Provider voice id (model-specific; query `askMindStudioSdk`) |
+| `turnDetection` | `{ "eagerness": "low" \| "medium" \| "high" }`, optional |
+| `greeting` | Optional spoken opener |
+| `systemPrompt` | Relative path to the compiled system prompt |
+| `auth` | **Required.** Who may start a session: `{ "requireUser": boolean, "requireRole"?: string[] }`. See the Auth section below |
+| `tools` | `{ method, latency, description }` — method `id` from the manifest, a latency class, and a relative path to the tool's markdown |
+| `webInterfacePath` | Optional. Where the voice layer lives in the web interface, for the editor preview |
+
+Declare it in `mindstudio.json`:
+
+```json
+{ "type": "voice", "path": "dist/interfaces/voice/interface.json" }
+```
+
+## Platform Behavior
+
+- Input schemas are derived from each method's contract — never hand-written.
+- The platform appends a `## Current User` block (name, roles) to the system prompt at runtime;
+  never author a placeholder for it.
+- Turn detection, barge-in (interruption truncates the agent's context to the audio the user
+  actually heard), and background-noise handling are platform-managed; `turnDetection.eagerness` is
+  the only knob.
+- Sessions have a per-app concurrency limit and a maximum duration, both configurable in the app's
+  settings; an idle session is ended gracefully after a prompt. Voice minutes and model usage are
+  metered.
+- Every session persists as a call record with a transcript, visible in the dashboard and readable
+  from the frontend via `voice.listSessions()` / `voice.getSession(id)`.
+
+## Auth
+
+**Every voice config declares an `auth` block.** A voice session spends the owner's money for its
+entire duration without necessarily touching a backend method, so the platform gates session
+creation itself:
+
+```json
+"auth": { "requireUser": true, "requireRole": ["member"] }
+```
+
+- `requireUser: true` — only authenticated app users may start a session; `false` — anyone,
+  including anonymous visitors. Most apps want `true`; choose `false` deliberately (a public
+  front-desk line).
+- `requireRole` (optional) — the user must hold **at least one** of the listed manifest role ids
+  (OR semantics, same as the backend `auth.requireRole(...)`). Omit or leave empty for no role
+  gate. Requires `requireUser: true`. Unknown role ids fail the build.
+- Denials reject `startSession()` with code `auth_required` (401) or `role_required` (403).
+- Dev preview is exempt — the builder is never locked out while testing.
+- Older compiled apps without the block fall back to the manifest's `auth.enabled` (auth-enabled →
+  users only; no auth → public). New configs always declare it explicitly.
+
+Once inside, voice sessions run as the **authenticated user** — every tool call carries that
+user's roles, so a method gated with `auth.requireRole` behaves exactly as it would from the web
+frontend or the agent interface. Anonymous sessions (when allowed) have no user and no roles:
+gated methods reject, and the caller's history is scoped to their browser's visitor identity.
+That's why role restrictions belong in the tool descriptions — the agent should decline in
+character, not relay a rejection.

package/dist/prompt/static/authoring.md

@@ -19,7 +19,7 @@ The scaffold starts with these spec files that cover the full picture of the app
 - **`src/interfaces/@brand/voice.md`** — voice and terminology: tone, error messages, word choices
 - **`src/roadmap/`** — feature roadmap. One file per feature (`type: roadmap`). See "Roadmap" below.
 
-These are starting points, not constraints. Create as many spec files as the project needs — the `src/` folder is your workspace and every `.md` file in it becomes compilation context. If the app has substantial content (presentation slides, copy, lesson plans, menu items, quiz questions), put it in its own file (`src/content.md`, `src/slides.md`, `src/menu.md`, etc.) rather than cramming it into `app.md` or `web.md`. If the domain is complex, split `app.md` into multiple files by area (`src/billing.md`, `src/approvals.md`). Add interface specs for other interface types (`api.md`, `webhook.md`, `cron.md`, `email.md`, `mcp.md`, `agent.md`) if the app uses them. Each of those has a skill carrying its spec format and config — `restApi`, `webhooks`, `scheduledJobs`, `inboundEmail`, `mcpInterfaces`, `agentInterfaces` — and you should load the relevant one before writing the spec rather than after, since the spec is what the config is compiled from. For external HTTP the choice is between two of them: the Webhook interface handles inbound provider webhooks (Stripe, GitHub) via secret-in-URL routing, while the API interface covers bearer-auth sync endpoints, public REST APIs, and batch tools. Organize however serves clarity — the platform reads the entire `src/` folder.
+These are starting points, not constraints. Create as many spec files as the project needs — the `src/` folder is your workspace and every `.md` file in it becomes compilation context. If the app has substantial content (presentation slides, copy, lesson plans, menu items, quiz questions), put it in its own file (`src/content.md`, `src/slides.md`, `src/menu.md`, etc.) rather than cramming it into `app.md` or `web.md`. If the domain is complex, split `app.md` into multiple files by area (`src/billing.md`, `src/approvals.md`). Add interface specs for other interface types (`api.md`, `webhook.md`, `cron.md`, `email.md`, `mcp.md`, `agent.md`, `voice.md`) if the app uses them. Each of those has a skill carrying its spec format and config — `restApi`, `webhooks`, `scheduledJobs`, `inboundEmail`, `mcpInterfaces`, `agentInterfaces`, `voiceInterfaces` — and you should load the relevant one before writing the spec rather than after, since the spec is what the config is compiled from. For external HTTP the choice is between two of them: the Webhook interface handles inbound provider webhooks (Stripe, GitHub) via secret-in-URL routing, while the API interface covers bearer-auth sync endpoints, public REST APIs, and batch tools. Organize however serves clarity — the platform reads the entire `src/` folder.
 
 Remember: users care about look and feel as much as (and often more than) underlying data structures. Don't treat the brand and interface specs as an afterthought — for many users, the visual identity and voice are the first things they want to get right.
 

package/dist/prompt/static/intake.md

@@ -11,7 +11,7 @@ Remy apps are full-stack TypeScript projects. You have a lot to work with:
 - **Backend (Methods):** TypeScript in a sandboxed runtime. Any npm package. Managed SQLite database with typed schemas and automatic migrations. Built-in app-managed auth with email/SMS verification, cookie sessions, and role enforcement. None of these are required — use what the app needs.
 - **Frontend (Web Interface):** Starts as Vite + React, but any TypeScript project with a build command works. Any framework, any library, or no framework at all.
 - **AI & integrations:** The `@mindstudio-ai/agent` SDK gives access to 200+ AI models (OpenAI, Anthropic, Google, Meta, Mistral, and more) and 1000+ integrations (email, SMS, Slack, HubSpot, Google Workspace, web scraping, image/video generation, media processing) with zero configuration — credentials are handled automatically. No API keys needed. Beyond individual actions, `runTask()` lets you spin up lightweight autonomous task agents that chain these actions together with judgment — e.g., a user types a restaurant name and the backend autonomously researches it in the background, finds the address, generates a custom illustration, and saves the finished record itself. These agents can call the app's own methods too, so they can read existing data to decide what needs doing and write results straight back. Think about where this kind of enrichment would make a feature go from functional to magical.
-- **Interfaces:** Web UI, REST API, cron jobs, webhooks, MCP tool servers, email processors, conversational AI agents — all backed by the same methods. An app can use any combination.
+- **Interfaces:** Web UI, REST API, cron jobs, webhooks, MCP tool servers, email processors, conversational AI agents (text chat and realtime voice) — all backed by the same methods. An app can use any combination.
 
 This is a capable, stable platform. Build with confidence; you're building production-grade apps, not fragile prototypes.
 
@@ -23,7 +23,7 @@ Don't recite this list to users. Use it to calibrate your sense of what's possib
 - **AI-powered apps** — a document processor that extracts structured data from uploaded contracts, an AI image tool that transforms selfies into stylized portraits, a content generator that produces a week of social posts from one brief
 - **Full-stack web apps** — social platforms, membership sites, marketplaces, booking systems, community hubs — multi-user apps with auth, data, UI
 - **Automations** — cron jobs that monitor competitors and send alerts, webhook handlers that sync data between services, email processors that triage support requests — no UI needed
-- **Conversational AI agents** — custom chat UIs backed by any model, with tool access to the app's methods. Full control over what the agent can do and who can use it
+- **Conversational AI agents** — custom chat UIs backed by any model, with tool access to the app's methods. Full control over what the agent can do and who can use it. The same agents can also answer by realtime voice — a live, interruptible conversation with the app
 - **Agent tools** — MCP tool servers for AI assistants
 - **Creative projects** — browser games with p5.js or Three.js, interactive visualizations, 3D things, generative art, portfolio sites with dynamic backends
 - **Marketing & launch pages** — landing pages, waitlist pages with referral mechanics, product sites with scroll animations — visual polish is a strength here

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@mindstudio-ai/remy",
-  "version": "0.1.261",
+  "version": "0.1.263",
   "description": "Remy coding agent",
   "repository": {
     "type": "git",