@avocadostudio-ai/orchestrator-core 0.3.2 → 0.3.3

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/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;

package/dist/chat/translation-chunking.js

@@ -0,0 +1,371 @@
+import { buildFullPageTranslationChecklist } from "./chat-pipeline-translation.js";
+import { ZERO_USAGE } from "../telemetry/usage.js";
+/**
+ * Full-page translation, split into independent per-block-group requests.
+ *
+ * One request for the whole page is the wrong shape for this job. A translation
+ * re-emits every string on the page, so its *output* length scales with the page
+ * while a single request's output is strictly serial: an 8 KB page cost 9,139
+ * output tokens and 75 seconds of streaming, and a page twice that size costs
+ * twice as long. Worse, the whole thing is one all-or-nothing unit — overshoot
+ * the token ceiling on the last block and the other six are discarded too.
+ *
+ * The blocks are independent, though. Nothing in translating the FAQ depends on
+ * how the hero was translated, so the work fans out: N smaller requests in
+ * parallel, each carrying only its own blocks, merged back into one plan. Wall
+ * clock becomes the slowest chunk rather than the sum, each chunk is far from
+ * any token ceiling, and a chunk that does fail costs only its own blocks.
+ *
+ * The tradeoff is input tokens — the schema contract and site context repeat per
+ * chunk — so each chunk carries only its own slice of the page outline, and the
+ * whole path is gated on the page being big enough to be worth it.
+ */
+// ---------------------------------------------------------------------------
+// Configuration
+// ---------------------------------------------------------------------------
+function envFlagOff(raw) {
+    return /^(0|false|no|off)$/i.test((raw ?? "").trim());
+}
+function envInt(raw, fallback) {
+    const parsed = Number((raw ?? "").trim());
+    return Number.isFinite(parsed) && parsed > 0 ? Math.floor(parsed) : fallback;
+}
+export function translationChunkingConfig() {
+    return {
+        enabled: !envFlagOff(process.env.CHAT_TRANSLATION_CHUNKING),
+        /**
+         * 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: envInt(process.env.CHAT_TRANSLATION_CHUNK_BYTES, 900),
+        /** Upper bound on parallel planner calls — one wave, not a stampede. */
+        maxChunks: envInt(process.env.CHAT_TRANSLATION_MAX_CHUNKS, 6),
+        /** Below these, a single request is already fast and chunking only adds input cost. */
+        minBlocks: envInt(process.env.CHAT_TRANSLATION_CHUNK_MIN_BLOCKS, 3),
+        minBytes: envInt(process.env.CHAT_TRANSLATION_CHUNK_MIN_BYTES, 1800)
+    };
+}
+/**
+ * Weigh each block by the `update_props` patch a translation has to emit for it.
+ *
+ * Two wrong answers were tried first. Block JSON size over-weights a Gallery of
+ * twenty image URLs that has nothing to translate. Translatable string length —
+ * the obvious fix — under-weights list blocks badly: a live run gave one 769-byte
+ * CardGrid the same weight as a 1030-byte prose block and then watched it take
+ * twice as long, because a list patch re-sends *every row* (a shorter array
+ * truncates the list) and pays JSON structure for each one.
+ *
+ * So the weight is the thing being predicted: build the minimal patch we ask the
+ * model for and measure it.
+ */
+function weighBlocks(page) {
+    const checklist = buildFullPageTranslationChecklist(page);
+    return checklist.map((entry) => {
+        const block = page.blocks.find((b) => b.id === entry.blockId);
+        const props = (block?.props ?? {});
+        const patch = {};
+        for (const field of entry.fields) {
+            const listMatch = field.match(/^([^[]+)\[(\d+)\]\.(.+)$/);
+            if (!listMatch) {
+                if (typeof props[field] === "string")
+                    patch[field] = props[field];
+                continue;
+            }
+            const [, listKey, rawIndex, itemField] = listMatch;
+            const source = props[listKey];
+            if (!Array.isArray(source))
+                continue;
+            const rows = patch[listKey]
+                ?? source.map(() => ({}));
+            patch[listKey] = rows;
+            const value = source[Number(rawIndex)]?.[itemField];
+            if (typeof value === "string")
+                rows[Number(rawIndex)][itemField] = value;
+        }
+        return { blockId: entry.blockId, bytes: JSON.stringify(patch).length };
+    });
+}
+/**
+ * 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 function planTranslationChunks(args) {
+    const config = translationChunkingConfig();
+    const targetBytes = args.targetBytes ?? config.targetBytes;
+    const maxChunks = args.maxChunks ?? config.maxChunks;
+    const weighted = weighBlocks(args.page);
+    if (weighted.length === 0)
+        return [];
+    const totalBytes = weighted.reduce((sum, entry) => sum + entry.bytes, 0);
+    const chunkCount = Math.min(weighted.length, maxChunks, Math.max(1, Math.ceil(totalBytes / targetBytes)));
+    if (chunkCount <= 1) {
+        return [{ blockIds: weighted.map((entry) => entry.blockId), bytes: totalBytes }];
+    }
+    const pageOrder = new Map(weighted.map((entry, index) => [entry.blockId, index]));
+    const bins = Array.from({ length: chunkCount }, () => ({ blockIds: [], bytes: 0 }));
+    // Heaviest first into the lightest bin. The first `chunkCount` blocks land in
+    // distinct empty bins, so no bin is ever left empty.
+    for (const entry of [...weighted].sort((a, b) => b.bytes - a.bytes)) {
+        const lightest = bins.reduce((min, bin) => (bin.bytes < min.bytes ? bin : min));
+        lightest.blockIds.push(entry.blockId);
+        lightest.bytes += entry.bytes;
+    }
+    for (const bin of bins)
+        bin.blockIds.sort((a, b) => pageOrder.get(a) - pageOrder.get(b));
+    bins.sort((a, b) => pageOrder.get(a.blockIds[0]) - pageOrder.get(b.blockIds[0]));
+    return bins;
+}
+/** Whether this page is worth fanning out, per the configured thresholds. */
+export function shouldChunkTranslation(page, chunks) {
+    const config = translationChunkingConfig();
+    if (!config.enabled)
+        return false;
+    if (chunks.length < 2)
+        return false;
+    const translatableBlocks = chunks.reduce((sum, chunk) => sum + chunk.blockIds.length, 0);
+    const translatableBytes = chunks.reduce((sum, chunk) => sum + chunk.bytes, 0);
+    return translatableBlocks >= config.minBlocks && translatableBytes >= config.minBytes;
+}
+// ---------------------------------------------------------------------------
+// Per-chunk request shaping
+// ---------------------------------------------------------------------------
+/**
+ * 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 function subsetPageForChunk(page, blockIds) {
+    return { ...page, blocks: page.blocks.filter((block) => blockIds.has(block.id)) };
+}
+/** The context pack narrowed to the chunk's blocks, so input cost doesn't repeat the whole page N times. */
+export function subsetContextPackForChunk(pack, blockIds) {
+    const outline = pack.pageOutline.filter((entry) => blockIds.has(entry.id));
+    return {
+        ...pack,
+        blockCount: outline.length,
+        pageOutline: outline,
+        // The selection and its neighbours belong to the whole-page view; a chunk is
+        // scoped by its checklist, and a stale "selected block" would pull the model
+        // toward a block this chunk may not even carry.
+        selected: { ...pack.selected, blockId: null, blockType: null, editablePath: null, block: null, imageUrlForVision: null },
+        neighbors: { previous: null, next: null }
+    };
+}
+/**
+ * Page-level ops a translation may legitimately emit, but only once. Handing the
+ * same site config to six chunks invites six conflicting `update_site_config`
+ * ops, so only the first chunk is allowed to produce them.
+ */
+const PAGE_LEVEL_OPS = new Set(["update_page_meta", "update_site_config"]);
+/** Ops that address a block, and so must address one of *this* chunk's blocks. */
+const BLOCK_SCOPED_OPS = new Set(["update_props", "update_item", "add_item", "remove_item", "move_item", "reorder_items"]);
+/**
+ * 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 function filterChunkOps(args) {
+    const kept = args.ops.filter((op) => {
+        if (BLOCK_SCOPED_OPS.has(op.op)) {
+            return "blockId" in op && typeof op.blockId === "string" && args.blockIds.has(op.blockId);
+        }
+        if (PAGE_LEVEL_OPS.has(op.op))
+            return args.isFirstChunk;
+        return false;
+    });
+    return { kept, droppedCount: args.ops.length - kept.length };
+}
+/**
+ * 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 async function generateChunkedTranslationPlan(args) {
+    const { plannerArgs, chunks, generate } = args;
+    // Ops stream to the UI (and to the streamed-per-op apply) as they arrive from
+    // whichever chunk produced them. Order across chunks is not meaningful — each
+    // op patches a different block — but the index has to stay unique and rising,
+    // so it is handed out centrally rather than per chunk.
+    let streamedOpIndex = 0;
+    const runChunk = async (chunk, index) => {
+        const blockIds = new Set(chunk.blockIds);
+        const isFirstChunk = index === 0;
+        const startedAt = Date.now();
+        let attempts = 0;
+        let lastError;
+        for (let attempt = 1; attempt <= 2; attempt += 1) {
+            attempts = attempt;
+            try {
+                const chunkPage = subsetPageForChunk(plannerArgs.currentPage, blockIds);
+                const result = await generate({
+                    ...plannerArgs,
+                    currentPage: chunkPage,
+                    contextPack: subsetContextPackForChunk(plannerArgs.contextPack, blockIds),
+                    outputTokenScale: (plannerArgs.outputTokenScale ?? 1) * attempt,
+                    // A page-wide translation normally ships every block's schema contract,
+                    // because it edits every block. A chunk edits two — and repeating ~9 KB
+                    // of contracts per chunk would hand back in input tokens most of what
+                    // the fan-out buys.
+                    contractBlockTypeAllowlist: [...new Set(chunkPage.blocks.map((block) => String(block.type)))],
+                    // Chunks are self-contained: no tools to call, no prior turns to
+                    // resolve against. Dropping both keeps the repeated input small.
+                    history: [],
+                    toolRuntime: undefined,
+                    toolCallContext: undefined,
+                    onToolExecution: undefined,
+                    // Prose callbacks are single-sourced. Six chunks streaming their own
+                    // summary into one message box would interleave into nonsense; ops and
+                    // change-log lines are independent and stream from every chunk.
+                    onToken: isFirstChunk ? plannerArgs.onToken : undefined,
+                    onSummaryChunk: isFirstChunk ? plannerArgs.onSummaryChunk : undefined,
+                    onThinking: isFirstChunk ? plannerArgs.onThinking : undefined,
+                    onStatusUpdate: isFirstChunk ? plannerArgs.onStatusUpdate : undefined,
+                    onPlannedOp: plannerArgs.onPlannedOp
+                        ? (op) => {
+                            streamedOpIndex += 1;
+                            plannerArgs.onPlannedOp(op, streamedOpIndex);
+                        }
+                        : undefined
+                });
+                const { kept, droppedCount } = filterChunkOps({ ops: result.plan.ops, blockIds, isFirstChunk });
+                if (droppedCount > 0) {
+                    args.log?.warn({ event: "translation_chunk_ops_dropped", chunkIndex: index, droppedCount, blockIds: chunk.blockIds }, "Translation chunk returned ops outside its own blocks — dropped");
+                }
+                return {
+                    outcome: {
+                        index,
+                        blockIds: chunk.blockIds,
+                        ok: true,
+                        opCount: kept.length,
+                        droppedOpCount: droppedCount,
+                        attempts,
+                        durationMs: Date.now() - startedAt,
+                        bytes: chunk.bytes,
+                        outputTokens: result.usage?.outputTokens ?? 0
+                    },
+                    result: { ...result, plan: { ...result.plan, ops: kept } }
+                };
+            }
+            catch (error) {
+                lastError = error;
+                const message = error instanceof Error ? error.message : String(error);
+                // Only a budget failure is worth an immediate identical retry; anything
+                // else (cancellation, an API error) should surface to the caller now.
+                if (attempt === 2 || !/truncated \(max_tokens/i.test(message))
+                    break;
+                args.log?.warn({ event: "translation_chunk_retry", chunkIndex: index, blockIds: chunk.blockIds, reason: message.slice(0, 200) }, "Translation chunk truncated — retrying with a larger budget");
+            }
+        }
+        return {
+            outcome: {
+                index,
+                blockIds: chunk.blockIds,
+                ok: false,
+                opCount: 0,
+                droppedOpCount: 0,
+                attempts,
+                durationMs: Date.now() - startedAt,
+                bytes: chunk.bytes,
+                outputTokens: 0,
+                reason: lastError instanceof Error ? lastError.message : String(lastError)
+            }
+        };
+    };
+    const settled = await Promise.all(chunks.map((chunk, index) => runChunk(chunk, index)));
+    const outcomes = settled.map((entry) => entry.outcome);
+    args.onChunksSettled?.(outcomes);
+    const succeeded = settled.filter((entry) => entry.result !== undefined);
+    if (succeeded.length === 0) {
+        const firstReason = outcomes.find((outcome) => outcome.reason)?.reason ?? "translation chunks produced no plan";
+        throw new Error(firstReason);
+    }
+    return mergeChunkResults(succeeded.map((entry) => entry.result), plannerArgs.currentPage.blocks.map((block) => block.id));
+}
+/** Chunk usage is real spend on the same request — the totals have to include all of it. */
+function addUsage(a, b) {
+    const cacheCreation = (a.cacheCreationInputTokens ?? 0) + (b.cacheCreationInputTokens ?? 0);
+    const cacheRead = (a.cacheReadInputTokens ?? 0) + (b.cacheReadInputTokens ?? 0);
+    return {
+        inputTokens: a.inputTokens + b.inputTokens,
+        outputTokens: a.outputTokens + b.outputTokens,
+        totalTokens: a.totalTokens + b.totalTokens,
+        ...(cacheCreation > 0 ? { cacheCreationInputTokens: cacheCreation } : {}),
+        ...(cacheRead > 0 ? { cacheReadInputTokens: cacheRead } : {})
+    };
+}
+/**
+ * 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 function mergeChunkResults(results, blockOrder) {
+    const ops = [];
+    const changeLog = [];
+    const seenBlockOps = new Set();
+    for (const result of results) {
+        for (const op of result.plan.ops) {
+            // Chunks are disjoint by construction, but a duplicate here would mean two
+            // ops racing to patch one block, and the loser's translation vanishing.
+            const key = "blockId" in op && typeof op.blockId === "string" ? `${op.op}:${op.blockId}` : null;
+            if (key) {
+                if (seenBlockOps.has(key))
+                    continue;
+                seenBlockOps.add(key);
+            }
+            ops.push(op);
+        }
+        for (const entry of result.plan.change_log ?? [])
+            changeLog.push(entry);
+    }
+    if (blockOrder) {
+        const rank = new Map(blockOrder.map((id, index) => [id, index]));
+        // Page-level ops carry no block, and belong at the top where the model put them.
+        const rankOf = (op) => "blockId" in op && typeof op.blockId === "string" ? rank.get(op.blockId) ?? Number.MAX_SAFE_INTEGER : -1;
+        ops.sort((a, b) => rankOf(a) - rankOf(b));
+    }
+    const summary = results.map((result) => result.plan.summary_for_user).find((text) => typeof text === "string" && text.trim().length > 0)
+        ?? "Translated the page.";
+    return {
+        plan: { intent: "edit_plan", summary_for_user: summary, change_log: changeLog, ops },
+        usage: results.reduce((total, result) => addUsage(total, result.usage), { ...ZERO_USAGE }),
+        schemaContext: results[0].schemaContext,
+        deferredNativeImageCalls: results.flatMap((result) => result.deferredNativeImageCalls ?? [])
+    };
+}

package/dist/checks/field-walk.d.ts

@@ -0,0 +1,25 @@
+import type { BlockManifest, PageDoc } from "@avocadostudio-ai/shared";
+import type { FieldEntry } from "./types.ts";
+export declare function walkPageFields(page: PageDoc, manifest: BlockManifest): FieldEntry[];
+/**
+ * Readable text inside a field value.
+ *
+ * A `text` field is a string. A `richtext` field is a ProseMirror document, or
+ * markdown, or — for a custom block registered with a loose schema — something
+ * else entirely. Collecting every `text` string in the tree handles all three
+ * without the caller having to know which it got, and returns "" for a shape
+ * this does not recognise rather than guessing.
+ */
+export declare function fieldText(value: unknown): string;
+/**
+ * The page's fields, split per block, in block order.
+ *
+ * Paths and containers are *block-relative* — every block with an image has a
+ * field at `imageUrl`, every block with a list has a `cards[0]` — so any rule
+ * that indexes fields by path or container has to do it one block at a time. A
+ * page-wide index of either silently pairs one block's image with another
+ * block's alt text, which is a false negative on the page that has two heroes
+ * and a false positive with the wrong block in its evidence on the page that
+ * has two of anything else.
+ */
+export declare function groupByBlock(fields: FieldEntry[]): Map<string, FieldEntry[]>;