@inetafrica/open-claudia 2.14.8 → 3.0.0

package/core/providers/index.js

@@ -0,0 +1,240 @@
+"use strict";
+
+const { validateProvider, validateTypedStatus } = require("./contract");
+
+const DEFAULT_PROVIDER_IDS = Object.freeze(["claude", "codex"]);
+const DEFAULT_STATUS_TTL_MS = 30_000;
+
+class ProviderRegistryError extends Error {
+  constructor(code, message, details = {}) {
+    super(message);
+    this.name = "ProviderRegistryError";
+    this.code = code;
+    this.details = details;
+  }
+}
+
+class ProviderRegistry {
+  constructor(options = {}) {
+    this.allowedProviderIds = new Set(options.allowedProviderIds || DEFAULT_PROVIDER_IDS);
+    this.defaultProvider = options.defaultProvider == null
+      ? null
+      : String(options.defaultProvider).trim().toLowerCase();
+    this.providers = new Map();
+    this.statusTtlMs = Number.isFinite(options.statusTtlMs) ? options.statusTtlMs : DEFAULT_STATUS_TTL_MS;
+    this.now = typeof options.now === "function" ? options.now : Date.now;
+    this.statusCache = new Map();
+  }
+
+  registerProvider(provider) {
+    validateProvider(provider);
+    if (!this.allowedProviderIds.has(provider.id)) {
+      throw new ProviderRegistryError("UNKNOWN_PROVIDER", `Unknown provider: ${provider.id}`, { providerId: provider.id });
+    }
+    if (this.providers.has(provider.id)) {
+      throw new ProviderRegistryError("DUPLICATE_PROVIDER", `Provider already registered: ${provider.id}`, { providerId: provider.id });
+    }
+    this.providers.set(provider.id, provider);
+    return provider;
+  }
+
+  getProvider(providerId) {
+    if (!this.allowedProviderIds.has(providerId) || !this.providers.has(providerId)) {
+      throw new ProviderRegistryError("UNKNOWN_PROVIDER", `Unknown provider: ${providerId}`, { providerId });
+    }
+    return this.providers.get(providerId);
+  }
+
+  listProviders() {
+    return [...this.providers.values()];
+  }
+
+  providerStatus(providerId, options = {}) {
+    const provider = this.getProvider(providerId);
+    const wantAuth = options.probeAuth !== false;
+
+    // Availability is a cheap executable lookup and always runs fresh, so a
+    // provider that disappears (or moves) mid-session is detected immediately.
+    let available = false;
+    let executable = null;
+    let availabilityReason = null;
+    try {
+      available = provider.isAvailable() === true;
+      if (available) executable = provider.executable() || null;
+      if (available && !executable) {
+        available = false;
+        availabilityReason = "Provider reported available without an executable";
+      }
+    } catch (error) {
+      availabilityReason = error.message;
+    }
+
+    if (!available) {
+      this.statusCache.delete(provider.id);
+      return {
+        id: provider.id,
+        label: provider.label,
+        availability: { state: "missing", executable: null, reason: availabilityReason || "Provider executable is unavailable" },
+        compatibility: { state: "not_checked", reason: "Provider executable is unavailable" },
+        auth: { state: "not_checked", reason: "Provider executable is unavailable" },
+      };
+    }
+
+    // The expensive CLI probes (version/help spawns, auth status) are served
+    // from a short TTL cache keyed to the same executable path. Only a fully
+    // healthy, auth-probed status is cached: negative results always re-probe
+    // so an install or login recovers immediately, and a no-auth probe never
+    // masks an auth regression for auth-requiring callers.
+    if (options.refresh !== true && this.statusTtlMs > 0) {
+      const cached = this.statusCache.get(provider.id);
+      if (cached
+          && (this.now() - cached.at) < this.statusTtlMs
+          && cached.status.availability.executable === executable) {
+        const status = structuredClone(cached.status);
+        if (!wantAuth) status.auth = { state: "not_checked", reason: "Authentication was not requested" };
+        return status;
+      }
+    }
+
+    const status = this.#probeStatus(provider, options, executable);
+    if (this.statusTtlMs > 0
+        && wantAuth
+        && status.compatibility.state === "compatible"
+        && status.auth.state === "authenticated") {
+      this.statusCache.set(provider.id, { at: this.now(), status: structuredClone(status) });
+    }
+    return status;
+  }
+
+  clearStatusCache(providerId = null) {
+    if (providerId === null) this.statusCache.clear();
+    else this.statusCache.delete(providerId);
+  }
+
+  #probeStatus(provider, options, executable) {
+    let compatibility;
+    try {
+      compatibility = validateTypedStatus(provider.compatibilityStatus(), "compatibility");
+    } catch (error) {
+      compatibility = { state: "unknown", reason: "Compatibility probe failed" };
+    }
+    const auth = compatibility.state === "incompatible" || options.probeAuth === false
+      ? { state: "not_checked", reason: compatibility.state === "incompatible" ? "Provider is incompatible" : "Authentication was not requested" }
+      : (() => {
+          try { return validateTypedStatus(provider.authStatus(), "auth"); }
+          catch (error) { return { state: "unknown", reason: "Authentication probe failed" }; }
+        })();
+    return {
+      id: provider.id,
+      label: provider.label,
+      availability: { state: "available", executable, reason: null },
+      compatibility,
+      auth,
+    };
+  }
+
+  availableProviders() {
+    return this.listProviders().filter((provider) => {
+      const status = this.providerStatus(provider.id, { probeAuth: false });
+      return status.availability.state === "available" && status.compatibility.state !== "incompatible";
+    });
+  }
+
+  selectDefaultProvider(preferredId = this.defaultProvider) {
+    const preferred = preferredId == null || String(preferredId).trim() === ""
+      ? null
+      : String(preferredId).trim().toLowerCase();
+    if (preferred) {
+      if (!this.allowedProviderIds.has(preferred) || !this.providers.has(preferred)) {
+        return {
+          providerId: null,
+          source: "explicit",
+          reason: `Unknown default provider: ${preferred}`,
+        };
+      }
+      const status = this.providerStatus(preferred, { probeAuth: false });
+      if (status.availability.state !== "available") {
+        return { providerId: null, source: "explicit", reason: `${status.label} is unavailable` };
+      }
+      if (status.compatibility.state !== "compatible") {
+        return {
+          providerId: null,
+          source: "explicit",
+          reason: status.compatibility.reason || `${status.label} compatibility could not be confirmed`,
+        };
+      }
+      return { providerId: preferred, source: "explicit", reason: null };
+    }
+
+    for (const provider of this.listProviders()) {
+      const status = this.providerStatus(provider.id, { probeAuth: false });
+      if (status.availability.state === "available" && status.compatibility.state === "compatible") {
+        return { providerId: provider.id, source: "detected", reason: null };
+      }
+    }
+    return {
+      providerId: null,
+      source: "detected",
+      reason: "No compatible provider is configured or installed",
+    };
+  }
+
+  resolveProviderForRun(providerId = null) {
+    if (providerId !== null && providerId !== undefined) {
+      const provider = this.getProvider(providerId);
+      return this.#assertRunnable(provider);
+    }
+
+    if (this.defaultProvider) {
+      const provider = this.getProvider(this.defaultProvider);
+      return this.#assertRunnable(provider);
+    }
+
+    const selection = this.selectDefaultProvider();
+    if (!selection.providerId) {
+      throw new ProviderRegistryError(
+        "NO_AVAILABLE_PROVIDER",
+        "No compatible provider is available. Configure Claude Code or OpenAI Codex before starting a model turn.",
+      );
+    }
+    // Foreground selection is deterministic and never silently changes the
+    // provider because authentication failed. Explicit fallback belongs to the
+    // utility-provider policy, where the caller opts into it and records it.
+    return this.#assertRunnable(this.getProvider(selection.providerId));
+  }
+
+  #assertRunnable(provider) {
+    const status = this.providerStatus(provider.id);
+    if (status.availability.state !== "available") {
+      throw new ProviderRegistryError("PROVIDER_UNAVAILABLE", `${provider.label} is unavailable`, { providerId: provider.id, status });
+    }
+    if (status.compatibility.state === "incompatible") {
+      throw new ProviderRegistryError("PROVIDER_INCOMPATIBLE", `${provider.label} is incompatible: ${status.compatibility.reason || "unsupported version"}`, { providerId: provider.id, status });
+    }
+    if (status.auth.state === "unauthenticated") {
+      throw new ProviderRegistryError("PROVIDER_UNAUTHENTICATED", `${provider.label} is not authenticated: ${status.auth.reason || "login required"}`, { providerId: provider.id, status });
+    }
+    return provider;
+  }
+}
+
+const registry = new ProviderRegistry({
+  defaultProvider: require("../config").DEFAULT_PROVIDER,
+});
+registry.registerProvider(require("./claude").claudeProvider);
+registry.registerProvider(require("./codex").codexProvider);
+
+module.exports = {
+  DEFAULT_PROVIDER_IDS,
+  ProviderRegistry,
+  ProviderRegistryError,
+  availableProviders: registry.availableProviders.bind(registry),
+  clearProviderStatusCache: registry.clearStatusCache.bind(registry),
+  getProvider: registry.getProvider.bind(registry),
+  listProviders: registry.listProviders.bind(registry),
+  providerStatus: registry.providerStatus.bind(registry),
+  registerProvider: registry.registerProvider.bind(registry),
+  resolveProviderForRun: registry.resolveProviderForRun.bind(registry),
+  selectDefaultProvider: registry.selectDefaultProvider.bind(registry),
+  registry,
+};

package/core/providers/utility-policy.js

@@ -0,0 +1,269 @@
+"use strict";
+
+const config = require("../config");
+
+const PROVIDER_IDS = Object.freeze(["claude", "codex"]);
+const PROVIDER_ID_SET = new Set(PROVIDER_IDS);
+const PURPOSES = Object.freeze(["subagent", "recall", "review", "dream", "introspection", "enforcer"]);
+const PURPOSE_SET = new Set(PURPOSES);
+const TIERS = Object.freeze(["low", "medium", "high"]);
+const TIER_SET = new Set(TIERS);
+const PURPOSE_PROVIDER_ENV = Object.freeze({
+  subagent: "SUBAGENT_PROVIDER",
+  recall: "RECALL_PROVIDER",
+  review: "MEMORY_PROVIDER",
+  dream: "DREAM_PROVIDER",
+  introspection: "DREAM_PROVIDER",
+  enforcer: "ENFORCER_PROVIDER",
+});
+const PURPOSE_MODEL_PREFIX = Object.freeze({
+  subagent: "SUBAGENT_MODEL",
+  recall: "RECALL_MODEL",
+  review: "PACK_REVIEW_MODEL",
+  dream: "DREAM_MODEL",
+  introspection: "DREAM_MODEL",
+  enforcer: "ENFORCER_MODEL",
+});
+const LEGACY_CLAUDE_MODEL_ENV = Object.freeze({
+  review: "PACK_REVIEW_MODEL",
+  dream: "DREAM_MODEL",
+  introspection: "DREAM_MODEL",
+  enforcer: "ENFORCER_MODEL",
+});
+
+class UtilityPolicyError extends Error {
+  constructor(code, message, details = {}) {
+    super(message);
+    this.name = "UtilityPolicyError";
+    this.code = code;
+    this.details = details;
+  }
+}
+
+function normalizeProvider(value, { allowActive = false, allowEmpty = false } = {}) {
+  const provider = String(value == null ? "" : value).trim().toLowerCase();
+  if (!provider && allowEmpty) return null;
+  if (PROVIDER_ID_SET.has(provider) || (allowActive && provider === "active")) return provider;
+  throw new UtilityPolicyError(
+    "INVALID_UTILITY_PROVIDER",
+    `Utility provider must be ${allowActive ? "active, " : ""}claude, or codex`,
+    { provider: provider || null },
+  );
+}
+
+function normalizePurpose(value) {
+  const purpose = String(value || "").trim().toLowerCase();
+  if (!PURPOSE_SET.has(purpose)) {
+    throw new UtilityPolicyError("INVALID_UTILITY_PURPOSE", `Unknown utility purpose: ${purpose || "(empty)"}`, { purpose });
+  }
+  return purpose;
+}
+
+function normalizeTier(value) {
+  const tier = String(value || "medium").trim().toLowerCase();
+  if (!TIER_SET.has(tier)) {
+    throw new UtilityPolicyError("INVALID_UTILITY_TIER", `Utility tier must be low, medium, or high`, { tier });
+  }
+  return tier;
+}
+
+function parseProviderFallbacks(value) {
+  const values = Array.isArray(value) ? value : String(value || "").split(",");
+  const result = [];
+  for (const raw of values) {
+    const provider = normalizeProvider(raw, { allowEmpty: true });
+    if (provider && !result.includes(provider)) result.push(provider);
+  }
+  return result;
+}
+
+function defaultActiveProvider(env = process.env) {
+  const inherited = String(env?.OC_PROVIDER || process.env.OC_PROVIDER || "").trim().toLowerCase();
+  if (PROVIDER_ID_SET.has(inherited)) return inherited;
+  try {
+    const { currentCanonicalUserId } = require("../context");
+    const canonicalUserId = currentCanonicalUserId();
+    if (!canonicalUserId) return null;
+    const state = require("../state");
+    return state.getActiveProvider(state.getUserState(canonicalUserId));
+  } catch (_) {
+    return null;
+  }
+}
+
+function registryProviders(registry) {
+  try {
+    const listed = registry.listProviders();
+    return listed.map((provider) => provider.id).filter((id) => PROVIDER_ID_SET.has(id));
+  } catch (_) {
+    return [...PROVIDER_IDS];
+  }
+}
+
+function runnableStatus(registry, providerId) {
+  let status;
+  try { status = registry.providerStatus(providerId); }
+  catch (error) {
+    return { runnable: false, code: error.code || "PROVIDER_UNAVAILABLE", reason: error.message || "provider status failed", status: null };
+  }
+  if (status?.availability?.state !== "available") {
+    return { runnable: false, code: "PROVIDER_UNAVAILABLE", reason: status?.availability?.reason || "provider executable is unavailable", status };
+  }
+  if (status?.compatibility?.state === "incompatible") {
+    return { runnable: false, code: "PROVIDER_INCOMPATIBLE", reason: status.compatibility.reason || "provider is incompatible", status };
+  }
+  if (status?.auth?.state === "unauthenticated") {
+    return { runnable: false, code: "PROVIDER_UNAUTHENTICATED", reason: status.auth.reason || "provider is not authenticated", status };
+  }
+  return { runnable: true, code: null, reason: null, status };
+}
+
+function envValue(env, key) {
+  return String(env?.[key] == null ? "" : env[key]).trim();
+}
+
+function exactModelOverride(env, purpose, providerId) {
+  const prefix = PURPOSE_MODEL_PREFIX[purpose];
+  if (prefix) {
+    const specific = envValue(env, `${prefix}_${providerId.toUpperCase()}`);
+    if (specific) return specific;
+  }
+  if (providerId === "claude") {
+    const legacyKey = LEGACY_CLAUDE_MODEL_ENV[purpose];
+    const legacy = legacyKey ? envValue(env, legacyKey) : "";
+    if (legacy) return legacy;
+  }
+  return null;
+}
+
+function modelFor(provider, request, env) {
+  const { purpose, tier, model } = request;
+  if (typeof model === "string" && model.trim()) return model.trim();
+  const customPrefix = String(request.modelEnvPrefix || "").trim();
+  if (customPrefix) {
+    if (!/^[A-Z][A-Z0-9_]*$/.test(customPrefix)) {
+      throw new UtilityPolicyError("INVALID_UTILITY_MODEL_OVERRIDE", "modelEnvPrefix must be an uppercase environment-key prefix");
+    }
+    const specific = envValue(env, `${customPrefix}_${provider.id.toUpperCase()}`);
+    if (specific) return specific;
+  }
+  const legacyKey = String(request.legacyClaudeModelEnv || "").trim();
+  if (provider.id === "claude" && legacyKey) {
+    if (!/^[A-Z][A-Z0-9_]*$/.test(legacyKey)) {
+      throw new UtilityPolicyError("INVALID_UTILITY_MODEL_OVERRIDE", "legacyClaudeModelEnv must be an uppercase environment key");
+    }
+    const legacy = envValue(env, legacyKey);
+    if (legacy) return legacy;
+  }
+  const exact = exactModelOverride(env, purpose, provider.id);
+  if (exact) return exact;
+  if (typeof provider.tierModel === "function") return provider.tierModel(tier);
+  return provider.defaultModel() || null;
+}
+
+function createUtilityPolicy(options = {}) {
+  const registry = options.registry || require("./index");
+  const env = options.env || config.config;
+  const activeProvider = typeof options.activeProvider === "function" ? options.activeProvider : () => defaultActiveProvider(env);
+
+  function candidateIds(request) {
+    const purpose = normalizePurpose(request.purpose);
+    const explicit = request.provider == null ? null : normalizeProvider(request.provider, { allowActive: true });
+    const purposeSetting = envValue(env, PURPOSE_PROVIDER_ENV[purpose]);
+    const configured = explicit || (purposeSetting ? normalizeProvider(purposeSetting, { allowActive: true }) : null)
+      || normalizeProvider(envValue(env, "UTILITY_PROVIDER") || "active", { allowActive: true });
+
+    let preferred = configured;
+    if (preferred === "active") {
+      const capturedActive = request.activeProvider == null
+        ? null
+        : normalizeProvider(request.activeProvider, { allowEmpty: true });
+      const active = capturedActive || activeProvider();
+      if (active) preferred = normalizeProvider(active);
+      else {
+        const globalDefault = envValue(env, "DEFAULT_PROVIDER");
+        preferred = globalDefault
+          ? normalizeProvider(globalDefault)
+          : (registryProviders(registry).find((providerId) => runnableStatus(registry, providerId).runnable) || null);
+      }
+    }
+    if (!preferred) {
+      throw new UtilityPolicyError("NO_AVAILABLE_UTILITY_PROVIDER", "No default utility provider is configured", { purpose });
+    }
+    const fallbacks = parseProviderFallbacks(
+      request.fallbacks !== undefined ? request.fallbacks : env?.PROVIDER_FALLBACKS,
+    );
+    return {
+      purpose,
+      preferred,
+      ids: [preferred, ...fallbacks.filter((id) => id !== preferred)],
+    };
+  }
+
+  function candidates(request = {}) {
+    const purpose = normalizePurpose(request.purpose);
+    const tier = normalizeTier(request.tier);
+    const selection = candidateIds({ ...request, purpose });
+    const attempts = [];
+    const runnable = [];
+    for (const providerId of selection.ids) {
+      const probe = runnableStatus(registry, providerId);
+      attempts.push({ providerId, code: probe.code, reason: probe.reason });
+      if (!probe.runnable) continue;
+      let provider;
+      try { provider = registry.getProvider(providerId); }
+      catch (error) {
+        attempts[attempts.length - 1] = { providerId, code: error.code || "UNKNOWN_PROVIDER", reason: error.message };
+        continue;
+      }
+      runnable.push({
+        purpose,
+        tier,
+        provider,
+        providerId,
+        preferredProviderId: selection.preferred,
+        fallbackUsed: providerId !== selection.preferred,
+        model: modelFor(provider, { ...request, purpose, tier }, env),
+        status: probe.status,
+        attempts: attempts.map((attempt) => ({ ...attempt })),
+      });
+    }
+    if (!runnable.length) {
+      throw new UtilityPolicyError(
+        "NO_AVAILABLE_UTILITY_PROVIDER",
+        `No configured provider can run the ${purpose} utility task`,
+        { purpose, preferredProviderId: selection.preferred, attempts },
+      );
+    }
+    return runnable;
+  }
+
+  return {
+    candidates,
+    resolve: (request) => candidates(request)[0],
+  };
+}
+
+let defaultPolicy = null;
+function resolveUtilityProvider(request) {
+  if (!defaultPolicy) defaultPolicy = createUtilityPolicy();
+  return defaultPolicy.resolve(request);
+}
+
+module.exports = {
+  LEGACY_CLAUDE_MODEL_ENV,
+  PROVIDER_IDS,
+  PURPOSES,
+  PURPOSE_MODEL_PREFIX,
+  PURPOSE_PROVIDER_ENV,
+  TIERS,
+  UtilityPolicyError,
+  createUtilityPolicy,
+  defaultActiveProvider,
+  exactModelOverride,
+  normalizePurpose,
+  normalizeTier,
+  parseProviderFallbacks,
+  resolveUtilityProvider,
+  runnableStatus,
+};

package/core/recall/classic.js

@@ -11,7 +11,7 @@
 // are injected here so module-local injection caches / lastInjected keep working.
 
 async function run(ctx) {
-  const { userText, fullContext, packLimit, budget, helpers } = ctx;
+  const { userText, fullContext, packLimit, budget, helpers, provider } = ctx;
   const {
     packsLib, entitiesLib, mergeMatches, filterMatches, logRecall,
     buildPackBlock, buildEntityBlock,
@@ -36,7 +36,7 @@ async function run(ctx) {
 
   const candPacks = packMatches;
   const candEntities = entityMatches;
-  ({ packMatches, entityMatches } = await filterMatches(userText, fullContext, packMatches, entityMatches));
+  ({ packMatches, entityMatches } = await filterMatches(userText, fullContext, packMatches, entityMatches, { provider }));
   packMatches = packMatches.slice(0, packLimit);
   entityMatches = entityMatches.slice(0, 4);
   logRecall(userText, candPacks, candEntities, packMatches, entityMatches);