Expose caller-supplied submissionId for direct agent prompts

[odysseus0]

Problem

The direct agent prompt APIs appear to generate submissionId inside Flue rather than letting the caller provide one.

That makes direct prompts hard to use safely from an application authority that needs durable, idempotent admission across retries. The issue is separate from #307: #307 fixed durable user-message replay after a direct prompt is admitted. This request is about exposing the admission identity at the public API boundary so the application can own retry/reconciliation semantics.

Current versions checked: @flue/sdk, @flue/runtime, and @flue/react 1.0.0-beta.9.

Distributed-systems failure case

A typical application flow looks like this:

1. App authority commits product intent locally, for example TaskEvent(task.continued, submissionId=sub_123).
2. App calls Flue direct prompt over a network/runtime boundary.
3. Flue may successfully admit the prompt.
4. The response may still be lost, the Worker may be replaced, or the caller may crash before recording the receipt.
5. The app retries the same product intent.

For this to be safe, the caller needs to retry with the same stable operation identity. If Flue generates submissionId only after the call crosses the boundary, the caller cannot prove whether a retry is the same admission or a new admission. That pushes applications toward duplicate prompts, custom sidecar wrappers, or weaker reconciliation logic.

This is the usual at-least-once distributed systems shape: exactly-once delivery is not available across the boundary, so the callee should accept a caller-owned idempotency key / operation identity for the mutation.

Desired behavior

Allow callers to pass an optional submissionId through direct prompt APIs. If omitted, Flue can keep today’s generated-id behavior.

Sketch:

await client.agents.sendAgent(agentName, agentId, {
  message: "continue this task",
  submissionId: "sub_123"
})

For React, the same should be possible from sendMessage options:

agent.sendMessage("continue this task", { submissionId: "sub_123" })

Expected semantics:

• The supplied submissionId becomes the canonical submission identity for the direct prompt.
• Retrying the same direct prompt with the same submissionId should reconcile to the same durable submission/admission rather than create a second logical input.
• If Flue cannot guarantee full idempotent no-op semantics yet, still accepting and persisting caller-supplied submissionId is useful because it gives applications a stable correlation/fencing key for reconciliation.
• If submissionId is omitted, current behavior remains unchanged.

Why this matters

Flue already has strong runtime/session machinery. Applications built on top of it still need to coordinate product authority with Flue admission. Without caller-supplied submissionId, the boundary forces app-level wrappers around direct prompts just to recover from commit-success/response-lost and replacement races.

With caller-supplied submissionId, the clean layering is:

• application authority owns product intent and persists the stable submission id;
• Flue owns runtime admission/execution/replay for that submission;
• retries and late receipts can be fenced by the same id instead of inferred from timing.

Local patch shape that worked for us

We patched the public API and runtime path narrowly:

• AgentPromptOptions / React SendMessageOptions accept submissionId?: string;
• SDK direct prompt requests include it when present;
• direct runtime payload schema accepts optional submissionId;
• direct submission input uses options.submissionId ?? crypto.randomUUID();
• Node and Cloudflare direct-admission paths pass the payload value through.

That was enough for our application boundary to use Flue’s own submission identity instead of inventing a separate wrapper identity.

[astrobot-houston]

Possibly related contribution from @av-x — opened #501 which appears to be addressing this.

Their summary: Adds submissionId support to the React and SDK client packages, allowing consumers to attach a stable submission identifier when sending messages. This enables idempotent retry behavior on ambiguous send failures by threading the ID through to the server's existing insert-or-ignore deduplication logic. The PR also bundles unrelated CI workflow additions and Cloudflare build changes.

Implementation: argonavis-labs/flue@art/run-5213-client-submission-id (diff)

This comment was posted automatically when #501 was redirected. The implementation is preserved on the branch above so it can inform the work here.