copilot-reverse 0.0.1 → 0.0.2

package/README.md

@@ -1,37 +1,166 @@
 # copilot-reverse
 
-Interactive terminal app that turns your GitHub Copilot subscription into local
-OpenAI- and Anthropic-compatible endpoints, with a self-healing daemon and a
-built-in assistant.
+**Use the GitHub Copilot subscription you already pay for as a local Claude Code / Codex backend.**
+No new API keys. No per-token bills. One terminal app.
 
-> **New here? Read the [User Guide](GUIDE.md) — a 60-second start, no jargon.**
+```
+  ┌─────────────┐        ┌───────────────────┐        ┌─────────────┐
+  │ Claude Code │ ─────▶ │  copilot-reverse  │ ─────▶ │   Copilot   │
+  │   / Codex   │  local │  (your machine)   │  proxy │  (your sub) │
+  └─────────────┘        └───────────────────┘        └─────────────┘
+```
 
 > **Disclaimer:** The GitHub Copilot integration uses community-documented,
 > unofficial endpoints, for use with your own Copilot subscription only. It may
 > break if GitHub changes these endpoints.
 
+---
+
+## 60-second start
+
+```bash
+npx copilot-reverse
+```
+
+1. It asks you to log in to GitHub (device code — paste a code in your browser). One time only.
+2. The terminal app launches. You'll see a prompt and a status bar.
+3. In the app, type:
+   ```
+   /setup-claude
+   ```
+   Pick a model (e.g. **claude-opus-4.8 (1M)**), choose **global**, done.
+4. Open a **new** terminal and run `claude`. It's now talking to Copilot through copilot-reverse. 🎉
+
+That's it. Codex users: run `/setup-codex` instead.
+
+Here's the app itself — a prompt, a live status bar, and slash-command autocomplete:
+
+```text
+ ✳ copilot-reverse                                                       worker: ready
+
+ Type a message to chat with the assistant, or /help for commands.
+╭─────────────────────────────────────────────────────────────────────────────────────╮
+│ › /setup                                                                              │
+╰─────────────────────────────────────────────────────────────────────────────────────╯
+  ❯ /setup-claude   print Claude Code config
+    /setup-codex    print Codex/OpenAI config
+    /setup-status   show configured endpoints
+    ↑↓ navigate · tab complete · enter run
+ model claude-opus-4.8  ·  daemon ready  ·  claude u:✓ p:○  codex u:✓ p:○  ·  /help
+```
+
+---
+
+## What can I do in the app?
+
+Just **talk to it** — it understands plain English and will do the work for you:
+
+> *"list models"* → shows every model + its context window
+> *"set up claude"* → configures Claude Code
+> *"is the worker healthy?"* → runs a health check
+> *"why did my last request fail?"* → shows the error
+
+Prefer commands? Type `/` to see them all. The essentials:
+
+| Command | What it does |
+|---|---|
+| `/setup-claude` · `/setup-codex` | Point Claude Code / Codex at copilot-reverse |
+| `/model` | Switch the chat model (1M-context models marked) |
+| `/status` · `/doctor` | Is everything healthy? |
+| `/logs` · `/metrics` | What ran, what failed, and why |
+| `/dashboard` | Open a live web dashboard in your browser |
+| `/report` | File a pre-filled bug report (diagnostics only — no prompts) |
+| `/reset-claude` · `/reset-codex` | Undo setup, restore original config |
+| `/login` · `/logout` | Sign in to GitHub (device-code) · sign out (remove token) |
+| `/help` · `/quit` | List commands · exit |
+
+### The live dashboard
+
+`/dashboard` opens a self-refreshing web view of everything happening through the proxy — worker
+health, request volume, and (most useful) recent **errors with their real messages**:
+
 ![copilot-reverse dashboard](images/dashboard.png)
 
-## Quick start
+---
+
+## Connect your own tools
+
+Already have something that speaks OpenAI or Anthropic? Point it here:
+
+- **OpenAI-compatible:** `http://127.0.0.1:7891/v1`
+- **Anthropic-compatible:** `http://127.0.0.1:7891`
+
+Any API key value works locally (it's your machine). Example:
 
 ```bash
-npx copilot-reverse      # device-code login, then the TUI launches
+export ANTHROPIC_BASE_URL=http://127.0.0.1:7891
+export ANTHROPIC_API_KEY=local
+claude
 ```
 
-In the TUI: `/help`, `/doctor`, `/setup-claude`, `/setup-codex`, `/metrics`, or
-just talk to the assistant in natural language.
+---
 
-Point clients at:
-- OpenAI: `http://127.0.0.1:7891/v1`
-- Anthropic: `http://127.0.0.1:7891`
+## The status bar, decoded
 
-## Architecture (M1)
+The bottom line of the app tells you everything at a glance:
 
-- **TUI** (Ink) — the `copilot-reverse` process: REPL + slash commands + claude-agent-sdk
+```text
+model claude-opus-4.8  ·  daemon ready  ·  claude u:✓ p:○  codex u:○ p:○  ·  /help
+```
+
+- **worker / daemon** — green `ready` means the proxy is up and self-healing.
+- **claude u:✓ p:○** — Claude Code is configured at the **u**ser (global) level, not in this **p**roject. Read live from your real config files.
+
+---
+
+## Troubleshooting
+
+**"context 100%" or `/compact` fails in Claude Code**
+Re-run `/setup-claude` and pick a **1M** model (e.g. `claude-opus-4.8 (1M)`). copilot-reverse writes
+the right context-window hint so the client stops assuming a small window. Then restart Claude Code.
+
+**"GitHub login expired"**
+Your Copilot session lapsed. You don't need to restart anything — when a chat fails, copilot-reverse
+detects it and tells you right there:
+
+```text
+assistant error: 401 authentication_error: GitHub login expired
+  ↳ your GitHub login looks expired — run /login to sign in again
+```
+
+Just type **`/login`**, complete the device-code prompt, and you're back — the worker reloads the new
+token automatically. (Switching accounts? `/logout` first, then `/login`.)
+
+**A request failed and I don't know why**
+Type `/logs` (or ask *"why did that fail?"*). Every failure is captured with its real upstream
+message. Still stuck? `/report` opens a pre-filled GitHub issue with diagnostics — **never** your
+prompt content.
+
+**Want to undo everything**
+`/reset-claude` and `/reset-codex` remove exactly the keys copilot-reverse added and leave the rest
+of your config untouched.
+
+---
+
+## Good to know
+
+- **Your data stays local.** The app proxies between your editor and Copilot on `127.0.0.1`. Your
+  GitHub token lives only in `~/.copilot-reverse/creds.json` on your own disk.
+- **It heals itself.** If the proxy crashes, the supervisor restarts it with backoff and records why.
+- **Unofficial endpoints.** This uses community-documented Copilot endpoints with *your own*
+  subscription. It may break if GitHub changes them — that's the trade-off for not needing extra keys.
+
+---
+
+## Architecture
+
+Three processes, one terminal app:
+
+- **TUI** (Ink) — the `copilot-reverse` process: REPL + slash commands + a claude-agent-sdk
   assistant (which dogfoods copilot-reverse's own Anthropic endpoint).
 - **Supervisor** (:7890) — control API + SQLite + self-healing worker supervision.
-- **Worker** (:7891) — OpenAI `/v1/chat/completions` + Anthropic `/v1/messages`
-  → Copilot, with tool-use translation both ways.
+- **Worker** (:7891) — OpenAI `/v1/chat/completions` + Anthropic `/v1/messages` → Copilot,
+  with tool-use translation both ways.
 
 ## Development
 
@@ -58,3 +187,8 @@ re-run and update `e2e/RESULTS.md`.
   `useInput` subscribes to stdin asynchronously after mount, so writes issued in
   the same tick as `render()` are dropped. The delay lets the subscription
   attach; assertions are otherwise unchanged.
+
+---
+
+Questions or bugs? Use `/report` from inside the app, or open an issue on
+[GitHub](https://github.com/wangcansunking/copilot-reverse). Happy hacking. 🚀

package/dist/cli/index.js

@@ -10,7 +10,7 @@ import { probeSupervisor } from "../daemon/lifecycle.js";
 import { startSupervisor } from "../supervisor/index.js";
 import { runAssistantTurn } from "../tui/assistant/runtime.js";
 import { makeOnChat } from "../tui/assistant/on-chat.js";
-import { readGhToken } from "../shared/creds.js";
+import { readGhToken, clearGhToken } from "../shared/creds.js";
 import { readClientSetup, writeClientSetup } from "../shared/client-setup.js";
 import { readChatModel, writeChatModel } from "../shared/prefs.js";
 import { CopilotTokenStore, isCopilotTokenValid } from "../providers/copilot/token.js";
@@ -66,9 +66,23 @@ async function launchTui() {
     const registry = buildRegistry({ client, quit }, endpoint, {
         dashboardUrl: `http://${cfg.bindHost}:${cfg.supervisorPort}/`,
         reportRepo: cfg.reportRepo,
-        appVersion: "0.0.1",
+        appVersion: "0.0.2",
         platform: `${process.platform} node-${process.version}`,
         resetClient,
+        // Re-run device-code login, then restart the worker so it picks up the new token.
+        login: async () => {
+            const lines = [];
+            await runDeviceLogin(dataDir(), fetch, (m) => lines.push(m));
+            await client.restart().catch(() => { });
+            lines.push("worker restarting with the new token");
+            return lines;
+        },
+        // Clear the stored token and restart the worker (it will report unauthenticated until re-login).
+        logout: async () => {
+            clearGhToken(dataDir());
+            await client.restart().catch(() => { });
+            return ["signed out — GitHub token removed", "run /login to sign in again"];
+        },
     });
     // Filled in below once we have a token; the assistant prefers a model's real window over the default.
     const modelLimits = {};
@@ -127,7 +141,7 @@ async function launchTui() {
     }));
 }
 const program = new Command();
-program.name("copilot-reverse").description("copilot-reverse: interactive Copilot proxy").version("0.0.1");
+program.name("copilot-reverse").description("copilot-reverse: interactive Copilot proxy").version("0.0.2");
 program.command("login").description("GitHub device-code login").action(() => runDeviceLogin(dataDir()));
 program.action(() => { void launchTui(); });
 program.parseAsync(process.argv);

package/dist/shared/creds.js

@@ -1,4 +1,4 @@
-import { existsSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
+import { existsSync, mkdirSync, readFileSync, writeFileSync, rmSync } from "node:fs";
 import { join } from "node:path";
 // M1: plaintext token in the data dir (0600). Encryption-at-rest is M2.
 const file = (dir) => join(dir, "creds.json");
@@ -12,3 +12,7 @@ export function readGhToken(dir) {
         return null;
     return JSON.parse(readFileSync(file(dir), "utf8")).ghToken ?? null;
 }
+// Remove the stored token (logout). No-op if there's nothing to remove.
+export function clearGhToken(dir) {
+    rmSync(file(dir), { force: true });
+}

package/dist/tui/assistant/on-chat.js

@@ -18,8 +18,15 @@ export function makeOnChat(cfg, runner, timeoutMs = DEFAULT_TURN_TIMEOUT_MS) {
                 print("⎿ interrupted");
                 return;
             }
-            print(`assistant error: ${err instanceof Error ? err.message : String(err)}`);
-            print("\n  ↳ next: retry · /model to switch model · /doctor to check health · /report to file it");
+            const message = err instanceof Error ? err.message : String(err);
+            print(`assistant error: ${message}`);
+            // Detect an expired/revoked GitHub login anywhere in the error and steer the user to re-auth.
+            if (/login expired|authentication_error|unauthorized|\b401\b|\b403\b|token exchange failed/i.test(message)) {
+                print("\n  ↳ your GitHub login looks expired — run /login to sign in again");
+            }
+            else {
+                print("\n  ↳ next: retry · /model to switch model · /doctor to check health · /report to file it");
+            }
         }
     };
 }

package/dist/tui/slash/commands.js

@@ -42,6 +42,8 @@ export function buildRegistry(ctx, endpoint, opts = {}) {
     reg.add({ name: "/setup-status", describe: "show configured endpoints", run: async () => [`OpenAI: http://${endpoint.host}:${endpoint.port}/v1`, `Anthropic: http://${endpoint.host}:${endpoint.port}`] });
     reg.add({ name: "/reset-claude", describe: "restore Claude Code config (remove copilot-reverse's keys)", run: async () => opts.resetClient ? opts.resetClient("claude") : ["reset not available"] });
     reg.add({ name: "/reset-codex", describe: "restore Codex/OpenAI config (remove copilot-reverse's keys)", run: async () => opts.resetClient ? opts.resetClient("codex") : ["reset not available"] });
+    reg.add({ name: "/login", describe: "sign in to GitHub (device-code)", run: async () => opts.login ? opts.login() : ["login not available"] });
+    reg.add({ name: "/logout", describe: "sign out — remove the stored GitHub token", run: async () => opts.logout ? opts.logout() : ["logout not available"] });
     reg.add({ name: "/model", describe: "switch the chat model", run: async () => ["opening model picker…"] });
     reg.add({ name: "/config", describe: "view & change configuration", run: async () => ["opening config panel…"] });
     reg.add({ name: "/dashboard", describe: "open the web dashboard in your browser", run: async () => {

package/dist/worker/errors.js

@@ -2,6 +2,10 @@
 // structured context-window-exceeded + model_not_supported guidance instead of a bare 400).
 export function errorHint(message) {
     const m = message.toLowerCase();
+    // An expired/revoked GitHub login — tell the user to re-authenticate from inside the app.
+    if (/login expired|authentication_error|token exchange failed|unauthorized|\b401\b|\b403\b/.test(m)) {
+        return "GitHub login expired — run /login to sign in again";
+    }
     if (/context_length_exceeded|prompt is too long|maximum context|too many tokens|context window/.test(m)) {
         return "context window exceeded — the conversation is too long; /compact or switch to a larger-context model";
     }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "copilot-reverse",
-  "version": "0.0.1",
+  "version": "0.0.2",
   "description": "Interactive terminal app that exposes your GitHub Copilot subscription as local OpenAI- and Anthropic-compatible endpoints, with a self-healing daemon and a built-in assistant.",
   "type": "module",
   "license": "MIT",
@@ -18,7 +18,6 @@
   "files": [
     "dist",
     "README.md",
-    "GUIDE.md",
     "images"
   ],
   "keywords": [

package/GUIDE.md

@@ -1,142 +0,0 @@
-# copilot-reverse — User Guide
-
-**Use the Copilot subscription you already pay for as a local Claude Code / Codex backend.**
-No new API keys. No per-token bills. One terminal app.
-
-```
-  ┌─────────────┐        ┌──────────────────┐        ┌─────────────┐
-  │ Claude Code │ ─────▶ │  copilot-reverse  │ ─────▶ │   Copilot   │
-  │   / Codex   │  local │  (your machine)   │  proxy │  (your sub) │
-  └─────────────┘        └──────────────────┘        └─────────────┘
-```
-
----
-
-## 60-second start
-
-```bash
-npx copilot-reverse
-```
-
-1. It asks you to log in to GitHub (device code — paste a code in your browser). One time only.
-2. The terminal app launches. You'll see a prompt and a status bar.
-3. In the app, type:
-   ```
-   /setup-claude
-   ```
-   Pick a model (e.g. **claude-opus-4.8 (1M)**), choose **global**, done.
-4. Open a **new** terminal and run `claude`. It's now talking to Copilot through copilot-reverse. 🎉
-
-That's it. Codex users: run `/setup-codex` instead.
-
-Here's the app itself — a prompt, a live status bar, and slash-command autocomplete:
-
-```text
- ✳ copilot-reverse                                                       worker: ready
-
- Type a message to chat with the assistant, or /help for commands.
-╭─────────────────────────────────────────────────────────────────────────────────────╮
-│ › /setup                                                                              │
-╰─────────────────────────────────────────────────────────────────────────────────────╯
-  ❯ /setup-claude   print Claude Code config
-    /setup-codex    print Codex/OpenAI config
-    /setup-status   show configured endpoints
-    ↑↓ navigate · tab complete · enter run
- model claude-opus-4.8  ·  daemon ready  ·  claude u:✓ p:○  codex u:✓ p:○  ·  /help
-```
-
----
-
-## What can I do in the app?
-
-Just **talk to it** — it understands plain English and will do the work for you:
-
-> *"list models"* → shows every model + its context window
-> *"set up claude"* → configures Claude Code
-> *"is the worker healthy?"* → runs a health check
-> *"why did my last request fail?"* → shows the error
-
-Prefer commands? Type `/` to see them all. The essentials:
-
-| Command | What it does |
-|---|---|
-| `/setup-claude` · `/setup-codex` | Point Claude Code / Codex at copilot-reverse |
-| `/model` | Switch the chat model (1M-context models marked) |
-| `/status` · `/doctor` | Is everything healthy? |
-| `/logs` · `/metrics` | What ran, what failed, and why |
-| `/dashboard` | Open a live web dashboard in your browser |
-| `/report` | File a pre-filled bug report (diagnostics only — no prompts) |
-| `/reset-claude` · `/reset-codex` | Undo setup, restore original config |
-| `/help` · `/quit` | List commands · exit |
-
-### The live dashboard
-
-`/dashboard` opens a self-refreshing web view of everything happening through the proxy — worker
-health, request volume, and (most useful) recent **errors with their real messages**:
-
-![copilot-reverse dashboard](images/dashboard.png)
-
----
-
-## Connect your own tools
-
-Already have something that speaks OpenAI or Anthropic? Point it here:
-
-- **OpenAI-compatible:** `http://127.0.0.1:7891/v1`
-- **Anthropic-compatible:** `http://127.0.0.1:7891`
-
-Any API key value works locally (it's your machine). Example:
-
-```bash
-export ANTHROPIC_BASE_URL=http://127.0.0.1:7891
-export ANTHROPIC_API_KEY=local
-claude
-```
-
----
-
-## The status bar, decoded
-
-The bottom line of the app (see the screenshot above) tells you everything at a glance:
-
-```text
-model claude-opus-4.8  ·  daemon ready  ·  claude u:✓ p:○  codex u:○ p:○  ·  /help
-```
-
-- **worker / daemon** — green `ready` means the proxy is up and self-healing.
-- **claude u:✓ p:○** — Claude Code is configured at the **u**ser (global) level, not in this **p**roject. Read live from your real config files.
-
----
-
-## Troubleshooting
-
-**"context 100%" or `/compact` fails in Claude Code**
-Re-run `/setup-claude` and pick a **1M** model (e.g. `claude-opus-4.8 (1M)`). copilot-reverse writes
-the right context-window hint so the client stops assuming a small window. Then restart Claude Code.
-
-**"GitHub login expired"**
-Your Copilot session lapsed. Restart copilot-reverse — it'll prompt you to log in again.
-
-**A request failed and I don't know why**
-Type `/logs` (or ask *"why did that fail?"*). Every failure is captured with its real upstream
-message. Still stuck? `/report` opens a pre-filled GitHub issue with diagnostics — **never** your
-prompt content.
-
-**Want to undo everything**
-`/reset-claude` and `/reset-codex` remove exactly the keys copilot-reverse added and leave the rest
-of your config untouched.
-
----
-
-## Good to know
-
-- **Your data stays local.** The app proxies between your editor and Copilot on `127.0.0.1`. Your
-  GitHub token lives only in `~/.copilot-reverse/creds.json` on your own disk.
-- **It heals itself.** If the proxy crashes, the supervisor restarts it with backoff and records why.
-- **Unofficial endpoints.** This uses community-documented Copilot endpoints with *your own*
-  subscription. It may break if GitHub changes them — that's the trade-off for not needing extra keys.
-
----
-
-Questions or bugs? Use `/report` from inside the app, or open an issue on
-[GitHub](https://github.com/wangcansunking/copilot-reverse). Happy hacking. 🚀