WRITE ACTION — builds, modifies, or fixes an EXISTING project with
a natural-language instruction. Use ONLY when the user clearly asks
for a change ("add X", "fix Y", "change the theme"). If the user is
only asking for advice, analysis, review, or suggestions ("what
could be improved?", "review my bot"), do NOT call this — answer
from the project's info instead; a review request is not an edit.
Describe ONLY the desired change — DreamAgent's AI automatically
handles code, tests, rebuild, and redeployment. Completed changes
are saved and committed automatically.
ASYNCHRONOUS: returns immediately with the session_key; monitor
with dreamagent_get_edit_progress (or dreamagent_get_chat_status
with the returned session key) until a terminal state. Report
success only after run_status reaches 'completed'. Edits consume
the user's AI credits.
ERRORS (actual returns): failures come back as text starting with
'ERROR:'. If the edit was rejected before starting, the text says
'the edit was NOT started' plus the reason — HTTP 402 insufficient
credits, 409 another edit already active, 423 session lock held by
another session, 404 wrong project id, 401 no account connected.
Treat the edit as failed/cancelled only when a status tool says so.
ONE EDIT AT A TIME: never start another modification on the same
project while one is running — check progress first and wait.
SUPERPOWERS: projects can use the account's enabled AI tools
(song/video/image generation, voiceover, lip sync, voice clone,
transcription, media processing, PDF tools). If the user asks to
add or use one ("add song generation", "generate an image feature"),
simply include that in the message — DreamAgent's agent knows the
enabled tools and wires the integration, UI and job handling
automatically. Check the catalog with dreamagent_list_superpowers;
if a tool is disabled, direct the user to dreamagent.cloud ->
Superpowers to enable it first.