diff --git a/README.md b/README.md index 9190d09..23de99b 100644 --- a/README.md +++ b/README.md @@ -435,6 +435,7 @@ Audio persistence and diagnostics: - To clear one session manually: `DELETE FROM session_config WHERE session_id='' AND key='lastAudioAttachment'`. - When Flynn rewrites bad model-provided audio tool args, it emits audit event `tool.args_rewritten`. - Runbook: `docs/runbooks/VOICE_TRANSCRIPTION_DEBUG.md`. +- SQLite quick reference: `docs/runbooks/SQLITE_QUICK_REFERENCE.md`. ### Text-to-Speech (TTS) Reply Audio diff --git a/docs/plans/state.json b/docs/plans/state.json index a461489..27e07e1 100644 --- a/docs/plans/state.json +++ b/docs/plans/state.json @@ -6052,6 +6052,18 @@ "docs/runbooks/VOICE_TRANSCRIPTION_DEBUG.md" ], "test_status": "docs-only update; no runtime code changes" + }, + "audit-followup-sqlite-quick-reference-runbook": { + "status": "completed", + "date": "2026-02-23", + "updated": "2026-02-23", + "summary": "Added a SQLite quick-reference runbook with high-utility operational queries for session history, session_config, tool execution diagnostics, pairing approvals, and safe backup/cleanup workflows.", + "files_modified": [ + "docs/runbooks/SQLITE_QUICK_REFERENCE.md", + "docs/runbooks/VOICE_TRANSCRIPTION_DEBUG.md", + "README.md" + ], + "test_status": "docs-only update; no runtime code changes" } }, "overall_progress": { diff --git a/docs/runbooks/SQLITE_QUICK_REFERENCE.md b/docs/runbooks/SQLITE_QUICK_REFERENCE.md new file mode 100644 index 0000000..10eb44e --- /dev/null +++ b/docs/runbooks/SQLITE_QUICK_REFERENCE.md @@ -0,0 +1,102 @@ +# SQLite Quick Reference (Flynn) + +Operational SQLite queries for fast debugging and cache management. + +## Setup + +```bash +DB=~/.local/share/flynn/sessions.db +SID='telegram:8367012007' # change per session +``` + +## 1) DB Health / Introspection + +```bash +sqlite3 "$DB" ".tables" +sqlite3 "$DB" ".schema" +``` + +## 2) Global Row Counts + +```bash +sqlite3 "$DB" "SELECT 'messages',COUNT(*) FROM messages +UNION ALL SELECT 'session_config',COUNT(*) FROM session_config +UNION ALL SELECT 'tool_executions',COUNT(*) FROM tool_executions;" +``` + +## 3) Most Recent Active Sessions + +```bash +sqlite3 "$DB" "SELECT session_id, datetime(MAX(created_at),'unixepoch','localtime') AS last_seen, COUNT(*) AS msg_count +FROM messages GROUP BY session_id ORDER BY MAX(created_at) DESC LIMIT 20;" +``` + +## 4) Recent Messages for One Session + +```bash +sqlite3 "$DB" "SELECT id, role, datetime(created_at,'unixepoch','localtime') AS ts, substr(content,1,200) +FROM messages WHERE session_id='$SID' ORDER BY id DESC LIMIT 30;" +``` + +## 5) Search Message History by Text + +```bash +sqlite3 "$DB" "SELECT session_id,id,role,datetime(created_at,'unixepoch','localtime') +FROM messages WHERE content LIKE '%audio.transcribe%' ORDER BY id DESC LIMIT 50;" +``` + +## 6) List Session Config Keys + +```bash +sqlite3 "$DB" "SELECT key, length(value) FROM session_config WHERE session_id='$SID' ORDER BY key;" +``` + +## 7) Inspect Cached Audio Across Sessions + +```bash +sqlite3 "$DB" "SELECT session_id, key, length(value) FROM session_config WHERE key='lastAudioAttachment';" +``` + +## 8) Clear One Session's Cached Audio + +```bash +sqlite3 "$DB" "DELETE FROM session_config WHERE session_id='$SID' AND key='lastAudioAttachment';" +``` + +Verify: + +```bash +sqlite3 "$DB" "SELECT session_id, key, length(value) FROM session_config WHERE key='lastAudioAttachment';" +``` + +## 9) Tool Success/Failure Summary + +```bash +sqlite3 "$DB" "SELECT tool_name, SUM(success=1) AS ok, SUM(success=0) AS fail, COUNT(*) AS total +FROM tool_executions GROUP BY tool_name ORDER BY total DESC;" +``` + +## 10) Recent Tool Failures for One Session + +```bash +sqlite3 "$DB" "SELECT id, tool_name, datetime(created_at,'unixepoch','localtime') AS ts +FROM tool_executions WHERE session_id='$SID' AND success=0 ORDER BY id DESC LIMIT 50;" +``` + +## 11) Pairing Approvals + +```bash +sqlite3 "$DB" "SELECT channel, sender_id, datetime(approved_at,'unixepoch','localtime') +FROM pairing_approved ORDER BY approved_at DESC;" +``` + +## 12) Safety Backup Before Manual Edits + +```bash +sqlite3 "$DB" ".backup '/tmp/flynn-sessions.backup.db'" +``` + +## Notes + +- `/reset` in a chat clears that session's messages/config/tool rows, including `lastAudioAttachment`. +- Prefer deleting one key for one session over broad deletes. diff --git a/docs/runbooks/VOICE_TRANSCRIPTION_DEBUG.md b/docs/runbooks/VOICE_TRANSCRIPTION_DEBUG.md index 4bb20da..9c74725 100644 --- a/docs/runbooks/VOICE_TRANSCRIPTION_DEBUG.md +++ b/docs/runbooks/VOICE_TRANSCRIPTION_DEBUG.md @@ -105,3 +105,6 @@ If `/reset` is run in that chat, it also clears the session's `lastAudioAttachme - `session.clear()` (e.g. `/reset`) removes messages, tool executions, and session config for that session. - Session TTL pruning removes stale sessions and associated config from SQLite. + +For additional operational queries (sessions, tools, pairing, backups), see: +- `docs/runbooks/SQLITE_QUICK_REFERENCE.md`