u-foo 2.3.11 → 2.3.12

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "u-foo",
-  "version": "2.3.11",
+  "version": "2.3.12",
   "description": "Multi-Agent Workspace Protocol. Just add u. claude → uclaude, codex → ucodex.",
   "license": "SEE LICENSE IN LICENSE",
   "homepage": "https://ufoo.dev",

package/src/agent/activityStateWriter.js

@@ -1,4 +1,6 @@
 const fs = require("fs");
+const { readJSON, writeJSON } = require("../bus/utils");
+const { appendAgentRegistryDiagnostic } = require("../ufoo/agentRegistryDiagnostics");
 
 /**
  * Centralized helper for writing activity_state to all-agents.json.
@@ -12,8 +14,17 @@ function writeActivityState(agentsFilePath, subscriber, state, options = {}) {
   const { since, force = false } = options;
   try {
     if (!agentsFilePath || !fs.existsSync(agentsFilePath)) return false;
-    const data = JSON.parse(fs.readFileSync(agentsFilePath, "utf8"));
-    if (!data.agents || !data.agents[subscriber]) return false;
+    const data = readJSON(agentsFilePath, null);
+    if (!data) return false;
+    if (!data.agents || !data.agents[subscriber]) {
+      appendAgentRegistryDiagnostic(agentsFilePath, "activity_state_subscriber_missing", {
+        source: "agent.activityStateWriter.writeActivityState",
+        subscriber,
+        state,
+        known_ids: Object.keys(data.agents || {}).sort(),
+      });
+      return false;
+    }
 
     const current = data.agents[subscriber].activity_state;
 
@@ -30,7 +41,7 @@ function writeActivityState(agentsFilePath, subscriber, state, options = {}) {
     data.agents[subscriber].activity_since = since
       ? new Date(since).toISOString()
       : new Date().toISOString();
-    fs.writeFileSync(agentsFilePath, JSON.stringify(data, null, 2));
+    writeJSON(agentsFilePath, data);
     return true;
   } catch {
     return false;

package/src/agent/internalRunner.js

@@ -3,6 +3,7 @@ const path = require("path");
 const { getUfooPaths } = require("../ufoo/paths");
 const { spawnSync } = require("child_process");
 const EventBus = require("../bus");
+const { readJSON, writeJSON } = require("../bus/utils");
 const { runCliAgent } = require("./cliRunner");
 const { normalizeCliOutput } = require("./normalizeOutput");
 const { createActivityStatePublisher } = require("./activityStatePublisher");
@@ -15,6 +16,7 @@ const { listToolsForCallerTier, CALLER_TIERS } = require("../tools");
 const { redactToolCallPayload, redactSecrets } = require("../providerapi/redactor");
 const { buildCachedMemoryPrefix } = require("../memory");
 const { shouldForwardStreamToPublisher } = require("./publisherRouting");
+const { appendAgentRegistryDiagnostic } = require("../ufoo/agentRegistryDiagnostics");
 
 function sleep(ms) {
   return new Promise((resolve) => setTimeout(resolve, ms));
@@ -493,14 +495,22 @@ function persistProviderSessionId(projectRoot, subscriber, providerSessionId) {
   try {
     const agentsFile = getUfooPaths(projectRoot).agentsFile;
     const parsed = fs.existsSync(agentsFile)
-      ? JSON.parse(fs.readFileSync(agentsFile, "utf8"))
+      ? readJSON(agentsFile, null)
       : {};
+    if (!parsed) return false;
     if (!parsed.agents || typeof parsed.agents !== "object") return false;
-    if (!parsed.agents[subscriber] || typeof parsed.agents[subscriber] !== "object") return false;
+    if (!parsed.agents[subscriber] || typeof parsed.agents[subscriber] !== "object") {
+      appendAgentRegistryDiagnostic(agentsFile, "provider_session_subscriber_missing", {
+        source: "agent.internalRunner.persistProviderSessionId",
+        subscriber,
+        known_ids: Object.keys(parsed.agents || {}).sort(),
+      });
+      return false;
+    }
     if (parsed.agents[subscriber].provider_session_id === id) return false;
     parsed.agents[subscriber].provider_session_id = id;
     parsed.agents[subscriber].provider_session_updated_at = new Date().toISOString();
-    fs.writeFileSync(agentsFile, `${JSON.stringify(parsed, null, 2)}\n`);
+    writeJSON(agentsFile, parsed);
     return true;
   } catch {
     return false;

package/src/agent/notifier.js

@@ -1,8 +1,10 @@
 const fs = require("fs");
 const path = require("path");
 const EventBus = require("../bus");
+const { readJSON, writeJSON } = require("../bus/utils");
 const Injector = require("../bus/inject");
 const { getUfooPaths } = require("../ufoo/paths");
+const { appendAgentRegistryDiagnostic } = require("../ufoo/agentRegistryDiagnostics");
 const { shakeTerminalByTty } = require("../bus/shake");
 const { isITerm2 } = require("../terminal/detect");
 const iterm2 = require("../terminal/iterm2");
@@ -62,7 +64,8 @@ class AgentNotifier {
   getNickname() {
     try {
       if (!this.agentsFile || !fs.existsSync(this.agentsFile)) return "";
-      const data = JSON.parse(fs.readFileSync(this.agentsFile, "utf8"));
+      const data = readJSON(this.agentsFile, null);
+      if (!data) return "";
       const meta = data.agents && data.agents[this.subscriber];
       return (meta && meta.nickname) ? String(meta.nickname) : "";
     } catch {
@@ -109,11 +112,18 @@ class AgentNotifier {
   updateHeartbeat() {
     try {
       if (!this.agentsFile || !fs.existsSync(this.agentsFile)) return;
-      const data = JSON.parse(fs.readFileSync(this.agentsFile, "utf8"));
+      const data = readJSON(this.agentsFile, null);
+      if (!data) return;
       if (data.agents && data.agents[this.subscriber]) {
         data.agents[this.subscriber].last_seen = new Date().toISOString();
-        fs.writeFileSync(this.agentsFile, JSON.stringify(data, null, 2));
+        writeJSON(this.agentsFile, data);
+        return;
       }
+      appendAgentRegistryDiagnostic(this.agentsFile, "heartbeat_subscriber_missing", {
+        source: "agent.notifier.updateHeartbeat",
+        subscriber: this.subscriber,
+        known_ids: Object.keys(data.agents || {}).sort(),
+      });
     } catch {
       // 心跳更新失败时静默忽略
     }
@@ -132,7 +142,8 @@ class AgentNotifier {
   getCurrentActivityState() {
     try {
       if (!this.agentsFile || !fs.existsSync(this.agentsFile)) return "";
-      const data = JSON.parse(fs.readFileSync(this.agentsFile, "utf8"));
+      const data = readJSON(this.agentsFile, null);
+      if (!data) return "";
       const meta = data.agents && data.agents[this.subscriber];
       return meta && typeof meta.activity_state === "string"
         ? String(meta.activity_state).trim().toLowerCase()

package/src/bus/index.js

@@ -60,7 +60,8 @@ class EventBus {
     this.queueManager = new QueueManager(this.busDir);
     this.subscriberManager = new SubscriberManager(
       this.busData,
-      this.queueManager
+      this.queueManager,
+      { agentsFile: this.agentsFile }
     );
     this.messageManager = new MessageManager(
       this.busDir,

package/src/bus/store.js

@@ -5,6 +5,7 @@ const path = require("path");
 const { getTimestamp, ensureDir, safeNameToSubscriber, getTtyProcessInfo } = require("./utils");
 const { getUfooPaths } = require("../ufoo/paths");
 const { loadAgentsData, saveAgentsData } = require("../ufoo/agentsStore");
+const { appendAgentRegistryDiagnostic } = require("../ufoo/agentRegistryDiagnostics");
 
 function readQueueTty(queueDir) {
   try {
@@ -25,7 +26,7 @@ function buildUsedNicknameSet(agents = {}) {
   return set;
 }
 
-function recoverQueueEntry(data, subscriber, queueDir, usedNicknames, now) {
+function recoverQueueEntry(data, subscriber, queueDir, usedNicknames, now, agentsFile) {
   if (!subscriber || data.agents[subscriber]) return false;
 
   if (subscriber === "ufoo-agent") {
@@ -45,6 +46,17 @@ function recoverQueueEntry(data, subscriber, queueDir, usedNicknames, now) {
     };
     return true;
   }
+  appendAgentRegistryDiagnostic(
+    agentsFile,
+    "queue_entry_not_recovered",
+    {
+      source: "bus.store.recoverQueueEntry",
+      subscriber,
+      queue_dir: queueDir,
+      reason: "non_controller_queue_without_registry_entry",
+      used_nicknames: Array.from(usedNicknames || []).sort(),
+    }
+  );
   return false;
 }
 
@@ -112,20 +124,20 @@ class BusStore {
       if (!stat.isDirectory()) continue;
 
       const subscriber = safeNameToSubscriber(entry);
-      recovered = recoverQueueEntry(data, subscriber, queueDir, usedNicknames, now) || recovered;
+      recovered = recoverQueueEntry(data, subscriber, queueDir, usedNicknames, now, this.agentsFile) || recovered;
     }
 
     recovered = reconcileReservedControllerAliases(data, now) || recovered;
 
     if (recovered) {
-      saveAgentsData(this.agentsFile, data);
+      saveAgentsData(this.agentsFile, data, { source: "bus.store.load.recoverQueueEntry", trace: true });
     }
     return data;
   }
 
   save(busData) {
     if (busData) {
-      saveAgentsData(this.agentsFile, busData);
+      saveAgentsData(this.agentsFile, busData, { source: "bus.store.save" });
     }
   }
 
@@ -144,7 +156,7 @@ class BusStore {
         created_at: getTimestamp(),
         agents: {},
       };
-      saveAgentsData(this.agentsFile, busData);
+      saveAgentsData(this.agentsFile, busData, { source: "bus.store.init", trace: true });
     }
   }
 

package/src/bus/subscriber.js

@@ -2,6 +2,7 @@ const fs = require("fs");
 const { getTimestamp, isAgentPidAlive, isMetaActive, isValidTty, getTtyProcessInfo } = require("./utils");
 const NicknameManager = require("./nickname");
 const { spawnSync } = require("child_process");
+const { appendAgentRegistryDiagnostic } = require("../ufoo/agentRegistryDiagnostics");
 
 function detectTerminalAppFromEnv() {
   const termProgram = process.env.TERM_PROGRAM || "";
@@ -102,9 +103,14 @@ function hasProviderSession(meta) {
  * 订阅者管理
  */
 class SubscriberManager {
-  constructor(busData, queueManager) {
+  constructor(busData, queueManager, options = {}) {
     this.busData = busData;
     this.queueManager = queueManager;
+    this.agentsFile = options.agentsFile || "";
+  }
+
+  logRegistry(event, payload = {}) {
+    appendAgentRegistryDiagnostic(this.agentsFile, event, payload);
   }
 
   cleanupSubscriberArtifacts(subscriber) {
@@ -152,6 +158,15 @@ class SubscriberManager {
           inheritedNickname = meta.nickname;
         }
         // Remove stale subscriber using same tty
+        this.logRegistry("cleanup_duplicate_tty", {
+          source: "bus.subscriber.cleanupDuplicateTty",
+          subscriber: id,
+          replacement: currentSubscriber,
+          tty: ttyPath,
+          same_agent_type: sameAgentType,
+          status: meta?.status || "",
+          nickname: meta?.nickname || "",
+        });
         delete this.busData.agents[id];
         try {
           const queueDir = this.queueManager.getQueueDir(id);
@@ -420,6 +435,16 @@ class SubscriberManager {
         const recoverable = hasProviderSession(meta);
         if (meta.status === "inactive") {
           if (!recoverable) {
+            this.logRegistry("cleanup_inactive_delete", {
+              source: "bus.subscriber.cleanupInactive",
+              subscriber: id,
+              reason: "internal_already_inactive_without_provider_session",
+              status: meta.status || "",
+              launch_mode: meta.launch_mode || "",
+              pid: meta.pid || 0,
+              tty: meta.tty || "",
+              last_seen: meta.last_seen || "",
+            });
             delete this.busData.agents[id];
             this.cleanupSubscriberArtifacts(id);
           }
@@ -427,11 +452,31 @@ class SubscriberManager {
         }
         if (!isMetaActive(meta)) {
           if (recoverable) {
+            this.logRegistry("cleanup_inactive_mark", {
+              source: "bus.subscriber.cleanupInactive",
+              subscriber: id,
+              reason: "internal_inactive_but_recoverable_provider_session",
+              status: meta.status || "",
+              launch_mode: meta.launch_mode || "",
+              pid: meta.pid || 0,
+              tty: meta.tty || "",
+              last_seen: meta.last_seen || "",
+            });
             meta.status = "inactive";
             meta.activity_state = "";
             meta.last_seen = getTimestamp();
             this.cleanupSubscriberArtifacts(id);
           } else {
+            this.logRegistry("cleanup_inactive_delete", {
+              source: "bus.subscriber.cleanupInactive",
+              subscriber: id,
+              reason: "internal_inactive_without_provider_session",
+              status: meta.status || "",
+              launch_mode: meta.launch_mode || "",
+              pid: meta.pid || 0,
+              tty: meta.tty || "",
+              last_seen: meta.last_seen || "",
+            });
             delete this.busData.agents[id];
             this.cleanupSubscriberArtifacts(id);
           }
@@ -439,6 +484,17 @@ class SubscriberManager {
         continue;
       }
       if (meta.status === "active" && !isMetaActive(meta)) {
+        this.logRegistry("cleanup_inactive_mark", {
+          source: "bus.subscriber.cleanupInactive",
+          subscriber: id,
+          reason: "active_meta_failed_liveness",
+          status: meta.status || "",
+          launch_mode: meta.launch_mode || "",
+          pid: meta.pid || 0,
+          tty: meta.tty || "",
+          tty_shell_pid: meta.tty_shell_pid || 0,
+          last_seen: meta.last_seen || "",
+        });
         meta.status = "inactive";
         meta.activity_state = "";
         meta.last_seen = getTimestamp();

package/src/bus/utils.js

@@ -3,6 +3,7 @@ const fs = require("fs");
 const path = require("path");
 const { spawnSync } = require("child_process");
 const { redactSecrets } = require("../providerapi/redactor");
+const { appendAgentRegistryDiagnostic } = require("../ufoo/agentRegistryDiagnostics");
 
 /**
  * 获取当前 UTC 时间戳（ISO 8601 格式）
@@ -200,6 +201,11 @@ function readJSON(filePath, defaultValue = null) {
     const content = fs.readFileSync(filePath, "utf8");
     return JSON.parse(content);
   } catch (err) {
+    appendAgentRegistryDiagnostic(filePath, "read_json_failed", {
+      source: "bus.utils.readJSON",
+      error: err && err.message ? err.message : String(err || "unknown"),
+      default_returned: defaultValue === null ? "null" : typeof defaultValue,
+    });
     return defaultValue;
   }
 }

package/src/ufoo/agentRegistryDiagnostics.js

@@ -0,0 +1,91 @@
+const fs = require("fs");
+const path = require("path");
+
+function isAgentsFile(filePath) {
+  return path.basename(filePath || "") === "all-agents.json"
+    && path.basename(path.dirname(filePath || "")) === "agent";
+}
+
+function getRegistryLogPath(agentsFilePath) {
+  const ufooRoot = path.dirname(path.dirname(agentsFilePath));
+  return path.join(ufooRoot, "run", "agent-registry-diagnostics.log");
+}
+
+function summarizeFile(filePath) {
+  try {
+    const stat = fs.statSync(filePath);
+    return {
+      exists: true,
+      size: stat.size,
+      mtime: stat.mtime.toISOString(),
+    };
+  } catch (err) {
+    return {
+      exists: false,
+      error: err && err.code ? err.code : String(err || "unknown"),
+    };
+  }
+}
+
+function summarizeAgents(data) {
+  const agents = data && typeof data === "object" && data.agents && typeof data.agents === "object"
+    ? data.agents
+    : {};
+  const ids = Object.keys(agents).sort();
+  const statuses = {};
+  const nicknames = {};
+  for (const id of ids) {
+    const meta = agents[id] || {};
+    const status = typeof meta.status === "string" && meta.status ? meta.status : "unknown";
+    statuses[status] = (statuses[status] || 0) + 1;
+    if (typeof meta.nickname === "string" && meta.nickname) {
+      nicknames[id] = meta.nickname;
+    }
+  }
+  return {
+    count: ids.length,
+    ids,
+    statuses,
+    nicknames,
+  };
+}
+
+function safePayload(payload = {}) {
+  const out = {};
+  for (const [key, value] of Object.entries(payload || {})) {
+    if (/token|secret|password|credential|auth/i.test(key)) {
+      out[key] = "[REDACTED]";
+    } else {
+      out[key] = value;
+    }
+  }
+  return out;
+}
+
+function appendAgentRegistryDiagnostic(agentsFilePath, event, payload = {}) {
+  if (!agentsFilePath || !isAgentsFile(agentsFilePath)) return;
+  try {
+    const logPath = getRegistryLogPath(agentsFilePath);
+    fs.mkdirSync(path.dirname(logPath), { recursive: true });
+    const line = JSON.stringify({
+      ts: new Date().toISOString(),
+      pid: process.pid,
+      ppid: process.ppid,
+      event,
+      agents_file: agentsFilePath,
+      file: summarizeFile(agentsFilePath),
+      ...safePayload(payload),
+    });
+    fs.appendFileSync(logPath, `${line}\n`, "utf8");
+  } catch {
+    // Diagnostics must never affect agent liveness paths.
+  }
+}
+
+module.exports = {
+  appendAgentRegistryDiagnostic,
+  summarizeAgents,
+  summarizeFile,
+  isAgentsFile,
+  getRegistryLogPath,
+};

package/src/ufoo/agentsStore.js

@@ -1,4 +1,5 @@
 const { getTimestamp, readJSON, writeJSON } = require("../bus/utils");
+const { appendAgentRegistryDiagnostic, summarizeAgents } = require("./agentRegistryDiagnostics");
 
 const AGENTS_SCHEMA_VERSION = 1;
 
@@ -89,9 +90,23 @@ function normalizeAgentsData(data) {
 function loadAgentsData(filePath) {
   const data = readJSON(filePath, null);
   if (!data) {
+    appendAgentRegistryDiagnostic(filePath, "load_agents_empty", {
+      source: "ufoo.agentsStore.loadAgentsData",
+      reason: "missing_or_unreadable_registry",
+    });
     return normalizeAgentsData({});
   }
-  return normalizeAgentsData(data);
+  const normalized = normalizeAgentsData(data);
+  const beforeSummary = summarizeAgents(data);
+  const afterSummary = summarizeAgents(normalized);
+  if (JSON.stringify(beforeSummary) !== JSON.stringify(afterSummary)) {
+    appendAgentRegistryDiagnostic(filePath, "load_agents_normalized", {
+      source: "ufoo.agentsStore.loadAgentsData",
+      before: beforeSummary,
+      after: afterSummary,
+    });
+  }
+  return normalized;
 }
 
 function parseTimestampMs(value) {
@@ -125,13 +140,27 @@ function mergeExternalActivityFields(targetMeta, diskMeta) {
   }
 }
 
-function saveAgentsData(filePath, data) {
+function saveAgentsData(filePath, data, options = {}) {
+  const source = typeof options.source === "string" && options.source
+    ? options.source
+    : "ufoo.agentsStore.saveAgentsData";
   const normalized = normalizeAgentsData(data);
 
   // Merge externally-managed fields from disk to avoid daemon in-memory writes
   // overwriting fresher runner/notifier state updates.
   const disk = readJSON(filePath, null);
   if (disk && disk.agents && normalized.agents) {
+    const droppedIds = Object.keys(disk.agents)
+      .filter((id) => !Object.prototype.hasOwnProperty.call(normalized.agents, id))
+      .sort();
+    if (droppedIds.length > 0) {
+      appendAgentRegistryDiagnostic(filePath, "save_agents_dropping_disk_entries", {
+        source,
+        dropped_ids: droppedIds,
+        disk: summarizeAgents(disk),
+        next: summarizeAgents(normalized),
+      });
+    }
     for (const [id, diskMeta] of Object.entries(disk.agents)) {
       if (!diskMeta || typeof diskMeta !== "object") continue;
       const targetMeta = normalized.agents[id];
@@ -140,6 +169,13 @@ function saveAgentsData(filePath, data) {
     }
   }
 
+  const nextSummary = summarizeAgents(normalized);
+  if (nextSummary.count === 0 || options.trace === true) {
+    appendAgentRegistryDiagnostic(filePath, "save_agents_data", {
+      source,
+      next: nextSummary,
+    });
+  }
   writeJSON(filePath, normalized);
 }