dsh-agent-plugins-market 0.5.2 → 0.6.0

package/lib/types/runtime/mcp-backend.d.ts

@@ -0,0 +1,49 @@
+/**
+ * MCP backend selection: whether suite MCP servers mount through the
+ * market's self-built bridge (default — stdio, Streamable HTTP with OAuth,
+ * and legacy SSE) or through the host's `@deepseek-ai/dsh-mcp-client`
+ * (compatibility mode: no OAuth, no SSE, but the host-native implementation).
+ *
+ * The choice is a host settings namespace (`dsh-agent-plugins-market`,
+ * `mcpEnhanced: boolean`, default true) registered by the plugin's node half:
+ * the registration is what makes the host 插件配置 tab serve our card, the
+ * client card binds it for state, and the node half watches it to remount
+ * servers when the switch flips. `readMcpBackend` remains only as the
+ * one-time migration from the earlier data-root `settings.json` choice.
+ *
+ * @module runtime/mcp-backend
+ */
+import z from '@deepseek-ai/schemastery';
+/** The MCP mount backend the market uses for suite servers. */
+export type McpBackend = 'builtin' | 'host';
+export declare const MCP_BACKENDS: readonly McpBackend[];
+/** Settings namespace this plugin registers; the key the plugin-config tab pairs our card by. */
+export declare const MCP_SETTINGS_NAMESPACE = "dsh-agent-plugins-market";
+/** Schema of the market settings namespace: the MCP enhancement switch and the download region. */
+export declare const MarketSettingsSchema: z<Schemastery.ObjectS<{
+    /** ON (default) = the built-in bridge with OAuth and SSE; OFF = host client compat mode. */
+    mcpEnhanced: z<boolean, boolean>;
+    /** Download region for GitHub acquisition; `auto` follows the interface language. */
+    downloadRegion: z<"auto" | "global" | "china", "auto" | "global" | "china">;
+}>, Schemastery.ObjectT<{
+    /** ON (default) = the built-in bridge with OAuth and SSE; OFF = host client compat mode. */
+    mcpEnhanced: z<boolean, boolean>;
+    /** Download region for GitHub acquisition; `auto` follows the interface language. */
+    downloadRegion: z<"auto" | "global" | "china", "auto" | "global" | "china">;
+}>>;
+/** Path of the legacy persisted settings file under the plugin data root. */
+export declare function marketSettingsPath(dataRoot: string): string;
+/** Read the legacy persisted backend; absent or invalid values read as the default. */
+export declare function readMcpBackend(dataRoot: string): Promise<McpBackend>;
+/** What the host client probe reports: resolvability plus its version. */
+export interface HostMcpClientProbe {
+    available: boolean;
+    version?: string;
+}
+/**
+ * Probe whether the host's `dsh-mcp-client` is resolvable from this plugin's
+ * module context, and at which version. Best effort: any failure reads as
+ * "unavailable", which the mount path surfaces as a per-server diagnostic
+ * when the host backend is selected.
+ */
+export declare function probeHostMcpClient(): Promise<HostMcpClientProbe>;

package/lib/types/runtime/mcp-client/bridge.d.ts

@@ -0,0 +1,37 @@
+/**
+ * The market's self-built MCP client bridge plugin: connects to one external
+ * MCP server and registers its tools on the harness ToolRuntime under
+ * server-qualified public names (`mcp__<serverName>__<rawName>`). One plugin
+ * instance per server; the mount registry loads instances through
+ * `ctx.plugin` exactly like the host's own client, so reconcile, retry,
+ * rollback, and HMR semantics are unchanged.
+ *
+ * Namespace plugin (named exports, no default export). Lifecycle is
+ * effect-scoped: disposal disconnects from the server, unregisters all tools,
+ * and releases the `serverName` namespace reservation. HMR hot-swaps by
+ * disposing the old instance and creating a new one; identical `serverName`
+ * reproduces identical public tool names.
+ *
+ * This replaces the runtime dependency on the host's `dsh-mcp-client`
+ * package: stdio, Streamable HTTP (with OAuth 2.1), and legacy SSE all run
+ * inside this plugin from the market's own `@modelcontextprotocol/sdk`
+ * dependency.
+ *
+ * @module runtime/mcp-client/bridge
+ */
+import type { Context } from '@deepseek-ai/cordis';
+import type { Config } from './config.js';
+/** Cordis plugin name used by loader diagnostics. */
+export declare const name = "market-mcp-client";
+/** Services required by this plugin. */
+export declare const inject: string[];
+/**
+ * Connect one MCP server and publish its initial tool generation before
+ * activation. Remains explicitly `async`: Cordis treats a prototype-bearing
+ * ordinary function as a constructor, whose returned Promise is not startup
+ * work.
+ * @param ctx - plugin context carrying the tool registry.
+ * @param config - resolved transport and server namespace configuration.
+ * @returns startup readiness after connection and initial tool discovery settle.
+ */
+export declare function apply(ctx: Context, config: Config): Promise<void>;

package/lib/types/runtime/mcp-client/config.d.ts

@@ -0,0 +1,123 @@
+/**
+ * Configuration types for the market's self-built MCP client bridge. One
+ * bridge instance connects to one MCP server; mounts are built
+ * programmatically by `mcp-config.ts`, so there is no Schemastery schema —
+ * every field the supervisor relies on is re-judged at load
+ * (`resolveReconnectPolicy`, serverName pattern) and misconfiguration fails
+ * that instance loudly instead of being normalized silently.
+ *
+ * @module runtime/mcp-client/config
+ */
+import type { ReconnectConfig } from './connection.js';
+export type { ReconnectConfig, ResolvedReconnectPolicy } from './connection.js';
+export { RECONNECT_DEFAULTS } from './connection.js';
+/** Default timeout for individual MCP tool calls (ms). */
+export declare const DEFAULT_TOOL_CALL_TIMEOUT_MS = 60000;
+/** Valid `serverName`, kept below the public tool-name budget. */
+export declare const SERVER_NAME_PATTERN: RegExp;
+/**
+ * Loopback callback tuning for the OAuth browser leg. The redirect listener
+ * binds `127.0.0.1`; port `0` (the default) picks an ephemeral port, which
+ * RFC 8252 §7.3 loopback redirects permit.
+ */
+export interface OAuthStorageConfig {
+    /** Fixed loopback port for the authorization redirect; `0` picks one ephemally. */
+    callbackPort?: number;
+}
+/**
+ * OAuth 2.1 authorization config for a Streamable HTTP (or legacy SSE)
+ * server. The MCP authorization flow (RFC 9728 discovery, dynamic client
+ * registration, PKCE, refresh) is performed by the SDK: on the server's `401`
+ * challenge the transport opens a loopback browser authorization, and granted
+ * tokens persist through the credentials service when one is mounted.
+ *
+ * Defaults to enabled — servers that never challenge are unaffected (the
+ * provider only activates on a `401`), so a suite needs no OAuth declaration
+ * for the flow to work.
+ */
+export interface OAuthConfig {
+    /** Enable the OAuth flow (default `true`; set `false` to opt out explicitly). */
+    enabled?: boolean;
+    /** Space-separated scope string requested during authorization, when the server needs one. */
+    scope?: string;
+    /** Loopback callback tuning; omission uses an ephemeral port and the defaults. */
+    storage?: OAuthStorageConfig;
+}
+/** Config for connecting to an MCP server via a spawned child process over stdio. */
+export interface StdioConfig {
+    /** Selects child-process stdio transport. */
+    transport: 'stdio';
+    /**
+     * Stable local namespace for this server's model-facing tool names
+     * (`mcp__<serverName>__<rawName>`). Must match `[A-Za-z0-9_-]{1,32}` and be
+     * unique across live bridge instances.
+     */
+    serverName: string;
+    /** Executable used to start the server. */
+    command: string;
+    /** Arguments passed directly, without shell interpolation. */
+    args: string[];
+    /** Extra env vars merged on top of scrubbed ambient env. */
+    env: Record<string, string>;
+    /** Working directory for the child process. */
+    cwd: string;
+    /** Per-tool-call timeout in milliseconds. */
+    toolCallTimeoutMs: number;
+    /** Fail plugin activation when the initial connection or tool synchronization fails. */
+    failOnStartupError: boolean;
+    /** Automatic reconnect policy after a lost connection; omission uses the defaults. */
+    reconnect?: ReconnectConfig;
+}
+/** Config for connecting to an MCP server over Streamable HTTP. */
+export interface StreamableHttpConfig {
+    /** Selects Streamable HTTP transport. */
+    transport: 'streamable-http';
+    /** Stable local namespace — see {@link StdioConfig.serverName}. */
+    serverName: string;
+    /** MCP endpoint URL. */
+    url: string;
+    /** Additional headers attached to MCP requests. */
+    headers: Record<string, string>;
+    /** OAuth 2.1 authorization (default enabled — see {@link OAuthConfig}); set `enabled: false` to opt out. */
+    auth?: OAuthConfig;
+    /** Per-tool-call timeout in milliseconds. */
+    toolCallTimeoutMs: number;
+    /** Fail plugin activation when the initial connection or tool synchronization fails. */
+    failOnStartupError: boolean;
+    /** Automatic reconnect policy after a lost connection; omission uses the defaults. */
+    reconnect?: ReconnectConfig;
+}
+/**
+ * Config for connecting to an MCP server over the legacy HTTP+SSE transport
+ * (the pre-Streamable-HTTP protocol some older servers still speak). The SDK
+ * owns the protocol pairing; OAuth semantics mirror the Streamable HTTP case.
+ */
+export interface SseConfig {
+    /** Selects the legacy HTTP+SSE transport. */
+    transport: 'sse';
+    /** Stable local namespace — see {@link StdioConfig.serverName}. */
+    serverName: string;
+    /** SSE endpoint URL the server advertises. */
+    url: string;
+    /** Additional headers attached to both the SSE stream and endpoint requests. */
+    headers: Record<string, string>;
+    /** OAuth 2.1 authorization (default enabled — see {@link OAuthConfig}). */
+    auth?: OAuthConfig;
+    /** Per-tool-call timeout in milliseconds. */
+    toolCallTimeoutMs: number;
+    /** Fail plugin activation when the initial connection or tool synchronization fails. */
+    failOnStartupError: boolean;
+    /** Automatic reconnect policy after a lost connection; omission uses the defaults. */
+    reconnect?: ReconnectConfig;
+}
+/** Configuration for one stdio, Streamable HTTP, or legacy SSE MCP server. */
+export type Config = StdioConfig | StreamableHttpConfig | SseConfig;
+/**
+ * Validate one programmatically-built config. Programmatic construction
+ * bypasses any schema layer, so every invariant the bridge relies on is
+ * re-judged here — a misconfiguration rejects the mount with an actionable
+ * error before any connection is attempted.
+ * @param config - raw bridge config built by `mcp-config.ts`.
+ * @returns the same config, narrowed to the validated shape.
+ */
+export declare function validateConfig(config: Config): Config;

package/lib/types/runtime/mcp-client/connection.d.ts

@@ -0,0 +1,82 @@
+/**
+ * Connection supervisor: owns the MCP client/transport generations for one
+ * bridge instance, keeps the harness tool registry in sync with the live
+ * generation, and — when the connection drops — restarts the configured
+ * server with bounded exponential backoff.
+ *
+ * One outage shares one attempt budget (`maxAttempts` consecutive failed
+ * attempts, delays doubling from `initialDelayMs` up to `maxDelayMs`). A
+ * connection that stays up past the stability window closes the outage, so
+ * the next disconnect starts a fresh budget while a crash-looping server —
+ * even one whose connects briefly succeed — still exhausts the cap instead of
+ * restarting forever. Exhaustion unregisters the server's tools and stops;
+ * disposal (including HMR) is the only way back from that state.
+ *
+ * Ported from the harness `dsh-mcp-client` supervisor (including the OAuth
+ * browser-leg hold: a failed initialize during a pending browser
+ * authorization holds the generation open — up to the loopback callback
+ * budget — instead of tearing down the authorization the user is mid-way
+ * through approving).
+ *
+ * @module runtime/mcp-client/connection
+ */
+import type { ToolHost } from './tools.js';
+import type { Config } from './config.js';
+/** Automatic reconnect policy for one MCP server connection. */
+export interface ReconnectConfig {
+    /** Reconnect automatically after a lost connection (default true). */
+    enabled?: boolean;
+    /** First reconnect delay in milliseconds; doubles per consecutive failed attempt (default 500). */
+    initialDelayMs?: number;
+    /** Backoff ceiling in milliseconds; also the uptime after which the attempt budget resets (default 30000). */
+    maxDelayMs?: number;
+    /** Consecutive failed attempts per outage before giving up for good (default 10). */
+    maxAttempts?: number;
+}
+/** Defaults shared by the config and {@link resolveReconnectPolicy}. */
+export declare const RECONNECT_DEFAULTS: Required<ReconnectConfig>;
+/** Fully resolved reconnect policy captured at plugin load. */
+export type ResolvedReconnectPolicy = Readonly<Required<ReconnectConfig>>;
+/**
+ * The one explicit resolve step from raw reconnect config to the policy the
+ * supervisor runs. Programmatic construction bypasses any schema layer, so
+ * every default and bound is re-judged here — misconfiguration fails the
+ * bridge instance at load.
+ *
+ * @param config - Raw `reconnect` config; omission uses the defaults.
+ * @param path - Diagnostic prefix naming the config location in thrown messages.
+ * @returns The frozen resolved policy.
+ */
+export declare function resolveReconnectPolicy(config: ReconnectConfig | undefined, path: string): ResolvedReconnectPolicy;
+/** Result from the initial connection attempt, for startup-await semantics. */
+export interface ConnectionOutcome {
+    /** If the initial connection or tool sync failed, the error; otherwise absent. */
+    error?: unknown;
+}
+/** Handle for one bridge instance's supervised connection. */
+export interface ConnectionHandle {
+    /**
+     * Settles when the first connection attempt completes (success or failure).
+     * The supervisor enters its reconnect loop regardless; the caller decides
+     * whether a failed startup is fatal via `failOnStartupError`.
+     */
+    ready: Promise<ConnectionOutcome>;
+    /**
+     * Stop reconnection, close the live client, wait for the in-flight attempt
+     * and queued tool syncs to quiesce, then unregister every tool this server
+     * still owns.
+     */
+    dispose(): Promise<void>;
+}
+/**
+ * Start the supervised connection for one MCP server and keep it alive per
+ * the reconnect policy.
+ *
+ * @param host - The bridge host providing the tool registry and logger.
+ * @param config - Resolved bridge config selecting the transport and server identity.
+ * @param policy - Resolved reconnect policy from {@link resolveReconnectPolicy}.
+ * @param credentials - The composition's credential store, when mounted; OAuth
+ *   state persists only when it is.
+ * @returns Handle with a `ready` promise for startup-await and a `dispose` for teardown.
+ */
+export declare function startConnection(host: ToolHost, config: Config, policy: ResolvedReconnectPolicy, credentials?: unknown): ConnectionHandle;

package/lib/types/runtime/mcp-client/host-seams.d.ts

@@ -0,0 +1,89 @@
+/**
+ * Local ports of the tiny host seams the self-built MCP client needs.
+ *
+ * The market plugin must stay self-contained at runtime: it cannot import
+ * host-internal packages that are not published at compatible versions, and
+ * every one of these seams is a small pure function or constant. Each port
+ * below is copied verbatim (semantics, not prose) from the harness source at
+ * `0.1.1-rc.2` and carries the upstream reference it came from, so a future
+ * host change can be re-diffed against `~/workspace/deepseek-harness`.
+ *
+ * Anything larger than a handful of lines (the JSON Schema subset validator)
+ * lives in its own module.
+ *
+ * @module runtime/mcp-client/host-seams
+ */
+/**
+ * The largest delay `setTimeout` accepts without overflowing to a 1ms clamp
+ * (2^31 - 1). Shared guard for reconnect and callback timers.
+ */
+export declare const MAX_TIMER_DELAY_MS = 2147483647;
+/** `DSH_*` environment namespace owned by the harness. */
+export declare const DSH_ENV_PREFIX: "DSH_";
+/**
+ * Credential-shaped environment names are NOT forwarded to MCP server child
+ * processes (the harness's own `DEEPSEEK_API_KEY`/secrets must not leak into a
+ * spawned server implicitly). Deliberately supplied env entries survive
+ * because the config's explicit env merges after the scrub.
+ */
+export declare const SENSITIVE_ENV_PATTERN: RegExp;
+/**
+ * The ambient parent environment minus credential-shaped names and minus all
+ * `DSH_*` names — the canonical base every harness child starts from. `PATH`,
+ * `HOME`, locale, and proxy variables survive, so child CLIs run normally;
+ * harness identity never leaks implicitly. Both scrubs match case-insensitively:
+ * Windows environment names are case-insensitive, so a parent `dsh_*` entry
+ * would otherwise survive and read back as `$env:DSH_*` in the child.
+ * @returns a fresh environment object safe to hand to a child spawn.
+ */
+export declare function scrubbedParentEnv(): Record<string, string>;
+/** A credential record key: `<scope>/<id>` with both segments in the grammar below. */
+declare const credentialKeyBrand: unique symbol;
+export type CredentialKey = string & {
+    readonly [credentialKeyBrand]: true;
+};
+/**
+ * Brand a scope and an id as a {@link CredentialKey}.
+ * @param scope - the owning plugin's registered name (here: the `mcp-auth` record scope).
+ * @param id - the plugin's own addressing unit (here: the folded serverName).
+ * @returns the branded key.
+ * @throws TypeError when either segment is not a lowercase hyphenated identifier.
+ */
+export declare function credentialKey(scope: string, id: string): CredentialKey;
+/**
+ * Structural mirror of the host `CredentialProvider` record surface the OAuth
+ * provider needs. Typed structurally because the store arrives via the
+ * optional `credentials` service; the OAuth provider narrows at runtime and
+ * falls back to memory-only state when the service is absent.
+ */
+export interface CredentialRecordStore {
+    describeRecord(key: CredentialKey): Promise<{
+        configured: boolean;
+        writable: boolean;
+    }>;
+    readRecord(key: CredentialKey): Promise<unknown>;
+    modifyRecord(key: CredentialKey, mutate: (current: unknown) => Promise<unknown>): Promise<unknown>;
+}
+/**
+ * Distinguish caller-correctable image admission failures from storage faults,
+ * so an admission refusal projects text diagnostics while a storage fault is
+ * reported as such.
+ */
+export declare function isImageAdmissionError(error: unknown): boolean;
+/** Raster formats supported by the durable attachment vocabulary. */
+export type ImageMediaType = 'image/png' | 'image/jpeg' | 'image/webp' | 'image/gif';
+/** One decoded image handed to the host attachment store. */
+export interface SaveImageAttachment {
+    data: Buffer;
+    mediaType: ImageMediaType;
+}
+/**
+ * Structural mirror of the host `AttachmentStore.saveImages` surface. The
+ * returned refs are opaque host values that ride inside `ContentBlock`
+ * image blocks; typed `unknown` here and narrowed by the model content
+ * contract at the projection site.
+ */
+export interface AttachmentStoreLike {
+    saveImages(images: readonly SaveImageAttachment[]): Promise<readonly unknown[]>;
+}
+export {};

package/lib/types/runtime/mcp-client/json-schema-subset.d.ts

@@ -0,0 +1,58 @@
+/**
+ * Local port of the harness's enforced JSON Schema subset validator
+ * (`@deepseek-ai/dsh-tools` `json-schema.ts`, rc.2) — narrowed to the one use
+ * the MCP bridge has: deciding whether an MCP server's advertised
+ * `outputSchema` may ride a tool registration as a structured-output schema.
+ *
+ * The upstream validator is 656 lines with realm-safe JSON intrinsics; this
+ * port keeps the *contract* — a closed keyword table, one scalar `type`,
+ * nested structure, and "unsupported keywords reject rather than pass
+ * unenforced" — with a conservative structural check. A schema this check
+ * wrongly rejects only loses structured typing (the bridge falls back to
+ * untyped JSON, exactly the upstream failure mode); one it wrongly accepts
+ * would flow into the host registry, so every branch here fails closed.
+ *
+ * @module runtime/mcp-client/json-schema-subset
+ */
+/** Scalar JSON values supported by `enum` and `const`. */
+export type JsonSchemaScalar = string | number | boolean | null;
+/** Single-type keywords accepted by the enforced subset. */
+export type JsonSchemaType = 'object' | 'array' | 'string' | 'number' | 'integer' | 'boolean' | 'null';
+/**
+ * One raw JSON Schema node in the enforced subset. The optional fields express
+ * the external wire schema; {@link assertSupportedJsonSchema} rejects invalid
+ * combinations before a caller treats the node as trusted.
+ */
+export interface JsonSchemaNode {
+    /** Omit with no constraints for any JSON value, or use `oneOf`. */
+    type?: JsonSchemaType;
+    /** Exactly one branch must validate; at least two branches are required. */
+    oneOf?: JsonSchemaNode[];
+    /** Nested property schemas (`type: 'object'` only). */
+    properties?: Record<string, JsonSchemaNode>;
+    /** Required property names; each must appear in `properties`. */
+    required?: string[];
+    /** `false` rejects undeclared keys; absent/`true` follows JSON Schema's open default. */
+    additionalProperties?: boolean;
+    /** Item schema (`type: 'array'` only); absent accepts any JSON item. */
+    items?: JsonSchemaNode;
+    /** Allowed values for a scalar node. */
+    enum?: JsonSchemaScalar[];
+    /** The single allowed value for a scalar node. */
+    const?: JsonSchemaScalar;
+    /** Annotation, ignored for validation. */
+    description?: string;
+    /** Annotation, ignored for validation. */
+    title?: string;
+    /** Annotation, ignored for validation but required to be lossless JSON. */
+    default?: JsonSchemaScalar | Record<string, unknown> | unknown[];
+    /** Annotation, ignored for validation but required to be lossless JSON. */
+    examples?: JsonSchemaScalar | Record<string, unknown> | unknown[];
+}
+/**
+ * Assert that a raw schema uses only the enforced subset. Annotation-only
+ * schemas are accepted as the standard unconstrained-JSON form.
+ * @param schema - untrusted raw JSON Schema.
+ * @throws Error listing every violation when the schema leaves the subset.
+ */
+export declare function assertSupportedJsonSchema(schema: unknown): asserts schema is JsonSchemaNode;

package/lib/types/runtime/mcp-client/oauth.d.ts

@@ -0,0 +1,121 @@
+/**
+ * OAuth 2.1 authorization-code support for Streamable HTTP (and legacy SSE)
+ * MCP servers that answer `401` with an OAuth challenge (`WWW-Authenticate:
+ * Bearer resource_metadata="…"` — the MCP authorization spec's discovery
+ * anchor).
+ *
+ * The SDK owns the protocol: its `auth()` helper performs RFC 9728 protected-
+ * resource discovery, authorization-server metadata lookup, RFC 7591 dynamic
+ * client registration, PKCE, token exchange, and refresh, and the HTTP
+ * transports invoke it on the first `401` through the
+ * {@link OAuthClientProvider} this module implements. This module owns the two
+ * parts the SDK leaves to the application: durable storage of client and token
+ * state, and the human leg of the flow — a loopback redirect that captures
+ * the authorization code without caller-side wiring.
+ *
+ * Tokens and registered client information persist as a `grant` credential
+ * record under `mcp-auth/<serverName>` through the harness credentials seam
+ * when one is mounted, so they land in the managed `.credentials.yaml`
+ * document (mode `0600`, file-locked, refresh-safe across processes) and are
+ * visible to the same surface that manages every other credential. Without a
+ * credentials service the provider still completes flows in memory; tokens
+ * then last exactly as long as the process.
+ *
+ * Ported from the harness `dsh-mcp-client` OAuth implementation (upstream
+ * commits archived at `docs/upstream-proposal/patches/`); the record format is
+ * byte-compatible, so grants written by either implementation are interchangeable.
+ *
+ * @module runtime/mcp-client/oauth
+ */
+import { type OAuthClientProvider } from '@modelcontextprotocol/sdk/client/auth.js';
+import type { OAuthClientInformationMixed, OAuthClientMetadata, OAuthTokens } from '@modelcontextprotocol/sdk/shared/auth.js';
+import type { OAuthStorageConfig } from './config.js';
+/** Credential-record scope for MCP OAuth state; per-server ids follow it. */
+export declare const MCP_AUTH_RECORD_SCOPE = "mcp-auth";
+/**
+ * Error thrown when the human leg fails or is abandoned: the browser never
+ * returned, the callback carried an OAuth error, or no browser could open.
+ * The transport surfaces it from `connect`; the supervisor's reconnect loop
+ * re-enters the flow — which reopens the browser — on a later attempt.
+ */
+export declare class AuthorizationAbortedError extends Error {
+    constructor(message: string, options?: ErrorOptions);
+}
+/** Opens the platform browser; injected in tests to record the URL instead. */
+export type BrowserOpener = (authorizationUrl: URL, serverName: string, log: (message: string) => void) => Promise<void>;
+/** The real opener: platform browser or default URL handler. */
+export declare const platformBrowserOpener: BrowserOpener;
+/**
+ * {@link OAuthClientProvider} over the harness credentials seam (or process
+ * memory when the seam is absent), with a loopback redirect that opens the
+ * system browser.
+ */
+export declare class LoopbackOAuthClientProvider implements OAuthClientProvider {
+    private readonly serverName;
+    private readonly storage;
+    private readonly scope;
+    private readonly log;
+    private readonly opener;
+    private readonly recordKey;
+    /** Credential store mounted in this composition; absence means memory-only. */
+    private readonly store;
+    /** In-memory fallback and cache over the store's durable state. */
+    private providerState;
+    /** The transport generation whose `finishAuth` completes the browser leg. */
+    private activeTransport;
+    /** Resolves `true` when the leg saved tokens, `false` when it failed; undefined while no leg is open. */
+    private browserLegSettled;
+    private callbackServer;
+    private callbackTimer;
+    private boundPort;
+    /** Serializes store writes so a rapid refresh cannot interleave read-modify-writes. */
+    private writeChain;
+    constructor(serverName: string, storage: OAuthStorageConfig, scope: string | undefined, log: (message: string) => void, store: unknown, opener?: BrowserOpener);
+    get redirectUrl(): string;
+    get clientMetadata(): OAuthClientMetadata;
+    clientInformation(): Promise<OAuthClientInformationMixed | undefined>;
+    saveClientInformation(clientInformation: OAuthClientInformationMixed): Promise<void>;
+    tokens(): Promise<OAuthTokens | undefined>;
+    saveTokens(tokens: OAuthTokens): Promise<void>;
+    /**
+     * Bind the loopback server, open the browser, and complete the code
+     * exchange into the bound transport generation. Resolves only after tokens
+     * are saved; an OAuth `error` redirect, a timeout, or a listener failure
+     * rejects with {@link AuthorizationAbortedError}.
+     */
+    redirectToAuthorization(authorizationUrl: URL): Promise<void>;
+    /** Whether a browser leg is open and the code exchange is still pending. */
+    get awaitingBrowser(): boolean;
+    /**
+     * Resolves once the pending browser leg finishes (tokens saved or the leg
+     * failed); undefined while no leg is open. The supervisor holds the
+     * connection generation — instead of timing out and respawning, which would
+     * abandon the leg the user is mid-way through approving — until this
+     * settles.
+     */
+    get browserLeg(): Promise<boolean> | undefined;
+    /**
+     * Register the transport generation whose `finishAuth` completes the flow.
+     * The transport calls `redirectToAuthorization` during `connect`; binding
+     * it here keeps the code exchange inside the generation that owns the
+     * connection, per the SDK's per-connection session model.
+     */
+    bindTransport(transport: {
+        finishAuth(code: string): Promise<void>;
+    }): void;
+    /** Abandon any previously bound browser leg before a new one starts. */
+    resetCallback(): void;
+    saveCodeVerifier(codeVerifier: string): Promise<void>;
+    codeVerifier(): Promise<string>;
+    invalidateCredentials(scope: 'all' | 'client' | 'tokens' | 'verifier' | 'discovery'): Promise<void>;
+    private load;
+    private mutate;
+    /**
+     * Bind a loopback listener, open the browser at `authorizationUrl` (its
+     * `redirect_uri` is rewritten to the bound port), and resolve with the code
+     * the user agent lands back with.
+     */
+    private awaitCallback;
+    private handleCallbackRequest;
+    private clearCallbackTimer;
+}