@avocadostudio-ai/orchestrator-core 0.1.0

package/dist/telemetry/migration-telemetry.d.ts

@@ -0,0 +1,35 @@
+/**
+ * Migration telemetry — persists per-migration run data to JSONL for analysis.
+ * Follows the same append-flush pattern as chat-telemetry.ts.
+ */
+export type MigrationTelemetryEntry = {
+    timestamp: string;
+    streamId: string;
+    status: "success" | "error";
+    durationMs: number;
+    numTurns: number;
+    toolCallCount: number;
+    toolsUsed: string[];
+    /** Tool call sequence with agent context (main vs subagent) */
+    toolDetails?: Array<{
+        tool: string;
+        agent: "main" | "sub";
+        durationMs?: number;
+    }>;
+    inputTokens: number;
+    outputTokens: number;
+    cacheReadInputTokens: number;
+    cacheCreationInputTokens: number;
+    totalCostUsd: number;
+    sitesCreated: string[];
+    userMessage?: string;
+    /** Per-model token + cost breakdown from Agent SDK */
+    modelBreakdown?: Record<string, {
+        inputTokens: number;
+        outputTokens: number;
+        costUsd: number;
+    }>;
+    /** Debug artifact directory for this run */
+    debugDir?: string;
+};
+export declare function pushMigrationTelemetry(entry: MigrationTelemetryEntry): void;

package/dist/telemetry/migration-telemetry.js

@@ -0,0 +1,40 @@
+/**
+ * Migration telemetry — persists per-migration run data to JSONL for analysis.
+ * Follows the same append-flush pattern as chat-telemetry.ts.
+ */
+import { appendFile, mkdir } from "node:fs/promises";
+import { resolve, dirname } from "node:path";
+import { homedir } from "node:os";
+const TELEMETRY_FILE = resolve(homedir(), ".data/telemetry/migration-telemetry.jsonl");
+const pendingWrites = [];
+let flushTimer = null;
+async function flushNow() {
+    if (pendingWrites.length === 0)
+        return;
+    const pending = pendingWrites.splice(0, pendingWrites.length);
+    const lines = pending.map((item) => JSON.stringify(item)).join("\n");
+    await mkdir(dirname(TELEMETRY_FILE), { recursive: true });
+    await appendFile(TELEMETRY_FILE, `${lines}\n`, "utf8");
+}
+function scheduleFlush() {
+    if (flushTimer)
+        clearTimeout(flushTimer);
+    flushTimer = setTimeout(() => {
+        void flushNow().catch((err) => {
+            console.error("[migration-telemetry] flush failed:", err instanceof Error ? err.message : String(err));
+        });
+    }, 150);
+    flushTimer.unref(); // don't keep the event loop alive for debug telemetry
+}
+// Flush on shutdown to avoid losing entries from multi-dollar agent runs
+process.on("beforeExit", () => { void flushNow().catch(() => { }); });
+export function pushMigrationTelemetry(entry) {
+    pendingWrites.push(entry);
+    scheduleFlush();
+    // Also log a summary line to console
+    const { inputTokens: inp, outputTokens: out, cacheReadInputTokens: cacheR, cacheCreationInputTokens: cacheC, totalCostUsd: cost } = entry;
+    console.log(`[migration-telemetry] ${entry.streamId.slice(0, 8)} ${entry.status} | ` +
+        `${entry.numTurns} turns, ${entry.toolCallCount} tools | ` +
+        `tokens: in=${inp} out=${out} cache_read=${cacheR} cache_create=${cacheC} | ` +
+        `cost=$${cost.toFixed(4)} | ${(entry.durationMs / 1000).toFixed(1)}s`);
+}

package/dist/telemetry/usage.d.ts

@@ -0,0 +1,24 @@
+export type TokenUsage = {
+    inputTokens: number;
+    outputTokens: number;
+    totalTokens: number;
+    cacheCreationInputTokens?: number;
+    cacheReadInputTokens?: number;
+};
+export declare const ZERO_USAGE: TokenUsage;
+/**
+ * Extract token usage from an OpenAI or Anthropic API response object.
+ * Handles both `prompt_tokens`/`completion_tokens` (OpenAI) and
+ * `input_tokens`/`output_tokens` (Anthropic) naming conventions.
+ */
+export declare function extractUsage(source: unknown): TokenUsage;
+/** USD per 1 million tokens. Keys use prefix matching. */
+export declare const USD_PER_MTOK: Record<string, {
+    input: number;
+    output: number;
+}>;
+/**
+ * Estimate the USD cost for a given model and token usage.
+ * Uses exact key match first, then falls back to prefix matching.
+ */
+export declare function estimateUsd(model: string, usage: TokenUsage): number | null;

package/dist/telemetry/usage.js

@@ -0,0 +1,80 @@
+// ---------------------------------------------------------------------------
+// Token usage tracking — extracted from benchmark-models.ts for reuse
+// ---------------------------------------------------------------------------
+export const ZERO_USAGE = { inputTokens: 0, outputTokens: 0, totalTokens: 0 };
+/**
+ * Extract token usage from an OpenAI or Anthropic API response object.
+ * Handles both `prompt_tokens`/`completion_tokens` (OpenAI) and
+ * `input_tokens`/`output_tokens` (Anthropic) naming conventions.
+ */
+export function extractUsage(source) {
+    const usage = source?.usage;
+    if (!usage)
+        return { ...ZERO_USAGE };
+    const promptTokens = typeof usage.prompt_tokens === "number" ? usage.prompt_tokens : 0;
+    const completionTokens = typeof usage.completion_tokens === "number" ? usage.completion_tokens : 0;
+    const inputTokens = typeof usage.input_tokens === "number" ? usage.input_tokens : promptTokens;
+    const outputTokens = typeof usage.output_tokens === "number" ? usage.output_tokens : completionTokens;
+    const anthropicCacheCreationTokensRaw = usage.cache_creation_input_tokens;
+    const anthropicCacheReadTokensRaw = usage.cache_read_input_tokens;
+    const openAIPromptDetails = usage.prompt_tokens_details;
+    const openAIInputDetails = usage.input_tokens_details;
+    const openAICachedPromptTokensRaw = openAIPromptDetails?.cached_tokens;
+    const openAICachedInputTokensRaw = openAIInputDetails?.cached_tokens;
+    const cacheCreationInputTokens = typeof anthropicCacheCreationTokensRaw === "number"
+        ? Math.max(0, anthropicCacheCreationTokensRaw)
+        : undefined;
+    const cacheReadInputTokens = typeof anthropicCacheReadTokensRaw === "number"
+        ? Math.max(0, anthropicCacheReadTokensRaw)
+        : typeof openAICachedPromptTokensRaw === "number"
+            ? Math.max(0, openAICachedPromptTokensRaw)
+            : typeof openAICachedInputTokensRaw === "number"
+                ? Math.max(0, openAICachedInputTokensRaw)
+                : undefined;
+    const totalTokens = typeof usage.total_tokens === "number" ? usage.total_tokens : Math.max(0, inputTokens) + Math.max(0, outputTokens);
+    return {
+        inputTokens: Math.max(0, inputTokens),
+        outputTokens: Math.max(0, outputTokens),
+        totalTokens: Math.max(0, totalTokens),
+        ...(cacheCreationInputTokens !== undefined ? { cacheCreationInputTokens } : {}),
+        ...(cacheReadInputTokens !== undefined ? { cacheReadInputTokens } : {})
+    };
+}
+// ---------------------------------------------------------------------------
+// Cost estimation
+// ---------------------------------------------------------------------------
+/** USD per 1 million tokens. Keys use prefix matching. */
+export const USD_PER_MTOK = {
+    // OpenAI — current GA lineup (exact match wins over the "gpt-*" prefix fallbacks below).
+    "gpt-5.6-sol": { input: 5, output: 30 },
+    "gpt-5.6-terra": { input: 2.5, output: 15 },
+    "gpt-5.6-luna": { input: 1, output: 6 },
+    "gpt-5.3-codex": { input: 1.75, output: 14 },
+    "gpt-5.4-nano": { input: 0.2, output: 1.25 },
+    // OpenAI — legacy, still served / referenced by env overrides.
+    "gpt-4o-mini": { input: 0.15, output: 0.6 },
+    "gpt-4o": { input: 2.5, output: 10 },
+    "gpt-5": { input: 1.25, output: 10 },
+    // Gemini — current GA lineup. Pro tiers are per-request >200K jumps ($2.50/$15);
+    // we track the base ≤200K rate, matching how the other rows report standard usage.
+    "gemini-3.6-flash": { input: 1.5, output: 7.5 },
+    "gemini-3.5-flash-lite": { input: 0.3, output: 2.5 },
+    "gemini-2.5-pro": { input: 1.25, output: 10 },
+    "gemini-2.5-flash": { input: 0.3, output: 2.5 },
+    // Prefix-matched. Rates current as of the Opus 4.8 / Sonnet 5 / Haiku 4.5 tier.
+    // Sonnet 5 has an intro rate of $2/$10 through 2026-08-31; we track the standard
+    // $3/$15 so cost estimates don't under-report once the intro window closes.
+    "claude-haiku": { input: 1, output: 5 },
+    "claude-sonnet": { input: 3, output: 15 },
+    "claude-opus": { input: 5, output: 25 }
+};
+/**
+ * Estimate the USD cost for a given model and token usage.
+ * Uses exact key match first, then falls back to prefix matching.
+ */
+export function estimateUsd(model, usage) {
+    const pricing = USD_PER_MTOK[model] ?? USD_PER_MTOK[Object.keys(USD_PER_MTOK).find((key) => model.startsWith(key)) ?? ""];
+    if (!pricing)
+        return null;
+    return (usage.inputTokens / 1_000_000) * pricing.input + (usage.outputTokens / 1_000_000) * pricing.output;
+}

package/dist/tools/builtin-registrations.d.ts

@@ -0,0 +1,12 @@
+import type { ToolRegistry } from "./registry.ts";
+export type DefaultBuiltinName = "unsplash-search" | "image-generate" | "gdrive-browse";
+export interface RegisterDefaultBuiltinsOptions {
+    /**
+     * Override which builtins are registered. Defaults to env-gated behavior:
+     *   - unsplash-search: always
+     *   - image-generate:  when OPENAI_API_KEY or GOOGLE_GENAI_API_KEY is set
+     *   - gdrive-browse:   when GOOGLE_DRIVE_FOLDER_ID is set
+     */
+    include?: DefaultBuiltinName[];
+}
+export declare function registerDefaultBuiltins(registry: ToolRegistry, options?: RegisterDefaultBuiltinsOptions): DefaultBuiltinName[];

package/dist/tools/builtin-registrations.js

@@ -0,0 +1,33 @@
+// Default builtin tool registrations.
+//
+// Kept in a separate module so that importing tools/runtime.ts does NOT
+// transitively pull in the image/ subdir (and therefore sharp + googleapis
+// + the image-generation SDKs). Library-mode consumers that only need the
+// chat planner can skip this module entirely; the Fastify orchestrator at
+// apps/orchestrator/src/index.ts calls registerDefaultBuiltins() at startup.
+import { unsplashSearchHandler, unsplashSearchManifest } from "./builtins/unsplash-search.js";
+import { imageGenerateHandler, imageGenerateManifest } from "./builtins/image-generate.js";
+import { gdriveBrowseHandler, gdriveBrowseManifest } from "./builtins/gdrive-browse.js";
+export function registerDefaultBuiltins(registry, options = {}) {
+    const env = process.env;
+    const defaultInclude = ["unsplash-search"];
+    if (env.OPENAI_API_KEY || env.GOOGLE_GENAI_API_KEY)
+        defaultInclude.push("image-generate");
+    if (env.GOOGLE_DRIVE_FOLDER_ID)
+        defaultInclude.push("gdrive-browse");
+    const include = options.include ?? defaultInclude;
+    const registered = [];
+    if (include.includes("unsplash-search")) {
+        registry.registerBuiltin(unsplashSearchManifest, unsplashSearchHandler);
+        registered.push("unsplash-search");
+    }
+    if (include.includes("image-generate")) {
+        registry.registerBuiltin(imageGenerateManifest, imageGenerateHandler);
+        registered.push("image-generate");
+    }
+    if (include.includes("gdrive-browse")) {
+        registry.registerBuiltin(gdriveBrowseManifest, gdriveBrowseHandler);
+        registered.push("gdrive-browse");
+    }
+    return registered;
+}

package/dist/tools/builtins/gdrive-browse.d.ts

@@ -0,0 +1,3 @@
+import type { ToolManifest, ToolHandler } from "../types.ts";
+export declare const gdriveBrowseManifest: ToolManifest;
+export declare const gdriveBrowseHandler: ToolHandler;

package/dist/tools/builtins/gdrive-browse.js

@@ -0,0 +1,68 @@
+import { listImages, isGdriveConfigured, fileNameToAlt, resolveGdriveFolderId } from "../../image/gdrive-client.js";
+export const gdriveBrowseManifest = {
+    name: "gdrive.browse",
+    description: "Browse and search images in the shared Google Drive folder. Use for brand assets, company photos, or user-uploaded images.",
+    capability: "read",
+    timeoutMs: 8000,
+    retryPolicy: { maxAttempts: 2, backoffMs: 200 },
+    idempotent: true,
+    inputSchema: {
+        type: "object",
+        additionalProperties: false,
+        required: [],
+        properties: {
+            query: { type: "string", description: "Optional search text to filter images by name" },
+            limit: { type: "integer", description: "Max results (1-10, default 5)" }
+        }
+    },
+    outputSchema: {
+        type: "object",
+        additionalProperties: false,
+        required: ["items"],
+        properties: {
+            items: {
+                type: "array",
+                items: {
+                    type: "object",
+                    additionalProperties: false,
+                    required: ["id", "imageUrl", "thumbUrl", "alt", "author", "sourceUrl"],
+                    properties: {
+                        id: { type: "string" },
+                        imageUrl: { type: "string" },
+                        thumbUrl: { type: "string" },
+                        alt: { type: "string" },
+                        author: { type: "string" },
+                        sourceUrl: { type: "string" }
+                    }
+                }
+            }
+        }
+    }
+};
+export const gdriveBrowseHandler = async ({ input, context }) => {
+    if (!isGdriveConfigured() && !context.gdriveFolderId) {
+        return { items: [] };
+    }
+    const typed = (input ?? {});
+    const query = typeof typed.query === "string" ? typed.query.trim() : undefined;
+    const limitRaw = typeof typed.limit === "number" ? typed.limit : 5;
+    const limit = Math.min(10, Math.max(1, Math.trunc(limitRaw)));
+    const folderId = resolveGdriveFolderId(context.gdriveFolderId);
+    if (!folderId)
+        return { items: [] };
+    const orchestratorPublicOrigin = (process.env.ORCHESTRATOR_PUBLIC_ORIGIN ?? "http://localhost:4200").replace(/\/+$/, "");
+    const files = await listImages(folderId, query, undefined, limit);
+    const items = files.map((file) => {
+        const imageUrl = `${orchestratorPublicOrigin}/gdrive/images/${file.id}`;
+        const thumbUrl = imageUrl;
+        return {
+            id: file.id,
+            imageUrl,
+            thumbUrl,
+            alt: fileNameToAlt(file.name),
+            author: "Google Drive",
+            sourceUrl: `https://drive.google.com/file/d/${file.id}/view`
+        };
+    });
+    return { items };
+};

package/dist/tools/builtins/image-generate.d.ts

@@ -0,0 +1,3 @@
+import type { ToolManifest, ToolHandler } from "../types.ts";
+export declare const imageGenerateManifest: ToolManifest;
+export declare const imageGenerateHandler: ToolHandler;

package/dist/tools/builtins/image-generate.js

@@ -0,0 +1,211 @@
+import { generateVariationImageWithOpenAI, generateVariationImageWithGemini, recordImageGenDuration, estimatedImageGenMs } from "../../image/image-helpers.js";
+import { getPage } from "../../state/session-state.js";
+const ASPECT_RATIO_TO_SIZE = {
+    landscape: "1536x1024",
+    square: "1024x1024",
+    portrait: "1024x1536"
+};
+const SIZE_DIMENSIONS = {
+    "1536x1024": { width: 1536, height: 1024 },
+    "1024x1024": { width: 1024, height: 1024 },
+    "1024x1536": { width: 1024, height: 1536 }
+};
+const COMPOSITION_HINTS = {
+    Hero: "Full-width hero section — landscape, cinematic, attention-grabbing",
+    Banner: "Banner strip — wide landscape, clean with space for overlay text",
+    CTA: "Call-to-action section — atmospheric, supportive background",
+    Card: "Card thumbnail — balanced square or portrait composition, focused subject",
+    CardGrid: "Card grid thumbnail — balanced, consistent style across cards",
+    FeatureGrid: "Feature illustration — clean, focused, minimal background",
+    Gallery: "Gallery image — well-composed, standalone photograph",
+    Carousel: "Carousel slide — landscape, visually striking",
+    TwoColumn: "Two-column layout image — balanced composition, clear subject",
+};
+/**
+ * Enrich a bare prompt with block/page context for better image generation.
+ */
+function enrichPromptWithContext(basePrompt, ctx) {
+    const parts = [];
+    if (ctx.blockType) {
+        parts.push(`Image for: ${ctx.blockType} block`);
+        const hint = COMPOSITION_HINTS[ctx.blockType];
+        if (hint)
+            parts.push(`Composition: ${hint}`);
+    }
+    // Look up block content for richer context
+    if (ctx.session && ctx.blockId && ctx.pageSlug) {
+        try {
+            const page = getPage(ctx.session, ctx.pageSlug);
+            if (page) {
+                if (page.title)
+                    parts.push(`Page: "${page.title}"`);
+                const block = page.blocks.find(b => b.id === ctx.blockId);
+                if (block) {
+                    const props = block.props;
+                    const heading = typeof props.heading === "string" ? props.heading : "";
+                    const subheading = typeof props.subheading === "string" ? props.subheading : "";
+                    const title = typeof props.title === "string" ? props.title : "";
+                    if (heading)
+                        parts.push(`Block heading: "${heading}"`);
+                    if (subheading)
+                        parts.push(`Block subheading: "${subheading}"`);
+                    if (title && title !== heading)
+                        parts.push(`Block title: "${title}"`);
+                }
+            }
+        }
+        catch {
+            // Session lookup may fail — just skip context enrichment
+        }
+    }
+    parts.push(`\nUser request: ${basePrompt}`);
+    if (ctx.style)
+        parts.push(`Style: ${ctx.style}`);
+    if (ctx.background === "transparent")
+        parts.push("Background: transparent (no background, isolated subject)");
+    parts.push("Constraints: no text overlays, no logos, no watermarks");
+    return parts.join("\n");
+}
+export const imageGenerateManifest = {
+    name: "image.generate",
+    description: "Generate an AI image from a text prompt. Default to quality 'draft'. Use 'final' only when the user explicitly asks for high quality, polished, or production-ready images.",
+    capability: "read",
+    timeoutMs: 90000,
+    retryPolicy: { maxAttempts: 1 },
+    idempotent: false,
+    inputSchema: {
+        type: "object",
+        additionalProperties: false,
+        required: ["prompt"],
+        properties: {
+            prompt: { type: "string", description: "Detailed text prompt describing the image to generate" },
+            aspectRatio: {
+                type: "string",
+                enum: ["landscape", "square", "portrait"],
+                description: "Aspect ratio of the generated image (default: landscape)"
+            },
+            quality: {
+                type: "string",
+                enum: ["draft", "final"],
+                description: "Image quality tier: 'draft' for fast previews, 'final' for production-ready"
+            },
+            style: { type: "string", description: "Optional style guidance (e.g. 'photorealistic', 'illustration')" },
+            background: {
+                type: "string",
+                enum: ["transparent", "opaque", "auto"],
+                description: "Background mode: 'transparent' for cutout/isolated subjects (logos, icons, product shots), 'opaque' for full scenes, 'auto' lets the model decide (default: auto)"
+            },
+            outputFormat: {
+                type: "string",
+                enum: ["png", "webp", "jpeg"],
+                description: "Output image format (default: png). Use png for transparency, webp for smaller files, jpeg for photos."
+            },
+            blockType: { type: "string", description: "Block type the image is for (e.g. 'Hero', 'Card') — helps match composition to layout" },
+            blockId: { type: "string", description: "Block ID — used to look up block content for context-aware generation" },
+            pageSlug: { type: "string", description: "Page slug — used with blockId to look up surrounding content" },
+        }
+    },
+    outputSchema: {
+        type: "object",
+        additionalProperties: false,
+        required: ["imageUrl", "alt", "width", "height"],
+        properties: {
+            imageUrl: { type: "string" },
+            alt: { type: "string" },
+            width: { type: "integer" },
+            height: { type: "integer" }
+        }
+    }
+};
+export const imageGenerateHandler = async ({ input, context, signal }) => {
+    const typed = (input ?? {});
+    const prompt = typeof typed.prompt === "string" ? typed.prompt.trim() : "";
+    if (!prompt) {
+        throw new Error("prompt is required for image.generate");
+    }
+    const aspectRatio = typed.aspectRatio ?? "landscape";
+    const quality = typed.quality ?? "draft";
+    const background = typed.background ?? "auto";
+    const outputFormat = typed.outputFormat ?? "png";
+    const size = ASPECT_RATIO_TO_SIZE[aspectRatio] ?? "1536x1024";
+    const dims = SIZE_DIMENSIONS[size] ?? { width: 1536, height: 1024 };
+    const model = quality === "final"
+        ? (process.env.OPENAI_IMAGE_MODEL?.trim() || "gpt-image-2")
+        : (process.env.OPENAI_IMAGE_MODEL_DRAFT?.trim() || "gpt-image-1-mini");
+    // Enrich prompt with block/page context when available
+    const hasContext = typed.blockType || typed.blockId || typed.pageSlug;
+    const enrichedPrompt = hasContext
+        ? enrichPromptWithContext(prompt, {
+            session: context.sessionId,
+            blockType: typed.blockType,
+            blockId: typed.blockId,
+            pageSlug: typed.pageSlug,
+            style: typed.style,
+            background,
+        })
+        : (typed.style ? `${prompt}. Style: ${typed.style}` : prompt);
+    context.onStatusUpdate?.("Generating AI image\u2026");
+    // Start progress timer for long-running image generation
+    const onProgress = context.onImageProgress;
+    const stages = [
+        { at: 0.00, pct: 0, label: "Understanding prompt\u2026" },
+        { at: 0.10, pct: 15, label: "Composing scene\u2026" },
+        { at: 0.30, pct: 40, label: "Rendering image\u2026" },
+        { at: 0.65, pct: 75, label: "Finalizing details\u2026" },
+        { at: 0.90, pct: 95, label: "Almost there\u2026" },
+    ];
+    const estimated = estimatedImageGenMs();
+    const startedAt = Date.now();
+    let currentStageIdx = 0;
+    onProgress?.({ percent: 0, stage: stages[0].label });
+    const progressTimer = onProgress ? setInterval(() => {
+        const elapsed = Date.now() - startedAt;
+        const progress = Math.min(elapsed / estimated, 1);
+        while (currentStageIdx < stages.length - 1 && progress >= stages[currentStageIdx + 1].at) {
+            currentStageIdx++;
+        }
+        const cur = stages[currentStageIdx];
+        const next = stages[currentStageIdx + 1] ?? { at: 1, pct: 95 };
+        const stageProgress = (progress - cur.at) / (next.at - cur.at);
+        const pct = Math.min(Math.round(cur.pct + stageProgress * (next.pct - cur.pct)), 95);
+        onProgress({ percent: pct, stage: cur.label });
+    }, 500) : null;
+    const provider = (process.env.IMAGE_GEN_PROVIDER?.trim().toLowerCase()) || "openai";
+    const genStart = Date.now();
+    let result = null;
+    try {
+        result = provider === "gemini"
+            ? await generateVariationImageWithGemini({
+                prompt: enrichedPrompt,
+                altText: prompt,
+                aspectRatio,
+                quality,
+                background,
+                signal,
+            })
+            : await generateVariationImageWithOpenAI({
+                prompt: enrichedPrompt,
+                altText: prompt,
+                size,
+                model,
+                background,
+                outputFormat,
+                signal,
+            });
+    }
+    finally {
+        recordImageGenDuration(Date.now() - genStart);
+        if (progressTimer)
+            clearInterval(progressTimer);
+    }
+    onProgress?.({ percent: 100, stage: "Done" });
+    if (!result) {
+        throw new Error("Image generation failed — no image was returned");
+    }
+    return {
+        imageUrl: result.url,
+        alt: result.alt,
+        width: dims.width,
+        height: dims.height
+    };
+};

package/dist/tools/builtins/unsplash-get-by-id.d.ts

@@ -0,0 +1,23 @@
+/**
+ * Resolve an Unsplash photo page URL or bare photo ID to a direct image asset
+ * URL via the Unsplash REST API.
+ *
+ * Reporters frequently drop links like
+ *   https://unsplash.com/photos/an-aerial-view-of-lava-in-the-ocean-4c0JJqaG93c
+ * which are HTML pages, not image assets. Setting `imageUrl` to those breaks
+ * the `<img>` tag. This tool extracts the ID (last token after the final
+ * hyphen) and fetches `GET /photos/:id` to get `urls.regular`.
+ */
+import type { ToolManifest, ToolHandler } from "../types.ts";
+export declare const unsplashGetByIdManifest: ToolManifest;
+/**
+ * Pull the photo ID out of an Unsplash URL. Supported shapes:
+ *   https://unsplash.com/photos/PHOTOID
+ *   https://unsplash.com/photos/slug-with-hyphens-PHOTOID
+ *   https://unsplash.com/photos/PHOTOID?ixid=...
+ *   http(s)://www.unsplash.com/... (www prefix + http tolerated)
+ *
+ * Returns null when the URL is not an unsplash.com/photos/* link.
+ */
+export declare function extractUnsplashPhotoId(input: string): string | null;
+export declare const unsplashGetByIdHandler: ToolHandler;

package/dist/tools/builtins/unsplash-get-by-id.js

@@ -0,0 +1,119 @@
+/**
+ * Resolve an Unsplash photo page URL or bare photo ID to a direct image asset
+ * URL via the Unsplash REST API.
+ *
+ * Reporters frequently drop links like
+ *   https://unsplash.com/photos/an-aerial-view-of-lava-in-the-ocean-4c0JJqaG93c
+ * which are HTML pages, not image assets. Setting `imageUrl` to those breaks
+ * the `<img>` tag. This tool extracts the ID (last token after the final
+ * hyphen) and fetches `GET /photos/:id` to get `urls.regular`.
+ */
+export const unsplashGetByIdManifest = {
+    name: "unsplash.get_by_id",
+    description: "Resolve an Unsplash photo page URL or ID to a direct image asset URL",
+    capability: "read",
+    timeoutMs: 6000,
+    retryPolicy: { maxAttempts: 2, backoffMs: 200 },
+    idempotent: true,
+    inputSchema: {
+        type: "object",
+        additionalProperties: false,
+        properties: {
+            url: { type: "string", description: "Unsplash photo page URL, e.g. https://unsplash.com/photos/slug-PHOTOID" },
+            photoId: { type: "string", description: "Bare Unsplash photo ID (alternative to url)" },
+        },
+    },
+    outputSchema: {
+        type: "object",
+        additionalProperties: false,
+        required: ["imageUrl", "alt", "author", "sourceUrl", "photoId"],
+        properties: {
+            imageUrl: { type: "string" },
+            alt: { type: "string" },
+            author: { type: "string" },
+            sourceUrl: { type: "string" },
+            photoId: { type: "string" },
+        },
+    },
+};
+/**
+ * Pull the photo ID out of an Unsplash URL. Supported shapes:
+ *   https://unsplash.com/photos/PHOTOID
+ *   https://unsplash.com/photos/slug-with-hyphens-PHOTOID
+ *   https://unsplash.com/photos/PHOTOID?ixid=...
+ *   http(s)://www.unsplash.com/... (www prefix + http tolerated)
+ *
+ * Returns null when the URL is not an unsplash.com/photos/* link.
+ */
+export function extractUnsplashPhotoId(input) {
+    const trimmed = input.trim();
+    if (!trimmed)
+        return null;
+    // Bare ID path (no slashes, no dots) — just validate shape
+    if (!trimmed.includes("/") && !trimmed.includes(".")) {
+        return /^[A-Za-z0-9_-]{6,}$/.test(trimmed) ? trimmed : null;
+    }
+    let url;
+    try {
+        url = new URL(trimmed);
+    }
+    catch {
+        return null;
+    }
+    if (!/(^|\.)unsplash\.com$/i.test(url.hostname))
+        return null;
+    const segments = url.pathname.split("/").filter(Boolean);
+    const photosIdx = segments.indexOf("photos");
+    if (photosIdx === -1 || photosIdx === segments.length - 1)
+        return null;
+    const slug = segments[photosIdx + 1];
+    // The photo ID is the trailing token after the last hyphen, or the whole slug
+    // if there are no hyphens (bare-ID form).
+    const lastHyphen = slug.lastIndexOf("-");
+    const candidate = lastHyphen === -1 ? slug : slug.slice(lastHyphen + 1);
+    return /^[A-Za-z0-9_-]{6,}$/.test(candidate) ? candidate : null;
+}
+export const unsplashGetByIdHandler = async ({ input }) => {
+    const typed = (input ?? {});
+    const rawId = typeof typed.photoId === "string" ? typed.photoId.trim() : "";
+    const rawUrl = typeof typed.url === "string" ? typed.url.trim() : "";
+    const photoId = rawId || (rawUrl ? extractUnsplashPhotoId(rawUrl) : null);
+    if (!photoId) {
+        throw new Error("Could not extract an Unsplash photo ID from the input. Provide an unsplash.com/photos/... URL or a bare photo ID.");
+    }
+    const accessKey = process.env.UNSPLASH_ACCESS_KEY?.trim();
+    if (!accessKey) {
+        throw new Error("UNSPLASH_ACCESS_KEY is not configured on the orchestrator.");
+    }
+    const endpoint = `https://api.unsplash.com/photos/${encodeURIComponent(photoId)}`;
+    const res = await fetch(endpoint, {
+        headers: {
+            Authorization: `Client-ID ${accessKey}`,
+            "Accept-Version": "v1",
+        },
+    });
+    if (!res.ok) {
+        const body = await res.text().catch(() => "");
+        throw new Error(`Unsplash API ${res.status}: ${res.statusText} — ${body.slice(0, 200)}`);
+    }
+    const data = (await res.json());
+    const base = typeof data.urls?.regular === "string" ? data.urls.regular
+        : typeof data.urls?.full === "string" ? data.urls.full
+            : typeof data.urls?.raw === "string" ? data.urls.raw
+                : "";
+    if (!base)
+        throw new Error("Unsplash response did not include a usable image URL.");
+    const joiner = base.includes("?") ? "&" : "?";
+    const imageUrl = `${base}${joiner}auto=format&fit=crop&w=1600&q=80`;
+    const altRaw = typeof data.alt_description === "string" ? data.alt_description
+        : typeof data.description === "string" ? data.description
+            : "";
+    const result = {
+        imageUrl,
+        alt: altRaw.trim() || "Unsplash photo",
+        author: typeof data.user?.name === "string" ? data.user.name : "Unsplash",
+        sourceUrl: typeof data.links?.html === "string" ? data.links.html : `https://unsplash.com/photos/${photoId}`,
+        photoId,
+    };
+    return result;
+};

package/dist/tools/builtins/unsplash-search.d.ts

@@ -0,0 +1,3 @@
+import type { ToolManifest, ToolHandler } from "../types.ts";
+export declare const unsplashSearchManifest: ToolManifest;
+export declare const unsplashSearchHandler: ToolHandler;