triflux 10.3.2 → 10.3.3

package/hub/workers/factory.mjs

@@ -1,21 +1,21 @@
-// hub/workers/factory.mjs — Worker 생성 팩토리
-
-import { GeminiWorker } from './gemini-worker.mjs';
-import { ClaudeWorker } from './claude-worker.mjs';
-import { CodexMcpWorker } from './codex-mcp.mjs';
-import { DelegatorMcpWorker } from './delegator-mcp.mjs';
-
-export function createWorker(type, opts = {}) {
-  switch (type) {
-    case 'gemini':
-      return new GeminiWorker(opts);
-    case 'claude':
-      return new ClaudeWorker(opts);
-    case 'codex':
-      return new CodexMcpWorker(opts);
-    case 'delegator':
-      return new DelegatorMcpWorker(opts);
-    default:
-      throw new Error(`Unknown worker type: ${type}`);
-  }
-}
+// hub/workers/factory.mjs — Worker 생성 팩토리
+
+import { GeminiWorker } from './gemini-worker.mjs';
+import { ClaudeWorker } from './claude-worker.mjs';
+import { CodexMcpWorker } from './codex-mcp.mjs';
+import { DelegatorMcpWorker } from './delegator-mcp.mjs';
+
+export function createWorker(type, opts = {}) {
+  switch (type) {
+    case 'gemini':
+      return new GeminiWorker(opts);
+    case 'claude':
+      return new ClaudeWorker(opts);
+    case 'codex':
+      return new CodexMcpWorker(opts);
+    case 'delegator':
+      return new DelegatorMcpWorker(opts);
+    default:
+      throw new Error(`Unknown worker type: ${type}`);
+  }
+}

package/mesh/index.mjs

@@ -0,0 +1,63 @@
+import { readdirSync } from "node:fs";
+import { join } from "node:path";
+
+export { MSG_TYPES, createMessage, serialize, deserialize, validate } from "./mesh-protocol.mjs";
+export { createRegistry } from "./mesh-registry.mjs";
+export { createMeshBudget } from "./mesh-budget.mjs";
+export { routeMessage, routeOrDeadLetter } from "./mesh-router.mjs";
+export { createMessageQueue } from "./mesh-queue.mjs";
+export { createHeartbeatMonitor } from "./mesh-heartbeat.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 && skillContent.includes(agentId)) {
+      skills.push(skillName);
+    }
+  }
+
+  return skills;
+}

package/mesh/mesh-budget.mjs

@@ -0,0 +1,128 @@
+/**
+ * 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

@@ -0,0 +1,100 @@
+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

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

package/mesh/mesh-queue.mjs

@@ -0,0 +1,165 @@
+const DEFAULT_MAX_QUEUE_SIZE = 100;
+const DEFAULT_TTL_MS = 0; // 0 = no expiry
+
+/**
+ * Creates a per-agent message queue with TTL and size limits.
+ *
+ * @param {object} [opts]
+ * @param {number} [opts.maxQueueSize=100] - Max messages per agent queue
+ * @param {number} [opts.ttlMs=0]         - Message TTL in ms (0 = no expiry)
+ * @returns {object} Queue API
+ */
+export function createMessageQueue(opts = {}) {
+  const {
+    maxQueueSize = DEFAULT_MAX_QUEUE_SIZE,
+    ttlMs = DEFAULT_TTL_MS,
+  } = opts;
+
+  /** @type {Map<string, Array<{ message: object, enqueuedAt: number }>>} */
+  const queues = new Map();
+
+  /**
+   * Returns the queue array for an agent (creates if absent).
+   * @param {string} agentId
+   * @returns {Array}
+   */
+  function getQueue(agentId) {
+    let q = queues.get(agentId);
+    if (!q) {
+      q = [];
+      queues.set(agentId, q);
+    }
+    return q;
+  }
+
+  /**
+   * Removes expired messages from the front of a queue.
+   * @param {Array} q
+   * @param {number} now
+   */
+  function purgeExpired(q, now) {
+    if (ttlMs <= 0) return;
+    while (q.length > 0 && (now - q[0].enqueuedAt) > ttlMs) {
+      q.shift();
+    }
+  }
+
+  /**
+   * Adds a message to the target agent's queue.
+   * If queue exceeds maxQueueSize, the oldest message is dropped.
+   *
+   * @param {string} agentId - Target agent
+   * @param {object} message - Mesh message
+   * @returns {{ queued: boolean, dropped: boolean }}
+   */
+  function enqueue(agentId, message) {
+    if (!agentId || typeof agentId !== "string") {
+      throw new TypeError("agentId must be a non-empty string");
+    }
+    const q = getQueue(agentId);
+    const now = Date.now();
+
+    purgeExpired(q, now);
+
+    let dropped = false;
+    if (q.length >= maxQueueSize) {
+      q.shift();
+      dropped = true;
+    }
+
+    q.push({ message, enqueuedAt: now });
+    return { queued: true, dropped };
+  }
+
+  /**
+   * Removes and returns the next message for an agent.
+   *
+   * @param {string} agentId
+   * @returns {object | null} The message, or null if queue is empty
+   */
+  function dequeue(agentId) {
+    const q = queues.get(agentId);
+    if (!q || q.length === 0) return null;
+
+    const now = Date.now();
+    purgeExpired(q, now);
+
+    if (q.length === 0) return null;
+    return q.shift().message;
+  }
+
+  /**
+   * Returns the next message without removing it.
+   *
+   * @param {string} agentId
+   * @returns {object | null}
+   */
+  function peek(agentId) {
+    const q = queues.get(agentId);
+    if (!q || q.length === 0) return null;
+
+    const now = Date.now();
+    purgeExpired(q, now);
+
+    if (q.length === 0) return null;
+    return q[0].message;
+  }
+
+  /**
+   * Returns the number of (non-expired) messages in an agent's queue.
+   *
+   * @param {string} agentId
+   * @returns {number}
+   */
+  function size(agentId) {
+    const q = queues.get(agentId);
+    if (!q) return 0;
+
+    const now = Date.now();
+    purgeExpired(q, now);
+
+    return q.length;
+  }
+
+  /**
+   * Drains all messages for an agent.
+   *
+   * @param {string} agentId
+   * @returns {object[]} Array of messages
+   */
+  function drain(agentId) {
+    const q = queues.get(agentId);
+    if (!q || q.length === 0) return [];
+
+    const now = Date.now();
+    purgeExpired(q, now);
+
+    const messages = q.map((entry) => entry.message);
+    q.length = 0;
+    return messages;
+  }
+
+  /**
+   * Removes an agent's queue entirely.
+   * @param {string} agentId
+   */
+  function clear(agentId) {
+    queues.delete(agentId);
+  }
+
+  /**
+   * Returns total message count across all agent queues.
+   * @returns {number}
+   */
+  function totalSize() {
+    let total = 0;
+    const now = Date.now();
+    for (const [, q] of queues) {
+      purgeExpired(q, now);
+      total += q.length;
+    }
+    return total;
+  }
+
+  return { enqueue, dequeue, peek, size, drain, clear, totalSize };
+}

package/mesh/mesh-registry.mjs

@@ -0,0 +1,78 @@
+/**
+ * Creates an agent registry for the mesh network.
+ * Agents register with capabilities; registry enables discovery.
+ * @returns {object} Registry API
+ */
+export function createRegistry() {
+  // Map<agentId, AgentInfo>
+  const agents = new Map();
+
+  /**
+   * Registers an agent with the registry.
+   * @param {string} agentId
+   * @param {string[]} capabilities
+   */
+  function register(agentId, capabilities = []) {
+    if (!agentId || typeof agentId !== "string") {
+      throw new TypeError("agentId must be a non-empty string");
+    }
+    if (!Array.isArray(capabilities)) {
+      throw new TypeError("capabilities must be an array");
+    }
+    const info = Object.freeze({
+      agentId,
+      capabilities: Object.freeze([...capabilities]),
+      registeredAt: new Date().toISOString(),
+    });
+    agents.set(agentId, info);
+  }
+
+  /**
+   * Unregisters an agent from the registry.
+   * @param {string} agentId
+   */
+  function unregister(agentId) {
+    agents.delete(agentId);
+  }
+
+  /**
+   * Discovers agents that have a specific capability.
+   * @param {string} capability
+   * @returns {string[]} Array of agentIds
+   */
+  function discover(capability) {
+    const result = [];
+    for (const [agentId, info] of agents) {
+      if (info.capabilities.includes(capability)) {
+        result.push(agentId);
+      }
+    }
+    return result;
+  }
+
+  /**
+   * Gets agent info by ID.
+   * @param {string} agentId
+   * @returns {object | null}
+   */
+  function getAgent(agentId) {
+    return agents.get(agentId) ?? null;
+  }
+
+  /**
+   * Lists all registered agents.
+   * @returns {object[]}
+   */
+  function listAll() {
+    return [...agents.values()];
+  }
+
+  /**
+   * Clears all registered agents.
+   */
+  function clear() {
+    agents.clear();
+  }
+
+  return { register, unregister, discover, getAgent, listAll, clear };
+}