agentao 0.2.5__tar.gz

agentao-0.2.5/.env.example

@@ -0,0 +1,22 @@
+# LLM Provider Configuration
+
+# Default LLM Provider (optional, defaults to OPENAI)
+# Determines which {PROVIDER}_API_KEY, {PROVIDER}_BASE_URL, {PROVIDER}_MODEL to use
+# Examples: OPENAI, DEEPSEEK, GEMINI, ANTHROPIC
+# LLM_PROVIDER=OPENAI
+
+# API Key (required)
+OPENAI_API_KEY=your-api-key-here
+
+# Base URL (optional, for OpenAI-compatible endpoints)
+# For OpenAI: leave empty or use https://api.openai.com/v1
+# For other providers: use their base URL
+# OPENAI_BASE_URL=https://api.openai.com/v1
+
+# Model (optional, defaults to gpt-4-turbo-preview)
+# For OpenAI: gpt-4-turbo-preview, gpt-4, gpt-3.5-turbo, etc.
+# For Claude via OpenAI-compatible endpoints: claude-3-opus-20240229, claude-3-sonnet-20240229, etc.
+# OPENAI_MODEL=gpt-4-turbo-preview
+
+# LLM Temperature (0.0-2.0, default: 0.2, lower = more deterministic)
+# LLM_TEMPERATURE=0.2

agentao-0.2.5/.github/workflows/ci.yml

@@ -0,0 +1,115 @@
+name: CI
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+    branches: [main]
+
+jobs:
+  # ─────────────────────────────────────────────────────────────
+  # Job 1 · Unit tests across Python 3.10 / 3.11 / 3.12
+  # ─────────────────────────────────────────────────────────────
+  test:
+    name: Test · Python ${{ matrix.python-version }}
+    runs-on: ubuntu-latest
+    strategy:
+      fail-fast: false
+      matrix:
+        python-version: ["3.10", "3.11", "3.12"]
+
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Install uv
+        uses: astral-sh/setup-uv@v5
+
+      - name: Install Python ${{ matrix.python-version }}
+        run: uv python install ${{ matrix.python-version }}
+
+      - name: Install dependencies
+        run: uv sync --python ${{ matrix.python-version }}
+
+      - name: Run tests
+        run: uv run --python ${{ matrix.python-version }} python -m pytest tests/ -v --tb=short
+
+  # ─────────────────────────────────────────────────────────────
+  # Job 2 · Build wheel + sdist, verify metadata with twine
+  # ─────────────────────────────────────────────────────────────
+  build:
+    name: Build distribution
+    runs-on: ubuntu-latest
+    needs: test
+
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Install uv
+        uses: astral-sh/setup-uv@v5
+
+      - name: Build wheel and sdist
+        run: uv build
+
+      - name: Check dist metadata with twine
+        run: uvx twine check dist/*
+
+      - name: Upload dist artifacts
+        uses: actions/upload-artifact@v4
+        with:
+          name: dist
+          path: dist/
+          retention-days: 7
+
+  # ─────────────────────────────────────────────────────────────
+  # Job 3 · Install from wheel, verify imports + CLI entry point
+  # ─────────────────────────────────────────────────────────────
+  smoke:
+    name: Smoke · Python ${{ matrix.python-version }}
+    runs-on: ubuntu-latest
+    needs: build
+    strategy:
+      fail-fast: false
+      matrix:
+        python-version: ["3.10", "3.11", "3.12"]
+
+    steps:
+      - name: Download dist artifacts
+        uses: actions/download-artifact@v4
+        with:
+          name: dist
+          path: dist/
+
+      - name: Set up Python ${{ matrix.python-version }}
+        uses: actions/setup-python@v5
+        with:
+          python-version: ${{ matrix.python-version }}
+
+      - name: Install wheel into a clean environment
+        run: pip install dist/*.whl
+
+      - name: Import check — package and public API
+        run: |
+          python -c "
+          import agentao
+          print('version:', agentao.__version__)
+          from agentao import Agentao, SkillManager
+          print('Public API OK')
+          "
+
+      - name: Import check — CLI entry point importable
+        run: python -c "from agentao.cli import entrypoint; print('CLI entrypoint OK')"
+
+      - name: Verify agentao command is on PATH
+        run: python -c "import shutil; assert shutil.which('agentao'), 'agentao not found on PATH'; print('agentao on PATH OK')"
+
+      - name: Verify bundled skills are discoverable after install
+        run: |
+          python -c "
+          from pathlib import Path
+          import agentao.skills.manager as m
+          bundled = m._BUNDLED_SKILLS_DIR
+          assert bundled.exists(), f'Bundled skills dir missing: {bundled}'
+          skills = [d.name for d in bundled.iterdir() if d.is_dir()]
+          assert 'skill-creator' in skills, f'skill-creator not found in {bundled}: {skills}'
+          print('Bundled skills OK:', skills)
+          "

agentao-0.2.5/.gitignore

@@ -0,0 +1,57 @@
+# Python-generated files
+__pycache__/
+*.py[cod]
+*$py.class
+*.so
+.Python
+build/
+develop-eggs/
+dist/
+downloads/
+eggs/
+.eggs/
+lib/
+lib64/
+parts/
+sdist/
+var/
+wheels/
+*.egg-info/
+.installed.cfg
+*.egg
+
+# Virtual environments
+venv/
+ENV/
+env/
+.venv
+
+# IDEs
+.vscode/
+.idea/
+*.swp
+*.swo
+*~
+
+# Environment variables
+.env
+
+# ChatAgent specific
+.chatagent_memory.json
+.agentao_memory.json
+chatagent.log
+*.log
+.chatagent/
+.agentao/
+examples/
+workspace/
+
+# OS
+.DS_Store
+Thumbs.db
+
+# Temporary development files
+scratch_*.py
+HIDDEN_*.md
+*_DRAFT.md
+*.tmp

agentao-0.2.5/.python-version

@@ -0,0 +1 @@
+3.12

agentao-0.2.5/CHANGELOG.md

@@ -0,0 +1,126 @@
+# Changelog
+
+All notable changes to Agentao are documented here.
+Format follows [Keep a Changelog](https://keepachangelog.com/en/1.1.0/).
+
+---
+
+## [0.2.3] — 2026-04-06
+
+### Added
+- **Plan mode v2** — tool-driven save/finalize workflow
+  - `plan_save(content)` tool: persists a draft and returns a `draft_id`
+  - `plan_finalize(draft_id)` tool: triggers the approval prompt; stale IDs are rejected
+  - Approval prompt shows the full plan before asking "Execute this plan? [y/N]"
+  - One-shot `consume_approval_request()` flag prevents repeated approval prompts
+  - Auto-save fallback skipped when a draft is already finalized
+- `agentao/plan/` sub-package: `session.py` (3-state FSM), `controller.py` (single exit path), `prompt.py` (mandatory turn protocol)
+- 44 new tests covering FSM transitions, lifecycle, tools, and prompt structure
+
+### Changed
+- Plan approval prompt now only appears after the model explicitly calls `plan_finalize`
+- `/plan save` removed as a CLI command; saving is now model-driven via the `plan_save` tool
+
+### Fixed
+- Finalized drafts can no longer be overwritten by the auto-save fallback path
+
+### Packaging
+- Added MIT `LICENSE` file (Bo Jin)
+- Heavy optional dependencies (`pymupdf`, `pdfplumber`, `pandas`, `openpyxl`, `Pillow`, `pycryptodome`, `google-genai`) moved to optional extras: `pdf`, `excel`, `image`, `crypto`, `google`; `full` installs everything
+- `skills/` and `workspace/` excluded from both wheel and sdist
+- `requires-python` lowered from `>=3.12` to `>=3.10`
+- Added `authors`, `license`, `keywords`, `classifiers`, `[project.urls]`
+- Version is now defined once in `agentao/__init__.py` and read dynamically by hatchling
+
+---
+
+## [0.2.1] — 2026-03-xx
+
+### Added
+- **Permission mode system** — three named presets: `read-only`, `workspace-write` (default), `full-access`
+- `/mode` command to switch and persist permission mode to `.agentao/settings.json`
+- Plan mode enforced via `PLAN` permission preset (no writes, no dangerous shell)
+- Mode restored exactly on `/plan implement` or `/plan clear`
+
+### Changed
+- Tool confirmation now driven by the active permission mode rather than per-tool flags
+- `/clear` resets permission escalation (`allow_all_tools`) back to False
+
+---
+
+## [0.2.0] — 2026-03-xx
+
+### Added
+- **Plan mode** — `/plan` enters a read-only research-and-draft workflow; agent proposes a structured Markdown plan before any mutations
+- **Display engine v2** — semantic tool headers (`→ read`, `← edit`, `$ shell`, `✱ search`), buffered output, tail-biased truncation, diff rendering, warning consolidation, live elapsed timer
+- **Background agent dashboard** — `/agents`, `/agent dashboard`, `/agent status`
+- **Transport protocol** — decoupled runtime from UI via `EventType` stream
+
+### Fixed
+- Streaming fallback, thinking handler scope, on_max_iterations guard
+- Buffer all shell output; robust `\r`/ANSI/CRLF handling
+
+---
+
+## [0.1.11] — 2026-02-xx
+
+### Added
+- **Three-tier context compression** — microcompaction (55% usage) + LLM summarization (65%) + circuit breaker after 3 failures
+- Structured 9-section LLM summary; partial compaction keeps last 20 messages verbatim
+- Three-tier overflow recovery on context-too-long API error
+- **Three-tier token counting** — real `prompt_tokens` from API → `count_tokens` API → local estimator (tiktoken / CJK heuristic)
+- `/context` command with token breakdown by component
+- Background agent push via `CancellationToken`
+
+---
+
+## [0.1.8] — 2026-01-xx
+
+### Added
+- **Sub-agent system** — foreground and background sub-agents with parent context injection and stats footer
+- `/agent bg <name> <task>` for background execution
+- Tool output file saving, head+tail truncation, per-line length limit
+- `/new` command; auto `max_completion_tokens`; session lifecycle hooks
+
+---
+
+## [0.1.5] — 2025-12-xx
+
+### Added
+- **Task checklist** (`todo_write`) — LLM-managed task list injected into system prompt; visible via `/todos`
+- **MCP (Model Context Protocol)** support — stdio and SSE transports; `mcp_*` tool registration
+- **Memory management** — persistent `.agentao_memory.json`; `save_memory`, `search_memory`, `delete_memory` tools; `/memory` commands
+- **Permission system** — per-tool confirmation with single-key menu; session escalation with **2** (Yes to all)
+- Cognitive Resonance — automatic memory recall with injection confirmation before each response
+- Session save/resume (`/sessions`)
+
+---
+
+## [0.1.1] — 2025-11-xx
+
+### Added
+- Renamed to **Agentao** (Agent + Tao)
+- Gemini provider support (`google-genai`)
+- `web_fetch` with automatic crawl4ai fallback for JS-heavy pages
+- `/confirm`, `/stream`, `/tools`, `/provider` commands
+- Sub-agent system (early version)
+- `ask_user` tool for LLM-initiated clarification
+- `-p` / `--print` flag for non-interactive print mode
+- Multi-line paste via `prompt_toolkit`; single-key confirmation via `readchar`
+
+### Changed
+- System prompt: reliability principles, structured reasoning (Action / Expectation / If wrong), operational guidelines
+- Context management: `ContextManager`, pinned messages, tool result truncation
+
+---
+
+## [0.1.0] — 2025-10-xx
+
+### Added
+- Initial release as **ChatAgent**
+- CLI chat loop with OpenAI-compatible API
+- Tool system: `read_file`, `write_file`, `replace`, `glob`, `grep`, `run_shell_command`, `web_fetch`, `google_web_search`, `save_memory`
+- Skills system — auto-discovery from `skills/` with YAML frontmatter
+- `AGENTAO.md` auto-loading for project-specific instructions
+- Current date injected as `<system-reminder>`
+- Complete LLM interaction logging to `agentao.log`

agentao-0.2.5/CLAUDE.md

@@ -0,0 +1,370 @@
+# CLAUDE.md
+
+This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
+
+## Package Management
+
+**Always use `uv` for package management**, not pip:
+
+```bash
+# Install dependencies
+uv sync
+
+# Add a new dependency
+uv add package-name
+
+# Run Python scripts
+uv run python script.py
+
+# Run the CLI
+uv run agentao
+# or
+uv run python main.py
+```
+
+## Running and Testing
+
+### Start the Agent
+
+```bash
+# Quick start
+./run.sh
+
+# Or directly
+uv run agentao
+
+# Or via Python
+uv run python main.py
+```
+
+### Run Tests
+
+```bash
+# Run all tests with pytest
+uv run python -m pytest tests/
+
+# Run a specific test file
+uv run python tests/test_imports.py
+uv run python tests/test_tool_confirmation.py
+uv run python tests/test_readchar_confirmation.py
+uv run python tests/test_date_in_prompt.py
+
+# All test files are in tests/ directory
+```
+
+### Configuration
+
+Copy and edit `.env` from `.env.example`:
+```bash
+cp .env.example .env
+# Edit .env with your API key and settings
+```
+
+Required: `OPENAI_API_KEY`
+Optional: `OPENAI_BASE_URL`, `OPENAI_MODEL`
+
+## Architecture
+
+### Three-Layer Design
+
+Agentao uses a **Tool-Agent-CLI** architecture:
+
+1. **CLI Layer** (`cli.py`): User interface with Rich, handles commands, manages session state (like `allow_all_tools`)
+2. **Agent Layer** (`agent.py`): Orchestrates LLM, tools, skills, and conversation history
+3. **Tool Layer** (`tools/`): Individual tool implementations following the Tool base class
+
+```
+User → CLI → Agent → LLM + Tools
+                  ↓
+            SkillManager (loads from skills/)
+```
+
+### Tool System
+
+All tools inherit from `Tool` base class (`tools/base.py`):
+
+```python
+class MyTool(Tool):
+    @property
+    def name(self) -> str:
+        return "my_tool"
+
+    @property
+    def description(self) -> str:
+        return "Description for LLM"
+
+    @property
+    def parameters(self) -> Dict[str, Any]:
+        return {...}  # JSON Schema
+
+    @property
+    def requires_confirmation(self) -> bool:
+        return False  # True for dangerous operations
+
+    def execute(self, **kwargs) -> str:
+        return "Result"
+```
+
+**Tool Registration**: Tools are registered in `agent.py::_register_tools()`. The `ToolRegistry` converts them to OpenAI function calling format.
+
+**Tool Confirmation**: Tools with `requires_confirmation=True` (Shell, Web, File Writing) pause execution and prompt user via `confirmation_callback` passed from CLI.
+
+**Tools requiring confirmation:**
+- `run_shell_command` - Shell command execution
+- `web_fetch` - Fetch web content
+- `google_web_search` - Web search
+- `write_file` - File writing/overwriting (prevents data loss)
+
+### Skills System
+
+**Dynamic Loading**: Skills are auto-discovered from `skills/` directory. Each subdirectory contains:
+- `SKILL.md` - Main file with YAML frontmatter (`name:`, `description:`)
+- `reference/*.md` (optional) - Additional documentation loaded on-demand
+
+**Skill Manager** (`skills/manager.py`):
+- Parses YAML frontmatter from SKILL.md files
+- Maintains `available_skills` dict (all skills)
+- Maintains `active_skills` dict (currently activated)
+- Injects active skill context into system prompt
+
+**Activation**: Use `activate_skill` tool or `/skills` command. Active skills add their documentation to the system prompt.
+
+### System Prompt Composition
+
+The system prompt is dynamically built in `agent.py::_build_system_prompt()`:
+
+1. **AGENTAO.md** (if exists in cwd) - Project-specific instructions
+2. **Agent Instructions** - Base Agentao capabilities
+3. **Current Date/Time** - Auto-injected: `YYYY-MM-DD HH:MM:SS (Day)`
+4. **Available Skills** - List with descriptions
+5. **Active Skills Context** - Full documentation of activated skills
+
+This composition happens on every `chat()` call to keep skills context fresh.
+
+### Conversation Flow
+
+```python
+# agent.py::chat()
+1. User message added to self.messages
+2. System prompt built (includes AGENTAO.md, date, skills)
+3. LLM called with messages + tools
+4. Loop (max 100 iterations):
+   a. If tool_calls: execute each tool
+      - Check requires_confirmation
+      - Call confirmation_callback if needed
+      - Execute tool or cancel based on response
+   b. Add tool results to messages
+   c. Call LLM again with updated messages
+   d. If no tool_calls: return final response
+```
+
+### Logging System
+
+**Complete LLM interaction logging** to `agentao.log`:
+- Every request/response (full content, no truncation)
+- All tool calls with formatted JSON arguments
+- Tool results
+- Token usage
+- Timestamps
+
+Logger is in `llm/client.py`. To debug tool execution or LLM behavior, check this log file.
+
+### CLI Commands
+
+User commands (start with `/`):
+- `/clear` - Clears history AND resets `allow_all_tools` to False
+- `/reset-confirm` - Resets `allow_all_tools` only (keeps history)
+- `/status` - Shows message count, model, active skills, confirmation mode
+- `/model [name]` - List models or switch to specified model
+- `/skills` - List available/active skills
+- `/memory` - Show saved memories
+- `/mcp` - List MCP servers and tools
+- `/help` - Show help
+
+Session state `allow_all_tools` persists across tool confirmations within one session.
+
+### MCP (Model Context Protocol) System
+
+Agentao supports connecting to external MCP servers that provide additional tools.
+
+**Configuration**: `.agentao/mcp.json` (project) and `~/.agentao/mcp.json` (global):
+```json
+{
+  "mcpServers": {
+    "server-name": {
+      "command": "npx",
+      "args": ["-y", "@modelcontextprotocol/server-filesystem", "/path"],
+      "env": { "TOKEN": "$MY_TOKEN" },
+      "trust": false
+    },
+    "remote-server": {
+      "url": "https://api.example.com/sse",
+      "headers": { "Authorization": "Bearer $API_KEY" },
+      "timeout": 30
+    }
+  }
+}
+```
+
+**Transport types**: `command` (stdio subprocess) or `url` (SSE).
+
+**Tool naming**: MCP tools are registered as `mcp_{server}_{tool}` (e.g. `mcp_github_create_issue`).
+
+**Architecture**:
+```
+.agentao/mcp.json → McpConfig → McpClientManager → McpClient (per server)
+                                                          ↓
+                                                   list_tools() / call_tool()
+                                                          ↓
+                                                   McpTool(Tool) → ToolRegistry
+```
+
+**Key files**:
+- `agentao/mcp/config.py` - Config loading, env var expansion
+- `agentao/mcp/client.py` - McpClient (single server), McpClientManager (multi-server)
+- `agentao/mcp/tool.py` - McpTool wrapper adapting MCP tools to Tool base class
+
+**Async bridge**: MCP SDK is async-only; McpClientManager uses a dedicated event loop with `run_until_complete()` to bridge into sync Agentao code.
+
+**CLI**: `/mcp list`, `/mcp add <name> <command|url>`, `/mcp remove <name>`
+
+## Adding New Components
+
+### Adding a Tool
+
+1. Create tool class in `agentao/tools/<module>.py`
+2. Implement `Tool` interface (name, description, parameters, execute)
+3. Set `requires_confirmation=True` if dangerous:
+   - Shell commands (arbitrary execution)
+   - Web access (network requests, privacy)
+   - File writing/overwriting (data loss risk)
+   - File deletion (irreversible)
+4. Register in `agent.py::_register_tools()`:
+   ```python
+   from .tools.mymodule import MyTool
+   # In _register_tools():
+   tools_to_register.append(MyTool())
+   ```
+
+### Adding a Skill
+
+1. Create directory: `skills/my-skill/`
+2. Create `SKILL.md` with YAML frontmatter:
+   ```yaml
+   ---
+   name: my-skill
+   description: Use when... (trigger conditions)
+   ---
+
+   # Skill Documentation
+   ...
+   ```
+3. (Optional) Add `reference/*.md` files for on-demand loading
+4. Restart agent - skill auto-discovered
+
+Reference files are loaded only when skill is activated (saves memory).
+
+## Important Patterns
+
+### Confirmation Callback Pattern
+
+CLI creates callback and passes to Agent:
+```python
+# cli.py
+def confirm_tool_execution(self, name, desc, args) -> bool:
+    # Show menu, get user choice
+    # Return True/False
+
+self.agent = Agentao(
+    confirmation_callback=self.confirm_tool_execution
+)
+```
+
+Agent checks before tool execution:
+```python
+# agent.py
+if tool.requires_confirmation and self.confirmation_callback:
+    confirmed = self.confirmation_callback(name, desc, args)
+    if not confirmed:
+        result = "Tool execution cancelled by user"
+```
+
+### Single-Key Input
+
+Uses `readchar` library for instant response:
+```python
+import readchar
+key = readchar.readkey()  # No Enter needed
+```
+
+Supports: `1`, `2`, `3`, `Esc`, `Ctrl+C`. Invalid keys are silently ignored.
+
+### Memory System
+
+Persistent JSON storage in `.agentao_memory.json` (gitignored):
+```python
+# tools/memory.py
+{"memories": [{"key": "...", "value": "...", "tags": [...], "timestamp": "..."}]}
+```
+
+**Available Tools:**
+- `save_memory` - Save/update memories
+- `search_memory` - Search by keyword
+- `delete_memory` - Delete specific memory
+- `clear_all_memories` - Clear all memories
+- `filter_memory_by_tag` - Filter by tag
+
+**CLI Commands:**
+- `/memory` or `/memory list` - List all memories
+- `/memory search <query>` - Search memories
+- `/memory tag <tag>` - Filter by tag
+- `/memory delete <key>` - Delete specific memory
+- `/memory clear` - Clear all (with confirmation)
+
+See `docs/features/memory-management.md` for detailed documentation.
+
+## File Organization
+
+```
+agentao/
+├── agentao/           # Main package
+│   ├── agent.py        # Core orchestration
+│   ├── cli.py          # CLI interface with Rich
+│   ├── llm/
+│   │   └── client.py   # OpenAI client wrapper
+│   ├── tools/          # Tool implementations
+│   │   ├── base.py     # Tool base class + registry
+│   │   ├── file_ops.py # Read, write, edit, list
+│   │   ├── search.py   # Glob, grep
+│   │   ├── shell.py    # Shell execution
+│   │   ├── web.py      # Fetch, search
+│   │   ├── memory.py   # Persistent memory
+│   │   ├── agents.py   # Helper agents
+│   │   └── skill.py    # Skill activation
+│   ├── mcp/            # MCP (Model Context Protocol) support
+│   │   ├── config.py   # Config loading + env var expansion
+│   │   ├── client.py   # McpClient + McpClientManager
+│   │   └── tool.py     # McpTool wrapper for Tool interface
+│   └── skills/
+│       └── manager.py  # Skill loading + management
+├── skills/             # Skill definitions (SKILL.md files)
+├── tests/              # Test files (test_*.py)
+├── docs/               # Documentation
+│   ├── features/       # Feature documentation
+│   ├── updates/        # Update logs
+│   ├── implementation/ # Technical implementation details
+│   └── dev-notes/      # Development notes (archived)
+├── CLAUDE.md           # Claude Code guidance
+├── AGENTAO.md        # Project-specific instructions
+└── main.py            # Entry point
+```
+
+## Key Dependencies
+
+- `openai` - LLM client (OpenAI-compatible APIs)
+- `rich` - CLI interface (markdown, panels, prompts)
+- `readchar` - Single-key input (no Enter needed)
+- `httpx` - HTTP client for web tools
+- `beautifulsoup4` - HTML parsing
+- `python-dotenv` - Environment configuration
+- `mcp` - Model Context Protocol client SDK