u-foo 3.0.14 → 3.0.16

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.16",
   "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/OPTIONAL_SKILLS/ubus-poll/SKILL.md

@@ -1,76 +0,0 @@
----
-name: ubus-poll
-description: |
-  Explicitly start a resident ufoo bus stream in an agent host that has been
-  configured to deliver streaming background-task output. Install by name only.
----
-
-# /ubus-poll - Resident Bus Stream
-
-This is an opt-in session-start skill. Run it only in a host where a human has
-configured this fallback. Do not install or invoke it for Codex CLI, Claude
-Code CLI, Agy, Kimi, or native ucode; those runtimes already have their own
-ufoo delivery path.
-
-## Start once per agent session
-
-Reuse the provisioned subscriber identity. Never create a second identity just
-for the poll process.
-
-```bash
-SUBSCRIBER="${UFOO_SUBSCRIBER_ID:-}"
-test -n "$SUBSCRIBER" || {
-  echo "ubus-poll requires a provisioned UFOO_SUBSCRIBER_ID"
-  exit 1
-}
-```
-
-Identity provisioning is a host/human setup step. Do not guess an agent type,
-call bare `ufoo bus join`, or borrow the workspace's current subscriber.
-
-Use the agent host's **streaming background-task** facility to start:
-
-```bash
-ufoo bus poll "$SUBSCRIBER" --follow --interval 2
-```
-
-The command must remain owned by that facility. Do not use `nohup`, shell `&`,
-or an OS-detached daemon: those routes can put output in a log that never
-reaches the agent. The command rejects a second resident poll for the same
-subscriber.
-
-The poll is deliberately queue-read-only. It emits current pending events at
-startup, waits for that batch to be acknowledged, then emits the next pending
-batch. It does not ack, claim, inject, or clear messages itself.
-
-## When background output arrives
-
-For every `[ufoo]<from:...>` event:
-
-1. Read `Content.message` and execute actionable work.
-2. After handling the emitted batch, run the exact `ack --through <seq>`
-   command printed by the poll stream. For example:
-
-   ```bash
-   ufoo bus ack "$SUBSCRIBER" --through 42
-   ```
-
-   `--through` preserves any later message that was not in the displayed batch.
-
-3. Reply to the sender only for a requested result, an answer, or information
-   they need to continue:
-
-   ```bash
-   ufoo bus send "<sender-id>" "<substantive result>"
-   ```
-
-Ack-only messages, greetings, and thanks need no reply.
-
-After sending, do not poll, sleep, or wait for a reply. Keep working; this
-resident stream will emit any follow-up.
-
-## Host requirement
-
-This flow works only when the agent host forwards incremental output from a
-still-running background task into the agent session. If it only returns output
-after process exit, use an explicitly invoked `/ubus` instead.