deploy: 4bcd7d0

Author: github-actions[bot]

2.0/llms-full.txt

@@ -721,7 +721,7 @@ Validation errors are returned in the standard control-plane error envelope with
 
 # Signals
 
-Signals allow you to trigger events in a workflow from outside the workflow. This can be useful for reacting to external events, enabling *human-in-the-loop* interventions, or for signaling the completion of an external task.
+Signals allow you to trigger events in a workflow from outside the workflow. This can be useful for reacting to external events, enabling *human-in-the-loop* interventions, or for signaling the completion of an external task. For repeated ordered inputs with durable cursor advancement, use [Message Streams](./message-streams.md).
 
 ## Named Signal Waits
 
@@ -779,7 +779,7 @@ Signal behavior:
 
 **Important:** The `await()` function should only be used in a workflow, not an activity.
 
-For condition waits — waiting until a predicate over durable state becomes true — see [Condition Waits](./condition-waits.md). For a timeout-backed `await`, see [Signal + Timer](./signal+timer.md).
+For condition waits — waiting until a predicate over durable state becomes true — see [Condition Waits](./condition-waits.md). For a timeout-backed `await`, see [Signal + Timer](./signal+timer.md). For repeated inbox/outbox flows, see [Message Streams](./message-streams.md).
 
 # Queries
 
@@ -902,6 +902,145 @@ Those webhook routes accept the same JSON `arguments` field as Waterline, return
 
 **Important:** Querying a workflow does not advance its execution, unlike signals.
 
+# Message Streams
+
+Message streams are the v2 authoring surface for repeated workflow messages:
+human input loops, assistant replies, workflow-to-workflow notifications, and
+other ordered messages that must survive replay and continue-as-new.
+
+Workflow authors should use the first-class facade:
+
+- `$this->inbox('stream-key')`
+- `$this->outbox('stream-key')`
+- `$this->messages('stream-key')`
+- `Workflow\V2\MessageStream`
+
+Do not write `workflow_messages` rows or cursor rows directly from application
+workflow code. The facade is the stable contract; lower-level message services
+exist for package/runtime integration.
+
+## Receiving Messages
+
+Use `peek()` when a workflow needs to inspect pending inbound messages without
+advancing its durable cursor. Use `receive()` or `receiveOne()` when the
+workflow is ready to consume messages and record cursor advancement in history.
+
+```php
+use Workflow\V2\Workflow;
+
+final class ApprovalInboxWorkflow extends Workflow
+{
+    public function handle(): array
+    {
+        $pending = $this->inbox('approval.requests')->peek(limit: 10);
+
+        if ($pending->isEmpty()) {
+            return ['status' => 'waiting'];
+        }
+
+        $message = $this->inbox('approval.requests')->receiveOne();
+
+        return [
+            'status' => 'received',
+            'payload_reference' => $message?->payload_reference,
+            'correlation_id' => $message?->correlation_id,
+        ];
+    }
+}
+```
+
+`peek()` is read-only. `receive()` and `receiveOne()` mark messages consumed and
+advance the durable message cursor for the current run. Cursor advancement is a
+history fact, so replay, Waterline exports, and continue-as-new handoff can all
+reason about which inbound messages were already consumed.
+
+## Sending References
+
+Use `outbox(...)->sendReference(...)` when a workflow needs to publish an
+ordered outbound message. The message table stores routing metadata and a
+payload reference; large or application-owned content stays in the app's
+payload store.
+
+```php
+use Workflow\V2\Workflow;
+
+final class AssistantReplyWorkflow extends Workflow
+{
+    public function handle(string $targetWorkflowId, string $replyReference): array
+    {
+        $message = $this->outbox('ai.assistant')->sendReference(
+            targetInstanceId: $targetWorkflowId,
+            payloadReference: $replyReference,
+            correlationId: $this->workflowId(),
+            metadata: ['kind' => 'assistant_reply'],
+        );
+
+        return [
+            'status' => 'sent',
+            'stream' => $message->stream_key,
+            'sequence' => $message->sequence,
+        ];
+    }
+}
+```
+
+This keeps the workflow history small and lets consumers validate the payload
+store separately from durable message ordering.
+
+## Continue-As-New
+
+Message streams are instance-first. When a workflow continues as new, pending
+inbound messages and the cursor position are transferred to the continued run.
+Consumed messages remain attached to the original run as historical evidence.
+
+That means a long-lived workflow can shed history and keep the same public
+message route:
+
+```php
+use function Workflow\V2\continueAsNew;
+use Workflow\V2\Workflow;
+
+final class HumanInputLoopWorkflow extends Workflow
+{
+    public function handle(int $iteration = 0): array
+    {
+        $message = $this->inbox('human.replies')->receiveOne();
+
+        if ($message === null) {
+            return ['status' => 'waiting', 'iteration' => $iteration];
+        }
+
+        if ($this->shouldContinueAsNew()) {
+            return continueAsNew($iteration + 1);
+        }
+
+        return [
+            'status' => 'processed',
+            'iteration' => $iteration,
+            'payload_reference' => $message->payload_reference,
+        ];
+    }
+}
+```
+
+The caller keeps addressing the workflow instance id. It does not need to know
+which run currently owns the stream cursor.
+
+## Authoring Rules
+
+- Use semantic stream keys such as `ai.assistant`, `human.replies`, or
+  `approval.requests`; treat them as part of the workflow's public contract.
+- Use `peek()` for inspection and `receive()` / `receiveOne()` for durable
+  consumption.
+- Use `sendReference()` for outbound messages; store large payloads in an
+  application payload store and pass a reference.
+- Keep application code on `Workflow::inbox()`, `Workflow::outbox()`, and
+  `MessageStream`; do not depend on `MessageService`, `WorkflowMessage`, or
+  cursor-row writes as the authoring pattern.
+- For one-shot external events, use [Signals](./signals.md). For request/return
+  state changes, use [Updates](./updates.md). Use message streams when repeated
+  ordered messages need cursor semantics.
+
 # Updates
 
 Updates allow you to retrieve information about the current state of a workflow and mutate the workflow state at the same time. They are essentially both a query and a signal combined into one.
@@ -3314,7 +3453,7 @@ When a workflow continues as new, the new run inherits the previous run's metada
 | Visibility labels | Carried forward as-is (set once at start time) |
 | Business key | Carried forward as-is |
 | Compatibility marker | Carried forward so the new run targets the same worker build |
-| Message cursor position | Carried forward so the new run knows which inbound messages (signals/updates) were already consumed |
+| Message cursor position | Carried forward so the new run knows which inbound messages were already consumed through [Message Streams](./message-streams.md) |
 
 The new run starts with the inherited metadata and can continue upserting search attributes and memo from there. This means a long-lived polling workflow can accumulate metadata across generations without losing state when it sheds history.
 
@@ -3341,6 +3480,11 @@ class PollingWorkflow extends Workflow
 }
 ```
 
+For long-lived human-input or assistant loops, prefer the first-class
+`$this->inbox()` / `$this->outbox()` [Message Streams](./message-streams.md)
+facade. Pending stream messages and cursor position move to the continued run,
+while consumed messages remain on the original run as history evidence.
+
 # Versioning
 
 Since workflows can run for long periods, sometimes months or even years, it's common to need to make changes to a workflow definition while executions are still in progress. Without versioning, modifying workflow code that affects the execution path would cause non-determinism errors during replay.
@@ -5422,6 +5566,27 @@ The export includes a SHA-256 integrity checksum. Set `DW_V2_HISTORY_EXPORT_SIGN
 
 The exported `selected_run` block includes `waits_projection_source`, `timeline_projection_source`, `timers_projection_source`, and `lineage_projection_source`. The exported `links` block also includes `projection_source`, and the `links.parents` / `links.children` sections come from the selected run's typed lineage history first, so child-workflow and continue-as-new relationships remain visible in the bundle even if mutable link rows have drifted during a local experiment. When a lineage row is surviving only through older mutable compatibility data, the bundle now marks that entry with `history_authority = mutable_open_fallback` and `diagnostic_only = true` instead of silently rehydrating extra link metadata during export.
 
+## AI Workflow Message Streams
+
+Repeated AI or human-input workflows should use the first-class v2 message
+stream facade as their authoring pattern:
+
+```php
+$reply = $this->inbox('ai.assistant')->receiveOne();
+
+$this->outbox('ai.assistant')->sendReference(
+    targetInstanceId: $this->workflowId(),
+    payloadReference: $storedReplyReference,
+    correlationId: $requestId,
+);
+```
+
+Keep app-owned payload storage for large request/response bodies, then pass
+the stored reference through the stream. Do not teach new sample workflows to
+write `workflow_messages`, `MessageStreamCursor`, or `MessageService` calls
+directly. See [Message Streams](/docs/2.0/features/message-streams) for the
+stable v2 inbox/outbox contract.
+
 **Step 10**
 
 Run the workflow and activity tests.
@@ -5504,6 +5669,12 @@ Use `simple` or `elapsed` as no-credential smoke tests. Use workflows with
 external credentials only after the local environment contains the required
 keys.
 
+When an agent edits repeated AI or human-input workflows, point it at the v2
+[Message Streams](/docs/2.0/features/message-streams) contract. The stable
+authoring pattern is `Workflow::inbox()` / `Workflow::outbox()` /
+`MessageStream`; direct `MessageService`, `WorkflowMessage`, or cursor-row
+writes are runtime internals, not sample code patterns.
+
 ## Command And Diagnostic Contracts
 
 Agents should prefer machine-readable surfaces over screenshots or prose:

404.html

@@ -13,13 +13,13 @@
 
 
 <link rel="search" type="application/opensearchdescription+xml" title="Durable Workflow" href="/opensearch.xml"><link rel="stylesheet" href="/assets/css/styles.bdb910b5.css">
-<link rel="preload" href="/assets/js/runtime~main.64fe7c58.js" as="script">
-<link rel="preload" href="/assets/js/main.16d43852.js" as="script">
+<link rel="preload" href="/assets/js/runtime~main.b4618c80.js" as="script">
+<link rel="preload" href="/assets/js/main.00ef40b6.js" as="script">
 </head>
 <body class="navigation-with-keyboard">
 <script>!function(){function t(t){document.documentElement.setAttribute("data-theme",t)}var e=function(){var t=null;try{t=localStorage.getItem("theme")}catch(t){}return t}();t(null!==e?e:"dark")}()</script><div id="__docusaurus">
 <div role="region" aria-label="Skip to main content"><a class="skipToContent_fXgn" href="#docusaurus_skipToContent_fallback">Skip to main content</a></div><nav class="navbar navbar--fixed-top"><div class="navbar__inner"><div class="navbar__items"><button aria-label="Toggle navigation bar" aria-expanded="false" class="navbar__toggle clean-btn" type="button"><svg width="30" height="30" viewBox="0 0 30 30" aria-hidden="true"><path stroke="currentColor" stroke-linecap="round" stroke-miterlimit="10" stroke-width="2" d="M4 7h22M4 15h22M4 23h22"></path></svg></button><a class="navbar__brand" href="/"><div class="navbar__logo"><img src="/img/logo.svg" alt="Workflow Logo" class="themedImage_ToTc themedImage--light_HNdA"><img src="/img/logo.svg" alt="Workflow Logo" class="themedImage_ToTc themedImage--dark_i4oU"></div><b class="navbar__title text--truncate">Durable Workflow</b></a><a class="navbar__item navbar__link" href="/docs/installation/">Docs</a><div class="navbar__item dropdown dropdown--hoverable"><a class="navbar__link" aria-haspopup="true" aria-expanded="false" role="button" href="/docs/introduction/">1.x</a><ul class="dropdown__menu"><li><a class="dropdown__link" href="/docs/2.0/introduction/">2.0</a></li><li><a class="dropdown__link" href="/docs/introduction/">1.x</a></li></ul></div><a class="navbar__item navbar__link" href="/blog/">Blog</a></div><div class="navbar__items navbar__items--right"><a href="https://github.com/durable-workflow/workflow" target="_blank" rel="noopener noreferrer" aria-label="Star Durable Workflow on GitHub" class="navbar-github-star-link navbar__item navbar__link" label="Star on GitHub"><svg aria-hidden="true" class="navbar-github-star-link__icon" viewBox="0 0 16 16"><path d="M8 0C3.58 0 0 3.58 0 8a8.01 8.01 0 0 0 5.47 7.59c.4.07.55-.17.55-.38 0-.19-.01-.82-.01-1.49-2.01.37-2.53-.49-2.69-.94-.09-.23-.48-.94-.82-1.13-.28-.15-.68-.52-.01-.53.63-.01 1.08.58 1.23.82.72 1.21 1.87.87 2.33.66.07-.52.28-.87.5-1.07-1.78-.2-3.64-.89-3.64-3.95 0-.87.31-1.59.82-2.15-.08-.2-.36-1.02.08-2.12 0 0 .67-.21 2.2.82A7.56 7.56 0 0 1 8 4.76c.68 0 1.36.09 2 .27 1.53-1.03 2.2-.82 2.2-.82.44 1.1.16 1.92.08 2.12.51.56.82 1.28.82 2.15 0 3.07-1.87 3.75-3.65 3.95.29.25.54.73.54 1.48 0 1.07-.01 1.93-.01 2.2 0 .21.15.46.55.38A8.01 8.01 0 0 0 16 8c0-4.42-3.58-8-8-8Z"></path></svg><span class="navbar-github-star-link__count" title="GitHub stars">1.2K</span></a><a href="https://github.com/durable-workflow/workflow" target="_blank" rel="noopener noreferrer" aria-label="Star Durable Workflow on GitHub" class="navbar-github-star-link navbar__link navbar-github-star-link--mobile-topbar" label="Star on GitHub"><svg aria-hidden="true" class="navbar-github-star-link__icon" viewBox="0 0 16 16"><path d="M8 0C3.58 0 0 3.58 0 8a8.01 8.01 0 0 0 5.47 7.59c.4.07.55-.17.55-.38 0-.19-.01-.82-.01-1.49-2.01.37-2.53-.49-2.69-.94-.09-.23-.48-.94-.82-1.13-.28-.15-.68-.52-.01-.53.63-.01 1.08.58 1.23.82.72 1.21 1.87.87 2.33.66.07-.52.28-.87.5-1.07-1.78-.2-3.64-.89-3.64-3.95 0-.87.31-1.59.82-2.15-.08-.2-.36-1.02.08-2.12 0 0 .67-.21 2.2.82A7.56 7.56 0 0 1 8 4.76c.68 0 1.36.09 2 .27 1.53-1.03 2.2-.82 2.2-.82.44 1.1.16 1.92.08 2.12.51.56.82 1.28.82 2.15 0 3.07-1.87 3.75-3.65 3.95.29.25.54.73.54 1.48 0 1.07-.01 1.93-.01 2.2 0 .21.15.46.55.38A8.01 8.01 0 0 0 16 8c0-4.42-3.58-8-8-8Z"></path></svg><span class="navbar-github-star-link__count" title="GitHub stars">1.2K</span></a><div class="toggle_vylO colorModeToggle_x44X"><button class="clean-btn toggleButton_gllP toggleButtonDisabled_aARS" type="button" disabled="" title="Switch between dark and light mode (currently dark mode)" aria-label="Switch between dark and light mode (currently dark mode)" aria-live="polite"><svg viewBox="0 0 24 24" width="24" height="24" class="lightToggleIcon_pyhR"><path fill="currentColor" d="M12,9c1.65,0,3,1.35,3,3s-1.35,3-3,3s-3-1.35-3-3S10.35,9,12,9 M12,7c-2.76,0-5,2.24-5,5s2.24,5,5,5s5-2.24,5-5 S14.76,7,12,7L12,7z M2,13l2,0c0.55,0,1-0.45,1-1s-0.45-1-1-1l-2,0c-0.55,0-1,0.45-1,1S1.45,13,2,13z M20,13l2,0c0.55,0,1-0.45,1-1 s-0.45-1-1-1l-2,0c-0.55,0-1,0.45-1,1S19.45,13,20,13z M11,2v2c0,0.55,0.45,1,1,1s1-0.45,1-1V2c0-0.55-0.45-1-1-1S11,1.45,11,2z M11,20v2c0,0.55,0.45,1,1,1s1-0.45,1-1v-2c0-0.55-0.45-1-1-1C11.45,19,11,19.45,11,20z M5.99,4.58c-0.39-0.39-1.03-0.39-1.41,0 c-0.39,0.39-0.39,1.03,0,1.41l1.06,1.06c0.39,0.39,1.03,0.39,1.41,0s0.39-1.03,0-1.41L5.99,4.58z M18.36,16.95 c-0.39-0.39-1.03-0.39-1.41,0c-0.39,0.39-0.39,1.03,0,1.41l1.06,1.06c0.39,0.39,1.03,0.39,1.41,0c0.39-0.39,0.39-1.03,0-1.41 L18.36,16.95z M19.42,5.99c0.39-0.39,0.39-1.03,0-1.41c-0.39-0.39-1.03-0.39-1.41,0l-1.06,1.06c-0.39,0.39-0.39,1.03,0,1.41 s1.03,0.39,1.41,0L19.42,5.99z M7.05,18.36c0.39-0.39,0.39-1.03,0-1.41c-0.39-0.39-1.03-0.39-1.41,0l-1.06,1.06 c-0.39,0.39-0.39,1.03,0,1.41s1.03,0.39,1.41,0L7.05,18.36z"></path></svg><svg viewBox="0 0 24 24" width="24" height="24" class="darkToggleIcon_wfgR"><path fill="currentColor" d="M9.37,5.51C9.19,6.15,9.1,6.82,9.1,7.5c0,4.08,3.32,7.4,7.4,7.4c0.68,0,1.35-0.09,1.99-0.27C17.45,17.19,14.93,19,12,19 c-3.86,0-7-3.14-7-7C5,9.07,6.81,6.55,9.37,5.51z M12,3c-4.97,0-9,4.03-9,9s4.03,9,9,9s9-4.03,9-9c0-0.46-0.04-0.92-0.1-1.36 c-0.98,1.37-2.58,2.26-4.4,2.26c-2.98,0-5.4-2.42-5.4-5.4c0-1.81,0.89-3.42,2.26-4.4C12.92,3.04,12.46,3,12,3L12,3z"></path></svg></button></div><div class="searchBox_ZlJk"><button type="button" class="DocSearch DocSearch-Button" aria-label="Search"><span class="DocSearch-Button-Container"><svg width="20" height="20" class="DocSearch-Search-Icon" viewBox="0 0 20 20"><path d="M14.386 14.386l4.0877 4.0877-4.0877-4.0877c-2.9418 2.9419-7.7115 2.9419-10.6533 0-2.9419-2.9418-2.9419-7.7115 0-10.6533 2.9418-2.9419 7.7115-2.9419 10.6533 0 2.9419 2.9418 2.9419 7.7115 0 10.6533z" stroke="currentColor" fill="none" fill-rule="evenodd" stroke-linecap="round" stroke-linejoin="round"></path></svg><span class="DocSearch-Button-Placeholder">Search</span></span><span class="DocSearch-Button-Keys"></span></button></div></div></div><div role="presentation" class="navbar-sidebar__backdrop"></div></nav><div id="docusaurus_skipToContent_fallback" class="main-wrapper mainWrapper_z2l0"><main class="container margin-vert--xl"><div class="row"><div class="col col--6 col--offset-3"><h1 class="hero__title">Page Not Found</h1><p>We could not find what you were looking for.</p><p>Please contact the owner of the site that linked you to the original URL and let them know their link is broken.</p></div></div></main></div><div><footer class="footer footer--dark"><div class="container container-fluid"><div class="row footer__links"><div class="col footer__col"><div class="footer__title">Docs</div><ul class="footer__items clean-list"><li class="footer__item"><a class="footer__link-item" href="/docs/introduction/">Introduction</a></li><li class="footer__item"><a class="footer__link-item" href="/docs/installation/">Installation</a></li></ul></div><div class="col footer__col"><div class="footer__title">Community</div><ul class="footer__items clean-list"><li class="footer__item"><a href="https://discord.gg/xu5aDDpqVy" target="_blank" rel="noopener noreferrer" class="footer__link-item">Discord<svg width="13.5" height="13.5" aria-hidden="true" viewBox="0 0 24 24" class="iconExternalLink_nPIU"><path fill="currentColor" d="M21 13v10h-21v-19h12v2h-10v15h17v-8h2zm3-12h-10.988l4.035 4-6.977 7.07 2.828 2.828 6.977-7.07 4.125 4.172v-11z"></path></svg></a></li><li class="footer__item"><a href="https://x.com/DurableWorkflow" target="_blank" rel="noopener noreferrer" class="footer__link-item">X<svg width="13.5" height="13.5" aria-hidden="true" viewBox="0 0 24 24" class="iconExternalLink_nPIU"><path fill="currentColor" d="M21 13v10h-21v-19h12v2h-10v15h17v-8h2zm3-12h-10.988l4.035 4-6.977 7.07 2.828 2.828 6.977-7.07 4.125 4.172v-11z"></path></svg></a></li></ul></div><div class="col footer__col"><div class="footer__title">More</div><ul class="footer__items clean-list"><li class="footer__item"><a href="https://durable-workflow.com/llms-full.txt" target="_blank" rel="noopener noreferrer" class="footer__link-item">LLM Docs<svg width="13.5" height="13.5" aria-hidden="true" viewBox="0 0 24 24" class="iconExternalLink_nPIU"><path fill="currentColor" d="M21 13v10h-21v-19h12v2h-10v15h17v-8h2zm3-12h-10.988l4.035 4-6.977 7.07 2.828 2.828 6.977-7.07 4.125 4.172v-11z"></path></svg></a></li><li class="footer__item"><a href="https://packagist.org/packages/durable-workflow/workflow" target="_blank" rel="noopener noreferrer" class="footer__link-item">Packagist<svg width="13.5" height="13.5" aria-hidden="true" viewBox="0 0 24 24" class="iconExternalLink_nPIU"><path fill="currentColor" d="M21 13v10h-21v-19h12v2h-10v15h17v-8h2zm3-12h-10.988l4.035 4-6.977 7.07 2.828 2.828 6.977-7.07 4.125 4.172v-11z"></path></svg></a></li></ul></div></div><div class="footer__bottom text--center"><div class="footer__copyright">Copyright © 2026 <a href="https://durable-workflow.com">Durable Workflow</a>.</div></div></div></footer></div></div>
-<script src="/assets/js/runtime~main.64fe7c58.js"></script>
-<script src="/assets/js/main.16d43852.js"></script>
+<script src="/assets/js/runtime~main.b4618c80.js"></script>
+<script src="/assets/js/main.00ef40b6.js"></script>
 </body>
 </html>