@agent-native/core 0.145.0 → 0.145.2

package/corpus/templates/clips/desktop/src-tauri/src/state.rs

@@ -1,6 +1,6 @@
 use std::sync::Mutex;
 use std::time::Instant;
-use tauri::Rect;
+use tauri::{AppHandle, Manager, Rect};
 
 use crate::tray_meetings::MeetingItem;
 
@@ -63,3 +63,29 @@ pub struct VoiceTargetBundle(pub Mutex<Option<String>>);
 /// Last dictation result for "paste last".
 #[derive(Default)]
 pub struct LastTranscript(pub Mutex<Option<String>>);
+
+/// CGDirectDisplayID the user picked in the multi-monitor screen picker,
+/// applying for the whole lifetime of the recording it was picked for (not
+/// just the first read) — `tray_display_id` and `tray_monitor_physical_rect`
+/// both read it via `get`. Cleared via `set(app, None)` by `show_monitor_picker`
+/// (next pick), `hide_recording_chrome` (stop), and
+/// `native_fullscreen_recording_cancel` (aborted start) — a stale pick must
+/// never leak into a later recording that skipped the picker (e.g. only one
+/// monitor connected).
+#[derive(Default)]
+pub struct SelectedRecordingDisplay(pub Mutex<Option<u32>>);
+
+impl SelectedRecordingDisplay {
+    pub fn get(app: &AppHandle) -> Option<u32> {
+        app.try_state::<Self>()
+            .and_then(|s| s.0.lock().ok().and_then(|g| *g))
+    }
+
+    pub fn set(app: &AppHandle, display_id: Option<u32>) {
+        if let Some(state) = app.try_state::<Self>() {
+            if let Ok(mut guard) = state.0.lock() {
+                *guard = display_id;
+            }
+        }
+    }
+}

package/corpus/templates/clips/desktop/src-tauri/src/util.rs

@@ -2,7 +2,8 @@ use tauri::{AppHandle, Emitter, Manager, WebviewUrl, WebviewWindow, WebviewWindo
 
 use crate::dlog;
 use crate::state::{
-    DictationActive, PopoverShownAt, RecordingActive, TrayAnchor, VoiceWakePopover,
+    DictationActive, PopoverShownAt, RecordingActive, SelectedRecordingDisplay, TrayAnchor,
+    VoiceWakePopover,
 };
 
 const POPOVER_SHADOW_GUTTER_LOGICAL: f64 = 24.0;
@@ -369,6 +370,16 @@ pub fn present_interactive_window(window: &WebviewWindow) {
 /// instead of `primary_monitor_physical_size` for any overlay that should appear
 /// on the same screen as the recording.
 pub fn tray_monitor_physical_rect(app: &AppHandle) -> (i32, i32, u32, u32) {
+    // A monitor picked in the multi-monitor screen picker wins over the tray
+    // icon's monitor for every overlay shown during that recording
+    // (countdown, toolbar, finalizing, region guides, ...) — see
+    // `SelectedRecordingDisplay`'s doc comment for its lifecycle.
+    if let Some(id) = SelectedRecordingDisplay::get(app) {
+        if let Some(rect) = crate::native_screen::monitor_rect_for_display_id(app, id) {
+            return rect;
+        }
+    }
+
     let tray_rect = app
         .try_state::<TrayAnchor>()
         .and_then(|a| a.0.lock().ok().and_then(|g| *g));

package/dist/agent/engine/index.d.ts

@@ -2,7 +2,7 @@
  * Public exports for the pluggable agent engine system.
  */
 export type { AgentEngine, EngineCapabilities, EngineTool, EngineMessage, EngineContentPart, EngineTextPart, EngineImagePart, EngineToolCallPart, EngineToolResultPart, EngineThinkingPart, EngineEvent, EngineStreamOptions, } from "./types.js";
-export { registerAgentEngine, getAgentEngineEntry, listAgentEngines, resolveEngine, getConfiguredEngineNameForRequest, getStoredModelForEngine, normalizeModelForEngine, resolveDelegatedRunModel, resolveEnginePreservesCustomModels, type NormalizeModelOptions, detectEngineFromEnv, detectEngineFromEnvForRequest, detectEngineFromUserSecrets, isAgentEngineSettingConfigured, isAgentEnginePackageInstalled, isStoredEngineUsable, isStoredEngineUsableForRequest, isResolvedEngineUsableForRequest, type AgentEngineEntry, type ResolveEngineConfig, } from "./registry.js";
+export { registerAgentEngine, getAgentEngineEntry, listAgentEngines, resolveEngine, explicitEngineName, getConfiguredEngineNameForRequest, getStoredModelForEngine, normalizeModelForEngine, resolveDelegatedRunModel, resolveEnginePreservesCustomModels, type NormalizeModelOptions, detectEngineFromEnv, detectEngineFromEnvForRequest, detectEngineFromUserSecrets, isAgentEngineSettingConfigured, isAgentEnginePackageInstalled, isStoredEngineUsable, isStoredEngineUsableForRequest, isResolvedEngineUsableForRequest, type AgentEngineEntry, type ResolveEngineConfig, } from "./registry.js";
 export { createBuilderEngine, BUILDER_DEFAULT_MODEL, BUILDER_SUPPORTED_MODELS, BUILDER_CAPABILITIES, } from "./builder-engine.js";
 export { createAnthropicEngine, ANTHROPIC_DEFAULT_MODEL, ANTHROPIC_SUPPORTED_MODELS, ANTHROPIC_CAPABILITIES, } from "./anthropic-engine.js";
 export { createAISDKEngine, type AISDKProvider } from "./ai-sdk-engine.js";

package/dist/agent/engine/index.js

@@ -1,7 +1,7 @@
 /**
  * Public exports for the pluggable agent engine system.
  */
-export { registerAgentEngine, getAgentEngineEntry, listAgentEngines, resolveEngine, getConfiguredEngineNameForRequest, getStoredModelForEngine, normalizeModelForEngine, resolveDelegatedRunModel, resolveEnginePreservesCustomModels, detectEngineFromEnv, detectEngineFromEnvForRequest, detectEngineFromUserSecrets, isAgentEngineSettingConfigured, isAgentEnginePackageInstalled, isStoredEngineUsable, isStoredEngineUsableForRequest, isResolvedEngineUsableForRequest, } from "./registry.js";
+export { registerAgentEngine, getAgentEngineEntry, listAgentEngines, resolveEngine, explicitEngineName, getConfiguredEngineNameForRequest, getStoredModelForEngine, normalizeModelForEngine, resolveDelegatedRunModel, resolveEnginePreservesCustomModels, detectEngineFromEnv, detectEngineFromEnvForRequest, detectEngineFromUserSecrets, isAgentEngineSettingConfigured, isAgentEnginePackageInstalled, isStoredEngineUsable, isStoredEngineUsableForRequest, isResolvedEngineUsableForRequest, } from "./registry.js";
 export { createBuilderEngine, BUILDER_DEFAULT_MODEL, BUILDER_SUPPORTED_MODELS, BUILDER_CAPABILITIES, } from "./builder-engine.js";
 export { createAnthropicEngine, ANTHROPIC_DEFAULT_MODEL, ANTHROPIC_SUPPORTED_MODELS, ANTHROPIC_CAPABILITIES, } from "./anthropic-engine.js";
 export { createAISDKEngine } from "./ai-sdk-engine.js";

package/dist/agent/engine/registry.d.ts

@@ -174,11 +174,26 @@ export interface ResolveEngineConfig {
     };
     /** API key (used as config for the resolved engine) */
     apiKey?: string;
+    /**
+     * Env var name `apiKey` was issued for, when the caller knows it. Declaring
+     * it keeps a provider-specific credential from reaching a different
+     * provider's engine; omit it for opaque keys.
+     */
+    apiKeyEnvVar?: string;
     /** Model override (used as part of engine config) */
     model?: string;
     /** App/template id used for org-scoped per-app model defaults. */
     appId?: string;
 }
+/**
+ * Engine name a caller explicitly selected, when {@link resolveEngine} will
+ * honor it as a name. Callers resolve the API key before they call
+ * `resolveEngine`, so they need the same answer the registry will reach:
+ * an untagged "active" key resolved against a different provider's setting
+ * would otherwise ride along to whichever engine this names. Returns
+ * `undefined` for an engine instance, which carries its own credential.
+ */
+export declare function explicitEngineName(engineOption: ResolveEngineConfig["engineOption"]): string | undefined;
 /**
  * Return the usable engine explicitly selected by the current user/org.
  *

package/dist/agent/engine/registry.js

@@ -559,9 +559,18 @@ async function apiKeyBelongsToDifferentProvider(apiKey, selectedEntry) {
     }
     return false;
 }
-async function engineCreateConfigForEntry(entry, apiKey, extra, preferResolvedCredential = false) {
+async function engineCreateConfigForEntry(entry, apiKey, extra, preferResolvedCredential = false, apiKeyEnvVar) {
     const safeExtra = { ...(extra ?? {}) };
     let matchingApiKey = apiKey;
+    // A declared provenance settles the question without inspecting values: a
+    // credential issued for another provider's env var is never this entry's
+    // key, so drop it on explicit branches too. Value comparison below cannot
+    // cover this — a host-supplied key (plugin `options.apiKey`) matches no
+    // stored secret, so it would otherwise reach whichever provider was picked.
+    if (apiKeyEnvVar !== undefined &&
+        !entry.requiredEnvVars.includes(apiKeyEnvVar)) {
+        matchingApiKey = undefined;
+    }
     // Automatic engine selection must also select that engine's credential.
     // Callers historically passed one untagged "active" key before the registry
     // chose an engine, which could hand an Anthropic key to an app-default
@@ -687,6 +696,26 @@ export async function isResolvedEngineUsableForRequest(engine, options = {}) {
     }
     return true;
 }
+/**
+ * Engine name a caller explicitly selected, when {@link resolveEngine} will
+ * honor it as a name. Callers resolve the API key before they call
+ * `resolveEngine`, so they need the same answer the registry will reach:
+ * an untagged "active" key resolved against a different provider's setting
+ * would otherwise ride along to whichever engine this names. Returns
+ * `undefined` for an engine instance, which carries its own credential.
+ */
+export function explicitEngineName(engineOption) {
+    if (!engineOption)
+        return undefined;
+    if (typeof engineOption === "string")
+        return engineOption;
+    if (typeof engineOption === "object" &&
+        !("stream" in engineOption) &&
+        typeof engineOption.name === "string") {
+        return engineOption.name;
+    }
+    return undefined;
+}
 /**
  * Return the usable engine explicitly selected by the current user/org.
  *
@@ -734,7 +763,7 @@ export async function getConfiguredEngineNameForRequest(options = {}) {
  * 7. Default "anthropic" (requires ANTHROPIC_API_KEY)
  */
 export async function resolveEngine(config) {
-    const { engineOption, apiKey, model: _model, appId } = config;
+    const { engineOption, apiKey, apiKeyEnvVar, model: _model, appId } = config;
     // 1. Explicit instance passed directly
     if (engineOption &&
         typeof engineOption === "object" &&
@@ -750,7 +779,7 @@ export async function resolveEngine(config) {
         if (!entry)
             throw new Error(`[agent-engine] Unknown engine: "${name}". Registered: ${[..._registry.keys()].join(", ")}`);
         assertAgentEnginePackageInstalled(entry);
-        return entry.create(await engineCreateConfigForEntry(entry, apiKey, engineConfig));
+        return entry.create(await engineCreateConfigForEntry(entry, apiKey, engineConfig, false, apiKeyEnvVar));
     }
     // 3. Explicit string name from options
     if (typeof engineOption === "string") {
@@ -758,7 +787,7 @@ export async function resolveEngine(config) {
         if (!entry)
             throw new Error(`[agent-engine] Unknown engine: "${engineOption}". Registered: ${[..._registry.keys()].join(", ")}`);
         assertAgentEnginePackageInstalled(entry);
-        return entry.create(await engineCreateConfigForEntry(entry, apiKey));
+        return entry.create(await engineCreateConfigForEntry(entry, apiKey, undefined, false, apiKeyEnvVar));
     }
     // 4. Env var — explicit engine name override
     const envEngine = process.env.AGENT_ENGINE;
@@ -766,14 +795,14 @@ export async function resolveEngine(config) {
         const entry = _registry.get(envEngine);
         if (entry) {
             assertAgentEnginePackageInstalled(entry);
-            return entry.create(await engineCreateConfigForEntry(entry, apiKey, undefined, true));
+            return entry.create(await engineCreateConfigForEntry(entry, apiKey, undefined, true, apiKeyEnvVar));
         }
     }
     const appDefault = await getAgentAppModelDefaultForCurrentRequest(appId);
     if (appDefault?.engine) {
         const entry = _registry.get(appDefault.engine);
         if (entry && (await isStoredEngineUsableForRequest(appDefault, entry))) {
-            return entry.create(await engineCreateConfigForEntry(entry, apiKey, undefined, true));
+            return entry.create(await engineCreateConfigForEntry(entry, apiKey, undefined, true, apiKeyEnvVar));
         }
     }
     let stored = null;
@@ -797,25 +826,25 @@ export async function resolveEngine(config) {
     if (storedRaw && typeof storedEngine === "string") {
         const entry = _registry.get(storedEngine);
         if (entry && (await isStoredEngineUsableForRequest(storedRaw, entry))) {
-            return entry.create(await engineCreateConfigForEntry(entry, apiKey, stripInlineApiKeyConfig(storedConfig), true));
+            return entry.create(await engineCreateConfigForEntry(entry, apiKey, stripInlineApiKeyConfig(storedConfig), true, apiKeyEnvVar));
         }
     }
     if (detectedFromUser) {
-        return detectedFromUser.create(await engineCreateConfigForEntry(detectedFromUser, apiKey, undefined, true));
+        return detectedFromUser.create(await engineCreateConfigForEntry(detectedFromUser, apiKey, undefined, true, apiKeyEnvVar));
     }
     // 8. Auto-detect from any provider env var — so just dropping a key in
     // .env works without also setting AGENT_ENGINE. Skip keys with active
     // auth-failure markers so a rejected deploy key cannot permanently win.
     const detected = await detectEngineFromEnvForRequest();
     if (detected) {
-        return detected.create(await engineCreateConfigForEntry(detected, apiKey, undefined, true));
+        return detected.create(await engineCreateConfigForEntry(detected, apiKey, undefined, true, apiKeyEnvVar));
     }
     // 9. Default: anthropic
     const anthropicEntry = _registry.get("anthropic");
     if (!anthropicEntry) {
         throw new Error("[agent-engine] Default Anthropic engine is not registered. Did builtin.ts fail to load?");
     }
-    return anthropicEntry.create(await engineCreateConfigForEntry(anthropicEntry, apiKey, undefined, true));
+    return anthropicEntry.create(await engineCreateConfigForEntry(anthropicEntry, apiKey, undefined, true, apiKeyEnvVar));
 }
 /**
  * Read the user-selected model for an engine from the `agent-engine` setting.

package/dist/agent/production-agent.d.ts

@@ -3,6 +3,7 @@ import type { Task } from "../a2a/types.js";
 import { type ActionAutomationContext, type ActionCaller } from "../action.js";
 import { fireInternalDispatch } from "../server/self-dispatch.js";
 import { type ReasoningEffort } from "../shared/reasoning-effort.js";
+import { type ResolveEngineConfig } from "./engine/index.js";
 import { PROVIDER_TO_ENV } from "./engine/provider-env-vars.js";
 import type { AgentEngine, EngineTool, EngineMessage, EngineContentPart } from "./engine/types.js";
 import { type Processor } from "./processors.js";
@@ -99,18 +100,56 @@ export declare function getOwnerApiKey(provider: string, ownerEmail: string | nu
  * "ai-sdk:openai" → "openai", "anthropic" → "anthropic"
  */
 export declare function engineToProvider(engineName: string): string;
+/** An API key together with the env var it was issued for. */
+export interface ResolvedOwnerApiKey {
+    apiKey: string | undefined;
+    /** Undefined when no key was found, or when the key's provider is unknown. */
+    apiKeyEnvVar: string | undefined;
+}
 /**
- * Resolve the active engine's provider and look up the user's API key for it.
+ * Resolve the owner's key for one named engine, tagged with the env var it was
+ * issued for.
  *
  * If the owner has no scoped key, fall back to provider keys supplied by the
  * hosting environment only when the current request can safely use deploy-level
  * credentials. This is a read from process-level config, not a request-scoped
  * write to `process.env`.
+ */
+export declare function getOwnerApiKeyForEngine(engineName: string, ownerEmail: string | null | undefined): Promise<ResolvedOwnerApiKey>;
+/**
+ * Resolve the active engine's provider and look up the user's API key for it.
  *
  * Callers that layer another deployment-key fallback after this should keep the
  * same precedence: scoped key first, host-provided env key second.
+ *
+ * The returned key is untagged, so it is only safe to hand to `resolveEngine`
+ * when the caller has no explicit engine of its own — otherwise the active
+ * setting and the selected engine can name different providers. Prefer
+ * {@link resolveOwnerEngineApiKey}, which decides that per call site.
  */
 export declare function getOwnerActiveApiKey(ownerEmail: string | null | undefined): Promise<string | undefined>;
+/**
+ * Resolve the credential to hand `resolveEngine` alongside `engineOption`.
+ *
+ * The provenance is the point. An explicitly named engine skips the registry's
+ * value-comparison path, so an untagged key resolved from the saved
+ * `agent-engine` setting would ride along to whatever provider the caller
+ * named — shipping, say, a live Anthropic secret to OpenAI's endpoint and
+ * making the resulting 401 blame a key the user never saved. Resolving the key
+ * for the named engine keeps the two in step; only the no-explicit-engine case
+ * may stay untagged, because the registry's automatic branches re-derive the
+ * credential themselves.
+ */
+export declare function resolveOwnerEngineApiKey(input: {
+    engineOption?: ResolveEngineConfig["engineOption"];
+    ownerEmail: string | null | undefined;
+    /**
+     * Host-provided credential, which is Anthropic by contract
+     * (`AgentChatPluginOptions.apiKey` / `WebhookHandlerOptions.apiKey`). Used
+     * only when no owner key was found.
+     */
+    anthropicFallback?: string;
+}): Promise<ResolvedOwnerApiKey>;
 /** @deprecated Use getOwnerApiKey("anthropic", ownerEmail) instead */
 export declare function getOwnerAnthropicApiKey(ownerEmail: string | null | undefined): Promise<string | undefined>;
 /**

package/dist/agent/production-agent.js

@@ -27,7 +27,7 @@ import { applyContextXrayTransformForIteration } from "./engine/context-directiv
 import { attemptContinuationDispatch } from "./engine/continuation-dispatch-retry.js";
 import { LLM_MISSING_CREDENTIALS_ERROR_CODE, LLM_MISSING_CREDENTIALS_MESSAGE, userFacingLlmCredentialError, } from "./engine/credential-errors.js";
 import { isProviderConnectionErrorMessage } from "./engine/error-detail.js";
-import { resolveEngine, registerBuiltinEngines, getStoredModelForEngine, normalizeModelForEngine, isResolvedEngineUsableForRequest, } from "./engine/index.js";
+import { resolveEngine, explicitEngineName, registerBuiltinEngines, getStoredModelForEngine, normalizeModelForEngine, isResolvedEngineUsableForRequest, } from "./engine/index.js";
 import { resolveEmptyResponseRetryMaxOutputTokens, resolveMainChatMaxOutputTokens, resolveMaxOutputTokensForEngine, } from "./engine/output-tokens.js";
 import { PROVIDER_TO_ENV } from "./engine/provider-env-vars.js";
 import { loadPriorTurnToolCallJournal } from "./engine/tool-call-journal-seed.js";
@@ -300,41 +300,92 @@ export async function getOwnerApiKey(provider, ownerEmail) {
 export function engineToProvider(engineName) {
     return engineName.startsWith("ai-sdk:") ? engineName.slice(7) : engineName;
 }
+const NO_OWNER_API_KEY = {
+    apiKey: undefined,
+    apiKeyEnvVar: undefined,
+};
 /**
- * Resolve the active engine's provider and look up the user's API key for it.
+ * Resolve the owner's key for one named engine, tagged with the env var it was
+ * issued for.
  *
  * If the owner has no scoped key, fall back to provider keys supplied by the
  * hosting environment only when the current request can safely use deploy-level
  * credentials. This is a read from process-level config, not a request-scoped
  * write to `process.env`.
- *
- * Callers that layer another deployment-key fallback after this should keep the
- * same precedence: scoped key first, host-provided env key second.
  */
-export async function getOwnerActiveApiKey(ownerEmail) {
+export async function getOwnerApiKeyForEngine(engineName, ownerEmail) {
     try {
-        const { getSetting } = await import("../settings/store.js");
-        const engineSetting = await getSetting("agent-engine");
-        const activeEngine = engineSetting?.engine ?? "anthropic";
-        const provider = engineToProvider(activeEngine);
+        const provider = engineToProvider(engineName);
+        const envVar = PROVIDER_TO_ENV[provider];
         const userKey = await getOwnerApiKey(provider, ownerEmail);
         if (userKey)
-            return userKey;
-        const envVar = PROVIDER_TO_ENV[provider];
+            return { apiKey: userKey, apiKeyEnvVar: envVar };
         if (!envVar || !canUseDeployCredentialFallbackForRequest(envVar)) {
-            return undefined;
+            return NO_OWNER_API_KEY;
         }
         const envKey = readDeployCredentialEnv(envVar);
         if (envKey &&
             !(await getProviderCredentialAuthFailure({ key: envVar, value: envKey }))) {
-            return envKey;
+            return { apiKey: envKey, apiKeyEnvVar: envVar };
         }
-        return undefined;
+        return NO_OWNER_API_KEY;
+    }
+    catch {
+        return NO_OWNER_API_KEY;
+    }
+}
+/**
+ * Resolve the active engine's provider and look up the user's API key for it.
+ *
+ * Callers that layer another deployment-key fallback after this should keep the
+ * same precedence: scoped key first, host-provided env key second.
+ *
+ * The returned key is untagged, so it is only safe to hand to `resolveEngine`
+ * when the caller has no explicit engine of its own — otherwise the active
+ * setting and the selected engine can name different providers. Prefer
+ * {@link resolveOwnerEngineApiKey}, which decides that per call site.
+ */
+export async function getOwnerActiveApiKey(ownerEmail) {
+    try {
+        const { getSetting } = await import("../settings/store.js");
+        const engineSetting = await getSetting("agent-engine");
+        const activeEngine = engineSetting?.engine ?? "anthropic";
+        return (await getOwnerApiKeyForEngine(activeEngine, ownerEmail)).apiKey;
     }
     catch {
         return undefined;
     }
 }
+/**
+ * Resolve the credential to hand `resolveEngine` alongside `engineOption`.
+ *
+ * The provenance is the point. An explicitly named engine skips the registry's
+ * value-comparison path, so an untagged key resolved from the saved
+ * `agent-engine` setting would ride along to whatever provider the caller
+ * named — shipping, say, a live Anthropic secret to OpenAI's endpoint and
+ * making the resulting 401 blame a key the user never saved. Resolving the key
+ * for the named engine keeps the two in step; only the no-explicit-engine case
+ * may stay untagged, because the registry's automatic branches re-derive the
+ * credential themselves.
+ */
+export async function resolveOwnerEngineApiKey(input) {
+    const engineName = explicitEngineName(input.engineOption);
+    if (engineName) {
+        const resolved = await getOwnerApiKeyForEngine(engineName, input.ownerEmail);
+        if (resolved.apiKey)
+            return resolved;
+    }
+    else {
+        const activeKey = await getOwnerActiveApiKey(input.ownerEmail);
+        if (activeKey)
+            return { apiKey: activeKey, apiKeyEnvVar: undefined };
+    }
+    const fallback = input.anthropicFallback?.trim();
+    return fallback &&
+        canUseDeployCredentialFallbackForRequest("ANTHROPIC_API_KEY")
+        ? { apiKey: fallback, apiKeyEnvVar: "ANTHROPIC_API_KEY" }
+        : NO_OWNER_API_KEY;
+}
 /** @deprecated Use getOwnerApiKey("anthropic", ownerEmail) instead */
 export async function getOwnerAnthropicApiKey(ownerEmail) {
     return getOwnerApiKey("anthropic", ownerEmail);
@@ -5884,34 +5935,22 @@ export function createProductionAgentHandler(options) {
         }
         // DIAGNOSTIC-ONLY: attachment upload + persistence finished.
         workerStep("attach_done");
-        // When a per-request engine override is specified, resolve the API key
-        // for that provider instead of the global active engine's provider.
+        // Resolve the key for the engine this request will actually select — the
+        // per-request override when there is one, otherwise the plugin's own
+        // engine — instead of the global active engine's provider.
+        // `options.apiKey` is the value the template constructed the plugin with
+        // (often wired from a deployment env var). Honor it as host-provided
+        // read-only configuration after scoped keys.
         // DIAGNOSTIC-ONLY: bracket per-owner API-key resolution (settings/app_secrets reads).
         workerStep("apikey_start");
-        let userApiKey;
-        if (requestEngine) {
-            const provider = engineToProvider(requestEngine);
-            userApiKey = await getOwnerApiKey(provider, ownerEmail);
-            const envVar = PROVIDER_TO_ENV[provider];
-            if (!userApiKey &&
-                envVar &&
-                canUseDeployCredentialFallbackForRequest(envVar)) {
-                // Read-only env fallback for the requested provider.
-                userApiKey = envVar ? readDeployCredentialEnv(envVar) : undefined;
-            }
-        }
-        else {
-            userApiKey = await getOwnerActiveApiKey(ownerEmail);
-        }
+        const engineOption = requestEngine ?? options.engine;
+        const { apiKey: effectiveApiKey, apiKeyEnvVar: effectiveApiKeyEnvVar } = await resolveOwnerEngineApiKey({
+            engineOption,
+            ownerEmail,
+            anthropicFallback: options.apiKey ?? readDeployCredentialEnv("ANTHROPIC_API_KEY"),
+        });
         // DIAGNOSTIC-ONLY: API-key resolution finished.
         workerStep("apikey_done");
-        // `options.apiKey` is the value the template constructed the plugin with
-        // (often wired from a deployment env var). Honor it as host-provided
-        // read-only configuration after scoped keys when deploy fallback is safe.
-        const hostApiKey = canUseDeployCredentialFallbackForRequest("ANTHROPIC_API_KEY")
-            ? (options.apiKey ?? readDeployCredentialEnv("ANTHROPIC_API_KEY"))
-            : undefined;
-        const effectiveApiKey = userApiKey ?? hostApiKey;
         // Resolve engine — per-request engine override takes priority
         // DIAGNOSTIC-ONLY: bracket engine resolution (Builder credential / app-default
         // settings reads inside resolveEngine).
@@ -5919,8 +5958,9 @@ export function createProductionAgentHandler(options) {
         let engine;
         try {
             engine = await resolveEngine({
-                engineOption: requestEngine ?? options.engine,
+                engineOption,
                 apiKey: effectiveApiKey,
+                apiKeyEnvVar: effectiveApiKeyEnvVar,
                 model: configuredModel,
                 appId: options.appId,
             });
@@ -5928,6 +5968,7 @@ export function createProductionAgentHandler(options) {
         catch {
             engine = await resolveEngine({
                 apiKey: effectiveApiKey,
+                apiKeyEnvVar: effectiveApiKeyEnvVar,
                 appId: options.appId,
             });
         }

package/dist/agent/run-manager.d.ts

@@ -181,13 +181,56 @@ export declare const SQL_SUBSCRIPTION_IDLE_POLL_MS = 500;
 export declare const SQL_SUBSCRIPTION_ACTIVE_GRACE_MS = 2000;
 /** Keep terminal/status probes at the historical cadence to bound DB work. */
 export declare const SQL_SUBSCRIPTION_STATUS_POLL_MS = 500;
+/**
+ * Consecutive empty polls before the IDLE cadence starts decaying toward
+ * `SQL_SUBSCRIPTION_IDLE_MAX_POLL_MS`.
+ *
+ * The active grace already covers a streaming producer, so decay only ever
+ * applies to a subscriber watching a run that is producing nothing: a long tool
+ * call, a slow first token, or a wedged producer. Those cost one poll per
+ * 500ms each, forever, per subscriber — the single largest source of idle
+ * `agent_run_events` reads.
+ */
+export declare const SQL_SUBSCRIPTION_IDLE_DECAY_AFTER_POLLS = 4;
+/**
+ * Ceiling for the decayed idle cadence. Bounds the WORST-CASE added latency to
+ * the next token a quiet run eventually produces; a row already waiting when the
+ * timer fires is delivered immediately, so this is not added to a streaming run.
+ */
+export declare const SQL_SUBSCRIPTION_IDLE_MAX_POLL_MS = 2000;
+/**
+ * Cadence for the opportunistic `reapIfStale` probe inside the SSE poll loop,
+ * kept SEPARATE from (and much slower than) the status probe next to it.
+ *
+ * A reap can only ever act on a run whose liveness basis is older than the
+ * tightest staleness window any sweep enforces — `RUN_STALE_MS`, 15s — so
+ * running it on the 500ms status cadence issued ~30 rounds of
+ * `reconcileTerminalRunFromEvents` + reap-eligibility queries (2-4 round trips
+ * each) before the first one could possibly match a row. This cadence still
+ * detects a stale producer well inside the client's own idle timeout while
+ * cutting that probe traffic ~10x. `getRunById` deliberately stays on the fast
+ * status cadence: it is one indexed read and it is what closes the stream on a
+ * NORMAL finish, which must stay prompt.
+ */
+export declare const SQL_SUBSCRIPTION_REAP_POLL_MS = 5000;
 /** Initial retry delay after a transient cross-isolate SQL polling failure. */
 export declare const SQL_SUBSCRIPTION_RETRY_BASE_MS = 250;
 /** Bound consecutive SQL polling failures so a dead subscription fails loud. */
 export declare const SQL_SUBSCRIPTION_MAX_CONSECUTIVE_FAILURES = 4;
 /** Cap retry delay even if the failure bound changes independently. */
 export declare const SQL_SUBSCRIPTION_RETRY_MAX_MS = 2000;
-export declare function resolveSqlSubscriptionPollMs(now: number, activePollUntil: number): number;
+export declare function resolveSqlSubscriptionPollMs(now: number, activePollUntil: number, consecutiveEmptyPolls?: number): number;
+/**
+ * Advance the empty-poll counter that drives `resolveSqlSubscriptionPollMs`'s
+ * decay.
+ *
+ * Only IDLE polls count. Counting the ~16 fast polls inside the active grace
+ * window would push the ladder to its cap the instant the grace expired, so a
+ * producer that pauses a few seconds between tokens would resume at the 2s cap
+ * instead of 500ms — a visible mid-stream stutter rather than the intended
+ * "this run has gone quiet" backoff.
+ */
+export declare function nextSqlSubscriptionEmptyPolls(current: number, hadEvents: boolean, now: number, activePollUntil: number): number;
 export declare function resolveSqlSubscriptionRetryMs(consecutiveFailures: number): number;
 export interface StartRunOptions {
     /** Keep a request-scoped serverless invocation alive for this run. */