u-foo 1.0.3 → 1.0.6

package/src/bus/API_DESIGN.md

@@ -0,0 +1,204 @@
+# Event Bus JavaScript API 设计
+
+## 概述
+
+已将 Event Bus 从 bash 迁移到 JavaScript，核心能力由 `src/bus` 模块提供。
+
+## 核心类设计
+
+```javascript
+class EventBus {
+  constructor(projectRoot);
+
+  // 初始化
+  async init();
+
+  // 订阅者管理
+  async join(sessionId, agentType, nickname);
+  async leave(subscriber);
+  async rename(subscriber, nickname);
+  async whoami(); // 获取当前订阅者 ID
+
+  // 消息发送
+  async send(target, message, publisher);
+  async broadcast(message, publisher);
+
+  // 消息接收
+  async check(subscriber, autoAck);
+  async ack(subscriber);
+  async consume(subscriber, fromBeginning);
+
+  // 查询与路由
+  async status();
+  async resolve(myId, targetType);
+
+  // 后台监听
+  async alert(subscriber, interval, options);
+  async listen(subscriber, options);
+}
+```
+
+## 文件结构
+
+```
+src/bus/
+├── index.js           # EventBus 主类
+├── subscriber.js      # 订阅者管理
+├── message.js         # 消息发送/接收
+├── queue.js           # 队列管理（offset, pending）
+├── nickname.js        # 昵称解析
+├── daemon.js          # bus daemon（自动注入 /ubus）
+├── utils.js           # 工具函数
+└── API_DESIGN.md      # 本文件
+```
+
+## 数据结构
+
+### .ufoo/agent/all-agents.json
+```json
+{
+  "schema_version": 1,
+  "created_at": "2026-01-29T...",
+  "agents": {
+    "claude-code:abc123": {
+      "agent_type": "claude-code",
+      "nickname": "architect",
+      "status": "active",
+      "joined_at": "...",
+      "last_seen": "...",
+      "pid": 12345,
+      "tty": "/dev/ttys001"
+    }
+  }
+}
+```
+
+### events/YYYY-MM-DD.jsonl
+```json
+{"seq":1,"timestamp":"...","type":"message/targeted","event":"message","publisher":"...","target":"...","data":{...}}
+```
+
+### queues/{subscriber}/pending.jsonl
+```json
+{"seq":1,"timestamp":"...","type":"message/targeted","event":"message","publisher":"...","data":{...}}
+```
+
+### queues/{subscriber}/offset
+```
+5
+```
+
+## 关键功能实现
+
+### 1. 消息路由（支持昵称）
+
+```javascript
+async resolveTarget(target) {
+  // 优先级：
+  // 1. 精确订阅者 ID (claude-code:abc123)
+  // 2. 昵称匹配 (architect -> claude-code:abc123)
+  // 3. 代理类型 (codex -> 所有 codex 代理)
+  // 4. 通配符 (* -> 所有代理)
+}
+```
+
+### 2. 队列管理
+
+```javascript
+class QueueManager {
+  async getOffset(subscriber);
+  async setOffset(subscriber, seq);
+  async appendPending(subscriber, event);
+  async readPending(subscriber);
+  async clearPending(subscriber);
+}
+```
+
+### 3. 序号生成（全局唯一）
+
+```javascript
+async getNextSeq() {
+  // 读取所有 events/*.jsonl 文件的最后一行
+  // 返回 max(seq) + 1
+  // 保证全局唯一、单调递增
+}
+```
+
+### 4. 昵称冲突检测
+
+```javascript
+async ensureUniqueNickname(nickname, excludeSubscriber) {
+  // 检查 all-agents.json 中是否已存在该昵称
+  // 返回是否唯一
+}
+```
+
+## 向后兼容性
+
+### CLI 接口保持不变
+
+```bash
+ufoo bus init
+ufoo bus join [session] [type] [nick]
+ufoo bus send <target> <message>
+# ... 所有命令保持原样
+```
+
+### 环境变量支持
+
+- `AI_BUS_PUBLISHER` - 发送者 ID
+- `CLAUDE_SESSION_ID` / `CODEX_SESSION_ID` - 会话 ID
+- `UFOO_NICKNAME` - 昵称
+
+## 错误处理
+
+```javascript
+class BusError extends Error {
+  constructor(code, message) {
+    super(message);
+    this.code = code;
+  }
+}
+
+// 错误码：
+// BUS_NOT_INITIALIZED
+// SUBSCRIBER_NOT_FOUND
+// NICKNAME_CONFLICT
+// INVALID_TARGET
+// ...
+```
+
+## 测试策略
+
+### 单元测试
+- 每个模块独立测试
+- Mock 文件系统操作
+
+### 集成测试
+- 完整消息流测试（send -> check -> ack）
+- 多订阅者场景
+- 昵称冲突处理
+
+### 性能测试
+- 消息发送延迟 < 50ms
+- 序号生成 < 10ms
+- 状态查询 < 100ms
+
+## 迁移检查清单
+
+- [ ] init 命令
+- [ ] join/leave 命令
+- [ ] send/broadcast 命令
+- [ ] check/ack 命令
+- [ ] status 命令
+- [ ] resolve 命令
+- [ ] rename 命令（支持昵称）
+- [ ] consume 命令
+- [ ] alert 后台监听
+- [ ] listen 前台监听
+- [ ] autotrigger 自动触发
+- [ ] 昵称解析（send 支持昵称）
+- [ ] 全局序号唯一性
+- [ ] 文件并发安全
+- [ ] 错误处理和日志
+- [ ] CLI 向后兼容

package/src/bus/activate.js

@@ -0,0 +1,156 @@
+const fs = require("fs");
+const { getUfooPaths } = require("../ufoo/paths");
+const { spawn, spawnSync } = require("child_process");
+
+/**
+ * 激活指定 agent 的终端
+ *
+ * 支持的方式：
+ * - tmux: 使用 tmux select-pane 激活
+ * - terminal: 使用 AppleScript 通过 tty 定位并激活 Terminal.app 的 tab/window
+ * - internal: 不支持自动激活（由 chat PTY view 处理）
+ */
+class AgentActivator {
+  constructor(projectRoot) {
+    this.projectRoot = projectRoot;
+    const paths = getUfooPaths(projectRoot);
+    this.agentsFile = paths.agentsFile;
+  }
+
+  /**
+   * 获取 agent 信息
+   */
+  getAgentInfo(agentId) {
+    try {
+      if (!fs.existsSync(this.agentsFile)) {
+        throw new Error("Bus not initialized");
+      }
+
+      const busData = JSON.parse(fs.readFileSync(this.agentsFile, "utf8"));
+      const meta = busData.agents?.[agentId];
+
+      if (!meta) {
+        throw new Error(`Agent not found: ${agentId}`);
+      }
+
+      return {
+        id: agentId,
+        nickname: meta.nickname || "",
+        tty: meta.tty || "",
+        tmux_pane: meta.tmux_pane || "",
+        launch_mode: meta.launch_mode || "",
+      };
+    } catch (err) {
+      throw new Error(`Failed to get agent info: ${err.message}`);
+    }
+  }
+
+  /**
+   * 激活 tmux pane
+   */
+  activateTmuxPane(paneId) {
+    return new Promise((resolve, reject) => {
+      // 首先检查 pane 是否存在
+      const checkProc = spawn("tmux", ["list-panes", "-a", "-F", "#{pane_id}"]);
+      let output = "";
+
+      checkProc.stdout.on("data", (data) => {
+        output += data.toString();
+      });
+
+      checkProc.on("close", (code) => {
+        if (code !== 0) {
+          reject(new Error("tmux is not running"));
+          return;
+        }
+
+        const panes = output.trim().split("\n");
+        if (!panes.includes(paneId)) {
+          reject(new Error(`tmux pane not found: ${paneId}`));
+          return;
+        }
+
+        // 激活 pane（选择 window 和 pane）
+        const selectProc = spawn("tmux", ["select-pane", "-t", paneId]);
+
+        selectProc.on("close", (selectCode) => {
+          if (selectCode === 0) {
+            resolve();
+          } else {
+            reject(new Error("Failed to select tmux pane"));
+          }
+        });
+
+        selectProc.on("error", reject);
+      });
+
+      checkProc.on("error", reject);
+    });
+  }
+
+  /**
+   * 通过 tty 激活 Terminal.app 中对应的 tab/window
+   */
+  activateTerminalByTty(ttyPath) {
+    if (process.platform !== "darwin") {
+      throw new Error("Terminal activation is only supported on macOS");
+    }
+    if (!ttyPath) {
+      throw new Error("Cannot activate: tty path required");
+    }
+
+    const script = `
+tell application "Terminal"
+  repeat with w in windows
+    repeat with t in tabs of w
+      if tty of t is "${ttyPath.replace(/\\/g, "\\\\").replace(/"/g, '\\"')}" then
+        set selected tab of w to t
+        set index of w to 1
+        activate
+        return "ok"
+      end if
+    end repeat
+  end repeat
+  return "not found"
+end tell`;
+
+    const result = spawnSync("osascript", ["-e", script], {
+      encoding: "utf8",
+      timeout: 5000,
+    });
+
+    if (result.status !== 0) {
+      throw new Error(`AppleScript failed: ${(result.stderr || "").trim()}`);
+    }
+
+    const output = (result.stdout || "").trim();
+    if (output === "not found") {
+      throw new Error(`Terminal tab not found for tty: ${ttyPath}`);
+    }
+  }
+
+  /**
+   * 激活 agent 的终端
+   */
+  async activate(agentId) {
+    const info = this.getAgentInfo(agentId);
+
+    if (info.launch_mode === "internal" || info.launch_mode === "internal-pty") {
+      throw new Error("Internal mode agents cannot be activated (no terminal window)");
+    }
+
+    if (info.launch_mode === "tmux" && info.tmux_pane) {
+      await this.activateTmuxPane(info.tmux_pane);
+      return;
+    }
+
+    if (info.launch_mode === "terminal" && info.tty) {
+      this.activateTerminalByTty(info.tty);
+      return;
+    }
+
+    throw new Error("Cannot activate: missing tty or tmux_pane for agent");
+  }
+}
+
+module.exports = AgentActivator;

package/src/bus/daemon.js

@@ -0,0 +1,308 @@
+const fs = require("fs");
+const path = require("path");
+const { readJSON, writeJSON, isPidAlive, isAgentPidAlive, ensureDir, safeNameToSubscriber, subscriberToSafeName } = require("./utils");
+const Injector = require("./inject");
+const QueueManager = require("./queue");
+
+/**
+ * Bus Daemon - 监控消息并自动注入命令
+ */
+class BusDaemon {
+  constructor(busDir, agentsFile, daemonDir, interval = 2000) {
+    this.busDir = busDir;
+    this.agentsFile = agentsFile;
+    this.interval = interval;
+    this.daemonDir = daemonDir;
+    this.pidFile = path.join(this.daemonDir, "daemon.pid");
+    this.logFile = path.join(this.daemonDir, "daemon.log");
+    this.countsDir = path.join(this.daemonDir, "counts", `${process.pid}`);
+    this.running = false;
+    this.cleanupCounter = 0;
+    this.cleanupInterval = 5; // 每 5 个周期清理一次
+
+    this.queueManager = new QueueManager(busDir);
+    this.injector = new Injector(busDir, agentsFile);
+  }
+
+  /**
+   * 检查 daemon 是否正在运行
+   */
+  isRunning() {
+    if (!fs.existsSync(this.pidFile)) {
+      return false;
+    }
+
+    const pid = parseInt(fs.readFileSync(this.pidFile, "utf8").trim(), 10);
+    return isPidAlive(pid);
+  }
+
+  /**
+   * 获取运行中的 daemon PID
+   */
+  getRunningPid() {
+    if (!fs.existsSync(this.pidFile)) {
+      return null;
+    }
+
+    const pid = parseInt(fs.readFileSync(this.pidFile, "utf8").trim(), 10);
+    return isPidAlive(pid) ? pid : null;
+  }
+
+  /**
+   * 启动 daemon
+   */
+  async start(background = false) {
+    // 检查是否已经在运行
+    if (this.isRunning()) {
+      const pid = this.getRunningPid();
+      console.log(`[daemon] Already running (pid=${pid})`);
+      return;
+    }
+    ensureDir(this.daemonDir);
+    ensureDir(path.join(this.daemonDir, "counts"));
+
+    if (background) {
+      // 后台模式：spawn 独立进程
+      const { spawn } = require("child_process");
+      const logStream = fs.openSync(this.logFile, "a");
+
+      const child = spawn(
+        process.execPath,
+        [
+          path.join(__dirname, "..", "..", "bin", "ufoo.js"),
+          "bus",
+          "daemon",
+          "--interval",
+          String(this.interval / 1000),
+        ],
+        {
+          detached: true,
+          stdio: ["ignore", logStream, logStream],
+          cwd: process.cwd(),
+        }
+      );
+
+      child.unref();
+
+      // 等待 PID 文件创建
+      await new Promise((resolve) => setTimeout(resolve, 500));
+
+      const pid = this.getRunningPid();
+      console.log(`[daemon] Started in background (pid=${pid}, log: ${this.logFile})`);
+    } else {
+      // 前台模式
+      this.run();
+    }
+  }
+
+  /**
+   * 停止 daemon
+   */
+  stop() {
+    const pid = this.getRunningPid();
+    if (!pid) {
+      console.log("[daemon] Not running");
+      return;
+    }
+
+    try {
+      process.kill(pid, "SIGTERM");
+      console.log(`[daemon] Stopped (pid=${pid})`);
+      if (fs.existsSync(this.pidFile)) {
+        fs.unlinkSync(this.pidFile);
+      }
+    } catch (err) {
+      console.error(`[daemon] Failed to stop: ${err.message}`);
+    }
+  }
+
+  /**
+   * 显示 daemon 状态
+   */
+  status() {
+    const pid = this.getRunningPid();
+    if (pid) {
+      console.log(`[daemon] Running (pid=${pid})`);
+    } else {
+      console.log("[daemon] Not running");
+      // 清理过时的 PID 文件
+      if (fs.existsSync(this.pidFile)) {
+        fs.unlinkSync(this.pidFile);
+      }
+    }
+  }
+
+  /**
+   * 运行 daemon（前台）
+   */
+  run() {
+    // 记录 PID
+    ensureDir(path.dirname(this.pidFile));
+    fs.writeFileSync(this.pidFile, `${process.pid}\n`, "utf8");
+
+    // 设置清理钩子
+    const cleanup = () => {
+      this.running = false;
+      if (fs.existsSync(this.pidFile)) {
+        fs.unlinkSync(this.pidFile);
+      }
+      if (fs.existsSync(this.countsDir)) {
+        fs.rmSync(this.countsDir, { recursive: true, force: true });
+      }
+    };
+
+    process.on("SIGTERM", cleanup);
+    process.on("SIGINT", cleanup);
+    process.on("exit", cleanup);
+
+    // 创建计数目录
+    ensureDir(this.countsDir);
+
+    console.log(`[daemon] Started (pid=${process.pid}, interval=${this.interval / 1000}s)`);
+    console.log(`[daemon] Watching: ${this.busDir}/queues/*/pending.jsonl`);
+
+    this.running = true;
+    this.watchLoop();
+  }
+
+  /**
+   * 主监控循环
+   */
+  async watchLoop() {
+    while (this.running) {
+      try {
+        // 定期清理死掉的 agent
+        this.cleanupCounter++;
+        if (this.cleanupCounter >= this.cleanupInterval) {
+          await this.cleanupDeadAgents();
+          this.cleanupCounter = 0;
+        }
+
+        // 检查所有订阅者的队列
+        await this.checkQueues();
+      } catch (err) {
+        console.error(`[daemon] Error: ${err.message}`);
+      }
+
+      // 等待下一个周期
+      await new Promise((resolve) => setTimeout(resolve, this.interval));
+    }
+  }
+
+  /**
+   * 检查所有队列
+   */
+  async checkQueues() {
+    const queuesDir = path.join(this.busDir, "queues");
+    if (!fs.existsSync(queuesDir)) {
+      return;
+    }
+
+    const subscribers = fs.readdirSync(queuesDir);
+
+    for (const safeName of subscribers) {
+      const pendingFile = path.join(queuesDir, safeName, "pending.jsonl");
+      if (!fs.existsSync(pendingFile)) {
+        continue;
+      }
+
+      // 获取当前消息数
+      let count = 0;
+      if (fs.statSync(pendingFile).size > 0) {
+        const content = fs.readFileSync(pendingFile, "utf8").trim();
+        count = content ? content.split("\n").length : 0;
+      }
+
+      // 获取上次的消息数
+      const lastCount = this.getLastCount(safeName);
+
+      // 如果有新消息，注入命令
+      if (count > lastCount) {
+        const subscriber = safeNameToSubscriber(safeName);
+        const now = new Date().toISOString().split("T")[1].slice(0, 8);
+        console.log(`[daemon] ${now} New message for ${subscriber} (${lastCount} -> ${count})`);
+
+        try {
+          await this.injector.inject(subscriber);
+          console.log(`[daemon] Injected /bus into ${subscriber}`);
+        } catch (err) {
+          console.error(`[daemon] Failed to inject: ${err.message}`);
+        }
+      }
+
+      // 更新计数
+      this.setLastCount(safeName, count);
+    }
+  }
+
+  /**
+   * 获取上次的消息计数
+   */
+  getLastCount(safeName) {
+    const countFile = path.join(this.countsDir, safeName);
+    if (!fs.existsSync(countFile)) {
+      return 0;
+    }
+    const content = fs.readFileSync(countFile, "utf8").trim();
+    return parseInt(content, 10) || 0;
+  }
+
+  /**
+   * 设置消息计数
+   */
+  setLastCount(safeName, count) {
+    const countFile = path.join(this.countsDir, safeName);
+    ensureDir(path.dirname(countFile));
+    fs.writeFileSync(countFile, `${count}\n`, "utf8");
+  }
+
+  /**
+   * 清理死掉的 agent
+   */
+  async cleanupDeadAgents() {
+    const agentsFile = this.agentsFile;
+    if (!fs.existsSync(agentsFile)) {
+      return;
+    }
+
+    const busData = readJSON(agentsFile);
+    if (!busData || !busData.agents) {
+      return;
+    }
+
+    let changed = false;
+
+    for (const [subscriber, meta] of Object.entries(busData.agents)) {
+      if (meta.status !== "active") {
+        continue;
+      }
+
+      // 检查 PID 是否仍然存活
+      if (meta.pid && !isAgentPidAlive(meta.pid)) {
+        const now = new Date().toISOString().split("T")[1].slice(0, 8);
+        console.log(`[daemon] ${now} Agent ${subscriber} (pid=${meta.pid}) is dead, marking inactive`);
+
+        meta.status = "inactive";
+        changed = true;
+
+        // 清理队列目录和 offset
+        const safeName = subscriberToSafeName(subscriber);
+        const queueDir = path.join(this.busDir, "queues", safeName);
+        const offsetFile = path.join(this.busDir, "offsets", `${safeName}.offset`);
+
+        if (fs.existsSync(queueDir)) {
+          fs.rmSync(queueDir, { recursive: true, force: true });
+        }
+        if (fs.existsSync(offsetFile)) {
+          fs.unlinkSync(offsetFile);
+        }
+      }
+    }
+
+    if (changed) {
+      writeJSON(agentsFile, busData);
+    }
+  }
+}
+
+module.exports = BusDaemon;