@dickpy/dsh-imagegen 1.0.20 → 1.2.0

package/src/client/settings-form.ts

@@ -102,6 +102,18 @@ export function textField(field: string): FieldSpec {
   }
 }
 
+/** A newline/comma-separated model list, persisted as a normalized string array. */
+export function stringListField(field: string): FieldSpec {
+  return {
+    field,
+    format: value => Array.isArray(value) ? value.filter((item): item is string => typeof item === 'string').join('\n') : '',
+    parse: (text) => {
+      const values = [...new Set(text.split(/[\n,]/).map(item => item.trim()).filter(Boolean))]
+      return values.length === 0 ? { kind: 'clear' } : { kind: 'set', value: values }
+    },
+  }
+}
+
 /** A boolean field, edited through true/false draft text. */
 export function booleanField(field: string): FieldSpec {
   return {

package/src/client/settings-scope.ts

@@ -20,8 +20,13 @@ import { SETTINGS_API } from '../protocol.ts'
 export interface ImageGenConfig {
   enabled?: boolean
   announceToAgent?: boolean
+  allowAgentImageGeneration?: boolean
   apiUrl?: string
   apiKey?: string
+  imageModels?: string[]
+  promptApiUrl?: string
+  promptApiKey?: string
+  promptModel?: string
 }
 
 /** Wire shape of one namespace view from the bridge. */
@@ -79,6 +84,8 @@ class BridgeScopeController<T> implements SettingsScope<T> {
   private readonly store: SnapshotStore<SettingsScopeSnapshot<T>>
   /** Whether the namespace currently holds a stored secret (e.g. apiKey). */
   private readonly keySet: SnapshotStore<boolean>
+  /** Individual secret presence bits, keyed by the settings field name. */
+  private readonly secretSets: SnapshotStore<Record<string, boolean>>
   private tail: Promise<void> = Promise.resolve()
   private disposed = false
 
@@ -96,6 +103,7 @@ class BridgeScopeController<T> implements SettingsScope<T> {
       mode: 'host',
     })
     this.keySet = createSnapshotStore(false)
+    this.secretSets = createSnapshotStore({})
   }
 
   getSnapshot(): SettingsScopeSnapshot<T> {
@@ -112,6 +120,16 @@ class BridgeScopeController<T> implements SettingsScope<T> {
     return this.keySet.subscribe(listener)
   }
 
+  /** Whether a specific secret field currently has a stored value. */
+  getSecretSetSnapshot(field: string): boolean {
+    return this.secretSets.getSnapshot()[field] === true
+  }
+
+  /** Observe changes to individual secret-field presence bits. */
+  subscribeSecretSets(listener: () => void): () => void {
+    return this.secretSets.subscribe(listener)
+  }
+
   subscribe(listener: () => void): () => void {
     return this.store.subscribe(listener)
   }
@@ -164,6 +182,7 @@ class BridgeScopeController<T> implements SettingsScope<T> {
         draft.writable = writable === true
       })
       this.keySet.set(false)
+      this.secretSets.set({})
       return
     }
     this.accept(view, writable)
@@ -200,7 +219,9 @@ class BridgeScopeController<T> implements SettingsScope<T> {
       // card binds without a narrowing decoder.
       draft.value = view.value as T
     })
-    this.keySet.set(Array.isArray(view.secrets) && view.secrets.some(secret => secret.set))
+    const secretSets = Object.fromEntries((view.secrets ?? []).map(secret => [secret.path.join('.'), secret.set]))
+    this.keySet.set(Object.values(secretSets).some(Boolean))
+    this.secretSets.set(secretSets)
   }
 }
 
@@ -210,6 +231,8 @@ export interface ImageGenScope extends SettingsScope<ImageGenConfig> {
   load(): Promise<void>
   getKeySetSnapshot(): boolean
   subscribeKeySet(listener: () => void): () => void
+  getSecretSetSnapshot(field: string): boolean
+  subscribeSecretSets(listener: () => void): () => void
 }
 
 /**

package/src/engine.ts

@@ -69,6 +69,27 @@ const GROK_ASPECT_ALIASES: Readonly<Record<string, string>> = {
   '21:9': '20:9',
 }
 
+/**
+ * One request-scoped timeout that is cleared as soon as its fetch settles.
+ * AbortSignal.timeout() cannot be disposed early; using it inside a long-lived
+ * task queue leaves an otherwise idle Node process holding every timeout.
+ */
+function requestSignal(source: AbortSignal | undefined, timeoutMs: number): { signal: AbortSignal; dispose: () => void } {
+  const controller = new AbortController()
+  const abortFromSource = () => { controller.abort(source?.reason) }
+  if (source?.aborted === true) abortFromSource()
+  else source?.addEventListener('abort', abortFromSource, { once: true })
+  const timeout = setTimeout(() => { controller.abort(new DOMException('The operation timed out.', 'TimeoutError')) }, timeoutMs)
+  timeout.unref()
+  return {
+    signal: controller.signal,
+    dispose: () => {
+      clearTimeout(timeout)
+      source?.removeEventListener('abort', abortFromSource)
+    },
+  }
+}
+
 /** Content-type extension hints for URL-fetched images. */
 function mimeOfExtension(path: string): string | undefined {
   const match = /\.([a-z0-9]+)$/i.exec(path)
@@ -181,16 +202,19 @@ async function normalizeItem(
     if (parsed === undefined) throw new ImageGenError('upstream returned a malformed data: url')
     return { b64: parsed.base64, mime: parsed.mime, revisedPrompt }
   }
+  const budget = requestSignal(undefined, IMAGE_FETCH_TIMEOUT_MS)
   let response: Response
   try {
     response = await fetch(url, {
       headers: {
         ...upstream.apiKey === '' ? {} : { authorization: `Bearer ${upstream.apiKey}` },
       },
-      signal: AbortSignal.timeout(IMAGE_FETCH_TIMEOUT_MS),
+      signal: budget.signal,
     })
   } catch (error) {
     throw new ImageGenError(`failed to fetch the generated image url: ${error instanceof Error ? error.message : String(error)}`)
+  } finally {
+    budget.dispose()
   }
   if (!response.ok) {
     throw new ImageGenError(`failed to fetch the generated image url: HTTP ${response.status}`)
@@ -212,6 +236,7 @@ async function requestOneImage(
   upstream: UpstreamConfig,
   request: GenerateRequest,
   params: ReturnType<typeof effectiveParams>,
+  signal?: AbortSignal,
 ): Promise<GeneratedImage[]> {
   const headers: Record<string, string> = {
     authorization: `Bearer ${upstream.apiKey.trim()}`,
@@ -258,13 +283,14 @@ async function requestOneImage(
     body = JSON.stringify({ prompt: request.prompt, ...params } as Record<string, unknown>)
   }
 
+  const budget = requestSignal(signal, UPSTREAM_TIMEOUT_MS)
   let response: Response
   try {
     response = await fetch(`${baseUrl}/images/${request.mode === 'edit' ? 'edits' : 'generations'}`, {
       method: 'POST',
       headers,
       body,
-      signal: AbortSignal.timeout(UPSTREAM_TIMEOUT_MS),
+      signal: budget.signal,
     })
   } catch (error) {
     const message = error instanceof Error ? error.message : String(error)
@@ -272,6 +298,8 @@ async function requestOneImage(
       throw new ImageGenError('上游接口响应超时（240 秒）', 'upstream-timeout')
     }
     throw new ImageGenError(`无法连接上游接口：${message}`, 'upstream-unreachable')
+  } finally {
+    budget.dispose()
   }
 
   let payload: unknown
@@ -312,14 +340,14 @@ async function requestOneImage(
  * parameter is never sent, because Responses-API-based gateways reject it as
  * `tools[0].n`), then the results are flattened in order.
  */
-export async function generateImage(upstream: UpstreamConfig, request: GenerateRequest): Promise<GenerateResult> {
+export async function generateImage(upstream: UpstreamConfig, request: GenerateRequest, options: { signal?: AbortSignal } = {}): Promise<GenerateResult> {
   const baseUrl = upstream.apiUrl.trim().replace(/\/+$/, '')
   if (baseUrl === '') throw new ImageGenError('api_url 未配置：请先在「设置 → 插件 → 可配置」中填写', 'config-missing')
   if (upstream.apiKey.trim() === '') throw new ImageGenError('api_key 未配置：请先在「设置 → 插件 → 可配置」中填写', 'config-missing')
   const params = effectiveParams(request)
   const count = effectiveCount(request)
   const batches = await Promise.all(
-    Array.from({ length: count }, () => requestOneImage(baseUrl, upstream, request, params)),
+    Array.from({ length: count }, () => requestOneImage(baseUrl, upstream, request, params, options.signal)),
   )
   return { images: batches.flat() }
 }

package/src/gallery-store.ts

@@ -60,6 +60,7 @@ interface StoredEntry {
   images: StoredImage[]
   hash?: string
   refName?: string
+  tags?: string[]
 }
 
 /** The index.json shape. */
@@ -171,6 +172,7 @@ function toWire(entry: StoredEntry): HistoryEntry {
       ...image.revisedPrompt === undefined ? {} : { revisedPrompt: image.revisedPrompt },
     })),
     ...entry.refName === undefined ? {} : { refName: entry.refName },
+    ...entry.tags === undefined ? {} : { tags: entry.tags },
   }
 }
 
@@ -242,6 +244,18 @@ export async function removeGallery(id: string): Promise<HistoryEntry[]> {
   })
 }
 
+/** Replace the user-managed labels for one gallery entry. */
+export async function updateGalleryTags(id: string, tags: string[]): Promise<HistoryEntry[]> {
+  return mutateGallery(async () => {
+    const normalized = [...new Set(tags.map(tag => tag.trim()).filter(Boolean))].slice(0, 20)
+    const entries = await readIndex()
+    const target = entries.find(entry => entry.id === id)
+    if (target !== undefined) target.tags = normalized
+    await writeIndex(entries)
+    return entries.map(toWire)
+  })
+}
+
 /** Remove every entry (and all image files). */
 export async function clearGallery(): Promise<HistoryEntry[]> {
   return mutateGallery(async () => {
@@ -263,4 +277,4 @@ export async function readGalleryImage(file: string): Promise<{ data: Buffer; mi
   } catch {
     return undefined
   }
-}
+}

package/src/generation-runtime.ts

@@ -0,0 +1,48 @@
+/**
+ * Shared host-side generation runtime. Both the browser routes and Agent tools
+ * submit to this one queue so persisted history and cancellation semantics stay
+ * identical regardless of where a request originated.
+ */
+
+import { randomUUID } from 'node:crypto'
+import { generateImage, type UpstreamConfig } from './engine.ts'
+import { appendHistory } from './history-store.ts'
+import type { GenerateRequest, GenerateResult, HistoryEntry, HistoryEntryInput } from './protocol.ts'
+import { GenerationTaskQueue } from './task-queue.ts'
+
+export interface HistorySink {
+  append(entry: HistoryEntryInput): Promise<HistoryEntry[]>
+}
+
+export class ImageGenerationRuntime {
+  readonly queue: GenerationTaskQueue
+
+  constructor(
+    private readonly resolve: () => UpstreamConfig,
+    private readonly history: HistorySink = { append: appendHistory },
+  ) {
+    this.queue = new GenerationTaskQueue((request, signal) => this.run(request, signal))
+  }
+
+  async run(request: GenerateRequest, signal?: AbortSignal): Promise<GenerateResult> {
+    const result = await generateImage(this.resolve(), request, { signal })
+    try {
+      const history = await this.history.append({
+        id: randomUUID(),
+        createdAt: Date.now(),
+        mode: request.mode,
+        model: request.model,
+        prompt: request.prompt,
+        size: request.size,
+        quality: request.quality,
+        detail: request.detail,
+        n: request.n,
+        images: result.images,
+        ...request.refName === undefined ? {} : { refName: request.refName },
+      })
+      return { ...result, history }
+    } catch (error) {
+      return { ...result, historyError: error instanceof Error ? error.message : String(error) }
+    }
+  }
+}

package/src/image-models.ts

@@ -0,0 +1,19 @@
+/**
+ * Image-model configuration shared by the host, panel, and Agent tools.
+ * `/models` exposes candidates only: the configured list is the explicit
+ * allow-list because OpenAI-compatible gateways rarely advertise modalities.
+ */
+
+export const DEFAULT_IMAGE_MODELS = ['gpt-image-2', 'grok-imagine-image'] as const
+
+/** Normalize user-entered model identifiers and retain a usable legacy default. */
+export function normalizeImageModels(value: unknown): string[] {
+  const candidates = Array.isArray(value) ? value : []
+  const unique = new Set<string>()
+  for (const candidate of candidates) {
+    if (typeof candidate !== 'string') continue
+    const model = candidate.trim()
+    if (model !== '') unique.add(model)
+  }
+  return unique.size > 0 ? [...unique] : [...DEFAULT_IMAGE_MODELS]
+}

package/src/index.ts

@@ -13,8 +13,13 @@ import z from 'schemastery'
 import type {} from '@deepseek-ai/dsh-host-webserver'
 // Type-only: pulls the systemPrompt Context merge (announcement section).
 import type {} from '@deepseek-ai/dsh-system-prompt'
+import type {} from '@deepseek-ai/dsh-tools'
+import type {} from '@deepseek-ai/dsh-attachment'
 import { IMAGEGEN_SETTINGS_NAMESPACE } from './protocol.ts'
 import { makeRoutes, type SettingsSeam } from './routes.ts'
+import { ImageGenerationRuntime } from './generation-runtime.ts'
+import { registerAgentImageTools } from './agent-image-tools.ts'
+import { DEFAULT_IMAGE_MODELS, normalizeImageModels } from './image-models.ts'
 
 /** Stable cordis plugin name. */
 export const name = 'imagegen'
@@ -26,7 +31,9 @@ export const inject = ['webServer', 'systemPrompt']
 // contract only requires name / inject / Config / apply.
 export { makeRoutes } from './routes.ts'
 export { generateImage, ImageGenError } from './engine.ts'
-export { appendGallery, clearGallery, listGallery, readGalleryImage, removeGallery } from './gallery-store.ts'
+export { ImageGenerationRuntime } from './generation-runtime.ts'
+export { registerAgentImageTools } from './agent-image-tools.ts'
+export { appendGallery, clearGallery, listGallery, readGalleryImage, removeGallery, updateGalleryTags } from './gallery-store.ts'
 export { listTemplates, readTemplateImage, refreshTemplates, clearTemplateMemo } from './templates-store.ts'
 export { checkForUpdate, clearUpdateCache, compareVersions, CURRENT_VERSION, installUpdate, profileFromProcess } from './updater.ts'
 
@@ -39,35 +46,61 @@ export interface Config {
   enabled?: boolean
   /** Announce the plugin in every agent's system prompt. */
   announceToAgent?: boolean
+  /** Allow Agents to submit and retrieve image-generation tasks. */
+  allowAgentImageGeneration?: boolean
   /** Base URL of the OpenAI-compatible endpoint, e.g. https://api.openai.com/v1 */
   apiUrl?: string
   /** Bearer API key (stored as a secret field on the settings seam). */
   apiKey?: string
+  /** Explicit allow-list of image models selected for this API endpoint. */
+  imageModels?: string[]
+  /** Optional OpenAI-compatible chat endpoint for prompt enhancement. */
+  promptApiUrl?: string
+  /** Optional secret for the prompt enhancement endpoint. */
+  promptApiKey?: string
+  /** Chat model used to expand short image prompts. */
+  promptModel?: string
 }
 
 export const Config: z<Config> = z.object({
   enabled: z.boolean().default(true),
   announceToAgent: z.boolean().default(true),
+  allowAgentImageGeneration: z.boolean().default(true),
   apiUrl: z.string().default(''),
   apiKey: z.string().role('secret').default(''),
+  imageModels: z.array(z.string()).default([...DEFAULT_IMAGE_MODELS]),
+  promptApiUrl: z.string().default(''),
+  promptApiKey: z.string().role('secret').default(''),
+  promptModel: z.string().default(''),
 })
 
 /** Schema defaults, re-read for hand-built contexts (the loader applies them normally). */
 const DEFAULT_ENABLED = true
 const DEFAULT_ANNOUNCE = true
+const DEFAULT_ALLOW_AGENT_IMAGE_GENERATION = true
 
 /** Order of the announcement section within the tool-guidance band. */
 const SECTION_ORDER = 150
 
 /** Model-facing announcement: plugin presence, capabilities, and limits. */
-export const IMAGEGEN_GUIDANCE = '本机已安装 dsh-imagegen 插件（DSH AI 生图）：侧边栏「AI 生图」入口。能力：对接 OpenAI 兼容图像生成 API（模型 gpt-image-2 / grok-imagine-image），支持文生图（/images/generations）与图生图（/images/edits，上传参考图，grok 模型按官方 JSON image_url 协议发送）；API 地址与密钥在 GUI「设置 → 插件 → 可配置」中配置，密钥仅存于本机设置文档；生成请求由本地宿主代理转发，结果以 base64 返回面板，可预览与下载；可一键把满意的图片加入「画廊」（工作台顶部 文生图 / 图生图 / 画廊 三个标签页，画廊在右侧展示，收藏持久化在本地 ~/.dsh/dsh-imagegen/gallery/）。内置「提示词模板库」（面板提示词框左下角「模板库」按钮）：打包 awesome-gpt-image-2 的数百条 gpt-image-2 提示词案例（含中文标题、分类、参考图，可搜索/按分类筛选），参考图经宿主代理按需缓存到本地；用户可一键把模板提示词填入提示词框再生成。限制：生成消耗上游 API 额度；图片内容由上游模型生成，可能不符合预期或包含不适宜内容；api_key 以明文存储在设置文档中；参考图会发送至所配置的 API 服务；模板库在线刷新与参考图首次加载需要访问 vibeui.top。用户提到「生图 / 绘画 / 生成图片 / gpt-image-2 / grok-imagine-image / 文生图 / 图生图 / 画廊 / 提示词模板」时即指本插件，请据此协作。'
+export const IMAGEGEN_GUIDANCE = '本机已安装 dsh-imagegen 插件（DSH AI 生图）：侧边栏「AI 生图」入口。能力：对接 OpenAI 兼容图像生成 API，模型由用户在「设置 → 插件 → AI 生图」中检测或手动配置的生图模型列表决定；支持文生图（/images/generations）与图生图（/images/edits，上传参考图，grok-imagine 模型按官方 JSON image_url 协议发送）。API 地址与密钥在 GUI 设置中配置，密钥仅存于本机设置文档；生成请求由本地宿主代理转发，结果以 base64 返回面板，可预览与下载。模型只能使用已配置的生图模型；模型出现在 /models 中不等于其网关原生支持生图协议，遇到 Qwen、Gemini 等非 OpenAI 生图协议时应如实说明上游兼容性。可一键把满意的图片加入「画廊」。内置「提示词模板库」（面板提示词框左下角「模板库」按钮）：打包 awesome-gpt-image-2 的数百条提示词案例，可搜索、筛选与复用。Agent 可直接调用 `generate_image` 提交文生图，也可用 `edit_image` 图生图；任务后台异步执行，完成后插件会自动唤醒原对话，并以可直接查看和复用的图片附件回贴结果，因此不要反复轮询。仅在用户明确要求进度或需要恢复任务时，才使用 `get_image_generation_task` 查询状态。限制：生成消耗上游 API 额度；图片内容由上游模型生成，可能不符合预期或包含不适宜内容；api_key 以明文存储在设置文档中；参考图会发送至所配置的 API 服务；模板库在线刷新与参考图首次加载需要访问 vibeui.top。用户提到「生图 / 绘画 / 生成图片 / 文生图 / 图生图 / 画廊 / 提示词模板」时即指本插件，请据此协作。'
+
+/** Add the live allow-list so an Agent can honor a user's model choice. */
+function guidanceFor(imageModels: string[]): string {
+  return `${IMAGEGEN_GUIDANCE} 当前允许调用的生图模型：${imageModels.join('、')}。用户指定其中某个模型时，工具参数 model 必须使用该精确名称；未指定时使用列表中的第一个。`
+}
 
 /** Effective config (schema defaults applied). */
 interface EffectiveConfig {
   enabled: boolean
   announceToAgent: boolean
+  allowAgentImageGeneration: boolean
   apiUrl: string
   apiKey: string
+  imageModels: string[]
+  promptApiUrl: string
+  promptApiKey: string
+  promptModel: string
 }
 
 /**
@@ -84,11 +117,24 @@ export function apply(ctx: Context, config?: Config): void {
     return {
       enabled: value.enabled ?? DEFAULT_ENABLED,
       announceToAgent: value.announceToAgent ?? DEFAULT_ANNOUNCE,
+      allowAgentImageGeneration: value.allowAgentImageGeneration ?? DEFAULT_ALLOW_AGENT_IMAGE_GENERATION,
       apiUrl: value.apiUrl ?? '',
       apiKey: value.apiKey ?? '',
+      imageModels: normalizeImageModels(value.imageModels),
+      promptApiUrl: value.promptApiUrl ?? '',
+      promptApiKey: value.promptApiKey ?? '',
+      promptModel: value.promptModel ?? '',
     }
   }
 
+  // Browser endpoints and Agent tools share the exact same serial queue. This
+  // keeps image persistence, cancellation, and retries coherent across both
+  // entry points while a tool call itself returns immediately with a task id.
+  const runtime = new ImageGenerationRuntime(() => {
+    const value = resolve()
+    return { apiUrl: value.apiUrl, apiKey: value.apiKey }
+  })
+
   // The route family mounts once, gated on the settings seam (the bridge
   // serves it; without the seam there is nothing to expose). Route handlers
   // read resolve() per request, so config edits apply live. The settings
@@ -104,6 +150,16 @@ export function apply(ctx: Context, config?: Config): void {
             const value = resolve()
             return { apiUrl: value.apiUrl, apiKey: value.apiKey }
           },
+          resolvePrompt: () => {
+            const value = resolve()
+            return {
+              apiUrl: value.promptApiUrl.trim() || value.apiUrl,
+              apiKey: value.promptApiKey.trim() || value.apiKey,
+              model: value.promptModel,
+            }
+          },
+          resolveImageModels: () => resolve().imageModels,
+          runtime,
         })
         const disposers = routes.map(route => ctx.webServer.register(route))
         return () => { for (const dispose of disposers) dispose() }
@@ -112,6 +168,19 @@ export function apply(ctx: Context, config?: Config): void {
     )
   })
 
+  ctx.inject(['tools', 'attachments'], (tctx) => {
+    tctx.effect(() => registerAgentImageTools(tctx, runtime, () => {
+      const value = resolve()
+      return {
+        enabled: value.enabled,
+        allowAgentImageGeneration: value.allowAgentImageGeneration,
+        apiUrl: value.apiUrl,
+        apiKey: value.apiKey,
+        imageModels: value.imageModels,
+      }
+    }), 'dsh-imagegen: agent image tools')
+  })
+
   // System-prompt announcement (toggled by settings changes).
   let disposeSection: (() => void) | undefined
   const sync = (): void => {
@@ -124,7 +193,7 @@ export function apply(ctx: Context, config?: Config): void {
     disposeSection = ctx.systemPrompt.section({
       name: 'plugin:dsh-imagegen',
       order: SECTION_ORDER,
-      text: IMAGEGEN_GUIDANCE,
+      text: guidanceFor(value.imageModels),
     })
   }
 

package/src/prompt-enhancer.ts

@@ -0,0 +1,79 @@
+/** OpenAI-compatible chat helpers used by the optional prompt-enhancement UI. */
+
+export interface PromptModelConfig {
+  apiUrl: string
+  apiKey: string
+  model: string
+}
+
+/** Credentials shared by OpenAI-compatible `/models` discovery. */
+export interface ModelListConfig {
+  apiUrl: string
+  apiKey: string
+}
+
+function endpoint(base: string, suffix: string): string {
+  return `${base.replace(/\/+$/, '')}${suffix}`
+}
+
+function headers(apiKey: string): HeadersInit {
+  return {
+    'content-type': 'application/json',
+    ...apiKey.trim() === '' ? {} : { authorization: `Bearer ${apiKey.trim()}` },
+  }
+}
+
+async function responseJson(response: Response): Promise<Record<string, unknown>> {
+  const body: unknown = await response.json().catch(() => undefined)
+  if (!response.ok || body === undefined || body === null || typeof body !== 'object') {
+    const message = body !== null && typeof body === 'object' && typeof (body as { error?: { message?: unknown } }).error?.message === 'string'
+      ? (body as { error: { message: string } }).error.message
+      : `HTTP ${response.status}`
+    throw new Error(message)
+  }
+  return body as Record<string, unknown>
+}
+
+/** List candidates exposed by an OpenAI-compatible endpoint. */
+export async function listOpenAIModels(config: ModelListConfig): Promise<string[]> {
+  if (config.apiUrl.trim() === '') throw new Error('API URL is required')
+  const response = await fetch(endpoint(config.apiUrl, '/models'), { headers: headers(config.apiKey) })
+  const body = await responseJson(response)
+  const data = Array.isArray(body.data) ? body.data : []
+  return [...new Set(data
+    .flatMap(item => item !== null && typeof item === 'object' && typeof (item as { id?: unknown }).id === 'string' ? [(item as { id: string }).id.trim()] : [])
+    .filter(Boolean))]
+    .sort((a, b) => a.localeCompare(b))
+}
+
+/** List chat models exposed by an OpenAI-compatible endpoint. */
+export async function listPromptModels(config: PromptModelConfig): Promise<string[]> {
+  return listOpenAIModels(config)
+}
+
+/** Expand a concise image request into a production-ready image prompt. */
+export async function enhancePrompt(config: PromptModelConfig, prompt: string): Promise<string> {
+  if (config.apiUrl.trim() === '' || config.model.trim() === '') throw new Error('prompt enhancement model is not configured')
+  const response = await fetch(endpoint(config.apiUrl, '/chat/completions'), {
+    method: 'POST',
+    headers: headers(config.apiKey),
+    body: JSON.stringify({
+      model: config.model.trim(),
+      temperature: 0.7,
+      messages: [
+        {
+          role: 'system',
+          content: 'You are an expert image-prompt editor. Expand the user request into one vivid, specific image-generation prompt. Preserve intent and language. Add only useful visual detail: subject, composition, lighting, materials, color, camera/style and quality. Return only the finished prompt, with no preface or markdown.',
+        },
+        { role: 'user', content: prompt },
+      ],
+    }),
+  })
+  const body = await responseJson(response)
+  const choices = Array.isArray(body.choices) ? body.choices : []
+  const content = choices[0] !== null && typeof choices[0] === 'object'
+    ? (choices[0] as { message?: { content?: unknown } }).message?.content
+    : undefined
+  if (typeof content !== 'string' || content.trim() === '') throw new Error('chat model returned an empty prompt')
+  return content.trim()
+}

package/src/protocol.ts

@@ -8,7 +8,7 @@
 export const IMAGEGEN_SETTINGS_NAMESPACE = 'dsh-imagegen'
 
 /** Published package version shared by the host updater and the client UI. */
-export const PLUGIN_VERSION = '1.0.20'
+export const PLUGIN_VERSION = '1.2.0'
 
 /** Same-origin route family (loopback-only, mirroring the dsh-ssh fence). */
 export const SETTINGS_API = {
@@ -19,6 +19,25 @@ export const SETTINGS_API = {
 /** The image-generation proxy route. */
 export const GENERATE_API = '/api/dsh-imagegen/generate'
 
+/** Host-mediated OpenAI-compatible prompt enhancement endpoints. */
+export const PROMPT_ENHANCE_API = {
+  models: '/api/dsh-imagegen/prompt-enhance/models',
+  enhance: '/api/dsh-imagegen/prompt-enhance',
+} as const
+
+/** Host-mediated candidate discovery for the configured image API. */
+export const IMAGE_MODEL_API = {
+  models: '/api/dsh-imagegen/image-models',
+} as const
+
+/** Host-resident generation queue endpoints. */
+export const TASK_API = {
+  submit: '/api/dsh-imagegen/tasks/submit',
+  list: '/api/dsh-imagegen/tasks/list',
+  cancel: '/api/dsh-imagegen/tasks/cancel',
+  retry: '/api/dsh-imagegen/tasks/retry',
+} as const
+
 /** Host-mediated GitHub Release update routes. */
 export const UPDATE_API = {
   check: '/api/dsh-imagegen/update/check',
@@ -49,6 +68,7 @@ export const GALLERY_API = {
   append: '/api/dsh-imagegen/gallery/append',
   remove: '/api/dsh-imagegen/gallery/remove',
   clear: '/api/dsh-imagegen/gallery/clear',
+  tags: '/api/dsh-imagegen/gallery/tags',
   image: '/api/dsh-imagegen/gallery/image',
 } as const
 
@@ -122,7 +142,7 @@ export interface GenerateRequest {
   mode: GenerateMode
   /** Upstream model name, e.g. gpt-image-2. */
   model: string
-  /** The prompt (up to 2000 chars in the UI). */
+  /** The prompt. Upstream providers may impose their own length limits. */
   prompt: string
   /** Canvas size as an aspect ratio: 'auto' or e.g. '1:1' / '16:9' / '21:9'.
    *  The host maps it onto each model's own vocabulary (aspect_ratio for Grok,
@@ -165,6 +185,19 @@ export interface GenerateResult {
   historyError?: string
 }
 
+export type GenerationTaskStatus = 'queued' | 'running' | 'completed' | 'failed' | 'cancelled'
+
+export interface GenerationTask {
+  id: string
+  request: GenerateRequest
+  status: GenerationTaskStatus
+  createdAt: number
+  startedAt?: number
+  finishedAt?: number
+  result?: GenerateResult
+  error?: string
+}
+
 /** GitHub Release update information shown by the client. */
 export interface UpdateInfo {
   currentVersion: string
@@ -198,6 +231,8 @@ export interface HistoryEntry {
   images: HistoryImageRef[]
   /** Reference-image filename (edit mode), kept for display only. */
   refName?: string
+  /** User-managed gallery labels (unused by history entries). */
+  tags?: string[]
 }
 
 /** A history entry the client submits for persistence (images still carry base64). */