agent-nuvira 3.3.8 → 3.3.9

package/dist/tools/modality/image-providers.d.ts

@@ -0,0 +1,71 @@
+/**
+ * Image-generation provider registry (`src/tools/modality/image-providers.ts`).
+ *
+ * The single source of truth for every backend `generate_image` can reach —
+ * mirroring the LLM `provider-catalog.ts` pattern so "add a provider" is data,
+ * not a code path. This is what makes BYOK real for images: a user who sets
+ * `GEMINI_API_KEY`, `OPENAI_API_KEY` or `STABILITY_API_KEY` gets that backend
+ * automatically; with nothing configured the free Pollinations endpoint runs.
+ *
+ * Selection (`resolveImageProvider`):
+ *   1. an explicit `provider` option / `modality.image.provider` config;
+ *   2. otherwise the first AVAILABLE provider in `IMAGE_PROVIDER_PRIORITY`
+ *      (Gemini → OpenAI → Stability → local ComfyUI → Pollinations).
+ * A configured-but-failing backend falls back to Pollinations in `generate-image.ts`.
+ *
+ * Env vars are read dual-form (`NUVIRA_`/`BUFF_` prefixed OR plain) so both a
+ * bare `export GEMINI_API_KEY=…` and the nuvira-style override work.
+ */
+export type ImageProviderId = 'gemini' | 'openai' | 'stability' | 'comfyui' | 'pollinations';
+export interface ImageGenerationRequest {
+    prompt: string;
+    width: number;
+    height: number;
+    /** Model override (provider-specific). */
+    model?: string;
+    /** Explicit local endpoint (overrides the IMAGE_API_URL env). */
+    endpoint?: string;
+}
+export interface ImageGenerationResult {
+    bytes: Buffer;
+    /** File extension including the dot ('.png' | '.jpg'). */
+    ext: '.png' | '.jpg';
+}
+export interface ImageProvider {
+    id: ImageProviderId;
+    label: string;
+    /** Env vars that can supply the key (prefixed or plain; first set wins). */
+    keyEnvVars: string[];
+    /** Default model when none is configured. */
+    defaultModel: string;
+    /** Approximate USD per image (0 = free). */
+    costPerUnit: number;
+    /** Quality score 0–1 (used only for reporting/priority). */
+    quality: number;
+    /** True when this backend needs an API key / endpoint to run. */
+    requiresConfig: boolean;
+    /** Is the backend usable right now (key/endpoint present)? */
+    available(): boolean;
+    /** Generate the image bytes, or throw with a descriptive message. */
+    generate(req: ImageGenerationRequest): Promise<ImageGenerationResult>;
+}
+/** The local ComfyUI / Stable Diffusion endpoint, if configured. */
+export declare function localImageEndpoint(): string | undefined;
+/** The registry — single source of image-backend metadata + generation. */
+export declare const IMAGE_PROVIDERS: Record<ImageProviderId, ImageProvider>;
+/**
+ * Auto-selection order when nothing is configured explicitly. Cloud backends
+ * the user paid for outrank the local/free ones; Pollinations is always the
+ * last-resort fallback.
+ */
+export declare const IMAGE_PROVIDER_PRIORITY: readonly ImageProviderId[];
+/** Is the provider a known registry id? */
+export declare function isImageProviderId(value: string | undefined): value is ImageProviderId;
+/** Provider ids currently usable (for CLI/dashboard diagnostics). */
+export declare function availableImageProviders(): ImageProviderId[];
+/**
+ * Which backend will run. An explicit, known `provider` wins; else the first
+ * available provider in priority order; else Pollinations.
+ */
+export declare function resolveImageProvider(requested?: string): ImageProviderId;
+//# sourceMappingURL=image-providers.d.ts.map

package/dist/tools/modality/image-providers.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"image-providers.d.ts","sourceRoot":"","sources":["../../../src/tools/modality/image-providers.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;GAiBG;AAMH,MAAM,MAAM,eAAe,GAAG,QAAQ,GAAG,QAAQ,GAAG,WAAW,GAAG,SAAS,GAAG,cAAc,CAAC;AAE7F,MAAM,WAAW,sBAAsB;IACrC,MAAM,EAAE,MAAM,CAAC;IACf,KAAK,EAAE,MAAM,CAAC;IACd,MAAM,EAAE,MAAM,CAAC;IACf,0CAA0C;IAC1C,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,iEAAiE;IACjE,QAAQ,CAAC,EAAE,MAAM,CAAC;CACnB;AAED,MAAM,WAAW,qBAAqB;IACpC,KAAK,EAAE,MAAM,CAAC;IACd,0DAA0D;IAC1D,GAAG,EAAE,MAAM,GAAG,MAAM,CAAC;CACtB;AAED,MAAM,WAAW,aAAa;IAC5B,EAAE,EAAE,eAAe,CAAC;IACpB,KAAK,EAAE,MAAM,CAAC;IACd,4EAA4E;IAC5E,UAAU,EAAE,MAAM,EAAE,CAAC;IACrB,6CAA6C;IAC7C,YAAY,EAAE,MAAM,CAAC;IACrB,4CAA4C;IAC5C,WAAW,EAAE,MAAM,CAAC;IACpB,4DAA4D;IAC5D,OAAO,EAAE,MAAM,CAAC;IAChB,iEAAiE;IACjE,cAAc,EAAE,OAAO,CAAC;IACxB,8DAA8D;IAC9D,SAAS,IAAI,OAAO,CAAC;IACrB,qEAAqE;IACrE,QAAQ,CAAC,GAAG,EAAE,sBAAsB,GAAG,OAAO,CAAC,qBAAqB,CAAC,CAAC;CACvE;AAaD,oEAAoE;AACpE,wBAAgB,kBAAkB,IAAI,MAAM,GAAG,SAAS,CAEvD;AAkID,2EAA2E;AAC3E,eAAO,MAAM,eAAe,EAAE,MAAM,CAAC,eAAe,EAAE,aAAa,CAwDlE,CAAC;AAEF;;;;GAIG;AACH,eAAO,MAAM,uBAAuB,EAAE,SAAS,eAAe,EAM7D,CAAC;AAIF,2CAA2C;AAC3C,wBAAgB,iBAAiB,CAAC,KAAK,EAAE,MAAM,GAAG,SAAS,GAAG,KAAK,IAAI,eAAe,CAErF;AAED,qEAAqE;AACrE,wBAAgB,uBAAuB,IAAI,eAAe,EAAE,CAE3D;AAED;;;GAGG;AACH,wBAAgB,oBAAoB,CAAC,SAAS,CAAC,EAAE,MAAM,GAAG,eAAe,CAMxE"}

package/dist/tools/modality/image-providers.js

@@ -0,0 +1,277 @@
+/**
+ * Image-generation provider registry (`src/tools/modality/image-providers.ts`).
+ *
+ * The single source of truth for every backend `generate_image` can reach —
+ * mirroring the LLM `provider-catalog.ts` pattern so "add a provider" is data,
+ * not a code path. This is what makes BYOK real for images: a user who sets
+ * `GEMINI_API_KEY`, `OPENAI_API_KEY` or `STABILITY_API_KEY` gets that backend
+ * automatically; with nothing configured the free Pollinations endpoint runs.
+ *
+ * Selection (`resolveImageProvider`):
+ *   1. an explicit `provider` option / `modality.image.provider` config;
+ *   2. otherwise the first AVAILABLE provider in `IMAGE_PROVIDER_PRIORITY`
+ *      (Gemini → OpenAI → Stability → local ComfyUI → Pollinations).
+ * A configured-but-failing backend falls back to Pollinations in `generate-image.ts`.
+ *
+ * Env vars are read dual-form (`NUVIRA_`/`BUFF_` prefixed OR plain) so both a
+ * bare `export GEMINI_API_KEY=…` and the nuvira-style override work.
+ */
+import { envBuff } from '../../config/paths.js';
+// ─── Env helpers ────────────────────────────────────────────────────────────
+/** Read the first non-empty value among names (prefixed + plain). */
+function keyFromEnv(names) {
+    for (const name of names) {
+        const value = (envBuff(name) ?? process.env[name])?.trim();
+        if (value)
+            return value;
+    }
+    return undefined;
+}
+/** The local ComfyUI / Stable Diffusion endpoint, if configured. */
+export function localImageEndpoint() {
+    return envBuff('IMAGE_API_URL') || process.env.IMAGE_API_URL;
+}
+// ─── Provider implementations ───────────────────────────────────────────────
+const POLLINATIONS_BASE = 'https://image.pollinations.ai/prompt/';
+const GEMINI_BASE = 'https://generativelanguage.googleapis.com/v1beta/models';
+/** Gemini / Imagen ("Nano Banana") image generation. */
+async function geminiGenerate(req) {
+    const key = keyFromEnv(['GEMINI_API_KEY', 'GOOGLE_API_KEY']);
+    if (!key)
+        throw new Error('Gemini API key is not configured');
+    const model = req.model || 'gemini-2.5-flash-image';
+    if (/imagen/i.test(model)) {
+        // Imagen models use the :predict endpoint.
+        const res = await fetch(`${GEMINI_BASE}/${model}:predict?key=${encodeURIComponent(key)}`, {
+            method: 'POST',
+            headers: { 'content-type': 'application/json' },
+            body: JSON.stringify({ instances: [{ prompt: req.prompt }], parameters: { sampleCount: 1 } }),
+        });
+        if (!res.ok)
+            throw new Error(`Gemini Imagen HTTP ${res.status}`);
+        const data = (await res.json());
+        const pred = data.predictions?.[0];
+        if (!pred?.bytesBase64Encoded)
+            throw new Error('Gemini Imagen returned no image');
+        return { bytes: Buffer.from(pred.bytesBase64Encoded, 'base64'), ext: mimeToExt(pred.mimeType) };
+    }
+    // Gemini image models use :generateContent with IMAGE response modality.
+    const res = await fetch(`${GEMINI_BASE}/${model}:generateContent?key=${encodeURIComponent(key)}`, {
+        method: 'POST',
+        headers: { 'content-type': 'application/json' },
+        body: JSON.stringify({
+            contents: [{ parts: [{ text: req.prompt }] }],
+            generationConfig: { responseModalities: ['IMAGE'] },
+        }),
+    });
+    if (!res.ok)
+        throw new Error(`Gemini image HTTP ${res.status}`);
+    const data = (await res.json());
+    const parts = data.candidates?.[0]?.content?.parts ?? [];
+    const withImage = parts.find((p) => p.inlineData?.data || p.inline_data?.data);
+    const b64 = withImage?.inlineData?.data ?? withImage?.inline_data?.data;
+    if (!b64)
+        throw new Error('Gemini returned no image');
+    const mime = withImage?.inlineData?.mimeType ?? withImage?.inline_data?.mime_type;
+    return { bytes: Buffer.from(b64, 'base64'), ext: mimeToExt(mime) };
+}
+/** OpenAI image models: DALL·E (2/3) and gpt-image-1. */
+async function openaiGenerate(req) {
+    const key = keyFromEnv(['OPENAI_API_KEY']);
+    if (!key)
+        throw new Error('OpenAI API key is not configured');
+    const model = req.model || 'gpt-image-1';
+    const body = { model, prompt: req.prompt, n: 1 };
+    // gpt-image-* always returns b64 and rejects response_format; dall-e-* needs it.
+    if (!/gpt-image/i.test(model))
+        body.response_format = 'b64_json';
+    const size = pickOpenAiSize(model, req.width, req.height);
+    if (size)
+        body.size = size;
+    const res = await fetch('https://api.openai.com/v1/images/generations', {
+        method: 'POST',
+        headers: { Authorization: `Bearer ${key}`, 'content-type': 'application/json' },
+        body: JSON.stringify(body),
+    });
+    if (!res.ok)
+        throw new Error(`OpenAI image HTTP ${res.status}`);
+    const data = (await res.json());
+    const first = data.data?.[0];
+    if (first?.b64_json)
+        return { bytes: Buffer.from(first.b64_json, 'base64'), ext: '.png' };
+    if (first?.url) {
+        const img = await fetch(first.url);
+        if (!img.ok)
+            throw new Error(`OpenAI image download HTTP ${img.status}`);
+        return { bytes: Buffer.from(await img.arrayBuffer()), ext: '.png' };
+    }
+    throw new Error('OpenAI returned no image');
+}
+/** Stability AI (Stable Image Core / SD3). */
+async function stabilityGenerate(req) {
+    const key = keyFromEnv(['STABILITY_API_KEY']);
+    if (!key)
+        throw new Error('Stability API key is not configured');
+    const form = new FormData();
+    form.append('prompt', req.prompt);
+    form.append('output_format', 'png');
+    form.append('aspect_ratio', aspectRatio(req.width, req.height));
+    if (req.model)
+        form.append('model', req.model);
+    const res = await fetch('https://api.stability.ai/v2beta/stable-image/generate/core', {
+        method: 'POST',
+        headers: { Authorization: `Bearer ${key}`, Accept: 'image/*' },
+        body: form,
+    });
+    if (!res.ok)
+        throw new Error(`Stability HTTP ${res.status}`);
+    const contentType = res.headers.get('content-type') ?? '';
+    if (!contentType.startsWith('image/'))
+        throw new Error(`Stability returned ${contentType || 'a non-image response'}`);
+    const bytes = Buffer.from(await res.arrayBuffer());
+    if (bytes.length === 0)
+        throw new Error('Stability returned an empty image');
+    return { bytes, ext: contentType.includes('jpeg') ? '.jpg' : '.png' };
+}
+/** Local Stable Diffusion / ComfyUI — POST {prompt,width,height} → bytes. */
+async function comfyuiGenerate(req) {
+    const url = req.endpoint ?? localImageEndpoint();
+    if (!url)
+        throw new Error('local image endpoint (BUFF_IMAGE_API_URL) is not configured');
+    const res = await fetch(url, {
+        method: 'POST',
+        headers: { 'content-type': 'application/json' },
+        body: JSON.stringify({ prompt: req.prompt, width: req.width, height: req.height }),
+    });
+    if (!res.ok)
+        throw new Error(`local backend HTTP ${res.status}`);
+    const contentType = res.headers.get('content-type') ?? '';
+    const bytes = Buffer.from(await res.arrayBuffer());
+    if (bytes.length === 0)
+        throw new Error('local backend returned an empty image');
+    return { bytes, ext: contentType.includes('jpeg') ? '.jpg' : '.png' };
+}
+/** Pollinations.ai — free, keyless, `{prompt}.png` with size params. */
+async function pollinationsGenerate(req) {
+    const url = `${POLLINATIONS_BASE}${encodeURIComponent(req.prompt)}?width=${req.width}&height=${req.height}&nologo=true`;
+    const res = await fetch(url);
+    if (!res.ok)
+        throw new Error(`image fetch failed: HTTP ${res.status}`);
+    const bytes = Buffer.from(await res.arrayBuffer());
+    if (bytes.length === 0)
+        throw new Error('image fetch returned empty body');
+    return { bytes, ext: '.png' };
+}
+// ─── Catalog ────────────────────────────────────────────────────────────────
+/** The registry — single source of image-backend metadata + generation. */
+export const IMAGE_PROVIDERS = {
+    gemini: {
+        id: 'gemini',
+        label: 'Google Gemini / Imagen (Nano Banana)',
+        keyEnvVars: ['GEMINI_API_KEY', 'GOOGLE_API_KEY'],
+        defaultModel: 'gemini-2.5-flash-image',
+        costPerUnit: 0.039,
+        quality: 0.9,
+        requiresConfig: true,
+        available: () => Boolean(keyFromEnv(['GEMINI_API_KEY', 'GOOGLE_API_KEY'])),
+        generate: geminiGenerate,
+    },
+    openai: {
+        id: 'openai',
+        label: 'OpenAI (DALL·E / gpt-image)',
+        keyEnvVars: ['OPENAI_API_KEY'],
+        defaultModel: 'gpt-image-1',
+        costPerUnit: 0.04,
+        quality: 0.95,
+        requiresConfig: true,
+        available: () => Boolean(keyFromEnv(['OPENAI_API_KEY'])),
+        generate: openaiGenerate,
+    },
+    stability: {
+        id: 'stability',
+        label: 'Stability AI',
+        keyEnvVars: ['STABILITY_API_KEY'],
+        defaultModel: 'stable-image-core',
+        costPerUnit: 0.002,
+        quality: 0.85,
+        requiresConfig: true,
+        available: () => Boolean(keyFromEnv(['STABILITY_API_KEY'])),
+        generate: stabilityGenerate,
+    },
+    comfyui: {
+        id: 'comfyui',
+        label: 'Local ComfyUI / Stable Diffusion',
+        keyEnvVars: [],
+        defaultModel: 'local',
+        costPerUnit: 0,
+        quality: 0.9,
+        requiresConfig: true,
+        available: () => Boolean(localImageEndpoint()),
+        generate: comfyuiGenerate,
+    },
+    pollinations: {
+        id: 'pollinations',
+        label: 'Pollinations.ai (free)',
+        keyEnvVars: [],
+        defaultModel: 'pollinations',
+        costPerUnit: 0,
+        quality: 0.7,
+        requiresConfig: false,
+        available: () => true,
+        generate: pollinationsGenerate,
+    },
+};
+/**
+ * Auto-selection order when nothing is configured explicitly. Cloud backends
+ * the user paid for outrank the local/free ones; Pollinations is always the
+ * last-resort fallback.
+ */
+export const IMAGE_PROVIDER_PRIORITY = [
+    'gemini',
+    'openai',
+    'stability',
+    'comfyui',
+    'pollinations',
+];
+// ─── Selection ──────────────────────────────────────────────────────────────
+/** Is the provider a known registry id? */
+export function isImageProviderId(value) {
+    return Boolean(value && Object.prototype.hasOwnProperty.call(IMAGE_PROVIDERS, value));
+}
+/** Provider ids currently usable (for CLI/dashboard diagnostics). */
+export function availableImageProviders() {
+    return IMAGE_PROVIDER_PRIORITY.filter((id) => IMAGE_PROVIDERS[id].available());
+}
+/**
+ * Which backend will run. An explicit, known `provider` wins; else the first
+ * available provider in priority order; else Pollinations.
+ */
+export function resolveImageProvider(requested) {
+    if (isImageProviderId(requested))
+        return requested;
+    for (const id of IMAGE_PROVIDER_PRIORITY) {
+        if (IMAGE_PROVIDERS[id].available())
+            return id;
+    }
+    return 'pollinations';
+}
+// ─── Small helpers ──────────────────────────────────────────────────────────
+function mimeToExt(mime) {
+    return (mime ?? '').includes('jpeg') || (mime ?? '').includes('jpg') ? '.jpg' : '.png';
+}
+/** Pick a size string OpenAI accepts for the given model. */
+function pickOpenAiSize(model, width, height) {
+    const gpt = /gpt-image/i.test(model);
+    if (width === height)
+        return '1024x1024';
+    if (gpt)
+        return width > height ? '1536x1024' : '1024x1536';
+    return width > height ? '1792x1024' : '1024x1792';
+}
+/** Stability wants an aspect ratio, not pixel dimensions. */
+function aspectRatio(width, height) {
+    if (width === height)
+        return '1:1';
+    return width > height ? '16:9' : '9:16';
+}
+//# sourceMappingURL=image-providers.js.map

package/dist/tools/modality/image-providers.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"image-providers.js","sourceRoot":"","sources":["../../../src/tools/modality/image-providers.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;GAiBG;AAEH,OAAO,EAAE,OAAO,EAAE,MAAM,oBAAoB,CAAC;AAyC7C,+EAA+E;AAE/E,qEAAqE;AACrE,SAAS,UAAU,CAAC,KAAe;IACjC,KAAK,MAAM,IAAI,IAAI,KAAK,EAAE,CAAC;QACzB,MAAM,KAAK,GAAG,CAAC,OAAO,CAAC,IAAI,CAAC,IAAI,OAAO,CAAC,GAAG,CAAC,IAAI,CAAC,CAAC,EAAE,IAAI,EAAE,CAAC;QAC3D,IAAI,KAAK;YAAE,OAAO,KAAK,CAAC;IAC1B,CAAC;IACD,OAAO,SAAS,CAAC;AACnB,CAAC;AAED,oEAAoE;AACpE,MAAM,UAAU,kBAAkB;IAChC,OAAO,OAAO,CAAC,eAAe,CAAC,IAAI,OAAO,CAAC,GAAG,CAAC,aAAa,CAAC;AAC/D,CAAC;AAED,+EAA+E;AAE/E,MAAM,iBAAiB,GAAG,uCAAuC,CAAC;AAElE,MAAM,WAAW,GAAG,yDAAyD,CAAC;AAE9E,wDAAwD;AACxD,KAAK,UAAU,cAAc,CAAC,GAA2B;IACvD,MAAM,GAAG,GAAG,UAAU,CAAC,CAAC,gBAAgB,EAAE,gBAAgB,CAAC,CAAC,CAAC;IAC7D,IAAI,CAAC,GAAG;QAAE,MAAM,IAAI,KAAK,CAAC,kCAAkC,CAAC,CAAC;IAC9D,MAAM,KAAK,GAAG,GAAG,CAAC,KAAK,IAAI,wBAAwB,CAAC;IAEpD,IAAI,SAAS,CAAC,IAAI,CAAC,KAAK,CAAC,EAAE,CAAC;QAC1B,2CAA2C;QAC3C,MAAM,GAAG,GAAG,MAAM,KAAK,CAAC,GAAG,WAAW,IAAI,KAAK,gBAAgB,kBAAkB,CAAC,GAAG,CAAC,EAAE,EAAE;YACxF,MAAM,EAAE,MAAM;YACd,OAAO,EAAE,EAAE,cAAc,EAAE,kBAAkB,EAAE;YAC/C,IAAI,EAAE,IAAI,CAAC,SAAS,CAAC,EAAE,SAAS,EAAE,CAAC,EAAE,MAAM,EAAE,GAAG,CAAC,MAAM,EAAE,CAAC,EAAE,UAAU,EAAE,EAAE,WAAW,EAAE,CAAC,EAAE,EAAE,CAAC;SAC9F,CAAC,CAAC;QACH,IAAI,CAAC,GAAG,CAAC,EAAE;YAAE,MAAM,IAAI,KAAK,CAAC,sBAAsB,GAAG,CAAC,MAAM,EAAE,CAAC,CAAC;QACjE,MAAM,IAAI,GAAG,CAAC,MAAM,GAAG,CAAC,IAAI,EAAE,CAAgF,CAAC;QAC/G,MAAM,IAAI,GAAG,IAAI,CAAC,WAAW,EAAE,CAAC,CAAC,CAAC,CAAC;QACnC,IAAI,CAAC,IAAI,EAAE,kBAAkB;YAAE,MAAM,IAAI,KAAK,CAAC,iCAAiC,CAAC,CAAC;QAClF,OAAO,EAAE,KAAK,EAAE,MAAM,CAAC,IAAI,CAAC,IAAI,CAAC,kBAAkB,EAAE,QAAQ,CAAC,EAAE,GAAG,EAAE,SAAS,CAAC,IAAI,CAAC,QAAQ,CAAC,EAAE,CAAC;IAClG,CAAC;IAED,yEAAyE;IACzE,MAAM,GAAG,GAAG,MAAM,KAAK,CAAC,GAAG,WAAW,IAAI,KAAK,wBAAwB,kBAAkB,CAAC,GAAG,CAAC,EAAE,EAAE;QAChG,MAAM,EAAE,MAAM;QACd,OAAO,EAAE,EAAE,cAAc,EAAE,kBAAkB,EAAE;QAC/C,IAAI,EAAE,IAAI,CAAC,SAAS,CAAC;YACnB,QAAQ,EAAE,CAAC,EAAE,KAAK,EAAE,CAAC,EAAE,IAAI,EAAE,GAAG,CAAC,MAAM,EAAE,CAAC,EAAE,CAAC;YAC7C,gBAAgB,EAAE,EAAE,kBAAkB,EAAE,CAAC,OAAO,CAAC,EAAE;SACpD,CAAC;KACH,CAAC,CAAC;IACH,IAAI,CAAC,GAAG,CAAC,EAAE;QAAE,MAAM,IAAI,KAAK,CAAC,qBAAqB,GAAG,CAAC,MAAM,EAAE,CAAC,CAAC;IAChE,MAAM,IAAI,GAAG,CAAC,MAAM,GAAG,CAAC,IAAI,EAAE,CAI7B,CAAC;IACF,MAAM,KAAK,GAAG,IAAI,CAAC,UAAU,EAAE,CAAC,CAAC,CAAC,EAAE,OAAO,EAAE,KAAK,IAAI,EAAE,CAAC;IACzD,MAAM,SAAS,GAAG,KAAK,CAAC,IAAI,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,UAAU,EAAE,IAAI,IAAI,CAAC,CAAC,WAAW,EAAE,IAAI,CAAC,CAAC;IAC/E,MAAM,GAAG,GAAG,SAAS,EAAE,UAAU,EAAE,IAAI,IAAI,SAAS,EAAE,WAAW,EAAE,IAAI,CAAC;IACxE,IAAI,CAAC,GAAG;QAAE,MAAM,IAAI,KAAK,CAAC,0BAA0B,CAAC,CAAC;IACtD,MAAM,IAAI,GAAG,SAAS,EAAE,UAAU,EAAE,QAAQ,IAAI,SAAS,EAAE,WAAW,EAAE,SAAS,CAAC;IAClF,OAAO,EAAE,KAAK,EAAE,MAAM,CAAC,IAAI,CAAC,GAAG,EAAE,QAAQ,CAAC,EAAE,GAAG,EAAE,SAAS,CAAC,IAAI,CAAC,EAAE,CAAC;AACrE,CAAC;AAED,yDAAyD;AACzD,KAAK,UAAU,cAAc,CAAC,GAA2B;IACvD,MAAM,GAAG,GAAG,UAAU,CAAC,CAAC,gBAAgB,CAAC,CAAC,CAAC;IAC3C,IAAI,CAAC,GAAG;QAAE,MAAM,IAAI,KAAK,CAAC,kCAAkC,CAAC,CAAC;IAC9D,MAAM,KAAK,GAAG,GAAG,CAAC,KAAK,IAAI,aAAa,CAAC;IACzC,MAAM,IAAI,GAA4B,EAAE,KAAK,EAAE,MAAM,EAAE,GAAG,CAAC,MAAM,EAAE,CAAC,EAAE,CAAC,EAAE,CAAC;IAC1E,iFAAiF;IACjF,IAAI,CAAC,YAAY,CAAC,IAAI,CAAC,KAAK,CAAC;QAAE,IAAI,CAAC,eAAe,GAAG,UAAU,CAAC;IACjE,MAAM,IAAI,GAAG,cAAc,CAAC,KAAK,EAAE,GAAG,CAAC,KAAK,EAAE,GAAG,CAAC,MAAM,CAAC,CAAC;IAC1D,IAAI,IAAI;QAAE,IAAI,CAAC,IAAI,GAAG,IAAI,CAAC;IAE3B,MAAM,GAAG,GAAG,MAAM,KAAK,CAAC,8CAA8C,EAAE;QACtE,MAAM,EAAE,MAAM;QACd,OAAO,EAAE,EAAE,aAAa,EAAE,UAAU,GAAG,EAAE,EAAE,cAAc,EAAE,kBAAkB,EAAE;QAC/E,IAAI,EAAE,IAAI,CAAC,SAAS,CAAC,IAAI,CAAC;KAC3B,CAAC,CAAC;IACH,IAAI,CAAC,GAAG,CAAC,EAAE;QAAE,MAAM,IAAI,KAAK,CAAC,qBAAqB,GAAG,CAAC,MAAM,EAAE,CAAC,CAAC;IAChE,MAAM,IAAI,GAAG,CAAC,MAAM,GAAG,CAAC,IAAI,EAAE,CAA0D,CAAC;IACzF,MAAM,KAAK,GAAG,IAAI,CAAC,IAAI,EAAE,CAAC,CAAC,CAAC,CAAC;IAC7B,IAAI,KAAK,EAAE,QAAQ;QAAE,OAAO,EAAE,KAAK,EAAE,MAAM,CAAC,IAAI,CAAC,KAAK,CAAC,QAAQ,EAAE,QAAQ,CAAC,EAAE,GAAG,EAAE,MAAM,EAAE,CAAC;IAC1F,IAAI,KAAK,EAAE,GAAG,EAAE,CAAC;QACf,MAAM,GAAG,GAAG,MAAM,KAAK,CAAC,KAAK,CAAC,GAAG,CAAC,CAAC;QACnC,IAAI,CAAC,GAAG,CAAC,EAAE;YAAE,MAAM,IAAI,KAAK,CAAC,8BAA8B,GAAG,CAAC,MAAM,EAAE,CAAC,CAAC;QACzE,OAAO,EAAE,KAAK,EAAE,MAAM,CAAC,IAAI,CAAC,MAAM,GAAG,CAAC,WAAW,EAAE,CAAC,EAAE,GAAG,EAAE,MAAM,EAAE,CAAC;IACtE,CAAC;IACD,MAAM,IAAI,KAAK,CAAC,0BAA0B,CAAC,CAAC;AAC9C,CAAC;AAED,8CAA8C;AAC9C,KAAK,UAAU,iBAAiB,CAAC,GAA2B;IAC1D,MAAM,GAAG,GAAG,UAAU,CAAC,CAAC,mBAAmB,CAAC,CAAC,CAAC;IAC9C,IAAI,CAAC,GAAG;QAAE,MAAM,IAAI,KAAK,CAAC,qCAAqC,CAAC,CAAC;IACjE,MAAM,IAAI,GAAG,IAAI,QAAQ,EAAE,CAAC;IAC5B,IAAI,CAAC,MAAM,CAAC,QAAQ,EAAE,GAAG,CAAC,MAAM,CAAC,CAAC;IAClC,IAAI,CAAC,MAAM,CAAC,eAAe,EAAE,KAAK,CAAC,CAAC;IACpC,IAAI,CAAC,MAAM,CAAC,cAAc,EAAE,WAAW,CAAC,GAAG,CAAC,KAAK,EAAE,GAAG,CAAC,MAAM,CAAC,CAAC,CAAC;IAChE,IAAI,GAAG,CAAC,KAAK;QAAE,IAAI,CAAC,MAAM,CAAC,OAAO,EAAE,GAAG,CAAC,KAAK,CAAC,CAAC;IAE/C,MAAM,GAAG,GAAG,MAAM,KAAK,CAAC,4DAA4D,EAAE;QACpF,MAAM,EAAE,MAAM;QACd,OAAO,EAAE,EAAE,aAAa,EAAE,UAAU,GAAG,EAAE,EAAE,MAAM,EAAE,SAAS,EAAE;QAC9D,IAAI,EAAE,IAAI;KACX,CAAC,CAAC;IACH,IAAI,CAAC,GAAG,CAAC,EAAE;QAAE,MAAM,IAAI,KAAK,CAAC,kBAAkB,GAAG,CAAC,MAAM,EAAE,CAAC,CAAC;IAC7D,MAAM,WAAW,GAAG,GAAG,CAAC,OAAO,CAAC,GAAG,CAAC,cAAc,CAAC,IAAI,EAAE,CAAC;IAC1D,IAAI,CAAC,WAAW,CAAC,UAAU,CAAC,QAAQ,CAAC;QAAE,MAAM,IAAI,KAAK,CAAC,sBAAsB,WAAW,IAAI,sBAAsB,EAAE,CAAC,CAAC;IACtH,MAAM,KAAK,GAAG,MAAM,CAAC,IAAI,CAAC,MAAM,GAAG,CAAC,WAAW,EAAE,CAAC,CAAC;IACnD,IAAI,KAAK,CAAC,MAAM,KAAK,CAAC;QAAE,MAAM,IAAI,KAAK,CAAC,mCAAmC,CAAC,CAAC;IAC7E,OAAO,EAAE,KAAK,EAAE,GAAG,EAAE,WAAW,CAAC,QAAQ,CAAC,MAAM,CAAC,CAAC,CAAC,CAAC,MAAM,CAAC,CAAC,CAAC,MAAM,EAAE,CAAC;AACxE,CAAC;AAED,6EAA6E;AAC7E,KAAK,UAAU,eAAe,CAAC,GAA2B;IACxD,MAAM,GAAG,GAAG,GAAG,CAAC,QAAQ,IAAI,kBAAkB,EAAE,CAAC;IACjD,IAAI,CAAC,GAAG;QAAE,MAAM,IAAI,KAAK,CAAC,6DAA6D,CAAC,CAAC;IACzF,MAAM,GAAG,GAAG,MAAM,KAAK,CAAC,GAAG,EAAE;QAC3B,MAAM,EAAE,MAAM;QACd,OAAO,EAAE,EAAE,cAAc,EAAE,kBAAkB,EAAE;QAC/C,IAAI,EAAE,IAAI,CAAC,SAAS,CAAC,EAAE,MAAM,EAAE,GAAG,CAAC,MAAM,EAAE,KAAK,EAAE,GAAG,CAAC,KAAK,EAAE,MAAM,EAAE,GAAG,CAAC,MAAM,EAAE,CAAC;KACnF,CAAC,CAAC;IACH,IAAI,CAAC,GAAG,CAAC,EAAE;QAAE,MAAM,IAAI,KAAK,CAAC,sBAAsB,GAAG,CAAC,MAAM,EAAE,CAAC,CAAC;IACjE,MAAM,WAAW,GAAG,GAAG,CAAC,OAAO,CAAC,GAAG,CAAC,cAAc,CAAC,IAAI,EAAE,CAAC;IAC1D,MAAM,KAAK,GAAG,MAAM,CAAC,IAAI,CAAC,MAAM,GAAG,CAAC,WAAW,EAAE,CAAC,CAAC;IACnD,IAAI,KAAK,CAAC,MAAM,KAAK,CAAC;QAAE,MAAM,IAAI,KAAK,CAAC,uCAAuC,CAAC,CAAC;IACjF,OAAO,EAAE,KAAK,EAAE,GAAG,EAAE,WAAW,CAAC,QAAQ,CAAC,MAAM,CAAC,CAAC,CAAC,CAAC,MAAM,CAAC,CAAC,CAAC,MAAM,EAAE,CAAC;AACxE,CAAC;AAED,wEAAwE;AACxE,KAAK,UAAU,oBAAoB,CAAC,GAA2B;IAC7D,MAAM,GAAG,GAAG,GAAG,iBAAiB,GAAG,kBAAkB,CAAC,GAAG,CAAC,MAAM,CAAC,UAAU,GAAG,CAAC,KAAK,WAAW,GAAG,CAAC,MAAM,cAAc,CAAC;IACxH,MAAM,GAAG,GAAG,MAAM,KAAK,CAAC,GAAG,CAAC,CAAC;IAC7B,IAAI,CAAC,GAAG,CAAC,EAAE;QAAE,MAAM,IAAI,KAAK,CAAC,4BAA4B,GAAG,CAAC,MAAM,EAAE,CAAC,CAAC;IACvE,MAAM,KAAK,GAAG,MAAM,CAAC,IAAI,CAAC,MAAM,GAAG,CAAC,WAAW,EAAE,CAAC,CAAC;IACnD,IAAI,KAAK,CAAC,MAAM,KAAK,CAAC;QAAE,MAAM,IAAI,KAAK,CAAC,iCAAiC,CAAC,CAAC;IAC3E,OAAO,EAAE,KAAK,EAAE,GAAG,EAAE,MAAM,EAAE,CAAC;AAChC,CAAC;AAED,+EAA+E;AAE/E,2EAA2E;AAC3E,MAAM,CAAC,MAAM,eAAe,GAA2C;IACrE,MAAM,EAAE;QACN,EAAE,EAAE,QAAQ;QACZ,KAAK,EAAE,sCAAsC;QAC7C,UAAU,EAAE,CAAC,gBAAgB,EAAE,gBAAgB,CAAC;QAChD,YAAY,EAAE,wBAAwB;QACtC,WAAW,EAAE,KAAK;QAClB,OAAO,EAAE,GAAG;QACZ,cAAc,EAAE,IAAI;QACpB,SAAS,EAAE,GAAG,EAAE,CAAC,OAAO,CAAC,UAAU,CAAC,CAAC,gBAAgB,EAAE,gBAAgB,CAAC,CAAC,CAAC;QAC1E,QAAQ,EAAE,cAAc;KACzB;IACD,MAAM,EAAE;QACN,EAAE,EAAE,QAAQ;QACZ,KAAK,EAAE,6BAA6B;QACpC,UAAU,EAAE,CAAC,gBAAgB,CAAC;QAC9B,YAAY,EAAE,aAAa;QAC3B,WAAW,EAAE,IAAI;QACjB,OAAO,EAAE,IAAI;QACb,cAAc,EAAE,IAAI;QACpB,SAAS,EAAE,GAAG,EAAE,CAAC,OAAO,CAAC,UAAU,CAAC,CAAC,gBAAgB,CAAC,CAAC,CAAC;QACxD,QAAQ,EAAE,cAAc;KACzB;IACD,SAAS,EAAE;QACT,EAAE,EAAE,WAAW;QACf,KAAK,EAAE,cAAc;QACrB,UAAU,EAAE,CAAC,mBAAmB,CAAC;QACjC,YAAY,EAAE,mBAAmB;QACjC,WAAW,EAAE,KAAK;QAClB,OAAO,EAAE,IAAI;QACb,cAAc,EAAE,IAAI;QACpB,SAAS,EAAE,GAAG,EAAE,CAAC,OAAO,CAAC,UAAU,CAAC,CAAC,mBAAmB,CAAC,CAAC,CAAC;QAC3D,QAAQ,EAAE,iBAAiB;KAC5B;IACD,OAAO,EAAE;QACP,EAAE,EAAE,SAAS;QACb,KAAK,EAAE,kCAAkC;QACzC,UAAU,EAAE,EAAE;QACd,YAAY,EAAE,OAAO;QACrB,WAAW,EAAE,CAAC;QACd,OAAO,EAAE,GAAG;QACZ,cAAc,EAAE,IAAI;QACpB,SAAS,EAAE,GAAG,EAAE,CAAC,OAAO,CAAC,kBAAkB,EAAE,CAAC;QAC9C,QAAQ,EAAE,eAAe;KAC1B;IACD,YAAY,EAAE;QACZ,EAAE,EAAE,cAAc;QAClB,KAAK,EAAE,wBAAwB;QAC/B,UAAU,EAAE,EAAE;QACd,YAAY,EAAE,cAAc;QAC5B,WAAW,EAAE,CAAC;QACd,OAAO,EAAE,GAAG;QACZ,cAAc,EAAE,KAAK;QACrB,SAAS,EAAE,GAAG,EAAE,CAAC,IAAI;QACrB,QAAQ,EAAE,oBAAoB;KAC/B;CACF,CAAC;AAEF;;;;GAIG;AACH,MAAM,CAAC,MAAM,uBAAuB,GAA+B;IACjE,QAAQ;IACR,QAAQ;IACR,WAAW;IACX,SAAS;IACT,cAAc;CACf,CAAC;AAEF,+EAA+E;AAE/E,2CAA2C;AAC3C,MAAM,UAAU,iBAAiB,CAAC,KAAyB;IACzD,OAAO,OAAO,CAAC,KAAK,IAAI,MAAM,CAAC,SAAS,CAAC,cAAc,CAAC,IAAI,CAAC,eAAe,EAAE,KAAK,CAAC,CAAC,CAAC;AACxF,CAAC;AAED,qEAAqE;AACrE,MAAM,UAAU,uBAAuB;IACrC,OAAO,uBAAuB,CAAC,MAAM,CAAC,CAAC,EAAE,EAAE,EAAE,CAAC,eAAe,CAAC,EAAE,CAAC,CAAC,SAAS,EAAE,CAAC,CAAC;AACjF,CAAC;AAED;;;GAGG;AACH,MAAM,UAAU,oBAAoB,CAAC,SAAkB;IACrD,IAAI,iBAAiB,CAAC,SAAS,CAAC;QAAE,OAAO,SAAS,CAAC;IACnD,KAAK,MAAM,EAAE,IAAI,uBAAuB,EAAE,CAAC;QACzC,IAAI,eAAe,CAAC,EAAE,CAAC,CAAC,SAAS,EAAE;YAAE,OAAO,EAAE,CAAC;IACjD,CAAC;IACD,OAAO,cAAc,CAAC;AACxB,CAAC;AAED,+EAA+E;AAE/E,SAAS,SAAS,CAAC,IAAwB;IACzC,OAAO,CAAC,IAAI,IAAI,EAAE,CAAC,CAAC,QAAQ,CAAC,MAAM,CAAC,IAAI,CAAC,IAAI,IAAI,EAAE,CAAC,CAAC,QAAQ,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC,MAAM,CAAC,CAAC,CAAC,MAAM,CAAC;AACzF,CAAC;AAED,6DAA6D;AAC7D,SAAS,cAAc,CAAC,KAAa,EAAE,KAAa,EAAE,MAAc;IAClE,MAAM,GAAG,GAAG,YAAY,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC;IACrC,IAAI,KAAK,KAAK,MAAM;QAAE,OAAO,WAAW,CAAC;IACzC,IAAI,GAAG;QAAE,OAAO,KAAK,GAAG,MAAM,CAAC,CAAC,CAAC,WAAW,CAAC,CAAC,CAAC,WAAW,CAAC;IAC3D,OAAO,KAAK,GAAG,MAAM,CAAC,CAAC,CAAC,WAAW,CAAC,CAAC,CAAC,WAAW,CAAC;AACpD,CAAC;AAED,6DAA6D;AAC7D,SAAS,WAAW,CAAC,KAAa,EAAE,MAAc;IAChD,IAAI,KAAK,KAAK,MAAM;QAAE,OAAO,KAAK,CAAC;IACnC,OAAO,KAAK,GAAG,MAAM,CAAC,CAAC,CAAC,MAAM,CAAC,CAAC,CAAC,MAAM,CAAC;AAC1C,CAAC"}

package/dist/tools/registry.d.ts

@@ -215,6 +215,15 @@ export interface ToolContext {
      * (tests, non-tiered callers) simply never extend the schema set.
      */
     loadedExtraTools?: Set<string>;
+    /**
+     * The actions this turn actually PERFORMED, as the loop observed them
+     * (successes and failures alike), appended per tool call. Gives a tool that
+     * reports a claim the reality its own prose cannot be: `finding` uses it to
+     * refuse a CONFIRMED verdict built on a command or path that never happened
+     * (see `enforceEvidenceProvenance` in `src/findings/verdicts.ts`). Optional —
+     * a direct call or a bare test context simply skips the provenance check.
+     */
+    executedActions?: import('../findings/verdicts.js').ExecutedAction[];
 }
 /** A clarify-style choice. */
 export interface AskUserChoice {
@@ -384,5 +393,5 @@ export declare const TOOL_CONTRACT_JSON = "You have tools available. Call them w
  * unparseable or schema-invalid (callers fall back to rule-based suggestions).
  */
 export declare function toFollowupSuggestions(raw: string): FollowupSuggestion[];
-export { MAX_FOLLOWUPS, MAX_FOLLOWUP_PROMPT_CHARS, MAX_FOLLOWUP_LABEL_CHARS, normalizeFollowups, FOLLOWUP_CONTINUATION_MARKER, buildFollowupContinuationPrompt, isFollowupContinuation, isSuggestedFollowup, } from './followup-utils.js';
+export { MAX_FOLLOWUPS, MAX_FOLLOWUP_PROMPT_CHARS, MAX_FOLLOWUP_LABEL_CHARS, normalizeFollowups, FOLLOWUP_CONTINUATION_MARKER, buildFollowupContinuationPrompt, isFollowupContinuation, isSuggestedFollowup, withContinuationFollowups, CONTINUE_PROMPT, RETRY_PROMPT, } from './followup-utils.js';
 //# sourceMappingURL=registry.d.ts.map

package/dist/tools/registry.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"registry.d.ts","sourceRoot":"","sources":["../../src/tools/registry.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"registry.d.ts","sourceRoot":"","sources":["../../src/tools/registry.ts"],"names":[],"mappings":"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"}

package/dist/tools/registry.js

@@ -28,6 +28,7 @@ import { z, toJSONSchema } from 'zod';
 import { ACTION_BY_INTENT } from '../nlu/actions.js';
 import { detectPermissionSeeking, IRREVERSIBLE_ACTION_RE } from '../learning/autonomy-policy.js';
 import { createFindingTool } from './finding-tool.js';
+import { recordArtifact } from './artifact-append.js';
 // ─── Tool definitions ───────────────────────────────────────────────────────
 // ─── Shared auto-delivery helper ─────────────────────────────────────────
 // Tools that produce artifact files (generate_image, speak, video_generate)
@@ -221,11 +222,15 @@ const browserSchema = z.object({
     text: z.string().optional().describe('Text to type (action=type)'),
     timeout_ms: z.number().int().min(500).max(120000).default(15000).optional().describe('Navigation/timeout in ms'),
 });
-/** I3 — generate_image tool args: free image generation. */
+/** I3 — generate_image tool args: bring-your-own-key image generation. */
 const imageGenSchema = z.object({
     prompt: z.string().min(1).describe('The image description'),
     width: z.number().int().min(64).max(2048).default(1024).optional().describe('Image width (default 1024)'),
     height: z.number().int().min(64).max(2048).default(1024).optional().describe('Image height (default 1024)'),
+    provider: z
+        .enum(['gemini', 'openai', 'stability', 'comfyui', 'pollinations'])
+        .optional()
+        .describe('Optional backend override: gemini (Imagen/Nano Banana), openai (DALL-E/gpt-image), stability, comfyui (local), or pollinations (free). Defaults to the first backend whose API key is configured.'),
 });
 /** I4 — voice tools: TTS + transcription (optional installs). */
 const speakSchema = z.object({
@@ -475,7 +480,7 @@ registerTool({
 });
 registerTool({
     name: 'ask_user',
-    description: 'Ask the user a clarifying question with 2–4 choices (multi-select optional). Use when a request is ambiguous or missing information.',
+    description: 'Ask the user a clarifying question with 2–4 choices (multi-select optional). Every surface also offers the user a free-text "Other" answer, so a reply may be their own words instead of one of your choices. Use when a request is ambiguous or missing information.',
     category: 'experience',
     inputSchema: askUserSchema,
     // NOT a dispenser: the tool result is the user's ANSWER, which the model
@@ -711,16 +716,19 @@ registerTool(createFindingTool());
 // `src/tools/web-research.ts` (mocked-fetch tests, no network).
 registerTool({
     name: 'web_search',
-    description: 'Search the web for a query, returning title/url/snippet hits (DuckDuckGo free tier or a configured SearXNG). Use to ground answers in current information.',
+    description: 'Search the web for a query, returning title/url/snippet hits. Uses the first available backend: a configured Brave/Serper/Tavily/Google-CSE key, a self-hosted SearXNG, or the keyless DuckDuckGo fallback. Set the backend with `tools.toolsets.web.provider` or an API-key env var. Use to ground answers in current information.',
     category: 'workflow',
     inputSchema: webSearchSchema,
     endsAgentStep: false,
-    run: async (args) => {
+    run: async (args, ctx) => {
         const { query, max_results } = webSearchSchema.parse(args);
         const { searchWeb } = await import('./web-research.js');
-        // Self-hosted SearXNG opt-in via env (free/OSS); unset → DuckDuckGo.
+        // Backend selection: an explicit `tools.toolsets.web.provider` wins, else
+        // the first backend with a configured key (Brave/Serper/Tavily/Google CSE),
+        // else SearXNG, else the keyless DuckDuckGo default.
         const searxngUrl = envBuff('SEARXNG_URL');
-        const results = await searchWeb(query, { maxResults: max_results, searxngUrl });
+        const provider = ctx?.configManager?.getAll?.()?.tools?.toolsets?.web?.provider;
+        const results = await searchWeb(query, { maxResults: max_results, searxngUrl, provider });
         if (results.length === 0) {
             return `web_search: no results for "${query}" (backend unavailable or network error).`;
         }
@@ -764,7 +772,7 @@ registerTool({
 });
 registerTool({
     name: 'generate_image',
-    description: 'Generate an image from a text prompt (Pollinations.ai free endpoint, or a local Stable Diffusion/ComfyUI via BUFF_IMAGE_API_URL). The image is saved to the sandbox images/ dir and the path is returned. When running in a gateway context (WhatsApp/Telegram/etc.), the image is automatically sent back to the originating channel.',
+    description: 'Generate an image from a text prompt using a bring-your-own-key backend: Google Gemini/Imagen (GEMINI_API_KEY), OpenAI DALL-E/gpt-image (OPENAI_API_KEY), Stability AI (STABILITY_API_KEY), a local ComfyUI/Stable Diffusion (BUFF_IMAGE_API_URL), or the free keyless Pollinations.ai fallback. The first backend whose key is configured wins (override with `modality.image.provider`), and a failing backend falls back to Pollinations. The image is saved to the sandbox images/ dir and the path is returned. When running in a gateway context (WhatsApp/Telegram/etc.), the image is automatically sent back to the originating channel.',
     category: 'workflow',
     inputSchema: imageGenSchema,
     endsAgentStep: false,
@@ -773,14 +781,27 @@ registerTool({
         const { generateImage, isImageGenAvailable } = await import('./modality/image-gen.js');
         if (!isImageGenAvailable())
             return 'generate_image: unavailable (no image backend configured).';
+        // Config (`modality.image.*`) supplies the default backend/model; an
+        // explicit tool arg overrides it.
+        const modality = ctx?.configManager?.getAll?.()?.modality?.image ?? {};
         const result = await generateImage(parsed.prompt, {
             width: parsed.width,
             height: parsed.height,
             apiUrl: envBuff('IMAGE_API_URL'),
+            provider: parsed.provider ?? modality.provider,
+            model: modality.model,
         });
         if (!result.ok)
             return `generate_image: failed — ${result.error}`;
         const file = result.file;
+        // I3 — the generated image is a deliverable: register it so the dashboard's
+        // Artifacts tab can show (and re-open) what this turn produced.
+        recordArtifact(ctx?.artifacts, {
+            kind: 'media',
+            title: `image: ${parsed.prompt.slice(0, 60)}`,
+            path: file,
+            mime: 'image/png',
+        });
         const delivered = await tryAutoDeliver(file, parsed.prompt, ctx, 'image');
         return `generate_image: saved to ${file}${delivered}`;
     },
@@ -798,6 +819,12 @@ registerTool({
         if (!result.ok)
             return `speak: failed — ${result.error}`;
         const file = result.file;
+        recordArtifact(ctx?.artifacts, {
+            kind: 'media',
+            title: `speech: ${parsed.text.slice(0, 60)}`,
+            path: file,
+            mime: 'audio/mpeg',
+        });
         const delivered = await tryAutoDeliver(file, parsed.text, ctx, 'audio');
         return `speak: saved to ${file}${delivered}`;
     },
@@ -976,7 +1003,7 @@ export function toFollowupSuggestions(raw) {
 // and dashboard must be able to normalise a followup (and recognise a clicked
 // one) WITHOUT pulling the whole 110-tool registry into their import graph —
 // doing so measurably slowed those hot paths.
-export { MAX_FOLLOWUPS, MAX_FOLLOWUP_PROMPT_CHARS, MAX_FOLLOWUP_LABEL_CHARS, normalizeFollowups, FOLLOWUP_CONTINUATION_MARKER, buildFollowupContinuationPrompt, isFollowupContinuation, isSuggestedFollowup, } from './followup-utils.js';
+export { MAX_FOLLOWUPS, MAX_FOLLOWUP_PROMPT_CHARS, MAX_FOLLOWUP_LABEL_CHARS, normalizeFollowups, FOLLOWUP_CONTINUATION_MARKER, buildFollowupContinuationPrompt, isFollowupContinuation, isSuggestedFollowup, withContinuationFollowups, CONTINUE_PROMPT, RETRY_PROMPT, } from './followup-utils.js';
 // ─── Tool run implementations (deferred imports to avoid cycles) ────────────
 /** Run a C3 pipeline action (build/resume/repair + E3c task tools) — see executor.ts. */
 function runPipelineTool(action, args, ctx) {