@hienlh/ppm 0.22.8 → 0.22.10

package/src/providers/claude-agent-sdk.ts

@@ -1072,14 +1072,7 @@ export class ClaudeAgentSdkProvider implements AIProvider {
       }
       console.log(`[sdk] query: session=${sessionId} isFirst=${isFirstMessage} fork=${shouldFork} cwd=${effectiveCwd} platform=${process.platform} accountMode=${!!account} permissionMode=${permissionMode} isBypass=${isBypass}`);
 
-      // Read MCP servers from PPM DB (fresh per query — user may add/remove between chats),
-      // merged with servers inherited from Claude Code's ~/.claude.json for this project.
-      // PPM DB entries override inherited ones on name conflict.
-      const ownServers = mcpConfigService.list();
-      const inheritedServers = providerConfig.inherit_claude_mcp !== false
-        ? listInheritedClaudeMcpServers(effectiveCwd)
-        : {};
-      const mcpServers = { ...inheritedServers, ...ownServers };
+      const mcpServers = this.resolveMcpServers(effectiveCwd);
       const hasMcp = Object.keys(mcpServers).length > 0;
 
       // Buffer subprocess stderr for crash diagnostics + log in real-time
@@ -1334,6 +1327,15 @@ export class ClaudeAgentSdkProvider implements AIProvider {
             } else {
               console.log(`[sdk] session=${sessionId} init: sdk_session_id=${sdkSid}`);
             }
+            // Carry each MCP server's connection state so the host can offer a sign-in
+            // for the ones reporting `needs-auth`.
+            const initServers = (msg as any).mcp_servers;
+            yield {
+              type: "system" as any,
+              subtype,
+              ...(Array.isArray(initServers) && { mcpServers: initServers }),
+            } as any;
+            continue;
           }
 
           // Detect compacting status
@@ -2109,6 +2111,83 @@ export class ClaudeAgentSdkProvider implements AIProvider {
   }
 
 
+  /**
+   * MCP servers for a query in `cwd`: PPM's own (read fresh — the user may add or remove
+   * one between chats) over those inherited from Claude Code's ~/.claude.json for this
+   * project. PPM entries win on a name conflict.
+   */
+  private resolveMcpServers(cwd: string): Record<string, unknown> {
+    const inherited = this.getProviderConfig().inherit_claude_mcp !== false
+      ? listInheritedClaudeMcpServers(cwd)
+      : {};
+    return { ...inherited, ...mcpConfigService.list() };
+  }
+
+  /**
+   * A subprocess that never receives a prompt, for control requests only — MCP status
+   * and MCP sign-in. It is configured like a chat query in `cwd` (same CLI, settings
+   * sources and MCP servers), so it sees exactly the servers a chat there would, and it
+   * never calls the model. The caller owns it and must `close()` it: an OAuth flow's
+   * localhost callback listener lives inside this process.
+   */
+  openMcpControlQuery(cwd: string): { query: any; close: () => void } {
+    const providerConfig = this.getProviderConfig();
+    const cliExecutablePath = resolveCliExecutablePath(
+      (providerConfig as { cli_command?: string }).cli_command,
+    );
+    const mcpServers = this.resolveMcpServers(cwd);
+    const { generator, controller } = createMessageChannel();
+    const q = query({
+      prompt: generator,
+      options: {
+        ...(needsNodeInterpreter(process.platform, cliExecutablePath) && { executable: "node" }),
+        ...(cliExecutablePath && { pathToClaudeCodeExecutable: cliExecutablePath }),
+        cwd,
+        settingSources: ["user", "project"],
+        // No account: MCP OAuth tokens belong to the CLI's own credential store, the same
+        // one an interactive `claude` writes, and no model call is ever made here.
+        env: this.buildQueryEnv(cwd, null),
+        settings: { permissions: { allow: [], deny: [] } },
+        ...(Object.keys(mcpServers).length > 0 && { mcpServers }),
+        stderr: (chunk: string) => {
+          const line = chunk.trim();
+          if (line) console.log(`[mcp-control] stderr: ${line.slice(0, 300)}`);
+        },
+      } as any,
+    });
+    let closed = false;
+    return {
+      query: q,
+      close: () => {
+        if (closed) return;
+        closed = true;
+        controller.done();
+        q.close();
+      },
+    };
+  }
+
+  /**
+   * Reconnect one MCP server inside a live chat subprocess, so a sign-in finished
+   * elsewhere shows up without restarting the conversation. Returns the server's status
+   * afterwards, or null when the session has no live subprocess.
+   */
+  async reconnectMcpServer(sessionId: string, serverName: string): Promise<string | null> {
+    const ss = this.streamingSessions.get(sessionId);
+    if (!ss) return null;
+    try {
+      await ss.query.reconnectMcpServer(serverName);
+    } catch (e) {
+      console.warn(`[sdk] session=${sessionId} reconnectMcpServer(${serverName}) failed: ${(e as Error).message}`);
+    }
+    try {
+      const statuses: Array<{ name: string; status: string }> = await ss.query.mcpServerStatus();
+      return statuses.find((s) => s.name === serverName)?.status ?? null;
+    } catch {
+      return null;
+    }
+  }
+
   /** Abort and fully teardown the streaming session — user must resume to continue */
   abortQuery(sessionId: string, source = "unknown"): void {
     // Capture stack to identify caller during debugging intermittent abort bugs

package/src/server/index.ts

@@ -180,6 +180,12 @@ app.route("/proxy", proxyRoutes);
 // HTML assets authenticate with bounded preview capabilities, never the PPM session token.
 app.route("/api/html-preview/content", htmlPreviewRoutes.content);
 
+// MCP sign-in redirect: reached by a browser navigation from the authorization server,
+// which carries no PPM token. It only completes a flow an authenticated user started.
+import { mcpAuthRoutes, mcpAuthCallbackHandler } from "./routes/mcp-auth.ts";
+import { mcpOAuthFlows } from "../services/mcp-oauth/mcp-oauth-flows.ts";
+app.get("/api/mcp-auth/callback", mcpAuthCallbackHandler);
+
 // Auth check endpoint (behind auth middleware)
 app.use("/api/*", authMiddleware);
 app.use("/api/*", gzipJson);
@@ -227,6 +233,7 @@ app.route("/api/loopback", loopbackRoutes);
 // API routes
 app.route("/api/settings", settingsRoutes);
 app.route("/api/settings/mcp", mcpRoutes);
+app.route("/api/mcp-auth", mcpAuthRoutes);
 app.route("/api/settings/themes", settingsThemesRoutes);
 app.route("/api/tunnel", tunnelRoutes);
 import { namedTunnelRoutes } from "./routes/named-tunnel.ts";
@@ -1054,6 +1061,8 @@ if (process.argv.includes("__serve__")) {
     // resident rust-analyzer holding a crate graph is too expensive to leave
     // to chance. Synchronous because process.exit follows immediately.
     try { lspManager.killAllSync(); } catch {}
+    // An MCP sign-in holds a Claude subprocess until it settles.
+    try { mcpOAuthFlows.disposeAll(); } catch {}
     try { server.stop(true); } catch {}
     process.exit(0);
   };

package/src/server/routes/mcp-auth.ts

@@ -0,0 +1,117 @@
+/**
+ * MCP sign-in (OAuth) for servers that report `needs-auth`.
+ *
+ * Everything here is behind PPM's auth except `mcpAuthCallbackHandler`: the authorization
+ * server redirects the *browser* there by a top-level navigation, which carries no PPM
+ * token. It is safe to leave open because it can only complete a flow an authenticated
+ * user started — it matches the redirect's single-use OAuth `state` to a waiting flow, and
+ * the CLI checks that state again before exchanging the code.
+ */
+import { Hono, type Context } from "hono";
+import { homedir } from "node:os";
+import { ok, err } from "../../types/api.ts";
+import { resolveProjectPath } from "../helpers/resolve-project.ts";
+import { mcpOAuthFlows, McpAuthFlowNotFoundError, type McpOAuthFlows } from "../../services/mcp-oauth/mcp-oauth-flows.ts";
+import { mcpStatusProbe } from "../../services/mcp-oauth/mcp-status-probe.ts";
+import { callbackUrlFor, customRedirectUri } from "../../services/mcp-oauth/mcp-oauth-redirect.ts";
+
+// A cached status would still say `needs-auth` right after a sign-in.
+mcpOAuthFlows.onAuthorized(() => mcpStatusProbe.invalidate());
+
+export const mcpAuthRoutes = new Hono();
+
+/** Directory whose MCP configuration applies: the project's, or the home directory. */
+function cwdFor(project: string | undefined): string {
+  return project ? resolveProjectPath(project) : homedir();
+}
+
+// GET /status?project=<name>&fresh=1 — every server's connection state
+mcpAuthRoutes.get("/status", async (c) => {
+  let cwd: string;
+  try { cwd = cwdFor(c.req.query("project")); } catch (e) { return c.json(err((e as Error).message), 404); }
+  try {
+    const servers = await mcpStatusProbe.status(cwd, { fresh: c.req.query("fresh") === "1" });
+    return c.json(ok(servers));
+  } catch (e) {
+    return c.json(err(`Could not read MCP status: ${(e as Error).message}`), 500);
+  }
+});
+
+// POST /start { server, project?, origin? } — begin a sign-in, returns the flow
+mcpAuthRoutes.post("/start", async (c) => {
+  const body = await c.req.json<{ server?: string; project?: string; origin?: string }>().catch(() => ({} as Record<string, undefined>));
+  if (!body.server || typeof body.server !== "string") return c.json(err("Missing required field: server"), 400);
+  let cwd: string;
+  try { cwd = cwdFor(body.project); } catch (e) { return c.json(err((e as Error).message), 404); }
+  const redirectUri = customRedirectUri(body.origin, [c.req.header("x-forwarded-host"), c.req.header("host")]);
+  try {
+    return c.json(ok(await mcpOAuthFlows.start(body.server, cwd, redirectUri)));
+  } catch (e) {
+    return c.json(err(`Could not start the sign-in: ${(e as Error).message}`), 500);
+  }
+});
+
+mcpAuthRoutes.get("/flows/:id", (c) => {
+  const flow = mcpOAuthFlows.get(c.req.param("id"));
+  return flow ? c.json(ok(flow)) : c.json(err("This sign-in is no longer active. Start again."), 404);
+});
+
+// POST /flows/:id/callback { url } — the redirect URL the user pasted
+mcpAuthRoutes.post("/flows/:id/callback", async (c) => {
+  const body = await c.req.json<{ url?: string }>().catch(() => ({} as { url?: string }));
+  if (!body.url || typeof body.url !== "string" || body.url.length > 16_384) {
+    return c.json(err("Paste the full address from the browser after signing in."), 400);
+  }
+  return flowAction(c, () => mcpOAuthFlows.submitCallback(c.req.param("id"), body.url!.trim()));
+});
+
+// POST /flows/:id/confirm — "I've granted access" for a claude.ai connector
+mcpAuthRoutes.post("/flows/:id/confirm", (c) => flowAction(c, () => mcpOAuthFlows.confirm(c.req.param("id"))));
+
+mcpAuthRoutes.delete("/flows/:id", (c) => {
+  const flow = mcpOAuthFlows.cancel(c.req.param("id"));
+  return flow ? c.json(ok(flow)) : c.json(err("Sign-in not found"), 404);
+});
+
+async function flowAction(c: Context, run: () => Promise<unknown>) {
+  try {
+    return c.json(ok(await run()));
+  } catch (e) {
+    if (e instanceof McpAuthFlowNotFoundError) return c.json(err(e.message), 404);
+    return c.json(err((e as Error).message), 500);
+  }
+}
+
+/** GET /api/mcp-auth/callback — PUBLIC. Where the authorization server sends the browser back. */
+export function createMcpAuthCallbackHandler(flows: McpOAuthFlows) {
+  return async (c: Context) => {
+    const url = new URL(c.req.url);
+    const flow = flows.findByState(url.searchParams.get("state"));
+    // A flow without a redirect URI uses the CLI's own localhost listener; its state
+    // arriving here means somebody is replaying it, not completing it.
+    if (!flow || !flow.redirectUri) {
+      return c.html(page("Sign-in not found", "This sign-in link is no longer active. Start the sign-in again from PPM."), 404);
+    }
+    const serverName = flow.serverName;
+    const result = await flows.submitCallback(flow.id, callbackUrlFor(flow.redirectUri, url.search));
+    if (result.status === "done") {
+      return c.html(page("Signed in", `${serverName} is connected. You can close this tab and return to PPM.`, true));
+    }
+    return c.html(page("Sign-in failed", result.error ?? `Could not finish signing in to ${serverName}.`), 400);
+  };
+}
+
+export const mcpAuthCallbackHandler = createMcpAuthCallbackHandler(mcpOAuthFlows);
+
+function page(title: string, message: string, closeSoon = false): string {
+  // Best effort: after the cross-site redirects most browsers refuse to let a tab close
+  // itself, and then the message simply stays.
+  const script = closeSoon ? "<script>setTimeout(function(){window.close()},1500)</script>" : "";
+  return `<!doctype html><html><head><meta charset="utf-8"><meta name="viewport" content="width=device-width,initial-scale=1">`
+    + `<title>${escapeHtml(title)}</title><style>body{font-family:system-ui,sans-serif;max-width:32rem;margin:15vh auto;padding:0 1.5rem;line-height:1.5;color-scheme:light dark}</style>`
+    + `</head><body><h1>${escapeHtml(title)}</h1><p>${escapeHtml(message)}</p>${script}</body></html>`;
+}
+
+function escapeHtml(s: string): string {
+  return s.replace(/[&<>"']/g, (ch) => ({ "&": "&amp;", "<": "&lt;", ">": "&gt;", '"': "&quot;", "'": "&#39;" })[ch]!);
+}

package/src/server/routes/settings.ts

@@ -118,6 +118,8 @@ const UI_PREF_VALIDATORS: Record<string, (v: unknown) => boolean> = {
   sidebarCollapsed: (v) => typeof v === "boolean",
   remoteDesktopStatsVisible: (v) => typeof v === "boolean",
   remoteDesktopWarningDismissed: (v) => typeof v === "boolean",
+  // MCP servers the user hid from the chat's sign-in bar (by name)
+  mcpSignInDismissed: (v) => Array.isArray(v) && v.length <= 200 && v.every((s) => typeof s === "string" && s.length <= 200),
   keepScreenAwake: (v) => typeof v === "boolean",
   sidebarWidth: (v) => typeof v === "number" && v >= 200 && v <= 600,
   gitStatusViewMode: (v) => v === "flat" || v === "tree",

package/src/server/ws/chat-mcp-sign-in-sync.ts

@@ -0,0 +1,58 @@
+/**
+ * Keeps each chat's "needs sign-in" list in step with MCP sign-ins.
+ *
+ * The list comes from the SDK's `init` message, so it is only as fresh as the subprocess.
+ * A sign-in finished from any screen stores tokens every Claude process can read, but a
+ * running chat subprocess keeps the server in `needs-auth` until told to reconnect it — so
+ * on each sign-in the server is reconnected in every chat still listing it.
+ *
+ * If that chat's subprocess still reports `needs-auth` afterwards, the only way to make it
+ * read the tokens is a fresh subprocess. That is done only when nothing would be lost: an
+ * idle turn is not enough, because background agents and shells keep running inside the
+ * subprocess after the turn that started them has ended. Otherwise the server goes back on
+ * the list, so the bar keeps saying what is still true.
+ */
+import { mcpOAuthFlows } from "../../services/mcp-oauth/mcp-oauth-flows.ts";
+
+export interface McpSignInSession {
+  providerId: string;
+  phase: string;
+  mcpNeedsAuth?: string[];
+}
+
+export interface McpSignInSyncDeps {
+  sessions: () => Iterable<[string, McpSignInSession]>;
+  broadcast: (sessionId: string, event: unknown) => void;
+  reconnect: (providerId: string, sessionId: string, serverName: string) => Promise<string | null>;
+  /** Whether the subprocess can be replaced without killing work still running in it. */
+  canDrop: (sessionId: string) => boolean;
+  dropIdle: (sessionId: string, serverName: string) => void;
+}
+
+/** The event carrying a session's list to its clients. */
+export function mcpStatusEvent(needsAuth: string[] | undefined) {
+  return { type: "mcp_status", needsAuth: needsAuth ?? [] };
+}
+
+/** React to one successful sign-in. Exported for tests; production wires it via `register`. */
+export async function handleMcpAuthorized(serverName: string, deps: McpSignInSyncDeps): Promise<void> {
+  const affected = [...deps.sessions()].filter(([, s]) => s.mcpNeedsAuth?.includes(serverName));
+  await Promise.all(affected.map(async ([sessionId, s]) => {
+    s.mcpNeedsAuth = s.mcpNeedsAuth!.filter((n) => n !== serverName);
+    deps.broadcast(sessionId, mcpStatusEvent(s.mcpNeedsAuth));
+    const status = await deps.reconnect(s.providerId, sessionId, serverName).catch(() => null);
+    // Anything but a definite `needs-auth` (connected, pending, a transient failure, or no
+    // live subprocess at all) is left alone: the next `init` reports the truth.
+    if (status !== "needs-auth") return;
+    if (s.phase === "idle" && deps.canDrop(sessionId)) {
+      deps.dropIdle(sessionId, serverName);
+      return;
+    }
+    if (!s.mcpNeedsAuth!.includes(serverName)) s.mcpNeedsAuth = [...s.mcpNeedsAuth!, serverName];
+    deps.broadcast(sessionId, mcpStatusEvent(s.mcpNeedsAuth));
+  }));
+}
+
+export function registerMcpSignInSync(deps: McpSignInSyncDeps): () => void {
+  return mcpOAuthFlows.onAuthorized((serverName) => { void handleMcpAuthorized(serverName, deps); });
+}

package/src/server/ws/chat.ts

@@ -18,6 +18,8 @@ import { configService } from "../../services/config.service.ts";
 import { formatTurnUsageLog } from "../../shared/turn-usage.ts";
 import { isAsyncAgentLaunchAck, isTerminalAgentStatus } from "../../shared/background-agent-status.ts";
 import { cacheReleaseDelayMs, selectWarmIdleEvictions } from "../../services/subprocess-retention.ts";
+import { needsAuthServerNames } from "../../services/mcp-oauth/mcp-oauth-redirect.ts";
+import { mcpStatusEvent, registerMcpSignInSync } from "./chat-mcp-sign-in-sync.ts";
 
 /** Resolve the SESSION's provider config — not the global default provider's.
  * Otherwise a non-default provider's chat (e.g. codex) would inherit claude's values. */
@@ -116,6 +118,8 @@ interface SessionEntry {
   lastImplicitTeamProbe?: number;
   /** Compact indicator state — sticky until turn ends or boundary received, synced on reconnect */
   compactStatus?: "compacting" | null;
+  /** MCP servers the subprocess reported as `needs-auth` at init — drives the chat's sign-in bar */
+  mcpNeedsAuth?: string[];
   /** toolUseIds of Bash/Agent calls launched with run_in_background — their spy outlives the tool_result */
   backgroundToolUseIds?: Set<string>;
   /** Nested-agent children buffered into turnEvents this turn (see MAX_NESTED_TURN_EVENTS) */
@@ -249,6 +253,28 @@ function broadcastBackgroundRegistry(sessionId: string): void {
 /** Tracks active sessions — persists even when FE disconnects */
 const activeSessions = new Map<string, SessionEntry>();
 
+registerMcpSignInSync({
+  sessions: () => activeSessions.entries(),
+  broadcast: (sessionId, event) => broadcast(sessionId, event),
+  reconnect: async (providerId, sessionId, serverName) => {
+    const provider = providerRegistry.get(providerId) as { reconnectMcpServer?: (s: string, n: string) => Promise<string | null> } | undefined;
+    return provider?.reconnectMcpServer?.(sessionId, serverName) ?? null;
+  },
+  // Background agents and shells outlive the turn inside the subprocess; a sign-in elsewhere
+  // must never be what kills them.
+  canDrop: (sessionId) => {
+    const entry = activeSessions.get(sessionId);
+    if (!entry || entry.isStreamingActive) return false;
+    if ((entry.backgroundToolUseIds?.size ?? 0) > 0) return false;
+    return !backgroundShellRegistry.list(sessionId).some((sh) => sh.status !== "stopped");
+  },
+  dropIdle: (sessionId, serverName) => dropIdleSubprocess(
+    sessionId,
+    "mcp_sign_in",
+    `Subprocess released: it could not see the new ${serverName} sign-in, the next turn starts a fresh one`,
+  ),
+});
+
 /** Check if any frontend client is currently connected via WebSocket */
 export function hasActiveClient(): boolean {
   for (const entry of activeSessions.values()) {
@@ -609,7 +635,10 @@ async function startSessionConsumer(sessionId: string, providerId: string, conte
       // System events → transition connecting → thinking, forward compact events
       if (evType === "system") {
         const sub = (ev as any).subtype;
-        if (sub === "compacting") {
+        if (sub === "init" && Array.isArray(ev.mcpServers)) {
+          entry.mcpNeedsAuth = needsAuthServerNames(ev.mcpServers);
+          broadcast(sessionId, mcpStatusEvent(entry.mcpNeedsAuth));
+        } else if (sub === "compacting") {
           entry.compactStatus = "compacting";
           console.log(`[chat] session=${sessionId} compact_status=compacting (persisted on entry)`);
           broadcast(sessionId, { type: "compact_status", status: "compacting" });
@@ -1001,6 +1030,7 @@ export const chatWebSocket = {
         pendingApproval: existing.pendingApprovalEvent ?? null,
         sessionTitle: session?.title || null,
         compactStatus: existing.compactStatus ?? null,
+        mcpNeedsAuth: existing.mcpNeedsAuth ?? [],
         model: resolveSessionModel(sessionId),
         effort: resolveSessionEffort(sessionId),
         thinking: resolveSessionThinkingEnabled(sessionId),
@@ -1134,6 +1164,7 @@ export const chatWebSocket = {
         pendingApproval: entry.pendingApprovalEvent ?? null,
         sessionTitle: chatService.getSession(sessionId)?.title || null,
         compactStatus: entry.compactStatus ?? null,
+        mcpNeedsAuth: entry.mcpNeedsAuth ?? [],
         model: resolveSessionModel(sessionId),
         effort: resolveSessionEffort(sessionId),
         thinking: resolveSessionThinkingEnabled(sessionId),
@@ -1342,6 +1373,7 @@ export const chatWebSocket = {
         pendingApproval: entry.pendingApprovalEvent ?? null,
         sessionTitle: chatService.getSession(sessionId)?.title || null,
         compactStatus: entry.compactStatus ?? null,
+        mcpNeedsAuth: entry.mcpNeedsAuth ?? [],
         model: resolveSessionModel(sessionId),
         effort: resolveSessionEffort(sessionId),
         thinking: resolveSessionThinkingEnabled(sessionId),
@@ -1368,6 +1400,7 @@ export const chatWebSocket = {
         pendingApproval: entry.pendingApprovalEvent ?? null,
         sessionTitle: chatService.getSession(sessionId)?.title || null,
         compactStatus: entry.compactStatus ?? null,
+        mcpNeedsAuth: entry.mcpNeedsAuth ?? [],
         model: resolveSessionModel(sessionId),
         effort: resolveSessionEffort(sessionId),
         thinking: resolveSessionThinkingEnabled(sessionId),
@@ -1388,6 +1421,7 @@ export const chatWebSocket = {
         pendingApproval: entry.pendingApprovalEvent ?? null,
         sessionTitle: chatService.getSession(sessionId)?.title || null,
         compactStatus: entry.compactStatus ?? null,
+        mcpNeedsAuth: entry.mcpNeedsAuth ?? [],
         model: resolveSessionModel(sessionId),
         effort: resolveSessionEffort(sessionId),
         thinking: resolveSessionThinkingEnabled(sessionId),

package/src/services/mcp-oauth/mcp-control-query.ts

@@ -0,0 +1,58 @@
+import type { McpServerState } from "./mcp-oauth-redirect.ts";
+
+/**
+ * The control requests PPM sends to a prompt-less Claude subprocess.
+ *
+ * `mcpAuthenticate` and `mcpSubmitOAuthCallbackUrl` exist on the SDK's `Query` object
+ * (they are what Claude's own apps use for "Sign in") but are left out of `sdk.d.ts`,
+ * which is why they are typed here rather than imported. A test asserts they still exist
+ * so an SDK upgrade that renames them fails loudly instead of the button doing nothing.
+ */
+export interface McpControlQuery {
+  mcpServerStatus(): Promise<McpServerState[]>;
+  mcpAuthenticate(serverName: string, redirectUri?: string): Promise<McpAuthenticateResult>;
+  mcpSubmitOAuthCallbackUrl(serverName: string, callbackUrl: string): Promise<unknown>;
+  reconnectMcpServer(serverName: string): Promise<void>;
+}
+
+/** What the CLI answers to `mcp_authenticate`. */
+export interface McpAuthenticateResult {
+  authUrl?: string;
+  /** False when the server is already signed in — nothing for the user to do. */
+  requiresUserAction: boolean;
+  /**
+   * False for claude.ai connectors: the grant happens on claude.ai and nothing is ever
+   * redirected back, so completion can only be detected by reconnecting.
+   */
+  callbackExpected: boolean;
+  /** "localhost": the CLI's own listener on `callbackPort`. "custom": the redirect URI PPM passed. */
+  redirectScheme?: "localhost" | "custom";
+  callbackPort?: number;
+  state?: string;
+}
+
+export interface McpControlHandle {
+  query: McpControlQuery;
+  close(): void;
+}
+
+export type OpenMcpControlQuery = (cwd: string) => Promise<McpControlHandle>;
+
+/**
+ * A control request that never answers must not hold its subprocess (or everyone waiting
+ * on it) forever; this turns silence into an error the caller can settle on.
+ */
+export function withTimeout<T>(promise: Promise<T>, ms: number, message: string): Promise<T> {
+  let timer: ReturnType<typeof setTimeout> | undefined;
+  const timeout = new Promise<never>((_, reject) => { timer = setTimeout(() => reject(new Error(message)), ms); });
+  return Promise.race([promise, timeout]).finally(() => clearTimeout(timer));
+}
+
+/** Opens control queries through the Claude provider, configured exactly like its chats. */
+export const openClaudeMcpControlQuery: OpenMcpControlQuery = async (cwd) => {
+  // Lazy: the registry pulls in every provider, which a unit test of the flow logic must not.
+  const { providerRegistry } = await import("../../providers/registry.ts");
+  const provider = providerRegistry.get("claude") as { openMcpControlQuery?: (cwd: string) => McpControlHandle } | undefined;
+  if (!provider?.openMcpControlQuery) throw new Error("The Claude provider is not available");
+  return provider.openMcpControlQuery(cwd);
+};