dsh-hyperframes 0.3.1 → 0.4.0

package/skills/media-use/audio/scripts/lib/gemini-auth_test.py

@@ -0,0 +1,90 @@
+"""Credential-boundary tests; stub Google's transport, never use real secrets."""
+
+import importlib.util
+import json
+import os
+import sys
+from pathlib import Path
+import tempfile
+import types
+import unittest
+from unittest.mock import Mock, patch
+
+
+# Keep the credential subprocess protocol UTF-8 on every platform.
+for _stream in (sys.stdout, sys.stderr):
+    if hasattr(_stream, "reconfigure"):
+        _stream.reconfigure(encoding="utf-8", errors=_stream.errors)
+
+spec = importlib.util.spec_from_file_location("gemini_auth", Path(__file__).with_name("gemini-auth.py"))
+auth = importlib.util.module_from_spec(spec)
+spec.loader.exec_module(auth)
+
+
+class AuthenticationTests(unittest.TestCase):
+    def setUp(self):
+        self.info = {"type": "service_account", "project_id": "account-project", "token_uri": "https://untrusted.invalid/token"}
+        self.credentials = Mock(token="fixture-token")
+        self.factory = Mock(return_value=self.credentials)
+        self.request = Mock(return_value=object())
+        transport = types.ModuleType("google.auth.transport.requests")
+        transport.Request = self.request
+        oauth = types.ModuleType("google.oauth2")
+        oauth.service_account = types.SimpleNamespace(Credentials=types.SimpleNamespace(from_service_account_info=self.factory))
+        modules = {name: types.ModuleType(name) for name in ("google", "google.auth", "google.auth.transport")}
+        modules.update({"google.auth.transport.requests": transport, "google.oauth2": oauth})
+        self.addCleanup(patch.stopall)
+        patch.dict("sys.modules", modules).start()
+        patch.dict(os.environ, {"GCS_CREDS": json.dumps(self.info)}, clear=True).start()
+
+    def test_scope_endpoint_and_refresh(self):
+        self.assertEqual(auth.authenticate(), {"token": "fixture-token", "project": "account-project"})
+        info = self.factory.call_args.args[0]
+        self.assertEqual(info["token_uri"], "https://oauth2.googleapis.com/token")
+        self.assertEqual(self.factory.call_args.kwargs["scopes"], ["https://www.googleapis.com/auth/generative-language.retriever"])
+        self.credentials.refresh.assert_called_once_with(self.request.return_value)
+
+    def test_file_takes_precedence_over_json_environment(self):
+        with tempfile.TemporaryDirectory() as directory:
+            path = Path(directory) / "service.json"
+            path.write_text(json.dumps({**self.info, "project_id": "file-project"}), encoding="utf-8")
+            os.environ["GOOGLE_APPLICATION_CREDENTIALS"] = str(path)
+            os.environ["GCS_CREDS"] = "invalid-json"
+            self.assertEqual(auth.authenticate()["project"], "file-project")
+
+    def test_quota_project_precedence(self):
+        os.environ["GCLOUD_PROJECT_ID"] = "alias-project"
+        self.assertEqual(auth.authenticate()["project"], "alias-project")
+        os.environ["GOOGLE_CLOUD_PROJECT"] = "explicit-project"
+        self.assertEqual(auth.authenticate()["project"], "explicit-project")
+
+    def test_user_adc_is_rejected_before_exchange(self):
+        os.environ["GCS_CREDS"] = json.dumps({"type": "authorized_user"})
+        self.assertIn("service-account JSON", auth.authenticate()["error"])
+        self.factory.assert_not_called()
+
+    def test_invalid_json_or_missing_file_does_not_fall_back(self):
+        os.environ["GCS_CREDS"] = "private-invalid-json"
+        self.assertIn("error", auth.authenticate())
+        os.environ["GCS_CREDS"] = json.dumps(self.info)
+        os.environ["GOOGLE_APPLICATION_CREDENTIALS"] = "/missing/service-account-fixture.json"
+        self.assertIn("error", auth.authenticate())
+        self.factory.assert_not_called()
+
+    def test_library_errors_are_redacted(self):
+        for boundary in (self.factory, self.credentials.refresh):
+            with self.subTest(boundary=boundary):
+                boundary.side_effect = RuntimeError("private-key-and-token")
+                result = auth.authenticate()
+                self.assertIn("error", result)
+                self.assertNotIn("private-key-and-token", json.dumps(result))
+                boundary.side_effect = None
+
+    def test_missing_dependency_has_actionable_error(self):
+        with patch.dict("sys.modules", {"google.auth.transport.requests": None}):
+            self.assertIn("pip install google-auth requests", auth.authenticate()["error"])
+        self.factory.assert_not_called()
+
+
+if __name__ == "__main__":
+    unittest.main()

package/skills/media-use/audio/scripts/lib/gemini-tts.mjs

@@ -0,0 +1,122 @@
+import { mkdirSync, writeFileSync } from "node:fs";
+import { dirname } from "node:path";
+import { geminiAuth } from "./gemini-auth.mjs";
+
+export const GEMINI_TTS_MODEL = "gemini-3.8-flash-tts";
+
+export const GEMINI_TTS_MODELS = [
+  GEMINI_TTS_MODEL,
+  "gemini-3.8-flash-lite-tts",
+  "gemini-3.1-flash-tts-preview",
+  "gemini-2.5-pro-preview-tts",
+  "gemini-2.5-flash-preview-tts",
+];
+
+// 3.8 returns WAV; older models return PCM that we wrap without resampling.
+// The shared engine transcribes the saved audio for word timings.
+export async function synthesizeGemini(
+  { text, voiceId = "Kore", model = GEMINI_TTS_MODEL, style, speed = 1, wavAbs },
+  { fetchImpl = fetch, authenticate = geminiAuth } = {},
+) {
+  let secret;
+  try {
+    if (!GEMINI_TTS_MODELS.includes(model)) {
+      throw new Error(`Unsupported Gemini TTS model: ${model}`);
+    }
+    if (speed !== 1) throw new Error("Gemini TTS uses style for pacing; omit speed or use 1");
+    const modern = model.startsWith("gemini-3.8-");
+    if (!modern && /^(voice_|voicekey_)/.test(voiceId)) {
+      throw new Error(
+        "Custom Gemini voices require a 3.8 TTS model; use a prebuilt voice with older models",
+      );
+    }
+    const auth = authenticate();
+    secret = auth.secret;
+    const content = {
+      type: "text",
+      text:
+        !modern && style ? `Read the following text with this delivery: ${style}\n\n${text}` : text,
+    };
+    if (modern && style) content.annotations = [{ type: "speech_metadata", style }];
+    const response = await fetchImpl(
+      "https://generativelanguage.googleapis.com/v1beta/interactions",
+      {
+        method: "POST",
+        headers: { "Content-Type": "application/json", ...auth.headers },
+        signal: AbortSignal.timeout(120_000),
+        body: JSON.stringify({
+          model,
+          input: [{ type: "user_input", content: [content] }],
+          response_format: modern ? { type: "audio", mime_type: "audio/wav" } : { type: "audio" },
+          generation_config: { speech_config: [{ voice: voiceId }] },
+          store: false,
+        }),
+      },
+    );
+    if (!response.ok) {
+      const detail = await response.text();
+      throw new Error(`Gemini TTS HTTP ${response.status}: ${detail}`);
+    }
+    const payload = await response.json();
+    if (payload.status !== "completed") {
+      throw new Error(`Gemini TTS did not complete (${payload.status ?? "missing status"})`);
+    }
+    const audio = (payload.steps ?? [])
+      .filter((step) => step.type === "model_output")
+      .flatMap((step) => step.content ?? [])
+      .filter((part) => part.type === "audio");
+    if (audio.length !== 1 || !audio[0].data) {
+      throw new Error("Gemini TTS returned no single audio block");
+    }
+    let bytes = Buffer.from(audio[0].data, "base64");
+    if (!modern && /^audio\/l16(?:;|$)/i.test(audio[0].mime_type ?? "")) {
+      bytes = pcmToWav(bytes, audio[0].mime_type);
+    } else if (audio[0].mime_type !== "audio/wav") {
+      throw new Error("Gemini TTS returned an unsupported audio format");
+    }
+    if (
+      bytes.length <= 44 ||
+      bytes.toString("ascii", 0, 4) !== "RIFF" ||
+      bytes.toString("ascii", 8, 12) !== "WAVE"
+    ) {
+      throw new Error("Gemini TTS returned invalid WAV audio");
+    }
+    mkdirSync(dirname(wavAbs), { recursive: true });
+    writeFileSync(wavAbs, bytes);
+    return { ok: true, words: null };
+  } catch (error) {
+    // Error responses must never echo the credential into logs or metadata.
+    const message = String(error?.message ?? error);
+    return {
+      ok: false,
+      words: null,
+      error: secret ? message.split(secret).join("[redacted]") : message,
+    };
+  }
+}
+
+function pcmToWav(pcm, mime) {
+  const rate = Number(/(?:^|;)\s*rate=(\d+)(?:;|$)/i.exec(mime)?.[1]);
+  const channels = /(?:^|;)\s*channels=([^;]+)/i.exec(mime)?.[1];
+  const codec = /(?:^|;)\s*codec=([^;]+)/i.exec(mime)?.[1];
+  if ((channels && channels.trim() !== "1") || (codec && codec.trim() !== "pcm")) {
+    throw new Error("Gemini TTS returned unsupported PCM channels or codec");
+  }
+  if (!Number.isInteger(rate) || rate < 8000 || rate > 96000 || !pcm.length || pcm.length % 2) {
+    throw new Error("Gemini TTS returned invalid PCM audio or sample rate");
+  }
+  const header = Buffer.alloc(44);
+  header.write("RIFF");
+  header.writeUInt32LE(36 + pcm.length, 4);
+  header.write("WAVEfmt ", 8);
+  header.writeUInt32LE(16, 16);
+  header.writeUInt16LE(1, 20);
+  header.writeUInt16LE(1, 22);
+  header.writeUInt32LE(rate, 24);
+  header.writeUInt32LE(rate * 2, 28);
+  header.writeUInt16LE(2, 32);
+  header.writeUInt16LE(16, 34);
+  header.write("data", 36);
+  header.writeUInt32LE(pcm.length, 40);
+  return Buffer.concat([header, pcm]);
+}

package/skills/media-use/audio/scripts/lib/gemini-tts.test.mjs

@@ -0,0 +1,243 @@
+import { test } from "node:test";
+import assert from "node:assert/strict";
+import { mkdtempSync, readFileSync, rmSync, existsSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { synthesizeGemini, GEMINI_TTS_MODEL } from "./gemini-tts.mjs";
+import { pickProvider, resolveVoiceId, synthesizeOne } from "./tts.mjs";
+
+function fixture(t) {
+  const dir = mkdtempSync(join(tmpdir(), "gemini-tts-"));
+  const saved = { ...process.env };
+  process.env.GEMINI_API_KEY = "test-gemini-key";
+  delete process.env.GOOGLE_API_KEY;
+  delete process.env.GOOGLE_APPLICATION_CREDENTIALS;
+  delete process.env.GCS_CREDS;
+  t.after(() => {
+    process.env = saved;
+    rmSync(dir, { recursive: true, force: true });
+  });
+  const wav = Buffer.alloc(48);
+  wav.write("RIFF");
+  wav.writeUInt32LE(40, 4);
+  wav.write("WAVEfmt ", 8);
+  wav.writeUInt32LE(16, 16);
+  wav.writeUInt16LE(1, 20);
+  wav.writeUInt16LE(1, 22);
+  wav.writeUInt32LE(24000, 24);
+  wav.writeUInt32LE(48000, 28);
+  wav.writeUInt16LE(2, 32);
+  wav.writeUInt16LE(16, 34);
+  wav.write("data", 36);
+  wav.writeUInt32LE(4, 40);
+  const audio = { type: "audio", mime_type: "audio/wav", data: wav.toString("base64") };
+  const payload = { status: "completed", steps: [{ type: "model_output", content: [audio] }] };
+  return {
+    wav,
+    audio,
+    payload,
+    args: { text: "Hello there.", voiceId: "Kore", wavAbs: join(dir, "voice", "one.wav") },
+  };
+}
+
+test("Gemini preserves verbatim text, directs style separately, saves WAV and requests transcription", async (t) => {
+  const { wav, payload, args } = fixture(t);
+  t.mock.method(globalThis, "fetch", async (url, options) => {
+    assert.equal(url, "https://generativelanguage.googleapis.com/v1beta/interactions");
+    assert.equal(options.headers["x-goog-api-key"], "test-gemini-key");
+    const body = JSON.parse(options.body);
+    assert.equal(body.model, GEMINI_TTS_MODEL);
+    assert.equal(body.store, false);
+    assert.deepEqual(body.input[0].content, [
+      {
+        type: "text",
+        text: args.text,
+        annotations: [{ type: "speech_metadata", style: "Warm and calm" }],
+      },
+    ]);
+    assert.deepEqual(body.generation_config.speech_config, [{ voice: "Kore" }]);
+    assert.equal(body.response_format.mime_type, "audio/wav");
+    return Response.json(payload);
+  });
+  const result = await synthesizeOne({ ...args, provider: "gemini", style: "Warm and calm" });
+  assert.deepEqual(result, { ok: true, words: null });
+  assert.deepEqual(readFileSync(args.wavAbs), wav);
+});
+
+test("Flash-Lite and GOOGLE_API_KEY work without a Gemini key", async (t) => {
+  const { payload, args } = fixture(t);
+  delete process.env.GEMINI_API_KEY;
+  process.env.GOOGLE_API_KEY = "test-google-key";
+  assert.equal(pickProvider("gemini"), "gemini");
+  assert.equal(await resolveVoiceId({ provider: "gemini" }), "Kore");
+  const result = await synthesizeGemini(
+    { ...args, model: "gemini-3.8-flash-lite-tts" },
+    {
+      fetchImpl: async (_, options) => {
+        assert.equal(options.headers["x-goog-api-key"], "test-google-key");
+        const body = JSON.parse(options.body);
+        assert.equal(body.model, "gemini-3.8-flash-lite-tts");
+        assert.equal(body.input[0].content[0].annotations, undefined);
+        return Response.json(payload);
+      },
+    },
+  );
+  assert.equal(result.ok, true);
+});
+
+test("Gemini remains opt-in even with a key and preserves explicitly chosen voices", async (t) => {
+  fixture(t);
+  assert.notEqual(pickProvider(), "gemini");
+  assert.equal(
+    await resolveVoiceId({ provider: "gemini", userVoice: "voice_custom" }),
+    "voice_custom",
+  );
+  delete process.env.GEMINI_API_KEY;
+  assert.throws(() => pickProvider("gemini"), /GEMINI_API_KEY or GOOGLE_API_KEY/);
+});
+
+test("invalid config fails before spending a generation request", async (t) => {
+  const { args } = fixture(t);
+  const deps = { fetchImpl: () => assert.fail("must not call the API") };
+  for (const change of [{ model: "gemini-2.5-flash" }, { speed: 1.2 }]) {
+    const result = await synthesizeGemini({ ...args, ...change }, deps);
+    assert.equal(result.ok, false);
+    assert.ok(result.error);
+  }
+  delete process.env.GEMINI_API_KEY;
+  assert.match((await synthesizeGemini(args, deps)).error, /needs GEMINI_API_KEY/);
+  assert.equal(existsSync(args.wavAbs), false);
+});
+
+test("HTTP and network failures stay actionable without leaking the key", async (t) => {
+  const { args } = fixture(t);
+  const result = await synthesizeGemini(args, {
+    fetchImpl: async () => new Response("quota exceeded test-gemini-key", { status: 429 }),
+  });
+  assert.equal(result.ok, false);
+  assert.match(result.error, /HTTP 429: quota exceeded/);
+  assert.ok(!result.error.includes("test-gemini-key"));
+  const timeout = await synthesizeGemini(args, {
+    fetchImpl: async () => {
+      throw new Error("timed out");
+    },
+  });
+  assert.match(timeout.error, /timed out/);
+  assert.equal(existsSync(args.wavAbs), false);
+});
+
+test("incomplete, missing, raw PCM and malformed audio cannot become a successful WAV", async (t) => {
+  const { args, payload, audio } = fixture(t);
+  const cases = [
+    { ...payload, status: "incomplete" },
+    { status: "completed", steps: [] },
+    ...[{ ...audio, mime_type: "audio/l16" }, { ...audio, data: "not audio" }, audio].map(
+      (part, i) => ({
+        status: "completed",
+        steps: [{ type: "model_output", content: i === 2 ? [part, part] : [part] }],
+      }),
+    ),
+  ];
+  for (const body of cases) {
+    const result = await synthesizeGemini(args, { fetchImpl: async () => Response.json(body) });
+    assert.equal(result.ok, false);
+    assert.equal(existsSync(args.wavAbs), false);
+  }
+});
+
+for (const model of [
+  "gemini-3.1-flash-tts-preview",
+  "gemini-2.5-pro-preview-tts",
+  "gemini-2.5-flash-preview-tts",
+]) {
+  test(`${model} uses legacy delivery prompts and wraps PCM as mono WAV`, async (t) => {
+    const { args, wav } = fixture(t);
+    const pcm = wav.subarray(44);
+    const result = await synthesizeGemini(
+      { ...args, model, style: "Warm and clear" },
+      {
+        fetchImpl: async (_, options) => {
+          const body = JSON.parse(options.body);
+          assert.deepEqual(body.response_format, { type: "audio" });
+          assert.equal(body.input[0].content[0].annotations, undefined);
+          assert.ok(body.input[0].content[0].text.endsWith(args.text));
+          assert.ok(body.input[0].content[0].text.includes("Warm and clear"));
+          return Response.json({
+            status: "completed",
+            steps: [
+              {
+                type: "model_output",
+                content: [
+                  {
+                    type: "audio",
+                    mime_type: "audio/L16;codec=pcm;rate=24000",
+                    data: pcm.toString("base64"),
+                  },
+                ],
+              },
+            ],
+          });
+        },
+      },
+    );
+    assert.equal(result.ok, true, result.error);
+    assert.deepEqual(readFileSync(args.wavAbs), wav);
+  });
+}
+
+test("service-account bearer and quota project reach synthesis, and token errors are redacted", async (t) => {
+  const { args, payload } = fixture(t);
+  const authenticate = () => ({
+    headers: { Authorization: "Bearer secret-token", "x-goog-user-project": "test-project" },
+    secret: "secret-token",
+  });
+  const ok = await synthesizeGemini(args, {
+    authenticate,
+    fetchImpl: async (_, options) => {
+      assert.equal(options.headers.Authorization, "Bearer secret-token");
+      assert.equal(options.headers["x-goog-user-project"], "test-project");
+      assert.equal(options.headers["x-goog-api-key"], undefined);
+      return Response.json(payload);
+    },
+  });
+  assert.equal(ok.ok, true);
+  const failed = await synthesizeGemini(args, {
+    authenticate,
+    fetchImpl: async () => new Response("denied secret-token", { status: 403 }),
+  });
+  assert.match(failed.error, /HTTP 403/);
+  assert.ok(!failed.error.includes("secret-token"));
+});
+
+test("older models reject unsupported PCM and custom voices", async (t) => {
+  const { args } = fixture(t);
+  for (const mime of [
+    "audio/l16",
+    "audio/l16;rate=0",
+    "audio/l16;rate=24000;channels=2",
+    "audio/l16;rate=24000;codec=other",
+  ]) {
+    const result = await synthesizeGemini(
+      { ...args, model: "gemini-3.1-flash-tts-preview" },
+      {
+        fetchImpl: async () =>
+          Response.json({
+            status: "completed",
+            steps: [
+              {
+                type: "model_output",
+                content: [{ type: "audio", mime_type: mime, data: "AAAAAA==" }],
+              },
+            ],
+          }),
+      },
+    );
+    assert.equal(result.ok, false);
+    assert.equal(existsSync(args.wavAbs), false);
+  }
+  const result = await synthesizeGemini(
+    { ...args, model: "gemini-2.5-pro-preview-tts", voiceId: "voice_custom" },
+    { fetchImpl: () => assert.fail("must not generate") },
+  );
+  assert.match(result.error, /Custom Gemini voices require/);
+});

package/skills/media-use/audio/scripts/lib/heygen.mjs

@@ -1,3 +1,4 @@
+import { fetchMedia } from "../../../scripts/lib/media-fetch.mjs";
 // heygen.mjs — vendored HeyGen REST helpers (auth + transport) for the audio
 // pipeline. The credential resolver matches the hyperframes CLI auth: first
 // usable source wins — $HEYGEN_API_KEY / $HYPERFRAMES_API_KEY → a nearby .env → ~/.heygen/
@@ -125,7 +126,7 @@ export async function heygenJSON(path, { method = "GET", headers = {}, body } =
 
 // Download a (presigned) URL to destPath; returns byte length.
 export async function downloadTo(url, destPath) {
-  const res = await fetch(url);
+  const res = await fetchMedia(url);
   if (!res.ok) throw new Error(`download HTTP ${res.status}: ${String(url).slice(0, 80)}`);
   const bytes = Buffer.from(await res.arrayBuffer());
   mkdirSync(dirname(destPath), { recursive: true });

package/skills/media-use/audio/scripts/lib/tts.mjs

@@ -1,3 +1,4 @@
+import { fetchMedia } from "../../../scripts/lib/media-fetch.mjs";
 // tts.mjs — multi-provider TTS for the media audio engine. The provider chain,
 // auto-detected from env, is the one documented in ../SKILL.md:
 //
@@ -19,6 +20,8 @@ import { tmpdir } from "node:os";
 import { dirname, join } from "node:path";
 import { heygenAuthHeaders, heygenCredential, heygenJSON } from "./heygen.mjs";
 import { pythonInvocation } from "./python.mjs";
+import { synthesizeGemini } from "./gemini-tts.mjs";
+import { geminiConfigured } from "./gemini-auth.mjs";
 
 // ── provider detection ────────────────────────────────────────────────────────
 export function heygenAvailable() {
@@ -36,8 +39,12 @@ export function elevenlabsAvailable() {
 // First available provider wins; an explicit choice is honored (and validated).
 export function pickProvider(userProvider) {
   if (userProvider) {
-    if (!["heygen", "elevenlabs", "kokoro"].includes(userProvider))
-      throw new Error(`invalid provider "${userProvider}" (heygen | elevenlabs | kokoro)`);
+    if (!["heygen", "elevenlabs", "kokoro", "gemini"].includes(userProvider))
+      throw new Error(`invalid provider "${userProvider}" (heygen | elevenlabs | kokoro | gemini)`);
+    if (userProvider === "gemini" && !geminiConfigured())
+      throw new Error(
+        "provider=gemini needs GEMINI_API_KEY or GOOGLE_API_KEY, or service-account credentials (GOOGLE_APPLICATION_CREDENTIALS or GCS_CREDS)",
+      );
     if (userProvider === "heygen" && !heygenAvailable())
       throw new Error(
         "provider=heygen but no HeyGen credentials (set $HEYGEN_API_KEY or run `npx hyperframes auth login`)",
@@ -55,6 +62,7 @@ export function pickProvider(userProvider) {
 // their own defaults.
 export async function resolveVoiceId({ provider, userVoice, lang = "en" }) {
   if (userVoice) return userVoice;
+  if (provider === "gemini") return "Kore";
   if (provider === "elevenlabs") return "21m00Tcm4TlvDq8ikWAM"; // Rachel
   if (provider === "kokoro") {
     if (lang === "en") return "am_michael";
@@ -247,10 +255,14 @@ export async function synthesizeOne({
   voiceId,
   lang = "en",
   speed = 1.0,
+  model,
+  style,
   wavAbs,
   hyperframesDir,
 }) {
   if (provider === "heygen") return synthesizeHeygen({ text, voiceId, lang, speed, wavAbs });
+  if (provider === "gemini")
+    return synthesizeGemini({ text, voiceId, model, style, speed, wavAbs });
   if (provider === "elevenlabs") {
     // The Python helper writes straight to wavAbs; unlike heygen (transcodeToWav)
     // and kokoro (the `hyperframes tts` CLI), it does NOT create the parent dir,
@@ -312,7 +324,7 @@ export async function synthesizeHeygen({ text, voiceId, lang, speed, wavAbs }, d
     if (!inner.audio_url) {
       return { ok: false, words: null, error: "HeyGen /voices/speech returned no audio_url" };
     }
-    const res = await fetchImpl(inner.audio_url);
+    const res = await fetchMedia(inner.audio_url, { fetchImpl });
     if (!res.ok) {
       return { ok: false, words: null, error: `audio_url fetch failed: HTTP ${res.status}` };
     }

package/skills/media-use/audio/scripts/wait-bgm.mjs

@@ -48,10 +48,14 @@ function isProcessAlive(pid) {
 }
 
 function readTail(path, maxChars = 6000) {
-  if (!path || !existsSync(path)) return "";
-  const s = statSync(path);
-  const txt = readFileSync(path, "utf8");
-  return txt.slice(Math.max(0, txt.length - Math.min(maxChars, s.size)));
+  if (!path) return "";
+  try {
+    const txt = readFileSync(path, "utf8");
+    return txt.slice(Math.max(0, txt.length - maxChars));
+  } catch (error) {
+    if (error.code === "ENOENT" || error.code === "ENOTDIR") return "";
+    throw error;
+  }
 }
 
 function detectFailure(logTail) {

package/skills/media-use/audio/scripts/wait-bgm.test.mjs

@@ -0,0 +1,65 @@
+import assert from "node:assert/strict";
+import { readFileSync } from "node:fs";
+import { test } from "node:test";
+import { runInNewContext } from "node:vm";
+
+const source = readFileSync(new URL("./wait-bgm.mjs", import.meta.url), "utf8");
+const start = source.indexOf("function readTail(");
+const end = source.indexOf("\nfunction detectFailure(", start);
+function load(read) {
+  return runInNewContext(`${source.slice(start, end)}; readTail`, {
+    readFileSync: read,
+    existsSync: () => true,
+    statSync: () => {
+      throw new Error("pathname stat must not precede log read");
+    },
+  });
+}
+
+test("reads a log once without a separate pathname check", () => {
+  let calls = 0;
+  const read = load((path, encoding) => {
+    calls++;
+    assert.equal(path, "renderer.log");
+    assert.equal(encoding, "utf8");
+    return "prefix\nRuntimeError: failed";
+  });
+  assert.equal(read("renderer.log", 20), "RuntimeError: failed");
+  assert.equal(calls, 1);
+});
+
+test("preserves UTF-16 character tail boundaries and zero-length tails", () => {
+  const txt = "🎵日本語".repeat(2000);
+  const read = load(() => txt);
+  assert.equal(read("log"), txt.slice(-6000));
+  assert.equal(read("log", 0), "");
+});
+
+for (const code of ["ENOENT", "ENOTDIR"]) {
+  test(`a log removed during polling is absent (${code})`, () => {
+    const read = load(() => {
+      throw Object.assign(new Error(code), { code });
+    });
+    assert.equal(read("log"), "");
+  });
+}
+
+test("preserves unexpected read errors", () => {
+  const error = Object.assign(new Error("denied"), { code: "EACCES" });
+  assert.throws(
+    () =>
+      load(() => {
+        throw error;
+      })("log"),
+    (caught) => caught === error,
+  );
+});
+
+test("empty log path does not access the filesystem", () => {
+  assert.equal(
+    load(() => {
+      throw new Error("unexpected read");
+    })(""),
+    "",
+  );
+});

package/skills/media-use/references/audio.md

@@ -9,9 +9,10 @@ shot), use the shared engine at `audio/scripts/audio.mjs`. It takes a neutral
 node <SKILL_DIR>/audio/scripts/audio.mjs --request ./audio_request.json --out ./audio_meta.json
 ```
 
-- **Request** `{ provider?, lang?, speed?, lines: [{ id, text, sfx?: [names] }], bgm: { mode?, query?, prompt? } }`: `id` joins each line back to your model; `bgm.mode` = `retrieve | generate | none` (omit for auto). `--only tts,bgm,sfx` runs a subset and merges into an existing `--out`.
+- **Request** `{ provider?, voice?, lang?, speed?, tts_model?, style?, lines: [{ id, text, style?, sfx?: [names] }], bgm: { mode?, query?, prompt? } }`: `id` joins each line back to your model; `bgm.mode` = `retrieve | generate | none` (omit for auto). `--only tts,bgm,sfx` runs a subset and merges into an existing `--out`.
+- **Gemini narration** is opt-in with `provider: "gemini"` and an API key or service-account credentials. `tts_model` defaults to `gemini-3.8-flash-tts`; 3.8 Flash-Lite, 3.1 Flash Preview, and 2.5 Pro/Flash Preview TTS are also supported. `style` directs delivery; a line's style overrides the request's style. CLI overrides: `--tts-model`, `--style`. See `audio/references/tts.md` for a complete request. The existing automatic provider order is unchanged.
 - **Output** `audio_meta.json` (id-keyed): `voices[].{path,duration_s,words[]}` (word timestamps for captions), `sfx[]`, `bgm`, `total_duration_s`.
-- **HeyGen free-usage path**: HeyGen CLI auth unlocks TTS plus music/SFX retrieval. Local/provider-specific generators are explicit alternatives where installed; run `node <SKILL_DIR>/scripts/resolve.mjs --doctor` before assuming retrieval or TTS will work.
+- **HeyGen free-usage path**: HeyGen CLI auth unlocks TTS plus music/SFX retrieval. Local/provider-specific generators are explicit alternatives where installed; run `npx hyperframes media-use resolve --doctor` before assuming retrieval or TTS will work.
 - If BGM took the generate path (`bgm_pending: true`), run `audio/scripts/wait-bgm.mjs` before final render.
 
 Single-shot helpers: `audio/scripts/heygen-tts.mjs` (one voice file). Transcription / background removal / captions use the `hyperframes` CLI (`transcribe`, `remove-background`), see the per-topic guides in `audio/references/` (`tts.md`, `bgm.md`, `sfx.md`, `transcribe.md`, `remove-background.md`, `captions/`).