@nomad-e/bluma-cli 0.2.1 → 0.5.0

package/dist/config/native_tools.json

@@ -227,41 +227,7 @@
         }
       }
     },
-    {
-      "type": "function",
-      "function": {
-        "name": "message",
-        "description": "Primary user-visible channel — use it generously. Call message_type \"info\" frequently during a turn (progress, findings, errors, next steps); multiple info calls per turn are required for good UX. The turn does not stop on \"info\". Use message_type \"result\" once when you finish this turn (final answer, deliverable, or question for the user); then the agent waits.",
-        "parameters": {
-          "type": "object",
-          "properties": {
-            "content": {
-              "type": "string",
-              "description": "Markdown body shown in the chat (user's language when appropriate)."
-            },
-            "message_type": {
-              "type": "string",
-              "enum": [
-                "info",
-                "result"
-              ],
-              "description": "Prefer \"info\" often while working (does not end turn). Use \"result\" only once to end the turn."
-            },
-            "attachments": {
-              "type": "array",
-              "items": {
-                "type": "string"
-              },
-              "description": "Optional file paths (absolute) to deliver as attachments. Put generated files under ./.bluma/artifacts/ (or paths returned by task_boundary / create_artifact); never a top-level ./artifacts/ folder — tools remap that to .bluma/artifacts/."
-            }
-          },
-          "required": [
-            "content",
-            "message_type"
-          ]
-        }
-      }
-    },
+
     {
       "type": "function",
       "function": {
@@ -328,6 +294,10 @@
             "filepath": {
               "type": "string",
               "description": "Path to the file to count lines from. Can be relative or absolute."
+            },
+            "file_path": {
+              "type": "string",
+              "description": "Alias for filepath, accepted for consistency with edit/file tools."
             }
           },
           "required": [
@@ -348,6 +318,10 @@
               "type": "string",
               "description": "Path to the file (workspace-relative or absolute)."
             },
+            "file_path": {
+              "type": "string",
+              "description": "Alias for filepath, accepted for consistency with edit/file tools."
+            },
             "offset": {
               "type": "integer",
               "description": "1-based start line; same as start_line. Defaults to 1."
@@ -720,30 +694,6 @@
         }
       }
     },
-    {
-      "type": "function",
-      "function": {
-        "name": "create_artifact",
-        "description": "Create or update an artifact under the workspace .bluma/artifacts/<session>/ directory (see task_boundary artifacts_dir). Use for plans, walkthroughs, notes, or deliverables. Not the same as ~/.bluma.",
-        "parameters": {
-          "type": "object",
-          "properties": {
-            "filename": {
-              "type": "string",
-              "description": "Name of the artifact file to create. Examples: 'implementation_plan.md', 'walkthrough.md', 'notes.md'."
-            },
-            "content": {
-              "type": "string",
-              "description": "Content to write to the artifact file. Supports markdown formatting."
-            }
-          },
-          "required": [
-            "filename",
-            "content"
-          ]
-        }
-      }
-    },
     {
       "type": "function",
       "function": {
@@ -823,7 +773,7 @@
       "type": "function",
       "function": {
         "name": "ask_user_question",
-        "description": "Ask the user one or more multiple-choice questions in the terminal (AskUserQuestion). Blocks until they answer. Only the first question is shown; options must be single-select.",
+        "description": "Ask the user one or more multiple-choice questions in the terminal (AskUserQuestion). Blocks until they answer. Supports multiple questions, option previews, and optional multi-select.",
         "parameters": {
           "type": "object",
           "properties": {
@@ -834,14 +784,15 @@
                 "properties": {
                   "question": { "type": "string", "description": "Question text" },
                   "header": { "type": "string", "description": "Short section title" },
-                  "multiSelect": { "type": "boolean", "description": "Not supported yet; omit or false." },
+                  "multiSelect": { "type": "boolean", "description": "Allow selecting multiple options for this question." },
                   "options": {
                     "type": "array",
                     "items": {
                       "type": "object",
                       "properties": {
                         "label": { "type": "string" },
-                        "description": { "type": "string" }
+                        "description": { "type": "string" },
+                        "preview": { "type": "string", "description": "Optional rendered preview shown beside the options." }
                       },
                       "required": ["label"]
                     }

package/dist/config/plan_mode_instructions.md

@@ -0,0 +1,218 @@
+# Plan Mode Instructions
+
+## Overview
+
+Plan Mode is a structured approach to problem-solving that emphasizes **clarity, alignment, and decision-completeness** before implementation.
+
+When in Plan Mode, you must follow the **3-phase workflow**:
+
+---
+
+## Phase 1: Grounding (Understanding)
+
+**Goal:** Demonstrate deep understanding of the problem before proposing solutions.
+
+**Actions:**
+- Read relevant files to understand context
+- Identify the root cause, not just symptoms
+- Map out the codebase structure affected
+- Ask clarifying questions if information is missing
+
+**Output format:**
+```
+<proposed_plan>
+## Understanding
+
+### What I Found
+- [Key findings from investigation]
+- [Root cause analysis]
+- [Files and lines involved]
+
+### Context
+- [Relevant code patterns]
+- [Dependencies and side effects]
+</proposed_plan>
+```
+
+---
+
+## Phase 2: Intent (Proposal)
+
+**Goal:** Present a clear, actionable plan for user approval.
+
+**Actions:**
+- Propose specific changes with file paths and line numbers
+- Explain the "why" behind each decision
+- Consider alternatives and trade-offs
+- Make the plan "decision complete" (user can approve without asking follow-ups)
+
+**Output format:**
+```
+<proposed_plan>
+## Proposed Plan
+
+### Objective
+[Clear statement of what we're fixing/building]
+
+### Approach
+1. [Step 1 with specific files/lines]
+2. [Step 2 with specific files/lines]
+3. [Step 3...]
+
+### Changes
+- **File: `src/path/to/file.ts`**
+  - Line 42: Change X to Y because...
+  - Add function `helper()` at line 50 to...
+
+### Alternatives Considered
+- Alternative A: [why not chosen]
+- Alternative B: [why not chosen]
+
+### Risks & Mitigations
+- [Potential issue] → [mitigation strategy]
+
+### Success Criteria
+- [How we'll know this is working]
+- [Tests to run]
+</proposed_plan>
+```
+
+---
+
+## Phase 3: Implementation (Execution)
+
+**Goal:** Execute the approved plan with precision.
+
+**Actions:**
+- Follow the approved plan exactly
+- Use `enter_plan_mode` before making changes
+- Make surgical, targeted edits
+- Run tests after each change
+- Use `exit_plan_mode` when complete
+
+**Important:**
+- Do NOT deviate from the approved plan without user consent
+- If you discover new issues, pause and propose an updated plan
+- Commit changes with clear, descriptive messages
+
+---
+
+## Plan Mode Rules
+
+### DO:
+✅ Use `<proposed_plan>` tags for all plans
+✅ Make plans "decision complete" (no follow-up questions needed)
+✅ Include specific file paths and line numbers
+✅ Explain reasoning behind each decision
+✅ Consider alternatives and trade-offs
+✅ Use `enter_plan_mode` before making changes
+✅ Run tests and verify changes work
+
+### DON'T:
+❌ Make changes without a proposed plan
+❌ Propose vague or incomplete plans
+❌ Skip the grounding phase (understand first!)
+❌ Deviate from approved plan without consent
+❌ Make multiple unrelated changes in one plan
+❌ Forget to run tests after implementation
+
+---
+
+## When to Use Plan Mode
+
+**Use Plan Mode when:**
+- Fixing bugs (especially complex ones)
+- Adding new features
+- Refactoring code
+- Making architectural changes
+- Any change that affects multiple files
+
+**Skip Plan Mode for:**
+- Simple, one-line fixes
+- Reading files to gather information
+- Quick exploratory tasks
+- User explicitly asks to "just fix it"
+
+---
+
+## Plan Mode Workflow Summary
+
+1. **Investigate** → Read files, understand the problem
+2. **Propose** → Create `<proposed_plan>` with clear steps
+3. **Wait** → Let user review and approve
+4. **Activate** → Call `enter_plan_mode` when approved
+5. **Implement** → Make the changes exactly as proposed
+6. **Verify** → Run tests, confirm success
+7. **Complete** → Call `exit_plan_mode` and report results
+
+---
+
+## Example Plan
+
+```
+<proposed_plan>
+## Understanding
+
+### What I Found
+- Null pointer in `src/auth/validate.ts:42` when `Session.expired` is true
+- The `user` field is undefined but code tries to access `user.id`
+- This happens because token cache isn't cleared on expiry
+
+### Context
+- `validateToken()` returns cached token even when expired
+- `getSession()` doesn't check if user exists before accessing properties
+
+## Proposed Plan
+
+### Objective
+Fix null pointer exception when session expires but token is cached
+
+### Approach
+1. Add null check in `validate.ts:42` before accessing `user.id`
+2. Clear token cache when session expires
+3. Add test case for expired session with cached token
+
+### Changes
+- **File: `src/auth/validate.ts`**
+  - Line 42: Add `if (!user) return { valid: false, error: 'Session expired' };`
+  - Line 58: Add cache invalidation when `Session.expired === true`
+
+### Alternatives Considered
+- Alternative: Always refresh token on expiry → Too aggressive, impacts performance
+- Alternative: Remove caching entirely → Loses benefit of caching valid tokens
+
+### Risks & Mitigations
+- Risk: Breaking existing valid sessions → Mitigation: Add comprehensive tests
+- Risk: Performance impact from cache invalidation → Mitigation: Only invalidate on confirmed expiry
+
+### Success Criteria
+- No null pointer on expired session
+- Valid sessions still cached and fast
+- Test coverage for edge case added
+</proposed_plan>
+```
+
+---
+
+## Tool Usage in Plan Mode
+
+When `enter_plan_mode` is active:
+- All write/execute tools require explicit confirmation
+- This ensures you review each change before it happens
+- Use this as a safety check, not a barrier
+
+Tools that require confirmation in Plan Mode:
+- `edit_tool`
+- `file_write`
+- `shell_command`
+- `spawn_agent`
+
+---
+
+## Final Notes
+
+**Remember:** A good plan is specific, actionable, and decision-complete.
+The user should be able to approve your plan without asking "what about X?" or "why this approach?"
+
+If you're unsure, **ask questions first** before proposing the plan.
+Better to spend 2 minutes clarifying than 20 minutes fixing the wrong thing.