v0.42.1: OGG Opus transcribe fix + config loader overlayFile fix

- transcribe tool: whisper.cpp cannot read OGG Opus audio.
  Added convertToWAV() that auto-detects unsupported formats
  and uses ffmpeg (16kHz mono WAV) before passing to whisper.
  Best-effort — falls through to original path if ffmpeg unavailable.
- config loader: overlayFile() was missing Transcription field
  propagation. Adding transcription section to ~/.odek/config.json
  was silently ignored. Now properly propagates the pointer field.
- docs: updated CHANGELOG (v0.42.0 + v0.42.1), TELEGRAM.md
  (auto-transcribe section with OGG→WAV docs), AGENTS.md (version)

Author: molty3000

AGENTS.md

@@ -12,7 +12,7 @@ It provides context about the project's architecture, conventions, and how to up
 - **Binary:** `odek` — single static binary, ~12 MB, instant startup.
 - **Config:** Five-layer priority: `~/.odek/secrets.env` → `~/.odek/config.json` → `./odek.json` → `ODEK_*` env vars → CLI flags.
 - **Benchmark:** AIEB v2.0 — 80.3% (highest published agent score on the Autonomous Intelligence Engineering Benchmark).
-- **Version:** v0.41.1 — see latest tag at https://github.com/BackendStack21/odek/releases
+- **Version:** v0.42.1 — see latest tag at https://github.com/BackendStack21/odek/releases
 
 ## Source Layout
 
@@ -87,7 +87,7 @@ ReAct cycle: observe → think → act → repeat.
 | Zero-fork data | `math_eval` — native arithmetic, `diff` — LCS diff, `json_query` — dot-path JSON, `tr` — text transform, `base64` — encode/decode |
 | File analysis | `glob` — fast glob find, `file_info` — stat metadata, `count_lines` — streaming line count, `word_count` — streaming word count, `checksum` — SHA256/SHA1/MD5, `sort` — sort lines, `head_tail` — first/last N lines |
 | Multi-pattern | `multi_grep` — N regex patterns parallel, `tree` — structured directory tree |
-| Audio | `transcribe` — local whisper.cpp audio transcription (OGG/WAV/MP3 → text) |
+| Audio | `transcribe` — local whisper.cpp audio transcription with auto-OGG→WAV conversion via ffmpeg |
 
 All gated by the `danger` security classifier with three actions: allow, deny, prompt.
 - `shell`: Classifies commands into risk classes (safe, local_write, system_write, destructive, network_egress, code_execution, install, blocked).

cmd/odek/transcribe_tool.go

@@ -14,6 +14,36 @@ import (
 	"github.com/BackendStack21/kode/internal/danger"
 )
 
+// ── Audio Format Conversion ──────────────────────────────────────────────
+
+// convertToWAV converts an audio file to WAV format using ffmpeg if needed.
+// Returns the path to the WAV file (may be the same as input if already WAV/MP3/FLAC
+// or if ffmpeg is unavailable/fails — in which case whisper will produce its own error).
+// The caller must remove the returned path if it differs from the input path.
+func convertToWAV(srcPath string) string {
+	ext := strings.ToLower(filepath.Ext(srcPath))
+	// whisper.cpp supports WAV, MP3, FLAC natively via dr_wav/dr_mp3/dr_flac.
+	switch ext {
+	case ".wav", ".mp3", ".flac":
+		return srcPath
+	}
+
+	// Check if ffmpeg is available
+	if _, err := exec.LookPath("ffmpeg"); err != nil {
+		return srcPath
+	}
+
+	// Convert to WAV using ffmpeg — best-effort, fall through on failure.
+	dstPath := srcPath + ".wav"
+	cmd := exec.Command("ffmpeg", "-y", "-i", srcPath, "-acodec", "pcm_s16le", "-ar", "16000", "-ac", "1", dstPath)
+	if err := cmd.Run(); err != nil {
+		// If ffmpeg fails (corrupt file, unsupported codec, etc.),
+		// just pass the original path — whisper will produce its own error.
+		return srcPath
+	}
+	return dstPath
+}
+
 // ── Resolved Paths ──────────────────────────────────────────────────
 
 // whisperBinary attempts to locate the whisper CLI binary.
@@ -191,6 +221,15 @@ func (t *transcribeTool) Call(argsJSON string) (result string, err error) {
 	}
 	f.Close()
 
+	// Convert to WAV if needed (whisper.cpp doesn't support OGG Opus natively).
+	wavPath := convertToWAV(args.Path)
+	cleanup := func() {
+		if wavPath != args.Path {
+			os.Remove(wavPath)
+		}
+	}
+	defer cleanup()
+
 	// Locate whisper binary
 	binary, err := whisperBinary(t.transcriptionCfg)
 	if err != nil {
@@ -216,7 +255,7 @@ func (t *transcribeTool) Call(argsJSON string) (result string, err error) {
 	args2 := []string{
 		"--model", modelPathResolved,
 		"--output-json",
-		"--file", args.Path,
+		"--file", wavPath,
 	}
 	if lang != "" {
 		args2 = append(args2, "--language", lang)

docs/CHANGELOG.md

@@ -1,5 +1,35 @@
 # Changelog
 
+## v0.42.1 (2026-05-24) — OGG Opus Transcribe Fix
+
+### Bug Fixes
+- **transcribe tool** — whisper.cpp cannot read OGG Opus audio (`dr_wav`/`dr_mp3` limitation). Telegram voice messages are OGG Opus → produced empty transcriptions silently. Added `convertToWAV()` that auto-detects unsupported formats and uses ffmpeg (16kHz mono WAV) before passing to whisper. Best-effort: falls through to original path if ffmpeg unavailable, so whisper's own error bubbles up
+- **config loader** — `overlayFile()` was missing `Transcription` field propagation. Adding `"transcription"` to `~/.odek/config.json` was silently ignored. Now properly propagates the pointer field
+
+### Stats
+- 43 insertions across 2 files (transcribe_tool.go, loader.go)
+- All 19 packages pass with `-race`
+
+---
+
+## v0.42.0 (2026-05-24) — Session Search
+
+### New Tool: `session_search`
+- Built-in `session_search` tool — browse, search, and recall past sessions by keyword or browse most recent
+- Uses FTS5 full-text search on the sessions index JSON
+- Supports: keyword queries with OR/AND, phrase search, role filtering, prefix search
+- Returns LLM-summarized matching sessions with timestamps and previews
+- Zero new dependencies (stdlib `encoding/json` + FTS5 via sqlite)
+
+### CI
+- Bumped `softprops/action-gh-release` from v2 to v4
+
+### Stats
+- 212 insertions across 3 files
+- All tests pass with `-race`
+
+---
+
 ## v0.41.1 (2026-05-24) — Quality Hardening
 
 ### Bug Fixes

docs/TELEGRAM.md

@@ -167,7 +167,7 @@ The `Handler` struct routes incoming updates to the appropriate callback based o
 |---|---|---|
 | `OnTextMessage` | Plain text message | `(chatID int64, text string) (string, error)` |
 | `OnCommand` | Slash command (e.g. `/start`) | `(chatID int64, command, args string) (string, error)` |
-| `OnVoiceMessage` | Voice message (OGG) | `(chatID int64, fileID string) (string, error)` |
+| `OnVoiceMessage` | Voice message (OGG Opus) | `(chatID int64, messageID int, fileID string) (string, error)` |
 | `OnPhotoMessage` | Photo message | `(chatID int64, fileIDs []string) (string, error)` |
 | `OnCallbackQuery` | Inline keyboard callback | `(chatID int64, callbackData string) (string, error)` |
 
@@ -292,6 +292,21 @@ Media files are saved to `~/.odek/media/` (created automatically on first downlo
 - Saves as `photo_<truncated_fileID>.<ext>` (default extension: `.jpg`)
 - Same fileID truncation as voice downloads
 
+### Auto-Transcribe (Voice → Text)
+
+When `transcription.auto_transcribe: true` is set in config and whisper is installed, voice messages are automatically transcribed into text before reaching the agent:
+
+```
+Voice message received → DownloadVoice (OGG Opus to disk)
+                        → convertToWAV (ffmpeg: OGG→16kHz mono WAV)
+                        → whisper.cpp (local transcription)
+                        → transcribed text injected as user message
+```
+
+**OGG Opus handling:** whisper.cpp uses `dr_wav`/`dr_mp3` internally and does not support OGG Opus. The transcribe tool auto-detects unsupported formats and converts via ffmpeg. If ffmpeg is unavailable, the original file is passed to whisper which produces a clear error message.
+
+**Fallback:** If auto-transcribe fails (ffmpeg unavailable, corrupt audio, whisper error), the agent receives the file path with a suggestion to use the `transcribe()` tool manually.
+
 ## Types (`types.go`)
 
 The package defines Telegram API types used throughout:

internal/config/loader.go

@@ -905,6 +905,9 @@ func overlayFile(base, override FileConfig) FileConfig {
 	if override.InteractionMode != "" {
 		base.InteractionMode = override.InteractionMode
 	}
+	if override.Transcription != nil {
+		base.Transcription = override.Transcription
+	}
 	return base
 }