triflux 10.2.1 → 10.3.0

package/hub/team/lead-control.mjs

@@ -1,23 +1,35 @@
+import { readState } from "../state.mjs";
+
 const DEFAULT_TIMEOUT_MS = 2500;
 const CONTROL_COMMAND_ALIASES = Object.freeze({
   stop: "abort",
   interrupt: "abort",
 });
 
-export const LEAD_CONTROL_COMMANDS = Object.freeze(["pause", "resume", "abort", "reassign"]);
+export const LEAD_CONTROL_COMMANDS = Object.freeze([
+  "pause",
+  "resume",
+  "abort",
+  "reassign",
+]);
 
 function resolveFetch(fetchImpl) {
   if (typeof fetchImpl === "function") return fetchImpl;
-  if (typeof globalThis.fetch === "function") return globalThis.fetch.bind(globalThis);
+  if (typeof globalThis.fetch === "function")
+    return globalThis.fetch.bind(globalThis);
   return null;
 }
 
 function normalizeHubBaseUrl(hubUrl) {
-  return String(hubUrl || "").replace(/\/+$/, "").replace(/\/mcp$/, "");
+  return String(hubUrl || "")
+    .replace(/\/+$/, "")
+    .replace(/\/mcp$/, "");
 }
 
 function normalizeCommand(command) {
-  const raw = String(command || "").trim().toLowerCase();
+  const raw = String(command || "")
+    .trim()
+    .toLowerCase();
   if (!raw) return "";
   return CONTROL_COMMAND_ALIASES[raw] || raw;
 }
@@ -27,6 +39,39 @@ function safeAbortSignal(timeoutMs) {
   return AbortSignal.timeout(timeoutMs);
 }
 
+function isPidAlive(pid) {
+  const resolvedPid = Number(pid);
+  if (!Number.isFinite(resolvedPid) || resolvedPid <= 0) return false;
+  try {
+    process.kill(resolvedPid, 0);
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+function resolveHeadlessHubUrl() {
+  const stateUrl = normalizeHubBaseUrl(readState()?.url);
+  if (stateUrl) return stateUrl;
+
+  const envHubUrl = normalizeHubBaseUrl(process.env.TFX_HUB_URL);
+  if (envHubUrl) return envHubUrl;
+
+  const envPort = Number(process.env.TFX_HUB_PORT || "27888");
+  const port = Number.isFinite(envPort) && envPort > 0 ? envPort : 27888;
+  return `http://127.0.0.1:${port}`;
+}
+
+function hasLiveHubState() {
+  const state = readState();
+  return !!normalizeHubBaseUrl(state?.url) && isPidAlive(state?.pid);
+}
+
+function toHeadlessSessionAgentId(sessionName) {
+  const normalizedSessionName = String(sessionName || "").trim();
+  return normalizedSessionName ? `session:${normalizedSessionName}` : "";
+}
+
 function safeJson(res) {
   return res.json().catch(() => ({}));
 }
@@ -102,3 +147,45 @@ export async function publishLeadControl({
     };
   }
 }
+
+export async function publishHeadlessControl(
+  sessionName,
+  command,
+  targetWorker = "*",
+) {
+  const sessionAgentId = toHeadlessSessionAgentId(sessionName);
+  if (!sessionAgentId) {
+    return {
+      ok: false,
+      noop: true,
+      error: "SESSION_NAME_REQUIRED",
+      command: String(command || "")
+        .trim()
+        .toLowerCase(),
+    };
+  }
+
+  if (!normalizeHubBaseUrl(process.env.TFX_HUB_URL) && !hasLiveHubState()) {
+    return {
+      ok: false,
+      noop: true,
+      error: "HUB_UNAVAILABLE",
+      command: String(command || "")
+        .trim()
+        .toLowerCase(),
+    };
+  }
+
+  return await publishLeadControl({
+    hubUrl: resolveHeadlessHubUrl(),
+    fromAgent: "lead",
+    toAgent: sessionAgentId,
+    command,
+    payload: {
+      session_name: String(sessionName || "").trim(),
+      target_worker: String(targetWorker || "*").trim() || "*",
+      issued_by: "lead",
+      issued_at: Date.now(),
+    },
+  });
+}

package/hub/team/mcp-selector.mjs

@@ -0,0 +1,145 @@
+const TASK_TYPES = Object.freeze([
+  "implement",
+  "review",
+  "research",
+  "qa",
+  "ship",
+  "multi",
+  "swarm",
+]);
+
+const CLI_TYPES = Object.freeze(["codex", "gemini"]);
+
+export const MCP_CATALOG = Object.freeze([
+  Object.freeze({
+    name: "filesystem",
+    purpose: "Read and write workspace files",
+    taskTypes: Object.freeze(["implement", "review", "qa", "ship"]),
+    cli: Object.freeze(["codex", "gemini"]),
+  }),
+  Object.freeze({
+    name: "github",
+    purpose: "Inspect PRs, issues, and release state",
+    taskTypes: Object.freeze(["review", "ship"]),
+    cli: Object.freeze(["codex"]),
+  }),
+  Object.freeze({
+    name: "browser",
+    purpose: "Research web pages and verify browser flows",
+    taskTypes: Object.freeze(["research", "qa"]),
+    cli: Object.freeze(["codex", "gemini"]),
+  }),
+  Object.freeze({
+    name: "context7",
+    purpose: "Fetch current SDK and API documentation",
+    taskTypes: Object.freeze(["implement", "review", "research"]),
+    cli: Object.freeze(["codex", "gemini"]),
+  }),
+  Object.freeze({
+    name: "exa",
+    purpose: "Search code examples and repositories",
+    taskTypes: Object.freeze(["research", "review"]),
+    cli: Object.freeze(["codex", "gemini"]),
+  }),
+  Object.freeze({
+    name: "tavily",
+    purpose: "Verify current external facts and search results",
+    taskTypes: Object.freeze(["research", "qa"]),
+    cli: Object.freeze(["gemini"]),
+  }),
+  Object.freeze({
+    name: "sequential-thinking",
+    purpose: "Structured reasoning for audits and review",
+    taskTypes: Object.freeze(["review"]),
+    cli: Object.freeze(["codex"]),
+  }),
+  Object.freeze({
+    name: "tfx-hub",
+    purpose: "Coordinate triflux hub, multi-agent, and swarm work",
+    taskTypes: Object.freeze(["ship", "multi", "swarm"]),
+    cli: Object.freeze(["codex", "gemini"]),
+  }),
+]);
+
+function uniqueStrings(values = []) {
+  return [
+    ...new Set(
+      (Array.isArray(values) ? values : [])
+        .map((value) => String(value ?? "").trim())
+        .filter(Boolean),
+    ),
+  ];
+}
+
+function assertOneOf(label, value, allowed) {
+  if (!allowed.includes(value)) {
+    throw new TypeError(`${label} must be one of: ${allowed.join(", ")}`);
+  }
+}
+
+export function selectMcpServers(opts = {}) {
+  const taskType = String(opts.taskType ?? "").trim();
+  const cli = String(opts.cli ?? "").trim();
+  assertOneOf("taskType", taskType, TASK_TYPES);
+  assertOneOf("cli", cli, CLI_TYPES);
+
+  const allCatalogNames = MCP_CATALOG.map((server) => server.name);
+  const available = new Set(
+    uniqueStrings(opts.available?.length ? opts.available : allCatalogNames),
+  );
+  const exclude = new Set(uniqueStrings(opts.exclude));
+  const force = uniqueStrings(opts.force);
+
+  const taskMatched = MCP_CATALOG.filter((server) =>
+    server.taskTypes.includes(taskType),
+  );
+  const compatible = taskMatched.filter((server) => server.cli.includes(cli));
+  const incompatible = taskMatched.filter(
+    (server) => !server.cli.includes(cli),
+  );
+
+  const selected = uniqueStrings([
+    ...compatible
+      .map((server) => server.name)
+      .filter((name) => available.has(name) && !exclude.has(name)),
+    ...force.filter((name) => available.has(name) && !exclude.has(name)),
+  ]);
+
+  const reasonParts = [
+    `task=${taskType}`,
+    `cli=${cli}`,
+    `selected=${selected.length ? selected.join(", ") : "none"}`,
+  ];
+  if (incompatible.length) {
+    reasonParts.push(
+      `cli-filtered=${incompatible.map((server) => server.name).join(", ")}`,
+    );
+  }
+  if (force.length) reasonParts.push(`forced=${force.join(", ")}`);
+  if (exclude.size) reasonParts.push(`excluded=${[...exclude].join(", ")}`);
+  if (opts.available?.length) {
+    reasonParts.push(`available=${[...available].join(", ")}`);
+  }
+
+  return {
+    selected,
+    reason: reasonParts.join(" | "),
+  };
+}
+
+export function buildMcpArgs(servers = [], cli) {
+  const resolvedCli = String(cli ?? "").trim();
+  assertOneOf("cli", resolvedCli, CLI_TYPES);
+
+  const selected = uniqueStrings(servers);
+  if (!selected.length) return [];
+
+  if (resolvedCli === "codex") {
+    return selected.flatMap((server) => [
+      "-c",
+      `mcp_servers.${server}.enabled=true`,
+    ]);
+  }
+
+  return ["--allowed-mcp-server-names", ...selected];
+}

package/hub/team/session-sync.mjs

@@ -1,13 +1,19 @@
+import { readState } from "../state.mjs";
+
 const DEFAULT_TIMEOUT_MS = 2500;
+const DEFAULT_HEADLESS_POLL_MS = 1000;
 
 function resolveFetch(fetchImpl) {
   if (typeof fetchImpl === "function") return fetchImpl;
-  if (typeof globalThis.fetch === "function") return globalThis.fetch.bind(globalThis);
+  if (typeof globalThis.fetch === "function")
+    return globalThis.fetch.bind(globalThis);
   return null;
 }
 
 function normalizeHubBaseUrl(hubUrl) {
-  return String(hubUrl || "").replace(/\/+$/, "").replace(/\/mcp$/, "");
+  return String(hubUrl || "")
+    .replace(/\/+$/, "")
+    .replace(/\/mcp$/, "");
 }
 
 function safeAbortSignal(timeoutMs) {
@@ -15,6 +21,55 @@ function safeAbortSignal(timeoutMs) {
   return AbortSignal.timeout(timeoutMs);
 }
 
+function isPidAlive(pid) {
+  const resolvedPid = Number(pid);
+  if (!Number.isFinite(resolvedPid) || resolvedPid <= 0) return false;
+  try {
+    process.kill(resolvedPid, 0);
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+function resolveHeadlessHubUrl(hubUrl) {
+  const normalized = normalizeHubBaseUrl(hubUrl);
+  if (normalized) return normalized;
+
+  const stateUrl = normalizeHubBaseUrl(readState()?.url);
+  if (stateUrl) return stateUrl;
+
+  const envHubUrl = normalizeHubBaseUrl(process.env.TFX_HUB_URL);
+  if (envHubUrl) return envHubUrl;
+
+  const envPort = Number(process.env.TFX_HUB_PORT || "27888");
+  const port = Number.isFinite(envPort) && envPort > 0 ? envPort : 27888;
+  return `http://127.0.0.1:${port}`;
+}
+
+function hasLiveHubState() {
+  const state = readState();
+  return !!normalizeHubBaseUrl(state?.url) && isPidAlive(state?.pid);
+}
+
+function toHeadlessSessionAgentId(sessionName) {
+  const normalizedSessionName = String(sessionName || "").trim();
+  return normalizedSessionName ? `session:${normalizedSessionName}` : "";
+}
+
+async function dispatchHeadlessCommand(command, callbacks) {
+  const callbackMap = {
+    pause: callbacks.onPause,
+    resume: callbacks.onResume,
+    abort: callbacks.onAbort,
+    reassign: callbacks.onReassign,
+  };
+  const handler = callbackMap[command?.command];
+  if (typeof handler === "function") {
+    await handler(command);
+  }
+}
+
 async function safeJson(res) {
   try {
     return await res.json();
@@ -24,8 +79,13 @@ async function safeJson(res) {
 }
 
 function normalizeLeadCommandMessage(message) {
-  const payload = message?.payload && typeof message.payload === "object" ? message.payload : {};
-  const command = String(payload.command || "").trim().toLowerCase();
+  const payload =
+    message?.payload && typeof message.payload === "object"
+      ? message.payload
+      : {};
+  const command = String(payload.command || "")
+    .trim()
+    .toLowerCase();
   if (!command) return null;
   return {
     messageId: message.id || null,
@@ -79,7 +139,9 @@ export async function subscribeToLeadCommands({
     });
 
     const body = await safeJson(res);
-    const messages = Array.isArray(body?.data?.messages) ? body.data.messages : [];
+    const messages = Array.isArray(body?.data?.messages)
+      ? body.data.messages
+      : [];
     const commands = messages
       .filter((message) => message?.topic === "lead.control")
       .map(normalizeLeadCommandMessage)
@@ -108,6 +170,90 @@ export async function subscribeToLeadCommands({
   }
 }
 
+export function createHeadlessControlSubscriber(
+  sessionName,
+  {
+    onPause,
+    onResume,
+    onAbort,
+    onReassign,
+    hubUrl,
+    pollIntervalMs = DEFAULT_HEADLESS_POLL_MS,
+    maxMessages = 10,
+    autoAck = true,
+    timeoutMs = DEFAULT_TIMEOUT_MS,
+    fetchImpl,
+  } = {},
+) {
+  const sessionAgentId = toHeadlessSessionAgentId(sessionName);
+  if (!sessionAgentId) {
+    return { stop() {} };
+  }
+
+  const explicitHubUrl =
+    normalizeHubBaseUrl(hubUrl) || normalizeHubBaseUrl(process.env.TFX_HUB_URL);
+  if (!explicitHubUrl && !hasLiveHubState()) {
+    return { stop() {} };
+  }
+
+  const resolvedHubUrl = explicitHubUrl || resolveHeadlessHubUrl(hubUrl);
+  const callbacks = { onPause, onResume, onAbort, onReassign };
+  const intervalMs = Math.max(
+    50,
+    Number(pollIntervalMs) || DEFAULT_HEADLESS_POLL_MS,
+  );
+
+  let stopped = false;
+  let timer = null;
+  let pending = false;
+
+  const stop = () => {
+    stopped = true;
+    if (timer) clearTimeout(timer);
+    timer = null;
+  };
+
+  const scheduleNext = () => {
+    if (stopped) return;
+    timer = setTimeout(tick, intervalMs);
+    if (typeof timer?.unref === "function") timer.unref();
+  };
+
+  const tick = async () => {
+    if (stopped || pending) {
+      scheduleNext();
+      return;
+    }
+
+    pending = true;
+    try {
+      const result = await subscribeToLeadCommands({
+        hubUrl: resolvedHubUrl,
+        agentId: sessionAgentId,
+        maxMessages,
+        autoAck,
+        timeoutMs,
+        fetchImpl,
+        onCommand: async (command) => {
+          await dispatchHeadlessCommand(command, callbacks);
+        },
+      });
+
+      if (!result?.ok && result?.error === "LEAD_COMMAND_SUBSCRIBE_FAILED") {
+        stop();
+        return;
+      }
+    } finally {
+      pending = false;
+      scheduleNext();
+    }
+  };
+
+  void tick();
+
+  return { stop };
+}
+
 export async function getTeamStatus({
   hubUrl,
   scope = "hub",
@@ -127,7 +273,8 @@ export async function getTeamStatus({
     return { ok: false, error: "HUB_URL_REQUIRED" };
   }
 
-  const normalizedMethod = String(method || "GET").toUpperCase() === "POST" ? "POST" : "GET";
+  const normalizedMethod =
+    String(method || "GET").toUpperCase() === "POST" ? "POST" : "GET";
   const statusScope = String(scope || "hub").trim() || "hub";
 
   let endpoint = `${hubBase}/bridge/status`;