dsh-hyperframes 0.9.0 → 0.9.2

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

@@ -12,9 +12,10 @@
 // Missing/failed BGM never blocks a render.
 
 import { spawn, spawnSync } from "node:child_process";
-import { existsSync, mkdirSync, openSync, closeSync } from "node:fs";
+import { existsSync, mkdirSync, openSync, closeSync, rmSync } from "node:fs";
 import { join } from "node:path";
 import { downloadTo, searchSounds } from "./heygen.mjs";
+import { agentWritePath } from "./media-record.mjs";
 import { pythonInvocation } from "./python.mjs";
 
 const r3 = (x) => Number(x.toFixed(3));
@@ -45,12 +46,12 @@ function pipInstall(deps) {
 }
 
 // ── retrieval (HeyGen music library) ──────────────────────────────────────────
-export async function retrieveBgm({ query, headers, hyperframesDir, hasVoice }) {
+export async function retrieveBgm({ query, headers, hyperframesDir, hasVoice, anomalies }) {
   const q = query || "calm cinematic underscore";
   const results = await searchSounds(q, "music", headers, { limit: 5 });
   if (!results.length) return null;
   const top = results[0];
-  const rel = "assets/bgm/track.mp3";
+  const rel = agentWritePath(hyperframesDir, "assets/bgm/track.mp3", { anomalies });
   await downloadTo(top.audio_url, join(hyperframesDir, rel));
   return {
     path: rel,
@@ -113,8 +114,9 @@ export function generateBgmDetached({
   lyriaRecipe,
   seedSeconds = 28,
   hasVoice,
+  anomalies,
 }) {
-  const rel = "assets/bgm/track.wav";
+  const rel = agentWritePath(hyperframesDir, "assets/bgm/track.wav", { anomalies });
   const abs = join(hyperframesDir, rel);
   mkdirSync(join(hyperframesDir, "assets", "bgm"), { recursive: true });
   const log = join(hyperframesDir, "assets", "bgm", `bgm-${Date.now()}.log`);
@@ -141,6 +143,7 @@ export function generateBgmDetached({
       "--prompt",
       prompt,
     ]);
+    rmSync(abs, { force: true }); // wait-bgm takes any file here as the finished track
     const proc = spawn(cmd, args, { detached: true, stdio: ["ignore", fd, fd] });
     proc.unref();
     closeSync(fd);
@@ -159,6 +162,7 @@ export function generateBgmDetached({
     const loops = targetS > seedS ? Math.ceil(targetS / seedS) : 1;
     const script = musicgenScript({ prompt, abs, targetS, seedS });
     const { cmd, args } = pythonInvocation(["-c", script]);
+    rmSync(abs, { force: true });
     const proc = spawn(cmd, args, { detached: true, stdio: ["ignore", fd, fd] });
     proc.unref();
     closeSync(fd);

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

@@ -1,6 +1,15 @@
 import { test } from "node:test";
 import assert from "node:assert/strict";
-import { BGM_BED_VOLUME, BGM_SILENT_VOLUME, bgmDefaultVolume } from "./bgm.mjs";
+import { existsSync, mkdirSync, mkdtempSync, rmSync, writeFileSync } from "node:fs";
+import { join } from "node:path";
+import { tmpdir } from "node:os";
+import { appendRecord } from "../../../scripts/lib/manifest.mjs";
+import {
+  BGM_BED_VOLUME,
+  BGM_SILENT_VOLUME,
+  bgmDefaultVolume,
+  generateBgmDetached,
+} from "./bgm.mjs";
 
 // Regression: narrated pipelines used to ship BGM at 0.8 (≈ -2 dB), ~16 dB
 // hotter than a music bed under a voice should be. The default under narration
@@ -28,3 +37,38 @@ test("the narrated default is well below the voice (≈ 0 dBFS)", () => {
     `bed should sit ≥16 dB under the voice, got ${separation.toFixed(1)} dB`,
   );
 });
+
+test(
+  "generating music again clears the engine's old track, so waiting cannot mistake it for the new one",
+  { skip: process.platform === "win32" && "the fake python is a shell script" },
+  (t) => {
+    const dir = mkdtempSync(join(tmpdir(), "hf-bgm-"));
+    const path = process.env.PATH;
+    t.after(() => {
+      process.env.PATH = path;
+      rmSync(dir, { recursive: true, force: true });
+    });
+    mkdirSync(join(dir, "bin"));
+    for (const name of ["python3", "python"])
+      writeFileSync(join(dir, "bin", name), "#!/bin/sh\nexit 0\n", { mode: 0o755 });
+    process.env.PATH = `${join(dir, "bin")}:${path}`;
+    mkdirSync(join(dir, "assets/bgm"), { recursive: true });
+    writeFileSync(join(dir, "assets/bgm/track.wav"), "last run's track");
+    appendRecord(dir, {
+      id: "bgm_001",
+      type: "bgm",
+      path: "assets/bgm/track.wav",
+      source: "generated",
+    });
+
+    const gen = generateBgmDetached({
+      prompt: "calm",
+      durationS: 5,
+      hyperframesDir: dir,
+      anomalies: [],
+    });
+
+    assert.equal(gen.path, "assets/bgm/track.wav");
+    assert.equal(existsSync(join(dir, "assets/bgm/track.wav")), false);
+  },
+);

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

@@ -1,15 +1,51 @@
 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/
+// usable source wins — a host gateway ($HEYGEN_API_BASE with its own
+// $HEYGEN_API_KEY) → a host-injected OAuth $HEYGEN_ACCESS_TOKEN (Bearer) →
+// $HEYGEN_API_KEY / $HYPERFRAMES_API_KEY → a nearby .env → ~/.heygen/
 // credentials (oauth → Bearer, else api_key → X-Api-Key; $HEYGEN_CONFIG_DIR
-// overrides the dir). Vendored so the skill ships standalone. Pure node.
+// overrides the dir). $HEYGEN_API_BASE moves every request to that host, as it
+// does for the heygen CLI; plain HTTP needs $HEYGEN_ALLOW_HTTP=1, as there.
+// Vendored so the skill ships standalone. Pure node.
 
-import { existsSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
+import { mkdirSync, readFileSync, writeFileSync } from "node:fs";
 import { homedir } from "node:os";
 import { dirname, join, resolve } from "node:path";
 
 export const HEYGEN_BASE = "https://api.heygen.com/v3";
+
+// The v3 base every request goes to: $HEYGEN_API_BASE when a host app names its own gateway (HyperFrames Desktop
+// forwards it to HeyGen with the API key saved in its Settings), else HeyGen's public API. Plain HTTP carries the key
+// in the clear, so it needs $HEYGEN_ALLOW_HTTP=1, the heygen CLI's own rule.
+export function heygenBase() {
+  const host = process.env.HEYGEN_API_BASE?.trim().replace(/\/+$/, "");
+  if (!host) return HEYGEN_BASE;
+  if (host.startsWith("http://") && process.env.HEYGEN_ALLOW_HTTP !== "1")
+    throw new Error(
+      `HEYGEN_API_BASE (${host}) uses HTTP, which sends the key in plaintext. Set HEYGEN_ALLOW_HTTP=1 to allow it.`,
+    );
+  return `${host}/v3`;
+}
+
+// No base override, or one on HeyGen's own hosts (a canary or dev API).
+function heygenOwnBase() {
+  const host = process.env.HEYGEN_API_BASE?.trim();
+  if (!host) return true;
+  try {
+    const name = new URL(host).hostname;
+    return name === "heygen.com" || name.endsWith(".heygen.com");
+  } catch {
+    return false;
+  }
+}
+
+// A host gateway: the host named its own API base and the key that base accepts. It pays for every call, so it wins
+// over any other credential the environment carries.
+const hostGatewayKey = () =>
+  process.env.HEYGEN_API_BASE?.trim() && process.env.HEYGEN_API_KEY
+    ? process.env.HEYGEN_API_KEY
+    : null;
 export const HEYGEN_CLI_SOURCE_HEADERS = { "X-HeyGen-Source": "cli" };
 // Tool-attribution sent on EVERY media-use HeyGen call regardless of auth type, so
 // the backend can isolate media-use consumption from other free TTS / avatar video.
@@ -17,13 +53,28 @@ export const HEYGEN_CLI_SOURCE_HEADERS = { "X-HeyGen-Source": "cli" };
 // OAuth-only cli-source header above, which also gates the free allowance.
 export const HEYGEN_CLIENT_SOURCE_HEADERS = { "X-HeyGen-Client-Source": "media-use" };
 
+// A missing `.env`, or a `.env` folder (some home dirs have one), is no env file: null. Read without checking first,
+// so the file cannot change between a check and the read.
+function envFileText(path) {
+  try {
+    return readFileSync(path, "utf8");
+  } catch (error) {
+    if (["ENOENT", "ENOTDIR", "EISDIR"].includes(error.code)) return null;
+    throw error;
+  }
+}
+
+// A host app sets these in the environment it spawns, never in a project file: a project's .env naming its own base
+// would send the person's shell HEYGEN_API_KEY to that host.
+const HOST_ONLY = new Set(["HEYGEN_API_BASE", "HEYGEN_ALLOW_HTTP"]);
+
 // Walk up ≤5 dirs from startDir; load the first .env (shell env always wins).
 export function loadEnvFromDir(startDir) {
   let dir = resolve(startDir);
   for (let i = 0; i < 5; i++) {
-    const envPath = join(dir, ".env");
-    if (existsSync(envPath)) {
-      for (const raw of readFileSync(envPath, "utf8").split("\n")) {
+    const text = envFileText(join(dir, ".env"));
+    if (text != null) {
+      for (const raw of text.split("\n")) {
         let line = raw.trim();
         if (!line || line.startsWith("#")) continue;
         if (line.startsWith("export ")) line = line.slice(7).trim();
@@ -36,7 +87,7 @@ export function loadEnvFromDir(startDir) {
           const end = val.indexOf(q, 1);
           val = end > 0 ? val.slice(1, end) : val.slice(1);
         }
-        if (!(key in process.env)) process.env[key] = val;
+        if (!HOST_ONLY.has(key) && !(key in process.env)) process.env[key] = val;
       }
       return;
     }
@@ -48,17 +99,35 @@ export function loadEnvFromDir(startDir) {
 
 // → { headers } | { expired: true } | null. Never throws.
 export function heygenCredential() {
+  const cred = resolveCredential();
+  return cred?.unreadable ? null : cred;
+}
+
+// heygenCredential's answer, or { unreadable: { file, code } } when the credentials path exists but cannot be read
+// (a folder, a locked ~/.heygen), so heygenAuthHeaders can say to fix that path: logging in again would fail there too.
+// Read without checking first, so the file cannot change between a check and the read.
+function resolveCredential() {
+  const gatewayKey = hostGatewayKey();
+  if (gatewayKey) return { headers: { "X-Api-Key": gatewayKey } };
+  // Every other credential belongs to HeyGen: a base on any other host gets none of them.
+  if (!heygenOwnBase()) return null;
+  const accessToken = process.env.HEYGEN_ACCESS_TOKEN;
+  if (accessToken) return { headers: { Authorization: `Bearer ${accessToken}` } };
   const envKey = process.env.HEYGEN_API_KEY || process.env.HYPERFRAMES_API_KEY;
   if (envKey) return { headers: { "X-Api-Key": envKey } };
 
   const file = join(process.env.HEYGEN_CONFIG_DIR || join(homedir(), ".heygen"), "credentials");
-  if (!existsSync(file)) return null;
-  const raw = readFileSync(file, "utf8").trim();
+  let raw;
+  try {
+    raw = readFileSync(file, "utf8").trim();
+  } catch (error) {
+    return error.code === "ENOENT" ? null : { unreadable: { file, code: error.code } };
+  }
   if (!raw) return null;
   if (!raw.startsWith("{")) return { headers: { "X-Api-Key": raw } };
 
   // A malformed credentials file (partial write / wrong shape) must degrade to
-  // "no credential", not crash the engine at startup — this function never throws.
+  // "no credential", not crash the engine at startup.
   let cred;
   try {
     cred = JSON.parse(raw);
@@ -88,7 +157,7 @@ export function heygenAuthMethod() {
 
 // → auth headers object, or throw with a fix hint.
 export function heygenAuthHeaders() {
-  const cred = heygenCredential();
+  const cred = resolveCredential();
   if (cred?.headers) {
     // Only tag OAuth (Bearer) traffic as cli-source — the backend uses it to
     // grant the free allowance for OAuth requests and ignores it for API-key
@@ -98,6 +167,10 @@ export function heygenAuthHeaders() {
       ? { ...cred.headers, ...HEYGEN_CLI_SOURCE_HEADERS, ...HEYGEN_CLIENT_SOURCE_HEADERS }
       : { ...cred.headers, ...HEYGEN_CLIENT_SOURCE_HEADERS };
   }
+  if (cred?.unreadable)
+    throw new Error(
+      `HeyGen credentials at ${cred.unreadable.file} can't be read (${cred.unreadable.code}) — fix or remove that path, then run \`npx hyperframes auth login\``,
+    );
   if (cred?.expired)
     throw new Error(
       "HeyGen OAuth token expired — run `npx hyperframes auth refresh` (or `npx hyperframes auth login`)",
@@ -114,14 +187,25 @@ export async function heygenJSON(path, { method = "GET", headers = {}, body } =
     opts.headers["Content-Type"] = "application/json";
     opts.body = JSON.stringify(body);
   }
-  const res = await fetch(`${HEYGEN_BASE}${path}`, opts);
+  const res = await fetch(`${heygenBase()}${path}`, opts);
   if (!res.ok) {
     const detail = await res.text().catch(() => "");
-    throw new Error(
-      `HeyGen ${method} ${path} → HTTP ${res.status}${detail ? `\n${detail.slice(0, 300)}` : ""}`,
-    );
+    const message = `HeyGen ${method} ${path} → HTTP ${res.status}${detail ? `\n${detail.slice(0, 300)}` : ""}`;
+    throw Object.assign(new Error(message), { status: res.status, body: detail });
+  }
+  // A DELETE may answer 204 with no body.
+  const text = await res.text();
+  return text ? JSON.parse(text) : {};
+}
+
+// HeyGen's own words for a failed call: its {"error":{"message"}}, else the raw body, else the error's message.
+export function heygenMessage(e) {
+  if (!e?.body) return e?.message ? String(e.message) : String(e);
+  try {
+    return JSON.parse(e.body).error?.message ?? e.body;
+  } catch {
+    return e.body;
   }
-  return res.json();
 }
 
 // Download a (presigned) URL to destPath; returns byte length.

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

@@ -1,27 +1,47 @@
 import { test } from "node:test";
 import assert from "node:assert/strict";
-import { mkdtempSync, rmSync, writeFileSync } from "node:fs";
+import { mkdirSync, mkdtempSync, rmSync, symlinkSync, writeFileSync } from "node:fs";
+import { createServer } from "node:http";
 import { tmpdir } from "node:os";
 import { join } from "node:path";
-import { heygenAuthHeaders, heygenAuthMethod } from "./heygen.mjs";
+import {
+  heygenAuthHeaders,
+  heygenAuthMethod,
+  heygenBase,
+  heygenCredential,
+  heygenJSON,
+  loadEnvFromDir,
+} from "./heygen.mjs";
 
+const HEYGEN_ENV = [
+  "HEYGEN_ACCESS_TOKEN",
+  "HEYGEN_API_KEY",
+  "HYPERFRAMES_API_KEY",
+  "HEYGEN_CONFIG_DIR",
+  "HEYGEN_API_BASE",
+  "HEYGEN_ALLOW_HTTP",
+];
+
+// Runs fn with every HeyGen variable unset, then puts them back; an async fn restores once it settles.
 function withCleanHeygenEnv(fn) {
-  const previousApiKey = process.env.HEYGEN_API_KEY;
-  const previousHyperframesApiKey = process.env.HYPERFRAMES_API_KEY;
-  const previousConfigDir = process.env.HEYGEN_CONFIG_DIR;
+  const previous = Object.fromEntries(HEYGEN_ENV.map((name) => [name, process.env[name]]));
+  const restore = () => {
+    for (const [name, value] of Object.entries(previous)) {
+      if (value === undefined) delete process.env[name];
+      else process.env[name] = value;
+    }
+  };
+  for (const name of HEYGEN_ENV) delete process.env[name];
+  let result;
   try {
-    delete process.env.HEYGEN_API_KEY;
-    delete process.env.HYPERFRAMES_API_KEY;
-    delete process.env.HEYGEN_CONFIG_DIR;
-    return fn();
-  } finally {
-    if (previousApiKey === undefined) delete process.env.HEYGEN_API_KEY;
-    else process.env.HEYGEN_API_KEY = previousApiKey;
-    if (previousHyperframesApiKey === undefined) delete process.env.HYPERFRAMES_API_KEY;
-    else process.env.HYPERFRAMES_API_KEY = previousHyperframesApiKey;
-    if (previousConfigDir === undefined) delete process.env.HEYGEN_CONFIG_DIR;
-    else process.env.HEYGEN_CONFIG_DIR = previousConfigDir;
+    result = fn();
+  } catch (error) {
+    restore();
+    throw error;
   }
+  if (result && typeof result.then === "function") return result.finally(restore);
+  restore();
+  return result;
 }
 
 test("heygenAuthHeaders does not tag API-key requests as CLI traffic, but still carries the media-use tool tag", () => {
@@ -62,6 +82,19 @@ test("heygenAuthHeaders tags OAuth requests as CLI traffic and with the media-us
   });
 });
 
+test("a host-injected HEYGEN_ACCESS_TOKEN wins over an API key and is treated as OAuth", () => {
+  withCleanHeygenEnv(() => {
+    process.env.HEYGEN_ACCESS_TOKEN = "at_host";
+    process.env.HEYGEN_API_KEY = "hg_test";
+    assert.deepEqual(heygenAuthHeaders(), {
+      Authorization: "Bearer at_host",
+      "X-HeyGen-Source": "cli",
+      "X-HeyGen-Client-Source": "media-use",
+    });
+    assert.equal(heygenAuthMethod(), "oauth");
+  });
+});
+
 test("heygenAuthMethod returns api_key for an env API key, without tagging headers", () => {
   withCleanHeygenEnv(() => {
     process.env.HEYGEN_API_KEY = "hg_test";
@@ -101,3 +134,159 @@ test("heygenAuthMethod returns null with no credential at all", () => {
     }
   });
 });
+
+test("loadEnvFromDir skips a .env folder and loads the .env file above it", () => {
+  const root = mkdtempSync(join(tmpdir(), "heygen-env-"));
+  const project = join(root, "project");
+  mkdirSync(join(project, ".env"), { recursive: true });
+  writeFileSync(join(root, ".env"), "MEDIA_USE_ENV_DIR_TEST=from-parent\n");
+  try {
+    loadEnvFromDir(project);
+    assert.equal(process.env.MEDIA_USE_ENV_DIR_TEST, "from-parent");
+  } finally {
+    delete process.env.MEDIA_USE_ENV_DIR_TEST;
+    rmSync(root, { recursive: true, force: true });
+  }
+});
+
+test("a project's .env cannot name the HeyGen base, so a shell key never leaves for its host", () => {
+  withCleanHeygenEnv(() => {
+    const project = mkdtempSync(join(tmpdir(), "heygen-env-"));
+    writeFileSync(
+      join(project, ".env"),
+      "HEYGEN_API_BASE=https://proxy.example.com\nHEYGEN_ALLOW_HTTP=1\nMEDIA_USE_ENV_BASE_TEST=loaded\n",
+    );
+    try {
+      process.env.HEYGEN_API_KEY = "hg_shell_real";
+      loadEnvFromDir(project);
+      assert.equal(process.env.MEDIA_USE_ENV_BASE_TEST, "loaded");
+      assert.equal(process.env.HEYGEN_API_BASE, undefined);
+      assert.equal(process.env.HEYGEN_ALLOW_HTTP, undefined);
+      assert.equal(heygenBase(), "https://api.heygen.com/v3");
+    } finally {
+      delete process.env.MEDIA_USE_ENV_BASE_TEST;
+      rmSync(project, { recursive: true, force: true });
+    }
+  });
+});
+
+test("heygenAuthMethod returns null when the credentials path is a folder", () => {
+  withCleanHeygenEnv(() => {
+    const dir = mkdtempSync(join(tmpdir(), "heygen-cred-"));
+    try {
+      mkdirSync(join(dir, "credentials"));
+      process.env.HEYGEN_CONFIG_DIR = dir;
+      assert.equal(heygenAuthMethod(), null);
+    } finally {
+      rmSync(dir, { recursive: true, force: true });
+    }
+  });
+});
+
+test("heygenAuthMethod returns null when the credentials path is a symlink loop", () => {
+  withCleanHeygenEnv(() => {
+    const dir = mkdtempSync(join(tmpdir(), "heygen-cred-"));
+    try {
+      symlinkSync(join(dir, "credentials"), join(dir, "credentials"));
+      process.env.HEYGEN_CONFIG_DIR = dir;
+      assert.equal(heygenAuthMethod(), null);
+    } finally {
+      rmSync(dir, { recursive: true, force: true });
+    }
+  });
+});
+
+test("heygenAuthHeaders says to fix an unreadable credentials path, and to log in when there is none", () => {
+  withCleanHeygenEnv(() => {
+    const dir = mkdtempSync(join(tmpdir(), "heygen-cred-"));
+    try {
+      process.env.HEYGEN_CONFIG_DIR = dir;
+      assert.throws(() => heygenAuthHeaders(), /no HeyGen credentials/);
+      mkdirSync(join(dir, "credentials"));
+      assert.equal(heygenCredential(), null);
+      assert.throws(
+        () => heygenAuthHeaders(),
+        (error) =>
+          error.message.includes(join(dir, "credentials")) &&
+          /fix or remove that path/.test(error.message),
+      );
+    } finally {
+      rmSync(dir, { recursive: true, force: true });
+    }
+  });
+});
+
+test("heygenBase is HeyGen's public API unless a host names another", () => {
+  withCleanHeygenEnv(() => {
+    assert.equal(heygenBase(), "https://api.heygen.com/v3");
+    process.env.HEYGEN_API_BASE = "https://api-canary.heygen.com/";
+    assert.equal(heygenBase(), "https://api-canary.heygen.com/v3");
+  });
+});
+
+test("heygenBase refuses a plain-HTTP host unless HEYGEN_ALLOW_HTTP is set, as the heygen CLI does", () => {
+  withCleanHeygenEnv(() => {
+    process.env.HEYGEN_API_BASE = "http://127.0.0.1:4100";
+    assert.throws(() => heygenBase(), /HEYGEN_ALLOW_HTTP=1/);
+    process.env.HEYGEN_ALLOW_HTTP = "1";
+    assert.equal(heygenBase(), "http://127.0.0.1:4100/v3");
+  });
+});
+
+test("a host gateway (HEYGEN_API_BASE with its own HEYGEN_API_KEY) wins over a host OAuth token", () => {
+  withCleanHeygenEnv(() => {
+    process.env.HEYGEN_API_BASE = "http://127.0.0.1:4100";
+    process.env.HEYGEN_ALLOW_HTTP = "1";
+    process.env.HEYGEN_API_KEY = "gateway-token";
+    process.env.HEYGEN_ACCESS_TOKEN = "at_host";
+    assert.deepEqual(heygenAuthHeaders(), {
+      "X-Api-Key": "gateway-token",
+      "X-HeyGen-Client-Source": "media-use",
+    });
+    assert.equal(heygenAuthMethod(), "api_key");
+  });
+});
+
+test("heygenJSON sends its request to the host's HEYGEN_API_BASE with the host's key", async () => {
+  /** @type {{ url?: string, key?: string | string[] }} */
+  const seen = {};
+  const server = createServer((req, res) => {
+    seen.url = req.url;
+    seen.key = req.headers["x-api-key"];
+    res.writeHead(200, { "content-type": "application/json" }).end('{"data":[]}');
+  });
+  await new Promise((done) => server.listen(0, "127.0.0.1", done));
+  const { port } = /** @type {import("node:net").AddressInfo} */ (server.address());
+  try {
+    await withCleanHeygenEnv(async () => {
+      process.env.HEYGEN_API_BASE = `http://127.0.0.1:${port}`;
+      process.env.HEYGEN_ALLOW_HTTP = "1";
+      process.env.HEYGEN_API_KEY = "gateway-token";
+      const reply = await heygenJSON("/voices?limit=1", { headers: heygenAuthHeaders() });
+      assert.deepEqual(reply, { data: [] });
+    });
+    assert.equal(seen.url, "/v3/voices?limit=1");
+    assert.equal(seen.key, "gateway-token");
+  } finally {
+    server.close();
+  }
+});
+
+test("a base that isn't HeyGen's gets no stored or host OAuth credential, only a key named for it", () => {
+  withCleanHeygenEnv(() => {
+    const dir = mkdtempSync(join(tmpdir(), "heygen-cred-"));
+    try {
+      process.env.HEYGEN_CONFIG_DIR = dir;
+      writeFileSync(join(dir, "credentials"), JSON.stringify({ api_key: "hg_stored" }));
+      process.env.HEYGEN_ACCESS_TOKEN = "at_host";
+      process.env.HEYGEN_API_BASE = "https://proxy.example.com";
+      assert.equal(heygenCredential(), null);
+      assert.throws(() => heygenAuthHeaders(), /no HeyGen credentials/);
+      // HeyGen's own hosts keep every credential source.
+      process.env.HEYGEN_API_BASE = "https://api-canary.heygen.com";
+      assert.equal(heygenAuthMethod(), "oauth");
+    } finally {
+      rmSync(dir, { recursive: true, force: true });
+    }
+  });
+});

package/skills/media-use/audio/scripts/lib/main-module.mjs

@@ -0,0 +1,13 @@
+import { realpathSync } from "node:fs";
+import { pathToFileURL } from "node:url";
+
+// Node resolves symlinks in the main module's import.meta.url but argv[1] keeps the invoked
+// spelling (a symlinked skills dir, or /tmp vs /private/tmp on macOS), so compare real paths.
+export function isMainModule(importMetaUrl) {
+  if (!process.argv[1]) return false;
+  try {
+    return pathToFileURL(realpathSync(process.argv[1])).href === importMetaUrl;
+  } catch {
+    return false;
+  }
+}

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

@@ -0,0 +1,118 @@
+import { existsSync } from "node:fs";
+import { extname, join } from "node:path";
+import { AGENT_SOURCES, latestRecordFor, recordInPlace } from "../../../scripts/lib/manifest.mjs";
+import { regenerateIndex } from "../../../scripts/lib/index-gen.mjs";
+
+/**
+ * Where the engine may write `rel`: there, unless another file of this run has `taken` it or the file there is
+ * the person's (not `reusable` and not recorded as agent-made). Then the first free `name-2.ext`, with an anomaly.
+ */
+export function agentWritePath(
+  hyperframesDir,
+  rel,
+  { anomalies, taken = new Set(), reusable = () => false },
+) {
+  const free = (path) =>
+    !taken.has(path) &&
+    (!existsSync(join(hyperframesDir, path)) ||
+      reusable(path) ||
+      AGENT_SOURCES.includes(latestRecordFor(hyperframesDir, path)?.source));
+  if (free(rel)) return rel;
+  const ext = extname(rel);
+  const stem = rel.slice(0, rel.length - ext.length);
+  let n = 2;
+  while (!free(`${stem}-${n}${ext}`)) n++;
+  const path = `${stem}-${n}${ext}`;
+  const why = taken.has(rel)
+    ? "another file of this run goes there"
+    : "the file there is yours (the media manifest does not record it as made by the engine)";
+  const note = `${rel}: kept, because ${why}; writing ${path} instead (audio_meta.json has the path used)`;
+  if (!anomalies.includes(note)) anomalies.push(note);
+  return path;
+}
+
+/** Each spoken line's file, picked before lines synthesize concurrently so two never land on one free name. */
+export function voicePaths(hyperframesDir, lines, anomalies) {
+  const taken = new Set();
+  const paths = new Map();
+  for (const line of lines.filter((l) => String(l.text ?? "").trim())) {
+    const rel = agentWritePath(hyperframesDir, `assets/voice/${line.id}.wav`, { anomalies, taken });
+    taken.add(rel);
+    paths.set(String(line.id), rel);
+  }
+  return paths;
+}
+
+// A cue's source as the manifest records it, and who provided it. A source missing here records as the person's
+// file, so every rerun would write a numbered copy beside it.
+const SFX_SOURCES = {
+  openverse: { source: "search", provider: "openverse.audio" },
+  local: { source: "bundled", provider: "bundled.sfx" },
+};
+
+// The files one engine run wrote, each with how it was made, for the project's media manifest.
+export function writtenAssets({ only, lines, voices, ttsProvider, bgm, bgmFields, sfx }) {
+  const textById = new Map(lines.map((line) => [String(line.id), String(line.text ?? "").trim()]));
+  const assets = [];
+  if (only.has("tts")) {
+    for (const voice of voices) {
+      assets.push({
+        path: voice.path,
+        type: "voice",
+        source: "generated",
+        intent: textById.get(voice.id),
+        duration: voice.duration_s,
+        provider: ttsProvider,
+      });
+    }
+  }
+  if (only.has("bgm") && bgm && !bgmFields.bgm_pending) {
+    assets.push({
+      path: bgm.path,
+      type: "bgm",
+      source: bgmFields.bgm_mode === "retrieve" ? "search" : "generated",
+      intent: bgm.query,
+      duration: bgm.duration_s,
+      provider: bgmFields.bgm_provider,
+    });
+  }
+  if (only.has("sfx")) {
+    for (const cue of new Map(sfx.map((entry) => [entry.file, entry])).values()) {
+      const { source, provider } = SFX_SOURCES[cue.source];
+      assets.push({
+        path: cue.file,
+        type: "sfx",
+        source,
+        intent: cue.name,
+        duration: cue.duration_s,
+        provider,
+      });
+    }
+  }
+  return assets;
+}
+
+/** Records each asset where it lies; returns one anomaly per file left unrecorded. */
+export function recordInManifest(hyperframesDir, assets) {
+  const anomalies = [];
+  for (const { path, type, source, intent, duration, provider } of assets) {
+    try {
+      recordInPlace(hyperframesDir, {
+        type,
+        path,
+        source,
+        description: intent,
+        duration,
+        provenance: { provider: provider || "local", ...(intent && { prompt: intent }) },
+      });
+    } catch (error) {
+      anomalies.push(`${path}: not recorded in the media manifest (${error.message})`);
+    }
+  }
+  try {
+    if (anomalies.length < assets.length) regenerateIndex(hyperframesDir);
+  } catch (error) {
+    anomalies.push(`.media/index.md: not refreshed (${error.message})`);
+  }
+  return anomalies;
+}