`callOnce()` should forward the OAuth-suppression option (`disableOAuth` from #198)

[feniix]

Summary

callOnce() is the one-shot library convenience exported from mcporter:

// src/runtime.ts (current main)
export async function callOnce(params: {
  server: string;
  toolName: string;
  args?: Record<string, unknown>;
  configPath?: string;
}): Promise<unknown>;

It drops every CallOptions knob the underlying runtime.callTool exposes. Once #198 lands disableOAuth on Runtime.callTool (and listTools / listResources / readResource), callOnce will be the only public call surface that can't suppress the interactive OAuth flow — headless callers will have to drop down to createRuntime + callTool + close just to set one boolean.

Why this matters

The README explicitly points callOnce at headless use cases (line 257 today):

callOnce automatically discovers the selected server (...), handles OAuth prompts, and closes transports when it finishes. It is ideal for manual runs or wiring MCPorter directly into an agent tool hook.

"Agent tool hook" is non-interactive. Today on main, if the cached token is expired or missing, callOnce reaches openExternal and tries to spawn a browser from a context the user can't see — the exact failure mode #197 reports and #198 closes for Runtime.callTool. The convenience function the README promotes for headless work cannot enforce headless safety.

Security / operational impact

Strictly additive and safe-by-default:

• disableOAuth defaults to undefined → behavior identical to today.
• disableOAuth: true is more restrictive than the default — suppresses interactive OAuth at the transport layer and short-circuits the unauthorized-fallback path that could otherwise re-enter OAuth.
• Falls back to cached tokens via the same on-disk store the CLI's --no-oauth path (added in fix(runtime): preserve disableOAuth across headless paths #198) uses. Missing or expired token → server returns 401, call fails cleanly. No hanging browser launch.

The flag only narrows what the runtime is allowed to do; no scenario widens an attacker's reach.

Proposed API

Add one optional field; forward it:

 export async function callOnce(params: {
   server: string;
   toolName: string;
   args?: Record<string, unknown>;
   configPath?: string;
+  disableOAuth?: boolean;
 }): Promise<unknown> {
   const runtime = await createRuntime({ configPath: params.configPath });
   try {
     return await runtime.callTool(params.server, params.toolName, {
       args: params.args,
+      disableOAuth: params.disableOAuth,
     });
   } finally {
     await runtime.close(params.server);
   }
 }

Forward only disableOAuth. Per #198's design, disableOAuth: true already implies cached-token use, so explicit allowCachedAuth isn't required. CallOptions.timeoutMs and ConnectOptions.oauthSessionOptions are deliberately left to the full Runtime surface — callers needing them should not be on the convenience function. Adding timeoutMs later is a reasonable separable expansion.

README follow-up

Update the README line above in the same PR to mention disableOAuth and cross-reference the CLI's --no-oauth flag.

Backward compatibility

Strictly additive. Every existing caller keeps working with the same default behavior.

Scope

callOnce only. Not in scope: revisiting callOnce's broader design, forwarding the full CallOptions / ConnectOptions surface.

Related & dependency

Becomes actionable when #198 lands; could also be folded into #198's PR.

• Add disableOAuth connect option — maxOAuthAttempts: 0 defeats the connection cache #197 — reports the underlying headless-safety requirement.
• fix(runtime): preserve disableOAuth across headless paths #198 — the open PR adding disableOAuth to Runtime.callTool and the matching CLI flags (--no-oauth). callOnce was the one public call surface not updated.
• Expose Runtime.connect's options shape as a public type #199 — types Runtime.connect's options surface so consumers can name the shape. This issue closes the matching gap for the convenience function: not just naming the posture, but being able to use it.

Priority

P3 / impact:auth-provider — same class as #199. The functional workaround (createRuntime + callTool + close) will exist once #198 lands; the gap is that the README documents a use case its convenience API cannot fully support.

[clawsweeper]

Codex review: keeping this open for maintainer follow-up; there is still a little grit to resolve. Reviewed June 6, 2026, 12:10 PM ET / 16:10 UTC.

Summary
Keep open: current main does not expose or forward disableOAuth through callOnce, and the related open runtime PR appears to add the base option to Runtime.callTool while leaving callOnce unchanged. This is a small valid follow-up, but it should be coordinated with #198 rather than closed as implemented.

Reproducibility: yes. for the API gap by source inspection: current main has no disableOAuth field on callOnce params and forwards only args to runtime.callTool. I did not run a live OAuth server because the missing public option is visible in source.

Next step
Maintainers should decide whether this belongs inside the open runtime OAuth PR or as a follow-up after that API lands.

Review details

Best possible solution:

Fold the narrow callOnce forwarder, README note, and focused coverage into the runtime disableOAuth work, or land it immediately after that option is accepted.

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

Yes for the API gap by source inspection: current main has no disableOAuth field on callOnce params and forwards only args to runtime.callTool. I did not run a live OAuth server because the missing public option is visible in source.

Is this the best way to solve the issue?

Unclear until the base disableOAuth API in the related PR is accepted. If that contract lands, forwarding only this boolean through callOnce is the narrowest maintainable fix.

AGENTS.md: found and applied where relevant.

Remaining risk / open question:

• The base disableOAuth public API is still under review in fix(runtime): preserve disableOAuth across headless paths #198, so landing this independently on current main would either anticipate or duplicate an unsettled auth-provider contract.

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

Label changes

Label changes:

• add P3: This is a low-risk additive API/docs follow-up with a runtime workaround through createRuntime once the base option exists.
• add impact:auth-provider: The request is specifically about suppressing interactive OAuth behavior on a public call path for headless callers.
• add issue-rating: 🦞 diamond lobster: Current issue advisory state selects this label.
• add clawsweeper:source-repro: 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 additive API/docs follow-up with a runtime workaround through createRuntime once the base option exists.
• impact:auth-provider: The request is specifically about suppressing interactive OAuth behavior on a public call path for headless callers.

Evidence reviewed

Acceptance criteria:

• ./runner pnpm run check
• ./runner pnpm test
• ./runner pnpm exec tsx scripts/docs-list.ts
• ./git diff --check

What I checked:

• Current callOnce surface omits disableOAuth: On current main, callOnce accepts only server, toolName, args, and configPath, then forwards only args to runtime.callTool. (src/runtime.ts:90, 2bf7a5eab23f)
• Current runtime options do not yet include disableOAuth: CallOptions currently contains args and timeoutMs, while ConnectOptions contains OAuth/cache knobs but no disableOAuth field on main. (src/runtime.ts:35, 2bf7a5eab23f)
• OAuth transport still keys suppression to maxOAuthAttempts: The transport option shape has maxOAuthAttempts and allowCachedAuth, and OAuth session creation still checks activeDefinition.auth === 'oauth' && options.maxOAuthAttempts !== 0. (src/runtime/transport.ts:83, 2bf7a5eab23f)
• README advertises callOnce for agent hooks: The README describes callOnce as handling OAuth prompts and being ideal for wiring MCPorter into an agent tool hook, which matches the reported headless-use gap. (README.md:257, 2bf7a5eab23f)
• Related PR leaves callOnce unchanged: The diff from current main to the related PR head adds disableOAuth to CallOptions and forwards it in callTool, but the callOnce hunk remains unchanged and still forwards only args. (src/runtime.ts:90, 625463c006c6)
• Vision supports the class of work: VISION.md prioritizes TypeScript/scripts/agent workflows, hosted OAuth providers, and small reliability improvements when they are bounded and verifiable. (VISION.md:3, 2bf7a5eab23f)

Likely related people:

• Peter Steinberger: Current src/runtime.ts and the relevant OAuth/cache option lines blame to the v0.11.3 release commit, and history shows repeated runtime/OAuth work including cached daemon OAuth calls. (role: recent area contributor; confidence: high; commits: 94e65ba0572e, 86e19f4413ba, 88237703e216; files: src/runtime.ts, src/runtime/transport.ts, README.md)
• feniix: Authored the related open runtime PR at fix(runtime): preserve disableOAuth across headless paths #198 that introduces disableOAuth across runtime helpers but does not add the callOnce forwarder requested here. (role: related API proposer; confidence: medium; commits: 625463c006c6; files: src/runtime.ts, src/runtime/transport.ts, tests/runtime-compose.test.ts)
• Sebastian Otaegui: History shows prior no-browser OAuth session support in the same transport/auth area that this issue builds on. (role: adjacent OAuth contributor; confidence: medium; commits: 033abb4358e6; files: src/runtime.ts, src/runtime/transport.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.