Chat Runtime Debugging

Chat Runtime Debugging

Use this skill when chat requests fail, sessions do not resume, tool cards look wrong, or Plan mode/question flow stalls.

Triage Order

1. Check the browser-facing route in apps/web/src/routes/api/chat.ts.
2. Check Pi runtime creation and session hydration in apps/web/src/lib/pi/server.ts.
3. Check Plan mode state and questionnaire handling in apps/web/src/lib/pi/plan-mode.ts.
4. Check UI stream consumption in apps/web/src/routes/index.tsx.
5. Check shared tool rendering in packages/hax-design/src/components/agent-elements/tools/.

Common Checks

• /api/chat/resources should show resource loader diagnostics without needing Bedrock.
• Stored sessionFile values must resolve inside .fleet/sessions.
• Live follow-ups and aborts depend on FLEET_PI_RUNTIME_TTL_MS.
• Pi tool lifecycle events should normalize into tool-Read, tool-Write, tool-Edit, tool-Bash, or generic tool-* cards.
• Plan mode can use read, bash, grep, find, ls, questionnaire, project_inventory, and workspace_index; it must not use edit or write.

Validation

Prefer:

pnpm --filter web typecheck
pnpm --filter web lint
pnpm --filter web test src/lib/pi/plan-mode.spec.ts