@vanillagreen/pi-claude-bridge 1.9.0 → 3.2.2

package/src/connector-inventory.ts

@@ -33,6 +33,7 @@
 
 const CONNECTOR_NS_PREFIX = "mcp__claude_ai_";
 const DEFAULT_API_BASE = "https://api.anthropic.com";
+const DEFAULT_PROXY_BASE = "https://mcp-proxy.anthropic.com/v1/mcp";
 // OAuth-token requests to the Anthropic API require this beta header; without it
 // endpoints reject the bearer credential.
 const OAUTH_BETA_HEADER = "oauth-2025-04-20";
@@ -43,6 +44,13 @@ export type ConnectorEntry = {
 	installedServerId?: string;
 	/** Catalog identity, shared across accounts that install the same connector. */
 	directoryUuid?: string;
+	/**
+	 * Account-side install state. `"connected"` marks the connectors the CLI
+	 * actually attempts; everything else it never gives a `Starting connection`
+	 * line at all. Verified live 2026-07-26: 7 `connected` / 20 `unknown` on the
+	 * app account, and the CLI connected exactly those 7.
+	 */
+	installState?: string;
 	description?: string;
 	isAuthless?: boolean;
 };
@@ -77,6 +85,49 @@ export type ClaudeOAuthCredentials = {
 
 type Json = Record<string, any>;
 
+/**
+ * The server name Claude Code itself registers a claude.ai connector under.
+ *
+ * This is the `mcpServers` KEY to use when declaring a connector explicitly, and
+ * it is load-bearing rather than cosmetic: the key IS the tool namespace. Keyed
+ * as anything else, the same connector appears twice — once from our
+ * declaration and once from the CLI's own loader — and consumers that pin
+ * fully-qualified tool names (memsira's executor hard-codes them into
+ * `--allowedTools` and its system prompt, and never globs a namespace) would
+ * be allowed to call neither copy reliably. Verified live: keyed as the CLI's
+ * name there is ONE server entry and one namespace (27 servers); keyed otherwise
+ * both appear (28 servers).
+ *
+ * What merges is the NAMESPACE, not the connection. Under the shared name the
+ * declaration and the CLI's own loader each still connect: across 40 cold runs
+ * the baseline logged 1 Slack connect (7 proxy connects total) and the declared
+ * arm logged 2 Slack connects (8 total), in 20 of 20 runs with no exceptions.
+ * Declaring N connectors therefore costs ~2N connections, not N. They run in
+ * parallel — slowest-connect per run moved from a 1192ms median to 1278ms, worst
+ * 1544ms, well inside the 5s cap — but that was measured with ONE declaration.
+ */
+export function connectorServerName(connectorName: string): string {
+	return `claude.ai ${connectorName.trim()}`;
+}
+
+/**
+ * The claude.ai MCP proxy endpoint for one installed connector.
+ *
+ * The `url` field is REQUIRED by the runtime schema, but the CLI does not
+ * connect to it: for `type: "claudeai-proxy"` it derives the endpoint from `id`.
+ * Caught live — pointing `url` at a local server that never responds still
+ * logged `Using claude.ai proxy at …/mcpsrv_01Wcus…` and connected. So this
+ * builds the honest value for a required field; it is `id` that must be right.
+ *
+ * That also explains why both id forms work: the `mcpsrv_…` id from
+ * `GET /v1/mcp_servers` and the `installedServerId` UUID this module returns
+ * each connected and served identical tools with the CLI's own connector
+ * loading disabled. Both resolve at the proxy; neither depends on `url`.
+ */
+export function connectorProxyUrl(installedServerId: string, proxyBase: string = DEFAULT_PROXY_BASE): string {
+	return `${trimTrailingSlashes(proxyBase)}/${encodeURIComponent(installedServerId)}`;
+}
+
 /**
  * Tool-namespace prefix for a connector, e.g. `Google Calendar` →
  * `mcp__claude_ai_Google_Calendar__`. Connector servers are named after the
@@ -89,16 +140,23 @@ export function connectorServerNamespace(connectorName: string): string {
 }
 
 // Candidate credential files, in precedence order. CLAUDE_CONFIG_DIR is set
-// per-account by hosts that run one sidecar per Claude account, so it must win
-// over the home-directory default or a multi-account host reads the wrong
-// account's connectors. Both file names are probed under each root because the
-// token and the org UUID do not reliably live in the same file across versions.
+// per-account by hosts that run one sidecar per Claude account, so when it is
+// set that root is probed EXCLUSIVELY: falling through to `~/.claude`/$HOME
+// would silently borrow the DEFAULT account's token for a managed profile
+// whose own `.credentials.json` is missing — a confident, well-formed answer
+// for the wrong account (see the token-scoping note above). Only the
+// no-config-dir default probes the home locations. Both file names are probed
+// under each root because the token and the org UUID do not reliably live in
+// the same file across versions.
 export function credentialCandidatePaths(env: NodeJS.ProcessEnv = process.env): string[] {
 	const roots: string[] = [];
 	const configDir = env.CLAUDE_CONFIG_DIR?.trim();
-	if (configDir) roots.push(configDir);
-	const home = env.HOME?.trim();
-	if (home) roots.push(`${home}/.claude`, home);
+	if (configDir) {
+		roots.push(configDir);
+	} else {
+		const home = env.HOME?.trim();
+		if (home) roots.push(`${home}/.claude`, home);
+	}
 	const seen = new Set<string>();
 	const paths: string[] = [];
 	for (const root of roots) {
@@ -246,6 +304,7 @@ export async function listAccountConnectors(deps: ListConnectorsDeps): Promise<C
 			name,
 			installedServerId: nonEmptyString(entry?.installedServerId),
 			directoryUuid: nonEmptyString(entry?.directoryUuid),
+			installState: nonEmptyString(entry?.installState),
 			description: nonEmptyString(entry?.description),
 			isAuthless: typeof entry?.isAuthless === "boolean" ? entry.isAuthless : undefined,
 		});

package/src/connector-runtime.ts

@@ -0,0 +1,158 @@
+// Connector prime/snapshot host: the per-credential-scope inventory cache the
+// query path reads synchronously (vstack#832/#870). Extracted from index.ts —
+// this is process-lifetime runtime state, not provider streaming logic.
+//
+// Connector declarations for the query path, cached per credential scope. The
+// inventory is one HTTPS round trip; doing it per TURN would add that latency
+// to every message, and an account's connector set does not change
+// mid-session. Keyed by CLAUDE_CONFIG_DIR because that is what selects the
+// account — the org UUID in the request path is ignored, so two accounts on
+// one host differ only by which credential directory was read.
+//
+// FAILS OPEN. If credentials or the inventory call fail we return no
+// declarations and the turn proceeds exactly as it does today: connectors may
+// race, which is the bug, but a network blip must not break the turn outright.
+
+import { readFileSync as nodeReadFileSync } from "node:fs";
+import { readCachedConnectors, scopeKeyFor, writeCachedConnectors } from "./connector-cache.js";
+import { listAccountConnectors, resolveClaudeOAuth } from "./connector-inventory.js";
+import { connectorMcpServers } from "./connectors.js";
+import { debug } from "./debug.js";
+
+// Read a credential file, treating any read error as "absent" — a missing or
+// unreadable candidate must fall through to the next one, not abort resolution.
+export function readCredentialFile(path: string): string | undefined {
+	try {
+		return nodeReadFileSync(path, "utf8");
+	} catch {
+		return undefined;
+	}
+}
+
+const connectorServerCache = new Map<string, Record<string, unknown>>();
+const connectorServerPending = new Set<string>();
+// Epoch ms of the last FAILED inventory attempt per scope, so a persistently
+// failing account cools down instead of issuing one new HTTPS request per turn
+// (VST-14). Missing credentials are exempt: that check is a local file read
+// with no request to bound, and a just-completed `claude login` must take
+// effect on the next turn.
+const connectorServerFailureAt = new Map<string, number>();
+
+// Deadline on the inventory round trip. Without one, a hung claude.ai request
+// held the pending flag forever — same budget as the account-host probe's
+// ACCOUNT_PROBE_DEADLINE_MS (VST-14).
+const CONNECTOR_PRIME_TIMEOUT_MS = 10_000;
+const CONNECTOR_PRIME_FAILURE_COOLDOWN_MS = 60_000;
+
+/** Overrides for tests; production callers use the defaults. */
+export type PrimeConnectorOverrides = {
+	timeoutMs?: number;
+	failureCooldownMs?: number;
+	now?: () => number;
+};
+
+function connectorScopeKey(claudeConfigDir: string | undefined = process.env.CLAUDE_CONFIG_DIR): string {
+	// One rule for every scope key — the on-disk cache and this in-memory cache
+	// must name the same scopes (see scopeKeyFor).
+	return scopeKeyFor(claudeConfigDir);
+}
+
+// Credential resolution env for a selected scope: managed requests always pass
+// their RESOLVED dir (accountSessionScope), so the parent's CLAUDE_CONFIG_DIR
+// never leaks into another profile's lookup; legacy passes undefined and keeps
+// the process-env rule.
+export function connectorCredentialEnv(claudeConfigDir: string | undefined = process.env.CLAUDE_CONFIG_DIR): NodeJS.ProcessEnv {
+	const env = { ...process.env };
+	if (claudeConfigDir?.trim()) env.CLAUDE_CONFIG_DIR = claudeConfigDir.trim();
+	else delete env.CLAUDE_CONFIG_DIR;
+	return env;
+}
+
+// Kick off the inventory fetch for the current credential scope. Fire and
+// forget: the query path can only read a SYNCHRONOUS snapshot, because
+// streamClaudeAgentSdk returns a stream and claims the SDK query handle in the
+// same tick — there is no await boundary to hang a fetch on without
+// restructuring abort handling.
+//
+// Primed at provider registration so the result is in hand well before the
+// first turn (the call measured ~400ms against app startup). If a turn arrives
+// first it declares nothing and behaves exactly as it does today — the race is
+// back for that one turn, which is the bug, but never worse than the status quo.
+//
+// FAILS OPEN throughout: no credentials, a failed inventory, or a thrown call
+// all resolve to "declare nothing" rather than breaking the turn. Failures are
+// NOT cached — a transient blip at registration used to pin `{}` for the
+// process lifetime, keeping every later turn undeclared and the disk-cache
+// fallback unreachable. Leaving the key unset makes the next snapshot retry;
+// the pending set dedupes concurrent fetches, and a failed inventory attempt
+// stamps a per-scope cooldown so a persistently failing account backs off
+// instead of re-priming on every turn (VST-14).
+export function primeConnectorServers(claudeConfigDir?: string, overrides: PrimeConnectorOverrides = {}): void {
+	const key = connectorScopeKey(claudeConfigDir);
+	if (connectorServerCache.has(key) || connectorServerPending.has(key)) return;
+	const now = overrides.now ?? Date.now;
+	const cooldownMs = overrides.failureCooldownMs ?? CONNECTOR_PRIME_FAILURE_COOLDOWN_MS;
+	const failedAt = connectorServerFailureAt.get(key);
+	if (failedAt !== undefined && now() - failedAt < cooldownMs) {
+		debug("connectors: prime cooling down after failure; declaring none until retry window opens");
+		return;
+	}
+	connectorServerPending.add(key);
+	void (async () => {
+		let failed = false;
+		try {
+			const credentials = resolveClaudeOAuth(readCredentialFile, connectorCredentialEnv(claudeConfigDir));
+			if (!credentials) {
+				debug("connectors: no OAuth credentials; declaring none (will retry)");
+				return;
+			}
+			const inventory = await listAccountConnectors({
+				credentials,
+				// A hung inventory request must not outlive the deadline: the abort
+				// surfaces as `ok: false` and takes the cooldown path below.
+				signal: AbortSignal.timeout(overrides.timeoutMs ?? CONNECTOR_PRIME_TIMEOUT_MS),
+			});
+			if (!inventory.ok) {
+				failed = true;
+				debug(`connectors: inventory failed (${inventory.reason}); declaring none (will retry after cooldown)`);
+				return;
+			}
+			const servers = connectorMcpServers(inventory);
+			debug(`connectors: declaring ${Object.keys(servers).length} of ${inventory.connectors.length} installed`,
+				Object.keys(servers).join(", ") || "none");
+			connectorServerCache.set(key, servers);
+			connectorServerFailureAt.delete(key);
+			// Persist so the NEXT cold process has this synchronously. Priming always
+			// loses the race against turn 1 in its own process; a cache written by an
+			// earlier run is the only thing turn 1 can read in time (vstack#870).
+			if (writeCachedConnectors(inventory.connectors, key)) {
+				debug(`connectors: cached ${inventory.connectors.length} entries`);
+			}
+		} catch (error) {
+			failed = true;
+			debug("connectors: declaration lookup threw; declaring none (will retry after cooldown)", error);
+		} finally {
+			if (failed) connectorServerFailureAt.set(key, now());
+			connectorServerPending.delete(key);
+		}
+	})();
+}
+
+/** Synchronous snapshot for the query path; `{}` until priming resolves. */
+export function connectorServersSnapshot(claudeConfigDir?: string): Record<string, unknown> {
+	const key = connectorScopeKey(claudeConfigDir);
+	const ready = connectorServerCache.get(key);
+	if (ready) return ready;
+	// Always start (or continue) the live fetch — the cache is a head start, not
+	// a replacement, and the refresh keeps the next process current.
+	primeConnectorServers(claudeConfigDir);
+	// Fall back to the previous run's inventory, read synchronously. This is the
+	// only thing that can populate turn 1 of a cold process, because priming
+	// cannot finish before the first query is built (vstack#870).
+	const cached = readCachedConnectors(key);
+	if (!cached) return {};
+	const servers = connectorMcpServers({ ok: true, complete: true, connectors: cached });
+	if (Object.keys(servers).length === 0) return {};
+	debug(`connectors: turn-1 declarations from cache — ${Object.keys(servers).join(", ")}`);
+	return servers;
+}