@avocadostudio-ai/orchestrator-core 0.1.0

package/dist/chat/changelog-coverage-validator.d.ts

@@ -0,0 +1,37 @@
+/**
+ * Post-plan change_log coverage validator.
+ *
+ * When a planner returns an edit_plan with N ops, the user reads change_log
+ * to decide whether to approve. If change_log is shorter than ops[], the
+ * user is approving blind to the uncovered ops — a silent bait-and-switch
+ * that erodes trust. If change_log is LONGER than ops[], the planner is
+ * describing changes it won't actually make (e.g. emits `duplicate_page`
+ * alone but narrates 4 follow-up `update_props` edits in change_log); the
+ * approval UI then promises content the apply step will silently drop.
+ *
+ * For the under-coverage case, the validator appends a synthesized bullet
+ * per uncovered op. For the over-coverage case, it trims trailing entries
+ * so the rendered plan matches what will actually run. Both directions
+ * report counts for telemetry so we can track how often planners drift.
+ */
+import { type EditPlan, type PageDoc } from "@avocadostudio-ai/shared";
+export type ChangelogCoverageResult = {
+    plan: EditPlan;
+    missingCount: number;
+    synthesizedEntries: string[];
+    extraCount: number;
+    droppedEntries: string[];
+    /** Number of update_props entries rewritten because they named the wrong field (#13). */
+    fieldMislabelCount: number;
+    relabeledEntries: string[];
+};
+/**
+ * Ensure change_log has at least one entry per op for edit_plan intents.
+ * When short, synthesize a generic entry per uncovered op so the user sees
+ * an accurate count of changes. Non-edit_plan intents and empty ops lists
+ * are passed through unchanged.
+ */
+export declare function validateChangelogCoverage(args: {
+    plan: EditPlan;
+    draft: Map<string, PageDoc>;
+}): ChangelogCoverageResult;

package/dist/chat/changelog-coverage-validator.js

@@ -0,0 +1,215 @@
+/**
+ * Post-plan change_log coverage validator.
+ *
+ * When a planner returns an edit_plan with N ops, the user reads change_log
+ * to decide whether to approve. If change_log is shorter than ops[], the
+ * user is approving blind to the uncovered ops — a silent bait-and-switch
+ * that erodes trust. If change_log is LONGER than ops[], the planner is
+ * describing changes it won't actually make (e.g. emits `duplicate_page`
+ * alone but narrates 4 follow-up `update_props` edits in change_log); the
+ * approval UI then promises content the apply step will silently drop.
+ *
+ * For the under-coverage case, the validator appends a synthesized bullet
+ * per uncovered op. For the over-coverage case, it trims trailing entries
+ * so the rendered plan matches what will actually run. Both directions
+ * report counts for telemetry so we can track how often planners drift.
+ */
+import { getBlockMeta, getPropDisplayName } from "@avocadostudio-ai/shared";
+// Distinctive label tokens (len ≥ 4) used to tell sibling fields apart —
+// "secondary" distinguishes "Secondary CTA Text" from "CTA Text". Short shared
+// tokens ("cta", "text") are dropped so overlap doesn't mask a wrong-field claim.
+function labelTokens(label) {
+    return label
+        .toLowerCase()
+        .split(/[^a-z0-9]+/)
+        .filter((t) => t.length >= 4);
+}
+const word = (t) => new RegExp(`\\b${t.replace(/[.*+?^${}()|[\]\\]/g, "\\$&")}\\b`);
+/**
+ * A change_log/summary entry for an update_props op "mislabels" when it names a
+ * field the op does NOT touch (a sibling on the same block) by a distinctive token
+ * and mentions none of the fields it DOES touch. That's an affirmatively false
+ * label — the user approves "rename the secondary CTA" while their heading,
+ * subheading, and primary CTA get rewritten (#13). Returns an accurate replacement
+ * string, or null when the narration is fine / can't be judged confidently.
+ */
+function detectFieldMislabel(args) {
+    const { op, narration, draft } = args;
+    const block = draft.get(op.pageSlug)?.blocks.find((b) => b.id === op.blockId);
+    const meta = block ? getBlockMeta(block.type) : undefined;
+    if (!block || !meta)
+        return null;
+    const changedKeys = Object.keys(op.patch ?? {});
+    if (changedKeys.length === 0)
+        return null;
+    const siblingKeys = Object.keys(meta.fields ?? {}).filter((k) => !changedKeys.includes(k));
+    if (siblingKeys.length === 0)
+        return null;
+    const name = meta.displayName ?? block.type;
+    const text = narration.toLowerCase();
+    // The block name itself ("Hero") shows up in most field labels ("Hero image")
+    // and in the narration ("the Hero block"), so its tokens carry no field signal —
+    // ignore them, or "Hero image" would match every mention of the Hero block.
+    const ignore = new Set(labelTokens(name));
+    const changedTokens = new Set(changedKeys.flatMap((k) => labelTokens(getPropDisplayName(block.type, k))).concat(changedKeys.map((k) => k.toLowerCase())));
+    // A patch on a LIST field (e.g. `cards`) legitimately edits its ITEM fields (a
+    // card's title/description). Those item-field names share tokens with scalar
+    // siblings — a CardGrid has both a scalar `title` ("Section title") and a card
+    // `title`. Without folding the changed list's item-field tokens in, accurate
+    // narration like "Renamed the first card title." reads as naming the scalar
+    // sibling and we'd overwrite it with a vaguer label. Treat them as "changed".
+    for (const k of changedKeys) {
+        const listMeta = meta.listFields?.[k];
+        if (!listMeta)
+            continue;
+        for (const [itemKey, itemMeta] of Object.entries(listMeta.itemFields ?? {})) {
+            changedTokens.add(itemKey.toLowerCase());
+            for (const t of labelTokens(itemMeta.label ?? itemKey))
+                changedTokens.add(t);
+        }
+    }
+    const siblingTokens = new Set(siblingKeys.flatMap((k) => labelTokens(getPropDisplayName(block.type, k))));
+    // Does the narration name a sibling field by a token unique to it (not shared
+    // with a changed field, not the block name)?
+    const namesWrongSibling = siblingKeys.some((k) => labelTokens(getPropDisplayName(block.type, k))
+        .filter((t) => !changedTokens.has(t) && !ignore.has(t))
+        .some((t) => word(t).test(text)));
+    if (!namesWrongSibling)
+        return null;
+    // Does it reference any CHANGED field by a token NOT shared with a sibling or
+    // the block name?
+    const mentionsChanged = changedKeys.some((k) => {
+        const tokens = labelTokens(getPropDisplayName(block.type, k)).filter((t) => !siblingTokens.has(t) && !ignore.has(t));
+        tokens.push(k.toLowerCase());
+        return tokens.some((t) => word(t).test(text));
+    });
+    if (mentionsChanged)
+        return null;
+    const labels = changedKeys.map((k) => getPropDisplayName(block.type, k));
+    return { replacement: `Will update the ${name} ${labels.join(", ")}.` };
+}
+function lookupBlockTypeName(args) {
+    const { blockId, pageSlug, draft } = args;
+    const page = draft.get(pageSlug);
+    const hit = page?.blocks.find((b) => b.id === blockId);
+    if (!hit)
+        return undefined;
+    return getBlockMeta(hit.type)?.displayName ?? hit.type;
+}
+function describeBlockOp(args) {
+    const name = lookupBlockTypeName(args);
+    return name ? `Will ${args.verb} the ${name} block.` : `Will ${args.verb} a block.`;
+}
+function describeOp(op, draft) {
+    switch (op.op) {
+        case "update_props":
+            return describeBlockOp({ verb: "update", blockId: op.blockId, pageSlug: op.pageSlug, draft });
+        case "add_block": {
+            const name = getBlockMeta(op.block.type)?.displayName ?? op.block.type;
+            return `Will add a new ${name} block.`;
+        }
+        case "remove_block":
+            return describeBlockOp({ verb: "remove", blockId: op.blockId, pageSlug: op.pageSlug, draft });
+        case "move_block":
+            return describeBlockOp({ verb: "reorder", blockId: op.blockId, pageSlug: op.pageSlug, draft });
+        case "duplicate_block":
+            return describeBlockOp({ verb: "duplicate", blockId: op.blockId, pageSlug: op.pageSlug, draft });
+        case "add_item":
+            return describeBlockOp({ verb: "add an item to", blockId: op.blockId, pageSlug: op.pageSlug, draft });
+        case "update_item":
+            return describeBlockOp({ verb: "update an item in", blockId: op.blockId, pageSlug: op.pageSlug, draft });
+        case "remove_item":
+            return describeBlockOp({ verb: "remove an item from", blockId: op.blockId, pageSlug: op.pageSlug, draft });
+        case "move_item":
+            return describeBlockOp({ verb: "reorder an item in", blockId: op.blockId, pageSlug: op.pageSlug, draft });
+        case "reorder_items":
+            return describeBlockOp({ verb: "reorder the items in", blockId: op.blockId, pageSlug: op.pageSlug, draft });
+        case "reorder_blocks":
+            return `Will reorder the sections on ${op.pageSlug}.`;
+        case "create_page":
+            return `Will create page ${op.page.slug}.`;
+        case "remove_page":
+            return `Will remove page ${op.pageSlug}.`;
+        case "rename_page":
+            return `Will rename page ${op.pageSlug}.`;
+        case "move_page":
+            return `Will reorder page ${op.pageSlug}.`;
+        case "duplicate_page":
+            return `Will duplicate page ${op.pageSlug}.`;
+        case "update_page_meta":
+            return "Will update page metadata.";
+        case "update_site_config":
+            return "Will update site settings.";
+        case "update_theme":
+            return "Will update the site theme.";
+        default: {
+            const _exhaustive = op;
+            return "Will apply an additional change.";
+        }
+    }
+}
+/**
+ * Ensure change_log has at least one entry per op for edit_plan intents.
+ * When short, synthesize a generic entry per uncovered op so the user sees
+ * an accurate count of changes. Non-edit_plan intents and empty ops lists
+ * are passed through unchanged.
+ */
+export function validateChangelogCoverage(args) {
+    const { plan, draft } = args;
+    const empty = {
+        plan,
+        missingCount: 0,
+        synthesizedEntries: [],
+        extraCount: 0,
+        droppedEntries: [],
+        fieldMislabelCount: 0,
+        relabeledEntries: []
+    };
+    if (plan.intent !== "edit_plan")
+        return empty;
+    const opCount = plan.ops.length;
+    // Field-level pass (#13): an update_props entry can be the right COUNT yet name
+    // the wrong field. Relabel each mislabeled update_props entry from the op's
+    // actual patch; for a single-op plan also correct the summary, which carries the
+    // same false claim. Runs before the count logic so it applies at equal counts.
+    const relabeledEntries = [];
+    for (let i = 0; i < plan.ops.length; i++) {
+        const op = plan.ops[i];
+        if (op.op !== "update_props")
+            continue;
+        const entry = i < plan.change_log.length ? plan.change_log[i] : "";
+        const narration = opCount === 1 ? `${entry} ${plan.summary_for_user ?? ""}` : entry;
+        const mislabel = detectFieldMislabel({ op, narration, draft });
+        if (!mislabel)
+            continue;
+        if (i < plan.change_log.length)
+            plan.change_log[i] = mislabel.replacement;
+        if (opCount === 1)
+            plan.summary_for_user = mislabel.replacement;
+        relabeledEntries.push(mislabel.replacement);
+    }
+    const changeCount = plan.change_log.length;
+    if (changeCount === opCount) {
+        return { ...empty, fieldMislabelCount: relabeledEntries.length, relabeledEntries };
+    }
+    // Empty ops list with non-empty change_log is almost always a planner
+    // confusion (intent should have been content_answer). Leave it for
+    // higher-level handling rather than wiping the user-facing copy here.
+    if (opCount === 0)
+        return empty;
+    if (changeCount < opCount) {
+        const missingCount = opCount - changeCount;
+        const synthesizedEntries = [];
+        for (let i = changeCount; i < opCount; i++) {
+            synthesizedEntries.push(describeOp(plan.ops[i], draft));
+        }
+        plan.change_log = [...plan.change_log, ...synthesizedEntries];
+        return { plan, missingCount, synthesizedEntries, extraCount: 0, droppedEntries: [], fieldMislabelCount: relabeledEntries.length, relabeledEntries };
+    }
+    // changeCount > opCount: planner described more changes than it emitted ops
+    // for. Trim trailing entries so the approval UI matches reality.
+    const extraCount = changeCount - opCount;
+    const droppedEntries = plan.change_log.slice(opCount);
+    plan.change_log = plan.change_log.slice(0, opCount);
+    return { plan, missingCount: 0, synthesizedEntries: [], extraCount, droppedEntries, fieldMislabelCount: relabeledEntries.length, relabeledEntries };
+}

package/dist/chat/chat-pipeline-context.d.ts

@@ -0,0 +1,211 @@
+import { plannerContextPack } from "../nlp/deterministic-planner.ts";
+import type { EditPlan, PageDoc } from "@avocadostudio-ai/shared";
+import { type TranslationScope } from "./chat-pipeline-translation.ts";
+export declare function shouldPreferFastModelForMessage(message: string): boolean;
+/**
+ * Returns true when the message is complex/ambiguous enough that we should
+ * auto-escalate to an Anthropic thinking-capable model with extended thinking
+ * enabled. Designed to complement `shouldPreferFastModelForMessage` (which
+ * downgrades simple edits) — this one upgrades.
+ *
+ * Positive signals:
+ *   - Multi-step / decomposable request
+ *   - Clarification follow-up (user is correcting an earlier result)
+ *   - Structural verbs suggesting site-level reasoning (restructure, redesign,
+ *     reorganize, rewrite tone, convert into, persuasive, narrative)
+ *   - Long request with multiple quoted values (compound multi-field)
+ */
+export declare function shouldEnableReasoningForMessage(message: string): boolean;
+export declare function shouldUseLlmIntentRouter(message: string): boolean;
+export declare function compactPlannerContextPack(args: {
+    contextPack: ReturnType<typeof plannerContextPack>;
+    message: string;
+    translationScope: TranslationScope;
+}): {
+    selected: {
+        blockId: string | null;
+        blockType: string | null;
+        editablePath: string | null;
+        block: {
+            id: string;
+            type: import("@avocadostudio-ai/shared").BlockType;
+            props: Record<string, unknown>;
+            selectedEditablePath: string | null;
+            selectedEditableValue: {} | null;
+        } | null;
+        imageUrlForVision: string | null;
+    };
+    neighbors: {
+        previous: {
+            id: string;
+            type: import("@avocadostudio-ai/shared").BlockType;
+        } | null;
+        next: {
+            id: string;
+            type: import("@avocadostudio-ai/shared").BlockType;
+        } | null;
+    };
+    pageOutline: {
+        id: string;
+        type: import("@avocadostudio-ai/shared").BlockType;
+        props: Record<string, unknown>;
+        arrayProps: Record<string, {
+            length: number;
+            labels?: string[];
+        }>;
+    }[];
+    pageMeta: import("@avocadostudio-ai/shared").PageMeta | null;
+    pageIntent: string;
+    recentSuccessfulEdits: {
+        at: string;
+        summary: string;
+        ops: ("update_props" | "create_page" | "add_block" | "remove_block" | "move_block" | "duplicate_block" | "add_item" | "update_item" | "remove_item" | "move_item" | "reorder_items" | "reorder_blocks" | "rename_page" | "remove_page" | "move_page" | "duplicate_page" | "update_page_meta" | "update_site_config" | "update_theme")[];
+    }[];
+    resolvedReferences: {
+        target: {
+            id: string;
+            type: import("@avocadostudio-ai/shared").BlockType;
+        } | null;
+        anchor: {
+            id: string;
+            type: import("@avocadostudio-ai/shared").BlockType;
+        } | null;
+        mentionedBlocks: {
+            id: string;
+            type: import("@avocadostudio-ai/shared").BlockType;
+            reason: string;
+        }[];
+    };
+    siteConfig: {
+        name: string | null;
+        logo: string | null;
+        navLabels: Record<string, string>;
+        navGroups: Record<string, string[]>;
+        defaultNavLabels: Record<string, string>;
+        editPath: string;
+    };
+    attachments?: {
+        id: string;
+        kind: "image" | "pdf";
+        url: string;
+        mimeType: string;
+        name?: string | undefined;
+        bytes?: number | undefined;
+    }[] | undefined;
+    route: string;
+    pageRoutes: string[];
+    blockCount: number;
+};
+export declare function minimalPlannerContextPack(args: {
+    contextPack: ReturnType<typeof plannerContextPack>;
+}): {
+    selected: {
+        blockId: string | null;
+        blockType: string | null;
+        editablePath: string | null;
+        block: {
+            id: string;
+            type: import("@avocadostudio-ai/shared").BlockType;
+            props: Record<string, unknown>;
+            selectedEditablePath: string | null;
+            selectedEditableValue: {} | null;
+        } | null;
+        imageUrlForVision: string | null;
+    };
+    neighbors: {
+        previous: {
+            id: string;
+            type: import("@avocadostudio-ai/shared").BlockType;
+        } | null;
+        next: {
+            id: string;
+            type: import("@avocadostudio-ai/shared").BlockType;
+        } | null;
+    };
+    pageOutline: {
+        id: string;
+        type: import("@avocadostudio-ai/shared").BlockType;
+        props: Record<string, unknown>;
+        arrayProps: Record<string, {
+            length: number;
+            labels?: string[];
+        }>;
+    }[];
+    pageMeta: import("@avocadostudio-ai/shared").PageMeta | null;
+    pageIntent: string;
+    recentSuccessfulEdits: {
+        at: string;
+        summary: string;
+        ops: ("update_props" | "create_page" | "add_block" | "remove_block" | "move_block" | "duplicate_block" | "add_item" | "update_item" | "remove_item" | "move_item" | "reorder_items" | "reorder_blocks" | "rename_page" | "remove_page" | "move_page" | "duplicate_page" | "update_page_meta" | "update_site_config" | "update_theme")[];
+    }[];
+    resolvedReferences: {
+        target: {
+            id: string;
+            type: import("@avocadostudio-ai/shared").BlockType;
+        } | null;
+        anchor: {
+            id: string;
+            type: import("@avocadostudio-ai/shared").BlockType;
+        } | null;
+        mentionedBlocks: {
+            id: string;
+            type: import("@avocadostudio-ai/shared").BlockType;
+            reason: string;
+        }[];
+    };
+    siteConfig: {
+        name: string | null;
+        logo: string | null;
+        navLabels: Record<string, string>;
+        navGroups: Record<string, string[]>;
+        defaultNavLabels: Record<string, string>;
+        editPath: string;
+    };
+    attachments?: {
+        id: string;
+        kind: "image" | "pdf";
+        url: string;
+        mimeType: string;
+        name?: string | undefined;
+        bytes?: number | undefined;
+    }[] | undefined;
+    route: string;
+    pageRoutes: string[];
+    blockCount: number;
+};
+export declare function shouldUseMinimalPlannerContext(args: {
+    message: string;
+    translationScope: TranslationScope;
+    activeBlockId?: string;
+    activeEditablePath?: string;
+}): boolean;
+export declare function shouldPreferFocusedTranslation(args: {
+    message: string;
+    inferredScope: TranslationScope;
+    activeBlockId?: string;
+}): boolean;
+/**
+ * Uses the deterministic planner's intent analysis to classify message
+ * complexity, providing more accurate context packing decisions than
+ * the pure-regex heuristics in shouldPreferFastModelForMessage.
+ *
+ * Returns "simple" when the intent is fully resolvable from the message
+ * (add/remove/move with clear target, or update with extracted patch).
+ * Returns "standard" otherwise.
+ */
+export declare function classifyMessageComplexity(args: {
+    message: string;
+    currentPage: PageDoc;
+    activeBlockId?: string;
+    activeEditablePath?: string;
+    translationScope: TranslationScope;
+}): "simple" | "standard";
+/**
+ * Checks whether a router plan is too shallow for the message's intent.
+ *
+ * Returns true when the message signals content generation need (e.g.,
+ * "add a compelling hero about our mission") but the router plan only
+ * has default/placeholder props. In this case the full planner should
+ * be preferred.
+ */
+export declare function isRouterPlanTooShallow(message: string, plan: EditPlan): boolean;