mixdog 1.4.0 → 1.4.2

package/src/session-runtime/services/provider-admin.mjs

@@ -111,13 +111,25 @@ import {
   providerAccountLimit,
   providerAccountBlockedUntil,
   ACCOUNT_PROVIDERS,
+  MAX_ACCOUNTS,
+  customProviderKeyIds,
+  setCustomProviderKeyIds,
 } from '../../runtime/shared/provider-accounts.mjs';
+import { customProviderKeyAccount } from '../../runtime/shared/custom-provider-keys.mjs';
 import { currentProviderAccountId, withProviderAccount } from '../../runtime/shared/provider-auth-binding.mjs';
 import {
   CUSTOM_API_KEY_ENV_RE,
   effectiveCustomModelRows,
   normalizeCustomProviderConfig as normalizeStoredCustomConfig,
 } from '../../runtime/agent/orchestrator/providers/custom-provider-config.mjs';
+import {
+  VERTEX_ADC_MODE,
+  VERTEX_API_KEY_MODE,
+  describeVertexAdc,
+  parseVertexServiceAccount,
+  probeVertexMetadata,
+} from '../../runtime/agent/orchestrator/providers/vertex-ai-auth.mjs';
+import { vertexEnvLocation } from '../../runtime/agent/orchestrator/providers/vertex-ai-models.mjs';
 
 const API_PROVIDERS = Object.freeze([
   Object.freeze({ id: 'openrouter', name: 'OpenRouter', env: 'OPENROUTER_API_KEY', url: 'https://openrouter.ai/keys' }),
@@ -134,6 +146,7 @@ const API_PROVIDERS = Object.freeze([
     url: 'https://console.anthropic.com/settings/keys',
   }),
   Object.freeze({ id: 'gemini', name: 'Gemini API', env: 'GEMINI_API_KEY', url: 'https://aistudio.google.com/apikey' }),
+  Object.freeze({ id: 'vertex-ai', name: 'Vertex AI', env: null, url: null }),
   Object.freeze({
     id: 'deepseek',
     name: 'DeepSeek API',
@@ -374,6 +387,23 @@ function storedSecretDetail(account) {
   return isFallbackSecret(account) ? 'stored in private file' : 'stored in keychain';
 }
 
+// The Vertex AI gcloud-login row's detail: who is signed in and where, or what to fix.
+function vertexAdcDetail(adc, location) {
+  if (!adc) return `gcloud login · ${location}`;
+  if (adc.state !== 'ready') return adc.message;
+  const account = adc.account || (adc.type === 'metadata' ? 'metadata server' : 'gcloud user login');
+  return [account, adc.projectId || 'no project', location].join(' · ');
+}
+
+// The Vertex AI location a row shows and where it comes from: the saved one
+// ('config'), else what the runtime would use unset ('environment' or
+// 'default'), which the connect form offers as a hint without saving it.
+function vertexRowLocation(configured) {
+  if (configured.location) return { location: String(configured.location), locationSource: 'config' };
+  const env = vertexEnvLocation();
+  return env ? { location: env, locationSource: 'environment' } : { location: 'global', locationSource: 'default' };
+}
+
 // `keychainIssue`: the setup response's one keyring check (never asked per row).
 function apiProviderSetup(p, providers, checkSecrets, keychainIssue) {
   const configured = providers[p.id] || {};
@@ -402,6 +432,74 @@ function apiProviderSetup(p, providers, checkSecrets, keychainIssue) {
   }
   const rowIssue = authenticated ? null : keychainIssue;
   if (rowIssue) detail = rowIssue.message;
+  if (p.id === 'vertex-ai' && configured.authMode === VERTEX_ADC_MODE) {
+    // gcloud login: nothing is stored; connected while enabled and the login is readable.
+    const { location, locationSource } = vertexRowLocation(configured);
+    const adc = checkSecrets ? describeVertexAdc({ projectId: configured.projectId }) : null;
+    // Without a login file a metadata server may stand in: probed once, in the
+    // background, for the next refresh to report.
+    if (adc?.state === 'missing') void probeVertexMetadata();
+    const ready = configuredEnabled && (!adc || adc.state === 'ready');
+    let adcStatus = configuredEnabled ? 'Not connected' : 'Off';
+    if (ready) adcStatus = 'Set';
+    return {
+      ...p,
+      group: 'api',
+      type: 'api-key',
+      authKind: 'adc',
+      authMode: VERTEX_ADC_MODE,
+      enabled: configuredEnabled,
+      authenticated: ready,
+      stored: false,
+      env: false,
+      envName: null,
+      status: adcStatus,
+      detail: vertexAdcDetail(adc, location),
+      location,
+      locationSource,
+      projectId: adc?.projectId || String(configured.projectId || '') || null,
+      ...(adc ? { adc } : {}),
+    };
+  }
+  if (p.id === 'vertex-ai') {
+    const { location, locationSource } = vertexRowLocation(configured);
+    // An express-mode API key, or the service-account key.
+    const express = configured.authMode === VERTEX_API_KEY_MODE;
+    // The connect form offers the gcloud login too; its status line reads this.
+    const adc = checkSecrets && !authenticated ? describeVertexAdc({ projectId: configured.projectId }) : null;
+    let projectId = String(configured.projectId || '');
+    if (!projectId && authenticated && checkSecrets && !express) {
+      try {
+        projectId = parseVertexServiceAccount(getAgentApiKey(p.id)).projectId;
+      } catch {
+        // An unreadable key leaves the project id empty; the status line then shows the location only.
+      }
+    }
+    if (!rowIssue) {
+      if (express) detail = `API key (express mode) · ${location}`;
+      else detail = projectId ? `${projectId} · ${location}` : `Location: ${location}`;
+    }
+    return {
+      ...p,
+      ...(rowIssue ? { keychainIssue: rowIssue } : {}),
+      group: 'api',
+      type: 'api-key',
+      authKind: express ? 'api-key' : 'service-account',
+      authMode: express ? VERTEX_API_KEY_MODE : 'service-account',
+      ...(adc ? { adc } : {}),
+      enabled: configuredEnabled || authenticated,
+      authenticated,
+      stored,
+      env: false,
+      envName: null,
+      status,
+      detail,
+      location,
+      locationSource,
+      projectId: projectId || null,
+      ...(credentialSource ? { credentialSource } : {}),
+    };
+  }
   return {
     ...p,
     ...(rowIssue ? { keychainIssue: rowIssue } : {}),
@@ -561,8 +659,12 @@ function customProviderRow(id, entry, checkSecrets = true) {
   row.auth = keyless ? 'none' : 'key';
   row.discovery = structuredClone(config?.discovery ?? entry.discovery ?? { newModelsHidden: false });
   row.modelOverrides = structuredClone(config?.modelOverrides ?? entry.modelOverrides ?? {});
+  if (config?.headers) row.headers = { ...config.headers };
   if (config?.wires) row.wires = [...config.wires];
   if (config?.modelWires) row.modelWires = { ...config.modelWires };
+  // Additional API keys by id only; their values never leave the keychain.
+  const extraKeyIds = keyless ? [] : customProviderKeyIds(id);
+  if (extraKeyIds.length) row.extraApiKeys = extraKeyIds.map((keyId) => ({ id: keyId }));
   // A stored config that does not normalize cannot run (the registry skips
   // it): say so explicitly instead of listing it as connected.
   // Every readiness flag consumers read says "not ready" (`stored` stays the
@@ -660,6 +762,20 @@ async function modelProxyProviderSetup(options) {
 
 function apiProviderStatusRow(p, config) {
   const configured = config.providers?.[p.id] || {};
+  if (p.id === 'vertex-ai' && configured.authMode === VERTEX_ADC_MODE) {
+    const adc = describeVertexAdc({ projectId: configured.projectId });
+    return {
+      id: p.id,
+      type: 'api-key',
+      enabled: configured.enabled === true,
+      authenticated: configured.enabled === true && adc.state === 'ready',
+      stored: false,
+      env: false,
+      envName: null,
+      label: p.name,
+      detail: vertexAdcDetail(adc, vertexRowLocation(configured).location),
+    };
+  }
   const envName = AGENT_PROVIDER_ENV[p.id] || p.env;
   const env = Boolean(envName && process.env[envName]);
   const stored = hasStoredSecret(SECRET_ACCOUNTS.agentApiKey(p.id));
@@ -720,6 +836,7 @@ export function renderProviderStatus(config = {}) {
       if (row.type === 'oauth') source = row.detail || 'oauth';
       else if (row.env) source = `env:${row.envName}`;
       else if (row.stored) source = 'keychain';
+      else if (row.detail) source = row.detail;
       const enabled = row.enabled ? 'enabled' : 'disabled';
       return `${row.id.padEnd(width)}  ${row.type.padEnd(7)}  ${auth.padEnd(8)}  ${enabled.padEnd(8)}  ${source}`;
     })
@@ -984,15 +1101,68 @@ export async function updateProviderAccounts(provider, change) {
   return listProviderAccounts(provider);
 }
 
-export async function saveProviderApiKey(cfgMod, provider, secret) {
+export async function saveProviderApiKey(cfgMod, provider, secret, options) {
   requireLocalProviderManagement();
   const id = String(provider || '').trim();
   if (!API_PROVIDER_IDS.has(id)) throw new Error(`unknown API-key provider "${id}"`);
   const value = String(secret || '').trim();
-  if (!value) throw new Error(`API key is required for ${id}`);
+  const adc = id === 'vertex-ai' && options?.authMode === VERTEX_ADC_MODE;
+  const express = id === 'vertex-ai' && options?.authMode === VERTEX_API_KEY_MODE;
+  if (!value && !adc) throw new Error(`API key is required for ${id}`);
+  let patch = { enabled: true };
+  if (id === 'vertex-ai') {
+    if (adc && value) throw new Error('Vertex AI gcloud login takes no key');
+    if (express && /[\s{]/.test(value)) throw new Error('Vertex AI express mode takes an API key, not a JSON key file');
+    if (!adc && !express) parseVertexServiceAccount(value);
+    // Only a location the user chose is saved: an empty one is unset (the
+    // runtime then follows the environment's region, then global). None given
+    // at all (the terminal setup) keeps a saved one; express mode never keeps
+    // one, as it serves global only.
+    const location = String(options?.location ?? '')
+      .trim()
+      .toLowerCase();
+    const projectId = String(options?.projectId || '').trim();
+    if (location && !/^[a-z0-9-]{1,63}$/.test(location)) throw new Error('Vertex AI location is invalid');
+    if (express && location && location !== 'global') {
+      throw new Error('Vertex AI express mode serves only the global location');
+    }
+    const locationPatch =
+      location || express || options?.location !== undefined ? { location: location || undefined } : {};
+    if (projectId && (!/^[a-zA-Z0-9._:-]{1,128}$/.test(projectId) || projectId.includes('/'))) {
+      throw new Error('Vertex AI project ID override is invalid');
+    }
+    if (adc) {
+      // gcloud login: nothing secret is stored, and the login must already be usable.
+      let login = describeVertexAdc({ projectId });
+      // No login file: a GCE / Cloud Run / GKE host's metadata server.
+      if (login.state === 'missing' && (await probeVertexMetadata())) login = describeVertexAdc({ projectId });
+      if (login.state !== 'ready') throw new Error(login.message);
+      if (!login.projectId) {
+        throw new Error(
+          'No Google Cloud project found for the gcloud login. Enter a project ID override, or run `gcloud config set project PROJECT_ID`.'
+        );
+      }
+      // The login replaces a key saved earlier rather than sitting beside it.
+      const account = SECRET_ACCOUNTS.agentApiKey(id);
+      if (hasStoredSecret(account)) await deleteSecretAsync(account);
+      updateConfigProvider(cfgMod, id, {
+        enabled: true,
+        ...locationPatch,
+        projectId: projectId || undefined,
+        authMode: VERTEX_ADC_MODE,
+      });
+      return { provider: id, type: 'adc', authenticated: true };
+    }
+    patch = {
+      enabled: true,
+      ...locationPatch,
+      projectId: projectId || undefined,
+      authMode: express ? VERTEX_API_KEY_MODE : 'service-account',
+    };
+  }
   await saveSecretAsync(SECRET_ACCOUNTS.agentApiKey(id), value);
-  updateConfigProvider(cfgMod, id, { enabled: true });
-  return { provider: id, type: 'api-key', authenticated: true };
+  updateConfigProvider(cfgMod, id, patch);
+  return { provider: id, type: id === 'vertex-ai' && !express ? 'service-account' : 'api-key', authenticated: true };
 }
 
 function sanitizeCustomError(error, secrets = []) {
@@ -1049,6 +1219,63 @@ function validateCustomTransportFields(input) {
     if (typeof input.apiKey === 'string' && input.apiKey !== '')
       throw new TypeError('custom provider apiKey and apiKeyEnv are mutually exclusive');
   }
+  if (input.extraApiKeys !== undefined) validateExtraApiKeys(input.extraApiKeys);
+}
+
+const CUSTOM_KEY_ID_RE = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/;
+
+// Additional API keys in use order, beside the primary key (MAX_ACCOUNTS in
+// all): `{ id }` keeps a saved key, `{ apiKey }` adds one and `{ id, apiKey }`
+// replaces a saved key's value; a blank `apiKey` keeps the saved key.
+function validateExtraApiKeys(rows) {
+  const invalid = () => new TypeError('custom provider extraApiKeys are invalid');
+  if (!Array.isArray(rows) || rows.length >= MAX_ACCOUNTS) throw invalid();
+  const ids = new Set();
+  for (const row of rows) {
+    if (!row || typeof row !== 'object' || Array.isArray(row)) throw invalid();
+    if (Object.keys(row).some((key) => key !== 'id' && key !== 'apiKey')) throw invalid();
+    if (row.id !== undefined && (typeof row.id !== 'string' || !CUSTOM_KEY_ID_RE.test(row.id) || ids.has(row.id)))
+      throw new TypeError('custom provider extraApiKeys id is invalid');
+    if (row.apiKey !== undefined && (typeof row.apiKey !== 'string' || row.apiKey.length > CUSTOM_API_KEY_MAX))
+      throw new TypeError('custom provider extraApiKeys apiKey is invalid');
+    if (row.id === undefined && !row.apiKey?.trim()) throw new TypeError('custom provider additional API key is empty');
+    if (row.id !== undefined) ids.add(row.id);
+  }
+}
+
+// The additional-key change a save makes over the `saved` key ids: `rows`
+// absent keeps them; a typed key is stored under a new id, so a replaced key
+// starts without the old one's cooldown. A keyless provider keeps none.
+function extraKeyPlan(saved, rows, keyless) {
+  if (keyless) return { saved, ids: [], added: [], removed: saved };
+  if (rows === undefined) return { saved, ids: saved, added: [], removed: [] };
+  const ids = [];
+  const added = [];
+  for (const row of rows) {
+    if (row.id !== undefined && !saved.includes(row.id)) throw new Error('An additional API key is no longer saved.');
+    const typed = typeof row.apiKey === 'string' ? row.apiKey.trim() : '';
+    if (!typed) {
+      ids.push(row.id);
+      continue;
+    }
+    const keyId = randomUUID();
+    ids.push(keyId);
+    added.push({ keyId, key: typed });
+  }
+  return { saved, ids, added, removed: saved.filter((keyId) => !ids.includes(keyId)) };
+}
+
+const extraKeysChanged = (plan) => plan.ids.join() !== plan.saved.join();
+
+async function applyExtraKeys(id, plan) {
+  for (const { keyId, key } of plan.added) await saveSecretAsync(customProviderKeyAccount(id, keyId), key);
+  if (extraKeysChanged(plan)) await setCustomProviderKeyIds(id, plan.ids);
+}
+
+// A failed save puts the saved roster back and drops the keys it added.
+async function revertExtraKeys(id, plan) {
+  if (extraKeysChanged(plan)) await setCustomProviderKeyIds(id, plan.saved);
+  for (const { keyId } of plan.added) await deleteSecretAsync(customProviderKeyAccount(id, keyId));
 }
 
 /** Whether the named environment variable is set to a non-empty value. */
@@ -1064,7 +1291,7 @@ function inputObject(input) {
 }
 
 // An edit that omits a stored setting keeps it: `auth` for every input shape,
-// and `discovery` / `modelOverrides` for a v2 input (a legacy `models` input
+// and `discovery` / `modelOverrides` / `headers` for a v2 input (a legacy `models` input
 // states the whole manual model list itself).
 function withStoredSettings(input, entry) {
   const stored = storedCustomConfig(entry);
@@ -1079,6 +1306,8 @@ function withStoredSettings(input, entry) {
   if (out.schemaVersion === stored.schemaVersion) {
     if (out.discovery === undefined) out.discovery = stored.discovery;
     if (out.modelOverrides === undefined) out.modelOverrides = stored.modelOverrides;
+    // `headers: {}` clears them; an omitted field keeps the stored ones.
+    if (out.headers === undefined && stored.headers) out.headers = stored.headers;
     // Served wires and per-model wires have no setup field yet: an edit on
     // the same protocol keeps them (another protocol serves other wires).
     if ((out.protocol ?? stored.protocol) === stored.protocol) {
@@ -1095,7 +1324,9 @@ function withStoredSettings(input, entry) {
 // the config. Synchronous, so a caller can merge and commit one snapshot.
 function customInputAt(snapshot, input, normalizeCustomProviderConfig, options) {
   const id = input.id === undefined ? null : input.id;
-  const merged = id ? withStoredSettings(input, existingCustomEntry(snapshot, id)) : input;
+  // Additional keys are secrets, applied by the save itself (extraKeyPlan).
+  const { extraApiKeys: _extraKeys, ...settings } = input;
+  const merged = id ? withStoredSettings(settings, existingCustomEntry(snapshot, id)) : settings;
   const config = normalizeCustomProviderConfig(merged, options);
   const typed = typeof merged.apiKey === 'string' ? merged.apiKey.trim() : '';
   const keyless = config.auth === 'none';
@@ -1147,9 +1378,16 @@ export async function saveCustomProvider(cfgMod, rawInput) {
   const commit = async () => {
     const account = SECRET_ACCOUNTS.agentApiKey(id);
     const previousKey = typed && existingId ? getAgentApiKey(id) : null;
+    // Auth as of this save's turn in the key queue: a no-auth save queued
+    // earlier may have landed since the input was resolved.
+    const keyless = existingId
+      ? customInputAt(cfgMod.loadConfig(), rawInput, normalizeCustomProviderConfig, { requireModels: false }).keyless
+      : resolved.keyless;
+    const extra = extraKeyPlan(existingId ? customProviderKeyIds(id) : [], rawInput.extraApiKeys, keyless);
     if (typed) await saveSecretAsync(account, typed);
     let entry;
     try {
+      await applyExtraKeys(id, extra);
       // Synchronous from here: omitted settings come from the config this
       // save commits over, so an edit that landed during the awaits above (a
       // model's visibility, a peer save, a removal) is never reverted.
@@ -1162,15 +1400,29 @@ export async function saveCustomProvider(cfgMod, rawInput) {
         { baseConfig: current }
       );
     } catch (error) {
+      await revertExtraKeys(id, extra);
       if (typed) {
         if (previousKey) await saveSecretAsync(account, previousKey);
         else await deleteSecretAsync(account);
       }
       throw error;
     }
+    // A removed key is dropped once the save holds; a keychain refusal then
+    // leaves an unused secret behind (reported), never a failed save that did commit.
+    for (const keyId of extra.removed) {
+      await deleteSecretAsync(customProviderKeyAccount(id, keyId)).catch((error) => {
+        process.stderr.write(
+          `[provider-admin] could not delete additional API key ${keyId} of ${id}: ${error?.message || error}\n`
+        );
+      });
+    }
     return customProviderRow(id, entry);
   };
-  return typed ? serializeCustomKeySave(id, commit) : commit();
+  // Every save that may change the keys runs in the provider's key queue: a
+  // typed key, an additional-key list, or a no-auth save (which drops them),
+  // decided from the input alone, never from a roster read outside the queue.
+  const keysChange = typed || rawInput.extraApiKeys !== undefined || (existingId && resolved.keyless);
+  return keysChange ? serializeCustomKeySave(id, commit) : commit();
 }
 
 // Replaces only the stored key of an existing custom provider. The provider's
@@ -1179,7 +1431,8 @@ export async function saveCustomProvider(cfgMod, rawInput) {
 export async function saveCustomProviderKey(cfgMod, rawId, rawKey) {
   requireLocalProviderManagement();
   const id = String(rawId || '').trim();
-  if (typeof rawKey !== 'string' || rawKey.length > CUSTOM_API_KEY_MAX) throw new TypeError('custom provider apiKey is invalid');
+  if (typeof rawKey !== 'string' || rawKey.length > CUSTOM_API_KEY_MAX)
+    throw new TypeError('custom provider apiKey is invalid');
   const key = rawKey.trim();
   if (!key) throw new Error('API key is required');
   const takesStoredKey = () => {
@@ -1398,6 +1651,9 @@ export async function removeCustomProvider(cfgMod, rawId) {
     // provider registered so the removal can be retried. A missing secret
     // (keyless provider) is not an error.
     await deleteSecretAsync(SECRET_ACCOUNTS.agentApiKey(id));
+    const extraKeyIds = customProviderKeyIds(id);
+    for (const keyId of extraKeyIds) await deleteSecretAsync(customProviderKeyAccount(id, keyId));
+    if (extraKeyIds.length) await setCustomProviderKeyIds(id, []);
     const current = cfgMod.loadConfig();
     const { [id]: _removed, ...providers } = current.providers || {};
     cfgMod.saveConfig(withoutProviderReferences({ ...current, providers }, id), { baseConfig: current });
@@ -1424,13 +1680,29 @@ export async function testCustomProvider(cfgMod, rawInput) {
         error: { kind: 'empty', message: 'No models were found for this provider' },
       };
     const { createCustomProvider } = await loadCustomProviderModule();
-    const provider = await createCustomProvider(id || 'custom-test', { ...config, apiKey });
-    await withTimeout(
+    const primary = await createCustomProvider(id || 'custom-test', { ...config, apiKey });
+    // A provider with additional keys tests through the same key pool as a
+    // real request: an explicit quota refusal moves on to the next key.
+    const keyIds = id && !config.apiKeyEnv && config.auth !== 'none' ? customProviderKeyIds(id) : [];
+    let provider = primary;
+    let routingKey;
+    if (keyIds.length) {
+      const [pool, keys] = await Promise.all([
+        import('../../runtime/agent/orchestrator/providers/account-pool.mjs'),
+        import('../../runtime/agent/orchestrator/providers/custom-provider-keys.mjs'),
+      ]);
+      routingKey = pool.ROUTING_METADATA_KEY;
+      provider = pool.createCustomKeyPoolProvider(id, primary, (keyId) => keys.customKeyEngine(primary, id, keyId));
+    }
+    const answer = await withTimeout(
       (signal) => provider.send([{ role: 'user', content: 'Reply with OK.' }], model, [], { signal, maxTokens: 16 }),
       CUSTOM_TEST_TIMEOUT_MS,
       'connection test'
     );
-    return { ok: true };
+    // Key numbers count the primary key as 1.
+    const served = routingKey ? answer?.providerMetadata?.[routingKey]?.accountId : undefined;
+    const index = keyIds.indexOf(served);
+    return index < 0 ? { ok: true } : { ok: true, key: { id: served, number: index + 2 } };
   } catch (error) {
     throw sanitizeCustomError(error, customSecrets(apiKey, config));
   }

package/src/session-runtime/session-turn-api.mjs

@@ -36,6 +36,8 @@ export function createSessionTurnApi(deps) {
     agentControl: agent.agentControl,
     taskControl: agent.taskControl,
     stopShellJob: agent.stopShellJob,
+    listStoppableShellJobs: agent.listStoppableShellJobs,
+    stopShellJobs: agent.stopShellJobs,
     releaseShellJob: agent.releaseShellJob,
     listShellJobs: agent.listShellJobs,
     onNotification: agent.onNotification,

package/src/session-runtime/settings-builtin-tools-api.mjs

@@ -8,6 +8,7 @@ import {
   setBuiltinInstalledInConfig,
 } from '../runtime/agent/orchestrator/runtime-core/builtin-features.mjs';
 import { featureEnvOverride, moduleEnabled } from '../runtime/agent/orchestrator/runtime-core/config-helpers.mjs';
+import { noteCacheWarmingEnabled } from '../runtime/agent/orchestrator/session/cache-warm.mjs';
 import { normalizeAgentAvatar } from '../runtime/shared/agent-avatar.mjs';
 import { LOCAL_PROVIDER_ID } from '../runtime/local-provider/managed-runtime.mjs';
 import { INSTRUCTION_FILES_MODES, normalizeInstructionFilesMode } from '../runtime/shared/instruction-files-mode.mjs';
@@ -100,11 +101,13 @@ export function createBuiltinToolSettings(
     // default on. The warmer reads the saved value at each
     // warm, so a change applies without a restart.
     getCacheWarmingSettings() {
-      return { enabled: getConfig()?.promptCacheWarming !== false };
+      return { enabled: getConfig()?.promptCacheWarming === true };
     },
     setCacheWarmingEnabled(enabled) {
       if (typeof enabled !== 'boolean') throw new TypeError('cache warming must be on or off (a boolean)');
       saveConfigAndAdopt({ ...getConfig(), promptCacheWarming: enabled });
+      // The warmer's synchronous state follows at once (off cancels chains).
+      noteCacheWarmingEnabled(enabled);
       return this.getCacheWarmingSettings();
     },
     // The one pixel face every Lead row on the bot page wears, shared by every

package/src/session-runtime/settings-system-api.mjs

@@ -57,7 +57,7 @@ export function createSystemSettings({
     },
     getHeartbeatSettings() {
       return {
-        heartbeat: getConfig()?.heartbeat !== false,
+        heartbeat: getConfig()?.heartbeat === true,
         intervalMinutes: normalizeHeartbeatIntervalMinutes(getConfig()?.heartbeatIntervalMinutes),
       };
     },

package/src/session-runtime/setup-tool/agent-settings-actions.mjs

@@ -3,8 +3,12 @@
  *  prompt-cache warming. Each goes through the runtime method its settings
  *  surface uses. Permission and connector writes are made as a remote client's
  *  are (`noWiden`): a chat may take authority away, never give an agent more
- *  without asking — that stays with the person in the desktop app. */
+ *  without asking — that stays with the person: in the desktop app, or on
+ *  the approval card a connector tool's widening raises
+ *  (connector-widen-approval.mjs). */
+import { CONNECTOR_POLICY_WIDENS } from '../../runtime/agent/orchestrator/mcp/agent-connectors.mjs';
 import { agentPermissions, setAgentPermission } from '../../runtime/agent/orchestrator/session/human-gate/store.mjs';
+import { askToWidenConnectorTool } from './connector-widen-approval.mjs';
 import { clean } from '../../runtime/agent/orchestrator/runtime-core/session-text.mjs';
 
 const NO_WIDEN = Object.freeze({ noWiden: true });
@@ -38,11 +42,17 @@ export const AGENT_SETTINGS_HANDLERS = {
     const name = requireText(args.name, 'name');
     return { agent, connectors: await rt.setAgentConnectorEnabled(agent, name, args.enabled, NO_WIDEN) };
   },
-  async set_agent_connector_tool(rt, args) {
+  // A narrowing applies at once; a widening waits on the person's card.
+  async set_agent_connector_tool(rt, args, context) {
     const agent = requireText(args.agent, 'agent');
     const name = requireText(args.name, 'name');
     const tool = requireText(args.tool, 'tool');
-    await rt.setAgentConnectorToolPermission(agent, name, tool, args.permission, NO_WIDEN);
+    try {
+      await rt.setAgentConnectorToolPermission(agent, name, tool, args.permission, NO_WIDEN);
+    } catch (error) {
+      if (error?.code !== CONNECTOR_POLICY_WIDENS) throw error;
+      return askToWidenConnectorTool(rt, { agent, server: name, tool, requested: args.permission }, context);
+    }
     return { agent, connector: name, tool, permission: args.permission };
   },
   async set_project_connector(rt, args) {

package/src/session-runtime/setup-tool/connector-widen-approval.mjs

@@ -0,0 +1,96 @@
+/** A bot's request for more authority on one connector tool (setup
+ *  set_agent_connector_tool toward auto or needs_approval): the model cannot
+ *  tell the user's words from text it read, so the change waits on an
+ *  approval card (human-gate/requests.mjs kind `connector`) that only a
+ *  person answers. The card offers each level above the tool's current one
+ *  (needs_approval, auto) and Deny; nothing is remembered, so every widening
+ *  asks again. The picked level is applied to that one tool, re-judged on the
+ *  stored policy inside its write (mcp/agent-connectors.mjs
+ *  withApprovedConnectorToolChange): a restriction that landed meanwhile stays. */
+import {
+  CONNECTOR_TOOL_ALREADY,
+  CONNECTOR_TOOL_NARROWED,
+  NO_WIDEN_MESSAGE,
+  PERMISSION_RANK,
+  agentConnectors,
+  connectorGroupId,
+  connectorToolPermission,
+  withApprovedConnectorToolChange,
+} from '../../runtime/agent/orchestrator/mcp/agent-connectors.mjs';
+import { recordHumanDecision } from '../../runtime/agent/orchestrator/session/human-gate/gate.mjs';
+import { CONNECTOR_WIDEN_LEVELS } from '../../runtime/agent/orchestrator/session/human-gate/requests.mjs';
+import { runAbortable } from '../../runtime/shared/abort-race.mjs';
+
+const NO_WIDEN = Object.freeze({ noWiden: true });
+
+/** The tool's effective level for `agent` now, as dispatch reads it. */
+function currentLevel(agent, server, tool) {
+  return connectorToolPermission(agentConnectors(agent), {
+    name: `mcp__${server}__${tool}`,
+    mcpServerName: server,
+    mcpToolName: tool,
+  });
+}
+
+/** Ask the person on a card, then apply the level they picked.
+ *  `requestApproval` is the calling turn's approval hook. */
+export async function askToWidenConnectorTool(
+  rt,
+  { agent, server, tool, requested },
+  { requestApproval, signal, sessionId, toolCallId } = {}
+) {
+  const from = currentLevel(agent, server, tool);
+  const receipt = { agent, connector: server, tool, requested };
+  if (PERMISSION_RANK[from] >= PERMISSION_RANK[requested]) {
+    return { ...receipt, saved: false, permission: from, note: `The tool is already ${from}; nothing changed.` };
+  }
+  // Nobody can be shown a card here: the person makes it in the desktop app.
+  if (typeof requestApproval !== 'function') throw new Error(NO_WIDEN_MESSAGE);
+  const choices = CONNECTOR_WIDEN_LEVELS.filter((level) => PERMISSION_RANK[level] > PERMISSION_RANK[from]);
+  const answer = await runAbortable(signal, () =>
+    requestApproval({
+      name: 'setup',
+      kind: 'connector',
+      agentId: agent,
+      // The card names the connector, not one of its accounts.
+      connector: { server: connectorGroupId(server), tool, from, requested, choices },
+      args: { action: 'set_agent_connector_tool', agent, name: server, tool, permission: requested },
+      reason: `Bot "${agent}" asks to change the permission of ${tool} (${connectorGroupId(server)}) from ${from} to ${requested}.`,
+      remember: ['once'],
+      sessionId,
+      toolCallId,
+    })
+  );
+  const level = answer?.approved === true && choices.includes(answer.scope) ? answer.scope : '';
+  // Audited with the answering device; no grant is ever stored (no action kind).
+  await recordHumanDecision(
+    { agentId: agent, kind: 'connector', tool: `${server}/${tool}`, target: `${from}>${level || requested}` },
+    answer
+  );
+  // A decision that settles after its turn was cancelled authorizes nothing.
+  signal?.throwIfAborted();
+  if (!level) {
+    const why = answer?.timedOut ? 'The approval card timed out' : 'The user did not approve this change';
+    return { ...receipt, saved: false, approved: false, permission: from, note: `${why}; nothing changed.` };
+  }
+  try {
+    await withApprovedConnectorToolChange({ server, tool, from, to: level }, () =>
+      rt.setAgentConnectorToolPermission(agent, server, tool, level, NO_WIDEN)
+    );
+  } catch (error) {
+    if (error?.code !== CONNECTOR_TOOL_NARROWED && error?.code !== CONNECTOR_TOOL_ALREADY) throw error;
+    return {
+      ...receipt,
+      saved: false,
+      approved: true,
+      permission: currentLevel(agent, server, tool),
+      note: `The user approved ${level}, but it was not applied: ${error.message}`,
+    };
+  }
+  return {
+    ...receipt,
+    approved: true,
+    permission: level,
+    note: `The user approved on the card; ${tool} is now ${level}.`,
+  };
+}

package/src/session-runtime/setup-tool/executor.mjs

@@ -364,7 +364,7 @@ async function featureStatus(rt, getConfig) {
     computer: { active: builtinFeatureActive(config, 'computer') },
     terminal: { active: builtinFeatureActive(config, 'terminal') },
     heartbeat: {
-      enabled: config?.heartbeat !== false,
+      enabled: config?.heartbeat === true,
       intervalMinutes: normalizeHeartbeatIntervalMinutes(config?.heartbeatIntervalMinutes),
     },
     reactions: { enabled: config?.reactions !== false },
@@ -909,7 +909,7 @@ export function createSetupToolExecutor({
     };
   }
 
-  async function execute(args, { signal, callerSessionId }) {
+  async function execute(args, { signal, callerSessionId, requestApproval = null, toolCallId = null }) {
     signal?.throwIfAborted();
     const requestDesktop = (request) => desktop.request(request, { signal });
     const action = validateSetupInput(args);
@@ -948,6 +948,10 @@ export function createSetupToolExecutor({
       getSession: getCallerSession,
       getConfig: () => getConfig?.() || {},
       executeSessionControl,
+      // The calling turn's approval card (a connector tool's widening asks the person).
+      requestApproval,
+      signal,
+      toolCallId,
     });
   }
 

package/src/session-runtime/setup-tool/tool-defs.mjs

@@ -477,7 +477,8 @@ export const SETUP_TOOL_DEFS = Object.freeze([
         permission: {
           type: 'string',
           enum: [...CONNECTOR_PERMISSIONS],
-          description: 'set_agent_connector_tool: needs_approval or disabled; auto is made in the desktop app.',
+          description:
+            'set_agent_connector_tool: a narrowing (toward disabled) applies at once; a widening (disabled → needs_approval/auto, needs_approval → auto) waits on an approval card the user answers (needs_approval, auto or deny, whatever was asked) and the result says what was applied.',
         },
         botOrder: {
           type: 'array',

package/src/session-runtime/tool-policy/policy-stage.mjs

@@ -135,6 +135,7 @@ export function createPolicyStage({
         : _buildBaseRules({
             omitTools: [...denied, unusedModelEditToolName(getRoute()?.model)],
             allowTools: schemaAllowedTools,
+            ownerIsAgent,
             provider: getRoute()?.provider,
             model: getRoute()?.model,
           });