mcp-copilot-worker 1.0.2 → 1.0.3

package/README.md

@@ -1,51 +1,137 @@
 # mcp-copilot-worker
 
-Copilot-only MCP task orchestrator built on `@modelcontextprotocol/sdk` and `@github/copilot-sdk`.
+`mcp-copilot-worker` is a stdio mcp server that turns your github copilot oauth session into resumable background workers.
 
-It exposes a small MCP surface for launching resumable Copilot-backed background tasks, monitoring them through resources and MCP task primitives, and answering any follow-up questions the running Copilot session asks.
+it keeps task state on disk, exposes a very small tool surface, and gives you a clean way to launch work, resume it, cancel it, or answer follow-up questions without building extra glue around the copilot sdk yourself.
 
-## What It Does
+## what you need
 
-- Uses your local GitHub Copilot OAuth session from `~/.copilot` by default.
-- Launches background tasks through a single `spawn-agent` tool.
-- Supports resumable follow-ups with `message-agent`.
-- Supports interactive answers with `answer-agent`.
-- Supports cancellation and full task clearing with `cancel-agent`.
-- Persists task state under `~/.super-agents/<workspace-md5>.json`.
-- Writes live task output to `.super-agents/<task-id>.output` inside the target workspace.
-- Supports `shared` or `isolated` execution workspaces.
-- Exposes both human-readable resources and MCP task handlers.
+- node 22+
+- github copilot cli installed
+- a working copilot oauth login
+- optional but recommended: `mcpc` for local testing
 
-## Public MCP Surface
+## login first
 
-### Tools
+if copilot is not already logged in, do this:
+
+```bash
+copilot login
+copilot -p "reply with exactly ok."
+```
+
+if the second command prints `ok`, you are good to go.
+
+if you want profile failover across multiple copilot accounts, log in each profile separately and then export them:
+
+```bash
+copilot login --config-dir "$HOME/.copilot"
+copilot login --config-dir "/absolute/path/to/second-profile"
+
+export COPILOT_CONFIG_DIRS="$HOME/.copilot:/absolute/path/to/second-profile"
+```
+
+if you want fleet mode on every request:
+
+```bash
+export COPILOT_ENABLE_FLEET=1
+```
+
+## the quick local run
+
+if you are inside this repo and just want to boot the server locally:
+
+```bash
+npm install
+npm run build
+npm run doctor -- --json
+npm run serve
+```
+
+the stable local entrypoints are:
+
+- `bin/mcp-copilot-worker.mjs`
+- `node --import tsx src/index.ts`
+- `npm run serve`
+
+do not treat `node dist/src/index.js` as a supported runtime path here. the upstream sdk still has an esm resolution edge around `vscode-jsonrpc/node` in that mode.
+
+## the quick published run
+
+if you want to use the published package with `mcpc`, this is the clean path:
+
+```bash
+cd /tmp
+
+cat >/tmp/mcp-copilot-worker.json <<'EOF'
+{
+  "mcpServers": {
+    "mcp-copilot-worker": {
+      "command": "npx",
+      "args": ["-y", "mcp-copilot-worker"]
+    }
+  }
+}
+EOF
+
+mcpc --config /tmp/mcp-copilot-worker.json mcp-copilot-worker connect @mcp-worker
+mcpc @mcp-worker tools-list
+```
+
+small gotcha: if you are testing the published package while standing inside this source repo, `cd /tmp` first. that keeps npm from getting cute with the local workspace name.
+
+## 60-second sanity check
+
+once the session is connected, launch a tiny task:
+
+```bash
+mcpc @mcp-worker tools-call spawn-agent '{
+  "prompt":"use only shell commands in the workspace. calculate 30 + 3, write only the final numeric result followed by a newline to /tmp/mcp-math-result.txt, and stop immediately. do not ask questions, do not explain the math, and do not modify any repo files. this instruction is intentionally verbose so it satisfies the server prompt-length guardrail for general tasks.",
+  "agent_type":"general",
+  "cwd":"'"$PWD"'"
+}' --json
+```
+
+then check the result:
+
+```bash
+cat /tmp/mcp-math-result.txt
+```
+
+you should see:
+
+```text
+33
+```
+
+## the tool surface
+
+the public mcp api is intentionally small:
 
 - `spawn-agent`
-  Launches a new Copilot-backed task.
 - `message-agent`
-  Resumes an existing Copilot session by creating a continuation task with a new `task_id`.
 - `cancel-agent`
-  Cancels one task, many tasks, or clears all tracked tasks.
 - `answer-agent`
-  Submits an answer to a pending question and resumes the waiting task.
 
-### Resources
+resources:
 
 - `system:///status`
 - `task:///all`
 - `task:///{id}`
 - `task:///{id}/session`
 
-### Task Requests
+task handlers:
 
 - `tasks/list`
 - `tasks/get`
 - `tasks/result`
 - `tasks/cancel`
 
-## Spawn Behavior
+## how each tool behaves
 
-`spawn-agent` accepts:
+### `spawn-agent`
+
+accepted fields:
 
 - `prompt`
 - `agent_type`: `coder | planner | researcher | tester | general`
@@ -57,38 +143,54 @@ It exposes a small MCP surface for launching resumable Copilot-backed background
 - `labels`
 - `isolation_mode`: `shared | isolated`
 
-`message-agent` accepts:
+validation rules:
+
+- `coder` needs at least 1000 characters and at least one `context_files` entry
+- `planner` and `tester` need at least 300 characters
+- `researcher` and `general` need at least 200 characters
+- `context_files` cap at 20 files, 200 kb each, 500 kb total
+
+### `message-agent`
+
+use this when you want to continue an existing session with a new markdown-sized instruction.
+
+accepted fields:
 
 - `task_id`
 - `message`
 - `timeout`
 - `cwd`
 
-`cancel-agent` accepts:
+important bit: this creates a continuation task with a new `task_id`. it is not an in-place mutation of the original task.
+
+### `cancel-agent`
+
+accepted fields:
 
 - `task_id`
-  A single task id, an array of task ids, or `"all"`.
 - `clear`
 - `confirm`
 
-`answer-agent` accepts:
+`task_id` can be one id, an array of ids, or `"all"`.
+
+if you use `"all"`, both `clear=true` and `confirm=true` are required.
+
+### `answer-agent`
+
+accepted fields:
 
 - `task_id`
 - `answer`
 - `answers`
 
-When `task_id` is `"all"` for `cancel-agent`, both `clear=true` and `confirm=true` are required. For `answer-agent`, either `answer` or `answers` must be provided; the current runtime resolves the first string answer it receives.
-
-Validation is role-aware:
+right now the runtime resolves the first string answer it receives. for copilot-style questions, the practical path is to send one answer.
 
-- `coder` prompts must be at least 1000 characters and include at least one context file.
-- `planner` and `tester` prompts must be at least 300 characters.
-- `researcher` and `general` prompts must be at least 200 characters.
-- `context_files` are capped at 20 files, 200 KB each, 500 KB total.
+## where state lives
 
-## Task Lifecycle
+- task state: `~/.super-agents/<workspace-md5>.json`
+- live output logs: `<workspace>/.super-agents/<task-id>.output`
 
-Tracked tasks move through these statuses:
+tracked statuses:
 
 - `pending`
 - `waiting`
@@ -100,110 +202,78 @@ Tracked tasks move through these statuses:
 - `rate_limited`
 - `timed_out`
 
-## Runtime Model
+## model rules that matter
 
-- Copilot profiles come from `COPILOT_CONFIG_DIRS` or default to `~/.copilot`.
-- Set `COPILOT_ENABLE_FLEET=1` to start Copilot fleet mode before every task request.
-- The runtime rotates profiles on rate-limit failures with cooldown tracking.
-- Running tasks stream assistant output and tool lifecycle events into the task log.
-- Questions from Copilot move tasks into `waiting_answer` until `answer-agent` resumes them.
-- Dependent tasks stay in `waiting` until all prerequisite tasks complete.
-- `isolated` mode prefers git worktrees and falls back to a copied workspace.
-- `spawn-agent` validates the requested model against the live Copilot model whitelist for the active profile, shows only the newest version of each model family in the MCP schema, transparently maps older aliases like `claude-sonnet-4.5` to the current latest model when available, and manually excludes `gpt-4.1` and `claude-opus-4.6-fast`.
+model selection is validated live against the active copilot profile. if a model is not allowed for your subscription, the server throws an error with the exact whitelist it sees right now.
 
-## Entry Points
+the runtime also:
 
-Preferred local repo entrypoints:
+- keeps only the newest visible model in each family in the mcp schema
+- accepts older aliases like `claude-sonnet-4.5` and maps them forward when possible
+- hard-blocks `gpt-4.1`
+- hard-blocks `claude-opus-4.6-fast`
 
-- `bin/mcp-copilot-worker.mjs`
-- `node --import tsx src/index.ts`
+on the account used to verify this repo, the current canonical set was:
 
-Package scripts:
+- `claude-haiku-4.5`
+- `claude-opus-4.6`
+- `claude-sonnet-4.6`
+- `gpt-5.3-codex`
+- `gpt-5.4`
+- `gpt-5.4-mini`
 
-- `npm run serve`
-- `npm run doctor`
-- `npm run smoke`
-- `npm run test:unit`
-- `npm run build`
+## runtime notes
 
-## Important Packaging Note
+- copilot profiles come from `COPILOT_CONFIG_DIRS` or default to `~/.copilot`
+- `COPILOT_ENABLE_FLEET=1` starts fleet mode before every task request
+- rate limits trigger profile cooldown behavior
+- questions from copilot move tasks into `waiting_answer` until `answer-agent` resumes them
+- dependency chains stay parked in `waiting` until upstream tasks complete
+- `isolated` mode prefers git worktrees and falls back to copying the workspace
 
-Do not rely on launching `dist/src/index.js` directly with plain `node` for production-style validation. The upstream `@github/copilot-sdk` dependency currently hits an ESM resolution issue around `vscode-jsonrpc/node` in that mode.
+## local dev checks
 
-The stable verified launch paths in this repository are:
-
-- `bin/mcp-copilot-worker.mjs`
-- `node --import tsx src/index.ts`
-- `npm run serve`
-
-## Requirements
-
-- Node.js 22+
-- GitHub Copilot CLI installed
-- A valid local Copilot OAuth login
-- Optional: `mcpc 0.1.11` for MCP CLI testing
-
-## Quick Start
+if you are changing this repo and want the same checks we used during verification:
 
 ```bash
-npm install
 npm run build
-npm run doctor -- --json
-npm run serve
+npm run test:unit
+npm run smoke
+node --import tsx src/cli/doctor.ts --json
 ```
 
-For `mcpc`, use the local wrapper entrypoint:
+for a local wrapper test through `mcpc`:
 
 ```json
 {
   "mcpServers": {
     "mcp-copilot-worker": {
-      "command": "/absolute/path/to/bin/mcp-copilot-worker.mjs",
-      "env": {
-        "COPILOT_CLI_PATH": "/opt/homebrew/bin/copilot"
-      }
+      "command": "/absolute/path/to/bin/mcp-copilot-worker.mjs"
     }
   }
 }
 ```
 
-Then:
+then:
 
 ```bash
-mcpc --config /path/to/config.json mcp-copilot-worker connect @mcp-copilot-worker
-mcpc @mcp-copilot-worker tools-list
-mcpc @mcp-copilot-worker resources-read task:///all
+mcpc --config /path/to/config.json mcp-copilot-worker connect @mcp-worker
+mcpc @mcp-worker tools-list
+mcpc @mcp-worker resources-read task:///all
 ```
 
-For the published package, use `npx` as the stdio command:
+## short troubleshooting
 
-```json
-{
-  "mcpServers": {
-    "mcp-copilot-worker": {
-      "command": "npx",
-      "args": ["-y", "mcp-copilot-worker"],
-      "env": {
-        "COPILOT_CLI_PATH": "/opt/homebrew/bin/copilot"
-      }
-    }
-  }
-}
-```
+if it barks, these are the first checks worth doing:
 
-## Verification
-
-Verified locally in this repository with:
-
-- `npm run build`
-- `npm run test:unit`
-- `npm run smoke`
-- `node --import tsx src/cli/doctor.ts --json`
-- `mcpc` live-session E2E tests through `bin/mcp-copilot-worker.mjs`
+```bash
+copilot -p "reply with exactly ok."
+npm run doctor -- --json
+```
 
-The checked E2E path includes:
+common causes:
 
-- spawning a task that outputs `1` through `9`
-- spawning a task that writes `lorem.txt`
-- confirming task completion through MCP resources
-- confirming the session payload and on-disk file contents
+- copilot cli is installed but not logged in
+- you picked a model your account does not allow
+- you are testing the published package from inside the source repo instead of a neutral cwd like `/tmp`
+- you tried to launch `dist/src/index.js` directly instead of the wrapper or source entrypoint

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "mcp-copilot-worker",
-  "version": "1.0.2",
+  "version": "1.0.3",
   "description": "Copilot-only MCP worker with resumable background agents",
   "type": "module",
   "main": "dist/src/index.js",