imagegen-smarto 0.1.4 → 0.2.1

package/README.md

@@ -85,13 +85,17 @@ After installation, use the profile that points requests to SmartO. The skill
 is configured for implicit invocation, so an image request can be written in
 natural language without first typing `$imagegen-smarto`.
 
-## How image generation works
+## Image generation workflow
 
-When the skill is triggered, Codex runs the installed `imagegen-smarto`
-command. The command reads the active provider URL, model, and Codex
-credential, sends a streaming Responses request with the SmartO marker, parses
-the returned `image_generation_call`, and saves the PNG locally. It prints an
-absolute `IMAGE_MARKDOWN=...` line so Codex can display the result inline.
+When the skill is triggered, Codex first turns the request into the same kind
+of structured, production-oriented prompt used by the official image skill.
+Detailed prompts are preserved and normalized; generic prompts receive only
+useful composition or presentation detail. Edits explicitly lock the parts
+that must remain unchanged.
+
+Codex then runs the installed `imagegen-smarto` command. The command uses the
+active SmartO provider and credential, saves the returned PNG locally, and
+prints an absolute `IMAGE_MARKDOWN=...` line so Codex can display it inline.
 
 You can also test the execution path directly:
 
@@ -107,9 +111,15 @@ imagegen-smarto generate \
   --image /absolute/path/to/source.png
 ```
 
-The command always uses `stream=true` internally because the relay requires
-streaming for image generation. The skill does not need to describe or modify
-the relay request body.
+The command handles its relay protocol internally; the skill only prepares the
+final image prompt, supplies reference-image paths, and consumes the returned
+image result.
+
+While the relay is producing an image, the command writes a periodic status
+heartbeat with elapsed time to stderr. This is a waiting indicator, not an
+upstream completion percentage. The final `IMAGE_PATH=` and `IMAGE_MARKDOWN=`
+records remain on stdout. Pass `--quiet` to suppress status messages while
+keeping those final records.
 
 ## Local profile switch
 

package/bin/generate.js

@@ -8,6 +8,17 @@ const path = require('node:path')
 
 const IMAGEGEN_MARKER = '__CODEX_VPS_IMAGEGEN__'
 const DEFAULT_TIMEOUT_MS = 10 * 60 * 1000
+const DEFAULT_PROGRESS_INTERVAL_MS = 15 * 1000
+
+function progressIntervalMs() {
+  const configured = Number(process.env.IMAGEGEN_SMARTO_PROGRESS_INTERVAL_MS)
+  if (Number.isFinite(configured) && configured > 0) return configured
+  return DEFAULT_PROGRESS_INTERVAL_MS
+}
+
+function reportProgress(message, quiet) {
+  if (!quiet) console.error(`imagegen-smarto: ${message}`)
+}
 
 function printGenerateHelp() {
   console.log(`imagegen-smarto generate - generate or edit an image through the active relay
@@ -23,6 +34,7 @@ Options:
   --model <model>       Override the model from Codex config
   --base-url <url>      Override the active provider base URL
   --timeout <seconds>   Request timeout (default: 600)
+  --quiet                Suppress status messages (final paths still print)
   --help                Show this help`)
 }
 
@@ -34,6 +46,7 @@ function parseGenerateArgs(argv) {
     model: null,
     baseUrl: null,
     timeoutMs: DEFAULT_TIMEOUT_MS,
+    quiet: false,
   }
   const positional = []
 
@@ -84,6 +97,11 @@ function parseGenerateArgs(argv) {
       continue
     }
 
+    if (arg === '--quiet') {
+      options.quiet = true
+      continue
+    }
+
     if (arg.startsWith('-')) {
       throw new Error(`unknown option: ${arg}`)
     }
@@ -273,7 +291,7 @@ function outputPathForIndex(requestedPath, index) {
   return `${base.slice(0, -extension.length)}-${index + 1}${extension}`
 }
 
-async function requestImage({ prompt, images, output, model, baseUrl, timeoutMs }) {
+async function requestImage({ prompt, images, output, model, baseUrl, timeoutMs, quiet }) {
   const codexHome = resolveCodexHome()
   const active = readActiveProviderConfig(codexHome)
   const apiKey = readApiKey(codexHome)
@@ -290,6 +308,14 @@ async function requestImage({ prompt, images, output, model, baseUrl, timeoutMs
   }
   const controller = new AbortController()
   const timeout = setTimeout(() => controller.abort(), timeoutMs)
+  const startedAt = Date.now()
+  const interval = progressIntervalMs()
+  const elapsedSeconds = () => Math.floor((Date.now() - startedAt) / 1000)
+  const progressTimer = setInterval(() => {
+    reportProgress(`still waiting for the image relay (${elapsedSeconds()}s elapsed)`, quiet)
+  }, interval)
+  const clearProgress = () => clearInterval(progressTimer)
+  reportProgress('starting image generation', quiet)
   let response
   try {
     response = await fetch(normalizeResponsesUrl(baseUrl || active.baseUrl), {
@@ -303,37 +329,52 @@ async function requestImage({ prompt, images, output, model, baseUrl, timeoutMs
     })
   } catch (error) {
     clearTimeout(timeout)
+    clearProgress()
     if (error.name === 'AbortError') throw new Error(`image request timed out after ${timeoutMs / 1000}s`)
     throw new Error(`cannot reach the image relay: ${error.message}`)
   }
 
   if (!response.ok) {
     clearTimeout(timeout)
+    clearProgress()
     const errorText = (await response.text()).slice(0, 2000)
     throw new Error(`image relay returned HTTP ${response.status}: ${errorText}`)
   }
   if (!response.body) {
     clearTimeout(timeout)
+    clearProgress()
     throw new Error('image relay returned no response body')
   }
 
+  reportProgress('relay connected; waiting for streamed image result', quiet)
+
   const results = []
   let relayError = null
   let buffer = ''
+  let reader = null
+  let streamDone = false
+  let resultReported = false
   const decoder = new TextDecoder()
   const onEvent = (event) => {
     relayError ||= extractError(event)
     const item = event.type === 'response.output_item.done' ? event.item : null
     if (item?.type === 'image_generation_call' && item.result) {
       results.push(item.result)
+      if (!resultReported) {
+        resultReported = true
+        reportProgress(`image result received after ${elapsedSeconds()}s; finishing response`, quiet)
+      }
     }
   }
 
   try {
-    const reader = response.body.getReader()
+    reader = response.body.getReader()
     while (true) {
       const { value, done } = await reader.read()
-      if (done) break
+      if (done) {
+        streamDone = true
+        break
+      }
       buffer += decoder.decode(value, { stream: true })
       buffer = consumeSseText(buffer, onEvent)
     }
@@ -346,6 +387,21 @@ async function requestImage({ prompt, images, output, model, baseUrl, timeoutMs
     throw new Error(`failed while reading the image relay response: ${error.message}`)
   } finally {
     clearTimeout(timeout)
+    clearProgress()
+    if (reader && !streamDone) {
+      try {
+        await reader.cancel()
+      } catch {
+        // The original request error is more useful than cleanup failures.
+      }
+    }
+    if (reader) {
+      try {
+        reader.releaseLock()
+      } catch {
+        // The stream may already have released the lock after an abort.
+      }
+    }
   }
 
   if (relayError) throw new Error(relayError)
@@ -360,6 +416,7 @@ async function requestImage({ prompt, images, output, model, baseUrl, timeoutMs
     fs.writeFileSync(filePath, decodeImageResult(results[index]), { mode: 0o600 })
     paths.push(filePath)
   }
+  reportProgress(`saved ${paths.length} image${paths.length === 1 ? '' : 's'} in ${elapsedSeconds()}s`, quiet)
   return paths
 }
 
@@ -381,6 +438,7 @@ async function generateImage(argv) {
     model: options.model,
     baseUrl: options.baseUrl,
     timeoutMs: options.timeoutMs,
+    quiet: options.quiet,
   })
   for (const filePath of paths) {
     console.log(`IMAGE_PATH=${filePath}`)

package/imagegen-smarto/SKILL.md

@@ -1,27 +1,51 @@
 ---
 name: imagegen-smarto
-description: Use the active SmartO relay to actually create or edit images. Trigger immediately for any request to create, draw, generate, modify, transform, or redesign a picture, including text-to-image (文生图), image-to-image (图生图), and image generation inside another workflow. Do not trigger for viewing, analyzing, describing, or recognizing an existing image, or for ordinary non-image tasks.
+description: Use the active SmartO relay to create or edit raster images. Trigger immediately for requests to create, draw, generate, modify, transform, or redesign a picture, including text-to-image (文生图), image-to-image (图生图), and image generation inside another workflow. Do not trigger for viewing, analyzing, describing, or recognizing an existing image, ordinary non-image tasks, or output better produced as SVG or code-native graphics.
 ---
 
 # SmartO image generation
 
-When this skill triggers, execute the installed `imagegen-smarto` command. The
-command is the image-generation entry point: it sends the request to the active
-Codex provider, adds the SmartO marker internally, keeps streaming enabled, and
-saves the returned image locally. Do not stop after reading this file and do
-not try to change the outer Codex request yourself.
+Use `imagegen-smarto generate` to produce the requested image. The command is
+the image-generation tool for this skill; execute it instead of stopping after
+reading these instructions.
 
-For a text-to-image request, run:
+## Workflow
 
-```sh
-imagegen-smarto generate --prompt "<the user's complete image prompt>"
-```
+1. Decide whether this is generation or an edit. Treat supplied images as edit
+   inputs only when the user asks to change or combine them; otherwise label
+   their reference role in the prompt.
+2. Rewrite the user's request into a strong image prompt using
+   [references/prompting.md](references/prompting.md). Preserve all explicit
+   requirements. Normalize detailed prompts; augment generic prompts only when
+   the addition materially improves the result.
+3. Generate one requested asset or variant per command:
 
-Preserve the user's complete prompt and edit instructions. For image-to-image
-requests, pass each available reference image as `--image <absolute-path>`.
-The command can be repeated for multiple requested outputs.
+   ```sh
+   imagegen-smarto generate --prompt "<final structured prompt>"
+   ```
 
-After the command succeeds, use every printed `IMAGE_MARKDOWN=...` line in the
-response so the generated file is displayed as an image. Do not replace the
-image with a textual description. If the command fails, report its actual error
-instead of claiming that an image was generated.
+4. For an edit, add each available source or reference image by absolute path.
+   Up to five images may be supplied:
+
+   ```sh
+   imagegen-smarto generate --prompt "<final structured edit prompt>" \
+     --image /absolute/path/to/input.png
+   ```
+
+5. If the user named an output location, pass `--output <path>`. Do not
+   overwrite an existing asset unless replacement was explicitly requested.
+6. Keep the default status heartbeat while the relay is working. Image
+   generation can take a minute or more; silence is not evidence of failure.
+   If another tool wrapper yields while the command is still running, wait for
+   the process to finish instead of interrupting it. Use `--quiet` only when a
+   caller needs machine-clean stderr.
+7. On success, include every printed `IMAGE_MARKDOWN=...` value in the answer
+   so Codex displays the generated file. Report the saved path. For a failed
+   command, report the actual error and do not claim that an image exists.
+
+The CLI writes status heartbeats to stderr and keeps the final `IMAGE_PATH=`
+and `IMAGE_MARKDOWN=` records on stdout. The heartbeat reports elapsed waiting
+time; it is not an upstream completion percentage or a health guarantee.
+
+For edits, state invariants explicitly in the prompt: `change only X; keep Y
+unchanged`. When iterating, make one targeted change and repeat the invariants.

package/imagegen-smarto/references/prompting.md

@@ -0,0 +1,99 @@
+# Image prompting
+
+Shape the user's request into a concise production-oriented specification.
+Use only the lines that improve the request; the schema is scaffolding, not a
+form that must always be filled.
+
+## Specificity
+
+- If the prompt is already detailed, preserve it and only normalize its order
+  and wording.
+- If the prompt is generic, add tasteful composition, framing, intended-use,
+  polish, or scene detail when it materially improves the output.
+- Do not invent extra characters, props, brands, slogans, palettes, or story
+  beats. Do not choose arbitrary left/right placement without layout context.
+- Keep exact user constraints and requested text unchanged.
+
+## Prompt structure
+
+For complex requests, use short labeled lines in this order:
+
+```text
+Use case: <taxonomy slug>
+Asset type: <where the image will be used> (optional)
+Primary request: <the user's main request>
+Input images: <Image 1: role; Image 2: role> (optional)
+Scene/backdrop: <environment>
+Subject: <main subject and important details>
+Style/medium: <photo, illustration, 3D, etc.>
+Composition/framing: <viewpoint, crop, placement, negative space>
+Lighting/mood: <lighting and atmosphere>
+Color palette: <requested or implied palette>
+Materials/textures: <important surface detail>
+Text (verbatim): "<exact text>"
+Constraints: <must preserve and must include>
+Avoid: <negative constraints>
+```
+
+Simple requests can remain short. Add only the fields needed to clarify the
+result.
+
+## Use-case taxonomy
+
+Generation:
+
+- `photorealistic-natural`: candid or editorial scenes with natural lighting
+  and real texture.
+- `product-mockup`: product, packaging, catalog, or merchandise imagery.
+- `ui-mockup`: practical app or web interface imagery at a stated fidelity.
+- `infographic-diagram`: structured diagrams with explicit layout and labels.
+- `scientific-educational`: accurate teaching visuals for a named audience.
+- `ads-marketing`: campaign imagery with audience, positioning, and exact copy.
+- `productivity-visual`: slides, charts, workflows, and business visuals.
+- `logo-brand`: simple, scalable mark exploration with a strong silhouette.
+- `illustration-story`: comics, children's art, and narrative scenes.
+- `stylized-concept`: style-driven concept art or rendered scenes.
+- `historical-scene`: period-specific scenes requiring factual accuracy.
+
+Editing:
+
+- `text-localization`: replace only in-image text and preserve layout.
+- `identity-preserve`: preserve face, body, pose, hair, and expression.
+- `precise-object-edit`: replace or remove a named element only.
+- `lighting-weather`: change environmental conditions while preserving content.
+- `background-extraction`: create a clean transparent-background cutout.
+- `style-transfer`: apply reference style without introducing extra elements.
+- `compositing`: combine indexed inputs with matched scale, light, perspective.
+- `sketch-to-render`: preserve layout, proportions, and perspective.
+
+## Composition and realism
+
+- Specify framing and viewpoint only when useful: close-up, full body, wide,
+  eye-level, low-angle, top-down.
+- Call out negative space when the image must leave room for UI or copy.
+- For people, clarify body framing, gaze, pose, and object interactions when
+  they matter.
+- For photorealism, explicitly request photorealism and concrete natural detail
+  such as skin texture, fabric wear, material grain, and imperfect surfaces.
+
+## Edits and references
+
+- Label every supplied image by index and role: edit target, style reference,
+  composition reference, or compositing input.
+- For edits, use `change only X; keep Y unchanged` and list all invariants.
+- For compositing, state what moves from each indexed image and require matched
+  lighting, perspective, and scale.
+- Repeat invariants on every edit iteration to reduce drift.
+
+## Text in images
+
+- Quote exact text, require verbatim rendering, and specify typography and
+  placement when those details matter.
+- Spell uncommon words letter by letter when accuracy is critical.
+- Require no extra characters or text beyond the supplied copy.
+
+## Iteration
+
+Start with a clean base prompt. Inspect the result against subject, style,
+composition, exact text, invariants, and avoid items. Refine with one targeted
+change at a time instead of rewriting unrelated parts of the prompt.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "imagegen-smarto",
-  "version": "0.1.4",
+  "version": "0.2.1",
   "description": "Install the imagegen-smarto Codex skill on Windows and Linux.",
   "bin": {
     "imagegen-smarto": "bin/cli.js"
@@ -11,7 +11,8 @@
     "README.md"
   ],
   "scripts": {
-    "postinstall": "node bin/cli.js install --postinstall"
+    "postinstall": "node bin/cli.js install --postinstall",
+    "test": "node --test"
   },
   "engines": {
     "node": ">=18"