docs: async fixture response documentation and changelog

Dynamic/async responses section on examples page. Info-box callouts
on fixtures and multi-turn pages. Changelog entry credits
@5ebastianMeier (issue #154).

Author: jpr5

CHANGELOG.md

@@ -4,6 +4,7 @@
 
 ### Added
 
+- **Async fixture responses** — Fixture responses can now be sync or async functions that receive the request and return the response dynamically. Enables awaiting side effects (database writes, API calls) before constructing the response — eliminating race conditions in complex multi-turn E2E tests. Works with all providers, streaming, and convenience methods (`on()`, `onMessage()`, `onTurn()`). (Feature request by @5ebastianMeier, issue #154)
 - **Snapshot-style recording** — When `X-Test-Id` is present, recorded fixtures are saved to `<fixturePath>/<slugified-testId>/<provider>.json` instead of timestamp-based filenames. Multiple fixtures for the same test+provider merge into one file. Stable paths enable meaningful PR diffs and easy test-to-fixture mapping. (Feature request by @jantimon, issue #155)
 
 ## [1.18.0] - 2026-05-04

docs/examples/index.html

@@ -607,6 +607,52 @@ <h3>Tool-call cycle with hasToolResult</h3>
   ]
 }</code></pre>
         </div>
+
+        <!-- ─── Dynamic / Async Responses ──────────────────────────── -->
+
+        <h2>Dynamic / Async Responses</h2>
+
+        <p>
+          Fixture responses can be functions &mdash; sync or async &mdash; that receive the request
+          and return the response dynamically. Use this when you need to await side effects, compute
+          responses based on request content, or inject runtime data into fixtures.
+        </p>
+
+        <h3>Async response with side-effect</h3>
+        <p>
+          Wait for an external operation to complete before constructing the fixture response.
+          Eliminates race conditions in multi-turn E2E tests where entity creation happens
+          out-of-band.
+        </p>
+        <div class="code-block">
+          <div class="code-block-header">async-side-effect.ts <span class="lang-tag">ts</span></div>
+          <pre><code><span class="op">mock</span>.<span class="fn">on</span>(
+  { <span class="prop">toolCallId</span>: <span class="str">"call_create_entity"</span> },
+  <span class="kw">async</span> (<span class="op">req</span>) <span class="kw">=&gt;</span> {
+    <span class="kw">const</span> <span class="op">entity</span> = <span class="kw">await</span> <span class="op">createEntityPromise</span>;
+    <span class="kw">return</span> {
+      <span class="prop">content</span>: <span class="str">`Entity "${entity.name}" created!`</span>,
+      <span class="prop">toolCalls</span>: [{
+        <span class="prop">name</span>: <span class="str">"next_step"</span>,
+        <span class="prop">arguments</span>: <span class="op">JSON</span>.<span class="fn">stringify</span>({ <span class="prop">entityId</span>: <span class="op">entity</span>.<span class="prop">id</span> }),
+      }],
+    };
+  },
+);</code></pre>
+        </div>
+
+        <h3>Request-aware response</h3>
+        <p>
+          Compute the response from the incoming request content. Useful for echo-style fixtures,
+          transformations, or conditional logic that goes beyond what match fields can express.
+        </p>
+        <div class="code-block">
+          <div class="code-block-header">request-aware.ts <span class="lang-tag">ts</span></div>
+          <pre><code><span class="op">mock</span>.<span class="fn">onMessage</span>(<span class="str">"translate"</span>, (<span class="op">req</span>) <span class="kw">=&gt;</span> {
+  <span class="kw">const</span> <span class="op">text</span> = <span class="op">req</span>.<span class="prop">messages</span>.<span class="fn">at</span>(-<span class="num">1</span>)?.<span class="prop">content</span> <span class="kw">??</span> <span class="str">""</span>;
+  <span class="kw">return</span> { <span class="prop">content</span>: <span class="str">`Translated: ${text.toUpperCase()}`</span> };
+});</code></pre>
+        </div>
       </main>
       <aside class="page-toc" id="page-toc"></aside>
     </div>

docs/fixtures/index.html

@@ -355,6 +355,14 @@ <h2>Response Types</h2>
           </p>
         </div>
 
+        <div class="info-box">
+          <p>
+            <strong>Dynamic responses:</strong> Responses can also be sync or async functions that
+            receive the request and return the response dynamically. See
+            <a href="/examples#dynamic-async-responses">Dynamic Responses</a> on the Examples page.
+          </p>
+        </div>
+
         <h2>Response Override Fields</h2>
         <p>
           Fixture responses can include optional fields to override auto-generated envelope values.

docs/multi-turn/index.html

@@ -182,6 +182,18 @@ <h3>hasToolResult &mdash; match by tool execution state</h3>
 }</code></pre>
         </div>
 
+        <div class="info-box">
+          <p>
+            <strong>Async fixture responses for race-free multi-turn tests.</strong> When a
+            multi-turn test depends on side effects between turns (database writes, entity creation,
+            external API calls), async fixture responses let you <code>await</code> those operations
+            before constructing the response &mdash; eliminating race conditions without
+            <code>setTimeout</code> hacks. See
+            <a href="/examples#dynamic-async-responses">Dynamic / Async Responses</a> on the
+            Examples page.
+          </p>
+        </div>
+
         <h3>Programmatic API</h3>
         <p>
           The <code>onTurn()</code> convenience method combines <code>turnIndex</code> with a