nemoris 0.1.0

package/src/runtime/provider-attempt.js

@@ -0,0 +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;
+  }
+}

package/src/runtime/report-fallback.js

@@ -0,0 +1,71 @@
+import { getProviderModePolicy } from "./guards.js";
+
+function readFlag(name) {
+  const raw = process.env[name];
+  return raw === "1" || raw === "true";
+}
+
+export function classifyRuntimeFailure(message) {
+  const normalized = String(message || "").toLowerCase();
+  if (!normalized) return "unknown_failure";
+  if (normalized.includes("timed out")) return "timeout";
+  if (normalized.includes("loading model") || normalized.includes("server loading")) return "provider_loading";
+  if (normalized.includes("missing auth token") || normalized.includes("missing api key")) return "auth_missing";
+  if (normalized.includes("model") && normalized.includes("not found")) return "missing_model";
+  if (normalized.includes("structured") && normalized.includes("output")) return "structured_output_failure";
+  if (normalized.includes("provider error")) return "provider_error";
+  return "unknown_failure";
+}
+
+export function getReportFallbackPolicy(runtimeConfig = {}, options = {}) {
+  const configured = runtimeConfig?.reportFallback || {};
+  const envEnabled = readFlag("NEMORIS_ALLOW_REPORT_FALLBACK");
+  const allowReportFallback = Boolean(options.allowReportFallback || envEnabled || configured.enabled === true);
+
+  return {
+    enabled: allowReportFallback,
+    configEnabled: configured.enabled === true,
+    envEnabled,
+    overrideEnabled: Boolean(options.allowReportFallback),
+    lane: configured.lane || "report_fallback_lowcost",
+    allowedJobIds: configured.allowedJobIds || ["workspace-health"],
+    allowedFailureClasses: configured.allowedFailureClasses || ["timeout", "provider_loading"]
+  };
+}
+
+export function resolveReportFallback({ runtimeConfig, job, routingDecision, providerId, failureClass, options = {} }) {
+  const policy = getReportFallbackPolicy(runtimeConfig, options);
+  const jobPolicy = job?.reportFallback || null;
+
+  if (!jobPolicy?.enabled) {
+    return { allowed: false, policy, reason: "Job is not configured for report fallback." };
+  }
+
+  if (!policy.enabled) {
+    return { allowed: false, policy, reason: "Report fallback is disabled." };
+  }
+
+  if (!policy.allowedJobIds.includes(job.id)) {
+    return { allowed: false, policy, reason: `Job ${job.id} is not allowed to use report fallback.` };
+  }
+
+  if (!policy.allowedFailureClasses.includes(failureClass)) {
+    return { allowed: false, policy, reason: `Failure class ${failureClass} does not qualify for report fallback.` };
+  }
+
+  if (providerId !== "ollama" || routingDecision?.selectedLane !== "local_report") {
+    return { allowed: false, policy, reason: "Report fallback only applies after local_report Ollama failures." };
+  }
+
+  const providerModePolicy = getProviderModePolicy();
+  if (!providerModePolicy.allowRemoteProviders) {
+    return { allowed: false, policy, reason: "Remote provider execution is not enabled." };
+  }
+
+  return {
+    allowed: true,
+    policy,
+    targetLane: jobPolicy.lane || policy.lane,
+    trigger: failureClass
+  };
+}