@avocadostudio-ai/orchestrator-core 0.1.0 → 0.2.1

package/dist/http/draft-provenance.d.ts

@@ -0,0 +1,68 @@
+/**
+ * Where the pages in a draft came from.
+ *
+ * `GET /draft/slugs` answered 200 with a page list whatever happened, and the
+ * list alone cannot be read back to its origin. Three very different situations
+ * were indistinguishable:
+ *
+ * - the caller named a real site and got its content;
+ * - the caller omitted `siteId` entirely, so it normalised to the bundled demo
+ *   site and eight plausible pages came back that belong to no site anyone
+ *   asked about;
+ * - the caller named a site that does not exist, and got an empty list that
+ *   reads exactly like a real site with no pages yet.
+ *
+ * An agent is the likeliest victim: it mistypes a `siteId`, sees a plausible
+ * answer, and every call after that succeeds against fiction. A human in the
+ * editor has the URL bar and a site switcher to notice with; an agent has this
+ * response and nothing else.
+ *
+ * So the response says which one it is. This is deliberately *not* a refusal —
+ * a site that has genuinely just been created is empty too, and 404-ing it
+ * would break the flow that fills it. What was missing was never the error
+ * status; it was any statement at all.
+ */
+export type DraftSource = 
+/** The bundled demo pages. Nobody's real content. */
+"demo"
+/** Read through a CMS adapter — the site's own content. */
+ | "adapter"
+/** Fetched from the orchestrator's configured site origin, which serves one site. */
+ | "bootstrap"
+/** This session's draft: seeded from the site earlier, or edited into being. */
+ | "draft"
+/** Empty, and no site by this id has ever been seen in this process. */
+ | "unknown-site"
+/** Empty, but the site is known — it genuinely has no pages yet. */
+ | "empty";
+export type DraftProvenance = {
+    siteId: string;
+    source: DraftSource;
+    /** Plain-language statement of what the caller is looking at. */
+    note?: string;
+    /** Only on `unknown-site`: what it could have meant. */
+    knownSiteIds?: string[];
+};
+/**
+ * Every site id this process has real state for.
+ *
+ * "Has an entry in `draftPages`" is not the test, and using it made this
+ * function useless: `getSessionDraft` creates the map on read, so *asking*
+ * about a mistyped site made that site known and the next answer said it was
+ * fine. The signals below are all writes.
+ *
+ * `versions` is what keeps a site known after its last page is deleted — an
+ * emptied site is not a missing one, and telling a caller to check the spelling
+ * of a site it just emptied would be its own small lie.
+ */
+export declare function knownSiteIds(): string[];
+export declare function describeDraft(args: {
+    /** Exactly what the caller sent, before normalisation — `undefined` matters. */
+    requestedSiteId: unknown;
+    scopedSession: string;
+    pageCount: number;
+    /** True when a CMS adapter backs this runtime (library mode with an adapter). */
+    hasAdapter?: boolean;
+    /** Set when auto-bootstrap filled this draft, to the origin it fetched from. */
+    bootstrappedFrom?: string;
+}): DraftProvenance;

package/dist/http/draft-provenance.js

@@ -0,0 +1,101 @@
+/**
+ * Where the pages in a draft came from.
+ *
+ * `GET /draft/slugs` answered 200 with a page list whatever happened, and the
+ * list alone cannot be read back to its origin. Three very different situations
+ * were indistinguishable:
+ *
+ * - the caller named a real site and got its content;
+ * - the caller omitted `siteId` entirely, so it normalised to the bundled demo
+ *   site and eight plausible pages came back that belong to no site anyone
+ *   asked about;
+ * - the caller named a site that does not exist, and got an empty list that
+ *   reads exactly like a real site with no pages yet.
+ *
+ * An agent is the likeliest victim: it mistypes a `siteId`, sees a plausible
+ * answer, and every call after that succeeds against fiction. A human in the
+ * editor has the URL bar and a site switcher to notice with; an agent has this
+ * response and nothing else.
+ *
+ * So the response says which one it is. This is deliberately *not* a refusal —
+ * a site that has genuinely just been created is empty too, and 404-ing it
+ * would break the flow that fills it. What was missing was never the error
+ * status; it was any statement at all.
+ */
+import { draftPages, siteConfigs, versions, normalizeSiteId, isLegacySiteId } from "../state/session-state.js";
+/**
+ * Every site id this process has real state for.
+ *
+ * "Has an entry in `draftPages`" is not the test, and using it made this
+ * function useless: `getSessionDraft` creates the map on read, so *asking*
+ * about a mistyped site made that site known and the next answer said it was
+ * fine. The signals below are all writes.
+ *
+ * `versions` is what keeps a site known after its last page is deleted — an
+ * emptied site is not a missing one, and telling a caller to check the spelling
+ * of a site it just emptied would be its own small lie.
+ */
+export function knownSiteIds() {
+    const ids = new Set();
+    const add = (key) => {
+        const sep = key.indexOf("::");
+        if (sep > 0)
+            ids.add(key.slice(0, sep));
+    };
+    for (const key of siteConfigs.keys())
+        add(key);
+    for (const [key, pages] of draftPages)
+        if (pages.size > 0)
+            add(key);
+    for (const [key, version] of versions)
+        if (version > 0)
+            add(key);
+    return [...ids].sort();
+}
+export function describeDraft(args) {
+    const siteId = normalizeSiteId(args.requestedSiteId);
+    const namedASite = typeof args.requestedSiteId === "string" && args.requestedSiteId.trim().length > 0;
+    /*
+     * A key with no `::` is the legacy/demo route, and the only way to reach it
+     * is a legacy site id — which is also what an *absent* `siteId` normalises to.
+     * That collapse is the whole trap: forgetting the parameter looks identical to
+     * asking for the demo site on purpose.
+     */
+    if (!args.scopedSession.includes("::") && isLegacySiteId(siteId)) {
+        return {
+            siteId,
+            source: "demo",
+            note: namedASite
+                ? `These are Avocado's bundled demo pages, served for the demo site "${siteId}".`
+                : "No siteId was supplied, so this is Avocado's bundled demo content — not any real site's " +
+                    "pages. Pass siteId to reach the site you meant."
+        };
+    }
+    if (args.bootstrappedFrom) {
+        return {
+            siteId,
+            source: "bootstrap",
+            note: `These pages were fetched from ${args.bootstrappedFrom}, which serves one site and answers ` +
+                `with its own content whatever siteId is asked for. They are stored under "${siteId}", but ` +
+                "that does not make them that site's pages — confirm the siteId is the one you meant."
+        };
+    }
+    if (args.pageCount > 0) {
+        return {
+            siteId,
+            source: args.hasAdapter ? "adapter" : "draft"
+        };
+    }
+    const known = knownSiteIds();
+    if (!known.includes(siteId) && !args.hasAdapter) {
+        return {
+            siteId,
+            source: "unknown-site",
+            note: `No site "${siteId}" has been seen in this process, so this empty list is not a report ` +
+                "that the site has no pages — it is that nothing here knows the site. Check the siteId, " +
+                "or register it with POST /sites/register.",
+            knownSiteIds: known
+        };
+    }
+    return { siteId, source: "empty", note: `Site "${siteId}" is known and currently has no pages.` };
+}

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

@@ -0,0 +1,58 @@
+/**
+ * Undo, redo, restore and the history log, as transport-agnostic actions.
+ *
+ * These lived only in `apps/orchestrator/src/routes/history.ts`, wired
+ * directly into Fastify. Library mode — `createOrchestrator()` in the site SDK
+ * — serves the same editor from a plain `Request`/`Response` handler, and it
+ * reimplements by hand whichever routes somebody remembered to add. It never
+ * had these, so `POST /history/undo` answered "not handled by
+ * createOrchestrator()" in a UI that shows an Undo button unconditionally,
+ * while `/ops` had been faithfully calling `pushUndo` all along: the stack
+ * filled up and nothing could ever pop it.
+ *
+ * A second hand-kept copy would drift the same way the first one did, so the
+ * logic moves here and both transports call it. Each function returns the
+ * status code and body to send; neither Fastify nor `Response` appears in this
+ * file.
+ */
+import type { Logger } from "../logger.js";
+/** What a caller sends. `siteId` scopes the session; both transports pass it through. */
+export type HistoryScope = {
+    session?: string;
+    siteId?: string;
+    slug?: string;
+};
+export type ActionResult = {
+    code: number;
+    body: unknown;
+};
+/** Whether undo and redo have anything to offer for this slug. */
+export declare function historyStatus(query: HistoryScope): ActionResult;
+/** The version log, without the snapshots — those are large and the list view never reads them. */
+export declare function historyLog(query: HistoryScope & {
+    limit?: string | number;
+}): ActionResult;
+/**
+ * Step one entry back on a slug's undo stack.
+ *
+ * A `null` entry means "the page did not exist at this point", so undoing onto
+ * it removes the page rather than restoring one — which is how undoing a
+ * `create_page` works. The same `null` goes onto the redo stack when the page
+ * exists now and did not before.
+ */
+export declare function historyUndoAction(body: HistoryScope, log: Logger): ActionResult;
+/** The mirror of undo, popping the redo stack and pushing current onto undo. */
+export declare function historyRedoAction(body: HistoryScope, log: Logger): ActionResult;
+/**
+ * Jump to any entry in the version log by applying its stored snapshot.
+ *
+ * Independent of the undo/redo stacks, so every entry stays reachable even
+ * after jumping elsewhere. The restore is itself an edit: the current state
+ * goes onto the undo stack (so undo reverses the restore) and the log gains a
+ * `restore` entry with its own snapshot.
+ */
+export declare function historyRestoreAction(body: {
+    session?: string;
+    siteId?: string;
+    targetVersion?: number;
+}, log: Logger): ActionResult;

package/dist/http/history-actions.js

@@ -0,0 +1,169 @@
+/**
+ * Undo, redo, restore and the history log, as transport-agnostic actions.
+ *
+ * These lived only in `apps/orchestrator/src/routes/history.ts`, wired
+ * directly into Fastify. Library mode — `createOrchestrator()` in the site SDK
+ * — serves the same editor from a plain `Request`/`Response` handler, and it
+ * reimplements by hand whichever routes somebody remembered to add. It never
+ * had these, so `POST /history/undo` answered "not handled by
+ * createOrchestrator()" in a UI that shows an Undo button unconditionally,
+ * while `/ops` had been faithfully calling `pushUndo` all along: the stack
+ * filled up and nothing could ever pop it.
+ *
+ * A second hand-kept copy would drift the same way the first one did, so the
+ * logic moves here and both transports call it. Each function returns the
+ * status code and body to send; neither Fastify nor `Response` appears in this
+ * file.
+ */
+import { scopedSessionKey, historyUndo, historyRedo, getHistoryMap, getPage, setPage, removePage, pushUndo, pushCappedHistory, bumpVersion, pushVersionEntry, getVersionLog, versions, versionLog, schedulePersistState } from "../state/session-state.js";
+const badRequest = (error) => ({ code: 400, body: { error } });
+/** Whether undo and redo have anything to offer for this slug. */
+export function historyStatus(query) {
+    if (!query.session || !query.slug)
+        return badRequest("session and slug are required");
+    const session = scopedSessionKey(query.session, query.siteId);
+    const undoList = getHistoryMap(historyUndo, session).get(query.slug) ?? [];
+    const redoList = getHistoryMap(historyRedo, session).get(query.slug) ?? [];
+    return { code: 200, body: { canUndo: undoList.length > 0, canRedo: redoList.length > 0 } };
+}
+/** The version log, without the snapshots — those are large and the list view never reads them. */
+export function historyLog(query) {
+    if (!query.session)
+        return badRequest("session is required");
+    const session = scopedSessionKey(query.session, query.siteId);
+    const requested = typeof query.limit === "string" ? parseInt(query.limit, 10) : query.limit;
+    const limit = requested ? Math.min(requested || 50, 100) : 50;
+    const entries = getVersionLog(session, query.slug, limit).map(({ snapshot: _snapshot, ...rest }) => rest);
+    return { code: 200, body: { entries, currentVersion: versions.get(session) ?? 0 } };
+}
+/**
+ * Step one entry back on a slug's undo stack.
+ *
+ * A `null` entry means "the page did not exist at this point", so undoing onto
+ * it removes the page rather than restoring one — which is how undoing a
+ * `create_page` works. The same `null` goes onto the redo stack when the page
+ * exists now and did not before.
+ */
+export function historyUndoAction(body, log) {
+    if (!body.session || !body.slug)
+        return badRequest("session and slug are required");
+    const session = scopedSessionKey(body.session, body.siteId);
+    const slug = body.slug;
+    const undoMap = getHistoryMap(historyUndo, session);
+    const redoMap = getHistoryMap(historyRedo, session);
+    const list = undoMap.get(slug) ?? [];
+    if (list.length === 0)
+        return badRequest("nothing to undo");
+    // May be null if the page was deleted; the snapshot still restores it.
+    const current = getPage(session, slug);
+    const prev = list.pop();
+    undoMap.set(slug, list);
+    if (prev === undefined)
+        return badRequest("nothing to undo");
+    const redoList = redoMap.get(slug) ?? [];
+    pushCappedHistory(redoList, current);
+    redoMap.set(slug, redoList);
+    if (prev === null) {
+        removePage(session, slug);
+        const previewVersion = bumpVersion(session);
+        pushVersionEntry(session, { version: previewVersion, slug, summary: "Undo", opTypes: [], opCount: 0, source: "undo", snapshot: null });
+        schedulePersistState(log);
+        return { code: 200, body: { status: "applied", previewVersion, navigateToSlug: "/", canUndo: list.length > 0, canRedo: true } };
+    }
+    setPage(session, structuredClone(prev));
+    const previewVersion = bumpVersion(session);
+    pushVersionEntry(session, { version: previewVersion, slug, summary: "Undo", opTypes: [], opCount: 0, source: "undo", snapshot: structuredClone(prev) });
+    schedulePersistState(log);
+    // The page the editor is looking at is gone, so send it somewhere real.
+    const navigateToSlug = current === null ? prev.slug : undefined;
+    return {
+        code: 200,
+        body: { status: "applied", previewVersion, canUndo: list.length > 0, canRedo: true, ...(navigateToSlug ? { navigateToSlug } : {}) }
+    };
+}
+/** The mirror of undo, popping the redo stack and pushing current onto undo. */
+export function historyRedoAction(body, log) {
+    if (!body.session || !body.slug)
+        return badRequest("session and slug are required");
+    const session = scopedSessionKey(body.session, body.siteId);
+    const slug = body.slug;
+    const undoMap = getHistoryMap(historyUndo, session);
+    const redoMap = getHistoryMap(historyRedo, session);
+    const list = redoMap.get(slug) ?? [];
+    if (list.length === 0)
+        return badRequest("nothing to redo");
+    const current = getPage(session, slug);
+    const next = list.pop();
+    redoMap.set(slug, list);
+    if (next === undefined)
+        return badRequest("nothing to redo");
+    const undoList = undoMap.get(slug) ?? [];
+    pushCappedHistory(undoList, current);
+    undoMap.set(slug, undoList);
+    if (next === null) {
+        removePage(session, slug);
+        const previewVersion = bumpVersion(session);
+        pushVersionEntry(session, { version: previewVersion, slug, summary: "Redo", opTypes: [], opCount: 0, source: "redo", snapshot: null });
+        schedulePersistState(log);
+        return { code: 200, body: { status: "applied", previewVersion, navigateToSlug: "/", canUndo: true, canRedo: list.length > 0 } };
+    }
+    setPage(session, structuredClone(next));
+    const previewVersion = bumpVersion(session);
+    pushVersionEntry(session, { version: previewVersion, slug, summary: "Redo", opTypes: [], opCount: 0, source: "redo", snapshot: structuredClone(next) });
+    schedulePersistState(log);
+    const navigateToSlug = current === null ? next.slug : undefined;
+    return {
+        code: 200,
+        body: { status: "applied", previewVersion, canUndo: true, canRedo: list.length > 0, ...(navigateToSlug ? { navigateToSlug } : {}) }
+    };
+}
+/**
+ * Jump to any entry in the version log by applying its stored snapshot.
+ *
+ * Independent of the undo/redo stacks, so every entry stays reachable even
+ * after jumping elsewhere. The restore is itself an edit: the current state
+ * goes onto the undo stack (so undo reverses the restore) and the log gains a
+ * `restore` entry with its own snapshot.
+ */
+export function historyRestoreAction(body, log) {
+    if (!body.session || typeof body.targetVersion !== "number") {
+        return badRequest("session and targetVersion are required");
+    }
+    const session = scopedSessionKey(body.session, body.siteId);
+    const entries = versionLog.get(session) ?? [];
+    const target = entries.find((entry) => entry.version === body.targetVersion);
+    if (!target)
+        return { code: 404, body: { error: "target version not found" } };
+    if (target.snapshot === undefined) {
+        return badRequest("target version has no restorable snapshot (legacy entry)");
+    }
+    // pushUndo also clears redo, which is right: a restore starts a new branch.
+    pushUndo(session, target.slug, getPage(session, target.slug));
+    if (target.snapshot === null)
+        removePage(session, target.slug);
+    else
+        setPage(session, structuredClone(target.snapshot));
+    const previewVersion = bumpVersion(session);
+    pushVersionEntry(session, {
+        version: previewVersion,
+        slug: target.slug,
+        summary: `Restored to v${body.targetVersion}`,
+        opTypes: [],
+        opCount: 0,
+        source: "restore",
+        snapshot: target.snapshot === null ? null : structuredClone(target.snapshot)
+    });
+    schedulePersistState(log);
+    const undoList = getHistoryMap(historyUndo, session).get(target.slug) ?? [];
+    const redoList = getHistoryMap(historyRedo, session).get(target.slug) ?? [];
+    return {
+        code: 200,
+        body: {
+            status: "applied",
+            previewVersion,
+            navigateToSlug: target.slug,
+            canUndo: undoList.length > 0,
+            canRedo: redoList.length > 0
+        }
+    };
+}

package/dist/http/image-generate-actions.d.ts

@@ -0,0 +1,268 @@
+/**
+ * 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 type { Logger } from "../logger.js";
+import type { ActionResult } from "./history-actions.js";
+export type { ActionResult };
+/**
+ * The one seam that decides where a generated image is written and what URL
+ * points back at it.
+ *
+ * The Fastify route wrote straight to `ctx.generatedImageDir` and built URLs
+ * from `ctx.orchestratorPublicOrigin`; the core helpers read the equivalent
+ * environment variables. Neither is right for a library-mode consumer, which
+ * has its own `imageDir` and serves `/generated-images/…` under the base path
+ * its route is mounted at. Without an injected store the extraction would
+ * "work" everywhere and return URLs that 404 in exactly one of the two
+ * transports, which is the failure that is hardest to notice from a test.
+ */
+export type ImageStore = {
+    save(bytes: Buffer, prefix: string, ext: string): Promise<{
+        url: string;
+    }>;
+};
+/**
+ * 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 declare function envImageStore(): ImageStore;
+/** A store for a transport that already knows its own directory and public base. */
+export declare function fileImageStore(options: {
+    dir: string;
+    publicBaseUrl: string;
+}): ImageStore;
+/** Only the two calls these actions make, so a test can supply a plain object. */
+export type OpenAIImagesClient = {
+    images: {
+        generate(args: {
+            model: string;
+            prompt: string;
+            size: string;
+        }): Promise<{
+            data?: Array<{
+                b64_json?: string | null;
+                url?: string | null;
+            }> | null;
+        }>;
+    };
+};
+export type OpenAIVisionClient = {
+    chat: {
+        completions: {
+            create(args: unknown): Promise<{
+                choices?: Array<{
+                    message?: {
+                        content?: string | null;
+                    };
+                }>;
+            }>;
+        };
+    };
+};
+export type GeminiPart = {
+    text?: string;
+    inlineData?: {
+        data?: string;
+        mimeType?: string;
+    };
+};
+export type GeminiContentResponse = {
+    candidates?: Array<{
+        content?: {
+            parts?: GeminiPart[];
+        };
+    }>;
+};
+export type GeminiImageChat = {
+    sendMessage(args: {
+        message: unknown;
+    }): Promise<GeminiContentResponse>;
+    sendMessageStream(args: {
+        message: unknown;
+    }): Promise<AsyncIterable<GeminiContentResponse>>;
+};
+export type GeminiImageClient = {
+    models: {
+        generateContent(args: unknown): Promise<GeminiContentResponse>;
+    };
+    chats: {
+        create(args: unknown): GeminiImageChat;
+    };
+};
+export type ImageActionDeps = {
+    log: Logger;
+    /** Defaults to `envImageStore()`. */
+    store?: ImageStore;
+    /** Test seams; the real clients are built from the environment when absent. */
+    openaiImages?: OpenAIImagesClient;
+    openaiVision?: OpenAIVisionClient;
+    gemini?: GeminiImageClient;
+    fetchFn?: typeof fetch;
+};
+export type GenerateImageBody = {
+    prompt?: string;
+    aspectRatio?: string;
+    provider?: string;
+    model?: string;
+};
+/**
+ * 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 declare function generateImageAction(body: GenerateImageBody, deps: ImageActionDeps): Promise<ActionResult>;
+/** Drop every live session and stop the sweeper. Tests only. */
+export declare function resetImageChatSessionsForTests(): void;
+/**
+ * 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 declare function detectAspectRatioFromPrompt(text: string): string | null;
+export type ImageChatBody = {
+    prompt?: string;
+    chatId?: string;
+    aspectRatio?: string;
+    stream?: boolean;
+    referenceImageUrl?: string;
+    referenceImageUrls?: string[];
+};
+/**
+ * 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 declare function validateImageChatRequest(body: ImageChatBody): ActionResult | 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 declare function resolveImageChatSession(body: ImageChatBody, ai: GeminiImageClient, log: Logger): {
+    chatId: string;
+    chat: GeminiImageChat;
+    aspectRatio: string;
+};
+/**
+ * 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 declare function buildImageChatMessage(body: ImageChatBody, deps: ImageActionDeps): Promise<unknown>;
+/**
+ * The SSE frames the streaming variant emits, in the order they can occur: one
+ * `chatId`, one `status`, then any number of `text` and `image` frames, and
+ * exactly one `done` — with an `error` before it if the generation broke.
+ *
+ * Unlike the variations stream, the event name goes on an SSE `event:` line
+ * rather than inside the payload, because the editor reads this one with
+ * `EventSource`-style named listeners.
+ */
+export type ImageChatFrame = {
+    event: "chatId";
+    chatId: string;
+    aspectRatio: string;
+} | {
+    event: "status";
+    stage: string;
+} | {
+    event: "text";
+    text: string;
+} | {
+    event: "image";
+    url: string;
+    alt: string;
+} | {
+    event: "error";
+    error: string;
+} | {
+    event: "done";
+};
+/** The wire encoding of one frame. */
+export declare function formatImageChatFrame(frame: ImageChatFrame): string;
+/**
+ * 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 declare function imageChatAction(body: ImageChatBody, deps: ImageActionDeps): Promise<ActionResult>;
+/**
+ * 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 declare function imageChatStreamAction(body: ImageChatBody, deps: ImageActionDeps, emit: (frame: ImageChatFrame) => void): Promise<void>;
+/**
+ * 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 declare function validateImageAnalysisInput(input: {
+    mimeType: string;
+    byteLength: number;
+}): ActionResult | 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 declare function interpretImageAction(input: {
+    bytes: Buffer;
+    byteLength: number;
+    mimeType: string;
+}, deps: ImageActionDeps): Promise<ActionResult>;