@avocadostudio-ai/orchestrator-core 0.1.0 → 0.2.1

package/dist/http/image-generate-actions.js

@@ -0,0 +1,546 @@
+/**
+ * Image generation — one-shot, multi-turn Gemini chat, and screenshot
+ * interpretation — as transport-agnostic actions.
+ *
+ * These three handlers lived only in `apps/orchestrator/src/routes/media.ts`,
+ * wired directly into Fastify, even though almost everything they call has been
+ * in orchestrator-core all along. Library mode — `createOrchestrator()` in the
+ * site SDK — serves the same editor from a plain `Request`/`Response` handler
+ * and reimplements by hand whichever routes somebody remembered to add. It
+ * never had these, so the editor's image picker answered "not handled by
+ * createOrchestrator()" for a Generate tab it shows unconditionally.
+ *
+ * Two things made a second hand-kept copy worse than usual here. The multi-turn
+ * chat keeps *live* Gemini sessions in a closure-scoped Map, so a duplicate
+ * implementation would also duplicate the session store and hand the same
+ * `chatId` two different conversations. And the streaming variant has an SSE
+ * frame vocabulary — `chatId`/`status`/`text`/`image`/`error`/`done` — that
+ * existed only inside the Fastify handler, while the editor parses those names
+ * by hand: nothing type-checks a string written on one side of a socket against
+ * the string read on the other. So the frames are built here, once, and
+ * `formatImageChatFrame` writes the wire bytes.
+ *
+ * Each function returns the status code and body to send, or emits frames;
+ * neither Fastify nor `Response` appears in this file.
+ */
+import { randomUUID } from "node:crypto";
+import { mkdir, writeFile } from "node:fs/promises";
+import { resolve } from "node:path";
+import OpenAI from "openai";
+import { getGeminiClient, getGeminiImageModel, saveGeneratedImage, GEMINI_ASPECT_RATIOS } from "../image/image-helpers.js";
+import { openAIChatOptionsForModel } from "../chat/planner.js";
+import { toErrorDetail } from "../errors.js";
+/**
+ * The historical behaviour: `ORCHESTRATOR_GENERATED_IMAGE_DIR` +
+ * `ORCHESTRATOR_PUBLIC_ORIGIN`, via the same helper the rest of core uses. This
+ * is the default so a caller that passes no store is byte-for-byte unchanged.
+ */
+export function envImageStore() {
+    return { save: async (bytes, prefix, ext) => saveGeneratedImage(bytes, prefix, ext) };
+}
+/** A store for a transport that already knows its own directory and public base. */
+export function fileImageStore(options) {
+    const base = options.publicBaseUrl.replace(/\/+$/, "");
+    return {
+        async save(bytes, prefix, ext) {
+            const fileName = `${prefix}_${Date.now()}_${randomUUID().slice(0, 8)}.${ext}`;
+            await mkdir(options.dir, { recursive: true });
+            await writeFile(resolve(options.dir, fileName), bytes);
+            return { url: `${base}/${fileName}` };
+        }
+    };
+}
+/**
+ * `@google/genai` is an *optional* peer dependency, loaded lazily by
+ * `getGeminiClient()`. A library-mode consumer who never asked for Gemini has
+ * not installed it, and an unhandled module-resolution throw would surface as a
+ * 500 with a stack trace about a missing package. It is a configuration
+ * problem, so it gets its own type and comes back as a 503.
+ */
+class GeminiUnavailableError extends Error {
+}
+async function loadGeminiClient(deps) {
+    if (deps.gemini)
+        return deps.gemini;
+    try {
+        return (await getGeminiClient());
+    }
+    catch (error) {
+        deps.log.warn({ event: "gemini_sdk_unavailable", error: toErrorDetail(error) }, "@google/genai could not be loaded");
+        throw new GeminiUnavailableError("@google/genai is not installed; install it to use Gemini image generation");
+    }
+}
+const storeOf = (deps) => deps.store ?? envImageStore();
+const fetchOf = (deps) => deps.fetchFn ?? fetch;
+/**
+ * Save the first inline image in a Gemini part list through the injected store.
+ *
+ * `saveGeminiInlineImage` in core does the same decode but always writes to the
+ * environment-configured directory, which is the one thing that has to be
+ * per-transport here.
+ */
+async function saveInlineImage(parts, store, prefix = "gen") {
+    for (const part of parts) {
+        const data = part.inlineData?.data;
+        if (!data)
+            continue;
+        const bytes = Buffer.from(data, "base64");
+        if (bytes.byteLength === 0)
+            continue;
+        const mimeType = part.inlineData?.mimeType ?? "image/png";
+        const ext = mimeType.includes("jpeg") || mimeType.includes("jpg") ? "jpg" : "png";
+        const { url } = await store.save(bytes, prefix, ext);
+        return { url, mimeType };
+    }
+    return null;
+}
+/** OpenAI has no aspect-ratio parameter, only sizes; these are the three the picker offers. */
+const OPENAI_ASPECT_SIZES = {
+    landscape: "1536x1024",
+    square: "1024x1024",
+    portrait: "1024x1536"
+};
+/**
+ * One image from one prompt, from whichever provider is configured.
+ *
+ * The provider is chosen per request (`body.provider`) and falls back to
+ * `IMAGE_GEN_PROVIDER`, then to OpenAI. Asking for Gemini without a Google key
+ * silently falls through to OpenAI rather than failing, because the editor
+ * sends a provider hint it inferred from the user's wording and a deployment
+ * that funds only one key should still generate images.
+ */
+export async function generateImageAction(body, deps) {
+    const hasOpenAI = !!process.env.OPENAI_API_KEY;
+    const hasGemini = !!process.env.GOOGLE_GENAI_API_KEY;
+    if (!hasOpenAI && !hasGemini) {
+        return { code: 503, body: { error: "No image generation API key configured (OPENAI_API_KEY or GOOGLE_GENAI_API_KEY)" } };
+    }
+    const prompt = typeof body.prompt === "string" ? body.prompt.trim() : "";
+    if (!prompt)
+        return { code: 400, body: { error: "prompt is required" } };
+    const requestedProvider = typeof body.provider === "string" ? body.provider.trim().toLowerCase() : "";
+    const requestedModel = typeof body.model === "string" ? body.model.trim() : "";
+    const envProvider = process.env.IMAGE_GEN_PROVIDER?.trim().toLowerCase() || "openai";
+    const provider = requestedProvider || envProvider;
+    const alt = prompt.slice(0, 200);
+    const store = storeOf(deps);
+    try {
+        if (provider === "gemini" && hasGemini) {
+            const url = await generateWithGemini({ prompt, aspectRatio: body.aspectRatio, model: requestedModel || undefined }, deps, store);
+            if (!url)
+                return { code: 502, body: { error: "Gemini image generation returned no data" } };
+            return { code: 200, body: { url, alt } };
+        }
+        if (!hasOpenAI)
+            return { code: 503, body: { error: "OPENAI_API_KEY not configured and provider is not gemini" } };
+        const size = OPENAI_ASPECT_SIZES[body.aspectRatio ?? "landscape"] ?? OPENAI_ASPECT_SIZES.landscape;
+        const model = requestedModel || process.env.OPENAI_IMAGE_MODEL_DRAFT?.trim() || "gpt-image-1-mini";
+        const client = deps.openaiImages ?? new OpenAI({ apiKey: process.env.OPENAI_API_KEY });
+        const result = await client.images.generate({ model, prompt, size });
+        const image = result.data?.[0];
+        // gpt-image-* answers with base64; the older URL-returning models need a
+        // second fetch, and that URL expires, so the bytes are copied locally
+        // either way rather than handed to the editor as a remote link.
+        let bytes = null;
+        if (typeof image?.b64_json === "string" && image.b64_json.length > 0) {
+            bytes = Buffer.from(image.b64_json, "base64");
+        }
+        else if (typeof image?.url === "string" && image.url.length > 0) {
+            const fetched = await fetchOf(deps)(image.url);
+            if (fetched.ok)
+                bytes = Buffer.from(await fetched.arrayBuffer());
+        }
+        if (!bytes || bytes.byteLength === 0)
+            return { code: 502, body: { error: "Image generation returned no data" } };
+        const saved = await store.save(bytes, "gen", "png");
+        return { code: 200, body: { url: saved.url, alt } };
+    }
+    catch (error) {
+        if (error instanceof GeminiUnavailableError)
+            return { code: 503, body: { error: error.message } };
+        return { code: 502, body: { error: "Image generation failed", detail: toErrorDetail(error) } };
+    }
+}
+/**
+ * The single-shot Gemini call, kept local because the generated bytes must go
+ * through the injected store — `generateVariationImageWithGemini` in core does
+ * the same request but always writes to the environment-configured directory.
+ *
+ * Failures come back as `null` with a warning rather than a throw, which is
+ * what that helper does too, so the caller's 502 body stays the one the editor
+ * already handles.
+ */
+async function generateWithGemini(args, deps, store) {
+    const ai = await loadGeminiClient(deps);
+    const model = args.model ?? getGeminiImageModel();
+    const geminiAspectRatio = GEMINI_ASPECT_RATIOS[args.aspectRatio ?? "landscape"] ?? "3:2";
+    try {
+        const response = await ai.models.generateContent({
+            model,
+            contents: args.prompt,
+            config: { responseModalities: ["TEXT", "IMAGE"], imageConfig: { aspectRatio: geminiAspectRatio, imageSize: "1K" } }
+        });
+        const parts = response.candidates?.[0]?.content?.parts;
+        if (!parts)
+            return null;
+        const saved = await saveInlineImage(parts, store, "gen");
+        return saved?.url ?? null;
+    }
+    catch (error) {
+        deps.log.warn({ event: "gemini_image_error", model, aspectRatio: geminiAspectRatio, error: toErrorDetail(error) }, "Gemini image generation failed");
+        return null;
+    }
+}
+/**
+ * Live Gemini chat objects, keyed by the `chatId` handed to the client.
+ *
+ * Module-scoped rather than per-transport on purpose: a `chatId` is meaningless
+ * to anyone but the process that created it, and two stores in one process
+ * would let the same id address two different conversations. Nothing here is
+ * persisted — a restart drops every session and the client starts a new one,
+ * which is why the id travels back on every frame.
+ */
+const imageChatSessions = new Map();
+const MAX_CHAT_SESSIONS = 200;
+const CHAT_SESSION_TTL_MS = 30 * 60 * 1000;
+const CHAT_SWEEP_INTERVAL_MS = 10 * 60 * 1000;
+let sweeper = null;
+/**
+ * Started on first use, not at import time: a process that never opens an image
+ * chat (every test in this repo, and every deployment without a Google key)
+ * should not carry a timer, and `unref` keeps the one we do start from holding
+ * the event loop open at shutdown.
+ */
+function ensureSessionSweeper() {
+    if (sweeper)
+        return;
+    sweeper = setInterval(() => {
+        const cutoff = Date.now() - CHAT_SESSION_TTL_MS;
+        for (const [id, session] of imageChatSessions) {
+            if (session.lastUsed < cutoff)
+                imageChatSessions.delete(id);
+        }
+    }, CHAT_SWEEP_INTERVAL_MS);
+    sweeper.unref();
+}
+/** Drop every live session and stop the sweeper. Tests only. */
+export function resetImageChatSessionsForTests() {
+    imageChatSessions.clear();
+    if (sweeper) {
+        clearInterval(sweeper);
+        sweeper = null;
+    }
+}
+/**
+ * Detect an aspect-ratio override in the prompt text.
+ *
+ * The picker has a ratio control, but people also just type "make it square",
+ * and a Gemini chat's `imageConfig` is fixed for the life of the session — so
+ * the wording has to be read here, before the session is created, or the
+ * request silently produces the previous shape.
+ */
+export function detectAspectRatioFromPrompt(text) {
+    const lower = text.toLowerCase();
+    const ratioMatch = lower.match(/\b(\d+)\s*:\s*(\d+)\b/);
+    if (ratioMatch) {
+        const w = Number(ratioMatch[1]);
+        const h = Number(ratioMatch[2]);
+        if (w > 0 && h > 0)
+            return `${w}:${h}`;
+    }
+    if (/\bsquare\b/.test(lower))
+        return "1:1";
+    // "portrait"/"landscape" are also ordinary subject words ("a landscape photo
+    // of a lake"), so they only count as a ratio next to a shape word.
+    if (/\bportrait\b/.test(lower) && /\b(ratio|aspect|orientation|format)\b/.test(lower))
+        return "2:3";
+    if (/\blandscape\b/.test(lower) && /\b(ratio|aspect|orientation|format)\b/.test(lower))
+        return "3:2";
+    if (/\bwidescreen\b|\bultra.?wide\b/.test(lower))
+        return "16:9";
+    return null;
+}
+/**
+ * The cheap guards, separate from the actions because the streaming transport
+ * has to answer them *before* it commits SSE headers — after that the status
+ * code is spent and the only way to say "no key" is a frame the client would
+ * have to special-case.
+ */
+export function validateImageChatRequest(body) {
+    if (!process.env.GOOGLE_GENAI_API_KEY) {
+        return { code: 503, body: { error: "GOOGLE_GENAI_API_KEY is not configured" } };
+    }
+    const prompt = typeof body.prompt === "string" ? body.prompt.trim() : "";
+    if (!prompt)
+        return { code: 400, body: { error: "prompt is required" } };
+    return null;
+}
+/**
+ * Find or create the Gemini chat this request belongs to.
+ *
+ * Ratio precedence is prompt > client hint > the session's current ratio > 3:2.
+ * A ratio change on an existing session cannot be applied in place — Gemini
+ * freezes `imageConfig` when the chat is created — so the session is replaced
+ * and the caller gets a new `chatId`. That loses the conversation, which is the
+ * honest trade: keeping the old chat would keep producing the old shape.
+ */
+export function resolveImageChatSession(body, ai, log) {
+    const model = getGeminiImageModel();
+    const prompt = typeof body.prompt === "string" ? body.prompt.trim() : "";
+    const promptRatio = detectAspectRatioFromPrompt(prompt);
+    const clientRatio = body.aspectRatio ? (GEMINI_ASPECT_RATIOS[body.aspectRatio] ?? body.aspectRatio) : null;
+    const create = (aspectRatio) => {
+        const chatId = randomUUID();
+        const chat = ai.chats.create({
+            model,
+            config: { responseModalities: ["TEXT", "IMAGE"], imageConfig: { aspectRatio } }
+        });
+        // Evicting the least recently used session bounds the memory a long-running
+        // orchestrator holds in live SDK objects; the sweeper alone would not, since
+        // a burst of 10k sessions all stay under the 30-minute TTL.
+        if (imageChatSessions.size >= MAX_CHAT_SESSIONS) {
+            let oldestId = "";
+            let oldestTime = Infinity;
+            for (const [id, session] of imageChatSessions) {
+                if (session.lastUsed < oldestTime) {
+                    oldestTime = session.lastUsed;
+                    oldestId = id;
+                }
+            }
+            if (oldestId)
+                imageChatSessions.delete(oldestId);
+        }
+        imageChatSessions.set(chatId, { chat, lastUsed: Date.now(), aspectRatio });
+        ensureSessionSweeper();
+        return { chatId, chat, aspectRatio };
+    };
+    const existingId = body.chatId ?? "";
+    const existing = existingId ? imageChatSessions.get(existingId) : undefined;
+    if (!existing)
+        return create(promptRatio ?? clientRatio ?? "3:2");
+    const desiredRatio = promptRatio ?? clientRatio ?? existing.aspectRatio;
+    if (desiredRatio !== existing.aspectRatio) {
+        log.info({ event: "image_chat_aspect_change", from: existing.aspectRatio, to: desiredRatio }, `[image/chat] Aspect ratio changed ${existing.aspectRatio} → ${desiredRatio}, creating new session`);
+        imageChatSessions.delete(existingId);
+        return create(desiredRatio);
+    }
+    existing.lastUsed = Date.now();
+    return { chatId: existingId, chat: existing.chat, aspectRatio: existing.aspectRatio };
+}
+/**
+ * The message to send: the prompt alone, or the prompt plus inlined reference
+ * images on the first turn (Gemini accepts up to 14).
+ *
+ * References are only inlined when the client sent no `chatId`, because after
+ * the first turn they are already in the conversation and re-sending them
+ * re-pays their tokens on every edit. A reference that will not load is warned
+ * about and skipped rather than failing the request: losing one of five moodboard
+ * images should not lose the generation.
+ */
+export async function buildImageChatMessage(body, deps) {
+    const prompt = typeof body.prompt === "string" ? body.prompt.trim() : "";
+    if (body.chatId)
+        return prompt;
+    const urls = [body.referenceImageUrl, ...(Array.isArray(body.referenceImageUrls) ? body.referenceImageUrls : [])]
+        .filter((url) => typeof url === "string" && url.trim().length > 0)
+        .slice(0, 14);
+    if (urls.length === 0)
+        return prompt;
+    const doFetch = fetchOf(deps);
+    const results = await Promise.allSettled(urls.map(async (url) => {
+        const res = await doFetch(url, { signal: AbortSignal.timeout(8000) });
+        if (!res.ok)
+            throw new Error(`HTTP ${res.status}`);
+        const buffer = Buffer.from(await res.arrayBuffer());
+        if (buffer.byteLength > 5 * 1024 * 1024)
+            throw new Error("Image too large (>5MB)");
+        const mimeType = res.headers.get("content-type") ?? "image/png";
+        return { inlineData: { mimeType, data: buffer.toString("base64") } };
+    }));
+    const inlineParts = [];
+    for (const result of results) {
+        if (result.status === "fulfilled")
+            inlineParts.push(result.value);
+        else {
+            deps.log.warn({ event: "gemini_ref_image_fetch_failed", error: result.reason instanceof Error ? result.reason.message : String(result.reason) }, "Failed to fetch reference image — skipping");
+        }
+    }
+    if (inlineParts.length === 0)
+        return prompt;
+    return [{ text: prompt }, ...inlineParts];
+}
+/** The wire encoding of one frame. */
+export function formatImageChatFrame(frame) {
+    const { event, ...payload } = frame;
+    return `event: ${event}\ndata: ${JSON.stringify(payload)}\n\n`;
+}
+/**
+ * One turn of the image chat, answered in a single JSON body.
+ *
+ * `url` is null when the model replied with text only — a refusal, or a
+ * question about the prompt — which is a normal turn, not an error.
+ */
+export async function imageChatAction(body, deps) {
+    const invalid = validateImageChatRequest(body);
+    if (invalid)
+        return invalid;
+    const prompt = (body.prompt ?? "").trim();
+    const store = storeOf(deps);
+    try {
+        const ai = await loadGeminiClient(deps);
+        const session = resolveImageChatSession(body, ai, deps.log);
+        const message = await buildImageChatMessage(body, deps);
+        const response = await session.chat.sendMessage({ message });
+        const parts = response.candidates?.[0]?.content?.parts;
+        if (!parts)
+            return { code: 502, body: { error: "Gemini returned no content" } };
+        let imageUrl = null;
+        let textResponse = "";
+        for (const part of parts) {
+            if (part.text)
+                textResponse += part.text;
+            else if (part.inlineData?.data) {
+                const saved = await saveInlineImage([part], store, "gen");
+                if (saved)
+                    imageUrl = saved.url;
+            }
+        }
+        return {
+            code: 200,
+            body: {
+                chatId: session.chatId,
+                url: imageUrl,
+                alt: prompt.slice(0, 200),
+                text: textResponse || undefined,
+                aspectRatio: session.aspectRatio
+            }
+        };
+    }
+    catch (error) {
+        if (error instanceof GeminiUnavailableError)
+            return { code: 503, body: { error: error.message } };
+        return { code: 502, body: { error: "Gemini image generation failed", detail: toErrorDetail(error) } };
+    }
+}
+/**
+ * The same turn, streamed.
+ *
+ * Resolves once the terminal `done` frame has been emitted; ending the stream
+ * stays with the transport, which owns the socket and has to close it on client
+ * disconnect too. Everything that goes wrong after the first frame — including
+ * a failure to reach Gemini at all — is reported as an `error` frame rather
+ * than thrown, because the status code is committed the moment the transport
+ * writes SSE headers and in-band is the only channel left. Callers should run
+ * `validateImageChatRequest` before those headers so a missing key is still a
+ * real 503.
+ */
+export async function imageChatStreamAction(body, deps, emit) {
+    const prompt = (body.prompt ?? "").trim();
+    const alt = prompt.slice(0, 200);
+    const store = storeOf(deps);
+    let session;
+    let message;
+    try {
+        const ai = await loadGeminiClient(deps);
+        session = resolveImageChatSession(body, ai, deps.log);
+        message = await buildImageChatMessage(body, deps);
+    }
+    catch (error) {
+        emit({ event: "error", error: toErrorDetail(error) });
+        emit({ event: "done" });
+        return;
+    }
+    emit({ event: "chatId", chatId: session.chatId, aspectRatio: session.aspectRatio });
+    emit({ event: "status", stage: "Generating image…" });
+    try {
+        const stream = await session.chat.sendMessageStream({ message });
+        for await (const chunk of stream) {
+            const parts = chunk.candidates?.[0]?.content?.parts;
+            if (!parts)
+                continue;
+            for (const part of parts) {
+                if (part.text)
+                    emit({ event: "text", text: part.text });
+                else if (part.inlineData?.data) {
+                    const saved = await saveInlineImage([part], store, "gen");
+                    if (saved)
+                        emit({ event: "image", url: saved.url, alt });
+                }
+            }
+        }
+    }
+    catch (error) {
+        emit({ event: "error", error: error instanceof Error ? error.message : String(error) });
+    }
+    emit({ event: "done" });
+}
+// ---------------------------------------------------------------------------
+// POST /image/interpret
+// ---------------------------------------------------------------------------
+/** What OpenAI vision reads as an `image_url` part. */
+const ALLOWED_IMAGE_ANALYSIS_MIME_TYPES = new Set(["image/png", "image/jpeg", "image/webp", "image/gif"]);
+const MAX_IMAGE_ANALYSIS_BYTES = 10 * 1024 * 1024;
+/**
+ * The checks on an uploaded image, shared so both transports answer alike.
+ *
+ * Each transport decodes multipart its own way — Fastify streams
+ * `request.file()`, library mode awaits `request.formData()` — and it was the
+ * *error bodies* around that decoding, not the decoding itself, that a second
+ * implementation would get subtly different. Returns null when the upload is
+ * acceptable.
+ */
+export function validateImageAnalysisInput(input) {
+    if (!ALLOWED_IMAGE_ANALYSIS_MIME_TYPES.has(input.mimeType)) {
+        return { code: 415, body: { error: `unsupported image type: ${input.mimeType}` } };
+    }
+    if (input.byteLength > MAX_IMAGE_ANALYSIS_BYTES) {
+        return { code: 413, body: { error: "image file is too large (max 10MB)" } };
+    }
+    if (input.byteLength === 0)
+        return { code: 400, body: { error: "image file is empty" } };
+    return null;
+}
+/**
+ * Describe a pasted screenshot in one sentence, for the chat composer to attach
+ * to the user's instruction.
+ *
+ * The image is inlined as a data URL rather than uploaded: the orchestrator has
+ * no public URL for a paste that never touched disk, and these are one-shot
+ * reads that nothing refers to again.
+ */
+export async function interpretImageAction(input, deps) {
+    if (!process.env.OPENAI_API_KEY)
+        return { code: 503, body: { error: "OPENAI_API_KEY is not configured" } };
+    const invalid = validateImageAnalysisInput({ mimeType: input.mimeType, byteLength: input.byteLength });
+    if (invalid)
+        return invalid;
+    const model = process.env.OPENAI_VISION_MODEL?.trim() || "gpt-4o";
+    const dataUrl = `data:${input.mimeType};base64,${input.bytes.toString("base64")}`;
+    const client = deps.openaiVision ?? new OpenAI({ apiKey: process.env.OPENAI_API_KEY });
+    try {
+        const completion = await client.chat.completions.create({
+            model,
+            ...openAIChatOptionsForModel(model),
+            messages: [
+                {
+                    role: "system",
+                    content: "You interpret pasted screenshots for a website editing assistant. Return one concise sentence describing the most actionable visual/context clue the editor should know. No markdown."
+                },
+                {
+                    role: "user",
+                    content: [
+                        { type: "text", text: "Analyze this screenshot and provide concise context for a website edit instruction." },
+                        { type: "image_url", image_url: { url: dataUrl } }
+                    ]
+                }
+            ]
+        });
+        const text = (completion.choices?.[0]?.message?.content ?? "").trim();
+        if (!text)
+            return { code: 502, body: { error: "image interpretation failed", detail: "No text returned." } };
+        return { code: 200, body: { text, model, bytes: input.byteLength, mimeType: input.mimeType } };
+    }
+    catch (error) {
+        return { code: 502, body: { error: "image interpretation failed", detail: toErrorDetail(error) } };
+    }
+}

package/dist/http/ops-actions.d.ts

@@ -0,0 +1,51 @@
+/**
+ * Validate-only op application, shared by both transports.
+ *
+ * `POST /ops` with `dryRun: true` is the one request in the API that promises
+ * *not* to change anything: it runs every operation against a clone, reports
+ * which would apply, skip or fail, and throws the result away. The MCP server's
+ * `avocado-dry-run-ops` tool exists to let an agent check a plan before
+ * committing to it.
+ *
+ * Library mode never read the flag. It parsed the body, ignored `dryRun`, and
+ * applied the operations for real — so the one call an agent makes precisely
+ * because it does not want to mutate the draft was the call that mutated it,
+ * and answered `status: "applied"` while doing so. Nothing about the reply
+ * suggested a dry run had been asked for.
+ *
+ * The branch lives here so neither transport can answer that question on its
+ * own again.
+ */
+import type { BlockManifest, Operation } from "@avocadostudio-ai/shared";
+import { type SkippedOperation } from "../ops/ops-engine.js";
+import type { ActionResult } from "./history-actions.js";
+export type { ActionResult };
+/**
+ * Never mutates state, so it skips undo snapshotting, the version bump and the
+ * 404-on-missing-page precheck — a missing page surfaces as a failed op in the
+ * results rather than as a status code, which is what a caller previewing a
+ * plan wants to see.
+ */
+export declare function opsDryRunAction(session: string, ops: Operation[], componentsManifest?: BlockManifest): Promise<ActionResult>;
+/**
+ * Human-readable change lines for a batch of operations that has just applied.
+ *
+ * Both transports answered every successful `POST /ops` with `changes: []`. It
+ * was a placeholder, not a claim — but `changes` is the field the editor renders
+ * as the bullet list under an assistant reply, and `/chat` fills it with real
+ * lines for exactly the same operations. An empty array on an applied write
+ * therefore reads as "this wrote nothing", and an external MCP session drew that
+ * inference in as many words.
+ *
+ * The lines come from the same builders `/chat` uses, so a `Hero` heading edit
+ * is described identically whether it arrived through the planner or through a
+ * hand-built ops array.
+ *
+ * `getBlockType` should resolve against the **pre-apply** draft where it can:
+ * `remove_block` and `remove_page` name a block that no longer exists by the
+ * time this runs, and looking it up afterwards yields "unknown block".
+ */
+export declare function describeAppliedOps(ops: Operation[], ctx: {
+    getBlockType: (slug: string, blockId: string) => string | undefined;
+    skippedOps?: SkippedOperation[];
+}): string[];

package/dist/http/ops-actions.js

@@ -0,0 +1,79 @@
+/**
+ * Validate-only op application, shared by both transports.
+ *
+ * `POST /ops` with `dryRun: true` is the one request in the API that promises
+ * *not* to change anything: it runs every operation against a clone, reports
+ * which would apply, skip or fail, and throws the result away. The MCP server's
+ * `avocado-dry-run-ops` tool exists to let an agent check a plan before
+ * committing to it.
+ *
+ * Library mode never read the flag. It parsed the body, ignored `dryRun`, and
+ * applied the operations for real — so the one call an agent makes precisely
+ * because it does not want to mutate the draft was the call that mutated it,
+ * and answered `status: "applied"` while doing so. Nothing about the reply
+ * suggested a dry run had been asked for.
+ *
+ * The branch lives here so neither transport can answer that question on its
+ * own again.
+ */
+import { applyOpsAtomically, classifyGuardrailError } from "../ops/ops-engine.js";
+import { buildOpChangeLogEntries, buildMetaChangeLogEntries } from "../chat/chat-pipeline-deterministic.js";
+import { toErrorDetail } from "../errors.js";
+/**
+ * Never mutates state, so it skips undo snapshotting, the version bump and the
+ * 404-on-missing-page precheck — a missing page surfaces as a failed op in the
+ * results rather than as a status code, which is what a caller previewing a
+ * plan wants to see.
+ */
+export async function opsDryRunAction(session, ops, componentsManifest) {
+    try {
+        const preview = await applyOpsAtomically(session, ops, { componentsManifest, dryRun: true });
+        const opResults = preview.opResults ?? [];
+        return {
+            code: 200,
+            body: {
+                status: "preview",
+                dryRun: true,
+                opResults,
+                appliedCount: opResults.filter((r) => r.status === "applied").length,
+                skippedCount: opResults.filter((r) => r.status === "skipped").length,
+                failedCount: opResults.filter((r) => r.status === "failed").length,
+                preview: preview.preview ?? null
+            }
+        };
+    }
+    catch (error) {
+        const reason = toErrorDetail(error);
+        return { code: 400, body: { error: reason, errorCode: classifyGuardrailError(reason) } };
+    }
+}
+/**
+ * Human-readable change lines for a batch of operations that has just applied.
+ *
+ * Both transports answered every successful `POST /ops` with `changes: []`. It
+ * was a placeholder, not a claim — but `changes` is the field the editor renders
+ * as the bullet list under an assistant reply, and `/chat` fills it with real
+ * lines for exactly the same operations. An empty array on an applied write
+ * therefore reads as "this wrote nothing", and an external MCP session drew that
+ * inference in as many words.
+ *
+ * The lines come from the same builders `/chat` uses, so a `Hero` heading edit
+ * is described identically whether it arrived through the planner or through a
+ * hand-built ops array.
+ *
+ * `getBlockType` should resolve against the **pre-apply** draft where it can:
+ * `remove_block` and `remove_page` name a block that no longer exists by the
+ * time this runs, and looking it up afterwards yields "unknown block".
+ */
+export function describeAppliedOps(ops, ctx) {
+    const skipped = ctx.skippedOps ?? [];
+    return [
+        ...buildOpChangeLogEntries(ops, { getBlockType: ctx.getBlockType }),
+        ...buildMetaChangeLogEntries(ops),
+        // A batch where every patch matched the value already stored is the case
+        // the empty array used to be mistaken for. Say it rather than imply it.
+        ...(skipped.length > 0
+            ? [`Skipped ${skipped.length} unchanged operation${skipped.length === 1 ? "" : "s"}.`]
+            : [])
+    ];
+}