@stackbone/cli 0.9.1 → 0.9.2

package/migrations/0122_model_routing_object.sql

@@ -0,0 +1,16 @@
+-- 0122_model_routing_object.sql — a provider routing is OpenRouter's whole
+-- `provider` object (`{ "only": ["deepinfra/fp8"], "allow_fallbacks": false }`),
+-- not only its `sort`.
+--
+-- `routing` holds the object. `sort` stays, now nullable, and carries the routing
+-- only when it is nothing but a plain sort: an SDK older than the object reads
+-- `sort` alone, and it must see a routing it cannot apply as no routing, never
+-- apply half of it. Rows written before 0122 keep `routing` NULL; every reader
+-- falls back to `{ "sort": sort }`.
+--
+-- No CHECK on `routing`, for the reason 0121 has none on `sort`.
+ALTER TABLE stackbone_platform.model_routing
+    ADD COLUMN IF NOT EXISTS routing jsonb;
+
+ALTER TABLE stackbone_platform.model_routing
+    ALTER COLUMN sort DROP NOT NULL;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@stackbone/cli",
-  "version": "0.9.1",
+  "version": "0.9.2",
   "license": "UNLICENSED",
   "type": "module",
   "bin": {

package/voice-worker/main.js

@@ -149,7 +149,7 @@ var loadVad = async () => {
 };
 
 // libs/runtime/voice-worker/src/worker.ts
-import { log as log4, voice as voice4 } from "@livekit/agents";
+import { log as log5, voice as voice4 } from "@livekit/agents";
 import {
   BackgroundVoiceCancellation,
   TelephonyBackgroundVoiceCancellation
@@ -975,8 +975,12 @@ var turnSchema = z8.strictObject({
   mode: z8.enum(["stt", "livekit"]),
   minEndpointingDelayMs: millisecondsSchema,
   maxEndpointingDelayMs: millisecondsSchema,
-  detectorThreshold: thresholdSchema
+  detectorThreshold: thresholdSchema,
+  // Flux refuses under 0.3 and above its own end-of-turn threshold (0.7 by default,
+  // not a setting), so the bound is the range Flux takes with that default.
+  eagerThreshold: z8.number().min(0.3).max(0.7)
 });
+var VOICE_EAGER_THRESHOLD_DEFAULT = 0.3;
 var interruptionsSchema = z8.strictObject({
   enabled: z8.boolean(),
   minDurationMs: millisecondsSchema,
@@ -1017,7 +1021,12 @@ var effectiveVoiceSettingsObjectSchema = z8.strictObject({
   sttModel: z8.enum(VOICE_STT_MODELS),
   keyterms: keytermsSchema.default(() => []),
   vad: vadSchema,
-  turn: turnSchema,
+  // Defaulted here, on the read side only: a box older than STA3-94 answers, and
+  // dispatches, a `turn` without it. Not on `turnSchema`, whose `.partial()` layers
+  // would then all declare it.
+  turn: turnSchema.extend({
+    eagerThreshold: turnSchema.shape.eagerThreshold.default(VOICE_EAGER_THRESHOLD_DEFAULT)
+  }),
   interruptions: interruptionsSchema,
   ttsModel: z8.enum(VOICE_TTS_MODELS),
   /**
@@ -1105,6 +1114,7 @@ var VOICE_SETTINGS_LEAF_PATHS = [
   "turn.minEndpointingDelayMs",
   "turn.maxEndpointingDelayMs",
   "turn.detectorThreshold",
+  "turn.eagerThreshold",
   "interruptions.enabled",
   "interruptions.minDurationMs",
   "interruptions.minWords",
@@ -1129,11 +1139,19 @@ var VOICE_SETTINGS_LEAF_PATHS = [
   "refusalPhrase"
 ];
 var voiceSettingOriginSchema = z8.enum(["studio", "code", "default"]);
+var LEAVES_NEWER_THAN_SOME_BOXES = /* @__PURE__ */ new Set([
+  "turn.eagerThreshold"
+]);
 var effectiveVoiceSettingsViewSchema = z8.strictObject({
   value: effectiveVoiceSettingsObjectSchema,
   origins: z8.strictObject(
     Object.fromEntries(
-      VOICE_SETTINGS_LEAF_PATHS.map((path) => [path, voiceSettingOriginSchema])
+      // A leaf newer than the box answering does not come back: that box runs its default.
+      // Every other leaf stays required, so a box that drops one is still caught.
+      VOICE_SETTINGS_LEAF_PATHS.map((path) => [
+        path,
+        LEAVES_NEWER_THAN_SOME_BOXES.has(path) ? voiceSettingOriginSchema.default("default") : voiceSettingOriginSchema
+      ])
     )
   )
 });
@@ -1247,6 +1265,9 @@ var VOICE_CALLS_PATH = "/voice/v1/calls";
 var voiceCallBootstrapSchema = z8.strictObject({
   identities: integrationIdentitiesSchema.optional()
 });
+var voiceCallKnowledgeSchema = z8.strictObject({
+  text: z8.string().min(1).max(HEARD_TEXT_MAX)
+});
 var voiceCallTranscriptSchema = z8.array(
   z8.strictObject({
     role: z8.enum(["user", "assistant"]),
@@ -1266,7 +1287,9 @@ var voiceCallTurnMetricsSchema = z8.strictObject({
   transcriptionMs: turnLatencyMs,
   llmTtftMs: turnLatencyMs,
   ttsTtfbMs: turnLatencyMs,
-  e2eMs: turnLatencyMs
+  e2eMs: turnLatencyMs,
+  /** How long before the final transcript the turn's last eager end of turn left for the box (STA3-94). */
+  preflightLeadMs: turnLatencyMs
 });
 var voiceCallTurnsSchema = z8.array(voiceCallTurnMetricsSchema).max(VOICE_CALL_TURNS_MAX);
 var voiceCallCompleteSchema = z8.strictObject({
@@ -1316,6 +1339,7 @@ async function* readSseData(body) {
 // libs/runtime/voice-worker/src/box-wire.ts
 var BODY_EXCERPT_CHARS = 300;
 var TURN_IDLE_TIMEOUT_MS = 3e4;
+var KNOWLEDGE_TIMEOUT_MS = 2e3;
 var NON_ASCII = /[\u007f-\uffff]/g;
 var runErrorOf = ({ message, code }) => new Error(`box run failed${code ? ` (${code})` : ""}: ${message}`);
 var BoxTurnError = class extends Error {
@@ -1424,23 +1448,39 @@ var toWireEvent = (ev) => {
       return { kind: "other", type };
   }
 };
+var postCallOperation = (wire, operation, payload, timeoutMs) => fetch(
+  boxEndpoint(
+    wire.boxUrl,
+    `${VOICE_CALLS_PATH}/${encodeURIComponent(wire.sessionKey)}/${operation}`
+  ),
+  {
+    method: "POST",
+    headers: { "content-type": "application/json", authorization: `Bearer ${wire.token}` },
+    signal: AbortSignal.timeout(timeoutMs),
+    body: JSON.stringify(payload)
+  }
+);
 var voiceCallRequest = async (wire, operation, payload) => {
-  const response = await fetch(
-    boxEndpoint(
-      wire.boxUrl,
-      `${VOICE_CALLS_PATH}/${encodeURIComponent(wire.sessionKey)}/${operation}`
-    ),
-    {
-      method: "POST",
-      headers: { "content-type": "application/json", authorization: `Bearer ${wire.token}` },
-      signal: AbortSignal.timeout(TURN_IDLE_TIMEOUT_MS),
-      body: JSON.stringify(payload)
-    }
-  );
+  const response = await postCallOperation(wire, operation, payload, TURN_IDLE_TIMEOUT_MS);
   if (!response.ok)
     throw new BoxTurnError(wire.agent, response.status, await readExcerpt(response));
   voiceCallLifecycleResponseSchema.parse(await response.json());
 };
+var voiceCallKnowledge = async (wire, text) => {
+  try {
+    const response = await postCallOperation(
+      wire,
+      "knowledge",
+      { text },
+      KNOWLEDGE_TIMEOUT_MS
+    );
+    await response.body?.cancel().catch(() => void 0);
+    if (response.ok) return "sent";
+    return response.status === 404 ? "gone" : "failed";
+  } catch {
+    return "failed";
+  }
+};
 
 // libs/runtime/voice-worker/src/heard.ts
 var VOICE_RESPONSE_MARKER = "stackboneVoiceResponse";
@@ -1621,11 +1661,13 @@ var defined = (metrics) => Object.fromEntries(Object.entries(metrics).filter(([,
 var watchTurnMetrics = (session, write, options = {}) => {
   let caller;
   let delivered;
+  let lead;
   session.on(voice2.AgentSessionEventTypes.ConversationItemAdded, ({ item }) => {
     if (!(item instanceof llm.ChatMessage)) return;
     if (item.role === "user") {
       caller = item.metrics;
       delivered = options.endOfTurnMs?.();
+      lead = options.preflightLeadMs?.();
       return;
     }
     if (item.role !== "assistant") return;
@@ -1637,10 +1679,12 @@ var watchTurnMetrics = (session, write, options = {}) => {
       transcriptionMs: options.endOfTurnMs ? void 0 : ms(caller?.transcriptionDelay),
       llmTtftMs: ms(reply.llmNodeTtft),
       ttsTtfbMs: ms(reply.ttsNodeTtfb),
-      e2eMs: e2eMs === void 0 || delivered === void 0 ? e2eMs : e2eMs + delivered
+      e2eMs: e2eMs === void 0 || delivered === void 0 ? e2eMs : e2eMs + delivered,
+      preflightLeadMs: lead === void 0 ? void 0 : Math.round(lead)
     });
     caller = void 0;
     delivered = void 0;
+    lead = void 0;
     if (Object.keys(metrics).length === 0) return;
     write(typeof runId === "string" ? { ...metrics, runId } : metrics);
   });
@@ -1979,15 +2023,56 @@ var createHangUp = ({
 // libs/runtime/voice-worker/src/session-options.ts
 import { tts, voice as voice3 } from "@livekit/agents";
 
-// libs/runtime/voice-worker/src/number-text.ts
+// libs/runtime/voice-worker/src/knowledge-prefetch.ts
+import { log as log3, stt as stt2 } from "@livekit/agents";
 import { TransformStream as TransformStream2 } from "node:stream/web";
+var knowledgeTap = (send, { onLead, now = Date.now } = {}) => {
+  let sentThisTurn;
+  let sentAt;
+  let gone = false;
+  let failureLogged = false;
+  const tap = (event) => {
+    if (gone || typeof event === "string") return;
+    if (event.type === stt2.SpeechEventType.FINAL_TRANSCRIPT) {
+      if (sentAt !== void 0) onLead?.(now() - sentAt);
+      sentThisTurn = void 0;
+      sentAt = void 0;
+      return;
+    }
+    if (event.type !== stt2.SpeechEventType.PREFLIGHT_TRANSCRIPT) return;
+    const text = event.alternatives?.[0]?.text.trim();
+    if (!text || text === sentThisTurn) return;
+    sentThisTurn = text;
+    sentAt = now();
+    void send(text).then((answer) => {
+      if (answer === "gone") gone = true;
+      if (answer === "failed" && !failureLogged) {
+        failureLogged = true;
+        log3().warn(
+          "voice worker: the box refused a knowledge prefetch; turns search on their own"
+        );
+      }
+    }).catch(() => void 0);
+  };
+  return (events) => events.pipeThrough(
+    new TransformStream2({
+      transform(event, controller) {
+        tap(event);
+        controller.enqueue(event);
+      }
+    })
+  );
+};
+
+// libs/runtime/voice-worker/src/number-text.ts
+import { TransformStream as TransformStream3 } from "node:stream/web";
 var THOUSANDS_COMMA = /(\d),(?=\d{3}(?!\d))/g;
 var TRAILING_NUMBER = /[\d.,]+$/;
 var rewrite = (text) => text.replace(THOUSANDS_COMMA, "$1");
 var dropThousandsComma = (input) => {
   let pending = "";
   return input.pipeThrough(
-    new TransformStream2({
+    new TransformStream3({
       transform(chunk, controller) {
         const text = pending + chunk;
         const tail = TRAILING_NUMBER.exec(text)?.[0] ?? "";
@@ -2004,7 +2089,7 @@ var dropThousandsComma = (input) => {
 
 // libs/runtime/voice-worker/src/phone-voice.ts
 import { AudioFrame as AudioFrame2 } from "@livekit/rtc-node";
-import { TransformStream as TransformStream3 } from "node:stream/web";
+import { TransformStream as TransformStream4 } from "node:stream/web";
 var LOW_CUT_HZ = 300;
 var HIGH_CUT_HZ = 3400;
 var Q = Math.SQRT1_2;
@@ -2040,7 +2125,7 @@ var phoneLine = (audio) => {
   let chainRate = 0;
   const norm = Math.tanh(DRIVE);
   return audio.pipeThrough(
-    new TransformStream3({
+    new TransformStream4({
       transform(frame, controller) {
         if (!chain || chainRate !== frame.sampleRate) {
           chainRate = frame.sampleRate;
@@ -2066,11 +2151,18 @@ var phoneLine = (audio) => {
 };
 
 // libs/runtime/voice-worker/src/session-options.ts
-var sttOptions = ({ sttModel, language, keyterms }) => {
+var sttOptions = ({ sttModel, language, keyterms, turn }) => {
   const terms = keyterms.length > 0 ? [...keyterms] : void 0;
   const keyterm = terms ? { keyterm: terms } : void 0;
   if (sttModel.startsWith("deepgram/flux")) {
-    return { model: sttModel, modelOptions: { language_hint: language, ...keyterm } };
+    return {
+      model: sttModel,
+      modelOptions: {
+        language_hint: language,
+        ...keyterm,
+        eager_eot_threshold: turn.eagerThreshold
+      }
+    };
   }
   if (sttModel.startsWith("assemblyai/")) {
     return {
@@ -2094,12 +2186,28 @@ var markupContext = (expressive, speech) => {
   return guide === void 0 ? [] : [{ description: VOICE_TTS_MARKUP_CONTEXT, value: guide }];
 };
 var VoiceCallAgent = class extends voice3.Agent {
-  constructor() {
-    super(...arguments);
+  constructor({ sendKnowledge, ...options }) {
+    super(options);
     this.sttDelivery = createSttDeliveryMeter();
+    this.#knowledge = sendKnowledge && knowledgeTap(sendKnowledge, {
+      onLead: (ms2) => {
+        this.#preflightLead = ms2;
+      }
+    });
+  }
+  #knowledge;
+  #preflightLead;
+  /** The last turn's preflight head start in ms, once: a turn never reuses another's. */
+  takePreflightLead() {
+    const lead = this.#preflightLead;
+    this.#preflightLead = void 0;
+    return lead;
   }
   async sttNode(audio, modelSettings) {
-    return this.sttDelivery.wrap(audio, (counted) => super.sttNode(counted, modelSettings));
+    return this.sttDelivery.wrap(audio, async (counted) => {
+      const events = await super.sttNode(counted, modelSettings);
+      return events && this.#knowledge ? this.#knowledge(events) : events;
+    });
   }
 };
 var PhoneLineAgent = class extends VoiceCallAgent {
@@ -2116,6 +2224,11 @@ var voiceSessionOptions = (settings, pieces) => {
     minSilenceDuration: vad.minSilenceMs
   });
   const speech = pieces.createTts(ttsOptions(settings));
+  const agentOptions = {
+    // The box holds the prompt: LiveKit's own chat context stays prompt-less.
+    instructions: "",
+    sendKnowledge: pieces.sendKnowledge
+  };
   return {
     session: {
       vad: pieces.vad,
@@ -2155,14 +2268,13 @@ var voiceSessionOptions = (settings, pieces) => {
         preemptiveGeneration: { enabled: false, preemptiveTts: false }
       }
     },
-    // The box holds the prompt: LiveKit's own chat context stays prompt-less.
-    agent: settings.phoneLine ? new PhoneLineAgent({ instructions: "" }) : new VoiceCallAgent({ instructions: "" }),
+    agent: settings.phoneLine ? new PhoneLineAgent(agentOptions) : new VoiceCallAgent(agentOptions),
     boxContext: markupContext(settings.expressive, speech)
   };
 };
 
 // libs/runtime/voice-worker/src/telemetry/call-traces.ts
-import { log as log3, telemetry } from "@livekit/agents";
+import { log as log4, telemetry } from "@livekit/agents";
 import { ExportResultCode } from "@opentelemetry/core";
 import { defaultResource, resourceFromAttributes } from "@opentelemetry/resources";
 import {
@@ -2174,7 +2286,7 @@ var warnOnRefusedBatch = (exporter, sessionKey) => ({
   export: (spans, done) => exporter.export(spans, (result) => {
     try {
       if (result.code !== ExportResultCode.SUCCESS) {
-        log3().warn(
+        log4().warn(
           { sessionKey, error: result.error?.message ?? "unknown" },
           "voice worker: a batch of call spans failed to export to the box"
         );
@@ -2288,14 +2400,14 @@ var callerNoiseCancellation = (caller) => {
   try {
     return caller.kind === ParticipantKind.SIP ? TelephonyBackgroundVoiceCancellation() : BackgroundVoiceCancellation();
   } catch (err) {
-    log4().warn({ error: messageOf(err) }, "voice worker: no noise cancellation on this call");
+    log5().warn({ error: messageOf(err) }, "voice worker: no noise cancellation on this call");
     return void 0;
   }
 };
 var runVoiceJob = async (ctx, deps) => {
   const dispatch = readDispatch(ctx.job.metadata);
   if (!dispatch) {
-    log4().warn(
+    log5().warn(
       { metadataChars: ctx.job.metadata?.length ?? 0 },
       "voice worker: refused a job without a valid dispatch"
     );
@@ -2304,7 +2416,7 @@ var runVoiceJob = async (ctx, deps) => {
   }
   await ctx.connect();
   const caller = await ctx.waitForParticipant().catch((err) => {
-    log4().info(
+    log5().info(
       { reason: messageOf(err) },
       "voice worker: the room closed before the caller joined"
     );
@@ -2332,22 +2444,22 @@ var runVoiceJob = async (ctx, deps) => {
     try {
       session.say(text);
     } catch (err) {
-      log4().info({ error: messageOf(err) }, `voice worker: the ${what} was not spoken`);
+      log5().info({ error: messageOf(err) }, `voice worker: the ${what} was not spoken`);
     }
   };
   const hangUpAfter = (played, reason) => {
     ending = true;
     session.input.setAudioEnabled(false);
     void Promise.resolve().then(played).catch((err) => {
-      log4().info({ error: messageOf(err) }, "voice worker: the closing phrase was not spoken");
+      log5().info({ error: messageOf(err) }, "voice worker: the closing phrase was not spoken");
     }).then(() => ctx.deleteRoom()).catch((err) => {
-      log4().warn({ error: messageOf(err) }, "voice worker: the room was not deleted");
+      log5().warn({ error: messageOf(err) }, "voice worker: the room was not deleted");
     }).then(
       () => finishCall(
         reason === "turns kept failing" || reason === "box refused the call token" ? "failed" : "completed"
       )
     ).catch(() => {
-      log4().warn(
+      log5().warn(
         { agent: dispatch.agent, sessionKey: dispatch.sessionKey, reason: "completion_failed" },
         "voice worker: call finalization failed"
       );
@@ -2367,12 +2479,12 @@ var runVoiceJob = async (ctx, deps) => {
   });
   const onTurnError = (err) => {
     if (err instanceof BoxTurnError && err.status === 401) {
-      log4().error(boxFailure(err), "voice worker: the box refused the call token (401)");
+      log5().error(boxFailure(err), "voice worker: the box refused the call token (401)");
       if (!ending) endCall(CALL_CLOSING_PHRASE, "box refused the call token");
       return;
     }
     failedInARow += 1;
-    log4().warn({ ...boxFailure(err), failedInARow }, "voice worker: a turn failed");
+    log5().warn({ ...boxFailure(err), failedInARow }, "voice worker: a turn failed");
     if (ending) return;
     if (failedInARow >= MAX_FAILED_TURNS_IN_A_ROW) {
       endCall(CALL_CLOSING_PHRASE, "turns kept failing");
@@ -2384,13 +2496,20 @@ var runVoiceJob = async (ctx, deps) => {
     failedInARow = 0;
     if (outcome === "interrupt" && !ending) endCall(PAUSED_RUN_PHRASE, "run paused for review");
   };
-  const plan = voiceSessionOptions(settings, { ...deps, vad: ctx.proc.userData.vad });
-  const wire = {
+  const call = {
     boxUrl: dispatch.boxUrl,
     token: dispatch.callToken,
     agent: dispatch.agent,
     sessionKey: dispatch.sessionKey,
-    tags: dispatch.tags,
+    tags: dispatch.tags
+  };
+  const plan = voiceSessionOptions(settings, {
+    ...deps,
+    vad: ctx.proc.userData.vad,
+    sendKnowledge: (text) => voiceCallKnowledge(call, text)
+  });
+  const wire = {
+    ...call,
     // With `expressive`, the TTS markup guide: LiveKit gives it only to its own chat context.
     context: plan.boxContext
   };
@@ -2406,7 +2525,7 @@ var runVoiceJob = async (ctx, deps) => {
     hangUpAfter,
     isEnding: () => ending,
     onResumeFailed: (err) => {
-      log4().warn(boxFailure(err), "voice worker: the hang_up resume failed");
+      log5().warn(boxFailure(err), "voice worker: the hang_up resume failed");
     }
   });
   const brain = new BoxLLM({
@@ -2438,14 +2557,14 @@ var runVoiceJob = async (ctx, deps) => {
         if (!(turns.length > 0 && error instanceof BoxTurnError && error.status === 400)) {
           throw error;
         }
-        log4().warn(
+        log5().warn(
           { agent: dispatch.agent, sessionKey: dispatch.sessionKey, status: error.status },
           "voice worker: the box refused the turn metrics, completing without them"
         );
         await complete({ transcript, outcome });
       }
     }).catch((error) => {
-      log4().warn(
+      log5().warn(
         { agent: dispatch.agent, sessionKey: dispatch.sessionKey, reason: "completion_failed" },
         "voice worker: call finalization failed"
       );
@@ -2466,12 +2585,15 @@ var runVoiceJob = async (ctx, deps) => {
     session,
     (metrics) => {
       if (turns.length < VOICE_CALL_TURNS_MAX) turns.push(metrics);
-      log4().info(
+      log5().info(
         { agent: dispatch.agent, sessionKey: dispatch.sessionKey, room: ctx.room.name, ...metrics },
         VOICE_TURN_METRICS_MESSAGE
       );
     },
-    deliversItsOwnEndOfTurn(settings) ? { endOfTurnMs: () => plan.agent.sttDelivery.take() } : {}
+    {
+      ...deliversItsOwnEndOfTurn(settings) ? { endOfTurnMs: () => plan.agent.sttDelivery.take() } : {},
+      preflightLeadMs: () => plan.agent.takePreflightLead()
+    }
   );
   const noiseCancellation = callerNoiseCancellation(participant);
   await session.start({
@@ -2481,7 +2603,7 @@ var runVoiceJob = async (ctx, deps) => {
   });
   if (settings.greeting !== null) sayIfOpen(settings.greeting, "greeting");
   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");
+    log5().warn({ error: messageOf(err) }, "voice worker: the background audio did not start");
   });
 };