@blockrun/franklin 3.15.47 → 3.15.49

package/dist/tools/imagegen.d.ts

@@ -32,3 +32,32 @@ export interface ImageGenDeps {
 export declare function createImageGenCapability(deps?: ImageGenDeps): CapabilityHandler;
 /** Back-compat static capability for callers that don't want the Content bridge. */
 export declare const imageGenCapability: CapabilityHandler;
+export interface ImagePollBody {
+    data?: {
+        b64_json?: string;
+        url?: string;
+        revised_prompt?: string;
+    }[];
+    error?: unknown;
+    status?: string;
+}
+export type ImagePollOutcome = {
+    kind: 'completed';
+    body: ImagePollBody;
+} | {
+    kind: 'failed';
+    error?: unknown;
+} | {
+    kind: 'timed_out';
+} | {
+    kind: 'poll_http_error';
+    status: number;
+    bodyPreview: string;
+};
+export interface PollImageJobOptions {
+    /** Total wall-clock ceiling. Defaults to 5 min (matches videogen scale). */
+    maxWaitMs?: number;
+    /** Sleep between polls. Defaults to 3 s. */
+    intervalMs?: number;
+}
+export declare function pollImageJob(pollEndpoint: string, headers: Record<string, string>, signal: AbortSignal, options?: PollImageJobOptions): Promise<ImagePollOutcome>;

package/dist/tools/imagegen.js

@@ -238,9 +238,13 @@ function buildExecute(deps) {
                 headers,
                 body,
             });
-            // Handle x402 payment
+            // Handle x402 payment. Lifted out of the inner block so the polling
+            // path below can reuse the signed headers — every poll request
+            // re-presents the same authorization (the gateway settles on the
+            // first completed poll, same contract as videogen.ts:251).
+            let paymentHeaders = null;
             if (response.status === 402) {
-                const paymentHeaders = await signPayment(response, chain, endpoint);
+                paymentHeaders = await signPayment(response, chain, endpoint);
                 if (!paymentHeaders) {
                     return { output: 'Payment failed. Check wallet balance with: franklin balance', isError: true };
                 }
@@ -255,7 +259,44 @@ function buildExecute(deps) {
                 const errText = await response.text().catch(() => '');
                 return { output: `Image generation failed (${response.status}): ${errText.slice(0, 200)}`, isError: true };
             }
-            const result = await response.json();
+            let result = await response.json();
+            // Async path: gateway returns HTTP 202 (Accepted, queued) + a poll_url
+            // when the upstream image model takes longer than the inline budget
+            // (gpt-image-1/-2 routinely exceed 30s). Verified 2026-05-04 from
+            // Cloud Run logs — five back-to-back ImageGen calls that the agent
+            // saw as "No image data returned from API" had all returned 202;
+            // 4 of 5 actually completed in GCS within 41–56s and would have
+            // been retrievable if Franklin had polled. Mirror videogen.ts's
+            // pollUntilReady contract: same x-payment header on each poll.
+            if (response.status === 202 && result.poll_url) {
+                const origin = new URL(apiUrl).origin;
+                const pollEndpoint = result.poll_url.startsWith('http')
+                    ? result.poll_url
+                    : `${origin}${result.poll_url}`;
+                const pollHeaders = paymentHeaders ? { ...headers, ...paymentHeaders } : headers;
+                // Replace the POST timeout with a longer poll deadline. Image
+                // generation routinely completes within 1–3 min once queued; the
+                // 5 min ceiling matches videogen's POLL_MAX_WAIT_MS scale.
+                clearTimeout(timeout);
+                const outcome = await pollImageJob(pollEndpoint, pollHeaders, controller.signal);
+                if (outcome.kind === 'failed') {
+                    return {
+                        output: `Image generation failed upstream: ${JSON.stringify(outcome.error ?? '').slice(0, 240)}`,
+                        isError: true,
+                    };
+                }
+                if (outcome.kind === 'poll_http_error') {
+                    return { output: `Image poll failed (${outcome.status}): ${outcome.bodyPreview}`, isError: true };
+                }
+                if (outcome.kind === 'timed_out') {
+                    return {
+                        output: `Image generation queued but did not complete within 5 minutes. Payment was settled when the gateway accepted the job (HTTP 202). ` +
+                            `If this keeps happening, the upstream image model is overloaded — try a smaller / faster model or retry later.`,
+                        isError: true,
+                    };
+                }
+                result = outcome.body;
+            }
             const imageData = result.data?.[0];
             if (!imageData) {
                 // Some gateways return 200 with an `error` / `message` field for
@@ -470,3 +511,48 @@ export function createImageGenCapability(deps = {}) {
 }
 /** Back-compat static capability for callers that don't want the Content bridge. */
 export const imageGenCapability = createImageGenCapability();
+export async function pollImageJob(pollEndpoint, headers, signal, options = {}) {
+    const maxWaitMs = options.maxWaitMs ?? 5 * 60 * 1000;
+    const intervalMs = options.intervalMs ?? 3_000;
+    const deadline = Date.now() + maxWaitMs;
+    while (Date.now() < deadline) {
+        if (signal.aborted)
+            throw new Error('aborted');
+        await sleep(intervalMs, signal);
+        const resp = await fetch(pollEndpoint, { method: 'GET', headers, signal });
+        if (resp.status === 202)
+            continue; // still queued
+        if (resp.status === 429 || resp.status >= 500)
+            continue; // transient
+        if (resp.ok) {
+            const body = (await resp.json().catch(() => null));
+            if (!body)
+                continue;
+            if (body.status === 'failed')
+                return { kind: 'failed', error: body.error };
+            if (body.status === 'completed' || (body.data && body.data[0])) {
+                return { kind: 'completed', body };
+            }
+            // Non-terminal but ok shape (e.g. status: 'in_progress') — wait.
+            continue;
+        }
+        const text = await resp.text().catch(() => '');
+        return { kind: 'poll_http_error', status: resp.status, bodyPreview: text.slice(0, 200) };
+    }
+    return { kind: 'timed_out' };
+}
+function sleep(ms, signal) {
+    return new Promise((resolve, reject) => {
+        if (signal.aborted)
+            return reject(new Error('aborted'));
+        const t = setTimeout(() => {
+            signal.removeEventListener('abort', onAbort);
+            resolve();
+        }, ms);
+        const onAbort = () => {
+            clearTimeout(t);
+            reject(new Error('aborted'));
+        };
+        signal.addEventListener('abort', onAbort, { once: true });
+    });
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@blockrun/franklin",
-  "version": "3.15.47",
+  "version": "3.15.49",
   "description": "Franklin — The AI agent with a wallet. Spends USDC autonomously to get real work done. Pay per action, no subscriptions.",
   "type": "module",
   "exports": {