connectonion 0.6.2__py3-none-any.whl → 0.6.4__py3-none-any.whl

connectonion/cli/co_ai/main.py

@@ -0,0 +1,52 @@
+"""AI coding agent web server entry point."""
+
+import logging
+from pathlib import Path
+from dotenv import load_dotenv
+from connectonion import host
+
+logging.basicConfig(
+    level=logging.WARNING,
+    format='[%(levelname)s] %(name)s: %(message)s'
+)
+
+
+# Load global keys.env for CLI commands (fallback for API keys)
+# Priority: current directory .env > global ~/.co/keys.env
+_global_keys = Path.home() / ".co" / "keys.env"
+if _global_keys.exists():
+    # load_dotenv doesn't override existing env vars, so cwd .env takes priority
+    load_dotenv(_global_keys)
+
+
+def start_server(
+    port: int = 8000,
+    model: str = "co/claude-opus-4-5",
+    max_iterations: int = 20,
+):
+    """Start AI coding agent web server.
+
+    Args:
+        port: Port to run server on
+        model: LLM model to use
+        max_iterations: Max tool iterations
+
+    The server will be accessible at:
+    - POST http://localhost:{port}/input
+    - WS ws://localhost:{port}/ws
+    - GET http://localhost:{port}/health
+    - GET http://localhost:{port}/info
+    """
+    from .agent import create_coding_agent
+
+    def agent_factory():
+        return create_coding_agent(
+            model=model,
+            max_iterations=max_iterations,
+            auto_approve=True,  # Always auto-approve in web mode
+            web_mode=True,
+        )
+
+    # Start server with open trust (no auth required)
+    # relay_url=None disables P2P discovery
+    host(agent_factory, port=port, trust="open", relay_url=None)

connectonion/cli/co_ai/plugins/__init__.py

@@ -0,0 +1,5 @@
+"""OO Agent plugins."""
+
+from .system_reminder import system_reminder
+
+__all__ = ['system_reminder']

connectonion/cli/co_ai/plugins/system_reminder.py

@@ -0,0 +1,154 @@
+"""
+System Reminder Plugin - Injects contextual guidance based on intent and tool usage.
+
+Two triggers:
+1. after_user_input: Detect intent (coding, agent creation) and inject relevant reminder
+2. after_each_tool: Inject reminder based on tool usage
+
+Usage:
+    from connectonion.cli.co_ai.plugins.system_reminder import system_reminder
+
+    agent = Agent("coder", plugins=[system_reminder])
+"""
+
+from pathlib import Path
+import fnmatch
+from typing import TYPE_CHECKING
+
+from connectonion.core.events import after_each_tool, after_user_input
+from connectonion.llm_do import llm_do
+
+if TYPE_CHECKING:
+    from connectonion.core.agent import Agent
+
+# Default reminders directory
+REMINDERS_DIR = Path(__file__).parent.parent / "prompts" / "system-reminders"
+
+# Intent detection prompt
+INTENT_PROMPT = """Analyze the user's request.
+
+User request: {user_prompt}
+
+Is this about building software, creating agents, writing code, or automation?
+Respond with ONE word only: "build" or "other"
+
+One word only:"""
+
+
+def _parse_frontmatter(text):
+    """Parse YAML frontmatter from markdown."""
+    if not text.startswith('---'):
+        return {}, text
+    parts = text.split('---', 2)
+    if len(parts) < 3:
+        return {}, text
+    import yaml
+    return yaml.safe_load(parts[1]) or {}, parts[2].strip()
+
+
+def _load_reminders(reminders_dir):
+    """Load all .md reminder files from directory."""
+    reminders_dir = Path(reminders_dir)
+    if not reminders_dir.exists():
+        return {}
+    reminders = {}
+    for f in reminders_dir.glob("*.md"):
+        meta, body = _parse_frontmatter(f.read_text())
+        if meta.get('name'):
+            reminders[meta['name']] = {
+                'content': body,
+                'triggers': meta.get('triggers', []),
+                'intent': meta.get('intent'),  # New: intent-based trigger
+            }
+    return reminders
+
+
+def _matches_pattern(pattern, value):
+    """Check if value matches glob pattern(s)."""
+    if not pattern or not value:
+        return False
+    patterns = [pattern] if isinstance(pattern, str) else pattern
+    return any(fnmatch.fnmatch(value, p) for p in patterns)
+
+
+def _find_tool_reminder(reminders, tool_name, args):
+    """Find matching reminder for tool usage."""
+    for reminder in reminders.values():
+        for trigger in reminder['triggers']:
+            if trigger.get('tool') and trigger['tool'] != tool_name:
+                continue
+            if trigger.get('path_pattern'):
+                path = args.get('path') or args.get('file_path', '')
+                if not _matches_pattern(trigger['path_pattern'], path):
+                    continue
+            if trigger.get('command_pattern'):
+                cmd = args.get('command') or args.get('cmd', '')
+                if not _matches_pattern(trigger['command_pattern'], cmd):
+                    continue
+            # All conditions matched
+            content = reminder['content']
+            path = args.get('path') or args.get('file_path', '')
+            return content.replace('${file_path}', path).replace('${tool_name}', tool_name)
+    return None
+
+
+def _find_intent_reminder(reminders, intent):
+    """Find matching reminder for detected intent."""
+    for reminder in reminders.values():
+        if reminder.get('intent') == intent:
+            return reminder['content']
+    return None
+
+
+# Load reminders once at import
+_REMINDERS = _load_reminders(REMINDERS_DIR)
+
+
+@after_user_input
+def detect_intent(agent: 'Agent') -> None:
+    """Detect user intent and inject relevant system reminder."""
+    user_prompt = agent.current_session.get('user_prompt', '')
+    if not user_prompt:
+        return
+
+    # Use llm_do to detect intent
+    intent = llm_do(
+        INTENT_PROMPT.format(user_prompt=user_prompt),
+        model="co/gemini-2.5-flash",
+        temperature=0,
+    ).strip().lower()
+
+    # Store intent in session
+    agent.current_session['intent'] = intent
+
+    # Find and inject intent-based reminder
+    content = _find_intent_reminder(_REMINDERS, intent)
+    if content:
+        agent.current_session['messages'].append({
+            'role': 'user',
+            'content': f"\n\n{content}"
+        })
+
+
+@after_each_tool
+def inject_tool_reminder(agent: 'Agent') -> None:
+    """Inject matching system reminder into tool result."""
+    trace = agent.current_session.get('trace', [])
+    messages = agent.current_session.get('messages', [])
+    if not trace or not messages:
+        return
+
+    last = trace[-1]
+    if last.get('type') != 'tool_result':
+        return
+
+    content = _find_tool_reminder(_REMINDERS, last.get('name', ''), last.get('args', {}))
+    if content:
+        for msg in reversed(messages):
+            if msg.get('role') == 'tool':
+                msg['content'] = msg.get('content', '') + '\n\n' + content
+                break
+
+
+# Export plugin
+system_reminder = [detect_intent, inject_tool_reminder]

connectonion/cli/co_ai/prompts/agents/explore.md

@@ -0,0 +1,79 @@
+# Explore Agent
+
+You are an explore agent specialized in quickly understanding codebases.
+
+## CRITICAL: READ-ONLY MODE
+
+<system-reminder>
+This is a READ-ONLY exploration agent. You are PROHIBITED from:
+- Creating, modifying, or deleting files
+- Moving, copying, or renaming files
+- Creating temporary files
+- Using redirect operators (>, >>)
+- Any operation that changes the filesystem
+
+You can ONLY use: glob, grep, read_file, and read-only bash commands (ls, git status, git log, git diff, find, cat, head, tail).
+
+This is a HARD CONSTRAINT, not a guideline.
+</system-reminder>
+
+## Your Mission
+
+Find files, search code, and answer questions about codebase structure. Be fast and thorough.
+
+## Tools (Read-Only)
+
+- `glob(pattern)` - Find files by pattern (e.g., `**/*.py`, `src/**/*.ts`)
+- `grep(pattern)` - Search file contents with regex
+- `read_file(path)` - Read file contents
+
+## Strategy
+
+1. **Start broad** - Use glob to find relevant files by pattern
+2. **Narrow down** - Use grep to find specific content
+3. **Read selectively** - Only read files that are directly relevant
+4. **Summarize** - Return structured, actionable findings
+
+## Output Format
+
+Return your findings in a clear structure:
+
+```
+## Files Found
+- path/to/file1.py - Brief description
+- path/to/file2.py - Brief description
+
+## Key Findings
+- Finding 1
+- Finding 2
+
+## Recommended Actions
+- Action 1
+- Action 2
+```
+
+## Guidelines
+
+- Be **fast** - Don't read every file, be selective
+- Be **thorough** - Cover multiple search patterns
+- Be **structured** - Return organized findings
+- Be **concise** - No unnecessary explanation
+- Be **read-only** - NEVER modify any files
+
+## Examples
+
+**Task**: "Find all API endpoints"
+```
+1. glob("**/api/**/*.py") or glob("**/routes/**/*.ts")
+2. grep("@app.route|@router|app.get|app.post")
+3. Read top matches
+4. Return list of endpoints with their handlers
+```
+
+**Task**: "How is authentication handled?"
+```
+1. grep("auth|login|session|jwt|token")
+2. glob("**/auth*/**")
+3. Read auth-related files
+4. Summarize the auth flow
+```

connectonion/cli/co_ai/prompts/agents/plan.md

@@ -0,0 +1,60 @@
+# Plan Agent
+
+You are a planning agent specialized in designing implementation strategies.
+
+## Your Mission
+
+Analyze requirements, explore the codebase, and create actionable implementation plans.
+
+## Tools
+
+- `glob(pattern)` - Find files by pattern
+- `grep(pattern)` - Search file contents
+- `read_file(path)` - Read file contents
+
+## Strategy
+
+1. **Understand the goal** - What exactly needs to be built/changed?
+2. **Explore existing code** - Find related files and patterns
+3. **Identify dependencies** - What will be affected?
+4. **Design the approach** - How should it be implemented?
+5. **Create steps** - Break into actionable tasks
+
+## Output Format
+
+```
+## Summary
+One-sentence description of what will be implemented.
+
+## Files to Modify
+- `path/to/file.py` - What changes are needed
+
+## Files to Create
+- `path/to/new_file.py` - Purpose of new file
+
+## Implementation Steps
+1. Step 1 - Details
+2. Step 2 - Details
+3. Step 3 - Details
+
+## Considerations
+- Risk or consideration 1
+- Risk or consideration 2
+```
+
+## Guidelines
+
+- Be **specific** - Name exact files and functions
+- Be **practical** - Steps should be immediately actionable
+- Be **complete** - Don't miss edge cases
+- Be **minimal** - Don't over-engineer, simplest solution that works
+
+## Examples
+
+**Task**: "Add user profile page"
+```
+1. Find existing page patterns: glob("**/pages/**/*.tsx")
+2. Find user-related code: grep("user|profile")
+3. Read similar pages for patterns
+4. Plan: Create ProfilePage, add route, connect to user API
+```

connectonion/cli/co_ai/prompts/assembler.py

@@ -0,0 +1,303 @@
+"""Prompt Assembler - Dynamic prompt composition with variable injection.
+
+Similar to Claude Code's approach:
+- Tool descriptions are injected based on available tools
+- Variables like ${TOOL_NAME} are interpolated at runtime
+- Conditional sections using ${condition ? "yes" : ""}
+- System reminders can be injected based on agent state
+
+Structure:
+    prompts/
+    ├── main.md           # Core agent behavior (with ${VARIABLES})
+    ├── tools/            # Tool-specific guidance
+    │   ├── shell.md
+    │   └── ...
+    ├── agents/           # Sub-agent prompts
+    │   └── explore.md
+    └── reminders/        # Runtime state reminders
+        └── plan_mode.md
+"""
+
+import re
+from pathlib import Path
+from typing import Any, Dict, List, Optional
+
+
+class PromptContext:
+    """Context object holding all variables for prompt interpolation."""
+    
+    def __init__(self):
+        self._vars: Dict[str, Any] = {}
+        self._tools: Dict[str, Any] = {}
+        self._tool_set: set = set()
+    
+    def set(self, key: str, value: Any):
+        """Set a variable value."""
+        self._vars[key] = value
+        return self
+    
+    def get(self, key: str, default: Any = None) -> Any:
+        """Get a variable value."""
+        return self._vars.get(key, default)
+    
+    def register_tool(self, tool: Any):
+        """Register a tool and extract its name."""
+        name = _get_tool_name(tool)
+        self._tools[name] = tool
+        self._tool_set.add(name)
+        return self
+    
+    def has_tool(self, name: str) -> bool:
+        """Check if a tool is available."""
+        return name in self._tool_set
+    
+    def get_tool_names(self):
+        """Get set of available tool names."""
+        return self._tool_set
+    
+    def to_dict(self):
+        """Export context as dict for interpolation."""
+        result = dict(self._vars)
+        result["AVAILABLE_TOOLS"] = self._tool_set
+        result["has_tool"] = self.has_tool
+        for name, tool in self._tools.items():
+            result[f"{name.upper()}_TOOL"] = tool
+        return result
+
+
+def interpolate(template: str, context: Dict[str, Any]) -> str:
+    """
+    Interpolate variables in template string.
+    
+    Supports:
+    - ${VAR_NAME} - simple variable substitution
+    - ${has_tool("name") ? "yes" : "no"} - conditional based on tool availability
+    - ${VAR_NAME or "default"} - default values
+    
+    Args:
+        template: String with ${...} placeholders
+        context: Dict of variable names to values
+        
+    Returns:
+        Interpolated string
+    """
+    def replace_var(match: re.Match) -> str:
+        expr = match.group(1).strip()
+        
+        # Handle ternary: condition ? "yes" : "no"
+        ternary_match = re.match(r'(.+?)\s*\?\s*"([^"]*)"\s*:\s*"([^"]*)"', expr)
+        if ternary_match:
+            condition_expr, true_val, false_val = ternary_match.groups()
+            condition_result = _eval_condition(condition_expr.strip(), context)
+            return true_val if condition_result else false_val
+        
+        # Handle: VAR_NAME or "default"
+        or_match = re.match(r'(\w+)\s+or\s+"([^"]*)"', expr)
+        if or_match:
+            var_name, default = or_match.groups()
+            value = context.get(var_name)
+            return str(value) if value else default
+        
+        # Simple variable lookup
+        if expr in context:
+            value = context[expr]
+            if callable(value) and not isinstance(value, type):
+                return str(value())
+            return str(value) if value is not None else ""
+        
+        # Keep original if not found (for debugging)
+        return match.group(0)
+    
+    # Match ${...} patterns, handling nested braces
+    pattern = r'\$\{([^}]+)\}'
+    return re.sub(pattern, replace_var, template)
+
+
+def _eval_condition(expr: str, context: Dict[str, Any]) -> bool:
+    """Evaluate a simple condition expression."""
+    # Handle: has_tool("name")
+    tool_check = re.match(r'has_tool\s*\(\s*"([^"]+)"\s*\)', expr)
+    if tool_check:
+        tool_name = tool_check.group(1)
+        has_tool_fn = context.get("has_tool")
+        if callable(has_tool_fn):
+            return bool(has_tool_fn(tool_name))
+        return tool_name in context.get("AVAILABLE_TOOLS", set())
+    
+    # Handle: VAR_NAME (truthy check)
+    if expr in context:
+        return bool(context[expr])
+    
+    # Handle: !VAR_NAME (falsy check)
+    if expr.startswith("!") and expr[1:] in context:
+        return not bool(context[expr[1:]])
+    
+    return False
+
+
+def _get_tool_name(tool: Any) -> str:
+    """Extract tool name from function or class instance."""
+    if callable(tool) and hasattr(tool, "__name__"):
+        return getattr(tool, "__name__")
+    if hasattr(tool, "name"):
+        return getattr(tool, "name")
+    return tool.__class__.__name__
+
+
+def assemble_prompt(
+    prompts_dir: str,
+    tools: Optional[List[Any]] = None,
+    context: Optional[PromptContext] = None,
+    extra_vars: Optional[Dict[str, Any]] = None,
+) -> str:
+    """
+    Assemble a system prompt from modular files with variable interpolation.
+
+    Args:
+        prompts_dir: Path to prompts directory
+        tools: List of tool objects/functions (loads matching .md files)
+        context: Optional PromptContext with pre-configured variables
+        extra_vars: Additional variables to inject
+
+    Returns:
+        Assembled and interpolated prompt string
+    """
+    prompts_path = Path(prompts_dir)
+    parts = []
+    
+    # Build context if not provided
+    if context is None:
+        context = PromptContext()
+    
+    # Register tools
+    if tools:
+        for tool in tools:
+            context.register_tool(tool)
+    
+    # Add extra variables
+    if extra_vars:
+        for key, value in extra_vars.items():
+            context.set(key, value)
+    
+    # Build interpolation dict
+    ctx_dict = context.to_dict()
+    
+    # Add tool name mappings for convenience
+    # e.g., SHELL_TOOL_NAME = "shell", READ_TOOL_NAME = "read_file"
+    for name in context.get_tool_names():
+        ctx_dict[f"{name.upper()}_TOOL_NAME"] = name
+    
+    # 1. Main prompt (required)
+    main_file = prompts_path / "main.md"
+    if main_file.exists():
+        content = main_file.read_text()
+        parts.append(interpolate(content, ctx_dict))
+
+    # 2. Workflow (agent creation workflow)
+    workflow_file = prompts_path / "workflow.md"
+    if workflow_file.exists():
+        content = workflow_file.read_text()
+        parts.append(interpolate(content, ctx_dict))
+
+    # 3. ConnectOnion framework prompt (index always included)
+    co_index = prompts_path / "connectonion" / "index.md"
+    if co_index.exists():
+        content = co_index.read_text()
+        parts.append(interpolate(content, ctx_dict))
+
+    # 4. ConnectOnion examples (all loaded for one-shot correct)
+    examples_dir = prompts_path / "connectonion" / "examples"
+    if examples_dir.exists():
+        for example_file in sorted(examples_dir.glob("*.md")):
+            content = example_file.read_text()
+            parts.append(interpolate(content, ctx_dict))
+
+    # 5. Tool descriptions (for each available tool)
+    tools_dir = prompts_path / "tools"
+    if tools_dir.exists() and tools:
+        for tool in tools:
+            tool_name = _get_tool_name(tool).lower()
+            tool_file = tools_dir / f"{tool_name}.md"
+            if tool_file.exists():
+                content = tool_file.read_text()
+                parts.append(interpolate(content, ctx_dict))
+    
+    return "\n\n---\n\n".join(parts)
+
+
+def load_reminder(
+    prompts_dir: str,
+    reminder_name: str,
+    context: Optional[PromptContext] = None,
+    extra_vars: Optional[Dict[str, Any]] = None,
+) -> Optional[str]:
+    """
+    Load a system reminder for runtime injection.
+    
+    Reminders are state-specific prompts injected during conversation,
+    wrapped in <system-reminder> tags.
+    
+    Args:
+        prompts_dir: Path to prompts directory
+        reminder_name: Name of the reminder (e.g., "plan_mode")
+        context: Optional PromptContext for variable interpolation
+        extra_vars: Additional variables to inject
+        
+    Returns:
+        Formatted reminder string with <system-reminder> tags, or None if not found
+    """
+    reminders_dir = Path(prompts_dir) / "reminders"
+    reminder_file = reminders_dir / f"{reminder_name}.md"
+    
+    if not reminder_file.exists():
+        return None
+    
+    content = reminder_file.read_text()
+    
+    # Build interpolation context
+    ctx_dict = {}
+    if context:
+        ctx_dict = context.to_dict()
+    if extra_vars:
+        ctx_dict.update(extra_vars)
+    
+    # Interpolate variables
+    interpolated = interpolate(content, ctx_dict)
+    
+    return f"<system-reminder>\n{interpolated}\n</system-reminder>"
+
+
+def load_agent_prompt(
+    prompts_dir: str,
+    agent_type: str,
+    context: Optional[PromptContext] = None,
+    extra_vars: Optional[Dict[str, Any]] = None,
+) -> Optional[str]:
+    """
+    Load a sub-agent system prompt.
+
+    Args:
+        prompts_dir: Path to prompts directory
+        agent_type: Type of agent (e.g., "explore", "plan")
+        context: Optional PromptContext for variable interpolation
+        extra_vars: Additional variables to inject
+
+    Returns:
+        Agent prompt string, or None if not found
+    """
+    agents_dir = Path(prompts_dir) / "agents"
+    agent_file = agents_dir / f"{agent_type}.md"
+
+    if not agent_file.exists():
+        return None
+
+    content = agent_file.read_text()
+
+    # Build interpolation context
+    ctx_dict = {}
+    if context:
+        ctx_dict = context.to_dict()
+    if extra_vars:
+        ctx_dict.update(extra_vars)
+
+    return interpolate(content, ctx_dict)

connectonion/cli/{docs/co-vibecoding-principles-docs-contexts-all-in-one.md → co_ai/prompts/connectonion/README.md}

@@ -1,5 +1,31 @@
 # ConnectOnion Framework - Complete Reference for AI Assistants
 
+## Documentation Directory Structure
+
+```
+.co/docs/
+├── README.md              # This file - complete reference for vibe coding
+├── quickstart.md          # 60-second getting started guide
+├── api.md                 # Full API reference
+├── connectonion.md        # Framework architecture deep dive
+├── examples.md            # Code examples and patterns
+├── principles.md          # Design philosophy
+├── cli/                   # CLI commands documentation
+├── concepts/              # Core concepts (agents, tools, trust)
+├── debug/                 # Debugging and @xray documentation
+├── design-decisions/      # Why things are built this way
+├── integrations/          # Third-party integrations
+├── network/               # Agent networking and communication
+├── templates/             # Project templates reference
+├── tui/                   # Terminal UI documentation
+├── useful_tools/          # Pre-built tools you can use
+└── useful_plugins/        # Claude Code plugins and extensions
+```
+
+**Start here:** `quickstart.md` for a 60-second intro, then use this README for comprehensive reference.
+
+---
+
 ## Context for AI Assistants
 
 You are helping a developer who wants to use ConnectOnion, a Python framework for creating AI agents with behavior tracking. This document contains everything you need to help them write effective ConnectOnion code.