aionui-troubleshooting

AionUi Troubleshooting

Use the bundled aioncore diagnose CLI for read-only troubleshooting. It uses the runtime context injected into the current agent conversation, so do not discover ports or call backend endpoints by hand.

Examples in this skill use English. When reporting findings or writing user content, use the user's language.

Rules

1. Use only "$AIONUI_HELPER_BIN" diagnose ....
2. Start with diagnose overview for broad "what is wrong" requests.
3. Use named diagnose commands first. Use diagnose http get only when no named command covers the diagnostic need.
4. Treat every command as read-only. To change AionUi configuration, use the separate aionui-config skill.
5. Never print raw provider, MCP header, token, password, or secret values. The CLI redacts known secret fields by default, but summarize sensitive findings carefully.
6. A single running snapshot does not prove a hang. Re-check the same conversation and compare runtime fields, message progress, and logs.

Capability Discovery

When unsure which command or stdin fields are available, ask the CLI:

"$AIONUI_HELPER_BIN" diagnose capabilities

The output is the agent-readable contract: domains, command names, stdin JSON fields, selector behavior, redacted fields, and the controlled HTTP escape hatch.

Runtime Context

The main stable selector is the current conversation:

{
  "conversation_id": "current"
}

The CLI resolves "current" from AIONUI_CONVERSATION_ID. Commands that read the backend also use AIONUI_BASE_URL and AIONUI_USER_ID from the same runtime context.

Start Wide

For a vague "AionUi is broken" report, run:

"$AIONUI_HELPER_BIN" diagnose overview

Use the overview to decide where to drill in:

• providers.unhealthy means inspect provider health.
• mcp.enabled_but_no_tools means inspect MCP startup/tool registration.
• cron.failing means inspect scheduled task state. If cron.failing is empty but cron issues are suspected, fall back to diagnose cron summary and check all[].state.last_status directly.
• running_conversations means inspect the conversation runtime repeatedly.

Commands By Symptom

Conversation Stuck Or Errored

Inspect the current conversation:

"$AIONUI_HELPER_BIN" diagnose conversations get <<'JSON'
{
  "conversation_id": "current"
}
JSON

Inspect a known conversation:

"$AIONUI_HELPER_BIN" diagnose conversations get <<'JSON'
{
  "conversation_id": "conv_123"
}
JSON

Read recent messages:

"$AIONUI_HELPER_BIN" diagnose conversations messages <<'JSON'
{
  "conversation_id": "current",
  "limit": 30,
  "errors_only": true
}
JSON

Interpretation:

• state=running with is_processing=true is only a suspected hang after repeated checks show no turn_id, runtime, or message progress.
• state=waiting_confirmation or pending_confirmations > 0 means the turn is waiting for user approval, not hung.

Provider Or Model Failure

"$AIONUI_HELPER_BIN" diagnose providers summary

Look for non-healthy model health, stale last_check, high latency, or an error string. The summary is redacted; do not ask for raw provider JSON unless the named command is insufficient.

Scheduled Task Did Not Run

"$AIONUI_HELPER_BIN" diagnose cron summary

Top-level fields: enabled, name, id. Run-state fields are nested under state: state.last_status, state.last_error, state.run_count, state.retry_count, state.next_run_at_ms, state.last_run_at_ms (timestamps are millisecond epoch integers, not human dates).

MCP Server Has No Tools

"$AIONUI_HELPER_BIN" diagnose mcp summary

An enabled server with tool_count=0 usually means startup failed, the command is unavailable, credentials are invalid, or the server crashed before tool registration.

Team Member Hung

"$AIONUI_HELPER_BIN" diagnose teams summary

Find the member's conversation_id, then drill into that conversation:

"$AIONUI_HELPER_BIN" diagnose conversations get <<'JSON'
{
  "conversation_id": "member_conv_123"
}
JSON

Backend Health

"$AIONUI_HELPER_BIN" diagnose health

Use this to confirm the backend is reachable and read the core version/build metadata.

Logs

Tail logs when the runtime provides AIONUI_LOG_DIR:

"$AIONUI_HELPER_BIN" diagnose logs tail <<'JSON'
{
  "lines": 100,
  "errors_only": true,
  "conversation_id": "current"
}
JSON

If AIONUI_LOG_DIR is unavailable and the user gives a log directory, pass it explicitly:

"$AIONUI_HELPER_BIN" diagnose logs tail <<'JSON'
{
  "log_dir": "/Users/alex/Library/Logs/AionUi",
  "lines": 100,
  "errors_only": true,
  "conversation_id": "conv_123"
}
JSON

Known benign noise: No onPostToolUseHook found for tool use ID warnings can appear around tool calls and are not automatically the root cause.

Controlled HTTP Escape Hatch

Use this only when a named command does not cover the diagnostic read.

"$AIONUI_HELPER_BIN" diagnose http get <<'JSON'
{
  "path": "/api/teams",
  "reason": "Inspect team fields not covered by diagnose teams summary."
}
JSON

Constraints:

• GET only.
• Path must be /health or start with /api/.
• Output is redacted and may be truncated.
• Prefer adding a named CLI command later if the same raw read becomes common.

Data Source Map

Concern	Command
Backend alive / version	diagnose health
Cross-domain snapshot	diagnose overview
Conversation runtime	diagnose conversations get
Conversation messages	diagnose conversations messages
Provider health	diagnose providers summary
Scheduled jobs	diagnose cron summary
MCP servers	diagnose mcp summary
Teams and member state	diagnose teams summary
Logs	diagnose logs tail
Uncovered read-only API	diagnose http get

Safety Notes

• This skill diagnoses; it does not repair.
• For configuration changes, switch to aionui-config.
• For scheduled task creation or updates, use the cron skill or aionui-config cron commands.
• When reporting results, explain evidence and uncertainty: "suspected stuck" after one snapshot, "confirmed stuck" only after repeated unchanged snapshots.