Skip to content

CowboyLogic/ai-dev / skills/copilot-worker

copilot-worker

Flagged

Delegate work to GitHub Copilot instead of doing it yourself, to save Claude tokens. Use this BEFORE reading three or more files (roughly 500 lines or more) to answer a question about a codebase ("look into", "find out how", "where is", "why does", "explain how X works", "does the code do Y", "give me an overview", "summarize"), before any code review of a diff or files, and before any implementation task that touches more than a file or two. Also use when the user says "use Copilot", "delegate", "hand off", or "worker". You plan the task and verify the result; Copilot does the bulk work.

FileKindSize
README.mdmarkdown5.3 KB
SKILL.mdskill md12.2 KB
references/upgrading.mdmarkdown4.3 KB
scripts/copilot_worker.pyscript30.0 KB
scripts/pins.jsonconfig46 B
scripts/test_copilot_worker.pyscript41.4 KB
scripts/test_sdk_contract.pyscript7.0 KB
scripts/test_worker_engine.pyscript36.5 KB
scripts/worker_engine.pyscript42.7 KB

references/upgrading.md

View on GitHub
# Upgrading the Copilot SDK and runtime

The worker is pinned to one GitHub Copilot SDK and the one Copilot runtime that SDK
carries. Upgrading either is a deliberate change made with this procedure, never a side
effect of running the script.

## What is pinned, and where

| What | Where |
| --- | --- |
| The SDK version | `scripts/pins.json` (`sdk`) and the `github-copilot-sdk==` line in the header of `scripts/copilot_worker.py` |
| The runtime version | `scripts/pins.json` (`runtime`). Each SDK release carries its own runtime and downloads it, checked against published checksums, so the two always move together |
| Every package the SDK needs | The same header, each at an exact `==` version |

The header lists the whole dependency set, not only the SDK, because the SDK's own
requirements are loose ranges (`pydantic>=2.0`, `httpx>=0.24`) that would otherwise float.

> [!NOTE]
> A lockfile (`uv lock --script`) was tried and rejected. It records the `exclude-newer`
> setting and package index of the machine that made it, and `uv run` ignores it and
> re-resolves when the user's configuration differs. Exact pins in the header behave the
> same on every machine and mirror.

## What enforces the pins

- The engine refuses to start a worker when the installed SDK or runtime differs from
  `scripts/pins.json`. The run ends `failed`, and `stderr.log` names the difference.
- `check` prints a `pins:` line and fails on a mismatch.
- The unit and contract tests run in CI against an environment built from the header, and
  fail when the header, `scripts/pins.json`, the installed SDK, or the SDK's dependency set disagree.

## Upgrade procedure

1. **Pick the SDK version** and read its release notes. Look for changes to permission
   handling, session options, event types, and the names of the runtime's built-in tools.
2. **Find its runtime and its dependency set:**

   ```bash
   uv run --no-project --no-config --with github-copilot-sdk==NEW \
     python -c "from copilot._cli_version import CLI_VERSION; print(CLI_VERSION)"
   echo "github-copilot-sdk==NEW" | uv pip compile - --no-config --no-header --no-annotate
   ```

3. **Update the header** in `scripts/copilot_worker.py` with the compiled list, and
   `scripts/pins.json` with the new `sdk` and `runtime`.
4. **Run the tests** from the repository root, in the environment the header describes:

   ```bash
   python - > /tmp/copilot-worker-requirements.txt <<'PY'
   import pathlib, re
   header = pathlib.Path("skills/copilot-worker/scripts/copilot_worker.py").read_text().split("# ///", 2)[1]
   print("\n".join(re.findall(r'^#\s+"([^"]+)",?$', header, re.MULTILINE)))
   PY
   REQUIRE_SDK_CONTRACT=1 uv run --no-project --with-requirements /tmp/copilot-worker-requirements.txt \
     python -m unittest discover -s skills/copilot-worker/scripts -v
   ```

   A failing contract test names the SDK option, class, or field that moved. Change the
   engine to match, and do not loosen the test.
5. **Check what the tests cannot see.** The SDK does not validate tool names, so a renamed
   runtime tool shows up only as a worker without that tool. Run the live check, then one
   `implement` task that runs a shell command, and read `permissions.jsonl` and
   `events.jsonl` for anything unexpected:

   ```bash
   uv run skills/copilot-worker/scripts/copilot_worker.py check --live
   ```

   The shell tools differ by platform (`SHELL_TOOLS` in `scripts/worker_engine.py`):
   `bash` and its companions on macOS and Linux, `powershell` and its companions on
   Windows. Run the `implement` check on Windows too when the upgrade touches shell
   handling.

6. **Update the documentation** that mentions behavior the upgrade changed, and say in the
   pull request which SDK and runtime versions moved.

## What the contract tests do not cover

- Whether the runtime still offers the built-in tools in `TOOLS` under the same names.
- How the runtime behaves: permission prompts, shell handling, and the content of events.
- Event shapes beyond the fields the engine reads. A parser built on `events.jsonl` needs
  its own tests when it exists.

## Housekeeping

The SDK keeps each runtime it has downloaded in its cache directory
(`~/Library/Caches/github-copilot-sdk/cli/` on macOS, `~/.cache/github-copilot-sdk/cli/`
on Linux, `%LOCALAPPDATA%\github-copilot-sdk\cli\` on Windows). Old versions stay there unused after an
upgrade and can be deleted.
add-product-e2e-evalpaperclipai/paperclipAdd or extend a Paperclip full-stack runner E2E workflow, fixture, matcher, or report evidence path for local or Daytona execution.Stars: 115kUpdated Claude CodeCodexVerifiedInstall
add-runner-evalpaperclipai/paperclipAdd or extend a Paperclip Runner protocol evaluation definition, roster, assertion, or report fixture with provenance and narrow validation.Stars: 115kUpdated Claude CodeCodexVerifiedInstall
diagnose-why-work-stoppedpaperclipai/paperclipCompatibility entry point for failed, stalled, looping, or over-recovered Paperclip work. Use fix-failed-paperclip-run for the full diagnosis, regression, repair, real verification, and green-PR workflow; honor an explicitly requested diagnosis-only scope.Stars: 115kUpdated Claude CodeCodexVerifiedInstall
fix-failed-paperclip-runpaperclipai/paperclipDiagnose and fix failed, stuck, slow, or incorrectly blocked Paperclip tasks and runs. Use with a task/run URL or failure report to trace the root cause, prove a regression red then green, check second-order effects, verify the real workflow, and deliver a PR with passing checks.Stars: 115kUpdated Claude CodeCodexVerifiedInstall