triflux 10.3.2 → 10.3.4

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 };
+}

package/mesh/mesh-router.mjs

@@ -0,0 +1,76 @@
+import { validate } from "./mesh-protocol.mjs";
+
+/**
+ * Routes a mesh message to target agent(s) based on the `to` field.
+ *
+ * Addressing modes:
+ *   - "agent-id"       → direct delivery (registry lookup)
+ *   - "*"              → broadcast to all registered agents
+ *   - "capability:X"   → discover agents with capability X
+ *
+ * @param {object} message  - A mesh-protocol message
+ * @param {object} registry - A mesh-registry instance
+ * @returns {{ routed: boolean, targets?: string[], reason?: string }}
+ */
+export function routeMessage(message, registry) {
+  const { valid, errors } = validate(message);
+  if (!valid) {
+    return { routed: false, reason: `invalid message: ${errors.join(", ")}` };
+  }
+
+  const { to, from } = message;
+
+  // Broadcast
+  if (to === "*") {
+    const all = registry.listAll();
+    const targets = all
+      .map((a) => a.agentId)
+      .filter((id) => id !== from);
+    if (targets.length === 0) {
+      return { routed: false, reason: "broadcast: no agents registered" };
+    }
+    return { routed: true, targets };
+  }
+
+  // Capability-based routing
+  if (to.startsWith("capability:")) {
+    const capability = to.slice("capability:".length);
+    if (!capability) {
+      return { routed: false, reason: "capability: empty capability name" };
+    }
+    const targets = registry.discover(capability);
+    if (targets.length === 0) {
+      return { routed: false, reason: `capability: no agents with "${capability}"` };
+    }
+    return { routed: true, targets };
+  }
+
+  // Direct addressing
+  const agent = registry.getAgent(to);
+  if (!agent) {
+    return { routed: false, reason: `agent not found: "${to}"` };
+  }
+  return { routed: true, targets: [to] };
+}
+
+/**
+ * Routes a message and collects dead-letter info when delivery fails.
+ *
+ * @param {object} message
+ * @param {object} registry
+ * @returns {{ routed: boolean, targets?: string[], deadLetter?: object }}
+ */
+export function routeOrDeadLetter(message, registry) {
+  const result = routeMessage(message, registry);
+  if (!result.routed) {
+    return {
+      ...result,
+      deadLetter: {
+        originalMessage: message,
+        reason: result.reason,
+        timestamp: new Date().toISOString(),
+      },
+    };
+  }
+  return result;
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "triflux",
-  "version": "10.3.2",
+  "version": "10.3.4",
   "description": "CLI-first multi-model orchestrator for Claude Code — route tasks to Codex, Gemini, and Claude",
   "type": "module",
   "bin": {
@@ -24,6 +24,7 @@
     "scripts",
     "hooks",
     "hud",
+    "mesh",
     ".claude-plugin",
     "README.md",
     "README.ko.md",

package/scripts/completions/tfx.bash

@@ -1,47 +1,47 @@
-#!/usr/bin/env bash
-# Installation: source /path/to/tfx.bash 또는 ~/.bashrc에 추가
-
-_tfx_completion() {
-    local cur prev words cword
-    COMPREPLY=()
-    cur="${COMP_WORDS[COMP_CWORD]}"
-    prev="${COMP_WORDS[COMP_CWORD-1]}"
-    words=("${COMP_WORDS[@]}")
-    cword=$COMP_CWORD
-
-    local commands="setup doctor multi hub auto codex gemini"
-    local multi_cmds="status stop kill attach list"
-    local hub_cmds="start stop status restart"
-    local flags="--thorough --quick --tmux --psmux --agents --no-attach --timeout"
-
-    if [[ $cword -eq 1 ]]; then
-        COMPREPLY=( $(compgen -W "${commands}" -- "$cur") )
-        return 0
-    fi
-
-    local cmd="${words[1]}"
-    case "${cmd}" in
-        multi)
-            if [[ $cword -eq 2 && ! "$cur" == -* ]]; then
-                COMPREPLY=( $(compgen -W "${multi_cmds}" -- "$cur") )
-            else
-                COMPREPLY=( $(compgen -W "${flags}" -- "$cur") )
-            fi
-            ;;
-        hub)
-            if [[ $cword -eq 2 ]]; then
-                COMPREPLY=( $(compgen -W "${hub_cmds}" -- "$cur") )
-            fi
-            ;;
-        doctor)
-            COMPREPLY=( $(compgen -W "--fix --reset" -- "$cur") )
-            ;;
-        setup|auto|codex|gemini)
-            if [[ "$cur" == -* ]]; then
-                COMPREPLY=( $(compgen -W "${flags}" -- "$cur") )
-            fi
-            ;;
-    esac
-}
-
-complete -F _tfx_completion tfx
+#!/usr/bin/env bash
+# Installation: source /path/to/tfx.bash 또는 ~/.bashrc에 추가
+
+_tfx_completion() {
+    local cur prev words cword
+    COMPREPLY=()
+    cur="${COMP_WORDS[COMP_CWORD]}"
+    prev="${COMP_WORDS[COMP_CWORD-1]}"
+    words=("${COMP_WORDS[@]}")
+    cword=$COMP_CWORD
+
+    local commands="setup doctor multi hub auto codex gemini"
+    local multi_cmds="status stop kill attach list"
+    local hub_cmds="start stop status restart"
+    local flags="--thorough --quick --tmux --psmux --agents --no-attach --timeout"
+
+    if [[ $cword -eq 1 ]]; then
+        COMPREPLY=( $(compgen -W "${commands}" -- "$cur") )
+        return 0
+    fi
+
+    local cmd="${words[1]}"
+    case "${cmd}" in
+        multi)
+            if [[ $cword -eq 2 && ! "$cur" == -* ]]; then
+                COMPREPLY=( $(compgen -W "${multi_cmds}" -- "$cur") )
+            else
+                COMPREPLY=( $(compgen -W "${flags}" -- "$cur") )
+            fi
+            ;;
+        hub)
+            if [[ $cword -eq 2 ]]; then
+                COMPREPLY=( $(compgen -W "${hub_cmds}" -- "$cur") )
+            fi
+            ;;
+        doctor)
+            COMPREPLY=( $(compgen -W "--fix --reset" -- "$cur") )
+            ;;
+        setup|auto|codex|gemini)
+            if [[ "$cur" == -* ]]; then
+                COMPREPLY=( $(compgen -W "${flags}" -- "$cur") )
+            fi
+            ;;
+    esac
+}
+
+complete -F _tfx_completion tfx