[Bala (0xba1a)]

Summary

Let CopilotBot use a repository's agent skills and run on any sandbox image. The motivating case is the Azure Linux repository: it ships AGENTS.md and azldev-* skills under .agents/skills, and with this PR CopilotBot can follow them to upgrade a component end to end.

Changes

• session_options: extra keyword arguments forwarded to the Copilot SDK's CopilotClient.create_session, for example skill_directories, disabled_skills, custom_agents, mcp_servers or working_directory.
  • Keys are checked against the installed SDK's create_session signature; unknown keys raise ValueError.
  • model, provider, streaming, hooks and system_message stay managed by CopilotBot and are rejected.
  • run(session_options=...) overrides them for one run without changing the bot's defaults.
  • Only option names are logged, never values, because values such as MCP server environment variables can hold secrets.
• invoked_skills: after a run, lists the skills the agent used, taken from the SDK's skill.invoked events. Skill load and invoke events are also logged.
• image: the container image of the sandbox CopilotBot creates, for example AZURELINUX_IMAGE. Passing both image and environment raises ValueError.
• copilot-cli as a tool definition: the CLI and its Node.js 22 runtime are installed from the new tool_definitions/copilot-cli.yaml, using the normal distro-aware tool model (feat(tools): distro-aware tool commands #205) instead of install code inside CopilotBot.
  • Debian: NodeSource, as before.
  • Azure Linux: its repos only package Node 20, so it uses the official nodejs.org build, checked against the release's SHASUMS256.txt.
  • Pinned version: @github/copilot@1.0.105, verified with copilot --version. It must match the CLI that the pinned github-copilot-sdk targets; see below.
  • Distro handling: an undetectable distro falls back to the first (Debian) entry; a detected but unsupported distro raises UnsupportedDistroError before anything runs.
  • Infrastructure only: CopilotBot installs this tool itself. It is never an additional_tool and adds nothing to the model's prompt.
  • Unchanged: starting the headless server, passing the GitHub token and the readiness check stay in CopilotBot. The host still gets the SDK from the microbots[ghcp] pip extra.
• Copilot SDK 1.0.28 and copilot-cli 1.0.105: upgraded from 0.3.0 and 1.0.39, the latest compatible pair.
  • Why both: each SDK 1.x release pins the CLI it targets (CLI_VERSION in copilot/_cli_version.py). The old and new halves don't mix: SDK 0.3.0 can't parse CLI 1.0.105 responses, and CLI 1.0.39 lacks the connect RPC that SDK 1.x calls.
  • Code: connects with CopilotClient(connection=UriRuntimeConnection(...)), which replaces ExternalServerConfig, and imports SessionEventType from the public copilot.session_events. An SDK older than 1.x now fails with an explicit upgrade message, and the copilot.types fallback for SDKs before 0.3.0 is gone.
  • Pins: pyproject.toml (ghcp extra) and copilot-cli.yaml each carry a comment to update the other. The ghcp CI job installs the ghcp extra instead of repeating the version.
  • Check: test/bot/test_copilot_version_pins.py verifies both pins are exact. Under the ghcp marker, it also verifies the installed SDK matches the pin and targets the pinned CLI version.
• model_id for BYOK deployments with custom names: new parameter and COPILOT_BYOK_MODEL_ID env var, mapped to the SDK's provider model_id; the deployment name stays the wire model.
  • Why: copilot-cli 1.0.105 picks request settings such as temperature and reasoning_effort from the model name. For CI's Azure deployment mini-swe-agent-gpt5, it fell back to generic defaults and sent temperature: 0, which GPT-5 rejects.
  • CI: the ghcp job now uses the Responses wire API and COPILOT_BYOK_MODEL_ID=gpt-5.
  • Verified: reproduced the failure locally against the same deployment. wire_api="responses" alone fixes it, and so does model_id alone. With CI's settings, all ghcp tests pass.
• Docs: CopilotBot guide sections on SDK session options and on using a repository's agent skills, with an Azure Linux example.

Testing

• Unit:
  • Session options: validation (reserved keys, unknown keys, non-mapping input), forwarding, per-run overrides, and option values kept out of the logs.
  • Skills: invoked_skills tracking, reset on each run.
  • Image and copilot-cli: image forwarding and rejection together with environment; copilot-cli.yaml resolution per distro (Node install, pinned CLI, no usage instructions); _install_copilot_cli driving the tool, and rejecting unsupported distros.
  • SDK 1.x: import and connection tests (UriRuntimeConnection to the container IP and CLI port; a pre-1.x SDK is rejected), a full run() through the 1.x session API, and the version-pin tests.
  • model_id: provider config in each BYOK path (explicit credentials, env vars, token provider) and through the constructor; unset by default.
  • Results: no new failures compared to main, including under -n auto as CI runs them. The session-options test that failed occasionally before was depending on COPILOT_BYOK_MODEL in the environment; it no longer does.
• Integration: CI's integration selection, run locally: 25 passed, with no new failures compared to main.
• Live: installing through copilot-cli.yaml works on both stock images (DEBIAN_IMAGE, AZURELINUX_IMAGE) with Node 22. With SDK 1.0.28 and CLI 1.0.105, the live ghcp CopilotBot task on Debian passes.
• End to end: the new test/bot/test_copilot_bot_azurelinux_skills.py (marked integration, slow, ghcp).
  • Setup: it mounts an Azure Linux checkout READ_ONLY on AZURELINUX_IMAGE with sudo_access=True, installs rpm/mock/azldev (feat(tools): rpm, mock and azldev tool definitions #209), and points the session at the checkout's .agents/skills.
  • Task: it asks the agent to upgrade util-linux.
  • Result with BYOK gpt-5.6-sol: passed with SDK 1.0.28 and CLI 1.0.105 in about 12 minutes (and before the upgrade, with 0.3.0 and 1.0.39). The agent used the azldev, azldev-comp-toml and azldev-update-component skills, upgraded util-linux from 2.41.5 to 2.42.4 inside the sandbox, never ran sudo, and left the host checkout unchanged.
  • Wire API: with CLI 1.0.105, gpt-5.6-sol needs COPILOT_BYOK_WIRE_API=responses. Over the default completions API, the CLI now sends reasoning_effort together with function tools, and the endpoint rejects that combination.
  • Keeping changes: set AZURELINUX_KEEP_CHANGES=1 to mount the checkout READ_WRITE and keep the agent's changes.

Stack

1. refactor(env): run stock MCR images, prepare the sandbox on the fly #202 (merged): stock MCR images prepared on the fly.
2. feat(tools): distro-aware tool commands #205 (merged): distro-aware tool commands.
3. feat(env): Azure Linux 3 sandbox image #207 (merged): Azure Linux 3 sandbox and image on the bots.
4. feat(env): optional passwordless sudo for the sandbox agent #208 (merged): optional passwordless sudo for the sandbox agent.
5. feat(tools): rpm, mock and azldev tool definitions #209 (merged): rpm / mock / azldev tool definitions.
6. This PR: CopilotBot session options, skill tracking and image selection.

[Codecov Comments Bot (codecov-commenter)]

Codecov Report

✅ All modified and coverable lines are covered by tests.
✅ Project coverage is 77.48%. Comparing base (3f05bc3) to head (f6b8a99).

Additional details and impacted files

@@            Coverage Diff             @@
##             main     #210      +/-   ##
==========================================
+ Coverage   77.22%   77.48%   +0.25%     
==========================================
  Files          47       47              
  Lines        3219     3256      +37     
==========================================
+ Hits         2486     2523      +37     
  Misses        733      733              

Flag	Coverage Δ
ghcp	33.53% <68.42%> (+1.66%)	⬆️
integration	42.22% <15.78%> (-0.27%)	⬇️
ollama_local	34.36% <15.78%> (-0.18%)	⬇️
slow-browser	18.36% <15.78%> (+<0.01%)	⬆️
slow-other	40.17% <15.78%> (-0.03%)	⬇️
unit	75.12% <100.00%> (+0.28%)	⬆️

Flags with carried forward coverage won't be shown. Click here to find out more.

Files with missing lines	Coverage Δ
src/microbots/bot/CopilotBot.py	100.00% <100.00%> (ø)

🚀 New features to boost your workflow:

• ❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.
• 📦 JS Bundle Analysis: Save yourself from yourself by tracking and limiting bundle sizes in JS merges.