@voltro/ai 0.58.0 → 0.59.0

package/CHANGELOG.md

@@ -39,6 +39,61 @@ _Changes staged for the next release accumulate here (rolled up from
 
 ---
 
+## [0.59.0] — 2026-08-30
+
+### ⚠ BREAKING
+
+- **@voltro/cli** — **`web.sourcemaps` moved to the top level of `app.config.ts`, and now covers every bundle the build minifies.**
+
+  It reached exactly one of them before: the vite CLIENT build. `voltro build` minifies four — the browser bundle, the SSR bundle, the `voltro start` bundle, and for an api app the precompiled entry plus the serve bundle that `voltro serve` actually runs — and none of the other three had a `sourcemap` option or a config path that could ask for one. `keepNames` rescues the identifiers that are read as strings and nothing else, so a frame out of the artefact production runs read `at Qo (serveEntry.js:236:76405)`.
+
+  The docs closed that hole with a sentence instead of a field: *server stack traces are un-minified already*. The built file says otherwise, and the server half is where it costs most — a schedule, a workflow step, a subscriber or a REST route has no browser caller whose frame could stand in for it.
+
+  A second field (`api.sourcemaps`) would have made the same mistake twice. "Do I want resolvable frames from this app" has one answer; how many bundles the build happens to emit is not the caller's business.
+
+  Three details that come with it:
+
+  - **The old spelling is REFUSED, not ignored.** A moved option that is silently dropped goes green, stops emitting maps, and is found by someone reading an unresolvable frame months later. - **Each output directory uploads under the prefix that matches how its files are named** — `~/assets` for the browser bundle, `~/` for the bundles a node process loaded. One prefix across both is wrong for one of them. - **The upload and sweep run at every exit of the build**, not after the client bundle. Sweeping there would have deleted the client maps before the server ones existed, leaving those neither uploaded nor deleted.
+
+  `minifiedBundlesCarryMaps.test.ts` asserts the property over the SET: every bundler options object in the CLI that turns minification on must also decide `sourcemap`. That is what was missing — not one option, three, because nothing was watching the class.
+
+  **`voltro update` carries you across this** — codemod `0.59.0/01_sourcemaps_moved_to_the_top_level`. If you pin versions by hand and never run it, print the notes without changing anything: `voltro update --codemods-only --from <your current version> --dry-run` (this one ships in 0.59.0).
+- **@voltro/ai** — **Speech has a cost path, and a built-in provider name can be taken over.**
+
+  Three changes, one thread: the speech seam existed and nothing could reach it.
+
+  **`registerSpeechProvider(name, provider, { replaceBuiltin: true })`.** Refusing `mock` / `openai` / `gateway` / `anthropic` outright was wrong, and the case that shows it is one the refusal could not see: a provider name is not always an alias the app chooses. `openai` is the segment the gateway puts in its model ids, so it is what a stored catalog's rows carry and what a picker submits — an app told to pick another name cannot, without rewriting persisted rows and live sessions. It keeps its own dispatch instead, for every provider rather than the colliding one. What the refusal protected is kept by putting the intent in the call.
+
+  **Registered providers resolve BEFORE built-ins.** The dispatch decided from a hard-coded list of built-in names, so without this the flag would let you register `openai` and never route to it — declared, documented, wired at zero call sites.
+
+  **`MeteredUsage` — a tally in characters or seconds.** Every speech vendor meters one of those; none meters tokens. A ledger that only knew tokens could not hold a speech call at all, so speech spend was not un-priced, it was *absent*. The token shape is untouched (it is what the AI SDK returns); the new shape is separate rather than a unit tacked onto `AiUsage`, because writing a character count into a field called `inputTokens` puts a lie in a row someone reads later.
+
+  `_voltro_ai_usage` gains a `unit` column, and `costSource` gains `'unpriced'`: a non-token unit with no supplied price is written with the real count and a zero cost rather than a fabricated one, since a per-1M-token rate applied to a character count produces a number indistinguishable from a real one. Sum the count columns grouped by `unit`, never across it.
+
+  BREAKING for a caller that had narrowed `CostBreakdown['costSource']` to two values or reads `estimateCostUsd`'s return positionally. No call site changes SHAPE — the token path takes the same arguments and returns the same numbers — but a narrowing is user-authored code, so this carries a `manual` codemod rather than `none`: nothing here can be transformed (whether the third member belongs in your union is your decision), and the reader who needs it is exactly the one a "touches no user-authored code" line would have sent away. It also names the query that does not fail but answers wrongly: summing `_voltro_ai_usage` counts ACROSS units now adds characters to tokens.
+
+  **`voltro update` carries you across this** — codemod `0.59.0/02_costsource_gained_unpriced`. If you pin versions by hand and never run it, print the notes without changing anything: `voltro update --codemods-only --from <your current version> --dry-run` (this one ships in 0.59.0).
+
+### Added
+
+- **@voltro/ai** — **`GatewayModelInfo.raw`** — the `/v1/models` entry exactly as it came over the wire, beside the normalised fields.
+
+  Normalising is the right default: the union of `tags`, `supported_parameters` and `modalities` is framework knowledge, and every app on the gateway was writing those forty lines differently. But normalising is lossy by construction, and the fields it drops are not decoration — a picker built on the vendor's own capability tags, a pricing display that shows a structure we have not normalised, `zdr` and `no_training` kept apart instead of folded into `dataPolicy`.
+
+  Without `raw`, such an app fetches the endpoint a second time and maintains a second parser of the same response. One field rather than three more normalised ones, because the alternative asks the same question again at every field the gateway adds.
+
+  Absent on the injected-provider path, for the same reason `capabilities` is: that seam never saw a response, and an empty object would turn "no wire data" into the claim that the wire carried nothing.
+
+### Fixed
+
+- **@voltro/cli** — **`@sentry/cli` 3.x loads.** The loader read one export spelling — `module.exports = SentryCli`, which is 2.x. 3.x ships `exports.SentryCli = SentryCli`, so `mod.default` is a namespace object rather than the class, and a build with a source-map upload configured stopped with *could not be loaded*.
+
+  The framework cannot pin its way out of this: `@sentry/cli` is FSL-1.1-MIT, so it is not ours to depend on and the app installs it — which means `pnpm add -D @sentry/cli`, the command we ourselves print, resolves the latest. Reading one spelling turned our own documented instruction into a failing build.
+
+  All four positions are accepted now (both spellings, each of which `import()` presents twice), and the two failures are told apart: a package that resolved but had no readable constructor no longer says *install it*. That reading is what cost a pipeline — locally `require()` resolves and the binary is there, so nothing about the install looks wrong.
+
+---
+
 ## [0.58.0] — 2026-08-30
 
 ### ⚠ BREAKING

package/dist/index.d.ts

@@ -373,7 +373,7 @@ export declare interface AiUsageRecordInput {
     readonly model: string;
     readonly operation: string;
     readonly agent?: string | null;
-    readonly usage: AiUsage;
+    readonly usage: AiUsage | MeteredUsage;
     /** Override the price table (negotiated/volume pricing or unknown model). */
     readonly price?: ModelPrice;
     /** The ACTUAL per-call cost reported by the provider/gateway (USD). When set,
@@ -573,6 +573,9 @@ export declare const buildCopilotSystemPrompt: (schema: CopilotSchema) => string
  *  `execute` tools ignore it. */
 export declare const buildSdkTools: (tools: Record<string, AnyTool>, ctx?: ToolContext) => ToolSet;
 
+/** The names `generateSpeech` resolves without a registration. */
+export declare const BUILTIN_SPEECH_PROVIDERS: ReadonlyArray<string>;
+
 /**
  * Cancel an in-flight stream by id. Aborts its controller (the SDK call stops +
  * the stream emits a terminal `cancelled` error). Returns `true` if a live
@@ -734,7 +737,9 @@ export declare interface CostBreakdown {
      *  the ACTUAL per-call cost (authoritative); `estimated` = derived from the
      *  static price table (or zero for an unknown model). Analytics can flag
      *  estimated rows + a model that priced at zero. */
-    readonly costSource: 'gateway' | 'estimated';
+    readonly costSource: 'gateway' | 'estimated' | 'unpriced';
+    /** What `inputTokens`/`outputTokens` are counts OF. */
+    readonly unit: UsageUnit;
 }
 
 /** Open a new thread (the store generates the id). */
@@ -1018,7 +1023,7 @@ export declare const embedMany: (texts: ReadonlyArray<string>, config?: Embeddin
  * unknown model (or the `mock` provider) resolves to zero cost rather
  * than throwing, so cost accounting never breaks a call.
  */
-export declare const estimateCostUsd: (usage: AiUsage, opts: {
+export declare const estimateCostUsd: (usage: AiUsage | MeteredUsage, opts: {
     readonly model: string;
     readonly price?: ModelPrice;
     readonly actualCostUsd?: number;
@@ -1219,6 +1224,26 @@ export declare interface GatewayModelInfo {
      * through is a decision nobody makes.
      */
     readonly dataPolicy?: ModelDataPolicy;
+    /**
+     * The entry exactly as it came over the wire.
+     *
+     * The normalised fields above are the shared answer to the questions every
+     * app on the gateway asks. `raw` is for the ones only one app asks — a chips
+     * row built from `tags`, a pricing display that shows the vendor's own
+     * structure, `zdr` and `no_training` kept apart rather than folded into
+     * `dataPolicy`.
+     *
+     * Without it, an app with its own display fetches `/v1/models` a SECOND time
+     * and maintains a SECOND parser of the same response — and then has to decide
+     * again, at every new field the gateway adds, whether to wait for us. That is
+     * the decision this field removes, which is why it is one field and not three
+     * more normalised ones.
+     *
+     * Absent on the injected-provider path for the same reason `capabilities` is:
+     * that seam never saw a response, and inventing an empty object would turn
+     * "no wire data" into the claim "the wire carried nothing".
+     */
+    readonly raw?: RawGatewayModel;
 }
 
 /**
@@ -1410,8 +1435,21 @@ export declare interface GenerateSpeechOptions {
 
 export declare interface GenerateSpeechResult {
     readonly audio: GeneratedAudio;
-    /** The speech model spec reports no usage; present for surface parity. */
-    readonly usage?: MediaUsage;
+    /**
+     * What the call consumed.
+     *
+     * The speech model SPEC reports none, so a gateway-routed call still leaves
+     * this undefined. A REGISTERED provider is the other case, and it is not a
+     * property of the model any more: an app's own adapter knows the billed
+     * quantity, because its vendor invoices on it — characters for ElevenLabs,
+     * Cartesia and OpenAI, seconds for others.
+     *
+     * So it takes a `MeteredUsage` too, and that is what makes speech spend
+     * reachable: without a shape that can say "4200 characters", the number the
+     * adapter already has has nowhere to go, and `recordAiUsage` never sees the
+     * call at all. Not un-priced — absent from the ledger.
+     */
+    readonly usage?: MediaUsage | MeteredUsage;
     readonly providerMetadata?: unknown;
 }
 
@@ -1676,6 +1714,8 @@ export declare const isEvalDefinition: (value: unknown) => value is EvalDefiniti
  */
 export declare const isExternalWrite: (tool: McpToolInfo, namespace: string, policy: McpToolPolicy) => boolean;
 
+export declare const isMeteredUsage: (u: AiUsage | MeteredUsage) => u is MeteredUsage;
+
 /** Is this a rendered prompt or a bare string? The discriminator `aiStep` uses
  *  so `prompt:` can accept either without a wrapper type at every call site. */
 export declare const isRenderedPrompt: (value: unknown) => value is RenderedPrompt;
@@ -2047,6 +2087,23 @@ export declare type MessagePart = {
     readonly data: string;
 };
 
+/**
+ * A tally in a unit that is not tokens.
+ *
+ * Deliberately NOT `AiUsage` with a unit tacked on. Writing a character count
+ * into a field called `inputTokens` puts a lie in a ledger row that someone
+ * reads later, and a dashboard summing that column across units is wrong in a
+ * way nothing reports. The token shape is left exactly as it was — it is what
+ * the AI SDK returns, and text callers change nothing.
+ */
+export declare interface MeteredUsage {
+    readonly unit: Exclude<UsageUnit, 'tokens'>;
+    /** What went in — characters of text, say. */
+    readonly input?: number | undefined;
+    /** What came out — seconds of audio, say. */
+    readonly output?: number | undefined;
+}
+
 /** A scripted inline file the mock model emits on a turn (usually an image).
  *  `data` is base64 (a short ascii string works for assertions). */
 export declare interface MockFile {
@@ -2176,6 +2233,13 @@ export declare interface ModelPrice {
 /** The current merged price map (defaults + installed overrides). Overrides win. */
 export declare const modelPricing: () => Record<string, ModelPrice>;
 
+/** Both shapes, flattened to the two counts + the unit they are counts of. */
+export declare const normaliseUsage: (usage: AiUsage | MeteredUsage) => {
+    readonly unit: UsageUnit;
+    readonly input: number;
+    readonly output: number;
+};
+
 /**
  * Wrap a `streamText` `Stream<AgentEvent>` with the same `voltro.ai.call` span +
  * metrics. The stream never fails — usage arrives on the terminal `done` event,
@@ -2619,11 +2683,31 @@ export declare const registeredSpeechProviders: () => ReadonlyArray<string>;
  * Register a speech provider under a name.
  *
  * The name then works in `generateSpeech({ provider: { name, model, voice } })`.
- * It must not collide with a built-in (`mock`, `openai`, `gateway`,
- * `anthropic`): silently shadowing one would make a config mean something
- * different depending on import order.
+ * Taking over a built-in name needs `{ replaceBuiltin: true }` — see the option.
  */
-export declare const registerSpeechProvider: (name: string, provider: SpeechProvider) => void;
+export declare const registerSpeechProvider: (name: string, provider: SpeechProvider, options?: RegisterSpeechProviderOptions) => void;
+
+export declare interface RegisterSpeechProviderOptions {
+    /**
+     * Take over a BUILT-IN name (`openai`, `gateway`, `anthropic`, `mock`).
+     *
+     * Refusing these outright was wrong, and the case that showed it is one the
+     * refusal could not see: a provider name is not always an alias the app
+     * chooses. `openai` is the value the GATEWAY puts in its model ids, so it is
+     * what an app's stored catalog rows carry and what its picker submits. Told
+     * to pick another name, such an app cannot — it would have to rewrite
+     * persisted rows and live sessions — so it keeps its own dispatch instead,
+     * and the primitive stays unused for every provider, not just the colliding
+     * one.
+     *
+     * What the refusal was actually protecting is worth keeping: a SILENT shadow,
+     * where the same config means different things depending on which module
+     * loaded first. This flag keeps that property by putting the intent in the
+     * call. An override is then a decision someone wrote down, not an accident of
+     * import order.
+     */
+    readonly replaceBuiltin?: boolean;
+}
 
 /**
  * Register (or reuse) the `AbortController` for `streamId`. `streamText` calls
@@ -2648,6 +2732,9 @@ export declare interface RenderedPrompt extends PromptStamp {
     readonly definition: PromptDefinition;
 }
 
+/** Whether `name` is a registration standing in front of a built-in. */
+export declare const replacesBuiltinSpeechProvider: (name: string) => boolean;
+
 /**
  * Gate an AI call against a per-tenant USD budget with an ATOMIC reservation —
  * the cap precedent is billing's `requireEntitlement` / storage's
@@ -3525,6 +3612,16 @@ export declare type TranscriptionTimestamps = 'none' | 'segment' | 'word';
  */
 export declare const unregisterStream: (streamId: string) => void;
 
+/**
+ * What a call was billed in.
+ *
+ * Text is tokens. Speech is not: every speech vendor meters CHARACTERS of input
+ * or SECONDS of audio, and none of them meters tokens. A ledger that only knows
+ * tokens therefore cannot hold a speech call at all — which is why speech spend
+ * was invisible rather than merely un-priced.
+ */
+export declare type UsageUnit = 'tokens' | 'characters' | 'seconds';
+
 /**
  * Validate a proposal against the schema and (on success) build a read-only
  * `QueryDescriptor`. EVERY table/column the proposal names must exist in the