@avocadostudio-ai/orchestrator-core 0.11.8 → 0.12.0

package/dist/agent/sites-agent-shared.d.ts

@@ -4,6 +4,7 @@
  *
  * Contains: prop validation/correction, CSS patching, port allocation, site ID sanitization.
  */
+import { type Logger } from "../logger.ts";
 export declare function sanitizeSiteId(name: string): string;
 export declare function monorepoRoot(): string;
 /**
@@ -15,7 +16,7 @@ export declare function monorepoRoot(): string;
  * forgotten.
  */
 export declare function getDraftModeSecret(): string;
-export declare function findAvailablePort(root: string): Promise<number>;
+export declare function findAvailablePort(root: string, log?: Logger): Promise<number>;
 export interface ThemePreset {
     name: string;
     description: string;
@@ -52,10 +53,10 @@ export type TriageResult = {
  * Fast triage using Haiku — classifies intent, extracts params, answers simple questions.
  * ~200ms, ~$0.001 per call.
  */
-export declare function triageWithHaiku(message: string, apiKey: string): Promise<TriageResult>;
+export declare function triageWithHaiku(message: string, apiKey: string, log?: Logger): Promise<TriageResult>;
 export declare function patchGlobalsCssVars(cssPath: string, vars: Record<string, string>): Promise<void>;
 export declare function fixFooterLinks(props: Record<string, unknown>): Record<string, unknown>;
-export declare function validateAndCorrectProps(blockType: string, props: Record<string, unknown>): {
+export declare function validateAndCorrectProps(blockType: string, props: Record<string, unknown>, log?: Logger): {
     props: Record<string, unknown>;
     corrected: boolean;
     error?: string;
@@ -67,7 +68,7 @@ export declare function validateAndCorrectProps(blockType: string, props: Record
 export declare function normalizePageBlocks(blocks: Array<{
     type: string;
     props: Record<string, unknown>;
-}>): {
+}>, log?: Logger): {
     contentBlocks: Array<{
         id: string;
         type: string;
@@ -156,6 +157,8 @@ export declare function startAndWaitForDevServer(opts: {
     cwd: string;
     useFilter?: boolean;
     timeoutMs?: number;
+    /** Where progress goes. Defaults to `consoleLogger()`. */
+    logger?: Logger;
 }): Promise<{
     serverReady: boolean;
 }>;

package/dist/agent/sites-agent-shared.js

@@ -4,6 +4,7 @@
  *
  * Contains: prop validation/correction, CSS patching, port allocation, site ID sanitization.
  */
+import { consoleLogger } from "../logger.js";
 import { mkdir, writeFile, readFile, readdir, stat } from "node:fs/promises";
 import { existsSync } from "node:fs";
 import { resolve, join, dirname } from "node:path";
@@ -30,7 +31,7 @@ export function monorepoRoot() {
 export function getDraftModeSecret() {
     return process.env.DRAFT_MODE_SECRET ?? "top-secret";
 }
-export async function findAvailablePort(root) {
+export async function findAvailablePort(root, log = consoleLogger()) {
     const appsDir = join(root, "apps");
     const usedPorts = new Set([3000, 4100, 4200]);
     try {
@@ -58,7 +59,7 @@ export async function findAvailablePort(root) {
     let port = 3500;
     while (usedPorts.has(port) || !(await isPortFree(createServer, port)))
         port++;
-    console.log(`[sites-agent] Selected port ${port} (used: ${[...usedPorts].sort().join(", ")})`);
+    log.info(`[sites-agent] Selected port ${port} (used: ${[...usedPorts].sort().join(", ")})`);
     return port;
 }
 function isPortFree(createServer, port) {
@@ -217,7 +218,7 @@ export const SITES_AGENT_MODELS = {
  * Fast triage using Haiku — classifies intent, extracts params, answers simple questions.
  * ~200ms, ~$0.001 per call.
  */
-export async function triageWithHaiku(message, apiKey) {
+export async function triageWithHaiku(message, apiKey, log = consoleLogger()) {
     const { default: Anthropic } = await import("@anthropic-ai/sdk");
     const client = new Anthropic({ apiKey });
     const response = await client.messages.create({
@@ -259,11 +260,11 @@ Extract URLs, site names, and scope constraints from the message. If not present
         // Strip markdown code fences if present
         const clean = text.replace(/^```json?\s*|\s*```$/g, "").trim();
         const parsed = JSON.parse(clean);
-        console.log(`[sites-agent] Triage: intent=${parsed.intent} url=${parsed.url ?? "-"} site=${parsed.siteName ?? "-"} scope=${parsed.scope ?? "-"}`);
+        log.info(`[sites-agent] Triage: intent=${parsed.intent} url=${parsed.url ?? "-"} site=${parsed.siteName ?? "-"} scope=${parsed.scope ?? "-"}`);
         return parsed;
     }
     catch {
-        console.log(`[sites-agent] Triage parse failed, defaulting to migrate: ${text.slice(0, 100)}`);
+        log.info(`[sites-agent] Triage parse failed, defaulting to migrate: ${text.slice(0, 100)}`);
         return { intent: "migrate" };
     }
 }
@@ -366,7 +367,7 @@ function renameKeys(obj, renames) {
     }
     return result;
 }
-export function validateAndCorrectProps(blockType, props) {
+export function validateAndCorrectProps(blockType, props, log = consoleLogger()) {
     const first = validateBlockProps(blockType, props);
     if (first.success)
         return { props, corrected: false };
@@ -382,7 +383,7 @@ export function validateAndCorrectProps(blockType, props) {
         corrected = fixFooterLinks(corrected);
     const second = validateBlockProps(blockType, corrected);
     if (second.success) {
-        console.log(`[sites-agent] Auto-corrected ${blockType} props`);
+        log.info(`[sites-agent] Auto-corrected ${blockType} props`);
         return { props: corrected, corrected: true };
     }
     const errorMsg = first.success === false && "error" in first
@@ -394,7 +395,7 @@ export function validateAndCorrectProps(blockType, props) {
  * Normalize and validate blocks for a page — applies prop correction, strips chrome blocks,
  * extracts footer. Shared between SDK and stdio bootstrap_pages implementations.
  */
-export function normalizePageBlocks(blocks) {
+export function normalizePageBlocks(blocks, log = consoleLogger()) {
     let strippedCount = 0;
     let footerBlock = null;
     const contentBlocks = blocks
@@ -432,7 +433,7 @@ export function normalizePageBlocks(blocks) {
                 }
             }
             else if (validation.error) {
-                console.warn(`[sites-agent] ${b.type} block validation: ${validation.error}`);
+                log.warn(`[sites-agent] ${b.type} block validation: ${validation.error}`);
             }
         }
         return { id: `b_${b.type.toLowerCase()}_${i + 1}`, type: b.type, props: mergedProps };
@@ -1043,6 +1044,7 @@ export async function detectSitePort(projectDir) {
  * Replaces fire-and-forget spawn patterns that reported success before the server was up.
  */
 export async function startAndWaitForDevServer(opts) {
+    const log = opts.logger ?? consoleLogger();
     const { spawn } = await import("node:child_process");
     const args = opts.useFilter
         ? ["--filter", `@ai-site-editor/${opts.siteId}`, "dev"]
@@ -1058,11 +1060,11 @@ export async function startAndWaitForDevServer(opts) {
                 }
                 catch { /* already dead */ }
             }
-            console.log(`[sites-agent] Killed existing process(es) on port ${opts.port}`);
+            log.info(`[sites-agent] Killed existing process(es) on port ${opts.port}`);
         }
     }
     catch { /* no process on port — fine */ }
-    console.log(`[sites-agent] Starting dev server for ${opts.siteId} on port ${opts.port}...`);
+    log.info(`[sites-agent] Starting dev server for ${opts.siteId} on port ${opts.port}...`);
     const devProcess = spawn("pnpm", args, {
         cwd: opts.cwd,
         stdio: ["ignore", "pipe", "pipe"],
@@ -1097,6 +1099,6 @@ export async function startAndWaitForDevServer(opts) {
         devProcess.stderr?.on("data", onData);
         devProcess.on("exit", () => { clearTimeout(timer); resolve(); });
     });
-    console.log(`[sites-agent] Dev server ${serverReady ? "ready" : "timed out"} for ${opts.siteId} at http://localhost:${opts.port}`);
+    log.info(`[sites-agent] Dev server ${serverReady ? "ready" : "timed out"} for ${opts.siteId} at http://localhost:${opts.port}`);
     return { serverReady };
 }

package/dist/agent/sites-agent-tools.d.ts

@@ -5,6 +5,7 @@
  * - list_sites, create_site, scrape_url (with screenshot), extract_design_tokens,
  *   bootstrap_pages, download_remote_image, apply_theme, discover_site_structure
  */
+import { type Logger } from "../logger.ts";
 /**
  * Create the MCP server with all sites-agent tools.
  */
@@ -15,4 +16,15 @@ export declare function createSitesAgentMcpServer(options: {
         tool: string;
         data: Record<string, unknown>;
     }) => void;
+    /**
+     * Where these tools report progress. Defaults to `consoleLogger()`.
+     *
+     * It matters that this is a parameter. This module is published, and it had
+     * forty-two bare `console.log` calls writing `[create_site] …` onto whatever
+     * stdout the host happened to own — unsilenceable, unstructured, and outside
+     * the `Logger` seam the rest of the package already threads through. The
+     * Fastify host passes its own request logger; a library consumer passes
+     * theirs, or takes the console default knowingly.
+     */
+    logger?: Logger;
 }): import("@anthropic-ai/claude-agent-sdk").McpSdkServerConfigWithInstance;

package/dist/agent/sites-agent-tools.js

@@ -10,6 +10,7 @@ import { join, dirname } from "node:path";
 import { existsSync } from "node:fs";
 import { tool, createSdkMcpServer } from "@anthropic-ai/claude-agent-sdk";
 import { createMigrationTools } from "../migration/migration-tools.js";
+import { consoleLogger } from "../logger.js";
 import { z } from "zod";
 import { getAllBlockMeta, defaultPropsForType } from "@avocadostudio-ai/shared";
 import { fetchPageContent, downloadImage, extractDesignTokens, mapToThemeVariables, discoverSitePages, scrapeFullPage } from "@avocadostudio-ai/migration-sdk";
@@ -34,18 +35,18 @@ function isRemoteImageUrl(url) {
     return IMAGE_URL_RE.test(url) || IMAGE_CDN_RE.test(url);
 }
 /** Recursively walk props and download any remote image URLs, replacing with local paths. */
-async function localizeRemoteImages(props, imagesDir) {
+async function localizeRemoteImages(props, imagesDir, log) {
     let downloaded = 0;
     async function walk(value) {
         if (typeof value === "string" && isRemoteImageUrl(value)) {
             try {
                 const result = await downloadImage(value, undefined, imagesDir);
                 downloaded++;
-                console.log(`[sites-agent] Auto-downloaded remote image: ${value} → ${result.localPath}`);
+                log.info(`[sites-agent] Auto-downloaded remote image: ${value} → ${result.localPath}`);
                 return `/images/${result.fileName}`;
             }
             catch {
-                console.warn(`[sites-agent] Failed to auto-download image: ${value}`);
+                log.warn(`[sites-agent] Failed to auto-download image: ${value}`);
                 return value;
             }
         }
@@ -70,6 +71,7 @@ async function localizeRemoteImages(props, imagesDir) {
  */
 export function createSitesAgentMcpServer(options) {
     const { session, emitSiteCreated, emitPhaseOutcome } = options;
+    const log = options.logger ?? consoleLogger();
     // ── LIST SITES ──
     const listSitesTool = tool("list_sites", "List all site project directories in the monorepo apps/ folder.", {}, async () => {
         try {
@@ -99,9 +101,9 @@ export function createSitesAgentMcpServer(options) {
         url: z.string().describe("Homepage URL of the site to analyze, e.g. 'https://example.com'"),
     }, async (args) => {
         try {
-            console.log(`[discover_structure] Discovering pages on ${args.url}...`);
+            log.info(`[discover_structure] Discovering pages on ${args.url}...`);
             const structure = await discoverSitePages(args.url);
-            console.log(`[discover_structure] Found ${structure.totalFound} pages via ${structure.source} on ${structure.origin}`);
+            log.info(`[discover_structure] Found ${structure.totalFound} pages via ${structure.source} on ${structure.origin}`);
             emitPhaseOutcome?.({ tool: "discover_site_structure", data: { totalPages: structure.totalFound, origin: structure.origin } });
             return {
                 content: [{
@@ -140,7 +142,7 @@ export function createSitesAgentMcpServer(options) {
                     if (existsSync(target))
                         await rm(target, { recursive: true, force: true });
                 }
-                console.log(`[sites-agent] Cleaned previous content from apps/${siteId}`);
+                log.info(`[sites-agent] Cleaned previous content from apps/${siteId}`);
                 // Reuse the existing port if not explicitly overridden
                 if (!args.port) {
                     try {
@@ -163,49 +165,54 @@ export function createSitesAgentMcpServer(options) {
                     s.listen(port, "127.0.0.1");
                 });
                 if (!free) {
-                    console.log(`[create_site] Requested port ${port} in use, auto-assigning...`);
+                    log.info(`[create_site] Requested port ${port} in use, auto-assigning...`);
                     port = 0;
                 }
             }
             if (!port)
-                port = await findAvailablePort(root);
-            console.log(`[create_site] START siteId=${siteId} port=${port} name="${args.name}"`);
-            // Create project structure
-            await mkdir(projectDir, { recursive: true });
-            await writeFile(join(projectDir, "package.json"), packageJson(siteId, args.name, port), "utf-8");
-            await writeFile(join(projectDir, "next.config.ts"), nextConfigTs(), "utf-8");
-            await writeFile(join(projectDir, "tsconfig.json"), tsconfigJson(), "utf-8");
-            await writeFile(join(projectDir, "postcss.config.mjs"), postcssConfig(), "utf-8");
-            await mkdir(join(projectDir, "app"), { recursive: true });
-            await writeFile(join(projectDir, "app/layout.tsx"), layoutTsx(args.name), "utf-8");
-            await writeFile(join(projectDir, "app/globals.css"), globalsCss(), "utf-8");
-            await mkdir(join(projectDir, "app/api/editor/[...path]"), { recursive: true });
-            await writeFile(join(projectDir, "app/api/editor/[...path]/route.ts"), editorApiRoute(), "utf-8");
-            await mkdir(join(projectDir, "app/[[...slug]]"), { recursive: true });
-            await writeFile(join(projectDir, "app/[[...slug]]/page.tsx"), pageTsx(siteId), "utf-8");
-            await mkdir(join(projectDir, "content"), { recursive: true });
-            await writeFile(join(projectDir, "content/pages.json"), samplePagesJson(), "utf-8");
-            await mkdir(join(projectDir, "lib"), { recursive: true });
-            await writeFile(join(projectDir, "lib/defaults.ts"), defaultsTs(siteId, args.name), "utf-8");
-            await mkdir(join(projectDir, "public"), { recursive: true });
-            await writeFile(join(projectDir, "public/.gitkeep"), "", "utf-8");
-            await mkdir(join(projectDir, "blocks"), { recursive: true });
-            await writeFile(join(projectDir, "blocks/register.tsx"), blocksRegisterTsx(), "utf-8");
-            await writeFile(join(projectDir, "public/logo.svg"), defaultLogoSvg(args.name), "utf-8");
-            await writeFile(join(projectDir, "public/favicon.svg"), faviconSvg(args.name), "utf-8");
+                port = await findAvailablePort(root, log);
+            log.info(`[create_site] START siteId=${siteId} port=${port} name="${args.name}"`);
+            // Create project structure.
+            //
+            // One entry per file, and the log line below counts the list rather than
+            // a number someone typed. It used to say "Wrote 13 project files" while
+            // writing fifteen — the count was right when the sequence of writeFile
+            // calls above it was shorter, and nothing connected the two.
             const envContent = `ORCHESTRATOR_URL=http://localhost:4200\nDRAFT_MODE_SECRET=${getDraftModeSecret()}\nNEXT_PUBLIC_DEFAULT_SITE_ID=${siteId}\nNEXT_PUBLIC_SITE_NAME=${args.name}\nNEXT_PUBLIC_EDITOR_ORIGIN=http://localhost:4100\n`;
-            await writeFile(join(projectDir, ".env.local"), envContent, "utf-8");
-            console.log(`[create_site] Wrote 13 project files to apps/${siteId}/`);
+            const projectFiles = [
+                ["package.json", packageJson(siteId, args.name, port)],
+                ["next.config.ts", nextConfigTs()],
+                ["tsconfig.json", tsconfigJson()],
+                ["postcss.config.mjs", postcssConfig()],
+                ["app/layout.tsx", layoutTsx(args.name)],
+                ["app/globals.css", globalsCss()],
+                ["app/api/editor/[...path]/route.ts", editorApiRoute()],
+                ["app/[[...slug]]/page.tsx", pageTsx(siteId)],
+                ["content/pages.json", samplePagesJson()],
+                ["lib/defaults.ts", defaultsTs(siteId, args.name)],
+                ["public/.gitkeep", ""],
+                ["blocks/register.tsx", blocksRegisterTsx()],
+                ["public/logo.svg", defaultLogoSvg(args.name)],
+                ["public/favicon.svg", faviconSvg(args.name)],
+                [".env.local", envContent]
+            ];
+            await mkdir(projectDir, { recursive: true });
+            for (const [relativePath, contents] of projectFiles) {
+                const target = join(projectDir, relativePath);
+                await mkdir(dirname(target), { recursive: true });
+                await writeFile(target, contents, "utf-8");
+            }
+            log.info(`[create_site] Wrote ${projectFiles.length} project files to apps/${siteId}/`);
             // Run pnpm install if needed (skip if node_modules exists from previous run)
             if (!existsSync(join(projectDir, "node_modules"))) {
-                console.log(`[create_site] Running pnpm install...`);
+                log.info(`[create_site] Running pnpm install...`);
                 const { execFile } = await import("node:child_process");
                 const { promisify } = await import("node:util");
                 await promisify(execFile)("pnpm", ["install", "--no-frozen-lockfile"], { cwd: root, timeout: 60_000 });
-                console.log(`[create_site] pnpm install complete`);
+                log.info(`[create_site] pnpm install complete`);
             }
             else {
-                console.log(`[create_site] Skipping pnpm install — node_modules exists`);
+                log.info(`[create_site] Skipping pnpm install — node_modules exists`);
             }
             const siteConfig = {
                 id: siteId,
@@ -223,14 +230,15 @@ export function createSitesAgentMcpServer(options) {
             });
             bumpVersion(sessionKey);
             // Start dev server and wait for it to be ready
-            console.log(`[create_site] Starting dev server on port ${port}...`);
+            log.info(`[create_site] Starting dev server on port ${port}...`);
             const { serverReady } = await startAndWaitForDevServer({
+                logger: log,
                 siteId, port, cwd: root, useFilter: true,
             });
-            console.log(`[create_site] Dev server ${serverReady ? "READY" : "FAILED"} on port ${port}`);
+            log.info(`[create_site] Dev server ${serverReady ? "READY" : "FAILED"} on port ${port}`);
             emitSiteCreated(siteConfig);
             emitPhaseOutcome?.({ tool: "create_site", data: { siteId, port, name: args.name, serverReady } });
-            console.log(`[create_site] DONE siteId=${siteId} port=${port} serverReady=${serverReady}`);
+            log.info(`[create_site] DONE siteId=${siteId} port=${port} serverReady=${serverReady}`);
             return {
                 content: [{
                         type: "text",
@@ -248,7 +256,7 @@ export function createSitesAgentMcpServer(options) {
             };
         }
         catch (e) {
-            console.error(`[create_site] ERROR: ${e instanceof Error ? e.message : String(e)}`);
+            log.error(`[create_site] ERROR: ${e instanceof Error ? e.message : String(e)}`);
             return { content: [{ type: "text", text: `Error: ${e instanceof Error ? e.message : String(e)}` }], isError: true };
         }
     }, { annotations: { destructiveHint: false, openWorldHint: false } });
@@ -261,12 +269,12 @@ export function createSitesAgentMcpServer(options) {
             let result = getCachedScrape(args.url);
             const cached = !!result;
             if (!result) {
-                console.log(`[scrape_url] Scraping ${args.url} (browser)...`);
+                log.info(`[scrape_url] Scraping ${args.url} (browser)...`);
                 result = await scrapeFullPage(args.url);
                 setCachedScrape(args.url, result);
             }
             const { content, screenshot, sections, outline, nav } = result;
-            console.log(`[scrape_url] ${cached ? "CACHED" : "SCRAPED"} ${args.url} in ${Date.now() - scrapeStart}ms — ${sections.length} sections, screenshot=${!!screenshot}, nav=${!!nav}`);
+            log.info(`[scrape_url] ${cached ? "CACHED" : "SCRAPED"} ${args.url} in ${Date.now() - scrapeStart}ms — ${sections.length} sections, screenshot=${!!screenshot}, nav=${!!nav}`);
             // Extract design tokens from CSS (with resolved CSS variables from Playwright)
             const tokens = extractDesignTokens(content.css, result.resolvedCssVars);
             const themeVars = mapToThemeVariables(tokens);
@@ -305,13 +313,13 @@ export function createSitesAgentMcpServer(options) {
             if (mobileScreenshot)
                 writes.push(saveScreenshot("mobile", mobileScreenshot.base64, args.url));
             if (writes.length)
-                Promise.all(writes).then(() => console.log(`[scrape_url] Screenshots saved`)).catch(() => { });
+                Promise.all(writes).then(() => log.info(`[scrape_url] Screenshots saved`)).catch(() => { });
             return { content: contentBlocks };
         }
         catch (e) {
             // Fall back to simple HTTP fetch (no browser)
             try {
-                console.warn(`[sites-agent] Browser scrape failed, falling back to HTTP: ${e instanceof Error ? e.message : String(e)}`);
+                log.warn(`[sites-agent] Browser scrape failed, falling back to HTTP: ${e instanceof Error ? e.message : String(e)}`);
                 const content = await fetchPageContent(args.url);
                 const { extractSections: extract, extractPageOutline: outline, extractNavigation: navExtract } = await import("@avocadostudio-ai/migration-sdk");
                 const sections = extract(content.html, content.baseUrl);
@@ -391,12 +399,12 @@ export function createSitesAgentMcpServer(options) {
         try {
             const totalBlocks = args.pages.reduce((sum, p) => sum + p.blocks.length, 0);
             const slugs = args.pages.map(p => p.slug);
-            console.log(`[bootstrap_pages] START siteId=${args.siteId} pages=${args.pages.length} blocks=${totalBlocks} slugs=[${slugs.join(", ")}]`);
+            log.info(`[bootstrap_pages] START siteId=${args.siteId} pages=${args.pages.length} blocks=${totalBlocks} slugs=[${slugs.join(", ")}]`);
             // Verify the site project was scaffolded first
             const root = monorepoRoot();
             const projectPkg = join(root, "apps", args.siteId, "package.json");
             if (!existsSync(projectPkg)) {
-                console.error(`[bootstrap_pages] GUARD FAILED: apps/${args.siteId}/package.json not found — create_site was not called`);
+                log.error(`[bootstrap_pages] GUARD FAILED: apps/${args.siteId}/package.json not found — create_site was not called`);
                 return { content: [{ type: "text", text: `Error: Site project apps/${args.siteId} does not exist. Call create_site first.` }], isError: true };
             }
             const sessionKey = scopedSessionKey(session, args.siteId);
@@ -414,7 +422,7 @@ export function createSitesAgentMcpServer(options) {
             // Process pages sequentially to avoid unbounded concurrent image downloads
             const pageDocs = [];
             for (const [pageIdx, page] of normalizedPages.entries()) {
-                console.log(`[bootstrap_pages] Processing page ${pageIdx + 1}/${normalizedPages.length}: ${page.slug} (${page.blocks.length} blocks)`);
+                log.info(`[bootstrap_pages] Processing page ${pageIdx + 1}/${normalizedPages.length}: ${page.slug} (${page.blocks.length} blocks)`);
                 const contentBlocks = page.blocks.filter(b => {
                     if (b.type === "SiteHeader") {
                         strippedCount++;
@@ -423,7 +431,7 @@ export function createSitesAgentMcpServer(options) {
                     if (b.type === "Footer") {
                         if (!footerBlock) {
                             let fp = fixFooterLinks(b.props);
-                            const v = validateAndCorrectProps("Footer", fp);
+                            const v = validateAndCorrectProps("Footer", fp, log);
                             if (v.corrected)
                                 fp = v.props;
                             footerBlock = { type: b.type, props: fp };
@@ -441,26 +449,26 @@ export function createSitesAgentMcpServer(options) {
                         mergedProps[key] = value;
                     }
                     if (blockMeta) {
-                        const validation = validateAndCorrectProps(b.type, mergedProps);
+                        const validation = validateAndCorrectProps(b.type, mergedProps, log);
                         if (validation.corrected) {
-                            console.log(`[bootstrap_pages]   Block ${b.type}: auto-corrected props`);
+                            log.info(`[bootstrap_pages]   Block ${b.type}: auto-corrected props`);
                             mergedProps = { ...baseProps };
                             for (const [key, value] of Object.entries(validation.props)) {
                                 mergedProps[key] = value;
                             }
                         }
                         else if (validation.error) {
-                            console.warn(`[bootstrap_pages]   Block ${b.type}: validation error — ${validation.error}`);
+                            log.warn(`[bootstrap_pages]   Block ${b.type}: validation error — ${validation.error}`);
                         }
                     }
                     else if (!getAllBlockMeta()[b.type]) {
-                        console.log(`[bootstrap_pages]   Block ${b.type}: custom type (not in built-in registry)`);
+                        log.info(`[bootstrap_pages]   Block ${b.type}: custom type (not in built-in registry)`);
                     }
                     return { id: `b_${b.type.toLowerCase()}_${i + 1}`, type: b.type, props: mergedProps };
                 });
                 // Auto-download any remote image URLs the agent missed
                 for (const block of blocks) {
-                    const { props: localizedProps, downloaded } = await localizeRemoteImages(block.props, imagesDir);
+                    const { props: localizedProps, downloaded } = await localizeRemoteImages(block.props, imagesDir, log);
                     if (downloaded > 0) {
                         block.props = localizedProps;
                         totalAutoDownloaded += downloaded;
@@ -476,9 +484,9 @@ export function createSitesAgentMcpServer(options) {
                 });
             }
             if (strippedCount > 0)
-                console.log(`[sites-agent] Stripped ${strippedCount} chrome blocks (SiteHeader/Footer)`);
+                log.info(`[sites-agent] Stripped ${strippedCount} chrome blocks (SiteHeader/Footer)`);
             if (totalAutoDownloaded > 0)
-                console.log(`[sites-agent] Auto-downloaded ${totalAutoDownloaded} remote images as safety net`);
+                log.info(`[sites-agent] Auto-downloaded ${totalAutoDownloaded} remote images as safety net`);
             // Write to session state
             for (const doc of pageDocs)
                 setPage(sessionKey, doc);
@@ -523,10 +531,10 @@ export function createSitesAgentMcpServer(options) {
                 }
                 await mkdir(dirname(pagesJsonPath), { recursive: true });
                 await writeFile(pagesJsonPath, JSON.stringify(allPages, null, 2) + "\n", "utf-8");
-                console.log(`[sites-agent] Wrote ${allPages.length} pages to ${pagesJsonPath}`);
+                log.info(`[sites-agent] Wrote ${allPages.length} pages to ${pagesJsonPath}`);
             }
             catch (writeErr) {
-                console.warn(`[sites-agent] Failed to write pages.json:`, writeErr);
+                log.warn({ err: writeErr }, "[sites-agent] Failed to write pages.json");
             }
             // Persist site config (nav labels, nav groups, logo, name, footer) to content/site-config.json
             {
@@ -559,25 +567,25 @@ export function createSitesAgentMcpServer(options) {
                         config.footer = { id: "chrome_footer", type: fb.type, props: fb.props };
                     }
                     await writeFile(configPath, JSON.stringify(config, null, 2) + "\n", "utf-8");
-                    console.log(`[sites-agent] Wrote site config to ${configPath}`);
+                    log.info(`[sites-agent] Wrote site config to ${configPath}`);
                 }
                 catch (err) {
-                    console.warn(`[sites-agent] Failed to write site-config.json:`, err);
+                    log.warn({ err }, "[sites-agent] Failed to write site-config.json");
                 }
             }
             // Persist theme overrides to globals.css
             if (args.themeOverrides && Object.keys(args.themeOverrides).length > 0) {
                 try {
                     await patchGlobalsCssVars(join(root, "apps", args.siteId, "app", "globals.css"), args.themeOverrides);
-                    console.log(`[sites-agent] Updated ${Object.keys(args.themeOverrides).length} theme vars in globals.css`);
+                    log.info(`[sites-agent] Updated ${Object.keys(args.themeOverrides).length} theme vars in globals.css`);
                 }
                 catch (cssErr) {
-                    console.warn(`[sites-agent] Failed to update globals.css:`, cssErr);
+                    log.warn({ err: cssErr }, "[sites-agent] Failed to update globals.css");
                 }
             }
             const totalBlocksFinal = args.pages.reduce((sum, p) => sum + p.blocks.length, 0);
             emitPhaseOutcome?.({ tool: "bootstrap_pages", data: { pagesCreated: createdPages.length, totalBlocks: totalBlocksFinal, pages: createdPages } });
-            console.log(`[bootstrap_pages] DONE siteId=${args.siteId} pages=${createdPages.length} blocks=${totalBlocksFinal} autoDownloaded=${totalAutoDownloaded}`);
+            log.info(`[bootstrap_pages] DONE siteId=${args.siteId} pages=${createdPages.length} blocks=${totalBlocksFinal} autoDownloaded=${totalAutoDownloaded}`);
             return {
                 content: [{
                         type: "text",
@@ -591,7 +599,7 @@ export function createSitesAgentMcpServer(options) {
             };
         }
         catch (e) {
-            console.error(`[bootstrap_pages] ERROR: ${e instanceof Error ? e.message : String(e)}`);
+            log.error(`[bootstrap_pages] ERROR: ${e instanceof Error ? e.message : String(e)}`);
             return { content: [{ type: "text", text: `Error: ${e instanceof Error ? e.message : String(e)}` }], isError: true };
         }
     }, { annotations: { destructiveHint: false, openWorldHint: false } });
@@ -604,15 +612,15 @@ export function createSitesAgentMcpServer(options) {
         try {
             const root = monorepoRoot();
             const outputDir = join(root, "apps", args.siteId, "public", "images");
-            console.log(`[download_image] ${args.url.slice(0, 100)}`);
+            log.info(`[download_image] ${args.url.slice(0, 100)}`);
             const result = await downloadImage(args.url, args.alt, outputDir);
             const localUrl = `/images/${result.fileName}`;
-            console.log(`[download_image] OK → ${localUrl}`);
+            log.info(`[download_image] OK → ${localUrl}`);
             emitPhaseOutcome?.({ tool: "download_remote_image", data: { fileName: result.fileName } });
             return { content: [{ type: "text", text: JSON.stringify({ localUrl, fileName: result.fileName }) }] };
         }
         catch (e) {
-            console.warn(`[download_image] FAILED ${args.url.slice(0, 100)} — ${e instanceof Error ? e.message : String(e)}`);
+            log.warn(`[download_image] FAILED ${args.url.slice(0, 100)} — ${e instanceof Error ? e.message : String(e)}`);
             return { content: [{ type: "text", text: JSON.stringify({ localUrl: args.url, error: "Download failed, using original URL" }) }] };
         }
     }, { annotations: { destructiveHint: false, openWorldHint: true } });
@@ -644,7 +652,7 @@ export function createSitesAgentMcpServer(options) {
         }
         const succeeded = results.filter(r => !r.error).length;
         emitPhaseOutcome?.({ tool: "download_remote_images", data: { succeeded, total: results.length } });
-        console.log(`[sites-agent] Batch downloaded ${succeeded}/${results.length} images`);
+        log.info(`[sites-agent] Batch downloaded ${succeeded}/${results.length} images`);
         return { content: [{ type: "text", text: JSON.stringify({ results, succeeded, failed: results.length - succeeded }) }] };
     }, { annotations: { destructiveHint: false, openWorldHint: true } });
     // ── BROWSE GOOGLE DRIVE IMAGES ──
@@ -710,7 +718,7 @@ export function createSitesAgentMcpServer(options) {
                 contentBlocks.push({ type: "text", text: `↑ ${r.name} → ${r.localUrl}` });
             }
         }
-        console.log(`[sites-agent] Browsed GDrive: ${manifest.length}/${files.length} images downloaded`);
+        log.info(`[sites-agent] Browsed GDrive: ${manifest.length}/${files.length} images downloaded`);
         return {
             content: [
                 { type: "text", text: `Found ${manifest.length} images. Thumbnails below — use localUrl paths in block props.\n${JSON.stringify(manifest, null, 2)}` },
@@ -734,7 +742,7 @@ export function createSitesAgentMcpServer(options) {
             await patchGlobalsCssVars(join(monorepoRoot(), "apps", args.siteId, "app", "globals.css"), args.variables);
         }
         catch (err) {
-            console.warn(`[sites-agent] Failed to persist theme to globals.css:`, err);
+            log.warn({ err }, "[sites-agent] Failed to persist theme to globals.css");
         }
         return {
             content: [{
@@ -973,8 +981,8 @@ export function createSitesAgentMcpServer(options) {
                 const { execSync } = await import("node:child_process");
                 const pids = execSync(`lsof -ti:${port} 2>/dev/null`, { encoding: "utf-8" }).trim();
                 if (pids) {
-                    console.log(`[integrate_site] Port ${port} in use, finding free port...`);
-                    port = await findAvailablePort(root);
+                    log.info(`[integrate_site] Port ${port} in use, finding free port...`);
+                    port = await findAvailablePort(root, log);
                     const pkg = JSON.parse(await readFile(join(projectDir, "package.json"), "utf-8"));
                     if (pkg.scripts?.dev) {
                         pkg.scripts.dev = pkg.scripts.dev.replace(/-p\s*\d+/, `-p ${port}`);
@@ -992,6 +1000,7 @@ export function createSitesAgentMcpServer(options) {
             // Start dev server and wait for ready
             const previewUrl = `http://localhost:${port}`;
             const { serverReady } = await startAndWaitForDevServer({
+                logger: log,
                 siteId: args.siteId, port, cwd: projectDir,
             });
             // Register in editor dashboard (emits site_created SSE event)
@@ -1043,8 +1052,8 @@ export function createSitesAgentMcpServer(options) {
                 const { execSync } = await import("node:child_process");
                 const pids = execSync(`lsof -ti:${port} 2>/dev/null`, { encoding: "utf-8" }).trim();
                 if (pids) {
-                    console.log(`[sites-agent] Port ${port} in use, finding free port...`);
-                    port = await findAvailablePort(root);
+                    log.info(`[sites-agent] Port ${port} in use, finding free port...`);
+                    port = await findAvailablePort(root, log);
                     // Update dev script with new port
                     const pkg = JSON.parse(await readFile(join(projectDir, "package.json"), "utf-8"));
                     if (pkg.scripts?.dev) {
@@ -1063,6 +1072,7 @@ export function createSitesAgentMcpServer(options) {
             // Start dev server and wait for it to be ready
             const previewUrl = `http://localhost:${port}`;
             const { serverReady } = await startAndWaitForDevServer({
+                logger: log,
                 siteId: args.siteId, port, cwd: projectDir,
             });
             const siteName = args.name ?? args.siteId;
@@ -1130,6 +1140,7 @@ export function createSitesAgentMcpServer(options) {
             }
             // Start dev server and wait for readiness
             const { serverReady } = await startAndWaitForDevServer({
+                logger: log,
                 siteId: args.siteId, port, cwd: root, useFilter: true,
             });
             const siteConfig = {

package/dist/chat/anthropic-cache.js

@@ -1,7 +1,30 @@
-const ENABLED_RE = /^(1|true|yes|on)$/i;
+import { envFlag } from "../env-flags.js";
+/**
+ * Prompt caching is ON by default. Every Anthropic request from this package —
+ * planner, intent parser, agent loop, variation pipeline — ships the same large
+ * stable system prefix plus the `submit_edit_plan` tool schema, which is the
+ * shape caching exists for. Set `ANTHROPIC_PROMPT_CACHE=0` to opt out.
+ *
+ * It defaulted to `false` until 2026-09-17, and the default was the whole
+ * setting: only this repo's own `.env` ever named the variable, so CI eval and
+ * e2e runs, `pnpm eval` (`eval-cli.ts` never loads dotenv), every deployment,
+ * and every library-mode integrator billed full price on a prefix that was
+ * byte-identical across requests. A default is the value almost everyone runs.
+ */
 function promptCacheEnabled() {
-    return ENABLED_RE.test((process.env.ANTHROPIC_PROMPT_CACHE ?? "").trim());
+    return envFlag("ANTHROPIC_PROMPT_CACHE", true);
 }
+/**
+ * Unset means the 5-minute TTL, and on this traffic that is the cheaper one —
+ * do not "upgrade" it to `1h` globally. The 1h entry costs 2x to write against
+ * 1.25x for 5m, and it only repays that on requests whose start-to-start gap
+ * exceeds 5 minutes. Replaying 651 real planner calls from
+ * `.data/chat-telemetry.ndjson` (2026-06 onward): most sit under a minute
+ * apart, only 44 fell in the 5-60 minute window the longer TTL rescues, and
+ * paying 2x on every other write to buy those back came out 20-32% *more*
+ * expensive. Set `ANTHROPIC_PROMPT_CACHE_TTL=1h` per-deployment if a given
+ * install's traffic really is that bursty — measure it there first.
+ */
 function promptCacheTtl() {
     const raw = (process.env.ANTHROPIC_PROMPT_CACHE_TTL ?? "").trim();
     if (raw === "5m" || raw === "1h")

package/dist/chat/chat-pipeline.js

@@ -7,6 +7,7 @@ import { isLikelyClarificationFollowUp } from "../nlp/intent-helpers.js";
 import { versions, pendingClarificationBySession, chatHistoryBySession, continuationChainBySession, imageSourcePreferenceBySession, getSessionDraft, getPage, setPage, pushUndo, bumpVersion, pushRecentEdit, pushVersionEntry, pushChatHistory, schedulePersistState, removePage } from "../state/session-state.js";
 import { getSiteAssets } from "../state/site-assets.js";
 import { loadPendingPlan, savePendingPlan, clearPendingPlan } from "../durable/pending-plan-store.js";
+import { envFlag } from "../env-flags.js";
 import { toErrorDetail, isNoEffectiveChangeError, isAlreadyCurrentError, classifyGuardrailError, formatValidationError, isRepairEligibleCategory, buildDeterministicRepairFeedback, validateOperations, applyOpsAtomically, isStructuralOperation, pickFocusBlockId, pickUpdatedSlug } from "../ops/ops-engine.js";
 import { evaluateDestructiveActions } from "../ops/destructive-action-gate.js";
 import { clarificationSuggestions, postEditSuggestions, keepDemoExecutable, demoPlanFromMessage, withKeylessNotice, plannerContextPack, compileDeterministicPlan, inferDeterministicIntent, isHighConfidenceDeterministicCase, tryCompoundDeterministicPlan, resolveImageUrlForAltField } from "../nlp/deterministic-planner.js";
@@ -472,7 +473,7 @@ export async function runChatPipeline(ctx, body, options) {
     // downgrade below. Honors an explicit caller provider/modelKey and falls back
     // to the prior auto-routing when Anthropic is unavailable. Disable with
     // CHAT_PLANNER_FORCE_SONNET=0. See CLAUDE.md § Chat Pipeline Flags.
-    const forceSonnet = /^(1|true|yes|on)$/i.test((process.env.CHAT_PLANNER_FORCE_SONNET ?? "").trim()) &&
+    const forceSonnet = envFlag("CHAT_PLANNER_FORCE_SONNET", false) &&
         !body.provider &&
         !body.modelKey &&
         ctx.availableProviders.includes("anthropic");
@@ -697,12 +698,12 @@ export async function runChatPipeline(ctx, body, options) {
         imageResolutionDurationMs: imageResolutionDurationMs > 0 ? imageResolutionDurationMs : undefined,
         planningAttempts: planningAttempts > 0 ? planningAttempts : undefined
     });
-    const incrementalApplyEnabled = !/^(0|false|no|off)$/i.test((process.env.CHAT_INCREMENTAL_APPLY ?? "1").trim());
+    const incrementalApplyEnabled = envFlag("CHAT_INCREMENTAL_APPLY", true);
     const streamedApplyMinStepMsRaw = Number(process.env.CHAT_STREAM_APPLY_MIN_STEP_MS ?? 260);
     const streamedApplyMinStepMs = Number.isFinite(streamedApplyMinStepMsRaw) && streamedApplyMinStepMsRaw > 0
         ? Math.min(Math.max(Math.trunc(streamedApplyMinStepMsRaw), 1), 2000)
         : 0;
-    const incrementalPlanStreamEnabled = !/^(0|false|no|off)$/i.test((process.env.CHAT_INCREMENTAL_PLAN_STREAM ?? "1").trim());
+    const incrementalPlanStreamEnabled = envFlag("CHAT_INCREMENTAL_PLAN_STREAM", true);
     const withDebugPayload = (payload, extra) => ({
         ...payload,
         debug: {
@@ -1056,8 +1057,8 @@ export async function runChatPipeline(ctx, body, options) {
         includeFullProps: translationScope === "page" || contentQuery || requestsPlanFirst(plannerMessage),
         attachments: body.attachments
     });
-    const compactContextExperimentEnabled = /^(1|true|yes|on)$/i.test((process.env.CHAT_COMPACT_CONTEXT_EXPERIMENT ?? "").trim());
-    const minimalContextExperimentEnabled = /^(1|true|yes|on)$/i.test((process.env.CHAT_MINIMAL_CONTEXT_EXPERIMENT ?? "").trim());
+    const compactContextExperimentEnabled = envFlag("CHAT_COMPACT_CONTEXT_EXPERIMENT", false);
+    const minimalContextExperimentEnabled = envFlag("CHAT_MINIMAL_CONTEXT_EXPERIMENT", false);
     const intentComplexity = !contentQuery
         ? classifyMessageComplexity({
             message: plannerMessage,
@@ -1535,7 +1536,7 @@ export async function runChatPipeline(ctx, body, options) {
                 // Defer image resolution: apply text/structural ops immediately, then
                 // resolve images in the background and patch them in via follow-up events.
                 // This avoids blocking the user for 1-15s while images are fetched/generated.
-                const deferImageResolution = !/^(0|false|no|off)$/i.test((process.env.CHAT_DEFER_IMAGE_RESOLUTION ?? "1").trim());
+                const deferImageResolution = envFlag("CHAT_DEFER_IMAGE_RESOLUTION", true);
                 if (!usedNativeUnsplashTool && !usedNativeImageTool && deferImageResolution) {
                     // Tag the plan with deferred image metadata so the apply step can
                     // resolve images after text ops are visible.
@@ -3197,7 +3198,7 @@ export async function runChatPipeline(ctx, body, options) {
                 return compoundOutcome.response;
         }
     }
-    const llmIntentRouterEnabled = !/^(0|false|no|off)$/i.test((process.env.CHAT_LLM_INTENT_ROUTER ?? "1").trim());
+    const llmIntentRouterEnabled = envFlag("CHAT_LLM_INTENT_ROUTER", true);
     // Skip the intent router for batch-add requests — the router's deterministic
     // compile can't generate meaningful content for "add 3 blocks" without specific
     // block types, so go straight to the full planner which can handle it.
@@ -3228,7 +3229,7 @@ export async function runChatPipeline(ctx, body, options) {
     // full planner concurrently. The router gets a ~200ms head start. If it succeeds
     // and produces a valid plan, we abort the full planner and return immediately.
     // If it fails, the full planner is already running — no wasted time.
-    const parallelPlannerEnabled = !/^(0|false|no|off)$/i.test((process.env.CHAT_PARALLEL_PLANNER ?? "1").trim());
+    const parallelPlannerEnabled = envFlag("CHAT_PARALLEL_PLANNER", true);
     const routerHeadStartMs = Math.max(0, Math.min(Number(process.env.CHAT_ROUTER_HEAD_START_MS ?? 200), 1000));
     // Request-scoped registry. Closures over *Impl vars so test hooks
     // (setGeneratePlanWith*ForTests) still take effect.
@@ -3814,7 +3815,7 @@ export async function runChatPipeline(ctx, body, options) {
     // sees changes at ~800ms intervals instead of waiting for the full plan.
     const streamedPerOpApplyEnabled = incrementalApplyEnabled &&
         incrementalPlanStreamEnabled &&
-        !/^(0|false|no|off)$/i.test((process.env.CHAT_STREAMED_OP_APPLY ?? "1").trim()) &&
+        envFlag("CHAT_STREAMED_OP_APPLY", true) &&
         Boolean(options?.onOpApplied);
     // Raised when an attempt dies on `max_tokens`. Retrying a truncation with the
     // same budget reproduces it exactly — three identical failures cost ~250s and

package/dist/chat/model-defaults.d.ts

@@ -0,0 +1,17 @@
+import type { AIProvider, ModelKey } from "../state/session-state.ts";
+export type ModelLookup = Record<AIProvider, Record<ModelKey, string>>;
+/**
+ * Per-provider, per-tier model defaults, each overridable by its own env var.
+ *
+ * A function rather than a constant because the env is read at call time:
+ * `createOrchestrator()` may be constructed before a host has finished loading
+ * its `.env`, and tests set these variables per-case.
+ */
+export declare const defaultModelLookup: () => ModelLookup;
+/**
+ * The providers this process has credentials for, in preference order.
+ *
+ * Order is load-bearing: the chat pipeline falls back to `availableProviders[0]`
+ * when a request names no provider.
+ */
+export declare const defaultProviders: () => AIProvider[];

package/dist/chat/model-defaults.js

@@ -0,0 +1,58 @@
+// The default model per (provider, tier), and the providers a set of API keys
+// makes available.
+//
+// This lived twice: once in apps/orchestrator/src/index.ts (the Fastify host)
+// and once in handler/create-orchestrator.ts (library mode). Both read the same
+// `OPENAI_MODEL_*` / `ANTHROPIC_MODEL_*` / `GOOGLE_GENAI_MODEL_*` variables, so
+// a deployment that set them got identical behaviour either way and the split
+// was invisible. A deployment that set none — which is every `createOrchestrator()`
+// consumer following the README — got different models depending on which half
+// of the repo was serving it.
+//
+// They drifted the moment that mattered. #42 ("refresh OpenAI + Gemini defaults
+// to current GA models") edited the Fastify copy; the library copy was carved
+// out later in #58 and kept the pre-refresh values, so library mode was still
+// defaulting to `gpt-4o-mini`, `gpt-4o`, `o1`, `o3` and `gemini-2.5-flash` two
+// model generations after the standalone server had moved off them. Nothing
+// failed: the models still answered, just older, slower and worse at planning.
+//
+// One table, one place to edit on the next refresh.
+/**
+ * Per-provider, per-tier model defaults, each overridable by its own env var.
+ *
+ * A function rather than a constant because the env is read at call time:
+ * `createOrchestrator()` may be constructed before a host has finished loading
+ * its `.env`, and tests set these variables per-case.
+ */
+export const defaultModelLookup = () => ({
+    openai: {
+        fast: process.env.OPENAI_MODEL_FAST ?? "gpt-5.4-nano",
+        balanced: process.env.OPENAI_MODEL_BALANCED ?? "gpt-5.6-terra",
+        reasoning: process.env.OPENAI_MODEL_REASONING ?? "gpt-5.6-terra",
+        codex: process.env.OPENAI_MODEL_CODEX ?? "gpt-5.3-codex"
+    },
+    anthropic: {
+        fast: process.env.ANTHROPIC_MODEL_FAST ?? "claude-haiku-4-5-20251001",
+        balanced: process.env.ANTHROPIC_MODEL_BALANCED ?? "claude-sonnet-5",
+        reasoning: process.env.ANTHROPIC_MODEL_REASONING ?? "claude-sonnet-5",
+        codex: process.env.ANTHROPIC_MODEL_CODEX ?? "claude-opus-4-8"
+    },
+    gemini: {
+        fast: process.env.GOOGLE_GENAI_MODEL_FAST ?? "gemini-3.5-flash-lite",
+        balanced: process.env.GOOGLE_GENAI_MODEL_BALANCED ?? "gemini-3.6-flash",
+        // No GA Gemini 3 Pro yet (3.1 Pro is preview-only), so the Pro tiers stay on 2.5 Pro.
+        reasoning: process.env.GOOGLE_GENAI_MODEL_REASONING ?? "gemini-2.5-pro",
+        codex: process.env.GOOGLE_GENAI_MODEL_CODEX ?? "gemini-2.5-pro"
+    }
+});
+/**
+ * The providers this process has credentials for, in preference order.
+ *
+ * Order is load-bearing: the chat pipeline falls back to `availableProviders[0]`
+ * when a request names no provider.
+ */
+export const defaultProviders = () => [
+    ...(process.env.OPENAI_API_KEY ? ["openai"] : []),
+    ...(process.env.ANTHROPIC_API_KEY ? ["anthropic"] : []),
+    ...(process.env.GOOGLE_GENAI_API_KEY ? ["gemini"] : [])
+];

package/dist/chat/planner.js

@@ -23,6 +23,7 @@ import { extractJsonObject, inferBlockTypeFromText, normalizePlanCandidate, repa
 import { extractUsage, ZERO_USAGE } from "../telemetry/usage.js";
 import { intentJsonSchema } from "./plan-json-schema.js";
 import { PlannerError, isPlannerError } from "../errors.js";
+import { envFlag } from "../env-flags.js";
 // Re-export for backward compatibility
 export { PlannerError, isPlannerError };
 /** @deprecated Use `PlannerError` instead. */
@@ -73,7 +74,7 @@ function extractResponsesOutcome(response) {
     return { refusal: null, incomplete: false };
 }
 export function isChatStrictPrimaryOpMode() {
-    return /^(1|true|yes|on)$/i.test((process.env.CHAT_STRICT_PRIMARY_OP_MODE ?? "").trim());
+    return envFlag("CHAT_STRICT_PRIMARY_OP_MODE", false);
 }
 export function isPageWideTranslationRequest(message) {
     const lower = message.toLowerCase();
@@ -97,10 +98,10 @@ const EDIT_PLAN_SHAPE_HINT = {
     suggested_next_actions: ["string (optional, 2-4 items)"]
 };
 export function isStrictJsonResponseEnabled() {
-    return /^(1|true|yes|on)$/i.test((process.env.CHAT_STRICT_JSON_RESPONSE ?? "").trim());
+    return envFlag("CHAT_STRICT_JSON_RESPONSE", false);
 }
 export function isAdaptiveSchemaContextEnabled() {
-    return /^(1|true|yes|on)$/i.test((process.env.CHAT_ADAPTIVE_SCHEMA_CONTEXT ?? "").trim());
+    return envFlag("CHAT_ADAPTIVE_SCHEMA_CONTEXT", false);
 }
 function schemaBudgetBytes() {
     const parsed = Number(process.env.CHAT_SCHEMA_BUDGET_BYTES ?? "9000");

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

@@ -1,6 +1,26 @@
 import type { EditPlan, PageDoc } from "@avocadostudio-ai/shared";
 import type { plannerContextPack } from "../nlp/deterministic-planner.ts";
 import type { CommonGeneratePlanArgs, GeneratePlanResult } from "./planner-types.ts";
+/**
+ * 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.
+ */
 export declare function translationChunkingConfig(): {
     enabled: boolean;
     /**

package/dist/chat/translation-chunking.js

@@ -1,5 +1,6 @@
 import { buildFullPageTranslationChecklist } from "./chat-pipeline-translation.js";
 import { ZERO_USAGE } from "../telemetry/usage.js";
+import { envFlag, envInt } from "../env-flags.js";
 /**
  * Full-page translation, split into independent per-block-group requests.
  *
@@ -23,16 +24,9 @@ import { ZERO_USAGE } from "../telemetry/usage.js";
 // ---------------------------------------------------------------------------
 // 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),
+        enabled: envFlag("CHAT_TRANSLATION_CHUNKING", true),
         /**
          * Translatable bytes to aim for per chunk.
          *
@@ -43,12 +37,12 @@ export function translationChunkingConfig() {
          * 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),
+        targetBytes: envInt("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),
+        maxChunks: envInt("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)
+        minBlocks: envInt("CHAT_TRANSLATION_CHUNK_MIN_BLOCKS", 3),
+        minBytes: envInt("CHAT_TRANSLATION_CHUNK_MIN_BYTES", 1800)
     };
 }
 /**

package/dist/demo-mode.js

@@ -22,16 +22,10 @@
 //   and costs bounded.
 import { createHash } from "node:crypto";
 import { OperationError } from "./errors.js";
+import { envFlag } from "./env-flags.js";
 // ---------------------------------------------------------------------------
 // Config — read once at module load, memoized
 // ---------------------------------------------------------------------------
-const TRUE_VALUES = new Set(["1", "true", "yes", "on"]);
-function envFlag(name, fallback = false) {
-    const raw = process.env[name];
-    if (raw === undefined)
-        return fallback;
-    return TRUE_VALUES.has(raw.trim().toLowerCase());
-}
 function envList(name, fallback) {
     const raw = process.env[name];
     if (!raw)

package/dist/env-flags.d.ts

@@ -0,0 +1,21 @@
+/**
+ * `process.env` wrappers over the shared flag table.
+ *
+ * The table itself lives in `@avocadostudio-ai/shared` because the editor reads
+ * the same flags out of `import.meta.env` and `localStorage` — see that module's
+ * header for why there was more than one of it.
+ *
+ * All three read the environment at call time, never at module load. A flag
+ * captured at import is a flag a test cannot set and a library-mode host cannot
+ * configure after its own `.env` has loaded, and several of these already had to
+ * be functions for exactly that reason.
+ */
+/** `true`/`false` for a flag with a documented default. */
+export declare function envFlag(name: string, fallback: boolean): boolean;
+/**
+ * `undefined` when the operator said nothing, `false` when they said anything
+ * that is not a recognised "on". Fail-closed — see `parseFlagExplicit`.
+ */
+export declare function envFlagExplicit(name: string): boolean | undefined;
+/** A positive integer, or `fallback`. */
+export declare function envInt(name: string, fallback: number): number;

package/dist/env-flags.js

@@ -0,0 +1,28 @@
+/**
+ * `process.env` wrappers over the shared flag table.
+ *
+ * The table itself lives in `@avocadostudio-ai/shared` because the editor reads
+ * the same flags out of `import.meta.env` and `localStorage` — see that module's
+ * header for why there was more than one of it.
+ *
+ * All three read the environment at call time, never at module load. A flag
+ * captured at import is a flag a test cannot set and a library-mode host cannot
+ * configure after its own `.env` has loaded, and several of these already had to
+ * be functions for exactly that reason.
+ */
+import { parseFlag, parseFlagExplicit, parseIntFlag } from "@avocadostudio-ai/shared";
+/** `true`/`false` for a flag with a documented default. */
+export function envFlag(name, fallback) {
+    return parseFlag(process.env[name], fallback);
+}
+/**
+ * `undefined` when the operator said nothing, `false` when they said anything
+ * that is not a recognised "on". Fail-closed — see `parseFlagExplicit`.
+ */
+export function envFlagExplicit(name) {
+    return parseFlagExplicit(process.env[name]);
+}
+/** A positive integer, or `fallback`. */
+export function envInt(name, fallback) {
+    return parseIntFlag(process.env[name], fallback);
+}

package/dist/handler/create-orchestrator.d.ts

@@ -1,4 +1,5 @@
-import { type AIProvider, type ModelKey } from "../state/session-state.ts";
+import { type AIProvider } from "../state/session-state.ts";
+import { type ModelLookup } from "../chat/model-defaults.ts";
 import { type ScreenshotCapture } from "../http/screenshot-actions.ts";
 import { type Logger } from "../logger.ts";
 import type { CmsAdapter, CmsCapabilities } from "../cms/adapter.ts";
@@ -8,8 +9,16 @@ export interface CreateOrchestratorConfig {
     /**
      * Provider model overrides. Defaults to env vars (OPENAI_MODEL_*, ANTHROPIC_MODEL_*,
      * GOOGLE_GENAI_MODEL_*). Pass an explicit object to override per-tier model names.
+     *
+     * To change one tier and keep the rest current, spread the defaults rather
+     * than retyping the table — `defaultModelLookup` is exported for this:
+     *
+     * ```ts
+     * const base = defaultModelLookup()
+     * modelLookup: { ...base, openai: { ...base.openai, reasoning: "o5" } }
+     * ```
      */
-    modelLookup?: Record<AIProvider, Record<ModelKey, string>>;
+    modelLookup?: ModelLookup;
     /**
      * Override available providers. Defaults to whichever API keys are present in
      * process.env (OPENAI_API_KEY / ANTHROPIC_API_KEY / GOOGLE_GENAI_API_KEY).

package/dist/handler/create-orchestrator.js

@@ -30,7 +30,9 @@ import { ResumableStreamStore, runResumableChatStream, TooManyPendingStreamsErro
 import { runChatPipeline, collectMentionedSlugsFromOps } from "../chat/chat-pipeline.js";
 import { createChatTelemetryStore } from "../telemetry/chat-telemetry.js";
 import { createToolRuntime } from "../tools/runtime.js";
+import { envFlag } from "../env-flags.js";
 import { loadStateFromDisk, scopedSessionKey, getSessionPages, getPage, getSiteConfig, setSiteConfig, pushUndo, bumpVersion, pushRecentEdit, pushVersionEntry, schedulePersistState, normalizeSiteId, publishStatusBySession, pushPublishLogEntry, persistenceHealth, persistenceWarning } from "../state/session-state.js";
+import { defaultModelLookup, defaultProviders } from "../chat/model-defaults.js";
 import { historyStatus, historyLog, historyUndoAction, historyRedoAction, historyRestoreAction, historyDiscardAction } from "../http/history-actions.js";
 import { whoamiAction } from "../http/session-actions.js";
 import { blocksManifestAction } from "../http/blocks-actions.js";
@@ -55,31 +57,6 @@ import { isAccessGateEnabled, mintAccessToken, verifyAccessPassword } from "../h
 import { declareLibraryMount, observeLibraryMount } from "./library-mount.js";
 import { checkAuth, resolveAuth, CLOSED_HINT } from "./auth.js";
 import { setSiteAssetLister, invalidateSiteAssets } from "../state/site-assets.js";
-const defaultModelLookup = () => ({
-    openai: {
-        fast: process.env.OPENAI_MODEL_FAST ?? "gpt-4o-mini",
-        balanced: process.env.OPENAI_MODEL_BALANCED ?? "gpt-4o",
-        reasoning: process.env.OPENAI_MODEL_REASONING ?? "o1",
-        codex: process.env.OPENAI_MODEL_CODEX ?? "o3"
-    },
-    anthropic: {
-        fast: process.env.ANTHROPIC_MODEL_FAST ?? "claude-haiku-4-5-20251001",
-        balanced: process.env.ANTHROPIC_MODEL_BALANCED ?? "claude-sonnet-5",
-        reasoning: process.env.ANTHROPIC_MODEL_REASONING ?? "claude-sonnet-5",
-        codex: process.env.ANTHROPIC_MODEL_CODEX ?? "claude-opus-4-8"
-    },
-    gemini: {
-        fast: process.env.GOOGLE_GENAI_MODEL_FAST ?? "gemini-2.5-flash",
-        balanced: process.env.GOOGLE_GENAI_MODEL_BALANCED ?? "gemini-2.5-flash",
-        reasoning: process.env.GOOGLE_GENAI_MODEL_REASONING ?? "gemini-2.5-pro",
-        codex: process.env.GOOGLE_GENAI_MODEL_CODEX ?? "gemini-2.5-pro"
-    }
-});
-const defaultProviders = () => [
-    ...(process.env.OPENAI_API_KEY ? ["openai"] : []),
-    ...(process.env.ANTHROPIC_API_KEY ? ["anthropic"] : []),
-    ...(process.env.GOOGLE_GENAI_API_KEY ? ["gemini"] : [])
-];
 async function buildRuntime(config) {
     const log = config.logger ?? consoleLogger();
     // Register host-app block schemas BEFORE the planner ever validates ops.
@@ -97,7 +74,7 @@ async function buildRuntime(config) {
     const chatTelemetry = createChatTelemetryStore({
         filePath: process.env.CHAT_TELEMETRY_FILE ?? "./.data/chat-telemetry.ndjson",
         limit: Number(process.env.CHAT_TELEMETRY_LIMIT ?? 500),
-        persistEnabled: !/^(0|false|no|off)$/i.test((process.env.CHAT_TELEMETRY_PERSIST ?? "1").trim()),
+        persistEnabled: envFlag("CHAT_TELEMETRY_PERSIST", true),
         logger: log
     });
     const toolRuntime = await createToolRuntime({ logger: log });

package/dist/index.d.ts

@@ -1,5 +1,7 @@
 export { createOrchestrator, type CreateOrchestratorConfig, type OrchestratorHandler } from "./handler/create-orchestrator.ts";
 export type { OrchestratorAuth, AuthContext } from "./handler/auth.ts";
+export { envFlag, envFlagExplicit, envInt } from "./env-flags.ts";
+export { defaultModelLookup, defaultProviders, type ModelLookup } from "./chat/model-defaults.ts";
 export type { CmsAdapter, CmsCapabilities, CmsInlineAsset, CmsPublishContext, CmsPublishResult, CmsPerspective, CmsReadOptions, CmsMediaItem, CmsMediaPage, CmsMediaQuery, CmsMediaUpload, ResolvedCapabilities } from "./cms/adapter.ts";
 export { jsonFileAdapter, editorApiAdapter, resolveCapabilities, cmsMediaSource, cmsMediaUploader, cmsMediaLabel, type JsonFileAdapterOptions, type EditorApiAdapterOptions, type CmsMediaSource, type CmsMediaUploader, type CmsMediaSourceConfig } from "./cms/index.ts";
 export { registerPublishTarget, selectPublishTarget, getPublishTarget, listPublishTargets } from "./publish/publish-target-registry.ts";

package/dist/index.js

@@ -18,6 +18,15 @@
 //
 // The Fastify HTTP wrapper lives in apps/orchestrator and imports from here.
 export { createOrchestrator } from "./handler/create-orchestrator.js";
+// Flag parsing, so a library-mode host reads its own options the way the
+// orchestrator reads its own — one truth table for "1"/"true"/"yes"/"on".
+export { envFlag, envFlagExplicit, envInt } from "./env-flags.js";
+// The model defaults `createOrchestrator()` applies when `config.modelLookup`
+// is omitted. Public because the sensible way to override one tier is to spread
+// the defaults and replace that entry — which a consumer cannot do if the table
+// they are overriding is unreachable, leaving them to retype all twelve models
+// and inherit none of the next refresh.
+export { defaultModelLookup, defaultProviders } from "./chat/model-defaults.js";
 export { jsonFileAdapter, editorApiAdapter, resolveCapabilities, cmsMediaSource, cmsMediaUploader, cmsMediaLabel } from "./cms/index.js";
 // The publish-target plugin point. `docs-site/integration/publishing.mdx` has
 // documented this as the way to publish somewhere we do not ship a target for

package/dist/nlp/deterministic-planner-suggestions.js

@@ -174,50 +174,37 @@ export function postEditSuggestions(args) {
             return;
         suggestions.push(value);
     };
-    // Detect if this was primarily an image update
-    const isImageUpdate = plan.change_log.some((entry) => /\b(image|images|unsplash|photo)\b/i.test(entry));
+    /*
+     * No bare "Edit <thing>" chips.
+     *
+     * This branch used to emit "Edit heading", "Edit CTA", "Edit Banner",
+     * "Edit cards" after every edit. Clicking one sends that literal string to
+     * the planner, which knows the field and not the value — so the only possible
+     * answer is "edit it to what?". Three clean-room runs measured the same
+     * outcome: **zero operations**, and on a keyed plan about $0.012 and five
+     * seconds to be asked a question the chip existed to avoid.
+     *
+     * There is no repair for the shape. A suggestion is a sentence the product is
+     * offering to run, and "change this field to something" is not a sentence
+     * anybody can run — only the person typing knows the something. The chips
+     * that survive below are the ones that name a complete action: add a section,
+     * add another item, generate an image.
+     *
+     * The `isImageUpdate` special-casing went with them; it chose *which*
+     * underspecified chip to show, which was never the problem.
+     */
     for (const op of plan.ops) {
-        if (op.op === "update_props") {
-            const block = current.blocks.find((b) => b.id === op.blockId);
-            if (block) {
-                if (isImageUpdate) {
-                    // After image updates, suggest content edits relevant to the block
-                    const blockType = block.type;
-                    if (blockType === "CardGrid" || blockType === "Card") {
-                        pushUniqueSuggestion("Edit cards");
-                        pushUniqueSuggestion("Update links");
-                    }
-                    else if (blockType === "FeatureGrid") {
-                        pushUniqueSuggestion("Edit features");
-                    }
-                    else if (blockType === "Hero") {
-                        pushUniqueSuggestion("Edit heading");
-                        pushUniqueSuggestion("Edit CTA");
-                    }
-                    else {
-                        pushUniqueSuggestion(`Edit ${blockType}`);
-                    }
-                }
-                else {
-                    const patchKeys = Object.keys(op.patch);
-                    const otherKeys = editablePropsFromBlock(block)
-                        .filter((k) => !patchKeys.includes(k) && !NON_CONTENT_PROP_KEYS.has(k));
-                    for (const key of otherKeys.slice(0, 2)) {
-                        pushUniqueSuggestion(promptFromPropKey(key, block.type));
-                    }
-                }
-            }
-        }
-        else if (op.op === "create_page") {
+        if (op.op === "create_page") {
             pushUniqueSuggestion("Generate image");
         }
         else if (op.op === "add_block") {
+            // Only the curated, complete follow-ups. A block with none falls through
+            // to the forward-looking section nudges below rather than to
+            // `Edit <Type>`, which is the same dead end as the branch above.
             const followups = ADD_BLOCK_FOLLOWUPS[op.block.type];
             if (followups)
                 for (const f of followups)
                     pushUniqueSuggestion(f);
-            else
-                pushUniqueSuggestion(`Edit ${op.block.type}`);
         }
         else if (op.op === "remove_block") {
             if (!hasType("CTA"))

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@avocadostudio-ai/orchestrator-core",
-  "version": "0.11.8",
+  "version": "0.12.0",
   "type": "module",
   "exports": {
     "./package.json": "./package.json",
@@ -22,8 +22,8 @@
     "openai": "^4.87.1",
     "sharp": "^0.35.4",
     "zod": "^4.3.6",
-    "@avocadostudio-ai/migration-sdk": "^0.11.8",
-    "@avocadostudio-ai/shared": "^0.11.8"
+    "@avocadostudio-ai/migration-sdk": "^0.12.0",
+    "@avocadostudio-ai/shared": "^0.12.0"
   },
   "devDependencies": {
     "@anthropic-ai/claude-agent-sdk": "^0.3.220",