copilot-relay 0.2.3 → 0.2.5

package/README.md

@@ -69,7 +69,6 @@ the top-level `model` field in `~/.claude/settings.json`. Exact
 Config lives at `~/.copilot-relay/config.yaml` and is hot-reloaded:
 
 ```yaml
-configVersion: 2
 host: 127.0.0.1
 port: 4142
 copilotBaseUrl: https://api.githubcopilot.com
@@ -81,9 +80,10 @@ upstreamTimeoutSeconds: 180
 webSearchBackend:
 ```
 
-`configVersion` is managed by copilot-relay. It gates one-time migrations that
-update a shipped default on installs which already persisted the previous value;
-do not edit it.
+copilot-relay writes the resolved config back to this file, so every key is
+present after the first start. Shipped defaults therefore apply to fresh
+installs only — once a value is in your `config.yaml` it is never rewritten by
+an upgrade. To pick up a changed default, edit the key yourself.
 
 `logLevel` controls verbosity:
 
@@ -112,9 +112,32 @@ 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, `1` not
+running, `2` running but the deep check failed.
+
 ## Logging
 
 At `debug`, every model request logs the requested model, upstream model, requested think effort, requested thinking, and effective think effort.
@@ -139,12 +162,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/config.default.yaml

@@ -4,10 +4,10 @@
 # Edit the user config file, not this template, for local changes.
 # Most values hot-reload while the service is running. host and port still
 # require restart because the listening socket is already bound.
-
-# Config schema version. Managed by copilot-relay; do not edit.
-# Used to apply one-time migrations when a shipped default changes.
-configVersion: 2
+#
+# Values here apply to a fresh install only. copilot-relay writes the resolved
+# config back to disk, so once a key exists in your config.yaml it is yours:
+# changing a shipped default never rewrites it.
 
 # Local host for the Claude Code-compatible HTTP server.
 host: 127.0.0.1

package/dist/main.js

@@ -436,24 +436,15 @@ const logLevels = [
 	"debug"
 ];
 /**
-* Schema version of ~/.copilot-relay/config.yaml.
+* Values used when a key is absent from the user's config.
 *
-* Bumped whenever a shipped default changes in a way that must reach installs
-* that already persisted the previous value. See supersededOpusModels.
+* readAppConfig() writes the resolved config back to disk, so an existing
+* install has every key materialized and never consults these again. Changing
+* one therefore affects fresh installs only, by design: copilot-relay does not
+* rewrite a value the user's config already holds.
 */
-const currentConfigVersion = 2;
-/**
-* Opus defaults shipped by earlier releases.
-*
-* readAppConfig() writes the resolved config back to disk, so every install
-* that ever ran an older build has the superseded default sitting in its
-* config.yaml. Without this set, bumping defaultConfig.opusModel would only
-* ever reach fresh installs.
-*/
-const supersededOpusModels = new Set(["claude-opus-4.8"]);
 const defaultConfig = {
 	claudeSetup: true,
-	configVersion: currentConfigVersion,
 	copilotBaseUrl: "https://api.githubcopilot.com",
 	gptModel: "gpt-5.6-sol",
 	host: "127.0.0.1",
@@ -543,10 +534,6 @@ const parseConfigYaml = (content) => {
 			case "claude_setup":
 				config.claudeSetup = unquoteYamlScalar(value);
 				break;
-			case "configVersion":
-			case "config_version":
-				config.configVersion = unquoteYamlScalar(value);
-				break;
 			case "copilotBaseUrl":
 			case "copilot_base_url":
 				config.copilotBaseUrl = unquoteYamlScalar(value);
@@ -601,9 +588,6 @@ const serializeConfig = (config) => [
 	"#",
 	"# This file is hot-reloaded while copilot-relay is running.",
 	"",
-	"# Config schema version. Managed by copilot-relay; do not edit.",
-	`configVersion: ${config.configVersion}`,
-	"",
 	"# Local host for the Claude Code-compatible HTTP server.",
 	`host: ${config.host}`,
 	"",
@@ -645,17 +629,6 @@ const serializeConfig = (config) => [
 	`opusModel: ${config.opusModel}`,
 	""
 ].join("\n");
-/**
-* Resolve opusModel, applying the one-time superseded-default migration.
-*
-* Gated on configVersion so it runs exactly once. Without that gate the rewrite
-* would re-run on every start, which would make a superseded model impossible
-* to pin deliberately - the user's edit would be reverted underneath them.
-*/
-const resolveOpusModel = (rawOpusModel, configVersion) => {
-	if (rawOpusModel === void 0) return defaultConfig.opusModel;
-	return configVersion < currentConfigVersion && supersededOpusModels.has(rawOpusModel) ? defaultConfig.opusModel : rawOpusModel;
-};
 async function readAppConfig() {
 	const raw = await readRawConfig();
 	const claudeSetup = normalizeBoolean(raw.claudeSetup);
@@ -665,16 +638,14 @@ async function readAppConfig() {
 	const port = normalizePort(raw.port);
 	const thinkEffort = normalizeThinkEffort(raw.thinkEffort);
 	const upstreamTimeoutSeconds = normalizeUpstreamTimeoutSeconds(raw.upstreamTimeoutSeconds);
-	const configVersion = normalizePositiveInteger(raw.configVersion) ?? 1;
 	const config = {
 		claudeSetup: claudeSetup ?? defaultConfig.claudeSetup,
-		configVersion: currentConfigVersion,
 		copilotBaseUrl: normalizeString(raw.copilotBaseUrl) ?? defaultConfig.copilotBaseUrl,
 		gptModel: normalizeString(raw.gptModel) ?? defaultConfig.gptModel,
 		host: host ?? defaultConfig.host,
 		logLevel: logLevel ?? defaultConfig.logLevel,
 		logRetentionDays: logRetentionDays$1 ?? defaultConfig.logRetentionDays,
-		opusModel: resolveOpusModel(normalizeString(raw.opusModel), configVersion),
+		opusModel: normalizeString(raw.opusModel) ?? defaultConfig.opusModel,
 		port: port ?? defaultConfig.port,
 		thinkEffort: thinkEffort ?? defaultConfig.thinkEffort,
 		upstreamTimeoutSeconds: upstreamTimeoutSeconds ?? defaultConfig.upstreamTimeoutSeconds,
@@ -780,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();
@@ -2869,9 +2867,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();
@@ -3049,6 +3047,195 @@ 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.
+*/
+const exitCodes = {
+	deepCheckFailed: 2,
+	notRunning: 1,
+	running: 0
+};
+const localProbeTimeoutMs = 5e3;
+const deepProbeTimeoutMs = 6e4;
+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 pids = await findRelayProcessIds(readProxyConfig(appConfig));
+	if (pids.length === 0) return {
+		...base,
+		running: false
+	};
+	const entry = await readRelayPidFileEntry();
+	const host = entry?.host ?? appConfig.host;
+	const port = entry?.port ?? appConfig.port;
+	const baseUrl = `http://${host}:${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: entry?.pid ?? pids[0],
+		port,
+		running: true,
+		...entry?.startedAt ? { startedAt: entry.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 = !result.running ? exitCodes.notRunning : result.deep && !result.deep.ok ? exitCodes.deepCheckFailed : exitCodes.running;
+	}
+});
+
 //#endregion
 //#region src/stop.ts
 const stop = defineCommand({
@@ -3076,6 +3263,7 @@ await runMain(defineCommand({
 		auth,
 		restart,
 		start,
+		status,
 		stop
 	}
 }));