feat(examples): GitHub Copilot CLI agent (github-copilot-sdk==0.2.2)

[elefthei]

Summary

Ships GitHub Copilot CLI as a first-class AgentField reasoner node, backed by the official github-copilot-sdk==0.2.2 (Public Preview). Other agents on the field can call Copilot the same way they call any other AgentField reasoner — no subprocess parsing, no bespoke protocol, full access to Copilot's event model and permission hooks.

Track A of the two-PR Copilot integration (Track B is #491, the skillkit target + doctor probes — independent of this PR).

Lives entirely under examples/python_agent_nodes/copilot_agent/:

• copilot_session.py — thin wrapper that returns a stable CopilotRunResult dict from a single Copilot turn. Event discrimination via SessionEventType (stable enum), never isinstance on event.data — subclass names like AssistantMessageData don't exist in the PyPI build even though the repo samples reference them.
• reasoners.py — four reasoners, ask / plan / review / run_task. Deny-by-default permission posture; run_task requires allow_tools=True and takes precedence-ordered allow_list / deny_list. Permission handler rejects with PermissionRequestResult(kind="denied", ...).
• Session mapping — the AgentField session id is mapped to a Copilot session id via session-scoped memory (copilot_session_id key). Different AF sessions always get independent Copilot sessions; continue_session=True reuses the mapping.
• Auth — reads COPILOT_GITHUB_TOKEN → GH_TOKEN → GITHUB_TOKEN → falls back to copilot --login user. Token never leaves the process env.
• Isolation — default is the user's real ~/.copilot/ so skills installed by af skill install and auth from copilot --login are visible. AGENTFIELD_COPILOT_ISOLATE=1 (or isolate=True) switches to a per-node sandbox under $AGENTFIELD_HOME/copilot-home/<node_id>.
• SDK compat smoke test — tests/test_sdk_compat.py imports every SDK symbol the example uses and fails loudly if the preview SDK drifts.

No changes outside examples/python_agent_nodes/copilot_agent/ and CHANGELOG.md; no new core deps.

Testing

• ./scripts/test-all.sh — N/A (no change to control-plane/, sdk/go/, or sdk/python/; the script does not traverse examples/).
• Additional verification:
  • pytest tests/ in the example — 21 passed (0 skipped, 0 xfail) against the stubbed CopilotClient in conftest.py. No live Copilot subscription required.
  • tests/test_sdk_compat.py asserts CopilotClient.create_session signature, CopilotSession.send_and_wait shape, PermissionHandler.approve_all, and every SessionEventType enum value we rely on.
  • python -m py_compile clean on copilot_session.py, reasoners.py, main.py.
  • Not yet exercised against a real Copilot login in CI (requires a fine-grained PAT with "Copilot Requests" permission; classic ghp_* PATs are rejected by the backend).

Checklist

• I updated documentation where applicable. (Example README.md covers quickstart, auth, isolation, cross-agent calls, and links to feat(skillkit,doctor): GitHub Copilot CLI target + doctor probes #491 for the skillkit half.)
• I added or updated tests. (21 unit tests + SDK compat smoke test in tests/.)
• I updated CHANGELOG.md — new [Unreleased] entry under ### Added.

Screenshots (if UI-related)

Not UI-related.

Related issues

Pairs with #491 (Copilot skillkit + doctor probes, independent — merge in either order). Installing #491 makes af skill install flow into ~/.copilot/skills/, visible to the session created by this example out of the box.

[CLAassistant]

Thank you for your submission! We really appreciate it. Like many open source projects, we ask that you sign our Contributor License Agreement before we can accept your contribution.

---

Lef Ioannidis seems not to be a GitHub user. You need a GitHub account to be able to sign the CLA. If you have already a GitHub account, please add the email address used for this commit to your account.
_{You have signed the CLA already but the status is still pending? Let us recheck it.}