nemoris 0.1.0 → 0.1.2

package/src/runtime/provider-attempt.js

@@ -1,582 +1,582 @@
-import { downloadTelegramFile } from "./telegram-inbound.js";
-import { ModelRouter } from "../providers/router.js";
-import { assertProviderExecutionAllowed } from "./guards.js";
-import { compileOutputContractSchema } from "./output-contract-schema.js";
-import { estimateInvocationTokens } from "./token-estimator.js";
-import { TokenCounter } from "./token-counter.js";
-import { classifyRuntimeFailure, getReportFallbackPolicy, resolveReportFallback } from "./report-fallback.js";
-import { extractUsageMetrics } from "../utils/usage-metrics.js";
-
-export function modelToProviderId(modelId) {
-  return String(modelId || "").split("/")[0] || null;
-}
-
-export function isRetryableError(err) {
-  const message = (err.message || "").toLowerCase();
-  const statusCode = err.statusCode || err.status || 0;
-
-  if (
-    message.includes("econnrefused") ||
-    message.includes("etimedout") ||
-    message.includes("fetch failed") ||
-    message.includes("net_error") ||
-    message.includes("timeout") ||
-    message.includes("enotfound") ||
-    message.includes("eai_again")
-  ) {
-    return true;
-  }
-
-  if (statusCode === 429 || (statusCode >= 500 && statusCode < 600)) {
-    return true;
-  }
-
-  return false;
-}
-
-export function computeProviderTimeoutMs(plan, providerConfig, options = {}) {
-  if (options.providerTimeoutMs != null) {
-    return Number(options.providerTimeoutMs);
-  }
-
-  const defaultTimeoutMs = Number(providerConfig?.defaultTimeoutMs || 0);
-  const budgetSeconds = Number(plan?.job?.budget?.maxRuntimeSeconds || 0);
-  const budgetTimeoutMs = budgetSeconds ? Math.min((budgetSeconds + 5) * 1000, 60000) : 0;
-  return Math.max(defaultTimeoutMs, budgetTimeoutMs || 0);
-}
-
-export function buildRoutingDecision(plan, options = {}) {
-  const routeMode = options.routeMode || plan.routing?.routeMode || "primary";
-  const selectedLane = options.laneOverride || plan.routing?.selectedLane || plan.job.modelLane;
-  return {
-    requestedLane: plan.job.modelLane,
-    selectedLane,
-    routeMode,
-    matchedRule: plan.routing?.matchedRule || null,
-    reasons: plan.routing?.reasons || [],
-    modelOverride: options.modelOverride || null
-  };
-}
-
-export function getLocalPromptContractOutputCap(plan, { providerId, providerCapabilities, routingDecision }) {
-  if (providerId !== "ollama") return null;
-  if (providerCapabilities?.structuredOutputMode !== "prompt_contract") return null;
-
-  const format = plan?.packet?.layers?.outputContract?.format || null;
-  if (format === "bulleted_briefing") return 1500;
-  if (format === "structured_rollup") return 2000;
-
-  if (routingDecision?.selectedLane === "local_cheap") return 400;
-  if (routingDecision?.selectedLane === "local_report") return 1200;
-  return null;
-}
-
-export async function prepareProviderAttempt({
-  plan,
-  runtimeConfig,
-  registry,
-  tokenCounter,
-  modelId,
-  providerConfig,
-  providerId,
-  routingDecision,
-  providerTimeoutMs,
-  toolSchemas,
-  buildSystemPrompt,
-  buildUserMessage
-}) {
-  if (!providerConfig) {
-    throw new Error(`No provider config for model ${modelId}`);
-  }
-  const adapter = registry.create(providerConfig);
-  const providerCapabilities = adapter?.getCapabilities?.() || null;
-  const nativeStructuredOutput = Boolean(
-    adapter &&
-      plan.packet.layers.outputContract &&
-      typeof adapter.supportsNativeStructuredOutput === "function" &&
-      adapter.supportsNativeStructuredOutput()
-  );
-  const responseSchema = nativeStructuredOutput
-    ? compileOutputContractSchema(plan.packet.layers.outputContract, {
-        thoughtFirst: providerCapabilities?.supportsReasoningSchema === true
-      })
-    : null;
-
-  const localPromptContractCap = getLocalPromptContractOutputCap(plan, {
-    providerId,
-    providerCapabilities,
-    routingDecision
-  });
-  const effectiveMaxTokens = localPromptContractCap
-    ? Math.min(Number(plan.job.budget.maxTokens || 0) || 0, localPromptContractCap)
-    : plan.job.budget.maxTokens;
-
-  const invocation = {
-    model: modelId,
-    system: buildSystemPrompt(plan, {
-      nativeStructuredOutput,
-      responseSchema,
-      toolSchemas
-    }),
-    messages: [
-      {
-        role: "user",
-        content: buildUserMessage(plan, {
-          nativeStructuredOutput,
-          responseSchema
-        })
-      }
-    ],
-    maxTokens: effectiveMaxTokens,
-    responseSchema,
-    timeoutMs: providerTimeoutMs,
-    tools: toolSchemas?.length ? toolSchemas : undefined,
-    options:
-      providerId === "ollama"
-        ? {
-            num_predict: effectiveMaxTokens
-          }
-        : undefined
-  };
-
-  const thinkMode = plan?.packet?.thinkMode;
-  if (
-    thinkMode && thinkMode !== "off" &&
-    providerId === "anthropic" &&
-    process.env.ANTHROPIC_THINKING_ENABLED === "true"
-  ) {
-    const THINK_BUDGETS = { low: 1000, medium: 8000, high: 16000 };
-    const budget = THINK_BUDGETS[thinkMode] || 8000;
-    invocation.betas = [...(invocation.betas || []), "interleaved-thinking-2025-05-14"];
-    invocation.thinking = { type: "enabled", budget_tokens: budget };
-  }
-
-  const preflight = await buildPreflight(runtimeConfig, invocation, {
-    providerId,
-    adapter,
-    tokenCounter
-  });
-
-  if (preflight.pressure === "hard") {
-    throw new Error(
-      `Preflight blocked ${plan.job.id}: estimated prompt tokens ${preflight.estimatedPromptTokens} exceed hard limit ${preflight.hardLimit}`
-    );
-  }
-
-  return {
-    adapter,
-    providerCapabilities,
-    invocation,
-    preflight
-  };
-}
-
-export async function buildPreflight(runtimeConfig, invocation, options = {}) {
-  const contextTokens = runtimeConfig?.safety?.contextTokens ?? 32768;
-  const softRatio = runtimeConfig?.safety?.contextPressureSoftRatio ?? 0.72;
-  const hardRatio = runtimeConfig?.safety?.contextPressureHardRatio ?? 0.9;
-  const freshSessionOnHighPressure = runtimeConfig?.safety?.freshSessionOnHighPressure ?? true;
-  const snapshotBeforeCompaction = runtimeConfig?.safety?.snapshotBeforeCompaction ?? true;
-  const tokenCounter = options.tokenCounter || new TokenCounter();
-  const tokenEstimate = await tokenCounter.countInvocation({
-    providerId: options.providerId,
-    invocation,
-    adapter: options.adapter
-  });
-  const heuristicEstimate = tokenEstimate.mode === "heuristic" ? tokenEstimate.details : estimateInvocationTokens(invocation);
-  const estimatedPromptTokens = tokenEstimate.total;
-  const softLimit = Math.floor(contextTokens * softRatio);
-  const hardLimit = Math.floor(contextTokens * hardRatio);
-
-  let pressure = "low";
-  if (estimatedPromptTokens >= hardLimit) pressure = "hard";
-  else if (estimatedPromptTokens >= softLimit) pressure = "high";
-
-  return {
-    contextTokens,
-    estimatedPromptTokens,
-    tokenEstimate,
-    heuristicEstimate,
-    softLimit,
-    hardLimit,
-    pressure,
-    freshSessionRequired: pressure !== "low" && freshSessionOnHighPressure,
-    snapshotBeforeCompaction
-  };
-}
-
-async function attachVisionInputs(plan, runtimeConfig, invocation, providerCapabilities) {
-  if (!plan.packet?.imageRefs?.length || !invocation) {
-    return invocation;
-  }
-
-  if (providerCapabilities?.supportsVision) {
-    const tgConfig = runtimeConfig?.telegram;
-    const botToken = tgConfig?.botTokenEnv ? process.env[tgConfig.botTokenEnv] : null;
-    if (!botToken) {
-      console.warn(`[executor] imageRefs present but botToken not resolved from ${tgConfig?.botTokenEnv || "undefined env key"}`);
-      return invocation;
-    }
-
-    const imageBlocks = [];
-    for (const ref of plan.packet.imageRefs) {
-      const downloaded = await downloadTelegramFile(ref.fileId, botToken);
-      if (downloaded) {
-        imageBlocks.push({
-          type: "image",
-          source: {
-            type: "base64",
-            media_type: downloaded.mediaType,
-            data: downloaded.base64,
-          },
-        });
-      }
-    }
-
-    if (imageBlocks.length > 0) {
-      const userIdx = invocation.messages.findLastIndex((message) => message.role === "user");
-      if (userIdx !== -1) {
-        const textContent = invocation.messages[userIdx].content;
-        invocation.messages[userIdx].content = [
-          ...imageBlocks,
-          { type: "text", text: textContent },
-        ];
-      }
-    }
-    return invocation;
-  }
-
-  const visionNote = "[Image received but this model doesn't support vision]";
-  const userIdx = invocation.messages.findLastIndex((message) => message.role === "user");
-  if (userIdx !== -1) {
-    const existing = invocation.messages[userIdx].content;
-    invocation.messages[userIdx].content = existing
-      ? `${existing}\n\n${visionNote}`
-      : visionNote;
-  }
-  return invocation;
-}
-
-function annotateAttemptError(error, metadata = {}) {
-  if (!error || typeof error !== "object") {
-    return error;
-  }
-
-  Object.assign(error, metadata);
-  return error;
-}
-
-async function executeProviderCall({
-  plan,
-  runtime,
-  mode,
-  registry,
-  tokenCounter,
-  modelId,
-  providerId,
-  providerConfig,
-  routingDecision,
-  providerTimeoutMs,
-  toolSchemas,
-  buildSystemPrompt,
-  buildUserMessage,
-  onPrepared
-}) {
-  let prepared = null;
-  let invocation = null;
-
-  try {
-    prepared = await prepareProviderAttempt({
-      plan,
-      runtimeConfig: runtime.runtime,
-      registry,
-      tokenCounter,
-      modelId,
-      providerConfig,
-      providerId,
-      routingDecision,
-      providerTimeoutMs,
-      toolSchemas,
-      buildSystemPrompt,
-      buildUserMessage
-    });
-
-    if (typeof onPrepared === "function") {
-      onPrepared(prepared);
-    }
-
-    invocation = await attachVisionInputs(
-      plan,
-      runtime.runtime,
-      prepared.invocation,
-      prepared.providerCapabilities
-    );
-
-    if (mode === "dry-run") {
-      return {
-        response: null,
-        providerId,
-        modelId,
-        usage: {
-          tokensIn: 0,
-          tokensOut: 0,
-          cacheIn: 0,
-          cacheCreation: 0,
-        },
-        cached: false,
-        adapter: prepared.adapter,
-        providerCapabilities: prepared.providerCapabilities,
-        invocation,
-        preflight: prepared.preflight,
-        providerModePolicy: null,
-        health: null,
-        toolLoopEnabled: false
-      };
-    }
-
-    const providerModePolicy = assertProviderExecutionAllowed({
-      jobId: plan.job.id,
-      modelLane: routingDecision.selectedLane,
-      providerId,
-      interactive: plan.job.trigger === "interactive"
-    });
-
-    let health = null;
-    if (providerModePolicy.requireHealthyProvider) {
-      const healthCheck = await prepared.adapter.healthCheck();
-      if (!healthCheck.ok) {
-        throw new Error(`Provider health check failed for ${providerId} with status ${healthCheck.status}`);
-      }
-      health = healthCheck;
-    }
-
-    const response = await prepared.adapter.invoke(invocation);
-    const usage = extractUsageMetrics(response);
-
-    return {
-      response,
-      providerId,
-      modelId,
-      usage,
-      cached: Boolean(usage.cacheIn || usage.cacheCreation),
-      adapter: prepared.adapter,
-      providerCapabilities: prepared.providerCapabilities,
-      invocation,
-      preflight: prepared.preflight,
-      providerModePolicy,
-      health,
-      toolLoopEnabled: true
-    };
-  } catch (error) {
-    throw annotateAttemptError(error, {
-      providerId,
-      modelId,
-      routingDecision,
-      providerCapabilities: prepared?.providerCapabilities || null,
-      invocation: invocation || prepared?.invocation || null,
-      preflight: prepared?.preflight || null
-    });
-  }
-}
-
-function buildFallbackState(runtimeConfig, routingDecision, providerId, modelId, options) {
-  return {
-    allowed: false,
-    attempted: false,
-    trigger: null,
-    finalSourceLane: routingDecision.selectedLane,
-    sourceLane: routingDecision.selectedLane,
-    sourceProviderId: providerId,
-    sourceModelId: modelId,
-    policy: getReportFallbackPolicy(runtimeConfig, options)
-  };
-}
-
-export async function attemptProvider({ plan, runtime, options = {} }) {
-  const mode = options.mode || "dry-run";
-  const router = options.router || new ModelRouter(runtime.router);
-  const routingDecision = buildRoutingDecision(plan, options);
-  const laneConfig = runtime.router?.[routingDecision.selectedLane];
-  const primaryModelId = options.modelOverride || plan.packet.modelOverride || router.resolve(routingDecision.selectedLane, routingDecision.routeMode);
-  const providersToTry = [primaryModelId, ...(laneConfig?.fallbackModels || [])];
-  const toolSchemas = options.toolSchemas || [];
-  const registry = options.registry;
-  const tokenCounter = options.tokenCounter;
-  const buildSystemPrompt = options.buildSystemPrompt;
-  const buildUserMessage = options.buildUserMessage;
-
-  let fallback = null;
-  let primaryError = null;
-  let lastProviderId = null;
-
-  for (const currentModelId of providersToTry) {
-    const currentProviderId = modelToProviderId(currentModelId);
-    const providerConfig = runtime.providers[currentProviderId];
-    const providerTimeoutMs = computeProviderTimeoutMs(plan, providerConfig, options);
-    const breaker = options.getBreaker?.(currentModelId, runtime.runtime) || null;
-    lastProviderId = currentProviderId;
-
-    if (breaker?.isOpen()) {
-      const retryAfter = breaker.retryAfter();
-      console.warn(`[Nemoris] circuit breaker open for ${currentModelId}, skipping (retry in ${Math.ceil(retryAfter)}s)`);
-      primaryError = new Error(`Provider ${currentModelId} circuit open — retry after ${Math.ceil(retryAfter)}s`);
-      annotateAttemptError(primaryError, {
-        providerId: currentProviderId,
-        modelId: currentModelId,
-        routingDecision,
-        fallback
-      });
-      continue;
-    }
-
-    try {
-      const attempt = await executeProviderCall({
-        plan,
-        runtime,
-        mode,
-        registry,
-        tokenCounter,
-        modelId: currentModelId,
-        providerId: currentProviderId,
-        providerConfig,
-        routingDecision,
-        providerTimeoutMs,
-        toolSchemas,
-        buildSystemPrompt,
-        buildUserMessage,
-        onPrepared: () => {
-          if (!fallback) {
-            fallback = buildFallbackState(runtime.runtime, routingDecision, currentProviderId, currentModelId, options);
-          }
-        }
-      });
-
-      if (mode === "provider") {
-        breaker?.recordSuccess();
-      }
-
-      return {
-        ...attempt,
-        routingDecision,
-        fallback,
-        primaryModelId
-      };
-    } catch (err) {
-      primaryError = annotateAttemptError(err, {
-        providerId: currentProviderId,
-        modelId: currentModelId,
-        routingDecision,
-        fallback
-      });
-      const statusCode = err.statusCode || err.status || 0;
-      breaker?.recordFailure(statusCode);
-
-      if (isRetryableError(err)) {
-        console.warn(`[executor] provider ${currentModelId} failed: ${err.message}, trying next`);
-        continue;
-      }
-      break;
-    }
-  }
-
-  if (!primaryError) {
-    primaryError = new Error("All providers in failover chain exhausted");
-    annotateAttemptError(primaryError, {
-      routingDecision,
-      fallback
-    });
-  }
-
-  const failureClass = classifyRuntimeFailure(primaryError?.message || "");
-  const fallbackResolution = resolveReportFallback({
-    runtimeConfig: runtime.runtime,
-    job: plan.job,
-    routingDecision,
-    providerId: lastProviderId,
-    failureClass,
-    options
-  });
-
-  fallback = {
-    ...(fallback || {}),
-    allowed: fallbackResolution.allowed,
-    attempted: false,
-    trigger: failureClass,
-    localFailureClass: failureClass,
-    localError: primaryError.message,
-    blockedReason: fallbackResolution.allowed ? null : fallbackResolution.reason,
-    targetLane: fallbackResolution.targetLane || null
-  };
-
-  if (!fallbackResolution.allowed) {
-    annotateAttemptError(primaryError, {
-      providerId: primaryError.providerId || lastProviderId,
-      routingDecision,
-      fallback
-    });
-    throw primaryError;
-  }
-
-  fallback.attempted = true;
-  const fallbackRoutingDecision = {
-    ...routingDecision,
-    selectedLane: fallbackResolution.targetLane,
-    routeMode: "fallback",
-    reasons: [...(routingDecision.reasons || []), `fallback:${failureClass}`],
-    description: "Failure-triggered report fallback."
-  };
-  const fallbackModelId = router.resolve(fallbackResolution.targetLane, "primary");
-  const fallbackProviderId = modelToProviderId(fallbackModelId);
-  const fallbackProviderConfig = runtime.providers[fallbackProviderId];
-
-  try {
-    const attempt = await executeProviderCall({
-      plan,
-      runtime,
-      mode,
-      registry,
-      tokenCounter,
-      modelId: fallbackModelId,
-      providerId: fallbackProviderId,
-      providerConfig: fallbackProviderConfig,
-      routingDecision: fallbackRoutingDecision,
-      providerTimeoutMs: computeProviderTimeoutMs(plan, fallbackProviderConfig, options),
-      toolSchemas,
-      buildSystemPrompt,
-      buildUserMessage
-    });
-
-    return {
-      ...attempt,
-      routingDecision: fallbackRoutingDecision,
-      fallback: {
-        ...fallback,
-        success: true,
-        finalSourceLane: fallbackRoutingDecision.selectedLane,
-        finalProviderId: fallbackProviderId,
-        finalModelId: fallbackModelId
-      },
-      toolLoopEnabled: mode === "provider" && Boolean(options.allowToolLoopOnFallback)
-    };
-  } catch (fallbackError) {
-    fallback = {
-      ...fallback,
-      success: false,
-      fallbackFailureClass: classifyRuntimeFailure(fallbackError?.message || ""),
-      fallbackError: fallbackError.message
-    };
-    const combinedError = new Error(
-      `Primary provider failed (${failureClass}) and fallback failed: ${fallbackError.message}`
-    );
-    annotateAttemptError(combinedError, {
-      providerId: fallbackProviderId,
-      modelId: fallbackModelId,
-      routingDecision: fallbackRoutingDecision,
-      providerCapabilities: fallbackError?.providerCapabilities || null,
-      invocation: fallbackError?.invocation || null,
-      preflight: fallbackError?.preflight || null,
-      fallback
-    });
-    throw combinedError;
-  }
-}
+import { downloadTelegramFile } from "./telegram-inbound.js";
+import { ModelRouter } from "../providers/router.js";
+import { assertProviderExecutionAllowed } from "./guards.js";
+import { compileOutputContractSchema } from "./output-contract-schema.js";
+import { estimateInvocationTokens } from "./token-estimator.js";
+import { TokenCounter } from "./token-counter.js";
+import { classifyRuntimeFailure, getReportFallbackPolicy, resolveReportFallback } from "./report-fallback.js";
+import { extractUsageMetrics } from "../utils/usage-metrics.js";
+
+export function modelToProviderId(modelId) {
+  return String(modelId || "").split("/")[0] || null;
+}
+
+export function isRetryableError(err) {
+  const message = (err.message || "").toLowerCase();
+  const statusCode = err.statusCode || err.status || 0;
+
+  if (
+    message.includes("econnrefused") ||
+    message.includes("etimedout") ||
+    message.includes("fetch failed") ||
+    message.includes("net_error") ||
+    message.includes("timeout") ||
+    message.includes("enotfound") ||
+    message.includes("eai_again")
+  ) {
+    return true;
+  }
+
+  if (statusCode === 429 || (statusCode >= 500 && statusCode < 600)) {
+    return true;
+  }
+
+  return false;
+}
+
+export function computeProviderTimeoutMs(plan, providerConfig, options = {}) {
+  if (options.providerTimeoutMs != null) {
+    return Number(options.providerTimeoutMs);
+  }
+
+  const defaultTimeoutMs = Number(providerConfig?.defaultTimeoutMs || 0);
+  const budgetSeconds = Number(plan?.job?.budget?.maxRuntimeSeconds || 0);
+  const budgetTimeoutMs = budgetSeconds ? Math.min((budgetSeconds + 5) * 1000, 60000) : 0;
+  return Math.max(defaultTimeoutMs, budgetTimeoutMs || 0);
+}
+
+export function buildRoutingDecision(plan, options = {}) {
+  const routeMode = options.routeMode || plan.routing?.routeMode || "primary";
+  const selectedLane = options.laneOverride || plan.routing?.selectedLane || plan.job.modelLane;
+  return {
+    requestedLane: plan.job.modelLane,
+    selectedLane,
+    routeMode,
+    matchedRule: plan.routing?.matchedRule || null,
+    reasons: plan.routing?.reasons || [],
+    modelOverride: options.modelOverride || null
+  };
+}
+
+export function getLocalPromptContractOutputCap(plan, { providerId, providerCapabilities, routingDecision }) {
+  if (providerId !== "ollama") return null;
+  if (providerCapabilities?.structuredOutputMode !== "prompt_contract") return null;
+
+  const format = plan?.packet?.layers?.outputContract?.format || null;
+  if (format === "bulleted_briefing") return 1500;
+  if (format === "structured_rollup") return 2000;
+
+  if (routingDecision?.selectedLane === "local_cheap") return 400;
+  if (routingDecision?.selectedLane === "local_report") return 1200;
+  return null;
+}
+
+export async function prepareProviderAttempt({
+  plan,
+  runtimeConfig,
+  registry,
+  tokenCounter,
+  modelId,
+  providerConfig,
+  providerId,
+  routingDecision,
+  providerTimeoutMs,
+  toolSchemas,
+  buildSystemPrompt,
+  buildUserMessage
+}) {
+  if (!providerConfig) {
+    throw new Error(`No provider config for model ${modelId}`);
+  }
+  const adapter = registry.create(providerConfig);
+  const providerCapabilities = adapter?.getCapabilities?.() || null;
+  const nativeStructuredOutput = Boolean(
+    adapter &&
+      plan.packet.layers.outputContract &&
+      typeof adapter.supportsNativeStructuredOutput === "function" &&
+      adapter.supportsNativeStructuredOutput()
+  );
+  const responseSchema = nativeStructuredOutput
+    ? compileOutputContractSchema(plan.packet.layers.outputContract, {
+        thoughtFirst: providerCapabilities?.supportsReasoningSchema === true
+      })
+    : null;
+
+  const localPromptContractCap = getLocalPromptContractOutputCap(plan, {
+    providerId,
+    providerCapabilities,
+    routingDecision
+  });
+  const effectiveMaxTokens = localPromptContractCap
+    ? Math.min(Number(plan.job.budget.maxTokens || 0) || 0, localPromptContractCap)
+    : plan.job.budget.maxTokens;
+
+  const invocation = {
+    model: modelId,
+    system: buildSystemPrompt(plan, {
+      nativeStructuredOutput,
+      responseSchema,
+      toolSchemas
+    }),
+    messages: [
+      {
+        role: "user",
+        content: buildUserMessage(plan, {
+          nativeStructuredOutput,
+          responseSchema
+        })
+      }
+    ],
+    maxTokens: effectiveMaxTokens,
+    responseSchema,
+    timeoutMs: providerTimeoutMs,
+    tools: toolSchemas?.length ? toolSchemas : undefined,
+    options:
+      providerId === "ollama"
+        ? {
+            num_predict: effectiveMaxTokens
+          }
+        : undefined
+  };
+
+  const thinkMode = plan?.packet?.thinkMode;
+  if (
+    thinkMode && thinkMode !== "off" &&
+    providerId === "anthropic" &&
+    process.env.ANTHROPIC_THINKING_ENABLED === "true"
+  ) {
+    const THINK_BUDGETS = { low: 1000, medium: 8000, high: 16000 };
+    const budget = THINK_BUDGETS[thinkMode] || 8000;
+    invocation.betas = [...(invocation.betas || []), "interleaved-thinking-2025-05-14"];
+    invocation.thinking = { type: "enabled", budget_tokens: budget };
+  }
+
+  const preflight = await buildPreflight(runtimeConfig, invocation, {
+    providerId,
+    adapter,
+    tokenCounter
+  });
+
+  if (preflight.pressure === "hard") {
+    throw new Error(
+      `Preflight blocked ${plan.job.id}: estimated prompt tokens ${preflight.estimatedPromptTokens} exceed hard limit ${preflight.hardLimit}`
+    );
+  }
+
+  return {
+    adapter,
+    providerCapabilities,
+    invocation,
+    preflight
+  };
+}
+
+export async function buildPreflight(runtimeConfig, invocation, options = {}) {
+  const contextTokens = runtimeConfig?.safety?.contextTokens ?? 32768;
+  const softRatio = runtimeConfig?.safety?.contextPressureSoftRatio ?? 0.72;
+  const hardRatio = runtimeConfig?.safety?.contextPressureHardRatio ?? 0.9;
+  const freshSessionOnHighPressure = runtimeConfig?.safety?.freshSessionOnHighPressure ?? true;
+  const snapshotBeforeCompaction = runtimeConfig?.safety?.snapshotBeforeCompaction ?? true;
+  const tokenCounter = options.tokenCounter || new TokenCounter();
+  const tokenEstimate = await tokenCounter.countInvocation({
+    providerId: options.providerId,
+    invocation,
+    adapter: options.adapter
+  });
+  const heuristicEstimate = tokenEstimate.mode === "heuristic" ? tokenEstimate.details : estimateInvocationTokens(invocation);
+  const estimatedPromptTokens = tokenEstimate.total;
+  const softLimit = Math.floor(contextTokens * softRatio);
+  const hardLimit = Math.floor(contextTokens * hardRatio);
+
+  let pressure = "low";
+  if (estimatedPromptTokens >= hardLimit) pressure = "hard";
+  else if (estimatedPromptTokens >= softLimit) pressure = "high";
+
+  return {
+    contextTokens,
+    estimatedPromptTokens,
+    tokenEstimate,
+    heuristicEstimate,
+    softLimit,
+    hardLimit,
+    pressure,
+    freshSessionRequired: pressure !== "low" && freshSessionOnHighPressure,
+    snapshotBeforeCompaction
+  };
+}
+
+async function attachVisionInputs(plan, runtimeConfig, invocation, providerCapabilities) {
+  if (!plan.packet?.imageRefs?.length || !invocation) {
+    return invocation;
+  }
+
+  if (providerCapabilities?.supportsVision) {
+    const tgConfig = runtimeConfig?.telegram;
+    const botToken = tgConfig?.botTokenEnv ? process.env[tgConfig.botTokenEnv] : null;
+    if (!botToken) {
+      console.warn(`[executor] imageRefs present but botToken not resolved from ${tgConfig?.botTokenEnv || "undefined env key"}`);
+      return invocation;
+    }
+
+    const imageBlocks = [];
+    for (const ref of plan.packet.imageRefs) {
+      const downloaded = await downloadTelegramFile(ref.fileId, botToken);
+      if (downloaded) {
+        imageBlocks.push({
+          type: "image",
+          source: {
+            type: "base64",
+            media_type: downloaded.mediaType,
+            data: downloaded.base64,
+          },
+        });
+      }
+    }
+
+    if (imageBlocks.length > 0) {
+      const userIdx = invocation.messages.findLastIndex((message) => message.role === "user");
+      if (userIdx !== -1) {
+        const textContent = invocation.messages[userIdx].content;
+        invocation.messages[userIdx].content = [
+          ...imageBlocks,
+          { type: "text", text: textContent },
+        ];
+      }
+    }
+    return invocation;
+  }
+
+  const visionNote = "[Image received but this model doesn't support vision]";
+  const userIdx = invocation.messages.findLastIndex((message) => message.role === "user");
+  if (userIdx !== -1) {
+    const existing = invocation.messages[userIdx].content;
+    invocation.messages[userIdx].content = existing
+      ? `${existing}\n\n${visionNote}`
+      : visionNote;
+  }
+  return invocation;
+}
+
+function annotateAttemptError(error, metadata = {}) {
+  if (!error || typeof error !== "object") {
+    return error;
+  }
+
+  Object.assign(error, metadata);
+  return error;
+}
+
+async function executeProviderCall({
+  plan,
+  runtime,
+  mode,
+  registry,
+  tokenCounter,
+  modelId,
+  providerId,
+  providerConfig,
+  routingDecision,
+  providerTimeoutMs,
+  toolSchemas,
+  buildSystemPrompt,
+  buildUserMessage,
+  onPrepared
+}) {
+  let prepared = null;
+  let invocation = null;
+
+  try {
+    prepared = await prepareProviderAttempt({
+      plan,
+      runtimeConfig: runtime.runtime,
+      registry,
+      tokenCounter,
+      modelId,
+      providerConfig,
+      providerId,
+      routingDecision,
+      providerTimeoutMs,
+      toolSchemas,
+      buildSystemPrompt,
+      buildUserMessage
+    });
+
+    if (typeof onPrepared === "function") {
+      onPrepared(prepared);
+    }
+
+    invocation = await attachVisionInputs(
+      plan,
+      runtime.runtime,
+      prepared.invocation,
+      prepared.providerCapabilities
+    );
+
+    if (mode === "dry-run") {
+      return {
+        response: null,
+        providerId,
+        modelId,
+        usage: {
+          tokensIn: 0,
+          tokensOut: 0,
+          cacheIn: 0,
+          cacheCreation: 0,
+        },
+        cached: false,
+        adapter: prepared.adapter,
+        providerCapabilities: prepared.providerCapabilities,
+        invocation,
+        preflight: prepared.preflight,
+        providerModePolicy: null,
+        health: null,
+        toolLoopEnabled: false
+      };
+    }
+
+    const providerModePolicy = assertProviderExecutionAllowed({
+      jobId: plan.job.id,
+      modelLane: routingDecision.selectedLane,
+      providerId,
+      interactive: plan.job.trigger === "interactive"
+    });
+
+    let health = null;
+    if (providerModePolicy.requireHealthyProvider) {
+      const healthCheck = await prepared.adapter.healthCheck();
+      if (!healthCheck.ok) {
+        throw new Error(`Provider health check failed for ${providerId} with status ${healthCheck.status}`);
+      }
+      health = healthCheck;
+    }
+
+    const response = await prepared.adapter.invoke(invocation);
+    const usage = extractUsageMetrics(response);
+
+    return {
+      response,
+      providerId,
+      modelId,
+      usage,
+      cached: Boolean(usage.cacheIn || usage.cacheCreation),
+      adapter: prepared.adapter,
+      providerCapabilities: prepared.providerCapabilities,
+      invocation,
+      preflight: prepared.preflight,
+      providerModePolicy,
+      health,
+      toolLoopEnabled: true
+    };
+  } catch (error) {
+    throw annotateAttemptError(error, {
+      providerId,
+      modelId,
+      routingDecision,
+      providerCapabilities: prepared?.providerCapabilities || null,
+      invocation: invocation || prepared?.invocation || null,
+      preflight: prepared?.preflight || null
+    });
+  }
+}
+
+function buildFallbackState(runtimeConfig, routingDecision, providerId, modelId, options) {
+  return {
+    allowed: false,
+    attempted: false,
+    trigger: null,
+    finalSourceLane: routingDecision.selectedLane,
+    sourceLane: routingDecision.selectedLane,
+    sourceProviderId: providerId,
+    sourceModelId: modelId,
+    policy: getReportFallbackPolicy(runtimeConfig, options)
+  };
+}
+
+export async function attemptProvider({ plan, runtime, options = {} }) {
+  const mode = options.mode || "dry-run";
+  const router = options.router || new ModelRouter(runtime.router);
+  const routingDecision = buildRoutingDecision(plan, options);
+  const laneConfig = runtime.router?.[routingDecision.selectedLane];
+  const primaryModelId = options.modelOverride || plan.packet.modelOverride || router.resolve(routingDecision.selectedLane, routingDecision.routeMode);
+  const providersToTry = [primaryModelId, ...(laneConfig?.fallbackModels || [])];
+  const toolSchemas = options.toolSchemas || [];
+  const registry = options.registry;
+  const tokenCounter = options.tokenCounter;
+  const buildSystemPrompt = options.buildSystemPrompt;
+  const buildUserMessage = options.buildUserMessage;
+
+  let fallback = null;
+  let primaryError = null;
+  let lastProviderId = null;
+
+  for (const currentModelId of providersToTry) {
+    const currentProviderId = modelToProviderId(currentModelId);
+    const providerConfig = runtime.providers[currentProviderId];
+    const providerTimeoutMs = computeProviderTimeoutMs(plan, providerConfig, options);
+    const breaker = options.getBreaker?.(currentModelId, runtime.runtime) || null;
+    lastProviderId = currentProviderId;
+
+    if (breaker?.isOpen()) {
+      const retryAfter = breaker.retryAfter();
+      console.warn(`[Nemoris] circuit breaker open for ${currentModelId}, skipping (retry in ${Math.ceil(retryAfter)}s)`);
+      primaryError = new Error(`Provider ${currentModelId} circuit open — retry after ${Math.ceil(retryAfter)}s`);
+      annotateAttemptError(primaryError, {
+        providerId: currentProviderId,
+        modelId: currentModelId,
+        routingDecision,
+        fallback
+      });
+      continue;
+    }
+
+    try {
+      const attempt = await executeProviderCall({
+        plan,
+        runtime,
+        mode,
+        registry,
+        tokenCounter,
+        modelId: currentModelId,
+        providerId: currentProviderId,
+        providerConfig,
+        routingDecision,
+        providerTimeoutMs,
+        toolSchemas,
+        buildSystemPrompt,
+        buildUserMessage,
+        onPrepared: () => {
+          if (!fallback) {
+            fallback = buildFallbackState(runtime.runtime, routingDecision, currentProviderId, currentModelId, options);
+          }
+        }
+      });
+
+      if (mode === "provider") {
+        breaker?.recordSuccess();
+      }
+
+      return {
+        ...attempt,
+        routingDecision,
+        fallback,
+        primaryModelId
+      };
+    } catch (err) {
+      primaryError = annotateAttemptError(err, {
+        providerId: currentProviderId,
+        modelId: currentModelId,
+        routingDecision,
+        fallback
+      });
+      const statusCode = err.statusCode || err.status || 0;
+      breaker?.recordFailure(statusCode);
+
+      if (isRetryableError(err)) {
+        console.warn(`[executor] provider ${currentModelId} failed: ${err.message}, trying next`);
+        continue;
+      }
+      break;
+    }
+  }
+
+  if (!primaryError) {
+    primaryError = new Error("All providers in failover chain exhausted");
+    annotateAttemptError(primaryError, {
+      routingDecision,
+      fallback
+    });
+  }
+
+  const failureClass = classifyRuntimeFailure(primaryError?.message || "");
+  const fallbackResolution = resolveReportFallback({
+    runtimeConfig: runtime.runtime,
+    job: plan.job,
+    routingDecision,
+    providerId: lastProviderId,
+    failureClass,
+    options
+  });
+
+  fallback = {
+    ...(fallback || {}),
+    allowed: fallbackResolution.allowed,
+    attempted: false,
+    trigger: failureClass,
+    localFailureClass: failureClass,
+    localError: primaryError.message,
+    blockedReason: fallbackResolution.allowed ? null : fallbackResolution.reason,
+    targetLane: fallbackResolution.targetLane || null
+  };
+
+  if (!fallbackResolution.allowed) {
+    annotateAttemptError(primaryError, {
+      providerId: primaryError.providerId || lastProviderId,
+      routingDecision,
+      fallback
+    });
+    throw primaryError;
+  }
+
+  fallback.attempted = true;
+  const fallbackRoutingDecision = {
+    ...routingDecision,
+    selectedLane: fallbackResolution.targetLane,
+    routeMode: "fallback",
+    reasons: [...(routingDecision.reasons || []), `fallback:${failureClass}`],
+    description: "Failure-triggered report fallback."
+  };
+  const fallbackModelId = router.resolve(fallbackResolution.targetLane, "primary");
+  const fallbackProviderId = modelToProviderId(fallbackModelId);
+  const fallbackProviderConfig = runtime.providers[fallbackProviderId];
+
+  try {
+    const attempt = await executeProviderCall({
+      plan,
+      runtime,
+      mode,
+      registry,
+      tokenCounter,
+      modelId: fallbackModelId,
+      providerId: fallbackProviderId,
+      providerConfig: fallbackProviderConfig,
+      routingDecision: fallbackRoutingDecision,
+      providerTimeoutMs: computeProviderTimeoutMs(plan, fallbackProviderConfig, options),
+      toolSchemas,
+      buildSystemPrompt,
+      buildUserMessage
+    });
+
+    return {
+      ...attempt,
+      routingDecision: fallbackRoutingDecision,
+      fallback: {
+        ...fallback,
+        success: true,
+        finalSourceLane: fallbackRoutingDecision.selectedLane,
+        finalProviderId: fallbackProviderId,
+        finalModelId: fallbackModelId
+      },
+      toolLoopEnabled: mode === "provider" && Boolean(options.allowToolLoopOnFallback)
+    };
+  } catch (fallbackError) {
+    fallback = {
+      ...fallback,
+      success: false,
+      fallbackFailureClass: classifyRuntimeFailure(fallbackError?.message || ""),
+      fallbackError: fallbackError.message
+    };
+    const combinedError = new Error(
+      `Primary provider failed (${failureClass}) and fallback failed: ${fallbackError.message}`
+    );
+    annotateAttemptError(combinedError, {
+      providerId: fallbackProviderId,
+      modelId: fallbackModelId,
+      routingDecision: fallbackRoutingDecision,
+      providerCapabilities: fallbackError?.providerCapabilities || null,
+      invocation: fallbackError?.invocation || null,
+      preflight: fallbackError?.preflight || null,
+      fallback
+    });
+    throw combinedError;
+  }
+}