opencode-pollinations-plugin 6.4.9 → 6.5.0

package/dist/server/quota.d.ts

@@ -1,48 +1,39 @@
 import { DetailedUsageEntry } from './pollinations-api.js';
-interface ResetInfo {
-    nextReset: Date;
-    lastReset: Date;
-    timeUntilReset: number;
-    timeSinceReset: number;
-    resetHour: number;
-    resetMinute: number;
-    resetSecond: number;
-    progressPercent: number;
-}
+/**
+ * v6.5 — Quest/Paid semantics.
+ * The old tier/refill model (KNOWN_REFILLS, hourly allowance deduction,
+ * tierMetaForAllowance) has been removed: upstream deleted the hourly refill
+ * (cron disabled 2026-06, code removed 2026-07). The client cannot read a
+ * reliable Quest/Paid split from /account/balance in prod, so `questBalance`
+ * is a BEST-EFFORT estimate (claimed quest pollen minus tier-metered usage
+ * since claim). `walletBalance` is Paid pollen when exposed (pack), otherwise
+ * estimated as total minus quest. meter_source in /account/usage remains the
+ * only authoritative retrospective split.
+ */
 export interface QuotaStatus {
-    tierRemaining: number;
-    tierUsed: number;
-    tierLimit: number;
-    questStash: number;
+    questBalance: number;
     walletBalance: number;
-    nextResetAt: Date;
-    timeUntilReset: number;
+    totalBalance: number;
     canUseEnterprise: boolean;
     isUsingWallet: boolean;
     needsAlert: boolean;
-    tier: string;
-    tierEmoji: string;
     errorType?: 'auth_limited' | 'network' | 'unknown';
 }
 export declare function fetchUsageForPeriod(apiKey: string, lastReset: Date): Promise<DetailedUsageEntry[]>;
-/** Map hourly refill amount → display meta (exported for unit tests). */
-export declare function tierMetaForAllowance(allowance: number): {
-    label: string;
-    emoji: string;
-};
-/** Known hourly refill ladder (read-only, for tests / UI). */
-export declare function getKnownRefills(): ReadonlyArray<{
-    pollen: number;
-    emoji: string;
-    label: string;
-}>;
 export declare function getQuotaStatus(forceRefresh?: boolean): Promise<QuotaStatus>;
-/** Next top-of-hour UTC reset window (exported for unit tests). */
-export declare function calculateResetInfo(): ResetInfo;
+/** Next top-of-hour UTC reset window (used for usage period windows only). */
+export declare function calculateResetInfo(): {
+    nextReset: Date;
+    lastReset: Date;
+};
 export declare function formatQuotaForToast(quota: QuotaStatus): string;
+/**
+ * Best-effort Quest balance: claimed quest pollen (tier bucket) minus
+ * tier-metered consumption since the earliest claim. This is NOT a server
+ * guarantee — the authoritative split is meter_source in /account/usage.
+ */
 export declare function fetchQuestStash(apiKey: string): Promise<{
     questStash: number;
     claimedQuestTier: number;
     tierConsumedSinceClaim: number;
 }>;
-export {};

package/dist/server/quota.js

@@ -4,18 +4,10 @@ import { loadConfig } from './config.js';
 const CACHE_TTL = 30000;
 let cachedQuota = null;
 let lastQuotaFetch = 0;
-const STASH_CACHE_TTL = 5 * 60 * 1000; // 5 min — le stash Quest change rarement
+const STASH_CACHE_TTL = 5 * 60 * 1000; // 5 min — Quest stash changes rarely
 let cachedStash = null;
 let lastStashFetch = 0;
 const ONE_HOUR_MS = 60 * 60 * 1000;
-const KNOWN_REFILLS = [
-    { pollen: 0, emoji: '👤', label: 'anonymous' },
-    { pollen: 0.01, emoji: '🍄', label: 'spore' },
-    { pollen: 0.15, emoji: '🌱', label: 'seed' },
-    { pollen: 0.4, emoji: '🌸', label: 'flower' },
-    { pollen: 0.8, emoji: '🍯', label: 'nectar' },
-    { pollen: 10, emoji: '🐝', label: 'router' },
-];
 // === LOGGING ===
 import { logApi } from './logger.js';
 function logQuota(msg) {
@@ -65,96 +57,11 @@ export async function fetchUsageForPeriod(apiKey, lastReset) {
     logQuota(`SmartFetch: Retrieved ${allUsage.length} transactions for current period.`);
     return allUsage;
 }
-// === ALLOWANCE DEDUCTION ===
-async function fetchUsageForAllowance(apiKey) {
-    const sevenDaysAgo = new Date(Date.now() - 7 * 24 * ONE_HOUR_MS);
-    const allUsage = [];
-    let cursorEventId = null;
-    let pageCount = 0;
-    const maxPages = 20;
-    while (pageCount < maxPages) {
-        let path = `/account/usage?days=7&limit=500`;
-        if (cursorEventId) {
-            path += `&before_event_id=${encodeURIComponent(cursorEventId)}`;
-        }
-        const res = await fetchAPI(path, apiKey);
-        if (!res.usage || res.usage.length === 0)
-            break;
-        let reachedCutoff = false;
-        for (const entry of res.usage) {
-            const ts = (entry.timestamp.includes('Z') ? entry.timestamp : entry.timestamp.replace(' ', 'T') + 'Z');
-            if (new Date(ts) < sevenDaysAgo) {
-                reachedCutoff = true;
-                break;
-            }
-            allUsage.push(entry);
-        }
-        if (reachedCutoff || res.usage.length < 500)
-            break;
-        const last = res.usage[res.usage.length - 1];
-        cursorEventId = last?.cursor_event_id || null;
-        if (!cursorEventId)
-            break;
-        pageCount++;
-    }
-    logQuota(`deduceAllowance: fetched ${allUsage.length} records over ${pageCount + 1} pages`);
-    return allUsage;
-}
-async function deduceAllowanceFromApi(apiKey) {
-    try {
-        const allUsage = await fetchUsageForAllowance(apiKey);
-        if (allUsage.length === 0)
-            return 0;
-        const sevenDaysAgo = new Date(Date.now() - 7 * 24 * ONE_HOUR_MS);
-        const hourlyBuckets = new Map();
-        for (const entry of allUsage) {
-            if (entry.meter_source !== 'tier')
-                continue;
-            const ts = entry.timestamp.includes('Z') ? entry.timestamp : entry.timestamp.replace(' ', 'T') + 'Z';
-            const entryTime = new Date(ts);
-            if (entryTime < sevenDaysAgo)
-                continue;
-            const hourKey = entryTime.getUTCFullYear() * 1000000
-                + entryTime.getUTCMonth() * 10000
-                + entryTime.getUTCDate() * 100
-                + entryTime.getUTCHours();
-            hourlyBuckets.set(hourKey, (hourlyBuckets.get(hourKey) || 0) + entry.cost_usd);
-        }
-        const maxHourlyTier = Math.max(0, ...hourlyBuckets.values());
-        const match = KNOWN_REFILLS.slice().reverse().find(r => r.pollen <= maxHourlyTier + 0.02);
-        logQuota(`deduceAllowance: ${allUsage.length} records, ${hourlyBuckets.size} hourly buckets, max=${maxHourlyTier.toFixed(4)}, deduced=${match?.pollen ?? 0} (${match?.label})`);
-        return match ? match.pollen : 0;
-    }
-    catch (e) {
-        logQuota(`deduceAllowance failed: ${e}`);
-        return 0;
-    }
-}
-function deduceAllowanceFromUsage(usage) {
-    const tierCosts = usage
-        .filter(u => u.meter_source === 'tier')
-        .map(u => u.cost_usd);
-    const maxHourlyTier = Math.max(0, ...tierCosts);
-    const match = KNOWN_REFILLS.slice().reverse().find(r => r.pollen <= maxHourlyTier + 0.02);
-    return match ? match.pollen : 0;
-}
-/** Map hourly refill amount → display meta (exported for unit tests). */
-export function tierMetaForAllowance(allowance) {
-    const match = KNOWN_REFILLS.find(r => r.pollen === allowance)
-        || KNOWN_REFILLS.findLast(r => r.pollen <= allowance);
-    return match
-        ? { label: match.label, emoji: match.emoji }
-        : { label: 'unknown', emoji: '❓' };
-}
-/** Known hourly refill ladder (read-only, for tests / UI). */
-export function getKnownRefills() {
-    return KNOWN_REFILLS;
-}
 // === MAIN QUOTA FUNCTION ===
 export async function getQuotaStatus(forceRefresh = false) {
     const config = loadConfig();
     if (!config.apiKey) {
-        return createDefaultQuota('none', 0);
+        return createDefaultQuota(0);
     }
     const now = Date.now();
     if (!forceRefresh && cachedQuota && (now - lastQuotaFetch) < CACHE_TTL) {
@@ -163,19 +70,6 @@ export async function getQuotaStatus(forceRefresh = false) {
     try {
         logQuota("Fetching Quota Data...");
         const balanceRes = await fetchAPI('/account/balance', config.apiKey);
-        const resetInfo = calculateResetInfo();
-        const periodUsage = await fetchUsageForPeriod(config.apiKey, resetInfo.lastReset);
-        const allowance = balanceRes.allowance
-            ?? config.refillOverride
-            ?? await deduceAllowanceFromApi(config.apiKey);
-        const tierMeta = tierMetaForAllowance(allowance);
-        const tierLimit = allowance;
-        const { tierUsed } = calculateCurrentPeriodUsage(periodUsage, resetInfo);
-        const tierRemaining = Math.max(0, tierLimit - tierUsed);
-        const cleanTierRemaining = Math.max(0, parseFloat(tierRemaining.toFixed(4)));
-        const totalBalance = balanceRes.total
-            ?? balanceRes.balance
-            ?? 0;
         // Fetch quest stash BEFORE paidPollen calculation (cached 5 min)
         const nowStash = Date.now();
         if (!cachedStash || (nowStash - lastStashFetch) > STASH_CACHE_TTL) {
@@ -185,29 +79,33 @@ export async function getQuotaStatus(forceRefresh = false) {
             }
             catch { /* keep previous */ }
         }
-        const questStash = cachedStash?.questStash ?? 0;
+        const questEstimate = cachedStash?.questStash ?? 0;
+        const totalBalance = balanceRes.total
+            ?? balanceRes.balance
+            ?? 0;
+        // Quest balance: native allowance when available (PR #12541 not in prod),
+        // else best-effort stash estimate.
+        const questBalance = balanceRes.allowance !== undefined
+            ? Math.max(0, balanceRes.allowance)
+            : questEstimate;
+        // Paid pollen: native pack when available, else total minus quest estimate.
         const paidPollenNative = balanceRes.pack;
-        const paidPollen = paidPollenNative !== undefined
-            ? paidPollenNative
-            : Math.max(0, totalBalance - cleanTierRemaining - questStash);
-        const cleanWalletBalance = Math.max(0, parseFloat(paidPollen.toFixed(4)));
-        const tierAlertPercent = tierLimit > 0 ? (cleanTierRemaining / tierLimit * 100) : 0;
-        const tierNeedsAlert = tierLimit > 0 && tierAlertPercent <= config.thresholds.tier;
+        const walletBalance = paidPollenNative !== undefined
+            ? Math.max(0, paidPollenNative)
+            : Math.max(0, totalBalance - questBalance);
+        const cleanQuestBalance = Math.max(0, parseFloat(questBalance.toFixed(4)));
+        const cleanWalletBalance = Math.max(0, parseFloat(walletBalance.toFixed(4)));
+        // Alerts (v6.5): thresholds are absolute pollen floors, not percentages.
+        const questNeedsAlert = cleanQuestBalance > 0 && cleanQuestBalance < (config.thresholds.quest ?? 0.05);
         const walletNeedsAlert = cleanWalletBalance > 0 && cleanWalletBalance < (config.thresholds.wallet || 0.5);
-        logQuota(`Fetch Success. Allowance: ${allowance}, Stash: ${questStash}, Paid: ${cleanWalletBalance}, Total: ${totalBalance}`);
+        logQuota(`Fetch Success. Quest: ${cleanQuestBalance}, Paid: ${cleanWalletBalance}, Total: ${totalBalance}`);
         cachedQuota = {
-            tierRemaining: cleanTierRemaining,
-            tierUsed,
-            tierLimit,
-            questStash,
+            questBalance: cleanQuestBalance,
             walletBalance: cleanWalletBalance,
-            nextResetAt: resetInfo.nextReset,
-            timeUntilReset: resetInfo.timeUntilReset,
-            canUseEnterprise: cleanTierRemaining > 0.05 || cleanWalletBalance > 0.05,
-            isUsingWallet: cleanTierRemaining <= 0.05 && cleanWalletBalance > 0.05,
-            needsAlert: tierNeedsAlert || walletNeedsAlert,
-            tier: tierMeta.label,
-            tierEmoji: tierMeta.emoji
+            totalBalance,
+            canUseEnterprise: cleanQuestBalance > 0.05 || cleanWalletBalance > 0.05,
+            isUsingWallet: cleanQuestBalance <= 0.05 && cleanWalletBalance > 0.05,
+            needsAlert: questNeedsAlert || walletNeedsAlert
         };
         lastQuotaFetch = now;
         return cachedQuota;
@@ -219,24 +117,17 @@ export async function getQuotaStatus(forceRefresh = false) {
             errorType = 'auth_limited';
         else if (e.message && e.message.includes('Network Error'))
             errorType = 'network';
-        return cachedQuota || { ...createDefaultQuota('error', 1), errorType };
+        return cachedQuota || { ...createDefaultQuota(0), errorType };
     }
 }
-function createDefaultQuota(tierName, limit) {
-    const meta = tierMetaForAllowance(limit);
+function createDefaultQuota(_limit) {
     return {
-        tierRemaining: 0,
-        tierUsed: 0,
-        tierLimit: limit,
-        questStash: 0,
+        questBalance: 0,
         walletBalance: 0,
-        nextResetAt: new Date(),
-        timeUntilReset: 0,
+        totalBalance: 0,
         canUseEnterprise: false,
         isUsingWallet: false,
-        needsAlert: false,
-        tier: tierName !== 'none' ? meta.label : 'none',
-        tierEmoji: meta.emoji
+        needsAlert: false
     };
 }
 // === HELPERS ===
@@ -249,7 +140,7 @@ function fetchAPI(endpoint, apiKey) {
             method: 'GET',
             headers: {
                 'Authorization': `Bearer ${apiKey}`,
-                'User-Agent': 'opencode-pollinations-plugin/6.4.1'
+                'User-Agent': 'opencode-pollinations-plugin/6.5.0'
             }
         };
         const req = https.request(options, (res) => {
@@ -272,62 +163,31 @@ function fetchAPI(endpoint, apiKey) {
         req.on('error', (e) => {
             reject(new Error(`Network Error: ${e.message}`));
         });
+        // v6.5: bound the request (quota read was previously unbounded → hang risk).
+        req.setTimeout(10000, () => {
+            req.destroy(new Error('Timeout: quota API fetch exceeded 10s'));
+        });
         req.end();
     });
 }
-/** Next top-of-hour UTC reset window (exported for unit tests). */
+/** Next top-of-hour UTC reset window (used for usage period windows only). */
 export function calculateResetInfo() {
     const now = new Date();
     const nextReset = new Date(Date.UTC(now.getUTCFullYear(), now.getUTCMonth(), now.getUTCDate(), now.getUTCHours() + 1, 0, 0, 0));
     const lastReset = new Date(nextReset.getTime() - ONE_HOUR_MS);
-    const timeUntilReset = Math.max(0, nextReset.getTime() - now.getTime());
-    const timeSinceReset = Math.max(0, now.getTime() - lastReset.getTime());
-    const progressPercent = Math.min(100, (timeSinceReset / ONE_HOUR_MS) * 100);
-    return {
-        nextReset,
-        lastReset,
-        timeUntilReset,
-        timeSinceReset,
-        resetHour: nextReset.getUTCHours(),
-        resetMinute: 0,
-        resetSecond: 0,
-        progressPercent
-    };
-}
-function calculateCurrentPeriodUsage(usage, resetInfo) {
-    let tierUsed = 0;
-    let packUsed = 0;
-    const entriesAfterReset = usage.filter(entry => {
-        const timestamp = entry.timestamp.replace(' ', 'T') + 'Z';
-        const entryTime = new Date(timestamp);
-        return entryTime >= resetInfo.lastReset;
-    });
-    for (const entry of entriesAfterReset) {
-        if (entry.meter_source === 'tier') {
-            tierUsed += entry.cost_usd;
-        }
-        else if (entry.meter_source === 'pack') {
-            packUsed += entry.cost_usd;
-        }
-    }
-    return { tierUsed, packUsed };
+    return { nextReset, lastReset };
 }
 export function formatQuotaForToast(quota) {
     if (quota.errorType === 'auth_limited') {
-        return `🔑 CLE LIMITÉE (Génération Seule) | 💎 Wallet: N/A | ⏰ Reset: N/A`;
+        return `🔑 CLE LIMITÉE (Génération Seule) | 💎 Paid: N/A | 🎁 Quest: N/A`;
     }
-    const tierPercent = quota.tierLimit > 0
-        ? Math.round((quota.tierRemaining / quota.tierLimit) * 100)
-        : 0;
-    const ms = quota.timeUntilReset;
-    const hours = Math.floor(ms / (1000 * 60 * 60));
-    const minutes = Math.floor((ms % (1000 * 60 * 60)) / (1000 * 60));
-    const resetIn = `${hours}h${minutes}m`;
-    const stashStr = quota.questStash > 0
-        ? ` | 🎁 ~${quota.questStash.toFixed(2)} (stash)`
-        : '';
-    return `${quota.tierEmoji} ${quota.tierRemaining.toFixed(2)}/${quota.tierLimit} (${tierPercent}%)${stashStr} | 💎 $${quota.walletBalance.toFixed(2)} | ⏰ ${resetIn}`;
+    return `🎁 Quest: ~${quota.questBalance.toFixed(2)} | 💎 Paid: ~${quota.walletBalance.toFixed(2)}${quota.needsAlert ? ' | ⚠️' : ''}`;
 }
+/**
+ * Best-effort Quest balance: claimed quest pollen (tier bucket) minus
+ * tier-metered consumption since the earliest claim. This is NOT a server
+ * guarantee — the authoritative split is meter_source in /account/usage.
+ */
 export async function fetchQuestStash(apiKey) {
     let claimedQuestTier = 0;
     let firstClaimMs = Infinity;

package/dist/server/scripts/pollinations_pricing.js

@@ -109,12 +109,15 @@ function getCost(m, type) {
 }
 // ─── RENDU VISUEL ────────────────────────────────────────────────────────────
 function parseNameDesc(m) {
-    const fullDesc = m.description || m.name;
-    const parts = fullDesc.split(" - ");
+    if (m.title && m.description) {
+        return { nom: m.title, desc: m.description };
+    }
+    const displayName = m.title || m.description || m.name;
+    const parts = displayName.split(" - ");
     if (parts.length > 1) {
         return { nom: parts[0].trim(), desc: parts.slice(1).join(" - ").trim() };
     }
-    return { nom: fullDesc, desc: "" };
+    return { nom: displayName, desc: "" };
 }
 function flags(m, overrides = []) {
     const f = [];

package/dist/server/status.js

@@ -5,6 +5,5 @@ export function createStatusHooks(client) {
     };
 }
 function formatStatus(quota) {
-    const tierName = quota.tier === 'alwaysfree' ? 'Free' : quota.tier;
-    return `${tierName} ${quota.tierRemaining.toFixed(2)}/${quota.tierLimit} 🌼 | Wallet $${quota.walletBalance.toFixed(2)}`;
+    return `🎁 Quest ~${quota.questBalance.toFixed(2)} | 💎 Paid ~${quota.walletBalance.toFixed(2)}`;
 }

package/dist/server/toast.js

@@ -41,7 +41,7 @@ export function emitStatusToast(type, message, title, metadata) {
             getQuotaStatus(true).then(quota => {
                 const quotaMsg = formatQuotaForToast
                     ? formatQuotaForToast(quota)
-                    : `🌻 Freetier: ${quota.tierRemaining.toFixed(2)}/${quota.tierLimit} | Wallet: $${quota.walletBalance.toFixed(2)}`;
+                    : `🎁 Quest: ~${quota.questBalance.toFixed(2)} | 💎 Paid: ~${quota.walletBalance.toFixed(2)}`;
                 finalMessage += `\n${quotaMsg}`;
                 dispatchToast('status', type, finalMessage, title || 'Pollinations Status');
             }).catch(() => {

package/dist/tools/index.d.ts

@@ -11,6 +11,7 @@ import { polliGenVideoTool } from './pollinations/gen_video.js';
 import { polliGenAudioTool } from './pollinations/gen_audio.js';
 import { polliSttTool } from './pollinations/transcribe_audio.js';
 import { polliGenMusicTool } from './pollinations/gen_music.js';
+import { polliGen3dTool } from './pollinations/gen_3d.js';
 import { polliWebSearchTool } from './pollinations/polli_web_search.js';
 import { polliBetaDiscoveryTool } from './pollinations/beta_discovery.js';
 import { polliGenConfirmTool } from './pollinations/polli_gen_confirm.js';
@@ -23,4 +24,4 @@ import { polliQuestsTool } from './pollinations/polli_quests.js';
  * @returns Record<string, Tool> to be spread into the plugin's tool: {} property
  */
 export declare function createToolRegistry(): Record<string, any>;
-export { polliGenImageTool, polliGenVideoTool, polliGenAudioTool, polliSttTool, polliGenMusicTool, polliWebSearchTool, polliBetaDiscoveryTool, polliGenConfirmTool, polliStatusTool, polliConfigTool, polliQuestsTool };
+export { polliGenImageTool, polliGenVideoTool, polliGenAudioTool, polliSttTool, polliGenMusicTool, polliGen3dTool, polliWebSearchTool, polliBetaDiscoveryTool, polliGenConfirmTool, polliStatusTool, polliConfigTool, polliQuestsTool };

package/dist/tools/index.js

@@ -30,6 +30,7 @@ import { polliGenVideoTool } from './pollinations/gen_video.js';
 import { polliGenAudioTool } from './pollinations/gen_audio.js';
 import { polliSttTool } from './pollinations/transcribe_audio.js';
 import { polliGenMusicTool } from './pollinations/gen_music.js';
+import { polliGen3dTool } from './pollinations/gen_3d.js';
 import { polliWebSearchTool } from './pollinations/polli_web_search.js';
 import { polliBetaDiscoveryTool } from './pollinations/beta_discovery.js';
 import { polliGenConfirmTool } from './pollinations/polli_gen_confirm.js';
@@ -82,6 +83,7 @@ export function createToolRegistry() {
         tools['polli_gen_audio'] = polliGenAudioTool;
         tools['polli_stt'] = polliSttTool;
         tools['polli_gen_music'] = polliGenMusicTool;
+        tools['polli_gen_3d'] = polliGen3dTool;
         // Unified search tool
         tools['polli_web_search'] = polliWebSearchTool;
         // Cost Guard Confirmation tool
@@ -104,4 +106,4 @@ export function createToolRegistry() {
     return tools;
 }
 // Re-export for convenience
-export { polliGenImageTool, polliGenVideoTool, polliGenAudioTool, polliSttTool, polliGenMusicTool, polliWebSearchTool, polliBetaDiscoveryTool, polliGenConfirmTool, polliStatusTool, polliConfigTool, polliQuestsTool };
+export { polliGenImageTool, polliGenVideoTool, polliGenAudioTool, polliSttTool, polliGenMusicTool, polliGen3dTool, polliWebSearchTool, polliBetaDiscoveryTool, polliGenConfirmTool, polliStatusTool, polliConfigTool, polliQuestsTool };

package/dist/tools/pollinations/artifact-core.d.ts

@@ -0,0 +1,53 @@
+/**
+ * Artifact Core (v6.5) — shared input/output primitives.
+ *
+ * Extracted from the Free Tools (gen_video_free.resolveAsset/mimeFor,
+ * imgtools buildMultipart/getDims) and generalized for Pollinations tools,
+ * Free services and local operations.
+ *
+ * Pipeline: resolveArtifactInput → executeOperation → retrieve bytes
+ *           → detectArtifactType (magic bytes) → persistArtifact
+ *
+ * Invariant: saved extension follows REAL detected bytes, never a
+ * caller-requested format (a b64 edit response can be JPEG while the
+ * caller assumes PNG — see Phase 2 live evidence T14).
+ */
+export interface ResolvedAsset {
+    buf: Buffer;
+    mime: string;
+    ext: string;
+    filename: string;
+}
+export interface DetectedArtifact {
+    format: string;
+    ext: string;
+    mime: string;
+}
+/** Magic-bytes detection. Returns null when the format is unknown. */
+export declare function detectArtifactType(buf: Buffer): DetectedArtifact | null;
+export declare function mimeForExt(ext: string): string;
+export declare function mimeFor(ext: string, kind: 'image' | 'audio' | 'video' | 'model'): string;
+/**
+ * Resolve an asset input (local path | http(s) URL | data: URI) into a
+ * Buffer + mime + filename. URL downloads are bounded (60s default).
+ */
+export declare function resolveArtifactInput(input: string, kind?: 'image' | 'audio' | 'video' | 'model', timeoutMs?: number): Promise<ResolvedAsset>;
+export declare function sanitizeFilename(name: string): string;
+export interface PersistOptions {
+    outputDir: string;
+    filename?: string;
+    preferredExt?: string;
+    /** When true (default), real magic bytes override the preferred extension. */
+    detectExt?: boolean;
+}
+export interface PersistedArtifact {
+    filePath: string;
+    size: number;
+    detected: DetectedArtifact | null;
+    ext: string;
+}
+/**
+ * Persist artifact bytes. The written extension follows the DETECTED magic
+ * bytes (detectExt !== false) — never a blind caller assumption.
+ */
+export declare function persistArtifact(buf: Buffer, opts: PersistOptions): PersistedArtifact;

package/dist/tools/pollinations/artifact-core.js

@@ -0,0 +1,159 @@
+/**
+ * Artifact Core (v6.5) — shared input/output primitives.
+ *
+ * Extracted from the Free Tools (gen_video_free.resolveAsset/mimeFor,
+ * imgtools buildMultipart/getDims) and generalized for Pollinations tools,
+ * Free services and local operations.
+ *
+ * Pipeline: resolveArtifactInput → executeOperation → retrieve bytes
+ *           → detectArtifactType (magic bytes) → persistArtifact
+ *
+ * Invariant: saved extension follows REAL detected bytes, never a
+ * caller-requested format (a b64 edit response can be JPEG while the
+ * caller assumes PNG — see Phase 2 live evidence T14).
+ */
+import * as fs from 'fs';
+import * as path from 'path';
+/** Magic-bytes detection. Returns null when the format is unknown. */
+export function detectArtifactType(buf) {
+    if (!buf || buf.length < 4)
+        return null;
+    // JPEG
+    if (buf[0] === 0xff && buf[1] === 0xd8 && buf[2] === 0xff) {
+        return { format: 'jpeg', ext: 'jpg', mime: 'image/jpeg' };
+    }
+    // PNG
+    if (buf[0] === 0x89 && buf[1] === 0x50 && buf[2] === 0x4e && buf[3] === 0x47) {
+        return { format: 'png', ext: 'png', mime: 'image/png' };
+    }
+    // GIF
+    if (buf.toString('ascii', 0, 3) === 'GIF') {
+        return { format: 'gif', ext: 'gif', mime: 'image/gif' };
+    }
+    // WebP
+    if (buf.length > 12 && buf.toString('ascii', 0, 4) === 'RIFF' && buf.toString('ascii', 8, 12) === 'WEBP') {
+        return { format: 'webp', ext: 'webp', mime: 'image/webp' };
+    }
+    // glTF binary (GLB) — magic 'glTF' (0x676C5446)
+    if (buf.toString('ascii', 0, 4) === 'glTF') {
+        return { format: 'glb', ext: 'glb', mime: 'model/gltf-binary' };
+    }
+    // MP4 (ftyp box at offset 4)
+    if (buf.length > 12 && buf.toString('ascii', 4, 8) === 'ftyp') {
+        return { format: 'mp4', ext: 'mp4', mime: 'video/mp4' };
+    }
+    // WebM (EBML magic)
+    if (buf[0] === 0x1a && buf[1] === 0x45 && buf[2] === 0xdf && buf[3] === 0xa3) {
+        return { format: 'webm', ext: 'webm', mime: 'video/webm' };
+    }
+    // MP3 (ID3 tag or MPEG frame sync)
+    if (buf.length > 3 && (buf.toString('ascii', 0, 3) === 'ID3' || (buf[0] === 0xff && (buf[1] & 0xe0) === 0xe0))) {
+        return { format: 'mp3', ext: 'mp3', mime: 'audio/mpeg' };
+    }
+    // WAV
+    if (buf.length > 12 && buf.toString('ascii', 0, 4) === 'RIFF' && buf.toString('ascii', 8, 12) === 'WAVE') {
+        return { format: 'wav', ext: 'wav', mime: 'audio/wav' };
+    }
+    // OGG
+    if (buf.toString('ascii', 0, 4) === 'OggS') {
+        return { format: 'ogg', ext: 'ogg', mime: 'audio/ogg' };
+    }
+    // JSON (fallback for text artifacts)
+    if (buf.length > 0 && (buf[0] === 0x7b || buf[0] === 0x5b)) {
+        return { format: 'json', ext: 'json', mime: 'application/json' };
+    }
+    return null;
+}
+const EXT_MIME = {
+    jpg: 'image/jpeg', jpeg: 'image/jpeg', png: 'image/png', webp: 'image/webp',
+    gif: 'image/gif', glb: 'model/gltf-binary', mp4: 'video/mp4', webm: 'video/webm',
+    mov: 'video/quicktime', mp3: 'audio/mpeg', wav: 'audio/wav', ogg: 'audio/ogg',
+    m4a: 'audio/mp4', flac: 'audio/flac', txt: 'text/plain', json: 'application/json',
+};
+export function mimeForExt(ext) {
+    return EXT_MIME[ext.toLowerCase()] || 'application/octet-stream';
+}
+export function mimeFor(ext, kind) {
+    const e = ext.toLowerCase();
+    const known = EXT_MIME[e];
+    if (known)
+        return known;
+    if (kind === 'image')
+        return 'image/jpeg';
+    if (kind === 'audio')
+        return 'audio/mpeg';
+    if (kind === 'video')
+        return 'video/mp4';
+    return 'application/octet-stream';
+}
+/**
+ * Resolve an asset input (local path | http(s) URL | data: URI) into a
+ * Buffer + mime + filename. URL downloads are bounded (60s default).
+ */
+export async function resolveArtifactInput(input, kind = 'image', timeoutMs = 60000) {
+    // data: URI
+    const dataMatch = input.match(/^data:([^;]+);base64,(.+)$/);
+    if (dataMatch) {
+        const mime = dataMatch[1];
+        const ext = (mime.split('/')[1] || 'bin').toLowerCase();
+        return { buf: Buffer.from(dataMatch[2], 'base64'), mime, ext, filename: `${kind}.${ext}` };
+    }
+    // http(s) URL — bounded fetch
+    if (/^https?:\/\//i.test(input)) {
+        const res = await fetch(input, { signal: AbortSignal.timeout(timeoutMs) });
+        if (!res.ok)
+            throw new Error(`Asset download failed: HTTP ${res.status}`);
+        const buf = Buffer.from(await res.arrayBuffer());
+        const urlExt = (input.split('?')[0].split('.').pop() || 'bin').toLowerCase();
+        const detected = detectArtifactType(buf);
+        const ext = detected ? detected.ext : urlExt;
+        const mime = detected ? detected.mime : mimeFor(urlExt, kind);
+        return { buf, mime, ext, filename: `${kind}.${ext}` };
+    }
+    // local file
+    if (fs.existsSync(input)) {
+        const buf = fs.readFileSync(input);
+        const detected = detectArtifactType(buf);
+        const nameExt = path.extname(input).toLowerCase().replace('.', '') || 'bin';
+        const ext = detected ? detected.ext : nameExt;
+        const mime = detected ? detected.mime : mimeFor(nameExt, kind);
+        return { buf, mime, ext, filename: path.basename(input) };
+    }
+    throw new Error(`Asset not found: ${input}`);
+}
+export function sanitizeFilename(name) {
+    return name.replace(/[^\w.\-]+/g, '_').slice(0, 120);
+}
+/**
+ * Persist artifact bytes. The written extension follows the DETECTED magic
+ * bytes (detectExt !== false) — never a blind caller assumption.
+ */
+export function persistArtifact(buf, opts) {
+    const detected = opts.detectExt === false ? null : detectArtifactType(buf);
+    const ext = detected?.ext ?? opts.preferredExt ?? 'bin';
+    if (!fs.existsSync(opts.outputDir)) {
+        fs.mkdirSync(opts.outputDir, { recursive: true });
+    }
+    let filename = opts.filename ? sanitizeFilename(opts.filename) : undefined;
+    if (!filename) {
+        filename = `artifact_${Date.now()}.${ext}`;
+    }
+    else if (opts.detectExt !== false && detected) {
+        // STRICT: the written extension follows the real bytes — a caller
+        // filename like my_image.png becomes my_image.jpg for JPEG bytes.
+        // Filesystem path and returned ext always agree.
+        const dotIdx = filename.lastIndexOf('.');
+        if (dotIdx > 0) {
+            filename = filename.slice(0, dotIdx) + '.' + ext;
+        }
+        else {
+            filename = `${filename}.${ext}`;
+        }
+    }
+    else if (!filename.includes('.')) {
+        filename = `${filename}.${ext}`;
+    }
+    const filePath = path.join(opts.outputDir, filename);
+    fs.writeFileSync(filePath, buf);
+    return { filePath, size: buf.length, detected, ext };
+}