@triflux/core 10.50.2 → 10.51.0

package/hub/routing-snapshot.mjs

@@ -1,261 +0,0 @@
-// hub/routing-snapshot.mjs
-//
-// PRD: .omx/plans/prd-dynamic-routing-engine.md
-//
-// Phase 0 — pure read-only context projector. Wraps HUD providers and the
-// AccountBroker public snapshot into a single deterministic snapshot that
-// `evaluateDynamicRoute(request, snapshot, policy)` consumes.
-//
-// Phase 0 contract:
-//   - no callers yet (dormant). Only `evaluateDynamicRoute()` is meant to read this.
-//   - lazy import of HUD providers + broker so this module imports cleanly even
-//     when those surfaces are absent in tests.
-//   - never mutates upstream state — strictly read-only.
-//   - all output fields are derivable from `publicSnapshot()` / HUD redacted API,
-//     so writing the resulting snapshot to disk does not leak credentials.
-
-const CLAUDE_HUD_MODULE = "../hud/providers/claude.mjs";
-const CODEX_HUD_MODULE = "../hud/providers/codex.mjs";
-const BROKER_MODULE = "./account-broker.mjs";
-
-async function loadHudClaude() {
-  try {
-    return await import(CLAUDE_HUD_MODULE);
-  } catch {
-    return null;
-  }
-}
-
-async function loadHudCodex() {
-  try {
-    return await import(CODEX_HUD_MODULE);
-  } catch {
-    return null;
-  }
-}
-
-async function loadBroker() {
-  try {
-    const mod = await import(BROKER_MODULE);
-    return mod.broker ?? mod.default ?? null;
-  } catch {
-    return null;
-  }
-}
-
-function normalizeClaudeUsage(raw, now) {
-  if (!raw || typeof raw !== "object") return null;
-  const data = raw.data ?? raw;
-  if (!data) return null;
-  return {
-    fiveHourPercent: numericOrNull(data.fiveHourPercent),
-    weeklyPercent: numericOrNull(data.weeklyPercent),
-    fiveHourResetsAt: toEpoch(data.fiveHourResetsAt),
-    weeklyResetsAt: toEpoch(data.weeklyResetsAt),
-    observedAt: toEpoch(data.observedAt) ?? now,
-    isStale: Boolean(raw.isStale ?? data.isStale),
-    source: data.source ?? "hud/providers/claude.mjs",
-  };
-}
-
-function normalizeCodexUsage(raw, now) {
-  if (!raw || typeof raw !== "object") return null;
-  const buckets = raw.buckets ?? raw.data?.buckets ?? raw;
-  if (!buckets || typeof buckets !== "object") return null;
-  const entries = Object.entries(buckets);
-  if (entries.length === 0) return null;
-  const out = {};
-  for (const [id, bucket] of entries) {
-    if (!bucket || typeof bucket !== "object") continue;
-    out[id] = {
-      primary: normalizeCodexBucketLeg(bucket.primary),
-      secondary: normalizeCodexBucketLeg(bucket.secondary),
-    };
-  }
-  return {
-    buckets: out,
-    observedAt: toEpoch(raw.observedAt) ?? now,
-    isStale: Boolean(raw.shouldRefresh === false ? false : raw.isStale),
-    source: raw.source ?? "hud/providers/codex.mjs",
-  };
-}
-
-function normalizeCodexBucketLeg(leg) {
-  if (!leg || typeof leg !== "object") return null;
-  return {
-    usedPercent: numericOrNull(leg.used_percent ?? leg.usedPercent),
-    resetsAt: toEpoch(leg.resets_at ?? leg.resetsAt),
-  };
-}
-
-function normalizeBrokerSnapshot(raw) {
-  if (!Array.isArray(raw)) return null;
-  const grouped = { codex: [], claude: [], gemini: [] };
-  for (const entry of raw) {
-    if (!entry || typeof entry !== "object") continue;
-    const provider = entry.provider;
-    if (!grouped[provider]) continue;
-    grouped[provider].push({
-      id: entry.id,
-      tier: entry.tier ?? "unknown",
-      busy: Boolean(entry.busy),
-      cooldownUntil: toEpoch(entry.cooldownUntil),
-      lastUsedAt: toEpoch(entry.lastUsedAt),
-      remainingMs: numericOrNull(entry.remainingMs),
-      circuitState: entry.circuitState ?? "closed",
-      failureCount: numericOrNull(entry.failureCount) ?? 0,
-      expiresAt: toEpoch(entry.expiresAt),
-      drainAfter: toEpoch(entry.drainAfter),
-    });
-  }
-  return grouped;
-}
-
-function numericOrNull(v) {
-  if (v === null || v === undefined) return null;
-  const n = Number(v);
-  return Number.isFinite(n) ? n : null;
-}
-
-function toEpoch(v) {
-  if (v === null || v === undefined) return null;
-  if (typeof v === "number") return Number.isFinite(v) ? v : null;
-  const parsed = Date.parse(v);
-  return Number.isNaN(parsed) ? null : parsed;
-}
-
-export async function buildRoutingSnapshot({
-  forceRefresh = false,
-  now = Date.now(),
-} = {}) {
-  const [hudClaude, hudCodex, broker] = await Promise.all([
-    loadHudClaude(),
-    loadHudCodex(),
-    loadBroker(),
-  ]);
-
-  let claude = null;
-  if (hudClaude?.readClaudeUsageSnapshot) {
-    try {
-      claude = normalizeClaudeUsage(
-        hudClaude.readClaudeUsageSnapshot({ forceRefresh }),
-        now,
-      );
-    } catch (err) {
-      claude = {
-        error: String(err?.message ?? err),
-        observedAt: now,
-        isStale: true,
-      };
-    }
-  }
-
-  let codex = null;
-  if (hudCodex?.readCodexRateLimitSnapshot) {
-    try {
-      codex = normalizeCodexUsage(
-        hudCodex.readCodexRateLimitSnapshot({ forceRefresh }),
-        now,
-      );
-    } catch (err) {
-      codex = {
-        error: String(err?.message ?? err),
-        observedAt: now,
-        isStale: true,
-      };
-    }
-  }
-
-  let brokerState = null;
-  if (broker?.publicSnapshot) {
-    try {
-      brokerState = normalizeBrokerSnapshot(broker.publicSnapshot());
-    } catch (err) {
-      brokerState = { error: String(err?.message ?? err) };
-    }
-  }
-
-  return {
-    schemaVersion: 1,
-    observedAt: now,
-    claude,
-    codex,
-    broker: brokerState,
-  };
-}
-
-// Phase 1 — in-process snapshot cache.
-// 의도: caller (Phase 1+ conductor / swarm-hypervisor) 가 spawn loop 에서
-// 매번 HUD/broker IO 를 트리거하지 않도록 정해진 TTL 안에서 같은 snapshot
-// 을 재사용한다. cache 는 모듈-local 이라 process 단위 (테스트 격리 위해
-// `resetSnapshotCache()` 노출).
-
-const DEFAULT_CACHE_TTL_MS = 900_000; // policy freshness max 와 정합
-
-let _cache = null; // { snapshot, fetchedAt }
-
-export function resetSnapshotCache() {
-  _cache = null;
-}
-
-/**
- * Cached snapshot shortcut. cache TTL 안이면 재사용, 아니면 새로 빌드.
- *
- * @param {{
- *   forceRefresh?: boolean,        // true 면 cache 무시하고 새로 빌드
- *   maxAgeMs?: number,             // override cache TTL (default 900_000)
- *   now?: number,                  // pure-fn: caller 가 epoch 주입 (default Date.now())
- *   builder?: function,            // 테스트용 builder 주입 (default buildRoutingSnapshot)
- * }} [opts]
- * @returns {Promise<object>}
- */
-export async function getDefaultSnapshot(opts = {}) {
-  const now = typeof opts.now === "number" ? opts.now : Date.now();
-  const maxAgeMs =
-    typeof opts.maxAgeMs === "number" ? opts.maxAgeMs : DEFAULT_CACHE_TTL_MS;
-  const builder = opts.builder || buildRoutingSnapshot;
-  const forceRefresh = Boolean(opts.forceRefresh);
-
-  if (!forceRefresh && _cache && now - _cache.fetchedAt < maxAgeMs) {
-    return _cache.snapshot;
-  }
-
-  const snapshot = await builder({ forceRefresh, now });
-  _cache = { snapshot, fetchedAt: now };
-  return snapshot;
-}
-
-/**
- * Synchronous cache shortcut. cache TTL 안에 fresh snapshot이 있으면 즉시 반환,
- * 아니면 null. caller (sync hot path — e.g. conductor.spawnSession) 가 broker.lease
- * atomic 인변량을 깨지 않고 dynamic routing decision 을 sync 로 평가할 수 있도록 한다.
- * builder 호출(IO)은 하지 않는다 — cache miss 면 caller 가 fallback decision 사용.
- *
- * @param {{
- *   maxAgeMs?: number,             // override cache TTL (default 900_000)
- *   now?: number,                  // pure-fn: caller 가 epoch 주입 (default Date.now())
- * }} [opts]
- * @returns {object|null} cache fresh이면 snapshot, 아니면 null
- */
-export function tryGetCachedSnapshot(opts = {}) {
-  const now = typeof opts.now === "number" ? opts.now : Date.now();
-  const maxAgeMs =
-    typeof opts.maxAgeMs === "number" ? opts.maxAgeMs : DEFAULT_CACHE_TTL_MS;
-  if (_cache && now - _cache.fetchedAt < maxAgeMs) {
-    return _cache.snapshot;
-  }
-  return null;
-}
-
-// Test helpers — pure normalizers exposed so unit tests can build snapshots
-// from mock provider responses without running real HUD I/O.
-export const __internal__ = {
-  normalizeClaudeUsage,
-  normalizeCodexUsage,
-  normalizeBrokerSnapshot,
-  // Phase 1 cache 테스트 helpers
-  getCacheStateForTest: () => (_cache ? { ..._cache } : null),
-  setCacheForTest: (state) => {
-    _cache = state ? { ...state } : null;
-  },
-};

package/mesh/index.mjs

@@ -1,69 +0,0 @@
-import { readdirSync } from "node:fs";
-import { join } from "node:path";
-
-export { createMeshBudget } from "./mesh-budget.mjs";
-export { createHeartbeatMonitor } from "./mesh-heartbeat.mjs";
-export {
-  createMessage,
-  deserialize,
-  MSG_TYPES,
-  serialize,
-  validate,
-} from "./mesh-protocol.mjs";
-export { createMessageQueue } from "./mesh-queue.mjs";
-export { createRegistry } from "./mesh-registry.mjs";
-export { routeMessage, routeOrDeadLetter } from "./mesh-router.mjs";
-
-/**
- * Loads skills assigned to a specific agent from a skills directory.
- * Reuses the same directory-scan approach as generateSkillDocs().
- *
- * @param {string} agentId - The agent identifier
- * @param {string} skillsDir - Path to the skills directory
- * @returns {Promise<string[]>} Array of skill names available to this agent
- */
-export async function loadSkillsForAgent(agentId, skillsDir) {
-  if (!agentId || typeof agentId !== "string") {
-    throw new TypeError("agentId must be a non-empty string");
-  }
-  if (!skillsDir || typeof skillsDir !== "string") {
-    throw new TypeError("skillsDir must be a non-empty string");
-  }
-
-  let entries;
-  try {
-    entries = readdirSync(skillsDir, { withFileTypes: true });
-  } catch {
-    return [];
-  }
-
-  const skills = [];
-  for (const entry of entries) {
-    if (!entry.isDirectory()) continue;
-    const skillName = entry.name;
-    const skillPath = join(skillsDir, skillName, "SKILL.md");
-    let skillContent = null;
-    try {
-      const { readFileSync } = await import("node:fs");
-      skillContent = readFileSync(skillPath, "utf8");
-    } catch {
-      // Skill has no SKILL.md — include it anyway
-    }
-
-    // If SKILL.md mentions the agentId or no agent restriction, include it
-    const isRestricted = skillContent
-      ? /^agents?\s*:/im.test(skillContent)
-      : false;
-
-    if (!isRestricted) {
-      skills.push(skillName);
-      continue;
-    }
-
-    if (skillContent?.includes(agentId)) {
-      skills.push(skillName);
-    }
-  }
-
-  return skills;
-}

package/mesh/mesh-budget.mjs

@@ -1,137 +0,0 @@
-/**
- * Warning level thresholds mirroring context-monitor.mjs classifyContextThreshold().
- * Reproduced here to avoid cross-module dependency.
- */
-const WARNING_LEVELS = Object.freeze({
-  critical: 90,
-  warn: 80,
-  info: 60,
-  ok: 0,
-});
-
-/**
- * Clamps a percentage value to [0, 100].
- * @param {number} value
- * @returns {number}
- */
-function clampPercent(value) {
-  const n = Number(value);
-  if (!Number.isFinite(n)) return 0;
-  return Math.min(100, Math.max(0, n));
-}
-
-/**
- * Classifies a usage percentage into a warning level.
- * Mirrors context-monitor.mjs classifyContextThreshold().
- * @param {number} percent
- * @returns {{ level: string, message: string }}
- */
-function classifyLevel(percent) {
-  const p = clampPercent(percent);
-  if (p >= WARNING_LEVELS.critical)
-    return { level: "critical", message: "에이전트 분할 또는 세션 교체 권장" };
-  if (p >= WARNING_LEVELS.warn) return { level: "warn", message: "압축 권장" };
-  if (p >= WARNING_LEVELS.info)
-    return { level: "info", message: "컨텍스트 절반 이상 사용" };
-  return { level: "ok", message: "" };
-}
-
-/**
- * Creates a per-agent token budget manager.
- * @returns {object} Budget API
- */
-export function createMeshBudget() {
-  // Map<agentId, { allocated: number, consumed: number }>
-  const budgets = new Map();
-
-  /**
-   * Allocates a token budget to an agent.
-   * @param {string} agentId
-   * @param {number} tokenLimit
-   */
-  function allocate(agentId, tokenLimit) {
-    if (!agentId || typeof agentId !== "string") {
-      throw new TypeError("agentId must be a non-empty string");
-    }
-    const limit = Math.max(0, Math.round(Number(tokenLimit) || 0));
-    const existing = budgets.get(agentId);
-    budgets.set(agentId, {
-      allocated: limit,
-      consumed: existing?.consumed ?? 0,
-    });
-  }
-
-  /**
-   * Records token consumption for an agent.
-   * @param {string} agentId
-   * @param {number} tokens
-   * @returns {{ remaining: number, percent: number, level: string }}
-   */
-  function consume(agentId, tokens) {
-    const budget = budgets.get(agentId);
-    if (!budget) {
-      throw new Error(`No budget allocated for agent: ${agentId}`);
-    }
-    const amount = Math.max(0, Math.round(Number(tokens) || 0));
-    const updated = {
-      allocated: budget.allocated,
-      consumed: budget.consumed + amount,
-    };
-    budgets.set(agentId, updated);
-
-    const remaining = Math.max(0, updated.allocated - updated.consumed);
-    const percent =
-      updated.allocated > 0
-        ? clampPercent((updated.consumed / updated.allocated) * 100)
-        : 100;
-    const { level } = classifyLevel(percent);
-    return { remaining, percent, level };
-  }
-
-  /**
-   * Returns the budget status for an agent.
-   * @param {string} agentId
-   * @returns {{ allocated: number, consumed: number, remaining: number, level: string }}
-   */
-  function getStatus(agentId) {
-    const budget = budgets.get(agentId);
-    if (!budget) {
-      return { allocated: 0, consumed: 0, remaining: 0, level: "ok" };
-    }
-    const remaining = Math.max(0, budget.allocated - budget.consumed);
-    const percent =
-      budget.allocated > 0
-        ? clampPercent((budget.consumed / budget.allocated) * 100)
-        : 0;
-    const { level } = classifyLevel(percent);
-    return {
-      allocated: budget.allocated,
-      consumed: budget.consumed,
-      remaining,
-      level,
-    };
-  }
-
-  /**
-   * Resets consumed tokens for all agents (keeps allocations).
-   */
-  function resetAll() {
-    for (const [agentId, budget] of budgets) {
-      budgets.set(agentId, { allocated: budget.allocated, consumed: 0 });
-    }
-  }
-
-  /**
-   * Returns a snapshot of all current allocations.
-   * @returns {Map<string, { allocated: number, consumed: number }>}
-   */
-  function listAllocations() {
-    const snap = new Map();
-    for (const [id, b] of budgets) {
-      snap.set(id, Object.freeze({ ...b }));
-    }
-    return snap;
-  }
-
-  return { allocate, consume, getStatus, resetAll, listAllocations };
-}

package/mesh/mesh-heartbeat.mjs

@@ -1,100 +0,0 @@
-const DEFAULT_INTERVAL_MS = 30_000;
-const DEFAULT_THRESHOLD_MS = 60_000;
-
-/**
- * Creates a heartbeat monitor that tracks agent liveness.
- *
- * @param {object} registry - A mesh-registry instance
- * @param {object} [opts]
- * @param {number} [opts.intervalMs=30000]   - Scan interval
- * @param {number} [opts.thresholdMs=60000]  - Stale threshold
- * @param {function} [opts.onStale]          - Called with agentId when stale detected
- * @returns {object} HeartbeatMonitor API
- */
-export function createHeartbeatMonitor(registry, opts = {}) {
-  const {
-    intervalMs = DEFAULT_INTERVAL_MS,
-    thresholdMs = DEFAULT_THRESHOLD_MS,
-    onStale,
-  } = opts;
-
-  /** @type {Map<string, number>} agentId → last heartbeat timestamp */
-  const heartbeats = new Map();
-  let timer = null;
-
-  /**
-   * Records a heartbeat for an agent.
-   * @param {string} agentId
-   */
-  function recordHeartbeat(agentId) {
-    if (!agentId || typeof agentId !== "string") {
-      throw new TypeError("agentId must be a non-empty string");
-    }
-    heartbeats.set(agentId, Date.now());
-  }
-
-  /**
-   * Returns agent IDs whose last heartbeat exceeds the threshold.
-   * Only considers agents currently registered in the registry.
-   *
-   * @param {number} [customThresholdMs] - Override default threshold
-   * @returns {string[]}
-   */
-  function getStaleAgents(customThresholdMs) {
-    const threshold = customThresholdMs ?? thresholdMs;
-    const now = Date.now();
-    const registered = registry.listAll();
-    const stale = [];
-
-    for (const agent of registered) {
-      const lastBeat = heartbeats.get(agent.agentId);
-      if (lastBeat === undefined || now - lastBeat >= threshold) {
-        stale.push(agent.agentId);
-      }
-    }
-    return stale;
-  }
-
-  /**
-   * Runs a single scan: finds stale agents and invokes onStale callback.
-   */
-  function scan() {
-    const stale = getStaleAgents();
-    if (typeof onStale === "function") {
-      for (const agentId of stale) {
-        onStale(agentId);
-      }
-    }
-  }
-
-  /**
-   * Starts periodic heartbeat scanning.
-   * @param {number} [customIntervalMs]
-   */
-  function start(customIntervalMs) {
-    stop();
-    const interval = customIntervalMs ?? intervalMs;
-    timer = setInterval(scan, interval);
-    timer.unref?.();
-  }
-
-  /**
-   * Stops periodic scanning.
-   */
-  function stop() {
-    if (timer !== null) {
-      clearInterval(timer);
-      timer = null;
-    }
-  }
-
-  /**
-   * Removes heartbeat record for an agent.
-   * @param {string} agentId
-   */
-  function remove(agentId) {
-    heartbeats.delete(agentId);
-  }
-
-  return { recordHeartbeat, getStaleAgents, start, stop, scan, remove };
-}

package/mesh/mesh-protocol.mjs

@@ -1,96 +0,0 @@
-import { randomUUID } from "node:crypto";
-
-export const MSG_TYPES = Object.freeze({
-  REQUEST: "request",
-  RESPONSE: "response",
-  EVENT: "event",
-  HEARTBEAT: "heartbeat",
-});
-
-const VALID_TYPES = new Set(Object.values(MSG_TYPES));
-
-/**
- * Creates an immutable mesh message.
- * @param {string} type - One of MSG_TYPES values
- * @param {string} from - Sender agent ID
- * @param {string} to - Recipient agent ID (or "*" for broadcast)
- * @param {unknown} payload - Message payload
- * @returns {Readonly<object>}
- */
-export function createMessage(type, from, to, payload = null) {
-  if (!VALID_TYPES.has(type)) {
-    throw new TypeError(`Invalid message type: ${type}`);
-  }
-  if (!from || typeof from !== "string") {
-    throw new TypeError("from must be a non-empty string");
-  }
-  if (!to || typeof to !== "string") {
-    throw new TypeError("to must be a non-empty string");
-  }
-  return Object.freeze({
-    type,
-    from,
-    to,
-    payload,
-    timestamp: new Date().toISOString(),
-    correlationId: randomUUID(),
-  });
-}
-
-/**
- * Serializes a message to a JSON string.
- * @param {object} message
- * @returns {string}
- */
-export function serialize(message) {
-  return JSON.stringify(message);
-}
-
-/**
- * Deserializes a JSON string to a message object.
- * @param {string} raw
- * @returns {object}
- */
-export function deserialize(raw) {
-  if (typeof raw !== "string") {
-    throw new TypeError("raw must be a string");
-  }
-  let parsed;
-  try {
-    parsed = JSON.parse(raw);
-  } catch {
-    throw new SyntaxError(`Failed to parse message: ${raw}`);
-  }
-  return parsed;
-}
-
-/**
- * Validates a message object.
- * @param {unknown} message
- * @returns {{ valid: boolean, errors: string[] }}
- */
-export function validate(message) {
-  const errors = [];
-
-  if (!message || typeof message !== "object") {
-    return { valid: false, errors: ["message must be an object"] };
-  }
-
-  if (!VALID_TYPES.has(message.type)) {
-    errors.push(`Invalid type: ${message.type}`);
-  }
-  if (!message.from || typeof message.from !== "string") {
-    errors.push("from must be a non-empty string");
-  }
-  if (!message.to || typeof message.to !== "string") {
-    errors.push("to must be a non-empty string");
-  }
-  if (!message.timestamp || typeof message.timestamp !== "string") {
-    errors.push("timestamp must be a non-empty string");
-  }
-  if (!message.correlationId || typeof message.correlationId !== "string") {
-    errors.push("correlationId must be a non-empty string");
-  }
-
-  return { valid: errors.length === 0, errors };
-}