Agent Host Debug Logs

Use this skill to orient to bundles produced by Developer: Export Agent Host Debug Logs.... These are different from the normal timestamped Code OSS log directory.

Treat the bundle as sensitive: it can contain tokens, prompts, file contents, terminal output, paths, and settings. Keep analysis local and avoid quoting secrets or unrelated user content. Timestamps, event names, IDs, status values, and general property values are fine.

Open the Bundle

The export name usually starts with ah-logs and may be a zip or an already-unpacked folder. For a zip, use the bundled extractor:

python3 .github/skills/agent-host-logs/scripts/extract.py "<archive>.zip"

The final line gives the temporary extraction path. Work from that folder and delete only that exact folder when finished.

Files are collected best-effort, so a valid bundle may contain only some of these:

events.jsonl
usage.jsonl
customizations.json
agenthost.log
agenthost.1.log
agenthost-server.log
vscode-logs/Window/renderer.log
vscode-logs/Window/renderer.1.log
vscode-logs/Shared/sharedprocess.log
ahp/*.jsonl
copilot-logs/*.log
remote-agenthost.log

What the Files Mean

The basic flow is:

Window/client <-> AHP <-> Agent Host process <-> Copilot SDK

How to Start

1. List the files and note their sizes.
2. Identify the reported symptom, approximate time, local or remote host, and any known session, chat, turn, request, or tool ID.
3. Start with the file closest to the symptom:
   • Turn or provider behavior: events.jsonl
   • Token/credit usage or cost questions: usage.jsonl
   • Client/server state or ordering: ahp/*.jsonl
   • Host implementation failure: agenthost*.log
   • SDK behavior: copilot-logs/*.log
   • UI behavior: vscode-logs/Window/renderer.log and its rotated segments
4. Search by the known time or ID, then follow the same operation into the adjacent layer.

Useful correlation fields include the raw session ID, session/chat URI, turnId, interactionId, tool/request IDs, JSON-RPC request id, AHP serverSeq, and event id/parentId.

Copilot Session Refresh Failures

At the default Info log level, agenthost*.log records the refresh operation, configuration and SDK session IDs, chat, turn, and first matching reason. Only the first matching trigger is reported, preserving the restart checks' short-circuit order. Structural reasons distinguish client tools, client plugins, and root MCP configuration without logging their contents.

Follow Preparing SDK session and the paired SDK resumeSession started / settled records by attemptId. Follow each attached SDK session's shutdown and disconnect records by instanceId, which distinguishes successive wrappers of the same SDK session. A disconnect wait completed record with disconnectRpc=pending and shutdownReceived=true means the shutdown notification unblocked the caller before the disconnect RPC settled. A later RPC completion or failure, including after disposed=true, is logged separately. Neither the notification nor the host-side wait alone proves that native cleanup finished; correlate these with the SDK process log before concluding there was a teardown/resume race.

Important Tips

• events.jsonl, Copilot SDK logs, and AHP timestamps are normally UTC. The plain .log files may use local machine time; remote logs may use another timezone.
• An AHP log is connection-scoped and can contain multiple sessions. A Copilot SDK process log can also contain multiple sessions.
• AHP files rotate as .jsonl, .1.jsonl, .2.jsonl, and so on. Use _ahpLog.ts to reconstruct order.
• A subscribe result can contain a full snapshot; its contents did not necessarily change at subscription time.
• _ahpLog.truncated: true means large values were omitted from that log record.
• Warning or error severity alone does not prove causality. Look for the matching failed response, missing completion, or user-visible consequence.
• Missing files are normal because export collection is best-effort.