@stackbone/cli 0.8.0 → 0.9.1

package/voice-worker/main.js

@@ -10,20 +10,20 @@ import {
 } from "@livekit/agents";
 import { OTLPTraceExporter } from "@opentelemetry/exporter-trace-otlp-http";
 
-// libs/runtime/voice-worker/src/thinking-sound.ts
-import { voice } from "@livekit/agents";
+// libs/runtime/voice-worker/src/background-audio.ts
+import { audioFramesFromFile, voice } from "@livekit/agents";
 import { AudioFrame } from "@livekit/rtc-node";
 var SAMPLE_RATE = 48e3;
 var FRAME_MS = 20;
 var SAMPLES_PER_FRAME = SAMPLE_RATE * FRAME_MS / 1e3;
-var VOLUME = 0.12;
+var CHIME_LEVEL = 0.12;
 var PATTERN = [
   [660, 140],
   [0, 60],
   [880, 160],
   [0, 900]
 ];
-var renderPattern = () => {
+var renderChime = () => {
   const total = PATTERN.reduce((n, [, ms2]) => n + SAMPLE_RATE * ms2 / 1e3, 0);
   const pcm = new Int16Array(total);
   let offset = 0;
@@ -31,41 +31,89 @@ var renderPattern = () => {
     const length = SAMPLE_RATE * ms2 / 1e3;
     for (let i = 0; hz > 0 && i < length; i++) {
       const envelope = 0.5 - 0.5 * Math.cos(2 * Math.PI * i / length);
-      const sample = Math.sin(2 * Math.PI * hz * i / SAMPLE_RATE) * envelope * VOLUME;
+      const sample = Math.sin(2 * Math.PI * hz * i / SAMPLE_RATE) * envelope * CHIME_LEVEL;
       pcm[offset + i] = Math.round(sample * 32767);
     }
     offset += length;
   }
-  return pcm;
-};
-var LOOP = renderPattern();
-async function* thinkingCue() {
-  for (; ; ) {
-    for (let start = 0; start + SAMPLES_PER_FRAME <= LOOP.length; start += SAMPLES_PER_FRAME) {
-      yield new AudioFrame(
-        LOOP.slice(start, start + SAMPLES_PER_FRAME),
+  const frames = [];
+  for (let start = 0; start + SAMPLES_PER_FRAME <= total; start += SAMPLES_PER_FRAME) {
+    frames.push(
+      new AudioFrame(
+        pcm.slice(start, start + SAMPLES_PER_FRAME),
         SAMPLE_RATE,
         1,
         SAMPLES_PER_FRAME
-      );
-    }
+      )
+    );
   }
-}
-var startThinkingCue = async ({
+  return frames;
+};
+var looped = (frames) => ({
+  async *[Symbol.asyncIterator]() {
+    const loop = await frames();
+    if (loop.length === 0) return;
+    for (; ; ) yield* loop;
+  }
+});
+var CHIME_FRAMES = renderChime();
+var CHIME = looped(async () => CHIME_FRAMES);
+var LIVEKIT_CLIPS = {
+  "office-ambience": voice.BuiltinAudioClip.OFFICE_AMBIENCE,
+  "keyboard-typing": voice.BuiltinAudioClip.KEYBOARD_TYPING,
+  "keyboard-typing2": voice.BuiltinAudioClip.KEYBOARD_TYPING2,
+  "hold-music": voice.BuiltinAudioClip.HOLD_MUSIC
+};
+var decoded = /* @__PURE__ */ new Map();
+var clipFrames = (clip) => {
+  let frames = decoded.get(clip);
+  if (!frames) {
+    frames = (async () => {
+      const all = [];
+      const path = voice.getBuiltinAudioPath(LIVEKIT_CLIPS[clip]);
+      for await (const frame of audioFramesFromFile(path, { sampleRate: SAMPLE_RATE })) {
+        all.push(frame);
+      }
+      return all;
+    })();
+    frames.catch(() => decoded.delete(clip));
+    decoded.set(clip, frames);
+  }
+  return frames;
+};
+var CLIPS = new Map(
+  Object.keys(LIVEKIT_CLIPS).map((clip) => [
+    clip,
+    looped(() => clipFrames(clip))
+  ])
+);
+var backgroundSource = (sound, volume) => {
+  if (sound === "none" || volume <= 0) return void 0;
+  const source = sound === "chime" ? CHIME : CLIPS.get(sound);
+  return source && { source, volume };
+};
+var SILENT = Object.freeze({ start: () => void 0, stop: () => void 0 });
+var startBackgroundAudio = async ({
   room,
-  session
+  session,
+  audio
 }) => {
-  const player = new voice.BackgroundAudioPlayer();
-  await player.start({ room, agentSession: session });
+  const ambientSound = backgroundSource(audio.ambientSound, audio.ambientVolume);
+  const thinking = backgroundSource(audio.thinkingSound, audio.thinkingVolume);
+  if (!ambientSound && !thinking) return SILENT;
+  const player = new voice.BackgroundAudioPlayer(ambientSound ? { ambientSound } : {});
+  const clip = audio.thinkingSound;
+  await Promise.all([
+    player.start({ room, agentSession: session }),
+    thinking && clip !== "chime" && clip !== "none" ? clipFrames(clip) : void 0
+  ]);
+  if (!thinking) return SILENT;
   let playing;
   return {
     start: () => {
-      playing ??= player.play(thinkingCue());
+      playing = player.play(thinking);
     },
-    stop: () => {
-      playing?.stop();
-      playing = void 0;
-    }
+    stop: () => playing?.stop()
   };
 };
 
@@ -112,29 +160,165 @@ import { ParticipantKind } from "@livekit/rtc-node";
 import { z } from "zod";
 var jsonObject = () => z.looseObject({});
 
-// libs/shared/validators/src/lib/common/page.ts
+// libs/shared/validators/src/lib/studio/studio-model-provider.ts
 import { z as z2 } from "zod";
+var modelProviderSlotSchema = z2.enum(["baseUrl", "apiKey"]);
+var MODEL_PROVIDER_SLOTS = {
+  baseUrl: ["MODEL_PROVIDER_BASE_URL", "OPENROUTER_BASE_URL"],
+  apiKey: ["MODEL_PROVIDER_API_KEY", "OPENROUTER_API_KEY"]
+};
+var SLOT_NAMES = Object.keys(MODEL_PROVIDER_SLOTS);
+var MODEL_PROVIDER_DEPRECATED_ENV_NAMES = SLOT_NAMES.map(
+  (slot) => MODEL_PROVIDER_SLOTS[slot][1]
+);
+var modelProviderSourceSchema = z2.enum(["environment", "stored", "none"]);
+var isModelProviderValuePresent = (value) => typeof value === "string" && value.trim() !== "";
+var storedOverridesSchema = z2.strictObject({
+  baseUrl: z2.boolean().optional(),
+  apiKey: z2.boolean().optional()
+});
+var modelProviderKindSchema = z2.enum(["openrouter", "ollama", "lmstudio", "generic"]);
+var modelProviderGetResponseSchema = z2.object({
+  configured: z2.boolean(),
+  base_url: z2.string().nullable(),
+  api_key_masked: z2.string().nullable(),
+  source: modelProviderSourceSchema.optional(),
+  env_override: z2.array(z2.string()).optional(),
+  effective_base_url: z2.string().nullable().optional(),
+  // The gateway kind of the endpoint IN EFFECT (the one `effective_base_url`
+  // names), resolved by the box; `null` when nothing is configured. Optional for
+  // the same version-skew reason as `source`: a box that predates the field.
+  kind: modelProviderKindSchema.nullable().optional(),
+  // The slots where a Studio override beats an exported value (PLA-1825, ADR
+  // D8), by SLOT name, never the variable's (D4). Such a slot drops out of
+  // `env_override`, which keeps naming only the variables that actually win.
+  // A box that knows overrides always sends the list, empty or not; an absent
+  // list is a box that predates them, and would drop an `override` it cannot
+  // read, so Studio offers no Override against it.
+  overridden: z2.array(modelProviderSlotSchema).optional()
+});
+var modelProviderPutRequestSchema = z2.object({
+  base_url: z2.url(),
+  api_key: z2.string().optional().nullable(),
+  kind: modelProviderKindSchema.optional(),
+  override: z2.object({ baseUrl: z2.boolean().optional(), apiKey: z2.boolean().optional() }).optional()
+}).refine((body) => body.override?.apiKey !== true || isModelProviderValuePresent(body.api_key), {
+  message: "Overriding the API key needs the key to use.",
+  path: ["api_key"]
+});
+var modelProviderAgentsOutcomeSchema = z2.object({
+  /** Agents that were degraded and are now serving. */
+  ready: z2.number().int().nonnegative(),
+  /** Agents that are still degraded (their reason was refreshed by the retry). */
+  degraded: z2.number().int().nonnegative()
+});
+var modelProviderPutResponseSchema = modelProviderGetResponseSchema.extend({
+  agents: modelProviderAgentsOutcomeSchema.optional()
+});
+var modelProviderFirstRunResponseSchema = z2.object({
+  completed: z2.boolean()
+});
+var modelProviderKeyCheckSchema = z2.enum(["verified", "unverified"]);
+var modelProviderTestResponseSchema = z2.object({
+  ok: z2.boolean(),
+  model_count: z2.number().int().nonnegative().optional(),
+  error: z2.string().optional(),
+  key_checked: modelProviderKeyCheckSchema.optional()
+});
+var modelProviderModelTypeSchema = z2.enum(["chat", "image", "embedding", "other"]);
+var modelProviderModelSchema = z2.object({
+  id: z2.string().min(1),
+  name: z2.string().optional(),
+  context_length: z2.number().int().positive().optional(),
+  pricing: z2.object({
+    prompt: z2.string().optional(),
+    completion: z2.string().optional()
+  }).optional(),
+  owned_by: z2.string().optional(),
+  type: modelProviderModelTypeSchema.optional(),
+  // What the gateway says the model can do (PLA-1605): `true`, `false`, or
+  // `null` for "this gateway does not say". The three values are distinct on
+  // purpose — Studio hides a model that reports no tool support and only WARNS
+  // about one that reports nothing, so collapsing `null` into `false` would hide
+  // every model on a custom OpenAI-compatible endpoint.
+  //
+  // Nullable AND optional: a box on an older runtime sends neither field, and
+  // that must keep validating, exactly as `type` already does.
+  tools: z2.boolean().nullable().optional(),
+  reasoning: z2.boolean().nullable().optional(),
+  // STA3-17: on a box with several providers, the one that serves this entry.
+  // `responding: false` marks an entry remembered from a provider that is down.
+  // Declared so the parse keeps it: an object schema strips what it does not name.
+  provider: z2.object({ id: z2.string(), name: z2.string(), responding: z2.boolean() }).optional()
+});
+var modelProviderModelsRequestSchema = z2.object({
+  base_url: z2.url().optional().nullable(),
+  api_key: z2.string().optional().nullable()
+});
+var modelProviderModelsResponseSchema = z2.object({
+  ok: z2.boolean(),
+  models: z2.array(modelProviderModelSchema).optional(),
+  error: z2.string().optional(),
+  warning: z2.string().optional()
+});
+var MODEL_PROVIDER_DEFAULT_ID = "default";
+var MODEL_PROVIDER_ID_PATTERN = /^[a-z][a-z0-9-]{0,30}[a-z0-9]$/;
+var modelProviderIdSchema = z2.string().regex(MODEL_PROVIDER_ID_PATTERN, {
+  message: "Lowercase letters, digits and dashes, 2 to 32, starting with a letter."
+}).refine((id) => id !== MODEL_PROVIDER_DEFAULT_ID, {
+  message: `'${MODEL_PROVIDER_DEFAULT_ID}' is provider 1's id.`
+});
+var pickedModelProviderIdSchema = z2.string().regex(MODEL_PROVIDER_ID_PATTERN);
+var modelProviderListItemSchema = z2.object({
+  id: z2.string(),
+  name: z2.string(),
+  kind: modelProviderKindSchema,
+  baseUrl: z2.string(),
+  apiKey: z2.string().nullable(),
+  source: z2.enum(["env", "local"]),
+  removable: z2.boolean(),
+  responding: z2.boolean().nullable(),
+  error: z2.string().optional()
+});
+var modelProviderListResponseSchema = z2.object({
+  providers: z2.array(modelProviderListItemSchema),
+  duplicatedIds: z2.array(z2.object({ modelId: z2.string(), providerIds: z2.array(z2.string()) }))
+});
+var providerFields = {
+  name: z2.string().trim().min(1),
+  kind: modelProviderKindSchema,
+  baseUrl: z2.url(),
+  apiKey: z2.string().optional()
+};
+var modelProviderCreateRequestSchema = z2.strictObject({
+  id: modelProviderIdSchema,
+  ...providerFields
+});
+var modelProviderUpdateRequestSchema = z2.strictObject(providerFields);
+
+// libs/shared/validators/src/lib/common/page.ts
+import { z as z3 } from "zod";
 var PAGE_LIMIT_MAX = 100;
-var cursorParamSchema = z2.string().min(1);
-var limitParamSchema = (max = PAGE_LIMIT_MAX) => z2.coerce.number().int().min(1).max(max);
-var orderParamSchema = z2.enum(["asc", "desc"]);
-var pageQuerySchema = z2.object({
+var cursorParamSchema = z3.string().min(1);
+var limitParamSchema = (max = PAGE_LIMIT_MAX) => z3.coerce.number().int().min(1).max(max);
+var orderParamSchema = z3.enum(["asc", "desc"]);
+var pageQuerySchema = z3.object({
   cursor: cursorParamSchema.optional(),
   limit: limitParamSchema().optional(),
   order: orderParamSchema.optional()
 });
 var forwardPageQuerySchema = pageQuerySchema.omit({ order: true });
-var pageCursorSchema = z2.string().nullable();
-var pageResponseSchema = (item) => z2.object({ items: z2.array(item), nextCursor: pageCursorSchema, prevCursor: pageCursorSchema });
-var forwardPageResponseSchema = (item) => z2.object({ items: z2.array(item), nextCursor: pageCursorSchema });
+var pageCursorSchema = z3.string().nullable();
+var pageResponseSchema = (item) => z3.object({ items: z3.array(item), nextCursor: pageCursorSchema, prevCursor: pageCursorSchema });
+var forwardPageResponseSchema = (item) => z3.object({ items: z3.array(item), nextCursor: pageCursorSchema });
 
 // libs/shared/validators/src/lib/agents/runs.ts
-import { z as z4 } from "zod";
+import { z as z5 } from "zod";
 
 // libs/shared/validators/src/lib/common/system-entries.ts
-import { z as z3 } from "zod";
-var systemEntriesParamSchema = z3.enum(["include", "exclude"]);
-var systemEntriesQuerySchema = z3.object({
+import { z as z4 } from "zod";
+var systemEntriesParamSchema = z4.enum(["include", "exclude"]);
+var systemEntriesQuerySchema = z4.object({
   system: systemEntriesParamSchema.optional()
 });
 
@@ -147,7 +331,7 @@ var RUN_STATUSES = [
   "waiting",
   "cancelled"
 ];
-var runStatusSchema = z4.enum(RUN_STATUSES);
+var runStatusSchema = z5.enum(RUN_STATUSES);
 var RUN_TRIGGERS = [
   "manual",
   "webhook",
@@ -160,40 +344,40 @@ var RUN_TRIGGERS = [
   "platform",
   "unknown"
 ];
-var runTriggerSchema = z4.enum(RUN_TRIGGERS);
-var runEntityKindSchema = z4.enum(["agent", "workflow"]);
-var runTriggerLinkSchema = z4.object({
+var runTriggerSchema = z5.enum(RUN_TRIGGERS);
+var runEntityKindSchema = z5.enum(["agent", "workflow"]);
+var runTriggerLinkSchema = z5.object({
   /** The `trigger_subscriptions.id`: the link the Studio trigger page routes to. */
-  subscriptionId: z4.string(),
+  subscriptionId: z5.string(),
   /** The connector id, e.g. `gmail`. */
-  connector: z4.string(),
+  connector: z5.string(),
   /** The trigger id within the connector, e.g. `gmail_new_email_received`. */
-  trigger: z4.string(),
-  outcome: z4.enum(["started", "resumed"]).optional(),
+  trigger: z5.string(),
+  outcome: z5.enum(["started", "resumed"]).optional(),
   /** The connector's brand name, e.g. `Gmail`. */
-  connectorDisplayName: z4.string().optional(),
+  connectorDisplayName: z5.string().optional(),
   /** The trigger's name, e.g. `New Email`. */
-  triggerDisplayName: z4.string().optional(),
-  connectorLogoUrl: z4.string().optional()
+  triggerDisplayName: z5.string().optional(),
+  connectorLogoUrl: z5.string().optional()
 });
-var runSchema = z4.object({
-  id: z4.uuid(),
+var runSchema = z5.object({
+  id: z5.uuid(),
   status: runStatusSchema,
   trigger: runTriggerSchema,
-  createdAt: z4.iso.datetime(),
-  startedAt: z4.iso.datetime().nullable(),
-  finishedAt: z4.iso.datetime().nullable(),
-  durationMs: z4.number().int().nullable(),
-  traceId: z4.string().nullable(),
+  createdAt: z5.iso.datetime(),
+  startedAt: z5.iso.datetime().nullable(),
+  finishedAt: z5.iso.datetime().nullable(),
+  durationMs: z5.number().int().nullable(),
+  traceId: z5.string().nullable(),
   // True when the run was triggered from the Studio Playground (header
   // `STACKBONE_PLAYGROUND_HEADER` on `POST /api/invoke`). Billing and the Trust
   // Layer's verified metrics filter on this column to exclude stress-tests.
-  isPlayground: z4.boolean(),
+  isPlayground: z5.boolean(),
   // Name of the agent or workflow this run belongs to (migration 0020). Stamped
   // at run creation: the agent name for `chat` runs, the workflow name for
   // `workflow` runs. Combined with `trigger` the UI knows the kind. Null for
   // classic/manual cloud runs (deep-agent chat is dev-only), so the Runs screen renders `—`.
-  entityName: z4.string().nullable(),
+  entityName: z5.string().nullable(),
   // Which KIND of entity `entityName` names (STA-426, migration 0037). Stamped at
   // run creation next to the name, so an agent and a workflow that share a name stop
   // sharing one row set. Null for a run written before the column existed (no
@@ -208,22 +392,22 @@ var runSchema = z4.object({
   // `trigger_subscriptions.id`, stamped at start for `trigger: 'event'` and null
   // for every other gate. Optional as well as nullable for the reason `entityKind`
   // is: an older box does not send the field.
-  triggerRef: z4.string().nullable().optional(),
+  triggerRef: z5.string().nullable().optional(),
   // The Connect link that started or resumed the run, with its names (PLA-1898).
   // Null for a run no link started; optional for the reason `entityKind` is.
   triggerLink: runTriggerLinkSchema.nullable().optional(),
   input: jsonObject().nullable(),
   output: jsonObject().nullable(),
-  error: z4.object({ message: z4.string(), stack: z4.string().optional() }).nullable(),
+  error: z5.object({ message: z5.string(), stack: z5.string().optional() }).nullable(),
   // Per-turn token usage for deep-agent CHAT runs (feature 68, A5): the chat
   // recorder folds the turn's usage and stamps the four token counters onto the run.
   // Null when the run had no model call; `totalTokens` is derived at read
   // (`input + output`), never stored. No $ cost (D5).
-  inputTokens: z4.number().int().nullable(),
-  outputTokens: z4.number().int().nullable(),
-  cacheReadTokens: z4.number().int().nullable(),
-  cacheWriteTokens: z4.number().int().nullable(),
-  totalTokens: z4.number().int().nullable(),
+  inputTokens: z5.number().int().nullable(),
+  outputTokens: z5.number().int().nullable(),
+  cacheReadTokens: z5.number().int().nullable(),
+  cacheWriteTokens: z5.number().int().nullable(),
+  totalTokens: z5.number().int().nullable(),
   /**
    * The run's own `metadata` jsonb, verbatim (PLA-1272 slice 4).
    *
@@ -244,37 +428,37 @@ var runSchema = z4.object({
    */
   metadata: jsonObject().nullable().optional()
 });
-var schemaIssueSchema = z4.object({
+var schemaIssueSchema = z5.object({
   /** Path segments to the offending field (`[]` for the root value). */
-  path: z4.array(z4.union([z4.string(), z4.number()])),
-  message: z4.string()
+  path: z5.array(z5.union([z5.string(), z5.number()])),
+  message: z5.string()
 });
-var runOutputViolationSchema = z4.object({
+var runOutputViolationSchema = z5.object({
   /** The workflow whose declared `outputSchema` the return value broke. */
-  workflowName: z4.string(),
-  issues: z4.array(schemaIssueSchema),
+  workflowName: z5.string(),
+  issues: z5.array(schemaIssueSchema),
   /**
    * When the projector observed it (ISO). Not the run's `finishedAt`: the run
    * closed at that instant whether or not anything validated it.
    */
-  recordedAt: z4.string()
+  recordedAt: z5.string()
 });
-var runIdParamSchema = z4.object({ runId: z4.uuid() });
-var runTagKeySchema = z4.string().regex(/^[a-z][a-z0-9_.-]{0,63}$/);
+var runIdParamSchema = z5.object({ runId: z5.uuid() });
+var runTagKeySchema = z5.string().regex(/^[a-z][a-z0-9_.-]{0,63}$/);
 var RUN_TAG_VALUE_MAX = 256;
 var RUN_TAGS_MAX = 16;
 var UNSTORABLE_TAG_CHAR = (
   // eslint-disable-next-line no-control-regex
   /[\u0000-\u001f\u007f]|[\ud800-\udbff](?![\udc00-\udfff])|(?<![\ud800-\udbff])[\udc00-\udfff]/
 );
-var runTagValueSchema = z4.string().min(1).max(RUN_TAG_VALUE_MAX).refine((value) => !UNSTORABLE_TAG_CHAR.test(value), {
+var runTagValueSchema = z5.string().min(1).max(RUN_TAG_VALUE_MAX).refine((value) => !UNSTORABLE_TAG_CHAR.test(value), {
   message: "A tag value holds no control character and no lone surrogate."
 });
 var splitRunTagFilter = (tag) => {
   const colon = tag.indexOf(":");
   return colon < 0 ? null : { key: tag.slice(0, colon), value: tag.slice(colon + 1) };
 };
-var runTagFilterSchema = z4.string().superRefine((tag, ctx) => {
+var runTagFilterSchema = z5.string().superRefine((tag, ctx) => {
   const filter = splitRunTagFilter(tag);
   if (!filter) {
     ctx.addIssue({ code: "custom", message: "A tag filter is `key:value`." });
@@ -296,17 +480,17 @@ var runTagFilterSchema = z4.string().superRefine((tag, ctx) => {
 var listRunsQuerySchema = pageQuerySchema.extend({
   status: runStatusSchema.optional(),
   trigger: runTriggerSchema.optional(),
-  from: z4.iso.datetime().optional(),
-  to: z4.iso.datetime().optional(),
+  from: z5.iso.datetime().optional(),
+  to: z5.iso.datetime().optional(),
   // Feature 69 — the Sessions detail screen reads a conversation's turns with
   // `GET /runs?session_id=<id>&order=asc`. `session_id` is the real
   // `runs.session_id` join column (the deterministic UUIDv5 of the deep-agent
   // session key), so it is exact-match on the indexed column.
-  session_id: z4.uuid().optional(),
+  session_id: z5.uuid().optional(),
   // Migration 0020 — the Runs screen filters to one agent/workflow by its
   // exact name (the value picked from the name dropdown, or deep-linked from
   // the agent/workflow detail's "View runs"). Exact-match on `runs.entity_name`.
-  name: z4.string().min(1).optional(),
+  name: z5.string().min(1).optional(),
   // STA-426 — narrow the name filter to ONE kind of entity, so "the runs of the
   // workflow named sync" excludes the agent that shares the name. A row that
   // DECLARES the other kind is always excluded; a row whose kind was never stamped
@@ -320,8 +504,8 @@ var listRunsQuerySchema = pageQuerySchema.extend({
   // or boolean matches its JSON spelling (`3`, `true`). The ONE filter here that is
   // not exact-match: it serves a search box, and a search box that needs the whole
   // address typed without a typo is not one. Nested paths are out of scope.
-  input_key: z4.string().min(1).optional(),
-  input_value: z4.string().min(1).optional(),
+  input_key: z5.string().min(1).optional(),
+  input_value: z5.string().min(1).optional(),
   // PLA-1785 — `exclude` leaves out the runs of the platform's own entries
   // (`studio-copilot`, `mapping-suggest`, `rag-ingest`), decided by the box's
   // `isSystemEntry` and applied before the cursor and the LIMIT, so a page stays
@@ -341,179 +525,43 @@ var listRunsQuerySchema = pageQuerySchema.extend({
   path: ["input_key"]
 });
 var runListResponseSchema = pageResponseSchema(runSchema);
-var runEntityEntrySchema = z4.object({
-  name: z4.string(),
+var runEntityEntrySchema = z5.object({
+  name: z5.string(),
   kind: runEntityKindSchema.nullable()
 });
-var runEntityNamesResponseSchema = z4.object({
-  names: z4.array(z4.string()),
-  entries: z4.array(runEntityEntrySchema).optional()
+var runEntityNamesResponseSchema = z5.object({
+  names: z5.array(z5.string()),
+  entries: z5.array(runEntityEntrySchema).optional()
 });
-var cancelRunResponseSchema = z4.object({
+var cancelRunResponseSchema = z5.object({
   run: runSchema
 });
 var STACKBONE_SESSION_HEADER = "x-stackbone-session";
 var RUN_TAGS_HEADER = "x-stackbone-run-tags";
-var fixtureSchema = z4.object({
-  id: z4.string(),
-  name: z4.string(),
+var fixtureSchema = z5.object({
+  id: z5.string(),
+  name: z5.string(),
   input: jsonObject().nullable(),
-  description: z4.string().nullable(),
-  createdAt: z4.iso.datetime()
+  description: z5.string().nullable(),
+  createdAt: z5.iso.datetime()
 });
-var createFixtureRequestSchema = z4.object({
-  name: z4.string().min(1).max(120),
+var createFixtureRequestSchema = z5.object({
+  name: z5.string().min(1).max(120),
   input: jsonObject(),
-  description: z4.string().max(2e3).optional().nullable()
+  description: z5.string().max(2e3).optional().nullable()
 });
 var fixtureListResponseSchema = pageResponseSchema(fixtureSchema);
-var fixtureIdParamSchema = z4.object({ fxtId: z4.uuid() });
-var handlerSchemaSchema = z4.object({
+var fixtureIdParamSchema = z5.object({ fxtId: z5.uuid() });
+var handlerSchemaSchema = z5.object({
   input: jsonObject().nullable(),
   output: jsonObject().nullable()
 });
-var schemaResponseSchema = z4.object({
+var schemaResponseSchema = z5.object({
   input: jsonObject().nullable(),
   output: jsonObject().nullable(),
   handlers: jsonObject().nullable().optional()
 });
 
-// libs/shared/validators/src/lib/studio/studio-model-provider.ts
-import { z as z5 } from "zod";
-var modelProviderSlotSchema = z5.enum(["baseUrl", "apiKey"]);
-var MODEL_PROVIDER_SLOTS = {
-  baseUrl: ["MODEL_PROVIDER_BASE_URL", "OPENROUTER_BASE_URL"],
-  apiKey: ["MODEL_PROVIDER_API_KEY", "OPENROUTER_API_KEY"]
-};
-var SLOT_NAMES = Object.keys(MODEL_PROVIDER_SLOTS);
-var MODEL_PROVIDER_DEPRECATED_ENV_NAMES = SLOT_NAMES.map(
-  (slot) => MODEL_PROVIDER_SLOTS[slot][1]
-);
-var modelProviderSourceSchema = z5.enum(["environment", "stored", "none"]);
-var isModelProviderValuePresent = (value) => typeof value === "string" && value.trim() !== "";
-var storedOverridesSchema = z5.strictObject({
-  baseUrl: z5.boolean().optional(),
-  apiKey: z5.boolean().optional()
-});
-var modelProviderKindSchema = z5.enum(["openrouter", "ollama", "lmstudio", "generic"]);
-var modelProviderGetResponseSchema = z5.object({
-  configured: z5.boolean(),
-  base_url: z5.string().nullable(),
-  api_key_masked: z5.string().nullable(),
-  source: modelProviderSourceSchema.optional(),
-  env_override: z5.array(z5.string()).optional(),
-  effective_base_url: z5.string().nullable().optional(),
-  // The gateway kind of the endpoint IN EFFECT (the one `effective_base_url`
-  // names), resolved by the box; `null` when nothing is configured. Optional for
-  // the same version-skew reason as `source`: a box that predates the field.
-  kind: modelProviderKindSchema.nullable().optional(),
-  // The slots where a Studio override beats an exported value (PLA-1825, ADR
-  // D8), by SLOT name, never the variable's (D4). Such a slot drops out of
-  // `env_override`, which keeps naming only the variables that actually win.
-  // A box that knows overrides always sends the list, empty or not; an absent
-  // list is a box that predates them, and would drop an `override` it cannot
-  // read, so Studio offers no Override against it.
-  overridden: z5.array(modelProviderSlotSchema).optional()
-});
-var modelProviderPutRequestSchema = z5.object({
-  base_url: z5.url(),
-  api_key: z5.string().optional().nullable(),
-  kind: modelProviderKindSchema.optional(),
-  override: z5.object({ baseUrl: z5.boolean().optional(), apiKey: z5.boolean().optional() }).optional()
-}).refine((body) => body.override?.apiKey !== true || isModelProviderValuePresent(body.api_key), {
-  message: "Overriding the API key needs the key to use.",
-  path: ["api_key"]
-});
-var modelProviderAgentsOutcomeSchema = z5.object({
-  /** Agents that were degraded and are now serving. */
-  ready: z5.number().int().nonnegative(),
-  /** Agents that are still degraded (their reason was refreshed by the retry). */
-  degraded: z5.number().int().nonnegative()
-});
-var modelProviderPutResponseSchema = modelProviderGetResponseSchema.extend({
-  agents: modelProviderAgentsOutcomeSchema.optional()
-});
-var modelProviderFirstRunResponseSchema = z5.object({
-  completed: z5.boolean()
-});
-var modelProviderKeyCheckSchema = z5.enum(["verified", "unverified"]);
-var modelProviderTestResponseSchema = z5.object({
-  ok: z5.boolean(),
-  model_count: z5.number().int().nonnegative().optional(),
-  error: z5.string().optional(),
-  key_checked: modelProviderKeyCheckSchema.optional()
-});
-var modelProviderModelTypeSchema = z5.enum(["chat", "image", "embedding", "other"]);
-var modelProviderModelSchema = z5.object({
-  id: z5.string().min(1),
-  name: z5.string().optional(),
-  context_length: z5.number().int().positive().optional(),
-  pricing: z5.object({
-    prompt: z5.string().optional(),
-    completion: z5.string().optional()
-  }).optional(),
-  owned_by: z5.string().optional(),
-  type: modelProviderModelTypeSchema.optional(),
-  // What the gateway says the model can do (PLA-1605): `true`, `false`, or
-  // `null` for "this gateway does not say". The three values are distinct on
-  // purpose — Studio hides a model that reports no tool support and only WARNS
-  // about one that reports nothing, so collapsing `null` into `false` would hide
-  // every model on a custom OpenAI-compatible endpoint.
-  //
-  // Nullable AND optional: a box on an older runtime sends neither field, and
-  // that must keep validating, exactly as `type` already does.
-  tools: z5.boolean().nullable().optional(),
-  reasoning: z5.boolean().nullable().optional(),
-  // STA3-17: on a box with several providers, the one that serves this entry.
-  // `responding: false` marks an entry remembered from a provider that is down.
-  // Declared so the parse keeps it: an object schema strips what it does not name.
-  provider: z5.object({ id: z5.string(), name: z5.string(), responding: z5.boolean() }).optional()
-});
-var modelProviderModelsRequestSchema = z5.object({
-  base_url: z5.url().optional().nullable(),
-  api_key: z5.string().optional().nullable()
-});
-var modelProviderModelsResponseSchema = z5.object({
-  ok: z5.boolean(),
-  models: z5.array(modelProviderModelSchema).optional(),
-  error: z5.string().optional(),
-  warning: z5.string().optional()
-});
-var MODEL_PROVIDER_DEFAULT_ID = "default";
-var MODEL_PROVIDER_ID_PATTERN = /^[a-z][a-z0-9-]{0,30}[a-z0-9]$/;
-var modelProviderIdSchema = z5.string().regex(MODEL_PROVIDER_ID_PATTERN, {
-  message: "Lowercase letters, digits and dashes, 2 to 32, starting with a letter."
-}).refine((id) => id !== MODEL_PROVIDER_DEFAULT_ID, {
-  message: `'${MODEL_PROVIDER_DEFAULT_ID}' is provider 1's id.`
-});
-var pickedModelProviderIdSchema = z5.string().regex(MODEL_PROVIDER_ID_PATTERN);
-var modelProviderListItemSchema = z5.object({
-  id: z5.string(),
-  name: z5.string(),
-  kind: modelProviderKindSchema,
-  baseUrl: z5.string(),
-  apiKey: z5.string().nullable(),
-  source: z5.enum(["env", "local"]),
-  removable: z5.boolean(),
-  responding: z5.boolean().nullable(),
-  error: z5.string().optional()
-});
-var modelProviderListResponseSchema = z5.object({
-  providers: z5.array(modelProviderListItemSchema),
-  duplicatedIds: z5.array(z5.object({ modelId: z5.string(), providerIds: z5.array(z5.string()) }))
-});
-var providerFields = {
-  name: z5.string().trim().min(1),
-  kind: modelProviderKindSchema,
-  baseUrl: z5.url(),
-  apiKey: z5.string().optional()
-};
-var modelProviderCreateRequestSchema = z5.strictObject({
-  id: modelProviderIdSchema,
-  ...providerFields
-});
-var modelProviderUpdateRequestSchema = z5.strictObject(providerFields);
-
 // libs/shared/validators/src/lib/studio/studio-voice.ts
 import { z as z8 } from "zod";
 
@@ -907,6 +955,14 @@ var VOICE_TTS_MODELS = [
   "gradium/default"
 ];
 var isCartesiaTtsModel = (model) => model.startsWith("cartesia/") && VOICE_TTS_MODELS.includes(model);
+var VOICE_BACKGROUND_CLIPS = [
+  "office-ambience",
+  "keyboard-typing",
+  "keyboard-typing2",
+  "hold-music"
+];
+var VOICE_AMBIENT_SOUNDS = ["none", ...VOICE_BACKGROUND_CLIPS];
+var VOICE_THINKING_SOUNDS = ["none", "chime", ...VOICE_BACKGROUND_CLIPS];
 var thresholdSchema = z8.number().min(0).max(1);
 var millisecondsSchema = z8.int().min(0).max(1e4);
 var keytermsSchema = z8.array(z8.string().trim().min(1).max(64)).max(50);
@@ -934,6 +990,27 @@ var ragSchema = z8.strictObject({
   timeoutMs: z8.int().min(200).max(1e4),
   previousExchanges: z8.int().min(0).max(5)
 });
+var volumeSchema = z8.number().min(0).max(1);
+var backgroundAudioSchema = z8.strictObject({
+  ambientSound: z8.enum(VOICE_AMBIENT_SOUNDS),
+  ambientVolume: volumeSchema,
+  thinkingSound: z8.enum(VOICE_THINKING_SOUNDS),
+  thinkingVolume: volumeSchema,
+  /**
+   * How long a reply's wait runs before the thinking sound starts, when no box tool
+   * call is open (a tool call starts it at once). Every turn waits for the knowledge
+   * search and the model's first token, about 1.4 s at the median on a voice box
+   * (2026-11-09), so a delay under that plays the sound on nearly every reply.
+   */
+  thinkingDelayMs: millisecondsSchema
+});
+var VOICE_BACKGROUND_AUDIO_DEFAULTS = Object.freeze({
+  ambientSound: "office-ambience",
+  ambientVolume: 0.7,
+  thinkingSound: "keyboard-typing",
+  thinkingVolume: 0.6,
+  thinkingDelayMs: 2e3
+});
 var effectiveVoiceSettingsObjectSchema = z8.strictObject({
   /** BCP-47-ish tag the STT is hinted with and the TTS speaks (`es`, `en-US`), or `multi`. */
   language: z8.string().max(16).regex(/^[A-Za-z]{2,8}(?:-[A-Za-z0-9]{1,8})*$/),
@@ -960,6 +1037,7 @@ var effectiveVoiceSettingsObjectSchema = z8.strictObject({
   phoneLine: z8.boolean(),
   /** LiveKit expressive mode: the turn gets Cartesia's markup guide (D5). Cartesia only. */
   expressive: z8.boolean(),
+  backgroundAudio: backgroundAudioSchema,
   /**
    * Whether the box records the call to its bucket (D30). Off, no egress starts: a
    * box may not be allowed to keep a caller's audio. The box alone reads it, so the
@@ -1007,6 +1085,13 @@ var callVoiceSettingsObjectSchema = effectiveVoiceSettingsObjectSchema.omit({
   recording: true,
   rag: true,
   refusalPhrase: true
+}).extend({
+  // A box older than `thinkingDelayMs` dispatches the group without it.
+  backgroundAudio: backgroundAudioSchema.extend({
+    thinkingDelayMs: millisecondsSchema.default(
+      VOICE_BACKGROUND_AUDIO_DEFAULTS.thinkingDelayMs
+    )
+  }).default(() => ({ ...VOICE_BACKGROUND_AUDIO_DEFAULTS }))
 });
 var callVoiceSettingsSchema = callVoiceSettingsObjectSchema.superRefine(checkCrossFieldRules);
 var VOICE_SETTINGS_LEAF_PATHS = [
@@ -1029,6 +1114,11 @@ var VOICE_SETTINGS_LEAF_PATHS = [
   "greeting",
   "phoneLine",
   "expressive",
+  "backgroundAudio.ambientSound",
+  "backgroundAudio.ambientVolume",
+  "backgroundAudio.thinkingSound",
+  "backgroundAudio.thinkingVolume",
+  "backgroundAudio.thinkingDelayMs",
   "recording",
   "rag.collection",
   "rag.minScore",
@@ -1061,7 +1151,8 @@ var voiceSettingsSchema = effectiveVoiceSettingsObjectSchema.extend({
   vad: vadSchema.partial(),
   turn: turnSchema.partial(),
   interruptions: interruptionsSchema.partial(),
-  rag: ragSchema.partial()
+  rag: ragSchema.partial(),
+  backgroundAudio: backgroundAudioSchema.partial()
 }).partial().superRefine(checkCrossFieldRules).superRefine(checkTtsPair);
 var checkStudioTtsPair = (value, ctx) => {
   if (value.ttsVoice !== void 0 && value.ttsModel === void 0) {
@@ -2143,23 +2234,52 @@ var CALL_CLOSING_PHRASE = Object.freeze({
 });
 var MAX_FAILED_TURNS_IN_A_ROW = 3;
 var inCallLanguage = (phrase, language) => language.split("-")[0]?.toLowerCase() === "es" ? phrase.es : phrase.en;
-var toolCallCue = () => {
+var thinkingCue = (delayMs) => {
   let cue;
   let open = 0;
+  let waitedLong = false;
+  let wait;
+  let playing = false;
+  const sync = () => {
+    const play = waitedLong || open > 0;
+    if (play === playing || !cue) return;
+    playing = play;
+    if (play) cue.start();
+    else cue.stop();
+  };
   return {
-    // A call can open before the cue's track is up.
+    // A turn can start before the track is up.
     attach: (ready) => {
       cue = ready;
-      if (open > 0) cue.start();
+      sync();
     },
-    onToolCall: (phase) => {
-      if (phase === "start") {
-        open += 1;
-        if (open === 1) cue?.start();
-      } else if (open > 0) {
-        open -= 1;
-        if (open === 0) cue?.stop();
+    onAgentState: (state) => {
+      if (state !== "thinking") {
+        clearTimeout(wait);
+        wait = void 0;
+        waitedLong = false;
+        sync();
+        return;
       }
+      if (wait !== void 0 || waitedLong) return;
+      wait = setTimeout(() => {
+        wait = void 0;
+        waitedLong = true;
+        sync();
+      }, delayMs);
+    },
+    onToolCall: (phase) => {
+      if (phase === "start") open += 1;
+      else if (open > 0) open -= 1;
+      sync();
+    },
+    /** The call is ending: a pending delay must not start the sound in a closed room. */
+    close: () => {
+      clearTimeout(wait);
+      wait = void 0;
+      waitedLong = false;
+      open = 0;
+      sync();
     }
   };
 };
@@ -2204,7 +2324,7 @@ var runVoiceJob = async (ctx, deps) => {
     deps
   );
   const settings = dispatch.voiceSettings;
-  const cue = toolCallCue();
+  const cue = thinkingCue(settings.backgroundAudio.thinkingDelayMs);
   const fallback = inCallLanguage(TURN_FALLBACK_PHRASE, settings.language);
   let failedInARow = 0;
   let ending = false;
@@ -2305,6 +2425,7 @@ var runVoiceJob = async (ctx, deps) => {
   const finishCall = (outcome = "disconnected") => {
     if (completion) return completion;
     ending = true;
+    cue.close();
     completion = Promise.resolve().then(async () => {
       await hangUp.pendingResume();
       await session.close();
@@ -2333,6 +2454,10 @@ var runVoiceJob = async (ctx, deps) => {
     return completion;
   };
   ctx.addShutdownCallback(() => finishCall());
+  session.on(
+    voice4.AgentSessionEventTypes.AgentStateChanged,
+    ({ newState }) => cue.onAgentState(newState)
+  );
   session.on(voice4.AgentSessionEventTypes.Close, () => {
     if (completion || ending) return;
     void finishCall().catch(() => void 0).finally(() => ctx.shutdown("caller left"));
@@ -2355,8 +2480,8 @@ var runVoiceJob = async (ctx, deps) => {
     inputOptions: noiseCancellation ? { noiseCancellation } : {}
   });
   if (settings.greeting !== null) sayIfOpen(settings.greeting, "greeting");
-  await deps.createCue({ room: ctx.room, session }).then(cue.attach, (err) => {
-    log4().warn({ error: messageOf(err) }, "voice worker: the thinking cue did not start");
+  await deps.createCue({ room: ctx.room, session, audio: settings.backgroundAudio }).then(cue.attach, (err) => {
+    log4().warn({ error: messageOf(err) }, "voice worker: the background audio did not start");
   });
 };
 
@@ -2366,7 +2491,7 @@ var liveDeps = () => ({
   createStt: (options) => new inference.STT(options),
   createTts: (options) => new inference.TTS(options),
   createTurnDetector: (options) => new inference.TurnDetector(options),
-  createCue: startThinkingCue,
+  createCue: startBackgroundAudio,
   // OTLP/HTTP JSON, uncompressed: the encoding the box relay takes and forwards as is.
   // `compression` is set so an `OTEL_EXPORTER_OTLP_COMPRESSION=gzip` in the worker's
   // environment cannot turn every export into a body the relay refuses.