@avocadostudio-ai/orchestrator-core 0.3.1 → 0.3.3

package/dist/chat/hallucination-validator.js

@@ -45,6 +45,22 @@ function findBlockType(args) {
     }
     return undefined;
 }
+/*
+ * Does this key read as a visual/presentational one?
+ *
+ * Deliberately a small allow-list of stems rather than a clever rule: the
+ * default has to be "content", because the expensive mistake is telling
+ * somebody their content edit was a styling limitation, not the reverse.
+ */
+const VISUAL_PROP_STEMS = [
+    "color", "colour", "background", "gradient", "animation", "animate", "shadow",
+    "font", "size", "spacing", "padding", "margin", "border", "radius", "opacity",
+    "align", "theme", "style", "variant", "width", "height", "position", "layout"
+];
+function isVisualPropName(prop) {
+    const lower = prop.toLowerCase();
+    return VISUAL_PROP_STEMS.some((stem) => lower.includes(stem));
+}
 function humanBlockName(blockType) {
     const meta = getBlockMeta(blockType);
     return meta?.displayName ?? blockType;
@@ -81,15 +97,33 @@ export function validateAndStripHallucinatedProps(args) {
             if (allowedKeys.has(key))
                 continue;
             delete patchCandidate[key];
-            hallucinatedProps.push({ blockId: op.blockId, blockType, propName: key });
+            hallucinatedProps.push({
+                blockId: op.blockId,
+                blockType,
+                propName: key,
+                allowedProps: [...allowedKeys].sort()
+            });
         }
     }
     if (hallucinatedProps.length > 0) {
-        // Merge duplicates into a single readable note keyed by blockType. We
-        // intentionally avoid echoing the raw prop name back to the user —
-        // doing so is (a) jargon-y (users don't think in prop keys), and (b)
-        // makes the note trivially collide with eval banned-word checks that
-        // try to prove the planner didn't promise the unsupported behavior.
+        /*
+         * Two different events used to share one sentence, and the wrong one was
+         * the default.
+         *
+         * "Some requested styling isn't available" is true when the planner
+         * promised a colour, a gradient or an animation the block has no field
+         * for. It is false — and actively misleading — when the planner simply
+         * used the wrong *name* for a field the block does have under another
+         * name: nothing about that is styling, and the sentence sends the reader
+         * to look at their design system. An integrator lost nine minutes to
+         * exactly that, on a block whose schema, registry and ops path were all
+         * correct.
+         *
+         * So classify the stripped key. A visual key keeps the original wording,
+         * because that is the case it was written for and the evals that check it
+         * are checking that case. A content key gets a sentence that names it,
+         * which is the one piece of information that ends the search.
+         */
         const byBlockType = new Map();
         for (const entry of hallucinatedProps) {
             const bucket = byBlockType.get(entry.blockType) ?? new Set();
@@ -97,9 +131,16 @@ export function validateAndStripHallucinatedProps(args) {
             byBlockType.set(entry.blockType, bucket);
         }
         const noteParts = [];
-        for (const [blockType] of byBlockType) {
+        for (const [blockType, props] of byBlockType) {
             const name = humanBlockName(blockType);
-            noteParts.push(`Some requested styling isn't available on the ${name} block — applied the supported parts.`);
+            const visual = [...props].filter(isVisualPropName);
+            const content = [...props].filter((prop) => !isVisualPropName(prop));
+            if (visual.length > 0) {
+                noteParts.push(`Some requested styling isn't available on the ${name} block — applied the supported parts.`);
+            }
+            for (const prop of content) {
+                noteParts.push(`The ${name} block has no “${prop}” field, so that part wasn't applied.`);
+            }
         }
         const note = noteParts.join(" ");
         const summary = plan.summary_for_user?.trimEnd() ?? "";

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