@gentbajko/slopify 0.7.0 → 0.8.1

package/dist/kernel/runner/queue.js

@@ -0,0 +1,65 @@
+// One app-wide queue: no more than five calls, with lower provider limits.
+// Waiting does not start an attempt or its idle timer. FIFO among eligible calls.
+export function createProviderQueue(limitFor) {
+    const active = new Map();
+    const waiting = [];
+    let total = 0;
+    function drain() {
+        while (total < 5) {
+            const at = waiting.findIndex((w) => (active.get(w.provider) ?? 0) <
+                Math.max(1, Math.min(5, Math.floor(limitFor(w.provider)) || 1)));
+            if (at < 0)
+                return;
+            const next = waiting.splice(at, 1)[0];
+            if (!next)
+                return;
+            next.signal.removeEventListener("abort", next.cancel);
+            if (next.signal.aborted) {
+                next.cancel();
+                continue;
+            }
+            total++;
+            active.set(next.provider, (active.get(next.provider) ?? 0) + 1);
+            next.start();
+        }
+    }
+    return {
+        run: (provider, signal, work) => {
+            if (signal.aborted)
+                return Promise.reject(signal.reason);
+            return new Promise((resolve, reject) => {
+                const waiter = {
+                    provider,
+                    signal,
+                    cancel: () => {
+                        const at = waiting.indexOf(waiter);
+                        if (at >= 0)
+                            waiting.splice(at, 1);
+                        signal.removeEventListener("abort", waiter.cancel);
+                        reject(signal.reason);
+                    },
+                    start: () => {
+                        void Promise.resolve()
+                            .then(() => {
+                            signal.throwIfAborted();
+                            return work();
+                        })
+                            .then(resolve, reject)
+                            .finally(() => {
+                            total--;
+                            const left = (active.get(provider) ?? 1) - 1;
+                            if (left)
+                                active.set(provider, left);
+                            else
+                                active.delete(provider);
+                            drain();
+                        });
+                    },
+                };
+                waiting.push(waiter);
+                signal.addEventListener("abort", waiter.cancel, { once: true });
+                drain();
+            });
+        },
+    };
+}

package/dist/main.js

@@ -7,8 +7,11 @@ import { buildRegistry } from "./adapter-registry.js";
 import { alignSubtitles } from "./adapters/alignment/index.js";
 import { prepareFfmpeg } from "./adapters/ffmpeg.js";
 import { nodeRunCli } from "./adapters/llm/run-cli.js";
+import { curateRegistry } from "./catalog/registry.js";
+import { createCatalogueStore } from "./catalog/store.js";
 import { createHub } from "./edge/events/hub.js";
 import { createApp } from "./edge/http/app.js";
+import { openFolder } from "./edge/open-folder.js";
 import { createAudioPreviewStore } from "./kernel/audio-preview.js";
 import { systemClock } from "./kernel/clock.js";
 import { openDb } from "./kernel/db/index.js";
@@ -21,11 +24,13 @@ import { sqliteAttempts } from "./kernel/runner/attempt-repo.js";
 import { dependenciesOf } from "./kernel/runner/graph.js";
 import { createRunner } from "./kernel/runner/index.js";
 import { stageProviders } from "./kernel/runner/providers.js";
+import { createProviderQueue } from "./kernel/runner/queue.js";
 import { readVersion } from "./kernel/version.js";
 import { modelSources } from "./model-catalog.js";
 import { claimStage, finishStage, projectById, projectPaused, stagesOf, } from "./slices/admission/repo.js";
 import { prepareProvidedArticleSegments } from "./slices/article/provided-entries.js";
 import { runArticle } from "./slices/article/run.js";
+import { pumpQueue, queueWaiting } from "./slices/batch/index.js";
 import { runImages } from "./slices/images/run.js";
 import { runNarration } from "./slices/narration/run.js";
 import { runResearch } from "./slices/research/run.js";
@@ -78,13 +83,14 @@ export async function boot(config) {
             log,
             post: httpPostEvents(collectorEndpoint(process.env), collectorTimeoutMs),
         }, flushDelayMs);
-        const registry = buildRegistry({
+        const catalogue = createCatalogueStore({ dataDir: paths.dataDir, fetch: globalThis.fetch });
+        const registry = curateRegistry(buildRegistry({
             db,
             fetch: globalThis.fetch,
             spawn: nodeRunCli,
             clock,
             probe: nodeCliProbe,
-        });
+        }), catalogue);
         const audioPreviews = createAudioPreviewStore();
         const runner = wire({
             db,
@@ -96,6 +102,7 @@ export async function boot(config) {
             telemetry,
             flusher,
             registry,
+            catalogue,
             ffmpeg,
             audioPreviews,
         });
@@ -163,6 +170,7 @@ export async function boot(config) {
             },
         });
         const app = createApp({
+            openFolder,
             db,
             paths,
             hub,
@@ -170,6 +178,7 @@ export async function boot(config) {
             updater,
             audioPreviews,
             ...modelSources(registry),
+            catalogue,
             clock,
             ids,
             log,
@@ -179,6 +188,20 @@ export async function boot(config) {
             probe: nodeCliProbe,
         });
         const server = await listen(app, config, log);
+        const queueTimer = setInterval(() => {
+            const release = updater.beginMutation();
+            if (!release)
+                return;
+            try {
+                pumpQueue(updateDb, runner);
+            }
+            catch {
+                log.write("error", "batch.queue", { detail: "The batch queue could not advance." });
+            }
+            finally {
+                release();
+            }
+        }, 1000);
         listeningPort = portOf(server) ?? config.port;
         // Whatever last run left queued goes out at start. Nothing waits for
         // it, and an unreachable collector costs one refused socket.
@@ -188,6 +211,7 @@ export async function boot(config) {
         let stopActivation = () => { };
         shutdown = () => {
             stopping ??= (async () => {
+                clearInterval(queueTimer);
                 stopActivation();
                 audioPreviews.close();
                 try {
@@ -221,7 +245,7 @@ export async function boot(config) {
         throw error;
     }
 }
-function wire({ audioPreviews, db, paths, clock, ids, log, hub, telemetry, flusher, registry, ffmpeg, }) {
+function wire({ audioPreviews, db, paths, clock, ids, log, hub, telemetry, flusher, registry, catalogue, ffmpeg, }) {
     // A stage counts what it did and the queue is flushed after each new event. `record`
     // swallows its own failures, so this can neither fail a stage nor widen what leaves the
     // machine - the payload allow-list is checked inside it.
@@ -237,11 +261,17 @@ function wire({ audioPreviews, db, paths, clock, ids, log, hub, telemetry, flush
     const writing = { db, paths, ids, clock, log, count };
     // A stage slice is handed the wrapped calls, never the registry: every provider call
     // it makes is already inside the retry policy (kernel/runner/providers.ts).
-    const providers = { registry, attempts: sqliteAttempts(db, ids), clock, log };
+    const providers = {
+        registry,
+        attempts: sqliteAttempts(db, ids),
+        clock,
+        log,
+        queue: createProviderQueue((provider) => catalogue.read().providers[provider]?.maxConcurrent ?? 1),
+    };
     return createRunner({
         stages: {
             stagesOf: (projectId) => stagesOf(db, projectId),
-            paused: (projectId) => projectPaused(db, projectId),
+            paused: (projectId) => projectPaused(db, projectId) || queueWaiting(db, projectId),
             dependenciesOf: (projectId, kind) => {
                 const project = projectById(db, projectId);
                 return project === undefined ? [] : dependenciesOf(kind, project.config.sources);
@@ -257,7 +287,14 @@ function wire({ audioPreviews, db, paths, clock, ids, log, hub, telemetry, flush
             audio: async (context) => {
                 const wrapped = stageProviders(providers, context);
                 await prepareProvidedArticleSegments(writing, context, wrapped);
-                await runNarration({ ...video, audioPreviews }, context, wrapped);
+                await runNarration({
+                    ...video,
+                    audioPreviews,
+                    maxCharacters: (provider, model) => {
+                        const entry = catalogue.models(provider, "tts").find((m) => m.id === model);
+                        return entry && "tts" in entry ? entry.tts.maxCharacters : 4000;
+                    },
+                }, context, wrapped);
             },
             images: (context) => runImages(writing, context, stageProviders(providers, context)),
             thumbnail: (context) => runThumbnail(writing, context, stageProviders(providers, context)),

package/dist/slices/admission/repo.js

@@ -1,9 +1,14 @@
 import { z } from "zod";
 import { stageKinds, stageStates } from "../../kernel/pipeline.js";
+import { thinkingModes } from "../../kernel/ports/llm.js";
 import { chunkModes } from "../narration/chunk.js";
 import { subtitleConfigSchema } from "../subtitles/model.js";
 import { entryModes, formats, stageSources } from "./model.js";
-const providerChoice = z.object({ provider: z.string(), model: z.string() });
+const providerChoice = z.object({
+    provider: z.string(),
+    model: z.string(),
+    thinking: z.enum(thinkingModes).optional(),
+});
 const entryChoice = z.object({ name: z.string(), mode: z.enum(entryModes) });
 // The shape Play posts and the shape `projects.config` holds, in one place: the second
 // is the first plus the rendered prompt texts.
@@ -38,7 +43,13 @@ export const runDraftSchema = z.object({
     }),
     // Optional until Play carries the control; unknown keys are stripped by this schema, so
     // a mode not listed here would never reach the audio stage.
-    chunking: z.object({ mode: z.enum(chunkModes), words: z.number().optional() }).optional(),
+    chunking: z
+        .object({
+        mode: z.enum(chunkModes),
+        words: z.number().optional(),
+        characters: z.number().int().min(1).max(1000000).optional(),
+    })
+        .optional(),
     silenceGapSeconds: z.number(),
     subtitles: subtitleConfigSchema.optional(),
 });

package/dist/slices/admission/start.js

@@ -13,7 +13,7 @@ export function initialState(source) {
 }
 // The project row, its six stages and the provided content all land together or not at
 // all. The caller ticks the runner after this returns, never inside it.
-export function startRun(deps, draft, rendered) {
+export function startRun(deps, draft, rendered, retainStaged = false) {
     const id = deps.ids.next();
     const at = deps.clock.now().toISOString();
     const config = { ...draft, rendered };
@@ -49,14 +49,14 @@ export function startRun(deps, draft, rendered) {
         for (const stage of stages) {
             insertStage(deps.db, stage);
         }
-        attachProvided(deps, id, draft, moved);
+        attachProvided(deps, id, draft, moved, retainStaged);
     });
-    for (const source of moved) {
+    for (const source of retainStaged ? [] : moved) {
         dropStagedSource(deps, source);
     }
     return { project, stages };
 }
-function attachProvided(deps, projectId, draft, collected) {
+function attachProvided(deps, projectId, draft, collected, retainStaged) {
     const { sources, provided } = draft;
     if (sources.research === "provide" && provided.research !== undefined) {
         storeText(deps, {
@@ -73,24 +73,25 @@ function attachProvided(deps, projectId, draft, collected) {
         storeArticleText(deps, { projectId, markdown: provided.article.trim() });
     }
     if (sources.audio === "provide") {
-        attach(deps, projectId, "audio", provided.audio, "audio_body", collected);
+        attach(deps, projectId, "audio", provided.audio, "audio_body", collected, retainStaged);
     }
     if (sources.thumbnail === "provide") {
-        attach(deps, projectId, "thumbnail", provided.thumbnail, "thumbnail", collected);
+        attach(deps, projectId, "thumbnail", provided.thumbnail, "thumbnail", collected, retainStaged);
     }
     if (sources.images === "provide") {
         // Slideshow order is the order the user left the list in.
         for (const [index, stagedFileId] of (provided.images ?? []).entries()) {
-            attach(deps, projectId, "images", stagedFileId, "image", collected, index + 1);
+            attach(deps, projectId, "images", stagedFileId, "image", collected, retainStaged, index + 1);
         }
     }
 }
-function attach(deps, projectId, kind, stagedFileId, role, collected, index) {
+function attach(deps, projectId, kind, stagedFileId, role, collected, retainStaged, index) {
     if (stagedFileId === undefined) {
         throw new Error(`the ${kind} stage is provided but carries no staged file`);
     }
     const result = attachStagedFile(deps, {
         stagedFileId,
+        retainStaged,
         projectId,
         role,
         ...(index === undefined ? {} : { index }),

package/dist/slices/article/continuation.js

@@ -43,7 +43,13 @@ export async function writeArticle(providers, choice, brief, onDelta) {
             onDelta(event.text);
         }
     };
-    let answer = await providers.llm({ provider: choice.provider, model: choice.model, messages: base, check: written }, stream);
+    let answer = await providers.llm({
+        provider: choice.provider,
+        model: choice.model,
+        ...(choice.thinking === undefined ? {} : { thinking: choice.thinking }),
+        messages: base,
+        check: written,
+    }, stream);
     const pieces = [answer.text];
     let tokens = plusUsage(noTokens, answer.usage);
     for (let n = 1; truncated(answer) && n <= continuationLimit; n += 1) {
@@ -52,6 +58,7 @@ export async function writeArticle(providers, choice, brief, onDelta) {
         answer = await providers.llm({
             provider: choice.provider,
             model: choice.model,
+            ...(choice.thinking === undefined ? {} : { thinking: choice.thinking }),
             messages,
             // The last continuation allowed is the one that has to end the article: a fourth
             // truncation is a failed attempt, which is the wrapper's to retry. The

package/dist/slices/article/segments.js

@@ -18,6 +18,7 @@ export async function writeSegment(providers, choice, config, category, article,
     const answer = await providers.llm({
         provider: choice.provider,
         model: choice.model,
+        ...(choice.thinking === undefined ? {} : { thinking: choice.thinking }),
         messages,
         check: (given) => given.text.trim() === "" ? `the ${category} answered with nothing` : undefined,
     });

package/dist/slices/batch/index.js

@@ -0,0 +1,82 @@
+import { z } from "zod";
+import { transact } from "../../kernel/db/tx.js";
+import { derive } from "../../kernel/runner/graph.js";
+import { projectPaused, stagesOf } from "../admission/repo.js";
+import { startRun } from "../admission/start.js";
+import { stagingPath } from "../storage/layout.js";
+import { deleteStagedFile, stagedFileById } from "../storage/repo.js";
+import { dropStagedSource } from "../storage/staging.js";
+const queueRow = z.object({
+    projectId: z.string(),
+    batchId: z.string(),
+    position: z.number(),
+    state: z.enum(["queued", "active", "finished"]),
+});
+export function queueEntries(db, batchId) {
+    return db
+        .prepare(`SELECT project_id AS projectId, batch_id AS batchId, position, state
+    FROM project_queue ${batchId === undefined ? "WHERE state != 'finished'" : "WHERE batch_id = ?"}
+    ORDER BY position`)
+        .all(...(batchId === undefined ? [] : [batchId]))
+        .map((row) => queueRow.parse(row));
+}
+export function queueWaiting(db, projectId) {
+    return (db
+        .prepare("SELECT 1 FROM project_queue WHERE project_id = ? AND state = 'queued'")
+        .get(projectId) !== undefined);
+}
+export function batchExists(db, id) {
+    return db.prepare("SELECT 1 FROM batches WHERE id = ?").get(id) !== undefined;
+}
+export function enqueueBatch(deps, batchId, runs) {
+    if (batchExists(deps.db, batchId))
+        return queueEntries(deps.db, batchId);
+    const sources = new Set();
+    transact(deps.db, () => {
+        deps.db
+            .prepare("INSERT INTO batches(id, created_at) VALUES (?, ?)")
+            .run(batchId, deps.clock.now().toISOString());
+        const used = new Set();
+        for (const { draft, rendered } of runs) {
+            const { project } = startRun(deps, draft, rendered, true);
+            deps.db
+                .prepare("INSERT INTO project_queue(project_id, batch_id) VALUES (?, ?)")
+                .run(project.id, batchId);
+            if (draft.sources.audio === "provide" && draft.provided.audio)
+                used.add(draft.provided.audio);
+            if (draft.sources.thumbnail === "provide" && draft.provided.thumbnail)
+                used.add(draft.provided.thumbnail);
+            if (draft.sources.images === "provide")
+                for (const id of draft.provided.images ?? [])
+                    used.add(id);
+        }
+        for (const id of used) {
+            const file = stagedFileById(deps.db, id);
+            if (file)
+                sources.add(stagingPath(deps.paths, file.path));
+            deleteStagedFile(deps.db, id);
+        }
+    });
+    for (const source of sources)
+        dropStagedSource(deps, source);
+    return queueEntries(deps.db, batchId);
+}
+// Only one batch video runs at once. A paused item holds its place; a failed or
+// canceled item releases the next video once its provider calls have drained.
+export function pumpQueue(db, runner) {
+    for (const entry of queueEntries(db)) {
+        const stages = stagesOf(db, entry.projectId);
+        const status = derive(stages, projectPaused(db, entry.projectId));
+        if (runner.hasInflight?.(entry.projectId))
+            return;
+        if (["done", "failed", "canceled"].includes(status)) {
+            db.prepare("UPDATE project_queue SET state = 'finished' WHERE project_id = ?").run(entry.projectId);
+            continue;
+        }
+        if (status === "paused")
+            return;
+        db.prepare("UPDATE project_queue SET state = 'active' WHERE project_id = ?").run(entry.projectId);
+        runner.tick(entry.projectId);
+        return;
+    }
+}

package/dist/slices/control/index.js

@@ -1,6 +1,7 @@
 import { transact } from "../../kernel/db/tx.js";
 import { derive, satisfied } from "../../kernel/runner/graph.js";
 import { finishStage, projectById, resetStage, setProjectPaused, stagesOf, updateProjectConfig, } from "../admission/repo.js";
+import { sameChunking } from "../narration/chunk.js";
 import { clearUnfinishedAudio } from "../reruns/index.js";
 import { providers as providerCatalog } from "../settings/model.js";
 import { hasKey, listVoices } from "../settings/repo.js";
@@ -137,13 +138,15 @@ export function changeProviders(deps, id, changes) {
             (changes.audio.provider !== project.config.audio?.provider ||
                 changes.audio.model !== project.config.audio?.model ||
                 changes.audio.voice !== project.config.audio?.voice);
+        const chunkingChanged = changes.chunking !== undefined && !sameChunking(changes.chunking, project.config.chunking);
         const orphaned = transact(deps.db, () => {
-            const files = audioChanged ? clearUnfinishedAudio(deps, id) : [];
+            const files = audioChanged || chunkingChanged ? clearUnfinishedAudio(deps, id) : [];
             updateProjectConfig(deps.db, id, {
                 ...project.config,
                 ...(changes.llm === undefined ? {} : { llm: changes.llm }),
                 ...(changes.audio === undefined ? {} : { audio: changes.audio }),
                 ...(changes.images === undefined ? {} : { images: changes.images }),
+                ...(changes.chunking === undefined ? {} : { chunking: changes.chunking }),
             }, deps.clock.now().toISOString());
             return files;
         });

package/dist/slices/control/providers.js

@@ -1,8 +1,11 @@
 import { z } from "zod";
+import { thinkingModes } from "../../kernel/ports/llm.js";
+import { chunkModes } from "../narration/chunk.js";
 const choice = z
     .object({
     provider: z.string().trim().min(1).max(200),
     model: z.string().trim().min(1).max(200),
+    thinking: z.enum(thinkingModes).optional(),
 })
     .strict();
 export const providerChangesSchema = z
@@ -10,6 +13,14 @@ export const providerChangesSchema = z
     llm: choice.optional(),
     audio: choice.extend({ voice: z.string().trim().min(1).max(200) }).optional(),
     images: choice.optional(),
+    chunking: z
+        .object({
+        mode: z.enum(chunkModes),
+        words: z.number().int().min(1).max(10000).optional(),
+        characters: z.number().int().min(1).max(1000000).optional(),
+    })
+        .strict()
+        .optional(),
 })
     .strict()
     .refine((value) => Object.keys(value).length > 0, "Pick at least one provider to update.");
@@ -53,9 +64,15 @@ export async function validateProviderChanges(changes, current) {
         if (current.allowsCustomModels?.(picked.provider) === true)
             continue;
         const models = await current.modelsFor(picked.provider, families[key]);
-        if (!models.some((model) => model.id === picked.model)) {
+        const model = models.find((model) => model.id === picked.model);
+        if (!model) {
             fields.push({ field: `${key}.model`, message: "Choose a model supported by this provider." });
         }
+        else if (key === "llm" &&
+            picked.thinking &&
+            !model.thinkingModes?.includes(picked.thinking)) {
+            fields.push({ field: `${key}.thinking`, message: "Choose a supported thinking setting." });
+        }
     }
     return fields;
 }

package/dist/slices/estimate/index.js

@@ -0,0 +1,81 @@
+export function estimateRun(draft, rendered, expectedWords, catalogue) {
+    const rows = [];
+    const model = (family, choice) => choice
+        ? catalogue?.models(choice.provider, family).find((m) => m.id === choice.model)
+        : undefined;
+    const llm = model("llm", draft.llm);
+    const tts = model("tts", draft.audio);
+    const image = model("image", draft.images);
+    const generatedArticle = draft.sources.article === "generate";
+    const articleChars = generatedArticle ? expectedWords * 6 : (draft.provided.article?.length ?? 0);
+    const promptChars = Object.values(rendered).reduce((sum, value) => sum + value.length, 0);
+    const row = (stage, amount, detail, variable = false) => {
+        rows.push({
+            stage,
+            low: amount === undefined ? null : amount * (variable ? 0.5 : 1),
+            high: amount === undefined ? null : amount * (variable ? 1.5 : 1),
+            detail,
+        });
+    };
+    const textCost = (input, output) => {
+        const p = llm?.pricing;
+        return p?.inputPerMillionTokens === undefined || p.outputPerMillionTokens === undefined
+            ? undefined
+            : ((input / 4) * p.inputPerMillionTokens + (output / 4) * p.outputPerMillionTokens) / 1000000;
+    };
+    const textNote = llm?.pricing.note ??
+        "CLI subscription or model pricing is unavailable; usage may be billed by your account.";
+    if (draft.sources.research === "generate")
+        row("Research", textCost(promptChars + 6000, 12000), `Assumes about 2,000 words of notes; web search fees are excluded. ${textNote}`, true);
+    else
+        row("Research", 0, "Provided or off; no generation charge.");
+    if (generatedArticle)
+        row("Article", textCost(promptChars + (draft.sources.research === "generate" ? 12000 : 0), articleChars), `${expectedWords.toLocaleString()} expected words. ${textNote}`, true);
+    else
+        row("Article", 0, "Provided article; no generation charge.");
+    if (draft.intro?.mode === "llm" || draft.outro?.mode === "llm")
+        row("Intro / outro text", textCost(promptChars + articleChars, 2400), textNote, true);
+    if (draft.sources.audio === "generate") {
+        const extras = ["intro", "outro"].reduce((n, key) => n + (rendered[key]?.length ?? 0), 0);
+        const llmExtras = (draft.intro?.mode === "llm" ? 1200 : 0) + (draft.outro?.mode === "llm" ? 1200 : 0);
+        const chars = articleChars + extras + llmExtras;
+        const p = tts?.pricing;
+        const amount = p?.perMillionCharacters === undefined
+            ? p?.perMinute === undefined
+                ? undefined
+                : (chars / 6 / 150) * p.perMinute
+            : (chars / 1000000) * p.perMillionCharacters;
+        row("Narration", amount, `About ${chars.toLocaleString()} characters. ${p?.note ?? "Account pricing is unknown."}`, generatedArticle || llmExtras > 0 || p?.perMinute !== undefined);
+    }
+    else
+        row("Narration", 0, "Provided or off; no generation charge.");
+    const images = draft.sources.images === "generate" ? draft.imagePrompts.reduce((n, p) => n + p.number, 0) : 0;
+    row("Images", images === 0
+        ? 0
+        : image?.pricing.perImage === undefined
+            ? undefined
+            : images * image.pricing.perImage, images === 0
+        ? "Provided or off."
+        : `${images} images. ${image?.pricing.note ?? "Model or account pricing is unknown."}`);
+    const thumbnail = ["from_prompt", "prompt_by_llm"].includes(draft.sources.thumbnail);
+    row("Thumbnail", thumbnail ? image?.pricing.perImage : 0, thumbnail
+        ? (image?.pricing.note ?? "Model or account pricing is unknown.")
+        : "Provided or off.");
+    if (draft.sources.thumbnail === "prompt_by_llm")
+        row("Thumbnail prompt", textCost(promptChars + articleChars, 1200), textNote, true);
+    row("Export / subtitles", 0, "Local processing; no API fee.");
+    return {
+        currency: "USD",
+        rows,
+        expectedWords,
+        catalogueDate: catalogue?.status().updatedAt ?? null,
+        low: rows.reduce((n, r) => n + (r.low ?? 0), 0),
+        high: rows.reduce((n, r) => n + (r.high ?? 0), 0),
+        unknown: rows.filter((r) => r.low === null).length,
+        assumptions: [
+            "Planning estimate, not a spending limit. Generated lengths use a ±50% range; actual output can exceed it.",
+            "Assumes roughly 6 characters per word, 4 characters per token, and 150 spoken words per minute.",
+            "Retries, extra reasoning tokens, web tools, taxes, discounts and included credits are excluded. Unknown charges are not counted as zero.",
+        ],
+    };
+}

package/dist/slices/narration/chunk.js

@@ -1,12 +1,6 @@
-// The run's chunking choice: whole text is one request, per paragraph is one request per
-// paragraph, and every ~N words is consecutive chunks each ending at the last sentence
-// boundary at or before N words, N defaulting to 500.
-//
-// Pure, and the only place the rule lives. Chunking sits in the functional core beside
-// substitution and the render plan, so it is testable with no I/O and `run.ts` does nothing
-// but call it.
-export const chunkModes = ["whole", "paragraph", "words"];
+export const chunkModes = ["whole", "paragraph", "words", "characters"];
 export const defaultChunkWords = 500;
+export const defaultChunkCharacters = 3000;
 // A run created before Play carried the control sends the whole text as one request,
 // which is the first case and the one that adds nothing the user did not ask for.
 export const defaultChunking = { mode: "whole" };
@@ -20,7 +14,9 @@ export function chunkNarration(text, chunking) {
         case "paragraph":
             return nonEmpty(text.split(paragraphBreak));
         case "words":
-            return wordRuns(text, chunking.words ?? defaultChunkWords);
+            return sentenceRuns(text, chunking.words ?? defaultChunkWords, wordsIn);
+        case "characters":
+            return sentenceRuns(text, chunking.characters ?? defaultChunkCharacters, (part) => Array.from(part.trim()).length);
     }
 }
 // What "N words" counts: runs of non-space. Exported because it is half of the rule -
@@ -28,29 +24,32 @@ export function chunkNarration(text, chunking) {
 export function wordsIn(text) {
     return text.split(/\s+/).filter((word) => word !== "").length;
 }
-function wordRuns(text, budget) {
-    // A budget below one word would end every chunk before it started; one sentence is the
-    // floor because the rule never cuts inside a sentence.
+export function sameChunking(left, right) {
+    const a = left ?? defaultChunking;
+    const b = right ?? defaultChunking;
+    if (a.mode !== b.mode)
+        return false;
+    if (a.mode === "words")
+        return (a.words ?? defaultChunkWords) === (b.words ?? defaultChunkWords);
+    if (a.mode === "characters")
+        return (a.characters ?? defaultChunkCharacters) === (b.characters ?? defaultChunkCharacters);
+    return true;
+}
+function sentenceRuns(text, budget, measure) {
     const limit = Math.max(1, Math.floor(budget));
     const chunks = [];
     let current = "";
-    let count = 0;
     for (const sentence of sentences(text)) {
-        const words = wordsIn(sentence);
-        // The last sentence boundary at or before N words: the sentence that would push the count
-        // past the budget starts the next chunk instead of being split.
-        if (count > 0 && count + words > limit) {
+        // Measure the joined text so spaces between sentences count toward a character budget.
+        if (current.trim() && measure(current + sentence) > limit) {
             chunks.push(current);
             current = "";
-            count = 0;
         }
         current += sentence;
-        count += words;
     }
     chunks.push(current);
-    // A single sentence longer than the budget lands here whole, on its own: a cut inside a
-    // clause would be an audible pause the writer never wrote. The provider's own per-request
-    // limit is what refuses it, as an error on the stage.
+    // Like word chunking, a sentence longer than the budget stays whole on its own.
+    // The provider-specific planning layer applies any hard request limit afterwards.
     return nonEmpty(chunks);
 }
 // ceiling: segmented as English. `Intl.Segmenter` is the platform's own sentence breaker