Add a resumable conversational workflow reference

The guides explain durable messaging, waits, activities and continue-as-new separately, but do not provide a single runnable reference for a long-lived conversation that survives worker replacement and bounds history growth.

At docs main e1ac63c3ccd93cbf7c6d0f6e94820af50531f545, Message Streams already documents reference payloads and cursor transfer through continue-as-new. Signals documents durable named waits. The agent operating-loop page describes an agent operating the product, which is a different task from authoring a conversational application.

Priority P3, a focused documentation/example addition using existing capabilities.

Acceptance:

Provide one runnable, clearly identified deployment/language path. Use a deterministic fake model activity so the reference requires no paid model account or secrets.
Accept ordered input, preserve conversation state or external payload references, and durably checkpoint emitted responses.
Demonstrate worker stop/replacement while waiting and while an activity is in flight. Verify that replay preserves the agreed progress and duplicate handling follows the documented at-least-once contract.
Bound history through a tested continue-as-new handoff, including pending input/cursor behavior. Keep external payload storage, summarization policy and authentication responsibilities explicit.
Link to the existing feature guides and the runnable Sample/AI examples where applicable. Do not promise a production-scale chatbot, durable process memory or unqualified latency.

Source review establishes a missing composite reference, not a missing durability primitive. No new runtime behavior or external AI provider commitment is requested. Existing issue metadata was searched for conversational references before opening this issue.

Keep human approval and inspectable whole-run state in the small reference: a recorded input/approval should resume the same logical conversation, activity-owned model work should use a fake adapter for the example, and continue-as-new should carry the explicit state needed afterward. A query or selected-run detail should explain the current phase/outcome. This remains one cohesive example; it does not add multi-region synchronization or a new prompt-evaluation platform to the acceptance scope.

Product review:

Keep the runnable conversational reference: existing durable input, activity, signal and continue-as-new primitives support it. There is no evidence here requiring a new conversation runtime. Qualify replacement, ordered pending input and continuation using released signal-boundary behavior. Shared #216 separately owns safe command retries; a reference must not claim exactly-once external effects.

Ownership: the durable-workflow-github-io repo agent is taking this (2026-11-03), after the stable-manifest PR (#437) and #405.

Plan. The runnable path is embedded Laravel: a new sample-app gallery sample, App\Workflows\Conversation\ConversationWorkflow with php artisan app:conversation. This site gets a guide page that links the existing Signals, Message Streams, Continue As New, Activities and execution-guarantee pages.

Model work: a deterministic fake model activity. No provider account or secrets.
Input and approval: declared instance signals for ordered user input, applied in durable command-sequence order, plus a human approval.
Replies: checkpointed as payload references on an outbox stream. The reply row is written by an activity keyed by reference, not by workflow code.
Status: a query that reports the phase and outcome.
History bound: continue-as-new after a fixed number of turns, carrying explicit state. Pending declared instance signals transfer to the successor, as released since 2.7.0.

Tests, against the released package (sample-app currently locks Workflow 2.17.1):

Worker loss while waiting on input: the workflow task is lost, and repair recreates it.
Worker loss with the model activity in flight: the lease expires, and the retry is redelivered.
In both cases, replay keeps the agreed progress. A late original completion is not recorded, and an activity re-run stays idempotent per the documented at-least-once contract.

Out of scope: exactly-once external effects, production chatbot scale, and latency claims.

Delivered:

sample-app#302: merged d1b4ef7c. Adds ConversationWorkflow and app:conversation, pinned to the locked Workflow 2.17.1, with 9 tests. The tests cover a worker lost while applying a signal, a worker lost with the model activity in flight, an at-least-once reply write, a stale, duplicate or early decision bound by a replay-stable proposal ID, and continue-as-new handoff.
Add a conversational workflow reference guide #440: merged 47cb143c. Adds the guide and gallery rows in 8 languages.

Live readback after Pages deploy:

/docs/conversational-workflows/ returns 200 with h1 "Conversational Workflow Reference"; it shows the proposalId signal parameter, the uuid4() step and the workflow#1010 note.
/fr/docs/conversational-workflows/ returns 200 with h1 "Référence de workflow conversationnel".
/docs/sample-app/ lists ConversationWorkflow.

Found along the way:

Workflow-code outbox()->sendReference() writes new messages on every replay workflow#1010: message-stream calls in workflow code aren't replay-safe. The warning is live via Warn that message-stream calls in workflow code are not replay-safe #439.
The decision-binding defect General found in review, fixed before merge.

Navigation Menu

Repository navigation

Add a resumable conversational workflow reference #257

Metadata

Assignees

Labels

Type

Projects

Milestone

Relationships

Development

Add a resumable conversational workflow reference #257

Description

Activity

rmcdaniel commented on Oct 19, 2026

rmcdaniel commented on Oct 20, 2026

rmcdaniel commented on Nov 3, 2026

rmcdaniel commented on Nov 4, 2026

Metadata

Metadata

Assignees

Labels

Type

Projects

Milestone

Relationships

Development

Issue actions