fix(agent): make UpdateListen provider shim a merged shape, not a union

The union-based shim fixed construction and `model` reads but left a third
regression: property access on a union requires the property on every arm, so
reads of the V2-only tuning fields (eot_threshold, eager_eot_threshold,
eot_timeout_ms, language_hints) failed with TS2339 because the generated union's
V1 arm lacks them. No union can fix that.

Model the field as a single merged shape instead: Omit<DeepgramListenProviderV2,
'version'> (keeping every previously-readable field readable and `model`
required) with `version` widened to string for the new v1/v2 selection, plus the
two V1-only fields as optional additions. Deriving from DeepgramListenProviderV2
means future V2 field changes flow through automatically.

Verified against a main worktree: all three pre-regen patterns compile and the
new explicit v1 selection also works, so the field is now a strict superset of
main. Extends the regression coverage to all three break modes.

Author: GregHolmes

src/api/resources/agent/resources/v1/types/AgentV1UpdateListen.ts

@@ -14,34 +14,49 @@ export namespace AgentV1UpdateListen {
      * Listen configuration to update. Contains a provider object with the same schema as Settings. The model and language can be changed mid-session.
      */
     export interface Listen {
-        /**
-         * Backward-compat shim: the 2026-07-31 regen repointed this field from
-         * `DeepgramListenProviderV2` to the new `AgentV1UpdateListenListenProvider`
-         * union, whose `V1`/`V2` variants both redeclare the `version` discriminant as
-         * REQUIRED. `DeepgramListenProviderV2.version` is optional, so pre-existing
-         * callers that omitted it — `{ type: "deepgram", model: "flux-general-en" }` —
-         * stopped compiling (TS2322).
-         *
-         * We union the bare `DeepgramListenProviderV2` back in so those call sites keep
-         * working, while the generated union still offers the new explicit v1/v2
-         * selection. Compile-compat only: the serialized payload is unchanged, and the
-         * spec actually RELAXED this field (its own docs dropped "the provider identity
-         * (type, version, model) is required and must match the current session"), so
-         * requiring `version` looks like a generator modeling artifact rather than
-         * intent. Drop this shim if the generator stops requiring the discriminant.
-         *
-         * The `& { model: string }` intersection pins the second half of the same
-         * regression: the generated union's `V1` arm declares `model?`, which widened
-         * reads of `provider.model` from `string` to `string | undefined`. `model` was
-         * required here before the regen, so re-requiring it restores the previous
-         * contract on both construction and reads, and only tightens the brand-new
-         * (never-released) v1 arm.
-         *
-         * Regression coverage in tests/unit/regen-constraints.test.ts (also gated by
-         * `make typecheck-tests`).
-         */
-        provider: (Deepgram.agent.AgentV1UpdateListenListenProvider | Deepgram.DeepgramListenProviderV2) & {
-            model: string;
-        };
+        provider: AgentV1UpdateListen.Provider;
     }
+
+    /**
+     * Backward-compat shim for `AgentV1UpdateListen.Listen.provider`.
+     *
+     * Before the 2026-07-31 regen this field was plain `DeepgramListenProviderV2`. The
+     * regen repointed it at the new `AgentV1UpdateListenListenProvider` union
+     * (`V1 | V2`), which broke three things at once for existing callers:
+     *
+     *   1. Both union arms redeclare the `version` discriminant as REQUIRED, while
+     *      `DeepgramListenProviderV2.version` is optional — so
+     *      `{ type: "deepgram", model: "flux-general-en" }` stopped compiling (TS2322).
+     *   2. The `V1` arm declares `model?`, widening reads of `provider.model` from
+     *      `string` to `string | undefined`.
+     *   3. Property access on a union requires the property on EVERY arm, so reads of
+     *      the V2-only fields (`eot_threshold`, `eager_eot_threshold`, `eot_timeout_ms`,
+     *      `language_hints`) started failing with TS2339 — the `V1` arm lacks them.
+     *
+     * No union can fix (3), so we model the field as a single merged shape instead:
+     * the V2 provider (which keeps every previously-readable field readable, and keeps
+     * `model` required) with `version` widened to `string` for the new v1/v2 selection,
+     * plus the two V1-only fields as optional additions. Deriving from
+     * `DeepgramListenProviderV2` means future V2 field changes flow through
+     * automatically; only the V1-only extras are hand-listed.
+     *
+     * Compile-compat only — the serialized payload is unchanged. The trade-off is that
+     * nonsensical mixtures (`version: "v1"` alongside `eot_threshold`) type-check; the
+     * API ignores what does not apply. Note the spec itself RELAXED this field (its docs
+     * dropped "the provider identity (type, version, model) is required and must match
+     * the current session"), so the required discriminant looks like a Fern modeling
+     * artifact — replace this shim with the generated union once the generator stops
+     * requiring `version`.
+     *
+     * Regression coverage in tests/unit/regen-constraints.test.ts (also gated by
+     * `make typecheck-tests`).
+     */
+    export type Provider = Omit<Deepgram.DeepgramListenProviderV2, "version"> & {
+        /** `v1` selects the legacy Listen API; `v2` (the default) selects Flux. Open per the spec. */
+        version?: string | undefined;
+        /** v1 only: language code to switch to mid-session. */
+        language?: string | undefined;
+        /** v1 only: applies smart formatting to improve transcript readability. */
+        smart_format?: boolean | undefined;
+    };
 }

tests/unit/regen-constraints.test.ts

@@ -223,6 +223,40 @@ describe("2026-07-31 regen constraints", () => {
             expect(v1.listen.provider.model).toBe("nova-3");
             expect(v2.listen.provider.model).toBe("flux-general-en");
         });
+
+        it("keeps `model` reading as a required string (not string | undefined)", () => {
+            const msg: Deepgram.agent.AgentV1UpdateListen = {
+                type: "UpdateListen",
+                listen: { provider: { type: "deepgram", model: "flux-general-en" } },
+            };
+            // Compile-time assertion: the V1 arm of the generated union declares
+            // `model?`, which would widen this to `string | undefined`.
+            const model: string = msg.listen.provider.model;
+            expect(model).toBe("flux-general-en");
+        });
+
+        it("keeps the V2-only tuning fields READABLE off provider", () => {
+            // Property access on a union requires the property on every arm, so these
+            // reads broke with TS2339 once the V1 arm (which lacks them) was introduced.
+            const msg: Deepgram.agent.AgentV1UpdateListen = {
+                type: "UpdateListen",
+                listen: {
+                    provider: {
+                        type: "deepgram",
+                        model: "flux-general-multi",
+                        eot_threshold: 0.7,
+                        eager_eot_threshold: 0.4,
+                        eot_timeout_ms: 4000,
+                        language_hints: ["en", "es"],
+                        keyterms: ["Deepgram"],
+                    },
+                },
+            };
+            const p = msg.listen.provider;
+            expect([p.eot_threshold, p.eager_eot_threshold, p.eot_timeout_ms]).toEqual([0.7, 0.4, 4000]);
+            expect(p.language_hints).toEqual(["en", "es"]);
+            expect(p.keyterms).toEqual(["Deepgram"]);
+        });
     });
 
     describe("listen v2 ForceEndTurn", () => {