Skip to content
Closed
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
5 changes: 3 additions & 2 deletions README.md
Original file line number Diff line number Diff line change
Expand Up @@ -70,8 +70,9 @@ Two ways to use it — pick one:
### Option 1 — Launcher (`bili pi` / `bili codex` / `bili claude` / `bili omp` / `bili opencode` / `bili hermes` / `bili dsh`)

The launcher wraps a client in one command: it starts a proxy on an
independent port (a fresh instance is always spawned — a port is never
reused), then points the client at it — **certificate-based MITM** where the
independent port (an already-healthy instance on the preferred port is
REUSED — #405; otherwise a fresh instance is spawned on a free port), then
points the client at it — **certificate-based MITM** where the
client honors proxy/CA env vars, or an isolated **`/bili/` config rewrite**
where it doesn't. No real config file is ever edited; the client's own
config is READ to discover which HTTPS upstream hosts it talks to, and those
Expand Down
10 changes: 5 additions & 5 deletions src/cli.ts
Original file line number Diff line number Diff line change
Expand Up @@ -332,11 +332,11 @@ export async function main(): Promise<void> {
return;
}
if (command === "plugin") {
// Installers read resolveProxyOrigin() (env first) at dispatch time.
// Apply --origin BEFORE handling the subcommand: the generic env
// merge further down runs only on the server path, which this
// branch returns ahead of — without this, a stale ~/.bili/
// proxy-origin discovery file would silently win over the flag.
// Installers bake bakedProxyOrigin() (explicit BILI_MCP_PROXY wins,
// else the stable default — #405) at dispatch time. Apply --origin
// BEFORE handling the subcommand: the generic env merge further down
// runs only on the server path, which this branch returns ahead of —
// without this, the flag would be ignored.
if (overrides.BILI_MCP_PROXY !== undefined) process.env.BILI_MCP_PROXY = overrides.BILI_MCP_PROXY;
if (pluginAction === "list") {
for (const row of pluginStatusAll()) {
Expand Down
16 changes: 15 additions & 1 deletion src/launcher.ts
Original file line number Diff line number Diff line change
Expand Up @@ -122,7 +122,8 @@ export interface LaunchOptions {
export interface ProxyHandle {
origin: string;
port: number;
child: SpawnChild;
/** Absent when an already-healthy instance was reused (#405) — stopProxy is a no-op then. */
child?: SpawnChild;
logPath?: string;
}

Expand Down Expand Up @@ -1500,6 +1501,19 @@ export async function ensureProxyRunning(
const now = deps.now ?? Date.now;
const sleepImpl = deps.sleep ?? ((ms: number) => new Promise<void>((r) => setTimeout(r, ms)));

// #405 fix #3: a healthy instance on the preferred port is REUSED. The old
// behavior always spawned a second instance on an ephemeral port, which
// hijacked the global proxy-origin pointer and forked session state across
// two processes (whoever saved last won).
const preferredOrigin = proxyOrigin(opts.host, opts.port);
if (await probeHealth(preferredOrigin, fetchImpl)) {
console.error(`bili: reusing healthy proxy at ${preferredOrigin} (no second instance spawned)`);
if (opts.mitmDomains && opts.mitmDomains.length > 0) {
console.error(`bili: note: custom MITM domains (${opts.mitmDomains.join(",")}) only apply to instances started with them — the reused instance keeps its own whitelist`);
}
return { origin: preferredOrigin, port: opts.port };
}

const port = await findFreePort(opts.port, opts.host);
const spawnedOrigin = proxyOrigin(opts.host, port);

Expand Down
88 changes: 74 additions & 14 deletions src/mcp.ts
Original file line number Diff line number Diff line change
Expand Up @@ -9,7 +9,7 @@
import fs from "node:fs";
import path from "node:path";
import { fileURLToPath } from "node:url";
import { proxyOriginFile } from "./paths.js";
import { probeOrigin, readPointerOrigin } from "./proxy-origin.js";

const VERSION = (() => {
try {
Expand All @@ -32,17 +32,60 @@ type McpToolDef = {
// every model request (x-claude-code-session-id), so binding is by identity.
// BILI_CONVERSATION_ID (launcher-spawned hosts like codex) has no matching
// request id — binding is headless (next NEW session).
const DEFAULT_PROXY_ORIGIN = "http://127.0.0.1:8787";
/** Stable discovery default baked into host configs by `bili plugin install`
* (#405): never an ephemeral launcher port, or one install would point the
* host at a dead port forever. */
export const DEFAULT_PROXY_ORIGIN = "http://127.0.0.1:8787";

export function resolveProxyOrigin(): string {
const fromEnv = process.env.BILI_MCP_PROXY?.trim();
if (fromEnv && fromEnv.length > 0) return fromEnv;
return readPointerOrigin() ?? DEFAULT_PROXY_ORIGIN;
}

const LIVE_PROBE_TIMEOUT_MS = 1500;
let liveOrigin: { origin: string; instanceId?: string } | null = null;

function noteRebind(msg: string): void {
try {
const discovered = fs.readFileSync(proxyOriginFile(), "utf8").trim();
if (/^https?:\/\/\S+$/.test(discovered)) return discovered;
} catch {
process.stderr.write(`[bili-mcp] ${msg}\n`);
} catch {}
}

/** Liveness-checked origin resolution (#405 fix #1): env → pointer file →
* default, probing /__bili/health on each and returning the first LIVE one.
* A killed ephemeral proxy therefore self-heals on the NEXT tool call — no
* host-client restart. The result is cached; any network failure invalidates
* it so the next call re-resolves against the current pointer file. */
export async function resolveLiveOrigin(): Promise<string> {
if (liveOrigin) return liveOrigin.origin;
const candidates: string[] = [];
const push = (o: string | null | undefined): void => {
if (o && o.length > 0 && !candidates.includes(o)) candidates.push(o);
};
push(process.env.BILI_MCP_PROXY?.trim());
push(readPointerOrigin());
push(DEFAULT_PROXY_ORIGIN);
for (const origin of candidates) {
const probe = await probeOrigin(origin, LIVE_PROBE_TIMEOUT_MS);
if (probe.live) {
if (candidates.length > 1 && origin !== candidates[0]) {
noteRebind(`proxy origin rebound ${candidates[0]} -> ${origin}${probe.instanceId ? ` (instance ${probe.instanceId.slice(0, 8)})` : ""}`);
}
liveOrigin = { origin, instanceId: probe.instanceId };
return origin;
}
}
return DEFAULT_PROXY_ORIGIN;
return candidates[0];
}

export function forgetLiveOrigin(): void {
liveOrigin = null;
}

/** Test hook: drop the cached live origin between cases. */
export function _resetMcpLiveOriginForTest(): void {
liveOrigin = null;
}

const TOOL_TIMEOUT_MS = 60_000;
Expand All @@ -67,7 +110,14 @@ function sendError(id: JsonRpcId, code: number, message: string): void {
}

async function fetchManifest(): Promise<void> {
const res = await fetch(`${resolveProxyOrigin()}/__bili/plugin/manifest`, { signal: AbortSignal.timeout(5000) });
const origin = await resolveLiveOrigin();
let res: Response;
try {
res = await fetch(`${origin}/__bili/plugin/manifest`, { signal: AbortSignal.timeout(5000) });
} catch (err) {
forgetLiveOrigin();
throw err;
}
if (!res.ok) throw new Error(`manifest fetch failed: ${res.status}`);
const data = (await res.json()) as { tools?: Record<string, { name: string; description?: string; input_schema?: unknown }[]> };
// Anthropic wire shape is the canonical MCP-compatible schema source.
Expand All @@ -86,15 +136,17 @@ function ensureManifest(): Promise<void> {
}

export async function forwardTool(tool: string, args: unknown, timeoutMs: number = TOOL_TIMEOUT_MS): Promise<string> {
const origin = await resolveLiveOrigin();
let res: Response;
try {
res = await fetch(`${resolveProxyOrigin()}/__bili/plugin/tool`, {
res = await fetch(`${origin}/__bili/plugin/tool`, {
method: "POST",
headers: { "content-type": "application/json" },
body: JSON.stringify({ conversationId, tool, args }),
signal: AbortSignal.timeout(timeoutMs),
});
} catch (err) {
forgetLiveOrigin();
if (err instanceof Error && err.name === "TimeoutError") throw new Error(`tool forward timed out after ${timeoutMs}ms: ${tool}`);
throw err;
}
Expand Down Expand Up @@ -128,12 +180,20 @@ async function handleMessage(msg: {
if (fromMeta) conversationId ??= fromMeta;
initialized = true;
if (conversationId && !registered) {
const registerFetch = fetch(`${resolveProxyOrigin()}/__bili/plugin/register`, {
method: "POST",
headers: { "content-type": "application/json" },
body: JSON.stringify({ conversationId, agent: "mcp", identity: IDENTITY_BINDING }),
signal: AbortSignal.timeout(5000),
});
const registerFetch = (async () => {
const origin = await resolveLiveOrigin();
try {
return await fetch(`${origin}/__bili/plugin/register`, {
method: "POST",
headers: { "content-type": "application/json" },
body: JSON.stringify({ conversationId, agent: "mcp", identity: IDENTITY_BINDING }),
signal: AbortSignal.timeout(5000),
});
} catch (err) {
forgetLiveOrigin();
throw err;
}
})();
registered = true; // issue-once: a repeated initialize must not re-register
if (IDENTITY_BINDING) {
// Identity-mode binding survives any arrival order —
Expand Down
58 changes: 52 additions & 6 deletions src/persist.ts
Original file line number Diff line number Diff line change
Expand Up @@ -48,8 +48,11 @@ import type { Session, BlockContent } from "./session.js";
* - No fsync of temp file or directory entry — a power loss can lose the
* most recent debounce window. Process crashes (SIGKILL) are safe up to
* the last successful write.
* - No cross-process lock — two proxy processes sharing BILI_SESSIONS_DIR
* will clobber each other's writes. Single-instance only.
* - No cross-process LOCK — two proxy processes sharing BILI_SESSIONS_DIR
* can still interleave writes. What IS protected (#405): a snapshot OLDER
* than the on-disk one (monotonic stats.requests / state.nextBlockId) is
* rejected instead of rolling counters back. Single-instance remains the
* supported deployment.
* - All writes within a process are serialized per-session by the kernel
* store's write chains; there is no per-session *request* serialization
* (two concurrent HTTP requests for the same session can interleave
Expand Down Expand Up @@ -162,21 +165,26 @@ function relPathFor(id: string, protocol?: string, upstreamOrigin?: string): str
/** Session persistence policy over the kernel StateStore mechanism. The
* public API predates the extraction and is kept stable for session.ts /
* server.ts / export.ts. */
const STALE_WARN_THROTTLE_MS = 60_000;

export class SessionStore {
readonly enabled: boolean;
private readonly dir: string;
private readonly store: StateStore<PersistedSession>;
private readonly log: Logger;
private readonly staleWarnAt = new Map<string, number>();

constructor(opts?: { dir?: string; debounceMs?: number; enabled?: boolean; log?: Logger }) {
const debounceMs = opts?.debounceMs ?? defaultDebounce();
this.enabled = (opts?.enabled ?? true) && debounceMs >= 0;
this.dir = opts?.dir ?? defaultDir();
this.log = opts?.log ?? defaultLogger;
this.store = new StateStore<PersistedSession>({
dir: this.dir,
version: PERSIST_VERSION,
debounceMs: Math.max(0, debounceMs),
enabled: this.enabled,
log: opts?.log ?? defaultLogger,
log: this.log,
relPath: (id, payload) =>
relPathFor(id, payload.meta?.protocol ?? payload.protocol, payload.meta?.upstreamOrigin ?? payload.upstreamOrigin),
// Adopt the pre-envelope flat format this store itself wrote
Expand Down Expand Up @@ -289,14 +297,14 @@ export class SessionStore {
* session state is persisted. Safe to call on the hot path. No-op if
* disabled. */
scheduleSave(session: Session): void {
this.store.scheduleSave(session.id, () => buildRecord(session));
this.store.scheduleSave(session.id, this.guardedBuild(session));
}

/** Asynchronously persist a session right now (skips the debounce). Throws
* on write failure so callers can react (e.g. avoid evicting). Serialized
* per-session by the kernel store's write chains. */
async writeNow(session: Session): Promise<void> {
await this.store.writeNow(session.id, () => buildRecord(session));
await this.store.writeNow(session.id, this.guardedBuild(session));
}

/** Synchronous flush for a single session. Used on memory eviction so a
Expand All @@ -305,7 +313,45 @@ export class SessionStore {
* Returns true on success, false on failure (caller must NOT evict on
* failure for a never-persisted session or it is lost permanently). */
flushSync(session: Session): boolean {
return this.store.flushSync(session.id, () => buildRecord(session));
return this.store.flushSync(session.id, this.guardedBuild(session));
}

/** #405 fix #4: dual-instance rollback guard. When two proxy processes
* share BILI_SESSIONS_DIR, whoever saves last used to win — an instance
* holding a STALE in-memory copy would roll counters back (requests:3 →
* 2). Both signals below are monotonic per session id, so either being
* strictly smaller proves staleness. Returns the fresher-on-disk payload
* when the incoming record is stale, else null. */
private staleDiskPayload(incoming: PersistedSession): PersistedSession | null {
const envelope = this.store.loadSync(incoming.id, relPathFor(incoming.id, incoming.meta?.protocol, incoming.meta?.upstreamOrigin));
if (!envelope) return null;
const disk = envelope.payload;
const diskRequests = disk.stats?.requests ?? disk.requests ?? 0;
const incRequests = incoming.stats?.requests ?? incoming.requests ?? 0;
if (incRequests < diskRequests) return disk;
if (incRequests === diskRequests) {
const diskBlocks = disk.state?.nextBlockId ?? 0;
const incBlocks = incoming.state?.nextBlockId ?? 0;
if (incBlocks < diskBlocks) return disk;
}
return null;
}

private guardedBuild(session: Session): () => PersistedSession {
return () => {
const record = buildRecord(session);
const disk = this.staleDiskPayload(record);
if (disk === null) return record;
const now = Date.now();
const last = this.staleWarnAt.get(record.id) ?? 0;
if (now - last >= STALE_WARN_THROTTLE_MS) {
this.staleWarnAt.set(record.id, now);
this.log("warn", `[persist] rejected stale snapshot for session ${record.id}: in-memory copy is older than the on-disk one (another bili instance holds newer state) — keeping disk state, no rollback (#405)`);
}
// Rewrite the disk's own payload: content-identical no-op that
// preserves the newer state while satisfying the write chain.
return disk;
};
}

/** Flush all dirty sessions with a pending debounce timer. Called on
Expand Down
20 changes: 15 additions & 5 deletions src/plugin-install.ts
Original file line number Diff line number Diff line change
Expand Up @@ -17,7 +17,7 @@ import os from "node:os";
import { execFileSync } from "node:child_process";
import { fileURLToPath } from "node:url";
import { resolvePiHome } from "./client-config.js";
import { resolveProxyOrigin } from "./mcp.js";
import { DEFAULT_PROXY_ORIGIN } from "./mcp.js";

export const PLUGIN_AGENTS = ["pi", "omp", "claude", "codex", "opencode"] as const;
export type PluginAgent = (typeof PLUGIN_AGENTS)[number];
Expand All @@ -28,6 +28,16 @@ export function selfPackageRoot(): string {
return path.resolve(path.dirname(here), "..");
}

/** #405 fix #4: the origin baked into host configs must be STABLE — never the
* ephemeral port a launcher just spawned (one install, permanent mismatch).
* Explicit user intent still wins (BILI_MCP_PROXY env / `bili plugin --origin`);
* runtime discovery of custom-port instances happens inside the MCP shell via
* the pointer file, not at install time. */
export function bakedProxyOrigin(): string {
const explicit = process.env.BILI_MCP_PROXY?.trim();
return explicit && explicit.length > 0 ? explicit : DEFAULT_PROXY_ORIGIN;
}

function homeFile(rel: string, envOverride?: string): string {
const raw = (envOverride !== undefined ? process.env[envOverride] : undefined)?.trim();
const base = raw && raw.length > 0 ? raw : os.homedir();
Expand Down Expand Up @@ -250,7 +260,7 @@ function claudeInstall(): string {
requireDistFile(mcpJs);
const claude = process.env.CLAUDE?.trim() || "claude";
try {
execFileSync(claude, ["mcp", "add", "bili", "--scope", "user", "-e", `BILI_MCP_PROXY=${resolveProxyOrigin()}`, "--", process.execPath, mcpJs], { stdio: ["ignore", "pipe", "pipe"], timeout: CLAUDE_EXEC_TIMEOUT_MS });
execFileSync(claude, ["mcp", "add", "bili", "--scope", "user", "-e", `BILI_MCP_PROXY=${bakedProxyOrigin()}`, "--", process.execPath, mcpJs], { stdio: ["ignore", "pipe", "pipe"], timeout: CLAUDE_EXEC_TIMEOUT_MS });
return `claude: installed via \`claude mcp add\` (user scope) -> ${claudeMcpJson()}`;
} catch (err) {
const stderr = err instanceof Error && "stderr" in err ? String((err as { stderr?: Buffer | string }).stderr ?? "") : "";
Expand Down Expand Up @@ -283,7 +293,7 @@ function codexToml(): string {
}

function codexBlock(): string {
return `\n[mcp_servers.bili]\ncommand = ${JSON.stringify(process.execPath)}\nargs = [${JSON.stringify(path.join(selfPackageRoot(), "dist", "mcp.js"))}]\nenv = { BILI_MCP_PROXY = ${JSON.stringify(resolveProxyOrigin())} }\n`;
return `\n[mcp_servers.bili]\ncommand = ${JSON.stringify(process.execPath)}\nargs = [${JSON.stringify(path.join(selfPackageRoot(), "dist", "mcp.js"))}]\nenv = { BILI_MCP_PROXY = ${JSON.stringify(bakedProxyOrigin())} }\n`;
}

function codexInstall(): string {
Expand All @@ -292,7 +302,7 @@ function codexInstall(): string {
const existing = /^[ \t]*\[mcp_servers\.bili\][ \t]*$/m.exec(text);
if (existing !== null) {
const block = text.slice(existing.index, text.indexOf("\n[", existing.index + 1) === -1 ? undefined : text.indexOf("\n[", existing.index + 1));
if (block.includes(`BILI_MCP_PROXY = ${JSON.stringify(resolveProxyOrigin())}`)) return `codex: already installed (${file})`;
if (block.includes(`BILI_MCP_PROXY = ${JSON.stringify(bakedProxyOrigin())}`)) return `codex: already installed (${file})`;
const refreshed = text.slice(0, existing.index) + codexBlock().replace(/^\n/, "") + text.slice(existing.index + block.length);
backupOnce(file);
fs.writeFileSync(file, refreshed);
Expand Down Expand Up @@ -346,7 +356,7 @@ function opencodeInstall(): string {
const data = readJson(file);
const mcp = (data.mcp as Record<string, unknown> | undefined) ?? {};
if ("bili" in mcp) return `opencode: already installed (${file})`;
mcp.bili = { type: "local", command: [process.execPath, mcpJs], environment: { BILI_MCP_PROXY: resolveProxyOrigin() }, enabled: true };
mcp.bili = { type: "local", command: [process.execPath, mcpJs], environment: { BILI_MCP_PROXY: bakedProxyOrigin() }, enabled: true };
data.mcp = mcp;
writeJson(file, data);
return `opencode: installed -> ${file} mcp.bili`;
Expand Down
Loading