@juspay/neurolink 12.6.0 → 12.7.0

package/dist/cli/proxy-clients/gemini.js

@@ -57,20 +57,49 @@ function upsertEnvVars(original, vars) {
         // Match an assignment at line start, tolerating `export ` and surrounding
         // spaces. Anchored per-line so a key mentioned inside a comment or another
         // value is not rewritten.
-        const re = new RegExp(`^[ \\t]*(?:export[ \\t]+)?${key}[ \\t]*=.*$`, "m");
         const line = `${key}=${value}`;
+        const all = new RegExp(`^[ \t]*(?:export[ \t]+)?${key}[ \t]*=.*(?:\r?\n|$)`, "gm");
+        const occurrences = text.match(all)?.length ?? 0;
+        if (occurrences === 0) {
+            text = `${text.length > 0 && !text.endsWith("\n") ? `${text}\n` : text}${line}\n`;
+            continue;
+        }
+        // Rewrite the FIRST occurrence in place — position is the user's and a
+        // byte-exact restore depends on keeping it — then drop any later ones.
+        //
+        // Dropping them is not tidiness. Gemini CLI's dotenv takes the LAST
+        // assignment: with a duplicate left in place our value is silently
+        // overridden and Gemini talks to Google while the writer reports success.
+        // Measured: a .env with the proxy URL first and a dead port second sent the
+        // request to the dead port.
+        let seen = 0;
         // A function replacement, never a string: `String.replace` expands `$&`,
         // `$1` and friends inside a replacement *string*, so a proxy key
         // containing `$&` would be stored as the matched assignment instead of
-        // itself. The callback form treats the value as literal.
-        text = re.test(text)
-            ? text.replace(re, () => line)
-            : `${text.length > 0 && !text.endsWith("\n") ? `${text}\n` : text}${line}\n`;
+        // itself.
+        text = text.replace(all, (match) => {
+            seen += 1;
+            if (seen > 1) {
+                return "";
+            }
+            // Re-emit the terminator that was matched, not an assumed LF. The regex
+            // captures `\r?\n`, and `"…\r\n".endsWith("\n")` is true, so testing for
+            // LF alone silently rewrote a CRLF line ending to LF — breaking the
+            // byte-exact round-trip this function's own contract promises, on the
+            // ordinary single-occurrence path rather than only on duplicates.
+            // Gemini CLI is cross-platform; a Windows-authored .env is not exotic.
+            const terminator = match.endsWith("\r\n")
+                ? "\r\n"
+                : match.endsWith("\n")
+                    ? "\n"
+                    : "";
+            return `${line}${terminator}`;
+        });
     }
     return text;
 }
 /**
- * Read the managed variables' values out of an `.env` body.
+ * Read the managed variables' effective values out of an `.env` body.
  *
  * Restore needs the original *values*, not the original file: replaying a
  * whole snapshot would discard everything the user changed after apply().
@@ -78,9 +107,14 @@ function upsertEnvVars(original, vars) {
 function readManagedVars(envText) {
     const out = {};
     for (const key of [BASE_URL_VAR, API_KEY_VAR]) {
-        const m = new RegExp(`^[ \\t]*(?:export[ \\t]+)?${key}[ \\t]*=(.*)$`, "m").exec(envText);
-        if (m) {
-            out[key] = m[1] ?? "";
+        // The LAST assignment, because that is the one dotenv resolves to. Reading
+        // the first would restore a value the CLI never actually used.
+        const all = [
+            ...envText.matchAll(new RegExp(`^[ \\t]*(?:export[ \\t]+)?${key}[ \\t]*=(.*)$`, "gm")),
+        ];
+        const last = all[all.length - 1];
+        if (last) {
+            out[key] = last[1] ?? "";
         }
     }
     return out;
@@ -89,7 +123,10 @@ function readManagedVars(envText) {
 function removeEnvVars(original, keys) {
     let text = original;
     for (const key of keys) {
-        const re = new RegExp(`^[ \\t]*(?:export[ \\t]+)?${key}[ \\t]*=.*(?:\\r?\\n|$)`, "m");
+        // Global: a duplicated key must be cleared everywhere. Removing only the
+        // first leaves a later assignment behind, and dotenv takes the LAST one —
+        // so a "restored" .env would still be pointing at the proxy.
+        const re = new RegExp(`^[ \\t]*(?:export[ \\t]+)?${key}[ \\t]*=.*(?:\\r?\\n|$)`, "gm");
         text = text.replace(re, "");
     }
     return text;
@@ -188,11 +225,16 @@ export async function clearGeminiProxySettings(expectedBaseUrl) {
     catch {
         return false;
     }
-    const configured = new RegExp(`^[ \\t]*(?:export[ \\t]+)?${BASE_URL_VAR}[ \\t]*=[ \\t]*(.*)$`, "m").exec(current);
-    if (!configured) {
+    // The EFFECTIVE assignment, not the first one on the page. dotenv resolves
+    // the last, so a user who appended their own base URL after apply() has
+    // already repointed Gemini — even though our line is still sitting above
+    // theirs. Checking the first saw our value, passed the ownership test, and
+    // restore then deleted the endpoint the CLI was actually using.
+    const configuredUrl = readManagedVars(current)[BASE_URL_VAR];
+    if (configuredUrl === undefined) {
         return false;
     }
-    if (expectedBaseUrl && configured[1]?.trim() !== expectedBaseUrl) {
+    if (expectedBaseUrl && configuredUrl.trim() !== expectedBaseUrl) {
         // Pointed somewhere else — the user's choice, not ours to revert.
         logger.debug("[proxy] Gemini clear: base URL is not the one we wrote, leaving it intact");
         return false;

package/dist/providers/sagemaker/client.js

@@ -6,6 +6,7 @@
  */
 import { handleSageMakerError, SageMakerError, isRetryableError, getRetryDelay, } from "./errors.js";
 import { logger } from "../../utils/logger.js";
+import { isAbortError } from "../../utils/errorHandling.js";
 import { tryImport } from "../../utils/tryImport.js";
 /**
  * Lazily load `@aws-sdk/client-sagemaker-runtime`.
@@ -114,7 +115,13 @@ export class SageMakerRuntimeClient {
             };
             const command = new InvokeEndpointCommand(input);
             const client = await this.getClient();
-            const response = (await this.executeWithRetry(() => client.send(command), params.EndpointName));
+            const response = (await this.executeWithRetry(
+            // The signal goes to the transport, not just to whatever loop is
+            // above us: without it an aborted call keeps its HTTP request in
+            // flight until the endpoint answers. An AbortError matches none of
+            // RETRYABLE_ERROR_CONDITIONS, so executeWithRetry surfaces it rather
+            // than re-issuing a request the caller has already abandoned.
+            () => client.send(command, { abortSignal: params.abortSignal }), params.EndpointName));
             const duration = Date.now() - startTime;
             logger.debug("SageMaker endpoint invocation successful", {
                 endpointName: params.EndpointName,
@@ -130,6 +137,15 @@ export class SageMakerRuntimeClient {
             };
         }
         catch (error) {
+            // The signal now reaches the transport, so this catch sees real
+            // AbortErrors for the first time — and must not wrap them.
+            // SageMakerError's constructor overwrites `.name`, and its generic
+            // fallback stamps `statusCode: 500`, which the retry classifier reads as
+            // "transient, try again". That fabricated status is what turned a
+            // cancellation into three attempts and 22 seconds.
+            if (isAbortError(error)) {
+                throw error;
+            }
             const duration = Date.now() - startTime;
             logger.error("SageMaker endpoint invocation failed", {
                 endpointName: params.EndpointName,
@@ -169,7 +185,10 @@ export class SageMakerRuntimeClient {
             };
             const command = new InvokeEndpointWithResponseStreamCommand(input);
             const client = await this.getClient();
-            const response = (await this.executeWithRetry(() => client.send(command), params.EndpointName));
+            const response = (await this.executeWithRetry(
+            // As above — an abort must tear down the response stream's connection,
+            // not merely stop the consumer reading from it.
+            () => client.send(command, { abortSignal: params.abortSignal }), params.EndpointName));
             logger.debug("SageMaker streaming invocation started", {
                 endpointName: params.EndpointName,
                 setupDuration: Date.now() - startTime,
@@ -192,6 +211,15 @@ export class SageMakerRuntimeClient {
             };
         }
         catch (error) {
+            // The signal now reaches the transport, so the streaming catch sees real
+            // AbortErrors for the first time — and must not wrap them.
+            // SageMakerError's constructor overwrites `.name`, and its generic
+            // fallback stamps `statusCode: 500`, which the retry classifier reads as
+            // "transient, try again". That fabricated status is what turned a
+            // cancellation into three attempts and 22 seconds.
+            if (isAbortError(error)) {
+                throw error;
+            }
             const duration = Date.now() - startTime;
             logger.error("SageMaker streaming invocation failed", {
                 endpointName: params.EndpointName,

package/dist/providers/sagemaker/language-model.d.ts

@@ -34,6 +34,15 @@ export declare class SageMakerLanguageModel implements SageMakerAsLanguageModel
     private config;
     private modelConfig;
     constructor(modelId: string, config: SageMakerConfig, modelConfig: SageMakerModelConfig);
+    /**
+     * Read the caller's abort signal out of the AI SDK's call options.
+     *
+     * `doGenerate`/`doStream` type `options` as `Record<string, unknown>`, so the
+     * value arrives as `unknown` even though `LanguageModelV2CallOptions`
+     * declares `abortSignal?: AbortSignal`. `instanceof` is a real runtime check
+     * rather than an assertion, which is what rule 14 asks for here.
+     */
+    private readAbortSignal;
     /**
      * Generate text synchronously using SageMaker endpoint
      */

package/dist/providers/sagemaker/language-model.js

@@ -10,6 +10,7 @@ import { handleSageMakerError } from "./errors.js";
 import { estimateTokenUsage, createSageMakerStream, parseUsageFromResponseBody, } from "./streaming.js";
 import { createAdaptiveSemaphore } from "./adaptive-semaphore.js";
 import { logger } from "../../utils/logger.js";
+import { isAbortError } from "../../utils/errorHandling.js";
 /**
  * Base synthetic streaming delay in milliseconds for simulating real-time response
  * Can be configured via SAGEMAKER_BASE_STREAMING_DELAY_MS environment variable
@@ -113,6 +114,18 @@ export class SageMakerLanguageModel {
             specificationVersion: this.specificationVersion,
         });
     }
+    /**
+     * Read the caller's abort signal out of the AI SDK's call options.
+     *
+     * `doGenerate`/`doStream` type `options` as `Record<string, unknown>`, so the
+     * value arrives as `unknown` even though `LanguageModelV2CallOptions`
+     * declares `abortSignal?: AbortSignal`. `instanceof` is a real runtime check
+     * rather than an assertion, which is what rule 14 asks for here.
+     */
+    readAbortSignal(options) {
+        const signal = options.abortSignal;
+        return signal instanceof AbortSignal ? signal : undefined;
+    }
     /**
      * Generate text synchronously using SageMaker endpoint
      */
@@ -134,6 +147,7 @@ export class SageMakerLanguageModel {
                 Body: JSON.stringify(sagemakerRequest),
                 ContentType: "application/json",
                 Accept: "application/json",
+                abortSignal: this.readAbortSignal(options),
             });
             // Parse SageMaker response
             const responseBody = JSON.parse(new TextDecoder().decode(response.Body));
@@ -223,6 +237,11 @@ export class SageMakerLanguageModel {
                 duration,
                 error: error instanceof Error ? error.message : String(error),
             });
+            // An abort is not a provider failure: wrapping it here would restore
+            // the fabricated 500 the client guard just avoided.
+            if (isAbortError(error)) {
+                throw error;
+            }
             throw handleSageMakerError(error, this.modelConfig.endpointName);
         }
     }
@@ -260,6 +279,7 @@ export class SageMakerLanguageModel {
                     Body: JSON.stringify(requestWithStreaming),
                     ContentType: this.modelConfig.contentType || "application/json",
                     Accept: this.modelConfig.accept || "application/json",
+                    abortSignal: this.readAbortSignal(options),
                 });
                 // Create intelligent streaming response
                 const stream = await createSageMakerStream(response.Body, this.modelConfig.endpointName, this.config, {
@@ -298,6 +318,13 @@ export class SageMakerLanguageModel {
                 };
             }
             catch (streamingError) {
+                // A cancelled turn is not a missing capability. This fallback exists
+                // for endpoints that cannot stream; re-issuing doGenerate() here with
+                // the same already-aborted signal only adds a wasted call and a
+                // misleading warning before the abort surfaces anyway.
+                if (isAbortError(streamingError)) {
+                    throw streamingError;
+                }
                 logger.warn("Streaming failed, falling back to non-streaming", {
                     endpointName: this.modelConfig.endpointName,
                     error: streamingError instanceof Error
@@ -351,6 +378,11 @@ export class SageMakerLanguageModel {
             logger.error("SageMaker doStream failed", {
                 error: error instanceof Error ? error.message : String(error),
             });
+            // An abort is not a provider failure: wrapping it here would restore
+            // the fabricated 500 the client guard just avoided.
+            if (isAbortError(error)) {
+                throw error;
+            }
             throw handleSageMakerError(error, this.modelConfig.endpointName);
         }
     }
@@ -681,6 +713,11 @@ export class SageMakerLanguageModel {
                 error: error instanceof Error ? error.message : String(error),
                 batchSize: prompts.length,
             });
+            // An abort is not a provider failure: wrapping it here would restore
+            // the fabricated 500 the client guard just avoided.
+            if (isAbortError(error)) {
+                throw error;
+            }
             throw handleSageMakerError(error, this.modelConfig.endpointName);
         }
     }

package/dist/proxy/clientAttribution.d.ts

@@ -16,6 +16,46 @@
  *   client is then still attributable by its own User-Agent rather than
  *   collapsing into one bucket with every other unknown.
  */
+/**
+ * Deliberately NOT mapped, with the measurement that ruled each one out.
+ *
+ * Copilot CLI is the one client here that cannot be identified from its
+ * User-Agent, and both of the strings it sends are actively unsafe to key on:
+ *
+ * - `OpenAI/JS 5.20.1` — the stock OpenAI JS SDK UA, sent by every caller of
+ *   that SDK. Mapping it to Copilot would file unrelated OpenAI-SDK traffic
+ *   under Copilot's name, which is worse than leaving it unattributed.
+ - `Mozilla/5.0 (compatible; MSIE 9.0; Windows NT 6.1; Trident/5.0)` — not a
+ *   CLI's User-Agent at all. This is what `curl` sends on a machine whose
+ *   `~/.curlrc` sets `user-agent`, so every curl-driven caller on such a host
+ *   shares it: scripts, agents, health probes. It accounted for the largest
+ *   single block of `unknown` rows in the log this table was measured against,
+ *   which is exactly what made it tempting.
+ *
+ *   Recorded because the first pass got this wrong in a way worth naming. The
+ *   string was seen arriving at two capture servers during Copilot CLI and
+ *   Gemini CLI runs and was written up as "sent by both CLIs". It was neither:
+ *   it was the aliveness `curl` fired at each capture server moments before
+ *   the CLI, picking up that host's curlrc. The paths gave it away on review —
+ *   the Gemini-side hit was a bare `GET /v1beta/models`, which is the probe's
+ *   URL and not one the CLI requests. A shared string across two unrelated
+ *   clients should have read as "shared dependency or shared tooling", not as
+ *   a property of either client.
+ *
+ * Copilot does send `x-initiator` and `x-interaction-type`, but neither is
+ * exclusive to it either. Attributing it needs a signal nobody has found yet,
+ * so it stays `unknown` and remains traceable through the stored raw header.
+ */
+/**
+ * The client names this table can produce.
+ *
+ * Exported so a test can check the roster of CLIs the proxy configures against
+ * the roster it can actually name. Those two lists drifted apart silently once
+ * already: five configurators shipped while the table still knew only Claude
+ * Code, and nothing failed, because an unattributed client looks exactly like
+ * a quiet one.
+ */
+export declare function getMappedClientNames(): ReadonlySet<string>;
 /**
  * Derive a stable client name, or "unknown" when the header is absent or
  * unrecognised. Never throws: attribution must not be able to fail a request.

package/dist/proxy/clientAttribution.js

@@ -49,16 +49,39 @@ const CLIENT_PREFIXES = [
  * - `OpenAI/JS 5.20.1` — the stock OpenAI JS SDK UA, sent by every caller of
  *   that SDK. Mapping it to Copilot would file unrelated OpenAI-SDK traffic
  *   under Copilot's name, which is worse than leaving it unattributed.
- * - `Mozilla/5.0 (compatible; MSIE 9.0; Windows NT 6.1; Trident/5.0)` — a
- *   spoofed browser string. It looks like a fingerprint and is not one: it was
- *   captured from **both** Copilot CLI and Gemini CLI, so it identifies no
- *   client at all. (It also accounts for the largest single block of
- *   `unknown` rows in this machine's log, which is what made it tempting.)
+ - `Mozilla/5.0 (compatible; MSIE 9.0; Windows NT 6.1; Trident/5.0)` — not a
+ *   CLI's User-Agent at all. This is what `curl` sends on a machine whose
+ *   `~/.curlrc` sets `user-agent`, so every curl-driven caller on such a host
+ *   shares it: scripts, agents, health probes. It accounted for the largest
+ *   single block of `unknown` rows in the log this table was measured against,
+ *   which is exactly what made it tempting.
+ *
+ *   Recorded because the first pass got this wrong in a way worth naming. The
+ *   string was seen arriving at two capture servers during Copilot CLI and
+ *   Gemini CLI runs and was written up as "sent by both CLIs". It was neither:
+ *   it was the aliveness `curl` fired at each capture server moments before
+ *   the CLI, picking up that host's curlrc. The paths gave it away on review —
+ *   the Gemini-side hit was a bare `GET /v1beta/models`, which is the probe's
+ *   URL and not one the CLI requests. A shared string across two unrelated
+ *   clients should have read as "shared dependency or shared tooling", not as
+ *   a property of either client.
  *
  * Copilot does send `x-initiator` and `x-interaction-type`, but neither is
  * exclusive to it either. Attributing it needs a signal nobody has found yet,
  * so it stays `unknown` and remains traceable through the stored raw header.
  */
+/**
+ * The client names this table can produce.
+ *
+ * Exported so a test can check the roster of CLIs the proxy configures against
+ * the roster it can actually name. Those two lists drifted apart silently once
+ * already: five configurators shipped while the table still knew only Claude
+ * Code, and nothing failed, because an unattributed client looks exactly like
+ * a quiet one.
+ */
+export function getMappedClientNames() {
+    return new Set(CLIENT_PREFIXES.map(([, name]) => name));
+}
 /** Cap stored User-Agents. They are attacker-influenced and unbounded. */
 const MAX_USER_AGENT_CHARS = 200;
 /**

package/dist/types/common.d.ts

@@ -352,6 +352,93 @@ export type TTSHandler = {
      * @throws {TTSError} On synthesis failure, timeout, or configuration issues
      */
     synthesize(text: string, options: TTSOptions): Promise<TTSResult>;
+    /**
+     * Stream provider-native audio for one pre-validated text segment.
+     *
+     * Return `undefined` when the requested options cannot be delivered
+     * incrementally. The processor then uses `synthesize()` and preserves the
+     * buffered fallback for handlers and formats without native support.
+     * Provider-local indexes, cumulative sizes, and finality are normalized by
+     * the processor before chunks reach the public stream — an implementation
+     * may leave `isFinal` false on every chunk rather than hold a fragment back
+     * to label the last one, and the processor discards reported finality
+     * either way.
+     *
+     * Yield `TTSChunk` fragments. The member is declared `unknown` — not a
+     * method signature — on purpose, and that is a deliberate trade.
+     *
+     * This is an OPTIONAL member added to a public structural type that
+     * consumers already implement. Any type narrower than `unknown` rejects some
+     * existing handler that already carries a member of this name, which is a
+     * source break under Critical Rule 5 whatever that other shape happens to
+     * be. That is not hypothetical: a member returning a sync `Generator`, an
+     * `async` method returning a `Promise` of an async iterable, a
+     * callback-style member returning `void` or `Promise<void>`, and a plain
+     * boolean capability flag all compile against `origin/release` today, and
+     * every one of them is rejected by a declared method signature — including
+     * an intentionally wide one such as `(...args: never[]) => unknown`, which
+     * still cannot accept the boolean. Only `unknown` accepts them all.
+     *
+     * The cost is that this member cannot contextually type an implementation's
+     * parameters. Authors annotate their own signature instead — OpenAI TTS
+     * declares `synthesizeStream(text: string, options: TTSOptions):
+     * AsyncIterable<TTSChunk> | undefined` on the class — which keeps full
+     * compiler checking of what that implementation yields. Nothing is checked
+     * at this member; usability is decided at runtime by the processor.
+     *
+     * The processor validates each fragment at runtime instead. A fragment is
+     * audio only when it carries a non-empty `data` `Buffer` (or `Uint8Array`);
+     * its `format` is honoured only when it names a real `TTSAudioFormat`, and
+     * the requested format is used otherwise. A fragment that fails that test —
+     * including an empty (`data.length === 0`) read — is skipped and never
+     * reaches the consumer. A native stream that completes without yielding a
+     * single deliverable fragment is treated as "no incremental delivery after
+     * all" and falls back to `synthesize()` for that segment.
+     *
+     * That filtering is specific to this native path. The buffered path
+     * forwards whatever `synthesize()` returns, a zero-byte buffer included, so
+     * a consumer of the public stream can still observe an empty chunk when a
+     * handler produces one.
+     *
+     * `undefined` is the only capability signal. Everything the processor does
+     * to decide whether this capability exists is asked BEFORE the segment's
+     * work starts, and every way that question can fail is a handler bug that
+     * the processor answers the same way: it serves that segment from
+     * `synthesize()` rather than losing it (the throwing modes also log a
+     * warning; a member that is merely not callable falls back silently). None
+     * of them should be used as a deliberate fallback mechanism. The modes it
+     * anticipates cover each read as well as each call, because reading a
+     * property can run a getter or a `Proxy` trap that throws just as a call
+     * can:
+     *
+     * - reading `synthesizeStream` off the handler throws;
+     * - the member is present but not callable;
+     * - reading `isConfigured` off the handler throws, or calling it throws —
+     *   the segment falls back to the buffered path, where `synthesize()` asks
+     *   again and a throw there fails the segment shaped, exactly as it would
+     *   for a handler with no native member (a handler that merely reports
+     *   itself unconfigured is not a bug: that segment fails with
+     *   `TTS_PROVIDER_NOT_CONFIGURED`, as it always has);
+     * - calling the member throws;
+     * - the returned value's async-iterability cannot be established, including
+     *   a value whose `Symbol.asyncIterator` property cannot even be read.
+     *
+     * An error raised once the segment's own work has started, by contrast,
+     * fails that segment like any other synthesis failure — it is not re-served
+     * from the buffered path. Iteration begins at the `[Symbol.asyncIterator]()`
+     * call, so that call throwing, that call handing back something that is not
+     * an iterator, and a first read that rejects are all segment failures rather
+     * than fallbacks.
+     *
+     * Implementations MUST enforce their own timeout and cancel any active
+     * transport when the returned iterable is closed.
+     *
+     * The value the processor looks for is a callable of the shape
+     * `(text: string, options: TTSOptions) => AsyncIterable<TTSChunk> | undefined`,
+     * invoked with the handler as `this`. `text` is one buffered text segment
+     * within the provider's length limit.
+     */
+    synthesizeStream?: unknown;
     /**
      * Get available voices for the provider
      *

package/dist/types/providers.d.ts

@@ -1282,6 +1282,16 @@ export type InvokeEndpointParams = {
     TargetVariant?: string;
     /** Inference ID for request tracking */
     InferenceId?: string;
+    /**
+     * Cancels the in-flight HTTP request, not just the loop around it.
+     *
+     * Named in camelCase deliberately: every other field here mirrors an AWS
+     * `InvokeEndpointCommandInput` member and keeps its PascalCase, whereas this
+     * one is a transport option handed to `client.send()` as
+     * `@smithy/types` `HttpHandlerOptions` — it is never part of the command
+     * payload, and spelling it differently keeps that boundary visible.
+     */
+    abortSignal?: AbortSignal;
 };
 /**
  * Response from SageMaker endpoint invocation

package/dist/types/voice.d.ts

@@ -134,6 +134,14 @@ export type VoiceTurn = {
 };
 /**
  * TTS-capable voice provider type
+ *
+ * @deprecated Use the canonical `TTSHandler` contract instead. Nothing in
+ * this package consumes `TTSProvider`; it is kept at its original shape so
+ * existing external callers keep compiling. `TTSHandler` is not a drop-in
+ * replacement — it requires `isConfigured()`, makes `getVoices` and
+ * `maxTextLength` optional, and its `synthesizeStream` may return `undefined`
+ * to select the buffered path — so this is a distinct legacy shape, not an
+ * alias.
  */
 export type TTSProvider = {
     /**
@@ -155,6 +163,11 @@ export type TTSProvider = {
 };
 /**
  * TTS stream chunk for streaming synthesis
+ *
+ * @deprecated Use the canonical `TTSChunk` type instead. Kept at its
+ * original shape so existing external callers keep compiling: `TTSChunk`
+ * narrows `format` to `TTSAudioFormat` and has no `timestampMs`, so it
+ * is not a drop-in replacement.
  */
 export type TTSStreamChunk = {
     /** Audio data chunk */