dsh-hyperframes 0.3.2 → 0.4.0

package/skills/media-use/scripts/lib/registry.mjs

@@ -1,218 +0,0 @@
-// Provider registry — the v2 contract.
-//
-// Each media type maps to an ORDERED list of provider entries. Providers are
-// tried in order; the first to return a non-null result wins, which keeps
-// resolution deterministic (same request -> same provider -> same file ->
-// reproducible renders). heygen-CLI is always first for the types it serves.
-//
-// An entry exposes any of three capability methods — search / generate /
-// process — plus { name }. media-use holds no keys; each external tool owns its
-// own auth. Providers, by type:
-//   - heygen CLI: catalog + TTS, first for every type it serves (OAuth free
-//     allowance first, then the user's HeyGen billing path)
-//   - mflux: local FLUX-class image gen, spec-selected to the machine's RAM
-//     (free, private, offline once cached)
-//   - codex CLI: image gen on the user's ChatGPT sub — the better-quality upsell
-//     and the fallback when no local model fits
-//   - Kokoro (via the hyperframes CLI): local voiceover, free/private fallback
-//     when HeyGen credentials are absent or --local-only is requested
-//
-// Generation is local-first, cloud-upsell. `ctx.provider` forces one provider
-// (e.g. "make an image with codex").
-
-import { bgmProvider } from "./bgm-provider.mjs";
-import { sfxProvider } from "./sfx-provider.mjs";
-import { bundledSfxProvider } from "./bundled-sfx-provider.mjs";
-import { imageProvider, iconProvider } from "./image-provider.mjs";
-import { brandProvider } from "./brand-provider.mjs";
-import {
-  svglSearch,
-  simpleIconsSearch,
-  githubAvatarSearch,
-  faviconSearch,
-} from "./logo-provider.mjs";
-import { heygenTtsGenerate } from "./voice-provider.mjs";
-import { heygenVideoGenerate } from "./heygen-video-provider.mjs";
-import { ltxVideoGenerate } from "./ltx-video-provider.mjs";
-import { localTtsGenerate } from "./tts-local-provider.mjs";
-import { codexImageGenerate } from "./codex-provider.mjs";
-import { mfluxImageGenerate } from "./mflux-provider.mjs";
-
-// Provider markers: `network` = hits a remote service (skipped by --local-only).
-// `paid` = may cost wallet credits after any OAuth/web-plan free allowance
-// (documentation for the agent's cost judgment, X4: agent-initiated paid should
-// confirm). HeyGen catalog SEARCH is free; HeyGen TTS is free for eligible
-// OAuth CLI users up to the monthly allowance, then follows the user's billing.
-const A = (name, caps) => ({ name, ...caps }); // local, free
-const N = (name, caps) => ({ name, network: true, ...caps }); // remote, free
-const P = (name, caps) => ({ name, network: true, paid: true, ...caps }); // remote, paid
-
-// heygen-CLI first. All remote providers are skipped by --local-only.
-const REGISTRY = {
-  bgm: [N("heygen.audio.sounds", { search: bgmProvider.search })],
-  sfx: [
-    N("heygen.audio.sounds", { search: sfxProvider.search }),
-    A("bundled.sfx", { search: bundledSfxProvider.search }),
-  ],
-  image: [
-    N("heygen.asset.search", { search: imageProvider.search }),
-    // Catalog miss -> generate. Local first (best FLUX-class model the machine's
-    // RAM can run, spec-selected; free, private, kept under --local-only), then
-    // the codex CLI on the user's ChatGPT sub as the better-quality upsell and
-    // the fallback when no local model fits.
-    A("mflux.local", { generate: mfluxImageGenerate }),
-    N("codex.image_gen", { generate: codexImageGenerate }),
-  ],
-  icon: [N("heygen.asset.search", { search: iconProvider.search })],
-  logo: [
-    // Official brand marks. Tiers verified by a 54-brand stress test (100%
-    // cascade hit); HeyGen asset search is deliberately absent — it returns
-    // generic look-alike icons for brand queries. All free, all network →
-    // --local-only leaves only the cache rungs.
-    N("svgl", { search: svglSearch }),
-    N("simple-icons", { search: simpleIconsSearch }),
-    N("github.avatar", { search: githubAvatarSearch }),
-    N("favicon.ddg", { search: faviconSearch }),
-  ],
-  voice: [
-    // HeyGen TTS first when credentialed so CLI/OAuth users consume the free
-    // web-plan allowance (10 min/month) before any paid path. --local-only skips
-    // it and keeps Kokoro as the private/offline fallback.
-    // Deliberately kept `paid` (X4 confirm-before-call) even though the first
-    // 10 min/month are free: the client can't know the remaining allowance, so
-    // confirming is safer than risking a silent charge once it's spent. (A
-    // tri-state "quota-first, paid after" would need backend quota state.)
-    P("heygen.tts", { generate: heygenTtsGenerate }),
-    A("kokoro.local", { generate: localTtsGenerate }),
-  ],
-  video: [
-    // HeyGen avatar video first when credentialed; --local-only skips it and
-    // keeps LTX as the local fallback.
-    P("heygen.video", { generate: heygenVideoGenerate }),
-    A("ltx.local", { generate: ltxVideoGenerate }),
-  ],
-  brand: [
-    // Local design spec, not heygen — reads frame.md / design.md tokens.
-    A("design_spec", { search: brandProvider.search }),
-  ],
-  grade: [
-    // Local deterministic cascade handled by resolve.mjs so grade records can
-    // carry an inline block as well as an optional frozen .cube file.
-    A("color_grade.local", { search: async () => null, generate: async () => null }),
-  ],
-  lut: [
-    // Lower-level local LUT generation/freezing path handled by resolve.mjs.
-    A("cube_lut.local", { search: async () => null, generate: async () => null }),
-  ],
-};
-
-function listFor(type) {
-  const list = REGISTRY[type];
-  if (!list) throw new Error(`unknown media type: ${type}`);
-  return list;
-}
-
-/** Ordered providers for a type. */
-export function getProviders(type) {
-  return listFor(type);
-}
-
-/** All declared media types. */
-export function listTypes() {
-  return Object.keys(REGISTRY);
-}
-
-/** Provider names available for a type, in cascade order (for --provider validation). */
-export function providerNamesFor(type) {
-  return listFor(type).map((p) => p.name);
-}
-
-/**
- * name -> cost tier ("local" | "network_free" | "network_paid") over a collection
- * of ordered provider lists, i.e. the A / N / P distinction the constructors above
- * already declare. Exported so the conflict rule below is testable against a
- * fixture; production reads the REGISTRY-wide index built from it.
- *
- * A name declared under two media types must carry the same tier in both. If it
- * didn't, "did this resolve cost credit" would depend on which type happened to
- * serve it, and the telemetry property would mean nothing — so this throws at
- * import rather than silently picking one.
- */
-export function buildProviderTierIndex(providerLists) {
-  const tiers = new Map();
-  for (const list of providerLists) {
-    for (const p of list) {
-      const tier = p.paid ? "network_paid" : p.network ? "network_free" : "local";
-      const prior = tiers.get(p.name);
-      if (prior && prior !== tier)
-        throw new Error(
-          `provider "${p.name}" is declared ${prior} under one media type and ${tier} under another`,
-        );
-      tiers.set(p.name, tier);
-    }
-  }
-  return tiers;
-}
-
-const PROVIDER_TIERS = buildProviderTierIndex(Object.values(REGISTRY));
-
-/**
- * Cost tier of a provider by name, or undefined for a name the registry doesn't
- * declare. The registry stays the single owner of "does this cost credit", so
- * dashboards and callers never re-derive it from provider-name string matching.
- */
-export function providerTierFor(name) {
-  return PROVIDER_TIERS.get(name);
-}
-
-/**
- * Does an override token (full name like "codex.image_gen" or a prefix like
- * "codex") match any provider declared for the type? Same match rule as
- * runProviders, so validation and dispatch never disagree.
- */
-export function providerMatches(type, want) {
-  return providerNamesFor(type).some((n) => n === want || n.startsWith(`${want}.`));
-}
-
-/**
- * Back-compat shim for the v1 single-provider API. Returns the first declared
- * provider for the type (tagged with `type`); throws for an unknown type.
- * Kept for v1 callers only — new code should use getProviders/runCapability.
- */
-export function getProvider(type) {
-  const first = listFor(type)[0] || {};
-  return { ...first, type };
-}
-
-/**
- * Run a capability across an explicit ordered provider list. Tries each in
- * order, returns the first non-null result, skips providers that don't expose
- * the capability. Pure over its input — the unit-testable core of the cascade.
- *
- * Offline guard: a `network` provider is skipped when `ctx.localOnly` is set —
- * unconditionally, even under a `ctx.provider` override. --local-only is a hard
- * safety flag: it must never make a network call. Forcing a network provider
- * while offline yields a clean miss (the caller explains the conflict), never a
- * silent network request.
- * Provider override: `ctx.provider` (a full name like "codex.image_gen" or a
- * prefix like "codex") pins resolution to matching providers only — this is how
- * a user "make an image WITH codex" forces the upsell instead of taking the
- * free-first default.
- */
-export async function runProviders(providers, capability, intent, ctx) {
-  const want = ctx?.provider;
-  for (const p of providers) {
-    if (want && p.name !== want && !p.name.startsWith(`${want}.`)) continue;
-    if (p.network && ctx?.localOnly) continue; // --local-only wins, even over --provider
-    const fn = p[capability];
-    if (typeof fn !== "function") continue;
-    const res = await fn(intent, ctx);
-    if (res) return res;
-  }
-  return null;
-}
-
-/** Run a capability over the providers for a type (deterministic, heygen-first). */
-export async function runCapability(type, capability, intent, ctx) {
-  return runProviders(getProviders(type), capability, intent, ctx);
-}

package/skills/media-use/scripts/lib/registry.test.mjs

@@ -1,261 +0,0 @@
-import { strict as assert } from "node:assert";
-import { test } from "node:test";
-import {
-  getProviders,
-  getProvider,
-  listTypes,
-  providerMatches,
-  providerNamesFor,
-  runProviders,
-  runCapability,
-  providerTierFor,
-  buildProviderTierIndex,
-} from "./registry.mjs";
-
-// --- registry shape -------------------------------------------------------
-
-test("listTypes exposes the v2 media types", () => {
-  const types = listTypes();
-  for (const t of [
-    "bgm",
-    "sfx",
-    "image",
-    "icon",
-    "logo",
-    "voice",
-    "video",
-    "brand",
-    "grade",
-    "lut",
-  ]) {
-    assert.ok(types.includes(t), `missing type: ${t}`);
-  }
-});
-
-test("heygen provider is first for every type it serves", () => {
-  for (const t of ["bgm", "sfx", "image", "icon"]) {
-    const first = getProviders(t)[0];
-    assert.ok(first, `no enabled provider for ${t}`);
-    assert.match(first.name, /^heygen/, `${t} first provider is ${first.name}`);
-  }
-});
-
-test("sanctioned providers only: heygen, local mflux/kokoro/ltx, codex, design spec, logo tiers", () => {
-  const allowed =
-    /^heygen|^bundled\.sfx$|^mflux\.local$|^kokoro\.local$|^ltx\.local$|^codex\.image_gen$|^design_spec$|^svgl$|^simple-icons$|^github\.avatar$|^favicon\.ddg$|^color_grade\.local$|^cube_lut\.local$/;
-  for (const t of listTypes()) {
-    for (const p of getProviders(t)) {
-      assert.ok(allowed.test(p.name), `${t} lists unsanctioned provider: ${p.name}`);
-    }
-  }
-});
-
-test("image cascade: heygen catalog, then local mflux, then the codex upsell", () => {
-  const ps = getProviders("image");
-  assert.match(ps[0].name, /^heygen/, "heygen catalog first");
-  const names = ps.map((p) => p.name);
-  const mflux = ps.find((p) => p.name === "mflux.local");
-  const codex = ps.find((p) => p.name === "codex.image_gen");
-  assert.ok(mflux && typeof mflux.generate === "function", "local mflux registered");
-  assert.ok(codex && typeof codex.generate === "function", "codex upsell registered");
-  assert.ok(names.indexOf("mflux.local") < names.indexOf("codex.image_gen"), "local before codex");
-  assert.ok(!mflux.network, "local mflux is kept under --local-only");
-  assert.ok(codex.network, "codex is network (skipped under --local-only)");
-});
-
-test("voice cascade: HeyGen TTS first, Kokoro remains the local fallback", () => {
-  const ps = getProviders("voice");
-  assert.equal(ps[0].name, "heygen.tts", "HeyGen TTS is first when credentials exist");
-  assert.ok(ps[0].network, "HeyGen TTS is network (skipped under --local-only)");
-  assert.ok(ps[0].paid, "HeyGen TTS may bill after the OAuth free allowance");
-  assert.equal(ps[1].name, "kokoro.local", "local Kokoro is the offline fallback");
-  assert.ok(!ps[1].network, "local Kokoro kept under --local-only");
-  assert.ok(!ps[1].paid, "local Kokoro is free");
-});
-
-test("video cascade: HeyGen first, LTX local fallback, generate-only", async () => {
-  assert.deepEqual(providerNamesFor("video"), ["heygen.video", "ltx.local"]);
-  assert.equal(providerMatches("video", "ltx.local"), true);
-
-  const ps = getProviders("video");
-  assert.ok(ps[0].network, "HeyGen video is network (skipped under --local-only)");
-  assert.ok(ps[0].paid, "HeyGen video may bill after the OAuth free allowance");
-  assert.ok(!ps[1].network, "local LTX is kept under --local-only");
-  assert.equal(await runCapability("video", "search", "x", {}), null);
-});
-
-test("sfx cascade: HeyGen catalog first, bundled library remains the local fallback", () => {
-  const ps = getProviders("sfx");
-  assert.equal(ps[0].name, "heygen.audio.sounds");
-  assert.ok(ps[0].network, "HeyGen SFX catalog is network-only");
-  assert.equal(ps[1].name, "bundled.sfx");
-  assert.equal(typeof ps[1].search, "function");
-  assert.ok(!ps[1].network, "bundled SFX remain available offline");
-});
-
-test("ctx.provider forces one generator (e.g. 'make an image WITH codex')", async () => {
-  const providers = [
-    { name: "heygen.asset.search", network: true, search: async () => null },
-    { name: "mflux.local", generate: async () => ({ hit: "local" }) },
-    { name: "codex.image_gen", network: true, generate: async () => ({ hit: "codex" }) },
-  ];
-  // no override: local wins (first generate to return non-null)
-  assert.deepEqual(await runProviders(providers, "generate", "x", {}), { hit: "local" });
-  // override to codex: skip local, use codex even though local would have worked
-  assert.deepEqual(await runProviders(providers, "generate", "x", { provider: "codex" }), {
-    hit: "codex",
-  });
-  // override matches the full name too
-  assert.deepEqual(
-    await runProviders(providers, "generate", "x", { provider: "codex.image_gen" }),
-    { hit: "codex" },
-  );
-  // --local-only wins even over a forced network provider: no network call,
-  // clean miss (the caller surfaces the conflict). A forced LOCAL provider under
-  // --local-only still runs.
-  assert.equal(
-    await runProviders(providers, "generate", "x", { provider: "codex", localOnly: true }),
-    null,
-  );
-  assert.deepEqual(
-    await runProviders(providers, "generate", "x", { provider: "mflux", localOnly: true }),
-    { hit: "local" },
-  );
-});
-
-test("getProvider returns the first provider with its type, throws for unknown", () => {
-  const p = getProvider("bgm");
-  assert.equal(p.type, "bgm");
-  assert.equal(typeof p.search, "function");
-  assert.throws(() => getProvider("unknown_type"), /unknown media type/);
-});
-
-test("getProviders throws for unknown type", () => {
-  assert.throws(() => getProviders("nope"), /unknown media type/);
-});
-
-// --- deterministic capability execution (runProviders core) ---------------
-
-test("runProviders calls providers in order and returns the first non-null", async () => {
-  const calls = [];
-  const providers = [
-    {
-      name: "a",
-      enabled: true,
-      search: async () => {
-        calls.push("a");
-        return null;
-      },
-    },
-    {
-      name: "b",
-      enabled: true,
-      search: async () => {
-        calls.push("b");
-        return { hit: "b" };
-      },
-    },
-    {
-      name: "c",
-      enabled: true,
-      search: async () => {
-        calls.push("c");
-        return { hit: "c" };
-      },
-    },
-  ];
-  const res = await runProviders(providers, "search", "x", {});
-  assert.deepEqual(res, { hit: "b" });
-  assert.deepEqual(calls, ["a", "b"], "must stop at first non-null, never call c");
-});
-
-test("runProviders skips providers missing the requested capability", async () => {
-  const providers = [
-    { name: "a", enabled: true /* no search */ },
-    { name: "b", enabled: true, search: async () => ({ hit: "b" }) },
-  ];
-  const res = await runProviders(providers, "search", "x", {});
-  assert.deepEqual(res, { hit: "b" });
-});
-
-test("runProviders returns null when no provider yields a result", async () => {
-  const providers = [{ name: "a", enabled: true, search: async () => null }];
-  assert.equal(await runProviders(providers, "search", "x", {}), null);
-});
-
-test("runCapability('bgm','process') is null — process slot is graceful when unfilled", async () => {
-  assert.equal(await runCapability("bgm", "process", "x", {}), null);
-});
-
-// --- provider cost tier (telemetry) ---------------------------------------
-
-test("providerTierFor reports the registry's own A/N/P declaration", () => {
-  assert.equal(providerTierFor("heygen.tts"), "network_paid");
-  assert.equal(providerTierFor("heygen.video"), "network_paid");
-  assert.equal(providerTierFor("heygen.audio.sounds"), "network_free");
-  assert.equal(providerTierFor("heygen.asset.search"), "network_free");
-  assert.equal(providerTierFor("codex.image_gen"), "network_free");
-  assert.equal(providerTierFor("bundled.sfx"), "local");
-  assert.equal(providerTierFor("kokoro.local"), "local");
-});
-
-test("providerTierFor agrees across every type that declares the same name", () => {
-  // heygen.audio.sounds serves both bgm and sfx; heygen.asset.search serves both
-  // image and icon. A name whose tier depended on the media type would make the
-  // telemetry property meaningless.
-  const byName = new Map();
-  for (const type of listTypes()) {
-    for (const name of providerNamesFor(type)) {
-      const tier = providerTierFor(name);
-      assert.ok(tier, `every declared provider has a tier (${type}/${name})`);
-      const prior = byName.get(name);
-      if (prior) assert.equal(tier, prior, `${name} must carry one tier across types`);
-      byName.set(name, tier);
-    }
-  }
-});
-
-test("providerTierFor returns undefined for a name the registry does not declare", () => {
-  assert.equal(providerTierFor("does.not.exist"), undefined);
-  assert.equal(providerTierFor(undefined), undefined);
-  assert.equal(providerTierFor(null), undefined);
-  assert.equal(providerTierFor(""), undefined);
-});
-
-test("buildProviderTierIndex throws when one name carries two tiers", () => {
-  assert.throws(
-    () =>
-      buildProviderTierIndex([
-        [{ name: "dual", network: true }],
-        [{ name: "dual", network: true, paid: true }],
-      ]),
-    /declared network_free under one media type and network_paid under another/,
-  );
-});
-
-test("buildProviderTierIndex accepts the same name repeated at the same tier", () => {
-  const index = buildProviderTierIndex([
-    [{ name: "same", network: true }],
-    [{ name: "same", network: true }],
-  ]);
-  assert.equal(index.get("same"), "network_free");
-});
-
-test("--local-only skips every network provider (even free remote ones)", async () => {
-  let remoteRan = false;
-  const providers = [
-    {
-      name: "heygen",
-      network: true,
-      search: async () => {
-        remoteRan = true;
-        return { hit: "net" };
-      },
-    },
-    { name: "local", search: async () => ({ hit: "local" }) },
-  ];
-  assert.deepEqual(await runProviders(providers, "search", "x", { localOnly: true }), {
-    hit: "local",
-  });
-  assert.equal(remoteRan, false, "the remote provider must not be called offline");
-});

package/skills/media-use/scripts/lib/search.mjs

@@ -1,24 +0,0 @@
-// Paginated text search over a manifest (project or global) by id / description
-// / entity. Plain substring match — no vector DB (B4): the agent's own file
-// search covers semantics; this just keeps result pages small enough to not
-// blow the context window.
-
-const PAGE = 10;
-
-export function searchRecords(records, query, { page = 1, pageSize = PAGE } = {}) {
-  const q = String(query || "")
-    .trim()
-    .toLowerCase();
-  const matched = q
-    ? records.filter((r) =>
-        [r.id, r.description, r.entity, r.type].some(
-          (f) => f && String(f).toLowerCase().includes(q),
-        ),
-      )
-    : records.slice();
-  const total = matched.length;
-  const pages = Math.max(1, Math.ceil(total / pageSize));
-  const p = Math.min(Math.max(1, page), pages);
-  const start = (p - 1) * pageSize;
-  return { results: matched.slice(start, start + pageSize), total, page: p, pages, pageSize };
-}

package/skills/media-use/scripts/lib/search.test.mjs

@@ -1,32 +0,0 @@
-import { strict as assert } from "node:assert";
-import { test } from "node:test";
-import { searchRecords } from "./search.mjs";
-
-const recs = Array.from({ length: 23 }, (_, i) => ({
-  id: `bgm_${i}`,
-  type: i % 2 ? "bgm" : "sfx",
-  description: i === 5 ? "energetic tech whoosh" : `track ${i}`,
-}));
-
-test("matches id / description / type, case-insensitively", () => {
-  assert.equal(searchRecords(recs, "ENERGETIC").results.length, 1);
-  assert.equal(searchRecords(recs, "energetic").results[0].id, "bgm_5");
-  assert.ok(searchRecords(recs, "sfx").total > 0);
-});
-
-test("caps page size and reports pagination", () => {
-  const r = searchRecords(recs, "", { pageSize: 10 });
-  assert.equal(r.results.length, 10, "never returns more than a page");
-  assert.equal(r.total, 23);
-  assert.equal(r.pages, 3);
-  assert.equal(r.page, 1);
-});
-
-test("page navigation returns the right slice, clamps out-of-range", () => {
-  assert.equal(searchRecords(recs, "", { page: 3, pageSize: 10 }).results.length, 3);
-  assert.equal(searchRecords(recs, "", { page: 99, pageSize: 10 }).page, 3, "clamped to last page");
-});
-
-test("empty query returns everything (paginated)", () => {
-  assert.equal(searchRecords(recs, "").total, 23);
-});

package/skills/media-use/scripts/lib/sfx-provider.mjs

@@ -1,23 +0,0 @@
-import { heygenSearch } from "./heygen-search.mjs";
-
-export const sfxProvider = {
-  async search(intent) {
-    const results = heygenSearch("audio sounds list", intent, {
-      type: "sound_effects",
-      minScore: 0.4,
-    });
-    if (!results) return null;
-    const best = results[0];
-    return {
-      url: best.audio_url,
-      source: "search",
-      // ext derived from audio_url by resolve.mjs — catalog SFX are .mp3 or .wav
-      metadata: {
-        description: best.description || best.name || intent,
-        duration: best.duration || null,
-        provider: "heygen.audio.sounds",
-        provenance: { track_id: best.id, score: best.score, query: intent },
-      },
-    };
-  },
-};