@matterailab/orbcode 0.2.2 → 0.2.4

package/dist/config/settings.js

@@ -18,6 +18,8 @@ const SETTINGS_KEYS = [
     "baseUrl",
     "apiKey",
     "env",
+    "enabledMcpServers",
+    "disabledMcpServers",
 ];
 export function getConfigDir() {
     return process.env.MATTERAI_CONFIG_DIR || path.join(os.homedir(), ".orbcode");
@@ -150,6 +152,12 @@ export function loadSettings() {
         if (Array.isArray(fileSettings.customModels)) {
             customModels.push(...fileSettings.customModels);
         }
+        // MCP servers: merge across scopes (local overrides project overrides
+        // user on name collisions). The MCP config layer also reads .mcp.json;
+        // settings.json mcpServers are the per-user/per-machine override path.
+        if (fileSettings.mcpServers && typeof fileSettings.mcpServers === "object") {
+            settings.mcpServers = { ...(settings.mcpServers ?? {}), ...fileSettings.mcpServers };
+        }
     }
     if (customModels.length > 0) {
         settings.customModels = customModels;
@@ -210,3 +218,22 @@ export function saveSettings(settings) {
     };
     fs.writeFileSync(getConfigPath(), JSON.stringify(toPersist, null, "\t") + "\n", { mode: 0o600 });
 }
+/**
+ * Persist the enabled/disabled MCP server lists to the local project
+ * settings.json (`.orbcode/settings.json`). These are per-project approval
+ * decisions, so they live in the local scope, not in config.json.
+ */
+export function saveMcpApproval(cwd, enabled, disabled) {
+    const settingsPath = path.join(cwd, ".orbcode", "settings.json");
+    let existing = {};
+    try {
+        existing = JSON.parse(fs.readFileSync(settingsPath, "utf8"));
+    }
+    catch {
+        // file may not exist yet
+    }
+    existing.enabledMcpServers = [...new Set(enabled)];
+    existing.disabledMcpServers = [...new Set(disabled)];
+    fs.mkdirSync(path.dirname(settingsPath), { recursive: true });
+    fs.writeFileSync(settingsPath, JSON.stringify(existing, null, "\t") + "\n", { mode: 0o600 });
+}

package/dist/core/agent.js

@@ -9,6 +9,8 @@ import { walkFiles } from "../tools/executors/listFiles.js";
 import { previewFileChange } from "../tools/executors/files.js";
 import { getSessionFilePath, saveSession } from "./sessions.js";
 import { HookRunner } from "./hooks.js";
+import { loadMemoryFiles } from "../memory/loader.js";
+import { loadSkills } from "../skills/loader.js";
 const MAX_STEPS_PER_TURN = 50;
 const RESULT_PREVIEW_LINES = 6;
 function detectRepo(cwd) {
@@ -77,6 +79,8 @@ export class Agent {
     title = "";
     createdAt = new Date().toISOString();
     hooks;
+    /** MCP server manager (may be undefined when MCP is disabled). */
+    mcp;
     /** SessionStart fires once, lazily, before the first turn of this instance. */
     sessionStarted = false;
     /** carries SessionStart additionalContext into the first user message */
@@ -107,7 +111,16 @@ export class Agent {
             this.firstMessageSent = this.messages.length > 0;
         }
         this.sessionApproveEdits = options.autoApproveEdits;
-        this.systemPrompt = buildSystemPrompt(options.cwd);
+        this.mcp = options.mcp;
+        // Build the system prompt with AGENTS.md memory files and the skills
+        // catalog injected, so the model sees project/user instructions and
+        // knows which skills it can invoke. An explicit override (from
+        // `orbcode -s <text>`) bypasses the default entirely.
+        const memoryFiles = options.systemPromptOverride ? [] : loadMemoryFiles(options.cwd);
+        const skills = options.systemPromptOverride ? new Map() : loadSkills(options.cwd);
+        this.systemPrompt = options.systemPromptOverride
+            ? options.systemPromptOverride
+            : buildSystemPrompt(options.cwd, { memoryFiles, skills });
         this.client = createLLMClient({
             token: options.token,
             modelId: options.modelId,
@@ -353,15 +366,26 @@ User time zone: ${timeZone}, UTC${timeZoneOffsetStr}`;
     async endSession(reason) {
         // Let in-flight Notification hooks settle before the final SessionEnd.
         await this.awaitBackground(3000);
-        if (!this.hooks.hasHooks("SessionEnd"))
-            return;
+        if (this.hooks.hasHooks("SessionEnd")) {
+            try {
+                await this.hooks.run("SessionEnd", { reason });
+            }
+            catch {
+                // a SessionEnd hook must never prevent the app from exiting
+            }
+        }
+        // Tear down MCP server connections so child processes / sockets don't leak.
         try {
-            await this.hooks.run("SessionEnd", { reason });
+            await this.mcp?.stop();
         }
         catch {
-            // a SessionEnd hook must never prevent the app from exiting
+            // best-effort
         }
     }
+    /** The MCP manager (for the TUI's /mcp command and approval flow). */
+    get mcpManager() {
+        return this.mcp;
+    }
     /** Summarize the conversation so far and replace history with the summary. */
     async compact() {
         const { onEvent } = this.options.callbacks;
@@ -452,7 +476,7 @@ User time zone: ${timeZone}, UTC${timeZoneOffsetStr}`;
         let reasoningDetails;
         const toolCallsByIndex = new Map();
         let nextSyntheticIndex = 10000;
-        const stream = this.client.createMessage(this.systemPrompt, this.outgoingMessages(), getActiveTools(), signal);
+        const stream = this.client.createMessage(this.systemPrompt, this.outgoingMessages(), getActiveTools(this.mcp), signal);
         for await (const chunk of stream) {
             if (signal.aborted)
                 throw new DOMException("aborted", "AbortError");
@@ -663,7 +687,10 @@ User time zone: ${timeZone}, UTC${timeZoneOffsetStr}`;
                     this.sessionApproveCommands = true;
             }
         }
-        const result = await executeTool(toolCall.name, args, this.toolContext());
+        // Yield so the UI can paint the "Working" indicator before a
+        // potentially long synchronous tool call blocks the event loop.
+        await new Promise(resolve => setImmediate(resolve));
+        const result = await executeTool(toolCall.name, args, this.toolContext(), this.mcp);
         // PostToolUse can feed extra context (or a block reason) back to the
         // model. PreToolUse additionalContext is delivered here too.
         let resultText = result.text;

package/dist/headless.js

@@ -1,8 +1,9 @@
 import { getModel, isValidAxonModel, usesAiSdk } from "./api/models.js";
 import { getAuthToken, getPendingProjectHooks, loadSettings } from "./config/settings.js";
 import { Agent } from "./core/agent.js";
+import { McpManager } from "./mcp/manager.js";
 /** Non-interactive `orbcode -p "prompt"` mode: prints the final response to stdout. */
-export async function runHeadless(prompt, yolo) {
+export async function runHeadless(prompt, yolo, systemPromptOverride) {
     const settings = loadSettings();
     // An unknown --model (or MATTERAI_MODEL) silently resolves to the default; say
     // so on stderr instead of quietly running a different model than requested.
@@ -28,6 +29,21 @@ export async function runHeadless(prompt, yolo) {
         process.stderr.write(`note: ${pendingHooks.commands.length} project hook(s) in .orbcode/settings.json are untrusted and were skipped. ` +
             `Trust them in an interactive session, or set MATTERAI_TRUST_PROJECT_HOOKS=1.\n`);
     }
+    // Start MCP servers. In headless mode there's no interactive approval, so
+    // project-scope servers are only connected if they were previously approved
+    // (persisted in .orbcode/settings.json). Unapproved project servers are
+    // skipped with a note, matching the project-hooks behavior.
+    const mcp = new McpManager(process.cwd(), settings.disabledMcpServers ?? [], settings.enabledMcpServers ?? []);
+    const mcpSnapshot = await mcp.start();
+    const pendingMcp = mcp.getPendingApproval();
+    if (pendingMcp.length > 0) {
+        process.stderr.write(`note: ${pendingMcp.length} project MCP server(s) in .mcp.json are unapproved and were skipped. ` +
+            `Approve them in an interactive session with /mcp.\n`);
+    }
+    const connectedMcp = mcpSnapshot.servers.filter((s) => s.status === "connected").length;
+    if (connectedMcp > 0) {
+        process.stderr.write(`MCP: ${connectedMcp}/${mcpSnapshot.servers.length} server(s) connected.\n`);
+    }
     let exitCode = 0;
     // Only the final content is printed: either the attempt_completion result
     // or, failing that, the last assistant text. Intermediate text and tool
@@ -46,6 +62,8 @@ export async function runHeadless(prompt, yolo) {
         autoApproveEdits: yolo,
         autoApproveSafeCommands: yolo,
         hooks: settings.hooks,
+        mcp,
+        systemPromptOverride,
         callbacks: {
             onEvent: (event) => {
                 switch (event.type) {
@@ -84,6 +102,7 @@ export async function runHeadless(prompt, yolo) {
     });
     await agent.runTurn(prompt);
     await agent.endSession("other");
+    await mcp.stop().catch(() => { });
     const finalContent = completionResult || lastText || textBuffer;
     if (finalContent) {
         process.stdout.write(finalContent.trimEnd() + "\n");

package/dist/index.js

@@ -3,6 +3,7 @@ import { render } from "ink";
 import { PRODUCT_NAME, VERSION } from "./branding.js";
 import { App } from "./ui/App.js";
 import { runHeadless } from "./headless.js";
+import { runMcpCommand } from "./commands/mcp.js";
 import { loadSessionById } from "./core/sessions.js";
 import { clearUpdateCache, compareVersions, fetchLatestNpmVersion, getGlobalInstallRoot, getUpdateInfo, isGlobalInstall, runNpmUpdate, } from "./utils/updateCheck.js";
 const PACKAGE_NAME = "@matterailab/orbcode";
@@ -15,10 +16,16 @@ Usage:
   orbcode login           sign in to MatterAI
   orbcode update          install the latest version from npm
   orbcode update --force  force a global install even if this CLI doesn't look global
+  orbcode mcp add ...     add an MCP server (see: orbcode mcp help)
+  orbcode mcp remove ...  remove an MCP server
+  orbcode mcp list        list configured MCP servers
   orbcode -p "<prompt>"   run a single prompt non-interactively (prints only the final response)
   orbcode -p "…" --yolo   non-interactive with auto-approved edits/commands
   orbcode --model <id>    use a specific model for this run
   orbcode --resume <id>   resume a previous session by id
+  orbcode -s "<prompt>"   override the default system prompt (replaces it entirely;
+                          accepts -s <text>, --system-prompt <text>, and
+                          --system-prompt=<text> for values that start with '-')
   orbcode --version       print version
   orbcode --help          show this help
 `);
@@ -67,6 +74,33 @@ function takeFlagValue(args, name) {
     args.splice(index, 2);
     return value;
 }
+/**
+ * Pop the `-s` / `--system-prompt` flag (and its value) out of `args`.
+ * Unlike `takeFlagValue` this accepts a value that starts with `-`, because
+ * a system-prompt override is free-form text. Supports three forms:
+ *   -s "<text>"             --value in next arg
+ *   --system-prompt "<text>"
+ *   --system-prompt="<text>"
+ *   --system-prompt=-<text>
+ */
+function takeSystemPrompt(args) {
+    const longWithEq = args.findIndex((a) => a.startsWith("--system-prompt="));
+    if (longWithEq !== -1) {
+        const value = args[longWithEq].slice("--system-prompt=".length);
+        args.splice(longWithEq, 1);
+        return value.length > 0 ? value : undefined;
+    }
+    const index = args.findIndex((a) => a === "-s" || a === "--system-prompt");
+    if (index === -1)
+        return undefined;
+    const value = args[index + 1];
+    if (value === undefined) {
+        console.error("Missing value after -s / --system-prompt");
+        process.exit(1);
+    }
+    args.splice(index, 2);
+    return value;
+}
 async function main() {
     // Override Node's default process title so terminals (iTerm2 "current job
     // name", VSCode terminal status, etc.) don't append " (node)" next to our
@@ -86,6 +120,11 @@ async function main() {
         const code = await runUpdate(force);
         process.exit(code);
     }
+    // `orbcode mcp ...` — manage MCP servers from the command line (add/remove/list).
+    if (args[0] === "mcp") {
+        const code = await runMcpCommand(args.slice(1));
+        process.exit(code);
+    }
     const model = takeFlagValue(args, "model") ?? takeFlagValue(args, "m");
     if (model) {
         // loadSettings() treats MATTERAI_MODEL as the highest-precedence override,
@@ -101,6 +140,10 @@ async function main() {
             process.exit(1);
         }
     }
+    // `-s` / `--system-prompt` lets the user replace the default prompt
+    // entirely. Accepts values starting with `-` (unlike other flags), so
+    // `orbcode -s '- you are a code reviewer'` works.
+    const systemPromptOverride = takeSystemPrompt(args);
     const printIndex = args.findIndex((a) => a === "-p" || a === "--print");
     if (printIndex !== -1) {
         const prompt = args[printIndex + 1];
@@ -108,7 +151,7 @@ async function main() {
             console.error("Missing prompt after -p");
             process.exit(1);
         }
-        await runHeadless(prompt, args.includes("--yolo"));
+        await runHeadless(prompt, args.includes("--yolo"), systemPromptOverride);
         return;
     }
     const initialView = args[0] === "login" ? "login" : undefined;
@@ -123,7 +166,7 @@ async function main() {
     // Fire-and-forget: a stale or no-network state just means the header shows
     // the "current version" line instead of an upgrade prompt.
     const updateCheckPromise = getUpdateInfo(PACKAGE_NAME, VERSION);
-    render(_jsx(App, { initialView: initialView, initialPrompt: initialPrompt, initialSession: initialSession, updateCheck: updateCheckPromise }));
+    render(_jsx(App, { initialView: initialView, initialPrompt: initialPrompt, initialSession: initialSession, systemPromptOverride: systemPromptOverride, updateCheck: updateCheckPromise }));
 }
 main().catch((error) => {
     console.error(error);

package/dist/mcp/auth.js

@@ -0,0 +1,289 @@
+import * as http from "node:http";
+import * as fs from "node:fs";
+import * as path from "node:path";
+import open from "open";
+import { ClientCredentialsProvider, PrivateKeyJwtProvider, } from "@modelcontextprotocol/sdk/client/auth-extensions.js";
+import { auth, } from "@modelcontextprotocol/sdk/client/auth.js";
+import { StreamableHTTPClientTransport } from "@modelcontextprotocol/sdk/client/streamableHttp.js";
+import { SSEClientTransport } from "@modelcontextprotocol/sdk/client/sse.js";
+import { getConfigDir } from "../config/settings.js";
+/**
+ * MCP OAuth support.
+ *
+ * Remote MCP servers (http/sse) often require OAuth. The SDK ships a full
+ * OAuth client (RFC 9728 discovery + RFC 8414 metadata + PKCE + dynamic client
+ * registration + token refresh), gated behind an `OAuthClientProvider` that
+ * persists per-server state. This module provides:
+ *
+ *   - `FileOAuthProvider`: a filesystem-backed provider that stores tokens,
+ *     client info, code verifiers, and discovery state per server under
+ *     `~/.orbcode/mcp-auth/<server>.json`.
+ *   - `startCallbackServer`: a one-shot loopback HTTP server that receives the
+ *     OAuth redirect and resolves with the authorization code.
+ *   - `buildAuthProvider`: turns an `McpOAuthConfig` into an `OAuthClientProvider`
+ *     (interactive auth-code flow, or M2M client_credentials / private_key_jwt).
+ *   - `connectWithAuth`: wraps the transport connect + auth retry loop.
+ */
+const CLIENT_METADATA = {
+    client_name: "OrbCode CLI",
+    redirect_uris: [], // filled in per-callback-port at runtime
+    grant_types: ["authorization_code", "refresh_token"],
+    token_endpoint_auth_method: "none",
+    scope: "",
+};
+/** Directory holding per-server OAuth state files. */
+function authDir() {
+    return path.join(getConfigDir(), "mcp-auth");
+}
+/** Path to a server's persistent OAuth store. */
+function authFilePath(serverName) {
+    return path.join(authDir(), `${serverName}.json`);
+}
+/** Read a server's OAuth store (or undefined if none). */
+function readAuthStore(serverName) {
+    try {
+        return JSON.parse(fs.readFileSync(authFilePath(serverName), "utf8"));
+    }
+    catch {
+        return undefined;
+    }
+}
+/** Write a server's OAuth store (best-effort). */
+function writeAuthStore(serverName, store) {
+    try {
+        fs.mkdirSync(authDir(), { recursive: true });
+        fs.writeFileSync(authFilePath(serverName), JSON.stringify(store, null, "\t") + "\n", {
+            mode: 0o600,
+        });
+    }
+    catch {
+        // best-effort; auth will just re-prompt next time
+    }
+}
+/** A filesystem-backed OAuthClientProvider for one MCP server. */
+class FileOAuthProvider {
+    serverName;
+    callbackPort;
+    scope;
+    store;
+    /** The authorization URL captured from the last redirectToAuthorization call. */
+    authUrl;
+    /** Resolved by redirectToAuthorization; awaited by the connect loop. */
+    codeResolve;
+    constructor(serverName, callbackPort, scope) {
+        this.serverName = serverName;
+        this.callbackPort = callbackPort;
+        this.scope = scope;
+        this.store = readAuthStore(serverName) ?? {};
+    }
+    get redirectUrl() {
+        return `http://localhost:${this.callbackPort}/callback`;
+    }
+    get clientMetadata() {
+        return { ...CLIENT_METADATA, redirect_uris: [this.redirectUrl], scope: this.scope ?? "" };
+    }
+    clientInformation() {
+        return this.store.clientInformation;
+    }
+    saveClientInformation(info) {
+        this.store.clientInformation = info;
+        writeAuthStore(this.serverName, this.store);
+    }
+    tokens() {
+        return this.store.tokens;
+    }
+    saveTokens(tokens) {
+        this.store.tokens = tokens;
+        writeAuthStore(this.serverName, this.store);
+    }
+    saveCodeVerifier(verifier) {
+        this.store.codeVerifier = verifier;
+        writeAuthStore(this.serverName, this.store);
+    }
+    codeVerifier() {
+        if (!this.store.codeVerifier)
+            throw new Error("No PKCE code verifier stored.");
+        return this.store.codeVerifier;
+    }
+    saveDiscoveryState(state) {
+        this.store.discoveryState = state;
+        writeAuthStore(this.serverName, this.store);
+    }
+    discoveryState() {
+        return this.store.discoveryState;
+    }
+    invalidateCredentials(scope) {
+        if (scope === "all")
+            this.store = {};
+        else if (scope === "client")
+            delete this.store.clientInformation;
+        else if (scope === "tokens")
+            delete this.store.tokens;
+        else if (scope === "verifier")
+            delete this.store.codeVerifier;
+        else if (scope === "discovery")
+            delete this.store.discoveryState;
+        writeAuthStore(this.serverName, this.store);
+    }
+    /** Open the user's browser to the authorization URL and capture it so the
+     *  caller can surface it in the TUI (with copy + paste fallback). */
+    redirectToAuthorization(authorizationUrl) {
+        this.authUrl = authorizationUrl.toString();
+        void open(this.authUrl).catch(() => {
+            // best-effort; the user can copy the URL from the TUI
+        });
+    }
+    /** The authorization URL captured from the last redirect (for TUI display). */
+    getAuthUrl() {
+        return this.authUrl;
+    }
+    /** Called by the callback server when the OAuth redirect lands. */
+    resolveCode(code) {
+        this.codeResolve?.(code);
+    }
+    /** Await the authorization code from the browser redirect or a manual paste. */
+    waitForCode() {
+        return new Promise((resolve) => {
+            this.codeResolve = resolve;
+        });
+    }
+}
+/** Start a one-shot loopback HTTP server to receive the OAuth redirect. */
+function startCallbackServer(port, onCode) {
+    const server = http.createServer((req, res) => {
+        const url = new URL(req.url ?? "/", `http://localhost:${port}`);
+        if (url.pathname !== "/callback") {
+            res.writeHead(404).end("not found");
+            return;
+        }
+        const code = url.searchParams.get("code");
+        const error = url.searchParams.get("error");
+        if (code) {
+            onCode(code);
+            res.writeHead(200, { "Content-Type": "text/html" });
+            res.end("<h1>Authorized</h1><p>You can close this tab and return to OrbCode.</p>");
+        }
+        else if (error) {
+            res.writeHead(400, { "Content-Type": "text/html" });
+            res.end(`<h1>Authorization failed</h1><p>${error}</p>`);
+        }
+        else {
+            res.writeHead(400, { "Content-Type": "text/html" });
+            res.end("<h1>Missing code</h1>");
+        }
+        // Close after responding so the port is freed immediately.
+        server.close();
+    });
+    server.listen(port, "127.0.0.1");
+    return server;
+}
+/** Pick an ephemeral loopback port for the callback server. */
+function ephemeralPort() {
+    // Bind to port 0 and read back the assigned port, then close immediately.
+    const probe = http.createServer().listen(0, "127.0.0.1");
+    const addr = probe.address();
+    probe.close();
+    return typeof addr === "object" && addr ? addr.port : 8765;
+}
+/** Build an OAuthClientProvider from an McpOAuthConfig. Returns the provider
+ *  plus a callback-port hint (for the interactive flow). */
+export function buildAuthProvider(serverName, oauth) {
+    // M2M: client_credentials grant (no browser).
+    if (typeof oauth === "object" && "grantType" in oauth && oauth.grantType === "client_credentials") {
+        return {
+            provider: new ClientCredentialsProvider({
+                clientId: oauth.clientId,
+                clientSecret: oauth.clientSecret,
+                scope: oauth.scope,
+                clientName: "OrbCode CLI",
+            }),
+        };
+    }
+    // M2M: private_key_jwt assertion (no browser).
+    if (typeof oauth === "object" && "grantType" in oauth && oauth.grantType === "private_key_jwt") {
+        return {
+            provider: new PrivateKeyJwtProvider({
+                clientId: oauth.clientId,
+                privateKey: oauth.privateKey,
+                algorithm: oauth.algorithm,
+                scope: oauth.scope,
+                clientName: "OrbCode CLI",
+            }),
+        };
+    }
+    // Interactive authorization-code flow (browser redirect).
+    const scope = typeof oauth === "object" ? oauth.scope : undefined;
+    const port = ephemeralPort();
+    return { provider: new FileOAuthProvider(serverName, port, scope), callbackPort: port };
+}
+/** True if the config requests OAuth (vs. static headers). */
+export function hasOAuth(config) {
+    return config.oauth !== undefined && config.oauth !== false;
+}
+/** True if a server config is http/sse with OAuth enabled. */
+export function isOAuthConfig(config) {
+    return (config.type === "http" || config.type === "sse") && hasOAuth(config);
+}
+/** True if this server has persisted OAuth tokens (i.e. already authenticated). */
+export function hasStoredAuth(serverName) {
+    const store = readAuthStore(serverName);
+    return Boolean(store && store.tokens && store.tokens.access_token);
+}
+/** Create an http/sse transport with an auth provider. The `authenticate()`
+ *  function uses the standalone `auth()` orchestrator to obtain tokens BEFORE
+ *  the transport is started (by client.connect()). This avoids the
+ *  "StreamableHTTPClientTransport already started" error that occurs when
+ *  transport.start() is called both by authenticate() and by client.connect().
+ *
+ *  When `intercept` is provided, the caller controls how the auth URL is shown
+ *  and how the code is obtained (TUI with copy + paste fallback). When omitted,
+ *  the flow auto-waits for the loopback callback server (headless mode). */
+export function createAuthTransport(serverName, url, kind, oauth, requestInit, intercept) {
+    const { provider, callbackPort } = buildAuthProvider(serverName, oauth);
+    const fileProvider = provider instanceof FileOAuthProvider ? provider : undefined;
+    const transport = kind === "http"
+        ? new StreamableHTTPClientTransport(url, { authProvider: provider, requestInit })
+        : new SSEClientTransport(url, { authProvider: provider, requestInit });
+    const authenticate = async () => {
+        // M2M providers (ClientCredentialsProvider, PrivateKeyJwtProvider) don't
+        // need a browser — the auth() call handles token acquisition directly.
+        if (!fileProvider) {
+            const result = await auth(provider, { serverUrl: url });
+            if (result === "REDIRECT") {
+                throw new Error("M2M provider requested a browser redirect — unexpected.");
+            }
+            return;
+        }
+        // Interactive flow: use the standalone auth() orchestrator.
+        // If we already have valid tokens, auth() returns AUTHORIZED immediately.
+        // If not, it returns REDIRECT (after calling redirectToAuthorization,
+        // which opens the browser and captures the URL).
+        const serverUrlStr = url.toString();
+        const result = await auth(provider, { serverUrl: serverUrlStr });
+        if (result === "AUTHORIZED")
+            return; // tokens are valid
+        // REDIRECT: the provider's redirectToAuthorization was called, which
+        // captured the auth URL and opened the browser. Surface it to the TUI.
+        const authUrl = fileProvider.getAuthUrl();
+        if (intercept && authUrl)
+            intercept.onAuthUrl(authUrl);
+        // Start the callback server (the browser redirect may arrive here).
+        const callbackServer = startCallbackServer(callbackPort, (code) => fileProvider.resolveCode(code));
+        try {
+            let code;
+            if (intercept) {
+                // Interactive: race the callback against a manual paste.
+                code = await Promise.race([intercept.getCode(), fileProvider.waitForCode()]);
+            }
+            else {
+                code = await fileProvider.waitForCode();
+            }
+            // Exchange the code for tokens via the standalone auth() call.
+            await auth(provider, { serverUrl: serverUrlStr, authorizationCode: code });
+        }
+        finally {
+            callbackServer.close();
+        }
+    };
+    return { transport, authenticate, provider: fileProvider };
+}