dsh-neartoken 0.19.2 → 0.20.0

package/README.md

@@ -220,7 +220,7 @@ location / {
 
 | 通道 | 判定 | 请求 | 响应 |
 |---|---|---|---|
-| `images` | 声明含 `image-generation`（gpt-image 系） | `POST /v1/images/generations` | `data[0].b64_json` 或临时 `url` |
+| `images` | 声明含 `image-generation`（gpt-image 系） | `POST /v1/images/tasks` 提交 → `GET /v1/images/tasks/<id>` 轮询 | 任务 `SUCCESS` 的 `data[0].url` / `b64_json`；站点回落同步时直接是 `data[0]` |
 | `genai` | 声明含 `gemini`（nano-banana、`gemini-*-image`） | `POST /v1beta/models/<model>:generateContent` | `candidates[0].content.parts[].inlineData`（结构化） |
 | `chat` | 其余（只有 `openai` 的，如 grok-imagine） | `POST /v1/chat/completions` | 回复文本里的 `data:image/...;base64,` 或图片链接 |
 
@@ -234,7 +234,7 @@ Gemini 系走原生 surface 而不是 openai 兼容层：同模型同提示词
 
 `images` 传工作区里的图片路径，工具读成 data URL 后按通道发送：
 
-- **images 通道**：作为 `image` 数组（data URL）发给 `/v1/images/generations`（站点 DTO 里没有可用的 `edits` 路由，参考图只能搭生成请求）
+- **images 通道**：作为 `image` 数组（data URL）随任务提交发给 `/v1/images/tasks`（站点 DTO 里没有可用的 `edits` 路由，参考图只能搭生成请求）
 - **genai 通道**：作为 `inlineData` part 与提示词一起进 `contents[0].parts`
 - **chat 通道**：作为 `image_url` content part 与提示词一起进 `messages`
 
@@ -251,13 +251,22 @@ Gemini 系走原生 surface 而不是 openai 兼容层：同模型同提示词
 
 限制：一次只出一张图（`n` 未暴露）；`mask` 局部重绘、`input_fidelity` 未暴露。
 
+### 异步任务
+
+`images` 通道的模型走站点的 **durable task**：`POST /v1/images/tasks` 立刻返回 `202 + task_id`，插件每 3 秒（退避到 5 秒）轮询 `GET /v1/images/tasks/<id>`，`SUCCESS` 后再取 `data[0].url` / `b64_json`。慢模型不再靠一条长 HTTP 撑时间 —— 连接断了，任务还在站点上跑。
+
+- **轮询只重读，不重提交**：轮询撞上 5xx、网关故障或断网，按同一 `task_id` 再来一次；任务没有幂等键，重复提交会重复计费，所以提交没拿到任务就原样报给模型，由模型决定要不要重试。
+- **取消只停轮询**：`exec.signal` 中止后本地不再查询，站点上的任务照常跑完并按站点规则计费。
+- **失败带站点原话**：`FAILURE` 的 `fail_reason`（例如 `DataInspectionFailed: …`）直接进错误消息，不用去站点后台翻。
+- **两种回落都能接**：站点没把该模型认领成任务时，同一端点直接回 `200 + data[]`；不认这个端点的老站点回 404，插件改用 `POST /v1/images/generations` 同步等一次。
+
 ### 超时
 
 生图是几十秒到几分钟的活，所以有两条时间线，故意错开：
 
 | 层 | 值 | 超时后模型看到什么 |
 |---|---|---|
-| 插件自己的预算 | `imageTimeoutMs`（默认 300 秒） | `the site did not return an image within 300s (imageTimeoutMs); … retry, raise imageTimeoutMs, or enable a faster image model` |
+| 插件自己的预算 | `imageTimeoutMs`（默认 300 秒），**从提交到拿到图的总预算**（含轮询） | `the site did not return an image within 300s (imageTimeoutMs); … a submitted task keeps running on the site and is billed when it finishes …` |
 | 工具调用截止时间 | `imageTimeoutMs + 30 秒`，声明给 harness 的 timeout policy | 通用的 `tool call timed out after …ms` |
 
 自己那条早 30 秒触发，所以正常情况模型拿到的是**能指路**的那条（等了多久、该调哪个旋钮）；harness 那条只兜住「工具无视 abort 继续跑」。预算耗尽和调用方取消是分开处理的（`AbortSignal.any` 里单独持有预算信号），取消原样向上传递，不会被写成超时。

package/lib/client.js

@@ -456,23 +456,23 @@ window.__ModuleLoader__.load({
 			document.head.appendChild(tag);
 		}
 		var group_tags_module_css_default = {
-			"toneIndigo": "FotuUq_toneIndigo",
 			"toneLime": "FotuUq_toneLime",
+			"tag": "FotuUq_tag",
+			"toneViolet": "FotuUq_toneViolet",
 			"toneRose": "FotuUq_toneRose",
 			"toneEmerald": "FotuUq_toneEmerald",
-			"ratioChip": "FotuUq_ratioChip",
-			"toneFuchsia": "FotuUq_toneFuchsia",
+			"toneTeal": "FotuUq_toneTeal",
 			"toneOrange": "FotuUq_toneOrange",
-			"tag": "FotuUq_tag",
-			"toneViolet": "FotuUq_toneViolet",
-			"toneSky": "FotuUq_toneSky",
+			"ratioBase": "FotuUq_ratioBase",
+			"toneCyan": "FotuUq_toneCyan",
+			"toneIndigo": "FotuUq_toneIndigo",
 			"toneAmber": "FotuUq_toneAmber",
-			"ratioPricey": "FotuUq_ratioPricey",
+			"ratioChip": "FotuUq_ratioChip",
 			"ratioCheap": "FotuUq_ratioCheap",
-			"toneTeal": "FotuUq_toneTeal",
-			"toneCyan": "FotuUq_toneCyan",
 			"tonePink": "FotuUq_tonePink",
-			"ratioBase": "FotuUq_ratioBase"
+			"toneSky": "FotuUq_toneSky",
+			"toneFuchsia": "FotuUq_toneFuchsia",
+			"ratioPricey": "FotuUq_ratioPricey"
 		};
 		//#endregion
 		//#region src/client/group-tags.tsx
@@ -527,39 +527,39 @@ window.__ModuleLoader__.load({
 			document.head.appendChild(tag);
 		}
 		var ModelGroupSelect_module_css_default = {
-			"triggerEffort": "_2pt-bW_triggerEffort",
-			"cellLabel": "_2pt-bW_cellLabel",
-			"groups": "_2pt-bW_groups",
-			"modelName": "_2pt-bW_modelName",
-			"groupName": "_2pt-bW_groupName",
-			"searchRow": "_2pt-bW_searchRow",
-			"retry": "_2pt-bW_retry",
-			"empty": "_2pt-bW_empty",
-			"triggerLabel": "_2pt-bW_triggerLabel",
-			"status": "_2pt-bW_status",
+			"trigger": "_2pt-bW_trigger",
+			"menu": "_2pt-bW_menu",
+			"groupInline": "_2pt-bW_groupInline",
 			"chevron": "_2pt-bW_chevron",
 			"search": "_2pt-bW_search",
+			"retry": "_2pt-bW_retry",
+			"status": "_2pt-bW_status",
 			"warning": "_2pt-bW_warning",
-			"option": "_2pt-bW_option",
-			"cellValue": "_2pt-bW_cellValue",
-			"variantCount": "_2pt-bW_variantCount",
-			"cellChevron": "_2pt-bW_cellChevron",
 			"selected": "_2pt-bW_selected",
-			"triggerIcon": "_2pt-bW_triggerIcon",
-			"searchClear": "_2pt-bW_searchClear",
-			"cell": "_2pt-bW_cell",
-			"groupOptionLabel": "_2pt-bW_groupOptionLabel",
 			"optionTrailing": "_2pt-bW_optionTrailing",
-			"toast": "_2pt-bW_toast",
-			"groupInline": "_2pt-bW_groupInline",
 			"modelOption": "_2pt-bW_modelOption",
-			"check": "_2pt-bW_check",
+			"variantCount": "_2pt-bW_variantCount",
+			"searchClear": "_2pt-bW_searchClear",
+			"toast": "_2pt-bW_toast",
+			"empty": "_2pt-bW_empty",
+			"optionActive": "_2pt-bW_optionActive",
+			"modelName": "_2pt-bW_modelName",
 			"optionCopy": "_2pt-bW_optionCopy",
-			"trigger": "_2pt-bW_trigger",
-			"menu": "_2pt-bW_menu",
-			"error": "_2pt-bW_error",
+			"cellValue": "_2pt-bW_cellValue",
+			"cellLabel": "_2pt-bW_cellLabel",
+			"groups": "_2pt-bW_groups",
+			"searchRow": "_2pt-bW_searchRow",
+			"triggerLabel": "_2pt-bW_triggerLabel",
+			"cellChevron": "_2pt-bW_cellChevron",
+			"cell": "_2pt-bW_cell",
 			"root": "_2pt-bW_root",
-			"optionActive": "_2pt-bW_optionActive"
+			"check": "_2pt-bW_check",
+			"groupName": "_2pt-bW_groupName",
+			"groupOptionLabel": "_2pt-bW_groupOptionLabel",
+			"triggerEffort": "_2pt-bW_triggerEffort",
+			"triggerIcon": "_2pt-bW_triggerIcon",
+			"option": "_2pt-bW_option",
+			"error": "_2pt-bW_error"
 		};
 		//#endregion
 		//#region src/client/ModelGroupSelect.tsx
@@ -1164,107 +1164,107 @@ window.__ModuleLoader__.load({
 			document.head.appendChild(tag);
 		}
 		var NearTokenSection_module_css_default = {
-			"voucherEmpty": "_02HI2q_voucherEmpty",
-			"row": "_02HI2q_row",
-			"notice": "_02HI2q_notice",
-			"series0": "_02HI2q_series0",
-			"series5": "_02HI2q_series5",
-			"voucherList": "_02HI2q_voucherList",
-			"label": "_02HI2q_label",
-			"tally": "_02HI2q_tally",
-			"metaLabel": "_02HI2q_metaLabel",
-			"badgeOn": "_02HI2q_badgeOn",
-			"metaChecks": "_02HI2q_metaChecks",
-			"metaCheck": "_02HI2q_metaCheck",
-			"rowMeta": "_02HI2q_rowMeta",
-			"rowRatio": "_02HI2q_rowRatio",
-			"form": "_02HI2q_form",
-			"cardHead": "_02HI2q_cardHead",
-			"linkLine": "_02HI2q_linkLine",
-			"metaBtn": "_02HI2q_metaBtn",
-			"metaField": "_02HI2q_metaField",
-			"search": "_02HI2q_search",
-			"tipGroup": "_02HI2q_tipGroup",
-			"topup": "_02HI2q_topup",
-			"title": "_02HI2q_title",
-			"cardToggle": "_02HI2q_cardToggle",
-			"countPicked": "_02HI2q_countPicked",
-			"factValue": "_02HI2q_factValue",
-			"metaBtnOn": "_02HI2q_metaBtnOn",
-			"select": "_02HI2q_select",
-			"axisLabel": "_02HI2q_axisLabel",
+			"fact": "_02HI2q_fact",
+			"tipGroupName": "_02HI2q_tipGroupName",
+			"chevron": "_02HI2q_chevron",
+			"segmentOn": "_02HI2q_segmentOn",
+			"axisRow": "_02HI2q_axisRow",
+			"swatch": "_02HI2q_swatch",
 			"series3": "_02HI2q_series3",
-			"voucherFact": "_02HI2q_voucherFact",
-			"factLabel": "_02HI2q_factLabel",
-			"linkRow": "_02HI2q_linkRow",
-			"facts": "_02HI2q_facts",
+			"voucherRow": "_02HI2q_voucherRow",
 			"link": "_02HI2q_link",
+			"rowMeta": "_02HI2q_rowMeta",
+			"gridLine": "_02HI2q_gridLine",
+			"axis": "_02HI2q_axis",
+			"list": "_02HI2q_list",
 			"topupChips": "_02HI2q_topupChips",
-			"buttonSmall": "_02HI2q_buttonSmall",
-			"rowName": "_02HI2q_rowName",
-			"voucherRow": "_02HI2q_voucherRow",
-			"tipRow": "_02HI2q_tipRow",
-			"tipGroupName": "_02HI2q_tipGroupName",
-			"badge": "_02HI2q_badge",
-			"refresh": "_02HI2q_refresh",
-			"metaIntro": "_02HI2q_metaIntro",
-			"count": "_02HI2q_count",
-			"metaInput": "_02HI2q_metaInput",
 			"topupInput": "_02HI2q_topupInput",
+			"topupChipActive": "_02HI2q_topupChipActive",
+			"count": "_02HI2q_count",
+			"title": "_02HI2q_title",
+			"countDot": "_02HI2q_countDot",
 			"chevronOpen": "_02HI2q_chevronOpen",
-			"metaActions": "_02HI2q_metaActions",
-			"segment": "_02HI2q_segment",
-			"codeRow": "_02HI2q_codeRow",
-			"segmentOn": "_02HI2q_segmentOn",
-			"yScale": "_02HI2q_yScale",
-			"chevron": "_02HI2q_chevron",
+			"plotPanel": "_02HI2q_plotPanel",
+			"legendItem": "_02HI2q_legendItem",
+			"metaEditor": "_02HI2q_metaEditor",
+			"code": "_02HI2q_code",
+			"metaIntro": "_02HI2q_metaIntro",
+			"voucherEmpty": "_02HI2q_voucherEmpty",
+			"cardHead": "_02HI2q_cardHead",
+			"buttonSmall": "_02HI2q_buttonSmall",
+			"card": "_02HI2q_card",
+			"legendName": "_02HI2q_legendName",
+			"invite": "_02HI2q_invite",
+			"button": "_02HI2q_button",
+			"plot": "_02HI2q_plot",
+			"factValue": "_02HI2q_factValue",
+			"legend": "_02HI2q_legend",
 			"valueRow": "_02HI2q_valueRow",
-			"buttonPrimary": "_02HI2q_buttonPrimary",
+			"metaHead": "_02HI2q_metaHead",
+			"cardToggle": "_02HI2q_cardToggle",
+			"badgeOn": "_02HI2q_badgeOn",
 			"topupBar": "_02HI2q_topupBar",
+			"buttonPrimary": "_02HI2q_buttonPrimary",
+			"voucherFact": "_02HI2q_voucherFact",
+			"metaBtnOn": "_02HI2q_metaBtnOn",
 			"intro": "_02HI2q_intro",
-			"autosave": "_02HI2q_autosave",
-			"tipTitle": "_02HI2q_tipTitle",
-			"countDot": "_02HI2q_countDot",
+			"linkLine": "_02HI2q_linkLine",
+			"row": "_02HI2q_row",
+			"select": "_02HI2q_select",
+			"factLabel": "_02HI2q_factLabel",
+			"countPicked": "_02HI2q_countPicked",
+			"section": "_02HI2q_section",
+			"tally": "_02HI2q_tally",
+			"metaField": "_02HI2q_metaField",
+			"chart": "_02HI2q_chart",
+			"axisLabel": "_02HI2q_axisLabel",
+			"series2": "_02HI2q_series2",
 			"topupChip": "_02HI2q_topupChip",
+			"metaBtn": "_02HI2q_metaBtn",
+			"metaTitle": "_02HI2q_metaTitle",
+			"topup": "_02HI2q_topup",
+			"metaLabel": "_02HI2q_metaLabel",
+			"name": "_02HI2q_name",
 			"metaHint": "_02HI2q_metaHint",
-			"plotPanel": "_02HI2q_plotPanel",
-			"yTick": "_02HI2q_yTick",
-			"plot": "_02HI2q_plot",
-			"gridLine": "_02HI2q_gridLine",
-			"fact": "_02HI2q_fact",
-			"hit": "_02HI2q_hit",
-			"metaEditor": "_02HI2q_metaEditor",
-			"legendItem": "_02HI2q_legendItem",
+			"tip": "_02HI2q_tip",
+			"segmented": "_02HI2q_segmented",
+			"segment": "_02HI2q_segment",
+			"plotRow": "_02HI2q_plotRow",
+			"series4": "_02HI2q_series4",
+			"series5": "_02HI2q_series5",
 			"handle": "_02HI2q_handle",
-			"swatch": "_02HI2q_swatch",
 			"series1": "_02HI2q_series1",
-			"name": "_02HI2q_name",
-			"legendName": "_02HI2q_legendName",
-			"series2": "_02HI2q_series2",
-			"invite": "_02HI2q_invite",
-			"plotRow": "_02HI2q_plotRow",
-			"metaTitle": "_02HI2q_metaTitle",
+			"voucherGroup": "_02HI2q_voucherGroup",
+			"metaActions": "_02HI2q_metaActions",
+			"tipGroup": "_02HI2q_tipGroup",
+			"yScale": "_02HI2q_yScale",
+			"tipRow": "_02HI2q_tipRow",
+			"codeRow": "_02HI2q_codeRow",
+			"toolbar": "_02HI2q_toolbar",
+			"label": "_02HI2q_label",
+			"facts": "_02HI2q_facts",
+			"tipTitle": "_02HI2q_tipTitle",
+			"hit": "_02HI2q_hit",
+			"refresh": "_02HI2q_refresh",
+			"linkRow": "_02HI2q_linkRow",
+			"notice": "_02HI2q_notice",
+			"voucherList": "_02HI2q_voucherList",
+			"form": "_02HI2q_form",
+			"search": "_02HI2q_search",
+			"rowName": "_02HI2q_rowName",
+			"yTick": "_02HI2q_yTick",
+			"legendCost": "_02HI2q_legendCost",
+			"series0": "_02HI2q_series0",
+			"actions": "_02HI2q_actions",
+			"rowRatio": "_02HI2q_rowRatio",
 			"voucherAmount": "_02HI2q_voucherAmount",
-			"axisRow": "_02HI2q_axisRow",
+			"metaChecks": "_02HI2q_metaChecks",
+			"autosave": "_02HI2q_autosave",
 			"gridBase": "_02HI2q_gridBase",
-			"legend": "_02HI2q_legend",
-			"actions": "_02HI2q_actions",
-			"axis": "_02HI2q_axis",
-			"legendCost": "_02HI2q_legendCost",
-			"toolbar": "_02HI2q_toolbar",
-			"topupChipActive": "_02HI2q_topupChipActive",
-			"tip": "_02HI2q_tip",
-			"button": "_02HI2q_button",
-			"section": "_02HI2q_section",
-			"chart": "_02HI2q_chart",
-			"voucherGroup": "_02HI2q_voucherGroup",
-			"code": "_02HI2q_code",
-			"list": "_02HI2q_list",
-			"series4": "_02HI2q_series4",
+			"metaInput": "_02HI2q_metaInput",
+			"metaCheck": "_02HI2q_metaCheck",
 			"hint": "_02HI2q_hint",
-			"metaHead": "_02HI2q_metaHead",
-			"segmented": "_02HI2q_segmented",
-			"card": "_02HI2q_card"
+			"badge": "_02HI2q_badge"
 		};
 		//#endregion
 		//#region src/client/NearTokenSection.tsx

package/lib/index.js

@@ -1325,6 +1325,28 @@ const IMAGE_NAME = /image|imagine|nano-banana|imagen|flux|seedream|dall-?e|midjo
 * a picture model.
 */
 const NON_IMAGE_NAME = /tts|transcri|\basr\b|speech|embed|rerank|veo|video|lyria|music|sora|whisper/i;
+/** The site's durable-task surface for picture models. */
+const TASKS_PATH = "/v1/images/tasks";
+/** The synchronous picture surface: a site without tasks, and a site that answers one here anyway. */
+const GENERATIONS_PATH = "/v1/images/generations";
+/** First poll interval, and the ceiling it backs off to (HANDOFF-new-api.md part 7). */
+const POLL_FIRST_MS = 3e3;
+const POLL_MAX_MS = 5e3;
+/** How much each poll adds before it reaches {@link POLL_MAX_MS}. */
+const POLL_STEP_MS = 1e3;
+/**
+* Statuses worth re-reading the same task for: a gateway's own failure says
+* nothing about the task, which is still running behind it.
+*/
+const TRANSIENT_STATUS = /* @__PURE__ */ new Set([
+	408,
+	425,
+	429,
+	500,
+	502,
+	503,
+	504
+]);
 /**
 * Whether a catalog route is a picture generator.
 * @param model - the bare model name.
@@ -1562,60 +1584,19 @@ var NearTokenImageClient = class {
 			timeoutMs
 		}).catch((error) => {
 			if (!budget.aborted) throw error;
-			throw new Error(`the site did not return an image within ${String(Math.round(timeoutMs / 1e3))}s (imageTimeoutMs); ${request.model} can be this slow — retry, raise imageTimeoutMs, or enable a faster image model`, { cause: error });
+			throw new Error(`the site did not return an image within ${String(Math.round(timeoutMs / 1e3))}s (imageTimeoutMs); ${request.model} can be this slow — a submitted task keeps running on the site and is billed when it finishes, so raise imageTimeoutMs or enable a faster image model`, { cause: error });
 		});
 	}
 	/**
-	* One request, one answer: the parts of a generation that the time budget wraps.
+	* One generation under the time budget: the channel decides whether the
+	* picture comes back in the answer or has to be waited for, and both shapes
+	* end as one picture reference.
 	* @param request - the call, already resolved to a channel and group.
 	* @returns the encoded picture.
 	*/
 	async attempt(request) {
 		const pictures = request.images ?? [];
-		const path = request.channel === "images" ? "/v1/images/generations" : request.channel === "genai" ? `/v1beta/models/${request.model}:generateContent` : "/v1/chat/completions";
-		const response = await postJson(request.send, `${this.deps.baseURL()}${path}`, {
-			headers: {
-				...attributionHeaders(),
-				...clientHeaders(),
-				"content-type": "application/json",
-				...request.channel === "genai" ? { "x-goog-api-key": request.key } : { authorization: `Bearer ${request.key}` },
-				...request.route?.groupRef === void 0 ? {} : { "x-neartoken-group": request.route.groupRef }
-			},
-			json: JSON.stringify(request.channel === "images" ? {
-				model: request.model,
-				prompt: request.prompt,
-				n: 1,
-				...request.size === void 0 ? {} : { size: request.size },
-				...request.quality === void 0 ? {} : { quality: request.quality },
-				...request.background === void 0 ? {} : { background: request.background },
-				...pictures.length === 0 ? {} : { image: pictures.map((picture) => `data:${picture.mediaType};base64,${picture.data}`) }
-			} : request.channel === "genai" ? { contents: [{
-				role: "user",
-				parts: [{ text: request.prompt }, ...pictures.map((picture) => ({ inlineData: {
-					mimeType: picture.mediaType,
-					data: picture.data
-				} }))]
-			}] } : {
-				model: request.model,
-				messages: [{
-					role: "user",
-					content: pictures.length === 0 ? request.prompt : [{
-						type: "text",
-						text: request.prompt
-					}, ...pictures.map((picture) => ({
-						type: "image_url",
-						image_url: { url: `data:${picture.mediaType};base64,${picture.data}` }
-					}))]
-				}],
-				stream: false
-			}),
-			signal: request.signal
-		});
-		if (!response.ok) {
-			const detail = (await response.text()).slice(0, 400);
-			throw new Error(`the site refused ${request.model} with HTTP ${String(response.status)}: ${detail}`);
-		}
-		const reply = extractImageReply(await response.json());
+		const reply = request.channel === "images" ? await this.imagesReply(request, pictures) : await this.chatReply(request, pictures);
 		if (reply === void 0) throw new Error(`${request.model} answered without an image; the model may not generate pictures on this site`);
 		const bytes = reply.kind === "base64" ? Uint8Array.from(Buffer.from(reply.data, "base64")) : await this.download(reply.url, request.signal, request.send);
 		const mediaType = sniffImageMediaType(bytes);
@@ -1627,6 +1608,173 @@ var NearTokenImageClient = class {
 			bytes
 		};
 	}
+	/** The headers every picture call carries; only the credential header is the channel's own. */
+	requestHeaders(request) {
+		return {
+			...attributionHeaders(),
+			...clientHeaders(),
+			"content-type": "application/json",
+			...request.channel === "genai" ? { "x-goog-api-key": request.key } : { authorization: `Bearer ${request.key}` },
+			...request.route?.groupRef === void 0 ? {} : { "x-neartoken-group": request.route.groupRef }
+		};
+	}
+	/** The headers a poll carries: the same credential, no routing decision left to make. */
+	pollHeaders(request) {
+		return {
+			...attributionHeaders(),
+			...clientHeaders(),
+			authorization: `Bearer ${request.key}`
+		};
+	}
+	/**
+	* The serialized body one channel sends.
+	* @param request - the attempt.
+	* @param pictures - reference pictures, already encoded.
+	* @returns the JSON body.
+	*/
+	requestBody(request, pictures) {
+		return JSON.stringify(request.channel === "images" ? {
+			model: request.model,
+			prompt: request.prompt,
+			n: 1,
+			...request.size === void 0 ? {} : { size: request.size },
+			...request.quality === void 0 ? {} : { quality: request.quality },
+			...request.background === void 0 ? {} : { background: request.background },
+			...pictures.length === 0 ? {} : { image: pictures.map((picture) => `data:${picture.mediaType};base64,${picture.data}`) }
+		} : request.channel === "genai" ? { contents: [{
+			role: "user",
+			parts: [{ text: request.prompt }, ...pictures.map((picture) => ({ inlineData: {
+				mimeType: picture.mediaType,
+				data: picture.data
+			} }))]
+		}] } : {
+			model: request.model,
+			messages: [{
+				role: "user",
+				content: pictures.length === 0 ? request.prompt : [{
+					type: "text",
+					text: request.prompt
+				}, ...pictures.map((picture) => ({
+					type: "image_url",
+					image_url: { url: `data:${picture.mediaType};base64,${picture.data}` }
+				}))]
+			}],
+			stream: false
+		});
+	}
+	/**
+	* One refusal, carrying the status and the site's own words.
+	* @param request - the attempt that was refused.
+	* @param response - the site's answer.
+	* @returns the error to throw.
+	*/
+	async refusal(request, response) {
+		const detail = (await response.text()).slice(0, 400);
+		return /* @__PURE__ */ new Error(`the site refused ${request.model} with HTTP ${String(response.status)}: ${detail}`);
+	}
+	/**
+	* The chat-shaped channels: one request that answers the picture.
+	* @param request - the attempt.
+	* @param pictures - reference pictures, already encoded.
+	* @returns the picture reference, or undefined when the answer carries none.
+	*/
+	async chatReply(request, pictures) {
+		const path = request.channel === "genai" ? `/v1beta/models/${request.model}:generateContent` : "/v1/chat/completions";
+		const response = await postJson(request.send, `${this.deps.baseURL()}${path}`, {
+			headers: this.requestHeaders(request),
+			json: this.requestBody(request, pictures),
+			signal: request.signal
+		});
+		if (!response.ok) throw await this.refusal(request, response);
+		return extractImageReply(await response.json());
+	}
+	/**
+	* The `images` channel: a durable task when the site runs one, the picture
+	* itself when it does not.
+	*
+	* Which of the two an answer is, is the answer's own business — a task id
+	* means polling, `data[]` means the picture is already here, and a 404 means
+	* this site predates the task endpoint. Choosing by configuration would break
+	* the moment the site ships or drops a task plugin.
+	* @param request - the attempt.
+	* @param pictures - reference pictures, already encoded.
+	* @returns the picture reference the answer carries.
+	*/
+	async imagesReply(request, pictures) {
+		const submitted = await postJson(request.send, `${this.deps.baseURL()}${TASKS_PATH}`, {
+			headers: this.requestHeaders(request),
+			json: this.requestBody(request, pictures),
+			signal: request.signal
+		});
+		if (submitted.status === 404) {
+			await submitted.body?.cancel().catch(() => {});
+			return this.syncImagesReply(request, pictures);
+		}
+		if (!submitted.ok) throw await this.refusal(request, submitted);
+		const body = await submitted.json();
+		const taskId = taskIdOf(body);
+		if (taskId === void 0) return extractImageReply(body);
+		return this.settleTask(request, taskId);
+	}
+	/**
+	* The synchronous images route, for a site that answers 404 on submit.
+	* @param request - the attempt.
+	* @param pictures - reference pictures, already encoded.
+	* @returns the picture reference the answer carries.
+	*/
+	async syncImagesReply(request, pictures) {
+		const response = await postJson(request.send, `${this.deps.baseURL()}${GENERATIONS_PATH}`, {
+			headers: this.requestHeaders(request),
+			json: this.requestBody(request, pictures),
+			signal: request.signal
+		});
+		if (!response.ok) throw await this.refusal(request, response);
+		return extractImageReply(await response.json());
+	}
+	/**
+	* Poll one submitted task until the site reports a terminal state.
+	*
+	* Polling is the only retry: a transient gateway failure or a dropped
+	* connection re-reads the same task, so a flaky link never submits — and
+	* bills — a second generation. The caller's budget is the exit; once it
+	* fires the task keeps running on the site and is billed when it finishes.
+	* @param request - the attempt that submitted the task.
+	* @param taskId - the id the submit answer carried.
+	* @returns the picture reference the finished task carries.
+	* @throws {Error} when the task fails, disappears, or the budget runs out.
+	*/
+	async settleTask(request, taskId) {
+		const poll = this.deps.poll?.() ?? {
+			firstMs: POLL_FIRST_MS,
+			maxMs: POLL_MAX_MS
+		};
+		const url = `${this.deps.baseURL()}${TASKS_PATH}/${encodeURIComponent(taskId)}`;
+		let waitMs = poll.firstMs;
+		for (;;) {
+			await waitFor(waitMs, request.signal);
+			waitMs = Math.min(poll.maxMs, waitMs + POLL_STEP_MS);
+			let response;
+			try {
+				response = await request.send(url, {
+					headers: this.pollHeaders(request),
+					signal: request.signal
+				});
+			} catch (error) {
+				if (request.signal.aborted) throw error;
+				continue;
+			}
+			if (response.status === 404) throw new Error(`the site no longer has task ${taskId} (HTTP 404): its result expired or the account changed; submit again`);
+			if (!response.ok) {
+				if (!TRANSIENT_STATUS.has(response.status) || request.signal.aborted) throw await this.refusal(request, response);
+				await response.body?.cancel().catch(() => {});
+				continue;
+			}
+			const body = await response.json();
+			const status = taskStatusOf(body);
+			if (status === "SUCCESS") return extractImageReply(body);
+			if (status === "FAILURE") throw new Error(`the site reported task ${taskId} as FAILURE: ${taskFailureReason(body)}`);
+		}
+	}
 	/**
 	* Fetch a generated picture from the short-lived URL some gateways answer with.
 	* @param url - the site's result URL.
@@ -1641,6 +1789,61 @@ var NearTokenImageClient = class {
 		return new Uint8Array(await response.arrayBuffer());
 	}
 };
+/**
+* The task id an answer carries, when it carries one.
+* @param body - the parsed answer.
+* @returns the id, or undefined when this was not a task answer.
+*/
+function taskIdOf(body) {
+	if (typeof body !== "object" || body === null) return void 0;
+	const id = body.task_id;
+	return typeof id === "string" && id.length > 0 ? id : void 0;
+}
+/**
+* The task state one answer carries, upper-cased.
+* @param body - the parsed answer.
+* @returns the state, or an empty string when the answer names none.
+*/
+function taskStatusOf(body) {
+	if (typeof body !== "object" || body === null) return "";
+	const status = body.status;
+	return typeof status === "string" ? status.toUpperCase() : "";
+}
+/**
+* Why the site reported a task as failed.
+* @param body - the parsed task answer.
+* @returns the site's own reason, or a generic one when it gave none.
+*/
+function taskFailureReason(body) {
+	const record = typeof body === "object" && body !== null ? body : {};
+	const error = record.error;
+	const detail = typeof error === "object" && error !== null ? error.message : void 0;
+	return ((typeof record.fail_reason === "string" && record.fail_reason.length > 0 ? record.fail_reason : typeof detail === "string" && detail.length > 0 ? detail : void 0) ?? "image generation failed").slice(0, 400);
+}
+/**
+* Wait one poll interval, ending early when the generation is cancelled.
+* @param ms - how long to wait; the tests pass zero to poll without waiting.
+* @param signal - the generation's cancellation and time budget.
+*/
+async function waitFor(ms, signal) {
+	if (signal.aborted) throw signal.reason instanceof Error ? signal.reason : /* @__PURE__ */ new Error("the image generation was cancelled");
+	if (ms <= 0) return;
+	await new Promise((resolve, reject) => {
+		const done = () => {
+			clearTimeout(timer);
+			signal.removeEventListener("abort", cancel);
+		};
+		const cancel = () => {
+			done();
+			reject(signal.reason instanceof Error ? signal.reason : /* @__PURE__ */ new Error("the image generation was cancelled"));
+		};
+		const timer = setTimeout(() => {
+			done();
+			resolve();
+		}, ms);
+		signal.addEventListener("abort", cancel, { once: true });
+	});
+}
 //#endregion
 //#region src/host/image-settings.ts
 /** Most picture models one save may enable. */
@@ -1928,7 +2131,7 @@ async function writePicture(ctx, exec, requested, bytes) {
 function registerGenerateImageTool(ctx, deps) {
 	return ctx.tools.register(defineTool({
 		name: "generate_image",
-		description: "Generate one image from a text prompt with the configured image model (the gpt-image, nano-banana, and gemini image families) and return the image itself. One call takes 20-60 seconds. Write the prompt as a full description of the picture you want; quoted text that must appear in the image is rendered by the model, but long lines may smear. Pass images to edit or compose from existing files and say what to keep and what to change; the first reference picture also sets the output aspect ratio. The available models are the ones the operator enabled in Settings → NearToken → Image generation.",
+		description: "Generate one image from a text prompt with the configured image model (the gpt-image, nano-banana, and gemini image families) and return the image itself. A call takes 20-60 seconds, and a queued or slow model can take minutes. Write the prompt as a full description of the picture you want; quoted text that must appear in the image is rendered by the model, but long lines may smear. Pass images to edit or compose from existing files and say what to keep and what to change; the first reference picture also sets the output aspect ratio. The available models are the ones the operator enabled in Settings → NearToken → Image generation.",
 		parameters: {
 			prompt: {
 				type: "string",

package/lib/types/host/images.d.ts

@@ -3,11 +3,15 @@
  * image models accept and the two result envelopes they answer with.
  *
  * The site lists picture generators next to chat models, and they do not share
- * one API. A model the catalog marks `image-generation` answers
- * `POST /v1/images/generations` with either a base64 body or a short-lived URL;
- * the Gemini-shaped ones (nano-banana, `*-image`) answer a chat completion whose
- * text embeds the picture. Both paths end here as encoded bytes, which is what
- * a tool result can carry.
+ * one API. A model the catalog marks `image-generation` is asked through the
+ * task endpoint (`POST /v1/images/tasks`): the site answers a durable task id at
+ * once and the picture arrives by polling, because a slow generator outlives
+ * any single HTTP response. The same endpoint answers the picture itself when
+ * nothing claims the model as a task, and a site too old to know it answers 404
+ * — the synchronous `POST /v1/images/generations` is then used once. The
+ * Gemini-shaped ones (nano-banana, `*-image`) answer a chat completion whose
+ * text embeds the picture. All paths end here as encoded bytes, which is what a
+ * tool result can carry.
  *
  * @module
  */
@@ -71,6 +75,14 @@ export interface NearTokenImageDeps {
     routes: () => Promise<readonly NearTokenRoute[]>;
     /** How long one generation may take before it is abandoned, in milliseconds. */
     timeoutMs: () => number;
+    /**
+     * Poll cadence for a durable task: the first wait and the ceiling it backs
+     * off to. Defaults to 3 s and 5 s; a test passes zeros to poll immediately.
+     */
+    poll?: () => {
+        readonly firstMs: number;
+        readonly maxMs: number;
+    };
     /** HTTP carrier; defaults to the process's own fetch. */
     fetch?: typeof fetch;
 }
@@ -112,11 +124,71 @@ export declare class NearTokenImageClient {
         readonly signal?: AbortSignal;
     }): Promise<NearTokenGeneratedImage>;
     /**
-     * One request, one answer: the parts of a generation that the time budget wraps.
+     * One generation under the time budget: the channel decides whether the
+     * picture comes back in the answer or has to be waited for, and both shapes
+     * end as one picture reference.
      * @param request - the call, already resolved to a channel and group.
      * @returns the encoded picture.
      */
     private attempt;
+    /** The headers every picture call carries; only the credential header is the channel's own. */
+    private requestHeaders;
+    /** The headers a poll carries: the same credential, no routing decision left to make. */
+    private pollHeaders;
+    /**
+     * The serialized body one channel sends.
+     * @param request - the attempt.
+     * @param pictures - reference pictures, already encoded.
+     * @returns the JSON body.
+     */
+    private requestBody;
+    /**
+     * One refusal, carrying the status and the site's own words.
+     * @param request - the attempt that was refused.
+     * @param response - the site's answer.
+     * @returns the error to throw.
+     */
+    private refusal;
+    /**
+     * The chat-shaped channels: one request that answers the picture.
+     * @param request - the attempt.
+     * @param pictures - reference pictures, already encoded.
+     * @returns the picture reference, or undefined when the answer carries none.
+     */
+    private chatReply;
+    /**
+     * The `images` channel: a durable task when the site runs one, the picture
+     * itself when it does not.
+     *
+     * Which of the two an answer is, is the answer's own business — a task id
+     * means polling, `data[]` means the picture is already here, and a 404 means
+     * this site predates the task endpoint. Choosing by configuration would break
+     * the moment the site ships or drops a task plugin.
+     * @param request - the attempt.
+     * @param pictures - reference pictures, already encoded.
+     * @returns the picture reference the answer carries.
+     */
+    private imagesReply;
+    /**
+     * The synchronous images route, for a site that answers 404 on submit.
+     * @param request - the attempt.
+     * @param pictures - reference pictures, already encoded.
+     * @returns the picture reference the answer carries.
+     */
+    private syncImagesReply;
+    /**
+     * Poll one submitted task until the site reports a terminal state.
+     *
+     * Polling is the only retry: a transient gateway failure or a dropped
+     * connection re-reads the same task, so a flaky link never submits — and
+     * bills — a second generation. The caller's budget is the exit; once it
+     * fires the task keeps running on the site and is billed when it finishes.
+     * @param request - the attempt that submitted the task.
+     * @param taskId - the id the submit answer carried.
+     * @returns the picture reference the finished task carries.
+     * @throws {Error} when the task fails, disappears, or the budget runs out.
+     */
+    private settleTask;
     /**
      * Fetch a generated picture from the short-lived URL some gateways answer with.
      * @param url - the site's result URL.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "dsh-neartoken",
-  "version": "0.19.2",
+  "version": "0.20.0",
   "publishConfig": {
     "access": "public"
   },