| 1 | # DeepSeek TUI Operations Runbook |
| 2 | |
| 3 | This runbook covers practical debugging and incident response for the local CLI/TUI runtime. |
| 4 | |
| 5 | ## Quick Triage |
| 6 | |
| 7 | 1. Confirm binary + config: |
| 8 | - `cargo run -- --version` |
| 9 | - `cat ~/.deepseek/config.toml` (or inspect configured profile) |
| 10 | 2. Enable verbose logs: |
| 11 | - `RUST_LOG=deepseek_cli=debug cargo run` |
| 12 | - For HTTP retries/reconnects: `RUST_LOG=deepseek_cli::client=debug cargo run` |
| 13 | 3. Capture current state: |
| 14 | - `ls ~/.deepseek/sessions` |
| 15 | - `ls ~/.deepseek/sessions/checkpoints` |
| 16 | - `ls ~/.deepseek/tasks` |
| 17 | |
| 18 | ## Incident: Turn Hangs or Stream Stops |
| 19 | |
| 20 | Symptoms: |
| 21 | - TUI remains in loading state |
| 22 | - partial assistant output with no completion |
| 23 | |
| 24 | Checks: |
| 25 | 1. Inspect retry/health logs (`deepseek_cli::client`) |
| 26 | 2. Verify endpoint connectivity: |
| 27 | - `curl -sS https://api.deepseek.com/v1/models -H "Authorization: Bearer $DEEPSEEK_API_KEY"` |
| 28 | 3. Confirm no local sandbox/permission deadlock in tool output |
| 29 | |
| 30 | Actions: |
| 31 | 1. If a foreground shell command is running, press `Ctrl+B` and choose whether to background it or cancel the current turn. |
| 32 | 2. If the command was started in the background, ask the assistant to cancel it with `exec_shell_cancel` and the returned task id. |
| 33 | 3. Use `Esc` or `Ctrl+C` to interrupt the current turn when you want to stop the request itself. |
| 34 | 4. Retry prompt; if still failing, restart TUI. |
| 35 | 5. On restart, verify the previous queued/in-flight runtime turn is shown as interrupted rather than left in a running state. |
| 36 | |
| 37 | ## Incident: Network Outage / Offline Behavior |
| 38 | |
| 39 | Expected behavior: |
| 40 | - New prompts are queued while offline mode is active |
| 41 | - Queue state persists to `~/.deepseek/sessions/checkpoints/offline_queue.json` |
| 42 | |
| 43 | Checks: |
| 44 | 1. Open queue in TUI: `/queue list` |
| 45 | 2. Confirm persisted queue file exists and updates timestamp |
| 46 | |
| 47 | Actions: |
| 48 | 1. Restore connectivity |
| 49 | 2. Re-send queued entries (from `/queue edit <n>` + Enter, or normal input flow) |
| 50 | 3. Ensure queue file clears when queue is empty |
| 51 | |
| 52 | ## Incident: Crash Recovery Needed |
| 53 | |
| 54 | Expected behavior: |
| 55 | - Checkpoint stored at `~/.deepseek/sessions/checkpoints/latest.json` |
| 56 | - Startup begins a fresh session unless `--resume`/`--continue` is supplied |
| 57 | |
| 58 | Actions: |
| 59 | 1. Resume prior work explicitly via `deepseek --resume <id>` or `Ctrl+R` in TUI |
| 60 | 2. If checkpoint inspection is needed, inspect `latest.json` for schema mismatch/details |
| 61 | 3. If schema is newer than binary supports, upgrade binary or remove stale checkpoint |
| 62 | |
| 63 | ## Incident: Persistent State Schema Errors |
| 64 | |
| 65 | Symptoms: |
| 66 | - Errors like `schema vX is newer than supported vY` |
| 67 | |
| 68 | Affected stores: |
| 69 | - sessions (`~/.deepseek/sessions/*.json`) |
| 70 | - runtime thread/turn/item records |
| 71 | - tasks (`~/.deepseek/tasks/tasks/*.json`) |
| 72 | |
| 73 | Actions: |
| 74 | 1. Confirm binary version and migration expectations |
| 75 | 2. Back up the state directory before editing |
| 76 | 3. Either: |
| 77 | - run with a newer compatible binary, or |
| 78 | - archive incompatible records and regenerate state |
| 79 | |
| 80 | ## Incident: MCP/Tool Execution Failures |
| 81 | |
| 82 | Checks: |
| 83 | 1. Validate `~/.deepseek/mcp.json` schema and server command paths |
| 84 | 2. Confirm server process can start manually |
| 85 | 3. Check sandbox denials in TUI history / logs |
| 86 | |
| 87 | Actions: |
| 88 | 1. Retry with required approvals (or YOLO only when appropriate) |
| 89 | 2. Temporarily disable failing MCP server and isolate issue |
| 90 | 3. Re-enable after verification with `/mcp` diagnostics |
| 91 | |
| 92 | ## Post-Incident Checklist |
| 93 | |
| 94 | 1. Preserve logs and relevant state files |
| 95 | 2. Record trigger, impact, and mitigation |
| 96 | 3. Add or update regression tests (retry/recovery/schema) |
| 97 | 4. Update this runbook and architecture docs if behavior changed |
| 98 |