u-foo 3.0.13 → 3.0.15

package/src/coordination/bus/index.js

@@ -23,6 +23,12 @@ const MessageManager = require("./message");
 const NicknameManager = require("./nickname");
 const Injector = require("./inject");
 const { BusStore } = require("./store");
+const {
+  acquirePollLease,
+  assertFollowPollAllowed,
+  releasePollLease,
+  runPendingPoll,
+} = require("./poll");
 
 /**
  * Event Bus - 项目级 Agent 事件总线
@@ -411,6 +417,90 @@ class EventBus {
     return pending;
   }
 
+  /**
+   * Observe pending messages continuously without claiming or acknowledging.
+   *
+   * This is an explicit fallback for agent hosts whose own background-task
+   * output is their delivery mechanism. Built-in ufoo agent families keep
+   * using their existing injection/internal-consumption paths.
+   */
+  async poll(subscriber, options = {}) {
+    this.ensureBus();
+
+    const target = String(subscriber || "").trim();
+    if (!target) {
+      throw new Error("poll --follow requires <subscriber-id>");
+    }
+
+    // Reject known built-in delivery IDs before loading or writing any shared
+    // bus state. This keeps accidental invocation side-effect free for them.
+    assertFollowPollAllowed(target);
+
+    this.loadBusData();
+    const meta = this.subscriberManager.getSubscriber(target);
+    if (!meta) {
+      throw new Error(`poll --follow requires a joined subscriber: ${target}`);
+    }
+    assertFollowPollAllowed(target, meta);
+
+    const intervalSeconds = Number(options.intervalSeconds);
+    const intervalMs = Math.max(
+      250,
+      Number.isFinite(intervalSeconds) ? intervalSeconds * 1000 : 2000
+    );
+    const pollPidFile = path.join(
+      this.busDir,
+      "pids",
+      `poll-${subscriberToSafeName(target)}.pid`
+    );
+    const lease = acquirePollLease(pollPidFile, { isAlive: isPidAlive });
+    const cleanupLease = () => releasePollLease(lease);
+    process.once("exit", cleanupLease);
+
+    try {
+      // The resident poll process owns liveness for this explicitly opted-in
+      // subscriber. No notifier/injector state is touched.
+      meta.status = "active";
+      meta.pid = process.pid;
+      this.subscriberManager.updateLastSeen(target);
+      this.saveBusData();
+
+      console.log(
+        `[ufoo-poll]<subscriber:${target}> following every ${intervalMs / 1000}s`
+      );
+
+      return await runPendingPoll({
+        intervalMs,
+        signal: options.signal,
+        sleep: options.sleep,
+        maxIterations: options.maxIterations,
+        readPending: () => this.queueManager.peekPending(target),
+        onEvents: async (events) => {
+          console.log(`[ufoo-poll] ${events.length} new pending event(s)`);
+          for (const event of events) {
+            const publisherMeta = this.busData.agents?.[event.publisher];
+            const nick = publisherMeta?.nickname;
+            const fromLabel = nick ? `${event.publisher}(${nick})` : event.publisher;
+            console.log(`[ufoo]<from:${fromLabel || "unknown"}>`);
+            console.log(`Type: ${event.type}/${event.event}`);
+            console.log(`Content: ${JSON.stringify(event.data)}`);
+          }
+          const sequenced = events
+            .map((event) => Number(event && event.seq))
+            .filter((seq) => Number.isFinite(seq) && seq > 0);
+          const throughSeq = sequenced.length === events.length
+            ? Math.max(...sequenced)
+            : 0;
+          const ackSuffix = throughSeq > 0 ? ` --through ${throughSeq}` : "";
+          console.log(`After handling, run: ufoo bus ack ${target}${ackSuffix}`);
+        },
+      });
+    } finally {
+      process.removeListener("exit", cleanupLease);
+      cleanupLease();
+    }
+  }
+
   /**
    * 确认消息
    */
@@ -429,6 +519,24 @@ class EventBus {
     return count;
   }
 
+  /**
+   * Confirm only the displayed portion of a sequenced pending queue.
+   */
+  async ackThrough(subscriber, throughSeq) {
+    this.ensureBus();
+    this.loadBusData();
+
+    const count = await this.messageManager.ackThrough(subscriber, throughSeq);
+
+    if (count > 0) {
+      logOk(`Acknowledged ${count} message(s) through seq=${throughSeq}`);
+    } else {
+      logOk(`No pending messages through seq=${throughSeq}`);
+    }
+
+    return count;
+  }
+
   /**
    * 消费事件
    */

package/src/coordination/bus/message.js

@@ -529,6 +529,10 @@ class MessageManager {
     return this.queueManager.ackPending(subscriber);
   }
 
+  async ackThrough(subscriber, throughSeq) {
+    return this.queueManager.ackPendingThrough(subscriber, throughSeq);
+  }
+
   /**
    * 消费事件（从 offset 开始）
    */

package/src/coordination/bus/poll.js

@@ -0,0 +1,190 @@
+"use strict";
+
+const fs = require("fs");
+const path = require("path");
+
+const BUILTIN_DELIVERY_AGENT_TYPES = new Set([
+  "agy",
+  "antigravity",
+  "claude",
+  "claude-code",
+  "codex",
+  "kimi",
+  "kimi-cli",
+  "kimi-code",
+  "ucode",
+  "ufoo",
+  "ufoo-agent",
+  "ufoo-code",
+]);
+
+function normalizeAgentType(value = "") {
+  return String(value || "").trim().toLowerCase();
+}
+
+function resolveSubscriberAgentType(subscriber, meta = null) {
+  const explicit = normalizeAgentType(meta && meta.agent_type);
+  if (explicit) return explicit;
+  const id = String(subscriber || "").trim();
+  const separator = id.indexOf(":");
+  return normalizeAgentType(separator === -1 ? id : id.slice(0, separator));
+}
+
+function assertFollowPollAllowed(subscriber, meta = null) {
+  const agentType = resolveSubscriberAgentType(subscriber, meta);
+  if (BUILTIN_DELIVERY_AGENT_TYPES.has(agentType)) {
+    throw new Error(
+      `poll --follow is disabled for built-in delivery agent type "${agentType}"`
+    );
+  }
+  return agentType;
+}
+
+function eventIdentity(event = {}) {
+  const seq = Number(event && event.seq);
+  if (Number.isFinite(seq) && seq > 0) {
+    return `seq:${seq}`;
+  }
+  return `event:${JSON.stringify(event || {})}`;
+}
+
+function enumerateEventKeys(events = []) {
+  const occurrences = new Map();
+  return events.map((event) => {
+    const identity = eventIdentity(event);
+    const occurrence = occurrences.get(identity) || 0;
+    occurrences.set(identity, occurrence + 1);
+    return {
+      event,
+      key: `${identity}#${occurrence}`,
+    };
+  });
+}
+
+function defaultSleep(ms) {
+  return new Promise((resolve) => setTimeout(resolve, ms));
+}
+
+function defaultIsPidAlive(pid) {
+  try {
+    process.kill(pid, 0);
+    return true;
+  } catch (err) {
+    return Boolean(err && err.code === "EPERM");
+  }
+}
+
+function acquirePollLease(pidFile, options = {}) {
+  const pid = Number(options.pid) || process.pid;
+  const isAlive = typeof options.isAlive === "function"
+    ? options.isAlive
+    : defaultIsPidAlive;
+
+  fs.mkdirSync(path.dirname(pidFile), { recursive: true });
+
+  if (fs.existsSync(pidFile)) {
+    let existing = 0;
+    try {
+      existing = Number.parseInt(fs.readFileSync(pidFile, "utf8").trim(), 10);
+    } catch {
+      existing = 0;
+    }
+    if (Number.isFinite(existing) && existing > 0 && isAlive(existing)) {
+      throw new Error(`poll --follow is already running (pid=${existing})`);
+    }
+    fs.rmSync(pidFile, { force: true });
+  }
+
+  let fd;
+  try {
+    fd = fs.openSync(pidFile, "wx");
+    fs.writeFileSync(fd, `${pid}\n`, "utf8");
+  } catch (err) {
+    if (err && err.code === "EEXIST") {
+      throw new Error("poll --follow is already starting for this subscriber");
+    }
+    throw err;
+  } finally {
+    if (typeof fd === "number") fs.closeSync(fd);
+  }
+
+  return { pid, pidFile };
+}
+
+function releasePollLease(lease) {
+  if (!lease || !lease.pidFile) return false;
+  try {
+    const existing = Number.parseInt(
+      fs.readFileSync(lease.pidFile, "utf8").trim(),
+      10
+    );
+    if (existing !== lease.pid) return false;
+    fs.rmSync(lease.pidFile, { force: true });
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+async function runPendingPoll(options = {}) {
+  const readPending = options.readPending;
+  const onEvents = options.onEvents;
+  const sleep = options.sleep || defaultSleep;
+  const signal = options.signal || null;
+  const intervalMs = Math.max(250, Number(options.intervalMs) || 2000);
+  const maxIterations = Number.isFinite(options.maxIterations)
+    ? Math.max(0, Math.floor(options.maxIterations))
+    : Infinity;
+
+  if (typeof readPending !== "function") {
+    throw new Error("runPendingPoll requires readPending");
+  }
+  if (typeof onEvents !== "function") {
+    throw new Error("runPendingPoll requires onEvents");
+  }
+  if (maxIterations === 0) {
+    return { iterations: 0 };
+  }
+
+  let inFlightKeys = new Set();
+  let iterations = 0;
+
+  while (!signal || !signal.aborted) {
+    // eslint-disable-next-line no-await-in-loop
+    const pending = await readPending();
+    const keyed = enumerateEventKeys(Array.isArray(pending) ? pending : []);
+    const currentKeys = new Set(keyed.map((entry) => entry.key));
+    const hasUnacknowledgedBatch = Array.from(inFlightKeys)
+      .some((key) => currentKeys.has(key));
+
+    if (!hasUnacknowledgedBatch) {
+      inFlightKeys = new Set();
+    }
+
+    if (inFlightKeys.size === 0 && keyed.length > 0) {
+      const batch = keyed.map((entry) => entry.event);
+      // eslint-disable-next-line no-await-in-loop
+      await onEvents(batch);
+      inFlightKeys = currentKeys;
+    }
+
+    iterations += 1;
+    if (iterations >= maxIterations || (signal && signal.aborted)) break;
+
+    // eslint-disable-next-line no-await-in-loop
+    await sleep(intervalMs);
+  }
+
+  return { iterations };
+}
+
+module.exports = {
+  BUILTIN_DELIVERY_AGENT_TYPES,
+  acquirePollLease,
+  assertFollowPollAllowed,
+  enumerateEventKeys,
+  eventIdentity,
+  releasePollLease,
+  resolveSubscriberAgentType,
+  runPendingPoll,
+};

package/src/coordination/bus/queue.js

@@ -5,7 +5,11 @@ const {
   ensureDir,
   truncateFile,
 } = require("./utils");
-const { DeliveryQueue, stripQueueEnvelope } = require("./deliveryQueue");
+const {
+  DeliveryQueue,
+  positiveSeq,
+  stripQueueEnvelope,
+} = require("./deliveryQueue");
 
 /**
  * 队列管理器
@@ -87,6 +91,15 @@ class QueueManager {
     return this.getDeliveryQueue(subscriber).readPending().map(stripQueueEnvelope);
   }
 
+  /**
+   * Non-mutating pending read for opt-in background observers.
+   *
+   * Unlike readPending(), this deliberately does not recover stale claims.
+   */
+  async peekPending(subscriber) {
+    return this.getDeliveryQueue(subscriber).readPendingRaw().map(stripQueueEnvelope);
+  }
+
   /**
    * 追加待处理消息
    */
@@ -122,6 +135,36 @@ class QueueManager {
     return count;
   }
 
+  /**
+   * Acknowledge only sequenced events up to and including throughSeq.
+   *
+   * Later arrivals remain pending, which prevents a background poll consumer
+   * from clearing messages that were not part of the emitted batch.
+   */
+  async ackPendingThrough(subscriber, throughSeq) {
+    const limit = Number(throughSeq);
+    if (!Number.isFinite(limit) || limit <= 0) {
+      throw new Error("ack --through requires a positive sequence");
+    }
+
+    const deliveryQueue = this.getDeliveryQueue(subscriber);
+    let count = 0;
+    while (true) {
+      const claim = deliveryQueue.claimNext();
+      if (!claim) break;
+
+      const seq = positiveSeq(claim.event);
+      if (seq === 0 || seq > limit) {
+        deliveryQueue.restoreClaim(claim);
+        break;
+      }
+
+      deliveryQueue.completeClaim(claim);
+      count += 1;
+    }
+    return count;
+  }
+
   /**
    * 检查是否有待处理消息
    */

package/src/coordination/bus/store.js

@@ -95,7 +95,7 @@ class BusStore {
   ensure() {
     if (!fs.existsSync(this.busDir) || !fs.existsSync(this.paths.agentDir)) {
       throw new Error(
-        "Event bus not initialized. Please run: ufoo bus init or /uinit"
+        "Event bus not initialized. Please run: ufoo init --targets bus"
       );
     }
   }

package/src/coordination/context/doctor.js

@@ -86,7 +86,7 @@ class ContextDoctor {
    * Lint bundled context skill.
    */
   lintProtocol() {
-    const repoSkill = path.join(this.projectRoot, "SKILLS", "uctx", "SKILL.md");
+    const repoSkill = path.join(this.projectRoot, "SKILLS", "ufoo-context", "SKILL.md");
 
     if (!fs.existsSync(repoSkill)) {
       console.log("No bundled context skill found (skipping protocol lint)");
@@ -94,7 +94,7 @@ class ContextDoctor {
     }
 
     console.log(`Linting bundled context skill: ${repoSkill}`);
-    this.checkFile(repoSkill, "SKILLS/uctx/SKILL.md");
+    this.checkFile(repoSkill, "SKILLS/ufoo-context/SKILL.md");
 
     return !this.failed;
   }

package/SKILLS/ubus/SKILL.md

@@ -1,250 +0,0 @@
----
-name: ubus
-description: |
-  Check and handle pending event-bus messages when /ubus is explicitly invoked.
-  Use when: (1) asked to check messages, (2) view bus status, (3) use watch/listen/auto modes.
-  If not yet joined bus, will auto-join.
----
-
-# /ubus - Check Event Bus Messages
-
-Check and handle pending messages on the event bus when `/ubus` is explicitly
-invoked.
-
-## Arguments
-
-- `/ubus` - Pull pending messages and show status
-- `/ubus watch` - Start background auto-notification (title badge + bell + notification center)
-- `/ubus stop` - Stop background auto-notification
-- `/ubus listen` - Foreground continuous listener, print new messages (suitable for side terminal)
-- `/ubus auto` - Unattended auto-execute (auto-inject `/ubus` and press Enter)
-
-## Execution Flow
-
-### 1. Check if .ufoo/bus exists
-
-```bash
-if [[ ! -d ".ufoo/bus" ]]; then
-  echo "Event bus not initialized, please run /uinit and select bus module"
-  exit
-fi
-```
-
-### 2. Get or create subscriber ID
-
-**IMPORTANT**: Always check for existing subscriber ID first to avoid creating duplicates.
-
-```bash
-# Reuse existing subscriber first (env -> whoami), join only if missing
-SUBSCRIBER="${UFOO_SUBSCRIBER_ID:-$(ufoo bus whoami 2>/dev/null || true)}"
-if [ -n "$SUBSCRIBER" ]; then
-  echo "Using existing subscriber ID: $SUBSCRIBER"
-else
-  # Not launched via uclaude/ucodex, need to join manually
-  SUBSCRIBER=$(ufoo bus join | tail -n 1)
-  echo "Joined event bus: $SUBSCRIBER"
-  # Example output: codex:0e293156 (nickname: codex-1)
-fi
-```
-
-**Why this matters**:
-- `uclaude`/`ucodex` automatically set `UFOO_SUBSCRIBER_ID` during launch
-- `ufoo bus whoami` can recover current ID even when env is missing
-- Re-joining may create identity drift and message routing issues
-- Always reuse existing ID when available
-
-To join with a custom nickname:
-
-```bash
-ufoo bus join [session-id] [agent-type] "your-nickname"
-# Example: ufoo bus join abc123 claude-code "architect"
-```
-
-### 3. Handle arguments
-
-If argument is `watch`, use **Bash tool's `run_in_background: true`** to start background notification:
-
-```bash
-# Title badge + bell + notification center (no accessibility permission needed)
-ufoo bus alert "$SUBSCRIBER" 2 --notify --daemon
-```
-
-If argument is `listen`, foreground blocking listener (no background task tool needed):
-
-```bash
-ufoo bus listen "$SUBSCRIBER" --from-beginning
-```
-
-If argument is `auto`, use unattended auto-execute:
-
-```bash
-# Start daemon (background resident), auto-inject /ubus + Enter on new message
-ufoo bus daemon --daemon
-```
-
-Tips:
-- Need to use `uclaude`/`ucodex` wrapper to start Claude Code/Codex (auto-records tty)
-- Terminal.app needs Accessibility permission (for keyboard input injection)
-
-If argument is `stop`, stop background notification:
-
-```bash
-ufoo bus alert "$SUBSCRIBER" --stop
-```
-
-### 4. Check pending events
-
-```bash
-ufoo bus check "$SUBSCRIBER"
-```
-
-The system automatically prefixes each message with `[ufoo]<from:id(nickname)>` to identify the sender. You do not need to add this prefix yourself.
-
-If pending events exist, output looks like:
-
-```
-[ufoo]<from:claude-code:abc123(architect)>
-  Type: message/targeted/message
-  Content: {"message":"review src/main.ts","injection_mode":"immediate"}
-```
-
-- The sender ID and nickname are in the `[ufoo]<from:...>` line — use the ID to reply
-- The actual task is in `Content.message`
-
-### 5. IMPORTANT: Acknowledge messages after handling
-
-After you have read and processed the messages, you MUST acknowledge them to prevent repeated notifications:
-
-```bash
-ufoo bus ack "$SUBSCRIBER"
-```
-
-**This is critical** - if you don't ack, the runtime may retry delivery or keep
-the event pending.
-
-**Default behavior is ack-only, no reply.** If there's nothing to do (no actionable task, no question to answer, no follow-up the sender genuinely needs), just ack and stop. Silence is a valid response — see "Handling Received Messages" below for when a reply IS warranted.
-
-### 6. Routing Override
-
-If the message explicitly instructs you to report to a specific PM/DEV/TEST ID, **send the result to that ID instead of the publisher**.
-
-### 5. Show bus status
-
-```bash
-ufoo bus status
-```
-
-Output (now includes nicknames):
-
-```
-=== Event Bus Status ===
-My identity: claude-code:xyz789
-Online agents: 2
-  - claude-code:abc123 (architect)
-  - claude-code:xyz789 (dev-lead)
-Recent events: 5
-```
-
-## Managing Nicknames
-
-### View and Change Nicknames
-
-```bash
-# Change an agent's nickname
-ufoo bus rename <subscriber-id> "new-nickname"
-# Example: ufoo bus rename claude-code:47b1d525 "backend-dev"
-
-# Nickname alias command
-ufoo bus nick <subscriber-id> "new-nickname"
-```
-
-**Important Notes:**
-- Nicknames must be globally unique
-- Cannot change nickname during join (use `rename` command instead)
-- Re-joining with same subscriber ID will reuse existing nickname
-- Auto-generated nicknames: `codex-1`, `codex-2`, `claude-1`, `claude-2`, etc.
-
-## Handling Received Messages
-
-When receiving targeted messages, the default flow is **execute → ack → stop**.
-Replies are the exception, not the default.
-
-1. **Understand request** — Read message content.
-2. **Execute task** — If the message delegates a task, do it.
-3. **`ufoo bus ack "$SUBSCRIBER"`** — Always ack, even when not replying.
-4. **Reply ONLY when substantive.** Send `ufoo bus send` to the sender only if at least one of the following is true:
-   - The sender asked a question → reply with the answer.
-   - The sender delegated a task → reply with the result / artifact / status.
-   - You discovered something the sender needs to proceed → reply with that fact.
-
-   ```bash
-   # Use this only when the criteria above are met.
-   ufoo bus send "<sender-id>" "<substantive-reply>"
-   ```
-
-### Anti-pattern: greet / ack loops
-
-If the inbound message is itself just a greeting, an acknowledgment, or a
-pleasantry, **do not reply**. Acking is enough. A bare-acknowledgment reply
-will be auto-injected on the other side, triggering them to reply in kind,
-and the two of you will ping-pong forever.
-
-| Inbound | Reply? |
-|---|---|
-| `👋` / `hi` / `hello` / `你好` | ❌ ack only |
-| `👍` / `ok` / `收到` / `thanks` / `noted` | ❌ ack only |
-| `已完成 / done / finished` (without a result the sender asked for) | ❌ ack only |
-| `请把 src/foo.ts 改成 ...` (task) | ✅ reply with result |
-| `这个 bug 的根因是什么？` (question) | ✅ reply with answer |
-| `我帮你找到了 X，需要你做 Y` (request) | ✅ reply with status |
-
-When in doubt: ack and stop. If the sender genuinely needs something from you,
-they will follow up with a concrete question or task.
-
-## Sending Messages
-
-After sending a message, do not run `/ubus`, poll, sleep, or wait for a reply.
-Continue the current task. Any follow-up message will be automatically injected
-into your prompt/session.
-
-### Smart Routing (when you don't know the target ID)
-
-If the user says "notify codex to do X" without specifying an ID, use smart routing:
-
-```bash
-# Step 1: Find candidates
-ufoo bus resolve "$SUBSCRIBER" codex
-
-# Output shows:
-# - If only 1 codex: directly shows the ID
-# - If multiple: shows each with nickname and message history
-```
-
-Based on the output:
-- **Single match**: Use that ID directly
-- **Multiple matches**: Analyze the message history to find the right target
-  - Look for context clues in previous conversations
-  - If still unclear, ask the user which one, or send to all of that type
-
-### Direct Send
-
-```bash
-# Send to specific Agent by full ID
-ufoo bus send "claude-code:abc123" "message content"
-
-# Send to specific Agent by nickname (NEW!)
-ufoo bus send "architect" "message content"
-ufoo bus send "backend-dev" "message content"
-
-# Send to all Agents of same type
-ufoo bus send "codex" "message content"
-
-# Broadcast to everyone
-ufoo bus broadcast "message content"
-```
-
-**Target Resolution Priority:**
-1. Exact subscriber ID (e.g., `claude-code:abc123`)
-2. Nickname match (e.g., `architect` → resolves to subscriber ID)
-3. Agent type (e.g., `codex` → all codex agents)
-4. Wildcard (`*` → all agents)