@xyagent/cli 0.0.1

package/src-ext/core/sessionSlot.mjs

@@ -0,0 +1,70 @@
+// 单 session 槽。
+//
+// 一个 `agentlink-agent <runtime>` 进程同一时刻**只持 1 个活跃 session**。
+// App 触发 "new session" → `replace(next)` → 旧的 abort，新的 spawn。
+//
+// 状态：
+//   idle        → spawning / ended
+//   spawning    → ready / crashed
+//   ready       → thinking / aborting
+//   thinking    → ready / aborting / crashed
+//   aborting    → idle
+//   crashed     → idle
+//   ended       → (terminal)
+
+import { createStateMachine } from "./stateMachine.mjs";
+
+export const SESSION_STATES = Object.freeze({
+  IDLE: "idle",
+  SPAWNING: "spawning",
+  READY: "ready",
+  THINKING: "thinking",
+  ABORTING: "aborting",
+  CRASHED: "crashed",
+  ENDED: "ended",
+});
+
+const ALLOWED = {
+  idle:      ["spawning", "ended"],
+  spawning:  ["ready", "crashed", "aborting"],
+  ready:     ["thinking", "aborting", "crashed", "ended"],
+  thinking:  ["ready", "aborting", "crashed", "ended"],
+  aborting:  ["idle", "ended"],
+  crashed:   ["idle", "ended"],
+  ended:     [],
+};
+
+export function createSessionSlot({ log, name }) {
+  const fsm = createStateMachine({
+    initial: SESSION_STATES.IDLE,
+    allowed: ALLOWED,
+    log,
+    name: name || "session-slot",
+  });
+
+  let currentSession = null;
+
+  function state() { return fsm.current(); }
+
+  function assign(session) {
+    currentSession = session;
+  }
+
+  function clear() {
+    currentSession = null;
+  }
+
+  function get() {
+    return currentSession;
+  }
+
+  return {
+    state,
+    can: fsm.can,
+    transition: fsm.transition,
+    onChange: fsm.onChange,
+    assign,
+    clear,
+    get,
+  };
+}

package/src-ext/core/stateMachine.mjs

@@ -0,0 +1,85 @@
+// 极简通用 FSM。
+//
+// 目的：
+//   - 把 session 生命周期状态转换显式化（而不是散在若干 boolean 里）。
+//   - 每次 transition 打一条 log，出问题一眼看到"卡在哪个状态"。
+//
+// 非法 transition **不抛异常**，打 warn + 拒绝变更 —— 避免状态机 bug 把整个
+// bridge 带下线。
+
+export function createStateMachine({ initial, allowed, log, name }) {
+  if (!initial) throw new Error("stateMachine: initial required");
+  if (!allowed || typeof allowed !== "object") {
+    throw new Error("stateMachine: allowed map required");
+  }
+  const smLog = (log || consoleFallback()).child
+    ? (log || consoleFallback()).child({ comp: "session", sm: name || "fsm" })
+    : log;
+
+  let state = initial;
+  let stateEnteredAt = Date.now();
+  const listeners = new Set();
+
+  function current() {
+    return state;
+  }
+
+  function can(next) {
+    const nexts = allowed[state] || [];
+    return nexts.includes(next);
+  }
+
+  function transition(next, reason) {
+    if (state === next) {
+      // 同态转换吞掉，不打 log —— 避免噪声
+      return true;
+    }
+    if (!can(next)) {
+      smLog.warn("session.state.illegal", "illegal transition refused", {
+        from: state,
+        to: next,
+        reason: reason || "",
+      });
+      return false;
+    }
+    const prev = state;
+    state = next;
+    const heldMs = Date.now() - stateEnteredAt;
+    stateEnteredAt = Date.now();
+    smLog.info("session.state", "state changed", {
+      from: prev,
+      to: next,
+      held_ms: heldMs,
+      reason: reason || "",
+    });
+    for (const fn of listeners) {
+      try {
+        fn(next, prev);
+      } catch (err) {
+        smLog.error("error.caught", "state listener threw", {
+          where: "stateMachine.listener",
+          err: err && err.message ? err.message : String(err),
+        });
+      }
+    }
+    return true;
+  }
+
+  function onChange(fn) {
+    listeners.add(fn);
+    return () => listeners.delete(fn);
+  }
+
+  return { current, can, transition, onChange };
+}
+
+// 极退化 fallback：仅在 log 未传时使用，只写 stderr。
+function consoleFallback() {
+  return {
+    info(...a) { process.stderr.write(`[sm.info] ${JSON.stringify(a)}\n`); },
+    warn(...a) { process.stderr.write(`[sm.warn] ${JSON.stringify(a)}\n`); },
+    error(...a) { process.stderr.write(`[sm.error] ${JSON.stringify(a)}\n`); },
+    debug() {},
+    child() { return consoleFallback(); },
+  };
+}

package/src-ext/core/toolsServerLifecycle.mjs

@@ -0,0 +1,169 @@
+// toolsServerLifecycle.mjs — agentlinkToolsServer 上电点 + discovery 文件管理
+//
+// bridge 主进程启动时调一次 startToolsServerAndPublishDiscovery({ registry, log }),
+// 它会:
+//   1. 启动 agentlinkToolsServer 在随机端口
+//   2. 把 { url, auth, pid, version, startedAt } 写到
+//      ~/.agentlink/tools-server.json (mode 0o600)
+//   3. 注册 SIGINT/SIGTERM/exit handler 清理 discovery 文件
+//   4. bridge 启动前先检测 stale discovery 文件:有死 PID 直接覆盖 + log info;
+//      有活 PID(不是我们自己)就 abort startup 避免端口冲突
+//
+// 设计要点(见 design.md D9):
+//   - bridge 重启分配新端口时,4 个 runtime 的 MCP 配置不变(都指向稳定的
+//     discovery 文件路径)
+//   - agentlink-mcp-stdio 通过 --discovery 读这个文件拿 url + auth
+//   - auth 防本机其它进程随意调用 tools server
+//
+// spec ref: openspec/changes/host-file-cos-attachment/specs/cli-tools-mcp-fanout/spec.md
+//           Requirement: agentlinkToolsServer started by bridge
+
+import fs from "node:fs/promises";
+import path from "node:path";
+import process from "node:process";
+import { startAgentlinkToolsServer } from "./agentlinkToolsServer.mjs";
+import { getAgentlinkDir } from "./attachAuditLog.mjs";
+
+const DISCOVERY_FILENAME = "tools-server.json";
+
+let cleanupInstalled = false;
+
+/**
+ * 在 bridge 主进程拉起 agentlinkToolsServer + 写 discovery 文件。
+ *
+ * @param {object} opts
+ * @param {object} opts.registry — agentlinkToolsRegistry 实例
+ * @param {object} opts.log
+ * @param {string} [opts.version] — npm_cli 包版本(写到 discovery 文件)
+ * @returns {Promise<{ port: number, baseUrl: string, authToken: string, discoveryPath: string, stop: () => Promise<void> }>}
+ */
+export async function startToolsServerAndPublishDiscovery({ registry, log, version }) {
+  if (!registry) throw new Error("startToolsServerAndPublishDiscovery: registry required");
+  if (!log) throw new Error("startToolsServerAndPublishDiscovery: log required");
+
+  const lifecycleLog = log.child({ comp: "tools-server-lifecycle" });
+  const agentlinkDir = getAgentlinkDir();
+  const discoveryPath = path.join(agentlinkDir, DISCOVERY_FILENAME);
+
+  // 1) 检测 stale discovery
+  await detectAndHandleStaleDiscovery(discoveryPath, lifecycleLog);
+
+  // 2) 启动 server
+  const server = await startAgentlinkToolsServer({ registry, log });
+
+  // 3) 写 discovery 文件
+  await fs.mkdir(agentlinkDir, { recursive: true, mode: 0o700 });
+  const discoveryDoc = {
+    url: server.baseUrl,
+    auth: server.authToken,
+    pid: process.pid,
+    version: version || "unknown",
+    startedAt: new Date().toISOString(),
+  };
+  await fs.writeFile(discoveryPath, JSON.stringify(discoveryDoc, null, 2), { mode: 0o600 });
+  lifecycleLog.info("tools_server.discovery.write", "wrote discovery file", {
+    path: discoveryPath,
+    port: server.port,
+  });
+
+  // 4) 注册 cleanup
+  const stop = async () => {
+    try {
+      await fs.unlink(discoveryPath);
+      lifecycleLog.info("tools_server.discovery.unlink", "removed discovery file");
+    } catch (err) {
+      if (err?.code !== "ENOENT") {
+        lifecycleLog.warn("tools_server.discovery.unlink_failed",
+          "failed to remove discovery file", { err: err?.message });
+      }
+    }
+    await server.close();
+  };
+  installCleanupOnce(stop, lifecycleLog);
+
+  return { ...server, discoveryPath, stop };
+}
+
+async function detectAndHandleStaleDiscovery(discoveryPath, log) {
+  let raw;
+  try {
+    raw = await fs.readFile(discoveryPath, "utf8");
+  } catch (err) {
+    if (err?.code === "ENOENT") return; // 没文件,正常
+    log.warn("tools_server.discovery.read_failed",
+      "discovery file read failed; will overwrite", { err: err?.message });
+    return;
+  }
+  let doc;
+  try {
+    doc = JSON.parse(raw);
+  } catch {
+    log.warn("tools_server.discovery.parse_failed",
+      "discovery file is corrupt; will overwrite");
+    return;
+  }
+  const stalePid = Number(doc?.pid);
+  if (!Number.isFinite(stalePid) || stalePid <= 0) {
+    log.info("tools_server.discovery.no_pid", "discovery file has no pid; overwriting");
+    return;
+  }
+  if (stalePid === process.pid) {
+    log.info("tools_server.discovery.self_pid", "discovery file's pid is self; overwriting");
+    return;
+  }
+  // kill(pid, 0) 探测进程存活:抛 ESRCH 表示进程已死,EPERM 表示进程在但无权
+  // 信号(几乎不会发生在自己 spawn 的 bridge),其它错误一律视为「不确定,保险
+  // 起见拒绝启动」。
+  try {
+    process.kill(stalePid, 0);
+    // 活进程 -> abort startup
+    const msg = `another agentlink bridge appears to be running (pid=${stalePid}). ` +
+      `If this is wrong, remove ${discoveryPath} and retry.`;
+    log.error("tools_server.discovery.alive_pid", msg, { stalePid });
+    throw new Error(msg);
+  } catch (err) {
+    if (err?.code === "ESRCH") {
+      log.info("tools_server.discovery.stale_recovered",
+        "stale discovery file detected; previous bridge is dead, will overwrite", { stalePid });
+      return;
+    }
+    if (err?.code === "EPERM") {
+      log.warn("tools_server.discovery.eperm",
+        "stale pid exists but unsignalable; assuming alive and aborting", { stalePid });
+      throw err;
+    }
+    throw err;
+  }
+}
+
+function installCleanupOnce(stop, log) {
+  if (cleanupInstalled) return;
+  cleanupInstalled = true;
+  let cleaned = false;
+  const handle = async (signal) => {
+    if (cleaned) return;
+    cleaned = true;
+    try {
+      await stop();
+    } catch (err) {
+      log.warn("tools_server.cleanup_failed",
+        "cleanup handler threw", { err: err?.message, signal });
+    }
+  };
+  process.once("SIGINT", () => handle("SIGINT").then(() => process.exit(130)));
+  process.once("SIGTERM", () => handle("SIGTERM").then(() => process.exit(143)));
+  process.once("exit", () => {
+    // 'exit' handler 不能 await,只 best-effort sync unlink。
+    if (cleaned) return;
+    cleaned = true;
+    try { stop(); } catch { /* swallow */ }
+  });
+}
+
+/**
+ * 暴露 discovery 文件路径供其它模块引用(如 mcpRuntimeFanout 写入到 MCP 配置时
+ * 需要这条 path)。
+ */
+export function getDiscoveryPath() {
+  return path.join(getAgentlinkDir(), DISCOVERY_FILENAME);
+}