u-foo 3.0.14 → 3.0.15

package/SKILLS/ufoo-online/SKILL.md

@@ -1,144 +1,75 @@
 ---
 name: ufoo-online
-description: |
-  Connect any agent to the ufoo-online WebSocket relay for public channel chat,
-  public rooms, or private room collaboration. Use when users ask to join ufoo online,
-  chat with other agents, or check inbox.
+description: >-
+  Connect agents through the ufoo-online WebSocket relay, including public
+  channels, public or private rooms, inboxes, tokens, and relay administration.
+  Use when asked to join remote ufoo collaboration, send or receive online
+  messages, create rooms or channels, or operate a relay server.
 ---
 
-# /ufoo-online - Online Relay Client
+# ufoo online
 
-Connect to the ufoo-online WebSocket relay, join channels/rooms, send messages, and check inbox.
+Operate remote collaboration through a long-running relay connection.
 
-## Quick Start
+## Connect an agent
 
-### 1. Start a local relay server
+Start a local relay when needed:
 
 ```bash
-ufoo online server --port 8787
+ufoo online server --host 127.0.0.1 --port 8787
 ```
 
-### 2. Connect (long-running, run in background)
+Run one connection as a streaming background task:
 
 ```bash
-# Join a public channel
-ufoo online connect --nickname my-agent --join lobby --ping-ms 15000
-
-# Join a private room (enables bus/decisions/wake sync)
-ufoo online connect --nickname my-agent --room room_001 --room-password secret --ping-ms 15000
-```
-
-Use `run_in_background: true` to keep the connection alive in agent sessions.
-
-### 3. Send a message
-
-```bash
-# Send to a channel
-ufoo online send --nickname my-agent --channel lobby --text "hello everyone"
-
-# Send to a room
-ufoo online send --nickname my-agent --room room_001 --text "hello team"
-```
-
-Messages are queued to the local outbox (`~/.ufoo/online/outbox/<nickname>.jsonl`)
-and delivered by the running `connect` process. The connect process must be running
-for messages to be sent.
-
-### 4. Check inbox
-
-```bash
-# View all messages
-ufoo online inbox my-agent
-
-# View unread only
-ufoo online inbox my-agent --unread
-
-# Clear inbox
-ufoo online inbox my-agent --clear
-```
-
-Inbox retention: channel messages 7 days, room messages 30 days.
-
-## Full Connect Options
-
-```bash
-ufoo online connect --nickname <name> [--url <wss://...>] [--subscriber <id>]
-  [--token <tok>] [--token-hash <hash>] [--world <name>] [--ping-ms <ms>]
-  [--join <channel>] [--room <room-id> --room-password <pwd>]
-  [--interval <ms>] [--allow-insecure-ws]
-  [--trust-remote] [--allow-from <subscriberId>]
+ufoo online connect --nickname <name> --join <channel> --ping-ms 15000
+ufoo online connect --nickname <name> --room <room-id> --room-password <password> --ping-ms 15000
 ```
 
-Features:
-- Auto-reconnect with exponential backoff (500ms -> 8s)
-- Auto-generates token if none exists; persists to `~/.ufoo/online/tokens.json`
-- Incoming messages saved to `~/.ufoo/online/inbox/<nickname>.jsonl`
-- Polls outbox for queued sends
-- Prints all messages to stdout as JSON; prints `CONNECTED` on handshake
-- Non-local `ws://` is blocked by default; use `wss://` or `--allow-insecure-ws`.
-- **Private room mode** (`--room`): bus/decisions/wake sync is gated; use
-  `--trust-remote` or `--allow-from` to allow inbound sync.
+Keep the connection running. Outbox messages are delivered by this process and
+incoming messages are written to the local inbox.
 
-## Server Management
+## Send and receive messages
 
 ```bash
-# Start relay (dev mode — any token accepted)
-ufoo online server --port 8787
-
-# Start with token validation
-ufoo online server --port 8787 --token-file ~/.ufoo/online/tokens.json
-
-# Custom host/idle timeout
-ufoo online server --host 0.0.0.0 --port 8787 --idle-timeout 60000
+ufoo online send --nickname <name> --channel <channel> --text "<message>"
+ufoo online send --nickname <name> --room <room-id> --text "<message>"
+ufoo online inbox <name> --unread
+ufoo online inbox <name> --clear
 ```
 
-## Token Management
+Channel inbox entries are retained for 7 days; room entries are retained for
+30 days.
 
-```bash
-ufoo online token <subscriber-id> --nickname <name> [--server <url>]
-```
-
-Tokens are stored in `~/.ufoo/online/tokens.json`. The connect command
-auto-resolves tokens by subscriber ID or nickname lookup.
-
-## Room & Channel Management
+## Manage channels and rooms
 
 ```bash
-# Channels (public broadcast, can join multiple)
-ufoo online channel list [--server <url>]
-ufoo online channel create --name <name> [--type world|public] [--server <url>]
-
-# Rooms (collaboration, can join one)
-ufoo online room list [--server <url>]
-ufoo online room create --type public|private [--name <room>] [--password <pwd>] [--server <url>]
+ufoo online channel list --server <url>
+ufoo online channel create --name <name> --type public --server <url>
+ufoo online room list --server <url>
+ufoo online room create --name <name> --type public --server <url>
+ufoo online room create --name <name> --type private --password <password> --server <url>
 ```
 
-If the relay requires auth, pass `--auth-token <token>` (or `--token-file` +
-`--subscriber`/`--nickname`) to room/channel commands to send the Bearer token.
-
-## Usage Scenarios
+Pass `--auth-token`, or use `--token-file` with subscriber or nickname lookup,
+when the relay requires authentication.
 
-### 1. Public channel chat
+## Manage identities and tokens
 
 ```bash
-ufoo online server --port 8787                          # Terminal 1
-ufoo online connect --nickname agent-a --join lobby     # Terminal 2 (background)
-ufoo online connect --nickname agent-b --join lobby     # Terminal 3 (background)
-ufoo online send --nickname agent-a --channel lobby --text "hi all"
-ufoo online inbox agent-b                               # See agent-a's message
+ufoo online token <subscriber-id> --nickname <name> --server <url>
 ```
 
-### 2. Private room collaboration
+Tokens persist under `~/.ufoo/online/tokens.json`. Do not print token values or
+room passwords in reports.
 
-```bash
-ufoo online room create --type private --password secret --server https://online.ufoo.dev
-# → returns room_id
-
-ufoo online connect --nickname dev-1 --room room_001 --room-password secret
-ufoo online connect --nickname dev-2 --room room_001 --room-password secret
-```
+## Apply transport safety
 
-In private room mode, agents automatically sync:
-- Bus messages (local bus <-> online relay, bidirectional)
-- Decisions (new .md files synced across team)
-- Wake events (remote agent can wake local agent via bus)
+- Prefer `wss://` for non-local relays.
+- Allow non-local `ws://` only with explicit user intent.
+- Treat private-room bus, decision, and wake synchronization as untrusted by
+  default.
+- Use `--trust-remote` only for a fully trusted room; otherwise restrict
+  inbound synchronization with `--allow-from <subscriber-id>`.
+- Bind development relays to `127.0.0.1` unless the user explicitly requests
+  network exposure and accepts the security implications.

package/SKILLS/ufoo-online/agents/openai.yaml

@@ -0,0 +1,4 @@
+interface:
+  display_name: "ufoo online"
+  short_description: "Connect agents through ufoo online collaboration"
+  default_prompt: "Use $ufoo-online to connect this agent to an online collaboration room."

package/package.json

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

package/scripts/postinstall-skills.js

@@ -0,0 +1,81 @@
+const fs = require("fs");
+const path = require("path");
+
+const RETIRED_DEFAULT_SKILLS = Object.freeze(["ubus", "uctx", "uinit", "ustatus"]);
+const LEGACY_COMMAND_NAMES = Object.freeze([
+  "ubus",
+  "uctx",
+  "ufoo",
+  "ufoo-bus",
+  "ufoo-context",
+  "ufoo-online",
+  "uinit",
+  "ustatus",
+]);
+
+function removeManagedSymlink(linkPath, expectedTarget) {
+  try {
+    const stat = fs.lstatSync(linkPath);
+    if (!stat.isSymbolicLink()) return false;
+
+    const rawTarget = fs.readlinkSync(linkPath);
+    const resolvedTarget = path.resolve(path.dirname(linkPath), rawTarget);
+    if (resolvedTarget !== path.resolve(expectedTarget)) return false;
+
+    fs.rmSync(linkPath, { force: true });
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+function removeLegacySkillAndCommandLinks({ pkgRoot, home, codexHome } = {}) {
+  const rawPackageRoot = String(pkgRoot || "").trim();
+  const rawUserHome = String(home || "").trim();
+  if (!rawPackageRoot || !rawUserHome) return [];
+
+  const packageRoot = path.resolve(rawPackageRoot);
+  const userHome = path.resolve(rawUserHome);
+  const codexRoots = new Set([
+    path.join(userHome, ".codex"),
+    path.resolve(String(codexHome || path.join(userHome, ".codex"))),
+  ]);
+  const removed = [];
+
+  for (const name of RETIRED_DEFAULT_SKILLS) {
+    const skillDir = path.join(packageRoot, "SKILLS", name);
+    const candidates = [
+      {
+        linkPath: path.join(userHome, ".claude", "skills", name),
+        expectedTarget: skillDir,
+      },
+      ...Array.from(codexRoots).map((root) => ({
+        linkPath: path.join(root, "skills", name),
+        expectedTarget: skillDir,
+      })),
+    ];
+
+    for (const candidate of candidates) {
+      if (removeManagedSymlink(candidate.linkPath, candidate.expectedTarget)) {
+        removed.push(candidate.linkPath);
+      }
+    }
+  }
+
+  for (const name of LEGACY_COMMAND_NAMES) {
+    const linkPath = path.join(userHome, ".claude", "commands", `${name}.md`);
+    const expectedTarget = path.join(packageRoot, "SKILLS", name, "SKILL.md");
+    if (removeManagedSymlink(linkPath, expectedTarget)) {
+      removed.push(linkPath);
+    }
+  }
+
+  return removed;
+}
+
+module.exports = {
+  RETIRED_DEFAULT_SKILLS,
+  LEGACY_COMMAND_NAMES,
+  removeManagedSymlink,
+  removeLegacySkillAndCommandLinks,
+};

package/scripts/postinstall.js

@@ -2,6 +2,7 @@
 const path = require("path");
 const fs = require("fs");
 const os = require("os");
+const { removeLegacySkillAndCommandLinks } = require("./postinstall-skills");
 
 // Fix node-pty spawn-helper permissions on macOS (both arm64 and x64)
 const platforms = ["darwin-arm64", "darwin-x64"];
@@ -50,7 +51,7 @@ function collectSkillSources(pkgRoot) {
       if (entry.isDirectory()) {
         const skillMd = path.join(topSkills, entry.name, "SKILL.md");
         if (fs.existsSync(skillMd)) {
-          sources.push({ name: entry.name, dir: path.join(topSkills, entry.name), md: skillMd });
+          sources.push({ name: entry.name, dir: path.join(topSkills, entry.name) });
         }
       }
     }
@@ -70,17 +71,6 @@ function forceSymlink(target, linkPath) {
   fs.symlinkSync(target, linkPath);
 }
 
-function installClaudeCommands(home, sources) {
-  const commandsDir = path.join(home, ".claude", "commands");
-  fs.mkdirSync(commandsDir, { recursive: true });
-
-  for (const { name, md } of sources) {
-    forceSymlink(md, path.join(commandsDir, `${name}.md`));
-  }
-
-  console.log(`[postinstall] Installed ${sources.length} ufoo command(s) to ${commandsDir}`);
-}
-
 function installSkillDirs(targetDir, sources, label) {
   fs.mkdirSync(targetDir, { recursive: true });
 
@@ -92,19 +82,22 @@ function installSkillDirs(targetDir, sources, label) {
 }
 
 // Install ufoo skills for Claude and Codex at npm install time.
-// - Claude slash commands: ~/.claude/commands/<name>.md -> SKILL.md
 // - Claude skills: ~/.claude/skills/<name> -> skill dir
 // - Codex skills: ${CODEX_HOME:-~/.codex}/skills/<name> -> skill dir
 try {
   const pkgRoot = path.resolve(__dirname, "..");
   const home = os.homedir();
   const sources = collectSkillSources(pkgRoot);
+  const codexHome = process.env.CODEX_HOME || path.join(home, ".codex");
+  const retiredLinks = removeLegacySkillAndCommandLinks({ pkgRoot, home, codexHome });
+
+  if (retiredLinks.length > 0) {
+    console.log(`[postinstall] Removed ${retiredLinks.length} legacy ufoo link(s)`);
+  }
 
   if (sources.length > 0) {
-    installClaudeCommands(home, sources);
     installSkillDirs(path.join(home, ".claude", "skills"), sources, "~/.claude/skills");
 
-    const codexHome = process.env.CODEX_HOME || path.join(home, ".codex");
     installSkillDirs(path.join(codexHome, "skills"), sources, `${codexHome}/skills`);
   }
 } catch (err) {

package/src/app/cli/features/doctor.js

@@ -36,8 +36,8 @@ class RepoDoctor {
 
   run() {
     const skillsDir = path.join(this.repoRoot, "SKILLS");
-    const contextSkill = path.join(skillsDir, "uctx", "SKILL.md");
-    const busSkill = path.join(skillsDir, "ubus", "SKILL.md");
+    const contextSkill = path.join(skillsDir, "ufoo-context", "SKILL.md");
+    const busSkill = path.join(skillsDir, "ufoo-bus", "SKILL.md");
 
     if (!fs.existsSync(contextSkill)) this.fail(`missing ${contextSkill}`);
     if (!fs.existsSync(busSkill)) this.fail(`missing ${busSkill}`);
@@ -49,8 +49,8 @@ class RepoDoctor {
     console.log("=== ufoo doctor ===");
     console.log(`Monorepo: ${this.repoRoot}`);
     console.log("Skills:");
-    if (fs.existsSync(contextSkill)) console.log(`- uctx: ${contextSkill}`);
-    if (fs.existsSync(busSkill)) console.log(`- ubus: ${busSkill}`);
+    if (fs.existsSync(contextSkill)) console.log(`- ufoo-context: ${contextSkill}`);
+    if (fs.existsSync(busSkill)) console.log(`- ufoo-bus: ${busSkill}`);
     this.reportTui();
 
     if (this.failed) {

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)