| name | chat-runtime-debugging |
| description | Diagnose Fleet Pi chat runtime failures, including NDJSON streams, Pi sessions, Bedrock model errors, resource loader diagnostics, queueing, aborts, and Plan mode question flow. |
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
- Check the browser-facing route in
apps/web/src/routes/api/chat.ts.
- Check Pi runtime creation and session hydration in
apps/web/src/lib/pi/server.ts.
- Check Plan mode state and questionnaire handling in
apps/web/src/lib/pi/plan-mode.ts.
- Check UI stream consumption in
apps/web/src/routes/index.tsx.
- Check shared tool rendering in
packages/ui/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 dlx tsx --test apps/web/src/lib/pi/plan-mode.test.ts
