comisai 1.0.34 → 1.0.37

package/node_modules/@comis/daemon/dist/rpc/agent-handlers.js

@@ -39,12 +39,12 @@ export function createAgentHandlers(deps) {
             if (deps.agents[agentId] !== undefined) {
                 throw new Error(`Agent already exists: ${agentId}`);
             }
-            // 260428-vyf L2: extract inlineContent BEFORE config processing.
-            // role/identity are write-once side-effects (ROLE.md / IDENTITY.md
-            // file writes), NOT durable state — they NEVER enter the persisted
-            // config patch. The L1 tool boundary is responsible for stripping
-            // them from `config.workspace` before this RPC is called; this
-            // handler only consumes the dedicated top-level `inlineContent`
+            // Extract inlineContent BEFORE config processing. role/identity
+            // are write-once side-effects (ROLE.md / IDENTITY.md file writes),
+            // NOT durable state — they NEVER enter the persisted config patch.
+            // The tool boundary is responsible for stripping them from
+            // `config.workspace` before this RPC is called; this handler only
+            // consumes the dedicated top-level `inlineContent`
             // field. If a (mis)caller leaves them inside config.workspace, the
             // downstream Zod strict-object will reject them — that's an
             // explicit failure mode, not a silent drop.
@@ -69,17 +69,37 @@ export function createAgentHandlers(deps) {
             existingSkills.builtinTools = { ...DEFAULT_BUILTIN_TOOLS, ...existingBt };
             raw.skills = existingSkills;
             const parsedConfig = PerAgentConfigSchema.parse(config);
-            // Credential guard (260501-2pz): fail-loud if the new agent's
-            // provider has no resolvable API key. Mirrors agents.update guard
+            // Credential guard: fail-loud if the new agent's provider has no
+            // resolvable API key. Mirrors agents.update guard
             // ordering — runs BEFORE the in-memory commit so rejection prevents
             // assignment, file persist, and hot-add. Same helper as the patch /
             // update call sites for cross-handler consistency.
-            const credCheck = resolveProviderCredential(parsedConfig.provider, {
-                providerEntries: deps.providerEntries ?? {},
-                secretManager: deps.secretManager,
-            });
-            if (!credCheck.ok) {
-                throw new Error(credCheck.reason);
+            //
+            // Also plumb agents.<id>.oauthProfiles + the daemon-level OAuth
+            // credential store so OAuth-only providers (e.g. openai-codex) can
+            // resolve via Source C. Pre-resolve has() so the resolver itself stays
+            // synchronous (port-side validator does no I/O).
+            {
+                const targetProvider = parsedConfig.provider;
+                // eslint-disable-next-line security/detect-object-injection -- typed Record<string, string> read; targetProvider validated by schema parse
+                const configuredProfileId = parsedConfig.oauthProfiles?.[targetProvider];
+                let loaderHasProfile = false;
+                if (configuredProfileId && deps.oauthCredentialStore) {
+                    const hasResult = await deps.oauthCredentialStore.has(configuredProfileId);
+                    loaderHasProfile = hasResult.ok && hasResult.value === true;
+                }
+                const credCheck = resolveProviderCredential(targetProvider, {
+                    providerEntries: deps.providerEntries ?? {},
+                    secretManager: deps.secretManager,
+                    modelsConfig: deps.modelsConfig,
+                    oauthProfiles: parsedConfig.oauthProfiles,
+                    oauthProfileLoader: configuredProfileId
+                        ? { has: (id) => id === configuredProfileId && loaderHasProfile }
+                        : undefined,
+                });
+                if (!credCheck.ok) {
+                    throw new Error(credCheck.reason);
+                }
             }
             deps.agents[agentId] = parsedConfig;
             // Best-effort persistence to config.yaml
@@ -109,7 +129,7 @@ export function createAgentHandlers(deps) {
                 }
             }
             const workspaceDir = resolveWorkspaceDir(parsedConfig, agentId);
-            // 260428-vyf L2: best-effort inline ROLE.md / IDENTITY.md write.
+            // Best-effort inline ROLE.md / IDENTITY.md write.
             // Only invoke when inlineContent has at least one populated field
             // AND the persistDeps logger is available (the helper requires a
             // structured logger; the in-memory-only test path skips it).
@@ -220,20 +240,63 @@ export function createAgentHandlers(deps) {
             }
             const merged = { ...existing, ...config };
             const parsedConfig = PerAgentConfigSchema.parse(merged);
-            // Credential guard + probe (260501-2pz): when provider OR model
-            // changes, (a) GUARD — fail-loud if the resulting provider's API key
-            // is not resolvable from any source (no silent skip), then (b) PROBE
-            // — preexisting wire validation when an explicit providers.entries
+            // Validate oauthProfiles patch — each profileId must exist in the
+            // OAuth credential store. Skipped when no oauthCredentialStore is
+            // wired (test contexts; non-OAuth-aware setups). Critical: this
+            // throws BEFORE the `deps.agents[agentId] = parsedConfig`
+            // reference-replacement at the end of the handler, so on failure the
+            // daemon's in-memory map AND the YAML are both unchanged. The
+            // Zod-layer format check has already run during
+            // PerAgentConfigSchema.parse(merged) above — this block ONLY checks
+            // existence in the store.
+            if (parsedConfig.oauthProfiles !== undefined && deps.oauthCredentialStore) {
+                for (const [provider, profileId] of Object.entries(parsedConfig.oauthProfiles)) {
+                    const has = await deps.oauthCredentialStore.has(profileId);
+                    if (!has.ok || !has.value) {
+                        throw new Error(`profile ${profileId} not found in store. Run "comis auth list" to see available profiles.`);
+                    }
+                    // The provider variable is iterated for completeness; the
+                    // existence check is keyed on profileId alone (validateProfileId
+                    // — invoked by the Zod refine — already enforced that the
+                    // profile-id's provider portion equals the map key).
+                    void provider;
+                }
+            }
+            // Credential guard + probe: when provider changes,
+            // (a) GUARD — fail-loud if the resulting provider's API key is not
+            // resolvable from any source (no silent skip), then (b) PROBE —
+            // preexisting wire validation when an explicit providers.entries
             // record with apiKeyName exists. Order matters: guard runs first
             // (cheap, all paths), probe runs second (only when applicable).
+            //
+            // Model-only changes with unchanged provider DO NOT fire the guard
+            // or probe — they introduce no new credential surface.
+            // Stale-broken-config detection moves to the next chat turn
+            // (fail-loud at the request boundary), where the message is
+            // correctly shaped for the actual failure mode (not a pre-emptive
+            // API-key prompt that is wrong for OAuth providers like
+            // openai-codex). Also plumbs agents.<id>.oauthProfiles + the
+            // daemon-level OAuth credential store so Source C can fire.
             const providerChanging = config.provider !== undefined && config.provider !== existing.provider;
-            const modelChanging = config.model !== undefined && config.model !== existing.model;
-            if (providerChanging || modelChanging) {
+            if (providerChanging) {
                 const targetProvider = parsedConfig.provider;
+                // Pre-resolve has() at the daemon edge so the resolver stays sync.
+                // eslint-disable-next-line security/detect-object-injection -- typed Record<string, string> read; targetProvider validated by schema parse
+                const configuredProfileId = parsedConfig.oauthProfiles?.[targetProvider];
+                let loaderHasProfile = false;
+                if (configuredProfileId && deps.oauthCredentialStore) {
+                    const hasResult = await deps.oauthCredentialStore.has(configuredProfileId);
+                    loaderHasProfile = hasResult.ok && hasResult.value === true;
+                }
                 // (a) GUARD — fail-loud if no credential source resolves
                 const resolution = resolveProviderCredential(targetProvider, {
                     providerEntries: deps.providerEntries ?? {},
                     secretManager: deps.secretManager,
+                    modelsConfig: deps.modelsConfig,
+                    oauthProfiles: parsedConfig.oauthProfiles,
+                    oauthProfileLoader: configuredProfileId
+                        ? { has: (id) => id === configuredProfileId && loaderHasProfile }
+                        : undefined,
                 });
                 if (!resolution.ok) {
                     throw new Error(resolution.reason);

package/node_modules/@comis/daemon/dist/rpc/agent-inline-workspace.d.ts

@@ -1,6 +1,6 @@
 /**
  * Best-effort writer for inline ROLE.md / IDENTITY.md content supplied via
- * the L2 single-call agents.create path (260428-vyf).
+ * the L2 single-call agents.create path.
  *
  * Collapses the previous 3-call agent-creation workflow
  * (`agents_manage.create` -> `write(ROLE.md)` -> `write(IDENTITY.md)`)

package/node_modules/@comis/daemon/dist/rpc/agent-inline-workspace.js

@@ -1,7 +1,7 @@
 // SPDX-License-Identifier: Apache-2.0
 /**
  * Best-effort writer for inline ROLE.md / IDENTITY.md content supplied via
- * the L2 single-call agents.create path (260428-vyf).
+ * the L2 single-call agents.create path.
  *
  * Collapses the previous 3-call agent-creation workflow
  * (`agents_manage.create` -> `write(ROLE.md)` -> `write(IDENTITY.md)`)
@@ -63,7 +63,7 @@ async function attemptWrite(deps, agentId, filename, targetPath, content) {
     catch (e) {
         const message = e instanceof Error ? e.message : String(e);
         deps.logger.warn({
-            module: "daemon.rpc.agent-handlers",
+            submodule: "rpc.agent-handlers",
             agentId,
             file: filename,
             err: e,
@@ -128,7 +128,7 @@ export async function writeInlineWorkspaceFiles(deps, params) {
     // Pure no-op invocations (both fields absent) stay silent.
     if (roleWritten || identityWritten) {
         deps.logger.info({
-            module: "daemon.rpc.agent-handlers",
+            submodule: "rpc.agent-handlers",
             agentId: params.agentId,
             roleBytes: roleWritten ? params.role.length : 0,
             identityBytes: identityWritten ? params.identity.length : 0,

package/node_modules/@comis/daemon/dist/rpc/builtin-provider-guard.js

@@ -1,6 +1,6 @@
 // SPDX-License-Identifier: Apache-2.0
 /**
- * Built-in provider redundancy guard for providers.create (260501-gyy FIX 2).
+ * Built-in provider redundancy guard for providers.create.
  *
  * Rejects providers_manage create attempts that would shadow pi-ai's
  * dynamic catalog with a redundant custom entry. A built-in provider
@@ -16,7 +16,7 @@
  * in the source template (catalog-agnostic). Pinned by source-grep
  * regression test in builtin-provider-guard.test.ts.
  *
- * Mirrors credential-resolver.ts shape (260501-2pz precedent).
+ * Mirrors credential-resolver.ts shape.
  *
  * @module
  */

package/node_modules/@comis/daemon/dist/rpc/config-handlers.d.ts

@@ -7,7 +7,7 @@
  * Extracted from daemon.ts rpcCallInner switch block
  * @module
  */
-import { type AppContainer, type ConfigGitManager } from "@comis/core";
+import { type AppContainer, type ConfigGitManager, type OAuthCredentialStorePort } from "@comis/core";
 import type { ComisLogger } from "@comis/infra";
 import { z } from "zod";
 import type { RpcHandler } from "./types.js";
@@ -26,6 +26,14 @@ export interface ConfigHandlerDeps {
         timeoutMs?: number;
         secret?: string;
     };
+    /**
+     * Optional OAuth credential store, used by the credential guard to
+     * confirm that an agent's `oauthProfiles[provider]` entry refers to a
+     * profile that actually exists in ~/.comis/auth-profiles.json (or the
+     * encrypted-SQLite equivalent). When absent, the OAuth branch of the
+     * resolver is a no-op — existing API-key behavior is preserved.
+     */
+    oauthCredentialStore?: OAuthCredentialStorePort;
 }
 /**
  * Unwrap Zod schema wrappers (Optional / Nullable / Default / Pipe) to get

package/node_modules/@comis/daemon/dist/rpc/config-handlers.js

@@ -8,7 +8,7 @@
  * Extracted from daemon.ts rpcCallInner switch block
  * @module
  */
-import { isImmutableConfigPath, getConfigSchema, getConfigSections, deepMerge, AppConfigSchema, redactConfigSecrets, warnSuspiciousEnvValues, getManagedSectionRedirect, formatRedirectHint, } from "@comis/core";
+import { isImmutableConfigPath, getConfigSchema, getConfigSections, deepMerge, AppConfigSchema, redactConfigSecrets, warnSuspiciousEnvValues, findUnresolvedEnvRefs, formatMissingEnvRefError, getManagedSectionRedirect, formatRedirectHint, } from "@comis/core";
 import { suppressError } from "@comis/shared";
 import { stringify as yamlStringify } from "yaml";
 import { existsSync, readFileSync, writeFileSync, mkdirSync, renameSync } from "node:fs";
@@ -444,7 +444,7 @@ export function createConfigHandlers(deps) {
                 // pre-flight and bridge metadata validator catch this earlier for
                 // LLM tool calls -- this path is reached when those layers are
                 // bypassed. Emit the same redirect hint so all clients see
-                // identical, model-agnostic recovery instructions (quick-260425-t40).
+                // identical, model-agnostic recovery instructions.
                 if (isImmutableConfigPath(section, key)) {
                     const redirect = getManagedSectionRedirect(section, key);
                     const suffix = redirect
@@ -452,29 +452,74 @@ export function createConfigHandlers(deps) {
                         : " This setting requires manual operator intervention via config files.";
                     throw new Error(`Config path "${key ? `${section}.${key}` : section}" is immutable and cannot be modified at runtime.${suffix}`);
                 }
-                // Credential guard (260501-2pz): when a patch targets an agent's
-                // provider/model field, verify the resulting provider's API key is
-                // resolvable from at least one source pi-coding-agent will consult
-                // at runtime. Fail-loud here rather than letting an unauthorized
-                // provider config persist and explode at the next chat turn.
-                // See `.planning/design/daemon-credential-guard/PLAN.md`.
+                // Credential guard: when a patch targets an agent's provider/model
+                // field, verify the resulting provider's API key is resolvable from
+                // at least one source pi-coding-agent will consult at runtime.
+                // Fail-loud here rather than letting an unauthorized provider
+                // config persist and explode at the next chat turn.
+                //
+                // Model-only patches with unchanged provider introduce no new
+                // credential surface — short-circuit the guard entirely. The
+                // runtime auth chain that just authenticated the LLM call making
+                // this patch will keep working. Stale-broken-config detection
+                // moves back to the next chat turn (fail-loud at the request
+                // boundary), where the message is correctly shaped for the actual
+                // failure mode (not a pre-emptive API-key prompt that is wrong for
+                // OAuth providers like openai-codex).
                 if (section === "agents" && isAgentProviderOrModelKey(key)) {
                     const targetProvider = extractTargetProvider(key, coercedValue, deps.container.config);
                     if (targetProvider !== undefined) {
-                        const resolution = resolveProviderCredential(targetProvider, {
-                            providerEntries: deps.container.config.providers?.entries ?? {},
-                            secretManager: deps.container.secretManager,
-                        });
-                        if (!resolution.ok) {
-                            deps.logger.warn({
-                                method: "config.patch",
-                                section,
-                                key,
-                                targetProvider,
-                                hint: "Provider credential not resolvable",
-                                errorKind: "validation",
-                            }, "Config patch rejected: missing provider credential");
-                            throw new Error(resolution.reason);
+                        // For `.model` keys, extractTargetProvider returns the agent's
+                        // CURRENT provider (config-handlers.ts:65-69) — so the resolved
+                        // targetProvider always equals the current provider. The
+                        // model-only short-circuit therefore always fires for `.model`
+                        // keys; we still compute the equality explicitly so the
+                        // intent is readable and the check survives any future change
+                        // to extractTargetProvider's contract.
+                        const isModelOnlyPatch = key.endsWith(".model");
+                        const agentId = key.split(".")[0];
+                        // eslint-disable-next-line security/detect-object-injection -- agentId from validated key; agents map is typed Record
+                        const currentProvider = agentId
+                            ? deps.container.config.agents?.[agentId]?.provider
+                            : undefined;
+                        const providerUnchanged = currentProvider === targetProvider;
+                        if (!(isModelOnlyPatch && providerUnchanged)) {
+                            // Provider is changing (or this is a `.provider` patch where
+                            // targetProvider is the new value) — run the credential guard.
+                            // eslint-disable-next-line security/detect-object-injection -- agentId from validated key; agents map is typed Record
+                            const agentOauthProfiles = (agentId
+                                ? deps.container.config.agents?.[agentId]?.oauthProfiles
+                                : undefined);
+                            // Pre-resolve the loader has() for the configured profile so the
+                            // resolver can stay synchronous. This keeps Hexagonal port-side
+                            // validators I/O-free.
+                            // eslint-disable-next-line security/detect-object-injection -- typed Record<string, string> read; targetProvider validated above
+                            const configuredProfileId = agentOauthProfiles?.[targetProvider];
+                            let loaderHasProfile = false;
+                            if (configuredProfileId && deps.oauthCredentialStore) {
+                                const hasResult = await deps.oauthCredentialStore.has(configuredProfileId);
+                                loaderHasProfile = hasResult.ok && hasResult.value === true;
+                            }
+                            const resolution = resolveProviderCredential(targetProvider, {
+                                providerEntries: deps.container.config.providers?.entries ?? {},
+                                secretManager: deps.container.secretManager,
+                                modelsConfig: deps.container.config.models,
+                                oauthProfiles: agentOauthProfiles,
+                                oauthProfileLoader: configuredProfileId
+                                    ? { has: (id) => id === configuredProfileId && loaderHasProfile }
+                                    : undefined,
+                            });
+                            if (!resolution.ok) {
+                                deps.logger.warn({
+                                    method: "config.patch",
+                                    section,
+                                    key,
+                                    targetProvider,
+                                    hint: "Provider credential not resolvable",
+                                    errorKind: "validation",
+                                }, "Config patch rejected: missing provider credential");
+                                throw new Error(resolution.reason);
+                            }
                         }
                     }
                 }
@@ -537,6 +582,42 @@ export function createConfigHandlers(deps) {
                     throw new Error(`Suspicious env value(s) in config patch: ${hints}. ` +
                         `Use \${VAR_NAME} syntax to reference secrets stored via env_set.`);
                 }
+                // Reject patches that reference env vars not in the secrets store, on
+                // enabled MCP servers only. The env-substitution skip on disabled
+                // servers makes `enabled:false + ${VAR}` harmless at bootstrap; this
+                // gate forbids the partially-valid `enabled:true + missing ${VAR}`
+                // shape.
+                //
+                // We walk `patch` (not the deep-merged config) because we only
+                // validate what's being WRITTEN this RPC. `restoreMcpServerEnv` above
+                // already restored env from existing YAML for partial-update-without-
+                // env patches, so `patch.integrations.mcp.servers[].env` is the
+                // post-restore truth. Full-config validation would re-flag pre-
+                // existing valid-at-write-time refs whose secrets were later removed
+                // (out of scope, separate problem).
+                const patchInteg = patch.integrations;
+                const patchMcp = patchInteg?.mcp;
+                const patchServers = patchMcp?.servers;
+                if (Array.isArray(patchServers)) {
+                    for (const s of patchServers) {
+                        if (!s || typeof s !== "object")
+                            continue;
+                        const server = s;
+                        // McpServerEntrySchema.enabled defaults to true → absent = enabled.
+                        // Only explicit `enabled: false` skips the check (preserves the
+                        // placeholder-for-later pattern).
+                        if (server.enabled === false)
+                            continue;
+                        if (!server.env)
+                            continue;
+                        const serverName = typeof server.name === "string" ? server.name : "<unnamed>";
+                        const unresolved = findUnresolvedEnvRefs(server.env, (key) => deps.container.secretManager.get(key));
+                        if (unresolved.length > 0) {
+                            const missingNames = unresolved.map((u) => u.varName);
+                            throw new Error(formatMissingEnvRefError(serverName, missingNames));
+                        }
+                    }
+                }
                 const updatedLocal = deepMerge(existingLocal, patch);
                 // ${VAR} env var references in string values are preserved
                 // through YAML round-trip. yamlStringify writes them literally, parseYaml
@@ -651,7 +732,7 @@ export function createConfigHandlers(deps) {
                 }
                 // Check immutable paths -- entire section is being replaced.
                 // Backstop for direct-RPC clients; LLM tool calls hit the same redirect
-                // earlier via gateway-tool / bridge validator (quick-260425-t40).
+                // earlier via gateway-tool / bridge validator.
                 if (isImmutableConfigPath(section)) {
                     const redirect = getManagedSectionRedirect(section);
                     const suffix = redirect

package/node_modules/@comis/daemon/dist/rpc/credential-resolver.d.ts

@@ -6,12 +6,41 @@ export interface CredentialResolverDeps {
     secretManager?: {
         has(key: string): boolean;
     };
+    /**
+     * Models config — used to resolve `provider: "default"` to the operator's
+     * configured `models.defaultProvider`, mirroring runtime resolution in
+     * `resolveAgentModel`. When omitted or `defaultProvider` is empty, a
+     * literal `"default"` input passes through and produces a clear rejection
+     * pointing the operator at `models.defaultProvider`.
+     */
+    modelsConfig?: {
+        defaultProvider?: string;
+    };
+    /**
+     * Per-agent OAuth profile map (Record<provider, profileId>) sourced from
+     * `agents.<id>.oauthProfiles` on the daemon's container.config. When an
+     * entry exists for the resolved provider AND `oauthProfileLoader.has`
+     * returns true, the resolver returns ok with source: "oauth_profile".
+     */
+    oauthProfiles?: Record<string, string>;
+    /**
+     * Synchronous facade over OAuthCredentialStorePort.has. The async port
+     * call MUST be performed at the daemon edge (config-handlers /
+     * agent-handlers) and adapted to this sync shape — the resolver itself
+     * does no I/O (hexagonal: port-side validator). Pass a closure such as
+     * `{ has: () => storeHasResult.ok && storeHasResult.value }`.
+     */
+    oauthProfileLoader?: {
+        has(profileId: string): boolean;
+    };
 }
 export interface CredentialResolution {
     ok: boolean;
     /** When ok=false: actionable error message ready to throw. */
     reason?: string;
     /** When ok=true: which source resolved. Useful for debug logs. */
-    source?: "keyless" | "providers_entry" | "env_canonical";
+    source?: "keyless" | "providers_entry" | "env_canonical" | "oauth_profile";
+    /** When ok=true: the provider name actually checked (after "default" resolution). */
+    resolvedProvider?: string;
 }
 export declare function resolveProviderCredential(targetProvider: string, deps: CredentialResolverDeps): CredentialResolution;

package/node_modules/@comis/daemon/dist/rpc/credential-resolver.js

@@ -9,11 +9,24 @@
  * Resolution chain (matches pi-coding-agent runtime semantics):
  *   1. KEYLESS_PROVIDER_TYPES.has(entry.type) — ollama / lm-studio
  *   2. providers.entries.<provider>.apiKeyName → secretManager.has(...)
- *   3. pi-ai's getEnvApiKey(provider) — canonical env + OAuth + ADC + AWS
+ *   3. pi-ai's getEnvApiKey(provider) — canonical env vars (incl. ANTHROPIC_OAUTH_TOKEN
+ *      and AWS/ADC special-cases). Does NOT cover comis-managed OAuth profiles in
+ *      ~/.comis/auth-profiles.json (e.g. openai-codex).
+ *   4. Comis OAuth profiles — agent.oauthProfiles[provider] resolved against an
+ *      injected oauthProfileLoader (the OAuthCredentialStorePort handle held by
+ *      the daemon, adapted to a synchronous has-check at the call site).
+ *
+ * Note on synchronous loader facade: `OAuthCredentialStorePort.has`
+ * is async (returns Promise<Result<boolean, Error>>). To avoid an async cascade
+ * through every call site, this resolver remains SYNCHRONOUS and accepts a
+ * sync facade (`oauthProfileLoader: { has(profileId: string): boolean }`).
+ * The async port `has()` call MUST be performed at the daemon edge
+ * (config-handlers / agent-handlers) and adapted into the closure. This keeps
+ * the port-side validator I/O-free (Hexagonal: validator does no I/O).
  *
  * @module
  */
-import { getEnvApiKey } from "@mariozechner/pi-ai";
+import { getEnvApiKey, getProviders, getModels } from "@mariozechner/pi-ai";
 /**
  * Provider types that don't need an API key. Mirrors agent's
  * KEYLESS_PROVIDER_TYPES at model-registry-adapter.ts:60 — extended here to
@@ -28,23 +41,73 @@ export function resolveProviderCredential(targetProvider, deps) {
             reason: `Invalid provider value: must be a non-empty string (got ${JSON.stringify(targetProvider)})`,
         };
     }
-    // eslint-disable-next-line security/detect-object-injection -- typed Record<string, ProviderEntry> read; targetProvider validated above
-    const entry = deps.providerEntries?.[targetProvider];
+    // Resolve `provider: "default"` to the operator's configured default,
+    // mirroring runtime resolution in `resolveAgentModel`:
+    //   1. If `providers.entries.default` is explicitly configured, treat that
+    //      as the operator's intent — the entry itself carries the credential
+    //      resolution path (keyless / apiKeyName).
+    //   2. Else, if `models.defaultProvider` is set, use that.
+    //   3. Otherwise, fall back to the most-populated native provider in the
+    //      pi-ai catalog (same heuristic the runtime applies).
+    // This keeps the credential check semantically aligned with the literal
+    // provider the runtime will select.
+    let effectiveProvider = targetProvider;
+    if (targetProvider.toLowerCase() === "default") {
+        const explicitDefault = deps.providerEntries?.default;
+        if (!explicitDefault) {
+            const dp = deps.modelsConfig?.defaultProvider;
+            if (dp && dp.length > 0) {
+                effectiveProvider = dp;
+            }
+            else {
+                const allProviders = getProviders();
+                if (allProviders.length > 0) {
+                    effectiveProvider = allProviders
+                        .map((p) => ({ p, n: getModels(p).length }))
+                        .sort((a, b) => b.n - a.n)[0].p;
+                }
+            }
+        }
+    }
+    // eslint-disable-next-line security/detect-object-injection -- typed Record<string, ProviderEntry> read; effectiveProvider validated above
+    const entry = deps.providerEntries?.[effectiveProvider];
     // 1. Keyless types
     if (entry && KEYLESS_PROVIDER_TYPES.has(entry.type)) {
-        return { ok: true, source: "keyless" };
+        return { ok: true, source: "keyless", resolvedProvider: effectiveProvider };
     }
     // 2. Source A: providers.entries with secret-manager-resolvable apiKeyName
     if (entry?.apiKeyName && deps.secretManager?.has(entry.apiKeyName)) {
-        return { ok: true, source: "providers_entry" };
+        return { ok: true, source: "providers_entry", resolvedProvider: effectiveProvider };
+    }
+    // 3. Source C: comis OAuth profile (per-agent agents.<id>.oauthProfiles).
+    //    Covers OAuth-only providers like openai-codex whose tokens live in
+    //    ~/.comis/auth-profiles.json — pi-ai's getEnvApiKey does NOT see them.
+    //    Inserted before Source B so OAuth profiles win over env-canonical when
+    //    both would resolve (the operator explicitly configured the profile).
+    // eslint-disable-next-line security/detect-object-injection -- typed Record<string, string> read; effectiveProvider validated above
+    const configuredProfileId = deps.oauthProfiles?.[effectiveProvider];
+    if (configuredProfileId && deps.oauthProfileLoader?.has(configuredProfileId)) {
+        return { ok: true, source: "oauth_profile", resolvedProvider: effectiveProvider };
     }
-    // 3. Source B: pi-ai canonical env / OAuth / ADC chain
-    if (getEnvApiKey(targetProvider)) {
-        return { ok: true, source: "env_canonical" };
+    // 4. Source B: pi-ai canonical env / OAuth / ADC chain
+    if (getEnvApiKey(effectiveProvider)) {
+        return { ok: true, source: "env_canonical", resolvedProvider: effectiveProvider };
     }
-    return { ok: false, reason: buildRejectionMessage(targetProvider, entry) };
+    return { ok: false, reason: buildRejectionMessage(effectiveProvider, entry, configuredProfileId) };
 }
-function buildRejectionMessage(targetProvider, entry) {
+function buildRejectionMessage(targetProvider, entry, configuredProfileId) {
+    // OAuth-aware rejection: when the agent has an oauthProfiles entry for this
+    // provider but the loader could not confirm the profile, the failure mode is
+    // a missing OAuth profile (not a missing API key). Point the operator at
+    // `comis auth login` rather than env_set / apiKeyName recovery.
+    if (configuredProfileId) {
+        const lines = [];
+        lines.push(`Cannot set agent provider to "${targetProvider}": OAuth profile "${configuredProfileId}" is configured but not found in the OAuth credential store (~/.comis/auth-profiles.json).`);
+        lines.push(`Recovery:`);
+        lines.push(`  Run \`comis auth login --provider ${targetProvider}\` to (re)authenticate and create the profile, then retry this patch.`);
+        lines.push(`  Run \`comis auth list\` to see currently stored profiles.`);
+        return lines.join("\n");
+    }
     const lines = [];
     lines.push(`Cannot set agent provider to "${targetProvider}": no API key found.`);
     if (entry?.apiKeyName) {

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

@@ -6,6 +6,7 @@
  */
 import type { McpClientManager } from "@comis/skills";
 import type { ComisLogger } from "@comis/infra";
+import type { SecretManager } from "@comis/core";
 import type { RpcHandler } from "./types.js";
 /** Dependencies required by MCP management RPC handlers. */
 export interface McpHandlerDeps {
@@ -17,6 +18,13 @@ export interface McpHandlerDeps {
     mcpClientManager: McpClientManager;
     /** Logger for MCP test connection (used by temporary manager). */
     logger: ComisLogger;
+    /**
+     * Optional SecretManager for env-ref validation on mcp.connect. When
+     * undefined (legacy/test wiring), the env-ref check is skipped — the
+     * existing connect behavior is preserved. In production it is always
+     * wired via `deps.container.secretManager` from rpc-dispatch.
+     */
+    secretManager?: SecretManager;
 }
 /**
  * Create a record of MCP management RPC handlers bound to the given deps.

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

@@ -6,6 +6,7 @@
  * @module
  */
 import { createMcpClientManager } from "@comis/skills";
+import { findUnresolvedEnvRefs, formatMissingEnvRefError } from "@comis/core";
 // ---------------------------------------------------------------------------
 // Factory
 // ---------------------------------------------------------------------------
@@ -30,9 +31,9 @@ export function createMcpHandlers(deps) {
             return { servers, total: servers.length };
         },
         "mcp.status": async (params) => {
-            const name = params.name;
+            const name = params.server_name;
             if (!name)
-                throw new Error("Missing required parameter: name");
+                throw new Error("Missing required parameter: server_name");
             const manager = deps.mcpClientManager;
             const conn = manager.getConnection(name);
             if (!conn) {
@@ -59,10 +60,10 @@ export function createMcpHandlers(deps) {
             };
         },
         "mcp.connect": async (params) => {
-            const name = params.name;
+            const name = params.server_name;
             const transport = params.transport;
             if (!name)
-                throw new Error("Missing required parameter: name");
+                throw new Error("Missing required parameter: server_name");
             if (!transport)
                 throw new Error("Missing required parameter: transport");
             const manager = deps.mcpClientManager;
@@ -76,6 +77,19 @@ export function createMcpHandlers(deps) {
                 headers: params.headers,
                 enabled: true,
             };
+            // Reject connects that reference env vars not in the secrets store.
+            // mcp.connect is unconditionally enabled (config.enabled = true
+            // above), so the check always applies when both env and secretManager
+            // are present. Skipped only when secretManager is unwired (test
+            // setups) — production always wires it via rpc-dispatch.
+            if (config.env && deps.secretManager) {
+                const sm = deps.secretManager;
+                const unresolved = findUnresolvedEnvRefs(config.env, (key) => sm.get(key));
+                if (unresolved.length > 0) {
+                    const missingNames = unresolved.map((u) => u.varName);
+                    throw new Error(formatMissingEnvRefError(name, missingNames));
+                }
+            }
             const result = await manager.connect(config);
             if (!result.ok) {
                 throw new Error(`Failed to connect MCP server "${name}": ${result.error.message}`);
@@ -88,9 +102,9 @@ export function createMcpHandlers(deps) {
             };
         },
         "mcp.disconnect": async (params) => {
-            const name = params.name;
+            const name = params.server_name;
             if (!name)
-                throw new Error("Missing required parameter: name");
+                throw new Error("Missing required parameter: server_name");
             const manager = deps.mcpClientManager;
             const conn = manager.getConnection(name);
             if (!conn) {
@@ -148,9 +162,9 @@ export function createMcpHandlers(deps) {
             }
         },
         "mcp.reconnect": async (params) => {
-            const name = params.name;
+            const name = params.server_name;
             if (!name)
-                throw new Error("Missing required parameter: name");
+                throw new Error("Missing required parameter: server_name");
             const manager = deps.mcpClientManager;
             // Use manager's reconnect (preserves generation counter, uses stored config)
             const result = await manager.reconnect(name);