@avocadostudio-ai/orchestrator-core 0.1.0

package/dist/image/image-helpers.js

@@ -0,0 +1,488 @@
+import { mkdir, writeFile } from "node:fs/promises";
+import { resolve } from "node:path";
+import OpenAI from "openai";
+import { listImages, fileNameToAlt, resolveGdriveFolderId } from "./gdrive-client.js";
+// ---------------------------------------------------------------------------
+// Image generation timing — rolling average for progress estimation
+// ---------------------------------------------------------------------------
+const recentGenDurations = [];
+const MAX_DURATION_HISTORY = 10;
+const DEFAULT_ESTIMATED_MS = 35_000;
+export function recordImageGenDuration(ms) {
+    recentGenDurations.push(ms);
+    if (recentGenDurations.length > MAX_DURATION_HISTORY)
+        recentGenDurations.shift();
+}
+export function estimatedImageGenMs() {
+    if (recentGenDurations.length === 0)
+        return DEFAULT_ESTIMATED_MS;
+    return Math.round(recentGenDurations.reduce((a, b) => a + b, 0) / recentGenDurations.length);
+}
+// ---------------------------------------------------------------------------
+// Query normalisation & keyword extraction
+// ---------------------------------------------------------------------------
+export function normalizeUnsplashQuery(raw) {
+    return raw
+        .toLowerCase()
+        .replace(/[^\p{L}\p{N}\s-]/gu, " ")
+        .replace(/\s+/g, " ")
+        .trim()
+        .slice(0, 80);
+}
+export function extractUnsplashQuery(message) {
+    const cleanMessage = message.replace(/\n?\[site context\][\s\S]*?\[\/site context\]\s*$/i, "").trim();
+    const aboutBeforeFromUnsplash = cleanMessage.match(/\b(?:about|of|with|for)\s+([^,.!?;\n]+?)\s+(?:from|using|via)\s+unsplash\b/i);
+    const fromUnsplashMatch = cleanMessage.match(/\b(?:from|using|via)\s+unsplash\b[^.?!\n]*?(?:showing|of|with|for)?[^\S\n]*([^,.!?;\n]+)/i);
+    const unsplashMatch = cleanMessage.match(/\bunsplash\b[^.?!\n]*?(?:showing|of|with|for)\s+([^,.!?;\n]+)/i);
+    const replaceImageWith = cleanMessage.match(/\b(?:replace|swap|change|update|set)\s+(?:the\s+)?(?:hero\s+)?(?:image|photo|picture)\s+(?:to|with|by)\s+([^,.!?;\n]+)/i);
+    const replaceImageWithGerman = cleanMessage.match(/\b(?:ersetze|ersetzen|aendere|ändere|tausche|tauschen)\s+(?:das|die|den)?\s*(?:hero\s*)?(?:bild|foto|image)\s+(?:durch|mit|zu)\s+([^,.!?;\n]+)/i);
+    const quotedWithImageContext = cleanMessage.match(/\b(?:image|photo|picture|bild|foto)\b[^"\n]{0,60}"([^"]+)"/i)?.[1] ??
+        cleanMessage.match(/^"([^"]+)"$/)?.[1];
+    const candidate = aboutBeforeFromUnsplash?.[1] ??
+        fromUnsplashMatch?.[1] ??
+        unsplashMatch?.[1] ??
+        replaceImageWith?.[1] ??
+        replaceImageWithGerman?.[1] ??
+        quotedWithImageContext;
+    if (!candidate)
+        return undefined;
+    const cleaned = candidate
+        .replace(/\b(an?|the|ein(?:e|en|em|er|es)?|der|die|das|den|dem|des)\s+/gi, "")
+        .replace(/\b(image|photo|picture)\b/gi, "")
+        .replace(/\b(of|with|showing|for|mit|von|fuer|für)\b/gi, " ")
+        .replace(/\s+/g, " ")
+        .trim();
+    const normalized = normalizeUnsplashQuery(cleaned);
+    return normalized.length > 0 ? normalized : undefined;
+}
+/**
+ * Detect explicit image generation intent in a message (e.g. "generate a new image", "new photo").
+ * Returns true for phrases that clearly request creating/replacing an image, but NOT for
+ * property edits like "change the image alt text".
+ */
+export function isExplicitImageGenRequest(message) {
+    const lower = message.toLowerCase();
+    return (/\b(?:generate|create)\b[^.!?\n]*\b(?:image|photo|picture)\b/i.test(lower) ||
+        /\bnew\s+(?:hero\s+)?(?:image|photo|picture)\b/i.test(lower) ||
+        /\breplace\b[^.!?\n]*\b(?:image|photo|picture)\b/i.test(lower));
+}
+/**
+ * Extract a detailed image description/prompt from a user message.
+ * Matches patterns like "generate a new image: [full description]".
+ * Returns the description (typically a rich prompt for AI image generation) or undefined.
+ */
+export function extractImagePromptFromMessage(message) {
+    // "generate/create/make a new image: [detailed description]"
+    const colonMatch = message.match(/\b(?:generate|create|make|new)\b[^.!?\n]*?\b(?:image|photo|picture)\s*[:]\s*(.+)/is);
+    if (colonMatch?.[1]) {
+        const desc = colonMatch[1].trim();
+        if (desc.length > 20)
+            return desc;
+    }
+    return undefined;
+}
+const IMAGE_QUERY_STOPWORDS = new Set([
+    "a", "an", "and", "background", "backgrounds", "different", "for", "from",
+    "image", "images", "of", "on", "photo", "photos", "picture", "pictures",
+    "the", "types", "unsplash", "various", "varied", "with"
+]);
+export function imageKeywordsFromQuery(raw, max = 3) {
+    const tokens = normalizeUnsplashQuery(raw)
+        .split(" ")
+        .map((part) => part.trim())
+        .filter((part) => part.length >= 3 && !IMAGE_QUERY_STOPWORDS.has(part));
+    const unique = Array.from(new Set(tokens));
+    return unique.slice(0, max);
+}
+// ---------------------------------------------------------------------------
+// Hero image query builder
+// ---------------------------------------------------------------------------
+export function heroImageQueryFromContext(args) {
+    // Strip [site context]...[/site context] metadata to avoid extracting metadata as query
+    const cleanMessage = args.message.replace(/\n?\[site context\][\s\S]*?\[\/site context\]\s*$/i, "").trim();
+    const explicit = extractUnsplashQuery(cleanMessage);
+    if (explicit)
+        return explicit;
+    const patch = args.patchCandidate;
+    const patchHeading = typeof patch?.heading === "string" ? patch.heading : "";
+    const patchSubheading = typeof patch?.subheading === "string" ? patch.subheading : "";
+    const patchAlt = typeof patch?.imageAlt === "string" ? patch.imageAlt : "";
+    const targetProps = args.targetBlock.props;
+    const heading = typeof targetProps.heading === "string" ? targetProps.heading : "";
+    const subheading = typeof targetProps.subheading === "string" ? targetProps.subheading : "";
+    const alt = typeof targetProps.imageAlt === "string" ? targetProps.imageAlt : "";
+    const candidates = [patchAlt, patchHeading, patchSubheading, heading, subheading, alt, args.currentPage.title]
+        .map((entry) => normalizeUnsplashQuery(entry))
+        .filter(Boolean);
+    for (const candidate of candidates) {
+        const terms = imageKeywordsFromQuery(candidate, 4);
+        if (terms.length > 0)
+            return terms.join(" ");
+    }
+    const fallback = normalizeUnsplashQuery(args.currentPage.title || args.targetBlock.type || "hero image");
+    return fallback || "hero image";
+}
+export function deriveVariationImageIntent(args) {
+    const fromMessage = extractUnsplashQuery(args.message);
+    const props = args.block.props;
+    const headingLike = typeof props.heading === "string"
+        ? props.heading
+        : typeof props.title === "string"
+            ? props.title
+            : typeof props.subheading === "string"
+                ? props.subheading
+                : "";
+    const fallback = normalizeUnsplashQuery([headingLike, args.block.type].filter(Boolean).join(" "));
+    const baseQuery = fromMessage ?? (fallback.length > 0 ? fallback : "abstract hero background");
+    const lowerMessage = args.message.toLowerCase();
+    const varyBackgrounds = /\bdifferent\s+(?:types?\s+of\s+)?backgrounds?\b/.test(lowerMessage) ||
+        /\bunique\s+backgrounds?\b/.test(lowerMessage) ||
+        /\bvaried\s+backgrounds?\b/.test(lowerMessage) ||
+        /\bvarious\s+backgrounds?\b/.test(lowerMessage);
+    const styleTerms = [];
+    if (/\bclose[\s-]?up\b/.test(lowerMessage) || /\bmacro\b/.test(lowerMessage))
+        styleTerms.push("close up");
+    if (/\bstudio\b/.test(lowerMessage))
+        styleTerms.push("studio lighting");
+    if (/\bfood\b/.test(lowerMessage) || /\bproduct\b/.test(lowerMessage))
+        styleTerms.push("food photography");
+    if (/\bdark\b/.test(lowerMessage))
+        styleTerms.push("dark moody");
+    if (/\bminimal\b/.test(lowerMessage))
+        styleTerms.push("minimal");
+    if (/\boutdoor\b/.test(lowerMessage) || /\bnature\b/.test(lowerMessage))
+        styleTerms.push("natural light");
+    const backgroundTerms = Array.from(new Set(Array.from(lowerMessage.matchAll(/\b(?:background|backgrounds)\s+(?:like|such as|with|in)?\s*([a-z0-9\s-]{3,45})/gi))
+        .map((match) => normalizeUnsplashQuery(match[1] ?? ""))
+        .filter(Boolean))).slice(0, 5);
+    const envDefault = (process.env.VARIATION_DEFAULT_IMAGE_SOURCE?.trim().toLowerCase() ?? "unsplash");
+    const resolvedDefault = envDefault === "ai" || envDefault === "llm" || envDefault === "gemini" || envDefault === "openai"
+        ? "llm"
+        : "unsplash";
+    const provider = /\bunsplash\b/.test(lowerMessage)
+        ? "unsplash"
+        : /\b(llm|openai|gemini|nano[-\s]?banana|gpt[-\s]?image(?:[-\s]?\d)?|ai[-\s]?generated|generated backgrounds?|synthetic backgrounds?)\b/.test(lowerMessage)
+            ? "llm"
+            : resolvedDefault;
+    return {
+        baseQuery,
+        subjectKeywords: imageKeywordsFromQuery(baseQuery, 4),
+        varyBackgrounds,
+        styleTerms,
+        provider,
+        backgroundTerms
+    };
+}
+export function buildVariationImageQuery(intent, variationIndex) {
+    const base = [intent.baseQuery, ...intent.styleTerms].filter(Boolean).join(" ");
+    if (!intent.varyBackgrounds)
+        return normalizeUnsplashQuery(base);
+    const backgrounds = ["studio background", "wood table background", "kitchen background", "dark background", "outdoor background"];
+    const chosen = backgrounds[variationIndex % backgrounds.length];
+    return normalizeUnsplashQuery(`${base} ${chosen}`);
+}
+export function buildVariationImagePrompt(args) {
+    const fallbackBackgrounds = [
+        "clean neutral studio gradient",
+        "cozy wooden table scene",
+        "bright kitchen countertop",
+        "dark cinematic backdrop",
+        "outdoor natural light"
+    ];
+    const customBackgrounds = args.intent.backgroundTerms;
+    const backgrounds = customBackgrounds.length > 0 ? customBackgrounds : fallbackBackgrounds;
+    const chosenBackground = args.intent.varyBackgrounds ? backgrounds[args.variationIndex % backgrounds.length] : backgrounds[0];
+    const subject = args.intent.baseQuery || `${args.blockType} hero visual`;
+    const style = args.intent.styleTerms.length > 0 ? args.intent.styleTerms.join(", ") : "natural product photography";
+    const lines = [
+        "Use case: precise-object-edit",
+        `Asset type: website ${args.blockType} image`
+    ];
+    if (args.pageContext)
+        lines.push(`Page: ${args.pageContext}`);
+    if (args.sectionContext)
+        lines.push(`Section: ${args.sectionContext}`);
+    lines.push(`Primary request: create a high-quality hero image featuring ${subject}`, `Scene/background: ${chosenBackground}`, `Style/medium: ${style}`, "Composition/framing: landscape composition with clear focal subject and breathing room", "Lighting/mood: clean, editorial, realistic", "Constraints: no text, no logos, no watermark", "Avoid: clutter, over-saturation, distorted objects");
+    return lines.join("\n");
+}
+// ---------------------------------------------------------------------------
+// Image generation & resolution
+// ---------------------------------------------------------------------------
+export async function generateVariationImageWithOpenAI(args) {
+    if (!process.env.OPENAI_API_KEY) {
+        args.log?.warn({ event: "openai_image_skip", reason: "no_api_key" }, "Skipping OpenAI image generation: OPENAI_API_KEY not set");
+        return null;
+    }
+    const model = args.model ?? process.env.OPENAI_IMAGE_MODEL?.trim() ?? "gpt-image-1-mini";
+    const size = args.size ?? "1536x1024";
+    const background = args.background ?? "auto";
+    const outputFormat = args.outputFormat ?? "png";
+    const client = new OpenAI({ apiKey: process.env.OPENAI_API_KEY });
+    const generatedImageDir = process.env.ORCHESTRATOR_GENERATED_IMAGE_DIR ?? resolve(process.cwd(), "../../.data/generated-images");
+    const orchestratorPublicOrigin = (process.env.ORCHESTRATOR_PUBLIC_ORIGIN ?? "http://localhost:4200").replace(/\/+$/, "");
+    args.log?.info({ event: "openai_image_start", model, size, background, outputFormat, promptLength: args.prompt.length }, "Starting OpenAI image generation");
+    const genStartMs = Date.now();
+    try {
+        // Forward AbortSignal to the OpenAI SDK so the HTTP request is cancelled
+        // when the tool executor's timeout (or the upstream chat request) aborts.
+        // Without this, a hung OpenAI API call would wedge the deferred image
+        // resolution loop indefinitely and leave the preview on "Generating image…".
+        const result = await client.images.generate({
+            model,
+            prompt: args.prompt,
+            size: size,
+            background,
+            output_format: outputFormat,
+        }, args.signal ? { signal: args.signal } : undefined);
+        const durationMs = Date.now() - genStartMs;
+        const image = result.data?.[0];
+        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 fetch(image.url, args.signal ? { signal: args.signal } : undefined);
+            if (fetched.ok) {
+                const arrayBuffer = await fetched.arrayBuffer();
+                bytes = Buffer.from(arrayBuffer);
+            }
+        }
+        if (!bytes || bytes.byteLength === 0)
+            return null;
+        await mkdir(generatedImageDir, { recursive: true });
+        const ext = outputFormat === "jpeg" ? "jpg" : outputFormat;
+        const fileName = `var_${Date.now()}_${Math.random().toString(36).slice(2, 8)}.${ext}`;
+        await writeFile(resolve(generatedImageDir, fileName), bytes);
+        args.log?.info({ event: "openai_image_done", model, size, durationMs, fileSizeBytes: bytes.byteLength }, `OpenAI image generated in ${durationMs}ms (model=${model})`);
+        return {
+            url: `${orchestratorPublicOrigin}/generated-images/${fileName}`,
+            alt: args.altText,
+            query: args.prompt
+        };
+    }
+    catch (err) {
+        const failDurationMs = Date.now() - genStartMs;
+        args.log?.warn({ event: "openai_image_error", model, durationMs: failDurationMs, error: err instanceof Error ? err.message : String(err) }, "OpenAI image generation failed");
+        return null;
+    }
+}
+// ---------------------------------------------------------------------------
+// Shared image save utility
+// ---------------------------------------------------------------------------
+export async function saveGeneratedImage(bytes, prefix = "gen", ext = "png") {
+    const generatedImageDir = process.env.ORCHESTRATOR_GENERATED_IMAGE_DIR ?? resolve(process.cwd(), "../../.data/generated-images");
+    const orchestratorPublicOrigin = (process.env.ORCHESTRATOR_PUBLIC_ORIGIN ?? "http://localhost:4200").replace(/\/+$/, "");
+    const fileName = `${prefix}_${Date.now()}_${Math.random().toString(36).slice(2, 8)}.${ext}`;
+    await mkdir(generatedImageDir, { recursive: true });
+    await writeFile(resolve(generatedImageDir, fileName), bytes);
+    return { fileName, url: `${orchestratorPublicOrigin}/generated-images/${fileName}` };
+}
+/** Extract the first inline image from a Gemini response, save to disk, return URL. */
+export async function saveGeminiInlineImage(parts, prefix = "gen") {
+    for (const part of parts) {
+        if (part.inlineData?.data) {
+            const mimeType = part.inlineData.mimeType ?? "image/png";
+            const bytes = Buffer.from(part.inlineData.data, "base64");
+            if (bytes.byteLength === 0)
+                continue;
+            const ext = mimeType.includes("jpeg") || mimeType.includes("jpg") ? "jpg" : "png";
+            const { url } = await saveGeneratedImage(bytes, prefix, ext);
+            return { url, mimeType };
+        }
+    }
+    return null;
+}
+// ---------------------------------------------------------------------------
+// Gemini client singleton + aspect ratios
+// ---------------------------------------------------------------------------
+export const GEMINI_ASPECT_RATIOS = {
+    landscape: "3:2",
+    square: "1:1",
+    portrait: "2:3"
+};
+// eslint-disable-next-line @typescript-eslint/no-explicit-any
+let _geminiClient = null;
+export async function getGeminiClient() {
+    if (_geminiClient)
+        return _geminiClient;
+    const { GoogleGenAI } = await import("@google/genai");
+    _geminiClient = new GoogleGenAI({ apiKey: process.env.GOOGLE_GENAI_API_KEY });
+    return _geminiClient;
+}
+export function getGeminiImageModel() {
+    return process.env.GOOGLE_GENAI_IMAGE_MODEL?.trim() || "gemini-3.1-flash-lite-image";
+}
+// ---------------------------------------------------------------------------
+// Gemini native image generation
+// ---------------------------------------------------------------------------
+export async function generateVariationImageWithGemini(args) {
+    if (!process.env.GOOGLE_GENAI_API_KEY?.trim()) {
+        args.log?.warn({ event: "gemini_image_skip", reason: "no_api_key" }, "Skipping Gemini image generation: GOOGLE_GENAI_API_KEY not set");
+        return null;
+    }
+    const ai = await getGeminiClient();
+    const model = args.model ?? getGeminiImageModel();
+    const geminiAspectRatio = GEMINI_ASPECT_RATIOS[args.aspectRatio ?? "landscape"] ?? "3:2";
+    const imageSize = args.quality === "final" ? "2K" : "1K";
+    args.log?.info({ event: "gemini_image_start", model, aspectRatio: geminiAspectRatio, imageSize, promptLength: args.prompt.length }, "Starting Gemini image generation");
+    // Gemini has no native transparency param — use prompt hint
+    const effectivePrompt = args.background === "transparent"
+        ? `${args.prompt}\n\nIMPORTANT: Generate this image on a fully transparent background with no background elements.`
+        : args.prompt;
+    const genStartMs = Date.now();
+    try {
+        // The @google/genai SDK does not expose an AbortSignal option, so we
+        // race the request against the signal manually. The executor enforces
+        // a hard timeout on top of this as a last line of defense.
+        const requestPromise = ai.models.generateContent({
+            model,
+            contents: effectivePrompt,
+            config: {
+                responseModalities: ["TEXT", "IMAGE"],
+                imageConfig: { aspectRatio: geminiAspectRatio, imageSize }
+            }
+        });
+        const response = args.signal
+            ? await Promise.race([
+                requestPromise,
+                new Promise((_resolve, reject) => {
+                    if (args.signal.aborted) {
+                        reject(new Error("Gemini image request aborted"));
+                        return;
+                    }
+                    args.signal.addEventListener("abort", () => reject(new Error("Gemini image request aborted")), { once: true });
+                })
+            ])
+            : await requestPromise;
+        const durationMs = Date.now() - genStartMs;
+        const parts = response.candidates?.[0]?.content?.parts;
+        if (!parts)
+            return null;
+        const saved = await saveGeminiInlineImage(parts, "var");
+        if (!saved)
+            return null;
+        args.log?.info({ event: "gemini_image_done", model, aspectRatio: geminiAspectRatio, durationMs }, `Gemini image generated in ${durationMs}ms (model=${model})`);
+        return { url: saved.url, alt: args.altText, query: args.prompt };
+    }
+    catch (err) {
+        const failDurationMs = Date.now() - genStartMs;
+        args.log?.warn({ event: "gemini_image_error", model, durationMs: failDurationMs, error: err instanceof Error ? err.message : String(err) }, "Gemini image generation failed");
+        return null;
+    }
+}
+export async function resolveUnsplashImage(query, options, logContext) {
+    const safeQuery = normalizeUnsplashQuery(query);
+    if (!safeQuery)
+        return null;
+    const variationIndex = typeof options?.variationIndex === "number" && Number.isInteger(options.variationIndex) && options.variationIndex >= 0
+        ? options.variationIndex
+        : 0;
+    const page = variationIndex + 1;
+    const log = logContext?.logger;
+    const accessKey = process.env.UNSPLASH_ACCESS_KEY?.trim();
+    log?.info({
+        event: "hero_image_resolve_start",
+        chatRequestId: logContext?.chatRequestId,
+        query: safeQuery,
+        variationIndex,
+        hasUnsplashKey: Boolean(accessKey),
+        subjectKeywords: options?.subjectKeywords ?? []
+    }, "Resolving hero image candidate");
+    if (accessKey) {
+        try {
+            const endpoint = `https://api.unsplash.com/search/photos?query=${encodeURIComponent(safeQuery)}&orientation=landscape&per_page=8&page=${page}&content_filter=high`;
+            const res = await fetch(endpoint, {
+                headers: {
+                    Authorization: `Client-ID ${accessKey}`,
+                    "Accept-Version": "v1"
+                }
+            });
+            function toImage(result) {
+                const baseUrl = typeof result?.urls?.regular === "string"
+                    ? result.urls.regular
+                    : typeof result?.urls?.full === "string"
+                        ? result.urls.full
+                        : undefined;
+                if (!baseUrl)
+                    return null;
+                const joiner = baseUrl.includes("?") ? "&" : "?";
+                const url = `${baseUrl}${joiner}auto=format&fit=crop&w=1600&q=80`;
+                const altCandidate = typeof result?.alt_description === "string"
+                    ? result.alt_description
+                    : typeof result?.description === "string"
+                        ? result.description
+                        : "";
+                return {
+                    url,
+                    alt: altCandidate.trim() || `Unsplash photo of ${safeQuery}`,
+                    query: safeQuery
+                };
+            }
+            if (res.ok) {
+                const payload = (await res.json());
+                const list = Array.isArray(payload.results) ? payload.results : [];
+                const subjectKeywords = Array.isArray(options?.subjectKeywords) && options?.subjectKeywords.length > 0
+                    ? options.subjectKeywords.map((k) => k.toLowerCase())
+                    : imageKeywordsFromQuery(safeQuery, 2);
+                const usedImageUrls = options?.usedImageUrls;
+                const matched = subjectKeywords.length > 0
+                    ? list.filter((item) => {
+                        const haystack = `${typeof item.alt_description === "string" ? item.alt_description : ""} ${typeof item.description === "string" ? item.description : ""}`.toLowerCase();
+                        return subjectKeywords.some((keyword) => haystack.includes(keyword));
+                    })
+                    : [];
+                const ordered = matched.length > 0 ? [...matched, ...list.filter((item) => !matched.includes(item))] : list;
+                for (const item of ordered) {
+                    const next = toImage(item);
+                    if (!next)
+                        continue;
+                    if (usedImageUrls && usedImageUrls.has(next.url))
+                        continue;
+                    log?.info({
+                        event: "hero_image_resolve_success",
+                        chatRequestId: logContext?.chatRequestId,
+                        provider: "unsplash_api",
+                        query: safeQuery,
+                        url: next.url,
+                        alt: next.alt
+                    }, "Resolved hero image from Unsplash API");
+                    return next;
+                }
+            }
+        }
+        catch {
+            // Fall through to source URL fallback.
+            log?.warn({
+                event: "hero_image_resolve_unsplash_error",
+                chatRequestId: logContext?.chatRequestId,
+                query: safeQuery
+            }, "Unsplash API lookup failed; falling back to seeded source");
+        }
+    }
+    return null;
+}
+// ---------------------------------------------------------------------------
+// Google Drive image resolution (parallel to resolveUnsplashImage)
+// ---------------------------------------------------------------------------
+export async function resolveGdriveImage(query, options) {
+    const resolvedFolderId = resolveGdriveFolderId(options?.folderId);
+    if (!resolvedFolderId)
+        return null;
+    const orchestratorPublicOrigin = (process.env.ORCHESTRATOR_PUBLIC_ORIGIN ?? "http://localhost:4200").replace(/\/+$/, "");
+    const log = options?.logger;
+    const safeQuery = normalizeUnsplashQuery(query);
+    const files = await listImages(resolvedFolderId, safeQuery || undefined, log, 1);
+    if (files.length === 0)
+        return null;
+    const first = files[0];
+    const url = `${orchestratorPublicOrigin}/gdrive/images/${first.id}`;
+    const alt = fileNameToAlt(first.name);
+    log?.info({
+        event: "gdrive_image_resolved",
+        chatRequestId: options?.chatRequestId,
+        query: safeQuery,
+        fileId: first.id,
+        fileName: first.name
+    }, "Resolved image from Google Drive");
+    return { url, alt, query: safeQuery };
+}

package/dist/index.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/index.js

@@ -0,0 +1 @@
+export {};

package/dist/jira/jira-approval.d.ts

@@ -0,0 +1,22 @@
+/**
+ * Approval keyword matcher for Jira comments.
+ *
+ * Used by the webhook dispatcher and poller to decide whether a reporter's
+ * comment signals "go ahead" (in To Do → start editing, in In Review → publish).
+ *
+ * Kept deliberately small and keyword-based. LLM-based intent detection would
+ * be overkill here — the set of things a reporter types to mean "yes" is small
+ * and we want fast, deterministic routing.
+ */
+/**
+ * Lowercase approval phrases. Matched as whole tokens (word boundaries) so
+ * "confirmation" does not match "confirm" and "goodbye" does not match "go".
+ */
+export declare const APPROVAL_KEYWORDS: readonly string[];
+/**
+ * Return true when the comment text contains an approval keyword as a whole token.
+ *
+ * Only the first few hundred characters are scanned — reporters commonly lead
+ * with "ok, also one more thing...", so longer prose doesn't need to match.
+ */
+export declare function isApprovalComment(text: unknown): boolean;

package/dist/jira/jira-approval.js

@@ -0,0 +1,51 @@
+/**
+ * Approval keyword matcher for Jira comments.
+ *
+ * Used by the webhook dispatcher and poller to decide whether a reporter's
+ * comment signals "go ahead" (in To Do → start editing, in In Review → publish).
+ *
+ * Kept deliberately small and keyword-based. LLM-based intent detection would
+ * be overkill here — the set of things a reporter types to mean "yes" is small
+ * and we want fast, deterministic routing.
+ */
+/**
+ * Lowercase approval phrases. Matched as whole tokens (word boundaries) so
+ * "confirmation" does not match "confirm" and "goodbye" does not match "go".
+ */
+export const APPROVAL_KEYWORDS = [
+    "proceed",
+    "go",
+    "go ahead",
+    "yes",
+    "ok",
+    "okay",
+    "approved",
+    "approve",
+    "lgtm",
+    "ship it",
+    "looks good",
+    "confirm",
+    "confirmed",
+    "continue",
+    "publish",
+];
+function escapeRegex(value) {
+    return value.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+}
+// Build once — case-insensitive, word-boundary on both sides, handles multi-word
+// phrases by escaping the space too.
+const APPROVAL_REGEX = new RegExp(`(?:^|\\W)(${APPROVAL_KEYWORDS.map(escapeRegex).join("|")})(?:$|\\W)`, "i");
+/**
+ * Return true when the comment text contains an approval keyword as a whole token.
+ *
+ * Only the first few hundred characters are scanned — reporters commonly lead
+ * with "ok, also one more thing...", so longer prose doesn't need to match.
+ */
+export function isApprovalComment(text) {
+    if (typeof text !== "string")
+        return false;
+    const trimmed = text.trim();
+    if (!trimmed)
+        return false;
+    return APPROVAL_REGEX.test(trimmed.slice(0, 500));
+}

package/dist/jira/jira-client.d.ts

@@ -0,0 +1,44 @@
+/**
+ * JIRA REST API client.
+ *
+ * Supports both JIRA Cloud (Basic auth: email + API token) and
+ * JIRA Server/Data Center (Bearer token / PAT).
+ *
+ * Uses only native fetch — no external HTTP library needed.
+ */
+import type { JiraIssue, JiraAttachment, JiraConfig } from "./jira-types.ts";
+export declare class JiraClient {
+    private readonly baseUrl;
+    private readonly authHeader;
+    private readonly isCloud;
+    constructor(config: Pick<JiraConfig, "baseUrl" | "email" | "apiToken">);
+    private request;
+    getIssue(issueKey: string): Promise<JiraIssue>;
+    getIssueAttachments(issueKey: string): Promise<JiraAttachment[]>;
+    /**
+     * Download an attachment binary. The `content` URL from JIRA requires the
+     * same auth header, so we can't just fetch it unauthenticated.
+     */
+    downloadAttachment(contentUrl: string): Promise<Buffer>;
+    addComment(issueKey: string, markdown: string): Promise<void>;
+    /**
+     * Transition an issue to a target status by name.
+     * Looks up available transitions to find the matching one.
+     */
+    transitionIssue(issueKey: string, targetStatusName: string): Promise<boolean>;
+    /**
+     * Assign an issue to a user by account ID (Cloud) or username (Server).
+     */
+    assignIssue(issueKey: string, assignee: {
+        accountId?: string;
+        name?: string;
+    }): Promise<void>;
+    searchJql(jql: string, maxResults?: number): Promise<JiraIssue[]>;
+}
+/**
+ * Convert simple markdown text to Atlassian Document Format (ADF).
+ * Handles paragraphs, bulletLists, tables, bold (**text**), italic (_text_),
+ * inline code (`text`), and links ([label](url)). Strips HTML comments.
+ * Good enough for status/clarification comments.
+ */
+export declare function markdownToAdf(markdown: string): object;