@nomad-e/bluma-cli 0.1.31 → 0.1.33

package/README.md

@@ -418,36 +418,109 @@ Here's BluMa in action:
 ---
 
 ## <a name="project-structure"></a>Project Structure
+
 ```
 bluma-cli/
-├── package.json               # npm/project config
-├── tsconfig.json              # TypeScript config
+├── package.json               # npm project config & dependencies
+├── tsconfig.json              # TypeScript configuration
+├── babel.config.cjs           # Babel presets for Jest/ESBuild
+├── jest.config.cjs            # Jest test configuration
 ├── scripts/
 │   └── build.js               # Build script using esbuild
 ├── src/
-│   ├── main.tsx               # Entry point (Ink renderer)
-│   ├── App.tsx                # Main React/Ink UI component
-│   ├── app/
-│   │   ├── agent/             # Agent core
-│   │   │   ├── Agent.ts       # Main orchestrator
-│   │   │   ├── BluMaAgent.ts  # Core agent loop & state
-│   │   │   ├── config/        # Configuration files
-│   │   │   ├── mcp/           # MCP client integration
-│   │   │   ├── prompts/       # System prompts
-│   │   │   ├── skills/        # Pluggable skills system
-│   │   │   ├── subagents/     # Sub-agent implementations
-│   │   │   └── tools/         # Tool definitions
-│   │   │       ├── natives/   # Native tools (shell, file ops, etc.)
-│   │   │       └── types.ts   # Tool type definitions
-│   │   └── ui/                # Ink/React CLI interface components
-│   ├── lib/                   # Shared utilities
-│   └── types/                 # TypeScript type definitions
-├── tests/                     # Test files
+│   ├── main.ts                # Entry point (CLI bootstrap & agent mode)
+│   └── app/
+│       ├── agent/             # Agent core & orchestration
+│       │   ├── agent.ts       # Main orchestrator (RouteManager integration)
+│       │   ├── routeManager.ts # Route registration & dispatch
+│       │   ├── bluma/
+│       │   │   └── core/
+│       │   │       └── bluma.ts # Core agent loop & state management
+│       │   ├── config/
+│       │   │   ├── native_tools.json # Native tool definitions
+│       │   │   └── skills/    # Built-in skills (git-commit, git-pr, pdf, xlsx, skill-creator)
+│       │   ├── core/
+│       │   │   ├── context-api/ # Context management & token counting
+│       │   │   │   ├── context_manager.ts
+│       │   │   │   ├── history_anchor.ts
+│       │   │   │   └── token_counter.ts
+│       │   │   ├── llm/       # LLM client (FactorRouter/OpenAI SDK)
+│       │   │   │   ├── llm.ts
+│       │   │   │   └── tool_call_normalizer.ts
+│       │   │   └── prompt/    # System prompt builder
+│       │   │       └── prompt_builder.ts
+│       │   ├── feedback/
+│       │   │   └── feedback_system.ts # Smart feedback & suggestions
+│       │   ├── session_manager/
+│       │   │   └── session_manager.ts # Session persistence & history
+│       │   ├── skills/
+│       │   │   └── skill_loader.ts # Pluggable skill system
+│       │   ├── subagents/     # Sub-agent implementations
+│       │   │   ├── registry.ts # Sub-agent registration & lookup
+│       │   │   ├── types.ts
+│       │   │   ├── base_llm_subagent.ts
+│       │   │   └── init/      # Init subagent (environment setup)
+│       │   │       ├── init_subagent.ts
+│       │   │       ├── init_system_prompt.ts
+│       │   │       └── contracts.ts
+│       │   ├── tools/
+│       │   │   ├── mcp/
+│       │   │   │   └── mcp_client.ts # MCP SDK integration
+│       │   │   └── natives/   # Native tools (20+ tools)
+│       │   │       ├── shell_command.ts
+│       │   │       ├── edit.ts
+│       │   │       ├── readLines.ts
+│       │   │       ├── ls.ts
+│       │   │       ├── grep_search.ts
+│       │   │       ├── find_by_name.ts
+│       │   │       ├── coding_memory.ts
+│       │   │       ├── load_skill.ts
+│       │   │       ├── message.ts
+│       │   │       ├── todo.ts
+│       │   │       ├── task_boundary.ts
+│       │   │       └── ... (10 more)
+│       │   ├── types/
+│       │   │   └── index.ts   # TypeScript type definitions
+│       │   └── utils/
+│       │       └── update_check.ts # Version update notifications
+│       └── ui/                # Ink/React CLI interface
+│           ├── App.tsx        # Main React component
+│           ├── layout.tsx     # UI layout components
+│           ├── components/    # Reusable UI components (20+)
+│           │   ├── MarkdownRenderer.tsx
+│           │   ├── ToolCallDisplay.tsx
+│           │   ├── ToolResultCard.tsx
+│           │   ├── InputPrompt.tsx
+│           │   ├── ConfirmationPrompt.tsx
+│           │   ├── SessionStats.tsx
+│           │   └── ... (15 more)
+│           ├── hooks/
+│           │   └── useAtCompletion.ts # Autocomplete hook
+│           ├── theme/
+│           │   ├── blumaTerminal.ts
+│           │   └── m3Layout.tsx
+│           ├── utils/
+│           │   ├── slashRegistry.ts
+│           │   ├── terminalTitle.ts
+│           │   └── ... (4 more)
+│           └── Asci/
+│               └── AsciiArt.ts
+├── tests/                     # Test suite (Jest 30)
+│   ├── *.spec.ts              # Unit & integration tests
+│   └── *.spec.tsx             # UI component tests
 ├── artifacts/                 # Generated deliverables (runtime)
-└── .bluma/                    # User config & sessions (runtime)
-    ├── sessions/              # Persistent session history
-    └── skills/                # Installed skills
+└── docs/                      # Documentation
+    ├── SKILLS.md              # Skills system documentation
+    ├── FACTOR_ROUTER_TURNS.md # FactorRouter integration details
+    └── assets/
+        └── bluma.png          # Project logo
 ```
+
+**Runtime directories** (created on first run):
+- `~/.bluma/sessions/` — Persistent session history
+- `~/.bluma/coding_memory.json` — Long-term coding notes
+- `~/.bluma/skills/` — User-installed skills
+- `~/.bluma/.env` — Optional local environment overrides
 ---
 
 ## <a name="development-and-build"></a>Development and Build
@@ -467,24 +540,95 @@ npm run dev      # (If configured, hot-reload/TS watch)
 
 ## <a name="extensibility-tools-and-plugins"></a>Extensibility: Tools, Skills and Plugins
 
-### Native Tools
-Add native tools in `src/app/agent/tools/natives/` for file operations, shell commands, code search, and more.
+### Native Tools (20+ Built-in)
+
+BluMa ships with a comprehensive set of native tools for software engineering tasks:
+
+**File Operations:**
+- `edit_tool` — Precise text replacement with context-aware editing
+- `read_file_lines` — Read specific line ranges from files
+- `ls_tool` — List directory contents with filtering & pagination
+- `count_file_lines` — Count total lines in a file
+- `view_file_outline` — Show code structure (classes, functions, methods)
+- `find_by_name` — Search files by name using glob patterns
+
+**Code Intelligence:**
+- `grep_search` — Search text patterns with regex support
+- `coding_memory` — Persistent notes about codebase & decisions
+
+**Shell & Process:**
+- `shell_command` — Execute shell commands (background async)
+- `command_status` — Check command progress & retrieve output
+- `send_command_input` — Send stdin to running commands
+- `kill_command` — Terminate running processes
+
+**Agent Workflow:**
+- `message` — Send messages to user (info or result)
+- `todo` — Manage task lists with completion tracking
+- `task_boundary` — Mark task phases (PLANNING, EXECUTION, VERIFICATION)
+- `load_skill` — Load specialized knowledge modules
+
+**UI & Navigation:**
+- All tools render rich Ink/React components in the terminal
+
+To add custom native tools, create a new file in `src/app/agent/tools/natives/` following the existing pattern.
+
+### Skills System (Pluggable Expertise)
 
-### Skills System
 BluMa features a **pluggable skills system** that loads domain-specific knowledge modules:
 
-- Skills are stored in `.bluma/skills/` (user) or `src/app/agent/skills/` (built-in)
-- Each skill is a directory with a `SKILL.md` file containing workflows and best practices
-- Skills can include `references/` (extra docs) and `scripts/` (executable helpers)
-- Load a skill with `load_skill({ skill_name: "git-commit" })`
+**Built-in Skills:**
+- `git-commit` — Professional Git commit workflows with Conventional Commits
+- `git-pr` — Pull request creation, commit validation, and merge preparation
+- `pdf` — PDF creation, manipulation, text extraction, merging, OCR
+- `xlsx` — Excel spreadsheet manipulation, formulas, data cleaning
+- `skill-creator` — Template and workflow for creating new skills
+
+**Skill Structure:**
+```
+skills/
+└── git-commit/
+    ├── SKILL.md              # Main workflow & instructions
+    ├── LICENSE.txt           # License terms
+    ├── references/
+    │   └── REFERENCE.md      # Additional documentation
+    └── scripts/
+        └── validate_commit_msg.py  # Executable helper
+```
 
-Available skills include: `git-commit`, `git-pr`, `testing`, `docker`, `pdf`, `xlsx`, and more.
+**How Skills Work:**
+1. Skills are stored in `src/app/agent/config/skills/` (built-in) or `~/.bluma/skills/` (user)
+2. Each skill includes a `SKILL.md` with YAML frontmatter defining:
+   - `name`, `description`, `version`
+   - `depends_on` (other skills for delegation)
+   - `tools.required` and `tools.recommended`
+3. Load a skill with: `load_skill({ skill_name: "git-commit" })`
+4. Skill body provides workflows, examples, and decision trees
+5. Skills can include `references/` (extra docs) and `scripts/` (Python helpers)
+
+**Creating Custom Skills:**
+Use the `skill-creator` skill to generate new skill templates. Skills are ideal for:
+- Encoding domain-specific workflows (testing, deployment, frameworks)
+- Packaging best practices and conventions
+- Providing reusable scripts and reference documentation
 
 ### MCP Integration
-Use the MCP SDK for advanced plugins integrating with external APIs and services.
+
+BluMa integrates with the **Model Context Protocol (MCP)** SDK for:
+- Connecting to external MCP servers
+- Discovering and invoking remote tools
+- Streaming tool results in real-time
+
+MCP client is located at `src/app/agent/tools/mcp/mcp_client.ts`.
 
 ### Custom UI Components
-Create custom Ink components in `src/app/ui/` to expand the interface.
+
+Extend the interface by creating custom Ink components in `src/app/ui/components/`. The UI layer supports:
+- React 18 with hooks
+- Custom renderers for tool calls and results
+- Streaming text and typewriter effects
+- Progress bars, spinners, and notifications
+- Markdown rendering with syntax highlighting
 
 ---
 
@@ -593,19 +737,74 @@ Enjoy, hack, and—if possible—contribute!
 ---
 
 ## 🏗 Architecture Diagram
-Below is a simplified diagram showing BluMa CLI's core architecture:
+
+BluMa's architecture is organized in **three layers**: UI, Agent Orchestration, and Core Services.
+
+### High-Level Overview
 ```
-[ main.ts ] → [ App.tsx (UI Layer) ]
-       ↓
-[ Agent (Orchestrator) ]
-       ↓
-[ BluMaAgent (Core Loop & State) ]
-       ↓
-[ MCPClient / Tools / Native Tools / SubAgents ]
-       ↓
-[ External APIs & System Operations ]
+┌─────────────────────────────────────────────────────────────┐
+│                      UI Layer (Ink/React)                    │
+│  main.ts → App.tsx → Components (20+) → Layout → Theme      │
+└─────────────────────────────────────────────────────────────┘
+                            ↓
+┌─────────────────────────────────────────────────────────────┐
+│                  Agent Orchestration Layer                   │
+│  agent.ts → RouteManager → BluMaAgent (bluma.ts)            │
+│  ↓                                                           │
+│  SubAgents Registry | Feedback System | Session Manager     │
+└─────────────────────────────────────────────────────────────┘
+                            ↓
+┌─────────────────────────────────────────────────────────────┐
+│                    Core Services Layer                       │
+│  ┌──────────────┬──────────────┬──────────────┐            │
+│  │ Context API  │  LLM Client  │  Prompt Bld  │            │
+│  │ (context     │  (Factor     │  (system     │            │
+│  │  manager)    │   Router)    │  prompts)    │            │
+│  └──────────────┴──────────────┴──────────────┘            │
+│  ┌──────────────┬──────────────┬──────────────┐            │
+│  │ MCP Client   │ Native Tools │  Skills      │            │
+│  │ (external    │  (20+ tools) │  (pluggable) │            │
+│  │  plugins)    │              │              │            │
+│  └──────────────┴──────────────┴──────────────┘            │
+└─────────────────────────────────────────────────────────────┘
+                            ↓
+┌─────────────────────────────────────────────────────────────┐
+│                 External Integrations                        │
+│  FactorRouter API | File System | Shell | MCP Servers       │
+└─────────────────────────────────────────────────────────────┘
 ```
-This flow ensures a clean separation between presentation, orchestration, core logic, and integration layers.
+
+### Key Architectural Concepts
+
+**1. RouteManager Pattern**
+- Central dispatch mechanism for command routing
+- Registers custom route handlers (e.g., `/init`, `/status`)
+- Falls back to core agent loop for unregistered commands
+- Enables extensible command architecture
+
+**2. SubAgents Registry**
+- Pluggable sub-agent system for specialized tasks
+- Each sub-agent declares capabilities via registry
+- Init subagent handles environment setup
+- Extensible via `registerSubAgent()` API
+
+**3. Context Management**
+- `ContextManager` handles conversation history
+- `TokenCounter` tracks token usage (tiktoken)
+- `HistoryAnchor` manages context window compression
+- Automatic pruning to stay within LLM limits
+
+**4. Session Persistence**
+- `SessionManager` persists all interactions
+- Stored in `~/.bluma/sessions/<session-id>.json`
+- Survives across CLI restarts
+- Includes full tool call history and results
+
+**5. Skills System**
+- Pluggable knowledge modules (`skill_loader.ts`)
+- Built-in skills: `git-commit`, `git-pr`, `pdf`, `xlsx`, `skill-creator`
+- Each skill includes `SKILL.md` with workflows
+- Can include `references/` (docs) and `scripts/` (executables)
 
 ### Sequence Diagram
 ```mermaid
@@ -730,23 +929,140 @@ flowchart LR
 ---
 
 ## 💡 Usage Examples
-- **Run Initialization Command**
+
+### Interactive CLI Mode
+
+**1. Start a Conversation**
+```bash
+bluma
+```
+Then ask naturally:
+- "Help me refactor this authentication module"
+- "Run tests and fix any failures"
+- "Create a PDF report from this data"
+
+**2. Use Slash Commands**
+```bash
+/init              # Initialize environment with init subagent
+/todo              # View current task list
+/memory list       # List all coding memory entries
+/skills            # List available skills
+```
+
+**3. Load Skills for Specialized Tasks**
+```
+# The agent will automatically load skills when needed
+"Commit these changes with a proper message"     → loads git-commit skill
+"Create a pull request"                          → loads git-pr skill
+"Generate a PDF report"                          → loads pdf skill
+"Analyze this Excel file"                        → loads xlsx skill
+```
+
+**4. Live Overlays During Processing**
+While the agent is working, type guidance:
+```
+[hint] Focus on the authentication flow first
+[constraint] Don't modify files in tests/ yet
+[override] expected_replacements=2
+[assume] target_database=postgresql
+```
+
+**5. Tool Confirmation Flow**
+When the agent requests a sensitive operation:
+```
+┌─────────────────────────────────────────┐
+│  EDIT PREVIEW                           │
+│  File: src/auth/login.ts                │
+│  Lines 45-67                            │
+│                                         │
+│  - old code                             │
+│  + new code                             │
+└─────────────────────────────────────────┘
+
+[Accept] [Decline] [Accept Always] [Expand]
+```
+
+### Agent Mode (Sandbox / API Integration)
+
+**6. Call BluMa from Another System**
+```bash
+BLUMA_SANDBOX=true BLUMA_SANDBOX_NAME="agiweb" \
+node dist/main.js agent --input - << 'EOF'
+{
+  "session_id": "conv-123",
+  "message_id": "job-456",
+  "from_agent": "agiweb",
+  "to_agent": "bluma",
+  "action": "generate_report",
+  "context": {
+    "user_request": "Create sales report PDF"
+  },
+  "user_context": {
+    "userId": "13",
+    "userName": "Alex",
+    "companyId": "4"
+  },
+  "metadata": { "sandbox": true }
+}
+EOF
+```
+
+**7. Parse JSONL Output**
+The agent outputs structured events:
+```json
+{"event_type":"log","level":"info","message":"Starting..."}
+{"event_type":"action_status","payload":{"action":"Thinking"}}
+{"event_type":"backend_message","backend_type":"tool_call",...}
+{"event_type":"result","status":"success","data":{"attachments":["/app/artifacts/report.pdf"]}}
+```
+
+**8. Retrieve Generated Artifacts**
+Check the `attachments` array in the final `result` event:
+```json
+{
+  "event_type": "result",
+  "status": "success",
+  "data": {
+    "message_id": "job-456",
+    "last_assistant_message": "Report generated successfully",
+    "attachments": [
+      "/app/artifacts/sales_report.pdf",
+      "/app/artifacts/sales_data.csv"
+    ]
+  }
+}
+```
+
+### Common Workflows
+
+**9. Code Refactoring**
 ```
-/init
+User: "Refactor this function to use async/await"
+→ Agent reads file with read_file_lines
+→ Plans changes with todo
+→ Applies edits with edit_tool (shows preview)
+→ Runs tests with shell_command
+→ Reports results
 ```
-Executes the `init` subagent to prepare the working environment.
 
-- **Confirm an Edit Operation**
-When the system prompts an `edit_tool` operation, review the preview and choose:
+**10. Git Workflow**
 ```
-Accept | Decline | Accept Always
+User: "Commit my changes"
+→ Agent loads git-commit skill
+→ Runs git status --short
+→ Stages files with git add
+→ Writes conventional commit message
+→ Executes git commit
 ```
 
-- **Live Overlay**
-During a long-running task, you can send hints:
+**11. Data Analysis & Reporting**
 ```
-[hint] Prefer small batch edits
-[constraint] Avoid editing src/app/ui/**
+User: "Analyze sales.xlsx and create a summary"
+→ Agent loads xlsx skill
+→ Runs Python script to read Excel
+→ Processes data with pandas
+→ Generates PDF with charts
+→ Returns attachments array
 ```
 
 ---

package/dist/config/native_tools.json

@@ -560,7 +560,7 @@
           "properties": {
             "skill_name": {
               "type": "string",
-              "description": "Name of the skill to load. Examples: 'testing', 'git-conventional', 'docker', 'react'. Check available skills in the system prompt."
+              "description": "Exact skill name from the <available_skills> list in the system prompt (e.g. git-commit, git-pr, pdf). Do not invent names — use only names listed there."
             }
           },
           "required": [