@1agh/maude 0.42.0 → 0.44.0

package/apps/studio/footage-store.ts

@@ -0,0 +1,235 @@
+/**
+ * @file       footage-store.ts — Footage-analysis + EDL sidecar persistence
+ *             (feature-footage-analysis-director, Task 2).
+ * @scope      apps/studio/footage-store.ts
+ * @purpose    Read / write the two VERSIONED sidecars behind the footage
+ *             "director" pipeline (DDR-115 taxonomy):
+ *               • `assets/<sha8>.footage.json` — a `FootageAnalysis` (per clip)
+ *               • `<designRoot>/<slug>.edl.json` — an `Edl` (per cut)
+ *             Mirrors `photo-store.ts`'s `createX(ctx)` factory + `Bun.write`/
+ *             `Bun.file` shape. Server-side only — imports the DEPENDENCY-FREE
+ *             `footage/schema.ts`.
+ *
+ * @security   UNLIKE `/_api/photo-edit`, the `/_api/footage` route is
+ *             MAIN-ORIGIN ONLY (privileged — NOT in either canvas allowlist).
+ *             It is written by the `footage-analyst` / `footage-director` agents
+ *             over loopback, never by the untrusted canvas iframe (DDR-054), so
+ *             a `GET → 405` assertion from the canvas origin guards it
+ *             (canvas-origin-gate.test.ts). The write path is still derived from
+ *             caller-supplied params, so the DDR-088 cap stack is preserved:
+ *               1. strict sha8 / slug extraction (hex or kebab, bounded) —
+ *                  rejects `..`, `/`, `%2f`, absolute paths by construction;
+ *               2. explicit containment assert (poisoned-designRoot backstop);
+ *               3. structural `validateFootageAnalysis` / `validateEdl`;
+ *               4. body/file size cap (256 KB — generous for analysis JSON).
+ */
+
+import path from 'node:path';
+
+import type { Context } from './context.ts';
+import {
+  EDL_VERSION,
+  type Edl,
+  FOOTAGE_ANALYSIS_VERSION,
+  type FootageAnalysis,
+  validateEdl,
+  validateFootageAnalysis,
+} from './footage/schema.ts';
+
+/** Max bytes for either sidecar (read + write). Analysis JSON is small; slack. */
+export const FOOTAGE_MAX_BYTES = 256 * 1024;
+
+const SHA_RE = /^[0-9a-f]{8,64}$/;
+// A cut slug: lowercase kebab, bounded. Matches the `slug.sh` normalization
+// shape — no path segment, no dot, so `..`/`/`/absolute can never survive.
+const SLUG_RE = /^[a-z0-9][a-z0-9-]{0,80}$/;
+
+/**
+ * Extract + validate the content-address sha8 from an `asset` param, in any of
+ * the forms a caller might hold (`assets/<sha8>.<ext>`, `/assets/<sha8>.png`,
+ * `<sha8>.png`, bare `<sha8>`). The hex regex is the traversal defense.
+ * (Copied from photo-store.assetSha8 — same contract, kept local so the two
+ * stores stay independent.)
+ */
+export function assetSha8(param: string | null | undefined): string | null {
+  if (typeof param !== 'string') return null;
+  let s = param.trim();
+  if (!s) return null;
+  s = s.replace(/^\/+/, '');
+  s = s.replace(/^assets\//, '');
+  s = s.replace(/\.[A-Za-z0-9]+$/, '');
+  return SHA_RE.test(s) ? s : null;
+}
+
+/** Validate a cut slug (already-normalized kebab), or null. */
+export function edlSlug(param: string | null | undefined): string | null {
+  if (typeof param !== 'string') return null;
+  const s = param.trim();
+  return SLUG_RE.test(s) ? s : null;
+}
+
+export interface FootageStore {
+  analysisPathForSha8(sha8: string): string;
+  edlPathForSlug(slug: string): string;
+  getAnalysis(assetParam: string | null | undefined): Promise<FootageAnalysis | null>;
+  saveAnalysis(
+    assetParam: string | null | undefined,
+    analysis: unknown
+  ): Promise<
+    | { ok: true; path: string; analysis: FootageAnalysis }
+    | { ok: false; status: number; error: string }
+  >;
+  getEdl(slugParam: string | null | undefined): Promise<Edl | null>;
+  saveEdl(
+    slugParam: string | null | undefined,
+    edl: unknown
+  ): Promise<{ ok: true; path: string; edl: Edl } | { ok: false; status: number; error: string }>;
+}
+
+export function createFootageStore(ctx: Context): FootageStore {
+  const designRoot = ctx.paths.designRoot;
+  const assetsDir = path.join(designRoot, 'assets');
+
+  function analysisPathForSha8(sha8: string): string {
+    if (!SHA_RE.test(sha8)) throw new Error(`invalid sha8: ${sha8}`);
+    const abs = path.join(assetsDir, `${sha8}.footage.json`);
+    const rel = path.relative(assetsDir, abs);
+    if (rel !== `${sha8}.footage.json` || rel.startsWith('..') || path.isAbsolute(rel)) {
+      throw new Error(`footage path escaped assets/: ${abs}`);
+    }
+    return abs;
+  }
+
+  function edlPathForSlug(slug: string): string {
+    if (!SLUG_RE.test(slug)) throw new Error(`invalid slug: ${slug}`);
+    const abs = path.join(designRoot, `${slug}.edl.json`);
+    const rel = path.relative(designRoot, abs);
+    if (rel !== `${slug}.edl.json` || rel.startsWith('..') || path.isAbsolute(rel)) {
+      throw new Error(`edl path escaped designRoot: ${abs}`);
+    }
+    return abs;
+  }
+
+  async function readSidecar<T>(
+    abs: string,
+    validate: (v: unknown) => { ok: boolean }
+  ): Promise<T | null> {
+    try {
+      const file = Bun.file(abs);
+      if (!(await file.exists())) return null;
+      if (file.size > FOOTAGE_MAX_BYTES) return null;
+      const parsed = JSON.parse(await file.text());
+      return validate(parsed).ok ? (parsed as T) : null;
+    } catch {
+      return null;
+    }
+  }
+
+  async function getAnalysis(
+    assetParam: string | null | undefined
+  ): Promise<FootageAnalysis | null> {
+    const sha8 = assetSha8(assetParam);
+    if (!sha8) return null;
+    return readSidecar<FootageAnalysis>(analysisPathForSha8(sha8), validateFootageAnalysis);
+  }
+
+  async function saveAnalysis(
+    assetParam: string | null | undefined,
+    analysis: unknown
+  ): Promise<
+    | { ok: true; path: string; analysis: FootageAnalysis }
+    | { ok: false; status: number; error: string }
+  > {
+    const sha8 = assetSha8(assetParam);
+    if (!sha8) return { ok: false, status: 400, error: 'invalid or missing asset (expected sha8)' };
+
+    let serialized: string;
+    try {
+      serialized = JSON.stringify(analysis ?? {});
+    } catch {
+      return { ok: false, status: 400, error: 'body is not serializable JSON' };
+    }
+    if (Buffer.byteLength(serialized, 'utf8') > FOOTAGE_MAX_BYTES) {
+      return {
+        ok: false,
+        status: 413,
+        error: `footage analysis exceeds ${FOOTAGE_MAX_BYTES} bytes`,
+      };
+    }
+
+    const check = validateFootageAnalysis(analysis);
+    if (!check.ok) {
+      return {
+        ok: false,
+        status: 400,
+        error: `invalid FootageAnalysis: ${check.errors.join('; ')}`,
+      };
+    }
+
+    // Stamp version only; the sidecar filename (<sha8>.footage.json) is the
+    // authoritative source key. `asset` is already validated as a well-formed
+    // relative path — keep the client's value verbatim.
+    const toWrite: FootageAnalysis = {
+      ...(analysis as FootageAnalysis),
+      version: FOOTAGE_ANALYSIS_VERSION,
+    };
+
+    let abs: string;
+    try {
+      abs = analysisPathForSha8(sha8);
+    } catch (e) {
+      return { ok: false, status: 400, error: e instanceof Error ? e.message : 'bad path' };
+    }
+    try {
+      await Bun.write(abs, JSON.stringify(toWrite, null, 2));
+    } catch (e) {
+      return { ok: false, status: 500, error: e instanceof Error ? e.message : 'write failed' };
+    }
+    return { ok: true, path: path.posix.join('assets', `${sha8}.footage.json`), analysis: toWrite };
+  }
+
+  async function getEdl(slugParam: string | null | undefined): Promise<Edl | null> {
+    const slug = edlSlug(slugParam);
+    if (!slug) return null;
+    return readSidecar<Edl>(edlPathForSlug(slug), validateEdl);
+  }
+
+  async function saveEdl(
+    slugParam: string | null | undefined,
+    edl: unknown
+  ): Promise<{ ok: true; path: string; edl: Edl } | { ok: false; status: number; error: string }> {
+    const slug = edlSlug(slugParam);
+    if (!slug) return { ok: false, status: 400, error: 'invalid or missing slug (expected kebab)' };
+
+    let serialized: string;
+    try {
+      serialized = JSON.stringify(edl ?? {});
+    } catch {
+      return { ok: false, status: 400, error: 'body is not serializable JSON' };
+    }
+    if (Buffer.byteLength(serialized, 'utf8') > FOOTAGE_MAX_BYTES) {
+      return { ok: false, status: 413, error: `edl exceeds ${FOOTAGE_MAX_BYTES} bytes` };
+    }
+
+    const check = validateEdl(edl);
+    if (!check.ok) {
+      return { ok: false, status: 400, error: `invalid Edl: ${check.errors.join('; ')}` };
+    }
+
+    const toWrite: Edl = { ...(edl as Edl), version: EDL_VERSION };
+    let abs: string;
+    try {
+      abs = edlPathForSlug(slug);
+    } catch (e) {
+      return { ok: false, status: 400, error: e instanceof Error ? e.message : 'bad path' };
+    }
+    try {
+      await Bun.write(abs, JSON.stringify(toWrite, null, 2));
+    } catch (e) {
+      return { ok: false, status: 500, error: e instanceof Error ? e.message : 'write failed' };
+    }
+    return { ok: true, path: `${slug}.edl.json`, edl: toWrite };
+  }
+
+  return { analysisPathForSha8, edlPathForSlug, getAnalysis, saveAnalysis, getEdl, saveEdl };
+}

package/apps/studio/fs-watch.ts

@@ -34,6 +34,16 @@ export function createFsWatch(ctx: Context): FsWatch {
 
   function start() {
     if (watcher) return;
+    // Capture/CI opt-out (MAUDE_NO_WATCH=1): a headless render server has no
+    // interactive editor to hot-reload, so it never needs the watcher. It's a
+    // DEFENSIVE measure for long video exports — an HMR hard-reload broadcast
+    // fired mid-capture (from a concurrent write to designRoot, e.g. a peer edit
+    // or a runtime-state save NOT in the skip-list below) destroys the Playwright
+    // page's execution context. (NB: in the 2026-07-10 cinematic-cut dogfood the
+    // ACTUAL cause of the "Execution context was destroyed" crashes turned out to
+    // be renderer compositing pressure — too many full-frame mix-blend-mode /
+    // filter layers per frame — not the watcher; this guard is belt-and-braces.)
+    if (process.env.MAUDE_NO_WATCH === '1') return;
     try {
       watcher = watch(ctx.paths.designRoot, { recursive: true }, (_event, filename) => {
         if (!filename) return;

package/apps/studio/generation/adapters/elevenlabs.ts

@@ -0,0 +1,370 @@
+// generation/adapters/elevenlabs.ts — ElevenLabs audio stack via the REST API
+// (DDR-164, Phase 2). Direct BYOK: the user's own ElevenLabs key →
+// api.elevenlabs.io directly, no aggregator, no SDK (plain `fetch`). ONE key
+// covers the whole audio stack:
+//
+//   • Music   — POST /v1/music                  (prompt → mp3)
+//   • SFX     — POST /v1/sound-generation        (prompt → mp3)
+//   • TTS     — POST /v1/text-to-speech/{voice}  (text + voice_id → mp3)
+//   • Scribe  — POST /v1/speech-to-text          (audio → word-timestamps → SRT)
+//
+// The audio verbs return binary mp3 in ONE round trip → an already-`done` Job
+// (callers never branch on sync/async), localized into assets/<sha8>.mp3.
+// Scribe returns word-level timings that captions.ts turns into an SRT the EDL
+// caption track consumes.
+//
+// Security mirrors the Gemini adapter (F1/F2): the key is sent ONLY in the
+// `xi-api-key` header (never a query string → no redirect/log leak); the outbound
+// base is https + host-allowlisted before the key-bearing request; and every
+// response body is byte-capped before it is buffered (RAM-DoS guard).
+
+import { wordsToSrt } from '../captions.ts';
+import type {
+  AdapterContext,
+  GenAsset,
+  GenRequest,
+  GenResult,
+  HistoryAudioItem,
+  Job,
+  ModelDescriptor,
+  ProviderAdapter,
+  ProviderDescriptor,
+} from '../types.ts';
+
+const DEFAULT_BASE = 'https://api.elevenlabs.io';
+const API_BASE = process.env.MAUDE_ELEVENLABS_API_BASE ?? DEFAULT_BASE;
+const ALLOWED_HOST = 'api.elevenlabs.io';
+const ALLOW_CUSTOM_BASE = /^(1|true|on|yes)$/i.test(process.env.MAUDE_GEN_ALLOW_CUSTOM_BASE ?? '');
+
+// Hard ceiling on a provider response before it is buffered (F1 — the same guard
+// the Gemini adapter added). Audio is heavier than a JSON image, so the cap is
+// higher; still bounded against a wedged/hostile upstream.
+const MAX_RESPONSE_BYTES = Math.max(
+  1024 * 1024,
+  Number(process.env.MAUDE_ELEVENLABS_MAX_RESPONSE_BYTES) || 128 * 1024 * 1024
+);
+
+/** Validate the outbound base ONCE (https + fixed host allowlist), F1/F2. */
+function assertSafeBase(base: string): void {
+  let u: URL;
+  try {
+    u = new URL(base);
+  } catch {
+    throw new Error('ElevenLabs API base is not a valid URL');
+  }
+  if (u.protocol !== 'https:') throw new Error('ElevenLabs API base must be https');
+  if (u.hostname !== ALLOWED_HOST && !ALLOW_CUSTOM_BASE) {
+    throw new Error(
+      `ElevenLabs API base host ${u.hostname} is not allowlisted (set MAUDE_GEN_ALLOW_CUSTOM_BASE=1 to override)`
+    );
+  }
+}
+
+/** Read a Response body into bytes with a hard cap (F1). */
+async function readBytesCapped(res: Response, maxBytes: number): Promise<Uint8Array> {
+  const declared = Number(res.headers.get('content-length'));
+  if (Number.isFinite(declared) && declared > maxBytes) {
+    throw new Error(`ElevenLabs response too large (${declared} > ${maxBytes} bytes)`);
+  }
+  const body = res.body;
+  if (!body) return new Uint8Array(await res.arrayBuffer());
+  const reader = body.getReader();
+  const chunks: Uint8Array[] = [];
+  let total = 0;
+  for (;;) {
+    const { done, value } = await reader.read();
+    if (done) break;
+    if (value) {
+      total += value.byteLength;
+      if (total > maxBytes) {
+        await reader.cancel().catch(() => {});
+        throw new Error(`ElevenLabs response exceeded ${maxBytes} bytes`);
+      }
+      chunks.push(value);
+    }
+  }
+  return new Uint8Array(Buffer.concat(chunks));
+}
+
+/** Read a capped body as text (for the JSON STT response + error messages). */
+async function readTextCapped(res: Response, maxBytes: number): Promise<string> {
+  return new TextDecoder().decode(await readBytesCapped(res, maxBytes));
+}
+
+export const ELEVENLABS_DESCRIPTOR: ProviderDescriptor = {
+  id: 'elevenlabs',
+  label: 'ElevenLabs (audio)',
+  kind: 'cloud',
+  auth: 'api-key',
+  keychainService: 'com.maude.app.elevenlabs',
+  modalities: ['audio', 'transcription'],
+  keyUrl: 'https://elevenlabs.io/app/settings/api-keys',
+  notes:
+    'Music, sound effects, text-to-speech, and Scribe speech-to-text — one key for the whole stack, billing your own ElevenLabs account. Music carries commercial-rights tiers (check your plan) and rejects prompts naming artists, songs, or lyrics. Voice cloning requires the voice owner’s consent.',
+};
+
+export const ELEVENLABS_MODELS: ModelDescriptor[] = [
+  { id: 'eleven_music', label: 'Music', modality: 'audio', costNote: 'per second', sync: true },
+  { id: 'eleven_text_to_sound_v2', label: 'Sound effects', modality: 'audio', sync: true },
+  {
+    id: 'eleven_v3',
+    label: 'Text to speech (v3)',
+    modality: 'audio',
+    costNote: 'per character',
+    sync: true,
+  },
+  {
+    id: 'eleven_multilingual_v2',
+    label: 'Text to speech (multilingual v2)',
+    modality: 'audio',
+    sync: true,
+  },
+  { id: 'scribe_v1', label: 'Scribe (speech-to-text)', modality: 'transcription', sync: true },
+];
+
+/** Which audio verb a request wants — from params.audioKind, else inferred. */
+type AudioKind = 'music' | 'sfx' | 'tts';
+function resolveAudioKind(req: GenRequest): AudioKind {
+  const explicit = req.params?.audioKind;
+  if (explicit === 'music' || explicit === 'sfx' || explicit === 'tts') return explicit;
+  // Infer: a voice_id means speech; otherwise default to music (the flagship).
+  if (req.params?.voice_id) return 'tts';
+  return 'music';
+}
+
+const num = (v: unknown): number | undefined =>
+  typeof v === 'number' && Number.isFinite(v) ? v : undefined;
+const str = (v: unknown): string | undefined => (typeof v === 'string' && v ? v : undefined);
+
+interface ScribeWord {
+  text?: string;
+  start?: number;
+  end?: number;
+  type?: string;
+}
+interface ScribeResponse {
+  text?: string;
+  words?: ScribeWord[];
+  detail?: unknown;
+}
+interface ErrorResponse {
+  detail?: { message?: string } | string;
+}
+
+// Task 2.5 — ElevenLabs History (GET /v1/history). The user's re-downloadable
+// past generations; matching + reuse spends NO credit (already paid).
+interface HistoryItemRaw {
+  history_item_id?: string;
+  text?: string;
+  voice_id?: string;
+  date_unix?: number;
+}
+interface HistoryResponseRaw {
+  history?: HistoryItemRaw[];
+}
+
+/** Pure History-response → HistoryAudioItem[] (exported for unit test). */
+export function parseHistory(json: HistoryResponseRaw): HistoryAudioItem[] {
+  const items = Array.isArray(json?.history) ? json.history : [];
+  const out: HistoryAudioItem[] = [];
+  for (const it of items) {
+    const id = typeof it.history_item_id === 'string' ? it.history_item_id : '';
+    if (!id) continue;
+    out.push({
+      id,
+      text: typeof it.text === 'string' ? it.text : '',
+      voiceId: typeof it.voice_id === 'string' ? it.voice_id : undefined,
+      at:
+        typeof it.date_unix === 'number' && Number.isFinite(it.date_unix)
+          ? new Date(it.date_unix * 1000).toISOString()
+          : undefined,
+    });
+  }
+  return out;
+}
+
+/** A sync Job wrapper — already resolved (mirrors the Gemini adapter). */
+function doneJob(id: string, result: Promise<GenResult>): Job {
+  let settled: 'done' | 'failed' = 'done';
+  const guarded = result.catch((err) => {
+    settled = 'failed';
+    throw err;
+  });
+  return {
+    id,
+    status: () => settled,
+    async *events() {
+      try {
+        await guarded;
+        yield { status: 'done' as const };
+      } catch (err) {
+        yield {
+          status: 'failed' as const,
+          message: err instanceof Error ? err.message : String(err),
+        };
+      }
+    },
+    result: () => guarded,
+    cancel: () => {},
+  };
+}
+
+export function createElevenLabsAdapter(ctx: AdapterContext): ProviderAdapter {
+  function requireKey(): string {
+    if (!ctx.apiKey) throw new Error('no ElevenLabs key configured — add one in Settings');
+    return ctx.apiKey;
+  }
+
+  /** POST JSON, expect a binary audio body → an audio GenAsset. */
+  async function postForAudio(path: string, body: unknown): Promise<GenAsset> {
+    assertSafeBase(API_BASE);
+    const res = await fetch(`${API_BASE}${path}`, {
+      method: 'POST',
+      headers: { 'content-type': 'application/json', 'xi-api-key': requireKey() },
+      body: JSON.stringify(body),
+      signal: ctx.signal ?? AbortSignal.timeout(180_000),
+    });
+    if (!res.ok) {
+      // Error bodies are JSON; the key is never echoed in them.
+      let msg = `HTTP ${res.status}`;
+      try {
+        const j = JSON.parse(await readTextCapped(res, 64 * 1024)) as ErrorResponse;
+        const d = j.detail;
+        msg = (typeof d === 'string' ? d : d?.message) ?? msg;
+      } catch {
+        /* keep the status message */
+      }
+      throw new Error(`ElevenLabs error: ${msg}`);
+    }
+    const bytes = await readBytesCapped(res, MAX_RESPONSE_BYTES);
+    if (bytes.byteLength === 0) throw new Error('ElevenLabs returned an empty audio body');
+    return { kind: 'audio', mime: res.headers.get('content-type') || 'audio/mpeg', bytes };
+  }
+
+  async function runAudio(req: GenRequest): Promise<GenResult> {
+    const started = Date.now();
+    const kind = resolveAudioKind(req);
+    const prompt = req.prompt ?? '';
+    let asset: GenAsset;
+    if (kind === 'tts') {
+      const voiceId = str(req.params?.voice_id);
+      if (!voiceId) throw new Error('text-to-speech requires a params.voice_id');
+      const modelId = str(req.params?.model_id) ?? str(req.model) ?? 'eleven_v3';
+      asset = await postForAudio(`/v1/text-to-speech/${encodeURIComponent(voiceId)}`, {
+        text: prompt,
+        model_id: modelId,
+      });
+    } else if (kind === 'sfx') {
+      const duration = num(req.params?.durationSeconds);
+      asset = await postForAudio('/v1/sound-generation', {
+        text: prompt,
+        ...(duration ? { duration_seconds: duration } : {}),
+      });
+    } else {
+      // music
+      const ms = num(req.params?.durationSeconds);
+      asset = await postForAudio('/v1/music', {
+        prompt,
+        ...(ms ? { music_length_ms: Math.round(ms * 1000) } : {}),
+      });
+    }
+    return { assets: [asset], usage: { ms: Date.now() - started } };
+  }
+
+  async function runTranscription(req: GenRequest): Promise<GenResult> {
+    const started = Date.now();
+    if (!req.sourceAsset) throw new Error('transcription requires a sourceAsset (an audio/video)');
+    if (!ctx.readSourceAsset) throw new Error('transcription requires source-asset access');
+    const src = await ctx.readSourceAsset(req.sourceAsset);
+    if (!src) throw new Error(`source asset not found or unreadable: ${req.sourceAsset}`);
+
+    assertSafeBase(API_BASE);
+    // Multipart: the audio file + model_id. Blob keeps the bytes out of a query.
+    // Copy to a plain ArrayBuffer (a valid BlobPart; also normalizes byteOffset).
+    const buf = src.bytes.buffer.slice(
+      src.bytes.byteOffset,
+      src.bytes.byteOffset + src.bytes.byteLength
+    ) as ArrayBuffer;
+    const form = new FormData();
+    form.append('file', new Blob([buf], { type: src.mime }), 'audio');
+    form.append('model_id', str(req.model) ?? 'scribe_v1');
+    const res = await fetch(`${API_BASE}/v1/speech-to-text`, {
+      method: 'POST',
+      headers: { 'xi-api-key': requireKey() }, // FormData sets its own content-type boundary
+      body: form,
+      signal: ctx.signal ?? AbortSignal.timeout(300_000),
+    });
+    const text = await readTextCapped(res, MAX_RESPONSE_BYTES);
+    if (!res.ok) {
+      let msg = `HTTP ${res.status}`;
+      try {
+        const j = JSON.parse(text) as ErrorResponse;
+        const d = j.detail;
+        msg = (typeof d === 'string' ? d : d?.message) ?? msg;
+      } catch {
+        /* keep status */
+      }
+      throw new Error(`ElevenLabs Scribe error: ${msg}`);
+    }
+    const json = JSON.parse(text) as ScribeResponse;
+    // Scribe returns word-level entries with `type` ('word' | 'spacing'); keep words.
+    const words = (json.words ?? [])
+      .filter((w) => (w.type ?? 'word') === 'word' && typeof w.text === 'string')
+      .map((w) => ({ text: String(w.text), start: Number(w.start) || 0, end: Number(w.end) || 0 }));
+    const srt = wordsToSrt(words);
+    const asset: GenAsset = { kind: 'transcription', mime: 'application/x-subrip', text: srt };
+    return { assets: [asset], usage: { ms: Date.now() - started }, raw: { text: json.text } };
+  }
+
+  // Task 2.5 — the user's re-usable audio history. Re-downloading spends NO
+  // credit (already paid). Rate-limited LIST → the route caches the listing;
+  // the audio GET localizes through the host's saveAsset (magic-byte sniff).
+  async function listHistory(): Promise<HistoryAudioItem[]> {
+    assertSafeBase(API_BASE);
+    const res = await fetch(`${API_BASE}/v1/history?page_size=100`, {
+      headers: { 'xi-api-key': requireKey() },
+      signal: ctx.signal ?? AbortSignal.timeout(30_000),
+    });
+    const text = await readTextCapped(res, 8 * 1024 * 1024);
+    if (!res.ok) {
+      let msg = `HTTP ${res.status}`;
+      try {
+        const j = JSON.parse(text) as ErrorResponse;
+        const d = j.detail;
+        msg = (typeof d === 'string' ? d : d?.message) ?? msg;
+      } catch {
+        /* keep status */
+      }
+      throw new Error(`ElevenLabs history error: ${msg}`);
+    }
+    return parseHistory(JSON.parse(text) as HistoryResponseRaw);
+  }
+
+  async function fetchHistoryAudio(id: string): Promise<GenAsset> {
+    // The id is provider-scoped and used ONLY in a fixed, non-interpolated path
+    // segment (encodeURIComponent) — no query, no key leak.
+    assertSafeBase(API_BASE);
+    const res = await fetch(`${API_BASE}/v1/history/${encodeURIComponent(id)}/audio`, {
+      headers: { 'xi-api-key': requireKey() },
+      signal: ctx.signal ?? AbortSignal.timeout(120_000),
+    });
+    if (!res.ok) throw new Error(`ElevenLabs history audio error: HTTP ${res.status}`);
+    const bytes = await readBytesCapped(res, MAX_RESPONSE_BYTES);
+    if (bytes.byteLength === 0) throw new Error('ElevenLabs history returned an empty audio body');
+    return { kind: 'audio', mime: res.headers.get('content-type') || 'audio/mpeg', bytes };
+  }
+
+  return {
+    descriptor: ELEVENLABS_DESCRIPTOR,
+    async listModels() {
+      return ELEVENLABS_MODELS;
+    },
+    async submit(req: GenRequest): Promise<Job> {
+      const id = `gen_${crypto.randomUUID()}`;
+      const run = req.modality === 'transcription' ? runTranscription(req) : runAudio(req);
+      return doneJob(id, run);
+    },
+    listHistory,
+    fetchHistoryAudio,
+  };
+}