@aitne/daemon 0.1.0

package/dist/core/backends/backend-router.js

@@ -0,0 +1,759 @@
+import { backendHasIntegrationConnector, delegatedIntegrationsForProcessKey, getDefaultTierForProcessKey, isCustomRoutineKey, isProcessKey, resolveProcessKey, TIER_LOCKED_PROCESS_KEYS, } from "@aitne/shared";
+import { readIntegrations } from "../../db/integrations-store.js";
+import { createLogger } from "../../logging.js";
+import { BackendDecisiveFailure, BackendQuotaError, } from "../agent-core.js";
+import { DEFAULT_CLAUDE_HIGH_MODEL, DEFAULT_CLAUDE_LITE_MODEL, DEFAULT_CLAUDE_MEDIUM_MODEL, findRegisteredModel, getModelsForBackend, } from "./model-registry.js";
+import { readCachedAuthStatus, recordReactiveAuthFailure, recordReactiveAuthSuccess, } from "./auth-health-monitor.js";
+const logger = createLogger("backend-router");
+/**
+ * Per-process maxTurns caps, applied when no DB-level process_backend_config
+ * override exists. Values are set at P95+ of observed turn distributions
+ * (see docs/design/appendices/token-efficiency-audit.md §1C).
+ */
+const PROCESS_MAX_TURNS = {
+    "routine.morning_routine": 50, // avg 17.7, max observed 35 — 300 was 8.5x max
+    "routine.hourly_check": 30, // P90=25, pad for complex observation sets
+    "routine.roadmap_refresh": 25, // single observed run was 13 turns
+    "message.dm": 35, // most <15, allow long conversations
+};
+const NOTIFICATION_DEDUPE_WINDOW_MS = 2 * 60 * 60 * 1000;
+/**
+ * One-line root-cause summary embedded in `BackendRouterHandledError.message`
+ * so operators reading dashboard / log output see *why* the backend failed
+ * without having to open the JSON payload. Format:
+ *   - quota:    `quota:<originalCode> — <inner message>`
+ *   - decisive: `<kind> — <inner cause message>` (e.g. `auth — 401 expired`)
+ */
+function describeBackendFailure(failure) {
+    if (failure instanceof BackendQuotaError) {
+        return `quota:${failure.originalCode} — ${failure.message}`;
+    }
+    const innerMessage = failure.cause instanceof Error
+        ? failure.cause.message
+        : failure.cause !== undefined
+            ? String(failure.cause)
+            : failure.message;
+    return `${failure.kind} — ${innerMessage}`;
+}
+export class BackendRouterHandledError extends Error {
+    cause;
+    mainFailure;
+    fallbackFailure;
+    constructor(message, cause, mainFailure, fallbackFailure = null) {
+        super(message);
+        this.cause = cause;
+        this.mainFailure = mainFailure;
+        this.fallbackFailure = fallbackFailure;
+        this.name = "BackendRouterHandledError";
+    }
+}
+export class BackendRouter {
+    db;
+    config;
+    notifier;
+    authTelemetry;
+    prepareSessionDir;
+    cores;
+    hasProcessConfigTable;
+    hasBackendDefaultsTable;
+    notificationDedup = new Map();
+    constructor(db, config, cores, notifier, authTelemetry, prepareSessionDir) {
+        this.db = db;
+        this.config = config;
+        this.notifier = notifier;
+        this.authTelemetry = authTelemetry;
+        this.prepareSessionDir = prepareSessionDir;
+        this.cores = Object.fromEntries(cores.map((core) => [core.backendId, core]));
+        this.hasProcessConfigTable = this.hasTable("process_backend_config");
+        this.hasBackendDefaultsTable = this.hasTable("backend_global_defaults");
+    }
+    async execute(params, streamCallbacks) {
+        const binding = params.preResolvedBinding ?? this.resolveBinding(params.event, {
+            processKey: params.processKey,
+            requestedTier: params.requestedTier,
+            ...(params.requestedBackendId ? { requestedBackendId: params.requestedBackendId } : {}),
+            ...(params.requestedModelId ? { requestedModelId: params.requestedModelId } : {}),
+        });
+        // Phase 3.3 — pre-flight auth cache check. When the main backend's
+        // cached auth status is recently confirmed bad, skip straight to the
+        // fallback to avoid a doomed subprocess. Only applies when a fallback
+        // is available; without one, we fall through to main and let it fail
+        // naturally (which triggers self-heal on the next successful execute).
+        if (binding.fallback) {
+            const preflight = readCachedAuthStatus(this.db, binding.main.backendId, this.config.authPreflightFreshnessMs);
+            if (preflight.shouldSkip) {
+                logger.warn({
+                    processKey: binding.processKey,
+                    backendId: binding.main.backendId,
+                    cachedStatus: preflight.status,
+                    fallbackBackendId: binding.fallback.backendId,
+                }, "Pre-flight auth check: main backend auth unavailable (cached), routing to fallback");
+                this.authTelemetry?.increment(binding.main.backendId, "preflight_skipped_main", "reactive");
+                return this.executePreflightFallback(binding, params, streamCallbacks);
+            }
+        }
+        const mainCore = this.requireCore(binding.main.backendId);
+        const mainWebSearch = this.isWebSearchEnabled(binding.main.backendId);
+        try {
+            const result = await mainCore.execute({
+                prompt: params.prompt,
+                context: params.context,
+                event: params.event,
+                modelId: binding.main.modelId,
+                maxTurns: binding.main.maxTurns,
+                maxBudgetUsd: binding.main.maxBudgetUsd,
+                sessionDir: params.sessionDir,
+                processKey: binding.processKey,
+                persistSession: params.persistSession,
+                conversationHistory: params.conversationHistory,
+                webSearchEnabled: mainWebSearch,
+                ...(params.sessionDbId !== undefined ? { sessionDbId: params.sessionDbId } : {}),
+                ...(params.turnToken ? { turnToken: params.turnToken } : {}),
+                ...(params.stagedAttachments && params.stagedAttachments.length > 0
+                    ? { stagedAttachments: params.stagedAttachments }
+                    : {}),
+                ...(params.allowedToolsOverride
+                    ? { allowedToolsOverride: params.allowedToolsOverride }
+                    : {}),
+            }, streamCallbacks);
+            // Reactive self-heal: a successful execute is authoritative proof the
+            // CLI held valid credentials. Bump auth_last_success_at (so the 60-day
+            // keepalive sweep tracks real usage) and clear any stale expired/missing
+            // cache row without waiting for the dashboard "Check auth" button.
+            recordReactiveAuthSuccess(this.db, binding.main.backendId, this.authTelemetry);
+            return result;
+        }
+        catch (error) {
+            // Reactive auth-health: persist the failure to the DB cache so
+            // pre-flight checks and `/auth status` reflect the real-time state.
+            if (error instanceof BackendDecisiveFailure && error.kind === "auth") {
+                recordReactiveAuthFailure(this.db, binding.main.backendId, error.cause instanceof Error ? error.cause.message : String(error.cause ?? ""), this.authTelemetry);
+            }
+            if (!binding.fallback ||
+                !(error instanceof BackendDecisiveFailure || error instanceof BackendQuotaError)) {
+                if (error instanceof BackendDecisiveFailure || error instanceof BackendQuotaError) {
+                    await this.handleNoFallbackFailure(params.event, binding.processKey, binding.main, error);
+                    throw new BackendRouterHandledError(`Backend "${binding.main.backendId}" failed without fallback: ${describeBackendFailure(error)}`, error, error);
+                }
+                throw error;
+            }
+            logger.warn({
+                processKey: binding.processKey,
+                backendId: binding.main.backendId,
+                failureKind: this.describeFailureKind(error),
+                fallbackBackendId: binding.fallback.backendId,
+            }, "Main backend failed decisively, attempting fallback");
+            return this.executeFallbackCore(binding, params, error, streamCallbacks);
+        }
+    }
+    async executeResume(params, streamCallbacks) {
+        const core = this.requireCore(params.backendId);
+        try {
+            const result = await core.executeResume({
+                sessionId: params.sessionId,
+                message: params.message,
+                modelId: params.modelId,
+                ...(params.maxTurns !== undefined ? { maxTurns: params.maxTurns } : {}),
+                ...(params.maxBudgetUsd !== undefined
+                    ? { maxBudgetUsd: params.maxBudgetUsd }
+                    : {}),
+                sessionDir: params.sessionDir,
+                webSearchEnabled: this.isWebSearchEnabled(params.backendId),
+                ...(params.sessionDbId !== undefined ? { sessionDbId: params.sessionDbId } : {}),
+                ...(params.turnToken ? { turnToken: params.turnToken } : {}),
+                ...(params.stagedAttachments && params.stagedAttachments.length > 0
+                    ? { stagedAttachments: params.stagedAttachments }
+                    : {}),
+                ...(params.eventCorrelationId
+                    ? { eventCorrelationId: params.eventCorrelationId }
+                    : {}),
+            }, streamCallbacks);
+            // executeResume also proves the backend holds valid credentials —
+            // keep `auth_last_success_at` in sync so DM sessions that run
+            // purely through session resumption don't false-trip the 60-day
+            // keepalive reminder.
+            recordReactiveAuthSuccess(this.db, params.backendId, this.authTelemetry);
+            return result;
+        }
+        catch (error) {
+            if (error instanceof BackendDecisiveFailure && error.kind === "auth") {
+                recordReactiveAuthFailure(this.db, params.backendId, error.cause instanceof Error ? error.cause.message : String(error.cause ?? ""), this.authTelemetry);
+            }
+            throw error;
+        }
+    }
+    async summarize(conversationText) {
+        const defaultBackendId = this.loadGlobalDefaults()?.default_backend ?? "claude";
+        const core = this.cores[defaultBackendId] ?? Object.values(this.cores)[0];
+        if (!core) {
+            throw new Error("No agent backends are registered");
+        }
+        const result = await core.summarize(conversationText);
+        // `summarize` is a successful backend invocation — the same reactive
+        // self-heal applies. Runs after the outer core is chosen (see
+        // loadGlobalDefaults fallback above), so stamp that backend.
+        recordReactiveAuthSuccess(this.db, core.backendId, this.authTelemetry);
+        return result;
+    }
+    /**
+     * Pre-flight entry point: creates a synthetic mainFailure for the
+     * skipped main backend and delegates to `executeFallbackCore`.
+     */
+    async executePreflightFallback(binding, params, streamCallbacks) {
+        const syntheticMainFailure = new BackendDecisiveFailure(binding.main.backendId, "auth", new Error("Pre-flight auth cache: main backend skipped"));
+        return this.executeFallbackCore(binding, params, syntheticMainFailure, streamCallbacks, { isPreflight: true });
+    }
+    /**
+     * Shared fallback execution — used by both the catch-block fallback
+     * (where `mainFailure` is the real execute error) and the pre-flight
+     * fallback (where `mainFailure` is a synthetic auth failure).
+     *
+     * Handles:
+     *   - fallback core execution with the same params shape
+     *   - reactive auth success/failure tracking on the fallback backend
+     *   - fallback success notification to admin
+     *   - fallback failure notification + BackendRouterHandledError throw
+     *
+     * Extracting this into a single method (design spec §5.2) ensures that
+     * a new side-effect (e.g. a new telemetry counter) only needs to be
+     * added once instead of in two diverging code paths.
+     */
+    async executeFallbackCore(binding, params, mainFailure, streamCallbacks, opts) {
+        const fallback = binding.fallback;
+        const fallbackCore = this.requireCore(fallback.backendId);
+        const fallbackWebSearch = this.isWebSearchEnabled(fallback.backendId);
+        // Ensure the session workdir has the fallback backend's instruction files.
+        // Heavy-tier session dirs are materialized once for the main backend; without
+        // this call, a Claude→Codex fallback would leave the dir with only CLAUDE.md
+        // and no AGENTS.md for Codex to read.
+        //
+        // Preflight path: there is no real main-backend failure to mask, so a
+        // throw here means the fallback would run in an unmaterialized workdir.
+        // Re-throw — the caller can fall back to the real execute path and surface
+        // a clearer diagnostic.
+        //
+        // Real-failure path: a throw here would mask the original main-backend
+        // failure with a re-materialization error and skip the fallback entirely.
+        // Log and continue: if the fallback core can't read its instructions the
+        // next `execute()` will surface a clearer diagnostic than ENOSPC.
+        if (params.sessionDir && this.prepareSessionDir) {
+            try {
+                this.prepareSessionDir(params.sessionDir, fallback.backendId, params.workdirEventType ?? params.event.type, params.workdirProcessKey ?? binding.processKey);
+            }
+            catch (err) {
+                if (opts?.isPreflight) {
+                    logger.error({
+                        err,
+                        sessionDir: params.sessionDir,
+                        fallbackBackendId: fallback.backendId,
+                        processKey: binding.processKey,
+                    }, "Pre-flight fallback session-dir re-materialization failed — aborting preflight");
+                    throw err;
+                }
+                logger.error({
+                    err,
+                    sessionDir: params.sessionDir,
+                    fallbackBackendId: fallback.backendId,
+                    processKey: binding.processKey,
+                }, "Fallback session-dir re-materialization failed — attempting fallback execute anyway");
+            }
+        }
+        // Re-apply backend-specific prompt overlays for the fallback backend
+        // when the caller supplied a reassembler. See RouterExecuteParams docs.
+        const fallbackPrompt = params.reassemblePrompt
+            ? params.reassemblePrompt(fallback.backendId)
+            : params.prompt;
+        try {
+            const result = await fallbackCore.execute({
+                prompt: fallbackPrompt,
+                context: params.context,
+                event: params.event,
+                modelId: fallback.modelId,
+                maxTurns: fallback.maxTurns,
+                maxBudgetUsd: fallback.maxBudgetUsd,
+                sessionDir: params.sessionDir,
+                processKey: binding.processKey,
+                persistSession: params.persistSession,
+                conversationHistory: params.conversationHistory,
+                webSearchEnabled: fallbackWebSearch,
+                ...(params.sessionDbId !== undefined ? { sessionDbId: params.sessionDbId } : {}),
+                ...(params.turnToken ? { turnToken: params.turnToken } : {}),
+                ...(params.stagedAttachments && params.stagedAttachments.length > 0
+                    ? { stagedAttachments: params.stagedAttachments }
+                    : {}),
+                ...(params.allowedToolsOverride
+                    ? { allowedToolsOverride: params.allowedToolsOverride }
+                    : {}),
+            }, streamCallbacks);
+            recordReactiveAuthSuccess(this.db, fallback.backendId, this.authTelemetry);
+            await this.notifyFallbackSuccess(params.event, binding.processKey, binding.main, mainFailure, fallback);
+            return result;
+        }
+        catch (fallbackError) {
+            if (fallbackError instanceof BackendDecisiveFailure
+                && fallbackError.kind === "auth") {
+                recordReactiveAuthFailure(this.db, fallback.backendId, fallbackError.cause instanceof Error
+                    ? fallbackError.cause.message
+                    : String(fallbackError.cause ?? ""), this.authTelemetry);
+            }
+            if (!(fallbackError instanceof BackendDecisiveFailure
+                || fallbackError instanceof BackendQuotaError)) {
+                throw fallbackError;
+            }
+            await this.handleFallbackFailure(params.event, binding.processKey, binding.main, mainFailure, fallback, fallbackError);
+            throw new BackendRouterHandledError(`Fallback backend "${fallback.backendId}" failed after "${binding.main.backendId}" — `
+                + `main: ${describeBackendFailure(mainFailure)}; `
+                + `fallback: ${describeBackendFailure(fallbackError)}`, fallbackError, mainFailure, fallbackError);
+        }
+    }
+    resolveBinding(event, options) {
+        const processKey = options?.processKey ?? resolveProcessKey(event);
+        // TIER_LOCKED hard clamp (DOCS_QA_B7_DESIGN.md S2). When set, this
+        // process is pinned to a tier regardless of requestedTier hints,
+        // process_backend_config rows, or global defaults. Folded into
+        // `effectiveRequestedTier` so the model-substitution branch below
+        // also fires, swapping any operator-pinned wrong-tier model to the
+        // canonical model at the locked tier.
+        const lockedTier = TIER_LOCKED_PROCESS_KEYS[processKey];
+        const effectiveRequestedTier = lockedTier ?? options?.requestedTier;
+        const requestedTier = effectiveRequestedTier;
+        const requestedBackendId = options?.requestedBackendId;
+        const requestedModelId = options?.requestedModelId;
+        const processConfig = this.loadProcessConfig(processKey);
+        // Explicit backend+model HARD override — dashboard chat model picker.
+        // Supersedes requestedTier and process_backend_config pins. Fallback is
+        // dropped: if the user explicitly picked a backend, silently rerouting
+        // to a different fallback would defeat the point of the picker. We
+        // still load maxTurns/maxBudget from process_backend_config so the
+        // user's per-process caps keep applying; otherwise fall back to the
+        // same defaults `resolveBinding` uses for unconfigured processes.
+        //
+        // Registered model → its registry tier becomes `resolvedTier`.
+        // Unregistered (custom) model → use the ProcessKey's default tier
+        // rather than hardcoding "high"; the override shouldn't mint a
+        // high-tier envelope for a medium-tier process just because the model
+        // id isn't in the registry.
+        if (requestedBackendId && requestedModelId) {
+            const overrideTier = this.tierFromModelId(requestedBackendId, requestedModelId) ??
+                this.resolveTier(processKey);
+            return {
+                processKey,
+                resolvedTier: overrideTier,
+                main: {
+                    backendId: requestedBackendId,
+                    modelId: requestedModelId,
+                    maxTurns: processConfig?.max_turns ??
+                        PROCESS_MAX_TURNS[processKey] ??
+                        (overrideTier === "high" ? 300 : overrideTier === "medium" ? 50 : 20),
+                    maxBudgetUsd: processConfig?.max_budget_usd ??
+                        (overrideTier === "high" ? 5.0 : overrideTier === "medium" ? 1.0 : 0.2),
+                },
+                fallback: null,
+            };
+        }
+        const resolvedTier = this.resolveTier(processKey, requestedTier);
+        if (processConfig) {
+            const main = this.resolveConfiguredBinding(processConfig.main_backend, processConfig.main_model, processConfig.max_turns, processConfig.max_budget_usd);
+            const fallback = processConfig.fallback_backend && processConfig.fallback_model
+                ? this.resolveConfiguredBinding(processConfig.fallback_backend, processConfig.fallback_model, processConfig.max_turns, processConfig.max_budget_usd)
+                : null;
+            // Explicit tier override — see RouterExecuteParams.requestedTier.
+            // Triggered when the caller passes an explicit requestedTier whose
+            // tier does NOT match the pinned model's registry tier. We swap the
+            // main model to a canonical choice for (backend, requestedTier).
+            // Without this branch, the explicit Opus escape hatches
+            // (agent_schedule.model, run-now requestedModel, dashboard chat
+            // picker's legacy sonnet/opus form) would be silently ignored after
+            // any Pro preset apply — every configurable process would be pinned
+            // to Sonnet and `main` would return that Sonnet regardless. The
+            // cross-backend superset override (requestedBackendId/requestedModelId)
+            // is handled earlier in this function and does not reach this
+            // branch.
+            //
+            // Invariants:
+            //   - If the pinned model's registry tier is unknown (user-supplied
+            //     custom model id), DO NOT override. The user explicitly chose a
+            //     non-standard model; clobbering it would be a silent regression.
+            //   - Fallback binding is preserved IFF its model's registry tier
+            //     also matches `requestedTier`. Otherwise drop it — routing back
+            //     to the wrong-tier fallback defeats the purpose of the override.
+            if (requestedTier) {
+                const overridden = this.maybeApplyTierOverride(main, requestedTier, processKey);
+                if (overridden) {
+                    const preservedFallback = this.preserveFallbackOnOverride(fallback, requestedTier);
+                    return {
+                        processKey,
+                        resolvedTier,
+                        main: overridden,
+                        fallback: this.refineFallbackForDelegation(processKey, preservedFallback),
+                    };
+                }
+            }
+            return {
+                processKey,
+                resolvedTier,
+                main,
+                fallback: this.refineFallbackForDelegation(processKey, fallback),
+            };
+        }
+        const defaults = this.loadGlobalDefaults();
+        const defaultBackendId = defaults?.default_backend ?? "claude";
+        const modelId = this.resolveDefaultModelId(defaultBackendId, resolvedTier, defaults);
+        return {
+            processKey,
+            resolvedTier,
+            main: {
+                backendId: defaultBackendId,
+                modelId,
+                maxTurns: PROCESS_MAX_TURNS[processKey] ??
+                    (resolvedTier === "high" ? 300 : resolvedTier === "medium" ? 50 : 20),
+                maxBudgetUsd: resolvedTier === "high" ? 5.0 : resolvedTier === "medium" ? 1.0 : 0.2,
+            },
+            fallback: null,
+        };
+    }
+    resolveConfiguredBinding(backendId, configuredModelId, configuredMaxTurns, configuredMaxBudgetUsd) {
+        return {
+            backendId,
+            modelId: configuredModelId,
+            maxTurns: configuredMaxTurns,
+            maxBudgetUsd: configuredMaxBudgetUsd,
+        };
+    }
+    /**
+     * Returns a modified binding whose `modelId` has been swapped to a canonical
+     * model for `requestedTier` on the same backend, or `null` when no override
+     * should be applied.
+     *
+     * Returns `null` (no override) in any of these cases:
+     *   1. The pinned model's registry tier is unknown (user-supplied custom
+     *      model id). This is **critical**: the user explicitly chose a
+     *      non-standard model, so we trust their choice over an
+     *      auto-substituted registry default. The previous implementation of
+     *      this method clobbered custom pins — that was a regression and is
+     *      covered by a dedicated test now.
+     *   2. The pinned model's tier already matches `requestedTier`.
+     *   3. No suitable canonical model exists for (backend, tier) in the
+     *      registry, or the canonical choice happens to be the already-pinned
+     *      model.
+     */
+    maybeApplyTierOverride(main, requestedTier, processKey) {
+        const pinnedTier = this.tierFromModelId(main.backendId, main.modelId);
+        if (pinnedTier === null) {
+            // Unknown tier → user-supplied custom model. Preserve it.
+            return null;
+        }
+        if (pinnedTier === requestedTier) {
+            return null;
+        }
+        const canonical = this.resolveCanonicalTierModel(main.backendId, requestedTier);
+        if (!canonical || canonical === main.modelId) {
+            return null;
+        }
+        logger.debug({
+            processKey,
+            pinnedModel: main.modelId,
+            pinnedTier,
+            requestedTier,
+            overrideModel: canonical,
+        }, "Explicit tier override — bypassing processConfig.main_model");
+        return { ...main, modelId: canonical };
+    }
+    /**
+     * Decide whether to keep the existing fallback binding when a tier override
+     * has been applied to the main binding. Returns the fallback unchanged when
+     * its model is registered at `requestedTier`; otherwise `null` so we don't
+     * silently route the override request into a wrong-tier fallback.
+     *
+     * Unregistered fallback model ids (custom) are preserved for the same
+     * reason as in `maybeApplyTierOverride`: trust user configuration.
+     */
+    preserveFallbackOnOverride(fallback, requestedTier) {
+        if (!fallback)
+            return null;
+        const fallbackTier = this.tierFromModelId(fallback.backendId, fallback.modelId);
+        if (fallbackTier === null || fallbackTier === requestedTier) {
+            return fallback;
+        }
+        return null;
+    }
+    /**
+     * Phase 4 — Integration-delegation gating.
+     *
+     * Null the fallback when the fallback backend has no registry connector
+     * for any delegated integration whose `taskFlowsTouched` declares this
+     * process key. Routing a delegated-integration process key into a
+     * connector-less backend would silently execute without the integration
+     * tools the task-flow variant expects.
+     *
+     * Main-backend incompatibility is intentionally NOT checked here —
+     * `PATCH /api/integrations/:key` and the setup wizard (§4.12.2 / §4.12.4)
+     * are the user-facing enforcement points. The router only refuses the
+     * fallback, which is the silent-rewire path the design spec calls out
+     * (§Phase 4, "Fallback refused when fallback backend lacks the connector
+     * required for any delegated integration the ProcessKey touches").
+     *
+     * Descriptor presence = contract: no live probe, no capabilityTools walk.
+     * Missing `backendConnectors[fallbackBackend]` → no connector → drop.
+     */
+    refineFallbackForDelegation(processKey, fallback) {
+        if (!fallback)
+            return null;
+        const integrations = readIntegrations(this.db);
+        const delegatedTouched = delegatedIntegrationsForProcessKey(processKey, integrations);
+        if (delegatedTouched.length === 0)
+            return fallback;
+        const blocking = delegatedTouched.filter((k) => !backendHasIntegrationConnector(k, fallback.backendId));
+        if (blocking.length === 0)
+            return fallback;
+        logger.warn({
+            processKey,
+            fallbackBackendId: fallback.backendId,
+            blockingIntegrations: blocking,
+        }, "Fallback backend lacks a connector for delegated integration(s) — dropping fallback");
+        return null;
+    }
+    tierFromModelId(backendId, modelId) {
+        return findRegisteredModel(backendId, modelId)?.tier ?? null;
+    }
+    /**
+     * Pick a canonical model for (backendId, tier) when the caller requests an
+     * explicit tier that the process_backend_config row does NOT satisfy.
+     *
+     * Priority:
+     *   1. Global default for that tier if (a) backend matches the default
+     *      backend AND (b) the configured default model is actually that tier
+     *      in the registry. The registered-tier guard prevents an
+     *      operator-customised default from leaking the wrong tier into the
+     *      router's resolution path.
+     *   2. First available model of (backendId, tier) in the model registry.
+     *   3. `null` — caller should keep the pinned model.
+     */
+    resolveCanonicalTierModel(backendId, tier) {
+        const defaults = this.loadGlobalDefaults();
+        if (defaults && defaults.default_backend === backendId) {
+            const candidate = tier === "high"
+                ? defaults.default_high_model
+                : tier === "medium"
+                    ? defaults.default_medium_model
+                    : defaults.default_lite_model;
+            const registered = findRegisteredModel(backendId, candidate);
+            if (registered?.tier === tier && registered.available) {
+                return candidate;
+            }
+        }
+        const match = getModelsForBackend(backendId).find((model) => model.tier === tier && model.available);
+        return match?.modelId ?? null;
+    }
+    resolveDefaultModelId(backendId, tier, defaults) {
+        if (defaults && backendId === defaults.default_backend) {
+            return tier === "high"
+                ? defaults.default_high_model
+                : tier === "medium"
+                    ? defaults.default_medium_model
+                    : defaults.default_lite_model;
+        }
+        if (backendId === "claude") {
+            return tier === "high"
+                ? DEFAULT_CLAUDE_HIGH_MODEL
+                : tier === "medium"
+                    ? DEFAULT_CLAUDE_MEDIUM_MODEL
+                    : DEFAULT_CLAUDE_LITE_MODEL;
+        }
+        const core = this.cores[backendId];
+        const models = core?.listModels() ?? [];
+        const exactTier = models.find((model) => model.tier === tier && model.available);
+        const fallback = models.find((model) => model.available) ?? models[0];
+        if (exactTier)
+            return exactTier.modelId;
+        if (fallback)
+            return fallback.modelId;
+        throw new BackendDecisiveFailure(backendId, "model_unavailable", new Error(`No registered model is available for backend "${backendId}"`));
+    }
+    resolveTier(processKey, requestedTier) {
+        // Hard lock — supersedes both `requestedTier` and any operator pin
+        // in `process_backend_config`. Keeps process keys like
+        // `dashboard.docs_qa` on the canonical medium tier even when the
+        // operator pinned the row to high in /settings/models (the
+        // tier-aware cascade leaves `updated_by='user'` rows alone). See
+        // TIER_LOCKED_PROCESS_KEYS for rationale.
+        const locked = TIER_LOCKED_PROCESS_KEYS[processKey];
+        if (locked) {
+            return locked;
+        }
+        if (requestedTier) {
+            return requestedTier;
+        }
+        if (isProcessKey(processKey)) {
+            return getDefaultTierForProcessKey(processKey);
+        }
+        // B-007 §5.8 — custom routines default to 'medium'. The scheduler
+        // normally emits an explicit `requestedModel` sourced from the
+        // routine file's `backend_tier` frontmatter, but if it ever arrives
+        // without one we default to medium rather than high so a
+        // misconfigured custom routine cannot silently drain the Opus quota.
+        if (isCustomRoutineKey(processKey)) {
+            return "medium";
+        }
+        // Truly unknown process keys keep the pre-B-007 behaviour of
+        // routing to a sufficient tier for unattended work — medium is the
+        // safer default than high (Opus) for unknown callers.
+        return "medium";
+    }
+    requireCore(backendId) {
+        const core = this.cores[backendId];
+        if (!core) {
+            throw new BackendDecisiveFailure(backendId, "model_unavailable", new Error(`Backend "${backendId}" is not registered`));
+        }
+        return core;
+    }
+    loadProcessConfig(processKey) {
+        if (!this.hasProcessConfigTable) {
+            return null;
+        }
+        return (this.db
+            .prepare(`SELECT
+             main_backend,
+             main_model,
+             fallback_backend,
+             fallback_model,
+             max_turns,
+             max_budget_usd
+           FROM process_backend_config
+           WHERE process_key = ?`)
+            .get(processKey) ?? null);
+    }
+    loadGlobalDefaults() {
+        if (!this.hasBackendDefaultsTable) {
+            return null;
+        }
+        return (this.db
+            .prepare(`SELECT
+             default_backend,
+             default_lite_model,
+             default_medium_model,
+             default_high_model
+           FROM backend_global_defaults
+           WHERE singleton = 1`)
+            .get() ?? null);
+    }
+    isWebSearchEnabled(backendId) {
+        try {
+            const row = this.db
+                .prepare("SELECT web_search_enabled FROM backends WHERE id = ?")
+                .get(backendId);
+            return row?.web_search_enabled === 1;
+        }
+        catch (err) {
+            // Defensive fallback: if the column or table is unexpectedly absent,
+            // treat web search as off rather than failing the binding lookup.
+            logger.debug({ err, backendId }, "web_search_enabled query failed, defaulting to false");
+            return false;
+        }
+    }
+    hasTable(name) {
+        const row = this.db
+            .prepare("SELECT 1 FROM sqlite_master WHERE type = 'table' AND name = ? LIMIT 1")
+            .get(name);
+        return !!row;
+    }
+    async handleNoFallbackFailure(event, processKey, main, failure) {
+        await this.maybeSendUserFacingFailure(event, processKey, failure);
+        await this.notifyConfiguredChannel(this.buildNoFallbackMessage(processKey, main, failure), event, `no-fallback:${processKey}:${main.backendId}:${this.describeFailureKind(failure)}`, "normal");
+    }
+    async handleFallbackFailure(event, processKey, main, mainFailure, fallback, fallbackFailure) {
+        await this.maybeSendUserFacingFailure(event, processKey, fallbackFailure);
+        await this.notifyConfiguredChannel(this.buildFallbackFailureMessage(processKey, main, mainFailure, fallback, fallbackFailure), event, null, "high");
+    }
+    async notifyFallbackSuccess(event, processKey, main, mainFailure, fallback) {
+        await this.notifyConfiguredChannel(this.buildFallbackSuccessMessage(processKey, main, mainFailure, fallback), event, `fallback-success:${processKey}:${main.backendId}:${fallback.backendId}`, "low");
+    }
+    async maybeSendUserFacingFailure(event, processKey, failure) {
+        if (!this.notifier || !this.isInteractiveProcess(processKey)) {
+            return;
+        }
+        await this.notifier.send(this.buildUserFacingFailureMessage(failure), event);
+    }
+    async notifyConfiguredChannel(message, event, dedupeKey, priority) {
+        if (!this.notifier) {
+            return;
+        }
+        if (dedupeKey && this.isNotificationDeduped(dedupeKey)) {
+            return;
+        }
+        await this.notifier.send(message, event, {
+            priority,
+            destinationMode: "configured_only",
+        });
+        if (dedupeKey) {
+            this.notificationDedup.set(dedupeKey, Date.now());
+        }
+    }
+    isNotificationDeduped(key) {
+        const lastSentAt = this.notificationDedup.get(key);
+        if (!lastSentAt) {
+            return false;
+        }
+        if (Date.now() - lastSentAt < NOTIFICATION_DEDUPE_WINDOW_MS) {
+            return true;
+        }
+        this.notificationDedup.delete(key);
+        return false;
+    }
+    isInteractiveProcess(processKey) {
+        return processKey === "message.dm"
+            || processKey === "message.mention"
+            || processKey === "dashboard.chat";
+    }
+    describeFailureKind(failure) {
+        if (failure instanceof BackendQuotaError) {
+            return "quota";
+        }
+        return failure.kind;
+    }
+    buildFallbackSuccessMessage(processKey, main, mainFailure, fallback) {
+        return [
+            `Backend switch: ${processKey} encountered `,
+            `${this.describeFailureKind(mainFailure)} on ${main.backendId}/${main.modelId}, `,
+            `fell back to ${fallback.backendId}/${fallback.modelId}.`,
+        ].join("");
+    }
+    buildNoFallbackMessage(processKey, main, failure) {
+        return [
+            `Backend execution failed: ${processKey} stopped due to `,
+            `${this.describeFailureKind(failure)} on ${main.backendId}/${main.modelId}. `,
+            "No fallback is configured.",
+        ].join("");
+    }
+    buildFallbackFailureMessage(processKey, main, mainFailure, fallback, fallbackFailure) {
+        return [
+            `Backend execution failed: ${processKey} encountered `,
+            `${this.describeFailureKind(mainFailure)} on ${main.backendId}/${main.modelId}, `,
+            `then ${this.describeFailureKind(fallbackFailure)} on ${fallback.backendId}/${fallback.modelId}.`,
+        ].join("");
+    }
+    buildUserFacingFailureMessage(failure) {
+        switch (this.describeFailureKind(failure)) {
+            case "quota":
+                if (this.isMaxBudgetFailure(failure)) {
+                    return "The per-turn budget limit was reached. Please try a shorter request or raise the budget in backend settings.";
+                }
+                return "This backend has reached its usage limit. Please try again later.";
+            case "auth":
+                return "Backend authentication failed. Please re-authorize from the dashboard.";
+            case "max_turns":
+                return "The processing turn limit has been reached. Please try a shorter request.";
+            case "timeout":
+                return "The backend timed out. Please try again later.";
+            case "model_unavailable":
+                return "The configured model is currently unavailable. Please select a different model in settings.";
+            default:
+                return "An error occurred during backend execution. Please try again.";
+        }
+    }
+    isMaxBudgetFailure(failure) {
+        return failure instanceof BackendQuotaError
+            && failure.originalCode === "max_budget_usd";
+    }
+}
+//# sourceMappingURL=backend-router.js.map