@fibscope/agent 0.1.0

package/lib/bridge/recommendation.mjs

@@ -0,0 +1,311 @@
+#!/usr/bin/env node
+
+import { pathToFileURL } from "node:url";
+import path from "node:path";
+
+export class FiberAutomationError extends Error {
+  constructor(message, code = "FIBER_AUTOMATION_ERROR", details = undefined) {
+    super(message);
+    this.name = "FiberAutomationError";
+    this.code = code;
+    this.details = details;
+  }
+}
+
+export function recommend(input = {}, options = {}) {
+  const context = normalizeAutomationContext(input);
+  const recommendations = [
+    ...recommendFromRootCauses(context),
+    ...recommendFromPredictions(context),
+    ...recommendFromDiagnostics(context),
+    ...recommendFromState(context, options),
+  ];
+  return dedupeRecommendations(recommendations)
+    .sort((left, right) => left.priority - right.priority);
+}
+
+export async function recommendFromSources(options = {}) {
+  const context = {};
+  if (options.component1State) context.component1 = options.component1State;
+  if (options.component2Result) context.component2 = options.component2Result;
+  if (options.component3Report) context.component3 = options.component3Report;
+
+  if (options.component1Module && options.rpcUrl) {
+    const imported = await import(resolveImportSpecifier(options.component1Module));
+    context.component1 = await imported.collectFiberStateReport({
+      rpcUrl: options.rpcUrl,
+      timeoutMs: options.timeoutMs ?? 8000,
+    });
+  }
+
+  if (options.component3Url) {
+    context.component3 = await fetchComponent3(options.component3Url, options);
+  }
+
+  return recommend(context, options);
+}
+
+export function normalizeAutomationContext(input = {}) {
+  return {
+    component1: input.component1 ?? input.fiberState ?? input.state ?? {},
+    component2: input.component2 ?? input.routeSimulation ?? input.paymentSimulation ?? {},
+    component3: input.component3 ?? input.observability ?? {},
+    rootCauses: [
+      ...(input.rootCauses ?? []),
+      ...(input.diagnoses ?? []),
+      ...(input.component3?.rootCauses ?? []),
+      ...(input.component3?.diagnostics?.rootCauses ?? []),
+    ],
+    predictions: [
+      ...(input.predictions ?? []),
+      ...(input.component2?.predictions ?? []),
+      ...(input.component2?.visualization?.predictions ?? []),
+    ],
+    diagnostics: [
+      ...(input.diagnostics ?? []),
+      ...(input.component1?.diagnostics ?? []),
+      ...(input.component3?.component1 ?? []),
+      ...(input.component3?.diagnostics?.component1 ?? []),
+    ],
+  };
+}
+
+function recommendFromRootCauses(context) {
+  return context.rootCauses.flatMap((cause) => recommendationsForCode(cause.code, {
+    source: "root-cause",
+    explanation: cause.explanation,
+    affectedChannel: cause.affectedChannel,
+    affectedPeer: cause.affectedPeer,
+    confidence: cause.confidence,
+  }));
+}
+
+function recommendFromPredictions(context) {
+  return context.predictions.flatMap((prediction) => recommendationsForCode(prediction.code, {
+    source: "prediction",
+    explanation: prediction.explanation,
+    confidence: prediction.confidence,
+  }));
+}
+
+function recommendFromDiagnostics(context) {
+  return context.diagnostics.flatMap((diagnostic) => {
+    const severity = String(diagnostic.severity ?? "info").toLowerCase();
+    const code = String(diagnostic.code ?? "UNKNOWN").toUpperCase();
+    if (severity === "info" && !isActionableCode(code)) return [];
+    return recommendationsForCode(code, {
+      source: "diagnostic",
+      explanation: diagnostic.description ?? diagnostic.title,
+      severity,
+    });
+  });
+}
+
+function recommendFromState(context, options) {
+  const state = context.component1;
+  const recommendations = [];
+  const outbound = amountMaybe(state?.liquidity?.totalOutbound);
+  const requested = amountMaybe(options.amount ?? context.component2?.request?.amount);
+  if (requested !== undefined && outbound !== undefined && requested > outbound) {
+    recommendations.push(recommendation(1, "Reduce payment amount", `Requested amount ${requested} exceeds outbound liquidity ${outbound}.`, "REDUCE_PAYMENT_AMOUNT", {
+      source: "component1-liquidity",
+      requested,
+      outbound,
+    }));
+  }
+  for (const channel of state?.channels ?? []) {
+    const capacity = amountMaybe(channel.capacity);
+    const local = amountMaybe(channel.localBalance);
+    if (capacity && local !== undefined && capacity > 0n && (local * 100n / capacity) < 15n) {
+      recommendations.push(recommendation(2, "Rebalance channel", `Channel ${short(channel.channelId)} has low outbound liquidity.`, "REBALANCE_CHANNEL", {
+        channelId: channel.channelId,
+        peerId: channel.peerId,
+      }));
+    }
+  }
+  return recommendations;
+}
+
+function recommendationsForCode(code, metadata = {}) {
+  const normalized = String(code ?? "UNKNOWN").toUpperCase();
+  if (normalized === "INSUFFICIENT_LIQUIDITY" || normalized === "INSUFFICIENT_OUTBOUND_LIQUIDITY" || normalized === "LOW_OUTBOUND_LIQUIDITY") {
+    return [
+      recommendation(1, "Rebalance an existing channel", metadata.explanation ?? "Outbound liquidity is insufficient for the attempted payment.", "REBALANCE_CHANNEL", metadata),
+      recommendation(2, "Open a new channel", "Add fresh outbound capacity through a new channel.", "OPEN_CHANNEL", metadata),
+      recommendation(3, "Reduce payment amount", "Retry with an amount that fits the current outbound liquidity.", "REDUCE_PAYMENT_AMOUNT", metadata),
+    ];
+  }
+  if (normalized === "NO_ROUTE" || normalized === "NO_CHANNELS") {
+    return [
+      recommendation(1, "Create a channel", metadata.explanation ?? "No usable route/channel is available.", "OPEN_CHANNEL", metadata),
+      recommendation(2, "Connect to more Fiber peers", "Improve graph reachability before retrying the payment.", "CONNECT_PEER", metadata),
+    ];
+  }
+  if (normalized === "CHANNEL_CLOSED" || normalized === "CHANNEL_NOT_OPEN") {
+    return [
+      recommendation(1, "Wait for channel state to settle", metadata.explanation ?? "A channel is not open.", "WAIT_CHANNEL_OPEN", metadata),
+      recommendation(2, "Use an alternate channel", "Route around the closed or pending channel.", "USE_ALTERNATE_ROUTE", metadata),
+    ];
+  }
+  if (normalized === "PEER_OFFLINE" || normalized === "NO_PEERS") {
+    return [
+      recommendation(1, "Reconnect Fiber peer", metadata.explanation ?? "A required peer is offline or no peer is connected.", "CONNECT_PEER", metadata),
+      recommendation(2, "Use alternate route", "Avoid the offline peer when selecting a route.", "USE_ALTERNATE_ROUTE", metadata),
+    ];
+  }
+  if (normalized === "HIGH_ROUTING_FEES") {
+    return [
+      recommendation(2, "Use lower-fee route", metadata.explanation ?? "The selected route has high fees.", "USE_ALTERNATE_ROUTE", metadata),
+      recommendation(3, "Tune fee policy", "Review peer/channel fee settings before retrying.", "TUNE_FEE_POLICY", metadata),
+    ];
+  }
+  if (normalized === "TIMEOUT" || normalized === "NODE_OFFLINE") {
+    return [
+      recommendation(1, "Verify FNN connectivity", metadata.explanation ?? "The local Fiber node is offline or timing out.", "VERIFY_NODE_RUNNING", metadata),
+      recommendation(2, "Check RPC connectivity", "Verify the configured RPC URL and network path.", "CHECK_RPC_CONNECTIVITY", metadata),
+    ];
+  }
+  return [
+    recommendation(5, "Rebuild state from observability data", metadata.explanation ?? "The failure cause is unknown.", "INSPECT_TELEMETRY", metadata),
+  ];
+}
+
+function isActionableCode(code) {
+  return [
+    "INSUFFICIENT_LIQUIDITY",
+    "INSUFFICIENT_OUTBOUND_LIQUIDITY",
+    "LOW_OUTBOUND_LIQUIDITY",
+    "NO_ROUTE",
+    "NO_CHANNELS",
+    "CHANNEL_CLOSED",
+    "CHANNEL_NOT_OPEN",
+    "PEER_OFFLINE",
+    "NO_PEERS",
+    "HIGH_ROUTING_FEES",
+    "TIMEOUT",
+    "NODE_OFFLINE",
+  ].includes(code);
+}
+
+function recommendation(priority, title, explanation, actionType, metadata = {}) {
+  return {
+    priority,
+    title,
+    explanation,
+    actionType,
+    metadata,
+  };
+}
+
+function dedupeRecommendations(items) {
+  const best = new Map();
+  for (const item of items) {
+    const key = `${item.actionType}:${item.title}`;
+    const existing = best.get(key);
+    if (!existing || item.priority < existing.priority) best.set(key, item);
+  }
+  return [...best.values()];
+}
+
+async function fetchComponent3(component3Url, options) {
+  const base = component3Url.replace(/\/$/, "");
+  const [diagnostics, health, metrics, alerts] = await Promise.all([
+    fetchJson(`${base}/diagnostics`, options),
+    fetchJson(`${base}/health`, options),
+    fetchJson(`${base}/metrics`, options),
+    fetchJson(`${base}/alerts`, options),
+  ]);
+  return { diagnostics, health, metrics, alerts };
+}
+
+async function fetchJson(url, options = {}) {
+  const controller = new AbortController();
+  const timer = setTimeout(() => controller.abort(), options.timeoutMs ?? 8000);
+  try {
+    const response = await fetch(url, { signal: controller.signal });
+    if (!response.ok) throw new FiberAutomationError(`${url} failed with HTTP ${response.status}`, "FETCH_FAILED");
+    return response.json();
+  } finally {
+    clearTimeout(timer);
+  }
+}
+
+function amountMaybe(value) {
+  if (value === undefined || value === null || value === "") return undefined;
+  if (typeof value === "bigint") return value;
+  if (typeof value === "number" && Number.isFinite(value)) return BigInt(Math.trunc(value));
+  if (typeof value === "string" && /^0x[0-9a-fA-F]+$/.test(value)) return BigInt(value);
+  if (typeof value === "string" && /^[0-9]+$/.test(value)) return BigInt(value);
+  return undefined;
+}
+
+function short(value) {
+  const text = String(value ?? "");
+  return text.length <= 14 ? text : `${text.slice(0, 8)}...${text.slice(-6)}`;
+}
+
+function resolveImportSpecifier(specifier) {
+  if (/^(file|data|node|https?):/.test(specifier)) return specifier;
+  if (specifier.startsWith(".") || specifier.includes("\\") || specifier.includes("/")) {
+    return pathToFileURL(path.resolve(process.cwd(), specifier)).href;
+  }
+  return specifier;
+}
+
+function stringify(value) {
+  return JSON.stringify(value, (_, nested) => typeof nested === "bigint" ? nested.toString() : nested, 2);
+}
+
+function parseCliArgs(argv) {
+  const options = {};
+  let command = argv[0]?.startsWith("--") ? "recommend" : (argv.shift() ?? "help");
+  for (let index = 0; index < argv.length; index += 1) {
+    const raw = argv[index];
+    const [flag, inline] = raw.split("=", 2);
+    const value = () => inline ?? argv[++index];
+    if (flag === "--rpc") options.rpcUrl = value();
+    else if (flag === "--component1-module") options.component1Module = value();
+    else if (flag === "--component3-url") options.component3Url = value();
+    else if (flag === "--amount") options.amount = value();
+    else if (flag === "--input") options.input = value();
+    else if (flag === "--json") options.json = true;
+    else if (flag === "--help" || flag === "-h") command = "help";
+    else throw new FiberAutomationError(`Unknown option ${flag}`, "CLI_USAGE_ERROR");
+  }
+  return { command, options };
+}
+
+async function readInput(pathname) {
+  if (!pathname) return {};
+  const { readFile } = await import("node:fs/promises");
+  return JSON.parse(await readFile(pathname, "utf8"));
+}
+
+function help() {
+  return [
+    "Fiber Automation Recommendation Engine",
+    "",
+    "Usage:",
+    "  node recommendation.mjs recommend --input context.json --json",
+    "  node recommendation.mjs recommend --rpc http://127.0.0.1:8227 --component1-module ../pulse/index.mjs --amount 100000000 --json",
+    "  node recommendation.mjs recommend --component3-url http://127.0.0.1:8793 --json",
+  ].join("\n");
+}
+
+if (process.argv[1] && import.meta.url === pathToFileURL(process.argv[1]).href) {
+  const { command, options } = parseCliArgs(process.argv.slice(2));
+  if (command === "help") {
+    console.log(help());
+  } else if (command === "recommend") {
+    const input = await readInput(options.input);
+    recommendFromSources({ ...options, ...input })
+      .then((items) => console.log(options.json ? stringify(items) : items.map((item) => `${item.priority}. ${item.title} (${item.actionType})`).join("\n")))
+      .catch((error) => {
+        console.error(error instanceof Error ? error.message : String(error));
+        process.exitCode = 1;
+      });
+  } else {
+    console.error(`Unknown command ${command}`);
+    process.exitCode = 1;
+  }
+}

package/lib/fnn-discovery.mjs

@@ -0,0 +1,293 @@
+import { spawnSync } from "node:child_process";
+import { constants } from "node:fs";
+import { access, readFile } from "node:fs/promises";
+import path from "node:path";
+
+export async function discoverFnnInstances(options = {}) {
+  const timeoutMs = options.timeoutMs ?? 1200;
+  const rows = process.platform === "win32" ? windowsFnnProcesses() : posixFnnProcesses();
+  const instances = [];
+
+  for (const row of rows) {
+    const parsed = parseFnnCommandLine(row.commandLine);
+    const configPath = parsed.configPath ? path.resolve(parsed.configPath) : undefined;
+    const baseDir = parsed.baseDir ? path.resolve(parsed.baseDir) : configPath ? path.dirname(configPath) : undefined;
+    const config = configPath ? await readFiberConfig(configPath) : {};
+    const rpcUrl = config.rpcUrl;
+    const reachable = rpcUrl ? await rpcResponds(rpcUrl, timeoutMs) : false;
+    instances.push({
+      pid: row.pid,
+      commandLine: row.commandLine,
+      configPath,
+      baseDir,
+      rpcUrl,
+      p2pListenAddr: config.p2pListenAddr,
+      p2pPort: config.p2pPort,
+      ckbRpcUrl: config.ckbRpcUrl,
+      network: config.network,
+      reachable,
+    });
+  }
+
+  return dedupeInstances(instances);
+}
+
+export async function chooseFnnInstance(instances, options = {}) {
+  const candidates = instances.filter((instance) => instance.pid && instance.rpcUrl);
+  if (!candidates.length) return undefined;
+  if (candidates.length === 1) return candidates[0];
+
+  const preferred = options.currentRpcUrl
+    ? candidates.find((instance) => sameUrl(instance.rpcUrl, options.currentRpcUrl))
+    : undefined;
+  if (preferred && options.preferCurrent === true) return preferred;
+
+  if (!options.interactive || typeof options.prompt !== "function") {
+    return candidates.find((instance) => instance.reachable) ?? candidates[0];
+  }
+
+  console.log("");
+  console.log("Running FNN instances");
+  candidates.forEach((instance, index) => {
+    console.log(`  ${index + 1}. ${describeFnnInstance(instance)}`);
+  });
+
+  while (true) {
+    const answer = (await options.prompt("  Select FNN instance to bind [1]: ")).trim() || "1";
+    const selected = Number(answer);
+    if (Number.isInteger(selected) && selected >= 1 && selected <= candidates.length) return candidates[selected - 1];
+    console.log(`  Choose a number from 1 to ${candidates.length}.`);
+  }
+}
+
+export function describeFnnInstance(instance) {
+  const status = instance.reachable ? "RPC ready" : "RPC not responding";
+  const rpc = instance.rpcUrl ?? "RPC unknown";
+  const base = instance.baseDir ?? "base dir unknown";
+  const network = instance.network ? `${instance.network}, ` : "";
+  return `pid ${instance.pid} (${network}${rpc}, ${status}) - ${base}`;
+}
+
+export function applyFnnInstanceToContext(context, instance) {
+  if (!instance?.rpcUrl) return context;
+  const parsed = new URL(instance.rpcUrl);
+  const rpcPort = Number(parsed.port || (parsed.protocol === "https:" ? 443 : 80));
+  const baseDir = instance.baseDir ?? context.baseDir;
+  const walletPath = path.join(baseDir, "ckb", "wallet.json");
+  return {
+    ...context,
+    baseDir,
+    walletConfig: context.explicitWalletConfig ? context.walletConfig : walletPath,
+    fiberKeyPath: path.join(baseDir, "ckb", "key"),
+    walletCopyPath: walletPath,
+    pidPath: path.join(baseDir, "fnn.pid"),
+    rpcHost: parsed.hostname,
+    rpcPort,
+    rpcUrl: instance.rpcUrl,
+    boundFnnInstance: instance,
+  };
+}
+
+export async function rpcResponds(rpcUrl, timeoutMs = 1500) {
+  try {
+    const result = await rpcCall(rpcUrl, "node_info", [], timeoutMs);
+    return Boolean(result?.pubkey || result?.node_id || result?.version);
+  } catch {
+    return false;
+  }
+}
+
+async function rpcCall(rpcUrl, method, params, timeoutMs) {
+  const controller = new AbortController();
+  const timeout = setTimeout(() => controller.abort(), timeoutMs);
+  try {
+    const response = await fetch(rpcUrl, {
+      method: "POST",
+      headers: { "content-type": "application/json" },
+      body: JSON.stringify({ id: 1, jsonrpc: "2.0", method, params }),
+      signal: controller.signal,
+    });
+    const payload = await response.json();
+    if (payload.error) throw new Error(payload.error.message ?? "FNN RPC error");
+    return payload.result;
+  } finally {
+    clearTimeout(timeout);
+  }
+}
+
+async function readFiberConfig(configPath) {
+  try {
+    await access(configPath, constants.F_OK);
+    return parseFiberConfig(await readFile(configPath, "utf8"));
+  } catch {
+    return {};
+  }
+}
+
+function parseFiberConfig(config) {
+  const lines = config.split(/\r?\n/);
+  let section = "";
+  let rpcListeningAddr;
+  let p2pListenAddr;
+  let ckbRpcUrl;
+  let network;
+
+  for (const rawLine of lines) {
+    const line = rawLine.replace(/#.*/, "");
+    const sectionMatch = /^([A-Za-z0-9_-]+):\s*$/.exec(line);
+    if (sectionMatch) {
+      section = sectionMatch[1];
+      continue;
+    }
+
+    if (section === "rpc") {
+      const match = /^\s+listening_addr:\s*["']?([^"'\s]+)["']?/.exec(line);
+      if (match) rpcListeningAddr = match[1];
+    }
+
+    if (section === "ckb") {
+      const match = /^\s+rpc_url:\s*["']?([^"'\s]+)["']?/.exec(line);
+      if (match) ckbRpcUrl = match[1];
+    }
+
+    if (section === "fiber") {
+      const listenMatch = /^\s+listening_addr:\s*["']?([^"'\s]+)["']?/.exec(line);
+      if (listenMatch) p2pListenAddr = listenMatch[1];
+      const match = /^\s+chain:\s*["']?([^"'\s]+)["']?/.exec(line);
+      if (match) network = match[1];
+    }
+  }
+
+  return {
+    network,
+    rpcUrl: rpcListeningAddr ? rpcUrlFromListeningAddr(rpcListeningAddr) : undefined,
+    p2pListenAddr,
+    p2pPort: p2pListenAddr ? p2pPortFromMultiaddr(p2pListenAddr) : undefined,
+    ckbRpcUrl,
+  };
+}
+
+function p2pPortFromMultiaddr(value) {
+  const match = /\/tcp\/(\d+)(?:\/|$)/.exec(String(value ?? ""));
+  return match ? Number(match[1]) : undefined;
+}
+
+function rpcUrlFromListeningAddr(value) {
+  const trimmed = value.trim();
+  const ipv6 = /^\[([^\]]+)]:(\d+)$/.exec(trimmed);
+  if (ipv6) return `http://[${loopbackHost(ipv6[1])}]:${ipv6[2]}`;
+  const ipv4 = /^([^:]+):(\d+)$/.exec(trimmed);
+  if (ipv4) return `http://${loopbackHost(ipv4[1])}:${ipv4[2]}`;
+  return undefined;
+}
+
+function loopbackHost(host) {
+  return host === "0.0.0.0" || host === "::" ? "127.0.0.1" : host;
+}
+
+function parseFnnCommandLine(commandLine) {
+  const tokens = tokenizeCommandLine(commandLine);
+  let configPath;
+  let baseDir;
+  for (let index = 0; index < tokens.length; index += 1) {
+    const token = tokens[index];
+    if (token === "-c" || token === "--config") configPath = tokens[index + 1];
+    else if (token.startsWith("--config=")) configPath = token.slice("--config=".length);
+    else if (token === "-d" || token === "--base-dir" || token === "--data-dir") baseDir = tokens[index + 1];
+    else if (token.startsWith("--base-dir=")) baseDir = token.slice("--base-dir=".length);
+    else if (token.startsWith("--data-dir=")) baseDir = token.slice("--data-dir=".length);
+  }
+  return { configPath, baseDir };
+}
+
+function tokenizeCommandLine(commandLine) {
+  const tokens = [];
+  let current = "";
+  let quote = "";
+  for (let index = 0; index < commandLine.length; index += 1) {
+    const char = commandLine[index];
+    if (quote) {
+      if (char === quote) quote = "";
+      else current += char;
+      continue;
+    }
+    if (char === '"' || char === "'") {
+      quote = char;
+      continue;
+    }
+    if (/\s/.test(char)) {
+      if (current) {
+        tokens.push(current);
+        current = "";
+      }
+      continue;
+    }
+    current += char;
+  }
+  if (current) tokens.push(current);
+  return tokens;
+}
+
+function windowsFnnProcesses() {
+  const command = [
+    "$ErrorActionPreference = 'SilentlyContinue';",
+    "Get-CimInstance Win32_Process |",
+    "Where-Object { $_.Name -ieq 'fnn.exe' } |",
+    "Select-Object ProcessId, CommandLine |",
+    "ConvertTo-Json -Compress",
+  ].join(" ");
+  const result = spawnSync("powershell.exe", ["-NoProfile", "-Command", command], {
+    encoding: "utf8",
+    timeout: 7000,
+    windowsHide: true,
+  });
+  if (result.status !== 0 || !result.stdout.trim()) return [];
+  try {
+    const parsed = JSON.parse(result.stdout);
+    return (Array.isArray(parsed) ? parsed : [parsed])
+      .map((row) => ({
+        pid: Number(row.ProcessId),
+        commandLine: typeof row.CommandLine === "string" ? row.CommandLine : "",
+      }))
+      .filter((row) => Number.isInteger(row.pid) && row.commandLine);
+  } catch {
+    return [];
+  }
+}
+
+function posixFnnProcesses() {
+  const result = spawnSync("ps", ["-axo", "pid=,comm=,args="], {
+    encoding: "utf8",
+    timeout: 5000,
+  });
+  if (result.status !== 0) return [];
+  return result.stdout
+    .split(/\r?\n/)
+    .map((line) => line.trim())
+    .filter(Boolean)
+    .map((line) => {
+      const match = /^(\d+)\s+(\S+)\s+(.+)$/.exec(line);
+      if (!match) return undefined;
+      return { pid: Number(match[1]), command: path.basename(match[2]), commandLine: match[3] };
+    })
+    .filter((row) => row && Number.isInteger(row.pid) && /^fnn(?:\.exe)?$/i.test(row.command));
+}
+
+function dedupeInstances(instances) {
+  const seen = new Set();
+  return instances.filter((instance) => {
+    if (seen.has(instance.pid)) return false;
+    seen.add(instance.pid);
+    return true;
+  });
+}
+
+function sameUrl(left, right) {
+  try {
+    const a = new URL(left);
+    const b = new URL(right);
+    return a.protocol === b.protocol && a.hostname === b.hostname && a.port === b.port;
+  } catch {
+    return left === right;
+  }
+}