AI-assisted debugging

Let Claude Code, Codex, or another local agent diagnose and repair a broken UniPost integration with the unipost CLI — diagnose, explain, patch, verify, escalate.

Agent repair loop

Give the agent evidence, boundaries, and a verification command.

The debug kit turns UniPost errors into a closed loop for local agents: classify auth, inspect logs, patch safe code/config issues, then prove the fix with non-destructive verification.

Default boundary

Read freely. Patch local code when the finding says it is safe. Ask before changing secrets, uploading bundles, or doing anything in the dashboard.

doctor diagnose -> patch -> doctor verify

How it works

The unipost doctor commands emit a stable, machine-readable doctor.v1 contract under the normal CLI envelope. The agent reads the findings, applies the recommended actions according to their safety level, verifies the fix, and only escalates a redacted support bundle when it cannot resolve the problem. Code edits stay with the agent, which already understands the repository; the CLI provides trusted evidence and deterministic verification. Agents should run unipost auth status --json first. If auth is missing, run unipost init or the Dashboard setup command. If auth is metadata_only, rebind with auth login --api-key or set UNIPOST_API_KEY.

Local readiness

Classify auth

Start with the local CLI binding so the agent knows whether it can query the workspace or needs a setup step first.

bash

unipost auth status --json

Doctor payload

Find evidence

Use doctor.v1 findings and workspace logs as the source of truth instead of guessing from error text.

bash

unipost doctor diagnose --json

Recommended actions

Patch safely

Apply only actions whose safety level allows it. Ask before touching secrets, dashboards, or live product state.

text

finding.recommended_actions[]

Closed loop

Verify or escalate

Re-run verification after every patch. Generate a redacted bundle only when the issue cannot be resolved locally.

bash

unipost doctor verify --json

Install the debug skill

Install the first-party UniPost debug skill for your agent, then ask it in plain language: “Use UniPost debug to fix my integration.”

Step	What to do
1. Finish CLI auth	Run `unipost init`, the Dashboard setup command, or `auth login --api-key` until `unipost auth status --json` reports a usable credential.
2. Add agent instructions	Run `unipost agent install --client codex\|claude-code --json`, then copy the returned debug skill files into the agent-specific skills directory.
3. Start with diagnosis	Ask the agent to use UniPost debug. It should run auth status, diagnose, explain/logs commands, patch local code when safe, and verify.
4. Escalate with redaction	If local repair is not enough, create a support bundle. Uploading still requires explicit user approval.

The debugging loop

Reading doctor findings

Every unipost doctor *--json command returns the doctor payload under data. Branch on data.status and iterate data.findings; never scrape the human-readable text.

data.status	Meaning
passed	No blocking issues. The integration looks healthy.
failed	Blocking issues with safe or assisted fixes. Patch and re-verify.
input_required	A manual product step is needed (e.g. connect an account).
needs_support	Could not resolve safely. Generate a redacted support bundle.

Local project hints

doctor diagnose also inspects the current project for safe repair hints: detected frameworks, installed UniPost SDK packages, environment variable names from example files, and relative file/line hints for common issues like a missing Bearer prefix, singular account_id post payloads, or local file paths passed as media URLs. It does not read real .envcontents; those files are reported only as secret-bearing files.

Action safety levels

Each recommended action carries a safety level that tells the agent how far it may go without you.

safety	Agent rule
read_only	The agent may run it freely.
safe_to_execute_without_user	The agent may apply the code/config patch directly.
needs_user_approval	Explain first, then ask before changing it (e.g. real `.env`).
manual_only	A real dashboard/product step the user must do themselves.

Secrets and non-destructive verification

The CLI masks API keys (for example up_live_9BWr...vhzHk) and never prints OAuth tokens, cookies, or webhook secrets. unipost doctor verifyruns only non-destructive checks (auth probe, workspace read, account/health read, logs read) and never live-publishes. Live publishing requires the explicit --allow-live-publish opt-in.

Escalating to support

When the agent cannot resolve the issue, unipost doctor support-bundle --jsonwrites a redacted unipost-debug-report.md with request ids, log ids, findings, and environment metadata — no secrets and no source code. With explicit user approval, add --upload to store the redacted report in the super-admin support bundle viewer; the CLI still writes the local report first and returns the uploaded bundle id under data.support.upload.

MCP debug tools

The UniPost MCP server exposes read-only debug tools for agents that already have a workspace API key. Agents can list recent workspace logs, explain one request or log id, and obtain the authenticated SSE stream URL plus reconnect rules. The stream tool returns instructions instead of opening an indefinite MCP call.