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

connectonion/docs/useful_plugins/system_reminder.md

@@ -0,0 +1,210 @@
+# System Reminder Plugin
+
+Inject contextual guidance into tool results to nudge agent behavior.
+
+## Quick Start
+
+```python
+from connectonion import Agent
+from connectonion.useful_plugins import system_reminder
+
+agent = Agent("assistant", tools=[...], plugins=[system_reminder])
+```
+
+## Concept
+
+System reminders are short messages appended to tool results that guide the agent's next action—without extra API calls or separate messages.
+
+**Example**: After writing a Python file, remind the agent to consider testing.
+
+```
+write_file("app.py", code)
+    ↓
+Result: "File written successfully"
+    ↓
+With system reminder: "File written successfully
+
+    <system-reminder>
+    Consider running tests to verify your changes work correctly.
+    This is a gentle reminder - ignore if not applicable.
+    </system-reminder>"
+```
+
+The LLM sees the system reminder as part of the tool output and naturally considers it.
+
+## How It Works
+
+```
+┌─────────────────────────────────────────────┐
+│          SYSTEM REMINDER FLOW                │
+├─────────────────────────────────────────────┤
+│                                             │
+│  1. Tool executes (e.g., write_file)        │
+│                 ↓                           │
+│  2. after_each_tool event fires             │
+│                 ↓                           │
+│  3. Plugin checks triggers:                 │
+│     - tool name matches?                    │
+│     - path pattern matches?                 │
+│                 ↓                           │
+│  4. If match: append system reminder        │
+│                 ↓                           │
+│  5. LLM sees result + system reminder       │
+│                                             │
+└─────────────────────────────────────────────┘
+```
+
+## Categories
+
+Based on Claude Code patterns, system reminders fall into five categories:
+
+| Category | Purpose | Example |
+|----------|---------|---------|
+| **Workflow Nudges** | Gentle best practice suggestions | "Consider running tests" |
+| **State Notifications** | Inform about state changes | "You exited plan mode" |
+| **External Events** | React to external changes | "File was modified by linter" |
+| **Next Steps** | Guide what to do next | "Verify your implementation" |
+| **Context Injection** | Provide relevant info | "This file contains secrets" |
+
+## File Format
+
+Each system reminder is a markdown file with YAML frontmatter:
+
+```markdown
+---
+name: test-reminder
+triggers:
+  - tool: write_file
+    path_pattern: "*.py"
+---
+
+<system-reminder>
+Consider running tests to verify your changes.
+This is a gentle reminder - ignore if not applicable.
+</system-reminder>
+```
+
+### Frontmatter Fields
+
+| Field | Required | Description |
+|-------|----------|-------------|
+| `name` | Yes | Unique identifier |
+| `triggers` | Yes | List of trigger conditions |
+| `triggers[].tool` | No | Tool name to match |
+| `triggers[].path_pattern` | No | Glob pattern(s) for file path arguments |
+| `triggers[].command_pattern` | No | Glob pattern(s) for command arguments |
+
+### Variables
+
+Use `${variable}` for dynamic content:
+
+| Variable | Description |
+|----------|-------------|
+| `${file_path}` | File path from tool arguments |
+| `${tool_name}` | Name of the tool that fired |
+
+## Design Principles
+
+**Gentle, Not Forceful**
+- ✓ "Consider running tests"
+- ✗ "You MUST run tests now"
+
+**Contextual, Not Spammy**
+- Fire only when relevant, not after every tool call
+
+**Simple Patterns**
+- Use glob: `*.py`, `["*.env", "*secret*"]`
+- Not regex: `.*\.py$`
+
+## Customizing
+
+Copy the plugin and built-in reminders to your project:
+
+```bash
+co copy system_reminder
+```
+
+Creates:
+```
+./plugins/system_reminder.py
+./prompts/system-reminders/
+├── test-reminder.md
+└── security-warning.md
+```
+
+Then import from your local copy:
+
+```python
+from plugins.system_reminder import system_reminder
+agent = Agent("assistant", plugins=[system_reminder])
+```
+
+Modify the reminder files in `./prompts/system-reminders/` to customize.
+
+---
+
+## Examples
+
+### Workflow Nudge: Test After Code Change
+
+```markdown
+---
+name: test-reminder
+triggers:
+  - tool: write_file
+    path_pattern: ["*.py", "*.js", "*.ts"]
+---
+
+<system-reminder>
+Code was modified. Consider:
+- Running relevant tests
+- Checking for linter errors
+This is a gentle reminder - ignore if not applicable.
+</system-reminder>
+```
+
+### State Notification: Plan Mode Exited
+
+```markdown
+---
+name: plan-mode-exited
+triggers:
+  - tool: exit_plan_mode
+---
+
+<system-reminder>
+You have exited plan mode. You can now make edits and run tools.
+</system-reminder>
+```
+
+### External Event: File Modified Externally
+
+```markdown
+---
+name: file-modified-externally
+triggers:
+  - tool: file_watcher
+---
+
+<system-reminder>
+${file_path} was modified externally (by user or linter).
+Don't revert these changes unless asked.
+</system-reminder>
+```
+
+### Context Injection: Security Warning
+
+```markdown
+---
+name: security-warning
+triggers:
+  - tool: read_file
+    path_pattern: ["*.env", "*secret*", "*.pem"]
+---
+
+<system-reminder>
+This file may contain sensitive information.
+- Never expose secrets in output
+- Never commit real credentials
+</system-reminder>
+```

connectonion/docs/useful_plugins/tool_approval.md

@@ -0,0 +1,139 @@
+# tool_approval
+
+Web-based approval for dangerous tools via WebSocket. Requires user confirmation before executing tools that can modify files or run commands.
+
+## Quick Start
+
+```python
+from connectonion import Agent, bash
+from connectonion.useful_plugins import tool_approval
+
+agent = Agent("assistant", tools=[bash], plugins=[tool_approval])
+agent.io = my_websocket_io  # Required for web mode
+
+agent.input("Install dependencies")
+# → Client receives: {"type": "approval_needed", "tool": "bash", "arguments": {"command": "npm install"}}
+# → Client responds: {"approved": true, "scope": "session"}
+# ✓ bash approved (session)
+```
+
+## How It Works
+
+1. Before each tool executes, check if it's dangerous
+2. If dangerous, send `approval_needed` event via WebSocket
+3. Wait for client response (blocks until received)
+4. If approved: execute tool, optionally remember for session
+5. If rejected: stop batch, return feedback to LLM
+
+## Tool Classification
+
+### Safe Tools (No Approval)
+
+Read-only operations that never modify state:
+
+```
+read, read_file, glob, grep, search
+list_files, get_file_info, task, load_guide
+enter_plan_mode, exit_plan_mode, write_plan
+task_output, ask_user
+```
+
+### Dangerous Tools (Require Approval)
+
+Operations that can modify files or have side effects:
+
+```
+bash, shell, run, run_in_dir
+write, edit, multi_edit
+run_background, kill_task
+send_email, post, delete, remove
+```
+
+## Client Protocol
+
+### Receive from server
+
+```json
+{
+  "type": "approval_needed",
+  "tool": "bash",
+  "arguments": {"command": "npm install"}
+}
+```
+
+### Send response
+
+```json
+// Approve for this session (no re-prompting)
+{"approved": true, "scope": "session"}
+
+// Approve once only
+{"approved": true, "scope": "once"}
+
+// Reject with feedback
+{"approved": false, "feedback": "Use yarn instead"}
+```
+
+## Approval Scopes
+
+| Scope | Behavior |
+|-------|----------|
+| `once` | Approve this call only |
+| `session` | Approve for rest of session (stored in memory) |
+
+## Rejection Behavior
+
+When user rejects a tool:
+
+1. Raises `ValueError` with feedback message
+2. Stops the entire tool batch (remaining tools skipped)
+3. LLM receives the error and can adjust approach
+
+```python
+# Example error message
+"User rejected tool 'bash'. Feedback: Use yarn instead"
+```
+
+## Terminal Logging
+
+The plugin logs all approval decisions:
+
+```
+✓ bash approved (session)    # Approved with session scope
+✓ edit approved (once)       # Approved for single use
+⏭ bash (session-approved)    # Skipped (already approved)
+✗ bash rejected: Use yarn    # Rejected with feedback
+✗ bash - connection closed   # WebSocket closed
+```
+
+## Events
+
+| Handler | Event | Purpose |
+|---------|-------|---------|
+| `check_approval` | `before_each_tool` | Check approval and prompt client |
+
+## Session Data
+
+```python
+# Approval state stored in session
+agent.current_session['approval'] = {
+    'approved_tools': {
+        'bash': 'session',   # Approved for session
+        'write': 'session'   # Approved for session
+    }
+}
+```
+
+## Non-Web Mode
+
+When `agent.io` is None (not web mode), all tools execute without approval. This is the default behavior for CLI usage.
+
+## Unknown Tools
+
+Tools not in SAFE_TOOLS or DANGEROUS_TOOLS are treated as safe and execute without approval.
+
+## See Also
+
+- [shell_approval](shell_approval.md) - Terminal-based approval for shell commands
+- [Events](../concepts/events.md) - Available event hooks
+- [Plugins](../concepts/plugins.md) - Plugin system overview

connectonion/docs/useful_prompts/README.md

@@ -0,0 +1,127 @@
+# Prompt Templates
+
+Pre-built prompt structures for common agent patterns. Copy to your project and customize.
+
+## Quick Reference
+
+| Template | Purpose | Use Case |
+|----------|---------|----------|
+| [coding_agent](coding_agent.md) | Coding Agent Prompt | CLI coding tools, code review bots |
+
+## Philosophy
+
+These are **examples to copy**, not framework code to import.
+
+1. Browse the templates
+2. Copy what fits your needs
+3. Modify freely - you own the code
+
+No lock-in. No rigid structure. Just good patterns.
+
+## Usage Pattern
+
+```bash
+# Copy template to your project
+cp -r $(python -c "from connectonion.useful_prompts import get_example_path; print(get_example_path('coding_agent'))") ./my_prompts
+
+# Or manually
+cp -r .../connectonion/useful_prompts/coding_agent/ ./my_prompts
+```
+
+```python
+# Use the assembler from your copied template
+from my_prompts.assembler import assemble_prompt
+from connectonion import Agent, Shell, DiffWriter
+
+tools = [Shell(), DiffWriter()]
+prompt = assemble_prompt(prompts_dir="my_prompts/prompts", tools=tools)
+
+agent = Agent("my-agent", system_prompt=prompt, tools=tools)
+```
+
+## Why Modular Prompts?
+
+Learned from Claude Code's architecture:
+
+| Benefit | Description |
+|---------|-------------|
+| **Per-tool guidance** | Each tool gets dedicated "when to use" / "when NOT to use" |
+| **Easy customization** | Modify one file without touching others |
+| **Conditional assembly** | Only include prompts for tools you actually use |
+| **Project context** | Add project-specific instructions separately |
+
+## Template Structure
+
+Each template follows this pattern:
+
+```
+template_name/
+├── prompts/
+│   ├── main.md           # Core agent behavior
+│   └── tools/            # Per-tool guidance
+│       ├── tool_a.md
+│       └── tool_b.md
+├── assembler.py          # Prompt assembly utility
+└── README.md             # Template documentation
+```
+
+## Customizing Templates
+
+### Modify agent behavior
+Edit `prompts/main.md`:
+- Agent personality and tone
+- Workflow steps
+- General guidelines
+
+### Add tool guidance
+Create `prompts/tools/my_tool.md`:
+```markdown
+# Tool: My Tool
+
+## When to Use
+- Situation A
+- Situation B
+
+## When NOT to Use
+- Situation C
+
+## Examples
+<good-example>
+...
+</good-example>
+
+<bad-example>
+...
+</bad-example>
+```
+
+### Add project context
+Create `.co/AGENT.md` in your project:
+```markdown
+# Project: My App
+
+## Tech Stack
+- Python 3.11, FastAPI
+
+## Conventions
+- Use snake_case
+- Type hints required
+```
+
+Pass it to the assembler:
+```python
+prompt = assemble_prompt(
+    prompts_dir="my_prompts/prompts",
+    tools=tools,
+    context_file=".co/AGENT.md"
+)
+```
+
+## Comparison: Single File vs Modular
+
+| Approach | Pros | Cons |
+|----------|------|------|
+| **Single file** | Simple, one place | Hard to maintain, can't customize per-tool |
+| **Modular** | Easy to update, per-tool control | More files to manage |
+
+**Recommendation:** Start with single file for simple agents. Switch to modular when you need per-tool customization or have 3+ tools.

connectonion/docs/useful_prompts/coding_agent.md

@@ -0,0 +1,214 @@
+# Coding Agent Prompt
+
+A modular prompt template for building coding assistants. This is a **prompt**, not code - you copy it, customize it, and use it as your agent's system prompt.
+
+## Overview
+
+This template provides:
+- **Main prompt** - Core agent behavior, tone, workflow
+- **Per-tool prompts** - Guidance for shell, file read/write, todo list
+- **Assembler** - Simple utility to combine prompts
+
+## Structure
+
+```
+coding_agent/
+├── prompts/
+│   ├── main.md           # Core agent behavior
+│   └── tools/            # Per-tool guidance
+│       ├── shell.md      # Shell/bash usage
+│       ├── read.md       # File reading
+│       ├── write.md      # File writing
+│       └── todo.md       # Task tracking
+├── assembler.py          # Prompt assembly (~50 lines)
+└── README.md
+```
+
+## Quick Start
+
+### 1. Copy to your project
+
+```bash
+# Using co copy (recommended)
+co copy coding_agent
+
+# Or manually
+cp -r $(python -c "from connectonion.useful_prompts import get_example_path; print(get_example_path('coding_agent'))") ./prompts
+```
+
+### 2. Use in your agent
+
+```python
+from prompts.assembler import assemble_prompt
+from connectonion import Agent
+from connectonion.useful_tools import Shell, DiffWriter, TodoList
+
+def read_file(path: str) -> str:
+    """Read file contents."""
+    return open(path).read()
+
+# Define tools
+tools = [Shell(), read_file, DiffWriter(), TodoList()]
+
+# Assemble prompt (only includes docs for tools you have)
+prompt = assemble_prompt(
+    prompts_dir="prompts/prompts",
+    tools=tools
+)
+
+# Create agent
+agent = Agent("coder", system_prompt=prompt, tools=tools)
+agent.run()
+```
+
+## Prompt Files
+
+### main.md
+
+Core agent behavior:
+- Tone and style (concise, no preamble)
+- Task workflow (understand → search → implement → verify)
+- Coding guidelines (read first, mimic style, minimal changes)
+- Persistence (don't give up easily)
+- Security rules (no secrets, no force push)
+
+### tools/shell.md
+
+When to use shell:
+- Git operations
+- Package management
+- Running tests
+- Build commands
+
+When NOT to use:
+- Reading files (use read_file)
+- Writing files (use write)
+
+### tools/read.md
+
+File reading best practices:
+- Always read before modifying
+- Check dependencies
+- Understand context
+
+### tools/write.md
+
+File writing guidelines:
+- Read first, then write
+- Match existing style
+- Minimal changes
+
+### tools/todo.md
+
+Task tracking guidance:
+- When to use (3+ steps)
+- When not to use (trivial tasks)
+- Task states and flow
+
+## Customization
+
+### Change agent personality
+
+Edit `prompts/main.md`:
+
+```markdown
+# My Custom Agent
+
+You are a friendly coding assistant that loves emojis! 🚀
+
+## Tone
+- Be enthusiastic and encouraging
+- Use emojis liberally
+- Celebrate small wins
+```
+
+### Add custom tool guidance
+
+Create `prompts/tools/my_api.md`:
+
+```markdown
+# Tool: My API
+
+## When to Use
+- Fetching user data
+- Updating records
+
+## When NOT to Use
+- Bulk operations (use batch API)
+
+## Rate Limits
+- Max 100 requests/minute
+- Use caching when possible
+```
+
+### Add project context
+
+Create `.co/AGENT.md`:
+
+```markdown
+# Project: E-commerce API
+
+## Stack
+- Python 3.11, FastAPI, PostgreSQL
+
+## Conventions
+- snake_case for functions
+- Type hints required
+- Tests in tests/ directory
+```
+
+Use in assembler:
+
+```python
+prompt = assemble_prompt(
+    prompts_dir="prompts/prompts",
+    tools=tools,
+    context_file=".co/AGENT.md"
+)
+```
+
+## The Assembler
+
+The assembler is intentionally simple (~50 lines):
+
+```python
+def assemble_prompt(prompts_dir, tools, context_file=None):
+    parts = []
+
+    # 1. Main prompt
+    parts.append(read("prompts/main.md"))
+
+    # 2. Tool descriptions (for each tool)
+    for tool in tools:
+        tool_file = f"prompts/tools/{tool.name}.md"
+        if exists(tool_file):
+            parts.append(read(tool_file))
+
+    # 3. Project context (optional)
+    if context_file:
+        parts.append(read(context_file))
+
+    return "\n\n---\n\n".join(parts)
+```
+
+You own this code. Modify it for your needs:
+- Add variable interpolation
+- Add conditional sections
+- Add version tracking
+- Whatever you need
+
+## Best Practices
+
+### From Claude Code
+
+1. **"When NOT to use"** sections are as important as "when to use"
+2. **Examples with reasoning** - show good AND bad patterns
+3. **Keep tool docs focused** - one tool per file
+4. **Project context separate** - easy to update per-project
+
+### Keep It Simple
+
+- Start with the template as-is
+- Only add complexity when needed
+- Delete files you don't use
+- The goal is clarity, not completeness