@nomad-e/bluma-cli 0.1.59 → 0.1.61

package/README.md

@@ -6,7 +6,9 @@
 
 **BluMa** is a CLI-based model agent for advanced software engineering workflows. Built with React/Ink 5, it provides an interactive terminal interface for LLM-powered automation, code generation, refactoring, and task execution. Features persistent sessions, contextual reasoning, smart feedback, coordinator mode for worker orchestration, and extensible tools/skills architecture.
 
-**Current Version:** 0.1.55
+> **Credit:** BluMa was conceived and architected by **Alex Fonseca**.
+
+**Current Version:** 0.1.60
 
 ---
 
@@ -278,12 +280,16 @@ BluMa includes **40+ built-in tools** organized by category:
 | `send_command_input` | Send input to running commands' stdin |
 | `kill_command` | Terminate running commands |
 
-### Agent Coordination
+### Agent Coordination (v0.1.60+)
 | Tool | Description |
 |------|-------------|
 | `spawn_agent` | Create background worker agents |
 | `wait_agent` | Wait for agent completion |
 | `list_agents` | List active/completed agents |
+| `send_message` | Send follow-up to running worker (continue without re-spawn) |
+| `list_mailbox_messages` | Read messages from workers (progress, permission requests) |
+| `signal_mailbox` | Send ack/nack/progress signals to workers |
+| `poll_mailbox` | Poll mailbox for new messages (legacy polling mode) |
 
 ### Task & Project Management
 | Tool | Description |
@@ -329,6 +335,8 @@ BluMa includes **40+ built-in tools** organized by category:
 | Tool | Description |
 |------|-------------|
 | `lsp_query` | LSP go-to-definition or references (TS/JS) |
+| `repl` | Interactive code execution (Python, Node, Bash) |
+| `task_output` | Read task output in real-time |
 
 ### Plan Mode
 | Tool | Description |
@@ -338,6 +346,185 @@ BluMa includes **40+ built-in tools** organized by category:
 
 ---
 
+## New Features in v0.1.60
+
+### Mailbox System (Bidirectional Communication)
+**Push-based communication** between coordinator and workers using EventEmitter:
+
+```typescript
+// Coordinator sends follow-up to running worker
+send_message({
+  to: "worker-session-id",
+  message: "Fix the null pointer in src/auth/validate.ts:42..."
+})
+
+// Coordinator reads messages from workers
+list_mailbox_messages({
+  from: "worker-session-id",
+  type: "progress_update",
+  unreadOnly: true
+})
+
+// Workers send progress/permission requests
+signal_mailbox({
+  sessionId: "coordinator-session-id",
+  type: "progress",
+  data: { percent: 50 }
+})
+```
+
+**Key Benefits:**
+- **No polling needed** - EventEmitter pushes messages instantly
+- **Permission requests** - Workers can request permissions mid-execution
+- **Progress tracking** - Real-time progress updates
+- **Follow-up commands** - Continue workers without re-spawn
+
+### Permission System
+**Granular permission rules** with allow/deny patterns:
+
+```typescript
+// Check permission for tool invocation
+permissionRulesEngine.checkPermission('edit_tool', {
+  filepath: '/src/auth/validate.ts'
+})
+// Returns: 'allow' | 'deny' | 'ask'
+
+// Add custom rule
+permissionRulesEngine.addRule({
+  type: 'allow',
+  toolPattern: 'read_*',
+  pathPattern: '**/*.md',
+  scope: 'global'
+})
+```
+
+**Features:**
+- **Tool patterns** - Wildcard matching for tool names
+- **Path patterns** - Glob-based file path matching
+- **Command patterns** - Shell command pattern matching
+- **Scopes** - global, workspace, session-level rules
+
+### Worker Context Isolation
+**AsyncLocalStorage-based context** for in-process workers:
+
+```typescript
+import { runWithWorkerContext, createWorkerContext } from './worker_context'
+
+const ctx = createWorkerContext({
+  workerType: 'research',
+  name: 'auth-investigation'
+})
+
+await runWithWorkerContext(ctx, async () => {
+  // Worker code runs with isolated context
+  // Shares LLM/MCP clients but has unique context
+})
+```
+
+### REPL Tool
+**Interactive code execution** for rapid prototyping:
+
+```typescript
+repl({
+  language: 'python',
+  code: `
+import pandas as pd
+df = pd.DataFrame({'a': [1, 2, 3]})
+print(df.sum())
+  `,
+  timeout: 30000
+})
+```
+
+**Supported languages:** Python, Node.js, Bash
+
+### Context Auto-Compact
+**Automatic context compression** with history anchoring:
+
+- **Budget:** 240k tokens
+- **Trigger:** 70% of budget (168k tokens)
+- **Strategy:** Compress old turns, keep last 10 turns complete
+- **Anchor:** System message with compressed summary
+
+```typescript
+const { messages, newAnchor } = await createApiContextWindow(
+  fullHistory,
+  currentAnchor,
+  compressedTurnSliceCount,
+  llmService,
+  userContext
+)
+```
+
+### Session Memory Extractor
+**Automatic memory extraction** from conversations:
+
+```typescript
+const memories = await memoryExtractor.extractMemoriesFromSession(messages)
+// Returns: ExtractedMemory[] with type, content, confidence, tags
+
+// Get relevant memories for query
+const relevant = await memoryExtractor.getRelevantMemories('authentication')
+```
+
+**Memory types:** codebase_knowledge, preference, decision, pattern, bugfix, architecture
+
+### Vim Mode
+**Vim-like keybindings** in input prompt:
+
+- **Modes:** normal, insert, visual, command
+- **Motions:** h/j/k/l, w/b, 0/$, g/G
+- **Operators:** d (delete), c (change), y (yank)
+- **Commands:** `:w`, `:q`, etc.
+
+```typescript
+// Enable vim mode
+/vim toggle
+```
+
+### Themes System
+**6 configurable UI themes:**
+
+| Theme | Description |
+|-------|-------------|
+| `default` | Classic dark terminal |
+| `dracula` | Purple accents |
+| `github` | GitHub Dark mode |
+| `monokai` | Vibrant green accents |
+| `nord` | Arctic blue palette |
+| `tokyo` | Tokyo Night blue-purple |
+
+```bash
+/theme dracula
+```
+
+### Init Subagent
+**Automatic BluMa.md generation:**
+
+```bash
+/init
+```
+
+Scans repository and generates comprehensive codebase documentation including:
+- Project overview
+- Technology stack detection
+- Directory structure with annotations
+- Key configs and scripts
+- CLI commands
+- Operational notes
+
+### Coding Memory Consolidate
+**Deduplication of coding memories:**
+
+```typescript
+consolidateCodingMemoryFile()
+// Merges duplicate entries by normalized text
+// Keeps oldest ID, merges tags
+// Creates backup .bak file
+```
+
+---
+
 ## Skills System
 
 Skills are **self-contained knowledge modules** that extend BluMa with domain expertise. They use **Progressive Disclosure** to manage context efficiently.
@@ -499,6 +686,8 @@ Built-in terminal commands (type `/` to see all):
 | `/kill <id>` | Send SIGTERM to a session by id |
 | `/tasks [list\|add\|complete\|update\|remove\|clear]` | Manage task list |
 | `/plan [show\|start\|end]` | Manage the active task boundary |
+| `/compact` | Manually compact conversation context |
+| `/export` | Export conversation as markdown |
 
 ### Agent
 | Command | Description |
@@ -527,6 +716,13 @@ Built-in terminal commands (type `/` to see all):
 | `/tools [grep]` | List native tools (optional filter) |
 | `/mcp [fs]` | List MCP tools (optional filter) |
 | `/features` | Feature flags: `/features` or `/features <key> on\|off` |
+| `/debug-workers` | Show running workers, PIDs, memory, and event bus state |
+| `/cost` | Show session cost and token usage |
+| `/memory` | Manage session memories |
+| `/stats` | Detailed session statistics |
+| `/theme` | Change UI theme |
+| `/keybindings` | Show or configure keybindings |
+| `/vim` | Toggle vim mode |
 
 ### Help
 | Command | Description |
@@ -777,7 +973,7 @@ Apache 2.0 — see [LICENSE](LICENSE) for details.
 
 - **Issues**: [GitHub Issues](https://github.com/nomad-e/bluma-cli/issues)
 - **Documentation**: This README + `docs/` directory
-- **Author**: Alex Fonseca
+- **Author & Architect**: Alex Fonseca (conceived and architected BluMa)
 - **npm Package**: [@nomad-e/bluma-cli](https://www.npmjs.com/package/@nomad-e/bluma-cli)
 
 ### Runtime Modules (v0.1.41+)