copilot-relay 0.0.4 → 0.0.6

package/README.md

@@ -11,6 +11,13 @@
 
 Yet, just another relay for Claude Code to use a GitHub Copilot subscription.
 
+## Disclaimer
+
+This is a research-oriented project and is not affiliated with GitHub, GitHub
+Copilot, Anthropic, or Claude Code. It depends on upstream GitHub Copilot
+services and undocumented compatibility behavior, so Copilot availability, model
+access, API behavior, and runtime stability are not guaranteed.
+
 Public API:
 
 - `POST /v1/messages`
@@ -18,6 +25,13 @@ Public API:
 - `GET /v1/models`
 - `GET /healthz`
 
+Claude WebSearch is bridge-managed: when the model selects the WebSearch tool,
+the relay executes Copilot `/responses` with `web_search_preview`, then sends the
+retrieved context through a final model pass and returns Claude
+`server_tool_use` / `web_search_tool_result` blocks. Unknown API routes return
+`500` and log method, path, selected headers, and request payload to help
+implement compatible endpoints later.
+
 Routing:
 
 | Requested model | Upstream model |
@@ -46,6 +60,7 @@ claudeSetup: true
 logLevel: info
 logRetentionDays: 3
 thinkEffort: xhigh
+webSearchBackend:
 ```
 
 `logLevel` controls verbosity:
@@ -54,12 +69,15 @@ thinkEffort: xhigh
 | --- | --- |
 | `error` | Startup, preflight, and request failures |
 | `info` | Errors plus startup status, preflight status, and local HTTP status codes |
-| `debug` | Info plus model routing summaries, Copilot upstream timings, token refresh scheduling, and request payloads |
+| `debug` | Info plus model routing summaries, Copilot upstream timings, and request payloads |
 
 Any other `logLevel` value is invalid and stops startup.
 
 Valid `thinkEffort`: `none`, `low`, `medium`, `high`, `xhigh`.
 
+`webSearchBackend` controls bridge-managed Claude WebSearch. Leave it empty to
+use `gptModel`, or set a Copilot Responses model ID such as `gpt-5.5`.
+
 The same folder stores `copilot_token.json` for the cached Copilot bearer token, `github_token` for refresh/login, and `logs/` for runtime logs.
 
 ## CLI
@@ -75,13 +93,26 @@ At `debug`, every model request logs the requested model, upstream model, reques
 
 Upstream failures are logged at `error` with full request and response context in the same log file.
 
+Unsupported Claude API requests are logged at `error` with the local method/path
+and detailed request payload.
+
 Logs are written to `~/.copilot-relay/logs/copilot-relay.log`; old `.log` files are cleaned according to `logRetentionDays`.
 
+Quick inspection:
+
+```sh
+tail -f ~/.copilot-relay/logs/copilot-relay.log
+grep -n "Failed to create\\|Startup preflight failed" ~/.copilot-relay/logs/copilot-relay.log
+```
+
+See [`docs/troubleshooting.md`](docs/troubleshooting.md) for common debugging workflows.
+
 ## 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).
 
 ```sh
 npm install

package/config.default.yaml

@@ -2,6 +2,8 @@
 #
 # This file is copied to ~/.copilot-relay/config.yaml on first start.
 # 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.
 
 # Local host for the Claude Code-compatible HTTP server.
 host: 127.0.0.1
@@ -22,7 +24,7 @@ claudeSetup: true
 #   info  - error logs plus startup status, preflight status, and local HTTP
 #           status codes
 #   debug - info logs plus model routing summaries, Copilot upstream timings,
-#           token refresh scheduling, and request payloads
+#           and request payloads
 # Any other value is invalid and stops startup.
 logLevel: info
 
@@ -33,6 +35,10 @@ logRetentionDays: 3
 # Valid values: none, low, medium, high, xhigh.
 thinkEffort: xhigh
 
+# Copilot model used for bridge-managed Claude WebSearch.
+# Leave empty to use gptModel.
+webSearchBackend:
+
 # Model routing: requests containing "opus" use opusModel; all others use gptModel.
 #
 # Upstream Copilot model used for non-Opus requests.

package/dist/main.js

@@ -371,7 +371,8 @@ const defaultConfig = {
 	logRetentionDays: 3,
 	opusModel: "claude-opus-4.8",
 	port: 4142,
-	thinkEffort: defaultReasoningEffort
+	thinkEffort: defaultReasoningEffort,
+	webSearchBackend: void 0
 };
 const isLogLevelName = (value) => typeof value === "string" && logLevels.includes(value.toLowerCase());
 const normalizeLogLevel = (value) => {
@@ -475,6 +476,10 @@ const parseConfigYaml = (content) => {
 			case "think_effort":
 				config.thinkEffort = unquoteYamlScalar(value);
 				break;
+			case "webSearchBackend":
+			case "web_search_backend":
+				config.webSearchBackend = unquoteYamlScalar(value);
+				break;
 			default: break;
 		}
 	}
@@ -508,7 +513,7 @@ const serializeConfig = (config) => [
 	"#   info  - error logs plus startup status, preflight status, and local HTTP",
 	"#           status codes",
 	"#   debug - info logs plus model routing summaries, Copilot upstream timings,",
-	"#           token refresh scheduling, request payloads, and upstream error details",
+	"#           and request payloads",
 	`logLevel: ${config.logLevel}`,
 	"",
 	"# Number of days to keep files in ~/.copilot-relay/logs.",
@@ -517,6 +522,9 @@ const serializeConfig = (config) => [
 	"# Default upstream thinking/reasoning effort: none, low, medium, high, xhigh.",
 	`thinkEffort: ${config.thinkEffort}`,
 	"",
+	"# Copilot model used for bridge-managed Claude WebSearch. Empty uses gptModel.",
+	`webSearchBackend: ${config.webSearchBackend ?? ""}`,
+	"",
 	"# Model routing: requests containing \"opus\" use opusModel; all others use gptModel.",
 	"",
 	"# Upstream Copilot model used for non-Opus requests.",
@@ -543,7 +551,8 @@ async function readAppConfig() {
 		logRetentionDays: logRetentionDays$1 ?? defaultConfig.logRetentionDays,
 		opusModel: normalizeString(raw.opusModel) ?? defaultConfig.opusModel,
 		port: port ?? defaultConfig.port,
-		thinkEffort: thinkEffort ?? defaultConfig.thinkEffort
+		thinkEffort: thinkEffort ?? defaultConfig.thinkEffort,
+		webSearchBackend: normalizeString(raw.webSearchBackend)
 	};
 	await writeConfig(config);
 	return config;
@@ -581,7 +590,8 @@ const readProxyConfig = (config) => ({
 	copilotToken: void 0,
 	host: config.host,
 	port: config.port,
-	vsCodeVersion: vscodeVersion
+	vsCodeVersion: vscodeVersion,
+	webSearchBackend: config.webSearchBackend
 });
 
 //#endregion
@@ -1724,6 +1734,256 @@ function translateErrorToClaudeErrorEvent() {
 	};
 }
 
+//#endregion
+//#region src/claude/web-search.ts
+const anthropicWebSearchToolPattern = /^web_search_\d{8}$/;
+const claudeCodeWebSearchToolName = "WebSearch";
+const searchResultLimit = 8;
+const webSearchInputSchema = {
+	type: "object",
+	properties: { query: {
+		type: "string",
+		description: "The web search query."
+	} },
+	required: ["query"],
+	additionalProperties: false
+};
+const isRecord = (value) => typeof value === "object" && value !== null && !Array.isArray(value);
+const isAnthropicNativeWebSearchTool = (tool) => tool.name === "web_search" && typeof tool.type === "string" && anthropicWebSearchToolPattern.test(tool.type);
+const isClaudeCodeWebSearchTool = (tool) => tool.name === claudeCodeWebSearchToolName;
+const isClaudeWebSearchTool = (tool) => isAnthropicNativeWebSearchTool(tool) || isClaudeCodeWebSearchTool(tool);
+const hasClaudeWebSearch = (payload) => payload.tools?.some(isClaudeWebSearchTool) ?? false;
+const isClaudeWebSearchToolName = (name) => name === "web_search" || name === claudeCodeWebSearchToolName;
+const getWebSearchBackendModel = (config) => config.webSearchBackend?.trim() || getModelRouting().gptModel;
+const prepareClaudeWebSearchDecisionPayload = (payload) => {
+	if (!hasClaudeWebSearch(payload)) return payload;
+	return {
+		...payload,
+		tools: payload.tools?.map((tool) => isClaudeWebSearchTool(tool) ? {
+			...tool,
+			input_schema: tool.input_schema ?? webSearchInputSchema
+		} : tool)
+	};
+};
+const textFromMessageContent = (content) => {
+	if (typeof content === "string") return content;
+	return content.flatMap((block) => {
+		if (block.type === "text") return [block.text];
+		if (block.type === "tool_result") return [block.content];
+		return [];
+	}).join("\n\n");
+};
+const getRequestedQuery = (payload) => {
+	const lastUserMessage = [...payload.messages].reverse().find((message) => message.role === "user");
+	const cleaned = (lastUserMessage ? textFromMessageContent(lastUserMessage.content) : "").replace(/<system-reminder>[\s\S]*?<\/system-reminder>/g, " ").replace(/\s+/g, " ").trim();
+	return cleaned.match(/\bsearch(?:\s+the\s+web)?(?:\s+for)?\s+(.+)$/i)?.[1]?.trim() || cleaned || "web search";
+};
+const getQueryFromToolArguments = (value) => {
+	const trimmed = value.trim();
+	if (!trimmed) return;
+	try {
+		const parsed = JSON.parse(trimmed);
+		if (isRecord(parsed) && typeof parsed.query === "string" && parsed.query.trim()) return parsed.query.trim();
+	} catch {
+		return trimmed;
+	}
+	return trimmed;
+};
+const getClaudeWebSearchToolCallFromChatResponse = (response, toolNameMapper) => {
+	const toolCall = response.choices.flatMap((choice) => choice.message.tool_calls ?? []).find((call) => isClaudeWebSearchToolName(toolNameMapper.toClaude(call.function.name)));
+	if (!toolCall) return;
+	const query = getQueryFromToolArguments(toolCall.function.arguments);
+	return query ? {
+		query,
+		toolCall
+	} : void 0;
+};
+const buildSearchInput = (payload, requestedQuery) => {
+	const systemText = typeof payload.system === "string" ? payload.system : Array.isArray(payload.system) ? payload.system.map((block) => block.text).join("\n\n") : "";
+	const messages = payload.messages.map((message) => `${message.role}: ${textFromMessageContent(message.content)}`).join("\n\n");
+	return [
+		"You are fulfilling an Anthropic web_search server tool request for Claude Code.",
+		"Search the web using the provided web_search_preview tool.",
+		`Requested web search query: ${requestedQuery}`,
+		"Return useful search results as plain text lines in this exact shape:",
+		"1. Title - https://example.com/page",
+		"Include only real source URLs from the search results.",
+		systemText ? `System context:\n${systemText}` : "",
+		`Conversation:\n${messages}`
+	].filter(Boolean).join("\n\n");
+};
+const buildWebSearchRequestPayload = (payload, requestedQuery, model) => ({
+	model,
+	input: buildSearchInput(payload, requestedQuery),
+	tools: [{ type: "web_search_preview" }],
+	max_output_tokens: Math.max(256, Math.min(payload.max_tokens ?? 1024, 1200)),
+	temperature: payload.temperature,
+	top_p: payload.top_p
+});
+const getSearchQuery = (response, requestedQuery) => {
+	for (const item of response.output ?? []) {
+		if (item.type !== "web_search_call") continue;
+		const action = isRecord(item.action) ? item.action : void 0;
+		const queries = Array.isArray(action?.queries) ? action.queries : [];
+		const query = typeof action?.query === "string" ? action.query : typeof queries[0] === "string" ? queries[0] : void 0;
+		if (query) return query;
+	}
+	return requestedQuery.slice(0, 200);
+};
+const getResponseText = (response) => (response.output ?? []).flatMap((item) => {
+	if (item.type !== "message") return [];
+	return (Array.isArray(item.content) ? item.content : []).flatMap((part) => isRecord(part) && part.type === "output_text" && typeof part.text === "string" ? [part.text] : []);
+}).join("\n").trim();
+const cleanTitle = (line, url) => {
+	return line.slice(0, line.indexOf(url)).replace(/^\s*(?:[-*]|\d+[.)])\s*/, "").replace(/\s*(?:[-:|])\s*$/, "").trim() || new URL(url).hostname;
+};
+const parseSearchResults = (text) => {
+	const results = [];
+	const seenUrls = /* @__PURE__ */ new Set();
+	for (const line of text.split(/\r?\n/)) {
+		const markdownMatch = line.match(/\[([^\]]+)]\((https?:\/\/[^)\s]+)\)/);
+		const url = markdownMatch?.[2] ?? line.match(/https?:\/\/[^\s)]+/)?.[0];
+		if (!url || seenUrls.has(url)) continue;
+		seenUrls.add(url);
+		results.push({
+			title: markdownMatch?.[1]?.trim() || cleanTitle(line, url),
+			url
+		});
+		if (results.length >= searchResultLimit) break;
+	}
+	return results;
+};
+const createFailedSearchExecution = (payload, requestedQuery, model, message) => ({
+	id: `msg_${randomUUID().replaceAll("-", "")}`,
+	inputTokens: 0,
+	model,
+	outputTokens: 0,
+	query: requestedQuery || getRequestedQuery(payload),
+	results: [],
+	text: message
+});
+const createClaudeWebSearchExecution = async (config, payload, requestedQuery) => {
+	const backendModel = getWebSearchBackendModel(config);
+	const response = await fetchCopilot(getCopilotProviderContext(config), "/responses", {
+		method: "POST",
+		headers: {
+			accept: "application/json",
+			"content-type": "application/json"
+		},
+		body: JSON.stringify(buildWebSearchRequestPayload(payload, requestedQuery, backendModel))
+	}, { initiator: "agent" });
+	if (!response.ok) {
+		const detail = await response.text().catch(() => "");
+		return createFailedSearchExecution(payload, requestedQuery, backendModel, [`Copilot web search is not available for model ${backendModel}.`, detail ? `Upstream response: ${detail}` : ""].filter(Boolean).join("\n"));
+	}
+	const upstream = await response.json();
+	const text = getResponseText(upstream);
+	const query = getSearchQuery(upstream, requestedQuery);
+	const results = parseSearchResults(text);
+	if (results.length === 0 && !text.trim()) return createFailedSearchExecution(payload, requestedQuery, upstream.model, "Copilot web search did not return search results.");
+	return {
+		id: upstream.id,
+		inputTokens: upstream.usage?.input_tokens ?? 0,
+		model: upstream.model,
+		outputTokens: upstream.usage?.output_tokens ?? 0,
+		query,
+		results,
+		text
+	};
+};
+const buildSearchResultBlock = (toolUseId, results) => ({
+	type: "web_search_tool_result",
+	tool_use_id: toolUseId,
+	content: results.length > 0 ? results.map((result) => ({
+		type: "web_search_result",
+		title: result.title,
+		url: result.url,
+		encrypted_content: "",
+		page_age: null
+	})) : {
+		type: "web_search_tool_result_error",
+		error_code: "unavailable"
+	}
+});
+const createClaudeWebSearchResponse = (search) => {
+	const toolUseId = `srvtoolu_${randomUUID().replaceAll("-", "")}`;
+	const content = [{
+		type: "server_tool_use",
+		id: toolUseId,
+		name: "web_search",
+		input: { query: search.query }
+	}, buildSearchResultBlock(toolUseId, search.results)];
+	if (search.text) content.push({
+		type: "text",
+		text: search.text
+	});
+	return {
+		id: search.id,
+		type: "message",
+		role: "assistant",
+		content,
+		model: search.model,
+		stop_reason: "end_turn",
+		stop_sequence: null,
+		usage: {
+			input_tokens: search.inputTokens,
+			output_tokens: search.outputTokens,
+			server_tool_use: { web_search_requests: 1 }
+		}
+	};
+};
+const getWebSearchResultText = (search) => {
+	if (search.results.length === 0) return search.text || "Web search did not return search results.";
+	return [
+		`Web search results for query: "${search.query}"`,
+		"",
+		...search.results.map((result, index) => `${index + 1}. ${result.title} - ${result.url}`)
+	].join("\n");
+};
+const createWebSearchResultContextMessage = (search) => ({
+	role: "system",
+	content: [
+		"Trusted bridge retrieval context: the assistant selected web_search, and copilot-relay executed it.",
+		"Use this context for the final answer. Do not describe it as user-provided or injected. Do not call web_search again.",
+		"If the user requested a specific output format, answer using only matching information from this context.",
+		"If the user asked for a URL only, output only that URL with no surrounding text.",
+		"",
+		`Query: ${search.query}`,
+		"",
+		getWebSearchResultText(search)
+	].join("\n")
+});
+const createFinalWebSearchPayload = (payload, search) => {
+	const messages = payload.messages.flatMap((message) => {
+		if (message.role === "tool") return [{
+			role: "developer",
+			content: ["Prior local tool result from the conversation:", String(message.content ?? "")].join("\n")
+		}];
+		if (message.tool_calls && message.tool_calls.length > 0) return message.content ? [{
+			...message,
+			tool_calls: void 0
+		}] : [];
+		return [message];
+	});
+	return {
+		...payload,
+		stream: false,
+		tools: void 0,
+		tool_choice: void 0,
+		messages: [...messages, createWebSearchResultContextMessage(search)]
+	};
+};
+const mergeWebSearchAndFinalResponse = (searchResponse, finalResponse) => ({
+	...finalResponse,
+	content: [...searchResponse.content.slice(0, 2), ...finalResponse.content],
+	usage: {
+		...finalResponse.usage,
+		input_tokens: searchResponse.usage.input_tokens + finalResponse.usage.input_tokens,
+		output_tokens: searchResponse.usage.output_tokens + finalResponse.usage.output_tokens,
+		server_tool_use: { web_search_requests: 1 }
+	}
+});
+
 //#endregion
 //#region src/lib/tokenizer.ts
 const encodingMap = {
@@ -1928,7 +2188,7 @@ const eventsFromClaudeResponse = (response) => {
 				thinking: block.thinking
 			}
 		});
-		else if (block.type === "tool_use") events$1.push({
+		else if (block.type === "tool_use" || block.type === "server_tool_use") events$1.push({
 			type: "content_block_delta",
 			index,
 			delta: {
@@ -1967,15 +2227,38 @@ claudeRoutes.post("/messages", async (c) => {
 	log.debug("Full Claude request payload", { payload: claudePayload });
 	try {
 		const upstreamModel = translateModelName(claudePayload.model);
-		const toolNameMapper = createClaudeToolNameMapper(claudePayload.tools, { ...getToolNameMapperOptionsForModel(upstreamModel) });
-		const response = await createChatCompletions(config, translateToOpenAI(claudePayload, void 0, toolNameMapper), {
+		const shouldLetModelDecideWebSearch = hasClaudeWebSearch(claudePayload);
+		const decisionPayload = shouldLetModelDecideWebSearch ? prepareClaudeWebSearchDecisionPayload(claudePayload) : claudePayload;
+		const toolNameMapper = createClaudeToolNameMapper(decisionPayload.tools, { ...getToolNameMapperOptionsForModel(upstreamModel) });
+		const openAIPayload = translateToOpenAI(decisionPayload, void 0, toolNameMapper);
+		if (shouldLetModelDecideWebSearch) openAIPayload.stream = false;
+		const response = await createChatCompletions(config, openAIPayload, {
 			client: "claude",
 			requestedModel: claudePayload.model,
 			requestedThinkEffort: getClaudeRequestedThinkEffort(claudePayload),
 			requestedThinking: getClaudeRequestedThinking(claudePayload)
 		});
 		if (isNonStreamingResponse(response)) {
-			const claudeResponse = translateToClaude(response, toolNameMapper);
+			const webSearchToolCall = shouldLetModelDecideWebSearch ? getClaudeWebSearchToolCallFromChatResponse(response, toolNameMapper) : void 0;
+			let claudeResponse;
+			if (webSearchToolCall) {
+				const search = await createClaudeWebSearchExecution(config, claudePayload, webSearchToolCall.query);
+				const searchResponse = createClaudeWebSearchResponse(search);
+				if (search.results.length === 0) claudeResponse = searchResponse;
+				else {
+					const finalResponse = await createChatCompletions(config, createFinalWebSearchPayload(openAIPayload, search), {
+						client: "claude",
+						requestedModel: claudePayload.model,
+						requestedThinkEffort: getClaudeRequestedThinkEffort(claudePayload),
+						requestedThinking: getClaudeRequestedThinking(claudePayload)
+					});
+					if (!isNonStreamingResponse(finalResponse)) throw new HTTPError("Claude web search final answer request unexpectedly streamed", new Response("Claude web search final answer request unexpectedly streamed", {
+						status: 502,
+						headers: { "content-type": "text/plain" }
+					}));
+					claudeResponse = mergeWebSearchAndFinalResponse(searchResponse, translateToClaude(finalResponse, toolNameMapper));
+				}
+			} else claudeResponse = translateToClaude(response, toolNameMapper);
 			if (!claudePayload.stream) return c.json(claudeResponse);
 			return streamSSE(c, async (stream) => {
 				for (const event of eventsFromClaudeResponse(claudeResponse)) await stream.writeSSE({
@@ -1984,6 +2267,10 @@ claudeRoutes.post("/messages", async (c) => {
 				});
 			});
 		}
+		if (shouldLetModelDecideWebSearch) throw new HTTPError("Claude web search model-decision request unexpectedly streamed", new Response("Claude web search model-decision request unexpectedly streamed", {
+			status: 502,
+			headers: { "content-type": "text/plain" }
+		}));
 		return streamSSE(c, async (stream) => {
 			const streamState = {
 				messageStartSent: false,
@@ -2060,6 +2347,25 @@ claudeRoutes.post("/messages/count_tokens", async (c) => {
 
 //#endregion
 //#region src/server.ts
+const loggedRequestHeaders = [
+	"anthropic-beta",
+	"anthropic-version",
+	"claude-beta",
+	"content-type"
+];
+const readRequestPayloadForLog = async (request) => {
+	const text = await request.clone().text().catch(() => "");
+	if (!text) return;
+	try {
+		return JSON.parse(text);
+	} catch {
+		return text;
+	}
+};
+const getLoggedHeaders = (request) => Object.fromEntries(loggedRequestHeaders.flatMap((name) => {
+	const value = request.headers.get(name);
+	return value ? [[name, value]] : [];
+}));
 const formatStatusLog = (method, path$1, status, ms, errorMessage) => {
 	const base = `${method} ${path$1} -> ${status} ${ms}ms`;
 	return status >= 400 && errorMessage ? `${base} error=${JSON.stringify(errorMessage)}` : base;
@@ -2087,6 +2393,17 @@ const createServer = (config) => {
 	}));
 	app.get("/healthz", (c) => c.json({ ok: true }));
 	app.route("/v1", claudeRoutes);
+	app.notFound(async (c) => {
+		const message = "Unsupported Claude API route";
+		c.set("requestErrorMessage", message);
+		log.error("Unsupported Claude API request", {
+			method: c.req.method,
+			path: c.req.path,
+			headers: getLoggedHeaders(c.req.raw),
+			payload: await readRequestPayloadForLog(c.req.raw)
+		});
+		return c.json({ error: { message } }, 500);
+	});
 	return app;
 };
 const startServer = (config) => serve({