Skip to content

Commit 216f064

Browse files
steipetesteipete
committed
fix: route media completions through requester agent
1 parent beb6652 commit 216f064

19 files changed

Lines changed: 1048 additions & 116 deletions

‎AGENTS.md‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -227,6 +227,7 @@ Skills own workflows; root owns hard policy and routing.
227227
- Parallels: `$openclaw-parallels-smoke`; Discord roundtrip: `$parallels-discord-roundtrip`.
228228
- Crabbox/WebVNC human demos: keep remote desktop visible/windowed; no fullscreen remote browser unless video/capture-style output.
229229
- ClawSweeper ops: `$clawsweeper`. Deployed hook sessions may post one concise `#clawsweeper` note only when surprising/actionable/risky; if using message tool, reply exactly `NO_REPLY`.
230+
- Generated-media completions wake the requester agent first. Requester visible-reply config decides final text vs message tool; direct media send is fallback/recovery only.
230231
- Memory wiki prompt digest stays tiny; prefer `wiki_search` / `wiki_get`; verify contact data before use; source-class provenance for generated people facts.
231232
- Rebrand/migration/config warnings: run `openclaw doctor`.
232233
- Never edit `node_modules`.

‎docs/automation/tasks.md‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -102,7 +102,7 @@ Not every agent run creates a task. Heartbeat turns and normal interactive chat
102102
<Accordion title="Notify defaults for cron and media">
103103
Main-session cron tasks use `silent` notify policy by default - they create records for tracking but do not generate notifications. Isolated cron tasks also default to `silent` but are more visible because they run in their own session.
104104

105-
Session-backed `image_generate`, `music_generate`, and `video_generate` runs also use `silent` notify policy. They still create task records, but completion is handed back to the original agent session as an internal wake so the agent can write the follow-up message and attach the finished media itself. Generated-media completion events require message-tool delivery: the agent must send the finished media with the `message` tool, then reply `NO_REPLY`. If the requester session is no longer active or its active wake fails, and the completion agent misses some or all generated media, OpenClaw sends an idempotent direct fallback with only the missing media to the original channel target.
105+
Session-backed `image_generate`, `music_generate`, and `video_generate` runs also use `silent` notify policy. They still create task records, but completion is handed back to the original agent session as an internal wake so the agent can write the follow-up message and attach the finished media itself. The requester agent follows its normal visible-reply contract: automatic final reply when configured, or `message(action="send")` plus `NO_REPLY` when the session requires message-tool replies. If the requester session is no longer active or its active wake fails, and the completion agent misses some or all generated media, OpenClaw sends an idempotent direct fallback with only the missing media to the original channel target.
106106

107107
</Accordion>
108108
<Accordion title="Concurrent media-generation guardrail">

‎docs/tools/image-generation.md‎

Lines changed: 6 additions & 5 deletions
Original file line numberDiff line numberDiff line change
@@ -11,11 +11,12 @@ sidebarTitle: "Image generation"
1111
The `image_generate` tool lets the agent create and edit images using your
1212
configured providers. In chat sessions, image generation runs asynchronously:
1313
OpenClaw records a background task, returns the task id immediately, and wakes
14-
the agent when the provider finishes. The completion agent must send generated
15-
images through the `message` tool. If the requester session is inactive or
16-
its active wake fails, and some generated images are still missing from
17-
message-tool delivery, OpenClaw sends an idempotent direct fallback with only
18-
the missing images.
14+
the agent when the provider finishes. The completion agent follows the
15+
session's normal visible-reply mode: automatic final reply delivery when
16+
configured, or `message(action="send")` when the session requires the message
17+
tool. If the requester session is inactive or its active wake fails, and some
18+
generated images are still missing from the completion reply, OpenClaw sends an
19+
idempotent direct fallback with only the missing images.
1920

2021
<Note>
2122
The tool only appears when at least one image-generation provider is

‎docs/tools/media-overview.md‎

Lines changed: 6 additions & 5 deletions
Original file line numberDiff line numberDiff line change
@@ -98,11 +98,12 @@ For async tools, OpenClaw submits the request to the provider, returns a task
9898
id immediately, and tracks the job in the task ledger. The agent continues
9999
responding to other messages while the job runs. When the provider finishes,
100100
OpenClaw wakes the agent with the generated media paths so it can tell the
101-
user and relay the result through the message tool. If the requester session
102-
is inactive or its active wake fails, and some generated media is still
103-
missing from message-tool delivery, OpenClaw sends an idempotent direct
104-
fallback with only the missing media. Media already delivered through the
105-
message tool is not posted again.
101+
user through the session's normal visible-reply mode: automatic final reply
102+
delivery when configured, or `message(action="send")` when the session requires
103+
the message tool. If the requester session is inactive or its active wake
104+
fails, and some generated media is still missing from the completion reply,
105+
OpenClaw sends an idempotent direct fallback with only the missing media. Media
106+
already delivered by the completion reply is not posted again.
106107

107108
## Speech-to-text and Voice Call
108109

‎docs/tools/music-generation.md‎

Lines changed: 6 additions & 6 deletions
Original file line numberDiff line numberDiff line change
@@ -15,12 +15,12 @@ fal, Google, MiniMax, and OpenRouter today.
1515
For session-backed agent runs, OpenClaw starts music generation as a
1616
background task, tracks it in the task ledger, then wakes the agent again
1717
when the track is ready so the agent can tell the user and attach the
18-
finished audio. Generated-media completions are delivered by the agent through
19-
the message tool. If the requester session is inactive or its active wake
20-
fails, and some generated audio is still missing from message-tool delivery,
21-
OpenClaw sends an idempotent direct fallback with only the missing audio. The
22-
completion wake explicitly warns the agent that normal final replies are
23-
private for this route.
18+
finished audio. The completion agent follows the session's normal visible-reply
19+
mode: automatic final reply delivery when configured, or `message(action="send")`
20+
when the session requires the message tool. If the requester session is
21+
inactive or its active wake fails, and some generated audio is still missing
22+
from the completion reply, OpenClaw sends an idempotent direct fallback with
23+
only the missing audio.
2424

2525
<Note>
2626
The built-in shared tool only appears when at least one music-generation

‎docs/tools/video-generation.md‎

Lines changed: 6 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -62,10 +62,12 @@ session:
6262
1. OpenClaw submits the request to the provider and immediately returns a task id.
6363
2. The provider processes the job in the background (typically 30 seconds to several minutes depending on the provider and resolution; slow queue-backed providers can run up to the configured timeout).
6464
3. When the video is ready, OpenClaw wakes the same session with an internal completion event.
65-
4. The agent tells the user and attaches the finished video through the
66-
message tool. If the requester session is inactive or its active wake
67-
fails, and some generated video is still missing from message-tool delivery,
68-
OpenClaw sends an idempotent direct fallback with only the missing video.
65+
4. The agent tells the user through the session's normal visible-reply mode:
66+
final reply delivery when automatic, or `message(action="send")` when the
67+
session requires the message tool. If the requester session is inactive or
68+
its active wake fails, and some generated video is still missing from the
69+
completion reply, OpenClaw sends an idempotent direct fallback with only the
70+
missing video.
6971

7072
While a job is in flight, duplicate `video_generate` calls in the same
7173
session return the current task status instead of starting another

0 commit comments

Comments
 (0)