ai-maestro 1.0.0

package/src/orchestration/provider-router.mjs

@@ -0,0 +1,352 @@
+import { classifyTask } from './task-classifier.mjs';
+import { listEngineRecords } from './capability-registry.mjs';
+import { selectEngine } from './engine-selector.mjs';
+import { deriveHealthTargetId, getHealthState } from './provider-health.mjs';
+import { DEFAULT_BUDGET } from './budget-manager.mjs';
+
+export const PROVIDER_ROUTER_ACTIONS = new Set(['switch_engine', 'needs_human', 'block', 'completed']);
+
+const AUTO_FALLBACK_FAILURE_CLASSES = new Set([
+  'infrastructure',
+  'network',
+  'timeout',
+  'stream_interruption',
+  'rate_limit',
+  'provider_unavailable',
+  'quota',
+  'model_unavailable'
+]);
+
+const HUMAN_FAILURE_CLASSES = new Set([
+  'authentication',
+  'engine_resolution',
+  'worker_failure',
+  'deliverable_rejection',
+  'safety_block',
+  'human_decision',
+  'unknown'
+]);
+
+function asArray(value) {
+  return Array.isArray(value) ? value : value == null ? [] : [value];
+}
+
+function asSet(value) {
+  return value instanceof Set ? value : new Set(asArray(value).map(item => String(item)));
+}
+
+function normalizeFailureClassification(input = {}) {
+  if (typeof input === 'string') {
+    return { outcome: 'failure', failureClass: input, reason: 'provided failure class' };
+  }
+  return {
+    ...input,
+    outcome: input.outcome || (input.failureClass ? 'failure' : 'unknown'),
+    failureClass: input.failureClass || input.failure_class || null
+  };
+}
+
+function reject(engineRecord, reason) {
+  return {
+    engineId: engineRecord && engineRecord.id ? String(engineRecord.id) : null,
+    healthTargetId: engineRecord && engineRecord.id ? String(engineRecord.id) : null,
+    accepted: false,
+    reason
+  };
+}
+
+function accept(engineRecord, healthState) {
+  const healthTargetId = deriveHealthTargetId(engineRecord);
+  return {
+    engineId: engineRecord.id,
+    healthTargetId,
+    accepted: true,
+    reason: 'eligible: enabled, unvisited, CLOSED circuit, and complete provider/model/capability metadata',
+    healthState: healthState.state
+  };
+}
+
+function deadlineExpired(deadline, timestamp) {
+  if (!deadline) return false;
+  const deadlineMs = Date.parse(deadline);
+  const nowMs = Date.parse(timestamp);
+  return Number.isFinite(deadlineMs) && Number.isFinite(nowMs) && nowMs >= deadlineMs;
+}
+
+function budgetAllowsAnotherAttempt(budgetState = {}) {
+  if (budgetState.allowed === false) {
+    return { allowed: false, reason: budgetState.reason || 'budget does not allow another attempt' };
+  }
+  const maxAttempts = Number.isInteger(budgetState.maxAttempts)
+    ? budgetState.maxAttempts
+    : Number.isInteger(budgetState.maxRunsPerTask)
+      ? budgetState.maxRunsPerTask
+      : Number.isInteger(budgetState.budget && budgetState.budget.maxRunsPerTask)
+        ? budgetState.budget.maxRunsPerTask
+        : DEFAULT_BUDGET.maxRunsPerTask;
+  const runsSoFar = Number.isInteger(budgetState.runsSoFar) ? budgetState.runsSoFar : 0;
+  if (runsSoFar >= maxAttempts) {
+    return { allowed: false, reason: 'maxRunsPerTask (' + maxAttempts + ') reached for this task (runsSoFar=' + runsSoFar + ').' };
+  }
+  return { allowed: true, maxAttempts, runsSoFar };
+}
+
+function engineRecordIsComplete(engineRecord) {
+  if (!engineRecord || typeof engineRecord.id !== 'string' || engineRecord.id.trim() === '') {
+    return { ok: false, reason: 'missing engine id' };
+  }
+  if (engineRecord.enabled !== true) {
+    return { ok: false, reason: 'disabled' };
+  }
+  if (!engineRecord.provider) {
+    return { ok: false, reason: 'missing provider' };
+  }
+  if (!engineRecord.model) {
+    return { ok: false, reason: 'missing model' };
+  }
+  if (!engineRecord.capabilities || typeof engineRecord.capabilities !== 'object') {
+    return { ok: false, reason: 'missing capabilities' };
+  }
+  return { ok: true };
+}
+
+function mapSelectionAlternatives(alternatives = []) {
+  return alternatives.map(item => ({
+    engineId: item.engine || null,
+    healthTargetId: item.engine || null,
+    accepted: false,
+    reason: item.rejectedBecause || 'rejected by capability gate'
+  }));
+}
+
+export async function selectFallbackCandidate({
+  taskClassification,
+  engines,
+  visitedEngineIds = new Set(),
+  visitedHealthTargets = new Set(),
+  allowPaid = false,
+  allowUnknownCost = true,
+  preferFree = true,
+  timestamp = new Date().toISOString(),
+  dependencies = {}
+} = {}) {
+  const getHealth = dependencies.getHealthState || getHealthState;
+  const select = dependencies.selectEngine || selectEngine;
+  const visitedEngines = asSet(visitedEngineIds);
+  const visitedTargets = asSet(visitedHealthTargets);
+  const acceptedEngines = [];
+  const candidateAudit = [];
+
+  for (const engineRecord of engines || []) {
+    const completeness = engineRecordIsComplete(engineRecord);
+    if (!completeness.ok) {
+      candidateAudit.push(reject(engineRecord, completeness.reason));
+      continue;
+    }
+    const engineId = String(engineRecord.id);
+    const healthTargetId = deriveHealthTargetId(engineRecord);
+    if (visitedEngines.has(engineId)) {
+      candidateAudit.push(reject(engineRecord, 'visited engine'));
+      continue;
+    }
+    if (visitedTargets.has(healthTargetId)) {
+      candidateAudit.push(reject(engineRecord, 'visited health target'));
+      continue;
+    }
+    const healthState = await getHealth(healthTargetId, { timestamp });
+    if (healthState.state === 'OPEN') {
+      candidateAudit.push({ ...reject(engineRecord, 'circuit OPEN'), healthState: healthState.state });
+      continue;
+    }
+    if (healthState.state === 'HALF_OPEN') {
+      candidateAudit.push({ ...reject(engineRecord, 'circuit HALF_OPEN is not selected automatically in 03H2A'), healthState: healthState.state });
+      continue;
+    }
+    if (healthState.state !== 'CLOSED') {
+      candidateAudit.push({ ...reject(engineRecord, 'unknown circuit state'), healthState: healthState.state || null });
+      continue;
+    }
+    acceptedEngines.push(engineRecord);
+    candidateAudit.push(accept(engineRecord, healthState));
+  }
+
+  const selection = await select(taskClassification, { engines: acceptedEngines, allowPaid, allowUnknownCost, preferFree });
+  const selectedEngineId = selection.selectedEngine || null;
+  const rejectedBySelection = mapSelectionAlternatives(selection.alternatives || []);
+  const rejectedCandidates = [
+    ...candidateAudit.filter(item => !item.accepted),
+    ...rejectedBySelection
+  ];
+  return {
+    selectedEngineId,
+    selectedEngine: selectedEngineId,
+    acceptedCandidates: candidateAudit.filter(item => item.accepted),
+    rejectedCandidates,
+    selection
+  };
+}
+
+export async function planProviderFallback({
+  task,
+  taskClassification: providedTaskClassification = null,
+  failureClassification: rawFailureClassification,
+  fallbackDecisionContext: providedFallbackDecisionContext = {},
+  visitedEngineIds = [],
+  visitedHealthTargets = [],
+  budgetState = {},
+  deadline = null,
+  timestamp = new Date().toISOString(),
+  allowPaid = false,
+  allowUnknownCost = true,
+  preferFree = true,
+  dependencies = {}
+} = {}) {
+  const reason = [];
+  const failureClassification = normalizeFailureClassification(rawFailureClassification || providedFallbackDecisionContext.failureClassification || {});
+  const failureClass = failureClassification.failureClass;
+  const taskClassification = providedTaskClassification || classifyTask(task || {});
+  const capabilityRequirements = taskClassification.requires || {};
+  const fallbackDecisionContext = {
+    ...providedFallbackDecisionContext,
+    taskClassification,
+    failureClassification,
+    capabilityRequirements,
+    visitedEngineIds: [...asSet(visitedEngineIds)],
+    visitedHealthTargets: [...asSet(visitedHealthTargets)],
+    budgetState
+  };
+
+  if (failureClassification.outcome === 'success') {
+    return {
+      action: 'completed',
+      candidateEngineId: null,
+      allowed: true,
+      reason: ['previous attempt succeeded'],
+      taskClassification,
+      failureClassification,
+      capabilityRequirements,
+      fallbackDecisionContext,
+      acceptedCandidates: [],
+      rejectedCandidates: []
+    };
+  }
+
+  if (deadlineExpired(deadline, timestamp)) {
+    return {
+      action: 'block',
+      terminalReason: 'fallback_exhausted',
+      candidateEngineId: null,
+      allowed: false,
+      reason: ['global fallback deadline expired'],
+      taskClassification,
+      failureClassification,
+      capabilityRequirements,
+      fallbackDecisionContext,
+      acceptedCandidates: [],
+      rejectedCandidates: []
+    };
+  }
+
+  const budget = budgetAllowsAnotherAttempt(budgetState);
+  if (!budget.allowed) {
+    return {
+      action: 'block',
+      terminalReason: 'fallback_blocked_by_budget',
+      candidateEngineId: null,
+      allowed: false,
+      reason: [budget.reason],
+      taskClassification,
+      failureClassification,
+      capabilityRequirements,
+      fallbackDecisionContext,
+      acceptedCandidates: [],
+      rejectedCandidates: []
+    };
+  }
+
+  if (HUMAN_FAILURE_CLASSES.has(failureClass) || !AUTO_FALLBACK_FAILURE_CLASSES.has(failureClass)) {
+    return {
+      action: 'needs_human',
+      candidateEngineId: null,
+      allowed: false,
+      reason: [failureClass === 'authentication'
+        ? 'authentication requires human intervention'
+        : 'failure class is not eligible for automatic fallback in 03H2A: ' + String(failureClass || 'unknown')],
+      taskClassification,
+      failureClassification,
+      capabilityRequirements,
+      fallbackDecisionContext,
+      acceptedCandidates: [],
+      rejectedCandidates: []
+    };
+  }
+
+  let engineRecords;
+  try {
+    const list = dependencies.listEngineRecords || listEngineRecords;
+    engineRecords = await list({ enabledOnly: false });
+  } catch (error) {
+    return {
+      action: 'needs_human',
+      candidateEngineId: null,
+      allowed: false,
+      reason: ['engine registry unreadable: ' + (error && error.message ? error.message : String(error))],
+      taskClassification,
+      failureClassification,
+      capabilityRequirements,
+      fallbackDecisionContext,
+      acceptedCandidates: [],
+      rejectedCandidates: []
+    };
+  }
+
+  const candidate = await selectFallbackCandidate({
+    taskClassification,
+    engines: engineRecords,
+    visitedEngineIds,
+    visitedHealthTargets,
+    allowPaid,
+    allowUnknownCost,
+    preferFree,
+    timestamp,
+    dependencies
+  });
+
+  if (!candidate.selectedEngineId) {
+    reason.push('no safe compatible fallback candidate');
+    if (failureClass === 'rate_limit') {
+      reason.push('rate limit cooldown recorded; no active wait is performed');
+    }
+    return {
+      action: 'needs_human',
+      candidateEngineId: null,
+      allowed: false,
+      reason,
+      taskClassification,
+      failureClassification,
+      capabilityRequirements,
+      fallbackDecisionContext,
+      acceptedCandidates: candidate.acceptedCandidates,
+      rejectedCandidates: candidate.rejectedCandidates,
+      selection: candidate.selection
+    };
+  }
+
+  reason.push('selected safe fallback candidate ' + candidate.selectedEngineId);
+  if (failureClass === 'rate_limit') {
+    reason.push('rate limit does not retry the same engine and does not wait actively');
+  }
+  return {
+    action: 'switch_engine',
+    candidateEngineId: candidate.selectedEngineId,
+    allowed: true,
+    reason,
+    taskClassification,
+    failureClassification,
+    capabilityRequirements,
+    fallbackDecisionContext,
+    acceptedCandidates: candidate.acceptedCandidates,
+    rejectedCandidates: candidate.rejectedCandidates,
+    selection: candidate.selection
+  };
+}