Skip to content

[docs] docs: Update for Copilot Auto API versions and Cloud Hypervisor network readiness #7566

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
lpcox merged 1 commit into from
Aug 20, 2026
Merged

[docs] docs: Update for Copilot Auto API versions and Cloud Hypervisor network readiness #7566

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
16 changes: 16 additions & 0 deletions docs/auth-matrix.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -184,6 +184,22 @@ When the resolved upstream host is a Copilot host (`githubcopilot.com` or a `*.g

Non-empty inbound values are preserved; empty values and case-variant duplicates are replaced so exactly one instance of each header reaches CAPI. Harnesses that do not send a stable `X-Interaction-Id` themselves (aider, Pi, …) therefore still get prompt-cache hits, and a harness that owns its own session identity can override the value simply by sending the header. There is no AWF-specific override env var for `X-Interaction-Id`: outside GitHub Actions the sidecar mints one UUID per process. Neither header is injected on non-Copilot hosts, so BYOK targets (Azure OpenAI, OpenRouter, …) and the OpenAI/Anthropic/Gemini providers are unaffected.

### Auto API Version Injection (`*.githubcopilot.com` only)

For GitHub Copilot catalog targets, the sidecar auto-selects appropriate `x-github-api-version` headers for certain endpoints to ensure API compatibility:

| Endpoint | HTTP Method | Auto-Selected Version | Notes |
|----------|-------------|----------------------|-------|
| `/auto` | POST | `2026-08-01` | Copilot Auto inference endpoint |
| `/models/session` | POST | `2025-07-16` | Model session initialization |
| `/models/session/intent` | POST | `2025-07-16` | Model session intent parsing |

**Key behaviors:**
- Auto-injection applies only to GitHub Copilot targets (`*.githubcopilot.com`); BYOK and non-Copilot targets are unaffected.
- If the request already includes an `x-github-api-version` header (case-insensitive), it is preserved and auto-injection is skipped.
- POST requests to other endpoints do not receive auto-injected versions; callers must specify versions for other endpoints if needed.
- Non-POST requests never receive auto-injected versions.

### `/models` Endpoint (Special Case)

The `/models` endpoint prefers `COPILOT_GITHUB_TOKEN` (GitHub OAuth) over BYOK keys when both are configured, because model listing is a GitHub platform feature. However, when no GitHub token is available (typical for direct-BYOK/custom targets), `/models` will use the BYOK credential.
Expand Down
15 changes: 13 additions & 2 deletions docs/cloud-hypervisor-foundation.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -75,8 +75,9 @@ AWF performs these steps for each run:
6. Create a bounded cgroup v2 leaf and launch Cloud Hypervisor as the invoking
non-root identity.
7. Start one sandboxed `virtiofsd` process for each validated export.
8. Create and boot the VM, connect to the guest supervisor over VSOCK, and
probe infrastructure connectivity.
8. Create and boot the VM, connect to the guest supervisor over VSOCK, verify
guest network readiness (loopback interface UP), and probe infrastructure
connectivity.
9. Execute the agent command and propagate its exit code. Timeouts return
`124`.
10. Sync and unmount guest filesystems, stop the VM and VMM, reap `virtiofsd`,
Expand Down Expand Up @@ -241,6 +242,16 @@ Preserved namespaces and processes continue consuming host resources. Remove
them only after collecting the diagnostics you need.
:::

### Guest network readiness timeout

If the guest network readiness check times out (error: `guest-network-not-ready`), the guest's loopback interface did not become UP before the timeout expired. Possible causes:

1. **Guest image mismatch** — The guest supervisor contract requires loopback to be brought up before opening the VSOCK listener. A mismatched or incompatible guest image may violate this ordering.
2. **Host system issue** — Delays in kernel or KVM initialization may cause the readiness check to timeout. Retry the run; transient delays are sometimes recoverable.
3. **Supervisor crash** — The guest supervisor may have crashed before initializing networking. Check preserved guest logs under `<workDir>/microvm-images/<runId>/` for supervisor output.

Verify the guest image digest and supervisor version match the build expectation, then retry.

### Guest cannot reach Squid or the API proxy

Check the namespace nftables rules, TAP state, and Squid/API proxy health. The
Expand Down
Loading