Skip to content

feat(agent): add custom Think provider events - #392

Merged
GregHolmes merged 4 commits into
mainfrom
gh/feat-agent-think-provider-events
Nov 20, 2026
Merged

GregHolmes merged 4 commits into
mainfrom
gh/feat-agent-think-provider-events

Conversation

@GregHolmes

Copy link
Copy Markdown
Collaborator

Proposed changes

  • Add experimental typed custom Think-provider request and response events.
  • Add payload validation, optional channel routing, default-handler support, tests, documentation, and a text-only example.

Validation

  • go test -v -run Test_ ./...
  • Focused custom-provider wire and routing tests.

Further comments

The provider contract is experimental. Production round-trip validation requires CUSTOM_THINK_PROVIDER_URL for a controlled wss:// custom Think endpoint; the internal Deepgram credential alone is insufficient. History and unrelated runtime controls remain out of scope.

@dg-coreylweathers dg-coreylweathers left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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:253 with "Experimental:".
  • Biggest rebase of the agent trio (7 files conflict with #391), so I'd land it last.

@dg-coreylweathers dg-coreylweathers left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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.

@GregHolmes
GregHolmes force-pushed the gh/feat-agent-think-provider-events branch from fdf0bbc to 4d43eb0 Compare November 5, 2026 12:00
@GregHolmes
GregHolmes force-pushed the gh/feat-agent-think-provider-events branch from 4d43eb0 to a0f5641 Compare November 16, 2026 11:47
@GregHolmes

Copy link
Copy Markdown
Collaborator Author

@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 dg-coreylweathers left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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 in DefaultChanHandler.Run()). It ends with fmt.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 behind if 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 the response.Content dump behind dch.debugWebsocket/klog, matching the 10 other handlers in the file.

Should-fix

  • [S1] pkg/client/agent/v1/websocket/client_channel.go:258 — still return 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't errors.Is match 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 in websocket.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 return common.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 packages ok, including the new tests/unit_test/agent package. PASS.
  • go test -race -count=10 on 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) through Think.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 the Test_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.go Start()). 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/CustomFromThinkProviderResponse doc comments both say "This is an experimental Voice Agent message/event." PASS — clearly marked per AGENTS.md's additive/documented requirement.
  • Routing: CustomFromThinkProviderChan is an optional interface (checked with a type assertion in chan_router.go and NewChanRouter), and unrouted responses fall back to the unhandled channel (Test_CustomFromThinkProviderFallsBackToUnhandled passes) 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 in Content), 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 DefaultChanHandler out 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.

GregHolmes added a commit that referenced this pull request Nov 16, 2026
## 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
@GregHolmes
GregHolmes force-pushed the gh/feat-agent-think-provider-events branch from a0f5641 to 70c9a7e Compare November 19, 2026 11:09
@GregHolmes

Copy link
Copy Markdown
Collaborator Author

@dg-coreylweathers — rebased #392 onto current main and addressed the request-changes findings in 70c9a7e.

  • DefaultChanHandler now prints only the custom Think-provider response label; debug output records object length without logging Content. The logging regression test sends a secret-bearing custom response and asserts it is absent from stdout and klog.
  • SendCustomToThinkProvider now wraps common.ErrInvalidJSON; its unit test verifies errors.Is.
  • Removed the redundant configuration-settings marshal before WriteJSON.

Verified with:

  • go test -race -count=30 ./pkg/api/agent/v1/websocket -run "^Test_DefaultChanHandlerDoesNotLogPayloads$"
  • go test -race -count=10 ./tests/unit_test/agent -run "^Test_Custom"
  • go test -v -run Test_ ./...

Could you please re-review?

@dg-coreylweathers dg-coreylweathers left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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_DefaultChanHandlerDoesNotLogPayloads pushes 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:249 wraps common.ErrInvalidJSON with %w and the test checks it with errors.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=10 on 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.

@dg-coreylweathers dg-coreylweathers left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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 TypeCustomToThinkProvider constant 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.ErrInvalidJSON so callers can errors.Is it, 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).

@dg-coreylweathers dg-coreylweathers left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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.

@GregHolmes
GregHolmes merged commit 85c1b1f into main Nov 20, 2026
7 of 8 checks passed
GregHolmes added a commit that referenced this pull request Nov 20, 2026
🤖 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>
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants