comfyui_o1key/docs/decisions/0005-persistent-image-job-history-summaries.md

0005: Persistent image-job history summaries

• Status: Accepted
• Date: 2026-09-04
• Owners: Maintainers

Context

Panel-triggered o1key image jobs do not pass through ComfyUI's native prompt executor. Their native task-queue rows are virtual records assembled by the frontend from the process-local ParallelImageJobManager. Restarting ComfyUI clears both that manager and the browser bridge, so completed o1key rows disappear even though their saved images remain.

Output-directory scanning cannot rebuild a complete history: users may choose custom prefixes, natural-number naming, subfolders, or absolute destinations. Persisting entire job snapshots would retain prompts and manifests that the history UI does not need.

Decision

Persist at most 200 terminal job summaries in <ComfyUI user directory>/o1key/image_job_history.json using atomic replacement. A summary contains only batch and node IDs, terminal state, counts, millisecond timestamps, bounded error/warning fields, failed request indexes, and sanitized ComfyUI image descriptors.

Expose the summaries through GET /o1key/image/jobs/history. The frontend loads up to 64 recent records before returning its first merged native history page. POST /o1key/image/jobs/history synchronizes single deletion and clear-history actions. History write failures are non-fatal to generation and image saving.

Consequences

• Completed, failed, and cancelled o1key rows survive ComfyUI and browser restarts.
• History remains available independently of the currently loaded workflow and output naming rule.
• Prompts, reference manifests, provider bodies, absolute paths, credentials, Base64 data, and signed URLs are intentionally unrecoverable from the history index.
• Existing rows created before this decision cannot be reconstructed reliably and begin appearing only after the first new terminal job is indexed.

Alternatives considered

• Scan output filenames at startup. Rejected because supported naming and destination choices do not preserve batch identity.
• Persist complete JobRecord objects. Rejected because prompts, manifests, and transient execution data exceed the history UI's needs and security boundary.
• Store only in browser local storage. Rejected because it is browser-profile-specific and does not survive browser data clearing or serve multiple connected clients consistently.

Validation

• tests/test_o1key_image_jobs.py recreates the store from disk, verifies terminal manager persistence, and checks that prompt, Base64, and signed URL fields are absent.
• tests/test_o1key_image_generator_frontend.mjs verifies first-page hydration into native history and independent concurrent retry-batch lifetime.