@nvae/llmswitch 0.2.0 → 0.4.0

package/README.md

@@ -284,7 +284,7 @@ API Key 会以**明文**保存在本机 profile、目标工具认证文件或 br
 - Anthropic 转换主要覆盖文本、工具调用和工具结果，图片等非文本内容可能无法完整保留。
 - Codex 的 Completions 模式是降级路径：对话会被展平为 prompt，复杂工具调用或 agent 流程可能表现不佳。
 - Codex Chat 模式仅在上游返回 HTTP `404` 或 `405` 时回退到 Completions；认证、网络及其他错误不会触发回退。
-- 托管 `web_search` 会转换为普通客户端函数，不会自动获得上游的托管搜索能力。
+- 请求中的托管 `web_search` 会转换为普通 Chat function；若上游自行搜索并以完整 `<web_search>...</web_search>` 块返回结果，bridge 会将其恢复为 Responses `web_search_call`，并保留去标签后的结果正文。
 - 自动发现模型需要 API Key 和兼容的 `/models` 端点；失败时需手动输入模型。
 
 ## 参与贡献

package/dist/adapters/claude.js

@@ -35,14 +35,14 @@ function stripManagedEnv(env) {
     }
     return next;
 }
-export function buildClaudeSettings(existing, profile, effectiveBaseUrl) {
+export function buildClaudeSettings(existing, profile, effectiveBaseUrl, effectiveApiKey = profile.apiKey) {
     assertCompatible("claude", profile.apiFormat);
     const env = stripManagedEnv({ ...(existing.env || {}) });
     clearProxyEnvKeys(env);
     const needsBridge = profileNeedsBridge(profile);
     env.ANTHROPIC_BASE_URL = effectiveBaseUrl || profile.baseUrl;
-    if (profile.apiKey) {
-        env.ANTHROPIC_AUTH_TOKEN = profile.apiKey;
+    if (effectiveApiKey) {
+        env.ANTHROPIC_AUTH_TOKEN = effectiveApiKey;
     }
     env.ANTHROPIC_MODEL = profile.models.default;
     env.ANTHROPIC_DEFAULT_SONNET_MODEL = profile.models.default;
@@ -75,15 +75,18 @@ export async function applyClaudeProfile(profile) {
     const existing = readClaudeSettings(configPath);
     const backupPath = backupFile(configPath, getBackupsDir("claude"), "settings");
     let effectiveBaseUrl = profile.baseUrl;
+    let effectiveApiKey = profile.apiKey;
     let bridgeNote = "";
     if (profileNeedsBridge(profile)) {
-        effectiveBaseUrl = await ensureBridgeForProfile(profile, "claude");
+        const connection = await ensureBridgeForProfile(profile, "claude");
+        effectiveBaseUrl = connection.baseUrl;
+        effectiveApiKey = connection.clientToken;
         bridgeNote = `已启动本地 Anthropic↔Chat 适配桥 → ${effectiveBaseUrl}（上游 ${profile.baseUrl}）。`;
     }
     else {
         await clearBridgeUpstream("claude");
     }
-    const next = buildClaudeSettings(existing, profile, effectiveBaseUrl);
+    const next = buildClaudeSettings(existing, profile, effectiveBaseUrl, effectiveApiKey);
     atomicWriteFile(configPath, JSON.stringify(next, null, 2) + "\n");
     setActiveProfile("claude", profile.name);
     return {

package/dist/adapters/codex.js

@@ -48,7 +48,7 @@ export function buildCodexConfig(existing, profile, effectiveBaseUrl) {
         model_providers: providers,
     };
 }
-export function buildCodexEnvFile(existingContent, profile) {
+export function buildCodexEnvFile(existingContent, profile, effectiveApiKey = profile.apiKey || "llm-switch-bridge") {
     const lines = existingContent ? existingContent.split(/\r?\n/) : [];
     const map = new Map();
     const order = [];
@@ -75,7 +75,7 @@ export function buildCodexEnvFile(existingContent, profile) {
     // When bridging, Codex talks to local bridge; key can be placeholder.
     // Bridge uses upstream.apiKey from its own config. Still write real key
     // so native responses profiles keep working.
-    map.set(keyName, profile.apiKey || "llm-switch-bridge");
+    map.set(keyName, effectiveApiKey);
     const proxyKeys = [
         "HTTP_PROXY",
         "HTTPS_PROXY",
@@ -124,11 +124,17 @@ export async function applyCodexProfile(profile) {
     assertCompatible("codex", profile.apiFormat);
     ensureDir(getCodexHome());
     let effectiveBaseUrl = normalizeBaseUrlForFormat(profile.apiFormat, profile.baseUrl);
+    let effectiveApiKey = profile.apiKey || "llm-switch-bridge";
     let bridgeNote = "";
     if (profileNeedsBridge(profile)) {
-        effectiveBaseUrl = (await ensureBridgeForProfile(profile, "codex")).replace(/\/+$/, "");
+        const connection = await ensureBridgeForProfile(profile, "codex");
+        effectiveBaseUrl = connection.baseUrl.replace(/\/+$/, "");
+        effectiveApiKey = connection.clientToken;
         bridgeNote = `已启动本地 Responses 适配桥 → ${effectiveBaseUrl}（上游 ${normalizeBaseUrlForFormat(profile.apiFormat, profile.baseUrl)}，模式 ${profile.bridgeMode || "chat"}）。`;
     }
+    else {
+        await clearBridgeUpstream("codex");
+    }
     const configPath = getCodexConfigPath();
     const envPath = getCodexEnvPath();
     const existing = readCodexConfig(configPath);
@@ -137,7 +143,7 @@ export async function applyCodexProfile(profile) {
     const next = buildCodexConfig(existing, profile, effectiveBaseUrl);
     atomicWriteFile(configPath, stringify(next) + "\n");
     const prevEnv = existsSync(envPath) ? readFileSync(envPath, "utf8") : "";
-    atomicWriteFile(envPath, buildCodexEnvFile(prevEnv, profile));
+    atomicWriteFile(envPath, buildCodexEnvFile(prevEnv, profile, effectiveApiKey));
     setActiveProfile("codex", profile.name);
     return {
         tool: "codex",

package/dist/bridge/manager.js

@@ -1,19 +1,37 @@
-import { execFileSync, spawn } from "node:child_process";
-import { existsSync, readFileSync } from "node:fs";
+import { spawn } from "node:child_process";
+import { randomUUID } from "node:crypto";
+import { existsSync } from "node:fs";
 import { fileURLToPath } from "node:url";
 import { normalizeBaseUrlForFormat } from "../utils/base-url.js";
-import { bridgeBaseUrl, bridgeRootUrl, getBridgePidPath, readBridgeState, readBridgeUpstreams, writeBridgeState, writeBridgeUpstream, } from "./state.js";
-import { DEFAULT_BRIDGE_HOST, DEFAULT_BRIDGE_PORT, emptyUpstreams, hasAnyUpstream, } from "./types.js";
+import { bridgeBaseUrl, bridgeRootUrl, generateBridgeToken, readBridgeState, updateBridgeState, writeBridgeUpstream, } from "./state.js";
+import { DEFAULT_BRIDGE_HOST, DEFAULT_BRIDGE_PORT, hasAnyUpstream, } from "./types.js";
+import { assertBridgeListenerAllowed, formatHostForUrl, parseBridgePort, resolveBridgeListener, } from "./runtime.js";
 import { listenBridge } from "./server.js";
+export class PortOccupiedError extends Error {
+    constructor(host, port) {
+        super(`端口 ${host}:${port} 已被其他进程占用；为避免误杀，llm-switch 不会自动终止该进程。`);
+        this.name = "PortOccupiedError";
+    }
+}
+export class LegacyBridgeRunningError extends Error {
+    constructor(host, port) {
+        super(`检测到旧版 bridge 正在 ${host}:${port} 运行。请先执行 llms bridge stop --legacy 并确认风险，然后重试。`);
+        this.name = "LegacyBridgeRunningError";
+    }
+}
+export class BridgeControlError extends Error {
+    constructor(message) {
+        super(message);
+        this.name = "BridgeControlError";
+    }
+}
 export function profileNeedsBridge(profile) {
     return profile.apiFormat === "openai-chat";
 }
 export function bridgeToolForCliTool(tool) {
-    if (tool === "codex" || tool === "claude")
-        return tool;
-    return null;
+    return tool === "codex" || tool === "claude" ? tool : null;
 }
-export function upstreamFromProfile(profile, tool) {
+export function upstreamFromProfile(profile, tool, clientToken = null) {
     const mode = tool === "claude" ? "chat" : profile.bridgeMode || "chat";
     return {
         baseUrl: normalizeBaseUrlForFormat(profile.apiFormat, profile.baseUrl),
@@ -23,42 +41,68 @@ export function upstreamFromProfile(profile, tool) {
         headers: profile.headers,
         profileName: profile.name,
         updatedAt: new Date().toISOString(),
+        clientToken,
+        migrationRequired: !clientToken,
     };
 }
-/**
- * Probe local bridge. Old builds may return 503 without `upstreams` — treat as
- * reachable but not healthy so callers can restart.
- */
-export async function probeBridge(host = readBridgeState().host, port = readBridgeState().port) {
+function controlUrl(host, port, path) {
+    return `http://${formatHostForUrl(host)}:${port}${path}`;
+}
+export async function probeBridge(host = readBridgeState().listener.advertiseHost, port = readBridgeState().listener.port) {
+    const state = readBridgeState();
+    const expected = state.instance;
     try {
-        const res = await fetch(`http://${host}:${port}/health`, {
+        const headers = {};
+        if (expected?.controlToken) {
+            headers["x-llm-switch-control"] = expected.controlToken;
+        }
+        const response = await fetch(controlUrl(host, port, "/health"), {
+            headers,
             signal: AbortSignal.timeout(800),
         });
         let body = null;
         try {
-            body = (await res.json());
+            body = (await response.json());
         }
         catch {
             body = null;
         }
-        const healthy = res.ok && body?.ok === true && body != null && "upstreams" in body;
-        return { reachable: true, healthy };
+        const instanceId = typeof body?.instanceId === "string" ? body.instanceId : undefined;
+        const authenticated = Boolean(response.ok &&
+            expected &&
+            instanceId &&
+            instanceId === expected.id);
+        const legacy = Boolean(response.ok &&
+            body?.ok === true &&
+            body != null &&
+            "upstreams" in body &&
+            !("service" in body));
+        return {
+            reachable: true,
+            healthy: authenticated,
+            authenticated,
+            legacy,
+            instanceId,
+        };
     }
     catch {
-        return { reachable: false, healthy: false };
+        return {
+            reachable: false,
+            healthy: false,
+            authenticated: false,
+            legacy: false,
+        };
     }
 }
-export async function isBridgeAlive(host = readBridgeState().host, port = readBridgeState().port) {
+export async function isBridgeAlive(host = readBridgeState().listener.advertiseHost, port = readBridgeState().listener.port) {
     return (await probeBridge(host, port)).healthy;
 }
 export function readPid() {
-    const path = getBridgePidPath();
-    if (!existsSync(path))
-        return null;
-    const n = Number(readFileSync(path, "utf8").trim());
-    return Number.isFinite(n) ? n : null;
+    return readBridgeState().instance?.pid ?? null;
 }
 export function isPidRunning(pid) {
+    if (!Number.isInteger(pid) || pid < 1 || pid > 2_147_483_647)
+        return false;
     try {
         process.kill(pid, 0);
         return true;
@@ -67,65 +111,86 @@ export function isPidRunning(pid) {
         return false;
     }
 }
-function urlForTool(tool, host, port, pid) {
-    const upstreams = readBridgeUpstreams();
-    const state = { host, port, upstreams, pid };
-    return tool === "claude" ? bridgeRootUrl(state) : bridgeBaseUrl(state);
+function connectionForTool(tool, state, clientToken) {
+    return {
+        baseUrl: tool === "claude" ? bridgeRootUrl(state) : bridgeBaseUrl(state),
+        clientToken,
+    };
+}
+function desiredListener() {
+    const current = readBridgeState();
+    const host = process.env.LLM_SWITCH_BRIDGE_HOST || current.listener.bindHost;
+    const port = process.env.LLM_SWITCH_BRIDGE_PORT
+        ? parseBridgePort(process.env.LLM_SWITCH_BRIDGE_PORT)
+        : current.listener.port;
+    const allowRemote = current.listener.allowRemote;
+    return resolveBridgeListener({ host, port, allowRemote });
 }
 /**
- * Configure per-tool upstream and ensure local bridge is listening.
- * Returns Codex base (`…/v1`) or Claude root (`…` without /v1).
+ * Preflight the listen address before writing an upstream, then configure the
+ * side and ensure an authenticated v2 daemon is running.
  */
 export async function ensureBridgeForProfile(profile, tool) {
-    const upstream = upstreamFromProfile(profile, tool);
-    writeBridgeUpstream(tool, upstream);
-    const state = readBridgeState();
-    const host = state.host || DEFAULT_BRIDGE_HOST;
-    const port = Number(process.env.LLM_SWITCH_BRIDGE_PORT) ||
-        state.port ||
-        DEFAULT_BRIDGE_PORT;
-    const upstreams = readBridgeUpstreams();
-    writeBridgeState({
-        ...state,
-        host,
-        port,
-        upstreams,
-        pid: state.pid,
-    });
-    const probe = await probeBridge(host, port);
-    if (probe.healthy) {
-        return urlForTool(tool, host, port, state.pid);
-    }
-    // Stale / incompatible process holding the port (e.g. pre-dual-upstream build).
-    if (probe.reachable) {
-        await forceStopBridge(host, port);
+    const listener = desiredListener();
+    const before = await probeBridge(listener.advertiseHost, listener.port);
+    if (before.reachable && !before.healthy) {
+        if (before.legacy) {
+            throw new LegacyBridgeRunningError(listener.bindHost, listener.port);
+        }
+        throw new PortOccupiedError(listener.bindHost, listener.port);
     }
-    await startBridgeDaemon(host, port);
-    for (let i = 0; i < 50; i++) {
-        if (await isBridgeAlive(host, port)) {
-            return urlForTool(tool, host, port, readPid());
+    const clientToken = generateBridgeToken();
+    const upstream = upstreamFromProfile(profile, tool, clientToken);
+    const configured = updateBridgeState((state) => ({
+        ...state,
+        listener,
+        host: listener.advertiseHost,
+        port: listener.port,
+        upstreams: { ...state.upstreams, [tool]: upstream },
+    }));
+    if (!before.healthy) {
+        await startBridgeDaemon(listener.bindHost, listener.port, listener.allowRemote);
+        for (let attempt = 0; attempt < 50; attempt += 1) {
+            if (await isBridgeAlive(listener.advertiseHost, listener.port))
+                break;
+            await new Promise((resolve) => setTimeout(resolve, 100));
+        }
+        if (!(await isBridgeAlive(listener.advertiseHost, listener.port))) {
+            throw new BridgeControlError(`Bridge 启动超时（${listener.bindHost}:${listener.port}）。可手动运行：llms bridge serve`);
         }
-        await new Promise((r) => setTimeout(r, 100));
     }
-    throw new Error(`Bridge 启动超时（${host}:${port}）。可手动运行：llms bridge serve`);
+    return connectionForTool(tool, readBridgeState() || configured, clientToken);
 }
 export async function clearBridgeUpstream(tool) {
     writeBridgeUpstream(tool, null);
-    const upstreams = readBridgeUpstreams();
-    if (!hasAnyUpstream(upstreams)) {
+    const state = readBridgeState();
+    if (!hasAnyUpstream(state.upstreams) && state.instance) {
         await stopBridge();
     }
 }
-export async function startBridgeDaemon(host = DEFAULT_BRIDGE_HOST, port = DEFAULT_BRIDGE_PORT) {
-    if (await isBridgeAlive(host, port)) {
+export async function startBridgeDaemon(host = DEFAULT_BRIDGE_HOST, port = DEFAULT_BRIDGE_PORT, allowRemote = false) {
+    const listener = resolveBridgeListener({ host, port, allowRemote });
+    const probe = await probeBridge(listener.advertiseHost, listener.port);
+    if (probe.healthy)
         return readPid() || 0;
-    }
-    const probe = await probeBridge(host, port);
     if (probe.reachable) {
-        await forceStopBridge(host, port);
+        if (probe.legacy)
+            throw new LegacyBridgeRunningError(host, port);
+        throw new PortOccupiedError(host, port);
     }
+    updateBridgeState((state) => ({
+        ...state,
+        listener,
+        host: listener.advertiseHost,
+        port: listener.port,
+        instance: null,
+        pid: null,
+    }));
     const entry = resolveCliEntry();
-    const child = spawn(process.execPath, [entry, "bridge", "serve", "--host", host, "--port", String(port)], {
+    const args = [entry, "bridge", "serve", "--host", host, "--port", String(port)];
+    if (allowRemote)
+        args.push("--allow-remote");
+    const child = spawn(process.execPath, args, {
         detached: true,
         stdio: "ignore",
         env: {
@@ -135,106 +200,136 @@ export async function startBridgeDaemon(host = DEFAULT_BRIDGE_HOST, port = DEFAU
         },
     });
     child.unref();
-    const pid = child.pid;
-    if (!pid)
-        throw new Error("无法启动 bridge 进程");
-    const state = readBridgeState();
-    writeBridgeState({
-        ...state,
-        host,
-        port,
-        pid,
-        upstreams: state.upstreams,
-    });
-    return pid;
-}
-/** Stop by recorded pid, then free the listen port if still held. */
-export async function forceStopBridge(host = readBridgeState().host, port = readBridgeState().port) {
-    await stopBridge();
-    await killListenersOnPort(port);
-    // Brief wait so TIME_WAIT / bind release settles.
-    for (let i = 0; i < 20; i++) {
-        const probe = await probeBridge(host, port);
-        if (!probe.reachable)
-            return;
-        await new Promise((r) => setTimeout(r, 50));
-    }
+    if (!child.pid)
+        throw new BridgeControlError("无法启动 bridge 进程");
+    return child.pid;
 }
 export async function stopBridge() {
     const state = readBridgeState();
-    const pid = state.pid || readPid();
-    let stopped = false;
-    if (pid && isPidRunning(pid)) {
-        try {
-            process.kill(pid, "SIGTERM");
-            stopped = true;
-        }
-        catch {
-            // ignore
-        }
+    const instance = state.instance;
+    if (!instance)
+        return false;
+    const probe = await probeBridge(state.listener.advertiseHost, state.listener.port);
+    if (!probe.authenticated || probe.instanceId !== instance.id) {
+        throw new BridgeControlError("无法验证 bridge 实例身份；为避免误杀，未发送任何进程信号。");
     }
-    writeBridgeState({
-        ...state,
-        pid: null,
-        upstreams: state.upstreams,
-    });
-    return stopped;
-}
-function killListenersOnPort(port) {
-    if (process.platform === "win32")
-        return;
+    let response;
     try {
-        const out = execFileSync("lsof", ["-ti", `tcp:${port}`, `-sTCP:LISTEN`], { encoding: "utf8" });
-        for (const line of out.split(/\n/)) {
-            const pid = Number(line.trim());
-            if (!pid || pid === process.pid)
-                continue;
-            try {
-                process.kill(pid, "SIGTERM");
-            }
-            catch {
-                // ignore
-            }
-        }
+        response = await fetch(controlUrl(state.listener.advertiseHost, state.listener.port, "/_control/shutdown"), {
+            method: "POST",
+            headers: {
+                "content-type": "application/json",
+                "x-llm-switch-control": instance.controlToken,
+            },
+            body: JSON.stringify({ instanceId: instance.id }),
+            signal: AbortSignal.timeout(2_000),
+        });
     }
-    catch {
-        // lsof miss / no listeners — ignore
+    catch (error) {
+        throw new BridgeControlError(`Bridge 协作关闭失败：${error instanceof Error ? error.message : String(error)}`);
+    }
+    if (!response.ok) {
+        throw new BridgeControlError(`Bridge 拒绝关闭请求（HTTP ${response.status}）`);
+    }
+    for (let attempt = 0; attempt < 100; attempt += 1) {
+        if (readBridgeState().instance?.id !== instance.id)
+            return true;
+        await new Promise((resolve) => setTimeout(resolve, 20));
     }
+    throw new BridgeControlError("Bridge 已接受关闭请求，但未在宽限期内清除实例身份");
 }
-export async function runBridgeForeground(host, port) {
-    const state = readBridgeState();
-    writeBridgeState({
+/** Compatibility alias: v2 never force-kills a listener. */
+export async function forceStopBridge() {
+    await stopBridge();
+}
+export async function runBridgeForeground(host, port, allowRemote = false) {
+    assertBridgeListenerAllowed(host, allowRemote);
+    const listener = resolveBridgeListener({ host, port, allowRemote });
+    const previous = readBridgeState();
+    const instance = {
+        id: randomUUID(),
+        controlToken: generateBridgeToken(),
+        pid: process.pid,
+        startedAt: new Date().toISOString(),
+    };
+    updateBridgeState((state) => ({
         ...state,
-        host,
-        port,
+        listener,
+        host: listener.advertiseHost,
+        port: listener.port,
         pid: process.pid,
-        upstreams: state.upstreams.codex || state.upstreams.claude
-            ? state.upstreams
-            : readBridgeUpstreams() || emptyUpstreams(),
+        instance,
+    }));
+    let resolveClosed;
+    const closed = new Promise((resolve) => {
+        resolveClosed = resolve;
     });
-    const server = await listenBridge(port, host);
-    const shutdown = () => {
-        server.close(() => process.exit(0));
+    let server = null;
+    let closing = false;
+    const clearIdentity = () => {
+        updateBridgeState((state) => state.instance?.id === instance.id
+            ? { ...state, instance: null, pid: null }
+            : state);
     };
-    process.on("SIGINT", shutdown);
-    process.on("SIGTERM", shutdown);
-    console.error(`llm-switch bridge listening on http://${host}:${port} (POST /v1/responses · POST /v1/messages → upstream chat/completions)`);
-    await new Promise(() => undefined);
+    const shutdown = async (requestedId = instance.id) => {
+        if (requestedId !== instance.id || closing)
+            return;
+        closing = true;
+        if (server) {
+            const forceTimer = setTimeout(() => server?.closeAllConnections(), 30_000);
+            await new Promise((resolve) => server.close(() => resolve()));
+            clearTimeout(forceTimer);
+        }
+        clearIdentity();
+        resolveClosed?.();
+    };
+    try {
+        server = await listenBridge(listener.port, listener.bindHost, {
+            controlToken: instance.controlToken,
+            instanceId: instance.id,
+            onShutdown: shutdown,
+        });
+    }
+    catch (error) {
+        try {
+            clearIdentity();
+        }
+        catch {
+            // Preserve the original bind error.
+        }
+        if (error.code === "EADDRINUSE") {
+            throw new PortOccupiedError(listener.bindHost, listener.port);
+        }
+        // Restore the previous listener only when no newer instance replaced us.
+        updateBridgeState((state) => state.instance
+            ? state
+            : {
+                ...state,
+                listener: previous.listener,
+                host: previous.listener.advertiseHost,
+                port: previous.listener.port,
+            });
+        throw error;
+    }
+    const onSignal = () => {
+        void shutdown();
+    };
+    process.once("SIGINT", onSignal);
+    process.once("SIGTERM", onSignal);
+    console.error(`llm-switch bridge listening on http://${formatHostForUrl(listener.bindHost)}:${listener.port} (authenticated)`);
+    await closed;
+    process.removeListener("SIGINT", onSignal);
+    process.removeListener("SIGTERM", onSignal);
 }
-/**
- * Prefer the entry currently running this CLI so `bun run ./src/index.ts`
- * respawns the same source tree; published installs use dist/index.js.
- */
 function resolveCliEntry() {
     const running = process.argv[1];
-    if (running && existsSync(running)) {
+    if (running && existsSync(running))
         return running;
-    }
     const compiled = fileURLToPath(new URL("../index.js", import.meta.url));
     if (existsSync(compiled))
         return compiled;
     const source = fileURLToPath(new URL("../index.ts", import.meta.url));
     if (existsSync(source))
         return source;
-    throw new Error("无法定位 llmswitch 入口文件");
+    throw new BridgeControlError("无法定位 llmswitch 入口文件");
 }