comisai 1.0.41 → 1.0.44

package/node_modules/@comis/daemon/dist/api/mcp-header-credential.js

@@ -0,0 +1,138 @@
+// SPDX-License-Identifier: Apache-2.0
+// @allow-throw: mcp-handlers helper — throws are caught and converted to JSON-RPC error responses by rpc-dispatch.ts:306-321.
+/**
+ * Header-credential lifecycle for mcp.connect and mcp.test.
+ *
+ * Classifies each (headerName, headerValue) pair in the headers block using
+ * `classifyHeaderCredential` from `@comis/core`, then:
+ *   - "ref"           → pass through unchanged
+ *   - "oauth-bearer"  → throw with [use_oauth_login] + actionable guidance
+ *   - "static-secret" → extract to secretStore, rewrite to ${VAR} ref
+ *                       or throw [plaintext_secret_in_headers] if no store
+ *
+ * Called from mcp.connect + mcp.test BEFORE contract parse so the mutated
+ * headers map (with ${VAR} refs) is what flows into buildPersistedMcpEntry
+ * and McpServerConfig. The input `headers` object is MUTATED in place so
+ * the caller's pre-parse `userParams` copy sees the rewritten ${VAR} values
+ * (for persistence). The returned `resolvedHeaders` map carries the original
+ * RAW values so the immediate live connect uses the real credential — not the
+ * unresolved `${VAR}` literal.
+ *
+ * When `plaintextOptOut` is true, oauth-bearer still throws unconditionally
+ * (the token will expire; the PKCE flow is the correct answer), but
+ * static-secret detection logs a WARN and passes through (caller bears risk).
+ *
+ * @module
+ */
+import { classifyHeaderCredential } from "@comis/core";
+/**
+ * Derive a `${VAR}` variable name from a server id + header name.
+ *
+ * Pattern: `MCP_<SERVERID_UPPER>__<HEADERNAME_UPPER_SLUG>`
+ *
+ * The DOUBLE-UNDERSCORE `__` separator prevents collisions between server
+ * and header segments. With a single `_` separator,
+ * ("foo-bar", "Key") and ("foo", "Bar-Key") both collapse to `MCP_FOO_BAR_KEY`.
+ * The double underscore guarantees distinctness because neither segment ever
+ * contains `__` after slugification (slugify replaces any non-[A-Z0-9] run
+ * with a single `_`).
+ *
+ * Non-empty sentinels ("SERVER" / "HEADER") guard against all-symbol inputs
+ * that would otherwise produce empty segments.
+ *
+ * Examples:
+ *   buildVarName("higgsfield", "Authorization") → "MCP_HIGGSFIELD__AUTHORIZATION"
+ *   buildVarName("context7", "X-Api-Key")       → "MCP_CONTEXT7__X_API_KEY"
+ *   buildVarName("foo-bar", "Key")              → "MCP_FOO_BAR__KEY"  (distinct from...)
+ *   buildVarName("foo", "Bar-Key")              → "MCP_FOO__BAR_KEY"  (...this one)
+ */
+export function buildVarName(serverId, headerName) {
+    const slug = (s) => s
+        .toUpperCase()
+        .replace(/[^A-Z0-9]+/g, "_")
+        .replace(/^_+|_+$/g, "");
+    const s = slug(serverId) || "SERVER";
+    const h = slug(headerName) || "HEADER";
+    return `MCP_${s}__${h}`;
+}
+/**
+ * Process all headers in `headers` map in place.
+ *
+ * For each header:
+ *   - "ref" → skip (already ${VAR}-form)
+ *   - "oauth-bearer" → ALWAYS throw with [use_oauth_login] (no opt-out — OAuth
+ *     tokens expire; the PKCE flow is the correct answer)
+ *   - "static-secret" + secretStore defined → extract, rewrite to ${VAR}, continue
+ *   - "static-secret" + secretStore undefined + !plaintextOptOut → throw [plaintext_secret_in_headers]
+ *   - "static-secret" + plaintextOptOut → WARN, pass through (operator bears risk)
+ *
+ * Returns `{ resolvedHeaders }` — a map of header values for the LIVE connect,
+ * where extracted static-secret entries carry the original raw value (not the
+ * `${VAR}` ref written into `headers`). This ensures the immediate connect uses
+ * the real credential rather than an unresolved `${VAR}` literal.
+ *
+ * @throws Error with [use_oauth_login] or [plaintext_secret_in_headers] marker
+ */
+export function processHeaderCredentials(opts) {
+    const { headers, serverName, secretStore, plaintextOptOut, logger, method } = opts;
+    // resolvedHeaders starts as a copy of the input; we update it below
+    // where a static-secret extraction would otherwise set ${VAR}.
+    const resolvedHeaders = { ...headers };
+    for (const [headerName, headerValue] of Object.entries(headers)) {
+        if (typeof headerValue !== "string")
+            continue;
+        const { kind } = classifyHeaderCredential(headerName, headerValue);
+        if (kind === "ref") {
+            // Already ${VAR}-form — pass through, no extraction needed.
+            // resolvedHeaders already has the ${VAR} value (copied above).
+            continue;
+        }
+        if (kind === "oauth-bearer") {
+            // OAuth bearer refusal is UNCONDITIONAL — no opt-out.
+            // The token will expire; auth:"oauth" + comis mcp login is the fix.
+            throw new Error(`[use_oauth_login] headers.${headerName} (server "${serverName}") ` +
+                `contains a short-lived OAuth bearer token that will expire on restart. ` +
+                `Remove the header, set auth:"oauth" in the server config, and run ` +
+                `"comis mcp login ${serverName}" to authenticate via the PKCE flow.`);
+        }
+        // kind === "static-secret"
+        if (plaintextOptOut) {
+            logger.warn({
+                method,
+                entityId: serverName,
+                hint: "disablePlaintextSecretCheck=true — plaintext header passed through",
+                errorKind: "config",
+            }, "MCP headers plaintext-secret check disabled per-server");
+            // resolvedHeaders already has the raw value (copied above).
+            continue;
+        }
+        if (!secretStore) {
+            // Fail-safe: no store available → refuse rather than persist plaintext.
+            throw new Error(`[plaintext_secret_in_headers] headers.${headerName} (server "${serverName}") ` +
+                `looks like a plaintext credential and no encrypted secret store is available. ` +
+                `Hint: ensure security.storage is not set to 'file' or 'env' in your config.yaml, or store ` +
+                `the secret via secrets_manage and reference it as "\${VAR}".`);
+        }
+        // Extract: derive var name, call secretStore.set, rewrite header value.
+        // resolvedHeaders keeps the raw value (for the live connect).
+        // headers[headerName] is rewritten to ${VAR} (for persistence/config.yaml).
+        const varName = buildVarName(serverName, headerName);
+        const result = secretStore.set(varName, headerValue);
+        if (!result.ok) {
+            throw new Error(`[plaintext_secret_in_headers] Failed to extract headers.${headerName} ` +
+                `(server "${serverName}") to secret store: ${result.error.message}. ` +
+                `Hint: fix the secret store, then retry.`);
+        }
+        // Live-apply: upsert into the shared SecretManager Map so broker/exec observe the new
+        // value on their next request without a restart (additive no-restart — P4a).
+        // Optional chaining guards callers (tests, legacy paths) that don't wire the handle.
+        opts.mutableSecretManager?.upsert(varName, headerValue);
+        // Rewrite the header value in place to the ${VAR} reference (for persistence).
+        // resolvedHeaders already holds the raw value from the initial copy above.
+        // static-secret means NO Bearer scheme in the raw value (classifyHeaderCredential
+        // returns "oauth-bearer" for Bearer+secret; "static-secret" is bare value only).
+        headers[headerName] = `\${${varName}}`;
+        // resolvedHeaders[headerName] stays as the original raw value (already set above).
+    }
+    return { resolvedHeaders };
+}

package/node_modules/@comis/daemon/dist/api/mcp-oauth-handlers.d.ts

@@ -0,0 +1,99 @@
+/**
+ * MCP OAuth RPC handler module.
+ *
+ * Two admin-only handlers, 1:1 with `mcp-oauth.ts` contracts (field parity):
+ *   - `mcp.oauth_login`  — coordinate the server-side OAuth login (discovery +
+ *     PKCE + the loopback browser-callback), persist tokens, reconnect, and
+ *     RETURN the authorization URL for the CLI to open.
+ *   - `mcp.oauth_logout` — clear the three on-disk token files so the next
+ *     connect forces re-auth.
+ *
+ * ── Browser launch is CLI-side ──────────────────────────────────────────────
+ * This module NEVER imports `open` and the daemon NEVER launches a browser (it
+ * may run on a remote host). `mcp.oauth_login` runs the loopback callback server
+ * + the SDK `auth()` flow server-side (via the `runOauthLogin` orchestrator in
+ * `@comis/skills`, which owns the SDK dependency) and returns `authUrl` (+ a
+ * `portForwardHint` on a headless host) for the CLI to act on. The injected
+ * `openUrl` is a daemon-side NO-OP.
+ *
+ * ── No throw escapes the login handler ──────────────────────────────────────
+ * Login failures (discovery cascade fail, callback timeout / CSRF, exchange
+ * error) return `status: "failed"` — the orchestrator catches and reports rather
+ * than throwing. The handler's own pre-flight guards (missing server, not an
+ * `auth:"oauth"` server) DO throw for the actionable "Missing required
+ * parameter" / "not configured for OAuth" UX (the dispatcher converts to a
+ * JSON-RPC error), matching the `mcp-handlers.ts` convention.
+ *
+ * ── Field parity ─────────────────────────────────────────────────────────────
+ * Both handlers reference `server_name` literally (it keys the token store +
+ * the reconnect target). `test/architecture/contract-handler-parity.test.ts`
+ * auto-discovers this `-handlers.ts` file and asserts the 1:1 field parity.
+ *
+ * SECURITY: tokens, the PKCE `code_verifier`, the CSRF `state`, and the
+ * authorization `code` are NEVER logged. The orchestrator owns the secret
+ * lifecycle; this handler only logs the server name + the login status.
+ *
+ * @module
+ */
+import { type OAuthLoginResult, type RunOauthLoginDeps, type TokenStore } from "@comis/skills";
+import type { WorkspaceApiDeps, RpcHandler } from "./types.js";
+/**
+ * Deps for the MCP OAuth handlers. Reuses the {@link WorkspaceApiDeps} slice
+ * (already carries `mcpClientManager`, `logger`, `container` for the persisted
+ * server config). The login orchestrator + token-store factory are injectable so
+ * unit tests supply a fake login runner + a tmpdir-backed store; production
+ * defaults to the real `@comis/skills` exports.
+ */
+export interface McpOauthHandlerDeps extends WorkspaceApiDeps {
+    /**
+     * The interactive OAuth login orchestrator (server-side discovery + callback +
+     * SDK auth() + saveTokens). Defaults to the real `@comis/skills` `runOauthLogin`.
+     */
+    readonly runOauthLogin?: (deps: RunOauthLoginDeps) => Promise<OAuthLoginResult>;
+    /**
+     * The mode-selected MCP OAuth token-store factory (selectMcpTokenStore via the
+     * daemon's pass-through). Returns the SAME instance the manager wiring uses.
+     * MAY return undefined in `env` storage mode (no writable store) — the login
+     * handler guards on that and fails loudly rather than falling back to a
+     * plaintext disk store. Used by `oauth_logout` to clear credentials and
+     * threaded into the login orchestrator so the exchange persists to the
+     * mode-selected backend.
+     */
+    readonly createTokenStore?: () => TokenStore | undefined;
+    /**
+     * Browser-launch side effect. ALWAYS a daemon-side NO-OP — the daemon never
+     * opens a browser; the CLI opens the returned `authUrl`. Injectable so tests
+     * can assert it is never a real `open` import.
+     */
+    readonly openUrl?: (url: string) => void;
+    /**
+     * Push a short completion message back to the operator's channel after a
+     * headless OAuth login successfully connects the MCP server (Fix 9). Fixes
+     * 4 + 6 + 8 land the connection asynchronously: the RPC returns
+     * `headless_hint` immediately, the operator authorizes in their browser,
+     * and the daemon-side background task completes the token exchange + the
+     * `manager.connect`. There is no path that wakes the agent at the moment
+     * of completion, so without this hook the agent stays silent until the
+     * operator explicitly asks "is it connected?" (observed 2026-05-28 against
+     * the live Higgsfield install — 27 tools discovered, agent silent).
+     *
+     * Wired by `rpc-dispatch.ts` to
+     * `deliveryService.deliverToChannel(adaptersByType[channelType], …)` —
+     * the same chokepoint `message.send` uses. The target is captured from
+     * the RPC's `_deliveryTarget` (`setup-tools.ts:289-303` injects this
+     * onto every agent-initiated call). Optional — undefined skips the
+     * notification cleanly (e.g., CLI-initiated logins where there is no
+     * channel to address; the operator sees the result in their terminal).
+     */
+    readonly notifyOperatorChannel?: (target: {
+        channelType: string;
+        channelId: string;
+        userId?: string;
+        tenantId?: string;
+    }, text: string) => Promise<void>;
+}
+/**
+ * Create the MCP OAuth RPC handlers bound to the given deps. Returns exactly the
+ * two keys `[McpOauthLoginContract.method, McpOauthLogoutContract.method]`.
+ */
+export declare function createMcpOauthHandlers(deps: McpOauthHandlerDeps): Record<string, RpcHandler>;

package/node_modules/@comis/daemon/dist/api/mcp-oauth-handlers.js

@@ -0,0 +1,308 @@
+// SPDX-License-Identifier: Apache-2.0
+// @allow-throw: RPC handler module — all throws are caught and converted to JSON-RPC error responses by rpc-dispatch.ts:306-321.
+/**
+ * MCP OAuth RPC handler module.
+ *
+ * Two admin-only handlers, 1:1 with `mcp-oauth.ts` contracts (field parity):
+ *   - `mcp.oauth_login`  — coordinate the server-side OAuth login (discovery +
+ *     PKCE + the loopback browser-callback), persist tokens, reconnect, and
+ *     RETURN the authorization URL for the CLI to open.
+ *   - `mcp.oauth_logout` — clear the three on-disk token files so the next
+ *     connect forces re-auth.
+ *
+ * ── Browser launch is CLI-side ──────────────────────────────────────────────
+ * This module NEVER imports `open` and the daemon NEVER launches a browser (it
+ * may run on a remote host). `mcp.oauth_login` runs the loopback callback server
+ * + the SDK `auth()` flow server-side (via the `runOauthLogin` orchestrator in
+ * `@comis/skills`, which owns the SDK dependency) and returns `authUrl` (+ a
+ * `portForwardHint` on a headless host) for the CLI to act on. The injected
+ * `openUrl` is a daemon-side NO-OP.
+ *
+ * ── No throw escapes the login handler ──────────────────────────────────────
+ * Login failures (discovery cascade fail, callback timeout / CSRF, exchange
+ * error) return `status: "failed"` — the orchestrator catches and reports rather
+ * than throwing. The handler's own pre-flight guards (missing server, not an
+ * `auth:"oauth"` server) DO throw for the actionable "Missing required
+ * parameter" / "not configured for OAuth" UX (the dispatcher converts to a
+ * JSON-RPC error), matching the `mcp-handlers.ts` convention.
+ *
+ * ── Field parity ─────────────────────────────────────────────────────────────
+ * Both handlers reference `server_name` literally (it keys the token store +
+ * the reconnect target). `test/architecture/contract-handler-parity.test.ts`
+ * auto-discovers this `-handlers.ts` file and asserts the 1:1 field parity.
+ *
+ * SECURITY: tokens, the PKCE `code_verifier`, the CSRF `state`, and the
+ * authorization `code` are NEVER logged. The orchestrator owns the secret
+ * lifecycle; this handler only logs the server name + the login status.
+ *
+ * @module
+ */
+import { McpOauthLoginContract, McpOauthLogoutContract, stripInternalFields, systemGetEnv, } from "@comis/core";
+import { runOauthLogin as defaultRunOauthLogin, } from "@comis/skills";
+// ---------------------------------------------------------------------------
+// Helpers
+// ---------------------------------------------------------------------------
+/** Read the persisted MCP server entry by name (or undefined). */
+function findServerEntry(deps, serverName) {
+    const servers = (deps.container?.config?.integrations?.mcp?.servers ?? []);
+    return servers.find((s) => s.name === serverName);
+}
+// ---------------------------------------------------------------------------
+// Factory
+// ---------------------------------------------------------------------------
+/**
+ * Create the MCP OAuth RPC handlers bound to the given deps. Returns exactly the
+ * two keys `[McpOauthLoginContract.method, McpOauthLogoutContract.method]`.
+ */
+export function createMcpOauthHandlers(deps) {
+    // The daemon NEVER opens a browser. A no-op is the default
+    // (the CLI opens the returned authUrl). Injectable only so tests can assert it.
+    const openUrl = deps.openUrl ?? (() => undefined);
+    const runOauthLogin = deps.runOauthLogin ?? defaultRunOauthLogin;
+    // Fail loudly — never fall back to a plaintext disk store. The token store is
+    // the ONE mode-selected instance (selectMcpTokenStore) threaded via the
+    // daemon pass-through `() => boot.mcpTokenStore`. In `env` storage mode that
+    // factory is absent OR returns undefined (no writable MCP OAuth store); both
+    // shapes mean "no place to persist MCP OAuth credentials". Surface an
+    // actionable storage-mode error (this module is `// @allow-throw:` —
+    // rpc-dispatch.ts:306-321 converts it to a JSON-RPC error) instead of silently
+    // downgrading to a plaintext `mcp-tokens/` write that the mode-selected
+    // manager would never read back (the split-brain this fix removes).
+    const resolveTokenStore = () => {
+        const store = deps.createTokenStore?.();
+        if (store === undefined) {
+            throw new Error('MCP OAuth login requires security.storage "file" or "encrypted" ' +
+                "(current mode has no credential store).");
+        }
+        return store;
+    };
+    return {
+        [McpOauthLoginContract.method]: async (rawParams) => {
+            // Bespoke pre-Zod guard — produces the legacy "Missing required parameter:
+            // server_name" UX. The contract's `.min(1)` is defense-in-depth.
+            const nameRaw = rawParams.server_name;
+            if (!nameRaw)
+                throw new Error("Missing required parameter: server_name");
+            // Capture the operator's channel target BEFORE stripping internals so
+            // the headless background completion (Fix 9) can push a notification
+            // back to the same chat that initiated this login. The dispatcher
+            // injects `_deliveryTarget` on every agent-initiated RPC at
+            // `setup-tools.ts:289-303`; CLI-initiated `comis mcp login` calls
+            // omit it (operator sees the result in their terminal).
+            const deliveryTarget = rawParams._deliveryTarget;
+            // Strip dispatcher-injected _X internals BEFORE contract parse.
+            const userParams = stripInternalFields(rawParams);
+            const params = McpOauthLoginContract.request.parse(userParams);
+            // Field parity: reference server_name literally (it keys the token store + reconnect).
+            const server_name = params.server_name;
+            // Resolve the persisted server config. Login requires an `auth:"oauth"`
+            // server with a URL (the SDK needs the resource-server URL for discovery).
+            const entry = findServerEntry(deps, server_name);
+            if (!entry) {
+                throw new Error(`MCP server not found: "${server_name}"`);
+            }
+            if (entry.auth !== "oauth") {
+                throw new Error(`MCP server "${server_name}" is not configured for OAuth (auth: "oauth" required).`);
+            }
+            if (!entry.url) {
+                throw new Error(`MCP server "${server_name}" has no url; OAuth discovery requires a remote (sse/http) server URL.`);
+            }
+            // Resolve the mode-selected token store BEFORE driving the login. Fail
+            // loudly here (at the handler boundary, so the dispatcher returns a clear
+            // JSON-RPC error) rather than inside runOauthLogin — the orchestrator
+            // catches its own errors and would mask the storage-mode signal as a
+            // generic status:"failed". In env mode there is no writable store; we must
+            // never fall back to a plaintext mcp-tokens/ write.
+            const tokenStore = resolveTokenStore();
+            // Run the server-side login. The orchestrator owns the SDK auth() call +
+            // the loopback callback + saveTokens; it NEVER throws. The daemon
+            // openUrl is a no-op — the CLI opens the returned authUrl.
+            //
+            // Fix 6: on the headless path, runOauthLogin returns immediately with
+            // status:"headless_hint" while a background task keeps the loopback
+            // alive and awaits the operator's redirect. When the redirect arrives
+            // and tokens are persisted, that background task fires `onAuthorized`
+            // so the live connection upgrades to the new bearer without an
+            // additional RPC. The non-headless path still returns "authorized"
+            // synchronously and the post-call branch below handles the reconnect.
+            //
+            // Fix 8: the hook calls manager.connect (NOT reconnect). Fix 4 in
+            // mcp-handlers.ts short-circuits the initial manager.connect when
+            // params.auth==="oauth" AND no token exists yet, so state.serverConfigs
+            // is empty at the moment OAuth completes. manager.reconnect throws
+            // "no stored config -- use connect() instead" against an empty map;
+            // we build the McpServerConfig from the persisted entry (Fix 4
+            // wrote it to container.config.integrations.mcp.servers + disk) and
+            // hand it straight to manager.connect, which threads through
+            // prepareOAuthProvider and reads the now-valid tokens from the store.
+            const result = await runOauthLogin({
+                serverName: server_name,
+                serverUrl: entry.url,
+                oauthConfig: entry.oauth ?? {},
+                // Hand the already-resolved (guaranteed non-undefined) store to the
+                // orchestrator. The guard above already failed loudly if none exists.
+                createTokenStore: () => tokenStore,
+                openUrl,
+                onAuthorized: async (name) => {
+                    const persistedServers = (deps.container?.config?.integrations?.mcp?.servers ?? []);
+                    const persistedEntry = persistedServers.find((s) => s.name === name);
+                    if (persistedEntry === undefined) {
+                        throw new Error(`Persisted entry for "${name}" not found after OAuth — config out of sync; ` +
+                            `retry mcp_manage(action:"connect", server_name:"${name}").`);
+                    }
+                    const mcpConfigRoot = deps.container?.config?.integrations?.mcp;
+                    // Map the persisted entry to an McpServerConfig. The shapes overlap
+                    // by design (McpServerEntrySchema is the persistence projection of
+                    // McpServerConfig minus runtime-only fields like `oauthProvider`),
+                    // so this is a field-by-field copy. The integrations.mcp root
+                    // settings (safety/OSV) are merged in last — they live above the
+                    // per-entry shape and the manager reads them from the config root.
+                    const reconnectConfig = {
+                        name: persistedEntry.name,
+                        transport: persistedEntry.transport,
+                        enabled: true,
+                        ...(persistedEntry.command !== undefined && { command: persistedEntry.command }),
+                        ...(persistedEntry.args !== undefined && { args: persistedEntry.args }),
+                        ...(persistedEntry.url !== undefined && { url: persistedEntry.url }),
+                        ...(persistedEntry.env !== undefined && { env: persistedEntry.env }),
+                        ...(persistedEntry.cwd !== undefined && { cwd: persistedEntry.cwd }),
+                        ...(persistedEntry.headers !== undefined && { headers: persistedEntry.headers }),
+                        ...(persistedEntry.maxConcurrency !== undefined && { maxConcurrency: persistedEntry.maxConcurrency }),
+                        ...(persistedEntry.rlimits !== undefined && { rlimits: persistedEntry.rlimits }),
+                        ...(persistedEntry.keepaliveIntervalMs !== undefined && { keepaliveIntervalMs: persistedEntry.keepaliveIntervalMs }),
+                        ...(persistedEntry.circuitBreakerThreshold !== undefined && { circuitBreakerThreshold: persistedEntry.circuitBreakerThreshold }),
+                        ...(persistedEntry.circuitBreakerCooldownMs !== undefined && { circuitBreakerCooldownMs: persistedEntry.circuitBreakerCooldownMs }),
+                        ...(persistedEntry.toolAllowlist !== undefined && { toolAllowlist: persistedEntry.toolAllowlist }),
+                        ...(persistedEntry.toolBlocklist !== undefined && { toolBlocklist: persistedEntry.toolBlocklist }),
+                        ...(persistedEntry.idleTtlMs !== undefined && persistedEntry.idleTtlMs > 0 && { idleTtlMs: persistedEntry.idleTtlMs }),
+                        ...(persistedEntry.enableResources !== undefined && { enableResources: persistedEntry.enableResources }),
+                        ...(persistedEntry.enablePrompts !== undefined && { enablePrompts: persistedEntry.enablePrompts }),
+                        ...(persistedEntry.supportsParallelToolCalls !== undefined && { supportsParallelToolCalls: persistedEntry.supportsParallelToolCalls }),
+                        ...(persistedEntry.auth !== undefined && { auth: persistedEntry.auth }),
+                        ...(persistedEntry.oauth !== undefined && { oauth: persistedEntry.oauth }),
+                        ...(mcpConfigRoot?.safetyAllowedEnvKeys !== undefined && { safetyAllowedEnvKeys: mcpConfigRoot.safetyAllowedEnvKeys }),
+                        ...(mcpConfigRoot?.osvCheckEnabled !== undefined && { osvCheckEnabled: mcpConfigRoot.osvCheckEnabled }),
+                        ...(mcpConfigRoot?.osvCacheTtlMs !== undefined && { osvCacheTtlMs: mcpConfigRoot.osvCacheTtlMs }),
+                    };
+                    const connectResult = await deps.mcpClientManager.connect(reconnectConfig);
+                    if (!connectResult.ok) {
+                        // Tokens persisted but connect failed — surface a WARN so the
+                        // operator knows to retry. Throwing propagates to runOauthLogin's
+                        // background try/catch which logs a fallback WARN.
+                        throw new Error(connectResult.error.message);
+                    }
+                    // Fix 9: push a short completion message back to the operator's
+                    // channel. Without this the agent stays silent until the operator
+                    // asks "is X connected?" (observed 2026-05-28: 27 Higgsfield
+                    // tools discovered, agent silent). Skip cleanly when the login
+                    // came in without a channel target (CLI-initiated) OR when the
+                    // notify hook is unwired (test harnesses). A notification failure
+                    // does NOT roll back the persisted tokens or the live connection
+                    // — it is purely a UX side-effect, logged at WARN if it throws.
+                    if (deliveryTarget !== undefined && deps.notifyOperatorChannel !== undefined) {
+                        const toolCount = connectResult.value.tools.length;
+                        try {
+                            await deps.notifyOperatorChannel(deliveryTarget, `✓ MCP server "${name}" connected — ${toolCount} tool${toolCount === 1 ? "" : "s"} available.`);
+                        }
+                        catch (notifyErr) {
+                            deps.logger.warn({
+                                method: "mcp.oauth_login",
+                                entityId: name,
+                                err: notifyErr instanceof Error ? notifyErr : new Error(String(notifyErr)),
+                                hint: "Headless OAuth + connect succeeded; only the operator notification failed. The connection is live; tools are registered.",
+                                errorKind: "platform",
+                            }, "Headless-OAuth completion notification failed");
+                        }
+                    }
+                },
+                logger: deps.logger,
+            });
+            // On authorized: reconnect so the now-valid provider attaches and tools load.
+            if (result.status === "authorized") {
+                const reconnectResult = await deps.mcpClientManager.reconnect(server_name);
+                if (!reconnectResult.ok) {
+                    // Tokens persisted but reconnect failed — surface as failed so the
+                    // operator retries the connect; do NOT claim authorized.
+                    deps.logger.warn({
+                        method: "mcp.oauth_login",
+                        entityId: server_name,
+                        err: reconnectResult.error.message,
+                        hint: "OAuth tokens persisted but the server failed to reconnect; retry mcp.reconnect",
+                        errorKind: "config",
+                    }, "OAuth login persisted tokens but reconnect failed");
+                    const failedReconnect = {
+                        server_name,
+                        status: "failed",
+                        ...(result.authUrl !== undefined ? { authUrl: result.authUrl } : {}),
+                    };
+                    if (systemGetEnv("NODE_ENV") !== "production") {
+                        McpOauthLoginContract.response.parse(failedReconnect);
+                    }
+                    return failedReconnect;
+                }
+            }
+            const response = {
+                server_name,
+                status: result.status,
+                ...(result.portForwardHint !== undefined
+                    ? { portForwardHint: result.portForwardHint }
+                    : {}),
+                ...(result.authUrl !== undefined ? { authUrl: result.authUrl } : {}),
+                // Device-flow path surfaces verification fields. Non-
+                // secret per RFC 8628 §6.1 (userCode is one-shot + time-bound;
+                // verificationUri is the provider's public endpoint). Conditional-
+                // spread keeps the PKCE path's response shape unchanged.
+                ...(result.verificationUri !== undefined
+                    ? { verificationUri: result.verificationUri }
+                    : {}),
+                ...(result.userCode !== undefined ? { userCode: result.userCode } : {}),
+                ...(result.expiresIn !== undefined ? { expiresIn: result.expiresIn } : {}),
+            };
+            // Dev-mode response validation gate.
+            if (systemGetEnv("NODE_ENV") !== "production") {
+                McpOauthLoginContract.response.parse(response);
+            }
+            return response;
+        },
+        [McpOauthLogoutContract.method]: async (rawParams) => {
+            // Bespoke pre-Zod guard — produces the legacy "Missing required parameter:
+            // server_name" UX. The contract's `.min(1)` is defense-in-depth.
+            const nameRaw = rawParams.server_name;
+            if (!nameRaw)
+                throw new Error("Missing required parameter: server_name");
+            // Strip dispatcher-injected _X internals BEFORE contract parse.
+            const userParams = stripInternalFields(rawParams);
+            const params = McpOauthLogoutContract.request.parse(userParams);
+            // Field parity: reference server_name literally (it keys the token-store deletion).
+            const server_name = params.server_name;
+            // Gate the destructive deleteAll() on the same persisted-server
+            // existence check the login handler uses. Without this guard an
+            // admin-scope caller could clear token files for ANY string the
+            // `safePath` substrate accepts under mcp-tokens/ — including names that
+            // were never configured (a typo, or another daemon's tokens in a shared
+            // directory). The schema-level `/^[a-zA-Z0-9_-]+$/` constraint lives on
+            // McpServerEntrySchema, NOT on the RPC contract, so the contract alone
+            // does not stop arbitrary names. Mirror the login handler's guard.
+            const entry = findServerEntry(deps, server_name);
+            if (!entry) {
+                throw new Error(`MCP server not found: "${server_name}"`);
+            }
+            // Clear the stored MCP OAuth credentials for the server. deleteAll is
+            // idempotent — clearing an already-absent set still succeeds, so
+            // cleared:true reflects "no credentials remain". A close() releases the
+            // store's disk-watch (no-op for the encrypted store). resolveTokenStore
+            // fails loudly in env mode (no writable store) rather than constructing a
+            // plaintext disk store just to delete from it.
+            const tokenStore = resolveTokenStore();
+            await tokenStore.deleteAll(server_name);
+            await tokenStore.close();
+            deps.logger.info({ method: "mcp.oauth_logout", entityId: server_name }, "OAuth credentials cleared; next connect forces re-auth");
+            const response = { server_name, cleared: true };
+            // Dev-mode response validation gate.
+            if (systemGetEnv("NODE_ENV") !== "production") {
+                McpOauthLogoutContract.response.parse(response);
+            }
+            return response;
+        },
+    };
+}

package/node_modules/@comis/daemon/dist/api/mcp-persisted-entry.d.ts

@@ -0,0 +1,96 @@
+/**
+ * Build the persisted `McpServerEntry` for the `mcp.connect` RPC handler.
+ *
+ * Extracted from `mcp-handlers.ts` to keep that leaf under the 800-line
+ * per-file cap AND — more importantly — to give a SINGLE SOURCE OF TRUTH for
+ * "which per-server fields flow through to persistence". That exact concern
+ * was missed twice in a row (an earlier change dropped the tool filters /
+ * resources-prompts opt-outs from the runtime config; another dropped
+ * them — plus supportsParallelToolCalls — from the PERSISTED entry, a security
+ * regression). Co-locating the construction here makes the field set auditable
+ * in one place.
+ *
+ * The split between the runtime `McpServerConfig` (built inline in the handler,
+ * consumed by `manager.connect`) and this persisted `McpServerEntry` (written
+ * back to config.yaml via `persistMcpServers`) is deliberate: the runtime
+ * object carries spawn-time-only fields (safetyAllowedEnvKeys, osvCheckEnabled,
+ * osvCacheTtlMs) that must NOT be persisted, while this entry carries only the
+ * schema-validated `McpServerEntry` shape.
+ *
+ * **Reconnect invariant:** mcp.connect has NO RPC params for the config-only fields
+ * (toolAllowlist, toolBlocklist, enableResources, enablePrompts,
+ * supportsParallelToolCalls, idleTtlMs). Their only source on a reconnect /
+ * re-add is the existing persisted entry — so they are conditionally spread
+ * from `persistedEntry` here. Dropping toolAllowlist/toolBlocklist on persist
+ * is a security regression: the operator-configured tool filter survives the
+ * runtime session but is gone on the next daemon restart, surfacing ALL tools.
+ *
+ * @module
+ */
+import type { McpServerEntry } from "@comis/core";
+/**
+ * Inputs to {@link buildPersistedMcpEntry}. The resolved* values are the
+ * handler's already-computed `params.X ?? persistedEntry?.X` results (current
+ * intent wins over the prior persisted value); the config-only fields are read
+ * directly from `persistedEntry` because the RPC has no params for them.
+ */
+export interface BuildPersistedMcpEntryInput {
+    /** The validated `server_name` RPC param. */
+    readonly serverName: string;
+    /** Transport from the validated RPC params. */
+    readonly transport: McpServerEntry["transport"];
+    /** Optional transport params from the validated RPC request. */
+    readonly command?: string;
+    readonly args?: string[];
+    readonly url?: string;
+    /** Unresolved `${KEY}` env references (NOT the resolved spawn values). */
+    readonly env?: Record<string, string>;
+    readonly headers?: Readonly<Record<string, string>>;
+    /** Whether the caller opted this server out of the plaintext-secret scan. */
+    readonly disablePlaintextSecretCheck: boolean;
+    /** Resolved rlimits (caller param > persisted > undefined). */
+    readonly resolvedRlimits?: McpServerEntry["rlimits"];
+    /** Resolved reliability overrides (caller param > persisted). */
+    readonly resolvedKeepaliveIntervalMs?: number;
+    readonly resolvedCircuitBreakerThreshold?: number;
+    readonly resolvedCircuitBreakerCooldownMs?: number;
+    /**
+     * Per-server auth scheme + OAuth hints. Config-only on the mcp.connect path
+     * (no RPC params) — the caller resolves them as `params.X ?? persistedEntry?.X`
+     * (current intent > persisted) and passes the result here. Conditionally spread
+     * so a no-param reconnect does NOT strip a server's `auth:"oauth"` requirement
+     * (prevents downgrade to no-auth).
+     */
+    readonly auth?: McpServerEntry["auth"];
+    readonly oauth?: McpServerEntry["oauth"];
+    /**
+     * Skill-bundle provenance. Set by the bundle resolver when persisting a bundled
+     * entry; absent on direct mcp.connect calls. INPUT-DRIVEN: a no-marker reconnect
+     * from a manual mcp.connect intentionally clears the marker (operator has explicitly
+     * overridden the bundle entry). Differs from the reconnect config-only fields below
+     * which fall back to persistedEntry -- those would silently survive an override;
+     * the bundle marker MUST be cleared so audits reflect operator intent.
+     */
+    readonly _bundleSource?: string;
+    /**
+     * Archived bundle entry when a user override (or --force from a second bundle)
+     * replaced it. Forwarded verbatim from input to output. Recursive shape --
+     * McpServerEntry self-reference resolved at parse time via z.lazy().
+     */
+    readonly _bundleArchive?: McpServerEntry;
+    /**
+     * The existing persisted entry for this server (if any). The reconnect
+     * config-only fields are propagated from here so a reconnect / re-add does
+     * not strip operator-set values.
+     */
+    readonly persistedEntry?: McpServerEntry;
+}
+/**
+ * Construct the `McpServerEntry` written back to config.yaml by `mcp.connect`.
+ *
+ * Conditional-spread pattern (`...(x !== undefined && { x })`) matches the
+ * runtime `McpServerConfig` construction in the handler, so a field absent on
+ * input is absent on output (no spurious `undefined` keys in the persisted
+ * YAML).
+ */
+export declare function buildPersistedMcpEntry(input: BuildPersistedMcpEntryInput): McpServerEntry;