connectonion 0.6.1__py3-none-any.whl → 0.6.3__py3-none-any.whl

connectonion/cli/co_ai/prompts/workflow.md

@@ -0,0 +1,89 @@
+# Workflow: Solving Problems with ConnectOnion Agents
+
+**When a user describes a problem, create a ConnectOnion agent to solve it.**
+
+## Step 1: Confirm Design with ask_user (REQUIRED)
+
+**BEFORE writing any code, use ask_user to confirm the agent design.**
+
+```python
+ask_user(
+    question="Which approach? (We can adjust later)",
+    options=[
+        "Atomic: 'Clean /downloads' → list_files, get_hash, delete → 'Deleted 5'",
+        "Safe: 'Clean safely' → find_duplicates, move_to_trash → 'Moved to trash'",
+        "Interactive: 'Find duplicates' → scan, ask_confirm, delete → 'User confirmed'",
+    ]
+)
+```
+
+**DO NOT skip this step. DO NOT use plan_mode for simple agent creation.**
+
+## Step 2: Write the Agent (Single File)
+
+After user confirms, write a Python file with ConnectOnion framework:
+
+```python
+from connectonion import Agent
+
+def list_files(dir: str) -> list[str]:
+    """List all files in directory."""
+    from pathlib import Path
+    return [str(f) for f in Path(dir).iterdir() if f.is_file()]
+
+def get_hash(path: str) -> str:
+    """Get MD5 hash of a file."""
+    import hashlib
+    return hashlib.md5(open(path, 'rb').read()).hexdigest()
+
+def delete_file(path: str) -> str:
+    """Delete a file."""
+    import os
+    os.remove(path)
+    return f"Deleted {path}"
+
+agent = Agent("cleaner", tools=[list_files, get_hash, delete_file])
+agent.input("Find and remove duplicate files in /downloads")
+```
+
+## Step 3: Done
+
+Report completion. No plan mode, no complex workflow.
+
+---
+
+## When to Use Plan Mode (NOT for agent creation)
+
+Reserve `enter_plan_mode()` for:
+- Multi-file refactors
+- Architecture changes
+- Complex features with unclear requirements
+- Tasks touching 5+ files
+
+**Do NOT use plan mode for:**
+- Creating a single ConnectOnion agent
+- Simple file operations
+- Clear, well-defined tasks
+
+---
+
+## NEVER DO THIS
+
+```python
+# BAD: Standalone script with argparse
+import argparse
+import hashlib
+def main():
+    parser = argparse.ArgumentParser()
+    # ... hardcoded logic ...
+
+# BAD: Using plan_mode for simple agent creation
+enter_plan_mode()  # Overkill for a single-file agent
+```
+
+## Key Rules
+
+1. **ask_user FIRST** - Confirm design before coding
+2. **from connectonion import Agent** - Always use the framework
+3. **Atomic tools** - Each function does ONE thing
+4. **No plan_mode for agents** - Just ask_user → write → done

connectonion/cli/co_ai/reminders.py

@@ -0,0 +1,159 @@
+"""System reminders for contextual guidance.
+
+System reminders are automatically injected into tool results or conversation
+to provide contextual constraints and guidance. They override default behavior
+when applicable.
+
+Usage:
+    from connectonion.cli.co_ai.reminders import inject_reminder, REMINDERS
+
+    # Inject a specific reminder
+    result = inject_reminder(tool_result, "plan_mode_active")
+
+    # Check if reminder should be shown
+    if should_show_todo_reminder(agent):
+        result = inject_reminder(result, "todo_reminder")
+"""
+
+from typing import Optional, Dict, Any
+from functools import wraps
+
+
+# System reminder templates
+REMINDERS: Dict[str, str] = {
+    # Plan mode reminder - injected when plan mode is active
+    "plan_mode_active": """<system-reminder>
+Plan mode is active. You are in READ-ONLY exploration mode.
+- You can ONLY use: glob, grep, read_file to explore
+- You can ONLY write to the plan file (.co/PLAN.md)
+- Do NOT make any code changes until plan is approved
+- Use write_plan() to update your plan
+- Use exit_plan_mode() when plan is complete
+</system-reminder>""",
+
+    # Todo reminder - gentle nudge to use todo tracking
+    "todo_reminder": """<system-reminder>
+Consider using todo_list() to track progress for multi-step tasks.
+Mark tasks complete immediately when finished.
+</system-reminder>""",
+
+    # Read-only mode for explore agent
+    "read_only": """<system-reminder>
+This is READ-ONLY mode. You are PROHIBITED from modifying any files.
+Only use: glob, grep, read_file, and read-only bash commands.
+</system-reminder>""",
+
+    # Security reminder after reading sensitive files
+    "security": """<system-reminder>
+This file may contain sensitive information (credentials, keys, tokens).
+- Never expose secrets in output
+- Never commit this file if it contains real credentials
+- Consider using environment variables instead
+</system-reminder>""",
+
+    # Anti-over-engineering reminder
+    "simplicity": """<system-reminder>
+Keep it simple:
+- Only change what's directly needed
+- Don't add error handling for scenarios that can't happen
+- Three similar lines > premature abstraction
+- If unused, delete completely
+</system-reminder>""",
+
+    # Workflow reminder - injected when writing Python files
+    "connectonion_workflow": """<system-reminder>
+When creating agents, ALWAYS use ConnectOnion framework:
+- `from connectonion import Agent`
+- Atomic tool functions (one thing each)
+- `agent = Agent("name", tools=[...])` + `agent.input("task")`
+
+NEVER create standalone scripts with argparse. NEVER skip ask_user confirmation.
+</system-reminder>""",
+
+    # After code write reminder
+    "after_write_code": """<system-reminder>
+Code written. If this is an agent:
+- Verify it uses `from connectonion import Agent`
+- Verify tools are atomic functions
+- If it's a standalone script with argparse, REWRITE using ConnectOnion
+</system-reminder>""",
+}
+
+
+def inject_reminder(content: str, reminder_key: str) -> str:
+    """
+    Inject a system reminder into content.
+
+    Args:
+        content: The original content (tool result, message, etc.)
+        reminder_key: Key from REMINDERS dict
+
+    Returns:
+        Content with reminder injected at the end
+    """
+    if reminder_key not in REMINDERS:
+        return content
+
+    reminder = REMINDERS[reminder_key]
+    return f"{content}\n\n{reminder}"
+
+
+def with_reminder(reminder_key: str):
+    """
+    Decorator to inject a reminder into tool results.
+
+    Usage:
+        @with_reminder("plan_mode_active")
+        def some_tool(...):
+            return result
+    """
+    def decorator(func):
+        @wraps(func)
+        def wrapper(*args, **kwargs):
+            result = func(*args, **kwargs)
+            if isinstance(result, str):
+                return inject_reminder(result, reminder_key)
+            return result
+        return wrapper
+    return decorator
+
+
+def should_show_security_reminder(file_path: str) -> bool:
+    """Check if file path suggests sensitive content."""
+    sensitive_patterns = [
+        ".env",
+        "credentials",
+        "secrets",
+        "config/prod",
+        "keys",
+        "password",
+        "token",
+        ".pem",
+        ".key",
+    ]
+    path_lower = file_path.lower()
+    return any(pattern in path_lower for pattern in sensitive_patterns)
+
+
+def get_contextual_reminders(context: Dict[str, Any]) -> list:
+    """
+    Get list of reminders based on current context.
+
+    Args:
+        context: Dict with current state info:
+            - plan_mode: bool
+            - todo_count: int
+            - file_path: str (for security check)
+
+    Returns:
+        List of reminder keys that should be shown
+    """
+    reminders = []
+
+    if context.get("plan_mode"):
+        reminders.append("plan_mode_active")
+
+    if context.get("file_path") and should_show_security_reminder(context["file_path"]):
+        reminders.append("security")
+
+    return reminders

connectonion/cli/co_ai/sessions.py

@@ -0,0 +1,110 @@
+"""Session management with SQLite persistence."""
+
+import json
+import sqlite3
+from datetime import datetime
+from pathlib import Path
+from typing import Optional
+
+
+def get_db_path() -> Path:
+    db_dir = Path.home() / ".co-ai"
+    db_dir.mkdir(exist_ok=True)
+    return db_dir / "sessions.db"
+
+
+def init_db(conn: sqlite3.Connection) -> None:
+    conn.execute("""
+        CREATE TABLE IF NOT EXISTS sessions (
+            id TEXT PRIMARY KEY,
+            title TEXT,
+            model TEXT,
+            created_at TEXT,
+            updated_at TEXT,
+            messages TEXT
+        )
+    """)
+    conn.commit()
+
+
+def get_connection() -> sqlite3.Connection:
+    conn = sqlite3.connect(get_db_path())
+    conn.row_factory = sqlite3.Row
+    init_db(conn)
+    return conn
+
+
+class SessionManager:
+    def __init__(self):
+        self.conn = get_connection()
+        self.current_id: Optional[str] = None
+    
+    def create_session(self, model: str = "") -> str:
+        session_id = datetime.now().strftime("%Y%m%d_%H%M%S")
+        now = datetime.now().isoformat()
+        self.conn.execute(
+            "INSERT INTO sessions (id, title, model, created_at, updated_at, messages) VALUES (?, ?, ?, ?, ?, ?)",
+            (session_id, "New Session", model, now, now, "[]")
+        )
+        self.conn.commit()
+        self.current_id = session_id
+        return session_id
+    
+    def save_message(self, role: str, content: str) -> None:
+        if not self.current_id:
+            return
+        
+        row = self.conn.execute(
+            "SELECT messages FROM sessions WHERE id = ?", (self.current_id,)
+        ).fetchone()
+        
+        if row:
+            messages = json.loads(row["messages"])
+            messages.append({"role": role, "content": content, "timestamp": datetime.now().isoformat()})
+            
+            title = content[:50] + "..." if len(content) > 50 else content
+            if len(messages) == 1:
+                self.conn.execute(
+                    "UPDATE sessions SET messages = ?, title = ?, updated_at = ? WHERE id = ?",
+                    (json.dumps(messages), title, datetime.now().isoformat(), self.current_id)
+                )
+            else:
+                self.conn.execute(
+                    "UPDATE sessions SET messages = ?, updated_at = ? WHERE id = ?",
+                    (json.dumps(messages), datetime.now().isoformat(), self.current_id)
+                )
+            self.conn.commit()
+    
+    def list_sessions(self, limit: int = 20) -> list[dict]:
+        rows = self.conn.execute(
+            "SELECT id, title, model, created_at, updated_at FROM sessions ORDER BY updated_at DESC LIMIT ?",
+            (limit,)
+        ).fetchall()
+        return [dict(row) for row in rows]
+    
+    def load_session(self, session_id: str) -> Optional[list[dict]]:
+        row = self.conn.execute(
+            "SELECT messages FROM sessions WHERE id = ?", (session_id,)
+        ).fetchone()
+        
+        if row:
+            self.current_id = session_id
+            return json.loads(row["messages"])
+        return None
+    
+    def delete_session(self, session_id: str) -> bool:
+        self.conn.execute("DELETE FROM sessions WHERE id = ?", (session_id,))
+        self.conn.commit()
+        if self.current_id == session_id:
+            self.current_id = None
+        return True
+
+
+_manager: Optional[SessionManager] = None
+
+
+def get_session_manager() -> SessionManager:
+    global _manager
+    if _manager is None:
+        _manager = SessionManager()
+    return _manager

connectonion/cli/co_ai/skills/__init__.py

@@ -0,0 +1,37 @@
+"""Skills system for OO agent.
+
+Skills are markdown files that teach the agent how to do specific tasks.
+They are auto-discovered based on description matching.
+
+Directory structure:
+    .co/skills/
+    ├── commit/
+    │   └── SKILL.md
+    └── review-pr/
+        └── SKILL.md
+
+SKILL.md format:
+    ---
+    name: skill-name
+    description: When to use this skill (for auto-detection)
+    ---
+
+    # Instructions
+    ...
+"""
+
+from connectonion.cli.co_ai.skills.loader import (
+    load_skills,
+    get_skill,
+    get_skills_for_prompt,
+    SKILLS_REGISTRY,
+)
+from connectonion.cli.co_ai.skills.tool import skill
+
+__all__ = [
+    "load_skills",
+    "get_skill",
+    "get_skills_for_prompt",
+    "skill",
+    "SKILLS_REGISTRY",
+]

connectonion/cli/co_ai/skills/builtin/commit/SKILL.md

@@ -0,0 +1,63 @@
+---
+name: commit
+description: Create git commits with good messages. Use when user says "commit", "create commit", or asks to commit changes.
+---
+
+# Git Commit Skill
+
+Create a well-formatted git commit for staged changes.
+
+## Instructions
+
+1. **Gather information** (run in parallel):
+   - `git status` - See what's staged and unstaged
+   - `git diff --staged` - See exactly what will be committed
+   - `git log --oneline -5` - See recent commit message style
+
+2. **Analyze changes**:
+   - What was changed? (files, functions, features)
+   - Why was it changed? (bug fix, new feature, refactor)
+   - Follow the repository's commit message style
+
+3. **Draft commit message**:
+   - First line: concise summary under 50 chars
+   - Focus on "why" not "what"
+   - Match existing commit style
+
+4. **Execute commit**:
+   - Stage relevant files if needed: `git add <files>`
+   - Commit with HEREDOC format:
+     ```bash
+     git commit -m "$(cat <<'EOF'
+     Your commit message here
+     EOF
+     )"
+     ```
+   - Verify with `git status`
+
+## Safety Rules
+
+- Do NOT commit .env or credential files
+- Do NOT use `--amend` unless explicitly asked
+- Do NOT push unless explicitly asked
+- If commit fails, create NEW commit (don't amend)
+
+## Example
+
+```bash
+# Check status and diff
+git status
+git diff --staged
+
+# Commit
+git commit -m "$(cat <<'EOF'
+Fix authentication timeout issue
+
+Increased JWT expiry from 1h to 24h to prevent
+frequent re-authentication during long sessions.
+EOF
+)"
+
+# Verify
+git status
+```

connectonion/cli/co_ai/skills/builtin/review-pr/SKILL.md

@@ -0,0 +1,76 @@
+---
+name: review-pr
+description: Review GitHub pull requests. Use when user says "review PR", "review pull request", or "/review-pr".
+---
+
+# PR Review Skill
+
+Review a GitHub pull request for code quality, correctness, and best practices.
+
+## Instructions
+
+1. **Get PR information**:
+   - If no PR number given: `gh pr list` to show open PRs
+   - With PR number: `gh pr view <number>` for details
+   - Get diff: `gh pr diff <number>`
+
+2. **Analyze the changes**:
+   - What does this PR do?
+   - Does the code follow project conventions?
+   - Are there any bugs or issues?
+   - Is the code well-tested?
+   - Are there security concerns?
+
+3. **Provide structured review**:
+   - Overview of what the PR does
+   - Code quality analysis
+   - Specific suggestions with line references
+   - Potential issues or risks
+   - Whether to approve, request changes, or comment
+
+## Review Checklist
+
+- [ ] Code correctness
+- [ ] Following project conventions
+- [ ] Error handling
+- [ ] Performance implications
+- [ ] Test coverage
+- [ ] Security considerations
+- [ ] Documentation updates needed
+
+## Output Format
+
+```markdown
+## PR Review: #<number> - <title>
+
+### Summary
+<One paragraph about what this PR does>
+
+### What's Good
+- Point 1
+- Point 2
+
+### Suggestions
+1. **File:line** - Description of suggestion
+2. **File:line** - Description of suggestion
+
+### Concerns
+- Any potential issues
+
+### Recommendation
+- [ ] Approve
+- [ ] Request Changes
+- [ ] Comment only
+```
+
+## Example
+
+```bash
+# Get PR details
+gh pr view 123
+
+# Get the diff
+gh pr diff 123
+
+# Then analyze and provide review
+```

connectonion/cli/co_ai/skills/loader.py

@@ -0,0 +1,166 @@
+"""Skills loader - discovers and loads skills from .co/skills/ directory."""
+
+import re
+from pathlib import Path
+from typing import Dict, Optional, List
+from dataclasses import dataclass
+
+
+@dataclass
+class SkillInfo:
+    """Metadata about a skill."""
+    name: str
+    description: str
+    path: Path
+
+    def load_content(self) -> str:
+        """Load the full SKILL.md content."""
+        return self.path.read_text(encoding="utf-8")
+
+
+# Global registry of discovered skills
+SKILLS_REGISTRY: Dict[str, SkillInfo] = {}
+
+
+def parse_skill_frontmatter(content: str) -> Dict[str, str]:
+    """Parse YAML frontmatter from SKILL.md content."""
+    # Match --- ... --- at start of file
+    match = re.match(r'^---\s*\n(.*?)\n---\s*\n', content, re.DOTALL)
+    if not match:
+        return {}
+
+    frontmatter = {}
+    for line in match.group(1).split('\n'):
+        if ':' in line:
+            key, value = line.split(':', 1)
+            frontmatter[key.strip()] = value.strip()
+
+    return frontmatter
+
+
+def discover_skills(base_path: Optional[Path] = None) -> List[SkillInfo]:
+    """
+    Discover all skills in .co/skills/ directory.
+
+    Skills can be:
+    - .co/skills/skill-name/SKILL.md (directory with SKILL.md)
+    - .co/skills/skill-name.md (single file)
+    - ~/.co/skills/ (user-level skills)
+    - Built-in skills from co_ai/skills/builtin/
+
+    Returns:
+        List of SkillInfo objects
+    """
+    skills = []
+
+    # Search paths (in priority order)
+    search_paths = []
+
+    # Project-level skills (highest priority)
+    if base_path:
+        search_paths.append(base_path / ".co" / "skills")
+    else:
+        search_paths.append(Path.cwd() / ".co" / "skills")
+
+    # User-level skills
+    home_skills = Path.home() / ".co" / "skills"
+    if home_skills.exists():
+        search_paths.append(home_skills)
+
+    # Built-in skills (lowest priority)
+    builtin_skills = Path(__file__).parent / "builtin"
+    if builtin_skills.exists():
+        search_paths.append(builtin_skills)
+
+    for skills_dir in search_paths:
+        if not skills_dir.exists():
+            continue
+
+        # Find SKILL.md in subdirectories
+        for skill_dir in skills_dir.iterdir():
+            if skill_dir.is_dir():
+                skill_file = skill_dir / "SKILL.md"
+                if skill_file.exists():
+                    skill_info = _parse_skill_file(skill_file)
+                    if skill_info:
+                        skills.append(skill_info)
+
+            # Also support single .md files
+            elif skill_dir.suffix == ".md" and skill_dir.stem != "SKILL":
+                skill_info = _parse_skill_file(skill_dir)
+                if skill_info:
+                    skills.append(skill_info)
+
+    return skills
+
+
+def _parse_skill_file(path: Path) -> Optional[SkillInfo]:
+    """Parse a SKILL.md file and extract metadata."""
+    content = path.read_text(encoding="utf-8")
+    frontmatter = parse_skill_frontmatter(content)
+
+    name = frontmatter.get("name")
+    description = frontmatter.get("description")
+
+    # If no name, use directory/file name
+    if not name:
+        if path.name == "SKILL.md":
+            name = path.parent.name
+        else:
+            name = path.stem
+
+    # If no description, try to extract from first paragraph
+    if not description:
+        # Remove frontmatter and find first paragraph
+        content_without_frontmatter = re.sub(r'^---\s*\n.*?\n---\s*\n', '', content, flags=re.DOTALL)
+        lines = content_without_frontmatter.strip().split('\n')
+        for line in lines:
+            line = line.strip()
+            if line and not line.startswith('#'):
+                description = line[:200]  # First 200 chars
+                break
+
+    if not description:
+        description = f"Skill: {name}"
+
+    return SkillInfo(name=name, description=description, path=path)
+
+
+def load_skills(base_path: Optional[Path] = None) -> Dict[str, SkillInfo]:
+    """
+    Load all skills and populate the registry.
+
+    Returns:
+        Dictionary of skill name -> SkillInfo
+    """
+    skills = discover_skills(base_path)
+
+    # Mutate rather than reassign to keep references in sync
+    SKILLS_REGISTRY.clear()
+    SKILLS_REGISTRY.update({s.name: s for s in skills})
+
+    return SKILLS_REGISTRY
+
+
+def get_skill(name: str) -> Optional[SkillInfo]:
+    """Get a skill by name from the registry."""
+    return SKILLS_REGISTRY.get(name)
+
+
+def get_skills_for_prompt() -> str:
+    """
+    Format skills for inclusion in system prompt.
+
+    Returns XML-formatted available skills list.
+    """
+    if not SKILLS_REGISTRY:
+        return ""
+
+    lines = ["<available_skills>"]
+    for name, info in SKILLS_REGISTRY.items():
+        # Escape description for XML
+        desc = info.description.replace("&", "&amp;").replace("<", "&lt;").replace(">", "&gt;")
+        lines.append(f'  <skill name="{name}" description="{desc}"/>')
+    lines.append("</available_skills>")
+
+    return "\n".join(lines)