mergestory 0.0.0-stage → 1.0.0

package/dist/llm/openai-compatible.js

@@ -0,0 +1,378 @@
+/**
+ * OpenAI and OpenAI-compatible provider over plain HTTPS (Chat Completions), so one adapter
+ * serves OpenAI, Ollama, OpenRouter, vLLM, LM Studio and Groq.
+ *
+ * The request asks for a strict JSON schema. Servers differ in what they accept, so a 400 that
+ * names an unsupported field makes the adapter adjust that one field and try again (at most once
+ * per field). A sampling parameter is never sent: current reasoning models reject them.
+ */
+import { estimateTokens } from '../core/cost.js';
+import { abortedError, MergeStoryError, TimedOutError, toMergeStoryError } from '../core/errors.js';
+import { asNumber, isRecord } from '../core/json.js';
+import { isPrivateHostname } from '../core/net.js';
+import { defaultIsRetryable, fetchWithRetry, HttpError } from '../core/retry.js';
+import { budgetLlmCostUsd } from './prices.js';
+import { buildMessages, parseEndpointUrl, parseJsonLoose, readBodyLimited, recordBilledFailure, safeSnippet, } from './shared.js';
+export const OPENAI_BASE_URL = 'https://api.openai.com/v1';
+/** A storyboard answer is a few hundred kilobytes; a much larger one comes from a broken server. */
+const MAX_ANSWER_BYTES = 32 * 1_048_576;
+function initialDialect(flavor) {
+    if (flavor === 'openai') {
+        return {
+            jsonMode: 'json_schema',
+            tokenField: 'max_completion_tokens',
+            reasoningEffort: true,
+            store: true,
+            cacheOptions: true,
+        };
+    }
+    // max_tokens is the name every compatible server accepts.
+    return {
+        jsonMode: 'json_schema',
+        tokenField: 'max_tokens',
+        reasoningEffort: false,
+        store: false,
+        cacheOptions: false,
+    };
+}
+function buildBody(request, model, dialect, effort) {
+    const system = dialect.jsonMode === 'json_object'
+        ? `${request.system}\n\nReturn one JSON object and nothing else. It must match this JSON Schema exactly:\n${JSON.stringify(request.jsonSchema)}`
+        : request.system;
+    const body = {
+        model,
+        messages: [{ role: 'system', content: system }, ...buildMessages(request)],
+        [dialect.tokenField]: request.maxOutputTokens,
+        response_format: dialect.jsonMode === 'json_schema'
+            ? {
+                type: 'json_schema',
+                json_schema: {
+                    name: request.schemaName.replace(/[^A-Za-z0-9_-]/g, '_').slice(0, 64) || 'schema',
+                    strict: true,
+                    schema: request.jsonSchema,
+                },
+            }
+            : { type: 'json_object' },
+    };
+    if (dialect.store)
+        body.store = false;
+    if (dialect.reasoningEffort)
+        body.reasoning_effort = effort;
+    if (dialect.cacheOptions)
+        body.prompt_cache_options = { mode: 'explicit' };
+    return body;
+}
+/** Change one field of the request after a 400 that names it. Returns a short note, or null when nothing applies. */
+function adaptDialect(dialect, applied, errorText) {
+    const text = errorText.toLowerCase();
+    const once = (key, change, note) => {
+        if (applied.has(key))
+            return null;
+        applied.add(key);
+        change();
+        return note;
+    };
+    if (dialect.jsonMode === 'json_schema' && /response_format|json_schema/.test(text)) {
+        return once('json', () => {
+            dialect.jsonMode = 'json_object';
+        }, 'JSON mode with the schema in the prompt');
+    }
+    if (dialect.cacheOptions && text.includes('prompt_cache_options')) {
+        return once('cache', () => {
+            dialect.cacheOptions = false;
+        }, 'without prompt_cache_options');
+    }
+    if (dialect.reasoningEffort && text.includes('reasoning_effort')) {
+        return once('effort', () => {
+            dialect.reasoningEffort = false;
+        }, 'without reasoning_effort');
+    }
+    if (text.includes(dialect.tokenField)) {
+        return once('tokens', () => {
+            dialect.tokenField = dialect.tokenField === 'max_tokens' ? 'max_completion_tokens' : 'max_tokens';
+        }, 'with the other output limit field');
+    }
+    return null;
+}
+const NON_RETRYABLE_429 = /insufficient_quota|credit_balance|spend_limit|usage_limit|quota_exceeded|billing/i;
+/**
+ * A 429 that reports a spending or quota limit will not clear by waiting, so it is not retried.
+ * Neither is a timeout: the model may still finish and bill that answer, and the next try would
+ * most likely time out as well.
+ */
+function isRetryable(err) {
+    if (err instanceof TimedOutError)
+        return false;
+    if (err instanceof HttpError) {
+        if (err.status === 429 && NON_RETRYABLE_429.test(err.bodySnippet))
+            return false;
+        return err.retryable;
+    }
+    return defaultIsRetryable(err);
+}
+/** The message inside an error body. The body may be an object, a plain string or cut off. */
+function errorMessageOf(snippet) {
+    try {
+        const parsed = JSON.parse(snippet);
+        if (typeof parsed === 'string')
+            return parsed;
+        if (isRecord(parsed)) {
+            const error = parsed.error;
+            if (typeof error === 'string')
+                return error;
+            if (isRecord(error) && typeof error.message === 'string')
+                return error.message;
+            if (typeof parsed.message === 'string')
+                return parsed.message;
+        }
+    }
+    catch {
+        // Not JSON, or longer than the stored snippet: use the raw text.
+    }
+    return snippet;
+}
+function missingKeyError(flavor, keyName) {
+    return new MergeStoryError('CONFIG_INVALID', `No API key was found for the ${flavor} provider.`, {
+        hint: `Set ${keyName}, or choose another provider with MERGESTORY_LLM_PROVIDER.`,
+    });
+}
+function mapFailure(err, ctx, options, host) {
+    if (ctx.signal.aborted)
+        return abortedError(err);
+    if (err instanceof HttpError) {
+        const detail = safeSnippet(ctx, errorMessageOf(err.bodySnippet));
+        const status = err.status;
+        const details = { status };
+        if (status === 401) {
+            return new MergeStoryError('CONFIG_INVALID', `${host} rejected the API key.`, {
+                cause: err,
+                hint: `Set ${options.keyName} to a valid key.`,
+                details,
+            });
+        }
+        if (status === 429) {
+            if (NON_RETRYABLE_429.test(err.bodySnippet)) {
+                return new MergeStoryError('LLM_FAILED', `${host} reports a quota or spending limit: ${detail}`, {
+                    cause: err,
+                    hint: 'Check the plan, billing and spend limits of this key.',
+                    details,
+                });
+            }
+            return new MergeStoryError('RATE_LIMITED', `${host} is rate limiting this key.`, {
+                cause: err,
+                retryable: true,
+                hint: 'Wait a minute and run again, or pick another model.',
+                details,
+            });
+        }
+        let hint = 'Check llm.model and llm.baseUrl.';
+        if (status === 402)
+            hint = 'The account is out of credit. Add credit or pick another provider.';
+        else if (status === 403)
+            hint = 'The key has no access to this model or region.';
+        else if (status === 404)
+            hint = 'Check that llm.baseUrl ends with /v1 and that llm.model exists on the server.';
+        else if (status === 413)
+            hint = 'The request is too large. Lower llm.maxInputTokens.';
+        else if (status === 400 && /context|too long|maximum/i.test(err.bodySnippet)) {
+            hint =
+                'The request may be longer than the model context. Lower llm.maxInputTokens or use privacy.llmContext "minimal".';
+        }
+        return new MergeStoryError('LLM_FAILED', `${host} returned an error (HTTP ${status}): ${detail}`, {
+            cause: err,
+            hint,
+            retryable: err.retryable,
+            details,
+        });
+    }
+    if (err instanceof MergeStoryError) {
+        if (err.code !== 'INTERNAL')
+            return err;
+        const timedOut = err instanceof TimedOutError;
+        return new MergeStoryError('LLM_FAILED', timedOut
+            ? `The model did not answer within ${Math.round(options.timeoutMs / 1000)} seconds.`
+            : `Could not reach ${host}: ${safeSnippet(ctx, err.message, 160)}`, {
+            cause: err,
+            retryable: true,
+            hint: timedOut
+                ? 'Raise llm.timeoutMs or shorten the change.'
+                : 'Check your network connection and llm.baseUrl. A local server must be running.',
+        });
+    }
+    return toMergeStoryError(err, 'LLM_FAILED');
+}
+function contentText(content) {
+    if (typeof content === 'string')
+        return content;
+    if (!Array.isArray(content))
+        return '';
+    return content.map((part) => (isRecord(part) && typeof part.text === 'string' ? part.text : '')).join('');
+}
+function readCompletion(body, request, ctx, options, host) {
+    const local = isPrivateHostname(new URL(`http://${host}`).hostname);
+    const parsed = isRecord(body) ? body : {};
+    const choices = Array.isArray(parsed.choices) ? parsed.choices : [];
+    const first = isRecord(choices[0]) ? choices[0] : null;
+    if (!first) {
+        // Some gateways report a failure inside an HTTP 200 answer.
+        const failure = isRecord(parsed.error) || typeof parsed.error === 'string'
+            ? errorMessageOf(JSON.stringify(parsed.error))
+            : '';
+        throw new MergeStoryError('LLM_FAILED', failure ? `${host} returned an error: ${safeSnippet(ctx, failure)}` : `${host} returned no answer.`, { hint: 'Check llm.model and llm.baseUrl.' });
+    }
+    const message = isRecord(first.message) ? first.message : {};
+    const finish = typeof first.finish_reason === 'string' ? first.finish_reason : null;
+    const text = contentText(message.content);
+    const usage = isRecord(parsed.usage) ? parsed.usage : null;
+    const promptDetails = usage && isRecord(usage.prompt_tokens_details) ? usage.prompt_tokens_details : null;
+    const inputTokens = asNumber(usage?.prompt_tokens) ??
+        asNumber(usage?.input_tokens) ??
+        estimateTokens(request.system + request.prompt);
+    const outputTokens = asNumber(usage?.completion_tokens) ?? asNumber(usage?.output_tokens) ?? estimateTokens(text);
+    const model = typeof parsed.model === 'string' && parsed.model ? parsed.model : options.model;
+    if (typeof message.refusal === 'string' && message.refusal.trim()) {
+        recordBilledFailure(ctx, options.id, options.model, inputTokens, outputTokens, local);
+        throw new MergeStoryError('LLM_REFUSED', `The model declined to write the storyboard: ${safeSnippet(ctx, message.refusal, 200)}`, {
+            hint: 'Try another model, or set llm.provider to "none" for the offline storyboard.',
+        });
+    }
+    if (finish === 'content_filter') {
+        recordBilledFailure(ctx, options.id, options.model, inputTokens, outputTokens, local);
+        throw new MergeStoryError('LLM_REFUSED', `${host} blocked the answer with its content filter.`, {
+            hint: 'Try another model, or set llm.provider to "none" for the offline storyboard.',
+        });
+    }
+    if (finish === 'length') {
+        recordBilledFailure(ctx, options.id, options.model, inputTokens, outputTokens, local);
+        throw new MergeStoryError('LLM_FAILED', `The model's answer was cut off after ${outputTokens} output tokens.`, {
+            hint: 'Raise llm.maxOutputTokens (reasoning models count thinking tokens too), lower llm.effort, or lower the target length.',
+        });
+    }
+    if (!text.trim()) {
+        recordBilledFailure(ctx, options.id, options.model, inputTokens, outputTokens, local);
+        throw new MergeStoryError('LLM_FAILED', 'The model returned no text.', {
+            hint: 'Run again. If it keeps happening, try another model.',
+            retryable: true,
+        });
+    }
+    return {
+        text,
+        json: parseJsonLoose(text),
+        usage: {
+            inputTokens,
+            outputTokens,
+            cacheReadTokens: asNumber(promptDetails?.cached_tokens) ?? undefined,
+            cacheWriteTokens: asNumber(promptDetails?.cache_write_tokens) ?? undefined,
+        },
+        model,
+        stopReason: finish,
+    };
+}
+/** Provider for the Chat Completions API of OpenAI or any server that speaks it. */
+export function createOpenAiProvider(options) {
+    const baseUrlText = options.baseUrl.href.replace(/\/+$/, '');
+    const host = options.baseUrl.host;
+    // A server on this machine or a private network (for example Ollama) bills nothing.
+    const local = isPrivateHostname(options.baseUrl.hostname);
+    return {
+        id: options.id,
+        model: options.model,
+        endpointHost: host,
+        async generateJson(request, ctx) {
+            const apiKey = ctx.secrets.get(options.keyName);
+            if (!apiKey && options.keyRequired)
+                throw missingKeyError(options.id, options.keyName);
+            const headers = { 'content-type': 'application/json' };
+            if (apiKey)
+                headers.authorization = `Bearer ${apiKey}`;
+            const dialect = initialDialect(options.id);
+            const applied = new Set();
+            for (;;) {
+                const body = buildBody(request, options.model, dialect, options.effort);
+                ctx.logger.debug('Chat Completions request', {
+                    host,
+                    model: options.model,
+                    jsonMode: dialect.jsonMode,
+                    turns: body.messages.length,
+                    promptChars: request.system.length + request.prompt.length,
+                });
+                let response;
+                try {
+                    response = await fetchWithRetry(`${baseUrlText}/chat/completions`, { method: 'POST', headers, body: JSON.stringify(body) }, {
+                        timeoutMs: options.timeoutMs,
+                        attempts: 3,
+                        minDelayMs: 1000,
+                        signal: ctx.signal,
+                        isRetryable,
+                        onRetry: ({ attempt, delayMs }) => ctx.logger.warn('Retrying the model request', { attempt, waitMs: Math.round(delayMs) }),
+                    });
+                }
+                catch (err) {
+                    if (err instanceof HttpError && (err.status === 400 || err.status === 422)) {
+                        const note = adaptDialect(dialect, applied, err.bodySnippet);
+                        if (note) {
+                            ctx.logger.info(`The server rejected part of the request. Trying again: ${note}.`);
+                            continue;
+                        }
+                    }
+                    throw mapFailure(err, ctx, options, host);
+                }
+                let parsed;
+                try {
+                    parsed = JSON.parse(new TextDecoder().decode(await readBodyLimited(response, MAX_ANSWER_BYTES, 'LLM_FAILED', host)));
+                }
+                catch (err) {
+                    if (err instanceof MergeStoryError)
+                        throw err;
+                    throw new MergeStoryError('LLM_FAILED', `${host} returned an answer that is not JSON.`, {
+                        cause: err,
+                        hint: 'Check that llm.baseUrl points at an OpenAI-compatible /v1 endpoint.',
+                    });
+                }
+                return readCompletion(parsed, request, ctx, options, host);
+            }
+        },
+        estimateCostUsd(inputTokens, outputTokens, ctx) {
+            return budgetLlmCostUsd(options.id, options.model, inputTokens, outputTokens, ctx, local);
+        },
+    };
+}
+/**
+ * The OpenAI key goes only to OpenAI, so the openai provider accepts no base URL except the
+ * OpenAI API. Returns the error for any other URL, or null when the setting is fine.
+ */
+export function openAiBaseUrlError(baseUrl) {
+    if (!baseUrl || baseUrl.trim().replace(/\/+$/, '') === OPENAI_BASE_URL)
+        return null;
+    return new MergeStoryError('CONFIG_INVALID', 'The openai provider only talks to the OpenAI API.', {
+        hint: 'To use another server, set llm.provider to "openai-compatible" and put its key in MERGESTORY_LLM_API_KEY. Or remove llm.baseUrl (MERGESTORY_LLM_BASE_URL) to use OpenAI.',
+    });
+}
+/** Validate the settings for the "openai" or "openai-compatible" provider and build it. */
+export function createOpenAiFromConfig(flavor, config, secrets, model) {
+    const keyName = flavor === 'openai' ? 'OPENAI_API_KEY' : 'MERGESTORY_LLM_API_KEY';
+    if (flavor === 'openai' && !secrets.has(keyName))
+        throw missingKeyError(flavor, keyName);
+    let baseUrlText = config.llm.baseUrl;
+    if (flavor === 'openai') {
+        const error = openAiBaseUrlError(baseUrlText);
+        if (error)
+            throw error;
+    }
+    if (flavor === 'openai-compatible' && !baseUrlText) {
+        throw new MergeStoryError('CONFIG_INVALID', 'The openai-compatible provider needs a base URL.', {
+            hint: 'Set llm.baseUrl or MERGESTORY_LLM_BASE_URL, for example http://localhost:11434/v1 for Ollama.',
+        });
+    }
+    baseUrlText ??= OPENAI_BASE_URL;
+    return createOpenAiProvider({
+        id: flavor,
+        model,
+        baseUrl: parseEndpointUrl(baseUrlText, 'llm.baseUrl'),
+        keyName,
+        keyRequired: flavor === 'openai',
+        effort: config.llm.effort,
+        timeoutMs: config.llm.timeoutMs,
+    });
+}
+//# sourceMappingURL=openai-compatible.js.map

package/dist/llm/prices.d.ts

@@ -0,0 +1,26 @@
+/**
+ * What an LLM call costs in USD, and what the budget assumes for a model with no price. Prices
+ * come from the run's price book: the built-in table in core/cost.ts with the "pricing" section
+ * of the config file laid over it, because providers change prices.
+ */
+import type { RunContext } from '../core/context.ts';
+interface ModelPrice {
+    inputPerMTok: number;
+    outputPerMTok: number;
+}
+/** The model id without a date or snapshot suffix ("claude-haiku-5-5-20261001" -> "claude-haiku-5-5"). */
+export declare function baseModelId(model: string): string;
+/**
+ * Estimated cost of a call in USD, from the run's price book for the exact id and then for the id
+ * without a date suffix. Returns null when the price is unknown.
+ */
+export declare function llmCostUsd(provider: string, model: string, inputTokens: number, outputTokens: number, ctx: RunContext): number | null;
+/** Rate used for a model whose price is unknown: the highest listed rate, so the budget still holds. */
+export declare const UNKNOWN_MODEL_PRICE: ModelPrice;
+/**
+ * Cost to check against the budget and to record. A model without a known price counts at
+ * UNKNOWN_MODEL_PRICE (with one warning per model), so an unlisted model can never get past the
+ * budget. Servers on this machine or a private network (for example Ollama) cost nothing.
+ */
+export declare function budgetLlmCostUsd(provider: string, model: string, inputTokens: number, outputTokens: number, ctx: RunContext, local: boolean): number;
+export {};

package/dist/llm/prices.js

@@ -0,0 +1,41 @@
+/** The model id without a date or snapshot suffix ("claude-haiku-5-5-20261001" -> "claude-haiku-5-5"). */
+export function baseModelId(model) {
+    return model.replace(/(?:[-@]\d{8}|-\d{4}-\d{2}-\d{2})$/, '');
+}
+/**
+ * Estimated cost of a call in USD, from the run's price book for the exact id and then for the id
+ * without a date suffix. Returns null when the price is unknown.
+ */
+export function llmCostUsd(provider, model, inputTokens, outputTokens, ctx) {
+    for (const id of new Set([model, baseModelId(model)])) {
+        const cost = ctx.cost.prices.llmCost(provider, id, inputTokens, outputTokens);
+        if (cost !== null)
+            return cost;
+    }
+    return null;
+}
+/** Rate used for a model whose price is unknown: the highest listed rate, so the budget still holds. */
+export const UNKNOWN_MODEL_PRICE = { inputPerMTok: 10, outputPerMTok: 50 };
+/**
+ * Cost to check against the budget and to record. A model without a known price counts at
+ * UNKNOWN_MODEL_PRICE (with one warning per model), so an unlisted model can never get past the
+ * budget. Servers on this machine or a private network (for example Ollama) cost nothing.
+ */
+export function budgetLlmCostUsd(provider, model, inputTokens, outputTokens, ctx, local) {
+    if (local)
+        return 0;
+    const known = llmCostUsd(provider, model, inputTokens, outputTokens, ctx);
+    if (known !== null)
+        return known;
+    if (ctx.firstTime(`unknown-llm-price:${provider}:${model}`)) {
+        ctx.progress({
+            stage: 'storyboard',
+            status: 'warn',
+            message: `No price is known for ${provider} model "${model}"; counting it at $${UNKNOWN_MODEL_PRICE.inputPerMTok}/` +
+                `$${UNKNOWN_MODEL_PRICE.outputPerMTok} per million tokens against the budget. Add its price to the "pricing" section of the config file.`,
+        });
+    }
+    return ((inputTokens * UNKNOWN_MODEL_PRICE.inputPerMTok + outputTokens * UNKNOWN_MODEL_PRICE.outputPerMTok) /
+        1_000_000);
+}
+//# sourceMappingURL=prices.js.map

package/dist/llm/shared.d.ts

@@ -0,0 +1,30 @@
+/** Helpers shared by the LLM providers. */
+import type { RunContext } from '../core/context.ts';
+import { type ErrorCode } from '../core/errors.ts';
+import type { LlmRequest } from '../core/providers.ts';
+/** Parse a JSON answer. Tolerates a code fence or text around the object. Returns undefined when nothing parses. */
+export declare function parseJsonLoose(text: string): unknown;
+/**
+ * Parse and check an endpoint URL taken from configuration or the environment.
+ * Rejects credentials in the URL and plain http to public hosts, so code and keys never travel unencrypted.
+ */
+export declare function parseEndpointUrl(value: string, setting: string): URL;
+/** Messages after the system prompt: the original request, then repair turns. Never ends with an assistant turn. */
+export declare function buildMessages(request: LlmRequest): {
+    role: 'user' | 'assistant';
+    content: string;
+}[];
+/**
+ * Record a call that the provider billed but that produced no usable answer (refused, cut off or
+ * empty). `model` is the model that was requested (the answer may name a dated snapshot instead);
+ * `local` marks a server on this machine or network. Successful calls are recorded by the caller,
+ * so every paid call appears once in the cost report.
+ */
+export declare function recordBilledFailure(ctx: RunContext, provider: string, model: string, inputTokens: number, outputTokens: number, local?: boolean): void;
+/** First part of a message, redacted and on one line, safe to put in an error. */
+export declare function safeSnippet(ctx: RunContext, text: string, max?: number): string;
+/**
+ * Read a whole response body, but stop with `code` once it is larger than `maxBytes`. A broken or
+ * hostile server could otherwise send gigabytes, and all of it would be kept in memory.
+ */
+export declare function readBodyLimited(response: Response, maxBytes: number, code: Extract<ErrorCode, 'LLM_FAILED' | 'TTS_FAILED'>, host: string): Promise<Buffer>;

package/dist/llm/shared.js

@@ -0,0 +1,115 @@
+import { MergeStoryError } from '../core/errors.js';
+import { isPrivateHostname } from '../core/net.js';
+import { budgetLlmCostUsd } from './prices.js';
+/** Parse a JSON answer. Tolerates a code fence or text around the object. Returns undefined when nothing parses. */
+export function parseJsonLoose(text) {
+    const trimmed = text.replace(/^/, '').trim();
+    const attempt = (candidate) => {
+        try {
+            return { ok: true, value: JSON.parse(candidate) };
+        }
+        catch {
+            return { ok: false };
+        }
+    };
+    const direct = attempt(trimmed);
+    if (direct.ok)
+        return direct.value;
+    const unfenced = trimmed.replace(/^```(?:json)?\s*/i, '').replace(/\s*```$/, '');
+    if (unfenced !== trimmed) {
+        const result = attempt(unfenced);
+        if (result.ok)
+            return result.value;
+    }
+    const first = unfenced.indexOf('{');
+    const last = unfenced.lastIndexOf('}');
+    if (first >= 0 && last > first) {
+        const result = attempt(unfenced.slice(first, last + 1));
+        if (result.ok)
+            return result.value;
+    }
+    return undefined;
+}
+/**
+ * Parse and check an endpoint URL taken from configuration or the environment.
+ * Rejects credentials in the URL and plain http to public hosts, so code and keys never travel unencrypted.
+ */
+export function parseEndpointUrl(value, setting) {
+    let url;
+    try {
+        url = new URL(value);
+    }
+    catch {
+        throw new MergeStoryError('CONFIG_INVALID', `${setting} is not a valid URL.`, {
+            hint: 'Use a full URL such as https://api.example.com/v1 or http://localhost:11434/v1.',
+        });
+    }
+    if (url.protocol !== 'https:' && url.protocol !== 'http:') {
+        throw new MergeStoryError('CONFIG_INVALID', `${setting} must start with https:// or http://.`);
+    }
+    if (url.username || url.password) {
+        throw new MergeStoryError('CONFIG_INVALID', `${setting} must not contain a user name or password.`, {
+            hint: 'Put keys in environment variables such as MERGESTORY_LLM_API_KEY, never in a URL.',
+        });
+    }
+    if (url.protocol === 'http:' && !isPrivateHostname(url.hostname)) {
+        throw new MergeStoryError('CONFIG_INVALID', `${setting} uses plain http to a public host.`, {
+            hint: 'Use https, or point at a server on this machine or your private network.',
+        });
+    }
+    return url;
+}
+/** Messages after the system prompt: the original request, then repair turns. Never ends with an assistant turn. */
+export function buildMessages(request) {
+    const messages = [
+        { role: 'user', content: request.prompt },
+        ...(request.history ?? []),
+    ];
+    if (messages[messages.length - 1]?.role !== 'user') {
+        throw new MergeStoryError('INTERNAL', 'The model history must end with a user turn.', {
+            hint: 'Assistant prefill is not supported by current models.',
+        });
+    }
+    return messages;
+}
+/**
+ * Record a call that the provider billed but that produced no usable answer (refused, cut off or
+ * empty). `model` is the model that was requested (the answer may name a dated snapshot instead);
+ * `local` marks a server on this machine or network. Successful calls are recorded by the caller,
+ * so every paid call appears once in the cost report.
+ */
+export function recordBilledFailure(ctx, provider, model, inputTokens, outputTokens, local = false) {
+    ctx.cost.record({
+        provider,
+        kind: 'llm',
+        model,
+        inputTokens,
+        outputTokens,
+        costUsd: budgetLlmCostUsd(provider, model, inputTokens, outputTokens, ctx, local),
+        estimated: true,
+    });
+}
+/** First part of a message, redacted and on one line, safe to put in an error. */
+export function safeSnippet(ctx, text, max = 300) {
+    return ctx.redactor.redact(text).replace(/\s+/g, ' ').trim().slice(0, max);
+}
+/**
+ * Read a whole response body, but stop with `code` once it is larger than `maxBytes`. A broken or
+ * hostile server could otherwise send gigabytes, and all of it would be kept in memory.
+ */
+export async function readBodyLimited(response, maxBytes, code, host) {
+    const chunks = [];
+    let size = 0;
+    // Leaving the loop early cancels the rest of the body.
+    for await (const chunk of response.body ?? []) {
+        size += chunk.byteLength;
+        if (size > maxBytes) {
+            throw new MergeStoryError(code, `${host} sent an answer larger than ${Math.round(maxBytes / 1_048_576)} MB.`, {
+                hint: 'Check that the address points at the right server.',
+            });
+        }
+        chunks.push(chunk);
+    }
+    return Buffer.concat(chunks);
+}
+//# sourceMappingURL=shared.js.map

package/dist/narration/assemble.d.ts

@@ -0,0 +1,36 @@
+import type { RunContext } from '../core/context.ts';
+import type { NarrationResult, Timeline } from '../core/types.ts';
+import type { RunFn } from './convert.ts';
+/** Integrated loudness the finished track is brought to, in LUFS. */
+export declare const TARGET_LUFS = -16;
+/** The true peak of the finished track stays at or below this, in dBTP. */
+export declare const TRUE_PEAK_DB = -1.5;
+export interface AssembleOptions {
+    /** Bring the finished track to the standard loudness. Default true. */
+    loudness?: boolean;
+}
+interface LoudnessStats {
+    integrated: number;
+    truePeak: number;
+    range: number;
+    threshold: number;
+    offset: number;
+}
+/** The numbers FFmpeg's loudnorm filter prints after its first pass, or null when there are none. */
+export declare function parseLoudnorm(stderr: string): LoudnessStats | null;
+/**
+ * Bring a track to TARGET_LUFS with a true peak of at most TRUE_PEAK_DB, in two passes of FFmpeg's
+ * loudnorm filter: the first measures, the second applies one steady gain (or, when that gain
+ * would push a peak over the ceiling, loudnorm's gentle dynamic mode). The track keeps its length
+ * and every sample stays where it was in time. Returns the track unchanged when it is too short or
+ * silent, is already on target, or FFmpeg is unavailable.
+ */
+export declare function normalizeLoudness(track: Int16Array, ctx: RunContext, run: RunFn): Promise<Int16Array>;
+/**
+ * Place every clip at its beat start time and write one mono 48 kHz WAV for the whole video, at
+ * the standard loudness (see normalizeLoudness). Beat start times are absolute (seconds from the
+ * start of the video). Returns null when there is no audio (silent provider and no music). Tests
+ * pass their own command runner as `run`.
+ */
+export declare function assembleNarrationTrack(narration: NarrationResult, timeline: Timeline, outPath: string, ctx: RunContext, options?: AssembleOptions, run?: RunFn): Promise<string | null>;
+export {};