comisai 1.0.33 → 1.0.36

package/node_modules/@comis/cli/dist/wizard/steps/04-credentials.js

@@ -17,6 +17,17 @@
  */
 import { updateState, sectionSeparator, info, validateApiKey, getKeyPrefix, } from "../index.js";
 import { getModels } from "@mariozechner/pi-ai";
+// ---- OAuth interactive-flow imports ----
+// CLI cannot import from packages/daemon (dep-direction); the OAuth
+// runner + selector + remote-env detector live in @comis/agent
+// (selectOAuthCredentialStore lives there). The browser opener is the
+// `open` package (exact-pinned in @comis/cli per CLAUDE.md
+// supply-chain invariants).
+import { homedir } from "node:os";
+import open from "open";
+import { loginOpenAICodexOAuth, isRemoteEnvironment, selectOAuthCredentialStore, redactEmailForLog, } from "@comis/agent";
+import { loadConfigFile, validateConfig, safePath, } from "@comis/core";
+import { createLogger } from "@comis/infra";
 // ---------- Provider Help URLs ----------
 const PROVIDER_HELP_URLS = {
     anthropic: "https://console.anthropic.com/settings/keys",
@@ -31,7 +42,13 @@ const PROVIDER_HELP_URLS = {
     openrouter: "https://openrouter.ai/settings/keys",
 };
 // ---------- Auth Method Options ----------
-/** Providers that offer an OAuth token alternative to API keys. */
+/**
+ * Providers that offer an OAuth token alternative to API keys.
+ *
+ * openai is API-key-only -- OAuth lives exclusively on the separate
+ * `openai-codex` provider id (which has its own dedicated branch with
+ * a method picker). Only anthropic remains here.
+ */
 const AUTH_METHOD_PROVIDERS = {
     anthropic: {
         options: [
@@ -47,20 +64,6 @@ const AUTH_METHOD_PROVIDERS = {
             oauth: "Generate with: claude setup-token",
         },
     },
-    openai: {
-        options: [
-            { value: "apikey", label: "API Key", hint: "sk-..." },
-            { value: "oauth", label: "OAuth Token", hint: "From OAuth app flow" },
-        ],
-        helpUrls: {
-            apikey: "https://platform.openai.com/api-keys",
-            oauth: null,
-        },
-        helpNotes: {
-            apikey: null,
-            oauth: "Use the token from your OAuth application flow.",
-        },
-    },
 };
 // ---------- Provider Validation Endpoints ----------
 /**
@@ -79,14 +82,6 @@ const AUTH_METHOD_PROVIDERS = {
  * https://generativelanguage.googleapis.com/v1beta/models,
  * https://api.groq.com/openai/v1/models).
  *
- * Follow-up to 260501-kqq Sub-Fix C: that migration replaced the static
- * PROVIDER_VALIDATION map (which had host-only baseUrls + correct /v1/models
- * suffixes) with the catalog-driven `getValidationEndpoint` helper, but the
- * path-table values were copied verbatim -- producing double-prefixed URLs
- * (e.g., https://api.openai.com/v1/v1/models -> 404) for the 6 providers
- * whose catalog baseUrl includes the version segment. 260501-mvw corrects
- * the table; the helper itself is unchanged.
- *
  * Drift risk: if pi-ai upgrades a provider's baseUrl AND its path convention
  * changes, this table must be updated. Acceptable trade-off -- explicit
  * beats clever (auto-detection of duplicated path segments could mask
@@ -95,10 +90,9 @@ const AUTH_METHOD_PROVIDERS = {
  * Excluded: `together` and `ollama` are NOT in pi-ai 0.71.0's catalog
  * (`getModels(p)[0]?.baseUrl` returns undefined for both). The line-130
  * fallback (`if (!entry) return { valid: true };`) handles them by
- * skipping live validation entirely. For `together` this is a deliberate
- * behavior change vs the pre-260501-kqq state -- live validation against
- * api.together.xyz is now skipped. Users can still target Together via
- * the synthetic `custom` endpoint route.
+ * skipping live validation entirely. Live validation against
+ * api.together.xyz is skipped; users can still target Together via the
+ * synthetic `custom` endpoint route.
  */
 const PROVIDER_VALIDATION_PATHS = {
     // Catalog baseUrl is HOST-ONLY for these providers -> path needs the /v1 prefix.
@@ -117,8 +111,8 @@ const PROVIDER_VALIDATION_PATHS = {
 };
 /**
  * Resolve the validation endpoint for a provider by reading the catalog
- * baseUrl from pi-ai (260501-gyy precedent: builtin-provider-guard.ts:45)
- * and combining it with a known path from PROVIDER_VALIDATION_PATHS.
+ * baseUrl from pi-ai (precedent: builtin-provider-guard.ts:45) and
+ * combining it with a known path from PROVIDER_VALIDATION_PATHS.
  *
  * Returns `undefined` for providers not in the catalog (or providers
  * with no models, e.g., ollama with no remote endpoint) -- callers
@@ -257,16 +251,24 @@ async function handleCustomEndpoint(state, prompter) {
 }
 /**
  * Branch C: Standard provider -- help URL, format pre-check, live validation, retry loop.
+ *
+ * Accepts an optional `preResolvedAuthMethod` parameter so the
+ * dispatcher (credentialsStep.execute) can hoist the auth-method select
+ * BEFORE deciding which branch handler to run. When set, the internal
+ * select is skipped — preventing a double-prompt for AUTH_METHOD_PROVIDERS
+ * entries. When undefined, the internal select runs.
  */
-async function handleStandardProvider(state, prompter, providerId) {
+async function handleStandardProvider(state, prompter, providerId, preResolvedAuthMethod) {
     // Auth method selection for providers that support OAuth
-    let authMethod;
+    let authMethod = preResolvedAuthMethod;
     const authConfig = AUTH_METHOD_PROVIDERS[providerId];
-    if (authConfig) {
+    if (authConfig && authMethod === undefined) {
         authMethod = await prompter.select({
             message: `${providerId} authentication method`,
             options: authConfig.options,
         });
+    }
+    if (authConfig) {
         // Show help URL or note based on auth method
         const helpUrl = authConfig.helpUrls[authMethod];
         const helpNote = authConfig.helpNotes[authMethod];
@@ -357,6 +359,172 @@ async function handleStandardProvider(state, prompter, providerId) {
     // but handle gracefully
     return state;
 }
+// ---------- Branch D: openai-codex OAuth ----------
+const wizardLogger = createLogger({ name: "wizard-oauth" });
+/**
+ * Open the OAuth credential store from the current config (mirrors the
+ * helper installed in `auth.ts`). Defaults to file storage when config
+ * is absent or doesn't set `oauth.storage`. Encrypted-mode CLI wiring
+ * requires SECRETS_MASTER_KEY + secretsDb — if `storage='encrypted'`,
+ * the wizard surfaces a fail-fast error (operator can switch to file mode
+ * for the wizard, then back to encrypted after).
+ */
+async function openWizardOAuthStore() {
+    const dataDir = safePath(homedir(), ".comis");
+    // eslint-disable-next-line no-restricted-syntax -- CLI bootstrap before SecretManager (matches doctor.ts:45 / health.ts:43 precedent)
+    const envPaths = process.env["COMIS_CONFIG_PATHS"];
+    const configPath = envPaths?.split(":")[0] ??
+        safePath(homedir(), ".comis", "config.yaml");
+    const loadResult = loadConfigFile(configPath);
+    if (!loadResult.ok) {
+        return selectOAuthCredentialStore({ storage: "file", dataDir });
+    }
+    const validated = validateConfig(loadResult.value);
+    if (!validated.ok) {
+        return selectOAuthCredentialStore({ storage: "file", dataDir });
+    }
+    const storage = validated.value.oauth?.storage ?? "file";
+    if (storage === "encrypted") {
+        throw new Error("OAuth storage mode is 'encrypted' but the wizard cannot bootstrap the encrypted store. " +
+            "Hint: set appConfig.oauth.storage to 'file' temporarily for the wizard, or run " +
+            "`comis auth login --provider openai-codex` from a shell where SECRETS_MASTER_KEY is exported.");
+    }
+    return selectOAuthCredentialStore({ storage: "file", dataDir });
+}
+/**
+ * Branch D: openai-codex OAuth — interactive method picker + runner dispatch.
+ *
+ * Surfaces the runner's three login methods (browser auto-open, browser
+ * manual paste, device-code) plus a "skip for now" escape hatch. OAuth
+ * lives on its own provider id so the openai (API-key) flow is
+ * straight-through.
+ *
+ * On runner success: writes the profile to the OAuth store AND updates
+ * wizard state with apiKey + oauthProfileId + validated=true. The matching
+ * `oauthProfiles` config emission in step 10 wires the daemon to resolve
+ * this identity for openai-codex calls.
+ *
+ * On "skip for now": leaves the wizard advancing with provider.id set but
+ * validated=false; logs the literal hint pointing to `comis auth login`.
+ */
+async function handleCodexOAuth(state, prompter) {
+    const isRemoteDefault = isRemoteEnvironment({ env: process.env });
+    const maxRetries = 3;
+    // Inline helpNote -- AUTH_METHOD_PROVIDERS no longer has an openai entry,
+    // so we cannot pull the note from the map. Keep the wording user-facing
+    // and explicit about what the picker will do.
+    prompter.note(info("OpenAI Codex uses your ChatGPT/Codex subscription -- no API key needed. Choose how you want to sign in."), "openai-codex OAuth");
+    const methodChoice = await prompter.select({
+        message: "How do you want to sign in?",
+        options: [
+            { value: "browser-auto", label: "Browser (auto-open)", hint: "Local desktop, opens default browser" },
+            { value: "browser-manual", label: "Browser (manual paste)", hint: "VPS, you paste callback URL after sign-in" },
+            { value: "device-code", label: "Device code (phone)", hint: "SSH/headless, type a short code on a phone" },
+            { value: "skip", label: "Skip for now", hint: "finish wizard, run `comis auth login` later" },
+        ],
+        initialValue: isRemoteDefault ? "device-code" : "browser-auto",
+    });
+    if (methodChoice === "skip") {
+        prompter.log.info("Skipped OAuth -- run `comis auth login --provider openai-codex` before starting the daemon.");
+        return updateState(state, {
+            provider: { id: "openai-codex", validated: false },
+        });
+    }
+    // Compute runner params from the method choice. The runner ignores
+    // isRemote when method === "device-code" but we still pass the detected
+    // value for log fidelity. browser-manual forces isRemote=true so the
+    // manual-paste handlers run regardless of detection.
+    let method;
+    let isRemote;
+    switch (methodChoice) {
+        case "browser-auto":
+            method = "browser";
+            isRemote = false;
+            break;
+        case "browser-manual":
+            method = "browser";
+            isRemote = true;
+            break;
+        case "device-code":
+            method = "device-code";
+            isRemote = isRemoteDefault;
+            break;
+    }
+    let store;
+    try {
+        store = await openWizardOAuthStore();
+    }
+    catch (err) {
+        const msg = err instanceof Error ? err.message : String(err);
+        prompter.log.error(msg);
+        return state;
+    }
+    for (let attempt = 1; attempt <= maxRetries; attempt++) {
+        const result = await loginOpenAICodexOAuth({
+            prompter,
+            isRemote,
+            openUrl: open,
+            logger: wizardLogger,
+            method,
+        });
+        if (result.ok) {
+            const v = result.value;
+            const profile = {
+                provider: "openai-codex",
+                profileId: v.profileId,
+                access: v.access,
+                refresh: v.refresh,
+                expires: v.expires,
+                accountId: v.accountId,
+                email: v.email,
+                displayName: v.displayName,
+                version: 1,
+            };
+            const writeResult = await store.set(v.profileId, profile);
+            if (!writeResult.ok) {
+                prompter.log.error(`Failed to persist OAuth profile: ${writeResult.error.message}`);
+                if (attempt === maxRetries)
+                    return state;
+                continue;
+            }
+            wizardLogger.info({
+                provider: "openai-codex",
+                profileId: v.profileId,
+                identity: redactEmailForLog(v.email) ?? `id-${v.accountId ?? "<unknown>"}`,
+                action: "wizard-login",
+                submodule: "wizard-oauth",
+            }, "OAuth profile written by wizard");
+            return updateState(state, {
+                provider: {
+                    id: "openai-codex",
+                    authMethod: "oauth",
+                    apiKey: v.access,
+                    oauthProfileId: v.profileId,
+                    validated: true,
+                },
+            });
+        }
+        // Failure path -- surface the rewritten error + recovery options.
+        prompter.log.warn(result.error.message);
+        if (result.error.hint)
+            prompter.log.info(result.error.hint);
+        const isLastAttempt = attempt === maxRetries;
+        const recoveryOptions = isLastAttempt
+            ? [{ value: "skip", label: "Skip provider setup" }]
+            : [
+                { value: "retry", label: "Try again" },
+                { value: "skip", label: "Skip provider setup" },
+            ];
+        const choice = await prompter.select({
+            message: "What would you like to do?",
+            options: recoveryOptions,
+        });
+        if (choice === "skip")
+            return state;
+        // choice === "retry" -> continue loop
+    }
+    return state;
+}
 // ---------- Step Implementation ----------
 export const credentialsStep = {
     id: "credentials",
@@ -376,7 +544,28 @@ export const credentialsStep = {
         if (providerId === "custom") {
             return handleCustomEndpoint(state, prompter);
         }
-        // Branch C: Standard provider
-        return handleStandardProvider(state, prompter, providerId);
+        // Branch D: openai-codex OAuth -- dedicated method picker
+        // dispatching to loginOpenAICodexOAuth. Kept ABOVE the auth-method
+        // hoist so openai-codex never sees the apikey/oauth select prompt.
+        if (providerId === "openai-codex") {
+            return handleCodexOAuth(state, prompter);
+        }
+        // Hoisted auth-method select runs UP FRONT for providers in
+        // AUTH_METHOD_PROVIDERS so the dispatcher can branch on the chosen
+        // method before handleStandardProvider runs. Only anthropic remains
+        // in the map -- openai is API-key-only.
+        let authMethod;
+        // eslint-disable-next-line security/detect-object-injection -- read of static const map indexed by validated provider string
+        const authConfig = AUTH_METHOD_PROVIDERS[providerId];
+        if (authConfig) {
+            authMethod = await prompter.select({
+                message: `${providerId} authentication method`,
+                options: authConfig.options,
+            });
+        }
+        // Branch C: Standard provider -- pass the hoisted authMethod so the
+        // handler doesn't double-prompt. Anthropic OAuth still flows through
+        // here for the existing claude setup-token paste path.
+        return handleStandardProvider(state, prompter, providerId, authMethod);
     },
 };

package/node_modules/@comis/cli/dist/wizard/steps/10-write-config.js

@@ -25,6 +25,10 @@ function getDefaultModel(provider) {
     const defaults = {
         anthropic: "claude-sonnet-4-5-20250929",
         openai: "gpt-4o",
+        // pi-ai catalog's first entry for openai-codex (verified via
+        // getModels("openai-codex")[0].id). If pi-ai shuffles its catalog,
+        // the daemon's runtime default kicks in (same path as unknown providers).
+        "openai-codex": "gpt-5.1",
         google: "gemini-2.0-flash",
         groq: "llama-3.3-70b-versatile",
         ollama: "llama3",
@@ -55,6 +59,16 @@ function buildConfigObject(state) {
     if (state.provider?.compatMode) {
         agentConfig.compatMode = state.provider.compatMode;
     }
+    // OAuth profile wiring -- when handleCodexOAuth (step 04) produced a
+    // profile, emit it onto the agent so the daemon resolves the right
+    // identity for this provider's LLM calls. PerAgentConfigSchema accepts
+    // oauthProfiles as Record<provider, profileId> with the literal
+    // <provider>:<identity> format already validated at runner time.
+    if (state.provider?.oauthProfileId && state.provider?.id) {
+        agentConfig.oauthProfiles = {
+            [state.provider.id]: state.provider.oauthProfileId,
+        };
+    }
     // Elevated reply (sender trust map)
     if (state.senderTrustEntries && state.senderTrustEntries.length > 0) {
         const senderTrustMap = {};

package/node_modules/@comis/cli/dist/wizard/steps/11-daemon-start.js

@@ -438,9 +438,9 @@ export const daemonStartStep = {
                 dockerSpinner.start("Signalling container daemon to restart...");
                 const targetPid = await findContainerDaemonPid();
                 if (targetPid) {
-                    // 260428-qrn: Prime the user BEFORE the SIGTERM so they have a
-                    // breadcrumb pointing at the missing `--restart unless-stopped`
-                    // flag. This is a heads-up, not an abort -- the existing
+                    // Prime the user BEFORE the SIGTERM so they have a breadcrumb
+                    // pointing at the missing `--restart unless-stopped` flag.
+                    // This is a heads-up, not an abort -- the existing
                     // waitForRestart detector still handles the failure path below.
                     prompter.log.warn("Restarting daemon via SIGTERM. The container must have been started with `--restart unless-stopped` (or equivalent compose `restart: unless-stopped`). If the container exits and stays exited, run `docker restart <container-name>` from your host.");
                     try {

package/node_modules/@comis/cli/dist/wizard/types.d.ts

@@ -79,6 +79,13 @@ export type ProviderConfig = {
     customEndpoint?: string;
     compatMode?: "openai" | "anthropic";
     validated?: boolean;
+    /**
+     * Set when authMethod === "oauth" and the interactive
+     * loginOpenAICodexOAuth flow succeeded. Carries the canonical
+     * `<provider>:<identity>` profile-store key so downstream consumers
+     * (multi-account selection) can locate the persisted profile.
+     */
+    oauthProfileId?: string;
 };
 /**
  * Immutable state accumulator for the wizard.

package/node_modules/@comis/cli/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@comis/cli",
   "private": true,
-  "version": "1.0.33",
+  "version": "1.0.36",
   "author": "Moshe Anconina",
   "license": "Apache-2.0",
   "description": "Command-line interface for the Comis AI agent platform",

package/node_modules/@comis/core/dist/bootstrap.d.ts

@@ -16,7 +16,7 @@ export interface BootstrapOptions {
 /**
  * The application dependency container.
  *
- * Created by bootstrap(), this wires all Phase 1 services together
+ * Created by bootstrap(), this wires all services together
  * and provides a single shutdown() method for graceful cleanup.
  */
 export interface AppContainer {

package/node_modules/@comis/core/dist/config/env-substitution.d.ts

@@ -35,6 +35,72 @@ export declare function substituteEnvVars(obj: unknown, getSecret: (key: string)
  * @returns Set of unique VAR_NAME strings referenced anywhere in the tree
  */
 export declare function extractReferencedSecretNames(obj: unknown): Set<string>;
+/**
+ * A single unresolved env-var reference discovered while walking an object tree.
+ *
+ * `path` is the dot-notation location of the *string value* containing the
+ * reference (e.g. `"servers[0].env.FINNHUB_API_KEY"`), matching the path
+ * format used by `warnSuspiciousEnvValues`. `varName` is the name being
+ * referenced (e.g. `"FINNHUB_API_KEY"`).
+ *
+ * Two missing vars in the *same* string produce two entries with the *same*
+ * `path` but different `varName`s — accepted, deterministic, useful for
+ * downstream message formatting.
+ */
+export interface UnresolvedEnvRef {
+    /** Dot-notation path to the string value that contains the reference. */
+    readonly path: string;
+    /** The referenced env var name (without `${}` braces). */
+    readonly varName: string;
+}
+/**
+ * Walk an object tree and return every `${VAR_NAME}` (or whole-string bare
+ * `$VAR_NAME`) reference whose name `getSecret` cannot resolve.
+ *
+ * Complement of `extractReferencedSecretNames`: that function returns *all*
+ * referenced names (used by exec's `secretRefs` policy); this function returns
+ * only the *unresolved* subset (used by daemon-side config-write validation
+ * gates — `config.patch` and `mcp.connect`).
+ *
+ * Resolution semantics mirror `substituteEnvVars`:
+ * - `getSecret` returning `undefined` → ref is missing (included in result).
+ * - `getSecret` returning `""` → ref is a valid empty value (NOT included).
+ * - `$${VAR}` escapes are literals, never refs (NOT included).
+ *
+ * Path format mirrors `warnSuspiciousEnvValues`: `parent.child[N].leaf`,
+ * with the dot prefix omitted at the root.
+ *
+ * The env-substitution skip on disabled MCP servers makes the
+ * `enabled:false + ${VAR}` placeholder pattern harmless at bootstrap; this
+ * helper lets the daemon's config-write paths reject `enabled:true + missing
+ * ${VAR}` *at write time* so it never reaches disk.
+ *
+ * @param obj - Object tree to scan.
+ * @param getSecret - Callback that returns the value for a given var name,
+ *                    or `undefined` if not in the secrets store.
+ * @returns Array of `{ path, varName }` entries for each unresolved ref.
+ *          Empty when every ref resolves.
+ */
+export declare function findUnresolvedEnvRefs(obj: unknown, getSecret: (key: string) => string | undefined): UnresolvedEnvRef[];
+/**
+ * Build the structured `[invalid_value]` error string for an enabled MCP
+ * server whose `env` block references env vars not in the secrets store.
+ *
+ * Used identically by `config.patch` and `mcp.connect` to keep the agent-
+ * facing message in lockstep across the two RPC surfaces.
+ *
+ * Behavior:
+ * - `missingVarNames` is sorted lexicographically for deterministic output.
+ * - First 3 names are listed; if more, ` (+N more)` is appended.
+ * - Single-var case uses singular "env var"; multi-var uses plural "env vars".
+ * - Recovery option (1) `secrets_manage({action:"set", ...})` always names the
+ *   FIRST missing var (alphabetical). Agents fix one at a time, then re-try.
+ *
+ * @param serverName - The MCP server name (`"<unnamed>"` if absent).
+ * @param missingVarNames - Names that `findUnresolvedEnvRefs` reported missing.
+ * @returns The exact `[invalid_value] ...` message.
+ */
+export declare function formatMissingEnvRefError(serverName: string, missingVarNames: readonly string[]): string;
 /** A warning about a suspicious env value found during config validation. */
 export interface EnvValueWarning {
     /** Dot-notation path to the suspicious value (e.g., "integrations.mcp.servers[1].env.TAVILY_API_KEY"). */

package/node_modules/@comis/core/dist/config/env-substitution.js

@@ -207,6 +207,121 @@ function collectRefsFromString(input, out) {
         return "";
     });
 }
+/**
+ * Walk an object tree and return every `${VAR_NAME}` (or whole-string bare
+ * `$VAR_NAME`) reference whose name `getSecret` cannot resolve.
+ *
+ * Complement of `extractReferencedSecretNames`: that function returns *all*
+ * referenced names (used by exec's `secretRefs` policy); this function returns
+ * only the *unresolved* subset (used by daemon-side config-write validation
+ * gates — `config.patch` and `mcp.connect`).
+ *
+ * Resolution semantics mirror `substituteEnvVars`:
+ * - `getSecret` returning `undefined` → ref is missing (included in result).
+ * - `getSecret` returning `""` → ref is a valid empty value (NOT included).
+ * - `$${VAR}` escapes are literals, never refs (NOT included).
+ *
+ * Path format mirrors `warnSuspiciousEnvValues`: `parent.child[N].leaf`,
+ * with the dot prefix omitted at the root.
+ *
+ * The env-substitution skip on disabled MCP servers makes the
+ * `enabled:false + ${VAR}` placeholder pattern harmless at bootstrap; this
+ * helper lets the daemon's config-write paths reject `enabled:true + missing
+ * ${VAR}` *at write time* so it never reaches disk.
+ *
+ * @param obj - Object tree to scan.
+ * @param getSecret - Callback that returns the value for a given var name,
+ *                    or `undefined` if not in the secrets store.
+ * @returns Array of `{ path, varName }` entries for each unresolved ref.
+ *          Empty when every ref resolves.
+ */
+export function findUnresolvedEnvRefs(obj, getSecret) {
+    const out = [];
+    scanForUnresolved(obj, "", getSecret, out);
+    return out;
+}
+function scanForUnresolved(value, path, getSecret, out) {
+    if (value === null || value === undefined)
+        return;
+    if (typeof value === "string") {
+        collectUnresolvedFromString(value, path, getSecret, out);
+        return;
+    }
+    if (Array.isArray(value)) {
+        for (let i = 0; i < value.length; i++) {
+            scanForUnresolved(value[i], `${path}[${i}]`, getSecret, out);
+        }
+        return;
+    }
+    if (typeof value === "object") {
+        const record = value;
+        for (const key of Object.keys(record)) {
+            const childPath = path ? `${path}.${key}` : key;
+            scanForUnresolved(record[key], childPath, getSecret, out);
+        }
+    }
+}
+/**
+ * Extract `${VAR}` and whole-string bare `$VAR` references from a single
+ * string and append `{ path, varName }` for each one whose value `getSecret`
+ * cannot resolve. Mirrors `collectRefsFromString` exactly so this helper and
+ * `extractReferencedSecretNames` agree on what counts as a reference.
+ */
+function collectUnresolvedFromString(input, path, getSecret, out) {
+    // Whole-string bare reference first (mirrors substituteString step 0).
+    const bareMatch = input.match(BARE_VAR_PATTERN);
+    if (bareMatch) {
+        const varName = bareMatch[1];
+        if (getSecret(varName) === undefined) {
+            out.push({ path, varName });
+        }
+        return;
+    }
+    // Mask escapes so they don't match ENV_VAR_PATTERN. Same SENTINEL pattern
+    // as substituteString / collectRefsFromString for parity.
+    const SENTINEL = "\x00ESC_VAR\x00";
+    const working = input.replace(ESCAPED_VAR_PATTERN, () => `${SENTINEL}${SENTINEL}`);
+    working.replace(ENV_VAR_PATTERN, (_match, varName) => {
+        if (getSecret(varName) === undefined) {
+            out.push({ path, varName });
+        }
+        return "";
+    });
+}
+/**
+ * Build the structured `[invalid_value]` error string for an enabled MCP
+ * server whose `env` block references env vars not in the secrets store.
+ *
+ * Used identically by `config.patch` and `mcp.connect` to keep the agent-
+ * facing message in lockstep across the two RPC surfaces.
+ *
+ * Behavior:
+ * - `missingVarNames` is sorted lexicographically for deterministic output.
+ * - First 3 names are listed; if more, ` (+N more)` is appended.
+ * - Single-var case uses singular "env var"; multi-var uses plural "env vars".
+ * - Recovery option (1) `secrets_manage({action:"set", ...})` always names the
+ *   FIRST missing var (alphabetical). Agents fix one at a time, then re-try.
+ *
+ * @param serverName - The MCP server name (`"<unnamed>"` if absent).
+ * @param missingVarNames - Names that `findUnresolvedEnvRefs` reported missing.
+ * @returns The exact `[invalid_value] ...` message.
+ */
+export function formatMissingEnvRefError(serverName, missingVarNames) {
+    // Defensive copy + sort for determinism.
+    const sorted = [...missingVarNames].sort();
+    const visible = sorted.slice(0, 3);
+    const overflow = sorted.length - visible.length;
+    const overflowSuffix = overflow > 0 ? ` (+${overflow} more)` : "";
+    const isPlural = sorted.length > 1;
+    const subject = isPlural ? "env vars" : "env var";
+    const list = visible.join(", ") + overflowSuffix;
+    // Recovery option (1) references the first (alphabetical) missing var only.
+    const firstName = sorted[0] ?? "VAR_NAME";
+    return (`[invalid_value] enabled MCP server "${serverName}" references ${subject} ${list} which is not in the secrets store. Either:\n` +
+        `  1) secrets_manage({action:"set", name:"${firstName}", value:"..."})\n` +
+        `  2) Drop the env block from this server (omit the env field)\n` +
+        `  3) Set enabled:false to defer until the secret is available`);
+}
 /**
  * Scan an object tree for env-like string values that look suspicious —
  * bare `$VAR` references, placeholder strings like "[REDACTED]", or raw API keys.

package/node_modules/@comis/core/dist/config/index.d.ts

@@ -30,6 +30,8 @@ export { IntegrationsConfigSchema, BraveSearchConfigSchema, McpServerEntrySchema
 export { MonitoringConfigSchema } from "./schema-observability.js";
 export { ObservabilityConfigSchema } from "./schema-observability.js";
 export type { ObservabilityConfig, ObservabilityPersistenceConfig } from "./schema-observability.js";
+export { OAuthConfigSchema } from "./schema-oauth.js";
+export type { OAuthConfig } from "./schema-oauth.js";
 export { PluginsConfigSchema, PluginEntrySchema } from "./schema-plugins.js";
 export { QueueConfigSchema, QueueModeSchema, OverflowPolicySchema, PerChannelQueueConfigSchema, OverflowConfigSchema, DebounceBufferConfigSchema, FollowupConfigSchema, PriorityLaneConfigSchema, LaneAssignmentConfigSchema, } from "./schema-queue.js";
 export { StreamingConfigSchema, PerChannelStreamingConfigSchema, TypingModeSchema, ChunkModeSchema, TableModeSchema, } from "./schema-streaming.js";
@@ -61,7 +63,7 @@ export { loadConfigFile, validateConfig } from "./loader.js";
 export type { ConfigLoadOptions } from "./loader.js";
 export { resolveIncludes, MAX_INCLUDE_DEPTH } from "./include-resolver.js";
 export type { IncludeResolverDeps } from "./include-resolver.js";
-export { substituteEnvVars, warnSuspiciousEnvValues, extractReferencedSecretNames, type EnvValueWarning } from "./env-substitution.js";
+export { substituteEnvVars, warnSuspiciousEnvValues, extractReferencedSecretNames, findUnresolvedEnvRefs, formatMissingEnvRefError, type EnvValueWarning, type UnresolvedEnvRef, } from "./env-substitution.js";
 export { migrateConfig } from "./migrate.js";
 export { deepMerge, mergeLayered, loadLayered } from "./layered.js";
 export { IMMUTABLE_CONFIG_PREFIXES, MUTABLE_CONFIG_OVERRIDES, isImmutableConfigPath, matchesOverridePattern, getMutableOverridesForSection } from "./immutable-keys.js";

package/node_modules/@comis/core/dist/config/index.js

@@ -32,6 +32,7 @@ export { GatewayConfigSchema, GatewayTlsConfigSchema, GatewayTokenSchema, Gatewa
 export { IntegrationsConfigSchema, BraveSearchConfigSchema, McpServerEntrySchema, McpConfigSchema, TranscriptionConfigSchema, TtsConfigSchema, TtsAutoModeSchema, ElevenLabsVoiceSettingsSchema, TtsOutputFormatSchema, ImageAnalysisConfigSchema, VisionScopeRuleSchema, VisionConfigSchema, LinkUnderstandingConfigSchema, MediaInfraConfigSchema, MediaConfigSchema, AutoReplyRuleSchema, AutoReplyConfigSchema, DOCUMENT_MIME_WHITELIST, FileExtractionConfigSchema, MediaPersistenceConfigSchema, ImageGenerationConfigSchema, } from "./schema-integrations.js";
 export { MonitoringConfigSchema } from "./schema-observability.js";
 export { ObservabilityConfigSchema } from "./schema-observability.js";
+export { OAuthConfigSchema } from "./schema-oauth.js";
 export { PluginsConfigSchema, PluginEntrySchema } from "./schema-plugins.js";
 export { QueueConfigSchema, QueueModeSchema, OverflowPolicySchema, PerChannelQueueConfigSchema, OverflowConfigSchema, DebounceBufferConfigSchema, FollowupConfigSchema, PriorityLaneConfigSchema, LaneAssignmentConfigSchema, } from "./schema-queue.js";
 export { StreamingConfigSchema, PerChannelStreamingConfigSchema, TypingModeSchema, ChunkModeSchema, TableModeSchema, } from "./schema-streaming.js";
@@ -51,7 +52,7 @@ export { loadConfigFile, validateConfig } from "./loader.js";
 // Include resolver ($include directive processing)
 export { resolveIncludes, MAX_INCLUDE_DEPTH } from "./include-resolver.js";
 // Environment variable substitution (${VAR} processing)
-export { substituteEnvVars, warnSuspiciousEnvValues, extractReferencedSecretNames } from "./env-substitution.js";
+export { substituteEnvVars, warnSuspiciousEnvValues, extractReferencedSecretNames, findUnresolvedEnvRefs, formatMissingEnvRefError, } from "./env-substitution.js";
 // Config migration (legacy key transformation)
 export { migrateConfig } from "./migrate.js";
 // Layered merge