@nodaro/shared 1.10.0 → 1.11.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@nodaro/shared",
-  "version": "1.10.0",
+  "version": "1.11.0",
   "description": "Shared types, model catalog, wire contracts, and structural vocabularies for the Nodaro platform and SDK.",
   "type": "module",
   "license": "Apache-2.0",

package/src/__tests__/credit-identifiers.test.ts

@@ -313,31 +313,31 @@ describe("buildVideoCreditModelIdentifier", () => {
   // --- Duration tiers for kling-3.0 ---
   describe("kling-3.0 duration tiers", () => {
     it("5s duration returns :5s tier", () => {
-      expect(buildVideoCreditModelIdentifier("kling-3.0", 5)).toBe("kling-3.0:5s")
+      expect(buildVideoCreditModelIdentifier("kling-3.0", 5, false)).toBe("kling-3.0:5s")
     })
 
     it("3s duration falls into 5s tier", () => {
-      expect(buildVideoCreditModelIdentifier("kling-3.0", 3)).toBe("kling-3.0:5s")
+      expect(buildVideoCreditModelIdentifier("kling-3.0", 3, false)).toBe("kling-3.0:5s")
     })
 
     it("10s duration returns :10s tier", () => {
-      expect(buildVideoCreditModelIdentifier("kling-3.0", 10)).toBe("kling-3.0:10s")
+      expect(buildVideoCreditModelIdentifier("kling-3.0", 10, false)).toBe("kling-3.0:10s")
     })
 
     it("7s duration falls into 10s tier", () => {
-      expect(buildVideoCreditModelIdentifier("kling-3.0", 7)).toBe("kling-3.0:10s")
+      expect(buildVideoCreditModelIdentifier("kling-3.0", 7, false)).toBe("kling-3.0:10s")
     })
 
     it("15s duration returns :15s tier", () => {
-      expect(buildVideoCreditModelIdentifier("kling-3.0", 15)).toBe("kling-3.0:15s")
+      expect(buildVideoCreditModelIdentifier("kling-3.0", 15, false)).toBe("kling-3.0:15s")
     })
 
     it("duration exceeding max tier clamps to last tier (20s -> 15s)", () => {
-      expect(buildVideoCreditModelIdentifier("kling-3.0", 20)).toBe("kling-3.0:15s")
+      expect(buildVideoCreditModelIdentifier("kling-3.0", 20, false)).toBe("kling-3.0:15s")
     })
 
     it("duration exceeding max tier clamps to last tier (100s -> 15s)", () => {
-      expect(buildVideoCreditModelIdentifier("kling-3.0", 100)).toBe("kling-3.0:15s")
+      expect(buildVideoCreditModelIdentifier("kling-3.0", 100, false)).toBe("kling-3.0:15s")
     })
   })
 
@@ -351,6 +351,18 @@ describe("buildVideoCreditModelIdentifier", () => {
       expect(buildVideoCreditModelIdentifier("kling", 5, true)).toBe("kling:5s:audio")
     })
 
+    it("kling-3.0 + sound UNDEFINED appends :audio (model default is audio ON)", () => {
+      // The provider layer generates audio when the caller expressed no intent
+      // (models.ts extraParams.sound: true + kling3-client `?? true`). Billing
+      // must mirror that via capability defaultOn — reserving the no-audio
+      // tier against an audio-on generation was a silent under-bill.
+      expect(buildVideoCreditModelIdentifier("kling-3.0", 5, undefined)).toBe("kling-3.0:5s:audio")
+    })
+
+    it("kling (2.6) + sound UNDEFINED does not append :audio (model default is OFF)", () => {
+      expect(buildVideoCreditModelIdentifier("kling", 5, undefined)).toBe("kling:5s")
+    })
+
     it("kling-3.0 + sound=false does not append :audio", () => {
       expect(buildVideoCreditModelIdentifier("kling-3.0", 5, false)).toBe("kling-3.0:5s")
     })
@@ -407,7 +419,7 @@ describe("buildVideoCreditModelIdentifier", () => {
   // --- String duration parsing ---
   describe("duration parsing", () => {
     it('string duration "10" is parsed as number 10', () => {
-      expect(buildVideoCreditModelIdentifier("kling-3.0", "10")).toBe("kling-3.0:10s")
+      expect(buildVideoCreditModelIdentifier("kling-3.0", "10", false)).toBe("kling-3.0:10s")
     })
 
     it('string duration "5" works', () => {
@@ -415,19 +427,19 @@ describe("buildVideoCreditModelIdentifier", () => {
     })
 
     it("NaN duration defaults to 5", () => {
-      expect(buildVideoCreditModelIdentifier("kling-3.0", "abc")).toBe("kling-3.0:5s")
+      expect(buildVideoCreditModelIdentifier("kling-3.0", "abc", false)).toBe("kling-3.0:5s")
     })
 
     it("undefined duration defaults to 5", () => {
-      expect(buildVideoCreditModelIdentifier("kling-3.0")).toBe("kling-3.0:5s")
+      expect(buildVideoCreditModelIdentifier("kling-3.0", undefined, false)).toBe("kling-3.0:5s")
     })
 
     it("0 duration falls into first tier", () => {
-      expect(buildVideoCreditModelIdentifier("kling-3.0", 0)).toBe("kling-3.0:5s")
+      expect(buildVideoCreditModelIdentifier("kling-3.0", 0, false)).toBe("kling-3.0:5s")
     })
 
     it("1 duration falls into first tier", () => {
-      expect(buildVideoCreditModelIdentifier("kling-3.0", 1)).toBe("kling-3.0:5s")
+      expect(buildVideoCreditModelIdentifier("kling-3.0", 1, false)).toBe("kling-3.0:5s")
     })
   })
 

package/src/__tests__/video-audio-capability.test.ts

@@ -22,15 +22,33 @@ describe("getVideoAudioCapability", () => {
     }
   })
 
-  it("returns ambient (sound toggle, cost-affecting) for Kling", () => {
+  it("returns native_speech (sound toggle, cost-affecting) for KIE Kling", () => {
+    // Probe-verified 2026-07-16: scripted quoted dialogue comes back verbatim
+    // with articulated lips on the KIE path for BOTH kling (2.6) and kling-3.0.
     for (const m of ["kling", "kling-3.0"]) {
       const cap = getVideoAudioCapability(m)
-      expect(cap.mode, m).toBe("ambient")
+      expect(cap.mode, m).toBe("native_speech")
       expect(cap.field, m).toBe("sound")
       expect(cap.affectsCost, m).toBe(true)
     }
   })
 
+  it("returns native_speech (generateAudio lever, flat-priced) for kling-3-omni", () => {
+    const cap = getVideoAudioCapability("kling-3-omni")
+    expect(cap.mode).toBe("native_speech")
+    expect(cap.field).toBe("generateAudio")
+    // Audio is priced into the Replicate flat per-duration rate — no :audio composite.
+    expect(cap.affectsCost).toBeUndefined()
+    expect(cap.defaultOn).toBe(true)
+  })
+
+  it("defaultOn mirrors each model's own config default", () => {
+    // kling-3.0 generates audio unless explicitly disabled (models.ts
+    // extraParams.sound: true + kling3-client `?? true`); kling 2.6 defaults off.
+    expect(getVideoAudioCapability("kling-3.0").defaultOn).toBe(true)
+    expect(getVideoAudioCapability("kling").defaultOn).toBeUndefined()
+  })
+
   it("returns audio_driven for Seedance 2.0", () => {
     for (const m of ["seedance-2", "seedance-2-fast"]) {
       const cap = getVideoAudioCapability(m)
@@ -66,6 +84,7 @@ describe("videoModelSupportsAudio", () => {
   it("is true for any model with an audio mode, false for silent", () => {
     expect(videoModelSupportsAudio("veo3")).toBe(true)
     expect(videoModelSupportsAudio("kling-3.0")).toBe(true)
+    expect(videoModelSupportsAudio("kling-3-omni")).toBe(true)
     expect(videoModelSupportsAudio("seedance-2")).toBe(true)
     expect(videoModelSupportsAudio("seedance")).toBe(true)
     expect(videoModelSupportsAudio("minimax")).toBe(false)
@@ -80,9 +99,12 @@ describe("videoModelCanSpeakDialogue", () => {
     expect(videoModelCanSpeakDialogue("seedance-2")).toBe(true)
     expect(videoModelCanSpeakDialogue("seedance-2-fast")).toBe(true)
     expect(videoModelCanSpeakDialogue("seedance-2-mini")).toBe(true)
+    // Kling 2.6 / 3.0 / Omni speak scripted dialogue natively (probe-verified
+    // 2026-07-16) — the Story→Video auto-pick uses in-model speech + revoice.
+    expect(videoModelCanSpeakDialogue("kling")).toBe(true)
+    expect(videoModelCanSpeakDialogue("kling-3.0")).toBe(true)
+    expect(videoModelCanSpeakDialogue("kling-3-omni")).toBe(true)
     // ambient-only models are NOT dialogue-capable — their audio is SFX/ambient
-    expect(videoModelCanSpeakDialogue("kling")).toBe(false)
-    expect(videoModelCanSpeakDialogue("kling-3.0")).toBe(false)
     expect(videoModelCanSpeakDialogue("seedance")).toBe(false)
     expect(videoModelCanSpeakDialogue("minimax")).toBe(false)
     expect(videoModelCanSpeakDialogue(undefined)).toBe(false)
@@ -101,10 +123,16 @@ describe("seedance-2-mini is a full Seedance 2 family member", () => {
 })
 
 describe("VIDEO_AUDIO_CAPABILITY internal consistency", () => {
-  it("every Kling AUDIO_ADDON provider is ambient + affectsCost", () => {
+  it("every AUDIO_ADDON provider is cost-affecting on the canonical `sound` lever", () => {
+    // The billing-critical invariant: the `:audio` surcharge keys off `sound`,
+    // so every surcharged model must declare audio, be marked cost-affecting,
+    // and carry its toggle on that exact field (applyVideoAudioToggle then
+    // refuses the generateAudio alias for these, making a billed/generated
+    // divergence structurally impossible).
     for (const m of AUDIO_ADDON_PROVIDERS) {
       const cap = getVideoAudioCapability(m)
-      expect(cap.mode, m).toBe("ambient")
+      expect(cap.mode, m).not.toBe("none")
+      expect(cap.field, m).toBe("sound")
       expect(cap.affectsCost, m).toBe(true)
     }
   })

package/src/credit-identifiers.ts

@@ -18,6 +18,7 @@ import {
   MOTION_DURATION_TIERS,
   T2I_TO_I2I_VARIANT,
   isVeoProvider,
+  getVideoAudioCapability,
 } from "./model-constants.js"
 import { isFlux2Model } from "./flux2-pricing.js"
 import { MODEL_CATALOG } from "./model-catalog.js"
@@ -227,8 +228,13 @@ export function buildVideoCreditModelIdentifier(
   const tier = tiers.find(t => durationSec <= t.maxSeconds) ?? tiers[tiers.length - 1]
   let identifier = `${effectiveProvider}:${tier.suffix}`
 
-  // Append audio suffix if applicable
-  if (AUDIO_ADDON_PROVIDERS.has(effectiveProvider) && sound) {
+  // Append audio suffix if applicable. When the caller expressed no intent
+  // (sound === undefined), fall back to the model's own default (capability
+  // `defaultOn` — kling-3.0 generates audio unless explicitly disabled), so an
+  // intent-less request is billed for the audio it actually produces instead
+  // of reserving the cheaper no-audio tier against an audio-on generation.
+  const soundOn = sound ?? (getVideoAudioCapability(effectiveProvider).defaultOn === true)
+  if (AUDIO_ADDON_PROVIDERS.has(effectiveProvider) && soundOn) {
     identifier += ":audio"
   }
 

package/src/model-constants.ts

@@ -1393,8 +1393,13 @@ export const AUDIO_ADDON_PROVIDERS = new Set([
  *                     lip-synced spoken dialogue. Toggle is offered; the
  *                     pipeline still uses TTS + lip-sync for dialogue.
  *   "native_speech" — bakes spoken dialogue + lip movement from the prompt
- *                     (VEO 3.x). The pipeline injects the dialogue line, enables
- *                     audio, and revoices the clip to the character's saved voice.
+ *                     (VEO 3.x always-on; Kling 2.6/3.0 behind the `sound`
+ *                     toggle — probe-verified 2026-07-16: scripted lines come
+ *                     back word-for-word with articulated lips on the KIE
+ *                     path, matching the official Kling 2.6 audio guide and
+ *                     Kling 3.0 prompting docs). The pipeline injects the
+ *                     dialogue line, enables audio, and revoices the clip to
+ *                     the character's saved voice.
  *   "audio_driven"  — lip-syncs to a supplied reference-audio track (Seedance
  *                     2.0 multimodal). The pipeline synthesises the character's
  *                     voice first, feeds it as reference audio, and skips the
@@ -1410,6 +1415,14 @@ export interface VideoAudioCapability {
   alwaysOn?: boolean
   /** Enabling audio raises the credit cost (Kling — see AUDIO_ADDON_PROVIDERS). */
   affectsCost?: boolean
+  /**
+   * The model generates audio when the caller expresses NO intent (its own
+   * config default is on — kling-3.0's `sound: true`, kling-3-omni's
+   * `generate_audio: true`). The `:audio` credit suffix mirrors this default
+   * so an intent-less request is billed for the audio it actually produces
+   * (see buildVideoCreditModelIdentifier). Absent ⇒ default off.
+   */
+  defaultOn?: boolean
 }
 
 /**
@@ -1426,9 +1439,22 @@ export const VIDEO_AUDIO_CAPABILITY: Record<string, VideoAudioCapability> = {
   veo3: { mode: "native_speech", alwaysOn: true },
   "veo3.1": { mode: "native_speech", alwaysOn: true },
   veo3_lite: { mode: "native_speech", alwaysOn: true },
-  // Kling 2.6 / 3.0 — ambient sound/SFX toggle; not lip-synced speech. Cost-affecting.
-  kling: { mode: "ambient", field: "sound", affectsCost: true },
-  "kling-3.0": { mode: "ambient", field: "sound", affectsCost: true },
+  // Kling 2.6 / 3.0 — native spoken dialogue + lip sync behind the `sound`
+  // toggle (probe-verified on the KIE path 2026-07-16: scripted quoted lines
+  // are spoken verbatim with articulated lips; the official Kling 2.6 audio
+  // guide documents speech/dialogue/narration/singing with [Character@Voice]
+  // binding, zh+en voices). Cost-affecting: `:audio` credit suffix.
+  // kling-3.0's model default is sound ON (kie models.ts extraParams +
+  // kling3-client `?? true`) → defaultOn keeps billing aligned with what an
+  // intent-less request actually generates; kling 2.6 defaults OFF.
+  kling: { mode: "native_speech", field: "sound", affectsCost: true },
+  "kling-3.0": { mode: "native_speech", field: "sound", affectsCost: true, defaultOn: true },
+  // Kling 3.0 Omni (Replicate kwaivgi/kling-v3-omni-video) — the Omni tier's
+  // headline feature IS native dialogue (per-character voices, unified audio
+  // timeline). Lever is Replicate's `generate_audio` (default true in our
+  // provider config → defaultOn); audio is priced into the flat per-duration
+  // rate, so NOT cost-affecting (no :audio composite).
+  "kling-3-omni": { mode: "native_speech", field: "generateAudio", defaultOn: true },
   // Seedance 1.x — optional ambient audio (generate_audio); not dialogue.
   seedance: { mode: "ambient", field: "generateAudio" },
   // Seedance 2.0 — multimodal; lip-syncs to a supplied reference-audio track.
@@ -1457,11 +1483,11 @@ export function videoModelSupportsAudio(model: string | undefined): boolean {
 
 /**
  * True when the model can produce lip-synced spoken DIALOGUE — either natively
- * (VEO) or driven by a supplied audio track (Seedance 2.0). Drives the Story→Video
- * dialogue auto-pick: in-model speech + character revoice (VEO) / character-voiced
- * reference audio (Seedance 2.0) vs. the TTS + separate-lip-sync fallback.
- * Ambient-only models (Kling, Seedance 1.x) return `false` — their audio is SFX,
- * not speech.
+ * (VEO 3.x, Kling 2.6/3.0/Omni) or driven by a supplied audio track (Seedance
+ * 2.0). Drives the Story→Video dialogue auto-pick: in-model speech + character
+ * revoice (VEO, Kling) / character-voiced reference audio (Seedance 2.0) vs.
+ * the TTS + separate-lip-sync fallback. Ambient-only models (Seedance 1.x)
+ * return `false` — their audio is SFX, not speech.
  */
 export function videoModelCanSpeakDialogue(model: string | undefined): boolean {
   const mode = getVideoAudioCapability(model).mode