@grackle-ai/runtime-copilot

Grackle runtime that drives GitHub Copilot via the Copilot SDK (@github/copilot-sdk).

Overview

The Copilot runtime implements the @grackle-ai/runtime-sdk AgentRuntime interface (CopilotRuntime extends BaseAgentRuntime) and wraps the GitHub Copilot SDK. It is registered with the PowerLine runtime registry under the name copilot and is selected by personas that target Copilot. Each agent session creates a CopilotClient, opens (or resumes) a Copilot session, streams the SDK's events back to Grackle, and tears the session down on completion.

The Copilot SDK (@github/copilot-sdk) and the Copilot CLI (@github/copilot) are not install-time dependencies. They are installed lazily at spawn time into an isolated per-runtime directory (~/.grackle/runtimes/copilot/) via ensureRuntimeInstalled and imported dynamically, so the package stays light until a Copilot session actually runs.

Configuration

All configuration is driven by environment variables so the runtime behaves identically across local, Docker, SSH, and other environments.

| Variable | Description | | ------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------- | | COPILOT_CLI_PATH | Path to the Copilot CLI binary. Defaults to copilot resolved via PATH. | | COPILOT_CLI_URL | URL of an external Copilot CLI server (e.g. localhost:4321). When set, the runtime connects to it instead of spawning a local CLI process. | | COPILOT_PROVIDER_CONFIG | JSON-encoded provider config for bring-your-own-key (BYOK) scenarios (e.g. type, baseUrl, apiKey). Malformed JSON is ignored. |

Session-level options are passed through from Grackle: the model, an optional system message (injected via the SDK's systemMessage in append mode), MCP servers, and the working directory. Tool permission prompts are auto-approved (approveAll) for headless operation.

Note: the Copilot SDK does not support a turn limit. If a maxTurns value is requested, it is logged and ignored — the session runs until idle.

Models

The model is selected per session and passed straight through to the Copilot SDK's session config; this package does not hard-code a model list or a default. The available models are those exposed by your Copilot CLI / SDK installation.

Credentials

The runtime resolves a GitHub token from the following environment variables, in priority order:

| Variable | Priority | | ---------------------- | -------- | | COPILOT_GITHUB_TOKEN | 1 | | GH_TOKEN | 2 | | GITHUB_TOKEN | 3 |

If a token is found, it is passed to the CopilotClient and the SDK uses it directly. If none is set, the runtime falls back to the logged-in Copilot user (useLoggedInUser). For BYOK setups, supply provider credentials via COPILOT_PROVIDER_CONFIG instead.

Requirements

• Node.js >= 22
• The GitHub Copilot SDK (@github/copilot-sdk) and Copilot CLI (@github/copilot) — installed lazily into ~/.grackle/runtimes/copilot/ at spawn time, or an external CLI server reachable via COPILOT_CLI_URL
• GitHub Copilot credentials — a token in COPILOT_GITHUB_TOKEN / GH_TOKEN / GITHUB_TOKEN, a logged-in Copilot CLI session, or a BYOK provider config in COPILOT_PROVIDER_CONFIG

License

MIT