copilot-relay 0.2.4 → 0.2.6

package/README.md

@@ -112,9 +112,34 @@ The same folder stores `copilot_token.json` for the cached Copilot bearer token,
 copilot-relay auth
 copilot-relay start
 copilot-relay restart
+copilot-relay status
 copilot-relay stop
 ```
 
+`status` reports whether a relay is running, where it is listening, and whether
+it is reachable:
+
+```text
+copilot-relay 0.2.5
+  process    running (pid 93744, up 1h 16m)
+  listening  http://127.0.0.1:4142
+  health     ok (9ms)
+  models     gpt-5.6-sol[1m], claude-opus-5
+  upstream   not checked (use --deep)
+  log        ~/.copilot-relay/logs/copilot-relay.2026-07-25.log
+  config     ~/.copilot-relay/config.yaml (logLevel=info, thinkEffort=max)
+```
+
+`--deep` additionally sends a real request through Copilot. That is the only
+check that proves the relay can actually serve Claude Code — a relay whose
+Copilot token expired an hour ago still answers `/healthz` and `/v1/models`,
+because neither contacts upstream. It is opt-in because it spends a few tokens.
+
+`--json` emits machine-readable output. Exit codes: `0` running and reachable,
+`1` not running, `2` running but not usable — the health probe failed, or
+`--deep` was requested and failed. `0` requires a live process *and* a passing
+health probe, so a relay that cannot answer `/healthz` never reports success.
+
 ## Logging
 
 At `debug`, every model request logs the requested model, upstream model, requested think effort, requested thinking, and effective think effort.
@@ -139,12 +164,23 @@ grep -n "Failed to create\\|Startup preflight failed" ~/.copilot-relay/logs/copi
 
 See [`docs/troubleshooting.md`](docs/troubleshooting.md) for common debugging workflows.
 
+## Running it as a service
+
+To keep the relay running across reboots, see [`wiki/`](wiki/) — per-platform
+setup for macOS, Windows, and Linux, in English and 中文, each covering
+registration, how to verify it is *actually* working rather than merely
+listening, and how to stop it.
+
+The same pages are published to the [wiki tab](https://github.com/D0n9X1n/copilot-relay/wiki),
+which is generated from `wiki/` on every merge. Edit the folder, not the tab.
+
 ## Development
 
 Developer notes live in [`docs/development.md`](docs/development.md).
 Architecture notes live in [`docs/architecture.md`](docs/architecture.md).
 Logging notes live in [`docs/logging.md`](docs/logging.md).
 Troubleshooting notes live in [`docs/troubleshooting.md`](docs/troubleshooting.md).
+User-facing guides live in [`wiki/`](wiki/).
 
 ```sh
 npm install

package/dist/main.js

@@ -7,11 +7,11 @@ import os from "node:os";
 import path, { dirname, resolve } from "node:path";
 import { fileURLToPath } from "node:url";
 import { execFile } from "node:child_process";
+import { createAdaptorServer } from "@hono/node-server";
 import { createHash, randomUUID } from "node:crypto";
 import { Agent, fetch as fetch$1 } from "undici";
 import { events } from "fetch-event-stream";
 import { readFileSync } from "node:fs";
-import { createAdaptorServer } from "@hono/node-server";
 import { Hono } from "hono";
 import { cors } from "hono/cors";
 import { streamSSE } from "hono/streaming";
@@ -751,6 +751,33 @@ const isProcessAlive = (pid) => {
 		return isNodeErrno(error) && error.code === "EPERM";
 	}
 };
+/**
+* Full pid-file record, for callers that need the listening address or start
+* time rather than just the pid.
+*
+* Deliberately tolerant: a corrupt or half-written pid file yields undefined
+* rather than throwing, because `status` must be able to report "not running"
+* instead of crashing on a file the user may have been mid-edit on.
+*
+* Returns undefined for the legacy bare-pid format, which carries no address.
+*/
+const readRelayPidFileEntry = async () => {
+	try {
+		const trimmed = (await fs.readFile(paths.pidPath, "utf8")).trim();
+		if (!trimmed || !trimmed.startsWith("{")) return;
+		const payload = JSON.parse(trimmed);
+		const pid = parsePid(payload.pid);
+		if (pid === void 0 || typeof payload.host !== "string" || typeof payload.port !== "number") return;
+		return {
+			host: payload.host,
+			pid,
+			port: payload.port,
+			startedAt: typeof payload.startedAt === "string" ? payload.startedAt : ""
+		};
+	} catch {
+		return;
+	}
+};
 const readRelayPidFile = async () => {
 	try {
 		const trimmed = (await fs.readFile(paths.pidPath, "utf8")).trim();
@@ -837,6 +864,27 @@ const isRelayPid = async (pid) => {
 	if (!command) return false;
 	return isRelayStartProcess(command, await getProcessCwd(pid));
 };
+/**
+* The relay serving `config.port`, or undefined if nothing is.
+*
+* Deliberately narrower than findRelayProcessIds: it never consults the global
+* process list. `stop` wants "any relay anywhere" so it can clean up strays;
+* `status` is asked about one configured relay, and answering with a different
+* one is worse than answering "not running" because it looks authoritative.
+*
+* Returns pid and address as a single coherent record, so a pid discovered one
+* way can never be printed next to an address taken from another.
+*/
+const findRelayOnPort = async (config) => {
+	const entry = await readRelayPidFileEntry();
+	if (entry && entry.port === config.port && isProcessAlive(entry.pid) && await isRelayPid(entry.pid)) return entry;
+	for (const pid of await getPortListenerPids(config.port)) if (await isRelayPid(pid)) return {
+		host: config.host,
+		pid,
+		port: config.port,
+		startedAt: ""
+	};
+};
 const findRelayProcessIds = async (config) => {
 	const candidates = /* @__PURE__ */ new Set();
 	const storedPid = await readRelayPidFile();
@@ -2840,9 +2888,9 @@ const getLoggedHeaders = (request) => Object.fromEntries(loggedRequestHeaders.fl
 	const value = request.headers.get(name);
 	return value ? [[name, value]] : [];
 }));
-const formatStatusLog = (requestId, method, path$1, status, ms, errorMessage) => {
-	const base = `request_id=${requestId} ${method} ${path$1} -> ${status} ${ms}ms`;
-	return status >= 400 && errorMessage ? `${base} error=${JSON.stringify(errorMessage)}` : base;
+const formatStatusLog = (requestId, method, path$1, status$1, ms, errorMessage) => {
+	const base = `request_id=${requestId} ${method} ${path$1} -> ${status$1} ${ms}ms`;
+	return status$1 >= 400 && errorMessage ? `${base} error=${JSON.stringify(errorMessage)}` : base;
 };
 const createServer = (config) => {
 	const app = new Hono();
@@ -2912,6 +2960,7 @@ const startServer = (config) => new Promise((resolve$1, reject) => {
 
 //#endregion
 //#region src/start.ts
+const canCloseConnections = (server) => typeof server.closeIdleConnections === "function" && typeof server.closeAllConnections === "function";
 async function startRelay(appConfig) {
 	appConfig ??= await readAppConfig();
 	setLogLevel(appConfig.logLevel);
@@ -2970,6 +3019,7 @@ async function startRelay(appConfig) {
 		applyRuntimeConfig(nextConfig);
 		log.info(`Config reloaded: logLevel=${nextConfig.logLevel} thinkEffort=${nextConfig.thinkEffort} upstreamTimeoutSeconds=${nextConfig.upstreamTimeoutSeconds}`);
 	});
+	const shutdownGraceMs = 2e3;
 	const shutdown = (signal) => {
 		log.info(`Received ${signal}; shutting down copilot-relay`);
 		server.close((error) => {
@@ -2978,6 +3028,13 @@ async function startRelay(appConfig) {
 				process.exitCode = 1;
 			}
 		});
+		if (canCloseConnections(server)) {
+			server.closeIdleConnections();
+			setTimeout(() => {
+				log.info("Grace period elapsed; closing remaining connections");
+				server.closeAllConnections();
+			}, shutdownGraceMs).unref();
+		}
 	};
 	process.once("SIGINT", shutdown);
 	process.once("SIGTERM", shutdown);
@@ -3020,6 +3077,204 @@ const restart = defineCommand({
 	}
 });
 
+//#endregion
+//#region src/status.ts
+/**
+* Exit codes, so `status` is usable in a health check or a script.
+*
+* 2 is distinct from 1 on purpose: "running but broken" and "not running" call
+* for different responses - restart the service versus re-authenticate.
+*
+* A failed health probe is a 2, not a 0. Printing FAILED while exiting 0 would
+* make every scripted caller treat an unreachable relay as fine. See #34.
+*/
+const exitCodes = {
+	notRunning: 1,
+	notUsable: 2,
+	running: 0
+};
+const localProbeTimeoutMs = 5e3;
+const deepProbeTimeoutMs = 6e4;
+/**
+* Status to exit code. Pure, because this mapping is the contract every
+* scripted caller depends on and deserves direct coverage.
+*
+* 0 requires a live process *and* a passing health probe. Printing FAILED while
+* exiting 0 would make every scripted caller treat an unreachable relay as
+* fine. See #34.
+*/
+const resolveExitCode = (status$1) => !status$1.running ? exitCodes.notRunning : !status$1.health?.ok ? exitCodes.notUsable : status$1.deep && !status$1.deep.ok ? exitCodes.notUsable : exitCodes.running;
+const formatUptime = (startedAt) => {
+	if (!startedAt) return "unknown";
+	const started = Date.parse(startedAt);
+	if (Number.isNaN(started)) return "unknown";
+	const seconds = Math.max(0, Math.floor((Date.now() - started) / 1e3));
+	if (seconds < 60) return `${seconds}s`;
+	if (seconds < 3600) return `${Math.floor(seconds / 60)}m`;
+	if (seconds < 86400) return `${Math.floor(seconds / 3600)}h ${Math.floor(seconds % 3600 / 60)}m`;
+	return `${Math.floor(seconds / 86400)}d ${Math.floor(seconds % 86400 / 3600)}h`;
+};
+/**
+* Pure state-to-lines mapping, kept free of IO so it can be tested directly
+* without spawning a relay or opening a socket.
+*/
+const renderStatus = (status$1) => {
+	const lines = [`copilot-relay ${status$1.version}`];
+	if (!status$1.running) {
+		lines.push("  process    not running", `  config     ${status$1.configPath} (logLevel=${status$1.logLevel}, thinkEffort=${status$1.thinkEffort})`, `  log        ${status$1.logPath}`, "", "  Start it with: copilot-relay start");
+		return lines;
+	}
+	lines.push(`  process    running (pid ${status$1.pid}, up ${formatUptime(status$1.startedAt)})`, `  listening  ${status$1.baseUrl}`);
+	const health = status$1.health;
+	lines.push(health?.ok ? `  health     ok (${health.ms}ms)` : `  health     FAILED${health?.detail ? ` — ${health.detail}` : ""}`);
+	lines.push(status$1.models?.length ? `  models     ${status$1.models.join(", ")}` : "  models     unavailable");
+	if (status$1.deep) lines.push(status$1.deep.ok ? `  upstream   ok (${status$1.deep.ms}ms) — end-to-end Copilot round trip` : `  upstream   FAILED${status$1.deep.detail ? ` — ${status$1.deep.detail}` : ""}`);
+	else lines.push("  upstream   not checked (use --deep)");
+	lines.push(`  log        ${status$1.logPath}`, `  config     ${status$1.configPath} (logLevel=${status$1.logLevel}, thinkEffort=${status$1.thinkEffort})`);
+	if (status$1.health?.ok && status$1.deep && !status$1.deep.ok) lines.push("", "  The relay is listening but cannot reach Copilot.", "  Try: copilot-relay auth");
+	return lines;
+};
+const probe = async (url, init, timeoutMs) => {
+	const started = performance.now();
+	const response = await fetch(url, {
+		...init,
+		signal: AbortSignal.timeout(timeoutMs)
+	});
+	return {
+		body: await response.json().catch(() => void 0),
+		ms: Math.round(performance.now() - started),
+		ok: response.ok,
+		status: response.status
+	};
+};
+const describeError = (error) => error instanceof Error ? error.name === "TimeoutError" ? "timed out" : error.message : String(error);
+const checkHealth = async (baseUrl) => {
+	try {
+		const result = await probe(`${baseUrl}/healthz`, {}, localProbeTimeoutMs);
+		return result.ok ? {
+			ms: result.ms,
+			ok: true
+		} : {
+			detail: `http ${result.status}`,
+			ms: result.ms,
+			ok: false
+		};
+	} catch (error) {
+		return {
+			detail: describeError(error),
+			ok: false
+		};
+	}
+};
+const readModels = async (baseUrl) => {
+	try {
+		const data = (await probe(`${baseUrl}/v1/models`, {}, localProbeTimeoutMs)).body?.data;
+		return Array.isArray(data) ? data.flatMap((model) => typeof model.id === "string" ? [model.id] : []) : [];
+	} catch {
+		return [];
+	}
+};
+/**
+* Layer 3: a real request through Copilot.
+*
+* Opt-in because it spends tokens. It is the only check that exercises token
+* refresh, the upstream call, and translation back to Claude shape.
+*/
+const checkDeep = async (baseUrl, model) => {
+	try {
+		const result = await probe(`${baseUrl}/v1/messages`, {
+			body: JSON.stringify({
+				max_tokens: 16,
+				messages: [{
+					content: "Reply with the single word: ok",
+					role: "user"
+				}],
+				model
+			}),
+			headers: {
+				"anthropic-version": "2023-06-01",
+				"content-type": "application/json"
+			},
+			method: "POST"
+		}, deepProbeTimeoutMs);
+		if (!result.ok) {
+			const message = result.body?.error?.message;
+			return {
+				detail: message ? `http ${result.status}: ${message}` : `http ${result.status}`,
+				ms: result.ms,
+				ok: false
+			};
+		}
+		const content = result.body?.content;
+		return Array.isArray(content) && content.length > 0 ? {
+			ms: result.ms,
+			ok: true
+		} : {
+			detail: "empty response",
+			ms: result.ms,
+			ok: false
+		};
+	} catch (error) {
+		return {
+			detail: describeError(error),
+			ok: false
+		};
+	}
+};
+const collectStatus = async (options) => {
+	const appConfig = await readAppConfig();
+	setLogLevel(appConfig.logLevel);
+	const base = {
+		configPath: paths.configPath,
+		logLevel: appConfig.logLevel,
+		logPath: getLogPath(),
+		thinkEffort: appConfig.thinkEffort,
+		version: appVersion
+	};
+	const relay = await findRelayOnPort(readProxyConfig(appConfig));
+	if (!relay) return {
+		...base,
+		running: false
+	};
+	const baseUrl = `http://${relay.host}:${relay.port}`;
+	const health = await checkHealth(baseUrl);
+	const models = health.ok ? await readModels(baseUrl) : [];
+	const deep = options.deep && health.ok ? await checkDeep(baseUrl, models[0] ?? appConfig.gptModel) : void 0;
+	return {
+		...base,
+		baseUrl,
+		...deep ? { deep } : {},
+		health,
+		models,
+		pid: relay.pid,
+		port: relay.port,
+		running: true,
+		...relay.startedAt ? { startedAt: relay.startedAt } : {}
+	};
+};
+const status = defineCommand({
+	meta: {
+		name: "status",
+		description: "Show whether copilot-relay is running and reachable."
+	},
+	args: {
+		deep: {
+			description: "Also send a real request through Copilot. Proves the relay works end to end; spends a few tokens.",
+			type: "boolean"
+		},
+		json: {
+			description: "Emit machine-readable JSON.",
+			type: "boolean"
+		}
+	},
+	async run({ args }) {
+		const result = await collectStatus({ deep: Boolean(args.deep) });
+		if (args.json) console.log(JSON.stringify(result, null, 2));
+		else console.log(renderStatus(result).join("\n"));
+		process.exitCode = resolveExitCode(result);
+	}
+});
+
 //#endregion
 //#region src/stop.ts
 const stop = defineCommand({
@@ -3047,6 +3302,7 @@ await runMain(defineCommand({
 		auth,
 		restart,
 		start,
+		status,
 		stop
 	}
 }));