llm-cli-gateway 2.13.0 → 2.13.2

package/.agents/skills/multi-llm-review/SKILL.md

@@ -3,7 +3,7 @@ name: multi-llm-review
 description: Parallel code reviews across Claude, Codex, Gemini, Grok, and Mistral. Use for quality analysis, bug finding, or security audit.
 metadata:
   author: verivus-oss
-  version: "1.6"
+  version: "1.7"
 ---
 
 # Multi-LLM Code Review
@@ -24,10 +24,89 @@ Parallel reviews using gateway MCP tools. Each LLM has different strengths — c
 
 Apply these on every dispatch unless the caller has explicitly overridden a rule in the current turn:
 
-1. **Omit `model`** — let the gateway use its configured default per CLI. Nominating a model risks deprecated IDs (`o3`, `o3-pro`, `gpt-4o`, …) and capability mismatches. Call `list_models` only when the caller has asked for a specific variant.
-2. **`approvalStrategy:"mcp_managed"`** is the skill dispatch default (the gateway schema default is `"legacy"`). It gates the request before execution; Claude then runs with `--permission-mode bypassPermissions`, Gemini with `--approval-mode yolo`, and Codex still needs `fullAuto:true` for autonomous file/shell work. Prefer this over raw bypass flags.
-3. **No wallclock timeout; poll every 60 s** — let sync auto-defer at 45 s or use `*_request_async`. Poll `llm_job_status` once every 60 seconds. Do **not** cancel jobs for taking too long; cancel only on explicit instruction or hard failure. `idleTimeoutMs` (no-output safeguard) is separate.
-4. **Iterate until unconditional APPROVED** (review dispatches only) — every review prompt must end with "End with APPROVED or NOT APPROVED with findings." On `NOT APPROVED` or conditional approval, consolidate findings, dispatch fixes (Codex + `fullAuto:true`), re-dispatch the review to the same reviewer. Repeat until unconditional APPROVED. Escalate after 3 rounds without convergence. This rule does **not** apply to pure implementation or non-review analysis dispatches.
+1. **Use the stdio gateway MCP surface only** — call the host's `mcp__gtwy__*` tools (or the equivalent stdio `gtwy` namespace exposed to the current agent). Do not use connector/shadow gateway tools when the user asked for stdio gateway validation.
+2. **Omit `model`** — let the gateway use its configured default per CLI. Nominating a model risks deprecated IDs (`o3`, `o3-pro`, `gpt-4o`, ...) and capability mismatches. Call `list_models` only when the caller has asked for a specific variant.
+3. **`approvalStrategy:"mcp_managed"`** is the skill dispatch default (the gateway schema default is `"legacy"`). It gates the request before execution. Grant full non-interactive verification permissions on every review round because permission grants are not assumed durable.
+4. **Full verification access for reviewers is required** — reviewers need read, test/build, code-search, docs lookup, web/search, and provider-safe gateway introspection access where appropriate. Do not suppress tools or pass empty allowlists. If a provider-specific permission or MCP server required for verification is rejected, treat that as a review dispatch failure and fix the gateway/permission setup before proceeding, unless the user explicitly authorizes a degraded review.
+5. **No wallclock timeout; poll every 90 s** — use `*_request_async`. Poll `llm_job_status` no more than once every 90 seconds. Do **not** cancel reviewer jobs for taking too long; cancel only on explicit user instruction or a terminal provider/runtime failure. `idleTimeoutMs` (no-output safeguard) is separate.
+6. **Iterate until unconditional APPROVED** (review dispatches only) — every review prompt must end with a strict verdict requirement. On `NOT APPROVED`, `CHANGES_REQUIRED`, `BLOCKER`, or conditional approval, consolidate findings, apply fixes, refresh the verification report and exact diff/commit evidence, then re-dispatch the same reviewers. Repeat until unconditional approval or a concrete blocker remains after evidence-based rebuttal. This rule does **not** apply to pure implementation or non-review analysis dispatches.
+
+## Standard Validation Gate
+
+Use this gate whenever the user asks for "the other LLMs", "cross review",
+"red team", "validation", or similar review work.
+
+### Evidence Packet
+
+Before dispatch, prepare a stable packet and pass the same packet to every
+reviewer:
+
+- **Corrective-program verification report**: the local verification report used
+  as the spec for the review. It must list claims, commands run, test names,
+  command-result digests, and code/doc evidence.
+- **Exact change set**: commit SHA(s) when available, the diff range or explicit
+  `git diff` command, and the changed-file list. If the work is uncommitted,
+  state that clearly and include the exact dirty-file list.
+- **Scope and invariants**: DAG step(s), issue/PR references, security
+  invariants, docs that define intended behavior, and out-of-scope files.
+- **Review log from prior rounds**: verbatim reviewer findings plus per-finding
+  responses marked `FIXED`, `DISAGREE`, or `BLOCKER`, each with file:line, test,
+  command, or doc evidence.
+
+The packet is not a substitute for inspection. The prompt must explicitly say
+that the verification report and summary are claims, not evidence.
+
+### Reviewer Contract
+
+Every reviewer prompt must require:
+
+- Verify claims against actual code, tests, docs, and upstream documentation.
+- Open/read the changed files and relevant neighboring code directly.
+- Run or inspect the cited tests/builds; approval cannot be based on a summary,
+  intent, plan-compliance, or "should be fixed" language.
+- Cite concrete evidence for each finding: `file:line`, test name + command, or
+  upstream doc URL. If a claim cannot be verified, report it as at least a major
+  finding.
+- Return strict structured output with `verdict`, `findings`, `inspected`, and
+  `unconditional_approval_blockers`.
+
+Recommended final verdict enum:
+
+```json
+{
+  "verdict": "APPROVED | CHANGES_REQUIRED | BLOCKER",
+  "findings": [
+    {
+      "id": "F1",
+      "severity": "blocker | major | minor | nit",
+      "file": "src/example.ts",
+      "line": 123,
+      "claim": "Exact claim reviewed",
+      "issue": "What is wrong",
+      "evidence": "file:line, command/test output digest, URL, or unable to verify: reason",
+      "suggested_fix": "Concrete fix"
+    }
+  ],
+  "inspected": ["files, tests, commands, docs actually inspected"],
+  "unconditional_approval_blockers": ["F1"]
+}
+```
+
+### Evidence-Based Triage
+
+For every finding:
+
+- If correct: fix it, run the relevant local gates, update the verification
+  report, and start a new review round with a fresh exact change set.
+- If disputed: respond to that reviewer through the gateway with code/doc/test
+  evidence. Do not rebut with assertion, intent, "by design", or "the code should
+  already do that" unless accompanied by the exact evidence. The reviewer must
+  withdraw the finding or provide counter-evidence.
+- If unresolvable in scope: record it as a concrete `BLOCKER` with evidence and
+  stop advancing the change until the user decides scope.
+
+"Approved with nits" is not unconditional approval. Fix the nits or get the
+reviewer to withdraw them as non-blocking with evidence.
 
 ## Workflow
 
@@ -61,28 +140,30 @@ CLIs share Claude's tool names or MCP semantics. The same data is available as
 
 ### 2. Send Parallel Reviews
 
-Sync tools auto-defer at 45s — if response contains `status:"deferred"`, poll `jobId` via `llm_job_status` every 60s, fetch with `llm_job_result`.
+Sync tools auto-defer at 45s, but review gates should prefer async tools. Poll
+`jobId` via `llm_job_status` no more than once every 90s, fetch with
+`llm_job_result` only after a terminal status.
 
 **Tip — share the stable prefix across reviewers:** when the same long brief / file dump is sent to every reviewer, switch from `prompt` to the structured `promptParts` field. The gateway concatenates in canonical order `system → tools → context → task`, so every reviewer sees byte-identical stable prefix bytes, raising implicit cache hit rate at each provider. `prompt` and `promptParts` are mutually exclusive — the runtime returns `provide exactly one of \`prompt\` or \`promptParts\`` if both are supplied. After the round, read `cache-state://prefix/{hash}` (tokens/hashes only, no prompt text) to confirm reviewers actually shared the prefix.
 
 **Claude — Quality & Architecture:**
 ```
-claude_request({prompt:"Review changes in {path} for architecture, design patterns, maintainability, documentation gaps. Read the files directly. Specific line numbers and fixes. End with APPROVED or NOT APPROVED with findings.",approvalStrategy:"mcp_managed",optimizePrompt:true,optimizeResponse:true})
+claude_request_async({prompt:"Review the attached evidence packet and exact change set for architecture, design patterns, maintainability, and documentation gaps. The packet is a claim, not evidence. Verify against the changed files, neighboring source, tests, and docs directly. Cite file:line/test/doc evidence. Return strict JSON and end with APPROVED, CHANGES_REQUIRED, or BLOCKER.",approvalStrategy:"mcp_managed",optimizePrompt:true})
 ```
 
 **Codex — Logic & Correctness:**
 ```
-codex_request({prompt:"Analyze {path} for logic bugs, off-by-one, missing error handling, race conditions, test gaps. Read the files directly. Severity: critical/high/medium/low. End with APPROVED or NOT APPROVED with findings.",fullAuto:true,approvalStrategy:"mcp_managed",optimizePrompt:true,optimizeResponse:true})
+codex_request_async({prompt:"Review the attached evidence packet and exact change set for logic bugs, off-by-one errors, missing error handling, races, and test gaps. The packet is a claim, not evidence. Verify against code/tests/docs directly. Cite file:line/test/doc evidence. Return strict JSON and end with APPROVED, CHANGES_REQUIRED, or BLOCKER.",fullAuto:true,approvalStrategy:"mcp_managed",optimizePrompt:true})
 ```
 
 **Gemini — Security & Edge Cases:**
 ```
-gemini_request({prompt:"Security audit {path}: injection, auth bypasses, data leaks, OWASP Top 10, crash-causing edge cases. Read the files directly. End with APPROVED or NOT APPROVED with findings.",approvalStrategy:"mcp_managed",optimizePrompt:true,optimizeResponse:true})
+gemini_request_async({prompt:"Review the attached evidence packet and exact change set for security issues: injection, auth bypasses, data leaks, OWASP Top 10, and crash-causing edge cases. The packet is a claim, not evidence. Verify against code/tests/docs/upstream docs directly. Cite evidence. Return strict JSON and end with APPROVED, CHANGES_REQUIRED, or BLOCKER.",approvalStrategy:"mcp_managed",optimizePrompt:true})
 ```
 
 **Grok — Independent Diversity (optional 4th reviewer):**
 ```
-grok_request({prompt:"Independent review of {path}. Read the files directly. Flag issues the other reviewers may have missed, contradict findings you disagree with, and call out blind spots. End with APPROVED or NOT APPROVED with findings.",approvalStrategy:"mcp_managed",optimizePrompt:true,optimizeResponse:true})
+grok_request_async({prompt:"Independent review of the attached evidence packet and exact change set. The packet is a claim, not evidence. Verify against code/tests/docs directly, flag blind spots, and contradict weak findings with evidence. Return strict JSON and end with APPROVED, CHANGES_REQUIRED, or BLOCKER.",approvalStrategy:"mcp_managed",optimizePrompt:true})
 ```
 
 Add Grok when consensus matters (high-stakes changes, security-critical paths) or to break ties between the other three. Auth must already be set up (`grok login` OAuth or `GROK_CODE_XAI_API_KEY`).
@@ -122,7 +203,10 @@ grok_request_async({prompt:"Independent diversity review of all TS files in src/
 mistral_request_async({prompt:"Independent Vibe review of all TS files in src/... End with APPROVED or NOT APPROVED with findings.",approvalStrategy:"mcp_managed",correlationId:"review-mistral"})
 ```
 
-Poll with `llm_job_status` every 60s, retrieve with `llm_job_result` when terminal. Jobs are durable — if your polling wrapper times out, re-issue the same call (the gateway auto-dedups onto the live job) or fetch by `jobId` later (default 30-day retention).
+Poll with `llm_job_status` no more than once every 90s, retrieve with
+`llm_job_result` when terminal. Jobs are durable — if your polling wrapper times
+out, re-issue the same call (the gateway auto-dedups onto the live job) or fetch
+by `jobId` later (default 30-day retention).
 
 For iterative Gemini reviews, pass `sessionId` for resumability:
 
@@ -135,23 +219,34 @@ gemini_request_async({prompt:"Deep security audit of src/... End with APPROVED o
 
 These patterns undermine review quality and trigger review integrity warnings:
 
-- **Don't inline code in `<code>` blocks** — provide file paths and let reviewers read files directly
+- **Don't use non-stdio gateway surfaces** when the requested validation path is
+  the local stdio gateway.
+- **Don't provide only a summary** — provide the verification report and exact
+  change set, while requiring reviewers to verify against files/tests/docs
+  directly.
+- **Don't under-grant review access** — full read, test/build, and MCP
+  verification access is the default. A partial-access review is not a valid
+  approval unless the user explicitly accepts that limitation.
 - **Don't suppress tools** — never include "do not run tools" or "respond only based on code provided" in review prompts
 - **Don't use `allowedTools:[]`** for reviews — reviewers need tool access to
   verify claims
 - **Don't copy tool names between providers** — Claude's `Read` / `Grep` /
   `Glob` names are not Grok, Codex, Gemini, or Vibe allowlist names. Check
   `provider_tool_capabilities` first, or omit provider tool allowlists.
-- **Do provide file paths** — `"Review changes in src/auth.ts"` instead of dumping file contents
+- **Don't cancel reviewer jobs** just because they are slow. Let them reach a
+  terminal status unless the user explicitly says to stop them.
+- **Do provide file paths and exact diff identifiers** — `"Review commit
+  abc123, diff range base..head, changed files src/auth.ts ..."` instead of
+  vague summaries.
 
 ## Iteration Loop (mandatory)
 
 Reviews are not one-shot. The caller runs this loop:
 
 1. Dispatch reviewer(s) with the verdict clause in the prompt
-2. Poll every 60s if deferred; fetch result
+2. Poll every 90s if deferred; fetch result only after terminal status
 3. Parse verdict from each reviewer — APPROVED / NOT APPROVED / conditional
-4. **Any NOT APPROVED or conditional** → consolidate findings → dispatch fixes (Codex + `fullAuto:true`) → re-dispatch same review → goto 2
+4. **Any NOT APPROVED, CHANGES_REQUIRED, BLOCKER, or conditional** → triage each finding with evidence → fix or rebut with code/doc/test citations → refresh verification report and exact diff → re-dispatch same review → goto 2
 5. **All APPROVED (unconditional)** → done
 6. After 3 rounds without convergence, escalate to the user
 
@@ -169,6 +264,6 @@ Reviews are not one-shot. The caller runs this loop:
 - Use all five async variants for true parallel reviews when you want Grok's
   independent perspective and Mistral Vibe's fifth review
 - Pass `sessionId` to `gemini_request_async` / `grok_request_async` for resumable follow-up
-- Check for `status:"deferred"` in sync responses — poll `jobId` every 60s if present
+- Check for `status:"deferred"` in sync responses — poll `jobId` no more than once every 90s if present
 - Gateway `mcpServers` default to the host's configured Claude MCP set; pass explicit server names only when the review needs those capabilities
 - **Re-issuing after a polling timeout is safe** — auto-dedup (default 1 h window, `LLM_GATEWAY_DEDUP_WINDOW_MS`) reattaches the new call to the existing job. Use `forceRefresh:true` only when inputs genuinely changed

package/CHANGELOG.md

@@ -2,6 +2,75 @@
 
 All notable changes to the llm-cli-gateway project.
 
+## [2.13.2] - 2026-07-01: remote HTTP + OAuth connector UX and hardening
+
+### Added
+
+- **`remote_http_oauth` readiness projection in `doctor --json`.** A stable,
+  ordered 8-stage decision tree (`not_started`, `missing_public_url`,
+  `endpoint_unreachable`, `oauth_disabled`, `unsafe_oauth_config`,
+  `missing_oauth_client`, `missing_workspace`, `ready`) with deterministic,
+  secret-free `next_actions`, the copy-safe connector URLs, `oauth.consent_required`,
+  and a path-free workspace summary. Validated by `setup/status.schema.json`.
+- **`llm-cli-gateway connector setup` command.** Emits a copy-safe JSON connector
+  packet (MCP URL, authorization URL, token URL, client id, workspace guidance)
+  plus a human summary, reusing the readiness projection. The deprecated no-auth
+  connector URL is omitted unless `--include-legacy-no-auth` is passed.
+- **Centralized remote URL construction (`src/remote-url.ts`).** doctor, the
+  connector packet, the CLI OAuth output, the installer, and the runtime OAuth
+  well-known metadata + `WWW-Authenticate` challenge all derive URLs from one
+  helper so they cannot drift.
+
+### Changed
+
+- **OAuth-first remote connector docs and setup UI.** The ChatGPT guide,
+  endpoint-exposure runbook, `ENDPOINT_EXPOSURE.md`, and setup UI lead with the
+  OAuth path keyed on `remote_http_oauth.stage`; the no-auth connector is
+  compatibility-only. `oauth client add` validates the redirect URI and client
+  id before writing, refuses duplicate ids, and labels copy-once secret output.
+
+### Security
+
+- **F17 hardening.** The unsafe-OAuth (public clients / `open_dev`) start gate
+  now fails closed when the gateway is publicly exposed via a public URL or
+  tunnel, not only on a non-loopback bind.
+- **No local-path disclosure to remote clients.** Remote MCP `workspace_*`
+  tools, `session_get`, `sessions://*` resources, and worktree response paths
+  are path-redacted for remote HTTP/OAuth callers (local operators keep absolute
+  paths; resume metadata is unaffected). `workspace_register_existing_repo` no
+  longer acts as a filesystem existence oracle.
+- **Installer URL redaction.** The Go installer derives OAuth/MCP URLs from a
+  clean origin and strips userinfo/query/fragment from the stored public URL, so
+  no credential-bearing URL is emitted.
+- **gitleaks allowlist** now covers the `gateway-logger` redaction test fixtures
+  (deliberate fake tokens), restoring a green secret-scan gate.
+
+## [2.13.1] - 2026-07-01: code-scanning hardening and review-gate discipline
+
+### Security
+
+- **CodeQL remediation for URL, ReDoS, logging, and OAuth cookie alerts.**
+  API endpoint joining no longer uses slash-trimming regexes; ACP message
+  redaction now uses a stack-based single-pass JSON payload scanner with
+  truncated structured-payload fallback; central gateway stderr logging redacts
+  message strings, structured args, and nested `Error` name/message/stack
+  values; the xAI missing-key error no longer leaks the configured env var name;
+  and OAuth consent CSRF cookies now include `HttpOnly`, `Secure`,
+  `SameSite=Lax`, `Path=/oauth`, and `Max-Age=300`.
+- **Regression coverage for the fixed alert surfaces.** Added focused tests for
+  endpoint slash normalization, nested and truncated ACP payload redaction,
+  logger redaction before stderr output, generic xAI missing-key messaging, and
+  complete OAuth CSRF cookie attributes.
+
+### Docs
+
+- **Standardized cross-LLM review validation.** The shipped multi-LLM review
+  skill and best-practices guide now require the stdio gateway surface, no
+  provider model nomination, full non-interactive verification access,
+  90-second polling, exact evidence packets, no cancellation of slow reviewers,
+  evidence-based rebuttals, and iteration until unconditional approval or a
+  concrete blocker.
+
 ## [2.13.0] - 2026-07-01: Cursor Agent CLI provider
 
 ### Added

package/dist/acp/errors.js

@@ -1,7 +1,5 @@
 export function redactAcpMessage(input) {
-    let out = input;
-    out = out.replace(/\{[\s\S]*?\}/g, "<redacted-json>");
-    out = out.replace(/\[[\s\S]*?\]/g, "<redacted-json>");
+    let out = redactJsonLikeBodies(input);
     out = out.replace(/\b(bearer|token|api[_-]?key|secret)\b\s*[:=]?\s*\S+/gi, "$1 <redacted>");
     out = out.replace(/\b(sk|xai|gsk|key)-[A-Za-z0-9_-]{8,}\b/gi, "<redacted-token>");
     out = out.replace(/(^|[^A-Za-z0-9._~\\/-])[A-Za-z]:\\[^\s"')\]}>]*/g, "$1<redacted-path>");
@@ -11,6 +9,64 @@ export function redactAcpMessage(input) {
     out = out.replace(/[A-Z0-9._%+-]+@[A-Z0-9.-]+\.[A-Z]{2,}/gi, "<redacted-email>");
     return out;
 }
+function redactJsonLikeBodies(input) {
+    let out = "";
+    let cursor = 0;
+    let bodyStart = -1;
+    let stack = [];
+    let inString = false;
+    let escaped = false;
+    for (let index = 0; index < input.length; index += 1) {
+        const char = input.charAt(index);
+        if (bodyStart === -1) {
+            const close = char === "{" ? "}" : char === "[" ? "]" : "";
+            if (!close)
+                continue;
+            bodyStart = index;
+            stack = [close];
+            inString = false;
+            escaped = false;
+            continue;
+        }
+        if (escaped) {
+            escaped = false;
+            continue;
+        }
+        if (char === "\\") {
+            escaped = inString;
+            continue;
+        }
+        if (char === '"') {
+            inString = !inString;
+            continue;
+        }
+        if (inString)
+            continue;
+        const nestedClose = char === "{" ? "}" : char === "[" ? "]" : "";
+        if (nestedClose) {
+            stack.push(nestedClose);
+            continue;
+        }
+        if (char !== stack[stack.length - 1])
+            continue;
+        stack.pop();
+        if (stack.length > 0)
+            continue;
+        out += input.slice(cursor, bodyStart);
+        out += "<redacted-json>";
+        cursor = index + 1;
+        bodyStart = -1;
+    }
+    if (bodyStart !== -1 && isLikelyJsonPayload(input.slice(bodyStart))) {
+        out += input.slice(cursor, bodyStart);
+        out += "<redacted-json>";
+        cursor = input.length;
+    }
+    return cursor === 0 ? input : out + input.slice(cursor);
+}
+function isLikelyJsonPayload(span) {
+    return /"(?:jsonrpc|method|params|prompt|content|body|token|secret|api[_-]?key|credential|auth|cwd|path|[A-Za-z0-9_-]+)"\s*:/i.test(span);
+}
 export function redactAcpDebug(value) {
     const sensitiveKey = /(payload|body|prompt|content|token|secret|api[_-]?key|credential|auth|cwd|path)/i;
     if (typeof value === "string") {

package/dist/api-http.js

@@ -40,8 +40,8 @@ export function isLoopbackUrl(value) {
     }
 }
 export function buildEndpointUrl(baseUrl, path) {
-    const trimmedBase = baseUrl.replace(/\/+$/, "");
-    const trimmedPath = path.replace(/^\/+/, "");
+    const trimmedBase = stripTrailingSlashChars(baseUrl);
+    const trimmedPath = stripLeadingSlashChars(path);
     const url = new URL(`${trimmedBase}/${trimmedPath}`);
     if (url.protocol !== "https:" &&
         !(url.protocol === "http:" && LOOPBACK_HOSTS.includes(url.hostname))) {
@@ -49,6 +49,20 @@ export function buildEndpointUrl(baseUrl, path) {
     }
     return url;
 }
+function stripTrailingSlashChars(value) {
+    let end = value.length;
+    while (end > 0 && value.charCodeAt(end - 1) === 47) {
+        end -= 1;
+    }
+    return value.slice(0, end);
+}
+function stripLeadingSlashChars(value) {
+    let start = 0;
+    while (start < value.length && value.charCodeAt(start) === 47) {
+        start += 1;
+    }
+    return value.slice(start);
+}
 export function isHttpTransient(error) {
     const status = typeof error?.status === "number" ? error.status : null;
     if (status === 429 || (status !== null && status >= 500))

package/dist/config.d.ts

@@ -162,4 +162,12 @@ export interface AcpConfig {
     };
 }
 export declare function loadAcpConfig(logger?: Logger): AcpConfig;
+export type RemoteOAuthConfigStatus = "absent" | "disabled" | "enabled" | "malformed";
+export interface RemoteOAuthConfigDiagnostics {
+    config: RemoteOAuthConfig;
+    status: RemoteOAuthConfigStatus;
+    configured: boolean;
+    issues: string[];
+}
+export declare function diagnoseRemoteOAuthConfig(logger?: Logger, env?: NodeJS.ProcessEnv): RemoteOAuthConfigDiagnostics;
 export declare function loadRemoteOAuthConfig(logger?: Logger, env?: NodeJS.ProcessEnv): RemoteOAuthConfig;

package/dist/config.js

@@ -663,11 +663,7 @@ function disabledOAuthConfig(sourcePath = null, envOverrides = []) {
 function isSafeRedirectUri(uri) {
     return isHttpsOrLoopbackUrl(uri);
 }
-export function loadRemoteOAuthConfig(logger = noopLogger, env = process.env) {
-    const configPath = defaultGatewayConfigPath();
-    const { parsed: configFile, sourcePath } = readGatewayTomlFile(configPath, logger, "OAuth");
-    const rawHttp = configFile?.http ?? {};
-    const rawOAuth = rawHttp.oauth ?? {};
+function mergeOAuthEnvOverrides(rawOAuth, env) {
     const envOverrides = [];
     const merged = { ...rawOAuth };
     if (env.LLM_GATEWAY_OAUTH_ENABLED !== undefined) {
@@ -695,43 +691,43 @@ export function loadRemoteOAuthConfig(logger = noopLogger, env = process.env) {
         merged.require_consent = merged.require_consent ?? true;
         envOverrides.push("LLM_GATEWAY_OAUTH_CONSENT_SECRET");
     }
-    const parsed = OAuthConfigSchema.safeParse(merged);
-    if (!parsed.success) {
-        logWarn(logger, "Invalid [http.oauth] config; remote OAuth disabled", {
-            error: parsed.error.message,
-        });
-        return disabledOAuthConfig(sourcePath, envOverrides);
-    }
-    const data = parsed.data;
+    return { merged, envOverrides };
+}
+function validateParsedOAuthConfig(data, env, sourcePath, envOverrides, logger, issues) {
     if (data.issuer !== "auto" && !isHttpsOrLoopbackUrl(data.issuer)) {
         logWarn(logger, "Invalid [http.oauth].issuer; remote OAuth disabled");
-        return disabledOAuthConfig(sourcePath, envOverrides);
+        issues.push("OAuth issuer must be an https:// URL (or a loopback URL for local testing).");
+        return null;
     }
     for (const client of data.clients) {
         if (!data.allow_public_clients && !client.client_secret_hash) {
             logWarn(logger, "OAuth client secret hash is required when public clients are disabled", {
                 client_id: client.client_id,
             });
-            return disabledOAuthConfig(sourcePath, envOverrides);
+            issues.push("An OAuth client is missing a client_secret_hash (required when public clients are disabled). Recreate it with `llm-cli-gateway oauth client add`.");
+            return null;
         }
         if (client.client_secret_hash && !isSecretHash(client.client_secret_hash)) {
             logWarn(logger, "Invalid OAuth client secret hash; remote OAuth disabled", {
                 client_id: client.client_id,
             });
-            return disabledOAuthConfig(sourcePath, envOverrides);
+            issues.push("An OAuth client secret hash is not a valid scrypt hash. Rotate it with `llm-cli-gateway oauth client rotate`.");
+            return null;
         }
         if (client.allowed_redirect_uris.length === 0 ||
             client.allowed_redirect_uris.some(uri => !isSafeRedirectUri(uri))) {
             logWarn(logger, "Invalid OAuth client redirect URI; remote OAuth disabled", {
                 client_id: client.client_id,
             });
-            return disabledOAuthConfig(sourcePath, envOverrides);
+            issues.push("An OAuth client has a missing or non-https/loopback redirect URI. Re-add the client with a valid --redirect-uri.");
+            return null;
         }
     }
     if (data.shared_secret?.enabled) {
         if (!data.shared_secret.secret_hash || !isSecretHash(data.shared_secret.secret_hash)) {
             logWarn(logger, "Invalid [http.oauth.shared_secret] secret_hash; remote OAuth disabled");
-            return disabledOAuthConfig(sourcePath, envOverrides);
+            issues.push("The OAuth shared-secret hash is missing or invalid. Reset it with `llm-cli-gateway oauth shared-secret set`.");
+            return null;
         }
     }
     if (data.registration_policy === "open_dev" && env.LLM_GATEWAY_OAUTH_OPEN_DEV !== "1") {
@@ -740,7 +736,8 @@ export function loadRemoteOAuthConfig(logger = noopLogger, env = process.env) {
     if (data.require_consent) {
         if (!data.consent_secret_hash || !isSecretHash(data.consent_secret_hash)) {
             logWarn(logger, "[http.oauth].require_consent is set but consent_secret_hash is missing/invalid; remote OAuth disabled");
-            return disabledOAuthConfig(sourcePath, envOverrides);
+            issues.push("require_consent is set but the consent secret hash is missing or invalid. Set it with `llm-cli-gateway oauth shared-secret set` or LLM_GATEWAY_OAUTH_CONSENT_SECRET.");
+            return null;
         }
     }
     return {
@@ -769,3 +766,45 @@ export function loadRemoteOAuthConfig(logger = noopLogger, env = process.env) {
         sources: { configFile: sourcePath, envOverrides },
     };
 }
+export function diagnoseRemoteOAuthConfig(logger = noopLogger, env = process.env) {
+    const configPath = defaultGatewayConfigPath();
+    const { parsed: configFile, sourcePath } = readGatewayTomlFile(configPath, logger, "OAuth");
+    const rawHttp = configFile?.http ?? {};
+    const rawOAuth = rawHttp.oauth ?? {};
+    const { merged, envOverrides } = mergeOAuthEnvOverrides(rawOAuth, env);
+    const configured = Object.keys(rawOAuth).length > 0 || envOverrides.length > 0;
+    const parsed = OAuthConfigSchema.safeParse(merged);
+    if (!parsed.success) {
+        logWarn(logger, "Invalid [http.oauth] config; remote OAuth disabled", {
+            error: parsed.error.message,
+        });
+        return {
+            config: disabledOAuthConfig(sourcePath, envOverrides),
+            status: "malformed",
+            configured: true,
+            issues: [
+                "The [http.oauth] config is invalid (schema validation failed); remote OAuth is disabled.",
+            ],
+        };
+    }
+    const data = parsed.data;
+    const issues = [];
+    const built = validateParsedOAuthConfig(data, env, sourcePath, envOverrides, logger, issues);
+    if (!built) {
+        return {
+            config: disabledOAuthConfig(sourcePath, envOverrides),
+            status: data.enabled ? "malformed" : configured ? "disabled" : "absent",
+            configured,
+            issues: data.enabled ? issues : [],
+        };
+    }
+    const status = built.enabled
+        ? "enabled"
+        : configured
+            ? "disabled"
+            : "absent";
+    return { config: built, status, configured, issues: [] };
+}
+export function loadRemoteOAuthConfig(logger = noopLogger, env = process.env) {
+    return diagnoseRemoteOAuthConfig(logger, env).config;
+}

package/dist/connector-setup.d.ts

@@ -0,0 +1,39 @@
+import { type RemoteHttpOAuthReadiness } from "./doctor.js";
+import type { RemoteOAuthConfig } from "./auth.js";
+export declare const CONNECTOR_SETUP_SECRET_WARNING = "Never paste gateway bearer tokens, OAuth client secrets, OAuth access tokens, consent/shared secrets, tunnel tokens, or provider credentials into a remote chat transcript. Only the fields in this packet are safe to paste into a connector UI.";
+export interface ConnectorSetupOptions {
+    clientId?: string;
+    includeLegacyNoAuth?: boolean;
+}
+export interface ConnectorSetupPacket {
+    ok: boolean;
+    schema: "remote-connector-setup.v1";
+    ready: boolean;
+    stage: RemoteHttpOAuthReadiness["stage"];
+    auth_mode: RemoteHttpOAuthReadiness["auth_mode"];
+    connector: {
+        mcp_url: string | null;
+        authorization_url: string | null;
+        token_url: string | null;
+        client_id: string | null;
+        client_secret_required: boolean;
+        client_secret_source: string | null;
+    };
+    workspace: RemoteHttpOAuthReadiness["workspace"];
+    next_actions: string[];
+    warnings: string[];
+    legacy_no_auth?: {
+        deprecated: true;
+        connector_url: string | null;
+        note: string;
+    };
+}
+export declare function buildConnectorSetupPacket(input: {
+    readiness: RemoteHttpOAuthReadiness;
+    oauth: RemoteOAuthConfig;
+    options?: ConnectorSetupOptions;
+    legacyNoAuthUrl?: string | null;
+}): ConnectorSetupPacket;
+export declare function legacyNoAuthConnectorUrl(env?: NodeJS.ProcessEnv): string | null;
+export declare function gatherConnectorSetupPacket(options?: ConnectorSetupOptions, env?: NodeJS.ProcessEnv): ConnectorSetupPacket;
+export declare function renderConnectorSetupSummary(packet: ConnectorSetupPacket): string;