@remodex/rmx 1.0.2

package/src/codex/write-coordination.ts

@@ -0,0 +1,114 @@
+/**
+ * The witness a native Codex write is coordinated by.
+ *
+ * NOT an `AdmissionSnapshot`, and the difference is the whole reason this file
+ * exists. `admitCodexWrite` refuses before it constructs a snapshot unless
+ * ownership is `owned` (`admission.ts`), so every snapshot it produces carries
+ * `owned` — the field cannot hold `unknown` at all. Reusing that type here would
+ * have meant one of two untruths: either the call becomes gated on ownership,
+ * which refuses Codex injection on every Windows machine and on Linux without a
+ * reachable user bus, or a hand-built snapshot claims an admission that never
+ * happened.
+ *
+ * So this type authorizes THE WRITE, not the DECISION to write. Deciding whether
+ * a write should happen at all is admission's job and belongs to its own phase,
+ * behind the Windows definition-chain walk.
+ *
+ * What the id covers, and why it is the OUTPUT rather than the inputs: the bytes
+ * `injectCodexConfig` emits depend on the port, the resolved catalog path, the
+ * hostname, websocket mode, legacy mode and the managed sub-agent defaults. An
+ * enumeration of those was already incomplete once. Hashing the computed
+ * candidate bytes closes the class instead of the instance — an input that
+ * changes the output changes the id whether or not anyone remembered to list it.
+ */
+import { createHash } from "node:crypto";
+
+export interface CodexWriteCandidate {
+  /** The exact string about to replace `config.toml`. */
+  readonly configBytes: string;
+  /** The exact string about to replace the profile. */
+  readonly profileBytes: string;
+  /** The RESOLVED catalog path, never the raw option. */
+  readonly catalogPath: string | null;
+}
+
+export interface CodexWriteEvidence {
+  /** sha256 of the `config.toml` bytes this operation read as its input. */
+  readonly nativeInputIdentity: string;
+  /** Digest of the persisted Remodex config these bytes were derived from. */
+  readonly persistedIdentity: string;
+  /** Generation as observed before the lock; `present:false` means no coordinator yet. */
+  readonly generation: Readonly<{ present: boolean; value: number }>;
+  /** Content identity of the journal, or a stable marker for absence. */
+  readonly journalIdentity: string;
+  readonly canonicalTargets: Readonly<{
+    config: string;
+    profile: string;
+    journal: string;
+  }>;
+}
+
+export interface CodexWriteCoordination {
+  readonly candidate: CodexWriteCandidate;
+  readonly evidence: CodexWriteEvidence;
+  /**
+   * Recorded context, deliberately OUTSIDE `comparisonId`.
+   *
+   * The lock compares one id and nothing else, so a field that is copied rather
+   * than re-observed detects no drift by being in it — it would only match
+   * itself. Ownership is not re-observed under the lock (that would mean running
+   * a service-manager subprocess while N and C are held), so it travels as
+   * something the operation SAW, not as something the comparison PROVES.
+   */
+  readonly observedOwnership: "owned" | "foreign" | "unknown";
+  readonly comparisonId: string;
+}
+
+/**
+ * Collapse a generation to one token.
+ *
+ * Absent and present-zero are the same authority — no cooperating write has
+ * committed — and they cannot be observed the same way: before the lock only
+ * absence is visible, and inside it only the committed zero is. Without this
+ * they never match and every first write refuses.
+ */
+function generationToken(generation: CodexWriteEvidence["generation"]): string {
+  const { present, value } = generation;
+  if (!Number.isSafeInteger(value) || value < 0) {
+    throw new TypeError(`A config generation must be a non-negative safe integer, got ${String(value)}.`);
+  }
+  return present && value > 0 ? `gen:${value}` : "gen:0";
+}
+
+export function hashCodexWriteCoordination(
+  candidate: CodexWriteCandidate,
+  evidence: CodexWriteEvidence,
+): string {
+  return createHash("sha256")
+    .update(JSON.stringify([
+      // The output, hashed directly. Two operations that intend different bytes
+      // cannot share an id, however they came to differ.
+      createHash("sha256").update(candidate.configBytes).digest("hex"),
+      createHash("sha256").update(candidate.profileBytes).digest("hex"),
+      candidate.catalogPath,
+      evidence.nativeInputIdentity,
+      evidence.persistedIdentity,
+      generationToken(evidence.generation),
+      evidence.journalIdentity,
+      evidence.canonicalTargets,
+    ]))
+    .digest("hex");
+}
+
+export function codexWriteCoordination(
+  candidate: CodexWriteCandidate,
+  evidence: CodexWriteEvidence,
+  observedOwnership: CodexWriteCoordination["observedOwnership"],
+): CodexWriteCoordination {
+  return {
+    candidate,
+    evidence,
+    observedOwnership,
+    comparisonId: hashCodexWriteCoordination(candidate, evidence),
+  };
+}

package/src/combos/failover.ts

@@ -0,0 +1,140 @@
+import { classifyError, isCyberPolicyCode } from "../lib/errors";
+import type { OcxComboTarget } from "../types";
+import { targetKey } from "./types";
+import {
+  captureConfigGeneration,
+  sweepExpiredOnWrite,
+  type GenerationContext,
+} from "../lib/state-store-sweeper";
+
+interface TargetCooldown {
+  cooldownUntil: number;
+}
+
+const DEFAULT_COOLDOWN_MS = 60_000;
+const MAX_COOLDOWN_MS = 10 * 60_000;
+
+/** Map<`${comboId}\0${provider/model}`, TargetCooldown> */
+const targetCooldowns = new Map<string, TargetCooldown>();
+let lastReconciledGeneration = 0;
+let liveComboTargets = new Set<string>();
+
+function cooldownMapKey(
+  comboId: string,
+  target: Pick<OcxComboTarget, "provider" | "model">,
+): string {
+  return `${comboId}\0${targetKey(target)}`;
+}
+
+export function parseRetryAfterMs(
+  value: string | null | undefined,
+  now = Date.now(),
+): number | undefined {
+  const text = value?.trim();
+  if (!text) return undefined;
+  if (/^\d+(?:\.\d+)?$/.test(text)) {
+    const seconds = Number(text);
+    if (Number.isFinite(seconds) && seconds > 0) {
+      return Math.min(Math.max(Math.ceil(seconds * 1000), 1), MAX_COOLDOWN_MS);
+    }
+  }
+  const timestamp = Date.parse(text);
+  if (!Number.isFinite(timestamp)) return undefined;
+  const delay = timestamp - now;
+  return delay > 0 ? Math.min(delay, MAX_COOLDOWN_MS) : undefined;
+}
+
+export function isComboTargetInCooldown(
+  comboId: string,
+  target: Pick<OcxComboTarget, "provider" | "model">,
+  now = Date.now(),
+): boolean {
+  const key = cooldownMapKey(comboId, target);
+  const entry = targetCooldowns.get(key);
+  if (!entry) return false;
+  if (entry.cooldownUntil <= now) {
+    targetCooldowns.delete(key);
+    return false;
+  }
+  return true;
+}
+
+export function coolComboTarget(
+  comboId: string,
+  target: Pick<OcxComboTarget, "provider" | "model">,
+  options?: { retryAfter?: string | null; now?: number; cooldownMs?: number; writerGeneration?: number },
+): void {
+  const now = options?.now ?? Date.now();
+  const writerGeneration = options?.writerGeneration ?? captureConfigGeneration();
+  const ownerKey = `${comboId}::${targetKey(target)}`;
+  if (writerGeneration < lastReconciledGeneration && !liveComboTargets.has(ownerKey)) return;
+  const cooldownMs = options?.cooldownMs
+    ?? parseRetryAfterMs(options?.retryAfter, now)
+    ?? DEFAULT_COOLDOWN_MS;
+  targetCooldowns.set(cooldownMapKey(comboId, target), {
+    cooldownUntil: now + Math.min(Math.max(cooldownMs, 1), MAX_COOLDOWN_MS),
+  });
+  sweepExpiredOnWrite(now);
+}
+
+export function reconcileComboTargetCooldowns(context: GenerationContext): number {
+  if (context.generation <= lastReconciledGeneration) return 0;
+  liveComboTargets = new Set(context.comboTargets);
+  lastReconciledGeneration = context.generation;
+  return 0;
+}
+
+export function sweepExpiredComboTargetCooldowns(now = Date.now()): number {
+  let removed = 0;
+  for (const [key, cooldown] of targetCooldowns) {
+    if (cooldown.cooldownUntil > now) continue;
+    targetCooldowns.delete(key);
+    removed += 1;
+  }
+  return removed;
+}
+
+export function clearComboTargetCooldowns(comboId?: string): void {
+  if (comboId === undefined) {
+    targetCooldowns.clear();
+    liveComboTargets.clear();
+    lastReconciledGeneration = 0;
+    return;
+  }
+  const prefix = `${comboId}\0`;
+  for (const key of targetCooldowns.keys()) {
+    if (key.startsWith(prefix)) targetCooldowns.delete(key);
+  }
+}
+
+export type ComboFailureDecision = "hop" | "stop";
+
+export function comboFailureDecision(
+  status: number,
+  message: string,
+  options?: { code?: string | null },
+): ComboFailureDecision {
+  if (status === 499) return "stop";
+  if (message.toLowerCase().includes("origin_rejected")) return "stop";
+  // Cyber policy is a hard non-retryable refusal — honor structured code even when
+  // classificationText was truncated before the JSON code field.
+  if (isCyberPolicyCode(options?.code)) return "stop";
+  const error = classifyError(status, "upstream_error", message);
+  if (isCyberPolicyCode(error.code)) return "stop";
+  if (["origin_rejected", "context_length_exceeded", "invalid_request_error"].includes(error.code ?? "")) {
+    return "stop";
+  }
+  if ([401, 403, 404, 408, 429].includes(status) || status >= 500) return "hop";
+  if ([
+    "permission_denied",
+    "subscription_required",
+    "invalid_api_key",
+    "insufficient_quota",
+    "rate_limit_exceeded",
+    "server_is_overloaded",
+    "upstream_server_error",
+  ].includes(error.code ?? "")) {
+    return "hop";
+  }
+  return "stop";
+}

package/src/combos/index.ts

@@ -0,0 +1,44 @@
+export {
+  COMBO_NAMESPACE,
+  comboAliasIssues,
+  comboConfigError,
+  comboConfigIssues,
+  comboDefaultEffort,
+  comboDisabledModelId,
+  comboDisabledModelSelectors,
+  comboModelId,
+  comboPublicModelId,
+  getCombo,
+  isNativeAliasCombo,
+  isValidComboId,
+  listComboIds,
+  normalizeComboConfig,
+  parseComboModelId,
+  preservesPhysicalComboProvider,
+  resolveComboId,
+  targetKey,
+} from "./types";
+export {
+  advanceComboAfterFailure,
+  clearComboSelectionState,
+  NoAvailableComboTargetsError,
+  noteComboFailure,
+  noteComboSuccess,
+  pickComboTarget,
+  tryPickComboModel,
+  UnknownComboError,
+  type ComboPick,
+} from "./resolve";
+export {
+  clearComboTargetCooldowns,
+  coolComboTarget,
+  isComboTargetInCooldown,
+  parseRetryAfterMs,
+  comboFailureDecision,
+  type ComboFailureDecision,
+} from "./failover";
+export {
+  comboIdFromRawBody,
+  concreteComboRequestBody,
+  resetComboEffortWarningStateForTests,
+} from "./request";

package/src/combos/request.ts

@@ -0,0 +1,64 @@
+import type { OcxComboDefaultEffort, OcxComboTarget, OcxConfig } from "../types";
+import { resolveComboId } from "./types";
+
+const warnedUnsupportedDefaults = new Set<string>();
+let lastWarningReconciledGeneration = 0;
+
+export function reconcileComboWarningMemos(generation: number): number {
+  if (generation <= lastWarningReconciledGeneration) return 0;
+  const removed = warnedUnsupportedDefaults.size;
+  warnedUnsupportedDefaults.clear();
+  lastWarningReconciledGeneration = generation;
+  return removed;
+}
+
+export function resetComboEffortWarningStateForTests(): void {
+  warnedUnsupportedDefaults.clear();
+}
+
+export function comboIdFromRawBody(body: unknown, config: OcxConfig): string | null {
+  if (!body || typeof body !== "object" || Array.isArray(body)) return null;
+  const model = (body as { model?: unknown }).model;
+  if (typeof model !== "string") return null;
+  return resolveComboId(config, model);
+}
+
+export function concreteComboRequestBody(
+  body: unknown,
+  target: Pick<OcxComboTarget, "provider" | "model">,
+  defaultEffort: OcxComboDefaultEffort | null,
+  targetReasoningEfforts: readonly string[] | undefined,
+): Record<string, unknown> {
+  const clone = structuredClone(body) as Record<string, unknown>;
+  clone.model = `${target.provider}/${target.model}`;
+  if (!defaultEffort) return clone;
+  const reasoning = clone.reasoning;
+  const needsDefault = reasoning === undefined || (
+    reasoning
+    && typeof reasoning === "object"
+    && !Array.isArray(reasoning)
+    && !Object.prototype.hasOwnProperty.call(reasoning, "effort")
+  );
+  if (!needsDefault) return clone;
+  // Both picker availability and runtime injection stay fail-closed until this concrete target
+  // advertises support. Keep the request guard even if an older dashboard saved a stale default.
+  if (!targetReasoningEfforts?.includes(defaultEffort)) {
+    const key = `${target.provider}/${target.model}:${defaultEffort}`;
+    if (!warnedUnsupportedDefaults.has(key)) {
+      warnedUnsupportedDefaults.add(key);
+      console.debug("[Remodex] combo default effort omitted", {
+        provider: target.provider,
+        model: target.model,
+        requestedEffort: defaultEffort,
+        capability: targetReasoningEfforts === undefined ? "unknown" : "unsupported",
+      });
+    }
+    return clone;
+  }
+  if (reasoning === undefined) {
+    clone.reasoning = { effort: defaultEffort };
+  } else {
+    clone.reasoning = { ...(reasoning as Record<string, unknown>), effort: defaultEffort };
+  }
+  return clone;
+}

package/src/combos/resolve.ts

@@ -0,0 +1,232 @@
+import type { OcxComboTarget, OcxConfig } from "../types";
+import { coolComboTarget, isComboTargetInCooldown } from "./failover";
+import { getCombo, resolveComboId, targetKey } from "./types";
+import type { NormalizedComboConfig } from "./types";
+import {
+  captureConfigGeneration,
+  type GenerationContext,
+} from "../lib/state-store-sweeper";
+
+export interface ComboPick {
+  comboId: string;
+  target: Required<OcxComboTarget>;
+  targetIndex: number;
+  attempted: string[];
+  writerGeneration: number;
+}
+
+interface SelectionState {
+  activeKey?: string;
+  successes: number;
+  currentWeights: Map<string, number>;
+}
+
+const selectionState = new Map<string, SelectionState>();
+let lastReconciledGeneration = 0;
+let liveComboTargets = new Set<string>();
+
+function comboTargetOwnerKey(comboId: string, key: string): string {
+  return `${comboId}::${key}`;
+}
+
+function mayCommitComboState(comboId: string, key: string, writerGeneration: number): boolean {
+  return writerGeneration >= lastReconciledGeneration
+    || liveComboTargets.has(comboTargetOwnerKey(comboId, key));
+}
+
+export class UnknownComboError extends Error {
+  constructor(readonly comboId: string) {
+    super(`Unknown combo: ${comboId}`);
+    this.name = "UnknownComboError";
+  }
+}
+
+export class NoAvailableComboTargetsError extends Error {
+  readonly code = "combo_unavailable";
+
+  constructor(readonly comboId: string) {
+    super(`No available targets for combo: ${comboId}`);
+    this.name = "NoAvailableComboTargetsError";
+  }
+}
+
+function targetProviderIsUsable(config: OcxConfig, target: OcxComboTarget): boolean {
+  return Object.hasOwn(config.providers, target.provider)
+    && config.providers[target.provider]?.disabled !== true;
+}
+
+function smoothWeightedIndex(
+  targets: Required<OcxComboTarget>[],
+  state: SelectionState,
+  eligible: (target: Required<OcxComboTarget>) => boolean,
+): number {
+  let best = -1;
+  let bestScore = Number.NEGATIVE_INFINITY;
+  let total = 0;
+  for (let i = 0; i < targets.length; i++) {
+    const target = targets[i]!;
+    if (!eligible(target)) continue;
+    const key = targetKey(target);
+    const score = (state.currentWeights.get(key) ?? 0) + target.weight;
+    state.currentWeights.set(key, score);
+    total += target.weight;
+    if (score > bestScore) {
+      best = i;
+      bestScore = score;
+    }
+  }
+  if (best >= 0) {
+    const key = targetKey(targets[best]!);
+    state.currentWeights.set(key, (state.currentWeights.get(key) ?? 0) - total);
+  }
+  return best;
+}
+
+export function pickComboTarget(
+  config: OcxConfig,
+  comboId: string,
+  options: {
+    exclude?: Iterable<string>;
+    eligible?: (target: Required<OcxComboTarget>) => boolean;
+  } = {},
+): ComboPick | null {
+  const writerGeneration = captureConfigGeneration();
+  const combo = getCombo(config, comboId);
+  if (!combo) throw new UnknownComboError(comboId);
+  const excluded = new Set(options.exclude ?? []);
+  const eligible = (target: Required<OcxComboTarget>): boolean =>
+    targetProviderIsUsable(config, target)
+    && !excluded.has(targetKey(target))
+    && (options.eligible?.(target) ?? true);
+
+  let targetIndex = -1;
+  if (combo.strategy === "round-robin") {
+    let state = selectionState.get(comboId);
+    if (!state) {
+      state = { successes: 0, currentWeights: new Map() };
+      selectionState.set(comboId, state);
+    }
+    if (state.activeKey) {
+      targetIndex = combo.targets.findIndex(target => targetKey(target) === state.activeKey && eligible(target));
+      if (targetIndex < 0) {
+        delete state.activeKey;
+        state.successes = 0;
+      }
+    }
+    if (targetIndex < 0) {
+      targetIndex = smoothWeightedIndex(combo.targets, state, eligible);
+      if (targetIndex >= 0) {
+        state.activeKey = targetKey(combo.targets[targetIndex]!);
+        state.successes = 0;
+      }
+    }
+  } else {
+    targetIndex = combo.targets.findIndex(eligible);
+  }
+
+  if (targetIndex < 0) return null;
+  const target = combo.targets[targetIndex]!;
+  return {
+    comboId,
+    target,
+    targetIndex,
+    attempted: [...excluded, targetKey(target)],
+    writerGeneration,
+  };
+}
+
+export function noteComboSuccess(
+  comboId: string,
+  combo: NormalizedComboConfig,
+  target: Required<OcxComboTarget>,
+  writerGeneration = captureConfigGeneration(),
+): void {
+  if (combo.strategy !== "round-robin") return;
+  const key = targetKey(target);
+  if (!mayCommitComboState(comboId, key, writerGeneration)) return;
+  const state = selectionState.get(comboId);
+  if (!state || state.activeKey !== key) return;
+  state.successes += 1;
+  if (state.successes >= combo.stickyLimit) {
+    delete state.activeKey;
+    state.successes = 0;
+  }
+}
+
+export function noteComboFailure(
+  comboId: string,
+  target: OcxComboTarget,
+  writerGeneration = captureConfigGeneration(),
+): void {
+  if (!mayCommitComboState(comboId, targetKey(target), writerGeneration)) return;
+  const state = selectionState.get(comboId);
+  if (state?.activeKey === targetKey(target)) {
+    delete state.activeKey;
+    state.successes = 0;
+  }
+}
+
+export function advanceComboAfterFailure(
+  config: OcxConfig,
+  pick: ComboPick,
+  options: {
+    retryAfter?: string | null;
+    now?: number;
+    eligible?: (target: Required<OcxComboTarget>) => boolean;
+  } = {},
+): ComboPick | null {
+  noteComboFailure(pick.comboId, pick.target, pick.writerGeneration);
+  coolComboTarget(pick.comboId, pick.target, {
+    ...options,
+    writerGeneration: pick.writerGeneration,
+  });
+  return pickComboTarget(config, pick.comboId, {
+    exclude: pick.attempted,
+    eligible: target => !isComboTargetInCooldown(pick.comboId, target, options.now)
+      && (options.eligible?.(target) ?? true),
+  });
+}
+
+export function reconcileComboRotationState(context: GenerationContext): number {
+  if (context.generation <= lastReconciledGeneration) return 0;
+  let removed = 0;
+  for (const [comboId, state] of selectionState) {
+    if (!context.comboIds.has(comboId)) {
+      selectionState.delete(comboId);
+      removed += 1;
+      continue;
+    }
+    if (state.activeKey && !context.comboTargets.has(comboTargetOwnerKey(comboId, state.activeKey))) {
+      delete state.activeKey;
+      state.successes = 0;
+      removed += 1;
+    }
+    for (const key of state.currentWeights.keys()) {
+      if (context.comboTargets.has(comboTargetOwnerKey(comboId, key))) continue;
+      state.currentWeights.delete(key);
+      removed += 1;
+    }
+  }
+  liveComboTargets = new Set(context.comboTargets);
+  lastReconciledGeneration = context.generation;
+  return removed;
+}
+
+export function clearComboSelectionState(comboId?: string): void {
+  if (comboId === undefined) {
+    selectionState.clear();
+    liveComboTargets.clear();
+    lastReconciledGeneration = 0;
+    return;
+  }
+  selectionState.delete(comboId);
+}
+
+export function tryPickComboModel(config: OcxConfig, modelId: string): ComboPick | null {
+  const comboId = resolveComboId(config, modelId);
+  if (!comboId) return null;
+  if (!getCombo(config, comboId)) throw new UnknownComboError(comboId);
+  const picked = pickComboTarget(config, comboId);
+  if (!picked) throw new NoAvailableComboTargetsError(comboId);
+  return picked;
+}