---
name: dictum-sdk-debugging
description: Diagnose Dictum SDK integration failures from public events, states, errors, result shape, auth configuration, audio capture, and transport behavior. Use when Codex needs to debug microphone denial, no speech, empty audio, network retry, quota/auth errors, WebSocket/SSE/POST behavior, or incorrect host UI state.
---

# Dictum SDK Debugging

Debug from the public contract first. Do not inspect or expose raw audio, signed tokens, provider frames, or private worker internals unless the user explicitly provides server-side code to inspect.

## Workflow

1. Collect a minimal trace: SDK version if known, sanitized `createSession` config shape, public event sequence with `seq`, `type`, `state`, `timestamp`, and safe `data` fields.
2. Classify the state path: `ready`, `listening`, `paused`, `retrying`, `transcribing`, or `error`.
3. Check local auth before remote symptoms. Missing `identityToken` must surface locally as `clientnotauthenticated` plus `error`.
4. Check target ownership. React-controlled and rich-editor failures usually need a custom insertion adapter.
5. Check audio format. Custom audio capture must provide WAV `Blob` chunks.
6. Check transport rules. WebSocket is default, SSE is explicit, retry is user-triggered and POST-based.
7. Return a fix with the smallest code change and a concrete event sequence to verify afterward.

## References

- Read `references/event-state-troubleshooting.md` for state/event/error interpretation.
- Read `references/transport-and-auth-errors.md` for WebSocket, SSE, POST, retry, auth, and quota diagnostics.

## Hard Rules

- Do not treat `audiotoolong` as an error; it continues to transcription with retained audio.
- Do not expose or request raw audio in public debugging artifacts.
- Do not invent `languageunsupported`, `language_unsupported`, or similar states/events. Dictum SDK does not expose that logic.
- Do not expose WebSocket `ack` frames as public SDK events.