---
{
  "id": "platform.image_editor.session-flow-and-lifecycle",
  "topic": "image_editor",
  "title": "Image Editor session flow and lifecycle",
  "locale": "en",
  "version": "2026-07-24",
  "summary": "Follow the live-session sequence and preserve the browser selection, history, disconnection, and export semantics.",
  "content": "Use `list_sessions` → `select_region` → `request_edit` → optional `undo` → `export`. `list_sessions` exposes only sessions explicitly granted to this Agent that still pass the image-project write check, with context such as `projectId` and `fileKey`. A region uses normalized 0..1 coordinates relative to the visible canvas, not pixels. `select_region` clears and replaces the entire mask, including a user's hand-painted selection; ask before replacing a selection the user may want to keep.\n\n`request_edit` consumes the mask at command execution time. The current browser rejects it with `selection_required` when no selection exists; treat the returned browser reason as runtime truth. A successful edit is loaded into the visible canvas, added to browser history, and advances the image project's current revision. Do not store the full prompt in knowledge or routing telemetry; the editor action redacts `arguments.prompt`.\n\n`undo` is one step in the shared browser canvas history and can therefore undo the user's own latest operation. At the history floor it silently changes nothing while still returning `{undone:true}`. There is no Agent redo action, and undo does not refund a completed edit. `export` renders the current canvas as PNG, uploads it as a new image-project revision managed through File Center, and returns `imageKey` and `assetUrl`; it does not post an image into the conversation.\n\nClosing or disconnecting the browser invalidates the session. For “session is not open” or “disconnected,” call `list_sessions` again instead of retrying the old ID. Distinguish not found, grant required, disconnected conflict, action timeout, and a browser rejection with its reason, such as `missing_region` or `selection_required`. Revoke and takeover cancellations are terminal for that grant, not retry signals.\n",
  "aliases": [
    "image edit flow",
    "select region",
    "inpaint selection",
    "editor undo",
    "export edited image",
    "局部重繪"
  ],
  "tags": [
    "image-editor",
    "session-flow",
    "lifecycle",
    "selection",
    "undo",
    "export"
  ],
  "relatedActions": [
    "arinova.image_editor.list_sessions",
    "arinova.image_editor.select_region",
    "arinova.image_editor.request_edit",
    "arinova.image_editor.undo",
    "arinova.image_editor.export"
  ],
  "relatedActionPrefixes": [],
  "url": "https://docs.arinova.ai/en/kb/image_editor/session-flow-and-lifecycle/"
}
---

Use `list_sessions` → `select_region` → `request_edit` → optional `undo` → `export`. `list_sessions` exposes only sessions explicitly granted to this Agent that still pass the image-project write check, with context such as `projectId` and `fileKey`. A region uses normalized 0..1 coordinates relative to the visible canvas, not pixels. `select_region` clears and replaces the entire mask, including a user's hand-painted selection; ask before replacing a selection the user may want to keep.

`request_edit` consumes the mask at command execution time. The current browser rejects it with `selection_required` when no selection exists; treat the returned browser reason as runtime truth. A successful edit is loaded into the visible canvas, added to browser history, and advances the image project's current revision. Do not store the full prompt in knowledge or routing telemetry; the editor action redacts `arguments.prompt`.

`undo` is one step in the shared browser canvas history and can therefore undo the user's own latest operation. At the history floor it silently changes nothing while still returning `{undone:true}`. There is no Agent redo action, and undo does not refund a completed edit. `export` renders the current canvas as PNG, uploads it as a new image-project revision managed through File Center, and returns `imageKey` and `assetUrl`; it does not post an image into the conversation.

Closing or disconnecting the browser invalidates the session. For “session is not open” or “disconnected,” call `list_sessions` again instead of retrying the old ID. Distinguish not found, grant required, disconnected conflict, action timeout, and a browser rejection with its reason, such as `missing_region` or `selection_required`. Revoke and takeover cancellations are terminal for that grant, not retry signals.