@vanillagreen/pi-claude-bridge 1.8.0 → 1.9.0

package/src/claude-executable.ts

@@ -0,0 +1,264 @@
+import { type SpawnOptions, type SpawnedProcess } from "@anthropic-ai/claude-agent-sdk";
+import { spawn as spawnProcess } from "child_process";
+import { accessSync, constants as fsConstants, readFileSync, realpathSync, statSync } from "fs";
+import { delimiter, join } from "path";
+import { isolatedFromEnv } from "./config.js";
+import { DEBUG, debug } from "./debug.js";
+
+function executableFromPath(name: string): string | undefined {
+	const paths = (process.env.PATH ?? "").split(delimiter).filter(Boolean);
+	for (const dir of paths) {
+		const candidate = join(dir, name);
+		try {
+			accessSync(candidate, fsConstants.X_OK);
+			return candidate;
+		} catch {
+			// keep searching
+		}
+	}
+	return undefined;
+}
+
+export function resolveClaudeExecutable(configured?: string): string | undefined {
+	const trimmed = configured?.trim();
+	if (trimmed) return trimmed;
+	// Isolated mode: never run whatever `claude` happens to be on $PATH — the
+	// host app either pins an executable in config or gets the SDK's bundled
+	// default, which ships inside the host bundle.
+	if (isolatedFromEnv()) return undefined;
+	return executableFromPath("claude") ?? executableFromPath("claude-code");
+}
+
+export type ClaudeExecutableFileType = "elf" | "mach-o" | "pe" | "shebang-script" | "empty" | "unknown";
+
+export interface ClaudeExecutablePreflightResult {
+	path: string;
+	realPath: string;
+	cwd: string;
+	realCwd: string;
+	fileType: ClaudeExecutableFileType;
+}
+
+function errnoValue(err: unknown): string | number | undefined {
+	return typeof (err as NodeJS.ErrnoException)?.errno === "number" ? (err as NodeJS.ErrnoException).errno : undefined;
+}
+
+function syscallValue(err: unknown): string | undefined {
+	return typeof (err as NodeJS.ErrnoException)?.syscall === "string" ? (err as NodeJS.ErrnoException).syscall : undefined;
+}
+
+function pathValue(err: unknown): string | undefined {
+	const value = (err as NodeJS.ErrnoException)?.path;
+	return typeof value === "string" ? value : undefined;
+}
+
+function codeValue(err: unknown, fallback: string): string {
+	const value = (err as NodeJS.ErrnoException)?.code;
+	return typeof value === "string" ? value : fallback;
+}
+
+function displayValue(value: unknown): string {
+	return value === undefined || value === null || value === "" ? "<none>" : String(value);
+}
+
+function makeClaudePreflightError(
+	summary: string,
+	details: { code: string; errno?: string | number; syscall?: string; path: string; cwd: string; fileType?: ClaudeExecutableFileType; realPath?: string; cause?: unknown },
+): Error & NodeJS.ErrnoException & { cwd: string; fileType?: ClaudeExecutableFileType; realPath?: string } {
+	const detail = [
+		`code=${details.code}`,
+		`errno=${displayValue(details.errno)}`,
+		`syscall=${displayValue(details.syscall)}`,
+		`path=${details.path}`,
+		`cwd=${details.cwd}`,
+		...(details.fileType ? [`fileType=${details.fileType}`] : []),
+		...(details.realPath ? [`realPath=${details.realPath}`] : []),
+	].join(" ");
+	const error = new Error(`${summary} (${detail})`) as Error & NodeJS.ErrnoException & { cwd: string; fileType?: ClaudeExecutableFileType; realPath?: string };
+	error.name = "ClaudeExecutablePreflightError";
+	error.code = details.code;
+	if (details.errno !== undefined) error.errno = typeof details.errno === "number" ? details.errno : Number(details.errno);
+	if (details.syscall) error.syscall = details.syscall;
+	error.path = details.path;
+	error.cwd = details.cwd;
+	if (details.fileType) error.fileType = details.fileType;
+	if (details.realPath) error.realPath = details.realPath;
+	if (details.cause !== undefined) (error as Error & { cause?: unknown }).cause = details.cause;
+	return error;
+}
+
+export function classifyClaudeExecutableBytes(bytes: Uint8Array): ClaudeExecutableFileType {
+	if (bytes.length === 0) return "empty";
+	if (bytes.length >= 2 && bytes[0] === 0x23 && bytes[1] === 0x21) return "shebang-script";
+	if (bytes.length >= 4 && bytes[0] === 0x7f && bytes[1] === 0x45 && bytes[2] === 0x4c && bytes[3] === 0x46) return "elf";
+	if (bytes.length >= 2 && bytes[0] === 0x4d && bytes[1] === 0x5a) return "pe";
+	if (bytes.length >= 4) {
+		const magic = bytes[0] * 0x1000000 + bytes[1] * 0x10000 + bytes[2] * 0x100 + bytes[3];
+		if (
+			magic === 0xfeedface ||
+			magic === 0xfeedfacf ||
+			magic === 0xcefaedfe ||
+			magic === 0xcffaedfe ||
+			magic === 0xcafebabe ||
+			magic === 0xbebafeca
+		) return "mach-o";
+	}
+	return "unknown";
+}
+
+export function preflightClaudeExecutable(path: string, cwd: string): ClaudeExecutablePreflightResult {
+	let realCwd: string;
+	try {
+		const cwdStat = statSync(cwd);
+		if (!cwdStat.isDirectory()) {
+			throw makeClaudePreflightError("Claude Code spawn cwd preflight failed: cwd is not a directory.", {
+				code: "ENOTDIR",
+				syscall: "chdir",
+				path: cwd,
+				cwd,
+			});
+		}
+		accessSync(cwd, fsConstants.X_OK);
+		realCwd = realpathSync(cwd);
+	} catch (err) {
+		if ((err as Error).name === "ClaudeExecutablePreflightError") throw err;
+		throw makeClaudePreflightError("Claude Code spawn cwd preflight failed: cwd is not reachable before spawning Claude Code.", {
+			code: codeValue(err, "EACCES"),
+			errno: errnoValue(err),
+			syscall: syscallValue(err),
+			path: pathValue(err) ?? cwd,
+			cwd,
+			cause: err,
+		});
+	}
+
+	let realPath: string;
+	try {
+		const stat = statSync(path);
+		if (!stat.isFile()) {
+			throw makeClaudePreflightError("Claude Code executable preflight failed: resolved path is not a file.", {
+				code: "EACCES",
+				syscall: "exec",
+				path,
+				cwd,
+			});
+		}
+		accessSync(path, fsConstants.X_OK);
+		realPath = realpathSync(path);
+	} catch (err) {
+		if ((err as Error).name === "ClaudeExecutablePreflightError") throw err;
+		throw makeClaudePreflightError("Claude Code executable preflight failed: cannot access resolved executable before spawning Claude Code.", {
+			code: codeValue(err, "ENOENT"),
+			errno: errnoValue(err),
+			syscall: syscallValue(err),
+			path: pathValue(err) ?? path,
+			cwd,
+			cause: err,
+		});
+	}
+
+	let fileType: ClaudeExecutableFileType;
+	try {
+		fileType = classifyClaudeExecutableBytes(readFileSync(realPath).subarray(0, 16));
+	} catch (err) {
+		throw makeClaudePreflightError("Claude Code executable preflight failed: cannot read executable header before spawning Claude Code.", {
+			code: codeValue(err, "EACCES"),
+			errno: errnoValue(err),
+			syscall: syscallValue(err),
+			path: pathValue(err) ?? realPath,
+			cwd,
+			realPath,
+			cause: err,
+		});
+	}
+
+	if (!["elf", "mach-o", "pe", "shebang-script"].includes(fileType)) {
+		throw makeClaudePreflightError("Claude Code executable preflight failed: executable header is not an ELF, Mach-O, PE, or shebang script.", {
+			code: "ENOEXEC",
+			syscall: "exec",
+			path,
+			cwd,
+			fileType,
+			realPath,
+		});
+	}
+
+	return { path, realPath, cwd, realCwd, fileType };
+}
+
+function envFlagEnabled(value: string | undefined): boolean {
+	return value === "1" || value?.toLowerCase() === "true";
+}
+
+export function wrapClaudeSpawnErrorForSdk(err: Error, options: SpawnOptions): Error & NodeJS.ErrnoException & { cwd: string; originalCode?: string; originalMessage?: string } {
+	const originalCode = codeValue(err, "SPAWN_ERROR");
+	const originalMessage = err.message;
+	const spawnPath = pathValue(err) ?? options.command;
+	const cwd = options.cwd ?? process.cwd();
+	const detail = [
+		`code=${originalCode}`,
+		`errno=${displayValue(errnoValue(err))}`,
+		`syscall=${displayValue(syscallValue(err))}`,
+		`path=${spawnPath}`,
+		`cwd=${cwd}`,
+		`command=${options.command}`,
+	].join(" ");
+	const wrapped = new Error(`Claude Code spawn failed: ${originalMessage} (${detail})`) as Error & NodeJS.ErrnoException & { cwd: string; originalCode?: string; originalMessage?: string };
+	wrapped.name = "ClaudeSpawnDiagnosticError";
+	// The SDK special-cases code === ENOENT and replaces the message with its
+	// generic "native binary not found" text. Preserve the original code in the
+	// message/originalCode while using a bridge code so the SDK surfaces context.
+	wrapped.code = originalCode === "ENOENT" ? "CLAUDE_BRIDGE_SPAWN_FAILED" : originalCode;
+	wrapped.originalCode = originalCode;
+	wrapped.originalMessage = originalMessage;
+	const errno = errnoValue(err);
+	if (errno !== undefined) wrapped.errno = typeof errno === "number" ? errno : Number(errno);
+	const syscall = syscallValue(err);
+	if (syscall) wrapped.syscall = syscall;
+	wrapped.path = spawnPath;
+	wrapped.cwd = cwd;
+	// Do not set `cause` here: the listener copies these structured fields back
+	// onto the original Error. A cause reference to that same object would become
+	// `err.cause === err`, making JSON.stringify throw on a circular structure.
+	// originalMessage plus code/errno/syscall/path/cwd preserve the useful data.
+	return wrapped;
+}
+
+export function spawnClaudeCodeWithDiagnostics(options: SpawnOptions): SpawnedProcess {
+	const pipeStderr = DEBUG || envFlagEnabled(options.env.DEBUG_CLAUDE_AGENT_SDK);
+	const child = spawnProcess(options.command, options.args, {
+		cwd: options.cwd,
+		env: options.env,
+		signal: options.signal,
+		stdio: ["pipe", "pipe", pipeStderr ? "pipe" : "ignore"],
+		windowsHide: true,
+	});
+	if (pipeStderr) {
+		child.stderr?.on("data", (data) => {
+			for (const line of data.toString().split(/\r?\n/)) {
+				if (line) debug(`[cli-stderr spawn] ${line}`);
+			}
+		});
+	}
+	child.prependListener("error", (err) => {
+		const originalStack = err.stack;
+		const wrapped = wrapClaudeSpawnErrorForSdk(err, options);
+		Object.assign(err, wrapped);
+		err.name = wrapped.name;
+		err.message = wrapped.message;
+		// Keep V8's stack from the actual Node spawn failure, not the wrapper
+		// construction site. Diagnostic fields above remain enumerable and
+		// JSON-serializable; stack stays the spawn-time breadcrumb for operators.
+		if (originalStack) err.stack = originalStack;
+	});
+	return {
+		stdin: child.stdin,
+		stdout: child.stdout,
+		get killed() { return child.killed; },
+		get exitCode() { return child.exitCode; },
+		kill: child.kill.bind(child),
+		on: child.on.bind(child),
+		once: child.once.bind(child),
+		off: child.off.bind(child),
+	};
+}

package/src/config.ts

@@ -1,6 +1,8 @@
 // User-facing extension config. Legacy config is loaded from
 // ~/.pi/agent/claude-bridge.json and .pi/claude-bridge.json. vstack extension
-// manager config is loaded from settings.json and overrides legacy files.
+// manager config is loaded from settings.json and overrides legacy files in
+// normal Pi sessions. Isolated embedding hosts consume only the authoritative
+// user claude-bridge.json and never read extension-manager settings.
 
 import type { SettingSource } from "@anthropic-ai/claude-agent-sdk";
 import { existsSync, readFileSync } from "fs";
@@ -87,10 +89,11 @@ export function piUserDir(): string {
 /**
  * Isolated mode (`CLAUDE_BRIDGE_ISOLATED=1`): a host app embedding the bridge
  * declares that nothing outside its explicitly configured dirs may be read.
- * Disables every cwd/home discovery fallback — the cwd AGENTS.md walk, project
- * `.pi/` settings + claude-bridge.json, project APPEND_SYSTEM.md, and the
- * `$PATH` claude executable search. Reads stay confined to `piUserDir()` (i.e.
- * `PI_CODING_AGENT_DIR`) and the explicitly configured executable path.
+ * Disables every cwd/home discovery fallback — all AGENTS.md discovery,
+ * extension-manager settings, project `.pi/` settings + claude-bridge.json,
+ * project APPEND_SYSTEM.md, and the `$PATH` claude executable search. Bridge
+ * configuration comes only from `piUserDir()/claude-bridge.json` and any
+ * explicitly configured executable path.
  * Default (unset) behavior for normal pi CLI users is unchanged.
  */
 export function isolatedFromEnv(): boolean {
@@ -163,7 +166,10 @@ function projectSettingsTrusted(settingsPath: string): boolean {
 
 function settingsPaths(cwd: string): string[] {
 	const user = join(piUserDir(), "settings.json");
-	if (isolatedFromEnv()) return [user];
+	// An embedding host may have to share PI_CODING_AGENT_DIR with an in-process
+	// Pi SDK. In isolated mode, settings.json is therefore not authoritative and
+	// must not be consulted even at user scope.
+	if (isolatedFromEnv()) return [];
 	const project = projectSettingsPath(cwd);
 	return projectSettingsTrusted(project) ? [user, project] : [user];
 }
@@ -312,7 +318,7 @@ export function loadConfig(cwd: string): Config {
 	const projectSettings = isolated ? undefined : projectSettingsPath(cwd);
 	const trustedProject = projectSettings !== undefined && projectSettingsTrusted(projectSettings);
 	const project = trustedProject ? tryParseJson(join(dirname(projectSettings), "claude-bridge.json")) : {};
-	const manager = managerToConfig(readManagerConfig(cwd));
+	const manager: Partial<Config> = isolated ? {} : managerToConfig(readManagerConfig(cwd));
 	const provider = normalizeProviderConfig({ ...global.provider, ...project.provider, ...manager.provider });
 	return {
 		enabled: manager.enabled ?? project.enabled ?? global.enabled ?? true,

package/src/connector-inventory.ts

@@ -0,0 +1,281 @@
+// 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";
+// 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;
+	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>;
+
+/**
+ * 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),
+			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);
+}