@dickpy/dsh-imagegen 1.0.19 → 1.1.0

package/src/index.ts

@@ -26,7 +26,7 @@ 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 { 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'
 
@@ -43,6 +43,12 @@ export interface Config {
   apiUrl?: string
   /** Bearer API key (stored as a secret field on the settings seam). */
   apiKey?: 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({
@@ -50,6 +56,9 @@ export const Config: z<Config> = z.object({
   announceToAgent: z.boolean().default(true),
   apiUrl: z.string().default(''),
   apiKey: z.string().role('secret').default(''),
+  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). */
@@ -68,6 +77,9 @@ interface EffectiveConfig {
   announceToAgent: boolean
   apiUrl: string
   apiKey: string
+  promptApiUrl: string
+  promptApiKey: string
+  promptModel: string
 }
 
 /**
@@ -86,6 +98,9 @@ export function apply(ctx: Context, config?: Config): void {
       announceToAgent: value.announceToAgent ?? DEFAULT_ANNOUNCE,
       apiUrl: value.apiUrl ?? '',
       apiKey: value.apiKey ?? '',
+      promptApiUrl: value.promptApiUrl ?? '',
+      promptApiKey: value.promptApiKey ?? '',
+      promptModel: value.promptModel ?? '',
     }
   }
 
@@ -104,6 +119,14 @@ 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,
+            }
+          },
         })
         const disposers = routes.map(route => ctx.webServer.register(route))
         return () => { for (const dispose of disposers) dispose() }

package/src/prompt-enhancer.ts

@@ -0,0 +1,67 @@
+/** OpenAI-compatible chat helpers used by the optional prompt-enhancement UI. */
+
+export interface PromptModelConfig {
+  apiUrl: string
+  apiKey: string
+  model: 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 chat models exposed by an OpenAI-compatible endpoint. */
+export async function listPromptModels(config: PromptModelConfig): Promise<string[]> {
+  if (config.apiUrl.trim() === '') throw new Error('prompt enhancement 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 data
+    .flatMap(item => item !== null && typeof item === 'object' && typeof (item as { id?: unknown }).id === 'string' ? [(item as { id: string }).id] : [])
+    .sort((a, b) => a.localeCompare(b))
+}
+
+/** 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.19'
+export const PLUGIN_VERSION = '1.1.0'
 
 /** Same-origin route family (loopback-only, mirroring the dsh-ssh fence). */
 export const SETTINGS_API = {
@@ -19,6 +19,20 @@ 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-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 +63,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 +137,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 +180,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 +226,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). */

package/src/routes.ts

@@ -10,11 +10,13 @@ import { randomUUID } from 'node:crypto'
 import type { WebRoute } from '@deepseek-ai/dsh-host-webserver'
 import { SettingsConflictError, settingsNamespace, type SettingsDescriptor } from '@deepseek-ai/dsh-settings'
 import { generateImage, type UpstreamConfig } from './engine.ts'
+import { enhancePrompt, listPromptModels, type PromptModelConfig } from './prompt-enhancer.ts'
+import { GenerationTaskQueue } from './task-queue.ts'
 import { appendHistory, clearHistory, listHistory, readHistoryImage, removeHistory } from './history-store.ts'
-import { appendGallery, clearGallery, listGallery, readGalleryImage, removeGallery } from './gallery-store.ts'
+import { appendGallery, clearGallery, listGallery, readGalleryImage, removeGallery, updateGalleryTags } from './gallery-store.ts'
 import { listTemplates, readTemplateImage, refreshTemplates } from './templates-store.ts'
 import { checkForUpdate, CURRENT_VERSION, installUpdate } from './updater.ts'
-import { GALLERY_API, GENERATE_API, HISTORY_API, IMAGEGEN_SETTINGS_NAMESPACE, SETTINGS_API, TEMPLATES_API, UPDATE_API, type GeneratedImage, type GenerateRequest, type HistoryEntry, type HistoryEntryInput, type TemplateListResult, type TemplateRefreshResult } from './protocol.ts'
+import { GALLERY_API, GENERATE_API, HISTORY_API, IMAGEGEN_SETTINGS_NAMESPACE, PROMPT_ENHANCE_API, SETTINGS_API, TASK_API, TEMPLATES_API, UPDATE_API, type GeneratedImage, type GenerateRequest, type HistoryEntry, type HistoryEntryInput, type TemplateListResult, type TemplateRefreshResult } from './protocol.ts'
 
 /** Cap on JSON request bodies (settings ops and generate payloads are small). */
 const MAX_JSON_BODY_BYTES = 24 * 1024 * 1024
@@ -35,6 +37,8 @@ export interface ImageGenRoutesDeps {
   settings: SettingsSeam
   /** Resolve the current upstream config (composition entry + settings). */
   resolve: () => UpstreamConfig
+  /** Resolve the optional chat-model configuration for prompt enhancement. */
+  resolvePrompt?: () => PromptModelConfig
   /** Overrideable history backend, primarily for host integration tests. */
   history?: {
     list: () => Promise<HistoryEntry[]>
@@ -49,6 +53,7 @@ export interface ImageGenRoutesDeps {
     append: (entry: HistoryEntryInput) => Promise<{ entries: HistoryEntry[]; added: boolean }>
     remove: (id: string) => Promise<HistoryEntry[]>
     clear: () => Promise<HistoryEntry[]>
+    updateTags?: (id: string, tags: string[]) => Promise<HistoryEntry[]>
     readImage: (file: string) => Promise<{ data: Buffer; mime: string } | undefined>
   }
   /** Overrideable template-library backend, primarily for host integration tests. */
@@ -112,6 +117,22 @@ function messageOf(error: unknown): string {
   return error instanceof Error ? error.message : String(error)
 }
 
+function parseGenerateRequest(body: Record<string, unknown>): GenerateRequest | undefined {
+  const prompt = typeof body.prompt === 'string' ? body.prompt.trim() : ''
+  if (prompt === '') return undefined
+  return {
+    mode: body.mode === 'edit' ? 'edit' : 'text',
+    model: typeof body.model === 'string' ? body.model : 'gpt-image-2',
+    prompt,
+    size: typeof body.size === 'string' ? body.size : 'auto',
+    quality: typeof body.quality === 'string' ? body.quality : 'auto',
+    n: typeof body.n === 'number' ? body.n : 1,
+    detail: typeof body.detail === 'string' ? body.detail : '',
+    ...typeof body.image === 'string' && body.image !== '' ? { image: body.image } : {},
+    ...typeof body.refName === 'string' && body.refName !== '' ? { refName: body.refName } : {},
+  }
+}
+
 /** Validate a submitted history entry (images carry base64). */
 function parseHistoryEntryInput(body: Record<string, unknown>): HistoryEntryInput | undefined {
   const raw = body.entry
@@ -199,11 +220,12 @@ export function makeRoutes(deps: ImageGenRoutesDeps): WebRoute[] {
     clear: clearHistory,
     readImage: readHistoryImage,
   }
-  const gallery = deps.gallery ?? {
+  const gallery: NonNullable<ImageGenRoutesDeps['gallery']> = deps.gallery ?? {
     list: listGallery,
     append: appendGallery,
     remove: removeGallery,
     clear: clearGallery,
+    updateTags: updateGalleryTags,
     readImage: readGalleryImage,
   }
   const templates = deps.templates ?? {
@@ -211,6 +233,29 @@ export function makeRoutes(deps: ImageGenRoutesDeps): WebRoute[] {
     refresh: refreshTemplates,
     readImage: readTemplateImage,
   }
+  const resolvePrompt = deps.resolvePrompt ?? (() => ({ apiUrl: '', apiKey: '', model: '' }))
+  const runGeneration = async (request: GenerateRequest, signal?: AbortSignal) => {
+    const result = await generateImage(deps.resolve(), request, { signal })
+    try {
+      const entries = await 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: entries }
+    } catch (error) {
+      return { ...result, historyError: messageOf(error) }
+    }
+  }
+  const taskQueue = new GenerationTaskQueue((request, signal) => runGeneration(request, signal))
   const guard = (req: IncomingMessage, res: ServerResponse, method: string): boolean => {
     if (!isLoopbackRequest(req)) {
       writeJson(res, 403, { error: 'forbidden: loopback-only' })
@@ -224,6 +269,37 @@ export function makeRoutes(deps: ImageGenRoutesDeps): WebRoute[] {
   }
 
   return [
+    // ----------------------------------------------- prompt enhancement
+    {
+      kind: 'exact',
+      path: PROMPT_ENHANCE_API.models,
+      handler: async (req, res) => {
+        if (!guard(req, res, 'POST')) return
+        try {
+          writeJson(res, 200, { ok: true, models: await listPromptModels(resolvePrompt()) })
+        } catch (error) {
+          writeJson(res, 200, { ok: false, code: 'prompt-models-failed', message: messageOf(error) })
+        }
+      },
+    },
+    {
+      kind: 'exact',
+      path: PROMPT_ENHANCE_API.enhance,
+      handler: async (req, res) => {
+        if (!guard(req, res, 'POST')) return
+        const body = await readJsonBody(req)
+        const prompt = typeof body?.prompt === 'string' ? body.prompt.trim() : ''
+        if (prompt === '') {
+          writeJson(res, 200, { ok: false, code: 'bad-request', message: 'prompt is required' })
+          return
+        }
+        try {
+          writeJson(res, 200, { ok: true, prompt: await enhancePrompt(resolvePrompt(), prompt) })
+        } catch (error) {
+          writeJson(res, 200, { ok: false, code: 'prompt-enhance-failed', message: messageOf(error) })
+        }
+      },
+    },
     // -------------------------------------------------- settings describe
     {
       kind: 'exact',
@@ -284,46 +360,13 @@ export function makeRoutes(deps: ImageGenRoutesDeps): WebRoute[] {
           writeJson(res, 200, { ok: false, code: 'bad-request', message: 'unreadable JSON body' })
           return
         }
-        const prompt = typeof body.prompt === 'string' ? body.prompt.trim() : ''
-        if (prompt === '') {
+        const request = parseGenerateRequest(body)
+        if (request === undefined) {
           writeJson(res, 200, { ok: false, code: 'bad-request', message: 'prompt is required' })
           return
         }
-        if (prompt.length > 2000) {
-          writeJson(res, 200, { ok: false, code: 'bad-request', message: 'prompt exceeds 2000 characters' })
-          return
-        }
-        const request: GenerateRequest = {
-          mode: body.mode === 'edit' ? 'edit' : 'text',
-          model: typeof body.model === 'string' ? body.model : 'gpt-image-2',
-          prompt,
-          size: typeof body.size === 'string' ? body.size : 'auto',
-          quality: typeof body.quality === 'string' ? body.quality : 'auto',
-          n: typeof body.n === 'number' ? body.n : 1,
-          detail: typeof body.detail === 'string' ? body.detail : '',
-          ...typeof body.image === 'string' && body.image !== '' ? { image: body.image } : {},
-          ...typeof body.refName === 'string' && body.refName !== '' ? { refName: body.refName } : {},
-        }
         try {
-          const result = await generateImage(deps.resolve(), request)
-          try {
-            const entries = await 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 },
-            })
-            writeJson(res, 200, { ok: true, ...result, history: entries })
-          } catch (error) {
-            writeJson(res, 200, { ok: true, ...result, historyError: messageOf(error) })
-          }
+          writeJson(res, 200, { ok: true, ...await runGeneration(request) })
         } catch (error) {
           const message = error instanceof Error ? error.message : String(error)
           const code = error instanceof Error && 'code' in error && typeof (error as { code?: unknown }).code === 'string'
@@ -333,6 +376,41 @@ export function makeRoutes(deps: ImageGenRoutesDeps): WebRoute[] {
         }
       },
     },
+    // ------------------------------------------------ generation task queue
+    {
+      kind: 'exact', path: TASK_API.submit,
+      handler: async (req, res) => {
+        if (!guard(req, res, 'POST')) return
+        const body = await readJsonBody(req)
+        const request = body === undefined ? undefined : parseGenerateRequest(body)
+        if (request === undefined) { writeJson(res, 200, { ok: false, code: 'bad-request', message: 'prompt is required' }); return }
+        writeJson(res, 200, { ok: true, task: taskQueue.submit(request) })
+      },
+    },
+    {
+      kind: 'exact', path: TASK_API.list,
+      handler: async (req, res) => { if (!guard(req, res, 'POST')) return; writeJson(res, 200, { ok: true, tasks: taskQueue.list() }) },
+    },
+    {
+      kind: 'exact', path: TASK_API.cancel,
+      handler: async (req, res) => {
+        if (!guard(req, res, 'POST')) return
+        const body = await readJsonBody(req)
+        const task = typeof body?.id === 'string' ? taskQueue.cancel(body.id) : undefined
+        if (task === undefined) { writeJson(res, 200, { ok: false, code: 'not-found', message: 'task not found' }); return }
+        writeJson(res, 200, { ok: true, task })
+      },
+    },
+    {
+      kind: 'exact', path: TASK_API.retry,
+      handler: async (req, res) => {
+        if (!guard(req, res, 'POST')) return
+        const body = await readJsonBody(req)
+        const task = typeof body?.id === 'string' ? taskQueue.retry(body.id) : undefined
+        if (task === undefined) { writeJson(res, 200, { ok: false, code: 'not-found', message: 'task not found' }); return }
+        writeJson(res, 200, { ok: true, task })
+      },
+    },
     // ----------------------------------------------- update check
     {
       kind: 'exact',
@@ -528,6 +606,22 @@ export function makeRoutes(deps: ImageGenRoutesDeps): WebRoute[] {
         }
       },
     },
+    // ----------------------------------------------------- gallery tags
+    {
+      kind: 'exact',
+      path: GALLERY_API.tags,
+      handler: async (req, res) => {
+        if (!guard(req, res, 'POST')) return
+        const body = await readJsonBody(req)
+        const id = typeof body?.id === 'string' ? body.id : ''
+        const tags = Array.isArray(body?.tags) ? body.tags.filter((tag): tag is string => typeof tag === 'string') : undefined
+        if (id === '' || tags === undefined || gallery.updateTags === undefined) {
+          writeJson(res, 200, { ok: false, code: 'bad-request', message: 'gallery id and tags are required' })
+          return
+        }
+        try { writeJson(res, 200, { ok: true, entries: await gallery.updateTags(id, tags) }) } catch (error) { writeJson(res, 200, { ok: false, code: 'gallery-failed', message: messageOf(error) }) }
+      },
+    },
     // ---------------------------------------------------- gallery clear
     {
       kind: 'exact',

package/src/task-queue.ts

@@ -0,0 +1,70 @@
+/** In-memory, host-resident image generation queue. */
+
+import { randomUUID } from 'node:crypto'
+import type { GenerateRequest, GenerateResult, GenerationTask } from './protocol.ts'
+
+export class GenerationTaskQueue {
+  private readonly tasks: GenerationTask[] = []
+  private readonly controllers = new Map<string, AbortController>()
+  private running = false
+
+  constructor(private readonly run: (request: GenerateRequest, signal: AbortSignal) => Promise<GenerateResult>) {}
+
+  list(): GenerationTask[] {
+    return this.tasks.map(task => ({ ...task, request: { ...task.request }, ...(task.result === undefined ? {} : { result: task.result }) }))
+  }
+
+  submit(request: GenerateRequest): GenerationTask {
+    const task: GenerationTask = { id: randomUUID(), request: { ...request }, status: 'queued', createdAt: Date.now() }
+    this.tasks.unshift(task)
+    void this.drain()
+    return task
+  }
+
+  cancel(id: string): GenerationTask | undefined {
+    const task = this.tasks.find(item => item.id === id)
+    if (task === undefined || task.status === 'completed' || task.status === 'failed' || task.status === 'cancelled') return task
+    task.status = 'cancelled'
+    task.finishedAt = Date.now()
+    this.controllers.get(id)?.abort()
+    return task
+  }
+
+  retry(id: string): GenerationTask | undefined {
+    const previous = this.tasks.find(item => item.id === id)
+    return previous === undefined ? undefined : this.submit(previous.request)
+  }
+
+  private async drain(): Promise<void> {
+    if (this.running) return
+    this.running = true
+    try {
+      for (;;) {
+        const task = this.tasks.find(item => item.status === 'queued')
+        if (task === undefined) return
+        task.status = 'running'
+        task.startedAt = Date.now()
+        const controller = new AbortController()
+        this.controllers.set(task.id, controller)
+        try {
+          const result = await this.run(task.request, controller.signal)
+          if (this.tasks.find(item => item.id === task.id)?.status !== 'cancelled') {
+            task.status = 'completed'
+            task.result = result
+            task.finishedAt = Date.now()
+          }
+        } catch (error) {
+          if (this.tasks.find(item => item.id === task.id)?.status !== 'cancelled') {
+            task.status = 'failed'
+            task.error = error instanceof Error ? error.message : String(error)
+            task.finishedAt = Date.now()
+          }
+        } finally {
+          this.controllers.delete(task.id)
+        }
+      }
+    } finally {
+      this.running = false
+    }
+  }
+}