@zhijiewang/openharness 2.11.0 → 2.13.0

package/dist/harness/submit-handler.js

@@ -6,6 +6,7 @@ import { processSlashCommand } from "../commands/index.js";
 import { cybergotchiEvents } from "../cybergotchi/events.js";
 import { resolveMcpMention } from "../mcp/loader.js";
 import { createInfoMessage, createUserMessage } from "../types/message.js";
+import { emitHookWithOutcome } from "./hooks.js";
 /**
  * Process user input: handle exit, companion mentions, slash commands,
  * @mentions, and prepare the prompt for the LLM.
@@ -58,7 +59,7 @@ export async function handleUserInput(input, ctx) {
             totalOutputTokens: ctx.cost.totalOutputTokens,
             sessionId: ctx.sessionId,
         };
-        const result = processSlashCommand(trimmed, cmdCtx);
+        const result = await processSlashCommand(trimmed, cmdCtx);
         if (result) {
             if (result.clearMessages)
                 messages = [];
@@ -78,10 +79,28 @@ export async function handleUserInput(input, ctx) {
             }
             if (result.prependToPrompt) {
                 messages = [...messages, createUserMessage(input)];
+                const prependPrompt = result.prependToPrompt;
+                const prependOutcome = await emitHookWithOutcome("userPromptSubmit", {
+                    prompt: prependPrompt,
+                    sessionId: ctx.sessionId,
+                    model: ctx.currentModel,
+                    provider: ctx.providerName,
+                    permissionMode: ctx.permissionMode,
+                });
+                if (!prependOutcome.allowed) {
+                    const reason = prependOutcome.reason ? `: ${prependOutcome.reason}` : "";
+                    return {
+                        handled: true,
+                        messages: [...messages, createInfoMessage(`Blocked by userPromptSubmit hook${reason}`)],
+                    };
+                }
+                const finalPrependPrompt = prependOutcome.additionalContext
+                    ? `${prependOutcome.additionalContext}\n\n${prependPrompt}`
+                    : prependPrompt;
                 return {
                     handled: false,
                     messages,
-                    prompt: result.prependToPrompt,
+                    prompt: finalPrependPrompt,
                     newModel: result.newModel ?? undefined,
                 };
             }
@@ -136,6 +155,21 @@ export async function handleUserInput(input, ctx) {
             /* ignore */
         }
     }
-    return { handled: false, messages, prompt: resolvedInput };
+    const outcome = await emitHookWithOutcome("userPromptSubmit", {
+        prompt: resolvedInput,
+        sessionId: ctx.sessionId,
+        model: ctx.currentModel,
+        provider: ctx.providerName,
+        permissionMode: ctx.permissionMode,
+    });
+    if (!outcome.allowed) {
+        const reason = outcome.reason ? `: ${outcome.reason}` : "";
+        return {
+            handled: true,
+            messages: [...messages, createInfoMessage(`Blocked by userPromptSubmit hook${reason}`)],
+        };
+    }
+    const finalPrompt = outcome.additionalContext ? `${outcome.additionalContext}\n\n${resolvedInput}` : resolvedInput;
+    return { handled: false, messages, prompt: finalPrompt };
 }
 //# sourceMappingURL=submit-handler.js.map

package/dist/mcp/client.d.ts

@@ -16,7 +16,11 @@ export declare class McpClient {
     private timeoutMs;
     private reconnectImpl;
     private constructor();
-    static connect(cfg: McpServerConfig, timeoutMs?: number): Promise<McpClient>;
+    static connect(cfg: McpServerConfig, timeoutMsOrOpts?: number | {
+        timeoutMs?: number;
+        openFn?: (url: string) => Promise<void>;
+        storageDir?: string;
+    } | undefined): Promise<McpClient>;
     /** Test-only constructor. Not exported from the package's public API. */
     static _forTesting(opts: ForTestingOptions): McpClient;
     private defaultReconnect;

package/dist/mcp/client.js

@@ -1,5 +1,12 @@
+import { homedir } from "node:os";
+import { join } from "node:path";
+import open from "open";
 import { normalizeMcpConfig } from "./config-normalize.js";
+import { buildAuthProvider } from "./oauth.js";
 import { buildClient, connectWithFallback } from "./transport.js";
+function credentialsDir() {
+    return join(homedir(), ".oh", "credentials", "mcp");
+}
 const DEFAULT_TIMEOUT_MS = 5_000;
 export class McpClient {
     name;
@@ -19,13 +26,29 @@ export class McpClient {
             this.instructions = instr;
         }
     }
-    static async connect(cfg, timeoutMs = cfg.timeout ?? DEFAULT_TIMEOUT_MS) {
+    static async connect(cfg, timeoutMsOrOpts = undefined) {
+        // Backward-compatible: accept number for timeout OR options object
+        const opts = typeof timeoutMsOrOpts === "number" ? { timeoutMs: timeoutMsOrOpts } : (timeoutMsOrOpts ?? {});
+        const timeoutMs = opts.timeoutMs ?? cfg.timeout ?? DEFAULT_TIMEOUT_MS;
+        const openFn = opts.openFn ??
+            (async (url) => {
+                await open(url);
+            });
+        const storageDirResolved = opts.storageDir ?? credentialsDir();
         const normalized = normalizeMcpConfig(cfg, process.env);
         if (normalized.kind === "error") {
             throw new Error(normalized.message);
         }
-        const sdk = await connectWithFallback(normalized.cfg, (c) => buildClient(c));
-        return new McpClient(cfg.name, cfg, sdk, timeoutMs);
+        const authProvider = buildAuthProvider(normalized.cfg, storageDirResolved, openFn);
+        if (authProvider)
+            await authProvider.ready();
+        try {
+            const sdk = await connectWithFallback(normalized.cfg, (c) => buildClient(c, { authProvider }));
+            return new McpClient(cfg.name, cfg, sdk, timeoutMs);
+        }
+        finally {
+            authProvider?.close();
+        }
     }
     /** Test-only constructor. Not exported from the package's public API. */
     static _forTesting(opts) {
@@ -35,7 +58,17 @@ export class McpClient {
         const normalized = normalizeMcpConfig(this.cfg, process.env);
         if (normalized.kind === "error")
             throw new Error(normalized.message);
-        return connectWithFallback(normalized.cfg, (c) => buildClient(c));
+        const authProvider = buildAuthProvider(normalized.cfg, credentialsDir(), async (url) => {
+            await open(url);
+        });
+        if (authProvider)
+            await authProvider.ready();
+        try {
+            return await connectWithFallback(normalized.cfg, (c) => buildClient(c, { authProvider }));
+        }
+        finally {
+            authProvider?.close();
+        }
     }
     async listTools() {
         const res = await this.sdk.listTools();

package/dist/mcp/oauth-storage.d.ts

@@ -0,0 +1,23 @@
+export type OhCredentials = {
+    issuerUrl: string;
+    clientInformation: {
+        client_id: string;
+        client_secret?: string;
+    } & Record<string, unknown>;
+    tokens: {
+        access_token: string;
+        refresh_token?: string;
+        expires_at?: number;
+        token_type?: string;
+        scope?: string;
+    };
+    codeVerifier?: string;
+    updatedAt: string;
+};
+/** Atomically write credentials for one server. Creates the directory with 0o700 on first use. */
+export declare function saveCredentials(storageDir: string, name: string, creds: OhCredentials): Promise<void>;
+/** Load credentials. Returns undefined on missing file OR corrupt JSON. Warns on world/group-readable mode. */
+export declare function loadCredentials(storageDir: string, name: string): Promise<OhCredentials | undefined>;
+/** Idempotent delete — ENOENT is swallowed. */
+export declare function deleteCredentials(storageDir: string, name: string): Promise<void>;
+//# sourceMappingURL=oauth-storage.d.ts.map

package/dist/mcp/oauth-storage.js

@@ -0,0 +1,58 @@
+import { promises as fs } from "node:fs";
+import { dirname, join } from "node:path";
+function pathFor(storageDir, name) {
+    return join(storageDir, `${name}.json`);
+}
+/** Atomically write credentials for one server. Creates the directory with 0o700 on first use. */
+export async function saveCredentials(storageDir, name, creds) {
+    const filePath = pathFor(storageDir, name);
+    const tmpPath = `${filePath}.tmp`;
+    await fs.mkdir(dirname(filePath), { recursive: true, mode: 0o700 });
+    const body = JSON.stringify(creds, null, 2);
+    await fs.writeFile(tmpPath, body, { mode: 0o600 });
+    await fs.rename(tmpPath, filePath);
+}
+/** Load credentials. Returns undefined on missing file OR corrupt JSON. Warns on world/group-readable mode. */
+export async function loadCredentials(storageDir, name) {
+    const filePath = pathFor(storageDir, name);
+    let raw;
+    try {
+        raw = await fs.readFile(filePath, "utf8");
+    }
+    catch (err) {
+        if (err.code === "ENOENT")
+            return undefined;
+        throw err;
+    }
+    try {
+        if (process.platform !== "win32") {
+            const s = await fs.stat(filePath);
+            if ((s.mode & 0o077) !== 0) {
+                console.warn(`[mcp] credentials file for '${name}' is world/group-readable; run 'chmod 600 ${filePath}'`);
+            }
+        }
+    }
+    catch {
+        // stat failure is non-fatal for load
+    }
+    try {
+        return JSON.parse(raw);
+    }
+    catch {
+        console.warn(`[mcp] credentials file for '${name}' is corrupt; ignoring`);
+        return undefined;
+    }
+}
+/** Idempotent delete — ENOENT is swallowed. */
+export async function deleteCredentials(storageDir, name) {
+    const filePath = pathFor(storageDir, name);
+    try {
+        await fs.unlink(filePath);
+    }
+    catch (err) {
+        if (err.code === "ENOENT")
+            return;
+        throw err;
+    }
+}
+//# sourceMappingURL=oauth-storage.js.map

package/dist/mcp/oauth.d.ts

@@ -0,0 +1,79 @@
+import type { OAuthClientProvider } from "@modelcontextprotocol/sdk/client/auth.js";
+import type { OAuthClientInformationMixed, OAuthClientMetadata, OAuthTokens } from "@modelcontextprotocol/sdk/shared/auth.js";
+import type { NormalizedConfig } from "./config-normalize.js";
+/** Thrown when the OAuth callback flow fails — user cancelled, timeout, state mismatch, etc. */
+export declare class OAuthFlowError extends Error {
+    readonly serverName: string;
+    constructor(serverName: string, reason: string);
+}
+export type OAuthCallbackResult = {
+    code: string;
+    state: string;
+};
+export type PendingCallback = {
+    /** The full redirect URI clients should be sent to. */
+    readonly redirectUri: string;
+    /** Resolves with the captured code+state; rejects on timeout or close. */
+    readonly done: Promise<OAuthCallbackResult>;
+    /** Close the listener immediately. Idempotent. */
+    close: () => void;
+};
+/**
+ * Bind a single-shot HTTP listener on 127.0.0.1 to receive the OAuth redirect.
+ * Returns after the server has bound (so redirectUri is available synchronously on the result).
+ * The `done` promise resolves when a valid /oauth/callback arrives, or rejects on timeout/close.
+ */
+export declare function awaitOAuthCallback(opts: {
+    timeoutMs: number;
+}): Promise<PendingCallback>;
+/** Strip access_token=, refresh_token=, and "Bearer <x>" from a log message. */
+export declare function redactToken(msg: string): string;
+export type OhOAuthProviderOptions = {
+    name: string;
+    storageDir: string;
+    /** Browser launch hook — injected for tests; production wires to `open` from the npm package. */
+    openFn: (url: string) => Promise<void>;
+};
+/**
+ * Implements the SDK's OAuthClientProvider backed by OhCredentials on disk.
+ * Lazily binds the callback listener on ready() (called before the SDK reads redirectUrl).
+ */
+export declare class OhOAuthProvider implements OAuthClientProvider {
+    private readonly name;
+    private readonly storageDir;
+    private readonly openFn;
+    private pending;
+    private _redirectUri;
+    private inMemoryCodeVerifier;
+    constructor(opts: OhOAuthProviderOptions);
+    /** Bind the callback listener and prepare redirectUri. Call before first SDK access. */
+    ready(): Promise<void>;
+    /** Release the callback listener (no-op if already resolved/closed). */
+    close(): void;
+    get redirectUrl(): string | URL | undefined;
+    get clientMetadata(): OAuthClientMetadata;
+    clientInformation(): Promise<OAuthClientInformationMixed | undefined>;
+    saveClientInformation(info: OAuthClientInformationMixed): Promise<void>;
+    tokens(): Promise<OAuthTokens | undefined>;
+    saveTokens(tokens: OAuthTokens): Promise<void>;
+    redirectToAuthorization(url: URL): Promise<void>;
+    saveCodeVerifier(verifier: string): Promise<void>;
+    codeVerifier(): Promise<string>;
+    /** Await a resolved callback from the listener bound in ready(). */
+    awaitCallback(): Promise<OAuthCallbackResult>;
+    private emptyCreds;
+}
+export type AuthStatus = "n/a" | "none" | "authenticated" | "expired";
+/**
+ * Construct an OAuth provider for a normalized config, iff:
+ * - type is http or sse
+ * - no static headers.Authorization
+ * - auth !== "none"
+ * Otherwise return undefined — the transport proceeds without OAuth.
+ */
+export declare function buildAuthProvider(cfg: NormalizedConfig, storageDir: string, openFn: (url: string) => Promise<void>): OhOAuthProvider | undefined;
+/** Delete stored credentials for a server. Safe to call when none exist. */
+export declare function clearTokens(storageDir: string, name: string): Promise<void>;
+/** Compute auth state for a server for /mcp display. */
+export declare function getAuthStatus(cfg: NormalizedConfig, storageDir: string): Promise<AuthStatus>;
+//# sourceMappingURL=oauth.d.ts.map

package/dist/mcp/oauth.js

@@ -0,0 +1,257 @@
+import { createServer } from "node:http";
+import { deleteCredentials, loadCredentials, saveCredentials } from "./oauth-storage.js";
+/** Thrown when the OAuth callback flow fails — user cancelled, timeout, state mismatch, etc. */
+export class OAuthFlowError extends Error {
+    serverName;
+    constructor(serverName, reason) {
+        super(`OAuth flow for '${serverName}' failed: ${reason}`);
+        this.name = "OAuthFlowError";
+        this.serverName = serverName;
+    }
+}
+const SUCCESS_HTML = `<!doctype html><html><body style="font-family: system-ui; padding: 2rem">
+<h2>Authorization complete</h2>
+<p>You can close this tab and return to openHarness.</p>
+</body></html>`;
+/**
+ * Bind a single-shot HTTP listener on 127.0.0.1 to receive the OAuth redirect.
+ * Returns after the server has bound (so redirectUri is available synchronously on the result).
+ * The `done` promise resolves when a valid /oauth/callback arrives, or rejects on timeout/close.
+ */
+export async function awaitOAuthCallback(opts) {
+    const server = createServer();
+    await new Promise((resolve, reject) => {
+        server.once("listening", () => resolve());
+        server.once("error", reject);
+        server.listen(0, "127.0.0.1");
+    });
+    const addr = server.address();
+    const redirectUri = `http://127.0.0.1:${addr.port}/oauth/callback`;
+    let closed = false;
+    let timer = null;
+    let resolveResult;
+    let rejectResult;
+    const done = new Promise((res, rej) => {
+        resolveResult = res;
+        rejectResult = rej;
+    });
+    function cleanup() {
+        if (closed)
+            return;
+        closed = true;
+        if (timer)
+            clearTimeout(timer);
+        timer = null;
+        server.close();
+    }
+    server.on("request", (req, res) => {
+        const host = req.headers.host ?? "";
+        if (!host.startsWith("127.0.0.1:")) {
+            res.statusCode = 403;
+            res.end("forbidden");
+            return;
+        }
+        const url = new URL(req.url ?? "/", `http://${host}`);
+        if (req.method !== "GET" || url.pathname !== "/oauth/callback") {
+            res.statusCode = 404;
+            res.end("not found");
+            return;
+        }
+        const code = url.searchParams.get("code") ?? "";
+        const state = url.searchParams.get("state") ?? "";
+        res.statusCode = 200;
+        res.setHeader("content-type", "text/html; charset=utf-8");
+        res.end(SUCCESS_HTML, () => {
+            cleanup();
+            resolveResult({ code, state });
+        });
+    });
+    timer = setTimeout(() => {
+        cleanup();
+        rejectResult(new Error(`OAuth callback timeout after ${opts.timeoutMs}ms`));
+    }, opts.timeoutMs);
+    return {
+        redirectUri,
+        done,
+        close: () => {
+            if (closed)
+                return;
+            cleanup();
+            rejectResult(new Error("OAuth callback closed before completion"));
+        },
+    };
+}
+/** Strip access_token=, refresh_token=, and "Bearer <x>" from a log message. */
+export function redactToken(msg) {
+    return msg
+        .replace(/(access_token|refresh_token|code)=[^&\s"']+/gi, "$1=<redacted>")
+        .replace(/Bearer\s+[^\s"']+/gi, "Bearer <redacted>");
+}
+const CALLBACK_TIMEOUT_MS = 5 * 60 * 1_000;
+/**
+ * Implements the SDK's OAuthClientProvider backed by OhCredentials on disk.
+ * Lazily binds the callback listener on ready() (called before the SDK reads redirectUrl).
+ */
+export class OhOAuthProvider {
+    name;
+    storageDir;
+    openFn;
+    pending = null;
+    _redirectUri = null;
+    inMemoryCodeVerifier = null;
+    constructor(opts) {
+        this.name = opts.name;
+        this.storageDir = opts.storageDir;
+        this.openFn = opts.openFn;
+    }
+    /** Bind the callback listener and prepare redirectUri. Call before first SDK access. */
+    async ready() {
+        if (this.pending)
+            return;
+        this.pending = await awaitOAuthCallback({ timeoutMs: CALLBACK_TIMEOUT_MS });
+        this._redirectUri = this.pending.redirectUri;
+    }
+    /** Release the callback listener (no-op if already resolved/closed). */
+    close() {
+        if (this.pending) {
+            // Attach a no-op catch so the rejected `done` promise doesn't become an unhandled rejection.
+            this.pending.done.catch(() => { });
+            this.pending.close();
+        }
+        this.pending = null;
+        this._redirectUri = null;
+    }
+    get redirectUrl() {
+        return this._redirectUri ?? undefined;
+    }
+    get clientMetadata() {
+        return {
+            client_name: "openharness",
+            redirect_uris: this._redirectUri ? [this._redirectUri] : [],
+            grant_types: ["authorization_code", "refresh_token"],
+            response_types: ["code"],
+            token_endpoint_auth_method: "none",
+        };
+    }
+    async clientInformation() {
+        const creds = await loadCredentials(this.storageDir, this.name);
+        return creds?.clientInformation;
+    }
+    async saveClientInformation(info) {
+        const creds = (await loadCredentials(this.storageDir, this.name)) ?? this.emptyCreds();
+        creds.clientInformation = info;
+        creds.updatedAt = new Date().toISOString();
+        await saveCredentials(this.storageDir, this.name, creds);
+    }
+    async tokens() {
+        const creds = await loadCredentials(this.storageDir, this.name);
+        if (!creds?.tokens?.access_token)
+            return undefined;
+        return {
+            access_token: creds.tokens.access_token,
+            refresh_token: creds.tokens.refresh_token,
+            token_type: creds.tokens.token_type ?? "Bearer",
+            scope: creds.tokens.scope,
+            expires_in: creds.tokens.expires_at && creds.tokens.expires_at > Date.now()
+                ? Math.floor((creds.tokens.expires_at - Date.now()) / 1000)
+                : 0,
+        };
+    }
+    async saveTokens(tokens) {
+        const creds = (await loadCredentials(this.storageDir, this.name)) ?? this.emptyCreds();
+        creds.tokens = {
+            access_token: tokens.access_token,
+            refresh_token: tokens.refresh_token,
+            token_type: tokens.token_type ?? "Bearer",
+            scope: tokens.scope,
+            expires_at: tokens.expires_in ? Date.now() + Number(tokens.expires_in) * 1000 : undefined,
+        };
+        creds.codeVerifier = undefined;
+        this.inMemoryCodeVerifier = null;
+        creds.updatedAt = new Date().toISOString();
+        await saveCredentials(this.storageDir, this.name, creds);
+    }
+    async redirectToAuthorization(url) {
+        const urlStr = url.toString();
+        try {
+            await this.openFn(urlStr);
+            console.warn(`[mcp] ${this.name}: opened browser for OAuth authorization. Waiting for callback...`);
+        }
+        catch (_err) {
+            console.warn(`[mcp] ${this.name}: could not open browser automatically. Please open this URL manually:\n  ${urlStr}`);
+            // Don't re-throw — the listener may still receive the callback if the user opens the URL by hand.
+        }
+    }
+    async saveCodeVerifier(verifier) {
+        this.inMemoryCodeVerifier = verifier;
+        const creds = (await loadCredentials(this.storageDir, this.name)) ?? this.emptyCreds();
+        creds.codeVerifier = verifier;
+        creds.updatedAt = new Date().toISOString();
+        await saveCredentials(this.storageDir, this.name, creds);
+    }
+    async codeVerifier() {
+        if (this.inMemoryCodeVerifier)
+            return this.inMemoryCodeVerifier;
+        const creds = await loadCredentials(this.storageDir, this.name);
+        if (!creds?.codeVerifier) {
+            throw new Error(`no code verifier saved for '${this.name}'`);
+        }
+        return creds.codeVerifier;
+    }
+    /** Await a resolved callback from the listener bound in ready(). */
+    async awaitCallback() {
+        if (!this.pending)
+            throw new Error("awaitCallback called before ready()");
+        try {
+            return await this.pending.done;
+        }
+        catch (err) {
+            const msg = err instanceof Error ? err.message : String(err);
+            throw new OAuthFlowError(this.name, msg);
+        }
+    }
+    emptyCreds() {
+        return {
+            issuerUrl: "",
+            clientInformation: { client_id: "" },
+            tokens: { access_token: "" },
+            updatedAt: new Date().toISOString(),
+        };
+    }
+}
+/**
+ * Construct an OAuth provider for a normalized config, iff:
+ * - type is http or sse
+ * - no static headers.Authorization
+ * - auth !== "none"
+ * Otherwise return undefined — the transport proceeds without OAuth.
+ */
+export function buildAuthProvider(cfg, storageDir, openFn) {
+    if (cfg.type === "stdio")
+        return undefined;
+    const headers = cfg.headers;
+    if (headers?.Authorization)
+        return undefined;
+    if (cfg.auth === "none")
+        return undefined;
+    return new OhOAuthProvider({ name: cfg.name, storageDir, openFn });
+}
+/** Delete stored credentials for a server. Safe to call when none exist. */
+export async function clearTokens(storageDir, name) {
+    await deleteCredentials(storageDir, name);
+}
+/** Compute auth state for a server for /mcp display. */
+export async function getAuthStatus(cfg, storageDir) {
+    if (cfg.type === "stdio")
+        return "n/a";
+    const headers = cfg.headers;
+    if (headers?.Authorization)
+        return "n/a";
+    const creds = await loadCredentials(storageDir, cfg.name);
+    if (!creds?.tokens?.access_token)
+        return "none";
+    if (creds.tokens.expires_at && creds.tokens.expires_at <= Date.now())
+        return "expired";
+    return "authenticated";
+}
+//# sourceMappingURL=oauth.js.map

package/dist/mcp/transport.d.ts

@@ -1,3 +1,4 @@
+import type { OAuthClientProvider } from "@modelcontextprotocol/sdk/client/auth.js";
 import { Client } from "@modelcontextprotocol/sdk/client/index.js";
 import type { Transport } from "@modelcontextprotocol/sdk/shared/transport.js";
 import type { NormalizedConfig } from "./config-normalize.js";
@@ -16,11 +17,14 @@ export declare class ProtocolError extends Error {
     readonly cause: unknown;
     constructor(serverName: string, cause: unknown);
 }
+export type BuildTransportOptions = {
+    authProvider?: OAuthClientProvider;
+};
 /**
  * Construct an SDK Transport for a normalized config.
  * Does NOT call .start() — caller (Client.connect) handles that.
  */
-export declare function buildTransport(cfg: NormalizedConfig): Promise<Transport>;
+export declare function buildTransport(cfg: NormalizedConfig, opts?: BuildTransportOptions): Promise<Transport>;
 /**
  * Connect to an MCP server, with auto-fallback from Streamable HTTP to
  * legacy SSE when the config's type was INFERRED from url (not explicit).
@@ -30,9 +34,16 @@ export declare function buildTransport(cfg: NormalizedConfig): Promise<Transport
  * wires it to `buildClient` (Task 7).
  */
 export declare function connectWithFallback<T>(cfg: NormalizedConfig, doConnect: (cfg: NormalizedConfig) => Promise<T>): Promise<T>;
+export type BuildClientOptions = {
+    authProvider?: OAuthClientProvider;
+};
 /**
  * Build a connected SDK Client for a normalized config.
  * Maps connect-time errors into OH's typed error taxonomy.
+ *
+ * When the auth provider exposes `awaitCallback()` (i.e. OhOAuthProvider), this
+ * function handles the full OAuth callback → finishAuth → reconnect loop so callers
+ * don't need to orchestrate it manually.
  */
-export declare function buildClient(cfg: NormalizedConfig): Promise<Client>;
+export declare function buildClient(cfg: NormalizedConfig, opts?: BuildClientOptions): Promise<Client>;
 //# sourceMappingURL=transport.d.ts.map