Initial TrueGrowth source import

openspec/changes/archive/2026-04-29-add-gpt-image-edit-support/design.md

@@ -0,0 +1,79 @@
+## Context
+
+The first GPT Image compatibility phase added profile-level image API compatibility and a dedicated official generation schema:
+
+- `openai.image.gpt-generation-json` -> `/images/generations`
+- `openai.image.basic-json` -> existing default compatibility adapter
+
+The second phase needs `/images/edits`, but the project still has only one image task surface and one image adapter method. A broad image operation abstraction would be cleaner long-term, but too large for this step.
+
+## Goals / Non-Goals
+
+- Goals:
+  - Support official GPT Image image-to-image/edit requests.
+  - Reuse existing `TaskType.IMAGE` queue/history/canvas flows.
+  - Keep basic Tuzi/OpenAI-compatible behavior unchanged.
+  - Avoid routing by model ID alone.
+- Non-Goals:
+  - No new task type.
+  - No new public MCP tool name.
+  - No full mask drawing UI in this phase.
+
+## Decisions
+
+- Decision: Add an edit request schema instead of a new task type.
+
+  The schema is the existing adapter handoff point. It lets the routing layer choose official generation vs official edit while keeping task plumbing stable.
+
+- Decision: Add planner-level schema preference.
+
+  The same model/profile can have both generation and edit bindings. Runtime request shape, not model ID, decides which binding is appropriate.
+
+- Decision: Use multipart edit requests for the official GPT Image adapter.
+
+  The official `/images/edits` examples use file-style form fields such as `image[]=@...`. The adapter converts the existing canvas data URLs or fetchable image references to `Blob`s, appends them as `image[]`, and lets `fetch` set the multipart boundary.
+
+## Runtime Flow
+
+```text
+Image task
+  -> extract reference images
+  -> decide preferred schema:
+       no references -> openai.image.gpt-generation-json
+       references/mask/edit mode -> openai.image.gpt-edit-form
+  -> resolve invocation plan with preferred schema
+  -> resolve adapter from binding
+  -> gpt-image-adapter sends /images/generations or /images/edits
+```
+
+If the preferred edit schema is unavailable, planning falls back to the highest-priority image binding. That preserves Tuzi/basic compatibility.
+
+## Request Fields
+
+Extend `ImageGenerationRequest` with lightweight edit semantics:
+
+```ts
+type ImageGenerationMode = 'text_to_image' | 'image_to_image' | 'image_edit';
+
+interface ImageGenerationRequest {
+  generationMode?: ImageGenerationMode;
+  referenceImages?: string[];
+  maskImage?: string;
+  inputFidelity?: 'high' | 'low';
+}
+```
+
+Official edit multipart fields:
+
+```text
+model=gpt-image-1.5
+prompt=...
+image[]=@image-1.png
+mask=@mask.png
+input_fidelity=high
+size=1024x1024
+```
+
+## Rollback
+
+Switching a profile from `openai-gpt-image` to `tuzi-compatible` or `openai-compatible-basic` returns reference-image requests to the default adapter compatibility path.