u-foo 1.0.3 → 1.1.9

package/README.md

@@ -6,7 +6,9 @@ Multi-agent AI collaboration toolkit for Claude Code and OpenAI Codex.
 
 - **Event Bus** - Real-time inter-agent messaging (`ufoo bus`)
 - **Context Sharing** - Shared decisions and project context (`ufoo ctx`)
-- **Agent Wrappers** - Auto-initialization for Claude Code (`uclaude`) and Codex (`ucodex`)
+- **Agent Wrappers** - Auto-initialization for Claude Code (`uclaude`), Codex (`ucodex`), and ufoo core (`ucode`)
+  - **PTY Wrapper** - Intelligent terminal emulation with ready detection
+  - **Smart Probe Injection** - Waits for agent initialization before injecting commands
 - **Skills System** - Extensible agent capabilities (`ufoo skills`)
 
 ## Quick Start
@@ -23,8 +25,46 @@ ufoo init
 # Or use agent wrappers (auto-init + bus join)
 uclaude   # instead of 'claude'
 ucodex    # instead of 'codex'
+ucode     # ufoo self-developed coding agent entry
 ```
 
+To import a local `pi-mono` checkout as a reference snapshot (reference-only):
+
+```bash
+npm run import:pi-mono -- /path/to/pi-mono
+```
+
+Native self-developed implementation lives under `src/code`.
+
+Prepare and verify `ucode` runtime wiring:
+
+```bash
+ufoo ucode doctor
+ufoo ucode prepare
+ufoo ucode build
+```
+
+Try native core queue runtime (WIP):
+
+```bash
+ucode-core submit --tool read --args-json '{"path":"README.md"}'
+ucode-core run-once --json
+ucode-core list --json
+```
+
+Configure `ucode` provider/model/API in `.ufoo/config.json` (ufoo-managed):
+
+```json
+{
+  "ucodeProvider": "openai",
+  "ucodeModel": "gpt-5.1-codex",
+  "ucodeBaseUrl": "https://api.openai.com/v1",
+  "ucodeApiKey": "sk-***"
+}
+```
+
+`ucode` writes these into a dedicated runtime directory (`.ufoo/agent/ucode/pi-agent`) and uses them for native planner/engine calls.
+
 ## Architecture
 
 ```
@@ -45,6 +85,8 @@ ucodex    # instead of 'codex'
        └─────────────┘ └───────┘ └─────────────┘
 ```
 
+Bus state lives in `.ufoo/agent/all-agents.json` (metadata), `.ufoo/bus/*` (queues/events), and `.ufoo/daemon/*` (bus daemon runtime).
+
 ## Commands
 
 | Command | Description |
@@ -53,7 +95,8 @@ ucodex    # instead of 'codex'
 | `ufoo status` | Show banner, unread bus messages, open decisions |
 | `ufoo daemon --start|--stop|--status` | Manage ufoo daemon |
 | `ufoo chat` | Launch ufoo chat UI (also default when no args) |
-| `ufoo bus join` | Join event bus (auto by uclaude/ucodex) |
+| `ufoo resume [nickname]` | Resume agent sessions (optional nickname) |
+| `ufoo bus join` | Join event bus (auto by uclaude/ucodex/ucode) |
 | `ufoo bus send <id> <msg>` | Send message to agent |
 | `ufoo bus check <id>` | Check pending messages |
 | `ufoo bus status` | Show bus status |
@@ -73,14 +116,15 @@ ufoo/
 │   ├── ufoo         # Main CLI entry (bash)
 │   ├── ufoo.js      # Node wrapper
 │   ├── uclaude      # Claude Code wrapper
-│   └── ucodex       # Codex wrapper
+│   ├── ucodex       # Codex wrapper
+│   └── ucode        # ufoo core wrapper
 ├── SKILLS/          # Global skills (uinit, ustatus)
-├── scripts/
-│   ├── bus.sh       # Event bus implementation
-│   ├── bus-*.sh     # Bus utilities (inject, daemon, alert)
-│   ├── context-*.sh # Context management
-│   ├── init.sh      # Project initialization
-│   └── skills.sh    # Skills management
+├── src/
+│   ├── bus/         # Event bus implementation (JS)
+│   ├── daemon/      # Daemon + chat bridge
+│   ├── agent/       # Agent launch/runtime
+│   └── code/        # Native ucode core implementation
+├── scripts/         # Legacy helpers (bash, deprecated)
 ├── modules/
 │   ├── context/     # Decision/context protocol
 │   ├── bus/         # Bus module resources
@@ -101,8 +145,9 @@ your-project/
 │   │   ├── queues/      # Per-agent message queues
 │   │   └── offsets/     # Read position tracking
 │   └── context/
-│       └── DECISIONS/   # Decision records
-├── scripts/             # Symlinked ufoo scripts
+│       ├── decisions/   # Decision records
+│       └── decisions.jsonl  # Decision index
+├── scripts/             # Legacy symlink (optional)
 ├── AGENTS.md            # Injected protocol blocks
 └── CLAUDE.md            # → AGENTS.md
 ```
@@ -162,3 +207,57 @@ ufoo --help
 ## License
 
 UNLICENSED (Private)
+
+## Recent Changes
+
+### 🚀 Smart Ready Detection & PTY Wrapper (2026-02-06)
+
+Added intelligent agent initialization detection for reliable probe injection:
+
+**Features:**
+- **ReadyDetector** - Monitors PTY output to detect when agents are ready
+- **Smart Probe Timing** - Injects session probe after agent initialization (not before)
+- **Multi-layer Fallback** - 10s ready detection + 8s fallback + 15 retries
+- **Performance Metrics** - Tracks detection time and buffer usage (`UFOO_DEBUG=1`)
+
+**Benefits:**
+- ✅ No more premature probe injection (was 2s, now waits for prompt)
+- ✅ Reliable session ID capture (39 tests, 100% pass)
+- ✅ Production-ready error handling and logging
+
+**Technical Details:**
+- `src/agent/readyDetector.js` - PTY output analysis
+- `src/agent/ptyWrapper.js` - Terminal emulation with monitoring
+- `src/daemon/providerSessions.js` - Early probe triggering support
+
+See `.ufoo/plans/ready-detection-production-checklist.md` for full details.
+
+---
+
+### 🎉 Bash to JavaScript Migration (2026-02-04)
+
+We've successfully migrated **80% of the codebase** from Bash to JavaScript for better maintainability and cross-platform support!
+
+**What Changed:**
+- ✅ EventBus core (986 lines) → 8 JavaScript modules
+- ✅ Daemon & inject → Pure JavaScript
+- ✅ status, skills, init → JavaScript modules
+- ⏸️ Context management scripts remain in Bash (complex text processing)
+
+**Impact:**
+- **CLI commands unchanged** - All commands work exactly as before
+- **Performance:** 51ms/message (vs 45ms in Bash, +13%)
+- **Testing:** 20/20 integration tests passing
+- **Quality:** Better error handling, testing, and IDE support
+
+**Learn More:**
+- See [MIGRATION_LOG.md](MIGRATION_LOG.md) for full details
+- View archived scripts in `scripts/.archived/migrated-to-js/`
+- Performance benchmarks in test reports
+
+**Why This Matters:**
+- 🎯 Unified JavaScript tech stack
+- 🧪 Easier to test and maintain
+- 🌍 Cross-platform potential (Windows/Linux)
+- 💡 Better IDE support and refactoring
+- 🚀 Foundation for future enhancements

package/README.zh-CN.md

@@ -45,6 +45,8 @@ ucodex    # 代替 'codex'
        └─────────────┘ └───────┘ └─────────────┘
 ```
 
+Bus 状态存放于 `.ufoo/agent/all-agents.json`（元数据）、`.ufoo/bus/*`（队列/事件）以及 `.ufoo/daemon/*`（bus daemon 运行态）。
+
 ## 命令列表
 
 | 命令 | 说明 |
@@ -53,6 +55,7 @@ ucodex    # 代替 'codex'
 | `ufoo status` | 显示 banner、未读消息和未处理决策 |
 | `ufoo daemon --start|--stop|--status` | 管理 ufoo 守护进程 |
 | `ufoo chat` | 启动 ufoo 交互界面（无参数默认进入） |
+| `ufoo resume [nickname]` | 恢复 agent 会话（可选昵称） |
 | `ufoo bus join` | 加入事件总线（uclaude/ucodex 自动完成）|
 | `ufoo bus send <id> <msg>` | 发送消息给Agent |
 | `ufoo bus check <id>` | 检查待处理消息 |
@@ -75,12 +78,11 @@ ufoo/
 │   ├── uclaude      # Claude Code 包装器
 │   └── ucodex       # Codex 包装器
 ├── SKILLS/          # 全局技能（uinit, ustatus）
-├── scripts/
-│   ├── bus.sh       # 事件总线实现
-│   ├── bus-*.sh     # 总线工具（注入、守护进程、提醒）
-│   ├── context-*.sh # 上下文管理
-│   ├── init.sh      # 项目初始化
-│   └── skills.sh    # 技能管理
+├── src/
+│   ├── bus/         # 事件总线实现（JS）
+│   ├── daemon/      # Daemon + chat bridge
+│   └── agent/       # Agent 启动/运行
+├── scripts/         # 历史遗留（bash，已弃用）
 ├── modules/
 │   ├── context/     # 决策/上下文协议
 │   ├── bus/         # 总线模块资源
@@ -102,7 +104,7 @@ your-project/
 │   │   └── offsets/     # 读取位置跟踪
 │   └── context/
 │       └── DECISIONS/   # 决策记录
-├── scripts/             # 软链接的 ufoo 脚本
+├── scripts/             # 软链接（历史遗留，可选）
 ├── AGENTS.md            # 注入的协议块
 └── CLAUDE.md            # → AGENTS.md
 ```

package/SKILLS/ufoo/SKILL.md

@@ -0,0 +1,132 @@
+---
+name: ufoo
+description: |
+  Unified ufoo agent protocol: context decisions, event bus, and initialization.
+  Use when: (1) input starts with "/ufoo" or "$ufoo", (2) agent session startup, (3) any ufoo-related operation.
+  Combines uctx (decisions), ubus (messaging), and uinit (initialization).
+---
+
+# ufoo — Unified Agent Protocol
+
+ufoo is the multi-agent coordination layer. It provides three capabilities:
+
+1. **Context Decisions** — Persistent knowledge log shared across agents
+2. **Event Bus** — Inter-agent messaging
+3. **Initialization** — Project setup for ufoo modules
+
+## Session Marker
+
+When you see a probe marker command like `/ufoo <marker>` (Claude) or `$ufoo <marker>` (Codex), this is daemon session tracking. **Do not reply.** Silently ignore it and wait for the next user input.
+
+---
+
+## 1. Context Decisions (uctx)
+
+### When to Record
+
+**"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.
+
+- **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**: one sentence or multi-page analysis — match the depth to the information value
+
+### Commands
+
+```bash
+ufoo ctx decisions -l              # List all decisions
+ufoo ctx decisions -s open         # Check open decisions
+ufoo ctx decisions -n 1            # Show latest decision
+ufoo ctx decisions new "Title"     # Create new decision
+```
+
+### Decision Format
+
+Decisions live at: `.ufoo/context/decisions/`
+
+```yaml
+---
+status: open
+---
+# DECISION NNNN: <Title>
+
+Date: YYYY-MM-DD
+Author: <agent>
+
+Context:
+What led to this decision?
+
+Decision:
+What is now considered true?
+
+Implications:
+What must follow from this?
+```
+
+### Handling Open Decisions
+
+1. **Read and understand** — sync other agents' knowledge
+2. **Check if action needed** — does it require implementation?
+3. **Execute if needed** — do the work
+4. **Resolve** — update frontmatter: `status: resolved`, `resolved_by:`, `resolved_at:`
+
+**NEVER resolve blindly.** Reading the title is not enough.
+
+---
+
+## 2. Event Bus (ubus)
+
+### Commands
+
+```bash
+ufoo bus check "$UFOO_SUBSCRIBER_ID"        # Check pending messages
+ufoo bus ack "$UFOO_SUBSCRIBER_ID"           # Acknowledge after handling
+ufoo bus send "<target>" "<message>"         # Send message
+ufoo bus broadcast "<message>"               # Broadcast to all
+ufoo bus status                              # Show bus status
+```
+
+### Runtime Report (Unified for assistant/ucodex/uclaude)
+
+Use the same report contract for runtime progress sync:
+
+```bash
+ufoo report start "<task>" --task <id> --agent "$UFOO_SUBSCRIBER_ID" --scope public
+ufoo report progress "<detail>" --task <id> --agent "$UFOO_SUBSCRIBER_ID" --scope public
+ufoo report done "<summary>" --task <id> --agent "$UFOO_SUBSCRIBER_ID" --scope public
+ufoo report error "<reason>" --task <id> --agent "$UFOO_SUBSCRIBER_ID" --scope public
+```
+
+Notes:
+- Use `--scope private` for helper-internal reports (assistant-like private channel).
+- `--controller ufoo-agent` routes report events to the ufoo-agent private inbox.
+
+### Target Resolution
+
+- Exact ID: `claude-code:abc123`
+- Nickname: `architect`
+- Type: `codex` (all codex agents)
+- Wildcard: `*` (broadcast)
+
+### CRITICAL: When you receive pending messages
+
+**EXECUTE tasks immediately. Do NOT ask the user.**
+
+1. Check: `ufoo bus check $UFOO_SUBSCRIBER_ID`
+2. Execute each task
+3. Reply: `ufoo bus send "<publisher>" "<result>"`
+4. **Always ack**: `ufoo bus ack $UFOO_SUBSCRIBER_ID`
+
+---
+
+## 3. Initialization (uinit)
+
+Trigger: `/uinit` or `/ufoo init`
+
+```bash
+ufoo init --modules context,bus --project $(pwd)
+```
+
+After init, auto-join bus if enabled.

package/SKILLS/uinit/SKILL.md

@@ -0,0 +1,78 @@
+---
+name: uinit
+description: |
+  Initialize ufoo modules in current project.
+  Use when: (1) new project needs context/bus enabled, (2) user inputs /uinit or /ufoo init.
+  Provides interactive module selection, defaults to all selected.
+---
+
+# uinit
+
+Initialize ufoo modules in current project.
+
+## Trigger
+
+User inputs `/uinit` or `/ufoo init`
+
+## Execution Flow
+
+### 1. Ask user to select modules
+
+Use AskUserQuestion tool, provide multi-select, default all selected:
+
+```
+Please select modules to enable:
+
+☑ context - Shared context protocol (.ufoo/context/)
+☑ bus - Agent event bus (.ufoo/bus/ + .ufoo/agent/)
+☐ resources - UI/Icons resources (optional)
+```
+
+Options:
+- `context` (recommended) - Shared context, decision recording, knowledge persistence
+- `bus` (recommended) - Multi-agent communication, task delegation, message passing
+- `resources` (optional) - UI tone guide, icon library
+
+Default selected: context, bus
+
+### 2. Execute initialization
+
+Based on user selection, execute:
+
+```bash
+ufoo init --modules <selected_modules> --project $(pwd)
+```
+
+### 3. If bus module selected, auto-join bus
+
+```bash
+SUBSCRIBER="${UFOO_SUBSCRIBER_ID:-$(ufoo bus whoami 2>/dev/null || true)}"
+if [ -n "$SUBSCRIBER" ]; then
+  echo "Using existing subscriber ID: $SUBSCRIBER"
+else
+  SUBSCRIBER=$(ufoo bus join | tail -1)
+  echo "Joined event bus: $SUBSCRIBER"
+fi
+```
+
+### 4. Report initialization result
+
+```
+=== ufoo initialization complete ===
+
+Enabled modules:
+  ✓ context → .ufoo/context/
+  ✓ bus → .ufoo/bus/ + .ufoo/agent/
+
+My identity: claude-code:<session-id>
+
+Next steps:
+  - Run /ctx to check context status
+  - See AGENTS.md for protocol rules
+```
+
+## Notes
+
+- If .ufoo/context, .ufoo/bus, or .ufoo/agent already exists, skip creation
+- After initialization, reuse existing subscriber ID first, join only as fallback (if bus enabled)
+- AGENTS.md will have protocol description block injected

package/SKILLS/ustatus/SKILL.md

@@ -0,0 +1,36 @@
+---
+name: ustatus
+description: |
+  Unified ufoo status check. Shows banner, unread bus messages, and open decisions.
+  Use when: (1) User asks for status, (2) Quick health check, (3) Before starting work.
+---
+
+# ufoo Status
+
+## What this does
+
+Quick, unified status view:
+- Banner
+- Unread bus messages (unacked queues)
+- Open decisions
+
+## Workflow
+
+### 1. Verify structure exists
+
+Check `.ufoo/` exists. If missing, tell user to run `ufoo init`.
+
+### 2. Run status command
+
+```bash
+ufoo status
+```
+
+### 3. Report status
+
+Briefly summarize:
+- Unread messages count
+- Open decisions count
+- Any immediate action needed
+
+If unread messages > 0, advise running `ufoo bus check <subscriber>` and `ufoo bus ack <subscriber>` after handling.

package/bin/uclaude.js

@@ -0,0 +1,13 @@
+#!/usr/bin/env node
+/**
+ * uclaude: Launch Claude Code and auto-join event bus
+ *
+ * Usage: uclaude [claude args...]
+ */
+
+const AgentLauncher = require("../src/agent/launcher");
+
+const launcher = new AgentLauncher("claude-code", "claude");
+const args = process.argv.slice(2);
+
+launcher.launch(args);

package/bin/ucode-core.js

@@ -0,0 +1,15 @@
+#!/usr/bin/env node
+
+const { runUcodeCoreCli } = require("../src/code/cli");
+
+(async () => {
+  const argv = process.argv.slice(2);
+  const result = await runUcodeCoreCli({ argv, projectRoot: process.cwd() });
+  if (result && typeof result.output === "string" && result.output) {
+    process.stdout.write(result.output);
+  }
+  process.exit(typeof result.exitCode === "number" ? result.exitCode : 0);
+})().catch((err) => {
+  process.stderr.write(`${err && err.message ? err.message : "ucode-core failed"}\n`);
+  process.exit(1);
+});

package/bin/ucode.js

@@ -0,0 +1,125 @@
+#!/usr/bin/env node
+/**
+ * ucode: Launch ufoo self-developed coding agent core
+ *
+ * Usage: ucode [core args...]
+ *
+ * Command resolution order:
+ * 1) UFOO_UCODE_CMD / UFOO_UFOO_CODE_CMD
+ * 2) .ufoo/config.json -> ucodeCommand / ufooCodeCommand
+ * 3) fallback: bundled native core entry
+ */
+
+const fs = require("fs");
+const AgentLauncher = require("../src/agent/launcher");
+const { resolveUcodeLaunch } = require("../src/agent/ucode");
+const { prepareUcodeBootstrap } = require("../src/agent/ucodeBootstrap");
+const { prepareUcodeRuntimeConfig } = require("../src/agent/ucodeRuntimeConfig");
+
+function stripAppendSystemPromptArgs(args = [], targetFile = "") {
+  const normalizedTarget = String(targetFile || "").trim();
+  if (!Array.isArray(args) || args.length === 0) return { args: [], removed: false };
+  const nextArgs = [];
+  let removed = false;
+  for (let i = 0; i < args.length; i += 1) {
+    const item = String(args[i] || "");
+    if (!item) continue;
+    if (item === "--append-system-prompt") {
+      const value = String(args[i + 1] || "");
+      if (!normalizedTarget || value === normalizedTarget) {
+        removed = true;
+        i += 1;
+        continue;
+      }
+      nextArgs.push(item, value);
+      i += 1;
+      continue;
+    }
+    if (item.startsWith("--append-system-prompt=")) {
+      const value = item.slice("--append-system-prompt=".length);
+      if (!normalizedTarget || value === normalizedTarget) {
+        removed = true;
+        continue;
+      }
+    }
+    nextArgs.push(item);
+  }
+  return { args: nextArgs, removed };
+}
+
+function shouldPreserveAppendTarget({
+  appendTarget = "",
+  bootstrapFile = "",
+} = {}) {
+  const append = String(appendTarget || "").trim();
+  if (!append) return false;
+  const bootstrap = String(bootstrapFile || "").trim();
+  if (!bootstrap) return fs.existsSync(append);
+  if (append === bootstrap) return false;
+  return fs.existsSync(append);
+}
+
+const resolved = resolveUcodeLaunch({
+  argv: process.argv.slice(2),
+  env: process.env,
+  cwd: process.cwd(),
+});
+
+if (resolved && resolved.env && typeof resolved.env === "object") {
+  for (const [key, value] of Object.entries(resolved.env)) {
+    if (!key) continue;
+    process.env[key] = String(value);
+  }
+}
+
+try {
+  const runtimePrepared = prepareUcodeRuntimeConfig({
+    projectRoot: process.cwd(),
+    env: process.env,
+  });
+  if (runtimePrepared && runtimePrepared.env && typeof runtimePrepared.env === "object") {
+    for (const [key, value] of Object.entries(runtimePrepared.env)) {
+      if (!key) continue;
+      process.env[key] = String(value);
+    }
+  }
+} catch {
+  // runtime config preparation is best-effort
+}
+
+try {
+  prepareUcodeBootstrap({
+    projectRoot: process.cwd(),
+    promptFile: process.env.UFOO_UCODE_PROMPT_FILE || "",
+    targetFile: process.env.UFOO_UCODE_BOOTSTRAP_FILE || "",
+  });
+} catch (err) {
+  const mode = String(process.env.UFOO_UCODE_APPEND_SYSTEM_PROMPT_MODE || "auto").trim().toLowerCase();
+  const bootstrapFile = String(process.env.UFOO_UCODE_BOOTSTRAP_FILE || "").trim();
+  const appendTarget = String(process.env.UFOO_UCODE_APPEND_SYSTEM_PROMPT || bootstrapFile).trim();
+  const preserveCustomAppend = shouldPreserveAppendTarget({ appendTarget, bootstrapFile });
+  if (mode !== "always" && !preserveCustomAppend) {
+    const stripped = stripAppendSystemPromptArgs(resolved.args, appendTarget);
+    resolved.args = stripped.args;
+    if (stripped.removed) {
+      console.error(`[ucode] Warning: bootstrap prepare failed; launching without --append-system-prompt (${err && err.message ? err.message : "unknown error"})`);
+    }
+  } else if (preserveCustomAppend) {
+    console.error(`[ucode] Warning: bootstrap prepare failed; preserving custom --append-system-prompt (${err && err.message ? err.message : "unknown error"})`);
+  }
+}
+
+const mode = String(process.env.UFOO_UCODE_APPEND_SYSTEM_PROMPT_MODE || "auto").trim().toLowerCase();
+const bootstrapFile = String(process.env.UFOO_UCODE_BOOTSTRAP_FILE || "").trim();
+const appendTarget = String(process.env.UFOO_UCODE_APPEND_SYSTEM_PROMPT || bootstrapFile).trim();
+const preserveCustomAppend = shouldPreserveAppendTarget({ appendTarget, bootstrapFile });
+if (mode !== "always" && bootstrapFile && !fs.existsSync(bootstrapFile) && !preserveCustomAppend) {
+  const stripped = stripAppendSystemPromptArgs(resolved.args, appendTarget);
+  resolved.args = stripped.args;
+  if (stripped.removed) {
+    console.error("[ucode] Warning: bootstrap file missing; launching without --append-system-prompt");
+  }
+}
+
+const launcher = new AgentLauncher(resolved.agentType, resolved.command);
+launcher.launch(resolved.args);

package/bin/ucodex.js

@@ -0,0 +1,13 @@
+#!/usr/bin/env node
+/**
+ * ucodex: Launch Codex and auto-join event bus
+ *
+ * Usage: ucodex [codex args...]
+ */
+
+const AgentLauncher = require("../src/agent/launcher");
+
+const launcher = new AgentLauncher("codex", "codex");
+const args = process.argv.slice(2);
+
+launcher.launch(args);