@vanillagreen/pi-claude-bridge 1.8.0 → 2.0.0

package/src/connector-audit.ts

@@ -0,0 +1,203 @@
+// Audit trail for connector calls the `claude` child executes itself.
+//
+// A claude.ai connector tool runs INSIDE the child, on the child's own MCP
+// servers, and is deliberately never mirrored into the Pi stream (see
+// isChildExecutedTool). That is the honest behaviour — mirroring wrote
+// `Tool <name> not found` into the transcript for calls that had SUCCEEDED
+// (drovr#311 / memsira#320) — but it leaves the Pi session with no record that
+// the call happened at all, so "did it really look that up?" could only be
+// answered from the child's own transcript.
+//
+// A pi `CustomEntry` closes that gap without reintroducing the bug: it is
+// persisted in the session file, is NOT a content block, and is documented as
+// "ignored by buildSessionContext", so Pi's agent loop can never dispatch it and
+// `convertPiMessages` (which reads messages, not entries) can never project it
+// back into the child's session. `CustomMessageEntry` is the sibling type that
+// DOES enter context — using it here would recreate the whole problem.
+//
+// The payload is never recorded. A connector result is live account data (mail,
+// messages, documents); the audit answers whether a call happened and what came
+// back, not what it said.
+
+import { extensionApi } from "./bridge-state.js";
+import { debug } from "./debug.js";
+import type { QueryContext, ToolCallDrainCause } from "./query-state.js";
+
+export const CONNECTOR_CALL_CUSTOM_TYPE = "claude-bridge-connector-call";
+
+/**
+ * What the bridge observed of a connector call.
+ *
+ * `unobserved` is the load-bearing one: the call was issued and the query ended
+ * before its result came back. Recording nothing for it would leave an answer in
+ * the transcript with no trace of the call behind it — indistinguishable from a
+ * turn where no call was ever made. Same reasoning as `interruptedToolCallResult`
+ * for Pi-side tools: a call that did not complete says so.
+ */
+export type ConnectorCallOutcome = "ok" | "error" | "unobserved";
+
+export interface ConnectorCallAuditData {
+	/** Raw connector tool name as the child invoked it (`mcp__claude_ai_<Server>__<tool>`). */
+	name: string;
+	/** The child's own `tool_use` id — the join key to its transcript. */
+	toolUseId: string;
+	outcome: ConnectorCallOutcome;
+	/** UTF-8 byte size of the observed result payload. Absent when the result was
+	 *  never observed, or could not be measured — never a confident 0 for
+	 *  something that was not sized. */
+	byteSize?: number;
+	/** Claude Code session that executed the call. Absent when the SDK never
+	 *  reported one for this query. */
+	childSessionId?: string;
+	/** Why an `unobserved` call ended. Absent for observed ones. */
+	reason?: ToolCallDrainCause;
+}
+
+/**
+ * Approximate UTF-8 byte size of a child tool result's payload.
+ *
+ * A string payload is measured directly; any other shape is measured as its JSON
+ * serialization, so a structured or image result reports the size it really
+ * carried. (The debug line this replaces reported `content.length` for an array
+ * payload — a BLOCK count wearing a byte size's name.)
+ *
+ * Returns undefined when there is nothing to measure or the payload cannot be
+ * serialized, so the caller omits the field rather than recording a 0 it did not
+ * measure. The payload itself is never returned or logged.
+ */
+export function connectorResultByteSize(content: unknown): number | undefined {
+	if (content === undefined || content === null) return undefined;
+	if (typeof content === "string") return Buffer.byteLength(content, "utf8");
+	try {
+		const json = JSON.stringify(content);
+		return typeof json === "string" ? Buffer.byteLength(json, "utf8") : undefined;
+	} catch {
+		return undefined;
+	}
+}
+
+/**
+ * An ADDITIONAL destination for connector-call records, for a host that embeds
+ * the bridge with no pi session to append to.
+ *
+ * Never throws is the contract on OUR side; a sink that throws anyway is caught
+ * and dropped, because an audit record must not be able to fail a turn.
+ */
+export type ConnectorCallAuditSink = (data: ConnectorCallAuditData) => void;
+
+let auditSink: ConnectorCallAuditSink | undefined;
+
+/**
+ * Install (or clear, with `undefined`) a host sink for connector-call records.
+ *
+ * **The sink ADDS a destination, it never replaces `appendEntry`.** A host that
+ * drives real `AgentSession`s gets the transcript-local entries for free, and a
+ * replacing sink would take those away and reopen the very audit gap this
+ * feature closes (memsira, 2026-07-28 — their `apps/sidecar/src/runtime.ts` is
+ * session-backed, and 122 of their app-chat session files carry the bridge's
+ * `claude-bridge-session` markers). A host with both a session and a sink has
+ * asked for both and gets both.
+ *
+ * It exists because the OTHER embedding shape gets nothing at all: drovr loads
+ * the bundle through a throwaway resource loader over
+ * `createAgentSessionServices` with no session, so `extensionApi` is undefined
+ * and every record it appended went nowhere (drovr #317, measured live). The
+ * sink is the seam such a host can reach without one.
+ *
+ * A callback rather than another `Symbol.for` global on purpose: the bundle
+ * already has one (`claude-bridge:activeStreamSimple`) and hosts document that
+ * coupling as a re-vendor hazard, so a second would be the wrong direction.
+ *
+ * Process-global, matching `setExtensionApi`: one bundle instance serves one
+ * host. A host that runs several conversations in ONE process must therefore
+ * route by `childSessionId` itself, or embed per conversation as drovr does.
+ */
+export function setConnectorCallAuditSink(sink: ConnectorCallAuditSink | undefined): void {
+	auditSink = sink;
+}
+
+/**
+ * Append one audit entry to every destination the host installed. Returns
+ * whether it reached AT LEAST ONE of them, so a caller can log the truth rather
+ * than assume — both are absent whenever the bridge runs outside a pi session
+ * and outside a sink-installing host (tests, the connector-inventory entry
+ * point).
+ *
+ * The two destinations are independent: one throwing must not cost the other
+ * its record. Never throws — an audit record must not be able to fail a turn.
+ */
+export function appendConnectorCallAudit(data: ConnectorCallAuditData): boolean {
+	let delivered = false;
+	if (extensionApi) {
+		try {
+			extensionApi.appendEntry(CONNECTOR_CALL_CUSTOM_TYPE, data);
+			delivered = true;
+		} catch (error) {
+			debug("appendConnectorCallAudit failed:", error);
+		}
+	}
+	if (auditSink) {
+		try {
+			// A COPY, because the sink is host code and `appendEntry` above holds a
+			// reference to the same object: a sink that mutated the record would be
+			// editing what the session already recorded.
+			auditSink({ ...data });
+			delivered = true;
+		} catch (error) {
+			debug("connector call audit sink failed:", error);
+		}
+	}
+	return delivered;
+}
+
+/**
+ * Record the observed result of a child-executed connector call, once.
+ *
+ * Keyed on the tool_use id rather than on the call site: the SDK can re-yield a
+ * `user` message, and an audit trail that counts one call twice is worse than
+ * one that counts it not at all. Returns whether an entry was appended.
+ */
+export function recordConnectorCallResult(
+	queryCtx: QueryContext,
+	toolUseId: string,
+	name: string,
+	isError: boolean,
+	byteSize: number | undefined,
+): boolean {
+	const pending = queryCtx.connectorCallAudit.get(toolUseId);
+	if (pending?.recorded) return false;
+	const childSessionId = pending?.childSessionId ?? queryCtx.childSessionId;
+	queryCtx.connectorCallAudit.set(toolUseId, { ...pending, name, childSessionId, recorded: true });
+	return appendConnectorCallAudit({
+		name,
+		toolUseId,
+		outcome: isError ? "error" : "ok",
+		...(byteSize !== undefined ? { byteSize } : {}),
+		...(childSessionId ? { childSessionId } : {}),
+	});
+}
+
+/**
+ * Record every connector call this query issued whose result never came back,
+ * naming the cause. Runs at query teardown, beside the Pi-side tool drain, and is
+ * idempotent — a call already recorded is skipped, and one recorded here is
+ * marked so a late arrival cannot record it again.
+ *
+ * Returns how many entries were appended.
+ */
+export function flushConnectorCallAudit(queryCtx: QueryContext, reason: ToolCallDrainCause): number {
+	let appended = 0;
+	for (const [toolUseId, state] of queryCtx.connectorCallAudit) {
+		if (state.recorded) continue;
+		queryCtx.connectorCallAudit.set(toolUseId, { ...state, recorded: true });
+		const childSessionId = state.childSessionId ?? queryCtx.childSessionId;
+		if (appendConnectorCallAudit({
+			name: state.name,
+			toolUseId,
+			outcome: "unobserved",
+			reason,
+			...(childSessionId ? { childSessionId } : {}),
+		})) appended++;
+	}
+	return appended;
+}

package/src/connector-cache.ts

@@ -0,0 +1,118 @@
+// Cross-PROCESS cache of the connector inventory (vstack#870).
+//
+// #868 primes the inventory at provider registration, but the fetch takes ~1.5s
+// while the first query is built at ~0.5-0.8s, so turn 1 of a cold sidecar goes
+// out with no declarations and gets exactly the #832 bug it was meant to fix.
+//
+// An in-process cache cannot help the consumer that needs it most. drovr builds
+// a sidecar lazily on the first bridge round and, since their sidecars are
+// per-SESSION, that is a fresh process for every new chat — so their exposure is
+// once per chat, indefinitely, and every one of those is a cold process. The
+// cache therefore has to survive process boundaries.
+//
+// Keyed by credential scope, because that is what selects the account: the org
+// UUID in the inventory request is ignored and only the credential decides whose
+// connectors come back. Two accounts on one host must not share a cache entry.
+//
+// Everything here is best-effort. A missing, unreadable, corrupt, stale, or
+// wrong-version cache returns undefined and the caller falls back to today's
+// behaviour — the same fail-open contract as the inventory call itself.
+//
+// The ON-DISK FORMAT HAS AN EXTERNAL READER (vstack#892). drovr quarantines this
+// bundle to its sidecar process, so rather than calling `listAccountConnectors`
+// in-process it re-implements the reader half — path
+// `<piUserDir()>/connector-cache/<sha256(CLAUDE_CONFIG_DIR).hex[0..16]>.json`,
+// payload `{version, scope, savedAt, connectors}`, 7-day max age — as the
+// "is this connector installed" half of its write gate.
+//
+// That coupling fails OPEN on drift by design, so a format change degrades them
+// from two gates to one rather than breaking them. It is still worth making the
+// change knowingly: bump CACHE_VERSION so their staleness check rejects rather
+// than misreads, and say so in the changelog. `unit-connector-cache.mjs` pins
+// the path shape and payload keys.
+import { createHash } from "node:crypto";
+import { mkdirSync, readFileSync, writeFileSync } from "node:fs";
+import { dirname, join } from "node:path";
+import { piUserDir } from "./config.js";
+import type { ConnectorEntry } from "./connector-inventory.js";
+
+const CACHE_VERSION = 1;
+/** Long enough to be useful across a machine's lifetime, short enough that a
+ *  removed connector stops being declared without needing a manual purge. A
+ *  stale entry is not dangerous — a connector that no longer resolves simply
+ *  fails to connect, which is the fail-open path — so this is hygiene, not a
+ *  correctness boundary. */
+const MAX_AGE_MS = 7 * 24 * 60 * 60 * 1000;
+
+export function connectorCacheScopeKey(env: NodeJS.ProcessEnv = process.env): string {
+	return env.CLAUDE_CONFIG_DIR?.trim() || "<default>";
+}
+
+/**
+ * Our own state directory, not the Claude config dir. The credential directory
+ * belongs to the CLI; the scope is encoded in the filename instead so we never
+ * write into someone else's tree. Hashed rather than escaped because a config
+ * dir is an arbitrary absolute path.
+ */
+export function connectorCachePath(scopeKey: string = connectorCacheScopeKey()): string {
+	const digest = createHash("sha256").update(scopeKey).digest("hex").slice(0, 16);
+	return join(piUserDir(), "connector-cache", `${digest}.json`);
+}
+
+/**
+ * Synchronous by design. The query path has no await boundary to hang a read on
+ * — `streamClaudeAgentSdk` returns its stream and claims the SDK query handle in
+ * the same tick — which is the whole reason the in-memory prime loses the race.
+ * A single small `readFileSync` is what makes turn 1 reachable at all.
+ */
+export function readCachedConnectors(
+	scopeKey: string = connectorCacheScopeKey(),
+	now: number = Date.now(),
+): ConnectorEntry[] | undefined {
+	let raw: string;
+	try {
+		raw = readFileSync(connectorCachePath(scopeKey), "utf8");
+	} catch {
+		return undefined;
+	}
+	let parsed: any;
+	try {
+		parsed = JSON.parse(raw);
+	} catch {
+		return undefined;
+	}
+	if (parsed?.version !== CACHE_VERSION) return undefined;
+	// Scope is stored as well as hashed into the path: a hash collision or a
+	// hand-copied file would otherwise hand one account another's connectors,
+	// which is the exact failure the token-scoping note in connector-inventory.ts
+	// warns about.
+	if (parsed?.scope !== scopeKey) return undefined;
+	const savedAt = typeof parsed?.savedAt === "number" ? parsed.savedAt : 0;
+	if (!savedAt || now - savedAt > MAX_AGE_MS || savedAt > now) return undefined;
+	if (!Array.isArray(parsed?.connectors)) return undefined;
+	const connectors = parsed.connectors.filter(
+		(entry: any) => entry && typeof entry.name === "string" && entry.name.trim(),
+	);
+	return connectors.length > 0 ? (connectors as ConnectorEntry[]) : undefined;
+}
+
+/** Best-effort write; a failure here must never affect the turn. */
+export function writeCachedConnectors(
+	connectors: ConnectorEntry[],
+	scopeKey: string = connectorCacheScopeKey(),
+	now: number = Date.now(),
+): boolean {
+	if (!Array.isArray(connectors) || connectors.length === 0) return false;
+	const path = connectorCachePath(scopeKey);
+	try {
+		mkdirSync(dirname(path), { recursive: true, mode: 0o700 });
+		writeFileSync(
+			path,
+			JSON.stringify({ version: CACHE_VERSION, scope: scopeKey, savedAt: now, connectors }),
+			{ mode: 0o600 },
+		);
+		return true;
+	} catch {
+		return false;
+	}
+}

package/src/connector-inventory.ts

@@ -0,0 +1,333 @@
+// Deterministic enumeration of a Claude account's installed claude.ai connectors.
+//
+// The capability probe this replaces asked the MODEL to enumerate connectors via
+// ToolSearch. A search returns what the search surfaced, which is a LOWER BOUND —
+// nothing in the result distinguishes "these are the connectors" from "these are
+// the connectors the search happened to return this time". Downstream then stored
+// that lower bound as authoritative, so an account with Slack attached could
+// report an inventory without Slack and no failure signal (vstack#838).
+//
+// This module asks the account instead of the model. Verified live against a
+// personal claude_max org: the endpoint is POST (a GET returns 405) and each
+// result carries BOTH `directoryUuid` (the catalog identity) and
+// `installedServerId` (this account's installed instance). A marketplace catalog
+// entry has no installed-server id, which is what establishes this as the
+// INSTALLED set rather than the registry listing.
+//
+// INSTALLED IS NOT ATTACHED. This endpoint reports what the ACCOUNT has
+// installed. It says nothing about whether a given connector's MCP server has
+// finished attaching inside the `claude` child that is about to run a turn —
+// this is a plain HTTPS call and does not consult that process at all. The two
+// were previously conflated by accident: the ToolSearch probe could only report
+// what was already attached, so an inventory implied availability (wrongly, but
+// conservatively — it under-reported, which fails safe). They are now separately
+// observable and can legitimately disagree: a correct `complete: true` inventory
+// can name Slack while `mcp__claude_ai_Slack__*` is not yet callable in this
+// process (vstack#832). Treat an inventory as NECESSARY BUT NOT SUFFICIENT for
+// availability and keep an attach-time check on the call path; do not derive
+// "can I call this tool right now" from this result.
+//
+// Because the answer comes from the account rather than a model turn, the result
+// is complete by construction — hence `complete: true` on success, and no
+// "partial" state. A failure is a failure, never an empty-but-successful list.
+
+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";
+
+export type ConnectorEntry = {
+	name: string;
+	/** This account's installed instance. Present on every live result observed. */
+	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;
+};
+
+// Discriminated so a caller cannot read `connectors` without having checked `ok`.
+// `complete` is carried explicitly rather than implied: the whole defect this
+// fixes was a result that looked authoritative while being a lower bound.
+// The absent side of each variant is declared as `?: undefined` rather than
+// omitted: this package compiles with `strict: false`, where narrowing a union
+// by a boolean discriminant does not reliably filter members, so a bare
+// `{ok:true}|{ok:false}` pair makes `inventory.reason` a compile error at every
+// call site. Spelling both sides keeps the union discriminated AND readable
+// without depending on strictNullChecks-era narrowing.
+export type ConnectorInventory =
+	| { ok: true; complete: true; connectors: ConnectorEntry[]; reason?: undefined }
+	| { ok: false; complete: false; connectors?: undefined; reason: string };
+
+// SCOPING IS BY TOKEN, NOT BY ORG. Verified live: the org UUID in the path is
+// ignored — an all-zero UUID and the literal string "not-a-uuid" both returned
+// the bearer token's own account, identically to the real org. A multi-account
+// host therefore CANNOT select an account by passing its organizationUuid; the
+// only thing that selects an account is which credential the token came from
+// (i.e. which CLAUDE_CONFIG_DIR was read). Getting that wrong yields a
+// confident, well-formed answer for the WRONG account.
+//
+// The real UUID is still sent rather than a placeholder, so the call keeps
+// working if the API starts enforcing it.
+export type ClaudeOAuthCredentials = {
+	accessToken: string;
+	organizationUuid: string;
+};
+
+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
+ * connector with whitespace replaced by underscores; corroborated against the
+ * independently-authored CLAUDE_AI_CONNECTOR_TOOL_PATTERNS in connectors.ts,
+ * which was built from a live tool enumeration rather than from this rule.
+ */
+export function connectorServerNamespace(connectorName: string): string {
+	return `${CONNECTOR_NS_PREFIX}${connectorName.trim().replace(/\s+/g, "_")}__`;
+}
+
+// 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.
+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);
+	const seen = new Set<string>();
+	const paths: string[] = [];
+	for (const root of roots) {
+		for (const name of [".credentials.json", ".claude.json"]) {
+			const p = `${root}/${name}`;
+			if (!seen.has(p)) { seen.add(p); paths.push(p); }
+		}
+	}
+	return paths;
+}
+
+/**
+ * Pull the OAuth access token and organization UUID out of the Claude config.
+ * They are scanned independently across all candidate files because they are not
+ * guaranteed to co-locate: on the machine this was verified against, the token
+ * lives in `.credentials.json` and the org UUID in `.claude.json`.
+ *
+ * `readFile` returns undefined for a missing/unreadable path. Parse failures are
+ * skipped rather than thrown — a corrupt file must not mask a good one later in
+ * the list.
+ */
+export function resolveClaudeOAuth(
+	readFile: (path: string) => string | undefined,
+	env: NodeJS.ProcessEnv = process.env,
+): ClaudeOAuthCredentials | undefined {
+	let accessToken: string | undefined;
+	let organizationUuid: string | undefined;
+
+	for (const path of credentialCandidatePaths(env)) {
+		const raw = readFile(path);
+		if (!raw) continue;
+		let parsed: Json;
+		try {
+			parsed = JSON.parse(raw) as Json;
+		} catch {
+			continue;
+		}
+		accessToken ??= nonEmptyString(parsed?.claudeAiOauth?.accessToken);
+		organizationUuid ??= nonEmptyString(parsed?.oauthAccount?.organizationUuid);
+		if (accessToken && organizationUuid) break;
+	}
+
+	if (!accessToken || !organizationUuid) return undefined;
+	return { accessToken, organizationUuid };
+}
+
+function nonEmptyString(value: unknown): string | undefined {
+	return typeof value === "string" && value.trim() ? value.trim() : undefined;
+}
+
+export function connectorsListUrl(organizationUuid: string, apiBase: string = DEFAULT_API_BASE): string {
+	return `${trimTrailingSlashes(apiBase)}/api/oauth/organizations/${encodeURIComponent(organizationUuid)}/mcp/connectors/list`;
+}
+
+// Linear-time trailing-slash trim. This was `apiBase.replace(/\/+$/, "")`, which
+// CodeQL correctly flags as a polynomial regex on uncontrolled input: `apiBase`
+// is a caller-supplied parameter, and an anchored `+` backtracks on a long run
+// of slashes. It only became reachable as library input once this module gained
+// a real export surface, which is exactly the exposure the export was for.
+function trimTrailingSlashes(value: string): string {
+	let end = value.length;
+	while (end > 0 && value.charCodeAt(end - 1) === 47 /* "/" */) end--;
+	return value.slice(0, end);
+}
+
+export type ListConnectorsDeps = {
+	credentials: ClaudeOAuthCredentials;
+	fetchImpl?: typeof fetch;
+	apiBase?: string;
+	signal?: AbortSignal;
+};
+
+/**
+ * Enumerate the account's installed connectors. Never throws: transport and
+ * protocol failures come back as `{ ok: false }` with a reason, so a caller can
+ * distinguish "this account has no connectors" (ok, empty list) from "we could
+ * not find out" — the distinction the search-driven probe could not express.
+ *
+ * The reason string is built only from the HTTP status and the API's own error
+ * message; the bearer token is never interpolated into it or logged.
+ */
+export async function listAccountConnectors(deps: ListConnectorsDeps): Promise<ConnectorInventory> {
+	const { credentials, apiBase, signal } = deps;
+	const fetchImpl = deps.fetchImpl ?? fetch;
+	const url = connectorsListUrl(credentials.organizationUuid, apiBase);
+	// Every failure return goes through this. Transport errors are the risk: a
+	// fetch/proxy layer is free to put the request headers — and therefore the
+	// bearer token — into the message it throws, and that message would otherwise
+	// land in a reason string that callers log.
+	const fail = (reason: string): ConnectorInventory =>
+		({ ok: false, complete: false, reason: redactSecret(reason, credentials.accessToken) });
+
+	let response: Response;
+	try {
+		response = await fetchImpl(url, {
+			method: "POST",
+			headers: {
+				"Authorization": `Bearer ${credentials.accessToken}`,
+				"anthropic-beta": OAUTH_BETA_HEADER,
+				"Content-Type": "application/json",
+			},
+			body: "{}",
+			signal,
+		});
+	} catch (error) {
+		return fail(`connector list request failed: ${errorText(error)}`);
+	}
+
+	let bodyText: string;
+	try {
+		bodyText = await response.text();
+	} catch (error) {
+		return fail(`connector list response unreadable: ${errorText(error)}`);
+	}
+
+	if (!response.ok) {
+		return fail(`connector list returned HTTP ${response.status}${apiErrorSuffix(bodyText)}`);
+	}
+
+	let parsed: Json;
+	try {
+		parsed = JSON.parse(bodyText) as Json;
+	} catch {
+		return fail("connector list returned a non-JSON body");
+	}
+
+	// A missing/!Array `results` is a protocol change, not an empty account. Treat
+	// it as failure — reporting "no connectors" here would recreate exactly the
+	// silent-wrong-answer failure this module exists to remove.
+	if (!Array.isArray(parsed?.results)) {
+		return fail("connector list response had no results array");
+	}
+
+	const connectors: ConnectorEntry[] = [];
+	for (const raw of parsed.results as unknown[]) {
+		const entry = raw as Json;
+		const name = nonEmptyString(entry?.name);
+		// An unnamed entry cannot be matched to a tool namespace by any consumer,
+		// so silently keeping it would understate the inventory in a way the
+		// caller could not detect. Fail instead.
+		if (!name) {
+			return fail("connector list contained an entry with no name");
+		}
+		connectors.push({
+			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,
+		});
+	}
+
+	return { ok: true, complete: true, connectors };
+}
+
+function apiErrorSuffix(bodyText: string): string {
+	try {
+		const message = (JSON.parse(bodyText) as Json)?.error?.message;
+		return typeof message === "string" && message.trim() ? ` (${message.trim()})` : "";
+	} catch {
+		return "";
+	}
+}
+
+// Replace the bearer token wherever it appears in text headed for a caller.
+// Also covers a URL-encoded rendering, since some transports encode headers into
+// an error's message. Short/empty tokens are not substituted — an over-eager
+// match would corrupt unrelated text.
+function redactSecret(text: string, secret: string): string {
+	if (!secret || secret.length < 8) return text;
+	let out = text;
+	for (const form of new Set([secret, encodeURIComponent(secret)])) {
+		out = out.split(form).join("[redacted]");
+	}
+	return out;
+}
+
+function errorText(error: unknown): string {
+	return error instanceof Error ? error.message : String(error);
+}