@goodandready/dsh-image-gen 0.11.0 → 0.11.2

package/lib/index.js

@@ -14,8 +14,8 @@
 
 import z from '@deepseek-ai/schemastery'
 import { credentialRef } from '@deepseek-ai/dsh-credentials'
-import { mkdir, readFile, writeFile } from 'node:fs/promises'
-import { enforceSecurePermissions, isTrustedLocalRequest } from './security.js'
+import { readFile } from 'node:fs/promises'
+import { isTrustedLocalRequest } from './security.js'
 import { saveAndAttachResult } from './attachment-helper.js'
 import {
   historyFile,
@@ -28,8 +28,7 @@ import {
   writeHistory,
   filterHistory,
 } from './history.js'
-import { existsSync, unlinkSync } from 'node:fs'
-import os from 'node:os'
+import { existsSync } from 'node:fs'
 import path from 'node:path'
 import {
   IMAGE_SIZES,
@@ -38,16 +37,16 @@ import {
   buildSidecar,
   normalizeMediaType,
   resolveApiKeyCandidates,
-  toLosslessJson,
-  saveAttachmentSafe,
   testProviderConnection,
 } from './providers.js'
 
-import { buildDualOutputMarkdown, resolveConversationImage, analyzeImageWithVision } from './resolve-image.js'
+import { resolveConversationImage, analyzeImageWithVision } from './resolve-image.js'
 import { registerAllTools } from './register-tools.js'
 import { registerPluginUpdater } from './updater.js'
 import { registerVaultRoutes } from './vault.js'
-
+import { registerSettingsRoutes } from './settings-route.js'
+import { clearAllAnchors } from './anchor-helpers.js'
+import { resetLoopGuard, getLoopGuardState } from './loop-guard.js'
 
 export { IMAGE_SIZES, OUTPUT_FORMATS, PROVIDER_KEYS, buildSidecar, normalizeMediaType, resolveConversationImage, analyzeImageWithVision }
 export { saveAndAttachResult }
@@ -63,13 +62,6 @@ export {
   filterHistory,
 }
 
-
-/**
- * Saves generated asset to workspace, registers with attachments, and returns Dual-Output (#150).
- */
-
-
-
 export const name = '@goodandready/dsh-image-gen'
 
 /** Settings namespace the Web card edits. */
@@ -80,45 +72,62 @@ const NS = 'dsh-image-gen'
 const LEGACY_NS = 'dsh-fal-image-gen'
 export const inject = ['tools', 'attachments', 'credentials', 'webServer', 'settings', 'llm', 'systemPrompt']
 
+// Polyfill for .volatile() schema annotation if runtime schemastery lacks it (#295)
+if (typeof z.prototype?.volatile !== 'function') {
+  z.prototype.volatile = function volatile() {
+    if (this.meta && this.meta.volatile) throw new TypeError('volatile schema is already wrapped')
+    return typeof this.extra === 'function' ? this.extra('volatile', true) : this
+  }
+}
+
 export const Config = z.object({
   enabled: z
     .boolean()
     .description('Master switch for image generation. When false, tools refuse to execute.')
-    .default(true),
+    .default(true)
+    .volatile(),
   provider: z
     .string()
     .description(`Which provider generates the image. One of: ${PROVIDER_KEYS.join(', ')}. `
       + '"fal" uses the FAL queue below; "custom" uses the OpenAI-compatible API configured under it.')
-    .default('fal'),
+    .default('fal')
+    .volatile(),
   model: z
     .string()
     .description('FAL model id, called as {baseURL}/{model}.')
-    .default('fal-ai/flux-2/klein/9b'),
+    .default('fal-ai/flux-2/klein/9b')
+    .volatile(),
   apiKeyEnv: z
     .string()
     .role('credential-ref')
     .description('Credential reference / env var holding the FAL API key (the "Key " auth prefix is added automatically when missing).')
-    .default('FAL_API_KEY'),
+    .default('FAL_API_KEY')
+    .volatile(),
   baseURL: z
     .string()
     .description('FAL queue base URL.')
-    .default('https://queue.fal.run'),
+    .default('https://queue.fal.run')
+    .volatile(),
   defaultSize: z
     .string()
     .description(`Default image size when the tool call omits image_size. One of: ${IMAGE_SIZES.join(', ')}.`)
-    .default('landscape_4_3'),
+    .default('landscape_4_3')
+    .volatile(),
   defaultFormat: z
     .string()
     .description(`Default output format. One of: ${OUTPUT_FORMATS.join(', ')}.`)
-    .default('png'),
+    .default('png')
+    .volatile(),
   pollIntervalMs: z
     .number()
     .description('Status polling interval in milliseconds.')
-    .default(2000),
+    .default(2000)
+    .volatile(),
   timeoutMs: z
     .number()
     .description('Total generation timeout in milliseconds (submit + poll + download).')
-    .default(180000),
+    .default(180000)
+    .volatile(),
   deliverAs: z
     .string()
     .description(
@@ -126,151 +135,216 @@ export const Config = z.object({
       + '"link": the tool returns a link and the card renders the picture from it — the chat model only ever sees text, so this works with any model. '
       + '"image": the tool returns the image itself — the picture is part of the result, which a text-only chat model cannot read, so this mode needs dsh-vision-bridge (or a vision-capable chat model).'
     )
-    .default('link'),
+    .default('link')
+    .volatile(),
   customBaseURL: z
     .string()
     .description('provider=custom: API root without a trailing slash, e.g. https://api.openai.com/v1. '
       + 'The request goes to {customBaseURL}/images/generations.')
-    .default(''),
+    .default('')
+    .volatile(),
   customModel: z
     .string()
     .description('provider=custom: model id, e.g. gpt-image-1.')
-    .default(''),
+    .default('')
+    .volatile(),
   customKeyEnv: z
     .string()
     .role('credential-ref')
     .description('provider=custom: credential reference / env var holding the API key. '
       + 'Empty means no authorization header, for gateways that need none.')
-    .default('OPENAI_API_KEY'),
+    .default('OPENAI_API_KEY')
+    .volatile(),
 
   replicateModel: z
     .string()
     .description('provider=replicate: model identifier on Replicate.')
-    .default('black-forest-labs/flux-schnell'),
+    .default('black-forest-labs/flux-schnell')
+    .volatile(),
   replicateKeyEnv: z
     .string()
     .role('credential-ref')
     .description('provider=replicate: credential reference / env var holding API token.')
-    .default('REPLICATE_API_TOKEN'),
+    .default('REPLICATE_API_TOKEN')
+    .volatile(),
 
   subscriptionQuality: z
     .string()
     .description('provider=codex or grok: quality asked of the subscription — low, medium, high or empty '
       + 'for the provider default.')
-    .default(''),
+    .default('')
+    .volatile(),
   customSize: z
     .string()
     .description('provider=custom: fixed size sent to the API, e.g. 1024x1024. '
       + 'Empty means the named size is translated automatically — set this only for an API picky about sizes.')
-    .default(''),
+    .default('')
+    .volatile(),
   localKind: z
     .string()
     .description('provider=local: which local API to use — "comfyui" or "a1111".')
-    .default('comfyui'),
+    .default('comfyui')
+    .volatile(),
   localBaseURL: z
     .string()
     .description('provider=local: server address, e.g. http://127.0.0.1:8188 (ComfyUI) or http://127.0.0.1:7860 (A1111).')
-    .default(''),
+    .default('')
+    .volatile(),
   localModel: z
     .string()
     .description('provider=local: model id (A1111) or workflow/schema name (ComfyUI). Empty means the server default.')
-    .default(''),
+    .default('')
+    .volatile(),
   localSteps: z
     .number()
     .description('provider=local: sampling steps.')
-    .default(20),
+    .default(20)
+    .volatile(),
   localCfg: z
     .number()
     .description('provider=local: CFG scale.')
-    .default(7),
+    .default(7)
+    .volatile(),
   seedreamBaseURL: z
     .string()
     .description('provider=seedream: base URL, e.g. https://api.bytedanceapi.com/v1 or Volcengine Ark.')
-    .default('https://api.bytedanceapi.com/v1'),
+    .default('https://api.bytedanceapi.com/v1')
+    .volatile(),
   seedreamKeyEnv: z
     .string()
     .role('credential-ref')
     .description('provider=seedream: credential reference / env var holding the API key.')
-    .default('SEEDREAM_API_KEY'),
+    .default('SEEDREAM_API_KEY')
+    .volatile(),
   seedreamModel: z
     .string()
     .description('provider=seedream: model id, e.g. seedream-4.0.')
-    .default('seedream-4.0'),
+    .default('seedream-4.0')
+    .volatile(),
   geminiKeyEnv: z
     .string()
     .role('credential-ref')
     .description('provider=gemini: credential reference / env var holding the Google API key.')
-    .default('GEMINI_API_KEY'),
+    .default('GEMINI_API_KEY')
+    .volatile(),
   geminiModel: z
     .string()
     .description('provider=gemini: model id, e.g. gemini-2.0-flash-exp-image-generation.')
-    .default('gemini-2.0-flash-exp-image-generation'),
+    .default('gemini-2.0-flash-exp-image-generation')
+    .volatile(),
   outputDir: z
     .string()
     .description('Where generated images are saved. A relative path resolves against the session working directory; an absolute path is used as given.')
-    .default('generated/images'),
+    .default('generated/images')
+    .volatile(),
   historyLimit: z
     .number()
     .description('How many recent generations to keep in the in-memory history list.')
-    .default(50),
+    .default(50)
+    .volatile(),
   pruneDays: z
     .number()
     .description('Delete generated files and history entries older than this many days. 0 (default) disables pruning.')
-    .default(0),
+    .default(0)
+    .volatile(),
   enhancePrompt: z
     .boolean()
     .description('Expand a short prompt into a detailed one through the chat model before generating. Off by default.')
-    .default(false),
+    .default(false)
+    .volatile(),
   enhanceModel: z
     .string()
     .description('Model used to enhance the prompt. Empty means the same model that leads the conversation.')
-    .default(''),
+    .default('')
+    .volatile(),
   autoEnhancePrompt: z
     .boolean()
     .description('Enrich prompts with photography, lighting, and composition quality tokens.')
-    .default(false),
+    .default(false)
+    .volatile(),
   defaultStylePreset: z
     .string()
     .description('Default style preset applied to generations (e.g. cinematic, anime, photorealistic).')
-    .default('none'),
+    .default('none')
+    .volatile(),
   enhanceBelowChars: z
     .number()
     .description('Only enhance prompts shorter than this many characters.')
-    .default(200),
+    .default(200)
+    .volatile(),
   stylePreset: z
     .string()
     .description('Optional style suffix appended to the prompt before generation. Empty (default) means no style is applied and the prompt is used as-is.')
-    .default(''),
+    .default('')
+    .volatile(),
   cacheBySeed: z
     .boolean()
     .description('If the same seed+prompt was already generated (present in history), return the cached result instead of generating again. Off by default.')
-    .default(false),
+    .default(false)
+    .volatile(),
   cacheByPrompt: z
     .boolean()
     .description('If the same prompt was already generated (present in history), return the cached result instead of generating again. Off by default.')
-    .default(false),
+    .default(false)
+    .volatile(),
   qualityGate: z
     .boolean()
     .description('Automatic quality gate with silent re-roll for blank or defective frames. On by default.')
-    .default(true),
+    .default(true)
+    .volatile(),
   dailyBudgetUsd: z
     .number()
     .description('Daily image generation spending budget in USD. 0 (default) disables limit enforcement.')
-    .default(0),
+    .default(0)
+    .volatile(),
   loopGuardLimit: z
     .number()
     .description('Maximum consecutive image generations per session without user interaction. 0 disables protection.')
-    .default(3),
+    .default(3)
+    .volatile(),
   diskCache: z
     .boolean()
     .description('Content-addressed disk caching for identical generations (<50ms retrieval, zero API cost). On by default.')
-    .default(true),
+    .default(true)
+    .volatile(),
   fallbackProviders: z
     .array(z.string())
     .description('Ordered list of fallback providers to cascade to if the primary encounters 429, 5xx, or quota limits.')
-    .default([]),
+    .default([])
+    .volatile(),
 })
 
+function isVolatileRef(value) {
+  return !!value && typeof value === 'object' && !Array.isArray(value) && typeof value.get === 'function'
+}
+
+export function plainConfig(cfg) {
+  if (isVolatileRef(cfg)) return plainConfig(cfg.get())
+  if (!cfg || typeof cfg !== 'object') return cfg
+  const out = {}
+  for (const key of Object.keys(cfg)) {
+    const value = cfg[key]
+    out[key] = isVolatileRef(value) ? value.get() : value
+  }
+  return out
+}
+
+export function volatileConfig(cfg) {
+  const plain = plainConfig(cfg)
+  if (!plain || typeof plain !== 'object') return plain
+  const out = {}
+  for (const [key, field] of Object.entries(Config.dict || {})) {
+    if (field?.meta?.volatile && Object.hasOwn(plain, key)) {
+      out[key] = plain[key]
+    }
+  }
+  return out
+}
+
+export function publicConfig(cfg) {
+  return plainConfig(cfg)
+}
+
 /** Keep a file stem safe for the filesystem. */
 /** Read source image for editing: filesystem path or attachment id. */
 export async function resolveSource(ctx, exec, ref) {
@@ -308,43 +382,33 @@ export async function resolveApiKey(ctx, ref) {
     try {
       const resolved = await ctx.credentials.resolve(credentialRef(candidate))
       if (resolved && resolved.value) return resolved.value
-    } catch {
-      // fall through to the environment
+    } catch (_) {
+      // Credential reference not found in service, try next candidate
     }
-    const fromEnv = process.env[candidate]
-    if (fromEnv) return fromEnv
+    const envVal = process.env[candidate]
+    if (envVal) return envVal
   }
-  throw new Error(
-    `API key not configured: set credential/env "${ref}" (Web: Settings → Credentials, or add "${ref}: <key>" to $DSH_HOME/.credentials.yaml)`,
-  )
+  return ''
 }
 
 /**
- * Migrate settings from legacy plugin name.
- *
- * Uses raw user layer: default values do not need migration,
- * distinguishable only from user overrides. If settings are already configured
- * under the new namespace, preserve them as newer choices.
- *
- * The legacy block is left untouched in settings to avoid unexpected deletions.
- * and causes no conflict with the active namespace.
+ * If the user configured the plugin under its old name (dsh-fal-image-gen), copy
+ * those settings forward into dsh-image-gen once so existing keys and choices
+ * are preserved. Only touches values that the user actually modified.
  */
 function migrateLegacySettings(sctx, scope) {
   try {
-    const readSection = sctx.settings.section
-    if (typeof readSection !== 'function') return
-    const legacy = readSection.call(sctx.settings, LEGACY_NS)
-    if (!legacy || typeof legacy !== 'object' || Object.keys(legacy).length === 0) return
-    const mine = readSection.call(sctx.settings, NS)
-    if (mine && typeof mine === 'object' && Object.keys(mine).length > 0) return
+    if (!scope || typeof scope.update !== 'function') return
+    const legacyScope = sctx.settings.get?.(LEGACY_NS)
+    if (!legacyScope) return
+    const legacy = legacyScope.get?.()
+    if (!legacy || typeof legacy !== 'object') return
     scope.update(structuredClone(legacy))
-  } catch (cannotMigrate) {
-    // Settings migration skipped — fallback to default schema configuration,
-    // and user may configure settings via UI card. No crash required.
+  } catch (_) {
+    // Settings migration skipped — fallback to default schema configuration
   }
 }
 
-/** History directory: persists across restarts. */
 /** Collect text chunks from llm.stream iterator. */
 export async function collectText(iterable) {
   let out = ''
@@ -389,12 +453,13 @@ export async function enhancePrompt(ctx, cfg, prompt, signal, provider) {
     const text = await collectText(chunks)
     if (!text) return { prompt, enhanced: false }
     return { prompt: text, enhanced: true }
-  } catch (e) {
+  } catch (_) {
     return { prompt, enhanced: false }
   }
 }
 
-export function apply(ctx, config) {
+export function apply(ctx, rawConfig) {
+  const config = Config(rawConfig ?? {})
   if (ctx.systemPrompt && typeof ctx.systemPrompt.section === 'function') {
     ctx.systemPrompt.section({
       name: 'tool:image-generation',
@@ -406,29 +471,79 @@ export function apply(ctx, config) {
     })
   }
 
-
-  // The Web card edits this namespace; without registering it the card binds to
-  // a namespace nobody declared, stays unready and renders nothing — which is
-  // why the plugin's settings tab was empty. Reading through getConfig() also
-  // means an edit applies to the next call instead of after a restart.
-  let getConfig = () => config
-  const live = () => Config(structuredClone(getConfig() ?? {})) ?? config
+  let settingsApi
+  let currentLiveConfig = null
+  let getConfig = () => currentLiveConfig || config
+  const live = () => Config(structuredClone(plainConfig(getConfig() ?? {}))) ?? config
+
+  const createSettingsAdapter = (svc) => {
+    if (!svc) return undefined
+    if (typeof svc.replace === 'function' || typeof svc.update === 'function' || typeof svc.mutate === 'function') {
+      const getRevision = () => {
+        try {
+          return svc.describe?.().find((row) => row.ns === NS)?.revision
+        } catch (_) {
+          return undefined
+        }
+      }
+      return {
+        get: () => live(),
+        replace: async (next) => {
+          const parsed = Config(structuredClone(plainConfig(next)))
+          currentLiveConfig = parsed
+          const payload = volatileConfig(parsed)
+          if (typeof svc.replace === 'function') {
+            await svc.replace(NS, payload, getRevision())
+          } else if (typeof svc.update === 'function') {
+            await svc.update(NS, payload, getRevision())
+          }
+          return parsed
+        },
+        update: async (patch) => {
+          const merged = Config({ ...publicConfig(live()), ...plainConfig(patch) })
+          currentLiveConfig = merged
+          const payload = volatileConfig(merged)
+          if (typeof svc.update === 'function') {
+            await svc.update(NS, payload, getRevision())
+          } else if (typeof svc.replace === 'function') {
+            await svc.replace(NS, payload, getRevision())
+          }
+          return merged
+        },
+        watch: (cb) => {
+          if (typeof svc.watch === 'function') return svc.watch(cb)
+          return () => {}
+        },
+      }
+    }
+    return undefined
+  }
 
   ctx.inject(['settings'], (sctx) => {
-    const scope = sctx.settings.register(NS, Config, { base: config })
-    migrateLegacySettings(sctx, scope)
-    getConfig = () => (scope?.get?.() ?? config) ?? config
-    sctx.effect(() => () => {
-      getConfig = () => config
-    })
+    if (typeof sctx.settings?.register === 'function') {
+      const scope = sctx.settings.register(NS, Config, { base: config })
+      settingsApi = scope
+      migrateLegacySettings(sctx, scope)
+      getConfig = () => (scope?.get?.() ?? config) ?? config
+      sctx.effect(() => () => {
+        getConfig = () => config
+        settingsApi = undefined
+      })
+    } else {
+      settingsApi = createSettingsAdapter(sctx.settings)
+      if (typeof sctx.settings?.describe === 'function') {
+        try {
+          sctx.settings.describe(NS, Config)
+        } catch (_) { /* bestEffort */ }
+      }
+      sctx.effect(() => () => {
+        getConfig = () => config
+        settingsApi = undefined
+      })
+    }
   })
 
-  // Serve the stored image so the tool card can show it inline. Tool cards do
-  // not render image blocks — only assistant messages do — so the picture a
-  // tool produces needs a URL of its own.
-  //
-  // Ids are content-addressed (`sha256:<hex>`), the store verifies them, and
-  // the route is same-origin like every other plugin route.
+  // Serve the stored image so the tool card can show it inline.
   const imageHandler = (() => {
     return async (req, res) => {
       if (req.method !== 'GET' && req.method !== 'HEAD') {
@@ -448,47 +563,37 @@ export function apply(ctx, config) {
         res.end(JSON.stringify({ error: 'bad attachment id' }))
         return
       }
-      // The store verifies the whole reference, not just the id: mediaType,
-      // byte count and dimensions must match what it probes from the bytes.
-      // The tool result carries all of them, so the card sends them back.
-      // Nothing is gained by forging them — the bytes are still verified
-      // against the sha256 in the id, and a mismatch is simply a 404.
-      const rawBytes = Number(query.get('b'))
-      const rawW = Number(query.get('w'))
-      const rawH = Number(query.get('h'))
-      const safeBytes = Number.isFinite(rawBytes) && rawBytes >= 0 ? rawBytes : 0
-      const safeW = Number.isFinite(rawW) && rawW >= 0 ? rawW : 0
-      const safeH = Number.isFinite(rawH) && rawH >= 0 ? rawH : 0
-
-      const ref = {
-        attachmentId: id,
-        mediaType: query.get('mt') || 'image/png',
-        bytes: safeBytes,
-        width: safeW,
-        height: safeH,
-      }
+
+      const mediaType = query.get('mediaType') ?? 'image/png'
+      const bytes = Number(query.get('bytes') ?? 0)
+      const width = Number(query.get('width') ?? 0)
+      const height = Number(query.get('height') ?? 0)
+
       try {
-        if (!ctx.attachments || typeof ctx.attachments.readImage !== 'function') {
-          res.writeHead(404, { 'Content-Type': 'application/json' })
-          res.end(JSON.stringify({ error: 'attachment service unavailable' }))
-          return
-        }
-        const stored = await ctx.attachments.readImage(ref)
+        const stored = await ctx.attachments.readImage({
+          attachmentId: id,
+          mediaType,
+          bytes,
+          width,
+          height,
+        })
         res.writeHead(200, {
-          'Content-Type': stored.ref?.mediaType || 'image/png',
-          // Content-addressed: the bytes behind an id never change.
+          'Content-Type': stored.ref?.mediaType || mediaType,
+          'Content-Length': stored.data.byteLength,
           'Cache-Control': 'public, max-age=31536000, immutable',
         })
+        if (req.method === 'HEAD') {
+          res.end()
+          return
+        }
         res.end(Buffer.isBuffer(stored.data) ? stored.data : Buffer.from(stored.data))
-      } catch (error) {
+      } catch (_) {
         res.writeHead(404, { 'Content-Type': 'application/json' })
-        res.end(JSON.stringify({ error: 'image not found or reference mismatch' }))
+        res.end(JSON.stringify({ error: 'attachment not found' }))
       }
     }
   })()
 
-  // Two routes, one handler: new route for new messages, legacy route for
-  // backward compatibility with conversation history.
   for (const path of ['/dsh-image-gen/image', '/dsh-fal-image-gen/image']) {
     ctx.effect(() => ctx.webServer.register({
       kind: 'exact',
@@ -497,7 +602,14 @@ export function apply(ctx, config) {
     }), `dsh-image-gen: image route ${path}`)
   }
 
-    // One-click plugin updater route per DSH standard
+  // Settings REST routes (#295)
+  registerSettingsRoutes(ctx, {
+    live,
+    getSettingsApi: () => settingsApi,
+    setLiveConfig: (c) => { currentLiveConfig = c },
+  })
+
+  // One-click plugin updater route per DSH standard
   ctx.effect(() => registerPluginUpdater(ctx, {
     endpoint: '/api/dsh-image-gen/update',
     packageName: '@goodandready/dsh-image-gen',
@@ -525,12 +637,13 @@ export function apply(ctx, config) {
         const deps = {
           fetchImpl: fetch,
           resolveKey: (ref) => resolveApiKey(ctx, ref),
-          cfg: (typeof getConfig === "function") ? getConfig() : config,
+          cfg: (typeof getConfig === 'function') ? getConfig() : config,
           ctx,
         }
         const result = await testProviderConnection(deps, provider)
+        const guardState = getLoopGuardState(provider)
         res.writeHead(200, { 'Content-Type': 'application/json' })
-        res.end(JSON.stringify({ provider, ...result }))
+        res.end(JSON.stringify({ provider, loopGuard: guardState, ...result }))
       } catch (err) {
         res.writeHead(500, { 'Content-Type': 'application/json' })
         res.end(JSON.stringify({ ok: false, error: err.message }))
@@ -570,6 +683,12 @@ export function apply(ctx, config) {
   // Vault route (#159)
   registerVaultRoutes(ctx)
 
+  // Session and cache teardown cleanup effect
+  ctx.effect(() => () => {
+    clearAllAnchors()
+    resetLoopGuard()
+  }, 'dsh-image-gen: session cleanup')
+
   // Tool registrations live in register-tools.js; each tool is a labeled ctx.effect (#216).
   registerAllTools(ctx, {
     config,
@@ -579,5 +698,4 @@ export function apply(ctx, config) {
     slugify,
     resolveApiKey,
   })
-
 }