connectonion 0.6.2__py3-none-any.whl → 0.6.4__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/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)

connectonion/cli/co_ai/skills/tool.py

@@ -0,0 +1,46 @@
+"""Skill tool - allows agent to invoke skills."""
+
+from typing import Optional
+from connectonion.cli.co_ai.skills.loader import get_skill, load_skills, SKILLS_REGISTRY
+
+
+def skill(name: str, args: Optional[str] = None) -> str:
+    """
+    Invoke a skill by name.
+
+    Skills are specialized instruction sets that guide you through specific tasks.
+    When you recognize a task matches a skill's description, call this tool to
+    load the full instructions.
+
+    Args:
+        name: The skill name (e.g., "commit", "review-pr")
+        args: Optional arguments to pass to the skill
+
+    Returns:
+        The full skill instructions (SKILL.md content)
+
+    Example:
+        skill("commit")  # Load commit instructions
+        skill("review-pr", args="123")  # Load PR review with PR number
+    """
+    # Ensure skills are loaded
+    if not SKILLS_REGISTRY:
+        load_skills()
+
+    skill_info = get_skill(name)
+
+    if not skill_info:
+        available = list(SKILLS_REGISTRY.keys())
+        if available:
+            return f"Skill '{name}' not found. Available skills: {', '.join(available)}"
+        else:
+            return f"Skill '{name}' not found. No skills are currently loaded."
+
+    # Load the full skill content
+    content = skill_info.load_content()
+
+    # If args provided, append them
+    if args:
+        content += f"\n\n---\n## Arguments\n{args}"
+
+    return content

connectonion/cli/co_ai/tools/__init__.py

@@ -0,0 +1,92 @@
+"""
+Coding tools for the AI agent (Claude Code-style).
+
+File Tools:
+    - read_file: Read file with line numbers
+    - edit: Precise string replacement (str_replace)
+    - multi_edit: Multiple atomic string replacements
+    - write: Full file overwrite with approval
+    - Write: Class-based write with mode control
+
+Search Tools:
+    - glob: Find files by pattern
+    - grep: Search file contents
+
+Task Tools:
+    - task: Spawn sub-agent for complex tasks
+    - run_background: Run command in background
+    - task_output: Get background task output
+    - kill_task: Stop background task
+
+Planning Tools:
+    - enter_plan_mode: Switch to planning mode
+    - exit_plan_mode: Exit planning mode
+    - write_plan: Write plan content
+
+Interaction Tools:
+    - ask_user: Ask user a question via io
+    - load_guide: Load documentation/guide
+
+Utility Classes:
+    - DiffWriter: Low-level file writer with diff preview
+    - TodoList: Task list management
+
+Note: File tools are re-exported from connectonion.useful_tools for consistency.
+"""
+
+# File tools (Claude Code-style) - re-export from useful_tools
+from connectonion.useful_tools import (
+    read_file,
+    edit,
+    multi_edit,
+    glob,
+    grep,
+    write,
+    FileWriter,
+    DiffWriter,
+    MODE_NORMAL,
+    MODE_AUTO,
+    MODE_PLAN,
+    TodoList,
+)
+
+# Task tools (CLI-specific)
+from connectonion.cli.co_ai.tools.task import task
+from connectonion.cli.co_ai.tools.background import run_background, task_output, kill_task
+
+# Planning tools (CLI-specific)
+from connectonion.cli.co_ai.tools.plan_mode import enter_plan_mode, exit_plan_mode, write_plan
+
+# Interaction tools (CLI-specific)
+from connectonion.cli.co_ai.tools.ask_user import ask_user
+from connectonion.cli.co_ai.tools.load_guide import load_guide
+
+__all__ = [
+    # File tools (Claude Code-style)
+    "read_file",
+    "edit",
+    "multi_edit",
+    "write",
+    "FileWriter",
+    "DiffWriter",
+    "MODE_NORMAL",
+    "MODE_AUTO",
+    "MODE_PLAN",
+    # Search tools
+    "glob",
+    "grep",
+    # Task tools
+    "task",
+    "run_background",
+    "task_output",
+    "kill_task",
+    # Planning tools
+    "enter_plan_mode",
+    "exit_plan_mode",
+    "write_plan",
+    # Interaction tools
+    "ask_user",
+    "load_guide",
+    # Utility classes
+    "TodoList",
+]