Repository navigation
feat(agent): add custom Think provider events - #392
Conversation
dg-coreylweathers
left a comment
There was a problem hiding this comment.
The experimental events look right. __customToThinkProvider serializes correctly, invalid JSON gets rejected client-side, and the experimental labeling is there. I couldn't verify the __customFromThinkProvider round trip live without a wss provider, so that part is unit-tested only.
One thing: the redaction commit goes beyond the agent. It removes the stdout ConfigurationSettings: print (client_channel.go:103), which on main leaks think/speak provider keys and headers, and it changes WriteJSON logging for every product (common/v1/websocket.go:485). It's a good fix, but squashed into a feat: it disappears from the changelog. Can you split it into its own fix: PR, or at least name it in the squash message?
Nits:
- README ~417: say the server silently ignores this without a
wss://custom endpoint. - Start the godoc at
client_channel.go:253with "Experimental:". - Biggest rebase of the agent trio (7 files conflict with #391), so I'd land it last.
dg-coreylweathers
left a comment
There was a problem hiding this comment.
Adding one to my earlier list: client_channel.go:258 returns fmt.Errorf("...must be valid JSON"), which callers can't match with errors.Is. #386 adds common.ErrInvalidJSON, so return that (or wrap it with %w) so both raw-JSON paths fail the same way.
Nit: _, marshalErr2 := json.Marshal(clone) now marshals only to check the error.
fdf0bbc to
4d43eb0
Compare
4d43eb0 to
a0f5641
Compare
|
@dg-coreylweathers — could you please re-review the current PR branch when you have a chance? The custom Think-provider event surface, example, and accompanying redaction changes are ready for another pass. |
dg-coreylweathers
left a comment
There was a problem hiding this comment.
Review: deepgram-go-sdk #392, feat(agent): add custom Think provider events
Verdict: request-changes
Blocking
- [B1]
pkg/api/agent/v1/websocket/chan_default.go:449-471(the new "custom Think provider response channel" goroutine inDefaultChanHandler.Run()). It ends withfmt.Printf("\n\n[CustomFromThinkProviderResponse]\n%s\n\n", response.Content), which dumps the full provider response body to stdout unconditionally, every time. Every other handler in this same file (Open, Welcome, ConversationText, UserStartedSpeaking, AgentThinking, FunctionCallRequest, AgentStartedSpeaking, AgentAudioDone, KeepAlive, SettingsApplied) prints only a bare[XResponse]label by default and gates the actual payload dump behindif dch.debugWebsocket { ... klog.V(2) ... }. This new handler breaks that pattern and is exactly the class of bug sibling PR #402 ("fix(websocket): redact control payload logs", currently open/unmerged) exists to fix elsewhere. Fix: print only the label unconditionally and move theresponse.Contentdump behinddch.debugWebsocket/klog, matching the 10 other handlers in the file.
Should-fix
- [S1]
pkg/client/agent/v1/websocket/client_channel.go:258— stillreturn fmt.Errorf("custom Think provider content must be valid JSON"). This is the exact line Corey flagged on 2026-10-30 (at commit fdf0bbc): callers can'terrors.Ismatch it.common.ErrInvalidJSON(the PR #386 sentinel this comment asked for) is merged and already in use elsewhere in this same package family (pkg/client/common/v1/constants.go:38-39, used inwebsocket.go:611). Not a blocked dependency — it's available now and simply wasn't changed. Fix:return fmt.Errorf("custom Think provider content must be valid JSON: %w", common.ErrInvalidJSON)or just returncommon.ErrInvalidJSON.
Nits
- [N1]
pkg/client/agent/v1/websocket/client_channel.go:103—_, marshalErr2 := json.Marshal(clone)still marshals only to check for an error, discarding the bytes;c.WriteJSON(clone)two lines later marshals the same map again. This is the nit Corey raised on the same Oct 30 comment; it's unchanged.
Verified (evidence)
- Build/vet/full test suite in Docker (
dg-go-sdk-test, Go 1.23):go build ./...exit 0,go vet ./...exit 0,go test -run Test_ ./...all packagesok, including the newtests/unit_test/agentpackage. PASS. go test -race -count=10on the new agent tests (Test_AgentStartDoesNotLogSettingsEndpoints,Test_SendCustomToThinkProviderWirePayloads,Test_CustomToThinkProviderValidation,Test_CustomFromThinkProvider*): all 10 iterations pass, no races. PASS.gh pr checks 392: mdlint, Go Tests, Lint, Title Check all pass — consistent with my own Docker run.- Redaction test exists and does what was asked:
tests/unit_test/agent/agent_think_provider_events_test.go:229(Test_AgentStartDoesNotLogSettingsEndpoints) pushes a known secret (header-secret-token) throughThink.Endpoint.Headers, captures klog+stdout at-v=6, and asserts the secret never appears — while separately confirming the real settings frame on the wire still carries it. Same pattern as theTest_WSClientDoesNotLogPayloads-style check asked for. PASS as a test, but see B1: it covers the outbound settings path, not the default handler printing an inbound custom-provider response path, which is where the new leak is. common.WriteJSON(pkg/client/common/v1/websocket.go:598) was changed in this PR from logging the full payload (klog.V(6).Infof("payload: %s\n", string(byData))) to length-only ("payload length: %d\n"). This is a real, global fix and directly addresses the redaction ask for the outbound path. PASS.- The unconditional
print("ConfigurationSettings: ")/fmt.Println(string(byteData))/klog.V(4)dump of the full cleaned settings (which would include Think endpoint/auth config) that existed before this PR was deleted outright (client_channel.goStart()). PASS — this was the worst leak and it's gone. - Experimental labeling: README.md adds "Experimental custom Think providers... Do not use this experimental feature for production traffic until you have verified the provider contract in your account," and the new
CustomToThinkProvider/CustomFromThinkProviderResponsedoc comments both say "This is an experimental Voice Agent message/event." PASS — clearly marked per AGENTS.md's additive/documented requirement. - Routing:
CustomFromThinkProviderChanis an optional interface (checked with a type assertion inchan_router.goandNewChanRouter), and unrouted responses fall back to the unhandled channel (Test_CustomFromThinkProviderFallsBackToUnhandledpasses) rather than being dropped silently. PASS — existing handlers unaffected. - The two "new" commits pushed today (bb5011f, a0f5641) are byte-identical in diff content to the commits already reviewed on 2026-10-30 (f6f5844/fdf0bbc) — same author timestamps, only the committer date and parent (now on top of the 3.11.0 release) changed. This is a rebase, not new work; neither of Corey's two specific Oct 30 asks (S1, N1) was touched.
Needs human
- Whether a custom Think provider's response content could ever itself carry sensitive data (e.g., echoed auth/config) is a server/provider-contract question nobody here can verify without
CUSTOM_THINK_PROVIDER_URL— same caveat the PR description already states. This doesn't change the B1 finding (the pattern-break is wrong regardless of what's typically inContent), but full production validation needs that live endpoint, which is out of scope for this review. - Whether to gate the re-review strictly on B1 alone, given S1/N1 were already non-blocking COMMENTED feedback last time, is a judgment call — recommending request-changes since B1 is a genuine new default-logging regression, not a style nit.
Developer-facing messaging
- A developer using
DefaultChanHandlerout of the box today gets every custom Think provider response body printed to their stdout by default, with no way to opt out short of writing a custom handler — inconsistent with how every other Voice Agent event behaves in this same handler (label-only by default, full dump only with debug logging enabled). Once B1 is fixed, the experimental messaging in the README and doc comments is good developer-to-developer framing already — clear about scope ("does not include history or other runtime controls") and clear about the production-readiness caveat.
## Summary - stop Agent configuration settings from being written to stdout or klog - log JSON control-message lengths rather than their contents, including raw JSON - prevent marshal-error logs from stringifying the failed payload - add race-safe coverage for typed, raw, and invalid JSON payloads Extracted from #392 so the security fix can ship independently as a patch release. ## Validation - `go test -race -count=10 ./pkg/client/common/v1 -run Test_WSClientDoesNotLogJSONPayloads` - `go test -v -run Test_ ./...` - a temporary local verification script used the exported `DEEPGRAM_API_KEY` for a read-only authenticated request without displaying or persisting the credential
a0f5641 to
70c9a7e
Compare
|
@dg-coreylweathers — rebased #392 onto current
Verified with:
Could you please re-review? |
dg-coreylweathers
left a comment
There was a problem hiding this comment.
Approving ca0cfe9.
What this PR does: Adds the experimental __customToThinkProvider message (SendCustomToThinkProvider) and the __customFromThinkProvider event for Voice Agent sessions whose agent.think.endpoint.url is a wss:// custom Think provider. Replies arrive on an optional CustomFromThinkProviderChan; a handler that does not implement it still gets them on the unhandled channel.
What I checked
- Does the default handler still print the provider's reply body? No. It prints only the
[CustomFromThinkProviderResponse]label (chan_default.go:345) and debug logs only the length (:396-404);Test_DefaultChanHandlerDoesNotLogPayloadspushes a secret through the channel and confirms it never reaches stdout or klog. That was the 11-16 blocker, removed at the source rather than narrowed. - Can callers match the invalid-JSON error? Yes.
client_channel.go:249wrapscommon.ErrInvalidJSONwith%wand the test checks it witherrors.Is. - Is the frame on the wire exact? Yes. The wire test checks object, string and null payloads against a real websocket server, and the router tests cover dispatch plus the fallback to the unhandled channel. Voice Agent is channel-only, so there is no callback router to cover.
- Any races?
-race -count=10on the agent packages is clean; build, vet and the full-run Test_suite pass in Docker on Go 1.19; CI is green on this head. - Breaking changes? None. Every public change is an addition and an unknown message type is still logged, not fatal.
- Docs? README.md:469 says the server silently ignores the message without a
wss://endpoint, and the godoc leads with "Experimental:".
Not covered: the __customFromThinkProvider round trip and whether content: null is accepted; both need a real wss:// Think provider.
Heads-up, no change needed: a handler that embeds *DefaultChanHandler now inherits GetCustomFromThinkProvider, so these events go to the default label printer instead of its own GetUnhandled override. Merge order: this sits on current main; #390 and #391 touch ten of the same files, so whichever lands last rebases. Drop the co-author trailer from my commit ca0cfe9 in the squash message.
ca0cfe9 to
f2090d8
Compare
dg-coreylweathers
left a comment
There was a problem hiding this comment.
Approving f2090d8.
What this PR does: Adds the experimental __customToThinkProvider message and the __customFromThinkProvider event for Voice Agent sessions whose Think provider is a custom wss:// endpoint. Replies arrive on an optional channel; handlers without it still get them on the unhandled channel.
What I checked
- What changed since my approval on 11/19? Nothing on the public surface. The rebase onto main moved one constant, renamed a local variable in the router, trimmed a godoc sentence, and swapped a string literal for the constant in a test. The new commit f2090d8 exists because the rebase dropped the
TypeCustomToThinkProviderconstant from the first commit; it puts it back. - Do the earlier fixes still hold? Yes. The default handler prints only a label and logs only the length of the provider's reply, the regression test pushes a secret through and confirms it never reaches stdout or klog, invalid JSON wraps
common.ErrInvalidJSONso callers canerrors.Isit, and the redundant marshal is gone. - Does it pass? Yes. Build, vet, the full suite, and a ten-count race run are green in Docker on Go 1.19; CI is green on this head.
- Breaking changes? None. All 14 removed lines are gofmt realignment or the deleted marshal.
Two notes, no block
- Squash-merge, not rebase-merge: the first three commits do not compile on their own because the constant only comes back in the fourth.
- The router no longer logs at
klog.V(1)when a custom-provider reply fails to unmarshal; the error is still returned. Fine as is.
After #390 lands, this needs a rebase with three keep-both conflicts (constants.go, interfaces.go, chan_logging_test.go).
f2090d8 to
4388290
Compare
dg-coreylweathers
left a comment
There was a problem hiding this comment.
Approving 4388290.
What changed since my approval this morning: only the rebase onto main after #390 landed. Every added line is the same as in f2090d8; the three files I predicted would conflict (interfaces/constants.go, interfaces/interfaces.go, chan_logging_test.go) now carry both #390's Think Live additions and this PR's custom-provider additions, nothing from #390 was dropped, and gofmt is clean on all three.
What I checked
- Does the earlier blocker stay fixed? Yes. The default handler prints only a label for a custom provider reply and logs the length at debug level (chan_default.go:413-418); the no-leak test pushes a secret-bearing custom response and a Think Live payload and asserts neither reaches stdout or klog (chan_logging_test.go:40-70); invalid JSON wraps
common.ErrInvalidJSON(client_channel.go:307). - Does it pass? Yes. Build, vet, the full
Test_suite, and a ten-count race run on the agent packages pass in Docker on Go 1.19. CI ran on this sha; the cancelled Title Check is the concurrency group superseding a duplicate run one second later. - Breaking changes? None. The only deletions are gofmt realignment and the removed redundant marshal.
At merge: squash, not rebase-merge. The first three commits still do not compile on their own because TypeCustomToThinkProvider only arrives in the fourth. No co-author trailers on this branch.
🤖 I have created a release *beep* *boop* --- ## [3.12.0](v3.11.1...v3.12.0) (2026-11-20) ### Features * **Voice Agent:** Add experimental custom Think-provider messaging: send arbitrary JSON to a configured `wss://` provider and receive its response through an optional typed channel. ([#392](#392)) ([85c1b1f](85c1b1f)) * **Voice Agent:** Add typed `UpdateListen`, `UpdateThink`, and `ForceEndTurn` controls, with optional channels for their acknowledgements and non-fatal warnings. ([#391](#391)) ([fe06d6a](fe06d6a)) * **Voice Agent:** Add invite-only Think Live settings, mid-session updates, frustration events, dynamic filler requests, and conversational-behavior metadata. ([#390](#390)) ([bcb9a87](bcb9a87)) * **Listen v1 REST:** Add Nova-3 multilingual `LanguageHint` request options and expose normalized applied hints plus detected utterance languages in responses. ([#389](#389)) ([560027c](560027c)) * **Listen v1 WebSocket:** Add mid-stream `Configure` support for keyterms and formatting features, plus typed success and failure events for callback and channel clients. ([#388](#388)) ([47c71cf](47c71cf)) * **Management:** Add typed project usage and billing reporting, including usage and billing breakdowns, available billing fields, and purchase history. ([#395](#395)) ([eeaf3db](eeaf3db)) ### Bug Fixes * **Voice Agent:** Send the API-required `prompt` and `message` keys for `UpdatePrompt` and `InjectAgentMessage`, preventing those controls from being rejected by the service. ([#396](#396)) ([580d314](580d314)) * **Management and Auth:** Return API request failures to callers instead of returning a response with a nil error. ([#399](#399)) ([305f5c8](305f5c8)) --- This PR was generated with [Release Please](https://github.com/googleapis/release-please). See [documentation](https://github.com/googleapis/release-please#release-please). --------- Co-authored-by: github-actions[bot] <41898282+github-actions[bot]@users.noreply.github.com> Co-authored-by: Greg Holmes <greg.holmes@deepgram.com>
Proposed changes
Validation
go test -v -run Test_ ./...Further comments
The provider contract is experimental. Production round-trip validation requires
CUSTOM_THINK_PROVIDER_URLfor a controlledwss://custom Think endpoint; the internal Deepgram credential alone is insufficient. History and unrelated runtime controls remain out of scope.