debug-runs
/debug-runs
Find and read the agent chat runs behind a run id, a user's email, or an object id or link (deck, design, dashboard, document, plan, recording, …) in any app, then work out what failed or why the object looks the way it does. Use when someone reports a broken chat, a failed run, or a bad result and gives you any of those instead of a thread.
- Author
- builderio ↗
- Repository
- agent-native ↗
- Licence
- MIT
- Last repository change
- 13.11.2026
Assessment and security
- Files in this package
- 1
- Scripts
- 0
- HTML comments
- 0
- URLs in SKILL.md
- 1
No signals detected. Repository changed on 13.11.2026, without references to retired models or APIs.
MIT, open: use and modify while retaining author attribution.
What it does and when to use it
Find and read the agent chat runs behind a run id, a user's email, or an object id or link (deck, design, dashboard, document, plan, recording, …) in any app, then work out what failed or why the object looks the way it does. Use when someone reports a broken chat, a failed run, or a bad result and gives you any of those instead of a thread.
Original author description
Find and read the agent chat runs behind a run id, a user's email, or an object id or link (deck, design, dashboard, document, plan, recording, …) in any app, then work out what failed or why the object looks the way it does. Use when someone reports a broken chat, a failed run, or a bad result and gives you any of those instead of a thread.
How it works
- 1. Find the runs
- 2. Read a thread
- 3. Diagnose
- Retention
- Rules
SKILL.md preview
--- name: debug-runs description: >- Find and read the agent chat runs behind a run id, a user's email, or an object id or link (deck, design, dashboard, document, plan, recording, …) in any app, then work out what failed or why the object looks the way it does. Use when someone reports a broken chat, a failed run, or a bad result and gives you any of those instead of a thread. scope: dev metadata: internal: true --- # Debug Runs `scripts/debug-runs.ts` reads production app databases (read-only, one transaction per query) and turns a run id, email, or object id into the chats and runs that touched it, with the full conversation. It needs `<APP>_DATABASE_URL` entries in the repo-root `.env` or `DATABASE_URL` in `templates/<app>/.env`. A worktree without its own `.env` falls back to the main checkout's. An app whose credentials fail shows up as an `error` entry; it was not searched, which is not the same as "nothing found". ## 1. Find the runs ```bash pnpm exec tsx scripts/debug-runs.ts find <input> [--app NAME] [--days 30] [--limit 20] ``` | Input | Example | How it is matched | |---|---|---| | Run id | `run-1700000000000-example` | live `agent_runs`/traces, else the thread active at the timestamp inside the id | | Email | `user@example.com` | threads they own, plus their MCP/A2A calls | | Object link | `https://slides.agent-native.com/deck/EXAMPLE_deck1` | app from the host, id from the path | | Bare object id | `EXAMPLE_design1` | every app: thread scope, owner lookup, owner's threads, audit inputs | Prefer the link over a bare id: it searches one app and also scans that app's audit log even when the object was deleted. `--app` does the same for a bare id. Each `results[]` entry is one app: - `owners`: the table the object lives in and its owner. - `threads[]`: `matchedBy`, title, owner, scope, and `runs[]` with status, error, model, and timing. - `externalAgentSessions`: calls from Claude Code, Codex, ChatGPT, and other MCP/A2A clients, grouped by client with 30-minute gaps. Their conversation lives in that client; only the calls reached us. - `uiSessions`: audited UI edits to the object outside any chat. - `auditError`: the audit scan timed out; rerun with a smaller `--days`. ## 2. Read a thread ```bash pnpm exec tsx scripts/debug-runs.ts show <runId | threadId> [--app NAME] ``` This writes `.tmp/debug-runs/<app>-<threadId>.md` and a `.json` beside it. The `.md` has the run list, live run rows, terminal run events, failed trace spans, versions the thread wrote, audited actions, and the transcript: user messages, assistant text, reasoning, and every tool call with its arguments and result. Long values are capped in the `.md`; the `.json` has them whole, plus the raw `thread_data`, including `_debugPrompts`, the system prompt of each run. ## 3. Diagnose **What failed.** Start at the failed run's `error`, then the last tool call before it. `result: (none recorded…)` means the run died inside that call. Then check the terminal event and failed spans, if they are still retained. A `runs[].screen` value is what the user was looking at when the run started. For a provider `ERROR ID`, search Sentry (the `sentry-cli` skill) by the user's email and the run's time window; run and thread ids sit in event extras, not tags. **Why it looks like this.** The "versions written by this thread" section links each saved version to its `runId`/`turnId`, in apps that keep versions (Analytics, Content, Design, Plan, Slides). Diff the version before and after the run in that app's versions table. Elsewhere, follow the mutating tool calls on the object in order. `uiSessions` and `externalAgentSessions` show edits that came from outside this chat. ## Retention | Data | Kept | |---|---| | `chat_threads.thread_data` (the full conversation) | until the user deletes the chat | | `agent_runs`, `agent_run_events` | 24h after success, 7 days after an error | | `agent_trace_spans`, `agent_trace_summaries` | 30 days | | `agent_audit_log` | 365 days | A deleted chat is gone; its audit rows remain. Threads created before May 2026 have no run ids, so `runs[]` is empty and only the transcript is available. ## Rules - This is customer data. Keep it in `.tmp/`. Never paste transcripts, emails, or object contents into GitHub, Slack, Jira, or commits; summarize the cause and cite ids. - For ad-hoc SQL beyond the script, stay read-only and never `LIKE` across `chat_threads.thread_data` without an `owner_email` or time filter. Design's table alone is over 1 GB, and an unfiltered scan times out against production.
Versions
The database has no other skills named debug-runs.
Database snapshot: 13.11.2026 · package version 8368fd3c2500 (SHA-256 digest of the entire package)
Downloads in the last 30 days: 0 · ranking
Report a problem with this skill: harmful content, incorrect descriptions or an author’s removal request.
Similar skills
- 100t3-side-chat
Read the user's T3 Code chats (projects, threads, transcripts) so a terminal agent can work as a side chat alongside a T3 Code agent. Use when the user mentions T3 / T3 Code, a T3 thread or project, a t3-thread:// link, or refers to "the other chat", "the agent in T3", or a… - 100error-shape-for-agents
Return errors an agent can act on: what failed, why, and the next call that would work. Use when a tool can fail because of bad arguments, missing files or an empty result - 100debug-production
Debug a running Last Light instance (usually production) via the `lastlight` CLI instead of SSH. Use when investigating a failed/stuck workflow, a bad agent run, a phase error, or "why didn't the bot do X" — anything that previously meant SSHing in to read SQLite or session logs. - 100codex-thread-reader
Locate and read a Codex thread by a codex thread link, thread id, or rollout path across all local CODEX_HOME directories (~/.codex, ~/.codex-gpt, ...). Use when the user pastes a codex:// link, asks to understand the 前因后果 of a Codex session, wants a timeline of what a… - 100debug-comfy-workflow
Diagnose a VibeComfy or ComfyUI workflow that fails validation, conversion, node/model resolution, runtime execution, or output production. Use when the user asks why a workflow does not run, has missing nodes/models, validation errors, bad wiring, failed RunPod/local runs, or… - 100running-chat-assistant
Runs and tests a Robomotion Chat Assistant flow (one that starts at Robomotion.ChatAssistant.ChatIn) the way its users meet it: as an Agent, in the real Chat Assistant page. `robomotion agent` pushes the flow, makes the agent and its robot, starts it on this machine and chats…