Expose Runtime.connect's options shape as a public type

[feniix]

Summary

Runtime.connect accepts an options object at runtime, but the type signature in dist/runtime.d.ts only exposes the bare positional signature:

connect(server: string): Promise<ClientContext>;

Consumers that need to wrap or override connect — e.g. a long-running daemon forcing disableOAuth: true on every internal call from callTool / listTools — have no public type for the options shape. The existing workaround is Record<string, any> on the parameter, which throws away type safety on a small but load-bearing surface (cache control + OAuth suppression).

Why this matters

connect's options object is already the public-facing primitive for cross-cutting concerns: cache identity (skipCache), OAuth posture (maxOAuthAttempts, disableOAuth once #198 lands, allowCachedAuth), and OAuth session forwarding (oauthSessionOptions). Consumers that need to enforce one of these choices end up writing a connect wrapper — and that wrapper has to know the shape.

Concrete in-the-wild example. evie-platform's daemon wraps Runtime so every internal connect call ends up daemon-safe (source):

// Today: TypeScript loses type safety on the options shape.
proto.connect = async (server: string, options: Record<string, any> = {}) => {
  return originalConnect(server, {
    ...options,
    maxOAuthAttempts: 0,
    allowCachedAuth: true,
    disableOAuth: true,                              // introduced by #198
  });
};

Every consumer that builds something similar (any headless / daemon / CI / scripted caller per the same niche #197 + #198 address) ends up either widening to Record<string, any> like this or copying mcporter's internal option fields locally and drifting from upstream.

Proposed API

Export the options shape under a stable name:

export interface ConnectOptions {
  /** Bypass the connection cache for this single call. */
  skipCache?: boolean;
  /** Maximum OAuth re-establishment attempts. 0 = never. */
  maxOAuthAttempts?: number;
  /** Use cached access tokens when available. */
  allowCachedAuth?: boolean;
  /**
   * Suppress OAuth entirely. Introduced by #198. Stronger than
   * `maxOAuthAttempts: 0` because it also short-circuits
   * `maybePromoteHttpDefinition` on the unauthorized-fallback path.
   * Note: `disableOAuth: false` is normalized to the same cache identity
   * as omitting the option (per #198).
   */
  disableOAuth?: boolean;
  /** Forwarded to `createClientContext`. */
  oauthSessionOptions?: OAuthSessionOptions;
}

(OAuthSessionOptions would likely need to be a named public export too if it isn't already — same rationale as ConnectOptions.)

Tighten Runtime's connect signature:

export interface Runtime {
  connect(server: string, options?: ConnectOptions): Promise<ClientContext>;
  // ...
}

Scope

This issue is scoped to the options shape only. The other casts a consumer like the evie daemon currently uses — the as any to mutate the runtime in place, and the as any to read ClientContext fields off the awaited connect promise — are separate concerns that would need their own changes (e.g. exporting ClientContext publicly, or moving consumers off prototype monkey-patching). Filing those separately keeps each ask easy to accept.

Backward compatibility

Strictly additive. Existing callers passing only the server name keep working (options arg is optional). Existing callers passing arbitrary objects keep working (TypeScript widens structurally). Old code paths using as any can drop the casts at their leisure.

Related

• Add disableOAuth connect option — maxOAuthAttempts: 0 defeats the connection cache #197 / fix(runtime): preserve disableOAuth across headless paths #198 — Add disableOAuth connect option — maxOAuthAttempts: 0 defeats the connection cache #197 reported that maxOAuthAttempts: 0 defeats the connection cache; fix(runtime): preserve disableOAuth across headless paths #198 is the PR closing it by adding disableOAuth as the cache-friendly OAuth-suppression primitive. This issue is the natural type-side follow-up: now that disableOAuth is the load-bearing option for headless callers, make it (and its sibling fields) discoverable through Runtime's public types so the wrappers needed to use it don't have to cast their way around.

Use-case context

Same daemon shape as #197 — a long-running process polling a hosted MCP server every ~30s, no GUI, needs to ensure no internal mcporter code path can reach openExternal. The daemon wraps Runtime itself today; getting the options shape typed publicly is the difference between three as any casts and zero.

[clawsweeper]

Codex review: keeping this open for maintainer follow-up; there is still a little grit to resolve. Reviewed June 6, 2026, 11:02 AM ET / 15:02 UTC.

Summary
Keep open: current main and v0.11.3 still expose Runtime.connect as a server-only public signature, while the matching ConnectOptions export exists only in the still-open #198 diff. This should stay paired with that API decision rather than being closed early.

Reproducibility: not applicable. as a runtime bug reproduction: this is a public TypeScript API request. Source inspection does confirm the current exported Runtime type lacks the options parameter and ConnectOptions export.

Ways to help us reproduce this

• Add a screenshot or short recording showing the behavior.
• Add expected vs actual behavior.
• Include redacted logs or terminal output.

Next step
A same-author open PR already changes this runtime API surface, and the repository guidance asks for maintainer judgment before adding new public API surface.

Review details

Best possible solution:

Land a maintainer-approved ConnectOptions export and Runtime.connect options signature in the same API direction as the disableOAuth work, re-exporting any nested option types needed from the package root.

Do we have a high-confidence way to reproduce the issue?

Not applicable as a runtime bug reproduction: this is a public TypeScript API request. Source inspection does confirm the current exported Runtime type lacks the options parameter and ConnectOptions export.

Is this the best way to solve the issue?

Unclear until maintainers settle the public API shape. The narrow maintainable path is to expose ConnectOptions and update Runtime.connect after or alongside the disableOAuth decision in #198.

AGENTS.md: found and applied where relevant.

Remaining risk / open question:

• The public API shape depends on the still-open disableOAuth work; exporting a stable ConnectOptions type before that decision settles could lock in the wrong fields.
• The request may also require deciding whether OAuthSessionOptions and possibly ClientContext should be re-exported from the package root, which is a maintainer API-boundary choice.

Codex review notes: model gpt-5.5, reasoning high; reviewed against 2bf7a5eab23f.

Label changes

Label changes:

• add P3: This is a low-risk public type/API ergonomics request, not a confirmed runtime regression on current main.
• add impact:auth-provider: The requested type covers OAuth posture options such as maxOAuthAttempts, allowCachedAuth, oauthSessionOptions, and the proposed disableOAuth field.
• add issue-rating: 🌊 off-meta tidepool: Current issue advisory state selects this label.
• add clawsweeper:no-new-fix-pr: Current issue advisory state selects this label.
• add clawsweeper:fix-shape-clear: Current issue advisory state selects this label.
• add clawsweeper:needs-maintainer-review: Current issue advisory state selects this label.
• add clawsweeper:needs-product-decision: Current issue advisory state selects this label.

Label justifications:

• P3: This is a low-risk public type/API ergonomics request, not a confirmed runtime regression on current main.
• impact:auth-provider: The requested type covers OAuth posture options such as maxOAuthAttempts, allowCachedAuth, oauthSessionOptions, and the proposed disableOAuth field.

Evidence reviewed

What I checked:

• Current Runtime type lacks options parameter: On current main, ConnectOptions is private and the exported Runtime interface declares connect(server: string): Promise<ClientContext> with no public options argument. (src/runtime.ts:47, 2bf7a5eab23f)
• Root package exports do not expose ConnectOptions: The root barrel exports CallOptions, ListToolsOptions, Runtime, RuntimeLogger, and ServerToolInfo, but not ConnectOptions or OAuthSessionOptions. (src/index.ts:5, 2bf7a5eab23f)
• Package public type surface goes through dist/index.d.ts: package.json points consumers at dist/index.d.ts and only exports the root package plus ./cli, so types not re-exported from src/index.ts are not part of the normal public package surface. (package.json:28, 2bf7a5eab23f)
• Latest release has the same missing signature: The v0.11.3 tag still has the server-only Runtime.connect signature, so the requested type exposure has not shipped in the latest release. (src/runtime.ts:62, 94e65ba0572e)
• Related open PR contains a matching but unmerged implementation: The open same-author PR at fix(runtime): preserve disableOAuth across headless paths #198 changes interface ConnectOptions to export interface ConnectOptions and updates Runtime.connect(server, options?: ConnectOptions), but the PR is still open and unmerged. (src/runtime.ts:47, 625463c006c6)
• Feature history points to the current runtime API owner: Blame shows the current runtime option interfaces and public Runtime.connect signature came from the v0.11.3 release commit by Peter Steinberger. (src/runtime.ts:35, 94e65ba0572e)

Likely related people:

• Peter Steinberger: Blame and path history show the current runtime public API, private ConnectOptions, and connect cache/options implementation are from the v0.11.3 release work, with additional recent OAuth/runtime fixes in the same area. (role: feature owner and recent area contributor; confidence: high; commits: 94e65ba0572e, 86e19f4413ba, 31bbaa804f34; files: src/runtime.ts, src/runtime/transport.ts, src/index.ts)
• feniix: The same contributor opened the type-surface issue and the open disableOAuth PR whose diff already exports ConnectOptions; prior merged headless OAuth work also touched the runtime and transport option paths. (role: adjacent feature contributor and current proposer; confidence: medium; commits: 2171c1f209cb, 033abb4358e6; files: src/runtime.ts, src/runtime/transport.ts, src/oauth.ts)
• bradhallett: Recent daemon cached-auth work changed the same allowCachedAuth runtime and keep-alive daemon paths that the requested public options type would document for wrappers. (role: adjacent daemon OAuth contributor; confidence: medium; commits: 1e6ce66d22d7, ccfaa2f4f0fc; files: src/daemon/runtime-wrapper.ts, src/daemon/host.ts, src/runtime.ts)

How this review workflow works

• ClawSweeper keeps one durable marker-backed review comment per issue or PR.
• Re-runs edit this comment so the latest verdict, findings, and automation markers stay together instead of adding duplicate bot comments.
• A fresh review can be triggered by eligible @clawsweeper re-review comments, exact-item GitHub events, scheduled/background review runs, or manual workflow dispatch.
• PR/issue authors and users with repository write access can comment @clawsweeper re-review or @clawsweeper re-run on an open PR or issue to request a fresh review only.
• Maintainers can also comment @clawsweeper review to request a fresh review only.
• Fresh-review commands do not start repair, autofix, rebase, CI repair, or automerge.
• Maintainer-only repair and merge flows require explicit commands such as @clawsweeper autofix, @clawsweeper automerge, @clawsweeper fix ci, or @clawsweeper address review.
• Maintainers can comment @clawsweeper explain to ask for more context, or @clawsweeper stop to stop active automation.