@athanlab/mcp 0.0.0-stage → 0.1.0

package/dist/script.js

@@ -0,0 +1,869 @@
+/**
+ * athanlab_speak_script's engine: many lines → one file per line, a
+ * manifest.json on ONE timeline, and optionally combined.wav.
+ *
+ *   0. Lock: one run per script folder at a time (src/lock.ts); a second run
+ *      on the same folder is refused with script_running.
+ *   1. Plan: a line whose file AND matching manifest entry exist is skipped;
+ *      a line with a job_id in the manifest is resumed (polled, downloaded —
+ *      never paid again); everything else is created. Each resumed job is
+ *      read first: one that is gone, failed, or past its 30-day audio
+ *      retention is planned as a new line, so it is capped, quoted and
+ *      confirm-gated like one. The run phase never creates a job for a line
+ *      it only follows.
+ *   2. Quote: a dry run per new line (free), summed; what each line costs is
+ *      cached for the confirm: true call, the balance never is. GET /usage
+ *      gives the balance as it is now, and refuses a read-only key or an
+ *      exhausted key budget before anything is asked of the user. Above the
+ *      confirmation threshold (2,000 characters or more than 20 lines) the
+ *      call stops here and returns the quote unless confirm is true.
+ *   3. Run: the same /usage read sets the pool size (free slots of
+ *      max_concurrent_jobs, at least 1); each line is its own job with its
+ *      own Idempotency-Key, written to the manifest BEFORE the POST — so even
+ *      a crash between the POST and its answer resumes with the same key and
+ *      is never charged twice. A stop error (plan, balance, key budget, auth…) stops new jobs;
+ *      lines already running finish.
+ *   4. Finish: durations (exact, from the WAV header, for WAV), the timeline
+ *      (gaps.sentence within a speaker, gaps.turn at a speaker change), the
+ *      manifest, and combined.wav when asked and every line succeeded.
+ *
+ * When the API documents POST /speech/batch, new lines are created through
+ * one batch instead (src/batch.ts); everything else is the same.
+ */
+import { createHash } from 'node:crypto';
+import { readFile } from 'node:fs/promises';
+import path from 'node:path';
+import { ACCOUNT_STOP_CODES, AthanLabError, LINE_ERROR_CODES, isRecord, toAthanLabError } from './api/errors.js';
+import { ensureDir, exists, resolveInside, sanitizeDirname, sanitizeFilename, writeFileAtomic } from './files.js';
+import { acquireScriptLock } from './lock.js';
+import { JOB_ID_PATTERN, TEXT_MAX_CHARACTERS, createSpeechJob, downloadJobAudio, getJob, jobOutcomeError, quoteSpeech, timingOf, waitForJob, } from './speech.js';
+import { DEFAULT_GAPS, layoutTimeline, roundMs } from './timeline.js';
+import { combineWavFiles, readWavInfo } from './wav.js';
+import { VERSION } from './version.js';
+export const CONFIRM_CHARACTERS_THRESHOLD = 2000;
+export const CONFIRM_LINES_THRESHOLD = 20;
+export const MAX_SCRIPT_LINES = 200;
+export const DEFAULT_SCRIPT_TIMEOUT_SECONDS = 900;
+const MAX_DOWNLOADS_AT_ONCE = 4;
+const QUOTE_CONCURRENCY = 3;
+const PROBE_CONCURRENCY = 4;
+const QUOTE_CACHE_TTL_MS = 30 * 60 * 1000;
+const MAX_JOB_ATTEMPTS = 2;
+export const MANIFEST_FILE = 'manifest.json';
+export const COMBINED_FILE = 'combined.wav';
+/** A succeeded job whose audio can still be downloaded (the API sends audio: null once it is deleted). */
+function audioAvailable(job, nowMs) {
+    if (!job.audio)
+        return false;
+    const expires = Date.parse(job.audio.expires_at);
+    return !Number.isFinite(expires) || expires > nowMs;
+}
+function sha256(value) {
+    return createHash('sha256').update(value).digest('hex');
+}
+function emptyToNull(value) {
+    const trimmed = value?.trim();
+    return trimmed ? trimmed : null;
+}
+function padWidth(count) {
+    return Math.max(3, String(count).length);
+}
+/**
+ * `NNN-label.ext`. The label's path separators become '-' BEFORE the position
+ * prefix is added: sanitizeFilename keeps only a name's last path segment, so
+ * "001-Mom/Dad" would lose its prefix and every "Mom/Dad" line would share
+ * "Dad.wav". With the prefix always intact, no two lines share a file.
+ */
+export function lineFileName(index, label, count, ext) {
+    const prefix = String(index + 1).padStart(padWidth(count), '0');
+    const clean = label ? label.replace(/[\\/]+/g, '-') : '';
+    return sanitizeFilename(clean ? `${prefix}-${clean}` : prefix, ext, prefix);
+}
+async function loadManifest(file, ctx) {
+    try {
+        const parsed = JSON.parse(await readFile(file, 'utf8'));
+        if (isRecord(parsed) && parsed.version === 1 && Array.isArray(parsed.lines))
+            return parsed;
+        ctx.logger.warn('ignoring an unreadable manifest.json', { file });
+    }
+    catch (err) {
+        if (err.code !== 'ENOENT')
+            ctx.logger.warn('ignoring an unreadable manifest.json', { file });
+    }
+    return null;
+}
+/** Pool of `size` workers over `items`; stops taking new items once `shouldStop()` is true. */
+async function pool(items, size, shouldStop, work) {
+    let next = 0;
+    const workers = Array.from({ length: Math.max(1, Math.min(size, items.length)) }, async () => {
+        while (!shouldStop() && next < items.length) {
+            const item = items[next++];
+            await work(item);
+        }
+    });
+    await Promise.all(workers);
+}
+class Semaphore {
+    limit;
+    active = 0;
+    waiting = [];
+    constructor(limit) {
+        this.limit = limit;
+    }
+    async run(fn) {
+        if (this.active >= this.limit)
+            await new Promise(resolve => this.waiting.push(resolve));
+        this.active++;
+        try {
+            return await fn();
+        }
+        finally {
+            this.active--;
+            this.waiting.shift()?.();
+        }
+    }
+}
+function isStringRecord(value) {
+    return isRecord(value) && Object.values(value).every(v => typeof v === 'string');
+}
+/** Does this job carry this line's request? (A job resource has no text: its length, voice, format and number mode.) */
+function jobMatchesLine(job, entry, format) {
+    const input = job.input;
+    return !!input
+        && input.characters === entry.characters
+        && input.output_format === format
+        && (input.number_mode ?? 'smart') === (entry.number_mode ?? 'smart')
+        && (entry.requested_voice_id === null || input.voice_id === entry.requested_voice_id);
+}
+function lineMetadata(scriptDir, entry) {
+    const metadata = {
+        client: 'athanlab-mcp',
+        script: scriptDir.slice(0, 500),
+        line_index: String(entry.index),
+    };
+    if (entry.id)
+        metadata.line_id = entry.id.slice(0, 500);
+    return metadata;
+}
+/**
+ * The same audio: text, voice and number mode. The file name is not part of
+ * it — a renamed line (new id, or a name from an older version of this
+ * server) keeps its job and is downloaded again under the new name, free.
+ */
+function sameRequest(previous, next) {
+    return !!previous
+        && previous.text === next.text
+        && (previous.requested_voice_id ?? null) === next.requested_voice_id
+        && (previous.number_mode ?? null) === next.number_mode;
+}
+export async function runScript(ctx, input, opts = {}) {
+    ctx.client.assertKey();
+    const { lines } = input;
+    if (lines.length === 0 || lines.length > MAX_SCRIPT_LINES) {
+        throw AthanLabError.client('invalid_input', `A script has 1–${MAX_SCRIPT_LINES} lines; this one has ${lines.length}.`, { param: 'lines' });
+    }
+    if (input.combine && input.output_format !== 'wav') {
+        throw AthanLabError.client('invalid_input', 'combine: true needs output_format "wav" (lines are joined as PCM). Use wav, or combine the MP3 files yourself from manifest.json.', { param: 'combine' });
+    }
+    lines.forEach((line, index) => {
+        if (!line.text.trim())
+            throw AthanLabError.client('invalid_input', `Line ${index} has no text.`, { param: `lines.${index}.text` });
+        if (line.text.length > TEXT_MAX_CHARACTERS) {
+            throw AthanLabError.client('text_too_long', `Line ${index} is ${line.text.length} characters; a line takes at most ${TEXT_MAX_CHARACTERS}. Split it at sentence ends (။ ! ?).`, { param: `lines.${index}.text` });
+        }
+    });
+    const gaps = {
+        sentence: input.gaps?.sentence ?? DEFAULT_GAPS.sentence,
+        turn: input.gaps?.turn ?? DEFAULT_GAPS.turn,
+    };
+    const format = input.output_format;
+    const numberMode = input.number_mode ?? null;
+    // A voices map is a casting decision: a speaker it does not name (a typo, a
+    // trailing space) would otherwise be voiced — and charged — in the default
+    // voice. Own properties only, so a speaker called 'constructor' is just a name.
+    const voicesMap = input.voices ?? null;
+    const castVoice = (speaker) => voicesMap && Object.hasOwn(voicesMap, speaker) ? emptyToNull(voicesMap[speaker]) : null;
+    if (voicesMap && Object.keys(voicesMap).length > 0) {
+        const uncast = [...new Set(lines
+                .filter(line => !emptyToNull(line.voice_id) && emptyToNull(line.speaker) && !Object.hasOwn(voicesMap, emptyToNull(line.speaker)))
+                .map(line => emptyToNull(line.speaker)))];
+        if (uncast.length) {
+            throw AthanLabError.client('invalid_input', `These speakers have no entry in voices and no voice_id: ${uncast.map(s => JSON.stringify(s)).join(', ')}. Add them to voices (names must match exactly) or give those lines a voice_id. Nothing was sent.`, { param: 'voices' });
+        }
+    }
+    const drafts = lines.map((line, index) => {
+        const id = emptyToNull(line.id);
+        const speaker = emptyToNull(line.speaker);
+        const requested = emptyToNull(line.voice_id) ?? (speaker ? castVoice(speaker) : null);
+        return {
+            index,
+            id,
+            speaker,
+            voice_id: requested,
+            requested_voice_id: requested,
+            number_mode: numberMode,
+            text: line.text,
+            file: lineFileName(index, id ?? speaker, lines.length, format),
+            status: 'pending',
+            job_id: null,
+            idempotency_key: null,
+            request_metadata: null,
+            attempts: 0,
+            characters: line.text.length,
+            characters_charged: null,
+            duration_seconds: null,
+            start_seconds: null,
+            end_seconds: null,
+            speech_start_seconds: null,
+            speech_end_seconds: null,
+            error: null,
+        };
+    });
+    if (new Set(drafts.map(d => d.file)).size !== drafts.length) {
+        // Unreachable while every name starts with its line's position; a guard, because two lines on one file would silently overwrite paid audio.
+        throw AthanLabError.client('internal_client_error', 'Two script lines would be written to the same file, so nothing was sent. Please report this.');
+    }
+    const scriptId = sha256(JSON.stringify({
+        format,
+        numberMode,
+        lines: drafts.map(d => [d.id, d.speaker, d.requested_voice_id, d.text]),
+    })).slice(0, 12);
+    const subdir = input.out_subdir ? sanitizeDirname(input.out_subdir, `script-${scriptId}`) : `script-${scriptId}`;
+    const dir = resolveInside(ctx.config.outputDir, subdir);
+    // One run per folder: a second one would plan and pay for the same lines again.
+    await ensureDir(ctx.config.outputDir);
+    const lock = await acquireScriptLock(dir, resolveInside(ctx.config.outputDir, `.${subdir}.lock`));
+    try {
+        return await runLocked(ctx, input, opts, { drafts, gaps, format, numberMode, scriptId, subdir, dir });
+    }
+    finally {
+        await lock.release();
+    }
+}
+async function runLocked(ctx, input, opts, base) {
+    const { drafts, gaps, format, numberMode, scriptId, subdir, dir } = base;
+    const manifestPath = path.join(dir, MANIFEST_FILE);
+    const previous = await loadManifest(manifestPath, ctx);
+    const previousByIndex = new Map((previous?.lines ?? []).map(line => [line.index, line]));
+    const formatUnchanged = previous?.output_format === format;
+    // ── 1. Plan ──
+    const planned = [];
+    for (const draft of drafts) {
+        const old = formatUnchanged ? previousByIndex.get(draft.index) : undefined;
+        let entry = draft;
+        let action = 'create';
+        const carried = sameRequest(old, draft);
+        if (carried) {
+            entry = { ...draft, ...old, index: draft.index, id: draft.id, speaker: draft.speaker, file: draft.file, error: null };
+            if (old.status === 'succeeded' && old.file === draft.file && await exists(path.join(dir, draft.file))) {
+                action = 'skip';
+            }
+            else if (old.job_id && (old.status === 'processing' || old.status === 'succeeded')) {
+                action = 'resume';
+            }
+            else if (old.status === 'pending' && old.idempotency_key) {
+                // A POST may have landed without its answer: same key → the same job,
+                // never a second charge — provided the body is the very same, so the
+                // metadata it was first sent with (older manifests: rebuilt from that
+                // run's line id), even if the line has been renamed since.
+                action = 'create';
+                entry.request_metadata = isStringRecord(old.request_metadata) ? old.request_metadata : lineMetadata(subdir, old);
+            }
+            else {
+                entry = { ...entry, status: 'pending', job_id: null, idempotency_key: null, request_metadata: null, error: null };
+            }
+        }
+        planned.push({
+            entry,
+            action,
+            carried,
+            input: {
+                text: entry.text,
+                voice_id: entry.requested_voice_id ?? undefined,
+                output_format: format,
+                number_mode: numberMode ?? undefined,
+                metadata: action === 'create' && entry.idempotency_key && entry.request_metadata ? entry.request_metadata : lineMetadata(subdir, entry),
+            },
+        });
+    }
+    /** A new job for this line: no job, no key, metadata from the line as it is now. */
+    const resetForNewJob = (p) => {
+        Object.assign(p.entry, { status: 'pending', job_id: null, idempotency_key: null, request_metadata: null });
+        p.input = { ...p.input, metadata: lineMetadata(subdir, p.entry) };
+    };
+    const recreate = (p, reason) => {
+        resetForNewJob(p);
+        p.entry.error = null;
+        p.action = 'create';
+        p.recreated = reason;
+    };
+    // ── 1b. Probe the jobs of resumed lines ──
+    // A job from an earlier run may be gone, failed, or past its 30-day audio
+    // retention. Such a line needs a NEW job — a new charge — so it is found
+    // here, before the cap, the quote and the confirmation, and goes through
+    // them like any new line. The run phase never creates a job for a line it
+    // was only asked to follow.
+    const probing = planned.filter(p => p.action === 'resume');
+    if (probing.length > 0) {
+        opts.onProgress?.(0, planned.length, `Checking ${probing.length} job(s) from an earlier run`);
+        await pool(probing, PROBE_CONCURRENCY, () => false, async (p) => {
+            let job;
+            try {
+                job = await getJob(ctx, p.entry.job_id, opts.signal ? { signal: opts.signal } : {});
+            }
+            catch (err) {
+                const e = toAthanLabError(err);
+                if (e.code !== 'not_found')
+                    throw e;
+                recreate(p, 'not_found');
+                return;
+            }
+            if (job.status === 'failed' || job.status === 'cancelled')
+                recreate(p, job.status === 'failed' ? 'job_failed' : 'cancelled');
+            else if (job.status === 'succeeded' && !audioAvailable(job, ctx.clock.now()))
+                recreate(p, 'audio_expired');
+            else
+                p.probed = job;
+        });
+    }
+    const toCreate = planned.filter(p => p.action === 'create');
+    const toResume = planned.filter(p => p.action === 'resume');
+    const skipped = planned.filter(p => p.action === 'skip');
+    const recreated = toCreate.filter(p => p.recreated);
+    const createCharacters = toCreate.reduce((sum, p) => sum + p.entry.characters, 0);
+    const recreatedNote = recreated.length > 0
+        ? ` This includes ${recreated.length} line(s) whose earlier job can no longer deliver audio (deleted after 30 days, gone, or failed), so they are generated — and charged — again.`
+        : '';
+    if (ctx.config.maxCharsPerCall !== null && createCharacters > ctx.config.maxCharsPerCall) {
+        throw AthanLabError.client('max_chars_exceeded', `This script would generate ${createCharacters} characters in one call, above ATHANLAB_MAX_CHARS_PER_CALL (${ctx.config.maxCharsPerCall}). Nothing was sent.${recreatedNote} Split the script into smaller calls (same out_subdir) or raise the cap.`);
+    }
+    // ── 2. Quote ──
+    let quote = {
+        characters: 0,
+        lines: 0,
+        dispatches: 0,
+        spendable: null,
+        sufficient: null,
+        lines_skipped: skipped.length,
+        lines_resumed: toResume.length,
+    };
+    let useBatch = false;
+    if (toCreate.length > 0) {
+        opts.onProgress?.(0, planned.length, `Quoting ${toCreate.length} line(s)`);
+        const batchQuote = ctx.features.batch ? await tryBatchQuote(ctx, toCreate, format, numberMode, opts.signal) : null;
+        if (batchQuote) {
+            quote = { ...quote, ...batchQuote };
+            useBatch = true;
+        }
+        else {
+            quote = { ...quote, ...(await quoteLines(ctx, toCreate, opts.signal)) };
+        }
+    }
+    // The account as it is now: entitlement, key budget, free job slots — and
+    // the balance the quote shows and is checked against. Never a balance from
+    // a cached quote: the user may have topped up since the first call.
+    const work = planned.filter(p => p.action !== 'skip');
+    const usage = work.length > 0 ? await readUsage(ctx, opts.signal) : null;
+    if (usage && toCreate.length > 0) {
+        if (usage.entitled === false) {
+            throw AthanLabError.client('plan_required', 'Creating jobs needs an active Max plan (or founder access); this key is read-only. Nothing was created.', {
+                upgradeUrl: usage.upgrade_url ?? null,
+            });
+        }
+        const remaining = usage.key?.remaining;
+        if (typeof remaining === 'number' && remaining < createCharacters) {
+            throw AthanLabError.client('key_budget_exceeded', `This key's monthly budget has ${remaining} characters left; the script needs ${createCharacters}. Nothing was created.`, {
+                details: { required: createCharacters, remaining, resets_at: usage.key?.resets_at ?? null },
+            });
+        }
+    }
+    if (toCreate.length > 0) {
+        // Without usage:read, the freshest dry run's balance (null when every quote came from the cache): the API's 402 stays the authority.
+        const spendable = typeof usage?.spendable === 'number' ? usage.spendable : quote.spendable;
+        quote = { ...quote, spendable, sufficient: spendable === null ? null : spendable >= quote.characters };
+        const needsConfirm = createCharacters > CONFIRM_CHARACTERS_THRESHOLD || toCreate.length > CONFIRM_LINES_THRESHOLD;
+        if (needsConfirm && !input.confirm) {
+            return {
+                ...emptyResult(dir, planned, quote, useBatch),
+                status: 'confirmation_required',
+                message: `Quote only — nothing was created or charged. ${toCreate.length} line(s), ${quote.characters} characters${quote.spendable !== null ? ` (the account can spend ${quote.spendable})` : ''}${skipped.length ? `; ${skipped.length} line(s) already done` : ''}.${recreatedNote} This is above the confirmation threshold (${CONFIRM_CHARACTERS_THRESHOLD} characters or ${CONFIRM_LINES_THRESHOLD} lines): show the quote to the user, then call again with the same arguments and confirm: true.`,
+            };
+        }
+        if (quote.sufficient === false) {
+            throw AthanLabError.client('insufficient_characters', `The script needs ${quote.characters} characters but the account can spend ${quote.spendable}. Nothing was created or charged.`, {
+                details: { required: quote.characters, spendable: quote.spendable },
+            });
+        }
+    }
+    // ── 3. Run ──
+    let concurrency = 1;
+    if (usage) {
+        const max = Math.max(1, usage.max_concurrent_jobs);
+        concurrency = Math.max(1, Math.min(max - usage.active_jobs, max));
+    }
+    await ensureDir(dir);
+    const now = new Date(ctx.clock.now()).toISOString();
+    const manifest = {
+        version: 1,
+        generator: `athanlab-mcp ${VERSION}`,
+        script_id: scriptId,
+        output_format: format,
+        gaps,
+        created_at: previous?.created_at ?? now,
+        updated_at: now,
+        timeline_complete: false,
+        total_duration_seconds: null,
+        combined_file: null,
+        batch: previous?.batch ?? null,
+        lines: planned.map(p => p.entry),
+    };
+    let saving = Promise.resolve();
+    const save = () => {
+        manifest.updated_at = new Date(ctx.clock.now()).toISOString();
+        const snapshot = JSON.stringify(manifest, null, 2);
+        saving = saving.catch(() => { }).then(() => writeFileAtomic(manifestPath, `${snapshot}\n`));
+        return saving;
+    };
+    await save();
+    const deadline = ctx.clock.now() + (input.timeout_seconds ?? DEFAULT_SCRIPT_TIMEOUT_SECONDS) * 1000;
+    const downloads = new Semaphore(MAX_DOWNLOADS_AT_ONCE);
+    let stopError = null;
+    let timedOut = false;
+    let chargedThisRun = 0;
+    let finished = skipped.length;
+    const startedAt = ctx.clock.now();
+    const report = (message) => opts.onProgress?.(finished, planned.length, message);
+    const finishLine = async (p, job) => {
+        const target = path.join(dir, p.entry.file);
+        await downloads.run(() => downloadJobAudio(ctx, job.id, format, target, opts.signal));
+        let duration = job.audio?.duration_seconds ?? null;
+        if (format === 'wav') {
+            try {
+                duration = (await readWavInfo(target)).durationSeconds;
+            }
+            catch (err) {
+                ctx.logger.warn('could not read the WAV header; using the API duration', { line: p.entry.index, error: err.message });
+            }
+        }
+        const timing = timingOf(job.audio);
+        Object.assign(p.entry, {
+            status: 'succeeded',
+            voice_id: job.input?.voice_id ?? p.entry.requested_voice_id,
+            characters_charged: job.usage?.characters_charged ?? p.entry.characters,
+            duration_seconds: duration,
+            speech_start_seconds: timing.speech_start_seconds,
+            speech_end_seconds: timing.speech_end_seconds,
+            error: null,
+        });
+        await save();
+    };
+    /** Poll an existing job to the end and save its audio. Returns the failed job when it did not succeed. */
+    const followJob = async (p, job, firstPoll) => {
+        const waited = await waitForJob(ctx, job, firstPoll, {
+            deadline,
+            ...(opts.signal ? { signal: opts.signal } : {}),
+            // Every poll is reported (the lines-done count unchanged: a heartbeat), so a long or cold-starting line is never silent.
+            onProgress: (polled) => report(`Line ${p.entry.index + 1}: ${polled.status}, ${Math.round((ctx.clock.now() - startedAt) / 1000)} s`),
+        });
+        if (waited.timedOut)
+            return 'timed_out';
+        if (waited.job.status === 'succeeded') {
+            await finishLine(p, waited.job);
+            return null;
+        }
+        return waited.job;
+    };
+    /**
+     * A followed job that can no longer deliver: the line is marked failed and
+     * left for the next run, which plans it as a new line — quoted, under the
+     * per-call cap and the confirmation, and charged only then.
+     */
+    const giveUp = async (entry, code, message) => {
+        if (code === 'not_found')
+            entry.job_id = null;
+        Object.assign(entry, {
+            status: 'failed',
+            idempotency_key: null,
+            error: { code, message: `${message} Run the same call again to generate this line anew (it is quoted first and charged again).` },
+        });
+        finished++;
+        await save();
+        report(`Line ${entry.index + 1} failed`);
+    };
+    /** The job an idempotency_conflict names, when it carries this line's request; null otherwise. */
+    const conflictingJob = async (p, e) => {
+        const jobId = e.details?.job_id;
+        if (typeof jobId !== 'string' || !JOB_ID_PATTERN.test(jobId))
+            return null;
+        try {
+            const job = await getJob(ctx, jobId, { deadline, ...(opts.signal ? { signal: opts.signal } : {}) });
+            return jobMatchesLine(job, p.entry, format) ? job : null;
+        }
+        catch (err) {
+            if (toAthanLabError(err).code === 'not_found')
+                return null;
+            throw err;
+        }
+    };
+    /**
+     * One line to the end. Only a line planned as 'create' (and not handed over
+     * by a batch) may create a job — its characters were quoted, capped and
+     * confirmed. A resumed or batch line is followed, and never re-created here.
+     */
+    const processLine = async (p, followOnly = false) => {
+        const entry = p.entry;
+        const mayCreate = p.action === 'create' && !followOnly;
+        const waitOpts = { deadline, ...(opts.signal ? { signal: opts.signal } : {}) };
+        let conflictHandled = false;
+        try {
+            let following = null;
+            if (entry.job_id) {
+                try {
+                    following = p.probed ?? await getJob(ctx, entry.job_id, waitOpts);
+                }
+                catch (err) {
+                    const e = toAthanLabError(err);
+                    if (e.code !== 'not_found')
+                        throw e;
+                    return await giveUp(entry, e.code, `Job ${entry.job_id} no longer exists.`);
+                }
+                p.probed = undefined;
+            }
+            for (;;) {
+                let outcome;
+                let chargedNow = 0;
+                if (following) {
+                    // The job exists (and was paid for): follow it.
+                    try {
+                        outcome = await followJob(p, following, 0);
+                    }
+                    catch (err) {
+                        const e = toAthanLabError(err);
+                        if (e.code !== 'audio_expired' && e.code !== 'job_failed' && e.code !== 'not_found')
+                            throw e;
+                        return await giveUp(entry, e.code, e.message);
+                    }
+                    following = null;
+                }
+                else {
+                    if (!mayCreate)
+                        return;
+                    if (stopError || ctx.clock.now() >= deadline) {
+                        if (!stopError)
+                            timedOut = true;
+                        return;
+                    }
+                    if (!entry.idempotency_key) {
+                        entry.idempotency_key = ctx.newIdempotencyKey();
+                        entry.request_metadata = p.input.metadata ?? null;
+                    }
+                    entry.status = 'pending';
+                    entry.attempts += 1;
+                    await save();
+                    let created;
+                    try {
+                        created = await createSpeechJob(ctx, p.input, entry.idempotency_key, waitOpts);
+                    }
+                    catch (err) {
+                        const e = toAthanLabError(err);
+                        if (e.code !== 'idempotency_conflict' || conflictHandled)
+                            throw e;
+                        // The saved key was first used with a different body. It is this
+                        // line's own key, so its job is this line's earlier attempt: adopt
+                        // it when it carries this line's request (paid then, not now);
+                        // otherwise start over with a new key.
+                        conflictHandled = true;
+                        entry.attempts -= 1;
+                        const earlier = await conflictingJob(p, e);
+                        if (earlier) {
+                            ctx.logger.info('adopting the job an earlier run created under this line\'s key', { line: entry.index, job_id: earlier.id });
+                            entry.job_id = earlier.id;
+                            entry.status = 'processing';
+                            await save();
+                            following = earlier;
+                        }
+                        else {
+                            ctx.logger.warn('saved Idempotency-Key belongs to a different request; using a new key', { line: entry.index });
+                            resetForNewJob(p);
+                        }
+                        continue;
+                    }
+                    entry.job_id = created.job.id;
+                    entry.status = 'processing';
+                    if (!created.replayed)
+                        chargedNow = created.job.usage?.characters_charged ?? entry.characters;
+                    chargedThisRun += chargedNow;
+                    await save();
+                    outcome = await followJob(p, created.job, created.firstPollSeconds);
+                }
+                if (outcome === null) {
+                    finished++;
+                    report(`Line ${entry.index + 1} done`);
+                    return;
+                }
+                if (outcome === 'timed_out') {
+                    timedOut = true;
+                    return;
+                }
+                const failure = jobOutcomeError(outcome);
+                // Refunds count against this run's charge only for a job this run paid for.
+                if (outcome.status === 'failed' && chargedNow > 0)
+                    chargedThisRun -= outcome.usage?.characters_refunded ?? 0;
+                if (mayCreate && outcome.status === 'failed' && failure.retryable && entry.attempts < MAX_JOB_ATTEMPTS && !stopError) {
+                    // Refunded; a new key, since the old one would replay this failure.
+                    resetForNewJob(p);
+                    continue;
+                }
+                entry.status = outcome.status === 'cancelled' ? 'cancelled' : 'failed';
+                entry.error = { code: failure.code, message: failure.message };
+                finished++;
+                await save();
+                report(`Line ${entry.index + 1} ${entry.status}`);
+                return;
+            }
+        }
+        catch (err) {
+            const e = toAthanLabError(err);
+            if (opts.signal?.aborted)
+                throw e;
+            if (LINE_ERROR_CODES.has(e.code)) {
+                entry.status = 'failed';
+                entry.error = { code: e.code, message: e.message };
+                entry.idempotency_key = null;
+                finished++;
+                await save();
+                return;
+            }
+            if (e.code === 'timeout' && ctx.clock.now() >= deadline) {
+                timedOut = true;
+                return;
+            }
+            // Everything else stops new work: the account, the key or the service
+            // is the problem, not this line. The entry keeps its key/job for a resume
+            // (re-running the script reuses it — no idempotency_key to hand back).
+            if (e.details && 'idempotency_key' in e.details) {
+                const { idempotency_key: _saved, ...rest } = e.details;
+                e.details = Object.keys(rest).length > 0 ? rest : null;
+            }
+            if (!stopError)
+                stopError = e;
+            if (!ACCOUNT_STOP_CODES.has(e.code))
+                ctx.logger.warn('script stopped on an unexpected error', { code: e.code, line: entry.index });
+            entry.error = { code: e.code, message: e.message };
+            await save();
+        }
+    };
+    report(`Generating ${work.length} line(s), ${concurrency} at a time`);
+    let usedBatch = false;
+    // A line still holding a per-line Idempotency-Key (an earlier run's POST that
+    // may have landed) must replay with that key; in a batch it could be bought twice.
+    const batchable = toCreate.filter(p => !p.entry.idempotency_key);
+    if (useBatch && batchable.length > 0) {
+        const { runBatch } = await import('./batch.js');
+        // Resumed lines and keyed lines run alongside the batch.
+        const alongside = pool([...toResume, ...toCreate.filter(p => p.entry.idempotency_key)], concurrency, () => false, p => processLine(p));
+        usedBatch = await runBatch(ctx, {
+            lines: batchable,
+            format,
+            numberMode,
+            manifest,
+            save,
+            deadline,
+            signal: opts.signal,
+            followLine: async (line, charged) => {
+                if (charged)
+                    chargedThisRun += line.entry.characters;
+                const planned = batchable.find(p => p.entry === line.entry);
+                if (planned)
+                    await processLine(planned, true);
+            },
+            onStop: (e) => { stopError ??= e; },
+            onTimeout: () => { timedOut = true; },
+        });
+        await alongside;
+        // No batches after all: one job per line, for the lines no earlier batch already gave a job.
+        if (!usedBatch)
+            await pool(batchable.filter(p => !p.entry.job_id), concurrency, () => false, p => processLine(p));
+    }
+    else {
+        await pool(work, concurrency, () => false, p => processLine(p));
+    }
+    await saving.catch(() => { });
+    // ── 4. Finish ──
+    const timeline = layoutTimeline(planned.map(p => ({ speaker: p.entry.speaker, durationSeconds: p.entry.status === 'succeeded' ? p.entry.duration_seconds : null })), gaps);
+    planned.forEach((p, i) => {
+        const slot = timeline.slots[i];
+        p.entry.start_seconds = roundMs(slot?.start ?? null);
+        p.entry.end_seconds = roundMs(slot?.end ?? null);
+    });
+    manifest.timeline_complete = timeline.complete;
+    manifest.total_duration_seconds = roundMs(timeline.totalSeconds);
+    let combinedPath = null;
+    let combineError = null;
+    if (input.combine) {
+        if (timeline.complete) {
+            try {
+                const target = path.join(dir, COMBINED_FILE);
+                await combineWavFiles(planned.map((p, i) => ({
+                    file: path.join(dir, p.entry.file),
+                    startSeconds: timeline.slots[i]?.start ?? 0,
+                })), target);
+                combinedPath = target;
+                manifest.combined_file = COMBINED_FILE;
+            }
+            catch (err) {
+                combineError = toAthanLabError(err).toJSON();
+            }
+        }
+        else {
+            combineError = { code: 'incomplete', message: 'combined.wav is written once every line has succeeded. Run the same call again to finish the remaining lines.' };
+        }
+    }
+    await save();
+    const counts = {
+        succeeded: planned.filter(p => p.entry.status === 'succeeded').length,
+        failed: planned.filter(p => p.entry.status === 'failed' || p.entry.status === 'cancelled').length,
+    };
+    const pending = planned.length - counts.succeeded - counts.failed;
+    const status = stopError
+        ? 'stopped'
+        : timedOut
+            ? 'timed_out'
+            : counts.succeeded === planned.length ? 'completed' : 'partial';
+    const stopped = stopError ? stopError.toJSON() : null;
+    const message = [
+        `${counts.succeeded}/${planned.length} line(s) ready in ${dir}${skipped.length ? ` (${skipped.length} already done, not charged again)` : ''}.`,
+        recreated.length ? `${recreated.length} line(s) were generated again: their earlier job could no longer deliver audio (deleted after 30 days, gone, or failed).` : '',
+        counts.failed ? `${counts.failed} failed — see each line's error.` : '',
+        stopError ? `Stopped creating new jobs: ${stopError.code}. ${stopError.action}` : '',
+        timedOut ? 'The time limit passed; running jobs continue on AthanLab\'s side. Call again with the same arguments to resume — finished lines are skipped and running jobs are followed, not paid again.' : '',
+        status === 'partial' || status === 'stopped' ? 'Re-run the same call to retry what is left; finished lines are skipped.' : '',
+        combinedPath ? `combined.wav: ${roundMs(timeline.totalSeconds)} s.` : '',
+        combineError && input.combine ? `combined.wav not written: ${String(combineError.message)}` : '',
+    ].filter(Boolean).join(' ');
+    return {
+        status,
+        directory: dir,
+        manifest_path: manifestPath,
+        combined_path: combinedPath,
+        quote: toCreate.length > 0 ? quote : null,
+        lines_total: planned.length,
+        lines_succeeded: counts.succeeded,
+        lines_skipped: skipped.length,
+        lines_failed: counts.failed,
+        lines_pending: pending,
+        characters_charged: Math.max(0, chargedThisRun),
+        total_duration_seconds: roundMs(timeline.totalSeconds),
+        timeline_complete: timeline.complete,
+        stopped,
+        combine_error: combineError,
+        used_batch: usedBatch,
+        message,
+        lines: planned.map(p => lineResult(dir, p.entry)),
+    };
+}
+function lineResult(dir, entry) {
+    return {
+        index: entry.index,
+        id: entry.id,
+        speaker: entry.speaker,
+        status: entry.status,
+        file: entry.status === 'succeeded' && entry.file ? path.join(dir, entry.file) : null,
+        job_id: entry.job_id,
+        duration_seconds: roundMs(entry.duration_seconds),
+        start_seconds: entry.start_seconds,
+        end_seconds: entry.end_seconds,
+        error: entry.error,
+    };
+}
+function emptyResult(dir, planned, quote, usedBatch) {
+    return {
+        directory: dir,
+        manifest_path: null,
+        combined_path: null,
+        quote,
+        lines_total: planned.length,
+        lines_succeeded: planned.filter(p => p.action === 'skip').length,
+        lines_skipped: planned.filter(p => p.action === 'skip').length,
+        lines_failed: 0,
+        lines_pending: planned.filter(p => p.action !== 'skip').length,
+        characters_charged: 0,
+        total_duration_seconds: null,
+        timeline_complete: false,
+        stopped: null,
+        combine_error: null,
+        used_batch: usedBatch,
+        lines: planned.map(p => lineResult(dir, p.entry)),
+    };
+}
+async function readUsage(ctx, signal) {
+    try {
+        return (await ctx.client.json('/usage', signal ? { signal } : {})).data;
+    }
+    catch (err) {
+        const e = toAthanLabError(err);
+        // A key without usage:read can still run a script, one line at a time.
+        if (e.code === 'scope_missing')
+            return null;
+        throw e;
+    }
+}
+/**
+ * A dry run per line. What a line costs is cached for 30 minutes, so the
+ * confirm: true call does not quote again; the balance is not (spendable here
+ * comes only from dry runs made now, and the caller prefers GET /usage).
+ */
+async function quoteLines(ctx, lines, signal) {
+    const cache = ctx.quoteCache;
+    const problems = [];
+    let characters = 0;
+    let dispatches = 0;
+    let spendable = null;
+    await pool(lines, QUOTE_CONCURRENCY, () => false, async (p) => {
+        const key = sha256(JSON.stringify({ ...p.input, metadata: undefined }));
+        const cached = cache?.get(key);
+        let cost;
+        if (cached && ctx.clock.now() - cached.at < QUOTE_CACHE_TTL_MS) {
+            cost = cached;
+        }
+        else {
+            let quote;
+            try {
+                quote = await quoteSpeech(ctx, { ...p.input, metadata: undefined }, signal);
+            }
+            catch (err) {
+                const e = toAthanLabError(err);
+                if (LINE_ERROR_CODES.has(e.code)) {
+                    problems.push({ index: p.entry.index, error: e });
+                    return;
+                }
+                throw e;
+            }
+            cost = { characters: quote.characters, dispatches: quote.dispatches };
+            cache?.set(key, { ...cost, at: ctx.clock.now() });
+            if (typeof quote.spendable === 'number')
+                spendable = spendable === null ? quote.spendable : Math.min(spendable, quote.spendable);
+        }
+        characters += cost.characters;
+        dispatches += cost.dispatches;
+    });
+    if (problems.length > 0) {
+        problems.sort((a, b) => a.index - b.index);
+        throw AthanLabError.client('invalid_lines', `${problems.length} line(s) would be refused, so nothing was created or charged: ${problems.map(p => `line ${p.index}: ${p.error.code} — ${p.error.message}`).join('; ')}`, {
+            details: { line_errors: problems.map(p => ({ index: p.index, code: p.error.code, message: p.error.message, param: p.error.param })) },
+        });
+    }
+    const total = spendable;
+    return {
+        characters,
+        lines: lines.length,
+        dispatches,
+        spendable: total,
+        sufficient: total === null ? null : total >= characters,
+    };
+}
+async function tryBatchQuote(ctx, lines, format, numberMode, signal) {
+    const { quoteBatch } = await import('./batch.js');
+    return quoteBatch(ctx, lines.map(p => ({ entry: p.entry, input: p.input, carried: p.carried })), format, numberMode, signal);
+}
+//# sourceMappingURL=script.js.map