feat: add requestTransform for deterministic matching and recording

Normalizes requests before matching and recording to handle dynamic
data (timestamps, UUIDs, session IDs) in prompts. When set, string
matching switches from includes to exact equality to prevent false
positives from shortened keys.

Applied across all 15 provider handlers + recorder. 16 new tests.

Based on the design by @iskhakovt in #63, rebuilt on the 1.7.0 codebase.

Author: jpr5

docs/migrate-from-mokksy.html

@@ -154,6 +154,16 @@ <h2>The quick switch</h2>
         <span class="str">"-p"</span>, <span class="str">"4010:4010"</span>, <span class="str">"-v"</span>, <span class="str">"./fixtures:/fixtures"</span>,
         <span class="str">"ghcr.io/copilotkit/aimock"</span>, <span class="str">"-f"</span>, <span class="str">"/fixtures"</span>)
         .<span class="fn">start</span>().<span class="fn">waitFor</span>()
+    <span class="cm">// Wait for server to be ready</span>
+    <span class="kw">repeat</span>(<span class="num">30</span>) {
+        <span class="kw">try</span> {
+            <span class="type">java.net.URL</span>(<span class="str">"http://localhost:4010/__aimock/health"</span>)
+                .<span class="fn">readText</span>()
+            <span class="kw">return</span>
+        } <span class="kw">catch</span> (_: <span class="type">Exception</span>) {
+            <span class="type">Thread</span>.<span class="fn">sleep</span>(<span class="num">200</span>)
+        }
+    }
 }
 
 <span class="kw">@AfterAll</span>

docs/migrate-from-python-mocks.html

@@ -248,17 +248,22 @@ <h3>aimock (after)</h3>
 
 <span class="op">@pytest.fixture</span>(scope=<span class="str">"session"</span>)
 <span class="kw">def</span> <span class="fn">aimock_server</span>():
-    <span class="cm"># Start aimock via Docker</span>
     proc = subprocess.Popen([
         <span class="str">"docker"</span>, <span class="str">"run"</span>, <span class="str">"--rm"</span>,
         <span class="str">"-p"</span>, <span class="str">"4010:4010"</span>,
         <span class="str">"-v"</span>, <span class="str">f"{os.getcwd()}/fixtures:/fixtures"</span>,
         <span class="str">"ghcr.io/copilotkit/aimock:latest"</span>,
         <span class="str">"-f"</span>, <span class="str">"/fixtures"</span>
     ])
-    time.sleep(<span class="num">2</span>)  <span class="cm"># wait for server</span>
+    <span class="cm"># Wait for health endpoint</span>
+    <span class="kw">import</span> requests
+    <span class="kw">for</span> _ <span class="kw">in</span> range(<span class="num">30</span>):
+        <span class="kw">try</span>:
+            <span class="kw">if</span> requests.get(<span class="str">"http://localhost:4010/__aimock/health"</span>).ok:
+                <span class="kw">break</span>
+        <span class="kw">except</span> requests.ConnectionError:
+            time.sleep(<span class="num">0.2</span>)
 
-    <span class="cm"># Point OpenAI SDK at the mock</span>
     os.environ[<span class="str">"OPENAI_BASE_URL"</span>] = <span class="str">"http://localhost:4010/v1"</span>
     os.environ[<span class="str">"OPENAI_API_KEY"</span>] = <span class="str">"mock-key"</span>
 
@@ -489,9 +494,16 @@ <h2>Alternative: npx fixture (no Docker)</h2>
 <span class="kw">def</span> <span class="fn">aimock_server</span>():
     proc = subprocess.Popen(
         [<span class="str">"npx"</span>, <span class="str">"aimock"</span>, <span class="str">"-p"</span>, <span class="str">"4010"</span>, <span class="str">"-f"</span>, <span class="str">"./fixtures"</span>],
-        stdout=subprocess.PIPE, stderr=subprocess.PIPE
+        stdout=subprocess.PIPE, stderr=subprocess.STDOUT
     )
-    time.sleep(<span class="num">2</span>)  <span class="cm"># wait for server</span>
+    <span class="cm"># Wait for health endpoint</span>
+    <span class="kw">import</span> requests
+    <span class="kw">for</span> _ <span class="kw">in</span> range(<span class="num">30</span>):
+        <span class="kw">try</span>:
+            <span class="kw">if</span> requests.get(<span class="str">"http://localhost:4010/__aimock/health"</span>).ok:
+                <span class="kw">break</span>
+        <span class="kw">except</span> requests.ConnectionError:
+            time.sleep(<span class="num">0.2</span>)
 
     os.environ[<span class="str">"OPENAI_BASE_URL"</span>] = <span class="str">"http://localhost:4010/v1"</span>
     os.environ[<span class="str">"OPENAI_API_KEY"</span>] = <span class="str">"mock-key"</span>

docs/record-replay.html

@@ -355,6 +355,55 @@ <h2>CI Pipeline Workflow</h2>
   run: docker stop aimock</code></pre>
         </div>
 
+        <h2>Request Transform</h2>
+        <p>
+          Prompts often contain dynamic data &mdash; timestamps, UUIDs, session IDs &mdash; that
+          changes between runs. This causes fixture mismatches on replay because the recorded key no
+          longer matches the live request. The <code>requestTransform</code> option normalizes
+          requests before both matching and recording, stripping out the volatile parts.
+        </p>
+
+        <div class="code-block">
+          <div class="code-block-header">
+            Strip timestamps before matching <span class="lang-tag">ts</span>
+          </div>
+          <pre><code>import { LLMock } from "@copilotkit/aimock";
+
+const mock = new LLMock({
+  requestTransform: (req) => ({
+    ...req,
+    messages: req.messages.map((m) => ({
+      ...m,
+      content:
+        typeof m.content === "string"
+          ? m.content.replace(/\d{4}-\d{2}-\d{2}T[\d:.+Z-]+/g, "")
+          : m.content,
+    })),
+  }),
+});
+
+// Fixture uses the cleaned key (no timestamp)
+mock.onMessage("tell me the weather ", { content: "Sunny" });
+
+// Request with a timestamp still matches after transform
+await mock.start();</code></pre>
+        </div>
+
+        <p>
+          When <code>requestTransform</code> is set, string matching for
+          <code>userMessage</code> and <code>inputText</code> switches from substring
+          (<code>includes</code>) to exact equality (<code>===</code>). This prevents shortened keys
+          from accidentally matching unrelated prompts. Without a transform, the existing
+          <code>includes</code> behavior is preserved for backward compatibility.
+        </p>
+
+        <p>
+          The transform is applied in both directions: <strong>recording</strong> saves the
+          transformed match key (no timestamps in the fixture file), and
+          <strong>matching</strong> transforms the incoming request before comparison. This means
+          recorded fixtures and live requests always use the same normalized key.
+        </p>
+
         <h2>Building Fixture Sets</h2>
         <p>A practical workflow for building and maintaining fixture sets:</p>
         <ol>