u-foo 1.0.3 → 1.1.9

package/bin/ufoo

@@ -18,14 +18,14 @@ Usage:
   ufoo daemon --start|--stop|--status
   ufoo chat
   ufoo init [--modules context[,resources]] [--project <dir>]
-  ufoo bus <...>            # delegates to ./scripts/bus.sh in the current project
-  ufoo ctx <...>            # delegates to ./scripts/ai-context-*.sh in the current project
+  ufoo bus <...>            # JS bus implementation (project-local data)
+  ufoo ctx <...>            # JS context commands (doctor|lint|decisions)
   ufoo skills list
   ufoo skills install <name|all> [--codex|--agents|--target <dir>]
 
 Notes:
   - `init` creates/updates <project>/.ai-context and injects CLAUDE.md/AGENTS.md blocks.
-  - For Codex notifications, prefer `scripts/bus-alert.sh` / `scripts/bus-listen.sh` (no IME issues).
+  - For Codex notifications, prefer `ufoo bus alert` / `ufoo bus listen` (no IME issues).
 USAGE
 }
 
@@ -37,10 +37,10 @@ case "$cmd" in
     exec node "$repo_root/bin/ufoo.js" chat
     ;;
   doctor)
-    exec bash "$repo_root/scripts/doctor.sh"
+    exec node "$repo_root/bin/ufoo.js" doctor "$@"
     ;;
   status)
-    exec bash "$repo_root/scripts/status.sh"
+    exec node "$repo_root/bin/ufoo.js" status "$@"
     ;;
   daemon)
     exec node "$repo_root/bin/ufoo.js" daemon "$@"
@@ -49,41 +49,19 @@ case "$cmd" in
     exec node "$repo_root/bin/ufoo.js" chat
     ;;
   init)
-    exec bash "$repo_root/scripts/init.sh" "$@"
+    exec node "$repo_root/bin/ufoo.js" init "$@"
     ;;
   bus)
     # Project-local bus commands. Must be run from within the target project.
-    if [[ ! -x "./scripts/bus.sh" ]]; then
-      echo "FAIL: missing ./scripts/bus.sh. Run: ufoo init --modules bus" >&2
-      exit 1
-    fi
-    exec bash "./scripts/bus.sh" "$@"
+    exec node "$repo_root/bin/ufoo.js" bus "$@"
     ;;
   ctx)
-    # Project-local ctx commands. Must be run from within the target project.
-    sub="${1:-doctor}"
-    shift || true
-    case "$sub" in
-      doctor)
-        exec bash "./scripts/ai-context-doctor.sh" "$@"
-        ;;
-      lint)
-        exec bash "./scripts/ai-context-lint.sh" "$@"
-        ;;
-      decisions)
-        exec bash "./scripts/ai-context-decisions.sh" "$@"
-        ;;
-      *)
-        echo "Unknown ctx subcommand: $sub" >&2
-        echo "Supported: doctor, lint, decisions" >&2
-        exit 1
-        ;;
-    esac
+    exec node "$repo_root/bin/ufoo.js" ctx "$@"
     ;;
   skills)
     sub="${1:-}"
     shift || true
-    exec bash "$repo_root/scripts/skills.sh" "$sub" "$@"
+    exec node "$repo_root/bin/ufoo.js" skills "$sub" "$@"
     ;;
   *)
     echo "Unknown command: $cmd" >&2

package/bin/ufoo-assistant-agent.js

@@ -0,0 +1,5 @@
+#!/usr/bin/env node
+
+const { runAssistantStdio } = require("../src/assistant/stdio");
+
+runAssistantStdio();

package/bin/ufoo-engine.js

@@ -0,0 +1,25 @@
+#!/usr/bin/env node
+
+const { runUfooEngineCli } = require("../src/assistant/ufooEngineCli");
+
+function readStdin() {
+  return new Promise((resolve) => {
+    let data = "";
+    process.stdin.setEncoding("utf8");
+    process.stdin.on("data", (chunk) => {
+      data += chunk;
+    });
+    process.stdin.on("end", () => resolve(data));
+    process.stdin.resume();
+  });
+}
+
+(async () => {
+  const stdinText = await readStdin();
+  const result = await runUfooEngineCli({
+    argv: process.argv.slice(2),
+    stdinText,
+  });
+  process.stdout.write(result.output);
+  process.exitCode = result.exitCode;
+})();

package/bin/ufoo.js

@@ -4,6 +4,7 @@ const { runCli } = require("../src/cli");
 const { runDaemonCli } = require("../src/daemon/run");
 const { runChat } = require("../src/chat");
 const { runInternalRunner } = require("../src/agent/internalRunner");
+const { runPtyRunner } = require("../src/agent/ptyRunner");
 
 const cmd = process.argv[2];
 
@@ -21,6 +22,22 @@ async function main() {
     await runInternalRunner({ projectRoot: process.cwd(), agentType });
     return;
   }
+  if (cmd === "agent-pty-runner") {
+    const agentType = process.argv[3] || "codex";
+    try {
+      await runPtyRunner({ projectRoot: process.cwd(), agentType });
+    } catch (err) {
+      const normalized = String(agentType || "").trim().toLowerCase();
+      if (normalized === "ufoo" || normalized === "ucode" || normalized === "ufoo-code") {
+        throw err;
+      }
+      // Fallback to headless runner if PTY is unavailable
+      // eslint-disable-next-line no-console
+      console.error(`[pty-runner] ${err.message || err}. Falling back to headless internal runner.`);
+      await runInternalRunner({ projectRoot: process.cwd(), agentType });
+    }
+    return;
+  }
   if (cmd === "chat") {
     await runChat(process.cwd());
     return;

package/modules/AGENTS.template.md

@@ -27,10 +27,17 @@ ufoo ctx decisions -l          # List all decisions
 ufoo ctx decisions -n 1        # Show latest decision
 
 # Bus
-ufoo bus join                  # Join bus (auto by uclaude/ucodex)
+SUBSCRIBER="${UFOO_SUBSCRIBER_ID:-$(ufoo bus whoami 2>/dev/null || true)}"
+[ -n "$SUBSCRIBER" ] || SUBSCRIBER=$(ufoo bus join | tail -1)
 ufoo bus check $SUBSCRIBER     # Check pending messages
 ufoo bus send "<id>" "<msg>"   # Send message
 ufoo bus status                # Show bus status
+
+# Runtime report (shared contract for assistant/ucodex/uclaude)
+ufoo report start "<task>" --task <id> --agent "$SUBSCRIBER" --scope public
+ufoo report progress "<detail>" --task <id> --agent "$SUBSCRIBER" --scope public
+ufoo report done "<summary>" --task <id> --agent "$SUBSCRIBER" --scope public
+ufoo report error "<reason>" --task <id> --agent "$SUBSCRIBER" --scope public
 ```
 
 ---
@@ -44,13 +51,21 @@ ufoo ctx decisions -n 1
 ```
 
 Key files in `.ufoo/context/`:
-- `DECISIONS/` - Decision log (append-only)
-- `SYSTEM.md` - System overview
-- `CONSTRAINTS.md` - Non-negotiable rules
+- `decisions/` - Decision log (append-only)
+
+**Decision recording policy — "If it has information value, write it down":**
+
+Record a decision whenever your work produces knowledge that would be useful to your future self, other agents, or the user. The threshold is LOW — when in doubt, record it.
 
-**Decision recording policy:**
-- **Must record**: evaluations, architecture, naming, trade-offs
-- Write decision **before replying** when applicable
+- **Always record**: architectural choices, trade-off analysis, research findings, non-obvious gotchas, naming/convention changes, external API behavior discovered, performance observations, bug root causes
+- **Also record**: open questions you couldn't resolve, assumptions you made, approaches you considered and rejected (with reasons), edge cases noticed but not handled
+- **Write the decision BEFORE acting on it** — if your session dies, the knowledge survives
+- **Granularity**: A decision can be one sentence ("X doesn't support Y, use Z instead") or a multi-page analysis. Match the depth to the information value.
+
+```bash
+ufoo ctx decisions new "Short descriptive title"
+# Then edit the created file with Context/Decision/Implications
+```
 
 ---
 
@@ -59,9 +74,12 @@ Key files in `.ufoo/context/`:
 ### CRITICAL: `ubus` Command Behavior
 
 **When you receive `ubus`, you MUST:**
-1. Check pending messages: `ufoo bus check $SUBSCRIBER`
-2. **EXECUTE each task immediately** - Do NOT ask the user
-3. Reply to sender: `ufoo bus send "<publisher>" "<result>"`
+1. Resolve subscriber ID first (reuse existing ID, join only as fallback):
+   `SUBSCRIBER="${UFOO_SUBSCRIBER_ID:-$(ufoo bus whoami 2>/dev/null || true)}"; [ -n "$SUBSCRIBER" ] || SUBSCRIBER=$(ufoo bus join | tail -1)`
+2. Check pending messages: `ufoo bus check $SUBSCRIBER`
+3. **EXECUTE each task immediately** - Do NOT ask the user
+4. Reply to sender: `ufoo bus send "<publisher>" "<result>"`
+5. **CRITICAL: Acknowledge messages after handling**: `ufoo bus ack $SUBSCRIBER`
 
 **Rules:**
 - Execute tasks immediately without asking
@@ -83,5 +101,5 @@ Extract sender ID from "from" field, use it to reply.
 
 1. Receive: `@you from claude-code:bd36dda0 Content: {"message":"Please analyze the project structure"}`
 2. Execute: Analyze the project structure
-3. Reply: `ufoo bus send "claude-code:bd36dda0" "Project contains src/, scripts/, modules/"`
+3. Reply: `ufoo bus send "claude-code:bd36dda0" "Project contains src/, modules/, bin/"`
 <!-- /ufoo -->

package/modules/bus/README.md

@@ -22,11 +22,17 @@ ufoo init --modules context,bus
 ## Directory Structure
 
 ```
-.bus/
-├── bus.json      # Bus metadata + subscriber status
-├── events/       # Event stream (JSONL, sharded by date)
-├── offsets/      # Each Agent's consumption progress
-└── queues/       # Targeted event queues
+.ufoo/
+├── agent/
+│   └── all-agents.json  # Agent metadata + agent status
+├── daemon/
+│   ├── daemon.pid
+│   ├── daemon.log
+│   └── counts/
+└── bus/
+    ├── events/          # Event stream (JSONL, sharded by date)
+    ├── offsets/         # Each Agent's consumption progress
+    └── queues/          # Targeted event queues
 ```
 
 ## Usage
@@ -34,33 +40,34 @@ ufoo init --modules context,bus
 ### Join Bus
 
 ```bash
-SUBSCRIBER=$(bash scripts/bus.sh join)
-# Output: claude-code:a1b2c3
+SUBSCRIBER="${UFOO_SUBSCRIBER_ID:-$(ufoo bus whoami 2>/dev/null || true)}"
+[ -n "$SUBSCRIBER" ] || SUBSCRIBER=$(ufoo bus join | tail -n 1)
+# Output: claude-code:a1b2c3 (or codex:def456)
 ```
 
 ### Check Pending Messages
 
 ```bash
-bash scripts/bus.sh check $SUBSCRIBER
+ufoo bus check "$SUBSCRIBER"
 ```
 
 ### Send Messages
 
 ```bash
 # Send to specific instance
-bash scripts/bus.sh send "claude-code:abc123" "Please help me review"
+ufoo bus send "claude-code:abc123" "Please help me review"
 
 # Send to all instances of same type
-bash scripts/bus.sh send "claude-code" "Everyone please review"
+ufoo bus send "claude-code" "Everyone please review"
 
 # Broadcast to all
-bash scripts/bus.sh broadcast "I completed feature-x"
+ufoo bus broadcast "I completed feature-x"
 ```
 
 ### View Status
 
 ```bash
-bash scripts/bus.sh status
+ufoo bus status
 ```
 
 ## Notifications/Alerts (no key injection, recommended)
@@ -68,47 +75,48 @@ bash scripts/bus.sh status
 If you want to receive "new message alerts" while running Codex/Claude in another terminal, use **agent-side alert/listen** (avoids IME/accessibility permission/window positioning fragmentation issues):
 
 ```bash
-SUBSCRIBER=$(bash scripts/bus.sh join | tail -n 1)
+SUBSCRIBER="${UFOO_SUBSCRIBER_ID:-$(ufoo bus whoami 2>/dev/null || true)}"
+[ -n "$SUBSCRIBER" ] || SUBSCRIBER=$(ufoo bus join | tail -n 1)
 
 # Background alert: title badge + bell + optional macOS notification center
-bash scripts/bus-alert.sh "$SUBSCRIBER" 1 --notify --daemon
+ufoo bus alert "$SUBSCRIBER" 1 --notify --daemon
 
 # Or: foreground continuous print of new messages (suitable for a side terminal)
-bash scripts/bus-listen.sh "$SUBSCRIBER" --from-beginning
+ufoo bus listen "$SUBSCRIBER" --from-beginning
 ```
 
 ## Unattended Auto-Execute (recommended)
 
-If you need **Claude A to notify Claude B / Codex C and have the target auto-execute** (e.g., auto-trigger `/ubus`), use `autotrigger`:
+If you need **Claude A to notify Claude B / Codex C and have the target auto-execute** (e.g., auto-trigger `/ubus`), use the bus daemon:
 
-1) First `join` in each terminal session (records `tty`, also records `TMUX_PANE` if in tmux):
+1) Resolve subscriber in each terminal session first (records `tty`, also records `TMUX_PANE` if in tmux). Join only as fallback:
 
 ```bash
-SUBSCRIBER=$(bash scripts/bus.sh join | tail -n 1)
+SUBSCRIBER="${UFOO_SUBSCRIBER_ID:-$(ufoo bus whoami 2>/dev/null || true)}"
+[ -n "$SUBSCRIBER" ] || SUBSCRIBER=$(ufoo bus join | tail -n 1)
 ```
 
-2) Start autotrigger in the project (runs as background daemon):
+2) Start the bus daemon in the project (runs as background daemon):
 
 ```bash
-# backend=auto prefers tmux (if available), otherwise tries Terminal.app do script (pure Automation), finally Accessibility
-bash scripts/bus-autotrigger.sh start --interval 1 --command "/ubus" --backend auto
+ufoo bus daemon --interval 1 --daemon
 ```
 
-3) After sending a message, autotrigger injects `/ubus` into the target session and presses Enter:
+3) After sending a message, the daemon injects `/ubus` into the target session and presses Enter:
 - tmux: `send-keys`
 - Terminal.app (pure Automation): `do script` (no Accessibility needed, but requires Automation authorization; compatibility depends on whether target program accepts input)
 - Terminal.app (Accessibility): System Events (needs Accessibility), injection sequence is Escape + paste + Return (avoids IME issues)
 
 Tips:
-- Terminal.app backend depends on `tty` in `bus.json`. Execute `join` in the target terminal session (ensure `tty` is not `not a tty`).
+- Terminal.app backend depends on `tty` in `.ufoo/agent/all-agents.json`. Execute `join` in the target terminal session (ensure `tty` is not `not a tty`).
 - Pure Automation backend needs one-time authorization: System Preferences → Privacy & Security → Automation (allow script to control Terminal).
 - Accessibility backend needs one-time authorization: System Preferences → Privacy & Security → Accessibility (for Terminal / script host).
 
 Stop/view status:
 
 ```bash
-bash scripts/bus-autotrigger.sh status
-bash scripts/bus-autotrigger.sh stop
+ufoo bus daemon --status
+ufoo bus daemon --stop
 ```
 
 ## Subscriber ID Format

package/modules/bus/SKILLS/ubus/SKILL.md

@@ -29,18 +29,29 @@ if [[ ! -d ".ufoo/bus" ]]; then
 fi
 ```
 
-### 2. Check if already joined bus
+### 2. Get or create subscriber ID
 
-Read `.ufoo/bus/bus.json`, check if current session is registered.
-
-If not, auto-join (will auto-generate a friendly nickname like "codex-1", "claude-1"):
+**IMPORTANT**: Always check for existing subscriber ID first to avoid creating duplicates.
 
 ```bash
-SUBSCRIBER=$(ufoo bus join | tail -n 1)
-echo "Joined event bus: $SUBSCRIBER"
-# Example output: codex:0e293156 (nickname: codex-1)
+# 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
@@ -127,7 +138,7 @@ Output (now includes nicknames):
 ```
 === Event Bus Status ===
 My identity: claude-code:xyz789
-Online subscribers: 2
+Online agents: 2
   - claude-code:abc123 (architect)
   - claude-code:xyz789 (dev-lead)
 Recent events: 5

package/modules/context/README.md

@@ -1,24 +1,12 @@
 # context
 
-A collaboration protocol that constrains AI behavior through explicit, versioned files.
+Decision-only context module for ufoo.
 
-## Why
-
-AI coding agents (Claude Code, Codex, Cursor, etc.) have two fundamental problems:
-
-1. **No shared memory** — Decisions made in one session are invisible to other agents or future sessions. Each agent starts fresh, repeating mistakes or contradicting prior work.
-
-This protocol solves it by treating decisions and context as files:
-- **Decisions as files** — Persistent, versioned, reviewable. All agents read the same truth.
-
-## Core Principle
-
-```
-Global context defines the law.
-Project context defines the truth.
-```
-
-**Files are truth, not memory.**
+Purpose:
+- Persist decisions in project workspaces
+- Keep decision format canonical in `uctx` skill
+ 
+Bus handles communication; context handles durable decision truth.
 
 ## Quick Start
 
@@ -34,42 +22,32 @@ This repository is the `context` module. The recommended entrypoint is `ufoo`.
 
 Global modules live under `~/.ufoo/modules/`.
 
-### Project: `<project>/.context/` (writable)
+### Project: `<project>/.ufoo/context/` (writable)
 
 ```
-.context/
-├── README.md        # Entry point / how to use this context
-├── SYSTEM.md        # Project architecture
-├── CONSTRAINTS.md   # Non-negotiable rules
-├── ASSUMPTIONS.md   # Current assumptions
-├── TERMINOLOGY.md   # Shared vocabulary
-└── DECISIONS/       # Append-only log
+.ufoo/context/
+├── decisions/       # Append-only decision log (decision-only mode)
+└── decisions.jsonl  # Decision index (ts/type/file/author)
 ```
 
-Must be in Git. Must be reviewable. Truth.
+Should be in the project workspace and writable by agents.
+Versioning is optional but recommended for auditability.
 
-## Protocol Structure
+## Module Structure
 
 ```
 context/                 # This repo
-├── SYSTEM.md               # Protocol definition
-├── RULES.md                # Collaboration rules
-├── CONSTRAINTS.md          # Protocol constraints
-├── DECISION-PROTOCOL.md    # How to write decisions
-├── HANDOFF.md              # Session handoff rules
-├── CONTEXT-STRUCTURE.md    # Project structure spec
-├── TEMPLATES/              # AI behavior constraint
-├── SKILLS/                 # tool skill docs (module-local)
-└── .context/            # Local project context for this repo (ignored; not part of protocol distribution)
+├── README.md               # This file
+├── SKILLS/uctx/SKILL.md    # Canonical decision format + workflow
+└── .ufoo/context/          # Local project context for this repo (ignored; not part of protocol distribution)
 ```
 
 ## For AI Agents
 
 1. Read installed module from `~/.ufoo/modules/context/`
-2. Read/write context from `<project>/.context/`
+2. Read/write decisions in `<project>/.ufoo/context/decisions/`
 3. **Never write to global** — only to project
-4. When unsure, write a decision
-5. Do not modify TEMPLATES/ without a decision
+4. Follow the decision format in `SKILLS/uctx/SKILL.md`
 
 ## Validate
 

package/modules/context/SKILLS/uctx/SKILL.md

@@ -14,12 +14,74 @@ Fast context check for daily use. Run at session start or anytime.
 
 Pre-flight reminder:
 - If the user is asking for evaluation/recommendation/plan, write a decision before replying.
+  Use: `ufoo ctx decisions new "<Title>"`
+
+## Decision format (canonical)
+
+Project context is decision-only. Decisions live at:
+`<project>/.ufoo/context/decisions/`
+
+Decision index (JSONL):
+`<project>/.ufoo/context/decisions.jsonl`
+
+Generate/update the index:
+```bash
+ufoo ctx decisions index
+```
+
+Each JSONL row includes:
+- `ts` (ISO timestamp)
+- `type` (`decision` or `decision_status`)
+- `file` (decision filename)
+- `author` (decision author or resolver)
+
+Create a new decision (recommended before replying when required):
+```bash
+ufoo ctx decisions new "Short Title"
+```
+
+**File naming:** `NNNN-<nickname>-short-title.md` (4-digit prefix + nickname + kebab-case slug).
+
+**Template for new decisions:**
+```yaml
+---
+status: open
+nickname: <nickname>
+---
+# DECISION NNNN: <Title>
+
+Date: YYYY-MM-DD
+Author: <agent>
+Nickname: <nickname>
+
+Context:
+What led to this decision?
+
+Decision:
+What is now considered true?
+
+Implications:
+What must follow from this?
+```
+
+**Status updates (only edit frontmatter):**
+```yaml
+---
+status: resolved
+resolved_by: <agent>
+resolved_at: YYYY-MM-DD
+---
+```
+
+Rules:
+- Decisions are append-only. Do not rewrite past content.
+- Only update the frontmatter when changing status.
 
 ## Workflow
 
 ### 1. Verify structure exists
 
-Check `.ufoo/context/` exists. If missing, tell user to run `uinit` (ufoo init CLI).
+Check `.ufoo/context/decisions/` exists. If missing, tell user to run `ufoo init`.
 
 ### 2. List all decisions