fix(agent): patch History event handling after regen

- dispatch Agent History websocket events on wire type "History"
- deserialize History variants by payload shape instead of message name
- add regression tests for conversation-text and function-call History events
- freeze and document the Agent History patch for future regens

Author: GregHolmes

.claude/skills/prepare-regen.md

@@ -12,6 +12,7 @@ Read AGENTS.md for full context on the regeneration workflow and freeze classifi
 4. Read `.fernignore` and classify each entry using the rules in AGENTS.md:
     - **Permanently frozen**: entirely hand-written, no Fern equivalent. NEVER touch these.
     - **Temporarily frozen**: Fern-generated with manual patches. These get swapped.
+    - Current Java temporary freezes include `ClientOptions.java` plus the Agent History patch files `V1WebSocketClient.java` and `AgentV1History.java`.
 5. For each **temporarily frozen** file only:
     - Copy the file to `<filename>.bak` alongside the original.
     - In `.fernignore`, replace the original path with the `.bak` path (protects our patch, lets Fern overwrite the original).

.claude/skills/review-regen.md

@@ -14,7 +14,7 @@ Read AGENTS.md for full context on the regeneration workflow and freeze classifi
     - Patches still needed (must be re-applied)
     - New changes from the generator worth noting
 5. Wait for user direction on which patches to re-apply.
-6. Re-apply confirmed patches to the generated files. If `src/main/java/com/deepgram/core/ClientOptions.java` was regenerated, run `python3 .claude/scripts/fix_clientoptions.py` to restore the Deepgram SDK header constants and `// x-release-please-version` markers.
+6. Re-apply confirmed patches to the generated files. If `src/main/java/com/deepgram/core/ClientOptions.java` was regenerated, run `python3 .claude/scripts/fix_clientoptions.py` to restore the Deepgram SDK header constants and `// x-release-please-version` markers. If Fern still generates Agent History incorrectly, re-apply the manual patches in `src/main/java/com/deepgram/resources/agent/v1/websocket/V1WebSocketClient.java` and `src/main/java/com/deepgram/resources/agent/v1/types/AgentV1History.java` so websocket dispatch uses wire type `"History"` and the history union selects variants by payload shape.
 7. In `.fernignore`, replace each `.bak` path back to the original path for files that still need patches.
 8. Remove `.fernignore` entries entirely for files where patches are no longer needed.
 9. Delete all `.bak` files.

.fernignore

@@ -16,6 +16,12 @@ src/main/java/com/deepgram/AsyncDeepgramClientBuilder.java
 # Fern regen overwrites these with incorrect SDK names and strips the markers.
 src/main/java/com/deepgram/core/ClientOptions.java
 
+# Agent History websocket patch
+# Fern currently dispatches on the message name instead of wire type "History",
+# and the generated union needs explicit variant selection for content vs function_calls.
+src/main/java/com/deepgram/resources/agent/v1/websocket/V1WebSocketClient.java
+src/main/java/com/deepgram/resources/agent/v1/types/AgentV1History.java
+
 # Transport abstraction (pluggable transport for SageMaker, etc.)
 src/main/java/com/deepgram/core/transport/
 

AGENTS.md

@@ -48,6 +48,8 @@ How to identify:
 Current temporarily frozen files:
 
 - `src/main/java/com/deepgram/core/ClientOptions.java` - preserves release-please version markers and correct SDK header constants that Fern currently overwrites; re-apply with `python3 .claude/scripts/fix_clientoptions.py` during review regen
+- `src/main/java/com/deepgram/resources/agent/v1/websocket/V1WebSocketClient.java` - patches Fern's generated Agent History websocket dispatch to use wire type `"History"` instead of message name `"AgentV1History"`
+- `src/main/java/com/deepgram/resources/agent/v1/types/AgentV1History.java` - patches Fern's generated Agent History union deserializer to choose the correct variant by payload shape (`role`/`content` vs `function_calls`)
 
 ### Prepare repo for regeneration
 
@@ -66,7 +68,7 @@ Current temporarily frozen files:
 The `.bak` files are our manually patched versions protected by `.fernignore`. The original paths now contain the freshly generated versions. By comparing the two, we can see what the generator now produces versus what we had patched.
 
 1. Diff each `.bak` file against the new generated version to understand what changed and whether our patches are still needed.
-2. Re-apply any patches that are still necessary to the newly generated files. For `src/main/java/com/deepgram/core/ClientOptions.java`, run `python3 .claude/scripts/fix_clientoptions.py` to restore the Deepgram SDK header constants and `// x-release-please-version` markers.
+2. Re-apply any patches that are still necessary to the newly generated files. For `src/main/java/com/deepgram/core/ClientOptions.java`, run `python3 .claude/scripts/fix_clientoptions.py` to restore the Deepgram SDK header constants and `// x-release-please-version` markers. If Agent History is still generated incorrectly, re-apply the `V1WebSocketClient.java` and `AgentV1History.java` patches and keep those files frozen.
 3. In `.fernignore`, replace each `.bak` path back to the original path for files that still need patches.
 4. Remove `.fernignore` entries entirely for any files where the generator now produces correct output.
 5. Delete all `.bak` files once review is complete.

src/main/java/com/deepgram/resources/agent/v1/types/AgentV1History.java

@@ -7,6 +7,7 @@
 import com.fasterxml.jackson.annotation.JsonValue;
 import com.fasterxml.jackson.core.JsonParseException;
 import com.fasterxml.jackson.core.JsonParser;
+import com.fasterxml.jackson.databind.JsonNode;
 import com.fasterxml.jackson.databind.DeserializationContext;
 import com.fasterxml.jackson.databind.annotation.JsonDeserialize;
 import com.fasterxml.jackson.databind.deser.std.StdDeserializer;
@@ -80,16 +81,19 @@ static final class Deserializer extends StdDeserializer<AgentV1History> {
 
         @java.lang.Override
         public AgentV1History deserialize(JsonParser p, DeserializationContext context) throws IOException {
-            Object value = p.readValueAs(Object.class);
-            try {
-                return of(ObjectMappers.JSON_MAPPER.convertValue(value, AgentV1HistoryContent.class));
-            } catch (RuntimeException e) {
+            JsonNode value = p.readValueAsTree();
+
+            if (value.hasNonNull("function_calls")) {
+                return of(ObjectMappers.JSON_MAPPER.treeToValue(value, AgentV1HistoryFunctionCalls.class));
             }
-            try {
-                return of(ObjectMappers.JSON_MAPPER.convertValue(value, AgentV1HistoryFunctionCalls.class));
-            } catch (RuntimeException e) {
+
+            if (value.hasNonNull("role") || value.hasNonNull("content")) {
+                return of(ObjectMappers.JSON_MAPPER.treeToValue(value, AgentV1HistoryContent.class));
             }
-            throw new JsonParseException(p, "Failed to deserialize");
+
+            throw new JsonParseException(
+                    p,
+                    "Failed to deserialize AgentV1History: expected either role/content or function_calls payload");
         }
     }
 }

src/main/java/com/deepgram/resources/agent/v1/websocket/V1WebSocketClient.java

@@ -664,7 +664,7 @@ private void handleIncomingMessage(String json) {
                         }
                     }
                     break;
-                case "AgentV1History":
+                case "History":
                     if (agentV1HistoryHandler != null) {
                         AgentV1History event = objectMapper.treeToValue(node, AgentV1History.class);
                         if (event != null) {

src/test/java/com/deepgram/resources/agent/v1/websocket/V1WebSocketClientTest.java

@@ -0,0 +1,107 @@
+package com.deepgram.resources.agent.v1.websocket;
+
+import static org.assertj.core.api.Assertions.assertThat;
+
+import com.deepgram.core.ClientOptions;
+import com.deepgram.core.Environment;
+import com.deepgram.resources.agent.v1.types.AgentV1History;
+import com.deepgram.resources.agent.v1.types.AgentV1HistoryContent;
+import com.deepgram.resources.agent.v1.types.AgentV1HistoryContentRole;
+import com.deepgram.resources.agent.v1.types.AgentV1HistoryFunctionCalls;
+import java.lang.reflect.Method;
+import java.util.concurrent.atomic.AtomicReference;
+import org.junit.jupiter.api.DisplayName;
+import org.junit.jupiter.api.Test;
+
+class V1WebSocketClientTest {
+
+    @Test
+    @DisplayName("dispatches History conversation text messages to the typed history handler")
+    void dispatchesHistoryConversationMessages() throws Exception {
+        V1WebSocketClient client = createClient();
+        AtomicReference<AgentV1History> history = new AtomicReference<>();
+        AtomicReference<Exception> error = new AtomicReference<>();
+        client.onAgentV1History(history::set);
+        client.onError(error::set);
+
+        invokeHandleIncomingMessage(client, "{\"type\":\"History\",\"role\":\"user\",\"content\":\"hello\"}");
+
+        assertThat(error.get()).isNull();
+        assertThat(history.get()).isNotNull();
+
+        String variant = history.get().visit(new AgentV1History.Visitor<String>() {
+            @Override
+            public String visit(AgentV1HistoryContent value) {
+                assertThat(value.getType()).isEqualTo("History");
+                assertThat(value.getRole()).isEqualTo(AgentV1HistoryContentRole.USER);
+                assertThat(value.getContent()).isEqualTo("hello");
+                return "content";
+            }
+
+            @Override
+            public String visit(AgentV1HistoryFunctionCalls value) {
+                return "function_calls";
+            }
+        });
+
+        assertThat(variant).isEqualTo("content");
+    }
+
+    @Test
+    @DisplayName("dispatches History function call messages to the typed history handler")
+    void dispatchesHistoryFunctionCallMessages() throws Exception {
+        V1WebSocketClient client = createClient();
+        AtomicReference<AgentV1History> history = new AtomicReference<>();
+        AtomicReference<Exception> error = new AtomicReference<>();
+        client.onAgentV1History(history::set);
+        client.onError(error::set);
+
+        invokeHandleIncomingMessage(
+                client,
+                "{" +
+                "\"type\":\"History\"," +
+                "\"function_calls\":[{" +
+                "\"id\":\"fc_123\"," +
+                "\"name\":\"lookup_weather\"," +
+                "\"client_side\":true," +
+                "\"arguments\":\"{\\\"city\\\":\\\"London\\\"}\"," +
+                "\"response\":\"sunny\"" +
+                "}]}" );
+
+        assertThat(error.get()).isNull();
+        assertThat(history.get()).isNotNull();
+
+        String variant = history.get().visit(new AgentV1History.Visitor<String>() {
+            @Override
+            public String visit(AgentV1HistoryContent value) {
+                return "content";
+            }
+
+            @Override
+            public String visit(AgentV1HistoryFunctionCalls value) {
+                assertThat(value.getType()).isEqualTo("History");
+                assertThat(value.getFunctionCalls()).hasSize(1);
+                assertThat(value.getFunctionCalls().get(0).getId()).isEqualTo("fc_123");
+                assertThat(value.getFunctionCalls().get(0).getName()).isEqualTo("lookup_weather");
+                assertThat(value.getFunctionCalls().get(0).getClientSide()).isTrue();
+                assertThat(value.getFunctionCalls().get(0).getArguments()).isEqualTo("{\"city\":\"London\"}");
+                assertThat(value.getFunctionCalls().get(0).getResponse()).isEqualTo("sunny");
+                return "function_calls";
+            }
+        });
+
+        assertThat(variant).isEqualTo("function_calls");
+    }
+
+    private static V1WebSocketClient createClient() {
+        ClientOptions clientOptions =
+                ClientOptions.builder().environment(Environment.PRODUCTION).build();
+        return new V1WebSocketClient(clientOptions);
+    }
+
+    private static void invokeHandleIncomingMessage(V1WebSocketClient client, String json) throws Exception {
+        Method handleIncomingMessage = V1WebSocketClient.class.getDeclaredMethod("handleIncomingMessage", String.class);
+        handleIncomingMessage.setAccessible(true);
+        handleIncomingMessage.invoke(client, json);
+    }
+}