@avocadostudio-ai/orchestrator-core 0.3.2 → 0.4.0

package/dist/chat/planner-types.d.ts

@@ -87,6 +87,21 @@ export type CommonGeneratePlanArgs = {
     thinking?: {
         effort: PlannerEffort;
     };
+    /**
+     * Multiplier on the planner's output-token budget (Anthropic). The pipeline
+     * raises it on a retry that followed a `max_tokens` truncation, so the next
+     * attempt has room the previous one lacked. Ignored by other providers.
+     */
+    outputTokenScale?: number;
+    /**
+     * Restrict the block-schema contracts sent to the model to these types.
+     *
+     * Set by the translation chunker: a chunk holding a Hero and a CTA cannot
+     * legitimately emit an op for a Gallery, so shipping every block's contract to
+     * every chunk repeats the largest part of the request for nothing. Leave unset
+     * anywhere the model may reference a type that isn't already on the page.
+     */
+    contractBlockTypeAllowlist?: string[];
 };
 /**
  * Effort levels accepted by the Messages API `output_config.effort` field on the

package/dist/chat/planner-types.js

@@ -29,7 +29,7 @@ const openAIPlanner = {
     },
     async generatePlan(args) {
         // OpenAI doesn't yet support Anthropic-style thinking events — drop them.
-        const { onStatusUpdate: _s, onImageProgress: _i, log: _l, onThinking: _t, thinking: _th, ...rest } = args;
+        const { onStatusUpdate: _s, onImageProgress: _i, log: _l, onThinking: _t, thinking: _th, outputTokenScale: _o, ...rest } = args;
         return generatePlanWithOpenAI(rest);
     },
 };
@@ -44,7 +44,7 @@ const geminiPlanner = {
     supportsNativeTools: true,
     parseIntent: parseIntentWithGemini,
     async generatePlan(args) {
-        const { onThinking: _t, thinking: _th, ...rest } = args;
+        const { onThinking: _t, thinking: _th, outputTokenScale: _o, ...rest } = args;
         return generatePlanWithGemini(rest);
     },
 };

package/dist/chat/planner.d.ts

@@ -45,6 +45,16 @@ export declare function buildPlannerSchemaContext(args: {
     forceFullContracts?: boolean;
     componentsManifest?: BlockManifest;
     effectiveBlockTypes?: string[];
+    /**
+     * Hard ceiling on which block contracts may be sent, whatever mode is chosen.
+     *
+     * A page-wide translation asks for `full` contracts because it edits every
+     * block on the page — but a *chunk* of one edits only the blocks it holds, and
+     * shipping all eighteen contracts to each of six chunks repeats ~9 KB six times
+     * for no gain. Set only where the caller can guarantee the model cannot
+     * legitimately reference a type outside the list.
+     */
+    contractBlockTypeAllowlist?: string[];
 }): {
     payload: PlannerSchemaContextPayload;
     meta: PlannerSchemaContextMeta;
@@ -136,6 +146,8 @@ export declare function generatePlanWithOpenAI(args: {
     client?: PlannerOpenAIClient;
     siteContextBlock?: string | null;
     forceFullSchemaContracts?: boolean;
+    /** Restrict block-schema contracts to these types. See CommonGeneratePlanArgs. */
+    contractBlockTypeAllowlist?: string[];
     componentsManifest?: BlockManifest;
     lightweight?: boolean;
     signal?: AbortSignal;

package/dist/chat/planner.js

@@ -191,13 +191,26 @@ function buildContractsForMode(args) {
         payload.pageMetaContract = pageMetaContractSummary();
     return payload;
 }
+/** Narrow the contract set to an allowlist, when the caller supplied a non-empty one. */
+function restrictContracts(allContracts, allowlist) {
+    if (!allowlist || allowlist.length === 0)
+        return allContracts;
+    const restricted = {};
+    for (const type of allowlist) {
+        if (type in allContracts)
+            restricted[type] = allContracts[type];
+    }
+    // An allowlist that matches nothing is a caller bug, not an instruction to
+    // send the model a page it has no schema for — fall back to everything.
+    return Object.keys(restricted).length > 0 ? restricted : allContracts;
+}
 export function buildPlannerSchemaContext(args) {
     const strictJsonEnabled = isStrictJsonResponseEnabled();
     const targetBlockTypes = pickTargetBlockTypes({ message: args.message, contextPack: args.contextPack });
     const includePageMetaContract = /\b(seo|meta|metadata|og\s*image|open\s*graph|description|structured\s*data|schema\.org)\b/i.test(args.message) || /\d{2,3}\s*char/i.test(args.message);
     const knownTypes = args.effectiveBlockTypes
         ?? (args.componentsManifest ? args.componentsManifest.blocks.map(c => c.type) : Object.keys(blockSchemas));
-    const allContracts = blockContractsSummary(args.componentsManifest);
+    const allContracts = restrictContracts(blockContractsSummary(args.componentsManifest), args.contractBlockTypeAllowlist);
     if (!isAdaptiveSchemaContextEnabled()) {
         const payload = args.legacyIncludeContracts
             ? {
@@ -1162,7 +1175,8 @@ export async function generatePlanWithOpenAI(args) {
             pageWideTranslation,
             legacyIncludeContracts: includeContracts,
             forceFullContracts: args.forceFullSchemaContracts,
-            componentsManifest: args.componentsManifest
+            componentsManifest: args.componentsManifest,
+            contractBlockTypeAllowlist: args.contractBlockTypeAllowlist
         });
     const user = {
         request: args.message,

package/dist/chat/prompts.d.ts

@@ -65,3 +65,8 @@ export declare function buildPlannerSystemPromptSegments(opts: PlannerPromptOpti
     stable: string;
     dynamic: string;
 };
+/**
+ * The subset of the corrections above that is true of THIS site's catalogue.
+ * Returns one prompt line per surviving correction, or an empty array.
+ */
+export declare function propNameCorrectionLines(effectiveBlockTypes: string[]): string[];

package/dist/chat/prompts.js

@@ -4,6 +4,7 @@
  * Eliminates duplication between OpenAI and Anthropic planner modules.
  * Provider-specific extensions are injected via the `provider` option.
  */
+import { blockAcceptsProp, blockListItemAcceptsKey } from "@avocadostudio-ai/shared";
 // ---------------------------------------------------------------------------
 // Intent parser
 // ---------------------------------------------------------------------------
@@ -154,7 +155,13 @@ const ANTHROPIC_IMAGE_TOOL_LINES = [
     "When using image.generate, write the returned imageUrl into the relevant imageUrl field and set imageAlt from the returned alt text.",
 ];
 const BLOCK_NAME_PRIVACY_OPENAI = "Never mention internal block IDs (b_hero_*, b_featuregrid_*, etc.), prop names (imageUrl, imageAlt), or system settings in summary_for_user or change_log. Use human-friendly descriptions instead (e.g. 'Update the Hero image' not 'Update imageUrl on b_hero_123').";
-const BLOCK_NAME_PRIVACY_ANTHROPIC = "Never mention internal block IDs (b_hero_*, b_featuregrid_*, etc.), prop names (imageUrl, imageAlt), or system settings in summary_for_user, change_log, or suggested_next_actions. Also avoid raw block type names like 'RichText', 'FeatureGrid', 'CardGrid', 'FAQAccordion' — use natural descriptions instead: 'text section', 'features grid', 'card grid', 'FAQ section'. Exception: 'Hero', 'CTA', and 'Testimonials' are fine as-is since users understand these terms.";
+/*
+ * Stated as a rule about identifiers rather than as a list of our block names:
+ * a site with its own catalogue has its own CamelCase type names, and an
+ * allowlist of ours neither covers them nor describes them. The test is whether
+ * the word reads as English to someone who has never seen the schema.
+ */
+const BLOCK_NAME_PRIVACY_ANTHROPIC = "Never mention internal block IDs (b_hero_*, b_featuregrid_*, etc.), prop names (imageUrl, imageAlt), or system settings in summary_for_user, change_log, or suggested_next_actions. Also avoid raw block type names — they are schema identifiers, not words users know. Describe the section by what it is: a type named 'RichText' is a 'text section', 'FeatureGrid' a 'features grid', 'FAQAccordion' an 'FAQ section', 'heroSplit' or 'PageHeader' just 'the hero' or 'the page header'. The test is whether the word reads as ordinary English rather than as a name from a schema; where it does — 'Hero', 'CTA', 'Testimonials', 'Gallery' — using it as-is is fine.";
 // ---------------------------------------------------------------------------
 // Full planner prompt — composed from section builders.
 // Each section becomes a ## HEADER in the emitted prompt so the LLM can
@@ -168,16 +175,18 @@ function joinSections(sections) {
 }
 function buildFullPlannerSegments(opts) {
     const hasNativeTools = opts.provider === "anthropic" || opts.provider === "gemini";
-    // Stable sections — depend only on provider (fixed for a given planner) and
-    // static rule constants. These bytes are identical across requests and are
-    // the part Anthropic caches. IMAGES is here too; it depends on hasNativeTools
-    // but that's stable per provider.
+    // Stable sections — the part Anthropic caches. "Stable" means stable across
+    // *requests*, not constant: IMAGES varies with hasNativeTools and OPERATION
+    // CATALOG with the site's block catalogue, and both are fixed for a given
+    // provider and site. Two sites with different catalogues get two cache
+    // entries, which is the correct trade — a prompt that tells the model the
+    // wrong prop names caches beautifully and edits the wrong field.
     const stableSections = [
         sectionRole(),
         sectionOutputContract(),
         sectionIntentDecisionTree(),
         sectionVoice(opts, hasNativeTools),
-        sectionOperationCatalog(),
+        sectionOperationCatalog(opts),
         sectionSchemaDiscipline(),
         sectionImages(hasNativeTools),
     ];
@@ -241,14 +250,88 @@ function sectionVoice(opts, hasNativeTools) {
     if (hasNativeTools) {
         lines.push("For edit_plan intent: summary_for_user must be ONE short sentence (max ~20 words) describing what the plan will do. Do NOT elaborate, explain why, or describe the content being added — let change_log carry the detail. Bad: 'Updated the hero heading with a punchier tone.' Good: 'Will add a **text section** about blueberry varieties after the features grid.'", "change_log coverage is MANDATORY: emit exactly one change_log entry per op, in the same order as ops[], describing what that specific op does. If ops has N entries, change_log must have N entries — never cluster multiple ops into one entry, never skip an op, never leave an op undescribed. The user reads change_log to decide whether to approve; a missing entry is a silent bait-and-switch.", "change_log entries should add specific detail NOT already in summary_for_user — e.g. list the actual content, items, or values being set. Do not paraphrase the summary.");
     }
-    lines.push("In summary_for_user, use simple markdown for readability: **bold** for key terms or labels, and bullet lists (- item) when listing multiple items, recommendations, or observations. Keep it scannable — avoid walls of text.", "When rewriting text, return plain text unless the prop is a rich-text prop (see below) or the user explicitly asks for markdown formatting. Do not wrap the entire rewrite in **bold** markers.", RULE_RICH_TEXT_PROPS, "For copy in German or similar long-compound languages, insert soft hyphen opportunities in long compounds where helpful for responsive line wrapping. Use the Unicode soft hyphen character (U+00AD), never HTML entities like ­ or ­.", opts.provider !== "openai" ? BLOCK_NAME_PRIVACY_ANTHROPIC : BLOCK_NAME_PRIVACY_OPENAI, "", "### suggested_next_actions", "2-4 short imperative phrases the user could type next (max 6 words each). Each MUST be a logical follow-up to the specific change just made — not a generic action. NEVER suggest 'Open /X' or any navigation to a page that the current plan is creating, duplicating, or otherwise still pending — the page won't exist until the user approves the plan, and there is no special navigation chip handler (suggestions are sent verbatim as the next chat command). Suggest plan refinements instead (e.g. 'Use a punchier hero headline', 'Add a card grid for spotlights', 'Drop the FAQ section'). Ask yourself: 'what would the user likely want to do next given THIS edit?' When the plan contains exactly one update_props op that changes a text field, the first 1-2 suggestions MUST be refinements of that same field (e.g. 'Make it shorter', 'Try a bolder tone', 'Revert to previous'). For example, after rewriting stats labels, suggest refining the same section ('Make the numbers bigger', 'Add a stat about X') — not unrelated actions like 'Change title' or 'Add a Testimonials section'. For needs_clarification, suggest the most likely concrete answers. Omit suggested_next_actions entirely if no contextual follow-up is obvious. Every suggestion must be an action the user can perform inside this editor — restricted to the block types in blockContracts / blockCatalogue (Hero, FeatureGrid, Testimonials, FAQAccordion, CTA, Card, CardGrid, RichText, TwoColumn, Banner, Carousel, Embed, Footer, Gallery, Quote, SiteHeader, Stats, Table, Tabs, Video) or SEO/site-config edits. NEVER suggest unsupported features: no forms, no email capture, no contact forms, no subscribe boxes, no newsletter signups, no popups/modals, no chat widgets, no live video, no payment/checkout — these require custom code the editor cannot produce. Never suggest actions outside the editor's scope such as A/B testing, analytics, performance monitoring, user research, or marketing strategy.");
+    lines.push("In summary_for_user, use simple markdown for readability: **bold** for key terms or labels, and bullet lists (- item) when listing multiple items, recommendations, or observations. Keep it scannable — avoid walls of text.", "When rewriting text, return plain text unless the prop is a rich-text prop (see below) or the user explicitly asks for markdown formatting. Do not wrap the entire rewrite in **bold** markers.", RULE_RICH_TEXT_PROPS, "For copy in German or similar long-compound languages, insert soft hyphen opportunities in long compounds where helpful for responsive line wrapping. Use the Unicode soft hyphen character (U+00AD), never HTML entities like ­ or ­.", opts.provider !== "openai" ? BLOCK_NAME_PRIVACY_ANTHROPIC : BLOCK_NAME_PRIVACY_OPENAI, "", "### suggested_next_actions", "2-4 short imperative phrases the user could type next (max 6 words each). Each MUST be a logical follow-up to the specific change just made — not a generic action. NEVER suggest 'Open /X' or any navigation to a page that the current plan is creating, duplicating, or otherwise still pending — the page won't exist until the user approves the plan, and there is no special navigation chip handler (suggestions are sent verbatim as the next chat command). Suggest plan refinements instead (e.g. 'Use a punchier hero headline', 'Add a card grid for spotlights', 'Drop the FAQ section'). Ask yourself: 'what would the user likely want to do next given THIS edit?' When the plan contains exactly one update_props op that changes a text field, the first 1-2 suggestions MUST be refinements of that same field (e.g. 'Make it shorter', 'Try a bolder tone', 'Revert to previous'). For example, after rewriting stats labels, suggest refining the same section ('Make the numbers bigger', 'Add a stat about X') — not unrelated actions like 'Change title' or 'Add a Testimonials section'. For needs_clarification, suggest the most likely concrete answers. Omit suggested_next_actions entirely if no contextual follow-up is obvious. Every suggestion must be an action the user can perform inside this editor — restricted to the block types listed in blockContracts / blockCatalogue for THIS site, or SEO/site-config edits. Never suggest adding a section this site has no block for; the catalogue is the whole list, not a sample of a larger one. NEVER suggest unsupported features: no forms, no email capture, no contact forms, no subscribe boxes, no newsletter signups, no popups/modals, no chat widgets, no live video, no payment/checkout — these require custom code the editor cannot produce. Never suggest actions outside the editor's scope such as A/B testing, analytics, performance monitoring, user research, or marketing strategy.");
+    return lines;
+}
+/*
+ * Prop-name corrections the model actually needs, and the reason they are not
+ * written as prose.
+ *
+ * Models reach for the obvious English word — `heading` for a section title,
+ * `question`/`answer` for an FAQ entry, `testimonial` for a quote — and several
+ * of Avocado's built-in blocks chose a different name. Telling the model so is
+ * worth real accuracy, and the line that did it read: "use 'title' not
+ * 'heading' for section titles (except Hero which uses 'heading')".
+ *
+ * That is a fact about Avocado's own catalogue stated as a fact about section
+ * titles. A site that brings its own blocks and names a text prop `heading` was
+ * being instructed, in the system prompt, to emit a prop its schema does not
+ * have. It is the same mistake the plan normalizer was fixed for in 0.3.3 — the
+ * normalizer no longer *creates* the wrong prop name, but nothing had stopped
+ * the prompt from *asking* for it, so the bug simply moved one layer up.
+ *
+ * So each correction now names the block type it is about, and is emitted only
+ * when the registry confirms it is still true: the type is in this site's
+ * catalogue, it really does reject the wrong key, and it really does accept the
+ * right one. A site that registers its own `Hero` with a `title` prop gets no
+ * line about Hero; a site with no FAQAccordion gets no line about `q`/`a`.
+ */
+const PROP_NAME_CORRECTIONS = [
+    { type: "Hero", wrong: "title", right: "heading", what: "the headline" },
+    { type: "FeatureGrid", wrong: "heading", right: "title", what: "the section title" },
+    { type: "CardGrid", wrong: "heading", right: "title", what: "the section title" },
+    { type: "Testimonials", wrong: "heading", right: "title", what: "the section title" },
+    { type: "FAQAccordion", wrong: "heading", right: "title", what: "the section title" },
+    { type: "CTA", wrong: "title", right: "heading", what: "the headline" },
+];
+const LIST_ITEM_CORRECTIONS = [
+    { type: "FAQAccordion", list: "items", wrong: "question", right: "q" },
+    { type: "FAQAccordion", list: "items", wrong: "answer", right: "a" },
+    { type: "Testimonials", list: "items", wrong: "testimonial", right: "quote" },
+];
+/**
+ * The subset of the corrections above that is true of THIS site's catalogue.
+ * Returns one prompt line per surviving correction, or an empty array.
+ */
+export function propNameCorrectionLines(effectiveBlockTypes) {
+    const present = new Set(effectiveBlockTypes);
+    const lines = [];
+    for (const c of PROP_NAME_CORRECTIONS) {
+        if (!present.has(c.type))
+            continue;
+        if (blockAcceptsProp(c.type, c.wrong))
+            continue;
+        if (!blockAcceptsProp(c.type, c.right))
+            continue;
+        lines.push(`${c.type} names ${c.what} '${c.right}', not '${c.wrong}'.`);
+    }
+    for (const c of LIST_ITEM_CORRECTIONS) {
+        if (!present.has(c.type))
+            continue;
+        if (blockListItemAcceptsKey(c.type, c.list, c.wrong))
+            continue;
+        if (!blockListItemAcceptsKey(c.type, c.list, c.right))
+            continue;
+        lines.push(`${c.type} \`${c.list}\` entries use '${c.right}', not '${c.wrong}'.`);
+    }
     return lines;
 }
-function sectionOperationCatalog() {
+function sectionOperationCatalog(opts) {
+    /*
+     * The universal rule first, so it governs even when no correction below
+     * applies: a prop name is a property of one block type's schema, never of the
+     * English word for the thing it holds.
+     */
+    const corrections = propNameCorrectionLines(opts.effectiveBlockTypes);
+    const addBlockPropRule = "add_block: use the exact prop names blockContracts lists for THAT block type. A prop name is a fact about one block's schema, not about the kind of content it holds — never carry a prop name across from another block type, and never infer one from the English word for the field ('heading', 'question', 'subtitle'). If blockContracts does not list a prop, the block does not have it: omit it rather than inventing a plausible name." +
+        (corrections.length > 0
+            ? ` Corrections for blocks on this site that models routinely get wrong: ${corrections.join(" ")}`
+            : "") +
+        " Always populate block.props with REAL content matching the user's request (headlines, body copy, list items grounded in the user's topic) — never emit add_block with empty or missing props; the system falls back to demo template defaults if you omit props, and that template will mislead the user. Placement: set `afterBlockId` to the id of the block the new section should follow — e.g. to add a section 'below the hero' / 'under the hero' / 'after the hero', set afterBlockId to the hero block's id from the pageOutline. Honor any position the user names ('below the hero', 'above the footer', 'after the pricing'). Omit afterBlockId only when no position is implied — it then appends at the very end of the page.";
     return [
         "## OPERATION CATALOG",
         "update_props: blockId is required and must target an existing block id (b_*). Never use a page route/path as blockId or path. Use blockId values from the pageOutline — never invent block IDs. Set patch to changed props only; use existing prop keys for the target block type. Emit keys in this exact order: op, pageSlug (if present), blockId, patch.",
-        "add_block: use exact prop names from blockContracts. Always populate block.props with REAL content matching the user's request (headlines, body copy, list items grounded in the user's topic) — never emit add_block with empty or missing props. The system will fall back to demo template defaults (e.g. 'Key features / Fast setup / Safe edits / Live updates') if you omit props, and that template will mislead the user. Common mistakes: use 'title' not 'heading' for section titles (except Hero which uses 'heading'), use 'q'/'a' not 'question'/'answer' for FAQ items, use 'quote' not 'testimonial' for Testimonials items. Placement: set `afterBlockId` to the id of the block the new section should follow — e.g. to add a section 'below the hero' / 'under the hero' / 'after the hero', set afterBlockId to the hero block's id from the pageOutline. Honor any position the user names ('below the hero', 'above the footer', 'after the pricing'). Omit afterBlockId only when no position is implied — it then appends at the very end of the page.",
+        addBlockPropRule,
         "remove_block: delete an ENTIRE block/section from the page (blockId required, no listKey). Use this — NOT remove_item — whenever the user removes a whole section, INCLUDING when they pick it by POSITION or TYPE: 'delete the second card grid', 'remove the first feature grid', 'hide the third section', 'remove the FAQ', 'get rid of the testimonials'. For 'remove ALL the <type>' / 'delete every <type>', emit one remove_block per matching block. remove_item is ONLY for deleting ONE entry inside a block's list and is signalled by an item word scoped INTO a container ('remove the last card IN the grid', 'delete a question FROM the FAQ'). A bare '[the Nth] <block-or-section-noun>' with no into-container preposition is ALWAYS a remove_block — never remove an item to satisfy it.",
         "add_item / update_item / remove_item / move_item: edit ONE entry inside a block's list prop (e.g. FeatureGrid `features`, FAQAccordion `items`, Testimonials `items`, CardGrid `cards`). Required on every item op: pageSlug, blockId, listKey. Address the target entry by its stable `itemId` (the item's `id` field) WHEN the block's full props are in your context — never guess or invent an itemId you cannot see. Otherwise use the 0-based `index`; the system resolves it against the current page state, so an index is safe too. add_item: supply `item` with the entry's props (do NOT invent an `id`, one is assigned); optional `afterItemId` (or `afterIndex`) positions it, omit ⇒ append. update_item: `patch` is a merge-patch over that entry's fields. move_item: `afterItemId` (or `afterIndex`) sets the new position, omit ⇒ move to front. When changing SEVERAL entries of one list in a single plan, replacing the whole list with one update_props op is also fine.",
         "update_page_meta: set SEO metadata (title, description, ogImage) on a page. Patch is merge-patch: only supplied keys update. Set a field to empty string to clear it.",

package/dist/chat/translation-chunking.d.ts

@@ -0,0 +1,124 @@
+import type { EditPlan, PageDoc } from "@avocadostudio-ai/shared";
+import type { plannerContextPack } from "../nlp/deterministic-planner.ts";
+import type { CommonGeneratePlanArgs, GeneratePlanResult } from "./planner-types.ts";
+export declare function translationChunkingConfig(): {
+    enabled: boolean;
+    /**
+     * Translatable bytes to aim for per chunk.
+     *
+     * Chunk wall clock is roughly a fixed time-to-first-token plus streaming time
+     * proportional to this. Measured on Sonnet 5: ~5s to first token, then ~130
+     * output tokens/second, and a chunk's output runs a little over one token per
+     * source byte. ~900 bytes puts streaming (~8s) in the same range as the fixed
+     * cost, which is where splitting further stops buying much and starts paying
+     * another chunk's input tokens for nothing.
+     */
+    targetBytes: number;
+    /** Upper bound on parallel planner calls — one wave, not a stampede. */
+    maxChunks: number;
+    /** Below these, a single request is already fast and chunking only adds input cost. */
+    minBlocks: number;
+    minBytes: number;
+};
+export type TranslationChunk = {
+    blockIds: string[];
+    /** Translatable bytes carried by this chunk — the driver of its output length. */
+    bytes: number;
+};
+/**
+ * Partition the page's translatable blocks into balanced chunks.
+ *
+ * Wall clock is the *heaviest* chunk, not the average one, so balance is the
+ * whole game: a first live run split a page into 1604 / 1010 / 172 / 769 bytes
+ * and spent 17 of its 23 seconds waiting on the first bin while a 172-byte bin
+ * sat finished. Packing blocks in page order is what produces that — it has to
+ * close a chunk before it can see what comes next.
+ *
+ * So blocks are packed heaviest-first into whichever chunk is currently lightest
+ * (longest-processing-time-first), which bounds the heaviest chunk far better,
+ * and page order is restored afterwards so the change log still reads top to
+ * bottom. Blocks are never split: an `update_props` op carries a whole block.
+ *
+ * Returns a single chunk when the page is too small to be worth splitting; the
+ * caller treats that as "don't chunk".
+ */
+export declare function planTranslationChunks(args: {
+    page: PageDoc;
+    targetBytes?: number;
+    maxChunks?: number;
+}): TranslationChunk[];
+/** Whether this page is worth fanning out, per the configured thresholds. */
+export declare function shouldChunkTranslation(page: PageDoc, chunks: TranslationChunk[]): boolean;
+/**
+ * The page as this chunk should see it: same id/slug/meta, only its own blocks.
+ *
+ * Everything downstream in the planner derives from `currentPage` — the output
+ * token budget, and the enumerated translation checklist handed to the model —
+ * so narrowing the page is what makes a chunk a chunk. No extra plumbing.
+ */
+export declare function subsetPageForChunk(page: PageDoc, blockIds: Set<string>): PageDoc;
+/** The context pack narrowed to the chunk's blocks, so input cost doesn't repeat the whole page N times. */
+export declare function subsetContextPackForChunk(pack: ReturnType<typeof plannerContextPack>, blockIds: Set<string>): ReturnType<typeof plannerContextPack>;
+/**
+ * Keep only what this chunk was asked for.
+ *
+ * A chunk sees a slice of the page, but nothing stops a model from volunteering
+ * an op for a block it half-remembers from the site context, or from restructuring
+ * a page it was asked to translate. Ops outside the chunk's blocks are dropped
+ * rather than merged: a translation that also deletes a section is not a
+ * translation, and two chunks editing the same block would silently race.
+ */
+export declare function filterChunkOps(args: {
+    ops: EditPlan["ops"];
+    blockIds: Set<string>;
+    isFirstChunk: boolean;
+}): {
+    kept: EditPlan["ops"];
+    droppedCount: number;
+};
+export type ChunkOutcome = {
+    index: number;
+    blockIds: string[];
+    ok: boolean;
+    opCount: number;
+    droppedOpCount: number;
+    attempts: number;
+    /** Wall clock for this chunk. The slowest one is the request's latency — the number to tune against. */
+    durationMs: number;
+    bytes: number;
+    outputTokens: number;
+    reason?: string;
+};
+/**
+ * Run every chunk in parallel and merge the results into one plan.
+ *
+ * A chunk that dies on a token ceiling is retried once on its own, with double
+ * the budget — retrying one chunk is cheap where retrying the page is not. A
+ * chunk that still fails is left out: the merged plan is short those blocks, and
+ * the pipeline's translation coverage gate is what notices and repairs that. The
+ * whole call only fails when every chunk failed, so the caller's own retry loop
+ * sees a normal planner failure.
+ */
+export declare function generateChunkedTranslationPlan(args: {
+    plannerArgs: CommonGeneratePlanArgs;
+    chunks: TranslationChunk[];
+    generate: (plannerArgs: CommonGeneratePlanArgs) => Promise<GeneratePlanResult>;
+    log?: {
+        warn: (obj: Record<string, unknown>, msg: string) => void;
+        info?: (obj: Record<string, unknown>, msg: string) => void;
+    };
+    onChunksSettled?: (outcomes: ChunkOutcome[]) => void;
+}): Promise<GeneratePlanResult>;
+/**
+ * Fold the chunk plans back into one.
+ *
+ * Chunks are balanced by weight rather than page position, so their ops come
+ * back shuffled; `blockOrder` puts them back the way the page reads, which is
+ * the order the change log and the plan preview are reviewed in.
+ *
+ * The user-facing summary is not concatenated: every chunk was given the user's
+ * original message, so every chunk wrote a summary of the same request
+ * ("Translated the page into Russian"), and stacking six of those reads like a
+ * stutter. The first one stands for all.
+ */
+export declare function mergeChunkResults(results: GeneratePlanResult[], blockOrder?: string[]): GeneratePlanResult;