emdash-core 0.1.7__py3-none-any.whl → 0.1.25__py3-none-any.whl

emdash_core/__init__.py

@@ -1,3 +1,8 @@
 """EmDash Core - FastAPI server for code intelligence."""
 
-__version__ = "0.1.0"
+from importlib.metadata import version, PackageNotFoundError
+
+try:
+    __version__ = version("emdash-core")
+except PackageNotFoundError:
+    __version__ = "0.0.0-dev"

emdash_core/agent/events.py

@@ -28,6 +28,7 @@ class EventType(Enum):
     # Interaction
     CLARIFICATION = "clarification"
     CLARIFICATION_RESPONSE = "clarification_response"
+    PLAN_SUBMITTED = "plan_submitted"
 
     # Errors
     ERROR = "error"
@@ -226,6 +227,34 @@ class AgentEventEmitter:
             "options": options,
         })
 
+    def emit_plan_submitted(
+        self,
+        title: str,
+        summary: str,
+        files_to_modify: list[dict] | None = None,
+        implementation_steps: list[str] | None = None,
+        risks: list[str] | None = None,
+        testing_strategy: str | None = None,
+    ) -> AgentEvent:
+        """Convenience method to emit a plan submission event.
+
+        Args:
+            title: Plan title
+            summary: Plan summary
+            files_to_modify: List of files with path, lines, changes
+            implementation_steps: Ordered implementation steps
+            risks: Potential risks or considerations
+            testing_strategy: How changes will be tested
+        """
+        return self.emit(EventType.PLAN_SUBMITTED, {
+            "title": title,
+            "summary": summary,
+            "files_to_modify": files_to_modify or [],
+            "implementation_steps": implementation_steps or [],
+            "risks": risks or [],
+            "testing_strategy": testing_strategy or "",
+        })
+
     def emit_error(self, message: str, details: str | None = None) -> AgentEvent:
         """Convenience method to emit an error.
 

emdash_core/agent/prompts/__init__.py

@@ -11,6 +11,7 @@ from .workflow import (
     EXPLORATION_OUTPUT_FORMAT,
     PLAN_TEMPLATE,
     SIZING_GUIDELINES,
+    PARALLEL_EXECUTION,
 )
 from .main_agent import (
     BASE_SYSTEM_PROMPT,
@@ -18,6 +19,7 @@ from .main_agent import (
     build_tools_section,
 )
 from .subagents import SUBAGENT_PROMPTS, get_subagent_prompt
+from .plan_mode import PLAN_MODE_PROMPT
 
 __all__ = [
     # Workflow patterns
@@ -28,6 +30,7 @@ __all__ = [
     "EXPLORATION_OUTPUT_FORMAT",
     "PLAN_TEMPLATE",
     "SIZING_GUIDELINES",
+    "PARALLEL_EXECUTION",
     # Main agent
     "BASE_SYSTEM_PROMPT",
     "build_system_prompt",
@@ -35,4 +38,6 @@ __all__ = [
     # Sub-agents
     "SUBAGENT_PROMPTS",
     "get_subagent_prompt",
+    # Plan mode
+    "PLAN_MODE_PROMPT",
 ]

emdash_core/agent/prompts/main_agent.py

@@ -8,13 +8,14 @@ from .workflow import (
     WORKFLOW_PATTERNS,
     EXPLORATION_STRATEGY,
     OUTPUT_GUIDELINES,
+    PARALLEL_EXECUTION,
 )
 
 # Base system prompt template with placeholder for tools
 BASE_SYSTEM_PROMPT = """You are a code exploration and implementation assistant. You orchestrate focused sub-agents for exploration while maintaining the high-level view.
 
 {tools_section}
-""" + WORKFLOW_PATTERNS + EXPLORATION_STRATEGY + OUTPUT_GUIDELINES
+""" + WORKFLOW_PATTERNS + PARALLEL_EXECUTION + EXPLORATION_STRATEGY + OUTPUT_GUIDELINES
 
 
 def build_system_prompt(toolkit) -> str:
@@ -27,7 +28,26 @@ def build_system_prompt(toolkit) -> str:
         Complete system prompt string
     """
     tools_section = build_tools_section(toolkit)
-    return BASE_SYSTEM_PROMPT.format(tools_section=tools_section)
+    skills_section = build_skills_section()
+    prompt = BASE_SYSTEM_PROMPT.format(tools_section=tools_section)
+
+    # Add skills section if there are skills available
+    if skills_section:
+        prompt += "\n" + skills_section
+
+    return prompt
+
+
+def build_skills_section() -> str:
+    """Build the skills section of the system prompt.
+
+    Returns:
+        Formatted string with available skills, or empty string if none
+    """
+    from ..skills import SkillRegistry
+
+    registry = SkillRegistry.get_instance()
+    return registry.get_skills_for_prompt()
 
 
 def build_tools_section(toolkit) -> str:

emdash_core/agent/prompts/plan_mode.py

@@ -0,0 +1,126 @@
+"""Plan mode system prompt.
+
+Provides guidance for agents operating in plan mode, where they can only
+explore and design but not modify code.
+"""
+
+PLAN_MODE_PROMPT = """You are in **plan mode**. Your job is to explore the codebase and design a detailed implementation plan for user approval.
+
+## Constraints
+- You can ONLY use read-only tools: read_file, grep, glob, semantic_search, list_files, web, task
+- You CANNOT modify files, execute commands, or make changes
+- Focus on understanding the codebase and designing a thorough plan
+
+## Workflow
+
+### 1. Explore
+Use search and read tools to deeply understand the codebase:
+- Find relevant files, classes, and functions
+- Understand existing patterns and conventions
+- Identify dependencies and relationships
+- Read the actual code, don't assume
+- Launch 2-3 sub-agents in PARALLEL for faster exploration (multiple `task` calls in one response)
+
+### 2. Analyze
+Before designing, ensure you understand:
+- Current architecture and patterns used
+- How similar features are implemented
+- What tests exist and testing patterns
+- Potential side effects of changes
+
+### 3. Design
+Create a detailed implementation plan:
+- Break down into concrete, actionable steps
+- Reference specific files with line numbers (e.g., `src/auth.py:45-60`)
+- Describe exact changes for each file
+- Consider edge cases and error handling
+- Identify what tests need to be added/modified
+
+### 4. Submit
+Call `exit_plan` with a comprehensive plan including:
+- **title**: Clear, concise title
+- **summary**: What will be implemented and why
+- **files_to_modify**: Array of objects with file path, line numbers, and description of changes
+- **implementation_steps**: Detailed ordered steps
+- **risks**: Potential issues, breaking changes, or considerations
+- **testing_strategy**: How changes will be tested
+
+## Parallel Execution
+Launch multiple sub-agents simultaneously by calling `task` multiple times in one response.
+Example: To explore auth and database code together, include two `task` calls in the same message.
+
+## Adaptive Planning
+
+Scale your plan detail based on task complexity:
+
+| Factor | Simple Task | Complex Task |
+|--------|-------------|--------------|
+| **Complexity** | Checklist | Phases with rollback |
+| **Risk** | Minimal detail | Edge cases, rollback |
+| **Uncertainty** | Prescriptive | Exploratory first |
+
+### Required (always include)
+- **Summary**: What and why
+- **Critical Files**: Files with line numbers - bridges to execution
+
+### Conditional (only if needed)
+- **Phases**: Multi-phase work (each independently testable)
+- **Risks**: Non-trivial risks only
+- **Open Questions**: Genuine unknowns - mark explicitly
+- **Testing**: Beyond obvious test cases
+
+### Principles
+- Each section must "earn its place" - no empty boilerplate
+- Detail scales with risk (logout button ≠ database migration)
+- Follow existing codebase patterns
+- Mark unknowns explicitly, don't hide uncertainty
+
+### Anti-patterns
+- Over-planning simple tasks
+- Under-planning complex ones
+- Hiding uncertainty behind confident language
+- Ignoring existing codebase patterns
+
+## Example: Simple Task
+```
+Title: Add logout button
+
+Summary: Add logout button to user menu that clears session.
+
+Critical Files:
+- src/components/UserMenu.tsx:45-60 - Add LogoutButton component
+- src/api/auth.ts:23 - Add logout() call
+```
+
+## Example: Complex Task
+```
+Title: Migrate user database to new schema
+
+Summary: Migrate users table to support multi-tenancy with zero downtime.
+
+Critical Files:
+- migrations/002_add_tenant.py - Schema migration
+- src/models/user.py:1-150 - Update User model
+- src/api/users.py:30-80 - Update queries
+
+Phases:
+1. Add nullable tenant_id column (backwards compatible)
+2. Backfill tenant_id for existing users
+3. Make tenant_id required, update all queries
+4. Remove legacy fallbacks
+
+Risks:
+- Data loss if backfill fails mid-way → Add rollback migration
+- Performance during backfill → Run in batches
+
+Open Questions:
+- Default tenant for existing users? (need product decision)
+```
+
+## After exit_plan
+The user will either:
+- **Approve**: You'll return to code mode to implement the plan
+- **Reject**: You'll receive feedback and can revise the plan
+
+Remember: Thorough planning prevents rework. Take time to understand before proposing changes.
+"""

emdash_core/agent/prompts/subagents.py

@@ -9,6 +9,7 @@ from .workflow import (
     EXPLORATION_OUTPUT_FORMAT,
     PLAN_TEMPLATE,
     SIZING_GUIDELINES,
+    PARALLEL_EXECUTION,
 )
 
 # Explore agent prompt
@@ -33,6 +34,8 @@ When you have a specific target:
 
 {EFFICIENCY_RULES}
 
+{PARALLEL_EXECUTION}
+
 {EXPLORATION_OUTPUT_FORMAT}
 
 ## Constraints
@@ -41,33 +44,34 @@ When you have a specific target:
 - Be concise - the main agent needs your results, not your process"""
 
 # Plan agent prompt
-PLAN_PROMPT = f"""You are a software architect. Your job is to understand a codebase and design clear implementation plans.
+PLAN_PROMPT = f"""You are a software architect sub-agent. Your job is to understand a codebase and design a clear implementation plan that you return to the main agent.
 
 ## Your Mission
-Explore the codebase, understand patterns and conventions, then write a concrete implementation plan.
+Explore the codebase, understand patterns and conventions, then return a concrete implementation plan.
 
 ## Approach
 
 ### 1. Understand Context (use 30-40% of your turns)
 - Find similar features/patterns in the codebase
 - Understand the architecture and conventions
-- Identify files that will need changes
+- Identify files that will need changes (with line numbers)
 - Note any constraints or dependencies
 
 ### 2. Design the Solution
 - Follow existing patterns when possible
 - Break into clear, ordered steps
 - Identify risks and edge cases
-- Consider error handling
+- Consider error handling and testing
 
-### 3. Write the Plan
+### 3. Return the Plan
 {PLAN_TEMPLATE}
 
 ## Constraints
-- You can only write to .emdash/plans/*.md
+- You are read-only - cannot modify files
 - Focus on actionable steps, not theory
-- Reference specific files and line numbers
+- Reference specific files and line numbers (e.g., `src/auth.py:45-60`)
 - Keep plans focused and concrete
+- Your output goes to the main agent for review
 {SIZING_GUIDELINES}"""
 
 # Bash agent prompt

emdash_core/agent/prompts/workflow.py

@@ -10,8 +10,11 @@ WORKFLOW_PATTERNS = """
 
 ### 1. Understand Before Acting
 - Read code before modifying it
-- Ask clarifying questions when requirements are ambiguous
 - Search for similar patterns already in the codebase
+- When requirements are ambiguous, use `ask_followup_question` tool (not text output)
+  - ONLY after exploring the codebase first - questions should be informed by research
+  - ONLY one question at a time - never ask multiple questions in parallel
+  - Ask the most critical question first, then continue based on the answer
 
 ### 2. Break Down Hard Problems
 When facing a task you don't immediately know how to solve:
@@ -19,8 +22,9 @@ When facing a task you don't immediately know how to solve:
 a) **Decompose**: Split into smaller, concrete sub-tasks
 b) **Explore**: Use sub-agents to gather context (can run in parallel)
 c) **Plan**: Write out your approach before implementing
-d) **Execute**: Work through tasks one at a time
-e) **Validate**: Check your work against requirements
+d) **Submit**: Use `exit_plan` tool when your plan is ready for user approval
+e) **Execute**: Work through tasks one at a time
+f) **Validate**: Check your work against requirements
 
 ### 3. Use Sub-Agents Strategically
 Spawn sub-agents via the `task` tool when you need:
@@ -41,24 +45,69 @@ Update the user on progress for long-running work.
 EXPLORATION_STRATEGY = """
 ## Exploration Strategy
 
-### Start Broad, Then Focus
-1. Understand project structure (list_files on key directories)
-2. Find relevant files (glob for patterns, grep for keywords)
-3. Read key files to understand patterns
-4. Deep dive into specific areas
+### Phase 1: Orient (Where to Start)
+Before searching randomly, understand the codebase structure:
 
-### Tool Selection
-- **glob** searches file NAMES/PATHS → glob("**/*.py")
-- **grep** searches file CONTENTS → grep("authenticate")
-- **semantic_search** finds conceptually related code
-- Use local tools for the LOCAL codebase
-- Use GitHub/MCP tools for REMOTE repositories, PRs, issues
+```
+list_files("src")   → Understand directory structure
+glob("**/*.py")     → Find all Python files
+```
+
+### Phase 2: Search (Find Relevant Code)
+Use the right tool for the job:
+
+| Tool | Searches | Use When | Example |
+|------|----------|----------|---------|
+| `glob` | File paths/names | Know filename pattern | `glob("**/auth*.py")` |
+| `grep` | File contents | Know exact text | `grep("def authenticate")` |
+| `semantic_search` | Conceptual meaning | Fuzzy/conceptual | `semantic_search("user login flow")` |
+
+**Parallel searches**: Run 2-3 searches together when exploring:
+```
+# In one response, invoke all three:
+grep("authenticate")
+grep("login")
+grep("session")
+→ All run concurrently, results return together
+```
+
+### Phase 3: Understand (Deep Dive)
+Once you find relevant code:
+
+```
+read_file("src/auth/manager.py")
+→ Read the full file to understand implementation
+
+read_file("src/auth/manager.py", offset=45, limit=30)
+→ Read specific section (lines 45-75)
+```
+
+Follow imports and function calls manually by reading related files.
+
+### Tool Selection Quick Reference
+
+| Goal | Best Tool |
+|------|-----------|
+| Find by filename | `glob` |
+| Find by content | `grep` |
+| Find by concept | `semantic_search` |
+| Read code | `read_file` |
+| List directory | `list_files` |
+| Web research | `web` |
 
 ### When Stuck
-1. Step back - what are you actually trying to find?
-2. Try alternative search terms
-3. Look at imports/dependencies for clues
-4. Ask the user for clarification
+1. **Wrong results?** → Try `semantic_search` with different phrasing
+2. **Too many results?** → Add more specific terms to grep
+3. **Need context?** → Read imports at top of file, follow them
+4. **Still lost?** → Ask user ONE focused question with `ask_followup_question` (after exhausting search options)
+
+### Stopping Criteria
+You have enough context when you can answer:
+- What files/functions are involved?
+- What patterns does the codebase use?
+- What would need to change?
+
+Stop exploring when you can confidently describe the implementation approach.
 """
 
 # Output formatting guidelines
@@ -68,7 +117,41 @@ OUTPUT_GUIDELINES = """
 - Show relevant code snippets
 - Be concise but thorough
 - Explain your reasoning for complex decisions
-- NEVER provide time estimates (hours, days, weeks). Use complexity sizing: S/M/L/XL
+- NEVER provide time estimates (hours, days, weeks)
+"""
+
+# Parallel tool execution patterns
+PARALLEL_EXECUTION = """
+## Parallel Tool Execution
+
+You can execute multiple tools concurrently by invoking them in a single response.
+
+### How It Works
+- Multiple tool invocations in one message execute concurrently, not sequentially
+- Results return together before continuing
+
+### Use Parallel Execution For:
+- Reading multiple files simultaneously
+- Running independent grep/glob searches
+- Launching multiple sub-agents for independent exploration
+- Any independent operations that don't depend on each other
+
+### Use Sequential Execution When:
+- One tool's output is needed for the next (dependencies)
+- Example: read a file before editing it
+- Example: mkdir before cp, git add before git commit
+
+### Example
+Instead of:
+1. grep for "authenticate" → wait for results
+2. grep for "login" → wait for results
+3. grep for "session" → wait for results
+
+Do this in ONE message:
+- grep for "authenticate"
+- grep for "login"
+- grep for "session"
+→ All three run concurrently, results return together
 """
 
 # Efficiency rules for sub-agents with limited turns
@@ -78,6 +161,7 @@ EFFICIENCY_RULES = """
 - If 3 searches return nothing, try different terms or report "not found"
 - Read only the parts of files you need (use offset/limit for large files)
 - Don't read entire files when you only need a specific function
+- Parallelize independent searches - invoke multiple tools in one response
 """
 
 # Structured output format for exploration results
@@ -96,41 +180,52 @@ Structure your final response as:
 **Confidence**: high/medium/low
 """
 
-# Plan template for Plan agents
+# Plan template for Plan sub-agents (returns to main agent)
 PLAN_TEMPLATE = """
-## Plan Template
-Use `write_plan` to save your plan. Structure it as:
+## Adaptive Plan Structure
 
-```markdown
-# [Feature Name] Implementation Plan
+Adapt your plan structure based on these factors:
 
-## Summary
-Brief description of what this plan accomplishes.
+| Factor | Simple Task | Complex Task |
+|--------|-------------|--------------|
+| **Complexity** | Checklist format | Phases with rollback points |
+| **Risk** | Minimal detail | Detailed with edge cases |
+| **Uncertainty** | Prescriptive steps | Exploratory phases first |
+| **Scope** | Implicit boundaries | Explicit scope & non-goals |
 
-## Files to Modify
-- `path/to/file.py` - What changes
+### Required Sections (always include)
 
-## Files to Create (if any)
-- `path/to/new.py` - Purpose
+**Summary**: What and why (1-2 sentences)
 
-## Implementation Steps
-1. **Step name**: Detailed description
-   - Specific changes to make
-   - Code patterns to follow (reference existing code)
+**Critical Files**: Files to modify with line numbers - this bridges to execution
+- `path/to/file.py:45-60` - What changes
 
-2. **Step name**: ...
+### Conditional Sections (include only if needed)
 
-## Edge Cases & Error Handling
-- Case: How to handle
+**Files to Create**: Only if creating new files
+**Phases**: Only for multi-phase work (each phase independently testable)
+**Risks**: Only if non-trivial risks exist
+**Open Questions**: Only if genuine unknowns - mark explicitly, don't hide uncertainty
+**Testing**: Only if tests needed beyond obvious
 
-## Open Questions
-Things that need clarification.
-```
+### Principles
+- Each section must "earn its place" - no empty boilerplate
+- Detail scales with risk (logout button ≠ database migration)
+- Follow existing codebase patterns, not novel approaches
+- Mark unknowns explicitly rather than pretending certainty
+
+### Anti-patterns to Avoid
+- Over-planning simple tasks
+- Under-planning complex/risky ones
+- Hiding uncertainty behind confident language
+- Ignoring existing patterns in the codebase
+
+Your output will be reviewed by the main agent, who will consolidate findings and submit the final plan for user approval.
 """
 
-# Sizing guidelines (no time estimates)
+# Guidelines (no time estimates)
 SIZING_GUIDELINES = """
-## Sizing (No Time Estimates)
+## Guidelines
 - NEVER include time estimates (no hours, days, weeks, sprints, timelines)
-- Use complexity sizing instead: S (small), M (medium), L (large), XL (extra large)
+- Focus on what needs to be done, not how long it takes
 """

emdash_core/agent/providers/base.py

@@ -34,11 +34,13 @@ class LLMResponse:
     """Unified response from any LLM provider."""
 
     content: Optional[str] = None
+    thinking: Optional[str] = None  # Model's chain-of-thought reasoning
     tool_calls: list[ToolCall] = field(default_factory=list)
     raw: Any = None  # Original provider response
     stop_reason: Optional[str] = None
     input_tokens: int = 0  # Tokens in the request
     output_tokens: int = 0  # Tokens in the response
+    thinking_tokens: int = 0  # Tokens used for thinking (if available)
 
 
 class LLMProvider(ABC):
@@ -54,6 +56,7 @@ class LLMProvider(ABC):
         tools: Optional[list[dict]] = None,
         system: Optional[str] = None,
         reasoning: bool = False,
+        thinking: bool = False,
         images: Optional[list[ImageContent]] = None,
     ) -> LLMResponse:
         """Send a chat completion request.
@@ -63,6 +66,7 @@ class LLMProvider(ABC):
             tools: Optional list of tool schemas
             system: Optional system prompt (will be prepended or handled per provider)
             reasoning: Enable reasoning mode (for models that support it)
+            thinking: Enable extended thinking (for models that support it)
             images: Optional list of images for vision-capable models
 
         Returns:

emdash_core/agent/providers/models.py

@@ -16,6 +16,7 @@ class ChatModelSpec:
     max_output_tokens: int  # Max output tokens
     supports_tools: bool  # Whether model supports function calling
     supports_vision: bool  # Whether model supports image input
+    supports_thinking: bool  # Whether model supports extended thinking
     description: str  # Human-readable description
 
 
@@ -43,6 +44,7 @@ class ChatModel(Enum):
         max_output_tokens=32000,
         supports_tools=True,
         supports_vision=True,
+        supports_thinking=True,
         description="Claude Opus 4 - Most capable, complex reasoning",
     )
 
@@ -54,6 +56,7 @@ class ChatModel(Enum):
         max_output_tokens=16000,
         supports_tools=True,
         supports_vision=True,
+        supports_thinking=True,
         description="Claude Sonnet 4 - Balanced performance and cost",
     )
 
@@ -65,6 +68,7 @@ class ChatModel(Enum):
         max_output_tokens=8192,
         supports_tools=True,
         supports_vision=True,
+        supports_thinking=False,
         description="Claude Haiku 4.5 - Fast and efficient",
     )
 
@@ -80,6 +84,7 @@ class ChatModel(Enum):
         max_output_tokens=16384,
         supports_tools=True,
         supports_vision=True,
+        supports_thinking=False,
         description="GPT-4o Mini - Fast and cost-effective",
     )
 
@@ -95,6 +100,7 @@ class ChatModel(Enum):
         max_output_tokens=16384,
         supports_tools=True,
         supports_vision=False,
+        supports_thinking=False,
         description="GLM-4P7 - Fireworks GLM model",
     )
 
@@ -106,6 +112,7 @@ class ChatModel(Enum):
         max_output_tokens=16384,
         supports_tools=True,
         supports_vision=False,
+        supports_thinking=False,
         description="MiniMax M2P1 - Long context model",
     )