@tencent-ai/agent-sdk 0.3.165 → 0.3.166

package/cli/dist/web-ui/docs/en/cli/troubleshooting.md

@@ -58,6 +58,50 @@ netstat -an | grep PORT_NUMBER
 
 ---
 
+## Permission Confirmation Dialog Unresponsive / Only ESC Closes It
+
+**Symptom**: The TUI shows a tool permission confirmation dialog. Pressing number keys / Enter to confirm doesn't dismiss the dialog, but ESC closes it normally — and after closing, the task has actually already started executing.
+
+### Log Location
+
+```bash
+ls -t ~/.codebuddy/logs/codebuddy-*.log | head -1   # latest log
+```
+
+You can relocate the entire config directory via the `CODEBUDDY_CONFIG_DIR` environment variable.
+
+### Key TAGs (in chronological order)
+
+A normal confirmation flow should produce the following sequence (`grep -E '\[Approve\]|\[Reject\]|\[dequeue\]|\[tool-permission\]'`):
+
+| TAG | Meaning |
+|---|---|
+| `[tool-permission] ASK ...` | A tool was intercepted and requires approval |
+| `[HandleInterruptions] Approval dialog shown` | TUI has displayed the dialog |
+| `[Approve] User approved tool: <name>` | User clicked confirm |
+| `[Approve] Deferred resolved` | Backend promise has been resolved (task starts executing here) |
+| `[dequeue] Queue empty, clearing interruptionSubject` | `pending$` cleared, dialog should disappear |
+| `[Approve] Success: ... interruption dequeued` | Full flow finished |
+
+The ESC path replaces `[Approve]` with `[Reject]`.
+
+### Symptom -> Inference
+
+| You see | Inference |
+|---|---|
+| Full TAG sequence present but dialog doesn't disappear | UI rendering is stuck (e.g., IDE closeTab RPC blocking await) |
+| `[Approve] User approved` present but `[dequeue]` missing | `findSessionByItem` failed; nearby logs will show `[Approve] Failed: Cannot find session` |
+| `dequeue Start` present but no `Queue empty` | `interruptionQueues` cannot fetch the queue (multi-session mismatch) |
+| No `[tool-permission] ASK` at all | The tool didn't go through approval — possibly `BypassPermissions` or allowed by allow rules |
+| `[tool-permission] ASK` present but no `Approval dialog shown` | TUI didn't subscribe to `pending$` (teammate concurrent session mismatch) |
+| `[Approve] Failed: No pending deferred found` | Deferred was consumed twice |
+
+### Minimum Info to Report to Developers
+
+30 consecutive lines of logs around the timestamp of the `[Approve]` / `[Reject]` / `[dequeue]` TAGs are enough to determine whether the UI didn't refresh, the backend didn't dequeue, or the IDE RPC is stuck.
+
+---
+
 ## Updates
 
 ### Auto Updates
@@ -78,6 +122,22 @@ codebuddy --version                                 # Current version
 npm view @tencent-ai/codebuddy-code version        # Latest version
 ```
 
+### Cannot Update to the Latest Version
+
+If `codebuddy update` or `npm install -g @tencent-ai/codebuddy-code@latest` consistently fails to fetch the latest version, the issue is usually caused by npm mirror cache delays. You can specify the official registry to retry:
+
+```bash
+npm install -g @tencent-ai/codebuddy-code@latest --registry=https://registry.npmjs.org/
+```
+
+Check the npm registry currently configured locally:
+
+```bash
+npm config get registry
+```
+
+If you regularly use a third-party mirror, you can temporarily specify the official registry in the update command without modifying the global configuration.
+
 ---
 
 ## Migrating from Claude Code